@intentius/behold 0.2.3 → 0.4.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;
 }
@@ -133,8 +164,9 @@ function readInfo(cfg) {
   const envNames = (v) => Array.isArray(v) ? v.map((x) => typeof x === "string" ? x : typeof x?.name === "string" ? x.name : void 0).filter((x) => !!x) : [];
   const stacks = readStacks(cfg?.stacks);
   const k8sProfiles = readK8sProfiles(cfg?.k8s);
+  const environments = envNames(cfg?.environments);
   return {
-    environments: envNames(cfg?.environments),
+    environments: environments.length ? environments : Object.keys(k8sProfiles ?? {}),
     lexicons: arr(cfg?.lexicons),
     ...k8sProfiles ? { k8sProfiles } : {},
     ...typeof cfg?.sourceDir === "string" ? { sourceDir: cfg.sourceDir } : {},
@@ -155,6 +187,36 @@ function parseEnvironmentNames(content) {
   }
   return [...body.matchAll(/["'`]([^"'`]+)["'`]/g)].map((m) => m[1]);
 }
+function parseK8sProfileNames(content) {
+  const m = content.match(/\bprofiles\s*:\s*\{/);
+  if (!m || m.index === void 0) return [];
+  const start = m.index + m[0].length;
+  let depth = 1;
+  let end = start;
+  for (; end < content.length && depth > 0; end++) {
+    if (content[end] === "{") depth++;
+    else if (content[end] === "}") depth--;
+  }
+  const body = content.slice(start, end - 1);
+  const names = [];
+  let d = 0;
+  let segment = "";
+  for (const ch of body) {
+    if (ch === "{") {
+      if (d === 0) {
+        const key = segment.match(/(["'`]?)([\w.-]+)\1\s*:\s*$/);
+        if (key) names.push(key[2]);
+        segment = "";
+      }
+      d++;
+    } else if (ch === "}") {
+      d--;
+    } else if (d === 0) {
+      segment += ch;
+    }
+  }
+  return names;
+}
 function parseStringLiteral(content, key) {
   const m = content.match(new RegExp(`\\b${key}\\s*:\\s*["'\`]([^"'\`]+)["'\`]`));
   return m?.[1];
@@ -169,10 +231,11 @@ 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");
+  const environments = parseEnvironmentNames(content);
   return {
-    environments: parseEnvironmentNames(content),
+    environments: environments.length ? environments : parseK8sProfileNames(content),
     lexicons: parseStringArray(content, "lexicons"),
     ...sourceDir ? { sourceDir } : {}
   };
@@ -185,10 +248,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 +552,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 +568,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 +660,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 +685,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 +798,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 +819,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 +839,7 @@ function discoverReleaseUnits(projectDir) {
   for (const file of files) {
     let content;
     try {
-      content = readFileSync2(file, "utf8");
+      content = readFileSync3(file, "utf8");
     } catch {
       continue;
     }
@@ -829,8 +892,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 +947,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 +981,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 +993,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;
     }
@@ -1838,7 +1901,7 @@ function projectK8sLogical(ir, env, boundContext) {
   if (k8s.length === 0) return { ir: { nodes: [], edges: [], groups: {} }, byContainer: {} };
   const cluster = boundManagedCluster(ir.nodes, boundContext);
   const CLUSTER_TITLE = cluster ? cluster.id : env ? `cluster ${env}` : "cluster";
-  const CLUSTER_SCOPED = "cluster-scoped";
+  const CLUSTER_SCOPED2 = "cluster-scoped";
   const namespaceTitle = (ns) => `namespace ${ns}`;
   const byContainer = {};
   const child = (parent, c) => {
@@ -1854,10 +1917,10 @@ function projectK8sLogical(ir, env, boundContext) {
       child(namespaceTitle(ns), n.id);
     } else {
       clusterScoped = true;
-      child(CLUSTER_SCOPED, n.id);
+      child(CLUSTER_SCOPED2, n.id);
     }
   }
-  if (clusterScoped) child(CLUSTER_TITLE, CLUSTER_SCOPED);
+  if (clusterScoped) child(CLUSTER_TITLE, CLUSTER_SCOPED2);
   const kept = new Set(headline.map((n) => n.id));
   const edges = ir.edges.filter((e) => kept.has(e.from) && kept.has(e.to));
   return { ir: { nodes: headline, edges, groups: {} }, byContainer };
@@ -1904,8 +1967,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 +1982,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 +1991,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: {} };
@@ -2519,6 +2582,22 @@ function edgelessNote(zoom, ir) {
   if (ir.nodes.length === 0 || ir.edges.length > 0) return void 0;
   return "no edges \u2014 nothing in this estate references anything else";
 }
+var CLUSTER_SCOPED = /* @__PURE__ */ new Set([
+  "K8s::Core::Namespace",
+  "K8s::Rbac::ClusterRole",
+  "K8s::Rbac::ClusterRoleBinding",
+  "K8s::Storage::StorageClass",
+  "K8s::Apiextensions::CustomResourceDefinition"
+]);
+function namespaceMismatchNote(nodes) {
+  const k8s = nodes.filter((n) => n?.lexicon === "k8s");
+  if (k8s.length === 0) return void 0;
+  const pending = k8s.filter((n) => n.attrs?._status === "accent" && !CLUSTER_SCOPED.has(n.kind ?? ""));
+  if (pending.length < 3) return void 0;
+  if (pending.some((n) => typeof n.attrs?.metadata?.namespace === "string" && n.attrs.metadata.namespace)) return void 0;
+  if (!k8s.some((n) => n.attrs?._status === "good")) return void 0;
+  return `${pending.length} pending k8s objects declare no metadata.namespace \u2014 if a controller stamps it at apply time (e.g. Flux's targetNamespace), the live read looked in "default", not where they run`;
+}
 function notesFor(zoom, ir, compositeEdgesAttached, logicalBefore) {
   const primary = zoom === "logical" && logicalBefore !== void 0 ? logicalKept(logicalBefore, ir.nodes.length) : zoomNote(zoom, ir, compositeEdgesAttached);
   const notes = [primary, edgelessNote(zoom, ir)].filter((n) => n !== void 0);
@@ -2821,8 +2900,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 +2923,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 +3148,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 +3323,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 +3352,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 +3406,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 +3436,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 +3449,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({
@@ -3477,10 +3561,48 @@ async function composeEstate(projectDirs, opts = {}) {
   );
   return composeStacks(stacks);
 }
+var firstLine = (e) => {
+  const msg = e instanceof Error ? e.message : String(e);
+  const m = msg.match(/exited \d+:\s*([\s\S]*)/);
+  return (m ? m[1] : msg).split("\n")[0].trim().slice(0, 160);
+};
+async function composeEstateOverlay(projectDirs, opts, classify) {
+  const names = shortStackNames(projectDirs);
+  const unobserved = [];
+  const dropped = [];
+  const stacks = new Array(projectDirs.length);
+  await Promise.all(
+    projectDirs.map(async (dir, i) => {
+      const name = names[i];
+      try {
+        stacks[i] = { name, ir: classify(await graphIr(dir, { ...opts, live: true, overlay: true })) };
+      } catch (err) {
+        const reason = firstLine(err);
+        try {
+          const { env: _env, live: _live, overlay: _overlay, ...srcOpts } = opts;
+          const src = await graphIr(dir, srcOpts);
+          for (const n of src.nodes) n.attrs = { ...n.attrs, _status: "neutral", _unobserved: reason };
+          stacks[i] = { name, ir: src };
+          unobserved.push({ name, reason });
+        } catch (err2) {
+          dropped.push({ name, reason: firstLine(err2) });
+        }
+      }
+    })
+  );
+  const present = stacks.filter((s) => !!s);
+  return {
+    ir: composeStacks(present),
+    observed: present.length - unobserved.length,
+    total: projectDirs.length,
+    unobserved,
+    dropped
+  };
+}
 
 // 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 +3620,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 +3892,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 +3939,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 +3992,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 +4075,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,7 +4113,18 @@ 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,
+      // #191: the cluster each k8s env is bound to (`k8s.profiles.<env>.
+      // context`) — the SPA's env picker shows it (`home → home-cloud`) so a
+      // wrong-cluster pick is visible BEFORE the read, not after (the failure
+      // chant#1100 exists to prevent, and the one behind #192's red herring).
+      ...k8sProfiles ? { k8sContexts: Object.fromEntries(Object.entries(k8sProfiles).flatMap(([e, p]) => p.context ? [[e, p.context]] : [])) } : {},
       lexicons,
       currentEnv: cfg.env ?? null,
       // v0.1.0 preview: the SPA hides git/PR ops + arbitrary-project affordances.
@@ -4003,6 +4151,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);
@@ -4015,6 +4229,9 @@ function createApp(cfg, broadcaster = new Broadcaster(), frames = new FrameBuffe
       let metaEnv = cfg.env ?? null;
       if (multi) {
         ir = await composeEstate(cfg.projectDirs, opts);
+        ir = addValueMatchEdges(ir);
+        ir = addK8sDeclaredEdges(ir);
+        ir = addClusterAnchorEdges(ir, await boundK8sContext(metaEnv ?? void 0));
       } else if (components) {
         ir = await componentGraphIr(cfg.projectDir, opts);
         const env = opts.env ?? cfg.env;
@@ -4050,10 +4267,14 @@ 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";
-      const srcNote = multi ? void 0 : notesFor(srcZoom, ir, srcCompositeEdgesAttached);
+      const estateLensNote = multi && (components || logical) ? `the ${components ? "components" : "logical"} lens doesn't apply to a composed estate yet \u2014 showing the composed entity graph` : void 0;
+      const srcNote = multi ? estateLensNote : notesFor(srcZoom, ir, srcCompositeEdgesAttached);
       return c.json({
         ir,
         svg,
@@ -4152,6 +4373,30 @@ function createApp(cfg, broadcaster = new Broadcaster(), frames = new FrameBuffe
     }
     const logical = new URL(c.req.url).searchParams.get("logical") === "1";
     try {
+      if (cfg.projectDirs && cfg.projectDirs.length > 1) {
+        const runtime = new URL(c.req.url).searchParams.get("runtime") === "1";
+        const est = await composeEstateOverlay(cfg.projectDirs, { ...tierTargetOpts(query), detail: query.detail, env }, reclassifyOverlay);
+        if (est.dropped.length === est.total) {
+          return c.json({ error: `no project in the estate could be graphed \u2014 ${est.dropped.map((d) => `${d.name}: ${d.reason}`).join("; ")}` }, 500);
+        }
+        let ir2 = pruneRuntimeChildren(est.ir);
+        if ((query.detail ?? 2) < 3) ir2 = pruneImports(ir2);
+        ir2 = addValueMatchEdges(ir2);
+        ir2 = addK8sDeclaredEdges(ir2);
+        ir2 = addClusterAnchorEdges(ir2, await boundK8sContext(env));
+        const { svg: svg2 } = renderGraph(ir2, { boxes: "byStack" });
+        const lensNote = logical || runtime ? `the ${logical ? "logical" : "runtime"} lens doesn't apply to a composed estate yet \u2014 showing the composed entity overlay` : void 0;
+        const coverNote = est.unobserved.length || est.dropped.length ? `live observe covered ${est.observed} of ${est.total} projects \u2014 ` + [
+          ...est.unobserved.map((u) => `${u.name}: ${u.reason} (painted unobserved)`),
+          ...est.dropped.map((d) => `${d.name}: dropped (${d.reason})`)
+        ].join("; ") : void 0;
+        const note2 = [lensNote, coverNote, namespaceMismatchNote(ir2.nodes)].filter(Boolean).join(" \xB7 ");
+        return c.json({
+          ir: ir2,
+          svg: svg2,
+          meta: { projectDir: cfg.projectDir, env, mode: "overlay", estate: est.total, ...note2 ? { note: note2 } : {} }
+        });
+      }
       const opts = { ...query, live: true, overlay: true, env, ...logical ? { detail: 3 } : {} };
       let ir = reclassifyOverlay(await graphIr(cfg.projectDir, opts));
       const boundContext = await boundK8sContext(env);
@@ -4189,8 +4434,9 @@ function createApp(cfg, broadcaster = new Broadcaster(), frames = new FrameBuffe
       const { svg } = renderGraph(ir, { boxes: "byContainer", radial: new URL(c.req.url).searchParams.get("radial") === "1" });
       const zoom = new URL(c.req.url).searchParams.get("runtime") === "1" ? "runtime" : query.detail === 1 ? "composites" : query.detail === 3 ? "attributes" : "resources";
       const tierNote = tierMismatchNote(ir, beholdConfig.tiers, query.tier);
+      const nsNote = namespaceMismatchNote(ir.nodes);
       const zoomNotes = notesFor(zoom, ir, compositeEdgesAttached);
-      const note = [tierNote, zoomNotes].filter(Boolean).join(" \xB7 ");
+      const note = [tierNote, nsNote, zoomNotes].filter(Boolean).join(" \xB7 ");
       return c.json({ ir, svg, meta: { projectDir: cfg.projectDir, env, mode: "overlay", ...note ? { note } : {} } });
     } catch (err) {
       return errorResponse(c, query, err);
@@ -4333,7 +4579,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 +4647,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 +4656,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 +4711,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 +4760,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 +4771,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 +4780,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 +4792,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 +4857,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 +4923,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 +4931,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 +5002,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 +5015,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 +5092,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 +5113,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);