# Provon Documentation

> Provon turns real agent traces into actionable fixes, reusable Knowledge, reviewed Datasets, and
> model improvements. Every output remains linked to the evidence that motivated it.

## Get Started

- [Documentation home](./README.md): Task-oriented map of the complete documentation set.
- [What Provon does](./get-started/index.md): Capabilities, boundaries, and improvement loops.
- [Install Provon](./get-started/install.md): Hosted, self-hosted installer, and source development.
- [Workbench onboarding](./get-started/workbench-onboarding.md): Built-in Workspace, Connect, and Discover flow.
- [Quickstart](./get-started/quickstart.md): Capture evidence and review the first Finding.
- [Core concepts](./get-started/core-concepts.md): Traces, Findings, Knowledge, Datasets, Gateway, and Models.
- [Choose a capture path](./get-started/choose-capture-path.md): Gateway, OTLP, and transcript sync.
- [Repair loop](./get-started/repair-loop.md): Move from trace evidence to repair and verification.
- [Model improvement loop](./get-started/model-improvement-loop.md): Collect, train, deploy, and observe.
- [Troubleshooting](./get-started/troubleshooting.md): Common setup and workflow failures.

## Tracing

- [Tracing overview](./tracing/index.md): Capture paths, evidence model, and documentation path.
- [Tracing quickstart](./tracing/quickstart.md): Send, inspect, export, and diagnose one trace.
- [OpenTelemetry](./tracing/opentelemetry.md): SDK, Collector, and OTLP/HTTP configuration.
- [Agent transcripts](./tracing/agent-transcripts.md): Inspect and sync Claude Code, Codex, and Pi sessions.
- [Claude Code](./tracing/claude-code.md): Native Claude Code trace export.
- [Codex](./tracing/codex.md): Native Codex trace export.
- [Trace model](./tracing/trace-model.md): Boundaries, identity, spans, and causality.
- [Diagnosis-ready tracing](./tracing/best-practices.md): Evidence quality guidance.
- [Multi-agent tracing](./tracing/multi-agent.md): Participants, handoffs, and distributed context.
- [Explore traces](./tracing/explore.md): Workbench investigation workflow.
- [Production tracing](./tracing/production.md): Sampling, batching, privacy, and retention.
- [Telemetry architecture](./tracing/telemetry-architecture.md): Internal storage and query paths.

## Findings

- [Findings](./findings/index.md): Rules, Runs, Findings, occurrences, review, and resolution.
- [Findings quickstart](./findings/quickstart.md): First trace-to-published-Finding flow.
- [Diagnostic rules](./findings/rules.md): Built-in Rules, thresholds, signal overrides, and adjudication.
- [Repair handoff](./findings/repair-handoff.md): Issue-tracker work items and resolution sync.
- [Findings troubleshooting](./findings/troubleshooting.md): No findings, false positives, and work-item errors.

## Knowledge

- [Knowledge](./knowledge/index.md): Learning Goals, extraction, review, and evidence lifecycle.
- [Knowledge quickstart](./knowledge/quickstart.md): Create your first Learning Goal and extracted item.
- [Knowledge best practices](./knowledge/best-practices.md): Write better goals, review items, and consume Knowledge.
- [Knowledge troubleshooting](./knowledge/troubleshooting.md): No items, low confidence, and skipped extractions.

## Datasets

- [Datasets](./datasets/index.md): Objectives, Examples, provenance, and exports.
- [Dataset quickstart](./datasets/quickstart.md): Create, collect, review, and consume a Dataset.
- [Dataset best practices](./datasets/best-practices.md): Review checklists, tag conventions, and coverage.
- [Dataset formats](./datasets/formats.md): Training and evaluation output formats with examples.
- [Dataset troubleshooting](./datasets/troubleshooting.md): Fix missing Examples and export errors.

## AI Gateway

- [Gateway overview](./ai-gateway/index.md): Boundary, objects, request lifecycle, and task map.
- [Gateway quickstart](./ai-gateway/quickstart.md): Connect a provider and verify a trace.
- [SDK integrations](./ai-gateway/integrations.md): OpenAI-compatible clients and frameworks.
- [Gateway migration](./ai-gateway/migration.md): Compatibility, canary rollout, and rollback.
- [Model providers](./ai-gateway/providers.md): Managed, BYOK, custom, and local targets.
- [Routing](./ai-gateway/routing.md): Model Policies, Auto Router, retries, and fallback.
- [Limits and guardrails](./ai-gateway/limits-and-guardrails.md): Limits and guardrails.
- [Gateway tracing](./ai-gateway/tracing.md): Trace Capture and model-attempt semantics.
- [Production Gateway](./ai-gateway/production.md): Security, rollout, and rollback.
- [Gateway troubleshooting](./ai-gateway/troubleshooting.md): Request-path failure isolation.
- [Realtime Gateway](./ai-gateway/realtime.md): WebSocket and realtime inference endpoints.

