selfpatch · bburda · Mar 20, 2026 · Mar 21, 2026 · Mar 21, 2026 · Mar 21, 2026
diff --git a/README.md b/README.md
@@ -15,45 +15,54 @@
 </p>
 
 <p align="center">
-  <b>Automotive-grade diagnostics for ROS 2 robots.</b><br>
-  When your robot fails, find out why — in minutes, not hours.
+  <b>Structured diagnostics for ROS 2 robots.</b><br>
+  When your robot fails, find out why - in minutes, not hours.
 </p>
 
 <p align="center">
-  Fault correlation · Black-box recording · REST API · <a href="https://github.com/selfpatch/ros2_medkit_mcp">AI via MCP</a>
+  Fault management · Live introspection · REST API · <a href="https://github.com/selfpatch/ros2_medkit_mcp">AI via MCP</a>
 </p>
 
+## The problem
+
+When a robot breaks in the field, you SSH in, run `ros2 node list`, grep through logs, and try to reconstruct what happened. It works for one robot on your desk. It does not work for 20 robots at a customer site, at 2 AM, when you cannot reproduce the issue.
+
+ros2_medkit gives your ROS 2 system a **diagnostic REST API** so you can inspect what is running, what failed, and why, without SSH and without custom tooling.
+
 ## 🚀 Quick Start
 
 **Try the full demo** (Docker, no ROS 2 needed):
 
 ```bash
 git clone https://github.com/selfpatch/selfpatch_demos.git
 cd selfpatch_demos/demos/turtlebot3_integration
-./run-demo.sh --headless
+./run-demo.sh
 # → API: http://localhost:8080/api/v1/  Web UI: http://localhost:3000
 ```
 
+Open `http://localhost:3000` in your browser. You will see a TurtleBot3 with Nav2, organized into a browsable entity tree with live faults, topic data, and parameter access.
+
 **Build from source** (ROS 2 Jazzy, Humble, or Rolling):
 
 ```bash
+source /opt/ros/jazzy/setup.bash   # or humble - adjust for your distro
 git clone --recurse-submodules https://github.com/selfpatch/ros2_medkit.git
 cd ros2_medkit
 rosdep install --from-paths src --ignore-src -r -y
 colcon build --symlink-install && source install/setup.bash
 ros2 launch ros2_medkit_gateway gateway.launch.py
-# → http://localhost:8080/api/v1/areas
+# → http://localhost:8080/api/v1/health
 ```
 
-For more examples, see our [Postman collection](postman/).
+Verify it works: `curl http://localhost:8080/api/v1/health` should return `{"status": "healthy", ...}`.
 
