agenticros 0.0.1 → 0.1.1

package/runtime/docs/memory.md

@@ -0,0 +1,292 @@
+# Memory
+
+AgenticROS ships an **optional**, **off-by-default** cross-adapter semantic memory subsystem. When enabled, OpenClaw, Claude Code MCP, Claude Desktop (via MCP), and Gemini CLI all expose the same four tools — `memory_remember`, `memory_recall`, `memory_forget`, `memory_status` — backed by a **shared, file-backed store**. The default namespace is the robot namespace, so every adapter talking to the same robot sees the same memories across processes, sessions, and restarts.
+
+When disabled (the default), the memory tools are not registered at all. There are no new dependencies, no new files on disk, and no behavior change for existing users.
+
+> **Cross-process out of the box.** With the `mem0` backend, the underlying `mem0ai/oss` package writes to `~/.mem0/vector_store.db` (SQLite + vectors) so a fact you remember from Claude Desktop is immediately recall-able from OpenClaw — and vice versa — without any extra setup or running server. With the `local` backend, the shared file is `~/.agenticros/memory.json`. See [Cross-adapter behavior](#cross-adapter-behavior) below.
+
+---
+
+## When to enable
+
+Useful when:
+
+- You use **multiple AI agents** with the same robot (e.g. OpenClaw on desktop + Claude Code on your phone via Claude Dispatch). Each agent sees what the others learned.
+- You want **facts to persist across sessions** (preferences, room layouts, names, routines) without re-explaining them every conversation.
+- You want the robot to **build up environment knowledge** over time ("the rug in the hallway is fragile", "the cat gets startled by fast turns").
+
+Not necessarily worth it when:
+
+- You only ever talk to the robot in single one-shot sessions.
+- Your needs fit in a static system prompt or config file.
+
+---
+
+## The four tools
+
+| Tool | Use |
+|---|---|
+| `memory_remember` | Store a fact: `{ content, tags?, path?, namespace? }`. Returns the persisted record id. |
+| `memory_recall` | Search by free-text query: `{ query, limit?, namespace? }`. Returns ranked matches. |
+| `memory_forget` | Delete: `{ id }`, `{ query, namespace }`, or `{ namespace }`. Irreversible. |
+| `memory_status` | Health check: `{ enabled, backend, namespace, recordCount, lastWriteAt, embedder? }`. |
+
+Tool descriptions in each adapter remind the agent to **store selectively** — memory is for facts the user wants remembered, not for transcribing every conversation.
+
+---
+
+## Namespace
+
+By default the namespace is `config.robot.namespace`, so memories are scoped per robot. Override with `config.memory.namespace` (e.g. to share across robots, or to scope per-user). Tools also accept a one-off `namespace` argument.
+
+| Scenario | Effective namespace |
+|---|---|
+| Default | `config.robot.namespace` |
+| Per-user override | Set `config.memory.namespace` to the user id |
+| Per-call override | Pass `namespace` in the tool args |
+
+> Heads up: with the default, two robots **never** see each other's memories. With a shared override, all robots with that namespace do.
+
+---
+
+## Backends
+
+| Backend | Deps | Search quality | Best for |
+|---|---|---|---|
+| `local` (default when enabled) | None | Keyword + recency | Zero-friction setup, "remember this fact" style use |
+| `mem0` | `pnpm add mem0ai` + an embedder | Semantic | Production, fuzzy recall ("what did I say about the kitchen?") |
+
+Both store data on the local filesystem. No cloud is involved unless you point `mem0`'s embedder/LLM at one.
+
+---
+
+## Recipes
+
+### Recipe 1: local (zero deps)
+
+Edit `~/.agenticros/config.json` (or use the OpenClaw config UI at `/agenticros/config`):
+
+```json
+{
+  "memory": {
+    "enabled": true,
+    "backend": "local"
+  }
+}
+```
+
+Restart the gateway (OpenClaw) or just the next tool call (Claude Code MCP re-reads config on every call; Gemini reads on every invocation).
+
+That's it. Memories live in `~/.agenticros/memory.json`.
+
+### Recipe 2: `mem0` + OpenAI (cloud embedder)
+
+```bash
+pnpm add mem0ai
+export OPENAI_API_KEY=sk-...
+```
+
+```json
+{
+  "memory": {
+    "enabled": true,
+    "backend": "mem0"
+  }
+}
+```
+
+The factory auto-detects the OpenAI key and configures the embedder as `text-embedding-3-small`. Operational data is written under `~/.mem0/` (persistent SQLite + vector store, shared across all processes on this host) and the operation history audit log lives at `~/.agenticros/memory-history.db`.
+
+### Recipe 3: `mem0` + Ollama (fully local)
+
+```bash
+pnpm add mem0ai
+ollama pull nomic-embed-text
+```
+
+```json
+{
+  "memory": {
+    "enabled": true,
+    "backend": "mem0",
+    "mem0": {
+      "embedder": {
+        "provider": "ollama",
+        "config": { "model": "nomic-embed-text" }
+      }
+    }
+  }
+}
+```
+
+The factory detects Ollama running at `http://localhost:11434` and uses it for embeddings. Nothing leaves the host.
+
+---
+
+## Cross-adapter behavior
+
+Memories are stored on the **local filesystem** and indexed by namespace. Any process on the same host that uses the same backend, same namespace, and same store paths sees the same memories.
+
+| Adapter | When it picks up new memories |
+|---|---|
+| **OpenClaw plugin** | At the start of the next chat session (the system context refetches the recently-remembered list every `before_agent_start`). For live `memory_recall` calls, immediately. |
+| **Claude Code MCP** | Immediately on every tool call (config is reloaded on each call). |
+| **Claude Desktop (MCP)** | Same as Claude Code — fresh tool call sees fresh data. |
+| **Gemini CLI** | Each `agenticros-gemini` invocation is a fresh process; it sees everything written so far. |
+
+Files written when memory is enabled:
+
+- `~/.mem0/vector_store.db` — mem0's SQLite + vectors (mem0 backend only).
+- `~/.mem0/config.json` — mem0 internal config (mem0 backend only).
+- `~/.agenticros/memory-history.db` — mem0 operation history audit log (mem0 backend only; path configurable via `memory.mem0.historyDbPath`).
+- `~/.agenticros/memory.json` — JSON store for the local backend (path configurable via `memory.local.storePath`).
+
+To clear everything for a namespace: use the OpenClaw config UI's **Clear all in namespace** button, or call `memory_forget` from any adapter with no `id` and no `query` (just the namespace).
+
+### Verifying cross-process sharing works
+
+```bash
+# From any adapter, e.g. Claude Desktop:
+"Remember that the robot has a RealSense D435i for its eyes."
+
+# Then, from OpenClaw chat in a browser tab:
+"What do I have for eyes?"
+```
+
+OpenClaw should answer **from memory** (no `ros2_camera_snapshot`, no ROS topic query). If it instead reaches for ROS tools, that means the chat session was opened **before** the fact was stored — close the chat and start a new one so the system context can refresh.
+
+### OpenClaw chat context injection
+
+When the OpenClaw plugin starts each chat session and memory is enabled, the plugin injects a short **Memory** section into the system prompt:
+
+- Instructions telling the LLM to call `memory_recall` **before** answering personal-context questions like *"what do I have for X"*, *"what's my Y"*, *"where is the Z"*.
+- A snapshot of up to 10 **recently-remembered** facts (newest first), so the most common personal-context questions can be answered **without** a tool call.
+
+The snapshot is produced via the new `MemoryProvider.recent(namespace, limit)` method on `@agenticros/core`. Both backends implement it; for the `mem0` backend it uses `memory.getAll({ filters: { user_id: namespace } })` and sorts by `created_at` desc.
+
+---
+
+## Smart-defaults auto-detection
+
+When `backend === "mem0"` and you have **not** set `memory.mem0.embedder`, the factory probes:
+
+1. Ollama at `http://localhost:11434/api/tags` (200 ms timeout). On success, embedder defaults to `{ provider: "ollama", config: { model: "nomic-embed-text" } }`.
+2. Otherwise, `OPENAI_API_KEY` in the environment. On success, embedder defaults to `{ provider: "openai", config: { model: "text-embedding-3-small" } }`.
+3. Otherwise, throws a single-line actionable error pointing you back here.
+
+If you want explicit control, set `memory.mem0.embedder` and the auto-detection is bypassed.
+
+---
+
+## `inferOnWrite`: raw store vs LLM extraction
+
+`mem0ai/oss` can optionally run LLM-driven fact extraction on `add` — the model rewrites your input into one or more atomic facts before storing.
+
+| `inferOnWrite` | Behavior | Cost on write |
+|---|---|---|
+| `false` (default) | Content stored verbatim. Agent decides what to remember. | No LLM call |
+| `true` | mem0 calls its configured `llm` to extract facts. | ~200–500 ms + tokens |
+
+When unsure, leave it `false`. Flip it on later if recall quality on conversational text isn't enough.
+
+```json
+{
+  "memory": {
+    "enabled": true,
+    "backend": "mem0",
+    "mem0": {
+      "inferOnWrite": true,
+      "llm": { "provider": "openai", "config": { "model": "gpt-4o-mini" } }
+    }
+  }
+}
+```
+
+---
+
+## OpenClaw config UI
+
+Visit `/agenticros/config` (e.g. `http://localhost:18790/agenticros/config` via the proxy). The Memory section has:
+
+- **Off / Local / Mem0** radio buttons.
+- For Mem0: `inferOnWrite` checkbox and an editable `historyDbPath`.
+- **Test** button — calls `GET /agenticros/memory/status` and shows the parsed JSON inline.
+- **Clear all in namespace** button — calls `POST /agenticros/memory/clear` after confirmation. Useful when you've been experimenting and want a clean slate.
+
+---
+
+## Verifying setup
+
+From any adapter, call:
+
+```text
+memory_status({})
+```
+
+Expected response when memory is enabled:
+
+```json
+{
+  "success": true,
+  "enabled": true,
+  "backend": "local",
+  "namespace": "robot3946b404c33e4aa39a8d16deb1c5c593",
+  "recordCount": 0,
+  "lastWriteAt": null
+}
+```
+
+If `enabled` comes back `false`, double-check `memory.enabled` in your config file. If you set `backend: "mem0"` but get an embedder error, follow the auto-detect order above.
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `Memory is not enabled.` returned from a memory tool | Config has `memory.enabled: false` (or no `memory` block) | Set `memory.enabled: true` and restart the consumer (gateway / MCP server) |
+| `memory: backend "mem0" requires the "mem0ai" package.` | `pnpm add mem0ai` not run | Run `pnpm add mem0ai` in the workspace |
+| `memory: backend "mem0" needs an embedder.` | No Ollama, no `OPENAI_API_KEY`, no explicit `embedder` | Run Ollama, set the env var, or configure `memory.mem0.embedder` |
+| Memory tools missing from `tools/list` (Claude Code / Claude Desktop) | `memory.enabled` is false in `~/.agenticros/config.json` (MCP server reads that file, not OpenClaw's gateway config) | Add the `memory` block to `~/.agenticros/config.json` and restart the MCP client |
+| `Tool error: Transport connection timed out after 15s. Is zenohd running?` on a memory call | Older build that routed memory tools through the Zenoh transport | Rebuild adapter (`pnpm --filter @agenticros/claude-code build`, or `pnpm --filter @agenticros/gemini build`) — memory tools no longer touch the transport |
+| Memories don't follow across adapters | Different `robot.namespace` between adapters | Make sure all adapters use the same robot namespace (or override `memory.namespace`) |
+| OpenClaw chat doesn't seem to know about a fact you just stored | Chat session was opened before the fact was stored | Close and reopen the chat — the `Memory` system-context block is built at `before_agent_start` and refreshes per session |
+| OpenClaw chat reaches for `ros2_*` tools instead of `memory_recall` for a personal-fact question | Old build without the system-context "Memory" injection | Rebuild the plugin (`pnpm --filter agenticros build`) and restart the gateway |
+| MCP server logs | — | `/tmp/agenticros-mcp.log` (Claude Code); OpenClaw gateway log under `/tmp/openclaw/` for the OpenClaw plugin |
+
+---
+
+## Architecture in one diagram
+
+```
++----------------+   +-------------------+   +---------------+
+|  OpenClaw      |   |  Claude Code /    |   |  Gemini CLI   |
+|  plugin        |   |  Claude Desktop   |   |               |
+|                |   |  (MCP / stdio)    |   |               |
++--------+-------+   +---------+---------+   +-------+-------+
+         |                     |                     |
+         |   memory_remember / recall / forget / status   |
+         |                     |                     |
+         +---------+-----------+-----------+---------+
+                             |
+                             v
+                  +-------------------------+
+                  |  @agenticros/core       |
+                  |  createMemory(config)   |
+                  +----------+----+---------+
+                             |    |
+                       +-----+    +-----+
+                       v                v
+                +-----------+    +-----------------+
+                | Local     |    | Mem0            |
+                | provider  |    | provider        |
+                +-----+-----+    +--------+--------+
+                      |                   |
+                      v                   v
+        ~/.agenticros/memory.json   ~/.mem0/vector_store.db
+                                     +
+                                     embedder (Ollama / OpenAI / ...)
+```
+
+No network sidecar. The mem0 backend runs in-process and writes to `~/.mem0/`. Multiple processes (OpenClaw gateway, Claude Desktop MCP server, ad-hoc `agenticros-gemini` invocations) all read and write the same files — that's how cross-adapter sharing works.

package/runtime/docs/robot-setup.md

@@ -0,0 +1,347 @@
+# AgenticROS Robot Setup Guide
+
+This guide gets the AgenticROS project running on your robot (Ubuntu + ROS2 + OpenClaw) for testing and demos.
+
+## Onboarding (quick path)
+
+For a **new robot**, use the setup scripts after cloning the repo:
+
+```bash
+git clone https://github.com/agenticros/agenticros.git
+cd agenticros
+```
+
+- **Interactive wizard** (asks robot vs gateway, then runs the right steps):
+  ```bash
+  ./scripts/onboard_robot.sh
+  ```
+
+- **Robot only** (run on the robot):
+  ```bash
+  ./scripts/setup_robot.sh
+  ```
+  Optionally: `--ros-distro jazzy` or `humble`, `--skip-apt` to skip apt and build rosbridge from source.
+
+- **Gateway only** (run where OpenClaw runs):
+  ```bash
+  ./scripts/setup_gateway_plugin.sh
+  ```
+  Optionally: `--rosbridge-url ws://ROBOT_IP:9090`, `--robot-namespace YOUR_NAMESPACE` to document config.
+
+Then start the bridges on the robot with `./scripts/run_demo_native.sh` and restart the OpenClaw gateway. See the rest of this doc for manual steps and troubleshooting.
+
+---
+
+## Deployment modes
+
+| Setup | OpenClaw runs on | Robot runs | Use case |
+|-------|------------------|------------|----------|
+| **Mode A** (same machine) | The robot | ROS2 + (optional) rosbridge on localhost | Single robot, all-in-one demo |
+| **Mode B** (network) | Your laptop or server | ROS2 + rosbridge_server | Dev/testing, multi-robot |
+| **Mode C** (cloud / remote) | Cloud or VPS | ROS2 + agenticros_agent (WebRTC node) | Remote ops, robot behind NAT |
+| **Mode D** (Zenoh) | Any | ROS2 with zenoh-bridge-ros2dds or Zenoh RMW | Zenoh-based stacks |
+
+Choose **Mode A** if OpenClaw is installed on the robot. Choose **Mode B** if OpenClaw runs on another machine on the same network. Choose **Mode C** if OpenClaw is in the cloud and the robot is behind NAT (see [Architecture](architecture.md#deployment-mode-c-cloud--remote)). Choose **Mode D** if your robot uses Zenoh.
+
+---
+
+## Prerequisites on the robot
+
+- Ubuntu (22.04 or 24.04 recommended)
+- ROS2 **Humble** or **Jazzy** (match your existing install)
+- (For Mode A) OpenClaw installed on the robot
+- (For Mode B) Robot and OpenClaw machine on the same network
+
+---
+
+## Step 1: Clone and prepare the repo on the robot
+
+On the robot (or on your dev machine if you’ll copy the built workspace to the robot):
+
+```bash
+cd ~  # or your preferred path
+git clone https://github.com/agenticros/agenticros.git
+cd agenticros
+```
+
+Use `--ros-distro` to match your ROS2 install (e.g. `humble` or `jazzy`):
+
+```bash
+./scripts/setup_workspace.sh --ros-distro humble
+```
+
+If you already have ROS2 and only need the AgenticROS workspace built:
+
+```bash
+# Use your distro: humble, jazzy, or kilted
+source /opt/ros/humble/setup.bash   # or jazzy
+cd agenticros/ros2_ws
+colcon build --symlink-install
+source install/setup.bash
+```
+
+---
+
+## Step 2: Install the rosbridge WebSocket server (required for plugin)
+
+The plugin talks to ROS2 via **rosbridge** over WebSocket. The robot needs the **rosbridge_suite** (which provides the WebSocket server). Install it for your distro:
+
+```bash
+# Ubuntu/Debian — use your ROS2 distro (humble or jazzy)
+sudo apt update
+sudo apt install -y ros-<DISTRO>-rosbridge-suite
+```
+
+Example for Humble:
+
+```bash
+sudo apt install -y ros-humble-rosbridge-suite
+```
+
+Example for Jazzy:
+
+```bash
+sudo apt install -y ros-jazzy-rosbridge-suite
+```
+
+---
+
+## Step 3: Run the robot-side stack
+
+Activate the workspace and start **rosbridge** (and optionally **agenticros_discovery**).
+
+### Option A: Activate once, then run (recommended)
+
+```bash
+cd /path/to/agenticros
+source scripts/activate_workspace.sh ros_env humble   # or jazzy
+```
+
+In **one terminal**, start the rosbridge WebSocket server (port 9090):
+
+```bash
+ros2 launch rosbridge_server rosbridge_websocket_launch.xml
+```
+
+In a **second terminal** (optional but useful for the AI agent), start the discovery node so the plugin knows your topics/services/actions:
+
+```bash
+source /path/to/agenticros/scripts/activate_workspace.sh ros_env humble
+ros2 run agenticros_discovery discovery_node
+```
+
+Keep both running while you use OpenClaw.
+
+### Option B: Use the launch script
+
+From the repo root:
+
+```bash
+./scripts/run_robot_rosbridge.sh [humble|jazzy]
+```
+
+This sources the workspace and starts `rosbridge_server`. In another terminal, run the discovery node as above if you want it.
+
+---
+
+## Step 4: Configure OpenClaw and the AgenticROS plugin
+
+> **Install note (OpenClaw 2026.6+).** The OpenClaw install-time code-safety
+> scan rejects any `node_modules/*` symlink that resolves outside the plugin
+> install root. pnpm workspaces always trip this (every dep is a symlink into
+> the hoisted store), so `openclaw plugins install -l ./packages/agenticros`
+> no longer works against the source tree. The supported flow is to flatten
+> the plugin into a deploy directory first with `pnpm deploy --prod`, then
+> link that. The helper script `scripts/setup_gateway_plugin.sh` does this
+> end-to-end; the commands below show the manual steps it runs.
+
+### If OpenClaw is on the robot (Mode A) — default
+
+Mode A uses **local DDS** (`LocalTransport`): OpenClaw runs on the **same machine** as ROS 2, and the plugin talks to the ROS graph directly (no rosbridge or Zenoh router required). `ROS_DOMAIN_ID` must match your stack (often **`0`**). **This is the default** — `transport.mode` defaults to `local` in the plugin schema, so you can skip the transport block entirely on the robot.
+
+One-shot install with the helper script:
+
+```bash
+cd /path/to/agenticros
+./scripts/setup_gateway_plugin.sh \
+    --robot-namespace robot3946b404c33e4aa39a8d16deb1c5c593 \
+    --camera-topic /camera/camera/color/image_raw/compressed
+```
+
+Or the manual equivalent:
+
+```bash
+cd /path/to/agenticros
+pnpm install
+pnpm --filter @agenticros/core build
+pnpm --filter @agenticros/ros-camera build
+pnpm --filter ./packages/agenticros build
+
+# Flatten into a deploy dir OpenClaw will accept
+pnpm --filter ./packages/agenticros deploy --prod ~/.agenticros/plugin-deploy
+rm -f ~/.agenticros/plugin-deploy/node_modules/.pnpm/node_modules/agenticros
+
+# Register with OpenClaw (linked from the deploy dir, not the workspace)
+openclaw plugins install -l ~/.agenticros/plugin-deploy
+
+# Apply
+systemctl --user restart openclaw-gateway.service   # or however you run the gateway
+```
+
+(Optional) **Gazebo + TurtleBot3 simulation** on the same host, aligned with the repo bringup package:
+
+```bash
+source /opt/ros/jazzy/setup.bash
+cd /path/to/agenticros/ros2_ws && source install/setup.bash
+ros2 launch agenticros_bringup mode_a_gazebo.launch.py
+```
+
+Or with RViz: `ros2 launch agenticros_bringup mode_a_gazebo_rviz.launch.py`. Use `ros_domain_id:=N` if the plugin uses a non-zero domain. See the repository README section **“RViz2 and Gazebo”**.
+
+If you prefer rosbridge on localhost instead (e.g. for debugging), you can still run **`rosbridge_server`** and set **Transport mode** to **`rosbridge`** with **`ws://localhost:9090`** — that is closer to Mode B wiring, not strict Mode A.
+
+**Re-deploying after a code change.** The deploy directory is a snapshot, not a symlink to the workspace. After editing the plugin source, re-run `scripts/setup_gateway_plugin.sh` (it's idempotent), or repeat the `pnpm --filter ./packages/agenticros build` + `pnpm deploy --prod ~/.agenticros/plugin-deploy` + gateway-restart steps.
+
+### If OpenClaw is on another machine (Mode B)
+
+1. On your **laptop/server** where OpenClaw runs:
+   ```bash
+   cd /path/to/agenticros
+   ./scripts/setup_gateway_plugin.sh \
+       --transport rosbridge \
+       --rosbridge-url "ws://<ROBOT_IP>:9090" \
+       --robot-namespace <YOUR_NAMESPACE>
+   ```
+   Or the manual equivalent of the deploy flow shown in Mode A.
+2. Find the robot’s IP (on the robot run `hostname -I` or check your router).
+3. In OpenClaw, the plugin config will already have:
+   - **Transport mode:** `rosbridge`
+   - **Rosbridge URL:** `ws://<ROBOT_IP>:9090`  
+     Example: `ws://192.168.1.50:9090`
+4. Ensure the robot’s firewall allows TCP port **9090** (rosbridge):
+   ```bash
+   sudo ufw allow 9090/tcp
+   sudo ufw reload
+   ```
+5. Start OpenClaw and your messaging app; the plugin will connect to the robot at that URL.
+
+### If using cloud + WebRTC (Mode C)
+
+OpenClaw runs in the cloud; the robot runs the **AgenticROS Agent Node** (`agenticros_agent`) and connects via WebRTC (STUN/TURN). Setup is different from A/B/D: the robot does **not** run rosbridge or Zenoh — it runs the WebRTC agent node and talks to the cloud plugin over a data channel. For full steps, see [Deployment Mode C: Cloud / Remote](architecture.md#deployment-mode-c-cloud--remote) in the Architecture doc. Configure the plugin with **Transport mode:** `webrtc` and the appropriate signaling URL, API URL, robot ID, and key.
+
+### If using Zenoh (Mode D)
+
+1. Run a Zenoh router (**zenohd**) with **zenoh-plugin-remote-api** so the plugin can connect. AgenticROS uses **zenoh-ts**, which connects only via **WebSocket** (e.g. `ws://localhost:10000`), not native TCP. If you only start `zenohd` with default TCP (7447), native tools like `z_sub -e tcp/127.0.0.1:7447` will see traffic but AgenticROS will not. See [Zenoh setup for AgenticROS](zenoh-agenticros.md) for a config that enables the remote-api WebSocket on port 10000.
+2. Install the plugin via the helper script with Zenoh wiring:
+   ```bash
+   cd /path/to/agenticros
+   ./scripts/setup_gateway_plugin.sh \
+       --transport zenoh \
+       --zenoh-endpoint "ws://<ROUTER_IP>:10000" \
+       --robot-namespace <YOUR_NAMESPACE>
+   ```
+3. Or set the AgenticROS plugin config manually:
+   - **Transport mode:** `zenoh`
+   - **Zenoh Router Endpoint:** `ws://<ROUTER_IP>:10000` (or the URL your router advertises)
+   - **Zenoh Domain ID:** match your `ROS_DOMAIN_ID` (default `0`)
+4. Optionally set **ROS2 Robot Namespace** (e.g. `robot-uuid`). Topics will be namespaced (e.g. `/robot-uuid/cmd_vel`). This applies to all transport modes.
+
+### ROS2 topic namespace
+
+The **robot.namespace** config (e.g. `robot-uuid`) makes the plugin use namespaced topics: root-level names like `cmd_vel` become `/robot-uuid/cmd_vel`. Use this when multiple robots share the same ROS 2 / Zenoh network. Documented in the plugin config as “ROS2 topic namespace; e.g. robot-uuid gives topics like /robot-uuid/cmd_vel”.
+
+---
+
+## Quick checks
+
+- **Rosbridge listening:** On the robot, with rosbridge running:
+  ```bash
+  ss -tlnp | grep 9090
+  ```
+  You should see something like `*:9090`.
+
+- **Discovery:** With discovery running, you can inspect what the agent will see:
+  ```bash
+  ros2 topic echo /agenticros/capabilities --once
+  ```
+
+- **Plugin connection:** In OpenClaw, after starting a chat, the plugin should connect to the robot; check OpenClaw logs for AgenticROS connection messages.
+
+---
+
+## Try a demo
+
+Once everything is running:
+
+1. Send a message to your bot, e.g. **“Move forward 1 meter”** (if your robot has `/cmd_vel`).  
+   **If the robot doesn’t move:** the base may subscribe to a **namespaced** cmd_vel (e.g. `/robot3946b404c33e4aa39a8d16deb1c5c593/cmd_vel`). Set **robot.namespace** in the plugin config to that prefix (e.g. `robot3946b404c33e4aa39a8d16deb1c5c593`), then restart the gateway. From the repo: `./scripts/configure_agenticros.sh --mode zenoh --zenoh-endpoint ws://localhost:10000 --namespace robot3946b404c33e4aa39a8d16deb1c5c593`.
+2. Or **“What do you see?”** if you have a camera topic.
+3. Use **`/estop`** for emergency stop (bypasses the AI).
+
+---
+
+## Troubleshooting
+
+| Issue | What to check |
+|-------|----------------|
+| Plugin won’t connect | Rosbridge URL correct? Robot IP (Mode B)? Firewall allows 9090? |
+| “Package not found” (rosbridge_server) | Install `ros-<distro>-rosbridge-suite` (Step 2). |
+| “Package not found” (agenticros_discovery) | Run `source scripts/activate_workspace.sh` and ensure `ros2_ws` is built. |
+| Different ROS distro | Use `--ros-distro humble` or `jazzy` in `setup_workspace.sh` and when sourcing. |
+
+### "Rate limited" in webchat (OpenAI)
+
+The message comes from **OpenAI's API limits**, not from AgenticROS. The gateway sends your chat to OpenAI; when OpenAI returns 429 (rate limit), OpenClaw shows "rate limited".
+
+1. **Confirm it's OpenAI** — Check gateway logs:  
+   `journalctl --user -u openclaw-gateway.service -n 100 --no-pager | grep -i "429\|rate\|limit\|error"`
+2. **Check your OpenAI account** — [Usage](https://platform.openai.com/usage), [API keys](https://platform.openai.com/api-keys). Free/low tiers have strict RPM/TPM and can stay limited for a while.
+3. **What helps** — Wait (RPM/TPM reset in minutes; daily limits at UTC midnight). Or in OpenClaw switch to a model with higher limits if available.
+4. **AgenticROS** — We only trim context/tool output to use fewer tokens; we can't remove OpenAI's limits.
+
+### 404 errors when installing rosbridge_suite
+
+If `sudo apt install ros-jazzy-rosbridge-suite` fails with **404 Not Found** (stale ROS or Ubuntu mirror):
+
+1. **Refresh and retry**
+   ```bash
+   sudo apt update
+   sudo apt install -y ros-jazzy-rosbridge-suite
+   ```
+
+2. **If it still fails**, install **from source** so you don't depend on the broken packages:
+   ```bash
+   cd /home/ubuntu/Projects/agenticros
+   ./scripts/install_rosbridge_from_source.sh jazzy
+   ```
+   Then run rosbridge with:
+   ```bash
+   source /opt/ros/jazzy/setup.bash
+   source ros2_ws/install/setup.bash
+   ros2 launch rosbridge_server rosbridge_websocket_launch.xml
+   ```
+
+For deployment with OpenClaw in the cloud and the robot behind NAT, see **Mode C** in [Architecture](architecture.md) (WebRTC + `agenticros_agent` on the robot).
+
+---
+
+## Launch script (mode and namespace)
+
+Use the configuration script to set transport mode, robot namespace, and optional Docker in one go:
+
+```bash
+./scripts/configure_agenticros.sh --interactive
+```
+
+Or with flags:
+
+| Goal | Example |
+|------|---------|
+| Mode A (OpenClaw on robot) | `--mode A` |
+| Mode B (robot on network) | `--mode B --robot-ip 192.168.1.50` |
+| Mode C (cloud + WebRTC) | `--mode C` (then set signaling/API/robot in config) |
+| Mode D (Zenoh) | `--mode D --zenoh-endpoint ws://localhost:10000` |
+| Robot namespace | `--namespace robot-uuid` (topics like `/robot-uuid/cmd_vel`) |
+| Demo with Docker (Mode B + local rosbridge) | `--docker` |
+
+The script updates `~/.openclaw/openclaw.json` (or `OPENCLAW_CONFIG`) with `plugins.entries.agenticros.config`. It requires **jq** for JSON edits; without jq it prints the options for you to set manually. With `--docker`, it also starts the Docker Compose ROS2+rosbridge service so you can point the plugin at `ws://localhost:9090`.

package/runtime/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "agenticros-monorepo",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "description": "AgenticROS — monorepo for ROS2 + AI agent integrations. The publishable CLI lives in packages/agenticros-cli (npm: `agenticros`).",
+  "scripts": {
+    "build": "pnpm -r build",
+    "clean": "pnpm -r exec rm -rf dist tsconfig.tsbuildinfo",
+    "lint": "pnpm -r lint",
+    "typecheck": "pnpm -r typecheck",
+    "mcp:kill": "pkill -f 'node packages/agenticros-claude-code/dist/index.js' || true",
+    "sync-skill-tools": "node scripts/sync-skill-tools.mjs",
+    "sync-skill-tools:dry": "node scripts/sync-skill-tools.mjs --dry-run --verbose"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=9.0.0"
+  },
+  "packageManager": "pnpm@9.15.4",
+  "author": "PlaiPin",
+  "license": "Apache-2.0",
+  "pnpm": {
+    "patchedDependencies": {
+      "@eclipse-zenoh/zenoh-ts@1.9.0": "patches/@eclipse-zenoh__zenoh-ts@1.9.0.patch"
+    }
+  }
+}