diff --git a/AGENTS.md b/AGENTS.md
index 2804b62..5c0c2fc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,236 +1,150 @@
-One AGENTS.md works across many agents, such as GitHub Copilot, Roo Code, Open AI's Codex, Devin, and more. This is a README for agents to help AI coding agents work on this project.
+# YouVersion Platform SDKs – Agent Guide
+
+## QUICK FACTS
+- Monorepo: pnpm workspaces + Turborepo
+- Packages:
+  - `@youversion/platform-core` (pure TS API clients)
+  - `@youversion/platform-react-hooks` (React hooks layer)
+  - `@youversion/platform-react-ui` (UI components)
+- Language: TypeScript
+- Test runner: Vitest
+- Node: >= 20.0.0
+- Package manager: pnpm >= 9.0.0 (no npm/yarn)
+
+## WHERE TO MAKE CHANGES
+
+- **New or changed API endpoints / data types**
+  → Add/update Zod schemas and clients in `packages/core`
+- **New React data hooks / provider behavior**
+  → Implement in `packages/hooks` using `@youversion/platform-core` clients
+- **New visual components / styling / UX**
+  → Implement in `packages/ui` using hooks from `@youversion/platform-react-hooks`
+
+**Rule of thumb:**
+- Core = network + types (no React)
+- Hooks = React logic/state around core
+- UI = components and styling around hooks
+
+## DEPENDENCY GRAPH
 
-## Project Overview
+```
+@youversion/platform-core  →  @youversion/platform-react-hooks  →  @youversion/platform-react-ui
+      (pure TS)                      (React hooks)                      (React components)
+```
+
+- Do not introduce reverse dependencies
+- Do not import UI or hooks from core
+- Do not import UI from hooks
 
-This is a monorepo for YouVersion Platform SDKs for React Web. The project uses pnpm workspaces, TypeScript, and Turbo for build orchestration.
+## STRUCTURE
+```
+packages/
+  core/        @youversion/platform-core (API clients, utilities)
+  hooks/       @youversion/platform-react-hooks (React hooks)
+  ui/          @youversion/platform-react-ui (UI components)
+tools/         Shared configs (TS, ESLint)
+```
 
-## Development Commands
+## COMMANDS
 
-### Essential Commands
 ```bash
-# Install dependencies (requires pnpm >= 9.0.0)
-pnpm install
+# Setup
+pnpm install              # Requires pnpm >= 9.0.0, Node >= 20.0.0
+
+# Build
+pnpm build               # Turbo builds all in dependency order
+pnpm build:core          # Build core only
+pnpm build:hooks         # Build hooks only
+pnpm build:react         # Build UI only
+
+# Development
+pnpm dev:web             # Start UI dev server with hot reload
+pnpm test                # Run tests sequentially across all packages
+pnpm test:watch          # Watch mode for all packages
+pnpm test:coverage       # Coverage reports for all packages
+
+# Quality
+pnpm lint                # ESLint all packages
+pnpm typecheck           # Type check all packages
+pnpm format              # Format all code
+
+# Release
+pnpm changeset           # Create changeset entry
+pnpm version-packages    # Apply changesets to versions
+pnpm release             # Build + publish all packages
+```
 
-# Build all packages in correct order
-pnpm build
+## PER-PACKAGE COMMANDS
 
-# Run tests across all packages (sequential execution for clear output)
-pnpm test
+```bash
+# Core
+pnpm --filter @youversion/platform-core test
+pnpm --filter @youversion/platform-core build
 
-# Type checking
-pnpm typecheck
+# Hooks
+pnpm --filter @youversion/platform-react-hooks test
+pnpm --filter @youversion/platform-react-hooks build
 
-# Linting
-pnpm lint
+# UI
+pnpm --filter @youversion/platform-react-ui test
+pnpm --filter @youversion/platform-react-ui build
+```
 
-# Format code
-pnpm format
+## KEY PATTERNS
 
