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

packages/auth/AGENTS.md

@@ -0,0 +1,116 @@
+# AGENTS.md — auth
+
+Users collection + authentication use cases (sign-in, sign-up, sign-out, password reset). Provides the Users Payload collection and tRPC procedures for authentication workflows.
+
+## What it owns
+
+- **Entities** — User type, auth-related errors (InvalidCredentials, UserNotFound)
+- **Use cases** — Sign-in, sign-up, sign-out, verify token, reset password
+- **Repository interface** — `IUsersRepository` for user persistence
+- **Mock repository** — In-memory user store for tests
+- **Payload repository** — Real Payload-backed user repository (constructor-injected at boot)
+- **Payload collection** — Users collection definition + hooks
+- **tRPC router** — Procedures for sign-in, sign-up, verify
+- **DI container** — Per-feature InversifyJS container with auth symbols
+- **UI components** — Auth-specific components (LoginForm, SignupForm, etc.)
+
+## Public exports
+
+From `package.json`:
+- `.` — User type + auth errors + UI components
+- `./api` — tRPC router (`authRouter`)
+- `./cms` — Payload Users collection
+- `./di/bind-production` — `bindProductionUsers()` to wire Payload repo at boot
+
+## What it must NOT import
+
+- Any other feature package (`@repo/blog`, `@repo/media`, etc.)
+- Any app package
+- `@repo/core-api`, `@repo/core-cms`, `@repo/core-trpc`, `@repo/core-ui` directly; only import from `@repo/core-shared` and use DI for Payload config
+
+## Layer rules
+
+### `src/` files use relative imports
+
+Avoid `@/` in source code:
+
+```typescript
+// ✓ Correct
+import type { IUsersRepository } from "../repositories/users.repository.interface.js";
+
+// ✗ Wrong (don't do this in src/)
+import { SomeType } from "@/entities/user.js";
+```
+
+### Tests use @/ alias
+
+Test files use `@/`:
+
+```typescript
+// ✓ Correct
+import { createUserUseCase } from "@/application/use-cases/create-user.use-case.js";
+```
+
+### DI container is per-feature
+
+Tests rebind their own container:
+
+```typescript
+import { container as authContainer, AUTH_SYMBOLS } from "@/di/container.js";
+import { MockUsersRepository } from "@/infrastructure/repositories/mock-users.repository.js";
+
+beforeEach(() => {
+  authContainer.unbindAll();
+  authContainer.bind(AUTH_SYMBOLS.IUsersRepository).to(MockUsersRepository);
+});
+```
+
+## Test conventions
+
+- **Unit tests** colocated with source: `*.test.ts` suffix
+- **Feature tests** in `tests/` folder: `*.feature.test.ts` suffix (cross-layer tests like sign-up flow)
+- **Vitest environment** — `node`
+- **Alias** — `@/` resolves to `src/`
+- **Run** — `pnpm test --filter @repo/auth`
+
+Covered areas: sign-in/up/out use cases, user validation, DI container binding.
+
+## Structure (minimal feature)
+
+```
+src/
+  entities/
+    user.ts                  # User schema + type
+    errors.ts                # AuthError, InvalidCredentials, etc.
+  application/
+    repositories/
+      users.repository.interface.ts
+    use-cases/
+      sign-in.use-case.ts
+      sign-up.use-case.ts
+  infrastructure/
+    repositories/
+      payload-users.repository.ts      # constructor-injected: Config
+      mock-users.repository.ts
+  di/
+    symbols.ts               # AUTH_SYMBOLS
+    container.ts             # authContainer
+    bind-production.ts       # bindProductionUsers(container, config)
+  interface-adapters/
+    controllers/
+      auth.controller.ts     # sign-in input validation
+  integrations/
+    cms/
+      collections/
+        users.ts             # Payload CollectionConfig
+      index.ts
+    api/
+      router.ts              # tRPC procedures
+      index.ts
+  ui/
+    login-form.tsx
+    signup-form.tsx
+  index.ts                   # re-exports: User, errors, UI components
+tests/
+  sign-up.feature.test.ts
+```

