@techspokes/typescript-wsdl-client 0.9.1 → 0.9.3

package/README.md

@@ -9,57 +9,46 @@
 [![TechSpokes Org](https://img.shields.io/badge/org-techspokes-181717?logo=github)](https://github.com/techspokes)
 [![Sponsor](https://img.shields.io/badge/sponsor-GitHub-blue?logo=github-sponsors)](https://github.com/sponsors/TechSpokes)
 
-> **Mission**: Transform complex WSDL/XSD definitions into ergonomic, type-safe TypeScript SOAP clients with optional OpenAPI 3.1 specs and production-ready Fastify REST gateways — enabling confident integration with legacy enterprise services.
+> **Transform complex WSDL/XSD definitions into type-safe TypeScript SOAP clients with optional OpenAPI 3.1 specs and production-ready REST gateways.**
 
----
+## Use This If You Need...
 
-## Table of Contents
+- ✅ **TypeScript-first SOAP clients** — Strongly typed, ergonomic client generation from WSDL
+- ✅ **OpenAPI 3.1 specs** — Generate REST API documentation that mirrors your TypeScript types
+- ✅ **REST gateway over SOAP** — Production-ready Fastify handlers with automatic request/response transformation
+- ✅ **CI-friendly determinism** — Stable, diff-friendly output for safe regeneration in version control
+- ✅ **Predictable modeling** — Flattened attributes, consistent `$value` convention, inheritance resolution
 
-- [1. Why This Project](#1-why-this-project-what-sets-it-apart)
-- [2. Installation](#2-installation)
-- [3. Quick Start](#3-quick-start)
-- [4. Commands Overview](#4-commands-overview)
-- [5. Command: `compile`](#5-command-compile)
-- [6. Command: `client`](#6-command-client)
-- [7. Command: `openapi`](#7-command-openapi)
-- [8. Command: `gateway`](#8-command-gateway)
-- [9. Command: `pipeline`](#9-command-pipeline)
-- [10. Working With Generated Clients](#10-working-with-generated-clients)
-- [11. OpenAPI Configuration](#11-openapi-configuration)
-- [12. Programmatic API](#12-programmatic-api)
-- [13. Advanced Topics](#13-advanced-topics)
-- [14. Troubleshooting](#14-troubleshooting)
-- [15. Contributing](#15-contributing)
-- [16. License](#16-license)
-- [17. Sponsors](#17-sponsors)
+**Vendor**: [TechSpokes](https://www.techspokes.com) · **Maintainer**: Serge Liatko ([@sergeliatko](https://github.com/sergeliatko))
 
 ---
 
-## 1. Why This Project (What Sets It Apart)
-
-Most WSDL generators produce loosely typed stubs or expose raw XML complexity to your application layer. This tool delivers **correct flattening, determinism, and multiple integration paths**:
-
-| Core Differentiator                  | What You Get                                                                                         |
-|--------------------------------------|------------------------------------------------------------------------------------------------------|
-| **Attribute + Element Flattening**   | Attributes and child elements appear as peer properties (no nested wrapper noise).                   |
-| **`$value` Text Content Convention** | Simple text & mixed content always represented as a `$value` property (collision-safe & documented). |
-| **Inheritance Resolution**           | `complexContent` and `simpleContent` extensions are merged or extended consistently.                 |
-| **Choice Strategy**                  | Predictable `all-optional` modeling today (future advanced discriminators planned).                  |
-| **WS-Policy Security Hints**         | Inline scan of policies surfaces required auth hints (e.g. `usernameToken`, `https`).                |
-| **Deterministic Output**             | Sorted declarations and stable alias resolution for diff-friendly regeneration.                      |
-| **Primitive Mapping Controls**       | Explicit flags for long / big integer / decimal / temporal families (string-first safety).           |
-| **Catalog Introspection**            | One JSON artifact (`catalog.json`) to drive further tooling (including OpenAPI & gateway).           |
-| **OpenAPI 3.1 Bridge**               | Mirrors the exact TypeScript model with no divergence between runtime and spec.                      |
-| **Standard Response Envelope**       | Always-on, debuggable envelope structure (status, message, data, error) for REST gateways.           |
-| **Fastify Gateway Generation**       | Production-ready route handlers with SOAP client integration and standardized envelope responses.    |
-| **Multi-format Output**              | `--openapi-format json\|yaml\|both` with always-on validation (unless disabled).                     |
-| **One-Shot Pipeline**                | Single pass (parse to TS to OpenAPI to Gateway) for CI & automation.                                 |
+## Table of Contents
 
-**Vendor**: [TechSpokes](https://www.techspokes.com) · **Maintainer**: Serge Liatko ([@sergeliatko](https://github.com/sergeliatko))
+- [Installation](#installation)
+- [Quick Start (60 Seconds)](#quick-start-60-seconds)
+- [What You Get (Outputs)](#what-you-get-outputs)
+- [Core Concepts](#core-concepts)
+- [Common Workflows](#common-workflows)
+- [Command Reference](#command-reference)
+  - [pipeline (Recommended)](#command-pipeline-recommended)
+  - [client](#command-client)
+  - [openapi](#command-openapi)
+  - [gateway](#command-gateway)
+  - [app](#command-app)
+  - [compile (Advanced)](#command-compile-advanced)
+- [Configuration Files](#configuration-files)
+- [Working With Generated Clients](#working-with-generated-clients)
+- [Production Concerns](#production-concerns)
+- [Programmatic API](#programmatic-api)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [License](#license)
+- [Support](#support)
 
 ---
 
-## 2. Installation
+## Installation
 
 ```bash
 npm install --save-dev @techspokes/typescript-wsdl-client
@@ -72,202 +61,557 @@ npm install soap   # Runtime dependency for SOAP calls
 
 ---
 
-## 3. Quick Start
+## Quick Start (60 Seconds)
+
+Generate a complete SOAP-to-REST stack in one command:
+
+```bash
+# Generate client, OpenAPI spec, gateway, and runnable app
+npx wsdl-tsc pipeline \
+  --wsdl-source examples/minimal/weather.wsdl \
+  --client-dir ./tmp/client \
+  --openapi-file ./tmp/openapi.json \
+  --gateway-dir ./tmp/gateway \
+  --gateway-service-name weather \
+  --gateway-version-prefix v1 \
+  --generate-app
+```
 
-### Generate TypeScript SOAP Client
+**Start the server:**
 
 ```bash
-npx wsdl-tsc client --wsdl-source ./wsdl/Weather.wsdl --client-dir ./src/services/weather
+cd tmp/app
+cp .env.example .env
+# Edit .env to set WSDL_SOURCE if needed
+npx tsx server.js
 ```
 
-**Try with included example:**
+**Test it:**
 
 ```bash
-npx wsdl-tsc client --wsdl-source examples/minimal/weather.wsdl --client-dir ./tmp/weather
+# Health check
+curl http://localhost:3000/health
+
+# Get OpenAPI spec
+curl http://localhost:3000/openapi.json | jq .
+
+# Call a SOAP operation via REST
+curl -X POST http://localhost:3000/get-weather-information \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+**What just happened?**
+1. Parsed the WSDL and compiled types
+2. Generated a TypeScript SOAP client with full type safety
+3. Created an OpenAPI 3.1 spec matching the client types
+4. Built Fastify gateway handlers that call SOAP and return JSON
+5. Created a runnable Express-style app with health/OpenAPI endpoints
+
+---
+
+## What You Get (Outputs)
+
+### TypeScript SOAP Client
+
 ```
+client/
+├── client.ts      # Strongly-typed SOAP client wrapper with methods
+├── types.ts       # Flattened interfaces, type aliases, and enums
+├── utils.ts       # Runtime metadata for JSON→SOAP conversion
+└── catalog.json   # Compiled schema representation (reusable)
+```
+
+**Example usage:**
+
+```typescript
+import { Weather } from './client/client.js';
+
+const client = new Weather({
+  source: 'https://example.com/weather.wsdl',
+});
+
+const result = await client.GetCityWeatherByZIP({ ZIP: '10001' });
+console.log(result.GetCityWeatherByZIPResult);
+```
+
+### OpenAPI 3.1 Specification
+
+```
+openapi.json   # or .yaml — Complete REST API documentation
+```
+
+- Mirrors exact TypeScript type structure
+- All responses wrapped in standard envelope (status, message, data, error)
+- Deterministic ordering for version control
+- Validates with `swagger-parser` by default
+
+### Fastify REST Gateway
+
+```
+gateway/
+├── schemas/
+│   ├── models/         # JSON Schema components with URN IDs
+│   └── operations/     # Request/response validation schemas
+├── routes/             # Route handlers (fully implemented)
+├── schemas.ts          # Schema registration module
+├── routes.ts           # Route aggregator
+├── runtime.ts          # Envelope builders, error handlers
+└── plugin.ts           # Fastify plugin wrapper
+```
+
+**Example integration:**
+
+```typescript
+import Fastify from 'fastify';
+import weatherGateway from './gateway/plugin.js';
+import { Weather } from './client/client.js';
+
+const app = Fastify({ logger: true });
+const client = new Weather({ source: 'weather.wsdl' });
+
+await app.register(weatherGateway, { client });
+await app.listen({ port: 3000 });
+```
+
+### Runnable Application
+
+```
+app/
+├── server.js       # Main entry point
+├── config.js       # Configuration with env var support
+├── .env.example    # Environment template
+├── README.md       # Usage instructions
+└── openapi.json    # OpenAPI spec (when --openapi-mode=copy)
+```
+
+### Standard Response Envelope
+
+All gateway responses follow this structure:
+
+**Success:**
+```json
+{
+  "status": "SUCCESS",
+  "message": null,
+  "data": { /* SOAP response */ },
+  "error": null
+}
+```
+
+**Error:**
+```json
+{
+  "status": "ERROR",
+  "message": "Request validation failed",
+  "data": null,
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Request validation failed",
+    "details": { /* validation errors */ }
+  }
+}
+```
+
+---
+
+## Core Concepts
+
+### Flattening and `$value`
+
+**Attributes and elements become peer properties** — No nested wrapper noise:
+
+```xml
+<!-- WSDL -->
+<xs:complexType name="Price">
+  <xs:simpleContent>
+    <xs:extension base="xs:decimal">
+      <xs:attribute name="currency" type="xs:string"/>
+    </xs:extension>
+  </xs:simpleContent>
+</xs:complexType>
+```
+
+```typescript
+// Generated TypeScript
+interface Price {
+  currency?: string;  // attribute
+  $value: string;     // text content (decimal mapped to string by default)
+}
+```
+
+### Primitive Mapping Defaults (String-First Safety)
+
+Prevents precision loss and parsing errors at the cost of convenience:
+
+| XSD Type      | Default  | Override Options   | When to Override                       |
+|---------------|----------|--------------------|----------------------------------------|
+| `xs:long`     | `string` | `number`, `bigint` | Use `number` if values fit JS range    |
+| `xs:integer`  | `string` | `number`           | Use `string` for arbitrary-size ints   |
+| `xs:decimal`  | `string` | `number`           | Use `string` for precise decimals      |
+| `xs:dateTime` | `string` | `Date`             | Use `Date` if runtime parsing is okay  |
+
+**Override with flags:**
+- `--client-int64-as number`
+- `--client-decimal-as string`
+- `--client-date-as Date`
+
+### Deterministic Generation
+
+All output is **stable and diff-friendly** for CI/CD:
+
+- ✅ Sorted type declarations
+- ✅ Sorted OpenAPI paths, schemas, parameters
+- ✅ Sorted JSON schema keys
+- ✅ Stable alias resolution
+- ✅ Consistent ordering of imports
+
+Regenerate safely without spurious diffs in version control.
+
+### Catalog as Intermediate Artifact
+
+`catalog.json` is the compiled representation of your WSDL:
+
+- **Debuggable** — Inspect types, operations, and metadata as JSON
+- **Cacheable** — Reuse across client/OpenAPI/gateway generation
+- **Co-located** — Automatically placed alongside generated output
 
-### Generate Everything (Pipeline)
+**Common locations:**
+- `client` command: `{client-dir}/catalog.json`
+- `openapi` command: `{openapi-dir}/catalog.json`
+- `pipeline` command: First available output directory
+
+---
+
+## Common Workflows
+
+### Which Command Should I Run?
+
+| I Want...                                     | Use Command  | Example                                                                                                              |
+|-----------------------------------------------|--------------|----------------------------------------------------------------------------------------------------------------------|
+| **Everything (client + OpenAPI + gateway)**   | `pipeline`   | `npx wsdl-tsc pipeline --wsdl-source service.wsdl --client-dir ./client --openapi-file ./api.json --gateway-dir ./gateway --gateway-service-name svc --gateway-version-prefix v1` |
+| **Only a TypeScript SOAP client**             | `client`     | `npx wsdl-tsc client --wsdl-source service.wsdl --client-dir ./client`                                              |
+| **Only OpenAPI spec (for docs or SDKs)**      | `openapi`    | `npx wsdl-tsc openapi --wsdl-source service.wsdl --openapi-file ./api.json`                                         |
+| **Only REST gateway (have OpenAPI already)**  | `gateway`    | `npx wsdl-tsc gateway --openapi-file ./api.json --client-dir ./client --gateway-dir ./gateway --gateway-service-name svc --gateway-version-prefix v1` |
+| **Runnable server for testing**               | `app`        | `npx wsdl-tsc app --client-dir ./client --gateway-dir ./gateway --openapi-file ./api.json`                          |
+| **Debug/inspect WSDL compilation**            | `compile`    | `npx wsdl-tsc compile --wsdl-source service.wsdl --catalog-file ./catalog.json`                                     |
+
+### Workflow 1: Generate Everything (Recommended)
+
+Use `pipeline` for complete stack generation:
 
 ```bash
 npx wsdl-tsc pipeline \
   --wsdl-source examples/minimal/weather.wsdl \
-  --client-dir ./tmp/client \
-  --openapi-file ./tmp/openapi.json \
-  --gateway-dir ./tmp/gateway \
+  --client-dir ./src/services/weather \
+  --openapi-file ./docs/weather-api.json \
+  --gateway-dir ./src/gateway/weather \
   --gateway-service-name weather \
   --gateway-version-prefix v1
 ```
 
-**Output**: Generates client files in `tmp/client/`, OpenAPI spec at `tmp/openapi.json`, gateway code in `tmp/gateway/`, and catalog at `tmp/client/catalog.json`.
+**Output:**
+- Client: `./src/services/weather/client.ts`, `types.ts`, `utils.ts`, `catalog.json`
+- OpenAPI: `./docs/weather-api.json`
+- Gateway: `./src/gateway/weather/` (routes, schemas, plugin)
 
----
+### Workflow 2: SOAP Client Only
 
-## 4. Commands Overview
+Generate TypeScript client for direct SOAP integration:
 
-The tool provides **five commands** for different integration scenarios:
+```bash
+npx wsdl-tsc client \
+  --wsdl-source ./wsdl/Hotel.wsdl \
+  --client-dir ./src/services/hotel
+```
 
-| Command    | Purpose                                                       | Typical Use Case                              |
-|------------|---------------------------------------------------------------|-----------------------------------------------|
-| `compile`  | Parse WSDL and emit `catalog.json` only                       | Debugging, inspection, or multi-stage builds  |
-| `client`   | Generate TypeScript SOAP client from WSDL or catalog          | Standard SOAP integration (most common)       |
-| `openapi`  | Generate OpenAPI 3.1 spec from WSDL or catalog                | Documentation, REST proxies, API gateways     |
-| `gateway`  | Generate Fastify gateway with full handlers from OpenAPI spec | Production REST gateway with SOAP integration |
-| `pipeline` | Run full pipeline: client + OpenAPI + gateway in one pass     | CI/CD automation, complete stack generation   |
+**Usage:**
 
----
+```typescript
+import soap from 'soap';
+import { Hotel } from './src/services/hotel/client.js';
 
-## 5. Command: `compile`
+const client = new Hotel({
+  source: 'https://example.com/hotel.wsdl',
+  security: new soap.WSSecurity('username', 'password'),
+});
 
-**Purpose**: Parse WSDL and generate only the intermediate `catalog.json` representation without TypeScript client code.
+const result = await client.SearchAvailableRooms({
+  checkIn: '2024-01-15',
+  checkOut: '2024-01-20',
+  guests: 2,
+});
+```
 
-**When to use**: 
-- Multi-stage builds where you want to cache the parsed WSDL
-- Debugging or inspecting the compiled schema structure
-- Sharing a compiled catalog across multiple generation targets
+### Workflow 3: OpenAPI for Documentation
 
-### Usage
+Generate OpenAPI spec for API documentation or SDK generation:
 
 ```bash
-npx wsdl-tsc compile --wsdl-source <file|url> --catalog-file <path> [options]
+npx wsdl-tsc openapi \
+  --wsdl-source ./wsdl/Booking.wsdl \
+  --openapi-file ./docs/booking-api.yaml \
+  --openapi-format yaml \
+  --openapi-title "Hotel Booking API" \
+  --openapi-version "1.0.0" \
+  --openapi-servers https://api.example.com/v1
 ```
 
-### Required Flags
+**Use the spec:**
+- Import into Postman, Insomnia, or Swagger UI
+- Generate client SDKs with OpenAPI Generator
+- Share as REST API documentation
 
-| Flag                | Description                              |
-|---------------------|------------------------------------------|
-| `--wsdl-source`     | Path or URL to the WSDL file             |
-| `--catalog-file`    | Output path for `catalog.json`           |
+### Workflow 4: REST Gateway Over SOAP
 
-### Optional Flags
+Build a REST API layer over legacy SOAP services:
 
-| Flag                               | Default        | Description                                                  |
-|------------------------------------|----------------|--------------------------------------------------------------|
-| `--import-extensions`              | `js`           | Import specifier style: `js`, `ts`, or `bare`                |
-| `--client-attributes-key`          | `$attributes`  | Attribute bag key for runtime mapper                         |
-| `--client-class-name`              | (derived)      | Override generated client class name                         |
-| `--client-int64-as`                | `string`       | Map 64-bit integers: `string`, `number`, or `bigint`         |
-| `--client-bigint-as`               | `string`       | Map arbitrary-size integers: `string` or `number`            |
-| `--client-decimal-as`              | `string`       | Map `xs:decimal`: `string` or `number`                       |
-| `--client-date-as`                 | `string`       | Map date/time types: `string` or `Date`                      |
-| `--client-choice-mode`             | `all-optional` | Choice element strategy: `all-optional` or `union`           |
-| `--client-fail-on-unresolved`      | `false`        | Fail build on unresolved type references                     |
-| `--client-nillable-as-optional`    | `false`        | Treat nillable elements as optional properties               |
+```bash
+# 1. Generate client + OpenAPI
+npx wsdl-tsc pipeline \
+  --wsdl-source ./wsdl/Legacy.wsdl \
+  --client-dir ./src/services/legacy \
+  --openapi-file ./docs/legacy-api.json
 
-### Examples
+# 2. Generate gateway
+npx wsdl-tsc gateway \
+  --openapi-file ./docs/legacy-api.json \
+  --client-dir ./src/services/legacy \
+  --gateway-dir ./src/gateway/legacy \
+  --gateway-service-name legacy \
+  --gateway-version-prefix v1
+```
 
-#### Basic Compilation
+**Or in one command:**
 
 ```bash
-npx wsdl-tsc compile \
-  --wsdl-source examples/minimal/weather.wsdl \
-  --catalog-file tmp/catalog.json
+npx wsdl-tsc pipeline \
+  --wsdl-source ./wsdl/Legacy.wsdl \
+  --client-dir ./src/services/legacy \
+  --openapi-file ./docs/legacy-api.json \
+  --gateway-dir ./src/gateway/legacy \
+  --gateway-service-name legacy \
+  --gateway-version-prefix v1
 ```
 
-#### With Custom Output Path
+### Workflow 5: CI/CD Integration
+
+Cache compiled catalog for faster multi-stage builds:
 
 ```bash
+# Stage 1: Compile catalog (cacheable)
 npx wsdl-tsc compile \
-  --wsdl-source https://example.com/Hotel.wsdl \
-  --catalog-file ./build/hotel-catalog.json \
-  --client-int64-as number \
-  --client-decimal-as string
+  --wsdl-source ./wsdl/Service.wsdl \
+  --catalog-file ./build/service-catalog.json
+
+# Stage 2: Generate client from catalog
+npx wsdl-tsc client \
+  --catalog-file ./build/service-catalog.json \
+  --client-dir ./src/services/service
+
+# Stage 3: Generate OpenAPI from catalog
+npx wsdl-tsc openapi \
+  --catalog-file ./build/service-catalog.json \
+  --openapi-file ./docs/service-api.json
 ```
 
-#### For Debugging
+### Workflow 6: Debugging Complex WSDL
+
+Inspect compiled types and operations:
 
 ```bash
-# Compile to inspect types and operations
+# Compile to catalog
 npx wsdl-tsc compile \
-  --wsdl-source ./wsdl/ComplexService.wsdl \
-  --catalog-file ./debug/catalog.json \
-  --client-fail-on-unresolved false
+  --wsdl-source ./wsdl/Complex.wsdl \
+  --catalog-file ./debug/catalog.json
+
+# Inspect types
+cat ./debug/catalog.json | jq '.types'
+
+# Inspect operations
+cat ./debug/catalog.json | jq '.operations'
 ```
 
-### Output
+---
+
+## Command Reference
 
-- `catalog.json` - Compiled schema representation including types, operations, and metadata
+The tool provides **six commands** for different integration scenarios. Commands are listed in **recommended order of use**:
 
-### Catalog Structure
+| Command    | Purpose                                                        | Typical Use Case                              |
+|------------|----------------------------------------------------------------|-----------------------------------------------|
+| `pipeline` | Run full pipeline: client + OpenAPI + gateway (+ app optional) | **CI/CD automation, complete stack generation (recommended)** |
+| `client`   | Generate TypeScript SOAP client from WSDL or catalog           | Standard SOAP integration                     |
+| `openapi`  | Generate OpenAPI 3.1 spec from WSDL or catalog                 | Documentation, REST proxies, API gateways     |
+| `gateway`  | Generate Fastify gateway with full handlers from OpenAPI spec  | Production REST gateway with SOAP integration |
+| `app`      | Generate runnable Fastify app from client + gateway + OpenAPI  | Local testing, quick iteration, demos         |
+| `compile`  | Parse WSDL and emit `catalog.json` only                        | Debugging, inspection, or multi-stage builds (advanced) |
 
-The catalog.json file contains the compiled WSDL representation:
+---
 
-```json
-{
-  "wsdlUri": "path/to/service.wsdl",
-  "targetNamespace": "http://example.com/service",
-  "serviceName": "WeatherService",
-  "types": [
-    {
-      "name": "GetWeatherRequest",
-      "properties": []
-    }
-  ],
-  "operations": [
-    {
-      "name": "GetWeather",
-      "input": "GetWeatherRequest",
-      "output": "GetWeatherResponse"
-    }
-  ],
-  "options": {
-    "imports": "js",
-    "catalog": true
-  }
-}
+### Command: `pipeline` (Recommended)
+
+**Purpose**: Run the complete generation pipeline in a single pass: WSDL parsing → TypeScript client → OpenAPI spec → Fastify gateway (+ app optional).
+
+**When to use**:
+- CI/CD automation
+- Complete stack generation
+- Ensuring all artifacts are generated from the same WSDL parse
+- One-command development workflows
+
+#### Usage
+
+```bash
+npx wsdl-tsc pipeline \
+  --wsdl-source <file|url> \
+  [--catalog-file <path>] \
+  [--client-dir <path>] \
+  [--openapi-file <path>] \
+  [--gateway-dir <path>] \
+  [options]
 ```
 
-**Key sections**:
-- `types` - All compiled type definitions with properties and inheritance
-- `operations` - SOAP operations with input/output type references
-- `options` - Compiler options used during generation
+#### Required Flags
 
-This catalog can be reused with the `client` and `openapi` commands via `--catalog-file`.
+| Flag                | Description                                                          |
+|---------------------|----------------------------------------------------------------------|
+| `--wsdl-source`     | Path or URL to WSDL file                                             |
 
-### Catalog File Organization
+#### Output Flags
 
-**Default behavior**: Catalog files are **co-located** with their primary output files for better organization and discoverability.
+| Flag                | Default                                     | Description                                       |
+|---------------------|---------------------------------------------|---------------------------------------------------|
+| `--catalog-file`    | Co-located with first output (see below)    | Output path for `catalog.json` (always generated) |
 
-**Catalog Location by Command**:
-- `compile`: Always requires explicit `--catalog-file` (no default)
-- `client`: Defaults to `{client-dir}/catalog.json`
-- `openapi`: Defaults to `{openapi-file-dir}/catalog.json`
-- `pipeline`: Intelligent cascade - first available: `{client-dir}` > `{openapi-dir}` > `{gateway-dir}` > `tmp/`
+**Catalog Default Location**: The catalog is automatically placed alongside the first available output:
+- With `--client-dir`: `{client-dir}/catalog.json`
+- With `--openapi-file` only: `{openapi-file-dir}/catalog.json`
+- With `--gateway-dir` only: `{gateway-dir}/catalog.json`
 
-**Common patterns**:
+**Note**: At least one of `--client-dir`, `--openapi-file`, or `--gateway-dir` must be provided.
 
-1. **Co-located with client** (recommended for most projects):
-   ```bash
-   npx wsdl-tsc client --wsdl-source service.wsdl --client-dir src/services/weather
-   ```
-   
-   Creates `src/services/weather/catalog.json` automatically.
-   
-   Result:
-   ```
-   src/services/weather/
-   ├── client.ts
-   ├── types.ts
-   ├── utils.ts
-   └── catalog.json
-   ```
+#### Generation Control Flags
 
-2. **Pipeline with multiple outputs** (catalog in client directory):
-   ```bash
-   npx wsdl-tsc pipeline --wsdl-source service.wsdl --client-dir src/client --openapi-file docs/api.json
-   ```
-   
-   Creates `src/client/catalog.json` (co-located with client).
+| Flag                    | Description                                    |
+|-------------------------|------------------------------------------------|
+| `--client-dir`          | Generate TypeScript client in this directory   |
+| `--openapi-file`        | Generate OpenAPI spec at this path             |
+| `--gateway-dir`         | Generate Fastify gateway in this directory     |
+| `--generate-app`        | Generate runnable app (requires gateway)       |
 
-3. **Shared catalog for multiple commands** (custom location):
-   ```bash
-   npx wsdl-tsc compile --wsdl-source service.wsdl --catalog-file build/shared-catalog.json
-   npx wsdl-tsc client --catalog-file build/shared-catalog.json --client-dir src/client
-   npx wsdl-tsc openapi --catalog-file build/shared-catalog.json --openapi-file docs/api.json
-   ```
+#### Optional Flags
+
+All flags from `client`, `openapi`, and `gateway` commands are supported. Key flags:
+
+**Client Flags:**
+- `--import-extensions` (default: `js`)
+- `--client-attributes-key` (default: `$attributes`)
+- `--client-class-name`
+- `--client-int64-as` (default: `string`)
+- `--client-bigint-as` (default: `string`)
+- `--client-decimal-as` (default: `string`)
+- `--client-date-as` (default: `string`)
+- `--client-choice-mode` (default: `all-optional`)
+- `--client-fail-on-unresolved` (default: `false`)
+- `--client-nillable-as-optional` (default: `false`)
+
+**OpenAPI Flags:**
+- `--openapi-format` (default: `json`)
+- `--openapi-title`
+- `--openapi-version` (default: `0.0.0`)
+- `--openapi-description`
+- `--openapi-servers` (default: `/`)
+- `--openapi-base-path`
+- `--openapi-path-style` (default: `kebab`)
+- `--openapi-method` (default: `post`)
+- `--openapi-tag-style` (default: `default`)
+- `--openapi-closed-schemas` (default: `false`)
+- `--openapi-prune-unused-schemas` (default: `false`)
+- `--openapi-envelope-namespace` (default: `ResponseEnvelope`)
+- `--openapi-error-namespace` (default: `ErrorObject`)
+- `--openapi-validate` (default: `true`)
+- `--openapi-security-config-file`
+- `--openapi-tags-file`
+- `--openapi-ops-file`
+
+**Gateway Flags:**
+- `--gateway-service-name` (required if `--gateway-dir` provided)
+- `--gateway-version-prefix` (required if `--gateway-dir` provided)
+- `--gateway-default-status-codes`
+- `--gateway-stub-handlers` (default: `false`)
+
+#### Examples
+
+**Complete Stack Generation:**
+
+```bash
+npx wsdl-tsc pipeline \
+  --wsdl-source examples/minimal/weather.wsdl \
+  --client-dir tmp/client \
+  --openapi-file tmp/openapi.json \
+  --gateway-dir tmp/gateway \
+  --gateway-service-name weather \
+  --gateway-version-prefix v1
+```
+
+**With App Generation:**
+
+```bash
+npx wsdl-tsc pipeline \
+  --wsdl-source examples/minimal/weather.wsdl \
+  --client-dir tmp/client \
+  --openapi-file tmp/openapi.json \
+  --gateway-dir tmp/gateway \
+  --gateway-service-name weather \
+  --gateway-version-prefix v1 \
+  --generate-app
+```
+
+**Client + OpenAPI Only:**
+
+```bash
+npx wsdl-tsc pipeline \
+  --wsdl-source https://example.com/Hotel.wsdl \
+  --client-dir ./build/client \
+  --openapi-file ./docs/hotel-api.json \
+  --openapi-format both
+```
+
+**With Full Configuration:**
+
+```bash
+npx wsdl-tsc pipeline \
+  --wsdl-source ./wsdl/Booking.wsdl \
+  --client-dir ./build/client \
+  --openapi-file ./docs/booking-api \
+  --gateway-dir ./build/gateway \
+  --openapi-format both \
+  --openapi-servers https://api.example.com/v1 \
+  --openapi-base-path /booking \
+  --openapi-security-config-file ./config/security.json \
+  --gateway-service-name booking \
+  --gateway-version-prefix v1 \
+  --client-int64-as number \
+  --client-decimal-as string
+```
+
+#### Pipeline Workflow
+
+The pipeline command executes these steps in order:
+
+1. **Parse WSDL** → Load and validate WSDL document
+2. **Compile Catalog** → Generate intermediate representation
+3. **Emit Catalog** → Write `catalog.json` (always)
+4. **Generate Client** → Emit TypeScript client files (if `--client-dir`)
+5. **Generate OpenAPI** → Create OpenAPI spec (if `--openapi-file`)
+6. **Generate Gateway** → Create Fastify gateway code (if `--gateway-dir`)
+7. **Generate App** → Create runnable application (if `--generate-app`)
+
+All steps share the same parsed WSDL and compiled catalog, ensuring consistency.
 
 ---
 
-## 6. Command: `client`
+### Command: `client`
 
 **Purpose**: Generate strongly-typed TypeScript SOAP client code from WSDL or a pre-compiled catalog.
 
@@ -382,7 +726,7 @@ npx wsdl-tsc client \
 
 ---
 
-## 7. Command: `openapi`
+### Command: `openapi`
 
 **Purpose**: Generate OpenAPI 3.1 specification from WSDL or a pre-compiled catalog, mirroring the exact TypeScript type structure.
 
@@ -577,7 +921,7 @@ This ensures diff-friendly output for version control.
 
 ---
 
-## 8. Command: `gateway`
+### Command: `gateway`
 
 **Purpose**: Generate a production-ready Fastify gateway with fully functional route handlers from an OpenAPI 3.1 specification. This creates a complete REST API layer over your SOAP client with automatic request/response transformation and standardized envelope responses.
 
@@ -860,189 +1204,334 @@ npx wsdl-tsc gateway \
   --gateway-stub-handlers
 ```
 
-This generates minimal handler stubs that throw "Not implemented" errors, allowing you to implement fully custom logic while keeping the routing and validation infrastructure.
+This generates minimal handler stubs that throw "Not implemented" errors, allowing you to implement fully custom logic while keeping the routing and validation infrastructure.
+
+---
+
+### Command: `app`
+
+**Purpose**: Generate a runnable Fastify application that integrates the generated client, gateway, and OpenAPI spec. This provides an immediately executable server for testing, development, and demonstrations.
+
+**When to use**:
+- Local testing and development
+- Quick iteration on gateway configurations
+- Demonstrating the generated API
+- CI smoke testing
+
+### Usage
+
+```bash
+npx wsdl-tsc app \
+  --client-dir <path> \
+  --gateway-dir <path> \
+  --openapi-file <path> \
+  [--catalog-file <path>] \
+  [--app-dir <path>] \
+  [options]
+```
+
+### Required Flags
+
+| Flag             | Description                                              |
+|------------------|----------------------------------------------------------|
+| `--client-dir`   | Path to client directory (where `client.ts` is located)  |
+| `--gateway-dir`  | Path to gateway directory (where `plugin.ts` is located) |
+| `--openapi-file` | Path to OpenAPI specification file                       |
+
+### Optional Flags
+
+| Flag                  | Default                       | Description                                       |
+|-----------------------|-------------------------------|---------------------------------------------------|
+| `--catalog-file`      | `{client-dir}/catalog.json`   | Path to catalog.json (for metadata extraction)    |
+| `--app-dir`           | `{gateway-dir}/../app`        | Output directory for generated app                |
+| `--import-extensions` | Inferred from catalog or `js` | Import-extension mode: `js`, `ts`, or `bare`      |
+| `--host`              | `127.0.0.1`                   | Default server host                               |
+| `--port`              | `3000`                        | Default server port                               |
+| `--prefix`            | `""` (empty)                  | Route prefix                                      |
+| `--logger`            | `true`                        | Enable Fastify logger                             |
+| `--openapi-mode`      | `copy`                        | How to handle OpenAPI file: `copy` or `reference` |
+
+### Examples
+
+#### Generate App After Pipeline
+
+```bash
+# First generate client, OpenAPI, and gateway
+npx wsdl-tsc pipeline \
+  --wsdl-source weather.wsdl \
+  --client-dir ./client \
+  --openapi-file ./openapi.json \
+  --gateway-dir ./gateway \
+  --gateway-service-name weather \
+  --gateway-version-prefix v1
+
+# Then generate runnable app
+npx wsdl-tsc app \
+  --client-dir ./client \
+  --gateway-dir ./gateway \
+  --openapi-file ./openapi.json \
+  --app-dir ./app
+```
+
+#### Generate App with Custom Configuration
+
+```bash
+npx wsdl-tsc app \
+  --client-dir ./client \
+  --gateway-dir ./gateway \
+  --openapi-file ./openapi.json \
+  --app-dir ./my-app \
+  --host 0.0.0.0 \
+  --port 8080 \
+  --prefix /api/v1
+```
+
+### Generated App Structure
+
+The `app` command generates the following files:
+
+```
+app/
+├── server.js (or .ts)    # Main application entry point
+├── config.js (or .ts)    # Configuration loader with env support
+├── .env.example          # Environment variable template
+├── README.md             # Usage instructions
+└── openapi.json          # OpenAPI spec (when --openapi-mode=copy)
+```
+
+### Running the Generated App
+
+```bash
+# Copy environment template
+cd app
+cp .env.example .env
+
+# Edit .env to configure WSDL source and other settings
+# vim .env
+
+# Run the server
+npx tsx server.js  # For TypeScript files
+# or
+node server.js     # For JavaScript files
+```
+
+### Configuration
+
+The generated app loads configuration from environment variables with the following precedence:
+
+1. **Environment variables** (runtime overrides)
+2. **Catalog defaults** (from generation-time)
+3. **Hard defaults** (in config file)
+
+#### Environment Variables
+
+| Variable        | Default (from catalog or flags) | Description                          |
+|-----------------|---------------------------------|--------------------------------------|
+| `WSDL_SOURCE`   | From catalog or **required**    | WSDL URL or local file path          |
+| `HOST`          | `127.0.0.1`                     | Server bind address                  |
+| `PORT`          | `3000`                          | Server listen port                   |
+| `PREFIX`        | `""` (empty)                    | Route prefix                         |
+| `LOGGER`        | `true`                          | Enable Fastify logger                |
+
+### Endpoints
+
+The generated app serves the following endpoints:
+
+#### Health Check
+```bash
+GET /health
+```
+Returns: `{ "ok": true }`
+
+#### OpenAPI Specification
+```bash
+GET /openapi.json
+```
+Returns: Complete OpenAPI 3.1 specification
 
----
+#### Gateway Routes
+All SOAP operations are exposed as REST endpoints. See the OpenAPI spec for complete API documentation.
 
-## 9. Command: `pipeline`
+### Example Usage
 
-**Purpose**: Run the complete generation pipeline in a single pass: WSDL parsing → TypeScript client → OpenAPI spec → Fastify gateway.
+```bash
+# Start the server
+cd app
+npx tsx server.js
 
-**When to use**:
-- CI/CD automation
-- Complete stack generation
-- Ensuring all artifacts are generated from the same WSDL parse
-- One-command development workflows
+# Test health endpoint
+curl http://localhost:3000/health
 
-### Usage
+# Get OpenAPI spec
+curl http://localhost:3000/openapi.json | jq .
 
-```bash
-npx wsdl-tsc pipeline \
-  --wsdl-source <file|url> \
-  [--catalog-file <path>] \
-  [--client-dir <path>] \
-  [--openapi-file <path>] \
-  [--gateway-dir <path>] \
-  [options]
+# Call a gateway operation (example)
+curl -X POST http://localhost:3000/get-weather-information \
+  -H "Content-Type: application/json" \
+  -d '{}'
 ```
 
-### Required Flags
+### Integration with Pipeline
 
-| Flag                | Description                                                          |
-|---------------------|----------------------------------------------------------------------|
-| `--wsdl-source`     | Path or URL to WSDL file                                             |
+The `app` command can also be used via the pipeline with the `--generate-app` flag:
 
-### Output Flags
+```bash
+npx wsdl-tsc pipeline \
+  --wsdl-source weather.wsdl \
+  --client-dir ./client \
+  --openapi-file ./openapi.json \
+  --gateway-dir ./gateway \
+  --gateway-service-name weather \
+  --gateway-version-prefix v1 \
+  --generate-app
+```
 
-| Flag                | Default                                     | Description                                       |
-|---------------------|---------------------------------------------|---------------------------------------------------|
-| `--catalog-file`    | Co-located with first output (see below)    | Output path for `catalog.json` (always generated) |
+This generates all artifacts including the runnable app in a single command.
 
-**Catalog Default Location**: The catalog is automatically placed alongside the first available output:
-- With `--client-dir`: `{client-dir}/catalog.json`
-- With `--openapi-file` only: `{openapi-file-dir}/catalog.json`
-- With `--gateway-dir` only: `{gateway-dir}/catalog.json`
+---
 
-**Note**: At least one of `--client-dir`, `--openapi-file`, or `--gateway-dir` must be provided.
+### Command: `compile` (Advanced)
 
-### Generation Control Flags
+**Purpose**: Parse WSDL and generate only the intermediate `catalog.json` representation without TypeScript client code.
 
-| Flag                    | Description                                    |
-|-------------------------|------------------------------------------------|
-| `--client-dir`          | Generate TypeScript client in this directory   |
-| `--openapi-file`        | Generate OpenAPI spec at this path             |
-| `--gateway-dir`         | Generate Fastify gateway in this directory     |
+**When to use**: 
+- Multi-stage builds where you want to cache the parsed WSDL
+- Debugging or inspecting the compiled schema structure
+- Sharing a compiled catalog across multiple generation targets
 
-### Optional Flags
+#### Usage
 
-All flags from `client`, `openapi`, and `gateway` commands are supported. Key flags:
+```bash
+npx wsdl-tsc compile --wsdl-source <file|url> --catalog-file <path> [options]
+```
 
-#### Client Flags
-- `--import-extensions` (default: `js`)
-- `--client-attributes-key` (default: `$attributes`)
-- `--client-class-name`
-- `--client-int64-as` (default: `string`)
-- `--client-bigint-as` (default: `string`)
-- `--client-decimal-as` (default: `string`)
-- `--client-date-as` (default: `string`)
-- `--client-choice-mode` (default: `all-optional`)
-- `--client-fail-on-unresolved` (default: `false`)
-- `--client-nillable-as-optional` (default: `false`)
+#### Required Flags
 
-#### OpenAPI Flags
-- `--openapi-format` (default: `json`)
-- `--openapi-title`
-- `--openapi-version` (default: `0.0.0`)
-- `--openapi-description`
-- `--openapi-servers` (default: `/`)
-- `--openapi-base-path`
-- `--openapi-path-style` (default: `kebab`)
-- `--openapi-method` (default: `post`)
-- `--openapi-tag-style` (default: `default`)
-- `--openapi-closed-schemas` (default: `false`)
-- `--openapi-prune-unused-schemas` (default: `false`)
-- `--openapi-envelope-namespace` (default: `ResponseEnvelope`)
-- `--openapi-error-namespace` (default: `ErrorObject`)
-- `--openapi-validate` (default: `true`)
-- `--openapi-security-config-file`
-- `--openapi-tags-file`
-- `--openapi-ops-file`
+| Flag                | Description                              |
+|---------------------|------------------------------------------|
+| `--wsdl-source`     | Path or URL to the WSDL file             |
+| `--catalog-file`    | Output path for `catalog.json`           |
 
-#### Gateway Flags
-- `--gateway-service-name` (required if `--gateway-dir` provided)
-- `--gateway-version-prefix` (required if `--gateway-dir` provided)
-- `--gateway-default-status-codes`
+#### Optional Flags
 
-### Examples
+| Flag                               | Default        | Description                                                  |
+|------------------------------------|----------------|--------------------------------------------------------------|
+| `--import-extensions`              | `js`           | Import specifier style: `js`, `ts`, or `bare`                |
+| `--client-attributes-key`          | `$attributes`  | Attribute bag key for runtime mapper                         |
+| `--client-class-name`              | (derived)      | Override generated client class name                         |
+| `--client-int64-as`                | `string`       | Map 64-bit integers: `string`, `number`, or `bigint`         |
+| `--client-bigint-as`               | `string`       | Map arbitrary-size integers: `string` or `number`            |
+| `--client-decimal-as`              | `string`       | Map `xs:decimal`: `string` or `number`                       |
+| `--client-date-as`                 | `string`       | Map date/time types: `string` or `Date`                      |
+| `--client-choice-mode`             | `all-optional` | Choice element strategy: `all-optional` or `union`           |
+| `--client-fail-on-unresolved`      | `false`        | Fail build on unresolved type references                     |
+| `--client-nillable-as-optional`    | `false`        | Treat nillable elements as optional properties               |
+
+#### Examples
 
-#### Complete Stack Generation (Using Default Catalog Location)
+**Basic Compilation:**
 
 ```bash
-npx wsdl-tsc pipeline \
+npx wsdl-tsc compile \
   --wsdl-source examples/minimal/weather.wsdl \
-  --client-dir tmp/client \
-  --openapi-file tmp/openapi.json \
-  --gateway-dir tmp/gateway \
-  --gateway-service-name weather \
-  --gateway-version-prefix v1
+  --catalog-file tmp/catalog.json
 ```
 
-**Output**: Catalog at `tmp/client/catalog.json`.
-
-#### Client + OpenAPI Only
+**With Custom Mapping Options:**
 
 ```bash
-npx wsdl-tsc pipeline \
+npx wsdl-tsc compile \
   --wsdl-source https://example.com/Hotel.wsdl \
-  --client-dir ./build/client \
-  --openapi-file ./docs/hotel-api.json \
-  --openapi-format both
+  --catalog-file ./build/hotel-catalog.json \
+  --client-int64-as number \
+  --client-decimal-as string
 ```
 
-**Output**: Catalog at `./build/client/catalog.json`.
-
-#### OpenAPI + Gateway Only
+**For Debugging:**
 
 ```bash
-npx wsdl-tsc pipeline \
-  --wsdl-source ./wsdl/Booking.wsdl \
-  --openapi-file ./docs/booking-api.json \
-  --gateway-dir ./build/gateway \
-  --gateway-service-name booking \
-  --gateway-version-prefix v1
+# Compile to inspect types and operations
+npx wsdl-tsc compile \
+  --wsdl-source ./wsdl/ComplexService.wsdl \
+  --catalog-file ./debug/catalog.json \
+  --client-fail-on-unresolved false
+
+# Inspect types
+cat ./debug/catalog.json | jq '.types'
+
+# Inspect operations
+cat ./debug/catalog.json | jq '.operations'
 ```
 
-**Output**: Catalog at `./docs/catalog.json`.
+#### Output
 
-#### With Custom Catalog Path
+- `catalog.json` - Compiled schema representation including types, operations, and metadata
 
-```bash
-npx wsdl-tsc pipeline \
-  --wsdl-source ./wsdl/Booking.wsdl \
-  --catalog-file ./build/shared/catalog.json \
-  --client-dir ./build/client \
-  --openapi-file ./docs/booking-api.json \
-  --gateway-dir ./build/gateway \
-  --gateway-service-name booking \
-  --gateway-version-prefix v1
-```
+#### Catalog Structure
 
-#### With Full Configuration
+The catalog.json file contains the compiled WSDL representation:
 
-```bash
-npx wsdl-tsc pipeline \
-  --wsdl-source ./wsdl/Booking.wsdl \
-  --client-dir ./build/client \
-  --openapi-file ./docs/booking-api \
-  --gateway-dir ./build/gateway \
-  --openapi-format both \
-  --openapi-servers https://api.example.com/v1 \
-  --openapi-base-path /booking \
-  --openapi-security-config-file ./config/security.json \
-  --gateway-service-name booking \
-  --gateway-version-prefix v1 \
-  --client-int64-as number \
-  --client-decimal-as string
+```json
+{
+  "wsdlUri": "path/to/service.wsdl",
+  "targetNamespace": "http://example.com/service",
+  "serviceName": "WeatherService",
+  "types": [
+    {
+      "name": "GetWeatherRequest",
+      "properties": []
+    }
+  ],
+  "operations": [
+    {
+      "name": "GetWeather",
+      "input": "GetWeatherRequest",
+      "output": "GetWeatherResponse"
+    }
+  ],
+  "options": {
+    "imports": "js",
+    "catalog": true
+  }
+}
 ```
 
-**Output**: Catalog at `./build/client/catalog.json`.
+**Key sections**:
+- `types` - All compiled type definitions with properties and inheritance
+- `operations` - SOAP operations with input/output type references
+- `options` - Compiler options used during generation
 
-### Pipeline Workflow
+This catalog can be reused with the `client` and `openapi` commands via `--catalog-file`.
 
-The pipeline command executes these steps in order:
+#### Catalog Co-location
 
-1. **Parse WSDL** → Load and validate WSDL document
-2. **Compile Catalog** → Generate intermediate representation
-3. **Emit Catalog** → Write `catalog.json` (always)
-4. **Generate Client** → Emit TypeScript client files (if `--client-dir`)
-5. **Generate OpenAPI** → Create OpenAPI spec (if `--openapi-file`)
-6. **Generate Gateway** → Create Fastify gateway code (if `--gateway-dir`)
+**Default behavior**: Catalog files are **co-located** with their primary output files for better organization and discoverability.
 
-All steps share the same parsed WSDL and compiled catalog, ensuring consistency.
+**Catalog Location by Command**:
+- `compile`: Always requires explicit `--catalog-file` (no default)
+- `client`: Defaults to `{client-dir}/catalog.json`
+- `openapi`: Defaults to `{openapi-file-dir}/catalog.json`
+- `pipeline`: Intelligent cascade - first available: `{client-dir}` > `{openapi-dir}` > `{gateway-dir}` > `tmp/`
+
+**Common patterns**:
+
+1. **Co-located with client** (recommended for most projects):
+   ```bash
+   npx wsdl-tsc client --wsdl-source service.wsdl --client-dir src/services/weather
+   ```
+   
+   Creates `src/services/weather/catalog.json` automatically.
+
+2. **Shared catalog for multiple commands** (custom location):
+   ```bash
+   npx wsdl-tsc compile --wsdl-source service.wsdl --catalog-file build/shared-catalog.json
+   npx wsdl-tsc client --catalog-file build/shared-catalog.json --client-dir src/client
+   npx wsdl-tsc openapi --catalog-file build/shared-catalog.json --openapi-file docs/api.json
+   ```
 
 ---
 
-## 10. Working With Generated Clients
+## Working With Generated Clients
 
 ### Client Construction
 
@@ -1109,7 +1598,7 @@ result.GetCityWeatherByZIPResult.Temperature;  // number | string (depends on ma
 
 ---
 
-## 11. OpenAPI Configuration
+## Configuration Files
 
 ### Security Configuration (`security.json`)
 
@@ -1168,7 +1657,106 @@ Per-operation overrides for method, summary, description, and deprecation:
 
 ---
 
-## 12. Programmatic API
+## Production Concerns
+
+### Deterministic Output Guarantees
+
+All generated code and specifications have **stable, deterministic ordering** for version control:
+
+- ✅ **TypeScript files**: Sorted type declarations, imports, and exports
+- ✅ **OpenAPI specs**: Sorted paths, HTTP methods, schemas, parameters, security schemes, tags
+- ✅ **JSON Schemas**: Sorted property keys and component names
+- ✅ **Gateway routes**: Alphabetically organized route files
+- ✅ **Catalog JSON**: Consistent ordering of types and operations
+
+**Benefit**: Safe regeneration in CI/CD without spurious diffs.
+
+### Validation Behavior
+
+**OpenAPI Validation** (enabled by default):
+- Uses `@apidevtools/swagger-parser`
+- Validates schema structure
+- Resolves all `$ref` references
+- Catches missing schemas and circular dependencies
+- Disable with `--openapi-validate false`
+
+**Gateway Contract Validation**:
+- All request/response bodies must use `$ref` to `components.schemas`
+- Every operation must have a default response with `application/json` content
+- All referenced schemas must exist in `components.schemas`
+
+### Error Handling
+
+**Gateway Error Classification**:
+
+| Error Type            | HTTP Status | Error Code            | When It Occurs                        |
+|-----------------------|-------------|-----------------------|---------------------------------------|
+| Validation errors     | 400         | `VALIDATION_ERROR`    | Request doesn't match JSON Schema     |
+| SOAP faults           | 502         | `SOAP_FAULT`          | SOAP service returned a fault         |
+| Connection refused    | 503         | `SERVICE_UNAVAILABLE` | Cannot reach SOAP endpoint            |
+| Timeout               | 504         | `GATEWAY_TIMEOUT`     | SOAP request exceeded timeout         |
+| Other errors          | 500         | `INTERNAL_ERROR`      | Unexpected errors                     |
+
+All errors are wrapped in the standard envelope format with `error` object populated.
+
+### SOAP Wire Logging
+
+Enable SOAP request/response debugging:
+
+```bash
+NODE_DEBUG=soap node app.js
+```
+
+This logs full XML request/response payloads to console.
+
+### CI/CD Tips
+
+**Caching Strategy:**
+
+```bash
+# Step 1: Compile catalog (cacheable artifact)
+npx wsdl-tsc compile \
+  --wsdl-source ./wsdl/Service.wsdl \
+  --catalog-file ./build/catalog.json
+
+# Step 2: Generate code from cached catalog
+npx wsdl-tsc client --catalog-file ./build/catalog.json --client-dir ./src/client
+npx wsdl-tsc openapi --catalog-file ./build/catalog.json --openapi-file ./docs/api.json
+```
+
+**Recommended Build Script** (`package.json`):
+
+```json
+{
+  "scripts": {
+    "generate": "npx wsdl-tsc pipeline --wsdl-source ./wsdl/service.wsdl --client-dir ./src/client --openapi-file ./docs/api.json --gateway-dir ./src/gateway --gateway-service-name svc --gateway-version-prefix v1",
+    "build": "npm run generate && tsc",
+    "typecheck": "tsc --noEmit"
+  }
+}
+```
+
+### Known Limitations
+
+**Choice Elements**:
+- Current strategy: `all-optional` (all branches optional)
+- Future: Discriminated union support (planned)
+
+**Union Types**:
+- Experimental `--client-choice-mode union` available
+- May require manual refinement for complex patterns
+
+**WS-Policy**:
+- Security hints extracted from policies
+- Custom policies may require manual security configuration
+
+**Array Wrapper Flattening**:
+- Single-child sequences with `maxOccurs>1` become array schemas
+- Sequences with multiple children preserve wrapper
+
+---
+
+## Programmatic API
 
 All CLI commands are available as TypeScript functions for programmatic usage.
 
@@ -1435,7 +2023,7 @@ interface PipelineOptions {
 
 ---
 
-## 13. Advanced Topics
+## Advanced Topics
 
 ### Primitive Mapping Philosophy
 
@@ -1510,7 +2098,7 @@ Disable with `--openapi-validate false` or `validate: false` in API.
 
 ---
 
-## 14. Troubleshooting
+## Troubleshooting
 
 ### Common Issues
 
@@ -1591,7 +2179,7 @@ The catalog is automatically placed at `./src/services/hotel/catalog.json`.
 
 ---
 
-## 15. Contributing
+## Contributing
 
 We welcome contributions! Here's how to get started:
 
@@ -1665,7 +2253,7 @@ See also: [CONTRIBUTING.md](CONTRIBUTING.md), [CODE_OF_CONDUCT.md](CODE_OF_CONDU
 
 ---
 
-## 16. License
+## License
 
 MIT © TechSpokes
 
@@ -1675,7 +2263,7 @@ See [LICENSE](LICENSE) for full text.
 
 ---
 
-## 17. Sponsors
+## Sponsors
 
 Support ongoing development and maintenance: