ts-procedures 6.0.2 → 6.2.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']) {
+    for (const skill of ['ts-procedures', 'ts-procedures-review', 'ts-procedures-scaffold', 'ts-procedures-kotlin', 'ts-procedures-swift']) {
       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');
+  console.log('  Skills:  ts-procedures, ts-procedures-scaffold, ts-procedures-review, ts-procedures-kotlin, ts-procedures-swift');
   console.log('  Agent:   ts-procedures-architect (architecture planning)\n');
   return false;
 }

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

@@ -15,6 +15,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.
 
 ## Core Flow
 

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

@@ -1013,6 +1013,8 @@ 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.
+
 Build-time CLI and programmatic API for generating typed client files from a `DocEnvelope`.
 
 ```typescript

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

@@ -0,0 +1,106 @@
+---
+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-swift/SKILL.md

@@ -0,0 +1,119 @@
+---
+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.

package/agent_config/copilot/copilot-instructions.md

@@ -386,6 +386,9 @@ npx ts-procedures-codegen --url http://localhost:3000/docs --out ./src/generated
 #                  --clean-out-dir   # recursively wipe --out before writing (prunes stale scope files)
 ```
 
+For Kotlin codegen (Android/JVM consumers), see `docs/codegen-kotlin.md` in the ts-procedures repo. The Kotlin target is types-only; consumer apps own HTTP/error handling.
+For Swift codegen (iOS/macOS/Apple-platform consumers), see `docs/codegen-swift.md` in the ts-procedures repo. The Swift target is types-only; consumer apps own HTTP/error handling.
+
 Generates one `.ts` file per scope plus a root `index.ts` that imports each scope as a namespace and exports a `create${ServiceName}Bindings(client)` factory AND a `create${ServiceName}Client(config)` convenience factory that pre-wires the error registry (defaults to `createApiBindings` / `createApiClient`; pass `--service-name <Name>` to rename). When namespace mode is on (the default), `index.ts` also wraps every scope namespace in an outer `export namespace ${ServiceName} { ... }` block so types are reachable as `Api.Users.GetUser.Params`, `Api.Errors.UseCaseError`, etc. The errors file (`_errors.ts`) emits runtime error classes extending a shared `${ServiceName}ProcedureError` base, each with `static fromResponse(body, meta)`, plus `${ServiceName}ErrorRegistry` (runtime dispatch map) and `${ServiceName}ProcedureErrorUnion` (type union). Defaults: `ApiErrors`, `ApiProcedureError`, `ApiErrorRegistry`, `ApiProcedureErrorUnion`.
 By default, types are wrapped in nested TS namespaces (`Scope.Route.Params`), JSDoc comments are emitted, and output is self-contained (no runtime dependency on `ts-procedures`). Use `--no-namespace-types` to revert to flat type names (`RouteParams`); this also disables the outer service namespace in `index.ts` and skips importing `_errors` from there.
 Note: ajsc formatting options (`--enum-style enum`, `--depluralize`, etc.) only take effect in namespace mode (the default). They are ignored with `--no-namespace-types`.

package/agent_config/cursor/cursorrules

