ts-procedures 6.0.1 → 6.0.2

package/docs/superpowers/plans/2026-04-24-kotlin-codegen-target.md

@@ -0,0 +1,1265 @@
+# Kotlin Codegen Target 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:** Add a `--target kotlin` mode to `ts-procedures-codegen` that emits one `.kt` file per scope, containing nested `object` namespaces with HTTP method constants, path-template constants, path-builder functions, and types delegated to `ajsc.emitKotlin`. No runtime, no adapter, no error registry — types and URL/method primitives only.
+
+**Architecture:** New `src/codegen/targets/kotlin/` directory housing scope/route emitters. Pipeline dispatches on a new `target` option. Type emission is delegated to `ajsc.emitKotlin` via a thin adapter that returns the explicit `EmitResult` contract (`code`, `rootTypeName`, `extractedTypeNames`, `imports`). Tests use a stubbed emitter so this work can ship before ajsc Phase A; one E2E compile test is gated behind ajsc availability.
+
+**Tech Stack:** TypeScript, Vitest, Node.js. Cross-repo dependency: `ajsc` package's Kotlin emitter (Phase A) — stubbed for unit/integration tests, real for E2E compile test.
+
+**Spec:** [`docs/superpowers/specs/2026-04-24-kotlin-swift-codegen-design.md`](../specs/2026-04-24-kotlin-swift-codegen-design.md)
+
+**Cross-repo dependency:** Phase A of the spec (ajsc Kotlin emitter) is independent work and lives in the `ajsc` repo. This plan covers Phase B only and ships fully testable software using a stubbed emitter. The kotlinc E2E test (Task 9) is gated until ajsc Phase A delivers.
+
+---
+
+## File Structure
+
+**New files:**
+
+| Path | Responsibility |
+|---|---|
+| `src/codegen/targets/kotlin/ajsc-adapter.ts` | Thin wrapper around `ajsc.emitKotlin`; exposes `KotlinEmitter` interface + stub factory for tests. |
+| `src/codegen/targets/kotlin/format-kotlin.ts` | Pure formatting helpers: package decl, source-hash header, deduped imports, indentation. |
+| `src/codegen/targets/kotlin/emit-route-kotlin.ts` | Emits one `object RouteName { ... }` block: method const, path template, path constant/fn, types via ajsc, `Errors` namespace. |
+| `src/codegen/targets/kotlin/emit-scope-kotlin.ts` | Emits one `.kt` file per scope: package + imports + outer `object Scope { <routes> }` + source hash. |
+| `src/codegen/targets/kotlin/__fixtures__/users-envelope.json` | Fixture DocEnvelope for integration tests. |
+| `src/codegen/targets/kotlin/__fixtures__/users-golden.kt` | Golden Kotlin output for byte-identical assertion. |
+| `src/codegen/targets/kotlin/*.test.ts` | One test file per source file. |
+
+**Modified files:**
+
+| Path | Change |
+|---|---|
+| `src/codegen/bin/cli.ts` | Add `--target` and `--kotlin-package` flags; extend `CodegenConfig`/`ParsedArgs`; validate kotlin requires package. |
+| `src/codegen/pipeline.ts` | Extend `PipelineOptions` with `target` + `kotlinPackage`; dispatch to Kotlin emitter, skip TS-only outputs (errors/index/client-runtime files). |
+| `src/codegen/index.ts` | Surface `target` + `kotlinPackage` via `GenerateClientOptions`. |
+
+The `targets/kotlin/` directory is intentionally self-contained so a future split into `@ts-procedures/codegen-kotlin` is a directory move, not a refactor.
+
+---
+
+## Task 1: Define `KotlinEmitter` adapter contract with test stub
+
+**Files:**
+- Create: `src/codegen/targets/kotlin/ajsc-adapter.ts`
+- Create: `src/codegen/targets/kotlin/ajsc-adapter.test.ts`
+
+This task introduces the contract before any consumer needs it. Production wiring to ajsc is deferred to Task 7; for now we only need the type + a stub factory so downstream tasks can test against a deterministic emitter.
+
+- [ ] **Step 1: Write the failing test**
+
+Write `src/codegen/targets/kotlin/ajsc-adapter.test.ts`:
+
+```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' })).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 — module `./ajsc-adapter.js` not found.
+
+- [ ] **Step 3: Write minimal implementation**
+
+Write `src/codegen/targets/kotlin/ajsc-adapter.ts`:
+
+```ts
+import type { JSONSchema7 } from 'json-schema'
+
+export interface KotlinEmitResult {
+  code: string
+  rootTypeName: string
+  extractedTypeNames: string[]
+  imports: string[]
+}
+
+export interface KotlinEmitOptions {
+  rootTypeName: string
+  inlineTypes?: boolean
+  serializer?: 'kotlinx'
+  enumStyle?: string
+  depluralize?: boolean
+  arrayItemNaming?: string
+  uncountableWords?: string[]
+}
+
+export interface KotlinEmitter {
+  emit(schema: JSONSchema7 | Record<string, unknown>, opts: KotlinEmitOptions): KotlinEmitResult
+}
+
+export function createStubKotlinEmitter(
+  results: Record<string, KotlinEmitResult>,
+): KotlinEmitter {
+  return {
+    emit(_schema, opts) {
+      const result = results[opts.rootTypeName]
+      if (result == null) {
+        throw new Error(
+          `[stub-kotlin-emitter] No stubbed result for rootTypeName "${opts.rootTypeName}". ` +
+          `Provide one in the results map.`,
+        )
+      }
+      return result
+    },
+  }
+}
+```
+
+- [ ] **Step 4: Run tests and verify they pass**
+
+```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 "feat(codegen/kotlin): define KotlinEmitter contract + test stub"
+```
+
+---
+
+## Task 2: Format helpers
+
+**Files:**
+- Create: `src/codegen/targets/kotlin/format-kotlin.ts`
+- Create: `src/codegen/targets/kotlin/format-kotlin.test.ts`
+
+Pure functions for assembling Kotlin source. Kept separate so route/scope emitters can compose them without duplication.
+
+- [ ] **Step 1: Write the failing test**
+
+```ts
+import { describe, expect, it } from 'vitest'
+import {
+  kotlinPackageDecl,
+  kotlinSourceHashHeader,
+  kotlinImports,
+  indent,
+} from './format-kotlin.js'
+
+describe('format-kotlin', () => {
+  it('emits a package declaration', () => {
+    expect(kotlinPackageDecl('com.example.api')).toBe('package com.example.api')
+  })
+
+  it('emits a source-hash header line', () => {
+    expect(kotlinSourceHashHeader('abc123')).toBe('// Source hash: abc123')
+  })
+
+  it('dedupes and sorts imports', () => {
+    expect(kotlinImports(['kotlinx.serialization.Serializable', 'kotlinx.serialization.SerialName', 'kotlinx.serialization.Serializable'])).toBe(
+      'import kotlinx.serialization.SerialName\nimport kotlinx.serialization.Serializable',
+    )
+  })
+
+  it('returns empty string when no imports', () => {
+    expect(kotlinImports([])).toBe('')
+  })
+
+  it('indents every line by 4 spaces per level', () => {
+    expect(indent('a\nb', 1)).toBe('    a\n    b')
+    expect(indent('a', 2)).toBe('        a')
+  })
+
+  it('preserves blank lines without trailing whitespace when indenting', () => {
+    expect(indent('a\n\nb', 1)).toBe('    a\n\n    b')
+  })
+})
+```
+
+- [ ] **Step 2: Run the test and verify it fails**
+
+```bash
+npx vitest run src/codegen/targets/kotlin/format-kotlin.test.ts
+```
+
+Expected: FAIL — module not found.
+
+- [ ] **Step 3: Write minimal implementation**
+
+```ts
+export function kotlinPackageDecl(pkg: string): string {
+  return `package ${pkg}`
+}
+
+export function kotlinSourceHashHeader(hash: string): string {
+  return `// Source hash: ${hash}`
+}
+
+export function kotlinImports(imports: string[]): string {
+  if (imports.length === 0) return ''
+  const unique = Array.from(new Set(imports)).sort()
+  return unique.map((i) => `import ${i}`).join('\n')
+}
+
+export function indent(text: string, level: number): string {
+  const prefix = '    '.repeat(level)
+  return text
+    .split('\n')
+    .map((line) => (line.length === 0 ? line : `${prefix}${line}`))
+    .join('\n')
+}
+```
+
+- [ ] **Step 4: Run tests and verify they pass**
+
+```bash
+npx vitest run src/codegen/targets/kotlin/format-kotlin.test.ts
+```
+
+Expected: PASS (6 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/codegen/targets/kotlin/format-kotlin.ts src/codegen/targets/kotlin/format-kotlin.test.ts
+git commit -m "feat(codegen/kotlin): add Kotlin source-formatting helpers"
+```
+
+---
+
+## Task 3: Emit per-route Kotlin block
+
+**Files:**
+- Create: `src/codegen/targets/kotlin/emit-route-kotlin.ts`
+- Create: `src/codegen/targets/kotlin/emit-route-kotlin.test.ts`
+
+Renders one `object RouteName { ... }` block. Drives the `KotlinEmitter` once per schema slot (`pathParams`, `query`, `body`, `response`) and once per error type. Stream routes are skipped with a warning (out of scope).
+
+The output is the inner code of the route object — the scope emitter wraps it with `object RouteName { ... }`.
+
+**Important shape note:** Per the codebase, `route.errors` is `string[]` (taxonomy keys), and the actual error schemas live in the envelope's top-level `errors: ErrorDoc[]` (`{ name, schema, ... }`). The route emitter therefore takes an `errorSchemas: Map<string, unknown>` parameter that the scope emitter (Task 4) and pipeline (Task 5) build from `envelope.errors`.
+
+- [ ] **Step 1: Write the failing test (path-param route)**
+
+Write `src/codegen/targets/kotlin/emit-route-kotlin.test.ts`. Start with one happy-path case:
+
+```ts
+import { describe, expect, it } from 'vitest'
+import type { AnyHttpRouteDoc } from '../../../implementations/types.js'
+import { emitKotlinRoute } from './emit-route-kotlin.js'
+import { createStubKotlinEmitter, type KotlinEmitResult } from './ajsc-adapter.js'
+
+const ok = (code: string, rootTypeName: string): KotlinEmitResult => ({
+  code,
+  rootTypeName,
+  extractedTypeNames: [],
+  imports: ['kotlinx.serialization.Serializable'],
+})
+
+const noErrors = new Map<string, unknown>()
+
+describe('emitKotlinRoute', () => {
+  it('emits an api-kind route with path params and a response', () => {
+    const route: AnyHttpRouteDoc = {
+      kind: 'api',
+      name: 'GetUser',
+      method: 'GET',
+      fullPath: '/users/:id',
+      schema: {
+        input: {
+          pathParams: { type: 'object' },
+        },
+        returnType: { type: 'object' },
+      },
+      errors: [],
+    } as unknown as AnyHttpRouteDoc
+
+    const emitter = createStubKotlinEmitter({
+      PathParams: ok('@Serializable data class PathParams(val id: String)', 'PathParams'),
+      Response: ok('@Serializable data class Response(val id: String, val name: String)', 'Response'),
+    })
+
+    const result = emitKotlinRoute(route, emitter, noErrors)
+
+    expect(result.imports).toContain('kotlinx.serialization.Serializable')
+    expect(result.code).toContain('const val method = "GET"')
+    expect(result.code).toContain('const val pathTemplate = "/users/{id}"')
+    expect(result.code).toContain('fun path(p: PathParams): String = "/users/${p.id}"')
+    expect(result.code).toContain('@Serializable data class PathParams(val id: String)')
+    expect(result.code).toContain('@Serializable data class Response(val id: String, val name: String)')
+  })
+})
+```
+
+- [ ] **Step 2: Run the test and verify it fails**
+
+```bash
+npx vitest run src/codegen/targets/kotlin/emit-route-kotlin.test.ts
+```
+
+Expected: FAIL — module not found.
+
+- [ ] **Step 3: Implement minimal `emitKotlinRoute` for api/rpc with path-param translation**
+
+```ts
+import type { AnyHttpRouteDoc } from '../../../implementations/types.js'
+import type { KotlinEmitter } from './ajsc-adapter.js'
+import { indent } from './format-kotlin.js'
+
+export interface EmitRouteResult {
+  /** Inner body of the `object RouteName { ... }` block — already indented one level. */
+  code: string
+  /** Imports collected from every ajsc emit + any helpers this route used. */
+  imports: string[]
+  /** Outer route name used as the `object RouteName` identifier. */
+  routeName: 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}"`
+}
+
+export function emitKotlinRoute(
+  route: AnyHttpRouteDoc,
+  emitter: KotlinEmitter,
+  errorSchemas: Map<string, unknown>,
+): EmitRouteResult {
+  const kind = (route as { kind?: string }).kind
+  if (kind === 'stream') {
+    console.warn(`[ts-procedures-codegen] Skipping stream route "${route.name}" — streams are out of scope for kotlin target.`)
+    return { code: '', imports: [], routeName: route.name }
+  }
+
+  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>
+
+  // Per-slot emission. Order is fixed for deterministic output.
+  const slots: Array<{ key: string; rootName: string; source: unknown }> = [
+    { key: 'pathParams', rootName: 'PathParams', source: input.pathParams },
+    { key: 'query', rootName: 'Query', source: input.query },
+    { key: 'body', rootName: 'Body', source: input.body },
+    { key: 'response', 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>, { rootTypeName: slot.rootName })
+    lines.push('')
+    lines.push(result.code)
+    imports.push(...result.imports)
+  }
+
+  // Errors namespace — route.errors is `string[]` of taxonomy keys; look up each schema
+  // from the envelope-level errors map. Keys without schemas are skipped silently
+  // (matching the existing TS scope emitter's `errorKeys` filter).
+  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>, { rootTypeName: key })
+      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 }
+}
+```
+
+- [ ] **Step 4: Run the test and verify it passes**
+
+```bash
+npx vitest run src/codegen/targets/kotlin/emit-route-kotlin.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Add tests for additional route shapes**
+
+Append to `emit-route-kotlin.test.ts`:
+
+```ts
+it('emits a route with no path params using a path constant', () => {
+  const route = {
+    kind: 'api',
+    name: 'CreateUser',
+    method: 'POST',
+    fullPath: '/users',
+    schema: { input: { body: { type: 'object' } }, returnType: { type: 'object' } },
+    errors: [],
+  } as unknown as AnyHttpRouteDoc
+
+  const emitter = createStubKotlinEmitter({
+    Body: ok('@Serializable data class Body(val name: String)', 'Body'),
+    Response: ok('@Serializable data class Response(val id: String)', 'Response'),
+  })
+
+  const result = emitKotlinRoute(route, emitter, noErrors)
+  expect(result.code).toContain('const val path = "/users"')
+  expect(result.code).not.toContain('fun path(')
+})
+
+it('emits an Errors namespace for routes whose error keys have schemas in the envelope', () => {
+  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 = createStubKotlinEmitter({
+    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 name: String, val message: String)', 'NotFound'),
+  })
+
+  const errorSchemas = new Map<string, unknown>([['NotFound', { type: 'object' }]])
+  const result = emitKotlinRoute(route, emitter, errorSchemas)
+  expect(result.code).toContain('object Errors {')
+  expect(result.code).toContain('@Serializable data class NotFound(val name: String, val message: String)')
+})
+
+it('silently skips error keys with no schema in the envelope map', () => {
+  const route = {
+    kind: 'api', name: 'GetUser', method: 'GET', fullPath: '/users',
+    schema: {}, errors: ['UnknownTaxonomyKey'],
+  } as unknown as AnyHttpRouteDoc
+  const result = emitKotlinRoute(route, createStubKotlinEmitter({}), new Map())
+  expect(result.code).not.toContain('object Errors {')
+})
+
+it('skips stream routes with a warning', () => {
+  const route = { kind: 'stream', name: 'WatchUsers', method: 'GET', path: '/users/stream', schema: {}, errors: [] } as unknown as AnyHttpRouteDoc
+  const result = emitKotlinRoute(route, createStubKotlinEmitter({}), noErrors)
+  expect(result.code).toBe('')
+})
+```
+
+- [ ] **Step 6: Run all tests and verify they pass**
+
+```bash
+npx vitest run src/codegen/targets/kotlin/emit-route-kotlin.test.ts
+```
+
+Expected: PASS (4 tests).
+
+- [ ] **Step 7: 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): emit per-route object block with method, path, types, errors"
+```
+
+---
+
+## Task 4: Emit per-scope Kotlin file
+
+**Files:**
+- Create: `src/codegen/targets/kotlin/emit-scope-kotlin.ts`
+- Create: `src/codegen/targets/kotlin/emit-scope-kotlin.test.ts`
+
+Renders one `.kt` file per scope. Composes route emissions inside an outer `object Scope { ... }`, prepends package + imports + source-hash header.
+
+- [ ] **Step 1: Write the failing test**
+
+```ts
+import { describe, expect, it } from 'vitest'
+import type { AnyHttpRouteDoc } from '../../../implementations/types.js'
+import type { ScopeGroup } from '../../group-routes.js'
+import { emitKotlinScope } from './emit-scope-kotlin.js'
+import { createStubKotlinEmitter, type KotlinEmitResult } from './ajsc-adapter.js'
+
+const ok = (code: string, rootTypeName: string): KotlinEmitResult => ({
+  code,
+  rootTypeName,
+  extractedTypeNames: [],
+  imports: ['kotlinx.serialization.Serializable'],
+})
+
+describe('emitKotlinScope', () => {
+  it('produces a complete kotlin source file for a single-route scope', () => {
+    const route: AnyHttpRouteDoc = {
+      kind: 'api',
+      name: 'GetUser',
+      method: 'GET',
+      fullPath: '/users/:id',
+      schema: { input: { pathParams: { type: 'object' } }, returnType: { type: 'object' } },
+      errors: [],
+    } as unknown as AnyHttpRouteDoc
+
+    const group: ScopeGroup = { scopeKey: 'users', camelCase: 'users', routes: [route] }
+    const emitter = createStubKotlinEmitter({
+      PathParams: ok('@Serializable data class PathParams(val id: String)', 'PathParams'),
+      Response: ok('@Serializable data class Response(val id: String)', 'Response'),
+    })
+
+    const file = emitKotlinScope(group, { kotlinPackage: 'com.example.api', sourceHash: 'abc123' }, emitter, new Map())
+
+    expect(file.filename).toBe('Users.kt')
+    expect(file.code).toContain('package com.example.api')
+    expect(file.code).toContain('// Source hash: abc123')
+    expect(file.code).toContain('import kotlinx.serialization.Serializable')
+    expect(file.code).toContain('object Users {')
+    expect(file.code).toContain('object GetUser {')
+    expect(file.code).toContain('const val method = "GET"')
+  })
+
+  it('joins multiple routes inside one scope object', () => {
+    const route1 = { kind: 'api', name: 'GetUser', method: 'GET', fullPath: '/users/:id', schema: {}, errors: [] } as unknown as AnyHttpRouteDoc
+    const route2 = { kind: 'api', name: 'CreateUser', method: 'POST', fullPath: '/users', schema: {}, errors: [] } as unknown as AnyHttpRouteDoc
+    const group: ScopeGroup = { scopeKey: 'users', camelCase: 'users', routes: [route1, route2] }
+    const emitter = createStubKotlinEmitter({})
+
+    const file = emitKotlinScope(group, { kotlinPackage: 'com.example.api', sourceHash: 'h' }, emitter, new Map())
+    expect(file.code).toContain('object GetUser {')
+    expect(file.code).toContain('object CreateUser {')
+    // exactly one outer scope object
+    expect((file.code.match(/^object Users \{/gm) ?? []).length).toBe(1)
+  })
+
+  it('uses PascalCase scope name for the filename and outer object', () => {
+    const group: ScopeGroup = { scopeKey: 'admin-users', camelCase: 'adminUsers', routes: [] }
+    const file = emitKotlinScope(group, { kotlinPackage: 'p', sourceHash: 'h' }, createStubKotlinEmitter({}), new Map())
+    expect(file.filename).toBe('AdminUsers.kt')
+    expect(file.code).toContain('object AdminUsers {')
+  })
+})
+```
+
+- [ ] **Step 2: Run the test and verify it fails**
+
+```bash
+npx vitest run src/codegen/targets/kotlin/emit-scope-kotlin.test.ts
+```
+
+Expected: FAIL.
+
+- [ ] **Step 3: Implement `emitKotlinScope`**
+
+```ts
+import type { ScopeGroup } from '../../group-routes.js'
+import type { KotlinEmitter } from './ajsc-adapter.js'
+import { emitKotlinRoute } from './emit-route-kotlin.js'
+import { kotlinPackageDecl, kotlinSourceHashHeader, kotlinImports, indent } from './format-kotlin.js'
+
+export interface EmitScopeOptions {
+  kotlinPackage: string
+  sourceHash: string
+}
+
+export interface EmittedKotlinFile {
+  filename: string
+  code: 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[] = []
+
+  for (const route of group.routes) {
+    const r = emitKotlinRoute(route, emitter, errorSchemas)
+    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' }
+}
+```
+
+- [ ] **Step 4: Run tests and verify they pass**
+
+```bash
+npx vitest run src/codegen/targets/kotlin/emit-scope-kotlin.test.ts
+```
+
+Expected: PASS (3 tests).
+
+- [ ] **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): emit per-scope .kt file with package, imports, and outer object"
+```
+
+---
+
+## Task 5: Pipeline target dispatch
+
+**Files:**
+- Modify: `src/codegen/pipeline.ts`
+- Modify: `src/codegen/pipeline.test.ts` (extend) or create dedicated kotlin pipeline test
+- Modify: `src/codegen/index.ts` (surface new options)
+
+When `target === 'kotlin'`, the pipeline must skip TS-only outputs (`_errors.ts`, `index.ts`, `_types.ts`, `_client.ts`) and instead emit only Kotlin `.kt` files.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `src/codegen/pipeline.test.ts`:
+
+```ts
+import { runPipeline } from './pipeline.js'
+import { createStubKotlinEmitter } from './targets/kotlin/ajsc-adapter.js'
+
+describe('runPipeline (kotlin target)', () => {
+  it('emits only .kt files when target is "kotlin"', async () => {
+    const envelope = {
+      version: '1' as const,
+      routes: [
+        {
+          kind: 'api',
+          name: 'GetUser',
+          scope: 'users',
+          method: 'GET',
+          fullPath: '/users/:id',
+          schema: { input: { pathParams: { type: 'object' } }, returnType: { type: 'object' } },
+          errors: [],
+        },
+      ],
+      errors: [],
+    } as any
+
+    const files = await runPipeline({
+      envelope,
+      outDir: 'out',
+      dryRun: true,
+      target: 'kotlin',
+      kotlinPackage: 'com.example.api',
+      kotlinEmitter: createStubKotlinEmitter({
+        PathParams: { code: '@Serializable data class PathParams(val id: String)', rootTypeName: 'PathParams', extractedTypeNames: [], imports: ['kotlinx.serialization.Serializable'] },
+        Response: { code: '@Serializable data class Response(val id: String)', rootTypeName: 'Response', extractedTypeNames: [], imports: ['kotlinx.serialization.Serializable'] },
+      }),
+    })
+
+    expect(files.map((f) => f.path)).toEqual(['out/Users.kt'])
+    expect(files[0].code).toContain('object Users {')
+  })
+
+  it('does not emit _errors.ts, index.ts, or client runtime files when target is "kotlin"', async () => {
+    const envelope = { version: '1', routes: [], errors: [] } as any
+    const files = await runPipeline({
+      envelope, outDir: 'out', dryRun: true,
+      target: 'kotlin', kotlinPackage: 'p',
+      kotlinEmitter: createStubKotlinEmitter({}),
+    })
+    expect(files.find((f) => f.path.endsWith('_errors.ts'))).toBeUndefined()
+    expect(files.find((f) => f.path.endsWith('index.ts'))).toBeUndefined()
+    expect(files.find((f) => f.path.endsWith('_client.ts'))).toBeUndefined()
+  })
+})
+```
+
+- [ ] **Step 2: Run the test and verify it fails**
+
+```bash
+npx vitest run src/codegen/pipeline.test.ts
+```
+
+Expected: FAIL — `target` and `kotlinPackage` not on `PipelineOptions`.
+
+- [ ] **Step 3: Extend `PipelineOptions` and dispatch on target**
+
+Edit `src/codegen/pipeline.ts`. Add to `PipelineOptions`:
+
+```ts
+import type { KotlinEmitter } from './targets/kotlin/ajsc-adapter.js'
+import { emitKotlinScope } from './targets/kotlin/emit-scope-kotlin.js'
+
+export interface PipelineOptions {
+  // ... existing fields ...
+  target?: 'ts' | 'kotlin'
+  kotlinPackage?: string
+  /** Injected for tests; production wiring resolves a real ajsc emitter. */
+  kotlinEmitter?: KotlinEmitter
+}
+```
+
+Inside `runPipeline`, before the existing TS scope-emit loop, branch on target:
+
+```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 (production wiring pending — Task 7)')
+  }
+
+  // Route errors are taxonomy keys (string[]); look up actual schemas from the
+  // envelope's top-level errors array. Mirrors the existing TS scope emitter.
+  const errorSchemas = new Map<string, unknown>()
+  for (const e of envelope.errors) {
+    if (e.schema != null) errorSchemas.set(e.name, e.schema)
+  }
+
+  const files: GeneratedFile[] = []
+  for (const group of groupArray) {
+    const emitted = emitKotlinScope(
+      group,
+      { kotlinPackage: options.kotlinPackage, sourceHash: hash },
+      options.kotlinEmitter,
+      errorSchemas,
+    )
+    files.push({ path: join(outDir, emitted.filename), code: emitted.code })
+  }
+
+  if (dryRun) {
+    for (const f of files) {
+      console.log(`[dry-run] Would write: ${f.path} (${Buffer.byteLength(f.code, 'utf8')} bytes)`)
+    }
+  } else {
+    if (cleanOutDir) await rm(outDir, { recursive: true, force: true })
+    await mkdir(outDir, { recursive: true })
+    await Promise.all(files.map((f) => writeFile(f.path, f.code, 'utf8')))
+  }
+  return files
+}
+```
+
+(All existing TS code remains below, untouched.)
+
+Also update `src/codegen/index.ts` to surface `target`, `kotlinPackage`, `kotlinEmitter` on `GenerateClientOptions`, and pass them through to `runPipeline`.
+
+- [ ] **Step 4: Run tests and verify they pass**
+
+```bash
+npx vitest run src/codegen/pipeline.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Run full codegen test suite to verify TS path is unaffected**
+
+```bash
+npx vitest run src/codegen/
+```
+
+Expected: PASS — all existing TS-target tests still green.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/codegen/pipeline.ts src/codegen/pipeline.test.ts src/codegen/index.ts
+git commit -m "feat(codegen): dispatch on target to emit kotlin .kt files"
+```
+
+---
+
+## Task 6: CLI flags for kotlin target
+
+**Files:**
+- Modify: `src/codegen/bin/cli.ts`
+- Modify: `src/codegen/bin/cli.test.ts`
+
+Adds `--target` and `--kotlin-package` flags. Extends `CodegenConfig` for the `kotlin` config-file section. Validates that kotlin requires a package via either CLI or config.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `src/codegen/bin/cli.test.ts`. The existing CLI uses a single `parseArgs(argv, config?)` signature — pass an empty argv with a config to test config-only resolution.
+
+```ts
+describe('cli — kotlin target', () => {
+  it('parses --target kotlin and --kotlin-package from CLI flags', () => {
+    const args = parseArgs(
+      ['--target', 'kotlin', '--kotlin-package', 'com.example.api', '--out', 'out', '--file', 'env.json'],
+    )
+    expect(args.target).toBe('kotlin')
+    expect(args.kotlin?.package).toBe('com.example.api')
+  })
+
+  it('reads kotlin.package from config when no CLI flag is provided', () => {
+    const config: CodegenConfig = {
+      target: 'kotlin',
+      kotlin: { package: 'com.example.api' },
+      outDir: 'out',
+      file: 'env.json',
+    }
+    const args = parseArgs(['--out', 'out', '--file', 'env.json'], config)
+    expect(args.target).toBe('kotlin')
+    expect(args.kotlin?.package).toBe('com.example.api')
+  })
+
+  it('CLI flag overrides config value', () => {
+    const config: CodegenConfig = {
+      target: 'kotlin',
+      kotlin: { package: 'old.pkg' },
+      outDir: 'out',
+      file: 'env.json',
+    }
+    const args = parseArgs(['--kotlin-package', 'new.pkg', '--out', 'out', '--file', 'env.json'], config)
+    expect(args.kotlin?.package).toBe('new.pkg')
+  })
+
+  it('errors when target is kotlin and no package is provided', () => {
+    expect(() =>
+      parseArgs(['--target', 'kotlin', '--out', 'out', '--file', 'env.json']),
+    ).toThrow(/--kotlin-package/)
+  })
+
+  it('--target ts is the default', () => {
+    const args = parseArgs(['--out', 'out', '--file', 'env.json'])
+    expect(args.target ?? 'ts').toBe('ts')
+  })
+})
+```
+
+(If `parseArgs` is not currently exported from `cli.ts`, export it. The implementer should mirror existing test style in `cli.test.ts` — there is no separate `mergeConfigAndArgs` helper.)
+
+- [ ] **Step 2: Run the test and verify it fails**
+
+```bash
+npx vitest run src/codegen/bin/cli.test.ts
+```
+
+Expected: FAIL.
+
+- [ ] **Step 3: Extend `CodegenConfig` / `ParsedArgs` and add flag parsing**
+
+In `cli.ts`, add to both interfaces:
+
+```ts
+target?: 'ts' | 'kotlin'
+kotlin?: { package: string }
+```
+
+Add flag parsing for `--target <ts|kotlin>` and `--kotlin-package <pkg>`. Add validation: when `target === 'kotlin'`, require either CLI flag or `config.kotlin.package`; otherwise throw `Error('[ts-procedures-codegen] target=kotlin requires --kotlin-package or kotlin.package in config')`.
+
+In the existing `--service-name` handling, log a debug-level note when the target is Kotlin (the value is silently ignored per spec); no behavior change.
+
+- [ ] **Step 4: Run all CLI tests and verify they pass**
+
+```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 --target and --kotlin-package flags"
+```
+
+---
+
+## Task 7: Wire production ajsc emitter
+
+**Files:**
+- Modify: `src/codegen/targets/kotlin/ajsc-adapter.ts`
+- Modify: `src/codegen/bin/cli.ts` (resolve the production emitter when `target === 'kotlin'`)
+
+So far the pipeline requires the caller to inject a `KotlinEmitter`. This task wires the production path that imports `ajsc` and adapts its return shape to `KotlinEmitResult`.
+
+**ajsc dependency:** This task depends on `ajsc` exposing `emitKotlin`. If ajsc Phase A is not yet delivered, complete steps 1–4 with a clear `TODO(ajsc-phase-a)` marker; the import will throw a clear error at runtime until ajsc ships. The unit-test path continues to use the stub.
+
+- [ ] **Step 1: Add a graceful resolver**
+
+Append to `ajsc-adapter.ts`:
+
+```ts
+/**
+ * Resolves the production Kotlin emitter from `ajsc`. Throws a clear error
+ * if the ajsc package does not yet expose `emitKotlin` (Phase A pending).
+ */
+export async function resolveProductionKotlinEmitter(): Promise<KotlinEmitter> {
+  // TODO(ajsc-phase-a): replace dynamic import with a static import once ajsc ships.
+  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. ' +
+      'Kotlin codegen requires ajsc Phase A. See docs/superpowers/specs/2026-04-24-kotlin-swift-codegen-design.md.',
+    )
+  }
+  return {
+    emit(schema, opts) {
+      // ajsc's return shape is normalized to KotlinEmitResult here.
+      const r = (emitKotlin as (s: unknown, o: unknown) => KotlinEmitResult)(schema, opts)
+      return r
+    },
+  }
+}
+```
+
+- [ ] **Step 2: Test the resolver fails clearly when ajsc.emitKotlin is missing**
+
+In `ajsc-adapter.test.ts`:
+
+```ts
+it('throws a clear error when ajsc.emitKotlin is unavailable', async () => {
+  // We can't easily mock the dynamic import; this test serves as documentation.
+  // On a system where ajsc has no emitKotlin export, this will throw.
+  // Skipped by default; flip to .only locally to verify message wording.
+  expect.assertions(0)
+})
+```
+
+- [ ] **Step 3: Wire CLI to pass the resolved emitter into the pipeline**
+
+In `cli.ts` where `runPipeline` / `generateClient` is invoked, when `target === 'kotlin'`, await `resolveProductionKotlinEmitter()` and pass it as `kotlinEmitter`.
+
+- [ ] **Step 4: Run all codegen tests**
+
+```bash
+npx vitest run src/codegen/
+```
+
+Expected: PASS — TS path unchanged; kotlin unit tests still pass via stub injection.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/codegen/targets/kotlin/ajsc-adapter.ts src/codegen/bin/cli.ts src/codegen/targets/kotlin/ajsc-adapter.test.ts
+git commit -m "feat(codegen/kotlin): resolve production ajsc.emitKotlin (gated on ajsc phase A)"
+```
+
+---
+
+## Task 8: Integration test with fixture envelope and golden output
+
+**Files:**
+- Create: `src/codegen/targets/kotlin/__fixtures__/users-envelope.json`
+- Create: `src/codegen/targets/kotlin/__fixtures__/users-golden.kt`
+- Create: `src/codegen/targets/kotlin/integration.test.ts`
+
+Asserts the entire pipeline produces byte-identical output for a representative envelope. Uses a stub emitter with hand-crafted realistic ajsc-style outputs.
+
+- [ ] **Step 1: Create the fixture envelope**
+
+Write `src/codegen/targets/kotlin/__fixtures__/users-envelope.json` with one scope (`users`) containing two routes:
+- `GetUser` (GET `/users/:id`, path params + response, error `NotFound`)
+- `CreateUser` (POST `/users`, body + response)
+
+Route-level `errors` is `string[]` of taxonomy keys; actual error schemas live in the envelope's top-level `errors` array. Match that shape:
+
+```json
+{
+  "version": "1",
+  "routes": [
+    {
+      "kind": "api",
+      "name": "GetUser",
+      "scope": "users",
+      "method": "GET",
+      "fullPath": "/users/:id",
+      "schema": {
+        "input": { "pathParams": { "type": "object" } },
+        "returnType": { "type": "object" }
+      },
+      "errors": ["NotFound"]
+    },
+    {
+      "kind": "api",
+      "name": "CreateUser",
+      "scope": "users",
+      "method": "POST",
+      "fullPath": "/users",
+      "schema": {
+        "input": { "body": { "type": "object" } },
+        "returnType": { "type": "object" }
+      },
+      "errors": []
+    }
+  ],
+  "errors": [
+    { "name": "NotFound", "schema": { "type": "object" }, "statusCode": 404 }
+  ]
+}
+```
+
+- [ ] **Step 2: Create the golden Kotlin output**
+
+Write `src/codegen/targets/kotlin/__fixtures__/users-golden.kt`. Use a realistic but stub-driven shape that matches what the test will produce. The exact contents will need to align with the source-hash of the envelope (computed at test time — see Step 4); for now write the golden file *without* the source-hash line, and the test will splice it.
+
+(The golden file's contents are deterministic given the stub emitter map. Hand-author it to match what `emitKotlinScope` produces for the fixture envelope; iterate after the first test run if needed.)
+
+- [ ] **Step 3: Write the integration test**
+
+Write `src/codegen/targets/kotlin/integration.test.ts`. Note: this package is `"type": "module"` so `__dirname` is not available — use the existing `fileURLToPath(import.meta.url)` pattern (see `src/codegen/emit-client-types.ts:14-15` for reference).
+
+```ts
+import { describe, expect, it } from 'vitest'
+import { readFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { runPipeline } from '../../pipeline.js'
+import { createStubKotlinEmitter } from './ajsc-adapter.js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+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'))
+    const goldenTemplate = await readFile(goldenPath, 'utf8')
+
+    const emitter = createStubKotlinEmitter({
+      PathParams: { code: '@Serializable\ndata class PathParams(val id: String)', rootTypeName: 'PathParams', extractedTypeNames: [], imports: ['kotlinx.serialization.Serializable'] },
+      Response: { code: '@Serializable\ndata class Response(val id: String, val name: String)', rootTypeName: 'Response', extractedTypeNames: [], imports: ['kotlinx.serialization.Serializable'] },
+      Body: { code: '@Serializable\ndata class Body(val name: String, val email: String)', rootTypeName: 'Body', extractedTypeNames: [], imports: ['kotlinx.serialization.Serializable'] },
+      NotFound: { code: '@Serializable\ndata class NotFound(val name: String = "NotFound", val message: String)', rootTypeName: 'NotFound', extractedTypeNames: [], imports: ['kotlinx.serialization.Serializable'] },
+    })
+
+    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('out/Users.kt')
+
+    // Hash is deterministic given envelope contents; splice into golden template.
+    const sourceHashLine = files[0].code.split('\n').find((l) => l.startsWith('// Source hash:')) ?? ''
+    const goldenWithHash = goldenTemplate.replace('// Source hash: <PLACEHOLDER>', sourceHashLine)
+    expect(files[0].code).toBe(goldenWithHash)
+  })
+})
+```
+
+- [ ] **Step 4: Run the test, capture actual output, finalize the golden file**
+
+```bash
+npx vitest run src/codegen/targets/kotlin/integration.test.ts
+```
+
+Expected on first run: FAIL — diff between produced output and golden. Inspect the failure, write the golden file using the produced output (with `// Source hash: <PLACEHOLDER>` swapped in for the real hash line). Re-run.
+
+- [ ] **Step 5: Re-run until PASS**
+
+```bash
+npx vitest run src/codegen/targets/kotlin/integration.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/codegen/targets/kotlin/__fixtures__ src/codegen/targets/kotlin/integration.test.ts
+git commit -m "test(codegen/kotlin): integration test with fixture envelope and golden output"
+```
+
+---
+
+## Task 9: kotlinc E2E compile test (gated)
+
+**Files:**
+- Create: `src/codegen/targets/kotlin/e2e-compile.test.ts`
+
+Generates real Kotlin output and runs `kotlinc` to verify the source compiles. Skipped unless `kotlinc` is available *and* ajsc Phase A is delivered.
+
+**Prerequisites:** ajsc package exposes `emitKotlin`; `kotlinc` is on `PATH`. The test uses `vitest`'s `it.skipIf` to gracefully skip when these aren't met.
+
+- [ ] **Step 1: Write the gated test**
+
+```ts
+import { describe, it, expect } from 'vitest'
+import { execSync } from 'node:child_process'
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+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
+  }
+}
+
+describe('kotlin codegen — kotlinc compile (gated)', () => {
+  it.skipIf(!kotlincAvailable() || process.env.TS_PROCEDURES_KOTLIN_E2E !== '1')(
+    'compiles generated output without errors',
+    async () => {
+      const emitter = await resolveProductionKotlinEmitter()
+      const envelope = JSON.parse(
+        await readFile(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)
+      }
+      // Compile against the kotlinx-serialization runtime jar present in the test env.
+      // If the jar isn't on the classpath, this fails; CI must provide it.
+      execSync(`kotlinc ${dir}/*.kt -d ${dir}/out.jar`, { stdio: 'inherit' })
+      expect(true).toBe(true) // reaching here means compile succeeded
+    },
+  )
+})
+```
+
+- [ ] **Step 2: Run locally to verify the gating works (skip path)**
+
+```bash
+npx vitest run src/codegen/targets/kotlin/e2e-compile.test.ts
+```
+
+Expected: SKIPPED (with reason) when `TS_PROCEDURES_KOTLIN_E2E !== '1'` or `kotlinc` is unavailable.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/codegen/targets/kotlin/e2e-compile.test.ts
+git commit -m "test(codegen/kotlin): gated kotlinc compile e2e (requires ajsc phase A + kotlinc)"
+```
+
+---
+
+## Task 10: Documentation
+
+**Files:**
+- Modify: `CLAUDE.md` (codegen section)
+- Modify: `README.md` (if present, note the new `--target kotlin` flag)
+
+- [ ] **Step 1: Update CLAUDE.md**
+
+In the "Client Code Generation" section of `CLAUDE.md`, add:
+
+```markdown
+- **Kotlin target** (`--target kotlin`): emits one `.kt` file per scope with nested `object` namespaces (`Users.GetUser.Response`), HTTP method constants, path templates, and path-builder functions. Types are emitted by `ajsc.emitKotlin` with `kotlinx.serialization` annotations. **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).
+- Streams, hooks, per-call options, and error dispatch logic are deliberately out of scope for the Kotlin target. See `docs/superpowers/specs/2026-04-24-kotlin-swift-codegen-design.md`.
+```
+
+- [ ] **Step 2: Verify build still passes**
+
+```bash
+npm run build
+npm run test
+npm run lint
+```
+
+Expected: all green.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add CLAUDE.md README.md
+git commit -m "docs: document kotlin codegen target"
+```
+
+---
+
+## Sequencing & dependencies
+
+| Task | Depends on | Blocks |
+|---|---|---|
+| 1. KotlinEmitter contract | — | 3, 4, 5, 7, 8, 9 |
+| 2. Format helpers | — | 4, 5 |
+| 3. Per-route emitter | 1, 2 | 4, 8 |
+| 4. Per-scope emitter | 1, 2, 3 | 5, 8 |
+| 5. Pipeline dispatch | 1, 4 | 6, 8 |
+| 6. CLI flags | 5 | 7 |
+| 7. Production ajsc wiring | 1, 5, 6 | 9 |
+| 8. Integration test | 4, 5 | — |
+| 9. kotlinc E2E (gated) | 7 + ajsc Phase A | — |
+| 10. Docs | all | — |
+
+Tasks 1, 2, 3, 4, 5, 6, 7, 8, 10 can be executed sequentially in a single session and are fully testable without external dependencies (stubbed emitter). Task 9 is gated; mark as deferred and revisit after ajsc Phase A delivers.
+
+## Definition of done
+
+- All tests in `src/codegen/targets/kotlin/` pass via `npx vitest run src/codegen/targets/kotlin/`.
+- All existing tests in `src/codegen/` still pass — TS-target behavior is unchanged.
+- `npm run build` succeeds.
+- `npm run lint` succeeds.
+- A manual run of `npx ts-procedures-codegen --target kotlin --kotlin-package com.example.api --file src/codegen/targets/kotlin/__fixtures__/users-envelope.json --out /tmp/kotlin-out` produces a `Users.kt` file matching the integration golden (modulo source-hash).
+- The kotlinc E2E test (Task 9) is staged for activation when ajsc Phase A delivers; documented in the commit and in CLAUDE.md.