convertible-cli 0.6.0__tar.gz → 0.7.0__tar.gz

{convertible_cli-0.6.0 → convertible_cli-0.7.0}/.markdownlint-cli2.yaml

@@ -19,6 +19,9 @@ ignores:
   - ".local/**"
   - ".afi/**"
   - ".teken/**"
+  # The virtualenv — installed packages (e.g. the [otel] extra's opentelemetry,
+  # idna) ship their own non-conformant Markdown; never lint dependencies.
+  - ".venv/**"
   # Vendored skills are cited verbatim from guildmaster — do not reformat them.
   - ".claude/skills/**"
   # devague artifacts (frames, exported specs/plans) are generated verbatim from

{convertible_cli-0.6.0 → convertible_cli-0.7.0}/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/). This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.0] - 2026-05-28
+
+### Added
+
+- GPS: opt-in OpenTelemetry traces + metrics for a drive (issue #22). Spans (`convertible.drive` -> `convertible.tool.*` -> `convertible.handoff`) and metrics (steps, tokens, tool latency, tool calls, hook denials, drive duration) emit over OTLP from the loop + the shared drive path, so every engine is instrumented identically (all-engines rule).
+- `convertible telemetry status` / `overview` introspection noun, plus an explain catalog entry.
+- `TelemetryConfig` resolved from `CONVERTIBLE_OTEL_*` / standard `OTEL_*` env vars (`OTEL_SDK_DISABLED` honored as a kill-switch).
+- Optional `[otel]` extra (opentelemetry SDK + OTLP/HTTP exporter); install with `pip install "convertible-cli[otel]"`.
+
+### Changed
+
+- `loop.run()` and `execute_drive` accept/own telemetry, defaulting to a no-op resolved from the environment (mirrors the hooks pattern). Off by default it is a strict no-op: no spans, no SDK import, `TaskResult` unchanged.
+
 ## [0.6.0] - 2026-05-28
 
 ### Added

{convertible_cli-0.6.0 → convertible_cli-0.7.0}/CLAUDE.md

@@ -21,6 +21,11 @@ The car metaphor *is* the architecture:
 - **Wheels** — engines are plugins discovered via the `convertible.engines`
   Python entry-point group (`convertible/registry.py`).
 - **Dashboard** — the JSON result artifact + step trace (`convertible/artifact.py`).
+- **GPS** — opt-in OpenTelemetry traces + metrics (`convertible/telemetry/`).
+  Instrumented in the loop + the shared drive path so every engine emits it
+  (all-engines rule), exactly like hooks. Off by default; the OpenTelemetry SDK
+  is an optional `[otel]` extra, imported lazily, so the base install stays
+  dep-free. Surfaced via the `telemetry` introspection noun.
 - **Handoff** — branch/commit/push + `gh pr create`, gated for offline/CI
   (`convertible/handoff.py`).
 - **Command templates** — named, parameterized task recipes in
@@ -53,8 +58,9 @@ The buildable spec and plan this implementation converged from live in
 
 In scope: the chassis, the entry-point wheel contract, exactly two engines
 (`mock`, `vllm-openai`), the git/PR handoff, command templates, lifecycle
-hooks, the foreground interactive palette, and layered per-model AGENTS/skills
-config (`convertible/layers.py`).
+hooks, the foreground interactive palette, layered per-model AGENTS/skills
+config (`convertible/layers.py`), and GPS — opt-in OpenTelemetry traces +
+metrics (`convertible/telemetry/`), with the SDK as an optional `[otel]` extra.
 
 **Out of scope for v0** — do not add without re-speccing: a multi-engine
 router/policy "gearbox", an execution sandbox, a daemon/server mode,
@@ -81,7 +87,15 @@ test (`tests/test_e2e_mock.py`) is the guard.
 - **No runtime dependencies.** `pyproject.toml` keeps `dependencies = []`; the
   vLLM driver speaks the OpenAI wire format over stdlib `urllib`; commands and
   hooks use only stdlib (`json`, `subprocess`, `pathlib`). Don't add a runtime
-  dep without a strong reason — dev-only deps go in the `dev` group.
+  dep without a strong reason — dev-only deps go in the `dev` group. The one
+  documented exception is **GPS**: the OpenTelemetry SDK ships as an optional
+  `[project.optional-dependencies] otel` extra, never a base dependency. It is
+  imported **lazily** inside `convertible/telemetry/_otel.py` (only when
+  telemetry is enabled), so `dependencies = []` and the zero-deps guard
+  (`tests/test_zero_deps.py`) still hold — the guard imports `convertible.loop`
+  / `convertible.telemetry` / `convertible.cli` and asserts no third-party leak
+  even with the extra installed. Keep the SDK confined to `_otel.py`; never
+  import `opentelemetry` from any other convertible module.
 - **Agent-first CLI.** New verbs are `convertible/cli/_commands/` modules with a
   `register(sub)`, wired in `convertible/cli/__init__.py`. Results to stdout,
   diagnostics/errors to stderr (never mixed); every command supports `--json`;
@@ -98,6 +112,11 @@ test (`tests/test_e2e_mock.py`) is the guard.
   hook firing — new engine wheels inherit the full lifecycle layer automatically
   and must not duplicate it. The all-engines rule applies: a hook config that
   fires on `mock` must fire identically on `vllm-openai`.
+- **Telemetry belongs to the chassis too.** `convertible/loop.py` (per tool
+  call) and the shared `execute_drive` path (root + handoff spans) own all
+  telemetry; no engine module touches the `telemetry` package. Off by default it
+  is a strict no-op (no spans, no SDK import, `TaskResult` unchanged) — protect
+  that so the e2e shape test and zero-deps guard keep passing.
 - **Repo-shipped hooks run by default (trusted-operator-env model D2).** There
   is no `--no-hooks` flag today. A per-repo trust gate is a tracked follow-up.
   Document this gap clearly; never document a non-existent flag.
@@ -118,6 +137,13 @@ uv run convertible hooks list --repo .             # list configured hooks
 uv run convertible hooks overview                  # surface description
 uv run convertible session --repo . --engine mock  # interactive palette
 
+# GPS / telemetry (opt-in; needs the [otel] extra):
+uv run convertible telemetry status                # resolved telemetry config
+uv run convertible telemetry overview              # surface description
+uv sync --extra otel                               # install the OpenTelemetry SDK
+CONVERTIBLE_OTEL_ENABLED=1 OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
+  uv run convertible drive "<task>" --repo . --engine mock --no-pr  # emits a trace
+
 # Lint + gates CI enforces:
 uv run black --check convertible tests
 uv run isort --check-only convertible tests

convertible_cli-0.6.0/README.md → convertible_cli-0.7.0/PKG-INFO

@@ -1,3 +1,25 @@
+Metadata-Version: 2.4
+Name: convertible-cli
+Version: 0.7.0
+Summary: Convertible CLI is a swappable coder-agent harness that turns different models into repo workers behind one shared task contract.
+Project-URL: Homepage, https://github.com/agentculture/convertible
+Project-URL: Issues, https://github.com/agentculture/convertible/issues
+Author: AgentCulture
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Requires-Python: >=3.12
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.25; extra == 'otel'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.25; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.25; extra == 'otel'
+Requires-Dist: opentelemetry-semantic-conventions>=0.46b0; extra == 'otel'
+Description-Content-Type: text/markdown
+
 # convertible
 
 ```text
@@ -42,6 +64,7 @@ which one ran.
 | **Tool-loop** | the bounded agentic loop the engine drives the repo through |
 | **Wheels** | replaceable engine plugins, discovered via Python entry points |
 | **Dashboard** | the JSON result artifact + step trace each run writes |
+| **GPS** | opt-in OpenTelemetry traces + metrics (`convertible/telemetry/`) |
 | **Garage** | `convertible wheels list` — the engines installed in this env |
 
 ## What ships in v0
@@ -313,6 +336,43 @@ The session loops until the user enters `q`, `quit`, or an empty line. Any
 driver flags accepted by `drive` (`--engine`, `--no-pr`, `--base-url`, etc.)
 are also accepted by `session`.
 
+## GPS: OpenTelemetry observability
+
+A drive can emit **OpenTelemetry traces + metrics** so it's observable against an
+OTLP collector — not just the per-run JSON artifact. Telemetry lives in the
+chassis (the loop + the shared drive path), so **every engine** emits it
+identically, exactly like lifecycle hooks.
+
+It is **off by default** and a strict no-op when off (no spans, no SDK import,
+the result artifact unchanged). The OpenTelemetry SDK is an **optional extra** —
+the base install keeps zero runtime dependencies:
+
+```bash
+pip install 'convertible-cli[otel]'                 # or: uv sync --extra otel
+export CONVERTIBLE_OTEL_ENABLED=1
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318   # OTLP/HTTP collector
+uv run convertible drive "<task>" --repo . --engine mock --no-pr
+#   -> stderr prints "trace: <id>"; the collector receives the spans + metrics
+```
+
+Requested without the extra installed, convertible degrades to a no-op with a
+one-line stderr notice — it never fails the drive.
+
+**Signals.** Spans: `convertible.drive` (root) → `convertible.tool.*` (per tool
+call) → `convertible.handoff`. Metrics: `convertible.steps`, `convertible.tokens`,
+`convertible.tool.latency`, `convertible.tool.calls`, `convertible.hook.denials`,
+`convertible.drive.duration`.
+
+**Config** (precedence: explicit > `CONVERTIBLE_OTEL_*` > standard `OTEL_*` >
+default): `CONVERTIBLE_OTEL_ENABLED`, `CONVERTIBLE_OTEL_ENDPOINT` /
+`OTEL_EXPORTER_OTLP_ENDPOINT`, `CONVERTIBLE_OTEL_SERVICE_NAME` /
+`OTEL_SERVICE_NAME`. `OTEL_SDK_DISABLED=true` is honored as a kill-switch.
+
+```bash
+uv run convertible telemetry status      # resolved config + whether the SDK is installed
+uv run convertible telemetry overview    # describe the surface
+```
+
 ## Per-model instructions & skills
 
 Convertible composes a model-specific **system prompt** for every drive from two
@@ -394,6 +454,8 @@ rely on a non-existent flag.
 | `agents overview` | Describe the agents surface. |
 | `skills list` | List resolved skill docs for a model. |
 | `skills overview` | Describe the skills surface. |
+| `telemetry status` | Show the resolved GPS / OpenTelemetry config + whether the SDK is installed. |
+| `telemetry overview` | Describe the telemetry surface. |
 | `session` | Open a foreground interactive palette. |
 | `wheels list` | List discovered engine wheels (the garage). |
 | `whoami` | Report this agent's nick, version, backend, and model. |

convertible_cli-0.6.0/PKG-INFO → convertible_cli-0.7.0/README.md

@@ -1,20 +1,3 @@
-Metadata-Version: 2.4
-Name: convertible-cli
-Version: 0.6.0
-Summary: Convertible CLI is a swappable coder-agent harness that turns different models into repo workers behind one shared task contract.
-Project-URL: Homepage, https://github.com/agentculture/convertible
-Project-URL: Issues, https://github.com/agentculture/convertible/issues
-Author: AgentCulture
-License-Expression: MIT
-License-File: LICENSE
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Topic :: Software Development
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-
 # convertible
 
 ```text
@@ -59,6 +42,7 @@ which one ran.
 | **Tool-loop** | the bounded agentic loop the engine drives the repo through |
 | **Wheels** | replaceable engine plugins, discovered via Python entry points |
 | **Dashboard** | the JSON result artifact + step trace each run writes |
+| **GPS** | opt-in OpenTelemetry traces + metrics (`convertible/telemetry/`) |
 | **Garage** | `convertible wheels list` — the engines installed in this env |
 
 ## What ships in v0
@@ -330,6 +314,43 @@ The session loops until the user enters `q`, `quit`, or an empty line. Any
 driver flags accepted by `drive` (`--engine`, `--no-pr`, `--base-url`, etc.)
 are also accepted by `session`.
 
+## GPS: OpenTelemetry observability
+
+A drive can emit **OpenTelemetry traces + metrics** so it's observable against an
+OTLP collector — not just the per-run JSON artifact. Telemetry lives in the
+chassis (the loop + the shared drive path), so **every engine** emits it
+identically, exactly like lifecycle hooks.
+
+It is **off by default** and a strict no-op when off (no spans, no SDK import,
+the result artifact unchanged). The OpenTelemetry SDK is an **optional extra** —
+the base install keeps zero runtime dependencies:
+
+```bash
+pip install 'convertible-cli[otel]'                 # or: uv sync --extra otel
+export CONVERTIBLE_OTEL_ENABLED=1
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318   # OTLP/HTTP collector
+uv run convertible drive "<task>" --repo . --engine mock --no-pr
+#   -> stderr prints "trace: <id>"; the collector receives the spans + metrics
+```
+
+Requested without the extra installed, convertible degrades to a no-op with a
+one-line stderr notice — it never fails the drive.
+
+**Signals.** Spans: `convertible.drive` (root) → `convertible.tool.*` (per tool
+call) → `convertible.handoff`. Metrics: `convertible.steps`, `convertible.tokens`,
+`convertible.tool.latency`, `convertible.tool.calls`, `convertible.hook.denials`,
+`convertible.drive.duration`.
+
+**Config** (precedence: explicit > `CONVERTIBLE_OTEL_*` > standard `OTEL_*` >
+default): `CONVERTIBLE_OTEL_ENABLED`, `CONVERTIBLE_OTEL_ENDPOINT` /
+`OTEL_EXPORTER_OTLP_ENDPOINT`, `CONVERTIBLE_OTEL_SERVICE_NAME` /
+`OTEL_SERVICE_NAME`. `OTEL_SDK_DISABLED=true` is honored as a kill-switch.
+
+```bash
+uv run convertible telemetry status      # resolved config + whether the SDK is installed
+uv run convertible telemetry overview    # describe the surface
+```
+
 ## Per-model instructions & skills
 
 Convertible composes a model-specific **system prompt** for every drive from two
@@ -411,6 +432,8 @@ rely on a non-existent flag.
 | `agents overview` | Describe the agents surface. |
 | `skills list` | List resolved skill docs for a model. |
 | `skills overview` | Describe the skills surface. |
+| `telemetry status` | Show the resolved GPS / OpenTelemetry config + whether the SDK is installed. |
+| `telemetry overview` | Describe the telemetry surface. |
 | `session` | Open a foreground interactive palette. |
 | `wheels list` | List discovered engine wheels (the garage). |
 | `whoami` | Report this agent's nick, version, backend, and model. |

{convertible_cli-0.6.0 → convertible_cli-0.7.0}/convertible/cli/__init__.py

@@ -84,6 +84,7 @@ def _build_parser() -> argparse.ArgumentParser:
     from convertible.cli._commands import overview as _overview_cmd
     from convertible.cli._commands import session as _session_cmd
     from convertible.cli._commands import skills as _skills_group
+    from convertible.cli._commands import telemetry as _telemetry_group
     from convertible.cli._commands import wheels as _wheels_group
     from convertible.cli._commands import whoami as _whoami_cmd
 
@@ -115,6 +116,8 @@ def _build_parser() -> argparse.ArgumentParser:
     # Layered per-model config: AGENTS instructions + skills.
     _agents_group.register(sub)
     _skills_group.register(sub)
+    # GPS: OpenTelemetry traces + metrics (opt-in, optional [otel] extra).
+    _telemetry_group.register(sub)
     # Interactive foreground palette (c28/R8).
     _session_cmd.register(sub)
 

{convertible_cli-0.6.0 → convertible_cli-0.7.0}/convertible/cli/_commands/drive.py

@@ -33,6 +33,7 @@ from convertible.commands import CommandError, expand_command
 from convertible.config import EngineConfig
 from convertible.contract import OK, Task, TaskResult
 from convertible.handoff import HandoffError, handoff
+from convertible.telemetry import load_telemetry
 
 
 def _render(result: TaskResult, engine: str, artifact_path: Path) -> str:
@@ -103,39 +104,69 @@ def execute_drive(
             EXIT_USER_ERROR, str(exc), "list engines with: convertible wheels list"
         ) from exc
 
+    # GPS: the root span wraps engine.drive() + handoff() + the artifact write, so
+    # the loop's tool spans nest under it. A no-op unless telemetry is enabled.
+    # The same shared path serves `drive` and `session`, so both are instrumented.
+    telemetry = load_telemetry()
     try:
-        result = engine.drive(task, config)
-    except Exception as exc:  # noqa: BLE001 - any failure still writes an artifact (h5)
-        result = failed_result(task.id, f"{type(exc).__name__}: {exc}")
-        result.command = command_name
-        write(result, artifact_dir(repo))
-        raise CliError(
-            EXIT_ENV_ERROR,
-            f"engine '{engine_name}' failed: {exc}",
-            "check the engine config / vLLM server; a result artifact was still written",
-        ) from exc
+        with telemetry.drive_span(
+            task_id=task.id,
+            engine=engine_name,
+            model=config.model,
+            max_steps=config.max_steps,
+        ) as drive_span:
+            trace_id = telemetry.trace_id_hex()
+            if trace_id:
+                emit_diagnostic(f"trace: {trace_id}")
 
-    if result.status == OK:
-        try:
-            outcome = handoff(
-                repo,
-                task.id,
-                instruction=task.instruction,
-                open_pr=open_pr,
-                base_branch=base,
+            try:
+                result = engine.drive(task, config)
+            except Exception as exc:  # noqa: BLE001 - any failure still writes an artifact (h5)
+                result = failed_result(task.id, f"{type(exc).__name__}: {exc}")
+                result.command = command_name
+                drive_span.set(status=result.status)
+                write(result, artifact_dir(repo))
+                raise CliError(
+                    EXIT_ENV_ERROR,
+                    f"engine '{engine_name}' failed: {exc}",
+                    "check the engine config / vLLM server; a result artifact was still written",
+                ) from exc
+
+            if result.status == OK:
+                with telemetry.handoff_span() as handoff_span:
+                    try:
+                        outcome = handoff(
+                            repo,
+                            task.id,
+                            instruction=task.instruction,
+                            open_pr=open_pr,
+                            base_branch=base,
+                        )
+                        result.branch = outcome.branch
+                        result.pr_url = outcome.pr_url
+                        if not result.changed_files:
+                            result.changed_files = outcome.changed_files
+                        handoff_span.set(
+                            branch=outcome.branch,
+                            committed=outcome.committed,
+                            pushed=outcome.pushed,
+                            pr_url=outcome.pr_url,
+                        )
+                        if outcome.note:
+                            emit_diagnostic(f"handoff: {outcome.note}")
+                    except HandoffError as exc:
+                        emit_diagnostic(f"handoff skipped: {exc}")
+
+            drive_span.set(
+                status=result.status,
+                step_count=len(result.steps),
+                pr_url=result.pr_url,
             )
-            result.branch = outcome.branch
-            result.pr_url = outcome.pr_url
-            if not result.changed_files:
-                result.changed_files = outcome.changed_files
-            if outcome.note:
-                emit_diagnostic(f"handoff: {outcome.note}")
-        except HandoffError as exc:
-            emit_diagnostic(f"handoff skipped: {exc}")
-
-    result.command = command_name
-    artifact_path = write(result, artifact_dir(repo))
-    return result, artifact_path
+            result.command = command_name
+            artifact_path = write(result, artifact_dir(repo))
+            return result, artifact_path
+    finally:
+        telemetry.flush()
 
 
 def cmd_drive(args: argparse.Namespace) -> int:

convertible_cli-0.7.0/convertible/cli/_commands/telemetry.py

@@ -0,0 +1,115 @@
+"""``convertible telemetry`` — inspect the GPS (OpenTelemetry) configuration.
+
+``telemetry status`` reports the resolved :class:`~convertible.telemetry.TelemetryConfig`
+(enabled flag, OTLP endpoint/protocol, service name, traces/metrics toggles) and
+whether the optional ``[otel]`` extra is installed; ``telemetry overview``
+describes the noun (satisfying the agent-first rubric: any noun with
+action-verbs must also expose ``overview``).
+
+This module imports only the **stdlib-clean** telemetry facade — never the SDK —
+so ``convertible telemetry`` works (reporting ``sdk_installed: false``) even when
+the extra is not installed.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from convertible.cli._commands.overview import emit_overview
+from convertible.cli._output import emit_result
+from convertible.telemetry import TelemetryConfig, sdk_available
+
+
+def _telemetry_sections() -> list[dict[str, object]]:
+    return [
+        {
+            "title": "What it does",
+            "items": [
+                "GPS for a drive: OpenTelemetry traces + metrics over OTLP",
+                "Off by default; opt in with CONVERTIBLE_OTEL_ENABLED=1",
+                "Needs the optional extra: pip install 'convertible-cli[otel]'",
+                "Instrumented in the loop + shared drive path, so every engine emits it",
+            ],
+        },
+        {
+            "title": "Signals",
+            "items": [
+                "spans: convertible.drive -> convertible.tool.* (+ convertible.handoff)",
+                "metrics: convertible.steps, convertible.tokens, convertible.tool.latency,"
+                " convertible.tool.calls, convertible.hook.denials, convertible.drive.duration",
+            ],
+        },
+        {
+            "title": "Configuration (precedence: explicit > CONVERTIBLE_OTEL_* > OTEL_* > default)",
+            "items": [
+                "CONVERTIBLE_OTEL_ENABLED — turn telemetry on (default: off)",
+                "CONVERTIBLE_OTEL_ENDPOINT / OTEL_EXPORTER_OTLP_ENDPOINT — collector URL",
+                "CONVERTIBLE_OTEL_SERVICE_NAME / OTEL_SERVICE_NAME — resource service.name",
+                "OTEL_SDK_DISABLED=true — standard kill-switch, forces telemetry off",
+            ],
+        },
+        {
+            "title": "Verbs",
+            "items": [
+                "telemetry status [--json] — show the resolved telemetry config",
+                "telemetry overview — describe the telemetry surface (this command)",
+            ],
+        },
+    ]
+
+
+def cmd_telemetry_overview(args: argparse.Namespace) -> int:
+    emit_overview(
+        "convertible telemetry",
+        _telemetry_sections(),
+        json_mode=bool(getattr(args, "json", False)),
+    )
+    return 0
+
+
+def cmd_telemetry_status(args: argparse.Namespace) -> int:
+    json_mode = bool(getattr(args, "json", False))
+    cfg = TelemetryConfig.resolve()
+    installed = sdk_available()
+
+    if json_mode:
+        payload = cfg.to_dict()
+        payload["sdk_installed"] = installed
+        emit_result(payload, json_mode=True)
+        return 0
+
+    lines = [
+        f"enabled:        {cfg.enabled}",
+        f"sdk_installed:  {installed}",
+        f"service_name:   {cfg.service_name}",
+        f"otlp_endpoint:  {cfg.otlp_endpoint}",
+        f"otlp_protocol:  {cfg.otlp_protocol}",
+        f"traces_enabled: {cfg.traces_enabled}",
+        f"metrics_enabled:{cfg.metrics_enabled}",
+    ]
+    if cfg.enabled and not installed:
+        lines.append("note:           enabled but the [otel] extra is not installed (no-op)")
+    emit_result("\n".join(lines), json_mode=False)
+    return 0
+
+
+def _no_verb(args: argparse.Namespace) -> int:
+    return cmd_telemetry_overview(args)
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser(
+        "telemetry",
+        help="Inspect the GPS / OpenTelemetry config (see 'convertible telemetry overview').",
+    )
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=_no_verb, json=False)
+    noun_sub = p.add_subparsers(dest="telemetry_command", parser_class=type(p))
+
+    st = noun_sub.add_parser("status", help="Show the resolved telemetry configuration.")
+    st.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    st.set_defaults(func=cmd_telemetry_status)
+
+    ov = noun_sub.add_parser("overview", help="Describe the telemetry surface.")
+    ov.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    ov.set_defaults(func=cmd_telemetry_overview)

{convertible_cli-0.6.0 → convertible_cli-0.7.0}/convertible/explain/catalog.py

@@ -326,6 +326,56 @@ scope); invokable skills are a tracked follow-up.
 """
 
 
+_TELEMETRY = """\
+# convertible telemetry
+
+GPS for a drive: opt-in OpenTelemetry **traces + metrics** over OTLP. Telemetry
+belongs to the chassis — it is instrumented once in the loop and the shared drive
+path, so *every* engine emits identical signals (the all-engines rule), exactly
+like lifecycle hooks.
+
+Off by default. The OpenTelemetry SDK is an **optional extra** (the base install
+keeps zero runtime dependencies); enable it with the env var and install the
+extra:
+
+    pip install 'convertible-cli[otel]'
+    export CONVERTIBLE_OTEL_ENABLED=1
+    export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318   # OTLP/HTTP collector
+
+When requested without the extra installed, convertible degrades to a no-op with
+a one-line stderr notice — it never fails the drive.
+
+## Signals
+
+- spans: `convertible.drive` (root) -> `convertible.tool.*` (per tool call) plus
+  `convertible.handoff`.
+- metrics: `convertible.steps`, `convertible.tokens` (attr `kind`),
+  `convertible.tool.latency`, `convertible.tool.calls`, `convertible.hook.denials`,
+  `convertible.drive.duration` (attr `status`).
+
+## Configuration
+
+Precedence (highest first): explicit > `CONVERTIBLE_OTEL_*` > standard `OTEL_*` >
+default. `OTEL_SDK_DISABLED=true` is honored as a kill-switch.
+
+- `CONVERTIBLE_OTEL_ENABLED` — turn telemetry on (default: off).
+- `CONVERTIBLE_OTEL_ENDPOINT` / `OTEL_EXPORTER_OTLP_ENDPOINT` — collector URL.
+- `CONVERTIBLE_OTEL_SERVICE_NAME` / `OTEL_SERVICE_NAME` — resource `service.name`.
+- `CONVERTIBLE_OTEL_METRICS_ENABLED` — toggle metric emission (default: on).
+
+## Usage
+
+    convertible telemetry status
+    convertible telemetry status --json
+    convertible telemetry overview
+
+## See also
+
+- `convertible explain drive`
+- `convertible explain hooks`
+"""
+
+
 ENTRIES: dict[tuple[str, ...], str] = {
     (): _ROOT,
     ("convertible",): _ROOT,
@@ -353,4 +403,7 @@ ENTRIES: dict[tuple[str, ...], str] = {
     ("skills",): _SKILLS,
     ("skills", "list"): _SKILLS,
     ("skills", "overview"): _SKILLS,
+    ("telemetry",): _TELEMETRY,
+    ("telemetry", "status"): _TELEMETRY,
+    ("telemetry", "overview"): _TELEMETRY,
 }