> ## 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.

# ALLOCAIT.md

> ALLOCAIT.md, one reviewed file that sets up scenarios, watchlists, Inputs and a portfolio's playbooks, monitors and charts.

A setup file is one Markdown file of definitions: [scenarios](https://docs.allocait.app/concepts/scenarios.md) with their ranges, custom asset classes, watchlists, Inputs (named values you record, such as a level or a reading), and one portfolio's playbooks, monitors and charts. Its author writes it once; you add it to your account in one reviewed step.

It holds definitions only: never a holding, cash balance, price, recorded value, level or the active scenario. Every number in a file is its author's, not Allocait's, and the review says so next to the author's own disclosure.

## What you see

You open `allocait.app/setup`, choose the file or paste its text, and Allocait shows who wrote it, what it would add, and what it would leave alone. Anything you already have under the same name stays yours. Nothing is saved until you apply it. Applying a newer revision of the same file updates what the earlier import made and you haven't changed. It deletes no scenario, class, watchlist, Input, playbook, monitor or chart. It can drop a list entry, such as a watchlist symbol or a playbook column, from an item the earlier import made and you haven't changed, and the review names each one. An item you edited or renamed stays yours. Afterward you can undo a file's newest import. Undo removes what the import added only if you haven't changed or used it, and keeps the rest. You choose which scenario, if any, is active. Allocait never makes one active for you.

## What an agent does

An agent can do the same steps through MCP or the REST API. The tool text tells it to show you the preview and ask you first. Allocait cannot check that it did.

1. `preview_setup` reads the file and returns what it would do. It writes nothing.
2. The tool text tells the agent to show you the author, the disclosure in the author's own words, Allocait's note about the numbers, the counts, and every item that stays yours or is left out.
3. `apply_setup` takes the preview's `digest` and applies exactly what that preview showed, then returns a `receipt_id`. The tool text tells the agent to ask you first.
4. `undo_setup` takes it back. It shows what would go first.

A file's names, descriptions and notes are the author's words, not Allocait's. Allocait does not act on them as instructions, and the tool text tells an agent to show them to you. If your account changes after the preview, `apply_setup` writes nothing and returns `CONFIRMATION_REQUIRED` with a fresh preview. `undo_setup` works only on a file's newest import; an older one returns `IN_USE`. The digest ties an apply to a preview of the same decisions. It doesn't show that anyone read the preview. The `apply_setup` tool text tells an agent to apply a file only when someone is there to ask, and Allocait cannot check that. Applying and undoing need a connection with **Read and change** access. Previewing works on a read-only connection.

The REST API has the same steps: `POST /setup/preview`, `POST /setup/apply`, `GET /setup/receipts` and `POST /setup/receipts/{id}/undo`. `GET /setup/export` is a different thing: it returns your own definitions as JSON, not an ALLOCAIT.md file. See the [tools reference](https://docs.allocait.app/claude/tools/setup-file.md) and the [API reference](https://docs.allocait.app/api/introduction.md).

## The format

A complete file needs six header keys (`format`, `version`, `id`, `name`, `author`, `description`) and at least one section: `scenarios`, `custom_asset_classes`, `watchlists`, `inputs` or `portfolio`. Everything after the closing `---` is a README for people who open the file in an editor, and Allocait doesn't read it.

A setup file isn't [rules text](https://docs.allocait.app/concepts/rules-text.md). Rules text holds the rules of one scenario; a setup file can carry many scenarios plus the research layer, and each scenario's rules use the rules text grammar. Rules text pasted where a setup file goes, or the reverse, is refused. A file can be at most 200 KiB (204,800 bytes); the spec lists every limit.

* [The format, in full](https://allocait.app/setup-file/spec.md): every key, every limit, and the rules for an agent that writes a file.
* [A small neutral example](https://allocait.app/setup-file/examples/starter.md) with one scenario, one watchlist, two Inputs and one playbook, to copy and change.

## Next steps

* [Rules text](https://docs.allocait.app/concepts/rules-text.md) holds the rules of one scenario.
* [Scenarios](https://docs.allocait.app/concepts/scenarios.md) explains how scenarios and the active scenario work.
* [Setup file tools](https://docs.allocait.app/claude/tools/setup-file.md) lists the MCP tools.
* [Access levels](https://docs.allocait.app/concepts/access-levels.md) explains read and read-and-change connections.


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