Emerald

Every debt with its principal, what has been paid, what is outstanding, how far along it is and when it projects to be paid off — plus the totals and what card installments still commit the user to. Open debts by default.

Description is built at runtime.

Remove a declared format: its declaration, its table and **every row in it**. Refused while another format links to it or folds its rows. The dry run says how many rows go; show that to the user, and call again with `commit: true` only on a plain yes. To remove some rows, use `delete_format_rows` instead.

Remove rows from a declared format by id — **a list of them in one call**. **Refused while any other row still links to one of them** — the dry run names those rows; re-link or clear them first. The app removes one row at a time from `#/formats/<name>`; this is how thirty go at once, after printing every one of them in full. Writes nothing until `commit: true`; a copy of the document is taken first, and it is the only way back.

Record that these merchants are not recurring bills, so the detector stops offering them — to this conversation and to every later one. A dismissal lasts until it is cleared; pass restore to clear it and let the merchant be suggested again. Writes immediately: it changes no transaction, no category and no bill.

In a document that keeps the `development` pack, before handing units out: for unit refs (every ready unit if left out), which can run at once and which share a path in their `paths` — one per line — and so go one after another, beside any unit in progress; a unit with no paths is unknown, never safe. Then each one’s brief, the units it waits on and the decisions it names. Read-only.

Describe an Emerald document (a .emd file): whether this plugin will serve it, the formats it declares with how many rows each holds, and — when it keeps the ledger — its accounts, transactions, categories and reporting currency. Call it when a tool refuses a document — every tool refuses one whose schema does not match, and this is the one that says so in a sentence the user can act on. Reads the file; never modifies it.

Change categories that exist — **a list of edits in one call**. Per entry: `name`, `parent_id` (any category of its kind with room — three levels at most — or null for the top level), `move` (up or down), `archived`, `monthly_target` (major units, null clears — the category’s Plan bucket in the plan in use: one figure, shared with Plan), `color` (category-1 … category-11, null for automatic), `icon`, or, alone in the entry, `merge_into` (a category id) or `delete: true` — with `move_to` (a category id of the same kind) when rows, rules, subcategories, Plan buckets, bills, debts or goals still …

Change bills that exist — **a list in one call**. Per entry: `name`, `expected_amount` (the whole charge, major units — a yearly premium is the year’s figure), `cadence`, `category_id` (null clears), `is_discretionary`, `day_of_month` (null clears), `ended_on` (YYYY-MM-DD or "today": it keeps its history and drops out of every plan); or, alone, `stop_tracking: true`, which removes it and what every plan said about it — its charges stay on Transactions. How it is recognised in the ledger is not changed here. Adding is `track_fixed_expenses`; what it does to a plan is `set_fixed_expense_roles`. …

Change a format this document **already** declares, as its table does: add `columns`, `claims`, `computed` columns, `unique`, `constraints`, `rollups` and `aggregates` as `declare_format` takes them; `rename`, `change` or `remove` what it has; `order` the columns. A rename keeps its values. Refused, naming the rows: a `required` column on rows, removing a column holding values, a list the rows do not fit, a type or unit change over values. Writes nothing until `commit: true`.

What looks like a recurring bill in the imported transactions but has not been confirmed as one: the merchant, the typical charge and its amortized monthly share, the cadence, how many months it was seen in, how much the amount and the day move, and how confident the detector is. Merchants already tracked or previously dismissed are excluded. This is the question `fixed_expenses` answers the other half of — that one lists what is already committed. Reads the document; changes nothing.

The bills the document tracks: what each is expected to cost, its amortized monthly equivalent, its cadence, whether the amount is fixed or variable, what it is matched against in the ledger, and whether the user marked it cuttable. Active ones by default.

What the engine can see is wrong in a format’s rows, without a rule anybody wrote: a link empty where most rows fill it, rows the same in every column, claims failed or unchecked. `read_onto_format` says it after every read. Reads only.

A rollup a format declares, run: a figure per month, and per linked row. `formats` lists them. A month with a row that cannot answer is `unchecked`, naming it; money stays per currency. Reads only.

