Skip to main content
A setup file is one Markdown file of definitions: scenarios 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 and the API reference.

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

​
Next steps