#183 docs: add troubleshooting for PATH-shadowed Doberman installations

[Anonymous]

Originally created by: Shihasz

Pull Request

Slice

• Repo: doberman-core
• Feature / Slice: [#174] — docs: add troubleshooting for PATH-shadowed Doberman installations
• Plan reference: N/A (docs fix from a filed issue, not part of the implementation plan)

What this PR does

Adds a "Troubleshooting: wrong or stale doberman on PATH" section to
docs/SETUP.md, right after the Install step. Covers how to list every
resolved doberman executable (PowerShell, Command Prompt, and Unix-like
shells), how to compare the resolved executable against the active virtual
environment, how to safely inspect pip/pipx/venv installs, and non-destructive
remediation options (re-activating the intended venv, invoking its executable
explicitly, or opening a fresh shell). No code changes.

Closes [#174].

Formatted and refined with AI assistance.

Tests added (run in CI)

• N/A — documentation-only change, no code paths affected. Ran the existing
  suite locally (ruff check ., ruff format --check ., lint-imports,
  pytest --cov=doberman ...) to confirm nothing broke; all commands in the
  new section were tested manually in their respective shells.

Public-release safety (doberman-core only)

• [x] Contains nothing from the "not allowed" list: no enterprise/hosted code, no proprietary detection, no customer data, no secrets, no commercial-license code
• [x] Core still builds/tests/runs with NO enterprise package installed

Security checklist

• [x] Fails closed on error / uncertainty — N/A (no runtime behavior changed; doc only)
• [x] No secret, full file, or unredacted prompt logged or committed
• [x] Any guardrail/learning change is raise-only (no silent loosening) — N/A, no guardrail logic touched
• [x] Every BLOCK/AUTH carries reason codes + a human explanation — N/A, no decision-engine code touched
• [x] doberman-core does not import doberman_enterprise — N/A, no imports added

Edge cases covered / Deviations from plan / Risks introduced

• Deliberately out of scope, per the issue: no PATH editing, no deleting
  environments, no uninstalling packages on the contributor's behalf, no
  changes to the installer/packaging config.
• No risks introduced — this is a documentation-only change with zero effect
  on runtime behavior, the decision engine, or CI.

[Anonymous]

Ticket changed by: fu351

• status: open --> closed

[Anonymous]

Originally posted by: fu351

Welcome to the pack, @Shihasz — and congratulations on your first contribution to Doberman! 🐾

Thank you for tackling [#174] and keeping the troubleshooting guidance non-destructive. If Doberman is useful to you, we'd love a star on the repo ⭐, and you're warmly invited to join us on Discord: https://discord.gg/Sfy5XGNqty

Glad to have you here!

[Anonymous]

Originally posted by: fu351

Your troubleshooting section for PATH-shadowed installs is exactly the kind of clear, step-by-step diagnostic doc that saves people hours of confusion — thanks for writing it. If you're up for another docs pass, [#186] (docs: catalogue every ReasonCode and what it means, level-2) is the same clarity instinct applied to Doberman's explainability contract, or [#189] (docs: document the shared shape of Doberman's host adapters, level-3) if you want a bit more code-reading first. Issues are labelled level-1 through level-10 so you can gauge scope before picking — commenting on one claims it.