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

package/cli/templates/common/README.md

@@ -8,7 +8,7 @@ A Muscat plugin project. Build, develop, and ship with `muscat-pk` CLI.
 muscat-pk dev        # UI preview + backend together
 muscat-pk dev:ui     # UI preview only
 muscat-pk dev:back   # backend only (Python watchfiles / ROS2 Docker)
-muscat-pk pack       # build a distributable ZIP
+muscat-pk build      # build + distributable ZIP
 ```
 
 ---
@@ -17,20 +17,47 @@ muscat-pk pack       # build a distributable ZIP
 
 ```
 __PLUGIN_DIR__/
-├─ src/
-│   └─ content.tsx      # plugin UI entry point
+├─ ui/
+│   ├─ content.tsx      # plugin UI entry point
+│   └─ style.css        # plugin styles auto-loaded by muscat()
+├─ py/
+│   └─ main.py          # Python backend entry point
 ├─ assets/
 │   └─ icon.svg         # icon referenced from manifest
 ├─ manifest.json        # metadata, contribution points, runtime config
-├─ main.py              # backend (Python or ROS2)
-└─ requirements.txt     # Python deps (auto-pinned to latest on pack)
+├─ README.md            # this file (copied to dist/ on build)
+└─ requirements.txt     # Python deps (auto-pinned to latest on build)
 ```
 
 > ROS2 plugins additionally include a `ros2_ws/` directory.
 
 ---
 
-## Frontend (`src/content.tsx`)
+## Frontend (`ui/content.tsx`)
+
+### JavaScript dependencies
+
+`muscat-pk build` runs this plugin project's own Vite build. Vite resolves
+imports from installed `node_modules`; it does not care whether a package is
+listed under `dependencies` or `devDependencies`, but the package must be
+installed.
+
+Do not run a production-only install such as `npm install --omit=dev` before
+building the plugin UI, because build tools like `vite`, `typescript`,
+`tailwindcss`, `@tailwindcss/vite`, `sass`, or `less` are usually
+`devDependencies`.
+
+The scaffold keeps this split:
+
+| package kind | examples | why |
+|---|---|---|
+| `dependencies` | `@rainbow-robotics/plugin-ui`, UI libraries imported by plugin source | Author-facing APIs used by `ui/*.tsx` |
+| `devDependencies` | `vite`, `typescript`, `tailwindcss`, `@tailwindcss/vite`, `sass`, `less` | Build/dev tools needed before `dist/*.js` is produced |
+
+The built plugin ZIP does not include `package.json` or `node_modules`. For
+production, Muscat provides `@rainbow-robotics/plugin-ui`, React, and ReactDOM
+through the host import map; plugin UI build output imports those as host
+externals.
 
 ### useRb() hook
 
@@ -46,13 +73,19 @@ function App() {
 
 ### rb API
 
-| Method | Description |
-|---|---|
-| `rb.pub(topic, payload)` | Publish a message to a topic |
-| `rb.sub(topic, handler)` | Subscribe to a topic — returns `{ undeclare() }` |
-| `rb.action(topic, payload?)` | Send a request and await a reply |
-| `rb.serve(topic, handler)` | Handle incoming requests from the backend |
-| `rb.toast(message, type?)` | Host toast notification (`"info" · "success" · "warning" · "error"`) |
+| Method                                                                                                             | Description                                                                                                                                                |
+| ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rb.pub(topic, payload)`                                                                                           | Publish a message to a topic                                                                                                                               |
+| `rb.sub(topic, handler)`                                                                                           | Subscribe to a topic — returns `{ undeclare() }`                                                                                                           |
+| `rb.action(topic, payload?)`                                                                                       | Send a request and await a reply                                                                                                                           |
+| `rb.serve(topic, handler)`                                                                                         | Handle incoming requests from the backend                                                                                                                  |
+| `rb.toast({ title?, message, type?, actionLabel?, handleActionClick?, closeOnActionClick?, duration?, onClose? })` | Show a host toast notification. `message` accepts a string or `ReactElement`. `type` can be `"info"`, `"danger"`, `"warning"`, `"caution"`, or `"success"` |
+| `rb.alert({ title?, message, buttonText? })`                                                                       | Show a host alert dialog. Resolves when the dialog is closed                                                                                               |
+| `rb.confirm({ title?, message, buttonText? })`                                                                     | Show a host confirmation dialog. `buttonText` accepts `{ yes, no }`. Resolves to `true` or `false`                                                         |
+| `rb.prompt({ title?, message, value?, placeholder?, buttonText? })`                                                | Show a host prompt dialog. `buttonText` accepts `{ yes, no }`. Resolves to the entered string or `undefined`                                               |
+
+Topic names passed to `pub`, `sub`, `action`, and `serve` are isolated per plugin.
+
 
 All methods support Generic Types:
 
@@ -66,91 +99,675 @@ const sub = await rb.sub<{ value: number }>("sensor/data", (data) => {
   console.log(data.value);
 });
 sub.undeclare(); // cleanup
+
+const ok = await rb.confirm({
+  title: "Run",
+  message: "Start the backend action?",
+});
+if (ok) {
+  await rb.action("run");
+}
 ```
 
-### Topic namespace
+### Saving and restoring your program command step (`useRbFormData` / `useRbSave`)
 
-Topics are automatically namespaced by plugin ID to prevent collisions across plugins.
+Use these only in your `program.panel` UI, where the user edits your program
+command step: `useRbFormData` gives back the values saved in the step, and
+`useRbSave` hands the current values to Muscat when the step is saved.
 
+```tsx
+import { useState } from "react";
+import { useRbFormData, useRbSave } from "@rainbow-robotics/plugin-ui/react";
+
+type GripArgs = { targetName: string; width: number };
+const DEFAULTS: GripArgs = { targetName: "", width: 20 };
+
+export default function App() {
+  // Previously-saved values, or undefined for a brand-new instance.
+  const saved = useRbFormData<GripArgs>();
+  const [args, setArgs] = useState<GripArgs>({ ...DEFAULTS, ...saved });
+
+  // Registers a getter the host calls when its Save button is clicked.
+  // Always returns the CURRENT values — re-registering on every render keeps
+  // the closure fresh, which useRbSave already handles for you.
+  useRbSave(() => ({
+    args,
+    summary: `${args.targetName || "target"} · ${args.width}mm`,
+  }));
+
+  return (/* ...form UI reading/writing `args`... */);
+}
 ```
-"sensor/data"   →  plugin/{pluginId}/sensor/data   (auto-namespaced)
-"/broadcast/x"  →  broadcast/x                    (leading / = absolute)
-```
+
+The value returned from `useRbSave` must be JSON-serialisable — the host
+persists it as-is. Not every host embeds plugins in a save/restore form; if
+yours doesn't, you can skip these hooks entirely.
 
 ### UI components
 
