> ## Documentation Index
> Fetch the complete documentation index at: https://visorai.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Response schema

> Reference the JSON envelope, run result structure, step result structure, and assertion result objects returned by visor.

visor returns a structured JSON envelope for normal commands.

If you run `visor --help`, `visor -h`, or invoke the CLI with no command, the CLI prints a plain-text usage summary instead. If you run `visor --version` or `visor -v`, the CLI prints the package version instead.

## Top-level envelope

| Field         | Type            | Meaning                                     |
| ------------- | --------------- | ------------------------------------------- |
| `status`      | string          | `ok` or `fail`                              |
| `command_id`  | string          | Unique command invocation id                |
| `started_at`  | string          | UTC timestamp                               |
| `ended_at`    | string          | UTC timestamp                               |
| `artifacts`   | array of string | Artifact paths associated with the response |
| `next_action` | string          | Hint for the next logical operation         |
| `error`       | object          | Present only on failure                     |
| `data`        | object          | Command-specific payload                    |

## Error payload

| Field          | Type   | Meaning                  |
| -------------- | ------ | ------------------------ |
| `code`         | string | Structured error code    |
| `message`      | string | Human-readable summary   |
| `likely_cause` | string | Best current explanation |
| `next_step`    | string | Suggested remediation    |

## Run result

When a scenario run succeeds or fails, `data.run` contains a run result.

| Field                   | Type            | Meaning                                                  |
| ----------------------- | --------------- | -------------------------------------------------------- |
| `run_id`                | string          | Unique run id                                            |
| `platform`              | string          | `android` or `ios`                                       |
| `device`                | string          | Resolved device name                                     |
| `started_at`            | string          | Run start timestamp                                      |
| `ended_at`              | string          | Run end timestamp                                        |
| `status`                | string          | `ok` or `fail`                                           |
| `steps`                 | array           | Ordered step results                                     |
| `assertions`            | array           | Assertion results                                        |
| `artifacts`             | array of string | Final copied artifact paths                              |
| `determinism_signature` | string          | SHA-256 signature of normalized run data                 |
| `seed`                  | number          | Present when the scenario provides a seed                |
| `map`                   | object          | Present when mapped execution was considered for the run |
| `error`                 | object          | Present when the run failed                              |

## Step result

| Field         | Type   | Meaning                      |
| ------------- | ------ | ---------------------------- |
| `id`          | string | Step id                      |
| `command`     | string | Executed command             |
| `status`      | string | `ok` or `fail`               |
| `duration_ms` | number | Step duration                |
| `details`     | object | Adapter-returned payload     |
| `error`       | object | Present when the step failed |

## Map metadata

Mapped execution metadata uses these fields:

| Field            | Type    | Meaning                                                                                               |
| ---------------- | ------- | ----------------------------------------------------------------------------------------------------- |
| `enabled`        | boolean | Whether map reads and writes were enabled                                                             |
| `used`           | boolean | Whether Visor used cached map knowledge for routing                                                   |
| `updated`        | boolean | Whether the host app map changed during the command                                                   |
| `repaired`       | boolean | Whether Visor repaired a stale or missing route                                                       |
| `repairs`        | number  | Count of bounded repair passes used                                                                   |
| `schema_version` | number  | App-map schema version                                                                                |
| `path`           | string  | Host path to the persisted app map when enabled                                                       |
| `identity`       | string  | App-map identity, scoped by platform and app id                                                       |
| `summary`        | object  | Path-free app-map inventory attached to `visor discover` responses when the persisted map can be read |

Direct action commands return this object in `data.map`. Scenario runs return it in `data.run.map`. A routed or repaired step may also include `details.map.route`, an ordered list of hidden route actions Visor performed before the requested step action.

`visor discover` adds `data.map.summary` when mapped execution is enabled and the persisted map file is readable. The summary is safe to share in reviews because it does not include the host map path.

| Summary field            | Type   | Meaning                                              |
| ------------------------ | ------ | ---------------------------------------------------- |
| `schema_version`         | number | App-map schema version read from disk                |
| `identity`               | string | App-map identity, scoped by platform and app id      |
| `app_id`                 | string | App id used for the map                              |
| `platform`               | string | `android` or `ios`                                   |
| `screens`                | number | Count of discovered logical screens                  |
| `variants`               | number | Count of discovered screen variants                  |
| `edges`                  | number | Count of recorded navigation edges                   |
| `actions`                | number | Count of stored action affordances                   |
| `auth_required_variants` | number | Count of variants marked as requiring authentication |
| `updated_at`             | string | Last persisted map update timestamp                  |

## Assertion result

Assertion results are plain objects with these fields:

| Field     | Type   | Meaning                         |
| --------- | ------ | ------------------------------- |
| `id`      | string | Assertion id                    |
| `type`    | string | Assertion type                  |
| `target`  | string | Selector that was checked       |
| `status`  | string | `passed` or `failed`            |
| `details` | string | Failure or informational detail |

## Benchmark result payload

Benchmark responses store their command-specific payload in `data`.

| Field              | Type            | Meaning                                                   |
| ------------------ | --------------- | --------------------------------------------------------- |
| `runs`             | number          | Number of iterations attempted                            |
| `threshold`        | number          | Required determinism threshold                            |
| `determinismScore` | number          | Calculated score                                          |
| `pass`             | boolean         | Whether the benchmark passed                              |
| `failures`         | number          | Count of failed iterations                                |
| `runIds`           | array of string | Run ids created during the benchmark                      |
| `warnings`         | array           | Validation warnings carried through from scenario parsing |

## Validation payload

Validation responses use this `data` structure:

| Field    | Type    | Meaning                                |
| -------- | ------- | -------------------------------------- |
| `valid`  | boolean | Whether the scenario passed validation |
| `issues` | array   | Validation errors and warnings         |

Important behavior:

* schema-invalid scenarios return `status: "ok"` with `data.valid: false` and a non-zero process exit code
* malformed JSON or unreadable files return a failure envelope with `status: "fail"`

Each issue contains:

* `severity`
* `code`
* `message`
* `path`

## Example envelope

```json theme={null}
{
  "status": "ok",
  "command_id": "cmd_123456789abc",
  "started_at": "2026-03-29T16:00:00Z",
  "ended_at": "2026-03-29T16:00:01Z",
  "artifacts": [
    "artifacts/run_123/screenshots/001-app-opened.png"
  ],
  "next_action": "report",
  "data": {
    "run": {
      "run_id": "run_123456789abc",
      "platform": "android",
      "device": "emulator-5554",
      "started_at": "2026-03-29T16:00:00Z",
      "ended_at": "2026-03-29T16:00:01Z",
      "status": "ok",
      "steps": [],
      "assertions": [],
      "artifacts": [],
      "determinism_signature": "...",
      "seed": 42
    },
    "warnings": []
  }
}
```