Interface protocol rev 2: two-level docs, hc CLI retired

docs/concepts/workspace_and_environment.md

@@ -22,8 +22,8 @@ or topic:
 
 | | **Tier 1 — ROS native** | **Tier 2 — workspace tooling** | **Tier 3 — separate project** |
 |---|---|---|---|
-| Location | `src/<pkg>/` | per-package `scripts/`, the `hc` CLI, a future top-level `scripts/` | its own git repo, outside the workspace |
-| Examples | `humanoid_controllers`, `humanoid_devices_robstride`, `humanoid_drivers_socketcan` | `robstride_probe`, calibration helpers, `hc bus ping` | `Lite-SDK2`, `Lite-Gravity-Compensation` |
+| Location | `src/<pkg>/` | per-package `scripts/`, the workspace pixi tasks, a future top-level `scripts/` | its own git repo, outside the workspace |
+| Examples | `humanoid_controllers`, `humanoid_devices_robstride`, `humanoid_drivers_socketcan` | `robstride_probe`, calibration helpers, `pixi run ping-bus` | `Lite-SDK2`, `Lite-Gravity-Compensation` |
 | Build / run | `colcon` + `ros2 run` | `pixi run …` | own toolchain (`uv run …`) |
 | Imports `rclpy`? | **yes** | no | **no** |
 | Talks to ROS via | native pub / sub / service / action | doesn't talk to running nodes | **DDS (CycloneDDS)** + file handoff |

docs/getting_started/installation.md

@@ -78,13 +78,11 @@ platforms = ["linux-64", "linux-aarch64"]
 # ROS 2 CLI + launch + runtime (ros2 launch / run / pkg). The bar packages
 # declare their library deps but not the CLI tooling, so pull a ROS base
 # yourself. Use ros-jazzy-desktop instead if you want the RViz-based
-# viewers (`hc viz urdf`, `view_lite.launch.py`).
+# viewers (`view_lite.launch.py`).
 ros-jazzy-ros-base = "*"
 # The whole Lite bringup: humanoid_controllers (ONNX-enabled), humanoid_control_msgs,
 # lite_description, humanoid_devices_robstride, humanoid_drivers_socketcan, humanoid_control_common, humanoid_control_policy.
 ros-jazzy-humanoid-control-bringup-lite = "*"
-# Optional: the `hc` toolbox CLI — lands on PATH (hc viz / hc bus ping / ...).
-ros-jazzy-humanoid-control-cli = "*"
 ```
 
 `berkeley-humanoids` is listed **first** so `ros-jazzy-humanoid-control-*` resolves from there, with
@@ -113,18 +111,22 @@ pixi run ros2 launch humanoid_bringup_lite real.launch.py
 RoboStack ROS core — no build step. Everything the packages ship (launch files,
 URDFs, meshes, controller YAMLs, console executables) lands on the ament index,
 so `ros2 launch …` / `ros2 run …` work inside `pixi shell` (or via
-`pixi run …`). The `hc` toolbox CLI installs a `bin/` shim, so `hc` itself
-is on `PATH` inside `pixi shell` (or via `pixi run -- hc …`).
+`pixi run -- ros2 …`).
 
 ```sh
 pixi shell
 ros2 pkg list | grep '^humanoid_control_'                              # the humanoid_control_* packages you pulled in
 ros2 launch humanoid_bringup_lite real.launch.py --show-args   # dry-parse the launch (no hardware)
-hc bus discover --iface can0 --scan-to 32              # read-only CAN scan, e.g.
+ros2 run humanoid_devices_robstride robstride_discover --iface can0 --scan-to 32   # read-only CAN scan, e.g.
 ```
 
+To get the standard one-word aliases (`pixi run scan-bus`,
+`pixi run viz`, …) in your own project, copy the task reference block
+from [How-to → Workspace commands](../how_to/use_pixi_tasks.md#the-reference-block)
+into your `pixi.toml`.
+
 :::note[What the channel ships today]
-`berkeley-humanoids` carries the **11 `ros-jazzy-humanoid-control-*` packages** for both `linux-64`
+`berkeley-humanoids` carries the **`ros-jazzy-humanoid-control-*` packages** for both `linux-64`
 and `linux-aarch64` (Jetson). That covers the full control stack and the
 real-hardware **Lite** bringup (`real.launch.py`). Not yet published: the MuJoCo
 simulation deps (`mujoco_*`), the piano task (`pianist_*`), and the EtherCAT /
@@ -216,7 +218,7 @@ and the compile-commands export come from `config/colcon-defaults.yaml` via
 `COLCON_DEFAULTS_FILE`, so the manual invocation behaves identically.)
 
 `pixi shell` sources the conda env and (via `scripts/activate.sh`) the
-`install/setup.sh` overlay once it exists, so `ros2`, `colcon`, `hc`, and every
+`install/setup.sh` overlay once it exists, so `ros2`, `colcon`, and every
 console script land on `PATH`. The build
 covers the Lite path (every Humanoid Control + Pianist package plus the three `mujoco_*`
 deps). `--symlink-install` means edits to launch / config / Python files are
@@ -228,18 +230,17 @@ re-sources the overlay whenever you enter `pixi shell`. Then run
 ### 5. Sanity-check
 
 ```sh
