Installer: make `~/.local/bin` PATH setup reliable on Linux (login-shell trap) + add install troubleshooting doc

[saadqbal]

Context

A customer on Ubuntu 24.04.4 LTS installed via the headline one-liner (curl -fsSL …/install.sh | sh) and reported the CLI was "still not in the PATH, even after restarting the shell."

Root cause

The unprivileged one-liner can't write /usr/local/bin, so install.sh falls back to $HOME/.local/bin (scripts/install.sh L240–L250) and then only prints PATH advice — it never edits a shell rc file (scripts/install.sh L262–L270).

On an Ubuntu desktop this combination is a trap:

• Ubuntu's stock ~/.profile adds ~/.local/bin to PATH, but only at login and only if the directory already existed at login. The installer creates it mid-session.
• GNOME Terminal opens non-login shells → they read ~/.bashrc (which has no such logic), not ~/.profile. So "open a new terminal" never triggers the fix; only a full logout/login does.

Net effect: a stock curl | sh install on an Ubuntu desktop leaves the CLI off PATH until the user does something non-obvious (re-login, or hand-edit an rc file the printed note doesn't even name).

Meanwhile the Windows installer already does the right thing — it persists user-scope PATH automatically (scripts/install.ps1 L205–L213). The Linux/macOS script should be no worse.

Proposed fix (any subset)

1. When falling back to ~/.local/bin, offer to append export PATH="$HOME/.local/bin:$PATH" to the correct rc file (detect $SHELL: ~/.zshrc for zsh, ~/.bashrc for bash), gated on interactivity — skip when stdin isn't a TTY (the piped curl | sh case) or behind an explicit --modify-path flag — mirroring what install.ps1 already does.
2. At minimum, replace the bare export PATH note with shell-/distro-aware guidance: name the rc file, and on Linux tell the user to . ~/.profile now or re-login (a new terminal tab is not enough).
3. Consider preferring /usr/local/bin more aggressively — it's on PATH for both login and non-login shells on Ubuntu out of the box — e.g. when sudo is available.
4. Add a short install-troubleshooting doc (none exists today — the repo has only the README + the RFC) covering the ~/.local/bin / PATH case for Linux (login vs non-login shells), macOS (.bash_profile vs .bashrc, zsh), and Windows (new window required), and link it from the README install section.

Acceptance criteria

• A stock curl … | sh install on Ubuntu 24.04 desktop yields a working tracebloc command in a newly-opened terminal without a full logout/login or manual rc editing — OR the installer prints unambiguous, shell-correct next steps that work on the first try.
• The behavior is documented in a troubleshooting doc linked from the README.
• No regression to the non-interactive curl | sh path (must not block waiting for input on a pipe).

References

• Customer OS: Ubuntu 24.04.4 LTS
• scripts/install.sh — fallback to $HOME/.local/bin: L240–L250; print-only PATH advice: L262–L270
• scripts/install.ps1 — auto-sets user-scope PATH: L205–L213
• Surfaced during a customer support thread (PATH-after-install).

[saadqbal]

Status: addressed by #61 (targets develop).

PR #61 (by @LukasWodka) makes install.sh persist the PATH entry to the user's shell rc on the ~/.local/bin fallback — directly fixing the "not on PATH after restarting the shell" report (verified across bash/zsh/fish on Linux + macOS, idempotent, no pipe-hang).

I pushed a follow-up commit (dda7218) to cover the rest of this ticket's acceptance criteria:

• Criterion Phase 2: kubeconfig discovery + parent release detection + SA token #2 (doc): added docs/troubleshooting.md + linked it from the README install section.
• Hardened the rc-write fallback so a read-only rc no longer leaks a raw Permission denied before the clean fallback message.

Acceptance criteria #1 (works on Ubuntu without re-login/manual editing) and #3 (no regression to the piped curl | sh path) are met; #2 is now satisfied.

Leaving this open until #61 merges. Per our board convention, a merge to develop won't auto-close it — close manually on merge.