packages/blog/AGENTS.md

@@ -0,0 +1,120 @@
+# AGENTS.md — blog
+
+Articles collection + content use cases (get article, list articles, create, publish, unpublish). Provides the Articles Payload collection and tRPC procedures for content management and retrieval.
+
+## What it owns
+
+- **Entities** — Article type, article-related errors (ArticleNotFound, InvalidSlug)
+- **Use cases** — Get article, list articles, create, publish, unpublish, delete
+- **Repository interface** — `IArticlesRepository` for article persistence
+- **Mock repository** — In-memory article store for tests
+- **Payload repository** — Real Payload-backed article repository (constructor-injected at boot)
+- **Payload collection** — Articles collection definition + hooks (publish timestamp, slugify)
+- **tRPC router** — Procedures for list, get-by-slug, create, publish
+- **DI container** — Per-feature InversifyJS container with blog symbols
+- **UI components** — Article-specific components (ArticleCard, ArticleList, etc.)
+
+## Public exports
+
+From `package.json`:
+- `.` — Article type + blog errors + UI components
+- `./api` — tRPC router (`blogRouter`)
+- `./cms` — Payload Articles collection
+- `./di/bind-production` — `bindProductionArticles()` to wire Payload repo at boot
+
+## What it must NOT import
+
+- Any other feature package (`@repo/auth`, `@repo/media`, etc.)
+- Any app package
+- `@repo/core-api`, `@repo/core-cms`, `@repo/core-trpc`, `@repo/core-ui` directly; only import from `@repo/core-shared` and use DI for Payload config
+
+## Layer rules
+
+### `src/` files use relative imports
+
+Avoid `@/` in source code:
+
+```typescript
+// ✓ Correct
+import type { IArticlesRepository } from "../repositories/articles.repository.interface.js";
+
+// ✗ Wrong (don't do this in src/)
+import { Article } from "@/entities/article.js";
+```
+
+### Tests use @/ alias
+
+Test files use `@/`:
+
+```typescript
+// ✓ Correct
+import { getArticleUseCase } from "@/application/use-cases/get-article.use-case.js";
+```
+
+### DI container is per-feature
+
+Tests rebind their own container:
+
+```typescript
+import { container as blogContainer, BLOG_SYMBOLS } from "@/di/container.js";
+import { MockArticlesRepository } from "@/infrastructure/repositories/mock-articles.repository.js";
+
+beforeEach(() => {
+  blogContainer.unbindAll();
+  blogContainer.bind(BLOG_SYMBOLS.IArticlesRepository).to(MockArticlesRepository);
+});
+```
+
+## Test conventions
+
+- **Unit tests** colocated with source: `*.test.ts` suffix
+- **Feature tests** in `tests/` folder: `*.feature.test.ts` suffix (cross-layer tests like publish flow)
+- **Vitest environment** — `node`
+- **Alias** — `@/` resolves to `src/`
+- **Run** — `pnpm test --filter @repo/blog`
+
+Covered areas: article CRUD use cases, slug validation, publish/unpublish flows, DI container binding.
+
+## Structure
+
+```
+src/
+  entities/
+    article.ts               # Article schema + type
+    errors.ts                # ArticleNotFound, InvalidSlug, etc.
+  application/
+    repositories/
+      articles.repository.interface.ts
+    use-cases/
+      get-article.use-case.ts
+      list-articles.use-case.ts
+      publish-article.use-case.ts
+  infrastructure/
+    repositories/
+      payload-articles.repository.ts   # constructor-injected: Config
+      mock-articles.repository.ts
+  di/
+    symbols.ts               # BLOG_SYMBOLS
+    container.ts             # blogContainer
+    bind-production.ts       # bindProductionArticles(container, config)
+  interface-adapters/
+    controllers/
+      articles.controller.ts # input validation
+  integrations/
+    cms/
+      collections/
+        articles.ts          # Payload CollectionConfig
+      hooks/
+        after-publish.ts     # revalidate, effects
+      index.ts
+    api/
+      router.ts              # tRPC procedures
+      index.ts
+  ui/
+    article-card.tsx
+    article-list.tsx
+    query.ts                 # typed tRPC query helpers
+  index.ts                   # re-exports: Article, UI components
+tests/
+  publish-article.feature.test.ts
+```

