@rainbow-robotics/muscat-plugin-kit 0.1.2-dev.9 → 0.10.1-dev.0

package/README.md

@@ -1,106 +1,1186 @@
 # @rainbow-robotics/muscat-plugin-kit
 
-Muscat 플러그인 개발 CLI. 스캐폴딩, 빌드/팩, 개발 서버(UI + 백엔드)를 제공합니다.
+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)
 
-### 방법 1 — npm (Node.js 20+ 필요)
+## Contents
 
-```bash
-# 최신 stable
-npm install -g @rainbow-robotics/muscat-plugin-kit
+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)
+
+---
 
-# dev 채널 (최신 개발 빌드)
-npm install -g @rainbow-robotics/muscat-plugin-kit@dev
+## 1. Install
 
-# 특정 버전
-npm install -g @rainbow-robotics/muscat-plugin-kit@1.2.3
+### npm (Node.js 20+)
+
+```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
 ```
 
-### 방법 2 — 설치 스크립트 (Node.js 없어도 됨)
+### Install script (no Node.js required)
 
 macOS / Linux / WSL:
 
 ```bash
-# 최신 stable
-curl -fsSL https://raw.githubusercontent.com/rainbow-robotics/web-rainbow-ui/main/scripts/install-muscat-pk.sh | sh
-
-# dev 채널
-MUSCAT_PK_TAG=dev curl -fsSL https://raw.githubusercontent.com/rainbow-robotics/web-rainbow-ui/main/scripts/install-muscat-pk.sh | sh
-
-# 특정 버전
-MUSCAT_PK_TAG=1.2.3 curl -fsSL https://raw.githubusercontent.com/rainbow-robotics/web-rainbow-ui/main/scripts/install-muscat-pk.sh | sh
+curl -fsSL https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/install.sh | sh
+curl -fsSL https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/install.sh | MUSCAT_PK_TAG=dev sh
+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
-# 최신 stable
-irm https://raw.githubusercontent.com/rainbow-robotics/web-rainbow-ui/main/scripts/install-muscat-pk.ps1 | iex
-
-# dev 채널
-$env:MUSCAT_PK_TAG="dev"; irm https://raw.githubusercontent.com/rainbow-robotics/web-rainbow-ui/main/scripts/install-muscat-pk.ps1 | iex
+irm https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/install.ps1 | iex
+$env:MUSCAT_PK_TAG="dev"; irm https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/install.ps1 | iex
 ```
 
-> 설치 스크립트는 Node.js 20+가 있으면 npm을 우선 사용하고, 없으면 S3에서 self-contained 바이너리를 받습니다.
+The script uses npm when Node.js 20+ is present, otherwise it downloads a self-contained binary.
 
-### 방법 3 — 바이너리 직접 다운로드
+### Direct binary download
 
 ```
-https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/v{버전}/{바이너리}
+https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/v{version}/{binary}
+https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/stable/{binary}
+https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/dev/{binary}
 ```
 
-| OS | 파일 |
+| OS | File |
 |---|---|
 | Linux x64 | `muscat-pk-linux-x64` |
 | macOS ARM64 | `muscat-pk-darwin-arm64` |
+| macOS x64 | `muscat-pk-darwin-x64` |
 | Windows x64 | `muscat-pk-win-x64.exe` |
 
-채널 포인터:
+Channel pointers: `.../muscat-plugin-kit/latest-version.txt` (stable), `.../muscat-plugin-kit/dev-version.txt` (dev).
 
-```
-# 최신 stable 버전 문자열
-https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/latest-version.txt
+### Requirements
+
+| 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
 
-# 최신 dev 버전 문자열
-https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/dev-version.txt
+```bash
+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
 ```
 
 ---
 
