@saasontools/strauss-kb 0.1.13 → 0.1.14

package/README.md

@@ -1,19 +1,15 @@
 # @saasontools/strauss-kb
 
-A knowledge base is a directory of small markdown records. Copy the directory
+A knowledge base is a directory of small markdown records: copy the directory
 and you have the whole thing — nothing outside it is needed to read, search,
-adjudicate, or trace it.
+adjudicate, or trace it. This package is that directory's library, command line,
+and MCP server; all three project one command table.
 
-This package is that directory's library, its command line, and its MCP server.
-All three project one command table, so a capability exists in every surface or
-in none.
+The point of the format is **standing**, not storage: not only "does this
+match?" but "is this still what we hold?" Results are flagged, never filtered.
 
-The point of the format is **standing**, not storage. A search engine answers
-"does this match?"; a knowledge base also has to answer "is this still what we
-hold?" — and the two disagree in a predictable direction, because a superseded
-record is usually the older, longer, more general one and its replacement is
-usually a narrowing. Every result therefore arrives flagged rather than
-filtered.
+Reference:
+[docs](https://saasontools.github.io/strauss-agent-tools/overview).
 
 ## Install
 
@@ -21,21 +17,15 @@ filtered.
 npm install -g @saasontools/strauss-kb
 ```
 
-Global install is the supported path. The consumers of the CLI are agent skills
-that shell out to `strauss-kb` by name, many times per session and from whatever
-directory the work happens to be in — so the binary has to be on `PATH` without
-a per-project setup step, and per-call resolution latency is paid on every call.
-The trade-off accepted is that the version is machine-wide and not pinned by the
-consuming project; the on-disk format is the compatibility contract, and the
-reader is deliberately tolerant of records it did not write (unknown frontmatter
-keys are preserved, a missing status defaults).
+Global install is the supported path: agent skills shell out to `strauss-kb` by
+name, from any directory.
 
 Two alternatives work and are not the documented convention:
 
-|                | Command                                                           | When it fits                                                                                                                                    |
-| -------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| Per invocation | `npx -y @saasontools/strauss-kb@0.1`                              | Pinned and zero-install; adds resolution latency to every call and needs a warm npx cache or a network.                                         |
-| Project-local  | `pnpm add -D @saasontools/strauss-kb` then `pnpm exec strauss-kb` | Pinned per repository and offline after install; bare `strauss-kb` does not resolve outside that repository, so skills cannot use one spelling. |
+|                | Command                                                           | When it fits                                                                                                  |
+| -------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| Per invocation | `npx -y @saasontools/strauss-kb@0.1`                              | Pinned, zero-install; per-call latency, needs a warm cache or net.                                            |
+| Project-local  | `pnpm add -D @saasontools/strauss-kb` then `pnpm exec strauss-kb` | Pinned per repository, offline; bare `strauss-kb` resolves only inside it, so skills cannot use one spelling. |
 
 As a library:
 
@@ -43,9 +33,7 @@ As a library:
 npm install @saasontools/strauss-kb
 ```
 
-Ships ESM and CommonJS. A consumer that transpiles per-file to CommonJS without
-bundling can `require()` it without depending on its Node version honouring
-`require(esm)`.
+ESM and CommonJS.
 
 ## What is in a base
 
@@ -58,24 +46,17 @@ bundling can `require()` it without depending on its Node version honouring
   .index.sqlite       search     derived, gitignored
 ```
 
-The default base is `.strauss/kb` relative to the working directory;
-`--bundle PATH` addresses any other. A scratch base under a worktree and a
-committed base versioned beside the code it describes are the same format with
-different lifetimes. Nothing promotes one to the other.
+The default base is `.strauss/kb`; `--bundle PATH` names another.
+`INDEX.md` and `log.jsonl` are store-owned and differ in kind:
 
-`INDEX.md` and `log.jsonl` are store-owned and differ in kind — treating them
-alike is how the history gets lost:
+|         | `INDEX.md`                 | `log.jsonl`                    |
+| ------- | -------------------------- | ------------------------------ |
+| Nature  | derived — from frontmatter | primary — events nothing holds |
+| Write   | full regenerate            | append                         |
+| Repair  | rebuilt when it disagrees  | malformed lines reported       |
+| If lost | reconstructed free         | gone                           |
 
-|         | `INDEX.md`                                 | `log.jsonl`                                 |
-| ------- | ------------------------------------------ | ------------------------------------------- |
-| Nature  | derived — recomputable from frontmatter    | primary — records events nothing else holds |
-| Write   | full regenerate                            | append                                      |
-| Repair  | rebuilt when it disagrees with the records | malformed lines reported, never rewritten   |
-| If lost | reconstructed free                         | gone                                        |
-
-Repair-on-read, not coordination, is what lets both exist without a lock. The
-index is _eventually_ correct: a writer whose scan predated another's record
-publishes a briefly stale index, and the next read through the store settles it.
+Repair-on-read, not coordination, lets both exist without a lock.
 
 ### Cross-worktree writes
 
@@ -119,63 +100,43 @@ GitHub itself performs.
 
 ## Records
 
-The filename is the identity. `fact.auth-retries.md` has concept id
-`fact.auth-retries` — `<type>.<slug>`, both halves kebab-case. One record per
-file, so parallel writers never merge; they only choose distinct names.
+The filename is the identity: `fact.auth-retries.md` has concept id
+`fact.auth-retries` — `<type>.<slug>`, both halves kebab-case.
 
 Records are [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog)
 concepts. `type` is the only key OKF requires; `title`, `description`,
 `resource`, `tags`, `sources`, `generated`, `verified`, and `stale_after` are
-OKF's. Unknown keys are preserved rather than stripped, as OKF requires of
-consumers.
-
-`verified` is the record's append-only trail of checks. Each entry is OKF's
-actor stamp — `{ by, at }` — and the entries this package's `verify` writes add
-a `note`: what the check actually found, not just that one happened. The `note`
-is a strauss extension key on the entries this tool writes, not an OKF
-requirement on the array, so noteless entries a foreign producer wrote remain
-readable, and prior entries are spread forward untouched rather than reshaped.
-
-Who may append is the point. A verifier whose actor equals the record's
-`generated.by` — compared case-insensitively over the whole actor, so case
-drift cannot mint a distinct verifier identity — is refused unless the actor
-is `human:`-prefixed: trust that can be self-granted is not trust, and a
-generator re-reading its own output is not an independent check. The refusal
-is recorded in the log as `verify:refused`, so an audit sees the attempt as
-well as the rule. The `human:` prefix itself is an honor-system label — actor
-identity is self-declared through `STRAUSS_KB_ACTOR`, not an authenticated
-identity claim — which is worth knowing when deciding how much weight a
-human-verified event carries.
-
-Anything prefixed `strauss_` is this package's extension, namespaced so a later
-OKF version defining the same name cannot collide:
-
-| Key                                                            | Meaning                                                                                                                                                                                       |
-| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `strauss_status`                                               | `draft`, `proposed`, `accepted`, `open`, `resolved`, `rejected`, `superseded`. Parses with a default of `draft`.                                                                              |
-| `strauss_supersedes` / `strauss_superseded_by`                 | Both directions of a supersession, written together.                                                                                                                                          |
-| `strauss_anchors`                                              | `{ file, symbol?, hash?, lines?, resolved_at? }` — where the record attaches in the code, and optionally what that code looked like when it did. See [Anchors and drift](#anchors-and-drift). |
-| `strauss_links`                                                | `{ target, rel }` — a typed causal edge, source → target. See [Links](#links).                                                                                                                |
-| `strauss_assumption`                                           | The claim has no source, said as a field rather than as a fake entry in `sources`.                                                                                                            |
-| `strauss_answered`                                             | Who resolved an open question, and when.                                                                                                                                                      |
-| `strauss_verify`                                               | Checks that would confirm the record still holds.                                                                                                                                             |
-| `strauss_materiality` / `strauss_confidence` / `strauss_owner` | `blocking`/`important`/`non-blocking`, `low`/`medium`/`high`, and a name.                                                                                                                     |
-
-Edges are markdown links in the body, as OKF specifies — untyped, with the kind
-conveyed by the surrounding prose. Broken links are legal: records are routinely
-written before the ones they point at exist. `strauss_links` adds a typed layer
-over that, described below.
-
-Twelve record types differ only in what their body answers and where they start
-in the lifecycle — `fact`, `requirement`, `constraint`, `decision`,
-`assumption`, `open-question`, `risk`, `contract`, `flow`, `affected-system`,
-`test-obligation`, `source-note`. `strauss-kb types` prints each one's purpose,
-body sections, and initial status; a section a type does not define is rejected
-rather than written.
-
-Do not work from memory on the frontmatter contract — `strauss-kb schema` emits
-JSON Schema generated from the code that enforces it, so it cannot drift from
-what a write will accept.
+OKF's. Unknown keys are preserved rather than stripped.
+
+`verified` is an append-only trail of checks, each an actor stamp `{ by, at }`
+plus a `note`. A verifier whose actor equals the record's `generated.by` is
+refused unless the actor is `human:`-prefixed, and the refusal is logged as
+`verify:refused`; the prefix is honor-system, since actor identity is
+self-declared through `STRAUSS_KB_ACTOR`.
+
+Anything prefixed `strauss_` is this package's extension, namespaced against a
+later OKF key of the same name:
+
+| Key                                                            | Meaning                                                                                                                                                         |
+| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `strauss_status`                                               | `draft`, `proposed`, `accepted`, `open`, `resolved`, `rejected`, `superseded`. Default `draft`.                                                                 |
+| `strauss_supersedes` / `strauss_superseded_by`                 | Both directions of a supersession, written together.                                                                                                            |
+| `strauss_anchors`                                              | `{ file, symbol?, hash?, lines?, resolved_at? }` — where the record attaches, and what that code looked like then. See [Anchors and drift](#anchors-and-drift). |
+| `strauss_links`                                                | `{ target, rel }` — a typed causal edge, source → target. See [Links](#links).                                                                                  |
+| `strauss_assumption`                                           | The claim has no source, as a field rather than a fake entry in `sources`.                                                                                      |
+| `strauss_answered`                                             | Who resolved an open question, and when.                                                                                                                        |
+| `strauss_verify`                                               | Checks that would confirm the record still holds.                                                                                                               |
+| `strauss_materiality` / `strauss_confidence` / `strauss_owner` | `blocking`/`important`/`non-blocking`, `low`/`medium`/`high`, and a name.                                                                                       |
+
+Twelve types differ in what their body answers and where they start in the
+lifecycle: `fact`, `requirement`, `constraint`, `decision`, `assumption`,
+`open-question`, `risk`, `contract`, `flow`, `affected-system`,
+`test-obligation`, `source-note`.
+
+`strauss-kb types` prints each one's purpose, sections, and initial status;
+`strauss-kb schema` emits JSON Schema from the code that enforces it.
+Body sections, edges, and the frontmatter contract:
+[specification](https://saasontools.github.io/strauss-agent-tools/specification).
 
 ```yaml
 ---
@@ -230,50 +191,16 @@ has the rest.
 
 ## Writes
 
-Records are staged to a sibling file and published atomically, so a concurrent
-reader sees a whole record or none. Publication uses `link`, which fails when
-the name is taken — two writers choosing one concept id is a 409 the caller must
-answer, by picking a more specific slug or by saying it meant to replace.
-`rename` is used only when the caller passes `overwrite`.
-
-Read-modify-write (`setStatus`, `answer`) checks a content digest immediately
-before publishing, which narrows the lost-update window rather than closing it.
-[ARCHITECTURE.md](./ARCHITECTURE.md) says why a lock was rejected.
-
-`supersede` writes both directions, so a backlink cannot drift in normal use and
-`validate` drops to catching hand-edits. A `write` (or `write-decision`) that
-carries `supersedes` does the same: the new record publishes first, then each
-prior record it names is marked superseded in turn — a crash between the two
-leaves an old record with no backlink, which `validate` already reports as
-"is not marked superseded", never a silent drift. A `supersedes` id naming a
-record that does not exist yet is legal and does not fail the write; `validate`
-is what reports a target that never resolves. A `supersedes` id naming the
-record's own concept id is a no-op rather than an error, duplicate ids mark
-once, and the array is capped at 32 entries.
-
-A concurrent writer marking the same target races the compare-and-swap check;
-that's retried a few times before giving up, and giving up is reported the
-same way as a target that doesn't exist yet — left out of `supersededIds` for
-`validate` to catch, not thrown, since the calling record is already
-published by that point. If two different records both name the same target
-in `supersedes`, the target's backlink points at whichever wrote last;
-`validate` doesn't see this as a problem because the target genuinely is
-superseded, but `kb_query`/`kb_load`'s adjudication surfaces the resulting
-fork as a warning at read time.
-
-`kb_write` and `kb_write_decision` return
-`{ conceptId, action: "created" | "superseded-prior", supersededIds }` —
-`supersededIds` is only the ids actually marked, not every id the input named.
-A 409 from a concept-id collision carries `action: "refused"` in its `details`,
-alongside the `conceptId`.
-
-Records are never deleted. Superseding keeps the earlier reasoning inspectable,
-which is what a later `trace` reads.
-
-`no-decision` records the explicit claim that a piece of work had nothing to
-decide (an idempotent `decision.none` record). It exists for workflow gates:
-"did you write a decision?" rewards writing a junk one, "did you answer?"
-does not — so silence has to be expressible.
+Records are staged to a sibling file and published atomically: a reader sees a
+whole record or none. A concept-id collision is a 409 the caller answers with a
+narrower slug or by saying it meant to replace. `supersede` writes both
+directions of the link, and `write`/`write-decision` do the same for every id in
+`supersedes`. Records are never deleted; superseding keeps earlier reasoning
+inspectable for `trace`.
+
+Crash, race, and fork edge cases:
+[specification](https://saasontools.github.io/strauss-agent-tools/specification).
+Why a lock was rejected: [ARCHITECTURE.md](./ARCHITECTURE.md).
 
 ## Anchors and drift
 
@@ -368,17 +295,12 @@ strauss-kb [--bundle PATH] <command> [args]
   STRAUSS_KB_ACTOR names the writer in the log
 ```
 
-Results go to stdout as JSON — `index`, `catalog` and `pack` are markdown, which is what
-they are, and `doctor` prints a table unless `--json` asks for the object
-behind it. `--json` is refused rather than ignored on the commands that have
-only one form, since a flag that quietly does nothing reads as one that
-worked; `--` ends flag parsing, for the verbs that end in free prose. Errors
-go to stderr and exit 1. `validate`, `anchor-resolve`, and `doctor --strict`
-are the commands whose exit code is not just "did it run": a check that
-reports a problem succeeded as a command and failed as a check, so each exits
-1 with its findings on stdout. Only `validate` findings with `severity: "error"`
-do that — a base mid-write is full of links to records not written yet, so
-warnings alone exit 0.
+Results go to stdout as JSON; `index`, `catalog` and `pack` are markdown, and
+`doctor` prints a table unless `--json`. `--json` is refused where a command has
+one form; `--` ends flag parsing. Errors go to stderr with exit 1; `validate`,
+`anchor-resolve` and `doctor --strict` exit 1 with findings on stdout; only
+`validate` findings with `severity: "error"` do, so warnings alone exit 0. Per-command flags:
+[cli-reference](https://saasontools.github.io/strauss-agent-tools/cli-reference).
 
 A flag accepts either spelling — `--budget 4000` or `--budget=4000` — and a
 flag given no value is an error rather than a silent fallback to the default,
@@ -402,16 +324,6 @@ strauss-kb validate || echo "errors above"   # warnings alone still exit 0
 ## MCP server
 
 `strauss-kb-mcp` speaks stdio and takes no API key and no required environment.
-Every CLI verb is a tool: `kb_write`, `kb_write_decision`, `kb_no_decision`,
-`kb_status`, `kb_supersede`, `kb_answer`, `kb_verify`, `kb_anchor_resolve`,
-`kb_load`, `kb_catalog`, `kb_pack`, `kb_query`, `kb_trace`, `kb_impact`,
-`kb_backlinks`, `kb_list`,
-`kb_index`, `kb_log`, `kb_validate`, `kb_doctor`, `kb_schema`, `kb_types`,
-`kb_pin`, `kb_unpin`, `kb_pins`, `kb_context`. Most tools take a `bundlePath`;
-`kb_schema` and `kb_types` describe the format rather than any one base, and
-`kb_pins` and `kb_context` read the workspace pin manifests instead. The one
-CLI verb with no tool is `sync-instructions` — file plumbing for hooks, not an
-agent capability; the capability is `kb_context`.
 
 ```json
 {
@@ -421,13 +333,17 @@ agent capability; the capability is `kb_context`.
 }
 ```
 
-The tool descriptions carry the judgment a schema cannot: that an unsourced
-claim is an `assumption` and not a `fact` with a vague source, that a conflict
-between two records belongs in a `risk` or a superseding `decision` rather than
-being quietly resolved, and that `kb_load` is usually the right first call.
+Every CLI verb is a tool: `kb_write`, `kb_write_decision`, `kb_no_decision`,
+`kb_status`, `kb_supersede`, `kb_answer`, `kb_verify`, `kb_anchor_resolve`, `kb_load`, `kb_catalog`,
+`kb_pack`,
+`kb_query`, `kb_trace`, `kb_impact`, `kb_backlinks`, `kb_list`, `kb_index`, `kb_log`, `kb_validate`,
+`kb_doctor`, `kb_schema`, `kb_types`, `kb_pin`, `kb_unpin`, `kb_pins`,
+`kb_context`. Most take a `bundlePath`. The one CLI verb with no tool is
+`sync-instructions`; the agent capability is `kb_context`.
 
-`STRAUSS_KB_ACTOR` names the writer in the log. Diagnostics go to stderr,
-because stdout is the JSON-RPC transport.
+`STRAUSS_KB_ACTOR` names the writer in the log; diagnostics go to stderr, since
+stdout is the JSON-RPC transport. Per-tool schemas:
+[mcp-reference](https://saasontools.github.io/strauss-agent-tools/mcp-reference).
 
 ## Library
 
@@ -448,11 +364,8 @@ for (const hit of hits) {
 }
 ```
 
-`matchToDiff` answers a different question from `query`: given a structural
-description of a diff, which records are anchored to each hunk. It takes hunks
-and optional symbol ranges rather than a patch, so this package carries no diff
-parser, and it degrades to file-level precision — labelled as such — when a
-symbol cannot be resolved.
+`matchToDiff` takes hunks and optional symbol ranges rather than a patch,
+answering which records are anchored to each hunk.
 
 ## Retrieval
 
@@ -465,111 +378,23 @@ problem:
 | Standing  | `strauss_status`, the supersession chain                | is this still what we hold?     |
 | Freshness | `stale_after`, `verified[]`                             | has anyone confirmed it lately? |
 
-Freshness is tiered by who did the confirming. OKF's spec (§5.3) defines the
-trust tiers from the verifying actor's prefix: an empty `verified[]` is
-unverified, an agent-prefixed verifier makes the record machine-confirmed, and
-a `human:`-prefixed verifier makes it human-reviewed. Of that ladder, today's
-adjudication reports only the first rung — the warning it attaches when
-`verified[]` is empty; reporting the full tier is upcoming tooling. When it
-lands, the tier will be derived from the events at read time, never stored, so
-it cannot drift from the trail that justifies it.
-
-**Load before you search.** These bases run to a few thousand tokens — twenty
-records measured at about 3,000 — so the first thing to try is taking all of it.
-On nine questions whose wording appears in no record, a reader holding the whole
-base answered eight; embedding search over the same records answered four. Two
-of those differences are structural rather than matters of degree: a reader can
-say no record answers the question, where vector search returns its nearest
-neighbour whatever the distance; and a reader picks the record that answers the
-question rather than the one nearest the topic. The mechanism is simple:
-retrieval makes similarity the gatekeeper, and a match the ranker misses never
-reaches the model. A full read lets the model do the matching itself —
-synonymy, implication across records, aggregation — which no ranker does.
-
-Read for a question, not for a session: a base loaded at the start of a long
-conversation is summarised away by the end of it, and reloading costs about
-three thousand tokens. Read it again at the point of use.
-
-**The three rungs, in one rule.** While the base fits the budget, `load` it
-whole. Once `load` refuses, `catalog` then `pack` the record that matters. For
-a lookup by wording, `query`.
+**Load before you search.** These bases run to a few thousand tokens, and a
+reader holding the whole base out-answers embedding search over the same records
+([ARCHITECTURE.md](./ARCHITECTURE.md#load-beats-retrieval-while-the-base-fits)).
+Read for a question, not for a session — a base loaded early in a long
+conversation is summarised away by the end.
 
-```bash
-strauss-kb load                          # under the budget: everything, with standing
-strauss-kb catalog                       # past it: one line per record, ~30 tokens each
-strauss-kb pack decision.cursor-v2       # then the neighbourhood around the one that matters
-strauss-kb query cursor pagination       # or a point lookup by wording
-```
+- `load` refuses rather than truncating past its budget (25,000 tokens default).
+- `--all` (`all: true` over MCP) bypasses that refusal; it excludes `--budget`.
+- Superseded records return as name, replacement and date only.
+- `catalog` is the rung with no ceiling: one line per record, ~30 tokens each.
+- `pack` is the middle rung: one record's neighbourhood, every cut named.
+- `query` flags rather than filters — every hit arrives with its standing.
+- `trace` orders by `generated.at` rather than ranking.
+- Chains resolve on read: `chain-cycle`, forked heads, `broken-chain`.
 
-A whole read gives perfect recall and can say _no record answers this_, which
-no ranker can. `catalog` keeps that at a fraction of the cost by naming every
-record instead of every body; `query` gives up both, returning its nearest hit
-whatever the distance.
-
-`load` refuses rather than truncating past its token budget (`--budget` /
-`budgetTokens`, 25,000 by default, held against the estimated size of what is
-handed back) — a truncated base reads as a complete one, so a caller would
-answer "never decided" from a slice it did not know was a slice. `context`
-refuses the same way at its own, tighter budget (4,000 by default). Superseded
-records come back as name, replacement and date only; `trace` still reaches
-them by id.
-
-A refusal reports `approxTokens` against `budgetTokens` and carries a `message`
-naming the budget and the next calls. A successful load reports `budgetTokens`
-too, so a caller can see how close it came before crossing the line.
-
-`--all` (`all: true` over MCP) bypasses the budget and hands back the entire
-bundle regardless of size. A loaded result carries `tokensLoaded`, and
-`budgetTokens: null` marks that no ceiling applied; `--all` is mutually
-exclusive with `--budget`. It is for an operator who has decided the size is
-worth the tokens — a narrower `type` filter, `catalog`, or `query` fits better
-when it is not.
-
-**Catalog is the rung that keeps the base knowable.** One line per record —
-concept id, type, title, standing, stale flag — sorted by type then title, at
-roughly thirty tokens each, so a base far past `load`'s budget still fits in
-one call. Superseded records show the replacement in place of a body. The
-header sums record counts by standing and reports staleness separately (a
-current record can be stale). Bodies live in `load`, `pack`, and `trace`.
-
-`catalog` alone has no ceiling and never refuses — cost is linear at roughly
-thirty tokens a record (a thousand-record base is about 30k, five thousand
-about 150k); narrow with `type` at that scale. Output is deterministic given
-a fixed clock — no timestamp, ordering total down to the concept id — so two
-catalogs of an unchanged base diff to nothing except a stale flag flipping as
-`stale_after` passes. Pass an explicit `now` (library callers) to hold
-byte-equality across that boundary.
-
-**Pack is the middle rung.** Under the budget, load the base whole. Past it, when the work centres on a record you can name (`catalog` is how you
-name it), `pack` hands over that record's bounded neighbourhood: everything
-within `--hops` of the root, walked over the base's edges — body links (a
-`relatedConceptIds` entry is one), supersession in both directions, shared
-code anchors, and shared sources — ranked and cut to `--max-nodes`. Standing
-travels with it: superseded neighbours arrive as the same stubs `load` emits.
-Every dropped record is named under Excluded, and past its own token budget
-`pack` refuses exactly as `load` does. Output is byte-identical across runs
-over an unchanged base below the header. With neither a size problem nor a
-root record in hand, the question is a point lookup — `query`.
-
-**Flag, never filter.** `query` returns every hit with its standing, because a
-filtered result set is invisible — the caller cannot tell it missed anything.
-The single exception is narrow: a superseded record is dropped only when its
-replacement is also in the results, so the thread is never lost.
-
-**Trace inverts the point query.** In a query a `rejected` record is the most
-dangerous thing retrievable — a well-formed assertion of what someone decided
-_not_ to do. In a history it is the content. `trace` follows supersession,
-shared code anchors, and shared sources, and orders by `generated.at`; ranking a
-history is meaningless when the sequence is the point.
-
-Chain resolution happens on read. A stored head would need rewriting on every
-ancestor whenever a chain grows, which is derived state that goes stale. The
-walk follows both pointers, so a hand-edit that left one side behind cannot
-return a record the base openly claims is replaced. A cycle terminates with
-`chain-cycle`; a fork reports every head rather than presenting a guess as a
-fact; a missing replacement is `broken-chain` with no head — the case that needs
-the most care, because returning the stale record unmarked looks exactly like
-success.
+Worked flows:
+[use-cases](https://saasontools.github.io/strauss-agent-tools/use-cases).
 
 **Placement is cache economics.** `load`'s output belongs in the stable
 prefix — system prompt or first turn; `query` and `pack` results belong at
@@ -581,98 +406,19 @@ caveats: <https://saasontools.github.io/strauss-agent-tools/mcp-reference>.
 
 ## Health
 
-`doctor` sweeps a whole base and reports what has decayed. It is read-only —
-nothing is re-dated, re-verified, superseded, or deleted — because every
-finding is a judgment somebody has to make: whether a claim still holds, which
-question is worth answering, which island to link or drop.
-
-It exists because decay is invisible from inside a single record. A stale
-record reads exactly like a live one, a question nobody answered reads exactly
-like one nobody asked, and a record nothing links to is reachable only by
-someone who already knows it is there. `validate` is the narrower neighbour:
-it asks only whether pointers between records agree.
-
-| Check                  | Reports                                                                        |
-| ---------------------- | ------------------------------------------------------------------------------ |
-| `expired`              | `stale_after` is in the past — or is not a readable date, which is no better.  |
-| `expiring`             | `stale_after` falls inside the next `--expiring-days` (30).                    |
-| `unverified`           | `verified[]` is empty and the record is over `--unverified-days` (90) old.     |
-| `aging`                | Still `open` or `proposed` after `--aging-days` (90).                          |
-| `orphaned`             | No other record links to it, by body link or supersession.                     |
-| `broken-supersession`  | A chain that does not resolve: no replacement, a missing one, a cycle, a fork. |
-| `superseded-but-cited` | A record that still holds, whose body links to one that does not.              |
-| `drifted`              | A hash-carrying anchor whose code moved, or whose file or symbol is gone.      |
-
-Pass `doctor --repo-root PATH` when the base does not sit inside the tree it
-describes; without it the sweep looks under the working directory.
-
-`superseded-but-cited`'s name is for its common case: a rejected target counts
-too, and is the worse half — a superseded record at least names its
-replacement, while a rejected one is a well-formed assertion of what someone
-decided _not_ to do, cited by a record the reader trusts.
-
-```bash
-strauss-kb doctor                       # the table
-strauss-kb doctor --json                # the object behind it
-strauss-kb doctor --strict              # exit 1 if anything has expired
-strauss-kb doctor --unverified-days 30  # a stricter confirmation window
-strauss-kb doctor --repo-root ../app    # where the anchored source lives
-```
-
-All eight groups are reported even when empty. A check that found nothing and
-a check that never ran look identical in a report that only lists findings,
-which is the whole value of a sweep.
-
-Judgments the checks make, worth knowing before reading a report:
-
-- **Superseded and rejected records sit out the freshness checks.** A replaced
-  record whose date has passed needs no repair, and reporting it would bury the
-  records that do. They stay in the graph checks, where standing is not the
-  question.
-- **A date-only `stale_after` expires at UTC midnight.** `2026-09-01` parses as
-  `2026-09-01T00:00:00Z`, so a record goes stale at the start of its date: a
-  sweep run at exactly that instant still calls it expiring, and one a minute
-  later calls it expired. That is `adjudicate`'s comparison rather than a
-  second one — two readings of the same field disagreeing about the day would
-  be worse than either.
-- **Age is read from `generated.at`, exclusively.** A record carrying no
-  timestamp is not reported as aging or unverified — without a start there is
-  no duration, and inventing one would flag every foreign record as overdue
-  (adjudication still warns `unverified` on it at read time). Exactly N days
-  old is not yet "older than N".
-- **`orphaned` counts incoming links only, and reads supersession one way.** A
-  record that cites five others and is cited by none is precisely the island:
-  reachable if you already know it exists. The replacement references what it
-  replaced, never the reverse — taken symmetrically, a dead record would vouch
-  for its own replacement and an old→new pair nothing else touches would rescue
-  itself. Shared anchors and shared sources are co-location rather than
-  reference, so they do not rescue a record either.
-- **A record citing the one it replaced is not superseded-but-cited.** That
-  link is the history working as designed, and reporting it would put a finding
-  on every correctly performed supersession.
-- **A replacement pointer is checked whatever the status says.** The store
-  writes `strauss_status` and `strauss_superseded_by` in one mutation, so a
-  record left `accepted` while naming a replacement was hand-edited — and
-  adjudication reads it as current no matter what the pointer says, which is
-  what makes it worth naming.
-- **`drifted` reports and never repairs.** It reads the same comparison
-  `kb_load` and `kb_query` do, so the sweep and the read paths cannot disagree
-  about what drift is. Unresolvable anchors ride in this group rather than a
-  ninth check, anchors carrying no hash are never read, and `--strict` does not
-  gate on drift.
-
-`--strict` gates on expiry alone. The other seven report debt a reader decides
-about; an expired record is the base itself saying it would stop standing
-behind something, which is the one finding a pipeline can act on without a
-judgment call.
+`doctor` sweeps a base read-only for `expired`, `expiring`, `unverified`,
+`aging`, `orphaned`, `broken-supersession`, `superseded-but-cited`, and
+`drifted`. All eight groups are reported even when empty; `--strict` gates on
+expiry alone, not on drift. Pass `--repo-root PATH` when the base does not sit
+inside the tree it describes.
+Windows and judgments:
+[cli-reference](https://saasontools.github.io/strauss-agent-tools/cli-reference).
 
 ## Living in an agent session
 
-Long sessions lose a knowledge base twice over: attention decays, and
-compaction summarises away both the records loaded early and the instruction
-that said to consult them. The fix is two-tier: a small index is re-injected
-at every context birth, and record bodies are fetched by tool when a question
-actually needs them.
+Compaction summarises away the records loaded early and the instruction to
+consult them. The fix is two-tier: a small index re-injected at every context
+birth, bodies fetched by tool when needed.
 
 ```bash
 strauss-kb pin docs/kb                   # mark a base every session should see
@@ -680,23 +426,13 @@ strauss-kb context                       # emit the pinned index block
 strauss-kb sync-instructions AGENTS.md   # or keep it in an instruction file
 ```
 
-Pins live in `.strauss/kb-pins.json`, committed with the repo. Two more
-layers exist: `.strauss/kb-pins.local.json` (personal, gitignore it) and
-`~/.strauss/kb-pins.json` (every workspace). Nearest layer wins per base,
-`--local`/`--user` write the other layers, and `unpin` removes from all
-three. A malformed layer is skipped on read and refused on write.
-
-Per pin:
-
-- `--mode full` — inject the records themselves, not just the index. For
-  small or critical bases (ADRs). Falls back to a labelled index when it
-  cannot fit the block budget.
-- `--mode index` — never inject bodies.
-- `--profiles a,b` — only inject in the named profiles.
-- `--frozen` — the base is concluded; write commands refuse until `--unfreeze`.
-
-Budgets are named profiles — `session-start`, `compact`, `turn` — with
-per-repo overrides in the manifest, so hook commands never carry numbers:
+Pins live in `.strauss/kb-pins.json`, committed with the repo, over
+`.strauss/kb-pins.local.json` (personal) and `~/.strauss/kb-pins.json` (every
+workspace); nearest layer wins per base. Per pin: `--mode full` injects bodies,
+`--mode index` never does, `--profiles a,b` narrows to named profiles, and
+`--frozen` refuses writes until `--unfreeze`. Budgets are named profiles —
+`session-start`, `compact`, `turn` — overridable per repo, so hook commands
+carry no numbers:
 
 ```json
 {
@@ -705,16 +441,9 @@ per-repo overrides in the manifest, so hook commands never carry numbers:
 }
 ```
 
-Flags beat the manifest, the manifest beats the built-ins, and invalid values
-fall back to defaults instead of silencing the index. Past its budget,
-`context` refuses like `load` does — never truncates — and its refusal says
-what to load directly and how to shrink the block.
-
-`sync-instructions <file>` keeps the same block between
-`<!-- strauss-kb:begin/end -->` sentinels in AGENTS.md or CLAUDE.md, touching
-nothing outside them. Re-run it when pins change; it is idempotent. This is
-the mechanism for runtimes without a reliable post-compaction hook, since
-instruction files are re-read where conversation history is not.
+`sync-instructions <file>` keeps that block between
+`<!-- strauss-kb:begin/end -->` sentinels in AGENTS.md or CLAUDE.md; it is
+idempotent, and covers runtimes without a reliable post-compaction hook.
 
 What each runtime gets (configs in the
 [plugin's adapters](../../plugins/strauss-kb/adapters/)):
@@ -725,12 +454,15 @@ What each runtime gets (configs in the
 | Session-start injection   | SessionStart hook  | SessionStart hook                           | PreInvocation, per turn    |
 | Post-compact re-injection | ✓ `compact` source | ✓ client-side; instruction-only when hosted | moot — injected every turn |
 | File-read blocking        | opt-in PreToolUse  | ✗ (shell is the side door)                  | opt-in PreToolUse, JSON    |
+| Manual-edit validation    | opt-in PostToolUse | ✗                                           | ✗                          |
+| Generated-file edit guard | opt-in PreToolUse  | ✗                                           | ✗                          |
 | Instruction file          | CLAUDE.md          | AGENTS.md                                   | AGENTS.md + rules/         |
 
-One more thing agents add: file tools. A raw read of a record file bypasses
-standing entirely — a superseded record reads exactly like a current one — so
-bases are read through the tools, and a workspace can enforce that with deny
-rules or the plugin's opt-in PreToolUse script:
+Never read record files directly — read through the tools; a raw read bypasses
+standing, and a superseded record reads exactly like a current one. Enforce it
+with deny rules or the plugin's
+[opt-in hook scripts](../../plugins/strauss-kb/README.md#opt-in-workspace-hooks),
+which also cover manual edits to a bundle:
 
 ```json
 {
@@ -742,45 +474,28 @@ rules or the plugin's opt-in PreToolUse script:
 
 ## Optional search tier
 
-`@tobilu/qmd` is an **optional peer dependency** providing BM25 (`searchLex`,
-no model download) over a `.index.sqlite` per base, rebuilt when a record is
-newer than the index.
+`@tobilu/qmd` is an **optional peer dependency** providing BM25 (`searchLex`, no
+model download) over a `.index.sqlite` per base, rebuilt when a record is newer
+than the index.
 
 ```bash
 npm install -g @tobilu/qmd    # alongside a global strauss-kb
 ```
 
-With it absent — the default — `query` falls back to a substring scan over
-concept ids, titles, descriptions, and bodies. Nothing throws, no answer changes
-shape, and only recall degrades. Measured against that fallback on a
-twenty-record base, the lexical tier wins on word forms (`pages` finds a record
-saying only `page`) and on little else: eight of nine probe queries returned
-exactly what substring returned.
-
-The vector tier is deliberately off. It does close the semantic gap — "why not
-just use a mutex" finds a record about compare-and-swap that no lexical match
-can — but its scores do not separate right from wrong. A wrong hit scored 0.318
-against a correct one at 0.295, and any threshold that drops the first drops the
-second. Scores are evidence for a reader to weigh, not a filter to apply before
-one.
-
-qmd is used as a library, never through its own MCP server: that would let a
-caller reach a base without going through the store, and its default markdown
-glob returns `INDEX.md` as a search hit.
+Absent — the default — `query` falls back to a substring scan over concept ids,
+titles, descriptions, and bodies: nothing throws, only recall degrades. The
+vector tier is off, since its scores do not separate right from wrong
+([ARCHITECTURE.md](./ARCHITECTURE.md#what-happens-when-a-base-outgrows-a-context)).
+qmd is used as a library, never through its own MCP server, which would bypass
+the store.
 
 ## Constraints worth knowing
 
-**The store is the sole accessor, not merely the sole writer.** Excluding
+The store is the sole accessor, not merely the sole writer: excluding
 store-owned files from listings and repairing the index on read hold only while
-everything goes through one door. Reading one record by a concept id you already
-hold is the exception — no invariant, deterministic path.
-
-**Cross-base questions are unaskable.** Supersession, traces, and search stop at
-the directory boundary. "Was this settled somewhere else?" is answered by a
-person choosing which base to open. That is the price of a base that can be
-copied, deleted, or handed over whole, and it is what keeps the search index
-disposable. [ARCHITECTURE.md](./ARCHITECTURE.md) covers the registry that would
-lift it, and why it is unbuilt.
+everything goes through one door. Cross-base questions are unaskable —
+supersession, traces, and search stop at the directory boundary
+([ARCHITECTURE.md](./ARCHITECTURE.md)).
 
 ## License