docs: rewrite README to house standard

[steipete]

Summary

Rewrites the README to the shared house structure: a one-line pitch, dynamic flat-square badges, the smallest working install path, a short quick start, progressive workflow links, development, and license. The README is 103 lines, down from 445, while keeping the existing banner and the read/watch/send proof near the top.

Content movement

• Moved the exhaustive injected-bridge CLI examples and IPC layout to docs/bridge.md; the docs-site build publishes it as bridge.html.
• Replaced duplicated command lists, JSON schemas, permissions troubleshooting, watch internals, and Linux setup with links to their existing canonical pages under docs/ / imsg.sh.
• Dropped no factual feature content as obsolete or unverifiable. No community, credit, or image content was removed.
• Added the customary one-line Unreleased documentation entry to CHANGELOG.md.

Verification

• make build — passed; built the universal arm64/x86_64 CLI and arm64e/arm64/x86_64 helper.
• make lint — passed with 12 existing non-serious SwiftLint warnings.
• make test — passed, 510 tests across 5 suites.
• make docs-site — passed; generated dist/docs-site/bridge.html.
• Scratch IMsgCore import/sample — passed swiftc -typecheck, then removed.
• Built CLI --version, generated help, and completions llm — passed; all README and bridge flags were checked against the generated command source of truth.
• Quick-start live read — attempted with the built binary, but this agent process lacks Full Disk Access and returned authorization denied (code: 23). The exact chats and history flags were therefore validated against the built binary's help, as allowed for permission-gated commands. Live watch, send, RPC, and injected-bridge examples were likewise help-validated because running them would require a live service, mutate Messages, or disable SIP.
• Links — all 19 relative targets resolve; every external and badge URL returned HTTP 200; badge SVGs contain no invalid or not found card.
• /Users/steipete/Projects/agent-skills/skills/autoreview/scripts/autoreview --mode local — clean, no accepted/actionable findings.

[clawsweeper]

Codex review: needs changes before merge. Reviewed August 2, 2026, 8:46 PM ET / August 3, 2026, 00:46 UTC.

ClawSweeper review

What this changes

The branch turns the README into a concise install-and-workflow entry point, moves optional injected-bridge command reference material to docs/bridge.md, and adds an unreleased documentation changelog entry.

Merge readiness

⚠️ Ready for maintainer review - 2 items remain

This focused documentation PR should remain open because it is authored by a repository collaborator. The README and bridge-reference split is coherent and aligns with current command surfaces, but the contributor-authored unreleased changelog entry should be removed before merge because release notes are release-owned.