packages/marketing-pages/AGENTS.md

@@ -0,0 +1,119 @@
+# AGENTS.md — marketing-pages
+
+Pages collection and SiteSettings global for site-wide metadata. Provides marketing/landing page content, SEO settings, and site configuration via Payload.
+
+## What it owns
+
+- **Entities** — Page type (slug, title, content, published), SiteSettings type (site name, description, logo)
+- **Use cases** — Get page, list pages, publish page, get site settings, update settings
+- **Repository interfaces** — `IPagesRepository`, `ISiteSettingsRepository`
+- **Mock repositories** — In-memory stores for tests
+- **Payload repositories** — Real Payload-backed repositories (constructor-injected at boot)
+- **Payload collection** — Pages collection definition
+- **Payload global** — SiteSettings global definition
+- **tRPC router** — Procedures for list pages, get page, get site settings
+- **DI container** — Per-feature InversifyJS container with marketing-pages symbols
+- **UI components** — Page display, hero section, CTA blocks, footer with site settings
+
+## Public exports
+
+From `package.json`:
+- `.` — Page type, SiteSettings type, UI components
+- `./api` — tRPC router (`marketingPagesRouter`)
+- `./cms` — Payload Pages collection + SiteSettings global (as separate exports)
+- `./di/bind-production` — `bindProductionMarketing()` to wire Payload repos at boot
+
+## What it must NOT import
+
+- Any other feature package (`@repo/auth`, `@repo/blog`, etc.)
+- Any app package
+- `@repo/core-api`, `@repo/core-cms`, `@repo/core-trpc`, `@repo/core-ui` directly; only import from `@repo/core-shared` and use DI for Payload config
+
+## Layer rules
+
+### `src/` files use relative imports
+
+```typescript
+// ✓ Correct
+import type { IPagesRepository } from "../repositories/pages.repository.interface.js";
+
+// ✗ Wrong
+import { Page } from "@/entities/page.js";
+```
+
+### Tests use @/ alias
+
+```typescript
+// ✓ Correct
+import { getPageUseCase } from "@/application/use-cases/get-page.use-case.js";
+```
+
+### DI container is per-feature
+
+Tests rebind:
+
+```typescript
+import { container as marketingContainer, MARKETING_SYMBOLS } from "@/di/container.js";
+import { MockPagesRepository } from "@/infrastructure/repositories/mock-pages.repository.js";
+
+beforeEach(() => {
+  marketingContainer.unbindAll();
+  marketingContainer.bind(MARKETING_SYMBOLS.IPagesRepository).to(MockPagesRepository);
+});
+```
+
+## Test conventions
+
+- **Unit tests** colocated: `*.test.ts`
+- **Feature tests** in `tests/`: `*.feature.test.ts`
+- **Vitest environment** — `node`
+- **Alias** — `@/` resolves to `src/`
+- **Run** — `pnpm test --filter @repo/marketing-pages`
+
+## Structure (minimal)
+
+```
+src/
+  entities/
+    page.ts
+    site-settings.ts
+    errors.ts
+  application/
+    repositories/
+      pages.repository.interface.ts
+      site-settings.repository.interface.ts
+    use-cases/
+      get-page.use-case.ts
+      list-pages.use-case.ts
+      get-site-settings.use-case.ts
+  infrastructure/
+    repositories/
+      payload-pages.repository.ts
+      payload-site-settings.repository.ts
+      mock-pages.repository.ts
+      mock-site-settings.repository.ts
+  di/
+    symbols.ts
+    container.ts
+    bind-production.ts
+  interface-adapters/
+    controllers/
+      pages.controller.ts
+  integrations/
+    cms/
+      collections/
+        pages.ts
+      globals/
+        site-settings.ts
+      index.ts
+    api/
+      router.ts
+      index.ts
+  ui/
+    page-display.tsx
+    hero-section.tsx
+    footer.tsx
+  index.ts
+tests/
+  publish-page.feature.test.ts
+```

