@rainbow-robotics/muscat-plugin-kit 0.1.2-dev.43 → 0.1.2-dev.45

package/cli/templates/common/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "muscat": {
+      "command": "muscat-pk",
+      "args": ["mcp"]
+    }
+  }
+}

package/cli/templates/common/README.md

@@ -18,7 +18,8 @@ muscat-pk build      # build + distributable ZIP
 ```
 __PLUGIN_DIR__/
 ├─ ui/
-│   └─ content.tsx      # plugin UI entry point
+│   ├─ content.tsx      # plugin UI entry point
+│   └─ style.css        # plugin styles auto-loaded by muscat()
 ├─ py/
 │   └─ main.py          # Python backend entry point
 ├─ assets/
@@ -34,6 +35,153 @@ __PLUGIN_DIR__/
 
 ## 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.
@@ -48,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:
 
@@ -68,33 +222,85 @@ 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.).
 
-```
-"sensor/data"   →  plugin/{pluginId}/sensor/data   (auto-namespaced)
-"/broadcast/x"  →  broadcast/x                    (leading / = absolute)
+```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`. 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);
 ```
 
 ---
@@ -119,14 +325,39 @@ robot.
 
 ---
 
-## Backend (`py/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:
 
-The backend communicates with the frontend using `rainbow.rb_sdk.RBPluginCall`.
-`muscat-pk dev` starts the Socket.IO bridge in Docker (published on port 10000) and
-runs the backend container sharing its network, so the SDK connects at localhost:10000.
-`py/main.py` should contain plugin logic only and must not start its own server.
+| 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. |
 
-### Python plugin
+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
@@ -167,25 +398,130 @@ if __name__ == "__main__":
         time.sleep(1)
 ```
 
-### ROS2 plugin
+#### 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)
 
-The node is launched with `--ros-args -r __ns:=/{slug}` automatically by `dev:back`.
+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
+```
+
+### ROS2 (rclcpp)
 
-    def timer_cb(self):
-        self.pub.publish(Float32(data=42.0))
+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");
+  }
+};
 ```
 
 ---
@@ -221,16 +557,17 @@ class __PLUGIN_CLASS__Node(Node):
   // "targetCategorys": ["manipulate", "amr", "rby1", "vision"],
 
   "contributes": [
-    // program.command — adds a step node to the program tree
+    // program.panel — defines a custom command for the Program page sequence
+    //   builder; runs via PluginProgramContext when the program reaches it
     {
-      "point": "program.command",
+      "point": "program.panel",
       "icon": "assets/icon.svg",
       "label": { "ko": "내 플러그인", "en": "My Plugin" },
-      "ui": "program/content",   // must be unique across all contributions
+      "ui": "program",           // must be unique across all contributions
       "commandInfo": {
         "name": "My Plugin",
         "icon": "assets/icon.svg",
-        "funcName": "plugin.run",
+        "funcName": "rb_program_sdk.plugin_execute",
         "args": {}
       }
     },
@@ -240,14 +577,14 @@ class __PLUGIN_CLASS__Node(Node):
       "icon": "assets/icon.svg",
       "label": { "ko": "내 플러그인", "en": "My Plugin" },
       "ui": "content",           // must be unique across all contributions
-      "opens": "popover"
+      "opens": "popover"         // popover | panel | page
     },
-    // move.rnb — adds a panel to the Move screen right-side area
+    // move.panel — adds a panel to the Move screen
     {
-      "point": "move.rnb",
+      "point": "move.panel",
       "icon": "assets/icon.svg",
       "label": { "ko": "내 플러그인", "en": "My Plugin" },
-      "ui": "move/content"       // must be unique across all contributions
+      "ui": "move"               // must be unique across all contributions
     }
   ],
 
@@ -256,7 +593,12 @@ class __PLUGIN_CLASS__Node(Node):
   //   { "type": "python", "entry": "main.py" }
   //   { "type": "cpp", "entry": "<executable name>" }
   //   { "type": "ros2", "rosClient": "rclpy" | "rclcpp", "package": "...", "launch": "..._node" }
-  "runtime": { "type": "python", "entry": "main.py" }
+  "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]
 }
 ```
 
@@ -273,17 +615,18 @@ class __PLUGIN_CLASS__Node(Node):
 
 **Contribution points:**
 
-| point | Where it appears | `commandInfo` required |
-|---|---|:---:|
-| `toolbar` | Top toolbar button (must have at least one) | — |
-| `program.command` | Program tree step node | ✓ |
-| `move.rnb` | Move screen right-side panel | — |
+| 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.command`):
+**`commandInfo` fields** (for `program.panel`):
 
 | field | type | description |
 |---|---|---|
-| `name` | `string` | Display name of the step node |
+| `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 |
@@ -308,10 +651,19 @@ class __PLUGIN_CLASS__Node(Node):
 - `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.command"`
+- `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
@@ -342,7 +694,19 @@ 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 or venv needed.
+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).
 
@@ -362,6 +726,54 @@ muscat-pk type change --to python     # → Python
 
 ---
 
+## 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"]
+```
+
+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
@@ -399,6 +811,8 @@ 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