docs(contributing): fix Windows desktop setup

[NgoQuocViet2001]

Summary

• Align the documented Rust toolchain with rust-toolchain.toml (1.96.1).
• Add Ninja to the native Windows prerequisite, install-order, and verification steps.
• Route native Windows contributors through the repository's dev:app:win bootstrap instead of the macOS-only dev:app script.
• Document the synchronized OPENHUMAN_DEV_PORT override and the /utf-8 MSVC workaround for non-UTF-8 code pages.

Problem

A fresh Windows contributor following CONTRIBUTING.md is told to install a stale Rust toolchain and use a macOS-specific desktop command. The guide also omits Ninja, the supported workaround for reserved port 1420, and the MSVC UTF-8 workaround described in #5034.

Solution

Update the guide against the current source-of-truth files rather than duplicating a lower-level Tauri command. The existing pnpm dev:app:win path already configures MSVC, Ninja, CEF, and applies OPENHUMAN_DEV_PORT to both Vite and Tauri, so the documentation now directs contributors to that maintained entrypoint.

Submission Checklist

If a section does not apply to this change, mark the item as N/A with a one-line reason. Do not delete items.

• N/A — docs-only change; no runtime behavior or testable production path changed.
• N/A — no executable lines changed, so diff coverage does not apply.
• N/A — no feature was added, removed, or renamed.
• N/A — no affected feature IDs for a contributor-guide correction.
• No new external network dependencies introduced.
• N/A — contributor setup documentation is not a release-cut surface.
• Linked issue is closed via Closes #5034 below.

Impact

Documentation only. No desktop, mobile, web, CLI, performance, security, migration, or runtime compatibility behavior changes.

Related

• Closes CONTRIBUTING: Windows contributor setup is incomplete and pins a stale Rust version #5034
• Follow-up PR(s)/TODOs: N/A

---

AI Authored PR Metadata (required for Codex/Linear PRs)

Keep this section for AI-authored PRs. For human-only PRs, mark each field N/A.

Linear Issue

• Key: N/A
• URL: N/A

Commit & Branch

• Branch: docs/5034-windows-contributor-setup
• Commit SHA: 567ded7bf0afeb5fb25d5edc1557be4618616f60

Validation Run

• pnpm --filter openhuman-app format:check — blocked locally; see below.
• pnpm typecheck — N/A: docs-only change.
• Focused tests: pnpm docs:check; source-of-truth assertions for Rust version, Windows script, Ninja package ID, and port override; local-link check; git diff --check.
• Rust fmt/check (if changed): N/A — no Rust changed.
• Tauri fmt/check (if changed): N/A — no Tauri source or config changed.

Validation Blocked

• command: CI=true pnpm --filter openhuman-app format:check
• error: local run exceeded 60 seconds while checking the unchanged app tree; this environment also has no cargo/rustc on PATH for the command's Rust formatting phase
• impact: none on the changed file; generated-doc, source-truth, local-link, and whitespace checks pass for CONTRIBUTING.md

Behavior Changes

• Intended behavior change: Windows contributors receive commands that match the repository's current toolchain and platform bootstrap.
• User-visible effect: the documented native Windows setup no longer sends contributors through stale or macOS-only steps.

Parity Contract

• Legacy behavior preserved: N/A — documentation only.
• Guard/fallback/dispatch parity checks: the documented port behavior was verified against scripts/run-dev-win.sh and the root/app package scripts.

Duplicate / Superseded PR Handling

• Duplicate PR(s): None found in the open PR search immediately before submission.
• Canonical PR: This PR.
• Resolution (closed/superseded/updated): N/A.

Summary by CodeRabbit

• Documentation
  • Updated development setup instructions to pin Rust toolchain to 1.96.1.
  • Expanded Windows installation and setup guidance for Rust, LLVM/Clang, CMake, and Ninja (including clearer step-by-step commands).
  • Added Windows dependency verification (e.g., Ninja version check).
  • Documented native Windows development entrypoints and improved troubleshooting for port selection and non-UTF-8 build failures.
  • Updated macOS setup and platform guidance to align with the 1.96.1 toolchain.

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Repo admins can enable using credits for code reviews in their settings.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: e2b3cfbd-cb2f-4e21-88e1-c1a81c2fd780

📥 Commits

Reviewing files that changed from the base of the PR and between 567ded7 and 4e1f5b2.

📒 Files selected for processing (1)

• CONTRIBUTING.md

🚧 Files skipped from review as they are similar to previous changes (1)

