ts-procedures 6.0.2 → 6.2.0

package/docs/superpowers/plans/2026-04-25-ajsc-v7-kotlin-polish.md

@@ -0,0 +1,1993 @@
+# ajsc v7.2 Kotlin Codegen Polish 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:** Polish the in-progress Kotlin codegen target to align with `ajsc@^7.2.0`: hardcode `inlineTypes: true` so cross-slot dedup falls out of nested-class scoping (no shared registry plumbing), trim dead options from the adapter contract, surface `--kotlin-serializer` and `--unsupported-unions` CLI flags, replace the trivial test fixture with one that exercises real ajsc v7.2 features, activate the previously-gated kotlinc E2E test, and ship a downstream-consumer setup guide.
+
+**Architecture:** ajsc emits **declarations only** (no `package`, no `import`); `ts-procedures` assembles `.kt` files (package line, deduped imports, scope/route wrappers, source-hash header). Per-route emission becomes a pure pipeline — no `Set<string>` shared across `emit` calls — because Kotlin's nested-class scoping makes `Body.Address` and `Response.Address` different fully-qualified names by construction. Two new pipeline opts thread through unchanged: `kotlinSerializer` (`'kotlinx' | 'none'`) and `unsupportedUnions` (`'throw' | 'fallback'`).
+
+**Tech Stack:** TypeScript, Vitest, Node.js, `ajsc@^7.2.0` (in `optionalDependencies`). E2E compile test uses `kotlinc` and `kotlinx-serialization-json` jar (gated on local env opt-in).
+
+**Spec:** [`docs/superpowers/specs/2026-04-25-ajsc-v7-kotlin-polish-design.md`](../specs/2026-04-25-ajsc-v7-kotlin-polish-design.md)
+
+**Branch context:** This plan executes on the `codegen-kotlin-swift` branch, which already contains a Phase B Kotlin codegen implementation (per [`docs/superpowers/plans/2026-04-24-kotlin-codegen-target.md`](./2026-04-24-kotlin-codegen-target.md)). Most files exist; this plan **modifies** them.
+
+---
+
+## File Structure
+
+| Path | Change | Responsibility |
+|---|---|---|
+| `src/codegen/targets/kotlin/ajsc-adapter.ts` | Modify | Drop `enumStyle`, add `serializer`/`unsupportedUnions`/`inlineTypes` on `KotlinEmitOptions`; clean up production resolver TODO. |
+| `src/codegen/targets/kotlin/ajsc-adapter.test.ts` | Modify | Drop dead-option asserts; pin production resolver error-message text. |
+| `src/codegen/targets/kotlin/emit-route-kotlin.ts` | Modify | Take new opts arg; pass `inlineTypes: true` + `serializer` + `unsupportedUnions` to every `emitter.emit`; replace inline `console.warn` with `skipped: true` return flag. |
+| `src/codegen/targets/kotlin/emit-route-kotlin.test.ts` | Modify | Assert opts threaded per slot; assert `skipped: true` on stream routes; assert slot ordering. |
+| `src/codegen/targets/kotlin/emit-scope-kotlin.ts` | Modify | Take new opts arg; thread to route emitter; collect `skippedStreams` and surface in return. |
+| `src/codegen/targets/kotlin/emit-scope-kotlin.test.ts` | Modify | Assert opts threaded; assert skipped-streams collection. |
+| `src/codegen/pipeline.ts` | Modify | Add `kotlinSerializer` + `unsupportedUnions` to `PipelineOptions`; thread through; aggregate `skippedStreams` and emit single summary log. |
+| `src/codegen/pipeline.test.ts` | Modify | Tests for new opts threading; test for stream summary log. |
+| `src/codegen/index.ts` | Modify | Surface new opts on `GenerateClientOptions`; pass through to `runPipeline`. |
+| `src/codegen/bin/cli.ts` | Modify | Add `--kotlin-serializer` and `--unsupported-unions` flag parsing; place in `parsed.kotlin.serializer` and `parsed.unsupportedUnions`; print setup-guide pointer after successful Kotlin run. |
+| `src/codegen/bin/cli.test.ts` | Modify | Tests for both new flags (CLI, config, override, invalid value); test for printed pointer. |
+| `src/codegen/targets/kotlin/__fixtures__/users-envelope.json` | Modify | Replace placeholder envelope with realistic schemas (3 routes, nested objects, discriminated `oneOf`, enum, `format: date-time`, `created-at` JSON key, two error types). |
+| `src/codegen/targets/kotlin/__fixtures__/users-golden.kt` | Modify | Regenerate against new fixture and updated stub emitter. |
+| `src/codegen/targets/kotlin/integration.test.ts` | Modify | Update stub emitter map for new fixture; add `UPDATE_GOLDENS=1` regeneration mode. |
+| `src/codegen/targets/kotlin/probe-unsupported-unions.test.ts` | Create | Snapshot test for ajsc's Kotlin `unsupportedUnions: 'fallback'` shape; gated on ajsc resolvability. |
+| `src/codegen/targets/kotlin/e2e-compile.test.ts` | Modify | Drop ajsc-availability gate; keep `kotlinc` + opt-in env gate; point at new fixture; document classpath setup. |
+| `docs/codegen-kotlin.md` | Create | Downstream consumer setup guide (Gradle, contextual serializers, sealed interfaces, `serializer: 'none'`, `unsupportedUnions: 'fallback'` from probe snapshot, documented limitations). |
+| `CLAUDE.md` | Modify | Update Kotlin target bullet: nested-class output shape note, two new flags, pointer to `docs/codegen-kotlin.md`. |
+
+---
+
+## Task 1: Tighten `KotlinEmitOptions` shape
+
+**Files:**
+- Modify: `src/codegen/targets/kotlin/ajsc-adapter.ts`
+- Modify: `src/codegen/targets/kotlin/ajsc-adapter.test.ts`
+
+Drop dead options (`enumStyle`) and add v7.2's actual surface (`serializer`, `unsupportedUnions`, `inlineTypes`). The interface shape should match what ajsc honors so downstream callers and the production resolver don't pass meaningless fields.
+
+- [ ] **Step 1: Update the failing test**
+
+Edit `src/codegen/targets/kotlin/ajsc-adapter.test.ts` — extend the existing happy-path test to round-trip the new opts through the stub:
+
+```ts
+import { describe, expect, it } from 'vitest'
+import { createStubKotlinEmitter, type KotlinEmitResult } from './ajsc-adapter.js'
+
+describe('createStubKotlinEmitter', () => {
+  it('returns the configured EmitResult for the matching root name', () => {
+    const expected: KotlinEmitResult = {
+      code: '@Serializable data class User(val id: String)',
+      rootTypeName: 'User',
+      extractedTypeNames: [],
+      imports: ['kotlinx.serialization.Serializable'],
+    }
+    const emitter = createStubKotlinEmitter({ User: expected })
+    expect(
+      emitter.emit(
+        { type: 'object' },
+        {
+          rootTypeName: 'User',
+          inlineTypes: true,
+          serializer: 'kotlinx',
+          unsupportedUnions: 'throw',
+        },
+      ),
+    ).toEqual(expected)
+  })
+
+  it('throws when asked to emit a name not in the stub map', () => {
+    const emitter = createStubKotlinEmitter({})
+    expect(() => emitter.emit({}, { rootTypeName: 'Missing' })).toThrow(/Missing/)
+  })
+})
+```
+
+- [ ] **Step 2: Run the test and verify it fails**
+
+```bash
+npx vitest run src/codegen/targets/kotlin/ajsc-adapter.test.ts
+```
+
+Expected: FAIL — TypeScript complains that `serializer` and `unsupportedUnions` aren't valid fields on `KotlinEmitOptions`.
+
+- [ ] **Step 3: Update `KotlinEmitOptions` shape**
+
+Edit `src/codegen/targets/kotlin/ajsc-adapter.ts` — replace the existing interface:
+
+```ts
+export interface KotlinEmitOptions {
+  rootTypeName: string
+  /** Always set true at our call sites; v7.2 default is false. */
+  inlineTypes?: boolean
+  serializer?: 'kotlinx' | 'none'
+  unsupportedUnions?: 'throw' | 'fallback'
+  arrayItemNaming?: string | false
+  depluralize?: boolean
+  uncountableWords?: string[]
+}
+```
+
+Removed: `enumStyle` (TS-only ajsc opt). Kept: passthroughs that ajsc's `BaseConverterOpts` honors.
+
+- [ ] **Step 4: Run the test and verify it passes**
+
+```bash
+npx vitest run src/codegen/targets/kotlin/ajsc-adapter.test.ts
+```
+
+Expected: PASS (2 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/codegen/targets/kotlin/ajsc-adapter.ts src/codegen/targets/kotlin/ajsc-adapter.test.ts
+git commit -m "refactor(codegen/kotlin): align KotlinEmitOptions with ajsc v7.2 surface"
+```
+
+---
+
+## Task 2: Pin production resolver error message and drop Phase A TODO
+
+**Files:**
+- Modify: `src/codegen/targets/kotlin/ajsc-adapter.ts`
+- Modify: `src/codegen/targets/kotlin/ajsc-adapter.test.ts`
+
+ajsc Phase A is delivered (v7.0+); the `TODO(ajsc-phase-a)` marker on `resolveProductionKotlinEmitter` is stale. The function still needs to throw a clear error if `import('ajsc')` fails (e.g., consumer ran `npm install --omit=optional`). Pin that message in a unit test so a future refactor can't silently change it.
+
+- [ ] **Step 1: Add a test that pins the error wording**
+
+Append to `src/codegen/targets/kotlin/ajsc-adapter.test.ts`:
+
+```ts
+import { resolveProductionKotlinEmitter } from './ajsc-adapter.js'
+
+describe('resolveProductionKotlinEmitter', () => {
+  it('returns a working emitter when ajsc is installed', async () => {
+    const emitter = await resolveProductionKotlinEmitter()
+    expect(typeof emitter.emit).toBe('function')
+  })
+  // Note: testing the failure path (ajsc unavailable) requires module mocking;
+  // we leave that as a manual-verification path. The error message is pinned
+  // by the message text below so any change requires updating both call sites.
+})
+```
+
+- [ ] **Step 2: Run and verify the new test passes**
+
+```bash
+npx vitest run src/codegen/targets/kotlin/ajsc-adapter.test.ts
+```
+
+Expected: PASS (3 tests). If FAIL because `ajsc` doesn't expose `emitKotlin`, the message text below already covers it — diagnose the install state with `npm ls ajsc`.
+
+- [ ] **Step 3: Drop the stale TODO; tighten the error message**
+
+In `src/codegen/targets/kotlin/ajsc-adapter.ts`, edit `resolveProductionKotlinEmitter`:
+
+```ts
+/**
+ * Resolves the production Kotlin emitter from `ajsc`. Throws a clear error
+ * if ajsc is not installed or does not expose `emitKotlin` (e.g. consumer
+ * ran `npm install --omit=optional` since ajsc is in optionalDependencies).
+ */
+export async function resolveProductionKotlinEmitter(): Promise<KotlinEmitter> {
+  const ajsc = await import('ajsc').catch(() => null)
+  const emitKotlin = (ajsc as { emitKotlin?: unknown } | null)?.emitKotlin
+  if (typeof emitKotlin !== 'function') {
+    throw new Error(
+      '[ts-procedures-codegen] ajsc.emitKotlin is not available. ' +
+      'Install ajsc (`npm install ajsc`) — it is an optional dependency.',
+    )
+  }
+  return {
+    emit(schema, opts) {
+      return (emitKotlin as (s: unknown, o: unknown) => KotlinEmitResult)(schema, opts)
+    },
+  }
+}
+```
+
+- [ ] **Step 4: Run all kotlin adapter tests**
+
+```bash
+npx vitest run src/codegen/targets/kotlin/ajsc-adapter.test.ts
+```
+
+Expected: PASS (3 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/codegen/targets/kotlin/ajsc-adapter.ts src/codegen/targets/kotlin/ajsc-adapter.test.ts
+git commit -m "refactor(codegen/kotlin): drop stale phase-a TODO; tighten resolver error wording"
+```
+
+---
+
+## Task 3: Pass `inlineTypes: true` + new opts per slot in `emit-route-kotlin.ts`
+
+**Files:**
+- Modify: `src/codegen/targets/kotlin/emit-route-kotlin.ts`
+- Modify: `src/codegen/targets/kotlin/emit-route-kotlin.test.ts`
+
+Make `emitKotlinRoute` a pure function over its inputs. Add an opts argument carrying `serializer` and `unsupportedUnions` (forwarded from pipeline). Hardcode `inlineTypes: true` at every `emitter.emit()` call site. Verify with a spy-style stub emitter that captures the opts it was called with.
+
+- [ ] **Step 1: Extend the test stub to capture opts**
+
+Edit `src/codegen/targets/kotlin/emit-route-kotlin.test.ts`. Add a helper at the top of the file:
+
+```ts
+import type { KotlinEmitOptions } from './ajsc-adapter.js'
+
+interface CapturedCall { schema: unknown; opts: KotlinEmitOptions }
+
+function makeSpyEmitter(results: Record<string, KotlinEmitResult>) {
+  const calls: CapturedCall[] = []
+  const emitter = {
+    emit(schema: unknown, opts: KotlinEmitOptions) {
+      calls.push({ schema, opts })
+      const r = results[opts.rootTypeName]
+      if (r == null) throw new Error(`No stubbed result for "${opts.rootTypeName}"`)
+      return r
+    },
+  }
+  return { emitter, calls }
+}
+```
+
+Then add a new test asserting opt threading:
+
+```ts
+it('passes inlineTypes:true plus serializer/unsupportedUnions to every slot emit', () => {
+  const route = {
+    kind: 'api',
+    name: 'GetUser',
+    method: 'GET',
+    fullPath: '/users/:id',
+    schema: {
+      input: { pathParams: { type: 'object' } },
+      returnType: { type: 'object' },
+    },
+    errors: ['NotFound'],
+  } as unknown as AnyHttpRouteDoc
+
+  const { emitter, calls } = makeSpyEmitter({
+    PathParams: ok('@Serializable data class PathParams(val id: String)', 'PathParams'),
+    Response: ok('@Serializable data class Response(val id: String)', 'Response'),
+    NotFound: ok('@Serializable data class NotFound(val message: String)', 'NotFound'),
+  })
+
+  emitKotlinRoute(route, emitter, new Map([['NotFound', { type: 'object' }]]), {
+    serializer: 'none',
+    unsupportedUnions: 'fallback',
+  })
+
+  // 3 emits: PathParams, Response, NotFound
+  expect(calls.length).toBe(3)
+  for (const c of calls) {
+    expect(c.opts.inlineTypes).toBe(true)
+    expect(c.opts.serializer).toBe('none')
+    expect(c.opts.unsupportedUnions).toBe('fallback')
+  }
+})
+
+it('preserves slot order: pathParams → query → body → response → errors', () => {
+  const route = {
+    kind: 'api',
+    name: 'X',
+    method: 'POST',
+    fullPath: '/x/:id',
+    schema: {
+      input: {
+        pathParams: { type: 'object' },
+        query: { type: 'object' },
+        body: { type: 'object' },
+      },
+      returnType: { type: 'object' },
+    },
+    errors: ['Z'],
+  } as unknown as AnyHttpRouteDoc
+
+  const { emitter, calls } = makeSpyEmitter({
+    PathParams: ok('a', 'PathParams'),
+    Query: ok('b', 'Query'),
+    Body: ok('c', 'Body'),
+    Response: ok('d', 'Response'),
+    Z: ok('e', 'Z'),
+  })
+
+  emitKotlinRoute(route, emitter, new Map([['Z', { type: 'object' }]]), {})
+
+  expect(calls.map((c) => c.opts.rootTypeName)).toEqual([
+    'PathParams', 'Query', 'Body', 'Response', 'Z',
+  ])
+})
+```
+
+- [ ] **Step 2: Run the tests and verify they fail**
+
+```bash
+npx vitest run src/codegen/targets/kotlin/emit-route-kotlin.test.ts
+```
+
+Expected: FAIL — `emitKotlinRoute` doesn't accept a fourth argument; `inlineTypes`/`serializer`/`unsupportedUnions` aren't passed.
+
+- [ ] **Step 3: Update `emitKotlinRoute` signature and behavior**
+
+Edit `src/codegen/targets/kotlin/emit-route-kotlin.ts`:
+
+```ts
+import type { AnyHttpRouteDoc } from '../../../implementations/types.js'
+import type { KotlinEmitter, KotlinEmitOptions } from './ajsc-adapter.js'
+import { indent } from './format-kotlin.js'
+
+export interface EmitRouteResult {
+  code: string
+  imports: string[]
+  routeName: string
+  /** True when the route was a stream (out-of-scope). Caller logs once. */
+  skipped?: boolean
+}
+
+/** Subset of KotlinEmitOptions threaded by the pipeline; per-call rootTypeName is set inside. */
+export interface EmitRouteOpts {
+  serializer?: 'kotlinx' | 'none'
+  unsupportedUnions?: 'throw' | 'fallback'
+  arrayItemNaming?: string | false
+  depluralize?: boolean
+  uncountableWords?: string[]
+}
+
+const COLON_PARAM_RE = /:([A-Za-z_][A-Za-z0-9_]*)/g
+
+function toBracePath(template: string): string {
+  return template.replace(COLON_PARAM_RE, '{$1}')
+}
+
+function pathParamNames(template: string): string[] {
+  const names: string[] = []
+  for (const match of template.matchAll(COLON_PARAM_RE)) names.push(match[1]!)
+  return names
+}
+
+function buildPathFn(bracePath: string, params: string[]): string {
+  if (params.length === 0) return `const val path = "${bracePath}"`
+  let body = bracePath
+  for (const name of params) body = body.replace(`{${name}}`, `\${p.${name}}`)
+  return `fun path(p: PathParams): String = "${body}"`
+}
+
+function emitOptsFor(rootTypeName: string, routeOpts: EmitRouteOpts): KotlinEmitOptions {
+  return {
+    rootTypeName,
+    inlineTypes: true,
+    ...(routeOpts.serializer !== undefined ? { serializer: routeOpts.serializer } : {}),
+    ...(routeOpts.unsupportedUnions !== undefined ? { unsupportedUnions: routeOpts.unsupportedUnions } : {}),
+    ...(routeOpts.arrayItemNaming !== undefined ? { arrayItemNaming: routeOpts.arrayItemNaming } : {}),
+    ...(routeOpts.depluralize !== undefined ? { depluralize: routeOpts.depluralize } : {}),
+    ...(routeOpts.uncountableWords !== undefined ? { uncountableWords: routeOpts.uncountableWords } : {}),
+  }
+}
+
+export function emitKotlinRoute(
+  route: AnyHttpRouteDoc,
+  emitter: KotlinEmitter,
+  errorSchemas: Map<string, unknown>,
+  routeOpts: EmitRouteOpts = {},
+): EmitRouteResult {
+  const kind = (route as { kind?: string }).kind
+  if (kind === 'stream') {
+    return { code: '', imports: [], routeName: route.name, skipped: true }
+  }
+
+  const isApi = kind === 'api' || 'fullPath' in route
+  const rawPath = isApi
+    ? (route as { fullPath: string }).fullPath
+    : (route as { path: string }).path
+  const method = String((route as { method: string }).method).toUpperCase()
+  const bracePath = toBracePath(rawPath)
+  const params = pathParamNames(rawPath)
+
+  const lines: string[] = [
+    `const val method = "${method}"`,
+    `const val pathTemplate = "${bracePath}"`,
+    buildPathFn(bracePath, params),
+  ]
+  const imports: string[] = []
+
+  const schema = (route as { schema?: Record<string, unknown> }).schema ?? {}
+  const input = (schema.input ?? {}) as Record<string, unknown>
+
+  const slots: Array<{ rootName: string; source: unknown }> = [
+    { rootName: 'PathParams', source: input.pathParams },
+    { rootName: 'Query', source: input.query },
+    { rootName: 'Body', source: input.body },
+    { rootName: 'Response', source: schema.returnType },
+  ]
+
+  for (const slot of slots) {
+    if (slot.source == null) continue
+    const result = emitter.emit(slot.source as Record<string, unknown>, emitOptsFor(slot.rootName, routeOpts))
+    lines.push('')
+    lines.push(result.code)
+    imports.push(...result.imports)
+  }
+
+  const routeErrorKeys = ((route as { errors?: string[] }).errors ?? [])
+    .filter((key) => errorSchemas.has(key))
+  if (routeErrorKeys.length > 0) {
+    const inner: string[] = []
+    for (const key of routeErrorKeys) {
+      const r = emitter.emit(errorSchemas.get(key) as Record<string, unknown>, emitOptsFor(key, routeOpts))
+      inner.push(r.code)
+      imports.push(...r.imports)
+    }
+    lines.push('')
+    lines.push('object Errors {')
+    lines.push(indent(inner.join('\n\n'), 1))
+    lines.push('}')
+  }
+
+  return { code: lines.join('\n'), imports, routeName: route.name, skipped: false }
+}
+```
+
+- [ ] **Step 4: Update existing tests to pass the new (optional) opts arg**
+
+The two new tests above pass `routeOpts` explicitly. The existing tests don't pass it (ok — opts default to `{}`). Verify the existing stream-skip test no longer asserts `console.warn`:
+
+```ts
+// In the existing 'skips stream routes with a warning' test, replace:
+//   const result = emitKotlinRoute(route, createStubKotlinEmitter({}), noErrors)
+//   expect(result.code).toBe('')
+// with:
+const result = emitKotlinRoute(route, createStubKotlinEmitter({}), noErrors)
+expect(result.code).toBe('')
+expect(result.skipped).toBe(true)
+// Rename the test: `returns skipped:true for stream routes` (drop "with a warning")
+```
+
+- [ ] **Step 5: Run all emit-route tests**
+
+```bash
+npx vitest run src/codegen/targets/kotlin/emit-route-kotlin.test.ts
+```
+
+Expected: PASS (7 tests — 5 existing + 2 new).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/codegen/targets/kotlin/emit-route-kotlin.ts src/codegen/targets/kotlin/emit-route-kotlin.test.ts
+git commit -m "feat(codegen/kotlin): hardcode inlineTypes:true; thread serializer/unsupportedUnions per slot"
+```
+
+---
+
+## Task 4: Plumb new opts through `emit-scope-kotlin.ts` + collect skipped streams
+
+**Files:**
+- Modify: `src/codegen/targets/kotlin/emit-scope-kotlin.ts`
+- Modify: `src/codegen/targets/kotlin/emit-scope-kotlin.test.ts`
+
+The scope emitter needs to (a) accept the new opts and pass them to `emitKotlinRoute`, and (b) collect the names of skipped stream routes so the pipeline can summarize once.
+
+- [ ] **Step 1: Add tests for opt threading and skipped-stream collection**
+
+Edit `src/codegen/targets/kotlin/emit-scope-kotlin.test.ts`. Add tests:
+
+```ts
+it('threads serializer/unsupportedUnions through to every emitter call', () => {
+  const route = { kind: 'api', name: 'X', method: 'GET', fullPath: '/x', schema: { returnType: { type: 'object' } }, errors: [] } as unknown as AnyHttpRouteDoc
+  const group: ScopeGroup = { scopeKey: 'x', camelCase: 'x', routes: [route] }
+
+  const calls: KotlinEmitOptions[] = []
+  const emitter = {
+    emit(_s: unknown, opts: KotlinEmitOptions) {
+      calls.push(opts)
+      return { code: 'data class Response', rootTypeName: 'Response', extractedTypeNames: [], imports: [] }
+    },
+  }
+
+  emitKotlinScope(
+    group,
+    { kotlinPackage: 'p', sourceHash: 'h', serializer: 'none', unsupportedUnions: 'fallback' },
+    emitter,
+    new Map(),
+  )
+
+  expect(calls.length).toBe(1)
+  expect(calls[0]!.serializer).toBe('none')
+  expect(calls[0]!.unsupportedUnions).toBe('fallback')
+  expect(calls[0]!.inlineTypes).toBe(true)
+})
+
+it('collects skipped stream-route names', () => {
+  const stream = { kind: 'stream', name: 'WatchUsers', method: 'GET', path: '/u/stream', schema: {}, errors: [] } as unknown as AnyHttpRouteDoc
+  const api = { kind: 'api', name: 'GetUser', method: 'GET', fullPath: '/u', schema: { returnType: { type: 'object' } }, errors: [] } as unknown as AnyHttpRouteDoc
+  const group: ScopeGroup = { scopeKey: 'u', camelCase: 'u', routes: [stream, api] }
+
+  const emitter = createStubKotlinEmitter({
+    Response: ok('data class Response(val id: String)', 'Response'),
+  })
+  const result = emitKotlinScope(group, { kotlinPackage: 'p', sourceHash: 'h' }, emitter, new Map())
+
+  expect(result.skippedStreams).toEqual(['WatchUsers'])
+  expect(result.code).toContain('object GetUser')
+  expect(result.code).not.toContain('object WatchUsers')
+})
+```
+
+(Add `import type { KotlinEmitOptions } from './ajsc-adapter.js'` at the top of the test file.)
+
+- [ ] **Step 2: Run the tests and verify they fail**
+
+```bash
+npx vitest run src/codegen/targets/kotlin/emit-scope-kotlin.test.ts
+```
+
+Expected: FAIL — `serializer`/`unsupportedUnions` not on `EmitScopeOptions`; `skippedStreams` not on `EmittedKotlinFile`.
+
+- [ ] **Step 3: Update the scope emitter**
+
+Edit `src/codegen/targets/kotlin/emit-scope-kotlin.ts`:
+
+```ts
+import type { ScopeGroup } from '../../group-routes.js'
+import type { KotlinEmitter } from './ajsc-adapter.js'
+import { emitKotlinRoute, type EmitRouteOpts } from './emit-route-kotlin.js'
+import { kotlinPackageDecl, kotlinSourceHashHeader, kotlinImports, indent } from './format-kotlin.js'
+
+export interface EmitScopeOptions extends EmitRouteOpts {
+  kotlinPackage: string
+  sourceHash: string
+}
+
+export interface EmittedKotlinFile {
+  filename: string
+  code: string
+  /** Names of stream routes within this scope that were skipped. */
+  skippedStreams: string[]
+}
+
+function pascalCase(scope: string): string {
+  return scope
+    .split('-')
+    .filter((p) => p.length > 0)
+    .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+    .join('')
+}
+
+export function emitKotlinScope(
+  group: ScopeGroup,
+  opts: EmitScopeOptions,
+  emitter: KotlinEmitter,
+  errorSchemas: Map<string, unknown>,
+): EmittedKotlinFile {
+  const scopeName = pascalCase(group.scopeKey)
+  const allImports: string[] = []
+  const routeBlocks: string[] = []
+  const skippedStreams: string[] = []
+
+  const routeOpts: EmitRouteOpts = {
+    ...(opts.serializer !== undefined ? { serializer: opts.serializer } : {}),
+    ...(opts.unsupportedUnions !== undefined ? { unsupportedUnions: opts.unsupportedUnions } : {}),
+    ...(opts.arrayItemNaming !== undefined ? { arrayItemNaming: opts.arrayItemNaming } : {}),
+    ...(opts.depluralize !== undefined ? { depluralize: opts.depluralize } : {}),
+    ...(opts.uncountableWords !== undefined ? { uncountableWords: opts.uncountableWords } : {}),
+  }
+
+  for (const route of group.routes) {
+    const r = emitKotlinRoute(route, emitter, errorSchemas, routeOpts)
+    if (r.skipped) {
+      skippedStreams.push(r.routeName)
+      continue
+    }
+    if (r.code === '') continue
+    allImports.push(...r.imports)
+    const wrapped = `object ${r.routeName} {\n${indent(r.code, 1)}\n}`
+    routeBlocks.push(wrapped)
+  }
+
+  const innerScope = routeBlocks.length === 0 ? '' : indent(routeBlocks.join('\n\n'), 1)
+  const scopeBlock = innerScope === ''
+    ? `object ${scopeName} {\n}`
+    : `object ${scopeName} {\n${innerScope}\n}`
+
+  const importsBlock = kotlinImports(allImports)
+  const parts = [
+    kotlinPackageDecl(opts.kotlinPackage),
+    kotlinSourceHashHeader(opts.sourceHash),
+    importsBlock,
+    scopeBlock,
+  ].filter((p) => p.length > 0)
+
+  return { filename: `${scopeName}.kt`, code: parts.join('\n\n') + '\n', skippedStreams }
+}
+```
+
+- [ ] **Step 4: Run scope-emitter tests**
+
+```bash
+npx vitest run src/codegen/targets/kotlin/emit-scope-kotlin.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/codegen/targets/kotlin/emit-scope-kotlin.ts src/codegen/targets/kotlin/emit-scope-kotlin.test.ts
+git commit -m "feat(codegen/kotlin): scope emitter threads new opts and surfaces skippedStreams"
+```
+
+---
+
+## Task 5: Pipeline plumbing for new opts + skipped-stream summary
+
+**Files:**
+- Modify: `src/codegen/pipeline.ts`
+- Modify: `src/codegen/index.ts`
+- Modify: `src/codegen/pipeline.test.ts`
+
+Add `kotlinSerializer` and `unsupportedUnions` to `PipelineOptions` and `GenerateClientOptions`. Aggregate `skippedStreams` across all scopes and emit one console.log summary line.
+
+- [ ] **Step 1: Add tests for opt threading and summary log**
+
+Append to `src/codegen/pipeline.test.ts` inside the existing `describe('runPipeline (kotlin target)', ...)`:
+
+```ts
+it('threads kotlinSerializer and unsupportedUnions to the emitter', async () => {
+  const calls: KotlinEmitOptions[] = []
+  const captureEmitter = {
+    emit(_s: unknown, opts: KotlinEmitOptions) {
+      calls.push(opts)
+      return { code: 'data class Response(val id: String)', rootTypeName: opts.rootTypeName, extractedTypeNames: [], imports: [] }
+    },
+  }
+
+  const envelope = {
+    basePath: '/api', headers: [], version: '1' as const, errors: [],
+    routes: [
+      {
+        kind: 'api', name: 'GetUser', scope: 'users', method: 'GET', fullPath: '/users/:id',
+        schema: { input: { pathParams: { type: 'object' } }, returnType: { type: 'object' } },
+        errors: [],
+      },
+    ],
+  } as any
+
+  await runPipeline({
+    envelope, outDir: 'out', dryRun: true,
+    target: 'kotlin', kotlinPackage: 'p',
+    kotlinSerializer: 'none',
+    unsupportedUnions: 'fallback',
+    kotlinEmitter: captureEmitter,
+  })
+
+  expect(calls.length).toBeGreaterThan(0)
+  for (const c of calls) {
+    expect(c.serializer).toBe('none')
+    expect(c.unsupportedUnions).toBe('fallback')
+    expect(c.inlineTypes).toBe(true)
+  }
+})
+
+it('logs a single summary line for skipped stream routes', async () => {
+  const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+  try {
+    const envelope = {
+      basePath: '/api', headers: [], version: '1' as const, errors: [],
+      routes: [
+        { kind: 'stream', name: 'WatchA', scope: 's', method: 'GET', path: '/a', schema: {}, errors: [] },
+        { kind: 'stream', name: 'WatchB', scope: 's', method: 'GET', path: '/b', schema: {}, errors: [] },
+        { kind: 'api', name: 'GetThing', scope: 's', method: 'GET', fullPath: '/c', schema: { returnType: { type: 'object' } }, errors: [] },
+      ],
+    } as any
+    await runPipeline({
+      envelope, outDir: 'out', dryRun: true,
+      target: 'kotlin', kotlinPackage: 'p',
+      kotlinEmitter: createStubKotlinEmitter({
+        Response: { code: 'data class Response(val ok: Boolean)', rootTypeName: 'Response', extractedTypeNames: [], imports: [] },
+      }),
+    })
+    const summary = logSpy.mock.calls.find((c) => String(c[0]).includes('Skipped'))
+    expect(summary).toBeDefined()
+    expect(String(summary![0])).toContain('Skipped 2 stream routes')
+    expect(String(summary![0])).toContain('WatchA')
+    expect(String(summary![0])).toContain('WatchB')
+  } finally {
+    logSpy.mockRestore()
+  }
+})
+
+it('does not log a summary when there are no skipped streams', async () => {
+  const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+  try {
+    const envelope = {
+      basePath: '/api', headers: [], version: '1' as const, errors: [],
+      routes: [{ kind: 'api', name: 'X', scope: 's', method: 'GET', fullPath: '/x', schema: { returnType: { type: 'object' } }, errors: [] }],
+    } as any
+    await runPipeline({
+      envelope, outDir: 'out', dryRun: true,
+      target: 'kotlin', kotlinPackage: 'p',
+      kotlinEmitter: createStubKotlinEmitter({ Response: { code: 'data class Response(val x: Int)', rootTypeName: 'Response', extractedTypeNames: [], imports: [] } }),
+    })
+    const summary = logSpy.mock.calls.find((c) => String(c[0]).includes('Skipped'))
+    expect(summary).toBeUndefined()
+  } finally {
+    logSpy.mockRestore()
+  }
+})
+```
+
+(Add `import type { KotlinEmitOptions } from './targets/kotlin/ajsc-adapter.js'` near the existing imports.)
+
+- [ ] **Step 2: Run tests and verify they fail**
+
+```bash
+npx vitest run src/codegen/pipeline.test.ts
+```
+
+Expected: FAIL — `kotlinSerializer` and `unsupportedUnions` aren't on `PipelineOptions`; no summary log.
+
+- [ ] **Step 3: Update `PipelineOptions` and runtime behavior**
+
+Edit `src/codegen/pipeline.ts`. Add fields:
+
+```ts
+export interface PipelineOptions {
+  // ... existing fields ...
+  target?: 'ts' | 'kotlin'
+  kotlinPackage?: string
+  kotlinSerializer?: 'kotlinx' | 'none'
+  unsupportedUnions?: 'throw' | 'fallback'
+  kotlinEmitter?: KotlinEmitter
+}
+```
+
+Inside `runPipeline`'s `target === 'kotlin'` branch, build the route-opts (forwarding both Kotlin-specific opts and the relevant pass-throughs from `options.ajsc`) and aggregate skipped streams:
+
+```ts
+if (options.target === 'kotlin') {
+  if (options.kotlinPackage == null) {
+    throw new Error('[ts-procedures-codegen] target=kotlin requires kotlinPackage')
+  }
+  if (options.kotlinEmitter == null) {
+    throw new Error(
+      '[ts-procedures-codegen] target=kotlin requires a kotlinEmitter (CLI resolves via resolveProductionKotlinEmitter)'
+    )
+  }
+
+  const errorSchemas = new Map<string, unknown>()
+  for (const e of envelope.errors) {
+    if (e.schema != null) errorSchemas.set(e.name, e.schema)
+  }
+
+  // Spec §"CLI flags" — `--array-item-naming`, `--depluralize`, `--uncountable-words`
+  // also apply to the Kotlin target. The CLI parks them on `options.ajsc` (a TS-target
+  // structure historically); copy the Kotlin-relevant subset onto the scope opts here.
+  const ajscPassthrough = options.ajsc ?? {}
+
+  const kotlinFiles: GeneratedFile[] = []
+  const allSkipped: string[] = []
+  for (const group of groupArray) {
+    const emitted = emitKotlinScope(
+      group,
+      {
+        kotlinPackage: options.kotlinPackage,
+        sourceHash: hash,
+        ...(options.kotlinSerializer !== undefined ? { serializer: options.kotlinSerializer } : {}),
+        ...(options.unsupportedUnions !== undefined ? { unsupportedUnions: options.unsupportedUnions } : {}),
+        ...(ajscPassthrough.arrayItemNaming !== undefined ? { arrayItemNaming: ajscPassthrough.arrayItemNaming } : {}),
+        ...(ajscPassthrough.depluralize !== undefined ? { depluralize: ajscPassthrough.depluralize } : {}),
+        ...(ajscPassthrough.uncountableWords !== undefined ? { uncountableWords: ajscPassthrough.uncountableWords } : {}),
+      },
+      options.kotlinEmitter,
+      errorSchemas,
+    )
+    kotlinFiles.push({ path: join(outDir, emitted.filename), code: emitted.code })
+    allSkipped.push(...emitted.skippedStreams)
+  }
+
+  if (allSkipped.length > 0) {
+    console.log(
+      `[ts-procedures-codegen] Skipped ${allSkipped.length} stream route${allSkipped.length === 1 ? '' : 's'} (kotlin target): ${allSkipped.join(', ')}`,
+    )
+  }
+
+  // ... existing dryRun / write logic unchanged ...
+  return kotlinFiles
+}
+```
+
+Also add a focused test asserting the passthrough wiring works. Append to `pipeline.test.ts` inside the existing `describe('runPipeline (kotlin target)', ...)`:
+
+```ts
+it('forwards ajsc passthroughs (arrayItemNaming/depluralize/uncountableWords) to the kotlin emitter', async () => {
+  const calls: KotlinEmitOptions[] = []
+  const captureEmitter = {
+    emit(_s: unknown, opts: KotlinEmitOptions) {
+      calls.push(opts)
+      return { code: 'data class Response(val id: String)', rootTypeName: opts.rootTypeName, extractedTypeNames: [], imports: [] }
+    },
+  }
+
+  const envelope = {
+    basePath: '/api', headers: [], version: '1' as const, errors: [],
+    routes: [{ kind: 'api', name: 'GetUser', scope: 'users', method: 'GET', fullPath: '/u', schema: { returnType: { type: 'object' } }, errors: [] }],
+  } as any
+
+  await runPipeline({
+    envelope, outDir: 'out', dryRun: true,
+    target: 'kotlin', kotlinPackage: 'p',
+    ajsc: { arrayItemNaming: 'Item', depluralize: true, uncountableWords: ['data'] },
+    kotlinEmitter: captureEmitter,
+  })
+
+  expect(calls.length).toBe(1)
+  expect(calls[0]!.arrayItemNaming).toBe('Item')
+  expect(calls[0]!.depluralize).toBe(true)
+  expect(calls[0]!.uncountableWords).toEqual(['data'])
+})
+```
+
+- [ ] **Step 4: Update `index.ts` to surface and pass the new opts**
+
+Edit `src/codegen/index.ts`:
+
+```ts
+export interface GenerateClientOptions extends ResolveInput {
+  // ... existing fields ...
+  target?: 'ts' | 'kotlin'
+  kotlinPackage?: string
+  kotlinSerializer?: 'kotlinx' | 'none'
+  unsupportedUnions?: 'throw' | 'fallback'
+  kotlinEmitter?: KotlinEmitter
+}
+
+export async function generateClient(options: GenerateClientOptions): Promise<GeneratedFile[]> {
+  const envelope = await resolveEnvelope(options)
+  return runPipeline({
+    envelope,
+    outDir: options.outDir,
+    ajsc: options.ajsc,
+    clientImportPath: options.clientImportPath,
+    dryRun: options.dryRun,
+    namespaceTypes: options.namespaceTypes,
+    selfContained: options.selfContained,
+    serviceName: options.serviceName,
+    cleanOutDir: options.cleanOutDir,
+    target: options.target,
+    kotlinPackage: options.kotlinPackage,
+    kotlinSerializer: options.kotlinSerializer,
+    unsupportedUnions: options.unsupportedUnions,
+    kotlinEmitter: options.kotlinEmitter,
+  })
+}
+```
+
+- [ ] **Step 5: Run all pipeline tests**
+
+```bash
+npx vitest run src/codegen/pipeline.test.ts
+```
+
+Expected: PASS (all existing + 3 new).
+
+- [ ] **Step 6: Run the full codegen suite to verify TS path is unaffected**
+
+```bash
+npx vitest run src/codegen/
+```
+
+Expected: PASS.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/codegen/pipeline.ts src/codegen/pipeline.test.ts src/codegen/index.ts
+git commit -m "feat(codegen/kotlin): pipeline threads serializer/unsupportedUnions and summarizes skipped streams"
+```
+
+---
+
+## Task 6: CLI flags `--kotlin-serializer` and `--unsupported-unions`
+
+**Files:**
+- Modify: `src/codegen/bin/cli.ts`
+- Modify: `src/codegen/bin/cli.test.ts`
+
+Add two new flags. Per spec: `--kotlin-serializer` lands at `parsed.kotlin.serializer`; `--unsupported-unions` lands at top-level `parsed.unsupportedUnions`. Defaults match prior behavior (`kotlinx`, `throw`).
+
+- [ ] **Step 1: Add tests for both flags**
+
+Append to `src/codegen/bin/cli.test.ts`:
+
+```ts
+describe('cli — kotlin-serializer flag', () => {
+  it('parses --kotlin-serializer kotlinx', () => {
+    const args = parseArgs(['--target', 'kotlin', '--kotlin-package', 'p', '--kotlin-serializer', 'kotlinx', '--out', 'o', '--file', 'e.json'])
+    expect(args.kotlin?.serializer).toBe('kotlinx')
+  })
+
+  it('parses --kotlin-serializer none', () => {
+    const args = parseArgs(['--target', 'kotlin', '--kotlin-package', 'p', '--kotlin-serializer', 'none', '--out', 'o', '--file', 'e.json'])
+    expect(args.kotlin?.serializer).toBe('none')
+  })
+
+  it('reads kotlin.serializer from config', () => {
+    const args = parseArgs(['--out', 'o', '--file', 'e.json'], {
+      target: 'kotlin', kotlin: { package: 'p', serializer: 'none' }, outDir: 'o', file: 'e.json',
+    } as CodegenConfig)
+    expect(args.kotlin?.serializer).toBe('none')
+  })
+
+  it('CLI overrides config', () => {
+    const args = parseArgs(['--kotlin-serializer', 'kotlinx', '--out', 'o', '--file', 'e.json'], {
+      target: 'kotlin', kotlin: { package: 'p', serializer: 'none' }, outDir: 'o', file: 'e.json',
+    } as CodegenConfig)
+    expect(args.kotlin?.serializer).toBe('kotlinx')
+  })
+
+  it('throws on invalid value', () => {
+    expect(() => parseArgs(['--target', 'kotlin', '--kotlin-package', 'p', '--kotlin-serializer', 'bogus', '--out', 'o', '--file', 'e.json']))
+      .toThrow(/--kotlin-serializer/)
+  })
+})
+
+describe('cli — unsupported-unions flag', () => {
+  it('parses --unsupported-unions throw', () => {
+    const args = parseArgs(['--unsupported-unions', 'throw', '--out', 'o', '--file', 'e.json'])
+    expect(args.unsupportedUnions).toBe('throw')
+  })
+
+  it('parses --unsupported-unions fallback', () => {
+    const args = parseArgs(['--unsupported-unions', 'fallback', '--out', 'o', '--file', 'e.json'])
+    expect(args.unsupportedUnions).toBe('fallback')
+  })
+
+  it('reads unsupportedUnions from config', () => {
+    const args = parseArgs(['--out', 'o', '--file', 'e.json'], {
+      unsupportedUnions: 'fallback', outDir: 'o', file: 'e.json',
+    } as CodegenConfig)
+    expect(args.unsupportedUnions).toBe('fallback')
+  })
+
+  it('CLI overrides config', () => {
+    const args = parseArgs(['--unsupported-unions', 'throw', '--out', 'o', '--file', 'e.json'], {
+      unsupportedUnions: 'fallback', outDir: 'o', file: 'e.json',
+    } as CodegenConfig)
+    expect(args.unsupportedUnions).toBe('throw')
+  })
+
+  it('throws on invalid value', () => {
+    expect(() => parseArgs(['--unsupported-unions', 'bogus', '--out', 'o', '--file', 'e.json']))
+      .toThrow(/--unsupported-unions/)
+  })
+
+  it('default is undefined when not set', () => {
+    const args = parseArgs(['--out', 'o', '--file', 'e.json'])
+    expect(args.unsupportedUnions).toBeUndefined()
+  })
+})
+```
+
+- [ ] **Step 2: Run tests and verify they fail**
+
+```bash
+npx vitest run src/codegen/bin/cli.test.ts
+```
+
+Expected: FAIL — flags not parsed; types missing.
+
+- [ ] **Step 3: Update `CodegenConfig`, `ParsedArgs`, and flag parsing**
+
+Edit `src/codegen/bin/cli.ts`:
+
+```ts
+export interface CodegenConfig {
+  // ... existing ...
+  target?: 'ts' | 'kotlin'
+  kotlin?: { package: string; serializer?: 'kotlinx' | 'none' }
+  unsupportedUnions?: 'throw' | 'fallback'
+}
+
+export interface ParsedArgs {
+  // ... existing ...
+  target?: 'ts' | 'kotlin'
+  kotlin?: { package: string; serializer?: 'kotlinx' | 'none' }
+  unsupportedUnions?: 'throw' | 'fallback'
+}
+```
+
+In `parseArgs`, alongside the existing `kotlinPackage` local, add:
+
+```ts
+let kotlinSerializer: 'kotlinx' | 'none' | undefined = config?.kotlin?.serializer
+let unsupportedUnions: 'throw' | 'fallback' | undefined = config?.unsupportedUnions
+```
+
+Add cases in the argv loop (placed near the existing `--kotlin-package` case):
+
+```ts
+} else if (arg === '--kotlin-serializer') {
+  const val = argv[++i]
+  if (val === 'kotlinx' || val === 'none') {
+    kotlinSerializer = val
+  } else {
+    throw new Error(`Invalid --kotlin-serializer value: ${val ?? '(missing)'} (expected 'kotlinx' or 'none')`)
+  }
+} else if (arg === '--unsupported-unions') {
+  const val = argv[++i]
+  if (val === 'throw' || val === 'fallback') {
+    unsupportedUnions = val
+  } else {
+    throw new Error(`Invalid --unsupported-unions value: ${val ?? '(missing)'} (expected 'throw' or 'fallback')`)
+  }
+}
+```
+
+In the return object, replace the existing kotlin spread with one that includes serializer when set, and add `unsupportedUnions`:
+
+```ts
+return {
+  // ... existing ...
+  ...(target !== undefined ? { target } : {}),
+  ...(kotlinPackage !== undefined
+    ? {
+        kotlin: {
+          package: kotlinPackage,
+          ...(kotlinSerializer !== undefined ? { serializer: kotlinSerializer } : {}),
+        },
+      }
+    : {}),
+  ...(unsupportedUnions !== undefined ? { unsupportedUnions } : {}),
+}
+```
+
+In `runWithWatch` and `main`, when forwarding to `generateClient`, include the new fields:
+
+```ts
+const result = await generateClient({
+  // ... existing ...
+  ...(parsed.kotlin?.serializer !== undefined ? { kotlinSerializer: parsed.kotlin.serializer } : {}),
+  ...(parsed.unsupportedUnions !== undefined ? { unsupportedUnions: parsed.unsupportedUnions } : {}),
+  ...kotlinWiring,
+})
+```
+
+(Same change in the `runWithWatch` `runPipeline` call.)
+
+- [ ] **Step 4: Run cli tests**
+
+```bash
+npx vitest run src/codegen/bin/cli.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/codegen/bin/cli.ts src/codegen/bin/cli.test.ts
+git commit -m "feat(codegen/cli): add --kotlin-serializer and --unsupported-unions flags"
+```
+
+---
+
+## Task 7: CLI prints setup-guide pointer after a successful Kotlin run
+
+**Files:**
+- Modify: `src/codegen/bin/cli.ts`
+- Modify: `src/codegen/bin/cli.test.ts`
+
+Extract a small testable helper that prints a one-line pointer to `docs/codegen-kotlin.md`. Call it from `main()` after a successful (non-watch, non-dry-run) Kotlin generation.
+
+- [ ] **Step 1: Add a test for the helper**
+
+Append to `src/codegen/bin/cli.test.ts`:
+
+```ts
+import { printPostRunHints } from './cli.js'
+
+describe('cli — printPostRunHints', () => {
+  it('prints a setup-guide pointer for the kotlin target', () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+    try {
+      printPostRunHints({ target: 'kotlin' })
+      const matched = logSpy.mock.calls.some((c) => String(c[0]).includes('docs/codegen-kotlin.md'))
+      expect(matched).toBe(true)
+    } finally {
+      logSpy.mockRestore()
+    }
+  })
+
+  it('prints nothing for the ts target', () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+    try {
+      printPostRunHints({ target: 'ts' })
+      expect(logSpy).not.toHaveBeenCalled()
+    } finally {
+      logSpy.mockRestore()
+    }
+  })
+
+  it('prints nothing when target is undefined (default ts)', () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+    try {
+      printPostRunHints({})
+      expect(logSpy).not.toHaveBeenCalled()
+    } finally {
+      logSpy.mockRestore()
+    }
+  })
+})
+```
+
+(Add `import { vi } from 'vitest'` to the existing imports if not already present.)
+
+- [ ] **Step 2: Run the test and verify it fails**
+
+```bash
+npx vitest run src/codegen/bin/cli.test.ts
+```
+
+Expected: FAIL — `printPostRunHints` not exported.
+
+- [ ] **Step 3: Add the helper and call it from `main`**
+
+In `src/codegen/bin/cli.ts`, add (near the bottom of the file, before `main`):
+
+```ts
+const KOTLIN_SETUP_GUIDE_URL =
+  'https://bitbucket.org/thermsio/ts-procedures/src/master/docs/codegen-kotlin.md'
+
+export function printPostRunHints(parsed: { target?: 'ts' | 'kotlin' }): void {
+  if (parsed.target === 'kotlin') {
+    console.log(`[ts-procedures-codegen] Kotlin setup guide: ${KOTLIN_SETUP_GUIDE_URL}`)
+  }
+}
+```
+
+Then in `main()`, after the successful (non-dry-run) generation, call it:
+
+```ts
+if (parsed.dryRun) {
+  console.log(`[ts-procedures-codegen] Dry run complete — ${result.length} files would be generated`)
+} else {
+  console.log(`[ts-procedures-codegen] Generated ${result.length} files → ${parsed.outDir}`)
+  printPostRunHints(parsed)
+}
+```
+
+(Also call `printPostRunHints(parsed)` once after `runWithWatch`'s first successful `run()` if you want the watch path to show it — defer to implementer judgement; the spec only requires the non-watch path.)
+
+- [ ] **Step 4: Run cli tests**
+
+```bash
+npx vitest run src/codegen/bin/cli.test.ts
+```
+
+Expected: PASS (3 new tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/codegen/bin/cli.ts src/codegen/bin/cli.test.ts
+git commit -m "feat(codegen/cli): print kotlin setup-guide pointer after successful run"
+```
+
+---
+
+## Task 8: Replace fixture envelope with realistic schemas
+
+**Files:**
+- Modify: `src/codegen/targets/kotlin/__fixtures__/users-envelope.json`
+
+Data-only task; no code or test changes here. Subsequent tasks consume this fixture.
+
+The fixture exercises (per spec):
+- nested objects (response with embedded `address`),
+- a discriminated `oneOf` (body of `CreateUser`),
+- an enum (`status` field on the list response),
+- `format: date-time` (`createdAt` on the response),
+- a kebab-case JSON key (`created-at` mapped to `createdAt`),
+- two error types (`NotFound`, `ValidationError`),
+- a route with no path params (`CreateUser`, `ListUsers`),
+- a route with path params (`GetUser`),
+- query params (`ListUsers`).
+
+- [ ] **Step 1: Replace the file**
+
+Overwrite `src/codegen/targets/kotlin/__fixtures__/users-envelope.json`:
+
+```json
+{
+  "version": "1",
+  "basePath": "/api",
+  "headers": [],
+  "routes": [
+    {
+      "kind": "api",
+      "name": "GetUser",
+      "scope": "users",
+      "method": "GET",
+      "fullPath": "/users/:id",
+      "schema": {
+        "input": {
+          "pathParams": {
+            "type": "object",
+            "properties": { "id": { "type": "string" } },
+            "required": ["id"]
+          }
+        },
+        "returnType": {
+          "type": "object",
+          "properties": {
+            "id": { "type": "string" },
+            "name": { "type": "string" },
+            "created-at": { "type": "string", "format": "date-time" },
+            "address": {
+              "type": "object",
+              "properties": {
+                "street": { "type": "string" },
+                "city": { "type": "string" }
+              },
+              "required": ["street", "city"]
+            }
+          },
+          "required": ["id", "name", "created-at", "address"]
+        }
+      },
+      "errors": ["NotFound"]
+    },
+    {
+      "kind": "api",
+      "name": "CreateUser",
+      "scope": "users",
+      "method": "POST",
+      "fullPath": "/users",
+      "schema": {
+        "input": {
+          "body": {
+            "oneOf": [
+              {
+                "type": "object",
+                "properties": {
+                  "kind": { "const": "guest" },
+                  "displayName": { "type": "string" }
+                },
+                "required": ["kind", "displayName"]
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "kind": { "const": "registered" },
+                  "email": { "type": "string" },
+                  "name": { "type": "string" }
+                },
+                "required": ["kind", "email", "name"]
+              }
+            ]
+          }
+        },
+        "returnType": {
+          "type": "object",
+          "properties": { "id": { "type": "string" } },
+          "required": ["id"]
+        }
+      },
+      "errors": ["ValidationError"]
+    },
+    {
+      "kind": "api",
+      "name": "ListUsers",
+      "scope": "users",
+      "method": "GET",
+      "fullPath": "/users",
+      "schema": {
+        "input": {
+          "query": {
+            "type": "object",
+            "properties": {
+              "status": { "type": "string", "enum": ["active", "inactive"] },
+              "limit": { "type": "integer" }
+            }
+          }
+        },
+        "returnType": {
+          "type": "object",
+          "properties": {
+            "items": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "id": { "type": "string" },
+                  "name": { "type": "string" }
+                },
+                "required": ["id", "name"]
+              }
+            }
+          },
+          "required": ["items"]
+        }
+      },
+      "errors": []
+    }
+  ],
+  "errors": [
+    {
+      "name": "NotFound",
+      "statusCode": 404,
+      "description": "Resource not found",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "name": { "const": "NotFound" },
+          "message": { "type": "string" }
+        },
+        "required": ["name", "message"]
+      }
+    },
+    {
+      "name": "ValidationError",
+      "statusCode": 400,
+      "description": "Input failed validation",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "name": { "const": "ValidationError" },
+          "message": { "type": "string" },
+          "field": { "type": "string" }
+        },
+        "required": ["name", "message"]
+      }
+    }
+  ]
+}
+```
+
+- [ ] **Step 2: Verify the JSON is valid**
+
+```bash
+python3 -m json.tool src/codegen/targets/kotlin/__fixtures__/users-envelope.json > /dev/null
+```
+
+Expected: no output, exit code 0. (`node -e require(...)` is not used because the project is `"type": "module"`. If `python3` isn't available, `npx jq . src/codegen/targets/kotlin/__fixtures__/users-envelope.json > /dev/null` works equivalently.)
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/codegen/targets/kotlin/__fixtures__/users-envelope.json
+git commit -m "test(codegen/kotlin): replace placeholder fixture with realistic 3-route envelope"
+```
+
+---
+
+## Task 9: Update integration test stub map and regenerate the golden
+
+**Files:**
+- Modify: `src/codegen/targets/kotlin/integration.test.ts`
+- Modify: `src/codegen/targets/kotlin/__fixtures__/users-golden.kt`
+
+The integration test runs the pipeline with a **stub** emitter (not real ajsc). The stub returns hand-authored ajsc-style nested-class-shape output for each slot in the new fixture. After updating the stub, regenerate the golden using `UPDATE_GOLDENS=1`.
+
+- [ ] **Step 1: Add `UPDATE_GOLDENS` regeneration mode + update the stub map**
+
+Replace `src/codegen/targets/kotlin/integration.test.ts` with:
+
+```ts
+import { describe, expect, it } from 'vitest'
+import { readFile, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { runPipeline } from '../../pipeline.js'
+import { createStubKotlinEmitter, type KotlinEmitResult } from './ajsc-adapter.js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+const ok = (code: string, rootTypeName: string, imports: string[] = ['kotlinx.serialization.Serializable']): KotlinEmitResult => ({
+  code,
+  rootTypeName,
+  extractedTypeNames: [],
+  imports,
+})
+
+describe('kotlin codegen — integration', () => {
+  it('produces byte-identical output against the golden fixture', async () => {
+    const envelopePath = join(__dirname, '__fixtures__/users-envelope.json')
+    const goldenPath = join(__dirname, '__fixtures__/users-golden.kt')
+    const envelope = JSON.parse(await readFile(envelopePath, 'utf8'))
+
+    // Hand-authored slot outputs in the v7.2 nested-class shape (inlineTypes: true).
+    // The exact whitespace matters — must match what emitKotlinScope produces when
+    // it concatenates these blocks under `object RouteName { ... }`.
+    const emitter = createStubKotlinEmitter({
+      // GetUser
+      PathParams: ok('@Serializable\ndata class PathParams(\n    val id: String,\n)', 'PathParams'),
+      Response: ok(
+        '@Serializable\ndata class Response(\n    val id: String,\n    val name: String,\n    @SerialName("created-at") @Contextual val createdAt: java.time.Instant,\n    val address: Address,\n) {\n    @Serializable\n    data class Address(\n        val street: String,\n        val city: String,\n    )\n}',
+        'Response',
+        ['kotlinx.serialization.Serializable', 'kotlinx.serialization.SerialName', 'kotlinx.serialization.Contextual'],
+      ),
+      NotFound: ok(
+        '@Serializable\ndata class NotFound(\n    val name: String = "NotFound",\n    val message: String,\n)',
+        'NotFound',
+      ),
+
+      // CreateUser
+      Body: ok(
+        '@Serializable\n@JsonClassDiscriminator("kind")\nsealed interface Body {\n    @Serializable\n    @SerialName("guest")\n    data class GuestBody(\n        val displayName: String,\n    ) : Body\n\n    @Serializable\n    @SerialName("registered")\n    data class RegisteredBody(\n        val email: String,\n        val name: String,\n    ) : Body\n}',
+        'Body',
+        ['kotlinx.serialization.Serializable', 'kotlinx.serialization.SerialName', 'kotlinx.serialization.json.JsonClassDiscriminator'],
+      ),
+      // CreateUser response — note the stub map is keyed on rootTypeName,
+      // so we need a distinct map entry. The integration helper lookup uses
+      // the slot name directly — Response is reused. Override per-route by
+      // registering both stubs and keying the call site... but our stub
+      // factory keys ONLY on rootTypeName. Since both routes' Response slots
+      // have rootTypeName="Response", we provide one entry and accept that
+      // both routes get the same stubbed Response. For golden integrity that's
+      // fine — the integration test pins file assembly, not ajsc semantics.
+      // CreateUser's Response is the one currently registered above.
+      ValidationError: ok(
+        '@Serializable\ndata class ValidationError(\n    val name: String = "ValidationError",\n    val message: String,\n    val field: String? = null,\n)',
+        'ValidationError',
+      ),
+
+      // ListUsers
+      Query: ok(
+        '@Serializable\ndata class Query(\n    val status: Status? = null,\n    val limit: Long? = null,\n) {\n    @Serializable\n    enum class Status {\n        @SerialName("active") ACTIVE,\n        @SerialName("inactive") INACTIVE,\n    }\n}',
+        'Query',
+        ['kotlinx.serialization.Serializable', 'kotlinx.serialization.SerialName'],
+      ),
+    })
+
+    // NOTE: GetUser.Response and CreateUser.Response collide on the stub map
+    // (same rootTypeName). The integration test consciously accepts this —
+    // rebuild the map at the call site if more granularity is needed later.
+    // For now the second Response usage in CreateUser will reuse the GetUser
+    // Response stub. We rewrite to a discriminated stub:
+    //
+    // (ignore — see how the route emitter uses rootTypeName 'Response' for
+    // both routes; a single stub entry is fine for golden purposes.)
+
+    const files = await runPipeline({
+      envelope, outDir: 'out', dryRun: true,
+      target: 'kotlin', kotlinPackage: 'com.example.api',
+      kotlinEmitter: emitter,
+    })
+
+    expect(files).toHaveLength(1)
+    expect(files[0]!.path).toBe(join('out', 'Users.kt'))
+    const produced = files[0]!.code
+
+    if (process.env.UPDATE_GOLDENS === '1') {
+      // Replace the source-hash line with the placeholder so the golden is portable.
+      const goldenContent = produced.replace(/^\/\/ Source hash: [a-f0-9]+$/m, '// Source hash: <PLACEHOLDER>')
+      await writeFile(goldenPath, goldenContent, 'utf-8')
+      // eslint-disable-next-line no-console
+      console.log(`[integration.test] Wrote golden: ${goldenPath}`)
+      return
+    }
+
+    const goldenTemplate = await readFile(goldenPath, 'utf8')
+    const sourceHashLine = produced.split('\n').find((l) => l.startsWith('// Source hash:')) ?? ''
+    const goldenWithHash = goldenTemplate.replace('// Source hash: <PLACEHOLDER>', sourceHashLine)
+    expect(produced).toBe(goldenWithHash)
+  })
+})
+```
+
+> **Note on the GetUser/CreateUser Response collision:** the stub map is keyed on `rootTypeName`, so both routes' `Response` slots resolve to the same stubbed value. This is acceptable because the integration test pins our **file assembly logic**, not ajsc's per-route semantics — any divergence in real ajsc output would surface in the kotlinc E2E test (Task 11) instead.
+
+- [ ] **Step 2: Run the test in regenerate mode**
+
+```bash
+UPDATE_GOLDENS=1 npx vitest run src/codegen/targets/kotlin/integration.test.ts
+```
+
+Expected: PASS (writes the golden). Inspect the produced file:
+
+```bash
+cat src/codegen/targets/kotlin/__fixtures__/users-golden.kt
+```
+
+It should contain `package com.example.api`, `// Source hash: <PLACEHOLDER>`, deduped imports (kotlinx.serialization.*), and `object Users { object GetUser { ... } object CreateUser { ... } object ListUsers { ... } }` with each route's nested data classes.
+
+- [ ] **Step 3: Run the test in normal mode**
+
+```bash
+npx vitest run src/codegen/targets/kotlin/integration.test.ts
+```
+
+Expected: PASS — produced output matches the golden modulo the source-hash splice.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/codegen/targets/kotlin/integration.test.ts src/codegen/targets/kotlin/__fixtures__/users-golden.kt
+git commit -m "test(codegen/kotlin): integration test against realistic fixture with golden regen mode"
+```
+
+---
+
+## Task 10: Probe test for `unsupportedUnions: 'fallback'` Kotlin behavior
+
+**Files:**
+- Create: `src/codegen/targets/kotlin/probe-unsupported-unions.test.ts`
+
+ajsc's v7.2 handoff documents the **Swift** `AnyCodable` fallback shape but does not specify what Kotlin emits in fallback mode. We need ground truth before documenting the flag in `docs/codegen-kotlin.md`. Snapshot test, gated on ajsc resolvability.
+
+- [ ] **Step 1: Create the probe test**
+
+Create `src/codegen/targets/kotlin/probe-unsupported-unions.test.ts`:
+
+```ts
+import { describe, it, expect } from 'vitest'
+
+let ajscResolvable = false
+let emitKotlinFn: ((schema: unknown, opts: unknown) => { code: string; imports: string[]; rootTypeName: string; extractedTypeNames: string[] }) | undefined
+
+try {
+  const ajsc = await import('ajsc')
+  if (typeof (ajsc as { emitKotlin?: unknown }).emitKotlin === 'function') {
+    ajscResolvable = true
+    emitKotlinFn = (ajsc as { emitKotlin: typeof emitKotlinFn }).emitKotlin!
+  }
+} catch {
+  // ajsc not installed (e.g. npm install --omit=optional); test skips below.
+}
+
+describe('ajsc.emitKotlin — unsupportedUnions: fallback', () => {
+  it.skipIf(!ajscResolvable)(
+    'produces a deterministic fallback shape for an untagged oneOf',
+    () => {
+      const schema = {
+        oneOf: [{ type: 'string' }, { type: 'integer' }],
+      }
+      const result = emitKotlinFn!(schema, {
+        rootTypeName: 'Mixed',
+        inlineTypes: true,
+        unsupportedUnions: 'fallback',
+      })
+
+      // Snapshot pins the current ajsc behavior. If ajsc changes the fallback
+      // shape, this diff prompts an intentional review and a corresponding
+      // update to docs/codegen-kotlin.md.
+      expect({
+        code: result.code,
+        imports: result.imports.slice().sort(),
+        rootTypeName: result.rootTypeName,
+        extractedTypeNames: result.extractedTypeNames.slice().sort(),
+      }).toMatchSnapshot()
+    },
+  )
+
+  it.skipIf(!ajscResolvable)(
+    'throws when unsupportedUnions defaults to throw',
+    () => {
+      const schema = { oneOf: [{ type: 'string' }, { type: 'integer' }] }
+      expect(() => emitKotlinFn!(schema, { rootTypeName: 'Mixed', inlineTypes: true })).toThrow()
+    },
+  )
+})
+```
+
+- [ ] **Step 2: Run the probe**
+
+```bash
+npx vitest run src/codegen/targets/kotlin/probe-unsupported-unions.test.ts
+```
+
+Expected: PASS (writes a `.snap` file under `__snapshots__/`). If ajsc isn't installed, both tests SKIP — that's fine.
+
+- [ ] **Step 3: Inspect the captured snapshot**
+
+```bash
+cat src/codegen/targets/kotlin/__snapshots__/probe-unsupported-unions.test.ts.snap
+```
+
+Note the actual `code` and `imports` produced. **This is the ground truth for Task 12's `docs/codegen-kotlin.md` "untagged unions" section.** Save the contents (or just reference the snap file path) for that task.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/codegen/targets/kotlin/probe-unsupported-unions.test.ts src/codegen/targets/kotlin/__snapshots__/
+git commit -m "test(codegen/kotlin): probe ajsc unsupportedUnions=fallback shape via snapshot"
+```
+
+---
+
+## Task 11: Activate kotlinc E2E (drop ajsc-availability gate)
+
+**Files:**
+- Modify: `src/codegen/targets/kotlin/e2e-compile.test.ts`
+
+ajsc Phase A is delivered — drop the ajsc-availability check. Keep the `kotlinc` toolchain check + `TS_PROCEDURES_KOTLIN_E2E=1` opt-in env var. Update fixture references (already point at `users-envelope.json`; that file got more interesting in Task 8). Document the kotlinx-serialization-json classpath requirement in a comment so contributors know what to set up locally.
+
+- [ ] **Step 1: Update the test to use only the toolchain + opt-in gate**
+
+Replace the existing `src/codegen/targets/kotlin/e2e-compile.test.ts` with:
+
+```ts
+import { describe, it, expect } from 'vitest'
+import { execSync } from 'node:child_process'
+import { mkdtempSync, writeFileSync, readFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { runPipeline } from '../../pipeline.js'
+import { resolveProductionKotlinEmitter } from './ajsc-adapter.js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+function kotlincAvailable(): boolean {
+  try {
+    execSync('kotlinc -version', { stdio: 'ignore' })
+    return true
+  } catch {
+    return false
+  }
+}
+
+const RUN = process.env.TS_PROCEDURES_KOTLIN_E2E === '1'
+
+/**
+ * E2E: real ajsc → real .kt output → real kotlinc compile.
+ *
+ * Gated on (a) `kotlinc` on PATH and (b) opt-in via env var so default
+ * `npm test` runs stay green for contributors without the toolchain.
+ *
+ * **Classpath setup (one-time, local):** download
+ *   `kotlinx-serialization-json-jvm-<ver>.jar` and
+ *   `kotlinx-serialization-core-jvm-<ver>.jar`
+ * from Maven Central, place under `~/.m2/repo/...` (or any directory),
+ * and set `TS_PROCEDURES_KOTLIN_E2E_CLASSPATH=/path/with:globs.jar` to
+ * inject them into the kotlinc invocation. If the env var is unset the
+ * compile uses kotlinc's default classpath which lacks the kotlinx jars
+ * and fails — that's the expected mode when checking gating works.
+ */
+describe('kotlin codegen — kotlinc compile (gated)', () => {
+  it.skipIf(!kotlincAvailable() || !RUN)(
+    'compiles generated output without errors',
+    async () => {
+      const emitter = await resolveProductionKotlinEmitter()
+      const envelope = JSON.parse(
+        readFileSync(join(__dirname, '__fixtures__/users-envelope.json'), 'utf8'),
+      )
+      const files = await runPipeline({
+        envelope,
+        outDir: 'out',
+        dryRun: true,
+        target: 'kotlin',
+        kotlinPackage: 'com.example.api',
+        kotlinEmitter: emitter,
+      })
+      const dir = mkdtempSync(join(tmpdir(), 'tsp-kotlin-e2e-'))
+      for (const f of files) {
+        writeFileSync(join(dir, f.path.split('/').pop()!), f.code)
+      }
+      const cp = process.env.TS_PROCEDURES_KOTLIN_E2E_CLASSPATH
+      const cpFlag = cp != null && cp.length > 0 ? `-classpath ${cp}` : ''
+      execSync(`kotlinc ${cpFlag} ${dir}/*.kt -d ${dir}/out.jar`, { stdio: 'inherit' })
+      expect(true).toBe(true)
+    },
+  )
+})
+```
+
+- [ ] **Step 2: Run locally to verify gating**
+
+```bash
+npx vitest run src/codegen/targets/kotlin/e2e-compile.test.ts
+```
+
+Expected: SKIPPED (with reason) when `TS_PROCEDURES_KOTLIN_E2E !== '1'`.
+
+- [ ] **Step 3: (Optional, if you have kotlinc + jars) verify the test compiles**
+
+```bash
+TS_PROCEDURES_KOTLIN_E2E=1 \
+  TS_PROCEDURES_KOTLIN_E2E_CLASSPATH=~/Downloads/kotlinx-serialization-json-jvm-*.jar:~/Downloads/kotlinx-serialization-core-jvm-*.jar \
+  npx vitest run src/codegen/targets/kotlin/e2e-compile.test.ts
+```
+
+Expected: PASS. If FAIL on missing imports, the classpath jars are wrong — adjust the env var.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/codegen/targets/kotlin/e2e-compile.test.ts
+git commit -m "test(codegen/kotlin): activate kotlinc E2E (toolchain-gated only); document classpath setup"
+```
+
+---
+
+## Task 12: Create downstream consumer setup guide
+
+**Files:**
+- Create: `docs/codegen-kotlin.md`
+
+The single highest-DX-impact deliverable in the plan. Use the snapshot from Task 10 to fill in the **Untagged unions** section with concrete content (don't speculate).
+
+- [ ] **Step 1: Author the guide**
+
+Create `docs/codegen-kotlin.md`:
+
+````markdown
+# Kotlin Codegen Setup Guide
+
+Generated by `ts-procedures-codegen --target kotlin`. One `.kt` file per scope; types are nested under route objects (`Users.GetUser.Response`, `Users.GetUser.Body.Address`).
+
+## Quickstart
+
+```bash
+npx ts-procedures-codegen \
+  --target kotlin \
+  --kotlin-package com.example.api \
+  --url https://api.example.com/_ts-procedures.json \
+  --out ./src/main/kotlin/com/example/api
+```
+
+Each scope produces one file (e.g. `Users.kt`). Access generated types as `Users.GetUser.Response`, `Users.GetUser.Body.GuestBody`, `Users.GetUser.Errors.NotFound`.
+
+## Gradle setup
+
+The default `--kotlin-serializer kotlinx` mode emits `@Serializable` data classes. Add the kotlinx-serialization plugin and runtime:
+
+```kotlin
+// build.gradle.kts
+plugins {
+    kotlin("jvm") version "<your-kotlin-version>"
+    kotlin("plugin.serialization") version "<your-kotlin-version>"
+}
+
+dependencies {
+    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:<version>")
+}
+```
+
+**JVM only.** Kotlin Multiplatform is not yet supported. If you need KMP-portable types, fall back to `--kotlin-serializer none` or post-process the emitted code.
+
+## Contextual serializers
+
+`format: date-time`, `format: uuid`, `format: uri`, `format: date`, `format: time` map to JVM stdlib types (`java.time.Instant`, `java.util.UUID`, etc.) annotated with `@Contextual`. Kotlinx-serialization does not know how to serialize these natively — register contextual serializers in your `Json` configuration:
+
+```kotlin
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.modules.SerializersModule
+import kotlinx.serialization.modules.contextual
+
+val json = Json {
+    serializersModule = SerializersModule {
+        contextual(java.time.Instant::class, InstantSerializer)
+        contextual(java.util.UUID::class, UUIDSerializer)
+        contextual(java.net.URI::class, URISerializer)
+        // ...etc for any format you use
+    }
+}
+```
+
+The serializers themselves are your responsibility (we don't ship them — the choice between ISO-8601 strings, epoch milliseconds, etc. is application-specific). Public Gist-quality implementations are widely available; we recommend ISO-8601 to match the server.
+
+## Discriminated unions
+
+A schema with a `oneOf` whose variants share a const-valued discriminator (e.g. `kind: "guest" | "registered"`) emits as a sealed interface:
+
+```kotlin
+@Serializable
+@JsonClassDiscriminator("kind")
+sealed interface Body {
+    @Serializable
+    @SerialName("guest")
+    data class GuestBody(val displayName: String) : Body
+
+    @Serializable
+    @SerialName("registered")
+    data class RegisteredBody(val email: String, val name: String) : Body
+}
+```
+
+The discriminator field (`kind`) is **erased** from each variant under `--kotlin-serializer kotlinx` — `@SerialName` carries it on the wire. With `--kotlin-serializer none` the discriminator field is retained.
+
+`@JsonClassDiscriminator` is read automatically by the kotlinx `Json` instance — no extra config needed.
+
+## JSON-key sanitization
+
+Kebab-case and snake-case JSON keys become camelCase property names with `@SerialName` auto-emitted so the wire format stays correct:
+
+```kotlin
+@Serializable
+data class Response(
+    @SerialName("created-at")
+    @Contextual
+    val createdAt: java.time.Instant,
+)
+```
+
+Reserved Kotlin words get a trailing underscore (`class` → `class_`).
+
+## Switching off kotlinx (Moshi, Gson, hand-written)
+
+`--kotlin-serializer none` emits plain `data class` types with no `@Serializable` annotation. You're then responsible for adapter setup:
+
+- **Reflection-based libraries** (Gson) work without further changes.
+- **Codegen-based** (Moshi with codegen) need their own annotation layer added.
+- Sealed interfaces still emit; the discriminator field is **retained** in variants under `none` mode.
+
+## Untagged unions: `--unsupported-unions fallback`
+
+By default, an untagged `oneOf` (e.g. `oneOf: [{ type: 'string' }, { type: 'integer' }]`) throws at codegen time with a path-bearing error message. Pass `--unsupported-unions fallback` to emit a placeholder shape instead.
+
+> **Fill this section in from the snapshot at `src/codegen/targets/kotlin/__snapshots__/probe-unsupported-unions.test.ts.snap`** — capture the actual `code` and `imports` produced. Do not speculate; the implementer should literally copy the snapshot content into this section verbatim before merging this PR.
+
+## Documented limitations
+
+The following ajsc behaviors are intentional and documented; they are **not bugs**:
+
+- `additionalProperties: { type: T }` is silently dropped with a `/** Note: schema permits additional keys of type T — not modeled. */` KDoc note. If your contract uses extra keys, add a sibling `Map<String, T>` field by hand or write a custom `KSerializer`.
+- Tuples with 4 or more positional types throw (`Pair`/`Triple` only). Refactor to a struct schema upstream.
+- Schema-level `examples` and `not` / `patternProperties` are not modeled (the latter throw with a path-bearing error).
+
+## Reference
+
+- Spec: [`docs/superpowers/specs/2026-04-25-ajsc-v7-kotlin-polish-design.md`](./superpowers/specs/2026-04-25-ajsc-v7-kotlin-polish-design.md)
+- ajsc README: `node_modules/ajsc/README.md` (or [npmjs.com/package/ajsc](https://www.npmjs.com/package/ajsc))
+- ts-procedures-codegen CLI flags: see `npx ts-procedures-codegen --help` (TODO: add `--help` if not yet implemented)
+````
+
+- [ ] **Step 2: Replace the placeholder "Untagged unions" subsection with the probe snapshot content**
+
+Read the snapshot file:
+
+```bash
+cat src/codegen/targets/kotlin/__snapshots__/probe-unsupported-unions.test.ts.snap
+```
+
+Copy the `code` value and the sorted `imports` list from the snapshot into the "Untagged unions" section of `docs/codegen-kotlin.md`, replacing the `> **Fill this section in...` block with a concrete code fence showing what ajsc emits.
+
+- [ ] **Step 3: Verify no placeholder remains**
+
+```bash
+grep -n 'Fill this section in' docs/codegen-kotlin.md && { echo 'ERROR: Untagged unions placeholder still present — copy the probe snapshot content in.' >&2; exit 1; } || echo 'OK: no placeholder text remains.'
+```
+
+Expected: `OK: no placeholder text remains.` and exit 0. If the placeholder string is found, go back to Step 2 and copy the snapshot content in.
+
+- [ ] **Step 4: Verify the doc renders sensibly**
+
+```bash
+# Visual check (cat or open in your editor)
+cat docs/codegen-kotlin.md | head -50
+```
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add docs/codegen-kotlin.md
+git commit -m "docs(codegen/kotlin): add downstream consumer setup guide"
+```
+
+---
+
+## Task 13: Update `CLAUDE.md` Kotlin target bullet
+
+**Files:**
+- Modify: `CLAUDE.md`
+
+- [ ] **Step 1: Update the Kotlin target bullet**
+
+In `CLAUDE.md`, find the section "Client Code Generation" and the existing bullet starting with `- **Kotlin target** (\`--target kotlin\`)`. Replace with:
+
+```markdown
+- **Kotlin target** (`--target kotlin`): emits one `.kt` file per scope with nested `object` namespaces (`Users.GetUser`, `Users.GetUser.Body`, `Users.GetUser.Body.Address` — types are emitted with `inlineTypes: true` so nested objects nest as Kotlin nested classes). HTTP method constants, path templates, and path-builder functions (`fun path(p: PathParams)`) for routes with path params; a `const val path` for routes without. Types are emitted by `ajsc.emitKotlin` with `kotlinx.serialization` annotations by default. **No runtime, no adapter, no error registry** — mobile devs own the HTTP layer entirely. Requires `--kotlin-package <com.example.api>` (or `kotlin.package` in the config file). Optional flags: `--kotlin-serializer <kotlinx|none>` (default `kotlinx` — emits `@Serializable`; pass `none` for plain data classes), `--unsupported-unions <throw|fallback>` (default `throw` — surfaces ajsc's escape hatch for untagged `oneOf` schemas).
+- Streams, hooks, per-call options, and error dispatch logic are deliberately out of scope for the Kotlin target. See `docs/superpowers/specs/2026-04-25-ajsc-v7-kotlin-polish-design.md` for the polish design and `docs/codegen-kotlin.md` for downstream consumer setup (Gradle deps, contextual serializers, sealed interfaces).
+```
+
+(Replace the existing two-bullet group; the previous spec reference becomes the new spec.)
+
+- [ ] **Step 2: Run the build to confirm CLAUDE.md is well-formed (no required validation, but a smoke check)**
+
+```bash
+git diff CLAUDE.md
+```
+
+Verify the diff is what you expect — bullet replaced, no surrounding sections damaged.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add CLAUDE.md
+git commit -m "docs: update CLAUDE.md kotlin target bullet for v7.2 polish"
+```
+
+---
+
+## Task 14: Final verification
+
+**Files:** none.
+
+Sanity-check the full codegen suite plus a manual end-to-end run.
+
+- [ ] **Step 1: Run all tests**
+
+```bash
+npm run test 2>&1 | tail -30
+```
+
+Expected: all PASS (E2E compile test SKIPS unless `TS_PROCEDURES_KOTLIN_E2E=1` and `kotlinc` available).
+
+- [ ] **Step 2: Run lint and build**
+
+```bash
+npm run lint && npm run build
+```
+
+Expected: both succeed.
+
+- [ ] **Step 3: Manual end-to-end smoke test using the production resolver**
+
+```bash
+npx ts-procedures-codegen \
+  --target kotlin \
+  --kotlin-package com.example.api \
+  --file src/codegen/targets/kotlin/__fixtures__/users-envelope.json \
+  --out /tmp/kotlin-out
+cat /tmp/kotlin-out/Users.kt
+```
+
+Expected: a real `.kt` file containing `package com.example.api`, `// Source hash: ...`, deduped imports, and `object Users { object GetUser { ... } object CreateUser { ... } object ListUsers { ... } }` with nested data classes. The setup-guide pointer should print at the end:
+
+```
+[ts-procedures-codegen] Kotlin setup guide: https://bitbucket.org/thermsio/ts-procedures/src/master/docs/codegen-kotlin.md
+```
+
+- [ ] **Step 4: (If kotlinc available) run the E2E**
+
+```bash
+TS_PROCEDURES_KOTLIN_E2E=1 \
+  TS_PROCEDURES_KOTLIN_E2E_CLASSPATH=<path-to-jars> \
+  npx vitest run src/codegen/targets/kotlin/e2e-compile.test.ts
+```
+
+Expected: PASS.
+
+---
+
+## Sequencing & dependencies
+
+| Task | Depends on | Blocks |
+|---|---|---|
+| 1. KotlinEmitOptions cleanup | — | 3 |
+| 2. Resolver TODO drop | 1 | — |
+| 3. emit-route inlineTypes + opts | 1 | 4 |
+| 4. emit-scope opts + skippedStreams | 3 | 5 |
+| 5. Pipeline opts + summary | 4 | 6 |
+| 6. CLI flags | 5 | 7 |
+| 7. CLI setup-guide pointer | 6 | — |
+| 8. Realistic fixture | — | 9, 10, 11 |
+| 9. Integration golden regen | 4, 8 | — |
+| 10. Probe test | 1, 8 | 12 |
+| 11. kotlinc E2E activation | 8 | — |
+| 12. Consumer doc | 10 | — |
+| 13. CLAUDE.md | 6, 7 | — |
+| 14. Final verification | all | — |
+
+Tasks 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14 are sequenced linearly above. Tasks 8, 10, 11 can run in any order relative to 1–7 (data and ajsc-only). For agentic execution, follow the order as written for cleanest dependency tracking.
+
+## Definition of done
+
+- All tests in `src/codegen/targets/kotlin/` pass via `npx vitest run src/codegen/targets/kotlin/`.
+- Probe snapshot exists and matches what ajsc currently emits for `unsupportedUnions: 'fallback'`.
+- The `__fixtures__/users-golden.kt` matches the produced output exactly (modulo source-hash splice).
+- `npm run test`, `npm run lint`, `npm run build` all succeed.
+- A manual `npx ts-procedures-codegen --target kotlin ...` run produces a realistic `Users.kt` and prints the setup-guide pointer.
+- The kotlinc E2E test (Task 11) runs locally with `TS_PROCEDURES_KOTLIN_E2E=1` and exits 0 (manual verification before merge — not required in CI unless someone wires up `kotlinc` provisioning separately).
+- `docs/codegen-kotlin.md` exists, has a real "Untagged unions" section sourced from the probe snapshot, and links from `CLAUDE.md`.