topicforge 0.5.3__tar.gz → 0.5.5__tar.gz

{topicforge-0.5.3 → topicforge-0.5.5}/.gitignore

@@ -230,3 +230,8 @@ CLAUDE*.md
 # Pro tier: paid features kept out of the open-source repo
 # -------------------------------------------------------------------------
 pro/
+
+# Vendor license files for the demo participants (never commit)
+scripts/integration/**/rti_license.dat
+scripts/integration/**/*.dat
+.venv-demo/

{topicforge-0.5.3 → topicforge-0.5.5}/CHANGELOG.md

@@ -7,6 +7,233 @@ and this project adheres to [Semantic Versioning 2.0.0](https://semver.org/spec/
 
 ## [Unreleased]
 
+## [0.5.5] - 2026-10-02
+
+Driven by a blind evaluation: agents given only TopicForge's tools had to
+diagnose live DDS buses with planted faults. The first rounds (on 0.5.4) found
+wrong blame on QoS, missed Liveliness and Ownership faults, hand-joined GUIDs
+and empty results read as "healthy". After the changes below, 16 of 16
+scenarios were diagnosed correctly, with no false alarm on a healthy bus.
+
+### Added
+
+- **`list_endpoints`, the 12th MCP tool.** Returns every announced DDS writer
+  and reader as a typed `EndpointInfo` (role, topic, type, owning participant
+  guid, name and vendor, structured QoS, announcement timestamp) plus a
+  `by_topic` roll-up that flags orphans (`no_reader`, `no_writer`). TopicForge's
+  own endpoints are excluded unless `include_observer`, and counted in
+  `excluded_observer_endpoints`. Endpoints of a participant that left are kept
+  (200 entries, 1 hour) and shown as `departed_writers` / `departed_readers`;
+  `include_departed` lists them. Served by Cyclone and the mock. Fast raises a
+  clear "not supported yet" error.
+- **Continuous discovery tracking on Cyclone.** A daemon thread (0.5 s period)
+  is the only code that reads the builtin discovery topics and feeds in-memory
+  caches that every discovery tool reads. Lifecycle no longer moves only when a
+  tool is called: a node restarted three times shows as 3 `lost` and 4
+  `discovered`, dated by DDS. The 2 s warm-up sleep is gone.
+- Timestamps on `participant_events` and `list_participants`: `announced_ns`,
+  `lost_ns`, `lost_time_source`, and on events `time_source` and `observed_ns`.
+  A DDS source timestamp and a local observation are never mixed.
+- `health_check` gains `now_ns`, `observer_started_ns`, `observed_domain_note`
+  and the tracker status (`tracker_running`, `tracker_passes`, `tracker_errors`,
+  `tracker_last_pass_ns`).
+- `QosProfile` gains optional `liveliness_kind`, `liveliness_lease_ns`,
+  `ownership_kind`, `ownership_strength`, `partitions`, `latency_budget_ns`,
+  `destination_order` and `data_representation`, read from Cyclone discovery.
+  A missing Partition policy is reported as `[""]` everywhere.
+- `peek_dds_samples` on `DCPSPublication`, `DCPSSubscription` and
+  `DCPSParticipant` carries structured `role`, `participant_guid`,
+  `participant_name`, `type_id`, `qos`, `announced_ns` and `is_observer`, and
+  sets `timestamp_ns` from the announcement. `_raw_text` is kept only for a
+  sample with nothing structured to read, truncated to 300 characters.
+- `peek_dds_samples` on a builtin topic returns the cached discovery state, not
+  a stream.
+- Topic filters accept `rt/x` and `x` interchangeably and report which form
+  matched. A filter that matches nothing returns the list of known topics.
+- Examples: the generic role nodes take partition, liveliness and ownership
+  options.
+
+### Changed
+
+- **Breaking: `detect_qos_mismatches` returns a `MismatchScan` envelope instead
+  of a bare list.** To migrate, read `["reports"]` where you used the list. The
+  envelope also carries `matched`, `not_matched`, `hints`, `pairs_checked`,
+  `topics_scanned`, `policies_checked`, `policies_unchecked` and
+  `mode_effective`. Why: an empty list was read as a healthy bus although only
+  four policies were checked, and readers and writers in different partitions
+  were blamed on Reliability.
+- Partition is checked first (`*` and `?` wildcards; a wildcard against a
+  wildcard never matches). A pair it separates is a `not_matched` entry with
+  reason `partition`; differing type names give reason `type_name`. The RxO
+  rules are not run on either. A `not_matched` pair lists the policies that
+  would be incompatible if it matched (`latent_incompatible_policies`).
+- Liveliness (kind and lease), LatencyBudget, Ownership (kind equality),
+  DestinationOrder and DataRepresentation join Reliability, Durability and
+  Deadline. History stays a labelled `risky` finding. A policy a side did not
+  announce is skipped, never guessed.
+- `MismatchReport` gains, additively, the reader and writer participant guid and
+  name, type names, `details` (requested and offered value, failed rule) and
+  `unchecked`.
+- Hints cover orphan topics whose names differ by at most 2 edits (compared
+  against all topics), path-suffix matches and XTypes type id differences (a
+  note, never a mismatch). Hints are prioritized and say how many were omitted.
+- A late joiner is not a hint (it is normal on most buses): a `MatchedPair` is
+  flagged `late_joiner` when its writer is VOLATILE and the reader, on the same
+  host, appeared more than 1 s later.
+- `reports`, `matched` and `not_matched` are capped at 200 entries each, with
+  `reports_total`, `matched_total`, `not_matched_total` and `truncated`.
+- `topic_metrics` reports a `status`, and on a user topic says it has no data
+  instead of returning zeros. `peek_dds_samples` on a user topic returns count
+  0 and a note. `ParticipantInfo` and endpoints gain `is_observer`, and
+  `vendor_source` says where a vendor came from.
+- Tool descriptions no longer carry internal history, and state the
+  single-domain and EXCLUSIVE-ownership facts.
+- `EndpointInfo.activity` is reserved (always `None`) with an `activity_note`
+  saying liveness is not observed.
+
+### Fixed
+
+- Infinite durations (cyclonedds reports 9223372036854775807) are normalized
+  to `None`; an infinite Deadline used to surface as a 9.2e18 ns deadline.
+- The Cyclone discovery tracker is stopped at interpreter exit.
+- A race between the tracker and a tool call could mark a live participant as
+  lost for good; a failed read could drop a participant's departure; endpoints
+  of a participant that had just left could stay listed as live. The tracker
+  and every tool now share one lock, and taken samples are never discarded.
+- The cyclonedds Python binding is not thread-safe when it converts QoS: two
+  threads in `take()` at once corrupted the heap on Windows. Every binding call
+  now goes through one process-wide lock, and tool handlers no longer call the
+  binding at all.
+- If every tracker pass fails, tools no longer wait 3 s each: warm-up is bounded
+  once. `health_check` reports failed passes and cache evictions.
+- An unreadable QoS duration is treated as unknown (`QosProfile.unknown_policies`),
+  not as infinite, so it cannot produce a false Deadline incompatibility.
+- Topic-name typo hints are bounded (banded edit distance, orphan cap, call
+  budget), so a bus with a thousand topics does not stall the call.
+- Partition matching was checked against a live Cyclone bus: `*` and `?` are
+  wildcards, `[...]` is literal, and two wildcard expressions never match each
+  other. Pinned by tests.
+
+### Known limits
+
+- A hung writer (alive, lease renewed, no data) is not observable without a
+  data probe. An opt-in probe is planned for 0.5.6.
+- A crash and a clean leave cannot be told apart, and `lost_ns` is an upper
+  bound of the death (the lease expiry after a crash).
+- A participant that cycles faster than the discovery history depth between two
+  tracker passes can be missed.
+- The Fast DDS backend has never run on a bus, and `list_endpoints` is not
+  supported there.
+- DDS Security is not supported.
+- User-topic payload decoding is disabled, so `topic_metrics` has no data on
+  user topics.
+
+## [0.5.4] - 2026-10-02
+
+First run of the DDS code against a live multi-vendor bus (Windows 11, a
+Python / Cyclone DDS participant and a Rust / Dust DDS participant, TopicForge
+driven by a real MCP client). Until now every DDS adapter had only been
+checked statically. The run exposed four defects that together made the DDS
+module non-functional on Cyclone; all are fixed and pinned by tests.
+
+### Fixed
+
+- Role nodes published below their rate (about 7 Hz for 10 Hz on Windows):
+  they now keep an absolute schedule.
+
+- **`list_participants` now reports the participant name and the hostname on
+  Cyclone.** The name comes from the EntityName QoS and the hostname from the
+  `__Hostname` discovery property; both were always null on a real bus.
+- **Participant GUIDs were never read.** cyclonedds 11.0.1 exposes the builtin
+  key as a `uuid.UUID`, which the extractor did not handle, so every
+  participant collapsed onto a single `unknown` entry.
+- **Vendors were never identified.** The builtin participant sample carries no
+  vendor field. The vendor id is now read from the first two bytes of the GUID
+  prefix, as RTPS recommends; implementations that do not follow that
+  convention (Dust DDS, and RTI by default) still report `unknown`, because
+  the Cyclone Python binding does not expose the vendor id from the RTPS
+  header.
+- **The OMG vendor-id table was wrong.** It mapped `01.05` to Fast DDS and
+  `01.16` to Cyclone; the correct ids are `01.0F` (eProsima) and `01.10`
+  (Eclipse), verified against both vendors' sources. The Cyclone side ran on a
+  live bus; the Fast DDS side (`fast_extract_vendor_id`) is verified
+  statically only, since its tests need a binding that is not on PyPI. The `vendor` field of
+  `ParticipantInfo` and `ParticipantEvent` now also accepts `rti_micro`,
+  `opensplice`, `opendds`, `coredx`, `intercom` and `dust` (soft-breaking for
+  clients validating the previous enum).
+- **`detect_qos_mismatches` never reported anything on Cyclone.** cyclonedds
+  scopes its policy class names (`Reliability.BestEffort`), and the
+  normalizer matched only the bare name, so no QoS profile was ever built.
+- **A stopped participant never disappeared.** Discovery readers keep the last
+  sample of a departed participant with a NOT_ALIVE instance state; those are
+  now ignored for participants and endpoints, so a participant is reported as
+  left when its lease expires, and a dead endpoint no longer produces a
+  mismatch.
+
+- Cyclone adapter created a new DDS reader on a builtin discovery topic on
+  every tool call and never deleted it. It now keeps one reader per builtin
+  topic and takes a non-blocking snapshot, so calls no longer wait 2 s each
+  (`detect_qos_mismatches` waited 4 s).
+- `peek_dds_samples` on `DCPSPublication` / `DCPSSubscription` reported the
+  endpoints of participants that had left; disposed entries are now dropped.
+  Its payload also carries the endpoint `type_name`.
+- `test_dds_cross_vendor.py` expected an error message from v0.3; it had
+  never run, since CI has no DDS binding. First run against the real Cyclone
+  binding.
+
+### Added
+
+- `examples/dds/`: a "write the code" track. Examples 00 (hello publisher
+  and subscriber), 05 (Reliability), 06 (Durability and the late joiner),
+  07 (Deadline declared and kept) and 08 (a crash seen from inside and from
+  outside) each ship a readable `publisher.py` and `subscriber.py` in Cyclone
+  DDS Python; the subscriber prints what it receives and the DDS statuses,
+  and TopicForge explains the same situation from outside. All fourteen
+  examples pass on a live bus.
+- The generic role nodes print one line per second per reader with what
+  they received, and examples 02, 04, 10 and 13 check that the broken
+  subscriber receives nothing while the control one receives data.
+- The harness keeps each program's output in a log file and prints it live
+  under `--hold`.
+
+- `scripts/integration/interop_check.py`: one-command multi-vendor demo
+  that starts a Rust / Dust and a Python / Cyclone participant, drives
+  TopicForge over stdio through the official MCP client, checks participant
+  discovery, a deliberate Reliability mismatch between the two vendors, and
+  the departure of a stopped participant, then stops every process it started.
+- A real Rust / Dust DDS participant (`publishers/dust_publisher`) and a real
+  Python / Cyclone participant replacing the previous scaffold, which never
+  wrote a sample.
+- Twelve interop programs in total, one per vendor and language with an
+  officially released binding (Cyclone C / C++ / Rust / Python, Dust Rust /
+  Python, Fast DDS C++ / Python, RTI Connext C / C++ / Python, OpenSplice C),
+  all following the contract in `scripts/integration/DEMO_CONTRACT.md`. The
+  driver starts whichever ones are built on the host and adapts its checks;
+  `--list` shows what can run. Only Cyclone Python and Dust Rust / Python / C
+  have been run, on Windows; the rest are written but unrun. RTI participants
+  need a local license and are never run in CI.
+- One-command launch scripts, `scripts/integration/launch/setup` and
+  `run_demo` (`.ps1` and `.sh`), which create `.venv-demo`, install the Cyclone
+  binding and build the Rust participant. `setup.ps1 -Firewall` adds inbound
+  UDP 7400-7500 rules on private networks for multi-machine runs.
+- Unicast peer configuration for Cyclone and Fast DDS and a guide for a mixed
+  Linux and Windows bus (`scripts/integration/config/`).
+- `.github/workflows/demo.yml` runs the driver with the Cyclone and Dust
+  participants on Ubuntu and Windows; `demo-fast.yml` builds Fast DDS 3 from
+  pinned tags and starts the C++ participant (weekly and manual).
+- `scripts/integration/README.md` rewritten around the demo: it previously
+  described the removed docker / scenario rig.
+
+- `examples/dds/`: real use cases 10 to 14 (driver swap, wiring, safety
+  monitor dropout, deadline not offered, restart loop) next to the concept
+  examples 01 to 04. All nine pass on a live bus.
+
+### Removed
+
+- The docker / scenario integration rig (`scenarios_runner.py`, `run-local.*`,
+  `docker-compose.yml`, per-vendor Dockerfiles, scenario JSON files, schema
+  test and `integration.yml`) is removed in favour of the demo driver.
+
 ## [0.5.3] - 2026-10-01
 
 Fixes from an independent senior review of the whole repository (five
@@ -23,8 +250,9 @@ the findings.
   because the names are unclaimed anyone could have registered them: users
   following the documented `pip install topicforge[dds]` would then have run
   that code. Those extras are removed; `[dds]` now means Cyclone only. The
-  metadata of 0.3.0 to 0.5.2 is immutable on PyPI, which is why those
-  releases are being yanked and a security advisory published.
+  metadata of 0.3.0 to 0.5.2 is immutable on PyPI, so those releases have
+  been yanked: `pip install topicforge` no longer selects them, although an
+  exact pin such as `topicforge==0.5.2` still installs one.
 - **Removed the automatic `topicforge_pro` plugin hook.** At startup the
   server imported any installed package named `topicforge_pro` and handed it
   the full MCP server instance, so a third-party package with that
@@ -1007,7 +1235,9 @@ Initial MVP release of TopicForge: ROS Topic Inspector & Bag Analyzer MCP server
 - The write path (publishing, commanding robots) is intentionally out of scope for the MVP.
 - `analyze_bag` in live mode parses `ros2 bag info` text output; deeper anomaly detection remains mock-only for now.
 
-[Unreleased]: https://github.com/yaniswav/TopicForge/compare/v0.5.3...HEAD
+[Unreleased]: https://github.com/yaniswav/TopicForge/compare/v0.5.5...HEAD
+[0.5.5]: https://github.com/yaniswav/TopicForge/compare/v0.5.4...v0.5.5
+[0.5.4]: https://github.com/yaniswav/TopicForge/compare/v0.5.3...v0.5.4
 [0.5.3]: https://github.com/yaniswav/TopicForge/compare/v0.5.2...v0.5.3
 [0.5.2]: https://github.com/yaniswav/TopicForge/compare/v0.5.1...v0.5.2
 [0.5.1]: https://github.com/yaniswav/TopicForge/compare/v0.5.0...v0.5.1

topicforge-0.5.5/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.5
+Name: topicforge
+Version: 0.5.5
+Summary: ROS Topic Inspector & Bag Analyzer MCP server for AI agents
+Project-URL: Homepage, https://github.com/yaniswav/TopicForge
+Project-URL: Repository, https://github.com/yaniswav/TopicForge
+Project-URL: Issues, https://github.com/yaniswav/TopicForge/issues
+Project-URL: Changelog, https://github.com/yaniswav/TopicForge/blob/main/CHANGELOG.md
+Author-email: Yanis ETHVIGNOT <ethvignot.yanis@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Yanis ETHVIGNOT
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: ai,claude,mcp,model-context-protocol,robotics,ros2
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: mcp<2,>=1.0.0
+Requires-Dist: pydantic>=2.6
+Provides-Extra: all
+Requires-Dist: cyclonedds>=0.10; extra == 'all'
+Provides-Extra: bags
+Requires-Dist: rosbags>=0.9; extra == 'bags'
+Provides-Extra: dds
+Requires-Dist: cyclonedds>=0.10; extra == 'dds'
+Provides-Extra: dds-cyclone
+Requires-Dist: cyclonedds>=0.10; extra == 'dds-cyclone'
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: rosbags>=0.9; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# TopicForge
+
+<!-- mcp-name: io.github.yaniswav/topicforge -->
+
+[![PyPI version](https://img.shields.io/pypi/v/topicforge.svg)](https://pypi.org/project/topicforge/)
+[![CI](https://github.com/yaniswav/TopicForge/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/yaniswav/TopicForge/actions/workflows/ci.yml)
+[![Python versions](https://img.shields.io/pypi/pyversions/topicforge.svg)](https://pypi.org/project/topicforge/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/yaniswav/TopicForge/blob/main/LICENSE)
+[![Read-only by architecture](https://img.shields.io/badge/safety-read--only_by_architecture-2563eb)](https://github.com/yaniswav/TopicForge#security-model)
+
+A read-only MCP (Model Context Protocol) server that lets an AI agent inspect a ROS2 graph, recorded bag files and the DDS layer underneath ROS, without being able to publish to the bus or command a robot. It is read-only by **architecture**, not by configuration: there is no write path to misconfigure and no permission system to audit.
+
+Without grounding, an LLM asked about a robot will invent topic names, message types and bag contents. TopicForge gives it **twelve typed tools** that return frozen Pydantic schemas, identical whether the server talks to a real robot or to its built-in mock fixtures. It is aimed at ROS2 developers, robotics ML/CV engineers and teams that cannot accept a write path into a production stack.
+
+For DDS, TopicForge joins a domain as a read-only participant through one open-source binding (Eclipse CycloneDDS from PyPI) and reads the builtin discovery topics that the OMG DDS-RTPS protocol standardizes. Every conformant vendor announces itself there, so a Cyclone participant also sees RTI Connext, OpenDDS, CoreDX and Dust DDS endpoints without any proprietary binding. This covers discovery only: participants, readers, writers and their QoS. See [`docs/dds-interop-matrix.md`](docs/dds-interop-matrix.md).
+
+## Quickstart
+
+No ROS2 needed; the mock adapter serves deterministic fixtures for a small differential robot (LIDAR + RGB camera). Python 3.10 to 3.13.
+
+```bash
+pip install topicforge
+TOPICFORGE_MODE=mock python -m topicforge
+# Windows PowerShell: $env:TOPICFORGE_MODE="mock"; python -m topicforge
+```
+
+The server speaks MCP over stdio and waits for a client, so wire it into one. For Claude Desktop, add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "topicforge": {
+      "command": "python",
+      "args": ["-m", "topicforge"],
+      "env": { "TOPICFORGE_MODE": "auto" }
+    }
+  }
+}
+```
+
+Then ask it to list the topics or to analyze `/tmp/demo.mcap`. For Claude Code: `claude mcp add topicforge -- topicforge`. Setup for a real ROS2 environment (WSL2, Linux, Docker, native Windows) is in [`docs/TESTING.md`](docs/TESTING.md); recurring monitoring prompts and the privacy contract are in [`docs/TUTORIEL.md`](docs/TUTORIEL.md).
+
+## Tools
+
+All twelve tools are read-only. Every response except `health_check` carries `mode_effective` (`"live"` or `"mock"`), so a caller can tell a real graph from fixtures.
+
+| Tool                    | Purpose                                                                                          |
+| ----------------------- | ------------------------------------------------------------------------------------------------ |
+| `health_check`          | Environment and mode introspection. Always succeeds; reports `mode` next to `requested_mode`      |
+| `list_topics`           | Discover the ROS2 graph                                                                          |
+| `get_topic_info`        | Message type, publisher/subscriber counts and QoS for one topic                                  |
+| `sample_messages`       | Peek recent messages on a ROS2 topic (count clamped to 50)                                       |
+| `analyze_bag`           | Summarize a `.mcap` / `.db3` / `.bag` recording                                                  |
+| `list_participants`     | DDS participants on the domain: vendor, `name` (EntityName QoS, Cyclone) and `hostname`          |
+| `detect_qos_mismatches` | Incompatible QoS pairs between DDS readers and writers                                           |
+| `peek_dds_samples`      | Raw DDS samples; structured on the three builtin discovery topics, presence-only on user topics   |
+| `participant_events`    | Timeline of participant `discovered` / `lost` events                                             |
+| `topic_metrics`         | Frequency, sequence-gap and latency schema; data only for builtin discovery topics               |
+| `peek_bag_samples`      | Decoded samples from a recorded bag (needs `pip install topicforge[bags]`)                       |
+| `list_endpoints`        | DDS writers and readers with structured QoS, per-topic roll-up that flags orphans (writer with no reader, reader with no writer) |
+
+Walkthroughs against the mock, each with the exact tool calls and payloads, are in [`examples/`](examples/README.md). To run the DDS tools against a real bus with several programs and vendors, see [`examples/dds/README.md`](examples/dds/README.md) (`python examples/dds/run_all.py`).
+
+## Modes
+
+| Mode   | When to use                                      | Backend                    |
+| ------ | ------------------------------------------------ | -------------------------- |
+| `mock` | Development, demos, CI, screencasts              | Deterministic fixtures     |
+| `live` | ROS2 sourced and on PATH, and/or a DDS backend   | `ros2` CLI, DDS participant |
+| `auto` | Detect what is available, else mock (default)    | Best available             |
+
+`live` and `auto` degrade instead of failing: if neither `ros2` nor a DDS backend comes up, the server serves the mock fixtures and `health_check` reports `mode: "mock"` next to `requested_mode`. Only `TOPICFORGE_MODE=mock` forces fixtures unconditionally. The live ROS2 adapter shells out to the `ros2` CLI, so `rclpy` does not need to be importable.
+
+## DDS backends
+
+```bash
+pip install topicforge[dds]                      # Eclipse CycloneDDS ([dds-cyclone] is the same thing)
+TOPICFORGE_DDS_BACKEND=cyclone python -m topicforge
+```
+
+`TOPICFORGE_DDS_BACKEND` accepts `mock` (default), `cyclone`, `fast` and `auto` (`fast`, then `cyclone`, then `mock`, whichever binding imports). An explicit value is honoured with or without `ros2` on PATH, in any mode except `mock`. If the binding is missing or the participant cannot start, the server logs a warning naming the cause and falls back to the ROS2 CLI alone, or to the mock fixtures. When both `ros2` and a DDS backend are up, a composite adapter routes the five ROS2 graph and bag tools to the CLI and the seven DDS tools to the DDS backend.
+
+A Fast DDS adapter exists but has never run against a bus, and its `fastdds` Python binding is not on PyPI: build it from eProsima's sources and install it next to TopicForge. There is no `[dds-fast]` extra. `opendds` and `dust` are permanent stubs that never serve. `rti`, `opensplice`, `coredx` and `intercom` are rejected with a configuration error, since the Pro tier is retired (see [`docs/pro.md`](docs/pro.md)). Full backend selection, the routing table and the QoS mismatch scenario are in [`docs/DDS_QUICKSTART.md`](docs/DDS_QUICKSTART.md); error messages are in [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md).
+
+## Configuration reference
+
+| Variable                   | Default | Description                                                                                       |
+| -------------------------- | ------- | ------------------------------------------------------------------------------------------------- |
+| `TOPICFORGE_MODE`          | `auto`  | `mock`, `live` or `auto`                                                                          |
+| `TOPICFORGE_LOG_LEVEL`     | `INFO`  | `DEBUG`, `INFO`, `WARNING`, `ERROR`                                                               |
+| `TOPICFORGE_ROS2_BIN`      | `ros2`  | Name or path of the ROS2 CLI binary                                                               |
+| `TOPICFORGE_TELEMETRY`     | `off`   | Opt-in anonymous telemetry; an unrecognized value aborts startup. See [Telemetry](#telemetry)     |
+| `TOPICFORGE_DDS_BACKEND`   | `mock`  | `mock`, `cyclone`, `fast`, `auto` (`opendds` and `dust` are stubs)                                 |
+| `TOPICFORGE_DDS_DOMAIN_ID` | `0`     | DDS domain observed (0..232). Joined at startup; changing it needs a restart                      |
+
+Samples with comments are in [`.env.example`](.env.example). Any invalid value stops the server with `topicforge: configuration error: ...` and exit code 2, so a typo cannot silently change behaviour.
+
+## Limitations
+
+- **DDS validation is partial.** The Cyclone adapter has run against a real bus, with Cyclone and Dust DDS participants, on Windows and in CI on Ubuntu and Windows (`.github/workflows/demo.yml`). The Fast DDS adapter has never run against a bus, and no RTI, OpenDDS, CoreDX or OpenSplice participant has been observed by this project. The multi-vendor claim rests on the RTPS protocol guarantee, not on a recorded cross-vendor run.
+- **User-topic payloads are not decoded.** `peek_dds_samples` on a user topic returns count 0 and a note that the topic is announced on the bus; no traffic is read. `topic_metrics` therefore has data only for the builtin discovery topics and says so in its `status`. It is a discovery-layer probe, not a publish-rate monitor.
+- **Liveliness at runtime is not observed.** A writer that is alive but silent (a hung process whose lease is still renewed) looks healthy, because TopicForge reads discovery, not data. An opt-in data probe is planned for 0.5.6. A crash and a clean leave cannot be told apart, and `lost_ns` is an upper bound of the death.
+- **Cyclone vendor ids.** Participants that do not follow the RTPS vendor-id convention in their GUID prefix (Dust DDS, and RTI by default) are reported with vendor `unknown`.
+- **Single domain.** The server observes the domain it joined at startup; changing it needs a restart.
+- **DDS Security is not handled.** A participant without credentials sees an empty secure bus. `detect_qos_mismatches` checks Partition, type name, Reliability, Durability, Deadline, Liveliness, LatencyBudget, Ownership (kind), DestinationOrder and DataRepresentation (History as a risk); Presentation, XTypes assignability and runtime behavior are not checked, and the result lists them in `policies_unchecked`. It returns a `MismatchScan` envelope: read `reports` for the mismatches.
+- **Fast DDS** serves no `list_endpoints`.
+- **`sample_messages` (live)** runs `ros2 topic echo --csv --once` with a short timeout; a topic with no current publisher returns an empty sample. `timestamp_ns` is the message `header.stamp` for `Header`-stamped types and `0` for headerless ones.
+- **`analyze_bag` (live)** parses `ros2 bag info` text and does not use `rosbags`; anomaly detection is mock-only. `peek_bag_samples` is the only tool that reads the file itself, through `rosbags`, and is served only by the ROS2 CLI adapter or the mock. Without `ros2`, bag tools return fixtures: check `health_check` for `mode: "mock"` before trusting bag output.
+- **Synchronous handlers.** The tools run on the MCP event loop; on Windows a hung `ros2` launcher can block the server.
+- No streaming or push subscriptions: tools are strictly request/response.
+
+The roadmap and the open work behind these limits are in [`docs/product-plan.md`](docs/product-plan.md).
+
+## Telemetry
+
+Opt-in, anonymous and **off by default**. When off, instrumentation returns the handler unchanged: no event is built, no transport is constructed, no network code runs (pinned by `tests/test_telemetry.py::test_build_app_off_makes_no_transport_calls`).
+
+```bash
+TOPICFORGE_TELEMETRY=on python -m topicforge
+```
+
+On-values: `on`, `1`, `true`, `yes`, `enabled`. Off-values: unset, `off`, `0`, `false`, `no`, `disabled`. Anything else is a configuration error, not a silent "off".
+
+When on, each tool call emits one event with exactly six fields:
+
+| Field        | Example         | Notes                                                       |
+| ------------ | --------------- | ----------------------------------------------------------- |
+| `tool_name`  | `"list_topics"` | One of the twelve tools, never argument values              |
+| `latency_ms` | `12.34`         | Handler wall-clock duration, 2 decimals                     |
+| `mode`       | `"mock"`        | Mode of the adapter actually serving: `mock` or `live`      |
+| `version`    | `"0.5.5"`       | TopicForge server version                                   |
+| `session_id` | `"a1b2c3..."`   | Random UUID per process, never persisted                    |
+| `success`    | `true`          | Whether the handler returned or raised                      |
+
+Never sent: topic names, message types or payloads, bag paths or contents, hostnames, usernames, IP addresses, environment variables, error messages. The field set is fenced by `tests/test_telemetry.py::test_payload_contains_only_whitelisted_keys`; adding a field requires updating this section. The default transport is a structured log line, there is no HTTP endpoint yet. The implementation is in [`src/topicforge/telemetry/`](src/topicforge/telemetry/).
+
+## Security model
+
+TopicForge is designed for **local trust**: it runs as a subprocess of your MCP client on a machine you control and inspects your own ROS2 graph, DDS domain and bag files. It is not hardened for adversarial inputs.
+
+- `TOPICFORGE_ROS2_BIN` accepts an arbitrary path; treat it the way you treat `PATH`.
+- `analyze_bag` and `peek_bag_samples` open whatever path the client passes (no workspace isolation, no symlink restriction).
+- All `ros2` invocations use `subprocess.run` with an argument list, never `shell=True`. ROS2 topic names are validated against `^/[A-Za-z0-9_/]+$` first.
+- The server loads no third-party code at startup. Until 0.5.2 it imported any installed `topicforge_pro` package; that hook was removed in 0.5.3 because it was an opening for a package of that name to add write tools.
+- No outbound network calls unless telemetry is turned on.
+
+Before exposing TopicForge to untrusted MCP clients (hosted endpoints, shared environments), add path isolation and revisit the `TOPICFORGE_ROS2_BIN` policy. Vulnerability reports: see [`SECURITY.md`](SECURITY.md).
+
+## Development
+
+```bash
+git clone https://github.com/yaniswav/TopicForge.git && cd TopicForge
+python -m venv .venv && source .venv/bin/activate     # Windows: .venv\Scripts\Activate.ps1
+pip install -e ".[dev]"
+python -m ruff check src tests
+python -m pytest
+```
+
+Tests run against the mock adapter, the live adapter's pure parsers and the binding-free DDS helpers; they never need a running ROS graph. Tests needing the `cyclonedds` or `fastdds` binding skip themselves when it is absent, and the `integration` marker (real-bus tests) is deselected by default. The `Makefile` (`make check`) uses POSIX shell syntax; on plain PowerShell run the commands above. See [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+## Upgrading
+
+TopicForge is pre-1.0 and the 0.x releases changed things freely; [`CHANGELOG.md`](CHANGELOG.md) is the record. Two points matter if you are coming from an old install. Releases 0.3.0 to 0.5.2 are yanked, so `pip install -U topicforge` resolves to 0.5.3 or later. And since 0.5.3 the `[dds-fast]`, `[dds-opendds]`, `[dds-dust]` and `[dds-all-oss]` extras no longer exist, the DDS backend values `rti`, `opensplice`, `coredx` and `intercom` are rejected, and `[dds]` and `[all]` resolve to Cyclone only. Schema changes across 0.x were additive optional fields; a client that pins a JSON Schema with `additionalProperties: false` needs to regenerate it.
+
+## Layout
+
+```
+src/topicforge/
+  server/      MCP bootstrap, build_app(settings)
+  tools/       thin FastMCP handlers, no backend logic
+  services/    input validation, orchestration, adapter factory
+  adapters/    ros2_live, ros2_mock, dds_cyclone, dds_fast, common/ (binding-free logic)
+  models/      frozen Pydantic schemas, the contract with MCP clients
+  config/      settings and mode resolution
+  telemetry/   opt-in, off by default
+examples/      mock walkthroughs (*.md) and runnable live DDS examples (dds/)
+scripts/       real-bus interop checks
+docs/          guides, product plan
+tests/         pytest suite, mock-only, no ROS2 or DDS required
+```
+
+Layers are strictly separated: handlers never call `subprocess`, adapters are the only code that talks to a backend, and new backends implement the `MiddlewareAdapter` protocol in `adapters/base.py`.
+
+## License
+
+MIT, see [LICENSE](LICENSE). Commercial support and integration work: [`docs/pro.md`](docs/pro.md).