feat(codegen): templateGenerator() factory + docsFile refactor

Adds templateGenerator() as a stock generator in codegen-ts — walks a
MetaRoot via a caller-supplied walk function, renders shared Mustache
templates against the produced data dicts via the existing
@metaobjectsdev/render engine, and writes output in any format
(Markdown / HTML / JSON / YAML / text). Establishes the line: code →
hand-coded generators (ts-poet, idiomatic per-port); documents →
templateGenerator (shared Mustache templates, port-agnostic).

Refactors rc.11's docsFile() (~250 LOC of hand-coded markdown string
emit) to use the new factory: ~85 LOC of generator + data builder
helper + a shared Mustache template under codegen-ts/templates/docs/.
Adopters can override by placing same-named templates in their
project's templates/ directory (hybrid resolution per the design
doc's D1 decision).

The EntityDocData TypeScript interface is now an exported public-API
contract — template authors get type-checking; the data-dict keys are
versioned per MO major (D3 decision). docs/features/codegen-data-shapes.md
documents the canonical shapes.

Conformance fixture docs-file-basic/expected/Author.md stays
byte-identical post-refactor (proves the refactor preserves output).

Test counts: codegen-ts 419 → 433 (+14: templateGenerator suite + factory
tests + data-builder contract tests + the docsFile conformance still
green). metadata / sdk / cli unchanged.

Pairs with 19b2c58's three-way merge policy: with strategy (b) now in
the write path, the templateGenerator output benefits from the same
hand-edit-survival guarantee any other generator provides. Adopters
hand-editing entity docs will see their edits merge cleanly on
subsequent regen.

Per the design doc at metaforge/docs/private/strategy/2026-05-28-
template-driven-codegen-design.md (option 1 chosen — combined policy
fix + factory refactor in one release cycle).

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

Author: dmealing

docs/features/codegen-data-shapes.md

