@senad-d/observme 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -4,6 +4,9 @@
 
 ### Added
 
+- Added a packaged `observme-docs` Pi skill that routes natural-language ObservMe questions to focused user, operator, reference, example, and contributor documentation through Pi's normal skill discovery, without an ObservMe system-prompt hook.
+- Added a versioned `@senad-d/observme/integration` event-bus API and transport-agnostic child-runner example for parent-side spawn/wait/join telemetry and child process lineage propagation.
+- Added README tables cataloging available metrics, trace spans, and structured log events, including opt-in and reserved signals.
 - Expanded the Grafana suite with SLO Health, Trace Journey, Agent Node Graphs, and LLM Conversations dashboards, plus richer multi-agent, cost, latency, tool, model, log, and export-health views.
 - Added correlated, content-safe telemetry for tool results, agent runs, workflows, subagent lifecycle events, interactive Bash executions, and configuration failures.
 - Added W3C trace continuation for launcher-propagated parent contexts, with sanitized lineage validation and fail-safe span-link/log fallbacks.
@@ -12,6 +15,9 @@
 
 ### Changed
 
+- Moved the detailed technical reference into `docs/reference/` and updated package, documentation, examples, dashboards, tests, and skill routes to use the new location.
+- Made the packaged `observme-docs` skill resolve routed references from its installed package root instead of the caller's working directory or a repository checkout.
+- Reorganized documentation around `docs/README.md`, a categorized technical-reference index, and an example guide with explicit usage and safety notes.
 - Split Pi event handling into focused lifecycle, agent/turn, LLM, tool/Bash, and session modules while preserving the `registerHandlers()` facade.
 - Centralized telemetry conventions, content-capture policy, sensitive-value rejection, diagnostic sanitization, Grafana transport, `/obs` command plumbing, and trusted-project configuration bootstrap.
 - Improved all dashboards with emitted-label-safe queries, selected-range calculations, zero/no-data states, bounded tables, canonical SLO formulas, and time-preserving Loki/Tempo drill-downs.

package/README.md

