# FINANCE.md

> The FINANCE.md open format carries a model's context, currency, units, language and glossary, read by every agent before it writes. Fields and example.

FINANCE.md is an open format for the context of a financial model: what a reader, person or agent, must know before reading a number. Every Layerz model carries one. The specification lives at github.com/layerzlabs/finance-md; the [FINANCE.md page](/finance-md) presents it.

A FINANCE.md is a Markdown file: a YAML header for what is structured, a free body for what needs explaining.

```markdown
---
finance_md: '0.1'
model_name: Acme SaaS plan 2027
currency: EUR
units: k
language: en
glossary:
  ARR: Annual recurring revenue, contracted, excluding services
---

## Objective

Three-year monthly plan for the Series A, read by the board.

## Statements

P&L by nature; cash flow indirect; net income feeds retained earnings.

## Conventions

Costs are negative. Headcount is end of month.
```

## Header fields

| Field | Type | Required | Description |
|---|---|---|---|
| `finance_md` | `"0.1"` | yes | Spec version, "0.1". `spec_version` is accepted as an alias. |
| `model_name` | `string` | yes | Name of the model, deal, entity or project. |
| `currency` | `string` | yes | Reporting currency, ISO 4217 (EUR, USD, …). |
| `units` | `string` |  | Scale the amounts are written in: `k` (thousands) or `M` (millions). |
| `secondary_units` | `string[]` |  | Non-monetary units the model uses (tonnes, SKU, MW, tokens, …). |
| `language` | `string` |  | Working language, ISO 639-1 (en, fr, es, …). |
| `owners` | `string[]` |  | People responsible for these conventions. |
| `sources` | `string[]` |  | Upstream systems that feed the model. |
| `glossary` | `object` |  | Company-specific or redefined terms, each with a one-line definition. |
| `inherits_from` | `string \| null` |  | Path or URL of a parent FINANCE.md (a sector or organisation template). |
| `model_id` | `string` |  | Tool-specific identifier (a Layerz model id). |

Unknown keys are kept, so a team can add its own.

## Body

The body is free Markdown. The sections agents expect and maintain:

- **Objective**: what the model builds and the deliverable expected.
- **Statements**: the structure of the P&L, the cash flow and the balance sheet, and how they connect.
- **Conventions**: signs, units, treatment of VAT, FX or one-offs.

## Reading and writing it

- MCP: `layerz_get_conventions` returns it with the workspace conventions; `layerz_set_finance_md` replaces it. It is also the resource `finance-md://model/{model_id}`.
- REST: `GET /models/:id/finance-md` and `PUT /models/:id/finance-md`.
- In the app: the model's **Context** panel.
