usage: okf find [-h] [--include-topics] [--limit LIMIT] [--where EXPR] [--breakdown]
hybrid ranked search: lexical FTS5/BM25 arm plus semantic arm
query search terms; quote multi-word queries
-h, --help show this help message and exit
--include-topics widen beyond .okf.toml declared bundle to topic folders
--limit LIMIT max results to print (default 10)
--where EXPR select concepts by an expression: `field op value` with op one of = != < <= >
>= ~ (contains), or `field in (a, b)`; combine with and, or, not and
parentheses. Fields: type, tag, path (<bundle>/<concept-id>), archived (true
or false), tier (unverified, machine-confirmed or human-reviewed), stale (true
or false), status (an absent status is stable) and any frontmatter key
(nested: a.b; through lists: verified.by, sources.resource). Timestamp keys
(generated.at, verified.at, stale_after, usage_window.from/to,
sources.last_modified, sources.usage_window.from/to) compare as instants and
take an ISO 8601 value with an explicit offset: stale_after <
2026-10-01T00:00:00Z. Archived concepts are hidden unless the expression names
`archived`. Quote a value holding spaces, + or other characters: 'a b'.
Example: (type = Runbook and tag != draft) and path ~ home-lab/
--breakdown print per-hit contributing field(s)/term(s); output is byte-identical to today
--expand-tags expand the query with semantically near registered tags before lexical
scoring; measured against the full catalogue and found ineffective for the
vocabulary-mismatch class it was built for, so it stays off by default
--json print one JSON envelope {command, ok, data, warnings, error}
Every hit's headline number is `rank: N` — its 1-based position in the
delivered list. It is the one scale comparable across a mixed-arm result,
because it IS the list order, and it claims nothing about the two arms'
raw scores being on one scale (D12: fuse_conditional hands the ranking to
whichever arm owns it, it never blends the two by score). Those raw,
non-comparable values stay out of the default output and show only with
--breakdown, one `score:` line per hit naming which arm produced it:
a/100 the FTS5/BM25 lexical arm, relative to this run's own top
a/(6 * n) the substring fallback used when no FTS index is available:
per query term 3 for a title hit, 2 for a tag hit, 1 for a
body hit, capped at one per field per term — so the maximum
cosine X.XX the semantic arm's raw cosine similarity — printed on its
own line, not folded into an a/100 fraction, because that
shape would invite comparing it against a lexical score
(D12, same rule as above).
`provenance:` names the arm that produced the line. Degradations (index
absent or stale, embedding backend unavailable) are announced on stderr,
one note per degraded arm.
--where EXPR selects the concepts the answer may hold, whichever arm owns
the ranking: the lexical, substring and semantic arms all apply it before
the result is cut to --limit. Without `archived` in the expression,
archived concepts are hidden; the semantic arm never covers them.