-ros2 pkg list | grep '^humanoid_control_'        # 12 entries from Humanoid Control
+ros2 pkg list | grep '^humanoid_control_'        # the humanoid_control_* packages
 ros2 pkg list | grep '^pianist_'    # 4 entries from pianist_ros2
 ros2 control list_hardware_interfaces 2>/dev/null \
     || echo "(no controller_manager running yet — expected)"
 ```
 
-The 11 `Humanoid Control` packages (Lite's `lite_description` comes separately, via `bar.repos`):
+The `Humanoid Control` packages (Lite's `lite_description` comes separately, via `bar.repos`):
 
 ```
 humanoid_bringup_lite
 humanoid_bringup_prime
-humanoid_control_cli
 humanoid_control_common
 humanoid_controllers
 humanoid_devices_robstride

docs/how_to/diagnose_enobufs.md

@@ -52,12 +52,12 @@ each motor.
 
 ```bash
 # Quick read-only probe to confirm motors are responding
-hc bus discover --iface can0
-hc bus discover --iface can1
+pixi run scan-bus --iface can0
+pixi run scan-bus --iface can1
 # Should report 7 motors on each bus, no ENOBUFS warnings in the output.
 ```
 
-If `hc bus discover` itself reports `tx_dropped > 0`, motors are
+If the scan itself reports `tx_dropped > 0`, motors are
 still off the bus. Don't proceed until that scan is clean.
 
 ## Step 2 — Check the kernel CAN state
@@ -157,8 +157,8 @@ bottleneck. Either drop the rate or upgrade the adapter.
 
 ```
 ENOBUFS warnings observed
-├── hc bus discover reports 0 motors → motor power off → fix power, relaunch
-├── hc bus discover reports motors but ENOBUFS persists at activation only
+├── pixi run scan-bus reports 0 motors → motor power off → fix power, relaunch
+├── pixi run scan-bus reports motors but ENOBUFS persists at activation only
 │   └── Burst-on-Enable. Drop activate-time WriteParameter calls (already done
 │       in our plugin via write_firmware_limits=false default). If recurring,
 │       raise txqueuelen or stagger Enables.

docs/how_to/first_real_bringup.md

@@ -46,15 +46,16 @@ acceptable; `BUS-OFF` means power-cycle the adapter.)
 
 ## Step 2 — Confirm motors are alive
 
-A read-only scan before anything claims the bus:
+A read-only scan before anything claims the bus (`scan-bus` is the
+workspace task wrapping
+`ros2 run humanoid_devices_robstride robstride_discover`):
 
 ```bash
 cd humanoid_control_ws
-pixi shell
-hc bus discover --iface can0 --scan-to 32
+pixi run scan-bus --iface can0 --scan-to 32
 # Expect 7 actuators at ids 11..17
 
-hc bus discover --iface can1 --scan-to 32
+pixi run scan-bus --iface can1 --scan-to 32
 # Expect 7 actuators at ids 21..27
 ```
 
@@ -66,6 +67,7 @@ warnings**, the actuators aren't powered — see
 ## Step 3 — Launch the bringup
 
 ```bash
+pixi shell    # enter the workspace env so ros2 is on PATH
 ros2 launch humanoid_bringup_lite real.launch.py
 ```
 

docs/how_to/mit_slider_gui.md

@@ -54,10 +54,13 @@ This brings up:
 - `zero_torque_controller` (active — safe default)
 - `forward_mit_controller` (loaded, **inactive**)
 
-In a second terminal, open the slider GUI:
+In a second terminal, open the slider GUI. It's a rarely-used tool,
+so it has no pixi task — run the canonical executable (plain
+`ros2 run …` inside a `pixi shell`, or via `pixi run --` from any
+terminal):
 
 ```bash
