docs(windows): note Git Bash requirement for A2UI builds#44234
docs(windows): note Git Bash requirement for A2UI builds#44234aniruddhaadak80 wants to merge 2 commits intoopenclaw:mainfrom
Conversation
openclaw-barnacle
bot
added
docs
Greptile SummaryThis is a documentation-only PR that adds a native Windows prerequisite callout to
Confidence Score: 5/5
Prompt To Fix All With AIThis is a comment left during a code review.
Path: docs/start/setup.md
Line: 30-34
Comment:
**Inconsistent note formatting**
The file already uses a `<Note>` MDX component at the top (lines 11–14) for callout-style content. This plain "Native Windows note:" paragraph doesn't match that convention and may render without any visual distinction in the docs site. Consider wrapping it in the same component for consistency:
```suggestion
<Note>
**Native Windows:** The repo build runs `pnpm canvas:a2ui:bundle`, which invokes a Bash script for the A2UI host bundle.
Install **Git for Windows** so Git Bash is available before running `pnpm build` or `pnpm build:strict-smoke`.
WSL2 remains the recommended Windows path for the full Gateway/tooling stack.
</Note>
```
How can I resolve this? If you propose a fix, please make it concise.Last reviewed commit: a207029 |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| Native Windows note: | ||
|
|
||
| - The repo build runs `pnpm canvas:a2ui:bundle`, which invokes a Bash script for the A2UI host bundle. | ||
| - If you build from native Windows instead of WSL2, install **Git for Windows** so Git Bash is available before running `pnpm build` or `pnpm build:strict-smoke`. | ||
| - WSL2 remains the recommended Windows path for the full Gateway/tooling stack. |
There was a problem hiding this comment.
Inconsistent note formatting
The file already uses a <Note> MDX component at the top (lines 11–14) for callout-style content. This plain "Native Windows note:" paragraph doesn't match that convention and may render without any visual distinction in the docs site. Consider wrapping it in the same component for consistency:
| Native Windows note: | |
| - The repo build runs `pnpm canvas:a2ui:bundle`, which invokes a Bash script for the A2UI host bundle. | |
| - If you build from native Windows instead of WSL2, install **Git for Windows** so Git Bash is available before running `pnpm build` or `pnpm build:strict-smoke`. | |
| - WSL2 remains the recommended Windows path for the full Gateway/tooling stack. | |
| <Note> | |
| **Native Windows:** The repo build runs `pnpm canvas:a2ui:bundle`, which invokes a Bash script for the A2UI host bundle. | |
| Install **Git for Windows** so Git Bash is available before running `pnpm build` or `pnpm build:strict-smoke`. | |
| WSL2 remains the recommended Windows path for the full Gateway/tooling stack. | |
| </Note> |
Prompt To Fix With AI
This is a comment left during a code review.
Path: docs/start/setup.md
Line: 30-34
Comment:
**Inconsistent note formatting**
The file already uses a `<Note>` MDX component at the top (lines 11–14) for callout-style content. This plain "Native Windows note:" paragraph doesn't match that convention and may render without any visual distinction in the docs site. Consider wrapping it in the same component for consistency:
```suggestion
<Note>
**Native Windows:** The repo build runs `pnpm canvas:a2ui:bundle`, which invokes a Bash script for the A2UI host bundle.
Install **Git for Windows** so Git Bash is available before running `pnpm build` or `pnpm build:strict-smoke`.
WSL2 remains the recommended Windows path for the full Gateway/tooling stack.
</Note>
```
How can I resolve this? If you propose a fix, please make it concise.Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
There was a problem hiding this comment.
Pull request overview
Updates contributor documentation to reduce native-Windows build confusion by calling out the repo’s Bash-dependent A2UI bundling step and pointing to remediation paths (Git Bash / WSL2).
Changes:
- Added a native-Windows prerequisite note to the from-source setup guide calling out the Bash-based
canvas:a2ui:bundlestep. - Added a Windows FAQ troubleshooting entry for
pnpm buildfailures aroundcanvas:a2ui:bundle/bash.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| docs/start/setup.md | Documents the Bash/Git Bash prerequisite for native Windows from-source builds. |
| docs/help/faq.md | Adds troubleshooting guidance for Windows pnpm build failures related to the A2UI bundling Bash script. |
| **3) `pnpm build` fails around `canvas:a2ui:bundle` / `bash`** | ||
|
|
There was a problem hiding this comment.
This new item is about from-source builds (pnpm build), but it’s nested under a Windows FAQ section titled as an installer-path problem. Consider moving it to a more build-specific troubleshooting section or adjusting the surrounding section title so readers can find this issue more predictably.
| Native Windows note: | ||
|
|
||
| - The repo build runs `pnpm canvas:a2ui:bundle`, which invokes a Bash script for the A2UI host bundle. | ||
| - If you build from native Windows instead of WSL2, install **Git for Windows** so Git Bash is available before running `pnpm build` or `pnpm build:strict-smoke`. |
There was a problem hiding this comment.
The guidance here implies that installing Git for Windows is sufficient before running pnpm build, but on Windows bash in npm scripts can still resolve to the System32 WSL stub (the common failure mode in #43891) unless the command is run from Git Bash or PATH is arranged so Git’s bash.exe wins. Consider updating the note to explicitly instruct running the build inside Git Bash (or otherwise ensuring bash resolves to Git Bash) rather than just “Git Bash is available”.
| - If you build from native Windows instead of WSL2, install **Git for Windows** so Git Bash is available before running `pnpm build` or `pnpm build:strict-smoke`. | |
| - If you build from native Windows instead of WSL2, install **Git for Windows** and run `pnpm build` / `pnpm build:strict-smoke` **from a Git Bash terminal** (or otherwise ensure that `bash` resolves to Git’s `bash.exe`, not the Windows System32 WSL stub). |
| - The from-source build bundles A2UI through a Bash script. | ||
| - Install **Git for Windows** so Git Bash is available, then reopen PowerShell and rerun the build. |
There was a problem hiding this comment.
This suggests “install Git for Windows … then reopen PowerShell and rerun”, but if bash resolves to the Windows System32 WSL stub, rerunning from PowerShell may still fail even after installing Git for Windows. Recommend telling users to run pnpm build from the Git Bash terminal (or to adjust PATH / verify where bash points to Git) so the script actually uses Git Bash.
| - The from-source build bundles A2UI through a Bash script. | |
| - Install **Git for Windows** so Git Bash is available, then reopen PowerShell and rerun the build. | |
| - The from-source build bundles A2UI through a Bash script, so a working **Git Bash** is required on Windows. | |
| - Install **Git for Windows** so Git Bash is available. | |
| - Run `pnpm build` from a **Git Bash** terminal (or make sure `where bash` shows the Git Bash executable, not the Windows System32 WSL stub, before rerunning from other shells). |
|
Overall this looks good. The Windows documentation changes do address the gap behind #43891 by calling out the Git Bash prerequisite / WSL2 fallback in both The main thing I’d flag is scope: this PR is titled and described as a Windows/A2UI documentation fix, but it also includes a separate iOS docs change in Minor nit: in |
Summary
pnpm buildreaches a Bash-based A2UI bundle step.Change Type (select all)
Scope (select all touched areas)
Linked Issue/PR
User-visible / Behavior Changes
Security Impact (required)
Repro + Verification
Environment
Steps
Expected
Actual
Evidence
Human Verification (required)
pnpm check:docsthrough Git Bash.xargs; validation was therefore run through Git Bash to keep the repository's intended docs gate intact.Compatibility / Migration
Failure Recovery (if this breaks)