@@ -42,8 +42,10 @@ ObservMe maps Pi lifecycle and session events to OpenTelemetry traces, metrics,
 - [Implementation Status](#implementation-status)
 - [Quick Start](#quick-start)
 - [Installation](#installation)
+- [Extension Integration](#extension-integration)
 - [Commands](#commands)
 - [Architecture](#architecture)
+- [Available Telemetry](#available-telemetry)
 - [Configuration and Privacy](#configuration-and-privacy)
 - [Safety Model](#safety-model)
 - [Dashboards and Examples](#dashboards-and-examples)
@@ -56,7 +58,7 @@ ObservMe maps Pi lifecycle and session events to OpenTelemetry traces, metrics,
 
 ## Implementation Status
 
-This checkout implements the ObservMe MVP scope from the packaged `ObservMe-Production-Docs/00-README.md` design overview:
+This checkout implements the ObservMe MVP scope described by the packaged [`docs/reference/00-README.md`](docs/reference/00-README.md) technical reference:
 
 - Extension load checks and `/obs health` backend checks.
 - Session, workflow, agent-run, turn, LLM, tool, bash, subagent-spawn, wait/join, compaction, branch, model-change, and thinking-level telemetry.
@@ -66,8 +68,6 @@ This checkout implements the ObservMe MVP scope from the packaged `ObservMe-Prod
 - Grafana dashboard JSON, alert rules, SLO definitions, Collector examples, and compatibility matrix artifacts.
 - Unit, contract, integration, chaos/failure, performance, package, and smoke-test coverage in the validation pipeline.
 
-The repository version is currently `0.1.0`. Run the validation commands below before publishing or deploying a release build.
-
 ## Quick Start
 
 Use this checklist to confirm telemetry end to end. You need a supported Pi installation; see the [compatibility matrix](docs/compatibility-matrix.md). If you already have an OTLP Collector and Grafana stack, skip the first step.
@@ -144,6 +144,31 @@ pi --no-extensions -e .
 | Git | `pi install git:senad-d/ObservMe` | Install from Git; use a tag or commit when you need a fixed version. |
 | Local checkout | `pi --no-extensions -e .` | Develop or test this repository. |
 
+The package also includes the `observme-docs` skill. Pi can load it automatically for natural-language ObservMe questions, or you can invoke it explicitly with `/skill:observme-docs`. The skill reads only the relevant packaged documentation and cites the matching file and section. ObservMe registers no system-prompt hook; Pi exposes the skill through its normal skill-discovery metadata.
+
+## Extension Integration
+
+Orchestrators, subagent runners, process managers, remote executors, and other Pi extensions can request ObservMe's versioned integration API through `pi.events`. The API records parent-side spawn/wait/join telemetry and returns the sanitized environment that must be passed to each child Pi process for workflow, agent-lineage, and W3C trace propagation.
+
+```typescript
+import { requestObservMeIntegration } from "@senad-d/observme/integration";
+
+const observme = requestObservMeIntegration(pi);
+const started = observme?.startSubagent({
+  command: "pi",
+  spawnType: "extension",
+  spawnReason: "delegated_task",
+  env: process.env,
+});
+
+if (started?.ok) {
+  await launchChildPi({ env: started.env });
+  observme.completeSubagent(started.spawnId, { childStatus: "active" });
+}
+```
+
+Use [`docs/extension-integration.md`](docs/extension-integration.md) for the complete lifecycle and API contract. The shipped [`examples/integrations/subagent-runner.ts`](examples/integrations/subagent-runner.ts) wraps a generic child transport, while [`docs/agent-subagent-observability-requirements.md`](docs/agent-subagent-observability-requirements.md) covers the larger orchestration design.
+
 ## Commands
 
 All commands are registered under `/obs`.
@@ -183,7 +208,67 @@ Grafana
 
 The extension factory in `src/extension.ts` only registers handlers and commands. OTEL SDK startup happens from `session_start`, and bounded flush/shutdown happens from `session_shutdown`, so importing or registering the extension does not open exporters, timers, or sockets.
 
-See `ObservMe-Production-Docs/02-reference-architecture.md` for the full architecture. Implementation planning specs are repository-only and live at <https://github.com/senad-d/ObservMe/tree/main/specs>. A reference Docker Compose deployment of the Grafana/Tempo/Loki/Prometheus/Collector stack is also repository-only at <https://github.com/senad-d/ObservMe/tree/main/observability-stack> because it contains generated local credentials and state placeholders.
+## Available Telemetry
+
+Traces, metrics, and logs are enabled by default and can be disabled independently in configuration. The names below are the OpenTelemetry instrument, span, and `event.name` values defined by ObservMe; backend ingestion may normalize dotted names. The tables identify reserved or registered names that do not yet have a live recording point. Other signals appear only after their corresponding Pi lifecycle event occurs.
+
+Metric labels are intentionally low-cardinality. Session, workflow, agent, trace, span, and entry IDs are available on correlated spans and logs, but are not added to Prometheus labels. Prometheus-compatible backends expose histograms as the usual `_bucket`, `_sum`, and `_count` series.
+
+### Metrics
+
+| Type | Area | Available metrics | What they show |
+| --- | --- | --- | --- |
+| Counter | Sessions and workflows | `observme_sessions_started_total`<br>`observme_sessions_shutdown_total`<br>`observme_workflows_started_total`<br>`observme_workflows_completed_total`<br>`observme_workflow_errors_total` | Session lifecycle and root-workflow outcomes. |
+| Counter | Agents and subagents | `observme_agent_runs_total`<br>`observme_agent_run_errors_total`<br>`observme_subagents_spawned_total`<br>`observme_subagent_spawn_failures_total`<br>`observme_orphan_agents_total`<br>`observme_trace_context_propagation_failures_total`<br>`observme_child_agent_failures_total`<br>`observme_parent_recovered_from_child_failure_total` | Agent activity, lineage health, child failures, and parent recovery. |
+| Counter | Turns and LLM requests | `observme_turns_started_total`<br>`observme_turns_completed_total`<br>`observme_llm_requests_total`<br>`observme_llm_errors_total` | Turn throughput and provider request outcomes. |
+| Counter | LLM tokens and cost | `observme_llm_input_tokens_total`<br>`observme_llm_output_tokens_total`<br>`observme_llm_cache_read_tokens_total`<br>`observme_llm_cache_write_tokens_total`<br>`observme_llm_cache_write_1h_tokens_total`<br>`observme_llm_reasoning_tokens_total`<br>`observme_llm_total_tokens_total`<br>`observme_llm_cost_usd_total` | Provider-reported token usage, cache usage, reasoning usage, and USD cost. Values are recorded when the provider supplies them. |
+| Counter | Tools and Bash | `observme_tool_calls_total`<br>`observme_tool_failures_total`<br>`observme_bash_executions_total`<br>`observme_bash_failures_total` | Tool and interactive Bash volume and failures. |
+| Counter | Session changes | `observme_model_changes_total`<br>`observme_thinking_level_changes_total`<br>`observme_compactions_total`<br>`observme_branches_total` | Model/thinking changes, compactions, and branch creation. |
+| Counter | ObservMe health | `observme_telemetry_dropped_total`<br>`observme_export_errors_total`<br>`observme_redaction_failures_total`<br>`observme_events_observed_total`<br>`observme_handler_errors_total` | Local drops, export/redaction failures, handler activity, and handler failures. |
+| Histogram | Workflow and agent tree | `observme_workflow_duration_ms`<br>`observme_agent_run_duration_ms`<br>`observme_subagent_spawn_duration_ms`<br>`observme_agent_wait_duration_ms`<br>`observme_agent_join_duration_ms`<br>`observme_agent_tree_depth`<br>`observme_agent_tree_width`<br>`observme_agent_fanout_count` | Workflow/agent latency and multi-agent tree shape. |
+| Histogram | Operation latency | `observme_turn_duration_ms`<br>`observme_llm_request_duration_ms`<br>`observme_tool_duration_ms`<br>`observme_bash_duration_ms`<br>`observme_handler_duration_ms` | End-to-end operation and extension-handler duration in milliseconds. |
+| Histogram | Context and payload size | `observme_compaction_tokens_before`<br>`observme_prompt_size_chars`<br>`observme_response_size_chars`<br>`observme_tool_result_size_chars` | Context size before compaction and payload sizes in characters. Size metrics do not contain payload content. |
+| Up-down counter | Current activity | `observme_active_spans`<br>`observme_active_agents` | Active operations and agents for the current exported stream. |
+| Registered, not yet recorded | Agent lifetime | `observme_agent_lifetime_duration_ms` | Reserved instrument; the current live handlers do not record measurements yet. |
+| Registered, not yet recorded | Official GenAI compatibility | `gen_ai.client.token.usage`<br>`gen_ai.client.operation.duration` | Reserved OpenTelemetry GenAI instruments; use the `observme_llm_*` metrics above for current data. |
+
+### Traces
+
+| Span name | Created for | Notes |
+| --- | --- | --- |
+| `pi.session` | A trusted Pi session | Root session span. It remains open during the session and is ended, flushed, and exported on `session_shutdown`. |
+| `pi.agent.run` | An agent run | Child of the session span; records run identity, lineage, source, duration, and status. |
+| `pi.agent.spawn` | A subagent launch | Records spawn type/reason, child identity, propagation outcome, duration, and failure status. |
+| `pi.agent.wait` | Waiting for a child agent | Correlates the parent, child, spawn, wait reason, and duration. |
+| `pi.agent.join` | Joining a child agent | Records child/join status, failure propagation or recovery, and duration. |
+| `pi.turn` | An agent turn | Child of the active agent run when available; contains turn, model, and lineage metadata. |
+| `pi.llm.request` | An LLM provider request | Records provider/model, API, usage, cost, stop reason, duration, and status. Redacted content attributes are opt-in. |
+| `pi.tool.call` | A Pi tool call | Records safe tool metadata, result size, duration, success, and bounded error class. Arguments/results are opt-in. |
+| `pi.bash.execution` | Interactive Bash execution | Records exit/cancel/truncation metadata, output size, duration, and status. Commands/output are opt-in. Tool-driven Bash remains a `pi.tool.call` span. |
+| `pi.compaction` | Session compaction | Records compaction reason, token count, summary metadata, and file-count metadata. |
+| `pi.branch` | Session-tree branch creation | Records source/destination entry metadata, branch summary metadata, and file counts. |
+| `pi.model.change` | Model change | Reserved span name. Current live telemetry adds a `model.changed` event to `pi.session` and emits a structured log instead of a standalone span. |
+| `pi.thinking.change` | Thinking-level change | Reserved span name. Current live telemetry adds a `thinking.changed` event to `pi.session` and emits a structured log instead of a standalone span. |
+
+### Logs
+
+All operational logs use short event bodies plus structured attributes. Correlation fields include available session, workflow, agent, agent-run, turn, trace, and span IDs. Raw prompts, responses, thinking, tool data, Bash data, paths, and error messages are excluded unless their specific capture setting is enabled and the value passes the redaction policy.
+
+| Area | Available `event.name` values | Availability and purpose |
+| --- | --- | --- |
+| Configuration, session, and workflow | `config.rejected`<br>`session.started`<br>`session.shutdown`<br>`session.duplicate_start`<br>`workflow.started`<br>`workflow.completed`<br>`workflow.failed` | Configuration diagnostics and top-level lifecycle/outcome events. |
+| Reserved session events | `session.named`<br>`session.error` | Public event names reserved for compatibility; current live handlers do not emit them. |
+| Agent run | `agent.run.started`<br>`agent.run.completed`<br>`agent.run.failed` | Agent-run lifecycle and outcome. |
+| Subagent lineage | `agent.spawn.started`<br>`agent.spawn.completed`<br>`agent.spawn.failed`<br>`agent.wait.started`<br>`agent.wait.completed`<br>`agent.join.started`<br>`agent.join.completed`<br>`agent.orphaned`<br>`trace_context.propagation_failed` | Parent/child lifecycle, lineage gaps, propagation failures, and join outcomes. |
+| Turn | `turn.started`<br>`turn.completed` | Turn lifecycle with run/turn correlation. |
+| LLM lifecycle | `llm.request.started`<br>`llm.request.completed`<br>`llm.request.failed` | Content-free provider request lifecycle, usage, cost, stop reason, and bounded errors. |
+| LLM content | `llm.prompt.captured`<br>`llm.response.captured`<br>`llm.thinking.captured` | Emitted only when the corresponding prompt, response, or thinking capture flag is enabled and redaction succeeds. |
+| Replay | `message.replayed` | Emitted by explicit `/obs backfill` replay; historical replay is disabled by default. |
+| Tools | `tool.call.started`<br>`tool.call.completed`<br>`tool.call.failed` | Content-free tool lifecycle, safe tool metadata, status, and correlation. |
+| Tool content | `tool.error.captured` | Separate failed-tool result log emitted only when `capture.toolResults` is enabled and redaction succeeds. |
+| Bash | `bash.completed` | Interactive Bash completion, status, exit/cancel/truncation metadata, and safe size/hash metadata. |
+| Session changes | `model.changed`<br>`thinking.changed`<br>`branch.created`<br>`compaction.created` | Model/thinking annotations and branch/compaction lifecycle. |
+| ObservMe health | `telemetry.dropped`<br>`redaction.failed`<br>`export.failed`<br>`handler.failed` | Bounded, content-safe diagnostics for the extension's own telemetry pipeline. |
 
 ## Configuration and Privacy
 
@@ -193,8 +278,6 @@ ObservMe supports layered configuration with this precedence:
 defaults → global ~/.pi/agent/observme.yaml → trusted project config → trusted project .env → system environment variables → runtime options
 ```
 
-The extension automatically creates `<project>/<CONFIG_DIR_NAME>/observme.yaml` (`<project>/.pi/observme.yaml` in the standard distribution) the first time Pi emits `session_start` in a trusted project and the file does not already exist. It uses Pi's exported config-directory name and serialized file-mutation queue. Pi emits that lifecycle for startup, `/reload`, new-session, resume, and fork flows; ObservMe attempts the same idempotent bootstrap for each trusted flow, skips untrusted projects or contexts without `ctx.cwd`, and never overwrites an existing file. Edit this file for project-specific setup: `otlp.endpoint` / `otlp.signalEndpoints` for your Collector, `resource.attributes` for service/project/tenant/environment identity, `capture` and `privacy` for content visibility, and `query.grafana` plus `query.links.traceUrlTemplate` for `/obs` Grafana commands. The generated starter keeps content-capture flags disabled, `privacy.redactionEnabled: true`, and `privacy.allowUnsafeCapture: false`; for local debugging, set only the needed `capture.*` flags to `true` and keep redaction enabled. Keep secrets out of YAML; use environment variables or a trusted project `.env` for values such as `OBSERVME_OTLP_TOKEN`, `OBSERVME_GRAFANA_TOKEN`, `OBSERVME_GRAFANA_PASSWORD`, and `OBSERVME_HASH_SALT`. See [`docs/configuration.md`](docs/configuration.md) for the quick configuration guide.
-
 Factory-safe loading uses defaults/global/system-environment/runtime options only. Session-scoped loading can add trusted project config and a project-local `.env` when Pi marks the project trusted. `/obs status` reports the effective config source, whether project-local config was loaded, skipped because the project is untrusted, or missing, plus bounded rejection issue codes, the configured Grafana URL, and query-readiness status without rendering tokens or passwords. In untrusted projects, ObservMe does not read project-local config or `.env` files and uses safe defaults/global/system-environment layers instead. Invalid or unsafe configuration emits a bounded `config.rejected` diagnostic and falls back safely without exposing rejected values.
 
 Cross-process agent lineage has a separate boundary: only the Pi process environment available to the shipped extension, or explicit runtime options for controlled embedders, is eligible for parent provenance. Project-local `.env` values configure ObservMe but cannot establish lineage. A child accepts only a complete validated workflow/parent/root/depth/spawn envelope and valid W3C context; malformed or stale envelopes fail open to a root/orphan fallback with sanitized telemetry.
@@ -269,7 +352,7 @@ For intentionally raw local debugging only, set `OBSERVME_REDACTION_ENABLED=fals
 
 Only new LLM events emitted after these settings and the updated Collector are active can show content; older telemetry dropped by the Collector cannot be recovered. Open the **ObservMe LLM Conversations** dashboard for a dedicated opt-in chat timeline. Do not query Grafana with raw prompt or response text.
 
-Full configuration schema: `ObservMe-Production-Docs/12-configuration-reference.md`. Full redaction/privacy design: `ObservMe-Production-Docs/06-security-privacy-redaction.md`.
+Full configuration schema: `docs/reference/12-configuration-reference.md`. Full redaction/privacy design: `docs/reference/06-security-privacy-redaction.md`.
 
 ## Safety Model
 
@@ -281,7 +364,7 @@ Full configuration schema: `ObservMe-Production-Docs/12-configuration-reference.
 - `/obs` query commands are read-only and are not imported by telemetry-emission code paths.
 - Invalid or unsafe configuration falls back to safe defaults with bounded `config.rejected`, `/obs status`, and available Pi UI diagnostics; rejected values are never rendered. Intentionally unsafe capture emits a visible warning.
 
-See [`SECURITY.md`](SECURITY.md) and `ObservMe-Production-Docs/06-security-privacy-redaction.md` for details.
+See [`SECURITY.md`](SECURITY.md) and `docs/reference/06-security-privacy-redaction.md` for details.
 
 ## Dashboards and Examples
 
@@ -290,21 +373,28 @@ These assets are included in the npm package:
 - Grafana dashboards: `dashboards/observme-*.json`, including Overview, SLO Health, Export Health, Trace Journey, Agents, Agent Node Graphs, Cost, Models, Latency, Tools, Errors, Logs and LLM I/O, LLM Conversations, and Branches/Compactions.
 - Alert rules: `dashboards/observme-alerts.yaml`.
 - SLO definitions: `dashboards/observme-slos.yaml`.
-- Supported local-stack ObservMe config: `examples/observme.yaml`.
-- Production Collector config with high-cardinality and content-drop processors: `examples/collector.yaml`.
-- Compatibility matrix: `docs/compatibility-matrix.md`.
+- Example guide and safety notes: [`examples/README.md`](examples/README.md).
+- Transport-agnostic subagent integration example: [`examples/integrations/subagent-runner.ts`](examples/integrations/subagent-runner.ts).
+- Supported local-stack ObservMe config: [`examples/observme.yaml`](examples/observme.yaml).
+- Production Collector config with high-cardinality and content-drop processors: [`examples/collector.yaml`](examples/collector.yaml).
+- Compatibility matrix: [`docs/compatibility-matrix.md`](docs/compatibility-matrix.md).
 
 Open **ObservMe Overview** first for health/SLO chips, workload, cost, latency, agent-lineage status, and time-preserving links to focused dashboards. Use **Trace Journey** to follow a session/workflow/agent/run across Prometheus aggregates, Loki logs, and Tempo traces. Use **LLM Conversations** only for redacted opt-in content; raw prompt, response, command, path, and error-message values should never be placed in dashboard URLs or Prometheus labels. Empty failure tables normally mean no matching failures in the selected range, while optional content panels can be empty because capture is disabled by default.
 
-The full dashboard map, standard variables, drill-down workflow, threshold colors, and zero-state semantics are documented in `ObservMe-Production-Docs/09-dashboards-alerts-slos.md`.
+The full dashboard map, standard variables, drill-down workflow, threshold colors, and zero-state semantics are documented in `docs/reference/09-dashboards-alerts-slos.md`.
 
 ## Documentation Set
 
+Start with [`docs/README.md`](docs/README.md), which routes installation, configuration, privacy, telemetry, troubleshooting, operations, architecture, and contributor questions to the smallest relevant document set.
+
 - [`docs/configuration.md`](docs/configuration.md): quick configuration guide.
 - [`docs/compatibility-matrix.md`](docs/compatibility-matrix.md): supported Pi, Node.js, OpenTelemetry, and local-stack versions.
 - [`docs/validation-flow.md`](docs/validation-flow.md): secret-safe Grafana and `/obs` troubleshooting flow.
-- `ObservMe-Production-Docs/`: architecture, configuration, privacy, dashboards, and operational reference docs.
+- [`docs/extension-integration.md`](docs/extension-integration.md): public API and process-propagation contract for other Pi extensions.
+- [`examples/README.md`](examples/README.md): example selection, usage, and safety guidance.
+- [`docs/reference/00-README.md`](docs/reference/00-README.md): categorized technical reference index.
 - [`SECURITY.md`](SECURITY.md): security reporting and package safety guidance.
+- [`skills/observme-docs/SKILL.md`](skills/observme-docs/SKILL.md): Pi's progressive-disclosure router for natural-language ObservMe questions.
 
 ## Development
 

package/SECURITY.md

@@ -1,6 +1,6 @@
 # Security Policy
 
-ObservMe is a Pi extension that instruments Pi agent sessions and exports OpenTelemetry traces, metrics, and logs to an external observability stack such as an OpenTelemetry Collector, Grafana Tempo, Loki, Prometheus, Mimir, or Grafana Cloud. This policy summarizes the implemented trust model; see `ObservMe-Production-Docs/06-security-privacy-redaction.md` for the full security, privacy, and redaction specification.
+ObservMe is a Pi extension that instruments Pi agent sessions and exports OpenTelemetry traces, metrics, and logs to an external observability stack such as an OpenTelemetry Collector, Grafana Tempo, Loki, Prometheus, Mimir, or Grafana Cloud. This policy summarizes the implemented trust model; see `docs/reference/06-security-privacy-redaction.md` for the full security, privacy, and redaction specification.
 
 ## Trust model
 

package/dashboards/observme-slos.yaml

@@ -1,5 +1,5 @@
 version: 1
-source: ObservMe-Production-Docs/09-dashboards-alerts-slos.md#12-slos
+source: docs/reference/09-dashboards-alerts-slos.md#12-slos
 slos:
   - id: observability-export
     name: Observability Export SLO

package/docs/README.md

@@ -0,0 +1,54 @@
+# ObservMe documentation
+
+This page is the entry point for ObservMe user, operator, and contributor documentation. Start with the task-oriented guides, then open the deeper reference only when you need implementation or telemetry-contract detail.
+
+## Start here
+
+| Goal | Read first | Then, if needed |
+| --- | --- | --- |
+| Install ObservMe and learn `/obs` commands | [`../README.md`](../README.md) | [`configuration.md`](configuration.md) |
+| Configure a trusted project | [`configuration.md`](configuration.md) | [`reference/12-configuration-reference.md`](reference/12-configuration-reference.md) |
+| Validate Grafana and `/obs` together | [`validation-flow.md`](validation-flow.md) | [`reference/11-deployment-runbooks.md`](reference/11-deployment-runbooks.md) |
+| Check supported versions | [`compatibility-matrix.md`](compatibility-matrix.md) | [`reference/10-testing-release-operations.md`](reference/10-testing-release-operations.md) |
+| Understand privacy and content capture | [`../SECURITY.md`](../SECURITY.md) | [`reference/06-security-privacy-redaction.md`](reference/06-security-privacy-redaction.md) |
+| Configure an OTEL Collector | [`../examples/README.md`](../examples/README.md) | [`reference/05-otel-pipeline-and-collector.md`](reference/05-otel-pipeline-and-collector.md) |
+| Understand metrics, spans, logs, and labels | [`../README.md#available-telemetry`](../README.md#available-telemetry) | [`reference/04-telemetry-semantic-conventions.md`](reference/04-telemetry-semantic-conventions.md) |
+| Operate dashboards, alerts, and SLOs | [`../README.md#dashboards-and-examples`](../README.md#dashboards-and-examples) | [`reference/09-dashboards-alerts-slos.md`](reference/09-dashboards-alerts-slos.md) |
+| Understand architecture and lifecycle | [`reference/02-reference-architecture.md`](reference/02-reference-architecture.md) | [`reference/03-pi-event-and-session-model.md`](reference/03-pi-event-and-session-model.md) |
+| Integrate another Pi extension or orchestrator | [`extension-integration.md`](extension-integration.md) | [`agent-subagent-observability-requirements.md`](agent-subagent-observability-requirements.md) |
+| Diagnose parent/subagent lineage | [`agent-subagent-observability-requirements.md`](agent-subagent-observability-requirements.md) | [`reference/03-pi-event-and-session-model.md`](reference/03-pi-event-and-session-model.md) |
+
+## User and operator guides
+
+- [`configuration.md`](configuration.md) — project config creation, fields to edit, credentials, privacy defaults, and precedence.
+- [`validation-flow.md`](validation-flow.md) — secret-safe troubleshooting when Grafana or `/obs` does not behave as expected.
+- [`compatibility-matrix.md`](compatibility-matrix.md) — tested Pi, Node.js, OpenTelemetry, Collector, and Grafana-stack versions.
+- [`../examples/README.md`](../examples/README.md) — purpose and safe use of the shipped configuration and integration examples.
+- [`extension-integration.md`](extension-integration.md) — public event-bus API for orchestrators, subagent runners, and other Pi extensions.
+- [`../SECURITY.md`](../SECURITY.md) — package trust model and vulnerability reporting.
+
+## Technical reference
+
+[`reference/00-README.md`](reference/00-README.md) is the reference index. Use it for architecture, Pi event mapping, telemetry semantics, Collector design, privacy rules, query behavior, dashboards, testing, deployment, and the complete configuration schema.
+
+The reference set is detailed and may describe reserved contracts as well as live behavior. The telemetry tables in [`../README.md#available-telemetry`](../README.md#available-telemetry) identify signals that are reserved or registered but not currently recorded.
+
+## Contributor and design notes
+
+These documents support extension development and are not the shortest path for normal setup:
+
+- [`STRUCTURE.md`](STRUCTURE.md) — repository structure conventions.
+- [`agent-subagent-observability-requirements.md`](agent-subagent-observability-requirements.md) — complete orchestration and tmux lineage requirements beyond the public integration API.
+- [`configuration-tui-design-standard.md`](configuration-tui-design-standard.md) — reusable configuration TUI visual design.
+- [`review-validation.md`](review-validation.md) — repository review and release-validation evidence.
+
+## Documentation precedence
+
+When documents overlap, use this order:
+
+1. [`../README.md`](../README.md) and the task-oriented guides in this directory for current user-facing behavior.
+2. [`reference/12-configuration-reference.md`](reference/12-configuration-reference.md) for the complete configuration contract.
+3. The remaining production reference documents for architecture and implementation detail.
+4. Contributor/design notes for repository work and future integration requirements.
+
+If two documents conflict, report the conflict explicitly instead of silently combining them. Never include credentials, raw prompts, raw commands, or other sensitive values in examples or troubleshooting output.

package/docs/agent-subagent-observability-requirements.md

@@ -13,17 +13,20 @@ It is documentation-only. It does not change runtime behavior.
 Project sources:
 
 - `README.md`
-- `ObservMe-Production-Docs/01-requirements-and-scope.md`
-- `ObservMe-Production-Docs/02-reference-architecture.md`
-- `ObservMe-Production-Docs/03-pi-event-and-session-model.md`
-- `ObservMe-Production-Docs/04-telemetry-semantic-conventions.md`
-- `ObservMe-Production-Docs/06-security-privacy-redaction.md`
-- `ObservMe-Production-Docs/07-extension-implementation-blueprint.md`
-- `ObservMe-Production-Docs/09-dashboards-alerts-slos.md`
-- `ObservMe-Production-Docs/10-testing-release-operations.md`
-- `ObservMe-Production-Docs/12-configuration-reference.md`
+- `docs/extension-integration.md`
+- `docs/reference/01-requirements-and-scope.md`
+- `docs/reference/02-reference-architecture.md`
+- `docs/reference/03-pi-event-and-session-model.md`
+- `docs/reference/04-telemetry-semantic-conventions.md`
+- `docs/reference/06-security-privacy-redaction.md`
+- `docs/reference/07-extension-implementation-blueprint.md`
+- `docs/reference/09-dashboards-alerts-slos.md`
+- `docs/reference/10-testing-release-operations.md`
+- `docs/reference/12-configuration-reference.md`
+- `src/integration.ts`
 - `src/pi/agent-lineage.ts`
 - `src/pi/agent-tree-tracker.ts`
+- `src/pi/integration-api.ts`
 - `src/pi/subagent-spawn.ts`
 - `src/pi/handlers.ts`
 - `src/pi/handler-internals.ts`
@@ -41,6 +44,7 @@ Project sources:
 - `dashboards/observme-slos.yaml`
 - `examples/observme.yaml`
 - `examples/collector.yaml`
+- `examples/integrations/subagent-runner.ts`
 - `test/agent-lineage.test.ts`
 - `test/subagent-spawn.test.mjs`
 
@@ -233,18 +237,16 @@ The required parent-side flow is:
 9. Parent records `pi.agent.join` when it receives the child result/status.
 10. Parent updates the in-memory agent tree and `/obs agents` runtime state.
 
-The existing helper module for this is `src/pi/subagent-spawn.ts`:
+External extensions use the versioned API documented in [`extension-integration.md`](extension-integration.md):
 
-- `startSubagentSpawn(...)`
-- `completeSubagentSpawn(...)`
-- `failSubagentSpawn(...)`
-- `runSubagentWithObservability(...)`
-- `startAgentWait(...)` / `endAgentWait(...)`
-- `startAgentJoin(...)` / `endAgentJoin(...)`
-- `recordAgentWait(...)` / `recordAgentJoin(...)`
-- `observeTrustedSubagentLineage(...)`
+- `requestObservMeIntegration(pi)`
+- `startSubagent(...)`
+- `completeSubagent(...)`
+- `failSubagent(...)`
+- `startWait(...)` / `endWait(...)`
+- `startJoin(...)` / `endJoin(...)`
 
-If a subagent extension launches `pi` without using these helpers, ObservMe can still observe the launcher as a normal tool call, but the agent/subagent dashboards will not get the full spawn/depth/fan-out/wait/join contract.
+The API delegates to ObservMe's internal `src/pi/subagent-spawn.ts` helpers without exposing the private telemetry session. If a subagent extension launches `pi` without this integration, ObservMe can still observe the launcher as a normal tool call, but the agent/subagent dashboards will not get the full spawn/depth/fan-out/wait/join contract.
 
 ### Tmux-specific spawn requirements
 
@@ -262,14 +264,7 @@ Required flow:
 8. Record `wait` while the orchestrator is waiting for child completion or a child status signal.
 9. Record `join` when the orchestrator collects a child result, sees a terminal child status, or times out.
 
-Conceptual command shape:
-
-```text
-tmux new-session -d -s <safe-session-name> \
-  'env OBSERVME_WORKFLOW_ID=... OBSERVME_PARENT_AGENT_ID=... traceparent=... pi ...'
-```
-
-The command above is illustrative only. The implementation must avoid logging the raw command because it contains environment values and user task text.
+Prefer a dedicated tmux server/socket that is started with the returned process environment, or explicit tmux per-session environment facilities. Do not serialize the envelope into a shell command. The generic [`../examples/integrations/subagent-runner.ts`](../examples/integrations/subagent-runner.ts) adapter leaves this transport-specific environment handling to its `ChildTransport` implementation.
 
 ## 4. Environment propagation contract
 
@@ -821,20 +816,21 @@ The Pi example subagent extension:
 - collects child assistant messages, tool results, token usage, cost, and final output
 - supports Ctrl+C abort by killing child processes
 
-By default, the example spawn call does not pass ObservMe propagation env and does not call ObservMe's `startSubagentSpawn` / `completeSubagentSpawn` / `failSubagentSpawn` helpers.
+By default, the example spawn call does not request ObservMe's integration API or pass its propagation environment.
 
 Therefore, to use that style of subagent and still populate ObservMe dashboards, an ObservMe-aware adapter must wrap the child process spawn and pass the returned env to the child process.
 
 Minimum adapter behavior:
 
-1. Before spawning child Pi, call `startSubagentSpawn` with spawn type/reason and safe command metadata.
-2. Pass `started.env` into `child_process.spawn`.
-3. On child process close success, call `completeSubagentSpawn`.
-4. On child process error/abort/failure, call `failSubagentSpawn` or complete with cancelled/failed status.
-5. Around blocking waits, record `pi.agent.wait`.
-6. When child output is collected, record `pi.agent.join` with child status.
-7. Ensure the child command loads ObservMe as an extension/package.
-8. Ensure the child ObservMe runtime accepts the propagated parent context as trusted.
+1. Request the API with `requestObservMeIntegration(pi)`.
+2. Before spawning child Pi, call `startSubagent` with spawn type/reason and safe command metadata.
+3. Pass the returned `env` into `child_process.spawn`.
+4. On launcher success, call `completeSubagent` with child status `active`.
+5. On launcher error/abort/failure, call `failSubagent` or complete with cancelled status.
+6. Around blocking waits, call `startWait` and `endWait`.
+7. When child output is collected, call `startJoin` and `endJoin` with child status.
+8. Ensure the child command loads ObservMe as an extension/package.
+9. Ensure the child ObservMe runtime receives the complete propagated parent context.
 
 Without that adapter, parent tool metrics may show a `subagent` tool call, but the agent-tree dashboard will not have reliable spawn/depth/fan-out/wait/join lineage.
 
@@ -946,7 +942,7 @@ These checkpoints reflect the current code and dashboards after source-review re
 - The production extension enables process-environment lineage eligibility while keeping trusted project `.env` outside the provenance boundary.
 - Valid W3C context explicitly parents the child `pi.session`; unavailable continuation uses a validated span link or bounded propagation-failure fallback.
 - Bounded agent-tree tracking exists in `src/pi/agent-tree-tracker.ts`.
-- Spawn/wait/join helper functions exist in `src/pi/subagent-spawn.ts`.
+- Spawn/wait/join helper functions exist in `src/pi/subagent-spawn.ts` and are exposed to other loaded extensions through the versioned `@senad-d/observme/integration` event-bus API.
 - Spawn duration is recorded on completion and launcher failure. Child completion/join records child failure and confirmed parent recovery once through bounded deduplication state.
 - Session, agent-run/turn, LLM, tool/bash, and session metadata/tree handlers are split under `src/pi/event-handlers/` behind the stable `src/pi/handlers.ts` facade.
 - Root workflow duration is recorded at shutdown, and failed agent runs increment `observme_agent_run_errors_total`.
@@ -957,7 +953,7 @@ These checkpoints reflect the current code and dashboards after source-review re
 ### Remaining integration gaps before relying on full subagent dashboards
 
 1. **External and tmux subagent launchers are not automatically wrapped.**
-   - `src/pi/subagent-spawn.ts` exposes helpers, but arbitrary extensions that call `child_process.spawn` or `tmux new-session` will not be detected automatically.
+   - The public integration API lets launchers record the lifecycle explicitly, but arbitrary extensions that call `child_process.spawn` or `tmux new-session` without it cannot be detected automatically.
    - The Pi example subagent extension currently spawns child Pi processes without ObservMe env propagation.
    - A future tmux orchestration extension must own this wrapping and lifecycle tracking.
 

package/docs/configuration.md

@@ -1,5 +1,7 @@
 # ObservMe configuration
 
+Use this guide for routine project setup. For every supported key and environment variable, see the [complete configuration reference](reference/12-configuration-reference.md). For the supported local profile, see the [example guide](../examples/README.md).
+
 ObservMe creates a project-local starter config automatically during trusted Pi session-start lifecycles.
 
 ## Automatic project config
@@ -36,3 +38,10 @@ defaults → global ~/.pi/agent/observme.yaml → trusted project .pi/observme.y
 Use `~/.pi/agent/observme.yaml` for standard-distribution global defaults that should apply across projects. Use `<CONFIG_DIR_NAME>/observme.yaml` for per-project setup. Because `.env` and system environment variables have higher precedence than YAML, remove or update stale `OBSERVME_REDACTION_ENABLED`, `OBSERVME_ALLOW_UNSAFE_CAPTURE`, and `OBSERVME_CAPTURE_*` overrides when YAML privacy settings appear to be ignored.
 
 Invalid or unsafe merged configuration falls back to safe defaults. `/obs status`, structured `config.rejected` telemetry, and Pi UI notifications when available report only bounded source and issue codes/counts; rejected values, paths, headers, regular expressions, and credentials are never rendered. Project `.env` remains a configuration layer only and cannot establish parent-agent lineage.
+
+## Related documentation
+
+- [Documentation index](README.md)
+- [Example configurations](../examples/README.md)
+- [Security, privacy, and redaction](reference/06-security-privacy-redaction.md)
+- [Grafana and `/obs` validation flow](validation-flow.md)