# Session workflow

> What an AI agent reads before it writes to a Layerz model, conventions, FINANCE.md and the model itself, and why every value depends on them.

The opening steps of every agent session on a Layerz model, from the modeling guide.

1. **Conventions first.** `layerz_get_conventions({ model_id })` returns the
   conventions of the model's workspace (the standing preferences its members
   share: conventions, tone, modelling habits, on every model of the
   workspace) and the model's FINANCE.md (currency,
   units, sign convention, glossary, objective, statement structure). Every
   value returned by the tools is expressed in those conventions: `12000` may
   be 12k EUR or 12M USD depending on `units` and `currency`. The same two
   documents come back as `conventions` in the results of `layerz_get_model`,
   `layerz_create_model`, `layerz_build_from_blueprint` and an unfiltered
   `layerz_read`, so a session that opens a model already has them.
2. **Push a local FINANCE.md.** When the local project root carries a
   `FINANCE.md`, push it with `layerz_set_finance_md({ content, source: "imported" })`
   so later writes follow the same conventions.
3. **Keep the FINANCE.md complete.** Its Markdown body documents the objective
   (what the model builds, the deliverable expected), the structure of the P&L,
   the Cash Flow and the Balance Sheet (sections, key line items, how they
   connect: net income → retained earnings, cash flow → closing cash) and the
   conventions. When any of this is missing or stale, reconstruct it from the
   live model (`layerz_read` returns every item with `role` + `parent_uid`;
   that hierarchy IS the statements structure) and persist it with
   `layerz_set_finance_md`. Update it in the same turn as any change to the
   model's identity, structure or conventions (`layerz_set_finance_md` or the
   `meta` op of `layerz_patch`).
4. **Model identity.** A model carries a `glyph`: a kebab-case Lucide icon
   name (https://lucide.dev/icons) shown as its emblem in the app and on shared
   links. When `glyph` is absent from `layerz_get_model`,
   set one coherent with the business via the `meta` op of `layerz_patch`
   (SaaS → `trending-up`, coffee shop → `coffee`, real estate → `house`,
   banking → `landmark`, energy → `wind`, HR → `users`, valuation → `scale`,
   treasury → `wallet`), without asking.
5. **Read before writing.** `layerz_read` (structure, optional values) and
   `layerz_get_model` (full detail, branches, sharing roster) are the two
   reads; `layerz_validate_model` audits the DAG. Values returned with
   `computable: false` are zero-filled placeholders: fix the model first.
6. **A `notice` is for the user.** A tool result can carry a `notice`
   (the AI actions of the billing cycle nearing the plan's cap). Relay it to
   the user in one sentence, once, and carry on with the task. Past the cap,
   the tools answer `QUOTA_EXCEEDED` with the reset date and the link to
   pass on.
