@workos/oagen 0.7.0 → 0.8.0

package/docs/core/compatibility.md

@@ -0,0 +1,83 @@
+# Compatibility Verification
+
+oagen includes a cross-language compatibility engine that detects breaking changes, classifies their severity per-language, and enforces policy before generated SDKs ship.
+
+## Overview
+
+The compatibility system answers: **"will this regeneration break existing callers?"**
+
+It works by comparing two snapshots of an SDK's public API surface — a baseline (the live SDK) and a candidate (the newly generated output) — and classifying every difference.
+
+## Lifecycle
+
+```
+compat-extract → .oagen-compat-snapshot.json → compat-diff → report → compat-summary
+```
+
+1. **Extract** — `oagen compat-extract` runs an extractor against the live SDK and writes a `CompatSnapshot` JSON file to disk (`.oagen-compat-snapshot.json`)
+2. **Diff** — `oagen compat-diff` compares a baseline snapshot (committed) against a candidate snapshot (freshly extracted from generated output), classifying each difference
+3. **Enforce** — `compat-diff` exits non-zero when unapproved changes meet or exceed the fail threshold (`--fail-on`)
+4. **Summary** — `oagen compat-summary` formats the JSON report as a markdown PR comment
+
+The baseline snapshot is committed to the repository and updated on each release. The candidate snapshot is extracted in CI from the freshly generated SDK.
+
+### CLI Commands
+
+| Command                | Purpose                                        |
+| ---------------------- | ---------------------------------------------- |
+| `oagen compat-extract` | Extract a snapshot from a live SDK → JSON file |
+| `oagen compat-diff`    | Diff two snapshot files → classified report    |
+| `oagen compat-summary` | Format a report → markdown PR comment          |
+
+See [CLI Reference](../cli.md) for full argument tables.
+
+## Relation to Smoke Tests
+
+Smoke tests verify **behavioral** correctness: does the generated SDK call the right endpoints with the right parameters? Compatibility verification checks **structural** correctness: does the generated SDK preserve the public API shape that callers depend on?
+
+Both run during `oagen verify`. Smoke tests catch bugs. Compat checks catch breaking changes.
+
+## Relation to Spec Diffing
+
+`oagen diff` compares two OpenAPI specs to show what changed at the API level. Compat verification compares two SDK surfaces to show what changed at the SDK level. A spec change may or may not produce a breaking SDK change, depending on the language and how the emitter handles it.
+
+## Key Concepts
+
+### Classification
+
+Every detected change gets a category and severity:
+
+- **Breaking** — Will break existing callers (e.g., `parameter_removed`, `symbol_renamed`)
+- **Soft-risk** — May affect callers depending on usage (e.g., `constructor_reordered_named_friendly`)
+- **Additive** — Safe to ship (e.g., `symbol_added`, `parameter_added_optional_terminal`)
+
+See [Compatibility IR](compatibility-ir.md) for the full category list.
+
+### Language Policy
+
+The same conceptual change has different severity in different languages. A parameter rename is breaking in PHP (named arguments) but soft-risk in Go (positional only). Language policy is defined by `CompatPolicyHints` with built-in defaults for all 9 supported languages.
+
+See [Compatibility Policy](compatibility-policy.md) for details.
+
+### Concept-First Approvals
+
+When a breaking change is intentional, it can be approved in `oagen.config.ts`. Approvals are concept-first: one approval targets one symbol and one change category, optionally scoped to specific languages.
+
+See [Compatibility Policy](compatibility-policy.md) for the approval schema.
+
+### Provenance
+
+Each classified change includes a provenance bucket explaining where the drift came from:
+
+- `spec_shape_change` — The spec changed
+- `emitter_template_change` — The emitter template changed
+- `normalization_change` — Naming normalization produced different output
+- `unknown` — Source of drift not determined
+
+## Further Reading
+
+- [CLI Reference](../cli.md) — `compat-extract`, `compat-diff`, `compat-summary` argument tables
+- [Compatibility IR](compatibility-ir.md) — Types, categories, parameters, `extractSnapshot()`
+- [Compatibility Policy](compatibility-policy.md) — Config, approvals, language defaults
+- [Manifest Schema](manifest-schema.md) — `.oagen-manifest.json` format
+- [Verify Compat](verify-compat.md) — CI workflows, reports, GitHub Actions example

