# Workbench onboarding

The first time you open the Provon Workbench you see a three-step onboarding flow:
**Workspace → Connect → Discover**. This page explains each step and how it maps to the
[Quickstart](./quickstart.md).

## Before you start

Make sure you can reach a Provon deployment:

- **Hosted**: open `https://app.provon.dev` and sign in.
- **Self-hosted**: run the installer, start the server, and open the Workbench URL printed in the
  logs. See [Install Provon](./install.md).

## Step 1: Workspace

Create an organization and a project.

- An **organization** holds your team and billing settings.
- A **project** holds traces, Findings, Rules, Datasets, and Knowledge.

The Workbench suggests placeholder names. You can rename them later in **Organization settings** and
**Project settings**.

After you confirm the names, Provon creates the project and generates a project API key. Copy it
immediately — it is shown only once.

## Step 2: Connect

Choose how agent evidence will reach Provon. The Workbench shows three options:

1. **Use a coding agent** (recommended for Claude Code, Codex, or Cursor): copy the project-specific
   setup prompt and hand it to your coding agent. The prompt asks the agent to inspect the codebase,
   recommend the best capture path, and implement it using your repository conventions.
2. **AI Gateway**: copy a curl or SDK snippet and send one OpenAI-compatible request.
3. **OpenTelemetry**: copy exporter environment variables and run your already-instrumented agent.

You can also connect later from **API keys**, **Providers**, or **Project settings**. See
[Choose a capture path](./choose-capture-path.md) for a detailed comparison.

## Step 3: Discover

After the first trace arrives, click **Analyze latest conversation**. Provon runs the enabled
diagnostic Rules against the most recent conversation and shows any produced Findings.

Discover is the fastest way to confirm that:

- traces are reaching the right project;
- conversation identity is stable;
- the trajectory can be reconstructed;
- Rules produce reviewable output for your workload.

If no Finding appears, that can be correct. Healthy conversations and weak candidates are
intentionally excluded. See [Auto-diagnose produces no Findings](./troubleshooting.md#auto-diagnose-produces-no-findings).

## After onboarding

Once onboarding is complete:

- Open **Traces** to inspect the full trajectory.
- Open **Rules** to turn on **Auto-diagnose** so future conversations are analyzed automatically.
- Open **Findings** to confirm, dismiss, or hand off supported problems.
- Open **Connectors** to link an issue tracker for repair handoff.

Follow the [Quickstart](./quickstart.md) for the complete trace-to-Finding workflow, or continue
with the [repair loop](./repair-loop.md) and [model improvement loop](./model-improvement-loop.md).