ts-procedures 8.2.0 → 8.3.0

package/agent_config/bin/setup.mjs

@@ -92,7 +92,7 @@ function setupClaude({ dryRun, check } = {}) {
     // Mirror install-claude.mjs: copy every file under each source skill dir, plus the agent.
     const claudeFiles = [];
     const skillsSrc = join(AGENT_CONFIG_DIR, 'claude-code', 'skills');
-    for (const skill of ['ts-procedures', 'ts-procedures-review', 'ts-procedures-scaffold', 'ts-procedures-kotlin', 'ts-procedures-swift']) {
+    for (const skill of ['ts-procedures']) {
       const walk = (dir, prefix) => {
         for (const entry of readdirSync(dir)) {
           const full = join(dir, entry);
@@ -128,7 +128,7 @@ function setupClaude({ dryRun, check } = {}) {
     console.log(`    ${f}`);
   }
   console.log('');
-  console.log('  Skills:  ts-procedures, ts-procedures-scaffold, ts-procedures-review, ts-procedures-kotlin, ts-procedures-swift');
+  console.log('  Skills:  ts-procedures (use `/ts-procedures review <path>` and `/ts-procedures scaffold <type> <Name>`; Kotlin/Swift codegen reference included)');
   console.log('  Agent:   ts-procedures-architect (architecture planning)\n');
   return false;
 }

package/agent_config/claude-code/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "ts-procedures",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "AI coding assistant plugin for ts-procedures — a TypeScript RPC framework for type-safe, schema-validated procedure calls with automatic validation, streaming support, and HTTP framework integrations."
 }

package/agent_config/claude-code/agents/ts-procedures-architect.md

@@ -134,4 +134,4 @@ type AuthContext = { userId: string; requestId: string; db: Database }
 
 ## Next Steps
 
-After planning, use `/ts-procedures:scaffold <type> <Name>` to generate each procedure with correct patterns and tests.
+After planning, use `/ts-procedures scaffold <type> <Name>` to generate each procedure with correct patterns and tests.

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

@@ -1,13 +1,39 @@
 ---
 name: ts-procedures
-description: "TypeScript RPC framework reference for ts-procedures — schema validation, error handling, HTTP builders, streaming, and code generation. Use when writing, reviewing, or debugging procedures, configuring HTTP builders, or designing schemas."
-user-invocable: false
+description: "TypeScript RPC framework reference for ts-procedures — type-safe schema-validated procedures (TypeBox, AJV), error classes and taxonomy, HonoAppBuilder, SSE/streaming, and client code generation for TypeScript, Kotlin (Android/JVM, kotlinx-serialization), and Swift (iOS/macOS/Apple, Codable). Use when writing, reviewing, scaffolding, or debugging ts-procedures procedures, HTTP builders, schemas, error handling, or generated clients."
+argument-hint: "[review <path> | scaffold <type> <Name>]"
+allowed-tools: Read, Write, Edit, Grep, Glob
 ---
 
+<!-- MAINTAINER NOTES (not part of the skill content):
+     1. Write/Edit are granted skill-wide because Scaffold Mode generates files. Claude Code
+        cannot scope allowed-tools per-mode within a single SKILL.md, so the write capability is
+        kept dormant by the File-write guard below — writes happen only when the literal first
+        word of $ARGUMENTS is `scaffold`. If the modes are ever split back into separate skills,
+        re-scope tools per skill accordingly.
+     2. The former standalone `ts-procedures-review` skill ran with `context: fork` and
+        `effort: high`. Those are skill-level settings that cannot be scoped to one mode, so
+        Review Mode now runs inline in the main context instead of a forked one. Review Mode
+        recovers isolation by suggesting a subagent for large reviews (see that section). -->
+
 # ts-procedures Framework Reference
 
 You are assisting a developer using **ts-procedures**, a TypeScript RPC framework that creates type-safe, schema-validated procedure calls with a single function definition. Always follow these rules when writing or reviewing code.
 
+> **ESM-only.** All ts-procedures packages ship ESM only — the consuming project needs `"type": "module"` in `package.json` and `moduleResolution` set to `"Bundler"` or `"NodeNext"` in `tsconfig.json`. (The full setup guide lives in the package `docs/`.)
+
+## Modes
+
+This skill has three modes, selected by the **first whitespace-delimited word of `$ARGUMENTS`**:
+
+| First word of `$ARGUMENTS` | Mode | What happens |
+|----------------------------|------|--------------|
+| *(empty)* | **Reference** | The framework knowledge below auto-loads. Read [patterns.md](patterns.md), [anti-patterns.md](anti-patterns.md), or [api-reference.md](api-reference.md) as needed. Kotlin/Swift client codegen have dedicated reference sections lower down. |
+| `review` | **Review Mode** | Audit the file/dir at the path argument against [checklist.md](checklist.md). Read-only. See the **Review Mode** section below. |
+| `scaffold` | **Scaffold Mode** | Generate implementation + test files from [templates/](templates). **Writes files.** See the **Scaffold Mode** section below. |
+
+**File-write guard.** This skill writes files in **Scaffold Mode only**. Scaffold Mode is entered **if and only if** the literal first word of `$ARGUMENTS` is `scaffold`. In every other case — empty `$ARGUMENTS` (reference), `review`, or any reference/codegen question (including Kotlin and Swift) — operate strictly read-only: use Read/Grep/Glob, never Write or Edit. Do **not** infer write permission from the surrounding task ("the user is obviously building an API, so I'll scaffold") — during an active build that reasoning is always pre-satisfied and is exactly the trap to avoid. Only the literal `scaffold` first word unlocks file writes. If you are unsure which mode you are in, you are not in Scaffold Mode.
+
 ## What Are You Trying to Do?
 
 Load the right reference for your task:
@@ -15,8 +41,8 @@ Load the right reference for your task:
 - **Writing new procedures or HTTP routes?** Read [patterns.md](patterns.md) — prescribed code examples for every procedure type and HTTP integration
 - **Reviewing or debugging existing code?** Read [anti-patterns.md](anti-patterns.md) — 20 common mistakes with before/after fixes and severity ratings
 - **Need exact API signatures or type definitions?** Read [api-reference.md](api-reference.md) — complete API documentation with type signatures for every export
-- **Generating a Kotlin client for Android/JVM consumers?** Use the separate `ts-procedures-kotlin` skill — it covers `--target kotlin` end-to-end and won't load unless the user mentions Kotlin/Android.
-- **Generating a Swift client for iOS/macOS/Apple-platform consumers?** Use the separate `ts-procedures-swift` skill — it covers `--target swift` end-to-end and won't load unless the user mentions Swift/iOS/Apple platforms.
+- **Generating a Kotlin client for Android/JVM consumers?** See the **Kotlin Client Codegen** section below — it covers `--target kotlin` end-to-end.
+- **Generating a Swift client for iOS/macOS/Apple-platform consumers?** See the **Swift Client Codegen** section below — it covers `--target swift` end-to-end.
 
 ## Core Flow
 
@@ -70,6 +96,8 @@ Uses **TypeBox** for schema definitions (`import { Type } from 'typebox'`):
 
 AJV config: `allErrors: true`, `coerceTypes: true`, `removeAdditional: true`
 
+> **Composing schemas:** the bundled TypeBox does **not** export `Type.Composite`. Extend a schema with a flat property spread — `Type.Object({ ...Base.properties, name: Type.String() })` — which also keeps the generated JSON Schema a single `object` instead of an `allOf`.
+
 ## Error Classes
 
 | Error Class | Trigger | Key Properties |
@@ -97,7 +125,7 @@ const appErrors = defineErrorTaxonomy({
 new HonoAppBuilder({ errors: appErrors, unknownError: { toResponse: () => ({ error: '...' }) } })
 ```
 
-Per-route narrowing: `APIConfig<keyof typeof appErrors & string>` / `RPCConfig<keyof typeof appErrors & string>` with a `errors: [...]` array on the config. Generated `_errors.ts` emits runtime classes — clients catch with `instanceof ${Service}Errors.${Name}` when using `create${Service}Client`.
+Per-route narrowing: add an `errors: [...]` array on the config. For `RPCConfig` routes narrow the factory via `RPCConfig<keyof typeof appErrors & string>`. For `CreateHttp` routes do **not** pass an explicit generic (that binds `TName` and breaks `schema.req`/`schema.res` inference) — instead attach `satisfies (keyof typeof appErrors & string)[]` to the `errors` array. Generated `_errors.ts` emits runtime classes — clients catch with `instanceof ${Service}Errors.${Name}` when using `create${Service}Client`.
 
 Full contract: `docs/http-integrations.md § Error Handling` (canonical) and `api-reference.md § Error Taxonomy API`.
 
@@ -173,8 +201,327 @@ The npm package ships user-facing documentation with narrative explanations and
 | `docs/http-integrations.md` | Hono unified builder (`HonoAppBuilder` — RPC + HTTP + streaming with stratified config), **error taxonomy (canonical)**, DocRegistry (unified constructor, `.documentError()`) |
 | `docs/client-and-codegen.md` | Client code generation, `createApiClient`/`createClient`, typed error dispatch, per-route `Errors` unions, per-call options, client-level defaults, typed RequestMeta augmentation, CLI options |
 | `docs/client-error-handling.md` | **Canonical guide** for 7.0+ client error surface: normalized error classes, `.safe()` Result API, `ClientErrorMap` augmentation, custom `ErrorClassifier`, migration from `ClientRequestError`. |
+| `docs/codegen-kotlin.md` | Kotlin target consumer setup (Gradle deps, contextual serializers, sealed interfaces) |
+| `docs/codegen-swift.md` | Swift target consumer setup (SPM/Xcode integration, JSONDecoder config, discriminated unions, error dispatch patterns) |
 | `CHANGELOG.md` | Release notes — see `[7.0.0]` for the safe-result API, new error classes, and `ClientRequestError` → `ClientHttpError` rename. See `[6.0.0]` for the peer error-handling model (taxonomy + `onError` + `onRequestError`). |
 
 ## Workflow
 
-After planning with the **ts-procedures-architect** agent, use `/ts-procedures:scaffold <type> <Name>` to generate implementations. Use `/ts-procedures:review <path>` to validate existing code.
+After planning with the **ts-procedures-architect** agent, use `/ts-procedures scaffold <type> <Name>` to generate implementations. Use `/ts-procedures review <path>` to validate existing code.
+
+---
+
+## Review Mode
+
+*Entered when the first word of `$ARGUMENTS` is `review`. Read-only — never Write or Edit in this mode. Run thoroughly and at high effort.*
+
+> **Isolation note:** as a standalone skill this review ran in a forked context. Folded into one skill it runs inline. For a large review where you want isolation (so the audit doesn't pollute the main conversation), dispatch this review to a subagent and relay its findings.
+
+Parse the remainder of `$ARGUMENTS` (everything after `review`) 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](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](anti-patterns.md) for detailed code examples of each violation.
+
+---
+
+## Scaffold Mode
+
+*Entered when the first word of `$ARGUMENTS` is `scaffold`. This is the only mode that writes files (see the File-write guard above).*
+
+Parse `$ARGUMENTS` as `scaffold <type> <Name>`. The first word (`scaffold`) is the mode selector; `<type>` is the second word, `<Name>` is the third.
+
+If `<type>` or `<Name>` is missing, ask the user for them before writing anything.
+
+### Instructions
+
+1. Validate `<type>` is a recognized type (see table below). Case-insensitive. **If it is not an exact match for one of the valid types, do not improvise or guess a template — list the valid types and ask the user to pick one.**
+2. Validate `<Name>` is PascalCase (e.g., `UserProfile`).
+3. Derive placeholder variants from the provided PascalCase Name:
+   - `{{Name}}` — PascalCase as given (e.g., `UserProfile`)
+   - `{{name}}` — camelCase (e.g., `userProfile`)
+   - `{{kebab}}` — kebab-case (e.g., `user-profile`)
+4. Read the template file from `templates/<type>.md` (relative to this skill directory).
+5. Replace all `{{Name}}`, `{{name}}`, and `{{kebab}}` placeholders with the appropriate variants.
+6. Generate the implementation file(s) following the template exactly.
+7. Also generate a colocated test file following ts-procedures test conventions.
+
+### Valid Types
+
+| Type | Template | Files Generated |
+|------|----------|----------------|
+| `procedure` | `templates/procedure.md` | `{{Name}}.procedure.ts`, `{{Name}}.procedure.test.ts` |
+| `stream-procedure` | `templates/stream-procedure.md` | `{{Name}}.stream.ts`, `{{Name}}.stream.test.ts` |
+| `hono` | `templates/hono.md` | `{{Name}}.hono.ts`, `{{Name}}.hono.test.ts` |
+| `client` | `templates/client.md` | `{{Name}}.client.ts`, `{{Name}}.client.test.ts` |
+| `astro-catchall` | `templates/astro-catchall.md` | `src/pages/api/[...rest].ts` |
+
+### Rules
+
+- Use `ctx.error()` for ad-hoc business errors; for structured errors with status codes and typed client dispatch, throw custom error classes and register them via `defineErrorTaxonomy` in the builder's `errors` config (see the HTTP builder templates).
+- Never throw raw `Error` — either use `ctx.error()` or a typed class registered in the taxonomy.
+- `schema.params` is validated at runtime; `schema.returnType` is documentation only.
+- Pass `ctx.signal` to all downstream async calls.
+- Stream handlers always have `ctx.signal` (guaranteed `AbortSignal`).
+- Use TypeBox for schema definitions (`import { Type } from 'typebox'`).
+- AJV config: `allErrors: true`, `coerceTypes: true`, `removeAdditional: true`.
+- Test files use `describe`/`test` from vitest.
+
+### Workflow
+
+Use the **ts-procedures-architect** agent to plan your API structure first, then scaffold each procedure. After scaffolding, use `/ts-procedures review <path>` to validate the implementation.
+
+---
+
+## Kotlin Client Codegen
+
+*Reference section — read-only. The Kotlin target is **types-only**: no runtime, no adapter, no error registry. Mobile/Android consumers own the HTTP layer.*
+
+You are assisting a developer who needs to generate Kotlin types from a `ts-procedures` server's `DocEnvelope`.
+
+### When this section 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, use the main reference above. For **Swift / iOS / macOS / Apple-platform** consumers, see the **Swift Client Codegen** section below.
+
+### 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 (Kotlin)
+
+- 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.
+
+---
+
+## Swift Client Codegen
+
+*Reference section — read-only. The Swift target is **types-only**: no runtime, no adapter, no error registry. iOS / macOS / Apple-platform consumers own the HTTP layer.*
+
+You are assisting a developer who needs to generate Swift types from a `ts-procedures` server's `DocEnvelope`.
+
+### When this section applies
+
+- The user mentions Swift, iOS, macOS, watchOS, tvOS, visionOS, Apple platforms, `Codable`, `URLSession`, or `--target swift`.
+- The user wants to share API types between a `ts-procedures` server and a Swift consumer.
+- The user is debugging Swift codegen output, SPM/Xcode integration, `JSONDecoder` configuration, or `Codable` conformance issues.
+
+If the user is generating a **TypeScript** client, use the main reference above. For **Kotlin/Android** consumers, see the **Kotlin Client Codegen** section above.
+
+### Quickstart
+
+```bash
+npx ts-procedures-codegen \
+  --target swift \
+  --url https://api.example.com/_ts-procedures.json \
+  --out ./Sources/MyApp/Generated
+```
+
+One `.swift` file per scope. Types accessed as `Users.GetUser.Response`, `Users.GetUser.PathParams`, `Users.GetUser.Response.Address` (nested structs via `inlineTypes: true`), `Users.GetUser.Errors.NotFound`.
+
+**Note:** unlike the Kotlin target, no `--swift-package` flag exists or is required. Swift modules are defined by Xcode/SPM targets.
+
+### CLI flags (Swift-specific)
+
+| Flag | Default | Purpose |
+|---|---|---|
+| `--target swift` | `ts` | Switch to the Swift codegen path |
+| `--swift-serializer <codable\|none>` | `codable` | `codable` emits `: Codable` + `CodingKeys`; `none` emits plain structs (consumer handles serialization) |
+| `--swift-access-level <public\|internal>` | `public` | Threads through to ajsc's `accessLevel`; use `internal` when generated types shouldn't appear in module ABI |
+| `--unsupported-unions <throw\|fallback>` | `throw` | **Functional for Swift** (unlike Kotlin where it's a no-op) — `fallback` emits a self-contained `AnyCodable` helper for untagged `anyOf`/`oneOf` |
+
+`--array-item-naming`, `--depluralize`, `--uncountable-words` also apply to the Swift target.
+
+### Output shape (what consumers see)
+
+```swift
+import Foundation
+
+public enum Users {
+    public enum GetUser {
+        public static let method = "GET"
+        public static let pathTemplate = "/users/{id}"
+        public static func path(_ p: PathParams) -> String { return "/users/\(p.id)" }
+
+        public struct PathParams: Codable {
+            public let id: String
+        }
+
+        public struct Response: Codable {
+            public let id: String
+            public let createdAt: Date
+            public let address: Address
+
+            enum CodingKeys: String, CodingKey {
+                case id
+                case createdAt = "created-at"
+                case address
+            }
+
+            public struct Address: Codable {
+                public let street: String
+                public let city: String
+            }
+        }
+
+        public enum Errors {
+            public struct NotFound: Codable {
+                public let name: String
+                public let message: String
+            }
+        }
+    }
+}
+```
+
+For routes without path params, `path` is a `static let`, not a function. Namespaces are caseless `enum`s (the standard Swift idiom — uninstantiable, zero runtime cost).
+
+### Consumer-side setup the dev MUST do
+
+The generated code requires these on the Apple-platform side. **Don't let the user assume the codegen handles them.**
+
+1. **Drop generated files into your SPM target or Xcode source group.** Any target containing the generated dir picks them up — no special build config. SPM globs sources recursively; for Xcode, use **File → Add Files to "<TargetName>"…** and ensure target membership is checked.
+
+2. **Configure `JSONDecoder.dateDecodingStrategy = .iso8601`.** **Required** if the schema uses any `format: date-time` field (which become `Foundation.Date`). Without this, decoding fails with `DecodingError.typeMismatch`. Symmetric: set `JSONEncoder.dateEncodingStrategy = .iso8601` for request bodies.
+
+3. **HTTP transport is the consumer's choice.** `URLSession` (with `async/await`) is the default recommendation — it's built-in and works on all Apple platforms with no dependencies. Alamofire / other libraries are fine but never required.
+
+4. **No runtime dispatch.** Error types are emitted as nested structs (`Users.GetUser.Errors.NotFound`), but there's no registry, no `instanceof`-style lookup, no `dispatchTypedError`. Consumers catch HTTP failures themselves and dispatch on status code or `body.name` (a regular `String` field, not a type-system discriminator) to decide which error struct to decode against. To make error structs throwable, declare a one-line `extension X.Errors.NotFound: Error {}` in user code (keep it out of the generated file so re-runs don't clobber it). This is by design; don't suggest implementing a registry.
+
+The full setup guide lives at `docs/codegen-swift.md` in the `ts-procedures` repo.
+
+### Documented limitations to flag during reviews
+
+- **`format: date` and `format: time` map to `String`.** Foundation has no native date-only or time-only type. Parse with `DateFormatter` if a typed value is needed.
+- **`type: integer` maps to `Int64`** (not `Int`). 32-bit Apple platforms exist; `Int64` guarantees range parity.
+- **`type: number` maps to `Double`.** For monetary values, convert to `Decimal` at the parse boundary.
+- **Heterogeneous tuples throw under `Codable`.** Swift tuples aren't `Codable`. Schemas with positional-tuple `items: [...]` arrays throw at codegen time. Refactor to a struct schema upstream.
+- **`additionalProperties: { type: T }` is silently dropped** with a doc-comment. Add a sibling `[String: T]` field by hand if your contract uses extra keys.
+- **`not` and `patternProperties` throw at codegen time.** Simplify the schema upstream.
+- **Untagged `oneOf` throws by default.** Add a discriminator, or pass `--unsupported-unions fallback` to emit `AnyCodable`-typed values (loses static typing).
+
+### Anti-patterns (Swift)
+
+- **Suggesting the Swift target ships a networking layer or HTTP adapter.** It does not — consumers own `URLSession`/etc. entirely.
+- **Recommending Alamofire as required.** `URLSession` + `async/await` is fine and ships with the OS. Alamofire is a personal-preference choice, not a dependency of the generated code.
+- **Conflating `--swift-serializer none` with "no setup needed".** `none` removes `Codable` conformance and `CodingKeys` — the consumer then needs their own serialization plan (hand-rolled, SwiftyJSON, etc.). It's strictly *more* setup, not less.
+- **Treating `--unsupported-unions fallback` as a no-op for Swift.** Unlike Kotlin (where it's silently dropped), the Swift target actually emits an `AnyCodable` helper that round-trips correctly. Use it when needed.
+- **Suggesting backwards compatibility with Swift 4 / pre-async-await.** Assume Swift 5.5+ (the async/await era). Sample dispatch code in docs uses `async throws`.
+- **Suggesting the codegen emits `: Error` conformance on error structs.** It doesn't (`Codable` only) — consumers add a one-line extension. Don't ask for this to be added to the codegen; it would force users into a particular error model.
+- **Mixing `--target swift` flags into a TypeScript-target invocation.** The flags are silently ignored; no harm, but the user is probably running the wrong target.

package/agent_config/claude-code/skills/ts-procedures/api-reference.md

@@ -222,7 +222,9 @@ function CreateHttp<
 
 ### Return Shape
 
-- **No `schema.res.headers`:** handler returns body bare (`T`).
+The `{ body, headers }` envelope is **opt-in**, gated entirely on `schema.res.headers`. The framework never duck-types the return value for a `body` key, so a domain model may safely carry its own `body` / `headers` fields.
+
+- **No `schema.res.headers`:** handler returns the body bare (`T`) — serialized verbatim.
 - **`schema.res.headers` declared:** handler returns `{ body: B, headers: H }`.
 
 ### Throws
@@ -1222,7 +1224,7 @@ const adapter = createFetchAdapter({ fetch: customFetch })
 
 ## generateClient(options)
 
-> For **Kotlin** client codegen (Android/JVM, types-only output), see the dedicated `ts-procedures-kotlin` skill. For **Swift** client codegen (iOS/macOS/Apple platforms, types-only output), see the dedicated `ts-procedures-swift` skill. The reference below covers TypeScript codegen only.
+> For **Kotlin** client codegen (Android/JVM, types-only output), see the *Kotlin Client Codegen* section in `SKILL.md`. For **Swift** client codegen (iOS/macOS/Apple platforms, types-only output), see the *Swift Client Codegen* section in `SKILL.md`. The reference below covers TypeScript codegen only.
 
 Build-time CLI and programmatic API for generating typed client files from a `DocEnvelope`.
 

package/agent_config/claude-code/skills/ts-procedures/patterns.md

@@ -65,6 +65,22 @@ const { GetUser } = Create(
 
 ---
 
+## Composing / Extending Schemas
+
+The TypeBox build bundled with ts-procedures does **not** export `Type.Composite`. Compose schemas with a flat object spread of the source `.properties` instead. This also keeps the generated JSON Schema a single `object` rather than an `allOf` (which codegen and AJV handle more cleanly).
+
+```typescript
+// DON'T: Type.Composite is not available in the bundled TypeBox
+// const User = Type.Composite([Base, Type.Object({ name: Type.String() })])
+
+// DO: flat spread of the base schema's properties
+const Base = Type.Object({ id: Type.String() })
+const User = Type.Object({ ...Base.properties, name: Type.String() })
+// User → a single { type: 'object', properties: { id, name } } JSON Schema
+```
+
+---
+
 ## Error Handling in Handlers
 
 Use `ctx.error()` for business logic errors. Never throw raw Error instances.
@@ -160,22 +176,28 @@ Key rules:
 - The core wraps any non-`ProcedureError` thrown from a handler into a `ProcedureError` with `.cause` set. The resolver unwraps this automatically so your taxonomy sees the real class.
 - Two peer modes: declarative (`errors` + `unknownError`) or imperative (`onError`). Both are first-class. When neither is configured, the builder falls through to a hard default (`{ error: message }`, 500).
 - `onCatch`'s `raw` is the framework request object (Hono `Context`) typed as `unknown` — cast at the use site.
+- **Typed client classes are automatic for `{ class, statusCode }`-only entries** (their default `{ name, message }` body is self-describing). You only need to add an explicit `schema` when you (a) supply a custom `toResponse` — the framework won't guess the shape — or (b) document a raw `ErrorDoc` (via `documentError(...)` / a `config.errors` array). Without a schema those fall back to the untyped `ClientHttpError` on the client.
 
 ### Per-route error declaration (typed)
 
-Declare which errors each procedure may emit via the `errors` field on `CreateHttp` / `Create` config. These populate the DocEnvelope per-route so generated clients can type `catch` blocks precisely. For compile-time typo protection, pass the taxonomy key type as the `TErrorKey` generic on `CreateHttp`.
+Declare which errors each procedure may emit via the `errors` field on `CreateHttp` / `Create` config. These populate the DocEnvelope per-route so generated clients can type `catch` blocks precisely. For compile-time typo protection, attach a `satisfies` clause to the `errors` array rather than supplying an explicit generic.
+
+> Do **not** write `CreateHttp<keyof typeof appErrors & string>(...)`. `CreateHttp` is generic over `<TName, TReq, TRes, TErrorKey>` (see api-reference.md and `TCreateHttpConfig`), so a single explicit type argument binds `TName` and breaks inference of the `schema.req` / `schema.res` channels. Let all four type parameters infer, and use `satisfies` to keep the `errors` keys typo-safe.
 
 ```typescript
 import { appErrors } from './errors/taxonomy'
 
 const API = Procedures<Ctx>()
 
-// CreateHttp accepts TErrorKey as a generic for compile-time protection
-API.CreateHttp<keyof typeof appErrors & string>('GetUser', {
+API.CreateHttp('GetUser', {
   path: '/users/:id',
   method: 'get',
-  errors: ['UseCaseError', 'AuthError'],  // typed against taxonomy keys; typos are TS errors
-  schema: { req: { /* ... */ } },
+  // typed against taxonomy keys; typos are TS errors — without binding TName/TReq/TRes
+  errors: ['UseCaseError', 'AuthError'] satisfies (keyof typeof appErrors & string)[],
+  schema: {
+    req: { /* ... */ },
+    res: { /* ... */ },
+  },
 }, async (ctx, params) => { /* ... */ })
 ```
 
@@ -669,7 +691,9 @@ API.CreateHttp('UpdateUserField', {
 
 ## Response Headers (v8 `CreateHttp`)
 
-When `schema.res.headers` is declared, the handler must return `{ body, headers }` instead of the body bare. The client surfaces initial response headers on `TypedStream.headers` for streaming routes.
+The `{ body, headers }` envelope is strictly **opt-in**. By default the handler's return value is serialized verbatim as the response body — the framework does **not** duck-type the result looking for a `body` key. The envelope is only expected when `schema.res.headers` is declared; in that case (and only then) the handler must return `{ body, headers }` instead of the body bare. The client surfaces initial response headers on `TypedStream.headers` for streaming routes.
+
+> Because the envelope is opt-in, a domain model may safely have its own `body` or `headers` field — without `schema.res.headers` declared, `{ id, body: '...' }` is serialized as-is, never reinterpreted as an envelope.
 
 ```typescript
 API.CreateHttp('DownloadReport', {

package/agent_config/copilot/copilot-instructions.md

@@ -51,7 +51,7 @@ import type { DocEnvelope, HeaderDoc, ErrorDoc } from 'ts-procedures/http-docs'
 
 4. **Stream handlers always have ctx.signal (guaranteed AbortSignal).** Standard handlers get it when HTTP implementations provide it. Check `signal.reason === 'stream-completed'` to distinguish normal completion from client disconnect.
 
-5. **Use TypeBox for schemas** (`import { Type } from 'typebox'`). Plain JSON Schema objects are not recognized. AJV config: `allErrors: true`, `coerceTypes: true`, `removeAdditional: true`.
+5. **Use TypeBox for schemas** (`import { Type } from 'typebox'`). Plain JSON Schema objects are not recognized. AJV config: `allErrors: true`, `coerceTypes: true`, `removeAdditional: true`. The bundled TypeBox does **not** export `Type.Composite` — compose schemas with a flat property spread (`Type.Object({ ...Base.properties, name: Type.String() })`), which also keeps the generated JSON Schema a single `object` instead of an `allOf`.
 
 6. **One factory per access level.** Separate `Procedures()` factories for public, authenticated, admin contexts.
 
@@ -237,16 +237,18 @@ Handlers throw the error classes directly — the builder auto-serializes. `onEr
 
 ### Per-route errors (typed)
 
-`APIConfig` and `RPCConfig` are generic over `TErrorKey extends string = string`. Narrow to your taxonomy for compile-time typo protection and route-level error doc entries:
+Declare a route's errors via the `errors` field on the `CreateHttp` config. For compile-time typo protection, attach a `satisfies` clause to the array — do NOT pass an explicit generic. `CreateHttp` is generic over `<TName, TReq, TRes, TErrorKey>`, so a single type argument binds `TName` and breaks `schema.req` / `schema.res` inference:
 
 ```typescript
-import { APIConfig } from 'ts-procedures/http'
 import { DocRegistry } from 'ts-procedures/http-docs'
 
-type MyAPIConfig = APIConfig<keyof typeof appErrors & string>
-const API = Procedures<Ctx, MyAPIConfig>()
+const API = Procedures<Ctx>()
 
-API.Create('GetUser', { path: '/users/:id', method: 'get', errors: ['UseCaseError'], /* ... */ }, ...)
+API.CreateHttp('GetUser', {
+  path: '/users/:id', method: 'get',
+  errors: ['UseCaseError'] satisfies (keyof typeof appErrors & string)[],
+  schema: { req: { pathParams: Type.Object({ id: Type.String() }) } },
+}, async (ctx, { pathParams }) => fetchUser(pathParams.id))
 
 // Seed envelope errors from the taxonomy + framework defaults in one call
 const envelope = new DocRegistry({ errors: appErrors, basePath: '/api' }).from(apiApp).toJSON()
@@ -272,6 +274,8 @@ try {
 }
 ```
 
+Typed classes are generated automatically for taxonomy entries declared with just `{ class, statusCode }` (their default `{ name, message }` body is self-describing). Add an explicit `schema` only when you give an entry a custom `toResponse` (shape can't be inferred) or document a raw `ErrorDoc` (via `documentError(...)` / a `config.errors` array) — without a schema those dispatch as the untyped `ClientHttpError`.
+
 Per-route error unions: routes with `errors: [...]` get an `Errors` type in their namespace (e.g. `Users.GetUser.Errors = ApiErrors.UseCaseError | ApiErrors.AuthError`).
 
 - Generated client error handling: catch the framework classes (`ClientHttpError`, `ClientNetworkError`, `ClientTimeoutError`, `ClientAbortError`), not raw `DOMException`/`TypeError` — the framework normalizes platform errors at the `executeCall` boundary, so raw platform errors no longer reach `catch` blocks after 7.0.0 (original is on `error.cause`). Use the `.safe()` sibling on RPC/API callables for an exhaustive `Result<T, E>` switch (`ok`, `typed`, `http`, `network`, `timeout`, `aborted`, `parse`, `usage`, `unknown`). Streams keep the throwing form — no `.safe()`.

package/agent_config/cursor/cursorrules

@@ -51,7 +51,7 @@ import type { DocEnvelope, HeaderDoc, ErrorDoc } from 'ts-procedures/http-docs'
 
 4. **Stream handlers always have ctx.signal (guaranteed AbortSignal).** Standard handlers get it when HTTP implementations provide it. Check `signal.reason === 'stream-completed'` to distinguish normal completion from client disconnect.
 
-5. **Use TypeBox for schemas** (`import { Type } from 'typebox'`). Plain JSON Schema objects are not recognized. AJV config: `allErrors: true`, `coerceTypes: true`, `removeAdditional: true`.
+5. **Use TypeBox for schemas** (`import { Type } from 'typebox'`). Plain JSON Schema objects are not recognized. AJV config: `allErrors: true`, `coerceTypes: true`, `removeAdditional: true`. The bundled TypeBox does **not** export `Type.Composite` — compose schemas with a flat property spread (`Type.Object({ ...Base.properties, name: Type.String() })`), which also keeps the generated JSON Schema a single `object` instead of an `allOf`.
 
 6. **One factory per access level.** Separate `Procedures()` factories for public, authenticated, admin contexts.
 
@@ -237,16 +237,18 @@ Handlers throw the error classes directly — the builder auto-serializes. `onEr
 
 ### Per-route errors (typed)
 
-`APIConfig` and `RPCConfig` are generic over `TErrorKey extends string = string`. Narrow to your taxonomy for compile-time typo protection and route-level error doc entries:
+Declare a route's errors via the `errors` field on the `CreateHttp` config. For compile-time typo protection, attach a `satisfies` clause to the array — do NOT pass an explicit generic. `CreateHttp` is generic over `<TName, TReq, TRes, TErrorKey>`, so a single type argument binds `TName` and breaks `schema.req` / `schema.res` inference:
 
 ```typescript
-import { APIConfig } from 'ts-procedures/http'
 import { DocRegistry } from 'ts-procedures/http-docs'
 
-type MyAPIConfig = APIConfig<keyof typeof appErrors & string>
-const API = Procedures<Ctx, MyAPIConfig>()
+const API = Procedures<Ctx>()
 
-API.Create('GetUser', { path: '/users/:id', method: 'get', errors: ['UseCaseError'], /* ... */ }, ...)
+API.CreateHttp('GetUser', {
+  path: '/users/:id', method: 'get',
+  errors: ['UseCaseError'] satisfies (keyof typeof appErrors & string)[],
+  schema: { req: { pathParams: Type.Object({ id: Type.String() }) } },
+}, async (ctx, { pathParams }) => fetchUser(pathParams.id))
 
 // Seed envelope errors from the taxonomy + framework defaults in one call
 const envelope = new DocRegistry({ errors: appErrors, basePath: '/api' }).from(apiApp).toJSON()
@@ -272,6 +274,8 @@ try {
 }
 ```
 
+Typed classes are generated automatically for taxonomy entries declared with just `{ class, statusCode }` (their default `{ name, message }` body is self-describing). Add an explicit `schema` only when you give an entry a custom `toResponse` (shape can't be inferred) or document a raw `ErrorDoc` (via `documentError(...)` / a `config.errors` array) — without a schema those dispatch as the untyped `ClientHttpError`.
+
 Per-route error unions: routes with `errors: [...]` get an `Errors` type in their namespace (e.g. `Users.GetUser.Errors = ApiErrors.UseCaseError | ApiErrors.AuthError`).
 
 - Generated client error handling: catch the framework classes (`ClientHttpError`, `ClientNetworkError`, `ClientTimeoutError`, `ClientAbortError`), not raw `DOMException`/`TypeError` — the framework normalizes platform errors at the `executeCall` boundary, so raw platform errors no longer reach `catch` blocks after 7.0.0 (original is on `error.cause`). Use the `.safe()` sibling on RPC/API callables for an exhaustive `Result<T, E>` switch (`ok`, `typed`, `http`, `network`, `timeout`, `aborted`, `parse`, `usage`, `unknown`). Streams keep the throwing form — no `.safe()`.

package/agent_config/lib/install-claude.mjs

@@ -6,7 +6,7 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const SOURCE_DIR = join(__dirname, '..', 'claude-code');
 
-const SKILL_NAMES = ['ts-procedures', 'ts-procedures-review', 'ts-procedures-scaffold', 'ts-procedures-kotlin', 'ts-procedures-swift'];
+const SKILL_NAMES = ['ts-procedures'];
 const AGENT_FILES = ['ts-procedures-architect.md'];
 
 function listFilesRecursive(dir) {
@@ -26,9 +26,9 @@ function listFilesRecursive(dir) {
  * Install Claude Code integration files into a project's .claude/ directory.
  *
  * Creates:
- *   .claude/skills/ts-procedures/            — Framework reference skill
- *   .claude/skills/ts-procedures-scaffold/   — Scaffold skill (templates included)
- *   .claude/skills/ts-procedures-review/     — Review skill
+ *   .claude/skills/ts-procedures/            — Unified skill: framework reference plus
+ *                                              `review`/`scaffold` $ARGUMENTS modes (checklist +
+ *                                              templates bundled) and Kotlin/Swift codegen reference
  *   .claude/agents/ts-procedures-architect.md — Architecture planning agent
  *
  * @param {string} projectRoot — Absolute path to the consuming project's root