@intentius/behold 0.6.0 → 0.8.0

package/dist/cli.js

@@ -1,8 +1,8 @@
 // src/cli.ts
-import { resolve as resolve3, dirname as dirname5, join as join13, relative as relative2, sep } from "node:path";
+import { resolve as resolve4, dirname as dirname6, join as join14, relative as relative3, sep } from "node:path";
 import { realpathSync, existsSync as existsSync10, cpSync } from "node:fs";
 import { spawnSync as spawnSync2 } from "node:child_process";
-import { fileURLToPath as fileURLToPath3 } from "node:url";
+import { fileURLToPath as fileURLToPath5 } from "node:url";
 
 // src/server.ts
 import { Hono } from "hono";
@@ -87,11 +87,11 @@ function contextBindsCluster(context, clusterName) {
 import { streamSSE } from "hono/streaming";
 import { serveStatic } from "@hono/node-server/serve-static";
 import { serve } from "@hono/node-server";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
 import { execFile as execFile4 } from "node:child_process";
 import { promisify as promisify4 } from "node:util";
-import { existsSync as existsSync9, readFileSync as readFileSync7 } from "node:fs";
-import { dirname as dirname3, join as join10, relative, resolve as resolve2 } from "node:path";
+import { existsSync as existsSync9, readFileSync as readFileSync9 } from "node:fs";
+import { dirname as dirname4, join as join11, relative, resolve as resolve2 } from "node:path";
 
 // src/recents.ts
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
@@ -125,8 +125,9 @@ function addRecent(dir, now = () => (/* @__PURE__ */ new Date()).toISOString())
 
 // src/chant.ts
 import { spawn } from "node:child_process";
-import { existsSync as existsSync3 } from "node:fs";
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";
 import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
 import { dirname as dirname2, join as join3, resolve } from "node:path";
 
 // src/project.ts
@@ -135,7 +136,7 @@ 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) {
+function chantConfigPath(projectDir) {
   for (const name of CONFIG_NAMES) {
     const p = join2(projectDir, name);
     if (existsSync2(p)) return p;
@@ -222,7 +223,7 @@ function parseStringLiteral(content, key) {
   return m?.[1];
 }
 async function detectProject(projectDir) {
-  const path = configPath(projectDir);
+  const path = chantConfigPath(projectDir);
   if (!path) return { environments: [], lexicons: [] };
   try {
     const mod = await import(pathToFileURL(path).href);
@@ -253,11 +254,30 @@ function loadBeholdConfig(projectDir) {
   try {
     const raw = JSON.parse(readFileSync2(path, "utf8"));
     const tiers = readTiers(raw);
-    return tiers ? { tiers } : {};
+    const members = Array.isArray(raw.members) ? raw.members.filter((m) => typeof m === "string" && !!m) : [];
+    return { ...tiers ? { tiers } : {}, ...members.length ? { members } : {} };
   } catch {
     return {};
   }
 }
+function readWorkspaces(projectDir) {
+  try {
+    const raw = JSON.parse(readFileSync2(join2(projectDir, "package.json"), "utf8"));
+    const ws = Array.isArray(raw.workspaces) ? raw.workspaces : raw.workspaces?.packages;
+    return Array.isArray(ws) ? ws.filter((w) => typeof w === "string") : [];
+  } catch {
+    return [];
+  }
+}
+function detectProjectShape(projectDir) {
+  const configFile = chantConfigPath(projectDir);
+  if (configFile) return { kind: "project", configFile };
+  const declared = loadBeholdConfig(projectDir).members;
+  const from = declared ? "behold-config" : "workspaces";
+  const members = (declared ?? readWorkspaces(projectDir)).filter((m) => !!chantConfigPath(join2(projectDir, m)));
+  if (members.length) return { kind: "estate", members, membersFrom: from };
+  return { kind: "none" };
+}
 
 // node_modules/@intentius/chant/src/yaml.ts
 function parseYAML(content) {
@@ -545,19 +565,18 @@ function graphFlags(opts) {
   if (opts.overlay) flags.push("--overlay");
   return flags;
 }
-function chantBinFrom(req) {
+function packageManifestFrom(req, name) {
   let entry;
   try {
-    entry = req.resolve("@intentius/chant");
+    entry = req.resolve(name);
   } catch {
     return void 0;
   }
   let dir = dirname2(entry);
   for (; ; ) {
-    const manifest = join3(dir, "package.json");
     try {
-      const pkg = createRequire(import.meta.url)(manifest);
-      if (pkg.name === "@intentius/chant") return join3(dir, pkg.bin?.chant ?? "bin/chant");
+      const pkg = createRequire(import.meta.url)(join3(dir, "package.json"));
+      if (pkg.name === name) return { root: dir, manifest: pkg };
     } catch {
     }
     const parent = dirname2(dir);
@@ -566,14 +585,52 @@ function chantBinFrom(req) {
   }
   return void 0;
 }
-function chantBin(projectDir) {
+function chantPackageFrom(req) {
+  const found = packageManifestFrom(req, "@intentius/chant");
+  if (!found) return void 0;
+  const { root, manifest } = found;
+  return { root, bin: join3(root, manifest.bin?.chant ?? "bin/chant"), ...manifest.version ? { version: manifest.version } : {} };
+}
+function resolveLexicons(projectDir, lexicons) {
+  const req = createRequire(join3(resolve(projectDir), "noop.js"));
+  return lexicons.map((lexicon) => {
+    const pkg = `@intentius/chant-lexicon-${lexicon}`;
+    const found = packageManifestFrom(req, pkg);
+    return { lexicon, pkg, installed: !!found, ...found?.manifest.version ? { version: found.manifest.version } : {} };
+  });
+}
+function resolveChant(projectDir) {
+  const own = chantPackageFrom(createRequire(import.meta.url));
   if (projectDir) {
-    const fromProject = chantBinFrom(createRequire(join3(resolve(projectDir), "noop.js")));
-    if (fromProject) return fromProject;
+    const fromProject = chantPackageFrom(createRequire(join3(resolve(projectDir), "noop.js")));
+    if (fromProject) return { source: fromProject.root === own?.root ? "behold" : "project", ...fromProject };
+  }
+  if (own) return { source: "behold", ...own };
+  return { source: "path", bin: "chant" };
+}
+function chantFloor() {
+  try {
+    const here = dirname2(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(readFileSync3(join3(here, "..", "package.json"), "utf8"));
+    return pkg.dependencies?.["@intentius/chant"]?.replace(/^[^0-9]*/, "") || void 0;
+  } catch {
+    return void 0;
+  }
+}
+function meetsFloor(version, floor) {
+  if (!version || !floor) return true;
+  const parts = (v) => v.split("-")[0].split(".").map((n) => Number.parseInt(n, 10));
+  const a = parts(version);
+  const b = parts(floor);
+  if (a.some(Number.isNaN) || b.some(Number.isNaN)) return true;
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const d = (a[i] ?? 0) - (b[i] ?? 0);
+    if (d !== 0) return d > 0;
   }
-  const own = chantBinFrom(createRequire(import.meta.url));
-  if (own) return own;
-  return "chant";
+  return true;
+}
+function chantBin(projectDir) {
+  return resolveChant(projectDir).bin;
 }
 function runChantRaw(args, projectDir, envOverride) {
   return new Promise((resolvePromise, reject) => {
@@ -798,7 +855,7 @@ function mergeClusterRoot(ir, clusterIr, running) {
 }
 
 // src/helm-releases.ts
-import { existsSync as existsSync4, readdirSync, readFileSync as readFileSync3, statSync } from "node:fs";
+import { existsSync as existsSync4, readdirSync, readFileSync as readFileSync4, statSync } from "node:fs";
 import { join as join4 } from "node:path";
 var RELEASE_KEY = /^release\/([^/]+)\/(.+)$/;
 function declaredChartNames(ir) {
@@ -839,7 +896,7 @@ function discoverReleaseUnits(projectDir) {
   for (const file of files) {
     let content;
     try {
-      content = readFileSync3(file, "utf8");
+      content = readFileSync4(file, "utf8");
     } catch {
       continue;
     }
@@ -892,7 +949,7 @@ function synthesizeHelmReleases(ir, observed, owners) {
 
 // src/gh-run.ts
 import { spawn as spawn2 } from "node:child_process";
-import { readdirSync as readdirSync2, readFileSync as readFileSync4 } from "node:fs";
+import { readdirSync as readdirSync2, readFileSync as readFileSync5 } from "node:fs";
 import { join as join5 } from "node:path";
 
 // src/ci-run.ts
@@ -947,19 +1004,19 @@ function finishPipelineProgress(state, exitCode) {
 }
 
 // src/gh-run.ts
-var defaultGhExec = (args) => new Promise((resolve4) => {
+var defaultGhExec = (args) => new Promise((resolve5) => {
   let out = "";
   let proc;
   try {
     proc = spawn2("gh", args, { stdio: ["ignore", "pipe", "pipe"] });
   } catch {
-    resolve4({ code: 127, out: "" });
+    resolve5({ code: 127, out: "" });
     return;
   }
   proc.stdout.on("data", (d) => out += d);
   proc.stderr.on("data", (d) => out += d);
-  proc.on("error", () => resolve4({ code: 127, out }));
-  proc.on("close", (code) => resolve4({ code: code ?? 1, out }));
+  proc.on("error", () => resolve5({ code: 127, out }));
+  proc.on("close", (code) => resolve5({ code: code ?? 1, out }));
 });
 async function ghReady(exec = defaultGhExec) {
   const { code, out } = await exec(["auth", "status"]);
@@ -993,7 +1050,7 @@ function pickWorkflow(projectDir, pipeline) {
   for (const f of files) {
     let text;
     try {
-      text = readFileSync4(join5(dir, f), "utf8");
+      text = readFileSync5(join5(dir, f), "utf8");
     } catch {
       continue;
     }
@@ -1309,13 +1366,22 @@ var FLUX_SOURCE_KINDS = /* @__PURE__ */ new Set([
   "K8s::Flux::HelmChart",
   "K8s::Flux::Bucket"
 ]);
-function sourceRefOf(refObj, referrer) {
+function sourceRefOf(refObj, referrer, defaultKind) {
   const ref = rec(refObj);
-  const kind = str2(ref?.kind);
+  const kind = str2(ref?.kind) ?? defaultKind;
   const name = str2(ref?.name);
   if (!kind || !name) return void 0;
   return { kind, name, namespace: str2(ref?.namespace) ?? namespaceOf(referrer) };
 }
+function namedRefOf(refObj, referrer) {
+  const ref = rec(refObj);
+  const name = str2(ref?.name);
+  if (!name) return void 0;
+  return { name, namespace: str2(ref?.namespace) ?? namespaceOf(referrer) };
+}
+function list(v) {
+  return Array.isArray(v) ? v : [];
+}
 function helmReleaseSourceRef(n) {
   return rec(rec(rec(n.attrs?.spec)?.chart)?.spec)?.sourceRef;
 }
@@ -1343,19 +1409,38 @@ function deriveK8sEdges(nodes) {
     if (from !== to) out.push({ from, to, kind: "ref", viaAttr, inferred: true });
   };
   const workloads = k8s.filter((n) => WORKLOAD_KINDS.has(n.kind));
-  const servicesByNsName = /* @__PURE__ */ new Map();
-  const sourcesByKindNsName = /* @__PURE__ */ new Map();
+  const byKindNsName = /* @__PURE__ */ new Map();
+  const appProjectsByName = /* @__PURE__ */ new Map();
   for (const n of k8s) {
     const name = nameOf(n);
     if (!name) continue;
-    if (n.kind === "K8s::Core::Service") servicesByNsName.set(`${namespaceOf(n)}/${name}`, n);
-    if (FLUX_SOURCE_KINDS.has(n.kind)) sourcesByKindNsName.set(`${shortKind(n.kind)}/${namespaceOf(n)}/${name}`, n);
+    byKindNsName.set(`${n.kind}\0${namespaceOf(n)}\0${name}`, n);
+    if (n.kind === "K8s::Argo::AppProject") {
+      const same = appProjectsByName.get(name) ?? [];
+      same.push(n);
+      appProjectsByName.set(name, same);
+    }
   }
-  const addSourceRef = (n, refObj, viaAttr) => {
-    const ref = sourceRefOf(refObj, n);
+  const lookup = (kind, namespace, name) => byKindNsName.get(`${kind}\0${namespace}\0${name}`);
+  const addFluxRef = (n, refObj, viaAttr, allowed, defaultKind) => {
+    const ref = sourceRefOf(refObj, n, defaultKind);
+    if (!ref || ref.name === "*") return;
+    const kind = `K8s::Flux::${ref.kind}`;
+    if (allowed && !allowed.has(kind)) return;
+    const target = lookup(kind, ref.namespace, ref.name);
+    if (target) add(n.id, target.id, viaAttr);
+  };
+  const addSourceRef = (n, refObj, viaAttr, defaultKind) => addFluxRef(n, refObj, viaAttr, FLUX_SOURCE_KINDS, defaultKind);
+  const addNamedRef = (n, refObj, kind, viaAttr) => {
+    const ref = namedRefOf(refObj, n);
     if (!ref) return;
-    const source = sourcesByKindNsName.get(`${ref.kind}/${ref.namespace}/${ref.name}`);
-    if (source) add(n.id, source.id, viaAttr);
+    const target = lookup(kind, ref.namespace, ref.name);
+    if (target) add(n.id, target.id, viaAttr);
+  };
+  const addProject = (n, project, viaAttr) => {
+    const candidates = project ? appProjectsByName.get(project) ?? [] : [];
+    const target = candidates.length === 1 ? candidates[0] : candidates.find((p) => namespaceOf(p) === namespaceOf(n));
+    if (target) add(n.id, target.id, viaAttr);
   };
   for (const n of k8s) {
     if (n.kind === "K8s::Core::Service") {
@@ -1370,7 +1455,7 @@ function deriveK8sEdges(nodes) {
     }
     if (n.kind === "K8s::Networking::Ingress") {
       for (const svcName of ingressBackendServices(n)) {
-        const svc = servicesByNsName.get(`${namespaceOf(n)}/${svcName}`);
+        const svc = lookup("K8s::Core::Service", namespaceOf(n), svcName);
         if (svc) add(n.id, svc.id, "ingress backend");
       }
       continue;
@@ -1388,10 +1473,36 @@ function deriveK8sEdges(nodes) {
     }
     if (n.kind === "K8s::Flux::Kustomization") {
       addSourceRef(n, rec(n.attrs?.spec)?.sourceRef, "sourceRef");
+      for (const dep of list(rec(n.attrs?.spec)?.dependsOn)) {
+        addNamedRef(n, dep, "K8s::Flux::Kustomization", "dependsOn");
+      }
       continue;
     }
     if (n.kind === "K8s::Flux::HelmRelease") {
       addSourceRef(n, helmReleaseSourceRef(n), "chart sourceRef");
+      continue;
+    }
+    if (n.kind === "K8s::Flux::ImagePolicy") {
+      addNamedRef(n, rec(n.attrs?.spec)?.imageRepositoryRef, "K8s::Flux::ImageRepository", "imageRepositoryRef");
+      continue;
+    }
+    if (n.kind === "K8s::Flux::ImageUpdateAutomation") {
+      addSourceRef(n, rec(n.attrs?.spec)?.sourceRef, "sourceRef", "GitRepository");
+      continue;
+    }
+    if (n.kind === "K8s::Flux::Alert") {
+      addNamedRef(n, rec(n.attrs?.spec)?.providerRef, "K8s::Flux::Provider", "providerRef");
+      for (const src of list(rec(n.attrs?.spec)?.eventSources)) {
+        addFluxRef(n, src, "eventSource");
+      }
+      continue;
+    }
+    if (n.kind === "K8s::Argo::Application") {
+      addProject(n, str2(rec(n.attrs?.spec)?.project), "project");
+      continue;
+    }
+    if (n.kind === "K8s::Argo::ApplicationSet") {
+      addProject(n, str2(rec(rec(rec(n.attrs?.spec)?.template)?.spec)?.project), "template project");
     }
   }
   return out;
@@ -1883,6 +1994,13 @@ function metaStr(node, key) {
   const v = meta?.[key];
   return typeof v === "string" ? v : void 0;
 }
+function destinationNamespace(n) {
+  if (n.kind !== "K8s::Argo::Application") return void 0;
+  const spec = n.attrs?.spec;
+  const dest = spec?.destination;
+  const ns = dest?.namespace;
+  return typeof ns === "string" && ns.length > 0 ? ns : void 0;
+}
 function declaredNamespaces(nodes) {
   const out = /* @__PURE__ */ new Set();
   for (const n of nodes) {
@@ -1893,6 +2011,8 @@ function declaredNamespaces(nodes) {
     }
     const ns = metaStr(n, "namespace");
     if (ns) out.add(ns);
+    const dest = destinationNamespace(n);
+    if (dest) out.add(dest);
   }
   return out;
 }
@@ -1972,6 +2092,12 @@ import { join as join6 } from "node:path";
 function overlayBoxTitle(name) {
   return `overlay ${name}`;
 }
+var ROOT_ANNOTATION = "chant.intentius.io/kustomize-root";
+function annotatedRoot(node) {
+  const metadata2 = node.attrs?.metadata;
+  const v = metadata2?.annotations?.[ROOT_ANNOTATION];
+  return typeof v === "string" && v ? v : void 0;
+}
 function dirOf2(node) {
   const file = node.sourceLoc?.file;
   if (typeof file !== "string") return "";
@@ -2002,12 +2128,15 @@ function projectKustomizeLogical(ir, sourceRoots, exists = existsSync5) {
   };
   const rootCache = /* @__PURE__ */ new Map();
   for (const n of k8s) {
-    const dir = dirOf2(n);
-    if (dir === "") continue;
-    if (!rootCache.has(dir)) rootCache.set(dir, kustomizationRoot(bases, dir, exists));
-    const root = rootCache.get(dir);
+    let root = annotatedRoot(n);
+    if (root === void 0) {
+      const dir = dirOf2(n);
+      if (dir === "") continue;
+      if (!rootCache.has(dir)) rootCache.set(dir, kustomizationRoot(bases, dir, exists));
+      root = rootCache.get(dir);
+    }
     if (root === void 0) continue;
-    const name = root.split("/").pop() || root;
+    const name = root.replace(/\/+$/, "").split("/").pop() || root;
     child(overlayBoxTitle(name), n.id);
   }
   return { ir: { nodes: [], edges: [], groups: {} }, byContainer };
@@ -2214,9 +2343,9 @@ function enrichedRefs(ir, aws, byId) {
   const producersByName = /* @__PURE__ */ new Map();
   for (const ex of ir.exports ?? []) {
     if (!ex.node || !byId.has(ex.node)) continue;
-    const list = producersByName.get(ex.name) ?? producersByName.set(ex.name, []).get(ex.name);
-    if (isExample(byId.get(ex.node))) list.push(ex.node);
-    else list.unshift(ex.node);
+    const list3 = producersByName.get(ex.name) ?? producersByName.set(ex.name, []).get(ex.name);
+    if (isExample(byId.get(ex.node))) list3.push(ex.node);
+    else list3.unshift(ex.node);
   }
   const exportNames = [...producersByName.keys()].sort((a, b) => b.length - a.length);
   const bridge = (paramId, producers) => {
@@ -2704,7 +2833,83 @@ function summarizePlan(plan, byComponent, nonResource) {
 }
 
 // src/render.ts
-import { layoutIr, layoutArchitecture, renderSvg, cardSizes } from "@intentius/pinhole";
+import { layoutIr, layoutArchitecture, renderSvg, cardSizes, registerPack } from "@intentius/pinhole";
+
+// src/icon-packs.ts
+import { readFileSync as readFileSync6 } from "node:fs";
+import { dirname as dirname3, join as join7 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+var ICON_ROOT = join7(dirname3(fileURLToPath2(import.meta.url)), "..", "web", "icons");
+var cache = /* @__PURE__ */ new Map();
+function unprefix(body) {
+  return body.replace(/\s(?:inkscape|sodipodi):[\w-]+\s*=\s*(["'])[\s\S]*?\1/g, "").replace(/\sxlink:href\s*=/g, " href=");
+}
+function loadIcon(rel) {
+  const hit = cache.get(rel);
+  if (hit) return hit;
+  const raw = readFileSync6(join7(ICON_ROOT, `${rel}.svg`), "utf8");
+  const open = raw.indexOf("<svg");
+  const openEnd = raw.indexOf(">", open);
+  const close = raw.lastIndexOf("</svg");
+  if (open < 0 || openEnd < 0 || close < 0) throw new Error(`malformed vendored icon: ${rel}.svg`);
+  const viewBox = /\bviewBox\s*=\s*(["'])(.*?)\1/.exec(raw.slice(open, openEnd))?.[2];
+  if (!viewBox) throw new Error(`vendored icon has no viewBox: ${rel}.svg`);
+  const glyph = { body: unprefix(raw.slice(openEnd + 1, close).trim()), colored: true, viewBox };
+  cache.set(rel, glyph);
+  return glyph;
+}
+var K8S_ICON_BY_KIND = {
+  "K8s::Apiextensions::CustomResourceDefinition": "crd",
+  "K8s::Apps::DaemonSet": "ds",
+  "K8s::Apps::Deployment": "deploy",
+  "K8s::Apps::ReplicaSet": "rs",
+  "K8s::Apps::StatefulSet": "sts",
+  "K8s::Autoscaling::HorizontalPodAutoscaler": "hpa",
+  "K8s::Batch::CronJob": "cronjob",
+  "K8s::Batch::Job": "job",
+  "K8s::Core::ConfigMap": "cm",
+  "K8s::Core::Endpoints": "ep",
+  "K8s::Core::LimitRange": "limits",
+  "K8s::Core::Namespace": "ns",
+  "K8s::Core::PersistentVolume": "pv",
+  "K8s::Core::PersistentVolumeClaim": "pvc",
+  "K8s::Core::Pod": "pod",
+  "K8s::Core::PodTemplate": "pod",
+  "K8s::Core::ReplicationController": "rs",
+  // the pre-ReplicaSet spelling of the same thing
+  "K8s::Core::ResourceQuota": "quota",
+  "K8s::Core::Secret": "secret",
+  "K8s::Core::Service": "svc",
+  "K8s::Core::ServiceAccount": "sa",
+  "K8s::Core::Volume": "vol",
+  "K8s::Networking::Ingress": "ing",
+  "K8s::Networking::IngressClass": "ing",
+  "K8s::Networking::NetworkPolicy": "netpol",
+  "K8s::Rbac::ClusterRole": "c-role",
+  "K8s::Rbac::ClusterRoleBinding": "crb",
+  "K8s::Rbac::Role": "role",
+  "K8s::Rbac::RoleBinding": "rb",
+  "K8s::Storage::StorageClass": "sc"
+};
+var K8S_MARK_BY_PREFIX = [
+  ["K8s::Flux::", "cncf/flux"],
+  ["K8s::Argo::", "cncf/argo"]
+];
+var HELM_MARK_KINDS = /* @__PURE__ */ new Set(["Helm::Chart", "Helm::Release"]);
+function k8sIconFor(kind) {
+  for (const [prefix, rel] of K8S_MARK_BY_PREFIX) {
+    if (kind.startsWith(prefix)) return loadIcon(rel);
+  }
+  const stem = K8S_ICON_BY_KIND[kind];
+  return stem ? loadIcon(`k8s/${stem}`) : void 0;
+}
+function helmIconFor(kind) {
+  return HELM_MARK_KINDS.has(kind) ? loadIcon("cncf/helm") : void 0;
+}
+
+// src/render.ts
+registerPack({ lexicon: "k8s", iconFor: k8sIconFor });
+registerPack({ lexicon: "helm", iconFor: helmIconFor });
 function renderArchitecture(ir, byContainer, opts = {}) {
   const spread = Math.min(1.5, ir.edges.length / Math.max(ir.nodes.length, 1));
   const layout = layoutArchitecture(ir, byContainer, {
@@ -2900,8 +3105,8 @@ function radializeLayout(layout, groupOf, size = /* @__PURE__ */ new Map()) {
 }
 
 // src/ops.ts
-import { readdirSync as readdirSync3, readFileSync as readFileSync5, existsSync as existsSync6 } from "node:fs";
-import { join as join7 } from "node:path";
+import { readdirSync as readdirSync3, readFileSync as readFileSync7, existsSync as existsSync6 } from "node:fs";
+import { join as join8 } from "node:path";
 var APPLY_TARGET_LEXICON = {
   cloudformation: "aws",
   kubectl: "k8s",
@@ -2923,11 +3128,11 @@ function discoverOps(projectDir) {
   const seen = /* @__PURE__ */ new Set();
   const out = [];
   for (const sub of ["ops", "src", "."]) {
-    const dir = join7(projectDir, sub);
+    const dir = join8(projectDir, sub);
     if (!existsSync6(dir)) continue;
     for (const f of readdirSync3(dir)) {
       if (!f.endsWith(".op.ts")) continue;
-      const content = readFileSync5(join7(dir, f), "utf8");
+      const content = readFileSync7(join8(dir, f), "utf8");
       const name = content.match(/name:\s*["'`]([^"'`]+)["'`]/)?.[1];
       if (!name || seen.has(name)) continue;
       seen.add(name);
@@ -2984,16 +3189,19 @@ function nodeDiff(json, nodeId) {
     if (drift) return { category: "drifted", changes: drift.changes ?? [] };
     const unobserved = r.unobserved?.find((u) => u.name === nodeId);
     if (unobserved) {
+      const queried = unobserved.queried ?? r.queried?.[nodeId];
       return {
         category: "unobserved",
         changes: [],
         unobservedReason: unobserved.reason,
-        ...unobserved.detail ? { unobservedDetail: unobserved.detail } : {}
+        ...unobserved.detail ? { unobservedDetail: unobserved.detail } : {},
+        ...queried ? { queried } : {}
       };
     }
     const runtimeChild = r.runtimeChildren?.find((rc) => rc.name === nodeId);
     if (runtimeChild) return { category: "runtime", changes: [], runtimeOwner: runtimeChild.owner };
-    if (r.missing?.includes(nodeId)) return { category: "missing", changes: [] };
+    if (r.missing?.includes(nodeId))
+      return { category: "missing", changes: [], ...r.queried?.[nodeId] ? { queried: r.queried[nodeId] } : {} };
     if (r.orphan?.includes(nodeId)) return { category: "orphan", changes: [] };
     if (r.disappeared?.includes(nodeId)) return { category: "disappeared", changes: [] };
     if (r.newlyObserved?.includes(nodeId)) return { category: "newlyObserved", changes: [] };
@@ -3037,6 +3245,117 @@ function classifyHealth(status) {
   if (HEALTHY.test(text)) return "healthy";
   return "unknown";
 }
+function rec2(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v) ? v : void 0;
+}
+function str3(v) {
+  return typeof v === "string" && v.length > 0 ? v : void 0;
+}
+function statusTree(o) {
+  const attrs = rec2(o.attributes);
+  if (!attrs) return void 0;
+  return rec2(attrs.status) ?? attrs;
+}
+var ARGO_HEALTH = {
+  Healthy: "healthy",
+  Degraded: "degraded",
+  Progressing: "progressing",
+  Suspended: "progressing",
+  Missing: "progressing",
+  Unknown: "unknown"
+};
+var ARGO_SYNC = {
+  Synced: "healthy",
+  OutOfSync: "progressing",
+  Unknown: "unknown"
+};
+function argoVerdict(o) {
+  if (o.type !== "K8s::Argo::Application") return void 0;
+  const tree = statusTree(o);
+  let health = str3(rec2(tree?.health)?.status);
+  let sync = str3(rec2(tree?.sync)?.status);
+  if (!health && !sync) {
+    const word = str3(o.status);
+    if (word === "READY") {
+      health = "Healthy";
+      sync = "Synced";
+    } else if (word && word in ARGO_HEALTH) health = word;
+    else if (word && word in ARGO_SYNC) sync = word;
+  }
+  const verdicts = [health ? ARGO_HEALTH[health] : void 0, sync ? ARGO_SYNC[sync] : void 0].filter(
+    (v) => v !== void 0
+  );
+  if (verdicts.length === 0) return void 0;
+  const detail = [health ? `health=${health}` : void 0, sync ? `sync=${sync}` : void 0].filter(Boolean).join(", ");
+  for (const rung of ["degraded", "progressing", "unknown"]) {
+    if (verdicts.includes(rung)) return { health: rung, detail };
+  }
+  return { health: "healthy", detail };
+}
+var FLUX_PENDING_REASON = /^(progressing|reconciling)/i;
+function readyFromConditions(tree) {
+  const conditions = tree?.conditions;
+  if (!Array.isArray(conditions)) return void 0;
+  for (const c of conditions) {
+    const cond = rec2(c);
+    if (!cond || cond.type !== "Ready") continue;
+    const status = str3(cond.status);
+    if (status !== "True" && status !== "False" && status !== "Unknown") continue;
+    return { status, reason: str3(cond.reason) };
+  }
+  return void 0;
+}
+function readyFromChantConditions(o) {
+  const conditions = rec2(o.attributes)?.conditions;
+  if (!Array.isArray(conditions)) return void 0;
+  for (const c of conditions) {
+    if (typeof c !== "string") continue;
+    const m = /^Ready(?:=([^:]*))?(?::|$)/.exec(c.trim());
+    if (!m) continue;
+    const reason = m[1]?.trim() || void 0;
+    return { status: reason && FLUX_PENDING_REASON.test(reason) ? "Unknown" : "False", reason };
+  }
+  return void 0;
+}
+function readyFromStatusWord(o) {
+  const word = str3(o.status);
+  if (!word || word === "PRESENT") return void 0;
+  if (word === "READY") return { status: "True" };
+  if (word === "NOT-READY") return { status: "False" };
+  return { status: FLUX_PENDING_REASON.test(word) ? "Unknown" : "False", reason: word };
+}
+function describeReady(ready) {
+  return `Ready=${ready.status}${ready.reason ? ` (${ready.reason})` : ""}`;
+}
+function revisionVerdict(tree) {
+  const applied = str3(tree?.lastAppliedRevision);
+  const attempted = str3(tree?.lastAttemptedRevision);
+  if (!applied || !attempted || applied === attempted) return void 0;
+  return { health: "progressing", detail: `applied ${applied}, attempted ${attempted}` };
+}
+var FLUX_TYPE_PREFIX = "K8s::Flux::";
+function fluxVerdict(o) {
+  if (!o.type?.startsWith(FLUX_TYPE_PREFIX)) return void 0;
+  const tree = statusTree(o);
+  const ready = readyFromConditions(tree) ?? readyFromChantConditions(o) ?? readyFromStatusWord(o);
+  if (ready?.status === "False") return { health: "degraded", detail: describeReady(ready) };
+  if (ready?.status === "Unknown") return { health: "progressing", detail: describeReady(ready) };
+  if (ready?.status === "True") return revisionVerdict(tree) ?? { health: "healthy", detail: describeReady(ready) };
+  const conditions = tree?.conditions;
+  const reconciling = Array.isArray(conditions) && conditions.some((c) => {
+    const cond = rec2(c);
+    return cond?.type === "Reconciling" && cond.status === "True";
+  });
+  if (reconciling) return { health: "progressing", detail: "Reconciling=True" };
+  if (!str3(o.status) || o.status === "PRESENT") {
+    return { health: "progressing", detail: "no Ready condition yet" };
+  }
+  return void 0;
+}
+function classifyObservedHealth(observed) {
+  if (!observed) return { health: "unknown" };
+  return argoVerdict(observed) ?? fluxVerdict(observed) ?? { health: classifyHealth(observed.status) };
+}
 
 // src/apply.ts
 var PROGRESS_EVENT_TYPES = /* @__PURE__ */ new Set([
@@ -3323,23 +3642,23 @@ var OpRunner = class {
 
 // src/substrates.ts
 import { spawn as spawn3 } from "node:child_process";
-import { existsSync as existsSync7, readFileSync as readFileSync6 } from "node:fs";
-import { join as join8 } from "node:path";
+import { existsSync as existsSync7, readFileSync as readFileSync8 } from "node:fs";
+import { join as join9 } from "node:path";
 import { platform } from "node:os";
 function probe(cmd, args) {
-  return new Promise((resolve4) => {
+  return new Promise((resolve5) => {
     let out = "";
     let proc;
     try {
       proc = spawn3(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
     } catch {
-      resolve4({ code: 127, out: "" });
+      resolve5({ code: 127, out: "" });
       return;
     }
     proc.stdout.on("data", (d) => out += d);
     proc.stderr.on("data", (d) => out += d);
-    proc.on("error", () => resolve4({ code: 127, out }));
-    proc.on("close", (code) => resolve4({ code: code ?? 1, out }));
+    proc.on("error", () => resolve5({ code: 127, out }));
+    proc.on("close", (code) => resolve5({ code: code ?? 1, out }));
   });
 }
 async function dockerAvailable() {
@@ -3352,11 +3671,11 @@ async function dockerRunning(nameFilter) {
   return out.split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
 }
 function scriptBringUp(projectDir, relPath, label) {
-  return existsSync7(join8(projectDir, relPath)) ? { label, cmd: "bash", args: [relPath] } : void 0;
+  return existsSync7(join9(projectDir, relPath)) ? { label, cmd: "bash", args: [relPath] } : void 0;
 }
 function projectLexicons(projectDir) {
   try {
-    const src = readFileSync6(join8(projectDir, "chant.config.ts"), "utf-8");
+    const src = readFileSync8(join9(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]);
@@ -3406,7 +3725,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 (!existsSync7(join8(projectDir, marker))) continue;
+    if (!existsSync7(join9(projectDir, marker))) continue;
     const c = docker ? await dockerRunning(name) : [];
     const d = dep(c.length > 0, "container up", "on-demand (pipeline run)");
     subs.push({
@@ -3436,7 +3755,7 @@ async function detectSubstrates(projectDir, preview = false, boundContext) {
       detail: endpoint ? `targeting ${endpoint}` : "real Fly (FLY_FLAPS_BASE_URL unset)"
     });
   }
-  if (existsSync7(join8(projectDir, ".github", "workflows"))) {
+  if (existsSync7(join9(projectDir, ".github", "workflows"))) {
     const gh = await probe("gh", ["auth", "status"]);
     const ready = gh.code === 0;
     subs.push({
@@ -3449,7 +3768,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(readFileSync6(join8(projectDir, "chant.config.ts"), "utf-8"));
+      hasProfiles = /temporal\s*:\s*\{[\s\S]{0,400}?profiles\s*:/.test(readFileSync8(join9(projectDir, "chant.config.ts"), "utf-8"));
     } catch {
     }
     subs.push({
@@ -3566,6 +3885,13 @@ var firstLine = (e) => {
   const m = msg.match(/exited \d+:\s*([\s\S]*)/);
   return (m ? m[1] : msg).split("\n")[0].trim().slice(0, 160);
 };
+function namespaceRuntimeOwners(name, ir) {
+  const own = new Set(ir.nodes.map((n) => n.id));
+  for (const n of ir.nodes) {
+    if (n.runtimeOwner && own.has(n.runtimeOwner)) n.runtimeOwner = `${name}/${n.runtimeOwner}`;
+  }
+  return ir;
+}
 async function composeEstateOverlay(projectDirs, opts, classify) {
   const names = shortStackNames(projectDirs);
   const unobserved = [];
@@ -3575,7 +3901,7 @@ async function composeEstateOverlay(projectDirs, opts, classify) {
     projectDirs.map(async (dir, i) => {
       const name = names[i];
       try {
-        stacks[i] = { name, ir: classify(await graphIr(dir, { ...opts, live: true, overlay: true })) };
+        stacks[i] = { name, ir: namespaceRuntimeOwners(name, classify(await graphIr(dir, { ...opts, live: true, overlay: true }))) };
       } catch (err) {
         const reason = firstLine(err);
         try {
@@ -3602,7 +3928,7 @@ async function composeEstateOverlay(projectDirs, opts, classify) {
 
 // src/events.ts
 import { watch, existsSync as existsSync8 } from "node:fs";
-import { join as join9 } from "node:path";
+import { join as join10 } from "node:path";
 var Broadcaster = class {
   listeners = /* @__PURE__ */ new Set();
   subscribe(fn) {
@@ -3620,7 +3946,7 @@ var Broadcaster = class {
 };
 var IGNORE = /(^|[\\/])(node_modules|dist|\.git)([\\/]|$)/;
 function watchSource(projectDir, onChange, debounceMs = 200) {
-  const dir = existsSync8(join9(projectDir, "src")) ? join9(projectDir, "src") : projectDir;
+  const dir = existsSync8(join10(projectDir, "src")) ? join10(projectDir, "src") : projectDir;
   let timer;
   const watcher = watch(dir, { recursive: true }, (_event, file) => {
     const name = typeof file === "string" ? file : "";
@@ -3728,19 +4054,21 @@ import { renderMorphHtml, layoutIr as layoutIr2 } from "@intentius/pinhole";
 function safeJson(value) {
   return JSON.stringify(value).replace(/</g, "\\u003c");
 }
+var LANES_MONO = `ui-monospace, "SF Mono", SFMono-Regular, "Cascadia Code", "JetBrains Mono", "IBM Plex Mono", Menlo, Consolas, monospace`;
 var LANES_CSS = `
-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); }
+body { background: var(--bg, #1e1e2e); color: var(--fg, #cdd6f4); padding-bottom: 150px; }
+#behold-lanes { position: fixed; left: 0; right: 0; bottom: 0; background: var(--bg, #1e1e2e);
+  border-top: 1px solid var(--line, #3b3c4a); padding: 8px 12px 10px; font: 11px/1.5 ${LANES_MONO}; color: var(--muted, #777a8c); }
 #behold-lanes .hd { display: flex; gap: 14px; align-items: baseline; margin-bottom: 4px; }
-#behold-lanes .hd .rt { color: var(--foreign, #d29922); }
-#behold-lanes .hd a { color: var(--pending, #58a6ff); text-decoration: none; margin-left: auto; }
+#behold-lanes .hd .rt { color: var(--foreign, #f9e2af); }
+#behold-lanes .hd a { color: var(--pending, #89b4fa); 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: 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); }`;
+  background: var(--panel, #2e2f40); border: 1px solid var(--rule, #4e4f64); border-radius: 3px; padding: 10px 12px; font: 11px/1.5 ${LANES_MONO};
+  color: var(--fg, #cdd6f4); display: none; }
+#behold-diff h4 { margin: 0 0 6px; font: 600 10.5px/1.4 ui-sans-serif, system-ui, sans-serif;
+  text-transform: uppercase; letter-spacing: .07em; color: var(--muted, #777a8c); }
+#behold-diff .a { color: var(--managed, #a6e3a1); } #behold-diff .r { color: var(--degraded, #f38ba8); } #behold-diff .c { color: var(--foreign, #f9e2af); }`;
 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>
@@ -3766,7 +4094,7 @@ const LF = ${safeJson(frames)};
     const inNow = now !== undefined, inPrev = prev !== undefined;
     return inNow !== inPrev || (inNow && inPrev && now !== prev);
   }
-  const color = s => s === "good" ? css("--managed", "#3fb950") : s === "warn" ? css("--foreign", "#d29922") : s === "accent" ? css("--pending", "#58a6ff") : css("--edge", "#6e7681");
+  const color = s => s === "good" ? css("--managed", "#a6e3a1") : s === "warn" ? css("--foreign", "#f9e2af") : s === "accent" ? css("--pending", "#89b4fa") : css("--edge", "#56596d");
 
   function draw() {
     const dpr = window.devicePixelRatio || 1;
@@ -3775,22 +4103,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] ? 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();
+      c.fillStyle = offset[s] ? css("--foreign", "#f9e2af") : css("--muted", "#777a8c"); c.textAlign = "left"; c.fillText(s, 8, y + 4);
+      c.strokeStyle = css("--line", "#3b3c4a"); 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 ? css("--fg", "#f0f6fc") : changed ? color(mode(f, s)) : css("--line", "#30363d");
+        c.fillStyle = hi ? css("--fg", "#cdd6f4") : changed ? color(mode(f, s)) : css("--line", "#3b3c4a");
         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 = css("--pending", "#58a6ff"); c.lineWidth = 1.5;
+    const px = baseX(cur); c.strokeStyle = css("--pending", "#89b4fa"); 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 = css("--foreign", "#d29922"); c.setLineDash([3,3]);
+    if (pair != null) { const qx = baseX(pair); c.strokeStyle = css("--foreign", "#f9e2af"); c.setLineDash([3,3]);
       c.beginPath(); c.moveTo(qx, padT - 2); c.lineTo(qx, padT + subs.length * rowH); c.stroke(); c.setLineDash([]); }
-    c.fillStyle = css("--fg", "#e6edf3"); c.textAlign = "center"; c.fillText(LF[cur].name, px, padT + subs.length * rowH + 16);
+    c.fillStyle = css("--fg", "#cdd6f4"); 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";
@@ -3896,7 +4224,7 @@ async function emulatorDown(projectDir) {
 }
 
 // src/server.ts
-var webRoot = join10(dirname3(fileURLToPath(import.meta.url)), "..", "web");
+var webRoot = join11(dirname4(fileURLToPath3(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;
@@ -3945,8 +4273,8 @@ function tierFailure(tier, message) {
 }
 function beholdVersion() {
   try {
-    const here = dirname3(fileURLToPath(import.meta.url));
-    return JSON.parse(readFileSync7(join10(here, "..", "package.json"), "utf8")).version ?? "unknown";
+    const here = dirname4(fileURLToPath3(import.meta.url));
+    return JSON.parse(readFileSync9(join11(here, "..", "package.json"), "utf8")).version ?? "unknown";
   } catch {
     return "unknown";
   }
@@ -4007,13 +4335,14 @@ function createApp(cfg, broadcaster = new Broadcaster(), frames = new FrameBuffe
       return void 0;
     }
   };
+  const estateSourceRoots = async (opts) => (await Promise.all((cfg.projectDirs ?? []).map(async (dir) => [await graphPath(dir, opts), dir]))).flat();
   app.get("/healthz", (c) => c.json({ ok: true, projectDir: cfg.projectDir, env: cfg.env ?? null, frames: frames.size }));
   app.get("/api/frames", (c) => c.json({ frames: frames.summaries() }));
   app.get("/lanes", (c) => {
     const all = frames.all();
     if (all.length < 2) {
       return c.html(
-        `<!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>`
+        `<!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,#1e1e2e);color:var(--muted,#777a8c);padding:2rem"><h3 style="color:var(--fg,#cdd6f4)">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,#cdd6f4)">\u21BB Refresh</b> (captures the current live state), run a <b style="color:var(--fg,#cdd6f4)">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()));
@@ -4079,8 +4408,8 @@ 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 = join10(cfg.projectDir, "scripts/local/local-down.sh");
-    const up = join10(cfg.projectDir, "scripts/local/local-up.sh");
+    const down = join11(cfg.projectDir, "scripts/local/local-down.sh");
+    const up = join11(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);
     }
@@ -4160,7 +4489,7 @@ function createApp(cfg, broadcaster = new Broadcaster(), frames = new FrameBuffe
     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"))) {
+    if (!existsSync9(join11(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);
@@ -4232,10 +4561,31 @@ function createApp(cfg, broadcaster = new Broadcaster(), frames = new FrameBuffe
       let mode;
       let metaEnv = cfg.env ?? null;
       if (multi) {
-        ir = await composeEstate(cfg.projectDirs, opts);
+        ir = await composeEstate(cfg.projectDirs, logical ? { ...opts, detail: 3 } : opts);
         ir = addValueMatchEdges(ir);
         ir = addK8sDeclaredEdges(ir);
-        ir = addClusterAnchorEdges(ir, await boundK8sContext(metaEnv ?? void 0));
+        const estateContext = await boundK8sContext(metaEnv ?? void 0);
+        ir = addClusterAnchorEdges(ir, estateContext);
+        if (logical) {
+          const logicalBefore = ir.nodes.length;
+          const { ir: projected, byContainer } = projectTopology(ir, metaEnv ?? void 0, estateContext, await estateSourceRoots(opts));
+          const { svg: svg2 } = renderArchitecture(projected, byContainer);
+          const logicalNote = notesFor("logical", projected, void 0, logicalBefore);
+          return c.json({
+            ir: projected,
+            svg: svg2,
+            byContainer,
+            meta: {
+              projectDir: cfg.projectDir,
+              env: metaEnv,
+              tier: opts.tier ?? null,
+              target: opts.target ?? null,
+              mode: "logical",
+              estate: cfg.projectDirs.length,
+              ...logicalNote ? { note: logicalNote } : {}
+            }
+          });
+        }
       } else if (components) {
         ir = await componentGraphIr(cfg.projectDir, opts);
         const env = opts.env ?? cfg.env;
@@ -4271,13 +4621,13 @@ 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"))) {
+      if (!multi && !components && !logical && !opts.lens && ir.nodes.length === 0 && !existsSync9(join11(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 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 estateLensNote = multi && components ? "the components 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,
@@ -4379,22 +4729,36 @@ function createApp(cfg, broadcaster = new Broadcaster(), frames = new FrameBuffe
     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);
+        const detail = logical ? 3 : query.detail;
+        const est = await composeEstateOverlay(cfg.projectDirs, { ...tierTargetOpts(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);
+        const composed = est.ir;
+        let ir2 = runtime ? attachRuntimeContainment(composed) : pruneRuntimeChildren(composed);
+        if ((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 boundContext2 = await boundK8sContext(env);
+        ir2 = addClusterAnchorEdges(ir2, boundContext2);
         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 ");
+        if (logical) {
+          const logicalBefore = ir2.nodes.length;
+          const { ir: projected, byContainer } = projectTopology(ir2, env, boundContext2, await estateSourceRoots(query));
+          const { svg: svg3 } = renderArchitecture(projected, byContainer);
+          const note3 = [notesFor("logical", projected, void 0, logicalBefore), coverNote, namespaceMismatchNote(projected.nodes)].filter(Boolean).join(" \xB7 ");
+          return c.json({
+            ir: projected,
+            svg: svg3,
+            byContainer,
+            meta: { projectDir: cfg.projectDir, env, mode: "logical", estate: est.total, ...note3 ? { note: note3 } : {} }
+          });
+        }
+        const { svg: svg2 } = renderGraph(ir2, { boxes: runtime ? "byContainer" : "byStack" });
+        const note2 = [coverNote, namespaceMismatchNote(ir2.nodes), runtime ? notesFor("runtime", ir2) : void 0].filter(Boolean).join(" \xB7 ");
         return c.json({
           ir: ir2,
           svg: svg2,
@@ -4500,10 +4864,12 @@ function createApp(cfg, broadcaster = new Broadcaster(), frames = new FrameBuffe
     const nodes = {};
     for (const id of ids) {
       const observed = nodeObserved(parsed, id);
+      const verdict = classifyObservedHealth(observed);
       nodes[id] = {
         observed,
         diff: nodeDiff(parsed, id),
-        health: classifyHealth(observed?.status),
+        health: verdict.health,
+        ...verdict.detail ? { healthDetail: verdict.detail } : {},
         // Field-level (per-manager) drift (#87, chant#1181) — null when no
         // lexicon in this diff carries a `deep` section at all.
         fieldDrift: nodeFieldDrift(parsed, id)
@@ -4527,12 +4893,14 @@ function createApp(cfg, broadcaster = new Broadcaster(), frames = new FrameBuffe
       return c.json({ error: "diff output was not JSON \u2014 chant may predate --live --json (needs 0.18.7+)" }, 500);
     }
     const observed = nodeObserved(parsed, node);
+    const verdict = classifyObservedHealth(observed);
     return c.json({
       node,
       env,
       diff: nodeDiff(parsed, node),
       observed,
-      health: classifyHealth(observed?.status),
+      health: verdict.health,
+      ...verdict.detail ? { healthDetail: verdict.detail } : {},
       // Field-level (per-manager) drift (#87, chant#1181) — null when no
       // lexicon in this diff carries a `deep` section at all.
       fieldDrift: nodeFieldDrift(parsed, node)
@@ -4583,7 +4951,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: join10(rel, "index.html") }));
+  app.get("/", serveStatic({ path: join11(rel, "index.html") }));
   return app;
 }
 async function startServer(cfg) {
@@ -4612,7 +4980,7 @@ async function startServer(cfg) {
     }
   }
   for (const dir of cfg.projectDirs ?? [cfg.projectDir]) {
-    if (existsSync9(join10(dir, "chant.config.ts"))) addRecent(dir);
+    if (existsSync9(join11(dir, "chant.config.ts"))) addRecent(dir);
   }
   const broadcaster = new Broadcaster();
   const frames = new FrameBuffer();
@@ -4718,19 +5086,19 @@ async function startServer(cfg) {
 }
 
 // src/demos.ts
-import { readFileSync as readFileSync8 } from "node:fs";
-import { join as join11 } from "node:path";
+import { readFileSync as readFileSync10 } from "node:fs";
+import { join as join12 } from "node:path";
 import { spawnSync } from "node:child_process";
 function loadDemoRegistry(pkgRoot) {
   let raw;
   try {
-    raw = JSON.parse(readFileSync8(join11(pkgRoot, "demos.json"), "utf8"));
+    raw = JSON.parse(readFileSync10(join12(pkgRoot, "demos.json"), "utf8"));
   } catch {
     return [];
   }
-  const list = raw?.demos;
-  if (!Array.isArray(list)) return [];
-  return list.filter((e) => {
+  const list3 = raw?.demos;
+  if (!Array.isArray(list3)) return [];
+  return list3.filter((e) => {
     const d = e;
     if (!d || typeof d.name !== "string" || !d.name || typeof d.description !== "string") return false;
     if (d.source === "bundled") {
@@ -4754,9 +5122,9 @@ function missingRequirements(entry) {
 }
 
 // src/export.ts
-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";
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2, copyFileSync, readFileSync as readFileSync11, readdirSync as readdirSync4 } from "node:fs";
+import { join as join13, dirname as dirname5, basename } from "node:path";
+import { fileURLToPath as fileURLToPath4 } from "node:url";
 var LENS_PARAMS = ["components", "detail", "env", "logical", "radial", "tier"];
 function canonicalKey(path, params) {
   const flat = params.get("components") === "1" || params.get("logical") === "1";
@@ -4803,7 +5171,7 @@ function captureKeys(axes) {
   return [...keys];
 }
 function webDir() {
-  return join12(dirname4(fileURLToPath2(import.meta.url)), "..", "web");
+  return join13(dirname5(fileURLToPath4(import.meta.url)), "..", "web");
 }
 function workerName(project, override) {
   const raw = override ?? `behold-${basename(project)}`;
@@ -4814,7 +5182,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 = join12(outDir, "snapshots");
+  const snapDir = join13(outDir, "snapshots");
   mkdirSync2(snapDir, { recursive: true });
   const keyToFile = {};
   let ok = 0;
@@ -4823,7 +5191,7 @@ async function runExport(cfg, outDir, opts = {}) {
     const res = await app.request(key);
     const body = await res.text();
     const file = slug(key);
-    writeFileSync2(join12(snapDir, file), body);
+    writeFileSync2(join13(snapDir, file), body);
     keyToFile[key] = `snapshots/${file}`;
     if (res.ok) ok++;
     else failed++;
@@ -4835,21 +5203,21 @@ async function runExport(cfg, outDir, opts = {}) {
     axes,
     keyToFile
   };
-  writeFileSync2(join12(outDir, "manifest.json"), JSON.stringify(manifest, null, 2));
-  const html = readFileSync9(join12(webDir(), "index.html"), "utf8").replace(
+  writeFileSync2(join13(outDir, "manifest.json"), JSON.stringify(manifest, null, 2));
+  const html = readFileSync11(join13(webDir(), "index.html"), "utf8").replace(
     /<\/head>/i,
     `  <script>window.__BEHOLD_STATIC__ = true;</script>
   </head>`
   );
-  writeFileSync2(join12(outDir, "index.html"), html);
+  writeFileSync2(join13(outDir, "index.html"), html);
   for (const f of readdirSync4(webDir())) {
     if (f === "index.html") continue;
-    copyFileSync(join12(webDir(), f), join12(outDir, f));
+    copyFileSync(join13(webDir(), f), join13(outDir, f));
   }
-  writeFileSync2(join12(outDir, "README.md"), BUNDLE_README);
+  writeFileSync2(join13(outDir, "README.md"), BUNDLE_README);
   const name = workerName(cfg.projectDir, opts.name);
   writeFileSync2(
-    join12(outDir, "wrangler.jsonc"),
+    join13(outDir, "wrangler.jsonc"),
     JSON.stringify(
       { $schema: "node_modules/wrangler/config-schema.json", name, compatibility_date: "2025-06-01", assets: { directory: "." } },
       null,
@@ -4896,15 +5264,239 @@ It's just files \u2014 GitHub Pages, S3, nginx, or Cloudflare Pages
 (\`wrangler pages deploy .\`) all work.
 `;
 
+// src/doctor.ts
+import { relative as relative2, resolve as resolve3 } from "node:path";
+var list2 = (xs) => xs.join(", ");
+var EMPTY_KUBECONFIG = { contexts: /* @__PURE__ */ new Map(), servers: /* @__PURE__ */ new Map() };
+function summarize(xs, max = 4) {
+  return xs.length <= max ? list2(xs) : `${list2(xs.slice(0, max))}, +${xs.length - max} more`;
+}
+function labelFor(root, target, estate) {
+  if (!estate) return "";
+  const rel = relative2(root, target);
+  return `${rel || "."}: `;
+}
+function chantCheck(root, targets, estate) {
+  const floor = chantFloor();
+  const resolutions = targets.map((t) => ({ target: t, res: resolveChant(t) }));
+  const missing = resolutions.filter(({ res }) => res.source !== "project");
+  const describe = ({ target, res }) => `${labelFor(root, target, estate)}${res.source === "project" ? `chant ${res.version ?? "(unknown version)"}` : "no chant installed"}`;
+  if (missing.length) {
+    return {
+      name: "chant",
+      status: "fail",
+      detail: `${list2(resolutions.map(describe))} \u2014 behold shells the project's own chant`,
+      fix: `Run \`npm install\` in ${list2(missing.map(({ target }) => relative2(root, target) || target))}`
+    };
+  }
+  const stale = resolutions.filter(({ res }) => !meetsFloor(res.version, floor));
+  const versions = list2(resolutions.map(describe));
+  if (stale.length) {
+    return {
+      name: "chant",
+      status: "warn",
+      detail: `${versions} \u2014 below behold's floor ${floor}`,
+      fix: "Bump @intentius/chant in the project (`npm install @intentius/chant@latest`) \u2014 older versions observe less."
+    };
+  }
+  return { name: "chant", status: "pass", detail: `${versions}${floor ? ` (behold's floor ${floor})` : ""}` };
+}
+function lexiconCheck(root, declared, estate) {
+  const missing = [];
+  const found = [];
+  for (const [target, lexicons] of declared) {
+    const label = labelFor(root, target, estate);
+    for (const r of resolveLexicons(target, lexicons)) {
+      (r.installed ? found : missing).push(`${label}${r.lexicon}${r.installed && r.version ? ` ${r.version}` : ""}`);
+    }
+  }
+  if (missing.length) {
+    return {
+      name: "lexicons",
+      status: "fail",
+      detail: `declared but not installed: ${list2(missing)}${found.length ? ` (installed: ${list2(found)})` : ""}`,
+      fix: "Run `npm install` in the project \u2014 chant can't graph source importing a lexicon it can't resolve."
+    };
+  }
+  if (!found.length) {
+    return { name: "lexicons", status: "pass", detail: "none declared" };
+  }
+  return { name: "lexicons", status: "pass", detail: `${found.length} installed: ${list2(found)}` };
+}
+function envCheck(envs, serveArg) {
+  if (!envs.length) {
+    return {
+      name: "envs",
+      status: "warn",
+      detail: "no environments declared \u2014 the declared graph serves, but there is no live overlay to pick",
+      fix: "Declare `environments` (or `k8s.profiles`) in chant.config.ts, then serve with `--env <name>`."
+    };
+  }
+  return { name: "envs", status: "pass", detail: `${list2(envs)} \u2014 \`behold serve ${serveArg} --env ${envs[0]}\` for the live overlay` };
+}
+function kubeCheck(lexicons, profiles, envs, kubeconfig) {
+  if (!lexicons.includes("k8s") && !lexicons.includes("helm")) {
+    return { name: "kube", status: "pass", detail: "no k8s or helm lexicon \u2014 no cluster binding to check" };
+  }
+  const ambient = kubeconfig.currentContext;
+  if (!kubeconfig.contexts.size) {
+    return {
+      name: "kube",
+      status: "warn",
+      detail: "no kubeconfig readable (kubectl absent, or it has no contexts) \u2014 the declared graph still serves",
+      fix: "Install kubectl and point KUBECONFIG at your cluster, or run `behold demo k8s` for a throwaway k3d one."
+    };
+  }
+  const bound = envs.filter((e) => profiles[e]?.context);
+  if (!bound.length) {
+    return {
+      name: "kube",
+      status: "warn",
+      detail: `no k8s.profiles binding \u2014 chant falls back to the ambient current-context${ambient ? ` (${ambient})` : " (none set)"}`,
+      fix: "Declare `k8s.profiles.<env>.context` in chant.config.ts so the cluster the reads hit is explicit, not ambient."
+    };
+  }
+  const lines = [];
+  const unresolved = [];
+  const mismatched = [];
+  for (const env of bound) {
+    const context = profiles[env].context;
+    const target = resolveK8sTarget(profiles, env, kubeconfig);
+    if (!target) {
+      unresolved.push(`${env}: ${context}`);
+      continue;
+    }
+    lines.push(`${env}: ${target.label} at ${target.endpoint}`);
+    if (ambient && ambient !== target.label) mismatched.push(`${env}: ${target.label}`);
+  }
+  if (unresolved.length) {
+    return {
+      name: "kube",
+      status: "warn",
+      detail: `context not in the kubeconfig \u2014 ${list2(unresolved)}${lines.length ? `; bound: ${list2(lines)}` : ""}`,
+      fix: `Add the context to your kubeconfig, or point k8s.profiles at one you have (${summarize([...kubeconfig.contexts.keys()])}).`
+    };
+  }
+  if (mismatched.length) {
+    return {
+      name: "kube",
+      status: "warn",
+      detail: `bound ${list2(lines)}, but the ambient current-context is ${ambient} \u2014 chant refuses a live read on a mismatch`,
+      fix: `Run \`kubectl config use-context ${mismatched[0].split(": ")[1]}\` before the live overlay.`
+    };
+  }
+  return { name: "kube", status: "pass", detail: `bound ${list2(lines)}` };
+}
+function substrateCheck(substrates) {
+  if (!substrates.length) return { name: "substrates", status: "pass", detail: "none needed by this project" };
+  const detail = list2(substrates.map((s) => `${s.label} ${s.status}`));
+  const down = substrates.filter((s) => s.status === "down" || s.status === "blocked");
+  if (!down.length) return { name: "substrates", status: "pass", detail };
+  const named = down.map((s) => `${s.label} (${s.bringUp ? `${s.bringUp.cmd} ${s.bringUp.args.join(" ")}` : s.detail})`);
+  return {
+    name: "substrates",
+    status: "warn",
+    detail,
+    fix: `Bring up: ${list2(named)} \u2014 or \`behold serve <dir> --local\`, which boots the project's own emulators (needs Docker).`
+  };
+}
+function opsCheck(root, ops, chantSource, estate) {
+  const mcp = chantSource === "project" ? "chant MCP available (the project's own chant)" : "chant MCP unavailable until the project's chant is installed";
+  if (!ops.length) {
+    return {
+      name: "ops",
+      status: "warn",
+      detail: `no committed Ops (*.op.ts) \u2014 behold can show drift but has nothing to trigger; ${mcp}`,
+      fix: "Add an ApplyOp (code to cloud) or ReconcileOp (cloud to PR) under ops/ \u2014 behold triggers your Ops, it holds no apply creds."
+    };
+  }
+  const names = ops.map((o) => `${labelFor(root, o.dir, estate)}${o.name} (${o.kind})`);
+  return { name: "ops", status: "pass", detail: `${ops.length} committed: ${list2(names)}; ${mcp}` };
+}
+async function diagnose(dir, probes = {}) {
+  const root = resolve3(dir);
+  const shape = detectProjectShape(root);
+  const behold = beholdVersion();
+  if (shape.kind === "none") {
+    return {
+      behold,
+      dir: root,
+      kind: "none",
+      ok: false,
+      checks: [
+        {
+          name: "project",
+          status: "fail",
+          detail: `no chant.config.ts here, and no estate members declared (.behold.json \`members\`, or npm workspaces)`,
+          fix: "Point behold at a chant project (`behold doctor <dir>`), or run `behold demo` for a bundled working example."
+        }
+      ]
+    };
+  }
+  const estate = shape.kind === "estate";
+  const members = (shape.members ?? []).map((m) => resolve3(root, m));
+  const targets = estate ? members : [root];
+  const primary = targets[0];
+  const projectCheck = estate ? {
+    name: "project",
+    status: "pass",
+    detail: `estate of ${members.length} projects (${shape.membersFrom === "behold-config" ? ".behold.json members" : "npm workspaces"}): ${list2(
+      members.map((m) => relative2(root, m))
+    )}`
+  } : { name: "project", status: "pass", detail: `chant project (${relative2(root, shape.configFile)})` };
+  const infos = await Promise.all(targets.map(async (t) => ({ target: t, info: await detectProject(t) })));
+  const declared = new Map(infos.map(({ target, info }) => [target, info.lexicons]));
+  const lexicons = [...new Set(infos.flatMap(({ info }) => info.lexicons))];
+  const envs = [...new Set(infos.flatMap(({ info }) => info.environments))];
+  const profiles = {};
+  for (const { info } of infos) for (const [env, p] of Object.entries(info.k8sProfiles ?? {})) profiles[env] ??= p;
+  const kubeconfig = lexicons.includes("k8s") || lexicons.includes("helm") ? await (probes.loadKubeconfig ?? loadKubeconfig)() : EMPTY_KUBECONFIG;
+  const kube = kubeCheck(lexicons, profiles, envs, kubeconfig);
+  const boundContext = resolveK8sTarget(profiles, envs[0], kubeconfig)?.label;
+  const substrates = await (probes.detectSubstrates ?? detectSubstrates)(primary, false, boundContext);
+  const checks = [
+    projectCheck,
+    chantCheck(root, targets, estate),
+    lexiconCheck(root, declared, estate),
+    // An estate root is not itself servable — the hint has to name its members
+    // (`behold serve a b c`, #31), which is what a stranger would otherwise
+    // discover by having the root serve nothing.
+    envCheck(envs, estate ? shape.members.map((m) => `${dir.replace(/\/$/, "")}/${m}`).join(" ") : dir),
+    kube,
+    substrateCheck(substrates),
+    opsCheck(root, discoverEstateOps(targets), resolveChant(primary).source, estate)
+  ];
+  return { behold, dir: root, kind: shape.kind, ok: !checks.some((c) => c.status === "fail"), checks };
+}
+function formatReport(report) {
+  const lines = [`behold doctor ${report.behold} \u2014 ${report.dir}`, ""];
+  for (const c of report.checks) {
+    lines.push(`  ${c.status.padEnd(4)}  ${c.name.padEnd(10)}  ${c.detail}`);
+    if (c.fix) lines.push(`        ${"fix".padEnd(10)}  ${c.fix}`);
+  }
+  const tally = (s) => report.checks.filter((c) => c.status === s).length;
+  lines.push("", `  ${tally("pass")} pass, ${tally("warn")} warn, ${tally("fail")} fail`, "");
+  return lines.join("\n");
+}
+
 // src/cli.ts
 var USAGE = `behold \u2014 a live control plane on chant (read-only core)
 
 Usage:
   behold demo [name] [target-dir] [--port <n>] [--list]
+  behold doctor [project-dir] [--json]
   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]
 
+  doctor  Why won't this project serve well? A read-only diagnosis of
+          everything behold needs \u2014 the project's kind, its own chant install
+          and version, declared lexicons, the envs the picker will infer, the
+          kube context chant binds versus the ambient one, substrate
+          readiness, committed Ops \u2014 each line pass/warn/fail with a one-line
+          fix. Defaults to the current directory. Exits 0 iff nothing failed;
+          --json for machines. Starts no server and changes nothing.
+
   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-
@@ -4965,6 +5557,8 @@ Options:
                       names, unlike --local; kept separate because Loom's own
                       \`scripts/local/local-up.sh\` Floci setup clashes on :4566
                       with chant's generic \`chant emulator up\`.
+  --json              doctor only: the report as JSON (stable keys) instead of
+                      the console lines \u2014 the AGENTS.md audience.
   --out <dir>         export only: output directory (default ./behold-export).
   --name <worker>     export only: Cloudflare Worker name in the generated
                       wrangler.jsonc.
@@ -4985,6 +5579,10 @@ async function run3(argv) {
     await runDemo(rest);
     return;
   }
+  if (cmd === "doctor") {
+    await runDoctor(rest);
+    return;
+  }
   if (cmd === "preview") {
     await runPreview(rest);
     return;
@@ -5048,7 +5646,7 @@ ${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) => resolve3(d));
+  const dirs = projectDirs.map((d) => resolve4(d));
   for (const d of dirs) warnIfNotChantProject(d);
   await startServer({
     projectDir: dirs[0],
@@ -5062,15 +5660,47 @@ ${USAGE}`);
   });
 }
 function warnIfNotChantProject(dir) {
-  if (existsSync10(join13(dir, "chant.config.ts"))) return;
+  const shape = detectProjectShape(dir);
+  if (shape.kind === "project") return;
+  if (shape.kind === "estate") {
+    process.stderr.write(
+      `behold: warning \u2014 ${dir} is an estate root, not a chant project itself.
+        Serve its members composed: behold serve ${shape.members.map((m) => join14(dir, m)).join(" ")}
+`
+    );
+    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).
+        \`behold doctor ${dir}\` says what's missing. No project yet? \`behold demo\` serves a bundled working example (needs Docker).
 `
   );
 }
+async function runDoctor(rest) {
+  let json = false;
+  let dirArg;
+  for (const a of rest) {
+    if (a === "--json") json = true;
+    else if (a === "-h" || a === "--help") return void process.stdout.write(USAGE);
+    else if (!a.startsWith("-")) dirArg = a;
+    else {
+      process.stderr.write(`behold doctor: unexpected argument '${a}'
+`);
+      process.exit(2);
+    }
+  }
+  const dir = dirArg ?? ".";
+  if (!existsSync10(resolve4(dir))) {
+    process.stderr.write(`behold doctor: no such directory: ${resolve4(dir)}
+`);
+    process.exit(2);
+  }
+  const report = await diagnose(dir);
+  process.stdout.write(json ? JSON.stringify(report, null, 2) + "\n" : formatReport(report));
+  if (!report.ok) process.exitCode = 1;
+}
 async function runDemo(rest) {
-  const pkgRoot = join13(dirname5(fileURLToPath3(import.meta.url)), "..");
+  const pkgRoot = join14(dirname6(fileURLToPath5(import.meta.url)), "..");
   const registry = loadDemoRegistry(pkgRoot);
   let port = 4600;
   let name;
@@ -5122,12 +5752,12 @@ async function runDemo(rest) {
 `);
     process.exit(2);
   }
-  const target = resolve3(
-    dirArg ?? (entry.name === "writes" && existsSync10("behold-demo") ? "behold-demo" : join13("behold-demos", entry.name))
+  const target = resolve4(
+    dirArg ?? (entry.name === "writes" && existsSync10("behold-demo") ? "behold-demo" : join14("behold-demos", entry.name))
   );
   if (!existsSync10(target)) {
     if (entry.source === "bundled") {
-      const bundled = join13(pkgRoot, entry.dir);
+      const bundled = join14(pkgRoot, entry.dir);
       if (!existsSync10(bundled)) {
         process.stderr.write(`behold demo ${entry.name}: this install has no bundled ${entry.dir}
 `);
@@ -5137,7 +5767,7 @@ async function runDemo(rest) {
 `);
       cpSync(bundled, target, {
         recursive: true,
-        filter: (src) => !relative2(bundled, src).split(sep).includes("node_modules")
+        filter: (src) => !relative3(bundled, src).split(sep).includes("node_modules")
       });
     } else {
       process.stdout.write(`behold demo ${entry.name} \u2192 cloning ${entry.repo} to ${target}
@@ -5153,7 +5783,7 @@ async function runDemo(rest) {
     process.stdout.write(`behold demo ${entry.name} \u2192 reusing ${target}
 `);
   }
-  if (existsSync10(join13(target, "package.json")) && !existsSync10(join13(target, "node_modules"))) {
+  if (existsSync10(join14(target, "package.json")) && !existsSync10(join14(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" });
@@ -5175,7 +5805,7 @@ async function runDemo(rest) {
   }
   process.stdout.write(`behold demo ${entry.name} \u2192 serving. Blue = declared; Deploy turns it green.
 `);
-  const serveDirs = entry.serve.dirs?.length ? entry.serve.dirs.map((d) => join13(target, d)) : [target];
+  const serveDirs = entry.serve.dirs?.length ? entry.serve.dirs.map((d) => join14(target, d)) : [target];
   const serveArgs = ["serve", ...serveDirs, "--port", String(port)];
   if (entry.serve.local) serveArgs.push("--local");
   if (entry.serve.env) serveArgs.push("--env", entry.serve.env);
@@ -5203,7 +5833,7 @@ async function runPreview(rest) {
     process.stderr.write("behold preview: --port must be a number\n");
     process.exit(2);
   }
-  const projectDir = resolve3(dirArg ?? process.cwd());
+  const projectDir = resolve4(dirArg ?? process.cwd());
   if (!existsSync10(projectDir)) {
     process.stderr.write(`behold preview: project not found at ${projectDir}
 `);
@@ -5224,21 +5854,21 @@ async function runPreview(rest) {
   await startServer({ projectDir, port, env: "local", previewMode: true });
 }
 async function runExportCmd(rest) {
-  let outDir = resolve3("behold-export");
+  let outDir = resolve4("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 = resolve3(rest[++i]);
+    if (a === "--out") outDir = resolve4(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 = resolve3(dirArg ?? process.cwd());
+  const projectDir = resolve4(dirArg ?? process.cwd());
   if (emulator) {
     injectEmulatorEnv(env);
     env ??= "local";
@@ -5254,7 +5884,7 @@ function isMainModule() {
   const entry = process.argv[1];
   if (!entry) return false;
   try {
-    return realpathSync(entry) === realpathSync(fileURLToPath3(import.meta.url));
+    return realpathSync(entry) === realpathSync(fileURLToPath5(import.meta.url));
   } catch {
     return false;
   }