# AGENTS.md — apps/cms

**Thin shell** hosting the Payload CMS admin panel via Next.js. All CMS configuration (collections, globals, hooks, access control, `payload.config.ts`) lives in `@repo/core-cms`, which aggregates collections from feature packages.

## Purpose

This app exists solely to serve the Payload Admin UI. It contains no custom CMS code beyond Next.js routing boilerplate. All business knowledge lives in feature packages (`@repo/auth`, `@repo/blog`, etc.), which export their collections/globals via subpath exports (`.../cms`). `@repo/core-cms` composes them into a single Payload config.

## Port: 3001

```bash
docker compose up -d postgres    # Start PostgreSQL on port 5432
pnpm dev --filter @repo/cms      # http://localhost:3001/admin
```

## Key Files

| File | Purpose |
|---|---|
| `next.config.mjs` | Minimal config wrapped with `withPayload()` from `@payloadcms/next` |
| `tsconfig.json` | TypeScript config with `@payload-config` path alias |
| `src/app/(payload)/layout.tsx` | Auto-generated Payload root layout (DO NOT MODIFY) |
| `src/app/(payload)/admin/[[...segments]]/page.tsx` | Auto-generated catch-all admin page (DO NOT MODIFY) |
| `src/app/(payload)/importMap.js` | Auto-generated Payload import map (DO NOT MODIFY) |

## Hard Rules

- **NEVER** add collections, globals, or hooks in this app — put them in feature packages
- **NEVER** create custom CMS logic here — use `@repo/core-cms`
- **NEVER** modify auto-generated files under `src/app/(payload)/`
- All Payload config changes go in `packages/core-cms/src/payload.config.ts`

## @payload-config Alias

The `tsconfig.json` points to `@repo/core-cms`:

```json
{
  "compilerOptions": {
    "paths": {
      "@payload-config": ["../../packages/core-cms/src/payload.config.ts"]
    }
  }
}
```

When Payload imports `@payload-config`, it resolves to the composed config from `@repo/core-cms`, which in turn imports feature collections.

## Composition flow

```
Feature 1 (@repo/blog)
  └─ src/integrations/cms/collections/articles.ts
      └─ exported as ./cms

Feature 2 (@repo/auth)
  └─ src/integrations/cms/collections/users.ts
      └─ exported as ./cms

Feature 3 (@repo/navigation)
  └─ src/integrations/cms/globals/header.ts
      └─ exported as ./cms

Core CMS (@repo/core-cms)
  └─ src/payload.config.ts
      imports all feature /cms exports
      calls buildConfig({ collections, globals })

This app (@repo/cms)
  └─ src/app/(payload)/layout.tsx
      loads config from @payload-config
      Payload CLI auto-generates admin routes
```

## Type Generation

After adding/modifying collections in any feature's `/cms` folder:

```bash
cd apps/cms && pnpm generate:types
# Regenerates packages/core-cms/src/generated-types.ts
```

## Dependencies

| Dependency | Purpose |
|---|---|
| `@repo/core-cms` | Payload config + buildConfig |
| `@payloadcms/next` | Next.js integration for Payload |
| `payload` | Payload CMS core |
| `next` | Next.js 15 framework |
| `sharp` | Image processing |

## Cross-References

- **Feature collections:** each feature's `src/integrations/cms/` folder
- **CMS composition:** `packages/core-cms/AGENTS.md`