# Building Axmo models — the guide

axmo-format-version: ed0892bbbdf4

**Who this is for:** an AI assistant or agent asked to build, check or change an Axmo model. **What it is:** how to
do it well. **What it is not:** the reference — the keys, codes, functions and report forms are generated from the
product and live in [`../generated/`](../generated/); this guide links to them.

## What an Axmo model is

Axmo is an Excel add-in. A model is **one YAML file**, `model.yaml`, usually inside an `.axmo` container (a zip that
holds `model.yaml` and a `format-version` file containing `1`). The user imports it from the Axmo ribbon in Excel.

A model holds:

- **dimensions** — trees of named elements: products by range, months by quarter;
- **series** — named quantities over some dimensions: an **input** is loaded from data; a **calculated** series
  has a formula, written once, that holds for every element;
- **data sources and loaders** — which ranges feed which series, columns mapped to dimensions;
- **output ranges** — reports Axmo writes to sheets;
- optionally **data** — the input cells, so the model works in an empty workbook.

The idea that makes Axmo different from a spreadsheet: **a formula is written on named quantities, not cells**.
`Stage Load = Volume * Minutes / 60` is one formula for every product, stage, plant and month, and every total
exists automatically at every level of every dimension.

**What the guide may claim** is bounded by [`../capabilities.md`](../capabilities.md): what the product is measured
to do with a model's data, each row pinned by a test. Where the guide and that table differ, the table is right.
**Each file declares its format version.** If two you read differ, one is an old cached copy: prefer
`llms-full.txt`, tell the user, and let the report decide.

## The files of this guide

| File | Read it when |
|---|---|
| [01-method.md](01-method.md) | Always, first: the order of work, from description to checked model. |
| [02-model-file.md](02-model-file.md) | Writing the YAML: skeleton, names, time, loaders, generated dimensions, output ranges. |
| [03-formulas-and-totals.md](03-formulas-and-totals.md) | Writing formulas; how each series totals up and splits down. |
| [04-recipes.md](04-recipes.md) | Looking for a worked pattern: balances, rates, ratios, actual vs budget, splits, formula forms, a ledger P&L. |
| [05-checking-and-fixing.md](05-checking-and-fixing.md) | Checking, reading the report and fixing, what Axmo cannot do today, the workbook tool. |

## The loop that makes the result reliable

**Never hand a model over unchecked.** Check, read the report and values, fix, check again, by the first route
you have:

- **Code that can download:** `node tool/axmo-check.mjs model.axmo --values` runs the real import, compile and
  update, prints the report, then every output range's cells. Exit `0` means no error; finish with `--strict`, which
  fails on a warning too. See [05-checking-and-fixing.md](05-checking-and-fixing.md).
- **Code that cannot download:** ask the user, in these words: *"Please download
  https://axmo.it/ai/axmo-model-check-skill.zip and drop it into our chat."* Unzip it and run its tool.
- **No code:** ask the user to import the file and press **Copy report** in the Import dialog, and paste the text
  back. It is the same report.

**Only a result the tool printed or the user pasted counts.** Never write output you did not run.

Then compare the values with numbers you calculated by hand for two or three cells. A model that imports cleanly
can still compute the wrong thing; only a hand-calculated value catches that.