@workos/oagen 0.0.1

package/dist/verify/index.js

@@ -0,0 +1,336 @@
+import {
+  diffSpecs,
+  generate,
+  getEmitter
+} from "../chunk-P5XUDUGY.js";
+import {
+  buildOverlayLookup,
+  diffSurfaces,
+  filterSurface,
+  getExtractor,
+  patchOverlay,
+  specDerivedEnumValues,
+  specDerivedFieldPaths,
+  specDerivedMethodPaths,
+  specDerivedNames
+} from "../chunk-IJ5E5AE7.js";
+import {
+  CommandError
+} from "../chunk-CIX5NOBF.js";
+
+// src/verify/run-compat-check.ts
+async function runCompatCheck(baseline, outputDir, lang, spec) {
+  const extractor = getExtractor(lang);
+  const candidate = await extractor.extract(outputDir);
+  let scopedBaseline = baseline;
+  let scopedToSpec = false;
+  let scopedSymbolCount;
+  if (spec) {
+    const allowed = specDerivedNames(spec, extractor.hints);
+    const fieldPaths = specDerivedFieldPaths(spec, extractor.hints);
+    const methodPaths = specDerivedMethodPaths(spec);
+    const enumVals = specDerivedEnumValues(spec);
+    scopedBaseline = filterSurface(baseline, allowed, { fieldPaths, methodPaths, enumValues: enumVals });
+    scopedToSpec = true;
+    scopedSymbolCount = Object.keys(scopedBaseline.interfaces).length + Object.keys(scopedBaseline.classes).length + Object.keys(scopedBaseline.typeAliases).length + Object.keys(scopedBaseline.enums).length;
+  }
+  const diff = diffSurfaces(scopedBaseline, candidate, extractor.hints);
+  const passed = diff.violations.every((v) => v.severity !== "breaking");
+  return { passed, diff, scopedToSpec, scopedSymbolCount };
+}
+
+// src/verify/run-overlay-retry-loop.ts
+import { existsSync, readFileSync, readdirSync, unlinkSync, statSync, openSync, readSync, closeSync } from "fs";
+import * as path from "path";
+var PATCHABLE_CATEGORIES = /* @__PURE__ */ new Set(["public-api", "export-structure"]);
+var GENERATED_MARKERS = ["Code generated by oagen", "auto-generated by oagen", "This file is auto-generated"];
+function cleanGeneratedFiles(dir) {
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry);
+    let stat;
+    try {
+      stat = statSync(full);
+    } catch {
+      continue;
+    }
+    if (stat.isDirectory()) {
+      cleanGeneratedFiles(full);
+      continue;
+    }
+    if (entry.endsWith(".json") || entry.endsWith(".lock")) continue;
+    try {
+      const buf = Buffer.alloc(200);
+      const fd = openSync(full, "r");
+      try {
+        readSync(fd, buf, 0, 200, 0);
+      } finally {
+        closeSync(fd);
+      }
+      const header = buf.toString("utf-8");
+      if (GENERATED_MARKERS.some((m) => header.includes(m))) {
+        unlinkSync(full);
+      }
+    } catch {
+    }
+  }
+}
+function loadManifestFromDir(outputDir) {
+  const manifestPath = path.join(outputDir, "smoke-manifest.json");
+  if (!existsSync(manifestPath)) return void 0;
+  try {
+    const parsed = JSON.parse(readFileSync(manifestPath, "utf-8"));
+    if (Array.isArray(parsed)) return parsed;
+    if (typeof parsed === "object" && parsed !== null) {
+      return Object.entries(parsed).map(([httpKey, value]) => {
+        const spaceIdx = httpKey.indexOf(" ");
+        const httpMethod = httpKey.slice(0, spaceIdx);
+        const httpPath = httpKey.slice(spaceIdx + 1);
+        const v = value;
+        return {
+          operationId: "",
+          sdkResourceProperty: v.service ?? "",
+          sdkMethodName: v.sdkMethod ?? "",
+          httpMethod,
+          path: httpPath,
+          pathParams: [],
+          bodyFields: [],
+          queryFields: []
+        };
+      });
+    }
+  } catch {
+  }
+  return void 0;
+}
+async function runOverlayRetryLoop(opts) {
+  const { baseline, parsedSpec, outputDir, lang, maxRetries, namespace, onRetry } = opts;
+  const manifest = loadManifestFromDir(outputDir);
+  const extractor = getExtractor(lang);
+  let overlay = buildOverlayLookup(baseline, manifest, parsedSpec, extractor.hints);
+  let prevPreserved = -1;
+  const patchedPerIteration = [];
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const compatResult2 = await runCompatCheck(baseline, outputDir, lang, parsedSpec);
+    if (compatResult2.passed) {
+      return {
+        status: "passed",
+        attempts: attempt,
+        patchedPerIteration,
+        compatResult: compatResult2
+      };
+    }
+    if (attempt === maxRetries) {
+      return {
+        status: "max-retries",
+        attempts: attempt,
+        patchedPerIteration,
+        compatResult: compatResult2
+      };
+    }
+    const patchable = compatResult2.diff.violations.filter((v) => PATCHABLE_CATEGORIES.has(v.category));
+    if (patchable.length === 0) {
+      return {
+        status: "no-patchable",
+        attempts: attempt,
+        patchedPerIteration,
+        compatResult: compatResult2
+      };
+    }
+    const currentPreserved = compatResult2.diff.preservedSymbols;
+    if (attempt > 0 && currentPreserved <= prevPreserved) {
+      return {
+        status: "stalled",
+        attempts: attempt,
+        patchedPerIteration,
+        compatResult: compatResult2
+      };
+    }
+    prevPreserved = currentPreserved;
+    patchedPerIteration.push(patchable.length);
+    onRetry?.(attempt + 1, maxRetries, patchable.length);
+    overlay = patchOverlay(overlay, patchable, baseline);
+    cleanGeneratedFiles(outputDir);
+    const emitter = getEmitter(lang);
+    await generate(parsedSpec, emitter, {
+      namespace: namespace ?? parsedSpec.name,
+      outputDir,
+      overlayLookup: overlay,
+      apiSurface: baseline
+    });
+  }
+  const compatResult = await runCompatCheck(baseline, outputDir, lang, parsedSpec);
+  return {
+    status: "max-retries",
+    attempts: maxRetries,
+    patchedPerIteration,
+    compatResult
+  };
+}
+
+// src/compat/staleness.ts
+function detectStaleSymbols(liveSurface, oldSpec, newSpec, hints) {
+  const violations = [];
+  const oldNames = specDerivedNames(oldSpec, hints);
+  const newNames = specDerivedNames(newSpec, hints);
+  const removedNames = /* @__PURE__ */ new Set();
+  for (const name of oldNames) {
+    if (!newNames.has(name)) removedNames.add(name);
+  }
+  for (const name of removedNames) {
+    if (liveSurface.classes[name]) {
+      violations.push({
+        category: "staleness",
+        severity: "warning",
+        symbolPath: name,
+        baseline: name,
+        candidate: "(removed from spec)",
+        message: `Class "${name}" is no longer defined in the OpenAPI spec`
+      });
+    }
+    if (liveSurface.interfaces[name]) {
+      violations.push({
+        category: "staleness",
+        severity: "warning",
+        symbolPath: name,
+        baseline: name,
+        candidate: "(removed from spec)",
+        message: `Interface "${name}" is no longer defined in the OpenAPI spec`
+      });
+    }
+    if (liveSurface.typeAliases[name]) {
+      violations.push({
+        category: "staleness",
+        severity: "warning",
+        symbolPath: name,
+        baseline: name,
+        candidate: "(removed from spec)",
+        message: `Type alias "${name}" is no longer defined in the OpenAPI spec`
+      });
+    }
+    if (liveSurface.enums[name]) {
+      violations.push({
+        category: "staleness",
+        severity: "warning",
+        symbolPath: name,
+        baseline: name,
+        candidate: "(removed from spec)",
+        message: `Enum "${name}" is no longer defined in the OpenAPI spec`
+      });
+    }
+  }
+  const oldFieldPaths = specDerivedFieldPaths(oldSpec, hints);
+  const newFieldPaths = specDerivedFieldPaths(newSpec, hints);
+  for (const fieldPath of oldFieldPaths) {
+    if (newFieldPaths.has(fieldPath)) continue;
+    const [modelName, fieldName] = fieldPath.split(".");
+    if (removedNames.has(modelName)) continue;
+    const iface = liveSurface.interfaces[modelName];
+    if (iface?.fields[fieldName]) {
+      violations.push({
+        category: "staleness",
+        severity: "warning",
+        symbolPath: fieldPath,
+        baseline: fieldName,
+        candidate: "(removed from spec)",
+        message: `Field "${fieldPath}" is no longer defined in the OpenAPI spec`
+      });
+    }
+  }
+  const diff = diffSpecs(oldSpec, newSpec);
+  for (const change of diff.changes) {
+    if (change.kind === "operation-removed") {
+      const cls = liveSurface.classes[change.serviceName];
+      if (cls?.methods[change.operationName]) {
+        violations.push({
+          category: "staleness",
+          severity: "warning",
+          symbolPath: `${change.serviceName}.${change.operationName}`,
+          baseline: change.operationName,
+          candidate: "(removed from spec)",
+          message: `Method "${change.serviceName}.${change.operationName}" is no longer defined in the OpenAPI spec`
+        });
+      }
+    }
+  }
+  return violations;
+}
+
+// src/verify/run-staleness-check.ts
+function runStalenessCheck(baseline, oldSpec, newSpec, lang) {
+  const extractor = getExtractor(lang);
+  const violations = detectStaleSymbols(baseline, oldSpec, newSpec, extractor.hints);
+  return { violations };
+}
+
+// src/verify/run-smoke-check.ts
+import { execFileSync } from "child_process";
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { fileURLToPath } from "url";
+import * as path2 from "path";
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = path2.dirname(__filename);
+function resolveScript(scriptRelPath) {
+  const distScript = path2.resolve(__dirname, "..", "..", "dist", "scripts", scriptRelPath.replace(/\.ts$/, ".js"));
+  if (existsSync2(distScript)) {
+    return { bin: "node", script: distScript };
+  }
+  const srcScript = path2.resolve(__dirname, "..", "..", "scripts", scriptRelPath);
+  return { bin: "npx", script: srcScript };
+}
+function runPackagedScript(scriptRelPath, args) {
+  const { bin, script } = resolveScript(scriptRelPath);
+  const fullArgs = bin === "npx" ? ["tsx", script, ...args] : [script, ...args];
+  execFileSync(bin, fullArgs, { stdio: "inherit", env: process.env });
+}
+function runSmokeCheck(opts) {
+  const { spec, lang, output, rawResults, smokeConfig, smokeRunner } = opts;
+  let baselinePath = rawResults ?? "smoke-results-raw.json";
+  let generatedBaseline = false;
+  if (!rawResults && !existsSync2("smoke-results-raw.json")) {
+    if (!spec) {
+      throw new CommandError(
+        "error: --spec <path> or OPENAPI_SPEC_PATH env var is required when no raw baseline exists",
+        "",
+        1
+      );
+    }
+    try {
+      runPackagedScript("smoke/baseline.ts", ["--spec", spec]);
+    } catch {
+      throw new CommandError("Baseline generation failed", "", 1);
+    }
+    baselinePath = "smoke-results-spec-baseline.json";
+    generatedBaseline = true;
+  }
+  const smokeArgs = ["--lang", lang, "--sdk-path", output, "--raw-results", baselinePath];
+  if (spec) smokeArgs.push("--spec", spec);
+  if (smokeConfig) smokeArgs.push("--smoke-config", smokeConfig);
+  try {
+    if (smokeRunner) {
+      const bin = smokeRunner.endsWith(".ts") ? "npx" : "node";
+      const fullArgs = bin === "npx" ? ["tsx", smokeRunner, ...smokeArgs] : [smokeRunner, ...smokeArgs];
+      execFileSync(bin, fullArgs, { stdio: "inherit", env: process.env });
+    } else {
+      runPackagedScript("smoke/sdk-test.ts", smokeArgs);
+    }
+    return { passed: true, baselinePath, generatedBaseline };
+  } catch {
+    if (existsSync2("smoke-compile-errors.json")) {
+      return { passed: false, compileErrors: true, baselinePath, generatedBaseline };
+    }
+    const findingsCount = existsSync2("smoke-diff-findings.json") ? JSON.parse(readFileSync2("smoke-diff-findings.json", "utf-8")).length : void 0;
+    return { passed: false, findingsCount, baselinePath, generatedBaseline };
+  }
+}
+export {
+  runCompatCheck,
+  runOverlayRetryLoop,
+  runSmokeCheck,
+  runStalenessCheck
+};

