@workos/oagen 0.6.0 → 0.8.0

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 |

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.6.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