packages/media/AGENTS.md

@@ -0,0 +1,109 @@
+# AGENTS.md — media
+
+Media collection for uploads (images, PDFs, etc.) and media-related use cases (upload, delete, list). Provides the Media Payload collection and tRPC procedures for asset management.
+
+## What it owns
+
+- **Entities** — Media type (filename, mimetype, size, URL), upload errors
+- **Use cases** — Upload media, delete media, list media, get media
+- **Repository interface** — `IMediaRepository` for media persistence
+- **Mock repository** — In-memory media store for tests
+- **Payload repository** — Real Payload-backed media repository (constructor-injected at boot)
+- **Payload collection** — Media collection definition
+- **tRPC router** — Procedures for upload, delete, list
+- **DI container** — Per-feature InversifyJS container with media symbols
+- **UI components** — Media upload form, media gallery
+
+## Public exports
+
+From `package.json`:
+- `.` — Media type + media errors + UI components
+- `./api` — tRPC router (`mediaRouter`)
+- `./cms` — Payload Media collection
+- `./di/bind-production` — `bindProductionMedia()` to wire Payload repo at boot
+
+## What it must NOT import
+
+- Any other feature package (`@repo/auth`, `@repo/blog`, etc.)
+- Any app package
+- `@repo/core-api`, `@repo/core-cms`, `@repo/core-trpc`, `@repo/core-ui` directly; only import from `@repo/core-shared` and use DI for Payload config
+
+## Layer rules
+
+### `src/` files use relative imports
+
+```typescript
+// ✓ Correct
+import type { IMediaRepository } from "../repositories/media.repository.interface.js";
+
+// ✗ Wrong
+import { Media } from "@/entities/media.js";
+```
+
+### Tests use @/ alias
+
+```typescript
+// ✓ Correct
+import { uploadMediaUseCase } from "@/application/use-cases/upload-media.use-case.js";
+```
+
+### DI container is per-feature
+
+Tests rebind their own container:
+
+```typescript
+import { container as mediaContainer, MEDIA_SYMBOLS } from "@/di/container.js";
+import { MockMediaRepository } from "@/infrastructure/repositories/mock-media.repository.js";
+
+beforeEach(() => {
+  mediaContainer.unbindAll();
+  mediaContainer.bind(MEDIA_SYMBOLS.IMediaRepository).to(MockMediaRepository);
+});
+```
+
+## Test conventions
+
+- **Unit tests** colocated: `*.test.ts`
+- **Feature tests** in `tests/`: `*.feature.test.ts`
+- **Vitest environment** — `node`
+- **Alias** — `@/` resolves to `src/`
+- **Run** — `pnpm test --filter @repo/media`
+
+## Structure (minimal)
+
+```
+src/
+  entities/
+    media.ts                 # Media schema + type
+    errors.ts                # UploadError, InvalidMimetype, etc.
+  application/
+    repositories/
+      media.repository.interface.ts
+    use-cases/
+      upload-media.use-case.ts
+      delete-media.use-case.ts
+  infrastructure/
+    repositories/
+      payload-media.repository.ts
+      mock-media.repository.ts
+  di/
+    symbols.ts
+    container.ts
+    bind-production.ts
+  interface-adapters/
+    controllers/
+      media.controller.ts
+  integrations/
+    cms/
+      collections/
+        media.ts
+      index.ts
+    api/
+      router.ts
+      index.ts
+  ui/
+    upload-form.tsx
+  index.ts
+tests/
+  upload.feature.test.ts
+```

