Merge branch 'worktree-agent-a75154ea111a2b638'

# Conflicts:
#	agent-context/skills/metaobjects-audit/references/csharp.md
#	docs/features/own-your-codegen.md

Author: dmealing

.claude/rules/codegen-architecture.md

@@ -24,7 +24,14 @@ interface Generator {
 }
 ```
 
-Helpers `perEntity()` and `oncePerRun()` cover the common "file per entity" / "one-shot" cases.
+Helpers `perEntity()`, `perPackage()` and `perModel()` cover the per-object / per-package /
+whole-model scopes (`oncePerRun()` is the deprecated alias of `perModel()`).
+
+**Writing a generator of your own is the primary path** (ADR-0034 Amendment 4): `meta
+generator new <name> [--scope entity|package|model]` writes a working one into
+`codegen/generators/` and wires it into the config. Model reads an owned generator needs
+are exported from the package root (`objectRefTarget`, `enumValues`, `servedPath`, the case
+helpers); the guide and every port's shape are in `docs/recipes/write-your-own-generator.md`.
 
 **Built-in factories**: `entityFile`, `queriesFile`, `routesFile`, `formFile`, `barrel`. Per ADR-0034 (scaffold-and-own) and its Amendment 2 (opt-in codegen), `meta init` scaffolds `codegen/generators/` EMPTY with `generators: []`; `meta gen --list --probe` is the catalog, and `meta eject <name>...` copies each chosen reference template into the consumer repo at `codegen/generators/*.ts` and prints the import and entry to wire. The owned copy is the ONLY import path for `entityFile`/`queriesFile`/`routesFile`/`barrel`: the deprecated `@metaobjectsdev/codegen-ts/generators` re-export of them was **removed at the 1.0 cut**.
 

README.md

@@ -17,7 +17,7 @@ model. Your hand-written logic stays yours.
 supposed to do — that your agent reads and writes. Two things happen to it:
 
 - **Generate.** The boring parts are derived from it, in TypeScript, Java, Kotlin, C#
-  and Python — at build time by reference generators you copy into your repo and own,
+  and Python — at build time by generators you write or copy into your repo and own,
   or at runtime from the live model. Nothing proprietary in the output.
 - **Verify.** The build fails when generated code drifts from the model and when a
   prompt's payload no longer matches what it's told — and it fails or warns when a
@@ -183,7 +183,7 @@ MetaObjects has two layers, and only the first is a promise
 
 | | Core — guaranteed | Helpers — yours |
 |---|---|---|
-| **What** | The metamodel, loader, canonical format and registry; runtime metadata access (the `ObjectManager`, not the HTTP adapters that mount it); schema migrations (`meta migrate`); the drift gates (`meta verify`); prompt render and the reply parser | Every generator that writes application code into your repo: routes, controllers, ORM wiring, DTOs, forms, grids, hooks |
+| **What** | The metamodel, loader, canonical format and registry; runtime metadata access (the `ObjectManager`, not the HTTP adapters that mount it); schema migrations (`meta migrate`); the drift gates (`meta verify`); prompt render and the reply parser | Every generator that writes code into your repo — the ones you write for the outputs you need, and the reference routes, controllers, ORM wiring, DTOs, forms, grids and hooks you copy |
 | **Promise** | Conformance-gated, the same behaviour in every port that ships it, covered by the [compatibility policy](docs/compatibility-policy.md) | Reference starting points that compile and pass their reference fixtures. Copy one with `meta eject` and change it freely |
 | **A defect is** | A MetaObjects bug, fixed in a release | A bug in the reference, fixed there; your copy is yours |
 
@@ -202,12 +202,17 @@ complete in all five ports; MCP exposure of declared prompts/tools is the one re
 roadmap item. The fifth has been dogfooded on maintainer-owned projects only, and the
 sixth ships two libraries at their own stability labels:
 
-1. **Codegen** *(reference generators you own, ejectable in every port)* — starting points that emit per-language
-   code (Drizzle/Zod + Fastify for TS, Spring REST + DTO + repository for Java,
-   `data class` + Exposed for Kotlin, EF Core record + ASP.NET routes for C#, Pydantic +
-   FastAPI for Python). Copy the ones you need, change them, and regenerate with
-   hand-edit-preserving three-way merge. The engine that runs them is core; their output
-   is yours.
+1. **Codegen** *(generators you write and own, in every port)* — on the core, you build
+   the generators your application needs: OpenAPI, JSON Schema, Zod, DTOs, a client,
+   docs — anything the model describes. A generator is a name plus a function from the
+   model to files, and `verify` gates it with nothing to register; `meta generator new
+   <name>` scaffolds a working one on TypeScript, and
+   [Write your own generator](docs/recipes/write-your-own-generator.md) has every port's
+   20-line shape plus JSON Schema and OpenAPI examples to copy. The reference generators
+   (Drizzle/Zod + Fastify for TS, Spring REST + DTO + repository for Java, `data class` +
+   Exposed for Kotlin, EF Core record + ASP.NET routes for C#, Pydantic + FastAPI for
+   Python) are starting points: eject the one that is close, change it, and regenerate.
+   The engine that runs generators is core; their output is yours.
 2. **Runtime metadata** — load metadata at runtime, drive behavior dynamically
    (CRUD, validation, relationships, dynamic admin UIs; typed tool payloads are
    declared today, with MCP exposure on the roadmap).

agent-context/skills/metaobjects-audit/references/csharp.md

@@ -64,13 +64,14 @@ copies the helper runtime the generated routes call (`FilterParser`, `EfCoreFilt
 `ValueObjectValidator`, `ConstraintErrors`, `Iso8601TimestampConverter`) into
 `codegen/runtime/` under the namespace `Codegen.Runtime`. That folder is owned code, not a
 hand-rolled filter parser: do not flag it. `dotnet meta gen --list` marks each owned copy
-`identical` or `DIFFERS`.
-
-A project that has not ejected is not a finding either: running the packaged generators by
-name is a supported choice. For a shape no built-in emits, the lighter path is a
-**declarative template**: `dotnet meta gen --template-spec <json> --template-root <dir>`,
-whose entries append to your `--generators` selection. Worked example with the full JSON:
-`docs/ports/csharp.md`.
+`identical` or `DIFFERS`. A generator the project WRITES is an `IGenerator` listed in
+`codegen/Program.cs` the same way.
+
+**A finding of the form "the built-ins do not emit the shape this project needs", or a
+hand-written layer the model fully describes, resolves to a generator the project writes**
+(ADR-0034 Amendment 4), or to a declarative template (`dotnet meta gen --template-spec
+<json> --template-root <dir>`) where the shape is what matters. Recommend it; it is the
+primary path. Worked template example: `docs/ports/csharp.md`.
 
 To re-scaffold the agent-context into a C# project, use the Node `meta` CLI (the
 single agent-docs assembler per ADR-0033):

agent-context/skills/metaobjects-audit/references/python.md

@@ -59,18 +59,17 @@ regardless of server language — see the migration reference.
 
 ## Owned generators
 
-Python does not scaffold-and-own generators — they are provided by the `metaobjects`
-package and selected by stable name via `--generators`, over a **closed built-in
-registry**. There is no analog to the TS `codegen/generators/*.ts` pattern here, and no
-seam to register a generator of your own. (`--provider module:symbol` registers
-**metamodel vocabulary**, not a generator — do not read it as one.)
-
-**So do not score a Python project down for "not owning its generators", and do not
-recommend writing one.** The customization path here is the **declarative template**:
-`metaobjects gen --template-spec <json> --templates <dir>`, whose entries append to your
-`--generators` selection. A finding of the form "the built-ins do not emit the shape this project
-needs" resolves to a template-spec, not to generator code. Worked example with the full
-JSON: `docs/ports/python.md`.
+Python generators are owned the same way as on every port. `metaobjects eject <name>`
+copies a reference into `codegen/generators/`, and a generator the project WRITES is wired
+the same way — a `module:symbol` entry in `--generators` or in `metaobjects.config.yaml`,
+reading the model through `metaobjects.codegen.model_walk`. (`--provider module:symbol`
+registers **metamodel vocabulary**, not a generator — do not read it as one.)
+
+**A finding of the form "the built-ins do not emit the shape this project needs", or a
+hand-written layer the model fully describes, resolves to a generator the project writes**
+(ADR-0034 Amendment 4), or to a declarative template (`metaobjects gen --template-spec
+<json> --templates <dir>`) where the shape is what matters. Recommend it; it is the
+primary path. Worked template example: `docs/ports/python.md`.
 
 To re-scaffold the agent-context into a Python project, use the Node `meta` CLI (the
 single agent-docs assembler per ADR-0033):