docs: record the Windows Store python alias failure in troubleshooting

[dchaudhari7177]

Rebased onto main and narrowed to docs only — #272 landed the script fix while this was open, so the scripts/check-duckdb-bind-claims.sh half of this branch is gone. What is left is the symptom entry, which #272 did not add.

Why the entry still earns its place

The failure names the wrong culprit. The pre-push hook dies with

Python was not found; run without arguments to install from the Microsoft Store…

on a machine where python --version prints a real version — so it reads as a broken Python install rather than as a PATH shim being preferred over a working interpreter. And CI never reproduces it: the duckdb-bind-claims job runs on ubuntu-latest.

The entry records the transcript that separates the two:

$ command -v python3          # finds the stub
/c/Users/you/AppData/Local/Microsoft/WindowsApps/python3
$ python3 -c "import sys"; echo $?
Python was not found; run without arguments to install from the Microsoft Store...
49
$ python -c "import sys"; echo $?
0

That is the shape a contributor needs in order to recognise the same thing coming from some other tool, so the entry closes with the Settings path to disable the alias (Apps → Advanced app settings → App execution aliases) rather than only pointing at this script.

The Fix line now points at main instead of describing a change — the script side is #272's, and this does not restate it.

Verification

• bash scripts/check-doc-citations.sh → 7 OK, 0 problems
• check-python-twins → OK (5 pairs)
• Diff is one file, +34/-0.

[cofade]

senior-reviewer — partially superseded by #272, but please don't close this

Reviewed against current main (669f6c3), which merged #272. I ran both variants of the script, ran shellcheck, and grepped the tree rather than taking either PR body at its word.

Status: CONFLICTING / DIRTY — #272 rewrote the same lines. The CI green on this branch predates #272's new ts-quality / python-lint / repo-guards jobs.

What is now redundant

The core fix already landed. scripts/check-duckdb-bind-claims.sh's candidate loop now runs "$cand" -c 'import sys; sys.exit(0)' instead of command -v, which is functionally identical to your probe. I verified both variants on a Windows box that has only py in Git Bash (no python3, no python): both resolve py and print OK — dev is LAN-reachable, prod is loopback-only, rc=0. shellcheck -S info is clean on both, so the two # shellcheck disable=SC2086 directives do their job.

What this PR still delivers that main does not

P1 — the docs deliverable named in #270 is unmet on main. The issue asked for docs/troubleshooting.md (symptom + fix). On main the stub is mentioned only as a parenthetical inside the ruff-not-found entry. Grepping origin/main across docs/, scripts/, CLAUDE.md, CONTRIBUTING.md, README.md:

string	hits on main
Python was not found	0
Microsoft Store	0
App Execution Alias	0
WindowsApps	0
check-duckdb-bind-claims (in troubleshooting.md)	0

Someone whose git push dies with Microsoft's Store advertisement has nothing to search for. Your 33-line entry is keyed on exactly that string. This is the PR's real remaining value.

P2 — main's comment now contradicts itself. scripts/check-duckdb-bind-claims.sh still carries "Windows Git Bash typically has only the py launcher, never python3 — the same detection ESP32-CAM/build.sh does for the same reason (#99)", and the paragraph #272 added directly beneath it explains that a stock Windows install does put a python3 on PATH. Both cannot be true. Your version deletes the stale line rather than stacking a correction on top of it.

I verified your supporting claim rather than accepting it. git log -S 'MS Store stub at python3.exe' -- ESP32-CAM/build.sh points at dc8435e ("fix: Step 2 wizard end-to-end on Windows", the #99 PR). So build.sh has validated by execution since #99, the parity claim written in #222 was false when written, and it is true today only by coincidence. You were right about the root cause, and it is exactly the failure mode CLAUDE.md's "never trust commit messages over code" rule exists to catch.

P2 — py -3 first is marginal, not a fix. main's python3 python py order already reaches a working interpreter in every case I could construct, including the one in #270. py -3 first only helps when python resolves to a working but wrong interpreter (a py2, a stale venv) — and the embedded JSON snippet in bind_host_ip is py2-compatible anyway. Worth taking for robustness; not worth a merge conflict on its own.

P2 — if py -3 stays, prefer an array over unquoted expansion. The script is #!/usr/bin/env bash, so this drops both disable=SC2086 directives:

PY=()
for cand in "py -3" python3 python py; do
  read -ra try <<<"$cand"
  if "${try[@]}" -c 'import sys' >/dev/null 2>&1; then PY=("${try[@]}"); break; fi
done
# …later:
printf '%s' "$rendered" | "${PY[@]}" -c '…'

P2 — the troubleshooting entry should cross-link, not duplicate. main's ruff entry already explains the stub. CLAUDE.md is explicit: "if the gotcha is already documented, link it; don't duplicate it." On rebase, let the new entry own the git push symptom and point at the ruff entry for the PATH half. Its "Fix. Already fixed — … Pull main" wording should also become a reference to #272.

Requested change

Rebase onto main and reduce this to the residual delta — the cross-linked troubleshooting.md entry, the stale-comment deletion, and optionally py -3 in the array form above.

Closing this outright would discard the one deliverable #270 explicitly asked for, and would leave that issue marked COMPLETED with its docs target unmet. The diagnosis here was correct before the fix landed elsewhere; the docs half is still owed.

Out of scope, tracked separately

ESP32-CAM/build.sh probes python3 python and never py — on a box like the one I tested, it fails outright. It is masked today only because the script prefers esptool.exe and skips Python entirely when it finds one. Meanwhile scripts/ruff.sh uses a third candidate list. Three probes, three orders. Filing a separate issue.

[cofade]

Follow-up issue filed for the three divergent interpreter probes: #273. It carries the stale-comment cleanup too, so if this PR is rebased and merged that part drops out of #273's scope.