[tonyketcham]

Summary of changes

Stacked on #281. This layer adds one read, flatbread proof find, and nothing else.

The recall benchmark in #281 showed why agents fail on a large graph: they cannot locate a record by what it says. On a graph ten times larger, "unknown" answers nearly doubled while reading stayed flat. A summary (proof brief) holds too little detail, and paging (proof records) holds too much noise.

proof find "<words>" [--effort <id> | --all] [--kinds ...] [--as-of <date>] [--retracted include|only] [--limit n] ranks records with BM25, a standard keyword score, over titles, full bodies, Blob payloads, and a few fields. Entity terms count extra: numbers with units, people, and code references. It prints at most 10 short cards inline (5 by default):

• one card per supersession chain, showing its live head and standing, which version matched, and the dated chain;
• the best 160-character passage anywhere in the body, so facts past the browse cut are visible;
• one hop of links in both directions, capped per relation;
• a code: line naming files, symbols, and commits the records cite.

With --all, candidate Efforts are ranked side by side, so an ambiguous prompt shows where it may belong. --as-of shows the version current at a date and ignores text written later. The index is built in memory beside the cached graph, and proof serve answers find like the other reads.

On the benchmark's 10x graph (4,980 records) a served query takes about 0.2 s, and five cards come to about 1,500 tokens. For the question "How much does one fixed-point tide step cost on Meridian?", which both strategies gave up on in the 10x run, the top card answers it. Whether find raises accuracy is the next layer's experiment.

Two reviewers checked correctness and size limits before this was committed; all 17 of their findings are fixed, including multi-word queries that the local CLI cut to one word, --as-of values read in the local time zone, and cards that dropped every link to fit.

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

• I added doc comments to any new public exports, and inline comments to any hard-to-understand areas
• My changes generate no new console errors locally
• If applicable, try to include a test that fails without this PR but passes with it (find.test.ts unit tests; serve.test.ts covers find locally and through proof serve)

Does this introduce any non-backwards compatible changes?

• Yes
• No

Does this include any user config changes?

• Yes
  • If so, I have updated the relevant areas of documentation
• No

The Proof skill (SKILL.md, reference.md) now tells agents to locate records with find, read full text with get, and use records only to count or page.

---

Generated by Claude Code