| name | okf-query |
| description | Multi-hop query and subgraph extraction over OKF bundles for progressive disclosure. Use when packing minimal context for long-running agents, exploring the neighborhood of a concept, or answering what relates to X within N hops. |
OKF Query & Progressive Disclosure
Goal
Answer graph questions and emit minimal context packs (subgraphs) instead of dumping entire directories.
This is the read-path optimizer. Defaults exist so a long-running agent does not eat the whole second brain.
Query types
| Intent | Approach |
|---|
| Neighbors of X | 1-hop inbound + outbound |
| Context pack for agent run | 2-hop outbound subgraph around the entry concept |
| Path A → B | BFS / path search on typed edges |
| By type | Filter concepts where frontmatter type matches |
| By tag | Filter on tags |
| Trust slice | Prefer verified: true and non-stale nodes |
Process
- Resolve bundle root and query target(s).
- Prefer deterministic tools:
- Shape results for the consumer:
- Human / agent pack: use
pack → markdown field (preferred)
- JSON: nodes + typed edges for downstream steps
- Cap pack size. Default hops = 2, max-nodes = 20. Increase only if the user needs deeper context.
- Annotate trust: mark unverified or draft nodes so consumers can deprioritize them. Do not silently omit schema-declared high-impact unverified nodes — flag them.
Deep reference: references/progressive-disclosure.md.
Progressive disclosure pack format
# Context pack: <root concept>
Hops: 2 | Nodes: N | Generated: <timestamp>
## Entry
- path, type, one-line description
## Included concepts (read order)
1. ...
2. ...
## Graph (Mermaid)
```mermaid
graph LR
A --> B
Excluded (available on request)
- siblings / deeper hops summary
## Rules
- Outbound-only by default. `--undirected` floods through Catalog hubs; prefer `impact` for “what would break?”.
- Prefer verified, active nodes when trimming packs under a size budget.
- Do not silently omit high-impact unverified nodes — flag them (`x-impact` from the owning plugin).
- Absolute paths in links inside packs so agents can open files reliably.
- Never fabricate nodes missing from the bundle.
## Done when
- Query answered with explicit hop depth and node count
- Pack is small enough for agent context (or user approved a larger extract)
