@intentius/behold 0.2.3 → 0.3.0

package/dist/cli.js

@@ -1,6 +1,7 @@
 // src/cli.ts
-import { resolve as resolve2 } from "node:path";
-import { realpathSync, existsSync as existsSync9 } from "node:fs";
+import { resolve as resolve3, dirname as dirname5, join as join12, relative as relative2, sep } from "node:path";
+import { realpathSync, existsSync as existsSync10, cpSync } from "node:fs";
+import { spawnSync } from "node:child_process";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 
 // src/server.ts
@@ -89,25 +90,55 @@ import { serve } from "@hono/node-server";
 import { fileURLToPath } from "node:url";
 import { execFile as execFile4 } from "node:child_process";
 import { promisify as promisify4 } from "node:util";
-import { existsSync as existsSync8 } from "node:fs";
-import { dirname as dirname2, join as join9, relative } from "node:path";
+import { existsSync as existsSync9, readFileSync as readFileSync7 } from "node:fs";
+import { dirname as dirname3, join as join10, relative, resolve as resolve2 } from "node:path";
+
+// src/recents.ts
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+var MAX_RECENTS = 20;
+function recentsFile() {
+  return process.env.BEHOLD_RECENTS_FILE || join(homedir(), ".behold", "recents.json");
+}
+function listRecents() {
+  try {
+    const rows = JSON.parse(readFileSync(recentsFile(), "utf8"));
+    if (!Array.isArray(rows)) return [];
+    return rows.filter(
+      (r) => !!r && typeof r.dir === "string" && existsSync(join(r.dir, "chant.config.ts"))
+    );
+  } catch {
+    return [];
+  }
+}
+function addRecent(dir, now = () => (/* @__PURE__ */ new Date()).toISOString()) {
+  const rows = listRecents().filter((r) => r.dir !== dir);
+  rows.unshift({ dir, lastOpened: now() });
+  const file = recentsFile();
+  try {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(rows.slice(0, MAX_RECENTS), null, 2) + "\n");
+  } catch {
+  }
+}
 
 // src/chant.ts
 import { spawn } from "node:child_process";
-import { existsSync as existsSync2 } from "node:fs";
+import { existsSync as existsSync3 } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname, join as join2, resolve } from "node:path";
+import { dirname as dirname2, join as join3, resolve } from "node:path";
 
 // src/project.ts
-import { readFileSync, existsSync } from "node:fs";
-import { join } from "node:path";
+import { readFileSync as readFileSync2, existsSync as existsSync2 } from "node:fs";
+import { join as join2 } from "node:path";
 import { pathToFileURL } from "node:url";
 var CONFIG_NAMES = ["chant.config.ts", "chant.config.mts", "chant.config.js", "chant.config.mjs"];
 var BEHOLD_CONFIG_NAME = ".behold.json";
 function configPath(projectDir) {
   for (const name of CONFIG_NAMES) {
-    const p = join(projectDir, name);
-    if (existsSync(p)) return p;
+    const p = join2(projectDir, name);
+    if (existsSync2(p)) return p;
   }
   return void 0;
 }
@@ -169,7 +200,7 @@ async function detectProject(projectDir) {
     if (info.environments.length || info.lexicons.length || info.sourceDir || info.stacks?.length) return info;
   } catch {
   }
