Skip to content

docs: simplify macOS app overview#97120

Merged
RomneyDa merged 3 commits into
mainfrom
macos-app-docs
Jun 27, 2026
Merged

docs: simplify macOS app overview#97120
RomneyDa merged 3 commits into
mainfrom
macos-app-docs

Conversation

@RomneyDa

@RomneyDa RomneyDa commented Jun 26, 2026

Copy link
Copy Markdown
Member

What Problem This Solves

The macOS platform overview was acting like a second runtime reference: it repeated launchd, IPC, exec approvals, deep links, remote tunnel, and dev details that already live under the narrower macOS pages. It also did not give readers an obvious path to download the macOS app from OpenClaw releases.

Why This Change Was Made

This rewrites docs/platforms/macos.md as a short overview/router page. It adds a prominent download section that points to OpenClaw GitHub Releases and tells readers to look for OpenClaw-<version>.dmg or .zip assets when a release includes macOS builds. Detailed launchd, remote, permissions, Canvas, IPC, logging, and exec approval content remains linked from the child pages instead of duplicated on the overview.

User Impact

macOS readers get a clearer first stop: what the app is for, where to download it, how to start, how to choose local vs remote Gateway mode, and which detail page to open next. The published /platforms/macos route stays in place.

AI-assisted docs PR.

Evidence

  • pnpm docs:list
  • pnpm format:docs:check
  • pnpm lint:docs
  • pnpm docs:check-mdx
  • pnpm docs:check-links
  • pnpm docs:check-i18n-glossary
  • git diff --check
  • Release asset spot-check with gh release view/list showed macOS assets exist on some releases (OpenClaw-<version>.dmg / .zip) but not every latest release, so the docs avoid hardcoding one versioned download URL.

@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation app: macos App: macos size: XS maintainer Maintainer-authored PR labels Jun 26, 2026
@clawsweeper

clawsweeper Bot commented Jun 26, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Codex review: needs maintainer review before merge. Reviewed June 26, 2026, 10:19 PM ET / 02:19 UTC.

Summary
The PR rewrites the macOS app overview into a concise install/router page and moves detailed state, debug, Canvas, remote, and IPC notes into macOS child docs.

PR surface: Docs -95. Total -95 across 5 files.

Reproducibility: not applicable. This PR changes documentation only and does not report a runtime bug. The prior docs accuracy concerns are source-checkable and appear resolved on the latest head.

Review metrics: none identified.

Stored data model
Persistent data-model change detected: migration/backfill/repair: docs/platforms/mac/bundled-gateway.md. Confirm migration or upgrade compatibility proof before merge.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🌊 off-meta tidepool
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • Wait for the live check-docs job on the current head to complete successfully before merging.

Risk before merge

  • [P1] The live check-docs job was still in progress when queried; maintainers should wait for it to finish successfully before merging.

Maintainer options:

  1. Decide the mitigation before merge
    Keep the overview/router rewrite open for maintainer review and merge it after the current docs check completes successfully, since the relocated operational claims are source-backed on the latest head.
  2. Pause or close
    Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

  • The PR is maintainer-labeled and source-backed, with the only remaining action being ordinary maintainer review plus completion of the pending docs check.

Security
Cleared: The diff only changes Markdown under docs/ and introduces no code execution, dependency, workflow, package, credential, or secret-handling surface.

Review details

Best possible solution:

Keep the overview/router rewrite open for maintainer review and merge it after the current docs check completes successfully, since the relocated operational claims are source-backed on the latest head.

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

Not applicable: this PR changes documentation only and does not report a runtime bug. The prior docs accuracy concerns are source-checkable and appear resolved on the latest head.

Is this the best way to solve the issue?

Yes: making docs/platforms/macos.md a short overview/router is the maintainable docs shape, while child pages carry the detailed operational material. The checked claims now match current macOS source and doctor behavior.

AGENTS.md: found and applied where relevant.

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

