@workos/oagen 0.0.1

package/skills/generate-sdk/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: generate-sdk
+description: Orchestrate generating an SDK for a target language end-to-end. Determines the right scenario (backwards-compatible or fresh) and guides through the correct sequence of sub-skills. Use when the user wants to generate an SDK, add a new language, create SDK bindings, start a new language target, or asks "how do I add X support". Also triggers for "new SDK", "language support", or "scaffold SDK".
+---
+
+# /generate-sdk
+
+## Overview
+
+Orchestrate the end-to-end workflow for generating an SDK for a target language. This skill does not implement anything itself — it determines the right scenario, sequences the correct skills, and tracks progress across steps.
+
+## Inputs
+
+- **language** — target language (e.g., `ruby`, `python`, `node`, `go`)
+- **scenario** — `A` (backwards-compatible with existing SDK) or `B` (fresh, no existing SDK)
+- **project** — path to the emitter project
+- **spec** — path to the OpenAPI spec
+- **sdk_path** — path to the live SDK (Scenario A only)
+
+## Reference Docs
+
+- [Workflows](../../docs/architecture/workflows.md) — Phase 1 setup vs. Phase 2 ongoing spec updates
+- [Pipeline](../../docs/architecture/pipeline.md) — three-stage parse/emit/write flow
+
+## Architecture
+
+Emitters, extractors, smoke tests, and their unit tests all live in the **emitter project**, not in the oagen core repo. The emitter project depends on `@workos/oagen` for types and shared utilities.
+
+## Context Management
+
+Sub-skills use **subagents** (via the built-in `Explore` agent type) to keep the main context lean. Read-heavy exploration — studying existing SDKs, reading reference implementations — is delegated to isolated agents that return only structured summaries. This prevents context rot during the write-heavy generation steps that follow.
+
+Each sub-skill documents where it uses subagents:
+
+- `/generate-emitter` — Step 1a (SDK exploration) and Steps 3-5 (reference emitter reading)
+- `/generate-extractor` — Prerequisites (SDK exploration)
+- `/generate-smoke-test` — Prerequisites (reference smoke script reading) and Step 2 (SDK SERVICE_MAP)
+- `/verify-compat` — Step 1 (baseline extraction spot-check)
+
+## Step 1: Gather Inputs
+
+Collect these values via `AskUserQuestion`. If any were provided as arguments, skip the corresponding question.
+
+1. **`language`** — target language (e.g., `ruby`, `python`, `php`, `node`)
+2. **`scenario`** — which workflow to use:
+   > **A. Backwards compatible** — There's a published SDK with consumers who depend on its public API. The generated SDK must match the existing surface.
+   >
+   > **B. Fresh** — No existing SDK to preserve, or you're intentionally replacing one. No compat constraints.
+3. **`sdk_path`** _(Scenario A only)_ — path to the existing SDK. Validate the path exists (look for `package.json`, `Gemfile`, `go.mod`, `pyproject.toml`, or similar).
+4. **`project`** — emitter project path (e.g., `../oagen-emitters/node`). Create if needed:
+   ```bash
+   mkdir -p {project}/src/{language} && mkdir -p {project}/test/{language}
+   ```
+5. **`spec`** — path to the OpenAPI spec (e.g., `../openapi.yaml`)
+
+Store all values and pass them to all sub-skill invocations.
+
+## Step 2: Present the Plan
+
+### Scenario A — Backwards compatible
+
+```
+Step 1: /generate-emitter {language} {project} sdk_path={sdk_path}    — study existing SDK, scaffold emitter
+Step 2: /generate-extractor {language} sdk_path={sdk_path}            — scaffold extractor
+Step 3: /verify-compat {language} sdk_path={sdk_path}                 — extract baseline, verify
+Step 4: /generate-smoke-test {language}                               — smoke tests against output dir
+Step 5: /verify-smoke-test {language}                                 — iterate until clean
+Step 6: /integrate {language} sdk_path={sdk_path}                     — merge into live SDK
+```
+
+### Scenario B — Fresh
+
+```
+Step 1: /generate-emitter {project} {language}    — scaffold emitter
+Step 2: /generate-smoke-test {language}            — wire-level HTTP parity tests
+Step 3: /verify-smoke-test {language}              — run smoke tests
+```
+
+> **Lifecycle note:** Scenario B is a one-time bootstrap. Once the generated SDK ships, it becomes the live SDK. All future spec updates follow Scenario A — use `--target` to integrate into the live SDK and `--api-surface` to preserve backwards compatibility.
+
+Confirm with the user, then invoke the first skill.
+
+## Step 3: Run Skills in Sequence
+
+Invoke each skill in order using the `Skill` tool, passing `project` through. After each skill, validate:
+
+```bash
+# After /generate-emitter — design doc, entry point, and tests
+ls {project}/docs/sdk-architecture/{language}.md
+ls {project}/src/{language}/index.ts
+cd {project} && npx vitest run test/{language}/ 2>&1 | tail -5
+
+# After /generate-extractor — extractor registered with hints
+grep -l "{language}Extractor\|{language}_extractor" {project}/oagen.config.ts
+grep -l "hints" {project}/src/compat/extractors/{language}.ts
+
+# After /verify-compat — handled by the skill itself
+
+# After /generate-smoke-test — script exists
+ls {project}/smoke/sdk-{language}.ts
+
+# After /verify-smoke-test — handled by the skill itself
+
+# After /integrate — changes visible in live SDK
+cd {sdk_path} && git diff --stat
+```
+
+**For Scenario A:** After `/generate-emitter`, also verify the design doc references real SDK patterns:
+
+```bash
+grep -c "existing SDK\|from src/" {project}/docs/sdk-architecture/{language}.md
+```
+
+If a skill fails or the user wants to pause, note where they stopped. They can resume by running the remaining skills individually.
+
+## Step 4: Final Checklist
+
+Run the full validation suite:
+
+```bash
+cd {project} && npx vitest run    # emitter project
+npx tsc --noEmit                  # oagen core type check
+npx tsup                          # oagen core build
+```
+
+Then present the summary:
+
+```
+=== {language} SDK support: COMPLETE ===
+
+Scenario: {A/B}
+Skills completed:
+  [x] /generate-emitter {language}
+  [x] /generate-extractor {language}     (Scenario A only)
+  [x] /verify-compat {language}          (Scenario A only)
+  [x] /integrate {language}              (Scenario A only)
+  [x] /generate-smoke-test {language}
+
+Validation:
+  Emitter tests:    {N} passed, {N} failed
+  Type check:       PASS/FAIL
+  Build:            PASS/FAIL
+```
+
+Only include this next section in the output if this is Scenario A:
+
+## Output
+
+This skill produces, via its sub-skills:
+
+- A complete language emitter registered in `oagen.config.ts`
+- An API surface extractor (Scenario A only)
+- A smoke test script at `smoke/sdk-{language}.ts`
+- Generated SDK code at `{project}/sdk/`
+- Integration into the live SDK (Scenario A only)

