docs: rewrite README to house standard

[steipete]

Summary

Rewrites the README as a 95-line front door with the house-standard title, dynamic badge row, verified install paths, a two-command quick start, one screenshot near the top, and progressive detail for fleet identity, automation, connection behavior, and development. The old README was 119 lines.

Moved and corrected

• Moved the full cross-platform command matrix, macOS acknowledgement exit codes, Darwin notifications, URL actions, and direct-install CLI linking to docs/cli.md.
• Moved macOS settings, fleet precedence, remote-session heuristics, platform-specific configuration pointers, and update behavior to docs/configuration.md.
• Kept the screenshot, cross-platform install channels, agent skill, credits, and license.
• Dropped no current factual content. Tightened two broad claims from the old README: location is macOS-only rather than a shared fleet field, and --wait, settings, and dismiss are macOS-only rather than common CLI behavior. No changelog entry was added because the changelog has no README-only documentation precedent.

Verification

• swift build — passed.
• swift test — 62 tests passed.
• APP_IDENTITY="-" ./Scripts/package_app.sh debug — built and packaged the app.
• open -a Nameplate and nameplate splash — exact quick start passed against the installed Developer ID-signed app.
• Temporary Swift Testing sample using the README fleet JSON — compiled and passed; scratch file removed.
• cargo test -p nameplate-core --manifest-path linux/Cargo.toml — 9 Linux core tests passed.
• Windows release assets and .NET 8 target were checked against the latest GitHub release, project files, and CLI source. The Windows app was not built because the host has no .NET SDK and WPF requires Windows.
• Interactive attention flags were checked against real nameplate --help output and all three CLI implementations rather than presenting a live alert.
• Every relative link resolves. Every external link and badge returned HTTP 200; badge SVGs contain no invalid or not found state.
• Autoreview (Codex, high reasoning) ran twice; the final run reported no accepted/actionable findings.

[clawsweeper]

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

ClawSweeper review

What this changes

Rewrites the README as a concise product entry point and adds CLI and configuration reference pages for platform-specific details.

Merge readiness

⚠️ Ready for maintainer review - 1 item remains

This owner-authored, documentation-only PR is coherent, factually aligned with the current implementation, and has no actionable patch defect. It should remain open for ordinary maintainer review rather than automated cleanup or repair.

Priority: P3
Reviewed head: 992fa5a30f44e76a3b92576be676abd88f2bd6c0

Review scores

Measure	Result	What it means
Overall readiness	🦞 diamond lobster (5/6)	A focused, well-supported documentation reorganization with no actionable correctness or security concern found.
Proof confidence	🌊 off-meta tidepool	Not applicable: This owner-authored documentation-only change is verified through source, platform-guide, and link-target review rather than external runtime proof.
Patch quality	🦞 diamond lobster (5/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This owner-authored documentation-only change is verified through source, platform-guide, and link-target review rather than external runtime proof.
Evidence reviewed	5 items	Documentation-only scope: The branch changes one README and adds two Markdown reference pages; it does not change application code, dependencies, release scripts, or workflows. CLI claims match implementation: The macOS CLI exposes attention, splash, settings, dismiss, wait, timeout, and the documented acknowledgement exit outcomes; the new reference page correctly marks the extra lifecycle commands as macOS-only. Cross-platform documentation matches maintained guides: The proposed Linux and Windows guidance agrees with the existing platform documentation: Linux uses optional layer-shell support and Windows uses the same executable for tray and CLI behavior.
Findings	None	None.
Security	None	None.

How this fits together

Nameplate is a cross-platform menu-bar or tray utility that derives a machine identity from local and fleet settings, then displays overlays, splashes, and attention prompts. The README and reference docs are the entry path from installation into platform-specific CLI and configuration behavior.

flowchart LR
  Install[Install channel] --> App[Nameplate app]
  Fleet[Fleet and local settings] --> Identity[Machine identity]
  Identity --> Overlays[Desktop overlays]
  CLI[CLI commands] --> App
  App --> Attention[Attention and splash output]
  Docs[README and reference docs] --> Install

Loading

Before merge

• Complete next step (P2) - This owner-authored documentation PR has no mechanical repair to queue; the remaining action is ordinary maintainer review.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Documentation surface	3 files affected: 2 added, 1 changed	The change is contained to the README and two reference pages, with no runtime or packaging surface modified.
Content reshaping	161 added, 74 removed	The branch materially reorganizes user guidance while reducing the README from 119 to 95 lines.

Technical review

Best possible solution:

Land the concise README and keep the detailed platform-specific CLI and configuration contract in the new reference pages, with future behavior changes updating the corresponding platform guide and reference page together.

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

Not applicable: this PR changes documentation rather than reporting a runtime failure. The moved CLI, fleet, and remote-viewing claims can be checked directly against current implementation and existing platform guides.

Is this the best way to solve the issue?

Yes. A short README with dedicated CLI and configuration references is the narrowest maintainable way to preserve the product front door while keeping platform-specific behavior discoverable.

AGENTS.md: found and applied where relevant.

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

Labels

Label changes:

• add rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🌊 off-meta tidepool and patch quality is 🦞 diamond lobster.
• remove rating: 🐚 platinum hermit: Current PR rating is rating: 🦞 diamond lobster, so this older rating label is no longer current.

Label justifications:

• P3: This is a low-risk documentation and onboarding improvement with no reported runtime regression.
• rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🌊 off-meta tidepool and patch quality is 🦞 diamond lobster.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: This owner-authored documentation-only change is verified through source, platform-guide, and link-target review rather than external runtime proof.

Evidence

What I checked:

• Documentation-only scope: The branch changes one README and adds two Markdown reference pages; it does not change application code, dependencies, release scripts, or workflows. (README.md:1, 992fa5a30f44)
• CLI claims match implementation: The macOS CLI exposes attention, splash, settings, dismiss, wait, timeout, and the documented acknowledgement exit outcomes; the new reference page correctly marks the extra lifecycle commands as macOS-only. (Sources/NameplateCLI/main.swift:25, 611446994d98)
• Cross-platform documentation matches maintained guides: The proposed Linux and Windows guidance agrees with the existing platform documentation: Linux uses optional layer-shell support and Windows uses the same executable for tray and CLI behavior. (linux/README.md:47, 611446994d98)
• Fleet and remote-viewing claims match source: Current source defines the fleet-file default and macOS-only location data, and recognizes Screen Sharing/VNC plus TeamViewer and AnyDesk for remote-viewing heuristics. (Sources/NameplateCore/RemoteViewing.swift:32, 611446994d98)
• Feature-history ownership: The current documentation and the central CLI, cross-platform, and release behavior predominantly date to Peter Steinberger's commits, including the v0.3.1 documentation update and the Windows/Linux parity work. (README.md:1, ae654d5495e0)

Likely related people:

• steipete: Peter Steinberger authored the current README baseline, the v0.3.1 documentation update, the cross-platform parity work, and this documentation branch. (role: feature and documentation owner; confidence: high; commits: ae654d5495e0, 045377e2b147, 992fa5a30f44; files: README.md, linux/README.md, windows/README.md)
• Matt Van Horn: The macOS attention wait and acknowledgement behavior documented in the new CLI reference originated in the focused attention-wait feature commit. (role: introduced acknowledgement semantics; confidence: medium; commits: fe5c1f1dabdb; files: Sources/NameplateCLI/main.swift)

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.

History

Review history (1 earlier review cycle)

• reviewed 2026-08-03T01:35:55.546Z sha 992fa5a :: needs maintainer review before merge. :: none