observme-docs

name	observme-docs
description	Answers questions about the ObservMe Pi extension, including installation, /obs commands, configuration, privacy and content capture, OpenTelemetry export, Grafana dashboards, metrics, traces, logs, troubleshooting, compatibility, development, and parent/subagent lineage. Use whenever a user asks how ObservMe works, how to set it up or operate it, or where its behavior is documented.

ObservMe documentation

Use the packaged ObservMe documentation for focused answers and the packaged implementation for exact current behavior. Runtime code, schemas, command registries, semantic-convention constants, and shipped configuration are the source of truth. Do not modify files unless the user separately asks for changes.

Resolve packaged paths

This skill and its references ship in the same installed Pi package. Do not resolve paths against the caller's working directory or assume that an ObservMe repository checkout exists.

1. Use the absolute path from which Pi loaded this SKILL.md as SKILL_FILE.
2. Set SKILL_DIR to the directory containing SKILL_FILE.
3. Set PACKAGE_ROOT to the absolute path obtained by resolving ../.. from SKILL_DIR.
4. Treat every package:<path> entry below as relative to PACKAGE_ROOT, and pass the resolved absolute path to file tools. Never pass the literal package: prefix.

For example, package:docs/configuration.md resolves to <PACKAGE_ROOT>/docs/configuration.md. Start with package:docs/README.md only for broad or unclear requests. For a specific request, read the routed document directly. If a routed file is absent, report that the installed package is incomplete; do not silently substitute a similarly named file from the current project.

The repository-only observability-stack/, tests, scripts, and package lock are not shipped in npm. Do not claim to inspect those paths from an installed package. Use the packaged local-profile documentation/examples, and point repository-stack implementation questions to the source checkout.

Route questions

User intent	Primary document	Optional deeper reference
Overview, capabilities, install, quick start, command list, telemetry catalog	package:README.md	package:docs/reference/01-requirements-and-scope.md
Project config creation, what to edit, credentials, precedence	package:docs/configuration.md	package:docs/reference/12-configuration-reference.md
Exact config key, environment variable, validation rule, safe default	package:docs/reference/12-configuration-reference.md	package:src/config/schema.ts, package:src/config/defaults.ts, package:src/config/load-config.ts, and package:src/config/validate.ts
Generated project starter	package:docs/configuration.md	package:src/config/bootstrap-project-config.ts
Privacy defaults, prompt/response/tool/Bash capture, redaction, hashing, paths, TLS	package:SECURITY.md	package:docs/reference/06-security-privacy-redaction.md
Metrics, spans, log events, attributes, labels, cardinality	package:README.md, section Available Telemetry	package:docs/reference/04-telemetry-semantic-conventions.md
OTLP endpoints, Collector processors/exporters, Tempo, Loki, Prometheus, Mimir	package:examples/README.md	package:docs/reference/05-otel-pipeline-and-collector.md
Local example configuration	package:examples/observme.yaml	package:docs/configuration.md
Production Collector example	package:examples/collector.yaml	package:docs/reference/05-otel-pipeline-and-collector.md
/obs status, health, session, cost, trace, link, tools, errors, logs, agents, backfill	package:README.md, section Commands	package:docs/reference/08-query-grafana-integration.md

Implementation verification map

Read implementation only when the user asks for exact/current behavior, the documentation is ambiguous, or drift is suspected. Read the smallest owning slice:

Behavior	Owning packaged source
/obs subcommand names and dispatch	package:src/commands/obs.ts; then the matching <PACKAGE_ROOT>/src/commands/obs-*.ts file for syntax/query/output
Config keys and types	package:src/config/schema.ts
Defaults	package:src/config/defaults.ts
Environment mappings and precedence	package:src/config/load-config.ts
Validation and production safety rules	package:src/config/validate.ts
Telemetry names	package:src/semconv/metrics.ts, package:src/semconv/spans.ts, package:src/semconv/attributes.ts
Live versus merely registered telemetry	package:src/pi/handler-runtime.ts plus the relevant <PACKAGE_ROOT>/src/pi/event-handlers/*.ts or package:src/pi/subagent-spawn.ts recording point
Content-capture behavior	package:src/privacy/content-capture.ts, package:src/privacy/redact.ts, package:src/privacy/hash.ts
Integration API types and runtime validation	package:src/integration.ts, package:src/pi/integration-api.ts, package:src/pi/subagent-spawn.ts
Pi capability policy	package:src/pi/compatibility.ts

Answer workflow

1. Classify the question using the routing table.
2. Read the primary document only as far as needed, following necessary Markdown links.
3. For exact, disputed, implementation-level, or version-sensitive behavior, verify the smallest source slice from the implementation map.
4. Answer directly and cite the relevant package-relative document path and heading. Include a source path when it resolved ambiguity.
5. If source and documentation conflict, say so, follow the implementation behavior, and identify the documentation as drift. Never prefer a design note over live code.
6. If the user asks only where something is documented, return the shortest matching path and heading.
7. Distinguish live telemetry from reserved names or instruments that are registered without measurements.

Current limitations that answers must preserve

• /obs backfill replays bounded current-session OTEL log records after confirmation; it does not reconstruct historical spans or metrics.
• YAML environment and tenant do not synchronize their matching resource attributes; set those attributes too. The corresponding environment overrides map both values.
• workflow.maxDepthWarning clamps the subagent_depth metric label rather than emitting a warning; workflow.maxFanoutWarning has no current live read after loading.
• metrics.labels is validated but current metric recorders do not apply configured labels.
• capture.filePaths is accepted and displayed but has no direct live recording point. privacy.pathMode still controls absolute paths embedded in other enabled content, and pathMode: full preserves them regardless of capture.filePaths.
• The redaction helper has an injectable PII stage, but current live configuration does not supply or enable a PII detector. Do not claim live PII removal.
• observme_agent_lifetime_duration_ms, gen_ai.client.token.usage, and gen_ai.client.operation.duration are registered without current measurements.
• session.error plus standalone pi.model.change and pi.thinking.change spans are reserved rather than live signals; session.named is emitted from session_info_changed.
• Arbitrary subagent launchers are not automatically correlated; full lineage requires an ObservMe-aware launcher using the integration API and returned environment.

Safety and accuracy

• Never request, print, or repeat Grafana tokens, OTLP tokens, passwords, hash salts, raw prompts, raw commands, or private paths.
• Recommend process environment variables or a trusted project .env for secrets; do not recommend literal credentials in YAML.
• Keep content capture disabled by default. For opt-in capture, keep redaction enabled and require the tenant hash salt.
• Warn that privacy.pathMode: full can expose paths embedded in any enabled content field.
• Never suggest workflow, session, agent, trace, span, entry, spawn, or tool-call IDs as Prometheus labels.
• Do not invent commands, options, configuration keys, telemetry names, supported versions, or remediation steps. If packaged documentation and source do not answer the question, state that limitation and point to the closest reference.