# Setup Report Schema

This document describes the JSON report `agdt-setup` attempts to emit after
every terminal execution path. Consumers can read this file (when present) to determine setup
outcome without parsing stdout.

**Default location:** `~/.agdt/last-setup-report.json`

**Override:** Set `AGDT_SETUP_REPORT_PATH` to redirect output to a custom path.

> **Last-Writer-Wins Limitation:** When multiple concurrent `agdt-setup`
> invocations target the same report path, the last writer wins. Each write is
> atomic (no partial files), but there is no locking between processes.

## Schema Fields

| Field | Type | Description |
|-------|------|-------------|
| `schema_version` | integer | Schema version (currently `1`). |
| `mode` | string | Execution mode: `setup`, `check`, `check-fix`, or `dry-run`. |
| `git_root` | string or null | Absolute path to the git repository root, or `null` if not in a repo. |
| `timestamp` | string | ISO-8601 UTC timestamp of report generation. |
| `exit_code` | integer | Numeric exit code from the taxonomy below. |
| `exit_code_name` | string | Named constant for the exit code. |
| `autorun_enabled` | boolean or null | Computed autorun resolution result. Derived from `--run`/`--no-run`, `AGDT_SETUP_RUN`/`AGDT_SETUP_NO_AUTORUN`, and CI/TTY detection. `null` when not computed. |
| `total_phases` | integer | Total number of recorded phases. |
| `passed` | integer | Phases with `status == "success"`. |
| `failed` | integer | Phases with `status == "failed"`. |
| `skipped` | integer | Phases with `status == "skipped"`. |
| `phases` | array | Ordered list of phase result objects. |
| `phases[].name` | string | Phase identifier. |
| `phases[].status` | string | One of `success`, `failed`, `skipped` (or future values). |
| `phases[].duration_ms` | integer | Wall-clock duration in milliseconds (`0` when unavailable). |
| `phases[].error` | string or null | Error message if status is `failed`. |
| `details` | object | Additional context (varies by exit code). |

## Exit Codes

| Code | Name | Description |
|------|------|-------------|
| 0 | OK | Setup completed successfully. |
| 1 | WARNINGS | Setup completed but one or more optional checks produced warnings. |
| 2 | MISSING_REQUIRED_DEP | A required dependency is missing. |
| 3 | VERSION_BLOCKED | Running version is older than the project-pinned minimum. |
| 4 | UPGRADED_RERUN_NEEDED | Package was upgraded; a re-run is required. |
| 5 | REPO_MUTATION_FAILED | A repository file-modification step failed. |
| 6 | AUTORUN_FAILED | An unexpected internal error occurred. |

## Example

```json
{
  "schema_version": 1,
  "mode": "setup",
  "git_root": "/home/user/project",
  "timestamp": "2026-01-15T10:30:00+00:00",
  "exit_code": 0,
  "exit_code_name": "OK",
  "autorun_enabled": true,
  "total_phases": 6,
  "passed": 6,
  "failed": 0,
  "skipped": 0,
  "phases": [
    {
      "name": "version_check",
      "status": "success",
      "duration_ms": 12,
      "error": null
    }
  ],
  "details": {}
}
```

## Further Detail

For the full expectations document (phases, decision flowchart, and sync-gated
field reference), see
[docs/setup-expectations/agdt-setup.md](setup-expectations/agdt-setup.md).