-# Start development environment
-pnpm dev:web            # For React SDK development
-```
+**Unified versioning**: All 3 packages share exact same version, always released together
 
-### Package-Specific Commands
-```bash
-# Build specific packages
-pnpm build:core    # Build core
-pnpm build:react   # Build React SDK
+**Build order enforced by Turbo**: core → hooks → ui (dependency chain)
 
-# Run tests in watch mode
-pnpm test:watch
+**React 19.1.2 exact pinning**: pnpm overrides lock all React packages to exact version
 
-# Run individual package tests with coverage
-pnpm --filter @youversion/platform-core test:coverage
-pnpm --filter @youversion/platform-react-hooks test:coverage
+**Tailwind CSS injection**: Auto-injected as JS constant via tsup define (no build step needed by consumers)
 
-# Build and verify outputs
-pnpm build
-```
+**Changeset workflow**: pnpm changeset → pnpm version-packages → pnpm release
 
-### Release Process
-```bash
-# Create a changeset for version updates
-pnpm changeset
+**Trusted publishing**: OIDC-based npm publishing (no tokens)
 
-# Version packages based on changesets
-pnpm version-packages
+**Pre-commit**: Husky + lint-staged runs ESLint + Prettier on staged files
 
-# Build and publish packages
-pnpm release
-```
+## CRITICAL GOTCHAS
 
-## Architecture
+### Build & Dependencies
+- Always rebuild dependent packages after modifying core or hooks
+- Turbo build cache can skip changes - run `turbo build --force` if needed
+- Workspace protocol: use `workspace:*` in package.json dependencies
 
-### Monorepo Structure
-```
-├── packages/
-│   ├── core/       # @youversion/platform-core - Published core package
-│   ├── hooks/      # @youversion/platform-react-hooks - Published React hooks
-│   └── ui/         # @youversion/platform-react-ui - Published React SDK
-├── tools/                 # Shared configs (TypeScript, ESLint, Jest)
-└── scripts/              # Build and development scripts
-```
+### Versioning & Release
+- Changesets required for ALL version bumps (even patches)
+- **Unified versioning**: All packages must share exact same version - never version packages independently
+- Pre-commit hooks fail if typecheck or lint fails
+
+### Environment
+- **Node.js requirement**: Minimum version 20.0.0 required
+- **React version**: Do not change React dependencies; pnpm overrides enforce 19.1.2
+- **Package manager**: Do not use npm/yarn; only pnpm supported
+
+### Package Boundaries (FOR AGENTS)
+- **Core must remain React-free** – do not import React or DOM APIs in `packages/core`
+- **Hooks should not duplicate core logic** – call core clients instead of re-implementing HTTP
+- **UI should not talk to the network directly** – always use hooks/core
+
+### Testing
+- One change in a package could break something in another package, so we want to make sure that all tests are passing across the packages before code gets pushed
+
+### When Stuck
+- Ask clarifying questions
+
+## ANTI-PATTERNS
+
+❌ Don't assume shared source directory (each package self-contained)
+❌ Don't use API Extractor (listed but not actually used)
+❌ Don't expect consistent build tools (core: tsup, hooks: tsc only, ui: tsup + tsc)
+❌ Don't modify React version (exact 19.1.2 enforced via pnpm overrides)
+❌ Don't use npm/yarn (only pnpm >= 9.0.0 supported)
+❌ Don't break unified versioning (all packages versioned together)
+
+## MORE DETAIL PER PACKAGE
 
-### Key Architectural Patterns
-
-1. **Package Dependencies**:
-   - `core` is the foundation (API clients, utilities)
-   - `hooks` depends on `core`
-   - `ui` depends on both `hooks` and `core`
-
-2. **Build Order**: Dependencies must be built in order:
-   - First: `core`
-   - Second: `hooks`
-   - Finally: `ui`
-
-3. **Unified Versioning**: All published packages share the same version number and are released together
-
-4. **UI Components**: All UI components use React.forwardRef and accept standard HTML attributes
-
-5. **TypeScript Configuration**: Shared configs in `tools/tsconfig/`
-
-6. **Testing**:
-   - All packages use Vitest
-   - Test files follow `*.test.ts(x)` pattern
-
-### Build System
-
-- **Turbo**: Orchestrates builds with caching and dependency management
-- **tsup**: Bundles TypeScript for packages
-- **API Extractor**: Generates single .d.ts file for published packages
-- **Changesets**: Manages versioning and changelogs
-
-### Code Quality
-
-- **Pre-commit hooks**: Husky runs lint-staged on git commits
-- **Lint-staged**: Runs ESLint and Prettier on staged files
-- **TypeScript**: Strict mode enabled, no implicit any
-- **ESLint**: Shared config from `tools/eslint-config/`
-
-### Publishing
-
-- Published packages:
-  - `@youversion/platform-core`
-  - `@youversion/platform-react-hooks`
-  - `@youversion/platform-react-ui`
-- All packages use unified versioning (same version number)
-- NPM registry: https://registry.npmjs.org/
-- Access: public
-
-## Review Guidelines
-
-When conducting code reviews, AI agents should systematically evaluate the following aspects:
-
-### Code Standards and Conventions
-- Do the changes follow the established conventions and patterns used throughout the codebase?
-- Is the code style consistent with existing code (indentation, naming conventions, file organization)?
-- Are the appropriate design patterns being used where applicable?
-- Does the code follow the monorepo structure and package boundaries?
-- Are TypeScript types properly defined and avoiding `any` types?
-- Do components follow the React.forwardRef pattern for UI components?
-
-### Security Assessment
-- Do the changes introduce any security vulnerabilities or risks?
-- Are user inputs properly validated and sanitized?
-- Is sensitive data properly handled and protected?
-- Are authentication and authorization checks properly implemented?
-- Are there any exposed API keys, credentials, or sensitive configuration data?
-- Are network requests using appropriate security protocols (HTTPS, proper headers)?
-- Is XSS protection properly implemented (no dangerouslySetInnerHTML without sanitization)?
-- Are Content Security Policy considerations met?
-
-### Performance Considerations
-- Do the changes introduce potential performance bottlenecks?
-- Are there any inefficient algorithms or data structures being used?
-- Is there unnecessary re-rendering or state updates in React components?
-- Are React hooks (useMemo, useCallback, memo) used appropriately to prevent unnecessary renders?
-- Are large lists properly virtualized where appropriate?
-- Is lazy loading implemented for heavy resources and code splitting used effectively?
-- Are bundle sizes kept reasonable (check with build output)?
-- Is tree-shaking working properly for unused exports?
-- Are web vitals (LCP, FID, CLS) maintained or improved?
-
-### React/TypeScript Best Practices
-- Are components properly optimized using React.memo, useMemo, and useCallback where appropriate?
-- Is component composition preferred over prop drilling?
-- Are custom hooks following the Rules of Hooks?
-- Is proper error boundary implementation in place?
-- Are TypeScript generics used effectively for reusable components?
-- Is strict mode TypeScript being followed (no implicit any, proper null checking)?
-- Are discriminated unions used for complex state management?
-- Are React 18+ features (Suspense, concurrent features) used appropriately?
-
-### Package Architecture
-- Does the code respect package boundaries (core → hooks → ui dependency order)?
-- Are internal APIs properly exported through package index files?
-- Is the unified versioning strategy maintained?
-- Are workspace dependencies correctly referenced?
-- Does the code follow the established build order requirements?
-
-### Functional Verification
-- Does the code actually implement what the PR description claims?
-- Are all acceptance criteria from the related issue/ticket met?
-- Are edge cases properly handled?
-- Is error handling comprehensive and user-friendly?
-- Are all promised features fully implemented and working?
-- Do changes work across all supported browsers?
-
-### Testing and Documentation
-- Are appropriate tests included for new functionality (using Vitest)?
-- Do tests follow the *.test.ts(x) naming pattern?
-- Do existing tests still pass?
-- Is the code self-documenting with clear variable and function names?
-- Are complex logic sections properly commented?
-- Are API changes documented with proper TypeScript JSDoc?
-- Are breaking changes clearly identified in changesets?
-- Is test coverage maintained or improved?
-
-### Dependencies and Compatibility
-- Are new dependencies necessary and well-maintained?
-- Do new dependencies have appropriate TypeScript types?
-- Are version requirements appropriate and following semver?
-- Is backward compatibility maintained where expected?
-- Are deprecated APIs avoided?
-- Are peer dependencies properly defined for the published packages?
-- Is the minimum Node.js version (>= 20.0.0) respected?
-
-### Build System and Tooling
-- Do changes work with the Turbo build cache?
-- Are tsup configurations properly maintained?
-- Does API Extractor successfully generate type definitions?
-- Do lint and format commands pass successfully?
-- Are pre-commit hooks passing?
-- Are changeset entries created for user-facing changes?
-
-### Accessibility
-- Are ARIA attributes properly implemented?
-- Is keyboard navigation fully supported?
-- Are focus states clearly visible?
-- Do interactive elements have appropriate roles?
-- Are form inputs properly labeled?
-- Is color contrast WCAG compliant?
-- Are screen reader announcements appropriate?
-
-### User Experience
-- Do the changes provide a smooth and intuitive user experience?
-- Are loading states and error states properly handled?
-- Is feedback provided for user actions?
-- Are animations performant and purposeful (respecting prefers-reduced-motion)?
-- Is responsive design maintained across viewport sizes?
-- Are browser-specific quirks handled appropriately?
-
-### Developer Experience
-- Is the API intuitive and consistent with existing patterns?
-- Are TypeScript types providing good IDE support and autocomplete?
-- Are error messages helpful and actionable?
-- Is the component API well-designed and flexible?
-- Are props properly documented with JSDoc comments?
-- Are examples provided for complex usage patterns?
-
-## Important Notes
-
-1. Always run `pnpm install` after pulling changes
-2. Use `pnpm` (not npm or yarn) for all operations
-3. Node.js >= 20.0.0 required
-4. When modifying packages, rebuild dependent packages in order (core → hooks → ui)
-5. All packages use unified versioning - they're always released together at the same version
+- `packages/core/AGENTS.md` – API clients, schemas, auth
+- `packages/hooks/AGENTS.md` – React hooks, providers
+- `packages/ui/AGENTS.md` – UI components, styling, build order
diff --git a/docs/review-guidelines.md b/docs/review-guidelines.md
new file mode 100644
index 0000000..dc84df7
--- /dev/null
+++ b/docs/review-guidelines.md
@@ -0,0 +1,108 @@
+## Review Guidelines
+
+When conducting code reviews, AI agents should systematically evaluate the following aspects:
+
+### Code Standards and Conventions
+- Do the changes follow the established conventions and patterns used throughout the codebase?
+- Is the code style consistent with existing code (indentation, naming conventions, file organization)?
+- Are the appropriate design patterns being used where applicable?
+- Does the code follow the monorepo structure and package boundaries?
+- Are TypeScript types properly defined and avoiding `any` types?
+
+### Security Assessment
+- Do the changes introduce any security vulnerabilities or risks?
+- Are user inputs properly validated and sanitized?
+- Is sensitive data properly handled and protected?
+- Are authentication and authorization checks properly implemented?
+- Are there any exposed API keys, credentials, or sensitive configuration data?
+- Are network requests using appropriate security protocols (HTTPS, proper headers)?
+- Is XSS protection properly implemented (no dangerouslySetInnerHTML without sanitization)?
+- Are Content Security Policy considerations met?
+
+### Performance Considerations
+- Do the changes introduce potential performance bottlenecks?
+- Are there any inefficient algorithms or data structures being used?
+- Is there unnecessary re-rendering or state updates in React components?
+- Are React hooks (useMemo, useCallback, memo) used appropriately to prevent unnecessary renders?
+- Are large lists properly virtualized where appropriate?
+- Is lazy loading implemented for heavy resources and code splitting used effectively?
+- Are bundle sizes kept reasonable (check with build output)?
+- Is tree-shaking working properly for unused exports?
+- Are web vitals (LCP, FID, CLS) maintained or improved?
+
+### React/TypeScript Best Practices
+- Are components properly optimized using React.memo, useMemo, and useCallback where appropriate?
+- Is component composition preferred over prop drilling?
+- Are custom hooks following the Rules of Hooks?
+- Is proper error boundary implementation in place?
+- Are TypeScript generics used effectively for reusable components?
+- Is strict mode TypeScript being followed (no implicit any, proper null checking)?
+- Are discriminated unions used for complex state management?
+- Are React 18+ features (Suspense, concurrent features) used appropriately?
+
+### Package Architecture
+- Does the code respect package boundaries (core → hooks → ui dependency order)?
+- Are internal APIs properly exported through package index files?
+- Is the unified versioning strategy maintained?
+- Are workspace dependencies correctly referenced?
+- Does the code follow the established build order requirements?
+
+### Functional Verification
+- Does the code actually implement what the PR description claims?
+- Are all acceptance criteria from the related issue/ticket met?
+- Are edge cases properly handled?
+- Is error handling comprehensive and user-friendly?
+- Are all promised features fully implemented and working?
+- Do changes work across all supported browsers?
+
+### Testing and Documentation
+- Are appropriate tests included for new functionality (using Vitest)?
+- Do tests follow the *.test.ts(x) naming pattern?
+- Do existing tests still pass?
+- Is the code self-documenting with clear variable and function names?
+- Are complex logic sections properly commented?
+- Are API changes documented with proper TypeScript JSDoc?
+- Are breaking changes clearly identified in changesets?
+- Is test coverage maintained or improved?
+
+### Dependencies and Compatibility
+- Are new dependencies necessary and well-maintained?
+- Do new dependencies have appropriate TypeScript types?
+- Are version requirements appropriate and following semver?
+- Is backward compatibility maintained where expected?
+- Are deprecated APIs avoided?
+- Are peer dependencies properly defined for the published packages?
+- Is the minimum Node.js version (>= 20.0.0) respected?
+
+### Build System and Tooling
+- Do changes work with the Turbo build cache?
+- Are tsup configurations properly maintained?
+- Does API Extractor successfully generate type definitions?
+- Do lint and format commands pass successfully?
+- Are pre-commit hooks passing?
+- Are changeset entries created for user-facing changes?
+
+### Accessibility
+- Are ARIA attributes properly implemented?
+- Is keyboard navigation fully supported?
+- Are focus states clearly visible?
+- Do interactive elements have appropriate roles?
+- Are form inputs properly labeled?
+- Is color contrast WCAG compliant?
+- Are screen reader announcements appropriate?
+
+### User Experience
+- Do the changes provide a smooth and intuitive user experience?
+- Are loading states and error states properly handled?
+- Is feedback provided for user actions?
+- Are animations performant and purposeful (respecting prefers-reduced-motion)?
+- Is responsive design maintained across viewport sizes?
+- Are browser-specific quirks handled appropriately?
+
+### Developer Experience
+- Is the API intuitive and consistent with existing patterns?
+- Are TypeScript types providing good IDE support and autocomplete?
+- Are error messages helpful and actionable?
+- Is the component API well-designed and flexible?
+- Are props properly documented with JSDoc comments?
+- Are examples provided for complex usage patterns?
diff --git a/greptile.json b/greptile.json
new file mode 100644
index 0000000..2c1059e
--- /dev/null
+++ b/greptile.json
@@ -0,0 +1,43 @@
+{
+  "commentTypes": ["logic", "syntax", "style"],
+  "instructions": "Enforce project-specific review guidelines - see docs/review-guidelines.md for complete checklist",
+  "customContext": {
+    "rules": [
+      {
+        "scope": ["src/**"],
+        "rule": "Package dependencies must follow core → hooks → ui dependency order"
+      },
+      {
+        "scope": ["src/**"],
+        "rule": "Always use workspace:* protocol for internal dependencies"
+      },
+      {
+        "scope": ["src/**"],
+        "rule": "Schema-first: All types defined in schemas/*.ts using Zod"
+      },
+      {
+        "scope": ["packages/**"],
+        "rule": "Unified versioning: All packages must maintain exact same version - never version packages independently"
+      },
+      {
+        "scope": ["packages/core/src/**"],
+        "rule": "Zero React: Pure TypeScript, no React dependencies"
+      },
+      {
+        "scope": ["packages/hooks/src/context/**"],
+        "rule": "Context and Provider in separate files, exported via context/index.ts"
+      },
+      {
+        "scope": ["packages/ui/src/**"],
+        "rule": "Auto-injected styles: index.ts calls injectStyles() on module load"
+      }
+    ],
+    "files": [
+      {
+        "scope": ["*"],
+        "path": "docs/review-guidelines.md",
+        "description": "Comprehensive review checklist for all pull requests"
+      }
+    ]
+  }
+}
diff --git a/packages/core/AGENTS.md b/packages/core/AGENTS.md
new file mode 100644
index 0000000..0a67e52
--- /dev/null
+++ b/packages/core/AGENTS.md
@@ -0,0 +1,75 @@
+# @youversion/platform-core
+
+## OVERVIEW
+Foundation package providing pure TypeScript API clients for YouVersion services with zero React dependencies.
+
+## STRUCTURE
+```
+schemas/                     # Zod schemas for all data types (schema-first design)
+client.ts                    # ApiClient - main HTTP client
+bible.ts                     # BibleClient - Bible data operations
+languages.ts                 # LanguagesClient - language data
+highlights.ts                # HighlightsClient - user highlights
+YouVersionAPI.ts             # Base YouVersion API client
+SignInWithYouVersionPKCE.ts  # PKCE auth implementation
+StorageStrategy.ts           # Storage interface (SessionStorage, MemoryStorage)
+```
+
+## PUBLIC API
+- `ApiClient`: Main HTTP client with auth handling
+- `BibleClient`: Fetch Bibles, chapters, verses, versions
+- `LanguagesClient`: Get available languages
+- `HighlightsClient`: Manage user highlights
+- `SignInWithYouVersionPKCE()`: PKCE auth flow function
+- `SessionStorage`, `MemoryStorage`: Storage strategies
+
+## DOs / DON'Ts
+
+✅ Do: Keep this package **framework-agnostic** (no React, no DOM, no browser-only APIs)
+✅ Do: Define all input/output types in `schemas/` using Zod; schemas are the single source of truth
+✅ Do: Reuse `YouVersionAPI` base client for new service clients
+✅ Do: Parse API responses with Zod schemas for validation
+
+❌ Don't: Import React, `window`, `document`, or browser storage APIs directly
+❌ Don't: Bypass Zod validation for API responses
+❌ Don't: Implement UI, hooks, or React state here
+
+## ADDING A NEW ENDPOINT OR CLIENT
+
+1. **Define types** in `schemas/` using Zod:
+   - Request payload schema
+   - Response schema
+2. **Extend or add a client**:
+   - Prefer extending existing clients (e.g., `BibleClient`) when the endpoint logically belongs there
+   - Otherwise, create `xyz.ts` with a new `XyzClient` that composes `YouVersionAPI`
+3. **Wire validation**:
+   - Parse API responses with the corresponding Zod schema
+   - Throw or return typed errors on validation failure
+4. **Export from public API**:
+   - Expose the new client/types from the main entry file so consumers can import them
+5. **Add tests**:
+   - Unit tests with MSW for mock responses
+   - Optional integration tests guarded by `INTEGRATION_TESTS=true`
+
+## HTTP & CONFIGURATION
+
+- HTTP client: Native `fetch` API
+- Base client: `YouVersionAPI` handles base URL, headers, auth tokens
+- All clients extend or compose `YouVersionAPI` for consistent HTTP behavior
+
+## CONVENTIONS
+- Schema-first: All types defined in schemas/*.ts using Zod
+- Zero React: Pure TypeScript, no React dependencies
+- Storage: Abstract via StorageStrategy interface
+- Auth: PKCE flow with pluggable storage backends
+- Error handling: Zod validation for all API responses
+
+## TESTING
+
+- Run tests: `pnpm --filter @youversion/platform-core test`
+- Framework: Vitest with Node environment
+- Mocking: MSW for API endpoints
+- Integration tests:
+  - Guarded by `INTEGRATION_TESTS=true`
+  - Only run in CI or when explicitly needed; default to mocked tests
+- Coverage: @vitest/coverage-v8
diff --git a/packages/core/CLAUDE.md b/packages/core/CLAUDE.md
new file mode 120000
index 0000000..47dc3e3
--- /dev/null
+++ b/packages/core/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/packages/hooks/AGENTS.md b/packages/hooks/AGENTS.md
new file mode 100644
index 0000000..765fd79
--- /dev/null
+++ b/packages/hooks/AGENTS.md
@@ -0,0 +1,64 @@
+# @youversion/platform-react-hooks
+
+## OVERVIEW
+React integration layer providing data fetching hooks with 3 core providers: YouVersionProvider, YouVersionAuthProvider, and ReaderProvider.
+
+**Depends on `@youversion/platform-core` for all API calls.** Hooks delegate to core clients; do not implement raw HTTP here.
+
+## STRUCTURE
+- `use*.ts` - Data fetching hooks (useBook, useChapter, usePassage, useVersion, etc.)
+- `context/` - Providers and contexts (separate files, exported via index.ts)
+- `utility/` - Helper functions (useDebounce, extractTextFromHTML, extractVersesFromHTML)
+
+## PUBLIC API
+- Data fetching hooks: useBook, useChapter, usePassage, useVersion, useVOTD, useVerse, useChapterNavigation, etc.
+- YouVersionProvider - Core SDK configuration
+- YouVersionAuthProvider - Authentication state
+- ReaderProvider - Reading session context
+- Utility functions exported from utility/index
+
+## PROVIDERS
+
+- **YouVersionProvider**
+  - Holds core SDK configuration (API base URL, clients)
+  - Wrap this around your app before using any data hooks
+
+- **YouVersionAuthProvider**
+  - Manages authentication state (userInfo, tokens, isLoading, error)
+  - Auth hooks like `useYVAuth` depend on this provider
+
+- **ReaderProvider**
+  - Manages Bible reading session state (currentVersion, currentChapter, currentBook, currentVerse)
+  - Hooks like `useChapterNavigation` depend on this provider
+
+## DOs / DON'Ts
+
+✅ Do: Use `YouVersionProvider` for configuration and access that config in hooks
+✅ Do: Wrap async data access in hooks rather than calling core clients directly in components
+✅ Do: Keep hooks **UI-agnostic** (no JSX returned, no direct DOM manipulation)
+✅ Do: Use the `useApiData` pattern for new data fetching hooks
+
+❌ Don't: Import components from `@youversion/platform-react-ui`
+❌ Don't: Talk directly to `fetch`/HTTP; always use `@youversion/platform-core`
+❌ Don't: Access `window.localStorage` directly for auth; rely on core's storage abstractions
+
+## DATA FETCHING PATTERN
+
+Hooks use a custom React Query-like pattern via `useApiData`:
+- Returns `{ data, loading, error, refetch }`
+- Provides caching and refetch capability
+- New hooks should follow this same pattern
+
+## CONVENTIONS
+- Context and Provider in separate files
+- All contexts exported via context/index.ts
+- TypeScript declarations generated separately (no bundling)
+- Build: tsc only
+
+## TESTING
+
+- Run tests: `pnpm --filter @youversion/platform-react-hooks test`
+- Framework: Vitest with jsdom environment
+- React Testing Library for component/hook tests
+- Mock APIs live in `__tests__/mocks`
+- Use provider wrappers for tests so hooks see the same context as in the app
diff --git a/packages/hooks/CLAUDE.md b/packages/hooks/CLAUDE.md
new file mode 120000
index 0000000..47dc3e3
--- /dev/null
+++ b/packages/hooks/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/packages/ui/AGENTS.md b/packages/ui/AGENTS.md
new file mode 100644
index 0000000..0f1c548
--- /dev/null
+++ b/packages/ui/AGENTS.md
@@ -0,0 +1,82 @@
+# @youversion/platform-react-ui
+
+## OVERVIEW
+Complete UI layer with many Bible components: BibleTextView, VerseOfTheDay, BibleReader, BibleChapterPicker, BibleVersionPicker, YouVersionAuthButton, BibleWidgetView, BibleAppLogoLockup
+
+## STRUCTURE
+```
+components/            # Public Bible components (exported)
+components/ui/         # Internal Radix primitives (not exported)
+lib/                   # Utilities (injectStyles, utils)
+src/index.ts           # Entry point with style injection side effect
+```
+
+## PUBLIC API
+- Components exported from `src/components/`
+- Re-exports from `@youversion/platform-core`:
+  - `SignInWithYouVersionPermission`, `SignInWithYouVersionResult`, `YouVersionAPIUsers`
+  - `ApiConfig`, `AuthenticationState` types
+- Re-exports from `@youversion/platform-react-hooks`:
+  - `YouVersionProvider`, `useYVAuth`, `UseYVAuthReturn` type
+
+## DOs / DON'Ts
+
+✅ Do: Use hooks from `@youversion/platform-react-hooks` for data; keep components thin
+✅ Do: Use Radix UI primitives from `components/ui/` for low-level behaviors (modals, popovers, etc.)
+✅ Do: Use Tailwind classes with the `yv:` prefix only
+✅ Do: Use semantic theme tokens (`yv:text-muted-foreground`, `yv:bg-destructive`) instead of arbitrary colors
+
+❌ Don't: Make raw network requests from UI components
+❌ Don't: Import from `@youversion/platform-core` directly (except re-exports in index.ts)
+❌ Don't: Add global CSS files; all styling goes through Tailwind build and `injectStyles`
+❌ Don't: Use unprefixed Tailwind classes (causes collisions in consumer apps)
+
+## CONVENTIONS
+- React 19+ peer dependency
+- Radix UI primitives for accessibility
+- Tailwind CSS via @tailwindcss/cli v4
+- tsup for bundling, tsc for type declarations
+
+## STYLING
+**Auto-injected on import**: `src/index.ts` calls `injectStyles()` on module load
+- CSS embedded as `__YV_STYLES__` constant via tsup define (no separate CSS file)
+- Built Tailwind CSS: `dist/tailwind.css` → injected as JS string at build time
+- For the theme to be applied to our components, we add a `data-yv-sdk` attribute on the parent containing element
+- Tailwind CSS classes must be prefixed with `yv:` to prevent class naming collision when someone uses our components in their app. For example, `mt-4` becomes `yv:mt-4`
+- Light/dark mode via CSS variables (`[data-yv-sdk]`)
+- Use semantic theme tokens (`yv:text-muted-foreground`, `yv:bg-destructive`) instead of arbitrary color values
+
+### Styling Usage Example
+
+```tsx
+export function Example() {
+  return (
+    <div data-yv-sdk>
+      <BibleTextView reference="John 3:16" />
+    </div>
+  );
+}
+```
+
+## TESTING
+- Vitest + jsdom for unit tests (`*.test.tsx`)
+- Playwright for Storybook integration tests (`pnpm test:integration`)
+- All Storybook tests with a play function need to have a `tags: ['integration']`
+- Test setup: `src/test/setup.ts`
+
+## BUILD ORDER
+```bash
+pnpm build:css    # Tailwind build + strip-layers.js
+pnpm build:js     # tsup bundling with __YV_STYLES__ injection
+pnpm build:types  # tsc declarations
+```
+
+From repo root, `pnpm build` runs Turbo which builds in order:
+1. `@youversion/platform-core`
+2. `@youversion/platform-react-hooks`
+3. `@youversion/platform-react-ui` (build:css → build:js → build:types)
+
+## CRITICAL
+- **Side effect**: importing package injects styles automatically
+- Never skip build:css step (styles required for __YV_STYLES__ constant)
+- Always rebuild after CSS changes
diff --git a/packages/ui/CLAUDE.md b/packages/ui/CLAUDE.md
new file mode 120000
index 0000000..47dc3e3
--- /dev/null
+++ b/packages/ui/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file