YPE-1006: Update AGENTS.md & CLAUDE.md files so that AI agents can better work with this repo

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