fix: review findings — env-var netrc write hygiene, network-vs-auth errors, installer collision guard, docs

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

skills/setup/SKILL.md

@@ -28,7 +28,9 @@ English for precision; never quote it to the user.
 as "il token" and never repeat its value. Never inline a literal token
 on a shell command line — it ends up in the transcript and the process
 list. Write credentials into the netrc file with the file-writing
-tool, then let curl read them via `--netrc-file`.
+tool — or, for values that live only in session env vars, via shell
+redirection with unexpanded `$VAR` references — then let curl read
+them via `--netrc-file`.
 
 The verification call used throughout:
 
@@ -42,8 +44,10 @@ The verification call used throughout:
    verification call.
    - `200` → tell the user (Italian) the token already works and ask
      whether they want to replace it anyway. If not, stop.
-   - anything else → tell them the stored token no longer works
+   - `401`/`403` → tell them the stored token no longer works
      (probably expired or revoked) and continue to Step 1.
+   - anything else (timeout, DNS) → network problem, not credentials:
+     report it (Italian) and stop.
 2. Otherwise look for legacy credentials, in order:
    - session env: `test -n "$JIRA_EMAIL" && test -n "$JIRA_API_TOKEN" && echo session || echo unset`
    - `~/.claude/settings.json` (if it exists): `env.JIRA_EMAIL` /
@@ -51,11 +55,28 @@ The verification call used throughout:
 
    If found in either place: write them to the netrc (Step 2 format,
    chmod 600) and run the verification call.
+
+   **Important — how to write the netrc depends on where the values
+   came from:**
+   - Values read from `~/.claude/settings.json` are literals you
+     already hold: write the netrc with the file-writing tool as usual.
+   - Session-env credentials must never be echoed or expanded by you:
+     write the file via shell redirection with unexpanded references,
+     e.g.
+
+         printf 'machine <host>\nlogin %s\npassword %s\n' \
+           "$JIRA_EMAIL" "$JIRA_API_TOKEN" > ~/.config/gw-triage/netrc
+         chmod 600 ~/.config/gw-triage/netrc
+
+   After writing, run the verification call.
    - `200` → tell the user (Italian) the existing credentials were
      migrated to the new store and work immediately; then do Step 3
      (clean up legacy stores) and Step 4. Done — skip token creation.
-   - anything else → delete the netrc just written, tell them the old
+   - `401`/`403` → delete the netrc just written, tell them the old
      token no longer works, continue to Step 1.
+   - anything else (timeout, DNS) → network problem, not credentials:
+     report it (Italian) and stop, leaving the netrc in place — it may
+     verify fine later.
 3. Nothing found → first-time setup, continue to Step 1.
 
 ## Step 1 — Token creation (user, in the browser)