package/docs/core/index.md

@@ -8,5 +8,10 @@ These documents define the stable center of oagen as an OSS framework.
 - [Pipeline Architecture](../architecture/pipeline.md)
 - [IR Type System Reference](../architecture/ir-types.md)
 - [Emitter Contract](../architecture/emitter-contract.md)
+- [Compatibility Verification](compatibility.md)
+- [Compatibility IR](compatibility-ir.md)
+- [Compatibility Policy](compatibility-policy.md)
+- [Manifest Schema](manifest-schema.md)
+- [Verify Compat](verify-compat.md)
 
 Read the quickstart first. The goal is to get from a spec to generated files without learning compatibility overlays, extractors, or smoke workflows.

package/docs/core/manifest-schema.md

@@ -0,0 +1,76 @@
+# Manifest Schema
+
+`.oagen-manifest.json` is a generated provenance artifact. It records what was generated, from which inputs, and when. It is machine-owned — humans should not edit it.
+
+## Purpose
+
+1. **Pruning** — On regeneration, oagen deletes files from the previous manifest that are no longer emitted, preventing stale-file accumulation
+2. **Provenance** — Records the spec, emitter, and config used for each generation run
+3. **Compat versioning** — Records the compat schema version for snapshot compatibility
+
+## Schema (v2)
+
+```json
+{
+  "version": 2,
+  "language": "php",
+  "sdkName": "workos-php",
+  "generatedAt": "2026-04-18T22:02:14.077Z",
+  "specSha": "sha256:abc123...",
+  "specPath": "../openapi-spec/spec/open-api-spec.yaml",
+  "emitterSha": "def456",
+  "emitterVersion": "0.7.0",
+  "configSha": "sha256:789abc...",
+  "compatSchemaVersion": "1",
+  "files": ["lib/Resource/CreateUser.php", "lib/Service/UserManagement.php"]
+}
+```
+
+## Field Semantics
+
+| Field                 | Type       | Required | Description                                                          |
+| --------------------- | ---------- | -------- | -------------------------------------------------------------------- |
+| `version`             | `number`   | yes      | Manifest schema version (currently `2`)                              |
+| `language`            | `string`   | yes      | Emitter target language (e.g., `"php"`)                              |
+| `sdkName`             | `string`   | no       | Human-readable SDK identity (e.g., `"workos-php"`)                   |
+| `generatedAt`         | `string`   | yes      | ISO-8601 timestamp of the generation run                             |
+| `specSha`             | `string`   | no       | SHA-256 hash of the source OpenAPI spec                              |
+| `specPath`            | `string`   | no       | Path or reference to the source spec                                 |
+| `emitterSha`          | `string`   | no       | Git SHA of the emitter code used                                     |
+| `emitterVersion`      | `string`   | no       | Emitter version string                                               |
+| `configSha`           | `string`   | no       | SHA-256 hash of the effective `oagen.config.ts`                      |
+| `compatSchemaVersion` | `string`   | no       | Version of the compat snapshot schema                                |
+| `files`               | `string[]` | yes      | Sorted list of generated file paths (relative to manifest directory) |
+
+## Generated Ownership
+
+The manifest is generated by `oagen generate` and written to the output directory. It should be committed to the SDK repository for pruning to work across regenerations.
+
+**Never put human-authored content in the manifest.** Approvals, allowlists, and policy belong in `oagen.config.ts`. The manifest is regenerated on every run — any manual edits will be overwritten.
+
+## Pruning Semantics
+
+When `oagen generate` runs:
+
+1. Read the existing `.oagen-manifest.json` (if present)
+2. Compare the previous `files` list against the current emission set
+3. Delete files that were previously generated but are no longer emitted
+4. Only delete files whose contents start with the oagen generation header (when a header guard is available)
+5. Write a new manifest with the current file list
+
+On first adoption (no previous manifest), pruning is skipped.
+
+## Backward Compatibility
+
+The manifest reader accepts both v1 and v2 manifests. v1 manifests (which lack `sdkName`, `specSha`, etc.) are read successfully — the new fields are simply absent. A v1 manifest written by an older oagen version will work with the current pruning system.
+
+If the manifest version is higher than supported, it is ignored with a warning.
+
+## What Must Not Go in the Manifest
+
+- Approvals or allowlists (human-authored → `oagen.config.ts`)
+- Release thresholds (human-authored → `oagen.config.ts`)
+- Manual exception records
+- Policy overrides
+
+The rule: **never make the generator rewrite a file that humans edit for policy.**