The rows this document holds of one declared format. Ask `formats` first for the column names — they belong to the document. `match` filters on exact values (text and enum members case-insensitively; a list column, the rows holding the one named), `search` a substring in every column as shown (a price as 12.90, a link by its row’s name) but yes/no, and `order` sorts by any column, computed too — by default the one a row is named by, which is its first text column. Narrow `columns` to get a table of just those — a computed column (a total, or one worked out from the row) by its name too; leave …

What kinds of thing this document holds — every format declared in it, with its columns, their types, units, bounds and enum members, and the prose the author wrote around them. The columns are declared per document: `start_here` ends with one line per format, enough to write a row, and this is the whole declaration. Name a `format` for its full column list; omit it for the list of what is declared. Reads the file; never modifies it.

Not for a model: a view drawn in the conversation calls it with its own key to fetch its document, and any other call is refused. Read rows with `format_rows`.

Every pension, study fund, provident fund and managers’ insurance the document tracks: the latest transcribed balance and how old it is, the management fee as stated and as measured against what was actually charged, what the dormant ones cost a year, and — the point of the feature — **whether the paychecks and the fund’s own report agree about what was deposited**. A fund finds its paycheck lines through the deduction types that pay into it — `set_deduction_types` sets that link. Name one with fund_id to also get its readings, its return window by window, and the working behind that check. Re…

What each open goal will hold in N months, by plain addition of the amount Plan puts toward it each month (no interest counted), and what a month would have to be to reach it on its date. The same view as the Goals screen.

In a document that keeps the ledger: the places worth setting up, in order — reading statements and paychecks, making the list of categories yours, giving each merchant a category, the bills, the plan, the opening balance and the cushion — with which are done and what the document shows for each, and the tool that does each one. The same list and the same checks as the app’s Guide me. Call it after create_document, or when the user asks what is left to set up. Reads the document; changes nothing.

Import a card or bank statement into an account, through the app’s own pipeline: the same parse, the same dedupe by natural key, the same rules applied on commit. **Dry-runs by default** — it reports what it would import and how the parse compares with the total the file prints for itself, and writes nothing until commit is true. **A file whose printed total does not reconcile is refused**, because importing over it puts numbers in the ledger the file itself says are wrong. Re-importing the same statement is safe: duplicates are matched and skipped.

Backs the document up now: a copy as it is, in Emerald’s folder, named for what it comes before (`work.before-20261006T120512-cleanup.emd`), and says where. A read or batch of 100+ rows keeps one by itself; ask before anything else worth undoing. The last 3 are kept, apart from the rolling copies.

Keep packs in an existing document (the Packs screen’s *Keep this pack here*): declares the pack’s formats it lacks, adds missing optional columns to those it holds, renames a column the pack renamed with its values, changes no row; a pack kept already is brought up to date this way, its formats’ notes and views’ settings too wherever the document still holds an earlier build’s — one a person changed is kept, and the dry run names it. Refused, naming the column, where a format of the same name is not the pack’s. Dry run until `commit: true`.

In a document that keeps the `development` pack: a unit’s closing pass in one call, for a list of units by `ref`: their new `decisions` (date, milestone, scope and `state: live` default to the unit’s), the unit to `built` with `landed` (default today), `files` and `decision` (default its first new one), its `review_entries` (`state: open` default), `close_milestone`, its git `commit` (refused without one unless `same_commit: true`) and `branch` (another than the claim’s refused unless `other_branch`), and the `report` of the session that built it. Or `inbox`: ids of a child’s proposals — an in…

One month already added up: income, expenses, balance, savings rate; how each compares with last month, the three-month average and the same month last year; the category breakdown rolled up to parents; the fixed-versus-variable split; and where the income came from. Defaults to the current month. Every figure comes from the same call the app own Insights screen makes, so they cannot disagree.

Remember what this conversation suggested for merchants that were **not** categorized — a category the user declined, or a name nobody could identify — so the next conversation does not ask about the same names again. Shown in the Asked about column of uncategorized_merchants, cleared automatically when a merchant is categorized. Writes immediately: it changes no transaction, no category and no rule.

Pause goals for a number of months, or start them again, **several in one call**. A paused goal is skipped by the projection and gives its monthly amount back to what is left in Plan for those months; it is not deleted and keeps its history. `months` counts this month: 1 skips this month only. 0 starts the goal again. Plan's own bucket is left alone. **Dry-runs by default**; the document is copied to a timestamped .bak first.

