@saasontools/strauss-kb 0.1.9 → 0.1.10

package/dist/{chunk-OFDWRMY6.js → chunk-EJQPZWN5.js}

@@ -586,6 +586,157 @@ async function unpinBase(workspaceDir, bundlePath2) {
   };
 }
 
+// src/errors.ts
+var Fault = /* @__PURE__ */ ((Fault2) => {
+  Fault2["Configuration"] = "Configuration";
+  Fault2["System"] = "System";
+  Fault2["User"] = "User";
+  return Fault2;
+})(Fault || {});
+var ErrorTypes = /* @__PURE__ */ ((ErrorTypes2) => {
+  ErrorTypes2["KbRecordAlreadyExists"] = "KbRecordAlreadyExists";
+  ErrorTypes2["KbInvalidConceptId"] = "KbInvalidConceptId";
+  ErrorTypes2["KbMissingFlagValue"] = "KbMissingFlagValue";
+  ErrorTypes2["KbPackBudgetExceeded"] = "KbPackBudgetExceeded";
+  ErrorTypes2["KbRecordNotFound"] = "KbRecordNotFound";
+  ErrorTypes2["KbSelfVerification"] = "KbSelfVerification";
+  ErrorTypes2["KbWriteConflict"] = "KbWriteConflict";
+  return ErrorTypes2;
+})(ErrorTypes || {});
+var BaseError = class extends Error {
+  code;
+  errorType;
+  fault;
+  retriable;
+  reportToUser;
+  details;
+  constructor(props) {
+    super(props.message);
+    this.name = props.name ?? this.constructor.name;
+    this.code = props.code ?? 500;
+    this.errorType = props.errorType;
+    this.fault = props.fault;
+    this.retriable = props.retriable ?? true;
+    this.reportToUser = props.reportToUser ?? false;
+    this.details = props.details;
+  }
+};
+
+// src/kb-errors.ts
+var KbRecordAlreadyExistsError = class extends BaseError {
+  constructor(conceptId2) {
+    super({
+      message: `kb: ${conceptId2} already exists \u2014 choose a more specific slug, or write with overwrite`,
+      errorType: "KbRecordAlreadyExists" /* KbRecordAlreadyExists */,
+      code: 409,
+      fault: "User" /* User */,
+      retriable: false,
+      reportToUser: true,
+      details: { conceptId: conceptId2, action: "refused" }
+    });
+    this.conceptId = conceptId2;
+  }
+  conceptId;
+};
+var KbRecordNotFoundError = class extends BaseError {
+  constructor(conceptId2) {
+    super({
+      message: `kb: ${conceptId2} does not exist`,
+      errorType: "KbRecordNotFound" /* KbRecordNotFound */,
+      code: 404,
+      fault: "User" /* User */,
+      retriable: false,
+      reportToUser: true,
+      details: { conceptId: conceptId2 }
+    });
+    this.conceptId = conceptId2;
+  }
+  conceptId;
+};
+var KbWriteConflictError = class extends BaseError {
+  constructor(conceptId2) {
+    super({
+      message: `kb: ${conceptId2} changed while it was being updated \u2014 re-read and retry`,
+      errorType: "KbWriteConflict" /* KbWriteConflict */,
+      code: 409,
+      fault: "System" /* System */,
+      retriable: true,
+      reportToUser: true,
+      details: { conceptId: conceptId2 }
+    });
+    this.conceptId = conceptId2;
+  }
+  conceptId;
+};
+var KbSelfVerificationError = class extends BaseError {
+  constructor(conceptId2, actor, generatedBy) {
+    super({
+      message: `kb: ${conceptId2} was generated by ${generatedBy}, and a record's generator cannot verify it \u2014 only a human or a different actor can`,
+      errorType: "KbSelfVerification" /* KbSelfVerification */,
+      code: 400,
+      fault: "User" /* User */,
+      retriable: false,
+      reportToUser: true,
+      details: { conceptId: conceptId2, actor, generatedBy, action: "refused" }
+    });
+    this.conceptId = conceptId2;
+    this.actor = actor;
+    this.generatedBy = generatedBy;
+  }
+  conceptId;
+  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 KbMissingFlagValueError = class extends BaseError {
+  constructor(flag) {
+    super({
+      message: `kb: ${flag} needs a value \u2014 pass ${flag} <value> or ${flag}=<value>`,
+      errorType: "KbMissingFlagValue" /* KbMissingFlagValue */,
+      code: 400,
+      fault: "User" /* User */,
+      retriable: false,
+      reportToUser: true,
+      details: { flag }
+    });
+    this.flag = flag;
+  }
+  flag;
+};
+var KbInvalidConceptIdError = class extends BaseError {
+  constructor(message, details) {
+    super({
+      message: `kb: ${message}`,
+      errorType: "KbInvalidConceptId" /* KbInvalidConceptId */,
+      code: 400,
+      fault: "User" /* User */,
+      retriable: false,
+      reportToUser: true,
+      details
+    });
+  }
+};
+
 // src/adjudicate.ts
 var STANDING = {
   accepted: "current",
@@ -678,6 +829,52 @@ function successors(record, byId) {
   return { records, missing };
 }
 
+// src/catalog.ts
+var EMPTY_STANDINGS = {
+  current: 0,
+  superseded: 0,
+  rejected: 0,
+  unsettled: 0,
+  open: 0
+};
+function catalog(bundle, options = {}) {
+  const wanted = options.type ? bundle.filter((record) => record.frontmatter.type === options.type) : bundle;
+  const entries = adjudicate(wanted, bundle, options.now ?? /* @__PURE__ */ new Date()).map((hit) => ({
+    conceptId: hit.record.conceptId,
+    type: hit.record.frontmatter.type,
+    title: hit.record.frontmatter.title ?? null,
+    standing: hit.standing,
+    supersededBy: hit.heads.map((head) => head.conceptId),
+    stale: hit.warnings.some((warning) => warning.kind === "stale")
+  })).sort(byTypeThenTitle);
+  const standings = { ...EMPTY_STANDINGS };
+  for (const entry of entries) standings[entry.standing] += 1;
+  return {
+    entries,
+    recordCount: entries.length,
+    standings,
+    currentCount: standings.current,
+    supersededCount: standings.superseded,
+    staleCount: entries.filter((entry) => entry.stale).length
+  };
+}
+function byTypeThenTitle(left, right) {
+  return byCodeUnit(left.type, right.type) || byCodeUnit(left.title ?? "", right.title ?? "") || byCodeUnit(left.conceptId, right.conceptId);
+}
+function byCodeUnit(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+function renderCatalogLine(entry) {
+  const parts = [
+    entry.conceptId,
+    entry.type,
+    entry.title ?? "(untitled)",
+    entry.standing === "superseded" ? `superseded \u2192 ${entry.supersededBy.join(", ") || "(no surviving head)"}` : entry.standing
+  ];
+  if (entry.stale) parts.push("stale");
+  return `- ${parts.join(" \xB7 ")}`;
+}
+
 // src/kb-index.ts
 var INDEX_FILE = "INDEX.md";
 var HEADING = "# KB Index";
@@ -1410,8 +1607,19 @@ function define(command) {
   return command;
 }
 function argvFlag(argv, name) {
+  const joined = argv.find((arg) => arg.startsWith(`${name}=`));
+  if (joined !== void 0) {
+    const value2 = joined.slice(name.length + 1);
+    if (!value2) throw new KbMissingFlagValueError(name);
+    return value2;
+  }
   const at = argv.indexOf(name);
-  return at !== -1 ? argv[at + 1] : void 0;
+  if (at === -1) return void 0;
+  const value = argv[at + 1];
+  if (value === void 0 || value.startsWith("--")) {
+    throw new KbMissingFlagValueError(name);
+  }
+  return value;
 }
 
 // src/commands/answer.ts
@@ -1433,27 +1641,90 @@ var answerCommand = define({
   }
 });
 
-// src/commands/context.ts
+// src/commands/catalog.ts
 import { z as z9 } from "zod";
+var catalogCommand = define({
+  name: "catalog",
+  tool: "kb_catalog",
+  usage: "catalog [type]",
+  description: "Lists every record as one line \u2014 concept id, type, title, standing, and a stale flag \u2014 at roughly thirty tokens each. Pick this over kb_load once kb_load refuses: kb_catalog never refuses. Superseded records show only their replacement; fetch bodies with kb_load, kb_pack, kb_query, or kb_trace.",
+  input: z9.object({
+    bundlePath,
+    type: z9.enum(KB_RECORD_TYPES).optional()
+  }),
+  fromArgv: (argv, path) => ({
+    bundlePath: path,
+    ...argv[1] && !argv[1].startsWith("--") ? { type: argv[1] } : {}
+  }),
+  run: async ({ store }, { bundlePath: path, type }) => render(
+    await store.catalog(path, { ...type ? { type } : {} }),
+    path,
+    type
+  )
+});
+function render(result, bundle, type) {
+  const lines = [
+    `# KB Catalog${type ? ` \u2014 ${type}` : ""}`,
+    `bundle: ${bundle}`,
+    `${count(result.recordCount, "record")}: ${standingCounts(result)}`
+  ];
+  if (result.staleCount) {
+    lines.push(
+      `${result.staleCount} stale \u2014 a flag over the standings above, not one of them`
+    );
+  }
+  lines.push("");
+  if (!result.entries.length) {
+    lines.push(
+      type ? `(no records of type ${type})` : "(no records \u2014 this base is empty)"
+    );
+  } else {
+    for (const entry of result.entries) lines.push(renderCatalogLine(entry));
+  }
+  lines.push(
+    "",
+    "Bodies are not here: kb_pack <conceptId> for the neighbourhood around one record, kb_load for the whole base when it fits the budget, kb_query for a lookup by wording, kb_trace <conceptId> for how a position was arrived at."
+  );
+  return lines.join("\n");
+}
+function standingCounts(result) {
+  const ORDER = [
+    "current",
+    "open",
+    "unsettled",
+    "rejected",
+    "superseded"
+  ];
+  const parts = ORDER.filter((standing) => result.standings[standing]).map(
+    (standing) => `${result.standings[standing]} ${standing}`
+  );
+  return parts.length ? parts.join(" \xB7 ") : "none";
+}
+function count(value, noun) {
+  return `${value} ${value === 1 ? noun : `${noun}s`}`;
+}
+
+// src/commands/context.ts
+import { z as z10 } from "zod";
 var contextCommand = define({
   name: "context",
   tool: "kb_context",
   usage: "context [--profile NAME] [--budget N] [--full-under N] [--format json] [--event NAME]",
   description: "The pinned-base index block, for injection at every context birth \u2014 startup, clear, resume, and after compaction. An index, not the content: concept ids, titles and standing, with the bodies left behind kb_load at the point of use. Emits nothing when nothing is pinned. Refuses with the list of bases and their sizes rather than truncating past its budget. Budgets resolve most-specific-first: explicit flags, then the workspace manifests' `context` tables (per profile, over their `default`), then the built-in profile (session-start, compact, turn), then package defaults \u2014 so a repo tunes its own numbers in .strauss/kb-pins.json without touching hook commands. Like kb_schema and kb_types this takes no bundlePath \u2014 it reads the workspace pin manifests, because which bases a session should see is workspace state, not a property of one base.",
-  input: z9.object({
-    budgetTokens: z9.number().int().positive().optional().describe(
+  input: z10.object({
+    budgetTokens: z10.number().int().positive().optional().describe(
       "Ceiling on the whole emitted block; past it the command refuses with a list of bases rather than truncating. Defaults to 4000."
     ),
-    fullUnderTokens: z9.number().int().positive().optional().describe(
+    fullUnderTokens: z10.number().int().positive().optional().describe(
       "Per-base rendering threshold, applied before the budget: a base whose complete load fits under this arrives as full records instead of index lines, and the whole block still answers to budgetTokens. Off by default \u2014 index-only is the safe default at a context birth, because injected bodies outlive the qualifiers on them; the session-start profile opts tiny bases in at 1500."
     ),
-    profile: z9.string().optional().describe(
+    profile: z10.string().optional().describe(
       "Named budget set: built-ins are session-start (full-under 1500), compact and turn (budget 2500); the manifests' `context` tables override per repo. Unknown names fall through to defaults rather than failing."
     ),
-    format: z9.enum(["markdown", "json"]).optional().describe(
+    format: z10.enum(["markdown", "json"]).optional().describe(
       "CLI envelope for hook protocols that require strict JSON on stdout. MCP callers omit this \u2014 the block itself is identical."
     ),
-    event: z9.string().optional().describe(
+    event: z10.string().optional().describe(
       "hookEventName stamped into the JSON envelope. Only meaningful with format=json."
     )
   }),
@@ -1489,14 +1760,14 @@ var contextCommand = define({
 });
 
 // src/commands/doctor.ts
-import { z as z10 } from "zod";
-var days = (what, fallback) => z10.number().int().positive().optional().describe(`${what} Defaults to ${fallback}.`);
+import { z as z11 } from "zod";
+var days = (what, fallback) => z11.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: z10.object({
+  input: z11.object({
     bundlePath,
     expiringDays: days(
       "How far ahead `expiring` looks, in days.",
@@ -1510,7 +1781,7 @@ var doctorCommand = define({
       "How long a record may stay `open` or `proposed` before `aging` reports it, in days.",
       DEFAULT_AGING_DAYS
     ),
-    strict: z10.boolean().optional().describe(
+    strict: z11.boolean().optional().describe(
       "Turn an expired record into a non-zero exit for the CLI. No effect on the report itself."
     )
   }),
@@ -1540,14 +1811,14 @@ var doctorCommand = define({
     });
     return { bundlePath: path, checkedAt, ...report };
   },
-  render: (result) => render(result),
+  render: (result) => render2(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) {
+function render2(result) {
   const { thresholds } = result;
   const lines = [
     `# KB Doctor \u2014 ${result.bundlePath}`,
@@ -1579,13 +1850,13 @@ function render(result) {
 }
 
 // src/commands/list.ts
-import { z as z11 } from "zod";
+import { z as z12 } from "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: z11.object({ bundlePath, type: z11.enum(KB_RECORD_TYPES).optional() }),
+  input: z12.object({ bundlePath, type: z12.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,
@@ -1597,21 +1868,21 @@ var listCommand = define({
 });
 
 // src/commands/load.ts
-import { z as z12 } from "zod";
+import { z as z13 } from "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: z12.object({
+  usage: "load [type] [--budget N] [--all]",
+  description: "Loads the whole knowledge base at once, each record with its standing. Superseded records arrive as stubs (name, replacement, date); rejected and open records arrive whole. Refuses past the token budget rather than truncating \u2014 call kb_catalog, then kb_pack on the record that matters, or narrow with `type`; kb_query for a lookup by wording. `all` bypasses the budget.",
+  input: z13.object({
     bundlePath,
-    type: z12.enum(KB_RECORD_TYPES).optional(),
-    budgetTokens: z12.number().int().positive().optional().describe("Approximate token ceiling. Defaults to 25000."),
-    all: z12.boolean().optional().describe(
-      "Load the entire base regardless of size. The deliberate-operator escape hatch; mutually exclusive with budgetTokens."
+    type: z13.enum(KB_RECORD_TYPES).optional(),
+    budgetTokens: z13.number().int().positive().optional().describe("Approximate token ceiling. Defaults to 25000."),
+    all: z13.boolean().optional().describe(
+      "Loads the entire base regardless of size, bypassing the token budget; mutually exclusive with budgetTokens."
     )
   }).refine((value) => !(value.all && value.budgetTokens !== void 0), {
-    message: "all and budgetTokens are mutually exclusive: pass a ceiling or none, not both."
+    message: "all is mutually exclusive with budgetTokens: pass a ceiling or none, not both."
   }),
   fromArgv: (argv, path) => {
     const budget = argvFlag(argv, "--budget");
@@ -1645,25 +1916,25 @@ var loadCommand = define({
 });
 
 // src/commands/log.ts
-import { z as z13 } from "zod";
+import { z as z14 } from "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: z13.object({ bundlePath }),
+  input: z14.object({ bundlePath }),
   fromArgv: (_argv, path) => ({ bundlePath: path }),
   run: ({ store }, { bundlePath: path }) => store.readLog(path)
 });
 
 // src/commands/no-decision.ts
-import { z as z14 } from "zod";
+import { z as z15 } from "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: z14.object({ bundlePath, reason: z14.string().min(1) }),
+  input: z15.object({ bundlePath, reason: z15.string().min(1) }),
   fromArgv: (argv, path) => ({
     bundlePath: path,
     reason: argv.slice(1).join(" ").trim()
@@ -1680,20 +1951,20 @@ var noDecisionCommand = define({
 });
 
 // src/commands/pack.ts
-import { z as z15 } from "zod";
+import { z as z16 } from "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: z15.object({
+  input: z16.object({
     bundlePath,
     conceptId,
-    hops: z15.number().int().positive().optional().describe("How far from the root the walk may reach. Defaults to 2."),
-    maxNodes: z15.number().int().positive().optional().describe(
+    hops: z16.number().int().positive().optional().describe("How far from the root the walk may reach. Defaults to 2."),
+    maxNodes: z16.number().int().positive().optional().describe(
       "How many records the pack may hold, root included. Defaults to 20."
     ),
-    budgetTokens: z15.number().int().positive().optional().describe(
+    budgetTokens: z16.number().int().positive().optional().describe(
       "Approximate token ceiling over what is actually emitted. Defaults to 25000."
     )
   }),
@@ -1715,10 +1986,10 @@ var packCommand = define({
       ...maxNodes !== void 0 ? { maxNodes } : {},
       ...budgetTokens !== void 0 ? { budgetTokens } : {}
     });
-    return render2(result, path, now());
+    return render3(result, path, now());
   }
 });
-function render2(result, bundle, at) {
+function render3(result, bundle, at) {
   const lines = [
     `# KB Pack \u2014 ${result.root}`,
     `bundle: ${bundle}`,
@@ -1780,22 +2051,22 @@ function warningLabel(warning) {
 }
 
 // src/commands/pin.ts
-import { z as z16 } from "zod";
+import { z as z17 } from "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: z16.object({
+  input: z17.object({
     bundlePath,
-    mode: z16.enum(["full", "index"]).optional().describe(
+    mode: z17.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: z16.array(z16.string()).optional().describe("Context profiles this pin surfaces in. Absent: all of them."),
-    layer: z16.enum(["project", "local", "user"]).optional().describe(
+    profiles: z17.array(z17.string()).optional().describe("Context profiles this pin surfaces in. Absent: all of them."),
+    layer: z17.enum(["project", "local", "user"]).optional().describe(
       "Which manifest to write: project (committed, default), local (personal, gitignored), user (~/.strauss, every workspace)."
     ),
-    frozen: z16.boolean().optional().describe(
+    frozen: z17.boolean().optional().describe(
       "true: the base is concluded \u2014 writes against it refuse while pinned. false: lift a freeze."
     )
   }),
@@ -1824,29 +2095,29 @@ var pinCommand = define({
 });
 
 // src/commands/pins.ts
-import { z as z17 } from "zod";
+import { z as z18 } from "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: z17.object({}),
+  input: z18.object({}),
   fromArgv: () => ({}),
   run: ({ store }) => listPins(store, process.cwd())
 });
 
 // src/commands/query.ts
-import { z as z18 } from "zod";
+import { z as z19 } from "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: z18.object({
+  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. This is the lookup-by-wording rung, and the narrowest of the three: use it when you know roughly what the record says. The decision rule around it \u2014 while the base fits kb_load's token budget, kb_load it whole, because 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; once kb_load refuses, kb_catalog for one line per record and then kb_pack on the record the work centres on; and kb_query when the question is a point lookup rather than a neighbourhood. A query cannot tell you that nothing was decided \u2014 it returns its nearest hit whatever the distance \u2014 so reach for kb_catalog when the question is what exists. Never read record files directly: this tool (with kb_load, kb_catalog, kb_pack 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: z19.object({
     bundlePath,
-    text: z18.string().optional(),
-    type: z18.enum(KB_RECORD_TYPES).optional(),
-    includeNonCurrent: z18.boolean().optional()
+    text: z19.string().optional(),
+    type: z19.enum(KB_RECORD_TYPES).optional(),
+    includeNonCurrent: z19.boolean().optional()
   }),
   fromArgv: (argv, path) => ({
     bundlePath: path,
@@ -1868,40 +2139,40 @@ var queryCommand = define({
 });
 
 // src/commands/read-index.ts
-import { z as z19 } from "zod";
+import { z as z20 } from "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: z19.object({ bundlePath }),
+  input: z20.object({ bundlePath }),
   fromArgv: (_argv, path) => ({ bundlePath: path }),
   run: ({ store }, { bundlePath: path }) => store.readIndex(path)
 });
 
 // src/commands/schema.ts
-import { z as z20 } from "zod";
+import { z as z21 } from "zod";
 var schemaCommand = define({
   name: "schema",
   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: z20.object({}),
+  input: z21.object({}),
   fromArgv: () => ({}),
   run: () => Promise.resolve(kbJsonSchemas())
 });
 
 // src/commands/status.ts
-import { z as z21 } from "zod";
+import { z as z22 } from "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: z21.object({
+  input: z22.object({
     bundlePath,
     conceptId,
-    status: z21.enum(KB_RECORD_STATUSES)
+    status: z22.enum(KB_RECORD_STATUSES)
   }),
   fromArgv: (argv, path) => ({
     bundlePath: path,
@@ -1916,13 +2187,13 @@ var statusCommand = define({
 });
 
 // src/commands/supersede.ts
-import { z as z22 } from "zod";
+import { z as z23 } from "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: z22.object({ bundlePath, conceptId, replacementId: conceptId }),
+  input: z23.object({ bundlePath, conceptId, replacementId: conceptId }),
   fromArgv: (argv, path) => ({
     bundlePath: path,
     conceptId: argv[1],
@@ -1936,16 +2207,16 @@ var supersedeCommand = define({
 });
 
 // src/commands/sync-instructions.ts
-import { z as z23 } from "zod";
+import { z as z24 } from "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: z23.object({
-    file: z23.string().min(1).describe("The instruction file to edit in place."),
-    budgetTokens: z23.number().int().positive().optional(),
-    fullUnderTokens: z23.number().int().positive().optional(),
-    profile: z23.string().optional()
+  input: z24.object({
+    file: z24.string().min(1).describe("The instruction file to edit in place."),
+    budgetTokens: z24.number().int().positive().optional(),
+    fullUnderTokens: z24.number().int().positive().optional(),
+    profile: z24.string().optional()
   }),
   fromArgv: (argv) => {
     const budget = argvFlag(argv, "--budget");
@@ -1971,17 +2242,17 @@ var syncInstructionsCommand = define({
 });
 
 // src/commands/trace.ts
-import { z as z24 } from "zod";
+import { z as z25 } from "zod";
 var traceCommand = define({
   name: "trace",
   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: z24.object({
+  input: z25.object({
     bundlePath,
     conceptId,
-    edges: z24.array(z24.enum(TRACE_EDGES)).optional(),
-    depth: z24.number().int().positive().optional()
+    edges: z25.array(z25.enum(TRACE_EDGES)).optional(),
+    depth: z25.number().int().positive().optional()
   }),
   fromArgv: (argv, path) => ({
     bundlePath: path,
@@ -2003,53 +2274,53 @@ var traceCommand = define({
 });
 
 // src/commands/types.ts
-import { z as z25 } from "zod";
+import { z as z26 } from "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: z25.object({}),
+  input: z26.object({}),
   fromArgv: () => ({}),
   run: () => Promise.resolve(RECORD_TYPES)
 });
 
 // src/commands/unpin.ts
-import { z as z26 } from "zod";
+import { z as z27 } from "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: z26.object({ bundlePath }),
+  input: z27.object({ bundlePath }),
   fromArgv: (argv, path) => ({ bundlePath: argv[1] ?? path }),
   run: (_ctx, { bundlePath: path }) => unpinBase(process.cwd(), path)
 });
 
 // src/commands/validate.ts
-import { z as z27 } from "zod";
+import { z as z28 } from "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: z27.object({ bundlePath }),
+  input: z28.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
-import { z as z28 } from "zod";
+import { z as z29 } from "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: z28.object({
+  input: z29.object({
     bundlePath,
     conceptId,
-    note: z28.string().refine((s) => s.trim().length > 0, {
+    note: z29.string().refine((s) => s.trim().length > 0, {
       message: "note must say what the check found"
     })
   }),
@@ -2069,7 +2340,7 @@ var verifyCommand = define({
 });
 
 // src/commands/write.ts
-import { z as z29 } from "zod";
+import { z as z30 } from "zod";
 var writeCommand = define({
   name: "write",
   tool: "kb_write",
@@ -2083,9 +2354,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: z29.object({
+  input: z30.object({
     bundlePath,
-    type: z29.enum(KB_RECORD_TYPES),
+    type: z30.enum(KB_RECORD_TYPES),
     input: composeInputSchema
   }),
   fromArgv: async (argv, path, stdin) => ({
@@ -2109,7 +2380,7 @@ var writeCommand = define({
 });
 
 // src/commands/write-decision.ts
-import { z as z30 } from "zod";
+import { z as z31 } from "zod";
 var writeDecisionCommand = define({
   name: "write-decision",
   tool: "kb_write_decision",
@@ -2122,7 +2393,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: z30.object({ bundlePath, input: decisionInputSchema }),
+  input: z31.object({ bundlePath, input: decisionInputSchema }),
   fromArgv: async (_argv, path, stdin) => ({
     bundlePath: path,
     input: JSON.parse(await stdin())
@@ -2152,6 +2423,7 @@ var KB_COMMANDS = [
   answerCommand,
   verifyCommand,
   loadCommand,
+  catalogCommand,
   packCommand,
   queryCommand,
   traceCommand,
@@ -2197,141 +2469,6 @@ function parseMarkdownWithFrontmatter(text, schema) {
   };
 }
 
-// src/errors.ts
-var Fault = /* @__PURE__ */ ((Fault2) => {
-  Fault2["Configuration"] = "Configuration";
-  Fault2["System"] = "System";
-  Fault2["User"] = "User";
-  return Fault2;
-})(Fault || {});
-var ErrorTypes = /* @__PURE__ */ ((ErrorTypes2) => {
-  ErrorTypes2["KbRecordAlreadyExists"] = "KbRecordAlreadyExists";
-  ErrorTypes2["KbInvalidConceptId"] = "KbInvalidConceptId";
-  ErrorTypes2["KbPackBudgetExceeded"] = "KbPackBudgetExceeded";
-  ErrorTypes2["KbRecordNotFound"] = "KbRecordNotFound";
-  ErrorTypes2["KbSelfVerification"] = "KbSelfVerification";
-  ErrorTypes2["KbWriteConflict"] = "KbWriteConflict";
-  return ErrorTypes2;
-})(ErrorTypes || {});
-var BaseError = class extends Error {
-  code;
-  errorType;
-  fault;
-  retriable;
-  reportToUser;
-  details;
-  constructor(props) {
-    super(props.message);
-    this.name = props.name ?? this.constructor.name;
-    this.code = props.code ?? 500;
-    this.errorType = props.errorType;
-    this.fault = props.fault;
-    this.retriable = props.retriable ?? true;
-    this.reportToUser = props.reportToUser ?? false;
-    this.details = props.details;
-  }
-};
-
-// src/kb-errors.ts
-var KbRecordAlreadyExistsError = class extends BaseError {
-  constructor(conceptId2) {
-    super({
-      message: `kb: ${conceptId2} already exists \u2014 choose a more specific slug, or write with overwrite`,
-      errorType: "KbRecordAlreadyExists" /* KbRecordAlreadyExists */,
-      code: 409,
-      fault: "User" /* User */,
-      retriable: false,
-      reportToUser: true,
-      details: { conceptId: conceptId2, action: "refused" }
-    });
-    this.conceptId = conceptId2;
-  }
-  conceptId;
-};
-var KbRecordNotFoundError = class extends BaseError {
-  constructor(conceptId2) {
-    super({
-      message: `kb: ${conceptId2} does not exist`,
-      errorType: "KbRecordNotFound" /* KbRecordNotFound */,
-      code: 404,
-      fault: "User" /* User */,
-      retriable: false,
-      reportToUser: true,
-      details: { conceptId: conceptId2 }
-    });
-    this.conceptId = conceptId2;
-  }
-  conceptId;
-};
-var KbWriteConflictError = class extends BaseError {
-  constructor(conceptId2) {
-    super({
-      message: `kb: ${conceptId2} changed while it was being updated \u2014 re-read and retry`,
-      errorType: "KbWriteConflict" /* KbWriteConflict */,
-      code: 409,
-      fault: "System" /* System */,
-      retriable: true,
-      reportToUser: true,
-      details: { conceptId: conceptId2 }
-    });
-    this.conceptId = conceptId2;
-  }
-  conceptId;
-};
-var KbSelfVerificationError = class extends BaseError {
-  constructor(conceptId2, actor, generatedBy) {
-    super({
-      message: `kb: ${conceptId2} was generated by ${generatedBy}, and a record's generator cannot verify it \u2014 only a human or a different actor can`,
-      errorType: "KbSelfVerification" /* KbSelfVerification */,
-      code: 400,
-      fault: "User" /* User */,
-      retriable: false,
-      reportToUser: true,
-      details: { conceptId: conceptId2, actor, generatedBy, action: "refused" }
-    });
-    this.conceptId = conceptId2;
-    this.actor = actor;
-    this.generatedBy = generatedBy;
-  }
-  conceptId;
-  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({
-      message: `kb: ${message}`,
-      errorType: "KbInvalidConceptId" /* KbInvalidConceptId */,
-      code: 400,
-      fault: "User" /* User */,
-      retriable: false,
-      reportToUser: true,
-      details
-    });
-  }
-};
-
 // src/search-index.ts
 import { stat } from "fs/promises";
 import { join as join3 } from "path";
@@ -2712,9 +2849,16 @@ ${answer}
    * is indistinguishable from a complete one, so a caller would answer "that
    * was never decided" from a slice it did not know was a slice.
    *
-   * That refusal is the default guardrail. `all` bypasses it outright and
-   * always hands back the whole bundle: an explicit, never-accidental escape
-   * hatch for an operator who has the budget to spend, not a wider default.
+   * A token budget decides that, measured over what is actually handed back.
+   * The refusal names the estimate and the budget, because a caller told only
+   * "too big" cannot tell whether to narrow the type filter, raise the budget,
+   * or stop loading the base whole altogether. Past the budget the answer is
+   * the catalog and then a pack, which is what the refusal says.
+   *
+   * That refusal is the default guardrail. `all` bypasses the budget outright
+   * and always hands back the whole bundle: an explicit, never-accidental
+   * escape hatch for an operator who has the budget to spend, not a wider
+   * default.
    */
   async load(bundlePath2, options = {}) {
     const budgetTokens = options.budgetTokens ?? DEFAULT_LOAD_BUDGET;
@@ -2729,7 +2873,12 @@ ${answer}
         loaded: false,
         recordCount: wanted.length,
         approxTokens: approxTokens2,
-        budgetTokens
+        budgetTokens,
+        message: refusalMessage({
+          approxTokens: approxTokens2,
+          budgetTokens,
+          type: options.type
+        })
       };
     }
     return {
@@ -2745,6 +2894,10 @@ ${answer}
   async trace(bundlePath2, seedId, options = {}) {
     return trace(seedId, await this.list(bundlePath2), options);
   }
+  /** Every record named in one line each. See `catalog.ts`. */
+  async catalog(bundlePath2, options = {}) {
+    return catalog(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);
@@ -3011,6 +3164,14 @@ function estimateTokens(record) {
 function estimateStubTokens(entry) {
   return Math.ceil(JSON.stringify(entry).length / 4);
 }
+function refusalMessage(refusal) {
+  const scope = refusal.type ? ` of type ${refusal.type}` : "";
+  return [
+    `Refusing to load this base whole: ~${refusal.approxTokens} tokens is past the ${refusal.budgetTokens}-token budget.`,
+    `Call kb_catalog for one line per record${scope} (id, type, title, standing), then kb_pack on the record that matters; kb_query works for a lookup by wording.`,
+    `To load anyway: raise budgetTokens (currently ${refusal.budgetTokens}), or all=true to bypass the budget.`
+  ].join(" ");
+}
 function stub(hit) {
   return {
     conceptId: hit.record.conceptId,
@@ -3119,7 +3280,7 @@ function typeRank(record) {
 }
 
 // src/version.ts
-var VERSION = true ? "0.1.9" : "0.0.0-dev";
+var VERSION = true ? "0.1.10" : "0.0.0-dev";
 
 export {
   kbSourceSchema,
@@ -3159,8 +3320,20 @@ export {
   listPins,
   pinBase,
   unpinBase,
+  Fault,
+  ErrorTypes,
+  BaseError,
+  KbRecordAlreadyExistsError,
+  KbRecordNotFoundError,
+  KbWriteConflictError,
+  KbSelfVerificationError,
+  KbPackBudgetExceededError,
+  KbMissingFlagValueError,
+  KbInvalidConceptIdError,
   adjudicate,
   resolveHeads,
+  catalog,
+  renderCatalogLine,
   INDEX_FILE,
   renderIndex,
   renderIndexLine,
@@ -3192,15 +3365,6 @@ export {
   stringifyMarkdownWithFrontmatter,
   splitMarkdownFrontmatter,
   parseMarkdownWithFrontmatter,
-  Fault,
-  ErrorTypes,
-  BaseError,
-  KbRecordAlreadyExistsError,
-  KbRecordNotFoundError,
-  KbWriteConflictError,
-  KbSelfVerificationError,
-  KbPackBudgetExceededError,
-  KbInvalidConceptIdError,
   SEARCH_INDEX_FILE,
   searchBase,
   resolveHits,
@@ -3213,4 +3377,4 @@ export {
   KbStore,
   VERSION
 };
-//# sourceMappingURL=chunk-OFDWRMY6.js.map
+//# sourceMappingURL=chunk-EJQPZWN5.js.map