@@ -386,6 +386,9 @@ npx ts-procedures-codegen --url http://localhost:3000/docs --out ./src/generated
 #                  --clean-out-dir   # recursively wipe --out before writing (prunes stale scope files)
 ```
 
+For Kotlin codegen (Android/JVM consumers), see `docs/codegen-kotlin.md` in the ts-procedures repo. The Kotlin target is types-only; consumer apps own HTTP/error handling.
+For Swift codegen (iOS/macOS/Apple-platform consumers), see `docs/codegen-swift.md` in the ts-procedures repo. The Swift target is types-only; consumer apps own HTTP/error handling.
+
 Generates one `.ts` file per scope plus a root `index.ts` that imports each scope as a namespace and exports a `create${ServiceName}Bindings(client)` factory AND a `create${ServiceName}Client(config)` convenience factory that pre-wires the error registry (defaults to `createApiBindings` / `createApiClient`; pass `--service-name <Name>` to rename). When namespace mode is on (the default), `index.ts` also wraps every scope namespace in an outer `export namespace ${ServiceName} { ... }` block so types are reachable as `Api.Users.GetUser.Params`, `Api.Errors.UseCaseError`, etc. The errors file (`_errors.ts`) emits runtime error classes extending a shared `${ServiceName}ProcedureError` base, each with `static fromResponse(body, meta)`, plus `${ServiceName}ErrorRegistry` (runtime dispatch map) and `${ServiceName}ProcedureErrorUnion` (type union). Defaults: `ApiErrors`, `ApiProcedureError`, `ApiErrorRegistry`, `ApiProcedureErrorUnion`.
 By default, types are wrapped in nested TS namespaces (`Scope.Route.Params`), JSDoc comments are emitted, and output is self-contained (no runtime dependency on `ts-procedures`). Use `--no-namespace-types` to revert to flat type names (`RouteParams`); this also disables the outer service namespace in `index.ts` and skips importing `_errors` from there.
 Note: ajsc formatting options (`--enum-style enum`, `--depluralize`, etc.) only take effect in namespace mode (the default). They are ignored with `--no-namespace-types`.

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'];
+const SKILL_NAMES = ['ts-procedures', 'ts-procedures-review', 'ts-procedures-scaffold', 'ts-procedures-kotlin', 'ts-procedures-swift'];
 const AGENT_FILES = ['ts-procedures-architect.md'];
 
 function listFilesRecursive(dir) {

package/build/codegen/bin/cli.d.ts

@@ -13,6 +13,16 @@ export interface CodegenConfig {
     selfContained?: boolean;
     serviceName?: string;
     cleanOutDir?: boolean;
+    target?: 'ts' | 'kotlin' | 'swift';
+    kotlin?: {
+        package: string;
+        serializer?: 'kotlinx' | 'none';
+    };
+    swift?: {
+        serializer?: 'codable' | 'none';
+        accessLevel?: 'public' | 'internal';
+    };
+    unsupportedUnions?: 'throw' | 'fallback';
 }
 export interface ParsedArgs {
     url?: string;
@@ -27,6 +37,16 @@ export interface ParsedArgs {
     selfContained: boolean;
     serviceName?: string;
     cleanOutDir: boolean;
+    target?: 'ts' | 'kotlin' | 'swift';
+    kotlin?: {
+        package: string;
+        serializer?: 'kotlinx' | 'none';
+    };
+    swift?: {
+        serializer?: 'codable' | 'none';
+        accessLevel?: 'public' | 'internal';
+    };
+    unsupportedUnions?: 'throw' | 'fallback';
 }
 /**
  * Loads a JSON config file. Returns undefined if the file doesn't exist.
@@ -45,3 +65,22 @@ export declare function parseArgs(argv: string[], config?: CodegenConfig): Parse
  * Extracts the --config value from argv without full parsing.
  */
 export declare function extractConfigPath(argv: string[]): string | undefined;
+export declare function printPostRunHints(parsed: {
+    target?: 'ts' | 'kotlin' | 'swift';
+}): void;
+/**
+ * Warns about flags that are currently no-ops for the Kotlin target.
+ *
+ * Scope is intentionally Kotlin-only — the param type omits `'swift'` so a
+ * reader can tell at a glance this function will never act on swift. Other
+ * targets get their own warner if/when they grow no-op flags. The call site
+ * narrows `parsed.target` before invoking.
+ *
+ * Currently: `--unsupported-unions` is a no-op because ajsc v7.2's Kotlin
+ * emitter silently emits an empty data class for untagged oneOf regardless
+ * of the flag (see docs/codegen-kotlin.md#untagged-unions).
+ */
+export declare function warnIfKotlinNoOpFlags(parsed: {
+    target?: 'ts' | 'kotlin';
+    unsupportedUnions?: 'throw' | 'fallback';
+}): void;

package/build/codegen/bin/cli.js

@@ -49,6 +49,12 @@ export function parseArgs(argv, config) {
     let selfContained = config?.selfContained ?? true;
     let serviceName = config?.serviceName;
     let cleanOutDir = config?.cleanOutDir ?? false;
+    let target = config?.target;
+    let kotlinPackage = config?.kotlin?.package;
+    let kotlinSerializer = config?.kotlin?.serializer;
+    let swiftSerializer = config?.swift?.serializer;
+    let swiftAccessLevel = config?.swift?.accessLevel;
+    let unsupportedUnions = config?.unsupportedUnions;
     let configPath;
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
@@ -116,18 +122,80 @@ export function parseArgs(argv, config) {
         else if (arg === '--no-clean-out-dir') {
             cleanOutDir = false;
         }
+        else if (arg === '--target') {
+            const val = argv[++i];
+            if (val === 'ts' || val === 'kotlin' || val === 'swift') {
+                target = val;
+            }
+            else {
+                throw new Error(`Invalid --target value: ${val ?? '(missing)'} (expected 'ts', 'kotlin', or 'swift')`);
+            }
+        }
+        else if (arg === '--kotlin-package') {
+            kotlinPackage = argv[++i];
+        }
+        else if (arg === '--kotlin-serializer') {
+            const val = argv[++i];
+            if (val === 'kotlinx' || val === 'none') {
+                kotlinSerializer = val;
+            }
+            else {
+                throw new Error(`Invalid --kotlin-serializer value: ${val ?? '(missing)'} (expected 'kotlinx' or 'none')`);
+            }
+        }
+        else if (arg === '--swift-serializer') {
+            const val = argv[++i];
+            if (val === 'codable' || val === 'none') {
+                swiftSerializer = val;
+            }
+            else {
+                throw new Error(`Invalid --swift-serializer value: ${val ?? '(missing)'} (expected 'codable' or 'none')`);
+            }
+        }
+        else if (arg === '--swift-access-level') {
+            const val = argv[++i];
+            if (val === 'public' || val === 'internal') {
+                swiftAccessLevel = val;
+            }
+            else {
+                throw new Error(`Invalid --swift-access-level value: ${val ?? '(missing)'} (expected 'public' or 'internal')`);
+            }
+        }
+        else if (arg === '--unsupported-unions') {
+            const val = argv[++i];
+            if (val === 'throw' || val === 'fallback') {
+                unsupportedUnions = val;
+            }
+            else {
+                throw new Error(`Invalid --unsupported-unions value: ${val ?? '(missing)'} (expected 'throw' or 'fallback')`);
+            }
+        }
         else if (arg === '--config') {
             configPath = argv[++i];
         }
     }
     // configPath is consumed by the caller (main) before parseArgs is called with the loaded config.
     // When called from main, config is already loaded. When called directly (tests), configPath is ignored.
+    // ---------------------------------------------------------------------------
+    // Validation — fails fast on user-controllable errors before envelope resolve.
+    // Runtime checks (emitter availability, etc.) happen later in pipeline.ts;
+    // those guards are aimed at non-CLI callers (direct API consumers, tests).
+    // The CLI resolves emitters before invoking `runPipeline`, so users only ever
+    // see flag-shape errors from this block, not pipeline-internal throws.
+    // ---------------------------------------------------------------------------
     if (outDir === undefined) {
         throw new Error('Missing required argument: --out <dir>');
     }
     if (url === undefined && file === undefined) {
         throw new Error('Missing required input source: provide --url <url> or --file <path>');
     }
+    // Kotlin target requires a package; surface this before any I/O happens.
+    if (target === 'kotlin' && (kotlinPackage === undefined || kotlinPackage === '')) {
+        throw new Error('Missing required argument: --kotlin-package <pkg> (required when --target kotlin)');
+    }
+    // Swift target currently has no required flags. If that changes, add the
+    // guard here so the failure mode stays consistent (flag-shape errors fire
+    // from parseArgs; runtime/emitter wiring errors fire from pipeline.ts).
     return {
         url,
         file,
@@ -141,6 +209,24 @@ export function parseArgs(argv, config) {
         selfContained,
         ...(serviceName !== undefined ? { serviceName } : {}),
         cleanOutDir,
+        ...(target !== undefined ? { target } : {}),
+        ...(kotlinPackage !== undefined
+            ? {
+                kotlin: {
+                    package: kotlinPackage,
+                    ...(kotlinSerializer !== undefined ? { serializer: kotlinSerializer } : {}),
+                },
+            }
+            : {}),
+        ...(swiftSerializer !== undefined || swiftAccessLevel !== undefined
+            ? {
+                swift: {
+                    ...(swiftSerializer !== undefined ? { serializer: swiftSerializer } : {}),
+                    ...(swiftAccessLevel !== undefined ? { accessLevel: swiftAccessLevel } : {}),
+                },
+            }
+            : {}),
+        ...(unsupportedUnions !== undefined ? { unsupportedUnions } : {}),
     };
 }
 /**
@@ -172,6 +258,21 @@ async function runWithWatch(parsed) {
         serviceName: parsed.serviceName,
         cleanOutDir: parsed.cleanOutDir,
     };
+    // Resolve the kotlin emitter once at watch start; it's stateless and reused per tick.
+    const kotlinWiring = parsed.target === 'kotlin'
+        ? {
+            target: 'kotlin',
+            kotlinPackage: parsed.kotlin.package,
+            kotlinEmitter: await (await import('../targets/kotlin/ajsc-adapter.js')).resolveProductionKotlinEmitter(),
+        }
+        : {};
+    // Resolve the swift emitter once at watch start; it's stateless and reused per tick.
+    const swiftWiring = parsed.target === 'swift'
+        ? {
+            target: 'swift',
+            swiftEmitter: await (await import('../targets/swift/ajsc-adapter.js')).resolveProductionSwiftEmitter(),
+        }
+        : {};
     let lastHash;
     const run = async () => {
         try {
@@ -194,6 +295,12 @@ async function runWithWatch(parsed) {
                 selfContained: parsed.selfContained,
                 serviceName: parsed.serviceName,
                 cleanOutDir: parsed.cleanOutDir,
+                ...(parsed.kotlin?.serializer !== undefined ? { kotlinSerializer: parsed.kotlin.serializer } : {}),
+                ...(parsed.unsupportedUnions !== undefined ? { unsupportedUnions: parsed.unsupportedUnions } : {}),
+                ...(parsed.swift?.serializer !== undefined ? { swiftSerializer: parsed.swift.serializer } : {}),
+                ...(parsed.swift?.accessLevel !== undefined ? { swiftAccessLevel: parsed.swift.accessLevel } : {}),
+                ...kotlinWiring,
+                ...swiftWiring,
             });
             console.log(`[ts-procedures-codegen] Generated client files → ${parsed.outDir}`);
         }
@@ -209,6 +316,34 @@ async function runWithWatch(parsed) {
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
+const KOTLIN_SETUP_GUIDE_URL = 'https://bitbucket.org/thermsio/ts-procedures/src/master/docs/codegen-kotlin.md';
+const SWIFT_SETUP_GUIDE_URL = 'https://bitbucket.org/thermsio/ts-procedures/src/master/docs/codegen-swift.md';
+export function printPostRunHints(parsed) {
+    if (parsed.target === 'kotlin') {
+        console.log(`[ts-procedures-codegen] Kotlin setup guide: ${KOTLIN_SETUP_GUIDE_URL}`);
+    }
+    if (parsed.target === 'swift') {
+        console.log(`[ts-procedures-codegen] Swift setup guide: ${SWIFT_SETUP_GUIDE_URL}`);
+    }
+}
+/**
+ * Warns about flags that are currently no-ops for the Kotlin target.
+ *
+ * Scope is intentionally Kotlin-only — the param type omits `'swift'` so a
+ * reader can tell at a glance this function will never act on swift. Other
+ * targets get their own warner if/when they grow no-op flags. The call site
+ * narrows `parsed.target` before invoking.
+ *
+ * Currently: `--unsupported-unions` is a no-op because ajsc v7.2's Kotlin
+ * emitter silently emits an empty data class for untagged oneOf regardless
+ * of the flag (see docs/codegen-kotlin.md#untagged-unions).
+ */
+export function warnIfKotlinNoOpFlags(parsed) {
+    if (parsed.target === 'kotlin' && parsed.unsupportedUnions !== undefined) {
+        console.warn('[ts-procedures-codegen] Note: --unsupported-unions is currently a no-op for --target kotlin ' +
+            '(ajsc v7.2 emits an empty data class regardless). See docs/codegen-kotlin.md#untagged-unions.');
+    }
+}
 async function main() {
     const argv = process.argv.slice(2);
     const configPath = extractConfigPath(argv);
@@ -217,12 +352,34 @@ async function main() {
         console.log(`[ts-procedures-codegen] Loaded config from ${configPath ?? DEFAULT_CONFIG_NAME}`);
     }
     const parsed = parseArgs(argv, config);
+    // The warner is intentionally Kotlin-only; pass the relevant fields and
+    // narrow `target` away from 'swift' here so the function's param type can
+    // stay tight.
+    if (parsed.target !== 'swift') {
+        warnIfKotlinNoOpFlags({
+            target: parsed.target,
+            ...(parsed.unsupportedUnions !== undefined ? { unsupportedUnions: parsed.unsupportedUnions } : {}),
+        });
+    }
     const source = parsed.url ?? parsed.file;
     console.log(`[ts-procedures-codegen] Reading docs from ${source}...`);
     if (parsed.watch) {
         await runWithWatch(parsed);
     }
     else {
+        const kotlinWiring = parsed.target === 'kotlin'
+            ? {
+                target: 'kotlin',
+                kotlinPackage: parsed.kotlin.package,
+                kotlinEmitter: await (await import('../targets/kotlin/ajsc-adapter.js')).resolveProductionKotlinEmitter(),
+            }
+            : {};
+        const swiftWiring = parsed.target === 'swift'
+            ? {
+                target: 'swift',
+                swiftEmitter: await (await import('../targets/swift/ajsc-adapter.js')).resolveProductionSwiftEmitter(),
+            }
+            : {};
         const result = await generateClient({
             url: parsed.url,
             file: parsed.file,
@@ -234,12 +391,19 @@ async function main() {
             selfContained: parsed.selfContained,
             serviceName: parsed.serviceName,
             cleanOutDir: parsed.cleanOutDir,
+            ...(parsed.kotlin?.serializer !== undefined ? { kotlinSerializer: parsed.kotlin.serializer } : {}),
+            ...(parsed.unsupportedUnions !== undefined ? { unsupportedUnions: parsed.unsupportedUnions } : {}),
+            ...(parsed.swift?.serializer !== undefined ? { swiftSerializer: parsed.swift.serializer } : {}),
+            ...(parsed.swift?.accessLevel !== undefined ? { swiftAccessLevel: parsed.swift.accessLevel } : {}),
+            ...kotlinWiring,
+            ...swiftWiring,
         });
         if (parsed.dryRun) {
             console.log(`[ts-procedures-codegen] Dry run complete — ${result.length} files would be generated`);
         }
         else {
             console.log(`[ts-procedures-codegen] Generated ${result.length} files → ${parsed.outDir}`);
+            printPostRunHints(parsed);
         }
     }
 }