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.

docs/ISSUES/urllib3-future.md

@@ -0,0 +1,44 @@
+Title: urllib3-future .pth hook can leave urllib3 broken after installation
+
+Description:
+
+We observed environments where installing `urllib3-future` (or packages
+that depend on it, such as `niquests`) leaves a `.pth` file in site-packages
+that overrides `urllib3` in a way that removes expected attributes (e.g.:
+`__version__`, `exceptions`) and causes import-time failures in downstream
+projects (e.g., `No module named 'urllib3.exceptions'`).
+
+Steps to reproduce (rough):
+
+1. Install `urllib3` and `urllib3-future` (or a package that depends on it)
+2. Observe that `import urllib3` may succeed but `urllib3.exceptions` or
+   `urllib3.__version__` are missing, or `importlib.util.find_spec('urllib3.exceptions')`
+   returns `None`.
+
+Impact:
+
+- Downstream packages that expect modern `urllib3` behavior break in subtle
+  ways at import time.
+
+Suggested actions for upstream:
+
+- Avoid using a `.pth` that replaces or mutates the `urllib3` package in-place,
+  or ensure it keeps the original `urllib3` semantics intact (i.e., do not create
+  a namespace that hides core attributes/members).
+- Provide clear upgrade/migration notes for hosts that may have mixed
+  `urllib3` and `urllib3-future` installed.
+
+Notes / local workaround:
+
+- In our project we implemented a startup compatibility check and fail-fast
+  guidance that suggests running:
+
+  python -m pip uninstall urllib3-future -y
+  python -m pip install --upgrade --force-reinstall urllib3
+  python -m pip install niquests -U
+
+and we added CI smoke tests and bootstrap verification so the problem is
+caught during setup rather than later at runtime.
+
+Please consider this a friendly bug report and feel free to ask for any
+additional diagnostics or reproduction details.

docs/KNOWN_ISSUES.md

@@ -0,0 +1,8 @@
+Known issues and brief remediation steps
+
+- urllib3 / urllib3-future conflict
+  - Symptom: `No module named 'urllib3.exceptions'` or missing `urllib3.__version__`.
+  - Root cause: a `.pth` file or packaging hook from `urllib3-future` may mutate the
+    `urllib3` namespace in incompatible ways.
+  - Remediation: uninstall `urllib3-future`, reinstall `urllib3`, and re-install
+    `niquests` if required. See `docs/ISSUES/urllib3-future.md` for more details.