hil, docs: reference toolchains by their official env vars, not one rig's paths

~/code/pico/pico-sdk and $HOME/code/esp-idf/export.sh are the ci rig's private layout;
written into instructions they silently stop being true on tusb, a dev PC, or any
future rig. The docs now use the variables the vendors define -- PICO_SDK_PATH for the
Pico SDK and IDF_PATH for ESP-IDF, activated explicitly as `. "$IDF_PATH/export.sh"` --
and leave where the checkouts live to each host's profile.

The variables are only useful if the shells that agents actually get can see them, and
`ssh <rig> 'cmd'` is non-interactive AND non-login: it reads no profile, and Debian's
sshd-sourced ~/.bashrc returns at the interactive guard before most of the file. The ci
rig already keeps its exports in the section ABOVE that early-return; IDF_PATH now sits
there beside PICO_SDK_PATH, and the whole chain is verified from a plain non-interactive
ssh: both variables visible, `. "$IDF_PATH/export.sh"` activates ESP-IDF v5.5.3 with
idf.py on PATH -- no login shell, no alias, no hard-coded path. hil-pool-check documents
that placement so the next rig is set up the same way.

5 files changed, 12 insertions, 10 deletions

diff --git a/.claude/agents/builder.md b/.claude/agents/builder.md
index 70648e80d..4edb7e0d4 100644
--- a/.claude/agents/builder.md
+++ b/.claude/agents/builder.md
@@ -25,7 +25,7 @@ cmake -S examples/<group>/<example> -B "$BUILD" -DBOARD=<BOARD> -G Ninja -DCMAKE
 cmake --build "$BUILD"
 ```
 
-Espressif boards (listed under `hw/bsp/espressif/boards/`): run `. $HOME/code/esp-idf/export.sh` first; only ESP-IDF examples build for them (e.g. `cdc_msc_freertos`): `idf.py -DBOARD=<BOARD> build` from the example dir.
+Espressif boards (listed under `hw/bsp/espressif/boards/`): run `. "$IDF_PATH/export.sh"` first (`IDF_PATH` is the official ESP-IDF variable, exported per host); only ESP-IDF examples build for them (e.g. `cdc_msc_freertos`): `idf.py -DBOARD=<BOARD> build` from the example dir.
 
 ## Recovery rules
 
diff --git a/.claude/skills/esp-target-debug/SKILL.md b/.claude/skills/esp-target-debug/SKILL.md
index 1af9fcf7f..7b21788f1 100644
--- a/.claude/skills/esp-target-debug/SKILL.md
+++ b/.claude/skills/esp-target-debug/SKILL.md
@@ -48,7 +48,7 @@ UART side is also the remote reset: `esptool.py --after hard_reset read_mac`.
 ## Attach
 
 ```bash
-. $HOME/code/esp-idf/export.sh          # openocd-esp32, riscv32-/xtensa-esp32s3-elf-gdb, esptool
+. "$IDF_PATH/export.sh"                 # openocd-esp32, riscv32-/xtensa-esp32s3-elf-gdb, esptool
 openocd -c 'set ESP_RTOS FreeRTOS' -f board/esp32p4-builtin.cfg \
         -c 'adapter serial <MAC-with-colons>' &        # S3: board/esp32s3-builtin.cfg
 riscv32-esp-elf-gdb -batch -ex 'target extended-remote :3333' \
diff --git a/.claude/skills/hil-pool-check/SKILL.md b/.claude/skills/hil-pool-check/SKILL.md
index 3c056c16b..65e28b65f 100644
--- a/.claude/skills/hil-pool-check/SKILL.md
+++ b/.claude/skills/hil-pool-check/SKILL.md
@@ -39,11 +39,13 @@ ssh ci.lan 'bash -lc "cd ~/code/tinyusb && python3 test/hil/helper/hil_pool_chec
 ## Notes
 
 Missing firmware is **built on the spot** — never skipped (`--no-build` opts out; those boards
-then report `flash-failed`). Builds need the family env, exported on the rig in
-`~/.profile`/`~/.bashrc`: `PICO_SDK_PATH` for rp2040/rp2350 (`~/code/pico/pico-sdk`), the
-ESP-IDF env for espressif — source it as `. $HOME/code/esp-idf/export.sh`, NOT as `get-idf`:
-that is an interactive shell alias (`~/.bashrc`), and aliases are not expanded in non-interactive
-shells, so scripts and agents get `get-idf: command not found` even under `bash -lc`. It also
+then report `flash-failed`). Builds need the family env, referenced by its OFFICIAL variable so the docs hold on any
+rig: `PICO_SDK_PATH` for rp2040/rp2350, `IDF_PATH` for espressif — activated explicitly as
+`. "$IDF_PATH/export.sh"`, never as `get-idf` (an interactive alias; aliases are not expanded
+in non-interactive shells, so scripts get `get-idf: command not found` even under `bash -lc`).
+Each host exports both vars in `~/.bashrc` ABOVE the interactive early-return, which is what
+makes a plain non-interactive `ssh <rig> 'cmd'` see them (verified on ci; where the checkouts
+live is that host's business, not this file's). It also
 needs `esptool` on PATH (pip's
 `~/.local/bin/esptool`; a non-login shell may lack it — run via `bash -lc`). An explicit `-B` is
 searched exclusively for *existing* firmware; builds still land in `cmake-build/` and are noted
diff --git a/CLAUDE.md b/CLAUDE.md
index 6a751aca7..c43a4f9f7 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -28,7 +28,7 @@ Bias toward caution over speed. For trivial tasks, use judgment.
 ```bash
 sudo apt-get install -y gcc-arm-none-eabi          # ARM toolchain (2-5 min, one-time)
 python3 tools/get_deps.py [FAMILY|-b BOARD]        # fetch deps into lib/, hw/mcu/ (<1 s)
-. $HOME/code/esp-idf/export.sh                     # Espressif only: before any build/flash/monitor
+. "$IDF_PATH/export.sh"                            # Espressif only: before any build/flash/monitor (IDF_PATH set per host)
 ```
 
 ## Build
diff --git a/test/hil/helper/hil_pool_check.py b/test/hil/helper/hil_pool_check.py
index 8ad68bc6d..d926bbe3d 100644
--- a/test/hil/helper/hil_pool_check.py
+++ b/test/hil/helper/hil_pool_check.py
@@ -329,7 +329,7 @@ def flash(board: dict, fw, allow_recovery: bool, probe_port: str, note: list) ->
             return True
         if rc == 127:  # flasher binary missing: retries/probe recovery can't fix env
             note.append(f'flasher tool missing ({err}) — esptool needs the ESP-IDF env '
-                        f'(. $HOME/code/esp-idf/export.sh)'
+                        f'(. "$IDF_PATH/export.sh")'
                         if board['flasher']['name'].lower() == 'esptool' else
                         f'flasher tool missing: {err}')
             return False
@@ -489,7 +489,7 @@ def ensure_fw(board: dict, variant: str, example: str, note: list):
     if rc == 127 and board['flasher']['name'].lower() == 'esptool':
         _builds[key] = (None, 'no-env')
         note.append(f'cannot build {base}: ESP-IDF env missing '
-                    f'(source $HOME/code/esp-idf/export.sh)')
+                    f'(. "$IDF_PATH/export.sh")')
         return None
     if rc == 124:  # hung build: a deps/cache retry cannot cure it, don't double the stall
         _builds[key] = (None, 'timeout')