# Provon Documentation

> Provon is the evidence layer for self-improving agent systems. It turns production traces into
> high-confidence Findings, hands repair-ready context to GitHub, and tracks the external outcome.

## Start Here

- [Documentation home](./README.md): Task-oriented index and the core trace-to-repair loop.
- [Quickstart](./quickstart.md): Start Provon, capture a trace, enable diagnostics, and hand off a Finding.
- [Tracing quickstart](./tracing-quickstart.md): Send, inspect, export, and diagnose one complete agent trace with the CLI.
- [Tracing](./tracing.md): Choose a capture path and understand the evidence flow.
- [Findings](./findings.md): Rule, Run, Finding semantics, review lifecycle, and diagnostics API.

## Tracing

- [Tracing overview](./tracing.md): Capture-path decision, evidence model, verification, and recommended documentation path.
- [Tracing quickstart](./tracing-quickstart.md): Direct OTLP/HTTP first trace, verification, CLI inspection, export, and source-based diagnosis.
- [OpenTelemetry setup](./opentelemetry.md): OTLP/HTTP configuration, SDK examples, Collector setup, and first-trace verification.
- [Agent transcript sync](./agent-transcripts.md): Project Claude Code, Codex, and Pi transcripts into canonical OTel spans.
- [Trace model and instrumentation](./tracing-model.md): Trace boundaries, conversation identity, span structure, and causal topology.
- [Tracing attribute reference](./tracing-attributes.md): Core OTel, GenAI, user, tool, retrieval, content, usage, cost, and error fields.
- [Diagnosis-ready tracing](./tracing-best-practices.md): Practical guidance for complete, stable, causal, and privacy-bounded evidence.
- [Multi-agent and distributed tracing](./tracing-multi-agent.md): Physical run isolation, conversation grouping, participant attribution, handoffs, and distributed context.
- [Explore traces](./trace-explorer.md): Workbench trace, conversation, user, search, and causal investigation workflow.
- [Tracing CLI](./tracing-cli.md): API-backed list, search, inspect, summarize, export, and source-based diagnosis commands.
- [Trace read API](./trace-api.md): Trace, span, statistics, conversation, user, pagination, and attachment endpoints.
- [Trace diagnosis with CLI](./trace-diagnosis.md): Trace sources, built-in Rules, deterministic mode, and hash-bound Agent adjudication.
- [Production tracing](./tracing-production.md): Sampling, batching, delivery, privacy, payload retention, and release checks.
- [OTLP/HTTP API](./otlp-api.md): Ingest endpoints, authentication, encodings, asynchronous acceptance, status codes, retries, and limits.

## AI Gateway

- [Gateway overview](./gateway.md): Gateway boundary, core model, request path, and documentation map.
- [Gateway quickstart](./gateway-quickstart.md): Connect a provider, send a request, and verify its trace.
- [Gateway migration](./gateway-migration.md): Compatibility inventory, credential separation, client migration, diagnostic identity, canary rollout, and rollback.
- [Gateway SDK integrations](./gateway-integrations.md): OpenAI-compatible client configuration, diagnostic context, native Messages requests, and migration checklist.
- [Model providers](./model-providers.md): Managed, BYOK, custom, and local/private Gateway targets, Provider Keys, and model mappings.
- [Gateway API](./gateway-api.md): Base URLs, authentication, model values, request context, discovery, endpoints, and errors.
- [Gateway routing](./gateway-routing.md): Direct providers, Model Policies, Auto Router, Provider Keys, retries, and fallback.
- [Gateway evidence](./gateway-observability.md): Trace Capture modes, conversation identity, trace semantics, and Finding inputs.
- [Gateway governance](./gateway-governance.md): API-key request, token, and cost limits plus built-in guardrails.
- [Production Gateway](./gateway-production.md): Compatibility gates, rollout stages, security, evidence policy, and rollback.
- [Gateway troubleshooting](./gateway-troubleshooting.md): Authentication, model resolution, provider attempts, policy rejections, streaming, and missing-trace diagnosis.

## Configuration

- [Connectors](./connectors.md): GitHub repair handoff and Automation destinations.
- [Capabilities](./capabilities.md): Current product capabilities and explicit product boundary.

## Self-hosting

- [Self-hosting overview](./self-hosting.md): Runtime choice, operator responsibilities, documentation path, and production gate.
- [Self-hosting architecture](./self-hosting-architecture.md): Logical planes, Node and Cloudflare mappings, data flow, storage, networking, and failures.
- [Node self-hosting](./self-hosting-node.md): Docker and source deployment, storage, reverse proxy, verification, and scaling constraints.
- [Cloudflare self-hosting](./self-hosting-cloudflare.md): Resource provisioning, bindings, secrets, deployment order, and surface verification.
- [Self-hosting configuration](./self-hosting-configuration.md): Runtime, storage, identity, Connector, OTLP, retention, and local-model settings.
- [Self-hosting security](./self-hosting-security.md): Trust boundary, network controls, credential custody, evidence privacy, and release gate.
- [Self-hosting operations](./self-hosting-operations.md): Health, monitoring, backup, restore, upgrade, capacity, retention, and incident procedures.

## Operations

- [Telemetry architecture](./telemetry.md): Internal ingestion, storage, summaries, isolation, retention, and failure semantics.
- [Troubleshooting](./troubleshooting.md): Startup, ingest, Gateway, diagnostics, and GitHub failure isolation.

## Repository

- [Project README](../README.md): Product overview and condensed setup.
- [Contributing](../CONTRIBUTING.md): Development setup, validation, and deployment commands.