docs: cross-platform prerequisites and preflight checklist

[jonathanMLDev]

This PR documents how to install and verify Python, Docker, act (including act-cli on Windows), and mikefarah/yq across Linux, macOS (Intel and Apple silicon), and Windows with Docker Desktop / WSL2. It adds Docker runtime notes (socket vs named pipe, --platform, WSL2 bind mounts), a short preflight checklist users can run before their first localci run, and guidance on lowering parallelism when Docker Desktop + WSL2 is under stress.

The root README gets a brief “host platforms” note linking to the Usage Guide; the Design Guide §F links to the same section for install paths and checks. A small comment was added near effective_parallel in localci run pointing readers to the Usage Guide for Windows/WSL2 parallelism.

close #32

Summary by CodeRabbit

• Documentation
  • Added "Host platforms" section clarifying Linux-container-first design and Docker Desktop usage on macOS/Windows
  • Expanded prerequisites documentation with detailed cross-platform installation guidance for required tools
  • Added preflight checklist with version verification and smoke-test commands
  • Included Docker runtime differences and WSL2 backend recommendations for Windows users
  • Improved documentation cross-references for easier navigation

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR consolidates cross-platform prerequisite documentation by expanding the User Guide with per-OS installation guidance, Docker runtime differences, and a preflight checklist. It updates the README with a host platforms section, adds supporting comments in the CLI code, and cross-links the Design Guide.

Changes

Cross-platform Prerequisites Documentation

Layer / File(s)	Summary
README Host Platforms Introduction README.md	Adds "Host platforms" section explaining Linux-container-first architecture and how Docker Desktop + WSL2 provide Linux execution on macOS and Windows.
Usage Guide Installation Structure cli/Usage Guide.md	Updates Table of Contents with entries for cross-platform prerequisites, Docker runtime differences, preflight checklist, and Windows/WSL2/parallelism.
Prerequisites Table and Core Guidance cli/Usage Guide.md	Expands prerequisites table with explicit platform/tool guidance (Docker, mikefarah/yq v4+, act) and adds cross-platform prerequisites section covering per-OS installation and environment-mixing warnings.
Docker Runtime Differences cli/Usage Guide.md	Documents Docker socket paths, arm64 architecture handling with --platform flag, and WSL2-specific mount and performance considerations.
Preflight Checklist and Verification cli/Usage Guide.md	Adds checklist with concrete commands to verify tool versions, connectivity, and workflow parse-only smoke test.
Parallelism and Performance Guidance cli/Usage Guide.md, cli/localci/cli/run.py	Explains ThreadPoolExecutor parallel execution, resource contention under Docker Desktop + WSL2, and configuration knobs (max_jobs, --parallel flag). Adds supporting comment in run.py.
Documentation Cross-references docs/Design Guide.md	Points readers to Usage Guide's cross-platform prerequisites section, consolidating host compatibility guidance.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• cppalliance/local-ci-test-system#35: Updates documentation to clarify the required mikefarah/yq v4+ YAML tooling dependency.

Suggested reviewers

• wpak-ai
• bradjin8

Poem

📚 Cross-platform paths now clear and bright,
From Linux hosts to Docker's might,
WSL2 dances, preflight checks guide,
No more guessing—docs provide! 🐰✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the main change—adding cross-platform prerequisites and preflight checklist documentation across multiple files.
Linked Issues check	✅ Passed	All primary coding/documentation objectives from #32 are met: cross-platform install docs added, Docker runtime differences documented, preflight checklist provided, and Windows limitations surfaced.
Out of Scope Changes check	✅ Passed	All changes directly support issue #32 requirements; no unrelated modifications or scope creep detected in the documentation and code comment updates.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[wpak-ai]

@coderabbitai resume

[coderabbitai]

✅ Actions performed

Reviews resumed.

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

cli/Usage Guide.md (1)

100-108: 💤 Low value

Consider suppressing error output in the act version check.

The command act --version || act-cli --version will display an error message from the first command if it fails before trying the second. For a cleaner preflight experience, consider redirecting stderr:

act --version 2>/dev/null || act-cli --version

However, this is a minor usability refinement; the current version is functional.

🤖 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 `@cli/Usage` Guide.md around lines 100 - 108, The act version check command
(`act --version || act-cli --version`) can emit an error message from the first
invocation before falling back; update that line to suppress stderr from `act
--version` (redirect stderr to /dev/null) so the fallback `act-cli --version`
runs cleanly and the preflight output is not cluttered by the first command's
error.

🤖 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 `@cli/Usage` Guide.md:
- Line 77: Update the heading text "#### macOS (Intel and Apple silicon)" to use
correct proper noun capitalization by changing "Apple silicon" to "Apple
Silicon" so the heading reads "#### macOS (Intel and Apple Silicon)"; ensure any
other occurrences of "Apple silicon" in the same file are similarly capitalized.
- Line 81: Summary: The proper noun "Apple silicon" is incorrectly capitalized;
change it to "Apple Silicon". Locate the Markdown line starting with "**Apple
silicon (arm64):**" and update the phrase to "**Apple Silicon (arm64):**"
ensuring the rest of the sentence remains unchanged (including the code example
and parenthetical architecture note).

---

Nitpick comments:
In `@cli/Usage` Guide.md:
- Around line 100-108: The act version check command (`act --version || act-cli
--version`) can emit an error message from the first invocation before falling
back; update that line to suppress stderr from `act --version` (redirect stderr
to /dev/null) so the fallback `act-cli --version` runs cleanly and the preflight
output is not cluttered by the first command's error.

🪄 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: defaults

Review profile: CHILL

Plan: Pro

Run ID: eb1c4597-4012-4d0f-833d-2415a2fb8678

📥 Commits

Reviewing files that changed from the base of the PR and between 2bfe042 and 4b145ad.

📒 Files selected for processing (4)

• README.md
• cli/Usage Guide.md
• cli/localci/cli/run.py
• docs/Design Guide.md