topicforge 0.1.0__tar.gz → 0.1.2__tar.gz

{topicforge-0.1.0 → topicforge-0.1.2}/.gitignore

@@ -188,7 +188,19 @@ CLAUDE*.md
 
 
 # -------------------------------------------------------------------------
-# Project-local docs and drafts kept out of the package / out of clients
+# Project-local docs and drafts kept out of the package / out of clients.
+# Allowlist exceptions: the folder README explains the convention, and
+# `*-spec.md` files are committable specs produced by pack-growth streams
+# (e.g. Stream C of a release plan). Everything else under projet-file/
+# stays local: PDFs, personal market briefs, raw strategy notes.
 # -------------------------------------------------------------------------
-docs/projet-file/
-docs/assets/screencast-raw/
+/docs/projet-file/**
+!/docs/projet-file/README.md
+!/docs/projet-file/*-spec.md
+/docs/assets/screencast-raw/
+
+
+# -------------------------------------------------------------------------
+# Pro tier — paid features kept out of the open-source repo
+# -------------------------------------------------------------------------
+pro/

topicforge-0.1.2/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+All notable changes to TopicForge are documented in this file.
+
+The format is based on [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.2] - 2026-05-13
+
+### Fixed
+
+- `sample_messages` now returns real publish-time timestamps in live mode for `Header`-stamped messages. The live adapter previously shelled out to `ros2 topic echo --once`, which does not emit timestamps, so `MessageSample.timestamp_ns` was always `0`. The invocation is now `ros2 topic echo --csv --once`, whose flattened CSV exposes `header.stamp.sec` and `header.stamp.nanosec` as the first two columns for any `Header`-stamped message; the new `parse_csv_echo` parser reconstructs `timestamp_ns = sec * 1_000_000_000 + nanosec` and strips those two columns out of the payload. **Headerless message types** (e.g. `std_msgs/String`, `geometry_msgs/Twist`) still return `timestamp_ns=0` — they carry no embedded timestamp. Surfacing the rmw **receive** timestamp (rather than the publish-time `header.stamp`) for arbitrary message types remains a roadmap item tied to the future `rclpy`-backed adapter.
+
+### Added
+
+- **`mode_effective` on every tool response (schema, soft-breaking additive).** `TopicInfo`, `SampleResult`, and `BagAnalysis` now carry a required `mode_effective: Literal["mock", "live"]` field. A new `effective_mode` property on the `RosAdapter` protocol is the single source of truth; `Ros2CliAdapter` returns `"live"`, `MockAdapter` returns `"mock"`, services thread it through at result construction time. **Producer side**: Python code constructing these models directly must now supply `mode_effective` — models are `frozen=True, extra="forbid"` with no default. **Client side (over MCP)**: additive — an MCP client consuming JSON sees one extra key per response and is unaffected unless it strictly validates against the v0.1.1 schema with a no-extra-keys assumption.
+- **DdsForge spec** (`docs/projet-file/mcp-02-spec.md`). Strategic draft for MCP 02: safety-first read-only DDS observability across middleware vendors (CycloneDDS OSS, RTI Connext Pro tier). Five tools, `MiddlewareAdapter` protocol, mock + cyclone + rti + auto modes. Reviewer notes appended (2026-05-13): wrong cross-reference in §11 flagged.
+- **DatasetForge spec** (`docs/projet-file/mcp-03-spec.md`). Vision Dataset Inspector spec, re-slotted to MCP 03 after competitive-landscape audit that surfaced zero non-ROS DDS-MCP projects and made DdsForge the stronger MCP 02 candidate. Reviewer notes appended (2026-05-13): contradictory §11 phrasing and two implicitly-resolved open questions flagged.
+
+### Changed
+
+- **Safety-first read-only repositioning.** README and `docs/product-plan.md §1` now lead with "read-only by architecture, not by configuration" as the primary identity. Pack candidate list updated: MCP 02 is now DdsForge (non-ROS DDS observability, zero-competition niche); DatasetForge slides to MCP 03. Strategic context in `docs/product-plan.md §4` and §8 (DDS-complete horizon).
+- **Internal API.** `Inspector.sample_messages` now returns a `SampleResult` envelope (previously a `list[MessageSample]`). The MCP-facing tool handler is reduced to a thin pass-through. No effect on the tool's wire-level response shape (handlers already wrapped the list into `SampleResult`), but flagged here for anyone importing `Inspector` directly outside this repo.
+
+### Internal
+
+- Docstring fix in `parse_csv_echo`: the example output now shows post-strip payload keys as `col_0`, `col_1` (the parser re-indexes from `col_0` after dropping the two timestamp columns), matching the existing test in `tests/test_live_adapter_parse.py`.
+
+## [0.1.1] - 2026-05-13
+
+### Added
+
+- **Opt-in anonymous usage telemetry** behind `TOPICFORGE_TELEMETRY=on` (default: off). When enabled, each MCP tool call emits a single event with six fields only: `tool_name`, `latency_ms`, `mode`, `version`, `session_id` (random UUID per process, never persisted), and `success`. No topic names, message bodies, bag paths, hostnames, or environment data ever leave the process. See the README "Telemetry" section for the full payload contract and opt-out instructions.
+- `src/topicforge/telemetry/` module with `TelemetryClient`, `TelemetryEvent`, and an `instrument()` decorator that wraps tool handlers with timing + emit. When telemetry is off, `instrument()` is the identity function — zero overhead and zero possibility of a network call in the OFF code path.
+- Pluggable `Transport` callable; v0.1.1 ships a structured-log transport. A future S3-backed HTTP endpoint will plug in without touching tool handlers.
+- 29 telemetry tests covering: default-off behaviour, env var parsing (`on`/`1`/`true`/`yes`/`enabled` vs anything else), payload shape and key allowlist, payload privacy (user input never leaks), session id stability and per-process uniqueness, transport-exception isolation, decorator signature preservation, and end-to-end verification that the OFF code path never invokes the transport.
+
+### Changed
+
+- `Settings` gained a `telemetry_enabled: bool` field.
+- `build_app(...)` accepts optional `telemetry` and `telemetry_transport` parameters for test injection.
+- `register_tools(...)` now takes a `TelemetryClient`.
+- `.env.example` documents `TOPICFORGE_TELEMETRY`.
+- README adds a `Telemetry` section and updates the Security model note to reflect opt-in telemetry availability.
+
+## [0.1.0] - 2026-05-12
+
+Initial MVP release of TopicForge — ROS Topic Inspector & Bag Analyzer MCP server.
+
+### Added
+
+- Five read-only MCP tools exposed over FastMCP: `health_check`, `list_topics`, `get_topic_info`, `sample_messages`, and `analyze_bag`.
+- `RosAdapter` protocol in `adapters/base.py` defining the contract every backend implements.
+- Mock adapter (`adapters/ros2_mock/`) with deterministic fixtures modeling a small differential mobile robot equipped with a LIDAR and an RGB camera.
+- Live adapter (`adapters/ros2_live/`) built on subprocess wrappers around the `ros2` CLI, with pure module-level parsers tested independently of any ROS2 install.
+- Three runtime modes selectable via `TOPICFORGE_MODE`: `mock`, `live`, and `auto`. The `auto` resolution lives in `Settings.effective_mode`; the live-to-mock fallback when the adapter cannot start lives in `services/factory.py`.
+- Windows-first cross-platform support: executable resolution via `shutil.which` (handles `ros2.cmd` / `ros2.bat` shims), `subprocess.run` called with absolute paths and never `shell=True`, all filesystem paths via `pathlib.Path`.
+- Pydantic v2 schemas in `models/` configured with `extra="forbid"` and `frozen=True`, returned as the structured payload of every tool.
+- Pytest suite that runs entirely without a ROS2 environment, covering services, mock adapter, and live-adapter parsers.
+- Build, lint, and tooling configuration: Python 3.11+, `mcp >= 1.0.0` (FastMCP), `pydantic >= 2.6`, pytest, ruff, hatchling.
+- Licensed under the MIT License.
+
+### Notes
+
+- 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.1.2...HEAD
+[0.1.2]: https://github.com/yaniswav/TopicForge/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/yaniswav/TopicForge/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/yaniswav/TopicForge/releases/tag/v0.1.0

{topicforge-0.1.0 → topicforge-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: topicforge
-Version: 0.1.0
+Version: 0.1.2
 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
@@ -47,23 +47,25 @@ Description-Content-Type: text/markdown
 
 # TopicForge
 
-> Stop asking Claude to invent topic names. TopicForge is the MCP server that grounds AI agents in your real ROS2 stack - or a faithful mock when you have no robot at hand.
+> **The safety-first read-only MCP for ROS2 robotics.** TopicForge lets AI agents inspect your ROS2 graph and bag files without ever publishing back to the bus — so your safety officer doesn't flinch when you wire Claude into your robot stack.
 
-TopicForge is a production-minded MCP (Model Context Protocol) server that lets AI agents - such as Claude - inspect ROS2 topics and analyze ROS bag files through a clean, structured tool interface. It is designed for robotics developers, ML/CV engineers working with robot data, and teams that want their AI tooling to *understand* their robotics stack instead of guessing at it.
+TopicForge is a production-minded MCP (Model Context Protocol) server that lets AI agents — such as Claude — inspect ROS2 topics and analyze ROS bag files through a clean, structured tool interface. It is read-only by **architecture**, not by configuration: there is no write path to misconfigure, no permission system to audit, no liability conversation to have. The MCP client can see the robot stack; it cannot touch it.
+
+This stance matters because the ROS-MCP space is no longer empty — general-purpose ROS-MCP servers exist that let an LLM publish topics, call services, and command robots. That shape is fine for demos; it is untenable for production fleets, defense systems, automotive AUTOSAR Adaptive surfaces, or anything safety-certified. TopicForge is the read-only alternative for those audiences, plus the robotics developers, ML/CV engineers, and teams that want their AI tooling to *understand* their robotics stack without commanding it.
 
 ## Why it exists
 
-LLM agents are good at reasoning over text, but ROS2 introspection lives in a CLI + DDS world they cannot directly reach. Without grounding, an LLM will hallucinate topic names, message types, and bag contents. TopicForge bridges that gap with a small, well-typed set of MCP tools:
+LLM agents are good at reasoning over text, but ROS2 introspection lives in a CLI + DDS world they cannot directly reach. Without grounding, an LLM will hallucinate topic names, message types, and bag contents. TopicForge bridges that gap with a small, well-typed set of MCP tools — all read-only, all returning frozen Pydantic schemas that a downstream agent can parse without ambiguity:
 
 | Tool              | Purpose                                                |
 | ----------------- | ------------------------------------------------------ |
 | `health_check`    | Environment & mode introspection                       |
 | `list_topics`     | Discover the ROS graph                                 |
 | `get_topic_info`  | Structured info for a single topic                     |
-| `sample_messages` | Peek recent messages on a topic                        |
+| `sample_messages` | Peek recent messages on a topic (publish-time timestamps for `Header`-stamped types) |
 | `analyze_bag`     | Summarize a `.mcap` / `.db3` / `.bag` recording        |
 
-Outputs are structured, JSON-serializable, and stable across runtime modes - they look the same whether the server is talking to a real robot or to its built-in mock fixtures.
+Outputs are structured, JSON-serializable, and stable across runtime modes - they look the same whether the server is talking to a real robot or to its built-in mock fixtures. Every response carries a `mode_effective` field (`"live"` or `"mock"`) so a downstream LLM can tell a real graph from the demo fixtures without re-reading `health_check`.
 
 ## 30-second demo without ROS2
 
@@ -229,9 +231,54 @@ make check    # both, plus tests (CI bundle)
 | `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 usage telemetry. See [Telemetry](#telemetry).    |
 
 See [`.env.example`](.env.example).
 
+## Telemetry
+
+TopicForge ships an **opt-in, anonymous, minimal** telemetry hook. It is **off by default** and the OFF code path performs **zero network calls** — pinned by a unit test (`tests/test_telemetry.py::test_build_app_off_makes_no_transport_calls`).
+
+### How to opt in
+
+```bash
+TOPICFORGE_TELEMETRY=on python -m topicforge
+# Windows PowerShell: $env:TOPICFORGE_TELEMETRY="on"; python -m topicforge
+```
+
+Accepted on-values: `on`, `1`, `true`, `yes`, `enabled` (case-insensitive). Anything else — including unset — keeps telemetry off.
+
+### How to opt out
+
+Unset the variable, set it to `off`, or just don't touch it. Opt-out is the default.
+
+### Exactly what is sent
+
+When telemetry is on, each MCP tool call emits a single event with **only** these six fields:
+
+| Field             | Example          | Notes                                                                  |
+| ----------------- | ---------------- | ---------------------------------------------------------------------- |
+| `tool_name`       | `"list_topics"`  | One of the five MVP tools — never argument values.                     |
+| `latency_ms`      | `12.34`          | Wall-clock duration of the handler, rounded to 2 decimals.             |
+| `mode`            | `"mock"`         | Effective runtime mode: `mock` or `live`.                              |
+| `version`         | `"0.1.2"`        | TopicForge server version.                                             |
+| `session_id`      | `"a1b2c3…"`      | Random UUID generated per process. Never persisted, never re-used.     |
+| `success`         | `true`           | Whether the handler returned (true) or raised (false).                 |
+
+### What is **never** sent
+
+- Topic names, message types, message payloads
+- Bag file paths or bag contents
+- Hostnames, usernames, IP addresses, ROS distro, environment variables
+- Stack traces, error messages, or any free-form text
+- Any persistent identifier — `session_id` is regenerated on every server start
+
+The payload shape is fenced by `tests/test_telemetry.py::test_payload_contains_only_whitelisted_keys`. Adding a field there requires a matching change in this section.
+
+### Where the code lives
+
+The complete telemetry implementation is in [`src/topicforge/telemetry/`](src/topicforge/telemetry/) — read it in under five minutes. The default transport is a structured log line (no HTTP endpoint yet); a future S3-backed endpoint will plug into the same `Transport` callable without touching tool handlers.
+
 ## Security model
 
 TopicForge is designed for **local trust**: it runs as a subprocess of your MCP client (Claude Desktop, Claude Code) on a machine you control, and inspects your own ROS2 graph or your own bag files. It is not hardened for adversarial inputs.
@@ -239,13 +286,13 @@ TopicForge is designed for **local trust**: it runs as a subprocess of your MCP
 - `TOPICFORGE_ROS2_BIN` accepts an arbitrary path - if you point it at a malicious binary, TopicForge will execute it. Treat the variable the way you treat `PATH`.
 - `analyze_bag` opens whatever path the MCP client passes (no workspace isolation, no symlink restriction). The threat model assumes the client is your trusted agent acting on your behalf.
 - All `ros2` CLI invocations use `subprocess.run` with an argument list - never `shell=True`. Topic names are validated against a strict allowlist (`^/[A-Za-z0-9_/]+$`) before being passed to the CLI.
-- No outbound network calls. No telemetry in v0.1.0 (opt-in usage metrics are on the Phase 1 roadmap).
+- No outbound network calls by default. Since v0.1.1, opt-in anonymous usage telemetry is available behind `TOPICFORGE_TELEMETRY=on` — see [Telemetry](#telemetry) for the exact payload and opt-out instructions. When off (the default), the OFF code path is a verified no-op.
 
 Before exposing TopicForge to *untrusted* MCP clients (hosted endpoints, shared environments), add path isolation and revisit the `TOPICFORGE_ROS2_BIN` policy.
 
 ## MVP limitations
 
-- `sample_messages` in live mode uses `ros2 topic echo --once` with a short timeout; topics with no current publisher will return an empty sample.
+- `sample_messages` in live mode uses `ros2 topic echo --csv --once` with a short timeout; topics with no current publisher will return an empty sample. `MessageSample.timestamp_ns` is the message's `header.stamp` (publish time) for `Header`-stamped messages and `0` for headerless types (`std_msgs/String`, `geometry_msgs/Twist`, …); surfacing the rmw receive timestamp for arbitrary types waits on the future `rclpy`-backed adapter.
 - `sample_messages` silently clamps `count` to 50 to keep tool output bounded; requests for more than 50 messages return at most 50 (the `SampleResult.count` field reflects what was actually returned).
 - `analyze_bag` in live mode shells out to `ros2 bag info` and parses its text output. Deep anomaly detection is mock-only for now.
 - No streaming / push subscriptions in the MVP. Tools are strictly request/response.

{topicforge-0.1.0 → topicforge-0.1.2}/README.md

@@ -1,22 +1,24 @@
 # TopicForge
 
-> Stop asking Claude to invent topic names. TopicForge is the MCP server that grounds AI agents in your real ROS2 stack - or a faithful mock when you have no robot at hand.
+> **The safety-first read-only MCP for ROS2 robotics.** TopicForge lets AI agents inspect your ROS2 graph and bag files without ever publishing back to the bus — so your safety officer doesn't flinch when you wire Claude into your robot stack.
 
-TopicForge is a production-minded MCP (Model Context Protocol) server that lets AI agents - such as Claude - inspect ROS2 topics and analyze ROS bag files through a clean, structured tool interface. It is designed for robotics developers, ML/CV engineers working with robot data, and teams that want their AI tooling to *understand* their robotics stack instead of guessing at it.
+TopicForge is a production-minded MCP (Model Context Protocol) server that lets AI agents — such as Claude — inspect ROS2 topics and analyze ROS bag files through a clean, structured tool interface. It is read-only by **architecture**, not by configuration: there is no write path to misconfigure, no permission system to audit, no liability conversation to have. The MCP client can see the robot stack; it cannot touch it.
+
+This stance matters because the ROS-MCP space is no longer empty — general-purpose ROS-MCP servers exist that let an LLM publish topics, call services, and command robots. That shape is fine for demos; it is untenable for production fleets, defense systems, automotive AUTOSAR Adaptive surfaces, or anything safety-certified. TopicForge is the read-only alternative for those audiences, plus the robotics developers, ML/CV engineers, and teams that want their AI tooling to *understand* their robotics stack without commanding it.
 
 ## Why it exists
 
-LLM agents are good at reasoning over text, but ROS2 introspection lives in a CLI + DDS world they cannot directly reach. Without grounding, an LLM will hallucinate topic names, message types, and bag contents. TopicForge bridges that gap with a small, well-typed set of MCP tools:
+LLM agents are good at reasoning over text, but ROS2 introspection lives in a CLI + DDS world they cannot directly reach. Without grounding, an LLM will hallucinate topic names, message types, and bag contents. TopicForge bridges that gap with a small, well-typed set of MCP tools — all read-only, all returning frozen Pydantic schemas that a downstream agent can parse without ambiguity:
 
 | Tool              | Purpose                                                |
 | ----------------- | ------------------------------------------------------ |
 | `health_check`    | Environment & mode introspection                       |
 | `list_topics`     | Discover the ROS graph                                 |
 | `get_topic_info`  | Structured info for a single topic                     |
-| `sample_messages` | Peek recent messages on a topic                        |
+| `sample_messages` | Peek recent messages on a topic (publish-time timestamps for `Header`-stamped types) |
 | `analyze_bag`     | Summarize a `.mcap` / `.db3` / `.bag` recording        |
 
-Outputs are structured, JSON-serializable, and stable across runtime modes - they look the same whether the server is talking to a real robot or to its built-in mock fixtures.
+Outputs are structured, JSON-serializable, and stable across runtime modes - they look the same whether the server is talking to a real robot or to its built-in mock fixtures. Every response carries a `mode_effective` field (`"live"` or `"mock"`) so a downstream LLM can tell a real graph from the demo fixtures without re-reading `health_check`.
 
 ## 30-second demo without ROS2
 
@@ -182,9 +184,54 @@ make check    # both, plus tests (CI bundle)
 | `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 usage telemetry. See [Telemetry](#telemetry).    |
 
 See [`.env.example`](.env.example).
 
+## Telemetry
+
+TopicForge ships an **opt-in, anonymous, minimal** telemetry hook. It is **off by default** and the OFF code path performs **zero network calls** — pinned by a unit test (`tests/test_telemetry.py::test_build_app_off_makes_no_transport_calls`).
+
+### How to opt in
+
+```bash
+TOPICFORGE_TELEMETRY=on python -m topicforge
+# Windows PowerShell: $env:TOPICFORGE_TELEMETRY="on"; python -m topicforge
+```
+
+Accepted on-values: `on`, `1`, `true`, `yes`, `enabled` (case-insensitive). Anything else — including unset — keeps telemetry off.
+
+### How to opt out
+
+Unset the variable, set it to `off`, or just don't touch it. Opt-out is the default.
+
+### Exactly what is sent
+
+When telemetry is on, each MCP tool call emits a single event with **only** these six fields:
+
+| Field             | Example          | Notes                                                                  |
+| ----------------- | ---------------- | ---------------------------------------------------------------------- |
+| `tool_name`       | `"list_topics"`  | One of the five MVP tools — never argument values.                     |
+| `latency_ms`      | `12.34`          | Wall-clock duration of the handler, rounded to 2 decimals.             |
+| `mode`            | `"mock"`         | Effective runtime mode: `mock` or `live`.                              |
+| `version`         | `"0.1.2"`        | TopicForge server version.                                             |
+| `session_id`      | `"a1b2c3…"`      | Random UUID generated per process. Never persisted, never re-used.     |
+| `success`         | `true`           | Whether the handler returned (true) or raised (false).                 |
+
+### What is **never** sent
+
+- Topic names, message types, message payloads
+- Bag file paths or bag contents
+- Hostnames, usernames, IP addresses, ROS distro, environment variables
+- Stack traces, error messages, or any free-form text
+- Any persistent identifier — `session_id` is regenerated on every server start
+
+The payload shape is fenced by `tests/test_telemetry.py::test_payload_contains_only_whitelisted_keys`. Adding a field there requires a matching change in this section.
+
+### Where the code lives
+
+The complete telemetry implementation is in [`src/topicforge/telemetry/`](src/topicforge/telemetry/) — read it in under five minutes. The default transport is a structured log line (no HTTP endpoint yet); a future S3-backed endpoint will plug into the same `Transport` callable without touching tool handlers.
+
 ## Security model
 
 TopicForge is designed for **local trust**: it runs as a subprocess of your MCP client (Claude Desktop, Claude Code) on a machine you control, and inspects your own ROS2 graph or your own bag files. It is not hardened for adversarial inputs.
@@ -192,13 +239,13 @@ TopicForge is designed for **local trust**: it runs as a subprocess of your MCP
 - `TOPICFORGE_ROS2_BIN` accepts an arbitrary path - if you point it at a malicious binary, TopicForge will execute it. Treat the variable the way you treat `PATH`.
 - `analyze_bag` opens whatever path the MCP client passes (no workspace isolation, no symlink restriction). The threat model assumes the client is your trusted agent acting on your behalf.
 - All `ros2` CLI invocations use `subprocess.run` with an argument list - never `shell=True`. Topic names are validated against a strict allowlist (`^/[A-Za-z0-9_/]+$`) before being passed to the CLI.
-- No outbound network calls. No telemetry in v0.1.0 (opt-in usage metrics are on the Phase 1 roadmap).
+- No outbound network calls by default. Since v0.1.1, opt-in anonymous usage telemetry is available behind `TOPICFORGE_TELEMETRY=on` — see [Telemetry](#telemetry) for the exact payload and opt-out instructions. When off (the default), the OFF code path is a verified no-op.
 
 Before exposing TopicForge to *untrusted* MCP clients (hosted endpoints, shared environments), add path isolation and revisit the `TOPICFORGE_ROS2_BIN` policy.
 
 ## MVP limitations
 
-- `sample_messages` in live mode uses `ros2 topic echo --once` with a short timeout; topics with no current publisher will return an empty sample.
+- `sample_messages` in live mode uses `ros2 topic echo --csv --once` with a short timeout; topics with no current publisher will return an empty sample. `MessageSample.timestamp_ns` is the message's `header.stamp` (publish time) for `Header`-stamped messages and `0` for headerless types (`std_msgs/String`, `geometry_msgs/Twist`, …); surfacing the rmw receive timestamp for arbitrary types waits on the future `rclpy`-backed adapter.
 - `sample_messages` silently clamps `count` to 50 to keep tool output bounded; requests for more than 50 messages return at most 50 (the `SampleResult.count` field reflects what was actually returned).
 - `analyze_bag` in live mode shells out to `ros2 bag info` and parses its text output. Deep anomaly detection is mock-only for now.
 - No streaming / push subscriptions in the MVP. Tools are strictly request/response.