@datarails-ai/dr-cli 0.0.1-locked → 1.6.71

package/dist/skills/fx-conversion-matrix/SKILL.md

@@ -0,0 +1,763 @@
+---
+name: fx-conversion-matrix
+description: Use when getting FX rates into a Datarails customer's tables and converting any currency to any other — whether the rates come from a provider feed (XE, quoting everything against USD) or from a file the customer supplies themselves. Builds a monthly-rolling conversion-matrix filebox, lands a rate column per reporting currency and rate type (average, closing/spot, plan), and wires those into the business tables as lookups. Triggers - "import FX rates for <org>", "build an FX conversion matrix", "convert currencies to each other", "cross-rate from USD", "triangulate FX rates", "the customer sent us their own rates", "load their budget/plan rates", "add avg and closing rate columns", "wire FX rates into Financials", "register a custom currency", "roll the FX file forward a month", "add FX to the calc models". Tagging existing Monetary fields currency-aware instead is dr-cli:fx-onboard; installing or updating the CLI is dr-cli:install (or `dr update`); the full dr command reference is the dr-cli skill.
+allowed-tools: Bash, Read, Write
+---
+
+# FX conversion matrix — get rates in, and cross-rate them onto the tables
+
+Takes FX rates from wherever the customer has them — a provider feed, or a
+spreadsheet they maintain themselves — and produces what they actually need: any
+currency converted to any other, as real columns on their tables, refreshed every
+month without anyone editing a formula.
+
+This skill teaches the FX-import flow, not the CLI. The `dr-cli` skill is the command
+authority for every command used here, and its **Auth** section covers login and
+identities. It ships both in the Claude Code plugin and in the npm package, so it is
+loaded wherever this skill is.
+
+**Scripts live in this skill's own `scripts/` folder,** the base directory Claude Code
+prints when it loads the skill. That is the same whether it came from the `dr-cli`
+plugin or from the npm package (`~/.claude/skills/fx-conversion-matrix/`).
+The commands below write it as `<skill-dir>/scripts/…`.
+
+**Division of authority:** the commands own mechanics — ids, payload shapes, what a
+flag does. This file owns *order*, *which shape and wiring apply*, and the failure
+modes the commands cannot see. Where the two disagree, believe the command output
+and fix this file.
+
+## What this is not
+
+Not `dr-cli:fx-onboard`. That skill makes **existing** Monetary fields currency-aware
+so widgets and DR.GET auto-convert (`fx_role`, `is_fx_aware`). This skill builds a
+**standalone reference table of conversion rates** and lands them as ordinary Float
+columns, usable anywhere.
+
+**This one runs first.** The FX selector does not convert — it swaps to a sibling
+column that already holds the amount in the chosen currency
+(`FxReportingFieldResolver`). Those per-currency columns have to exist before
+`fx-onboard` can tag them, and computing them is posting amount times a rate. This
+skill is where the rate comes from. Land the rates here, compute the reporting
+amounts, then run `fx-onboard` to make them selectable.
+
+## Inputs to collect before starting
+
+| Input | Why | How to confirm |
+|---|---|---|
+| Org + data centre | every command needs `--server` / `--account` | `dr whoami --server <S>` |
+| Where the rates come from | feed vs customer file — changes Step 0 only | ask |
+| Rate **shape** | single-base or directed pairs | **detect, Step 0b** |
+| Rate **types** | avg / closing / plan — one column each | ask; most customers need ≥ 2 |
+| Currencies | one tab + columns + mapper each | ask; never infer |
+| Target tables | where the rates must land | ask |
+| Wiring (A or B) | changes the workbook layout | see Step 7 |
+
+## Use UDM field names
+
+Every field this skill touches or creates follows the UDM convention, so the tables
+stay readable by MEC, reconciliation and everything else that assumes it. Aliases are
+the display name lowercased with spaces as underscores.
+
+| Display name | Alias | Type | What it is |
+|---|---|---|---|
+| `Posting Amount` | `posting_amount` | Float | the balance in local currency |
+| `Posting Currency` | `posting_currency` | Text | the local currency it was posted in |
+| `Reporting Currency` | `reporting_currency` | Text | the consolidation target |
+| `Reporting Month` | `reporting_month` | Date | **last day of month, 00:00:00 UTC** |
+| `Currency AVG rate` | `currency_avg_rate` | Float | period-average rate, for P&L |
+| `Currency EOP rate` | `currency_eop_rate` | Float | end-of-period rate, for balance sheet |
+| `Reporting Rate` | `reporting_rate` | Float or Text | the rate actually applied to a row |
+
+**`Reporting Rate` is derived, not a third source rate.** It picks between the other
+two by statement type, and the reporting amount is `Posting Amount × Reporting Rate`:
+
+```
+Amount = IF([Account Group L0]=="Balance Sheet",[Currency EOP rate],[Currency AVG rate])*[Posting Amount]
+```
+
+Get that condition wrong and it fails silently: a literal that never matches makes
+every row fall through to the AVG branch, so balance-sheet figures are translated at
+the wrong rate and nothing reports it. On a single-currency tenant it is invisible,
+because AVG and EOP are both 1.
+
+**`Reporting Month` being last-day-of-month is a UDM rule, not a preference** — and it
+is the same normalisation Step 4 needs anyway, since `DR.MONTH()` cannot match raw
+daily timestamps. `EOMONTH([Posting Date])` satisfies both.
+
+### The currency goes in the name only when it is needed
+
+UDM models **one** reporting currency per table, so a single-currency table needs no
+currency in its rate column names — and leaving it out is what keeps the plain UDM
+name that MEC and reconciliation look for. Add the currency only once there is more
+than one, and keep the UDM stem when you do. `build-matrix.mjs` climbs that ladder on
+its own:
+
+| Reporting currencies | Column name | Set by |
+|---|---|---|
+| one | `Currency AVG rate` | default |
+| several | `EUR Currency AVG rate` | default, once `--targets` names more than one |
+| several, source worth stating | `Currency USD to EUR AVG rate` | `--column-pattern "Currency {base} to {ccy} {type} rate"` |
+
+All three forms already exist in the reference org, so none of this is a new
+convention — the org has `Currency AVG rate`, `GBP Currency AVG rate` and
+`Currency USD to GBP AVG rate` side by side today. Pattern tokens are `{type}`,
+`{ccy}` and `{base}`; `{base}` is refused in pairs mode, where the source currency
+varies per row and there is no one base to name.
+
+## Build on what is there. Never replace it.
+
+A customer who already has any FX setup has it for a reason, and someone is
+already reading those numbers. **Inventory before you create anything**, and
+extend what you find rather than standing up a parallel copy beside it:
+
+```bash
+dr lut list --table <business_table> --json      # existing lookups, and of which kind
+dr templates get <business_table> --json         # rate columns they already have
+dr templates get <fx_table> --json               # and on the rates table
+dr datamappers list --table <fx_table>           # existing mappers
+dr functions list --template <fx_table>          # existing rate functions
+dr filebox data-query get <fx_filebox>           # an existing query and its schedule
+```
+
+Read each result as a decision:
+
+| What you find | What to do |
+|---|---|
+| A lookup with `document` set (filebox-sourced) | **Extend that one.** Do not add a table lookup beside it. |
+| A lookup with `source_template` set (table-sourced) | Extend it — re-send its existing fields plus the new ones. |
+| Rate columns that already exist | Reuse the names. A second column meaning the same thing is worse than an ugly name. |
+| A function already on the rate field | Reuse it. Functions are cheap to make and confusing to duplicate. |
+| A data-query already syncing | Leave its schedule alone. Widen the query, do not replace the connection. |
+| Nothing | Only then are you choosing, and Step 7's wiring A is the default. |
+
+**Naming is part of this.** If their columns read `Avg EUR Rate`, use
+`--column-pattern "{type} {ccy} Rate"` so yours match. Matching an existing
+convention matters more than the convention you would have picked.
+
+## Order is not optional
+
+```
+rates table exists → register custom currencies → detect shape → functions
+  → filebox → workbook → register functions → upload + tag + calculate
+  → rate columns → lookups → verify types on EVERY table → calc models
+```
+
+---
+
+## Step 0a — Get a rates table
+
+### If a provider feed already lands one
+
+```bash
+dr filebox get <fx_filebox_id> --server <S> --json     # → template_status[].table_template
+dr templates get <table_id> --server <S> --json
+```
+
+### If the customer supplies their own file
+
+Same destination, one extra hop: their file becomes a filebox, and a mapper lands it
+as a table.
+
+```bash
+dr filebox create --name "<Name>_FX_Rates" --scenario Actuals \
+  --date-sub-type month --parent <folder_id> --server <S> --json
+dr filebox upload-version <filebox_id> --file their-rates.xlsx --server <S> --json
+dr filebox set-version-date-tag <version_id> --month <YYYY-MM> --server <S> --json
+```
+
+Then a mapper onto a new (or existing) table, mapping at minimum: the currency
+column(s), the period column, and one column per rate type. `dr datamappers create
+flat` handles the common single-header-row sheet; `from-file` is the power path.
+**`--field` on `flat` keys on the CSV HEADER, not the table field.** Every CSV column
+defaults to `Text` (CSV values are strings) and `--field` overrides that — but the lookup
+uses the column name as it appears in row 1 of the file, *before* any `--rename`. So with
+`--rename "mid=FX Rate"` the override is `--field "mid:Float"`; writing
+`--field "FX Rate:Float"` matches no header, silently does nothing, and the column lands
+`Text`. Nothing warns you, and `datamappers get` omits `fields_to_change` from its
+response — so you cannot confirm what was sent by reading the mapper back. Check the
+column type on the table instead.
+
+### First import: 24 months, not one
+
+A first import backfills **24 historical months**, so variance against last year
+works from day one and nobody has to come back for it later. On a data-query
+filebox that is one call with one `--date` per period (the flag repeats):
+
+```bash
+dr filebox data-query sync <filebox_id> --date 2026-08-01 --date 2026-07-01 ... --server <S>
+```
+
+Each period lands as its own version, named for its month. Verified: 24 dates in
+a single call produced 24 versions, September 2024 through August 2026. The sync
+is asynchronous — poll `dr filebox data-query get <id>` until `status` leaves
+`SYNCING` before trusting a version count.
+
+Afterwards the ongoing schedule takes over; `sync_offset_array: [0, -1]` re-syncs
+the current and previous period on each run, which is what picks up a late
+correction to last month.
+
+For a customer file, 24 months means 24 tagged versions, or one file carrying a
+period column. Ask which they have before assuming.
+
+Customer-maintained rate files are usually *plan* or *board-approved* rates, not
+market rates. Do not assume a monthly cadence, and do not assume they will be
+updated on time — ask who owns the file and how the new month gets in.
+
+### Either way: do not trust field names
+
+A rates table that has been iterated on collects plausible-looking dead fields. The
+reference org's FX table carries eight of them — `Currency AVG rate`,
+`Currency EOP rate`, `GBP Currency AVG rate`, `GBP`, `USD to GBP`,
+`Currency USD to GBP AVG rate`, `Rate to GBP` — all either null or hardcoded to one
+currency. The live field was plainly named `FX Rate`.
+
+```bash
+dr templates distinct <table_id> --field "Posting Currency" --server <S> --json
+dr templates aggregate <table_id> --group-by "Posting Currency" \
+  --group-by "Reporting Month" --metric "<rate field>:AVG" --server <S> --json
+```
+
+A field is live when **every** currency moves month to month. An existing function
+pointing at a field is not evidence the field is populated.
+
+### The period field must be month-normalised
+
+A feed that arrives daily (XE lands one row per currency per day) gives a period column
+full of timestamps like `2026-08-01T00:00:00+00:00`. `DR.MONTH(DR_TAG_DATE)` does **not**
+match those, and the matrix computes **all zeros with no error** — a third silent-zero
+cause on top of the two in Steps 4 and 5. Derive a month column and point the matrix at it:
+
+```
+calculated_fields: [{ name: "Reporting Month", formula: " EOMONTH( [Posting Date] )" }]
+```
+
+`EOMONTH` needs its input to already be a `Date`. If the source column is still `Text` the
+calc silently produces no column at all — no error, the field simply never appears. Pin the
+date column's type in the same mapper (`from-file --field "Posting Date:Date"`), not
+afterwards.
+
+> **`templates set-field-type` does not survive a rescan.** Retyping a column after the fact
+> works, and is then silently reverted the next time the table is rescanned, because the
+> mapper re-infers from the source. Types must be pinned in the mapper. The one place
+> retyping is the only option is a lookup target (Step 7b), which has no mapper.
+
+## Step 0b — Detect the shape, and stop if it is ambiguous
+
+Two shapes reach this skill, and they are converted completely differently. Detect;
+do not assume.
+
+**The structural signal is how many currency dimensions the table has.**
+
+| Currency dimensions | Shape | Meaning |
+|---|---|---|
+| one (e.g. `Posting Currency`) | `single-base` | every rate quoted against one currency |
+| two (e.g. `Posting Currency` + `Reporting Currency`) | `pairs` | directed pairs, supplied as-is |
+
+Then confirm against the data, and **stop rather than guess**:
+
+```bash
+# single-base: exactly ONE code must be 1.0 in every period -- that is the base
+dr templates aggregate <id> --group-by "Posting Currency" --metric "<rate>:AVG" --server <S> --json
+
+# pairs: which (from, to) combinations actually exist
+dr templates aggregate <id> --group-by "Posting Currency" \
+  --group-by "Reporting Currency" --metric "<rate>:AVG" --server <S> --json
+```
+
+**Stop conditions — report to the implementor, do not proceed:**
+
+- **No currency is always 1.0** in a one-dimension table. The base may not be present
+  as a row, or the field is not what you think. Ask.
+  - **This is the normal case for a provider feed.** XE quotes every currency *against* the
+    base and never against itself, so a real XE extract contains no USD row at all. The
+    matrix needs that 1.0 anchor — to convert *from* the base, and to anchor the target
+    column when the target *is* the base. Inject it as a **separate document and mapper**
+    into the same table (one row per period, rate `1`), which is what the reference org's
+    own `fx_integration_usd` mapper does. Do not edit the provider's file to add it: the
+    feed should stay exactly as it arrived.
+- **More than one currency is always 1.0.** Either the data is wrong, or these are
+  pegged currencies and the base is genuinely ambiguous. Ask which is the base.
+- **Pairs mode with gaps.** Every (source, target) the customer wants must be
+  present. List the missing pairs and ask for them. **Never derive a missing pair.**
+  Triangulating through a pivot currency invents a rate the customer never agreed
+  to, and the result is indistinguishable from one they did. If they explicitly ask
+  for it, convert their file to single-base against that pivot instead — then the
+  derivation is visible in the workbook rather than hidden in this step.
+
+> **Pairs mode cannot detect its own gaps later.** A pair the source lacks returns
+> `0`, with no error. Coverage has to be established here or not at all.
+
+## Step 1 — Register any custom currencies
+
+A code the ISO list does not carry (`BUSD` for budgeted USD, a plan-rate code, an
+internal unit) must exist as an org custom currency **before** any field references
+it, or the Tables dialog cannot offer it back and the org list and the field drift
+apart.
+
+```bash
+dr fx default-currency --server <S>        # lists what the org can already offer
+dr fx add-currency BUSD --symbol "B$" --server <S>
+```
+
+`add-currency` refuses an ISO code, so it is safe to run over a mixed list. See the
+`dr-cli:fx-onboard` skill for how the org currency list is used downstream.
+
+## Step 2 — Create one function per rate type
+
+A Datarails function binds exactly **one** value field, so a customer who supplies
+average and closing rates needs two functions. Names take no whitespace.
+
+```bash
+dr functions create --name FX_Avg_Rate --template <table_id> \
+  --field <avg_field_id> --agg AVG --server <S> --json
+dr functions create --name FX_EOP_Rate --template <table_id> \
+  --field <eop_field_id> --agg AVG --server <S> --json
+```
+
+No persisted filters — currency and period are supplied per-cell. These are
+prod-tier writes; confirm first.
+
+## Step 3 — Create the filebox
+
+```bash
+dr filebox create --name "<Name>_Conversion_Rates" --scenario Actuals \
+  --date-sub-type month --parent <folder_id> --server <S> --json
+```
+
+Put it next to the source FX filebox (same `--parent`) so it is discoverable.
+
+## Step 4 — Build the workbook
+
+```bash
+node <skill-dir>/scripts/build-matrix.mjs \
+  --out matrix.xlsx --base USD \
+  --rate-types "Avg=FX_Avg_Rate,Spot=FX_EOP_Rate" \
+  --currencies USD,EUR,GBP,ILS --targets EUR,GBP,ILS \
+  --shape single-base --layout matrix \
+  --period-field "Reporting Month" --currency-field "Posting Currency"
+```
+
+For `--shape pairs` add `--to-currency-field "Reporting Currency"`. For wiring B use
+`--layout lut` (Step 7). The script writes `matrix.xlsx.layout.json` alongside the
+workbook — Step 6 consumes it so the two never disagree about a cell.
+
+Column names follow the ladder above — `Currency AVG rate` for one reporting currency,
+`EUR Currency AVG rate` for several — or whatever `--column-pattern` you pass to match an
+org's existing names.
+
+**How single-base converts.** Every row is quoted against the same base, so
+`rate(source→target) = rate(target)/rate(source)`, anchored on the target's own row.
+One `DR.GET` per row per type, not one per pair, and it degenerates correctly when
+the base is itself a row (its rate is 1, and the self-rate comes out exactly 1).
+
+**Pairs mode derives nothing** — each cell is a direct lookup of the supplied pair.
+
+**Argument order fails silently.** The period pair must come immediately after the
+function name, before any other dimension filter, or `DR.GET` returns `0` — no
+error, no `#NAME?`:
+
+```
+=_xll.DR.GET(FX_Avg_Rate,"[Reporting Month]",_xll.DR.MONTH(DR_TAG_DATE),"[Posting Currency]","EUR","[Scenario]","Actuals")
+                         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ this pair first
+```
+
+`DR_TAG_DATE` is built in — do not declare it; the backend resolves it at calc time
+once the file is a tagged filebox version. Wrap it in `DR.MONTH()` for a Date period
+field. For a human-readable label use `=TEXT(DR_TAG_DATE,"mmmm yyyy")` — `DR.MONTH()`
+returns a range-like pseudo-value and cannot be fed to `TEXT()`.
+
+```bash
+unzip -o matrix.xlsx -d /tmp/m && grep -o '<f>[^<]*</f>' /tmp/m/xl/worksheets/sheet1.xml
+```
+
+## Step 5 — Register the functions, then upload, tag, calculate
+
+A brand-new function has no defined name in a freshly built workbook, and `DR.GET`
+against an unregistered name **also returns `0` silently**. Register **every**
+function — repeat `--function` per rate type:
+
+```bash
+dr documents add-functions matrix.xlsx --function <avg_fn_id> --function <eop_fn_id> \
+  --out matrix_fnreg.xlsx --server <S>
+grep -o '<definedName name="FX_[^"]*">[^<]*</definedName>' /tmp/m/xl/workbook.xml
+```
+
+```bash
+dr filebox upload-version <filebox_id> --file matrix_fnreg.xlsx --server <S> --json
+dr filebox set-version-date-tag <version_id> --doc <filebox_id> --month <YYYY-MM> --server <S> --json
+dr documents calculate <filebox_id> --month <YYYY-MM> --no-roll --server <S>
+```
+
+**`--no-roll` matters.** `calculate` defaults to `do_roll=true`, advancing the tag to
+the *next* period after computing — correct for the monthly cycle (Step 8), wrong
+here: it would leave the visible version tagged to a month with no source data,
+reading as all zeros.
+
+```bash
+dr filebox download <filebox_id> --server <S> --output result.xlsx --force
+```
+
+Two cheap, high-signal checks per rate type: each tab's **self-rate is exactly 1**,
+and one **reciprocal pair multiplies to 1**.
+
+## Step 6 — Land the rate columns (wiring A)
+
+One datamapper per target currency, each writing one column per rate type onto the
+**FX table**:
+
+```bash
+node <skill-dir>/scripts/gen-mappers.mjs \
+  --layout-file matrix.xlsx.layout.json \
+  --filebox <filebox_id> --version <document_version_id> --template <fx_table_id> \
+  --out-dir ./mappers --server <S>
+```
+
+It prints a ready command per currency. The target table is the **positional**
+argument — `create from-file <table_id>`, not `--table`.
+
+**Always pass `--field "<column>:Float"` for every mapped column** (the generator
+does). A `map_to` naming a column the template lacks **bootstraps that field** — that
+is how these columns come into being, there is no add-field API — but the
+bootstrapped **type is inferred from the sample values, often Text**, and a Text rate
+column silently breaks every downstream calculation.
+
+**The body must carry no `template_id`.** In power mode that key names the *source*
+template, and the CLI resolves every `map_to` from it and **throws on any name the
+source lacks** — and that throw happens *before* `--field` overrides are merged, so
+`--field` cannot rescue it. The rate columns exist nowhere yet by design, so a body
+carrying `template_id` fails every create. (The thrown message advises `--field`; on
+this path that advice does not hold.) The generator omits it.
+
+`document_version_id` is required and is **not** in `dr datamappers get` output —
+read it from the upload response or `dr filebox versions <filebox_id>`.
+
+### Changing a mapper that already exists: remap, don't update
+
+Widening an existing feed mapper, or adding reporting-amount columns to a business
+table's mappers, means editing mappers that already exist. `dr datamappers update` is
+the obvious tool, and on many orgs **it cannot work.** A mapper created by an org
+import or template push has no source version on record. `PUT
+/api/templates/mappers/<id>` reads the mapper's source file, and for such a mapper it
+fails with a bare HTTP 500. The server log shows `AttributeError: 'NoneType' object has
+no attribute 'get_document_data'`. No request body fixes it, because the endpoint never
+reads a version from the body.
+
+Remap instead. `dr datamappers create from-file <table_id>` with the existing
+mapper's id replaces it in place and records a real source version:
+
+```json
+{
+  "name": "<existing name>",
+  "datamapper_id": <existing mapper id>,
+  "ordinal": <existing ordinal>,
+  "document_version_id": <an ACTIVE version of one of its documents>,
+  "selected_document_ids": [<its mapped_documents_ids>],
+  "sheet_name": "<a sheet that exists in THAT version>",
+  "config": { ... the edited config ... }
+}
+```
+
+- **The mapper gets a new id.** The old id stays behind bound to no documents, and
+  lookups, which live on the table, are unaffected. Keep an old→new id log for rollback.
+- **`ordinal` must be the existing one.** A lower one is refused as a duplicate mapper.
+- **`sheet_name` must exist in the version you pass**, and a mapper's
+  `preview_sheet_name` is often stale. Check with `dr filebox sheets <version_id>`; when
+  the preview sheet is gone and the version has one sheet, use that one.
+- **Use an ACTIVE version, not simply the latest.** A version in `ERROR` status cannot be
+  read, and the remap 500s with `Cannot read sheet with name '<sheet>'`. Pick the newest
+  version whose status is `ACTIVE`.
+- **Skip mappers whose documents are all gone.** A mapper can stay bound only to
+  deleted documents (`dr filebox get` returns 404). It feeds no rows, and there is no
+  version to remap against. Confirm with `templates aggregate --group-by FileBox_ID`
+  before skipping one.
+- **Widen a feed only by appending columns at the end.** A header entry keyed on a
+  column's letter keeps working when new columns are added after it. Inserting columns
+  in the middle breaks every mapper that reads the file.
+
+Pass `--no-rescan` on each remap and let Step 7's lookup rebuild drive the rescans.
+
+## Step 7 — Carry the rates into the business tables
+
+**The wiring is not yours to pick if they already have one.** Run
+`dr lut list --table <business_table> --json` first and match what is there — a
+lookup with `document` set is filebox-sourced (B), one with `source_template` set is
+table-sourced (A). Only an org with no rate lookup at all is a free choice, and then
+A is the default.
+
+**Wiring A — one table-sourced lookup per business table (the default for a fresh
+org).** The columns already live on the FX table, so one lookup carries every
+currency and every rate type:
+
+```bash
+dr lut create-table-lookup --table <business_table> --source-table <fx_table> \
+  --keys "Posting Currency,Reporting Month" \
+  --fields "EUR Currency AVG rate,EUR Currency EOP rate,GBP Currency AVG rate" --server <S>
+```
+
+**`--keys` and `--fields` take ONE comma-separated list each — they are not repeatable.**
+Repeating the flag silently keeps only the last value, producing a one-key, one-field
+lookup that looks like it succeeded. Check the `KEY_LEN`/`KEYS`/`FIELDS` counts the
+command prints against what you passed.
+
+Adding a currency later touches one mapper and one `--fields` entry, not every table.
+
+**Wiring B — one filebox-sourced lookup per currency tab.** Skips Step 6 and points
+each business table straight at the matrix file:
+
+```bash
+dr lut create --table <business_table> --payload-file ./luts/eur.json --server <S>
+```
+
+> **Wiring B needs `--layout lut` in Step 4.** A filebox-sourced LUT resolves its keys
+> **positionally from the source file's column-header row** — the first `key_len`
+> columns become the keys and the payload's `keys`/`fields` arrays are *silently
+> ignored*. Against the `matrix` layout a 2-key lookup would take `Currency` and the
+> base-rate helper as its keys. The `lut` layout puts the keys leftmost and makes the
+> period a real column. `dr lut create` prints a stderr warning when the stored shape
+> differs from what was sent — **read it**, it is the only signal you get.
+
+### Extending a lookup that already exists
+
+**Table-sourced.** `update-table-lookup` overlays only what you pass, but `--fields`
+is a whole list, not an append — so send the existing fields **plus** the new ones,
+or the ones you omit are dropped:
+
+```bash
+dr lut list --table <tid> --json          # read its current fields first
+dr lut update-table-lookup <lut_id> --fields "<existing>,<existing>,<new>" --server <S>
+```
+
+**Filebox-sourced — the important case.** A filebox-sourced lookup resolves its
+fields **positionally from the source file**, so you cannot add a field by editing
+the lookup. Widen the *file*: add the new rate column to the query or workbook that
+feeds it, re-sync, and the lookup picks the column up. Editing the LUT's `fields`
+array alone changes nothing — the engine ignores it.
+
+That is the whole reason to check first. An org on wiring B gets its new currency by
+widening their existing feed, which is a one-line change to a query. Standing up a
+table lookup beside it would leave two sources of the same rate disagreeing the
+first time one is re-synced and the other is not.
+
+Either wiring returns 202 and computes asynchronously; re-run
+`dr lut list --table <tid>` to confirm.
+
+### Build the lookup after the source has finished loading
+
+A table-sourced lookup snapshots its source table **when it is created or updated.**
+Point it at an FX table whose new versions are still being processed (a backfill that
+reads `SYNCED` but is still scanning), and it builds **empty**. Every target row then
+gets an empty rate, with no error. The only trace is in the server log:
+`total_luts_size_bytes=0`. `lut list` looks fine, and its key and field counts are
+correct.
+
+So order it: sync → wait for `dr scans status <fx_table>` to leave `in_process` →
+create or extend the lookups. If you already built one too early, re-run
+`dr lut update-table-lookup <id> --table <tid>` with any flag, for example
+`--check-misses true`. That rebuilds the lookup from the current source and triggers
+a selective rescan of the affected versions on the target table, which also picks up
+any mapper you remapped in the meantime. Rebuild again after every later backfill.
+
+Verify on the target, not the lookup:
+`dr templates aggregate <tid> --group-by "Reporting Month" --metric "EUR Currency AVG rate:AVG"`
+must be non-zero in every month the FX table covers.
+
+## Step 7b — Verify the types on EVERY table, not just the source
+
+**This is where the reference org is currently broken.** On its FX table the columns
+are Float; on Financials, where the lookup carries them, `Rate to EUR` / `Rate to GBP`
+/ `Rate to ILS` all landed as **Text**. Arithmetic on them is broken or silently
+coercing, and nothing reported it.
+
+```bash
+dr templates get <fx_table_id> --server <S> --json        # source columns
+dr templates get <business_table> --server <S> --json     # lookup targets -- CHECK THESE
+```
+
+A correct source column is not evidence of a correct target column, and **the target
+type is not predictable, so check it every time.** Both outcomes have been seen on live
+tenants with Float sources:
+
+- **Text:** why the reference org's Financials columns are Text today.
+- **Float:** 54 lookup targets across 9 tables on a DEMO tenant (2026-09). The source
+  columns had been pinned `Float` through the mapper's `--field` in Step 6.
+
+`lut create-table-lookup` has no `--field` to pin the target type. Retype every target
+that came in Text:
+
+```bash
+dr templates set-field-type <field_id> --type Float --server <S>   # plan, then --confirm-token
+```
+
+This is the one retype that sticks, because a lookup target has no mapper to re-infer it.
+
+## Step 7c — Calc models: the rows no mapper touches
+
+A calc model writes its output rows **straight into the table**. They skip the mappers,
+so the per-currency amount columns you add in the mappers never reach them. On a
+Financials table that uses Beginning Balance models, that is every balance-sheet opening
+balance: the currency columns come out empty on exactly the rows a balance-sheet report
+reads first.
+
+Find them before you call the reporting amounts done:
+
+```bash
+dr calcmodels list --server <S>
+dr templates aggregate <table> --group-by "Calc_Model_ID" \
+  --metric "Amount:SUM" --metric "Amount EUR:SUM" --server <S>
+```
+
+Rows with a `Calc_Model_ID` and an empty currency column are this step's job.
+
+### What a custom column can see
+
+Read these before you write a formula (they come from the server's calc-model engine):
+
+- **A model rolls up exactly one field**, its `agg_field`. Everything else on an output
+  row is the date field, a `group_by` field, the two `Calc_Model_*` fields, or a lookup
+  output.
+- **`custom_columns` are evaluated on the output rows, after the roll-up.** A formula
+  can only reference columns that exist on the output row. A source column that is not
+  in `group_by` is **not available**.
+- **Lookups do run on output rows, but only lookups whose keys are all on the row.** An
+  FX lookup keyed on `Reporting Month` and `Posting Currency` works when the model's date
+  field is `Reporting Month` and `Posting Currency` is in `group_by`. If either key is
+  missing, the rate is empty and the column silently computes nothing.
+- **Only `is_selected: true` columns are computed.** Only `function.formula` matters:
+  `function.type` and `function.fields` are frontend metadata that the engine ignores.
+
+### The formula
+
+Mirror the model's own value field. Most Beginning Balance models roll up `Amount`,
+which is already in the reporting currency (USD, say). Convert that balance back to the
+posting currency at the row's month-end rate, then out to each target currency at that
+currency's month-end rate:
+
+```
+Amount EUR = [Amount] / [Currency EOP rate] * [EUR Currency EOP rate]
+```
+
+A model that rolls up `Posting Amount` needs one step:
+`[Posting Amount] * [EUR Currency EOP rate]`.
+
+**Know what this number is.** It translates the whole balance at that month's closing
+rate (the closing-rate method). It is **not** the sum of each month's activity
+translated at that month's rate, which is what the model's own USD `Amount` column
+holds. The two differ whenever rates move. If the customer needs the historical-rate
+version, the only way is one extra model per currency, each rolling up its own
+`Amount <X>`. That is a separate decision for the owner.
+
+### Applying it
+
+```bash
+dr calcmodels get <id> --server <S> --json > cm.json
+# append one custom column per currency to config.custom_columns:
+#   {"id": <next>, "field": {"id": <Amount EUR field id>}, "is_selected": true,
+#    "function": {"type": "custom", "fields": [], "formula": "<formula>"}}
+dr calcmodels update <id> --file cm.json --server <S>
+```
+
+Two traps on the way:
+
+- **Decode the formulas before you PUT.** `calcmodels get` returns existing formulas
+  HTML-encoded (`&quot;Beginning Balance&quot;`), and `update` sends them back
+  unchanged. The server then fails to parse its own `Data Type` column, and the model
+  goes to **ERROR**. Nothing names the cause on the CLI side; the server log shows
+  `SyntaxError ... lambda :&quot;Beginning Balance&quot;`. Replace `&quot;`, `&amp;`,
+  `&lt;`, `&gt;` and `&#x27;` in every `function.formula` first.
+- **The CLI refuses `AUTO` on a model that writes back into its own source table**, and
+  Beginning Balance models always do. Models created before that check are often still
+  on `AUTO`, so a plain `update` is refused. Do **not** flip them to `DAILY` to get past
+  the check. That changes how often the customer's balances refresh, and it is the
+  owner's call. Either get the owner's decision, or add the columns in the Tables UI,
+  which keeps the flow as it is. Existing `AUTO` models of this kind have been observed
+  running stably, so the refusal alone is not evidence of a loop.
+
+Every save retriggers a recalculation. Poll `dr calcmodels get <id>` until `status` leaves
+`PROCESSING`. It must come back `ACTIVE`; on `ERROR`, check the decoding trap first.
+
+### Verify
+
+In a month that has rates, `Amount EUR` should equal `Amount / (EUR→USD rate)`. Check one:
+
+```bash
+dr templates aggregate <table> --group-by "Reporting Month" \
+  --metric "Amount:SUM" --metric "Amount EUR:SUM" --metric "Currency EOP rate:AVG" \
+  --filter "Calc_Model_ID=<id>" --filter "Posting Currency=EUR" --server <S>
+```
+
+**Beginning Balance rows run to the table's last month, not the last month with rates.**
+A table that carries budget or forecast rows into future years gets opening balances in
+those years too, and every one of them computes `0` in the currency columns until those
+months have rates (plan rates, usually). Report that as a rate-coverage gap, not a
+formula bug.
+
+## Step 8 — Rolling each month
+
+No re-upload, no formula edit — the `DR.GET` calls re-resolve against whatever period
+the version is tagged to.
+
+- **Recompute the same period:** `set-version-date-tag` + `documents calculate --month <M> --no-roll`
+- **Roll forward:** `documents calculate --month <current>` (default roll)
+- **Roll backward:** same, plus `--backward`
+
+A customer-maintained rate file adds a dependency here: rolling forward before they
+have entered next month's rates computes zeros. Confirm the source month exists first.
+
+---
+
+## Handing someone a rate table
+
+The chain above lands rates as *columns on tables*, which is what the product
+consumes. When a human needs to read them — a customer asking "what rate did you
+use?", an auditor, a month-end pack — a square matrix is the presentable form:
+
+```bash
+node <skill-dir>/scripts/rates-to-xlsx.mjs   --in rates.csv --out matrix.xlsx [--date 2026-08-31]
+```
+
+It takes a `from_currency, to_currency, rate, timestamp` feed — the shape a
+triangulating SQL data-query produces — and writes a square matrix for one date
+plus a `Daily Rates` tab with every pair. Column names are matched
+case-insensitively with a positional fallback, `--date` defaults to the latest in
+the file, and a pair the feed does not carry is left **blank rather than guessed**.
+
+All three scripts share `_xlsx.mjs`, the dependency-free .xlsx writer, so a fix to
+the package layout reaches every producer.
+
+## Guard rails
+
+- **Every write here is prod-tier.** Functions, filebox, mappers, lookups and custom
+  currencies are all mutations. Confirm before running on `US`, `US2`, `UK`, `CA`,
+  `EU` — **and on `DEMO`**, which is a customer-facing demo tenant, not a sandbox.
+  Prefer a `DEV`/`TEST*` rehearsal when the org is unstated.
+- **Never guess a currency, a base, or a missing pair.** Each is a question for the
+  customer. A wrong rate mislabels real money and nobody downstream can tell.
+- **Never guess the rate field.** Sample real rows (Step 0a).
+- **Datamappers bootstrap schema.** A typo in `map_to` does not error — it creates a
+  junk column on a production table. Check spelling before, and types after.
+- **Don't leave half-built objects.** An abandoned rehearsal should have its filebox,
+  functions and mappers deleted.
+
+## Common mistakes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Every cell is `0`, no error | `DR.GET` argument order — period pair not first | Step 4 |
+| Every cell is `0`, no error | a function not registered into the workbook | Step 5 |
+| One rate type is all `0`, the others fine | only the first `--function` was registered | Step 5 |
+| Some pairs `0` in pairs mode | the source never carried that pair | Step 0b — coverage |
+| Latest version reads all zeros | `calculate` rolled the tag to a month with no data | `--no-roll`, Step 5 |
+| Rates plausible but never change month to month | built on a dead leftover field | Step 0a |
+| Rate column is Text on the FX table | bootstrapped type inferred from samples | `--field "…:Float"`, Step 6 |
+| Rate column is Text on the business table | lookup target type not checked | **Step 7b** |
+| Lookup returns nothing / wrong values | filebox-sourced LUT took the wrong columns as keys | `--layout lut`, Step 7 |
+| `#NAME?` on the label cell | `TEXT()` wrapped around `DR.MONTH()` | Step 4 |
+| Self-rate is not exactly 1 | ratio not anchored to the target row | Step 4 |
+| Custom code rejected by the Tables dialog | never registered as an org currency | Step 1 |
+| `datamappers update` 500s on an unchanged config | mapper has no source version (org import) | remap, Step 6 |
+| Remap 500s: `Cannot read sheet with name …` | chosen version is in `ERROR` status | use the newest ACTIVE version, Step 6 |
+| New lookup columns empty on every target row | lookup built while the FX table was still scanning | rebuild the lookup, Step 7 |
+| Opening balances have no currency amounts | calc-model rows skip the mappers | **Step 7c** |
+| Calc model goes to `ERROR` right after `update` | HTML-encoded formulas sent back unchanged | decode, Step 7c |
+| Calc-model currency column empty in every month | FX lookup key not on the output row | date field + `group_by`, Step 7c |
+| Calc-model currency column `0` only in future months | opening balances run past rate coverage | plan rates, Step 7c |