feat(docs): meta docs surfaces prompt text + a prompt data-flow view

`meta docs --site` now shows the actual prompt TEXT and a directional data-flow
diagram of the prompt-construction pipeline.

- --prompts <dir>: the site's prompt-source search now includes <root>/templates/
  and an explicit --prompts dir, so a project whose .mustache sources live outside
  metaobjects/ or templates/ (e.g. data/templates/) renders the real prompt text on
  each prompt page (each {{var}} linked to its payload field) instead of a
  "source missing" note.
- Prompt data-flow diagram on the site index: request payload VO --input--> prompt,
  prompt/output --produces/parses--> response VO, and (where a VO references an entity)
  the DB-entity --source/persists-- bookends. Derived from template.prompt
  @payloadRef/@responseRef + template.output/toolcall @payloadRef + each VO's entity
  refs. A new @responseRef graph edge completes the pipeline.

Additive. Gated by the docs-site golden (AI fixture now exercises the full pipeline
incl. @responseRef) + a link-graph unit test; docs-site 44 + cli 406 green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014xy8powhHYJ6gfFt9Ut8dL

Author: dmealing

CHANGELOG.md

@@ -7,6 +7,26 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+### Added — `meta docs` surfaces prompt TEXT + a prompt data-flow view (site)
+
+The browsable HTML doc site (`meta docs --site`) now shows the actual prompt text and a
+directional prompt-construction data-flow diagram (npm-only; `docs-site` + `cli`):
+
+- **`--prompts <dir>`** — the `--site` prompt-source search now includes `<root>/templates/`
+  and an explicit `--prompts` dir, so a project whose prompt `.mustache` sources live
+  outside `metaobjects/` or `templates/` (e.g. `data/templates/`) renders the actual
+  prompt TEXT on each prompt page (with every `{{var}}` linked to its payload field)
+  instead of a "source missing" note.
+- **Prompt data-flow diagram** on the site index — a directional Mermaid flowchart of the
+  pipeline: request payload VO ──input──▶ prompt, prompt/output ──produces/parses──▶
+  response VO, and (where a VO references an entity) the DB-entity ──source/persists──
+  bookends. Derived structurally from `template.prompt @payloadRef`/`@responseRef` and
+  `template.output`/`template.toolcall @payloadRef`, plus each VO's entity references. A
+  new `@responseRef` graph edge (prompt → response VO) completes the pipeline.
+
+Additive: markdown surfaces and non-pipeline site output are unchanged. Gated by the
+`docs-site` golden (its AI fixture now exercises the full pipeline) + a link-graph unit test.
+
 ## [0.20.2] — 2026-07-25
 
 **npm `0.20.2` only** (NuGet `0.19.3` / PyPI `0.19.5` / Maven Central `7.11.3` unchanged — no changed product file; D1 is a TS-only dialect). A bug-fix patch, no API or vocabulary change.

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

