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

package/dist/skills/dr-cli/reference/budget-builder.md

@@ -0,0 +1,151 @@
+# Budget Builder (Budget management templates)
+
+Create/preview budget templates and manage their custom rows from the CLI.
+A Budget Builder template is one report-definition JSON (the `tree_to_report`
+envelope); every command here takes it via `--payload-file`.
+
+Commands:
+
+- `budget-builder build --payload-file <f>` — rebuild/preview (the call behind
+  every UI change). Flags: `--design compact|tabular|repetitive`,
+  `--legacy-design`, `--option k=v` (repeatable), `--timeframe-label`,
+  `--out-file`, `--json`.
+- `budget-builder validate-row --payload-file <f> --name <s> --formula <s>
+  --position <row-name> [--format <s>] [--before]` — pre-check a custom-row
+  formula; surfaces the server's verdict reason on failure and prints a
+  warning for `hidden_dependency` (truncated-preview) verdicts.
+  `--position` is REQUIRED — the server rejects an empty anchor with
+  "Position does not exist in choices." (verified live); `build` prints the
+  valid anchor names.
+- `budget-builder add-row` — validate, then merge the row and rebuild
+  (`--out-file` writes the updated definition for a later `save`).
+- `budget-builder save --payload-file <f>` — persist to Budget management
+  (new template → `id: -1` in the payload).
+- `documents split create|list|status|undo` — split a saved budget file into
+  per-dimension-value child files (see
+  [reference/filebox-documents.md](filebox-documents.md) for the documents
+  group generally). `create` and `undo` are two-step confirms.
+
+## Pre-flight questionnaire — ask BEFORE building a template
+
+Values inherited from a scaffold report (actuals-ending date, fill mode,
+design) are the #1 source of silently-wrong templates. Ask in one batch; items
+with a stated default may proceed, but say aloud which default was applied.
+
+1. **Environment + tenant** — verify with `dr whoami --server <key>`, echo the
+   org back. Production requires explicit confirmation.
+2. **Template name** — and is it a keep-or-delete test artifact?
+3. **Budget year** → `budget_info.year` (string). The year of the budget
+   CONTEXT the user started from — identical to the file-system /
+   planning-cycle year (2027 cycle → `"2027"`). NOT derived from the calendar;
+   never default to the current year.
+4. **Budget cycle name** → `budget_info.cycle`. **NO DEFAULT — always ask.**
+   (API: key must be PRESENT and a non-null string; the value is the user's.)
+5. **Function** → `functions: [{id, name}]` + `template_id` (the function's
+   own template). Not mandatory — without an answer pick `Value` or another
+   relevant EXISTING function from `dr functions list`; never invent one;
+   state the pick.
+6. **Actuals ending** → `date_picker` (unix seconds, end of the last actuals
+   month). **BLOCKING — always ask; never silently apply a computed value.**
+   The auto-detect is the PROPOSAL inside the question, not the answer:
+   query the function's table for the latest month with Actuals data
+   (`dr templates aggregate` filtered to Scenario = Actuals, grouped by the
+   date field, take max), **clamp to before the current month** (running in
+   Jul-26 with Jul-26 data → propose Jun-26; the running month is still
+   open), then ask: "Actuals data runs through <max>; I propose actuals
+   ending <clamped>. Confirm or give another month." Only proceed on an
+   explicit confirmation or an explicit month.
+7. **Missing actuals filled from — Manual, Forecast, or Budget?**
+   → `budget_info.scenario` (`scenario_for_non_actuals_dates` server-side).
+   No safe default.
+8. **Column-section fields** → `cols[]` (+ column totals/subtotals).
+9. **Row-section fields + grouping order** → `rows[]`. OPEX default when
+   unspecified: **`Dept > Report field > Account`** — resolve each against
+   the function's template fields and confirm the exact names.
+10. **Scope filters** → `global_filters` / `referenceFields[].includes`.
+    OPEX default (unless asked otherwise): filter on **`Account Group L2`**
+    (the field differentiating OPEX / Income / etc.); list its values and
+    propose the in-scope ones.
+11. **Layout** (defaults ok, state them) — `options.design` (CLI default
+    repetitive), New design ON (`options.standardDesign: false` — INVERTED
+    name — AND `budget_info.new_design: true` — NOT inverted),
+    totals/subtotals/zero-suppression toggles.
+12. **Custom calculated rows** — each needs name (must be UNIQUE among
+    `calculatedRows` — the CLI refuses duplicates because the verdict map is
+    name-keyed), formula (bracket ROW-NAME refs like `[1000 Cash]`, never
+    period labels like `[Feb-26]`), a REQUIRED anchor (`--position
+    <row-name>` — `build` prints the valid anchor names), and `--before` vs
+    default after.
+13. **Split intent** — will the template be split per department afterwards?
+    If yes, confirm the split field + values now (`documents split`).
+14. **Scaffold review** — when building from an existing report's payload
+    (`dr reports get <id> --json`, definition under `.payload`), list every
+    inherited value the questionnaire covers and confirm each explicitly.
+
+## Workflow
+
+```
+dr whoami --server <key>
+dr functions list --server <key>              # function id + template_id
+dr templates list --server <key>              # field names for rows/cols/filters
+# (Q6 unanswered) auto-detect last actuals month; echo it back
+dr reports get <scaffold-id> --server <key> --json   # optional scaffold (.payload)
+# edit payload per answers; id: -1, type: "budget"
+dr budget-builder build --payload-file def.json --server <key>   # must succeed first
+dr budget-builder add-row … --out-file def.json                  # per custom row
+dr budget-builder save --payload-file def.json --server <key>
+dr reports get <new-id> --server <key> --json  # round-trip check; echo settings
+```
+
+## Wire-shape gotchas (live-verified)
+
+- `type: "budget"` requires `budget_info`:
+  `{year, scenario, cycle: <non-null string>, new_design: <bool>}`. Missing
+  `cycle` key → server `KeyError`; explicit `cycle: null` → `.title()` crash.
+- `budget_info.scenario` wire values are lowercase: `budget` | `forecast` |
+  `manual` (the UI's "leave empty / manual" option = `manual`).
+- Budget COLUMNS are auto-generated server-side from `budget_info` +
+  `date_picker` — leave `cols: []`; only rows are authored.
+- Row HIERARCHY is encoded by nesting, NOT by flat array order: the child
+  field node goes in the parent node's `children: [...]` array (recursive).
+  Flat siblings in `rows[]` render as independent top-level row fields.
+  Top-level row nodes of a budget report also carry
+  `is_budget_output: <bool>` (false unless the "budget year data" toggle
+  applies to that field).
+- A `global_filters` entry must carry BOTH a `fields` array and the values:
+  `{name, field: <id>, fields: [{id, name, template_id}], values: ["…"],
+  is_excluded: false, show_in_graph: false, override_global_filter: false}` —
+  the server reads `fields[0].id` AND each `fields[].template_id`
+  unconditionally (`field`-only shape crashes with `KeyError: 'fields'`).
+  Filter VALUES must match the table exactly — check with
+  `dr templates distinct <tid> --field "<name>"` (e.g. `Operating Expense`,
+  singular, not "operating expenses").
+- Two new-design flags point OPPOSITE ways: `options.standardDesign: false` =
+  ON (inverted); `budget_info.new_design: true` = ON (not inverted).
+- Custom rows must ALWAYS carry `positionValue` (a REAL anchor row name — the
+  server 500s with a KeyError when the key is missing and rejects `''` with
+  "Position does not exist in choices.") and `afterPositionValue` (boolean).
+  The CLI's required `--position` + `--before` handle this, and the CLI also
+  normalizes scaffold-payload rows that lack the keys so old files don't 500.
+- Validation verdicts: `custom_value_validation.rows[<name>].status/reason`
+  (`ok` | `broken` | `hidden_dependency` — exhaustive at the source,
+  `custom_value_validation_service.py`). The CLI fails CLOSED: only
+  `ok`/`hidden_dependency` pass; `hidden_dependency` (truncated preview,
+  refs unverifiable) prints a warning; `broken`, an unknown status, or a
+  missing per-row entry all reject.
+- Calculated-row conventions (match the tenant's own P&L rows): absolute
+  rows use format `''`/`'#,###'`; percentage rows use `'#,###%'`. A calc row
+  may anchor to ANOTHER calc row (e.g. Gross Margin `[Gross Profit]/[Revenue]`
+  positioned after Gross Profit). Chain multiple `add-row` calls by passing
+  the same file to `--payload-file` and `--out-file`.
+- Revenue-model defaults (unless the user asks otherwise): scope
+  `Account Group L2 = Income` (ask whether `Other Income` and
+  `Cost of Goods Sold` are in scope); when COGS is included, offer
+  `Gross Profit = [<revenue group>]-[<COGS group>]` and
+  `Gross Margin = [Gross Profit]/[<revenue group>]` (`'#,###%'`) calc rows.
+  Formula refs target the top-level GROUP row names — `build` prints them
+  ("Row anchors for --position: …").
+- Payload files may carry a UTF-8 BOM — `--payload-file` strips it (all
+  commands, since the PR that added this doc). On OLDER dr-cli versions a
+  BOM breaks parsing; there, write with `[IO.File]::WriteAllText` +
+  `UTF8Encoding($false)` instead of `Out-File -Encoding utf8`.

package/dist/skills/dr-cli/reference/calc-vals.md

@@ -0,0 +1,73 @@
+# Calculated Values (per-table)
+
+Commands (alias `calcvals`): `calc-vals list --table <tid>`,
+`calc-vals get <id> --table <tid>`,
+`calc-vals create --table <tid> --name <n> --formula <f> [--format <mask>]`,
+`calc-vals update <id> --table <tid> [--name|--formula|--format]`,
+`calc-vals delete <id> --table <tid>`. `delete` is two-step confirm. `get` is a
+client-side filter over `list` (there is no per-id GET).
+
+These are the FE's **Setup → Tables → row kebab → "Calculated values"** — a
+per-table (template) list of named formula values. They are **not**
+`dr calcmodels`, **not** `dr functions`, **not** semantic-layer `dr metrics`,
+and **not** datamapper calculated fields. Every subcommand is template-scoped,
+so `--table <id>` is **required** on all of them (get the id from
+`dr templates list`).
+
+## Endpoint surface
+
+All under `/api/templates/<tid>/calc_vals` on the monolith. `update`/`delete`
+append the calc-value id: `/api/templates/<tid>/calc_vals/<id>`. Read shape is
+exactly four keys: `{id, name, formula, format}`.
+
+## Field semantics
+
+- **formula** — bracketed, quoted `{source}.member` tokens joined by `+ - * /`,
+  e.g. `["{DR_CVS}.Gross"]` or `["{Category}.Revenue"]+["{Category}.COGS"]`.
+  Sources: `{DR_CVS}` (other calculated values) and dimension / account-group
+  fields (`{Category}`, `{Account Group L1}`, …). The server returns formulas
+  **HTML-entity-encoded** (`&quot;` for `"`); the CLI decodes on every read
+  (table + `--json`) and decodes write input too, so a `formula` you read back
+  pastes straight into `--formula`. Send raw double-quotes on write.
+- **format** — a bare number-format **mask string** (e.g. `"####.##%"`), or
+  `null` when unset (it is NOT an object). On `update`, `--format ""` clears it.
+- **field** — the write-only FE "From" picker selection; never echoed on read.
+  The BE treats it as picker metadata (it does not have to match the formula
+  source). The CLI handles it for you: `create` sends the safe default
+  `{name:"DR_CVS",label:"Calculated Values"}`; `update` (flag mode)
+  **omits it**, so a flag-only update never resets the source of a value created
+  in the FE. Set it explicitly only via `--file`.
+
+## Write semantics
+
+- `create` / `update` have two modes: **flags** (`--name`/`--formula`/`--format`)
+  or **`--file <path>`** (a full JSON object body, POST/PUT verbatim). The two
+  are mutually exclusive.
+- `update` is read-modify-write: it fetches the current value (filtering `list`),
+  splices the provided flags, and PUTs. `--file` update guards `body.id` against
+  the URL `<id>` to catch pointing the wrong file at the wrong id.
+- `--file` rejects a non-object body (array/primitive) before any HTTP.
+- `delete` uses the standard two-step confirm token (resource `calcval`); the FE
+  only has a click-confirm, but the CLI gates it because it runs on prod tenants.
+
+## Building from plain-English intent
+
+The operator describes the value ("on the Financials table, a Gross Margin =
+Revenue − COGS, shown as a 2-decimal percent"). You resolve the table name to a
+`template_id` (`dr templates list`), express the formula in the bracketed-ref
+syntax above, and run:
+
+```
+dr calc-vals create --table <tid> --name "Gross Margin" \
+  --formula '["{Category}.Revenue"]-["{Category}.COGS"]' --format "####.##%" --server <S>
+```
+
+For an account-group source, reference the dimension field by its FE label
+(e.g. `{Account Group L1}`). For a rare explicit `field`, build a full body and
+use `--file`.
+
+## Customer-facing docs (KB)
+
+Help Center → table setup / "Calculated values". Find current articles with
+`dr kb search "calculated values table"` (or browse `dr kb categories` /
+`dr kb sections`). Cite the article; don't paraphrase from memory.

package/dist/skills/dr-cli/reference/calcmodels.md

@@ -0,0 +1,76 @@
+# Calc models
+
+Commands (alias `calc-models`): `calcmodels list`, `calcmodels get <id>`,
+`calcmodels create --file <p>`, `calcmodels update <id> --file <p>`,
+`calcmodels set-flow <id> --flow Auto|Daily`, `calcmodels recalculate <id>`,
+`calcmodels delete <id>`. `set-flow`, `recalculate`, and `delete` are two-step
+confirm. `get` is a client-side filter over `list` (there is no per-id GET);
+`update`/`delete` take the **calc-model id** in the path.
+
+## Types
+
+Three types (schema is identical across them; only defaults differ):
+
+- `BEGINNING_BALANCE_Y_TO_M`
+- `BEGINNING_BALANCE_ONE_TO_M` — note `ONE_TO_M`, **not** `ONETIME_TO_M`
+- `CUMULATIVE_TO_M`
+
+Default `custom_columns[0].formula` is `"Beginning Balance"` for the two
+beginning-balance types, `"Activity"` for cumulative (plus differing name /
+description text).
+
+## Field semantics
+
+- `status` — last-run state; observed `ACTIVE`, `PROCESSING` (loose-typed to
+  tolerate enum drift).
+- `update_flow` — `AUTO` or `DAILY` only. There is no `MANUAL`; manual
+  recalculation is the separate `recalculate` action.
+- **Self-loop guard:** when `destination_template_id == config.source_template_id`
+  (the model writes back into its own source — typical for Beginning-Balance-into-
+  Financials), `create`/`update` refuse `AUTO` client-side. Use `DAILY` for
+  self-loop models — `AUTO` triggers a recursive recalc that drives the model to
+  ERROR with duplicate rows.
+- `description` — capped at 256 characters; the CLI refuses longer values.
+- `data_model` — asymmetric on the wire: numeric org id on POST, slug string
+  (e.g. `"acme.com"`) on GET/PUT. The CLI passes whatever's on the wire.
+
+## Write semantics
+
+- `update --file` PUTs the full body verbatim. The CLI guards `body.id` against
+  the URL `<id>` to catch pointing the wrong file at the wrong id.
+- `set-flow` and `recalculate` fetch the current model, splice (or not), and PUT.
+  The server retriggers a recalc task on **every** PUT regardless of diff — there
+  is no force flag.
+- There is no server-side optimistic concurrency (no `If-Match`/ETag). A
+  concurrent edit during the pause between plan and confirm is silently
+  overwritten when the PUT lands — coordinate with anyone else editing the same
+  model before confirming.
+
+## Building a `create` body from plain-English intent
+
+The operator describes the model in plain English (type, source table, run
+dates, filter values, group-by fields, custom output columns). You resolve all
+names to integer IDs against the tenant — never ask the operator for IDs:
+
+1. `dr templates list --server <S>` → resolve the source table name to its
+   `template_id`.
+2. `dr templates get <template_id> --server <S>` → resolve every named field
+   (value field, date field, each filter field, each group-by field, each
+   custom-column target, plus the system slots `Calc Model ID`,
+   `Calc Model Name`, `Data Type`) to its integer field id.
+3. Construct the 6-key body in memory: `name`, `description`, `data_model`,
+   `type`, `destination_template_id`, `config`. The `config` sub-object carries
+   `source_template_id`, `date_field` (with `time_range = [unix_seconds, null]`),
+   `agg_field`, `data_type_field`, `calc_model_id_field`, `calc_model_name_field`,
+   `group_by[]`, `filters[]`, `custom_columns[]`.
+4. `dr whoami --server <S>` → derive the numeric `data_model` org id.
+5. Write the body to a tmpfile, then `dr calcmodels create --file <tmpfile> --server <S>`.
+
+For `update`: `dr calcmodels get <id> --server <S> --json` → splice the requested
+change → write to a tmpfile → `dr calcmodels update <id> --file <tmpfile> --server <S>`.
+
+## Customer-facing docs (KB)
+
+Help Center → **"Getting Data into Datarails"** → Data Management. Find current articles with `dr kb search "calc model beginning balance"` (or
+browse `dr kb categories` / `dr kb sections`). Cite the article; don't
+paraphrase from memory.

package/dist/skills/dr-cli/reference/cash.md

@@ -0,0 +1,61 @@
+# Cash module
+
+Datarails Cash is its own FinanceOS application (cash management / liquidity), not
+part of Planning.
+
+Read:
+
+- `cash currencies list [--detailed]` (server-supported codes),
+  `cash currencies prefs` (the org's saved currency list + default).
+- `cash rules list <template_id|alias> [--archived]`,
+  `cash rules get <template_id|alias> <rule_id>`.
+- `cash tags list <template_id|alias>` — distinct values in the template's
+  `dr_acc_l3` field. **Discovery only** — `output` on `cash rules create` is a
+  free-form string and is not constrained by this list. 404s on tenants where the
+  cash-category field is aliased differently (surfaced verbatim).
+
+Write:
+
+- `cash currencies set-prefs --currencies USD,EUR,…` (admin-only; uppercased +
+  deduped server-side).
+- `cash transactions <template_id|alias>` — search; `--fields N,M` required;
+  `--page` / `--page-size` / `--manual-only` / `--search "text" --search-fields
+  f1,f2` / `--sort name:asc|desc` (repeatable) / `--filters-file <path>`;
+  `--alias bank_balances|bank_transactions` resolves the template.
+- `cash rescan-rules <template_id|alias>` (surfaces a 409 "already running"
+  verbatim).
+- `cash rules create <template_id|alias> --file <path>` — file is a single rule
+  object or an array (bulk); server auto-assigns `order` if omitted and rejects
+  duplicate condition-sets with 400. Each condition's `input_field` accepts the
+  field name **or** its alias. `output` is free-form.
+- `cash rules update <template_id|alias> <rule_id> --file <path>` — PUT = full
+  replace; two-step (plan diffs current vs new).
+- `cash rules delete <template_id|alias> <rule_id>` — two-step.
+- `cash rules delete-all <template_id|alias> --all | --ids 1,2,3
+  [--include-archived] [--quiet]` — bulk delete under a single two-step;
+  continue-on-error with a `K of N failed` final throw.
+- `cash rules import-csv <template_id|alias> --file <path>` — parses a
+  `Detailed Rule,Parameters,Category` CSV (inverse of `export-csv`).
+- `cash rules reorder <template_id|alias>` — `--file {rules:[{id,order}]}` or
+  `--order 101:1,102:2,…` (mutually exclusive); atomic; two-step.
+- `cash rules export-csv <template_id|alias> [-o <path>|-]` (`-o -` = stdout).
+- `cash rules ai-trigger` — auto-discovers `bank_transactions` + `coa`;
+  support-user only + `cash_ai_rules` flag-gated; two-step.
+- `cash set-default-currency <code>` (empty string clears).
+- `cash hidden-rules upsert <template_id|alias> --file <path>` — array of
+  `{customer_transaction_id, conditions, output, …}`; upsert by
+  `customer_transaction_id`; two-step. There is no native list/get for hidden
+  rules.
+- `cash hidden-rules delete <template_id|alias> --transactions <id1,id2,…>` —
+  two-step (server returns 204 even on misses).
+
+**Rule condition schema:** `{input_field, operation, args, is_falsy?}`.
+Operations: `EQ` (any), `GT`/`GTE`/`LT`/`LTE` (number), `RANGE` (`[n,n]`), `IN`
+(array), `STARTSWITH`/`ENDSWITH`/`CONTAINS`/`REGEX`/`WILDCARD` (string).
+`is_falsy: true` negates the match (default false).
+
+## Customer-facing docs (KB)
+
+Help Center → **"Cash"** category. Find current articles with
+`dr kb search "cash management rules"` (or browse `dr kb categories` /
+`dr kb sections`). Cite the article; don't paraphrase from memory.

package/dist/skills/dr-cli/reference/dashboards-widgets.md

@@ -0,0 +1,85 @@
+# Dashboards, widgets, storyboards, reports, extables
+
+## Dashboards
+
+- `dashboards list`, `dashboards get`.
+- `dashboards create`, `dashboards delete` (two-step confirm), `dashboards prepare`.
+- `dashboards set-date-picker <id>` — five mutually-exclusive flag groups
+  mirroring the FE picker:
+  - `--mode <today|yesterday|this_month|prev_month>` (strict enum), or
+  - `--day YYYY-MM-DD` / `--month YYYY-MM` / `--quarter YYYY-Qn` / `--year YYYY`
+    (custom date flags compute a UTC end-of-period epoch).
+  - `--payload-file` is an escape hatch for `name`/`palette`/etc., with the
+    typed flags overlaid. No confirm token (non-destructive config). A 403
+    surfaces verbatim when the operator lacks `modify_dashboard`.
+
+### Push a dashboard to other organizations
+
+`dashboards push <id> --to <orgs> [--override]` — two-step confirm.
+
+1. `organizations push-targets` lists the eligible destinations. `--to` takes
+   their ids or names, comma-separated or repeated (`--to 4412,4413`,
+   `--to "Acme Corp" --to 4413`), max 50 per run. A destination that isn't on
+   that list is rejected and **nothing** is pushed.
+   - An all-digit token is only ever matched against ids, so an organization
+     *named* e.g. `2024` must be addressed by its id. Same for a name
+     containing a comma — `--to` splits on commas before matching.
+2. Run the command without `--confirm-token` to see the plan (source name,
+   resolved destinations as `name (id)`, mode), then re-run with the token.
+
+`--override` reuses the dashboard a previous push created in each destination,
+**discarding its widgets and filters** before re-cloning. Without it a new
+dashboard is added, with `' Copy'` appended if the name is taken.
+
+The push is queued and returns no job id — results arrive as in-app
+notifications. Confirm with `dashboards list --account <destination>`.
+
+## Widgets
+
+- `widgets list`, `widgets get <id>`, `widgets data <id>` (alias `widget`).
+- `widgets data` applies the dashboard's saved filter bar and global date
+  picker **by default** (one extra `GET /api/dashboards/<id>`), so its answer
+  matches what the product renders — including widgets configured relative to
+  the dashboard's date picker (e.g. "last 12 months as of the dashboard
+  date"). Presets (`today`/`yesterday`/`this_month`/`prev_month`) resolve to
+  end-of-period UTC epochs; saved filters without values are skipped. Human
+  output prints the applied context (`dashboard context: N filters, reference
+  date …`); `--json` stays the verbatim server body. Pass
+  `--no-dashboard-context` for the widget-only computation. Per-user saved
+  views (view-scoped filter/sort/aggregation
+  overrides) are not applied — parity is with the dashboard's saved state,
+  same as scheduled report emails.
+- `widgets create --file` (power mode), `widgets update <id> --file`,
+  `widgets delete <id>` (two-step confirm).
+- Flag-driven builders:
+  - `widgets chart --type column|bar|line|area` + modifiers `--stacked`
+    `--percent` `--smooth`.
+  - `widgets kpi` — single tile.
+  - `widgets pie` — optional `--drilldown`.
+  - `widgets table` — pivot.
+  - `widgets text` — rich-text section header.
+  - `widgets gauge --type enhanced|dynamic-goal` — enhanced = single value vs
+    target; dynamic-goal splits the goal by one `--time-by` field.
+  - `widgets waterfall --type breakdown|walkthrough` — breakdown needs one
+    `--group-by` row dim and one `--time-by` col dim; walkthrough is cols-only.
+  - `widgets published-item` — a stub that throws on invocation; use
+    `widgets create --file` with `chart_type: "published_item"` to reference a
+    published item.
+- **Chart `--type`** accepts either a composite literal
+  (`column-stacked-percent`) **or** flags (`--type column --stacked --percent`)
+  — pick one form.
+
+## Storyboards / reports / extables
+
+- `storyboards list|get|slides`; `storyboards prepare`, `storyboards delete`
+  (two-step confirm).
+- `reports list|get`; `reports clone`, `reports delete` (two-step confirm).
+- `extables list|get`; `extables clone`, `extables delete` (two-step confirm).
+  To inject an ExTable's data into a raw `.xlsx`, that's `documents add-extables`
+  (see reference/filebox-documents.md), **not** an `extables` subcommand.
+
+## Customer-facing docs (KB)
+
+Help Center → the **"Reports & Analysis"** category (Report Builder / Dashboards / Storyboards). Find current articles with `dr kb search "dashboard widget report"` (or
+browse `dr kb categories` / `dr kb sections`). Cite the article; don't
+paraphrase from memory.

package/dist/skills/dr-cli/reference/datamappers.md

@@ -0,0 +1,150 @@
+# Datamappers + mapper recipes
+
+## Read
+
+- `datamappers list`, `datamappers get <id>`.
+- `datamappers list --table <id> --full --json` — adds each mapper's compiled
+  `mapping_rules` (the SSDL JSON the ETL engine actually runs; `config` is only
+  the UI definition it was built from). HTML entities are decoded, so
+  `mapping_rules` is directly JSON-parseable. The server leaves out mappers
+  whose source filebox is archived.
+- `datamappers custom-functions` — the authoritative formula-language function
+  list (names + signatures + descriptions). Copy from here when authoring
+  calc-field formulas.
+- `datamappers processed-versions <mapper_id>` — which doc-versions the mapper
+  has extracted.
+- `datamappers connected-fileboxes <mapper_id>` — filebox metadata for the docs
+  the mapper covers.
+
+## Create — type required up-front
+
+Ask the operator "Flat table, Dimension table, or Multiple tables?" then pick
+the matching subcommand. `datamappers create <flat|dimension|multiple|from-file>
+<table_id>`:
+
+- `flat` requires `--name --doc-version --sheet`. Use `--doc-version`, **not**
+  `--version` — `--version` is reserved by the global `dr --version` and silently
+  no-ops the subcommand.
+- `dimension` adds required `--dim Coord=Label` (≥1).
+- `multiple` adds required `--dim` and `--table-id-cell Coord=Label` (≥1).
+- `from-file --file <path>` is the power mode — it ships the JSON body without
+  the convenience-flag validation, but **not** strictly verbatim. Three things
+  still rewrite it: `--rescan`/`--no-rescan` set or strip `rescan`; a source
+  `template_id` in the body is resolved to `fields_to_change` and then removed
+  (see below); and repeatable `--field NAME:TYPE` upserts `fields_to_change`.
+  Required body fields: `name`, `document_version_id`, `selected_document_ids`
+  (GET returns this renamed as `mapped_documents_ids`), `config`, `sheet_name`.
+
+**Schema-bootstrap shortcut:** mapping `map_to: "<field>"` to a column the target
+template doesn't have yet auto-adds that field on the table (plus 4 system
+scenario fields on the first mapper). This is the documented way to declare
+fields on a freshly-created template — there is no separate "add field" API.
+
+**Bootstrapped field types are value-inferred, not copied (DR-51801).** When
+the body carries no explicit type, the server infers each new field's type from
+the sample values (`Tables/models.py update_mapper` → `ssdl_infer_field_types`).
+A small/loose sample often yields `Text` (occasionally `Integer`). The inference
+does **not** consult a sibling table's field of the same name, so duplicating a
+mapper onto a sibling table would **not** carry the source types — field type
+lives on the template field, never in the mapper `config`, so a byte-identical
+`config` cannot transmit it.
+
+**Automatic type resolution when duplicating a mapper (DR-51801).**
+`datamappers get --json` injects the source `template_id` into its output (the
+mapper API omits it — DR-51821). When a `from-file` body carries a `template_id`,
+`create from-file` reads it as the **source** template, looks up every `map_to`
+target's type on that template's fields, and sends them as `fields_to_change` —
+so a mapper learned via `get` and re-created on a sibling table keeps its types
+with no manual step. The source `template_id` is consumed by the CLI and stripped
+before POST (the target template is the positional arg). If **any** `map_to`
+target has no field of that name on the source template, the command **fails**
+rather than let the server silently mis-infer it. Override or supplement the
+resolved types with `--field NAME:TYPE` (`Text|Float|Date|Integer`, repeatable),
+which wins over the auto-resolved value; a `template_id`-free body keeps the old
+value-inference behavior. `NAME` is the target **table field** name (the
+`map_to`), not the source column header.
+
+## Update / preview / bind / delete
+
+- `datamappers update`, `datamappers delete` (two-step confirm).
+- `datamappers preview --payload-file <p>` — renders mapper output for sample
+  input ("what would this extract?") before saving.
+- `datamappers bind <mapper_id> --doc <id> [--rescan latest|all]` — change which
+  docs a mapper is bound to.
+
+### `update --field NAME:TYPE` — set column types (materialising calc columns)
+
+`datamappers update <id> --payload-file <p> [--field NAME:TYPE ...]`. Repeatable;
+`TYPE` is `Text|Float|Date|Integer`. Each `--field` becomes a `fields_to_change`
+entry on the PUT body, telling the server to set that column's type **explicitly**
+instead of inferring it — this is exactly what the web UI's "Publish and scan"
+does (same `PUT api/templates/mappers/<id>` endpoint; the only payload difference
+is `fields_to_change`).
+
+**When you need it:** adding a calc column that multiplies/divides by a
+**LUT-injected column**. LUT columns land as **Text**; the server infers Text for
+them, so a formula like `[Posting Amount] * [Sign]` fails to materialise and the
+PUT returns a bare `HTTP 500` (`ETLError: … incorrect formula syntax`) — even
+though the formula is valid. Fixing the LUT column's type up-front lets it
+materialise:
+
+```
+dr datamappers update 496476 --payload-file body.json \
+  --field DR_ACCT_Sign_FPA:Integer --rescan all
+```
+
+Merge semantics: `--field` upserts by name into any `fields_to_change` already in
+the payload (type replaced, the entry's other keys preserved); a new name appends
+a minimal `{name, type}`. The server applies only the keys present, so unrelated
+field attributes are left untouched (it does default `is_hidden`→false and
+`ignore_hours`→true for the changed field).
+
+**Caveat:** the server **rejects the type change with HTTP 400** when the template
+has more than one mapper ("Changing the type field … might break some widgets").
+Single-mapper templates (the common onboarding case) are fine.
+
+## Calc-field formulas
+
+`create`/`update` run a client-side guard on `config.calculated_fields[].formula`
+before any HTTP call. It catches the obvious cases — empty/whitespace, bare
+unquoted English text, single `=` instead of `==`, unbalanced `[]`/`()`/`"`, and
+the `EOMONTH` arity foot-gun (Datarails `EOMONTH` is single-arg; Excel's 2-arg
+form fails). It does **not** catch every server-side failure: a syntactically
+valid formula the ETL compiler can't resolve (unknown/wrong-cased function,
+unresolvable `[field]` reference, a string-constant that happens to be quoted)
+still returns a bare 500.
+
+After `create`, the CLI polls the template's `fields[]` for up to 30s for every
+declared calc field to materialise, and warns (pointing at `mapper-recipes get`
+for working formulas) if any are missing — this catches the EOMONTH failure
+mode. Skipped when `--no-rescan` is set.
+
+On a PUT 500, the CLI writes a `dr-cli-error-<timestamp>.md` to the cwd capturing
+URL + status + request/response bodies; the path is named in the stderr error.
+
+Formula syntax:
+
+- Equality is `==` (single `=` is rejected).
+- String literals use double quotes (`"Actuals"`). `&quot;`-encoded quotes
+  round-trip too — the CLI auto-decodes HTML entities (`&quot; &amp; &lt; &gt;`)
+  in the body before send — but raw `"` is preferred.
+- Function names are case-tolerant (`IF`/`If`/`if`); when unsure, copy from
+  `datamappers get` output.
+- `[bracketed]` field references must resolve to a header `map_to`, another
+  calc-field `name`, or a system field (`[FileBox_ID]`, `[System_Year]`,
+  `[System_Date_Tag_Label]`, `[Posting Date]`, …).
+
+## Mapper recipes
+
+- `mapper-recipes list`, `mapper-recipes get <id>` — a library of known-good
+  mapper configs; `get` is a good source of working formulas.
+- `mapper-recipes save --name <n> --from-version <id> --config-file <p>
+  --fields-file <p> [--description <s>]` — the CLI takes plain JSON files and
+  stringifies `config` / `fields_to_change` on the way out (the server stores
+  them as JSON strings).
+
+## Customer-facing docs (KB)
+
+Help Center → **"Getting Data into Datarails"** → Data Mapper. Find current articles with `dr kb search "data mapper"` (or
+browse `dr kb categories` / `dr kb sections`). Cite the article; don't
+paraphrase from memory.