> For the complete documentation index, see [llms.txt](https://docs.kyvvu.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kyvvu.com/platform/incidents.md).

# Incident Management

**What you'll learn:** How incidents are created, the incident lifecycle, and how to triage and resolve them.

***

## What is an incident?

An **incident** is a policy violation record. When the engine evaluates a step and a policy returns `warn` or `block`, an incident is created and sent to the configured incident sink (by default, the same destination as the behavioral trace — see [Configuring the incident sink](#configuring-the-incident-sink)).

Incidents provide the audit trail — they record what was violated, when, by which agent, and in which task.

## Incident lifecycle

```
open  →  active  →  resolved
                 →  ignored
```

| Status       | Meaning                                                                                  |
| ------------ | ---------------------------------------------------------------------------------------- |
| **open**     | Newly created. No human has reviewed it.                                                 |
| **active**   | Acknowledged by somebody in the workspace. Under investigation or remediation.           |
| **resolved** | The violation has been addressed — code fixed, policy adjusted, or root cause mitigated. |
| **ignored**  | Reviewed and determined to be a false positive or acceptable risk.                       |

## Incident data

Each incident includes:

| Field               | Description                                                     |
| ------------------- | --------------------------------------------------------------- |
| `agent_id`          | The agent that triggered the violation.                         |
| `enforcement_point` | `step_execution` or `agent_registration`.                       |
| `task_id`           | The task in which the violation occurred (for step violations). |
| `step_name`         | The step that was evaluated.                                    |
| `step_type`         | The behaviour type.                                             |
| `action`            | `warn` or `block`.                                              |
| `risk_score`        | The aggregate risk score (0.0 to 1.0).                          |
| `violations`        | List of violated policies with name, severity, and details.     |
| `timestamp`         | When the violation occurred.                                    |

## Dashboard workflow

1. Navigate to **Incidents** in the sidebar.
2. Filter by status, agent, severity, or time range.
3. Click an incident to see full details.
4. Use the action buttons:
   * **Resolve** — mark as addressed.
   * **Ignore** — mark as false positive.
   * **Reactivate** — reopen a resolved or ignored incident.

## API endpoints

| Method | Path                                | Description                  |
| ------ | ----------------------------------- | ---------------------------- |
| `GET`  | `/api/v1/incidents`                 | List incidents (filterable). |
| `GET`  | `/api/v1/incidents/{id}`            | Get incident details.        |
| `PUT`  | `/api/v1/incidents/{id}/resolve`    | Resolve incident.            |
| `PUT`  | `/api/v1/incidents/{id}/ignore`     | Ignore incident.             |
| `PUT`  | `/api/v1/incidents/{id}/reactivate` | Reactivate incident.         |

Incidents are never deleted — they form part of the immutable audit trail. They travel with their agent: moving an agent to another workspace carries its logs and incidents along, hash chain intact, and each moved incident carries a self-contained snapshot of the policy it violated, so deleting the workspace it left cannot destroy it.

## Configuring the incident sink

Incidents follow the same **location + format** sink model as behavioral traces. By default the incident sink **inherits the trace sink** (`KV_LOG_LOCATION` / `KV_LOG_FORMAT`), substituting the `…/api/v1/incidents` path for the Kyvvu `kv` format. So if traces already flow to the platform, incidents do too — no extra configuration needed.

To route incidents to a **different** destination, set `KV_INCIDENT_LOCATION` (and optionally `KV_INCIDENT_FORMAT`):

```bash
# Send incidents to the platform explicitly (kv format → …/api/v1/incidents)
export KV_INCIDENT_LOCATION=https://platform.kyvvu.com
export KV_INCIDENT_FORMAT=kv
```

`KV_INCIDENT_LOCATION` accepts the same values as `KV_LOG_LOCATION` — an HTTP URL, a file path (JSONL), `stdout`, or `none`/empty to disable:

```bash
# Local debugging — print incident JSON to stdout
export KV_INCIDENT_LOCATION=stdout
```

```bash
# Emit a standalone kyvvu.incident OpenTelemetry span
export KV_INCIDENT_LOCATION=http://collector:4318
export KV_INCIDENT_FORMAT=otlp
```

***

## Next steps

* [Dashboard Guide](/platform/dashboard.md) — navigate the dashboard
* [Reports](/platform/reports.md) — generate audit reports from incident data
* [Policies and Rules](/core-concepts/policies.md) — understand how violations are determined