create-evda 0.1.0

package/lib/doctor.mjs

@@ -0,0 +1,419 @@
+// evda doctor: validate a directory against Spec 04 and 05 and say what was examined.
+//
+// Every section prints exactly one of:
+//   CHECKED <n> <noun>   it looked at n things, and n is never 0 (0 is a broken discovery step)
+//   SKIPPED <noun>: why  it had nothing to look at, and says so; a skip is never a tick
+// A run that exits 0 without a CHECKED line of n > 0 is itself a failure. The guard is at the end.
+//
+// FALSIFIED 2026-09-15, three ways, on a fresh scaffold, each watched:
+//   1. Appended H-0001 (refined) and H-0002 with `**Supersedes:** H-0001` and no `Superseded by`
+//      on H-0001 -> "FAIL  ledger/hypotheses.md:80  H-0002 supersedes H-0001 but H-0001 does not
+//      say Superseded by: H-0002. The chain reads differently from each end." and "FAILED  1
+//      failure(s), 1 warning(s), 8 check(s) with something in them", exit 1.
+//   2. Removed ledger/ with the role still mapped -> "FAIL  role ledger  is mapped to ledger but
+//      that directory does not exist. An empty directory and a missing one are different facts."
+//      and "SKIPPED hypotheses: ledger file is missing (already failed above)", exit 1.
+//   3. Emptied the mapping and layers -> "CHECKED 0 roles  0 mapped, 6 absent" followed by
+//      "FAIL  roles  CHECKED 0 is not a pass. The discovery step found nothing to examine, which
+//      is a broken step, not a clean record." and "FAILED  3 failure(s)", exit 1.
+// FALSIFIED 2026-09-16, sections 12 and 13, on a fresh scaffold whose record/people/sam.md carried
+// two references, one with `password: hunter2` and one through a connector the folder did not
+// declare -> "CHECKED 3 folder manifests  0 with connectors", then
+//   "FAIL  record/people/sam.md  REFUSED: record/people/sam.md: references[0] carries a field
+//    named "password". A reference holds a pointer, a label and a date; ..."
+//   "FAIL  record/people/sam.md  references contacts:2F1A-77 through contacts, which
+//    record/people/folder.evda.json does not declare (it declares: none)."
+//   "CHECKED 2 references  across 1 file(s), 1 refused" and "FAILED  2 failure(s)", exit 1.
+// The value hunter2 appeared nowhere in the output. The same run, the first time, was made against
+// the wrong record: `evda doctor scratch` with a bare directory name fell through the locator to
+// ~/.evda/current, which is why bin/evda.mjs pickDir now treats a directory that exists as the
+// argument.
+// FALSIFIED 2026-09-16, section 11b, on a scaffold with one private circle (workshop), an agent
+// granted viewer on it through `evda grant`, and a hand-written grants/peers/bot.atlas--core.eco
+// file giving an agent editor on a circle the record does not have ->
+//   "FAIL  grant  grants/peers/bot.atlas--core.eco.yaml: grants editor to an agent. An agent holds
+//    viewer and nothing else (Spec 00 #65)."
+//   "FAIL  grant  grants/peers/bot.atlas--core.eco.yaml grants circle "core", and this record has
+//    no such circle."
+//   "CHECKED 2 grants  across 2 circle(s), 2 to agents", "FAILED  2 failure(s)", exit 1.
+// `evda access workshop --as iris.atlas` on the same record: ALLOWED, exit 0, naming the grant
+// file; `evda access core --as iris.atlas`: REFUSED, exit 2, "no circle named "core"".
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { readManifest, checkVersion, unknownKeys, unknownLayers, holderOf, holderProblems, KNOWN_LAYERS, SCHEMA_VERSION } from "./manifest.mjs";
+import { readGrants } from "./grants.mjs";
+import { resolveAll, resolveRole, rolesForLayer, ROLES } from "./roles.mjs";
+import { parseLedger, countHeads } from "./ledger.mjs";
+import { validateEntries } from "./validate.mjs";
+import { deriveDue, currentIndex, currentDigest } from "./index.mjs";
+import { mdFiles, fileDate } from "./record.mjs";
+import { splitFence, digestFrom, digestBytes, DIGEST_BUDGET } from "./agents.mjs";
+import { readCircles, coverage, LEGACY_MANIFEST } from "./circles.mjs";
+import { folderManifests, folderFor, viewNamedIn, FOLDER_MANIFEST } from "./folders.mjs";
+import { referencesIn } from "./references.mjs";
+import { EvdaError } from "./errors.mjs";
+
+// Same rule as record.mjs fileDate: a daily file is dated by a leading YYYY-MM-DD in its name.
+// A suffix after the date is allowed (`2026-01-19 - The Scale Question.md`); no date is not.
+const DAILY_NAME = /^\d{4}-\d{2}-\d{2}(?:[ .-]|$)/;
+
+export function doctor(dir, { out = console.log, via = "argument" } = {}) {
+  const failures = [];
+  const warnings = [];
+  const checked = [];
+  const fail = (where, msg) => { failures.push(`${where}  ${msg}`); out(`  FAIL  ${where}  ${msg}`); };
+  const warn = (where, msg) => { warnings.push(`${where}  ${msg}`); out(`  WARN  ${where}  ${msg}`); };
+  const ok = (n, noun, detail) => {
+    checked.push({ n, noun });
+    out(`  CHECKED ${n} ${noun}${detail ? `  ${detail}` : ""}`);
+    if (n === 0) fail(noun, `CHECKED 0 is not a pass. The discovery step found nothing to examine, which is a broken step, not a clean record.`);
+  };
+  const skip = (noun, why) => out(`  SKIPPED ${noun}: ${why}`);
+
+  out(`evda doctor  ${dir}  (located via ${via})`);
+
+  // 1. manifest
+  let manifest;
+  try {
+    manifest = readManifest(dir);
+  } catch (e) {
+    out(`  ${e.message}`);
+    return finish(e.exit ?? 2);
+  }
+  const unknown = unknownKeys(manifest);
+  const holder = holderOf(manifest);
+  for (const p of holderProblems(manifest)) fail("evda.json", p);
+  if (!manifest.id) warn("evda.json", 'has no "id". Another record names this one by its id in a grant or a reference; without one it cannot be granted anything.');
+  ok(1, "manifest", `evda.json: schema ${manifest.evda}, held by a ${holder.kind}${holder.id ? ` (${holder.id})` : ""}, layers [${manifest.layers.join(", ")}]${unknown.length ? `, ${unknown.length} unknown key(s) preserved: ${unknown.join(", ")}` : ""}`);
+
+  // 2. version
+  let version;
+  try {
+    version = checkVersion(dir, manifest);
+  } catch (e) {
+    out(`  ${e.message}`);
+    fail(".evda/version", e.code);
+    return finish(e.exit ?? 2);
+  }
+  ok(1, "version file", `.evda/version = ${version.onDisk}, matches evda.json${version.newerThanTool ? ` (WARN: newer than this tool's ${SCHEMA_VERSION}; operating known layers only, everything else preserved)` : ""}`);
+  if (version.newerThanTool) warn("evda.json", `schema ${manifest.evda} is newer than this tool (${SCHEMA_VERSION}). Nothing unknown will be touched.`);
+
+  // 3. layers against mapping. Two records of one fact, so they must agree.
+  const evda = { dir, manifest, version };
+  let roles;
+  try {
+    roles = resolveAll(evda);
+  } catch (e) {
+    out(`  ${e.message}`);
+    fail("evda.json mapping", e.code);
+    return finish(2);
+  }
+  for (const layer of manifest.layers) {
+    if (!KNOWN_LAYERS.includes(layer)) { warn("evda.json layers", `"${layer}" is not a layer this tool knows. Preserved, not validated.`); continue; }
+    const mapped = rolesForLayer(layer).filter((r) => manifest.mapping[r] !== undefined);
+    if (mapped.length === 0) fail("evda.json layers", `layer "${layer}" is declared but none of its roles (${rolesForLayer(layer).join(", ")}) is in the mapping.`);
+  }
+  for (const r of roles) {
+    if (!r.mapped) continue;
+    if (!r.known) { warn("evda.json mapping", `role "${r.role}" is not one this tool knows. Preserved, not validated.`); continue; }
+    if (r.layer && !manifest.layers.includes(r.layer)) fail("evda.json mapping", `role "${r.role}" is mapped but its layer "${r.layer}" is not declared in layers.`);
+  }
+  if (manifest.layers.length) ok(manifest.layers.length, "layers", manifest.layers.join(", "));
+  else fail("evda.json layers", "no layers declared. An EVDA with no layers is a directory with a manifest in it.");
+
+  // 4. roles. A mapped path that does not exist is loud. An absent role is stated.
+  const mappedKnown = roles.filter((r) => r.mapped && r.known);
+  for (const r of roles) {
+    if (!r.known) continue;
+    if (!r.mapped) { out(`        ${r.role.padEnd(16)} absent (not in mapping)`); continue; }
+    if (r.kind === "file") {
+      if (!r.exists) { fail(`role ${r.role}`, `is mapped to ${r.rel} but that file does not exist.`); continue; }
+      if (r.isDir) { fail(`role ${r.role}`, `is mapped to ${r.rel} which is a directory, not a file.`); continue; }
+      out(`        ${r.role.padEnd(16)} -> ${r.rel}  present`);
+      continue;
+    }
+    if (!r.exists) { fail(`role ${r.role}`, `is mapped to ${r.rel} but that directory does not exist. An empty directory and a missing one are different facts.`); continue; }
+    if (!r.isDir) { fail(`role ${r.role}`, `is mapped to ${r.rel} which is a file, not a directory.`); continue; }
+    let detail = "";
+    if (r.file) detail = r.fileExists ? `${r.fileRel} present` : `${r.fileRel} MISSING`;
+    else detail = `${countMd(r.abs)} md file(s)`;
+    out(`        ${r.role.padEnd(16)} -> ${r.rel}  ${detail}`);
+    if (r.file && !r.fileExists) fail(`role ${r.role}`, `${r.fileRel} does not exist. The ledger role is mapped, so its file must be there.`);
+  }
+  ok(mappedKnown.length, "roles", `${mappedKnown.length} mapped, ${roles.filter((r) => r.known && !r.mapped).length} absent`);
+
+  // 5. operating layer, a mapped role like the others. Only a record with none is a failure.
+  const agentsRole = resolveRole(evda, "agents");
+  let fence = null;
+  if (!agentsRole.mapped) {
+    fail("evda.json mapping", 'has no "agents" role. A record without its operating layer is not installable; add "agents": "<the file agents read>" (AGENTS.md, CLAUDE.md, or wherever it lives).');
+  } else if (!agentsRole.exists || agentsRole.isDir) {
+    skip("operating layer", "agents role did not resolve to a file (already failed above)");
+  } else {
+    const rel = agentsRole.rel;
+    const agents = readFileSync(agentsRole.abs, "utf8");
+    if (agents.trim() === "") fail(rel, "is empty.");
+    else {
+      if (!/ledger/i.test(agents)) warn(rel, "never mentions the ledger. An operating layer that does not name the loop cannot operate it.");
+      if (!/hypothes/i.test(agents)) warn(rel, "never mentions hypotheses.");
+      try {
+        fence = splitFence(agents);
+      } catch (e) {
+        fail(rel, e.message);
+      }
+      if (fence === null) warn(rel, "has no evda:generated fence. The owner has taken the whole file; `evda upgrade` has nothing it owns to replace.");
+      if (!/## What I have been taught/.test(agents)) warn(rel, 'has no "## What I have been taught" section, so a correction has nowhere to land.');
+    }
+    // Claude Code reads CLAUDE.md and nothing else. If the operating layer is elsewhere, CLAUDE.md
+    // has to import it or a Claude Code session here starts with no instructions.
+    if (rel !== "CLAUDE.md") {
+      const claudePath = join(dir, "CLAUDE.md");
+      const imports = existsSync(claudePath) && new RegExp(`^@${rel.replace(/[.*+?^${}()|[\\]\\\\]/g, "\\$&")}\\s*$`, "m").test(readFileSync(claudePath, "utf8"));
+      if (!imports) warn("CLAUDE.md", `does not import ${rel}. Claude Code loads CLAUDE.md and not ${rel}, so a Claude Code session here would start with no operating layer.`);
+    }
+    ok(1, "operating layer", rel);
+  }
+
+  // 6. record files
+  const recordRoles = mappedKnown.filter((r) => r.layer === "record" && r.exists && r.isDir);
+  if (recordRoles.length === 0) {
+    skip("record files", manifest.layers.includes("record") ? "no record role resolved to a directory" : "no record layer declared");
+  } else {
+    let total = 0;
+    let undated = 0;
+    for (const r of recordRoles) {
+      const files = mdFiles(r.abs);
+      total += files.length;
+      if (r.role === "record/daily") {
+        const bad = readdirSync(r.abs).filter((n) => n.endsWith(".md") && !DAILY_NAME.test(n));
+        if (bad.length) warn(r.rel, `${bad.length} file(s) not named YYYY-MM-DD.md, invisible to the occurrence index: ${bad.slice(0, 5).join(", ")}${bad.length > 5 ? ", ..." : ""}`);
+      }
+      for (const p of files) {
+        if (!fileDate(p, readFileSync(p, "utf8"))) undated += 1;
+      }
+    }
+    if (total === 0) skip("record files", `every mapped record directory is empty (${recordRoles.map((r) => r.rel).join(", ")})`);
+    else ok(total, "record files", `across ${recordRoles.length} role(s)${undated ? `, ${undated} undated (no date in filename or frontmatter)` : ""}`);
+  }
+
+  // 7. ledger
+  let parsed = null;
+  let ledgerRel = null;
+  const ledgerRole = resolveRole(evda, "ledger");
+  if (!ledgerRole.mapped) {
+    skip("hypotheses", "no ledger role in the mapping");
+  } else if (!ledgerRole.exists || !ledgerRole.fileExists) {
+    skip("hypotheses", "ledger file is missing (already failed above)");
+  } else {
+    ledgerRel = ledgerRole.fileRel;
+    const text = readFileSync(ledgerRole.file, "utf8");
+    const heads = countHeads(text);
+    parsed = parseLedger(text);
+    if (!/^\s{4}### H-\d{4}:/m.test(text)) warn(ledgerRel, "has no entry template at its top. A stranger opening this file has no shape to write to.");
+    if (heads === 0) {
+      skip("hypotheses", `${ledgerRel} has no entries yet`);
+    } else if (parsed.entries.length === 0) {
+      fail(ledgerRel, `has ${heads} entry heading(s) but the parser found 0 entries. The parser is broken, not the ledger.`);
+    } else {
+      for (const p of validateEntries(parsed, { root: dir })) {
+        (p.level === "fail" ? fail : warn)(`${ledgerRel}:${p.line}`, p.message);
+      }
+      ok(parsed.entries.length, "hypotheses", `${ledgerRel}: ${summarizeStatus(parsed)}`);
+    }
+  }
+
+  // 8. temporal index
+  if (!ledgerRole.mapped || !parsed) {
+    skip("temporal index", "no ledger to derive it from");
+  } else {
+    const expected = deriveDue(parsed, ledgerRel);
+    const actual = currentIndex(evda);
+    const rows = expected ? expected.trimEnd().split("\n").length : 0;
+    if (actual === null) warn(".evda/due.jsonl", `missing. Derived, so nothing is lost; run \`evda reindex\` (${rows} row(s) would be written).`);
+    else if (actual !== expected) warn(".evda/due.jsonl", `is stale against the ledger. Run \`evda reindex\`. Nothing is lost; it is derived.`);
+    ok(1, "temporal index", actual === null ? "absent" : actual === expected ? `.evda/due.jsonl matches the ledger (${rows} due)` : "stale");
+  }
+
+  // 9. digest, derived from the fence. Budgeted.
+  if (!fence) {
+    skip("digest", "the operating layer has no generated fence to derive it from");
+  } else {
+    const expected = digestFrom(fence.generated);
+    const bytes = digestBytes(expected);
+    if (bytes > DIGEST_BUDGET) fail(".evda/digest.md", `would be ${bytes} bytes, over the ${DIGEST_BUDGET} byte budget.`);
+    const actual = currentDigest(evda);
+    if (actual === null) warn(".evda/digest.md", "missing. Derived; run `evda reindex`.");
+    else if (actual !== expected) warn(".evda/digest.md", `is stale against ${agentsRole.rel}. Run \`evda reindex\`.`);
+    ok(1, "digest", `${bytes}/${DIGEST_BUDGET} bytes${actual === expected ? `, matches ${agentsRole.rel}` : ""}`);
+  }
+
+  // 10. circles, each an eco declared by its own eco.yaml (HQ-1162, HQ-1165). A directory under
+  // the role with no manifest is a failure; a public circle is readable, a private one is declared
+  // only; a circle still on circle.json is read and told to move.
+  const circlesRole = resolveRole(evda, "circles");
+  if (!circlesRole.mapped) {
+    skip("circles", "no circles role in the mapping");
+  } else if (!circlesRole.exists || !circlesRole.isDir) {
+    skip("circles", "circles role did not resolve to a directory (already failed above)");
+  } else {
+    let circles;
+    try {
+      circles = readCircles(evda);
+    } catch (e) {
+      out(`  ${e.message}`);
+      fail(circlesRole.rel, e.code);
+      return finish(e.exit ?? 1);
+    }
+    for (const c of circles) {
+      for (const p of c.problems) (p.level === "fail" ? fail : warn)(`circle ${c.name}`, p.message);
+      const members = Object.entries(c.members).map(([n, m]) => `${n} -> ${m.kind === "path" ? m.rel : `table ${m.table}`}`).join(", ");
+      const policy = c.policy ? `, policy: ${c.policy.rules.length} rule(s)` : "";
+      out(`        ${c.name.padEnd(16)} ${c.manifest?.public === true ? "public" : "private"}  ${c.readable ? "readable" : "not readable"}${c.source === LEGACY_MANIFEST ? "  (circle.json)" : ""}${members ? `  [${members}]` : ""}${policy}`);
+    }
+    if (circles.length === 0) skip("circles", `${circlesRole.rel} holds no circle directories`);
+    else ok(circles.length, "circles", `${circles.filter((c) => c.readable).length} public and readable, ${circles.filter((c) => c.manifest?.public === false).length} private, ${circles.filter((c) => c.policy).length} with a policy${circles.some((c) => c.source === LEGACY_MANIFEST) ? `, ${circles.filter((c) => c.source === LEGACY_MANIFEST).length} still on circle.json` : ""}`);
+
+    // 11. every entry resolves to exactly one circle (Spec 07, section 3). Zero is an entry nobody
+    // can say who may read; two is an entry with two access answers, which an encryption boundary
+    // cannot have.
+    if (circles.length > 0) {
+      const entries = [];
+      for (const r of mappedKnown.filter((x) => x.layer === "record" && x.exists && x.isDir)) entries.push(...mdFiles(r.abs));
+      if (ledgerRole.mapped && ledgerRole.fileExists) entries.push(ledgerRole.file);
+      if (entries.length === 0) {
+        skip("entries across circles", "the record has no entries to cover");
+      } else {
+        const cov = coverage(evda, circles, entries);
+        const none = cov.filter((c) => c.circles.length === 0);
+        const many = cov.filter((c) => c.circles.length > 1);
+        const show = (list) => list.slice(0, 5).map((c) => relative(dir, c.abs)).join(", ") + (list.length > 5 ? ", ..." : "");
+        if (none.length) fail("circles", `${none.length} entr${none.length === 1 ? "y" : "ies"} no circle covers: ${show(none)}. Every entry resolves to exactly one circle; a private circle whose members cover the rest of the record is the usual answer.`);
+        if (many.length) fail("circles", `${many.length} entr${many.length === 1 ? "y" : "ies"} covered by more than one circle: ${many.slice(0, 5).map((c) => `${relative(dir, c.abs)} (${c.circles.join(", ")})`).join(", ")}${many.length > 5 ? ", ..." : ""}. One access answer per entry.`);
+        ok(entries.length, "entries", `across ${circles.length} circles, ${none.length} uncovered, ${many.length} covered twice`);
+      }
+    }
+  }
+
+  // 11b. grants (Spec 00 #65): who may read each circle, one substrate member tuple per file under
+  // the grants role. A grant on a circle that does not exist, or one that gives an agent more than
+  // viewer, fails; a grant on a public circle is a warning, since it changes nothing.
+  const grantsRole = resolveRole(evda, "grants");
+  if (!grantsRole.mapped) {
+    skip("grants", "no grants role in the mapping");
+  } else if (!grantsRole.exists || !grantsRole.isDir) {
+    skip("grants", "grants role did not resolve to a directory (already failed above)");
+  } else {
+    const grants = readGrants(evda);
+    const known = circlesRole.mapped && circlesRole.exists && circlesRole.isDir ? readCircles(evda) ?? [] : [];
+    const circleNames = new Set(known.map((c) => c.name));
+    const publicNames = new Set(known.filter((c) => c.manifest?.public === true).map((c) => c.name));
+    for (const g of grants) {
+      for (const p of g.problems) (p.level === "fail" ? fail : warn)("grant", p.message);
+      if (g.circle && !circleNames.has(g.circle)) fail("grant", `${g.rel} grants circle "${g.circle}", and this record has no such circle.`);
+      else if (g.circle && publicNames.has(g.circle)) warn("grant", `${g.rel} grants circle "${g.circle}", which is public; the grant changes nothing.`);
+      if (g.principalId) out(`        ${g.principalId.padEnd(24)} ${g.role ?? "?"} on ${g.circle ?? "?"}  (${g.holder ? g.holder.kind + (g.holder.name ? ` ${g.holder.name}` : "") : "holder unknown"})`);
+    }
+    if (grants.length === 0) skip("grants", `${grantsRole.rel} holds no grant files`);
+    else ok(grants.length, "grants", `across ${new Set(grants.map((g) => g.circle).filter(Boolean)).size} circle(s), ${grants.filter((g) => g.holder?.kind === "agent").length} to agents`);
+  }
+
+  // 12. folder manifests (Spec 07, section 2): each record folder says what its entries are and
+  // which connectors feed its references. A manifest that is not JSON refuses the run.
+  let folders = [];
+  if (recordRoles.length === 0) {
+    skip("folder manifests", "no record role resolved to a directory");
+  } else {
+    try {
+      folders = folderManifests(evda);
+    } catch (e) {
+      out(`  ${e.message}`);
+      fail(FOLDER_MANIFEST, e.code);
+      return finish(e.exit ?? 2);
+    }
+    for (const f of folders) {
+      for (const p of f.problems) (p.level === "fail" ? fail : warn)(`folder ${relative(dir, f.dir) || "."}`, p.message);
+      out(`        ${(relative(dir, f.dir) || ".").padEnd(24)} type ${f.type ?? "?"}  connectors [${f.connectors.join(", ")}]  views [${f.views.map((v) => v.view).join(", ")}]`);
+    }
+    if (folders.length === 0) skip("folder manifests", `no record folder carries ${FOLDER_MANIFEST}`);
+    else ok(folders.length, "folder manifests", `${folders.filter((f) => f.connectors.length).length} with connectors`);
+
+    // 12b. views (Spec 07, section 5): a manifest's `views` declare the markdown files the renderer
+    // (@evda/views, not this package) writes over the folder's entries. Doctor checks what it can
+    // without the renderer: the path stays inside the record, the file is there, and its header
+    // names the same view. What the header says beyond the name is the renderer's to refuse.
+    let views = 0;
+    for (const f of folders) {
+      const where = `folder ${relative(dir, f.dir) || "."}`;
+      for (const v of f.views) {
+        views += 1;
+        const abs = resolve(dir, v.path);
+        if (abs !== dir && !abs.startsWith(dir + sep)) { fail(where, `view "${v.view}" names ${v.path}, which is outside the record. A view's path is relative to the record root.`); continue; }
+        if (!existsSync(abs) || !statSync(abs).isFile()) { fail(where, `view "${v.view}" names ${v.path}, and no file is there. The renderer writes it; until then the declaration promises a file the record does not hold.`); continue; }
+        const named = viewNamedIn(readFileSync(abs, "utf8"));
+        if (named === null) fail(where, `${v.path} is declared as view "${v.view}" but does not open with a header naming its query (---, view: <name>, ---).`);
+        else if (named !== v.view) fail(where, `${v.path} is declared as view "${v.view}" but its header says view: ${named}. The header and the declaration must agree.`);
+      }
+    }
+    if (views === 0) skip("views", "no folder manifest declares a view");
+    else ok(views, "views", `across ${folders.filter((f) => f.views.length).length} folder(s)`);
+  }
+
+  // 13. references (Spec 07, section 4): a pointer, a label and a date, never the payload, never
+  // a secret, and only through a connector the folder declares.
+  if (recordRoles.length === 0) {
+    skip("references", "no record role resolved to a directory");
+  } else {
+    let refs = 0;
+    let refused = 0;
+    const files = new Set();
+    for (const r of recordRoles) {
+      for (const p of mdFiles(r.abs)) {
+        const rel = relative(dir, p);
+        const found = referencesIn(readFileSync(p, "utf8"), rel);
+        for (const pr of found.problems) { refused += 1; fail(rel, pr.message); }
+        if (found.references.length === 0 && found.problems.length === 0) continue;
+        files.add(rel);
+        refs += found.references.length + found.problems.length;
+        const folder = folderFor(p, folders);
+        for (const ref of found.references) {
+          if (!folder) fail(rel, `references ${ref.ref} but no folder above it carries ${FOLDER_MANIFEST}. A reference resolves through a connector the folder declares; say what the folder holds and which connectors feed it.`);
+          else if (!folder.connectors.includes(ref.scheme)) fail(rel, `references ${ref.ref} through ${ref.scheme}, which ${folder.rel} does not declare (it declares: ${folder.connectors.join(", ") || "none"}).`);
+        }
+      }
+    }
+    if (refs === 0) skip("references", "no record file carries a references list");
+    else ok(refs, "references", `across ${files.size} file(s)${refused ? `, ${refused} refused` : ""}`);
+  }
+
+  return finish(0);
+
+  function finish(refusedExit) {
+    if (refusedExit === 2) {
+      out(`REFUSED  nothing was written`);
+      return { failures, warnings, checked, exit: 2 };
+    }
+    const real = checked.filter((c) => c.n > 0);
+    if (real.length === 0) {
+      fail("doctor", "printed no CHECKED line with n > 0. A checker that examined nothing is not a checker.");
+    }
+    if (failures.length) {
+      out(`FAILED  ${failures.length} failure(s), ${warnings.length} warning(s), ${real.length} check(s) with something in them`);
+      return { failures, warnings, checked, exit: 1 };
+    }
+    out(`OK  ${real.length} check(s), ${warnings.length} warning(s)`);
+    return { failures, warnings, checked, exit: 0 };
+  }
+}
+
+function countMd(dir) {
+  try { return mdFiles(dir).length; } catch { return 0; }
+}
+
+function summarizeStatus(parsed) {
+  const counts = {};
+  for (const e of parsed.entries) counts[e.statusWord || "?"] = (counts[e.statusWord || "?"] ?? 0) + 1;
+  return Object.entries(counts).map(([k, v]) => `${v} ${k}`).join(", ");
+}
+
+export { EvdaError };

package/lib/errors.mjs

@@ -0,0 +1,26 @@
+// One error type for the whole data layer. `exit` is the process exit code a CLI should use:
+//   1  something is wrong with the record and the tool said what
+//   2  the tool REFUSED to operate (version mismatch, no manifest, escaped path). Nothing was written.
+export class EvdaError extends Error {
+  constructor(message, { code = "EVDA", exit = 1 } = {}) {
+    super(message);
+    this.name = "EvdaError";
+    this.code = code;
+    this.exit = exit;
+  }
+}
+
+// Is `argv1` this module's file, the way node was actually invoked? Through realpath on BOTH
+// sides, because an installed bin is a symlink (node_modules/.bin/evda -> ../create-evda/bin/
+// evda.mjs) and path.resolve() does not follow symlinks. Comparing resolve(argv[1]) to the
+// module URL is how the first clean-machine `npx create-evda` exited 0 having written nothing.
+// `moduleUrl` is the caller's import.meta.url.
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+export function isEntry(argv1, moduleUrl) {
+  try {
+    return realpathSync(argv1) === realpathSync(fileURLToPath(moduleUrl));
+  } catch {
+    return false;
+  }
+}

package/lib/folders.mjs

@@ -0,0 +1,160 @@
+// folder.evda.json: what a folder's entries are (Spec 07, section 2).
+//
+//   {
+//     "type": "person",
+//     "connectors": ["contacts"],
+//     "views": [{ "view": "everyone", "of": "person", "in": "people.eco", "path": "record/people/Everyone.md" }]
+//   }
+//
+// `type` is what the entries are, one of the Spec 07 types. `connectors` are the reference schemes
+// the folder's entries may point through; the resolver registry reads this list and skips a scheme
+// the folder does not name. `views` are the folder's view declarations (Spec 07, section 5), one
+// object each: `view` (its name), `of` (the entity kind it renders), `in` (the eco the entries live
+// in), `path` (the markdown file it renders to, relative to the record root), and optionally
+// `status` (keep only these) and `group`. The renderer is `@evda/views`, not this package, so this
+// package checks the shape and leaves what the values mean to the renderer. The manifest never
+// names a circle: a circle declares its own members by path, and a second copy would drift.
+// Nothing moves: the manifest sits in the folder it describes, and a folder without one is a
+// folder that has not said what it holds.
+//
+// A file inherits the nearest manifest above it, within the record. An entry that carries a
+// reference must sit under a manifest, and that manifest must declare the reference's scheme.
+
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { resolveAll } from "./roles.mjs";
+import { SCHEMES } from "./references.mjs";
+import { EvdaError } from "./errors.mjs";
+
+export const FOLDER_MANIFEST = "folder.evda.json";
+export const FOLDER_TYPES = ["record", "person", "project", "course", "source", "concept", "event", "log", "ticket", "capture", "piece", "blob", "rule", "hypothesis"];
+export const FOLDER_KEYS = ["type", "connectors", "views"];
+export const VIEW_KEYS_REQUIRED = ["view", "of", "in", "path"];
+export const VIEW_KEYS = [...VIEW_KEYS_REQUIRED, "status", "group"];
+
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const nonEmpty = (v) => typeof v === "string" && v.trim() !== "";
+
+// The view a markdown file's header names, or null when the file does not open with a header
+// (`---`, `view: <name>` among the lines, `---`). This is the one thing doctor reads off a view
+// file; the rest of the header is the renderer's.
+export function viewNamedIn(text) {
+  const lines = text.split("\n");
+  if (lines[0] !== "---") return null;
+  let name = null;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === "---") return name;
+    const m = /^view:\s*(.+?)\s*$/.exec(lines[i]);
+    if (m) name = m[1];
+  }
+  return null;
+}
+
+// Read one folder's manifest. null when the folder has none. Throws when the file is present and
+// not JSON, because a manifest that cannot be read is worse than none.
+export function readFolderManifest(dirAbs) {
+  const p = join(dirAbs, FOLDER_MANIFEST);
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch (e) {
+    throw new EvdaError(`REFUSED: ${p} is not valid JSON (${e.message}).`, { code: "BAD_FOLDER", exit: 2 });
+  }
+}
+
+// Validate a manifest. Returns { manifest, type, connectors, views, problems }; never throws for a
+// problem in the content, so doctor can list them all.
+export function validateFolderManifest(m, rel) {
+  const problems = [];
+  const fail = (msg) => problems.push({ level: "fail", message: `${rel}: ${msg}` });
+  const warn = (msg) => problems.push({ level: "warn", message: `${rel}: ${msg}` });
+  const out = { manifest: m, type: null, connectors: [], views: [], problems };
+  if (!isObject(m)) { fail("must hold a JSON object."); return out; }
+  if (!nonEmpty(m.type)) fail(`has no "type". Say what the entries are: ${FOLDER_TYPES.join(", ")}.`);
+  else {
+    out.type = m.type.trim();
+    if (!FOLDER_TYPES.includes(out.type)) warn(`type "${out.type}" is not one this tool knows (${FOLDER_TYPES.join(", ")}). Preserved; nothing renders it.`);
+  }
+  if (m.connectors !== undefined) {
+    if (!Array.isArray(m.connectors) || !m.connectors.every(nonEmpty)) fail(`"connectors" must be a list of scheme names.`);
+    else {
+      for (const c of m.connectors) {
+        if (!SCHEMES.includes(c)) fail(`connector "${c}" is not a reference scheme this tool can resolve (${SCHEMES.join(", ")}). A connector nothing resolves is a promise nothing keeps.`);
+      }
+      out.connectors = [...new Set(m.connectors)];
+      if (out.connectors.length !== m.connectors.length) warn(`"connectors" lists a scheme twice.`);
+    }
+  }
+  if (m.views !== undefined) {
+    if (!Array.isArray(m.views)) fail(`"views" must be a list of view declarations.`);
+    else {
+      const names = new Set();
+      m.views.forEach((v, i) => {
+        const at = `views[${i}]`;
+        if (!isObject(v)) { fail(`${at} must be a view declaration: { view, of, in, path, status?, group? }, not ${JSON.stringify(v)}.`); return; }
+        const missing = VIEW_KEYS_REQUIRED.filter((k) => !nonEmpty(v[k]));
+        if (missing.length) fail(`${at} has no "${missing.join('", "')}". A view declares its name (view), what it renders (of), which eco (in), and the file it renders to (path).`);
+        if (v.status !== undefined && (!Array.isArray(v.status) || !v.status.every(nonEmpty))) fail(`${at} "status" must be a list of status words.`);
+        if (v.group !== undefined && !nonEmpty(v.group)) fail(`${at} "group" must be a word.`);
+        const unknown = Object.keys(v).filter((k) => !VIEW_KEYS.includes(k));
+        if (unknown.length) warn(`${at} carries ${unknown.length} key(s) this tool does not know, preserved: ${unknown.join(", ")}.`);
+        if (nonEmpty(v.view)) {
+          if (names.has(v.view)) fail(`declares view "${v.view}" twice.`);
+          names.add(v.view);
+        }
+        if (!missing.length) out.views.push(v);
+      });
+    }
+  }
+  if (m.circle !== undefined || m.circles !== undefined) fail(`names a circle. A circle declares its own members by path (eco.yaml); a second copy here would drift.`);
+  const unknown = Object.keys(m).filter((k) => !FOLDER_KEYS.includes(k));
+  if (unknown.length) warn(`${unknown.length} unknown key(s) preserved, not validated: ${unknown.join(", ")}.`);
+  return out;
+}
+
+// Every folder manifest under the record's record roles, deepest last. Each item is
+// { rel, abs, dir, ...validateFolderManifest }. Throws only on a manifest that is not JSON.
+export function folderManifests(evda) {
+  const out = [];
+  const roots = resolveAll(evda).filter((r) => r.known && r.mapped && r.layer === "record" && r.exists && r.isDir);
+  const walk = (dir) => {
+    const m = readFolderManifest(dir);
+    if (m !== null) {
+      const abs = join(dir, FOLDER_MANIFEST);
+      out.push({ rel: relative(evda.dir, abs), abs, dir, ...validateFolderManifest(m, relative(evda.dir, abs)) });
+    }
+    for (const name of readdirSync(dir).sort()) {
+      if (name.startsWith(".")) continue;
+      const p = join(dir, name);
+      if (statSync(p).isDirectory()) walk(p);
+    }
+  };
+  for (const r of roots) walk(r.abs);
+  return out;
+}
+
+// The manifest that governs a file: the nearest one in an ancestor directory, or null.
+export function folderFor(fileAbs, manifests) {
+  let best = null;
+  for (const m of manifests) {
+    if (fileAbs === m.dir || !fileAbs.startsWith(m.dir + sep)) continue;
+    if (!best || m.dir.length > best.dir.length) best = m;
+  }
+  return best;
+}
+
+// Write a manifest into a folder inside the record. Refuses a folder outside the record, an
+// unknown connector, and an existing manifest unless told to overwrite.
+export function writeFolderManifest(evda, dir, { type, connectors = [], views = [] }, { overwrite = false } = {}) {
+  const abs = resolve(evda.dir, dir);
+  if (abs !== evda.dir && !abs.startsWith(evda.dir + sep)) throw new EvdaError(`REFUSED: ${dir} is outside the record.`, { code: "BAD_FOLDER", exit: 2 });
+  if (!existsSync(abs) || !statSync(abs).isDirectory()) throw new EvdaError(`${dir} is not a directory in the record.`, { code: "BAD_FOLDER", exit: 2 });
+  const m = { type, connectors, views };
+  const v = validateFolderManifest(m, relative(evda.dir, join(abs, FOLDER_MANIFEST)) || FOLDER_MANIFEST);
+  const first = v.problems.find((p) => p.level === "fail");
+  if (first) throw new EvdaError(`REFUSED: ${first.message}`, { code: "BAD_FOLDER", exit: 2 });
+  const p = join(abs, FOLDER_MANIFEST);
+  if (existsSync(p) && !overwrite) throw new EvdaError(`${relative(evda.dir, p)} exists; pass overwrite to replace it.`, { exit: 2 });
+  writeFileSync(p, JSON.stringify(m, null, 2) + "\n");
+  return p;
+}