-## 빠른 시작
+## 2. Quick start
 
 ```bash
-muscat-pk new my-plugin        # 플러그인 프로젝트 생성 (python 또는 ros2 선택)
+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.
+
+---
+
+## 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 sim list` | List the robot simulators for `dev --sim` |
+| `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 [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 `<pm> install`, the IDE `.venv` and the C++ dev image |
+| `--help` | print the usage |
+
+The plugin id is `com.example.<dir>` (lowercased; edit it in `manifest.json`). `new` also writes `.gitignore`, `AGENTS.md`, `CLAUDE.md` and `.mcp.json` (see [11](#11-ai-coding-agent-setup-muscat-pk-mcp)), and runs `git init` with an initial commit (delete `.git` if you don't want it).
+
+Unless `--no-install`:
+
+- python / ros2 (rclpy): an IDE-only `.venv` (see [9.6](#96-ide-support-python)).
+- cpp / ros2-cpp: builds the C++ dev image so the editor finds the SDK headers (skipped with a warning when Docker is missing).
+
+### 3.2 `type change`
+
+```bash
+muscat-pk type change [--to python|cpp|ros2|ros2-cpp] [--readme]
+```
+
+| Option | Meaning |
+|---|---|
+| `--to` | new type; a numbered prompt when omitted |
+| `--readme` | replace `README.md` with the new type's without asking (old file → `README.md.bak`) |
+
+Rewrites `manifest.json` → `runtime` and adds the new backend's files (`cpp/` or `ros2_ws/`) unless that directory already exists. Files of the old type (`cpp/`, `ros2_ws/`, …) are left in place. When switching between a Python and a C++ backend it offers to replace the README (`--readme` answers yes). Switching to a C++ type prepares the C++ dev image like `new`.
+
+### 3.3 `dev`, `dev:ui`, `dev:back`
+
+```bash
+muscat-pk dev        [--robot-ip <ip>] [--robot-token <token>] [--keep-id] [--sim <model>]
+                     [--port <n>] [--no-open]
+muscat-pk dev:ui     [--robot-ip <ip>] [--port <n>] [--keep-id] [--no-open]
+muscat-pk dev:back   [--robot-ip <ip>] [--robot-token <token>] [--keep-id]
+```
+
+| Command | What runs |
+|---|---|
+| `dev` | builds the dev image and backend first (a failed build only warns), then a local Muscat runtime when no robot is given (or the robot runs no Muscat), then `dev:ui` and `dev:back` |
+| `dev:ui` | the plugin's Vite dev server + preview-host at `http://localhost:4180` (next free port), opened in the browser |
+| `dev:back` | the backend in a Docker container matching the robot. Python restarts on `py/**/*.py` changes (watchfiles) |
+
+| Option | Meaning |
+|---|---|
+| `--robot-ip` | robot to develop against; else `MUSCAT_ROBOT_HOST`, else a prompt (blank = no robot) |
+| `--robot-token` | service token for a robot with the login policy on; else `MUSCAT_ROBOT_TOKEN`, else a prompt (blank = none) |
+| `--keep-id` | run under the manifest id instead of a dev id (see [9.3](#93-several-developers-on-one-robot)) |
+| `--sim` | `dev` only, no robot: start a robot simulator (below). Skips the robot IP prompt |
+| `--port` | preview-host port (default `4180`; the next free one when taken) |
+| `--no-open` | don't open the browser (it is not opened in CI or without a TTY either) |
+
+- One dev environment per PC: they share the backend container, the local Muscat and its ports. A second `dev` / `dev:ui` / `dev:back` asks to stop the running one (`Stop it and start this one? [y/N]`).
+- 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.
+- Before start, `dev` and `dev:back` check `manifest.json` → `variables` and `ports` (errors stop it); `dev:back` also prints other manifest errors as warnings. The full check runs on `build`. Undeclared listening ports stop the backend (see [5.6](#56-ports)).
+- Against a robot running Muscat, the UI is that robot's Muscat UI and the backend uses its gateway. With a local `muscat-dev` container (or `--sim`) it is the local real Muscat UI; otherwise the mock preview.
+- `dev` / `dev:ui` print a hint when a newer kit is published (`MUSCAT_PK_NO_UPDATE_CHECK=1` skips it).
+- Stopping `dev` (Ctrl+C) removes the backend container, and its own local Muscat and simulators.
+
+#### Developing without a robot (`--sim`)
+
+With no robot IP, `dev --sim <model>` also starts a robot simulator next to the local Muscat. The plugin SDK's robot calls then reach a real coreSW.
+
+```bash
+muscat-pk sim list          # "<name>\t<what runs>" per line
+muscat-pk dev --sim 500920
+muscat-pk dev --sim rby1-m_v1.2
+```
+
+| `--sim` | Muscat services | Simulator |
+|---|---|---|
+| `500920` | common, log, manipulate | one `rainbowroboticsofficial/cobot-sim` |
+| `RBY2` | common, log, manipulate | three cobot-sim (C500880, C501880, C502880) |
+| `rby1-a`, `rby1-m`, `rby1-ub` (or a version, e.g. `rby1-m_v1.2`) | common, log, rby1 | `rainbowroboticsofficial/rby1-sim` + Xvfb, built locally |
+
+- The simulated model is registered as the local Muscat's robot model (`500920` → C500920, `rby1-m` → m). The UI is then the real Muscat UI (dashboard, components, Move, Log, Settings) instead of the mock preview.
+- A simulator runs only with `--sim`. Any other value fails with `--sim takes one of: 500920, RBY2, rby1-a, rby1-m, rby1-ub (rby1 also takes rby1-m_v1.2)`. A model missing from the manifest's `targetModels` only gets a warning.
+- Simulator images use the latest Docker Hub tag (an rby1 version picks the matching tag). Offline, an already pulled image is used.
+- rby1-sim keeps rendering, so it uses about one CPU core. The cap is `MUSCAT_PK_RBY1_CPUS` (default 1.5).
+- No simulator is attached while another Muscat such as `muscat-dev` is running.
+- There is no amr simulator yet.
+- The local Muscat, the simulators and the backend all run with `--ipc host` like on the robot, so zenoh SHM and `shm_open` reach each other.
+
+### 3.4 `build`
+
+```bash
+muscat-pk build [--arch amd64|arm64|both]
+```
+
+Steps:
+
+1. Asks for a new `manifest.json` version (blank keeps the current one; TTY only).
+2. Asks for the target arch (unless `--arch`) and deletes an existing ZIP of that version, so a failed build leaves no stale ZIP.
+3. Validates the manifest (all of section 5) and checks that each `contributes[].ui` has `ui/<entry>.tsx` (or `.ts` / `.jsx` / `.js`).
+4. `vite build` of every `contributes[].ui` entry → `dist/<entry>.js`. A plugin without `contributes` builds no UI. Without Node.js 20+ (binary CLI) it asks `Build the plugin without its UI? [y/N]`; yes drops `contributes` from `dist/manifest.json`.
+5. Copies `manifest.json`, `assets/`, `README.md`, `README.<lang>.md`, `CHANGELOG.md`, `py/` and `requirements.txt` into `dist/`.
+6. Backend:
+   - python / ros2 (rclpy): resolves `requirements.txt` into `dist/requirements.lock` (`uv pip compile`, Python 3.12; pre-releases allowed when a pinned line is one) and downloads binary wheels (cp312, `--only-binary=:all:`) into `dist/wheels/` per arch. A package with no matching wheel stops the build.
+   - cpp: CMake Release build in Docker → `dist/<arch>/<entry>` plus `dist/<arch>/lib/` (`librb_sdk.so`). The CMake target name must equal `runtime.entry`.
+   - ros2: colcon build in Docker → `dist/ros2_ws/install/` (rclpy, built once) or `dist/ros2_ws/install-<arch>/` (rclcpp, per arch).
+7. Writes `installedSize` (bytes of `dist/` without `wheels/`) into `manifest.json` and `dist/manifest.json`.
+8. Packs `dist/` into `<project dir>-<version>.zip` in the project root.
+
+| Option | Meaning |
+|---|---|
+| `--arch` | `amd64` (`x86_64`), `arm64` (`aarch64`) or `both`; asked in a TTY (default both), `both` otherwise |
+
+Every runtime except `none` needs Docker. Building the other arch needs Docker emulation; on native Linux enable it once with `docker run --privileged --rm tonistiigi/binfmt --install <arch>`.
+
+### 3.5 `update`
+
+```bash
+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
+muscat-pk update 1.2.3      # a specific version (also --tag <tag> / --version <v>)
+```
+
+| Option | Meaning |
+|---|---|
+| `[tag]` | npm dist-tag or version (`latest`, `dev`, `1.2.3`). Omitted: `latest`; on a dev build it asks to stay on dev (default) or switch to stable |
+| `--global` | also update the global CLI when run from a project's local install |
+
+| Where you run it | What it updates |
+|---|---|
+| Inside a project with a local install | that project's `muscat-plugin-kit` + `plugin-ui` (+ `preview-host` when listed in `package.json`) |
+| Same, with `--global` | the above + the global CLI |
+| Anywhere else | the global CLI (npm `-g` or the S3 binary) and local deps if inside a project |
+
+- When the project's local install is older than the CLI you run, that CLI updates the project instead (project only).
+- Packages stay in their current `dependencies` / `devDependencies` section; the package manager is taken from `packageManager` or the lock file.
+- An old project layout is migrated after a `[y/N]` prompt: `src/` → `ui/` (+ `vite.config.ts`, `tsconfig.json`), `main.py` → `py/main.py`, `backend/` → `py/`.
+- Missing `.mcp.json`, `AGENTS.md`, `CLAUDE.md` are added; existing ones are kept.
+- On Windows the new binary replaces the old one on the next run.
+
+After updating it lists code that needs changes for the new `plugin-ui` (``This project needs changes for the updated plugin-ui. Fix these before `muscat-pk dev` / `build`:``). Fix them (or run `check_project` through `muscat-pk mcp`).
+
+### 3.6 `sdk`
+
+```bash
+muscat-pk sdk list               # 12 newest published versions
+muscat-pk sdk update [version]   # latest stable when omitted
+```
+
+| Backend | `list` source | `update` rewrites |
+|---|---|---|
+| python, ros2 (rclpy) | PyPI `rainbow-rb-sdk` | every `rainbow-rb-*==` pin in `requirements.txt` together (they pin each other exactly); adds `rainbow-rb-sdk==<ver>` when missing. An existing `.venv` is refreshed; the dev container installs it on the next `dev` / `dev:back` |
+| C++ (`cpp`, `ros2-cpp`) | apt `rainbow-rb-sdk-dev` (stable, numeric versions only) | `find_package(rb_sdk <ver> EXACT REQUIRED)` in `cpp/CMakeLists.txt` / `ros2_ws/src/*/CMakeLists.txt`; the dev image is rebuilt with it on the next `build` / `dev:back` |
+
+A C++ version must be digits and dots (`"<v>" is not a CMake version (digits and dots only)`).
+
+### 3.7 `storybook`, `mcp`, `completion`, `version`
+
+```bash
+muscat-pk storybook [--port 6007] [--rebuild]
+muscat-pk mcp [--install codex]
+muscat-pk completion [bash|zsh|fish|powershell]
+muscat-pk version
+muscat-pk uninstall
+```
+
+| Command / option | Meaning |
+|---|---|
+| `storybook --port` | port to serve on (default `6007`); a taken port fails with `port <n> is in use — pass a free one with --port <n>.` |
+| `storybook --rebuild` | rebuild the Storybook first (only from a repo checkout; the published kit ships it prebuilt) |
+| `mcp` | stdio MCP server (section 11). It relays to the real server (`mcp --serve`) and restarts it when the kit is updated, so a running agent session picks up the new tools |
+| `mcp --install codex` | register the server in `~/.codex/config.toml` (no-op when already there) |
+| `version` | the version of the copy that actually ran (also `-v`, `--version`) |
+| `uninstall` | npm global: `npm uninstall -g`; binary: deletes the executable. A project-local install is removed with the project's package manager instead |
+
+`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` (else `powershell` on Windows, `bash` elsewhere). Windows `cmd.exe` has no completion hook — use PowerShell, Git Bash or WSL. Optional convenience; nothing depends on it.
+
+| 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` |
+| 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 (locked into dist/requirements.lock on build)
+├─ package.json         # UI deps (not shipped)
+├─ vite.config.ts       # must use the muscat() preset
+├─ tsconfig.json
+├─ AGENTS.md, CLAUDE.md # rules for AI coding agents (CLAUDE.md → @AGENTS.md)
+├─ .mcp.json            # registers `muscat-pk mcp` for Claude Code
+├─ .gitignore
+└─ README.md            # copied into dist/ (with README.<lang>.md, CHANGELOG.md)
+```
+
+The scaffolded `requirements.txt` pins `rainbow-rb-sdk`, `rainbow-rb-flat-buffers` and `rainbow-rb-zenoh` to the same version (change it with `muscat-pk sdk update`). Generated, not committed: `node_modules/`, `dist/`, `.muscat-dev/`, `.venv/`, `*.zip`, `cpp/build*`, `ros2_ws/{install,build*,log}`.
+
+`vite.config.ts`:
+
+```ts
+import { defineConfig } from "vite";
+import tailwindcss from "@tailwindcss/vite";
+import { muscat } from "@rainbow-robotics/muscat-plugin-kit/vite";
+
+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
+
+Fully validated by `muscat-pk build` (errors: `manifest.json errors: …`). `dev` / `dev:back` check `variables` and `ports` before start, and `dev:back` prints the rest as warnings.
+
+### 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 of strings. Categories: `manipulate`, `amr`, `rby1`, `vision` |
+| `contributes` | no | see 5.3. Missing or `[]` = a backend-only plugin (no screens, no UI build) |
+| `variables` | no | see 5.5 |
+| `ports` | no | see 5.6 |
+| `runtime` | yes | see 5.7 |
+| `installedSize` | — | written by `build` (bytes) |
+
+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) |
+
+A non-empty `contributes` needs at least one `toolbar` entry (that is where the host lists the plugin). Each `ui` must have a matching `ui/<entry>.tsx` (or `.ts` / `.jsx` / `.js`), checked on `build`.
+
+| 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] }
+```
+
+| Rule | Enforced by |
+|---|---|
+| Only `28600-28999`, `number[]`, non-empty when present, no duplicates | 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 (`backend opened undeclared TCP port(s): …`) |
+| No two enabled plugins share a port | the robot, at install (HTTP 409) |
+
+- The kit's own dev ports (gateway `10000`, MediaMTX `8554` / `8889` / `8189`, the Zenoh dev peer port) and OS-assigned loopback ports are excluded.
+- The monitor can't tell plugin ports apart when the backend shares a network namespace with other services, so it is off on native Linux (`--network host`) and when the backend joins a local Muscat container (the usual `dev` without a robot). Declare them anyway — the robot checks them at install.
+- Declared ports are published on every host interface, TCP and UDP, so devices on the LAN reach them as on the robot (from the local Muscat under `dev`); a busy host port is skipped with a warning. The backend gets them as `RB_PLUGIN_PORTS`.
+
+### 5.7 `runtime`
+
+| 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 |
+
+---
+
+## 6. Plugin UI SDK (`useRb`)
+
+Package `@rainbow-robotics/plugin-ui`:
+
+| Import | Contents |
+|---|---|
+| `@rainbow-robotics/plugin-ui/react` | Muscat components (`RB*`), `useRb`, `useRbFormData`, `useRbSave`, `useRbStorage`, `createRbStore`, `RbSdk` / `RbStore` / `RbSetState` types |
+| `@rainbow-robotics/plugin-ui/sdk` | the same hooks without the components, plus `RbContext` and the `RbNotifyType` type |
+| `@rainbow-robotics/plugin-ui/manifest` | manifest types (`PluginManifest`, `PluginContribution`, `PluginVariable`, `PluginRuntime`), `CONTRIBUTION_POINTS`, `VARIABLE_TYPES`, `validateManifest` |
+
+Outside a Muscat host (a unit test, Storybook) `useRb()` returns a stub: calls log `[plugin-ui] rb.<name> called outside of a host context` and resolves to an empty value.
+
+### 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>;
+}
+```
+
+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 |
+|---|---|---|
+| `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 |
+
+```tsx
+const rb = useRb();
+
+await rb.pub("event", { clicked: true });
+
+const sub = await rb.sub<{ ready: boolean }>("state", (s) => setReady(s.ready));
+// cleanup: sub.undeclare()
+
+const res = await rb.action<{ ok: boolean }, { width: number }>("grip", { width: 20 });
+
+await rb.serve("tool/ping", (payload) => ({ pong: payload }));
+```
+
+- 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]);
+```
+
+### 6.3 Host dialogs and toast
+
+| 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" });
+}
+```
+
+### 6.4 Program page (`rb.program`)
+
+| 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) |
+| `rb.program.getCommandDefaults?(command, scope?)` | default step of a command whose defaults read the live robot (catalog `rules.hasFactoryDataFn`); optional, host-dependent |
+
+```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 };
+```
+
+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.
+
+### 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 })}
+    />
+  );
+}
+```
+
+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 { RBTextInput, 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, RBSlider } 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); `undefined` for a fresh mount |
+| `rb.onSave(getPayload)` | low-level form of `useRbSave`; returns the unregister function |
+| `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, RBRby1SDK
+from rainbow.rb_sdk.rb_sdk_cpp import ConnectOptions, PluginRouteError, RBPluginGatewayError
+```
+
+`rainbow.rb_sdk` exports `RBPluginCall`, `PluginProgramContext`, `RBManipulateSDK`, `RBAmrSDK`, `RBRby1SDK`, `RBProgramSDK`, `RBBaseSDK` and `rby1` (the vendored rby1-sdk types). Everything else (`ConnectOptions`, `PluginRouter`, `PluginRouteError`, `RBPluginGatewayError`, …) is in `rainbow.rb_sdk.rb_sdk_cpp`.
+
+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. `RBPluginCall(plugin_id=None)`: the id is the argument, else env `RB_PLUGIN_ID`, else `PLUGIN_ID` (slashes trimmed). There is one instance per process and plugin id — calling `RBPluginCall()` again returns the same object.
+
+```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)
 
