@intentius/behold 0.4.0 → 0.5.0

package/README.md

@@ -28,6 +28,10 @@ npx @intentius/behold demo            # copies the example to ./behold-demo, ins
 ```
 
 The copied project is yours: edit its source and watch the graph change live.
+There's a whole catalog — `behold demo --list` names the rest (`behold demo
+k8s` stands the same loop up on a throwaway k3d cluster: runtime Pods, field
+ownership). Every loaded demo lands in the panel's recents, so switching
+between them is the Scope tab.
 
 Already have a chant project?
 

package/demos.json

@@ -0,0 +1,30 @@
+{
+  "demos": [
+    {
+      "name": "writes",
+      "description": "One S3 bucket + policy on a local Floci emulator — blue to green in five minutes. The default.",
+      "source": "bundled",
+      "dir": "example-writes",
+      "requires": ["docker"],
+      "serve": { "local": true, "env": "prod" }
+    },
+    {
+      "name": "k8s",
+      "description": "An nginx Deployment + Service on a throwaway k3d cluster — runtime children (Pods), field ownership, honest unobserved. Cluster persists across runs; scripts/local/local-down.sh removes it.",
+      "source": "bundled",
+      "dir": "example-k8s",
+      "requires": ["docker", "k3d", "kubectl"],
+      "setup": "bash scripts/local/local-up.sh",
+      "serve": { "local": true, "env": "local" }
+    },
+    {
+      "name": "fountain",
+      "description": "The mature estate: self-hosted fountain (a real app) on a throwaway k3d cluster — tiers (try the ha tier picker), seams, drift, runtime Pods. Clones INTENTIUS/fountain-ops; ~5 minutes, mostly image pulls. `just down` in the clone removes the cluster.",
+      "source": "git",
+      "repo": "https://github.com/INTENTIUS/fountain-ops",
+      "requires": ["docker", "k3d", "kubectl", "jq", "just"],
+      "setup": "just up",
+      "serve": { "env": "local" }
+    }
+  ]
+}

package/dist/cli.js

@@ -1,7 +1,7 @@
 // src/cli.ts
-import { resolve as resolve3, dirname as dirname5, join as join12, relative as relative2, sep } from "node:path";
+import { resolve as resolve3, dirname as dirname5, join as join13, relative as relative2, sep } from "node:path";
 import { realpathSync, existsSync as existsSync10, cpSync } from "node:fs";
-import { spawnSync } from "node:child_process";
+import { spawnSync as spawnSync2 } from "node:child_process";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 
 // src/server.ts
@@ -3729,17 +3729,19 @@ function safeJson(value) {
   return JSON.stringify(value).replace(/</g, "\\u003c");
 }
 var LANES_CSS = `
