Should `--limit` bound the whole `context` response, or only the ranked seeds?

Gap: issue-996b567e5131 Blocking: yes · Rank: 3 · Asked: 2026-07-26 · Answered: 2026-07-26 Authority: repo maintainer (chose "bound the response, add --expand N")

Question¶

docir context --limit 3 returned 9 documents, because one-hop graph expansion runs after the limit and is itself uncapped. Should --limit bound the whole response, or is it deliberately a seed-set size with expansion on top — and if so, what bounds the response an agent receives?

What the system does today¶

OBSERVED: 3 decisions with out-degree 2, --limit 3 → 9 results. Worst case is limit × (1 + max out-degree), growing with graph density. Evidence: document_service.py:260-273 (limit enforced), :297-307 (expansion, uncapped).

Proposed answer¶

--limit bounds the final result. If expansion should be separately controllable, add --expand N with a small default and document the interaction.

Why it matters¶

docir's headline claim is "token-cheap for agents" and context is the flagship command with a default limit of 5. The overrun scales with exactly the well-linked corpus the product encourages, so it worsens as adoption succeeds.

Answer¶

ANSWERED 2026-07-26: bound the response, with --expand N for neighbour control. Implemented as reserved-then-backfilled slots. See issue-996b567e5131 resolution.

---

Migrated from the discovery question queue (Q-003); the queue itself now lives in this store.