docs(get-started): add macOS preparation page#3241
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThis PR adds a dedicated macOS preparation guide and a conditional "Prepare macOS for NemoClaw" link in the prerequisites page. The new guide covers macOS Ventura+ prerequisites, Xcode Command Line Tools, Docker Desktop or Colima setup, Node.js 22.16+ installation, optional Ollama inference, Quickstart linking, and macOS troubleshooting. ChangesmacOS Preparation Documentation
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 ESLint
ESLint skipped: no ESLint configuration detected in root package.json. To enable, add Comment |
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (4)
docs/get-started/macos-preparation.md (4)
25-27: ⚡ Quick winAdjust page structure to match the docs template.
The intro on Line 25-27 is three sentences (target is one or two), and the page uses
## Next Stepinstead of a bottom## Next Stepssection linking related pages.
As per coding guidelines, "Page starts with a one- or two-sentence introduction." and "A 'Next Steps' section at the bottom links to related pages."Also applies to: 147-152
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/get-started/macos-preparation.md` around lines 25 - 27, Condense the current three-sentence intro at the top (the lines that begin "Complete these steps before following the Quickstart...") into one or two sentences that briefly state the page purpose and who it targets, then replace the bottom "## Next Step" heading with "## Next Steps" and add concise links to related pages (Quickstart, Prepare Windows for NemoClaw, and Linux Quickstart) so readers can navigate; also apply the same intro/Next Steps fixes to the similar block referenced around lines 147-152.
101-103: 💤 Low valueUse active voice in the Colima socket check sentence.
Line 101 says "the Colima socket path is detected," which is passive voice; rewrite in active voice.
As per coding guidelines, "Active voice required. Flag passive constructions."🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/get-started/macos-preparation.md` around lines 101 - 103, Rewrite the passive sentence "the Colima socket path is detected" into active voice; locate the sentence that reads "If `docker info` fails, check that the Colima socket path is detected." and change it to an active phrasing such as "If `docker info` fails, check that your system detects the Colima socket path" or "If `docker info` fails, verify that the Colima socket path is detected by your system" so the statement uses active voice.
110-121: ⚡ Quick winAdd intro sentences under each H3 subsection before command blocks.
Line 110 (
With Homebrew) and Line 116 (With nvm) jump directly into commands; each section should open with a brief introductory sentence.
As per coding guidelines, "Sections use H2 and H3, each starting with an introductory sentence."🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/get-started/macos-preparation.md` around lines 110 - 121, The H3 sections "With Homebrew" and "With nvm" jump straight into command blocks without an introductory sentence; add a single brief sentence under each H3 ("With Homebrew" and "With nvm") that explains what the command does (e.g., installs Node 22 via Homebrew / sets up nvm and installs Node 22) before the fenced code blocks so the sections comply with the guideline that each H2/H3 starts with an introductory sentence.
59-59: ⚡ Quick winAvoid colons in section titles.
Line 59 and Line 74 use title colons (
Option A: ...,Option B: ...), which violates docs title formatting.
As per coding guidelines, "No colons in titles."Also applies to: 74-74
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/get-started/macos-preparation.md` at line 59, Change the two section headings that contain colons ("### Option A: Docker Desktop (Recommended)" and "### Option B: ...") to remove the colon and use an allowed separator (e.g., "### Option A — Docker Desktop (Recommended)" and "### Option B — ..."), updating both heading strings so they comply with the "No colons in titles" guideline.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/get-started/macos-preparation.md`:
- Line 76: Remove the disallowed third-party GitHub link for "Colima" in the
docs/get-started/macos-preparation.md content: replace the markdown link
"[Colima](https://github.com/abcorporeal/colima)" with plain text "Colima" (or
an approved/internal reference) so the repo URL is not included in the Markdown.
---
Nitpick comments:
In `@docs/get-started/macos-preparation.md`:
- Around line 25-27: Condense the current three-sentence intro at the top (the
lines that begin "Complete these steps before following the Quickstart...") into
one or two sentences that briefly state the page purpose and who it targets,
then replace the bottom "## Next Step" heading with "## Next Steps" and add
concise links to related pages (Quickstart, Prepare Windows for NemoClaw, and
Linux Quickstart) so readers can navigate; also apply the same intro/Next Steps
fixes to the similar block referenced around lines 147-152.
- Around line 101-103: Rewrite the passive sentence "the Colima socket path is
detected" into active voice; locate the sentence that reads "If `docker info`
fails, check that the Colima socket path is detected." and change it to an
active phrasing such as "If `docker info` fails, check that your system detects
the Colima socket path" or "If `docker info` fails, verify that the Colima
socket path is detected by your system" so the statement uses active voice.
- Around line 110-121: The H3 sections "With Homebrew" and "With nvm" jump
straight into command blocks without an introductory sentence; add a single
brief sentence under each H3 ("With Homebrew" and "With nvm") that explains what
the command does (e.g., installs Node 22 via Homebrew / sets up nvm and installs
Node 22) before the fenced code blocks so the sections comply with the guideline
that each H2/H3 starts with an introductory sentence.
- Line 59: Change the two section headings that contain colons ("### Option A:
Docker Desktop (Recommended)" and "### Option B: ...") to remove the colon and
use an allowed separator (e.g., "### Option A — Docker Desktop (Recommended)"
and "### Option B — ..."), updating both heading strings so they comply with the
"No colons in titles" guideline.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 076be513-c858-42e9-9f1f-a6ad36609eb6
📒 Files selected for processing (2)
docs/get-started/macos-preparation.mddocs/get-started/prerequisites.md
4699f6a to
8299148
Compare
There was a problem hiding this comment.
🧹 Nitpick comments (1)
docs/get-started/macos-preparation.md (1)
52-52: ⚡ Quick winSplit compound sentence for better diff readability.
Line 52 contains two independent clauses joined by "and". The style guide requires one sentence per line to make diffs more readable. Split this into two lines.
📝 Suggested formatting improvement
-If the tools are already installed, the command prints a message saying so and you can continue to the next step. +If the tools are already installed, the command prints a message saying so. +You can continue to the next step.As per coding guidelines, "One sentence per line in source (makes diffs readable). Flag paragraphs where multiple sentences appear on the same line."
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/get-started/macos-preparation.md` at line 52, The sentence "If the tools are already installed, the command prints a message saying so and you can continue to the next step." contains two independent clauses on one line; split it into two separate sentences and place each sentence on its own line so the first line reads that the command prints a message if tools are installed and the second line advises the reader they can continue to the next step, ensuring one sentence per line for diff readability.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@docs/get-started/macos-preparation.md`:
- Line 52: The sentence "If the tools are already installed, the command prints
a message saying so and you can continue to the next step." contains two
independent clauses on one line; split it into two separate sentences and place
each sentence on its own line so the first line reads that the command prints a
message if tools are installed and the second line advises the reader they can
continue to the next step, ensuring one sentence per line for diff readability.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: eeb7c44f-d51f-4540-b452-358fdeb5c2db
📒 Files selected for processing (2)
docs/get-started/macos-preparation.mddocs/get-started/prerequisites.md
✅ Files skipped from review due to trivial changes (1)
- docs/get-started/prerequisites.md
|
✨ Thanks for submitting this PR that adds a macOS preparation page to the documentation, addressing the issue reported in #3232. This change involves creating a new page with step-by-step guidance for macOS users, covering topics such as installing Xcode Command Line Tools, Docker Desktop, and Node.js. Related open issues: |
8299148 to
750c1d5
Compare
|
Rebased on latest main to resolve the toctree conflict with the Windows preparation page. |
|
Friendly ping — just checking if this is in the review queue. Happy to adjust anything if needed. Thanks! |
Add docs/get-started/macos-preparation.md with end-to-end guidance for macOS users, mirroring the existing Windows preparation page: - Prerequisites (macOS Ventura+, Apple Silicon and Intel) - Install Xcode Command Line Tools - Install a Container Runtime (Docker Desktop or Colima with resource guidance) - Install Node.js (Homebrew or nvm) - Optional: Set Up Local Inference with Ollama - Troubleshooting links to existing macOS-specific sections Update prerequisites.md to add the macOS preparation link and toctree entry alongside the existing Windows entry. Signed-off-by: kagura-agent <kagura.agent.ai@gmail.com>
750c1d5 to
5734fe2
Compare
|
Hi — friendly ping on this PR. Let me know if there's any feedback or changes needed. 🙂 |
There was a problem hiding this comment.
🧹 Nitpick comments (1)
docs/get-started/prerequisites.mdx (1)
38-39: ⚡ Quick winSplit sentences onto separate lines.
Lines 38-39 contain two sentences on the same line. The style guide requires one sentence per line to make diffs readable.
♻️ Proposed fix
-NemoClaw needs Docker access. -On personal Linux development machines, adding your user to the `docker` group is the standard way to run Docker without sudo. +NemoClaw needs Docker access. +On personal Linux development machines, adding your user to the `docker` group is the standard way to run Docker without sudo.As per coding guidelines: "One sentence per line in source (makes diffs readable). Flag paragraphs where multiple sentences appear on the same line."
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/get-started/prerequisites.mdx` around lines 38 - 39, The two-sentence paragraph "NemoClaw needs Docker access. On personal Linux development machines, adding your user to the `docker` group is the standard way to run Docker without sudo." should be split so each sentence is on its own line; update the paragraph in docs/get-started/prerequisites.mdx to place "NemoClaw needs Docker access." on one line and "On personal Linux development machines, adding your user to the `docker` group is the standard way to run Docker without sudo." on the next line to satisfy the one-sentence-per-line guideline.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@docs/get-started/prerequisites.mdx`:
- Around line 38-39: The two-sentence paragraph "NemoClaw needs Docker access.
On personal Linux development machines, adding your user to the `docker` group
is the standard way to run Docker without sudo." should be split so each
sentence is on its own line; update the paragraph in
docs/get-started/prerequisites.mdx to place "NemoClaw needs Docker access." on
one line and "On personal Linux development machines, adding your user to the
`docker` group is the standard way to run Docker without sudo." on the next line
to satisfy the one-sentence-per-line guideline.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 34c6605c-3541-47aa-9e7b-4fb2c2009a77
📒 Files selected for processing (1)
docs/get-started/prerequisites.mdx
|
Thanks for putting this together. I’m going to close this because I don’t think a separate macOS preparation page adds enough value right now. The existing prerequisites page already covers the macOS requirements: Node.js, Docker Desktop or Colima, Xcode Command Line Tools, tested macOS runtime combinations, and the Docker-driver OpenShell gateway path. The Quickstart and local inference docs cover the installer and Ollama flow. This PR mostly expands those prerequisites into install commands and basic checks, which would add another page for us to keep in sync without much new guidance. If we find a specific macOS setup gap, I’d prefer a smaller targeted update to the prerequisites or troubleshooting page. |
Description
Fixes #3232
Problem
Windows users have a dedicated preparation page at
docs/get-started/windows-preparation.mdthat walks through every prerequisite step. macOS has no equivalent page — macOS-specific topics (Xcode CLI Tools, Docker Desktop vs Colima, Homebrew,brew install ollama) are scattered across multiple files or absent entirely.Solution
Add
docs/get-started/macos-preparation.mdwith end-to-end macOS guidance mirroring the Windows page structure:xcode-select --installbrew install ollamaUpdate
prerequisites.mdto add macOS preparation link and toctree entry alongside the existing Windows entry.Testing
#macos-first-run-failures,#colima-socket-not-detected-macos)Changes
docs/get-started/macos-preparation.mddocs/get-started/prerequisites.mdSummary by CodeRabbit