ts-procedures 8.2.0 → 8.3.0

package/docs/ai-agent-setup.md

@@ -22,7 +22,7 @@ npx ts-procedures-setup copilot      # GitHub Copilot only
 
 | Tool | Files | Auto-updates? |
 |------|-------|---------------|
-| **Claude Code** | `.claude/skills/ts-procedures/`, `.claude/skills/ts-procedures-scaffold/`, `.claude/skills/ts-procedures-review/`, `.claude/agents/ts-procedures-architect.md` | Yes |
+| **Claude Code** | `.claude/skills/ts-procedures/` (single skill — reference + `review`/`scaffold` modes + Kotlin/Swift codegen), `.claude/agents/ts-procedures-architect.md` | Yes |
 | **Cursor** | `.cursorrules` (marker-based section) | Yes |
 | **GitHub Copilot** | `.github/copilot-instructions.md` (marker-based section) | Yes |
 
@@ -34,9 +34,10 @@ After initial setup, rules are automatically refreshed on every `npm install` or
 
 Once installed, Claude Code gets:
 
-- **Framework reference skill** — `ts-procedures` with core API, schema system, error handling, and decision framework (auto-discovered by Claude Code)
-- **Scaffold skill** — `/ts-procedures-scaffold <type> <Name>` generates procedures, streams, and HTTP setups with correct patterns
-- **Review skill** — `/ts-procedures-review <path>` checks code against a 60+ item checklist
+- **Unified `ts-procedures` skill** — one skill with three modes selected by the first word of its arguments:
+  - *Reference* (no argument) — core API, schema system, error handling, decision framework, plus Kotlin/Swift client-codegen reference (auto-discovered by Claude Code)
+  - *Scaffold* — `/ts-procedures scaffold <type> <Name>` generates procedures, streams, and HTTP setups with correct patterns
+  - *Review* — `/ts-procedures review <path>` checks code against a 60+ item checklist
 - **Architecture agent** — `ts-procedures-architect` helps plan procedure structure, schema design, and HTTP implementation choices
 
 ## CLI Options
@@ -54,8 +55,6 @@ The `.claude/` files are auto-generated and regenerated on `npm install`. You ca
 ```gitignore
 # Auto-generated AI agent rules (regenerated on npm install)
 .claude/skills/ts-procedures/
-.claude/skills/ts-procedures-scaffold/
-.claude/skills/ts-procedures-review/
 .claude/agents/ts-procedures-*.md
 ```
 

package/docs/client-and-codegen.md

@@ -4,6 +4,10 @@
 
 ts-procedures can generate type-safe client SDKs directly from your server's `DocRegistry` output. Generated files include TypeScript types and callable functions for every registered procedure, organized by scope — no manual type duplication required.
 
