ts-procedures 8.3.0 → 8.5.0

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

@@ -0,0 +1,1292 @@
+# 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 |