-  const content = readFileSync(path, "utf8");
+  const content = readFileSync2(path, "utf8");
   const sourceDir = parseStringLiteral(content, "sourceDir");
   return {
     environments: parseEnvironmentNames(content),
@@ -185,10 +216,10 @@ function readTiers(cfg) {
   return { envVar: tiers.envVar, values };
 }
 function loadBeholdConfig(projectDir) {
-  const path = join(projectDir, BEHOLD_CONFIG_NAME);
-  if (!existsSync(path)) return {};
+  const path = join2(projectDir, BEHOLD_CONFIG_NAME);
+  if (!existsSync2(path)) return {};
   try {
-    const raw = JSON.parse(readFileSync(path, "utf8"));
+    const raw = JSON.parse(readFileSync2(path, "utf8"));
     const tiers = readTiers(raw);
     return tiers ? { tiers } : {};
   } catch {
@@ -489,15 +520,15 @@ function chantBinFrom(req) {
   } catch {
     return void 0;
   }
-  let dir = dirname(entry);
+  let dir = dirname2(entry);
   for (; ; ) {
-    const manifest = join2(dir, "package.json");
+    const manifest = join3(dir, "package.json");
     try {
       const pkg = createRequire(import.meta.url)(manifest);
-      if (pkg.name === "@intentius/chant") return join2(dir, pkg.bin?.chant ?? "bin/chant");
+      if (pkg.name === "@intentius/chant") return join3(dir, pkg.bin?.chant ?? "bin/chant");
     } catch {
     }
-    const parent = dirname(dir);
+    const parent = dirname2(dir);
     if (parent === dir) break;
     dir = parent;
   }
@@ -505,7 +536,7 @@ function chantBinFrom(req) {
 }
 function chantBin(projectDir) {
   if (projectDir) {
-    const fromProject = chantBinFrom(createRequire(join2(resolve(projectDir), "noop.js")));
+    const fromProject = chantBinFrom(createRequire(join3(resolve(projectDir), "noop.js")));
     if (fromProject) return fromProject;
   }
   const own = chantBinFrom(createRequire(import.meta.url));
@@ -597,8 +628,8 @@ function runCommandStream(cmd, args, cwd, onLine) {
   return { pid: proc.pid ?? -1, kill: () => proc.kill(), done };
 }
 function legacyGraphPath(projectDir) {
-  const src = join2(projectDir, "src");
-  return existsSync2(src) ? src : projectDir;
+  const src = join3(projectDir, "src");
+  return existsSync3(src) ? src : projectDir;
 }
 async function graphPath(projectDir, opts = {}) {
   let info;
@@ -622,7 +653,7 @@ async function graphIr(projectDir, opts = {}) {
   return runChantJson(graphArgs(src, "ir", opts, false), projectDir, envOverridesFor(opts));
 }
 async function clusterRootGraphIr(projectDir, opts = {}) {
-  if (!existsSync2(join2(projectDir, "cluster"))) return void 0;
+  if (!existsSync3(join3(projectDir, "cluster"))) return void 0;
   const { live: _live, overlay: _overlay, env: _env, ...sourceOnly } = opts;
   try {
     return await runChantJson(graphArgs("cluster", "ir", sourceOnly, false), projectDir, envOverridesFor(sourceOnly));
@@ -735,8 +766,8 @@ function mergeClusterRoot(ir, clusterIr, running) {
 }
 
 // src/helm-releases.ts
-import { existsSync as existsSync3, readdirSync, readFileSync as readFileSync2, statSync } from "node:fs";
-import { join as join3 } from "node:path";
+import { existsSync as existsSync4, readdirSync, readFileSync as readFileSync3, statSync } from "node:fs";
+import { join as join4 } from "node:path";
 var RELEASE_KEY = /^release\/([^/]+)\/(.+)$/;
 function declaredChartNames(ir) {
   const names = /* @__PURE__ */ new Set();
@@ -756,12 +787,12 @@ function matchesDeclaredChart(chart, declared) {
 }
 function discoverReleaseUnits(projectDir) {
   const owners = /* @__PURE__ */ new Map();
-  const roots = [join3(projectDir, "src"), join3(projectDir, "ops")];
+  const roots = [join4(projectDir, "src"), join4(projectDir, "ops")];
   const files = [];
   const walk = (dir, depth) => {
-    if (depth > 4 || !existsSync3(dir)) return;
+    if (depth > 4 || !existsSync4(dir)) return;
     for (const f of readdirSync(dir)) {
-      const p = join3(dir, f);
+      const p = join4(dir, f);
       let s;
       try {
         s = statSync(p);
@@ -776,7 +807,7 @@ function discoverReleaseUnits(projectDir) {
   for (const file of files) {
     let content;
     try {
-      content = readFileSync2(file, "utf8");
+      content = readFileSync3(file, "utf8");
     } catch {
       continue;
     }
@@ -829,8 +860,8 @@ function synthesizeHelmReleases(ir, observed, owners) {
 
 // src/gh-run.ts
 import { spawn as spawn2 } from "node:child_process";
-import { readdirSync as readdirSync2, readFileSync as readFileSync3 } from "node:fs";
-import { join as join4 } from "node:path";
+import { readdirSync as readdirSync2, readFileSync as readFileSync4 } from "node:fs";
+import { join as join5 } from "node:path";
 
 // src/ci-run.ts
 function pipelineProgress(pipeline) {
@@ -884,19 +915,19 @@ function finishPipelineProgress(state, exitCode) {
 }
 
 // src/gh-run.ts
-var defaultGhExec = (args) => new Promise((resolve3) => {
+var defaultGhExec = (args) => new Promise((resolve4) => {
   let out = "";
   let proc;
   try {
     proc = spawn2("gh", args, { stdio: ["ignore", "pipe", "pipe"] });
   } catch {
-    resolve3({ code: 127, out: "" });
+    resolve4({ code: 127, out: "" });
     return;
   }
   proc.stdout.on("data", (d) => out += d);
   proc.stderr.on("data", (d) => out += d);
-  proc.on("error", () => resolve3({ code: 127, out }));
-  proc.on("close", (code) => resolve3({ code: code ?? 1, out }));
+  proc.on("error", () => resolve4({ code: 127, out }));
+  proc.on("close", (code) => resolve4({ code: code ?? 1, out }));
 });
 async function ghReady(exec = defaultGhExec) {
   const { code, out } = await exec(["auth", "status"]);
@@ -918,7 +949,7 @@ function parseWorkflow(file, text) {
   return { file, jobIds: jobs, dispatchable };
 }
 function pickWorkflow(projectDir, pipeline) {
-  const dir = join4(projectDir, ".github", "workflows");
+  const dir = join5(projectDir, ".github", "workflows");
   let files;
   try {
     files = readdirSync2(dir).filter((f) => f.endsWith(".yml") || f.endsWith(".yaml"));
@@ -930,7 +961,7 @@ function pickWorkflow(projectDir, pipeline) {
   for (const f of files) {
     let text;
     try {
-      text = readFileSync3(join4(dir, f), "utf8");
+      text = readFileSync4(join5(dir, f), "utf8");
     } catch {
       continue;
     }
@@ -1904,8 +1935,8 @@ function projectHelmLogical(ir) {
 }
 
 // src/logical-kustomize.ts
-import { existsSync as existsSync4 } from "node:fs";
-import { join as join5 } from "node:path";
+import { existsSync as existsSync5 } from "node:fs";
+import { join as join6 } from "node:path";
 function overlayBoxTitle(name) {
   return `overlay ${name}`;
 }
@@ -1919,7 +1950,7 @@ function kustomizationRoot(bases, dir, exists) {
   let current = dir;
   for (let i = 0; i < 4 && current; i++) {
     for (const base of bases) {
-      if (exists(join5(base, current, "kustomization.yaml")) || exists(join5(base, current, "kustomization.yml"))) {
+      if (exists(join6(base, current, "kustomization.yaml")) || exists(join6(base, current, "kustomization.yml"))) {
         return current;
       }
     }
@@ -1928,7 +1959,7 @@ function kustomizationRoot(bases, dir, exists) {
   }
   return void 0;
 }
-function projectKustomizeLogical(ir, sourceRoots, exists = existsSync4) {
+function projectKustomizeLogical(ir, sourceRoots, exists = existsSync5) {
   const bases = Array.isArray(sourceRoots) ? sourceRoots : [sourceRoots];
   const k8s = ir.nodes.filter((n) => n.lexicon === "k8s");
   if (k8s.length === 0) return { ir: { nodes: [], edges: [], groups: {} }, byContainer: {} };
@@ -2821,8 +2852,8 @@ function radializeLayout(layout, groupOf, size = /* @__PURE__ */ new Map()) {
 }
 
 // src/ops.ts
-import { readdirSync as readdirSync3, readFileSync as readFileSync4, existsSync as existsSync5 } from "node:fs";
-import { join as join6 } from "node:path";
+import { readdirSync as readdirSync3, readFileSync as readFileSync5, existsSync as existsSync6 } from "node:fs";
+import { join as join7 } from "node:path";
 var APPLY_TARGET_LEXICON = {
   cloudformation: "aws",
   kubectl: "k8s",
@@ -2844,11 +2875,11 @@ function discoverOps(projectDir) {
   const seen = /* @__PURE__ */ new Set();
   const out = [];
   for (const sub of ["ops", "src", "."]) {
-    const dir = join6(projectDir, sub);
-    if (!existsSync5(dir)) continue;
+    const dir = join7(projectDir, sub);
+    if (!existsSync6(dir)) continue;
     for (const f of readdirSync3(dir)) {
       if (!f.endsWith(".op.ts")) continue;
-      const content = readFileSync4(join6(dir, f), "utf8");
+      const content = readFileSync5(join7(dir, f), "utf8");
       const name = content.match(/name:\s*["'`]([^"'`]+)["'`]/)?.[1];
       if (!name || seen.has(name)) continue;
       seen.add(name);
@@ -3069,6 +3100,11 @@ var OpRunner = class {
    * before the first event lands so a reload between trigger and first event
    * doesn't show the PREVIOUS run's stale terminal state). */
   lastApplyProgress = initialApplyProgress;
+  /** #195: re-point delegated writes at a switched project. The runner reads
+   * `deps.projectDir` at trigger time, so this is the whole retarget. */
+  retarget(projectDir) {
+    this.deps.projectDir = projectDir;
+  }
   /** Name of the running op, or null. */
   get running() {
     return this.current;
@@ -3239,23 +3275,23 @@ var OpRunner = class {
 
 // src/substrates.ts
 import { spawn as spawn3 } from "node:child_process";
-import { existsSync as existsSync6, readFileSync as readFileSync5 } from "node:fs";
-import { join as join7 } from "node:path";
+import { existsSync as existsSync7, readFileSync as readFileSync6 } from "node:fs";
+import { join as join8 } from "node:path";
 import { platform } from "node:os";
 function probe(cmd, args) {
-  return new Promise((resolve3) => {
+  return new Promise((resolve4) => {
     let out = "";
     let proc;
     try {
       proc = spawn3(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
     } catch {
-      resolve3({ code: 127, out: "" });
+      resolve4({ code: 127, out: "" });
       return;
     }
     proc.stdout.on("data", (d) => out += d);
     proc.stderr.on("data", (d) => out += d);
-    proc.on("error", () => resolve3({ code: 127, out }));
-    proc.on("close", (code) => resolve3({ code: code ?? 1, out }));
+    proc.on("error", () => resolve4({ code: 127, out }));
+    proc.on("close", (code) => resolve4({ code: code ?? 1, out }));
   });
 }
 async function dockerAvailable() {
@@ -3268,11 +3304,11 @@ async function dockerRunning(nameFilter) {
   return out.split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
 }
 function scriptBringUp(projectDir, relPath, label) {
-  return existsSync6(join7(projectDir, relPath)) ? { label, cmd: "bash", args: [relPath] } : void 0;
+  return existsSync7(join8(projectDir, relPath)) ? { label, cmd: "bash", args: [relPath] } : void 0;
 }
 function projectLexicons(projectDir) {
   try {
-    const src = readFileSync5(join7(projectDir, "chant.config.ts"), "utf-8");
+    const src = readFileSync6(join8(projectDir, "chant.config.ts"), "utf-8");
     const m = src.match(/lexicons\s*:\s*\[([^\]]*)\]/);
     if (!m) return [];
     return [...m[1].matchAll(/["']([^"']+)["']/g)].map((x) => x[1]);
@@ -3322,7 +3358,7 @@ async function detectSubstrates(projectDir, preview = false, boundContext) {
     ["forgejo", "Forgejo", ".forgejo", "test/forgejo-runtime-e2e.sh"]
   ];
   for (const [name, label, marker, script] of forges) {
-    if (!existsSync6(join7(projectDir, marker))) continue;
+    if (!existsSync7(join8(projectDir, marker))) continue;
     const c = docker ? await dockerRunning(name) : [];
     const d = dep(c.length > 0, "container up", "on-demand (pipeline run)");
     subs.push({
@@ -3352,7 +3388,7 @@ async function detectSubstrates(projectDir, preview = false, boundContext) {
       detail: endpoint ? `targeting ${endpoint}` : "real Fly (FLY_FLAPS_BASE_URL unset)"
     });
   }
-  if (existsSync6(join7(projectDir, ".github", "workflows"))) {
+  if (existsSync7(join8(projectDir, ".github", "workflows"))) {
     const gh = await probe("gh", ["auth", "status"]);
     const ready = gh.code === 0;
     subs.push({
@@ -3365,7 +3401,7 @@ async function detectSubstrates(projectDir, preview = false, boundContext) {
   if (lexicons.includes("temporal")) {
     let hasProfiles = false;
     try {
-      hasProfiles = /temporal\s*:\s*\{[\s\S]{0,400}?profiles\s*:/.test(readFileSync5(join7(projectDir, "chant.config.ts"), "utf-8"));
+      hasProfiles = /temporal\s*:\s*\{[\s\S]{0,400}?profiles\s*:/.test(readFileSync6(join8(projectDir, "chant.config.ts"), "utf-8"));
     } catch {
     }
     subs.push({
@@ -3479,8 +3515,8 @@ async function composeEstate(projectDirs, opts = {}) {
 }
 
 // src/events.ts
-import { watch, existsSync as existsSync7 } from "node:fs";
-import { join as join8 } from "node:path";
+import { watch, existsSync as existsSync8 } from "node:fs";
+import { join as join9 } from "node:path";
 var Broadcaster = class {
   listeners = /* @__PURE__ */ new Set();
   subscribe(fn) {
@@ -3498,7 +3534,7 @@ var Broadcaster = class {
 };
 var IGNORE = /(^|[\\/])(node_modules|dist|\.git)([\\/]|$)/;
 function watchSource(projectDir, onChange, debounceMs = 200) {
-  const dir = existsSync7(join8(projectDir, "src")) ? join8(projectDir, "src") : projectDir;
+  const dir = existsSync8(join9(projectDir, "src")) ? join9(projectDir, "src") : projectDir;
   let timer;
   const watcher = watch(dir, { recursive: true }, (_event, file) => {
     const name = typeof file === "string" ? file : "";
@@ -3770,7 +3806,7 @@ async function emulatorDown(projectDir) {
 }
 
 // src/server.ts
-var webRoot = join9(dirname2(fileURLToPath(import.meta.url)), "..", "web");
+var webRoot = join10(dirname3(fileURLToPath(import.meta.url)), "..", "web");
 var execFileP = async (cmd, args) => (await promisify4(execFile4)(cmd, args, { encoding: "utf8", timeout: 1e4 })).stdout;
 function optsFromQuery(url, tierEnvVar, projectDir) {
   const q = url.searchParams;
@@ -3817,6 +3853,21 @@ function tierFailure(tier, message) {
     remedy: `A non-default tier (e.g. a production-only one) can need parameters \u2014 real credentials, a different target \u2014 this environment doesn't have. Pick a different tier to see its graph.`
   };
 }
+function beholdVersion() {
+  try {
+    const here = dirname3(fileURLToPath(import.meta.url));
+    return JSON.parse(readFileSync7(join10(here, "..", "package.json"), "utf8")).version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+function noProjectError(projectDir) {
+  return {
+    code: "no-project",
+    error: `${projectDir} doesn't look like a chant project \u2014 no chant.config.ts here, and the graph came back empty.`,
+    remedy: "Run behold from inside a chant project (or pass its path: behold preview <dir>). No project yet? `behold demo` serves a bundled working example against a local emulator (needs Docker)."
+  };
+}
 function errorResponse(c, opts, err) {
   const message = err instanceof Error ? err.message : String(err);
   const failure = err instanceof ChantCliError ? err.failure : classifyChantFailure(message);
@@ -3855,8 +3906,8 @@ function createApp(cfg, broadcaster = new Broadcaster(), frames = new FrameBuffe
   onDone: (opEnv) => captureFrame(cfg.projectDir, opEnv ?? cfg.env, frames, broadcaster)
 })) {
   const app = new Hono();
-  const beholdConfig = loadBeholdConfig(cfg.projectDir);
-  const tierEnvVar = beholdConfig.tiers?.envVar;
+  let beholdConfig = loadBeholdConfig(cfg.projectDir);
+  let tierEnvVar = beholdConfig.tiers?.envVar;
   const boundK8sContext = async (env) => {
     try {
       const { lexicons, k8sProfiles } = await detectProject(cfg.projectDir);
@@ -3938,9 +3989,9 @@ function createApp(cfg, broadcaster = new Broadcaster(), frames = new FrameBuffe
     return c.json({ started: true, name, ran: label });
   });
   app.post("/api/local/reset", (c) => {
-    const down = join9(cfg.projectDir, "scripts/local/local-down.sh");
-    const up = join9(cfg.projectDir, "scripts/local/local-up.sh");
-    if (!existsSync8(down) || !existsSync8(up)) {
+    const down = join10(cfg.projectDir, "scripts/local/local-down.sh");
+    const up = join10(cfg.projectDir, "scripts/local/local-up.sh");
+    if (!existsSync9(down) || !existsSync9(up)) {
       return c.json({ error: "no local-down.sh / local-up.sh in scripts/local \u2014 reset is only for local emulator projects" }, 400);
     }
     if (!runner.bringUp("reset local emulator", "bash", ["-c", "bash scripts/local/local-down.sh && bash scripts/local/local-up.sh"], cfg.projectDir)) {
@@ -3976,6 +4027,12 @@ function createApp(cfg, broadcaster = new Broadcaster(), frames = new FrameBuffe
     const axes = deployAxes(tierEnvVar, lexicons, k8sTarget);
     return c.json({
       projectDir: cfg.projectDir,
+      // #195: the full estate composition (multi-project serves) and the
+      // switcher's recents, so the SPA's project section can show what's
+      // loaded and offer where to go. Recents exclude nothing here — the SPA
+      // filters out the currently-loaded dir itself.
+      ...cfg.projectDirs && cfg.projectDirs.length > 1 ? { projectDirs: cfg.projectDirs } : {},
+      recents: listRecents().map((r) => r.dir),
       environments,
       lexicons,
       currentEnv: cfg.env ?? null,
@@ -4003,6 +4060,72 @@ function createApp(cfg, broadcaster = new Broadcaster(), frames = new FrameBuffe
       ...axes
     });
   });
+  app.post("/api/project/open", async (c) => {
+    if (cfg.previewMode) return c.json({ error: "switching projects is locked in preview mode" }, 403);
+    const body = await c.req.json().catch(() => ({}));
+    const dir = typeof body.dir === "string" && body.dir.trim() ? resolve2(body.dir.trim()) : "";
+    if (!dir || !existsSync9(dir)) return c.json({ error: `no such directory: ${dir || "(no dir given)"}` }, 400);
+    if (!existsSync9(join10(dir, "chant.config.ts"))) {
+      return c.json({ error: `${dir} doesn't look like a chant project \u2014 no chant.config.ts` }, 400);
+    }
+    addRecent(cfg.projectDir);
+    cfg.projectDir = dir;
+    cfg.projectDirs = void 0;
+    cfg.env = void 0;
+    beholdConfig = loadBeholdConfig(dir);
+    tierEnvVar = beholdConfig.tiers?.envVar;
+    runner.retarget(dir);
+    addRecent(dir);
+    cfg.onProjectSwitch?.(dir);
+    broadcaster.emit("changed");
+    return c.json({ ok: true, projectDir: dir });
+  });
+  app.post("/api/project/reveal", async (c) => {
+    const body = await c.req.json().catch(() => ({}));
+    const dir = typeof body.dir === "string" && body.dir.trim() ? resolve2(body.dir.trim()) : cfg.projectDir;
+    const known = /* @__PURE__ */ new Set([cfg.projectDir, ...cfg.projectDirs ?? [], ...listRecents().map((r) => r.dir)]);
+    if (!known.has(dir)) return c.json({ error: "not a served or recent project directory" }, 400);
+    const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "explorer" : "xdg-open";
+    try {
+      await execFileP(opener, [dir]);
+      return c.json({ ok: true });
+    } catch (err) {
+      return c.json({ error: err instanceof Error ? err.message : String(err) }, 500);
+    }
+  });
+  app.get(
+    "/api",
+    (c) => c.json({
+      name: "behold",
+      version: beholdVersion(),
+      agentsGuide: "https://github.com/INTENTIUS/behold/blob/main/AGENTS.md",
+      routes: [
+        { method: "GET", path: "/api", desc: "this index" },
+        { method: "GET", path: "/api/project", desc: "project info: dir, recents, environments, tiers, targets, stacks, preview lock" },
+        { method: "POST", path: "/api/project/open", desc: "switch the served project: JSON body {dir} (validated; preview-locked)" },
+        { method: "POST", path: "/api/project/reveal", desc: "open the OS file manager at a served/recent project dir: JSON body {dir?}" },
+        { method: "GET", path: "/api/graph", desc: "the graph {ir, svg, meta} \u2014 params: detail=0..3, components=1, logical=1, env, stack, tier, target, lens, up=1, down=1, radial=1" },
+        { method: "GET", path: "/api/overlay", desc: "live drift overlay for ?env= \u2014 same shape/params as /api/graph, plus runtime=1" },
+        { method: "GET", path: "/api/diff", desc: "per-node live diff for ?env= \u2014 {env, nodes: {<id>: {observed, diff, health, fieldDrift}}}" },
+        { method: "GET", path: "/api/reconcile", desc: "pending-change summary for ?env=" },
+        { method: "GET", path: "/api/resources", desc: "component \u2192 declared resources" },
+        { method: "GET", path: "/api/ci", desc: "generated CI pipeline projection {stages, jobs, forge}" },
+        { method: "GET", path: "/api/substrates", desc: "substrate readiness {substrates: [{name, label, status, detail, bringUp?}]}" },
+        { method: "GET", path: "/api/ops", desc: "committed Ops + adopt lexicons + apply progress" },
+        { method: "GET", path: "/api/history", desc: "recent source commits (rollback targets)" },
+        { method: "GET", path: "/api/frames", desc: "captured lanes frames" },
+        { method: "GET", path: "/api/events", desc: "SSE: changed / op / apply / pr" },
+        { method: "POST", path: "/api/refresh", desc: "re-observe live now (?env=) \u2014 returns the fresh graph" },
+        { method: "POST", path: "/api/apply", desc: "delegated apply: ?env=&component=<name|all> (guarded, preview-locked)" },
+        { method: "POST", path: "/api/ops/:name/run", desc: "run a committed Op (delegated write)" },
+        { method: "POST", path: "/api/ops/:name/signal/:gate", desc: "approve an Op's gate" },
+        { method: "POST", path: "/api/rollback", desc: "open a rollback PR: ?to=<sha>" },
+        { method: "POST", path: "/api/substrates/:name/up", desc: "bring a substrate up" },
+        { method: "POST", path: "/api/local/reset", desc: "reset the local emulator" },
+        { method: "POST", path: "/api/ci/dispatch", desc: "dispatch the GitHub Actions pipeline via the operator's gh" }
+      ]
+    })
+  );
   app.get("/api/graph", async (c) => {
     const url = new URL(c.req.url);
     const opts = optsFromQuery(url, tierEnvVar, cfg.projectDir);
@@ -4050,6 +4173,9 @@ function createApp(cfg, broadcaster = new Broadcaster(), frames = new FrameBuffe
           srcCompositeEdgesAttached = 0;
         }
       }
+      if (!multi && !components && !logical && !opts.lens && ir.nodes.length === 0 && !existsSync9(join10(cfg.projectDir, "chant.config.ts"))) {
+        return c.json(noProjectError(cfg.projectDir), 404);
+      }
       const radial = new URL(c.req.url).searchParams.get("radial") === "1";
       const { svg } = renderGraph(ir, multi ? { boxes: "byStack" } : { radial });
       const srcZoom = components ? "components" : logical ? "logical" : opts.detail === 1 ? "composites" : opts.detail === 3 ? "attributes" : "resources";
@@ -4333,7 +4459,7 @@ function createApp(cfg, broadcaster = new Broadcaster(), frames = new FrameBuffe
   });
   const rel = relative(process.cwd(), webRoot) || ".";
   app.use("/*", serveStatic({ root: rel }));
-  app.get("/", serveStatic({ path: join9(rel, "index.html") }));
+  app.get("/", serveStatic({ path: join10(rel, "index.html") }));
   return app;
 }
 async function startServer(cfg) {
@@ -4401,8 +4527,8 @@ async function startServer(cfg) {
       }
     }
   };
-  const stopWatch = watchSource(cfg.projectDir, onEstateChange);
-  const stopPoll = cfg.env && cfg.pollSecs ? startDriftPoll({
+  let stopWatch = watchSource(cfg.projectDir, onEstateChange);
+  let stopPoll = cfg.env && cfg.pollSecs ? startDriftPoll({
     intervalMs: cfg.pollSecs * 1e3,
     query: () => graphIr(cfg.projectDir, { live: true, overlay: true, env: cfg.env }),
     onChange: onPollDrift,
@@ -4410,6 +4536,16 @@ async function startServer(cfg) {
 `)
   }) : () => {
   };
+  cfg.onProjectSwitch = (dir) => {
+    stopWatch();
+    stopWatch = watchSource(dir, onEstateChange);
+    stopPoll();
+    stopPoll = () => {
+    };
+    process.stdout.write(`  switched \u2192 ${dir}
+`);
+    void capture();
+  };
   void capture();
   let shuttingDown = false;
   const shutdown = () => {
@@ -4455,8 +4591,8 @@ async function startServer(cfg) {
 }
 
 // src/export.ts
-import { mkdirSync, writeFileSync, copyFileSync, readFileSync as readFileSync6, readdirSync as readdirSync4 } from "node:fs";
-import { join as join10, dirname as dirname3, basename } from "node:path";
+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 { fileURLToPath as fileURLToPath2 } from "node:url";
 var LENS_PARAMS = ["components", "detail", "env", "logical", "radial", "tier"];
 function canonicalKey(path, params) {
@@ -4504,7 +4640,7 @@ function captureKeys(axes) {
   return [...keys];
 }
 function webDir() {
-  return join10(dirname3(fileURLToPath2(import.meta.url)), "..", "web");
+  return join11(dirname4(fileURLToPath2(import.meta.url)), "..", "web");
 }
 function workerName(project, override) {
   const raw = override ?? `behold-${basename(project)}`;
@@ -4515,8 +4651,8 @@ 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 = join10(outDir, "snapshots");
-  mkdirSync(snapDir, { recursive: true });
+  const snapDir = join11(outDir, "snapshots");
+  mkdirSync2(snapDir, { recursive: true });
   const keyToFile = {};
   let ok = 0;
   let failed = 0;
@@ -4524,7 +4660,7 @@ async function runExport(cfg, outDir, opts = {}) {
     const res = await app.request(key);
     const body = await res.text();
     const file = slug(key);
-    writeFileSync(join10(snapDir, file), body);
+    writeFileSync2(join11(snapDir, file), body);
     keyToFile[key] = `snapshots/${file}`;
     if (res.ok) ok++;
     else failed++;
@@ -4536,21 +4672,21 @@ async function runExport(cfg, outDir, opts = {}) {
     axes,
     keyToFile
   };
-  writeFileSync(join10(outDir, "manifest.json"), JSON.stringify(manifest, null, 2));
-  const html = readFileSync6(join10(webDir(), "index.html"), "utf8").replace(
+  writeFileSync2(join11(outDir, "manifest.json"), JSON.stringify(manifest, null, 2));
+  const html = readFileSync8(join11(webDir(), "index.html"), "utf8").replace(
     /<\/head>/i,
     `  <script>window.__BEHOLD_STATIC__ = true;</script>
   </head>`
   );
-  writeFileSync(join10(outDir, "index.html"), html);
+  writeFileSync2(join11(outDir, "index.html"), html);
   for (const f of readdirSync4(webDir())) {
     if (f === "index.html") continue;
-    copyFileSync(join10(webDir(), f), join10(outDir, f));
+    copyFileSync(join11(webDir(), f), join11(outDir, f));
   }
-  writeFileSync(join10(outDir, "README.md"), BUNDLE_README);
+  writeFileSync2(join11(outDir, "README.md"), BUNDLE_README);
   const name = workerName(cfg.projectDir, opts.name);
-  writeFileSync(
-    join10(outDir, "wrangler.jsonc"),
+  writeFileSync2(
+    join11(outDir, "wrangler.jsonc"),
     JSON.stringify(
       { $schema: "node_modules/wrangler/config-schema.json", name, compatibility_date: "2025-06-01", assets: { directory: "." } },
       null,
@@ -4601,10 +4737,18 @@ 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 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.
+
   export  Capture the live estate into a self-contained, interactive STATIC
           bundle (default ./behold-export) \u2014 every env/tier \xD7 zoom \xD7 radial,
           replayable with no backend. Host it anywhere (Cloudflare Pages/Workers,
@@ -4659,6 +4803,7 @@ Options:
   --name <worker>     export only: Cloudflare Worker name in the generated
                       wrangler.jsonc.
   -h, --help          This text.
+  -v, --version       Print the behold version.
 `;
 async function run3(argv) {
   const [cmd, ...rest] = argv;
@@ -4666,6 +4811,14 @@ async function run3(argv) {
     process.stdout.write(USAGE);
     return;
   }
+  if (cmd === "-v" || cmd === "--version") {
+    process.stdout.write(beholdVersion() + "\n");
+    return;
+  }
+  if (cmd === "demo") {
+    await runDemo(rest);
+    return;
+  }
   if (cmd === "preview") {
     await runPreview(rest);
     return;
@@ -4729,7 +4882,8 @@ ${USAGE}`);
     process.stderr.write("behold serve: --auto-sync needs --env and --poll (it acts on polled drift)\n");
     process.exit(2);
   }
-  const dirs = projectDirs.map((d) => resolve2(d));
+  const dirs = projectDirs.map((d) => resolve3(d));
+  for (const d of dirs) warnIfNotChantProject(d);
   await startServer({
     projectDir: dirs[0],
     // primary — ops/overlay/rollback act on it
@@ -4741,6 +4895,61 @@ ${USAGE}`);
     ...local ? { local: true } : {}
   });
 }
+function warnIfNotChantProject(dir) {
+  if (existsSync10(join12(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).
+`
+  );
+}
+async function runDemo(rest) {
+  let port = 4600;
+  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 {
+      process.stderr.write(`behold demo: unexpected argument '${a}'
+`);
+      process.exit(2);
+    }
+  }
+  if (!Number.isFinite(port)) {
+    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");
+    process.exit(2);
+  }
+  const target = resolve3(dirArg ?? "behold-demo");
+  if (!existsSync10(target)) {
+    process.stdout.write(`behold demo \u2192 copying the example project 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 \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 (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)]);
+}
 function injectEmulatorEnv(env) {
   process.env.LOOM_ENV ??= env ?? "local";
   process.env.AWS_ENDPOINT_URL ??= "http://localhost:4566";
@@ -4763,13 +4972,14 @@ async function runPreview(rest) {
     process.stderr.write("behold preview: --port must be a number\n");
     process.exit(2);
   }
-  const projectDir = resolve2(dirArg ?? process.cwd());
-  if (!existsSync9(projectDir)) {
+  const projectDir = resolve3(dirArg ?? process.cwd());
+  if (!existsSync10(projectDir)) {
     process.stderr.write(`behold preview: project not found at ${projectDir}
 `);
     process.exit(2);
   }
   if (!emulator) {
+    warnIfNotChantProject(projectDir);
     await startServer({ projectDir, port });
     return;
   }
@@ -4783,26 +4993,26 @@ async function runPreview(rest) {
   await startServer({ projectDir, port, env: "local", previewMode: true });
 }
 async function runExportCmd(rest) {
-  let outDir = resolve2("behold-export");
+  let outDir = resolve3("behold-export");
   let env;
   let name;
   let dirArg;
   let emulator = false;
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
-    if (a === "--out") outDir = resolve2(rest[++i]);
+    if (a === "--out") outDir = resolve3(rest[++i]);
     else if (a === "--env") env = rest[++i];
     else if (a === "--name") name = rest[++i];
     else if (a === "--emulator") emulator = true;
     else if (a === "-h" || a === "--help") return void process.stdout.write(USAGE);
     else if (!a.startsWith("-")) dirArg = a;
   }
-  const projectDir = resolve2(dirArg ?? process.cwd());
+  const projectDir = resolve3(dirArg ?? process.cwd());
   if (emulator) {
     injectEmulatorEnv(env);
     env ??= "local";
   }
-  if (!existsSync9(projectDir)) {
+  if (!existsSync10(projectDir)) {
     process.stderr.write(`behold export: project not found at ${projectDir}
 `);
     process.exit(2);