> ## Documentation Index
> Fetch the complete documentation index at: https://overmind-b84ae13c-codex-workshop-queue-capacity.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent & Capabilities

> How Overmind models your agent — one graph per project, made of capabilities discovered by a local scan, described by agent-authored cards, and confirmed by telemetry.

export const Ascii = ({lines, cols}) => <div className="om-ascii-frame" style={{
  "--om-ascii-cols": cols || Math.max(...lines.map(line => line.length))
}}>
    <pre className="om-ascii">{lines.join("\n")}</pre>
  </div>;

Your **agent** in Overmind is the product itself: one per project, mapped as a graph of **capabilities**. A capability is one purpose the product serves — triage tickets, answer from the knowledge base, resolve a dispute. Each capability record joins two sides: static structure from your repository (entry points, prompts, tools, modes, call edges) and runtime behaviour from telemetry (traces, task executions, live scores). Everything else on the platform hangs off capabilities — traces bind to one, datasets are aligned to one, eval sets belong to one, optimisation runs edit a capability's code, and trained models are benchmarked against the model a capability runs in production.

## How capabilities get into Overmind

<Ascii
  cols={74}
  lines={[
"╔══════════════════════╗                               ╔═ Overmind ══════╗",
"║      Local repo      ║                               ║                 ║",
"║chassis → cards → sync╟────POST /api/v1/sync──────┐   ║                 ║",
"╚══════════════════════╝                           │   ║  ╔════════════╗ ║",
"                                                   ├───╫─▶║ Capability ║ ║",
"╔══════════════════════╗                           │   ║  ╚════════════╝ ║",
"║ Production telemetry ╟──overmind.capability.id───┘   ║                 ║",
"╚══════════════════════╝                               ║                 ║",
"                                                       ╚═════════════════╝",
]}
/>

<Ascii
  cols={74}
  lines={[
"╔═ Overmind ═════════════════════════════════════════════════════╗",
"║                  ┌───────┬────────────┬──────────────┐         ║",
"║                  │       ▼            ▼              ▼         ║",
"║ ╔════════════╗   │  ╔════════╗  ╔══════════╗  ╔════════════╗   ║",
"║ ║ Capability ╟───┤  ║ Traces ║  ║ Datasets ║  ║ Eval sets  ║   ║",
"║ ╚════════════╝   │  ╚════════╝  ╚══════════╝  ╚════════════╝   ║",
"║                  │                                             ║",
"║                  └────────────┬──────────────────────┐         ║",
"║                               ▼                      ▼         ║",
"║                     ╔═══════════════════╗   ╔════════════════╗ ║",
"║                     ║ Optimisation runs ║   ║ Trained models ║ ║",
"║                     ╚═══════════════════╝   ╚════════════════╝ ║",
"║                                                                ║",
"╚════════════════════════════════════════════════════════════════╝",
]}
/>

### The scan

Discovery runs in your repository, not on the server. `/overmind setup` in your coding agent drives it; `overmind chassis` and `overmind sync` are the CLI halves. See the [CLI](/platform/cli).

The installed skill opens with the detected repository, package manager, and verified connection, then previews ten onboarding stages: installation, project connection, and eight scan stages. Each update shows the current stage name and number, completed count, and how many stages follow it. Discovery explains the capabilities and their source-grounded relationships; later updates report findings rather than just commands. Longer stages include per-capability counts. Completion requires a successful sync; a failed stage keeps its number and reports the error.

Before upload, the agent summarizes the destination, included data, credential checks performed, and local configuration to review. The final handoff reports what was actually synced, material caveats, outstanding verification, and one recommended next action. Instrumentation, application runs, and server-side evaluator preparation remain separate work.

Before scanning, the agent identifies its model when available, the configured Overmind destination, and the data involved. Source excerpts read by the coding agent enter its model context. Sync sends capability metadata, including captured prompt text, tool descriptions, and source references; it does not send a repository archive. The configuration's API-key field is excluded from the snapshot and used for authentication. Overmind may pass the synced metadata to its configured providers to prepare evaluators. Local command execution is not a guarantee that all model processing stays on the machine.

