@senad-d/observme 0.1.1 → 0.1.2

package/docs/extension-integration.md

@@ -0,0 +1,222 @@
+# Integrating other Pi extensions with ObservMe
+
+Use this guide when another Pi extension launches or manages work that ObservMe cannot infer from Pi's standard lifecycle events. Orchestrators, subagent runners, process managers, remote executors, and workflow engines should use the versioned integration API instead of constructing ObservMe lineage variables themselves.
+
+## What ObservMe captures automatically
+
+Every Pi process that loads ObservMe emits its own supported session, workflow, agent-run, turn, LLM, tool, Bash, branch, compaction, model, thinking, trace, metric, and log telemetry. No integration API is needed for those standard Pi events.
+
+Cross-process orchestration adds information that Pi does not emit automatically:
+
+- a parent decided to spawn a child;
+- the child belongs to a specific workflow and parent/root lineage;
+- W3C trace context should cross the process boundary;
+- the parent waited for and joined the child;
+- the launcher, child, or join failed, timed out, or recovered.
+
+An orchestration extension must report those transitions and launch the child with the propagation environment returned by ObservMe.
+
+## Public integration surface
+
+Import the API types and discovery helper from the package subpath:
+
+```typescript
+import {
+  requestObservMeIntegration,
+  type ObservMeIntegrationApi,
+} from "@senad-d/observme/integration";
+```
+
+The helper uses Pi's shared `pi.events` bus and negotiates integration API version 1 synchronously:
+
+```typescript
+const observme: ObservMeIntegrationApi | undefined = requestObservMeIntegration(pi);
+```
+
+ObservMe registers no global object and does not require another extension to import its internal telemetry session. The event bus is the runtime boundary; the package subpath provides the stable constants, types, and request helper.
+
+The API can be absent when ObservMe is not installed, disabled by package configuration, not loaded yet, or incompatible. A method returns `{ ok: false, reason: "session_unavailable" }` when ObservMe is loaded but no telemetry session is active. Orchestration must remain functional in both cases and may run the child without ObservMe correlation after reporting a bounded local warning.
+
+A package that cannot take a runtime dependency can implement the same synchronous request directly. Keep this channel and version stable:
+
+```typescript
+let observme: ObservMeIntegrationApi | undefined;
+pi.events.emit("observme:integration:request", {
+  supportedVersions: [1],
+  respond(api: ObservMeIntegrationApi) {
+    observme ??= api;
+  },
+});
+```
+
+Request the API when the user/tool starts orchestration, not from the extension factory. If a `session_start` handler must launch work automatically, account for extension handler ordering and retry only after ObservMe has an active session.
+
+## Required parent lifecycle
+
+Use this order for each child process:
+
+1. Request the ObservMe integration API.
+2. Call `startSubagent()` immediately before launching the child.
+3. Pass the returned `env` as the child process environment without logging it.
+4. Call `completeSubagent(..., { childStatus: "active" })` when the launcher successfully creates the child.
+5. Call `failSubagent()` when the launcher fails before the child is active.
+6. Call `startWait()`/`endWait()` around time spent waiting for child completion.
+7. Call `startJoin()`/`endJoin()` when collecting the terminal child status or result.
+
+```typescript
+const observme = requestObservMeIntegration(pi);
+const started = observme?.startSubagent({
+  command: "pi",
+  args: ["--mode", "rpc"],
+  spawnType: "extension",
+  spawnReason: "delegated_task",
+  env: process.env,
+});
+
+if (!started?.ok) {
+  // Continue fail-open without correlation, or notify the operator locally.
+  return;
+}
+
+try {
+  await launchChildPi({ env: started.env });
+  observme.completeSubagent(started.spawnId, {
+    childAgentId: started.childAgentId,
+    childStatus: "active",
+  });
+} catch (error) {
+  observme.failSubagent(started.spawnId, {
+    childAgentId: started.childAgentId,
+    errorClass: error instanceof Error ? error.name : "launcher_error",
+  });
+  throw error;
+}
+```
+
+Do not put raw tasks, prompts, command lines, environment values, child output, or private paths in `errorClass`, `spawnReason`, or other bounded fields.
+
+## API methods
+
+| Method | Use |
+| --- | --- |
+| `getContext()` | Read the current workflow, root/parent/current agent, role, depth, session, and trace identifiers for local orchestration correlation. These are high-cardinality values and must not become metric labels. |
+| `startSubagent(options)` | Starts `pi.agent.spawn`, records spawn metrics/logs, creates bounded parent tree state, and returns a sanitized propagation environment. |
+| `completeSubagent(spawnId, options)` | Ends a successful launcher operation. Use child status `active` when the child is running; use `completed` only when launch and child completion are intentionally represented together. |
+| `failSubagent(spawnId, options)` | Ends a launcher failure and records bounded failure telemetry. |
+| `startWait(options)` / `endWait(id, options)` | Measures time the parent is blocked on a child or dependency. |
+| `startJoin(options)` / `endJoin(id, options)` | Measures result collection and records child failure propagation or confirmed parent recovery. |
+
+`startSubagent()` accepts:
+
+| Option | Values and meaning |
+| --- | --- |
+| `spawnId` | Optional caller-generated safe ID; omit to let ObservMe generate it. |
+| `childAgentId` | Optional bounded parent-side placeholder; this is not propagated as the child's real agent ID. |
+| `command` / `args` | Used only to create a salted command fingerprint when configured; raw values are not exported. Omit them if the launcher cannot safely provide them. |
+| `spawnType` | `command`, `tool`, `extension`, or `unknown`. |
+| `spawnReason` | `delegated_task`, `parallel_search`, `review`, `tool_wrapper`, or `unknown`. |
+| `toolCallId` | Optional high-cardinality trace/log correlation when a tool initiated the spawn. |
+| `env` | Base child environment. ObservMe removes stale lineage/W3C keys and returns the replacement environment. |
+
+Completion and wait/join methods use bounded child states (`starting`, `active`, `completed`, `failed`, `cancelled`, `orphaned`), join states (`waiting`, `completed`, `failed`, `cancelled`, `timeout`, `unknown`), and wait reasons (`dependency`, `rate_limit`, `child_running`, `unknown`). `failurePropagated=false` on a completed join confirms that the parent recovered from a failed child.
+
+All mutation methods return a discriminated result. Handle `session_unavailable`, `spawn_not_found`, `wait_not_found`, `join_not_found`, and `operation_failed` without crashing Pi. Do not retry a completed lifecycle handle blindly; repeated completion can otherwise hide an orchestration-state bug.
+
+## Propagation environment
+
+`startSubagent()` clears stale ObservMe and W3C values from the supplied base environment and, when enabled, returns a complete current envelope. Default names are:
+
+```text
+OBSERVME_WORKFLOW_ID
+OBSERVME_PARENT_AGENT_ID
+OBSERVME_ROOT_AGENT_ID
+OBSERVME_PARENT_SESSION_ID
+OBSERVME_PARENT_TRACE_ID
+OBSERVME_PARENT_SPAN_ID
+OBSERVME_AGENT_DEPTH
+OBSERVME_SPAWN_ID
+OBSERVME_AGENT_CAPABILITY
+traceparent
+tracestate
+```
+
+Important rules:
+
+- Pass the complete returned `env`; do not merge stale lineage values back afterward.
+- Do not set `OBSERVME_AGENT_ID` for a child. The child creates its own logical agent ID.
+- `OBSERVME_AGENT_DEPTH` carries the parent depth; the child increments it.
+- The child accepts lineage only from its Pi process environment, not project `.env`.
+- When trace propagation is enabled, `traceparent` is required and duplicate parent trace/span metadata must agree with it.
+- Never log or persist the full environment.
+
+Names can be changed in ObservMe configuration. This is another reason to use the returned environment rather than hardcoding defaults.
+
+## Child requirements
+
+The child Pi process must:
+
+1. load a compatible ObservMe package;
+2. receive the returned environment unchanged;
+3. use the same or a compatible OTLP destination;
+4. run in a trusted project when project-local ObservMe configuration is required;
+5. avoid `--no-extensions` unless ObservMe is explicitly loaded again with `-e`.
+
+A child that loads ObservMe without the envelope is still observable, but it appears as a separate root-like runtime. A malformed or partial envelope fails open and emits bounded orphan/propagation diagnostics.
+
+The parent-side `childAgentId` is a bounded placeholder until the child's generated agent ID is reported through the orchestrator's own RPC, status-file, or result protocol. Use `spawnId`, workflow ID, and trace context as the initial cross-process correlation. Do not propagate the placeholder as `OBSERVME_AGENT_ID`.
+
+## Transport requirements
+
+The integration API is transport-agnostic. A launcher can use a local subprocess, Pi RPC, JSON/print mode, tmux, SSH, a container runtime, a queue, or another process manager as long as it:
+
+- passes the returned environment unchanged to the child Pi process;
+- does not serialize the envelope or raw task into telemetry or captured logs;
+- reports launcher completion/failure separately from child completion;
+- records wait and join around the transport's actual blocking and result-collection boundaries;
+- guarantees the child loads a compatible ObservMe extension;
+- cleans up temporary files, pipes, sessions, containers, or remote resources deterministically.
+
+Transport-specific environment behavior remains the launcher's responsibility. For example, a long-running tmux server can cache an old environment, an SSH command can expose arguments in logs, and a container runtime can require an explicit environment allowlist. Use the transport's secure environment mechanism instead of embedding the envelope in a shell command.
+
+See [`../examples/integrations/subagent-runner.ts`](../examples/integrations/subagent-runner.ts) for a generic transport adapter and [`agent-subagent-observability-requirements.md`](agent-subagent-observability-requirements.md) for detailed orchestration considerations.
+
+## Telemetry produced by a complete integration
+
+A complete parent/child flow can produce:
+
+- spans: `pi.agent.spawn`, `pi.agent.wait`, `pi.agent.join`, and the child's normal `pi.session`/agent/turn/LLM/tool spans;
+- metrics: spawn count/failure/duration, wait/join duration, active agents, depth, width, fan-out, orphan and propagation failures, child failures, and parent recovery;
+- logs: `agent.spawn.*`, `agent.wait.*`, `agent.join.*`, `agent.orphaned`, and `trace_context.propagation_failed`.
+
+Workflow, session, agent, spawn, trace, and span identifiers remain trace/log attributes only. Aggregate metric labels use bounded fields such as role, depth, spawn type/reason, status, reason, and error class.
+
+## Supported boundaries and non-goals
+
+| Integration | Supported behavior |
+| --- | --- |
+| Direct child `pi` process | Full parent spawn/wait/join telemetry and child trace continuation when the child loads ObservMe and receives the returned environment. |
+| Process-manager child Pi | Supported with explicit environment handling appropriate to the selected transport. |
+| RPC, JSON, or print-mode child Pi | Supported; the orchestration transport determines task/result handling while ObservMe handles telemetry correlation. |
+| Remote child Pi | Supported when the launcher transmits the envelope securely, the child loads ObservMe, and both sides export to compatible backends. Do not print the envelope into remote shell logs. |
+| Non-Pi subprocess | Parent launcher telemetry can be recorded, but the subprocess does not emit Pi session/turn/LLM/tool telemetry unless it is itself instrumented. |
+| Arbitrary custom metrics/logs/spans | Not exposed by this API. The API intentionally limits labels and event names to the ObservMe orchestration contract. Propose a versioned semantic addition instead of accepting arbitrary telemetry names or labels. |
+| Orchestration control | Not provided. Task queues, process/session management, RPC, retries, concurrency, status transport, result storage, and cleanup remain the orchestrator's responsibility. |
+
+## Dependency and versioning guidance
+
+The example imports `@senad-d/observme/integration` because it ships inside the same ObservMe package. A separately distributed Pi package has two choices:
+
+1. Add `@senad-d/observme` as a development/runtime dependency according to its packaging strategy so the helper and types resolve, while still requiring users to load ObservMe as a Pi extension.
+2. Avoid a runtime dependency by emitting the documented `observme:integration:request` event locally and using an `import type` during development. The runtime protocol is the shared Pi event channel, not shared module state.
+
+Pi packages can have separate module roots. Do not assume that an independently installed ObservMe package is automatically resolvable as a Node module from another package, and do not load a bundled second ObservMe extension accidentally. Runtime negotiation determines whether one compatible ObservMe integration provider is actually loaded.
+
+The current public integration version is `1`. Additive API changes can preserve version 1; incompatible behavior requires a new negotiated version.
+
+## Related documentation
+
+- [Documentation index](README.md)
+- [Agent and subagent orchestration requirements](agent-subagent-observability-requirements.md)
+- [Pi event and session model](reference/03-pi-event-and-session-model.md)
+- [Telemetry semantic conventions](reference/04-telemetry-semantic-conventions.md)
+- [Configuration reference](reference/12-configuration-reference.md)

