Doc progressive disclosure: L0/L1/L2 excerpt levels + retrieval trajectory explain

[aurexav]

Context\n- The product goal is token-efficient memory usage: return compact results first, then expand/hydrate evidence on demand.\n\nGoal\n- Add progressive disclosure for docs: return L0 (metadata + short snippet) then L1/L2 (larger excerpt windows) with an explicit retrieval trajectory.\n\nDeliverables\n- API additions:\n - docs_search returns L0 results with stable locators\n - docs_excerpts_get supports level=0|1|2 (bounded caps per level)\n- Trace/trajectory model for doc retrieval (stage-level explain):\n - candidate retrieval\n - filter application\n - fusion/rerank (if enabled)\n - excerpt hydration\n\nAcceptance criteria\n- Deterministic size caps per level.\n- Trajectory explain output is machine-readable and linkable to source_ref.\n\nRelated\n- #80 (observability)

[aurexav]

Decision (2026-02-24)

• Progressive disclosure is a first-class Doc Ext feature.
• docs_search_l0 returns L0 pointers/snippets only; L1/L2 must be fetched via docs_excerpts_get with explicit bounds.
• Keep trajectory/explain focused on excerpt selection (not a full ranking platform).

[aurexav]

Decision (2026-02-24)

• L0/L1/L2 semantics are now locked:
  • L0 = pointer+preview only (returned by docs_search_l0).
  • L1 = bounded excerpt for evidence/citation (default hydrate level).
  • L2 = larger bounded context window when L1 is insufficient.
• Hydration contract:
  • L1/L2 are obtained only via docs_excerpts_get with explicit bounds; never inline full docs in search.
  • Responses must include integrity/verification signals (hashes + selector match status) to support facts-first, fail-closed evidence use.

[aurexav]

Partial implementation landed in commit ba3cbde:

• L0/L1/L2 concepts implemented as:
  • docs_search_l0 (L0 discovery list)
  • docs_excerpts_get with level = L1|L2 (bounded excerpt hydration)

Still missing for this issue:

• Trajectory / explain payload (why retrieved, which channels contributed, selector/verification details).
• More explicit excerpt locator contract.