• CONTRIBUTING.md

---

📝 Walkthrough

Walkthrough

CONTRIBUTING.md now documents Rust 1.96.1, complete Windows dependency installation including Ninja, native Windows desktop development commands, and troubleshooting for port conflicts and non-UTF-8 code pages.

Changes

Contributor setup documentation

Layer / File(s)	Summary
Toolchain and dependency setup CONTRIBUTING.md	Prerequisites and bootstrap instructions use Rust 1.96.1; Windows setup adds ordered Rust, LLVM/Clang, CMake, Ninja, and Node.js/pnpm steps, with updated verification commands.
Desktop development and troubleshooting CONTRIBUTING.md	Desktop instructions include macOS and native Windows entrypoints, plus guidance for OPENHUMAN_DEV_PORT conflicts and CL=/utf-8 codepage issues.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Poem

I’m a rabbit with setup notes neat,
Rust and Ninja hop in step complete.
Windows paths now clearly shown,
Ports and codepages no longer unknown.
🐇 Builds can bloom from carrot to code!

🚥 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 clearly matches the docs-only Windows setup fixes in CONTRIBUTING.md.
Linked Issues check	✅ Passed	The PR addresses the linked issue by updating Rust 1.96.1, adding Ninja, documenting the Windows entrypoint, port override, and CL=/utf-8 workaround.
Out of Scope Changes check	✅ Passed	The changes stay within Windows contributor setup documentation and related guidance, with no unrelated runtime or feature work.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

---

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.}

[coderabbitai]

Actionable comments posted: 2

🤖 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 `@CONTRIBUTING.md`:
- Around line 219-223: Update the dev:app:win port guidance around
OPENHUMAN_DEV_PORT to require checking both the configured port and its derived
HMR port (OPENHUMAN_DEV_PORT + 1) for availability and exclusion from listed
ranges. Ensure the guidance also prevents selecting 65535 as the base port,
since the companion HMR port must remain valid.
- Around line 69-71: Update the LIBCLANG_PATH example in the contributing
documentation to use executable PowerShell syntax: assign the quoted path
through the $env:LIBCLANG_PATH environment-variable form and label the code
block as powershell.

🪄 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: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: e4ba2390-0996-4b31-be5f-a1863d5414ba

📥 Commits

Reviewing files that changed from the base of the PR and between 49b5bb7 and 567ded7.

📒 Files selected for processing (1)

• CONTRIBUTING.md

[greptile-apps]

Greptile Summary

This docs-only PR fixes the Windows contributor setup section in CONTRIBUTING.md by aligning the documented Rust toolchain (1.96.1) with rust-toolchain.toml, adding Ninja as a required Windows prerequisite, and directing native Windows contributors to pnpm dev:app:win instead of the macOS-specific dev:app entrypoint. It also documents the OPENHUMAN_DEV_PORT port-conflict workaround and the /utf-8 MSVC encoding fix for non-UTF-8 code pages.

• Rust version corrected: 1.93.0 → 1.96.1, verified against rust-toolchain.toml (pinned for rusqlite 0.40 / cfg_select!).
• Ninja added to Windows setup: matches run-dev-win.sh which requires find_ninja and sets CMAKE_GENERATOR=Ninja and CMAKE_MAKE_PROGRAM.
• Windows dev command updated: pnpm dev:app:win exists in both the root and app/package.json, and the referenced bootstrap script handles MSVC, CEF staging, and the OPENHUMAN_DEV_PORT → Tauri devUrl synchronization; app/vite.config.ts reads the same variable, confirming the "synchronized" claim.

Confidence Score: 5/5

Documentation-only change; no production code, scripts, or configuration files were modified.

Every factual claim in the updated guide was verified against the source-of-truth files: the Rust version matches rust-toolchain.toml, pnpm dev:app:win resolves correctly through both package.json files, run-dev-win.sh confirms Ninja is required and OPENHUMAN_DEV_PORT is applied to both Vite and Tauri, and vite.config.ts reads the same port variable. No executable lines were touched.

No files require special attention.

Important Files Changed

Filename	Overview
CONTRIBUTING.md	Docs-only update; all factual claims verified against rust-toolchain.toml, package.json, and scripts/run-dev-win.sh — Rust version, Ninja requirement, dev:app:win command, and OPENHUMAN_DEV_PORT behavior are all accurate.

_{Reviews (1): Last reviewed commit: "fix(docs): use PowerShell syntax for LIB..." | Re-trigger Greptile}