-muscat-pk dev                  # UI + 백엔드 동시 실행
-muscat-pk dev:ui               # UI 미리보기만
-muscat-pk dev:back             # 백엔드만 (Python watchfiles / ROS2 Docker)
+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. One handler per key — serving it again replaces the previous one |
+| `subscribe(topic, callback=None)` | receive publishes |
+| `publish(topic, payload=None)` | push to subscribers; dropped silently while disconnected |
+| `call(keyexpr, *, payload, timeout=3.0)` | request the other side and wait; raises `RBPluginGatewayError` when disconnected or on timeout |
+| `unserve(keyexpr=None)` / `undeclare_queryable(keyexpr=None)` | remove one / all serve handlers |
+| `unsubscribe(topic=None, callback=None)` / `unsubscribe_topic(topic=None, callback=None)` | remove one callback, a topic's subscriptions, or all |
+| `plugin_id` | the plugin id in use (dev id under `muscat-pk dev`) |
+| `connected` | transport connected |
+| `data_dir` | persistent data directory, created on access: `RB_PLUGIN_DATA_DIR` (set by Muscat), else `/app/data/runtime/plugins/data/{plugin_id}`. 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. Topics are scoped like the UI's: `"state"` → `{plugin_id}/state`, a leading `/` is absolute.
+
+### 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`).
 
