@saasontools/strauss-kb 0.1.6 → 0.1.7

package/dist/cli-main.cjs

@@ -1156,23 +1156,123 @@ var noDecisionCommand = define({
   }
 });
 
-// src/commands/pin.ts
+// src/commands/pack.ts
 var import_zod12 = 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({
+    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(
+      "How many records the pack may hold, root included. Defaults to 20."
+    ),
+    budgetTokens: import_zod12.z.number().int().positive().optional().describe(
+      "Approximate token ceiling over what is actually emitted. Defaults to 25000."
+    )
+  }),
+  fromArgv: (argv, path) => {
+    const hops = argvFlag(argv, "--hops");
+    const maxNodes = argvFlag(argv, "--max-nodes");
+    const budget = argvFlag(argv, "--budget");
+    return {
+      bundlePath: path,
+      conceptId: argv[1],
+      ...hops ? { hops: Number(hops) } : {},
+      ...maxNodes ? { maxNodes: Number(maxNodes) } : {},
+      ...budget ? { budgetTokens: Number(budget) } : {}
+    };
+  },
+  run: async ({ store, now }, { bundlePath: path, conceptId: root, hops, maxNodes, budgetTokens }) => {
+    const result = await store.pack(path, root, {
+      ...hops !== void 0 ? { hops } : {},
+      ...maxNodes !== void 0 ? { maxNodes } : {},
+      ...budgetTokens !== void 0 ? { budgetTokens } : {}
+    });
+    return render(result, path, now());
+  }
+});
+function render(result, bundle, at) {
+  const lines = [
+    `# KB Pack \u2014 ${result.root}`,
+    `bundle: ${bundle}`,
+    `budget: ~${result.tokensLoaded} of ${result.budgetTokens} tokens, ${result.recordCount} records`,
+    `packed: ${at}`,
+    "",
+    `## Records (${result.records.length})`
+  ];
+  for (const record of result.records) {
+    lines.push(
+      "",
+      `### ${record.conceptId}${record.title ? ` \u2014 ${record.title}` : ""} [${record.standing}]`
+    );
+    if (record.warnings.length) {
+      lines.push(`warnings: ${record.warnings.map(warningLabel).join("; ")}`);
+    }
+    if (record.anchors.length) {
+      lines.push(
+        `anchors: ${record.anchors.map(
+          (anchor) => anchor.symbol ? `${anchor.file}#${anchor.symbol}` : anchor.file
+        ).join(", ")}`
+      );
+    }
+    lines.push("", record.body.trimEnd());
+  }
+  if (result.superseded.length) {
+    lines.push("", `## Superseded (${result.superseded.length})`);
+    for (const entry of result.superseded) {
+      lines.push(
+        `- ${entry.conceptId} \u2192 ${entry.supersededBy.join(", ") || "(no surviving head)"}${entry.at ? ` (${entry.at})` : ""}`
+      );
+    }
+  }
+  if (result.excluded.length) {
+    lines.push("", `## Excluded (${result.excluded.length})`);
+    for (const cut of result.excluded) lines.push(`- ${cut}`);
+  }
+  return lines.join("\n");
+}
+function warningLabel(warning) {
+  switch (warning.kind) {
+    case "superseded":
+      return `superseded by ${warning.by.join(", ")}`;
+    case "unsettled":
+      return `unsettled (${warning.status})`;
+    case "broken-chain":
+      return `broken chain \u2014 ${warning.missing} is not in the bundle`;
+    case "chain-cycle":
+      return `chain cycle through ${warning.through.join(" \u2192 ")}`;
+    case "forked-chain":
+      return `forked chain \u2014 heads ${warning.heads.join(", ")}`;
+    case "stale":
+      return `stale since ${warning.staleAfter}`;
+    case "unresolved-question":
+      return "unresolved question";
+    default:
+      return warning.kind;
+  }
+}
+
+// src/commands/pin.ts
+var import_zod13 = 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_zod12.z.object({
+  input: import_zod13.z.object({
     bundlePath,
-    mode: import_zod12.z.enum(["full", "index"]).optional().describe(
+    mode: import_zod13.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_zod12.z.array(import_zod12.z.string()).optional().describe("Context profiles this pin surfaces in. Absent: all of them."),
-    layer: import_zod12.z.enum(["project", "local", "user"]).optional().describe(
+    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(
       "Which manifest to write: project (committed, default), local (personal, gitignored), user (~/.strauss, every workspace)."
     ),
-    frozen: import_zod12.z.boolean().optional().describe(
+    frozen: import_zod13.z.boolean().optional().describe(
       "true: the base is concluded \u2014 writes against it refuse while pinned. false: lift a freeze."
     )
   }),
@@ -1201,29 +1301,29 @@ var pinCommand = define({
 });
 
 // src/commands/pins.ts
-var import_zod13 = require("zod");
+var import_zod14 = 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_zod13.z.object({}),
+  input: import_zod14.z.object({}),
   fromArgv: () => ({}),
   run: ({ store }) => listPins(store, process.cwd())
 });
 
 // src/commands/query.ts
-var import_zod14 = require("zod");
+var import_zod15 = 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_zod14.z.object({
+  input: import_zod15.z.object({
     bundlePath,
-    text: import_zod14.z.string().optional(),
-    type: import_zod14.z.enum(KB_RECORD_TYPES).optional(),
-    includeNonCurrent: import_zod14.z.boolean().optional()
+    text: import_zod15.z.string().optional(),
+    type: import_zod15.z.enum(KB_RECORD_TYPES).optional(),
+    includeNonCurrent: import_zod15.z.boolean().optional()
   }),
   fromArgv: (argv, path) => ({
     bundlePath: path,
@@ -1245,33 +1345,33 @@ var queryCommand = define({
 });
 
 // src/commands/read-index.ts
-var import_zod15 = require("zod");
+var import_zod16 = 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_zod15.z.object({ bundlePath }),
+  input: import_zod16.z.object({ bundlePath }),
   fromArgv: (_argv, path) => ({ bundlePath: path }),
   run: ({ store }, { bundlePath: path }) => store.readIndex(path)
 });
 
 // src/commands/schema.ts
-var import_zod18 = require("zod");
+var import_zod19 = require("zod");
 
 // src/json-schema.ts
-var import_zod17 = require("zod");
+var import_zod18 = require("zod");
 
 // src/kb-log.ts
-var import_zod16 = require("zod");
+var import_zod17 = require("zod");
 var LOG_FILE = "log.jsonl";
-var kbLogEntrySchema = import_zod16.z.object({
-  at: import_zod16.z.string().min(1),
-  by: import_zod16.z.string().min(1),
-  operation: import_zod16.z.string().min(1),
-  conceptId: import_zod16.z.string().min(1),
+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),
   /** Second concept id, where the operation relates two — supersession. */
-  target: import_zod16.z.string().min(1).optional()
+  target: import_zod17.z.string().min(1).optional()
 }).strict();
 function renderLogEntry(entry) {
   return `${JSON.stringify(kbLogEntrySchema.parse(entry))}
@@ -1302,11 +1402,11 @@ function parseLog(raw) {
 // src/json-schema.ts
 function kbJsonSchemas() {
   return {
-    recordFrontmatter: import_zod17.z.toJSONSchema(kbRecordFrontmatterSchema, {
+    recordFrontmatter: import_zod18.z.toJSONSchema(kbRecordFrontmatterSchema, {
       io: "input"
     }),
-    composeInput: import_zod17.z.toJSONSchema(composeInputSchema, { io: "input" }),
-    logEntry: import_zod17.z.toJSONSchema(kbLogEntrySchema, { io: "input" })
+    composeInput: import_zod18.z.toJSONSchema(composeInputSchema, { io: "input" }),
+    logEntry: import_zod18.z.toJSONSchema(kbLogEntrySchema, { io: "input" })
   };
 }
 
@@ -1316,22 +1416,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_zod18.z.object({}),
+  input: import_zod19.z.object({}),
   fromArgv: () => ({}),
   run: () => Promise.resolve(kbJsonSchemas())
 });
 
 // src/commands/status.ts
-var import_zod19 = require("zod");
+var import_zod20 = 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_zod19.z.object({
+  input: import_zod20.z.object({
     bundlePath,
     conceptId,
-    status: import_zod19.z.enum(KB_RECORD_STATUSES)
+    status: import_zod20.z.enum(KB_RECORD_STATUSES)
   }),
   fromArgv: (argv, path) => ({
     bundlePath: path,
@@ -1346,13 +1446,13 @@ var statusCommand = define({
 });
 
 // src/commands/supersede.ts
-var import_zod20 = require("zod");
+var import_zod21 = 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_zod20.z.object({ bundlePath, conceptId, replacementId: conceptId }),
+  input: import_zod21.z.object({ bundlePath, conceptId, replacementId: conceptId }),
   fromArgv: (argv, path) => ({
     bundlePath: path,
     conceptId: argv[1],
@@ -1366,16 +1466,16 @@ var supersedeCommand = define({
 });
 
 // src/commands/sync-instructions.ts
-var import_zod21 = require("zod");
+var import_zod22 = 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_zod21.z.object({
-    file: import_zod21.z.string().min(1).describe("The instruction file to edit in place."),
-    budgetTokens: import_zod21.z.number().int().positive().optional(),
-    fullUnderTokens: import_zod21.z.number().int().positive().optional(),
-    profile: import_zod21.z.string().optional()
+  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()
   }),
   fromArgv: (argv) => {
     const budget = argvFlag(argv, "--budget");
@@ -1401,43 +1501,50 @@ var syncInstructionsCommand = define({
 });
 
 // src/commands/trace.ts
-var import_zod22 = require("zod");
+var import_zod23 = require("zod");
 
-// src/trace.ts
-var TRACE_EDGES = ["supersession", "anchor", "source"];
-function trace(seedId, bundle, options = {}) {
-  const edges = options.edges?.length ? options.edges : TRACE_EDGES;
-  const maxDepth = options.depth ?? 3;
-  const byId = new Map(bundle.map((record) => [record.conceptId, record]));
-  const seed = byId.get(seedId);
-  if (!seed) return [];
-  const reached = /* @__PURE__ */ new Map([
-    [seedId, { record: seed, depth: 0, via: [] }]
-  ]);
-  let frontier = [seed];
-  for (let depth = 1; depth <= maxDepth && frontier.length; depth += 1) {
-    const next = [];
-    for (const from of frontier) {
-      for (const edge of edges) {
-        for (const record of neighbours(from, bundle, edge)) {
-          const existing = reached.get(record.conceptId);
-          if (existing) {
-            if (existing.depth > 0 && !existing.via.includes(edge)) {
-              existing.via.push(edge);
-            }
-            continue;
-          }
-          reached.set(record.conceptId, { record, depth, via: [edge] });
-          next.push(record);
-        }
+// 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] });
     }
-    frontier = next;
   }
-  return [...reached.values()].sort(byGeneratedAt);
+  return [...found.values()];
 }
-function neighbours(from, bundle, edge) {
-  switch (edge) {
+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(
@@ -1471,6 +1578,40 @@ function anchorsTouch(left, right) {
   if (!left.symbol || !right.symbol) return true;
   return left.symbol === right.symbol;
 }
+
+// src/trace.ts
+var TRACE_EDGES = ["supersession", "anchor", "source"];
+function trace(seedId, bundle, options = {}) {
+  const edges = options.edges?.length ? options.edges : TRACE_EDGES;
+  const maxDepth = options.depth ?? 3;
+  const byId = new Map(bundle.map((record) => [record.conceptId, record]));
+  const seed = byId.get(seedId);
+  if (!seed) return [];
+  const reached = /* @__PURE__ */ new Map([
+    [seedId, { record: seed, depth: 0, via: [] }]
+  ]);
+  let frontier = [seed];
+  for (let depth = 1; depth <= maxDepth && frontier.length; depth += 1) {
+    const next = [];
+    for (const from of frontier) {
+      for (const edge of edges) {
+        for (const record of edgeNeighbours(from, bundle, edge)) {
+          const existing = reached.get(record.conceptId);
+          if (existing) {
+            if (existing.depth > 0 && !existing.via.includes(edge)) {
+              existing.via.push(edge);
+            }
+            continue;
+          }
+          reached.set(record.conceptId, { record, depth, via: [edge] });
+          next.push(record);
+        }
+      }
+    }
+    frontier = next;
+  }
+  return [...reached.values()].sort(byGeneratedAt);
+}
 function byGeneratedAt(left, right) {
   const at = (step) => step.record.frontmatter.generated?.at ?? "";
   return at(left).localeCompare(at(right)) || left.depth - right.depth;
@@ -1482,11 +1623,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_zod22.z.object({
+  input: import_zod23.z.object({
     bundlePath,
     conceptId,
-    edges: import_zod22.z.array(import_zod22.z.enum(TRACE_EDGES)).optional(),
-    depth: import_zod22.z.number().int().positive().optional()
+    edges: import_zod23.z.array(import_zod23.z.enum(TRACE_EDGES)).optional(),
+    depth: import_zod23.z.number().int().positive().optional()
   }),
   fromArgv: (argv, path) => ({
     bundlePath: path,
@@ -1508,31 +1649,31 @@ var traceCommand = define({
 });
 
 // src/commands/types.ts
-var import_zod23 = require("zod");
+var import_zod24 = 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_zod23.z.object({}),
+  input: import_zod24.z.object({}),
   fromArgv: () => ({}),
   run: () => Promise.resolve(RECORD_TYPES)
 });
 
 // src/commands/unpin.ts
-var import_zod24 = require("zod");
+var import_zod25 = 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_zod24.z.object({ bundlePath }),
+  input: import_zod25.z.object({ bundlePath }),
   fromArgv: (argv, path) => ({ bundlePath: argv[1] ?? path }),
   run: (_ctx, { bundlePath: path }) => unpinBase(process.cwd(), path)
 });
 
 // src/commands/validate.ts
-var import_zod25 = require("zod");
+var import_zod26 = require("zod");
 
 // src/validate.ts
 function validateBundle(records) {
@@ -1575,23 +1716,23 @@ var validateCommand = define({
   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_zod25.z.object({ bundlePath }),
+  input: import_zod26.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_zod26 = require("zod");
+var import_zod27 = 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_zod26.z.object({
+  input: import_zod27.z.object({
     bundlePath,
     conceptId,
-    note: import_zod26.z.string().refine((s) => s.trim().length > 0, {
+    note: import_zod27.z.string().refine((s) => s.trim().length > 0, {
       message: "note must say what the check found"
     })
   }),
@@ -1611,7 +1752,7 @@ var verifyCommand = define({
 });
 
 // src/commands/write.ts
-var import_zod27 = require("zod");
+var import_zod28 = require("zod");
 var writeCommand = define({
   name: "write",
   tool: "kb_write",
@@ -1625,9 +1766,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_zod27.z.object({
+  input: import_zod28.z.object({
     bundlePath,
-    type: import_zod27.z.enum(KB_RECORD_TYPES),
+    type: import_zod28.z.enum(KB_RECORD_TYPES),
     input: composeInputSchema
   }),
   fromArgv: async (argv, path, stdin) => ({
@@ -1651,7 +1792,7 @@ var writeCommand = define({
 });
 
 // src/commands/write-decision.ts
-var import_zod28 = require("zod");
+var import_zod29 = require("zod");
 var writeDecisionCommand = define({
   name: "write-decision",
   tool: "kb_write_decision",
@@ -1664,7 +1805,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_zod28.z.object({ bundlePath, input: decisionInputSchema }),
+  input: import_zod29.z.object({ bundlePath, input: decisionInputSchema }),
   fromArgv: async (_argv, path, stdin) => ({
     bundlePath: path,
     input: JSON.parse(await stdin())
@@ -1694,6 +1835,7 @@ var KB_COMMANDS = [
   answerCommand,
   verifyCommand,
   loadCommand,
+  packCommand,
   queryCommand,
   traceCommand,
   listCommand,
@@ -1827,6 +1969,27 @@ var KbSelfVerificationError = class extends BaseError {
   actor;
   generatedBy;
 };
+var KbPackBudgetExceededError = class extends BaseError {
+  constructor(recordCount, approxTokens2, budgetTokens, excluded) {
+    super({
+      message: `kb: a pack of ${recordCount} records is ~${approxTokens2} tokens against a budget of ${budgetTokens} \u2014 lower hops or maxNodes, or raise the budget`,
+      errorType: "KbPackBudgetExceeded" /* KbPackBudgetExceeded */,
+      code: 400,
+      fault: "User" /* User */,
+      retriable: false,
+      reportToUser: true,
+      details: { recordCount, approxTokens: approxTokens2, budgetTokens, excluded }
+    });
+    this.recordCount = recordCount;
+    this.approxTokens = approxTokens2;
+    this.budgetTokens = budgetTokens;
+    this.excluded = excluded;
+  }
+  recordCount;
+  approxTokens;
+  budgetTokens;
+  excluded;
+};
 var KbInvalidConceptIdError = class extends BaseError {
   constructor(message, details) {
     super({
@@ -1927,6 +2090,90 @@ async function loadQmd(logger) {
   }
 }
 
+// src/pack.ts
+var DEFAULT_PACK_HOPS = 2;
+var DEFAULT_PACK_MAX_NODES = 20;
+var TYPE_PRIORITY = [
+  "decision",
+  "constraint",
+  "requirement",
+  ...KB_RECORD_TYPES.filter(
+    (type) => !["decision", "constraint", "requirement"].includes(type)
+  )
+];
+function pack(bundle, rootId, options = {}) {
+  const hops = options.hops ?? DEFAULT_PACK_HOPS;
+  const maxNodes = options.maxNodes ?? DEFAULT_PACK_MAX_NODES;
+  const budgetTokens = options.budgetTokens ?? DEFAULT_LOAD_BUDGET;
+  const byId = new Map(bundle.map((record) => [record.conceptId, record]));
+  const root = byId.get(rootId);
+  if (!root) throw new KbRecordNotFoundError(rootId);
+  const reached = [{ record: root, depth: 0 }];
+  const seen = /* @__PURE__ */ new Set([rootId]);
+  let frontier = [root];
+  for (let depth = 1; frontier.length; depth += 1) {
+    const next = [];
+    for (const from of frontier) {
+      for (const { record } of neighbours(from, bundle)) {
+        if (seen.has(record.conceptId)) continue;
+        seen.add(record.conceptId);
+        reached.push({ record, depth });
+        next.push(record);
+      }
+    }
+    frontier = next;
+  }
+  reached.sort(byRank);
+  const within = reached.filter((entry) => entry.depth <= hops);
+  const kept = within.slice(0, maxNodes);
+  const excluded = [
+    ...within.slice(maxNodes),
+    ...reached.filter((entry) => entry.depth > hops)
+  ].map((entry) => entry.record.conceptId).sort();
+  const adjudicated = adjudicate(
+    kept.map((entry) => entry.record),
+    bundle
+  );
+  const superseded = adjudicated.filter((hit) => hit.standing === "superseded").map(stub);
+  const whole = adjudicated.filter((hit) => hit.standing !== "superseded");
+  const tokensLoaded = whole.reduce((total, hit) => total + estimateTokens(hit.record), 0) + superseded.reduce((total, entry) => total + estimateStubTokens(entry), 0);
+  const recordCount = adjudicated.length;
+  if (tokensLoaded > budgetTokens) {
+    throw new KbPackBudgetExceededError(
+      recordCount,
+      tokensLoaded,
+      budgetTokens,
+      excluded
+    );
+  }
+  return {
+    root: rootId,
+    records: whole.map((hit) => ({
+      conceptId: hit.record.conceptId,
+      title: hit.record.frontmatter.title ?? null,
+      standing: hit.standing,
+      supersededBy: hit.heads.map((head) => head.conceptId),
+      warnings: hit.warnings,
+      anchors: hit.record.frontmatter.strauss_anchors ?? [],
+      body: hit.record.body
+    })),
+    superseded,
+    excluded,
+    recordCount,
+    tokensLoaded,
+    budgetTokens
+  };
+}
+function byRank(left, right) {
+  return left.depth - right.depth || typeRank(left.record) - typeRank(right.record) || (left.record.frontmatter.title ?? "").localeCompare(
+    right.record.frontmatter.title ?? ""
+  ) || left.record.conceptId.localeCompare(right.record.conceptId);
+}
+function typeRank(record) {
+  const index = TYPE_PRIORITY.indexOf(record.frontmatter.type);
+  return index === -1 ? TYPE_PRIORITY.length : index;
+}
+
 // src/kb-store.ts
 var KB_DIR = (0, import_node_path6.join)(".strauss", "kb");
 var STORE_OWNED = /* @__PURE__ */ new Set([INDEX_FILE, LOG_FILE, SEARCH_INDEX_FILE]);
@@ -2216,6 +2463,10 @@ ${answer}
   async trace(bundlePath2, seedId, options = {}) {
     return trace(seedId, await this.list(bundlePath2), options);
   }
+  /** A bounded neighbourhood around one record. See `pack.ts`. */
+  async pack(bundlePath2, rootId, options = {}) {
+    return pack(await this.list(bundlePath2), rootId, options);
+  }
   /**
    * The stored index, rebuilt if it disagrees with the records.
    *
@@ -2422,6 +2673,9 @@ function digest(contents) {
   return (0, import_node_crypto.createHash)("sha256").update(contents).digest("hex");
 }
 
+// src/version.ts
+var VERSION = true ? "0.1.7" : "0.0.0-dev";
+
 // src/cli.ts
 async function runKbCli(argv) {
   const { bundle, rest } = takeBundle(argv);
@@ -2430,6 +2684,11 @@ async function runKbCli(argv) {
     process.stdout.write(usage());
     return;
   }
+  if (name === "--version" || name === "-v") {
+    process.stdout.write(`${VERSION}
+`);
+    return;
+  }
   const command = KB_COMMANDS_BY_NAME.get(name);
   if (!command) die(`unknown command ${name}`);
   const raw = await command.fromArgv(rest, bundle, readStdin);
@@ -2499,6 +2758,7 @@ function usage() {
     ),
     "",
     `  --bundle PATH  defaults to ./${KB_DIR}`,
+    "  --version      the installed package version",
     "  STRAUSS_KB_ACTOR names the writer in the log",
     ""
   ].join("\n");