Search & Facets - DuckBrain

The query surface is four universal facets that map to SQL predicates, an ambient view layer, and one escape hatch. Calling agents compose flags; the CLI never parses natural language into args.

Facet	Flags	Example
WHO	`--person`, `--from`	`--person devon` (ships with the entity spine)
WHERE	`--in <container>`	`--in admin-cindy` — channel, chat, thread, meeting, repo
WHEN	`--since --until --on`	`--since 30d`, `--on 2026-07-01` (ISO or `Nd/Nw/Nm/Ny`)
SOURCE	`--source app[:account]`	`--source slack:autono`, `--source markdown`

Ranking modes: --mode bm25 (default — Okapi BM25 over title+text), --mode vec (local-embedding similarity), --mode hybrid (RRF fusion of both, k=60). The default only changes when the eval harness proves a mode wins. Escape hatch: --where "<raw SQL>" over the docs columns — source-specific fields stay in the VARIANT payload, reachable by SQL instead of new flags. View (ambient, set by workspace config): --instance (which brain), --class (classification ceiling), --observer (whose assertions).

duckbrain search "payroll" --source slack:autono --in admin-cindy --since 30d
duckbrain context "onboarding" --source slack:beyond --budget 3000 --mode hybrid