+## Setup / prerequisites
+
+> **ESM only.** ts-procedures and its generated output are ESM-only — a `tsconfig.json` with `"module": "commonjs"` fails immediately. In your consuming project set `"type": "module"` in `package.json`, and in `tsconfig.json` use `"module": "ESNext"` with `"moduleResolution": "Bundler"` (or `"NodeNext"`). Run scripts with [`tsx`](https://github.com/privatenumber/tsx) during development (e.g. `tsx src/index.ts`).
+
 ## Quick Start
 
 **Step 1 — Serve your docs endpoint** (see [DocRegistry](./http-integrations.md#docregistry--composing-docs-from-multiple-builders) for setup):
@@ -35,7 +39,11 @@ const api = createApiClient({
     },
   },
 })
+```
 
+> **Note:** `basePath` must be the **origin only** (e.g. `http://localhost:3000`), not `http://localhost:3000/api`. Generated client paths already include the server's `pathPrefix` (e.g. `/api/...`), so putting the prefix in `basePath` too doubles it up to `/api/api/...`.
+
+```typescript
 try {
   const user = await api.users.GetUser({ pathParams: { id: '123' } })
 } catch (err) {

package/docs/core.md

@@ -214,6 +214,8 @@ schema: { params: Type.Object({ title: Type.String() }) }
 
 TypeBox schemas are valid JSON Schema and work directly with AJV for runtime validation.
 
+> **Composing schemas:** the bundled typebox has no `Type.Composite`. Compose with a flat object spread instead — `Type.Object({ ...Base.properties, extra: Type.String() })` — which also keeps the emitted JSON Schema a single `object` rather than an `allOf`.
+
 ### Validation Behavior
 
 AJV is configured with:

package/docs/http-integrations.md

@@ -134,6 +134,10 @@ new HonoAppBuilder({
 
 For streaming procedures the taxonomy covers the pre-stream path only; mid-stream errors are handled via `stream.onMidStreamError`.
 
+> **Typed client classes — when you get them for free.** A taxonomy entry declared with just `{ class, statusCode }` is self-describing: its default body is `{ name, message }`, so codegen emits a typed client error class and registry entry automatically — `catch (e) { if (e instanceof ApiErrors.NotFound) ... }` works with zero extra ceremony. The framework can only do this when it knows the wire shape. Two cases where it can't, and the client falls back to the untyped `ClientHttpError` until you help it:
+> - **Custom `toResponse` without a `schema`.** Once you shape the body yourself, the framework won't guess it. Add an explicit `schema` matching your `toResponse` to restore the typed class.
+> - **Raw `ErrorDoc`s** added via `DocRegistry.documentError(...)` or a `config.errors` array (rather than a taxonomy). These carry no body contract — give them a `schema` to make them typed on the client.
+
 ### Imperative — the `onError` callback
 
 For apps that don't need typed client dispatch or declarative docs, configure `onError` directly and handle every error in one place:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-procedures",
-  "version": "8.2.0",
+  "version": "8.3.0",
   "description": "A TypeScript RPC framework that creates type-safe, schema-validated procedure calls with a single function definition. Define your procedures once and get full type inference, runtime validation, and framework integration hooks.",
   "main": "build/exports.js",
   "types": "build/exports.d.ts",

package/src/codegen/emit-errors.integration.test.ts

@@ -10,6 +10,11 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { execSync } from 'node:child_process'
 import { generateClient } from './index.js'
+import { emitErrorsFile } from './emit-errors.js'
+import {
+  defineErrorTaxonomy,
+  taxonomyToErrorDocs,
+} from '../implementations/http/error-taxonomy.js'
 import type { DocEnvelope } from '../implementations/types.js'
 
 describe('generated _errors.ts — runtime behavior', () => {
@@ -180,4 +185,25 @@ describe('generated _errors.ts — runtime behavior', () => {
       rmSync(outDir, { recursive: true, force: true })
     }
   }, 30000)
+
+  // ---------------------------------------------------------------------------
+  // Taxonomy-derived envelope: a class+statusCode-only entry must produce a
+  // typed client error class + registry entry (previously schema-less → skipped).
+  // ---------------------------------------------------------------------------
+  it('emits a typed class + registry entry for a class+statusCode-only taxonomy entry', async () => {
+    const taxonomy = defineErrorTaxonomy({
+      // Only { class, statusCode } — the common case. No schema, no toResponse.
+      AuthError: { class: class AuthError extends Error {}, statusCode: 401 },
+    })
+    const errorDocs = taxonomyToErrorDocs(taxonomy)
+
+    // The synthesized schema is what makes codegen emit a class for it.
+    const result = await emitErrorsFile(errorDocs)
+    expect(result).toBeDefined()
+    expect(result).toContain('export class AuthError')
+    expect(result).toContain('export const ErrorRegistry = {')
+    // Precise registry membership — `^\s*AuthError,$` avoids matching a
+    // substring like `MyAuthError,` or an occurrence in a comment.
+    expect(result).toMatch(/^\s*AuthError,$/m)
+  })
 })

package/src/implementations/http/error-taxonomy.test.ts

@@ -5,10 +5,14 @@ import {
   ProcedureYieldValidationError,
 } from '../../errors.js'
 import type { TProcedureRegistration } from '../../index.js'
+import * as AJV from 'ajv'
 import {
   defineErrorTaxonomy,
   resolveErrorResponse,
   defaultErrorTaxonomy,
+  taxonomyToErrorDocs,
+  defaultErrorSchema,
+  defaultErrorBody,
 } from './error-taxonomy.js'
 
 class UseCaseError extends Error {
@@ -436,3 +440,110 @@ describe('resolveErrorResponse', () => {
     expect(Object.keys(taxonomy)).toEqual(['B', 'A'])
   })
 })
+
+describe('taxonomyToErrorDocs', () => {
+  test('synthesizes a { name const, message } schema for class+statusCode-only entries', () => {
+    const taxonomy = defineErrorTaxonomy({
+      AuthError: { class: AuthError, statusCode: 401 },
+    })
+    const docs = taxonomyToErrorDocs(taxonomy)
+    const auth = docs.find((d) => d.name === 'AuthError')
+    expect(auth?.statusCode).toBe(401)
+    expect(auth?.schema).toEqual({
+      type: 'object',
+      properties: {
+        name: { type: 'string', const: 'AuthError' },
+        message: { type: 'string' },
+      },
+      required: ['name', 'message'],
+    })
+  })
+
+  test('does NOT synthesize a schema when a custom toResponse is present', () => {
+    const taxonomy = defineErrorTaxonomy({
+      UseCaseError: {
+        class: UseCaseError,
+        statusCode: 422,
+        toResponse: (err) => ({ name: 'UseCaseError', message: err.externalMsg }),
+      },
+    })
+    const docs = taxonomyToErrorDocs(taxonomy)
+    const useCase = docs.find((d) => d.name === 'UseCaseError')
+    expect(useCase?.schema).toBeUndefined()
+  })
+
+  test('preserves an explicit schema untouched', () => {
+    const explicitSchema = {
+      type: 'object',
+      properties: {
+        name: { type: 'string', const: 'UseCaseError' },
+        reason: { type: 'string' },
+      },
+      required: ['name', 'reason'],
+    }
+    const taxonomy = defineErrorTaxonomy({
+      UseCaseError: {
+        class: UseCaseError,
+        statusCode: 422,
+        schema: explicitSchema,
+      },
+    })
+    const docs = taxonomyToErrorDocs(taxonomy)
+    const useCase = docs.find((d) => d.name === 'UseCaseError')
+    expect(useCase?.schema).toBe(explicitSchema)
+  })
+})
+
+describe('defaultErrorSchema', () => {
+  test('synthesizes the { name, message } envelope for a bare entry', () => {
+    expect(defaultErrorSchema('AuthError', { class: AuthError, statusCode: 401 })).toEqual({
+      type: 'object',
+      properties: {
+        name: { type: 'string', const: 'AuthError' },
+        message: { type: 'string' },
+      },
+      required: ['name', 'message'],
+    })
+  })
+
+  test('returns undefined when a custom toResponse is present (shape unknown)', () => {
+    expect(
+      defaultErrorSchema('UseCaseError', {
+        class: UseCaseError,
+        statusCode: 422,
+        toResponse: () => ({ name: 'UseCaseError' }),
+      })
+    ).toBeUndefined()
+  })
+
+  test('returns the explicit schema when one is set', () => {
+    const schema = { type: 'object', properties: {} }
+    expect(
+      defaultErrorSchema('UseCaseError', { class: UseCaseError, statusCode: 422, schema })
+    ).toBe(schema)
+  })
+})
+
+// The synthesized schema and the runtime body share one source (defaultErrorBody).
+// This locks the invariant: whatever the default branch serializes must validate
+// against the schema codegen turns into the client error class. If either side
+// changes shape, this fails before consumers see a mismatch.
+describe('defaultErrorBody / defaultErrorSchema invariant', () => {
+  const ajv = new AJV.Ajv()
+
+  test('default body validates against the synthesized schema', () => {
+    const schema = defaultErrorSchema('AuthError', { class: AuthError, statusCode: 401 })
+    const validate = ajv.compile(schema!)
+
+    expect(validate(defaultErrorBody('AuthError', new Error('nope')))).toBe(true)
+    // A non-Error throw stringifies to a message — still valid.
+    expect(validate(defaultErrorBody('AuthError', 'plain string'))).toBe(true)
+    // Wrong discriminator name is rejected by the `const` — proves the schema
+    // actually constrains the wire shape the client dispatcher keys on.
+    expect(validate({ name: 'SomethingElse', message: 'x' })).toBe(false)
+  })
+
+  test('default body carries exactly the schema-described keys', () => {
+    expect(Object.keys(defaultErrorBody('X', new Error('m'))).sort()).toEqual(['message', 'name'])
+  })
+})

package/src/implementations/http/error-taxonomy.ts

@@ -204,9 +204,67 @@ export const PROCEDURE_REGISTRATION_ERROR_DOC: ErrorDoc = {
   },
 }
 
+/**
+ * The default response body for an entry without a custom `toResponse`:
+ * `{ name: <key>, message }`. This is the single source of truth for the default
+ * wire shape — `resolveErrorResponse` serializes with it and
+ * {@link defaultErrorSchema} describes it. Keeping both derived from one place
+ * means the synthesized schema can never drift from what the runtime emits.
+ */
+export function defaultErrorBody(key: string, err: unknown): { name: string; message: string } {
+  return {
+    name: key,
+    message: err instanceof Error ? err.message : String(err),
+  }
+}
+
+/**
+ * Synthesizes the response-body JSON Schema for a taxonomy entry that ships
+ * neither an explicit `schema` nor a custom `toResponse`.
+ *
+ * The common case for `defineErrorTaxonomy` is `{ class, statusCode }` only.
+ * For those entries the default `toResponse` (see `resolveErrorResponse`) emits
+ * exactly `{ name: <key>, message }`. Without a schema, `taxonomyToErrorDocs`
+ * produced a schema-less `ErrorDoc`, and codegen (`emit-errors.ts`) only emits a
+ * typed client error class for docs that carry a schema — so these entries
+ * silently fell back to the untyped `ClientHttpError`, while framework errors
+ * (which ship schemas) worked. That mismatch was confusing.
+ *
+ * By describing the default envelope here, the entry becomes self-describing and
+ * codegen emits a typed client error class with zero ceremony from the consumer.
+ *
+ * Rules:
+ * - Entry has an explicit `schema` → caller keeps it (this is not consulted).
+ * - Entry has a custom `toResponse` but no `schema` → returns `undefined`; the
+ *   body shape is unknown and we never guess it.
+ * - Entry has neither → returns the `{ name: const <key>, message }` schema that
+ *   describes {@link defaultErrorBody} — the exact body the runtime serializes.
+ *   (An invariant test keeps the two from drifting.)
+ */
+export function defaultErrorSchema(
+  key: string,
+  entry: ErrorTaxonomyEntry
+): Record<string, unknown> | undefined {
+  if (entry.schema) return entry.schema
+  if (entry.toResponse) return undefined
+  return {
+    type: 'object',
+    properties: {
+      name: { type: 'string', const: key },
+      message: { type: 'string' },
+    },
+    required: ['name', 'message'],
+  }
+}
+
 /**
  * Converts a taxonomy into {@link ErrorDoc} objects suitable for a DocEnvelope.
  *
+ * For entries that supply neither a `schema` nor a custom `toResponse`, the
+ * schema of the default `{ name, message }` envelope is synthesized (see
+ * {@link defaultErrorSchema}) so client codegen emits a typed error class for
+ * them too — matching the behavior of the schema-carrying framework defaults.
+ *
  * @internal Used by `DocRegistry` to merge taxonomy entries into the envelope.
  *   Consumers should pass their taxonomy directly to `new DocRegistry({ errors: taxonomy })`
  *   rather than calling this helper — the constructor handles the conversion.
@@ -216,7 +274,7 @@ export function taxonomyToErrorDocs(taxonomy: ErrorTaxonomy): ErrorDoc[] {
     name: key,
     statusCode: entry.statusCode,
     description: entry.description ?? '',
-    schema: entry.schema,
+    schema: defaultErrorSchema(key, entry),
   }))
 }
 
@@ -314,10 +372,7 @@ export function resolveErrorResponse(params: {
 
         const rawBody = entry.toResponse
           ? entry.toResponse(candidate as any, { key })
-          : {
-              name: key,
-              message: candidate instanceof Error ? candidate.message : String(candidate),
-            }
+          : defaultErrorBody(key, candidate)
         const body = ensureName(rawBody, key)
 
         return {

package/src/implementations/http/hono/handlers/http.test.ts

@@ -120,11 +120,79 @@ describe('installHttpRoute', () => {
         path: '/q', method: 'get',
         schema: { req: { query: Type.Any() }, res: { body: Type.Any() } },
       },
-        async (_ctx, { query }) => ({ body: query }))
+        async (_ctx, { query }) => query)
     }, { api: { queryParser } })
 
     const res = await app.request('/q?a=1&b=2')
     expect(queryParser).toHaveBeenCalledWith('a=1&b=2')
     expect(await res.json()).toEqual({ parsed: true, raw: 'a=1&b=2' })
   })
+
+  test('domain object with a top-level "body" field serializes whole (no res.headers)', async () => {
+    const { app } = buildApp((P) => {
+      P.CreateHttp('GetMessage', {
+        path: '/msg', method: 'get',
+        schema: { res: { body: Type.Object({ id: Type.String(), body: Type.String() }) } },
+      }, async () => ({ id: '1', body: 'hello text' }))
+    })
+    const res = await app.request('/msg')
+    expect(res.status).toBe(200)
+    expect(await res.json()).toEqual({ id: '1', body: 'hello text' })
+  })
+
+  test('envelope unwraps when res.headers is declared', async () => {
+    const { app } = buildApp((P) => {
+      P.CreateHttp('Enveloped', {
+        path: '/env', method: 'get',
+        schema: { res: { body: Type.Object({ ok: Type.Boolean() }), headers: Type.Object({}) } },
+      }, async () => ({ body: { ok: true }, headers: { 'x-trace': 'z' } }))
+    })
+    const res = await app.request('/env')
+    expect(res.status).toBe(200)
+    expect(res.headers.get('x-trace')).toBe('z')
+    expect(await res.json()).toEqual({ ok: true })
+  })
+
+  // Headers-only response shape — `res: { headers }` with no `res.body`. The
+  // handler returns `{ headers }` (no body key). The response must be bodyless,
+  // not an empty `application/json` payload that a client can't parse.
+  test('headers-only res schema returns a clean bodyless response', async () => {
+    const { app } = buildApp((P) => {
+      P.CreateHttp('HeadOnly', {
+        path: '/ho', method: 'get',
+        schema: { res: { headers: Type.Object({}) } },
+      }, async () => ({ headers: { 'x-trace': 'h1' } }))
+    })
+    const res = await app.request('/ho')
+    expect(res.status).toBe(200)
+    expect(res.headers.get('x-trace')).toBe('h1')
+    expect(res.headers.get('content-type')).toBeNull()
+    expect(await res.text()).toBe('')
+  })
+
+  // A void handler on a non-204 status sends a clean bodyless response rather
+  // than an empty `application/json` payload — uniform with the headers-only and
+  // 204 paths (an undefined body is always bodyless).
+  test('void handler on a 200 status returns a clean bodyless response', async () => {
+    const { app } = buildApp((P) => {
+      P.CreateHttp('Void', { path: '/void', method: 'get', schema: {} }, async () => undefined)
+    })
+    const res = await app.request('/void')
+    expect(res.status).toBe(200)
+    expect(res.headers.get('content-type')).toBeNull()
+    expect(await res.text()).toBe('')
+  })
+
+  test('res.headers declared with a 204 status applies headers and no body', async () => {
+    const { app } = buildApp((P) => {
+      P.CreateHttp('NoContent', {
+        path: '/nc', method: 'delete',
+        schema: { res: { headers: Type.Object({}) } },
+      }, async () => ({ headers: { 'x-trace': 'd1' } }))
+    })
+    const res = await app.request('/nc', { method: 'DELETE' })
+    expect(res.status).toBe(204)
+    expect(res.headers.get('x-trace')).toBe('d1')
+    expect(await res.text()).toBe('')
+  })
 })

package/src/implementations/http/hono/handlers/http.ts

@@ -103,32 +103,30 @@ export function installHttpRoute(params: {
 
       cfg.api?.onSuccess?.(procedure, c)
 
-      // 204 No Content — no body, just optional headers
-      if (successStatus === 204) {
-        if (result && typeof result === 'object' && 'headers' in result && (result as any).headers) {
-          for (const [k, v] of Object.entries((result as any).headers as Record<string, string>)) {
-            c.header(k, v)
-          }
-        }
-        return c.body(null, 204)
+      // The `{ body, headers }` envelope is OPT-IN via `schema.res.headers`: when
+      // the route declares response headers, the handler returns `{ body, headers }`;
+      // otherwise its return value IS the body. Gating on the schema (rather than
+      // duck-typing the result for a `body`/`headers` key) lets a domain object
+      // safely carry its own `body`/`headers` field without being unwrapped.
+      // Normalize both shapes to a single `{ body, headers }` so the response
+      // decision below is uniform for every legal return shape.
+      const hasResHeaders = procedure.config.schema?.res?.headers != null
+      const { body, headers } = hasResHeaders
+        ? ((result ?? {}) as { body?: unknown; headers?: unknown })
+        : { body: result, headers: undefined }
+
+      if (headers && typeof headers === 'object') {
+        for (const [k, v] of Object.entries(headers as Record<string, string>)) c.header(k, v)
       }
 
-      let body: unknown = result
-      let headers: Record<string, string> | undefined
-
-      if (result && typeof result === 'object' && 'body' in result && 'headers' in result) {
-        body = (result as any).body
-        headers = (result as any).headers as Record<string, string>
-      } else if (result && typeof result === 'object' && 'headers' in result && !('body' in result)) {
-        for (const [k, v] of Object.entries((result as any).headers as Record<string, string>)) {
-          c.header(k, v)
-        }
+      // No body to send — a 204 status, or an `undefined` return (a `void`
+      // handler, or a headers-only `res: { headers }` envelope). Emit a clean
+      // bodyless response instead of `c.json(undefined)`, which would send an
+      // empty, unparseable body under an `application/json` content-type.
+      if (successStatus === 204 || body === undefined) {
         return c.body(null, successStatus as any)
-      } else if (result && typeof result === 'object' && 'body' in result && !('headers' in result)) {
-        body = (result as any).body
       }
 
-      if (headers) for (const [k, v] of Object.entries(headers)) c.header(k, v)
       return c.json(body, successStatus as any)
     } catch (error) {
       return dispatchPreStreamError({

package/agent_config/claude-code/skills/ts-procedures-kotlin/SKILL.md

@@ -1,106 +0,0 @@
----
-name: ts-procedures-kotlin
-description: "Kotlin client codegen for ts-procedures — generate types-only Kotlin source from a ts-procedures DocEnvelope for Android/JVM consumers. Use when the user mentions Kotlin, Android, mobile clients, kotlinx-serialization, or asks how to generate non-TypeScript types from a ts-procedures server."
-user-invocable: false
----
-
-# ts-procedures — Kotlin Client Codegen
-
-You are assisting a developer who needs to generate Kotlin types from a `ts-procedures` server's `DocEnvelope`. The Kotlin target is **types-only** — no runtime, no adapter, no error registry. Mobile/Android consumers own the HTTP layer.
-
-## When this skill applies
-
-- The user mentions Kotlin, Android, kotlinx-serialization, mobile client, or `--target kotlin`.
-- The user wants to share API types between a `ts-procedures` server and a Kotlin/JVM consumer.
-- The user is debugging Kotlin codegen output, Gradle setup, or contextual serializer registration.
-
-If the user is generating a **TypeScript** client, redirect them to the main `ts-procedures` skill. For **Swift / iOS / macOS / Apple-platform** consumers, redirect to `ts-procedures-swift`.
-
-## 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
-```
-
-One `.kt` file per scope. Types accessed as `Users.GetUser.Response`, `Users.GetUser.Body.Address` (nested classes via `inlineTypes: true`), `Users.GetUser.Errors.NotFound`.
-
-## CLI flags (Kotlin-specific)
-
-| Flag | Default | Purpose |
-|---|---|---|
-| `--target kotlin` | `ts` | Switch to the Kotlin codegen path |
-| `--kotlin-package <com.example.api>` | required | Sets the `package` declaration on every emitted `.kt` file |
-| `--kotlin-serializer <kotlinx\|none>` | `kotlinx` | `kotlinx` emits `@Serializable`; `none` emits plain data classes for Moshi/Gson/hand-written serialization |
-| `--unsupported-unions <throw\|fallback>` | `throw` | **Currently a no-op for Kotlin** — ajsc v7.2 silently emits an empty `data class` for untagged `oneOf` regardless. CLI warns when set |
-
-`--array-item-naming`, `--depluralize`, `--uncountable-words` also apply to the Kotlin target.
-
-## Output shape (what consumers see)
-
-```kotlin
-package com.example.api
-
-import kotlinx.serialization.Serializable
-import kotlinx.serialization.SerialName
-import kotlinx.serialization.Contextual
-import kotlinx.serialization.json.JsonClassDiscriminator
-
-object Users {
-    object GetUser {
-        const val method = "GET"
-        const val pathTemplate = "/users/{id}"
-        fun path(p: PathParams): String = "/users/${p.id}"
-
-        @Serializable data class PathParams(val id: String)
-
-        @Serializable
-        data class Response(
-            val id: String,
-            @SerialName("created-at") @Contextual val createdAt: java.time.Instant,
-            val address: Address,
-        ) {
-            @Serializable data class Address(val street: String, val city: String)
-        }
-
-        object Errors {
-            @Serializable
-            data class NotFound(val name: String = "NotFound", val message: String)
-        }
-    }
-}
-```
-
-For routes without path params, `path` is a `const val`, not a function.
-
-## Consumer-side setup the dev MUST do
-
-The generated code requires these on the Android/JVM side. **Don't let the user assume the codegen handles them.**
-
-1. **Gradle:** `kotlin("plugin.serialization")` plugin + `org.jetbrains.kotlinx:kotlinx-serialization-json` dependency. (`kotlinx-serialization-core` is a transitive dep; no need to declare it explicitly.)
-
-2. **Contextual serializers:** `format: date-time`/`uuid`/`uri`/`date`/`time` map to JVM stdlib types annotated with `@Contextual`. The consumer's `Json` configuration MUST register `contextual(java.time.Instant::class, ...)` etc., otherwise decoding fails. We don't ship the serializers — choice between ISO-8601 and epoch ms is application-specific.
-
-3. **Discriminated unions:** `@JsonClassDiscriminator` is read automatically by `kotlinx-serialization-json` — no extra config needed.
-
-4. **No runtime dispatch:** error types are emitted as nested data classes (`Users.GetUser.Errors.NotFound`), but there's no `instanceof`-style registry, no `dispatchTypedError`. Consumers catch HTTP failures themselves and inspect `body.name` (a regular `String` field, not a type-system discriminator) to decide which error data class to deserialize against. This is by design; don't suggest implementing it.
-
-The full setup guide lives at `docs/codegen-kotlin.md` in the `ts-procedures` repo.
-
-## Documented limitations to flag during reviews
-
-- **Untagged `oneOf` produces an empty `data class`.** Won't round-trip. Add a server-side discriminator, hand-write a `KSerializer`, or pre-process the envelope.
-- **Tuples > 3 elements throw** at codegen time. Refactor to a struct schema upstream.
-- **`additionalProperties: { type: T }` is silently dropped** with a KDoc note. Add a sibling `Map<String, T>` field by hand if your contract uses extra keys.
-- **Schema-level `examples` are not modeled.** They're documentation-only on the server side; consumers don't see them.
-
-## Anti-patterns
-
-- Suggesting the Kotlin target ships an HTTP adapter or error registry.
-- Recommending `--kotlin-serializer none` without noting the consumer is responsible for adapter setup.
-- Treating `--unsupported-unions fallback` as functional for Kotlin — it's a no-op (the CLI itself warns when set).
-- Saying KMP (Kotlin Multiplatform) is supported — JVM only for now.
-- Mixing `--target kotlin` flags into a TypeScript-target invocation; some flags are silently ignored, others (like `--kotlin-package`) are required only for kotlin.

package/agent_config/claude-code/skills/ts-procedures-review/SKILL.md

@@ -1,48 +0,0 @@
----
-name: ts-procedures-review
-description: "Review ts-procedures code for pattern adherence, schema correctness, error handling, and signal propagation."
-argument-hint: "<path>"
-allowed-tools: Read Grep Glob
-context: fork
-effort: high
----
-
-# Review ts-procedures Code
-
-Parse `$ARGUMENTS` as a file or directory path. If a directory, review all `.ts` and `.tsx` files within it.
-
-## Instructions
-
-1. Read the target file(s).
-2. Identify ts-procedures imports (`ts-procedures`, `ts-procedures/hono`, `ts-procedures/http`, `ts-procedures/http-docs`, `ts-procedures/http-errors`, `ts-procedures/client`, `ts-procedures/codegen`) to determine file types.
-3. Check each file against the categorized checklist in [checklist.md](checklist.md).
-4. For detailed code examples of each violation pattern, reference [anti-patterns.md](../ts-procedures/anti-patterns.md) — it shows 20 common mistakes with before/after code fixes and severity ratings.
-5. Output findings grouped by severity.
-
-## Output Format
-
-For each finding:
-
-```
-[SEVERITY] file:line — Violation
-  Problem: What's wrong
-  Fix: Concrete before/after code
-```
-
-Severity levels:
-- **CRITICAL** — Will cause bugs, silent failures, resource leaks, or runtime errors. Must fix.
-- **WARNING** — Anti-pattern that hurts maintainability or correctness. Should fix.
-- **SUGGESTION** — Improvement for readability, type safety, or DX. Nice to have.
-
-## Summary
-
-After individual findings, provide:
-- Total findings by severity
-- Overall assessment (healthy / needs attention / significant issues)
-- Top 3 priorities to address
-- If structural issues found, suggest `/ts-procedures:scaffold <type> <Name>` to generate correct implementations
-
-## Reference
-
-See [checklist.md](checklist.md) for the complete categorized checklist by file type.
-See [anti-patterns.md](../ts-procedures/anti-patterns.md) for detailed code examples of each violation.