search: retrieve without reading the whole bundle

When to use it

• "What do we know about X?", "Where is X documented?", "Which concept covers the invoice dedup key?": a pointed question, not broad task context.
• Before pasting a bundle into the context window. The whole point of the format is that you never need to.
• When you suspect the knowledge exists but nobody remembers where. Finding it cheaply is what keeps the bundle in the loop at all.

What the agent does

Retrieval is progressive disclosure end to end. Every step pays a few hundred bytes to decide what the next step reads; full bodies come last, and only the winners.

1. Ingest the map, decide where to look. okf index --no-body is the skeleton: every directory, its counts, types, tags, children. The agent does the semantic matching here. The question names a meaning, the map names areas, and connecting the two is judgment, not string equality. A promising area costs one more call: okf index <dir> --area billing returns its authored index body and listing.
2. Cut across with the finder when the question is lexical. An exact symbol, an error code, a phrase goes to okf search, scoped by what the map taught: --area billing --type Decision. Ranked rows with snippets come back, and often the snippet already answers.
3. Read only the winners. A match row's id is its file. The agent reads that one file, follows its links one hop at a time, and checks log.md when freshness matters.
4. Answer with citations, then write back. The concept ids used are cited in the answer. If the answer was missing, stale, or needlessly hard to find, the agent switches to maintain and records what it learned. Retrieval friction is curation signal.

The division of labor stays sharp: the CLI is exact and deterministic by default; the agent is the fuzzy layer. Synonyms and vocabulary drift are handled by reasoning over the map and okf tags, because judgment about meaning beats approximate string matching at that job. The tool does carry a --fuzzy flag, and it earns its keep on one narrow case: a genuine typo, or a spelling you half remember. Reach for it there, not as a substitute for learning the bundle's own words.

Try it

In Claude Code with the okf plugin:

/okf:gem search where do we document the invoice dedup key?

Or ask the skill in plain words: "Search the bundle: what do we know about retry idempotency?"

Pitfalls

• The dump is the anti-pattern. okf graph --json with bodies, or reading the whole tree "for context", costs more than every step of the ladder combined. The gem's own test suite pins the economics: the progressive path must answer a planted question in under a quarter of the bytes of the full dump.
• Grep before map misses what is not there. Grep cannot find the index entry that is missing, and line hits do not rank. Go through the format's own views first; grep is the fallback when the CLI is absent.
• Synonym hammering. Mechanically retrying near-identical terms is token spend without judgment. Learn the bundle's vocabulary from its tags and types, then ask in its own words.