# Agent Instructions

## Monorepo Package Map

| Package | Purpose |
|---|---|
| `@repo/core` | Clean architecture: entities, use cases, interfaces, DI |
| `@repo/api` | tRPC router definitions (calls core controllers) |
| `@repo/api-client` | Shared React Query hooks + ApiProvider |
| `@repo/cms-core` | Payload CMS config, collections, hooks, globals |
| `@repo/cms-client` | Dual-mode Payload client (local + HTTP) |
| `@repo/ui` | shadcn/ui + Atomic Design component library |
| `@repo/eslint-config` | Shared ESLint flat configs |
| `@repo/typescript-config` | Shared TypeScript configs |

| App | Purpose |
|---|---|
| `apps/web-next` | Next.js 15 reference app |
| `apps/web-tanstack` | TanStack Start reference app |
| `apps/cms` | Thin Next.js shell for Payload admin |
| `apps/storybook` | Centralized Storybook instance |

## Dependency Flow (one direction only)

```
apps/web-next, apps/web-tanstack → @repo/api-client → @repo/api → @repo/core
apps/cms → @repo/cms-core → @repo/core/application (hooks only)
@repo/core/infrastructure → @repo/cms-client (standalone)
@repo/ui (standalone)
```

## HARD RULES — NEVER VIOLATE

- **NEVER:** packages/core → apps/*
- **NEVER:** apps/cms → packages/core/infrastructure
- **NEVER:** packages/cms-client → apps/cms or packages/core or packages/cms-core
- **NEVER:** packages/cms-core → packages/cms-client
- **NEVER:** core/entities → anything
- **NEVER:** core/application → core/infrastructure

## How to Add a New Feature (end-to-end)

1. Define entity in `packages/core/src/entities/models/`
2. Define repository interface in `packages/core/src/application/repositories/`
3. Write use case in `packages/core/src/application/use-cases/{domain}/`
4. Write controller in `packages/core/src/interface-adapters/controllers/{domain}/`
5. Write infrastructure implementation in `packages/core/src/infrastructure/`
6. Register in DI container (`packages/core/src/di/`)
7. Add tRPC router in `packages/api/src/router/`
8. Add React Query hook in `packages/api-client/src/hooks/`
9. If CMS collection needed: add to `packages/cms-core/src/collections/`
10. Build UI component in `packages/ui/src/` (classify atomic level)
11. Write Storybook story (co-located `.stories.tsx`)
12. Write tests (unit in packages/core/tests/, E2E in tests/e2e/)

## How to Add a New UI Component

1. Classify: atom (single element), molecule (2-3 atoms), organism (complex section), template (layout)
2. Create folder: `packages/ui/src/{level}/{component-name}/`
3. Create: `{name}.tsx`, `{name}.stories.tsx`, `index.ts`
4. Story title: `"{Level}/{ComponentName}"` (e.g., `"Atoms/Button"`)
5. Export from level's `index.ts` barrel file
6. Import rules: atoms ← nothing | molecules ← atoms | organisms ← atoms+molecules | templates ← all

## How to Add a Payload CMS Collection

1. Create folder: `packages/cms-core/src/collections/{name}/`
2. Create: `index.ts` (CollectionConfig), `fields.ts`, optionally `hooks/`, `access/`
3. Import in `packages/cms-core/src/payload.config.ts` collections array
4. Export from `packages/cms-core/src/index.ts`
5. Hooks that contain business logic must delegate to use cases in `@repo/core/application`