feat(uno-q): ship the arduino-uno-q expert skill on every node by default

Vendors the comprehensive UNO Q skill (SKILL.md + 7 references/*.md) and installs it into EVERY agent's workspace on each board, so agents know this board's specifics (dual-brain arch, Bridge/RPC, pin tables, LED matrix + the ArduinoGraphics-not-installed gotcha) instead of guessing generic Arduino. Why per-agent workspace: ZeroClaw's read_skill returns only SKILL.md; the agent reads references/*.md via the workspace-sandboxed file_read tool, so references are only reachable under ~/.zeroclaw/agents/<alias>/workspace/skills/. A shared/skills bundle surfaces the skill but its references get sandbox-blocked. - push-skill.sh installs a SKILL.md+references skill into every agent workspace (discovers aliases from the board); provision-fleet runs it per board. - config.template risk profile now allows + auto-approves read_skill + file_read so agents load skills without a human approver (webhook path is non-interactive). - Flattened the folded 'description: >-' to single-line (ZeroClaw's frontmatter parser is a flat scanner, not full YAML). Verified on board 65301572 with cloud/Sonnet-5: discovered arduino-uno-q → read_skill(SKILL.md) → file_read references/04-bridge-rpc.md → correct board-specific answer citing the file. Co-Authored-By: Claude Opus 4.8 <[email protected]>
2026-07-16 09:14:00 -07:00
parent 7233a4b1c0
commit d2135a1938
12 changed files with 877 additions and 2 deletions
@@ -0,0 +1,67 @@
+# UNO Q — Remote & Headless Access
+
+The Linux side is a real networked computer, so you can work with the board without a monitor. Three complementary paths: **Network Mode** (App Lab GUI over LAN), **SSH** (terminal), and **`adb`** (over USB). For a workshop where students use their own laptops, combine Network Mode for the GUI and SSH for the terminal.
+
+## Prerequisite: get the board on the network
+The board must be on Wi-Fi (or Ethernet via dongle) and you need either its **IP** or its **mDNS hostname**. SSH is **enabled automatically** during the App Lab first-run setup once you configure a username, password, and Wi-Fi.
+
+## Find the board's IP address
+Open a terminal on the board (App Lab bottom-left `>_` icon, or a desktop terminal) and run:
+```bash
+ip addr show
+```
+Look under the **`wlan0`** interface (or `eth0` if using Ethernet) for the `inet` address.
+
+## Network Mode (App Lab over the LAN)
+- Run App Lab on your PC; boards discovered on the local network appear tagged **"Network."** Select yours and enter credentials — you now develop from your PC as if local.
+- Discovery uses **mDNS** (Bonjour/zeroconf). The board advertises `<board-name>.local`.
+- **Firewall/OS notes:**
+  - Allow **UDP port 5353** (mDNS) through the firewall.
+  - On Windows, approve the `mdns-discovery.exe` prompt from Windows Defender.
+  - Reaching the board directly by browser, SSH, or raw IP does **not** guarantee it shows up in Network Mode — mDNS must be working for the App Lab discovery.
+
+## SSH (terminal access)
+Default Linux user is **`arduino`**. Connect with either the IP or the mDNS name:
+```bash
+ssh arduino@<BOARD_IP>          # e.g. ssh [email protected]
+ssh arduino@<board-name>.local  # if mDNS resolves on your network
+```
+On first connect, accept the host-key fingerprint (`yes`) and enter the board password you set during setup.
+
+For passwordless login, install your key the standard way:
+```bash
+ssh-copy-id arduino@<BOARD_IP>
+```
+(or append your public key to `~/.ssh/authorized_keys` on the board). After that, `ssh arduino@<BOARD_IP>` won't prompt for a password.
+
+Once in over SSH you have the full board: `apt`, `systemctl` (e.g. manage `arduino-router`), the `arduino-app-cli`, the LED sysfs, etc.
+
+## Copy files to the board
+Use `scp` (or `rsync`) from your PC. Apps live in `~/ArduinoApps/` on the board:
+```bash
+mkdir -p ~/ArduinoApps/<project-name>              # (run on the board)
+scp -r * arduino@<BOARD_IP>:~/ArduinoApps/<project-name>   # (run on your PC, from the project dir)
+```
+Then start/stop it remotely with the CLI (see setup reference):
+```bash
+arduino-app-cli app start ~/ArduinoApps/<project-name>
+arduino-app-cli app logs  ~/ArduinoApps/<project-name>
+arduino-app-cli app stop  ~/ArduinoApps/<project-name>
+```
+
+## `adb` (over USB, no network needed)
+With the Linux host udev rules installed (see setup reference), the board also speaks `adb`:
+```bash
+adb devices     # confirm the board is attached
+adb shell       # shell into the board over USB
+```
+Handy when Wi-Fi isn't configured yet, for first-time provisioning, or for recovery.
+
+## Hardware serial console (last resort)
+If the board won't boot or has no network, the **JCTL** debug UART gives the raw SoC console at **115200 bps, 1.8 V logic** (use a 1.8 V USB-TTL adapter — see hardware reference). It shows bootloader/kernel messages and offers a login prompt with your Linux credentials.
+
+## Picking the right one
+- **GUI development from your laptop** → Network Mode.
+- **Scripting, service management, autostart, file transfer, headless control** → SSH (+ `scp`, `arduino-app-cli`).
+- **No network yet / provisioning / recovery** → `adb` over USB.
+- **Won't boot / diagnosing early startup** → 1.8 V hardware debug UART.