Label changes

Label justifications:

  • P3: This is a bounded macOS documentation cleanup with no runtime behavior change.
  • 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: Real behavior proof is not required because this PR only changes files under docs/.
Evidence reviewed

PR surface:

Docs -95. Total -95 across 5 files.

View PR surface stats
Area Files Added Removed Net
Source 0 0 0 0
Tests 0 0 0 0
Docs 5 121 216 -95
Config 0 0 0 0
Generated 0 0 0 0
Other 0 0 0 0
Total 5 121 216 -95

What I checked:

Likely related people:

  • steipete: Recent source and docs history ties this handle to the macOS debug CLI, deep-link hardening, and remote transport behavior the PR documents. (role: recent area contributor; confidence: high; commits: 4999f15688b1, 28d9dd7a7725, 6375ee836fef; files: apps/macos/Sources/OpenClawMacCLI/DiscoverCommand.swift, apps/macos/Sources/OpenClaw/DeepLinks.swift, docs/platforms/mac/remote.md)
  • vincentkoc: Recent docs history ties this handle to docs navigation/sidebar and macOS MagicDNS discovery documentation adjacent to this overview rewrite. (role: docs IA contributor; confidence: medium; commits: 5c9408d3ca25, 93f2da84261c, aa69b12d0086; files: docs/docs.json, docs/platforms/macos.md)
  • RomneyDa: Beyond authoring this PR, recent merged history shows adjacent macOS release documentation work by this handle. (role: recent adjacent docs contributor; confidence: medium; commits: bdd365a34882; files: docs/reference/RELEASING.md, docs/platforms/macos.md)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

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.

How this review workflow works
  • 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.

@clawsweeper clawsweeper Bot added rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. P3 Low-priority cleanup, docs, polish, ergonomics, or speculative work. labels Jun 26, 2026
@clawsweeper clawsweeper Bot added rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. and removed rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. labels Jun 26, 2026
@clawsweeper clawsweeper Bot added rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. and removed rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. labels Jun 27, 2026
@RomneyDa
RomneyDa merged commit 7bbd090 into main Jun 27, 2026
57 of 62 checks passed
@RomneyDa
RomneyDa deleted the macos-app-docs branch June 27, 2026 23:04
@Haderach-Ram Haderach-Ram mentioned this pull request Jun 28, 2026
Open
@github-actions github-actions Bot mentioned this pull request Jun 28, 2026
Open
github-actions Bot pushed a commit to Desicool/openclaw that referenced this pull request Jun 28, 2026
@RomneyDa
docs: simplify macOS app overview (openclaw#97120)
6ec484c 
* docs: simplify macOS app docs

* docs: preserve macOS app detail links

* docs: address macOS review feedback
QiuYuang pushed a commit to QiuYuang/openclaw that referenced this pull request Jul 1, 2026
@RomneyDa @QiuYuang
docs: simplify macOS app overview (openclaw#97120)
6cf1866 
* docs: simplify macOS app docs

* docs: preserve macOS app detail links

* docs: address macOS review feedback
chenyangjun-xy pushed a commit to chenyangjun-xy/openclaw that referenced this pull request Jul 1, 2026
@RomneyDa
docs: simplify macOS app overview (openclaw#97120)
9b56358 
* docs: simplify macOS app docs

* docs: preserve macOS app detail links

* docs: address macOS review feedback
chenyangjun-xy pushed a commit to chenyangjun-xy/openclaw that referenced this pull request Jul 3, 2026
@RomneyDa @chenyangjun-xy
docs: simplify macOS app overview (openclaw#97120)
00d5978 
* docs: simplify macOS app docs

* docs: preserve macOS app detail links

* docs: address macOS review feedback
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

app: macos App: macos docs Improvements or additions to documentation maintainer Maintainer-authored PR P3 Low-priority cleanup, docs, polish, ergonomics, or speculative work. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. size: XS status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@RomneyDa