Every paycheck recorded in the document — gross, net, the employer’s own contributions, total compensation, the effective tax rate, what payroll put away, and whether each itemization reconciles to its net. Plus the salary months with no paycheck at all, per-year totals, and **the deduction-type vocabulary with its ids**, which is what a line of a new paycheck has to name. Reads the document; changes nothing.

One plan worked out for one month: net pay, the bills out of net, what is left to split, each bucket’s amount and share, what it actually got lately, when a goal is reached at this rate, money with no job to do — and what *using* the plan for that month would write (a planned deposit into a goal, a planned payment on a debt). **Dry-runs by default**, which is also how you read it; `commit: true` writes those suggestions and gives the month this plan. `months` instead gives a list of months this plan and writes nothing else, and `back_to_default` puts months of this plan back on the default — t…

The Plan screen as rows: each plan with what every bill does to it (out of net, part of the split, or ignored) and its buckets — what each is for (a goal, a debt, a category, a fund, an account or nothing) and how it is sized. Ids are here for `set_plan`, `set_fixed_expense_roles` and `edit_fixed_expenses`. The worked-out figures for a month are `plan_month`.

Read what the user already keeps onto a declared format: any .csv, .xlsx (or .xls) or .json of rows, a file row per table row; or **a folder of Markdown notes**, a note per row: `title`, `file`, each frontmatter key, `inline tags`, `body links` and `body`, with a link read from `[[name]]` or `[text](file.md)`; a body link naming no row is left out and named, the note still read; a hidden file is not read; links between notes of one folder are filled; `items` reads list items or table rows onto another format, each linked to its note. **Dry-runs by default**: the reader with each key’s header c…

List a declared format’s readers — one per kind of file it has read — or name and forget them. Dry-runs until `commit: true`. Forgetting takes back no row.

Record payments against a debt — **several in one call**. The amount is a magnitude; the direction is known. A payment is **all principal** unless it names an interest portion, because v1 has no amortization schedule. Paying more than is outstanding is allowed and is flagged. **Dry-runs by default**; the document is copied to a timestamped .bak first. Payments the app discovered at import are a separate thing and are confirmed in the app.

Record money moving in a goal — **several in one call**. Six modes: DEPOSIT, WITHDRAWAL, TRANSFER between holdings, OPENING for what was already there when tracking started, and GAIN / LOSS for what the market did. **The mode carries the direction; the amount is always positive.** OPENING, GAIN and LOSS are in the balance but are not money the user set aside, so they are kept out of the savings rate. **Dry-runs by default**; the document is copied to a timestamped .bak first. Editing and deleting a movement are app-only. A DEPOSIT here is money **set aside** by hand, still inside the bank; dep…

