@rainbow-robotics/muscat-plugin-kit 1.10.3-dev.0 → 1.10.3-dev.3

package/README.md

@@ -1,50 +1,57 @@
 # @rainbow-robotics/muscat-plugin-kit
 
-CLI for developing Muscat plugins. Provides scaffolding, build/pack, and dev servers (UI + backend).
+CLI for developing Muscat plugins (`muscat-pk`): scaffolding, dev servers (UI + backend), build/pack, and the SDK references a plugin author needs.
+
+[한국어 문서 (README.ko.md)](./README.ko.md)
+
+## Contents
+
+1. [Install](#1-install)
+2. [Quick start](#2-quick-start)
+3. [Commands](#3-commands)
+4. [Project layout](#4-project-layout)
+5. [manifest.json](#5-manifestjson)
+6. [Plugin UI SDK (`useRb`)](#6-plugin-ui-sdk-userb)
+7. [Python plugin SDK](#7-python-plugin-sdk)
+8. [Other backend runtimes (C++ / ROS 2)](#8-other-backend-runtimes-c--ros-2)
+9. [Development environment](#9-development-environment)
+10. [Styles](#10-styles)
+11. [AI coding agent setup (`muscat-pk mcp`)](#11-ai-coding-agent-setup-muscat-pk-mcp)
+12. [Environment variables](#12-environment-variables)
+13. [Troubleshooting](#13-troubleshooting)
 
-## Install
-
-### Option 1 — npm (requires Node.js 20+)
+---
 
-```bash
-# latest stable
-npm install -g @rainbow-robotics/muscat-plugin-kit
+## 1. Install
 
-# dev channel (latest dev build)
-npm install -g @rainbow-robotics/muscat-plugin-kit@dev
+### npm (Node.js 20+)
 
-# specific version
-npm install -g @rainbow-robotics/muscat-plugin-kit@1.2.3
+```bash
+npm install -g @rainbow-robotics/muscat-plugin-kit          # latest stable
+npm install -g @rainbow-robotics/muscat-plugin-kit@dev      # dev channel
+npm install -g @rainbow-robotics/muscat-plugin-kit@1.2.3    # specific version
 ```
 
-### Option 2 — S3 install script (no Node.js required)
+### Install script (no Node.js required)
 
 macOS / Linux / WSL:
 
 ```bash
-# latest stable
 curl -fsSL https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/install.sh | sh
-
-# dev channel
 curl -fsSL https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/install.sh | MUSCAT_PK_TAG=dev sh
-
-# specific version
 curl -fsSL https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/install.sh | MUSCAT_PK_TAG=1.2.3 sh
 ```
 
 Windows PowerShell:
 
 ```powershell
-# latest stable
 irm https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/install.ps1 | iex
-
-# dev channel
 $env:MUSCAT_PK_TAG="dev"; irm https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/install.ps1 | iex
 ```
 
-> The install script uses npm when Node.js 20+ is present, otherwise it downloads a self-contained binary from S3.
+The script uses npm when Node.js 20+ is present, otherwise it downloads a self-contained binary.
 
-### Option 3 — direct binary download
+### Direct binary download
 
 ```
 https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/v{version}/{binary}
@@ -59,129 +66,317 @@ https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/dev/{bi
 | macOS x64 | `muscat-pk-darwin-x64` |
 | Windows x64 | `muscat-pk-win-x64.exe` |
 
-Channel pointers:
+Channel pointers: `.../muscat-plugin-kit/latest-version.txt` (stable), `.../muscat-plugin-kit/dev-version.txt` (dev).
 
-```
-# latest stable version string
-https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/latest-version.txt
+### Requirements
 
-# latest dev version string
-https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/dev-version.txt
-```
+| Tool | Needed for |
+|---|---|
+| Node.js 20+ (or the binary) | the CLI, UI build |
+| Docker | every backend runtime except `none` (`dev:back`, `dev`, `build`) |
+| `uv` or Python 3.12 (optional) | IDE-only `.venv` for Python linting |
 
 ### Uninstall
 
-Regardless of how it was installed, `muscat-pk` can remove itself:
-
 ```bash
-muscat-pk uninstall
+muscat-pk uninstall                                     # works for npm and binary installs
+npm uninstall -g @rainbow-robotics/muscat-plugin-kit    # manual, npm
+sudo rm -f /usr/local/bin/muscat-pk                     # manual, binary
 ```
 
-Manual removal:
+---
 
-```bash
-# if installed via npm
-npm uninstall -g @rainbow-robotics/muscat-plugin-kit
+## 2. Quick start
 
-# if installed via the S3 binary (default macOS/Linux path)
-sudo rm -f /usr/local/bin/muscat-pk
+```bash
+muscat-pk new my-plugin     # scaffold (asks author, email, description, type, package manager)
+cd my-plugin
+muscat-pk dev               # UI preview + backend together
+muscat-pk build             # dist/ + distributable ZIP
 ```
 
+Install the ZIP from the robot's Muscat plugin page.
+
 ---
 
-## Quick start
+## 3. Commands
+
+| Command | Description |
+|---|---|
+| `muscat-pk new [dir]` | Scaffold a plugin project |
+| `muscat-pk type change` | Switch the backend type |
+| `muscat-pk dev` | Local Muscat runtime + `dev:ui` + `dev:back` |
+| `muscat-pk dev:ui` | UI preview in a mini-Muscat (preview-host) |
+| `muscat-pk dev:back` | Backend only, in Docker, with hot reload |
+| `muscat-pk build` | Build, lock Python deps, vendor wheels, ZIP |
+| `muscat-pk update` | Update the kit, `plugin-ui` and `preview-host` |
+| `muscat-pk sdk <list\|update [version]>` | Manage the `rainbow-rb-sdk` version |
+| `muscat-pk storybook` | Browse the bundled rb-components Storybook |
+| `muscat-pk mcp` | MCP server for AI coding agents |
+| `muscat-pk uninstall` | Remove the CLI |
+| `muscat-pk version` | Print the running version (`-v`, `--version`) |
+| `muscat-pk completion [shell]` | Print a shell completion script |
+
+`muscat-pk <command> --help` prints the options of a command.
+
+### 3.1 `new`
 
 ```bash
-muscat-pk new my-plugin        # scaffold a plugin project (choose python / cpp / ros2 / ros2-cpp)
-cd my-plugin
+muscat-pk new [dir] [--type python|cpp|ros2|ros2-cpp] [--pm npm|yarn|pnpm|bun]
+                    [--author <name>] [--email <email>] [--description <text>]
+                    [--yes] [--no-install]
+```
+
+| Option | Meaning |
+|---|---|
+| `dir` | target directory (must be empty); asked when omitted |
+| `--type` | backend type: `python` (default), `cpp`, `ros2` (rclpy), `ros2-cpp` (rclcpp) |
+| `--pm` | front-end package manager; defaults to `yarn` inside a Yarn workspace, else `npm` |
+| `--author` / `--email` / `--description` | manifest fields (email is required by the manifest) |
+| `--yes` | no prompts; unspecified values use defaults |
+| `--no-install` | skip `npm install` |
+
+Python projects also get an IDE-only `.venv` (see [9.6](#96-ide-support-python)).
 
-muscat-pk dev                  # run UI + backend together
-muscat-pk dev:ui               # UI preview only
-muscat-pk dev:back             # backend only (Docker: python/cpp/ros2)
+### 3.2 `type change`
 
-muscat-pk build                # build dist/ and produce a distributable ZIP (skip the ZIP with --no-zip)
+```bash
+muscat-pk type change [--to python|cpp|ros2|ros2-cpp] [--readme]
 ```
 
-## Command list
+Rewrites `manifest.json` → `runtime` and adds the new backend's files. Files of the old type (`cpp/`, `ros2_ws/`, …) are left in place. `--readme` also replaces the README with the new type's.
 
-| Command | Description |
+### 3.3 `dev`, `dev:ui`, `dev:back`
+
+```bash
+muscat-pk dev        [--robot-ip <ip>] [--keep-id]
+muscat-pk dev:ui     [--robot-ip <ip>] [--port <n>] [--keep-id]
+muscat-pk dev:back   [--keep-id]
+```
+
+| Command | What runs |
 |---|---|
-| `muscat-pk new [dir]` | Scaffold a plugin project (also creates an IDE-only python `.venv`) |
-| `muscat-pk type change` | Switch backend type (`python` / `cpp` / `ros2` / `ros2-cpp`) |
-| `muscat-pk build` | Build `ui/*.tsx` → `dist/*.js` (one per `contributes[].ui` entry in the manifest) and produce a distributable ZIP |
-| `muscat-pk dev` | UI + backend dev server together |
-| `muscat-pk dev:ui` | Mini-Muscat preview server |
-| `muscat-pk dev:back` | Backend dev server (Docker, hot-reload) |
-| `muscat-pk storybook` | Browse the bundled rb-components Storybook |
-| `muscat-pk mcp` | Run an MCP server for AI coding agents (exposes rb-components/design-token/SDK docs) |
-| `muscat-pk update` | Update the kit + plugin-ui + preview-host to the latest version; lists old-API UI code to fix |
-| `muscat-pk sdk <list\|update>` | Manage the `rainbow-rb-sdk` version — python: `requirements.txt`, C++ (cpp / ros2-cpp): `find_package(rb_sdk <ver> EXACT REQUIRED)` in `CMakeLists.txt` |
-| `muscat-pk version` | Print the installed CLI version (`-v` / `--version` also work) |
-| `muscat-pk completion [shell]` | Print a shell completion script (`bash` / `zsh` / `fish` / `powershell`; defaults to `$SHELL`) |
+| `dev` | a local Muscat runtime when no robot is given, then `dev:ui` and `dev:back` |
+| `dev:ui` | the plugin's Vite dev server + preview-host at `http://localhost:4180/plugin-dev` (next free port) |
+| `dev:back` | the backend in a Docker container matching the robot. Python restarts on `py/**/*.py` changes (watchfiles) |
 
-### Update policy
+- Robot IP comes from `--robot-ip`, `MUSCAT_ROBOT_HOST`, or a prompt (leave blank for local).
+- Against a remote robot the plugin runs under a dev id (see [9.3](#93-several-developers-on-one-robot)); `--keep-id` uses the manifest id.
+- The manifest is validated before start; undeclared listening ports stop the backend (see [5.6](#56-ports)).
 
-`muscat-pk` can be installed globally (npm `-g` or the S3 binary) and/or per
-plugin project (`node_modules`). Two rules keep those from drifting apart:
+### 3.4 `build`
+
+```bash
+muscat-pk build [--arch amd64|arm64|both]
+```
 
-**The project's local install wins.** When you run `muscat-pk` inside a plugin
-project that has its own install, the CLI hands off to that copy. So the CLI,
-the `vite` preset your `vite.config.ts` imports, and the `preview-host` that
-`dev:ui` launches are always the single version the project pinned — a global
-CLI that is newer or older than the project can't half-apply itself.
+Steps:
 
-**`update` only touches what you're in.**
+1. Asks for a new `manifest.json` version (blank keeps the current one).
+2. Validates the manifest.
+3. `vite build` of every `contributes[].ui` entry → `dist/<entry>.js`.
+4. Backend:
+   - python: pins unpinned lines of `requirements.txt` to the latest PyPI version, writes `dist/requirements.lock` (`uv pip compile`), and vendors wheels into `dist/wheels/` per arch.
+   - cpp: CMake build in Docker → `dist/<arch>/<entry>` plus `dist/<arch>/lib/librb_sdk.so`.
+   - ros2: colcon build in Docker → `dist/ros2_ws/install-<arch>/`.
+5. Packs `dist/` into `<project dir>-<version>.zip` in the project root.
 
-| Where you run it | What it updates |
+| Option | Meaning |
 |---|---|
-| Inside a project with a local install | that project's `muscat-plugin-kit` + `plugin-ui` only |
-| Same, with `--global` | the above, plus the global CLI |
-| Anywhere else | the global CLI (and local deps if you're in a project) |
+| `--arch` | target arch; asked in a TTY, `both` otherwise |
+
+### 3.5 `update`
 
 ```bash
-muscat-pk update            # this project only
+muscat-pk update            # this project only (when it has a local install)
 muscat-pk update --global   # this project + the global CLI
-muscat-pk update dev        # follow the dev channel instead of latest
-muscat-pk version           # which version is actually running here
+muscat-pk update dev        # follow the dev channel
 ```
 
-`dev:ui` also prints a one-line notice when a newer version is published. It is
-skipped by `MUSCAT_PK_NO_UPDATE_CHECK=1` and fails silently offline.
-
-### Offline / air-gapped use
+| Where you run it | What it updates |
+|---|---|
+| Inside a project with a local install | that project's `muscat-plugin-kit` + `plugin-ui` |
+| Same, with `--global` | the above + the global CLI |
+| Anywhere else | the global CLI (and local deps if inside a project) |
 
-Docker images are only built when they are missing. `docker build` contacts the
-registry to resolve the base image tag on every run — even when every layer is
-cached — so rebuilding an image you already have would break `dev` with no
-network. Once an image exists locally, `muscat-pk` skips the build entirely.
+After updating it lists UI code that still uses removed APIs. Fix them (or run `check_project` through `muscat-pk mcp`).
 
-Move images to a machine with no internet:
+### 3.6 `sdk`
 
 ```bash
-# on a machine with network
-docker save muscat-pk-python-dev muscat-pk-runtime | gzip > muscat-pk-images.tar.gz
-
-# on the offline machine
-gunzip -c muscat-pk-images.tar.gz | docker load
+muscat-pk sdk list               # published rainbow-rb-sdk versions
+muscat-pk sdk update [version]   # latest when omitted
 ```
 
-Force a rebuild with `MUSCAT_PK_REBUILD_IMAGE=1`.
+- python: rewrites every `rainbow-rb-*==` pin in `requirements.txt` together (they pin each other exactly).
+- C++ (`cpp`, `ros2-cpp`): rewrites `find_package(rb_sdk <ver> EXACT REQUIRED)` in `CMakeLists.txt`.
+
+### 3.7 `storybook`, `mcp`, `completion`, `version`
 
-### Shell completion
+```bash
+muscat-pk storybook [--port 6007] [--rebuild]
+muscat-pk mcp [--install codex]
+muscat-pk completion [bash|zsh|fish|powershell]
+muscat-pk version
+```
+
+`completion` prints a Tab-completion script for your shell — once registered, `muscat-pk d<Tab>` offers `dev`, `dev:ui`, `dev:back`. It only prints the script; append it to your shell's rc file as below. `[shell]` is `bash`, `zsh`, `fish` or `powershell`, defaulting to `$SHELL`. Windows `cmd.exe` has no completion hook — use PowerShell, Git Bash or WSL. Optional convenience; nothing depends on it.
 
-| OS / shell | Command |
+| OS / shell | Completion setup |
 |---|---|
 | macOS (zsh) | `muscat-pk completion zsh >> ~/.zshrc && source ~/.zshrc` |
 | Linux (bash) | `muscat-pk completion bash >> ~/.bashrc && source ~/.bashrc` |
 | fish | `muscat-pk completion fish > ~/.config/fish/completions/muscat-pk.fish` |
-| Windows (PowerShell) | `muscat-pk completion powershell >> $PROFILE; . $PROFILE` |
+| PowerShell | `muscat-pk completion powershell >> $PROFILE; . $PROFILE` |
+
+---
+
+## 4. Project layout
+
+```
+my-plugin/
+├─ ui/
+│   ├─ content.tsx      # UI entry (one file per contributes[].ui), `export default App`
+│   └─ style.css        # auto-loaded for every entry
+├─ py/main.py           # python backend entry (runtime.entry)
+├─ cpp/                 # cpp backend (CMake)            — cpp type
+├─ ros2_ws/             # colcon workspace               — ros2 / ros2-cpp type
+├─ assets/icon.svg
+├─ manifest.json
+├─ requirements.txt     # python deps (pinned on build)
+├─ package.json         # UI deps (not shipped)
+├─ vite.config.ts       # must use the muscat() preset
+└─ README.md            # copied into dist/
+```
 
-Windows `cmd.exe` has no completion mechanism to hook into — use PowerShell, Git Bash, or WSL.
+`vite.config.ts`:
 
-## Backend port policy
+```ts
+import { defineConfig } from "vite";
+import tailwindcss from "@tailwindcss/vite";
+import { muscat } from "@rainbow-robotics/muscat-plugin-kit/vite";
 
-A plugin backend that opens a TCP listener must declare every such port in
-`manifest.json`:
+export default defineConfig({ plugins: [tailwindcss(), muscat()] });
+```
+
+The ZIP contains only the plugin's own code and assets. `@rainbow-robotics/plugin-ui`, `react` and `react-dom` come from the host's import map.
+
+---
+
+## 5. manifest.json
+
+Validated by `muscat-pk dev`, `dev:back` and `build`.
+
+### 5.1 Full example
+
+```json
+{
+  "id": "com.example.my-plugin",
+  "name": "My Plugin",
+  "version": "1.0.0",
+  "minMuscatVersion": "1.0.0",
+  "author": "Kim",
+  "email": "kim@example.com",
+  "company": "Example Inc.",
+  "description": { "en": "Gripper helper", "ko": "그리퍼 도우미" },
+  "icons": "assets/icon.svg",
+  "targetModels": "all",
+  "targetCategorys": ["manipulate"],
+  "contributes": [
+    { "point": "toolbar", "icon": "assets/icon.svg", "label": { "en": "My Plugin" }, "ui": "content", "opens": "popover" }
+  ],
+  "variables": [
+    { "name": "RBP_grip_force", "type": "number", "init": 0.5, "description": { "en": "Gripper force (0–1)" } }
+  ],
+  "ports": [28600],
+  "runtime": { "type": "python", "entry": "main.py" }
+}
+```
+
+### 5.2 Top-level fields
+
+| Field | Required | Rule |
+|---|---|---|
+| `id` | yes | reverse-domain: `.`-separated parts of lowercase letters/digits joined by single `-`, each starting with a letter (`com.example.my-plugin`). No `_` |
+| `name`, `version`, `minMuscatVersion` | yes | non-empty strings |
+| `author`, `email` | yes | non-empty strings |
+| `company` | no | string |
+| `description` | yes | string or i18n object |
+| `icons` | yes | SVG path string, or `{ "16", "48", "128" }` for PNG/JPG (all three) |
+| `targetModels` / `targetCategorys` | at least one | `"all"` or a non-empty array. Categories: `manipulate`, `amr`, `rby1`, `vision` |
+| `contributes` | yes | see 5.3 |
+| `variables` | no | see 5.5 |
+| `ports` | no | see 5.6 |
+| `runtime` | yes | see 5.7 |
+
+i18n object: `en` is required; allowed keys `ko`, `en`, `ja`, `zh`, `vi`, `th`, `es`.
+
+### 5.3 `contributes`
+
+| Field | Rule |
+|---|---|
+| `point` | `toolbar`, `lnb`, `move.panel`, `program.panel`, `program.monitor` |
+| `ui` | UI entry name under `ui/` without extension (default `content`); unique across entries |
+| `label` | required, string or i18n object |
+| `icon` | icon path |
+| `opens` | toolbar only: `popover`, `panel`, `page` |
+| `commandInfo` | required for `program.panel` (5.4) |
+
+At least one `toolbar` entry is required.
+
+| Point | Where it shows |
+|---|---|
+| `toolbar` | header toolbar button; opens as popover / panel / page |
+| `lnb` | left navigation |
+| `move.panel` | Move page panel |
+| `program.panel` | a custom command in the Program page's step tree; its `ui` is the step's edit form |
+| `program.monitor` | a tab in the Program page's monitor panel (next to General / Digital I/O / Monitor / Log), rendered per task |
+
+### 5.4 `commandInfo` (`program.panel`)
+
+```json
+{
+  "point": "program.panel",
+  "ui": "program",
+  "label": { "en": "My Step" },
+  "commandInfo": {
+    "name": "My Step",
+    "icon": "assets/icon.svg",
+    "funcName": "rb_program_sdk.plugin_execute",
+    "args": { "message": "hello" }
+  }
+}
+```
+
+| Field | Type | Meaning |
+|---|---|---|
+| `name` | string, required | command name in the tree |
+| `icon` | string, required | icon path |
+| `iconClassName` | string | extra icon class |
+| `funcName` | string | function the executor calls (`rb_program_sdk.plugin_execute` for Python backends) |
+| `args` | object | default step args, passed with `plugin_id` to the backend |
+| `disabled`, `syncGroupId`, `disableCopy`, `disableDelete`, `requireChildren`, `requireParent` | boolean | tree editing rules |
+| `allowChildren`, `allowParents`, `notAllowChildren` | string[] | allowed / forbidden neighbour commands |
+| `childrenCommand` | string | command created as a child |
+
+### 5.5 `variables` (PyFM)
+
+Variables the plugin exposes to PyFM programs. The Program page's variable picker lists only declared ones.
+
+```json
+{ "name": "RBP_target_pose", "type": "array", "init": [0, 0, 0], "description": { "en": "Target pose" } }
+```
+
+| Field | Required | Rule |
+|---|---|---|
+| `name` | yes | `RBP_` + letters/digits/underscore; unique per plugin |
+| `type` | yes | `number`, `string`, `boolean`, `array` |
+| `init` | yes | initial value matching `type` |
+| `description` | no | string or i18n object — write one, the UI shows nothing otherwise |
+
+### 5.6 `ports`
+
+A backend that opens a TCP listener must declare every port:
 
 ```json
 { "ports": [28600, 28601] }
@@ -189,80 +384,635 @@ A plugin backend that opens a TCP listener must declare every such port in
 
 | Rule | Enforced by |
 |---|---|
-| Ports must be within `28600-28999` | `muscat-pk build` / `dev` (manifest validation) |
-| Reserved robot/industrial ports are rejected | same — `502`, `2222`, `4840`, `5170-5179`, `8000-8999`, `10000`, `30004`, `34964`, `44818`, `50000-50005`, `50051` |
-| **Every listening port must be declared** | `dev` / `dev:back` runtime monitor — stops the backend on the first undeclared port |
-| No two enabled plugins may claim the same port | the robot, at install time (HTTP 409) |
+| Only `28600-28999`, `number[]` | manifest validation |
+| Reserved ports rejected: `502`, `2222`, `4840`, `5170-5179`, `8000-8999`, `10000`, `30004`, `34964`, `44818`, `50000-50005`, `50051` | manifest validation |
+| Every listening port must be declared | `dev` / `dev:back` runtime monitor stops the backend on the first undeclared port |
+| No two enabled plugins share a port | the robot, at install (HTTP 409) |
 
-The runtime monitor is strict on purpose: an undeclared port outside the plugin
-range is invisible to both the monitor and the robot's conflict check, so it
-would only surface as a collision after deployment.
+The kit's own dev ports (gateway `10000`, the Zenoh dev peer port) are excluded. Under `muscat-pk dev` declared ports are published on `127.0.0.1`; a busy host port is skipped with a warning.
 
-`muscat-pk`'s own dev plumbing (the plugin gateway on `10000`, the Zenoh dev
-peer port) is excluded from the check — it isn't the plugin's traffic.
+### 5.7 `runtime`
 
-Under `muscat-pk dev` declared ports are published to `127.0.0.1` from the local
-Muscat container (the backend shares its network), so you can reach the backend
-from the host.
+| runtime | Source | Required fields |
+|---|---|---|
+| `{ "type": "none" }` | — | UI-only plugin |
+| `{ "type": "python", "entry": "main.py" }` | `py/` | `entry` |
+| `{ "type": "cpp", "entry": "<executable>" }` | `cpp/` | `entry` = built executable name |
+| `{ "type": "ros2", "rosClient": "rclpy", "package": "<pkg>", "launch": "<pkg>_node" }` | `ros2_ws/` | `rosClient`, `package`, `launch` |
+| `{ "type": "ros2", "rosClient": "rclcpp", "package": "<pkg>", "launch": "<pkg>_node" }` | `ros2_ws/` | same |
 
-## Variables (pyfm)
+---
 
-Variables the plugin wants to expose to pyfm programs must be pre-declared in
-`manifest.json` — the Muscat UI lists only declared variables in its variable
-picker:
+## 6. Plugin UI SDK (`useRb`)
 
-```json
-{
-  "variables": [
-    { "name": "RBP_grip_force", "type": "number", "init": 0.5, "description": { "ko": "그리퍼 힘 (0~1)", "en": "Gripper force (0–1)" } },
-    { "name": "RBP_target_pose", "type": "array", "init": [0, 0, 0] }
-  ]
+Package `@rainbow-robotics/plugin-ui`:
+
+| Import | Contents |
+|---|---|
+| `@rainbow-robotics/plugin-ui/react` | Muscat components (`RB*`), `useRb`, `useRbFormData`, `useRbSave`, `useRbStorage`, `createRbStore` |
+| `@rainbow-robotics/plugin-ui/sdk` | the same hooks without the components, `RbSdk` / `RbStore` / `RbSetState` types |
+
+### 6.1 Entry component
+
+Each top-level `ui/*.tsx` default-exports a React component. The host mounts it and provides `rb` through context.
+
+```tsx
+import { useRb } from "@rainbow-robotics/plugin-ui/sdk";
+import { RBLabelButton } from "@rainbow-robotics/plugin-ui/react";
+
+export default function App() {
+  const rb = useRb();
+  return <RBLabelButton onClick={() => rb.action("grip", { width: 20 })}>Grip</RBLabelButton>;
 }
 ```
 
-| Field | Required | Rule |
+Use plugin-ui components instead of native `<button>`, `<input>`, `<select>`, `<textarea>`, `<table>`, `<dialog>`. Common mappings: button → `RBLabelButton` / `RBIconButton`, text input → `RBTextInput` / `RBTextField`, number → `RBSideNumberInput`, select → `RBSelectBox` + `Option`, checkbox → `RBCheckBox`, switch → `RBSwitch`, slider → `RBSlider`, table → `RBTable`, modal → `RBModal`, tabs → `RBTabs`. `muscat-pk storybook` and `muscat-pk mcp` show props and examples.
+
+### 6.2 Messaging with the backend
+
+| UI | Backend (Python) | Pattern |
 |---|---|---|
-| `name` | yes | must start with `RBP_`, then letters/digits/underscore; unique per plugin |
-| `type` | yes | `"number"` \| `"string"` \| `"array"` |
-| `init` | yes | initial value, must match `type` |
-| `description` | no | string or i18n object (`en` required in object form). Without it the UI shows the variable with no explanation — write one. |
+| `rb.pub(topic, payload)` | `@plugin.subscribe(topic)` | fire-and-forget UI → backend |
+| `rb.sub(topic, handler)` | `plugin.publish(topic, payload)` | backend → UI stream |
+| `rb.action(topic, payload?)` | `@plugin.serve(topic)` | UI request, backend reply |
+| `rb.serve(topic, handler)` | `plugin.call(topic, payload=...)` | backend request, UI reply |
 
-Validated by `muscat-pk build` / `dev` alongside the rest of the manifest.
+```tsx
+const rb = useRb();
 
-## IDE support (Python)
+await rb.pub("event", { clicked: true });
 
-`muscat-pk new` creates a `.venv` at the project root with `requirements.txt` installed. The real backend still runs in a Docker container — this `.venv` exists purely for editor linting (pylint/pyright).
+const sub = await rb.sub<{ ready: boolean }>("state", (s) => setReady(s.ready));
+// cleanup: sub.undeclare()
 
-If it can't be created (no local Python 3 or `uv` found), scaffolding prints a warning and continues — Docker-based dev still works without it:
+const res = await rb.action<{ ok: boolean }, { width: number }>("grip", { width: 20 });
 
+await rb.serve("tool/ping", (payload) => ({ pong: payload }));
 ```
-Could not create .venv (no local Python/uv?) — skipping, Docker dev still works.
+
+- Topics are scoped to the plugin id: `"state"` → `{pluginId}/state`. A leading `/` makes it absolute (`"/broadcast/x"`).
+- All four take generics for payload / result types.
+- Unsubscribe in a `useEffect` cleanup:
+
+```tsx
+useEffect(() => {
+  let sub: { undeclare(): Promise<void> } | undefined;
+  rb.sub("state", setState).then((s) => (sub = s));
+  return () => void sub?.undeclare();
+}, [rb]);
 ```
 
-Install `uv` (recommended) or a system Python 3.12, then re-run `muscat-pk new` (or `muscat-pk type change`) to create it.
+### 6.3 Host dialogs and toast
 
-## AI coding agent setup (`muscat-pk mcp`)
+| API | Resolves |
+|---|---|
+| `rb.toast({ title?, message, type?, actionLabel?, handleActionClick?, closeOnActionClick?, duration?, onClose? })` | — (`message`: string or ReactElement; `type`: `info`, `danger`, `warning`, `caution`, `success`) |
+| `rb.alert({ title?, message, buttonText? })` | when closed |
+| `rb.confirm({ title?, message, buttonText?: { yes, no } })` | `true` / `false` |
+| `rb.prompt({ title?, message, value?, placeholder?, buttonText?: { yes, no } })` | entered string, or `undefined` when cancelled |
+
+```tsx
+if (await rb.confirm({ title: "Run", message: "Start the backend action?" })) {
+  await rb.action("run");
+  rb.toast({ message: "Started", type: "success" });
+}
+```
 
-`muscat-pk mcp` runs an MCP server (stdio) that gives an AI coding agent grounded info about `rb-components`, design tokens, and the Python `rainbow-rb-sdk` — actual prop types, real Storybook examples, and live-introspected SDK signatures/docstrings, instead of the agent guessing from training data. Use it while working inside a plugin project scaffolded by `muscat-pk new`.
+### 6.4 Program page (`rb.program`)
 
-### Claude Code
+| API | Meaning |
+|---|---|
+| `rb.program.getSteps(scope?)` | main step tree of the program open on the Program page |
+| `rb.program.setSteps(steps, scope?)` | replace it — an unsaved edit the user then saves |
+| `rb.program.getCatalog(scope?)` | the loaded robot's command catalog (names, default args, nesting rules) |
+
+```ts
+type PluginProgramStep = {
+  command: string;                    // "MoveJ", "Point", "Wait", "Repeat", "Condition", ...
+  args?: Record<string, unknown>;
+  summary?: string;
+  fields?: Record<string, unknown>;   // step-level fields, e.g. SubTask's subTaskType
+  children?: PluginProgramStep[];
+};
+type PluginProgramScope = { taskId?: string; robotModel?: string };
+```
 
-Claude Code reads a project-scoped `.mcp.json` at the plugin's root:
+Without `scope` the host uses the first main task. In a `program.monitor` tab `rb.data` is `{ point: "program.monitor", taskId, robotModel }` — pass it as `scope` so a multi-component robot hits the right task.
 
-```json
-{
-  "mcpServers": {
-    "muscat": {
-      "command": "muscat-pk",
-      "args": ["mcp"]
-    }
-  }
+### 6.5 Step form save/restore (`program.panel`)
+
+| Hook | Meaning |
+|---|---|
+| `useRbFormData<T>()` | values saved in this step, `undefined` for a new step |
+| `useRbSave(fn)` | registers the getter the host calls on Save; always sees current state. Return value must be JSON |
+
+```tsx
+import { useState } from "react";
+import { RBSlider, useRbFormData, useRbSave } from "@rainbow-robotics/plugin-ui/react";
+
+type Args = { width: number };
+
+export default function App() {
+  const saved = useRbFormData<Args>();
+  const [args, setArgs] = useState<Args>({ width: 20, ...saved });
+  useRbSave(() => ({ args, summary: `${args.width}mm` }));
+  return (
+    <RBSlider
+      value={[args.width]}
+      min={0}
+      max={100}
+      onValueChange={(values: number[]) => setArgs({ width: values[0] ?? 0 })}
+    />
+  );
 }
 ```
 
-### Codex
+The saved `args` reach the backend's `on_execute(args)` (see [7.3](#73-pluginprogramcontext--program-command)).
+
+### 6.6 Browser storage (`rb.storage`, `useRbStorage`, `createRbStore`)
+
+Keep browser-side plugin data only here. Everything is namespaced `muscat-plugin:<pluginId>`, and the host deletes it when the plugin is uninstalled — data stored any other way (raw `localStorage`, your own IndexedDB) is never cleaned up.
+
+| Backend | Use |
+|---|---|
+| `rb.storage` (= `rb.storage.indexedDB`) | default; structured values (objects, arrays, `Date`, `Blob`, …) |
+| `rb.storage.local` | `localStorage`, JSON values, survives reloads |
+| `rb.storage.session` | `sessionStorage`, JSON values, gone when the tab closes |
+| `rb.storage.cookie` | ~4 KB per value and sent with every request to the host — tiny values only |
+
+Every backend has the same API:
+
+| Method | Meaning |
+|---|---|
+| `get<T>(key)` | value, or `undefined` |
+| `set(key, value)` | save |
+| `delete(key)` | remove |
+| `keys()` | this plugin's keys |
+| `subscribe(listener, key?)` | `({ kind, key, value }) => void` on every change made through this API — this screen, other screens of the plugin (toolbar panel, Program tab, …) and other browser tabs. `value` is `undefined` after a delete. Returns the unsubscribe function |
+| `getItem` / `setItem` / `removeItem` | zustand `StateStorage` (raw strings) |
+
+```tsx
+const rb = useRb();
+await rb.storage.set("lastRun", { at: new Date(), ok: true });
+const last = await rb.storage.get<{ at: Date; ok: boolean }>("lastRun");
+await rb.storage.local.set("theme", "dark");
+```
+
+#### `useRbStorage` — one stored value as React state
+
+```tsx
+import { useRbStorage } from "@rainbow-robotics/plugin-ui/react";
+
+type Draft = { name: string };
+
+function Editor() {
+  const [draft, setDraft] = useRbStorage<Draft>("draft", { kind: "local", initial: { name: "" } });
+  // setDraft(next) saves; setDraft(undefined) deletes
+  return <RBTextInput value={draft?.name ?? ""} handleChange={(name: string) => void setDraft({ name })} />;
+}
+```
+
+- `useRbStorage<T>(key, { kind?, initial? })` → `[value, setValue]`. `kind` defaults to `"indexeddb"`.
+- Re-renders when the value changes anywhere (other screens, other tabs).
+- `value` is `initial` until the stored value has loaded.
+
+#### `createRbStore` — persisted zustand-style store
+
+Define once at module level, use from any screen of the plugin:
+
+```tsx
+import { createRbStore } from "@rainbow-robotics/plugin-ui/react";
+
+type Settings = {
+  speed: number;
+  points: string[];
+  setSpeed: (v: number) => void;
+  addPoint: (p: string) => void;
+};
+
+export const useSettings = createRbStore<Settings>(
+  (set, get) => ({
+    speed: 50,
+    points: [],
+    setSpeed: (speed) => set({ speed }),
+    addPoint: (p) => set((s) => ({ points: [...s.points, p] })),
+  }),
+  { name: "settings", storage: "local" },
+);
+
+function SpeedPanel() {
+  const speed = useSettings((s) => s.speed);       // re-renders only when speed changes
+  const setSpeed = useSettings((s) => s.setSpeed);
+  return <RBSlider value={[speed]} min={0} max={100} onValueChange={(v: number[]) => setSpeed(v[0] ?? 0)} />;
+}
+```
+
+| Member | Meaning |
+|---|---|
+| `createRbStore<T>(init, { name, storage? })` | `init(set, get)` returns initial state + actions. `name` is the storage key; `storage` is a backend kind (default `"indexeddb"`) |
+| `useStore()` / `useStore(selector)` | whole state / a slice (re-renders only when the slice changes) |
+| `useStore.getState()` | current state, outside React |
+| `useStore.setState(partial \| (s) => partial)` | merge a change, outside React |
+| `useStore.subscribe((next, prev) => …)` | listen outside React; returns unsubscribe |
+
+- State changes only through `set` / `setState`. Every change is saved and re-renders every screen and tab using the store.
+- Functions (actions) are not saved; only data fields are.
+- The saved data loads when the first component using the store mounts (the plugin id is known only then). Before that `getState()` returns the initial values.
+- Changes are merged shallowly: set a new array/object (`[...s.points, p]`) instead of mutating it.
+
+#### Using zustand `persist` directly
+
+Every backend is a zustand `StateStorage`:
+
+```ts
+import { persist, createJSONStorage } from "zustand/middleware";
+persist(fn, { name: "settings", storage: createJSONStorage(() => rb.storage.local) });
+```
+
+`zustand` is then a dependency of your plugin; `createRbStore` needs nothing extra.
+
+### 6.7 Other
+
+| API | Meaning |
+|---|---|
+| `rb.data` | host-provided mount data (`program.monitor` scope, saved form values) |
+| `rb.rosPeers.get()` | PCs allowed to reach this plugin's ROS 2 nodes |
+| `rb.rosPeers.set(ips)` | save the list and restart the backend; rejects an invalid IP |
+
+---
+
+## 7. Python plugin SDK
+
+Python backends (`runtime.type: "python"`, entry `py/main.py`) use `rainbow-rb-sdk`, pinned in `requirements.txt` and changed with `muscat-pk sdk update`. The robot's plugin container provides the SDK at runtime.
+
+```python
+from rainbow.rb_sdk import RBPluginCall, PluginProgramContext, RBManipulateSDK, RBAmrSDK
+from rainbow.rb_sdk.plugin import PluginRouteError
+from rainbow.rb_sdk.rb_sdk_cpp import ConnectOptions
+```
+
+Which API depends on the contribution point:
+
+| Contribution point | Backend |
+|---|---|
+| `toolbar` / `lnb` / `move.panel` / `program.monitor` | `RBPluginCall` + robot SDKs (`RBManipulateSDK`, `RBAmrSDK`) called directly. No stop/pause/variable context |
+| `program.panel` | `PluginProgramContext` — runs as a program step, tied to stop/pause and program variables |
+
+### 7.1 `RBPluginCall` — UI ↔ backend
+
+Internal only (UI ↔ backend, plugin ↔ plugin); not reachable from outside Muscat. The plugin id comes from env `RB_PLUGIN_ID`.
+
+```python
+plugin = RBPluginCall()
+
+@plugin.serve("grip")                  # UI: await rb.action("grip", { width })
+def grip(payload=None):
+    width = (payload or {}).get("width", 20)
+    plugin.publish("state", {"last_grip_width": width})
+    return {"ok": True, "width": width}
+
+@plugin.subscribe("event")             # UI: rb.pub("event", ...)
+def on_event(payload=None):
+    print(payload)
+
+plugin.publish("state", {"ready": True})                         # UI: rb.sub("state", ...)
+res = plugin.call("tool/ping", payload={"hi": 1}, timeout=3.0)   # UI: rb.serve("tool/ping", ...)
+```
+
+| Member | Meaning |
+|---|---|
+| `serve(keyexpr, handler=None)` | request/response handler; decorator or direct call. Return value = reply |
+| `subscribe(topic, callback=None)` | receive publishes |
+| `publish(topic, payload=None)` | push to subscribers |
+| `call(keyexpr, *, payload, timeout=3.0)` | request the other side and wait |
+| `unserve(keyexpr=None)` | remove one / all serve handlers |
+| `unsubscribe(topic=None, callback=None)` | remove subscriptions |
+| `plugin_id` | the plugin id in use (dev id under `muscat-pk dev`) |
+| `connected` | transport connected |
+| `data_dir` | persistent data directory, created on access. Survives updates and restarts; removed with the plugin. The install directory (cwd) is replaced on every update — keep state, caches and settings here |
+| `router` | external endpoints (7.2) |
+
+Payloads must be JSON-serialisable. Handlers may be sync or async.
+
+### 7.2 `plugin.router` — external endpoints
+
+Exposes `common/plugin/{plugin_id}/{path}` over REST, Socket.IO, TCP, MQTT and WebRTC. The running Muscat (`common`) picks it up without a restart; it disappears when the plugin stops. Requires `rainbow-rb-sdk` ≥ 0.0.9.dev5 on the robot (older: `AttributeError`).
+
+```python
+@plugin.router.on("/hello")                             # every transport
+def hello(payload, meta):
+    return {"msg": f"hi {payload.get('name')}", "via": meta["transport"]}
+
+@plugin.router.on("/admin", explicit_routes=["api"])    # REST only
+def admin(payload, meta):
+    if not (meta.get("principal") or {}).get("is_admin"):
+        raise PluginRouteError(403, "admin only")
+    return {"ok": True}
+
+@plugin.router.subscribe("/cmd", explicit_events=["tcp"])
+def on_cmd(payload):
+    ...
+
+plugin.router.emit("/state", {"busy": True})
+```
+
+| API | Meaning | External side |
+|---|---|---|
+| `router.on(path, explicit_routes=None)` | request/response | calls `common/plugin/{id}/{path}` (REST: `POST`) |
+| `router.subscribe(topic, explicit_events=None)` | receive external publishes | publishes to `common/plugin/{id}/{topic}` |
+| `router.emit(topic, payload=None)` | push to external subscribers | subscribes to `common/plugin/{id}/{topic}` |
+
+Handler contract:
+
+- Signature `(payload, meta)`, `(payload)` or `()` — only declared arguments are injected. Sync or async.
+- `payload`: what the caller sent (REST: JSON body merged with query params).
+- `meta`: `{"transport": "api"|"socket"|"tcp"|"mqtt"|"webrtc", "principal": dict | None}`. With the login policy on, `principal` is the token subject. Role checks are the plugin's job.
+- Return value = response body (JSON). `None` → empty.
+- `raise PluginRouteError(code, message)` sets the status; any other exception → 500 with `str(exc)`.
+- `subscribe` handlers take `(payload)` and return nothing.
+
+Rules:
+
+- Write only the path; the SDK adds `plugin_id`. Multi-segment paths work (`/tool/echo`). Declaring a path twice → `ValueError`.
+- `explicit_routes` / `explicit_events`: `None` = every transport. Names `api | socket | tcp | mqtt | webrtc`; `subscribe` accepts only `tcp | mqtt | webrtc`. Unknown → `ValueError`. A disallowed transport gets 404.
+- `on` and `subscribe` may share a name.
+
+Calling from outside:
+
+| Transport | How |
+|---|---|
+| REST | `POST /common/plugin/{id}/{path}`, JSON body |
+| Socket.IO | emit `common/plugin/{id}/{path}`; reply in the ack |
+| TCP | topic `common/plugin/{id}/{path}` request / publish |
+| MQTT | request `common/plugin/{id}/{path}/__req__`; publish `common/plugin/{id}/{topic}` |
+| WebRTC | data channel topic `common/plugin/{id}/{path}` |
+
+```bash
+curl -s -X POST http://<robot>/common/plugin/com.example.my-plugin/hello \
+  -H 'Content-Type: application/json' -d '{"name":"kim"}'
+# under muscat-pk dev (the dev id is printed at start)
+curl -s -X POST http://localhost:3000/common/plugin/<dev-id>/hello -H 'Content-Type: application/json' -d '{}'
+```
+
+| Situation | Status |
+|---|---|
+| No such path / plugin down / transport not allowed | 404 |
+| No answer within 10 s | 504 |
+| `common` ↔ gateway not connected | 503 |
+| Handler raised | 500 (`PluginRouteError` → its code) |
+
+Auth: with the login policy on a token is required (any role); REST uses the same Bearer token as other Muscat APIs. Off: no token.
+
+Known limits:
+
+- A path named `install` can't be called over REST (taken by the registry install route).
+- MQTT echoes to the sender: `emit` + `subscribe` on the same topic receives its own push over `mqtt`. Drop `mqtt` from `explicit_events` or use separate topics.
+- After restarting the plugin, external calls may return 504 for up to a minute, then 404, until the gateway drops the old socket.
+
+### 7.3 `PluginProgramContext` — program command
+
+Used only for `program.panel`. When the program reaches the step, the executor calls `commandInfo.funcName` with `plugin_id` + the step args, and the SDK calls your `on_execute`.
+
+```python
+import asyncio
+from rainbow.rb_sdk import PluginProgramContext
+
+ctx = PluginProgramContext(plugin_id="com.example.my-plugin")
+
+@ctx.on_execute
+async def handle(args: dict) -> None:
+    count = await ctx.get_variable("counter")
+    await ctx.set_variable("counter", (count or 0) + 1)
+    await ctx.set_variable("RBP_my_plugin_result", 42)   # new variable → RBP_ required
+
+    for _ in range(100):
+        await ctx.check_stop()     # stop → CancelledError, pause → waits until resumed
+        await asyncio.sleep(0.5)
+
+    await ctx.done()               # always; the step never finishes otherwise
+
+@ctx.on_executor_state_change
+async def on_change(robot_model: str, state: str) -> None:
+    if state == "paused":
+        print(f"{robot_model} paused")
+
+async def background() -> None:
+    while True:
+        await asyncio.sleep(1.0)
+        await ctx.set_variable("RBP_my_plugin_heartbeat", 1)   # ignored when no program runs
+
+async def main() -> None:
+    asyncio.create_task(background())
+    await ctx.start()              # stays resident
+
+asyncio.run(main())
+```
+
+| Member | Meaning |
+|---|---|
+| `on_execute(fn)` | decorator; called once per execution of this step with the step args |
+| `done()` | step finished — always call |
+| `check_stop(robot_model=None)` | stop → `CancelledError`, pause → waits. Call every loop iteration |
+| `get_variable(name, robot_model=None, plugin_id=None)` | read; `None` when no program runs |
+| `set_variable(name, value)` | write to every running main task; ignored when no program runs |
+| `executor_state(robot_model=None)` | state string for a model, or `{model: state}` for all |
+| `is_paused(robot_model=None)` / `is_stopped(robot_model=None)` | state checks |
+| `on_executor_state_change(fn)` | decorator; `(robot_model, state)` once per change |
+| `start()` / `stop()` / `pause()` | lifecycle |
+| `in_execute`, `exec_robot_model`, `plugin_id`, `started`, `control_topic` | properties |
+
+#### Variables
+
+- Existing variable: written by name as-is — exchanging values with the program is the point.
+- New variable: must start with `RBP_` (`RuntimeError` otherwise), inside or outside a step. Use `RBP_{plugin}_{name}` to avoid collisions; `RBP_` alone doesn't prevent two plugins overwriting each other.
+- Declare in `manifest.json` → `variables` what the Program page should offer (5.5).
+
+`set_variable` targets every running main task:
+
+| When | Own program | Other robots' main tasks |
+|---|---|---|
+| During own step | immediate | at their next step boundary |
+| Outside a step | next step boundary | same |
+
+`get_variable` options:
+
+```python
+await ctx.get_variable("counter")                              # first value across main tasks
+await ctx.get_variable("counter", robot_model="C500920")       # one robot
+await ctx.get_variable("RBP_TEST", plugin_id="A.plugin")       # what that plugin last wrote
+```
+
+Each variable keeps a per-plugin record (`meta.writers`), so a colliding name is still recoverable: `get_variable(..., plugin_id=...)` from the SDK, `get_var("A.plugin", "RBP_TEST")` in a program expression. A write can rarely be lost when it races the worker's flush — re-check important values.
+
+#### Executor state
+
+States: `idle | running | paused | waiting | stopped | post_start | completed | error`. A model with no running task is `None` / absent.
+
+- Published every 0.8 s on `muscat/executor/state` — up to ~1 s latency.
+- With `IS_DEV=true` there is no publish; always `None`.
+- `on_executor_state_change` fires once per per-model change; handler exceptions are only logged.
 
-Codex has no project-scoped config file — it reads a single, per-user `~/.codex/config.toml`. Add:
+Scope of `check_stop` / `is_paused` / `is_stopped`:
+
+1. `robot_model` given → that model
+2. omitted inside `on_execute` → the model executing this step
+3. omitted elsewhere → all models
+
+### 7.4 Robot SDKs from the backend
+
+```python
+manipulate = RBManipulateSDK()
+manipulate.move.call_move_j(
+    robot_model="C500920",
+    target={"tar_values": [0, 0, 0, 0, 0, 0, 0], "tar_frame": -1, "tar_unit": 0},
+)
+```
+
+Add your own safety checks before moving the robot. Exact signatures: `muscat-pk mcp` (`search_rb_sdk`, `get_rb_sdk_api`).
+
+### 7.5 Remote dev (laptop → robot)
+
+```bash
+export MUSCAT_ROBOT_HOST=192.168.1.100
+export MUSCAT_ROBOT_TOKEN=<service token>   # only when the robot's login policy is on
+muscat-pk dev:back
+```
+
+```python
+async def main():
+    host = os.getenv("MUSCAT_ROBOT_HOST")
+    if host:
+        opts = ConnectOptions()
+        opts.host = host
+        opts.token = os.getenv("MUSCAT_ROBOT_TOKEN", "")
+        manipulate.connect(opts)
+    register_handlers()   # after connect() — connect() reopens the session and drops earlier handlers
+    ...
+    if host:
+        await manipulate.disconnect()
+```
+
+The scaffolded `py/main.py` already follows this.
+
+---
+
+## 8. Other backend runtimes (C++ / ROS 2)
+
+All non-`none` runtimes run in Docker during `dev:back`, `dev` and `build`.
+
+### 8.1 C++ (`cpp`)
+
+- Source in `cpp/`, CMake build in Docker against the C++ SDK (apt `rainbow-rb-sdk-dev`).
+- CMake: `find_package(rb_sdk <ver> EXACT REQUIRED)` + `target_link_libraries(<target> rb_sdk::rb_sdk)` (C++20).
+- Headers: `<rainbow/rb_sdk/manipulate/rb_manipulate_sdk.hpp>`, `<rainbow/rb_sdk/plugin/rb_plugin.hpp>` (`rb_plugin::RBPluginCall`), `<rainbow/rb_sdk/program/plugin_program_context.hpp>` (`rb_plugin::PluginProgramContext`).
+- Dynamic link; `build` copies `librb_sdk.so` into `dist/<arch>/lib/`.
+
+Building outside the container (Ubuntu 24.04):
+
+```bash
+curl -fsSL https://rainbowrobotics.github.io/rb-sdk/rb-sdk-apt-repo.gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/rb-sdk-apt.gpg
+echo 'deb [signed-by=/usr/share/keyrings/rb-sdk-apt.gpg] https://rainbowrobotics.github.io/rb-sdk stable main' | sudo tee /etc/apt/sources.list.d/rb-sdk.list
+sudo apt update && sudo apt install rainbow-rb-sdk-dev
+```
+
+### 8.2 ROS 2 (`ros2` + `rclpy` / `rclcpp`)
+
+- Source in `ros2_ws/src/<package>/`; `runtime.package` = colcon package, `runtime.launch` = node executable.
+- Relative topic names live under the plugin's namespace: id with `.` → `/`, `-` → `_` (`com.example.my-plugin` → `/com/example/my_plugin`). Use absolute names (`/cmd_vel`) for shared topics.
+- `RBPluginCall` works in an rclpy node too.
+- ROS discovery stays on the robot (`ROS_AUTOMATIC_DISCOVERY_RANGE=LOCALHOST`). Allow external PCs from the UI with `rb.rosPeers.set([...])`; Muscat restarts the backend with `ROS_STATIC_PEERS`. In dev the list is in `.muscat-dev/ros-peers.json`.
+
+---
+
+## 9. Development environment
+
+### 9.1 Local Muscat runtime
+
+Without a robot IP, `dev` / `dev:ui` need a Muscat on `localhost:3000`:
+
+- reuses any container already publishing `:10000` (`muscat`, `muscat-dev`, …);
+- otherwise starts `muscat-pk-muscat` — the S3 runtime image running only `common`, cached in `~/.muscat-pk/muscat/`. It keeps running between runs.
+
+```bash
+docker rm -f muscat-pk-muscat          # stop it
+MUSCAT_PK_NO_LOCAL_MUSCAT=1 muscat-pk dev   # don't start it
+```
+
+### 9.2 Developing on the robot PC
+
+On the robot PC Muscat already serves the gateway on `10000`; the CLI uses it and starts no local Muscat.
+
+### 9.3 Several developers on one robot
+
+Against a remote robot, `dev` / `dev:back` run the plugin as `<manifest id>.dev-<user>-<random>` (random part kept in `~/.muscat-pk/dev-id`), so two machines don't answer each other's UI. UI, backend, ROS namespace and external routes all use the dev id. `--keep-id` uses the manifest id (for program `execute` or external clients) — then only one machine may connect.
+
+### 9.4 Local vs global install
+
+If the project has its own `muscat-plugin-kit` in `node_modules`, any `muscat-pk` hands off to it, so the CLI, `vite` preset and `preview-host` are always the project's pinned version. `muscat-pk version` prints the copy that actually ran.
+
+### 9.5 Offline / air-gapped
+
+Docker images are built only when missing (a rebuild contacts the registry even when cached).
+
+```bash
+docker save muscat-pk-python-dev muscat-pk-runtime | gzip > muscat-pk-images.tar.gz   # online machine
+gunzip -c muscat-pk-images.tar.gz | docker load                                       # offline machine
+```
+
+Force a rebuild with `MUSCAT_PK_REBUILD_IMAGE=1`.
+
+### 9.6 IDE support (Python)
+
+`muscat-pk new` creates `.venv` with `requirements.txt` installed — for editor linting only; the backend runs in Docker. Without `uv` or Python 3 it prints `Could not create .venv (no local Python/uv?) — skipping, Docker dev still works.`; install one and re-run `new` or `type change`.
+
+### 9.7 JavaScript dependencies
+
+`build` runs the project's own Vite build, so packages must be installed. Don't `npm install --omit=dev` before building — `vite`, `typescript`, `tailwindcss`, `sass`, `less` are devDependencies. The ZIP ships no `node_modules`.
+
+---
+
+## 10. Styles
+
+- `muscat()` auto-loads `ui/style.{css,scss,sass,less}` / `ui/styles.*` for every entry and `ui/{entry}.*` for a matching entry, and injects the CSS into the JS bundle.
+- Built selectors are scoped under `[data-muscat-plugin-id="..."]`, so plugin CSS can't touch the host or other plugins.
+- Use design-token classes (`bg-bg-*`, `text-fg-*`, `typo-*`) rather than hex colors.
+
+Tailwind (default, no preflight):
+
+```css
+@layer theme, utilities;
+@import "tailwindcss/theme.css" layer(theme);
+@import "tailwindcss/utilities.css" layer(utilities);
+@source "./**/*.{ts,tsx}";
+```
+
+SCSS / Less: `npm i -D sass` (or `less`) and create `ui/style.scss` (`ui/style.less`).
+
+Emotion `styled` works as is. For the `css` prop:
+
+```bash
+npm i @emotion/react @emotion/styled && npm i -D @emotion/babel-plugin
+```
+
+```ts
+muscat({ react: { jsxImportSource: "@emotion/react", babel: { plugins: ["@emotion/babel-plugin"] } } })
+```
+
+and `"jsxImportSource": "@emotion/react"` in `tsconfig.json`. Emotion `Global` is not scoped — avoid it.
+
+---
+
+## 11. AI coding agent setup (`muscat-pk mcp`)
+
+An MCP server (stdio) with grounded info on rb-components (props, Storybook examples), design tokens, and the Python `rainbow-rb-sdk` (introspected signatures/docstrings), plus `check_project` for upgrading old projects.
+
+Claude Code — `.mcp.json` at the plugin root:
+
+```json
+{ "mcpServers": { "muscat": { "command": "muscat-pk", "args": ["mcp"] } } }
+```
+
+Codex — `muscat-pk mcp --install codex`, or `~/.codex/config.toml`:
 
 ```toml
 [mcp_servers.muscat]
@@ -270,13 +1020,40 @@ command = "muscat-pk"
 args = ["mcp"]
 ```
 
-You don't run `muscat-pk mcp` yourself either way — the agent spawns and manages it automatically once it's registered.
+The agent starts the server itself.
+
+---
 
-## Package roles
+## 12. Environment variables
 
-| Package | Role |
+| Variable | Effect |
 |---|---|
-| `@rainbow-robotics/plugin-ui` | UI runtime contract: React direct mount, `useRb()` context, host services |
-| `@rainbow-robotics/muscat-plugin-kit` | CLI, templates, build/pack, preview host |
+| `MUSCAT_ROBOT_HOST` | robot IP for `dev` / `dev:ui` / `dev:back` (skips the prompt) |
+| `MUSCAT_ROBOT_TOKEN` | service token when the robot's login policy is on |
+| `MUSCAT_PK_NO_LOCAL_MUSCAT=1` | don't start the local Muscat runtime |
+| `MUSCAT_PK_REBUILD_IMAGE=1` | rebuild Docker images |
+| `MUSCAT_PK_RB_SDK_VERSION` | C++ SDK version baked into the C++ images (with `MUSCAT_PK_REBUILD_IMAGE=1`) |
+| `MUSCAT_PK_NO_UPDATE_CHECK=1` | skip the update check on `dev` / `dev:ui` |
+| `RB_REGISTRY` | npm registry for the update check (default `https://registry.npmjs.org`) |
+| `MUSCAT_PK_TAG` | install script channel / version |
+| `NO_COLOR` / `FORCE_COLOR` | output colors |
+
+Inside the backend container: `RB_PLUGIN_ID` (the plugin / dev id).
 
-A plugin ZIP only contains the plugin's own code and assets. `@rainbow-robotics/plugin-ui`, `react`, and `react-dom` are provided by the host's (Muscat/robot) import map.
+---
+
+## 13. Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `manifest.json errors: …` | fix each listed field (section 5) |
+| backend stops with an undeclared port | add the port (28600-28999) to `ports` |
+| UI preview says "no default export" | entry must `export default App`; `vite.config.ts` must use `muscat()`; run `check_project` via `muscat-pk mcp` |
+| `vite not found — UI will not load` | run `npm install` in the project |
+| `AttributeError: router` | robot SDK older than 0.0.9.dev5 |
+| step never finishes | `on_execute` must `await ctx.done()` |
+| Stop doesn't stop the plugin | call `await ctx.check_stop()` in every loop |
+| `RuntimeError` on `set_variable` | new variable names need `RBP_` |
+| `get_variable` returns `None` | no program running (or `IS_DEV=true` for executor state) |
+| external call 504 after restart | wait up to a minute for the gateway to drop the old socket |
+| a newer/older local install answers | expected — the project's local kit wins; `muscat-pk update` |