diff --git a/docs/guides/adding-a-feature.md b/docs/guides/adding-a-feature.md
index 2d25f5d..7c67e44 100644
--- a/docs/guides/adding-a-feature.md
+++ b/docs/guides/adding-a-feature.md
@@ -1,69 +1,164 @@
 # Adding a New Feature — End-to-End Guide
 
-A feature is a vertical slice: entities, use cases, repositories, tRPC router, CMS integration, DI container, and UI components — all owned by one package.
+A feature is a vertical slice: domain entities, use cases, repositories,
+tRPC router, CMS collection, DI container, and query builders — all owned
+by one package under `packages/<feature>/`.
 
-Decide upfront: **Is this a new feature or an extension of an existing one?** New features get a new package (e.g., `packages/comments`). Extensions add to an existing feature (e.g., adding an `unapprove-article` procedure to `packages/blog`).
+**New feature or extension?** A new capability gets a new package (e.g.,
+`packages/comments`). Adding an operation to an existing feature (e.g.,
+a `publishArticle` procedure to `packages/blog`) means extending that
+package — create new files alongside the existing ones, following the same
+per-use-case patterns below.
 
-> **TDD Order Required:** You may not advance to the next layer until the
-> current layer's tests are red, then green. See [TDD Workflow](./tdd-workflow.md).
+> **TDD Order Required.** Write a failing test before each implementation
+> file. Advance to the next layer only after the current layer is green.
+> See [TDD Workflow](./tdd-workflow.md).
 
-## Part 1: New Feature Scaffold
+---
 
-### Step 1: Decide shape
+## 1. Overview
 
-The smallest viable feature has:
-- `entities/` — type definitions and schemas (Zod)
-- `application/use-cases/` — one business operation
-- `application/repositories/` — interface + mock implementation
-- `infrastructure/repositories/` — Payload-backed implementation (if needed)
-- `di/` — InversifyJS container + symbol table
-- `integrations/api/` — tRPC router (optional if no read API)
-- `integrations/cms/` — Payload collection/global (if Payload-backed)
-- `ui/` — feature-specific components (atoms/molecules/organisms)
+Every feature package owns:
 
-### Step 2: Create the package
+| Layer | What lives there |
+|---|---|
+| `entities/models/` | Zod schemas + inferred TypeScript types |
+| `entities/errors/` | Domain error classes (`this.name` required); `common.ts` for `InputParseError` |
+| `application/repositories/` | Repository interface (no implementation) |
+| `application/use-cases/` | One factory per operation; owns `xInputSchema`, `xOutputSchema`, and `xOutputSchema.parse()` |
+| `infrastructure/repositories/` | Real (`<noun>.repository.ts`) and mock (`<noun>.repository.mock.ts`) siblings |
+| `interface-adapters/controllers/` | One factory per use case; accepts `unknown`, calls `safeParse`, runs presenter |
+| `di/` | `symbols.ts` + `module.ts` + `container.ts` + `bind-production.ts` |
+| `integrations/api/` | `procedures.ts` (feature error map) + `router.ts` (uses `xProcedure.input(xInputSchema)`) |
+| `integrations/cms/` | Payload collection/global configs |
+| `ui/` | Query builders and future React components (behind `./ui` subpath) |
+| `__factories__/` | Test data factories |
+| `__contracts__/` | Contract suites shared by mock and real repository tests |
 
