ts-procedures 8.2.0 → 8.2.1

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,37 @@
 ---
 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.
 
+## 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 +39,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
 
@@ -173,8 +197,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

@@ -1222,7 +1222,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/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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-procedures",
-  "version": "8.2.0",
+  "version": "8.2.1",
   "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/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.

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

@@ -1,50 +0,0 @@
----
-name: ts-procedures-scaffold
-description: "Generate ts-procedures implementations with correct patterns — procedures, streams, Hono apps (RPC, streams, REST in one builder), and client setup."
-argument-hint: "<type> <Name>"
-allowed-tools: Read Write
----
-
-# Scaffold ts-procedures Code
-
-Scaffold a `$0` ts-procedures implementation named `$1`.
-
-If either argument is missing, ask the user for `<type>` and `<Name>`.
-
-## Instructions
-
-1. Validate `$0` is a recognized type (see table below). Case-insensitive.
-2. Validate `$1` 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/$0.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.

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

@@ -1,119 +0,0 @@
----
-name: ts-procedures-swift
-description: "Swift client codegen for ts-procedures — generate types-only Swift source from a ts-procedures DocEnvelope for iOS/macOS/Apple-platform consumers. Use when the user mentions Swift, iOS, macOS, Apple platforms, Codable, or asks how to generate non-TypeScript types from a ts-procedures server."
-user-invocable: false
----
-
-# ts-procedures — Swift Client Codegen
-
-You are assisting a developer who needs to generate Swift types from a `ts-procedures` server's `DocEnvelope`. The Swift target is **types-only** — no runtime, no adapter, no error registry. iOS / macOS / Apple-platform consumers own the HTTP layer.
-
-## When this skill 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, redirect them to the main `ts-procedures` skill. For **Kotlin/Android** consumers, redirect to `ts-procedures-kotlin`.
-
-## 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
-
-- **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.