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

package/dist/skills/fx-conversion-matrix/scripts/gen-mappers.mjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+/**
+ * Emit one `dr datamappers create from-file` body per target currency.
+ *
+ * Each mapper reads one `To <CCY>` tab of the conversion filebox and writes one
+ * column per rate type onto the FX table. Coordinates come from the layout
+ * sidecar `build-matrix.mjs` wrote, so the two scripts cannot disagree about a
+ * cell -- which matters once rate types shift the columns (one type puts the
+ * cross-rate in C, two put them in C and E, pairs mode puts the first in B).
+ *
+ * Two things the body cannot express, and the caller must supply:
+ *
+ *   1. `--field "<column>:Float"` on the create call, one per mapped column. 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 and is
+ *      often Text, and a Text rate column breaks every downstream calculation
+ *      without complaining. The printed command lines always carry the
+ *      overrides.
+ *
+ *   2. `document_version_id` is required by `from-file` and is NOT present in
+ *      `dr datamappers get` output. Read it from the upload response or
+ *      `dr filebox versions <filebox_id>`.
+ *
+ * The currency column maps to whatever `currency_field` the layout sidecar carries,
+ * which build-matrix defaults to the UDM `Posting Currency`. The period calc fields
+ * below write `Reporting Month`, which UDM requires to be the last day of the month
+ * at 00:00:00 UTC -- `[System_Date]` on a month-tagged filebox already is.
+ *
+ * The body deliberately carries NO `template_id`. In power mode that key names
+ * the SOURCE template a mapper was learned on, not the target (the target is
+ * the positional table id), and the CLI resolves every `map_to` type from it
+ * and THROWS on any name the source lacks -- before --field overrides are
+ * merged, so --field cannot rescue it. The rate columns do not exist anywhere
+ * yet, by design, so carrying template_id would fail every create. Omitting it
+ * opts into server-side inference, and --field pins the type.
+ *
+ * Usage:
+ *   node gen-mappers.mjs --layout-file matrix.xlsx.layout.json \
+ *     --filebox 125890 --version 843990 --template 2760 \
+ *     [--targets EUR,GBP] [--out-dir ./mappers] [--name-prefix fx_conversion_rates] \
+ *     [--ordinal-start 1] [--server DEV]
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { die, parseArgs, splitCodes, str } from './_args.mjs';
+
+const args = parseArgs(process.argv.slice(2));
+const layoutFile = str(args, 'layout-file');
+const filebox = Number(args.filebox);
+const version = Number(args.version);
+const template = Number(args.template);
+const outDir = str(args, 'out-dir') ?? './mappers';
+const namePrefix = str(args, 'name-prefix') ?? 'fx_conversion_rates';
+const ordinalStart = args['ordinal-start'] === undefined ? 1 : Number(args['ordinal-start']);
+const serverFlag = str(args, 'server') ?? '<S>';
+
+if (layoutFile === undefined) {
+  die('--layout-file <matrix.xlsx.layout.json> is required (written by build-matrix.mjs)');
+}
+for (const [flag, value] of [
+  ['--filebox', filebox],
+  ['--version', version],
+  ['--template', template],
+]) {
+  if (!Number.isInteger(value) || value <= 0) {
+    die(`${flag} <id> is required and must be a positive integer`);
+  }
+}
+
+let layout;
+try {
+  layout = JSON.parse(await readFile(layoutFile, 'utf8'));
+} catch (err) {
+  die(`could not read ${layoutFile}: ${err.message}`);
+}
+if (!Array.isArray(layout?.sheets) || layout.sheets.length === 0) {
+  die(`${layoutFile} carries no sheets -- was it written by build-matrix.mjs?`);
+}
+
+if (layout.layout === 'lut') {
+  die(
+    'this layout was built for wiring B (filebox-sourced lookups), which needs no\n' +
+      '       datamappers. Use `dr lut create --payload-file` per tab instead, or rebuild\n' +
+      '       with --layout matrix if you meant wiring A.',
+  );
+}
+
+const wanted = str(args, 'targets');
+const only = wanted === undefined ? undefined : new Set(splitCodes(wanted));
+
+const sheets = layout.sheets.filter((s) => only === undefined || only.has(s.target));
+if (sheets.length === 0) die('--targets matched none of the sheets in the layout file');
+
+/** One `config.header` entry. Every field but the three varying ones is fixed. */
+const headerEntry = (coordinate, value, mapTo) => ({
+  role: 'header',
+  coordinate,
+  value,
+  groups: [],
+  map_to: mapTo,
+  match_type: 'value',
+});
+
+function mapperBody(sheetSpec, ordinal) {
+  const { sheet, columns, target, currency_coordinate: currencyCoord } = sheetSpec;
+  return {
+    name: `${namePrefix}_${template}_${target.toLowerCase()}`,
+    sheet_name: sheet,
+    document_version_id: version,
+    selected_document_ids: [filebox],
+    ordinal,
+    config: {
+      sheets_filter: { values: [sheet], is_excluded: false },
+      preview_sheet_name: sheet,
+      header: [
+        // The sidecar names the currency field; the fallback only defends a
+        // hand-edited layout file.
+        headerEntry(currencyCoord, 'Currency', layout.currency_field ?? 'Posting Currency'),
+        ...columns.map((c) => headerEntry(c.coordinate, c.name, c.name)),
+      ],
+      footer: [],
+      dimension: [],
+      attributes: [],
+      table_id: [],
+      value_field_name: 'value',
+      // Both period columns come off the filebox version's own date tag, so
+      // rolling the file forward re-stamps the rows without a formula edit.
+      calculated_fields: [
+        { name: 'Posting Date', formula: ' [System_Date] ', role: 'calculated_fields' },
+        { name: 'Reporting Month', formula: ' [System_Date] ', role: 'calculated_fields' },
+      ],
+      fx_conversions: [],
+      ignore_zeros: true,
+      improved_etl: null,
+    },
+  };
+}
+
+await mkdir(outDir, { recursive: true });
+
+const commands = [];
+for (const [i, spec] of sheets.entries()) {
+  const body = mapperBody(spec, ordinalStart + i);
+  const file = join(outDir, `${spec.target.toLowerCase()}.json`);
+  await writeFile(file, `${JSON.stringify(body, null, 2)}\n`, 'utf8');
+  console.log(
+    `wrote ${file}  (sheet "${spec.sheet}" -> ` +
+      `${spec.columns.map((c) => `${c.coordinate} "${c.name}"`).join(', ')})`,
+  );
+  // The target table is a POSITIONAL argument, not a flag. Every mapped column
+  // gets an explicit Float, or the server infers a type from the samples.
+  const overrides = spec.columns
+    .map((c) => `--field ${JSON.stringify(`${c.name}:Float`)}`)
+    .join(' ');
+  commands.push(
+    `dr datamappers create from-file ${template} --file ${file} ${overrides} ` +
+      `--server ${serverFlag} --json`,
+  );
+}
+
+console.log('\nRun these in order (each is a prod-tier write -- confirm first):\n');
+for (const c of commands) console.log(`  ${c}`);
+
+const allColumns = [...new Set(sheets.flatMap((s) => s.columns.map((c) => c.name)))];
+console.log(
+  `\nThen confirm all ${allColumns.length} column(s) landed as Float, not Text --\n` +
+    `on the FX table AND on every table a lookup carries them into:\n` +
+    `  dr templates get ${template} --server ${serverFlag} --json\n`,
+);

