@metaobjectsdev/codegen-ts 0.9.0 → 0.10.0

package/src/generators/docs-data.ts

@@ -8,7 +8,7 @@
 // for `docs/entity-page.md` (or any of the partials) reference these keys.
 //
 // `EntityDocData` is the **Markdown-flavored** data shape — it intentionally
-// mixes raw structural fields (entity, validation, generated) with
+// mixes raw structural fields (entity, constraints) with
 // **pre-rendered Markdown fragments** so cross-port walk functions (TS,
 // Python, C#, Java, Kotlin) don't have to re-derive the same escaping rules
 // (pipe-inside-cell escapes, backtick wrapping, identity bullets,
@@ -40,20 +40,30 @@
 // `{{#identities.0}}` for the same effect, at which point the flag fields
 // can be deprecated.
 
-/** One row in the Storage table — fully-rendered as a single Markdown table
- *  row. The escaping rules for pipe-inside-cell are non-trivial and live in
- *  the data builder, not the template, so templates stay trivial and the
- *  cross-port walk functions don't have to re-derive the rules. */
+/** One row in the NEUTRAL Storage table — the physical persistence MAPPING,
+ *  fully-rendered as a single Markdown table row. ADR-0020: the Storage
+ *  section documents declared physical facts only (column name → neutral
+ *  physical type → nullable → key) and makes NO language assumption — it does
+ *  NOT carry a TypeScript type or any ORM DDL. Its value-add over the
+ *  Constraints table is the field→column name mapping + any physical
+ *  `@dbColumnType` override + the key role. The pre-rendered `rowLine` keeps
+ *  templates trivial and means cross-port walk functions don't re-derive the
+ *  Markdown escaping. */
 export interface StorageFieldDoc {
   name: string;                  // raw field name (without backticks)
-  /** @markdown — already escaped TS type, with backticks. */
-  tsTypeCell: string;
-  /** @markdown — already escaped SQL expression, wrapped in backticks. */
-  sqlExprCell: string;
-  /** @markdown — already-formatted constraints text. */
-  constraintsCell: string;
+  /** @markdown — physical column name (field's `@column` if set, else the
+   *  field name), wrapped in backticks. */
+  columnCell: string;
+  /** @markdown — neutral physical type (declared `@dbColumnType` override
+   *  uppercased, else the field's logical type), wrapped in backticks. */
+  typeCell: string;
+  /** @markdown — "yes" if the field is nullable (not required, not a PK),
+   *  else "no". */
+  nullableCell: string;
+  /** @markdown — key role: "primary key", "foreign key → `Target`", or "". */
+  keyCell: string;
   /** @markdown — pre-rendered full Markdown table row, e.g.
-   *    "| `id` | `number` | `integer(\"id\")` | primary key |"
+   *    "| `id` | `long` | no | primary key |"
    *  Templates emit this verbatim via `{{{rowLine}}}`. */
   rowLine: string;
 }
@@ -77,9 +87,74 @@ export interface UsedByDoc {
   bullet: string;
 }
 