@@ -0,0 +1,142 @@
+# Codegen data shapes — the public contract for template authors
+
+When you write a custom Mustache template that drives a `templateGenerator()`
+instance, the data dict your template receives follows a stable, typed shape
+exported from `@metaobjectsdev/codegen-ts/generators`. This page documents
+those shapes — they are **public API**. Field keys are versioned per
+MetaObjects **major** release; deprecations are announced before removal.
+
+## Why this matters
+
+`templateGenerator()` separates three concerns:
+
+| Layer | Owner | Contract |
+|---|---|---|
+| **Data extraction** | per-port walker (TS / C# / Python / Java / Kotlin) | typed data dict |
+| **Template rendering** | shared Mustache via `@metaobjectsdev/render` | Mustache spec |
+| **File emission** | the runner + overwrite policy | three-way merge |
+
+The middle layer is **language-agnostic**: the same Mustache template that
+renders `<Entity>.md` from TypeScript walks identically from C# or Python.
+That only holds if the data dict shape is stable across ports and across
+upgrades — hence this contract.
+
+## Shapes by template
+
+### `docs/entity-page.md` → `EntityDocData`
+
+The per-entity Markdown documentation page. Populated by
+`buildEntityDocData(entity, opts)`.
+
+```ts
+interface EntityDocData {
+  generatedMarker: string;          // "<!-- @generated by ... -->"
+  entity: {
+    name: string;                   // "Author"
+    type: string;                   // "object.entity"
+    source?: string;                // "meta.blog.json"
+    package?: string;               // "acme::blog"
+    description?: string;
+  };
+  descriptionQuote?: string;        // "> ..." (each line of description)
+  preambleHeader: string;           // "**Type:** ...\n**Source:** ...\n**Package:** ..."
+  storage?: { tableHeader: string; rows: StorageFieldDoc[] };
+  hasStorage?: boolean;
+  identities?: IdentityDoc[];
+  hasIdentities?: boolean;
+  relationships?: RelationshipDoc[];
+  hasRelationships?: boolean;
+  validation: {
+    insertSchema: string;           // "AuthorInsertSchema"
+    updateSchema: string;           // "AuthorUpdateSchema"
+    entityFile: string;             // "Author.ts"
+    lower: string;                  // "author"
+  };
+  usedBy?: UsedByDoc[];
+  hasUsedBy?: boolean;
+  generated: GeneratedFileDoc[];    // "Generated code" bullets
+}
+```
+
+Each `StorageFieldDoc` / `IdentityDoc` / `RelationshipDoc` / `UsedByDoc`
+carries one or more **already-rendered** strings (e.g. `rowLine`, `bullet`)
+the template emits via `{{{rowLine}}}`. The escaping rules for Markdown
+table pipes, code-spans, etc. live in the **builder** so templates stay
+trivial and cross-port walkers don't have to re-derive the rules.
+
+**Adopter override path.** Drop a `templates/docs/entity-page.md.mustache`
+file into your project; the project's `templates/` directory takes precedence
+over the framework defaults. Same for any partial under `templates/docs/`.
+
+### Section-presence flags (`hasX`)
+
+Mustache cleanly iterates an array (`{{#identities}}...{{/identities}}`) but
+has no native "is this array non-empty?" check that doesn't also iterate.
+To emit a section header (`## Identity`) ONCE per section, we provide both:
+
+- `identities: IdentityDoc[]` — drive the bullet loop
+- `hasIdentities: true` — drive the section-header conditional
+
+```mustache
+{{#hasIdentities}}
+
+## Identity
+
+{{#identities}}
+- {{{bullet}}}
+{{/identities}}
+{{/hasIdentities}}
+```
+
+Same pattern for `hasStorage`, `hasRelationships`, `hasUsedBy`.
+
+## Versioning policy
+
+- **Adding a new field** is a minor-version event (`0.7.x → 0.8.x`).
+  Existing templates keep working.
+- **Renaming or removing a field** requires a deprecation cycle:
+  - Major version N: the new name is added; the old name is kept and
+    emits a deprecation warning at codegen time. The
+    `meta verify --strict` check fails on use of the deprecated key.
+  - Major version N+1: the old name is removed.
+- **Re-shaping a nested object** (e.g. flattening `validation.lower` to
+  top-level `lowerName`) is a breaking change requiring the same
+  deprecation cycle.
+
+The conformance fixtures gate the shapes per port: any port whose walker
+emits an out-of-spec shape fails the cross-port conformance suite.
+
+## Where to find the types
+
+```ts
+import type {
+  EntityDocData,
+  StorageFieldDoc,
+  IdentityDoc,
+  RelationshipDoc,
+  UsedByDoc,
+  GeneratedFileDoc,
+} from "@metaobjectsdev/codegen-ts/generators";
+
+import { buildEntityDocData, templateGenerator } from "@metaobjectsdev/codegen-ts/generators";
+```
+
+Each type is intentionally narrow — fields are required iff the corresponding
+section MUST appear in every entity's docs output. Optional fields use
+`?` and templates check via `{{#fieldName}}...{{/fieldName}}`.
+
+## Adding new template families
+
+To add a new shape (e.g. for an HTML docs site, an OpenAPI spec, or a
+Mermaid diagram):
+
+1. Export a typed `interface XxxData` from a sibling module of
+   `docs-data.ts`.
+2. Provide a `buildXxxData(input, opts)` builder.
+3. Ship a default template at `templates/<group>/<source>.mustache` inside
+   `codegen-ts`.
+4. Add a conformance fixture that locks the expected output.
+5. Document the new shape on this page under a new section.
+
+The `templateGenerator({ walk, template, format })` factory does the rest —
+no new generator scaffolding is needed.

server/typescript/packages/codegen-ts/package.json

@@ -17,7 +17,7 @@
       "default": "./dist/generators/index.js"
     }
   },
-  "files": ["dist", "src", "README.md", "LICENSE"],
+  "files": ["dist", "src", "templates", "README.md", "LICENSE"],
   "scripts": {
     "build": "tsc -p .",
     "typecheck": "tsc -p tsconfig.typecheck.json"
@@ -35,6 +35,7 @@
   "publishConfig": { "access": "public" },
   "dependencies": {
     "@metaobjectsdev/metadata": "workspace:*",
+    "@metaobjectsdev/render": "workspace:*",
     "@biomejs/js-api": "^0.7.0",
     "@biomejs/wasm-nodejs": "^1.9.4",
     "ts-poet": "^6.10.0"
@@ -46,7 +47,6 @@
   "devDependencies": {
     "@biomejs/biome": "^1.9.0",
     "@metaobjectsdev/codegen-ts-react": "workspace:*",
-    "@metaobjectsdev/render": "workspace:*",
     "bun-types": "latest",
     "drizzle-orm": "^0.36.0",
     "hono": "^4.6.0",