-Import Muscat components from `@rainbow-robotics/plugin-ui/react`. The plugin emits
-`rb-*` tags; the host renders the actual components.
+Import Muscat components from `@rainbow-robotics/plugin-ui/react` and export a
+React component as the default export. The host mounts that component directly
+and provides `useRb()` through context.
 
 ```tsx
-import { connect } from "@rainbow-robotics/plugin-ui/connect";
-import { Button, Slider, Text, Switch } from "@rainbow-robotics/plugin-ui/react";
+import { useState } from "react";
+import { RBLabelButton, RBSlider, RBSwitch } from "@rainbow-robotics/plugin-ui/react";
 import { useRb } from "@rainbow-robotics/plugin-ui/sdk";
 
-function App() {
+export default function App() {
   const rb = useRb();
-  return <Button label="Run" onPress={() => rb.action("run")} />;
+  const [width, setWidth] = useState(20);
+  const [enabled, setEnabled] = useState(true);
+
+  return (
+    <div className="flex flex-col gap-4">
+      <RBSlider
+        value={[width]}
+        min={0}
+        max={100}
+        onValueChange={(values: number[]) => setWidth(values[0] ?? 0)}
+      />
+      <RBSwitch checked={enabled} onCheckedChange={setEnabled} />
+      <RBLabelButton
+        disabled={!enabled}
+        onClick={() => rb.action("grip", { width })}
+      >
+        Grip
+      </RBLabelButton>
+    </div>
+  );
 }
-
-connect(App);
 ```
 
 ---
 
