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

README.md

@@ -4,36 +4,19 @@
 [![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](#license)
 [![Rust 1.95+](https://img.shields.io/badge/rust-1.95%2B-orange.svg)](https://www.rust-lang.org)
 
-> _PRs in this repo are driven end-to-end by the aram-ai-global v3 multi-agent stack._
-
 **A deterministic design-system linter for rendered websites, not the code behind it.**
 
 Plumb opens a web page in a headless browser at multiple viewports, extracts the computed DOM, and measures it against a declarative design-system spec. It emits structured, pixel-precise violations an AI coding agent can fix in one shot — "ESLint for rendered websites."
 
 Plumb ships as a single Rust binary with two entry points:
 
-- A **CLI** (`plumb lint <url>`) for developers and CI/CD.
+- A **CLI** (`plumb lint <url>`) for developers and CI.
 - An **MCP server** (`plumb mcp`) that exposes tools to AI coding agents (Claude Code, Cursor, Codex, Windsurf) via the Model Context Protocol.
 
-## Status
-
-Pre-alpha. The walking skeleton is in place; real rules and the real browser driver land in subsequent PRs. See the [PRD](docs/local/prd.md) (local-only) for the full product scope.
-
-## Quick start
-
-> Install commands are placeholders until the first release. For now, build from source:
->
-> ```bash
-> git clone https://github.com/aram-devdocs/plumb
-> cd plumb
-> just setup
-> just build-release
-> ```
-
-After the first release:
+## Install
 
 ```bash
-# macOS / Linux / Windows
+# Install script (macOS / Linux / Windows)
 curl -LsSf https://plumb.aramhammoudeh.com/install.sh | sh
 
 # Cargo
@@ -46,12 +29,13 @@ brew install aram-devdocs/plumb/plumb
 npm i -g plumb-cli
 ```
 
+Per-channel notes, version pinning, and offline attestation verification live in the [Install](https://plumb.aramhammoudeh.com/install.html) page.
+
 ## Documentation
 
-- [The Plumb Book](https://plumb.aramhammoudeh.com) (coming soon — built from `docs/src/`)
+- [The Plumb Book](https://plumb.aramhammoudeh.com) — install, quick start, CLI, configuration, MCP, rules.
 - [Contributing](CONTRIBUTING.md)
 - [Security policy](SECURITY.md)
-- [Code of conduct](CODE_OF_CONDUCT.md)
 - [Changelog](CHANGELOG.md)
 
 ## License

docs/src/blog/launch-v0.6.md

@@ -5,8 +5,7 @@ an open Discussions tab for questions, ideas, and field reports.
 
 If you want to see the project as it exists today, start with
 [plumb.aramhammoudeh.com](https://plumb.aramhammoudeh.com/). That is
-the current public docs URL. `plumb.dev` is not the canonical docs
-domain yet, so keep using the `aramhammoudeh.com` address for now.
+the current public docs URL.
 
 ## What shipped in v0.6
 
@@ -20,33 +19,19 @@ websites. It has two entry points:
 - `plumb lint <url>` for local runs and CI
 - `plumb mcp` for AI coding agents
 
-## Install status
+## Install
 
-The install page in the book lists four channels:
+Plumb is published to crates.io, npm, and a Homebrew tap, with a curl
+install script and prebuilt platform archives. The full set of channels
+lives on the [Install](../install.md) page; the [Quick start](../quickstart.md)
+walks through the first run.
 
-- install script
-- `cargo install`
-- Homebrew
-- build from source
-
-Today, the supported path is still build from source. The other channels
-are documented so the book does not need a rewrite on release day, but
-they do not replace the source build yet.
-
-If you want to try Plumb right now:
+If you want to lint the live docs site as a smoke test:
 
 ```bash
-git clone https://github.com/aram-devdocs/plumb
-cd plumb
-just setup
-just build-release
-target/release/plumb --version
-target/release/plumb lint plumb-fake://hello
+plumb lint https://plumb.aramhammoudeh.com
 ```
 
-The full setup notes live on the [Install](../install.md) and
-[Quick start](../quickstart.md) pages.
-
 ## Demo and docs
 
 The live docs site is the easiest demo at the moment:
@@ -55,12 +40,6 @@ The live docs site is the easiest demo at the moment:
 - [Install](https://plumb.aramhammoudeh.com/install.html)
 - [Quick start](https://plumb.aramhammoudeh.com/quickstart.html)
 
-If you already have a local build, you can lint the live site directly:
-
-```bash
-plumb lint https://plumb.aramhammoudeh.com
-```
-
 ## Join the discussion
 
 GitHub Discussions is now on for the repo:

docs/src/ci/github-code-scanning.md

@@ -32,7 +32,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Install Plumb
-        run: cargo install --git https://github.com/aram-devdocs/plumb plumb
+        run: cargo install plumb-cli
 
       - name: Run Plumb
         id: plumb

docs/src/ci/reviewdog.md

@@ -58,7 +58,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Install Plumb
-        run: cargo install --git https://github.com/aram-devdocs/plumb plumb
+        run: cargo install plumb-cli
 
       - uses: reviewdog/action-setup@v1
         with:

docs/src/cli.md

@@ -30,6 +30,7 @@ major version falls in Plumb's supported range (see
 | `--hide-scrollbars [bool]` | CSS scrollbar killer. Default `true`. |
 | `--dpr <factor>` | Pin device-pixel ratio for `Emulation.setDeviceMetricsOverride`. |
 | `--suggest-ignores` | Append a suggested `.plumbignore` block. See [`--suggest-ignores`](./cli/suggest-ignores.md). |
+| `--auto-fetch-chromium` | Download Chrome-for-Testing into Plumb's cache when no `--executable-path` is given and no system Chromium is detected. See [Install Chromium](./install-chromium.md#auto-fetch-opt-in). |
 
 Exit codes:
 
@@ -90,12 +91,11 @@ Stdout carries the rendered lint output (`pretty` by default;
 can tail the watch output with the JSON consumer of your choice
 without losing the status line.
 
-Watch flags mirror `plumb lint`'s. Two extras:
+Watch flags mirror `plumb lint`'s. One extra:
 
 | Flag | Description |
 |------|-------------|
 | `--path <dir>` | Directory to watch. Repeatable. Defaults to CWD. |
-| `--once` | Hidden — runs a single cycle and exits, used by tests. |
 
 A `.plumbignore` file at the root of any watched directory excludes
 paths whose substring matches any of its lines. Blank lines and lines

docs/src/configuration.md

@@ -53,9 +53,9 @@ configuration fields.
 [rules."<id>"]        # per-rule overrides
 ```
 
-The walking skeleton defaults to a single `desktop` viewport at
-1280×800 if `[viewports.*]` is omitted. Real runs SHOULD declare every
-viewport explicitly.
+If `[viewports.*]` is omitted, Plumb defaults to a single `desktop`
+viewport at 1280×800. Real runs SHOULD declare every viewport
+explicitly.
 
 ## `[viewports.<name>]`
 

docs/src/install.md

@@ -1,23 +1,14 @@
 # Install
 
-Plumb ships as a single binary. Pick the channel that matches your
-shell and your tolerance for tracking pre-release builds.
+Plumb ships as a single binary. Pick the channel that matches your shell.
 
-> **Pre-release notice.** Plumb is pre-alpha. The install script,
-> `cargo install`, and Homebrew channels become available at the first
-> tagged release. Until then the supported install path is "build from
-> source." The other commands are listed here so the page does not
-> change shape after release day.
-
-## Channels at a glance
-
-| Channel | Best for | Status |
-|---------|----------|--------|
-| Install script | macOS / Linux / Windows users who want one-line install | Available at first release |
-| `cargo install` | Rust developers already on `cargo` | Available at first release |
-| Homebrew tap | macOS / Linux Homebrew users | Available at first release |
-| `npm i -g` | Node-tooling shops that already pin CLI tools through npm | Available at first release |
-| Build from source | Contributors and pre-release testers | Available now |
+| Channel | Best for |
+|---------|----------|
+| Install script | macOS / Linux / Windows users who want one-line install |
+| `cargo install` | Rust developers already on `cargo` |
+| Homebrew tap | macOS / Linux Homebrew users |
+| `npm i -g` | Node-tooling shops that already pin CLI tools through npm |
+| Build from source | Contributors hacking on Plumb itself |
 
 After install, run `plumb --version` to confirm. Then point yourself at
 the [Quick start](./quickstart.md).
@@ -63,7 +54,7 @@ This builds from source against the version published to crates.io.
 Pin a version with `--version`:
 
 ```bash
-cargo install plumb-cli --version 0.1.0
+cargo install plumb-cli --version 0.0.2
 ```
 
 ## Homebrew
@@ -92,7 +83,7 @@ before extracting it.
 
 ## Build from source
 
-This is the only supported path until the first release. You need:
+Use this path if you're hacking on Plumb. You need:
 
 - `git`
 - A Rust toolchain (1.95+). Install via [`rustup`](https://rustup.rs/).

docs/src/introduction.md

@@ -59,7 +59,7 @@ Pick the channel that fits your workflow:
 - [`cargo install`](./install.md#cargo) — if you already have a Rust toolchain
 - [Homebrew](./install.md#homebrew) — `brew install aram-devdocs/plumb/plumb`
 - [npm](./install.md#npm) — `npm i -g plumb-cli`
-- [Build from source](./install.md#build-from-source) — the only path available today (pre-alpha)
+- [Build from source](./install.md#build-from-source) — for hacking on Plumb itself
 
 Then continue with the docs for your workflow:
 
@@ -68,11 +68,6 @@ Then continue with the docs for your workflow:
 - [GitHub Code Scanning](./ci/github-code-scanning.md) for SARIF in CI
 - [reviewdog](./ci/reviewdog.md) for PR feedback in CI
 
-## Status
-
-Pre-alpha. The current public docs live at
-`https://plumb.aramhammoudeh.com/`.
-
 ## Next
 
 - [Install](./install.md) — pick a release channel.

docs/src/mcp/claude.md

@@ -52,40 +52,6 @@ Run a quick smoke test by asking Claude Code:
 
 If the tool returns your message, the transport is working.
 
-## Verified locally
-
-The plumb MCP server has been wired into a live Claude Code session.
-The agent invoked `lint_url` against `plumb-fake://hello` (the canonical
-walking-skeleton URL); the response below is the actual JSON returned
-by the server.
-
-```text
-Tool call: mcp__plumb__lint_url with `{"url": "plumb-fake://hello"}`
-```
-
-```json
-{
-  "violations": [
-    {
-      "rule_id": "spacing/grid-conformance",
-      "severity": "warning",
-      "message": "`html > body` has off-grid padding-top 13px; expected a multiple of 4px.",
-      "selector": "html > body",
-      "viewport": "desktop",
-      "rect": { "x": 0, "y": 0, "width": 1280, "height": 800 },
-      "dom_order": 2,
-      "fix": {
-        "kind": { "kind": "css_property_replace", "property": "padding-top", "from": "13px", "to": "12px" },
-        "description": "Snap `padding-top` to the nearest spacing-grid value (12px).",
-        "confidence": "medium"
-      },
-      "doc_url": "https://plumb.aramhammoudeh.com/rules/spacing-grid-conformance"
-    }
-  ],
-  "counts": { "error": 0, "warning": 1, "info": 0, "total": 1 }
-}
-```
-
 ## Lint a page
 
 Ask Claude Code:

docs/src/mcp/compare-viewports.md

@@ -121,5 +121,6 @@ text content block describing the error.
 
 ## See also
 
-- [`lint_url`](./lint_url.md) — single-viewport lint.
-- [PRD §14.2](../../local/prd.md) — MCP response shape.
+- [MCP server reference](../mcp.md) — single-viewport `lint_url` and
+  full tool list.
+- [Configuration](../configuration.md) — `plumb.toml` reference.

docs/src/rules/baseline-rhythm.md

@@ -92,4 +92,4 @@ severity = "error"
 
 - [`spacing/grid-conformance`](./spacing-grid-conformance.md) — the
   horizontal spacing-grid sibling.
-- PRD SS11.3 -- vertical rhythm and baseline alignment.
+- PRD §11.3 — vertical rhythm and baseline alignment.