feat(docs): neutral overview page with embedded Mermaid ER diagram + navigable index

docsFile() now emits a neutral README.md overview at the docs root: a title +
one-line model description, the whole-model Mermaid erDiagram, and a navigable
index grouping every entity page and every template.output page. Index links use
docPageHref so they resolve in BOTH flat and package layouts.

Extracted renderMermaidErBlock() as the single shared neutral ER builder;
renderMermaidModel() (the standalone model.md body) and the docs overview both
consume it — no duplicated graph logic. The standalone Tier-1 mermaidErDiagram
generator is retained as a thin back-compat wrapper, with a tier note (ADR-0020)
pointing to the neutral docs engine as the canonical home of the ER diagram.

meta docs summary now reports the overview page; README is not miscounted as an
entity/template. Per-entity focused diagrams deferred (would need new graph
scoping; the overview ER is the required win).

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

Author: dmealing

server/typescript/packages/cli/src/commands/docs.ts

@@ -221,13 +221,14 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
     return 1;
   }
 
-  // Summary: docsFile() emits one page per entity first, then one per
-  // template.output. The entity count is the matched object count; the rest
-  // are template pages.
+  // Summary: docsFile() emits ONE overview/index page (README.md) plus one page
+  // per entity and one per template.output. The entity count is the matched
+  // object count; the remaining non-overview pages are template pages.
   const entityCount = root.objects().filter(ctx.matches).length;
-  const templateCount = files.length - entityCount;
+  const overviewCount = files.filter((f) => f.path === "README.md").length;
+  const templateCount = files.length - entityCount - overviewCount;
   log.info(
-    `meta docs — wrote ${entityCount} entity page(s) + ${templateCount} template page(s) → ${outDir}`,
+    `meta docs — wrote ${overviewCount} overview + ${entityCount} entity page(s) + ${templateCount} template page(s) → ${outDir}`,
   );
   return 0;
 }

server/typescript/packages/cli/test/docs-command.test.ts

@@ -216,12 +216,35 @@ describe("meta docs — standalone neutral metadata docs", () => {
     expect(await docsCommand([root, "--out", out], root)).toBe(0);
 
     const summary = logged.join("\n");
-    // Mentions counts + destination.
+    // Mentions counts + destination, including the overview/index page.
+    expect(summary).toMatch(/1 overview/);
     expect(summary).toMatch(/1 entity/);
     expect(summary).toMatch(/1 template/);
     expect(summary).toContain(out);
   });
 
