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

# Write your rules

> Write your rules as text by hand, with an AI, or from an existing statement.

This guide writes rules text and imports it into a [scenario](https://docs.allocait.app/concepts/scenarios.md). [Rules text format](https://docs.allocait.app/concepts/rules-text-format.md) is the reference: every key, the defaults for an edge you leave out and the class-name rules.

## Option 1: write it by hand

Start from this example and replace every number with your own.

Illustrative example. The figures are hypothetical, not a recommendation.

```markdown theme={null}
---
version: 1
name: Example rules
classes:
  Equities: { target: 53, min: 44, max: 67 }
  Fixed Income: { target: 24, min: 18, max: 29 }
  Cash: { min: 3, max: 11 }
---

# Notes

Review quarterly.
```

To add a size range for single holdings, put `position_size` under a class, and `short_position_size` for shorts. For example, `position_size: { max: 9 }` caps one holding at 9% of the portfolio. The [format reference](https://docs.allocait.app/concepts/rules-text-format.md#format-rules) explains both keys and what [defaults](https://docs.allocait.app/concepts/rules-text-format.md#defaults) apply.

## Option 2: have an AI draft one

Give an AI assistant your own rules in plain language and ask it to produce rules text. The numbers below are a fictional example; use yours. A prompt like this is a starting point. Check what the assistant writes with a preview before you import it:

```
Write rules text for Allocait with these rules:
- Equities: 44-67% of the portfolio, target 53%, no single holding over 9%
- Fixed Income: 18-29%, target 24%
- Cash: 3-11%

Follow the rules text spec at https://allocait.app/rules/spec.md.
```

The Allocait MCP server offers a `draft_rules` prompt. With no notes, its text asks the assistant to ask for your classes and ranges one at a time. Where your MCP client lists prompts depends on the client. See [Claude and MCP](https://docs.allocait.app/claude/overview.md).

## Option 3: convert an existing investment policy statement

Paste your investment policy statement or spreadsheet to an AI assistant and ask it to convert the allocation ranges into rules text format. If a document splits a class (domestic and international equity, for example), choose whether to keep the parts as separate classes named as written, or combine them into one built-in class by adding their targets, minimums and maximums. A name that isn't an exact match, such as Global Equities, becomes a new custom class. In an MCP client that lists prompts, the `draft_rules` prompt takes the statement in its `notes` argument.

## Checking the text

Before importing, call `preview_rules` (MCP) or `POST /scenarios/{id}/rules` with `dry_run: true` (REST API) to validate the text against the spec and see what it would change, without touching your account.

## Importing

**1. Open the Edit as text tab**

Pick the scenario in the top bar, then go to **Allocation** and open the **Edit as text** tab. The tab shows that scenario's current rules as rules text you can copy or download.

**2. Paste or upload your text**

Choose **Import**, then drop a file or paste your rules text. **Examples** (**Browse examples** on a scenario with no rules yet) opens starting points with every number left blank, for you to fill in, then review and apply the same way.

**3. Review the preview**

Allocait shows every class that would change, be added, or be removed, with the old value next to the new one. Nothing is written yet.

**4. Apply**

Choose **Apply changes**. Allocait saves a restore point first, then confirms the update with an **Undo** button that stays for ten seconds. After that, the same point is listed under **Restore points** on the Edit as text tab. **Restore** sets the scenario's rules back to that point and says which classes it could not restore. Allocait keeps the 20 newest restore points per account.

An agent does the same through tools: `preview_rules` returns the changes without writing, and `apply_rules` writes them and returns a restore point; `restore_rules` sets the rules back to that point and returns a new restore point. To change one class without a file, `save_class_rule`, which keeps every other rule and also saves a restore point. Applying needs Read and change access; see [what each level of access allows](https://docs.allocait.app/concepts/access-levels.md).

## Next steps

* [Rules text format](https://docs.allocait.app/concepts/rules-text-format.md) lists every key and default.
* [Rules text](https://docs.allocait.app/concepts/rules-text.md) explains the format and how an import works.
* [Scenarios](https://docs.allocait.app/concepts/scenarios.md) explains how imported rules text relates to the active scenario.
* [Check before you trade](https://docs.allocait.app/guides/check-before-you-trade.md) tests a change against the rules you just imported.
* [Rule tools](https://docs.allocait.app/claude/tools/rules.md) lists the tools an agent uses.


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