docs(readme): state the goal — one question, one complete answer, and the two stair-steps toward it

[joyful-ii-V-I]

The page said what ripwire does and never said what it is for. This is the objective in a reader's terms rather than a maintainer's — terminality, and the two properties that make it reachable in practice — placed above the fold, after the pitch and before the lineage block.

### The goal: one question, one complete answer.

**Terminality is the objective.** Ask the codebase a question and the answer should carry everything
you need — no follow-on grep, no three more whole-file reads to fill in what it left out. A call
followed by three greps is the same search paid for twice: it does not save you tokens and it does
not make the coding faster.

**Two things make that reachable in practice, and neither is the destination.** Answers are honest
about their own limits — a count that cannot be a total is labelled a floor, a zero means "none
found" and never "none exists", every truncation is disclosed — so an answer never looks more
complete than it is, and the map never degrades the code by guessing. And an answer can be given a
token budget, so what one costs is something you ask for rather than discover; where a complete
answer will not fit, it says it went over rather than silently dropping the row you needed.

Those two are the stair-steps: honest about what is missing, priced in what it spends. The step they
climb toward is a question fully answered in one call, which is not always trivial to reach — and
where it is not, the output says so rather than pretending otherwise.

Deliberately not written as a hard cap. An earlier draft said "answers are bounded, so a complete answer cannot cost you the context it was supposed to protect", which is false by the tool's own design: docs/METHODOLOGY.md §9 principle 2 exceeds the ceiling with over_ceiling="1" rather than drop the row that would have terminated the search. A hard-cap claim would also have undercut the terminality paragraph directly above it. It reads instead as a budget you ask for with disclosed overshoot — true, and the stronger form of the point.

Two other claims pulled back to what is actually true. "An answer never looks more complete than it is" rather than "never a confident wrong one" — the honesty attributes stop an answer overstating itself; they do not make the resolver infallible, which is what amb="K" exists to disclose. And "an answer can be given a token budget" rather than every answer being bounded, since the flag table carries honorsMaxTokens per verb.

Sequenced behind #61. The overshoot sentence is the contract and over_ceiling ships, but #61 was an open bug against that contract on the --for --detail path — max_tokens was named and applied to the bodies only. This lane was held until #77 landed and #61 closed, so the claim is true of the shipped tool rather than aspirational.

No counts, no flag names, no published number — nothing here collides with a gate-count site or the absorb line.

CI: run 34413952370 — 26/26 green on 86612185.

🤖 Generated with Claude Code

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: d1c55826-88a6-4f45-8bcf-156d8b0394d4

📥 Commits

Reviewing files that changed from the base of the PR and between c38d3ee and 8661218.

📒 Files selected for processing (1)

• README.md

Cache: Disabled due to data retention organization setting

Knowledge base: Disabled due to Reviews -> Disable Knowledge Base setting

---

📝 Summary

Summary by CodeRabbit

• Documentation
  • Added guidance explaining the tool’s goal of providing complete answers to codebase questions in a single call.
  • Documented answer limitations, including disclosed truncation and configurable token budgets.

Walkthrough

README.md adds a section that defines the goal of answering one codebase question in one call. It documents floor counts, disclosed truncations, and token-budget reporting.

Changes

Answer documentation

Layer / File(s)	Summary
Answer goals and limits README.md	Documents complete-answer behavior, honesty guarantees, and configurable token-budget limits.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Suggested reviewers: andriytyurnikov, pollybot13

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/readme-terminality-goal

---

_{Comment @coderabbitai help to get the list of available commands.}