package/docs/core/quickstart.md

@@ -35,11 +35,18 @@ npm install
 
 The scaffold gives you:
 
-- `oagen.config.ts`
-- `src/demo/index.ts`
+- `oagen.config.ts` -- a minimal config for local development that imports the plugin bundle
+- `src/plugin.ts` -- plugin bundle export registering the stub emitter
+- `src/demo/index.ts` -- stub emitter implementing the `Emitter` interface
 - build/test tooling
 - `sdk:generate` and related package scripts
 
+> **Note:** The scaffolded project uses the plugin model. The consumer project
+> (e.g. a spec repo) imports the plugin bundle from `src/plugin.ts` and layers
+> its own spec interpretation policy on top. See the
+> [CLI Reference](../cli.md#configuration-oagenconfigts) for plugin
+> composition examples.
+
 ## 4. Replace the Stub Emitter
 
 Edit `src/demo/index.ts` to return a few simple files:

package/docs/core/verify-compat.md

@@ -0,0 +1,235 @@
+# Verify Compat
+
+`oagen verify` runs compatibility checks as part of its verification pipeline. This document covers the compat-specific CLI flags, report outputs, and CI integration.
+
+## CLI Flags
+
+### Existing Flags (Compat-Related)
+
+| Flag                   | Description                                                         |
+| ---------------------- | ------------------------------------------------------------------- |
+| `--api-surface <path>` | Baseline API surface JSON — enables compat verification             |
+| `--spec <path>`        | OpenAPI spec for spec-scoped comparison                             |
+| `--scope <mode>`       | `full` or `spec-only` (default: `spec-only` when `--spec` provided) |
+| `--max-retries <n>`    | Max overlay patch iterations (default: 3)                           |
+| `--diagnostics`        | Write `verify-diagnostics.json`                                     |
+
+### New Flags (Classified Compat)
+
+| Flag                       | Description                                                  |
+| -------------------------- | ------------------------------------------------------------ |
+| `--compat-report <path>`   | Write machine-readable classified compat report to this path |
+| `--compat-fail-on <level>` | Override fail threshold: `none`, `breaking`, or `soft-risk`  |
+| `--compat-baseline <path>` | Path to baseline compatibility snapshot                      |
+| `--compat-explain`         | Include provenance explanations in terminal output           |
+
+CLI flags take precedence over `oagen.config.ts` settings.
+
+## Report Outputs
+
+### Machine-Readable Report (`--compat-report`)
+
+```json
+{
+  "schemaVersion": "1",
+  "language": "php",
+  "summary": {
+    "breaking": 3,
+    "softRisk": 2,
+    "additive": 11
+  },
+  "changes": [
+    {
+      "severity": "breaking",
+      "category": "parameter_renamed",
+      "symbol": "Authorization.check",
+      "conceptualChangeId": "chg_parameter_renamed_authorization.check_resourceid",
+      "provenance": "emitter_template_change",
+      "old": { "parameter": "resourceId" },
+      "new": { "parameter": "resourceTarget" }
+    }
+  ]
+}
+```
+
+### Human Summary (`--compat-explain`)
+
+```
+Compat report for php:
+  3 breaking, 2 soft-risk, 11 additive
+
+  Breaking:
+    [parameter_renamed] Authorization.check — Parameter "resourceId" renamed to "resourceTarget"
+      provenance: emitter_template_change
+    [parameter_removed] UserManagement.createUser — Parameter "passwordHashType" removed
+      provenance: spec_shape_change
+
+  Soft-risk:
+    [constructor_reordered_named_friendly] CreateUser.constructor — reordered (named-friendly)
+      provenance: normalization_change
+
+  Additive: 11 new symbol(s)
+```
+
+### Diagnostics (`--diagnostics`)
+
+The existing `verify-diagnostics.json` continues to include legacy compat data (preservation score, violations by category/severity). The new classified report is written separately via `--compat-report`.
+
+## Failure Thresholds
+
+The verify command fails when unapproved changes meet or exceed the fail threshold:
+
+| `--compat-fail-on` | Fails on                                 |
+| ------------------ | ---------------------------------------- |
+| `none`             | Never fails for compat changes           |
+| `breaking`         | Unapproved breaking changes (default)    |
+| `soft-risk`        | Unapproved breaking OR soft-risk changes |
+
+Approved changes (matched by `compat.allow` in config) are excluded from the failure threshold.
+
+## CI Integration
+
+There are two CI models: **integrated** (via `oagen verify`) and **file-based** (via standalone `compat-extract` / `compat-diff` / `compat-summary` commands). The file-based model is recommended for new setups.
+
+### File-Based CI (Recommended)
+
+The file-based model uses `.oagen-compat-snapshot.json` as a committed baseline artifact. On each PR, the candidate SDK is extracted, diffed against the baseline, and a summary is posted as a PR comment.
+
+```yaml
+name: Compat Check
+on: [pull_request]
+
+jobs:
+  compat:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        lang: [node, php, python, ruby, go, kotlin, dotnet, elixir, rust]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Generate candidate SDK
+        run: oagen generate --spec openapi.yml --lang ${{ matrix.lang }} --output ./generated
+
+      - name: Extract candidate snapshot
+        run: |
+          oagen compat-extract \
+            --sdk-path ./generated \
+            --lang ${{ matrix.lang }} \
+            --output /tmp \
+            --spec openapi.yml
+
+      - name: Diff against baseline
+        run: |
+          oagen compat-diff \
+            --baseline .oagen-compat-snapshot.json \
+            --candidate /tmp/.oagen-compat-snapshot.json \
+            --output compat-report-${{ matrix.lang }}.json \
+            --fail-on breaking
+
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: compat-report-${{ matrix.lang }}
+          path: compat-report-${{ matrix.lang }}.json
+
+  summary:
+    needs: compat
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: compat-report-*
+          merge-multiple: true
+
+      - name: Post cross-language PR summary
+        run: |
+          oagen compat-summary \
+            --report compat-report-*.json \
+            | gh pr comment ${{ github.event.pull_request.number }} --body-file -
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+For a single-language project, simplify to one job without the matrix:
+
+```bash
+oagen compat-extract --sdk-path ./generated --lang node --output /tmp --spec openapi.yml
+oagen compat-diff --baseline .oagen-compat-snapshot.json --candidate /tmp/.oagen-compat-snapshot.json --output report.json --fail-on breaking
+oagen compat-summary --report report.json | gh pr comment --body-file -
+```
+
+#### Baseline Management
+
+The baseline snapshot is committed to the repository and updated as part of the release process:
+
+```bash
+# After releasing a new SDK version, update the baseline
+oagen compat-extract --sdk-path . --lang node --output .
+git add .oagen-compat-snapshot.json
+git commit -m "chore: update compat baseline for v2.1.0"
+```
+
+#### Report-Only Mode (Phase 4)
+
+To run compat checks without blocking PRs, set `--fail-on none`:
+
+```bash
+oagen compat-diff \
+  --baseline .oagen-compat-snapshot.json \
+  --candidate /tmp/candidate-snapshot.json \
+  --output compat-report.json \
+  --fail-on none
+```
+
+The PR summary will still be posted, but the job will not fail. Switch to `--fail-on breaking` when ready for hard enforcement.
+
+### Integrated CI (via `oagen verify`)
+
+The `oagen verify` command runs compat checks as part of its verification pipeline. This is suitable when you want smoke tests and compat checks in a single step.
+
+```yaml
+- name: Verify SDK
+  run: |
+    oagen verify \
+      --lang php \
+      --output ./generated \
+      --api-surface sdk-php-surface.json \
+      --spec openapi.yaml \
+      --compat-report compat-report.json \
+      --compat-fail-on breaking \
+      --diagnostics
+```
+
+### Exit Codes
+
+| Code | Meaning                                  |
+| ---- | ---------------------------------------- |
+| 0    | All checks passed                        |
+| 1    | Compat violations or smoke test findings |
+| 2    | SDK compile errors                       |
+
+## How to Read and Act on Findings
+
+### Breaking Changes
+
+1. Check the `provenance` field — is this from a spec change or an emitter change?
+2. If spec-driven: this may need a major version release
+3. If emitter-driven: fix the emitter to preserve backward compatibility
+4. If intentional: add an approval to `oagen.config.ts`
+
+### Soft-Risk Changes
+
+1. Review whether callers are likely affected
+2. If safe: no action needed (or add approval for documentation)
+3. If risky: fix the emitter or bump the release level
+
+### Additive Changes
+
+Safe to ship. No action needed.
+
+## Overlay Retry Loop
+
+The existing overlay retry loop (`--max-retries`) continues to work with the legacy compat system. It patches `public-api` and `export-structure` violations by correcting overlay mappings and regenerating. The classified compat report runs after the overlay loop has converged.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workos/oagen",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Framework for building OpenAPI SDK emitters",
   "author": "WorkOS",
   "license": "MIT",

package/skills/generate-emitter/SKILL.md

@@ -11,7 +11,7 @@ Scaffold a complete language emitter for oagen that translates the intermediate
 
 oagen has a plugin architecture for code generation. Each target language is an **emitter** — a TypeScript module that implements the `Emitter` interface. An emitter receives parsed IR nodes (models, enums, services, etc.) and returns `GeneratedFile[]` — arrays of `{ path, content }` pairs. The engine orchestrator calls each emitter method, prepends a file header, and writes the results to disk.
 
-Emitters live in **external projects** (not inside the oagen core repo). They import all oagen types from `@workos/oagen` and register via `oagen.config.ts` in their project.
+Emitters live in **external projects** (not inside the oagen core repo). They import all oagen types from `@workos/oagen` and are exported through the emitter project's plugin bundle (e.g., `workosEmittersPlugin`), which the consumer project's `oagen.config.ts` imports.
 
 ## Reference Docs
 
@@ -41,7 +41,7 @@ Before starting, read and understand these oagen core types (all imported from `
 - `planOperation`, `OperationPlan` — operation analysis helpers
 - `toPascalCase`, `toSnakeCase`, `toCamelCase`, `toKebabCase`, `toUpperSnakeCase` — naming utilities
 
-Also read the project's `oagen.config.ts` to understand how emitters are registered.
+Also read the project's plugin bundle export (e.g., `src/plugin.ts`) to understand how emitters are registered.
 
 If an `sdk_path` argument is provided, you MUST thoroughly study that SDK before proceeding to Step 1. The existing SDK's actual code — not generic conventions — drives every design decision.
 
@@ -227,17 +227,22 @@ export const {language}Emitter: Emitter = {
 
 ## Step 7: Register Emitter
 
-Add the emitter to `oagen.config.ts` and re-export from `src/index.ts`:
+Add the emitter to the plugin bundle export (e.g., `src/plugin.ts`) and re-export from `src/index.ts`:
 
 ```typescript
-// oagen.config.ts
-import { {language}Emitter } from './src/{language}/index.js';
-const config: OagenConfig = { emitters: [/* existing, */ {language}Emitter] };
+// src/plugin.ts
+import { {language}Emitter } from './{language}/index.js';
+export const workosEmittersPlugin = {
+  emitters: [/* existing, */ {language}Emitter],
+  // ...
+};
 
 // src/index.ts
 export { {language}Emitter } from './{language}/index.js';
 ```
 
+The consumer project's `oagen.config.ts` imports the plugin bundle, so the new emitter is automatically available.
+
 ## Step 8: Create Tests
 
 Create test files under `test/{language}/` **in the emitter project**:
@@ -386,7 +391,7 @@ This skill produces, in the emitter project:
 - `src/{language}/*.ts` — emitter generator files implementing the `Emitter` interface
 - `test/{language}/*.ts` — unit tests for each generator
 - `docs/sdk-architecture/{language}.md` — SDK design document
-- Updated `oagen.config.ts` with the new emitter registered
+- Updated plugin bundle (`src/plugin.ts`) and `src/index.ts` with the new emitter registered
 
 ## Backwards Compatibility
 

package/skills/generate-emitter/references/project-scaffold.md

@@ -12,7 +12,8 @@ When `{project}/package.json` does **NOT** exist, create the following boilerpla
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
-    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" }
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
+    "./plugin": { "types": "./dist/plugin.d.ts", "import": "./dist/plugin.js" }
   },
   "scripts": {
     "build": "tsup",
@@ -76,7 +77,7 @@ export default defineConfig({
 ```ts
 import { defineConfig } from "tsup";
 export default defineConfig({
-  entry: { index: "src/index.ts" },
+  entry: { index: "src/index.ts", plugin: "src/plugin.ts" },
   format: ["esm"],
   dts: true,
   clean: true,
@@ -86,21 +87,41 @@ export default defineConfig({
 
 ## `oagen.config.ts`
 
+Minimal config for local emitter development. The canonical consumer config lives in the consumer project.
+
 ```ts
 import type { OagenConfig } from "@workos/oagen";
-const config: OagenConfig = { emitters: [] };
+import { plugin } from "./src/plugin.js";
+const config: OagenConfig = { ...plugin };
 export default config;
 ```
 
-(Step 6 of the main skill adds the emitter to this config.)
+## `src/plugin.ts`
+
+Plugin bundle export. The consumer project imports this to get all emitters, extractors, and smoke runners.
+
+```ts
+import type { OagenConfig } from "@workos/oagen";
+export const plugin: Pick<
+  OagenConfig,
+  "emitters" | "extractors" | "smokeRunners"
+> = {
+  emitters: [],
+  extractors: [],
+  smokeRunners: {},
+};
+```
+
+(Step 7 of the main skill adds the emitter to this plugin bundle.)
 
 ## `src/index.ts`
 
 ```ts
-// Barrel export — re-exports all emitters
+// Barrel export — re-exports all emitters and the plugin bundle
+export { plugin } from "./plugin.js";
 ```
 
-(Step 6 adds the re-export.)
+(Step 7 adds the emitter re-export.)
 
 ## `.gitignore`
 

package/skills/generate-extractor/SKILL.md

@@ -13,7 +13,7 @@ Scaffold a language extractor for oagen's compat verification system. An extract
 Live SDK → Extractor → ApiSurface JSON → Differ ← Generated SDK → Violations
 ```
 
-Each language needs its own extractor because public surface detection is language-specific (e.g., TypeScript exports vs. Ruby public methods vs. Python `__all__` vs. Go capitalized identifiers). An extractor implements the `Extractor` interface and is registered via `oagen.config.ts` in the emitter project.
+Each language needs its own extractor because public surface detection is language-specific (e.g., TypeScript exports vs. Ruby public methods vs. Python `__all__` vs. Go capitalized identifiers). An extractor implements the `Extractor` interface and is exported through the emitter project's plugin bundle (e.g., `workosEmittersPlugin`), which the consumer project's `oagen.config.ts` imports.
 
 ## Reference Docs
 
@@ -115,16 +115,22 @@ export const {language}Extractor: Extractor = {
 
 ## Step 3: Register the Extractor
 
-Add to `oagen.config.ts`:
+Add the extractor to the plugin bundle export (e.g., `src/plugin.ts`) and re-export from `src/index.ts`:
 
 ```typescript
-import { {language}Extractor } from './src/compat/extractors/{language}.js';
-const config: OagenConfig = {
-  emitters: [/* ... */],
-  extractors: [{language}Extractor],
+// src/plugin.ts
+import { {language}Extractor } from './compat/extractors/{language}.js';
+export const workosEmittersPlugin = {
+  extractors: [/* existing, */ {language}Extractor],
+  // ...
 };
+
+// src/index.ts
+export { {language}Extractor } from './compat/extractors/{language}.js';
 ```
 
+The consumer project's `oagen.config.ts` imports the plugin bundle, so the new extractor is automatically available.
+
 ## Step 4: Create a Fixture SDK
 
 Create a minimal but representative fixture at `test/fixtures/sample-sdk-{language}/` **in the emitter project**. It must include:
@@ -175,7 +181,7 @@ If `sdk_path` was provided, also test against the real SDK and verify all public
 ```
 === Extractor: {language} ===
 Files created:   src/compat/extractors/{language}.ts, test suite, fixture SDK
-Modified:        oagen.config.ts
+Modified:        src/plugin.ts, src/index.ts
 Validation:      Tests / Fixture extract / Determinism / Real SDK extract
 ApiSurface:      {N} classes, {N} interfaces, {N} type aliases, {N} enums, {N} exports
 ```
@@ -187,7 +193,7 @@ This skill produces, in the emitter project:
 - `src/compat/extractors/{language}.ts` — extractor implementing the `Extractor` interface with `LanguageHints`
 - `test/compat/extractors/{language}.test.ts` — extraction tests against fixture SDK
 - `test/fixtures/sample-sdk-{language}/` — minimal fixture SDK for testing
-- Updated `oagen.config.ts` with the new extractor registered
+- Updated plugin bundle (`src/plugin.ts`) and `src/index.ts` with the new extractor registered
 
 ## Common Pitfalls
 

package/skills/generate-sdk/SKILL.md

@@ -91,7 +91,7 @@ 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 "{language}Extractor\|{language}_extractor" {project}/src/plugin.ts {project}/src/index.ts
 grep -l "hints" {project}/src/compat/extractors/{language}.ts
 
 # After /verify-compat — handled by the skill itself
@@ -148,7 +148,7 @@ Only include this next section in the output if this is Scenario A:
 
 This skill produces, via its sub-skills:
 
-- A complete language emitter registered in `oagen.config.ts`
+- A complete language emitter registered in the plugin bundle (`src/plugin.ts`)
 - An API surface extractor (Scenario A only)
 - A smoke test script at `smoke/sdk-{language}.ts`
 - Generated SDK code at `{project}/sdk/`

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

@@ -136,17 +136,21 @@ Create the script **in the emitter project**:
 
 ## Step 6: Register the Smoke Runner
 
-Add to `oagen.config.ts`:
+Add the smoke runner path to the plugin bundle export (e.g., `src/plugin.ts`):
 
 ```typescript
-const config: OagenConfig = {
-  emitters: [/* ... */],
+// src/plugin.ts
+export const workosEmittersPlugin = {
   smokeRunners: {
-    {language}: './smoke/sdk-{language}.ts',
+    // existing runners...
+    {language}: path.join(smokeDir, 'sdk-{language}.ts'),
   },
+  // ...
 };
 ```
 
+The consumer project's `oagen.config.ts` imports the plugin bundle, so the new smoke runner is automatically available.
+
 ## Step 7: Validate
 
 ```bash
@@ -182,4 +186,4 @@ See `scripts/smoke/README.md` (in oagen core) for the full remediation guide. Se
 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
+- Updated plugin bundle (`src/plugin.ts`) with the smoke runner path registered