feat(admin): the insights artifact -- one page for topology and spend (issue #175)

The fourth insights slice, the one the series exists for: /dispatch
insights html [7d|30d|mtd] writes <graphDir>/insights.html, one
self-contained file:// document -- the trigger/flow topology with spend
badged onto its triggers, beside the cost fold drawn as hand-rolled
inline SVG charts (KPI tiles, plan verdict cards, a daily spend column
chart, the four breakdown bar lists).

- graph-html.mjs gains exports, not loads: buildGraphScene is the
  normalize+layout+SVG-emission half of buildGraphHtml extracted whole
  (behavior-preserving; every existing pin green untouched), plus
  escapeHtml/embedJson/fmt/PAGE_JS/legendHtml/bannersHtml/PAGE_THEME.
  The purity pin is substring-level and directional on purpose: the
  module may be a source of truth for a sibling emitter, it may never
  load one itself.
- insights-html.mjs: two loads only (graph-html, panel), so the money
  strings come from the REAL fmtCost -- a plan-covered bucket draws a
  plan:<id> chip and NO dollar bar, estimates are dashed and
  translucent beside their ~ est. text (hue never the sole encoding),
  floors carry >= on the chart, gap days render as baseline ticks, a
  null byTrigger renders 'not computed'. Byte-deterministic under
  permutation, total on junk, allowlist-normalized, one script element,
  no fetching, no innerHTML, textContent-only tips, row->node
  cross-highlight by replaying a guarded synthetic click so PAGE_JS
  keeps sole ownership of selection. The topology pane takes the
  scene's own aspect ratio (a fixed pane letterboxed a flat topology
  into a mostly-empty band; caught by a headless-Chrome screenshot).
- index.ts: the insights subcommand (bare insights answers usage; the
  artifact IS the feature), USAGE/KNOWN_SUBCOMMANDS/description in
  step, completion for insights html <window>, assembleInsights
  composing the two existing assemblers, insightsHtmlCommand as
  graphHtmlCommand's structural twin (atomic stable path, URL first,
  headless skip-and-say, write-failure never opens). Default window
  30d, deliberately not costs' mtd: the topology half is pinned at a
  30d record window and one page's halves should agree.

Specs in the same PR: NEW REQ-INSIGHTS-HTML-EXPORT;
REQ-COST-ANALYTICS amended one sentence (the artifact joins the named
surfaces; rules (a)-(g) unchanged); DES-ADMIN-VIA-PI-EXTENSION amended
with the factoring facts and rejections (shared third emitter,
duplication, in-place folding, a charting dependency);
REQ-GRAPH-HTML-EXPORT UNCHANGED, checked (graph html stays the lighter
topology-only export); REQ-TOPOLOGY-GRAPH UNCHANGED, checked;
DES-GRAPH-EDGE-DERIVATION UNCHANGED, checked; DES-COST-FOLD-BY-SCAN
UNCHANGED, checked. New docs/insights.md; cross-links in docs/graph.md
and docs/costs.md.

Suite green in the CI posture: 2224 tests, 0 skipped, live Valkey.

Signed-off-by: Rob Boerman <robboerman@live.nl>

Author: edgehero

admin/src/graph-html.mjs

@@ -93,6 +93,22 @@ const STATUS_OTHER = "#6e7681";
 const BADGE_ORANGE = "#db6d28";
 const BADGE_GREEN = "#3fb950";
 const DANGER = "#f85149";
+
+// The page palette as one frozen bag, for the sibling artifact builder (insights-html.mjs): this
+// module may be a source of truth for other pure emitters, it may just never load one itself --
+// the purity test's ban is directional on purpose.
+export const PAGE_THEME = Object.freeze({
+  canvas: PAGE_CANVAS,
+  panel: PAGE_PANEL,
+  border: PAGE_BORDER,
+  fg: PAGE_FG,
+  dim: PAGE_DIM,
+  accent: PAGE_ACCENT,
+  amber: PAGE_AMBER,
+  danger: DANGER,
+  green: STATUS_COMPLETED,
+  chipStroke: CHIP_STROKE,
+});
 const GROUP_FILL = "#E6E0F8";
 const WIRE_OBSERVED = "#999";
 const WIRE_CONFIG = "#6e7681";