package/dist/skills/fx-conversion-matrix/scripts/rates-to-xlsx.mjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+/**
+ * Turn a triangulated rate feed into a presentable .xlsx.
+ *
+ * Reads the shape a triangulating feed produces -- one row per ordered pair per
+ * day, cross-rated at the source rather than in a workbook:
+ *
+ *     from_currency, to_currency, rate, timestamp
+ *
+ * A CSV in that shape is correct but is not what anyone hands a customer. This
+ * pivots it into a square matrix for one date and keeps the daily detail on a
+ * second tab.
+ *
+ * Column names are matched case-insensitively and fall back to position, so a
+ * feed that calls them `source`/`target` still works.
+ *
+ * Usage:
+ *   node rates-to-xlsx.mjs --in rates.csv --out matrix.xlsx [--date 2026-08-31]
+ *
+ * `--date` picks the matrix tab's date; the default is the latest in the file.
+ * No dependencies -- see `_xlsx.mjs`.
+ */
+import { readFile, writeFile } from 'node:fs/promises';
+
+import { die, parseArgs, str } from './_args.mjs';
+import { buildWorkbook, colName, numberCell, sheetXml, textCell } from './_xlsx.mjs';
+
+const args = parseArgs(process.argv.slice(2));
+const inPath = str(args, 'in');
+const outPath = str(args, 'out') ?? 'rates.xlsx';
+const wantDate = str(args, 'date');
+
+if (inPath === undefined) {
+  die('--in <rates.csv> is required (the file a triangulating data-query produced)');
+}
+
+/** Split one CSV line, honouring double-quoted fields. */
+function splitCsvLine(line) {
+  const out = [];
+  let cur = '';
+  let quoted = false;
+  for (let i = 0; i < line.length; i += 1) {
+    const ch = line[i];
+    if (quoted) {
+      if (ch === '"' && line[i + 1] === '"') {
+        cur += '"';
+        i += 1;
+      } else if (ch === '"') {
+        quoted = false;
+      } else {
+        cur += ch;
+      }
+    } else if (ch === '"') {
+      quoted = true;
+    } else if (ch === ',') {
+      out.push(cur);
+      cur = '';
+    } else {
+      cur += ch;
+    }
+  }
+  out.push(cur);
+  return out;
+}
+
+const raw = (await readFile(inPath, 'utf8')).trim();
+if (raw === '') die(`${inPath} is empty`);
+const lines = raw.split(/\r?\n/);
+const header = splitCsvLine(lines[0]).map((h) => h.trim().toLowerCase());
+
+/** Locate a column by any of its known spellings, else by position. */
+const pick = (names, fallbackIndex) => {
+  for (const n of names) {
+    const i = header.indexOf(n);
+    if (i !== -1) return i;
+  }
+  return fallbackIndex;
+};
+
+const iFrom = pick(['from_currency', 'from', 'source', 'source_currency'], 0);
+const iTo = pick(['to_currency', 'to', 'target', 'target_currency'], 1);
+const iRate = pick(['rate', 'mid', 'value'], 2);
+const iDate = pick(['timestamp', 'date', 'reporting_month', 'posting_date'], 3);
+
+const records = [];
+for (const line of lines.slice(1)) {
+  if (line.trim() === '') continue;
+  const f = splitCsvLine(line);
+  const rate = Number(f[iRate]);
+  if (!Number.isFinite(rate)) continue;
+  records.push({
+    from: (f[iFrom] ?? '').trim(),
+    to: (f[iTo] ?? '').trim(),
+    rate,
+    // Date only -- a triangulated feed is daily, and the matrix is per day.
+    date: (f[iDate] ?? '').trim().slice(0, 10),
+  });
+}
+
+if (records.length === 0) die(`${inPath} carried no usable rate rows`);
+
+const dates = [...new Set(records.map((r) => r.date))].sort();
+const latest = dates.at(-1);
+const matrixDate = wantDate ?? latest;
+if (!dates.includes(matrixDate)) {
+  die(`--date ${matrixDate} is not in the file (it holds ${dates[0]} … ${latest})`);
+}
+
+const codes = [...new Set(records.map((r) => r.from))].sort();
+const onDate = new Map(
+  records.filter((r) => r.date === matrixDate).map((r) => [`${r.from}>${r.to}`, r.rate]),
+);
+
+// --- Sheet 1: the square matrix for one date -------------------------------
+const matrix = new Map();
+matrix.set(1, [textCell('A1', `FX Conversion Matrix — ${matrixDate}`)]);
+matrix.set(2, [
+  textCell('A2', 'Read as: 1 unit of the ROW currency buys this many of the COLUMN currency'),
+]);
+matrix.set(4, [
+  textCell('A4', 'from \\ to'),
+  ...codes.map((c, i) => textCell(`${colName(2 + i)}4`, c)),
+]);
+codes.forEach((from, i) => {
+  const r = 5 + i;
+  const cells = [textCell(`A${r}`, from)];
+  codes.forEach((to, j) => {
+    const v = onDate.get(`${from}>${to}`);
+    if (v !== undefined) cells.push(numberCell(`${colName(2 + j)}${r}`, v));
+  });
+  matrix.set(r, cells);
+});
+
+// --- Sheet 2: every pair, every day ----------------------------------------
+const daily = new Map();
+daily.set(1, [
+  textCell('A1', 'from_currency'),
+  textCell('B1', 'to_currency'),
+  textCell('C1', 'rate'),
+  textCell('D1', 'date'),
+]);
+records.forEach((r, i) => {
+  const n = i + 2;
+  daily.set(n, [
+    textCell(`A${n}`, r.from),
+    textCell(`B${n}`, r.to),
+    numberCell(`C${n}`, r.rate),
+    textCell(`D${n}`, r.date),
+  ]);
+});
+
+// Literal data only -- nothing to recalculate, so no fullCalcOnLoad.
+await writeFile(
+  outPath,
+  buildWorkbook([
+    { name: 'Conversion Matrix', xml: sheetXml(matrix) },
+    { name: 'Daily Rates', xml: sheetXml(daily) },
+  ]),
+);
+
+const totalPairs = codes.length ** 2;
+const missing = totalPairs - onDate.size;
+console.log(
+  `wrote ${outPath} — ${codes.length}×${codes.length} matrix for ${matrixDate}, ` +
+    `${records.length} daily rows across ${dates.length} date(s)`,
+);
+if (missing > 0) {
+  console.log(
+    `note: ${missing} of ${totalPairs} pairs are absent on ${matrixDate} — ` +
+      `those cells are blank rather than guessed`,
+  );
+}