Write rows into a declared format — **a list of them in one call**. The columns belong to the document — `start_here` lists them, `formats` in full — and a key the format has not got refuses the batch rather than being dropped, because a figure you believe you stored and did not is worse than one you know is missing. A `money` column takes the amount in major units beside its own `<column>_currency` key, and a `quantity` column takes the figure beside a `<column>_unit` key naming a unit this document knows — `amount: 200` with `amount_unit: ml`. A `link` takes the row’s id, its name (first tex…

Transcribe what a pension, hishtalmut, provident or managers’-insurance report says into the document — **several readings in one call**. Each entry names a fund by fund_id or by name, and carries one reading: the balance and its date, plus whatever else the report printed. A name that matches no fund creates it, once per batch, so four quarterly reports for one fund are four entries naming the same fund. **Leave out anything the report did not state** — an empty field means "not stated", and a 0 would be read as a stated zero. **Dry-runs by default**: it returns what it would write and writes…

Write what a statement printed each holding was worth on a day — **a list in one call**. Transcribed, never fetched: there is no price feed. `value` is the worth as printed, in major units; `quantity`, `cost_basis` and `price` are optional and each is a check: the cost against what the rows that name the holding put in by that day, the quantity against their quantities, quantity × `price` against the value (a price printed in agorot is divided by 100 first — the check catches it when it is not). An account’s own cash holding takes a value only, checked against the account’s running balance. A …

Write what a broker’s (or any account with holdings’) statement printed — **the whole file in one call**: its movements onto the account, and its holdings table as dated readings. **You read the file** — a PDF, usually — and send what it printed; nothing here parses it. Each row is the **value date**, the description as printed, the signed `amount` (a buy negative, a deposit or a sale positive; a fee printed in its own column is already inside the amount), and `cash_after`, the cash balance the statement printed after it. A buy or a sale also names the `holding` and the `quantity` (bought posi…

Write paychecks into the document — **several in one call**, one entry per paycheck. Each needs the salary month, the payment date, gross and net; an itemization is optional, and each of its lines names a deduction type by id from `paychecks`. Read a paycheck PDF or photo yourself and this is where what it says goes. **Dry-runs by default**: it returns what it would record, including whether each paycheck’s itemization reconciles to its net, and writes nothing until called again with commit true. Nothing here deduplicates — a second paycheck for a salary month is allowed, because a 13th salary…

Teach this document a unit it does not know — `slice`, `IU`, a tablespoon that is 20 ml in this kitchen. A unit is what a declared column says its figures are in and what a claim's `in` converts into, so a conversion the document cannot make is a conversion this fixes. **The engine converts inside a dimension and never across one**: grams to kilograms is arithmetic, millilitres to grams needs a density, and a density is a column of the format rather than a unit. A symbol the document already has is corrected — its factor and its note, never what it measures. `currency` sets the document’s curr…

Goals and where the money is: net worth — the one figure Overview shows, with its parts (in the bank, in accounts with holdings, locked, pension and hishtalmut funds, owed) — each goal balance broken into the four ways money got there, and the monthly expense figure the emergency-fund target is measured against. Open goals by default.

Every row of every format, and the rest of the file, that holds any of `terms`: each hit by format, row and column, columns searched as shown. One call where `format_rows`’ `search` is one a format. Or `denylist`, a `--replace-text` file: the scan before a document is shared — hits only, a term named by its line, and the file’s bytes checked for a deleted value. Reads only.

Say that a bank merchant pays a credit card — **a list in one call**. Give the bank `transaction_id` and the `card_account_id` it pays (ids from `document_info`); omit the card to take the answer back. This is *This pays a card* on a Transactions row and on a By merchant row. Optionally `counts` says whether those bank rows count in the totals: false leaves them out, because the card’s own rows already hold that money. **Dry-runs by default**; commit with `commit: true` once the user has said yes.

Set the cushion. **What is in the bank** is the latest statement balance of the bank accounts that count — **every bank account and cash, until `accounts` unticks it**; **each goal saved in one of them holds its part** (its deposits into that account’s own cash holding), and **the cushion is what is left**, against a target of `months` of bills plus the Plan `buckets` (Groceries, say) counted beside the bills. No goal is the cushion and setting it makes none. Goals holding more than an account, or than the whole, is a failed check, never shrunk to fit. Every answer ends with the split as it st…

Everything the deduction types screen does, for **several types in one call**: **make** a type (its name, what the paycheck calls it, its kind), **rename** one, change its kind, **remove** one, put the list in **order**, and say what each type **counts as** (out of net, saving — the two flags every paycheck figure turns on) and what it **pays into** — a fund or a goal for a saving line, a debt (a payroll loan) for a loan repayment. **This link is how a fund finds its paycheck lines**: a pension line is a deposit into a fund only because its type names the fund, and `funds` checks those deposit…

Leave transactions out of every total — **a list of ids in one call** — or count them again with `excluded: false`. A row left out stays in the ledger and is shown marked; it is simply not summed. This is what the Transactions screen’s row menu does: a card bill the bank statement shows as one charge is the same money as the card statement’s rows, and counting both doubles the month. **Dry-runs by default** and says how much it would take off the totals; commit with `commit: true` after the user has said yes. The document is copied to a timestamped .bak first. Ids come from `transactions`.

For each bill, per plan: `net` (comes out of net pay before the split), `split` (is one share of the split, drawn on the bar) or `ignore` (this plan leaves it out). **A list in one call.** A bill the paycheck already took (a pension deduction) is outside the choice and refused. An expense with no choice made is ignored. This is the Plan screen’s switch on every row. **Dry-runs by default**: it shows each change and writes nothing until `commit: true`; the document is copied to a timestamped .bak first. Ids come from `plans`.

Set the monthly amount toward a goal, or the extra on a debt: the Plan bucket for it, in the default plan. The difference comes from (or goes back to) Plan's Everything else, as on the Goals and Debts screens; a goal or debt with no bucket gets one. **Dry-runs by default**; the document is copied to a timestamped .bak first.

Say what feeds each goal, **several in one call**. **One feed per goal, never both**, so nothing counts twice: either a **Money moved category** — a transaction categorized under it is a deposit into the goal, read from the bank — or, with `from_holding: true`, **the rows that name its default holding**: every buy or sale of that holding inside an account that holds things (`set_transaction_holdings`) is a deposit, and the bank transfer that brought the cash there feeds nothing — or, with `from_transfers: true`, **the confirmed transfers into the bank or cash account whose own Cash is its defa…

Says months had no pay — between jobs, unpaid leave — so no paycheck is missing for them: Home stops asking "No paycheck for …" and `paychecks` stops listing them as gaps. `no_pay: false` takes it back. Stores the answer only; no paycheck and no figure. **Dry-runs by default**; the document is copied to a timestamped .bak first.

Say what each bank or cash account **held before its first statement**, and the day that stands for everything before — **several in one call**. A document cannot read this off a file. The answer shows the check it buys: opening, plus what the statements moved since, has to equal the balance the last statement ended on, and the row says by how much when it does not. `clear: true` forgets one. A credit card has none. **Dry-runs by default**; the document is copied to a timestamped .bak first.

Say which account each place on Net worth is — the bank account, the broker, the savings account whose statements show its money — **several in one call**. A place *links* to an account and is not merged with it: a deposit or cash at home has no statements and names none (`account: null` takes a link away). A card cannot be named, and an account is named by one place at most. The account gets its own cash holding in the place, made with the link — or `cash_holding` picks one already there, such as the holding goal deposits already land in. Unlinking keeps the holding. A bank account or cash ha…

What the Plan screen does to a plan — **a list of entries in one call**. Per entry: `plan_id` for an existing plan, or `create: true` with `name` (and `copy_of`, a plan id, to start from its sizes and its choices for the bills); then any of `name`, `make_default`, `basis` ({kind: LAST_PAYCHECK | AVERAGE_LAST_N | SPECIFIC_PAYCHECK | CUSTOM_AMOUNT, amount, months, paycheck_id}) — a bonus month is a plan whose basis is an amount — and `buckets`, **the plan’s whole list of buckets** as the screen’s bar has it: each {bucket_id (existing) or name (new), points_at: {kind: goal | debt | category | fun…

Name the holding a transaction bought or sold, and how much of it — **a list in one call**. Such a row is cash turning into a holding inside one account (a broker buying a fund, a savings account opening a deposit): it counts in neither came in, went out nor moved, and the holding’s quantity is the sum of its rows’ quantities. `quantity` is a count of the thing, never money — bought is positive, sold negative, up to six places. `holding: null` clears both. The holding must sit at a place that names the row’s own account, or at one that names none, and is never an account’s own cash. Holdings a…

Write the note on a transaction — **a list in one call**. An empty `note` clears it. This is the row menu’s *Add a note*: a line about one charge that is worth remembering. **Dry-runs by default**; commit with `commit: true` after the user has seen the table. Ids come from `transactions`.

Answer, for a goal, whether money **set aside** (promised to it but still inside the bank) is still there. A set-aside amount nobody has confirmed for more than 90 days is the one that is asked about; `goal_projection` lists them. `still_there: true` records today against them so they are not asked about again for 90 days. `false` withdraws them from the goal, with the reason written, so the balance stops counting money that is gone. Several goals in one call. **Dry-runs by default**; the document is copied to a timestamped .bak first.

Shows the person one declared format as the app draws it — its table, its list (one line per row, a tick, grouped as `arrange_views view:list` says), or its board, roadmap or ready-to-start list when the format has one; or the agenda, every dated format’s rows from today; or a dashboard (no `format`: the document’s) — in the conversation, in a client that draws MCP Apps; the answer’s first line says whether this client said it draws them. Call it when they ask to see a format, or some of its rows: `match` and `search` filter exactly as `format_rows` does, and the view draws only those rows and…

Set merchants aside in the By merchant queue — **a list in one call** — or put them back with `skip: false`. "I do not know what this is" is a real answer to a cryptic bank transfer; a skip writes nothing to any transaction. Names are the normalized ones `uncategorized_merchants` prints. **Dry-runs by default**; commit with `commit: true`.

Call first. Answers the questions this document’s own views say a session starts from — what is ready to start, what is open, the latest entries — each with the `format_rows` call that lists it whole; then what a row of each format looks like, enough to write one; and where new work begins: `formats`, then `read_onto_format` (files or a folder of notes) or `declare_format`. Read-only.

Read a card or bank statement (.xlsx, .xls, .csv) and report what is in it: which sheet, where the header row is, what each column looks like and what the app guesses it is, the first rows verbatim, and whether a reader already recognises these columns. Changes nothing — call this before import_statement so the user can confirm the columns. **The user maps the columns; the app only guesses**, so show them this and ask.

Writes the document again as `text` (diffs in git) or as `sqlite` bytes, and every later write keeps that shape — the app’s Save as text. Refused when the text would not carry it — a document keeping the ledger, for one. Writes nothing until `commit: true`.

Suggest each goal's monthly amount: goals by nearest date (no kind of goal goes first), each taking what gets it there on its date until what Plan has for goals runs out (what they take now plus what is left after every bucket). A goal with no date is sized as a year of what is missing; a reached, target-less or paused goal gets nothing. The preview is the suggestion; `commit: true` writes it through the same rule a typed amount on Goals uses, so the rest of the split moves with it. **Dry-runs by default**; the document is copied to a timestamped .bak first.

Take back the rows one file wrote onto a declared format — **exactly those rows and no others**. Called with no `reading`, it lists every file read onto the format with when, and how many rows each still has. **Dry-runs by default** and writes nothing until `commit: true`. **The reader is kept** (forgetting one is `readers`), so supersede → correct the file → read it again is one call each. This is how a file read twice stops being two copies; a file is matched by its bytes, never row by row.

Turn recurring charges into tracked bills — **several in one call**. An entry either names a `merchant` from fixed_expense_candidates, in which case the charge, cadence and category come from the detector unless overridden, or gives a `name` and an `expected_amount` for a bill the ledger cannot see, like an annual premium paid by standing order elsewhere. **Dry-runs by default**: it returns what it would track and writes nothing until called again with commit true. Confirming the same merchant twice updates the row already covering it rather than adding a second. The document is copied to a ti…

A filtered page of the ledger, plus the totals over every matching row — not just the page. Filter by date range, account, category, uncategorized-only, merchant search and amount bounds; sort by date, charge date, merchant, category or amount. Use this to answer "what did I spend at X" and to show the evidence behind any figure.

Lists the transfers between two of the person’s own accounts that imports have found: a row leaving one account and the same amount arriving in another within a few days. Undecided ones by default; `answer` reads the transfers or the rows that are not one. An answered transfer is neither income nor spending. `answer_transfers` answers them.

The uncategorized backlog, grouped by merchant: how many rows each merchant has, and what the user has already categorized other rows of the same merchant under. Ordered by the largest single-currency outflow, which is not printed. Start a "help me categorize" conversation here.

Give an account a real name and the last 4 digits of its card or number. The digits are what matches an imported statement to the right account, and what identifies a card charge on a bank statement, so they are worth asking for. Account ids come from document_info.

Change columns of rows already stored — **a list of edits in one call**. Each names its row by `id` or by `where` (`{ref: "INV-0042"}`, which survives another writer; a text document renews ids on every write), and the `values` to change. `expect` (`{state: "planned"}`) refuses the batch unless the row still holds that, so two sessions cannot both take one row. Every column not named is left exactly as it was, which is the difference between this and the app: `#/formats/<name>` shows a person every column and writes every column, and this corrects three of thirty across a batch. A required col…

One year already added up: income, expenses, balance and savings rate; averages over the complete months only; the best and worst month by balance; a month-by-month table where a month with no data reads as nothing rather than as zero; and what the paychecks say about gross, tax and payroll savings. Defaults to the current year.