@@ -114,14 +130,14 @@ const GLYPH = Object.freeze({
 // The 5-entity escape, byte-for-byte the worker's buildFormPage helper: every string interpolated
 // into markup goes through this, operator-authored or not, because "charset-bound upstream" is an
 // assumption and an entity is a guarantee.
-function escapeHtml(s) {
+export function escapeHtml(s) {
   return String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
 
 // JSON destined for the inline script: `<` becomes < so no value can spell `</script>` and
 // break out of the script element, and U+2028/2029 become escapes because they are line
 // terminators to a JS parser while being invisible to JSON.
-function embedJson(value) {
+export function embedJson(value) {
   return JSON.stringify(value)
     .replace(/</g, "\\u003c")
     .replace(/\u2028/g, "\\u2028")
@@ -130,7 +146,7 @@ function embedJson(value) {
 
 // Every number that reaches markup goes through this: a non-finite value becomes 0 rather than
 // serialising as one of the three words the well-formedness test bans outright.
-function fmt(v) {
+export function fmt(v) {
   const n = Number.isFinite(v) ? Math.round(v * 10) / 10 : 0;
   return String(n);
 }
@@ -908,7 +924,7 @@ function legendSwatch(inner) {
   return `<svg width="16" height="12" aria-hidden="true">${inner}</svg>`;
 }
 
-function legendHtml(norm) {
+export function legendHtml(norm) {
   const rows = [];
   const row = (sample, text) => rows.push(`<div class="row">${sample}<span>${escapeHtml(text)}</span></div>`);
   rows.push("<h2>edges</h2>");
@@ -938,7 +954,7 @@ function legendHtml(norm) {
   return `<div id="legend">${rows.join("")}</div>`;
 }
 
-function bannersHtml(norm) {
+export function bannersHtml(norm) {
   const banners = [];
   if (!norm.ok) banners.push("no graph model supplied; the page has nothing to draw");
   if (norm.meta.triggersMissing) banners.push("no triggers file found");
@@ -976,7 +992,7 @@ svg.canvas{display:block;width:100%;height:100%;cursor:grab;touch-action:none}
 // sit inside one), and with three hard rules the tests pin: no fetching of any kind, no markup
 // assembly on the client (textContent only), and the clock read spelled without the static
 // accessor this module's purity regex bans.
-const PAGE_JS = `
+export const PAGE_JS = `
 (function () {
   "use strict";
   var svg = document.getElementById("graph");
@@ -1166,7 +1182,15 @@ const PAGE_JS = `
  * the available outcomes. `now` is the injected generation instant (ms epoch); the module never
  * reads a clock of its own, so the same model and the same now are byte-identical forever.
  */
-export function buildGraphHtml(model, { now, fullPaths } = {}) {
+/**
+ * The scene half of the page: normalize, lay out, and emit the SVG body plus the per-node data the
+ * page script needs. Split from buildGraphHtml so a sibling artifact (insights-html.mjs) can place
+ * the same topology inside a larger document without a second layout engine or a second escaping
+ * discipline. The layout's placed nodes still hold their normalised node objects (original ids and
+ * all) -- that is server-side composition state for the caller; only `svgBody`/`graphData` strings
+ * belong in a page, and they carry minted ordinals alone.
+ */
+export function buildGraphScene(model, { now, fullPaths } = {}) {
   let norm;
   try {
     norm = normalizeModel(model);
@@ -1222,7 +1246,11 @@ export function buildGraphHtml(model, { now, fullPaths } = {}) {
     layout.wires.map((w) => wireSvg(w, nowMs)).join(""),
     nodeParts.join(""),
   ].join("");
-  const vb = layout.viewBox;
+  return { norm, layout, svgBody, viewBox: layout.viewBox, graphData, nowMs };
+}
+
+export function buildGraphHtml(model, { now, fullPaths } = {}) {
+  const { norm, svgBody, viewBox: vb, graphData, nowMs } = buildGraphScene(model, { now, fullPaths });
   const svgEl = [
     `<svg id="graph" class="canvas" viewBox="${fmt(vb.x)} ${fmt(vb.y)} ${fmt(vb.w)} ${fmt(vb.h)}" role="img" aria-label="pi-dispatch trigger and flow graph" preserveAspectRatio="xMidYMid meet">`,
     `<g id="root">${svgBody}</g>`,

admin/src/index.ts

@@ -85,6 +85,7 @@ import {
 } from "./read-model.mjs";
 import { buildGraphModel } from "./graph-model.mjs";
 import { buildGraphHtml } from "./graph-html.mjs";
+import { buildInsightsHtml } from "./insights-html.mjs";
 import { openBrowser } from "@edgehero/pi-dispatch/open-browser";
 // The deployment pointer (INT-DEPLOYMENT-POINTER-CONTRACT): the wizard-written file that aims this
 // extension at a deployment built in another directory. Layered into process.env once at factory load
@@ -162,7 +163,7 @@ const REBUILT_NOTICE = (reason: string) =>
   `replaced invalid settings file (${reason}) — other keys were lost`;
 
 const USAGE =
-  "usage: /dispatch <status|pause|resume|run|runs|logs|budget|costs|graph|triggers|settings|set|unset|setup>";
+  "usage: /dispatch <status|pause|resume|run|runs|logs|budget|costs|graph|insights|triggers|settings|set|unset|setup>";
 
 const KNOWN_SUBCOMMANDS = [
   "status",
@@ -174,6 +175,7 @@ const KNOWN_SUBCOMMANDS = [
   "budget",
   "costs",
   "graph",
+  "insights",
   "triggers",
   "settings",
   "set",
@@ -217,8 +219,10 @@ export default function admin(pi: ExtensionAPI): void {
   }
 
   pi.registerCommand("dispatch", {
+    // The operator-visible summary; `graph` was missing from it once while USAGE carried it, which
+    // is exactly the drift the USAGE/KNOWN_SUBCOMMANDS pin exists to catch -- keep all three in step.
     description:
-      "pi-dispatch admin: status|pause|resume|run|runs|logs|budget|costs|triggers|settings|set|unset|setup",
+      "pi-dispatch admin: status|pause|resume|run|runs|logs|budget|costs|graph|insights|triggers|settings|set|unset|setup",
     getArgumentCompletions: (prefix) => completeArguments(prefix),
     handler: async (args, ctx) => dispatch(pi, args, ctx),
   });
@@ -944,6 +948,17 @@ async function dispatch(pi: ExtensionAPI, args: string, ctx: any): Promise<void>
       send(pi, renderGraph(await assembleGraph(paths)));
       return;
     }
+    case "insights": {
+      // `insights html` is the only verb: the artifact IS the feature (issue #175), and a bare
+      // `insights` answering usage beats it silently aliasing either half's text renderer. Same
+      // no-LLM-tool posture as `graph`: the assembly spawns git per folder.
+      if (tokens[1] === "html") {
+        await insightsHtmlCommand(paths, tokens, notify);
+        return;
+      }
+      notify?.(INSIGHTS_USAGE, "warning");
+      return;
+    }
     case "run": {
       const folder = tokens[1];
       const flow = tokens[2];
@@ -1147,6 +1162,79 @@ export async function graphHtmlCommand(paths: any, tokens: string[], notify: Not
   deps.openBrowser(url);
 }
 
+const INSIGHTS_USAGE = "usage: /dispatch insights html [7d|30d|mtd] [--no-open] [--full-paths]";
+
+/**
+ * Assemble the unified insights payload: the graph model and the cost fold the two existing
+ * assemblers already build, plus the per-trigger spend map keyed by graph node id. The spend map is
+ * derived from the SPEND window's records (the operator's question), not the graph's fixed record
+ * window -- the artifact states both windows, and a badge whose window differed from the table
+ * beside it would be the quiet inconsistency this surface exists to kill.
+ */
+async function assembleInsights(paths: any, window: string): Promise<any> {
+  const graph = await assembleGraph(paths);
+  const costs = assembleCosts(paths, window);
+  if (costs?.unreachable) {
+    return { graph, fold: null, costsUnreachable: String(costs.unreachable), window, costByTrigger: null };
+  }
+  const fold = costs?.fold ?? null;
+  // Re-fold the spend map at the requested window so badge and table agree. assembleCosts already
+  // scanned; scanning again here costs one directory pass and keeps the two assemblers untouched.
+  const nowMs = Date.now();
+  const sinceMs = costsSinceMs(window, nowMs);
+  const records = scanRunRecords({ logsDir: paths.logsDir, sinceMs, nowMs });
+  let costByTrigger: any = null;
+  if (Array.isArray(records)) {
+    const triggersView: any = readTriggers({ triggersPath: paths.triggersPath });
+    const subsView: any = readSubscriptions({ subscriptionsPath: paths.subscriptionsPath });
+    const triggerJoin = attributeRunsToTriggers({ records, triggers: Array.isArray(triggersView?.triggers) ? triggersView.triggers : [] });
+    costByTrigger = foldTriggerCosts({ records, subscriptions: Array.isArray(subsView?.subscriptions) ? subsView.subscriptions : [], pricing: PRICING, triggerJoin });
+  }
+  return { graph, fold, costsUnreachable: null, window, costByTrigger };
+}
+
+/**
+ * `/dispatch insights html [7d|30d|mtd] [--no-open] [--full-paths]` (REQ-INSIGHTS-HTML-EXPORT):
+ * graphHtmlCommand's structural twin -- assemble, render the self-contained artifact, write it
+ * ATOMICALLY to the STABLE path `<graphDir>/insights.html`, print the file:// URL FIRST, then
+ * best-effort open unless headless/--no-open. A cost-side degrade (scan unreachable) still writes
+ * the page with its banner: the artifact is total, never a stack trace. Default window 30d, NOT
+ * costs' mtd: the topology half is pinned at a 30d record window, and the one page's two halves
+ * should describe the same period unless the operator asks otherwise. Exported for its tests.
+ */
+export async function insightsHtmlCommand(paths: any, tokens: string[], notify: Notify, deps: any = realGraphHtmlDeps()): Promise<void> {
+  const rest = tokens.slice(2);
+  const noOpen = rest.includes("--no-open");
+  const fullPaths = rest.includes("--full-paths");
+  const positional = rest.filter((t) => t !== "--no-open" && t !== "--full-paths");
+  const window = positional.length > 0 ? positional[0] : "30d";
+  if (positional.length > 1 || !COSTS_WINDOWS.includes(window)) {
+    notify?.(INSIGHTS_USAGE, "warning");
+    return;
+  }
+  const payload = await assembleInsights(paths, window);
+  const html = buildInsightsHtml(payload, { now: deps.now(), fullPaths });
+  const file = `${paths.graphDir}/insights.html`;
+  try {
+    deps.fs.mkdirSync(paths.graphDir, { recursive: true });
+    const tmp = `${file}.tmp`;
+    deps.fs.writeFileSync(tmp, html, { mode: 0o644 });
+    deps.fs.renameSync(tmp, file);
+  } catch (err: any) {
+    notify?.(`insights html: could not write ${file} (${err?.message ?? err})`, "error");
+    return;
+  }
+  const url = pathToFileURL(file).href;
+  notify?.(`insights written: ${url}`, "info");
+  if (noOpen) return;
+  const headless = isHeadlessEnv(deps.env, deps.platform);
+  if (headless) {
+    notify?.(`not opening a browser (${headless}): open the URL on this machine's desktop, or scp the file there`, "info");
+    return;
+  }
+  deps.openBrowser(url);
+}
+
 /**
  * `/dispatch costs [7d|30d|mtd]` renders the fold; `costs whatif …` estimates one flow at another model's
  * rates. Both send PII-free text into the admin channel -- the same records `runs` already sends,
@@ -1742,6 +1830,16 @@ function completeArguments(prefix: string) {
     const items = ["html"].filter((w) => w.startsWith(partial)).map((w) => ({ value: `graph ${w}`, label: w }));
     return items.length > 0 ? items : null;
   }
+  if (parts[0] === "insights" && parts.length === 2) {
+    const partial = parts[1];
+    const items = ["html"].filter((w) => w.startsWith(partial)).map((w) => ({ value: `insights ${w}`, label: w }));
+    return items.length > 0 ? items : null;
+  }
+  if (parts[0] === "insights" && parts[1] === "html" && parts.length === 3) {
+    const partial = parts[2];
+    const items = ["7d", "30d", "mtd"].filter((w) => w.startsWith(partial)).map((w) => ({ value: `insights html ${w}`, label: w }));
+    return items.length > 0 ? items : null;
+  }
   if ((parts[0] === "set" || parts[0] === "unset") && parts.length === 2) {
     const partial = parts[1];
     const items = KNOWN_KEYS.filter((k) => k.startsWith(partial)).map((k) => ({