docs: ship-ready cleanup pass — DRY, accurate, no AI-tell

[aram-devdocs]

Summary

Pre-V0 (0.0.2) docs cleanup. Aligns every public surface (README, mdBook book, crate READMEs) with the actual binary behavior; drops pre-alpha hedging now that the four install channels are wired; removes duplicated install copy that drifted between README, install.md, and introduction.md.

• README is now a tight elevator pitch: 4-line install block + link to install.html. No more "walking skeleton" / "coming soon" / "placeholder" status text.
• install.md drops the pre-release notice block and the "Status: Available at first release" column. Adds the npm channel.
• introduction.md drops the redundant Status section, adds the npm link, repoints "build from source" at hacking-on-Plumb rather than "the only path today".
• cli.md adds --auto-fetch-chromium (was missing); drops the hidden --once from the watch flag table.
• blog/launch-v0.6.md drops the "supported path is still build from source" claim now that brew/npm/curl/cargo are wired.
• ci/github-code-scanning.md and ci/reviewdog.md replace cargo install --git ... plumb with cargo install plumb-cli.
• mcp/compare-viewports.md fixes the broken lint_url.md link and the local/prd.md link (PRD is gitignored).
• mcp/claude.md drops the long "Verified locally" JSON blob and the "walking-skeleton URL" framing — the canonical example already lives in mcp.md.
• rules/baseline-rhythm.md fixes the PRD SS11.3 -- typo to PRD §11.3 — .

Out of scope

docs/src/ci/release-prep.md is intentionally untouched. The install-smoke validator (tests/install-smoke-validate.sh) on origin/main pins the exact "#51 wired / #52 prep-only" wording in that page; the unscoped-npm switch (PR #246) updates both files together and will replace the prep-only block.

Test plan

• cargo run -p xtask -- pre-release — green (16 rules / docs match, 9 runbook specs valid, 12 release-readiness kits valid).
• cargo run -p xtask -- sync-rules-index — green.
• just check — green (fmt, clippy -D warnings, dep-policy, install-smoke-validate, release-security-validate, all 10 stages).
• mdbook build docs — clean build, no broken intra-doc links.
• cargo test --workspace --lib --tests — all green.
• plumb {lint,init,mcp,watch,explain,schema} --help cross-checked against cli.md.

🤖 Generated with Claude Code

[github-actions]

Now I have enough to write a complete review.

---

PR #247 — docs: ship-ready cleanup pass — DRY, accurate, no AI-tell

Scope: Docs-only. No Rust code changes, no Cargo.toml changes.

1. Determinism, layering, error handling, test coverage

All four checks pass trivially — no Rust source was modified.

2. Documentation accuracy

Changes are factually correct against the codebase:

• --auto-fetch-chromium confirmed in crates/plumb-cli/src/main.rs:160,261 — addition is accurate.
• --once confirmed hidden/internal (crates/plumb-cli/src/commands/watch.rs:19 comment) — removal from user-facing docs is correct.
• cargo install --git … plumb → cargo install plumb-cli matches the unscoped rename from PR chore(ci): switch npm to unscoped plumb-cli + enable in cargo-dist installers #246.
• Version pin updated from 0.1.0 → 0.0.2 — matches current release.
• ./lint_url.md link in compare-viewports.md was broken (no such file in docs/src/mcp/); fix is valid.
• ../../local/prd.md link was pointing to a gitignored file; fix is valid.

3. Punch list

Minor — not blockers:

• README.md (old line ~43): [Code of conduct](CODE_OF_CONDUCT.md) was silently removed. The file exists and is the normal OSS governance link. Either keep it or document why it was dropped — removing it without mention is surprising.

• docs/src/mcp/compare-viewports.md:125: The replacement link [Configuration](../configuration.md) stands in for "PRD §14.2 — MCP response shape." configuration.md covers plumb.toml; it says nothing about MCP response shape. A more accurate replacement would be [MCP server reference → response shape](../mcp.md#response-shape) or similar. As-is, the "See also" entry misleads the reader about what they'll find.

• docs/src/mcp/claude.md (removed "Verified locally" block): mcp.md shows the envelope shape but uses /* … */ for violations. The removed example was the only place the complete violation object (all 9 fields + nested fix.kind) appeared in a rendered doc. The loss is minor since the schema is implied by the rules pages, but there's now no single worked example a reader can copy-paste.

• Anti-AI-writing check: new prose is clean — no flagged phrases from .agents/rules/documentation.md.

---

Verdict: APPROVE