## AI Models

- [AI Models](./ai-models/index.md): Local model and fine-tuning lifecycle.
- [Self-hosted models](./ai-models/self-hosted-models.md): Import, download, and serve models.
- [Model fine-tuning](./ai-models/fine-tuning.md): Jobs, checkpoints, lineage, and export.
- [AI Models quickstart](./ai-models/quickstart.md): First local model import and Gateway deployment.
- [AI Models troubleshooting](./ai-models/troubleshooting.md): Common model runtime and training failures.

## Self-Hosting

- [Self-hosting overview](./self-hosting/index.md): Runtime choice and production gate.
- [Architecture](./self-hosting/architecture.md): Logical planes, storage, networks, and failures.
- [Node](./self-hosting/node.md): Docker and source deployment.
- [Cloudflare](./self-hosting/cloudflare.md): Split Worker deployment.
- [Configuration](./self-hosting/configuration.md): Runtime settings and bindings.
- [Security](./self-hosting/security.md): Trust, credentials, privacy, and release checks.
- [Operations](./self-hosting/operations.md): Health, backup, upgrades, capacity, and incidents.
- [Upgrading](./self-hosting/upgrading.md): Self-hosted upgrade guide, compatibility policy, and matrix.

## CLI

- [CLI overview](./cli/index.md): Installation, command groups, and output contract.
- [CLI authentication](./cli/authentication.md): Profiles, credentials, projects, and origins.
- [Workspace CLI](./cli/workspace.md): Organizations, projects, members, and invitations.
- [API keys CLI](./cli/api-keys.md): Project API keys and usage policies.
- [Tracing CLI](./cli/traces.md): Query, inspect, summarize, and export traces.
- [Transcripts CLI](./cli/transcripts.md): Local browser viewer for agent transcripts.
- [Sync CLI](./cli/sync.md): Upload persisted transcripts as traces.
- [CLI diagnosis](./cli/diagnose.md): Diagnose local evidence without persistence.
- [Findings CLI](./cli/findings.md): Review, hand off, and manage Findings.
- [Knowledge CLI](./cli/knowledge.md): Materialize and search project Knowledge.
- [Datasets CLI](./cli/datasets.md): Datasets and Examples.
- [Gateway CLI](./cli/gateway.md): Provider keys, routing, guardrails, and observability.
- [Connectors CLI](./cli/connectors.md): Project connector integrations.
- [Models CLI](./cli/models.md): Install and serve local models.
- [Ingest CLI](./cli/ingest.md): Unified agent-session ingest (live hooks and sync).
- [Ingest Hooks CLI](./cli/install-hooks.md): Install and manage live trace hooks.

## API Reference

- [API overview](./api/index.md): Surfaces, base URLs, capabilities, and conventions.
- [Authentication](./api/authentication.md): API keys, sessions, identity providers, and secrets.
- [Gateway API](./api/gateway.md): Inference, discovery, streaming, and errors.
- [OTLP/HTTP API](./api/otlp.md): Telemetry ingest and retry semantics.
- [Trace Read API](./api/traces.md): Traces, spans, conversations, users, and attachments.
- [Telemetry Read API](./api/telemetry.md): Logs and metrics.
- [Tracing attributes](./api/tracing-attributes.md): Normalized OTel and GenAI evidence fields.
- [Findings API](./api/findings.md): Rules, Runs, Findings, backfills, and handoff.
- [Knowledge API](./api/knowledge.md): Settings, Learning Goals, items, and backfills.
- [Datasets API](./api/datasets.md): Datasets and directly owned Examples.
- [Models API](./api/models.md): Model runtime lifecycle.
- [Fine-Tuning API](./api/fine-tuning.md): Jobs, configs, checkpoints, lineage, and export.
- [Model Pricing API](./api/model-pricing.md): Price matching, tiers, and overrides.
- [Dashboards API](./api/dashboards.md): Dashboard definitions and streaming queries.
- [Workspace API](./api/workspace.md): Organizations, projects, API keys, Gateway settings, and integrations.
- [Playground API](./api/playground.md): Model comparison Playgrounds and Runs.

## Repository

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