+  test("emits a neutral README.md overview with an embedded Mermaid ER diagram", async () => {
+    const root = await project();
+    const out = join(root, "out-overview");
+    expect(await docsCommand([root, "--out", out], root)).toBe(0);
+
+    // The overview/index page lands at the docs root as README.md.
+    expect(existsSync(join(out, "README.md"))).toBe(true);
+    const readme = await readFile(join(out, "README.md"), "utf8");
+
+    // Carries the fenced Mermaid ER diagram + links to the model's pages.
+    expect(readme).toContain("```mermaid");
+    expect(readme).toContain("erDiagram");
+    // Links every entity + template page emitted in the same run.
+    expect(readme).toContain("(./Welcome.md)");
+    expect(readme).toContain("(./WelcomePage.md)");
+
+    // Neutral — no language/toolchain leakage (".md" links allowed).
+    expect(readme.replace(/\.md\b/g, "")).not.toMatch(/\.ts\b/);
+    expect(readme).not.toContain("Zod");
+    expect(readme).not.toContain("## Generated code");
+  });
+
   test("loads metaobjects.config.ts providers so custom types resolve", async () => {
     const root = await customTypeProject();
     const out = join(root, "out-custom");

server/typescript/packages/codegen-ts/src/generators/docs-file.ts

@@ -18,19 +18,30 @@
 // 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, EmittedFile } from "../generator.js";
 import {
   docPageOutputPath,
+  docPageHref,
   docPageNode,
   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;
@@ -55,11 +66,18 @@ export const docsFile = function docsFile(opts?: DocsFileOpts): Generator {
       // 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 path = docPageOutputPath(layout, docPageNode(entity));
+          const node = docPageNode(entity);
+          entityNodes.push(node);
+          const path = docPageOutputPath(layout, node);
           placements.push({ path, fqn: entity.resolutionKey() });
           const payload = buildEntityDocData(entity, {
             dialect: rc.dialect,
@@ -92,7 +110,9 @@ export const docsFile = function docsFile(opts?: DocsFileOpts): Generator {
       // (`<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 path = docPageOutputPath(layout, docPageNode(child));
+        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 });
         let content: string;
@@ -113,6 +133,19 @@ export const docsFile = function docsFile(opts?: DocsFileOpts): Generator {
         files.push({ path, content });
       }
 
+      // 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) {
+        const indexContent = renderIndexPage(ctx.loadedRoot, layout, entityNodes, templateNodes);
+        placements.push({ path: INDEX_FILENAME, fqn: "<overview>" });
+        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);
@@ -124,3 +157,58 @@ export const docsFile = function docsFile(opts?: DocsFileOpts): Generator {
   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[],
+): 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("");
+  }
+
+  // Trailing newline (one), matching the per-page convention.
+  return out.join("\n").replace(/\n+$/, "\n");
+}

server/typescript/packages/codegen-ts/src/generators/mermaid-er.ts

@@ -12,6 +12,14 @@ 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.
  */
 export const mermaidErDiagram = function mermaidErDiagram(
   opts?: MermaidErOptions,

server/typescript/packages/codegen-ts/src/templates/mermaid-er.ts

@@ -8,17 +8,20 @@ import type { MetaObject, MetaRoot } from "@metaobjectsdev/metadata";
 import { DOC_ATTR_DESCRIPTION } from "@metaobjectsdev/metadata";
 import { readDocAttrs } from "./jsdoc.js";
 
-/** Render a docs/model.md body: Mermaid erDiagram + per-entity prose. Abstract
- *  entities are excluded — they have no physical table to put in a diagram
- *  (matches migrate-ts/expected-schema.ts's same filter). */
-export function renderMermaidModel(root: MetaRoot): string {
+/** Render JUST the fenced ```mermaid erDiagram``` block for the whole model
+ *  (entities + identity.reference relationships) — NO per-entity prose. This is
+ *  the single neutral ER-diagram builder; both `renderMermaidModel()` (the
+ *  standalone model.md body) AND the neutral docs OVERVIEW page (`README.md`,
+ *  emitted by the Tier-2 `meta docs` engine) consume it, so there is exactly
+ *  ONE place ER topology is computed — no duplicate graph logic (ADR-0020).
+ *
+ *  Abstract entities are excluded — they have no physical table to put in a
+ *  diagram (matches migrate-ts/expected-schema.ts's same filter). */
+export function renderMermaidErBlock(root: MetaRoot): string {
   const entities = root
     .objects()
     .filter((o) => o.isEntity() && !o.isAbstract);
   const parts: string[] = [];
-
-  parts.push("# Data Model");
-  parts.push("");
   parts.push("```mermaid");
   parts.push("erDiagram");
   for (const line of renderRelationships(entities)) parts.push(`    ${line}`);
@@ -27,6 +30,22 @@ export function renderMermaidModel(root: MetaRoot): string {
     for (const line of renderEntityBlock(entity)) parts.push(`    ${line}`);
   }
   parts.push("```");
+  return parts.join("\n");
+}
+
+/** Render a docs/model.md body: Mermaid erDiagram + per-entity prose. Abstract
+ *  entities are excluded — they have no physical table to put in a diagram
+ *  (matches migrate-ts/expected-schema.ts's same filter). Reuses the shared
+ *  `renderMermaidErBlock()` for the diagram so the ER logic is never duplicated. */
+export function renderMermaidModel(root: MetaRoot): string {
+  const entities = root
+    .objects()
+    .filter((o) => o.isEntity() && !o.isAbstract);
+  const parts: string[] = [];
+
+  parts.push("# Data Model");
+  parts.push("");
+  parts.push(renderMermaidErBlock(root));
   parts.push("");
 
   for (const entity of entities) {