@rainbow-robotics/muscat-plugin-kit 0.1.2-dev.8 → 1.0.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,170 @@ 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.
+
+### 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.
 
 ### useRb() hook
 
@@ -46,13 +196,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 +222,306 @@ 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 form data (`useRbFormData` / `useRbSave`)
 
-Topics are automatically namespaced by plugin ID to prevent collisions across plugins.
+If the host embeds your plugin in a form it owns (e.g. a program step editor
+with its own Save button), it can hand your plugin previously-saved values and
+pull the current values back out when the user saves. The host — not the
+plugin — persists the data (IndexedDB, backend, etc.).
 
+```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);
+---
+
+## Developing directly on the robot PC
+
+If you're running `muscat-pk dev` **on the robot PC itself**, Muscat is likely already
+running its own Socket.IO bridge on port 10000. In that case the CLI detects the port
+conflict and asks:
+
+```
+⚠ port 10000 is already in use — can't start Socket.IO bridge.
+  Proceed without Socket.IO bridge? [y/N]:
 ```
 
+Answer **y**. Your plugin backend will connect to the Muscat bridge that's already
+running instead of starting a new one — exactly what you want when developing on the
+robot.
+
+> If you answer **n** (or just press Enter), the CLI exits so you can free the port
+> manually and retry.
+
 ---
 
-## Backend (`main.py`)
+## 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 the Muscat bridge or 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` | A live UI panel/popover the operator interacts with directly | 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:
+
+```json
+{ "runtime": { "type": "none" } }
+```
+
+### Python
+
+Python plugins use `py/main.py` and can communicate with the UI through
+`rainbow.rb_sdk.RBPluginCall`.
+
+```python
+import time
+from rainbow.rb_sdk import RBAmrSDK, RBManipulateSDK, RBPluginCall
+
+plugin = RBPluginCall()
+
+
+plugin.publish("state", {"ready": True})
 
-The backend communicates with the frontend using `rainbow_rb_zenoh`.
-Set the `prefix` to `plugin/{manifest.id}` to match the frontend's auto-namespace.
 
-### Python plugin
+@plugin.subscribe("event")
+def on_ui_event(payload=None):
+    print(payload)
+
+
+@plugin.serve("tool/echo")
+def echo(payload=None):
+    return {"echo": payload}
+
+
+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], "tar_frame": 0, "tar_unit": 0},
+    )
+
+
+if __name__ == "__main__":
+    while True:
+        time.sleep(1)
+```
+
+#### 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_zenoh import ZenohRouter, ZenohClient
+from rainbow.rb_sdk import PluginProgramContext
 
-router = ZenohRouter(prefix="plugin/__PLUGIN_ID__")
-client = ZenohClient()
+ctx = PluginProgramContext(plugin_id="my-plugin")
 
 
-@router.subscribe("sensor/data")
-async def on_sensor(*, dict_payload, **_):
-    print("received:", dict_payload)
+@ctx.on_execute
+async def handle(args: dict) -> None:
+    message = args.get("message", "")
+    print(f"[my-plugin] execute called: message={message}", flush=True)
 
+    # check stop/pause during long-running work
+    for _ in range(10):
+        await ctx.check_stop()
+        await asyncio.sleep(0.1)
 
-@router.queryable("get-status")
-async def get_status(req=None, **_):
-    return {"ok": True}
+    # read a program variable
+    counter = await ctx.get_variable("counter")
+    print(f"[my-plugin] counter={counter}", flush=True)
 
+    # update a variable
+    await ctx.set_variable("result", f"done: {message}")
 
-async def main():
-    await router.startup()
-    await asyncio.Event().wait()  # keep alive
+    # finish the step
+    await ctx.done()
 
 
 if __name__ == "__main__":
-    asyncio.run(main())
+    asyncio.run(ctx.start())
 ```
 
-### ROS2 plugin
+### C++
+
+C++ plugins use `cpp/` and are built with CMake inside Docker. The current C++
+template is a build/run skeleton; wire it to the plugin gateway when the C++ SDK
+is available.
+
+```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;
+}
+```
 
-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.
+### ROS2 (rclpy)
+
+ROS2 Python plugins use `ros2_ws/` with `runtime.rosClient: "rclpy"`. The node
+is launched with `--ros-args -r __ns:=/{slug}` automatically by `dev:back`.
 
 ```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
+```
 
-    def timer_cb(self):
-        self.pub.publish(Float32(data=42.0))
+### ROS2 (rclcpp)
+
+ROS2 C++ plugins use `ros2_ws/` with `runtime.rosClient: "rclcpp"`.
+
+```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");
+  }
+};
 ```
 
 ---
@@ -159,30 +530,156 @@ 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
+    }
   ],
 
-  // "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` — required array; must contain at least one `toolbar` entry
+- `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
+
+`muscat-pk build` throws on any validation error. `muscat-pk dev` prints warnings.
+
+**Backend port rules:**
+- Declare a port only if your backend opens a TCP server/listener.
+- `muscat-pk dev` and `muscat-pk dev:back` stop the backend if it opens an
+  undeclared managed port.
+- Reserved ports include `502`, `2222`, `4840`, `5170-5179`, `8000-8999`,
+  `10000`, `30004`, `34964`, `44818`, `50000-50005`, and `50051`.
+
+---
+
+## 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 +694,96 @@ 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.
+
+---
+
+## 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.
+
+**Browse the components live** with `muscat-pk storybook`.
+
+### 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** — add to `~/.codex/config.toml`:
+
+```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
+muscat-pk build --no-zip   # build only, no ZIP
 ```
 
-- Builds `src/content.tsx` → `dist/content.js`
+- 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 +791,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 +810,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 (--no-zip to skip)
+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 +820,5 @@ 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
 ```