-```bash
-mkdir -p packages/<feature-name>/src/{entities,application/{use-cases,repositories},infrastructure/repositories,di,integrations/{api,cms},ui,interface-adapters/controllers,__factories__,__contracts__}
+The walkthrough below builds a minimal `comments` feature from scratch.
+All concrete code mirrors the `blog` package (the most fully developed
+feature) — read `packages/blog/src/` alongside this guide.
+
+---
+
+## 2. Canonical Folder Layout
+
+```
+packages/comments/
+  src/
+    entities/
+      models/
+        comment.ts                # Zod schema + Comment type
+        comment.test.ts
+      errors/
+        comment.ts                # CommentNotFoundError  (this.name required)
+        common.ts                 # InputParseError       (this.name required)
+        errors.test.ts
+    application/
+      repositories/
+        comments.repository.interface.ts
+      use-cases/
+        get-comments.use-case.ts  # getCommentsInputSchema + getCommentsOutputSchema + parse
+        get-comments.use-case.test.ts
+        create-comment.use-case.ts
+        create-comment.use-case.test.ts
+    infrastructure/
+      repositories/
+        comments.repository.mock.ts       # MockCommentsRepository
+        comments.repository.mock.test.ts  # runs contract suite
+        comments.repository.ts            # CommentsRepository (Payload-backed)
+        comments.repository.test.ts       # runs contract suite against Payload stub
+    interface-adapters/
+      controllers/
+        get-comments.controller.ts        # factory + presenter
+        get-comments.controller.test.ts
+        create-comment.controller.ts
+        create-comment.controller.test.ts
+    di/
+      symbols.ts
+      module.ts
+      container.ts
+      container.test.ts
+      bind-production.ts
+    integrations/
+      api/
+        procedures.ts   # commentsProcedure with feature error map
+        router.ts       # commentsProcedure.input(xInputSchema)
+        router.test.ts  # includes R26 error-mapping assertions
+        index.ts
+      cms/
+        collections/
+          comments.collection.ts
+        index.ts
+    ui/
+      query.ts    # query builders
+      index.ts    # re-exports query builders
+    __factories__/
+      comment.factory.ts
+      index.ts
+    __contracts__/
+      comments-repository.contract.ts
+    index.ts      # contracts only: types, errors, schemas, IUseCase/IController aliases
+  tests/
+    comments.feature.test.ts   # cross-layer integration (no container)
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  eslint.config.js
 ```
 
-### Step 3: Create `package.json`
+---
+
+## 3. Step-by-Step Walkthrough
+
+### Step 1: Create the package scaffold
+
+```bash
+mkdir -p packages/comments/src/{entities/{models,errors},application/{repositories,use-cases},infrastructure/repositories,interface-adapters/controllers,di,integrations/{api,cms/collections},ui,__factories__,__contracts__}
+mkdir -p packages/comments/tests
+```
+
+### Step 2: `package.json`
 
 ```json
 {
-  "name": "@repo/<feature-name>",
-  "version": "0.0.1",
+  "name": "@repo/comments",
   "private": true,
+  "version": "0.0.0",
   "type": "module",
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./api": {
-      "types": "./dist/integrations/api/index.d.ts",
-      "import": "./dist/integrations/api/index.js"
-    },
-    "./cms": {
-      "types": "./dist/integrations/cms/index.d.ts",
-      "import": "./dist/integrations/cms/index.js"
-    },
-    "./di/bind-production": {
-      "types": "./dist/di/bind-production.d.ts",
-      "import": "./dist/di/bind-production.js"
-    }
+    ".": "./src/index.ts",
+    "./ui": "./src/ui/index.ts",
+    "./cms": "./src/integrations/cms/index.ts",
+    "./api": "./src/integrations/api/index.ts",
+    "./di/bind-production": "./src/di/bind-production.ts"
+  },
+  "scripts": {
+    "build": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@repo/core-shared": "workspace:*",
-    "@repo/core-testing": "workspace:*"
+    "@trpc/server": "^11.0.0",
+    "inversify": "^6.2.0",
+    "payload": "^3.14.0",
+    "reflect-metadata": "^0.2.2",
+    "zod": "^3.24.0"
   },
   "devDependencies": {
-    "@repo/core-typescript": "workspace:*"
+    "@repo/core-eslint": "workspace:*",
+    "@repo/core-testing": "workspace:*",
+    "@repo/core-typescript": "workspace:*",
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "vitest": "^3.1.0"
   }
 }
 ```
 
-### Step 4: Create `tsconfig.json`
+### Step 3: `tsconfig.json`
 
 ```json
 {
@@ -74,12 +169,12 @@ mkdir -p packages/<feature-name>/src/{entities,application/{use-cases,repositori
     "lib": ["ES2022", "DOM"],
     "jsx": "preserve"
   },
-  "include": ["src/**/*"],
+  "include": ["src/**/*", "tests/**/*"],
   "exclude": ["node_modules", "dist"]
 }
 ```
 
-### Step 5: Create `vitest.config.ts`
+### Step 4: `vitest.config.ts`
 
 ```typescript
 import { defineConfig } from "vitest/config";
@@ -89,7 +184,7 @@ export default defineConfig({
   test: {
     environment: "node",
     globals: true,
-    include: ["src/**/*.test.ts"],
+    include: ["src/**/*.test.ts", "tests/**/*.test.ts"],
   },
   resolve: {
     alias: {
@@ -99,28 +194,16 @@ export default defineConfig({
 });
 ```
 
-### Step 6: Add to root `pnpm-workspace.yaml` (if not already included)
-
-```yaml
-packages:
-  - "packages/*"
-```
-
-Run `pnpm install` — the new package is now part of the workspace.
+Run `pnpm install` to link the new package into the workspace.
 
 ---
 
-## Part 2: Build the Layers (Test-First)
+### Step 5: Entity model (RED → GREEN)
 
-The steps below use `comments` as the example feature name. Replace `comments`/`Comment`/`comment` with your feature name throughout.
-
----
-
-### Step 1: Write failing test for entity schema
-
-Create `packages/comments/src/entities/comment.test.ts`:
+Write the test first:
 
 ```typescript
+// src/entities/models/comment.test.ts
 import { describe, expect, it } from "vitest";
 import { commentSchema } from "./comment";
 
@@ -136,34 +219,22 @@ describe("commentSchema", () => {
     expect(result.body).toBe("Great post");
   });
 
-  it("rejects empty body", () => {
+  it("rejects an empty body", () => {
     expect(() =>
-      commentSchema.parse({
-        id: "c-1",
-        articleId: "a-1",
-        body: "",
-        authorId: "u-1",
-        createdAt: new Date(),
-      }),
+      commentSchema.parse({ id: "c-1", articleId: "a-1", body: "", authorId: "u-1", createdAt: new Date() }),
     ).toThrow();
   });
 });
 ```
 
-Run — confirm RED:
-
 ```bash
-pnpm test --filter @repo/comments -- comment.test.ts
-# Error: Cannot find module './comment'
+pnpm test --filter @repo/comments -- comment.test.ts   # RED — module not found
 ```
 
----
-
-### Step 2: Implement entity to pass
-
-Create `packages/comments/src/entities/comment.ts`:
+Implement:
 
 ```typescript
+// src/entities/models/comment.ts
 import { z } from "zod";
 
 export const commentSchema = z.object({
@@ -177,29 +248,83 @@ export const commentSchema = z.object({
 export type Comment = z.infer<typeof commentSchema>;
 ```
 
-Create `packages/comments/src/entities/index.ts`:
-
-```typescript
-export { commentSchema, type Comment } from "./comment.js";
-```
-
-Run — confirm GREEN:
-
 ```bash
-pnpm test --filter @repo/comments -- comment.test.ts
-# PASS  ✓ accepts a valid comment
-# PASS  ✓ rejects empty body
+pnpm test --filter @repo/comments -- comment.test.ts   # GREEN
 ```
 
 ---
 
-### Step 3: Write factory
-
-Create `packages/comments/src/__factories__/comment.factory.ts`:
+### Step 6: Domain errors
 
 ```typescript
+// src/entities/errors/comment.ts
+export class CommentNotFoundError extends Error {
+  constructor(message = "Comment not found", options?: ErrorOptions) {
+    super(message, options);
+    this.name = "CommentNotFoundError";   // required — R6
+  }
+}
+```
+
+```typescript
+// src/entities/errors/common.ts
+export class InputParseError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "InputParseError";        // required — R6
+  }
+}
+```
+
+Test both (colocated `errors.test.ts`):
+
+```typescript
+// src/entities/errors/errors.test.ts
+import { describe, expect, it } from "vitest";
+import { CommentNotFoundError } from "./comment";
+import { InputParseError } from "./common";
+
+describe("CommentNotFoundError", () => {
+  it("has name CommentNotFoundError", () => {
+    const e = new CommentNotFoundError();
+    expect(e.name).toBe("CommentNotFoundError");
+    expect(e).toBeInstanceOf(Error);
+  });
+});
+
+describe("InputParseError", () => {
+  it("has name InputParseError", () => {
+    const e = new InputParseError("bad");
+    expect(e.name).toBe("InputParseError");
+  });
+});
+```
+
+---
+
+### Step 7: Repository interface
+
+Interfaces have no implementation and no test. They are contracts.
+
+```typescript
+// src/application/repositories/comments.repository.interface.ts
+import type { Comment } from "../../entities/models/comment";
+
+export interface ICommentsRepository {
+  getComment(id: string): Promise<Comment | undefined>;
+  getCommentsForArticle(articleId: string): Promise<Comment[]>;
+  createComment(input: Comment): Promise<Comment>;
+}
+```
+
+---
+
+### Step 8: Test factory
+
+```typescript
+// src/__factories__/comment.factory.ts
 import { defineFactory } from "@repo/core-testing/factory";
-import type { Comment } from "../entities/comment.js";
+import type { Comment } from "../entities/models/comment";
 
 export const commentFactory = defineFactory<Comment>(({ sequence }) => ({
   id: `comment-${sequence}`,
@@ -210,141 +335,117 @@ export const commentFactory = defineFactory<Comment>(({ sequence }) => ({
 }));
 ```
 
-Create `packages/comments/src/__factories__/index.ts`:
-
-```typescript
-export { commentFactory } from "./comment.factory.js";
-```
-
 ---
 
-### Step 4: Write failing test for use case (using factory + mock repo)
+### Step 9: Use case — factory function with input/output schemas (RED → GREEN)
 
-The use case depends on `ICommentsRepository`. Write the test before the repository exists; use a hand-rolled inline mock for now.
+Every use case exports:
+- `xInputSchema` — a `z.ZodObject` with `.strict()` (use `z.object({}).strict()` for void inputs)
+- `xOutputSchema` — for non-void use cases
+- `XInput` / `XOutput` types
+- `IXUseCase` alias (`ReturnType<typeof xUseCase>`)
 
-Create `packages/comments/src/application/use-cases/create-comment.use-case.test.ts`:
+The body ends with `xOutputSchema.parse(result)` before returning.
+
+Write the test first (direct injection — no container):
 
 ```typescript
-import { beforeEach, describe, expect, it } from "vitest";
-import { commentFactory } from "../../__factories__/comment.factory";
-import { createCommentUseCase } from "./create-comment.use-case";
-import { commentsContainer } from "../../di/container";
-import { COMMENTS_SYMBOLS } from "../../di/symbols";
-import type { ICommentsRepository } from "../repositories/comments-repository.interface";
-import { MockCommentsRepository } from "../../infrastructure/repositories/mock-comments.repository";
+// src/application/use-cases/get-comments.use-case.test.ts
+import { describe, expect, it } from "vitest";
+import { ZodError } from "zod";
+import {
+  getCommentsUseCase,
+  getCommentsOutputSchema,
+} from "@/application/use-cases/get-comments.use-case";
+import { MockCommentsRepository } from "@/infrastructure/repositories/comments.repository.mock";
+import { commentFactory } from "@/__factories__/comment.factory";
 
-describe("createCommentUseCase", () => {
-  let repo: MockCommentsRepository;
-
-  beforeEach(() => {
-    if (commentsContainer.isBound(COMMENTS_SYMBOLS.ICommentsRepository)) {
-      commentsContainer.unbind(COMMENTS_SYMBOLS.ICommentsRepository);
-    }
-    repo = new MockCommentsRepository();
-    commentsContainer
-      .bind<ICommentsRepository>(COMMENTS_SYMBOLS.ICommentsRepository)
-      .toConstantValue(repo);
+describe("getCommentsUseCase", () => {
+  it("returns comments for an article", async () => {
+    const repo = new MockCommentsRepository();
     commentFactory.reset();
+    await repo.createComment(commentFactory.build({ articleId: "a-1" }));
+
+    const useCase = getCommentsUseCase(repo);
+    const result = await useCase({ articleId: "a-1" });
+    expect(result).toHaveLength(1);
+    expect(result[0]?.articleId).toBe("a-1");
   });
 
-  it("creates a comment with the correct fields", async () => {
-    const result = await createCommentUseCase({
-      articleId: "a-1",
-      body: "Great post",
-      authorId: "u-1",
-    });
-    expect(result.body).toBe("Great post");
-    expect(result.articleId).toBe("a-1");
-    expect(result.authorId).toBe("u-1");
-    expect(typeof result.id).toBe("string");
+  it("returns empty array when no comments exist", async () => {
+    const repo = new MockCommentsRepository();
+    const useCase = getCommentsUseCase(repo);
+    const result = await useCase({ articleId: "missing" });
+    expect(result).toEqual([]);
+  });
+});
+
+// R25 — output validation
+describe("getCommentsUseCase output validation (R25)", () => {
+  it("throws ZodError when the repository returns malformed data", async () => {
+    const repo = new MockCommentsRepository();
+    (repo as unknown as { _comments: unknown[] })._comments.push({ id: 123 });
+
+    const useCase = getCommentsUseCase(repo);
+    await expect(useCase({ articleId: "a-1" })).rejects.toBeInstanceOf(ZodError);
   });
 
-  it("throws when body is empty", async () => {
-    await expect(
-      createCommentUseCase({ articleId: "a-1", body: "", authorId: "u-1" }),
-    ).rejects.toThrow();
+  it("exports getCommentsOutputSchema that validates Comment[]", () => {
+    expect(getCommentsOutputSchema.safeParse([]).success).toBe(true);
   });
 });
 ```
 
-Run — confirm RED:
-
 ```bash
-pnpm test --filter @repo/comments -- create-comment.use-case.test.ts
-# Error: Cannot find module './create-comment.use-case'
+pnpm test --filter @repo/comments -- get-comments.use-case.test.ts   # RED
 ```
 
----
-
-### Step 5: Implement use case to pass
-
-Create `packages/comments/src/di/symbols.ts`:
+Implement:
 
 ```typescript
-export const COMMENTS_SYMBOLS = {
-  ICommentsRepository: Symbol("ICommentsRepository"),
-} as const;
-```
+// src/application/use-cases/get-comments.use-case.ts
+import { z } from "zod";
+import { commentSchema } from "../../entities/models/comment";
+import type { ICommentsRepository } from "../repositories/comments.repository.interface";
 
-Create `packages/comments/src/application/repositories/comments-repository.interface.ts`:
+// ── Input ────────────────────────────────────────────────────────────────
+export const getCommentsInputSchema = z
+  .object({ articleId: z.string() })
+  .strict();
+export type GetCommentsInput = z.infer<typeof getCommentsInputSchema>;
 
-```typescript
-import type { Comment } from "../../entities/comment.js";
+// ── Output ───────────────────────────────────────────────────────────────
+export const getCommentsOutputSchema = z.array(commentSchema);
+export type GetCommentsOutput = z.infer<typeof getCommentsOutputSchema>;
 
-export interface ICommentsRepository {
-  createComment(comment: Comment): Promise<Comment>;
-  getCommentsForArticle(articleId: string): Promise<Comment[]>;
-}
-```
+// ── Use case ─────────────────────────────────────────────────────────────
+export type IGetCommentsUseCase = ReturnType<typeof getCommentsUseCase>;
 
-Create `packages/comments/src/application/use-cases/create-comment.use-case.ts`:
-
-```typescript
-import type { Comment } from "../../entities/comment.js";
-import { commentSchema } from "../../entities/comment.js";
-import { commentsContainer } from "../../di/container.js";
-import { COMMENTS_SYMBOLS } from "../../di/symbols.js";
-import type { ICommentsRepository } from "../repositories/comments-repository.interface.js";
-
-export async function createCommentUseCase(input: {
-  articleId: string;
-  body: string;
-  authorId: string;
-}): Promise<Comment> {
-  const repo = commentsContainer.get<ICommentsRepository>(
-    COMMENTS_SYMBOLS.ICommentsRepository,
-  );
-  const comment: Comment = {
-    id: crypto.randomUUID(),
-    articleId: input.articleId,
-    body: input.body,
-    authorId: input.authorId,
-    createdAt: new Date(),
+export const getCommentsUseCase =
+  (commentsRepository: ICommentsRepository) =>
+  async (input: GetCommentsInput): Promise<GetCommentsOutput> => {
+    const result = await commentsRepository.getCommentsForArticle(input.articleId);
+    return getCommentsOutputSchema.parse(result);
   };
-  commentSchema.parse(comment); // throws on invalid body
-  return repo.createComment(comment);
-}
 ```
 
-Run — confirm GREEN:
-
 ```bash
-pnpm test --filter @repo/comments -- create-comment.use-case.test.ts
-# PASS  ✓ creates a comment with the correct fields
-# PASS  ✓ throws when body is empty
+pnpm test --filter @repo/comments -- get-comments.use-case.test.ts   # GREEN
 ```
 
 ---
 
-### Step 6: Write contract suite
+### Step 10: Mock repository + contract suite (RED → GREEN)
 
-Create `packages/comments/src/__contracts__/comments-repository.contract.ts`:
+Define the contract once and run it against both the mock and the real
+Payload-backed repository:
 
 ```typescript
-import { it, expect, beforeEach } from "vitest";
+// src/__contracts__/comments-repository.contract.ts
+import { beforeEach, expect, it } from "vitest";
 import { defineContractSuite } from "@repo/core-testing/contract";
-import type { ICommentsRepository } from "../application/repositories/comments-repository.interface.js";
-import { commentFactory } from "../__factories__/comment.factory.js";
+import type { ICommentsRepository } from "../application/repositories/comments.repository.interface";
+import { commentFactory } from "../__factories__/comment.factory";
 
 export const commentsRepositoryContract =
   defineContractSuite<ICommentsRepository>(
@@ -357,7 +458,7 @@ export const commentsRepositoryContract =
         repo = await buildSubject();
       });
 
-      it("createComment returns a comment with the correct fields", async () => {
+      it("createComment returns the created comment", async () => {
         const seed = commentFactory.build({ body: "Hello" });
         const created = await repo.createComment(seed);
         expect(typeof created.id).toBe("string");
@@ -365,83 +466,361 @@ export const commentsRepositoryContract =
       });
 
       it("getCommentsForArticle returns comments for the given articleId", async () => {
-        const seed = commentFactory.build({ articleId: "a-1" });
-        await repo.createComment(seed);
+        await repo.createComment(commentFactory.build({ articleId: "a-1" }));
         const results = await repo.getCommentsForArticle("a-1");
         expect(results).toHaveLength(1);
         expect(results[0]?.articleId).toBe("a-1");
       });
 
       it("getCommentsForArticle returns empty array for unknown articleId", async () => {
-        const results = await repo.getCommentsForArticle("no-such-article");
+        const results = await repo.getCommentsForArticle("no-such");
         expect(results).toHaveLength(0);
       });
     },
   );
 ```
 
----
-
-### Step 7: Implement Mock repo, run contract → green
-
-Create `packages/comments/src/infrastructure/repositories/mock-comments.repository.ts`:
+Implement the mock:
 
 ```typescript
+// src/infrastructure/repositories/comments.repository.mock.ts
 import "reflect-metadata";
 import { injectable } from "inversify";
-import type { ICommentsRepository } from "../../application/repositories/comments-repository.interface.js";
-import type { Comment } from "../../entities/comment.js";
+import type { ICommentsRepository } from "../../application/repositories/comments.repository.interface";
+import type { Comment } from "../../entities/models/comment";
 
 @injectable()
 export class MockCommentsRepository implements ICommentsRepository {
-  private _comments: Comment[] = [];
+  _comments: Comment[] = [];
 
-  async createComment(comment: Comment): Promise<Comment> {
-    this._comments.push(comment);
-    return comment;
+  async getComment(id: string): Promise<Comment | undefined> {
+    return this._comments.find((c) => c.id === id);
   }
 
   async getCommentsForArticle(articleId: string): Promise<Comment[]> {
     return this._comments.filter((c) => c.articleId === articleId);
   }
+
+  async createComment(input: Comment): Promise<Comment> {
+    this._comments.push(input);
+    return input;
+  }
 }
 ```
 
-Create `packages/comments/src/infrastructure/repositories/mock-comments.repository.test.ts`:
+Run the contract against the mock:
 
 ```typescript
+// src/infrastructure/repositories/comments.repository.mock.test.ts
 import { describe } from "vitest";
 import { commentsRepositoryContract } from "@/__contracts__/comments-repository.contract";
-import { MockCommentsRepository } from "./mock-comments.repository";
+import { MockCommentsRepository } from "./comments.repository.mock";
 
 describe("MockCommentsRepository", () => {
   commentsRepositoryContract.run(async () => new MockCommentsRepository());
 });
 ```
 
-Run — confirm GREEN:
-
 ```bash
-pnpm test --filter @repo/comments -- mock-comments.repository.test.ts
-# PASS  Contract: ICommentsRepository
-#   ✓ createComment returns a comment with the correct fields
-#   ✓ getCommentsForArticle returns comments for the given articleId
-#   ✓ getCommentsForArticle returns empty array for unknown articleId
+pnpm test --filter @repo/comments -- comments.repository.mock.test.ts   # GREEN
 ```
 
 ---
 
-### Step 8: Implement Payload repo (with vi.mock), run same contract → green
+### Step 11: Controller — `unknown` input + presenter (RED → GREEN)
 
-Create `packages/comments/src/infrastructure/repositories/payload-comments.repository.ts`:
+Controllers import `xInputSchema` from the use-case file — never redefine it.
+Every non-void controller defines a top-level `function presenter` and returns
+`Promise<ReturnType<typeof presenter>>`. Identity is fine.
 
 ```typescript
+// src/interface-adapters/controllers/get-comments.controller.test.ts
+import { describe, expect, it } from "vitest";
+import { getCommentsController } from "@/interface-adapters/controllers/get-comments.controller";
+import { getCommentsUseCase } from "@/application/use-cases/get-comments.use-case";
+import { MockCommentsRepository } from "@/infrastructure/repositories/comments.repository.mock";
+import { InputParseError } from "@/entities/errors/common";
+import { commentFactory } from "@/__factories__/comment.factory";
+
+describe("getCommentsController", () => {
+  it("returns comments on valid input", async () => {
+    const repo = new MockCommentsRepository();
+    commentFactory.reset();
+    await repo.createComment(commentFactory.build({ articleId: "a-1" }));
+
+    const ctrl = getCommentsController(getCommentsUseCase(repo));
+    const result = await ctrl({ articleId: "a-1" });
+    expect(result).toHaveLength(1);
+  });
+
+  it("throws InputParseError when articleId is missing", async () => {
+    const repo = new MockCommentsRepository();
+    const ctrl = getCommentsController(getCommentsUseCase(repo));
+    await expect(ctrl({})).rejects.toBeInstanceOf(InputParseError);
+  });
+
+  it("throws InputParseError on unknown extra fields (strict)", async () => {
+    const repo = new MockCommentsRepository();
+    const ctrl = getCommentsController(getCommentsUseCase(repo));
+    await expect(ctrl({ articleId: "a-1", extra: true })).rejects.toBeInstanceOf(InputParseError);
+  });
+});
+```
+
+```bash
+pnpm test --filter @repo/comments -- get-comments.controller.test.ts   # RED
+```
+
+Implement:
+
+```typescript
+// src/interface-adapters/controllers/get-comments.controller.ts
+import { InputParseError } from "../../entities/errors/common";
+import {
+  getCommentsInputSchema,
+  type GetCommentsOutput,
+  type IGetCommentsUseCase,
+} from "../../application/use-cases/get-comments.use-case";
+
+function presenter(value: GetCommentsOutput) {
+  return value;
+}
+
+export type IGetCommentsController = ReturnType<typeof getCommentsController>;
+
+export const getCommentsController =
+  (getCommentsUseCase: IGetCommentsUseCase) =>
+  async (input: unknown): Promise<ReturnType<typeof presenter>> => {
+    const parsed = getCommentsInputSchema.safeParse(input);
+    if (!parsed.success) {
+      throw new InputParseError("Invalid get-comments input", { cause: parsed.error });
+    }
+    const result = await getCommentsUseCase(parsed.data);
+    return presenter(result);
+  };
+```
+
+```bash
+pnpm test --filter @repo/comments -- get-comments.controller.test.ts   # GREEN
+```
+
+---
+
+### Step 12: DI — symbols, module, container
+
+```typescript
+// src/di/symbols.ts
+export const COMMENTS_SYMBOLS = {
+  ICommentsRepository: Symbol.for("comments:ICommentsRepository"),
+  // Use cases
+  IGetCommentsUseCase: Symbol.for("comments:IGetCommentsUseCase"),
+  // Controllers
+  IGetCommentsController: Symbol.for("comments:IGetCommentsController"),
+} as const;
+```
+
+```typescript
+// src/di/module.ts
+import { ContainerModule, type interfaces } from "inversify";
+import type { ICommentsRepository } from "../application/repositories/comments.repository.interface";
+import { MockCommentsRepository } from "../infrastructure/repositories/comments.repository.mock";
+import {
+  getCommentsUseCase,
+  type IGetCommentsUseCase,
+} from "../application/use-cases/get-comments.use-case";
+import {
+  getCommentsController,
+  type IGetCommentsController,
+} from "../interface-adapters/controllers/get-comments.controller";
+import { COMMENTS_SYMBOLS } from "./symbols";
+
+export const CommentsModule = new ContainerModule((bind: interfaces.Bind) => {
+  bind<ICommentsRepository>(COMMENTS_SYMBOLS.ICommentsRepository).to(MockCommentsRepository);
+
+  bind<IGetCommentsUseCase>(COMMENTS_SYMBOLS.IGetCommentsUseCase).toDynamicValue((ctx) =>
+    getCommentsUseCase(
+      ctx.container.get<ICommentsRepository>(COMMENTS_SYMBOLS.ICommentsRepository),
+    ),
+  );
+
+  bind<IGetCommentsController>(COMMENTS_SYMBOLS.IGetCommentsController).toDynamicValue((ctx) =>
+    getCommentsController(
+      ctx.container.get<IGetCommentsUseCase>(COMMENTS_SYMBOLS.IGetCommentsUseCase),
+    ),
+  );
+});
+```
+
+```typescript
+// src/di/container.ts
+import "reflect-metadata";
+import { Container } from "inversify";
+import { CommentsModule } from "./module";
+
+export const commentsContainer = new Container({ defaultScope: "Singleton" });
+commentsContainer.load(CommentsModule);
+```
+
+Verify DI wiring:
+
+```typescript
+// src/di/container.test.ts
+import { describe, it, expect } from "vitest";
+import { commentsContainer } from "@/di/container";
+import { COMMENTS_SYMBOLS } from "@/di/symbols";
+
+describe("commentsContainer", () => {
+  it("resolves ICommentsRepository", () => {
+    expect(commentsContainer.get(COMMENTS_SYMBOLS.ICommentsRepository)).toBeDefined();
+  });
+
+  it("resolves IGetCommentsUseCase", () => {
+    expect(commentsContainer.get(COMMENTS_SYMBOLS.IGetCommentsUseCase)).toBeDefined();
+  });
+
+  it("resolves IGetCommentsController", () => {
+    expect(commentsContainer.get(COMMENTS_SYMBOLS.IGetCommentsController)).toBeDefined();
+  });
+});
+```
+
+---
+
+### Step 13: `procedures.ts` — feature-scoped error map
+
+Each feature has exactly one `procedures.ts`. It exports an `xProcedure`
+that wraps `defineErrorMiddleware` with the feature's own error constructors.
+`core-shared` provides the factory but knows nothing about feature errors.
+
+```typescript
+// src/integrations/api/procedures.ts
+import { t } from "@repo/core-shared/trpc/init";
+import { defineErrorMiddleware } from "@repo/core-shared/trpc/define-error-middleware";
+import { CommentNotFoundError } from "../../entities/errors/comment";
+import { InputParseError } from "../../entities/errors/common";
+
+export const commentsProcedure = t.procedure.use(
+  defineErrorMiddleware([
+    [InputParseError, "BAD_REQUEST"],
+    [CommentNotFoundError, "NOT_FOUND"],
+  ]),
+);
+```
+
+---
+
+### Step 14: tRPC router (RED → GREEN, includes R26 error-mapping test)
+
+The router:
+- uses `commentsProcedure` (never bare `publicProcedure`)
+- calls `.input(xInputSchema)` importing from the use-case file — never redefines the schema inline
+- resolves controllers from the container
+
+```typescript
+// src/integrations/api/router.test.ts
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { TRPCError } from "@trpc/server";
+import { commentsContainer } from "@/di/container";
+import { CommentsModule } from "@/di/module";
+import { commentsRouter } from "@/integrations/api/router";
+
+describe("commentsRouter", () => {
+  beforeEach(() => {
+    commentsContainer.unbindAll();
+    commentsContainer.load(CommentsModule);
+  });
+  afterEach(() => {
+    commentsContainer.unbindAll();
+  });
+
+  it("exposes getComments procedure", () => {
+    expect(Object.keys(commentsRouter._def.procedures)).toContain("getComments");
+  });
+
+  it("getComments returns empty array by default", async () => {
+    const caller = commentsRouter.createCaller({});
+    expect(await caller.getComments({ articleId: "a-1" })).toEqual([]);
+  });
+});
+
+// R26 — error mapping
+describe("commentsRouter (R26 error mapping)", () => {
+  beforeEach(() => {
+    commentsContainer.unbindAll();
+    commentsContainer.load(CommentsModule);
+  });
+  afterEach(() => {
+    commentsContainer.unbindAll();
+  });
+
+  it("translates zod parse failure → BAD_REQUEST", async () => {
+    const caller = commentsRouter.createCaller({});
+    try {
+      await caller.getComments({} as unknown as { articleId: string });
+      throw new Error("expected throw");
+    } catch (e) {
+      expect(e).toBeInstanceOf(TRPCError);
+      expect((e as TRPCError).code).toBe("BAD_REQUEST");
+    }
+  });
+});
+```
+
+```bash
+pnpm test --filter @repo/comments -- router.test.ts   # RED
+```
+
+Implement:
+
+```typescript
+// src/integrations/api/router.ts
+import { router } from "@repo/core-shared/trpc/init";
+import { commentsContainer } from "../../di/container";
+import { COMMENTS_SYMBOLS } from "../../di/symbols";
+import { getCommentsInputSchema } from "../../application/use-cases/get-comments.use-case";
+import type { IGetCommentsController } from "../../interface-adapters/controllers/get-comments.controller";
+import { commentsProcedure } from "./procedures";
+
+export const commentsRouter = router({
+  getComments: commentsProcedure
+    .input(getCommentsInputSchema)
+    .query(({ input }) => {
+      const ctrl = commentsContainer.get<IGetCommentsController>(
+        COMMENTS_SYMBOLS.IGetCommentsController,
+      );
+      return ctrl(input);
+    }),
+});
+
+export type CommentsRouter = typeof commentsRouter;
+```
+
+```typescript
+// src/integrations/api/index.ts
+export { commentsRouter } from "./router";
+export type { CommentsRouter } from "./router";
+```
+
+```bash
+pnpm test --filter @repo/comments -- router.test.ts   # GREEN
+```
+
+---
+
+### Step 15: Real Payload-backed repository
+
+Implement `CommentsRepository` and run the same contract suite against it
+via a Payload stub (`vi.mock("payload", ...)`). Mirror the pattern from
+`packages/blog/src/infrastructure/repositories/articles.repository.ts`.
+
+```typescript
+// src/infrastructure/repositories/comments.repository.ts
 import "reflect-metadata";
 import { injectable } from "inversify";
 import { getPayload } from "payload";
 import type { SanitizedConfig } from "payload";
-import type { ICommentsRepository } from "../../application/repositories/comments-repository.interface.js";
-import type { Comment } from "../../entities/comment.js";
+import type { ICommentsRepository } from "../../application/repositories/comments.repository.interface";
+import type { Comment } from "../../entities/models/comment";
 
 type PayloadCommentDoc = {
   id: string | number;
@@ -462,21 +841,17 @@ function mapDoc(doc: PayloadCommentDoc): Comment {
 }
 
 @injectable()
-export class PayloadCommentsRepository implements ICommentsRepository {
+export class CommentsRepository implements ICommentsRepository {
   constructor(private config: SanitizedConfig) {}
 
-  async createComment(comment: Comment): Promise<Comment> {
+  async getComment(id: string): Promise<Comment | undefined> {
     const payload = await getPayload({ config: this.config });
-    const created = await payload.create({
-      collection: "comments",
-      data: {
-        articleId: comment.articleId,
-        body: comment.body,
-        author: comment.authorId,
-      } as never,
-      overrideAccess: true,
-    });
-    return mapDoc(created as PayloadCommentDoc);
+    try {
+      const doc = await payload.findByID({ collection: "comments", id, overrideAccess: true });
+      return mapDoc(doc as PayloadCommentDoc);
+    } catch {
+      return undefined;
+    }
   }
 
   async getCommentsForArticle(articleId: string): Promise<Comment[]> {
@@ -488,344 +863,83 @@ export class PayloadCommentsRepository implements ICommentsRepository {
     });
     return result.docs.map((d) => mapDoc(d as PayloadCommentDoc));
   }
+
+  async createComment(input: Comment): Promise<Comment> {
+    const payload = await getPayload({ config: this.config });
+    const created = await payload.create({
+      collection: "comments",
+      data: { articleId: input.articleId, body: input.body, author: input.authorId } as never,
+      overrideAccess: true,
+    });
+    return mapDoc(created as PayloadCommentDoc);
+  }
 }
 ```
 
-Create `packages/comments/src/infrastructure/repositories/payload-comments.repository.test.ts`:
+Contract test with a Payload stub (see
+`packages/blog/src/infrastructure/repositories/articles.repository.test.ts`
+for the full `vi.mock("payload", ...)` pattern):
 
 ```typescript
+// src/infrastructure/repositories/comments.repository.test.ts
 import { describe, vi } from "vitest";
 import { commentsRepositoryContract } from "@/__contracts__/comments-repository.contract";
-import { PayloadCommentsRepository } from "./payload-comments.repository";
-import { stubPayloadConfig } from "@repo/core-testing/payload";
+import { CommentsRepository } from "./comments.repository";
 
 vi.mock("payload", () => ({ getPayload: vi.fn() }));
 
-describe("PayloadCommentsRepository", () => {
+describe("CommentsRepository", () => {
   commentsRepositoryContract.run(async () => {
     const store = new Map<string, Record<string, unknown>>();
     const stub = {
-      create: vi.fn(async ({ data }: { collection: string; data: Record<string, unknown> }) => {
+      findByID: vi.fn(async ({ id }: { id: string }) => store.get(id)),
+      find: vi.fn(async ({ where }: { where?: { articleId?: { equals: string } } }) => {
+        let docs = Array.from(store.values());
+        if (where?.articleId) {
+          docs = docs.filter((d) => d["articleId"] === where.articleId?.equals);
+        }
+        return { docs };
+      }),
+      create: vi.fn(async ({ data }: { data: Record<string, unknown> }) => {
         const doc = { id: `stub-${store.size + 1}`, ...data };
         store.set(String(doc.id), doc);
         return doc;
       }),
-      find: vi.fn(async ({ where }: { collection: string; where?: { articleId?: { equals: string } } }) => {
-        let docs = Array.from(store.values());
-        if (where?.articleId) {
-          docs = docs.filter((d) => d.articleId === where.articleId?.equals);
-        }
-        return { docs };
-      }),
     };
     const { getPayload } = await import("payload");
     (getPayload as ReturnType<typeof vi.fn>).mockResolvedValue(stub);
-    return new PayloadCommentsRepository(stubPayloadConfig);
+    return new CommentsRepository({} as never);
   });
 });
 ```
 
-Run — confirm GREEN:
-
-```bash
-pnpm test --filter @repo/comments -- payload-comments.repository.test.ts
-# PASS  PayloadCommentsRepository > Contract: ICommentsRepository
-#   ✓ createComment returns a comment with the correct fields
-#   ✓ getCommentsForArticle returns comments for the given articleId
-#   ✓ getCommentsForArticle returns empty array for unknown articleId
-```
-
 ---
 
-### Step 9: Write failing controller test
-
-Create `packages/comments/src/interface-adapters/controllers/comments.controller.test.ts`:
+### Step 16: `bind-production.ts`
 
 ```typescript
-import { beforeEach, describe, expect, it } from "vitest";
-import { commentsContainer } from "../../di/container";
-import { COMMENTS_SYMBOLS } from "../../di/symbols";
-import { MockCommentsRepository } from "../../infrastructure/repositories/mock-comments.repository";
-import type { ICommentsRepository } from "../../application/repositories/comments-repository.interface";
-import { InputParseError } from "../../entities/errors";
-import { createCommentController } from "./comments.controller";
+// src/di/bind-production.ts
+import type { SanitizedConfig } from "payload";
+import { commentsContainer } from "./container";
+import { COMMENTS_SYMBOLS } from "./symbols";
+import { CommentsRepository } from "../infrastructure/repositories/comments.repository";
 
-describe("comments controller", () => {
-  beforeEach(() => {
-    if (commentsContainer.isBound(COMMENTS_SYMBOLS.ICommentsRepository)) {
-      commentsContainer.unbind(COMMENTS_SYMBOLS.ICommentsRepository);
-    }
-    commentsContainer
-      .bind<ICommentsRepository>(COMMENTS_SYMBOLS.ICommentsRepository)
-      .toConstantValue(new MockCommentsRepository());
-  });
-
-  describe("createCommentController", () => {
-    it("creates a comment on valid input", async () => {
-      const result = await createCommentController({
-        articleId: "a-1",
-        body: "Nice article",
-        authorId: "u-1",
-      });
-      expect(result.body).toBe("Nice article");
-    });
-
-    it("throws InputParseError when body is missing", async () => {
-      await expect(
-        createCommentController({ articleId: "a-1", authorId: "u-1" }),
-      ).rejects.toBeInstanceOf(InputParseError);
-    });
-  });
-});
-```
-
-Run — confirm RED:
-
-```bash
-pnpm test --filter @repo/comments -- comments.controller.test.ts
-# Error: Cannot find module './comments.controller'
-```
-
----
-
-### Step 10: Implement controller
-
-Create `packages/comments/src/entities/errors.ts`:
-
-```typescript
-export class InputParseError extends Error {
-  constructor(message: string, options?: { cause?: unknown }) {
-    super(message, options);
-    this.name = "InputParseError";
+export function bindProductionComments(config: SanitizedConfig): void {
+  if (commentsContainer.isBound(COMMENTS_SYMBOLS.ICommentsRepository)) {
+    commentsContainer.unbind(COMMENTS_SYMBOLS.ICommentsRepository);
   }
+  commentsContainer
+    .bind(COMMENTS_SYMBOLS.ICommentsRepository)
+    .toConstantValue(new CommentsRepository(config));
 }
 ```
 
-Create `packages/comments/src/interface-adapters/controllers/comments.controller.ts`:
-
-```typescript
-import { z } from "zod";
-import { InputParseError } from "../../entities/errors.js";
-import { createCommentUseCase } from "../../application/use-cases/create-comment.use-case.js";
-import type { Comment } from "../../entities/comment.js";
-
-const createInputSchema = z.object({
-  articleId: z.string().min(1),
-  body: z.string().min(1),
-  authorId: z.string().min(1),
-});
-
-export async function createCommentController(
-  input: Partial<z.infer<typeof createInputSchema>>,
-): Promise<Comment> {
-  const parsed = createInputSchema.safeParse(input);
-  if (!parsed.success) {
-    throw new InputParseError("Invalid create-comment input", {
-      cause: parsed.error,
-    });
-  }
-  return createCommentUseCase(parsed.data);
-}
-```
-
-Run — confirm GREEN:
-
-```bash
-pnpm test --filter @repo/comments -- comments.controller.test.ts
-# PASS  ✓ creates a comment on valid input
-# PASS  ✓ throws InputParseError when body is missing
-```
-
 ---
 
-### Step 11: Write failing tRPC integration test
-
-Create `packages/comments/src/integrations/api/router.test.ts`:
-
-```typescript
-import { beforeEach, describe, expect, it } from "vitest";
-import { commentsContainer } from "../../di/container";
-import { COMMENTS_SYMBOLS } from "../../di/symbols";
-import { MockCommentsRepository } from "../../infrastructure/repositories/mock-comments.repository";
-import type { ICommentsRepository } from "../../application/repositories/comments-repository.interface";
-import { commentsRouter } from "./router";
-
-describe("commentsRouter", () => {
-  beforeEach(() => {
-    if (commentsContainer.isBound(COMMENTS_SYMBOLS.ICommentsRepository)) {
-      commentsContainer.unbind(COMMENTS_SYMBOLS.ICommentsRepository);
-    }
-    commentsContainer
-      .bind<ICommentsRepository>(COMMENTS_SYMBOLS.ICommentsRepository)
-      .toConstantValue(new MockCommentsRepository());
-  });
-
-  it("exposes createComment procedure", () => {
-    const procedureNames = Object.keys(commentsRouter._def.procedures);
-    expect(procedureNames).toContain("createComment");
-  });
-
-  it("createComment creates and returns the comment", async () => {
-    const caller = commentsRouter.createCaller({});
-    const result = await caller.createComment({
-      articleId: "a-1",
-      body: "Hello",
-      authorId: "u-1",
-    });
-    expect(result.body).toBe("Hello");
-  });
-});
-```
-
-Run — confirm RED:
-
-```bash
-pnpm test --filter @repo/comments -- router.test.ts
-# Error: Cannot find module './router'
-```
-
----
-
-### Step 12: Wire router
-
-Create `packages/comments/src/di/container.ts`:
-
-```typescript
-import "reflect-metadata";
-import { Container } from "inversify";
-import { MockCommentsRepository } from "../infrastructure/repositories/mock-comments.repository.js";
-import { COMMENTS_SYMBOLS } from "./symbols.js";
-import type { ICommentsRepository } from "../application/repositories/comments-repository.interface.js";
-
-export const commentsContainer = new Container({ defaultScope: "Singleton" });
-commentsContainer
-  .bind<ICommentsRepository>(COMMENTS_SYMBOLS.ICommentsRepository)
-  .to(MockCommentsRepository);
-```
-
-Create `packages/comments/src/integrations/api/router.ts`:
-
-```typescript
-import { z } from "zod";
-import { t } from "@repo/core-shared/trpc/init";
-import { createCommentController } from "../../interface-adapters/controllers/comments.controller.js";
-
-export const commentsRouter = t.router({
-  createComment: t.procedure
-    .input(
-      z.object({
-        articleId: z.string().min(1),
-        body: z.string().min(1),
-        authorId: z.string().min(1),
-      }),
-    )
-    .mutation(async ({ input }) => {
-      return createCommentController(input);
-    }),
-});
-```
-
-Create `packages/comments/src/integrations/api/index.ts`:
-
-```typescript
-export { commentsRouter } from "./router.js";
-```
-
-Run — confirm GREEN:
-
-```bash
-pnpm test --filter @repo/comments -- router.test.ts
-# PASS  ✓ exposes createComment procedure
-# PASS  ✓ createComment creates and returns the comment
-```
-
----
-
-### Step 13: (UI optional) Write failing component test with renderWithProviders
-
-Create `packages/comments/src/ui/CommentForm.test.tsx`:
-
-```typescript
-import { describe, expect, it } from "vitest";
-import { renderWithProviders } from "@repo/core-testing/react";
-import { CommentForm } from "./CommentForm";
-
-describe("CommentForm", () => {
-  it("renders a textarea and submit button", () => {
-    const screen = renderWithProviders(
-      <CommentForm articleId="a-1" authorId="u-1" onSuccess={() => {}} />,
-    );
-    expect(screen.getByRole("textbox")).toBeInTheDocument();
-    expect(screen.getByRole("button", { name: /post comment/i })).toBeInTheDocument();
-  });
-});
-```
-
-Run — confirm RED:
-
-```bash
-pnpm test --filter @repo/comments -- CommentForm.test.tsx
-# Error: Cannot find module './CommentForm'
-```
-
----
-
-### Step 14: Implement component
-
-Create `packages/comments/src/ui/CommentForm.tsx`:
-
-```typescript
-import { useState } from "react";
-
-interface CommentFormProps {
-  articleId: string;
-  authorId: string;
-  onSuccess: () => void;
-}
-
-export function CommentForm({ articleId, authorId, onSuccess }: CommentFormProps) {
-  const [body, setBody] = useState("");
-
-  async function handleSubmit(e: React.FormEvent) {
-    e.preventDefault();
-    // Wire to tRPC mutation in a real implementation
-    onSuccess();
-  }
-
-  return (
-    <form onSubmit={handleSubmit}>
-      <textarea
-        value={body}
-        onChange={(e) => setBody(e.target.value)}
-        placeholder="Write a comment..."
-      />
-      <button type="submit">Post comment</button>
-    </form>
-  );
-}
-```
-
-Run — confirm GREEN:
-
-```bash
-pnpm test --filter @repo/comments -- CommentForm.test.tsx
-# PASS  ✓ renders a textarea and submit button
-```
-
----
-
-### Step 15: Wire into core-api / core-cms, run typecheck + lint + boundaries
-
-Create `packages/comments/src/index.ts`:
-
-```typescript
-export { commentSchema, type Comment } from "./entities/index.js";
-export { commentsContainer } from "./di/container.js";
-```
-
-Create `packages/comments/src/integrations/cms/collections/comments.collection.ts`:
+### Step 17: Payload collection
 
 ```typescript
+// src/integrations/cms/collections/comments.collection.ts
 import type { CollectionConfig } from "payload";
 
 export const comments: CollectionConfig = {
@@ -839,50 +953,85 @@ export const comments: CollectionConfig = {
 };
 ```
 
-Create `packages/comments/src/integrations/cms/index.ts`:
-
 ```typescript
-export { comments } from "./collections/comments.collection.js";
+// src/integrations/cms/index.ts
+export { comments } from "./collections/comments.collection";
 ```
 
-Create `packages/comments/src/di/bind-production.ts`:
+---
+
+### Step 18: Public API — `src/index.ts` and `src/ui/index.ts`
+
+The feature root exports contracts only (types, errors, schemas, type
+aliases). UI artifacts live behind `./ui`.
 
 ```typescript
-import type { Container } from "inversify";
-import type { SanitizedConfig } from "payload";
-import { PayloadCommentsRepository } from "../infrastructure/repositories/payload-comments.repository.js";
-import { COMMENTS_SYMBOLS } from "./symbols.js";
-import type { ICommentsRepository } from "../application/repositories/comments-repository.interface.js";
+// src/index.ts
+export type { Comment } from "./entities/models/comment";
+export { CommentNotFoundError } from "./entities/errors/comment";
+export { InputParseError } from "./entities/errors/common";
+export type { CommentsRouter } from "./integrations/api/router";
 
-export async function bindProductionComments(
-  container: Container,
-  config: SanitizedConfig,
-): Promise<void> {
-  const repo = new PayloadCommentsRepository(config);
-  container.rebind<ICommentsRepository>(COMMENTS_SYMBOLS.ICommentsRepository).toConstantValue(repo);
+// Use case schemas + types
+export {
+  getCommentsInputSchema,
+  getCommentsOutputSchema,
+  type GetCommentsInput,
+  type GetCommentsOutput,
+  type IGetCommentsUseCase,
+} from "./application/use-cases/get-comments.use-case";
+
+// Controller type aliases
+export type { IGetCommentsController } from "./interface-adapters/controllers/get-comments.controller";
+```
+
+```typescript
+// src/ui/query.ts
+type TrpcClient = {
+  comments: {
+    getComments: {
+      queryOptions: (input: { articleId: string }) => unknown;
+    };
+  };
+};
+
+export function getCommentsQuery(client: TrpcClient, articleId: string) {
+  return client.comments.getComments.queryOptions({ articleId });
 }
 ```
 
-**Wire into `core-api`** — edit `packages/core-api/src/routers.ts`:
+```typescript
+// src/ui/index.ts
+export { getCommentsQuery } from "./query";
+```
+
+---
+
+### Step 19: Wire into `core-api` and `core-cms`
+
+These are composition packages — this is the only time a feature-level
+symbol crosses a package boundary.
+
+**`packages/core-api/src/root.ts`** (or equivalent aggregator):
 
 ```typescript
 import { commentsRouter } from "@repo/comments/api";
 
 export const appRouter = t.router({
   comments: commentsRouter,
-  // ... other feature routers
+  // ... other features
 });
 ```
 
-**Wire into `core-cms`** — edit `packages/core-cms/src/collections/index.ts`:
+**`packages/core-cms/src/collections/index.ts`** (or equivalent):
 
 ```typescript
 import { comments } from "@repo/comments/cms";
 
-export const collections = [comments];
+export const collections = [...existingCollections, comments];
 ```
 
-**Add path aliases** — edit `tsconfig.base.json`:
+Add path aliases to `tsconfig.base.json`:
 
 ```json
 {
@@ -890,6 +1039,7 @@ export const collections = [comments];
     "paths": {
       "@repo/comments": ["packages/comments/src/index.ts"],
       "@repo/comments/api": ["packages/comments/src/integrations/api/index.ts"],
+      "@repo/comments/ui": ["packages/comments/src/ui/index.ts"],
       "@repo/comments/cms": ["packages/comments/src/integrations/cms/index.ts"],
       "@repo/comments/di/bind-production": ["packages/comments/src/di/bind-production.ts"]
     }
@@ -897,7 +1047,27 @@ export const collections = [comments];
 }
 ```
 
-**Validate everything passes:**
+Also add `@repo/comments: workspace:*` to `packages/core-api/package.json`
+and `packages/core-cms/package.json` dependencies.
+
+---
+
+### Step 20: App bootstrap
+
+Each app calls `bindProduction*` per feature at startup to swap mock
+implementations for real Payload-backed ones. For example, in
+`apps/web-next/src/server/bind-production.ts`:
+
+```typescript
+import { bindProductionComments } from "@repo/comments/di/bind-production";
+
+// called once at startup with the resolved Payload config
+await bindProductionComments(resolvedConfig);
+```
+
+---
+
+### Step 21: Final validation
 
 ```bash
 pnpm install
@@ -907,132 +1077,91 @@ pnpm lint --filter @repo/comments
 pnpm turbo boundaries
 ```
 
----
-
-## Part 3: Integrate with Core
-
-### Wire into app bootstrap
-
-In `apps/web-next/src/app/layout.tsx` or equivalent:
-
-```typescript
-import { bindProductionComments } from "@repo/comments/di/bind-production";
-import { payloadConfig } from "@repo/core-cms";
-
-// At app boot:
-await bindProductionComments(commentsContainer, payloadConfig);
-```
-
-### Final test, typecheck, build
-
-```bash
-pnpm install
-pnpm typecheck --filter @repo/comments
-pnpm test --filter @repo/comments
-pnpm build --filter @repo/comments
-```
+All must pass before shipping.
 
 ---
 
-## Part 4: Modifying an Existing Feature
+## 4. Configuration Checklist
 
-Example: Adding an `unapprove-article` procedure to `packages/blog`.
-
-### 1. Write the failing test first
-
-Create or extend the use case test:
-
-```typescript
-// packages/blog/src/application/use-cases/unapprove-article.use-case.test.ts
-import { beforeEach, describe, expect, it } from "vitest";
-import { blogContainer } from "../../di/container";
-import { BLOG_SYMBOLS } from "../../di/symbols";
-import { MockArticlesRepository } from "../../infrastructure/repositories/mock-articles.repository";
-import { articleFactory } from "../../__factories__/article.factory";
-import { unapproveArticleUseCase } from "./unapprove-article.use-case";
-
-describe("unapproveArticleUseCase", () => {
-  let repo: MockArticlesRepository;
-
-  beforeEach(() => {
-    if (blogContainer.isBound(BLOG_SYMBOLS.IArticlesRepository)) {
-      blogContainer.unbind(BLOG_SYMBOLS.IArticlesRepository);
-    }
-    repo = new MockArticlesRepository();
-    blogContainer.bind(BLOG_SYMBOLS.IArticlesRepository).toConstantValue(repo);
-    articleFactory.reset();
-  });
-
-  it("sets article status to draft", async () => {
-    const article = articleFactory.build({ status: "published" });
-    await repo.createArticle(article);
-    const result = await unapproveArticleUseCase(article.id);
-    expect(result?.status).toBe("draft");
-  });
-});
-```
-
-Run — confirm RED. Then implement.
-
-### 2. Implement use case
-
-Create `packages/blog/src/application/use-cases/unapprove-article.use-case.ts`:
-
-```typescript
-import type { Article } from "../../entities/article.js";
-import { blogContainer } from "../../di/container.js";
-import { BLOG_SYMBOLS } from "../../di/symbols.js";
-import type { IArticlesRepository } from "../repositories/articles-repository.interface.js";
-
-export async function unapproveArticleUseCase(
-  articleId: string,
-): Promise<Article | undefined> {
-  const repo = blogContainer.get<IArticlesRepository>(
-    BLOG_SYMBOLS.IArticlesRepository,
-  );
-  return repo.updateArticle(articleId, { status: "draft" });
-}
-```
-
-Run — confirm GREEN.
-
-### 3. Add tRPC procedure
-
-Edit `packages/blog/src/integrations/api/router.ts`:
-
-```typescript
-export const blogRouter = t.router({
-  // ... existing
-  unapproveArticle: t.procedure
-    .input(z.object({ articleId: z.string() }))
-    .mutation(async ({ input }) => {
-      return unapproveArticleUseCase(input.articleId);
-    }),
-});
-```
-
-### 4. Test and lint
-
-```bash
-pnpm test --filter @repo/blog
-pnpm lint --filter @repo/blog
-```
+| File | Key items |
+|---|---|
+| `package.json` | `"type": "module"`; exports map with `.`, `./ui`, `./api`, `./cms`, `./di/bind-production`; `@repo/core-shared`, `inversify`, `zod`, `payload` in deps |
+| `tsconfig.json` | `"rootDir": "."` (covers both `src/` and `tests/`); `"outDir": "dist"` |
+| `vitest.config.ts` | `resolve.alias: { "@": path.resolve(__dirname, "./src") }` |
+| `eslint.config.js` | extends `@repo/core-eslint`; tag set to `"feature"` in Turborepo `turbo.json` |
+| `tsconfig.base.json` | path aliases for every subpath export |
+| `turbo.json` | feature package must appear (or be glob-matched) in the workspace graph |
 
 ---
 
-## Done Criteria
+## 5. Common Pitfalls
 
-- Package created with correct folder structure
-- `entities/` has Zod schemas with unit tests (RED then GREEN)
-- `__factories__/` has a factory for each entity
-- `application/use-cases/` has business logic tested with mock repos
-- `__contracts__/` has contract suites for each repository interface
-- `infrastructure/repositories/` has mock and (if Payload) Payload implementations, both passing the contract suite
-- `interface-adapters/controllers/` has input-parsing controllers with tests
-- `integrations/api/` exports a tRPC router with integration tests
-- `di/container.ts` wires everything; `di/bind-production.ts` binds Payload repo
-- Feature exported from `core-api` router aggregator
-- Feature collections exported from `core-cms`
-- Path aliases added to `tsconfig.base.json`
-- `pnpm install && pnpm typecheck && pnpm test && pnpm lint` all pass
-- ESLint boundaries pass (feature only imports `core-*` and tooling)
+1. **Forgetting `this.name` in domain error constructors.** Without it,
+   `instanceof` checks in `defineErrorMiddleware` still work, but
+   serialized stack traces label the error as `"Error"` instead of
+   `"CommentNotFoundError"`, making debugging significantly harder. Set
+   `this.name = "CommentNotFoundError"` in every domain error and
+   `InputParseError` constructor (ADR-013 R6).
+
+2. **Redefining the input schema in the controller.** The controller must
+   `import { xInputSchema } from "../../application/use-cases/x.use-case"`.
+   A local `const inputSchema = z.object({...})` in the controller
+   silently diverges from the tRPC procedure's schema — this was the exact
+   bug Plans 8 and 9 fixed. One schema, one source.
+
+3. **Typing controller input as `Partial<...>` or `z.infer<...>`** instead of
+   `unknown`. The controller receives unvalidated data from an external
+   boundary; `unknown` is the correct type. Using a TypeScript type here
+   bypasses the runtime `safeParse` guard entirely when callers are
+   within the same TypeScript project.
+
+4. **Skipping the presenter on a non-void controller.** Every non-void
+   controller must define `function presenter(value: XOutput)` and return
+   `Promise<ReturnType<typeof presenter>>`. Identity (`return value`) is
+   fine, but the function must exist. Skipping it makes adding a view
+   transform later a structural change instead of a one-line edit
+   (ADR-013 R11).
+
+5. **Adding feature error classes to `core-shared`.** `core-shared` must
+   stay boundary-clean — it provides `defineErrorMiddleware` but knows
+   nothing about `CommentNotFoundError` or any other feature error class.
+   Feature packages pass their own constructors to `defineErrorMiddleware`
+   in their own `procedures.ts`. Adding feature errors to `core-shared`
+   violates the `feature → core` dependency direction enforced by ESLint
+   boundaries and Turborepo.
+
+6. **Re-exporting query builders from the feature root `src/index.ts`.**
+   Query builders import React Query, which is a UI concern. The feature
+   root (`.`) is a contract-only export consumed by apps, other features,
+   and server-side code. UI artifacts go behind `./ui` (ADR-013 §Decision
+   point 4). Apps import from `@repo/comments/ui`, not `@repo/comments`.
+
+7. **Forgetting to add the `./ui` subpath to `package.json`.** If
+   `src/ui/index.ts` exists but the `"./ui"` entry is missing from the
+   `exports` map, TypeScript resolves the import in workspace mode but
+   the build fails. Always keep the exports map in sync with
+   `tsconfig.base.json` path aliases.
+
+---
+
+## 6. Cross-References
+
+- **ADR-012** (`docs/decisions/adr-012-lazar-conformance.md`) — factory-function
+  use cases and controllers, entity layout, file naming, one-controller-per-use-case,
+  `.toDynamicValue()` DI bindings, direct injection in tests.
+- **ADR-013** (`docs/decisions/adr-013-input-output-unification.md`) — use-case
+  file as single source for `xInputSchema` + `xOutputSchema`; presenter pattern;
+  per-feature `procedures.ts` error map; public surface split (`./` vs `./ui`).
+- **Refactor log — Plan 8** (`docs/superpowers/refactor-logs/2026-05-05-lazar-pattern-conformance.md`) —
+  file-by-file inventory of every rename, split, and pattern change applied
+  to all existing features.
+- **Refactor log — Plan 9** (`docs/superpowers/refactor-logs/2026-05-06-input-output-unification.md`) —
+  inventory of schema additions, presenter additions, `procedures.ts` additions,
+  and `./ui` subpath additions across all 5 features.
+- **CLAUDE.md** (root) — Key Conventions section is the quick-reference
+  summary; this guide is the authoritative walkthrough.
+- **Architecture overview** (`docs/architecture/overview.md`) — canonical
+  data-flow diagram showing the full request path from React component
+  through tRPC, controller, use case, repository, and back.
+- **TDD Workflow** (`docs/guides/tdd-workflow.md`) — required reading on
+  RED → GREEN discipline, direct factory injection, and R25/R26 test obligations.
diff --git a/docs/guides/tdd-workflow.md b/docs/guides/tdd-workflow.md
index 1501980..87b4dcc 100644
--- a/docs/guides/tdd-workflow.md
+++ b/docs/guides/tdd-workflow.md
@@ -10,43 +10,37 @@ TDD in this monorepo is not dogma — it is a feedback mechanism. Writing a test
 
 **Step 1 — Write the failing test (RED)**
 
-`packages/blog/src/application/repositories/articles-repository.interface.ts` defines the `getArticleBySlug(slug: string): Promise<Article | undefined>` method. Before implementing anything, write a test that calls it through the use case or controller.
+`packages/blog/src/application/repositories/articles.repository.interface.ts` defines `getArticleBySlug(slug: string): Promise<Article | undefined>`. Before implementing anything, write a controller test that constructs the dependencies directly — no container rebinding.
 
 ```typescript
-// packages/blog/src/interface-adapters/controllers/articles.controller.test.ts
-import { beforeEach, describe, expect, it } from "vitest";
-import { blogContainer } from "../../di/container";
-import { BLOG_SYMBOLS } from "../../di/symbols";
-import { MockArticlesRepository } from "../../infrastructure/repositories/mock-articles.repository";
-import type { IArticlesRepository } from "../../application/repositories/articles-repository.interface";
-import { articleFactory } from "../../__factories__/article.factory";
-import { getArticleBySlugController } from "./articles.controller";
+// packages/blog/src/interface-adapters/controllers/get-article-by-slug.controller.test.ts
+import { describe, expect, it } from "vitest";
+import { getArticleBySlugController } from "@/interface-adapters/controllers/get-article-by-slug.controller";
+import { getArticleBySlugUseCase } from "@/application/use-cases/get-article-by-slug.use-case";
+import { MockArticlesRepository } from "@/infrastructure/repositories/articles.repository.mock";
+import { articleFactory } from "@/__factories__/article.factory";
 
 describe("getArticleBySlugController", () => {
-  let repo: MockArticlesRepository;
-
-  beforeEach(() => {
-    if (blogContainer.isBound(BLOG_SYMBOLS.IArticlesRepository)) {
-      blogContainer.unbind(BLOG_SYMBOLS.IArticlesRepository);
-    }
-    repo = new MockArticlesRepository();
-    blogContainer
-      .bind<IArticlesRepository>(BLOG_SYMBOLS.IArticlesRepository)
-      .toConstantValue(repo);
-    articleFactory.reset();
-  });
-
   it("returns the article when the slug exists", async () => {
-    await repo.createArticle(
-      articleFactory.build({ slug: "hello-world", authorId: "u1" }),
-    );
-    const result = await getArticleBySlugController({ slug: "hello-world" });
+    const repo = new MockArticlesRepository();
+    articleFactory.reset();
+    await repo.createArticle(articleFactory.build({ slug: "hello-world", authorId: "u1" }));
+
+    const useCase = getArticleBySlugUseCase(repo);
+    const controller = getArticleBySlugController(useCase);
+
+    const result = await controller({ slug: "hello-world" });
     expect(result?.slug).toBe("hello-world");
   });
 
-  it("returns undefined for a missing slug", async () => {
-    const result = await getArticleBySlugController({ slug: "no-such-slug" });
-    expect(result).toBeUndefined();
+  it("throws ArticleNotFoundError for a missing slug", async () => {
+    const repo = new MockArticlesRepository();
+    const useCase = getArticleBySlugUseCase(repo);
+    const controller = getArticleBySlugController(useCase);
+
+    await expect(
+      controller({ slug: "no-such-slug" }),
+    ).rejects.toBeInstanceOf(ArticleNotFoundError);
   });
 });
 ```
@@ -54,9 +48,9 @@ describe("getArticleBySlugController", () => {
 **Run it — confirm RED:**
 
 ```
-pnpm test --filter @repo/blog -- articles.controller.test.ts
+pnpm test --filter @repo/blog -- get-article-by-slug.controller.test.ts
 
- FAIL  src/interface-adapters/controllers/articles.controller.test.ts
+ FAIL  src/interface-adapters/controllers/get-article-by-slug.controller.test.ts
   getArticleBySlugController
     × returns the article when the slug exists
       AssertionError: expected undefined to equal "hello-world"
@@ -65,37 +59,40 @@ pnpm test --filter @repo/blog -- articles.controller.test.ts
 **Step 2 — Write the minimal implementation (GREEN)**
 
 ```typescript
-// packages/blog/src/interface-adapters/controllers/articles.controller.ts
-export async function getArticleBySlugController(input: {
-  slug: string;
-}): Promise<Article | undefined> {
-  const parsed = getBySlugInputSchema.safeParse(input);
-  if (!parsed.success) {
-    throw new InputParseError("Invalid get-article-by-slug input", {
-      cause: parsed.error,
-    });
-  }
-  const repo = blogContainer.get<IArticlesRepository>(
-    BLOG_SYMBOLS.IArticlesRepository,
-  );
-  return repo.getArticleBySlug(parsed.data.slug);
+// packages/blog/src/interface-adapters/controllers/get-article-by-slug.controller.ts
+import type { IGetArticleBySlugUseCase, GetArticleBySlugOutput } from
+  "../application/use-cases/get-article-by-slug.use-case";
+import { getArticleBySlugInputSchema } from "../application/use-cases/get-article-by-slug.use-case";
+import { InputParseError } from "../entities/errors/common";
+
+function presenter(value: GetArticleBySlugOutput) { return value; }
+
+export function getArticleBySlugController(useCase: IGetArticleBySlugUseCase) {
+  return async (input: unknown): Promise<ReturnType<typeof presenter>> => {
+    const parsed = getArticleBySlugInputSchema.safeParse(input);
+    if (!parsed.success)
+      throw new InputParseError("Invalid get-article-by-slug input", { cause: parsed.error });
+    return presenter(await useCase(parsed.data));
+  };
 }
+
+export type IGetArticleBySlugController = ReturnType<typeof getArticleBySlugController>;
 ```
 
 **Run again — confirm GREEN:**
 
 ```
-pnpm test --filter @repo/blog -- articles.controller.test.ts
+pnpm test --filter @repo/blog -- get-article-by-slug.controller.test.ts
 
- PASS  src/interface-adapters/controllers/articles.controller.test.ts
+ PASS  src/interface-adapters/controllers/get-article-by-slug.controller.test.ts
   getArticleBySlugController
     ✓ returns the article when the slug exists
-    ✓ returns undefined for a missing slug
+    ✓ throws ArticleNotFoundError for a missing slug
 ```
 
 **Step 3 — Refactor**
 
-Extract the schema parse + error throw into a helper if the same pattern appears in three controllers:
+If the same `safeParse` + `InputParseError` throw pattern appears in multiple controllers, extract a shared `parseOrThrow` helper:
 
 ```typescript
 function parseOrThrow<T>(schema: z.ZodSchema<T>, raw: unknown, msg: string): T {
@@ -135,11 +132,10 @@ describe("getArticlesUseCase", () => {
 });
 
 // Controller
-describe("articles controller", () => {
-  describe("createArticleController", () => {
-    it("creates an article on valid input", async () => { ... });
-    it("throws InputParseError on missing title", async () => { ... });
-  });
+describe("getArticleBySlugController", () => {
+  it("returns the article when the slug exists", async () => { ... });
+  it("throws ArticleNotFoundError for a missing slug", async () => { ... });
+  it("throws InputParseError on invalid input shape", async () => { ... });
 });
 ```
 
@@ -160,11 +156,14 @@ Every test body has three clearly separated sections. No logic between Act and A
 ```typescript
 it("filters by status when status is provided", async () => {
   // Arrange
+  const repo = new MockArticlesRepository();
+  articleFactory.reset();
   await repo.createArticle(articleFactory.build({ status: "draft" }));
   await repo.createArticle(articleFactory.build({ status: "published" }));
+  const useCase = getArticlesUseCase(repo);
 
   // Act
-  const result = await getArticlesUseCase({ status: "published" });
+  const result = await useCase({ status: "published" });
 
   // Assert
   expect(result).toHaveLength(1);
@@ -199,8 +198,18 @@ Is it a pure function (entity validation, slug generation)?
   → No mock. Pass inputs, assert output.
 
 Is it a use case test?
-  → Rebind the repository at DI level using blogContainer.unbind / .bind.
-  → Use MockArticlesRepository, not a vi.fn() spy.
+  → Construct new MockXRepository() and inject directly into the factory:
+      const repo = new MockXRepository();
+      const useCase = xUseCase(repo);
+      await useCase(input);
+  → No container unbind/rebind.
+
+Is it a controller test?
+  → Construct the mock repo, build the use case, inject into the controller factory:
+      const repo = new MockXRepository();
+      const useCase = xUseCase(repo);
+      const controller = xController(useCase);
+      await controller(input);
 
 Is it a repository test (Payload implementation)?
   → vi.mock('payload') at the top of the file.
@@ -212,8 +221,9 @@ Is it a React component that fetches data?
   → Do not mock fetch or XMLHttpRequest directly.
 
 Is it a route handler / tRPC procedure?
-  → Mock at the boundary only (the repository). Call the procedure through
-    blogRouter.createCaller({}) — do not mock the router internals.
+  → Use blogContainer / xContainer with unbindAll + load(XModule) in
+    beforeEach/afterEach. Call the procedure through xRouter.createCaller({})
+    — do not mock the router internals.
 ```
 
 The rule: mock the thing your layer depends on, never the thing under test.
@@ -224,7 +234,7 @@ The rule: mock the thing your layer depends on, never the thing under test.
 
 | Layer | Tool | Target ratio | Location pattern |
 |---|---|---|---|
-| Entity (schema, type guards) | Vitest | Highest — every entity | `src/entities/*.test.ts` |
+| Entity (schema, type guards) | Vitest | Highest — every entity | `src/entities/models/*.test.ts` |
 | Use case (business logic) | Vitest + mock repo | High — every use case | `src/application/use-cases/*.test.ts` |
 | Controller (input parsing) | Vitest + mock repo | High — every controller | `src/interface-adapters/controllers/*.test.ts` |
 | Repository contract | Vitest + contract suite | One per impl | `src/infrastructure/repositories/*.test.ts` |
@@ -299,7 +309,7 @@ articleFactory.build({ slug: "my-slug", status: "published" })
 }
 ```
 
-Always call `factory.reset()` in `beforeEach` to restart the sequence counter.
+Always call `factory.reset()` in `beforeEach` (or inline before use) to restart the sequence counter.
 
 **When to hand-craft**
 
@@ -311,7 +321,7 @@ Hand-craft objects only when testing boundary values (empty string, max-length t
 
 ```typescript
 import { defineFactory } from "@repo/core-testing/factory";
-import type { Comment } from "../entities/comment.js";
+import type { Comment } from "../entities/models/comment";
 
 export const commentFactory = defineFactory<Comment>(({ sequence }) => ({
   id: `comment-${sequence}`,
@@ -323,13 +333,181 @@ export const commentFactory = defineFactory<Comment>(({ sequence }) => ({
 ```
 
 2. Re-export from `packages/<feature>/src/__factories__/index.ts`.
-3. Call `commentFactory.reset()` in every `beforeEach` that uses it.
+3. Call `commentFactory.reset()` in every `beforeEach` (or inline) that uses it.
 
 The `defineFactory` function lives in `packages/core-testing/src/factory/define-factory.ts`.
 
 ---
 
-## 9. Contract Suite Usage
+## 9. Output Validation Tests (R25)
+
+Every **non-void** use case must have an R25 test that injects a malformed mock response and asserts the use case throws `ZodError`. This verifies that the `xOutputSchema.parse(result)` at the end of each use case actually guards against misbehaving repositories.
+
+**Void use cases are exempt:** `signOutUseCase`, `deleteMediaUseCase`, and any future use case returning `Promise<void>` skip R25 — they have no output schema.
+
+**Pattern A — reach into `_articles` (or equivalent backing array) when the typed API prevents you from inserting bad data:**
+
+```typescript
+// packages/blog/src/application/use-cases/get-articles.use-case.test.ts
+import { ZodError } from "zod";
+import { getArticlesUseCase, getArticlesOutputSchema } from "@/application/use-cases/get-articles.use-case";
+import { MockArticlesRepository } from "@/infrastructure/repositories/articles.repository.mock";
+
+describe("getArticlesUseCase output validation (R25)", () => {
+  it("throws when the repository returns a malformed article", async () => {
+    const repo = new MockArticlesRepository();
+    // bypass typed createArticle by reaching into the backing array directly
+    (repo as unknown as { _articles: unknown[] })._articles.push({ id: 123 });
+
+    const useCase = getArticlesUseCase(repo);
+    await expect(useCase({})).rejects.toBeInstanceOf(ZodError);
+  });
+
+  it("exports an output schema that mirrors Article[]", () => {
+    expect(getArticlesOutputSchema).toBeDefined();
+    expect(getArticlesOutputSchema.safeParse([]).success).toBe(true);
+  });
+});
+```
+
+**Pattern B — inline stub when pattern A is impractical (service layer or complex dependency):**
+
+```typescript
+// packages/auth/src/application/use-cases/sign-in.use-case.test.ts
+import type { IAuthenticationService } from "@/application/services/authentication.service.interface";
+
+describe("signInUseCase output validation (R25)", () => {
+  it("throws when authenticationService returns a malformed session", async () => {
+    const users = new MockUsersRepository([]);
+    await users.createUser(userFactory.build({ username: "alice" }));
+
+    const auth = {
+      verifyPassword: async () => true,
+      createSession: async () => ({ session: { id: 123 }, cookie: null }),
+    } as unknown as IAuthenticationService;
+
+    const useCase = signInUseCase(users, auth);
+    await expect(useCase({ username: "alice", password: "x" })).rejects.toBeInstanceOf(ZodError);
+  });
+});
+```
+
+Group R25 tests in a separate `describe` block labelled `"<useCase> output validation (R25)"` so they are easy to grep.
+
+---
+
+## 10. Router Error-Mapping Tests (R26)
+
+Each feature's `router.test.ts` must assert that thrown domain errors become `TRPCError` with the correct code. The router test uses `xRouter.createCaller({})` and calls real procedures backed by the default mock bindings.
+
+The `beforeEach` / `afterEach` blocks reload the DI module so each test gets a fresh mock repository:
+
+```typescript
+// packages/blog/src/integrations/api/router.test.ts
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { TRPCError } from "@trpc/server";
+import { blogContainer } from "@/di/container";
+import { BlogModule } from "@/di/module";
+import { blogRouter } from "@/integrations/api/router";
+
+describe("blogRouter (R26 error mapping)", () => {
+  beforeEach(() => {
+    blogContainer.unbindAll();
+    blogContainer.load(BlogModule);
+  });
+
+  afterEach(() => {
+    blogContainer.unbindAll();
+  });
+
+  it("translates ArticleNotFoundError → NOT_FOUND", async () => {
+    const caller = blogRouter.createCaller({});
+    try {
+      await caller.articleBySlug({ slug: "missing" });
+      throw new Error("expected throw");
+    } catch (e) {
+      expect(e).toBeInstanceOf(TRPCError);
+      expect((e as TRPCError).code).toBe("NOT_FOUND");
+    }
+  });
+
+  it("translates zod parse failure → BAD_REQUEST", async () => {
+    const caller = blogRouter.createCaller({});
+    try {
+      await caller.articleBySlug({} as unknown as { slug: string });
+      throw new Error("expected throw");
+    } catch (e) {
+      expect(e).toBeInstanceOf(TRPCError);
+      expect((e as TRPCError).code).toBe("BAD_REQUEST");
+    }
+  });
+});
+```
+
+For features where a domain error can only be triggered by an empty store (e.g. `navigation`'s `HeaderNotFoundError`), inline a `NullXRepository` and rebind the container:
+
+```typescript
+it("translates HeaderNotFoundError → NOT_FOUND", async () => {
+  @injectable()
+  class NullHeaderRepository implements IHeaderRepository {
+    async getHeader() { return undefined; }
+  }
+  navigationContainer.unbind(NAVIGATION_SYMBOLS.IHeaderRepository);
+  navigationContainer.bind(NAVIGATION_SYMBOLS.IHeaderRepository).to(NullHeaderRepository);
+
+  const caller = navigationRouter.createCaller({});
+  try {
+    await caller.header({});
+    throw new Error("expected throw");
+  } catch (e) {
+    expect(e).toBeInstanceOf(TRPCError);
+    expect((e as TRPCError).code).toBe("NOT_FOUND");
+  }
+});
+```
+
+Every feature needs at least one `NOT_FOUND` (or domain-error) test and one `BAD_REQUEST` (schema validation) test.
+
+---
+
+## 11. Presenter Shape Tests (R27/R28)
+
+When a controller's presenter **reshapes** the use-case output (rather than returning it unchanged), the controller test must assert the **view shape** — not the full use-case output.
+
+**Example — auth `sign-in` (non-identity presenter):**
+
+The `signInUseCase` returns `{ session, cookie }`. The presenter extracts `cookie` and returns it directly. The controller test must assert the cookie's shape:
+
+```typescript
+// packages/auth/src/interface-adapters/controllers/sign-in.controller.test.ts
+describe("signInController", () => {
+  it("returns a cookie on successful sign-in", async () => {
+    const users = new MockUsersRepository([]);
+    const auth = new MockAuthenticationService(users);
+    await users.createUser(
+      userFactory.build({ username: "alice", passwordHash: "hashed_testpassword" }),
+    );
+
+    const useCase = signInUseCase(users, auth);
+    const controller = signInController(useCase);
+
+    const result = await controller({ username: "alice", password: "testpassword" });
+    // assert the VIEW shape (cookie), not the use-case output ({ session, cookie })
+    expect(result.name).toBe("session");
+    expect(result.value).toBeTruthy();
+  });
+});
+```
+
+**Identity presenters skip this.** Blog, marketing-pages, navigation, and media controllers all use identity presenters (`return value`). Their controller tests assert on the same fields the use case would return — that is fine, because the presenter does not transform.
+
+**Rule of thumb:** if `presenter(value)` does anything other than `return value`, write a test that cannot pass by accident — assert a field that only exists on the *view*, not on `XOutput`.
+
+Void controllers (`signOutController`, `deleteMediaController`) return `Promise<void>` and have no presenter — no view-shape test applies.
+
+---
+
+## 12. Contract Suite Usage
 
 A contract suite asserts that every implementation of a repository interface satisfies the same behavioral contract. The suite runs once per implementation; the implementation is supplied via `buildSubject`.
 
@@ -340,8 +518,8 @@ A contract suite asserts that every implementation of a repository interface sat
 ```typescript
 import { it, expect, beforeEach } from "vitest";
 import { defineContractSuite } from "@repo/core-testing/contract";
-import type { ICommentsRepository } from "../application/repositories/comments-repository.interface.js";
-import { commentFactory } from "../__factories__/comment.factory.js";
+import type { ICommentsRepository } from "../application/repositories/comments.repository.interface";
+import { commentFactory } from "../__factories__/comment.factory";
 
 export const commentsRepositoryContract =
   defineContractSuite<ICommentsRepository>(
@@ -367,10 +545,10 @@ export const commentsRepositoryContract =
 2. Run the contract against the mock implementation:
 
 ```typescript
-// packages/<feature>/src/infrastructure/repositories/mock-comments.repository.test.ts
+// packages/<feature>/src/infrastructure/repositories/comments.repository.mock.test.ts
 import { describe } from "vitest";
 import { commentsRepositoryContract } from "@/__contracts__/comments-repository.contract";
-import { MockCommentsRepository } from "./mock-comments.repository";
+import { MockCommentsRepository } from "./comments.repository.mock";
 
 describe("MockCommentsRepository", () => {
   commentsRepositoryContract.run(async () => new MockCommentsRepository());
@@ -380,30 +558,36 @@ describe("MockCommentsRepository", () => {
 3. Run the contract against the Payload implementation (with `vi.mock('payload')`):
 
 ```typescript
-// packages/<feature>/src/infrastructure/repositories/payload-comments.repository.test.ts
+// packages/<feature>/src/infrastructure/repositories/comments.repository.test.ts
 import { describe, vi } from "vitest";
 import { commentsRepositoryContract } from "@/__contracts__/comments-repository.contract";
-import { PayloadCommentsRepository } from "./payload-comments.repository";
+import { CommentsRepository } from "./comments.repository";
 import { stubPayloadConfig } from "@repo/core-testing/payload";
 
 vi.mock("payload", () => ({ getPayload: vi.fn() }));
 
-describe("PayloadCommentsRepository", () => {
+describe("CommentsRepository", () => {
   commentsRepositoryContract.run(async () => {
     const { getPayload } = await import("payload");
     (getPayload as ReturnType<typeof vi.fn>).mockResolvedValue(buildStub());
-    return new PayloadCommentsRepository(stubPayloadConfig);
+    return new CommentsRepository(stubPayloadConfig);
   });
 });
 ```
 
-4. Run tests. Fix until green. Both implementations now share the same contract.
+4. Run tests. Fix until green.
 
-The `buildSubject` pattern is the key: each `run()` call provides a fresh instance, so every contract `it()` starts with a clean repository.
+The `buildSubject` pattern ensures each `run()` call supplies a fresh instance — every contract `it()` starts with a clean repository.
+
+**File naming convention (post-Plan-8):**
+- Mock implementation: `<x>.repository.mock.ts` (not `mock-<x>.repository.ts`)
+- Mock test: `<x>.repository.mock.test.ts`
+- Real implementation: `<x>.repository.ts` (no `payload-` prefix)
+- Interface: `<x>.repository.interface.ts`
 
 ---
 
-## 10. Running Tests
+## 13. Running Tests
 
 **Watch mode (recommended during development):**
 
@@ -422,7 +606,7 @@ it.only("returns undefined for a missing slug", async () => { ... });
 Run the file directly:
 
 ```bash
-pnpm test --filter @repo/blog -- articles.controller.test.ts
+pnpm test --filter @repo/blog -- get-article-by-slug.controller.test.ts
 ```
 
 **Debug a failing test:**
@@ -436,7 +620,7 @@ pnpm test --filter @repo/blog -- --reporter=verbose
 For node-level debugging:
 
 ```bash
-node --inspect-brk node_modules/.bin/vitest run src/interface-adapters/controllers/articles.controller.test.ts
+node --inspect-brk node_modules/.bin/vitest run src/interface-adapters/controllers/get-article-by-slug.controller.test.ts
 ```
 
 Then attach Chrome DevTools at `chrome://inspect`.