Priority: P3
Reviewed head: 8483a0d1e04daa90cdf8a1c0c8e6cfb974032e85

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	The documentation reorganization is focused and well-validated in the PR body, with one release-process correction needed before merge.
Proof confidence	🌊 off-meta tidepool	Not applicable: This collaborator-authored documentation change includes stated CLI-help and link validation; no external contributor real-behavior-proof gate applies.
Patch quality	🐚 platinum hermit (4/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This collaborator-authored documentation change includes stated CLI-help and link validation; no external contributor real-behavior-proof gate applies.
Evidence reviewed	6 items	Repository guidance: The full repository guidance requires focused changes and validation evidence. This PR is limited to documentation and its body reports build, lint, test, docs-site, link, and CLI-help validation. Focused documentation change: The proposed commit changes three documentation files only, with 217 additions and 395 deletions; it does not alter source code, dependencies, workflows, or generated artifacts. Documentation links resolve: All relative Markdown targets found in the proposed README and bridge page exist in the PR tree, including the new advanced-bridge reference path.
Findings	1 actionable finding	[P2] Leave the changelog to the release process
Security	None	None.

How this fits together

The README is the public entry point for the macOS Messages CLI. It guides users from installation and normal database/AppleScript workflows to canonical documentation, including the SIP-disabled IMCore bridge used for advanced Messages controls.

flowchart LR
  Visitor[CLI user] --> FrontDoor[README quick start]
  FrontDoor --> Standard[Read and send workflows]
  FrontDoor --> FullDocs[Canonical documentation]
  FullDocs --> Bridge[Optional IMCore bridge reference]
  Bridge --> Advanced[Advanced Messages controls]

Loading

Before merge

• Leave the changelog to the release process (P2) - Remove this contributor-authored unreleased entry. The release-note policy keeps CHANGELOG.md release-owned, so documenting this README reshaping here creates a parallel release-note decision outside that process.
• Resolve merge risk (P1) - Keeping the unreleased CHANGELOG.md entry would bypass the release-owned changelog process and create a parallel release-note decision in a normal documentation PR.

Findings

• [P2] Leave the changelog to the release process — CHANGELOG.md:5-6

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Documentation surface	3 files affected; 217 added, 395 removed	The branch substantially restructures public documentation without changing runtime code.
Reference relocation	1 new bridge reference page; README reduced from 445 to 103 stated lines	Review should ensure advanced IMCore guidance remains discoverable through the new canonical page.

Merge-risk options

Maintainer options:

1. Decide the mitigation before merge
   Merge the concise README-to-canonical-docs split and bridge reference after removing the contributor-authored CHANGELOG.md entry; let the release process decide whether and how this documentation update is recorded.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Technical review

Best possible solution:

Merge the concise README-to-canonical-docs split and bridge reference after removing the contributor-authored CHANGELOG.md entry; let the release process decide whether and how this documentation update is recorded.

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

Not applicable: this PR changes documentation, so the relevant verification is CLI-help, documentation-link, and generated-docs validation rather than runtime bug reproduction.

Is this the best way to solve the issue?

No: the README and bridge-reference split is maintainable, but normal PRs should not add the release-owned CHANGELOG.md entry.

Full review comments:

• [P2] Leave the changelog to the release process — CHANGELOG.md:5-6
  Remove this contributor-authored unreleased entry. The release-note policy keeps CHANGELOG.md release-owned, so documenting this README reshaping here creates a parallel release-note decision outside that process.
  Confidence: 0.93

Overall correctness: patch is incorrect
Overall confidence: 0.93

AGENTS.md: found and applied where relevant.

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

Labels

Label changes:

• add P3: This is a low-risk documentation and discoverability improvement without a runtime behavior change.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: This collaborator-authored documentation change includes stated CLI-help and link validation; no external contributor real-behavior-proof gate applies.

Label justifications:

• P3: This is a low-risk documentation and discoverability improvement without a runtime behavior change.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: This collaborator-authored documentation change includes stated CLI-help and link validation; no external contributor real-behavior-proof gate applies.

Evidence

Acceptance criteria:

• [P1] git diff --check.
• [P1] Inspect Markdown link targets in README.md and docs/bridge.md.

What I checked:

• Repository guidance: The full repository guidance requires focused changes and validation evidence. This PR is limited to documentation and its body reports build, lint, test, docs-site, link, and CLI-help validation. (AGENTS.md:1, 4605e7ce16ea)
• Focused documentation change: The proposed commit changes three documentation files only, with 217 additions and 395 deletions; it does not alter source code, dependencies, workflows, or generated artifacts. (README.md:1, 8483a0d1e04d)
• Documentation links resolve: All relative Markdown targets found in the proposed README and bridge page exist in the PR tree, including the new advanced-bridge reference path. (docs/bridge.md:1, 8483a0d1e04d)
• Bridge reference matches current command surface: Current main declares the send-rich bridge command and its documented --chat, text, reply, attachment, and URL examples, supporting the new separation from normal README workflows. (Sources/imsg/Commands/BridgeMessagingCommands.swift:89, 4605e7ce16ea)
• Recent ownership history: README history identifies Peter Steinberger's release preparation commit and Vincent Koc's recent RPC documentation update as the most relevant current-main provenance. (README.md:1, e9580a332432)
• Release-note change: The branch adds a documentation entry under the unreleased changelog section; normal OpenClaw PR review keeps this release-owned file outside contributor changes. (CHANGELOG.md:5, 8483a0d1e04d)

Likely related people:

• steipete: The current PR is authored by steipete, and current-main release preparation for the README history is authored by Peter Steinberger, corresponding to this repository collaborator's established documentation and release context. (role: recent release and documentation contributor; confidence: high; commits: 1d8b679cc3a3, 8483a0d1e04d; files: README.md, CHANGELOG.md, docs/bridge.md)
• Vincent Koc: Vincent Koc's current-main RPC pagination change is the most recent documented feature update touching the README history and adjacent RPC documentation. (role: recent adjacent documentation contributor; confidence: medium; commits: e9580a332432; files: README.md, docs/rpc.md)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Remove the unreleased CHANGELOG.md entry and retain the README and bridge-reference changes.

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.