[shailendra-nv]

Summary

Direct readers of main's documentation to the maintained native Windows implementation on windows. This PR is based on main and changes documentation only, keeping Windows implementation and releases on their own branch.

Merge the companion Windows documentation PR #4757 first so links to its new WINDOWS.md resolve.

Related Issue

Closes #4756.

Companion: #4757 targets windows and closes #4755. Related MXC implementation-detail documentation work is in #4646.

The author has verified MAINTAIN access; the issue currently has no state:accepted label.

Changes

• Add a top-level Windows guide and update README, CONTRIBUTING, TESTING, CI, and AGENTS.
• Pin Windows source, build, configuration, and runtime links to windows, including from published docs on main.
• Distinguish native MXC from WSL, main's installer/release artifacts, and older MXC source snapshots retained on main.
• Refresh Windows contributor guidance from the Windows branch, require a Windows-based checkout, and include E2E in both full-validation paths with an exit-code check after every task.
• Preserve main's code and unrelated documentation. All 14 changed files are Markdown/MDX.

Release Notes

Native Windows documentation now identifies windows as its implementation and release branch and explains the current build and runtime limitations.

Testing

• Markdown lint: 161 files, zero errors; repeated by the commit hook. Both changed contributor-skill files also passed direct lint with the repository rules.
• PowerShell validation examples: 96 execution cases across both documents, x64/ARM64 paths, and Windows PowerShell 5.1/PowerShell 7, using a native mock executable to simulate success, failure at every task, and incomplete E2E coverage. Verified that execution stops immediately after each failed task. Thirty-two baseline checks reproduced masked failures; all six PowerShell blocks parsed in both versions.
• Skill YAML metadata, local links, and all 14 referenced Windows tasks checked against the live Windows branch.
• Mermaid validation: 210 files scanned, all diagrams valid.
• SPDX validation: 1,300 files checked, all headers valid.
• Documentation navigation checker: every page URL matches its path.
• Fern 5.112.0 validation: zero errors and three existing warnings. The gateway configuration MDX parse warning also reproduced with that file restored to its unchanged main baseline; the other warnings cover unauthenticated redirect checking and theme contrast.
• Added repository links and anchors checked against the corresponding checkout; git diff --check passed.
• Full mise run pre-commit was attempted again but could not complete because Rust toolchain and Python/TypeScript dependency downloads were unavailable in this environment. Scoped contributor-guidance checks passed, including all 20 immediate exit-code checks. A temporary documentation-only commit hook passed; the installed repository hook was unchanged.
• Runtime unit/E2E tests are not applicable. No runtime or build implementation changed.

Checklist

• Follows Conventional Commits.
• Commits are signed off (DCO).
• Relevant architecture and published documentation updated.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-23T16:38:22.973152Z	14b86a1	New commits
🔒 Security Review	✅ Completed 2026-10-23T16:37:10.997119Z	14b86a1	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-4758.docs.buildwithfern.com/openshell

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c9142ea7d4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[drew]

Let's try and keep docs short and consistent.

[shailendra-nv]

Thanks for the feedback. The follow-up is pushed in 960d14ea. It trims the repeated Windows callouts, adds dedicated Windows sections, and restores the gateway example with current settings.

The scoped documentation checks passed. The broad pre-commit task could not complete because Rust/Python dependency downloads are blocked in this environment; the documentation-only commit hook passed.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 960d14ea54

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a11a8a2ec2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 14b86a1289

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[drew]

/ok to test dee46a9