package/skills/generate-smoke-test/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: generate-smoke-test
+description: Create a smoke test script for a new SDK language that verifies wire-level HTTP parity against the OpenAPI spec and live API baseline. Use when adding smoke tests for a new language, verifying a generated SDK against the real API, or checking HTTP request/response correctness. Also triggers for "integration test", "wire-level test", "HTTP parity", or "end-to-end SDK test".
+---
+
+# /generate-smoke-test
+
+Create a self-contained smoke test script for a new SDK language that captures wire-level HTTP request/response pairs and compares them against the raw API baseline or spec-only baseline.
+
+## Overview
+
+Each language's smoke test is a single file: `smoke/sdk-{lang}.ts` **in the emitter project**. It uses the target language's native HTTP interception to capture what the SDK actually sends over the wire, then outputs `SmokeResults` JSON. The diff tool compares this against a baseline and reports mismatches by severity.
+
+The script is self-contained — no proxy, no subprocess protocol, no separate driver. It imports shared infrastructure from `@workos/oagen/smoke` and implements language-specific parts inline.
+
+## Resolve Paths
+
+**Emitter project:** Use the `project` argument if provided, otherwise use `AskUserQuestion`.
+
+**oagen core:** Check for `node_modules/@workos/oagen/`, or `src/engine/types.ts` in the current directory, otherwise ask.
+
+## Prerequisites
+
+Read and understand these files before writing any code:
+
+1. **`@workos/oagen/smoke`** (exported from `{oagen}/scripts/smoke/shared.ts`) — `parseSpec()`, `planOperations()`, `generatePayload()` / `generateCamelPayload()`, `generateQueryParams()` / `generateCamelQueryParams()`, `IdRegistry`, `getExpectedStatusCodes()` / `isUnexpectedStatus()`, `resolvePath()`, `CapturedExchange`, `SmokeResults`
+
+2. **Existing smoke scripts (read via subagent)** — Use the `Agent` tool with `subagent_type: Explore` to study the closest existing smoke script. This keeps ~630+ lines of reference source out of the main context:
+
+   > Read the smoke scripts in `{emitterProject}/smoke/` (e.g., `sdk-node.ts`, `sdk-ruby.ts`). For the closest one to {language}, return: purpose, exported function signatures, structural pattern (setup → intercept → iterate → capture → cleanup), key abstractions (MethodResolution, SERVICE_MAP, interceptFetch, buildArgs), and which parts are language-specific vs. reusable. Be concise.
+
+   The Node script is the canonical reference (~630 lines) covering:
+   - `MethodResolution` interface and 4-tier resolution: manifest, exact match, CRUD prefix, keyword fuzzy
+   - `SERVICE_MAP` — IR service names to SDK property names
+   - `interceptFetch()` — HTTP interception with provenance capture
+   - `buildArgs()` — argument construction from IR operations
+
+3. **`{oagen}/scripts/smoke/raw.ts`** — raw baseline script
+4. **`{oagen}/scripts/smoke/diff.ts`** — diff tool severity levels (CRITICAL/WARNING/INFO)
+5. **`docs/sdk-architecture/{language}.md`** (in emitter project) — target language patterns and HTTP client
+
+## Resolve Spec Path
+
+Determine the location of the OpenAPI spec before doing anything:
+
+1. If the `spec` argument was provided, use that.
+2. Otherwise, use `AskUserQuestion`: "Where is your OpenAPI spec located? (absolute or relative path, e.g. `../openapi.yaml`)"
+
+Store it as `spec`.
+
+## Step 1: Determine HTTP Interception Strategy
+
+The interception must capture the raw request (method, path, query params, body) and raw response (status, body). Choose based on the target language's SDK:
+
+- **Node:** Patch `globalThis.fetch`
+- **Ruby:** WebMock `stub_request` or monkey-patch `Net::HTTP`
+- **Python:** `responses`, `respx` (for httpx), or `unittest.mock.patch`
+- **Go:** Custom `http.RoundTripper`
+- **Java/Kotlin:** OkHttp `Interceptor`
+
+The interception code is typically ~20-30 lines. It must capture the request as-sent, let the real HTTP call proceed, capture the response, and store both in a `currentCapture` variable.
+
+## Step 2: Build the SERVICE_MAP
+
+Map IR service names to SDK resource accessors. There are two sources of truth depending on the SDK:
+
+### Generated SDK (preferred)
+
+For emitter-generated SDKs, the `smoke-manifest.json` (produced by the emitter's `generateManifest` hook) contains the authoritative `service` field for every operation. The smoke test should load this manifest and use its service mappings. The `SERVICE_MAP` only needs fallback entries for services not covered by the manifest.
+
+If no manifest exists, warn the user: the emitter should implement `generateManifest`. Without it, most operations will be skipped because heuristic method resolution fails on disambiguated names.
+
+### Live/hand-written SDK
+
+If `sdk_path` points to a hand-written SDK (not emitter-generated), **delegate the exploration to a subagent** to discover accessor names:
+
+Use the `Agent` tool with `subagent_type: Explore` and a prompt like:
+
+> Explore the SDK at `{sdk_path}`. Focus specifically on: the main client class, its resource accessor properties/methods, and how they map to domain names. Return a mapping of resource names to accessor names (e.g., Organizations → "organizations", Connections → "sso"). Only report what you actually find.
+
+Then build the mapping:
+
+```typescript
+const SERVICE_MAP: Record<string, string> = {
+  Organizations: "organizations",
+  Connections: "sso",
+};
+```
+
+Each language's SDK will have different accessor names — discover them by reading the SDK's client class.
+
+## Step 3: Implement SDK Method Resolution
+
+Adapt the 4-tier resolution to the target language's naming conventions:
+
+0. **Manifest match** — Load `smoke-manifest.json` from the SDK output directory (emitter-generated, not hand-maintained). This is the **primary** resolution path for generated SDKs. The manifest maps every `HTTP_METHOD /path` to `{ sdkMethod, service }` and is produced by the emitter's `generateManifest` hook. If the manifest is missing, warn and fall through to heuristic tiers.
+1. **Exact match** — IR operation name converted to target convention
+2. **CRUD prefix match** — standard verbs (create, list, retrieve/get, update, delete) with service name tiebreaker
+3. **Keyword fuzzy match** — stem words and score overlap
+
+Key convention differences: Ruby/Python use `snake_case`, Go uses `PascalCase`, Node uses `camelCase`.
+
+Each resolution records provenance metadata (`ExchangeProvenance`) so findings can be traced back to the resolution path.
+
+## Step 4: Implement Argument Construction
+
+Build SDK call arguments from IR operations (reference `buildArgs()` in existing smoke scripts):
+
+- No path params + has body → `method(payload)`
+- No path params + has query params → `method(queryOpts)`
+- Single path param, no body/query → `method(id)` (positional)
+- Complex (path params + body/query) → `method(mergedOptions)`
+- Idempotent POST → append empty options object for idempotency key
+
+Choose the right payload convention: Node uses `generateCamelPayload()`, Ruby/Python may use `generatePayload()` directly (snake_case).
+
+## Step 5: Write `smoke/sdk-{lang}.ts`
+
+Create the script **in the emitter project**:
+
+1. Imports from `@workos/oagen/smoke`
+2. HTTP interception setup
+3. `main()` function:
+   - Parse CLI args, validate API key
+   - Parse spec via `parseSpec()`
+   - Load manifest from `{sdk-path}/smoke-manifest.json` (emitter-generated). If missing, log a warning — method resolution will rely on heuristic tiers and most operations will likely be skipped.
+   - Load and configure the SDK
+   - Iterate `planOperations()` groups
+   - For each operation: resolve SDK method, resolve path params, build args, call SDK, capture exchange
+   - Extract IDs via `ids.extractAndStore()`
+   - Track POST creates for cleanup
+   - Cleanup created entities in reverse
+   - Restore original HTTP behavior
+   - Write `smoke-results-sdk-{lang}.json`
+4. Summary output (successes, errors, skipped, unexpected statuses)
+
+## Step 6: Register the Smoke Runner
+
+Add to `oagen.config.ts`:
+
+```typescript
+const config: OagenConfig = {
+  emitters: [/* ... */],
+  smokeRunners: {
+    {language}: './smoke/sdk-{language}.ts',
+  },
+};
+```
+
+## Step 7: Validate
+
+```bash
+# Offline validation against spec baseline (no API key needed)
+oagen verify --lang {lang} --output {sdk-path} --spec <spec>
+
+# Live validation against real API (requires API key and raw baseline)
+oagen verify --lang {lang} --output {sdk-path} --raw-results smoke-results-raw.json
+```
+
+## Emitter-Fixing Loop
+
+During initial setup, run `oagen generate` then the smoke test until skips are minimized:
+
+```bash
+oagen generate --lang {lang} --output {sdk-path} --spec {spec} --namespace {ns}
+# The emitter produces smoke-manifest.json alongside the SDK — the smoke test loads it automatically.
+oagen verify --lang {lang} --output {sdk-path} --spec {spec}
+```
+
+If many operations are skipped with "No matching SDK method", check that the emitter's `generateManifest` is implemented and that the manifest file is being written to the SDK output directory. The manifest is the primary mechanism the smoke test uses to find SDK methods.
+
+| Exit | Meaning       | Output                      | Action                                  |
+| ---- | ------------- | --------------------------- | --------------------------------------- |
+| 0    | Clean         | —                           | Done                                    |
+| 1    | Findings      | `smoke-diff-findings.json`  | Read findings, fix emitter/smoke script |
+| 2    | Compile error | `smoke-compile-errors.json` | Read errors, fix emitter                |
+
+See `scripts/smoke/README.md` (in oagen core) for the full remediation guide. See [Workflows](../../docs/architecture/workflows.md) for the overall workflow diagram.
+
+## Output
+
+This skill produces, in the emitter project:
+
+- `smoke/sdk-{language}.ts` — self-contained smoke test script
+- Updated `oagen.config.ts` with the smoke runner path registered

package/skills/integrate/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: integrate
+description: Integrate generated SDK code into a live SDK by running `oagen generate --target`. Required for every Scenario A generation cycle — initial setup and ongoing spec updates. Use when the user wants to merge generated code into an existing SDK or integrate emitter output into a live codebase.
+---
+
+# /integrate
+
+## Purpose
+
+Integrate generated SDK code into a live SDK by running `oagen generate --target`. This runs every time code is generated for a live SDK, not just once — both during initial setup and on every subsequent spec update. The writer's additive merge makes it safe to run on every regeneration.
+
+## Reference Docs
+
+- [Pipeline Architecture](../../docs/architecture/pipeline.md) — how the writer's additive merge works
+- [Workflows](../../docs/architecture/workflows.md) — where `/integrate` fits in the overall workflow
+- [Emitter Contract](../../docs/architecture/emitter-contract.md) — overlay integration and `skipIfExists`
+
+## Prerequisites
+
+Before integration:
+
+1. **Verify-compat must have passed** — check for an existing API surface file (`sdk-{language}-surface.json` in the emitter project). If missing, suggest running `/verify-compat` first.
+2. **The emitter should use `fileBySymbol` hints** for correct file placement — this ensures generated files land at the paths the live SDK expects.
+
+## Step 1: Resolve Paths
+
+Determine required paths:
+
+- **Language**: from argument, or use `AskUserQuestion`
+- **Live SDK path** (`sdk_path`): from argument, or use `AskUserQuestion`: "Where is the live SDK? (absolute or relative path)"
+- **OpenAPI spec** (`spec`): from argument, `OPENAPI_SPEC_PATH` env var, or use `AskUserQuestion`
+- **Emitter project** (`project`): from argument, or detect from current directory
+- **Output directory** (`output`): use a temp directory or the emitter project's `sdk/` directory
+- **API surface** (`api_surface`): `sdk-{language}-surface.json` in the emitter project
+- **Manifest** (`manifest`): `smoke-manifest.json` in the output directory (if it exists)
+
+## Step 2: Dry-Run Preview
+
+Run `oagen generate` with `--dry-run` and `--target` to show what will happen:
+
+```bash
+npx tsx src/cli/index.ts generate \
+  --spec {spec} \
+  --lang {language} \
+  --output {output} \
+  --target {sdk_path} \
+  --namespace {namespace} \
+  --api-surface {api_surface} \
+  --manifest {manifest} \
+  --dry-run
+```
+
+Present the output to the user. The dry-run shows:
+
+- Files that would be written to the output directory
+- Files that would be written/merged/skipped in the target directory
+
+## Step 3: Confirm and Execute
+
+Use `AskUserQuestion` to confirm:
+
+> "The above files will be written to `{output}` and integrated into `{sdk_path}`. Proceed?"
+
+On confirmation, run without `--dry-run`:
+
+```bash
+npx tsx src/cli/index.ts generate \
+  --spec {spec} \
+  --lang {language} \
+  --output {output} \
+  --target {sdk_path} \
+  --namespace {namespace} \
+  --api-surface {api_surface} \
+  --manifest {manifest}
+```
+
+## Step 4: Post-Integration Verification
+
+Suggest running the live SDK's test suite:
+
+```bash
+cd {sdk_path} && npm test  # or equivalent for the target language
+```
+
+If tests fail, the merger's additive-only guarantees mean hand-written code was not modified — failures are likely from new symbols that need wiring up or import updates.
+
+## Step 5: Summary
+
+Report what happened:
+
+```
+=== Integration Complete ===
+Target: {sdk_path}
+New files created: {N}
+Existing files merged: {N}
+Files skipped: {N}
+
+Next steps:
+  - Review changes: cd {sdk_path} && git diff
+  - Run tests: cd {sdk_path} && npm test
+  - If needed, re-run /integrate after fixing issues
+```
+
+## Output
+
+- Generated files written to `{output}` directory
+- Files merged into the live SDK at `{sdk_path}` via the writer's additive merge
+- Summary report showing new files created, existing files merged, and files skipped

package/skills/verify-compat/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: verify-compat
+description: Verify that generated SDK code preserves backwards compatibility with a live SDK. Use when regenerating an SDK for a language that has an existing published SDK, checking for breaking changes, regressions, or API surface drift. Also triggers for "BC check", "backwards compatibility", "compat verification", "breaking change detection", "API surface comparison", or "regression check".
+---
+
+# /verify-compat
+
+Verify that generated SDK code preserves backwards compatibility with a live SDK's public API surface.
+
+## Overview
+
+The compat verification workflow extracts the public API surface from a live SDK, generates code with a compatibility overlay that preserves existing names, and then diffs the result against the baseline. Any regressions (renamed methods, changed signatures, missing exports) are reported as violations.
+
+This is the middle tier of the three-tier testing pyramid:
+
+- **Unit tests** — verify emitter logic in isolation
+- **Compat verification** — verify the API surface (names, signatures, exports) matches the live SDK
+- **Smoke tests** — verify wire-level HTTP behavior against the real API
+
+## Reference Docs
+
+- [Extractor Contract](../../docs/architecture/extractor-contract.md) — `Extractor` interface, `ApiSurface` type, Language Hints reference
+- [Workflows](../../docs/architecture/workflows.md) — where compat verification fits in the overall setup flow
+- Language hints: `src/compat/language-hints.ts` (`nodeHints`, `resolveHints`)
+- Node extractor (reference): `src/compat/extractors/node.ts`
+- Overlay logic: `src/compat/overlay.ts`
+- Differ: `src/compat/differ.ts`
+
+## Resolve oagen Core Path
+
+Check for `node_modules/@workos/oagen/`, or `src/engine/types.ts` in the current directory, otherwise ask.
+
+## Prerequisites
+
+- An emitter exists for `<language>` (run `/generate-emitter` first)
+- The live SDK is accessible at `--sdk-path` — must be the real, published SDK
+- An extractor exists for `<language>` (run `/generate-extractor` first), with `hints: LanguageHints` properly configured for the target language
+- The emitter has been run at least once to produce generated output
+- The emitter's design doc (`docs/sdk-architecture/{language}.md`) exists and documents the real SDK's patterns
+
+## Resolve Paths
+
+All artifacts (surface files, generated output) live **inside the emitter project** — never in `/tmp` or other throwaway locations. This ensures they persist across sessions and are available to convenience scripts.
+
+Determine required paths:
+
+1. **Emitter project** (`project`): from argument, or detect from CWD (look for `oagen.config.ts`), or use `AskUserQuestion`
+2. **Spec** (`spec`): from argument, or use `AskUserQuestion`
+3. **Live SDK** (`sdk_path`): from argument, or use `AskUserQuestion`
+4. **API surface file**: `{project}/sdk-{language}-surface.json` — always in the emitter project root
+5. **Generated output**: `{project}/sdk/` — a subdirectory of the emitter project
+
+**Validation**: The `sdk_path` MUST NOT be the same as or inside the output directory. If it is, reject it and ask again.
+
+## Step 1: Extract Baseline
+
+```bash
+oagen extract --sdk-path {sdk_path} --lang <language> --output {project}/sdk-{language}-surface.json
+```
+
+This produces `sdk-{language}-surface.json` in the **emitter project root** — the baseline snapshot of the live SDK's public API.
+
+**Gitignore it** — it's a derived artifact:
+
+```bash
+grep -q 'sdk-\*-surface.json' {project}/.gitignore 2>/dev/null || echo 'sdk-*-surface.json' >> {project}/.gitignore
+```
+
+**Verify the output via subagent:** Use the `Agent` tool with `subagent_type: Explore` to spot-check the extraction. This keeps the SDK's source out of the main context:
+
+> Explore the SDK at `{sdk_path}`. List all public classes and their public method names. Only report what you actually find — no assumptions.
+
+Compare the subagent's findings against `<output-path>/sdk-{language}-surface.json`. If the surface looks empty or incomplete, the extractor may need fixes — run `/generate-extractor` to debug.
+
+**Scope to API-relevant symbols:** The live SDK may export hand-written classes and interfaces that are not derivable from the OpenAPI spec (e.g., `CookieSession`, `PKCE`, `Webhooks`, signature verification utilities, HTTP client abstractions). These are out of scope for compat verification — the emitter isn't expected to generate them.
+
+After extraction, cross-reference the baseline surface against the OpenAPI spec's operations. Symbols that have no corresponding OpenAPI operation should be noted but excluded from the compat score. Report them separately so the user knows what's excluded:
+
+```
+Out of scope (not in OpenAPI spec): CookieSession, PKCE, Webhooks, ...
+In scope (API-derived): 280 classes, 1200 interfaces, ...
+```
+
+This prevents the compat score from being diluted by symbols the emitter can't possibly generate. The goal is to measure how well the emitter preserves the API surface, not how completely it replicates hand-written SDK features.
+
+## Step 2: Generate with Overlay
+
+```bash
+oagen generate --spec {spec} --lang <language> --output {project}/sdk --api-surface {project}/sdk-{language}-surface.json
+```
+
+The emitter receives the overlay via `EmitterContext` and uses it to preserve existing method names, class names, and type names where possible. The generated output goes to `{project}/sdk/`, not a temp directory.
+
+## Step 3: Verify
+
+**IMPORTANT:** Always include `--spec` so the comparison is scoped to spec-derivable symbols only. Without it, the score includes hand-written SDK features (webhooks, PKCE, etc.) that the emitter can't generate, producing a misleadingly low compat score.
+
+```bash
+oagen verify --spec {spec} --lang <language> --output {project}/sdk --api-surface {project}/sdk-{language}-surface.json
+```
+
+- **Exit 0** + preservation score = all clear
+- **Exit 1** + violations = review each violation (see Step 4)
+
+## Step 4: Interpret Results
+
+| Category           | Meaning                                                |
+| ------------------ | ------------------------------------------------------ |
+| `public-api`       | A public class, method, or type was renamed or removed |
+| `signature`        | A method's parameter list or return type changed       |
+| `export-structure` | A barrel export is missing or reorganized              |
+| `behavioral`       | A behavioral contract changed (e.g., async to sync)    |
+
+| Severity   | Action                                                             |
+| ---------- | ------------------------------------------------------------------ |
+| `breaking` | Must fix before shipping — this will break consumers               |
+| `warning`  | Review carefully — may be intentional but could surprise consumers |
+
+**For each violation:**
+
+1. Check `symbolPath` to locate the affected symbol
+2. Compare `baseline` vs `candidate` to understand the change
+3. Fix the emitter to preserve the baseline name/signature, OR
+4. If intentional, document it as a breaking change
+
+**When violations can't be auto-fixed:** Some violations indicate structural emitter issues (wrong method signature shape, missing exports). These require changing emitter code directly — the overlay loop can only fix naming mismatches, not structural problems. Read the violation details to determine whether this is an overlay issue or an emitter issue.
+
+## Step 5: Self-Correcting Loop
+
+Repeat Steps 2 and 3 until violations are resolved:
+
+```bash
+oagen generate --spec {spec} --lang <language> --output {project}/sdk --api-surface {project}/sdk-{language}-surface.json
+oagen verify --spec {spec} --lang <language> --output {project}/sdk --api-surface {project}/sdk-{language}-surface.json
+```
+
+Continue until either all violations are resolved (exit 0) or no further improvement is possible (fix the emitter manually).
+
+## When to Skip
+
+For languages where backwards compatibility isn't relevant (full rewrites, new SDKs), skip compat verification:
+
+```bash
+oagen generate --spec <spec> --lang <language> --output <path> --no-compat-check
+```
+
+## Output
+
+- `{project}/sdk-{language}-surface.json` — extracted API surface baseline
+- Generated SDK at `{project}/sdk/` with compat overlay applied
+- Violation report (exit 1) or clean pass (exit 0)