packages/navigation/AGENTS.md

@@ -0,0 +1,112 @@
+# AGENTS.md — navigation
+
+Header global for main site navigation. Provides the Header Payload global and tRPC procedures for dynamic navigation content.
+
+## What it owns
+
+- **Entities** — Navigation type (title, links, menu items)
+- **Use cases** — Get header, update header
+- **Repository interface** — `INavigationRepository` for navigation persistence
+- **Mock repository** — In-memory navigation store for tests
+- **Payload repository** — Real Payload-backed navigation repository (constructor-injected at boot)
+- **Payload global** — Header global definition
+- **tRPC router** — Procedures for get header
+- **DI container** — Per-feature InversifyJS container with navigation symbols
+- **UI components** — Navigation menu, header with branding
+
+## Public exports
+
+From `package.json`:
+- `.` — Navigation type + UI components (NavigationMenu, Header)
+- `./api` — tRPC router (`navigationRouter`)
+- `./cms` — Payload Header global
+- `./di/bind-production` — `bindProductionNavigation()` to wire Payload repo at boot
+
+## What it must NOT import
+
+- Any other feature package (`@repo/auth`, `@repo/blog`, etc.)
+- Any app package
+- `@repo/core-api`, `@repo/core-cms`, `@repo/core-trpc`, `@repo/core-ui` directly; only import from `@repo/core-shared` and use DI for Payload config
+
+## Layer rules
+
+### `src/` files use relative imports
+
+```typescript
+// ✓ Correct
+import type { INavigationRepository } from "../repositories/navigation.repository.interface.js";
+
+// ✗ Wrong
+import { Navigation } from "@/entities/navigation.js";
+```
+
+### Tests use @/ alias
+
+```typescript
+// ✓ Correct
+import { getHeaderUseCase } from "@/application/use-cases/get-header.use-case.js";
+```
+
+### DI container is per-feature
+
+Tests rebind:
+
+```typescript
+import { container as navContainer, NAV_SYMBOLS } from "@/di/container.js";
+import { MockNavigationRepository } from "@/infrastructure/repositories/mock-navigation.repository.js";
+
+beforeEach(() => {
+  navContainer.unbindAll();
+  navContainer.bind(NAV_SYMBOLS.INavigationRepository).to(MockNavigationRepository);
+});
+```
+
+## Test conventions
+
+- **Unit tests** colocated: `*.test.ts`
+- **Feature tests** in `tests/`: `*.feature.test.ts`
+- **Vitest environment** — `node`
+- **Alias** — `@/` resolves to `src/`
+- **Run** — `pnpm test --filter @repo/navigation`
+
+## Structure (minimal)
+
+Per spec addendum v5 ("create folders only when needed"), this feature is small:
+
+```
+src/
+  entities/
+    navigation.ts            # Navigation/Header schema
+  application/
+    repositories/
+      navigation.repository.interface.ts
+    use-cases/
+      get-header.use-case.ts
+  infrastructure/
+    repositories/
+      payload-navigation.repository.ts
+      mock-navigation.repository.ts
+  di/
+    symbols.ts
+    container.ts
+    bind-production.ts
+  interface-adapters/
+    controllers/
+      navigation.controller.ts
+  integrations/
+    cms/
+      globals/
+        header.ts            # Payload GlobalConfig
+      index.ts
+    api/
+      router.ts
+      index.ts
+  ui/
+    navigation-menu.tsx
+    header.tsx
+  index.ts
+tests/
+  get-header.feature.test.ts
+```
+
+No `application/use-cases/` subdirectory; just one or two use-cases at the top level.