@saasontools/strauss-kb 0.1.7 → 0.1.8

package/dist/cli-main.cjs

@@ -1055,14 +1055,460 @@ var contextCommand = define({
   }
 });
 
-// src/commands/list.ts
+// src/commands/doctor.ts
 var import_zod8 = require("zod");
+
+// src/kb-edges.ts
+var KB_EDGE_KINDS = [
+  "body-link",
+  "supersession",
+  "anchor",
+  "source"
+];
+var BODY_LINK_TARGET = new RegExp(
+  `\\]\\((${KB_CONCEPT_ID_PATTERN.source.replace(/^\^|\$$/g, "")})\\.md\\)`,
+  "g"
+);
+function neighbours(from, bundle, kinds = KB_EDGE_KINDS) {
+  const found = /* @__PURE__ */ new Map();
+  for (const kind of kinds) {
+    for (const record of edgeNeighbours(from, bundle, kind)) {
+      const existing = found.get(record.conceptId);
+      if (existing) {
+        if (!existing.via.includes(kind)) existing.via.push(kind);
+        continue;
+      }
+      found.set(record.conceptId, { record, via: [kind] });
+    }
+  }
+  return [...found.values()];
+}
+function edgeNeighbours(from, bundle, kind) {
+  switch (kind) {
+    // A link whose target is not in the bundle is legal per compose.ts —
+    // records are routinely written before the ones they point at exist — so
+    // missing targets are skipped, never an error.
+    case "body-link": {
+      const targets = new Set(
+        [...from.body.matchAll(BODY_LINK_TARGET)].map((match) => match[1])
+      );
+      if (!targets.size) return [];
+      return bundle.filter(
+        (candidate) => candidate.conceptId !== from.conceptId && targets.has(candidate.conceptId)
+      );
+    }
+    // Both directions and both pointers: `supersede()` writes the pair, but a
+    // hand-edit can leave one side behind, and a walk trusting one pointer
+    // would miss a replacement the bundle openly declares.
+    case "supersession":
+      return bundle.filter(
+        (candidate) => candidate.conceptId !== from.conceptId && (candidate.conceptId === from.frontmatter.strauss_superseded_by || from.frontmatter.strauss_supersedes?.includes(
+          candidate.conceptId
+        ) || candidate.frontmatter.strauss_superseded_by === from.conceptId || candidate.frontmatter.strauss_supersedes?.includes(from.conceptId))
+      );
+    // The edge that answers "why is this code shaped this way": every record
+    // attached to the same file or symbol, whatever its standing.
+    case "anchor": {
+      const mine = from.frontmatter.strauss_anchors ?? [];
+      if (!mine.length) return [];
+      return bundle.filter(
+        (candidate) => candidate.conceptId !== from.conceptId && (candidate.frontmatter.strauss_anchors ?? []).some(
+          (theirs) => mine.some((ours) => anchorsTouch(ours, theirs))
+        )
+      );
+    }
+    case "source": {
+      const mine = new Set((from.frontmatter.sources ?? []).map((s) => s.id));
+      if (!mine.size) return [];
+      return bundle.filter(
+        (candidate) => candidate.conceptId !== from.conceptId && (candidate.frontmatter.sources ?? []).some(
+          (source) => mine.has(source.id)
+        )
+      );
+    }
+  }
+}
+function anchorsTouch(left, right) {
+  if (left.file !== right.file) return false;
+  if (!left.symbol || !right.symbol) return true;
+  return left.symbol === right.symbol;
+}
+
+// src/validate.ts
+function validateBundle(records) {
+  const byId = new Map(records.map((record) => [record.conceptId, record]));
+  const problems = [];
+  const report = (check, conceptId2, note) => problems.push({ check, conceptId: conceptId2, note });
+  for (const record of records) {
+    const { conceptId: conceptId2, frontmatter: fm } = record;
+    if (!isKbRecordType(fm.type)) {
+      report("type", conceptId2, `unrecognised type "${fm.type}"`);
+    }
+    if (fm.strauss_status === "superseded") {
+      const by = fm.strauss_superseded_by;
+      if (!by) {
+        report("superseded_by", conceptId2, "superseded with no replacement");
+      } else if (!byId.has(by)) {
+        report("superseded_by", conceptId2, `replacement ${by} is missing`);
+      } else if (!byId.get(by)?.frontmatter.strauss_supersedes?.includes(conceptId2)) {
+        report("backlink", by, `does not list ${conceptId2} in supersedes`);
+      }
+    }
+    for (const old of fm.strauss_supersedes ?? []) {
+      const previous = byId.get(old);
+      if (!previous) {
+        report("supersedes", conceptId2, `target ${old} is missing`);
+      } else if (previous.frontmatter.strauss_status !== "superseded") {
+        report("supersedes", conceptId2, `${old} is not marked superseded`);
+      }
+    }
+    if (fm.strauss_assumption && fm.sources?.length) {
+      report("assumption", conceptId2, "marked an assumption but cites sources");
+    }
+  }
+  return problems;
+}
+
+// src/doctor.ts
+var DEFAULT_EXPIRING_DAYS = 30;
+var DEFAULT_UNVERIFIED_DAYS = 90;
+var DEFAULT_AGING_DAYS = 90;
+var CHECK_HEADLINES = {
+  expired: "past its stale_after date",
+  expiring: "stale_after falls within the window",
+  unverified: "nobody has ever confirmed it, and it is old enough to matter",
+  aging: "still open or still proposed long after it was written",
+  orphaned: "no other record links to it",
+  "broken-supersession": "the supersession pointers do not resolve",
+  "superseded-but-cited": "a live record's body links to one that no longer holds"
+};
+var DAY_MS = 864e5;
+function doctor(bundle, options = {}) {
+  const thresholds = {
+    expiringDays: options.expiringDays ?? DEFAULT_EXPIRING_DAYS,
+    unverifiedDays: options.unverifiedDays ?? DEFAULT_UNVERIFIED_DAYS,
+    agingDays: options.agingDays ?? DEFAULT_AGING_DAYS
+  };
+  const now = options.now ?? /* @__PURE__ */ new Date();
+  const adjudicated = adjudicate(bundle, bundle, now);
+  const standings = new Map(
+    adjudicated.map((hit) => [hit.record.conceptId, hit.standing])
+  );
+  const inForce = adjudicated.filter(
+    (hit) => hit.standing !== "superseded" && hit.standing !== "rejected"
+  );
+  const groups = [
+    group("expired", expired(inForce, now)),
+    group("expiring", expiring(inForce, now, thresholds.expiringDays)),
+    group("unverified", unverified(inForce, now, thresholds.unverifiedDays)),
+    group("aging", aging(inForce, now, thresholds.agingDays)),
+    group("orphaned", orphaned(bundle)),
+    group("broken-supersession", brokenSupersession(bundle, adjudicated)),
+    group("superseded-but-cited", supersededButCited(bundle, standings))
+  ];
+  const counts = Object.fromEntries(
+    groups.map((entry) => [entry.check, entry.count])
+  );
+  const findingCount = groups.reduce((total, entry) => total + entry.count, 0);
+  return {
+    recordCount: bundle.length,
+    thresholds,
+    counts,
+    groups,
+    findingCount,
+    healthy: findingCount === 0
+  };
+}
+function group(check, findings) {
+  return {
+    check,
+    headline: CHECK_HEADLINES[check],
+    count: findings.length,
+    findings
+  };
+}
+function expired(hits, now) {
+  const findings = [];
+  for (const hit of hits) {
+    const raw = hit.record.frontmatter.stale_after;
+    if (!raw) continue;
+    const at = Date.parse(raw);
+    if (Number.isNaN(at)) {
+      findings.push(
+        finding(hit.record, `stale_after "${raw}" is not a readable date`)
+      );
+      continue;
+    }
+    if (at < now.getTime()) {
+      findings.push(
+        finding(
+          hit.record,
+          `stale since ${raw} (${daysBetween(at, now.getTime())} days ago)`
+        )
+      );
+    }
+  }
+  return findings;
+}
+function expiring(hits, now, withinDays) {
+  const horizon = now.getTime() + withinDays * DAY_MS;
+  const findings = [];
+  for (const hit of hits) {
+    const raw = hit.record.frontmatter.stale_after;
+    if (!raw) continue;
+    const at = Date.parse(raw);
+    if (Number.isNaN(at) || at < now.getTime() || at > horizon) continue;
+    findings.push(
+      finding(
+        hit.record,
+        `goes stale ${raw} (in ${daysBetween(now.getTime(), at)} days)`
+      )
+    );
+  }
+  return findings;
+}
+function unverified(hits, now, olderThanDays) {
+  const findings = [];
+  for (const hit of hits) {
+    if (hit.record.frontmatter.verified?.length) continue;
+    const age = ageInDays(hit.record, now);
+    if (age === null || age <= olderThanDays) continue;
+    findings.push(
+      finding(hit.record, `never verified, written ${age} days ago`)
+    );
+  }
+  return findings;
+}
+function aging(hits, now, olderThanDays) {
+  const findings = [];
+  for (const hit of hits) {
+    const status = hit.record.frontmatter.strauss_status;
+    if (status !== "open" && status !== "proposed") continue;
+    const age = ageInDays(hit.record, now);
+    if (age === null || age <= olderThanDays) continue;
+    findings.push(
+      finding(
+        hit.record,
+        status === "open" ? `open for ${age} days` : `proposed ${age} days ago and still unsettled`
+      )
+    );
+  }
+  return findings.sort(
+    (left, right) => left.conceptId.localeCompare(right.conceptId)
+  );
+}
+function orphaned(bundle) {
+  const present = new Set(bundle.map((record) => record.conceptId));
+  const referenced = /* @__PURE__ */ new Set();
+  for (const record of bundle) {
+    for (const neighbour of edgeNeighbours(record, bundle, "body-link")) {
+      referenced.add(neighbour.conceptId);
+    }
+    for (const replaced of record.frontmatter.strauss_supersedes ?? []) {
+      referenced.add(replaced);
+    }
+    const replacement = record.frontmatter.strauss_superseded_by;
+    if (replacement && present.has(replacement)) {
+      referenced.add(record.conceptId);
+    }
+  }
+  return bundle.filter((record) => !referenced.has(record.conceptId)).map((record) => finding(record, "no other record links to it"));
+}
+var SUPERSESSION_CHECKS = /* @__PURE__ */ new Set([
+  "superseded_by",
+  "supersedes",
+  "backlink"
+]);
+function brokenSupersession(bundle, adjudicated) {
+  const byId = new Map(bundle.map((record) => [record.conceptId, record]));
+  const findings = [];
+  const seen = /* @__PURE__ */ new Set();
+  const add = (record, note) => {
+    const key = `${record.conceptId}\0${note}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    findings.push(finding(record, note));
+  };
+  for (const problem of validateBundle(bundle)) {
+    if (!SUPERSESSION_CHECKS.has(problem.check)) continue;
+    const record = byId.get(problem.conceptId);
+    if (record) add(record, problem.note);
+  }
+  for (const record of bundle) {
+    const replacement = record.frontmatter.strauss_superseded_by;
+    if (!replacement) continue;
+    if (!byId.has(replacement)) {
+      add(record, `replacement ${replacement} is missing`);
+    } else if (record.frontmatter.strauss_status !== "superseded") {
+      add(
+        record,
+        `names ${replacement} as its replacement but is not marked superseded`
+      );
+    }
+  }
+  for (const hit of adjudicated) {
+    for (const warning of hit.warnings) {
+      if (warning.kind === "broken-chain") {
+        add(hit.record, `replacement ${warning.missing} is missing`);
+      } else if (warning.kind === "chain-cycle") {
+        add(
+          hit.record,
+          `supersession chain cycles through ${warning.through.join(" \u2192 ")}`
+        );
+      } else if (warning.kind === "forked-chain") {
+        add(
+          hit.record,
+          `two records claim to replace it: ${warning.heads.join(", ")}`
+        );
+      }
+    }
+  }
+  return findings.sort(
+    (left, right) => left.conceptId.localeCompare(right.conceptId)
+  );
+}
+function supersededButCited(bundle, standings) {
+  const byId = new Map(bundle.map((record) => [record.conceptId, record]));
+  const findings = [];
+  for (const record of bundle) {
+    const standing = standings.get(record.conceptId);
+    if (standing === "superseded" || standing === "rejected") continue;
+    for (const target of edgeNeighbours(record, bundle, "body-link")) {
+      const targetStanding = standings.get(target.conceptId);
+      if (targetStanding !== "superseded" && targetStanding !== "rejected") {
+        continue;
+      }
+      if (replaces(record, target)) continue;
+      const replacement = target.frontmatter.strauss_superseded_by;
+      findings.push(
+        finding(
+          record,
+          `cites ${targetStanding} ${target.conceptId}${targetStanding === "superseded" && replacement && byId.has(replacement) ? ` \u2014 replaced by ${replacement}` : ""}`
+        )
+      );
+    }
+  }
+  return findings;
+}
+function replaces(later, earlier) {
+  return (later.frontmatter.strauss_supersedes ?? []).includes(earlier.conceptId) || earlier.frontmatter.strauss_superseded_by === later.conceptId;
+}
+function finding(record, note) {
+  return {
+    conceptId: record.conceptId,
+    title: record.frontmatter.title ?? null,
+    status: record.frontmatter.strauss_status,
+    note
+  };
+}
+function daysBetween(from, to) {
+  return Math.max(0, Math.floor((to - from) / DAY_MS));
+}
+function ageInDays(record, now) {
+  const at = record.frontmatter.generated?.at;
+  if (!at) return null;
+  const written = Date.parse(at);
+  if (Number.isNaN(written)) return null;
+  return daysBetween(written, now.getTime());
+}
+
+// src/commands/doctor.ts
+var days = (what, fallback) => import_zod8.z.number().int().positive().optional().describe(`${what} Defaults to ${fallback}.`);
+var doctorCommand = define({
+  name: "doctor",
+  tool: "kb_doctor",
+  usage: "doctor [--expiring-days N] [--unverified-days N] [--aging-days N] [--strict]",
+  description: "A health sweep over a whole base: what the calendar has already retired, what nobody ever confirmed, what has been open or proposed long enough that the status is now the answer, and what the graph has dropped on the floor. Read-only \u2014 it never writes, never supersedes, and never re-dates anything; every finding names a record for a person to repair. Seven checks, grouped and counted: expired (past `stale_after`), expiring (inside the window), unverified (an empty `verified[]` on a record old enough to matter), aging (still `open` or `proposed`), orphaned (no other record links to it), broken supersession (a chain that does not resolve), and superseded-but-cited (a live record whose body links to a record that no longer holds). Every group is reported even when empty, because a check that found nothing and a check that never ran look identical in a report that only lists findings.\n\nThis is the question no reader thinks to ask, which is why it needs a command: decay is invisible from inside a single record \u2014 a stale one reads exactly like a live one, and a question nobody answered reads exactly like one nobody asked. Reach for it when picking up a base someone else kept, before trusting a base you have not touched in months, or on a schedule; kb_validate is the narrower neighbour, checking only whether pointers between records agree.",
+  input: import_zod8.z.object({
+    bundlePath,
+    expiringDays: days(
+      "How far ahead `expiring` looks, in days.",
+      DEFAULT_EXPIRING_DAYS
+    ),
+    unverifiedDays: days(
+      "How old an unconfirmed record must be before `unverified` reports it, in days.",
+      DEFAULT_UNVERIFIED_DAYS
+    ),
+    agingDays: days(
+      "How long a record may stay `open` or `proposed` before `aging` reports it, in days.",
+      DEFAULT_AGING_DAYS
+    ),
+    strict: import_zod8.z.boolean().optional().describe(
+      "Turn an expired record into a non-zero exit for the CLI. No effect on the report itself."
+    )
+  }),
+  // Presence, not truthiness: `--expiring-days ""` is a caller who meant
+  // something and mistyped it, and a falsy test would answer by quietly
+  // sweeping at the default. Passed through as given, the schema rejects it
+  // and says which field.
+  fromArgv: (argv, path) => {
+    const expiring2 = argvFlag(argv, "--expiring-days");
+    const unverified2 = argvFlag(argv, "--unverified-days");
+    const agingDays = argvFlag(argv, "--aging-days");
+    return {
+      bundlePath: path,
+      ...expiring2 !== void 0 ? { expiringDays: Number(expiring2) } : {},
+      ...unverified2 !== void 0 ? { unverifiedDays: Number(unverified2) } : {},
+      ...agingDays !== void 0 ? { agingDays: Number(agingDays) } : {},
+      ...argv.includes("--strict") ? { strict: true } : {}
+    };
+  },
+  run: async ({ store, now }, { bundlePath: path, expiringDays, unverifiedDays, agingDays }) => {
+    const checkedAt = now();
+    const report = doctor(await store.list(path), {
+      ...expiringDays !== void 0 ? { expiringDays } : {},
+      ...unverifiedDays !== void 0 ? { unverifiedDays } : {},
+      ...agingDays !== void 0 ? { agingDays } : {},
+      now: new Date(checkedAt)
+    });
+    return { bundlePath: path, checkedAt, ...report };
+  },
+  render: (result) => render(result),
+  // Only expiry, and only under --strict. The other six checks report debt a
+  // reader decides about; an expired record is the base asserting something it
+  // already said it would stop standing behind, which is the one finding a
+  // pipeline can act on without a judgment call.
+  failsWhen: (result, input) => input.strict === true && result.counts.expired > 0
+});
+function render(result) {
+  const { thresholds } = result;
+  const lines = [
+    `# KB Doctor \u2014 ${result.bundlePath}`,
+    `records: ${result.recordCount}`,
+    `thresholds: expiring within ${thresholds.expiringDays}d, unverified over ${thresholds.unverifiedDays}d, aging over ${thresholds.agingDays}d`,
+    `checked: ${result.checkedAt}`,
+    ""
+  ];
+  const width = Math.max(...result.groups.map((group2) => group2.check.length));
+  for (const group2 of result.groups) {
+    lines.push(
+      `  ${group2.check.padEnd(width)}  ${String(group2.count).padStart(3)}  ${group2.headline}`
+    );
+  }
+  for (const group2 of result.groups) {
+    if (!group2.count) continue;
+    lines.push("", `## ${group2.check} (${group2.count})`);
+    for (const found of group2.findings) {
+      lines.push(
+        `- ${found.conceptId}${found.title ? ` \u2014 ${found.title}` : ""}: ${found.note}`
+      );
+    }
+  }
+  lines.push(
+    "",
+    result.healthy ? "Nothing to repair." : `${result.findingCount} finding${result.findingCount === 1 ? "" : "s"} across ${result.groups.filter((group2) => group2.count).length} of ${result.groups.length} checks.`
+  );
+  return lines.join("\n");
+}
+
+// src/commands/list.ts
+var import_zod9 = require("zod");
 var listCommand = define({
   name: "list",
   tool: "kb_list",
   usage: "list [type]",
   description: "Every record, optionally narrowed to one type. Use kb_query when you have a question; this is for enumerating.",
-  input: import_zod8.z.object({ bundlePath, type: import_zod8.z.enum(KB_RECORD_TYPES).optional() }),
+  input: import_zod9.z.object({ bundlePath, type: import_zod9.z.enum(KB_RECORD_TYPES).optional() }),
   fromArgv: (argv, path) => ({ bundlePath: path, type: argv[1] }),
   run: async ({ store }, { bundlePath: path, type }) => (await store.list(path, type)).map((record) => ({
     conceptId: record.conceptId,
@@ -1074,17 +1520,17 @@ var listCommand = define({
 });
 
 // src/commands/load.ts
-var import_zod9 = require("zod");
+var import_zod10 = require("zod");
 var loadCommand = define({
   name: "load",
   tool: "kb_load",
   usage: "load [type] [--budget N | --all]",
   description: "Load the whole knowledge base at once, each record with its standing. Prefer this over searching: these bases run to a few thousand tokens, and a reader holding all of it has perfect recall and knows why it is asking, which no ranker does. Superseded records arrive under `superseded` as name, replacement and date only \u2014 their bodies no longer hold, and reading one later in a long session is the mistake this prevents; pass the id to kb_trace when you need the history. Rejected and unresolved records arrive whole: what was turned down, and what is still open, is the part a diff cannot show you. Refuses with a count rather than truncating when the base is too large \u2014 a truncated base is indistinguishable from a complete one, and would have you conclude something was never decided from a slice you did not know was a slice. Call at the point of use, not once per session: a base loaded early is summarised away by compaction, so if the visible context holds no records from this base and the question at hand is one it might govern, load before answering \u2014 never conclude nothing was decided from a context with no KB content in it. This tool (with kb_query and kb_trace) is the only supported way to read a base; a raw file read bypasses supersession resolution and returns replaced records as if current.\n\nThat refusal is the default guardrail, meant for an agent that would otherwise burn its whole context on one call. `all` bypasses it and loads everything regardless of size: a deliberate operator with the budget to spend, not something to reach for automatically. It is mutually exclusive with `budgetTokens`. When the reader does not need everything, kb_query or a narrower `type` filter is the better fit than either.",
-  input: import_zod9.z.object({
+  input: import_zod10.z.object({
     bundlePath,
-    type: import_zod9.z.enum(KB_RECORD_TYPES).optional(),
-    budgetTokens: import_zod9.z.number().int().positive().optional().describe("Approximate token ceiling. Defaults to 25000."),
-    all: import_zod9.z.boolean().optional().describe(
+    type: import_zod10.z.enum(KB_RECORD_TYPES).optional(),
+    budgetTokens: import_zod10.z.number().int().positive().optional().describe("Approximate token ceiling. Defaults to 25000."),
+    all: import_zod10.z.boolean().optional().describe(
       "Load the entire base regardless of size. The deliberate-operator escape hatch; mutually exclusive with budgetTokens."
     )
   }).refine((value) => !(value.all && value.budgetTokens !== void 0), {
@@ -1122,25 +1568,25 @@ var loadCommand = define({
 });
 
 // src/commands/log.ts
-var import_zod10 = require("zod");
+var import_zod11 = require("zod");
 var logCommand = define({
   name: "log",
   tool: "kb_log",
   usage: "log",
   description: "What touched what, and when. The only artifact here that cannot be reconstructed from the records, so malformed lines are reported rather than repaired.",
-  input: import_zod10.z.object({ bundlePath }),
+  input: import_zod11.z.object({ bundlePath }),
   fromArgv: (_argv, path) => ({ bundlePath: path }),
   run: ({ store }, { bundlePath: path }) => store.readLog(path)
 });
 
 // src/commands/no-decision.ts
-var import_zod11 = require("zod");
+var import_zod12 = require("zod");
 var noDecisionCommand = define({
   name: "no-decision",
   tool: "kb_no_decision",
   usage: "no-decision <reason...>",
   description: 'Claim in one sentence that there was nothing to decide. Gating on "did you write a decision?" rewards writing a junk one; gating on "did you answer?" does not, so silence has to be expressible. Idempotent \u2014 restating it is not a collision.',
-  input: import_zod11.z.object({ bundlePath, reason: import_zod11.z.string().min(1) }),
+  input: import_zod12.z.object({ bundlePath, reason: import_zod12.z.string().min(1) }),
   fromArgv: (argv, path) => ({
     bundlePath: path,
     reason: argv.slice(1).join(" ").trim()
@@ -1157,20 +1603,20 @@ var noDecisionCommand = define({
 });
 
 // src/commands/pack.ts
-var import_zod12 = require("zod");
+var import_zod13 = require("zod");
 var packCommand = define({
   name: "pack",
   tool: "kb_pack",
   usage: "pack <conceptId> [--hops N] [--max-nodes N] [--budget N]",
   description: "The bounded neighbourhood around one record: everything within `hops` of the root, ranked and cut to `maxNodes`, with every cut record named under Excluded \u2014 a named gap is knowable, a silent one is not. Prefer this over kb_load when the base is too large to hold whole and the work centres on one record; prefer it over kb_query when the question needs the governed neighbourhood \u2014 what was settled and what binds near this record \u2014 rather than a lookup by wording. Superseded records arrive as name, replacement and date stubs exactly as kb_load emits them: their bodies no longer hold, and kb_trace has the history. Refuses outright rather than truncating when the pack would exceed its token budget \u2014 a partial pack is indistinguishable from a complete one \u2014 reporting the record count and every already-cut id so the caller can lower hops or maxNodes, or raise the budget. The header carries the bundle, root, budget and a timestamp; everything below the header is byte-identical across runs over an unchanged base, so two packs can be diffed and a changed byte means changed knowledge. This tool (with kb_load, kb_query and kb_trace) is the only supported way to read a base; a raw file read bypasses supersession resolution and returns replaced records as if current.",
-  input: import_zod12.z.object({
+  input: import_zod13.z.object({
     bundlePath,
     conceptId,
-    hops: import_zod12.z.number().int().positive().optional().describe("How far from the root the walk may reach. Defaults to 2."),
-    maxNodes: import_zod12.z.number().int().positive().optional().describe(
+    hops: import_zod13.z.number().int().positive().optional().describe("How far from the root the walk may reach. Defaults to 2."),
+    maxNodes: import_zod13.z.number().int().positive().optional().describe(
       "How many records the pack may hold, root included. Defaults to 20."
     ),
-    budgetTokens: import_zod12.z.number().int().positive().optional().describe(
+    budgetTokens: import_zod13.z.number().int().positive().optional().describe(
       "Approximate token ceiling over what is actually emitted. Defaults to 25000."
     )
   }),
@@ -1192,10 +1638,10 @@ var packCommand = define({
       ...maxNodes !== void 0 ? { maxNodes } : {},
       ...budgetTokens !== void 0 ? { budgetTokens } : {}
     });
-    return render(result, path, now());
+    return render2(result, path, now());
   }
 });
-function render(result, bundle, at) {
+function render2(result, bundle, at) {
   const lines = [
     `# KB Pack \u2014 ${result.root}`,
     `bundle: ${bundle}`,
@@ -1257,22 +1703,22 @@ function warningLabel(warning) {
 }
 
 // src/commands/pin.ts
-var import_zod13 = require("zod");
+var import_zod14 = require("zod");
 var pinCommand = define({
   name: "pin",
   tool: "kb_pin",
   usage: "pin [bundle-path] [--mode full|index] [--profiles a,b] [--local|--user] [--frozen|--unfreeze]",
   description: "Pin a base into a workspace pin manifest, so `context` surfaces it at every context birth. Three layers, nearest wins: the committed project manifest (.strauss/kb-pins.json, the default), `--local` (.strauss/kb-pins.local.json, personal and gitignored), and `--user` (~/.strauss/kb-pins.json, every workspace). Idempotent \u2014 re-pinning changes nothing unless --mode, --profiles, or --frozen/--unfreeze are given, which update just those fields. `--mode full` preloads the whole base into the block regardless of the full-under threshold; `--mode index` never upgrades. `--profiles` scopes the pin to named context profiles. `--frozen` marks the base concluded: write commands against it refuse and `context` labels it read-only. A path with no records yet succeeds with a warning; bases are routinely pinned before they are populated. Pins are workspace state: the pinned base itself is never touched.",
-  input: import_zod13.z.object({
+  input: import_zod14.z.object({
     bundlePath,
-    mode: import_zod13.z.enum(["full", "index"]).optional().describe(
+    mode: import_zod14.z.enum(["full", "index"]).optional().describe(
       "full: always emit this base's records whole (still under the block budget); index: never upgrade. Absent: the profile's full-under threshold decides."
     ),
-    profiles: import_zod13.z.array(import_zod13.z.string()).optional().describe("Context profiles this pin surfaces in. Absent: all of them."),
-    layer: import_zod13.z.enum(["project", "local", "user"]).optional().describe(
+    profiles: import_zod14.z.array(import_zod14.z.string()).optional().describe("Context profiles this pin surfaces in. Absent: all of them."),
+    layer: import_zod14.z.enum(["project", "local", "user"]).optional().describe(
       "Which manifest to write: project (committed, default), local (personal, gitignored), user (~/.strauss, every workspace)."
     ),
-    frozen: import_zod13.z.boolean().optional().describe(
+    frozen: import_zod14.z.boolean().optional().describe(
       "true: the base is concluded \u2014 writes against it refuse while pinned. false: lift a freeze."
     )
   }),
@@ -1301,29 +1747,29 @@ var pinCommand = define({
 });
 
 // src/commands/pins.ts
-var import_zod14 = require("zod");
+var import_zod15 = require("zod");
 var pinsCommand = define({
   name: "pins",
   tool: "kb_pins",
   usage: "pins",
   description: "Every pinned base across the manifest layers, each with its layer and whether it currently resolves to readable records. Reads the workspace manifests rather than any one base, like kb_context.",
-  input: import_zod14.z.object({}),
+  input: import_zod15.z.object({}),
   fromArgv: () => ({}),
   run: ({ store }) => listPins(store, process.cwd())
 });
 
 // src/commands/query.ts
-var import_zod15 = require("zod");
+var import_zod16 = require("zod");
 var queryCommand = define({
   name: "query",
   tool: "kb_query",
   usage: "query <text...>",
   description: "Search and return each match with its standing. Results are flagged, never filtered: a superseded record comes back alongside whatever replaced it, and a rejected one is marked as something explicitly not adopted. Prefer kb_load when the base fits its budget: on this package's measurements, a reader holding the whole base answered eight of nine questions whose wording appears in no record, where embedding search answered four. Never read record files directly \u2014 this tool (with kb_load and kb_trace) is the only supported way to read a base; a file read bypasses supersession resolution and returns replaced records as if current.",
-  input: import_zod15.z.object({
+  input: import_zod16.z.object({
     bundlePath,
-    text: import_zod15.z.string().optional(),
-    type: import_zod15.z.enum(KB_RECORD_TYPES).optional(),
-    includeNonCurrent: import_zod15.z.boolean().optional()
+    text: import_zod16.z.string().optional(),
+    type: import_zod16.z.enum(KB_RECORD_TYPES).optional(),
+    includeNonCurrent: import_zod16.z.boolean().optional()
   }),
   fromArgv: (argv, path) => ({
     bundlePath: path,
@@ -1345,33 +1791,33 @@ var queryCommand = define({
 });
 
 // src/commands/read-index.ts
-var import_zod16 = require("zod");
+var import_zod17 = require("zod");
 var readIndexCommand = define({
   name: "index",
   tool: "kb_index",
   usage: "index",
   description: "The index, rebuilt if it disagrees with the records. One call gives the whole shape of the base: title, type, status, and description per record. The cheap re-orientation call after compaction or deep in a long session \u2014 a few hundred tokens; call it (or kb_context, when bases are pinned) first, then kb_load or fetch by concept id.",
-  input: import_zod16.z.object({ bundlePath }),
+  input: import_zod17.z.object({ bundlePath }),
   fromArgv: (_argv, path) => ({ bundlePath: path }),
   run: ({ store }, { bundlePath: path }) => store.readIndex(path)
 });
 
 // src/commands/schema.ts
-var import_zod19 = require("zod");
+var import_zod20 = require("zod");
 
 // src/json-schema.ts
-var import_zod18 = require("zod");
+var import_zod19 = require("zod");
 
 // src/kb-log.ts
-var import_zod17 = require("zod");
+var import_zod18 = require("zod");
 var LOG_FILE = "log.jsonl";
-var kbLogEntrySchema = import_zod17.z.object({
-  at: import_zod17.z.string().min(1),
-  by: import_zod17.z.string().min(1),
-  operation: import_zod17.z.string().min(1),
-  conceptId: import_zod17.z.string().min(1),
+var kbLogEntrySchema = import_zod18.z.object({
+  at: import_zod18.z.string().min(1),
+  by: import_zod18.z.string().min(1),
+  operation: import_zod18.z.string().min(1),
+  conceptId: import_zod18.z.string().min(1),
   /** Second concept id, where the operation relates two — supersession. */
-  target: import_zod17.z.string().min(1).optional()
+  target: import_zod18.z.string().min(1).optional()
 }).strict();
 function renderLogEntry(entry) {
   return `${JSON.stringify(kbLogEntrySchema.parse(entry))}
@@ -1402,11 +1848,11 @@ function parseLog(raw) {
 // src/json-schema.ts
 function kbJsonSchemas() {
   return {
-    recordFrontmatter: import_zod18.z.toJSONSchema(kbRecordFrontmatterSchema, {
+    recordFrontmatter: import_zod19.z.toJSONSchema(kbRecordFrontmatterSchema, {
       io: "input"
     }),
-    composeInput: import_zod18.z.toJSONSchema(composeInputSchema, { io: "input" }),
-    logEntry: import_zod18.z.toJSONSchema(kbLogEntrySchema, { io: "input" })
+    composeInput: import_zod19.z.toJSONSchema(composeInputSchema, { io: "input" }),
+    logEntry: import_zod19.z.toJSONSchema(kbLogEntrySchema, { io: "input" })
   };
 }
 
@@ -1416,22 +1862,22 @@ var schemaCommand = define({
   tool: "kb_schema",
   usage: "schema",
   description: "JSON Schema for the frontmatter, the write input, and log entries \u2014 generated from the code that enforces them, so it cannot drift from what a write will accept.",
-  input: import_zod19.z.object({}),
+  input: import_zod20.z.object({}),
   fromArgv: () => ({}),
   run: () => Promise.resolve(kbJsonSchemas())
 });
 
 // src/commands/status.ts
-var import_zod20 = require("zod");
+var import_zod21 = require("zod");
 var statusCommand = define({
   name: "status",
   tool: "kb_status",
   usage: "status <concept-id> <status>",
   description: "Move a record's status, leaving everything else alone. Uses a compare-and-swap, so a concurrent change fails loudly rather than being overwritten.",
-  input: import_zod20.z.object({
+  input: import_zod21.z.object({
     bundlePath,
     conceptId,
-    status: import_zod20.z.enum(KB_RECORD_STATUSES)
+    status: import_zod21.z.enum(KB_RECORD_STATUSES)
   }),
   fromArgv: (argv, path) => ({
     bundlePath: path,
@@ -1446,13 +1892,13 @@ var statusCommand = define({
 });
 
 // src/commands/supersede.ts
-var import_zod21 = require("zod");
+var import_zod22 = require("zod");
 var supersedeCommand = define({
   name: "supersede",
   tool: "kb_supersede",
   usage: "supersede <concept-id> <replacement-id>",
   description: "Mark a record superseded by another, linking both directions. Use this rather than editing a record whose meaning changed \u2014 a record that quietly becomes something else invalidates every reference to it, and the earlier understanding is what a later trace needs.",
-  input: import_zod21.z.object({ bundlePath, conceptId, replacementId: conceptId }),
+  input: import_zod22.z.object({ bundlePath, conceptId, replacementId: conceptId }),
   fromArgv: (argv, path) => ({
     bundlePath: path,
     conceptId: argv[1],
@@ -1466,16 +1912,16 @@ var supersedeCommand = define({
 });
 
 // src/commands/sync-instructions.ts
-var import_zod22 = require("zod");
+var import_zod23 = require("zod");
 var syncInstructionsCommand = define({
   name: "sync-instructions",
   usage: "sync-instructions <file> [--profile NAME] [--budget N] [--full-under N]",
   description: "Idempotently plant the `context` block between sentinel comments in an instruction file (AGENTS.md, CLAUDE.md), creating the block when absent and leaving everything outside the sentinels alone. CLI-only: this is file plumbing for runtimes whose instruction files are re-read where their conversations are not, not an agent capability \u2014 the capability is kb_context.",
-  input: import_zod22.z.object({
-    file: import_zod22.z.string().min(1).describe("The instruction file to edit in place."),
-    budgetTokens: import_zod22.z.number().int().positive().optional(),
-    fullUnderTokens: import_zod22.z.number().int().positive().optional(),
-    profile: import_zod22.z.string().optional()
+  input: import_zod23.z.object({
+    file: import_zod23.z.string().min(1).describe("The instruction file to edit in place."),
+    budgetTokens: import_zod23.z.number().int().positive().optional(),
+    fullUnderTokens: import_zod23.z.number().int().positive().optional(),
+    profile: import_zod23.z.string().optional()
   }),
   fromArgv: (argv) => {
     const budget = argvFlag(argv, "--budget");
@@ -1501,83 +1947,7 @@ var syncInstructionsCommand = define({
 });
 
 // src/commands/trace.ts
-var import_zod23 = require("zod");
-
-// src/kb-edges.ts
-var KB_EDGE_KINDS = [
-  "body-link",
-  "supersession",
-  "anchor",
-  "source"
-];
-var BODY_LINK_TARGET = new RegExp(
-  `\\]\\((${KB_CONCEPT_ID_PATTERN.source.replace(/^\^|\$$/g, "")})\\.md\\)`,
-  "g"
-);
-function neighbours(from, bundle, kinds = KB_EDGE_KINDS) {
-  const found = /* @__PURE__ */ new Map();
-  for (const kind of kinds) {
-    for (const record of edgeNeighbours(from, bundle, kind)) {
-      const existing = found.get(record.conceptId);
-      if (existing) {
-        if (!existing.via.includes(kind)) existing.via.push(kind);
-        continue;
-      }
-      found.set(record.conceptId, { record, via: [kind] });
-    }
-  }
-  return [...found.values()];
-}
-function edgeNeighbours(from, bundle, kind) {
-  switch (kind) {
-    // A link whose target is not in the bundle is legal per compose.ts —
-    // records are routinely written before the ones they point at exist — so
-    // missing targets are skipped, never an error.
-    case "body-link": {
-      const targets = new Set(
-        [...from.body.matchAll(BODY_LINK_TARGET)].map((match) => match[1])
-      );
-      if (!targets.size) return [];
-      return bundle.filter(
-        (candidate) => candidate.conceptId !== from.conceptId && targets.has(candidate.conceptId)
-      );
-    }
-    // Both directions and both pointers: `supersede()` writes the pair, but a
-    // hand-edit can leave one side behind, and a walk trusting one pointer
-    // would miss a replacement the bundle openly declares.
-    case "supersession":
-      return bundle.filter(
-        (candidate) => candidate.conceptId !== from.conceptId && (candidate.conceptId === from.frontmatter.strauss_superseded_by || from.frontmatter.strauss_supersedes?.includes(
-          candidate.conceptId
-        ) || candidate.frontmatter.strauss_superseded_by === from.conceptId || candidate.frontmatter.strauss_supersedes?.includes(from.conceptId))
-      );
-    // The edge that answers "why is this code shaped this way": every record
-    // attached to the same file or symbol, whatever its standing.
-    case "anchor": {
-      const mine = from.frontmatter.strauss_anchors ?? [];
-      if (!mine.length) return [];
-      return bundle.filter(
-        (candidate) => candidate.conceptId !== from.conceptId && (candidate.frontmatter.strauss_anchors ?? []).some(
-          (theirs) => mine.some((ours) => anchorsTouch(ours, theirs))
-        )
-      );
-    }
-    case "source": {
-      const mine = new Set((from.frontmatter.sources ?? []).map((s) => s.id));
-      if (!mine.size) return [];
-      return bundle.filter(
-        (candidate) => candidate.conceptId !== from.conceptId && (candidate.frontmatter.sources ?? []).some(
-          (source) => mine.has(source.id)
-        )
-      );
-    }
-  }
-}
-function anchorsTouch(left, right) {
-  if (left.file !== right.file) return false;
-  if (!left.symbol || !right.symbol) return true;
-  return left.symbol === right.symbol;
-}
+var import_zod24 = require("zod");
 
 // src/trace.ts
 var TRACE_EDGES = ["supersession", "anchor", "source"];
@@ -1623,11 +1993,11 @@ var traceCommand = define({
   tool: "kb_trace",
   usage: "trace <concept-id> [edges...]",
   description: 'How a position was arrived at, as a timeline ordered by when each record was written. Deliberately includes rejected, draft, and superseded records \u2014 in a history those are the content, not noise. Follows supersession, shared code anchors, and shared sources. Use when the question is "why is this the way it is" rather than "what do we hold now". This tool (with kb_load and kb_query) is the only supported way to read a base; a raw file read bypasses supersession resolution and returns replaced records as if current.',
-  input: import_zod23.z.object({
+  input: import_zod24.z.object({
     bundlePath,
     conceptId,
-    edges: import_zod23.z.array(import_zod23.z.enum(TRACE_EDGES)).optional(),
-    depth: import_zod23.z.number().int().positive().optional()
+    edges: import_zod24.z.array(import_zod24.z.enum(TRACE_EDGES)).optional(),
+    depth: import_zod24.z.number().int().positive().optional()
   }),
   fromArgv: (argv, path) => ({
     bundlePath: path,
@@ -1649,90 +2019,53 @@ var traceCommand = define({
 });
 
 // src/commands/types.ts
-var import_zod24 = require("zod");
+var import_zod25 = require("zod");
 var typesCommand = define({
   name: "types",
   tool: "kb_types",
   usage: "types",
   description: "The twelve record types with their purpose, body sections, and starting status. Read this before writing rather than guessing headings \u2014 a section the type does not define is rejected.",
-  input: import_zod24.z.object({}),
+  input: import_zod25.z.object({}),
   fromArgv: () => ({}),
   run: () => Promise.resolve(RECORD_TYPES)
 });
 
 // src/commands/unpin.ts
-var import_zod25 = require("zod");
+var import_zod26 = require("zod");
 var unpinCommand = define({
   name: "unpin",
   tool: "kb_unpin",
   usage: "unpin [bundle-path]",
   description: "Remove a base from every pin manifest layer that holds it \u2014 project, local, and user \u2014 because unpinned means gone, not still injected from another file. Reports which layers were touched.",
-  input: import_zod25.z.object({ bundlePath }),
+  input: import_zod26.z.object({ bundlePath }),
   fromArgv: (argv, path) => ({ bundlePath: argv[1] ?? path }),
   run: (_ctx, { bundlePath: path }) => unpinBase(process.cwd(), path)
 });
 
 // src/commands/validate.ts
-var import_zod26 = require("zod");
-
-// src/validate.ts
-function validateBundle(records) {
-  const byId = new Map(records.map((record) => [record.conceptId, record]));
-  const problems = [];
-  const report = (check, conceptId2, note) => problems.push({ check, conceptId: conceptId2, note });
-  for (const record of records) {
-    const { conceptId: conceptId2, frontmatter: fm } = record;
-    if (!isKbRecordType(fm.type)) {
-      report("type", conceptId2, `unrecognised type "${fm.type}"`);
-    }
-    if (fm.strauss_status === "superseded") {
-      const by = fm.strauss_superseded_by;
-      if (!by) {
-        report("superseded_by", conceptId2, "superseded with no replacement");
-      } else if (!byId.has(by)) {
-        report("superseded_by", conceptId2, `replacement ${by} is missing`);
-      } else if (!byId.get(by)?.frontmatter.strauss_supersedes?.includes(conceptId2)) {
-        report("backlink", by, `does not list ${conceptId2} in supersedes`);
-      }
-    }
-    for (const old of fm.strauss_supersedes ?? []) {
-      const previous = byId.get(old);
-      if (!previous) {
-        report("supersedes", conceptId2, `target ${old} is missing`);
-      } else if (previous.frontmatter.strauss_status !== "superseded") {
-        report("supersedes", conceptId2, `${old} is not marked superseded`);
-      }
-    }
-    if (fm.strauss_assumption && fm.sources?.length) {
-      report("assumption", conceptId2, "marked an assumption but cites sources");
-    }
-  }
-  return problems;
-}
-
-// src/commands/validate.ts
+var import_zod27 = require("zod");
 var validateCommand = define({
   name: "validate",
   tool: "kb_validate",
   usage: "validate",
   description: "Check pointers no single record can see: supersession links that disagree between the two records, and assumptions that cite sources. Per-record shape is enforced on every read, so a problem here means someone edited a file by hand.",
-  input: import_zod26.z.object({ bundlePath }),
+  input: import_zod27.z.object({ bundlePath }),
   fromArgv: (_argv, path) => ({ bundlePath: path }),
   run: async ({ store }, { bundlePath: path }) => validateBundle(await store.list(path)),
   failsWhen: (result) => Array.isArray(result) && result.length > 0
 });
 
 // src/commands/verify.ts
-var import_zod27 = require("zod");
+var import_zod28 = require("zod");
 var verifyCommand = define({
   name: "verify",
   tool: "kb_verify",
   usage: "verify <concept-id> --note <text>",
   description: "Append one verified[] event \u2014 who checked the record, when, and what the check found. Appends only; prior events are never rewritten. A record's own generator is refused unless the actor is human: re-reading your own output is not an independent check.",
-  input: import_zod27.z.object({
+  input: import_zod28.z.object({
     bundlePath,
     conceptId,
-    note: import_zod27.z.string().refine((s) => s.trim().length > 0, {
+    note: import_zod28.z.string().refine((s) => s.trim().length > 0, {
       message: "note must say what the check found"
     })
   }),
@@ -1752,7 +2085,7 @@ var verifyCommand = define({
 });
 
 // src/commands/write.ts
-var import_zod28 = require("zod");
+var import_zod29 = require("zod");
 var writeCommand = define({
   name: "write",
   tool: "kb_write",
@@ -1766,9 +2099,9 @@ var writeCommand = define({
     "- Prefer a new record over overloading an existing one, and keep each short. A record nobody finishes reading is not durable memory.",
     "- Records are never deleted; supersede instead, so the earlier reasoning stays inspectable."
   ].join("\n"),
-  input: import_zod28.z.object({
+  input: import_zod29.z.object({
     bundlePath,
-    type: import_zod28.z.enum(KB_RECORD_TYPES),
+    type: import_zod29.z.enum(KB_RECORD_TYPES),
     input: composeInputSchema
   }),
   fromArgv: async (argv, path, stdin) => ({
@@ -1792,7 +2125,7 @@ var writeCommand = define({
 });
 
 // src/commands/write-decision.ts
-var import_zod29 = require("zod");
+var import_zod30 = require("zod");
 var writeDecisionCommand = define({
   name: "write-decision",
   tool: "kb_write_decision",
@@ -1805,7 +2138,7 @@ var writeDecisionCommand = define({
     "- `alternative` is what you turned down and why, not a list of everything considered.",
     "- A reference to material you read goes in `sources`; a reference to code goes in `anchors`; a reference to another record goes in `relatedConceptIds`."
   ].join("\n"),
-  input: import_zod29.z.object({ bundlePath, input: decisionInputSchema }),
+  input: import_zod30.z.object({ bundlePath, input: decisionInputSchema }),
   fromArgv: async (_argv, path, stdin) => ({
     bundlePath: path,
     input: JSON.parse(await stdin())
@@ -1842,6 +2175,7 @@ var KB_COMMANDS = [
   readIndexCommand,
   logCommand,
   validateCommand,
+  doctorCommand,
   schemaCommand,
   pinCommand,
   unpinCommand,
@@ -2674,12 +3008,13 @@ function digest(contents) {
 }
 
 // src/version.ts
-var VERSION = true ? "0.1.7" : "0.0.0-dev";
+var VERSION = true ? "0.1.8" : "0.0.0-dev";
 
 // src/cli.ts
 async function runKbCli(argv) {
-  const { bundle, rest } = takeBundle(argv);
-  const name = rest[0] ?? "";
+  const { flags, literal } = takeLiteral(argv);
+  const { bundle, rest: withFlags } = takeBundle(flags);
+  const name = withFlags[0] ?? "";
   if (!name || name === "-h" || name === "--help") {
     process.stdout.write(usage());
     return;
@@ -2691,6 +3026,14 @@ async function runKbCli(argv) {
   }
   const command = KB_COMMANDS_BY_NAME.get(name);
   if (!command) die(`unknown command ${name}`);
+  const json = withFlags.includes("--json");
+  if (json && !command.render) {
+    die(`${name} takes no --json: its result is already the machine shape`);
+  }
+  const rest = [
+    ...json ? withFlags.filter((argument) => argument !== "--json") : withFlags,
+    ...literal
+  ];
   const raw = await command.fromArgv(rest, bundle, readStdin);
   const parsed = command.input.safeParse(raw);
   if (!parsed.success) {
@@ -2710,13 +3053,16 @@ async function runKbCli(argv) {
     },
     parsed.data
   );
-  if (command.failsWhen?.(result)) process.exitCode = 1;
+  if (command.failsWhen?.(result, parsed.data)) process.exitCode = 1;
   if (result === "") return;
-  process.stdout.write(
-    typeof result === "string" ? result.endsWith("\n") ? result : `${result}
-` : `${JSON.stringify(result, null, 2)}
-`
-  );
+  const text = command.render && !json ? command.render(result) : typeof result === "string" ? result : JSON.stringify(result, null, 2);
+  process.stdout.write(text.endsWith("\n") ? text : `${text}
+`);
+}
+function takeLiteral(argv) {
+  const at = argv.indexOf("--");
+  if (at === -1) return { flags: argv, literal: [] };
+  return { flags: argv.slice(0, at), literal: argv.slice(at + 1) };
 }
 function takeBundle(argv) {
   const at = argv.indexOf("--bundle");
@@ -2758,6 +3104,8 @@ function usage() {
     ),
     "",
     `  --bundle PATH  defaults to ./${KB_DIR}`,
+    "  --json         the machine shape, where a command prints a table",
+    "  --             everything after it is text, not flags",
     "  --version      the installed package version",
     "  STRAUSS_KB_ACTOR names the writer in the log",
     ""