-## Backend (`main.py`)
+## Developing directly on the robot PC
+
+If you're running `muscat-pk dev` **on the robot PC itself**, Muscat already serves the
+plugin gateway on port 10000. The CLI sees that, does not start its own local Muscat, and
+your plugin backend connects to the robot's gateway — exactly what you want when
+developing on the robot.
+
+---
+
+## Several developers on one robot
+
+Against a remote robot, `muscat-pk dev` / `dev:back` run your plugin under a dev id of its own,
+`<manifest id>.dev-<user>-<random>` (printed at start; the random part is kept in `~/.muscat-pk/dev-id`).
+Two machines developing the same plugin on one robot would otherwise register the same topics on its
+gateway, and a button in one UI would silently run the other machine's backend. The UI, the backend,
+the ROS namespace and external routes (`common/plugin/<dev id>/<path>`) all use the dev id.
+
+Pass `--keep-id` to run under the manifest id instead, e.g. to test program `execute` or an external
+client that uses the real id. Then only one machine may be connected to that robot.
+
+---
+
+## Backend runtimes
+
+`manifest.json` chooses one backend runtime. `muscat-pk dev` runs backend code in
+a Docker container matching the robot environment. Backend code should contain
+plugin logic only; it should not start its own copy of the plugin gateway.
+
+### Which backend pattern? (depends on the contribution point)
+
+**How you control the robot depends on what your plugin contributes** (see
+`manifest.json` → `contributes[].point`). Don't mix these up:
+
+| Contribution point | What it is | Backend pattern |
+| --- | --- | --- |
+| `program.panel` (with `commandInfo`) | Defines a **custom command** the plugin adds to the Program page's rule-based sequence builder. The operator places it into the program tree like any built-in command (Move J, Point, Wait, …); it runs when the program reaches that step. | **`PluginProgramContext`** — integrated with the program's stop/pause and variables. See _Program command backend_ below. |
+| `toolbar` / `lnb` / `move.panel` / `program.monitor` | A live UI panel/popover the operator interacts with directly (`program.monitor` is a tab in the Program page's monitor panel, next to General / Digital I/O / Monitor / Log; it is rendered per selected task, and `rb.data` is `{ point: "program.monitor", taskId, robotModel }` — pass it as the `scope` argument of `rb.program.*` so a multi-component robot's calls hit that component's task) | Call the robot **SDK directly** (`RBManipulateSDK`, `RBAmrSDK`) from `py/main.py`, or `rb.action(...)` → your backend → SDK. **Not** a program step — there is no stop/pause/variable context. |
+
+Rule of thumb: use `PluginProgramContext` **only** for a `program.panel` command
+that runs as part of a program. To move the robot live from a toolbar/move panel,
+use the SDK — a program-step context does not apply.
+
+### Frontend-only (`none`)
+
+Use this when the plugin only has UI and calls host services:
 
-The backend communicates with the frontend using `rainbow_rb_zenoh`.
-Set the `prefix` to `plugin/{manifest.id}` to match the frontend's auto-namespace.
+```json
+{ "runtime": { "type": "none" } }
+```
+
+### Python
 
-### Python plugin
+Python plugins use `py/main.py` and can communicate with the UI through
+`rainbow.rb_sdk.RBPluginCall`.
 
 ```python
-import asyncio
-from rainbow_rb_zenoh import ZenohRouter, ZenohClient
+import time
+from rainbow.rb_sdk import RBAmrSDK, RBManipulateSDK, RBPluginCall
+
+plugin = RBPluginCall()
+
 
-router = ZenohRouter(prefix="plugin/__PLUGIN_ID__")
-client = ZenohClient()
+plugin.publish("state", {"ready": True})
 
 
-@router.subscribe("sensor/data")
-async def on_sensor(*, dict_payload, **_):
-    print("received:", dict_payload)
+@plugin.subscribe("event")
+def on_ui_event(payload=None):
+    print(payload)
 
 
-@router.queryable("get-status")
-async def get_status(req=None, **_):
-    return {"ok": True}
+@plugin.serve("tool/echo")
+def echo(payload=None):
+    return {"echo": payload}
 
 
-async def main():
-    await router.startup()
-    await asyncio.Event().wait()  # keep alive
+def call_frontend():
+    res = plugin.call("tool/ping", payload={"hello": "plugin"})
+    print(res)
+
+
+def move_j_example():
+    amr = RBAmrSDK()
+    manipulate = RBManipulateSDK()
+    return manipulate.move.call_move_j(
+        robot_model="C500920",
+        target={"tar_values": [0, 0, 0, 0, 0, 0, 0], "tar_frame": -1, "tar_unit": 0},
+    )
 
 
 if __name__ == "__main__":
-    asyncio.run(main())
+    while True:
+        time.sleep(1)
+```
+
+#### External endpoints (`plugin.router`)
+
+`plugin.serve` / `plugin.subscribe` / `plugin.publish` are **internal only** (plugin
+UI ↔ backend, plugin ↔ plugin). To expose an endpoint to the outside world —
+REST, Socket.IO, TCP, MQTT, WebRTC — use `plugin.router`. Declaring one is a
+single decorator; the running Muscat (`common`) picks it up without a restart,
+and it disappears when the plugin stops or is removed.
+
+> Requires a robot running `rainbow-rb-sdk` **0.0.9.dev5 or newer** (the SDK is
+> provided by the plugin container at runtime). On older robots `plugin.router`
+> does not exist and raises `AttributeError`.
+
+```python
+from rainbow.rb_sdk import RBPluginCall
+from rainbow.rb_sdk.plugin import PluginRouteError
+
+plugin = RBPluginCall()  # plugin_id comes from env RB_PLUGIN_ID
+
+
+@plugin.router.on("/hello")                                  # all 5 transports
+def hello(payload: dict, meta: dict):
+    return {"msg": f"hi {payload.get('name')}"}              # return value = response body
+
+
+@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")            # becomes the external status
+    ...
+
+
+@plugin.router.subscribe("/cmd", explicit_events=["tcp"])    # receive external TCP publish
+def on_cmd(payload: dict):
+    ...
+
+
+plugin.router.emit("/state", {"busy": True})                 # push to external subscribers
+```
+
+| API | Meaning | External address |
+| --- | --- | --- |
+| `router.on(path, explicit_routes=None)` | request/response handler | `common/plugin/{plugin_id}/{path}` (REST is always `POST`) |
+| `router.subscribe(topic, explicit_events=None)` | receive external publishes | external side publishes to `common/plugin/{plugin_id}/{topic}` |
+| `router.emit(topic, payload)` | plugin → external push | external side subscribes to `common/plugin/{plugin_id}/{topic}` |
+
+- The `plugin_id` prefix is added by the SDK — write only the path in plugin code.
+- Paths may have several segments (`/tool/echo`). Declaring the same path twice raises `ValueError`.
+- Transport names: `api | socket | tcp | mqtt | webrtc`. `subscribe` accepts only `tcp | mqtt | webrtc`. Unknown names raise `ValueError`.
+- `explicit_routes` / `explicit_events` of `None` means every transport. A request on a transport not listed gets 404.
+
+Handler contract:
+
+- Signature `(payload, meta)`, `(payload)` or `()` — only the arguments you declare are injected. Sync and async both work.
+- `payload`: what the caller sent (for REST: JSON body merged with query params). The shape is up to the plugin.
+- `meta`: `{"transport": "api"|"socket"|"tcp"|"mqtt"|"webrtc", "principal": dict | None}`. When the robot's login policy is on, `principal` holds the token subject. **Role checks are the plugin's job** — inspect `meta["principal"]` yourself.
+- The return value is the response body (must be JSON-serialisable). `None` → empty response.
+- Status codes: `raise PluginRouteError(code, message)`. Any other exception → 500 with `str(exc)` as the message.
+- `subscribe` handlers take `(payload)` only and return nothing.
+
+#### Calling plugin endpoints from outside
+
+| Transport | How |
+| --- | --- |
+| REST | `POST /common/plugin/{plugin_id}/{path}` (through the api-gateway), JSON body |
+| Socket.IO | emit event `common/plugin/{plugin_id}/{path}`, response arrives in the ack |
+| TCP | topic `common/plugin/{plugin_id}/{path}` request / publish |
+| MQTT | request: `common/plugin/{plugin_id}/{path}/__req__`, publish: `common/plugin/{plugin_id}/{topic}` |
+| WebRTC | data channel topic `common/plugin/{plugin_id}/{path}` |
+
+Auth: when the robot's login policy is on, a token is **required** (any role — GUEST passes). When it is off, calls go straight through. REST uses the same Bearer token as the other Muscat APIs.
+
+```bash
+curl -s -X POST http://<robot>/common/plugin/my-plugin/hello \
+  -H 'Content-Type: application/json' -d '{"name":"kim"}'
+```
+
+| Situation | Status |
+| --- | --- |
+| No plugin declares that path / plugin is down / transport not allowed | 404 |
+| Plugin did not answer within 10 s | 504 |
+| `common` ↔ gateway not connected | 503 |
+| Handler raised | 500 (`PluginRouteError` → its `code`) |
+
+Known limits:
+
+- A plugin path named `install` cannot be called over REST (`POST /common/plugin/{id}/install` is taken by the registry install route first). Socket/TCP are unaffected.
+- Swagger shows one catch-all route, not per-plugin paths.
+- The MQTT broker echoes to the sender: a plugin that `emit`s and `subscribe`s the same topic receives its own push over `mqtt`. Drop `mqtt` from `explicit_events` or use separate topics. (TCP is filtered by `sender_id`.)
+- `on` and `subscribe` may share a name — they live in separate tables.
+
+During `muscat-pk dev` the local Muscat runtime takes the `router.*` registrations
+on its gateway (port `10000`), and its `common` (port `3000`) routes
+`common/plugin/...` to them like on the robot — try
+`curl http://localhost:3000/common/plugin/<plugin-id>/<path>`. After restarting the plugin process,
+external calls may return 504 for up to about a minute (until the gateway notices
+the old socket is gone), then 404 — that is expected.
+
+#### Program command backend (`program.panel`)
+
+A `program.panel` contribution defines a **custom command** your plugin adds to
+the Muscat **Program page**, where the operator builds a robot program as a
+rule-based sequence (a program tree). Your command appears alongside the
+built-ins (Move J, Point, Wait, …); the operator places it into the tree, and
+each time the program executes that step the host calls your backend through
+`PluginProgramContext` — receiving the step args, checking for stop/pause,
+reading/writing program variables, and signalling completion. This pattern is
+**only** for `program.panel`; a toolbar/move-panel plugin uses the SDK directly
+instead (see the table above).
+
+```python
+"""
+Plugin backend main.py example (program.panel command).
+
+manifest.json:
+  "runtime": {"type": "python", "entry": "main.py"},
+  "contributes": [{
+    "point": "program.panel",
+    "ui": "program",
+    "label": {"en": "My Plugin Step"},
+    "commandInfo": {
+      "name": "My Plugin Step",
+      "icon": "assets/icon.svg",
+      "funcName": "rb_program_sdk.plugin_execute",
+      "args": {"message": "hello"}   # plugin-author-defined args
+    }
+  }]
+
+The host invokes commandInfo.funcName (rb_program_sdk.plugin_execute) with
+args.plugin_id + your args when the program reaches this step.
+"""
+import asyncio
+from rainbow.rb_sdk import PluginProgramContext
+
+ctx = PluginProgramContext(plugin_id="my-plugin")
+
+
+@ctx.on_execute
+async def handle(args: dict) -> None:
+    """Called once when my Step executes. Variable writes apply to the
+    running program immediately + broadcast to other robots' main tasks."""
+    count = await ctx.get_variable("counter")          # read an existing program variable
+    await ctx.set_variable("counter", count + 1)       # update an existing variable — allowed
+    await ctx.set_variable("RBP_TEST", 1)              # NEW variables must start with RBP_
+
+    for i in range(100):
+        await ctx.check_stop()   # auto-scoped to this Step's robot model
+        await asyncio.sleep(0.5)
+
+    await ctx.done()
+
+
+async def background_monitor() -> None:
+    """Resident task outside any Step. If no program is running,
+    get returns None and set is silently ignored — always safe to call."""
+    while True:
+        await asyncio.sleep(1.0)
+
+        # targets every running main task (no robot_model param — always broadcast)
+        await ctx.set_variable("RBP_TEST", 3)
+
+        # get options
+        v1 = await ctx.get_variable("counter")                           # first value found in the whole tree
+        v2 = await ctx.get_variable("counter", robot_model="C500920")    # a specific robot
+        v3 = await ctx.get_variable("RBP_TEST", plugin_id="my-plugin")   # the value my-plugin last wrote
+
+        if ctx.executor_state("C500920") == "paused":
+            print("C500920 program is paused")
+
+
+async def main() -> None:
+    asyncio.create_task(background_monitor())
+    await ctx.start()  # stays resident
+
+
+asyncio.run(main())
+```
+
+#### Program variables & executor state (`PluginProgramContext`)
+
+`rainbow.rb_sdk.PluginProgramContext` lets the plugin process interact with the
+running program (PyFM): read/write program variables and observe execution
+state — inside a Step handler or from a resident task, at any time.
+
+- The `on_execute` handler is called **only when PyFM executes this plugin's
+  Step**. One Step execution = one handler call, and the Step does not finish
+  until you call `ctx.done()` — always call it.
+- The plugin process itself stays resident after `ctx.start()`; executor state
+  queries and variable access below keep working whether or not a Step is
+  executing.
+
+#### Variable naming rules (important)
+
+PyFM variables are a **program-wide shared namespace**. One rule:
+
+- **Modifying an existing variable** — the name passes as-is. Exchanging
+  variables between the program and the plugin is the intended usage.
+- **Creating a variable that doesn't exist** — the `RBP_` prefix is
+  **required** (enforced by the SDK/server; a violation raises
+  `RuntimeError`). Applies equally inside and outside Step execution.
+
+For new variable names, a convention that includes the plugin id is strongly
+recommended:
+
+```
+RBP_{plugin_id}_{name}
+
+e.g. RBP_vision_detect_count, RBP_gripper_last_error
+```
+
+Why:
+
+- `RBP_` — instantly identifies plugin-created variables in the program
+  editor/UI.
+- `{plugin_id}` — **prevents name collisions with other plugins.** If two
+  plugins use the same name they overwrite the same variable (`RBP_` alone is
+  not something the SDK guards against).
+
+#### Reading / writing variables
+
+```python
+value = await ctx.get_variable("counter")                 # read (no name restriction)
+await ctx.set_variable("counter", value + 1)              # modify existing variable — allowed
+await ctx.set_variable("RBP_my-plugin_result", 42)        # create new variable — RBP_ required
+```
+
+`set_variable` always applies to **every running main task** (a plugin belongs
+to muscat, not to a specific robot — there is no `robot_model` parameter):
+
+| When | Own program | Other robots' main tasks |
+|---|---|---|
+| During own Step execution | via the control queryable — **immediate** | broadcast — each at its next Step boundary |
+| Outside a Step (resident task, …) | resident endpoint — next Step boundary | same |
+
+`get_variable` has options:
+
+```python
+await ctx.get_variable("counter")                          # search all main tasks (first value found)
+await ctx.get_variable("counter", robot_model="C500920")   # a specific robot's value
+await ctx.get_variable("RBP_TEST", plugin_id="A.plugin")   # the value that plugin last wrote
+```
+
+Caveats:
+
+- If no program is running, `set_variable` is **silently ignored** and
+  `get_variable` returns `None`. (`RuntimeError` is raised only for real
+  errors, like the `RBP_` violation on a new variable — the message is tagged
+  `[plugin:{id}]` with the offending plugin.)
+- Rarely, a write can be lost if it races the worker's variable flush
+  (lock-free read-modify-write). For important values, re-check and retry on
+  the next cycle.
+
+#### Per-plugin value storage (meta)
+
+Besides the shared value, each variable entry records which plugin last wrote
+what:
+
+```python
+# state_dict["variables"] — after A wrote 1 and B wrote 2
+"RBP_TEST": {
+    "value": 2,                                # shared slot = last written value
+    "type": "local",
+    "meta": {"writers": {"A.plugin": 1, "B.plugin": 2}},   # per-plugin record
+}
+```
+
+So the exact value is recoverable even when names collide:
+
+- Plugin SDK: `ctx.get_variable("RBP_TEST", plugin_id="A.plugin")` → `1`
+- Program step expression: `COUNT = get_var("A.plugin", "RBP_TEST") + 1` → `2`
+- A plain name (`RBP_TEST += 1`) uses the shared slot (last written value) → `3`
+
+#### Executor state
+
+Subscribes to the `muscat/executor/state` publish (0.8 s interval) and exposes
+per-robot-model state:
+
+```python
+ctx.executor_state("C500920")   # "running" | "paused" | "waiting" | ... | None
+ctx.executor_state()            # {"C500920": "paused", "amr": "running"}
+ctx.is_paused("C500920")        # whether that model is paused
+ctx.is_stopped("C500920")       # stop/error transition of a model seen active this run
+```
+
+- States: `idle | running | paused | waiting | stopped | post_start | completed | error`
+- A model with no running task is `None` / absent from the dict.
+- The publish interval is 0.8 s, so expect up to ~1 s of latency.
+- With `IS_DEV=true` there is no publish at all — always `None`.
+
+To get a callback at the moment the state changes, without polling:
+
+```python
+@ctx.on_executor_state_change
+async def on_change(robot_model: str, state: str) -> None:
+    if state == "paused":
+        print(f"{robot_model} paused")
+```
+
+- Not called for repeated publishes of the same state — fires exactly once
+  per per-model state change.
+- An exception in the handler is only logged; state tracking keeps running.
+
+#### Responding to pause / stop
+
+```python
+@ctx.on_execute
+async def handle(args: dict) -> None:
+    for i in range(100):
+        # stop → CancelledError (propagated to the executor as a stop),
+        # pause → waits here until resumed.
+        # Inside on_execute this automatically watches only the robot model
+        # executing this Step.
+        await ctx.check_stop()
+
+        ...  # actual work
+        await asyncio.sleep(0.5)
+
+    await ctx.done()
 ```
 
-### ROS2 plugin
+Scope priority for `check_stop` / `is_paused` / `is_stopped`:
 
-The node is launched with `--ros-args -r __ns:=/{slug}` automatically by `dev:back`.
-ROS2 topics are bridged to the plugin communication layer — no extra code needed.
+1. `robot_model` given — that model only
+2. Omitted inside `on_execute` — **only the model executing this Step**
+   (passed in by the executor)
+3. Omitted elsewhere (resident task, …) — all models
+
+A handler doing long-running work must call `check_stop()` every loop
+iteration so it reacts to pause/stop immediately. Without it, the plugin keeps
+running even after the operator presses Stop.
+
+Variables your plugin wants the Program page variable picker to offer must be
+pre-declared in `manifest.json` under `"variables"` (see the manifest section
+below).
+
+### C++
+
+C++ plugins use `cpp/` and are built with CMake inside Docker against the
+Rainbow Robotics C++ SDK (see _C++ SDK_ below).
+
+```cpp
+#include <chrono>
+#include <cstdlib>
+#include <iostream>
+#include <string>
+#include <thread>
+
+int main() {
+  const char* plugin_id = std::getenv("RB_PLUGIN_ID");
+  std::cout << "[__PLUGIN_NAME__] backend ready"
+            << (plugin_id ? std::string(" (id=") + plugin_id + ")" : "")
+            << std::endl;
+
+  while (true) {
+    std::this_thread::sleep_for(std::chrono::seconds(1));
+  }
+  return 0;
+}
+```
+
+#### C++ SDK (`rainbow-rb-sdk-dev`)
+
+Both C++ runtimes (`cpp`, `ros2` + `rclcpp`) link the Rainbow Robotics C++ SDK
+from the apt package `rainbow-rb-sdk-dev`. The `muscat-pk` dev containers already
+have it, so `muscat-pk dev` / `build` need nothing extra. To build outside the
+container (your own Ubuntu 24.04 machine, or the robot PC):
+
+```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
+```
+
+- CMake: `find_package(rb_sdk REQUIRED)` + `target_link_libraries(<target> rb_sdk::rb_sdk)` (C++20). pkg-config: `rb_sdk`.
+- Headers: `<rainbow/rb_sdk/manipulate/rb_manipulate_sdk.hpp>` (`RBManipulateSDK`),
+  `<rainbow/rb_sdk/program/plugin_program_context.hpp>` (`rb_plugin::PluginProgramContext`, for `program.panel` commands — the header's top comment has a full `main()` example).
+- The binary is linked **dynamically**; `muscat-pk build` copies the matching `librb_sdk.so` into `dist/<arch>/lib/` (the robot has no SDK installed), so each plugin keeps the SDK version it was built with. The version is the one pinned in `CMakeLists.txt` (`find_package(rb_sdk <version> EXACT REQUIRED)`); change it with `muscat-pk sdk update <version>`.
+- UI ↔ backend messaging works from C++ too: `rb_plugin::RBPluginCall` in `<rainbow/rb_sdk/plugin/rb_plugin.hpp>` (see the scaffolded `cpp/main.cpp`).
+
+### ROS2 (rclpy)
+
+ROS2 Python plugins use `ros2_ws/` with `runtime.rosClient: "rclpy"`. relative topic names are placed under the plugin's ROS namespace — the plugin id
+with "." → "/" and "-" → "_" (`com.example.my-plugin` → `/com/example/my_plugin`), in dev
+and on the robot. Use an absolute name (`/cmd_vel`) for topics shared with other nodes.
+`RBPluginCall` works in the node module too (UI messaging and `plugin.router`).
 
 ```python
 # ros2_ws/src/__PLUGIN_SLUG__/__PLUGIN_SLUG__/node.py
 import rclpy
 from rclpy.node import Node
-from std_msgs.msg import Float32
+from rainbow.rb_sdk import RBManipulateSDK
+
+sdk = RBManipulateSDK()
+
 
 class __PLUGIN_CLASS__Node(Node):
     def __init__(self):
         super().__init__("__PLUGIN_SLUG___node")
-        # relative topic name — __ns prefix applied automatically
-        self.pub = self.create_publisher(Float32, "sensor_data", 10)
-        self.create_timer(1.0, self.timer_cb)
+        self.get_logger().info("__PLUGIN_NAME__ node started")
+        # use sdk alongside ROS2 publishers/subscribers/services as needed
+```
+
+
+#### Talking to an external PC over ROS 2
+
+ROS 2 discovery stays on the robot (`ROS_AUTOMATIC_DISCOVERY_RANGE=LOCALHOST`; `muscat-pk dev`
+runs the same), so robots on one LAN don't mix topics. Allow specific PCs from the plugin UI —
+Muscat keeps the list per plugin, starts your backend with `ROS_STATIC_PEERS` set to it, and
+restarts the plugin when it changes. Your ROS code needs no changes; the PC needs no extra settings.
+
+```tsx
+const rb = useRb();
+const peers = await rb.rosPeers.get();               // ["192.168.0.50"]
+await rb.rosPeers.set(["192.168.0.50", "192.168.0.51"]); // saves + restarts the plugin; rejects on a bad IP
+```
+
+- Per plugin: plugin B keeps its allowed PCs when plugin A (allowing the same PC) is stopped or removed.
+- It opens communication; it is not access control — a PC that knows the robot's IP can still
+  add the robot to its own `ROS_STATIC_PEERS`.
+- In `muscat-pk dev` the list is kept in `.muscat-dev/ros-peers.json` (ROS 2 backends).
+
+### ROS2 (rclcpp)
+
+ROS2 C++ plugins use `ros2_ws/` with `runtime.rosClient: "rclcpp"`. The node links
+the Rainbow C++ SDK the same way as the `cpp` runtime (see _C++ SDK_ above).
+
+```cpp
+#include "rclcpp/rclcpp.hpp"
+
+class __PLUGIN_CLASS__Node : public rclcpp::Node {
+public:
+  __PLUGIN_CLASS__Node() : Node("__PLUGIN_SLUG___node") {
+    RCLCPP_INFO(this->get_logger(), "__PLUGIN_NAME__ node started");
+  }
+};
+```
+
+---
+
+## Video streaming (MediaMTX)
+
+Muscat runs a MediaMTX media server. The backend publishes a stream over RTSP and
+the UI plays it over WebRTC. `muscat-pk dev` runs the same server (or uses a local
+Muscat's), so the addresses are identical in dev and on the robot.
+
+| | Address |
+| --- | --- |
+| Publish (backend) | `rtsp://127.0.0.1:8554/<plugin_id>/<name>` |
+| Play (UI) | `http://<host>:8889/<plugin_id>/<name>/` |
+
+- Prefix the path with your plugin id — paths are shared with robot cameras and other plugins.
+- The robot runtime has no ffmpeg, GStreamer or OpenCV; bring your own encoder (below).
 
-    def timer_cb(self):
-        self.pub.publish(Float32(data=42.0))
+**Backend (Python)** — use PyAV: add `av` and `numpy` to `requirements.txt`. Its wheels
+include FFmpeg, so they ship in the ZIP like any other dependency.
+
+```python
+import fractions, time
+import av, numpy as np
+
+out = av.open("rtsp://127.0.0.1:8554/__PLUGIN_ID__/cam", mode="w", format="rtsp",
+              options={"rtsp_transport": "tcp"})
+stream = out.add_stream("libx264", rate=25, options={"preset": "ultrafast", "tune": "zerolatency"})
+stream.width, stream.height, stream.pix_fmt = 640, 360, "yuv420p"
+
+i = 0
+while True:
+    img = np.zeros((360, 640, 3), dtype=np.uint8)          # your RGB frame here
+    frame = av.VideoFrame.from_ndarray(img, format="rgb24")
+    frame.pts, frame.time_base = i, fractions.Fraction(1, 25)
+    for packet in stream.encode(frame):
+        out.mux(packet)
+    i += 1
+    time.sleep(1 / 25)
+```
+
+Run the encoder loop in a thread (or `asyncio.to_thread`) so it doesn't block the
+`RBPluginCall` handlers.
+
+**UI** — embed MediaMTX's WebRTC player. `location.hostname` is `localhost` in the
+preview and the robot's address on the robot:
+
+```tsx
+const STREAM = "__PLUGIN_ID__/cam"; // the path the backend publishes
+
+export default function Camera() {
+  return (
+    <iframe
+      src={`${location.protocol}//${location.hostname}:8889/${STREAM}/`}
+      allow="autoplay"
+      className="aspect-video w-full border-0"
+    />
+  );
+}
 ```
 
 ---
@@ -159,30 +776,186 @@ class __PLUGIN_CLASS__Node(Node):
 
 ```jsonc
 {
-  "id": "com.example.my-plugin",   // unique plugin ID (reverse-domain recommended)
+  // unique plugin ID — reverse-domain format recommended
+  "id": "com.example.my-plugin",
   "name": "My Plugin",
   "version": "1.0.0",
-  "minAppVersion": "2.0.0",
-  "icon": "assets/icon.svg",
+
+  // minimum Muscat version required to load this plugin
+  "minMuscatVersion": "1.0.0",
+
+  // plugin author (empty string is fine)
+  "author": "Your Name",
+
+  // displayed in the Muscat plugin store / info panel
+  // string or { en (required), ko, ja, zh, vi, th, es }
+  "description": { "en": "Plugin description", "ko": "플러그인 설명" },
+
+  // SVG string (single file) or PNG/JPG size map (all three sizes required)
+  "icons": "assets/icon.svg",
+  // "icons": { "16": "assets/icon-16.png", "48": "assets/icon-48.png", "128": "assets/icon-128.png" },
+
+  // targetModels and/or targetCategorys — at least one is required
+  // "all" = every target, or list specific values
+  "targetModels": "all",
+  // "targetModels": ["C500920", "C500930"],
+  "targetCategorys": "all",
+  // "targetCategorys": ["manipulate", "amr", "rby1", "vision"],
 
   "contributes": [
-    { "point": "program.panel", "label": "My Plugin", "icon": "assets/icon.svg" },
-    { "point": "lnb",           "label": "My Plugin", "icon": "assets/icon.svg" },
-    { "point": "header.toolbar","label": "My Plugin", "icon": "assets/icon.svg", "opens": "popover" }
+    // program.panel — defines a custom command for the Program page sequence
+    //   builder; runs via PluginProgramContext when the program reaches it
+    {
+      "point": "program.panel",
+      "icon": "assets/icon.svg",
+      "label": { "ko": "내 플러그인", "en": "My Plugin" },
+      "ui": "program",           // must be unique across all contributions
+      "commandInfo": {
+        "name": "My Plugin",
+        "icon": "assets/icon.svg",
+        "funcName": "rb_program_sdk.plugin_execute",
+        "args": {}
+      }
+    },
+    // toolbar — adds a button to the top toolbar (required)
+    {
+      "point": "toolbar",
+      "icon": "assets/icon.svg",
+      "label": { "ko": "내 플러그인", "en": "My Plugin" },
+      "ui": "content",           // must be unique across all contributions
+      "opens": "popover"         // popover | panel | page
+    },
+    // move.panel — adds a panel to the Move screen
+    {
+      "point": "move.panel",
+      "icon": "assets/icon.svg",
+      "label": { "ko": "내 플러그인", "en": "My Plugin" },
+      "ui": "move"               // must be unique across all contributions
+    }
+  ],
+
+  // optional: variables this plugin exposes to pyfm programs — the Program
+  // page variable picker lists ONLY declared variables. name must start with
+  // RBP_; description is optional but without it the UI can't explain the
+  // variable, so write one.
+  "variables": [
+    { "name": "RBP_grip_force", "type": "number", "init": 0.5, "description": { "ko": "그리퍼 힘", "en": "Gripper force" } },
+    { "name": "RBP_target_pose", "type": "array", "init": [0, 0, 0] }
   ],
 
-  // "python" | "ros2"
-  "runtime": { "type": "python", "entry": "main.py" }
+  // runtime — one of:
+  //   { "type": "none" }
+  //   { "type": "python", "entry": "main.py" }
+  //   { "type": "cpp", "entry": "<executable name>" }
+  //   { "type": "ros2", "rosClient": "rclpy" | "rclcpp", "package": "...", "launch": "..._node" }
+  "runtime": { "type": "python", "entry": "main.py" },
+
+  // optional: TCP ports opened by this plugin backend
+  // only number[] is allowed; ranges/objects are not accepted
+  // external plugin ports must be within 28600-28999
+  "ports": [28600]
 }
 ```
 
+**Backend types:**
+
+| type | source dir | build / run | entry |
+|---|---|---|---|
+| `python` | `py/` | pip + run in Docker | `main.py` |
+| `cpp` | `cpp/` | CMake in Docker | built executable name |
+| `ros2` (rclpy) | `ros2_ws/` | colcon (ament_python) in Docker | — |
+| `ros2` (rclcpp) | `ros2_ws/` | colcon (ament_cmake) in Docker | — |
+
+> Every back end runs in a Docker container matching the robot (Ubuntu 24.04 + Python 3.12), so dev behaves like production and compiled binaries are ABI-compatible. **Docker is required** for all backend types (only a frontend-only `none` plugin skips it). No local Python/toolchain setup is needed.
+
 **Contribution points:**
 
-| point | Where it appears |
-|---|---|
-| `program.panel` | Program panel tab |
-| `lnb` | Left navigation bar |
-| `header.toolbar` | Header toolbar button |
+| point | Where it appears | Backend | `commandInfo` |
+|---|---|---|:---:|
+| `toolbar` | Top toolbar button (must have at least one) | SDK / `rb.action` | — |
+| `lnb` | Left navigation entry | SDK / `rb.action` | — |
+| `move.panel` | Move screen panel | SDK / `rb.action` | — |
+| `program.panel` | Custom command in the Program page sequence builder | `PluginProgramContext` | ✓ |
+
+**`commandInfo` fields** (for `program.panel`):
+
+| field | type | description |
+|---|---|---|
+| `name` | `string` | Display name of the command in the program tree |
+| `icon` | `string` | Icon path |
+| `iconClassName` | `string?` | Optional CSS class for the icon |
+| `funcName` | `string?` | Backend function name to call |
+| `args` | `Record<string, any>?` | Default arguments |
+| `disabled` | `boolean?` | Whether the node is disabled |
+| `allowChildren` | `string[]?` | Allowed child commands |
+| `allowParents` | `string[]?` | Allowed parent commands |
+| `notAllowChildren` | `string[]?` | Disallowed child commands |
+| `syncGroupId` | `boolean?` | Sync group ID across children |
+| `disableCopy` | `boolean?` | Prevent copy |
+| `disableDelete` | `boolean?` | Prevent delete |
+| `requireChildren` | `boolean?` | Whether a child command is required |
+| `requireParent` | `boolean?` | Whether a parent command is required |
+| `childrenCommand` | `string?` | Default command type for children |
+
+**Validation rules:**
+- `id`, `name`, `version`, `minMuscatVersion` — required non-empty strings
+- `author` — required non-empty string
+- `description` — required (`string` or `{ en (required), ko?, ja?, zh?, vi?, th?, es? }`)
+- `icons` — SVG: single string path ending in `.svg`; PNG/JPG: object with `"16"`, `"48"`, `"128"` all present
+- `targetModels` — `"all"` or a non-empty array of robot model ID strings (at least one of `targetModels` / `targetCategorys` required)
+- `targetCategorys` — `"all"` or a non-empty array of `"manipulate" | "amr" | "rby1" | "vision"` (at least one of `targetModels` / `targetCategorys` required)
+- `contributes` — the plugin's screens; when present it must contain at least one `toolbar` entry. Leave it out (or `[]`) for a backend-only plugin: no UI is built, and Node.js is not needed to build it
+- `ui` — each contribution must have a unique value
+- `commandInfo` — required when `point` is `"program.panel"`
+- `ports` — optional `number[]`; every port must be within `28600-28999`
+  and must not be a reserved robot/industrial/internal port
+- `variables` — optional array of `{ name, type, init, description? }`:
+  - `name` — must start with `RBP_`, then letters/digits/underscore; unique per plugin
+  - `type` — `"number" | "string" | "array"`
+  - `init` — required initial value, must match `type`
+  - `description` — optional `string` or i18n object (`en` required in object form)
+
+`muscat-pk build` throws on any validation error. `muscat-pk dev` prints
+warnings — except `variables` errors (e.g. a name without the `RBP_` prefix),
+which are hard errors in `dev` / `dev:back` too.
+
+**Backend port rules:**
+- Declare a port only if your backend opens a TCP server/listener.
+- **Every listening TCP port must be declared.** `muscat-pk dev` and
+  `muscat-pk dev:back` watch the backend and stop it the moment it opens a port
+  that is not in `ports`. A port outside `28600-28999` can't be declared, so it
+  must not be opened either — picking e.g. `5500` is not a way around the rule.
+  It would escape this check *and* the robot's install-time conflict check, and
+  only collide once it's running on a robot.
+- Reserved ports include `502`, `2222`, `4840`, `5170-5179`, `8000-8999`,
+  `10000`, `30004`, `34964`, `44818`, `50000-50005`, and `50051`.
+- The robot rejects installation (HTTP 409) if a declared port is reserved,
+  out of range, or already claimed by another enabled plugin.
+
+**Reaching your backend's ports during development:**
+- Declared ports are published to `127.0.0.1` on your machine, so
+  `curl http://127.0.0.1:28600` works from the host on macOS, Windows, and Linux.
+- On native Linux the dev container uses host networking, so the ports are on
+  the host already.
+- If a declared port is already taken on your machine, `muscat-pk dev` warns and
+  skips publishing that one — the backend still listens inside the container.
+
+---
+
+## Localized documentation
+
+You can ship per-language README files alongside the main `README.md`. Place them in the project root:
+
+```
+README.md        # default / English fallback
+README.ko.md     # Korean
+README.en.md     # explicit English (optional)
+README.ja.md     # Japanese
+```
+
+All `README*.md` files found at the project root are automatically copied to `dist/` on
+`muscat-pk build`. Muscat displays the file matching the user's locale,
+falling back to `README.md` if none matches.
 
 ---
 
@@ -197,37 +970,119 @@ numpy==1.26.4
 opencv-python
 ```
 
-Then just run `muscat-pk dev` or `muscat-pk dev:back` — dependencies are installed automatically on every startup:
+Run `muscat-pk dev` or `muscat-pk dev:back` — dependencies are installed automatically
+inside the dev container (`pip install -r requirements.txt`) on every startup. No
+local Python is required for this.
 
-- **Python plugin**: installed into `.venv` via `pip install -r requirements.txt`
-- **ROS2 plugin**: installed inside the Docker container via `pip install -r requirements.txt`
+`muscat-pk dev:back` also best-effort creates/refreshes a local `.venv` in the
+background (via `uv` if available, else your system Python) with the same deps —
+purely so your editor (pylint, pyright, mypy, ...) can resolve imports and lint
+correctly. It's not used to run the backend; Docker is the actual execution
+environment, so this step is silently skipped if no local Python toolchain is
+available. Point your editor's Python interpreter at `.venv`.
 
-No extra steps needed.
+`muscat-pk sdk update` also refreshes `.venv` in place if one already exists, so
+your editor picks up the new `rainbow-rb-sdk` version immediately.
 
-> `muscat-pk build` / `muscat-pk pack` only **pins** versions in `requirements.txt` — it does not run `pip install`.
+> `muscat-pk build` only **pins** versions in `requirements.txt` — it does not run `pip install` (the robot installs them at load time).
 
 ---
 
 ## Switching backend type
 
 ```bash
-muscat-pk type change             # interactive
-muscat-pk type change --to ros2   # python → ros2
-muscat-pk type change --to python # ros2 → python
+muscat-pk type change                 # interactive
+muscat-pk type change --to cpp        # → C++
+muscat-pk type change --to ros2       # → ROS2 (rclpy / Python)
+muscat-pk type change --to ros2-cpp   # → ROS2 (rclcpp / C++)
+muscat-pk type change --to python     # → Python
+```
+
+> Existing backend dirs (`ros2_ws/`, `cpp/`) are not deleted when switching away. Remove them manually if no longer needed.
+
+> Switching between a Python and a C++ backend asks whether to replace this README with the matching one (the old file is kept as `README.md.bak`). Add `--readme` to answer yes without the prompt.
+
+---
+
+## AI coding assistants (MCP)
+
+If you build your plugin with an AI assistant (Claude Code, Codex, …), give it
+grounded knowledge of the Muscat UI components, design tokens, and SDK instead of
+letting it guess. `muscat-pk mcp` is an MCP server exposing:
+
+- `list_components` / `get_component_props` / `get_component_example` — every
+  `@rainbow-robotics/plugin-ui/react` component with its real props and a working
+  Storybook example.
+- `list_design_tokens` / `search_design_tokens` — the Tailwind classes to use
+  (`bg-bg-*`, `text-fg-*`, `typo-*`, …) so your UI matches the host theme.
+- `search_rb_sdk` — how to use `useRb()`, `rb.*`, `useRbFormData`/`useRbSave`, and
+  the backend runtimes.
+- `list_rb_sdk` / `get_rb_sdk_api` — the installed `rainbow-rb-sdk` (Python
+  backend) classes and signatures; with `lang: "cpp"`, the C++ SDK headers
+  (`rainbow-rb-sdk-dev`, read out of the `muscat-pk` cpp dev image — build it
+  once with `muscat-pk dev:back`).
+- `check_project` — what this project must change for the plugin-ui it has
+  installed (old APIs such as `connect(App)` or `Slider`, a `vite.config` without
+  the `muscat()` preset, `tsc` errors), the same list `muscat-pk update` prints.
+  Ask the assistant to fix the project after an update; it re-checks until clean.
+
+**Browse the components live** with `muscat-pk storybook`.
+
+`muscat-pk new` also writes `AGENTS.md` (read by Codex, Cursor, Gemini CLI, Copilot)
+and a `CLAUDE.md` that imports it: the UI rules (plugin-ui components instead of
+native `<select>`/`<input>`/`<button>`, design tokens for colors) for assistants that
+do not call the MCP tools on their own. Add your own project notes there.
+
+### Register the server
+
+**Claude Code** — a `.mcp.json` is already scaffolded at your plugin root, so
+it works out of the box:
+
+```json
+{
+  "mcpServers": {
+    "muscat": {
+      "command": "muscat-pk",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+**Codex** — register once with:
+
+```bash
+muscat-pk mcp --install codex
+```
+
+This appends the server to `~/.codex/config.toml` (idempotent — safe to run
+again). Equivalent manual config:
+
+```toml
+[mcp_servers.muscat]
+command = "muscat-pk"
+args = ["mcp"]
 ```
 
-> `ros2_ws/` is not deleted when switching back to python. Remove it manually if no longer needed.
+Any other MCP client works too — it's a standard stdio MCP server started with
+`muscat-pk mcp`. If `muscat-pk` isn't on the client's PATH, use its absolute path
+(`which muscat-pk`) as `command`.
 
 ---
 
 ## Shipping
 
 ```bash
-muscat-pk pack
+muscat-pk build   # build + ZIP
 ```
 
-- Builds `src/content.tsx` → `dist/content.js`
+> Building the other arch (e.g. arm64 on an amd64 PC) runs in an emulated container for
+> C++ backends. Docker Desktop has it built in; on Linux enable it once with
+> `docker run --privileged --rm tonistiigi/binfmt --install all`, or pass `--arch` for one arch.
+
+- Builds `ui/content.tsx` → `dist/content.js` (minified)
 - Pins `requirements.txt` to latest versions (stable-only on `main` branch)
+- Copies `assets/`, `manifest.json`, `README*.md`, `py/`, and `requirements.txt` into `dist/`
 - ROS2: runs `colcon build` inside the Jazzy container; includes `ros2_ws/install/`
 - Output: `__PLUGIN_DIR__-{version}.zip`
 
@@ -235,10 +1090,15 @@ ZIP layout:
 
 ```
 __PLUGIN_DIR__-1.0.0.zip
-├─ dist/             # built UI
-├─ main.py
-├─ requirements.txt  # pinned
-└─ ros2_ws/install/  # ROS2 only
+├─ dist/
+│   ├─ content.js        # built UI
+│   ├─ manifest.json
+│   ├─ assets/
+│   ├─ README.md
+│   ├─ README.ko.md      # if present
+│   ├─ main.py           # from py/
+│   └─ requirements.txt  # pinned
+└─ ros2_ws/install/      # ROS2 only
 ```
 
 ---
@@ -249,8 +1109,9 @@ __PLUGIN_DIR__-1.0.0.zip
 muscat-pk dev        # UI + backend
 muscat-pk dev:ui     # UI preview only (preview-host)
 muscat-pk dev:back   # backend only (Python: watchfiles / ROS2: Docker)
-muscat-pk build      # UI build only → dist/
-muscat-pk pack       # build + ZIP
+muscat-pk build      # build → dist/ + distributable ZIP
+muscat-pk storybook  # browse the rb-components UI library in a browser
+muscat-pk mcp        # MCP server for AI assistants (components/tokens/SDK docs)
 ```
 
 ```bash
@@ -258,4 +1119,130 @@ muscat-pk type change    # switch backend type
 muscat-pk sdk list       # show current Python SDK version
 muscat-pk sdk update     # update Python SDK to latest
 muscat-pk update         # update muscat-plugin-kit itself
+muscat-pk uninstall      # remove muscat-pk itself
+```
+
+---
+
+## Styles
+
+`muscat()` automatically loads `ui/style.{css,scss,sass,less}` (or
+`ui/styles.{css,scss,sass,less}`) for every UI entry, plus
+`ui/{entry}.{css,scss,sass,less}` for a matching entry-specific stylesheet. You
+do not need to import CSS from every `.tsx` file.
+
+The scaffold uses Tailwind's theme/utilities layers only, so plugin utilities
+are generated from files under `ui/` without applying Tailwind preflight resets
+to the host page.
+
+Built CSS selectors are scoped under the current plugin id
+(`[data-muscat-plugin-id="..."]`). CSS-in-JS libraries such as Emotion work
+normally, but global styles should be scoped by the author.
+
+### Tailwind
+
+This template enables Tailwind in `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 default `ui/style.css` uses Tailwind theme/utilities only, not preflight:
+
+```css
+@layer theme, utilities;
+
+@import "tailwindcss/theme.css" layer(theme);
+@import "tailwindcss/utilities.css" layer(utilities);
+
+@source "./**/*.{ts,tsx}";
+```
+
+### SCSS, Sass, and Less
+
+Install the preprocessor package, then create one of the auto-loaded style files.
+
+```bash
+npm i -D sass
 ```
+
+```scss
+/* ui/style.scss */
+$accent: #3b82f6;
+
+.panel {
+  border: 1px solid color-mix(in srgb, $accent 40%, transparent);
+
+  &__title {
+    color: $accent;
+  }
+}
+```
+
+For Less, install `less` and use `ui/style.less`.
+
+### Emotion
+
+Emotion dependencies may be in `dependencies` or `devDependencies`; Vite can
+bundle them when they are installed and imported by the plugin.
+
+For `styled`, no Vite config change is needed:
+
+```bash
+npm i @emotion/react @emotion/styled
+```
+
+```tsx
+import styled from "@emotion/styled";
+
+const Panel = styled.div({
+  display: "grid",
+  gap: 12,
+});
+```
+
+For Emotion's `css` prop, pass React plugin options through `muscat()` and add
+`jsxImportSource` to `tsconfig.json`:
+
+```bash
+npm i @emotion/react @emotion/styled
+npm i -D @emotion/babel-plugin
+```
+
+```ts
+// vite.config.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({
+      react: {
+        jsxImportSource: "@emotion/react",
+        babel: {
+          plugins: ["@emotion/babel-plugin"],
+        },
+      },
+    }),
+  ],
+});
+```
+
+```json
+{
+  "compilerOptions": {
+    "jsxImportSource": "@emotion/react"
+  }
+}
+```
+
+Emotion `Global` writes global CSS at runtime, so scope it manually or avoid it
+inside plugins.