-muscat-pk build                # dist/ 빌드
-muscat-pk pack                 # 배포용 ZIP 생성
+```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 |
 |---|---|
-| `muscat-pk new [dir]` | 플러그인 프로젝트 스캐폴딩 |
-| `muscat-pk type change` | 백엔드 타입 전환 (python ↔ ros2) |
-| `muscat-pk build` | `src/content.tsx` → `dist/content.js` 빌드 |
-| `muscat-pk pack` | 빌드 후 배포용 ZIP 생성 |
-| `muscat-pk dev` | UI + 백엔드 동시 개발 서버 |
-| `muscat-pk dev:ui` | 미니 Muscat 미리보기 서버 |
-| `muscat-pk dev:back` | 백엔드 개발 서버 (hot-reload) |
-| `muscat-pk update` | kit + plugin-ui 최신 버전으로 업데이트 |
-| `muscat-pk sdk <list\|update>` | Python rainbow-rb-sdk 버전 관리 |
+| 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 |
 |---|---|
-| `@rainbow-robotics/plugin-ui` | UI 런타임 계약: rb-* 엘리먼트, React 바인딩, sandbox connect |
-| `@rainbow-robotics/muscat-plugin-kit` | CLI, 템플릿, 빌드/팩, 미리보기 호스트 |
+| 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 |
+| `set_execute_handler(fn)` / `set_state_change_handler(fn)` | the same two registrations without a decorator |
+| `begin_execution(robot_model=None)` / `end_execution()` | execute lifecycle hooks the SDK calls around `on_execute`; not needed in normal plugins |
+| `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.
+
+Scope of `check_stop` / `is_paused` / `is_stopped`:
 