package/docs/advanced/index.md

@@ -0,0 +1,11 @@
+# Advanced Docs
+
+These features are useful, but they are not required to adopt oagen as a framework.
+
+Use this section when you need to preserve an existing SDK surface, verify behavior with smoke tests, or integrate generated files into a live SDK tree.
+
+- [Workflows](../architecture/workflows.md)
+- [Extractor Contract](../architecture/extractor-contract.md)
+- [Non-Additive Changes](../architecture/non-additive-changes.md)
+- [`@oagen-ignore` — Preserving Hand-Written Code](./oagen-ignore.md)
+- [CLI Reference](../cli.md)

package/docs/advanced/oagen-ignore.md

@@ -0,0 +1,144 @@
+# `@oagen-ignore` — Preserving Hand-Written Code
+
+The `@oagen-ignore` system lets you protect hand-written code from being overwritten during regeneration. It operates at three scopes: docstring, region, and file.
+
+## Docstring-Level: `@oagen-ignore`
+
+Add `@oagen-ignore` anywhere inside a docstring to prevent the merger from overwriting it. The tag is a simple substring match — no regex, no parsing.
+
+### TypeScript
+
+```typescript
+/**
+ * Exchange an authorization code for a profile and access token.
+ *
+ * Auto-detects public vs confidential client mode:
+ * - If codeVerifier is provided: Uses PKCE flow (public client)
+ * - If no codeVerifier: Uses client_secret from API key (confidential client)
+ *
+ * @oagen-ignore
+ * @throws Error if neither codeVerifier nor API key is available
+ */
+async getProfileAndToken(...) { ... }
+```
+
+### Python
+
+```python
+def get_profile_and_token(self, ...):
+    """Exchange an authorization code for a profile and access token.
+
+    Auto-detects public vs confidential client mode.
+
+    @oagen-ignore
+    """
+```
+
+### Scope
+
+Protects:
+
+- **Top-level symbol docstrings** — classes, interfaces, type aliases, enums
+- **Member-level docstrings** — methods, fields, properties
+
+Applies in both merge modes (full merge and docstring-only).
+
+### Behavior
+
+- Matched via `text.includes('@oagen-ignore')`.
+- If the existing docstring contains `@oagen-ignore`, it is kept as-is regardless of what the generated output says.
+- If the existing symbol has no docstring at all, a generated docstring is still inserted (there's nothing to preserve).
+- Language-agnostic: works for any language whose merge adapter implements `extractDocstrings`.
+
+## Region-Level: `@oagen-ignore-start` / `@oagen-ignore-end`
+
+Wrap one or more symbols in a region to protect them from **both** deep merge (new members) and docstring refresh.
+
+### TypeScript
+
+```typescript
+// @oagen-ignore-start
+/**
+ * Hand-written SSO class with custom PKCE flow logic.
+ * The merger will not add new methods or update this docstring.
+ */
+export class SSO {
+  getProfileAndToken() {
+    /* custom implementation */
+  }
+}
+// @oagen-ignore-end
+
+// This class is NOT protected — normal merge rules apply
+export class Users {
+  list() {}
+}
+```
+
+### Python
+
+```python
+# @oagen-ignore-start
+class SSO:
+    """Hand-written SSO class."""
+
+    def get_profile_and_token(self):
+        """Custom PKCE flow."""
+        pass
+# @oagen-ignore-end
+```
+
+### Scope
+
+For each symbol whose declaration start falls within a region:
+
+- **Deep merge** is skipped — no new members are added
+- **Docstring refresh** is skipped — both top-level and member docstrings are preserved
+- **Top-level append** still works — new symbols outside the region are appended normally
+
+### Behavior
+
+- Markers are matched as literal substrings in comments. The comment style doesn't matter (`//`, `#`, `/* */`).
+- Regions are paired: each `@oagen-ignore-start` must have a matching `@oagen-ignore-end`. An unclosed start does **not** protect anything.
+- Multiple regions per file are supported.
+- New symbols (not present in the existing file) are still appended even if existing symbols are in ignored regions.
+
+## File-Level: `@oagen-ignore-file`
+
+Add `@oagen-ignore-file` anywhere in an existing file to prevent the writer from touching it at all. The file is completely skipped — no merge, no docstring refresh, no overwrite.
+
+### TypeScript
+
+```typescript
+// @oagen-ignore-file
+// This entire file is hand-maintained and should never be regenerated.
+
+export class CustomClient {
+  // ...
+}
+```
+
+### Python
+
+```python
+# @oagen-ignore-file
+
+class CustomClient:
+    """Fully hand-written client."""
+    pass
+```
+
+### Behavior
+
+- Only checked on **existing** files. A brand-new file is always written, even if the generated content contains `@oagen-ignore-file`.
+- Matched via `existingContent.includes('@oagen-ignore-file')`.
+- The file appears in `WriteResult.ignored` and is logged as `Ignored N files (@oagen-ignore-file)`.
+- Does not affect other files in the same batch.
+
+## Summary
+
+| Marker                                      | Scope     | Protects                                             |
+| ------------------------------------------- | --------- | ---------------------------------------------------- |
+| `@oagen-ignore`                             | Docstring | That specific docstring from overwrite               |
+| `@oagen-ignore-start` / `@oagen-ignore-end` | Region    | Enclosed symbols from deep merge + docstring refresh |
+| `@oagen-ignore-file`                        | File      | Entire file from any writer action                   |

package/docs/agents/architecture.md

@@ -0,0 +1,53 @@
+# Architecture And Core Contracts
+
+Use this guide when changing parsing, IR types, orchestration, file writing, or shared framework architecture.
+
+## Pipeline
+
+`OpenAPI spec -> Parser -> IR -> Emitter -> GeneratedFile[] -> Writer -> disk`
+
+Three stages transform an OpenAPI spec into SDK files:
+
+1. **Parse** (`src/parser/parse.ts`) — Load and bundle the spec via `@redocly/openapi-core`, extract `Model[]`, `Enum[]`, and `Service[]` into the IR (`ApiSpec`). Sub-modules handle ref resolution (`refs.ts`), schema walking (`schemas.ts`), operation grouping (`operations.ts`), pagination detection (`pagination.ts`), and inline model extraction (`inline-models.ts`).
+
+2. **Emit** (`src/engine/orchestrator.ts`) — Call each emitter method in order (`generateModels` → `generateEnums` → `generateResources` → `generateClient` → `generateErrors` → `generateConfig` → `generateTypeSignatures` → `generateTests` → `generateManifest`), collect `GeneratedFile[]`, prepend file headers.
+
+3. **Write** (`src/engine/writer.ts`) — Write files to disk. New files are created in full. Existing files are merged at the AST level via `merger.ts` (additive-only — new symbols appended, existing symbols untouched). Files marked `skipIfExists` are never overwritten.
+
+## Modification Patterns
+
+When changing pipeline behavior:
+
+- **Adding a new IR node** — Update `src/ir/types.ts`, add `assertNever` branch in emitters. See [IR Types](../architecture/ir-types.md).
+- **Adding a parser feature** — Add or modify sub-modules in `src/parser/`, wire into `parseSpec()`. Parser tests live in `test/parser/`.
+- **Changing orchestration** — Modify `src/engine/orchestrator.ts`. The `generate()` function builds `EmitterContext`, calls `generateAllFiles()`, then `writeFiles()`.
+- **Changing write behavior** — Modify `src/engine/writer.ts` or `src/engine/merger.ts`. The writer never deletes files; see [Non-Additive Changes](../architecture/non-additive-changes.md) for staleness detection.
+- **Plugin/config changes** — Modify `src/cli/config-loader.ts`. The `OagenConfig` interface defines all user-facing config fields. See [CLI Reference](../cli.md) for command details.
+
+## Core Contracts
+
+- IR types live in `src/ir/types.ts`
+- The emitter interface lives in `src/engine/types.ts`
+- Operation planning lives in `src/engine/operation-plan.ts`
+- Emitter registration lives in `src/engine/registry.ts`
+- Config loading lives in `src/cli/config-loader.ts`
+
+## Source Of Truth
+
+- Pipeline details: [docs/architecture/pipeline.md](../architecture/pipeline.md)
+- Dependency rules: [docs/architecture/dependency-layers.md](../architecture/dependency-layers.md)
+- IR contract details: [docs/architecture/ir-types.md](../architecture/ir-types.md)
+- Emitter contract details: [docs/architecture/emitter-contract.md](../architecture/emitter-contract.md)
+- Non-additive changes: [docs/architecture/non-additive-changes.md](../architecture/non-additive-changes.md)
+- CLI reference: [docs/cli.md](../cli.md)
+- Workflow diagrams: [docs/diagrams/generate-sdk-workflow.md](../diagrams/generate-sdk-workflow.md)
+
+## Directory Landmarks
+
+- `src/parser/`: OpenAPI to IR (refs, schemas, operations, pagination, inline models)
+- `src/engine/`: orchestration, writer, merger, registry, shared engine types
+- Language-specific emitters live in the separate `oagen-emitters` project (import from `@workos/oagen`)
+- `src/differ/`: incremental diff engine
+- `src/compat/`: compat verification, overlay, staleness detection, extractors
+- `src/cli/`: CLI entry points and config loader
+- `src/utils/`: naming utilities (snake_case, camelCase, PascalCase conversions)

package/docs/agents/emitters.md

@@ -0,0 +1,69 @@
+# Emitter Implementation
+
+Use this guide when adding or changing a language emitter.
+
+## Working Model
+
+Emitters transform IR into `GeneratedFile[]`. Keep generator methods pure: no I/O and no side effects.
+
+## Common Emitter Layout
+
+Emitters live in the separate `oagen-emitters` project and import types from `@workos/oagen`. Most emitters are organized around:
+
+- `index.ts`: emitter entry point
+- `type-map.ts`: `TypeRef` to target-language type mapping
+- `naming.ts`: target-language naming rules
+- `models.ts`: model generation
+- `enums.ts`: enum generation
+- `resources.ts`: service and resource generation
+- `client.ts`: HTTP client generation
+- `errors.ts`: error types
+- `config.ts`: configuration output
+- `tests.ts`: generated test files
+- `fixtures.ts`: generated fixtures
+- `manifest.ts`: smoke manifest output when needed
+
+Language-specific extras already exist in some emitters:
+
+- Ruby: `yard.ts`, `types-rbs.ts`, `types-rbi.ts`
+- Node: `options.ts`, `common.ts`, `manifest.ts`
+
+- `src/engine/operation-plan.ts` provides shared operation semantics (`OperationPlan`). Emitters should call `planOperation(op)` rather than duplicating decision logic for `isDelete`, `hasBody`, `isPaginated`, `responseModelName`, etc.
+
+## Naming
+
+IR names use PascalCase. Each emitter is responsible for converting names through its local `naming.ts`.
+
+## Verifying Backwards Compatibility
+
+When regenerating an SDK for a language that already has a published SDK, verify that the generated output preserves the existing public API surface.
+
+**When to use:**
+
+- The target language has an existing SDK with consumers who depend on its public API
+- You're modifying an emitter and need to ensure no regressions in method names, signatures, or exports
+
+**When to skip:**
+
+- The target language is brand new (no existing SDK) — pass `--no-compat-check` to the generate command
+- You're doing a full rewrite where breaking changes are intentional and documented
+
+**How the self-correcting loop works:**
+
+1. Extract the live SDK's API surface (`oagen extract --sdk-path <path> --lang <language> --output <output>/sdk-{language}-surface.json`)
+2. Generate with the overlay (`--api-surface <output>/sdk-{language}-surface.json`) so the emitter preserves existing names
+3. Verify the generated output against the baseline (`oagen verify --api-surface <output>/sdk-{language}-surface.json --lang <language> --output <output>`)
+4. If violations exist, fix the emitter and regenerate — loop mode (`--loop`) automates this cycle
+
+The differ and overlay delegate all language-specific logic to the extractor's `hints: LanguageHints` object. Every extractor must provide hints — use `resolveHints({...})` to override only what differs from Node defaults. See `docs/architecture/extractor-contract.md` for the full hints reference.
+
+The `--api-surface` flag is supported by both `oagen generate` and `oagen diff` (for incremental generation with compat overlay).
+
+Run `/generate-extractor <language>` to scaffold the extractor, then `/verify-compat <language>` for the full guided workflow.
+
+## Source Of Truth
+
+- Per-language design docs: `docs/sdk-architecture/{language}.md` in the emitter project
+- Extractor contract: `docs/architecture/extractor-contract.md`
+- Create a new emitter: `/generate-emitter <language>`
+- Create a new extractor: `/generate-extractor <language>`

package/docs/agents/testing.md

@@ -0,0 +1,60 @@
+# Testing And Smoke Validation
+
+Use this guide when changing framework behavior, emitter-generated output, or compat verification coverage.
+
+## Quick Start: Spec Update Pipeline
+
+When a new spec version arrives:
+
+```bash
+oagen diff --old v1.yml --new v2.yml --report         # review what changed
+oagen generate --spec v2.yml --lang node --output ./sdk
+oagen verify --spec v2.yml --lang node --output ./sdk
+
+# With custom smoke runner
+oagen verify --spec v2.yml --lang node --output ./sdk --smoke-runner ./my-runner.ts
+```
+
+Exit 0 = all passed. Exit 1 = findings (`smoke-diff-findings.json`). Exit 2 = compile error (`smoke-compile-errors.json`).
+
+See [Workflows](../architecture/workflows.md) for the full workflow diagram (setup vs. ongoing).
+
+## Unit And Integration Tests
+
+- `test/` mirrors `src/`
+- Prefer `toMatchInlineSnapshot()` for representative output assertions
+
+## Compat Verification
+
+Compat verification checks that generated SDK code preserves the public API surface of an existing live SDK. It sits between unit tests and smoke tests in the testing pyramid:
+
+- **Unit tests** — verify emitter logic in isolation (fast, no external dependencies)
+- **Compat verification** — verify the API surface (names, signatures, exports) matches the live SDK
+- **Smoke tests** — verify wire-level HTTP behavior against the real API
+
+Compat verification catches regressions like renamed methods, changed parameter signatures, missing exports, and reorganized barrel files — issues that unit tests don't cover because they don't compare against the live SDK, and that smoke tests don't cover because they focus on HTTP behavior rather than API shape.
+
+- Compat extraction: `oagen extract --sdk-path <path> --lang <language> --output <output>/sdk-{language}-surface.json`
+- Compat verification: `oagen verify --api-surface <output>/sdk-{language}-surface.json --lang <language> --output <output>`
+- Unified verify (includes compat): `oagen verify --api-surface <output>/sdk-{language}-surface.json --lang <language> --output <output>`
+- Run `/verify-compat <language>` for the full guided workflow
+- See `docs/architecture/extractor-contract.md` for building new language extractors
+- The differ and overlay use `LanguageHints` from the extractor to handle language-specific type comparisons (nullability, unions, extraction artifacts, derived model names). See the "Language Hints" section in the extractor contract doc.
+
+## Smoke Tests
+
+Smoke scripts live under `scripts/smoke/`.
+
+- **Verify (recommended):** `oagen verify --lang <language> --output <path>` (after `oagen generate`)
+- **Custom smoke runner:** `oagen verify --lang <language> --output <path> --smoke-runner ./my-runner.ts` or set `smokeRunners` (per-language map) in `oagen.config.ts`
+- General smoke runner: `npm run smoke`
+- Raw baseline generation: `npm run smoke:raw`
+- Spec-only baseline: `npm run smoke:baseline`
+- Per-language SDK smoke tests: registered via `smokeRunners` in `oagen.config.ts`
+- Diffing: `npm run smoke:diff`
+- Validation: `npm run smoke:validate`
+
+## Source Of Truth
+
+- Smoke testing guide: `scripts/smoke/README.md`
+- Create a smoke test with the `.claude` skill: `/generate-smoke-test <language>`