@metaobjectsdev/docs-site 0.15.8-rc.1

package/src/site.ts

@@ -0,0 +1,289 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { render, InMemoryProvider } from "@metaobjectsdev/render";
+import { loadModel } from "./load";
+import { LinkGraph, fqnOf } from "./link-graph";
+import { CoverageTracker } from "./coverage";
+import type { CoverageReport } from "./coverage";
+import { harvestComments } from "./yaml-comments";
+import { buildIndexPage } from "./builders/index-data";
+import type { CoreConfig } from "./builders/index-data";
+import { buildPackagePage } from "./builders/package-data";
+import { buildObjectPage } from "./builders/object-data";
+import { buildPromptPage } from "./builders/prompt-data";
+import { buildOutputPage } from "./builders/output-data";
+import { buildEnumsPage, findAnomalies, buildSearchIndex } from "./builders/extras";
+import type { Anomaly } from "./builders/extras";
+import { checkLinks } from "./link-check";
+import { legendHtml, esc as escBadge } from "./badges";
+import type { ObjectPageData } from "./builders/object-data";
+import type { PromptPageData } from "./builders/prompt-data";
+import type { OutputPageData } from "./builders/output-data";
+
+// ─── Public API ────────────────────────────────────────────────────────────────
+
+export interface SiteOptions {
+  sourceDirs: string[];
+  outDir: string;
+  title: string;
+  stamp: string;
+  commit: string;
+  core?: CoreConfig;
+  /** Override dir; if a file of the same basename exists here, it wins over the bundled templates/ dir. */
+  templatesDir?: string;
+  /** Override dir for assets; if a file of the same basename exists here, it wins over the bundled assets/ dir. */
+  assetsDir?: string | undefined;
+}
+
+export interface SiteResult {
+  pages: string[];
+  coverage: CoverageReport;
+  anomalies: Anomaly[];
+  dangling: string[];
+}
+
+// ─── Helpers ───────────────────────────────────────────────────────────────────
+
+/** Relative-root prefix: "" for root pages, "../../" for depth-2 pages. */
+function relRootFor(href: string): string {
+  const depth = href.split("/").length - 1;
+  return "../".repeat(depth);
+}
+
+/** Write a file, creating parent dirs as needed. */
+function writeOut(outDir: string, relPath: string, content: string | Uint8Array): string {
+  const abs = join(outDir, relPath);
+  mkdirSync(dirname(abs), { recursive: true });
+  writeFileSync(abs, content);
+  return relPath;
+}
+
+// ─── Template loading ──────────────────────────────────────────────────────────
+
+const SELF_DIR = dirname(fileURLToPath(import.meta.url));
+
+const BUNDLED_TEMPLATES = resolve(SELF_DIR, "../templates");
+
+function loadTemplate(name: string, overrideDir?: string): string {
+  if (overrideDir) {
+    const candidate = join(overrideDir, name);
+    if (existsSync(candidate)) return readFileSync(candidate, "utf8");
+  }
+  return readFileSync(join(BUNDLED_TEMPLATES, name), "utf8");
+}
+
+const BUNDLED_ASSETS = resolve(SELF_DIR, "../assets");
+
+function loadAsset(name: string, overrideDir?: string): string {
+  if (overrideDir) {
+    const candidate = join(overrideDir, name);
+    if (existsSync(candidate)) return readFileSync(candidate, "utf8");
+  }
+  return readFileSync(join(BUNDLED_ASSETS, name), "utf8");
+}
+
+// ─── Nav HTML ─────────────────────────────────────────────────────────────────
+
+/**
+ * Build the sidebar nav HTML for a specific page as a collapsible tree.
+ * Each package is a <details> element (open if it's the current page's package).
+ * Members are listed as links within each package. Deterministic: sorted packages, sorted members.
+ */
+function buildNavHtml(
+  g: LinkGraph,
+  relRoot: string,
+  currentPkgPath: string,
+  dataPackages: { pkg: string; pkgPath: string }[],
+  promptPackages: { pkg: string; pkgPath: string }[],
+): string {
+  const nodes = g.nodes();
+
+  const renderGroup = (label: string, pkgList: { pkg: string; pkgPath: string }[]): string => {
+    if (pkgList.length === 0) return "";
+    const parts: string[] = [`<div class="text-xs font-semibold opacity-50 mt-3 mb-1">${label}</div>`];
+    for (const p of pkgList) {
+      const isOpen = p.pkgPath === currentPkgPath;
+      const pkgHref = escBadge(relRoot + p.pkgPath + "/index.html");
+      const pkgLabel = escBadge(p.pkg);
+      const members = nodes
+        .filter((n) => n.pkg === p.pkg)
+        .sort((a, b) => a.name.localeCompare(b.name));
+      const memberLinks = members.map((m) =>
+        `<a href="${escBadge(relRoot + m.href)}" class="link font-mono text-xs opacity-70 hover:opacity-100 pl-3 block">${escBadge(m.name)}</a>`
+      ).join("\n");
+      parts.push(
+        `<details${isOpen ? " open" : ""}>\n` +
+        `<summary class="cursor-pointer font-mono text-xs opacity-70 hover:opacity-100"><a href="${pkgHref}">${pkgLabel}</a></summary>\n` +
+        memberLinks + `\n</details>`
+      );
+    }
+    return parts.join("\n");
+  };
+
+  return [
+    renderGroup("Data", dataPackages),
+    renderGroup("Prompts", promptPackages),
+  ].filter(Boolean).join("\n");
+}
+
+// ─── Orchestrator ─────────────────────────────────────────────────────────────
+
+export async function generateSite(opts: SiteOptions): Promise<SiteResult> {
+  // 1. Load + graph + comments
+  const loaded = await loadModel(opts.sourceDirs);
+  const g = new LinkGraph(loaded);
+  const docs = harvestComments(opts.sourceDirs);
+  const cov = new CoverageTracker();
+
+  // 2. Derive package lists (deterministic sort)
+  const nodes = g.nodes();
+  const allPkgs = [...new Set(nodes.map((n) => n.pkg))].sort();
+  const promptPkgSet = new Set(nodes.filter((n) => n.kind !== "object").map((n) => n.pkg));
+  const dataPkgList = allPkgs
+    .filter((p) => !promptPkgSet.has(p))
+    .map((p) => ({ pkg: p, pkgPath: p.split("::").join("/") }));
+  const promptPkgList = allPkgs
+    .filter((p) => promptPkgSet.has(p))
+    .map((p) => ({ pkg: p, pkgPath: p.split("::").join("/") }));
+
+  // 3. Load chrome templates (fixed)
+  const chromeHead = loadTemplate("chrome-head.mustache", opts.templatesDir);
+  const chromeFoot = loadTemplate("chrome-foot.mustache", opts.templatesDir);
+
+  // 4. Rendering helper: concat chrome + page template, render with payload + shared fields
+  const provider = new InMemoryProvider({});
+  const pages: string[] = [];
+
+  const legend = legendHtml();
+
+  // TOC builders — only list sections with non-empty data; ids must match id="s-..." in templates
+  const objectTocHtml = (d: ObjectPageData): string => {
+    const sections: { id: string; label: string; present: boolean }[] = [
+      { id: "s-overview", label: "Overview", present: !!d.desc },
+      { id: "s-fields", label: "Fields", present: d.ownFields.length > 0 },
+      { id: "s-indexes", label: "Indexes &amp; keys", present: d.indexes.length > 0 },
+      { id: "s-validators", label: "Validators", present: d.validators.length > 0 },
+      { id: "s-relationships", label: "Relationships", present: d.relations.length > 0 },
+      { id: "s-provenance", label: "Field provenance", present: d.origins.length > 0 },
+      { id: "s-inheritance", label: "Inheritance", present: !!d.inheritanceMermaid },
+      { id: "s-neighborhood", label: "Neighborhood", present: !!d.neighborhoodMermaid },
+      { id: "s-referenced-by", label: "Referenced by", present: d.referencedBy.length > 0 },
+    ];
+    return sections
+      .filter((s) => s.present)
+      .map((s) => `<a href="#${s.id}" class="link opacity-70 hover:opacity-100">${s.label}</a>`)
+      .join("\n");
+  };
+
+  const promptTocHtml = (d: PromptPageData): string => {
+    const sections: { id: string; label: string; present: boolean }[] = [
+      { id: "s-payload", label: "Payload tree", present: d.payloadTree.length > 0 },
+      { id: "s-source", label: "Source", present: !!d.sourceHtml },
+    ];
+    return sections
+      .filter((s) => s.present)
+      .map((s) => `<a href="#${s.id}" class="link opacity-70 hover:opacity-100">${s.label}</a>`)
+      .join("\n");
+  };
+
+  const outputTocHtml = (d: OutputPageData): string => {
+    const sections: { id: string; label: string; present: boolean }[] = [
+      { id: "s-contract", label: "Parse contract", present: d.fields.length > 0 },
+    ];
+    return sections
+      .filter((s) => s.present)
+      .map((s) => `<a href="#${s.id}" class="link opacity-70 hover:opacity-100">${s.label}</a>`)
+      .join("\n");
+  };
+
+  const renderPage = (
+    pageTemplateName: string,
+    href: string,
+    pageData: Record<string, unknown>,
+    tocHtml: string = "",
+    currentPkgPath: string = "",
+  ): void => {
+    const relRoot = relRootFor(href);
+    const navHtml = buildNavHtml(g, relRoot, currentPkgPath, dataPkgList, promptPkgList);
+    const pageTpl = loadTemplate(pageTemplateName, opts.templatesDir);
+    const template = chromeHead + pageTpl + chromeFoot;
+    const payload = {
+      ...pageData,
+      title: opts.title,
+      stamp: opts.stamp,
+      commit: opts.commit,
+      relRoot,
+      navHtml,
+      tocHtml,
+      legendHtml: legend,
+    };
+    const html = render({ template, payload, provider, format: "text" });
+    writeOut(opts.outDir, href, html);
+    pages.push(href);
+  };
+
+  // 5. Index page
+  const indexData = buildIndexPage(g, cov, {
+    title: opts.title,
+    stamp: opts.stamp,
+    commit: opts.commit,
+    core: opts.core,
+    sourceDirs: opts.sourceDirs,
+  });
+  renderPage("index.html.mustache", "index.html", indexData as unknown as Record<string, unknown>);
+
+  // 6. Enums page
+  const enumRows = buildEnumsPage(g);
+  renderPage("enums.html.mustache", "enums.html", { rows: enumRows } as Record<string, unknown>);
+
+  // 7. Anomalies + coverage (deferred until all pages built — build now, write after member pages)
+  const anomalies = findAnomalies(g, opts.sourceDirs);
+
+  // 8. Package + member pages (deterministic: pkgs sorted, then members sorted)
+  for (const pkg of allPkgs) {
+    const pkgData = buildPackagePage(pkg, g, cov, opts.sourceDirs);
+    const pkgHref = `${pkgData.pkgPath}/index.html`;
+    renderPage("package.html.mustache", pkgHref, pkgData as unknown as Record<string, unknown>, "", pkgData.pkgPath);
+
+    // Member pages sorted by name
+    const pkgNodes = nodes.filter((n) => n.pkg === pkg).sort((a, b) => a.name.localeCompare(b.name));
+    for (const n of pkgNodes) {
+      const fqn = fqnOf(n.node);
+      const pkgPath = n.pkgPath;
+      if (n.kind === "object") {
+        const data = buildObjectPage(fqn, g, cov);
+        renderPage("object.html.mustache", n.href, data as unknown as Record<string, unknown>, objectTocHtml(data), pkgPath);
+      } else if (n.kind === "prompt") {
+        const data = buildPromptPage(fqn, g, cov, opts.sourceDirs);
+        renderPage("prompt.html.mustache", n.href, data as unknown as Record<string, unknown>, promptTocHtml(data), pkgPath);
+      } else if (n.kind === "output") {
+        const data = buildOutputPage(fqn, g, cov, docs, opts.sourceDirs);
+        renderPage("output.html.mustache", n.href, data as unknown as Record<string, unknown>, outputTocHtml(data), pkgPath);
+      }
+    }
+  }
+
+  // 9. Coverage page (after all member pages so cov is fully populated)
+  const coverage = cov.report(loaded.root);
+  const coverageData = {
+    kinds: coverage.kinds,
+    attrs: coverage.attrs,
+    anomalies,
+  };
+  renderPage("coverage.html.mustache", "coverage.html", coverageData as Record<string, unknown>);
+
+  // 10. Write assets (consumer assetsDir wins over the bundled dir)
+  writeOut(opts.outDir, "assets/site.css", loadAsset("site.css", opts.assetsDir));
+  writeOut(opts.outDir, "assets/site.js", loadAsset("site.js", opts.assetsDir));
+
+  // 11. Search index
+  const searchIndex = buildSearchIndex(g);
+  writeOut(opts.outDir, "assets/search-index.json", JSON.stringify(searchIndex));
+
+  // 12. Link check (throws if any dangling links found)
+  const dangling = checkLinks(opts.outDir, pages);
+  if (dangling.length) throw new Error("link check failed:\n" + dangling.join("\n"));
+
+  return { pages, coverage, anomalies, dangling };
+}

