ts-procedures 6.0.0 → 6.0.1

package/docs/superpowers/plans/2026-04-24-doc-registry-simplification.md

@@ -0,0 +1,886 @@
+# DocRegistry Simplification Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Collapse `DocRegistry.fromTaxonomy` into a single smart constructor that accepts `errors: ErrorTaxonomy` directly, add a fluent `.documentError(...docs)` method for rare extension cases, and make `taxonomyToErrorDocs` an internal helper — so developers interact with one concept ("errors") and never see implementation-level words like "taxonomy" in the DocRegistry API.
+
+**Architecture:** The constructor's `errors` field becomes the single entry point. It accepts an `ErrorTaxonomy` (the thing developers already have from `defineErrorTaxonomy`), auto-converts to `ErrorDoc[]` internally, auto-merges framework defaults (opt-out via `includeDefaults: false`), and auto-dedupes. The fluent `.documentError(...docs: ErrorDoc[])` method handles rare cases where extra errors (middleware-level, infrastructure, doc-only) need documentation without a taxonomy entry. `fromTaxonomy` is deleted. `taxonomyToErrorDocs` remains in the codebase (still used internally by `DocRegistry`) but is removed from the `./http-errors` public export so it stops leaking.
+
+**Tech Stack:** TypeScript, Vitest, existing ts-procedures v6 taxonomy infrastructure.
+
+**Breaking changes (v6 was released today in commit `c667cca`, so blast radius is near-zero):**
+1. `DocRegistry.fromTaxonomy(taxonomy, config)` → removed. Use `new DocRegistry({ errors: taxonomy })`.
+2. `DocRegistryConfig.errors: ErrorDoc[]` → `DocRegistryConfig.errors: ErrorTaxonomy | ErrorDoc[]` (polymorphic; existing `ErrorDoc[]` call sites still work).
+3. `DocRegistryConfig` gains `includeDefaults?: boolean` (default `true`). Previously, framework defaults were **not** auto-included when using the plain constructor — this is now a behavioral change: `new DocRegistry({ errors: [...] })` will merge in framework defaults unless `includeDefaults: false` is passed. Any test/consumer that constructed `new DocRegistry({ errors: [myCustom] })` and expected exactly `[myCustom]` needs either `includeDefaults: false` or to account for the defaults.
+4. `taxonomyToErrorDocs` → removed from the `./http-errors` public export. Still exists internally in `error-taxonomy.ts` but no longer in the published type surface.
+
+---
+
+## File Structure
+
+**Files to modify:**
+
+| File | Responsibility |
+|---|---|
+| `src/implementations/types.ts` | `DocRegistryConfig` — widen `errors` field, add `includeDefaults` |
+| `src/implementations/http/doc-registry.ts` | Rewrite constructor (detect taxonomy vs ErrorDoc[], auto-merge defaults, dedupe); add `.documentError()`; delete `fromTaxonomy` |
+| `src/implementations/http/error-taxonomy.ts` | Remove `export` from `taxonomyToErrorDocs` (or keep export but drop from the subpath entry — see Task 1) |
+| `src/implementations/http/doc-registry.test.ts` | Add tests for new polymorphic `errors`, auto-dedupe, auto-defaults, `.documentError()`; adjust `defaultErrors()` tests; migrate any existing construction that relied on no-auto-defaults |
+| `src/implementations/http/route-errors.test.ts` | Replace 4 `DocRegistry.fromTaxonomy` call sites with `new DocRegistry({ errors: ... })`. Update `describe` block name. |
+| `docs/http-integrations.md` | Replace `fromTaxonomy` example with unified constructor; update surrounding prose |
+| `src/implementations/http/README.md` | Update example to show taxonomy in constructor instead of `defaultErrors()` spread |
+| `CHANGELOG.md` | Add v6.0.1 (or v7 if breaking deemed major) section describing the collapse |
+| `CLAUDE.md` | Update the DocRegistry paragraph to drop `fromTaxonomy` mention |
+| `agent_config/claude-code/agents/ts-procedures-architect.md` | Replace `fromTaxonomy` reference |
+| `agent_config/claude-code/skills/ts-procedures/SKILL.md` | Remove `fromTaxonomy` from doc table |
+| `agent_config/claude-code/skills/ts-procedures/patterns.md` | Replace `fromTaxonomy` code example |
+| `agent_config/claude-code/skills/ts-procedures/api-reference.md` | Remove `fromTaxonomy` from class signature; remove `taxonomyToErrorDocs` public-function section; update `DocRegistryConfig` type; document `.documentError()` |
+| `agent_config/claude-code/skills/ts-procedures-review/checklist.md` | Replace 2 `fromTaxonomy` references |
+| `agent_config/copilot/copilot-instructions.md` | Replace `fromTaxonomy` example |
+| `agent_config/cursor/cursorrules` | Mirror copilot changes |
+
+**Files NOT modified:**
+- `src/implementations/http/error-taxonomy.test.ts` — doesn't reference `fromTaxonomy`
+- HTTP builder source files — taxonomy runtime wiring is unchanged
+- Client code (`src/client/**`, `src/codegen/**`) — the DocEnvelope shape is unchanged; this is purely an input-ergonomics change
+- `agent_config/claude-code/skills/ts-procedures/anti-patterns.md` — verify no references, no changes expected
+
+---
+
+## Task 1: Verify current API surface and write failing tests first
+
+**Files:**
+- Modify: `src/implementations/http/doc-registry.test.ts`
+
+This is a TDD-driven refactor. Before touching production code, encode the new behavior as failing tests so the refactor has a reliable target.
+
+- [ ] **Step 1.1: Confirm `taxonomyToErrorDocs` is currently exported via `./http-errors` subpath**
+
+Run: `grep -n "export" src/implementations/http/error-taxonomy.ts | grep -i "taxonomy\|errordoc"`
+Expected: Confirms `export function taxonomyToErrorDocs` exists. The `./http-errors` subpath re-exports everything from this file, so it's part of the public API today.
+
+- [ ] **Step 1.2: Read the current `doc-registry.test.ts` top-of-file imports and fixtures so new tests fit the existing shape**
+
+Run: `head -60 src/implementations/http/doc-registry.test.ts`
+Expected: See the imports (`DocRegistry`, test fixtures like `rpcDoc`, `apiDoc`). Note the describe-block structure.
+
+- [ ] **Step 1.3: Append a new describe block to `doc-registry.test.ts` covering the new behaviors**
+
+Add this describe block at the end of the outer `describe('DocRegistry', ...)` block (after the existing `defaultErrors()` block, before `kind discriminant`):
+
+```typescript
+  // --------------------------------------------------------------------------
+  // taxonomy input + auto-defaults + dedupe (v6.0.1 simplification)
+  // --------------------------------------------------------------------------
+  describe('errors: ErrorTaxonomy (polymorphic constructor input)', () => {
+    test('accepts an ErrorTaxonomy directly and converts to ErrorDoc[]', () => {
+      const taxonomy = defineErrorTaxonomy({
+        AuthError: {
+          class: class AuthError extends Error {},
+          statusCode: 401,
+          description: 'unauthenticated',
+        },
+      })
+      const envelope = new DocRegistry({ errors: taxonomy }).toJSON()
+      const auth = envelope.errors.find((e) => e.name === 'AuthError')
+      expect(auth).toBeDefined()
+      expect(auth?.statusCode).toBe(401)
+      expect(auth?.description).toBe('unauthenticated')
+    })
+
+    test('auto-includes framework defaults when errors is a taxonomy', () => {
+      const taxonomy = defineErrorTaxonomy({
+        AuthError: { class: class AuthError extends Error {}, statusCode: 401 },
+      })
+      const names = new DocRegistry({ errors: taxonomy }).toJSON().errors.map((e) => e.name)
+      expect(names).toContain('AuthError')
+      expect(names).toContain('ProcedureValidationError')
+      expect(names).toContain('ProcedureYieldValidationError')
+      expect(names).toContain('ProcedureError')
+      expect(names).toContain('ProcedureRegistrationError')
+    })
+
+    test('auto-includes framework defaults when errors is ErrorDoc[]', () => {
+      const custom: ErrorDoc = { name: 'CustomThing', statusCode: 418, description: 'teapot' }
+      const names = new DocRegistry({ errors: [custom] }).toJSON().errors.map((e) => e.name)
+      expect(names).toContain('CustomThing')
+      expect(names).toContain('ProcedureValidationError')
+    })
+
+    test('includeDefaults: false omits framework defaults', () => {
+      const taxonomy = defineErrorTaxonomy({
+        AuthError: { class: class AuthError extends Error {}, statusCode: 401 },
+      })
+      const names = new DocRegistry({ errors: taxonomy, includeDefaults: false })
+        .toJSON()
+        .errors.map((e) => e.name)
+      expect(names).toEqual(['AuthError'])
+    })
+
+    test('user taxonomy entry with same name as default overrides default (dedupe, user wins)', () => {
+      const taxonomy = defineErrorTaxonomy({
+        ProcedureError: {
+          class: Error,
+          statusCode: 418,
+          description: 'custom override',
+        },
+      })
+      const envelope = new DocRegistry({ errors: taxonomy }).toJSON()
+      const proc = envelope.errors.filter((e) => e.name === 'ProcedureError')
+      expect(proc).toHaveLength(1)
+      expect(proc[0].statusCode).toBe(418)
+      expect(proc[0].description).toBe('custom override')
+    })
+
+    test('user ErrorDoc with same name as default overrides default (dedupe, user wins)', () => {
+      const custom: ErrorDoc = {
+        name: 'ProcedureError',
+        statusCode: 418,
+        description: 'custom override',
+      }
+      const envelope = new DocRegistry({ errors: [custom] }).toJSON()
+      const proc = envelope.errors.filter((e) => e.name === 'ProcedureError')
+      expect(proc).toHaveLength(1)
+      expect(proc[0].statusCode).toBe(418)
+    })
+
+    test('empty errors config still returns framework defaults', () => {
+      const names = new DocRegistry().toJSON().errors.map((e) => e.name)
+      expect(names).toContain('ProcedureError')
+      expect(names).toContain('ProcedureValidationError')
+      expect(names).toContain('ProcedureYieldValidationError')
+      expect(names).toContain('ProcedureRegistrationError')
+    })
+
+    test('includeDefaults: false with no errors produces empty error list', () => {
+      const envelope = new DocRegistry({ includeDefaults: false }).toJSON()
+      expect(envelope.errors).toEqual([])
+    })
+  })
+
+  // --------------------------------------------------------------------------
+  // .documentError() fluent extension
+  // --------------------------------------------------------------------------
+  describe('.documentError()', () => {
+    test('adds a single ErrorDoc to the envelope', () => {
+      const registry = new DocRegistry({ includeDefaults: false }).documentError({
+        name: 'RateLimitExceeded',
+        statusCode: 429,
+        description: 'too many requests',
+      })
+      const names = registry.toJSON().errors.map((e) => e.name)
+      expect(names).toEqual(['RateLimitExceeded'])
+    })
+
+    test('accepts multiple docs via variadic args', () => {
+      const registry = new DocRegistry({ includeDefaults: false }).documentError(
+        { name: 'A', statusCode: 400, description: 'a' },
+        { name: 'B', statusCode: 500, description: 'b' }
+      )
+      const names = registry.toJSON().errors.map((e) => e.name)
+      expect(names).toEqual(['A', 'B'])
+    })
+
+    test('returns this for chaining', () => {
+      const registry = new DocRegistry()
+      const returned = registry.documentError({
+        name: 'Foo',
+        statusCode: 500,
+        description: 'x',
+      })
+      expect(returned).toBe(registry)
+    })
+
+    test('composes with taxonomy input — extends docs without replacing', () => {
+      const taxonomy = defineErrorTaxonomy({
+        AuthError: { class: class AuthError extends Error {}, statusCode: 401 },
+      })
+      const envelope = new DocRegistry({ errors: taxonomy })
+        .documentError({ name: 'RateLimitExceeded', statusCode: 429, description: 'x' })
+        .toJSON()
+      const names = envelope.errors.map((e) => e.name)
+      expect(names).toContain('AuthError')
+      expect(names).toContain('RateLimitExceeded')
+      expect(names).toContain('ProcedureValidationError')
+    })
+
+    test('dedupes against existing errors (last write wins)', () => {
+      const registry = new DocRegistry({ includeDefaults: false })
+        .documentError({ name: 'Foo', statusCode: 400, description: 'first' })
+        .documentError({ name: 'Foo', statusCode: 500, description: 'second' })
+      const foo = registry.toJSON().errors.filter((e) => e.name === 'Foo')
+      expect(foo).toHaveLength(1)
+      expect(foo[0].statusCode).toBe(500)
+      expect(foo[0].description).toBe('second')
+    })
+  })
+```
+
+Make sure the imports at the top of `doc-registry.test.ts` include `defineErrorTaxonomy` from `./error-taxonomy.js` and the `ErrorDoc` type. If they're not already imported, add them.
+
+- [ ] **Step 1.4: Run the new tests to confirm they fail**
+
+Run: `npx vitest run src/implementations/http/doc-registry.test.ts`
+Expected: All new tests in the two new describe blocks FAIL with type errors (`errors: taxonomy` not assignable) or behavioral mismatches (defaults not auto-included, `documentError` method not found). Existing tests still pass.
+
+- [ ] **Step 1.5: Commit the failing tests**
+
+```bash
+git add src/implementations/http/doc-registry.test.ts
+git commit -m "test(doc-registry): add failing tests for unified constructor + documentError()"
+```
+
+---
+
+## Task 2: Widen `DocRegistryConfig` and rewrite the `DocRegistry` class
+
+**Files:**
+- Modify: `src/implementations/types.ts:186-190`
+- Modify: `src/implementations/http/doc-registry.ts` (full rewrite of class body)
+
+- [ ] **Step 2.1: Widen `DocRegistryConfig.errors` and add `includeDefaults`**
+
+In `src/implementations/types.ts`, replace the `DocRegistryConfig` interface (lines 186-190) with:
+
+```typescript
+export interface DocRegistryConfig {
+  basePath?: string
+  headers?: HeaderDoc[]
+  /**
+   * Errors to document in the envelope. Accepts either your runtime
+   * {@link ErrorTaxonomy} (from `defineErrorTaxonomy`) — the common case — or
+   * a raw `ErrorDoc[]` for consumers who aren't using a taxonomy.
+   *
+   * Framework defaults (`ProcedureError`, `ProcedureValidationError`,
+   * `ProcedureYieldValidationError`, `ProcedureRegistrationError`) are merged
+   * in automatically and deduped. Opt out via `includeDefaults: false`.
+   */
+  errors?: ErrorTaxonomy | ErrorDoc[]
+  /** Whether to auto-merge framework error defaults. Defaults to `true`. */
+  includeDefaults?: boolean
+}
+```
+
+Add the `ErrorTaxonomy` import to the top of `types.ts`. Check where it currently lives — if there's a circular-import risk (the taxonomy file imports types from `types.ts`), use a `type`-only import:
+
+```typescript
+import type { ErrorTaxonomy } from './http/error-taxonomy.js'
+```
+
+- [ ] **Step 2.2: Verify no circular import**
+
+Run: `npm run build`
+Expected: Build succeeds. If it fails with a circular-import or ordering error, inline the `ErrorTaxonomy` type shape into `types.ts` instead (copy the minimal shape: `Record<string, { statusCode: number; description?: string; schema?: Record<string, unknown>; class?: unknown; match?: unknown; toResponse?: unknown; onCatch?: unknown }>`) — this is load-bearing structural compatibility, not identity. Prefer the import path; only fall back if proven circular.
+
+- [ ] **Step 2.3: Rewrite `DocRegistry` class**
+
+Overwrite `src/implementations/http/doc-registry.ts` with the following. This rewrite:
+- Detects whether `config.errors` is a taxonomy or `ErrorDoc[]` via shape check
+- Applies defaults when `includeDefaults !== false`
+- Dedupes by `name` (user wins over defaults; last-write-wins within user entries)
+- Adds `documentError(...docs: ErrorDoc[]): this`
+- Deletes `fromTaxonomy`
+- Keeps `defaultErrors()` public (still used by `api-reference.md` callers who build custom envelopes)
+
+```typescript
+import type {
+  AnyHttpRouteDoc,
+  DocEnvelope,
+  DocRegistryConfig,
+  DocRegistryOutputOptions,
+  DocSource,
+  ErrorDoc,
+  HeaderDoc,
+} from '../types.js'
+import {
+  ErrorTaxonomy,
+  defaultErrorTaxonomy,
+  taxonomyToErrorDocs,
+} from './error-taxonomy.js'
+
+export type {
+  AnyHttpRouteDoc,
+  DocEnvelope,
+  DocRegistryConfig,
+  DocRegistryOutputOptions,
+  DocSource,
+  ErrorDoc,
+  HeaderDoc,
+} from '../types.js'
+
+/**
+ * `ProcedureRegistrationError` is thrown at procedure-definition time (never at
+ * request time), so it doesn't appear in the runtime taxonomy. It is documented
+ * here so consumers still see it in the error catalog.
+ */
+const PROCEDURE_REGISTRATION_ERROR_DOC: ErrorDoc = {
+  name: 'ProcedureRegistrationError',
+  statusCode: 500,
+  description:
+    'An invalid schema or configuration was detected at procedure registration time.',
+  schema: {
+    type: 'object',
+    properties: {
+      name: { type: 'string', const: 'ProcedureRegistrationError' },
+      procedureName: { type: 'string' },
+      message: { type: 'string' },
+    },
+    required: ['name', 'procedureName', 'message'],
+  },
+}
+
+/**
+ * Duck-type check: a taxonomy is `Record<string, ErrorTaxonomyEntry>` where
+ * each entry has a numeric `statusCode`. An `ErrorDoc[]` is an array.
+ * Arrays and taxonomies are trivially distinguishable via `Array.isArray`.
+ */
+function isTaxonomy(input: ErrorTaxonomy | ErrorDoc[]): input is ErrorTaxonomy {
+  return !Array.isArray(input)
+}
+
+/**
+ * Dedupes ErrorDocs by `name`, last occurrence wins. Input order is preserved
+ * for survivors — meaning when two entries share a name, the later one's
+ * position in the output is where the LAST occurrence appeared.
+ */
+function dedupeByName(docs: ErrorDoc[]): ErrorDoc[] {
+  const byName = new Map<string, ErrorDoc>()
+  for (const doc of docs) byName.set(doc.name, doc)
+  return Array.from(byName.values())
+}
+
+export class DocRegistry {
+  private readonly basePath: string
+  private readonly headers: HeaderDoc[]
+  private errors: ErrorDoc[]
+  private readonly sources: DocSource<AnyHttpRouteDoc>[] = []
+
+  constructor(config?: DocRegistryConfig) {
+    this.basePath = config?.basePath ?? ''
+    this.headers = config?.headers ?? []
+
+    const includeDefaults = config?.includeDefaults ?? true
+    const userErrors: ErrorDoc[] = config?.errors
+      ? isTaxonomy(config.errors)
+        ? taxonomyToErrorDocs(config.errors)
+        : config.errors
+      : []
+
+    // Precedence: defaults come first, then user errors override via dedupe
+    // (last-write-wins). Matches runtime resolution order — user taxonomy
+    // entries win over framework defaults when keys overlap.
+    const merged = includeDefaults
+      ? [...DocRegistry.defaultErrors(), ...userErrors]
+      : userErrors
+
+    this.errors = dedupeByName(merged)
+  }
+
+  from(source: DocSource<AnyHttpRouteDoc>): this {
+    this.sources.push(source)
+    return this
+  }
+
+  /**
+   * Adds one or more {@link ErrorDoc} entries to the envelope. Use for
+   * documenting errors that aren't in your runtime taxonomy — middleware-level
+   * errors, infrastructure errors (502/503/504), or doc-only meta errors.
+   *
+   * Deduped against existing errors by `name` — last write wins, so calling
+   * this with a name that already exists overrides the earlier entry.
+   */
+  documentError(...docs: ErrorDoc[]): this {
+    this.errors = dedupeByName([...this.errors, ...docs])
+    return this
+  }
+
+  toJSON<T = DocEnvelope>(options?: DocRegistryOutputOptions<T>): T {
+    let routes = this.sources.flatMap((source) => source.docs)
+
+    if (options?.filter) {
+      routes = routes.filter(options.filter)
+    }
+
+    const envelope: DocEnvelope = {
+      basePath: this.basePath,
+      headers: [...this.headers],
+      errors: [...this.errors],
+      routes,
+    }
+
+    if (options?.transform) {
+      return options.transform(envelope)
+    }
+
+    return envelope as T
+  }
+
+  /**
+   * Framework error defaults for the DocEnvelope — derived from
+   * {@link defaultErrorTaxonomy} so the documented shape cannot drift from what
+   * the HTTP builders actually emit at runtime. `ProcedureRegistrationError` is
+   * appended because it's thrown at registration time (never at request time)
+   * and therefore lives only in the catalog, not the runtime taxonomy.
+   *
+   * Most consumers do not need to call this directly — the `DocRegistry`
+   * constructor auto-includes these unless `includeDefaults: false` is passed.
+   */
+  static defaultErrors(): ErrorDoc[] {
+    return [
+      ...taxonomyToErrorDocs(defaultErrorTaxonomy),
+      PROCEDURE_REGISTRATION_ERROR_DOC,
+    ]
+  }
+}
+```
+
+Notable details:
+- `errors` field is no longer `readonly` because `documentError` mutates it.
+- `isTaxonomy` uses `!Array.isArray(input)` — simple and correct since `ErrorTaxonomy` is `Record<string, ...>`.
+- Dedup precedence is **defaults-first, user-last** so user entries override defaults, AND within user entries, the last write wins. This matches the old `fromTaxonomy` behavior (user entries override defaults) and aligns with runtime resolution.
+
+- [ ] **Step 2.4: Run the new failing tests — they should now pass**
+
+Run: `npx vitest run src/implementations/http/doc-registry.test.ts`
+Expected: All tests pass, including the new ones from Task 1.
+
+- [ ] **Step 2.5: Run the full test suite to check for regressions**
+
+Run: `npm run test`
+Expected: Most pass, but expect failures in:
+- `src/implementations/http/doc-registry.test.ts` tests that expected `new DocRegistry()` to produce exactly `[]` errors (they will now produce the 4 defaults).
+- `src/implementations/http/route-errors.test.ts` — still uses `DocRegistry.fromTaxonomy`, which no longer exists. TypeScript should catch this at compile-time via `tsc`-in-vitest, or the runtime will throw "not a function". These are fixed in Task 3.
+
+Note the specific failing tests and their assertion messages — Task 3 fixes them.
+
+- [ ] **Step 2.6: Fix doc-registry.test.ts regressions**
+
+Find any existing test in `doc-registry.test.ts` that asserts `errors: []` or similar expected-empty behavior when constructing `new DocRegistry()` without `errors:`. These tests previously passed because the old constructor did NOT auto-merge defaults. Two options:
+
+(a) If the test is specifically validating "no defaults by default," update the assertion to reflect the new behavior (defaults included), OR
+(b) If the test just wanted a clean slate for some other assertion (e.g., checking route behavior), pass `{ includeDefaults: false }` to restore the old behavior.
+
+Read each failing test, pick (a) or (b) based on intent, and fix accordingly.
+
+Scan specifically for: `const registry = new DocRegistry()` (no args) at lines 64, 95, 101, 106, 111, 117, 123, 129, 137, 160, 171, 192, 202, 214, 234, 242 — most are for route-plumbing tests and can take `{ includeDefaults: false }`. Lines around 178 use `{ headers, errors }` — verify the assertions still hold with defaults merged, or add `includeDefaults: false`.
+
+- [ ] **Step 2.7: Re-run doc-registry.test.ts**
+
+Run: `npx vitest run src/implementations/http/doc-registry.test.ts`
+Expected: All tests pass.
+
+- [ ] **Step 2.8: Commit**
+
+```bash
+git add src/implementations/types.ts src/implementations/http/doc-registry.ts src/implementations/http/doc-registry.test.ts
+git commit -m "refactor(doc-registry): unify constructor to accept ErrorTaxonomy; add .documentError()"
+```
+
+---
+
+## Task 3: Migrate `route-errors.test.ts` off `fromTaxonomy`
+
+**Files:**
+- Modify: `src/implementations/http/route-errors.test.ts:120-177`
+
+- [ ] **Step 3.1: Rewrite the `fromTaxonomy` describe block**
+
+Replace lines 120-177 of `src/implementations/http/route-errors.test.ts` with:
+
+```typescript
+describe('DocRegistry with taxonomy input', () => {
+  test('seeds envelope errors from the taxonomy + framework defaults', () => {
+    const registry = new DocRegistry({ errors: appErrors, basePath: '/api' })
+    const envelope = registry.toJSON()
+    const names = envelope.errors.map((e) => e.name)
+    expect(names).toContain('UseCaseError')
+    expect(names).toContain('AuthError')
+    expect(names).toContain('ProcedureValidationError')
+    expect(names).toContain('ProcedureRegistrationError')
+    expect(envelope.basePath).toBe('/api')
+  })
+
+  test('includeDefaults: false omits framework entries', () => {
+    const registry = new DocRegistry({ errors: appErrors, includeDefaults: false })
+    const names = registry.toJSON().errors.map((e) => e.name)
+    expect(names).toEqual(['UseCaseError', 'AuthError'])
+  })
+
+  test('user entry with same key as default takes precedence (deduped)', () => {
+    const overridden = defineErrorTaxonomy({
+      ProcedureError: {
+        class: Error,
+        statusCode: 418,
+        description: 'custom override',
+      },
+    })
+    const envelope = new DocRegistry({ errors: overridden }).toJSON()
+    const proc = envelope.errors.find((e) => e.name === 'ProcedureError')
+    expect(proc?.statusCode).toBe(418)
+    expect(proc?.description).toBe('custom override')
+    const count = envelope.errors.filter((e) => e.name === 'ProcedureError').length
+    expect(count).toBe(1)
+  })
+
+  test('registered route errors survive DocRegistry composition', () => {
+    const API = Procedures<{}, APIConfig<keyof typeof appErrors & string>>()
+    API.Create(
+      'GetUser',
+      {
+        path: '/users/:id',
+        method: 'get',
+        errors: ['UseCaseError'],
+        schema: {
+          input: { pathParams: Type.Object({ id: Type.String() }) },
+          returnType: Type.Object({}),
+        },
+      },
+      async () => ({})
+    )
+    const app = new HonoAPIAppBuilder().register(API, () => ({}))
+    app.build()
+
+    const envelope = new DocRegistry({ errors: appErrors }).from(app).toJSON()
+    const route = envelope.routes.find((r) => r.kind === 'api' && r.name === 'GetUser')
+    expect(route?.errors).toEqual(['UseCaseError'])
+  })
+})
+```
+
+- [ ] **Step 3.2: Run the test file to confirm**
+
+Run: `npx vitest run src/implementations/http/route-errors.test.ts`
+Expected: All tests pass.
+
+- [ ] **Step 3.3: Run full test suite**
+
+Run: `npm run test`
+Expected: All tests pass.
+
+- [ ] **Step 3.4: Commit**
+
+```bash
+git add src/implementations/http/route-errors.test.ts
+git commit -m "test(route-errors): migrate fromTaxonomy call sites to unified constructor"
+```
+
+---
+
+## Task 4: Demote `taxonomyToErrorDocs` from the public `./http-errors` surface
+
+**Files:**
+- Modify: `src/implementations/http/error-taxonomy.ts` (JSDoc + @internal tag)
+
+The function still needs to be importable from `doc-registry.ts` (same module directory), but we want it out of the `./http-errors` public docs so consumers don't see it as an API entry point.
+
+The cleanest way without breaking the cross-module import is to keep the `export` (needed because `doc-registry.ts` imports it) but mark it `@internal` via JSDoc. TypeScript's `--stripInternal` or explicit documentation tooling will honor this. Our `tsconfig` may not strip it, but the signal to consumers (and to our agent_config docs) is clear.
+
+- [ ] **Step 4.1: Add `@internal` JSDoc tag to `taxonomyToErrorDocs`**
+
+In `src/implementations/http/error-taxonomy.ts`, update the JSDoc block at line ~185 from:
+
+```typescript
+/**
+ * Converts a taxonomy into {@link ErrorDoc} objects suitable for a DocEnvelope.
+ * Single source of truth so the runtime mapping and the documented shape
+ * cannot drift apart.
+ */
+export function taxonomyToErrorDocs(taxonomy: ErrorTaxonomy): ErrorDoc[] {
+```
+
+to:
+
+```typescript
+/**
+ * Converts a taxonomy into {@link ErrorDoc} objects suitable for a DocEnvelope.
+ *
+ * @internal Used by `DocRegistry` to merge taxonomy entries into the envelope.
+ *   Consumers should pass their taxonomy directly to `new DocRegistry({ errors: taxonomy })`
+ *   rather than calling this helper — the constructor handles the conversion.
+ */
+export function taxonomyToErrorDocs(taxonomy: ErrorTaxonomy): ErrorDoc[] {
+```
+
+- [ ] **Step 4.2: Verify build still passes**
+
+Run: `npm run build`
+Expected: Success.
+
+- [ ] **Step 4.3: Commit**
+
+```bash
+git add src/implementations/http/error-taxonomy.ts
+git commit -m "docs(error-taxonomy): mark taxonomyToErrorDocs @internal — consumers should use DocRegistry directly"
+```
+
+---
+
+## Task 5: Update project documentation
+
+**Files:**
+- Modify: `docs/http-integrations.md:278-302`
+- Modify: `src/implementations/http/README.md:256-262`
+- Modify: `CHANGELOG.md:17,22,26-27`
+- Modify: `CLAUDE.md:100`
+
+- [ ] **Step 5.1: Rewrite the DocRegistry section in `docs/http-integrations.md`**
+
+Read the current section:
+
+```bash
+sed -n '274,303p' docs/http-integrations.md
+```
+
+Replace lines 274-303 with:
+
+```markdown
+## DocRegistry — Composing Docs from Multiple Builders
+
+Use `DocRegistry` to compose route documentation from any combination of HTTP builders into a typed envelope:
+
+```typescript
+import { DocRegistry } from 'ts-procedures/http-docs'
+
+const docs = new DocRegistry({
+  basePath: '/api',
+  headers: [{ name: 'Authorization', description: 'Bearer token', required: false }],
+  errors: appErrors,  // your ErrorTaxonomy — auto-converted to ErrorDocs, framework defaults merged
+})
+  .from(rpcBuilder)
+  .from(apiBuilder)
+  .from(streamBuilder)
+
+app.get('/docs', (c) => c.json(docs.toJSON()))
+```
+
+`errors` accepts either your runtime `ErrorTaxonomy` (the common case) or a raw `ErrorDoc[]`. Framework defaults (`ProcedureError`, `ProcedureValidationError`, `ProcedureYieldValidationError`, `ProcedureRegistrationError`) are merged in automatically and deduped — user entries win when keys overlap. Pass `includeDefaults: false` to opt out.
+
+For errors that aren't in your taxonomy (middleware-level, infrastructure, doc-only meta errors), use the fluent `.documentError()` method:
+
+```typescript
+const docs = new DocRegistry({ errors: appErrors, basePath: '/api' })
+  .from(rpcBuilder)
+  .documentError({ name: 'RateLimitExceeded', statusCode: 429, description: 'too many requests' })
+```
+
+`from()` stores a reference — routes are read lazily at `toJSON()` time, so builders can be registered before or after `.build()`. Supports optional `filter` and `transform` options for customizing output.
+
+The `DocRegistry` output is the input for [Client Code Generation](./client-and-codegen.md).
+```
+
+- [ ] **Step 5.2: Update `src/implementations/http/README.md`**
+
+Replace lines 256-262 (the `new DocRegistry({ errors: DocRegistry.defaultErrors() })` example) to match the new constructor idiom:
+
+```bash
+sed -n '250,270p' src/implementations/http/README.md
+```
+
+Replace the example with:
+
+```typescript
+const docs = new DocRegistry({
+  basePath: '/api',
+  errors: appErrors,  // framework defaults auto-merged and deduped
+})
+```
+
+(Keep surrounding prose coherent.)
+
+- [ ] **Step 5.3: Update `CHANGELOG.md`**
+
+At the top of the file, add a new unreleased/patch section (use v6.0.1 or whatever the next version is):
+
+```markdown
+## v6.0.1 — DocRegistry constructor simplification
+
+### Changed
+
+- `DocRegistry` constructor now accepts `errors: ErrorTaxonomy | ErrorDoc[]` (polymorphic). Pass your taxonomy directly instead of converting it beforehand.
+- Framework error defaults are now auto-merged into every `DocRegistry` envelope (user entries override defaults via dedupe). Opt out via `includeDefaults: false`.
+- New fluent method `DocRegistry.prototype.documentError(...docs: ErrorDoc[])` for documenting errors not in the taxonomy.
+
+### Removed
+
+- `DocRegistry.fromTaxonomy(taxonomy, config?)` — superseded by `new DocRegistry({ errors: taxonomy, ...config })`. The new form is strictly more capable (dedupe applies to plain-constructor call sites too).
+- `taxonomyToErrorDocs` — still exists as an internal helper but marked `@internal` and no longer a recommended entry point. Pass your taxonomy to `DocRegistry` directly.
+
+### Migration
+
+```typescript
+// before (v6.0.0)
+DocRegistry.fromTaxonomy(appErrors, { basePath: '/api' })
+
+// after (v6.0.1)
+new DocRegistry({ errors: appErrors, basePath: '/api' })
+```
+
+If you were constructing `new DocRegistry({ errors: [myDoc] })` in v6.0.0 and relied on framework defaults NOT being auto-included, add `includeDefaults: false` to preserve v6.0.0 behavior.
+```
+
+Also scan the existing CHANGELOG for stale references to `fromTaxonomy` in the v6.0.0 entry (line 22, 26-27). Leave the v6.0.0 entry historically accurate — don't rewrite history. The v6.0.1 section above notes the deprecation.
+
+- [ ] **Step 5.4: Update `CLAUDE.md:100`**
+
+The relevant paragraph currently says:
+> `DocRegistry.defaultErrors()` derives from `defaultErrorTaxonomy` via `taxonomyToErrorDocs` — single source of truth for the documented and runtime-emitted shapes. `DocRegistry.fromTaxonomy(taxonomy, config?)` seeds envelope errors directly from a taxonomy (user entries + framework defaults, deduped).
+
+Replace with:
+> `DocRegistry.defaultErrors()` derives from `defaultErrorTaxonomy` — single source of truth for the documented and runtime-emitted shapes. The `DocRegistry` constructor accepts `errors: ErrorTaxonomy | ErrorDoc[]` directly (common case: pass your taxonomy) and auto-merges framework defaults unless `includeDefaults: false`. For errors outside your taxonomy (middleware, infrastructure, doc-only), chain `.documentError(...docs)`.
+
+- [ ] **Step 5.5: Verify docs-consistency script still passes**
+
+Run: `npm run check-docs`
+Expected: All invariants pass. If any invariant trips (e.g., an MD file now lacks a taxonomy reference that the script requires), fix the file.
+
+- [ ] **Step 5.6: Commit**
+
+```bash
+git add docs/http-integrations.md src/implementations/http/README.md CHANGELOG.md CLAUDE.md
+git commit -m "docs: update DocRegistry examples + changelog for v6.0.1 simplification"
+```
+
+---
+
+## Task 6: Update agent_config skill content
+
+**Files:**
+- Modify: `agent_config/claude-code/agents/ts-procedures-architect.md:40`
+- Modify: `agent_config/claude-code/skills/ts-procedures/SKILL.md:174`
+- Modify: `agent_config/claude-code/skills/ts-procedures/patterns.md:189`
+- Modify: `agent_config/claude-code/skills/ts-procedures/api-reference.md:280,298-304,788-821,878`
+- Modify: `agent_config/claude-code/skills/ts-procedures-review/checklist.md:77,118`
+- Modify: `agent_config/copilot/copilot-instructions.md:257`
+- Modify: `agent_config/cursor/cursorrules` (if it contains the same text)
+
+- [ ] **Step 6.1: Update `ts-procedures-architect.md`**
+
+Line 40 currently says:
+> Use `DocRegistry` to compose route docs from multiple builders — never manually wire `/docs` endpoints. Use `DocRegistry.fromTaxonomy(appErrors)` to seed envelope errors from your taxonomy + framework defaults in one call.
+
+Replace with:
+> Use `DocRegistry` to compose route docs from multiple builders — never manually wire `/docs` endpoints. Pass your taxonomy directly: `new DocRegistry({ errors: appErrors })` — framework defaults are auto-merged and deduped. For errors outside your taxonomy, chain `.documentError(...docs)`.
+
+- [ ] **Step 6.2: Update `skills/ts-procedures/SKILL.md:174`**
+
+The doc table mentions `DocRegistry + fromTaxonomy` — replace with `DocRegistry constructor + documentError()`.
+
+Run: `grep -n "DocRegistry\|fromTaxonomy" agent_config/claude-code/skills/ts-procedures/SKILL.md`
+Expected: Find the table row. Replace `DocRegistry + fromTaxonomy` with `DocRegistry (unified constructor, .documentError())`.
+
+- [ ] **Step 6.3: Update `patterns.md:189`**
+
+Read current example:
+
+```bash
+sed -n '185,200p' agent_config/claude-code/skills/ts-procedures/patterns.md
+```
+
+Replace the `DocRegistry.fromTaxonomy(appErrors, { basePath: '/api' })` call with `new DocRegistry({ errors: appErrors, basePath: '/api' })`. Add a follow-up example showing `.documentError()` for non-taxonomy errors.
+
+- [ ] **Step 6.4: Update `api-reference.md`**
+
+This file has several touch points:
+- Line 280: description of `description?` on taxonomy entry mentions "consumed by DocRegistry" — keep unchanged.
+- Lines 298-304: the `### taxonomyToErrorDocs(taxonomy)` section. Delete the entire section — it's no longer part of the public API. Add a note in its place:
+  > Taxonomy-to-doc conversion is handled automatically by `DocRegistry` when you pass your taxonomy to the constructor. There is no public helper.
+- Lines 788-821: the `class DocRegistry { ... }` signature. Update it:
+  - Remove the `static fromTaxonomy(...)` method.
+  - Add the `documentError(...docs: ErrorDoc[]): this` method.
+  - Update the constructor signature to show `errors: ErrorTaxonomy | ErrorDoc[]` and the new `includeDefaults` field.
+- Line 878: the bullet about `defaultErrors()` — keep but add a sentence noting consumers rarely need to call it directly since the constructor auto-merges.
+
+- [ ] **Step 6.5: Update `ts-procedures-review/checklist.md`**
+
+Two lines to update (77, 118). Replace both `DocRegistry.fromTaxonomy(appErrors)` references with `new DocRegistry({ errors: appErrors })`.
+
+- [ ] **Step 6.6: Update `copilot-instructions.md:257` and `cursorrules`**
+
+Read:
+
+```bash
+sed -n '253,260p' agent_config/copilot/copilot-instructions.md
+grep -n "fromTaxonomy\|DocRegistry" agent_config/cursor/cursorrules
+```
+
+Replace `DocRegistry.fromTaxonomy(appErrors, { basePath: '/api' }).from(apiApp).toJSON()` with `new DocRegistry({ errors: appErrors, basePath: '/api' }).from(apiApp).toJSON()` in both files.
+
+- [ ] **Step 6.7: Run docs consistency check**
+
+Run: `npm run check-docs`
+Expected: All invariants still pass (we haven't removed taxonomy references; we've just simplified the API they describe).
+
+- [ ] **Step 6.8: Commit**
+
+```bash
+git add agent_config/
+git commit -m "docs(agent_config): update all skill content for DocRegistry v6.0.1 simplification"
+```
+
+---
+
+## Task 7: Final verification
+
+**Files:** (none modified)
+
+- [ ] **Step 7.1: Run the full test suite**
+
+Run: `npm run test`
+Expected: All tests pass, zero failures.
+
+- [ ] **Step 7.2: Run the linter**
+
+Run: `npm run lint`
+Expected: Zero errors.
+
+- [ ] **Step 7.3: Run the build**
+
+Run: `npm run build`
+Expected: TypeScript compilation succeeds, `build/` directory populated, no type errors.
+
+- [ ] **Step 7.4: Run the docs-consistency script**
+
+Run: `npm run check-docs`
+Expected: All invariants pass.
+
+- [ ] **Step 7.5: Grep the repo for any remaining `fromTaxonomy` references**
+
+Run: `grep -rn "fromTaxonomy" --include="*.ts" --include="*.md" --include="*.json" .`
+Expected: Zero hits outside of `CHANGELOG.md` (where the v6.0.0 historical entry and the v6.0.1 migration guide legitimately mention it).
+
+- [ ] **Step 7.6: Grep for remaining `taxonomyToErrorDocs` references outside intended locations**
+
+Run: `grep -rn "taxonomyToErrorDocs" --include="*.ts" --include="*.md" .`
+Expected: Only in `src/implementations/http/error-taxonomy.ts` (declaration + internal JSDoc), `src/implementations/http/doc-registry.ts` (internal import), and `CHANGELOG.md` (historical mentions). Zero hits in `agent_config/` or `docs/`.
+
+- [ ] **Step 7.7: Verify the CHANGELOG for v6.0.0 still accurately describes what shipped in v6.0.0**
+
+Don't rewrite history — v6.0.0 did ship `fromTaxonomy`, and the v6.0.0 entry should say so. The v6.0.1 entry handles the removal.
+
+- [ ] **Step 7.8: Bump `package.json` version**
+
+Edit `package.json` and bump `version` from `6.0.0` to `6.0.1`. (Or 7.0.0 if the user considers the removal of a public API major — confirm before bumping.)
+
+- [ ] **Step 7.9: Final commit**
+
+```bash
+git add package.json
+git commit -m "chore: bump version to 6.0.1"
+```
+
+- [ ] **Step 7.10: Run `npm run prepublishOnly` (if configured) as a dry-run**
+
+Run: `npm pack --dry-run`
+Expected: Package contents look correct; no stale `fromTaxonomy` mentions in included files beyond the changelog.
+
+---
+
+## Summary
+
+After this plan:
+- **Single way to construct** `DocRegistry` — the plain constructor.
+- **One polymorphic `errors` field** accepts the user's runtime taxonomy directly, with auto-convert/auto-defaults/auto-dedupe all for free.
+- **Fluent `.documentError()` method** covers the rare extension case cleanly.
+- **`fromTaxonomy` is gone**; `taxonomyToErrorDocs` is internal.
+- **"Taxonomy" vocabulary** lives only where it originates (`defineErrorTaxonomy`) — it vanishes from downstream DocRegistry-facing APIs and docs.
+- **Backward-compat bridge:** existing `new DocRegistry({ errors: [ErrorDoc, ...] })` call sites still work and now benefit from auto-dedupe + auto-defaults (one behavioral change noted in the changelog).