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

# Scenarios

> Author, search, and re-run reusable verification scenarios so the agent verifies the right flows the same way every time.

A **scenario** is a reusable, saved verification script — "log in as admin, open billing, confirm the invoice total updates" — captured once and replayed on demand. Instead of re-describing what to verify (or letting the agent re-discover it) on every run, you build up a small library of scenarios the verifier can run directly. Scenarios are **committed to the repo**, so your whole team (and CI) shares them.

Each scenario belongs to one [verification cycle](/cli/guides/verification#verification-platforms) — a browser scenario drives the browser, an Android scenario drives the device, and so on — and is stored as a script the matching devtools server can run in a single call.

<Note>
  Saved scenarios are installed in **enforce** and **assist** modes (the same gating as the verifier). In **monitoring-only** mode the scenario commands and sub-agent aren't installed.
</Note>

***

## The commands

Three agent-invoked slash commands manage scenarios. On Claude Code and Cursor they're `/`-prefixed; on Codex use the `$` mention syntax (`$ironbee-manage-scenario`).

| Command                    | What it does                                                                                                         |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `/ironbee-manage-scenario` | **Add, update, or delete** a scenario. By default it authors the script against your **running app**, then saves it. |
| `/ironbee-search-scenario` | **Find** saved scenarios by name, description, or metadata (e.g. a covered path). Read-only.                         |
| `/ironbee-sync-scenario`   | **Re-validate and repair** saved scenarios that have drifted as the code changed.                                    |

Like the verifier, on Claude Code and Codex these **delegate to a dedicated `ironbee-scenario` sub-agent** that owns the scenario tools (and, like the verifier, can't edit your code — the scenario store is written server-side). On Cursor (and Codex in `main-agent` mode) the main agent drives the tools directly.

### Author a scenario

```bash theme={null}
/ironbee-manage-scenario log in as admin, open /billing, confirm the invoice total updates
/ironbee-manage-scenario ./scenarios/checkout.md          # author from a file's contents
/ironbee-manage-scenario draft a smoke test of the home page   # `draft` = author from source only
```

By default authoring is **live**: the agent drives your running app to understand it (navigate, log in, click, snapshot — the same way a verification run does), writes the script from what it actually observes, validates it by running once, and tears down anything it started. If the app can't be started it falls back to a **source-only draft**, and a leading `draft` token forces source-only authoring up front.

The sub-agent decides add-vs-update (it checks for an existing same-name scenario first), picks the right cycle, declares any [parameters](#parametric-scenarios) the script takes, and stamps metadata. A delete or a fuzzy-matched update asks you to confirm the matched scenario first.

### Search scenarios

```bash theme={null}
/ironbee-search-scenario checkout                      # fuzzy over name + description
/ironbee-search-scenario covers src/billing/invoice.ts # metadata match (e.g. a covered path)
```

It searches every enabled cycle's store and returns the matches (name, description, cycle, and a relevance score for fuzzy searches).

***

## Parametric scenarios

A scenario script reads its inputs from an `args` binding — `const { baseUrl } = args;` — so the same flow can run against different values. Each input is declared up front as a **typed parameter**, so the scenario carries its own input contract: defaults, types, and which values are required all travel with the script.

When the agent authors a parametric scenario it captures sensible **defaults from the live-authoring run**, so the scenario re-runs "as captured" with zero arguments — you only pass `args` to *override* a default. Each parameter declares:

| Field         | Purpose                                                                                                                                             |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | The `args` key the script reads (e.g. `baseUrl`). Required.                                                                                         |
| `description` | What the parameter is, for the agent and for humans.                                                                                                |
| `type`        | `string`, `number`, `boolean`, `object`, or `array`. Omit for an untyped passthrough; `object` / `array` are shallow-checked at the top level only. |
| `default`     | Applied when the caller omits the argument (captured from the authoring run).                                                                       |
| `example`     | A documentation-only shape, surfaced when there's no `default`. Never injected or validated.                                                        |
| `required`    | Rejects the run when there's no value **and** no `default`.                                                                                         |

On every run the parameters are enforced: defaults fill in omitted arguments, `required` values must be present, and declared types are shallow-validated — a wrong-type or missing-required run **fails loudly** instead of silently passing `undefined` to the script. The declared parameters ride along in search and run output, so a scenario's contract is visible without opening the script.

<Note>
  Parameters are first-class — the agent manages them through `/ironbee-manage-scenario`, and they supersede the older `argsSchema` metadata convention. A scenario with no declared parameters keeps a fully-opaque `args` passthrough (its expected shape is documented in the scenario's description).
</Note>

***

## Verify with a saved scenario

Once a scenario exists, point `/ironbee-verify` at it with a `scenario:` reference instead of re-typing the flow — the verifier resolves it and runs it in one call, with no re-discovery:

```bash theme={null}
/ironbee-verify scenario:checkout flow              # run a saved scenario by name or description
/ironbee-verify fix scenario:the full purchase flow # fix mode + a saved scenario
/ironbee-verify scenario:checkout flow args:{"baseUrl":"http://localhost:8080"}  # override a param for this run
```

The reference can be an exact name or a semantic description (the verifier picks the best match, asks if it's ambiguous, and falls back to normal discovery if nothing matches). This is the third scenario form `/ironbee-verify` accepts, alongside [inline text and file paths](/cli/guides/verification#custom-verification-scenarios).

To run a [parametric scenario](#parametric-scenarios) against different values, add a trailing `args:{...}` JSON object — it overrides the scenario's captured defaults for that run only (omitted params keep their defaults; the same typed-parameter validation still applies). Without it, a saved scenario re-runs exactly as captured.

***

## Where scenarios are stored

Saved scenarios are committed under a single flat store, `.ironbee/scenarios/` — the `ironbee-devtools` compose server registers the scenario tools once for the whole project rather than per cycle. A scenario can therefore be **cross-platform**: one script may drive several cycles' tools (for example a `bdt_*` browser step followed by a `bedt_*` backend check), authored as a single scenario rather than split per platform. Each scenario records its platform(s) in its `ironbee.platform` / `ironbee.platforms` metadata, which is what `ironbee scenario status` and the [TUI](/cli/guides/interactive-mode) scenarios area display.

Unlike the per-session `sessions/` data, the scenario store is **not gitignored** — scenarios are repo content meant to be reviewed in PRs and shared with the team, the same trust level as `.ironbee/VERIFICATION.md`. The store is committed and client-agnostic (it isn't per-client).

<Note>
  Older installs wrote one folder per cycle (`.ironbee/scenarios/bdt/`, `ndt/`, `bedt/`, `adt/`, `tdt/`). That layout is still read for back-compat — its scenarios are unioned with the flat store — so existing scenarios keep working without migration.
</Note>

***

## Keep scenarios fresh

Saved scenarios rot as the code they cover evolves. Two **pure-code** commands (no LLM, no app run) tell you where things stand — useful both at the terminal and as CI gates:

### `ironbee scenario status`

Reports the freshness of every saved scenario against the current code by git-diffing each scenario's covered paths since the commit it was authored at:

```bash theme={null}
ironbee scenario status            # fresh / stale / unknown per scenario
ironbee scenario status --stale    # only stale ones; exits non-zero if any exist (CI gate)
ironbee scenario status --json     # machine-readable
```

* **fresh** — no covered file changed since the scenario was authored.
* **stale** — covered files changed since then (or it was saved as an unvalidated draft).
* **unknown** — can't tell (not a git repo, or the scenario has no covered-path / commit baseline).

### `ironbee scenario coverage`

The inverse: changed code that **no** saved scenario covers — i.e. where you might want to author a new one. It resolves the current change set (working tree ∪ the last [`verification.context.commitDepth`](/cli/configuration/configuration#verification) commits), filters it to verification-relevant files (the same patterns the gate uses, so docs, lockfiles, and test files drop out), and lists the ones no scenario's covered paths match.

```bash theme={null}
ironbee scenario coverage                    # changed, verification-relevant files with no scenario
ironbee scenario coverage --commit-depth 0   # working tree only
ironbee scenario coverage --json
```

Coverage is **advisory** (covered paths are author-declared, so a gap can be a false positive) — most changes legitimately need no scenario, so it has no exit gate.

### Repair drift with `/ironbee-sync-scenario`

`scenario status` only *detects* staleness; repairing it is the agent-driven `/ironbee-sync-scenario`, which re-runs the target scenario against the live app and fixes drift:

```bash theme={null}
/ironbee-sync-scenario all          # re-run + repair stale scenarios, stamp them current
/ironbee-sync-scenario check all    # dry-run — report drift, change nothing
/ironbee-sync-scenario force all    # re-validate every scenario, not just stale ones
/ironbee-sync-scenario checkout     # a single scenario by name or description
```

Sync repairs **mechanical** drift only — the way the flow is driven (a renamed selector, a moved route) — and **never** changes *what* a scenario asserts (that would mask a regression). When it hits a real defect it stops and reports instead of editing the scenario; when an expectation genuinely changed it asks you. A leading `check` token makes it a dry-run; `force` re-validates everything rather than just the stale set. It's not a verification cycle — it submits no verdict and doesn't gate completion.

<Note>
  Browse freshness without running anything from the [TUI](/cli/guides/interactive-mode) **Scenarios** area — a read-only fresh/stale/unknown view of every saved scenario. Repair is still the agent's `/ironbee-sync-scenario`.
</Note>

***

## What's next?

<CardGroup cols={2}>
  <Card title="Verification" icon="shield-check" href="/cli/guides/verification">
    Choose which platforms get verified and switch between enforce, assist, and monitoring.
  </Card>

  <Card title="Verification context" icon="file-text" href="/cli/guides/verification-context">
    Give the agent area-specific instructions with `.ironbee/VERIFICATION.md` files.
  </Card>
</CardGroup>