docs(agents): add per-package AGENTS.md for all core-* packages

packages/core-api/AGENTS.md

@@ -0,0 +1,48 @@
+# AGENTS.md — core-api
+
+**Composition-only package** that aggregates feature tRPC routers into a single root `appRouter`. It does not define procedures; instead, it imports them from feature packages.
+
+## Responsibilities
+
+- **Compose tRPC appRouter** — merges feature routers into `t.router({ ... })`
+- **Type export** — exports `AppRouter` type for frontend type safety
+- **No procedure definitions** — all routers owned by their respective features (`@repo/auth`, `@repo/blog`, etc.)
+- **No business logic** — purely structural assembly
+
+## Allowed imports
+
+- **`@repo/<feature>/api`** subpath exports only (to get tRPC routers)
+  - e.g., `import { authRouter } from "@repo/auth/api"`
+  - e.g., `import { blogRouter } from "@repo/blog/api"`
+  - e.g., `import { navigationRouter } from "@repo/navigation/api"`
+- `@repo/core-shared/trpc/init` — for `t.router()` builder
+
+## Must NOT import
+
+- Any feature's root package or other subpaths (e.g., NOT `@repo/blog/di`, NOT `@repo/blog/entities`)
+- Any app package
+- `@repo/core-cms`, `@repo/core-trpc`, `@repo/core-ui`
+
+## Public exports
+
+From `package.json`:
+- `.` — `appRouter` and `AppRouter` type
+
+Example usage:
+```typescript
+import { appRouter, type AppRouter } from "@repo/core-api";
+```
+
+## Test conventions
+
+- No unit tests (composition layer)
+- Verify at app boot: `pnpm dev --filter @repo/web-next` succeeds and tRPC client fetches data
+- Run router health check: `pnpm typecheck` confirms `AppRouter` type is valid
+
+## Structure
+
+```
+src/
+  root.ts                    # t.router({ ... }) aggregating all feature routers
+  index.ts                   # re-exports appRouter + type
+```

packages/core-cms/AGENTS.md

@@ -0,0 +1,51 @@
+# AGENTS.md — core-cms
+
+**Composition-only package** that aggregates feature Payload collections and globals into a single Payload config. It does not define its own collections; instead, it imports them from feature packages.
+
+## Responsibilities
+
+- **Compose Payload config** — `buildConfig()` with all collections and globals from features
+- **Type generation** — Output `generated-types.ts` from Payload's TypeScript generator
+- **No collection definitions** — all collections owned by their respective features (`@repo/auth`, `@repo/blog`, etc.)
+- **No business logic** — purely structural assembly
+
+## Allowed imports
+
+- **`@repo/<feature>/cms`** subpath exports only (to get collections/globals)
+  - e.g., `import { articles } from "@repo/blog/cms"`
+  - e.g., `import { users } from "@repo/auth/cms"`
+  - e.g., `import { pages, siteSettings } from "@repo/marketing-pages/cms"`
+
+## Must NOT import
+
+- Any feature's root package or other subpaths (e.g., NOT `@repo/blog/di`, NOT `@repo/blog/entities`)
+- Any app package
+- `@repo/core-shared`, `@repo/core-api`, `@repo/core-trpc`, `@repo/core-ui`
+
+## Public exports
+
+From `package.json`:
+- `.` — the Payload config (default export) + buildConfig re-export
+- `./generated-types` — Payload-generated TypeScript types
+
+Example usage:
+```typescript
+import { buildConfig } from "@repo/core-cms";
+// or
+import type { Config, User, Article } from "@repo/core-cms/generated-types";
+```
+
+## Test conventions
+
+- No unit tests (composition layer)
+- Verify at app boot: `pnpm dev --filter @repo/cms` succeeds and admin UI loads
+- Type generation: `pnpm generate:types` in `apps/cms`
+
+## Structure
+
+```
+src/
+  payload.config.ts          # imports feature /cms exports, calls buildConfig()
+  generated-types.ts         # auto-generated by Payload
+  index.ts                   # re-exports config
+```

packages/core-shared/AGENTS.md

@@ -0,0 +1,36 @@
+# AGENTS.md — core-shared
+
+Generic, reusable primitives with **zero business knowledge**. This package is the foundation for all other packages and exports utilities, Payload field/hook definitions, and tRPC initialization.
+
+## Responsibilities
+
+- **Generic primitives** — environment helpers, date utilities, type guards
+- **Payload utilities** — field definitions (slug, SEO), blocks (CTA), access controls (is-admin), hooks (slugify, publish timestamp)
+- **tRPC platform** — `initTRPC.create()`, shared context factory, procedure builders
+- **No business domain knowledge** — no awareness of articles, users, media, or any feature
+
+## Must NOT import
+
+- Any feature package (`@repo/auth`, `@repo/blog`, etc.)
+- Any app package
+- Framework-specific code (Next.js, TanStack React Query)
+
+## Public exports
+
+From `package.json`:
+- `.` — all utilities, Payload exports, tRPC init
+- `./payload` — Payload field/hook/block utilities only
+- `./trpc/init` — tRPC initialization only
+- `./trpc/context` — tRPC context factory only
+
+## Test conventions
+
+- Tests colocated: `src/lib/slug-field.ts` → `src/lib/slug-field.test.ts`
+- Vitest environment: `node`
+- Alias: `@/` resolves to `src/`
+- Run: `pnpm test --filter @repo/core-shared`
+
+Covered areas:
+- Slug field generation + validation
+- Payload hooks (publish-at timestamp, slugify-if-missing)
+- Access control helpers

