docs: README as landing page + repo-wide staleness sweep

README rewritten 304->172 lines against the audited command surface:
- Star/follow CTAs + dynamic crates.io/CI/MIT/MSRV badges (static
  hand-maintained status badge dropped — it went stale every release)
- Removed features documented but never shipped (A/B testing, double
  opt-in, optin/suppression/dnscheck commands); "Planned Commands"
  reframed as the shipped command reality with agent-info as the
  source of truth
- Added the missing Install/Quick Start (all three channels verified:
  crates.io, 199-biotechnologies tap, git), exit-code table, hosted
  SharpClap unsubscribe section, and a one-line v0.5 roadmap entry
  linking the deliverability-guard plan
- Every CLI invocation in the file verified to exist in src/cli.rs;
  every relative link resolves

AGENTS.md/CONTRIBUTING.md/docs/subscriber-integration.md: stale
architecture and "spec isn't written yet" claims corrected to v0.4.5
reality; SharpClap companion and v0.5 plan referenced.

Author: longevityboris

AGENTS.md

@@ -8,6 +8,7 @@ them without an MCP server, schema file, or browser dashboard.
 ## Current state
 
 - **Version**: v0.4.5 (design-gate enforcement on top of v0.4.4)
+- **Hosted unsubscribe companion**: [`web/`](./web) is SharpClap, a Next.js app on Vercel that serves the public `/u/<token>` unsubscribe page and the RFC 8058 one-click POST endpoint a local CLI cannot. `unsubscribe sync` mirrors its recorded opt-outs into local SQLite suppression (`--endpoint`, `--api-key-env`, `--after`, `--limit`, `--max-pages`, `--dry-run`). Token secret: `MLC_UNSUBSCRIBE_SECRET`; sync key read from `MLC_UNSUBSCRIBE_SYNC_KEY`, falling back to `SYNC_API_KEY`. See [web/README.md](./web/README.md).
 - **Research**: see [/research](./research) for the five dossiers that informed the original design
 - **Recent plans**:
   - [v0.2 rearchitecture](./docs/plans/2026-04-08-phase-7-v0.2-rearchitecture.md) (shipped as v0.2.0)
@@ -19,6 +20,7 @@ them without an MCP server, schema file, or browser dashboard.
   - v0.4.3 patch: `skill install` / `skill status` install the embedded Codex/Claude/Gemini skill
   - v0.4.4 patch: embedded skill and `agent-info` include explicit email design rules plus `template inspect` for browser/design handoffs
   - v0.4.5 patch: `template create --from-file` and `broadcast send` preflight enforce the design + lint gate (override with `--force` / `--allow-design-errors`); JSX heuristic catches modern frameworks without an explicit React import; single design-rule scanner shared by inspect/create/send
+  - [v0.5 deliverability guard](./docs/plans/2026-07-19-v0.5-deliverability-guard.md) — planned, not shipped: send-ramp governor + bounce/complaint circuit breaker
 
 ## Production hardening (v0.3.x)
 
@@ -41,6 +43,7 @@ What "production-grade" means in this codebase:
 - **Agent-facing design guidance**: `agent-info.template_design_rules` and the embedded skill tell agents to use table wrappers, visible margins, inline link styles, restrained typography, plain-text inspection, and broadcast preview before real sends.
 - **Design handoff inspection**: run `template inspect --from-file <path>` on browser/React/JSX/design-canvas handoffs before `template create`. A `browser_prototype_needs_conversion` verdict means the file is design direction only; convert it into standalone table-based inline HTML before linting, previewing, or sending.
 - **Design + lint gate (v0.4.5)**: `template create --from-file` refuses imports whose verdict is `browser_prototype_needs_conversion` or whose lint reports any errors — error codes `template_create_design_blocked` / `template_create_lint_blocked`, override with `--force`. `broadcast send` re-runs the design check at preflight and refuses error-level findings — error code `template_has_design_errors`, override with `--allow-design-errors` or set `[guards].block_design_errors = false` in `config.toml`. The two error codes use distinct names so an agent can route a JSX handoff through conversion without confusing it with a substantive lint failure.
+- **Hosted unsubscribe sync**: unsubscribe clicks land on the SharpClap companion and stay in its Postgres until pulled. Run `unsubscribe sync` before every real send so hosted opt-outs reach local suppression; `--dry-run` verifies the endpoint and key without writing suppression or cursor state.
 
 ## Conventions
 
@@ -73,6 +76,6 @@ Returns a JSON manifest of every subcommand, every flag, every exit code. No doc
 This split exists so neither tool has to do the other's job:
 
 - `email-cli` owns the Resend API surface, accounts, profiles, transports, the inbox, the webhook listener.
-- `mailing-list-cli` owns campaigns, segmentation, templates, suppression, double opt-in, A/B testing, analytics.
+- `mailing-list-cli` owns campaigns, segmentation, templates, suppression, analytics, revenue attribution, and the hosted-unsubscribe sync.
 
 For an agent: use `email-cli` for personal correspondence, `mailing-list-cli` for newsletters and campaigns. They cooperate on the same Resend account but each one stays in its lane.

CONTRIBUTING.md

@@ -1,21 +1,15 @@
 # Contributing
 
-`mailing-list-cli` is in the spec phase. The fastest way to help right now is to shape what we build before any code lands.
+`mailing-list-cli` is a shipped Rust binary, published to crates.io and the `199-biotechnologies/homebrew-tap` Homebrew tap. Contributions to commands, tests, and docs are welcome.
 
-## Right now
-
-1. **Read [the research](./research/README.md)** — five dossiers covering modern newsletter platforms, marketing tools, Resend's API surface, deliverability and compliance at scale, and email template formats for AI agents.
-2. **Open a [Discussion](https://github.com/paperfoot/mailing-list-cli/discussions)** if you spot something missing, want a feature on the roadmap, or disagree with a direction call.
-3. **Comment on the [pinned roadmap issue](https://github.com/paperfoot/mailing-list-cli/issues)** if you want a specific command added or reshaped.
-
-## Once the binary ships
-
-Three steps:
+## How to contribute
 
 1. Fork, branch, code.
 2. Run `cargo test` and `cargo clippy` until both are green.
 3. Open a PR. Keep it focused — one feature or one fix per PR.
 
+For anything larger than a bug fix, open an [issue](https://github.com/paperfoot/mailing-list-cli/issues) first so the shape is agreed before you build. The [research dossiers](./research/README.md) explain why the tool is designed the way it is; the release process lives in [docs/release.md](./docs/release.md).
+
 ### Conventions
 
 - We follow the [agent-cli-framework](https://github.com/paperfoot/agent-cli-framework) patterns. Read the framework README before adding new commands.
@@ -28,7 +22,7 @@ Three steps:
 ### Tests
 
 - Unit tests live next to the code.
-- Integration tests verify the public CLI surface end-to-end against a recorded Resend fixture.
+- Integration tests verify the public CLI surface end-to-end against a stub email-cli script (`tests/fixtures/stub-email-cli.sh`) — this crate has no Resend code of its own; every API call goes through email-cli.
 - A spec test ensures every command listed in `agent-info` is routable.
 
 ## Code of conduct