@rainbow-robotics/muscat-plugin-kit 0.1.2-dev.5 → 0.1.2-dev.50

package/cli/templates/common/README.md

@@ -1,16 +1,824 @@
 # __PLUGIN_NAME__
 
-A Muscat plugin scaffolded with `muscat-pk`.
+A Muscat plugin project. Build, develop, and ship with `muscat-pk` CLI.
+
+## Quick start
+
+```bash
+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 build      # build + distributable ZIP
+```
+
+---
+
+## Project structure
+
+```
+__PLUGIN_DIR__/
+├─ 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
+├─ 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 (`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
+
+Access the communication API between the plugin module and UI from any plugin component.
+
+```tsx
+import { useRb } from "@rainbow-robotics/plugin-ui/sdk";
+
+function App() {
+  const rb = useRb();
+}
+```
+
+### 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({ 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:
+
+```tsx
+const status = await rb.action<{ ok: boolean }, { id: number }>(
+  "get-status",
+  { id: 1 },
+);
+
+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");
+}
+```
+
+### Saving and restoring form data (`useRbFormData` / `useRbSave`)
+
+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`... */);
+}
+```
+
+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` and export a
+React component as the default export. The host mounts that component directly
+and provides `useRb()` through context.
+
+```tsx
+import { useState } from "react";
+import { RBLabelButton, RBSlider, RBSwitch } from "@rainbow-robotics/plugin-ui/react";
+import { useRb } from "@rainbow-robotics/plugin-ui/sdk";
+
+export default function App() {
+  const rb = useRb();
+  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>
+  );
+}
+```
+
+---
+
+## 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 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})
+
+
+@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_sdk import PluginProgramContext
+
+ctx = PluginProgramContext(plugin_id="my-plugin")
+
+
+@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)
+
+    # 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}")
+
+    # finish the step
+    await ctx.done()
+
+
+if __name__ == "__main__":
+    asyncio.run(ctx.start())
+```
+
+### 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;
+}
+```
+
+### 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 rainbow.rb_sdk import RBManipulateSDK
+
+sdk = RBManipulateSDK()
+
+
+class __PLUGIN_CLASS__Node(Node):
+    def __init__(self):
+        super().__init__("__PLUGIN_SLUG___node")
+        self.get_logger().info("__PLUGIN_NAME__ node started")
+        # use sdk alongside ROS2 publishers/subscribers/services as needed
+```
+
+### 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");
+  }
+};
+```
+
+---
+
+## manifest.json
+
+```jsonc
+{
+  // unique plugin ID — reverse-domain format recommended
+  "id": "com.example.my-plugin",
+  "name": "My Plugin",
+  "version": "1.0.0",
+
+  // 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": [
+    // 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
+    }
+  ],
+
+  // 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 | 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.
+
+---
+
+## Installing Python dependencies
+
+Add any package with an optional version pin to `requirements.txt`:
+
+```
+rainbow-rb-sdk
+rainbow-rb-flat-buffers
+numpy==1.26.4
+opencv-python
+```
+
+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.
+
+`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`.
+
+`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` only **pins** versions in `requirements.txt` — it does not run `pip install` (the robot installs them at load time).
+
+---
+
+## Switching backend type
 
 ```bash
-__PM__ run dev        # preview in a mini-Muscat (preview-host) + back end
-__PM__ run dev:ui     # UI preview only
-__PM__ run pack       # build a distributable ZIP
+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
 ```
 
-- `src/content.tsx` — your plugin UI. Import components from `@rainbow-robotics/plugin-ui/react`.
-- `manifest.json` — id, contributions, actions, runtime.
-- `assets/` — static assets (icons referenced from the manifest).
-- `main.py` — (sdk runtime) back-end handler using `rainbow-rb-sdk`.
+> Existing backend dirs (`ros2_ws/`, `cpp/`) are not deleted when switching away. Remove them manually if no longer needed.
+
+---
+
+## AI coding assistants (MCP)
 
-The plugin only emits `rb-*` name tags; Muscat renders the real components.
+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"]
+```
+
+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 build            # build + ZIP
+muscat-pk build --no-zip   # build only, no ZIP
+```
+
+- 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`
+
+ZIP layout:
+
+```
+__PLUGIN_DIR__-1.0.0.zip
+├─ 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
+```
+
+---
+
+## All commands
+
+```bash
+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      # 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
+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
+```