-#behold-lanes { position: fixed; left: 0; right: 0; bottom: 0; background: #0d1117;
-  border-top: 1px solid #30363d; padding: 8px 12px 10px; font: 12px ui-sans-serif, system-ui, sans-serif; color: #8b949e; }
+body { background: var(--bg, #0d1117); color: var(--fg, #e6edf3); padding-bottom: 150px; }
+#behold-lanes { position: fixed; left: 0; right: 0; bottom: 0; background: var(--bg, #0d1117);
+  border-top: 1px solid var(--line, #30363d); padding: 8px 12px 10px; font: 12px ui-sans-serif, system-ui, sans-serif; color: var(--muted, #8b949e); }
 #behold-lanes .hd { display: flex; gap: 14px; align-items: baseline; margin-bottom: 4px; }
-#behold-lanes .hd .rt { color: #d29922; }
+#behold-lanes .hd .rt { color: var(--foreign, #d29922); }
+#behold-lanes .hd a { color: var(--pending, #58a6ff); text-decoration: none; margin-left: auto; }
 #behold-lanes canvas { display: block; width: 100%; cursor: pointer; }
 #behold-diff { position: fixed; right: 12px; bottom: 156px; width: 260px; max-height: 40vh; overflow: auto;
-  background: #161b22; border: 1px solid #30363d; border-radius: 6px; padding: 10px 12px; font: 12px ui-sans-serif, system-ui, sans-serif;
-  color: #e6edf3; display: none; }
-#behold-diff h4 { margin: 0 0 6px; font-size: 12px; color: #8b949e; }
-#behold-diff .a { color: #3fb950; } #behold-diff .r { color: #f85149; } #behold-diff .c { color: #d29922; }
-body { padding-bottom: 150px; }`;
+  background: var(--panel, #161b22); border: 1px solid var(--line, #30363d); border-radius: 6px; padding: 10px 12px; font: 12px ui-sans-serif, system-ui, sans-serif;
+  color: var(--fg, #e6edf3); display: none; }
+#behold-diff h4 { margin: 0 0 6px; font-size: 12px; color: var(--muted, #8b949e); }
+#behold-diff .a { color: var(--managed, #3fb950); } #behold-diff .r { color: var(--degraded, #f85149); } #behold-diff .c { color: var(--foreign, #d29922); }`;
+var THEME_BOOT = `<script type="module">import { initTheme, onThemeChange, mountThemePicker } from "/theme.js"; initTheme(); mountThemePicker(document.getElementById("behold-lanes-pickers")); onThemeChange(() => window.dispatchEvent(new Event("behold-theme")));</script>`;
 function laneStripScript(frames) {
   return `<script>
 const LF = ${safeJson(frames)};
@@ -3750,6 +3752,7 @@ const LF = ${safeJson(frames)};
   const rowH = 22, padL = 96, padR = 16, padT = 6;
   const H = padT + subs.length * rowH + 24;
   const t0 = LF[0].t, tN = LF[LF.length - 1].t, span = Math.max(1, tN - t0);
+  const css = (n, fb) => (getComputedStyle(document.documentElement).getPropertyValue(n).trim() || fb);
   const offset = {}; // per-substrate time offset (graph-inert)
   let cur = LF.length - 1, focus = null, pair = null;
 
@@ -3763,7 +3766,7 @@ const LF = ${safeJson(frames)};
     const inNow = now !== undefined, inPrev = prev !== undefined;
     return inNow !== inPrev || (inNow && inPrev && now !== prev);
   }
-  const color = s => s === "good" ? "#3fb950" : s === "warn" ? "#d29922" : s === "accent" ? "#58a6ff" : "#6e7681";
+  const color = s => s === "good" ? css("--managed", "#3fb950") : s === "warn" ? css("--foreign", "#d29922") : s === "accent" ? css("--pending", "#58a6ff") : css("--edge", "#6e7681");
 
   function draw() {
     const dpr = window.devicePixelRatio || 1;
@@ -3772,22 +3775,22 @@ const LF = ${safeJson(frames)};
     c.clearRect(0, 0, host.clientWidth, H); c.font = "12px ui-sans-serif, system-ui, sans-serif";
     subs.forEach((s, r) => {
       const y = padT + r * rowH + rowH / 2;
-      c.fillStyle = offset[s] ? "#d29922" : "#8b949e"; c.textAlign = "left"; c.fillText(s, 8, y + 4);
-      c.strokeStyle = "#21262d"; c.beginPath(); c.moveTo(padL, y); c.lineTo(host.clientWidth - padR, y); c.stroke();
+      c.fillStyle = offset[s] ? css("--foreign", "#d29922") : css("--muted", "#8b949e"); c.textAlign = "left"; c.fillText(s, 8, y + 4);
+      c.strokeStyle = css("--line", "#21262d"); c.beginPath(); c.moveTo(padL, y); c.lineTo(host.clientWidth - padR, y); c.stroke();
       LF.forEach((f, i) => {
         if (!f.byLexicon[s]) return;
         // dot per substrate; brighter when a node in this substrate changed at i
         const changed = Object.keys(f.status).some(id => f.lexicon[id] === s && changedAt(id, i));
         const hi = focus && f.lexicon[focus] === s && changedAt(focus, i);
-        c.fillStyle = hi ? "#f0f6fc" : changed ? color(mode(f, s)) : "#30363d";
+        c.fillStyle = hi ? css("--fg", "#f0f6fc") : changed ? color(mode(f, s)) : css("--line", "#30363d");
         c.beginPath(); c.arc(xOf(i, s), y, i === cur ? 5 : hi ? 4.5 : 3.5, 0, 7); c.fill();
       });
     });
-    const px = baseX(cur); c.strokeStyle = "#58a6ff"; c.lineWidth = 1.5;
+    const px = baseX(cur); c.strokeStyle = css("--pending", "#58a6ff"); c.lineWidth = 1.5;
     c.beginPath(); c.moveTo(px, padT - 2); c.lineTo(px, padT + subs.length * rowH); c.stroke();
-    if (pair != null) { const qx = baseX(pair); c.strokeStyle = "#d29922"; c.setLineDash([3,3]);
+    if (pair != null) { const qx = baseX(pair); c.strokeStyle = css("--foreign", "#d29922"); c.setLineDash([3,3]);
       c.beginPath(); c.moveTo(qx, padT - 2); c.lineTo(qx, padT + subs.length * rowH); c.stroke(); c.setLineDash([]); }
-    c.fillStyle = "#e6edf3"; c.textAlign = "center"; c.fillText(LF[cur].name, px, padT + subs.length * rowH + 16);
+    c.fillStyle = css("--fg", "#e6edf3"); c.textAlign = "center"; c.fillText(LF[cur].name, px, padT + subs.length * rowH + 16);
     document.getElementById("behold-lanes-meta").textContent =
       LF.length + " frames \xB7 frame " + (cur + 1) + "/" + LF.length + (focus ? " \xB7 focus " + focus : "");
     document.getElementById("behold-lanes-rt").style.display = anyOffset() ? "inline" : "none";
@@ -3828,6 +3831,7 @@ const LF = ${safeJson(frames)};
   window.addEventListener("keydown", (e) => { if (e.key === "ArrowLeft") go(cur - 1); if (e.key === "ArrowRight") go(cur + 1);
     if (e.key === "Escape") { focus = null; pair = null; showDiff(); draw(); } });
   window.addEventListener("resize", draw);
+  window.addEventListener("behold-theme", draw); // #198: theme flip repaints the strip
 
   // focus cursor: click a graph node \u2192 highlight where it changed (graph \u2192 lanes)
   function wireNodes() { document.querySelectorAll("[data-node-id]").forEach(el => {
@@ -3853,7 +3857,7 @@ function renderLanes(frames, summaries) {
     status: Object.fromEntries(f.ir.nodes.map((n) => [n.id, n.attrs?._status ?? ""])),
     lexicon: Object.fromEntries(f.ir.nodes.map((n) => [n.id, n.lexicon]))
   }));
-  const strip = `<style>${LANES_CSS}</style><div id="behold-diff"></div><div id="behold-lanes"><div class="hd"><span>deployment lanes</span><span id="behold-lanes-meta"></span><span class="rt" id="behold-lanes-rt" style="display:none">offset \u2014 graph shows real time</span></div><canvas id="behold-lanes-canvas"></canvas></div>` + laneStripScript(laneFrames);
+  const strip = `<style>${LANES_CSS}</style>` + THEME_BOOT + `<div id="behold-diff"></div><div id="behold-lanes"><div class="hd"><span>deployment lanes</span><span id="behold-lanes-meta"></span><span class="rt" id="behold-lanes-rt" style="display:none">offset \u2014 graph shows real time</span><a href="/">\u2190 graph</a><span id="behold-lanes-pickers"></span></div><canvas id="behold-lanes-canvas"></canvas></div>` + laneStripScript(laneFrames);
   return doc.includes("</body>") ? doc.replace("</body>", `${strip}</body>`) : doc + strip;
 }
 
@@ -4009,7 +4013,7 @@ function createApp(cfg, broadcaster = new Broadcaster(), frames = new FrameBuffe
     const all = frames.all();
     if (all.length < 2) {
       return c.html(
-        `<!doctype html><meta charset=utf-8><body style="font:14px system-ui;background:#0d1117;color:#8b949e;padding:2rem"><h3 style="color:#e6edf3">deployment lanes</h3><p>${all.length} frame(s) captured \u2014 need at least two to scrub.</p><p>Frames accrue when the estate moves: hit <b style="color:#e6edf3">\u21BB Refresh</b> (captures the current live state), run a <b style="color:#e6edf3">Sync</b>/Adopt, edit the source, or serve with <code>--poll</code> against a moving environment. Then reload.</p><p><a href="/" style="color:#58a6ff;text-decoration:none">\u2190 back to the graph</a></p></body>`
+        `<!doctype html><meta charset=utf-8><script type="module">import { initTheme } from "/theme.js"; initTheme();</script><body style="font:14px system-ui;background:var(--bg,#0d1117);color:var(--muted,#8b949e);padding:2rem"><h3 style="color:var(--fg,#e6edf3)">deployment lanes</h3><p>${all.length} frame(s) captured \u2014 need at least two to scrub.</p><p>Frames accrue when the estate moves: hit <b style="color:var(--fg,#e6edf3)">\u21BB Refresh</b> (captures the current live state), run a <b style="color:var(--fg,#e6edf3)">Sync</b>/Adopt, edit the source, or serve with <code>--poll</code> against a moving environment. Then reload.</p><p><a href="/" style="color:var(--pending,#58a6ff);text-decoration:none">\u2190 back to the graph</a></p></body>`
       );
     }
     return c.html(renderLanes(all, frames.summaries()));
@@ -4607,6 +4611,9 @@ async function startServer(cfg) {
       );
     }
   }
+  for (const dir of cfg.projectDirs ?? [cfg.projectDir]) {
+    if (existsSync9(join10(dir, "chant.config.ts"))) addRecent(dir);
+  }
   const broadcaster = new Broadcaster();
   const frames = new FrameBuffer();
   const runner = new OpRunner({
@@ -4710,9 +4717,43 @@ async function startServer(cfg) {
   });
 }
 
+// src/demos.ts
+import { readFileSync as readFileSync8 } from "node:fs";
+import { join as join11 } from "node:path";
+import { spawnSync } from "node:child_process";
+function loadDemoRegistry(pkgRoot) {
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync8(join11(pkgRoot, "demos.json"), "utf8"));
+  } catch {
+    return [];
+  }
+  const list = raw?.demos;
+  if (!Array.isArray(list)) return [];
+  return list.filter((e) => {
+    const d = e;
+    if (!d || typeof d.name !== "string" || !d.name || typeof d.description !== "string") return false;
+    if (d.source === "bundled") {
+      if (typeof d.dir !== "string" || !d.dir) return false;
+    } else if (d.source === "git") {
+      if (typeof d.repo !== "string" || !d.repo) return false;
+    } else {
+      return false;
+    }
+    if (!Array.isArray(d.requires) || d.requires.some((r) => typeof r !== "string")) return false;
+    if (!d.serve || typeof d.serve !== "object") return false;
+    return true;
+  });
+}
+function missingRequirements(entry) {
+  const bins = entry.source === "git" && !entry.requires.includes("git") ? [...entry.requires, "git"] : entry.requires;
+  const finder = process.platform === "win32" ? "where" : "which";
+  return bins.filter((bin) => spawnSync(finder, [bin], { stdio: "ignore" }).status !== 0);
+}
+
 // src/export.ts
-import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2, copyFileSync, readFileSync as readFileSync8, readdirSync as readdirSync4 } from "node:fs";
-import { join as join11, dirname as dirname4, basename } from "node:path";
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2, copyFileSync, readFileSync as readFileSync9, readdirSync as readdirSync4 } from "node:fs";
+import { join as join12, dirname as dirname4, basename } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 var LENS_PARAMS = ["components", "detail", "env", "logical", "radial", "tier"];
 function canonicalKey(path, params) {
@@ -4760,7 +4801,7 @@ function captureKeys(axes) {
   return [...keys];
 }
 function webDir() {
-  return join11(dirname4(fileURLToPath2(import.meta.url)), "..", "web");
+  return join12(dirname4(fileURLToPath2(import.meta.url)), "..", "web");
 }
 function workerName(project, override) {
   const raw = override ?? `behold-${basename(project)}`;
@@ -4771,7 +4812,7 @@ async function runExport(cfg, outDir, opts = {}) {
   const app = createApp(cfg);
   const proj = await (await app.request("/api/project")).json();
   const axes = { environments: proj.environments ?? [], tiers: proj.tiers ?? [] };
-  const snapDir = join11(outDir, "snapshots");
+  const snapDir = join12(outDir, "snapshots");
   mkdirSync2(snapDir, { recursive: true });
   const keyToFile = {};
   let ok = 0;
@@ -4780,7 +4821,7 @@ async function runExport(cfg, outDir, opts = {}) {
     const res = await app.request(key);
     const body = await res.text();
     const file = slug(key);
-    writeFileSync2(join11(snapDir, file), body);
+    writeFileSync2(join12(snapDir, file), body);
     keyToFile[key] = `snapshots/${file}`;
     if (res.ok) ok++;
     else failed++;
@@ -4792,21 +4833,21 @@ async function runExport(cfg, outDir, opts = {}) {
     axes,
     keyToFile
   };
-  writeFileSync2(join11(outDir, "manifest.json"), JSON.stringify(manifest, null, 2));
-  const html = readFileSync8(join11(webDir(), "index.html"), "utf8").replace(
+  writeFileSync2(join12(outDir, "manifest.json"), JSON.stringify(manifest, null, 2));
+  const html = readFileSync9(join12(webDir(), "index.html"), "utf8").replace(
     /<\/head>/i,
     `  <script>window.__BEHOLD_STATIC__ = true;</script>
   </head>`
   );
-  writeFileSync2(join11(outDir, "index.html"), html);
+  writeFileSync2(join12(outDir, "index.html"), html);
   for (const f of readdirSync4(webDir())) {
     if (f === "index.html") continue;
-    copyFileSync(join11(webDir(), f), join11(outDir, f));
+    copyFileSync(join12(webDir(), f), join12(outDir, f));
   }
-  writeFileSync2(join11(outDir, "README.md"), BUNDLE_README);
+  writeFileSync2(join12(outDir, "README.md"), BUNDLE_README);
   const name = workerName(cfg.projectDir, opts.name);
   writeFileSync2(
-    join11(outDir, "wrangler.jsonc"),
+    join12(outDir, "wrangler.jsonc"),
     JSON.stringify(
       { $schema: "node_modules/wrangler/config-schema.json", name, compatibility_date: "2025-06-01", assets: { directory: "." } },
       null,
@@ -4857,17 +4898,20 @@ It's just files \u2014 GitHub Pages, S3, nginx, or Cloudflare Pages
 var USAGE = `behold \u2014 a live control plane on chant (read-only core)
 
 Usage:
-  behold demo [target-dir] [--port <n>]
+  behold demo [name] [target-dir] [--port <n>] [--list]
   behold preview [project-dir] [--port <n>] [--emulator]
   behold export [project-dir] [--out <dir>] [--env <name>] [--name <worker>] [--emulator]
   behold serve <project-dir\u2026> [--port <n>] [--env <name>] [--poll <secs>] [--local]
 
-  demo    The five-minute path from npm \u2014 no chant project needed. Copies the
-          bundled example (an S3 bucket + policy) into ./behold-demo (or
-          [target-dir]), installs its dependencies, and serves it against a
-          local emulator: blue = declared, click Deploy, watch it turn green.
-          Needs Docker. The copy is yours \u2014 edit its source and watch the
-          graph change live.
+  demo    The five-minute path from npm \u2014 no chant project needed. A catalog
+          of demo estates (behold demo --list): bundled ones copy out of the
+          package into a directory that's yours to edit; git ones shallow-
+          clone a public estate. Bare \`behold demo\` is the AWS example \u2014 an
+          S3 bucket + policy on a local emulator: blue = declared, click
+          Deploy, watch it turn green. \`behold demo k8s\` stands a workload
+          up on a throwaway k3d cluster instead. Needs Docker (and per-demo
+          tools --list names). Loaded demos land in the panel's recents, so
+          switching between them is the Scope tab.
 
   export  Capture the live estate into a self-contained, interactive STATIC
           bundle (default ./behold-export) \u2014 every env/tier \xD7 zoom \xD7 radial,
@@ -5016,7 +5060,7 @@ ${USAGE}`);
   });
 }
 function warnIfNotChantProject(dir) {
-  if (existsSync10(join12(dir, "chant.config.ts"))) return;
+  if (existsSync10(join13(dir, "chant.config.ts"))) return;
   process.stderr.write(
     `behold: warning \u2014 ${dir} has no chant.config.ts; this doesn't look like a chant project.
         No project yet? \`behold demo\` serves a bundled working example (needs Docker).
@@ -5024,14 +5068,37 @@ function warnIfNotChantProject(dir) {
   );
 }
 async function runDemo(rest) {
+  const pkgRoot = join13(dirname5(fileURLToPath3(import.meta.url)), "..");
+  const registry = loadDemoRegistry(pkgRoot);
   let port = 4600;
+  let name;
   let dirArg;
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
     if (a === "--port") port = Number(rest[++i]);
-    else if (a === "-h" || a === "--help") return void process.stdout.write(USAGE);
-    else if (!a.startsWith("-")) dirArg = a;
-    else {
+    else if (a === "--list") {
+      if (!registry.length) {
+        process.stdout.write("behold demo: no catalog in this install (demos.json missing)\n");
+        return;
+      }
+      for (const e of registry) {
+        const missing2 = missingRequirements(e);
+        const ready = missing2.length ? `needs ${missing2.join(", ")}` : "ready";
+        process.stdout.write(`  ${e.name.padEnd(14)} ${ready.padEnd(20)} ${e.description}
+`);
+      }
+      process.stdout.write("\nRun one: behold demo <name>   (bare `behold demo` = writes)\n");
+      return;
+    } else if (a === "-h" || a === "--help") return void process.stdout.write(USAGE);
+    else if (!a.startsWith("-")) {
+      if (!name && registry.some((e) => e.name === a)) name = a;
+      else if (!dirArg) dirArg = a;
+      else {
+        process.stderr.write(`behold demo: unexpected argument '${a}'
+`);
+        process.exit(2);
+      }
+    } else {
       process.stderr.write(`behold demo: unexpected argument '${a}'
 `);
       process.exit(2);
@@ -5041,34 +5108,75 @@ async function runDemo(rest) {
     process.stderr.write("behold demo: --port must be a number\n");
     process.exit(2);
   }
-  const bundled = join12(dirname5(fileURLToPath3(import.meta.url)), "..", "example-writes");
-  if (!existsSync10(bundled)) {
-    process.stderr.write("behold demo: this install has no bundled example project (example-writes)\n");
+  const entry = registry.find((e) => e.name === (name ?? "writes"));
+  if (!entry) {
+    process.stderr.write(`behold demo: no "${name ?? "writes"}" in this install's catalog \u2014 behold demo --list
+`);
+    process.exit(2);
+  }
+  const missing = missingRequirements(entry);
+  if (missing.length) {
+    process.stderr.write(`behold demo ${entry.name}: missing ${missing.join(", ")} \u2014 install and re-run.
+`);
     process.exit(2);
   }
-  const target = resolve3(dirArg ?? "behold-demo");
+  const target = resolve3(
+    dirArg ?? (entry.name === "writes" && existsSync10("behold-demo") ? "behold-demo" : join13("behold-demos", entry.name))
+  );
   if (!existsSync10(target)) {
-    process.stdout.write(`behold demo \u2192 copying the example project to ${target} (it's yours \u2014 edit it)
+    if (entry.source === "bundled") {
+      const bundled = join13(pkgRoot, entry.dir);
+      if (!existsSync10(bundled)) {
+        process.stderr.write(`behold demo ${entry.name}: this install has no bundled ${entry.dir}
 `);
-    cpSync(bundled, target, {
-      recursive: true,
-      filter: (src) => !relative2(bundled, src).split(sep).includes("node_modules")
-    });
+        process.exit(2);
+      }
+      process.stdout.write(`behold demo ${entry.name} \u2192 copying to ${target} (it's yours \u2014 edit it)
+`);
+      cpSync(bundled, target, {
+        recursive: true,
+        filter: (src) => !relative2(bundled, src).split(sep).includes("node_modules")
+      });
+    } else {
+      process.stdout.write(`behold demo ${entry.name} \u2192 cloning ${entry.repo} to ${target}
+`);
+      const r = spawnSync2("git", ["clone", "--depth", "1", entry.repo, target], { stdio: "inherit" });
+      if (r.status !== 0) {
+        process.stderr.write(`behold demo ${entry.name}: clone failed
+`);
+        process.exit(r.status ?? 1);
+      }
+    }
   } else {
-    process.stdout.write(`behold demo \u2192 reusing ${target}
+    process.stdout.write(`behold demo ${entry.name} \u2192 reusing ${target}
 `);
   }
-  if (!existsSync10(join12(target, "node_modules"))) {
-    process.stdout.write("behold demo \u2192 npm install (the example's own chant + lexicons)\u2026\n");
-    const r = spawnSync("npm", ["install"], { cwd: target, stdio: "inherit", shell: process.platform === "win32" });
+  if (existsSync10(join13(target, "package.json")) && !existsSync10(join13(target, "node_modules"))) {
+    process.stdout.write(`behold demo ${entry.name} \u2192 npm install\u2026
+`);
+    const r = spawnSync2("npm", ["install"], { cwd: target, stdio: "inherit", shell: process.platform === "win32" });
     if (r.status !== 0) {
       process.stderr.write(`behold demo: npm install failed in ${target}${r.error ? ` (${r.error.message})` : ""}
 `);
       process.exit(r.status ?? 1);
     }
   }
-  process.stdout.write("behold demo \u2192 serving with a local emulator (Docker). Blue = declared; Deploy turns it green.\n");
-  await run3(["serve", target, "--local", "--env", "prod", "--port", String(port)]);
+  if (entry.setup) {
+    process.stdout.write(`behold demo ${entry.name} \u2192 ${entry.setup}
+`);
+    const r = spawnSync2(entry.setup, { cwd: target, stdio: "inherit", shell: true });
+    if (r.status !== 0) {
+      process.stderr.write(`behold demo ${entry.name}: setup failed (${entry.setup})
+`);
+      process.exit(r.status ?? 1);
+    }
+  }
+  process.stdout.write(`behold demo ${entry.name} \u2192 serving. Blue = declared; Deploy turns it green.
+`);
+  const serveArgs = ["serve", target, "--port", String(port)];
+  if (entry.serve.local) serveArgs.push("--local");
+  if (entry.serve.env) serveArgs.push("--env", entry.serve.env);
+  await run3(serveArgs);
 }
 function injectEmulatorEnv(env) {
   process.env.LOOM_ENV ??= env ?? "local";

package/example-k8s/README.md

@@ -0,0 +1,120 @@
+# The k3d turnkey demo — behold's Kubernetes counterpart to Loom-on-Floci
+
+The smallest real thing on Kubernetes: one `nginx` Deployment + Service (+ a
+PodDisruptionBudget), deployed from the browser with the **▶ Deploy
+(k3d-apply)** header button, against a local, single-node
+[k3d](https://k3d.io) cluster — no cloud account, no credentials.
+
+```
+src/config.ts        static config — app name, pinned image tag
+src/web.ts            WebApp composite → Deployment + Service + PodDisruptionBudget
+ops/k3d-apply.op.ts   ApplyOp "k3d-apply" — code → local k3d, server-side apply
+chant.config.ts       lexicons [k8s, temporal], k8s.profiles.local bound to k3d-behold-k3d-demo
+scripts/local/        local-up.sh / local-down.sh — the k3d cluster's own lifecycle
+```
+
+## Run it
+
+From the **behold** repo root:
+
+```sh
+npm run demo:k8s
+#   → brings up a single-node k3d cluster ("behold-k3d-demo"),
+#     then serves this project at http://localhost:4600
+```
+
+That one command does two things: `scripts/local/local-up.sh` creates the
+cluster (idempotent — reuses one already up), then `behold serve --local`
+points its live overlay at it. `--local`'s usual boot step (`chant emulator
+up`) is a no-op here — chant's k8s lexicon has no local-emulator capability
+the way Floci does for aws — so the cluster comes up via the same generic
+substrate **Bring up** mechanism the Floci demo's `scripts/local/local-up.sh`
+convention already uses (see `src/substrates.ts`), just run up front instead
+of from a click. Ctrl-C stops `behold serve` and tears the cluster back down;
+Docker or k3d missing degrades to the source graph with a clear message
+instead of crashing.
+
+1. Open **http://localhost:4600**. The graph shows the Deployment, Service and
+   PodDisruptionBudget — **blue** (declared, not yet deployed).
+2. Click **▶ Deploy (k3d-apply)** in the header (or ⌘K → "Deploy: Sync"). The
+   now-line streams Build → Plan (a live
+   diff) → Apply: a Kubernetes **server-side apply**, field manager
+   `chant:behold-k3d-demo` (chant#1074/#1075) — deletes are **owned-only**, a
+   marker-scoped prune that only ever touches what chant itself applied.
+3. The three nodes flip **blue → green (managed)**. Zoom in on the Deployment
+   and its two Pods appear **nested underneath it** — the runtime tier
+   (chant#1077/behold#86): live children a Deployment's controller created,
+   never declared here, never classified as drift or an orphan.
+
+## The four things this proves live (epic #84)
+
+behold's k8s parity (#85–#87) shipped against fixtures; this is it against a
+real cluster.
+
+**Declared, not yet deployed.** Before step 2, `/api/overlay` reports all
+three nodes `_status: accent` (pending) — chant knows about them, the cluster
+doesn't yet.
+
+**Runtime children.** After apply, `/api/overlay`'s `ir.groups.byContainer`
+nests the Deployment's Pods under it, each `_status: runtime` — a tier below
+what's declared, sourced from the cluster's own `ownerReferences`, that
+behold's zoom dial can descend into.
+
+**Managed-fields drift.** Scale or label the Deployment out of band —
+`kubectl scale deployment/web --replicas=3`, bypassing chant entirely — and
+`/api/diff`'s `fieldDrift` reports `spec.replicas: { kind: "changed", declared:
+2, live: 3 }`: chant's own SSA-tracked field, now diverged from a competing
+field manager (`kubectl`, visible in `kubectl get deploy/web -o json`'s
+`metadata.managedFields`). Re-running `k3d-apply` at that point doesn't
+silently overwrite it: chant's server-side apply refuses —
+
+```
+k8s: server-side apply of apps/v1 Deployment web was refused — 1 field is owned by another field manager.
+
+  "kubectl" owns:
+    .spec.replicas
+
+chant applied as field manager "chant:behold-k3d-demo". Taking these fields means the managers above
+stop owning them, and will contest them again on their next apply.
+```
+
+— naming the contested path and the competing manager, and leaving the field
+alone rather than force-resolving it. (One honest gap found running this
+live: a **new** out-of-band key with no chant-declared counterpart at all —
+`kubectl label deployment/web team=platform`, which has no corresponding
+`web.spec` field in `src/web.ts` — doesn't currently surface in `fieldDrift`,
+only a value change to a field chant *does* declare does. Worth a follow-up
+issue on the chant side; noted here rather than papered over.)
+
+**Unobserved.** `chant.config.ts` binds environment `local` to kubectl context
+`k3d-behold-k3d-demo` (chant#1100) — every read/apply checks that binding
+against whatever context is actually ambient, and refuses rather than reading
+the wrong cluster. Switch away from it for a moment —
+
+```sh
+kubectl config use-context <anything-else>
+```
+
+— and `/api/overlay` flips every node to `_status: neutral` with
+`unobservedReason: "read-failed"`, Pods and all: an honest "did not look",
+never a false "these are all gone." Switch back
+(`kubectl config use-context k3d-behold-k3d-demo`) and the next refresh
+recovers cleanly.
+
+## Cleanup
+
+`Ctrl-C` on `npm run demo:k8s` runs `scripts/local/local-down.sh`
+automatically: deletes the `behold-k3d-demo` cluster and restores whatever
+kubectl context was current before `local-up.sh` ran. Safe to run by hand too:
+
+```sh
+bash scripts/local/local-down.sh
+```
+
+## Note for chant#1179
+
+This Op's `delete: "owned-only"` exercises the same typed, marker-scoped
+prune path chant#1179 wants a live k3d E2E for. This demo isn't that test —
+it's a manual walkthrough, not an automated assertion of "exactly the orphan
+and nothing else was deleted" — but it does confirm the path runs against a
+real cluster, not just `fakeCluster`.

package/example-k8s/chant.config.ts

@@ -0,0 +1,21 @@
+import type { ChantConfig } from "@intentius/chant";
+import type { K8sChantConfig } from "@intentius/chant-lexicon-k8s";
+
+// Bound to the demo's own cluster (scripts/local/local-up.sh creates it, k3d
+// names the context "k3d-behold-k3d-demo") rather than whatever kubectl
+// context happens to be ambient — chant#1100. A declared binding is checked
+// against the ambient context on every live read/apply; a mismatch refuses
+// loudly instead of silently reading the wrong cluster. The walkthrough's
+// "unobserved" step (README.md) is exactly that refusal, produced on purpose
+// by switching away from this context for a moment.
+export default {
+  lexicons: ["k8s", "temporal"],
+  sourceDir: "src",
+  environments: ["local"],
+  ownership: { stack: "behold-k3d-demo", env: "local" },
+  k8s: {
+    profiles: {
+      local: { context: "k3d-behold-k3d-demo" },
+    },
+  } satisfies K8sChantConfig,
+} satisfies ChantConfig;

package/example-k8s/ops/k3d-apply.op.ts

@@ -0,0 +1,18 @@
+import { ApplyOp } from "@intentius/chant-lexicon-temporal";
+
+// code → local k3d (chant#704), no cloud account. scripts/local/local-up.sh
+// (run by `npm run demo:k8s` before behold starts serving) brings the cluster
+// up; behold's Run button on this Op deploys the declared app to it —
+// build → plan (live diff) → server-side apply, field manager
+// "chant:behold-k3d-demo" (chant#1074/#1075). Deletes are owned-only: a
+// marker-scoped prune that never touches anything chant didn't declare — the
+// same path chant#1179 wants a live E2E for; this Op exercises it, but isn't
+// that test.
+const { op } = ApplyOp({
+  name: "k3d-apply",
+  env: "local",
+  target: "kubectl",
+  output: "app.yaml",
+  delete: "owned-only",
+});
+export default op;