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

# Scenarios

> A named set of rules for one portfolio. You can switch a portfolio between them.

A scenario is a named set of rules. Each rule covers one asset class and holds an [allocation band](https://docs.allocait.app/concepts/allocation-bands.md), a [size range](https://docs.allocait.app/concepts/position-sizes.md), a short size range, or a mix of them, plus an optional target. Allocait checks a portfolio against its active scenario. A [rules text](https://docs.allocait.app/concepts/rules-text.md) describes one scenario.

If you keep different rules for different conditions, save each set as its own scenario, for example `Rules A` and `Rules B`, and change which one is active instead of editing one set back and forth. A new account starts with an empty scenario; see below.

## Scenarios and portfolios

A scenario belongs to you, not to any one portfolio. A portfolio has one **active scenario** at a time. You can point more than one portfolio at the same scenario, or give each portfolio its own.

A new account starts with an empty scenario called `My rules`, active on a portfolio called `Main Portfolio`. You enter every number; Allocait never picks one for you.

## The active scenario

The active scenario is the one a portfolio's compliance and rebalance are checked against. Only a deliberate act on a scenario sets it:

* You pick it in the top-bar switcher, or choose **Make active** on a scenario in **Allocation**.
* An agent sets it with `save_portfolio` and `active_scenario_id`, when you ask.
* On the done step of a [setup file](https://docs.allocait.app/concepts/setup-file.md) import, you can pick one from a list.

Nothing else writes it. Creating, editing, copying rules into or opening a scenario leaves the active one unchanged. So do importing a setup file or rules text, undoing an import and loading a page. Allocait also never picks one for you: a portfolio with no active scenario stays that way until you choose, even when you have only one scenario.

### When none is set

| Where | What you see |
| - | - |
| **Allocation** | A chooser lists your scenarios by name, with none preselected. |
| Home, **Compliance** and **Rebalance** | **No scenario set**. |
| An agent's snapshot | No scenario. |
| An agent's checks | They need a `scenario_id` you name. |

Deleting the active scenario leaves the portfolio with none. Deleting a scenario also deletes its [restore points](https://docs.allocait.app/concepts/rules-text.md#importing), the saved copies that let you undo a change to its rules, and the past values kept for its rules. You can't undo a deletion.

### Other things you can do

* To look at or edit another scenario without switching, pick it on the **Rules** or **Edit as text** tab. An **Active** tag marks the one in use.
* To add, copy or delete a scenario, use the menu beside its name: **Add scenario…**, **Copy rules to…**, **Delete scenario…**.

## For agents

An agent sees the same scenarios as the app. `list_portfolios` returns each scenario with its `rule_count` and the portfolios that use it. `save_scenario` creates or renames one, `delete_scenario` deletes one and needs the `confirm_name` the user gave, and `save_portfolio` with `active_scenario_id` changes the active scenario. `get_portfolio_snapshot`, `check_allocations` and `check_trades` take an optional `scenario_id` and default to the portfolio's active scenario. To change a scenario's rules, see [Rules text](https://docs.allocait.app/concepts/rules-text.md).

## Next steps

* [Allocation bands](https://docs.allocait.app/concepts/allocation-bands.md) and [position sizes](https://docs.allocait.app/concepts/position-sizes.md) describe the rules a scenario holds.
* [Write your rules](https://docs.allocait.app/guides/write-your-rules.md) fills a scenario from rules text.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.