package/src/yaml-comments.ts

@@ -0,0 +1,33 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+export interface CommentDocs { objectDesc: Map<string, string>; fieldNote: Map<string, string>; }
+const clean = (c: string) => c.replace(/^[#\s─═-]+/, "").replace(/[─═]+\s*$/, "").trim();
+
+export function harvestComments(sourceDirs: string[]): CommentDocs {
+  const objectDesc = new Map<string, string>(); const fieldNote = new Map<string, string>();
+  const files: string[] = [];
+  const walk = (d: string) => { for (const e of readdirSync(d)) { const p = join(d, e); if (statSync(p).isDirectory()) walk(p); else if (/\.ya?ml$/.test(e)) files.push(p); } };
+  for (const d of sourceDirs) walk(d);
+  for (const f of files) {
+    const lines = readFileSync(f, "utf8").split("\n");
+    let current: string | undefined;
+    for (let i = 0; i < lines.length; i++) {
+      const m = lines[i]!.match(/^\s*-\s*object\.\w+:/);
+      if (m) {
+        current = undefined;
+        for (let j = i + 1; j < Math.min(i + 4, lines.length); j++) {
+          const nm = lines[j]!.match(/^\s*name:\s*(\S+)/); if (nm) { current = nm[1]; break; }
+        }
+        if (current) {
+          const desc: string[] = [];
+          for (let k = i - 1; k >= 0 && lines[k]!.trim().startsWith("#"); k--) { const c = clean(lines[k]!.trim()); if (c) desc.unshift(c); }
+          if (desc.length) objectDesc.set(current, desc.join(" ").replace(/\s+/g, " ").slice(0, 400));
+        }
+      }
+      const fm = lines[i]!.match(/^\s*-\s*field\.\w+:\s*\{\s*name:\s*(\w+)[^}]*\}\s*#\s*(.+)$/);
+      if (fm && current) fieldNote.set(`${current}.${fm[1]}`, clean(fm[2]!).slice(0, 160));
+    }
+  }
+  return { objectDesc, fieldNote };
+}

package/templates/chrome-foot.mustache

@@ -0,0 +1,17 @@
+</main>
+<aside class="pl-toc hidden xl:block w-56 shrink-0 h-screen sticky top-0 overflow-y-auto py-8 pr-6 text-xs">
+  {{#tocHtml}}<div class="opacity-50 mb-2 uppercase tracking-wide">On this page</div><div class="flex flex-col gap-1">{{{tocHtml}}}</div>{{/tocHtml}}
+  <div class="opacity-50 mt-6 mb-2 uppercase tracking-wide">Legend</div><div class="flex flex-wrap gap-1">{{{legendHtml}}}</div>
+</aside>
+</div>
+<dialog id="search-modal" class="modal">
+  <div class="modal-box max-w-2xl p-0">
+    <label class="input input-bordered flex items-center gap-2 m-3"><input id="search" type="search" placeholder="search entities, fields, prompts…" class="grow" autofocus><kbd class="kbd kbd-xs">esc</kbd></label>
+    <div id="search-results" class="max-h-96 overflow-y-auto px-3 pb-3 flex flex-col gap-0.5"></div>
+  </div>
+  <form method="dialog" class="modal-backdrop"><button>close</button></form>
+</dialog>
+<footer class="pl-footer text-xs opacity-40 px-10 pb-6">generated {{stamp}} · {{commit}} · metadata-docs</footer>
+<script>window.__REL_ROOT__ = "{{relRoot}}";</script>
+<script src="{{relRoot}}assets/site.js"></script>
+</body></html>

package/templates/chrome-head.mustache

@@ -0,0 +1,21 @@
+<!DOCTYPE html>
+<html lang="en" data-theme="night">
+<head>
+<meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>{{title}}</title>
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/daisyui@5.5.19/daisyui.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/daisyui@5.5.19/themes.css">
+<script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4.2.4/dist/index.global.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/svg-pan-zoom@3.6.2/dist/svg-pan-zoom.min.js"></script>
+<link rel="stylesheet" href="{{relRoot}}assets/site.css">
+</head>
+<body class="min-h-screen bg-base-200 text-base-content">
+<div class="flex">
+<nav class="pl-sidebar hidden lg:flex flex-col w-72 shrink-0 h-screen sticky top-0 border-r border-base-300 bg-base-100 overflow-y-auto p-4 gap-1 text-sm">
+  <a href="{{relRoot}}index.html" class="font-bold font-mono text-primary">{{title}}</a>
+  <button id="search-open" class="btn btn-sm btn-block justify-between my-2 font-normal opacity-80">
+    <span>search…</span><kbd class="kbd kbd-xs">⌘K</kbd></button>
+  {{{navHtml}}}
+</nav>
+<main class="min-w-0 flex-1 max-w-4xl px-6 lg:px-10 py-8">

package/templates/coverage.html.mustache

@@ -0,0 +1,24 @@
+<h1 class="text-2xl font-bold font-mono">Coverage</h1>
+<p class="text-sm opacity-60 mt-1">Which metadata node kinds and attributes are rendered by the doc pages.</p>
+{{#kinds.length}}
+<h2 class="text-lg font-semibold mt-6">Node kinds</h2>
+<div class="overflow-x-auto"><table class="table table-xs">
+  <thead><tr><th>Kind</th><th>Count</th><th>Rendered</th></tr></thead><tbody>
+  {{#kinds}}<tr><td class="font-mono">{{key}}</td><td>{{count}}</td><td>{{#consumed}}<span class="badge badge-success badge-xs">✓</span>{{/consumed}}{{^consumed}}<span class="badge badge-error badge-xs">✗</span>{{/consumed}}</td></tr>{{/kinds}}
+  </tbody></table></div>
+{{/kinds.length}}
+{{#attrs.length}}
+<h2 class="text-lg font-semibold mt-6">Attributes</h2>
+<div class="overflow-x-auto"><table class="table table-xs">
+  <thead><tr><th>Attribute</th><th>Count</th><th>Rendered</th></tr></thead><tbody>
+  {{#attrs}}<tr><td class="font-mono">{{key}}</td><td>{{count}}</td><td>{{#consumed}}<span class="badge badge-success badge-xs">✓</span>{{/consumed}}{{^consumed}}<span class="badge badge-error badge-xs">✗</span>{{/consumed}}</td></tr>{{/attrs}}
+  </tbody></table></div>
+{{/attrs.length}}
+{{#anomalies.length}}
+<h2 class="text-lg font-semibold mt-6">Anomalies</h2>
+<div class="overflow-x-auto"><table class="table table-xs">
+  <thead><tr><th>Kind</th><th>Subject</th><th>Detail</th></tr></thead><tbody>
+  {{#anomalies}}<tr><td class="font-mono opacity-70">{{kind}}</td><td><a class="link font-mono" href="{{relRoot}}{{href}}">{{subject}}</a></td><td class="text-xs opacity-70">{{detail}}</td></tr>{{/anomalies}}
+  </tbody></table></div>
+{{/anomalies.length}}
+{{^anomalies.length}}<p class="text-sm opacity-50 mt-4">No anomalies detected.</p>{{/anomalies.length}}

package/templates/enums.html.mustache

@@ -0,0 +1,14 @@
+<h1 class="text-2xl font-bold font-mono">Enums</h1>
+<p class="text-sm opacity-60 mt-1">All enum-valued fields across the metadata.</p>
+{{#rows.length}}
+<div class="overflow-x-auto mt-4"><table class="table table-xs">
+  <thead><tr><th>Owner</th><th>Field</th><th>Values</th><th>Default</th></tr></thead><tbody>
+  {{#rows}}<tr>
+    <td><a class="link font-mono" href="{{relRoot}}{{ownerHref}}">{{owner}}</a></td>
+    <td class="font-mono">{{field}}</td>
+    <td class="flex flex-wrap gap-1">{{#values}}<span class="badge badge-ghost badge-xs font-mono">{{.}}</span>{{/values}}</td>
+    <td class="font-mono opacity-60">{{deflt}}</td>
+  </tr>{{/rows}}
+  </tbody></table></div>
+{{/rows.length}}
+{{^rows.length}}<p class="text-sm opacity-50 mt-4">No enum fields found.</p>{{/rows.length}}

package/templates/index.html.mustache

@@ -0,0 +1,54 @@
+<h1 class="text-2xl font-bold font-mono">{{title}}</h1>
+<div class="stats stats-horizontal shadow my-4 text-sm">
+  <div class="stat"><div class="stat-title">objects</div><div class="stat-value font-mono text-lg">{{stats.objects}}</div></div>
+  <div class="stat"><div class="stat-title">tables</div><div class="stat-value font-mono text-lg">{{stats.tables}}</div></div>
+  <div class="stat"><div class="stat-title">packages</div><div class="stat-value font-mono text-lg">{{stats.packages}}</div></div>
+  <div class="stat"><div class="stat-title">prompt VOs</div><div class="stat-value font-mono text-lg">{{stats.promptVos}}</div></div>
+  <div class="stat"><div class="stat-title">prompts</div><div class="stat-value font-mono text-lg">{{stats.prompts}}</div></div>
+  <div class="stat"><div class="stat-title">contracts</div><div class="stat-value font-mono text-lg">{{stats.contracts}}</div></div>
+  <div class="stat"><div class="stat-title">enums</div><div class="stat-value font-mono text-lg">{{stats.enums}}</div></div>
+</div>
+{{#coreMermaid}}
+<div class="card bg-base-100 border border-base-300 p-4 my-4">
+  <div class="font-semibold mb-2">Core ERD</div>
+  <div class="pl-diagram"><pre class="mermaid">{{coreMermaid}}</pre></div>
+  <div class="text-xs opacity-50 mt-1">{{coreCaption}}</div>
+  {{#coreLegend.length}}<div class="flex flex-wrap gap-1 mt-2 text-xs">{{#coreLegend}}<span class="badge badge-xs" style="background:{{fill}};border-color:{{stroke}};color:#cbd5e1">{{pkg}}</span>{{/coreLegend}}</div>
+  <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}}
+{{#packageMermaid}}
+<div class="card bg-base-100 border border-base-300 p-4 my-4">
+  <div class="font-semibold mb-2">Package dependencies</div>
+  <div class="pl-diagram"><pre class="mermaid">{{packageMermaid}}</pre></div>
+</div>
+{{/packageMermaid}}
+{{#fullEdges.length}}
+<details class="my-4">
+  <summary class="cursor-pointer text-sm font-semibold">All cross-package edges</summary>
+  <div class="overflow-x-auto mt-2"><table class="table table-xs">
+    <thead><tr><th>From</th><th>To</th><th>n</th></tr></thead><tbody>
+    {{#fullEdges}}<tr><td class="font-mono">{{from}}</td><td class="font-mono">{{to}}</td><td>{{n}}</td></tr>{{/fullEdges}}
+    </tbody></table></div>
+</details>
+{{/fullEdges.length}}
+{{#dataPackages.length}}
+<h2 class="text-lg font-semibold mt-6">Data packages</h2>
+<div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-3 mt-2">
+{{#dataPackages}}<a href="{{relRoot}}{{href}}" class="card bg-base-100 border border-base-300 p-3 hover:border-primary transition-colors">
+  <div class="font-mono font-semibold text-sm">{{pkg}}</div>
+  <div class="text-xs opacity-60 mt-1">{{objectCount}} objects · {{promptCount}} prompts · {{contractCount}} contracts</div>
+  <div class="text-xs opacity-60 mt-1">{{purpose}}</div>
+</a>{{/dataPackages}}
+</div>
+{{/dataPackages.length}}
+{{#promptPackages.length}}
+<h2 class="text-lg font-semibold mt-6">Prompt packages</h2>
+<div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-3 mt-2">
+{{#promptPackages}}<a href="{{relRoot}}{{href}}" class="card bg-base-100 border border-base-300 p-3 hover:border-secondary transition-colors">
+  <div class="font-mono font-semibold text-sm">{{pkg}}</div>
+  <div class="text-xs opacity-60 mt-1">{{objectCount}} objects · {{promptCount}} prompts · {{contractCount}} contracts</div>
+  <div class="text-xs opacity-60 mt-1">{{purpose}}</div>
+</a>{{/promptPackages}}
+</div>
+{{/promptPackages.length}}

package/templates/object.html.mustache

@@ -0,0 +1,46 @@
+<div class="text-xs breadcrumbs font-mono opacity-70"><ul><li>{{{breadcrumbHtml}}}</li></ul></div>
+<h1 class="text-2xl font-bold font-mono mt-1">{{name}}
+  <span class="badge badge-primary badge-sm align-middle">{{kindBadge}}</span>
+  {{#isView}}<span class="badge badge-info badge-sm align-middle">view</span>{{/isView}}
+  {{#isAbstract}}<span class="badge badge-ghost badge-sm align-middle">abstract</span>{{/isAbstract}}</h1>
+<div class="font-mono text-xs opacity-60 mt-1">
+  {{#tableName}}{{#isView}}view{{/isView}}{{^isView}}table{{/isView}} <code>{{tableName}}</code>{{/tableName}}
+  {{#pkHtml}} · pk {{{pkHtml}}}{{/pkHtml}}{{#generation}} · gen {{generation}}{{/generation}}</div>
+{{#desc}}<section id="s-overview" class="mt-4"><p class="text-sm leading-relaxed">{{desc}}</p></section>{{/desc}}
+
+<section id="s-fields" class="mt-6"><h2 class="text-lg font-semibold">Fields</h2>
+<div class="overflow-x-auto"><table class="table table-xs"><thead><tr><th>Field</th><th>Type</th><th></th><th>Description</th></tr></thead><tbody>
+{{#ownFields}}<tr id="{{anchor}}"><td class="font-mono">{{name}}{{#isArray}}[]{{/isArray}}</td><td class="opacity-60">{{type}}</td><td>{{{badgesHtml}}}</td><td class="text-xs">{{desc}}</td></tr>
+{{#enumValues.length}}<tr><td></td><td colspan="3" class="pl-4">{{#enumValues}}<span class="badge badge-soft badge-accent badge-xs mr-1">{{value}}{{#deflt}} ★{{/deflt}}</span>{{/enumValues}}</td></tr>{{/enumValues.length}}
+{{/ownFields}}
+</tbody></table></div>
+{{#inheritedFields.length}}<div class="collapse collapse-arrow bg-base-100 border border-base-300 mt-2"><input type="checkbox"><div class="collapse-title text-sm font-semibold opacity-70">Inherited fields ({{inheritedFields.length}})</div><div class="collapse-content"><table class="table table-xs opacity-80"><tbody>
+{{#inheritedFields}}<tr id="{{anchor}}"><td class="font-mono">{{name}}{{#isArray}}[]{{/isArray}} <span class="text-[10px] opacity-50">↑ <a class="link" href="{{inheritedFrom.href}}">{{inheritedFrom.name}}</a></span></td><td class="opacity-60">{{type}}</td><td>{{{badgesHtml}}}</td></tr>{{/inheritedFields}}
+</tbody></table></div></div>{{/inheritedFields.length}}</section>
+
+{{#indexes.length}}<section id="s-indexes" class="mt-6"><h2 class="text-lg font-semibold">Indexes &amp; keys</h2>
+<table class="table table-xs"><thead><tr><th>Name</th><th>Kind</th><th>Fields</th><th>Detail</th></tr></thead><tbody>
+{{#indexes}}<tr><td class="font-mono">{{name}}</td><td><span class="badge badge-soft {{#unique}}badge-success{{/unique}}{{^unique}}badge-neutral{{/unique}} badge-xs">{{kind}}</span></td><td class="font-mono text-xs">{{fields}}</td><td class="text-xs opacity-70">{{extra}}</td></tr>{{/indexes}}
+</tbody></table></section>{{/indexes.length}}
+
+{{#validators.length}}<section id="s-validators" class="mt-6"><h2 class="text-lg font-semibold">Validators</h2>
+<table class="table table-xs"><tbody>{{#validators}}<tr><td class="font-mono text-xs opacity-70">{{subject}}</td><td class="font-mono text-xs">{{rule}}</td></tr>{{/validators}}</tbody></table></section>{{/validators.length}}
+
+{{#relations.length}}<section id="s-relationships" class="mt-6"><h2 class="text-lg font-semibold">Relationships</h2>
+<table class="table table-xs"><tbody>{{#relations}}<tr><td class="font-mono">{{name}}</td><td class="text-xs opacity-60">{{cardinality}}</td><td><a class="link font-mono text-xs" href="{{toHref}}">{{toName}}</a></td></tr>{{/relations}}</tbody></table></section>{{/relations.length}}
+
+{{#origins.length}}<section id="s-provenance" class="mt-6"><h2 class="text-lg font-semibold">Field provenance</h2>
+<table class="table table-xs"><thead><tr><th>Field</th><th>From</th><th>Via</th></tr></thead><tbody>{{#origins}}<tr><td class="font-mono">{{field}}</td><td class="font-mono text-xs opacity-70">{{from}}</td><td class="font-mono text-xs opacity-70">{{via}}</td></tr>{{/origins}}</tbody></table></section>{{/origins.length}}
+
+{{#inheritanceMermaid}}<section id="s-inheritance" class="mt-6"><h2 class="text-lg font-semibold">Inheritance</h2>
+<div class="card bg-base-100 border border-base-300 p-2 pl-diagram"><pre class="mermaid">{{inheritanceMermaid}}</pre></div></section>{{/inheritanceMermaid}}
+
+{{#neighborhoodMermaid}}<section id="s-neighborhood" class="mt-6"><h2 class="text-lg font-semibold">Neighborhood</h2>
+<div class="card bg-base-100 border border-base-300 p-2 pl-diagram"><pre class="mermaid">{{neighborhoodMermaid}}</pre></div>
+{{#neighborhoodLegend.length}}<div class="flex flex-wrap gap-1 mt-2 text-xs">{{#neighborhoodLegend}}<span class="badge badge-xs" style="background:{{fill}};border-color:{{stroke}};color:#cbd5e1">{{pkg}}</span>{{/neighborhoodLegend}}</div>{{/neighborhoodLegend.length}}
+<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 <span class="opacity-70">(ER boxes: dashed = value, dotted = view)</span></div>
+{{#neighborhoodMore}}<div class="text-xs opacity-50 mt-1">+{{neighborhoodMore}} more neighbor(s) — see <a class="link" href="#s-referenced-by">Referenced by</a>.</div>{{/neighborhoodMore}}</section>{{/neighborhoodMermaid}}
+
+{{#referencedBy.length}}<section id="s-referenced-by" class="mt-6 text-sm"><span class="opacity-50">referenced by</span> {{#referencedBy}}<a class="link font-mono text-xs" href="{{href}}" title="{{via}}">{{name}}</a> {{/referencedBy}}</section>{{/referencedBy.length}}
+{{#usedByTemplates.length}}<div class="text-sm mt-1"><span class="opacity-50">used by templates</span> {{#usedByTemplates}}<a class="link font-mono text-xs" href="{{href}}">{{name}}</a> {{/usedByTemplates}}</div>{{/usedByTemplates.length}}
+<div class="text-[10px] opacity-40 mt-6 font-mono">{{sourceFile}}</div>

package/templates/output.html.mustache

@@ -0,0 +1,16 @@
+<div class="text-xs breadcrumbs font-mono opacity-70"><ul><li>{{{breadcrumbHtml}}}</li></ul></div>
+<h1 class="text-2xl font-bold font-mono mt-1">{{name}} <span class="badge badge-accent badge-sm align-middle">{{format}}</span> <span class="badge badge-ghost badge-sm align-middle">output</span></h1>
+{{#payloadName}}<div class="text-sm mt-2 opacity-70">payload: <a class="link font-mono" href="{{payloadHref}}">{{payloadName}}</a></div>{{/payloadName}}
+<div class="text-sm mt-1 opacity-60 font-mono">
+  textRef: {{textRef}}
+  {{^textRefResolves}}<span class="badge badge-warning badge-xs ml-2">forward-pointing</span>{{/textRefResolves}}
+</div>
+{{#desc}}<p class="mt-3 text-sm">{{desc}}</p>{{/desc}}
+{{#fields.length}}
+<section id="s-contract" class="mt-6"><h2 class="text-lg font-semibold">Parse contract</h2>
+<div class="overflow-x-auto"><table class="table table-xs">
+  <thead><tr><th>Field</th><th>Type</th><th>Wire</th><th>Meaning</th></tr></thead><tbody>
+  {{#fields}}<tr><td class="font-mono">{{name}}{{#isArray}}[]{{/isArray}}</td><td class="opacity-60">{{type}}</td><td class="font-mono text-xs opacity-70">{{wire}}</td><td>{{{refHtml}}}{{#note}} {{note}}{{/note}}</td></tr>{{/fields}}
+  </tbody></table></div>
+</section>
+{{/fields.length}}

package/templates/package.html.mustache

@@ -0,0 +1,43 @@
+<div class="text-xs breadcrumbs font-mono opacity-70"><ul><li>{{{breadcrumbHtml}}}</li></ul></div>
+<h1 class="text-2xl font-bold font-mono">{{title}}</h1>
+{{#descHtml}}<p class="text-sm my-3">{{descHtml}}</p>{{/descHtml}}
+{{#keyCards.length}}
+<div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-3 my-4">
+{{#keyCards}}<a href="{{href}}" class="card bg-base-100 border border-base-300 p-3"><div class="font-mono font-semibold">{{name}}</div><div class="text-xs opacity-50">{{inbound}} refs</div></a>{{/keyCards}}
+</div>
+{{/keyCards.length}}
+{{#erdMermaid}}<div class="card bg-base-100 border border-base-300 p-2 pl-diagram my-4"><pre class="mermaid">{{erdMermaid}}</pre>{{#erdLegend.length}}<div class="flex flex-wrap gap-1 mt-2 text-xs">{{#erdLegend}}<span class="badge badge-xs" style="background:{{fill}};border-color:{{stroke}};color:#cbd5e1">{{pkg}}</span>{{/erdLegend}}</div>{{/erdLegend.length}}<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></div>{{/erdMermaid}}
+{{#abstracts.length}}
+<h2 class="text-lg font-semibold mt-6">Abstracts</h2>
+<div class="overflow-x-auto"><table class="table table-xs">
+  <thead><tr><th>Name</th><th>Kind</th><th>Fields</th></tr></thead><tbody>
+  {{#abstracts}}<tr><td><a class="link font-mono" href="{{href}}">{{name}}</a></td><td class="opacity-60">{{kind}}</td><td>{{fieldCount}}</td></tr>{{/abstracts}}
+  </tbody></table></div>
+{{/abstracts.length}}
+{{#objects.length}}
+<h2 class="text-lg font-semibold mt-6">Objects</h2>
+<div class="overflow-x-auto"><table class="table table-xs">
+  <thead><tr><th>Name</th><th>Kind</th><th>Table</th><th>Fields</th><th>Extends</th></tr></thead><tbody>
+  {{#objects}}<tr><td><a class="link font-mono" href="{{href}}">{{name}}</a></td><td class="opacity-60">{{kind}}</td><td class="font-mono opacity-60">{{table}}</td><td>{{fieldCount}}</td><td class="font-mono opacity-60">{{extendsName}}</td></tr>{{/objects}}
+  </tbody></table></div>
+{{/objects.length}}
+{{#prompts.length}}
+<h2 class="text-lg font-semibold mt-6">Prompts</h2>
+<div class="overflow-x-auto"><table class="table table-xs">
+  <thead><tr><th>Name</th><th>Payload</th><th>Format</th><th>textRef</th></tr></thead><tbody>
+  {{#prompts}}<tr><td><a class="link font-mono" href="{{href}}">{{name}}</a></td><td><a class="link font-mono opacity-70" href="{{payloadHref}}">{{payloadName}}</a></td><td class="opacity-60">{{format}}</td><td class="font-mono text-xs opacity-50">{{textRef}}</td></tr>{{/prompts}}
+  </tbody></table></div>
+{{/prompts.length}}
+{{#outputs.length}}
+<h2 class="text-lg font-semibold mt-6">Output contracts</h2>
+<div class="overflow-x-auto"><table class="table table-xs">
+  <thead><tr><th>Name</th><th>Payload</th><th>Format</th><th>textRef</th></tr></thead><tbody>
+  {{#outputs}}<tr><td><a class="link font-mono" href="{{href}}">{{name}}</a></td><td><a class="link font-mono opacity-70" href="{{payloadHref}}">{{payloadName}}</a></td><td class="opacity-60">{{format}}</td><td class="font-mono text-xs opacity-50">{{textRef}}</td></tr>{{/outputs}}
+  </tbody></table></div>
+{{/outputs.length}}
+{{#referencedBy.length}}
+<h2 class="text-lg font-semibold mt-6">Referenced by</h2>
+<div class="flex flex-wrap gap-2 mt-2">
+  {{#referencedBy}}<a href="{{href}}" class="badge badge-ghost font-mono">{{pkg}} <span class="opacity-50 ml-1">×{{n}}</span></a>{{/referencedBy}}
+</div>
+{{/referencedBy.length}}

package/templates/prompt.html.mustache

@@ -0,0 +1,28 @@
+<div class="text-xs breadcrumbs font-mono opacity-70"><ul><li>{{{breadcrumbHtml}}}</li></ul></div>
+<h1 class="text-2xl font-bold font-mono mt-1">{{name}} <span class="badge badge-secondary badge-sm align-middle">prompt</span></h1>
+<div class="flex flex-wrap gap-1 mt-2">{{{attrsHtml}}}</div>
+{{#payloadName}}<div class="text-sm mt-2 opacity-70">payload: <a class="link font-mono" href="{{payloadHref}}">{{payloadName}}</a></div>{{/payloadName}}
+{{#desc}}<p class="text-sm mb-3">{{desc}}</p>{{/desc}}
+{{#payloadTree.length}}
+<section id="s-payload" class="mt-6"><h2 class="text-lg font-semibold">Payload tree</h2>
+<div class="overflow-x-auto"><table class="table table-xs">
+  <thead><tr><th>Field</th><th>Type</th><th>Ref</th><th>Description</th></tr></thead><tbody>
+  {{#payloadTree}}<tr id="{{anchor}}" class="pl-indent-{{indent}}"><td class="font-mono">{{name}}{{#isArray}}[]{{/isArray}}</td><td class="opacity-60">{{type}}</td><td>{{{refHtml}}}</td><td class="text-xs opacity-70">{{desc}}</td></tr>{{/payloadTree}}
+  </tbody></table></div>
+</section>
+{{/payloadTree.length}}
+{{#sourceHtml}}
+<section id="s-source" class="mt-6"><h2 class="text-lg font-semibold">Source</h2>
+<pre class="pl-mu">{{{sourceHtml}}}</pre>
+</section>
+{{/sourceHtml}}
+{{#sourceMissingNote}}<div class="alert alert-warning text-sm mt-4">{{sourceMissingNote}}</div>{{/sourceMissingNote}}
+{{#packageFiles.length}}
+<h2 class="text-lg font-semibold mt-6">Other files in package</h2>
+{{#packageFiles}}
+<details class="mt-2">
+  <summary class="cursor-pointer font-mono text-sm opacity-70">{{file}}</summary>
+  <pre class="pl-mu mt-1">{{{html}}}</pre>
+</details>
+{{/packageFiles}}
+{{/packageFiles.length}}