docs(cli): npm-first README + flag wrong-arch Windows ARM64 mapping

crates/plumb-cli/Cargo.toml

@@ -10,7 +10,11 @@ homepage.workspace = true
 documentation.workspace = true
 repository.workspace = true
 readme = "README.md"
-keywords.workspace = true
+# Per-crate keywords override the workspace defaults so the npm package
+# (cargo-dist copies these into the npm `package.json` keywords field
+# alongside `categories`) leads with `cli` — the term npm searchers use.
+# crates.io caps at 5 keywords; alphanumeric + dash + underscore only.
+keywords = ["cli", "linter", "design-system", "mcp", "chromium"]
 categories.workspace = true
 exclude = ["AGENTS.md", "CLAUDE.md"]
 

crates/plumb-cli/README.md

@@ -1,34 +1,62 @@
 # plumb-cli
 
-The `plumb` command-line interface — a deterministic design-system linter
-for rendered websites.
+A deterministic design-system linter for rendered websites — CLI + MCP server for AI coding agents.
 
-This crate builds the `plumb` binary. For library usage, depend on
-[`plumb-core`](https://crates.io/crates/plumb-core) instead.
+## Install
+
+```bash
+# npm (Node-tooling shops)
+npm i -g plumb-cli
+
+# Cargo (Rust toolchain)
+cargo install plumb-cli
+
+# Homebrew (macOS / Linuxbrew)
+brew install aram-devdocs/plumb/plumb
+
+# Install script (macOS / Linux)
+curl -LsSf https://plumb.aramhammoudeh.com/install.sh | sh
+```
+
+> **Intel Mac**: native binaries return when [#269](https://github.com/aram-devdocs/plumb/issues/269) closes. Use `cargo install plumb-cli` in the meantime.
+
+## What it does
 
-## Usage
+Plumb opens a page in a headless browser at multiple viewports, measures the computed DOM against a declared design-system spec, and emits structured, pixel-precise violations an AI coding agent can fix in one shot.
+
+Two entry points:
+
+- `plumb lint <url>` — for developers and CI.
+- `plumb mcp` — Model Context Protocol server for Claude Code, Cursor, Codex, Windsurf.
+
+## Quick usage
 
 ```bash
-# Lint a URL at default viewports
+# Sanity check — runs against a canned snapshot, no browser needed
+plumb lint plumb-fake://hello
+
+# Lint a real URL
 plumb lint https://example.com
 
-# Output as SARIF for GitHub Code Scanning
-plumb lint https://example.com --format sarif
+# Generate SARIF for GitHub Code Scanning
+plumb lint https://example.com --format sarif --output plumb.sarif
 
-# Start the MCP server for AI agents
+# Run as MCP server (stdio)
 plumb mcp
 
 # Explain a rule
-plumb explain spacing/scale-conformance
+plumb explain spacing/grid-conformance
 ```
 
-## Install
+## Documentation
 
-```bash
-cargo install plumb-cli
-```
+Full docs: <https://plumb.aramhammoudeh.com>
 
 ## License
 
-Licensed under either of [Apache License, Version 2.0](LICENSE-APACHE)
-or [MIT License](LICENSE-MIT) at your option.
+Dual-licensed under either:
+
+- Apache License, Version 2.0
+- MIT License
+
+at your option.

dist-workspace.toml

@@ -37,6 +37,21 @@ tap = "aram-devdocs/homebrew-plumb"
 # in the `publish-npm` job in `.github/workflows/release.yml` (not via
 # cargo-dist's built-in publish-jobs). The `NPM_TOKEN` repo secret powers
 # that push. Public install command: `npm i -g plumb-cli`.
+#
+# Known issue (audit finding H7): cargo-dist 0.28.0 auto-expands the npm
+# `supportedPlatforms` map with fallback target triples that point at
+# the wrong-arch binary. With the `targets` list above, the generated
+# `package.json` adds these entries automatically:
+#
+#   aarch64-pc-windows-msvc  → plumb-cli-x86_64-pc-windows-msvc.zip   (wrong arch — silent x86_64 install on Windows ARM)
+#   x86_64-pc-windows-gnu    → plumb-cli-x86_64-pc-windows-msvc.zip   (msvc binary, gnu host — usually OK)
+#
+# cargo-dist 0.28.0 has no knob in `dist-workspace.toml` to opt out of
+# the supportedPlatforms fallback. The fix lives in the `publish-npm`
+# job in `.github/workflows/release.yml`: extract the tarball, strip
+# the `aarch64-pc-windows-msvc` key from `package.json`, re-pack, then
+# `npm publish`. Tracked in the share-readiness plan; see the
+# follow-up PR that wires the strip step.
 
 [dist.github-custom-runners]
 aarch64-unknown-linux-gnu = "ubuntu-24.04-arm"