@workos/oagen 0.7.0 → 0.8.0

package/docs/architecture/emitter-contract.md

@@ -154,9 +154,9 @@ Production emitters live in the separate `oagen-emitters` project and import typ
 1. Create design doc at `docs/sdk-architecture/{language}.md` in the emitter project
 2. Scaffold files under `src/{language}/` in the emitter project
 3. Implement all `Emitter` methods
-4. Register in the emitter project's `oagen.config.ts`
+4. Export through the emitter project's plugin bundle (e.g. `src/plugin.ts`)
 5. Add tests under `test/{language}/` in the emitter project
 
 Or use: `/generate-emitter <language>`
 
-Emitters are registered via `oagen.config.ts` — no need to modify CLI source. See the Configuration section in the README.
+Emitters are registered via the plugin bundle exported from the emitter package. The consumer project's `oagen.config.ts` imports the bundle and layers spec interpretation policy on top. See the [CLI Reference](../cli.md#configuration-oagenconfigts) for details.

package/docs/architecture/extractor-contract.md

@@ -98,12 +98,13 @@ const goHints = resolveHints({
 Extractors are registered via `oagen.config.ts` in the consumer project. The CLI loads the config at startup and registers all extractors automatically before any command runs.
 
 ```typescript
-// oagen.config.ts
-import { myExtractor } from "./src/compat/extractors/my-language.js";
+// oagen.config.ts (consumer project)
+import { workosEmittersPlugin } from "@workos/oagen-emitters";
 import type { OagenConfig } from "@workos/oagen";
 
 const config: OagenConfig = {
-  extractors: [myExtractor],
+  ...workosEmittersPlugin, // includes all extractors
+  // spec interpretation policy...
 };
 export default config;
 ```
@@ -212,8 +213,8 @@ All tree-sitter parsers use `safeParse()` from `src/utils/tree-sitter.ts` to han
 3. Provide `hints` as a `LanguageHints` object. Every extractor must have hints — the differ and overlay delegate all language-specific logic through them.
 4. Split into `{language}-parser.ts` and `{language}-surface.ts` if either: (a) the language separates type definitions from method implementations (structural joining needed), or (b) the classification logic for mapping parsed types to `ApiClass`/`ApiInterface`/`ApiEnum` is non-trivial. If the AST co-locates symbols and classification is straightforward, a single `{language}-parser.ts` returning `ApiClass[]` directly is sufficient.
 5. Use `safeParse()` from `src/utils/tree-sitter.ts` instead of calling `parser.parse()` directly.
-6. Export from `src/index.ts`
-7. Register in the consumer project's `oagen.config.ts`
+6. Export from `src/index.ts` and include in the plugin bundle
+7. The consumer project's `oagen.config.ts` picks it up through the plugin bundle
 8. Add tests in `test/compat/extractors/{language}.test.ts`
 9. Create a fixture SDK in `test/fixtures/sample-sdk-{language}/` with known classes, methods, and exports
 10. Verify deterministic output: extracting twice produces identical JSON

package/docs/architecture/pipeline.md

@@ -96,11 +96,12 @@ Every generator method receives:
 Simple map from language name → `Emitter` instance. Emitters are registered at startup via `oagen.config.ts`:
 
 ```typescript
-// In oagen.config.ts (emitter project)
-import { nodeEmitter, rubyEmitter } from "./src/index.js";
+// In oagen.config.ts (consumer project)
+import { workosEmittersPlugin } from "@workos/oagen-emitters";
 
 export default {
-  emitters: [nodeEmitter, rubyEmitter],
+  ...workosEmittersPlugin,
+  // spec interpretation policy...
 };
 ```
 

package/docs/architecture/workflows.md

@@ -12,7 +12,7 @@ gets written or fixed.
 
 ### Skill sequence
 
-**Project setup:** Run `oagen init --lang {language}` to create the emitter project, then implement the emitter methods.
+**Project setup:** Run `oagen init --lang {language}` to scaffold an emitter project, then implement the emitter methods. Export the emitter through a plugin bundle so the consumer project can register it via its `oagen.config.ts`.
 
 **Scenario A** (existing SDK to preserve):
 
@@ -106,8 +106,10 @@ to preserve backwards compatibility:
 3. **Verify:** `oagen verify --spec v2.yml --lang {lang} --output ./sdk --api-surface sdk-{lang}-surface.json`
 4. **Ship** if verify exits 0
 
-**External consumers** configure emitters and extractors via `oagen.config.ts`
-instead of modifying CLI source — see the Configuration section in the README.
+**Consumer projects** register emitters and extractors by importing plugin bundles
+from emitter packages into their `oagen.config.ts`. Spec interpretation policy
+(transforms, hints, mount rules) also lives in the consumer config. See the
+[CLI Reference](../cli.md#configuration-oagenconfigts) for details.
 
 ### If verify fails on a spec update
 

package/docs/cli.md

@@ -52,6 +52,85 @@ oagen extract --sdk-path ./existing-sdk --lang ruby --output my-surface.json
 | `--lang <language>` | Yes      |                           | Target language                                                                                                 |
 | `--output <path>`   | No       | `sdk-{lang}-surface.json` | Output file path (recommend writing to your output dir, e.g. `./sdk/sdk-ruby-surface.json`, and gitignoring it) |
 
+## `oagen compat-extract`
+
+Extract a compat snapshot from a live SDK and write it to a JSON file. The snapshot is a machine-readable record of the SDK's public API surface, used as input to `compat-diff`.
+
+```bash
+oagen compat-extract --sdk-path ./existing-sdk --lang node --output .
+oagen compat-extract --sdk-path ./existing-sdk --lang php --output ./sdk --spec openapi.yml
+```
+
+| Argument            | Required | Default                 | Description                                                                        |
+| ------------------- | -------- | ----------------------- | ---------------------------------------------------------------------------------- |
+| `--sdk-path <path>` | Yes      |                         | Path to the live SDK                                                               |
+| `--lang <language>` | Yes      |                         | Target language                                                                    |
+| `--output <dir>`    | Yes      |                         | Directory to write `.oagen-compat-snapshot.json` into                              |
+| `--spec <path>`     | No       | `OPENAPI_SPEC_PATH` env | Path to OpenAPI spec — enriches symbols with `operationId`, `route`, and `specSha` |
+
+Always writes `.oagen-compat-snapshot.json` in the specified directory. The snapshot file is meant to be committed to the repository and updated on each release.
+
+When `--spec` is provided, the command parses the spec and enriches callable symbols with `operationId` and `route` (HTTP method + path) by matching against spec operations. It also computes a SHA-256 of the spec file and stores it as `source.specSha` in the snapshot.
+
+## `oagen compat-diff`
+
+Diff two compat snapshot files and produce a classified change report. No extraction or spec required — pure file-in, report-out.
+
+```bash
+# Basic diff with terminal output
+oagen compat-diff --baseline .oagen-compat-snapshot.json --candidate /tmp/candidate.json
+
+# With machine-readable report and failure threshold
+oagen compat-diff \
+  --baseline .oagen-compat-snapshot.json \
+  --candidate /tmp/candidate.json \
+  --output compat-report.json \
+  --fail-on breaking
+```
+
+| Argument             | Required | Default    | Description                                        |
+| -------------------- | -------- | ---------- | -------------------------------------------------- |
+| `--baseline <path>`  | Yes      |            | Path to the baseline compat snapshot JSON          |
+| `--candidate <path>` | Yes      |            | Path to the candidate compat snapshot JSON         |
+| `--output <path>`    | No       |            | Write machine-readable JSON report to this path    |
+| `--fail-on <level>`  | No       | `breaking` | Fail threshold: `none`, `breaking`, or `soft-risk` |
+| `--explain`          | No       | `false`    | Include provenance explanations in terminal output |
+
+**Exit codes:** 0 = no changes exceed threshold, 1 = changes exceed threshold.
+
+## `oagen compat-summary`
+
+Format a compat report as a markdown PR comment. Reads the JSON report produced by `compat-diff --output` and outputs markdown to stdout or a file.
+
+```bash
+# Single language
+oagen compat-summary --report compat-report.json | gh pr comment --body-file -
+
+# Cross-language rollup (multiple reports)
+oagen compat-summary --report php.json --report python.json --report go.json
+
+# Write to a file
+oagen compat-summary --report compat-report.json --output summary.md
+```
+
+| Argument             | Required | Default | Description                                                                |
+| -------------------- | -------- | ------- | -------------------------------------------------------------------------- |
+| `--report <path...>` | Yes      |         | Path(s) to compat report JSON(s) — pass multiple for cross-language rollup |
+| `--output <path>`    | No       | stdout  | Write markdown to this file instead of stdout                              |
+
+**Single report** output includes:
+
+- Status header (pass/warning/fail)
+- Summary table with breaking, soft-risk, and additive counts
+- Breaking changes table (always visible)
+- Soft-risk and additive changes in collapsible `<details>` sections
+
+**Multiple reports** produce a cross-language rollup:
+
+- Per-language summary table (breaking/soft-risk/additive per language)
+- Conceptual changes table showing per-language severity for each change
+- Same conceptual change across languages is shown as one row, not N separate rows
+
 ## `oagen verify`
 
 Verify an already-generated SDK — run smoke tests and optional compat checks. Use after `oagen generate`.
@@ -103,9 +182,10 @@ Creates:
 
 - `package.json` with `@workos/oagen` dependency and `sdk:generate`/`sdk:verify`/`sdk:extract` scripts
 - `tsconfig.json`, `vitest.config.ts`, `tsup.config.ts` — build/test tooling
-- `oagen.config.ts` — registers the stub emitter
+- `oagen.config.ts` — minimal config for local development, imports the plugin bundle
+- `src/plugin.ts` — plugin bundle export registering the stub emitter
 - `src/{language}/index.ts` — stub emitter implementing the full `Emitter` interface
-- `src/index.ts` — barrel export
+- `src/index.ts` — barrel export including the plugin bundle
 - Empty directories: `test/`, `smoke/`, `docs/sdk-architecture/`
 
 After initialization, `npm run typecheck` passes immediately. Implement your emitter methods in `src/{language}/` to start generating SDK code.
@@ -141,19 +221,80 @@ oagen resolve --spec openapi.yml --format json
 
 When `oagen.config.ts` defines `operationHints` and/or `mountRules`, they are applied automatically. The table format flags operations that have no hint and are resolved purely by algorithm.
 
+## `--config <path>`
+
+All commands accept a global `--config <path>` option to load a specific config file instead of the default cwd-based discovery.
+
+```bash
+# Explicit config
+oagen generate --config ../openapi-spec/oagen.config.ts --spec openapi.yml --lang node --output ./sdk
+
+# Default: searches for oagen.config.ts in the current directory
+oagen generate --spec openapi.yml --lang node --output ./sdk
+```
+
+When `--config` is omitted, the CLI searches the current working directory for `oagen.config.ts`, `oagen.config.js`, or `oagen.config.mjs` in that order.
+
 ## Configuration (`oagen.config.ts`)
 
-Place an `oagen.config.ts` (or `.js`/`.mjs`) in your project root to register emitters, extractors, and customize pipeline behavior. The CLI loads this file at startup before any command runs.
+Place an `oagen.config.ts` (or `.js`/`.mjs`) in the project that drives generation. The CLI loads this file at startup before any command runs.
+
+The config file belongs to the **consumer project** (the project that owns spec interpretation policy), not the emitter library. Emitter packages export plugin bundles that the consumer config composes.
+
+### Consumer config (recommended)
+
+```ts
+import type { OagenConfig } from "@workos/oagen";
+import { workosEmittersPlugin } from "@workos/oagen-emitters";
+
+const config: OagenConfig = {
+  ...workosEmittersPlugin,
+  docUrl: "https://workos.com/docs",
+  operationIdTransform: (id) => id.replace(/Controller_/, ""),
+  operationHints,
+  mountRules,
+};
+
+export default config;
+```
+
+### Standalone emitter config
+
+For standalone emitter projects that also serve as the consumer:
 
 ```ts
 import type { OagenConfig } from "@workos/oagen";
 import { nodeEmitter } from "./src/node/index.js";
-import { nodeExtractor } from "./src/node/extractor.js";
 
 const config: OagenConfig = {
   emitters: [nodeEmitter],
-  extractors: [nodeExtractor],
-  docUrl: "https://workos.com/docs",
+};
+
+export default config;
+```
+
+### Composing multiple plugin bundles
+
+```ts
+import type { OagenConfig } from "@workos/oagen";
+import { workosEmittersPlugin } from "@workos/oagen-emitters";
+import { experimentalPlugin } from "@workos/oagen-experimental";
+
+const config: OagenConfig = {
+  emitters: [
+    ...(workosEmittersPlugin.emitters ?? []),
+    ...(experimentalPlugin.emitters ?? []),
+  ],
+  extractors: [
+    ...(workosEmittersPlugin.extractors ?? []),
+    ...(experimentalPlugin.extractors ?? []),
+  ],
+  smokeRunners: {
+    ...(workosEmittersPlugin.smokeRunners ?? {}),
+    ...(experimentalPlugin.smokeRunners ?? {}),
+  },
+  operationHints,
+  mountRules,
 };
 
 export default config;
@@ -168,6 +309,7 @@ export default config;
 | `emitterProject`       | `string`                        | Path to the emitter project directory. Used by skills to scaffold new emitters, tests, and smoke runners in the correct location.                                                                                                                |
 | `smokeRunners`         | `Record<string, string>`        | Map from language key to custom smoke runner script path. Overrides the built-in `sdk-test.ts` for `oagen verify`. Can also be set per-invocation with `--smoke-runner`.                                                                         |
 | `operationIdTransform` | `(id: string) => string`        | Custom transform for operation IDs. Receives the raw `operationId` from the spec; return the desired operation name. No additional casing conversion is applied. When omitted, `operationId` values are converted to `camelCase`.                |
+| `schemaNameTransform`  | `(name: string) => string`      | Custom transform for schema (model/enum) names. Applied after the built-in `cleanSchemaName` normalization. Receives the cleaned PascalCase name; return the desired name.                                                                       |
 | `docUrl`               | `string`                        | Base URL for documentation links. When set, relative markdown paths in descriptions (e.g. `[User](/reference/authkit/user)`) are expanded to full URLs (e.g. `[User](https://workos.com/docs/reference/authkit/user)`).                          |
 | `operationHints`       | `Record<string, OperationHint>` | Per-operation overrides keyed by `"METHOD /path"`. Override derived method names, remount to a different service, or split union-body operations into typed wrappers. See [Operation Resolution](architecture/ir-types.md#operation-resolution). |
 | `mountRules`           | `Record<string, string>`        | Service-level remounting. Maps IR service name to target service/namespace (PascalCase). All operations in the source service are mounted on the target unless overridden per-operation in `operationHints`.                                     |

package/docs/contributor/public-api.md

@@ -15,7 +15,7 @@ It includes:
 - spec diffing APIs such as `diffSpecs`
 - naming utilities used by emitters
 - `planOperation`
-- config typing needed by emitter projects
+- config typing needed by consumer and emitter projects
 
 Changes to this surface require a deliberate compatibility review.
 

package/docs/core/compatibility-ir.md

@@ -0,0 +1,200 @@
+# Compatibility IR
+
+The compatibility IR defines the types used to represent, diff, and classify SDK public API surfaces.
+
+## CompatSnapshot
+
+A full snapshot of an SDK's public API surface.
+
+```ts
+interface CompatSnapshot {
+  schemaVersion: string;
+  source: {
+    specSha?: string;
+    extractedAt: string;
+  };
+  policies: CompatPolicyHints;
+  symbols: CompatSymbol[];
+}
+```
+
+## CompatSymbol
+
+A single public API symbol.
+
+```ts
+interface CompatSymbol {
+  id: string;
+  kind: CompatSymbolKind;
+  fqName: string;
+  ownerFqName?: string;
+  displayName: string;
+  visibility: "public" | "protected" | "internal";
+  stability: "stable" | "unstable" | "deprecated";
+  sourceKind: CompatSourceKind;
+  operationId?: string;
+  schemaName?: string;
+  route?: { method: string; path: string };
+  parameters?: CompatParameter[];
+  returns?: CompatTypeRef;
+}
+```
+
+### Symbol Kinds
+
+| Kind               | Description                              |
+| ------------------ | ---------------------------------------- |
+| `service_accessor` | A service class (e.g., `UserManagement`) |
+| `callable`         | A method on a service class              |
+| `constructor`      | A constructor/initializer                |
+| `field`            | A field on an interface/model            |
+| `property`         | A property on a class                    |
+| `enum`             | An enum type                             |
+| `enum_member`      | A member of an enum                      |
+| `alias`            | A type alias or interface name           |
+
+### Source Kinds
+
+| Source Kind                      | Description                      |
+| -------------------------------- | -------------------------------- |
+| `generated_service_wrapper`      | Generated from an API service    |
+| `generated_model_constructor`    | Generated model constructor      |
+| `generated_resource_constructor` | Generated resource constructor   |
+| `generated_enum`                 | Generated from an enum schema    |
+| `compat_alias`                   | Added for backward compatibility |
+
+## CompatParameter
+
+```ts
+interface CompatParameter {
+  publicName: string;
+  wireName?: string;
+  position: number;
+  required: boolean;
+  nullable: boolean;
+  hasDefault: boolean;
+  passing: CompatPassingStyle;
+  type: CompatTypeRef;
+  sensitivity: ParameterSensitivity;
+}
+```
+
+### Passing Styles
+
+| Style                   | Description             | Languages                      |
+| ----------------------- | ----------------------- | ------------------------------ |
+| `positional`            | Position-only arguments | Go, Rust                       |
+| `keyword`               | Keyword arguments       | Python, Ruby, Elixir           |
+| `named`                 | Named arguments         | PHP, Kotlin, C#                |
+| `keyword_or_positional` | Either style            | Python (positional-or-keyword) |
+| `options_object`        | Object destructuring    | Node/TypeScript                |
+| `builder`               | Builder pattern         | Java-style                     |
+
+### Parameter Sensitivity
+
+```ts
+interface ParameterSensitivity {
+  order: boolean; // Position changes are breaking
+  publicName: boolean; // Name changes are breaking
+  requiredness: boolean; // Requiredness changes are breaking
+  type: boolean; // Type changes are breaking
+}
+```
+
+## Change Categories
+
+### Breaking
+
+| Category                                       | Description                                         |
+| ---------------------------------------------- | --------------------------------------------------- |
+| `symbol_removed`                               | A public symbol was removed                         |
+| `symbol_renamed`                               | A public symbol was renamed                         |
+| `parameter_removed`                            | A parameter was removed                             |
+| `parameter_renamed`                            | A parameter was renamed                             |
+| `parameter_requiredness_increased`             | Optional → required                                 |
+| `parameter_type_narrowed`                      | Parameter type changed                              |
+| `parameter_position_changed_order_sensitive`   | Parameter moved in order-sensitive language         |
+| `constructor_position_changed_order_sensitive` | Constructor param moved in order-sensitive language |
+| `named_arg_name_removed`                       | Named argument removed                              |
+| `keyword_name_removed`                         | Keyword argument removed                            |
+| `overload_removed`                             | Method overload removed                             |
+| `union_wrapper_migration_without_compat_alias` | Union wrapper migration without backward compat     |
+
+### Soft-Risk
+
+| Category                                              | Description                                      |
+| ----------------------------------------------------- | ------------------------------------------------ |
+| `parameter_added_non_terminal_optional`               | Optional param added (not at end)                |
+| `constructor_reordered_named_friendly`                | Constructor reordered in named-friendly language |
+| `default_value_changed`                               | Default value changed                            |
+| `wrapper_stricter_than_previous_sdk_but_matches_spec` | Stricter but spec-correct                        |
+| `doc_surface_drift`                                   | Documentation-only drift                         |
+
+### Additive
+
+| Category                            | Description                 |
+| ----------------------------------- | --------------------------- |
+| `symbol_added`                      | New symbol added            |
+| `parameter_added_optional_terminal` | Optional param added at end |
+| `new_constructor_overload_added`    | New constructor overload    |
+| `new_wrapper_alias_added`           | New compatibility alias     |
+
+## Provenance Buckets
+
+Every classified change includes a provenance field explaining the source of drift:
+
+| Provenance                | Description                                    |
+| ------------------------- | ---------------------------------------------- |
+| `spec_shape_change`       | The OpenAPI spec changed shape                 |
+| `spec_ordering_change`    | The spec changed property ordering             |
+| `emitter_template_change` | The emitter template was modified              |
+| `compat_extractor_change` | The extractor logic changed                    |
+| `operation_hint_change`   | An operation hint changed                      |
+| `manual_override_change`  | A manual override was applied                  |
+| `normalization_change`    | Naming normalization produced different output |
+| `unknown`                 | Source not determined                          |
+
+## Extracting Snapshots
+
+Every extractor implements `extractSnapshot()`, which returns a `CompatSnapshot` directly:
+
+```ts
+const extractor = getExtractor("node");
+const snapshot: CompatSnapshot = await extractor.extractSnapshot(sdkPath);
+```
+
+This is the primary method used by `oagen compat-extract`. Internally, extractors call `extract()` to produce an `ApiSurface`, then convert it to a `CompatSnapshot` via the bridge function.
+
+### Extractor Interface
+
+```ts
+interface Extractor {
+  language: string;
+  extract(sdkPath: string): Promise<ApiSurface>;
+  extractSnapshot(sdkPath: string): Promise<CompatSnapshot>;
+  hints: LanguageHints;
+}
+```
+
+Both `extract()` and `extractSnapshot()` are available. Use `extractSnapshot()` for the compat pipeline. Use `extract()` when you need the raw `ApiSurface` for overlay or legacy workflows.
+
+### Spec Enrichment
+
+When `oagen compat-extract` receives `--spec`, it enriches callable symbols with spec-derived metadata:
+
+- **`operationId`** — the operation name from the spec, matched by service + method name
+- **`route`** — the HTTP method and path (e.g., `{ method: "POST", path: "/users" }`)
+- **`source.specSha`** — SHA-256 of the spec file
+
+This enrichment happens after extraction, as a post-step in the CLI. Extractors themselves don't need spec awareness.
+
+### Bridge: ApiSurface → CompatSnapshot
+
+The `apiSurfaceToSnapshot()` function converts an `ApiSurface` to a `CompatSnapshot`, applying language-appropriate passing styles and sensitivity flags. This is what `extractSnapshot()` uses internally.
+
+```ts
+import { apiSurfaceToSnapshot } from "@workos/oagen";
+
+const surface: ApiSurface = await extractor.extract(sdkPath);
+const snapshot: CompatSnapshot = apiSurfaceToSnapshot(surface);
+```

package/docs/core/compatibility-policy.md

@@ -0,0 +1,170 @@
+# Compatibility Policy
+
+Human-authored compatibility policy lives in the `compat` section of `oagen.config.ts`. This is the single place for fail thresholds, language overrides, and intentional break approvals.
+
+## Config Schema
+
+```ts
+export default {
+  compat: {
+    failOn: "breaking",
+    reportPath: "compat-report.json",
+    explain: true,
+    baselinePath: "sdk-surface.json",
+    languagePolicy: {
+      php: {
+        // optional sparse overrides
+      },
+    },
+    allow: [
+      // intentional break approvals
+    ],
+  },
+};
+```
+
+### Fields
+
+| Field            | Type                                             | Default      | Description                                |
+| ---------------- | ------------------------------------------------ | ------------ | ------------------------------------------ |
+| `failOn`         | `'none' \| 'breaking' \| 'soft-risk'`            | `'breaking'` | Severity threshold for `verify` failure    |
+| `reportPath`     | `string`                                         | —            | Path to write machine-readable JSON report |
+| `explain`        | `boolean`                                        | `false`      | Include provenance explanations in output  |
+| `baselinePath`   | `string`                                         | —            | Path to baseline compatibility snapshot    |
+| `languagePolicy` | `Record<LanguageId, Partial<CompatPolicyHints>>` | —            | Per-language policy overrides              |
+| `allow`          | `CompatApproval[]`                               | —            | Intentional break approvals                |
+
+## Language Policy
+
+Language policy determines which aspects of the public API are breaking. Built-in defaults capture language semantics:
+
+| Language | Caller Uses Param Names | Constructor Order | Param Names Public | Overloads Public | Arity Public |
+| -------- | ----------------------- | ----------------- | ------------------ | ---------------- | ------------ |
+| PHP      | yes                     | yes               | yes                | no               | no           |
+| Python   | yes                     | yes               | yes                | no               | no           |
+| Ruby     | yes                     | yes               | yes                | no               | no           |
+| Go       | no                      | yes               | no                 | no               | yes          |
+| Kotlin   | yes                     | no                | yes                | yes              | no           |
+| .NET     | yes                     | no                | yes                | yes              | no           |
+| Elixir   | yes                     | no                | yes                | no               | yes          |
+| Rust     | no                      | yes               | no                 | no               | yes          |
+| Node     | no                      | no                | no                 | no               | no           |
+
+### Overriding Language Defaults
+
+Use `languagePolicy` only when a specific SDK intentionally diverges from language norms:
+
+```ts
+compat: {
+  languagePolicy: {
+    node: {
+      // This Node SDK uses positional args, not options objects
+      methodParameterNamesArePublicApi: true,
+    },
+  },
+}
+```
+
+## Approvals
+
+Approvals are concept-first: one approval covers one conceptual change across affected languages.
+
+### Schema
+
+```ts
+interface CompatApproval {
+  symbol: string; // Fully-qualified symbol
+  category: string; // Change category (e.g., 'parameter_renamed')
+  appliesTo?: string[]; // Language IDs, or omit for all
+  match?: {
+    // Optional narrowing
+    parameter?: string;
+    member?: string;
+    oldName?: string;
+    newName?: string;
+  };
+  allowedReleaseLevel?: "major" | "minor" | "patch";
+  reason: string; // Required explanation
+  issue?: string; // Issue tracker reference
+  expiresAfterVersion?: string;
+  approved?: boolean; // Whether this approval is active (default: true)
+}
+```
+
+### The `approved` Field
+
+Approvals default to active. Set `approved: false` to deactivate an approval without removing it from the config — useful for temporarily disabling an approval or keeping a record of past approvals.
+
+```ts
+{
+  symbol: 'Authorization.check',
+  category: 'parameter_renamed',
+  reason: 'Intentional rename for v3',
+  issue: 'SDK-1234',
+  approved: false, // deactivated — this break is no longer approved
+}
+```
+
+When `approved` is `false`, the matching engine skips the approval entirely. When `approved` is `true` or omitted, the approval is active.
+
+### Example
+
+```ts
+compat: {
+  allow: [
+    {
+      symbol: 'WorkOS\\Service\\UserManagement::createUser',
+      category: 'parameter_removed',
+      match: { parameter: 'passwordHashType' },
+      appliesTo: ['php', 'python', 'kotlin', 'dotnet'],
+      allowedReleaseLevel: 'major',
+      reason: 'Intentional wrapper-object migration',
+      issue: 'SDK-1234',
+      expiresAfterVersion: '6.0.0',
+    },
+  ],
+}
+```
+
+### Matching Rules
+
+Approvals must be narrow:
+
+**Good:**
+
+- One symbol, one category, one conceptual change
+- Optionally one parameter/member
+- Optionally a bounded set of affected languages
+
+**Bad (rejected by validation):**
+
+- Wildcard symbols (`*`, `Authorization.*`)
+- Empty reason
+- Missing symbol or category
+
+### Anti-patterns
+
+| Pattern                            | Problem                            |
+| ---------------------------------- | ---------------------------------- |
+| Approve all breaks in one language | Too broad — masks real regressions |
+| Approve all parameter changes      | Hides future unintentional breaks  |
+| No reason field                    | No audit trail                     |
+| No issue reference                 | Can't trace back to decisions      |
+
+## Severity Determination
+
+The default severity for a category comes from the classification engine. Language policy can modify this:
+
+1. A `parameter_renamed` change is `breaking` by default
+2. If the language policy says `methodParameterNamesArePublicApi: false` (e.g., Go), the classifier can downgrade to `soft-risk`
+3. Approvals can further suppress changes from the failure threshold
+
+## Fail Threshold
+
+The `failOn` level determines which unapproved changes cause `oagen verify` to fail:
+
+| Level       | Fails on                                 |
+| ----------- | ---------------------------------------- |
+| `none`      | Never fails for compat                   |
+| `breaking`  | Unapproved breaking changes              |
+| `soft-risk` | Unapproved breaking OR soft-risk changes |