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

# scenario.json

> Scenario structure, keys, tags, and writing effective descriptions

A scenario is a directory containing a `scenario.json` file and optional Ansible playbooks. All scenarios live under a shared root (auto-detected, or set with `-p`).

## Directory Layout

```
scenarios/
  <category>/
    <NNN-scenario-name>/
      scenario.json       # required
      prepare.yml         # optional: Ansible setup before execution
      restore.yml         # optional: Ansible teardown after execution
      validate.yml        # optional: Ansible verification after execution
      inventory.ini       # optional: Ansible inventory
      [support files]     # config snippets, fixtures, test data, etc.
```

The category and numeric prefix (`NNN`) are conventions for organization: they have no special meaning to the runner. The runner uses the full relative path from the scenarios root as the scenario key (e.g. `nginx/001-broken-config`).

***

## scenario.json

The only required file. At minimum, three fields are needed:

```json theme={null}
{
  "key": "nginx/001-broken-config",
  "name": "Nginx Broken Configuration",
  "description": "@2501 the nginx service on the web server is not running. Investigate the issue and fix it so the service is running correctly."
}
```

### Required Fields

| Field         | Description                                                                                             |
| ------------- | ------------------------------------------------------------------------------------------------------- |
| `key`         | Unique identifier. Must match the relative directory path (e.g. `nginx/001-broken-config`).             |
| `name`        | Human-readable name shown in reports.                                                                   |
| `description` | The instruction sent to the agent. Write it as you would a real task: describe symptoms, not solutions. |

### Optional Fields

| Field        | Description                                                                                    |
| ------------ | ---------------------------------------------------------------------------------------------- |
| `tags`       | String array for grouping. Pass a tag to `-s` to run all matching scenarios (e.g. `-s nginx`). |
| `hosts`      | Target host definitions. See [Hosts](/0.4/scenario-runner/hosts).                              |
| `agents`     | Agent definitions. See [Agents](/0.4/scenario-runner/agents).                                  |
| `validation` | Validation rules. See [Validation](/0.4/scenario-runner/validation).                           |

***

## Writing Good Descriptions

The `description` is the exact instruction the agent receives. A few guidelines:

* **Describe symptoms, not solutions.** "The nginx service is not running after a configuration change" is better than "Fix the nginx config file."
* **Be concrete.** Reference the host name, service name, or observable behavior when you know it.
* **Keep it realistic.** Write it as you would a real support ticket or runbook task.

***

## Scenario Keys and Tags

The `key` must exactly match the directory path relative to the scenarios root:

```
scenarios/nginx/001-broken-config/scenario.json
                                   └─ key: "nginx/001-broken-config"
```

Tags are free-form strings for grouping. A scenario can have multiple tags:

```json theme={null}
{
  "key": "nginx/001-broken-config",
  "name": "Nginx Broken Configuration",
  "description": "...",
  "tags": ["nginx", "web", "config"]
}
```

Run all scenarios with a given tag:

```bash theme={null}
2501-runner run -s nginx
2501-runner run -s web
```

Tags and explicit keys can be mixed:

```bash theme={null}
2501-runner run -s nginx,disk/001-cleanup
```