packages/core-trpc/AGENTS.md

@@ -0,0 +1,54 @@
+# AGENTS.md — core-trpc
+
+Frontend tRPC platform providing the client and framework-specific providers (Next.js, TanStack). Bridges typed backend (`@repo/core-api`) to frontend applications.
+
+## Responsibilities
+
+- **Create tRPC React client** — `createTRPCReact<AppRouter>()` for use in React apps
+- **Query client factory** — TanStack React Query setup per app
+- **Framework-specific providers** — Next.js App Router provider + TanStack Start provider
+- **No business logic** — purely framework integration
+
+## Must NOT import
+
+- Any feature package (`@repo/auth`, `@repo/blog`, etc.)
+- Any app package
+- `@repo/core-api`, `@repo/core-cms`, `@repo/core-ui`
+
+## Public exports
+
+From `package.json`:
+- `.` — client + query client factory
+- `./next` — Next.js App Router provider
+- `./tanstack` — TanStack Start provider
+
+Example usage:
+```typescript
+// In Next.js app
+import { TrpcProvider } from "@repo/core-trpc/next";
+
+// In TanStack Start app
+import { TrpcProvider } from "@repo/core-trpc/tanstack";
+
+// In client components
+import { useTRPC } from "@repo/core-trpc";
+const trpc = useTRPC();
+```
+
+## Test conventions
+
+- No unit tests (provider layer)
+- Verify at app boot: `pnpm dev --filter @repo/web-next` or `pnpm dev --filter @repo/web-tanstack` succeeds
+- Verify client type safety: `pnpm typecheck` confirms `AppRouter` is imported and typed correctly
+
+## Structure
+
+```
+src/
+  client.ts                  # createTRPCReact<AppRouter>()
+  query-client.ts            # makeQueryClient()
+  providers/
+    next-provider.tsx        # 'use client' provider for Next.js
+    tanstack-provider.tsx    # Provider for TanStack Start
+  index.ts                   # re-exports client + factories
+```

packages/core-ui/AGENTS.md

@@ -0,0 +1,65 @@
+# AGENTS.md — core-ui
+
+Design-system primitives organized by Atomic Design. Only **generic components** (atoms, molecules, generic organisms) live here. Feature-specific components live in their respective feature packages.
+
+## Responsibilities
+
+- **Atoms** — Single HTML elements: Button, Input, Label, Card
+- **Molecules** — Combinations: FormField (Label + Input), Badge, Avatar
+- **Generic Organisms** — Reusable complex layouts: Modal, Tabs, NavigationMenu, CommandPalette
+- **Templates** — Page layouts: AuthLayout, DashboardLayout, LandingLayout
+- **Utilities** — `cn()` for className merging, design tokens, Tailwind config
+
+## Feature-specific boundary
+
+Feature-specific organisms (e.g., `ArticleCard`, `ArticleList`, `HeaderNavMenu`) live in their feature's `ui/` folder, NOT here. This boundary keeps `core-ui` framework-agnostic and reusable.
+
+## Must NOT import
+
+- Any feature package (`@repo/auth`, `@repo/blog`, etc.)
+- Any app package
+- `@repo/core-api`, `@repo/core-cms`, `@repo/core-trpc`
+
+## Public exports
+
+From `package.json`:
+- `.` — all atoms, molecules, organisms, templates
+
+Example usage:
+```typescript
+import { Button, Input, Label } from "@repo/core-ui";
+import { FormField } from "@repo/core-ui";
+import { Modal, Tabs } from "@repo/core-ui";
+```
+
+## Test conventions
+
+- Tests colocated: `src/atoms/button/button.tsx` → `src/atoms/button/button.test.tsx`
+- Vitest environment: `jsdom` (React component testing)
+- Alias: `@/` resolves to `src/`
+- Run: `pnpm test --filter @repo/core-ui`
+- Storybook stories colocated: `src/atoms/button/button.stories.tsx`
+
+## Structure
+
+```
+src/
+  atoms/
+    {name}/
+      {name}.tsx             # Component
+      {name}.test.tsx        # Tests
+      {name}.stories.tsx     # Storybook story
+      index.ts               # Barrel export
+  molecules/
+    {name}/
+      ...
+  organisms/
+    {name}/
+      ...
+  templates/
+    {name}/
+      ...
+  lib/
+    utils.ts                 # cn() and helpers
+  index.ts                   # Re-exports everything
+```