docs: rewrite README to house standard

[steipete]

Summary

• Reworks the README around the house-standard path: pitch, dynamic badges, install, quick start, progressively deeper usage, development, and license.
• Keeps the front door at 90 lines while preserving the detailed command examples in docs/usage.md and linking the existing protocol/implementation spec.
• Uses only verified distribution channels: Homebrew, Go install, GitHub release archives, and the existing Docker build.

Moved or dropped

• Moved command examples, automation flags, Spotify OAuth setup, shell completions, Docker usage, source helpers, and prior-work links to docs/usage.md.
• Left discovery internals, endpoint details, CLI behavior, and implementation layout in the existing docs/spec.md.
• Dropped the dated, unverified claim about BluShell's license state. Replaced the unreachable ice1.somafm.com example with an audio URL that returns HTTP 200.

Verification

• go build -o dist/blu ./cmd/blu
• go test ./...
• golangci-lint run --timeout=5m
• go mod tidy followed by a clean git diff --exit-code -- go.mod go.sum
• pnpm build, pnpm test, and pnpm lint
• Installed through brew install steipete/tap/blucli; installed go install github.com/steipete/blucli/cmd/blu@latest into a temporary GOBIN.
• Validated the player-dependent quick-start shapes through the real devices, status, and now help paths because no BluOS hardware was available to this worker.
• Parsed the README config sample into the repository's Go config type and loaded both generated completion scripts.
• Resolved every relative link; all external Markdown destinations and all five badges returned HTTP 200; badge SVGs contained no invalid/not-found card.
• /Users/steipete/Projects/agent-skills/skills/autoreview/scripts/autoreview --mode local: clean, no accepted/actionable findings.

Docker was not installed on this worker, so the existing container commands were checked against Dockerfile and the repository's Docker smoke-test workflow rather than run locally. Homebrew installation and the packaged binary worked; the tap formula's separate brew test currently fails after invoking blu --version because its Ruby assertion passes a Homebrew Version object to assert_match, which is outside this documentation-only change.

CI

On exact head 219d8c85f991c874abdfc7199cf43f7faf4ebd05, both Docker jobs, both lint jobs, all six platform-test jobs, and GitGuardian passed. Both duplicate govulncheck jobs report pre-existing advisory GO-2026-5856 in the repository's pinned Go 1.25.11 standard library; the advisory is fixed in Go 1.25.12. This PR does not change the toolchain under its documentation-only scope.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed August 2, 2026, 9:18 PM ET / August 3, 2026, 01:18 UTC.

ClawSweeper review

What this changes

The PR replaces the long README with a concise installation and quick-start guide and adds docs/usage.md for detailed CLI commands, Spotify, Docker, and shell-completion guidance.

Merge readiness

✅ Ready for maintainer review

Keep this owner-authored PR open for normal merge review. The focused README/usage-guide split matches the current command, configuration, release, and container surfaces, and no discrete documentation defect or security concern was found.

Priority: P3
Reviewed head: 219d8c85f991c874abdfc7199cf43f7faf4ebd05

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	The focused documentation patch is source-aligned and has no actionable correctness finding.
Proof confidence	🌊 off-meta tidepool	Not applicable: All changed files are documentation, so external after-fix real-behavior proof is not required.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: All changed files are documentation, so external after-fix real-behavior proof is not required.
Evidence reviewed	6 items	Focused PR diff: The branch changes two documentation files only: 184 additions and 163 deletions, with no runtime, dependency, workflow, or package changes. CLI command contract: The documented command groups and global flags map to the current dispatcher, including discovery, playback, queue, diagnostics, Spotify, completions, --dry-run, and --trace-http. Configuration and selection contract: The documented config location and device-selection concepts are consistent with os.UserConfigDir, the blu/config.json path, aliases, BLU_DEVICE, cached discovery, and live discovery behavior.
Findings	None	None.
Security	None	None.

How this fits together

blucli is a Go command-line client that discovers and controls BluOS players over a local network. The README is its first-use entry point, while the usage guide expands into operational commands and the protocol specification explains implementation details.

flowchart LR
  User[User or script] --> Readme[README install and quick start]
  Readme --> Usage[Usage guide]
  Readme --> CLI[blu command]
  Usage --> CLI
  CLI --> Discovery[Player discovery and selection]
  Discovery --> Players[BluOS players]
  CLI --> Spec[Protocol specification]

Loading

Before merge

None.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Documentation surface	2 files affected; 184 added, 163 removed	The change is a contained documentation reorganization with no executable or dependency surface.

Technical review

Best possible solution:

Merge the focused README and usage-guide reorganization so the README remains a concise first-use path and docs/usage.md remains the detailed operational reference.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this PR changes documentation rather than fixing a reported behavior defect. Its command and configuration statements were checked directly against current source.

Is this the best way to solve the issue?

Yes: separating a concise first-use README from a detailed usage guide is the narrowest maintainable solution, and the inspected examples align with current command and packaging contracts.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against e19ab32fa5d8.

Labels

Label changes:

• add P3: This is a low-risk documentation and onboarding refinement with no supported runtime regression.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: All changed files are documentation, so external after-fix real-behavior proof is not required.

Label justifications:

• P3: This is a low-risk documentation and onboarding refinement with no supported runtime regression.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: All changed files are documentation, so external after-fix real-behavior proof is not required.

Evidence

What I checked:

• Focused PR diff: The branch changes two documentation files only: 184 additions and 163 deletions, with no runtime, dependency, workflow, or package changes. (README.md:1, 219d8c85f991)
• CLI command contract: The documented command groups and global flags map to the current dispatcher, including discovery, playback, queue, diagnostics, Spotify, completions, --dry-run, and --trace-http. (internal/app/run.go:108, e19ab32fa5d8)
• Configuration and selection contract: The documented config location and device-selection concepts are consistent with os.UserConfigDir, the blu/config.json path, aliases, BLU_DEVICE, cached discovery, and live discovery behavior. (internal/config/config.go:63, e19ab32fa5d8)
• Distribution coverage: The release configuration builds macOS, Linux, and Windows archives, while the release workflow dispatches the Homebrew tap update; this supports the rewritten install guidance. (.goreleaser.yaml:9, e19ab32fa5d8)
• Documentation provenance: The existing README dates to the v0.1.5 release commit, and the proposed rewrite is a single focused commit based directly on current main. (README.md:1, 219d8c85f991)
• Release baseline: Current main is newer than the latest shipped v0.1.5 tag; the documentation branch is not merged and is therefore not part of a release. (README.md:1, e19ab32fa5d8)

Likely related people:

• steipete: The repository owner authored both the v0.1.5 README baseline and this focused documentation rewrite; available README history points to that continuing ownership. (role: recent documentation contributor; confidence: high; commits: c2fe0b16c983, 219d8c85f991; files: README.md, docs/usage.md)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.