jedarden adab169bed docs(miroir-ctl): add subcommand runbooks and help text (P11.4, miroir-uyx.4)

- Created docs/ctl/*.md runbooks for all 16 miroir-ctl subcommands
- Each runbook includes: purpose, preconditions, examples, gotchas, see also
- Added runbook location to --help output
- All runbooks under 50 lines for easy reading

Closes: miroir-uyx.4

2026-05-24 11:47:36 -04:00

1,011 B

Raw Blame History

`miroir-ctl explain`

Purpose

Analyze query plans and show how search queries are routed across shards.

Preconditions

Index must exist
Admin API key configured

Examples

# Explain a simple search query
miroir-ctl explain --index myindex --q "test query"

# Explain with filters
miroir-ctl explain --index logs --q "error" --filter "timestamp > 2024-01-01"

# Explain with ranking details
miroir-ctl explain --index myindex --q "test" --show-ranking

# Show shard routing for a query
miroir-ctl explain --index myindex --q "test" --show-routing

Gotchas

Not yet implemented — see tracking bead for details
Explain doesn't execute the query — it only shows the plan
Use --show-routing to understand which nodes are contacted
Ranking details show score breakdown per field
Explain is useful for debugging slow queries — check per-shard latency

1,011 B Raw Blame History

miroir-ctl explain

Purpose

Preconditions

Examples

Gotchas

See also

1,011 B

Raw Blame History

`miroir-ctl explain`