[oscarbol09]

What does this PR do?

Adds \docs/WINDOWS_TROUBLESHOOTING.md\ and links it from the README Troubleshooting table, fulfilling the proposal agreed in #1170.

Each entry documents:

• Confirmed symptom
• Affected version ranges
• Current workaround
• Canonical tracking issue

The entries reflect verified status against v0.10.x and v0.11.0 (clarifying that earlier root-cause fixes such as wide-string environment variable decoding and out-of-process update handling apply to v0.10.0+, while keeping open issues like #1130 and #1145 actionable for triage).

Refs #1170

Note: Drafted with AI assistance (Antigravity/Gemini) on behalf of Oscar Madera (@oscarbol09).

Checklist

• Every commit is signed off (\git commit -s) — required, CI rejects unsigned commits (DCO, see CONTRIBUTING.md)
• Documentation-only change (no C code or build infrastructure modified)

[DeusData]

Thank you, @oscarbol09, for following through on the proposal you opened in #1170, and for shaping every entry exactly the way it was agreed there: confirmed symptom, affected versions, workaround and tracking issue. We are reviewing it now. One thing we need to settle on our side first: an earlier pull request for the same page (#2262) is still open, and we want both contributions credited fairly before we land one. We will come back shortly with the outcome and a few small wording updates, since a couple of entries changed with v0.12.0. Nothing is needed from you in the meantime.

[github-actions]

Thanks for opening this — it has been seen, and it is queued.

This note is automated, but it is not a brush-off: it exists so you know where your PR stands instead of having to guess from silence.

Current review status: working through a backlog. 0.9.1-rc.1 is out, so the release freeze that held reviews is over — but it left a large queue of open pull requests behind it, and we are reading through them oldest-first. The background is in discussion #1144.

What that means for this PR, concretely:

• It will not be closed for inactivity. No stale bot touches pull requests here.
• It may still sit a while before a human reads it. That is on us, not on you.
• Older PRs are read first, so a recent one is not being skipped — it is behind a queue.

Things that will genuinely speed it up whenever review does happen:

• Keep it rebased on main — the tree is moving quickly right now, and a conflicting branch cannot be reviewed as the diff you intended.
• Get CI green, or say which failures you believe are pre-existing.
• Keep the change to one claim. Bundled features and refactors get split before they get merged, which costs you a round trip.
• Every commit needs a sign-off (git commit -s) — CI enforces DCO.

If this fixes a bug, a reproduction we can run is worth more than a description of the symptom.

Thanks for contributing, and sorry in advance for the wait.

[DeusData]

Thank you, @oscarbol09, for turning the proposal from #1170 into a real page, and for keeping every entry to the shape agreed there: symptom, affected versions, workaround and tracking issue. That structure is exactly what keeps a page like this honest from one release to the next.

As promised, we pushed one small commit on top of your branch (a36b2ee) to bring the entries up to date with v0.12.x. It only touches docs/WINDOWS_TROUBLESHOOTING.md; your README link stays as you wrote it.

1. Non-ASCII paths: the workaround now keeps to the two simple routes, ASCII-only paths for the two variables or an upgrade, and drops the NTFS junction example.
2. Upgrade entry: the CLI command is update, so the symptom now names it that way, and Can't upgrade codebase-memory-mcp on windows platform. Can't uninstall. #1168 is marked as closed, fixed in v0.10.0.
3. Index worker: from v0.12.0, a worker that exits without returning a result is no longer counted as a success, and its log is kept. The entry now says so and asks for the log when indexing still fails on v0.11.0 or newer.
4. Antigravity: the affected range is now explicit (all releases through v0.12.1 when neither detection signal is present), together with which signal each version checks; the duplicate binary is scoped to v0.9.x and earlier.
5. OpenCode: detection is now listed per version: PATH only on v0.9.x, the configuration from v0.10.0, and from v0.12.0 the data folder that both the OpenCode CLI and the Desktop app create, so PATH is no longer needed. It also notes the long-PATH and npm/mise/scoop shim gaps that fix(cli): resolve Windows CLI detection for long PATH and npm/mise/scoop shims (#221) #2381 fixed after v0.12.1, and gives a workaround for each version.

An earlier pull request for the same page, #2262 by Tamer, laid out much of this structure first, so the commit carries a Co-authored-by line for Tamer, and we will close #2262 with thanks once this one lands. The page is credited to both of you.

If you push to this branch again, please pull first so the new commit is not lost. We will merge once CI is green. Thank you again for following this through!

[DeusData]

Thank you for your patience, @oscarbol09. CI went green on this branch, but this evening's merges on main touched files this pull request also changes, so that green no longer covered today's main. We merged current main into the branch once more (one merge commit, 5d97172; your changes are untouched) and will merge once the fresh checks are green. Please pull before pushing again.

[DeusData]

Merged as ba0f8a8 - thank you, @oscarbol09! docs/WINDOWS_TROUBLESHOOTING.md is now on main, with every entry in the agreed shape: symptom, affected versions, workaround and tracking issue, brought up to date for v0.12.x. Thank you for turning the #1170 proposal into a real page and for following it through.