package/docs/reference/00-README.md

@@ -0,0 +1,81 @@
+# ObservMe technical reference
+
+This directory contains the detailed architecture, telemetry, privacy, operations, and implementation contracts for ObservMe. For installation or routine setup, start with [`../../README.md`](../../README.md) and the task-oriented [`../README.md`](../README.md) index instead.
+
+ObservMe is a Pi extension that captures session, turn, tool, LLM, branch, compaction, and agent-lineage events, translates them into OpenTelemetry traces, metrics, and logs, and exports them to an external observability stack. It is not a local analytics database.
+
+## Choose a document
+
+### Product and architecture
+
+| File | Use it for |
+| --- | --- |
+| [`01-requirements-and-scope.md`](01-requirements-and-scope.md) | Product goals, personas, hard requirements, non-goals, and success criteria. |
+| [`02-reference-architecture.md`](02-reference-architecture.md) | Components, data flow, trace shape, deployment topologies, and failure boundaries. |
+| [`03-pi-event-and-session-model.md`](03-pi-event-and-session-model.md) | Pi event mapping, session entries, branching, compaction, recovery, and agent lineage. |
+| [`07-extension-implementation-blueprint.md`](07-extension-implementation-blueprint.md) | Extension modules, lifecycle, span registries, handlers, and implementation patterns. |
+| [`pi-session-format.md`](pi-session-format.md) | Adapted Pi JSONL session reference used by ObservMe. |
+
+### Telemetry and data handling
+
+| File | Use it for |
+| --- | --- |
+| [`04-telemetry-semantic-conventions.md`](04-telemetry-semantic-conventions.md) | Span names, attributes, metrics, labels, logs, and cardinality rules. |
+| [`05-otel-pipeline-and-collector.md`](05-otel-pipeline-and-collector.md) | OTLP exporters, Collector pipelines, routing, sampling, and backend notes. |
+| [`06-security-privacy-redaction.md`](06-security-privacy-redaction.md) | Capture defaults, data classification, redaction, hashing, TLS, and tenant isolation. |
+
+### Operation and configuration
+
+| File | Use it for |
+| --- | --- |
+| [`08-query-grafana-integration.md`](08-query-grafana-integration.md) | `/obs` query behavior, Grafana access, safe queries, and trace links. |
+| [`09-dashboards-alerts-slos.md`](09-dashboards-alerts-slos.md) | Dashboard map, variables, drill-downs, PromQL/LogQL, alerts, and SLOs. |
+| [`10-testing-release-operations.md`](10-testing-release-operations.md) | Test levels, failure tests, performance, cardinality, releases, and support. |
+| [`11-deployment-runbooks.md`](11-deployment-runbooks.md) | Local, Docker, CI, and production deployment checks plus common incidents. |
+| [`12-configuration-reference.md`](12-configuration-reference.md) | Complete YAML schema, environment variables, precedence, defaults, and validation. |
+
+### Source basis
+
+| File | Use it for |
+| --- | --- |
+| [`13-source-notes.md`](13-source-notes.md) | Pi, OpenTelemetry, and Grafana assumptions used by this reference set. |
+
+## Related task-oriented documentation
+
+- [`../configuration.md`](../configuration.md) — quick project configuration.
+- [`../extension-integration.md`](../extension-integration.md) — versioned integration API for orchestrators and other Pi extensions.
+- [`../validation-flow.md`](../validation-flow.md) — secret-safe Grafana and `/obs` troubleshooting.
+- [`../compatibility-matrix.md`](../compatibility-matrix.md) — currently tested versions.
+- [`../../examples/README.md`](../../examples/README.md) — safe use of the shipped YAML examples.
+- [`../../SECURITY.md`](../../SECURITY.md) — package trust and vulnerability reporting.
+
+## Core design
+
+```text
+Pi Agent
+  └── ObservMe Pi Extension
+        ├── OTEL Traces  ──► OTEL Collector ──► Tempo
+        ├── OTEL Metrics ──► OTEL Collector ──► Prometheus / Mimir
+        └── OTEL Logs    ──► OTEL Collector ──► Loki
+
+Grafana
+  ├── Tempo datasource
+  ├── Loki datasource
+  └── Prometheus/Mimir datasource
+```
+
+## Reference principles
+
+1. **OTLP-first.** ObservMe emits OpenTelemetry traces, metrics, and logs.
+2. **No durable local telemetry storage.** Only bounded in-memory queues are allowed.
+3. **Fail open.** Observability failure must not stop Pi.
+4. **Privacy by default.** Prompt, response, thinking, tool, Bash, and path capture starts disabled.
+5. **Pi-native and OTEL-compatible semantics.** ObservMe uses `observme.*`, `pi.*`, and applicable official `gen_ai.*` attributes.
+6. **Agent lineage by design.** Parent and child telemetry uses `pi.agent.*` lineage and W3C context where an ObservMe-aware launcher can propagate it.
+7. **Low-cardinality metrics.** Workflow, session, agent, trace, span, entry, and tool-call identifiers belong on traces and logs, not metric labels.
+8. **Collector recommended.** Direct-to-backend export is for development or constrained environments.
+9. **Backend-neutral.** Tempo, Loki, and Prometheus/Mimir are reference backends rather than hard runtime dependencies.
+
+## How to interpret this reference
+
+Some documents define reserved or future-facing contracts in addition to currently emitted behavior. Use the telemetry catalog in [`../../README.md#available-telemetry`](../../README.md#available-telemetry) to distinguish live signals from names marked reserved or registered but not yet recorded. If a detailed reference conflicts with the current user guides, report the discrepancy and prefer the current user-facing behavior until the reference is corrected.

package/{ObservMe-Production-Docs → docs/reference}/05-otel-pipeline-and-collector.md

@@ -121,6 +121,11 @@ service:
 This configuration routes traces to Tempo, logs to Loki, and metrics to a Prometheus-compatible remote write endpoint such as Mimir. Use a Collector distribution that contains every configured component. The minimal debug example works with the core Collector, while `prometheusremotewrite`, `probabilistic_sampler`, and `tail_sampling` are commonly deployed from the Collector Contrib distribution or a vendor distribution such as Grafana Alloy.
 
 ```yaml
+# Production-oriented Collector reference for Tempo, Loki, and Mimir.
+# Verify that your Collector distribution contains every configured component,
+# replace backend endpoints/security for your deployment, and never add raw
+# content or high-cardinality execution identifiers to metric labels.
+# Guide: examples/README.md; design: docs/reference/05-otel-pipeline-and-collector.md.
 extensions:
   health_check:
     endpoint: 0.0.0.0:13133

package/{ObservMe-Production-Docs → docs/reference}/07-extension-implementation-blueprint.md

@@ -424,7 +424,15 @@ Rules:
 - Rate limit export
 - Confirm with user before sending historical content
 
-## 13. Versioning
+## 13. Inter-extension integration
+
+Other Pi extensions must not import ObservMe's private telemetry session or `src/pi/subagent-spawn.ts` directly. ObservMe exposes a versioned request/response API through Pi's shared `pi.events` bus and the `@senad-d/observme/integration` package export.
+
+The public API covers current context plus subagent spawn, launcher completion/failure, wait, and join transitions. `startSubagent()` returns the sanitized process environment that the launcher passes to the child. Runtime negotiation lets an orchestrator remain optional when ObservMe is absent or inactive.
+
+See [`../extension-integration.md`](../extension-integration.md) for the public contract and [`../../examples/integrations/subagent-runner.ts`](../../examples/integrations/subagent-runner.ts) for a transport-agnostic consumer example.
+
+## 14. Versioning
 
 Extension versioning:
 
@@ -432,16 +440,19 @@ Extension versioning:
 MAJOR.MINOR.PATCH
 ```
 
-Breaking semconv changes require MAJOR.
+Breaking semantic-convention changes require MAJOR. Incompatible inter-extension API changes require a newly negotiated integration API version.
 
-## 14. Build Artifact
+## 15. Package surface
 
-Recommended output:
+The published Pi package includes:
 
 ```text
-dist/observme.js
-dist/observme.d.ts
+src/extension.ts                         # Pi extension entry
+src/integration.ts                       # public inter-extension types and discovery helper
+skills/observme-docs/SKILL.md            # progressive documentation routing
+docs/extension-integration.md            # integration contract
+examples/integrations/subagent-runner.ts
 examples/observme.yaml
 examples/collector.yaml
-dashboards/*.json
+dashboards/*
 ```

package/{ObservMe-Production-Docs → docs/reference}/pi-session-format.md

@@ -424,4 +424,4 @@ Key methods for working with sessions programmatically.
 - `getSessionDir()` - Session storage directory
 - `getSessionId()` - Session UUID
 - `getSessionFile()` - Session file path (undefined for in-memory)
-- `isPersisted()` - Whether session is saved to disk
+- `isPersisted()` - Whether session is saved to disk

package/docs/review-validation.md

@@ -53,7 +53,7 @@ Use this checklist when a review, release candidate, or local operator needs cov
 | `npm run smoke:handlers` | Yes | Dependencies installed. | None. Uses the local Pi API harness. | No tracked writes. | Registers the extension and executes one command plus the first agent-facing tool when present. |
 | `npm run smoke:pi-lifecycle` | Yes | Dependencies installed. | None. Uses explicit loopback-only, telemetry-disabled config. | No tracked writes. | Registers `session_start`/`session_shutdown` and confirms lifecycle status cleanup without Collector, Grafana, or credentials. |
 | `npm run smoke:pi-runtime` | Yes when the `pi` CLI is installed in the test image | A working local `pi` executable, dependencies installed, and permission to spawn a local child process. | No credentials. It deletes inherited `OBSERVME_*` values and uses a deterministic loopback backend. | Creates a temporary project and extension files under the OS temp directory, then removes them; local loopback server only. | Real Pi RPC extension load, `/obs` discovery/routing, reload/new-session replacement, and credential-free event-shape smoke coverage. |
-| `npm run smoke:packaged` | Usually release/local only | `npm` available and package dependencies resolvable for a temporary install. | May need npm registry/cache access to install package dependencies; no project credentials. | Runs `npm pack`, creates a temporary project under the OS temp directory, installs the tarball with `--ignore-scripts --no-audit --no-fund --package-lock=false`, and removes the temp directory. | Packaged install layout and declared Pi extension files in the installed package. |
+| `npm run smoke:packaged` | Usually release/local only | `npm` available and package dependencies resolvable for a temporary install. | May need npm registry/cache access to install package dependencies; no project credentials. | Runs `npm pack`, creates a temporary project under the OS temp directory, installs the tarball with `--ignore-scripts --no-audit --no-fund --package-lock=false`, and removes the temp directory. | Packaged install layout plus declared Pi extension and skill resources in the installed package. |
 | `npm run test:integration:collector` | No | Docker daemon available; Collector image `OBSERVME_COLLECTOR_IMAGE` or `otel/opentelemetry-collector-contrib:0.104.0` pullable or cached. | Docker image pull may require network; no Grafana/model credentials. | Starts a temporary Collector container with loopback-published ports and stops it in test cleanup. | OTLP export to Collector debug pipeline for representative traces, metrics, and logs. |
 | `npm run test:integration:grafana-stack` | No | Docker Compose available; `observability-stack/docker-compose.yml` and test overlay available; required Grafana/Tempo/Loki/Prometheus images pullable or cached. | Docker image pull may require network; no external Grafana credentials. Test-created local Grafana admin secret is synthetic. | Creates isolated Docker Compose project/networks/containers. May create `observability-stack/secrets/grafana_admin_password` when missing and removes the test-created file during cleanup; also creates temporary command-project files under the OS temp directory. If interrupted, run `docker compose` with the printed project name or remove stale `observme-grafana-it-*` resources. | Live local stack ingestion, datasource queries, `/obs` query commands, and dashboard provisioning imports. |
 | `npm run validate:grafana-obs` | No | Running Pi session with ObservMe loaded, reachable Collector/Grafana stack, and recent telemetry. See `docs/validation-flow.md`. | Requires Grafana read credentials from environment variables (`OBSERVME_GRAFANA_TOKEN` or username/password), datasource UIDs, and `OBSERVME_VALIDATION_SESSION_ID`; may access the configured Grafana URL. | Read-only against the configured stack; no file writes expected. Keep terminal output sanitized and omit secrets. | Operator-facing validation that Grafana has ObservMe data and representative `/obs` commands work against the same stack. |

package/docs/validation-flow.md

@@ -1,6 +1,6 @@
 # ObservMe Grafana + `/obs` validation flow
 
-Use this secret-safe flow when Grafana shows ObservMe data but `/obs` commands appear broken. It classifies the failure as ingestion, labels, Grafana auth/query access, local TLS/DNS, Pi command registration, or session state.
+Use this secret-safe flow when Grafana shows ObservMe data but `/obs` commands appear broken. It classifies the failure as ingestion, labels, Grafana auth/query access, local TLS/DNS, Pi command registration, or session state. For first-time setup, read the [configuration guide](configuration.md) and [example guide](../examples/README.md) first.
 
 ## Preconditions
 
@@ -115,3 +115,10 @@ node --test test/dashboards.test.mjs test/exporter-failure.test.ts test/chaos-fa
 | `/obs command path` | Pi command state, session state, or command query mismatch | Re-run the Pi commands in step 1; then run `npm run smoke:pi-runtime` to isolate real Pi command registration. |
 
 Release validation should not be considered complete while any step fails.
+
+## Related documentation
+
+- [Documentation index](README.md)
+- [Query and Grafana integration](reference/08-query-grafana-integration.md)
+- [Deployment runbooks and common incidents](reference/11-deployment-runbooks.md)
+- [Dashboards, alerts, and SLOs](reference/09-dashboards-alerts-slos.md)

package/examples/README.md

@@ -0,0 +1,52 @@
+# ObservMe examples
+
+The npm package ships configuration examples and an extension-integration example. They are starting points, not credential stores or a complete orchestration product. Copy only what you need, review every endpoint and lifecycle transition, and keep tokens, passwords, and hash salts in environment variables or a trusted project `.env` file.
+
+## `observme.yaml`
+
+[`observme.yaml`](observme.yaml) is a privacy-preserving local-development profile for the repository's supported Grafana stack:
+
+- OTLP/HTTP exports to `http://localhost:4318`.
+- Grafana queries use `https://observability.local`.
+- Local self-signed TLS and IPv4 preference are enabled for that profile.
+- Prompt, response, thinking, tool, Bash, and path capture remain disabled.
+- Redaction remains enabled and unsafe capture remains disabled.
+
+To use it in a trusted project:
+
+1. Copy it to `<project>/<CONFIG_DIR_NAME>/observme.yaml` (normally `.pi/observme.yaml`).
+2. Set Grafana and OTLP credentials through environment variables or a trusted project `.env`.
+3. Restart Pi so the session-scoped configuration is reloaded.
+4. Run `/obs status` and `/obs health`.
+
+Read [`../docs/configuration.md`](../docs/configuration.md) for the quick guide and [`../docs/reference/12-configuration-reference.md`](../docs/reference/12-configuration-reference.md) for every setting.
+
+## `collector.yaml`
+
+[`collector.yaml`](collector.yaml) is a production-oriented Collector reference for a Grafana stack:
+
+- traces are exported to Tempo;
+- logs are exported to Loki;
+- metrics are remote-written to Mimir;
+- high-cardinality workflow, agent, session, and spawn attributes are removed from metrics;
+- accidental content attributes are removed from logs as defense in depth.
+
+The example uses Collector components commonly provided by the Collector Contrib distribution. Verify that your deployed distribution includes every receiver, processor, and exporter, then replace backend endpoints and security settings for your environment.
+
+Read [`../docs/reference/05-otel-pipeline-and-collector.md`](../docs/reference/05-otel-pipeline-and-collector.md) for pipeline design and [`../docs/reference/11-deployment-runbooks.md`](../docs/reference/11-deployment-runbooks.md) for deployment and incident checks.
+
+## `integrations/subagent-runner.ts`
+
+[`integrations/subagent-runner.ts`](integrations/subagent-runner.ts) demonstrates how another Pi extension can wrap any child transport with ObservMe's versioned integration API. The transport interface can represent a local subprocess, Pi RPC, tmux, SSH, a container, a queue, or another process manager.
+
+The generic adapter records spawn, launcher success/failure, wait, join, cancellation, timeout, and failure propagation while passing the returned environment to the transport unchanged. It does not prescribe task delivery, process management, result encoding, concurrency, retries, durable state, or child-ID handshake.
+
+Read [`../docs/extension-integration.md`](../docs/extension-integration.md) before adapting it and [`../docs/agent-subagent-observability-requirements.md`](../docs/agent-subagent-observability-requirements.md) for the complete orchestration contract.
+
+## Safety notes
+
+- Do not place real secrets directly in either YAML file.
+- Keep content capture disabled unless there is an explicit, reviewed need.
+- Keep redaction enabled for captured content and configure `OBSERVME_HASH_SALT`.
+- Do not promote session, workflow, agent, trace, span, entry, or tool-call IDs to Prometheus labels.
+- Use insecure transport or certificate verification bypass only for controlled local development.

package/examples/collector.yaml

@@ -1,3 +1,8 @@
+# Production-oriented Collector reference for Tempo, Loki, and Mimir.
+# Verify that your Collector distribution contains every configured component,
+# replace backend endpoints/security for your deployment, and never add raw
+# content or high-cardinality execution identifiers to metric labels.
+# Guide: examples/README.md; design: docs/reference/05-otel-pipeline-and-collector.md.
 extensions:
   health_check:
     endpoint: 0.0.0.0:13133