package/dist/skills/fx-onboard/SKILL.md

@@ -0,0 +1,325 @@
+---
+name: fx-onboard
+description: Use when enabling the FX currency selector for a Datarails customer — turning an existing org's Monetary fields, DR.GET functions and dashboard widgets currency-aware so users can switch a dashboard or workbook between currencies. Triggers - "enable FX for <customer>", "set up the currency selector", "make this org currency-aware", "roll out FX conversion to <org>", "turn on multi-currency for this tenant", "FX onboarding", "which tables should be currency aware", "why doesn't the currency dropdown show anything", "the currency selector says N/A", "tag the posting and reporting amounts", "set the org default currency", "roll back the FX conversion". Maps the org, proposes a plan, and only writes after the implementor approves. Run dr-cli:fx-conversion-matrix FIRST - the selector swaps between per-currency reporting-amount columns that must already exist, and that skill is what computes them. Installing or updating the CLI is dr-cli:install; a misbehaving CLI is dr-cli:doctor.
+allowed-tools: Bash, Read, Write
+---
+
+# FX onboarding — enable the currency selector for one org
+
+Takes an existing customer from "no FX" to a working currency selector: Monetary
+fields tagged with their FX roles, DR.GET functions and dashboard widgets
+currency-aware, and an org default currency set.
+
+This skill teaches the FX flow, not the CLI. The `dr-cli` skill is the command
+authority for anything outside `dr fx`, 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.
+
+**Division of authority:** the dry run is the authority on mechanics — what will
+change, in which currency, and on which evidence. This file is the authority on
+*order*, on *when to stop and ask a human*, and on the hazards the commands cannot
+see. Where the two disagree, believe the command output and fix this file.
+
+## Before this skill: do the reporting-amount columns exist?
+
+**Run `dr-cli:fx-conversion-matrix` first.** The selector does not convert anything.
+It **swaps columns**: when a viewer picks GBP, `FxReportingFieldResolver` looks for a
+sibling field on the same template with `fx_role=reporting_amount` and
+`currency_code='GBP'`, and queries that column instead. Its own docstring is blunt
+about it — *"No exchange-rate arithmetic happens here. The converted amounts already
+exist as sibling columns on the same template."*
+
+So the converted amounts must already be in the table, one column per currency, before
+this skill can tag them. If no sibling column exists for a currency, the resolver
+returns nothing and that currency simply never appears in the selector — visible
+absence, not wrong numbers. The columns are what this skill makes *selectable*; they
+are not what it creates.
+
+Getting those columns computed — posting amount times a rate, per currency — is
+`dr-cli:fx-conversion-matrix`. Land the rates there first, compute the reporting
+amounts, then come back here to tag them.
+
+> Not to be confused with the older `CurrencyConversionService` (reached through
+> `CoreEngine.db.table_api_djm`), which DOES multiply by a rate, read from one
+> server-wide table named by `fx_rate_table_id` on the `datarails.com` org. That path
+> is separate from the selector and this skill does not use it. Worth knowing because
+> its failure mode is nastier: its SQL defaults an unresolved rate to 1 (DR-52685), so
+> a stale rate table silently returns unconverted numbers.
+
+## What this actually is
+
+Not a toggle. On an existing customer the amount columns are `Float`, so this
+**retypes customer columns to `Monetary`** and triggers a rescan. The org sees new
+behaviour in dashboards and Excel afterwards. Treat it as a change to a production
+tenant, because it is one.
+
+The hard part is not running the commands. It is answering **"what currency is this
+column in?"** — the question CS raised in the FX focus group, because for most
+customers `amount` carries no clue. This skill's job is to gather the evidence, and
+to **stop and ask a human when the evidence is not there.** Never guess a currency.
+
+## Order is not optional
+
+```
+flags → posting → reporting → default currency → widgets + functions → verify
+```
+
+Currency conversion needs a value field that is `Monetary` **and** carries an
+`fx_role`. The server answers a conversion request on an untagged field with a
+**400, not a skip**, so running the converters first makes every widget report
+`needs-fx-role`. Tag fields first, always.
+
+---
+
+## Step 0 — Preflight
+
+Do not reimplement the CLI install. **With the `dr-cli` plugin**, its hook installs the
+pinned version before this skill runs; if `dr` is missing or the wrong version, route
+to `/dr-cli:install`, and if it is installed but misbehaving, to `/dr-cli:doctor`.
+**Without the plugin** (this skill came from the npm package),
+`dr` is already installed, because that install is what delivered this skill. Update
+it with `dr update`, and use the `dr-cli` skill's troubleshooting for a misbehaving CLI.
+
+Four things this skill does check, because each one silently wastes the whole session:
+
+1. **`dr fx` exists.** `dr fx --help` must list `set-posting`, `set-reporting`,
+   `default-currency`, `convert-functions`, `convert-widgets`. If it does not, the CLI
+   predates FX — `/dr-cli:install`, or `dr update` without the plugin.
+2. **You are on the right tenant, as the right identity.** Run
+   `dr whoami --server <key> --account <email>` and **show the operator the org name
+   and id before anything else.** Getting this wrong is the single worst outcome here:
+   every write lands on someone else's customer. Use `dr login-as <customer-email>`
+   for a customer tenant (see `dr-switch-user`).
+3. **Feature flags.** `fx_enabled` and `fx_dashboard_selector` must be on for the org:
+   `dr features orgs list <org_id>` — a flag's *presence* means enabled. Without them
+   the customer sees nothing after all this work. Enabling them is
+   `dr features orgs add`, and it is a decision for the PM/CS owner, not this skill.
+4. **The tenant's backend supports FX.** Run `dr fx default-currency`. Be careful how
+   you read it: the CLI treats a missing currency endpoint as "no currencies", so
+   *"No reporting currencies available"* means **either** a pre-FX server **or** simply
+   that no reporting fields are tagged yet — the command cannot tell you which, and says
+   so. On a fresh customer that message is expected, not a blocker. To distinguish the
+   two, check whether an FX-era build is deployed (ask R&D or check the release) before
+   concluding the tenant cannot support FX.
+
+---
+
+## Step 1 — Map the org
+
+Read-only. Build the picture before proposing anything.
+
+```bash
+dr templates list                      # tables, with ids
+dr dashboards list                     # dashboards
+dr functions list                      # DR.GET functions, org-wide
+dr fx default-currency                 # current default + what the selector can offer
+```
+
+Then, for each table that looks financial, `dr templates get <id> --json` and read the
+fields. You are looking for:
+
+- **amount-shaped columns** — `Posting Amount`, `Amount`, `Reporting Amount`,
+  `<CODE> Amount`, and anything else numeric that holds money.
+- **currency columns** — `Posting Currency`, `Reporting Currency`. These are the
+  evidence for step 2.
+- **rate columns** — `Currency EOP rate`, `Currency AVG rate`, `<CODE> rate`. Their
+  presence means the customer is already doing FX by hand.
+
+### Stop and look for existing FX machinery
+
+**This is the one that can corrupt a customer's numbers.** Before proposing anything,
+check whether the org already converts currency manually:
+
+- calculated fields whose formula multiplies an amount by a rate —
+  `dr calc-vals list --table <id> --json`, looking for formulas like
+  `[Posting Amount] * [Currency EOP rate]`;
+- FX lookup tables — `dr lut list --table <id>` has an `IS_FX` column;
+- amount columns that are already per-currency (`USD Amount`, `EUR Amount`).
+
+If any exist, **say so in the plan and do not proceed on those tables without a human
+decision.** Making a field currency-aware when the data is already converted
+double-converts it. Silent wrong numbers are worse than no feature.
+
+### Coverage across tables
+
+A dashboard's selector offers a currency only where the data exists. For each
+dashboard, note which tables feed its widgets, and compute the **intersection** of
+reporting currencies across those tables. A currency present in one table but missing
+in another shows the end user a "currency is missing" card on half the dashboard. Call
+that out in the plan — it is a data gap, not a config bug.
+
+---
+
+## Step 2 — Decide the currency semantics per table
+
+For each FX table, two questions.
+
+**Which column is the posting amount?** Usually the one named `Posting Amount` — the
+original, mixed-currency figure. `dr fx set-posting` finds it by name.
+
+**What currency is each reporting column in?** `set-reporting` answers this itself
+where the evidence exists — existing config, then a code in the field name, then a
+single-valued "Reporting Currency" column — and its dry run prints **which** of those
+it used per field in the `SOURCE` column (`existing`, `field-name`,
+`reporting-currency-values`). Read that column rather than re-deriving the rules here;
+`dr fx set-reporting --help` is their definition.
+
+Your job is the case the command deliberately refuses:
+
+**Nothing says so → ask.** A table the sweep lists with `!` is one it would not guess
+on. Do not infer from the rate columns, the customer's country, or the biggest number.
+Put the question to the CSM or the customer: *"Your `Amount` column — which currency
+are those figures in?"* An honest blocker beats a plausible guess, because a wrong
+currency code mislabels real money and nobody downstream can tell. Resolve it with
+`--map "<field>=<CODE>"` once a human answers.
+
+Sample rows when it helps a human decide — `dr templates sample <id> --rows 20` —
+but sampling shows magnitudes, never a currency. Magnitude is a hint for a human, not
+a conclusion for you.
+
+---
+
+## Step 3 — Propose the plan, then stop
+
+Write the plan out and **wait for approval.** Use the CLI's own dry runs as the
+evidence — they are exact, and they are free:
+
+```bash
+dr fx set-posting --all-tables
+dr fx set-reporting --all-tables
+dr fx convert-widgets --all
+dr fx convert-functions
+```
+
+Every one of those is read-only until confirmed. The field commands print a plan and a
+`--confirm-token`; the converters print a plan and need `--confirm`.
+
+The plan you show the implementor must contain:
+
+- **the tenant** — org name and id, and the identity that will write;
+- **per table**: which field becomes posting, which become reporting and in which
+  currency, **and where that currency came from** (name / data / the customer told us);
+- **tables needing a human decision**, quoted from the dry run's `!` lines, with the
+  question to ask;
+- **existing manual FX machinery** found in step 1, and what it means;
+- **currency coverage gaps** across each dashboard's tables;
+- **counts** of widgets and functions that will convert, plus how many are skipped and
+  why (`needs-sum`, `needs-fx-role`);
+- **the org default currency** you propose, and that it is what AI agents fall back to;
+- **what is NOT covered by the CLI** and stays a manual UI step (see below);
+- **the rollback** for each phase.
+
+Do not fold the "needs a human" items into the write step. They are the plan's most
+important output.
+
+---
+
+## Step 4 — Execute, in order, on approval
+
+Per table or org-wide with `--all-tables`. Each field command is its own two-step
+token: run it, read the plan, re-run with the printed `--confirm-token`.
+
+```bash
+# 1. posting amounts
+dr fx set-posting --all-tables                     # plan
+dr fx set-posting --all-tables --confirm-token <t> # apply
+
+# 2. reporting amounts (add --map "<field>=<CODE>" for tables the sweep could not judge)
+dr fx set-reporting --all-tables
+dr fx set-reporting --all-tables --confirm-token <t>
+
+# a table the sweep skipped, resolved by hand:
+dr fx set-reporting <table_id> --map "Amount=GBP"
+
+# a custom currency the ISO list lacks (e.g. budgeted USD):
+dr fx add-currency BUSD --symbol 'B$'
+
+# 3. the org default (Super Admin)
+dr fx default-currency USD --confirm
+
+# 4. the sweeps
+dr fx convert-widgets --all --confirm
+dr fx convert-functions --confirm
+```
+
+Rules while executing:
+
+- **Never pass `--force-sum` without saying so in the plan.** It changes a widget's
+  aggregator to SUM, which changes what the customer sees.
+- **Never use `--allow-custom` or `--allow-unlisted` to get past a validation error.**
+  They exist for a code you know is coming, not to silence a refusal.
+- **Re-runs are safe.** Every command is idempotent — an already-configured field
+  reports `unchanged`, an already-aware widget reports `already`. If a run half-fails,
+  fix the cause and run it again; do not hand-patch.
+- **A failure is not a reason to skip.** `needs-fx-role` means step 1 or 2 is
+  incomplete for that field. Go back rather than forcing.
+
+### Capture a rollback point first
+
+For the widget sweep, save the before-state so there is a restore path beyond the flag:
+
+```bash
+dr widgets get <id> -d <dashboard> --json > before-widget-<id>.json
+```
+
+---
+
+## Step 5 — Verify, and report
+
+Do not stop at "the commands succeeded".
+
+```bash
+dr fx set-posting --all-tables      # expect: nothing left to set
+dr fx set-reporting --all-tables    # expect: nothing left to update
+dr fx convert-widgets --all         # expect: nothing left to convert
+dr fx convert-functions             # expect: nothing left to convert
+dr fx default-currency              # expect: the agreed default, and the currency list
+```
+
+Read the counts the commands print rather than matching exact wording — these summary
+lines belong to the CLI and change with it. What you are checking is that a re-run
+plans no further changes, and that the tables it still lists with `!` are the ones you
+already reported as needing a customer answer.
+
+Then confirm it works for a human, not just in the API: open a converted dashboard,
+switch the selector, and check the numbers change and no widget shows the
+"currency is missing" card. A widget whose table lacks the selected currency is a data
+gap to report, not a config error to fix here.
+
+Report: what changed (tables, fields, widgets, functions, default), what was skipped
+and why, the open questions for the customer, the manual UI steps still outstanding,
+and the rollback commands.
+
+---
+
+## What the CLI cannot do — say this out loud
+
+These stay manual, and omitting them from the report leaves the job half-done:
+
+- **Excel report currency.** `convert-functions` sets the DR.GET flag, but a saved
+  Excel report carries its own `currency_code`, and the file-level selector is UI only.
+- **Clearing an FX role.** `set-posting`/`set-reporting` set roles; removing one is the
+  Tables UI.
+- **Per-user currency preference.** Users pick their own currency per dashboard; only
+  the org default is scriptable.
+
+## Rollback
+
+- **Widgets / functions:** `dr fx convert-widgets --all --off --confirm` and
+  `dr fx convert-functions --off --confirm`. Acts on the stored flag alone, so it also
+  clears flags left on entities that no longer qualify.
+- **A widget body:** `dr widgets update <id> -d <dashboard> --file before-widget-<id>.json`.
+- **Org default:** `dr fx default-currency --none --confirm` (back to posting currency)
+  or set the previous code.
+- **Field roles:** no CLI path — the Tables UI. Say so rather than implying a clean undo.
+
+## Failure modes worth recognising
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Selector shows `N/A` | Widget has no single Monetary value field | Check the widget's value section; only one value field can be currency-aware |
+| Selector dropdown empty | No `reporting_amount` fields tagged, or flags off | Step 2, then check `fx_enabled` |
+| Widget shows "currency is missing" | That table has no reporting field for the selected currency | Data gap — report it, do not force |
+| Everything reports `needs-fx-role` | Converters ran before the field commands | Do step 1–2 first |
+| `needs-sum` | Aggregator is not SUM; conversion is SUM-only | Decide with the owner, then `--force-sum` deliberately |
+| Numbers doubled after enabling | The org already converted manually | Stop, roll back, resolve the existing FX machinery |