fix: README line-by-line audit — internal consistency + accuracy

[justi]

Summary

Five fixes from a critical line-by-line audit of the README — internal consistency between the sample document, the cutoff date, and the marketing punchlines.

Findings

#	Severity	Where	Problem	Fix
1	HIGH	Line 30	"done arguing about Rails 7 syntax on a Rails 8 app" — sample shows cutoff 2026-01-31, by which point Claude already knows Rails 8	Reworded to match the data: "it sees the 8.1.3 patch and the CVE before it touches your code"
2	HIGH	Line 27	Sample CVE bullet referenced 8.0.2.1 + CVE-2025 alongside 8.1.x deltas — confusing	Replaced with a hypothetical 8.1.3 advisory + CVE-2026 stamp consistent with the post-cutoff window
3	HIGH	Line 114	"Why I built this" had same Rails-7-on-Rails-8 mismatch	Reworded to a realistic patch-level scenario
4	HIGH	Line 133	"GitHub Discussions" — repo has Discussions disabled (gh repo view --json hasDiscussionsEnabled returns false)	Replaced with "Open an issue tagged enhancement, or send a PR"
5	MEDIUM	Line 128	"adapter surface is small (~4 functions)" — real contract is seven (parser + 3 local/HTTP pairs)	Reworded to spell out the real shape

What I verified to ground the audit

• ✅ Rails sub-gem count: README claims 12, code confirms exactly 12 (RUBY_RAILS_SUBGEMS in lib/adapters/ruby/local.sh)
• ✅ Test count: README claims ~205, full suite reports exactly 205 (10+8+6+6+35+13+7+4+23+16+11+22+11+33)
• ✅ Version: README claims v0.3.1, bin/postcut:4 confirms VERSION="0.3.1"
• ✅ Cutoff date for claude-opus-4-7: 2026-01-31 matches model's actual training cutoff
• ✅ All flags listed in Usage exist in bin/postcut
• ❌ Adapter function count: README said ~4, real is 7 — fixed in this PR
• ❌ GitHub Discussions: README pointed there, but repo has them disabled — fixed in this PR (alternative: enable Discussions on the repo and revert this part of the fix)

Stats

• 5 insertions, 5 deletions — surgical
• 138 lines (unchanged)
• No code touched, no tests touched

Test plan

• git diff --stat — only README.md, 5/5
• Full test suite still 205/205 (unchanged)
• Manual eyeball of each edit in context

Open question for the maintainer

If you want GitHub Discussions instead of issue tags for "ideas / use cases", enable Discussions in repo Settings → Features and revert the line 133 edit. Otherwise this fix is the safer default.

🤖 Generated with Claude Code

[justi]

Second codex pass on the README (resumed prior thread, confronted with what it missed) — codex acknowledged the prior misses with a postmortem (reading-pass failure / assumption error / scope issue / verification failure / codebase-scope miss) and surfaced four follow-up findings, all addressed in commit dea58f6:

#	Severity	Where	Fix
1	MEDIUM	Line 27 (sample CVE)	Fabricated GHSA + CVE IDs from the previous fix swapped for explicit placeholders (GHSA-XXXX-XXXX-XXXX / CVE-2026-XXXXX). A made-up real-looking advisory undermines factual posture more than the original mismatch.
2	MEDIUM	Line 109 (GITHUB_TOKEN)	Was "rate limit on registry/advisory calls" — token actually only affects GitHub API (releases + advisories), not RubyGems registry. Reworded to match lib/core/github.sh scope and CLI help text.
3	LOW	Line 44 (install)	"symlinks into PATH" was unconditional — install.sh prints an export PATH=... hint when no writable bin dir found. Added the caveat.
4	LOW	Lines 18-21 (sample)	Sample omitted two blockquote guidance lines that lib/core/save.sh:96-97 actually emits before the per-gem sections. Added them so "What it generates" stays a faithful sample.

The pattern across both audit rounds: copy-driven inconsistencies were caught quickly; technical/factual claims required either grepping the codebase or running gh repo view. Worth keeping that gap in mind for future review prompts.