-### Experimental: Pixi
+For a guided walkthrough with demo nodes and the full API, see the [Getting Started tutorial](https://selfpatch.github.io/ros2_medkit/getting_started.html). For API examples, see our [Postman collection](postman/).
 
-> **Note:** Pixi support is experimental and not the official build path.
-> The standard ROS 2 toolchain (rosdep + colcon) remains the primary method.
+### Experimental: Pixi
 
 [Pixi](https://pixi.sh) provides a reproducible, lockfile-based environment
-without requiring a system-wide ROS 2 installation (Linux x86_64 only):
+without requiring a system-wide ROS 2 installation (Linux x86_64 only).
+This is experimental; the standard ROS 2 toolchain (rosdep + colcon) remains the primary method.
 
 ```bash
 curl -fsSL https://pixi.sh/install.sh | bash
@@ -64,215 +73,120 @@ pixi run -e jazzy smoke   # verify gateway starts
 ```
 
 See [installation docs](https://selfpatch.github.io/ros2_medkit/installation.html#experimental-pixi)
-for details and known limitations.
-Feedback welcome on [#265](https://github.com/selfpatch/ros2_medkit/issues/265).
-
-## ✨ Features
-
-| Feature | Status | Description |
-|---------|--------|-------------|
-| 🔍 Discovery | **Available** | Automatically discover running nodes, topics, services, and actions |
-| 📊 Data | **Available** | Read and write topic data via REST |
-| ⚙️ Operations | **Available** | Call services and actions with execution tracking |
-| 🔧 Configurations | **Available** | Read, write, and reset node parameters |
-| 🚨 Faults | **Available** | Query, inspect, and clear faults with environment data and snapshots |
-| 📦 Bulk Data | **Available** | Upload, download, and manage files (calibration, firmware, rosbags) |
-| 📡 Subscriptions | **Available** | Stream live data and fault events via SSE |
-| 🎯 Triggers | **Available** | Condition-based push notifications for resource changes |
-| 🔄 Software Updates | **Available** | Async prepare/execute lifecycle with pluggable backends |
-| 🔒 Authentication | **Available** | JWT-based RBAC (viewer, operator, configurator, admin) |
-| 📋 Logs | **Available** | Log sources, entries, and configuration |
-| 🔁 Entity Lifecycle | Planned | Start, restart, shutdown control |
-| 🔐 Modes & Locking | Planned | Target mode control and resource locking |
-| 📝 Scripts | **Available** | Diagnostic script upload and execution (SOVD 7.15) |
-| 🧹 Clear Data | Planned | Clear cached and learned diagnostic data |
-| 📞 Communication Logs | Planned | Protocol-level communication logging |
-
-## 📖 Overview
-
-ros2_medkit models a robot as a **diagnostic entity tree**:
-
-| Entity | Description | Example |
-|--------|-------------|---------|
-| **Area** | Physical or logical domain | `base`, `arm`, `safety`, `navigation` |
-| **Component** | Hardware or software component within an area | `motor_controller`, `lidar_driver` |
-| **Function** | Capability provided by one or more components | `localization`, `obstacle_detection` |
-| **App** | Deployable software unit | node, container, process |
-
-Compatible with the **SOVD (Service-Oriented Vehicle Diagnostics)** model — same concepts across robots, vehicles, and embedded systems.
-
-## 📋 Requirements
-
-- **OS:** Ubuntu 24.04 LTS (Jazzy / Rolling) or Ubuntu 22.04 LTS (Humble)
-- **ROS 2:** Jazzy Jalisco, Humble Hawksbill, or Rolling (experimental)
-- **Compiler:** GCC 11+ (C++17 support)
-- **Build System:** colcon + ament_cmake
-
-## 📚 Documentation
-
-- 📖 [Full Documentation](https://selfpatch.github.io/ros2_medkit/)
-- 🗺️ [Roadmap](https://selfpatch.github.io/ros2_medkit/roadmap.html)
-- 📋 [GitHub Milestones](https://github.com/selfpatch/ros2_medkit/milestones)
-
-## 💬 Community
+for details. Feedback welcome on [#265](https://github.com/selfpatch/ros2_medkit/issues/265).
 
-We'd love to have you join our community!
+## What you get
 
-- **💬 Discord** — [Join our server](https://discord.gg/6CXPMApAyq) for discussions, help, and announcements
-- **🐛 Issues** — [Report bugs or request features](https://github.com/selfpatch/ros2_medkit/issues)
-- **💡 Discussions** — [GitHub Discussions](https://github.com/selfpatch/ros2_medkit/discussions) for Q&A and ideas
+**Start here: Faults.** Your robot has 47 nodes. Something throws an error.
+Instead of grepping logs, you query `GET /api/v1/faults` and get a structured list
+with fault codes, timestamps, affected entities, environment snapshots, and history.
+Clear faults, subscribe to new ones via SSE, correlate them across components.
 
----
+Beyond faults, medkit exposes the full ROS 2 graph through REST:
 
-## 🛠️ Development
+| | What it does |
+|---|---|
+| **Discovery** | Automatically finds running nodes, topics, services, and actions |
+| **Data** | Read and write topic data via REST |
+| **Operations** | Call services and actions with execution tracking |
+| **Configurations** | Read, write, and reset node parameters |
+| **Bulk Data** | Upload/download files (calibration, firmware, rosbags) |
+| **Subscriptions** | Stream live data and fault events via SSE |
+| **Triggers** | Condition-based push notifications for resource changes |
+| **Locking** | Resource locking for safe concurrent access |
+| **Scripts** | Upload and execute diagnostic scripts on entities |
+| **Software Updates** | Async prepare/execute lifecycle with pluggable backends |
+| **Authentication** | JWT-based RBAC (viewer, operator, configurator, admin) |
+| **Logs** | Log entries and configuration |
 
-This section is for contributors and developers who want to build and test ros2_medkit locally.
+On the [roadmap](https://selfpatch.github.io/ros2_medkit/roadmap.html): entity lifecycle control, mode management, communication logs.
 
-### Pre-commit Hooks
+## How it organizes your robot
 
-This project uses [pre-commit](https://pre-commit.com/) to automatically run
-`clang-format`, `flake8`, and other checks on staged files before each commit,
-plus an incremental clang-tidy check on `git push`.
+medkit models your system as an **entity tree** with four levels:
 
-```bash
-pip install pre-commit
-pre-commit install
-pre-commit install --hook-type pre-push
 ```
-
-To run all hooks against every file (useful after first setup):
-
-```bash
-pre-commit run --all-files
+Areas          Components         Apps (nodes)
+─────          ──────────         ────────────
+base       ┬─ motor_controller ┬─ left_wheel_driver
+           │                   └─ right_wheel_driver
+           └─ battery_monitor  └─ bms_node
+
+navigation ┬─ lidar_driver     └─ rplidar_node
+           └─ nav_stack        ┬─ nav2_controller
+                               ├─ nav2_planner
+                               └─ nav2_bt_navigator
 ```
 
-### Installing Dependencies
+A small robot might have a single area. A large robot can use areas to separate physical domains:
 
-```bash
-rosdep install --from-paths src --ignore-src -r -y
 ```
-
-### Building
-
-```bash
-colcon build --symlink-install
-```
-
-### Testing
-
-Use the `scripts/test.sh` convenience script:
-
-```bash
-source install/setup.bash
-./scripts/test.sh              # unit tests only (default)
-./scripts/test.sh integ        # integration tests only
-./scripts/test.sh lint         # linters (excluding clang-tidy)
-./scripts/test.sh tidy         # clang-tidy only (slow, ~8-10 min)
-./scripts/test.sh all          # everything
-./scripts/test.sh <test_name>  # single test by CTest name regex
-```
-
-You can pass extra colcon arguments after the preset:
-
-```bash
-./scripts/test.sh unit --packages-select ros2_medkit_gateway
+areas/
+├── base/
+│   └── components/
+│       ├── motor_controller/   → apps: left_wheel, right_wheel
+│       └── battery_monitor/    → apps: bms_node
+├── arm/
+│   └── components/
+│       ├── joint_controller/   → apps: joint_1..joint_6
+│       └── gripper/            → apps: gripper_driver
+├── navigation/
+│   └── components/
+│       ├── lidar_driver/       → apps: rplidar_node
+│       ├── camera_driver/      → apps: realsense_node
+│       └── nav_stack/          → apps: controller, planner, bt_navigator
+└── safety/
+    └── components/
+        ├── emergency_stop/     → apps: estop_monitor
+        └── collision_detect/   → apps: collision_checker
 ```
 
-### Pre-push Hook (clang-tidy)
+**Functions** cut across the tree. A function like `localization` might depend on apps from both `navigation` and `base`, giving you a capability-oriented view alongside the physical hierarchy.
 
-An incremental clang-tidy check runs automatically on `git push` via pre-commit, analyzing only changed `.cpp` files. Typical run takes 5-30s vs 8-10 min for a full analysis.
+This entity model follows the **SOVD (Service-Oriented Vehicle Diagnostics)** standard, so the same concepts work across robots, vehicles, and embedded systems.
 
-Setup:
-
-```bash
-# Install the pre-push hook (if not already done above)
-pre-commit install --hook-type pre-push
+## 📋 Requirements
 
-# Build the merged compile_commands.json (required once after build)
-./scripts/merge-compile-commands.sh
-```
+- **OS:** Ubuntu 24.04 LTS (Jazzy / Rolling) or Ubuntu 22.04 LTS (Humble)
+- **ROS 2:** Jazzy Jalisco, Humble Hawksbill, or Rolling (experimental)
+- **Compiler:** GCC 11+ (C++17 support)
+- **Build System:** colcon + ament_cmake
 
-To run manually without pushing:
+## 📚 Documentation
 
-```bash
-./scripts/clang-tidy-diff.sh
-```
+- 📖 [Full Documentation](https://selfpatch.github.io/ros2_medkit/)
+- 🗺️ [Roadmap](https://selfpatch.github.io/ros2_medkit/roadmap.html)
+- 📋 [GitHub Milestones](https://github.com/selfpatch/ros2_medkit/milestones)
 
-### Code Coverage
+## 💬 Community
 
-To generate code coverage reports locally:
+- **💬 Discord** - [Join our server](https://discord.gg/6CXPMApAyq) for discussions, help, and announcements
+- **🐛 Issues** - [Report bugs or request features](https://github.com/selfpatch/ros2_medkit/issues)
+- **💡 Discussions** - [GitHub Discussions](https://github.com/selfpatch/ros2_medkit/discussions) for Q&A and ideas
 
-1. Build with coverage flags enabled:
+## 🤝 Contributing
 
-```bash
-colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Debug -DENABLE_COVERAGE=ON
-```
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for build instructions, testing, pre-commit hooks, CI/CD details, and code coverage.
 
-2. Run tests:
+Quick version:
 
 ```bash
+pipx install pre-commit && pre-commit install && pre-commit install --hook-type pre-push
+colcon build --symlink-install
 source install/setup.bash
-colcon test --ctest-args -LE linter
-```
-
-3. Generate coverage report:
-
-```bash
-lcov --capture --directory build --output-file coverage.raw.info --ignore-errors mismatch,negative
-lcov --extract coverage.raw.info '*/ros2_medkit/src/*/src/*' '*/ros2_medkit/src/*/include/*' --output-file coverage.info --ignore-errors unused
-lcov --list coverage.info
-```
-
-4. (Optional) Generate HTML report:
-
-```bash
-genhtml coverage.info --output-directory coverage_html
+./scripts/test.sh          # unit tests
+./scripts/test.sh all      # everything
 ```
 
-Then open `coverage_html/index.html` in your browser.
-
-### CI/CD
-
-All pull requests and pushes to main are automatically built and tested using GitHub Actions.
-The CI workflow tests across **ROS 2 Jazzy** (Ubuntu 24.04), **ROS 2 Humble** (Ubuntu 22.04), and **ROS 2 Rolling** (Ubuntu 24.04, allow-failure):
-
-**build-and-test** (matrix: Humble + Rolling):
-
-- Full build with ccache and unit/integration tests
-- Rolling jobs are allowed to fail (best-effort forward-compatibility)
-
-**jazzy-build** / **jazzy-lint** / **jazzy-test**:
-
-- `jazzy-build` compiles all packages with ccache and clang-tidy enabled
-- `jazzy-lint` and `jazzy-test` run in parallel after the build completes
-- Linting includes clang-format, clang-tidy, copyright, cmake-lint, and more
-
-**coverage** (Jazzy only):
-
-- Builds with coverage instrumentation (Debug mode, ccache-enabled)
-- Runs unit and integration tests (excluding linters)
-- Generates lcov coverage report (available as artifact)
-- Uploads coverage to Codecov (only on push to main)
-
-After every run the workflow uploads test results and coverage reports as artifacts for debugging and review.
-
----
-
-## 🤝 Contributing
-
-Contributions are welcome! Whether it's bug reports, feature requests, documentation improvements, or code contributions — we appreciate your help.
-
-1. Read our [Contributing Guidelines](CONTRIBUTING.md)
-2. Check out [good first issues](https://github.com/selfpatch/ros2_medkit/labels/good%20first%20issue) for beginners
-3. Follow our [Code of Conduct](CODE_OF_CONDUCT.md)
+Check out [good first issues](https://github.com/selfpatch/ros2_medkit/labels/good%20first%20issue) for places to start.
 
 ## 🔒 Security
 
 If you discover a security vulnerability, please follow the responsible disclosure process in [SECURITY.md](SECURITY.md).
 
 ## 📄 License
 
-This project is licensed under the **Apache License 2.0** — see the [LICENSE](LICENSE) file for details.
+Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
 
 ---
 

diff --git a/docs/api/rest.rst b/docs/api/rest.rst
@@ -25,7 +25,7 @@ Server Capabilities
 
       {
         "name": "ROS 2 Medkit Gateway",
-        "version": "0.3.0",
+        "version": "0.4.0",
         "api_base": "/api/v1",
         "endpoints": [
           "GET /api/v1/health",
@@ -66,7 +66,7 @@ Server Capabilities
             "version": "1.0.0",
             "base_uri": "/api/v1",
             "vendor_info": {
-              "version": "0.3.0",
+              "version": "0.4.0",
               "name": "ros2_medkit"
             }
           }
@@ -494,6 +494,12 @@ Manage ROS 2 node parameters.
 ``DELETE /api/v1/components/{id}/configurations``
    Reset all parameters to default values.
 
+Resource Locking
+----------------
+
+SOVD resource locking for preventing concurrent modification of entity state.
+See :doc:`locking` for the full API reference.
+
 Faults Endpoints
 ----------------