Merge pull request #969 from 916BGAI/nanokvm

docs: update PicoClaw board documentation

docs/hardware/en/lichee/RV_Nano/7_picoclaw_board.md

@@ -10,6 +10,11 @@ update:
 
 ## PicoClaw Expansion Board
 
+<div style="display:flex; gap:12px; justify-content:center; align-items:center; margin: 8px 0 16px;">
+	<img src="./../../../zh/lichee/assets/RV_Nano/picoclaw/rvclaw.jpeg" style="width:60%; height:auto;" alt="rvclaw" />
+	<img src="./../../../zh/lichee/assets/RV_Nano/rvclaw/rvclaw-kit.jpg" style="width:30.5%; height:auto;" alt="rvclaw kit" />
+</div>
+
 The PicoClaw Expansion Board is a feature extension board built for **PicoClaw** interactive applications, based on the **LicheeRV Nano** development board. It is designed for voice interaction and local display scenarios, integrating display, buttons, status LEDs, battery management, and audio peripheral interfaces to quickly build a complete HMI terminal.
 
 The board includes a **240×240 LCD** for system status, recognized text, conversation output, and UI menus. It also provides **2 onboard buttons** for mode switching and confirmation, and **2 LEDs** for power/running/status indication. A **Battery** connector is provided with charging support, with a **maximum charging power of 3W**. Speaker connection for voice playback is also supported.
@@ -25,6 +30,8 @@ Main features of the PicoClaw Expansion Board:
 - Speaker connection and voice output support
 - Real-time conversation and result display (with customized image)
 
