agenticros 0.0.1 → 0.1.1

package/runtime/docs/architecture.md

@@ -0,0 +1,366 @@
+# AgenticROS System Architecture
+
+![AgenticROS architecture: agent platforms → adapter packages → shared TypeScript runtime → transports → ROS 2 workspace and robot](images/agenticros-architecture.png)
+
+AgenticROS supports four deployment modes depending on where OpenClaw runs
+relative to the robot. The AI Gateway layer and ROS2 layer remain the same
+across all modes — only the transport between them changes.
+
+The diagram above shows how every agent platform (OpenClaw Gateway, Codex /
+Claude Code, Gemini CLI, and direct users/operators) funnels through adapter
+packages into the shared `@agenticros/core` runtime, then out across the
+configured transport (Zenoh, rosbridge, local DDS, or WebRTC) to the ROS 2
+workspace and robot hardware. The text diagrams below break out each
+deployment mode in more detail.
+
+---
+
+## AI Gateway Layer (common to all modes)
+
+```
+┌──────────────────────────────────────────────────────────────────────────────────┐
+│                              MESSAGING LAYER                                     │
+│                                                                                  │
+│    ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐        │
+│    │ WhatsApp │  │ Telegram │  │ Discord  │  │  Slack   │  │ Web Chat │        │
+│    └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘        │
+│         └──────────────┴──────┬─────┴──────────────┴─────────────┘               │
+└───────────────────────────────┼──────────────────────────────────────────────────┘
+                                ▼
+┌──────────────────────────────────────────────────────────────────────────────────┐
+│                           AI GATEWAY LAYER                                       │
+│                                                                                  │
+│  ┌────────────────────────────────────────────────────────────────────────────┐  │
+│  │                        OPENCLAW GATEWAY                                    │  │
+│  │   ┌──────────────┐  ┌─────────────────┐  ┌──────────────────────────┐     │  │
+│  │   │   Sessions   │  │   AI Agent      │  │   Memory / State         │     │  │
+│  │   │  (per-user)  │  │  (intent →      │  │  (cross-conversation)    │     │  │
+│  │   │              │  │   tool calls)   │  │                          │     │  │
+│  │   └──────────────┘  └───────┬─────────┘  └──────────────────────────┘     │  │
+│  └─────────────────────────────┼─────────────────────────────────────────────┘  │
+│                                ▼                                                 │
+│  ┌────────────────────────────────────────────────────────────────────────────┐  │
+│  │                       AGENTICROS PLUGIN                                       │  │
+│  │                                                                            │  │
+│  │  ┌─────────────────────────────────────────────────────────────────────┐   │  │
+│  │  │                    TOOL REGISTRY                                     │   │  │
+│  │  │                                                                      │   │  │
+│  │  │  ros2_publish    ros2_subscribe_once    ros2_service_call            │   │  │
+│  │  │  ros2_action_goal   ros2_param_get/set  ros2_list_topics            │   │  │
+│  │  │  ros2_camera_snapshot   follow_robot (Follow Me mission)            │   │  │
+│  │  └──────────────────────────────┬──────────────────────────────────────┘   │  │
+│  │                                 │                                          │  │
+│  │  ┌──────────────┐  ┌───────────▼──────────┐  ┌─────────────────────┐      │  │
+│  │  │   SKILLS     │  │  SAFETY VALIDATOR    │  │  ROBOT CONTEXT      │      │  │
+│  │  │              │  │                      │  │                     │      │  │
+│  │  │ navigate-to  │  │ before_tool_call     │  │ before_agent_start  │      │  │
+│  │  │ take-photo   │  │  · velocity limits   │  │  · capabilities    │      │  │
+│  │  │ check-status │  │  · workspace bounds  │  │  · topics/services │      │  │
+│  │  │ pick-object  │  │  · blocked ops       │  │  · safety config   │      │  │
+│  │  │ follow-me    │  │                      │  │                     │      │  │
+│  │  └──────────────┘  └──────────┬───────────┘  └─────────────────────┘      │  │
+│  │                               │                                            │  │
+│  │  ┌────────────────────────────┤   ┌──────────────────────────────────┐     │  │
+│  │  │  /estop COMMAND            │   │  TRANSPORT ADAPTER               │     │  │
+│  │  │  (bypasses AI entirely)    │   │  (mode-dependent, see below)     │     │  │
+│  │  └────────────────────────────┘   └──────────────┬───────────────────┘     │  │
+│  └──────────────────────────────────────────────────┼────────────────────────┘  │
+└─────────────────────────────────────────────────────┼────────────────────────────┘
+                                                      │
+                                                      ▼
+                                          ┌───────────────────────┐
+                                          │  Mode A, B, C, or D   │
+                                          │  (see below)          │
+                                          └───────────────────────┘
+```
+
+## ROS2 Layer (common to all modes)
+
+```
+┌──────────────────────────────────────────────────────────────────────────────────┐
+│                              ROS2 LAYER                                          │
+│                                                                                  │
+│                           ROS2 DDS Bus                                           │
+│         ┌──────────┬──────────┬──────────┬──────────┐                            │
+│         ▼          ▼          ▼          ▼          ▼                            │
+│  ┌────────────┐┌────────┐┌────────┐┌─────────┐┌──────────────┐                  │
+│  │  /cmd_vel  ││ /odom  ││/camera ││/battery ││/diagnostics  │  ...             │
+│  │  (Twist)   ││(Odom)  ││(Image) ││(State)  ││(DiagArray)   │                  │
+│  └─────┬──────┘└───┬────┘└───┬────┘└────┬────┘└──────┬───────┘                  │
+│        │           │         │          │            │                            │
+│  ┌─────▼───────────▼─────────▼──────────▼────────────▼────────────────────┐      │
+│  │                         ROBOT HARDWARE                                  │      │
+│  │                                                                         │      │
+│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐               │      │
+│  │  │  Motors  │  │  Camera  │  │  LIDAR   │  │   IMU    │   ...         │      │
+│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘               │      │
+│  └─────────────────────────────────────────────────────────────────────────┘      │
+│                                                                                   │
+│  ┌─────────────────────────────────┐  ┌───────────────────────────────────┐       │
+│  │  agenticros_discovery              │  │  Nav2 / MoveIt2 / Other Stacks   │       │
+│  │  (capability introspection)     │  │  (navigation, manipulation)       │       │
+│  └─────────────────────────────────┘  └───────────────────────────────────┘       │
+└──────────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Deployment Mode A: Same Machine
+
+OpenClaw runs directly on the robot's computer. The plugin talks to ROS2
+natively through the local DDS bus — no network transport needed. The user
+only interacts through messaging apps over the internet.
+
+Best for: single-robot setups, embedded deployments, edge devices with
+internet access.
+
+```
+    User (Telegram, WhatsApp, etc.)
+                 │
+                 │  internet
+                 ▼
+┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐
+│                        ROBOT MACHINE                                     │
+│                                                                          │
+│  ┌────────────────────────────────────────────────────────────────────┐  │
+│  │  OPENCLAW + AGENTICROS PLUGIN                                        │  │
+│  │                                                                    │  │
+│  │  AI Agent → Safety Validator → Tool Execution                     │  │
+│  └──────────────────────┬─────────────────────────────────────────────┘  │
+│                         │                                                │
+│                         │ direct (local DDS / rclnodejs)                 │
+│                         ▼                                                │
+│  ┌────────────────────────────────────────────────────────────────────┐  │
+│  │  ROS2 DDS Bus                                                      │  │
+│  │  /cmd_vel  /odom  /camera  /battery  /diagnostics  ...            │  │
+│  └──────────────────────┬─────────────────────────────────────────────┘  │
+│                         ▼                                                │
+│  ┌────────────────────────────────────────────────────────────────────┐  │
+│  │  ROBOT HARDWARE   (motors, camera, LIDAR, IMU)                    │  │
+│  └────────────────────────────────────────────────────────────────────┘  │
+│                                                                          │
+└ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘
+
+Transport: none (same process / local IPC)
+Latency:   ~ms
+NAT issue:  none — only outbound internet needed for messaging APIs
+```
+
+---
+
+## Deployment Mode B: Local Network
+
+OpenClaw runs on a separate machine on the same network as the robot
+(e.g. a laptop, local server, or dev workstation). The plugin connects to
+rosbridge_server on the robot via WebSocket over LAN.
+
+Best for: development, testing, multi-robot labs, on-premises deployments
+where everything is on the same network.
+
+```
+    User (Telegram, WhatsApp, etc.)
+                 │
+                 │  internet
+                 ▼
+┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐     ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐
+│  LOCAL SERVER / DEV MACHINE    │     │  ROBOT                          │
+│                                │     │                                 │
+│  ┌──────────────────────────┐  │     │  ┌───────────────────────────┐  │
+│  │  OPENCLAW + AGENTICROS      │  │     │  │  rosbridge_server         │  │
+│  │  PLUGIN                  │──┼─────┼─►│  (WebSocket → ROS2 DDS)   │  │
+│  │                          │  │ LAN │  └─────────────┬─────────────┘  │
+│  │  rosbridge-client lib    │  │ WS  │                │                │
+│  └──────────────────────────┘  │     │                ▼                │
+│                                │     │  ┌───────────────────────────┐  │
+└ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘     │  │  ROS2 DDS Bus             │  │
+                                       │  │  /cmd_vel  /odom  ...     │  │
+                                       │  └─────────────┬─────────────┘  │
+                                       │                ▼                │
+                                       │  ┌───────────────────────────┐  │
+                                       │  │  ROBOT HARDWARE           │  │
+                                       │  └───────────────────────────┘  │
+                                       │                                 │
+                                       └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘
+
+Transport: WebSocket (ws://robot-ip:9090) via rosbridge protocol
+Latency:   ~ms (LAN)
+NAT issue:  none — both machines are on the same network
+```
+
+---
+
+## Deployment Mode C: Cloud / Remote
+
+OpenClaw runs on a cloud server or VPS. The robot is on a remote network
+(factory, warehouse, field) behind NAT/firewall. Neither side can directly
+reach the other. A WebRTC connection with STUN/TURN handles NAT traversal
+so both sides can establish peer-to-peer communication.
+
+Best for: production deployments, remote operations, fleet management,
+when operators and robots are in different locations.
+
+```
+    User (Telegram, WhatsApp, etc.)
+                 │
+                 │  internet
+                 ▼
+┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐                  ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐
+│  CLOUD / VPS                   │                  │  ROBOT (behind NAT/firewall)   │
+│                                │                  │                                │
+│  ┌──────────────────────────┐  │                  │  ┌──────────────────────────┐  │
+│  │  OPENCLAW + AGENTICROS      │  │                  │  │  AgenticROS Agent Node      │  │
+│  │  PLUGIN                  │  │                  │  │  (ROS2 node)             │  │
+│  │                          │  │                  │  │                          │  │
+│  │  WebRTC data channel     │◄─┼── P2P or TURN ──┼─►│  WebRTC data channel     │  │
+│  └──────────────────────────┘  │    (encrypted)   │  └────────────┬─────────────┘  │
+│                                │                  │               │                │
+└ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘                  │               │ local DDS      │
+                                       ┌─────────┐ │               ▼                │
+                                       │  STUN / │ │  ┌──────────────────────────┐  │
+                                       │  TURN   │ │  │  ROS2 DDS Bus            │  │
+                                       │  Server │ │  │  /cmd_vel  /odom  ...    │  │
+                                       └─────────┘ │  └────────────┬─────────────┘  │
+                                                    │               ▼                │
+                                                    │  ┌──────────────────────────┐  │
+                                                    │  │  ROBOT HARDWARE          │  │
+                                                    │  └──────────────────────────┘  │
+                                                    │                                │
+                                                    └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘
+
+Transport: WebRTC data channel (STUN for NAT traversal, TURN as relay fallback)
+Latency:   ~10-100ms (internet, varies)
+NAT issue:  solved — both sides connect outbound to STUN/TURN, then P2P
+```
+
+In Mode C, the robot runs a **AgenticROS Agent Node** (`agenticros_agent`) — a
+lightweight ROS2 node that connects outbound to the signaling/TURN server
+and establishes a WebRTC data channel with the cloud-side plugin. Commands
+and feedback flow over this encrypted peer-to-peer channel. Neither side
+needs a public IP or open inbound ports.
+
+---
+
+## Deployment Mode D: Zenoh
+
+When the robot uses **ROS 2 with Zenoh RMW** (`RMW_IMPLEMENTATION=rmw_zenoh_cpp`),
+the plugin can connect directly to a Zenoh router via **zenoh-ts** (WebSocket to
+`zenoh-plugin-remote-api`). No rosbridge or WebRTC bridge is required.
+
+Best for: robots already on Zenoh, low-latency pub/sub, or deployments that
+prefer the Zenoh stack over DDS.
+
+```
+    User (Telegram, WhatsApp, etc.)
+                 │
+                 │  internet
+                 ▼
+┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐     ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐
+│  OPENCLAW MACHINE               │     │  ROBOT (Zenoh RMW)           │
+│                                 │     │                               │
+│  ┌──────────────────────────┐   │     │  ┌─────────────────────────┐  │
+│  │  OPENCLAW + AGENTICROS      │   │     │  │  Zenoh router           │  │
+│  │  PLUGIN                  │   │     │  │  (zenohd)                │  │
+│  │                          │   │     │  └───────────┬─────────────┘  │
+│  │  zenoh-ts (WebSocket)    │───┼─────┼─►             │                │
+│  └──────────────────────────┘   │     │               │ Zenoh         │
+│                                 │     │  ┌─────────────▼─────────────┐  │
+└ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘     │  │  ROS2 (rmw_zenoh_cpp)      │  │
+                                       │  │  /cmd_vel  /odom  ...       │  │
+                                       │  └─────────────┬─────────────┘  │
+                                       │                ▼                │
+                                       │  ┌─────────────────────────────┐  │
+                                       │  │  ROBOT HARDWARE             │  │
+                                       │  └─────────────────────────────┘  │
+                                       │                                   │
+                                       └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘
+
+Transport: Zenoh (WebSocket to Zenoh router; plugin uses zenoh-ts)
+Latency:   ~ms
+NAT issue:  depends on network — router must be reachable from OpenClaw
+```
+
+Set `transport.mode` to `zenoh`, configure `zenoh.routerEndpoint` (e.g.
+`ws://router-host:10000` for zenoh-ts), and optionally `zenoh.domainId` to
+match `ROS_DOMAIN_ID` / rmw_zenoh. The `robot.namespace` config applies to
+topic names (and thus to Zenoh key expressions), e.g. namespace `robot-uuid`
+yields `/robot-uuid/cmd_vel`.
+
+---
+
+## Transport Adapter Abstraction
+
+All plugin tools call `getTransport()` instead of directly using a specific
+client library. The `RosTransport` interface (`@agenticros/transport`) provides
+a unified API for all three deployment modes:
+
+```
+  Plugin Tools (ros2_publish, ros2_subscribe_once, ...)
+       │
+       ▼
+  getTransport(): RosTransport
+       │
+       ├── RosbridgeTransport  (Mode B — @agenticros/rosbridge-client)
+       │     └── WebSocket → rosbridge_server → ROS2 DDS
+       │
+       ├── LocalTransport      (Mode A — @agenticros/transport-local, stub)
+       │     └── rclnodejs → ROS2 DDS directly
+       │
+       ├── WebRTCTransport     (Mode C — @agenticros/transport-webrtc, stub)
+       │     └── WebRTC data channel → agenticros_agent → ROS2 DDS
+       │
+       └── ZenohTransport      (Mode D — zenoh-ts)
+             └── WebSocket → Zenoh router → ROS2 (rmw_zenoh_cpp)
+```
+
+The `createTransport(config)` factory in `@agenticros/transport` uses dynamic
+`import()` to load the correct adapter by mode, so unused adapters and their
+dependencies are never loaded.
+
+---
+
+## Optional cross-adapter memory
+
+When `config.memory.enabled` is true, all four adapters (OpenClaw, Claude Code
+MCP, Claude Desktop MCP, Gemini CLI) register four extra tools —
+`memory_remember`, `memory_recall`, `memory_forget`, `memory_status` — backed
+by a **shared, file-backed store** namespaced by `robot.namespace`. With the
+`mem0` backend, the vector store lives at `~/.mem0/vector_store.db`, so every
+process on the host reads and writes the same data — that is what enables
+true cross-adapter recall (a fact remembered from Claude Desktop is immediately
+recall-able from OpenClaw).
+
+The OpenClaw plugin additionally injects a `### Memory` section into each
+chat's system context at `before_agent_start`, containing usage directives
+for the four tools plus a snapshot of up to 10 recently-remembered facts
+(via the `MemoryProvider.recent(namespace, limit)` core method). This lets
+the OpenClaw LLM answer common personal-context questions ("what do I have
+for X?") **without** a tool call, while still using `memory_recall` for
+deeper semantic search.
+
+Off by default; see [memory.md](memory.md) for setup, recipes, and
+cross-process verification steps.
+
+---
+
+## Data Flow Example
+
+```
+  User (Telegram)                AgenticROS                        Robot
+       │                            │                              │
+       │  "Move forward 2 meters"   │                              │
+       │───────────────────────────►│                              │
+       │                            │                              │
+       │              AI Agent selects ros2_publish                │
+       │              Safety hook validates (0.5 m/s < 1.0 limit) │
+       │                            │                              │
+       │                            │  publish /cmd_vel            │
+       │                            │─────────────────────────────►│
+       │                            │  (via Mode A, B, or C)       │  Motors
+       │                            │                              │  engage
+       │                            │  subscribe /odom             │
+       │                            │◄─────────────────────────────│
+       │                            │                              │
+       │  "Done! Moved 2m forward"  │                              │
+       │◄───────────────────────────│                              │
+       │                            │                              │
+```

package/runtime/docs/cli.md

@@ -0,0 +1,140 @@
+# `agenticros` CLI reference
+
+`agenticros` is the single command-line entry point for the AgenticROS
+project. It orchestrates the existing shell scripts (`scripts/start_demo.sh`,
+`scripts/setup_gateway_plugin.sh`, …) and the simulation launchers, and adds
+an interactive menu, a doctor, and a status/logs view on top.
+
+## Install
+
+| Audience | Command |
+|---|---|
+| One-off (no install) | `npx agenticros` |
+| Per-user global      | `pnpm add -g agenticros` (or `npm install -g agenticros`) |
+| Contributor (repo)   | `./agenticros` from the repo root, or `./scripts/install_cli.sh` |
+
+The `npx` and `npm` flows ship a snapshot of the entire AgenticROS monorepo
+inside the published tarball. The first `agenticros init` copies that
+snapshot into `~/agenticros` (configurable via `$AGENTICROS_HOME` or
+`--install-dir`), then runs `pnpm install`, `pnpm build`, and `colcon build`
+there. After init, every subsequent `agenticros` invocation operates against
+`~/agenticros` as the workspace root.
+
+Contributors working from a clone get a third "workspace mode": the CLI auto-
+detects the `agenticros-monorepo` package.json walking upward from its install
+location and uses the live sources / dist directly.
+
+## Commands
+
+### `agenticros` (no args)
+
+Opens the interactive top-level menu. The menu adapts to the doctor's output:
+if any red checks are present, "First-time setup" is moved to the top.
+
+### `agenticros up [target]`
+
+Bring up a robot stack. Targets:
+
+| Target    | What it does |
+|-----------|-----|
+| `real`    | Runs `scripts/start_demo.sh`: RealSense camera, motor controller, MCP server. |
+| `sim-amr` | Launches the simulated 2-wheel AMR (Phase 2 - WIP). |
+| `sim-arm` | Launches the simulated UR5e arm + MoveIt2 (Phase 3 - WIP). |
+
+Flags:
+- `--ros-distro humble|jazzy|…` override ROS distro detection
+- `--namespace <ns>` override the robot namespace
+- `--rviz` open RViz alongside the sim
+- `--no-camera` skip starting the RealSense camera (real target)
+- `--no-motors` skip starting the motor controller (real target)
+
+### `agenticros down [--keep-camera] [--keep-gateway]`
+
+SIGTERMs every process recorded in `/tmp/agenticros-*.pid` and stops the
+`openclaw-gateway.service` user unit (unless `--keep-gateway`). Also cleans
+up stray `gz sim`, `rviz2`, and `parameter_bridge` processes.
+
+### `agenticros init [--force] [--install-dir <path>]`
+
+Idempotent first-time setup wizard. Each step queries doctor first and is
+skipped (with a checkmark) when already done:
+
+1. JS workspace deps (`pnpm install`)
+2. JS workspace build (`pnpm build`)
+3. ROS 2 workspace build (`colcon build --symlink-install`)
+4. OpenClaw plugin install (via `scripts/setup_gateway_plugin.sh`)
+5. Robot config (writes `~/.agenticros/config.json`)
+6. OpenAI API key (paste once → `scripts/configure_agenticros.sh`)
+7. Final `agenticros doctor` summary
+
+Pass `--force` to re-run every step regardless of state.
+
+### `agenticros doctor [--json]`
+
+Runs every health check and prints a coloured table. With `--json`, emits the
+same report as a structured object for CI / scripting:
+
+```json
+{
+  "checks": [{ "id": "ros-distro", "label": "...", "severity": "green" }, …],
+  "summary": { "green": 10, "yellow": 1, "red": 0 }
+}
+```
+
+Exits non-zero if any check is red.
+
+### `agenticros status [--json]`
+
+Shows running components (camera / sim / mcp / rosbridge / openclaw-gateway)
+and the last-used mode/namespace from `~/.agenticros/cli-state.json`.
+
+### `agenticros logs [target]`
+
+Tails one of: `camera`, `mcp`, `sim`, `rosbridge`, `gateway`. Without a
+target, prints the list of available log targets. Defaults to follow mode
+(`-f`); pass `--no-follow` to disable.
+
+### `agenticros config [action] [key=value]`
+
+Read or edit `~/.agenticros/config.json`. Actions:
+
+| Action | Example | Effect |
+|---|---|---|
+| `show`  | `agenticros config show` (or just `agenticros config`) | Pretty-print the file. |
+| `set`   | `agenticros config set robot.namespace=sim_robot` | Write a single key (dot-paths supported). |
+| `edit`  | `agenticros config edit` | Open in `$EDITOR`. |
+| `reset` | `agenticros config reset` | Delete the file (with confirm). |
+
+## Where state lives
+
+| Path | Owner | Purpose |
+|---|---|---|
+| `~/.agenticros/config.json` | User | AgenticROS runtime config (transport mode, namespace, safety limits). |
+| `~/.agenticros/cli-state.json` | CLI | Last-used mode/namespace for the menu's "(yesterday)" hint. |
+| `~/agenticros/` | CLI (npm-install mode) | Copy of the monorepo, with built dist + colcon install. |
+| `/tmp/agenticros-*.pid` | CLI | PIDs of background processes the CLI spawned. |
+| `/tmp/agenticros-*.log` | CLI | Stdout/stderr from those processes. |
+| `~/.openclaw/openclaw.json` | OpenClaw gateway | Plugin registration + per-plugin config (incl. AgenticROS). |
+
+## Environment variables
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `AGENTICROS_HOME` | `~/agenticros` | Install root in npm-install mode. |
+| `AGENTICROS_CONFIG_PATH` | (auto) | Override the path to `~/.agenticros/config.json`. |
+| `AGENTICROS_ROBOT_NAMESPACE` | (from config) | Force a robot namespace at runtime. |
+| `OPENAI_API_KEY` | (none) | If set, doctor reports green without requiring OpenClaw profile config. |
+
+## Troubleshooting
+
+- **`doctor` shows red checks** → run `agenticros init` to walk through every
+  step. Re-run `doctor` afterward.
+- **`up` exits immediately** → `agenticros logs <component>` (the CLI now
+  records where every child wrote its output) and read the error in context.
+- **`up sim-amr` warns "scripts/sim/run_sim.sh not found"** → simulation
+  support is delivered in CLI Phase 2; until then the message tells you when
+  to expect it.
+- **`pnpm --filter agenticros build` builds two packages** → check the OpenClaw
+  plugin's `packages/agenticros/package.json`; its npm name should be
+  `@agenticros/openclaw`, not `agenticros`. If it's wrong, `pnpm --filter` will
+  match both. (Fixed in this repo as of June 2026.)