ts-procedures 8.6.0 → 9.1.0

package/docs/superpowers/plans/2026-06-05-dx-feedback-round.md

@@ -1,1292 +0,0 @@
-# DX Feedback Round 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:** Resolve five downstream DX findings — codegen `--help`, an offline `writeDocEnvelope` helper, shared codegen types keyed on `$id`, function-valued client headers for dynamic auth, and scaffolder file-naming knobs.
-
-**Architecture:** Five mostly-independent changes. #1/#2/#4 are self-contained and fully TDD-able. #3 (shared types) is gated behind a verification spike (Task 8) because the emission mechanism depends on how ajsc v7.2.0 handles a `$ref`→named-type; the spike picks `$ref`-reference vs post-emit substitution before the emission tasks run. #5 edits the AI-skill markdown + templates (no runtime code).
-
-**Tech Stack:** TypeScript (ESM, `.js` import specifiers), Vitest, AJV/TypeBox, ajsc (dynamic import), Hono.
-
-**Spec:** `docs/superpowers/specs/2026-06-05-dx-feedback-round-design.md`
-
-**Conventions to follow:**
-- Run a single test file: `npx vitest run <path>`. Full suite: `npm run test`. Lint: `npm run lint`. Build: `npm run build`.
-- ESM imports use `.js` specifiers even for `.ts` sources.
-- Commit after each green task. Branch is `dx-feedback` (already checked out).
-
----
-
-## File Structure
-
-| File | Responsibility | Tasks |
-|------|----------------|-------|
-| `src/codegen/bin/flag-specs.ts` (new) | Structured flag catalog + `formatHelp()` | 1, 2 |
-| `src/codegen/bin/cli.ts` (modify) | Consume flag specs; `--help`/`-h`/bare → usage; exclude help from suggester | 1, 2, 3 |
-| `src/codegen/bin/cli.test.ts` (modify/locate) | CLI behaviour tests | 1, 2, 3 |
-| `src/doc-envelope.ts` (new) + package export | `writeDocEnvelope(source, path)` helper | 4, 5 |
-| `src/codegen/collect-models.ts` (new) | Walk routes, collect `$id` subschemas, dedup, collision-detect | 9, 10 |
-| `src/codegen/emit-models.ts` (new) | Emit `_models.ts` (generated + re-exported) | 11 |
-| `src/codegen/emit-scope.ts` (modify) | Reference hoisted models instead of inlining | 12 |
-| `src/codegen/targets/ts/run.ts` (modify) | Wire collect→emit-models→scope; emit `_models.ts` | 12 |
-| `src/codegen/index.ts` + `pipeline.ts` + `targets/_shared/target-run.ts` (modify) | Thread `shareModels` + `sharedTypesImport` options | 12 |
-| `src/codegen/bin/cli.ts` (modify) | `--share-models`/`--no-share-models` flag + `sharedTypesImport` config | 13 |
-| `src/client/types.ts` (modify) | `HeadersInit` type on `ProcedureCallDefaults.headers` | 6 |
-| `src/client/resolve-options.ts` (modify) | async `resolveHeaders`; `applyRequestOptions` async | 6 |
-| `src/client/call.ts` + `stream.ts` (modify) | `await applyRequestOptions(...)` | 6 |
-| `docs/client-and-codegen.md` (modify) | Auth seam section | 7 |
-| `agent_config/.../skills/ts-procedures/SKILL.md` + `templates/*.md` (modify) | `fileNameStyle` + `groupBy` scaffold args | 14 |
-
----
-
-## #1 — `--help` for the codegen CLI
-
-### Task 1: Structured flag catalog with `formatHelp()`
-
-**Files:**
-- Create: `src/codegen/bin/flag-specs.ts`
-- Test: `src/codegen/bin/flag-specs.test.ts`
-
-- [ ] **Step 1: Write the failing test**
-
-```ts
-// src/codegen/bin/flag-specs.test.ts
-import { describe, it, expect } from 'vitest'
-import { FLAG_SPECS, KNOWN_FLAGS, formatHelp } from './flag-specs.js'
-
-describe('flag-specs', () => {
-  it('derives KNOWN_FLAGS from the spec table', () => {
-    expect(KNOWN_FLAGS).toContain('--url')
-    expect(KNOWN_FLAGS).toContain('--service-name')
-    expect(KNOWN_FLAGS).toContain('--target')
-    // every spec name appears
-    for (const spec of FLAG_SPECS) expect(KNOWN_FLAGS).toContain(spec.name)
-  })
-
-  it('formatHelp lists every flag with its description, grouped', () => {
-    const help = formatHelp()
-    expect(help).toMatch(/Usage: ts-procedures-codegen/)
-    for (const spec of FLAG_SPECS) {
-      expect(help).toContain(spec.name)
-      expect(help).toContain(spec.description)
-    }
-    // group headers present
-    expect(help).toMatch(/Source/)
-    expect(help).toMatch(/Targets/)
-  })
-
-  it('does not list --help/-h as a real codegen flag in KNOWN_FLAGS suggestion set', () => {
-    // help is handled separately; it must NOT be a did-you-mean candidate
-    expect(KNOWN_FLAGS).not.toContain('--help')
-    expect(KNOWN_FLAGS).not.toContain('-h')
-  })
-})
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `npx vitest run src/codegen/bin/flag-specs.test.ts`
-Expected: FAIL — `flag-specs.js` not found / exports missing.
-
-- [ ] **Step 3: Write `flag-specs.ts`**
-
-Port every current flag (cli.ts:87-98, `KNOWN_FLAGS`) into a structured table. Include the value flags' `arg` placeholders and one-line descriptions.
-
-```ts
-// src/codegen/bin/flag-specs.ts
-export interface FlagSpec {
-  name: string
-  arg?: string
-  description: string
-  group: 'Source' | 'Output' | 'Codegen' | 'Targets' | 'Misc'
-  default?: string
-}
-
-export const FLAG_SPECS: readonly FlagSpec[] = [
-  // Source
-  { name: '--url', arg: '<url>', description: 'Fetch the doc envelope from a running server', group: 'Source' },
-  { name: '--file', arg: '<path>', description: 'Read the doc envelope from a JSON file (see writeDocEnvelope)', group: 'Source' },
-  { name: '--config', arg: '<path>', description: 'Load options from a JSON config file', group: 'Source' },
-  // Output
-  { name: '--out', arg: '<dir>', description: 'Output directory for generated files', group: 'Output' },
-  { name: '--dry-run', description: 'Print what would be written without touching disk', group: 'Output' },
-  { name: '--clean-out-dir', description: 'Prune orphaned generator-owned files before writing', group: 'Output', default: 'on' },
-  { name: '--no-clean-out-dir', description: 'Disable orphan pruning', group: 'Output' },
-  { name: '--watch', description: 'Regenerate on envelope change', group: 'Output' },
-  { name: '--interval', arg: '<ms>', description: 'Poll interval for --watch (default 3000)', group: 'Output' },
-  // Codegen
-  { name: '--service-name', arg: '<name>', description: 'Service identifier driving generated names', group: 'Codegen', default: 'Api' },
-  { name: '--namespace-types', description: 'Wrap types in nested namespaces', group: 'Codegen', default: 'on' },
-  { name: '--no-namespace-types', description: 'Flat type names', group: 'Codegen' },
-  { name: '--self-contained', description: 'Bundle the client runtime into the output dir', group: 'Codegen', default: 'on' },
-  { name: '--no-self-contained', description: 'Import the client runtime from ts-procedures/client', group: 'Codegen' },
-  { name: '--client-import-path', arg: '<path>', description: 'Override the client runtime import path', group: 'Codegen' },
-  { name: '--share-models', description: 'Hoist $id-bearing schemas into a shared _models.ts', group: 'Codegen', default: 'on' },
-  { name: '--no-share-models', description: 'Inline every type per route (legacy behaviour)', group: 'Codegen' },
-  { name: '--jsdoc', description: 'Emit JSDoc on generated types', group: 'Codegen', default: 'on' },
-  { name: '--no-jsdoc', description: 'Suppress JSDoc', group: 'Codegen' },
-  { name: '--enum-style', arg: '<union|enum>', description: 'How to emit enums (namespace mode)', group: 'Codegen' },
-  { name: '--depluralize', description: 'Depluralize extracted array-item type names', group: 'Codegen' },
-  { name: '--array-item-naming', arg: '<name|false>', description: 'Naming for extracted array-item types', group: 'Codegen' },
-  { name: '--uncountable-words', arg: '<csv>', description: 'Words exempt from depluralization', group: 'Codegen' },
-  // Targets
-  { name: '--target', arg: '<ts|kotlin|swift>', description: 'Output language', group: 'Targets', default: 'ts' },
-  { name: '--kotlin-package', arg: '<pkg>', description: 'Package for Kotlin output (required for --target kotlin)', group: 'Targets' },
-  { name: '--kotlin-serializer', arg: '<kotlinx|none>', description: 'Kotlin serialization annotations', group: 'Targets', default: 'kotlinx' },
-  { name: '--swift-serializer', arg: '<codable|none>', description: 'Swift Codable conformance', group: 'Targets', default: 'codable' },
-  { name: '--swift-access-level', arg: '<public|internal>', description: 'Swift access level', group: 'Targets', default: 'public' },
-  { name: '--unsupported-unions', arg: '<throw|fallback>', description: 'Behaviour for untagged oneOf schemas', group: 'Targets', default: 'throw' },
-]
-
-export const KNOWN_FLAGS: readonly string[] = FLAG_SPECS.map((s) => s.name)
-
-const GROUP_ORDER: FlagSpec['group'][] = ['Source', 'Output', 'Codegen', 'Targets', 'Misc']
-
-export function formatHelp(): string {
-  const lines: string[] = []
-  lines.push('Usage: ts-procedures-codegen --out <dir> (--url <url> | --file <path>) [options]')
-  lines.push('')
-  lines.push('Generate a typed client from a ts-procedures doc envelope.')
-  lines.push('')
-  const col = Math.max(...FLAG_SPECS.map((s) => (s.name + (s.arg ? ' ' + s.arg : '')).length)) + 2
-  for (const group of GROUP_ORDER) {
-    const specs = FLAG_SPECS.filter((s) => s.group === group)
-    if (specs.length === 0) continue
-    lines.push(`${group}:`)
-    for (const s of specs) {
-      const left = s.name + (s.arg ? ' ' + s.arg : '')
-      const def = s.default ? ` (default: ${s.default})` : ''
-      lines.push(`  ${left.padEnd(col)}${s.description}${def}`)
-    }
-    lines.push('')
-  }
-  lines.push('  -h, --help      Show this help and exit')
-  return lines.join('\n')
-}
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `npx vitest run src/codegen/bin/flag-specs.test.ts`
-Expected: PASS.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/codegen/bin/flag-specs.ts src/codegen/bin/flag-specs.test.ts
-git commit -m "feat(codegen): structured flag catalog with formatHelp()"
-```
-
-### Task 2: Replace `KNOWN_FLAGS` in cli.ts with the spec-derived one
-
-**Files:**
-- Modify: `src/codegen/bin/cli.ts` (remove the literal `KNOWN_FLAGS` at 87-98, import from `flag-specs.js`)
-
-- [ ] **Step 1: Update cli.ts to import the catalog**
-
-Delete the literal `const KNOWN_FLAGS = [...] as const` block (lines 87-98). Add at the top with the other imports:
-
-```ts
-import { KNOWN_FLAGS, formatHelp } from './flag-specs.js'
-```
-
-`closestKnownFlag` already iterates `KNOWN_FLAGS`; it now reads the imported array (a `readonly string[]`). No other change needed in `closestKnownFlag`.
-
-- [ ] **Step 2: Run the existing CLI tests to verify no regression**
-
-Run: `npx vitest run src/codegen/bin/cli.test.ts`
-Expected: PASS (unknown-flag/did-you-mean tests still green — same flag set).
-
-- [ ] **Step 3: Build to confirm no dangling references**
-
-Run: `npm run build`
-Expected: no TS errors referencing `KNOWN_FLAGS`.
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add src/codegen/bin/cli.ts
-git commit -m "refactor(codegen): derive KNOWN_FLAGS from the flag-specs catalog"
-```
-
-### Task 3: Handle `--help`/`-h`/bare invocation in the CLI entrypoint
-
-**Files:**
-- Modify: `src/codegen/bin/cli.ts` (the `main()` function — read lines 359-end to find argv handling and `process.exit`)
-- Test: `src/codegen/bin/cli.test.ts`
-
-- [ ] **Step 1: Write the failing test**
-
-```ts
-// add to src/codegen/bin/cli.test.ts
-import { shouldShowHelp } from './cli.js'
-import { formatHelp } from './flag-specs.js'
-
-describe('--help handling', () => {
-  it('shouldShowHelp true for --help, -h, and bare (no args)', () => {
-    expect(shouldShowHelp(['--help'])).toBe(true)
-    expect(shouldShowHelp(['-h'])).toBe(true)
-    expect(shouldShowHelp([])).toBe(true)
-  })
-  it('shouldShowHelp false when real flags are present', () => {
-    expect(shouldShowHelp(['--url', 'http://x', '--out', 'gen'])).toBe(false)
-  })
-  it('help text covers the full flag surface', () => {
-    const help = formatHelp()
-    expect(help).toContain('--watch')
-    expect(help).toContain('--enum-style')
-    expect(help).toContain('--target')
-  })
-})
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `npx vitest run src/codegen/bin/cli.test.ts`
-Expected: FAIL — `shouldShowHelp` not exported.
-
-- [ ] **Step 3: Add `shouldShowHelp` and wire it into `main()`**
-
-Add the predicate near `parseArgs`:
-
-```ts
-/**
- * True when the CLI should print usage and exit 0: an explicit --help/-h, or a
- * bare invocation with no args. --help is handled here (not in parseArgs) so it
- * never reaches the unknown-flag branch and never appears in did-you-mean.
- */
-export function shouldShowHelp(argv: string[]): boolean {
-  if (argv.length === 0) return true
-  return argv.includes('--help') || argv.includes('-h')
-}
-```
-
-In `main()` (read the existing function; it currently does `extractConfigPath` → `loadConfigFile` → `parseArgs` → `generateClient`), add as the very first lines after reading `argv`:
-
-```ts
-const argv = process.argv.slice(2)
-if (shouldShowHelp(argv)) {
-  console.log(formatHelp())
-  process.exit(0)
-}
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `npx vitest run src/codegen/bin/cli.test.ts`
-Expected: PASS.
-
-- [ ] **Step 5: Manual smoke check**
-
-Run: `npm run build && node build/codegen/bin/cli.js --help`
-Expected: usage text, exit 0. Then `node build/codegen/bin/cli.js --targt ts --out x --url y` still errors with the did-you-mean suggestion.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/codegen/bin/cli.ts src/codegen/bin/cli.test.ts
-git commit -m "feat(codegen): --help/-h/bare invocation prints usage and exits 0"
-```
-
----
-
-## #2 — `writeDocEnvelope` offline helper
-
-### Task 4: `writeDocEnvelope(source, path)` helper
-
-**Files:**
-- Create: `src/doc-envelope.ts`
-- Test: `src/doc-envelope.test.ts`
-
-- [ ] **Step 1: Write the failing test**
-
-```ts
-// src/doc-envelope.test.ts
-import { describe, it, expect, afterEach } from 'vitest'
-import { readFile, rm, mkdtemp } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { writeDocEnvelope } from './doc-envelope.js'
-import type { DocEnvelope } from './implementations/types.js'
-
-const envelope: DocEnvelope = { basePath: '', headers: [], errors: [], routes: [] }
-
-describe('writeDocEnvelope', () => {
-  let dir: string
-  afterEach(async () => { if (dir) await rm(dir, { recursive: true, force: true }) })
-
-  it('writes a plain DocEnvelope as pretty JSON', async () => {
-    dir = await mkdtemp(join(tmpdir(), 'tsp-'))
-    const out = join(dir, 'nested', 'docs.json')
-    await writeDocEnvelope(envelope, out)
-    const parsed = JSON.parse(await readFile(out, 'utf8'))
-    expect(parsed).toEqual(envelope)
-  })
-
-  it('accepts a builder-like object with toDocEnvelope()', async () => {
-    dir = await mkdtemp(join(tmpdir(), 'tsp-'))
-    const out = join(dir, 'docs.json')
-    const builderLike = { toDocEnvelope: () => envelope }
-    await writeDocEnvelope(builderLike, out)
-    const parsed = JSON.parse(await readFile(out, 'utf8'))
-    expect(parsed).toEqual(envelope)
-  })
-
-  it('accepts a DocRegistry-like object (toJSON)', async () => {
-    dir = await mkdtemp(join(tmpdir(), 'tsp-'))
-    const out = join(dir, 'docs.json')
-    const registryLike = { toJSON: () => envelope }
-    await writeDocEnvelope(registryLike, out)
-    expect(JSON.parse(await readFile(out, 'utf8'))).toEqual(envelope)
-  })
-})
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `npx vitest run src/doc-envelope.test.ts`
-Expected: FAIL — module not found.
-
-- [ ] **Step 3: Write the helper**
-
-```ts
-// src/doc-envelope.ts
-import { mkdir, writeFile } from 'node:fs/promises'
-import { dirname } from 'node:path'
-import type { DocEnvelope } from './implementations/types.js'
-
-/** A built builder/registry that can produce a DocEnvelope. */
-export type DocEnvelopeSource =
-  | DocEnvelope
-  | { toDocEnvelope(): DocEnvelope }
-  | { toJSON(): DocEnvelope }
-
-function resolveEnvelope(source: DocEnvelopeSource): DocEnvelope {
-  if (typeof (source as { toDocEnvelope?: unknown }).toDocEnvelope === 'function') {
-    return (source as { toDocEnvelope(): DocEnvelope }).toDocEnvelope()
-  }
-  if (typeof (source as { toJSON?: unknown }).toJSON === 'function') {
-    return (source as { toJSON(): DocEnvelope }).toJSON()
-  }
-  return source as DocEnvelope
-}
-
-/**
- * Serializes a doc envelope to disk as pretty JSON so codegen can run offline
- * via `--file <path>` without a running server. Accepts a plain `DocEnvelope`,
- * a builder exposing `toDocEnvelope()`, or a `DocRegistry` exposing `toJSON()`.
- * Parent directories are created as needed.
- */
-export async function writeDocEnvelope(source: DocEnvelopeSource, path: string): Promise<void> {
-  const envelope = resolveEnvelope(source)
-  await mkdir(dirname(path), { recursive: true })
-  await writeFile(path, JSON.stringify(envelope, null, 2), 'utf8')
-}
-```
-
-> Note: if `DocEnvelope` is not exported from `./implementations/types.js`, import it from wherever `DocRegistry` re-exports it (`./implementations/http/doc-registry.js` re-exports `DocEnvelope`). Verify the correct specifier when implementing.
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `npx vitest run src/doc-envelope.test.ts`
-Expected: PASS.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/doc-envelope.ts src/doc-envelope.test.ts
-git commit -m "feat: writeDocEnvelope helper for offline codegen"
-```
-
-### Task 5: Export `writeDocEnvelope` from the package entrypoint + document the loop
-
-**Files:**
-- Modify: the package root barrel (find it: `grep -n "writeDocEnvelope\|export" src/index.ts` and check `package.json` `exports`/`main`)
-- Modify: `docs/client-and-codegen.md` (add a short "Offline codegen" subsection)
-
-- [ ] **Step 1: Add the export**
-
-In the root barrel (`src/index.ts` or the file `package.json` `main`/`exports` points to), add:
-
-```ts
-export { writeDocEnvelope, type DocEnvelopeSource } from './doc-envelope.js'
-```
-
-Confirm it lands in a publicly-exported subpath. If the package exposes subpaths via `package.json` `exports`, ensure either the root or a sensible subpath re-exports it.
-
-- [ ] **Step 2: Document the offline loop**
-
-In `docs/client-and-codegen.md`, add a subsection:
-
-```markdown
-### Offline codegen (no running server)
-
-Emit the envelope to disk once, then generate against the file:
-
-```ts
-// scripts/emit-docs.ts
-import { writeDocEnvelope } from 'ts-procedures'
-import { buildApp } from '../src/server/app.js' // your built HonoAppBuilder / DocRegistry
-
-const builder = buildApp()        // whatever produces your built app/registry
-await writeDocEnvelope(builder, 'docs.json')
-```
-
-```bash
-tsx scripts/emit-docs.ts
-npx ts-procedures-codegen --file docs.json --out src/generated --service-name Api
-```
-
-`writeDocEnvelope` accepts a built `HonoAppBuilder`, a `DocRegistry`, or a plain
-`DocEnvelope`. No running HTTP server required.
-```
-
-- [ ] **Step 3: Build + test**
-
-Run: `npm run build && npm run test`
-Expected: PASS.
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add src/index.ts docs/client-and-codegen.md
-git commit -m "feat: export writeDocEnvelope; document offline codegen loop"
-```
-
----
-
-## #4 — Function-valued client headers (dynamic auth)
-
-### Task 6: `HeadersInit` function support + async header resolution
-
-**Files:**
-- Modify: `src/client/types.ts:202-208` (`ProcedureCallDefaults.headers`)
-- Modify: `src/client/resolve-options.ts:85-95` (`resolveHeaders` → async) and `140-158` (`applyRequestOptions` → async)
-- Modify: `src/client/call.ts:58` and `src/client/stream.ts:189` (`await applyRequestOptions(...)`)
-- Test: `src/client/resolve-options.test.ts` (locate; create if absent)
-
-- [ ] **Step 1: Write the failing test**
-
-```ts
-// src/client/resolve-options.test.ts (add)
-import { describe, it, expect } from 'vitest'
-import { applyRequestOptions } from './resolve-options.js'
-import type { AdapterRequest } from './types.js'
-
-const baseReq: AdapterRequest = { method: 'POST', url: '/x', headers: undefined, body: undefined }
-
-describe('function-valued headers', () => {
-  it('resolves a sync function-valued default header', async () => {
-    const { request } = await applyRequestOptions(baseReq, { headers: () => ({ Authorization: 'Bearer t1' }) }, undefined)
-    expect(request.headers).toMatchObject({ Authorization: 'Bearer t1' })
-  })
-
-  it('resolves an async function-valued header', async () => {
-    const { request } = await applyRequestOptions(
-      baseReq,
-      { headers: async () => ({ Authorization: 'Bearer async' }) },
-      undefined,
-    )
-    expect(request.headers).toMatchObject({ Authorization: 'Bearer async' })
-  })
-
-  it('per-call headers win over default headers (both functions)', async () => {
-    const { request } = await applyRequestOptions(
-      baseReq,
-      { headers: () => ({ Authorization: 'Bearer default', 'x-a': '1' }) },
-      { headers: () => ({ Authorization: 'Bearer call' }) },
-    )
-    expect(request.headers).toMatchObject({ Authorization: 'Bearer call', 'x-a': '1' })
-  })
-
-  it('static record path still works', async () => {
-    const { request } = await applyRequestOptions(baseReq, { headers: { 'x-s': 'v' } }, undefined)
-    expect(request.headers).toMatchObject({ 'x-s': 'v' })
-  })
-})
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `npx vitest run src/client/resolve-options.test.ts`
-Expected: FAIL — `applyRequestOptions` is sync / returns non-promise; function headers not resolved.
-
-- [ ] **Step 3: Update the `headers` type in `types.ts`**
-
-Replace `headers?: Record<string, string>` on `ProcedureCallDefaults` (line 205) with a named type, and add the alias above the interface:
-
-```ts
-/**
- * Request headers as a static record OR a (possibly async) function evaluated
- * per request. Use the function form for values that change between calls —
- * e.g. a rotating bearer token: `headers: () => ({ Authorization: \`Bearer ${session.token}\` })`.
- * A static record captured at construction goes stale; a function is re-evaluated each call.
- */
-export type HeadersInit =
-  | Record<string, string>
-  | (() => Record<string, string> | Promise<Record<string, string>>)
-```
-
-```ts
-export interface ProcedureCallDefaults {
-  signal?: AbortSignal
-  timeout?: number
-  headers?: HeadersInit
-  basePath?: string
-  meta?: RequestMeta
-}
-```
-
-(`ProcedureCallOptions extends ProcedureCallDefaults`, so per-call inherits it automatically.) Update the `headers` JSDoc bullet (lines 196-197) to mention the function form.
-
-- [ ] **Step 4: Make `resolveHeaders` async and `applyRequestOptions` async**
-
-In `resolve-options.ts`:
-
-```ts
-async function resolveHeadersValue(
-  h: HeadersInit | undefined,
-): Promise<Record<string, string> | undefined> {
-  if (h == null) return undefined
-  return typeof h === 'function' ? await h() : h
-}
-
-/**
- * Merges headers with precedence: default < per-call. Function-valued headers
- * are evaluated (awaited) per request. Returns undefined if none would be set.
- */
-export async function resolveHeaders(
-  defaults: ProcedureCallDefaults | undefined,
-  options: ProcedureCallOptions | undefined,
-): Promise<Record<string, string> | undefined> {
-  const defaultHeaders = await resolveHeadersValue(defaults?.headers)
-  const callHeaders = await resolveHeadersValue(options?.headers)
-  if (!defaultHeaders && !callHeaders) return undefined
-  return { ...defaultHeaders, ...callHeaders }
-}
-```
-
-Make `applyRequestOptions` async and await the headers:
-
-```ts
-export async function applyRequestOptions(
-  request: AdapterRequest,
-  defaults: ProcedureCallDefaults | undefined,
-  options: ProcedureCallOptions | undefined,
-): Promise<ApplyRequestOptionsResult> {
-  const signalSources = resolveSignalSources(defaults, options)
-  const resolvedHeaders = await resolveHeaders(defaults, options)
-  const meta = resolveMeta(defaults, options)
-
-  const headers =
-    resolvedHeaders || request.headers
-      ? { ...resolvedHeaders, ...request.headers }
-      : undefined
-
-  return {
-    request: { ...request, headers, signal: signalSources.combined, meta },
-    signalSources,
-  }
-}
-```
-
-Add `HeadersInit` to the type imports at the top of `resolve-options.ts`.
-
-- [ ] **Step 5: Await the call sites**
-
-`src/client/call.ts:58` → `const applied = await applyRequestOptions(request, defaults, options)`.
-`src/client/stream.ts:189` → `const applied = await applyRequestOptions(request, defaults, options)`.
-Both are already inside `async` functions.
-
-- [ ] **Step 6: Run tests**
-
-Run: `npx vitest run src/client/resolve-options.test.ts src/client/call.test.ts`
-Expected: PASS. Then `npm run test` to catch any other caller of `applyRequestOptions`/`resolveHeaders` that now needs `await` (grep first: `grep -rn "applyRequestOptions\|resolveHeaders" src`).
-
-- [ ] **Step 7: Build**
-
-Run: `npm run build`
-Expected: clean. The self-contained `_client.ts`/`_types.ts` are emitted from these sources, so regeneration picks up the new type automatically.
-
-- [ ] **Step 8: Commit**
-
-```bash
-git add src/client/types.ts src/client/resolve-options.ts src/client/call.ts src/client/stream.ts src/client/resolve-options.test.ts
-git commit -m "feat(client): function-valued headers for dynamic auth (async-resolved per request)"
-```
-
-### Task 7: Document the auth seam
-
-**Files:**
-- Modify: `docs/client-and-codegen.md` (the hooks/auth area near lines 36-39 and 356-389)
-
-- [ ] **Step 1: Add/expand the auth section**
-
-```markdown
-### Authentication (rotating tokens)
-
-A bearer token that only exists after login — and rotates — must NOT live in a
-static `headers` record: it is captured once at construction and goes stale after
-the next login. Use one of the two dynamic seams instead.
-
-**Function-valued `headers` (recommended for auth):**
-
-```ts
-createClient({
-  // ...
-  defaults: {
-    headers: () => ({ Authorization: `Bearer ${session.token}` }), // re-evaluated per call
-  },
-})
-```
-
-The function may be async (`async () => ({ ... })`) and is awaited before each
-request. Per-call `headers` still override defaults.
-
-**`onBeforeRequest` hook (when you need the full request):**
-
-```ts
-hooks: {
-  onBeforeRequest(ctx) {
-    ctx.request.headers = { ...ctx.request.headers, Authorization: `Bearer ${getToken()}` }
-    return ctx
-  },
-}
-```
-
-> ⚠️ A token placed in a static `headers: { Authorization: ... }` record compiles
-> but silently goes stale. Reach for the function form or the hook.
-```
-
-- [ ] **Step 2: Commit**
-
-```bash
-git add docs/client-and-codegen.md
-git commit -m "docs(client): document function-valued headers and onBeforeRequest as the auth seams"
-```
-
----
-
-## #3 — Shared types keyed on `$id`
-
-### Task 8: Verification spike (gates the emission mechanism)
-
-**Files:**
-- Create (throwaway, removed after): `src/codegen/__spike__/ajsc-ref.test.ts`
-
-This task produces a **decision**, not shipped code. Record the outcome in the plan's Task 9-12 before implementing them.
-
-- [ ] **Step 1: Confirm nested `$id` survives `extractJsonSchema`**
-
-Write a quick test feeding a TypeBox schema with a nested `$id` through the same path `toDocEnvelope` uses (`src/schema/extract-json-schema.ts` → whatever the rpc/api doc builders call). Assert the nested `$id` is present in the resulting JSON schema.
-
-```ts
-import { describe, it, expect } from 'vitest'
-import { Type } from 'typebox'
-import { extractJsonSchema } from '../../schema/extract-json-schema.js' // verify exact path/name
-
-describe('spike: nested $id survival', () => {
-  it('keeps $id on a nested object schema', () => {
-    const Message = Type.Object({ id: Type.String() }, { $id: 'urn:msg', title: 'Message' })
-    const Thread = Type.Object({ messages: Type.Array(Message) }, { $id: 'urn:thread', title: 'Thread' })
-    const js = extractJsonSchema(Thread) as any
-    // assert urn:msg is reachable somewhere in js
-    expect(JSON.stringify(js)).toContain('urn:msg')
-  })
-})
-```
-
-Run it. **If `$id` is stripped:** the first emission task (Task 9) must first fix extraction to preserve nested `$id`. Record which.
-
-- [ ] **Step 2: Probe ajsc `$ref` behaviour**
-
-Using the same dynamic `import('ajsc')` path as `src/codegen/emit-types.ts` (`jsonSchemaToExtractedTypes`), feed a schema shaped like:
-
-```json
-{ "type": "object", "properties": { "msg": { "$ref": "#/$defs/Message" } },
-  "$defs": { "Message": { "type": "object", "title": "Message", "properties": { "id": { "type": "string" } } } } }
-```
-
-Observe whether ajsc emits a **reference** to a `Message` type (preferred) or **inlines** the object. Record the result.
-
-- [ ] **Step 3: Record the decision**
-
-**SPIKE OUTCOME (2026-06-05):**
-- **Probe 1:** nested `$id`/`title` **fully survive** into the route JSON schema (`extractJsonSchema` is a no-op for TypeBox; TypeBox inlines referenced objects but preserves `$id`/`title` on every copy). → Task 9 does **not** need to fix extraction.
-- **Probe 2:** ajsc 7.2.0 **inlines** a `$ref` target and re-extracts it **named by property**, with no dedup and no verbatim-type / external-ref / `$defs`-reference option (full option surface checked; `tsType`/`x-tsType`/bare-`$ref` all ignored or rejected; `EmitResult.imports` is always empty for TS). So **Mechanism A is not viable.**
-- **Re-spike → chosen mechanism: Mechanism C (placeholder-token).** Empirically verified clean and property-name-independent:
-  1. Walk each route schema; replace every subschema whose `$id` is in the model registry with `{ const: '__MODELREF__<ModelName>__' }` (identity comes from `$id`, not property name; reused models get the same token → free dedup).
-  2. Call ajsc **unchanged** (both `inlineTypes` modes; the token is a string-literal type, never extracted as a sub-type, survives inside `Array<...>`).
-  3. Single deterministic global replace on the emitted string: `/["']__MODELREF__([A-Za-z_$][\w$]*)__["']/g` → `$1`, accumulating captured names into a per-file import set.
-  4. Emit `import type { Message, … } from './_models.js'` from the collected set. Emit `_models.ts` standalone via `emitTypescript(modelSchema, { rootTypeName, inlineTypes:false })`.
-  - This avoids the brittle per-property rename machinery of Mechanism B entirely. **Task 12 implements Mechanism C.**
-
-- [ ] **Step 4: Remove the spike files; commit the decision note**
-
-```bash
-rm -rf src/codegen/__spike__
-git commit --allow-empty -m "chore(codegen): spike — chose Mechanism C (placeholder-token) for \$id model emission (see plan Task 8)"
-```
-
-### Task 9: `collect-models.ts` — registry + collision detection
-
-**Files:**
-- Create: `src/codegen/collect-models.ts`
-- Test: `src/codegen/collect-models.test.ts`
-
-- [ ] **Step 1: Write the failing test**
-
-```ts
-// src/codegen/collect-models.test.ts
-import { describe, it, expect } from 'vitest'
-import { collectModels } from './collect-models.js'
-
-const messageSchema = { type: 'object', $id: 'urn:msg', title: 'Message', properties: { id: { type: 'string' } } }
-
-it('collects each $id subschema once, named from title', () => {
-  const routes = [
-    { jsonSchema: { response: messageSchema } },
-    { jsonSchema: { body: { type: 'object', properties: { msg: messageSchema } } } },
-  ] as any
-  const models = collectModels(routes)
-  expect(models.map((m) => m.name)).toEqual(['Message'])
-  expect(models[0].id).toBe('urn:msg')
-})
-
-it('throws on $id collision with divergent body', () => {
-  const a = { type: 'object', $id: 'urn:x', title: 'X', properties: { a: { type: 'string' } } }
-  const b = { type: 'object', $id: 'urn:x', title: 'X', properties: { b: { type: 'number' } } }
-  const routes = [{ jsonSchema: { response: a } }, { jsonSchema: { body: b } }] as any
-  expect(() => collectModels(routes)).toThrow(/urn:x/)
-})
-
-it('disambiguates distinct $ids that derive the same name', () => {
-  const m1 = { type: 'object', $id: 'urn:a/message', title: 'Message', properties: { a: { type: 'string' } } }
-  const m2 = { type: 'object', $id: 'urn:b/message', title: 'Message', properties: { b: { type: 'string' } } }
-  const models = collectModels([{ jsonSchema: { response: m1 } }, { jsonSchema: { body: m2 } }] as any)
-  expect(models.map((m) => m.name).sort()).toEqual(['Message', 'Message2'])
-})
-
-it('ignores schemas without $id', () => {
-  const routes = [{ jsonSchema: { response: { type: 'object', title: 'Loose', properties: {} } } }] as any
-  expect(collectModels(routes)).toEqual([])
-})
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `npx vitest run src/codegen/collect-models.test.ts`
-Expected: FAIL — module not found.
-
-- [ ] **Step 3: Implement `collect-models.ts`**
-
-```ts
-// src/codegen/collect-models.ts
-import type { AnyHttpRouteDoc } from '../implementations/types.js'
-
-export interface CollectedModel {
-  id: string
-  name: string
-  schema: Record<string, unknown>
-}
-
-function deriveName(schema: Record<string, unknown>, id: string): string {
-  const title = typeof schema.title === 'string' ? schema.title : undefined
-  const base = title ?? id.split(/[/#:]/).filter(Boolean).pop() ?? 'Model'
-  // PascalCase-ish; reuse toPascalCase from naming.ts if it fits the input shape.
-  return base.replace(/(^|[^A-Za-z0-9])([A-Za-z0-9])/g, (_, _s, c) => c.toUpperCase())
-}
-
-/** Stable structural key for collision detection (order-insensitive JSON). */
-function stableKey(schema: unknown): string {
-  return JSON.stringify(schema, Object.keys(schema as object).sort?.() ?? undefined)
-}
-
-function walk(node: unknown, visit: (s: Record<string, unknown>) => void): void {
-  if (node == null || typeof node !== 'object') return
-  if (Array.isArray(node)) { for (const item of node) walk(item, visit); return }
-  const obj = node as Record<string, unknown>
-  if (typeof obj.$id === 'string') visit(obj)
-  for (const value of Object.values(obj)) walk(value, visit)
-}
-
-/**
- * Walks every route's JSON schema and returns the deduped set of $id-bearing
- * subschemas, named from `title`. Hoisting is keyed on declared identity ($id)
- * — never on structure. Two subschemas sharing an $id but with divergent bodies
- * are a hard error. Distinct $ids that derive the same name are disambiguated
- * deterministically (Message, Message2, …) by first-seen order.
- */
-export function collectModels(routes: AnyHttpRouteDoc[]): CollectedModel[] {
-  const byId = new Map<string, { schema: Record<string, unknown>; key: string }>()
-  for (const route of routes) {
-    walk((route as { jsonSchema?: unknown }).jsonSchema, (s) => {
-      const id = s.$id as string
-      const key = stableKey(s)
-      const existing = byId.get(id)
-      if (existing) {
-        if (existing.key !== key) {
-          throw new Error(
-            `[ts-procedures-codegen] Two schemas share $id "${id}" but have different shapes. ` +
-              `An $id must identify a single type. Give the divergent schema its own $id.`,
-          )
-        }
-        return
-      }
-      byId.set(id, { schema: s, key })
-    })
-  }
-
-  const models: CollectedModel[] = []
-  const usedNames = new Map<string, number>()
-  for (const [id, { schema }] of byId) {
-    let name = deriveName(schema, id)
-    const seen = usedNames.get(name)
-    if (seen) { usedNames.set(name, seen + 1); name = `${name}${seen + 1}` }
-    else usedNames.set(name, 1)
-    models.push({ id, name, schema })
-  }
-  return models
-}
-```
-
-> When implementing, prefer the existing `toPascalCase` from `src/codegen/naming.ts` for `deriveName` if its input contract matches; keep one naming utility.
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `npx vitest run src/codegen/collect-models.test.ts`
-Expected: PASS.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/codegen/collect-models.ts src/codegen/collect-models.test.ts
-git commit -m "feat(codegen): collect-models — dedup \$id subschemas with collision detection"
-```
-
-### Task 10: Resolve the `sharedTypesImport` map onto collected models
-
-**Files:**
-- Modify: `src/codegen/collect-models.ts` (add import-map resolution)
-- Test: `src/codegen/collect-models.test.ts`
-
-- [ ] **Step 1: Write the failing test**
-
-```ts
-import { resolveModelImports } from './collect-models.js'
-
-it('marks models mapped to a user package as imported', () => {
-  const models = [{ id: 'urn:msg', name: 'Message', schema: {} as any }]
-  const resolved = resolveModelImports(models, { 'urn:msg': { module: '@shared/schemas', name: 'Message' } })
-  expect(resolved[0]).toMatchObject({ id: 'urn:msg', import: { module: '@shared/schemas', name: 'Message' } })
-})
-
-it('leaves unmapped models as generated (no import)', () => {
-  const models = [{ id: 'urn:msg', name: 'Message', schema: {} as any }]
-  const resolved = resolveModelImports(models, {})
-  expect(resolved[0].import).toBeUndefined()
-})
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `npx vitest run src/codegen/collect-models.test.ts`
-Expected: FAIL — `resolveModelImports` not exported.
-
-- [ ] **Step 3: Implement**
-
-```ts
-// add to collect-models.ts
-export interface SharedTypeImport { module: string; name: string }
-export type SharedTypesImportMap = Record<string, SharedTypeImport>
-export interface ResolvedModel extends CollectedModel { import?: SharedTypeImport }
-
-/** Tags each model with its user-package import when its $id is in the map. */
-export function resolveModelImports(
-  models: CollectedModel[],
-  map: SharedTypesImportMap | undefined,
-): ResolvedModel[] {
-  return models.map((m) => {
-    const mapped = map?.[m.id]
-    return mapped ? { ...m, import: mapped } : { ...m }
-  })
-}
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `npx vitest run src/codegen/collect-models.test.ts`
-Expected: PASS.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/codegen/collect-models.ts src/codegen/collect-models.test.ts
-git commit -m "feat(codegen): resolve sharedTypesImport map onto collected models"
-```
-
-### Task 11: `emit-models.ts` — generate `_models.ts`
-
-**Files:**
-- Create: `src/codegen/emit-models.ts`
-- Test: `src/codegen/emit-models.test.ts`
-
-Uses `jsonSchemaToTypeBody` (flat) / the extracted-types path from `emit-types.ts` to render each generated model as a root named type. Per Task 8 decision, generated models are rendered as standalone root types either way (`_models.ts` is target-of-reference in both mechanisms).
-
-- [ ] **Step 1: Write the failing test**
-
-```ts
-// src/codegen/emit-models.test.ts
-import { describe, it, expect } from 'vitest'
-import { emitModelsFile } from './emit-models.js'
-
-it('re-exports mapped models and declares generated ones', async () => {
-  const code = await emitModelsFile(
-    [
-      { id: 'urn:msg', name: 'Message', schema: {} as any, import: { module: '@shared/schemas', name: 'Message' } },
-      { id: 'urn:thread', name: 'Thread', schema: { type: 'object', title: 'Thread', properties: { id: { type: 'string' } } } as any },
-    ],
-    { ajsc: {}, namespaceTypes: true, serviceName: 'Api' },
-  )
-  expect(code).toContain("export { Message } from '@shared/schemas'")
-  expect(code).toMatch(/export (type|interface) Thread/)
-})
-
-it('aliases a re-export when the local name differs from the package name', async () => {
-  const code = await emitModelsFile(
-    [{ id: 'urn:msg', name: 'ChatMessage', schema: {} as any, import: { module: '@shared/schemas', name: 'Message' } }],
-    { ajsc: {}, namespaceTypes: true, serviceName: 'Api' },
-  )
-  expect(code).toContain("export { Message as ChatMessage } from '@shared/schemas'")
-})
-
-it('returns null when there are no models', async () => {
-  expect(await emitModelsFile([], { ajsc: {}, namespaceTypes: true, serviceName: 'Api' })).toBeNull()
-})
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `npx vitest run src/codegen/emit-models.test.ts`
-Expected: FAIL — module not found.
-
-- [ ] **Step 3: Implement `emit-models.ts`**
-
-Render order: re-exports first, then generated declarations. In namespace mode, wrap generated models in `export namespace ${serviceName}Models { ... }` and re-exports above it (re-exports can also live inside the namespace via `export import`, but a top-level `export { X } from '...'` is simpler and is what scopes import). Reuse `jsonSchemaToTypeBody`/`jsonSchemaToExtractedTypes` from `emit-types.ts`.
-
-```ts
-// src/codegen/emit-models.ts
-import type { ResolvedModel } from './collect-models.js'
-import type { AjscOptions } from './emit-types.js'
-import { jsonSchemaToTypeBody } from './emit-types.js' // verify export
-
-export interface EmitModelsOptions {
-  ajsc?: AjscOptions
-  namespaceTypes: boolean
-  serviceName: string
-}
-
-export async function emitModelsFile(
-  models: ResolvedModel[],
-  opts: EmitModelsOptions,
-): Promise<string | null> {
-  if (models.length === 0) return null
-  const header = '// Generated by ts-procedures-codegen. DO NOT EDIT.'
-  const reexports: string[] = []
-  const decls: string[] = []
-
-  for (const m of models) {
-    if (m.import) {
-      const clause = m.import.name === m.name ? m.name : `${m.import.name} as ${m.name}`
-      reexports.push(`export { ${clause} } from '${m.import.module}'`)
-    } else {
-      const body = await jsonSchemaToTypeBody(m.schema, opts.ajsc)
-      if (body == null) continue
-      decls.push(`export type ${m.name} = ${body}`)
-    }
-  }
-
-  const lines = [header, '']
-  if (reexports.length) lines.push(...reexports, '')
-  if (decls.length) {
-    if (opts.namespaceTypes) {
-      // keep flat top-level types; scopes reference them via the _models import.
-      lines.push(...decls)
-    } else {
-      lines.push(...decls)
-    }
-  }
-  return lines.join('\n')
-}
-```
-
-> Decision note: keep `_models.ts` declarations **flat top-level** named types regardless of `namespaceTypes` — scope files import them by name (`import type { Message } from './_models.js'`). This avoids the value+type `export import` gymnastics the scope namespaces need; `_models.ts` is pure types. Confirm scope import wiring in Task 12 matches.
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `npx vitest run src/codegen/emit-models.test.ts`
-Expected: PASS.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/codegen/emit-models.ts src/codegen/emit-models.test.ts
-git commit -m "feat(codegen): emit-models — _models.ts hub (re-exports + generated types)"
-```
-
-### Task 12: Wire collect→emit-models→scope-reference into the TS pipeline
-
-**Files:**
-- Modify: `src/codegen/targets/_shared/target-run.ts` (add `shareModels?`, `sharedTypesImport?` to `TargetRunInput`)
-- Modify: `src/codegen/pipeline.ts` (thread options through)
-- Modify: `src/codegen/index.ts` (`GenerateClientOptions` + `generateClient` pass-through)
-- Modify: `src/codegen/targets/ts/run.ts` (collect models, emit `_models.ts`, pass model registry to `emitScopeFile`)
-- Modify: `src/codegen/emit-scope.ts` (reference hoisted models instead of inlining — per Task 8 mechanism)
-- Test: `src/codegen/targets/ts/run.test.ts` (locate the existing run/pipeline test that uses `__fixtures__/users-envelope.json`)
-
-- [ ] **Step 1: Extend the fixture and write the failing integration test**
-
-Add a `$id`'d schema reused across two routes to a **copy** of the canonical fixture (or extend it if other targets tolerate the extra `$id` — they ignore it). Assert:
-
-```ts
-it('emits a single _models.ts entry for a reused $id and references it from scopes', async () => {
-  const files = await generateClient({
-    envelope: envelopeWithSharedMessage, outDir: tmp, serviceName: 'Api',
-    namespaceTypes: true, selfContained: false, shareModels: true,
-  })
-  const models = files.find((f) => f.path.endsWith('_models.ts'))!
-  expect(models.code.match(/export type Message =/g)).toHaveLength(1)
-  const scope = files.find((f) => f.path.endsWith('messages.ts'))!
-  expect(scope.code).toContain("from './_models.js'")
-  expect(scope.code).toContain('Message')
-})
-
-it('--no-share-models (shareModels:false) restores byte-identical legacy output', async () => {
-  const off = await generateClient({ envelope: envelopeWithSharedMessage, outDir: tmpA, serviceName: 'Api', shareModels: false, namespaceTypes: true, selfContained: false })
-  // no _models.ts emitted
-  expect(off.find((f) => f.path.endsWith('_models.ts'))).toBeUndefined()
-})
-
-it('schemas without $id are unchanged when shareModels is on', async () => {
-  const on = await generateClient({ envelope: envelopeNoIds, outDir: t1, shareModels: true, namespaceTypes: true, selfContained: false, serviceName: 'Api' })
-  const off = await generateClient({ envelope: envelopeNoIds, outDir: t2, shareModels: false, namespaceTypes: true, selfContained: false, serviceName: 'Api' })
-  const code = (fs: typeof on, n: string) => fs.find((f) => f.path.endsWith(n))!.code
-  // scope output identical (ignoring _models.ts which won't exist either way)
-  expect(code(on, 'users.ts')).toBe(code(off, 'users.ts'))
-})
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `npx vitest run src/codegen/targets/ts/run.test.ts`
-Expected: FAIL — `shareModels` not accepted / `_models.ts` not emitted.
-
-- [ ] **Step 3: Thread the options**
-
-- `GenerateClientOptions` (index.ts:7-26): add `shareModels?: boolean` and `sharedTypesImport?: SharedTypesImportMap`. Pass both into `runPipeline` (index.ts:30-48).
-- `pipeline.ts`: forward to the per-target input.
-- `target-run.ts` `TargetRunInput`: add `shareModels?: boolean`, `sharedTypesImport?: SharedTypesImportMap`.
-- Default `shareModels` to `true` at the public boundary (cli/pipeline), `false` fallback in low-level run module (mirror the `cleanOutDir` convention).
-
-- [ ] **Step 4: Implement in `targets/ts/run.ts`**
-
-After `const errorKeys = ...` and before the scope loop:
-
-```ts
-import { collectModels, resolveModelImports } from '../../collect-models.js'
-import { emitModelsFile } from '../../emit-models.js'
-
-const shareModels = input.shareModels ?? false
-const models = shareModels
-  ? resolveModelImports(collectModels(envelope.routes), input.sharedTypesImport)
-  : []
-const modelsById = new Map(models.map((m) => [m.id, m]))
-```
-
-Pass `modelsById` into `emitScopeFile(group, { ..., models: modelsById })`. After the scope loop, emit `_models.ts`:
-
-```ts
-if (models.length > 0) {
-  const modelsCode = await emitModelsFile(models, { ajsc: ajscOpts, namespaceTypes, serviceName })
-  if (modelsCode != null) {
-    const ml = modelsCode.split('\n'); ml.splice(1, 0, hashComment)
-    files.push({ path: join(outDir, '_models.ts'), code: ml.join('\n') })
-  }
-}
-```
-
-Guard the reserved-filename check (run.ts:44-52) to also reject a scope named `_models` in self-contained-or-share-models mode.
-
-- [ ] **Step 5: Implement the scope reference in `emit-scope.ts` (per Task 8 mechanism)**
-
-`emitScopeFile`/`formatTypes` gain a `models?: Map<string, ResolvedModel>` context field. Before converting a route schema:
-
-- **Mechanism A (`$ref`):** pre-process the route schema — replace any subschema whose `$id` is in `models` with `{ $ref: '#/$defs/<name>' }` and attach a `$defs` table containing each referenced model. Feed to ajsc; capture references to the model names. Emit `import type { Message } from './_models.js'` (flat) at the top of the scope file for every referenced model (collect referenced names per scope). In namespace mode, reference the bare `Message` (imported) inside the namespace — confirm the spike output uses the imported name.
-- **Mechanism B (substitution):** convert the route schema as today, then for each model whose `$id` appears in this route, string-substitute the emitted structural literal with the model name (word-boundary patch, same approach as `renameExtractedTypes`), and add the `_models.js` import.
-
-Either way: add the `_models.js` type-import line for the set of model names referenced in the scope file. Match the existing import style (the file already imports from `./_types`/client path).
-
-- [ ] **Step 6: Run the test + full suite**
-
-Run: `npx vitest run src/codegen/targets/ts/run.test.ts && npm run test`
-Expected: PASS. Verify the no-`$id` regression (byte-identical scope output) is green.
-
-- [ ] **Step 7: Build + smoke-generate against the demo server**
-
-Run: `npm run build`. Then regenerate the repo's own client per the documented loop and eyeball `messages.ts` + `_models.ts`: one `Message` type, scopes reference it.
-
-- [ ] **Step 8: Commit**
-
-```bash
-git add src/codegen
-git commit -m "feat(codegen): hoist \$id schemas into _models.ts and reference them from scopes"
-```
-
-### Task 13: `--share-models` flag + `sharedTypesImport` config
-
-**Files:**
-- Modify: `src/codegen/bin/cli.ts` (`CodegenConfig`, `ParsedArgs`, parse loop, pass-through to `generateClient`)
-- Modify: `src/codegen/bin/flag-specs.ts` is already done (Task 1 included the two flags)
-- Test: `src/codegen/bin/cli.test.ts`
-
-- [ ] **Step 1: Write the failing test**
-
-```ts
-it('parses --share-models / --no-share-models', () => {
-  expect(parseArgs(['--out', 'g', '--url', 'u']).shareModels).toBe(true) // default on
-  expect(parseArgs(['--out', 'g', '--url', 'u', '--no-share-models']).shareModels).toBe(false)
-})
-
-it('reads sharedTypesImport from config', () => {
-  const cfg = { sharedTypesImport: { 'urn:msg': { module: '@shared/schemas', name: 'Message' } } }
-  expect(parseArgs(['--out', 'g', '--url', 'u'], cfg as any).sharedTypesImport).toEqual(cfg.sharedTypesImport)
-})
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `npx vitest run src/codegen/bin/cli.test.ts`
-Expected: FAIL — `shareModels`/`sharedTypesImport` absent.
-
-- [ ] **Step 3: Implement**
-
-- `CodegenConfig` (cli.ts:12-29): add `shareModels?: boolean` and `sharedTypesImport?: Record<string, { module: string; name: string }>`.
-- `ParsedArgs` (31-48): add `shareModels: boolean` and `sharedTypesImport?: ...`.
-- In `parseArgs`: `let shareModels = config?.shareModels ?? true` and `const sharedTypesImport = config?.sharedTypesImport`. Add parse branches:
-
-```ts
-} else if (arg === '--share-models') {
-  shareModels = true
-} else if (arg === '--no-share-models') {
-  shareModels = false
-```
-
-- Return them in the object (spread `sharedTypesImport` only when defined).
-- In `main()` where `generateClient` is called, pass `shareModels` and `sharedTypesImport`.
-
-(`--share-models`/`--no-share-models` are already in `FLAG_SPECS`/`KNOWN_FLAGS` from Task 1, so the unknown-flag guard accepts them — verify.)
-
-- [ ] **Step 4: Run test + build**
-
-Run: `npx vitest run src/codegen/bin/cli.test.ts && npm run build`
-Expected: PASS.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/codegen/bin/cli.ts src/codegen/bin/cli.test.ts
-git commit -m "feat(codegen): --share-models flag + sharedTypesImport config"
-```
-
----
-
-## #5 — Scaffolder file-naming knobs
-
-### Task 14: `fileNameStyle` + `groupBy` in the scaffold skill + templates
-
-**Files:**
-- Modify: `agent_config/claude-code/skills/ts-procedures/SKILL.md` (scaffold-mode section, ~lines 260-304)
-- Modify: `agent_config/claude-code/skills/ts-procedures/templates/procedure.md`, `stream-procedure.md`, `hono.md`, `client.md` (output-filename lines)
-
-This is markdown/instruction content (no runtime tests). Verify by reading the rendered instructions and the placeholder logic.
-
-- [ ] **Step 1: Add the two args to SKILL.md scaffold mode**
-
-In the scaffold-mode section, document:
-
-```markdown
-**Optional flags:**
-- `fileNameStyle` — `PascalCase` (default) | `kebab.concern`.
-  - `PascalCase`: `GetUser.procedure.ts`
-  - `kebab.concern`: `get-user.procedure.ts`
-- `groupBy` — `flat` (default, CWD) | `scope`.
-  - `scope`: writes under `<scope>/`, e.g. `users/get-user.procedure.ts`. Scope is the
-    procedure's `scope` (from its config), kebab-cased.
-
-**Default inference (when neither flag is passed):** inspect the target directory.
-If existing procedure files are kebab-cased and grouped in per-scope folders, default
-to `fileNameStyle: kebab.concern` + `groupBy: scope`. Otherwise default to
-`PascalCase` + `flat`. State the inferred choice before writing files.
-```
-
-Add placeholder derivations:
-
-```markdown
-Derived placeholders:
-- `{{Name}}` — PascalCase (e.g. `GetUser`)
-- `{{kebab}}` — kebab-case (e.g. `get-user`)
-- `{{scope}}` — kebab-cased scope (e.g. `users`)
-- `{{fileName}}` — `{{Name}}` when fileNameStyle=PascalCase, else `{{kebab}}`
-- `{{dir}}` — `` (empty) when groupBy=flat, else `{{scope}}/`
-```
-
-Update the "Files Generated" table to use the computed name, e.g.
-`{{dir}}{{fileName}}.procedure.ts`, `{{dir}}{{fileName}}.procedure.test.ts`.
-
-- [ ] **Step 2: Update each template's output-filename line**
-
-In `templates/procedure.md` (line ~3) and siblings, replace the hardcoded
-`{{Name}}.procedure.ts` output reference with `{{dir}}{{fileName}}.procedure.ts`
-(and `.test.ts`). Same for `stream-procedure.md` (`.stream.ts`), `hono.md`
-(`.hono.ts`), `client.md` (`.client.ts`). Leave the code bodies untouched.
-
-- [ ] **Step 3: Verify the skill still installs cleanly**
-
-The installer is a pure recursive copy (`agent_config/lib/install-claude.mjs`), so no transform to update. Run any agent_config check if present:
-
-Run: `node agent_config/bin/setup.mjs --dry-run` (or `npx ts-procedures-setup --dry-run` from a consumer) to confirm the files still copy. If a `--check` CI script exists, run it.
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add agent_config/claude-code/skills/ts-procedures
-git commit -m "feat(scaffold): fileNameStyle + groupBy with auto-default inference"
-```
-
----
-
-## Final verification
-
-- [ ] **Run the full suite:** `npm run test` — all green.
-- [ ] **Lint:** `npm run lint` — clean.
-- [ ] **Build:** `npm run build` — clean.
-- [ ] **Regenerate the repo's own client** via the documented offline loop; confirm `_models.ts` holds one `Message`, scopes reference it, and `--help` prints usage.
-- [ ] **Update `CLAUDE.md`** if any new public surface needs documenting (writeDocEnvelope, `_models.ts`, `sharedTypesImport`, function-valued headers, `--share-models`).
-- [ ] **Update the downstream feedback file** marking #1–#5 resolved (mirror the 8.3.0 reset note style).
-
----
-
-## Spec coverage check
-
-| Spec section | Task(s) |
-|---|---|
-| #1 structured flags + `--help`/bare, exclude from suggester | 1, 2, 3 |
-| #2 `writeDocEnvelope` + docs | 4, 5 |
-| #3 collect by `$id`, dedup, collision error | 9 |
-| #3 `sharedTypesImport` map | 10, 13 |
-| #3 `_models.ts` hub (generated + re-export) | 11 |
-| #3 scope references model; default-on; no-`$id` unchanged; TS-only | 12, 13 |
-| #3 ajsc/nested-`$id` risk spike | 8 |
-| #4 function-valued headers, async resolve, per-call merge | 6 |
-| #4 auth-seam docs | 7 |
-| #5 `fileNameStyle` + `groupBy` + auto-default | 14 |