+If you want to print the enclosure yourself, download the [PicoClaw Expansion Board enclosure 3D model files](https://dl.sipeed.com/shareURL/LICHEE/LicheeRV_Nano/08_RVClaw).
+
 ### About PicoClaw
 
 <div align="center">
@@ -58,13 +65,13 @@ File name: `picoclaw-rv-nano-YYYYMMDD.img.xz`
 
 - Expansion-board side code in the image is based on Python, located at `/opt/app_picoclaw` (source: [https://github.com/sipeed/rvclaw](https://github.com/sipeed/rvclaw)), which is convenient for custom development.
 
-## Quick Start
+## Quick Start with PicoClaw
 
-### 1. Select an Application
+### Select an Application
 
 After startup, the system enters the application selection screen by default. Press `KEY1` to select the PicoClaw application, or press `KEY2` to select the CC Buddy application. In the PicoClaw application, long-press `KEY2` to return to this application selection screen. CC Buddy is a customized virtual pet application that provides a cute interactive interface and simple conversation features, making it suitable for first-time users to try out.
 
-### 2. Network Connection
+### Connect Wi-Fi
 
 First, access the device console. Recommended methods:
 
@@ -76,9 +83,28 @@ First, access the device console. Recommended methods:
 	<img src="./../../../zh/lichee/assets/RV_Nano/picoclaw/usb_net.jpeg" style="width: 90%; height: auto;" alt="usb network" >
 </div>
 
-Then log in with SSH or serial. Default username/password are both `root`. After login, follow [Peripheral Usage](https://wiki.sipeed.com/hardware/en/lichee/RV_Nano/5_peripheral.html#WIFI) to connect Wi-Fi.
+Then log in with SSH or serial. Default username/password are both `root`.
 
-### 3. Configure PicoClaw
+**After logging in, connect Wi-Fi as follows.**
+
+<details>
+<summary>Connect Wi-Fi</summary>
+
+> ```bash
+> # Create wifi.sta in the first SD-card partition to enable STA mode:
+> touch /boot/wifi.sta && rm -f /boot/wifi.ap /boot/wifi.mon
+>
+> # Then write the AP SSID and password into files:
+> echo ssid > /boot/wifi.ssid
+> echo pass > /boot/wifi.pass
+>
+> # Finally restart the Wi-Fi service
+> /etc/init.d/S30wifi restart
+> ```
+
+</details>
+
+### Configure PicoClaw
 
 On first boot, PicoClaw is not initialized yet. You need initial configuration first. You can use Web UI or TUI. The following uses Web UI.
 
@@ -139,6 +165,178 @@ After saving, press and hold the left `KEY1` button on the expansion board to re
 	</div>
 </div>
 
+## CC Buddy Application
+
+### About CC Buddy
+
+<div align="center">
+	<img src="./../../../zh/lichee/assets/RV_Nano/rvclaw/cc_buddy_hero.jpg" style="width: 90%; height: auto;" alt="📷 cc buddy hero" >
+</div>
+
+**CC Buddy** is another application built into the PicoClaw Expansion Board image. It is positioned as a **companion device for Claude Code**. It turns Claude Code activity into a cute virtual pet (ASCII Pet), and moves **permission approval requests** generated by Claude Code tool or command execution from the computer to the LicheeRV Nano screen. You can approve or deny requests directly with the device buttons, and the decision is sent back to Claude Code, so you do not need to switch back to the computer window.
+
+CC Buddy is ported from Felix Rieseberg's [claude-desktop-buddy](https://github.com/anthropics/claude-desktop-buddy) project, with dedicated adaptations for LicheeRV Nano + PicoClaw Expansion Board: 240×240 ST7789 display, KEY1(A)/KEY2(B) buttons, onboard LEDs, and more. The source code is located at `/opt/app_cc_buddy` in the system image.
+
+Core design ideas:
+
+- **Embodied feedback**: Map Claude Code states (idle, busy, waiting for approval, task completed, etc.) to pet emotions and actions, making invisible Agent behavior visible.
+- **Nearby approval**: Permission requests are pushed to the device screen. Press A/B to approve or deny directly, reducing context switching.
+- **CLI bridge**: Uses Claude Code's official Hook mechanism plus a local daemon to bridge events to the device TCP port, without modifying Claude Code itself.
+
+### Main Features
+
+- Display an ASCII pixel-style pet on the 240×240 LCD (`capybara`, `cat`, and `robot` are provided by default and can be switched in settings)
+- Show Claude Code session status in real time: total sessions, running, waiting, token usage, and latest command/output line
+- Permission approval dialog: shows tool name, prompt message, and waiting time, with highlight after 10 seconds
+- Pet growth system: calculates mood, fed, and energy from approval speed, denial count, and token usage; accumulated tokens trigger level-up animation
+- Multiple display modes: HUD (script/transcript), INFO (device/network/statistics), PET (pet status page), CLOCK (shown when no Claude connection exists)
+- Optional LED status blinking, auto screen sleep after 30 seconds of inactivity, and sound feedback (configurable in settings)
+- One-click switch back to the PicoClaw application from the app menu without rebooting
+
+<div style="display:flex; gap:10px; justify-content:center; margin: 8px 0 16px;">
+	<img src="./../../../zh/lichee/assets/RV_Nano/rvclaw/cc_buddy_mode_hud.jpg" alt="📷 cc buddy hud mode" style="width:23%; min-width:160px; height:auto; border:1px solid #e5e7eb; border-radius:6px; box-shadow:0 2px 8px rgba(0,0,0,.1);" />
+	<img src="./../../../zh/lichee/assets/RV_Nano/rvclaw/cc_buddy_mode_info_P4.jpg" alt="📷 cc buddy info mode" style="width:23%; min-width:160px; height:auto; border:1px solid #e5e7eb; border-radius:6px; box-shadow:0 2px 8px rgba(0,0,0,.1);" />
+	<img src="./../../../zh/lichee/assets/RV_Nano/rvclaw/cc_buddy_mode_pet_P1.jpg" alt="📷 cc buddy pet mode" style="width:23%; min-width:160px; height:auto; border:1px solid #e5e7eb; border-radius:6px; box-shadow:0 2px 8px rgba(0,0,0,.1);" />
+	<img src="./../../../zh/lichee/assets/RV_Nano/rvclaw/cc_buddy_mode_clock_species_capybara.jpg" alt="📷 cc buddy clock mode" style="width:23%; min-width:160px; height:auto; border:1px solid #e5e7eb; border-radius:6px; box-shadow:0 2px 8px rgba(0,0,0,.1);" />
+</div>
+
+<details>
+<summary>Full Mode</summary>
+
+<div style="display:flex; gap:10px; justify-content:center; margin: 8px 0 16px;">
+	<img src="./../../../zh/lichee/assets/RV_Nano/rvclaw/cc_buddy_mode_pet_P1.jpg" alt="📷 cc buddy pet mode P1" style="width:48%; min-width:160px; height:auto; border:1px solid #e5e7eb; border-radius:6px; box-shadow:0 2px 8px rgba(0,0,0,.1);" />
+	<img src="./../../../zh/lichee/assets/RV_Nano/rvclaw/cc_buddy_mode_pet_P2.jpg" alt="📷 cc buddy pet mode P2" style="width:48%; min-width:160px; height:auto; border:1px solid #e5e7eb; border-radius:6px; box-shadow:0 2px 8px rgba(0,0,0,.1);" />
+</div>
+
+<div style="display:flex; gap:10px; justify-content:center; margin: 8px 0 16px;">
+	<img src="./../../../zh/lichee/assets/RV_Nano/rvclaw/cc_buddy_mode_info_P1.jpg" alt="📷 cc buddy info mode P1" style="width:31%; min-width:160px; height:auto; border:1px solid #e5e7eb; border-radius:6px; box-shadow:0 2px 8px rgba(0,0,0,.1);" />
+	<img src="./../../../zh/lichee/assets/RV_Nano/rvclaw/cc_buddy_mode_info_P2.jpg" alt="📷 cc buddy info mode P2" style="width:31%; min-width:160px; height:auto; border:1px solid #e5e7eb; border-radius:6px; box-shadow:0 2px 8px rgba(0,0,0,.1);" />
+	<img src="./../../../zh/lichee/assets/RV_Nano/rvclaw/cc_buddy_mode_info_P3.jpg" alt="📷 cc buddy info mode P3" style="width:31%; min-width:160px; height:auto; border:1px solid #e5e7eb; border-radius:6px; box-shadow:0 2px 8px rgba(0,0,0,.1);" />
+</div>
+
+<div style="display:flex; gap:10px; justify-content:center; margin: 8px 0 16px;">
+	<img src="./../../../zh/lichee/assets/RV_Nano/rvclaw/cc_buddy_mode_info_P4.jpg" alt="📷 cc buddy info mode P4" style="width:31%; min-width:160px; height:auto; border:1px solid #e5e7eb; border-radius:6px; box-shadow:0 2px 8px rgba(0,0,0,.1);" />
+	<img src="./../../../zh/lichee/assets/RV_Nano/rvclaw/cc_buddy_mode_info_P5.jpg" alt="📷 cc buddy info mode P5" style="width:31%; min-width:160px; height:auto; border:1px solid #e5e7eb; border-radius:6px; box-shadow:0 2px 8px rgba(0,0,0,.1);" />
+	<img src="./../../../zh/lichee/assets/RV_Nano/rvclaw/cc_buddy_mode_info_P6.jpg" alt="📷 cc buddy info mode P6" style="width:31%; min-width:160px; height:auto; border:1px solid #e5e7eb; border-radius:6px; box-shadow:0 2px 8px rgba(0,0,0,.1);" />
+</div>
+</details>
+
+### Connection Method
+
+CC Buddy communicates with the device through **Claude Code CLI (Hooks + Daemon)**.
+
+It is intended for users who use the `claude` terminal command. A daemon runs on the computer and bridges Claude Code Hook events to the device TCP port.
+
+```
+Claude Code CLI (sessions)
+		│ HTTP hooks (automatically injected into ~/.claude/settings.json)
+		▼
+cc_buddy_daemon.py (default :9876)
+		│ TCP
+		▼
+RVClaw device (:19000)
+```
+
+Start the daemon on the computer ([download script here](https://raw.githubusercontent.com/sipeed/rvclaw/refs/heads/main/app_cc_buddy/hooks/cc_buddy_daemon.py)):
+
+```bash
+python3 cc_buddy_daemon.py --device <RVCLAW_IP>
+# Custom port
+python3 cc_buddy_daemon.py --device <RVCLAW_IP> --port 9877
+```
+
+After startup, the daemon automatically:
+
+- Writes the following Hooks into `~/.claude/settings.json`, and automatically cleans them up on exit (Ctrl+C / SIGTERM)
+- Listens on `http://127.0.0.1:9876` for Claude Code Hook events
+- Connects to the RVClaw `19000` TCP port to send heartbeats and receive button decisions
+
+| Hook | Purpose |
+| --- | --- |
+| SessionStart / SessionEnd | Maintain active session count |
+| PreToolUse | Mark running state and build command transcript |
+| PostToolUse | Clear running state |
+| Stop | Mark session generation completed |
+| **PermissionRequest** | **Block** and wait for device button decision (default timeout: 30s) |
+| PermissionDenied | Clear waiting state |
+| PreCompact | Sync token count |
+
+Then use `claude` normally. When Claude needs permission, the device switches to the approval page. Press **A to approve / B to deny**, and the daemon sends the decision back to Claude Code.
+
+<div align="center">
+	<img src="./../../../zh/lichee/assets/RV_Nano/rvclaw/cc_buddy_approval.jpg" style="width: 60%; height: auto; border: 1px solid #e5e7eb; border-radius: 4px; box-shadow: 0 2px 8px rgba(0,0,0,0.1);" alt="📷 cc buddy approval" >
+</div>
+
+### Button Operations
+
+CC Buddy reuses the two buttons for multiple functions. Behavior changes with the current UI:
+
+| Operation | A (left) | B (right) |
+| --- | --- | --- |
+| Short press on main screen | Switch display mode (NORMAL / PET / INFO) | Turn pages in INFO/PET pages; scroll transcript in HUD mode |
+| Long press (≥ 600ms) | Open main menu (settings / help / about / demo / to picoclaw / close) | — |
+| Approval page | **Approve** (once) | **Deny** (deny) |
+| Menu/settings opened | Move selection | Confirm/trigger selected item |
+| Screen sleeping | Wake screen (first press does not trigger function) | Wake screen (first press does not trigger function) |
+
+> Select `to picoclaw` in the main menu to switch back to the PicoClaw application without rebooting. The CC Buddy service stops and the PicoClaw service starts.
+
+### Settings and Persistence
+
+<div style="display:flex; gap:10px; justify-content:center; margin: 8px 0 16px;">
+	<img src="./../../../zh/lichee/assets/RV_Nano/rvclaw/cc_buddy_menu.jpg" alt="📷 cc buddy menu" style="width:45%; min-width:200px; height:auto; border:1px solid #e5e7eb; border-radius:6px; box-shadow:0 2px 8px rgba(0,0,0,.1);" />
+	<img src="./../../../zh/lichee/assets/RV_Nano/rvclaw/cc_buddy_settings.jpg" alt="📷 cc buddy settings" style="width:45%; min-width:200px; height:auto; border:1px solid #e5e7eb; border-radius:6px; box-shadow:0 2px 8px rgba(0,0,0,.1);" />
+</div>
+
+Go to `main menu → settings` to configure:
+
+| Setting | Description | Values |
+| --- | --- | --- |
+| brightness | Display brightness level | 0–4 |
+| sound | Sound feedback switch | on / off |
+| led | Status LED switch (blinks while waiting for approval) | on / off |
+| transcript | HUD transcript display switch | on / off |
+| ascii pet | Pet species selection | capybara / cat / robot |
+| sleep | Auto screen sleep after 30s of inactivity | on / off |
+| reset stats | Clear growth data and restore defaults | — |
+
+Device data is persisted in `/root/.cc_buddy/`:
+
+- `stats.json`: level, accumulated tokens, approve/deny counters, pet species index, owner/pet names, etc.
+- `settings.json`: the settings above
+
+### Pet Growth Rules
+
+<div style="display:flex; gap:10px; justify-content:center; margin: 8px 0 16px;">
+	<img src="./../../../zh/lichee/assets/RV_Nano/rvclaw/cc_buddy_mode_clock_species_capybara.jpg" alt="📷 cc buddy capybara" style="width:30%; min-width:160px; height:auto; border:1px solid #e5e7eb; border-radius:6px; box-shadow:0 2px 8px rgba(0,0,0,.1);" />
+	<img src="./../../../zh/lichee/assets/RV_Nano/rvclaw/cc_buddy_mode_clock_species_cat.jpg" alt="📷 cc buddy cat" style="width:30%; min-width:160px; height:auto; border:1px solid #e5e7eb; border-radius:6px; box-shadow:0 2px 8px rgba(0,0,0,.1);" />
+	<img src="./../../../zh/lichee/assets/RV_Nano/rvclaw/cc_buddy_mode_clock_species_robot.jpg" alt="📷 cc buddy robot" style="width:30%; min-width:160px; height:auto; border:1px solid #e5e7eb; border-radius:6px; box-shadow:0 2px 8px rgba(0,0,0,.1);" />
+</div>
+
+- **MOOD**: Faster approval means higher mood (< 5s triggers a one-time `HEART` animation); frequent denials reduce mood.
+- **FED**: Levels up about every 50K accumulated tokens and plays the `CELEBRATE` animation.
+- **ENERGY**: Designed to recover after placing the screen face-down for a nap (currently unsupported).
+- **State mapping**: disconnected → IDLE; waiting for approval → ATTENTION (with LED blinking); ≥ 3 sessions running → BUSY; recently completed → CELEBRATE; late night (1:00–7:00) without Claude connection → SLEEP (clock mode).
+
+### Custom Development
+
+Development repository: [GitHub app_cc_buddy](https://github.com/sipeed/rvclaw/tree/main/app_cc_buddy).
+CC Buddy is written entirely in Python with a clear directory structure:
+
+| File | Purpose |
+| --- | --- |
+| `main.py` | Main event loop, button dispatch, state switching, display refresh |
+| `config.py` | Pin definitions, SPI parameters, font paths, UI layout constants |
+| `ui.py` | Draws splash screen, HUD, approval page, Info/Pet/Clock/Menu/Settings pages |
+| `buddy.py` + `buddies/*.py` | Pet renderers (capybara, cat, and robot registered by default) |
+| `state.py` | Data structures such as `TamaState`, `PersonaState`, and `DisplayMode` |
+| `protocol.py` | JSON heartbeat/command parsing and permission-response packaging |
+| `transport.py` | TCP communication implementation on port 19000 |
+| `hooks/cc_buddy_daemon.py` | Host-side Hook bridge daemon |
+| `S99cc_buddy_app` | Boot startup script |
+
+To add a custom pet species, create a species file under `buddies/` and register it with `register_species()` in `buddies/__init__.py`.
+
 ## FAQ
 
 - Errors during conversation

docs/hardware/zh/lichee/RV_Nano/7_picoclaw_board.md

@@ -8,12 +8,13 @@ update:
       - First version
 ---
 
-[*模型文件于此下载*](https://dl.sipeed.com/shareURL/LICHEE/LicheeRV_Nano/08_RVClaw)
-![rvclaw-kit-jpg](../../../zh/lichee/assets/RV_Nano/rvclaw/rvclaw-kit.jpg)
-
-
 ## PicoClaw 扩展板
 
+<div style="display:flex; gap:12px; justify-content:center; align-items:center; margin: 8px 0 16px;">
+  <img src="../../../zh/lichee/assets/RV_Nano/picoclaw/rvclaw.jpeg" style="width:60%; height:auto;" alt="rvclaw" />
+  <img src="../../../zh/lichee/assets/RV_Nano/rvclaw/rvclaw-kit.jpg" style="width:30.5%; height:auto;" alt="rvclaw kit" />
+</div>
+
 PicoClaw 扩展板是一款为 **PicoClaw** 交互应用打造、基于 **LicheeRV Nano** 开发板的功能扩展板，面向语音交互与本地显示场景，集成显示、按键、指示灯、电池管理与音频外设接口，便于快速搭建完整的人机交互终端。
 
 扩展板搭载一块 **240×240 LCD 屏幕**，可用于展示系统状态、识别文本、对话结果与交互菜单；板载 **2 个按键**，用于模式切换、功能确认等操作；板载 **2 个 LED 灯**，用于电源、运行与状态提示。扩展板提供 **Battery 电池接口**，支持充电，**最大充电功率为 3W**。同时支持连接喇叭实现语音播放。
@@ -29,6 +30,8 @@ PicoClaw 扩展板的主要功能包括：
 - 支持喇叭连接与语音输出
 - 支持实时对话与结果显示（需配合定制镜像）
 
+如需自行打印外壳，可在此下载 [PicoClaw 扩展板外壳 3D 模型文件](https://dl.sipeed.com/shareURL/LICHEE/LicheeRV_Nano/08_RVClaw)。
+
 ### PicoClaw 介绍
 
 <div align="center">