@@ -50,6 +50,11 @@ interface DocsFlags {
   /** Optional override for the project root used to resolve adopter
    *  `templates/` overrides. Defaults to the metadata root. */
   templates?: string;
+  /** Optional directory holding the prompt `.mustache` sources, for a project
+   *  whose templates live outside the conventional `metaobjects/` or `templates/`
+   *  roots (e.g. `data/templates/`). Added to the `--site` prompt-source search
+   *  path so the HTML site can show the prompt TEXT. Mirrors `verify --prompts`. */
+  prompts?: string;
   /** Which doc surfaces to emit, when overridden on the CLI. `--model` ⇒
    *  ["model"], `--api` ⇒ ["api"], both ⇒ ["model","api"]. Unset ⇒ defer to the
    *  resolved `docs:` config (default both). */
@@ -85,6 +90,7 @@ function parseDocsArgs(argv: string[], cwd: string): DocsFlags {
   let metadata: string | undefined;
   let out: string | undefined;
   let templates: string | undefined;
+  let prompts: string | undefined;
   let layout: DocsLayout | undefined;
   let baseUrl: string | undefined;
   let wantModel = false;
@@ -132,6 +138,12 @@ function parseDocsArgs(argv: string[], cwd: string): DocsFlags {
       templates = v;
     } else if (a.startsWith("--templates=")) {
       templates = a.slice("--templates=".length);
+    } else if (a === "--prompts") {
+      const v = argv[++i];
+      if (v === undefined) throw new Error(`${a} requires a directory argument`);
+      prompts = v;
+    } else if (a.startsWith("--prompts=")) {
+      prompts = a.slice("--prompts=".length);
     } else if (a.startsWith("-")) {
       throw new Error(`unknown flag: ${a}`);
     } else if (metadata === undefined) {
@@ -166,6 +178,7 @@ function parseDocsArgs(argv: string[], cwd: string): DocsFlags {
     ...(surfaces.length > 0 || wantSite ? { surfaces } : {}),
     ...(baseUrl !== undefined ? { baseUrl } : {}),
     ...(templates !== undefined ? { templates } : {}),
+    ...(prompts !== undefined ? { prompts } : {}),
   };
 }
 
@@ -187,6 +200,9 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
   }
 
   const metaRoot = resolvePath(cwd, flags.metadata);
+  // Absolute prompt-source dir for the site (--prompts), for a project whose
+  // templates live outside metaobjects/ or templates/ (e.g. data/templates/).
+  const promptsDir = flags.prompts !== undefined ? resolvePath(cwd, flags.prompts) : undefined;
 
   // `--scaffold-site`: copy the docs-site templates + assets into codegen/docs-site/
   // so the consumer owns them (ADR-0034 scaffold-and-own). Scaffold and return —
@@ -261,7 +277,7 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
   // WITHOUT building the markdown GenContext — decoupled and one fewer failure
   // surface. Combined with --model/--api it is emitted after them (below).
   if (flags.site && docsCfg.surfaces.length === 0) {
-    return emitSite(metaRoot, outDir, configProviders);
+    return emitSite(metaRoot, outDir, configProviders, promptsDir);
   }
 
   // Load metadata standalone — same loader path as migrate/gen. Threads any
@@ -428,7 +444,7 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
 
   // SITE surface (additive) — emit after the markdown surfaces so both coexist.
   if (flags.site) {
-    const siteRc = await emitSite(metaRoot, outDir, configProviders);
+    const siteRc = await emitSite(metaRoot, outDir, configProviders, promptsDir);
     if (siteRc !== 0) return siteRc;
   }
 
@@ -501,9 +517,26 @@ async function emitSite(
   metaRoot: string,
   outDir: string,
   configProviders?: readonly MetaDataTypeProvider[],
+  promptsDir?: string,
 ): Promise<number> {
   const siteOutDir = resolvePath(outDir, "site");
+  // metaobjects/ is REQUIRED (the site loads the model from it) and always first.
+  // Prompt `.mustache` source is additionally searched in the conventional
+  // <root>/templates/ and any explicit --prompts dir (for a project whose templates
+  // live elsewhere, e.g. data/templates/) — else the site can't show the prompt TEXT
+  // and prints a "source missing" note. Only existing dirs are added, and dirs are
+  // deduped by BASENAME (the site keys source groups by basename, and rejects a dup).
   const sourceDirs = [join(metaRoot, DEFAULT_METADATA_DIR)];
+  const seenBasenames = new Set([basename(join(metaRoot, DEFAULT_METADATA_DIR))]);
+  if (promptsDir !== undefined && !existsSync(promptsDir)) {
+    log.warn(`docs: --prompts dir does not exist: ${promptsDir}`);
+  }
+  for (const d of [join(metaRoot, "templates"), ...(promptsDir !== undefined ? [promptsDir] : [])]) {
+    if (existsSync(d) && !seenBasenames.has(basename(d))) {
+      sourceDirs.push(d);
+      seenBasenames.add(basename(d));
+    }
+  }
   // Scaffold-and-own: when the consumer has copied templates/assets into
   // codegen/docs-site/ (via --scaffold-site), use those; else the bundled defaults.
   const ownedTemplates = join(metaRoot, "codegen/docs-site/templates");

server/typescript/packages/cli/src/index.ts

@@ -42,6 +42,7 @@ DOCS FLAGS:
   <metadata>            Project root holding metaobjects/ (default: current directory)
   --out <dir>, -o       Output directory for the pages (default: ./docs)
   --templates <dir>     Project root to resolve adopter templates/ overrides (default: <metadata>)
+  --prompts <dir>       Extra dir holding prompt .mustache sources for --site (e.g. data/templates/)
 
 VERIFY FLAGS (ADR-0021 D2 — explicit subverbs; combine any; exit 1 on ANY drift):
   --templates           Template/prompt {{field}}↔payload drift (the bare-verify default)
@@ -159,6 +160,8 @@ FLAGS:
   --site                Generate the browsable HTML documentation site (<out>/site/)
   --scaffold-site       Copy the site's templates + assets into codegen/docs-site/ to own (theme) them
   --templates <dir>     Project root to resolve adopter templates/ overrides (default: <metadata>)
+  --prompts <dir>       Extra dir holding prompt .mustache sources (for --site) when they
+                        live outside metaobjects/ or templates/ (e.g. data/templates/)
   --help, -h            Print this help
 `,
   init: `meta init — scaffold metaobjects/ + .metaobjects/ in the current repo

server/typescript/packages/cli/test/__snapshots__/cli.test.ts.snap

@@ -36,6 +36,7 @@ DOCS FLAGS:
   <metadata>            Project root holding metaobjects/ (default: current directory)
   --out <dir>, -o       Output directory for the pages (default: ./docs)
   --templates <dir>     Project root to resolve adopter templates/ overrides (default: <metadata>)
+  --prompts <dir>       Extra dir holding prompt .mustache sources for --site (e.g. data/templates/)
 
 VERIFY FLAGS (ADR-0021 D2 — explicit subverbs; combine any; exit 1 on ANY drift):
   --templates           Template/prompt {{field}}↔payload drift (the bare-verify default)

server/typescript/packages/docs-site/src/builders/index-data.ts

@@ -1,12 +1,62 @@
 import { LinkGraph, fqnOf } from "../link-graph.js";
+import type { DocNode } from "../link-graph.js";
 import type { CoverageTracker } from "../coverage.js";
 import { flowchartDomain, packageFlowchart } from "../mermaid.js";
 import { harvestPackageDocs } from "../package-docs.js";
 import { esc } from "../badges.js";
 
 export interface PkgCard { pkg: string; href: string; objectCount: number; promptCount: number; contractCount: number; purpose: string; }
 export interface CoreConfig { pin?: string[]; exclude?: string[]; n?: number; }
-export interface IndexPageData { title: string; stamp: string; commit: string; stats: { objects: number; tables: number; packages: number; promptVos: number; prompts: number; contracts: number; enums: number }; coreMermaid: string; coreCaption: string; coreLegend: { pkg: string; fill: string; stroke: string }[]; packageMermaid: string; fullEdges: { from: string; to: string; n: number }[]; dataPackages: PkgCard[]; promptPackages: PkgCard[]; }
+export interface IndexPageData { title: string; stamp: string; commit: string; stats: { objects: number; tables: number; packages: number; promptVos: number; prompts: number; contracts: number; enums: number }; coreMermaid: string; coreCaption: string; coreLegend: { pkg: string; fill: string; stroke: string }[]; packageMermaid: string; dataflowMermaid: string; dataflowLegend: { pkg: string; fill: string; stroke: string }[]; fullEdges: { from: string; to: string; n: number }[]; dataPackages: PkgCard[]; promptPackages: PkgCard[]; }
+
+/**
+ * The prompt-construction DATA-FLOW pipeline as a directional flowchart:
+ *   DB entity ──source──▶ request payload VO ──input──▶ prompt
+ *   prompt/output ──produces/parses──▶ response VO ──persists──▶ DB entity
+ * Derived structurally from `template.prompt @payloadRef` (request VO) / `@responseRef`
+ * (response VO) and `template.output`/`template.toolcall @payloadRef` (response VO),
+ * plus each VO's field/origin/extends links back to entities. Returns undefined when
+ * the model declares no template pipeline (nothing to draw).
+ */
+function buildDataflow(g: LinkGraph): { mermaid: string; legend: { pkg: string; fill: string; stroke: string }[] } | undefined {
+  const isEntity = (d: DocNode | undefined): d is DocNode => !!d && d.kind === "object" && d.node.subType === "entity";
+  // Entities a VO is linked to, in EITHER direction (VO.field→entity, or entity extends VO).
+  const linkedEntities = (voFqn: string): DocNode[] => {
+    const out: DocNode[] = [];
+    for (const r of g.refsFrom(voFqn)) if (r.kind === "field" || r.kind === "origin" || r.kind === "fk") { const d = g.byFqn(r.to); if (isEntity(d)) out.push(d); }
+    for (const r of g.refsTo(voFqn)) if (r.kind === "extends" || r.kind === "field" || r.kind === "origin" || r.kind === "fk") { const d = g.byFqn(r.from); if (isEntity(d)) out.push(d); }
+    return out;
+  };
+  const nodes = new Map<string, { name: string; pkg: string; kind: string }>();
+  const edges: { from: string; to: string; label: string }[] = [];
+  const seen = new Set<string>();
+  const addNode = (d: DocNode): string => { nodes.set(d.name, { name: d.name, pkg: d.pkg, kind: d.node.subType }); return d.name; };
+  const addEdge = (from: string, to: string, label: string): void => { const k = `${from}|${to}`; if (from !== to && !seen.has(k)) { seen.add(k); edges.push({ from, to, label }); } };
+
+  for (const t of g.nodes().filter((n) => n.kind !== "object")) {
+    const tFqn = fqnOf(t.node);
+    const isPrompt = t.kind === "prompt";
+    const payload = g.refsFrom(tFqn).find((r) => r.kind === "payload");
+    const response = g.refsFrom(tFqn).find((r) => r.kind === "response");
+    const tName = addNode(t);
+    if (isPrompt && payload) {
+      const vo = g.byFqn(payload.to);
+      if (vo) { const voName = addNode(vo);
+        for (const e of linkedEntities(payload.to)) addEdge(addNode(e), voName, "source");
+        addEdge(voName, tName, "input"); }
+    }
+    // RESPONSE half: a prompt's @responseRef VO, or an output/toolcall's @payloadRef VO.
+    const respRef = isPrompt ? response : payload;
+    if (respRef) {
+      const vo = g.byFqn(respRef.to);
+      if (vo) { const voName = addNode(vo);
+        addEdge(tName, voName, isPrompt ? "produces" : "parses");
+        for (const e of linkedEntities(respRef.to)) addEdge(voName, addNode(e), "persists"); }
+    }
+  }
+  if (edges.length === 0) return undefined;
+  return flowchartDomain([...nodes.values()], edges);
+}
 
 export function buildIndexPage(g: LinkGraph, cov: CoverageTracker, opts: { title: string; stamp: string; commit: string; core?: CoreConfig | undefined; sourceDirs?: string[] | undefined }): IndexPageData {
   const objs = g.nodes().filter((n) => n.kind === "object");
@@ -56,6 +106,7 @@ export function buildIndexPage(g: LinkGraph, cov: CoverageTracker, opts: { title
   const heroNodes = [...shown.values()].filter((dn) => connected.has(dn.name));
   const hero = flowchartDomain(heroNodes.map((dn) => ({ name: dn.name, pkg: dn.pkg, kind: dn.node.subType })), heroEdges);
   const coreMermaid = hero.mermaid, coreLegend = hero.legend;
+  const dataflow = buildDataflow(g);
   const coreCaption = `${heroNodes.length} of the most-connected objects (entities, views, and payloads), colored by domain.`;
   // package docs for purpose cards
   const pdocs = harvestPackageDocs(opts.sourceDirs ?? []);
@@ -89,6 +140,8 @@ export function buildIndexPage(g: LinkGraph, cov: CoverageTracker, opts: { title
     coreCaption,
     coreLegend,
     packageMermaid: packageFlowchart(fullEdges.filter((e) => e.n >= 2), counts),
+    dataflowMermaid: dataflow?.mermaid ?? "",
+    dataflowLegend: dataflow?.legend ?? [],
     fullEdges,
     dataPackages: pkgs.filter((p) => !promptPkgSet.has(p)).map(card),
     promptPackages: pkgs.filter((p) => promptPkgSet.has(p)).map(card) };

server/typescript/packages/docs-site/src/link-graph.ts

@@ -5,7 +5,7 @@ import { type LoadedModel, treeOf } from "./load.js";
 export interface DocNode { kind: "object" | "prompt" | "output"; name: string; pkg: string; pkgPath: string; href: string; node: MetaData; tree: string; }
 export interface Ref {
   from: string; to: string; via: string;
-  kind: "field" | "fk" | "extends" | "payload" | "relationship" | "origin";
+  kind: "field" | "fk" | "extends" | "payload" | "response" | "relationship" | "origin";
   cardinality?: "one" | "many" | undefined;
   through?: string | undefined;         // junction FQN (M:N)
   sourceJoinField?: string | undefined; // junction source FK (M:N)
@@ -145,6 +145,13 @@ export class LinkGraph {
           const to = resolveRef(p, dn.pkg);
           if (to) addRef({ from: fqn, to, via: "payloadRef", kind: "payload" });
         }
+        // A prompt's @responseRef is the response value-object it PRODUCES — the
+        // missing hop of the data-flow pipeline (prompt → response VO → entity).
+        const r = dn.node.attr("responseRef");
+        if (typeof r === "string") {
+          const to = resolveRef(r, dn.pkg);
+          if (to) addRef({ from: fqn, to, via: "responseRef", kind: "response" });
+        }
       }
     }
   }

server/typescript/packages/docs-site/templates/index.html.mustache

@@ -17,6 +17,14 @@
   <div class="text-[11px] opacity-50 mt-1"><span class="font-mono">▭</span> entity · <span class="font-mono">⬭</span> value object · <span class="font-mono">▱</span> view</div>{{/coreLegend.length}}
 </div>
 {{/coreMermaid}}
+{{#dataflowMermaid}}
+<div class="card bg-base-100 border border-base-300 p-4 my-4">
+  <div class="font-semibold mb-2">Prompt data-flow</div>
+  <div class="pl-diagram"><pre class="mermaid">{{dataflowMermaid}}</pre></div>
+  <div class="text-xs opacity-50 mt-1">The prompt-construction pipeline: request payload VOs flow <span class="font-mono">input</span>→ prompts; tool-calls/outputs <span class="font-mono">parse/produce</span>→ response VOs. A VO that references an entity adds the DB <span class="font-mono">source</span>/<span class="font-mono">persists</span> hops (entity → payload VO … response VO → entity).</div>
+  {{#dataflowLegend.length}}<div class="flex flex-wrap gap-1 mt-2 text-xs">{{#dataflowLegend}}<span class="badge badge-xs" style="background:{{fill}};border-color:{{stroke}};color:#cbd5e1">{{pkg}}</span>{{/dataflowLegend}}</div>{{/dataflowLegend.length}}
+</div>
+{{/dataflowMermaid}}
 {{#packageMermaid}}
 <div class="card bg-base-100 border border-base-300 p-4 my-4">
   <div class="font-semibold mb-2">Package dependencies</div>

server/typescript/packages/docs-site/test/fixture/golden/acme/ai/NpcResponse.html

@@ -81,7 +81,7 @@ <h1 class="text-2xl font-bold font-mono mt-1">NpcResponse
 
 
 
-<section id="s-referenced-by" class="mt-6 text-sm"><span class="opacity-50">referenced by</span> <a class="link font-mono text-xs" href="npcReviewOutput.html" title="payloadRef">npcReviewOutput</a> </section>
+<section id="s-referenced-by" class="mt-6 text-sm"><span class="opacity-50">referenced by</span> <a class="link font-mono text-xs" href="npcReview.html" title="responseRef">npcReview</a> <a class="link font-mono text-xs" href="npcReviewOutput.html" title="payloadRef">npcReviewOutput</a> </section>
 <div class="text-sm mt-1"><span class="opacity-50">used by templates</span> <a class="link font-mono text-xs" href="npcReviewOutput.html">npcReviewOutput</a> </div>
 <div class="text-[10px] opacity-40 mt-6 font-mono">meta.ai.yaml</div>
 </main>

server/typescript/packages/docs-site/test/fixture/golden/acme/ai/index.html

@@ -49,7 +49,7 @@
 <h1 class="text-2xl font-bold font-mono">Fixture</h1>
 
 <div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-3 my-4">
-<a href="ItemView.html" class="card bg-base-100 border border-base-300 p-3"><div class="font-mono font-semibold">ItemView</div><div class="text-xs opacity-50">1 refs</div></a><a href="NpcPayload.html" class="card bg-base-100 border border-base-300 p-3"><div class="font-mono font-semibold">NpcPayload</div><div class="text-xs opacity-50">1 refs</div></a><a href="NpcResponse.html" class="card bg-base-100 border border-base-300 p-3"><div class="font-mono font-semibold">NpcResponse</div><div class="text-xs opacity-50">1 refs</div></a><a href="OrderLine.html" class="card bg-base-100 border border-base-300 p-3"><div class="font-mono font-semibold">OrderLine</div><div class="text-xs opacity-50">0 refs</div></a>
+<a href="NpcResponse.html" class="card bg-base-100 border border-base-300 p-3"><div class="font-mono font-semibold">NpcResponse</div><div class="text-xs opacity-50">2 refs</div></a><a href="ItemView.html" class="card bg-base-100 border border-base-300 p-3"><div class="font-mono font-semibold">ItemView</div><div class="text-xs opacity-50">1 refs</div></a><a href="NpcPayload.html" class="card bg-base-100 border border-base-300 p-3"><div class="font-mono font-semibold">NpcPayload</div><div class="text-xs opacity-50">1 refs</div></a><a href="OrderLine.html" class="card bg-base-100 border border-base-300 p-3"><div class="font-mono font-semibold">OrderLine</div><div class="text-xs opacity-50">0 refs</div></a>
 </div>
 <div class="card bg-base-100 border border-base-300 p-2 pl-diagram my-4"><pre class="mermaid">%%{init: {'theme':'base','themeVariables':{'darkMode':true,'background':'#0b1220','primaryColor':'#1e2a3a','primaryTextColor':'#cbd5e1','primaryBorderColor':'#4a7fa5','lineColor':'#64748b','secondaryColor':'#1a2535','tertiaryColor':'#0f1826','fontSize':'13px'}}}%%
 erDiagram