Overhaul README for clarity, accuracy, and install path

[mattstein111]

Summary

Full README overhaul applying feedback from an independent review. The goal is to make the marketplace install flow the front door, cover prerequisites explicitly, and fix accuracy gaps between what the README claimed and what the code does.

Structural changes

• Lead with claude plugin install sms@mattstein111/claude-code-sms — the git-clone flow is now a collapsed "from source" block. This was the single biggest friction point for new users.
• New Prerequisites section (Bun, provider/DID, tunnel, systemd/launchd, Claude Code) so readers can tell in 30 seconds whether they can run this.
• New "What it looks like" section near the top, showing a real <channel> tag Claude receives and the actual permission-relay SMS text.
• Bold default-deny callout up top — security-minded readers no longer have to scroll to the gate table to learn unknown numbers are dropped.
• /sms:configure is now the primary Quick Start path; the manual .env/access.json walkthrough moved into <details>.
• New Troubleshooting section covering listener down, 401 from provider, silent drop on allowlist, MCP startup crash, and permission relay not firing.
• Multi-session / DID subscription detail collapsed into <details> so the main flow reads cleanly.
• Concrete Cloudflare Tunnel one-liner and a security note that tokens in URL query strings can leak via provider logs.

Accuracy fixes (things the old README got wrong)

• download_attachment requires a chat_id parameter — previously undocumented. Access scoping would bite any user who tried to call it.
• fetch_messages response shape documented, including the 200-item cap.
• dmPolicy: "disabled" value is now documented alongside "allowlist".
• Permission replies accept y/yes/n/no, case-insensitive, with whitespace tolerance (regex is /^\s*(y|yes|n|no)\s+([a-km-z0-9]{5})\s*$/i).
• All ten listener security layers mentioned in one sentence; the high-level diagram only shows five.
• SMS_PROVIDER=twilio example swapped for SMS_PROVIDER=other since voip.ms is the only tested path.
• Wildcard matching clarified as prefix-based rather than area-code-specific.
• Dedicated providers' untested status called out at the top of their table, not buried in Known Limitations.
• Fixed stale "launched March 2026" reference.
• License section rewritten. The old text ("Private. Not yet licensed for distribution.") contradicted a public repo that invites install via claude plugin install. New text says personal project, offered as-is, open an issue if you need a formal license. If you want a proper OSI license (MIT is typical for this kind of plugin), happy to follow up with a LICENSE file.
• Contributing-a-provider links to providers/twilio.ts (dedicated) and providers/other.ts (generic) as reference implementations.
• Fixed launchd plist filename (com.claude.sms-listener.plist).

Nits

• Clarified "owner's own phone" in the opening line.
• Added a 0.2.3-beta status badge.
• Called out chmod 600/700 enforcement rationale.

Test plan

• Read the rendered README on the branch and confirm the flow matches your mental model
• Decide whether to adopt a proper OSI license (MIT?) and add a LICENSE file in a follow-up
• Optional: have someone unfamiliar with the project attempt setup from the new Quick Start

🤖 Generated with Claude Code