# DOX — packages/kb

Files in this directory. One row per source file.

| File | Purpose |
|------|---------|
| `bin/kb.mjs` | Committed plain-JS bin shim (never built, never stale). Branch table vs `engine-fingerprint.json`: hashes match → import `dist/cli.js` silently; mismatch/missing in a dev checkout (tsconfig resolvable) → rebuild via nearest `node_modules/typescript/lib/tsc.js`, refresh fingerprint, import; mismatch in an installed package (no tsconfig) → loud stderr warning + import stale dist; `dist/cli.js` missing without tsconfig → hard error naming the divergence. See change: fix-kb-eval-measurement-integrity. |
| `bin/lib/engine-fingerprint.mjs` | THE shared engine-fingerprint lib (zero-dep): `srcHash` (src/**.ts minus `__tests__`, LF-normalized, path-sorted SHA-256), `tsconfigHash` (extends chain), `distHash`; `writeFingerprint` for `npm run build` (`--write <pkgRoot>`) + CLI mode. bin shim + `scripts/check-kb-dist-fresh.mjs` + CI gate share these bytes. See change: fix-kb-eval-measurement-integrity. |
| `engine-fingerprint.json` | Committed build artifact written by `npm run build`: {srcHash, tsconfigHash, distHash} over packages/kb. Makes dist staleness visible to CI (dist/ is gitignored — a CI build is fresh by construction); shipped in the tarball for the installed-package leg of the bin shim. See change: fix-kb-eval-measurement-integrity. |
| `README.md` | Package overview. SQLite/FTS5 markdown knowledge base. `kb search` / `kb agents` / `kb dox lint` examples; points at `pi-dashboard-kb-extension` for the pi tools. |
| `skill/kb-search/SKILL.md` | kb-search skill. Frontmatter `name: kb-search`. Retrieve-before-answer: search local FTS5 markdown KB before answering project questions from memory/guessing. Pull retrieval (agent calls, nothing auto-injected), sub-second, zero model tokens. |
| `skill/kb-setup/SKILL.md` | kb-setup skill. Frontmatter `name: kb-setup`. One-time KB bring-up wrapping `kb init`: detect config → choose scope + sources → `kb init` → trust remote source → `kb index` → smoke `kb search` to verify. |
| `eval/golden.doc-example.json` | Example golden set (bare array form) shipped as a `kb eval --golden` sample. |
| `eval/golden.doc-example.paraphrase.json` | Paraphrase variant of the example golden set — tracks robustness to reworded queries. |
| `eval/golden.markdown-intent.json` | Bundled golden set, markdown targets (n=108). Mined from implicit click feedback in session transcripts. Carries `$provenance` + the stated sampling bias (only searches that produced an opened file are represented). See change: fix-kb-search-retrieval-quality. |
| `eval/golden.source-intent.json` | Bundled golden set, source targets (n=104). `expect` = the AGENTS.md record documenting the opened file (sidecar, else nearest ancestor naming it) — a source file can never appear in kb results since the KB indexes markdown; `openedFile` records what the agent actually opened. See change: fix-kb-search-retrieval-quality. |
| `eval/golden.provenance.json` | Mining parameters + corpus counts for both bundled fixtures (window, min query terms, click/refine/abandon split). Makes a re-mine auditable against quoted numbers. See change: fix-kb-search-retrieval-quality. |
| `eval/measure-render.ts` | Render repricing: mean tokens + distinct sources per page, legacy render vs shipped. Exits non-zero if a page grew. Options via shared `searchOptsFromConfig` (BEFORE/AFTER differ by explicit overrides). Needs the cached index from `run-fixtures.ts --fresh`. See change: fix-kb-search-retrieval-quality; fix-kb-eval-measurement-integrity. |
| `eval/measure-search-latency.ts` | Search + verdict-enrichment latency over the bundled fixture index (reuses `run-fixtures.ts` cache; `--fresh` rebuilds). `--enrich` adds the ADDITIVE enrichment median/p95 vs the advisory 15 ms target; `--json`. See change: add-kb-trust-verdicts-and-search-guard. |
| `eval/mine-golden-sets.mjs` | Re-mines both golden sets from `~/.pi/agent/sessions/**.jsonl` via implicit relevance feedback (file opened within N tool calls of a `kb_search`). `--sessions/--out/--window/--repo`. Markdown pairs require the file to have appeared in that search's own results; source pairs resolve to the documenting AGENTS.md record. See change: fix-kb-search-retrieval-quality. |
| `eval/run-fixtures.ts` | Scores every ranking variant (baseline → dedup → quota → coverage rerank → PRF) over both fixtures against a real index of this repo; variants are `overrides` over the shared `searchOptsFromConfig` base. `--fresh` rebuilds the tmp index (minutes), else reuses it; `--sweep` walks the lane-quota share on the dedup-only base AND the `laneLeadMargin` axis `{0,0.1,0.2,0.3,0.5}` (+ a `coverageRerank`/PRF spot-check row) as PAIRED rows via `buildPairedRow`; `--json`. Passes `roots` to `evaluate` — omitting them made the D4 reachability rule drop EVERY path-bearing expect (source-intent n=0) — and throws on a zero-scored fixture. See change: fix-kb-search-retrieval-quality; fix-kb-eval-measurement-integrity; fix-kb-search-lane-composition. |
| `eval/sweep-rows.ts` | `buildPairedRow(variant, metricsBySet)` + `PAIRED_SETS`. Builds one sweep row carrying BOTH golden sets side by side; throws when a fixture is missing or scored 0 items — a half-reported row is the exact shape that hides a lane regression. Extracted from `run-fixtures.ts` so the invariant is unit-testable (the script indexes the whole repo on import). See change: fix-kb-search-lane-composition. |
| `verify.ts` | verify script. NODE_OPTIONS=--experimental-sqlite tsx verify.ts. Deliberate store-default consumer of SearchOpts (`{ limit }` only) — NOT converted to searchOptsFromConfig (would silently change kb dox/verify behaviour). See change: fix-kb-eval-measurement-integrity. |
| `vitest.config.ts` | vitest config for kb package. `pool:"forks"` + `maxWorkers:PARALLEL_MAX_WORKERS` matches the repo-wide project convention — required for the root runner to group this project (added to `vitest.config.ts` projects so kb tests finally gate CI). See change: fix-kb-search-retrieval-quality. |