<Steps>
  <Step title="overmind chassis">
    Prints a deterministic AST inventory of Python functions and call edges under the repository root. `/overmind setup` runs this first; the digest is ground truth the cards must not contradict.
  </Step>

  <Step title="Author the cards">
    The coding agent reads the source against that chassis and writes one capability per product purpose into `overmind.toml` — name, slug, entry point, prompt, tools, and a **card**: task, input/output contract, success criteria, failure modes, and a trajectory map of anchors with `file#Lstart-Lend` provenance. Roles inside one orchestration — a crew, a graph of workers, a supervisor with specialists — are **modes** of the one capability that orchestration serves, not separate capabilities. There is no server-side model call.
  </Step>

  <Step title="overmind sync">
    POSTs `overmind.toml` to `POST /api/v1/sync`. The response carries assigned capability ids, and the CLI writes them back. The first sync with an account-scoped key creates the project and mints the project-scoped key the MCP entry uses.
  </Step>
</Steps>

After code changes: run `/overmind setup` again; it includes the final `overmind sync`. A trajectory entry whose anchors are not call-graph reachable from its entry is stamped `verified = false`.

### What the server does with a sync

`POST /api/v1/sync` reconciles the snapshot with the project's capabilities. Then, per capability:

* **Identity is carried**, in order: the toml `id` → the toml `slug` → a new record. A capability the push no longer includes becomes a leftover (`archived = true` in the toml on the next `sync down`).
* **Behaviours are minted from the trajectory map**: one contract per mapped route, with an entry anchor, the ordered anchors that follow it, and its tool set. Behaviours are what [trace scoring](/agent-testing/trace-scoring#behaviours-and-bindings) binds production traffic to; the Console labels the column **Task**.
* **The Default eval set is refreshed** for every current capability on each sync: Tier-0 rule-based checks compiled from the card (deduplicated), Tier-1 generative LLM judges grounded in it (authored once per capability), and per-behaviour outcome and step judges for trace scoring. See [Eval](/agent-testing/eval#authoring).

### A scan never deletes

A capability the push no longer includes becomes a **leftover**: it keeps its id and data, leaves the agent view, shows a **Not in latest scan** badge, and remounts in place when a later push reproduces it. `slug` in `overmind.toml` is the server identity — rename a capability by editing `name`, never `slug`.

To remove a capability yourself, use **Delete capability** at the bottom of its page (`DELETE /api/capabilities/{id}/`). The record is soft-deleted: it leaves lists, scans and identity lookup, its traces, datasets and runs stay, and its inference alias stops serving. Because a deleted capability is invisible to later syncs, the next push of the same code mints a fresh record with a new id, and `overmind sync` writes that id to `overmind.toml`. Code that sets the old UUID as `capability_id` needs the new one; a slug keeps binding.

### Telemetry

Spans carrying `overmind.capability.id` — set with [`init(capability_id=...)`](/tracing/sdk-python#init) or a `capability(..., id=)` scope — bind to that capability. The value is the capability's UUID or its toml `slug`; both resolve, and both are stable through renames. `overmind.capability.name` is a display label and never binds.

Ingest never creates a capability. An identity the project does not know leaves the span **unbound**: it is stored, browsable under Observability's Unbound filter, and binds retroactively when a later push makes the identity resolvable. A capability created by hand (`POST /api/capabilities/`) carries an **Observed** badge, because no scan can retire it.

## The agent page

**Agent** in the sidebar opens the product view: the capability grid, or the onboarding prompt while the project is still empty. Open a capability for its page. The **Repository snapshot** in the header names the repository, branch and last scan time behind the map. A scan that recorded no revision reads **Revision unavailable**; a project with no scan reads **No repository scan**.

<Frame caption="The Agent page: one card per capability with its model, traffic, and live score.">
  <img src="https://mintcdn.com/overmind-b84ae13c-codex-workshop-queue-capacity/qKX7fWUX8kgqFDpP/images/platform/agent-home.jpg?fit=max&auto=format&n=qKX7fWUX8kgqFDpP&q=85&s=0beddc3b46c18a50cf07f077077703cb" alt="Agent page with the capability grid" width="1512" height="794" data-path="images/platform/agent-home.jpg" />
</Frame>

The header carries the name (editable in place), copyable **capability id** and **project id** chips, the slug, and the **Not in latest scan** and **Observed** badges when they apply. **View traces** opens the capability's filtered Observability view. Below it, one scrolling page:

* **Facts** — the model the capability serves through (or the live deployed model behind its alias) and its source path.
* **Prompt** — the system prompt lifted from your code, one per mode when the capability has several.
* **Trajectory map** — the entry point, each behaviour's steps with the tools they may use, and its terminal, as an interactive graph.
* **Components** — every anchor, tool and utility the scan found, with file-level provenance.
* **Dataset** — datasets aligned to this capability. See [Datasets](/core/datasets).
* **Eval metrics** — the capability's eval sets and evaluators, with score history over its runs. See [Eval](/agent-testing/eval).
* **Models** — the production model and any models trained on this capability's data, linking into [Models](/models/training) and [Inference](/models/inference).

<Frame caption="A capability page: facts, the prompt, and the trajectory map with two behaviours.">
  <img src="https://mintcdn.com/overmind-b84ae13c-codex-workshop-queue-capacity/qKX7fWUX8kgqFDpP/images/platform/capability-page.jpg?fit=max&auto=format&n=qKX7fWUX8kgqFDpP&q=85&s=6196c8871fcd8c66bc38138fce89ccf8" alt="Capability page with facts bar, prompt card and trajectory map" width="1456" height="821" data-path="images/platform/capability-page.jpg" />
</Frame>

<Frame caption="The trajectory map expanded: the entry point, each behaviour's steps and the tools they may use, and its terminal.">
  <img src="https://mintcdn.com/overmind-b84ae13c-codex-workshop-queue-capacity/qKX7fWUX8kgqFDpP/images/platform/capability-flow.jpg?fit=max&auto=format&n=qKX7fWUX8kgqFDpP&q=85&s=61022621cf114058cc99ad57893b750c" alt="Trajectory map fullscreen view" width="1456" height="821" data-path="images/platform/capability-flow.jpg" />
</Frame>

The Agent page is the record of the latest sync: each capability with its card and behaviours.

## Instrumentation

Which of a capability's anchors emit telemetry is answered by the traces themselves: a task execution's route shows the contract anchors it matched, and a behaviour with no executions has none. To close a gap, ask your coding agent: the `get_instrumentation_plan` MCP tool returns placement tickets (file, qualname, decorator, required scope) for the project or one capability, and `verify_instrumentation` grades a fresh trace against the contract without writing anything. The `/overmind ensure-tracing` command runs that loop. See [MCP](/platform/mcp).

## API

```bash theme={null}
# The whole agent graph: current capabilities, their edges, and the latest scan
curl -H "X-Api-Key: $OVERMIND_API_KEY" "https://api.overmindlab.ai/api/agent/?project={project_id}"

# List capabilities / one capability
curl -H "X-Api-Key: $OVERMIND_API_KEY" "https://api.overmindlab.ai/api/capabilities/"
curl -H "X-Api-Key: $OVERMIND_API_KEY" "https://api.overmindlab.ai/api/capabilities/{id}/"

# The evaluation spec and the selectable system prompts
curl -H "X-Api-Key: $OVERMIND_API_KEY" "https://api.overmindlab.ai/api/capabilities/{id}/eval_spec/"
curl -H "X-Api-Key: $OVERMIND_API_KEY" "https://api.overmindlab.ai/api/capabilities/{id}/prompts/"

# Behaviours and how well the eval set covers each one
curl -H "X-Api-Key: $OVERMIND_API_KEY" "https://api.overmindlab.ai/api/behaviours/"
curl -H "X-Api-Key: $OVERMIND_API_KEY" "https://api.overmindlab.ai/api/behaviours/coverage/?capability={id}"

# Pull the reconciled snapshot (leftovers come back archived)
curl -H "X-Api-Key: $OVERMIND_API_KEY" "https://api.overmindlab.ai/api/v1/sync?project_id={project_id}"
```

`GET /api/capabilities/` returns current capabilities unless `?status=` asks for leftovers. `PATCH /api/capabilities/{id}/` updates mutable fields, including `model`. Writing `active_model` starts a persisted activation that verifies inference before switching the alias; read `activation` for progress and errors. The existing selection remains active until verification succeeds. `POST /api/v1/sync` is what `overmind sync` speaks; it takes API-key auth and requires `project_id` to be in the key's scope (a project-scoped key supplies its one project). Through MCP: `inspect_capability_health`, `query_failures`, and the `overmind://capabilities/{capability}` resource. See the [REST API](/platform/api) for the full surface.

## Good to know

* **The baseline matters.** The capability's `model` field is what training benchmarks and optimiser baselines measure against. The card is where the model gets named when the codebase resolves models through a role chain rather than a literal.
* **Commit `overmind.toml`.** It carries the ids and the authored cards that keep identity and semantics stable across syncs. `.overmind/credentials.toml` holds the project key and is excluded from git by `overmind sync`.
* **Pin identity in code.** `overmind.init(capability_id="<slug-or-uuid>")` or a `capability(..., id=)` scope stamps `overmind.capability.id` on every span inside. Ingest binds by that id alone.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.