khh

docs/BOOTSTRAP.md

@@ -32,6 +32,7 @@ Notes
 
 - On Windows you may need to run PowerShell with an appropriate ExecutionPolicy (example shows using `-ExecutionPolicy Bypass`).
 - The scripts default to a venv directory named `.venv` in the repository root. Use `-VenvPath` (PowerShell) or `--venv` (bash) to choose a different directory.
+- The scripts will also install Playwright browser binaries by default (Chromium only) after installing Python dependencies. Use `--no-playwright` (bash) or `-NoPlaywright` (PowerShell) to opt out, or `--playwright-browsers <list>` / `-PlaywrightBrowsers <list>` to request specific engines (comma-separated, or use `all` to install all engines).
 - The scripts are intended to make day-to-day developer setup easy; tweak flags for your desired install mode (editable vs normal) and shortcut preferences.
 
 ## Deno — installed by bootstrap
@@ -82,3 +83,31 @@ DENO_VERSION=v1.34.3 ./scripts/bootstrap.sh
 If you'd like, I can also:
 - Add a short README section in `readme.md` referencing this doc, or
 - Add a small icon and polish Linux desktop entries with an icon path.
+
+## Troubleshooting: urllib3 / urllib3-future conflicts ⚠️
+
+On some environments a third-party package (for example `urllib3-future`) may
+install a site-packages hook that interferes with the real `urllib3` package.
+When this happens you might see errors like:
+
+  Error importing cmdlet 'get_tag': No module named 'urllib3.exceptions'
+
+The bootstrap scripts now run a verification step after installing dependencies
+and will stop if a broken `urllib3` is detected to avoid leaving you with a
+partially broken venv.
+
+Recommended fix (activate the venv first or use the venv python explicitly):
+
+PowerShell / Windows (from repo root):
+
+  .venv\Scripts\python.exe -m pip uninstall urllib3-future -y
+  .venv\Scripts\python.exe -m pip install --upgrade --force-reinstall urllib3
+  .venv\Scripts\python.exe -m pip install niquests -U
+
+POSIX (Linux/macOS):
+
+  .venv/bin/python -m pip uninstall urllib3-future -y
+  .venv/bin/python -m pip install --upgrade --force-reinstall urllib3
+  .venv/bin/python -m pip install niquests -U
+
+If problems persist, re-run the bootstrap script after applying the fixes.