-플러그인 ZIP에는 플러그인 코드와 에셋만 포함됩니다. `@rainbow-robotics/plugin-ui`, `react`, `react-dom`은 호스트(Muscat/로봇)의 import map에서 제공됩니다.
+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 (or against a robot that runs no Muscat), `dev` / `dev:ui` need a Muscat on `localhost:3000` (API) and `:10000` (plugin gateway):
+
+- reuses any container already publishing `:10000` (`muscat`, `muscat-dev`, …). A container not started by the kit does not publish the plugin's ports;
+- uses a Muscat already listening on those ports without a container (robot PC, host networking);
+- otherwise starts `muscat-pk-muscat` — the S3 runtime image (`muscat-pk-runtime:<version>`, from `version.json`) running `common` (plus the services `--sim` needs) and MediaMTX (`8554`, `8889`, `8189`), cached in `~/.muscat-pk/muscat/`. It is recreated when the published plugin ports or services change, and a new Muscat version replaces the old image. Its data (DB, logs, programs) lives in the container only, so a new container starts empty.
+- `dev` removes its own `muscat-pk-muscat` on exit; started by `dev:ui` alone it keeps running.
+- The backend joins the local Muscat's network namespace, so `execute` and the SDK reach it like on the robot.
+
+```bash
+docker rm -f muscat-pk-muscat          # stop it
+MUSCAT_PK_NO_LOCAL_MUSCAT=1 muscat-pk dev   # don't start it
+```
+
+Its API docs are at `http://localhost:3000/common/docs`.
+
+### 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 or when the kit's Dockerfile / build args changed (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
+```
+
+C++ / ROS 2 projects also need `muscat-pk-cpp-dev` / `muscat-pk-ros2-dev` (and the per-arch `-amd64` / `-arm64` images used by `build`). Offline, the local Muscat uses the cached `version.json` and the simulators an already pulled image.
+
+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.
+
+| Tool | Returns |
+|---|---|
+| `list_components`, `get_component_props`, `get_component_example` | plugin-ui components, their prop types, real Storybook usage |
+| `list_design_tokens`, `search_design_tokens` | design-token Tailwind classes (`bg-bg-*`, `text-fg-*`, `typo-*`) |
+| `list_rb_sdk`, `search_rb_sdk`, `get_rb_sdk_api` | Python `rainbow-rb-sdk` and C++ SDK classes / signatures / docstrings |
+| `check_project` | what an older project must change after `muscat-pk update` |
+
+Claude Code — `.mcp.json` at the plugin root (written by `new`, or by `update` when missing):
+
+```json
+{ "mcpServers": { "muscat": { "command": "muscat-pk", "args": ["mcp"] } } }
+```
+
+Codex — `muscat-pk mcp --install codex` (on Windows it writes `muscat-pk.cmd`), or `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.muscat]
+command = "muscat-pk"
+args = ["mcp"]
+```
+
+The agent starts the server itself.
+
+---
+
+## 12. Environment variables
+
+| Variable | Effect |
+|---|---|
+| `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_BUILD_CACHE=1` | build Docker images with `--no-cache` (CI) |
+| `MUSCAT_PK_HOST_NETWORK=0` | on native Linux, use the Docker Desktop (bridge) path instead of `--network host` (CI) |
+| `MUSCAT_PK_RBY1_CPUS` | CPU cap of the rby1 simulator (default `1.5`) |
+| `MUSCAT_PK_MUSCAT_S3` | where the local Muscat runtime is downloaded from (default `https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat/main`) |
+| `MUSCAT_HOST_AGENT_DISABLE=1` | don't start the host Zenoh byte-proxy (macOS / Windows / WSL against a remote robot) |
+| `MUSCAT_PROXY_PORT` | port of that proxy (default `47100`) |
+| `MUSCAT_ZENOH_ADVERTISE_HOST` / `MUSCAT_ZENOH_PORT` | LAN IP / port the remote robot dials back to (default: the route to the robot / `53917` or the next free port) |
+| `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 |
+| `CI` | set: `dev:ui` doesn't open the browser |
+| `NO_COLOR=1` / `FORCE_COLOR` | output colors |
+
+Inside the backend container: `RB_PLUGIN_ID` (the plugin / dev id), `RB_PLUGIN_PORTS` (declared `ports`, comma-separated), `MUSCAT_ROBOT_HOST` / `MUSCAT_ROBOT_TOKEN` (remote dev). On the robot Muscat also sets `RB_PLUGIN_DATA_DIR` (see `data_dir`, 7.1).
+
+---
+
+## 13. Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `manifest.json errors: …` | fix each listed field (section 5) |
+| `manifest.json variable errors: …` / `manifest.json port errors: …` on `dev` | fix `variables` (5.5) / `ports` (5.6) |
+| `A Muscat plugin dev environment is already running: …` | answer `y` to stop it, or stop the other `dev` first |
+| `Docker is installed but the daemon is not running` | start Docker Desktop (or `sudo systemctl start docker`) |
+| `contributes declares ui "<entry>" but ui/<entry>.tsx … does not exist.` | add the file or fix `contributes[].ui` |
+| `wheel download failed for <arch>` | a dependency has no cp312 binary wheel for that arch — pick another version or package |
+| `can't build <arch> on this <host>: Docker has no <arch> emulation.` | `docker run --privileged --rm tonistiigi/binfmt --install <arch>`, or `--arch <host arch>` |
+| `Permission denied when deleting dist/` | an old build left root-owned files: `sudo rm -rf dist` once |
+| 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 |
+| `RBPluginGatewayError` from `plugin.call` | the gateway is disconnected, or no reply within `timeout` (is a UI `rb.serve` registered?) |
+| 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` |