| 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 neighborhood of a concept, extracting agent routing subgraphs, 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.
Query types
| Intent | Approach |
|---|
| Neighbors of X | 1-hop inbound + outbound |
| Context pack for agent run | 2-hop subgraph around entry agent + shared state |
| Routing path A → B | BFS / path search on agent-graph 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.
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
- Prefer verified, active nodes when trimming packs under a size budget.
- Do not silently omit high-impact unverified nodes — flag them.
- 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)