-export interface GeneratedFileDoc {
-  filename: string;              // "Author.ts"
-  description: string;           // "Drizzle table, Zod schemas, ..."
+/** One row in the unified Fields table — merges the old Storage + Constraints
+ *  cells into a single per-field row. Cells are pre-rendered Markdown so
+ *  templates stay trivial. An empty cell is "".
+ *
+ *  Replaces the previous Storage + Constraints split which duplicated facts
+ *  (field name, logical type, key role, required-vs-nullable). Following the
+ *  research synthesis: domain-model docs (FHIR, GitHub GraphQL Objects,
+ *  Schema.org) all surface one Fields/Properties table per resource. */
+export interface FieldDoc {
+  field: string;                 // raw field name (without backticks/anchor)
+  /** @markdown — anchored, badge-prefixed field cell:
+   *    `<a id="field-id"></a>🔑 \`id\``  (PK)
+   *    `<a id="field-userId"></a>🔗 \`userId\``  (FK)
+   *    `<a id="field-name"></a>\`name\``  (plain) */
+  fieldCell: string;
+  /** @markdown — neutral logical type; for FK fields, suffixed with the
+   *  cross-linked target — e.g. "`int` → [`User`](User.md)". */
+  typeCell: string;
+  /** @markdown — "yes" / "" — whether the field is required (or a PK). */
+  requiredCell: string;
+  /** @markdown — physical persistence info, ONLY when interesting:
+   *    `@column` override that differs from the field name → "`UserId`"
+   *    `@dbColumnType` set → "`UserId` `UUID`"  (or "`Data` `JSONB`" when
+   *      the field name happens to match the column)
+   *  Empty when field name == column AND no @dbColumnType override. */
+  storageCell: string;
+  /** @markdown — all the rules: validators (regex/length/numeric), default,
+   *  enum value set, extends EnumName, references, unique. Joined by " · ". */
+  rulesCell: string;
+}
+
+/** One expanded per-field detail entry — rendered as a sub-section below
+ *  the at-a-glance Fields table. ONLY emitted for fields with non-trivial
+ *  content (@description / @summary / validators / extends-enum / FK ref /
+ *  default / column-override). Skipped for plain typed fields with nothing
+ *  extra to surface — keeps the entity page from ballooning with empty
+ *  stubs.
+ *
+ *  The `block` is fully pre-rendered Markdown so the template is trivial
+ *  (`{{{block}}}` per row) and cross-port walks emit consistent output
+ *  without re-implementing the layout.
+ *
+ *  Authoring path: any field that wants surface in this section just sets
+ *  `@description` and/or `@summary` in the metadata YAML. Mirrors the
+ *  per-entity pattern. */
+export interface FieldDetailDoc {
+  field: string;                 // raw field name (without backticks)
+  /** @markdown — the full per-field block, headed by `### \`fieldName\``
+   *  and followed by italic summary, description paragraph, validator
+   *  bullets, type/FK/extends/default lines. */
+  block: string;
+}
+
+/** Deprecated alias for {@link FieldDoc} — kept for back-compat in case any
+ *  external template author destructured the old ConstraintRow shape.
+ *  @deprecated use FieldDoc */
+export interface ConstraintRow {
+  field: string;                 // raw field name (without backticks)
+  /** @markdown — "yes" / "" — whether the field is required (or a PK). */
+  required: string;
+  /** @markdown — neutral logical type cell, e.g. "`string`", "`enum`",
+   *  "`Address[]`". */
+  type: string;
+  /** @markdown — size/range limits, e.g. "maxLength: 200" — "" if none. */
+  limits: string;
+  /** @markdown — declared rules: enum value sets, patterns, validators,
+   *  uniqueness, default — "" if none. */
+  rules: string;
 }
 
 export interface EntityDocData {
@@ -96,6 +171,7 @@ export interface EntityDocData {
     source?: string;             // "meta.blog.json"
     package?: string;            // "acme::blog"
     description?: string;        // raw description text (may be multi-line)
+    summary?: string;            // raw summary text (single line)
   };
 
   /** @markdown — description as a blockquote (one `> ` per line). Present
@@ -104,16 +180,49 @@ export interface EntityDocData {
    *  constructs. */
   descriptionQuote?: string;
 
+  /** @markdown — `@summary` rendered as a one-line italic lead-in (e.g.
+   *  `*Tracks ...*`). Present iff `entity.summary` is set. Distinct from
+   *  `descriptionQuote` (a blockquote) so an entity that carries BOTH
+   *  surfaces both — short headline above, expanded paragraph below. */
+  summaryLead?: string;
+
+  /** @markdown — fenced ```mermaid erDiagram block``` showing the focal
+   *  entity plus its direct in/out FK neighbors (1-hop). Replaces the
+   *  cognitive load of the whole-model graph with an in-context view.
+   *  Mirrors the dbdocs pattern. Skipped when the entity has no neighbors. */
+  neighborhoodErBlock?: string;
+  /** Gate flag for Mustache — true iff `neighborhoodErBlock` is present.
+   *  See the "Mustache idiom note" at the top of this file. */
+  hasNeighborhoodEr?: boolean;
+
   /** @markdown — multi-line preamble block: Type / Source? / Package?, one
    *  per line, in the exact order matching the legacy emitter. Always
    *  present. */
   preambleHeader: string;
 
-  /** Storage section. Present iff the entity has a writable rdb source and
-   *  is NOT object.value. */
+  /** Unified Fields section — one row per field, merging the per-field facts
+   *  the old Storage + Constraints tables split between. Always emitted when
+   *  the entity has any fields. */
+  fields: {
+    hasFields: boolean;
+    rows: FieldDoc[];
+  };
+
+  /** Expanded per-field details — emitted as a "## Field details" section
+   *  AFTER the at-a-glance Fields table. Skips fields with nothing extra to
+   *  say (no description, no summary, no validators, no extends, no default,
+   *  no FK, no column override) so the section doesn't balloon the page. */
+  fieldDetails: {
+    hasDetails: boolean;
+    rows: FieldDetailDoc[];
+  };
+
+  /** @deprecated Storage section. The merged Fields table covers this now;
+   *  the old shape is still populated for adopters with custom templates that
+   *  reference it, but new templates should use `fields` instead. */
   storage?: {
-    /** @markdown — pre-rendered "| Field | ... |\n|---|---|---|---|" header
-     *  pair. */
+    /** @markdown — pre-rendered "| Column | Type | Nullable | Key |\n|---|...|"
+     *  header pair. */
     tableHeader: string;
     rows: StorageFieldDoc[];
   };
@@ -131,13 +240,14 @@ export interface EntityDocData {
   /** Present-and-non-empty flag for the relationships section. */
   hasRelationships?: boolean;
 
-  /** Validation section — RAW (not Markdown-flavored). Always emitted.
-   *  Custom non-Markdown templates can rely on these fields. */
-  validation: {
-    insertSchema: string;        // "AuthorInsertSchema"
-    updateSchema: string;        // "AuthorUpdateSchema"
-    entityFile: string;          // "Author.ts"
-    lower: string;               // "author" (lowercased first letter)
+  /** @deprecated Constraints section. The merged Fields table covers this
+   *  now; the old shape is still populated for adopters with custom templates
+   *  that reference it, but new templates should use `fields` instead. */
+  constraints: {
+    /** True iff there is at least one row to render (objects always have
+     *  fields, so this is generally true; gates the section header). */
+    hasConstraints: boolean;
+    rows: ConstraintRow[];
   };
 
   /** "Used by" — present iff any templates declare `@payloadRef` → this
@@ -149,6 +259,7 @@ export interface EntityDocData {
   /** Present flag for the storage section. */
   hasStorage?: boolean;
 
-  /** Generated-code section — always emitted (at minimum the entity file). */
-  generated: GeneratedFileDoc[];
+  /** Cross-links to this entity's generated-SDK api page, one per api surface
+   *  (per language). Present only when api surfaces are emitted with the model. */
+  apiRefs?: Array<{ label: string; href: string; last?: boolean }>;
 }

package/src/generators/docs-file.ts

@@ -18,30 +18,72 @@
 // byte-for-byte. If you're hacking on this and the conformance test
 // breaks, the refactor is the bug, not the fixture.
 
-import type { MetaObject } from "@metaobjectsdev/metadata";
+import type { MetaObject, MetaRoot } from "@metaobjectsdev/metadata";
+import { TYPE_TEMPLATE, TEMPLATE_SUBTYPE_OUTPUT } from "@metaobjectsdev/metadata";
 import { render } from "@metaobjectsdev/render";
-import type { Generator, GeneratorFactory } from "../generator.js";
-import { entityOutputPath } from "../import-path.js";
+import type { Provider } from "@metaobjectsdev/render";
+import type { Generator, GeneratorFactory, EmittedFile } from "../generator.js";
+import {
+  docPageOutputPath,
+  docPageHref,
+  docPageNode,
+  apiSurfaceHref,
+  assertNoDuplicateDocPaths,
+  type DocPageNode,
+  type DocPagePlacement,
+} from "../docs-paths.js";
 import { projectProvider } from "../render-engine/framework-provider.js";
+import { renderMermaidErBlock } from "../templates/mermaid-er.js";
 import { buildEntityDocData } from "./docs-data-builder.js";
+import { buildTemplateDocData } from "./template-doc-builder.js";
+import type { OutputLayout } from "../import-path.js";
+
+// The neutral OVERVIEW/index page. GitHub (and most doc-site renderers) treat a
+// folder's README.md as its landing page, so the model overview lands here.
+const INDEX_FILENAME = "README.md";
+// The index lives at the docs ROOT (package-less) in BOTH layouts — links are
+// computed relative to root via docPageHref.
+const INDEX_NODE: DocPageNode = { name: "README" };
 
 export interface DocsFileOpts {
   filter?: (entity: MetaObject) => boolean;
   target?: string;
+  /** When set, one or more api surfaces are emitted alongside the model surface,
+   *  each under its own sub-directory (e.g. `"api/ts"`) with a per-language label.
+   *  docsFile then cross-links each model entity page to ALL its api pages and
+   *  adds an "API reference" section to the index, every href computed via the
+   *  shared `apiSurfaceHref` so it resolves relative in BOTH layouts (or absolute
+   *  when a `baseUrl` is given). ABSENT/empty ⇒ model-only output (byte-identical
+   *  to historical behaviour). */
+  apiSurfaces?: Array<{ label: string; subDir: string; baseUrl?: string }>;
 }
 
-/** The names of the generators that may emit sibling files for an entity.
- *  We always list them in the "Generated code" section — adopters cross-
- *  reference their own metaobjects.config.ts to confirm which are wired in.
- *  Matches the rc.11 behavior. */
-const KNOWN_SIBLING_GENERATORS = new Set([
-  "queries-file",
-  "routes-file",
-  "routes-file-hono",
-]);
-
 const TEMPLATE_REF = "docs/entity-page.md";
+// The NEUTRAL render-contract page emitted per `template.output` node — a
+// sibling artifact, distinct from the entity page (Task 3).
+const TEMPLATE_PAGE_REF = "docs/template-page.md";
 
+/** Render one docs page, wrapping any engine error with the page ref + output
+ *  path so a template failure points at the exact page (shared by the entity
+ *  and template.output emission paths — identical error contract). */
+function renderDocPage(ref: string, payload: unknown, provider: Provider, path: string): string {
+  try {
+    return render({ ref, payload, provider, format: "markdown" });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`docs-file: failed rendering '${ref}' for '${path}': ${msg}`, {
+      cause: err instanceof Error ? err : undefined,
+    });
+  }
+}
+
+/**
+ * @deprecated ADR-0021 D1: `meta docs` is the single door for documentation.
+ * `docsFile()` stays as the INTERNAL engine that `meta docs` calls — do NOT add
+ * it to a `meta gen` config / the public generator surface. It is flagged
+ * neutral in the generator registry (`--list`) and is not part of the
+ * recommended native `meta gen` suite. Use `meta docs` instead.
+ */
 export const docsFile = function docsFile(opts?: DocsFileOpts): Generator {
   const generator: Generator = {
     name: "docs-file",
@@ -52,36 +94,160 @@ export const docsFile = function docsFile(opts?: DocsFileOpts): Generator {
       const rc = ctx.renderContext;
       const provider = projectProvider(ctx.projectRoot ?? process.cwd());
       const layout = ctx.config.outputLayout ?? "flat";
-      return ctx.loadedRoot.objects().filter(ctx.matches).map((entity: MetaObject) => {
-        const path = entityOutputPath(layout, entity.package, `${entity.name}.md`);
-        const payload = buildEntityDocData(entity, {
-          dialect: rc.dialect,
-          ...(rc.columnNamingStrategy !== undefined && {
-            columnNamingStrategy: rc.columnNamingStrategy,
-          }),
-          loadedRoot: rc.loadedRoot,
-          generatorNames: KNOWN_SIBLING_GENERATORS,
-        });
-        let content: string;
-        try {
-          content = render({
-            ref: TEMPLATE_REF,
-            payload,
-            provider,
-            format: "markdown",
+      // One {label, href} per api surface, every href computed via the shared
+      // `apiSurfaceHref` from the FROM page's own output path (so it resolves
+      // relative in BOTH layouts, or absolute when the surface declares a
+      // baseUrl). The api page for a node lives at `<subDir>/<same placement>`,
+      // so the from-path doubles as the page placement. ABSENT/empty surfaces ⇒
+      // undefined → output byte-identical to historical model-only runs.
+      const apiRefsFor = (fromPath: string): Array<{ label: string; href: string }> | undefined =>
+        opts?.apiSurfaces?.map((s) => ({ label: s.label, href: apiSurfaceHref(fromPath, s, fromPath) }));
+      // Track every (path, fqn) so we can hard-error on a collision (defense
+      // against silent doc-page overwrite) AFTER all pages are placed.
+      const placements: DocPagePlacement[] = [];
+      // Collect the placement nodes of each linkable page so the OVERVIEW/index
+      // (README.md) can link them via the SAME docPageHref used everywhere else
+      // (links resolve in flat AND package layout). Grouped entity vs template.
+      const entityNodes: DocPageNode[] = [];
+      const templateNodes: DocPageNode[] = [];
+      const files: EmittedFile[] = ctx.loadedRoot
+        .objects()
+        .filter(ctx.matches)
+        .map((entity: MetaObject) => {
+          const node = docPageNode(entity);
+          entityNodes.push(node);
+          const path = docPageOutputPath(layout, node);
+          placements.push({ path, fqn: entity.resolutionKey() });
+          // Cross-link to the sibling api surfaces, when emitted (shared builder).
+          const apiRefs = apiRefsFor(path);
+          const payload = buildEntityDocData(entity, {
+            dialect: rc.dialect,
+            layout,
+            ...(rc.columnNamingStrategy !== undefined && {
+              columnNamingStrategy: rc.columnNamingStrategy,
+            }),
+            loadedRoot: rc.loadedRoot,
+            ...(apiRefs !== undefined && { apiRefs }),
           });
-        } catch (err) {
-          const msg = err instanceof Error ? err.message : String(err);
-          throw new Error(
-            `docs-file: failed rendering '${TEMPLATE_REF}' for '${path}': ${msg}`,
-            { cause: err instanceof Error ? err : undefined },
-          );
-        }
-        return { path, content };
-      });
+          return { path, content: renderDocPage(TEMPLATE_REF, payload, provider, path) };
+        });
+
+      // ALSO emit one NEUTRAL render-contract page per `template.output` node —
+      // a sibling artifact, distinct from the entity page. Raw node name → file
+      // (`<name>.md`), agreeing with the entity Used-by back-link target.
+      for (const child of ctx.loadedRoot.ownChildren()) {
+        if (child.type !== TYPE_TEMPLATE || child.subType !== TEMPLATE_SUBTYPE_OUTPUT) continue;
+        const node = docPageNode(child);
+        templateNodes.push(node);
+        const path = docPageOutputPath(layout, node);
+        placements.push({ path, fqn: child.resolutionKey() });
+        const payload = buildTemplateDocData(child, {
+          layout,
+          loadedRoot: ctx.loadedRoot,
+          provider,
+        });
+        files.push({ path, content: renderDocPage(TEMPLATE_PAGE_REF, payload, provider, path) });
+      }
+
+      // Emit the neutral OVERVIEW/index page (README.md) at the docs root: the
+      // whole-model Mermaid ER diagram (reusing the single shared
+      // renderMermaidErBlock builder — no duplicated ER logic, ADR-0020) plus a
+      // navigable index linking every entity + template page. Prepended so it is
+      // the first file (and so README is included in the collision backstop).
+      // Only emitted when at least one page exists — an all-filtered/empty run
+      // produces nothing (no orphan landing page with an empty diagram).
+      if (files.length > 0) {
+        // The api index lives at `<subDir>/README.md` per surface; the model index
+        // lives at the docs root, so the from-path is the root-level index path
+        // (shared builder — same relative/absolute rule as the entity refs).
+        const apiIndexRefs = apiRefsFor(INDEX_FILENAME);
+        const indexContent = renderIndexPage(
+          ctx.loadedRoot,
+          layout,
+          entityNodes,
+          templateNodes,
+          apiIndexRefs,
+        );
+        placements.push({ path: INDEX_FILENAME, fqn: "<the auto-generated overview/index page>" });
+        files.unshift({ path: INDEX_FILENAME, content: indexContent });
+      }
+
+      // Hard backstop against silent overwrite (ALL layouts): two nodes that
+      // resolve to the same output path → throw naming both FQNs + the path.
+      assertNoDuplicateDocPaths(placements);
+
+      return files;
     },
   };
   if (opts?.filter) generator.filter = opts.filter;
   if (opts?.target) generator.target = opts.target;
   return generator;
 } as GeneratorFactory<DocsFileOpts>;
+
+/** Build the neutral OVERVIEW/index page (README.md) body: a title + one-line
+ *  description, the whole-model Mermaid ER diagram (the shared
+ *  renderMermaidErBlock — ONE builder, no duplication), and a navigable index
+ *  grouping entity pages vs template pages. Every link is computed with
+ *  docPageHref(layout, INDEX_NODE, target) so it resolves in BOTH flat and
+ *  package layout (the index lives at the docs root). Fully neutral — Mermaid +
+ *  entity/template names + relationships only. */
+function renderIndexPage(
+  root: MetaRoot,
+  layout: OutputLayout,
+  entityNodes: DocPageNode[],
+  templateNodes: DocPageNode[],
+  apiIndexRefs?: Array<{ label: string; href: string }>,
+): string {
+  const pkg = root.package;
+  const out: string[] = [];
+  out.push("# Data Model");
+  out.push("");
+  out.push(
+    pkg !== undefined && pkg.length > 0
+      ? `Overview of the \`${pkg}\` metadata model — entities, their relationships, and output templates.`
+      : "Overview of the metadata model — entities, their relationships, and output templates.",
+  );
+  out.push("");
+
+  // The whole-model ER diagram (shared neutral builder). Per-entity prose stays
+  // on each entity page; only the fenced erDiagram block lives on the overview.
+  out.push("## Diagram");
+  out.push("");
+  out.push(renderMermaidErBlock(root));
+  out.push("");
+
+  // Navigable index — grouped, sorted by name for stable output. Links resolve
+  // in both layouts because docPageHref derives them from the same placement.
+  const byName = (a: DocPageNode, b: DocPageNode) => a.name.localeCompare(b.name);
+  if (entityNodes.length > 0) {
+    out.push("## Entities");
+    out.push("");
+    for (const node of [...entityNodes].sort(byName)) {
+      out.push(`- [${node.name}](${docPageHref(layout, INDEX_NODE, node)})`);
+    }
+    out.push("");
+  }
+  if (templateNodes.length > 0) {
+    out.push("## Templates");
+    out.push("");
+    for (const node of [...templateNodes].sort(byName)) {
+      out.push(`- [${node.name}](${docPageHref(layout, INDEX_NODE, node)})`);
+    }
+    out.push("");
+  }
+
+  // Cross-link to the GENERATED-SDK api reference indexes, when api surfaces are
+  // emitted alongside the model surface — one bullet per language surface. ABSENT
+  // or empty → no section (index byte-identical to model-only runs).
+  if (apiIndexRefs !== undefined && apiIndexRefs.length > 0) {
+    out.push("## API reference");
+    out.push("");
+    for (const ref of apiIndexRefs) {
+      out.push(`- [${ref.label}](${ref.href})`);
+    }
+    out.push("");
+  }
+
+  // Trailing newline (one), matching the per-page convention.
+  return out.join("\n").replace(/\n+$/, "\n");
+}

package/src/generators/entity-file.ts

@@ -1,6 +1,7 @@
 import type { MetaObject } from "@metaobjectsdev/metadata";
-import { perEntity, type Generator, type GeneratorFactory } from "../generator.js";
+import { perEntity, type EmittedFile, type GenContext, type Generator, type GeneratorFactory } from "../generator.js";
 import { renderEntityFile } from "../templates/entity-file.js";
+import { renderSharedEnumsFile, SHARED_ENUMS_BASENAME } from "../templates/enums-file.js";
 import { formatTs } from "../format.js";
 import { entityOutputPath } from "../import-path.js";
 import { isAbstract } from "../instance-artifacts.js";
@@ -27,24 +28,39 @@ export interface EntityFileOpts {
 
 export const entityFile = function entityFile(opts?: EntityFileOpts): Generator {
   const allowlists = opts?.allowlists ?? true;
+  const perEntityEmit = perEntity(async (entity, ctx) => {
+    if (!ctx.renderContext) {
+      throw new Error("entity-file: renderContext is required (provided by runGen)");
+    }
+    // Abstract entities contribute shape only. When emitAbstractShapes is off
+    // (cross-port knob; default on) the entity-file generator emits nothing for
+    // them. Instance/write generators skip abstract unconditionally elsewhere.
+    if (isAbstract(entity) && !ctx.renderContext.emitAbstractShapes) {
+      return [];
+    }
+    return {
+      path: entityOutputPath(ctx.config.outputLayout ?? "flat", entity.package, `${entity.name}.ts`),
+      content: await formatTs(renderEntityFile(entity, ctx.renderContext, { allowlists })),
+    };
+  });
+
   const generator: Generator = {
     name: "entity-file",
     emitsEntityModule: true,
-    generate: perEntity(async (entity, ctx) => {
-      if (!ctx.renderContext) {
-        throw new Error("entity-file: renderContext is required (provided by runGen)");
-      }
-      // Abstract entities contribute shape only. When emitAbstractShapes is off
-      // (cross-port knob; default on) the entity-file generator emits nothing for
-      // them. Instance/write generators skip abstract unconditionally elsewhere.
-      if (isAbstract(entity) && !ctx.renderContext.emitAbstractShapes) {
-        return [];
+    generate: async (ctx: GenContext): Promise<EmittedFile[]> => {
+      const files = await perEntityEmit(ctx);
+      // FR-019: emit the shared-enums module ONCE per run, into the entity-module
+      // target root. Returns null (no file) when the model uses no materialized
+      // shared enums — keeping the inline-enum default byte-identical (no new file).
+      const sharedEnums = renderSharedEnumsFile(ctx.loadedRoot);
+      if (sharedEnums !== null) {
+        files.push({
+          path: `${SHARED_ENUMS_BASENAME}.ts`,
+          content: await formatTs(sharedEnums),
+        });
       }
-      return {
-        path: entityOutputPath(ctx.config.outputLayout ?? "flat", entity.package, `${entity.name}.ts`),
-        content: await formatTs(renderEntityFile(entity, ctx.renderContext, { allowlists })),
-      };
-    }),
+      return files;
+    },
   };
   if (opts?.filter) {
     generator.filter = opts.filter;

package/src/generators/extractor-file.ts

@@ -5,7 +5,8 @@
 //
 // The emitted extractor sits over the output-parser's nested-capable extract and turns dirty LLM
 // text into the strict typed payload graph. It imports from the sibling <Name>.output.ts (the
-// output-parser) and ./payloads.ts, so run it alongside outputParser() + a payload generator.
+// output-parser) and from each payload value-object's own entity module (<VO>.ts, emitted by
+// entityFile), so run it alongside outputParser() + entityFile().
 //
 // Consumer wiring (metaobjects.config.ts):
 //   generators: [..., outputParser(), extractor()]

package/src/generators/field-anchor.ts

@@ -0,0 +1,24 @@
+// Per-field doc anchor convention (linked-template-source-docs).
+//
+// A field's stable doc anchor slug is `field-<name>` (the field name verbatim).
+// This is the SINGLE source of truth for the slug, shared by BOTH:
+//   • the entity-page builder, which emits a literal `<a id="field-<name>">` in
+//     each Constraints-table Field cell, and
+//   • the template-source annotator, whose links target `#field-<name>`.
+// Sharing one helper means the anchor and its links can never drift.
+//
+// The name is used verbatim (not URL-slugified): MetaObjects field names are
+// already identifier-safe (no spaces / punctuation), so `field-<name>` is a
+// valid HTML id and a valid Markdown fragment as-is.
+
+/** The stable doc-anchor slug for a field: `field-<name>`. */
+export function fieldAnchorSlug(name: string): string {
+  return `field-${name}`;
+}
+
+/** The literal HTML anchor a Markdown link can target: `<a id="field-<name>"></a>`.
+ *  Renders on GitHub-flavored Markdown and static-site generators, including
+ *  inside a table cell. */
+export function fieldAnchorHtml(name: string): string {
+  return `<a id="${fieldAnchorSlug(name)}"></a>`;
+}

package/src/generators/index.ts

@@ -4,12 +4,16 @@ export { callableFile, type CallableFileOpts } from "./callable-file.js";
 export { routesFile, type RoutesFileOpts } from "./routes-file.js";
 export { routesFileHono, type RoutesFileHonoOpts } from "./routes-file-hono.js";
 export { barrel, type BarrelOpts } from "./barrel.js";
+/** @deprecated ADR-0021 D1 — neutral artifact owned by `meta docs` (ADR-0020); not part of the recommended `meta gen` suite. */
 export { mermaidErDiagram, type MermaidErOptions } from "./mermaid-er.js";
 export { promptRender, type PromptRenderOpts } from "./prompt-render-file.js";
 export { outputParser, type OutputParserOpts } from "./output-parser-file.js";
 export { extractor, type ExtractorOpts } from "./extractor-file.js";
 export { outputPrompt, type OutputPromptOpts } from "./output-prompt-file.js";
 export { renderHelper, type RenderHelperOpts } from "./render-helper-file.js";
+/** @deprecated ADR-0025 — `meta docs` is the single docs door; `apiDocsFile` stays as the internal engine of its api surface, not a `meta gen` config generator. */
+export { apiDocsFile, type ApiDocsFileOpts } from "./api-docs-file.js";
+/** @deprecated ADR-0021 D1 — `meta docs` is the single docs door; `docsFile` stays as its internal engine, not a `meta gen` config generator. */
 export { docsFile, type DocsFileOpts } from "./docs-file.js";
 export {
   templateGenerator,
@@ -17,12 +21,15 @@ export {
   type TemplateWalkResult,
   type TemplateFormat,
 } from "./template-generator.js";
+export { traceHelperFile, type TraceHelperOpts } from "./trace-helper-file.js";
 export type {
   EntityDocData,
   StorageFieldDoc,
   IdentityDoc,
   RelationshipDoc,
   UsedByDoc,
-  GeneratedFileDoc,
+  ConstraintRow,
 } from "./docs-data.js";
 export { buildEntityDocData } from "./docs-data-builder.js";
+export type { TemplateDocData, TemplateOutputPart } from "./template-doc-data.js";
+export { buildTemplateDocData } from "./template-doc-builder.js";

package/src/generators/mermaid-er.ts

@@ -12,6 +12,20 @@ export interface MermaidErOptions {
  * Emit a single Markdown file containing a Mermaid `erDiagram` plus per-entity
  * prose sections. The renderer walks the loaded root for all entities; the
  * default outFile is "docs/model.md".
+ *
+ * TIER NOTE (ADR-0020): the CANONICAL home of the neutral ER diagram is now the
+ * neutral docs engine — the OVERVIEW/index page (`README.md`) emitted by
+ * `docsFile()` / `meta docs` embeds the SAME `renderMermaidErBlock()` this
+ * generator's `renderMermaidModel()` reuses. This standalone Tier-1 generator is
+ * retained ONLY as a thin back-compat wrapper for adopters that already have
+ * `mermaidErDiagram` in their `meta gen` config; it adds NO ER logic of its own
+ * (no duplication) — it delegates to the shared `renderMermaidModel()` builder.
+ *
+ * @deprecated ADR-0021 D1: the ER diagram is a Tier-2 neutral artifact owned by
+ * the docs engine (ADR-0020). Use `meta docs` — it embeds the same ER block.
+ * This standalone `meta gen` generator is flagged neutral in the registry
+ * (`--list`) and is no longer part of the recommended native suite. Kept for
+ * back-compat; do not add to new gen configs.
  */
 export const mermaidErDiagram = function mermaidErDiagram(
   opts?: MermaidErOptions,