-hc motor slider
+pixi run -- ros2 run humanoid_devices_robstride mit_slider_gui
 ```
 
 A Qt window appears with five sliders (position, velocity, effort,

docs/how_to/probe_can_bus.md

@@ -39,11 +39,14 @@ and the bus is acking. `ERROR-WARNING` is transient and self-recovers;
 
 ## Scan all IDs on a bus
 
+`scan-bus` is the workspace task wrapping
+`ros2 run humanoid_devices_robstride robstride_discover`; trailing
+args forward verbatim:
+
 ```bash
 cd humanoid_control_ws
-pixi shell
-hc bus discover --iface can0
-hc bus discover --iface can1
+pixi run scan-bus --iface can0
+pixi run scan-bus --iface can1
 ```
 
 Default scan range: 1..32. Sends one `GetDeviceId` per ID with 8 ms
@@ -68,11 +71,11 @@ on `can1` (right arm).
 
 ```bash
 # Default range is 1..32; widen if you suspect IDs outside that.
-hc bus discover --iface can0 \
+pixi run scan-bus --iface can0 \
     --scan-from 1 --scan-to 127
 
 # Tighter scan (faster) if you only want to check specific IDs:
-hc bus discover --iface can0 \
+pixi run scan-bus --iface can0 \
     --scan-from 11 --scan-to 17
 ```
 
@@ -81,7 +84,7 @@ hc bus discover --iface can0 \
 If the bus is slow / cheap-USB-adapter, raise `--per-id-wait-ms`:
 
 ```bash
-hc bus discover --iface can0 \
+pixi run scan-bus --iface can0 \
     --per-id-wait-ms 20
 ```
 
@@ -90,7 +93,7 @@ hc bus discover --iface can0 \
 When you know the ID and want a deeper status check:
 
 ```bash
-hc bus ping --iface can0 --id 11
+pixi run ping-bus --iface can0 --id 11
 # TX  GetDeviceId  id=...
 # RX  GetDeviceId reply  device=11  uid=...
 # stats: rx=1 tx=1 rx_dropped=0 tx_failed=0
@@ -101,11 +104,11 @@ With `--read-status` the ping briefly Enables, prompts an
 responds with calibrated-looking values:
 
 ```bash
-hc bus ping --iface can0 --id 11 --read-status
+pixi run ping-bus --iface can0 --id 11 --read-status
 # RX  OperationStatus  device=11  pos= 4.9200 rad  vel= 0.0  torque= 0.0  temp=24.0 C  fault_bits=0x00
 ```
 
-The `pos` value is **motor-frame, no calibration** (this CLI doesn't
+The `pos` value is **motor-frame, no calibration** (the probe doesn't
 load `calibration.yaml`). It's the raw absolute-encoder reading. If
 it's plausibly in `[-4π, 4π]` and the motor reports temp around room
 temp with `fault_bits=0x00`, the motor is healthy.
@@ -129,7 +132,7 @@ how you confirm `on_deactivate`'s Disable made it through.
 
 ## Common findings
 
-| `hc bus discover` reports | Likely cause |
+| `pixi run scan-bus` reports | Likely cause |
 |---|---|
 | `found : 0 actuator(s)` | Bus down, adapter unplugged, or motors not powered. Check `ip -d link` and the bench power. |
 | `found : N < expected` | Some motors are off the bus. Trace the daisy-chain — usually a connector. |

docs/how_to/recover_from_fault.md

@@ -60,7 +60,7 @@ from.
 
 **Recovery**:
 1. Confirm motors are powered:
-   `hc bus discover --iface canN`
+   `pixi run scan-bus --iface canN`
 2. Confirm wiring — wiggle the daisy chain connector at each motor.
 3. Restart the launch. `RX_TIMEOUT` clears on `on_activate` so a
    relaunch is sufficient; no power-cycle needed.
@@ -90,7 +90,7 @@ generic flag.
    every joint.
 2. If the fault persists, single-step diagnosis:
    ```bash
-   hc bus ping --iface canN --id <X> --read-status
+   pixi run ping-bus --iface canN --id <X> --read-status
    ```
    The reply's `fault_bits` byte tells you which specific sub-cause:
    - `bit 0` = overtemperature (also raised as `FLAG_TEMPERATURE_LIMIT`)