Refine README for clarity and concision

[lukefwalton]

What & why

This is a documentation-only change that refines the README for clarity and concision without altering any technical content or promises. The changes:

• Tighten the opening description to lead with the core value proposition
• Simplify explanations of the five core ideas while preserving technical accuracy
• Break up dense paragraphs into shorter, more scannable prose
• Reformat the "Where to take it" section as a bulleted list for readability
• Streamline the "What stays out" and "Next steps" sections
• Fix minor phrasing and punctuation throughout

The technical substance — the privacy boundary, citation grounding, mode enforcement, gold query testing, and all code references — remains unchanged. This is editorial refinement to make the existing design easier to understand on first read.

Guarantee spot-check (before → after)

Per the automated review's suggestion, the exact wording of the repo's non-negotiables, before and after the edit:

Private text never reaches the prompt

• Before: "private text cannot leak into the prompt" / "there is nothing through which private prose could reach the model"
• After: "keeps your private text out of the prompt" / "there is no path by which private prose can reach the model"

Citations grounded in retrieved evidence

• Unchanged: "assertCitationsGroundedInEvidence verifies every citation is the exact (id, url) pair of something actually retrieved. An invented source is an error, not a footnote."

Modes derived from evidence, not model self-report

• Unchanged: "re-derives the mode from the final mix — the model can't claim supported while citing nothing but hints" / "modes are re-derived from the evidence, not taken on the model's word"

not-found = empty answer, zero citations

• Unchanged: the mode table row (not-found | none, empty answer) and "validateAnswer rejects contract violations — a not-found with prose, a sourced mode without sources"

All enforcement-point references (src/no-leak.ts, src/answer.ts, src/retrieve.ts, eval/gold.yaml) are retained. The public-safe title/locator contract warning in §3 and "Make it yours" is retained verbatim in substance.

Checklist

• Documentation only — no code changes
• No impact on tests, types, or runtime behavior
• All code references and technical claims remain accurate

https://claude.ai/code/session_01WaBFvdeWXodudFEpU2dGNg

[surmado-code-review]

Automated Checks (advisory, non-blocking)

✅ All checks passed.

---

Standards Compliance

[UNVERIFIED] No standards violations are visible from the provided diff because the diff body is empty. If this is truly README.md-only, the main standards check is factual alignment with the repo’s non-negotiables, especially that the README still states these guarantees precisely and without softening them:

• private text never reaches the prompt
• citations are grounded in retrieved evidence
• modes are derived from evidence after repair/validation, not model self-report
• not-found means empty answer + zero citations

For this repo, those are not just messaging points; they are core behavioral promises, so editorial changes are still worth checking closely against the current code and eval semantics.

Summary

This appears to be a documentation-only refinement of README.md for clarity and readability, with no claimed code, test, or runtime changes. Risk is low, but the README describes the system’s most important guarantees, so the key review question is whether the wording still matches the actual enforcement points and gold-eval behavior.

Reviewer: most of the risk is in whether the revised README language still exactly matches the no-leak boundary, citation grounding, and mode/not-found semantics — the rest is standard prose cleanup.

What to pay attention to

• Opening/project description: make sure the tighter wording still leads with the two hard promises and doesn’t weaken “private text must never reach the prompt.”
• Citation/mode sections: confirm the README still says citations are validated against evidence and that answer modes come from repaired/validated evidence, not from what the model claims.
• “What stays out” / limitations / next steps: editorial simplification can accidentally broaden scope or blur non-goals; worth checking that these sections remain precise.

Things I noticed

🟡 Yellow flags — consider for this PR or a follow-up:

• [UNVERIFIED] The actual README diff isn’t included here, so I can’t confirm that the revised prose preserves the repo’s exact guarantees. For this project, docs that describe the boundary and grounding behavior are important enough that I’d want a quick spot-check against implementation and eval/gold.yaml before merge.

Good patterns

• Keeping this scoped to a single doc file is the right shape for an editorial cleanup.
• The PR description is clear about intent: improve readability without changing technical claims or promises.

Suggested improvements

1. If not already present in the edit, keep explicit references to the enforcement points (src/no-leak.ts, citation grounding/repair, eval/gold.yaml) so readers can audit claims against code.
2. For a docs-only PR like this, consider adding a rendered README preview or before/after excerpts in the PR description; that makes prose changes much easier to review.
3. Do one final pass for absolute-vs-qualified wording around the boundary and not-found behavior; those are the easiest guarantees to accidentally soften during concision edits.

Questions for the author

• Can you attach the actual README.md diff or a rendered preview? With the diff omitted here, I can’t verify that the edited wording still tracks the repo’s non-negotiable guarantees precisely.

---

Surmado Code Review (v1.2-mt) is an automated review, designed to work alongside human judgment.

Want to change your STANDARDS.md or YML? Edit it directly, or tune it with our AI agent Scout.

Comment /rerun-review on this PR to refresh the review — costs 1 additional PR credit.