feat: behold doctor — the read-only first-touch diagnosis (#236)

[lex00]

Closes #236.

behold doctor [dir] [--json] — a read-only console report of everything behold needs to serve a project well. Seven lines, each pass/warn/fail with a one-line fix, exit 0 iff nothing failed.

behold doctor 0.7.0 — /path/to/example-k8s

  pass  project     chant project (chant.config.ts)
  pass  chant       chant 0.44.2 (behold's floor 0.38.0)
  pass  lexicons    2 installed: k8s 0.44.2, temporal 0.44.2
  pass  envs        local — `behold serve example-k8s --env local` for the live overlay
  warn  kube        context not in the kubeconfig — local: k3d-behold-k3d-demo
        fix         Add the context to your kubeconfig, or point k8s.profiles at one you have (…, +10 more).
  warn  substrates  Docker up, k3d down, Temporal blocked
        fix         Bring up: k3d (bash scripts/local/local-up.sh), Temporal (no temporal.profiles in chant.config.ts — chant run will refuse)
  pass  ops         1 committed: k3d-apply (apply); chant MCP available (the project's own chant)

  5 pass, 2 warn, 0 fail

The checks

line	source	fail when
project	detectProjectShape (project.ts)	neither a chant project nor an estate root
chant	resolveChant (chant.ts)	the project has no chant of its own; warns below behold's floor
lexicons	resolveLexicons (chant.ts)	a declared lexicon isn't installed
envs	detectProject	never — no envs warns, and says "no live overlay" plainly
kube	loadKubeconfig + resolveK8sTarget (k8s-target.ts)	never — no kubeconfig, an unresolvable context, or an ambient/declared mismatch (chant#1100 refuses the live read) all warn
substrates	detectSubstrates (substrates.ts)	never — a down substrate costs the live half, not the graph
ops	discoverEstateOps (ops.ts)	never — no committed Ops warns; MCP availability rides along

A fail is something that stops behold serving the project. A warn costs the live half — which is why a k8s project with no kube context warns rather than fails, per the acceptance list.

Reuse, not new probing

Every fact comes from the module the server already reads it from — including k8s-target.ts exactly as-is (no chant-k8s-client; #231 stays its own lane). Where a check needed detection the server didn't have, the logic went into the shared module:

• project.ts — detectProjectShape (chant.config.* / .behold.json members / npm workspaces) and chantConfigPath. cli.ts's warnIfNotChantProject now shares it, so behold serve on an estate root points at the members instead of reporting a missing chant.config.ts.
• chant.ts — resolveChant / resolveLexicons / chantFloor / meetsFloor, with chantBin re-expressed through resolveChant and chantBinFrom kept as a wrapper over the new chantPackageFrom.

resolveChant compares package roots, not requires, to tell the project's own chant from behold's fallback. Node resolution walks up parent directories, so every bundled example resolves behold's chant without having one of its own — reported as "the project's", the check would have missed the exact missing install it exists to catch.

Estates are diagnosed across their members: per-member chant and lexicon lines, unioned envs and lexicons, discoverEstateOps for the Ops, and the serve hint names the members rather than the unservable root.

Tests

src/doctor.test.ts — healthy project (all pass), no-project dir (single fail + fix), missing install (fail naming npm install), k8s with no context (warn), bound context resolved, ambient/declared mismatch, down substrate, no envs, no Ops, estate via .behold.json and via workspaces. Plus a --json shape test (key order, one check per name, fix present iff not pass) and an inline snapshot of the console output. Fixtures are built in the OS tmpdir and cleaned up — example-writes' node_modules is absent in a fresh checkout and present after just example-install, so a test keyed on either state would pass half the time. The two live probes (kubeconfig, substrates) are injected, so nothing depends on the host's Docker or kubeconfig.

Docs: README quickstart, AGENTS.md discovery step, and the "Open your own project" docs page.

just check green.

🤖 Generated with Claude Code