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

package/README.md

@@ -111,6 +111,7 @@ Install the ZIP from the robot's Muscat plugin page.
 | `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 |
@@ -134,9 +135,15 @@ muscat-pk new [dir] [--type python|cpp|ros2|ros2-cpp] [--pm npm|yarn|pnpm|bun]
 | `--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` |
+| `--no-install` | skip `<pm> install`, the IDE `.venv` and the C++ dev image |
+| `--help` | print the usage |
 
-Python projects also get an IDE-only `.venv` (see [9.6](#96-ide-support-python)).
+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`
 
@@ -144,25 +151,67 @@ Python projects also get an IDE-only `.venv` (see [9.6](#96-ide-support-python))
 muscat-pk type change [--to python|cpp|ros2|ros2-cpp] [--readme]
 ```
 
-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.
+| 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>] [--keep-id]
-muscat-pk dev:ui     [--robot-ip <ip>] [--port <n>] [--keep-id]
-muscat-pk dev:back   [--keep-id]
+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` | 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` | 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) |
 
-- Robot IP comes from `--robot-ip`, `MUSCAT_ROBOT_HOST`, or a prompt (leave blank for local).
+| 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.
-- The manifest is validated before start; undeclared listening ports stop the backend (see [5.6](#56-ports)).
+- 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 |
+|---|---|---|
+| `500880`, `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 (`500880` → C500880, `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: 500880, 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`
 
@@ -172,18 +221,23 @@ muscat-pk build [--arch amd64|arm64|both]
 
 Steps:
 
-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.
+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` | target arch; asked in a TTY, `both` otherwise |
+| `--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`
 
@@ -191,25 +245,41 @@ Steps:
 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` |
+| 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 (and local deps if inside a project) |
+| 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 UI code that still uses removed APIs. Fix them (or run `check_project` through `muscat-pk mcp`).
+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               # published rainbow-rb-sdk versions
-muscat-pk sdk update [version]   # latest when omitted
+muscat-pk sdk list               # 12 newest published versions
+muscat-pk sdk update [version]   # latest stable when omitted
 ```
 
-- 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`.
+| 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`
 
@@ -218,9 +288,19 @@ muscat-pk storybook [--port 6007] [--rebuild]
 muscat-pk mcp [--install codex]
 muscat-pk completion [bash|zsh|fish|powershell]
 muscat-pk version
+muscat-pk uninstall
 ```
 
-`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.
+| 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 |
 |---|---|
@@ -243,12 +323,18 @@ my-plugin/
 ├─ ros2_ws/             # colcon workspace               — ros2 / ros2-cpp type
 ├─ assets/icon.svg
 ├─ manifest.json
-├─ requirements.txt     # python deps (pinned on build)
+├─ 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
-└─ README.md            # copied into dist/
+├─ 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
@@ -265,7 +351,7 @@ The ZIP contains only the plugin's own code and assets. `@rainbow-robotics/plugi
 
 ## 5. manifest.json
 
-Validated by `muscat-pk dev`, `dev:back` and `build`.
+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
 
@@ -303,11 +389,12 @@ Validated by `muscat-pk dev`, `dev:back` and `build`.
 | `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 |
+| `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`.
 
@@ -322,7 +409,7 @@ i18n object: `en` is required; allowed keys `ko`, `en`, `ja`, `zh`, `vi`, `th`,
 | `opens` | toolbar only: `popover`, `panel`, `page` |
 | `commandInfo` | required for `program.panel` (5.4) |
 
-At least one `toolbar` entry is required.
+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 |
 |---|---|
@@ -384,12 +471,14 @@ A backend that opens a TCP listener must declare every port:
 
 | Rule | Enforced by |
 |---|---|
-| Only `28600-28999`, `number[]` | manifest validation |
+| 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 |
+| 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`, 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.
+- 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 `127.0.0.1` (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`
 
@@ -409,8 +498,11 @@ 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 |
+| `@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
 
@@ -561,7 +653,7 @@ await rb.storage.local.set("theme", "dark");
 #### `useRbStorage` — one stored value as React state
 
 ```tsx
-import { useRbStorage } from "@rainbow-robotics/plugin-ui/react";
+import { RBTextInput, useRbStorage } from "@rainbow-robotics/plugin-ui/react";
 
 type Draft = { name: string };
 
@@ -581,7 +673,7 @@ function Editor() {
 Define once at module level, use from any screen of the plugin:
 
 ```tsx
-import { createRbStore } from "@rainbow-robotics/plugin-ui/react";
+import { createRbStore, RBSlider } from "@rainbow-robotics/plugin-ui/react";
 
 type Settings = {
   speed: number;
@@ -635,7 +727,8 @@ persist(fn, { name: "settings", storage: createJSONStorage(() => rb.storage.loca
 
 | API | Meaning |
 |---|---|
-| `rb.data` | host-provided mount data (`program.monitor` scope, saved form values) |
+| `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 |
 
@@ -646,11 +739,12 @@ persist(fn, { name: "settings", storage: createJSONStorage(() => rb.storage.loca
 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
+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 |
@@ -660,7 +754,7 @@ Which API depends on the contribution point:
 
 ### 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`.
+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()
@@ -681,18 +775,18 @@ res = plugin.call("tool/ping", payload={"hi": 1}, timeout=3.0)   # UI: rb.serve(
 
 | Member | Meaning |
 |---|---|
-| `serve(keyexpr, handler=None)` | request/response handler; decorator or direct call. Return value = reply |
+| `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 |
-| `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 |
+| `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. Survives updates and restarts; removed with the plugin. The install directory (cwd) is replaced on every update — keep state, caches and settings here |
+| `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.
+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
 
@@ -818,6 +912,8 @@ asyncio.run(main())
 | `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 |
 
@@ -928,16 +1024,21 @@ sudo apt update && sudo apt install rainbow-rb-sdk-dev
 
 ### 9.1 Local Muscat runtime
 
-Without a robot IP, `dev` / `dev:ui` need a Muscat on `localhost:3000`:
+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`, …);
-- otherwise starts `muscat-pk-muscat` — the S3 runtime image running only `common`, cached in `~/.muscat-pk/muscat/`. It keeps running between runs.
+- 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.
+- `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.
@@ -952,13 +1053,15 @@ If the project has its own `muscat-plugin-kit` in `node_modules`, any `muscat-pk
 
 ### 9.5 Offline / air-gapped
 
-Docker images are built only when missing (a rebuild contacts the registry even when cached).
+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)
@@ -1006,13 +1109,20 @@ and `"jsxImportSource": "@emotion/react"` in `tsconfig.json`. Emotion `Global` i
 
 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:
+| 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`, or `~/.codex/config.toml`:
+Codex — `muscat-pk mcp --install codex` (on Windows it writes `muscat-pk.cmd`), or `~/.codex/config.toml`:
 
 ```toml
 [mcp_servers.muscat]
@@ -1033,12 +1143,20 @@ The agent starts the server itself.
 | `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 |
-| `NO_COLOR` / `FORCE_COLOR` | output colors |
+| `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).
+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).
 
 ---
 
@@ -1047,10 +1165,18 @@ Inside the backend container: `RB_PLUGIN_ID` (the plugin / dev id).
 | 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_` |

package/cli/README.md

@@ -229,8 +229,10 @@ inside plugins.
   at `/plugin-dev` — a real mini-Muscat shell. Without a robot IP it needs a Muscat
   on `localhost:3000` for program preview: `dev` / `dev:ui` reuse any container that
   already publishes `:10000` (`muscat`, `muscat-dev`, …) and otherwise start
-  `muscat-pk-muscat` — the S3 runtime image (`muscat/main/muscat.zip`) running only the
+  `muscat-pk-muscat` — the S3 runtime image (`muscat/main/muscat.zip`) running the
   `common` service from `muscat/main/version.json`, cached under `~/.muscat-pk/muscat/`.
+  `dev --sim <model>` adds the services the model needs (log + manipulate / rby1), opens
+  common's Zenoh on the `muscat-pk` network, and starts simulators there (`cli/src/sim.mjs`).
   It keeps running between runs (`docker rm -f muscat-pk-muscat` to stop);
   `MUSCAT_PK_NO_LOCAL_MUSCAT=1` disables it.
 

package/cli/bin/muscat-pk.mjs

@@ -88,7 +88,7 @@ function formatHelp() {
     commandRow("new [dir]", `Scaffold a new plugin project ${color.dim("(prompts: author, email, description, type, front-package-manager)")}`),
     commandRow("type change", `Switch backend type ${color.dim("(python | cpp | ros2-python | ros2-cpp)")}`),
     commandRow("build", `Build + lock deps + vendor wheels + zip ${color.dim(`(${option("--arch")} amd64|arm64|both)`)}`),
-    commandRow("dev", "Run a local Muscat runtime, dev:ui, and dev:back together"),
+    commandRow("dev", `Run a local Muscat runtime, dev:ui, and dev:back together ${color.dim(`(${option("--sim")} 500880|500920|RBY2|rby1-a|rby1-m|rby1-ub)`)}`),
     commandRow("dev:ui", `Preview the plugin in a mini-Muscat ${color.dim("(preview-host)")}`),
     commandRow("dev:back", `Run the plugin back end ${color.dim("(python: watchfiles reload / ros2: Docker)")}`),
     commandRow("storybook", `Browse the bundled rb-components Storybook ${color.dim(`(${option("--port")} <n>, ${option("--rebuild")})`)}`),
@@ -96,6 +96,7 @@ function formatHelp() {
     commandRow("update", `Update ${color.magenta("@rainbow-robotics/muscat-plugin-kit")}, ${color.magenta("@rainbow-robotics/plugin-ui")} and ${color.magenta("@rainbow-robotics/preview-host")} ${color.dim(`(local-only if run from a project's local install; ${option("--global")} also updates the global CLI)`)}`),
     commandRow("uninstall", `Remove the installed ${color.cyan("muscat-pk")} CLI ${color.dim("(npm global or S3 binary)")}`),
     commandRow("sdk <list|update [version]>", "Manage the python rainbow-rb-sdk version"),
+    commandRow("sim list", `List the robot simulators for ${option("dev --sim")}`),
     commandRow("version", `Print the installed ${color.cyan("muscat-pk")} version`),
     commandRow("completion [shell]", `Print a shell completion script ${color.dim("(bash | zsh | fish | powershell)")}`),
     "",
@@ -137,6 +138,9 @@ async function main() {
         return await runUninstall(args);
       case "sdk":
         return await runSdk(args);
+      case "sim":
+        if (args[0] !== "list") throw new Error("usage: muscat-pk sim list");
+        return (await import("../src/sim.mjs")).runSimList();
       case "completion":
         return await runCompletion(args);
       case "version":

package/cli/src/completion.mjs

@@ -20,6 +20,7 @@ const COMMANDS = [
   ["update", "Update muscat-pk and plugin-ui"],
   ["uninstall", "Remove the installed muscat-pk CLI"],
   ["sdk", "Manage the rainbow-rb-sdk version (python: requirements.txt, C++: CMakeLists.txt)"],
+  ["sim", "List the robot simulators for dev --sim"],
   ["version", "Print the installed muscat-pk version"],
   ["completion", "Print a shell completion script"],
   ["help", "Show help"],
@@ -28,6 +29,7 @@ const COMMANDS = [
 const SUBCOMMANDS = {
   type: ["change"],
   sdk: ["list", "update"],
+  sim: ["list"],
   completion: ["bash", "zsh", "fish", "powershell"],
 };
 

package/cli/src/dev.mjs

@@ -1,4 +1,5 @@
-// muscat-pk dev — run the local Muscat runtime (gateway, MediaMTX, common), dev:ui, and dev:back together.
+// muscat-pk dev — run the local Muscat runtime (gateway, MediaMTX, common), robot simulators (--sim),
+// dev:ui, and dev:back together.
 import { spawn, spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { connect as netConnect } from "node:net";
@@ -7,6 +8,7 @@ import { fileURLToPath } from "node:url";
 import { runDevUi } from "./devUi.mjs";
 import { claimDevSession, stopDevBackContainers } from "./devSession.mjs";
 import { ensureLocalMuscat, GATEWAY_PORT, isPortInUse, MUSCAT_CONTAINER, robotHasMuscat } from "./muscatLocal.mjs";
+import { resolveSim, startSim, stopSims } from "./sim.mjs";
 import { assertManifestPorts, assertManifestVariables, readManifest } from "./manifest.mjs";
 import { devPluginId } from "./devId.mjs";
 import {
@@ -14,6 +16,7 @@ import {
   ensureIdeVenv,
   findPluginRoot,
   log,
+  parseArgs,
   prompt,
   promptRobotConnection,
   venvPython,
@@ -129,13 +132,24 @@ export async function runDev(args = []) {
   // the robot itself — the local Muscat then publishes the zenoh port for it.
   if (!proxyEndpoint) await ensureRemoteZenohEnv(robotIp, { log });
 
+  // No robot: a simulator stands in for it (--sim, else the manifest's target).
+  const sim = remoteRobot ? null : resolveSim(parseArgs(args).sim, readManifest(root));
+
   // A robot running Muscat is the gateway (:10000) and common for both the UI and the backend.
   // Otherwise the local Muscat runtime is; the backend joins its netns, so the plugin's declared
   // ports are published from it too.
   const muscat = (await robotHasMuscat(robotIp)) ? null : await ensureLocalMuscat({
     pluginPorts: portRanges,
     zenohPort: remoteRobot && !proxyEndpoint ? Number(process.env.MUSCAT_ZENOH_PORT) || null : null,
+    services: sim?.services,
+    env: sim?.env,
   }).catch((e) => { log.warn(`local Muscat: ${e.message}`); return null; });
+  if (sim && muscat !== MUSCAT_CONTAINER) {
+    log.warn(`--sim needs muscat-pk's own Muscat${muscat ? ` ('${muscat}' is running — stop it to use the simulator)` : ""}; no simulator.`);
+  } else if (sim) {
+    // dev:ui then serves the real Muscat UI against the local Muscat, like with muscat-dev.
+    if (await startSim(sim).catch((e) => log.warn(`simulator: ${e.message}`))) process.env.MUSCAT_PK_SIM = sim.name;
+  }
   if (muscat) {
     process.env.MUSCAT_PK_MUSCAT_CONTAINER = muscat;
   } else if (remoteRobot || (await isPortInUse(GATEWAY_PORT))) {
@@ -161,7 +175,10 @@ export async function runDev(args = []) {
     if (backend.exitCode === null) backend.kill();
     stopDevBackContainers();
     // Only our own runtime — a muscat-dev the user started stays up.
-    if (muscat === MUSCAT_CONTAINER) spawnSync("docker", ["rm", "-f", MUSCAT_CONTAINER], { stdio: "ignore" });
+    if (muscat === MUSCAT_CONTAINER) {
+      stopSims();
+      spawnSync("docker", ["rm", "-f", MUSCAT_CONTAINER], { stdio: "ignore" });
+    }
   };
   process.once("SIGINT", cleanup);
   process.once("SIGTERM", cleanup);

package/cli/src/devBack.mjs

@@ -61,7 +61,7 @@ function muscatZenohEnv(container) {
 
 function backendNetwork(portRanges, robotGateway) {
   const muscat = process.env.MUSCAT_PK_MUSCAT_CONTAINER;
-  if (muscat) return { run: ["--network", `container:${muscat}`], env: muscatZenohEnv(muscat), shared: true };
+  if (muscat) return { run: ["--network", `container:${muscat}`, "--ipc", "host"], env: muscatZenohEnv(muscat), shared: true };
   // The robot runs Muscat: its gateway, own netns (host network on Linux), declared ports published.
   if (robotGateway) {
     const run = usesHostNetwork() ? ["--network", "host"] : publishPortFlags(portRanges);

package/cli/src/devUi.mjs

@@ -214,7 +214,8 @@ export async function runDevUi(args = []) {
     });
   }
 
-  const localDevMuscat = await localFullMuscat(robotIp);
+  // muscat-dev, or our own Muscat with a simulator (`dev --sim`): a full local Muscat to show.
+  const localDevMuscat = !!process.env.MUSCAT_PK_SIM || (await localFullMuscat(robotIp));
   const uiHost = isRemoteRobot(robotIp) ? robotIp : localDevMuscat ? "localhost" : "";
 
   const previewRoot = findPreviewHostRoot();