Merge origin/main into sp-g-registry-conformance (FR-017 + SP-G); reconcile registry coverage snapshot (template.output attrs now exercised by main's new template-doc fixtures)

Auto-merge was clean (0 conflicts). The only semantic reconciliation needed was
regenerating fixtures/registry-conformance/coverage-report.json: main's new
template-doc-{document,email} doc fixtures now exercise six previously-untested
template.output attrs (htmlBodyRef, kind, maxChars, requiredTags, subjectRef,
textBodyRef) — pure coverage progress, no newly-untested subtype.

Verified across all 5 ports. No C# codegen drift (drift test green — M:N nav
still not emitted per FR-017 Phase 3, so our committed .g.cs stayed valid).
conformance.yml auto-merge kept both sides (our registry-conformance TS lines +
main's generator-registry-conformance CI jobs in C#/Java/Kotlin/Python). No
attr.stringarray reintroduction by main. New generator-registry-conformance
corpus green in every port.

Pre-existing-on-main failures (NOT merge-induced, reproduced on a pristine main
checkout): template-doc-document / template-doc-email fail the strict metadata
conformance runners (TS/C#/Java) with "fixture declares no expectation files" —
main's doc fixtures live under fixtures/conformance/ but ship only expected/*.md,
which the strict runners reject (Python's tolerant runner passes). Kotlin
integration-tests-kotlin KotlinCodegenMatchesReferenceTest timestamp drift
(main commit f237c23/f9ed09d7) is Docker-gated and untouched by this merge.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dmealing

.github/workflows/conformance.yml

@@ -57,6 +57,11 @@ jobs:
           cd ../render && bun test test/render-conformance.test.ts test/verify-conformance.test.ts test/extract/extract-conformance.test.ts test/output-prompt-conformance.test.ts
           # Validator-parity corpus (generated input validation). No Docker.
           cd ../integration-tests && bun test test/validation-conformance.test.ts
+          # Doc-template + CLI suites: byte-identity template gate, embedded-template
+          # gate, neutrality / collision guards, and the docs golden corpus +
+          # `meta docs` command. Whole-package so future tests auto-run. No Docker.
+          cd ../codegen-ts && bun test
+          cd ../cli && bun test
 
       - name: C# conformance
         if: matrix.language == 'csharp'
@@ -67,6 +72,8 @@ jobs:
           dotnet test MetaObjects.Render.Tests/MetaObjects.Render.Tests.csproj --nologo --verbosity quiet
           # Validator-parity corpus (generated DataAnnotations input validation).
           dotnet test MetaObjects.Codegen.Tests/MetaObjects.Codegen.Tests.csproj --filter "FullyQualifiedName~ValidationConformance" --nologo --verbosity quiet
+          # Generator stable-name registry conformance (ADR-0021 D3).
+          dotnet test MetaObjects.Codegen.Tests/MetaObjects.Codegen.Tests.csproj --filter "FullyQualifiedName~GeneratorRegistryConformance" --nologo --verbosity quiet
 
       - name: Java conformance
         if: matrix.language == 'java'
@@ -80,8 +87,9 @@ jobs:
           mvn -pl metadata test -Dtest='ConformanceTest,YamlConformanceTest,ObjectModelConformanceTest' -q
           # Byte-exact render / verify / extract / output-prompt corpora (render module).
           mvn -pl render test -Dtest='RenderCrossPortReportTest,VerifyConformanceTest,ExtractConformanceTest,OutputPromptConformanceTest' -q
-          # Validator-parity corpus (generated DTO jakarta.validation, codegen-spring module).
-          mvn -pl codegen-spring test -Dtest='ValidationConformanceTest' -q
+          # Validator-parity corpus (generated DTO jakarta.validation, codegen-spring module)
+          # + generator stable-name registry conformance (ADR-0021 D3).
+          mvn -pl codegen-spring test -Dtest='ValidationConformanceTest,GeneratorRegistryConformanceTest' -q
 
       - name: Python conformance
         if: matrix.language == 'python'
@@ -93,6 +101,8 @@ jobs:
           uv run pytest tests/render -q
           # Validator-parity corpus (generated Pydantic input validation).
           uv run pytest tests/codegen/test_validation_conformance.py -q
+          # Generator registry CLI ergonomics (gen --list / --generators selection, ADR-0021 D3).
+          uv run pytest tests/codegen/test_cli_registry.py -q
 
   conformance-kotlin:
     # Kotlin (codegen-kotlin, KotlinPoet on the JVM) ships no loader / YAML /
@@ -117,8 +127,9 @@ jobs:
           # SNAPSHOT-resolution race when the test module references freshly-built
           # artifacts.
           mvn -pl codegen-kotlin -am install -DskipTests -q
-          # object-model + output-prompt + validator-parity corpora (the corpora Kotlin has).
-          mvn -pl codegen-kotlin test -Dtest='ObjectModelConformanceTest,OutputPromptConformanceTest,ValidationConformanceTest' -q
+          # object-model + output-prompt + validator-parity corpora (the corpora Kotlin has)
+          # + generator stable-name registry conformance (ADR-0021 D3).
+          mvn -pl codegen-kotlin test -Dtest='ObjectModelConformanceTest,OutputPromptConformanceTest,ValidationConformanceTest,GeneratorRegistryConformanceTest' -q
 
   completeness-gate:
     needs: [conformance, conformance-kotlin]
@@ -128,3 +139,19 @@ jobs:
       - uses: oven-sh/setup-bun@v2
       - run: bun install
       - run: cd server/typescript/packages/metadata && bun run conformance:mutation
+
+  doc-template-drift:
+    # Fails if the bundled package copy of the canonical doc templates, or the
+    # embedded-templates TS module (used by the standalone `meta` binary), is
+    # stale. sync-doc-templates.sh reproduces both from the canonical root
+    # templates/docs/ source; a non-empty diff means a dev forgot to run it.
+    needs: fixture-lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install
+      - name: Regenerate bundled + embedded doc templates from canonical
+        run: bash scripts/sync-doc-templates.sh
+      - name: Fail if synced/generated doc-template artifacts are stale
+        run: git diff --exit-code -- server/typescript/packages/codegen-ts/templates server/typescript/packages/codegen-ts/src/render-engine/embedded-templates.generated.ts

docs/features/cli.md

@@ -23,24 +23,64 @@ command surface splits in two:
 | Project scaffold (`init`) | Node `meta` | `meta init` | TS projects |
 | **Schema migrate** | **Node `meta`** | `meta migrate` | **any backend** — schema is Node-only (ADR-0015) |
 | **Schema drift** (`verify --db`) | **Node `meta`** | `meta verify --db` | **any backend** — live-DB drift, Node-only |
+| **Codegen drift** (`verify --codegen`) | **Node `meta`** | `meta verify --codegen` | TS reference (ADR-0021 D2) — regen-to-temp + diff committed output |
+| **Template/prompt drift** (`verify --templates`) | **Node `meta`** | `meta verify --templates` | TS reference (ADR-0021 D2) — `{{field}}`↔payload; the bare-`verify` default |
 | TS codegen | Node `meta` | `meta gen` | TS projects |
-| C# codegen | `dotnet meta` | `dotnet meta gen` / `verify` | a .NET tool (`ToolCommandName=dotnet-meta`); invoked `dotnet meta` so it never shadows the Node `meta` |
+| C# codegen | `dotnet meta` | `dotnet meta gen` / `verify --templates` / `verify --codegen` | a .NET tool (`ToolCommandName=dotnet-meta`); invoked `dotnet meta` so it never shadows the Node `meta`; ships the ADR-0021 D2 subverbs (`--db` rejected, exit 2; bare `verify` = `--templates`) |
 | Java/Kotlin codegen | Maven plugin | `mvn metaobjects:generate` (`meta:gen`) | Kotlin generators run through the same goal — see below |
-| Java/Kotlin codegen drift | Maven plugin | `mvn metaobjects:verify` (`meta:verify`) | regenerate + fail on drift vs committed output (generator-neutral) |
-| Python codegen | console-script | `metaobjects gen` / `verify` | `[project.scripts] metaobjects` — **not** `meta` (that's the Node schema CLI) |
-
-## Two meanings of `verify` — keep them distinct
-
-- **Schema `verify --db`** (Node `meta`, any backend): live-DB drift — does the
-  database match the metadata? Node-only, ADR-0015.
-- **Codegen `verify`** (`dotnet meta verify`, `mvn meta:verify`, `metaobjects
-  verify`): regenerate code from metadata into a temp location and fail if it
-  differs from the committed generated output — "a teammate changed metadata
-  without regenerating → caught". This is the enterprise-CI primitive added per
-  port; it does **not** touch a database.
-- (Separately, the FR-004 **template/prompt** drift check — `Renderer.verify` —
-  also surfaces under `verify` in the ports that ship it; it checks `{{...}}`
-  references against the payload VO. It is a third, orthogonal facet.)
+| Java/Kotlin verify | Maven plugin | `mvn metaobjects:verify -Dmeta.verify.mode=codegen\|templates` (`meta:verify`) | parameter-driven ADR-0021 D2 modes (one goal covers BOTH Java + Kotlin): `codegen` (default, back-compat — regen + fail on drift vs committed output, generator-neutral) / `templates` (`{{field}}`↔payload drift via the render `Verify` engine). `db` rejected ("schema verify is the migrate engine, ADR-0015") |
+| Python codegen | console-script | `metaobjects gen` / `verify --codegen` / `verify --templates` | `[project.scripts] metaobjects` — **not** `meta` (that's the Node schema CLI); ships the ADR-0021 D2 subverbs (`--db` rejected, exit 2) |
+
+## `verify` is one verb with explicit subverbs (ADR-0021 D2)
+
+Historically `verify` meant *different things per port* (TS/C# = template drift,
+Java/Python = codegen drift, `--db` = schema drift) and the modes were not
+parallel. [ADR-0021 D2](../../spec/decisions/ADR-0021-codegen-surface-coherence.md)
+fixes that: **`verify` is one verb with three explicit subverbs**, one
+vocabulary everywhere, each port implementing the modes it supports.
+
+| Subverb | What it checks | Touches a DB? |
+|---|---|---|
+| `verify --db` | **Schema drift** — does the live database (or snapshot) match the metadata? (migrate engine, ADR-0015) | yes |
+| `verify --codegen` | **Codegen drift** — regenerate from metadata into a temp dir and fail if it differs from the committed generated output. Catches "metadata changed but `meta gen` wasn't re-run" and "someone hand-edited a generated file". | no |
+| `verify --templates` | **Template/prompt drift** — `Renderer.verify` checks each `template.*` node's `{{field}}` references against its payload VO (FR-004). | no |
+
+Rules of the contract:
+
+- **Combinations aggregate.** Pass any mix (`verify --db --codegen --templates`);
+  each selected mode runs and the **exit code is non-zero if *any* mode reports
+  drift**.
+- **Bare `verify` = the port's documented back-compat default.** TS/C# default to
+  `--templates`; Java/Python default to `--codegen`. In every case bare `verify`
+  also prints a one-line note advertising the explicit subverbs.
+- **`--codegen` needs to know where the committed output lives.** It diffs
+  against the configured `outDir` (and any per-target `outDir`) from
+  `metaobjects.config.ts`. With no config it errors clearly (exit 2) rather than
+  silently passing — there is nothing to diff against.
+- **Unknown/invalid flag → exit 2** with usage.
+
+**Port status (staged per ADR-0021):** the **TypeScript Node `meta` is the
+reference** and implements all three subverbs today. **Python `metaobjects`
+ships the subverbs**: `verify --codegen` (regen-to-temp + diff vs `--out`, the
+historical default), `verify --templates` (each `template.*` node's `{{field}}`
+↔ payload-VO field tree via the render `verify()` gate, resolving refs through a
+filesystem provider rooted at `--templates-root`), and `verify --db` which is
+**cleanly rejected with exit 2** ("schema verify is the migrate engine,
+ADR-0015"). Bare `verify` stays `--codegen` for back-compat. The **C# `dotnet
+meta`** port likewise ships the codegen-side subverbs: `verify --templates` (its
+historical template/prompt drift gate, the C# back-compat default), `verify
+--codegen` (regenerate the default generator suite to a temp dir and diff against
+the committed `--out` tree, never touching it), and a **clean `--db` rejection
+(exit 2)** — bare `dotnet meta verify` keeps `--templates` and prints the subverb
+note. The **Java/Kotlin `mvn meta:verify`** port expresses the same vocabulary as a
+`mode` parameter (Maven goals are parameter-driven, not flag-driven): `-Dmeta.verify.mode=codegen`
+(default, byte-identical to the historical goal — regen-to-temp + diff vs committed
+output) and `-Dmeta.verify.mode=templates` (each `template.*` node's `{{field}}`↔payload-VO
+field tree via the render `Verify` engine, resolving refs through a filesystem provider rooted
+at `-Dmeta.verify.templateRoot`). The one goal covers BOTH Java (`codegen-spring`) and Kotlin
+(`codegen-kotlin`) since they share it. `mode=db` is **cleanly rejected** ("schema verify is the
+migrate engine, ADR-0015"); an unknown mode fails listing the valid ones. (Schema `--db` remains
+Node-only by the ADR-0015 design — see below.)
 
 ## Schema is Node-only — by design
 

docs/superpowers/plans/2026-06-02-docs-binary-and-providers.md

@@ -0,0 +1,54 @@
+# `meta docs` binary templates + config providers — implementation plan
+
+> REQUIRED SUB-SKILL: superpowers:subagent-driven-development.
+
+**Goal:** Close the two documented follow-ups from the neutral-metadata-docs feature so `meta docs` is a fully standalone Tier-2 capability:
+1. Framework doc templates resolve inside the `bun --compile` `meta` binary (today they don't — only adopter-provided `templates/` work there).
+2. `meta docs` loads `metaobjects.config.ts` providers so adopters with custom field/object types can generate docs.
+
+**Architecture:** Both `codegen-ts` and `cli` build with `tsc` (the binary is built separately with `bun build --compile`). So embedding cannot use a `.mustache` text-import (tsc rejects it). Instead generate a plain-string module from the canonical `templates/`, imported by the framework provider with an on-disk-first / embedded-fallback chain. Config-provider loading mirrors `gen.ts`.
+
+**Tech:** TypeScript, bun 1.3.8, tsc builds, the existing `render()`/`projectProvider` chain.
+
+---
+
+## Task 1: Embedded framework-template fallback (fixes binary)
+
+**Intent:** `FrameworkTemplatesProvider` resolves the framework doc templates from the embedded map when the on-disk `templates/` dir is unavailable (the compiled binary). On-disk stays FIRST so dev/install layouts keep honoring local edits + adopter overrides.
+
+**Files:**
+- Create `scripts/generate-embedded-templates.ts` (bun script) — reads canonical `templates/docs/*.mustache`, writes `server/typescript/packages/codegen-ts/src/render-engine/embedded-templates.generated.ts` exporting `export const EMBEDDED_FRAMEWORK_TEMPLATES: Record<string, string> = { "docs/<name>.md": <content>, ... }` (key = the ref WITHOUT `.mustache`, matching how refs resolve; value = exact file text). Plain string literals only (tsc-safe). Header `// @generated from templates/docs/*.mustache — DO NOT EDIT; run scripts/generate-embedded-templates.ts`.
+- Extend `scripts/sync-doc-templates.sh` to ALSO invoke the generator (so one command syncs the package copy AND regenerates the embedded module from canonical).
+- Modify `server/typescript/packages/codegen-ts/src/render-engine/framework-provider.ts` — `FrameworkTemplatesProvider.resolve(ref)`: keep the on-disk lookup first; if it returns undefined, return `EMBEDDED_FRAMEWORK_TEMPLATES[ref]` (or undefined). Update the stale comment (lines ~33-35) that references a non-existent embedded fallback to describe the real one.
+- Test: `server/typescript/packages/codegen-ts/test/embedded-templates.test.ts` — (a) GATE: every canonical `templates/docs/*.mustache` has a matching embedded entry whose content is byte-identical (prevents drift); (b) the embedded map covers exactly the canonical set (no missing/extra); (c) simulate the binary case: a `FrameworkTemplatesProvider` whose on-disk dir is unresolved still resolves `docs/entity-page.md` + `docs/template-page.md` from the embedded map.
+
+- [ ] Step 1: Write `embedded-templates.test.ts` (drift gate + binary-fallback). Run → FAIL (generated module doesn't exist).
+- [ ] Step 2: Write `scripts/generate-embedded-templates.ts`; run it to produce `embedded-templates.generated.ts`. Wire it into `sync-doc-templates.sh`.
+- [ ] Step 3: Update `FrameworkTemplatesProvider.resolve` (on-disk → embedded fallback) + fix the stale comment.
+- [ ] Step 4: Run → PASS the new test + `bun test packages/codegen-ts` (existing docs/golden/byte-identity gates unaffected — on-disk still wins in dev). Report counts.
+- [ ] Step 5: Binary proof — `cd packages/cli && bun build ./bin/meta.ts --compile --outfile /tmp/meta-test --external @biomejs/wasm-bundler --external @biomejs/wasm-web`, then run `/tmp/meta-test docs <fixture-metadata> --out /tmp/docsout` from a dir with NO `templates/` and assert entity + template `.md` files are produced (framework templates now resolve from the embed). Report the result. (If building the full binary is too heavy/slow, at minimum assert the embedded provider resolves with on-disk forced-undefined — but attempt the real binary.)
+- [ ] Step 6: Commit. `feat(codegen-ts): embed framework doc templates so they resolve in the compiled binary`
+
+## Task 2: `meta docs` loads config providers (fixes custom types)
+
+**Intent:** `meta docs` loads `metaobjects.config.ts` (best-effort) and passes `providers` to `loadMemory`, so adopters with custom field/object types can generate docs — mirroring `gen.ts`.
+
+**Files:**
+- Modify `server/typescript/packages/cli/src/commands/docs.ts` — before `loadMemory`, best-effort `loadMetaobjectsConfig(projectRoot)` (import from `../lib/load-metaobjects-config.js`, as gen.ts does); if it succeeds, pass `{ providers: forgeConfig.providers }` to `loadMemory` (guard undefined, exactly like `gen.ts:42-43`). If config loading fails/absent, proceed config-less (docs must still work with no config — do NOT hard-fail; gen treats config as required, docs must NOT).
+- Test: `server/typescript/packages/cli/test/docs-command.test.ts` — add a case: a fixture project WITH a `metaobjects.config.ts` (or the config-loading mechanism) declaring a custom field/object type used in its metadata; `meta docs` loads + emits docs without a "type does not resolve" failure. Also keep/confirm the existing no-config case still works (config-less).
+
+- [ ] Step 1: Write the custom-type-with-config docs test (mirror how gen's config tests set up `loadMetaobjectsConfig`/a fixture config). Run → FAIL (docs currently ignores providers → custom type fails to load).
+- [ ] Step 2: Add best-effort config+providers loading to `docs.ts` (mirror gen.ts; non-fatal when absent).
+- [ ] Step 3: Run → PASS the new test + the existing no-config docs tests + `bun test packages/cli`. Report counts.
+- [ ] Step 4: Commit. `feat(cli): meta docs loads metaobjects.config.ts providers (custom types)`
+
+## Task 3: Closeout
+- [ ] Full suites: `bun test packages/codegen-ts packages/cli packages/render` green; counts.
+- [ ] Hygiene (merge-base diff): no private names/home paths/node_modules/bunfig/lockfile/dist.
+- [ ] Whole-branch code-review + simplifier; fix findings.
+- [ ] Forward-merge to main, push, remove worktree, delete branch, update memory.
+
+## Notes / guards
+- The embedded module is a GENERATED artifact gated against canonical `templates/` — edit root templates, run `sync-doc-templates.sh` (now also regenerates the embed). Three representations (root canonical, package bundled copy, embedded module) all gated byte-identical.
+- On-disk MUST stay first in `FrameworkTemplatesProvider` so adopter overrides + dev edits win; embedded is fallback only.
+- Don't touch native code generators, the render engine, other ports, or doc neutrality. Public-repo hygiene.