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

package/dist/skills/dr-cli/SKILL.md

@@ -0,0 +1,659 @@
+---
+name: dr-cli
+description: Use when customer success or engineering needs to inspect OR change a customer's Datarails setup from the command line, or create/update/delete Datarails resources (templates, dashboards, widgets, functions, calculated values, dynamic ranges, datamappers, LUTs, fileboxes, integrations, users). Triggers - "create a chart/KPI/pie/table on this dashboard", "bulk-create users", "defer the invite emails", "change a user's login email", "turn email notifications on/off for a user", "re-enable emails for everyone in this org", "create N viewers with specific data permissions", "bulk-grant table/dashboard/filebox permissions from a CSV", "create many permission groups from a CSV", "upload this file", "compare Datarails values", "how many X does this customer have", "am I logged in", "who am I on this tenant", "is this the right customer?", "trigger a rescan", "look up a metric/KPI". Install/update/login → /dr-cli:install; a misbehaving CLI → /dr-cli:doctor; FX → /dr-cli:fx-conversion-matrix then /dr-cli:fx-onboard.
+---
+
+# dr-cli — Datarails CLI
+
+`dr` is a Node.js CLI for working with a customer's Datarails environment
+(templates, dashboards, widgets, functions, calculated values, ranges,
+datamappers, LUTs, fileboxes, integrations, metrics, reconciliation/MEC,
+forecast, cash, spend, workflows, users, orgs) from any terminal on macOS or
+Windows. Reads and writes are both supported.
+
+This SKILL.md is the **router**: safety rules, auth, the full command map, the
+core workflows, and the foot-guns that bite. Per-area detail lives in
+`reference/*.md` — read the named file when you operate that area. Exact flags
+for any command come from `dr <command> --help` (the binary is authoritative).
+
+## Safety rules (enforce these)
+
+1. **Prod writes need explicit in-chat confirmation.** ANY mutating command —
+   `create` / `update` / `delete` **and every other write path** (e.g.
+   `register-identity`, `bulk-create`, `bulk-set-email`, `bulk-permissions`,
+   `set-email`, `set-email-notifications`, `bulk-set-email-notifications`,
+   `set-password`, `set-field-type`) — on `US`, `US2`, `UK`, `CA`,
+   `EU`, `DEMO` (DEMO is a customer-facing prod tenant, not a sandbox) must be
+   confirmed by the user before you run them. `register-identity --confirm` in
+   particular sends real invite emails to customers, so it counts as a prod
+   write. Demonstrate on `DEV` / `DEV-1` / `TEST` / `TEST-1`..`TEST-7` first when
+   you can. Reads never need confirmation.
+2. **Every `delete` is a two-step confirm.** Running `… delete <id>` without a
+   token fetches the target, prints its name + key attributes, and emits a
+   short-lived token bound to `(resource, id, verb)`. Re-run with
+   `--confirm-token <tok>` to actually delete. `templates set-field-type` is
+   gated the same way (it can break widgets/ranges). Relay the target details to
+   the user first. See [reference/safety.md](reference/safety.md) for the
+   interactive prod gate and how the token works.
+3. **Prod destructives end in a desktop dialog, not a chat word.** After the
+   user's in-chat "yes, do it", re-invoke with the token — the binary pops a
+   dialog (or TTY prompt) where the *user* types a fresh challenge word; in a
+   headless shell it refuses non-zero. Don't add your own word ritual in chat.
+   Non-prod (`DEV`/`DEV-1`/`TEST`/`TEST-1`..`TEST-7`) is token-only, a plain
+   "yes" suffices; `DEMO` counts as prod. Details in
+   [reference/safety.md](reference/safety.md).
+4. **Credentials are sensitive.** Sessions live in the OS keychain, or in a
+   credential file where one is in use — never extract or echo JWTs or session
+   IDs into chat.
+5. **Don't invent commands.** If it isn't in the command map below, it doesn't
+   exist — escalate or ask. Never guess a flag; run `dr <command> --help`.
+6. **`UsageStats` is off-limits.** Never rescan/mutate it; `rescan table`
+   refuses it by name on every tenant.
+
+## Auth
+
+Sessions live in the **OS keychain** (Windows Credential Manager / macOS
+Keychain), keyed by `(server, email)` — or in a **credential file** where one is
+in use (see below). With the keychain, multiple servers and multiple identities
+per server can be logged in at once.
+
+- `dr login --server US` — browser OAuth; session to the keychain, or to the
+  credential file when one is in use (see below).
+- `dr login --api-key --server US` — save a user-bound **API key** instead of a
+  browser session. The key is read from a hidden prompt, or from stdin when
+  piped (`printf '%s\n' "$KEY" | dr login --api-key -s us`; piped, `-s` is
+  required unless a credential file already names the server; don't run the
+  piped form under shell tracing or command logging). Never pass the key as an
+  argument or paste it into chat. `dr` exchanges it for a JWT itself, so no
+  re-login is ever needed while the key is live. Keys come from an operator
+  today (no self-service command yet). `login-as` cannot run from an API-key
+  identity.
+- `dr login-as <email> --server US` — impersonate a user, **JWT only, no
+  browser**. Needs an operator `login` first; stores a switchable identity you
+  then target with `--account <email>`. `--as <operator-email>` picks the
+  operator if several are stored; `--user-id <n>` skips the email lookup.
+  Refreshes/auto-remints silently — no re-prompt until the operator expires.
+- `dr whoami --server US` — confirm who/where you are. Offline (decodes the local
+  JWT, no network). **Always sanity-check after login or a server switch.**
+  Shows `Impersonated by:` for a `login-as` identity, and a `Scope:` row for
+  every identity (see below).
+- `dr logout --server US` / `dr logout --all`.
+
+A **credential file wins over the keychain**: `dr` looks at
+`DR_CREDENTIALS_FILE`, or `~/.dr/session.json` when that variable is unset, and
+if the file is there every command reads its credentials from it — even on a
+host whose keychain works — and writes it only when they change (`login`,
+`logout`, a JWT refresh). Only when that one path is absent does `dr` use the
+keychain. That is what makes `dr` usable where no keychain exists (CI, headless
+hosts, containers). `dr whoami`'s `Auth:` line names the file in use. The file holds one
+identity: `login` re-authenticates it and `logout` removes the file, but
+`login-as` is refused (nowhere to put a second identity). If those credentials
+are a bare token pair provisioned by something other than `dr login`, they
+carry no session cookie and `login` / `logout` refuse over them: whatever
+provisioned them owns renewing them. A file holding an `apiKey` is the CLI's
+own to renew: `logout` deletes it and `login --api-key` replaces the key, while
+a plain `login` is refused over it even when the file also holds a cookie,
+because the key is what later commands authenticate as. `dr` warns on stderr,
+once per identity, when a provisioner-supplied `apiKeyExpiresAt` is within
+14 days — from any command that authenticates and from `whoami`, which is where
+an operator goes to inspect a credential; `login`, `logout` and `login-as` do
+not show it. Nothing derives that date: the
+exchange response does not carry it and `login --api-key` does not set it, so
+update it in the file alongside the key, or the warning keeps naming the old
+one.
+
+`--server <KEY>` is **required on every command that hits an API**. Valid keys:
+`US`, `US2`, `UK`, `CA`, `EU`, `DEV`, `DEV-1`, `TEST`, `TEST-1`, `TEST-2`, `TEST-3`, `TEST-4`, `TEST-5`, `TEST-6`, `TEST-7`, `DEMO` (case-insensitive).
+
+You can also pass a full **`https://<host>.datarails.com` URL** instead of a
+key to reach an ad-hoc / PR-preview environment, e.g.
+`dr login --server https://<preview-host>.datarails.com`. Only `https`
+and `*.datarails.com` hosts are accepted; the session is keyed by the hostname.
+`dr logout --all` only revokes the built-in registry servers — log out of a URL
+environment explicitly with `dr logout --server <url>`.
+
+**Multi-identity:** when more than one account is stored for a server, pass
+`--account <email>`. With one identity stored, `--account` can be omitted; a
+missing `--account` against a multi-identity server errors with the available
+emails.
+
+### Credential scope
+
+An identity may carry a **scope** — a ceiling chosen by whoever approved the
+credential (an agent's definition, an API key, a device-flow login), and it is a
+ceiling on top of the user's own permissions, never a grant beyond them.
+Commands outside it are hidden from `--help`, and invoking one anyway — or
+hitting a server with it — exits **3** naming the `resource:action` that is
+missing. **`dr whoami` prints the ceiling**: `Scope: Read only` (or `Read and
+write` / `Full access`) for a preset, otherwise a `custom (N resources)` tree of
+products, resources and the actions allowed on each, and
+`Scope: unrestricted (no ceiling on this credential)` for a token that carries
+no claim at all. Under `login-as` it reads `(inherited from operator)` — the
+ceiling is the operator's. `dr whoami --json` adds `scopes` carrying the claim
+exactly as the token holds it — an array, or a space-separated string, or `null`
+when the token has no such claim. It is **not** normalised, so an entry `dr`
+could not parse is still visible there; read the `Scope:` row for the ceiling
+that is actually in force.
+
+**Do not try to work around a scope** — no direct API calls, no switching
+identity to dodge it. Report what you cannot do and the `resource:action` it
+needs, so whoever minted the credential can widen it.
+
+**`dr --help` can list less than the full tree, for two different reasons.**
+The ROOT listing is context-dependent, and **a short listing never means "the
+command does not exist."** Two mechanisms shorten it and they do not behave the
+same:
+
+1. **No identity resolved** — no `--server` and no credential file, or a
+   `--server` whose stored identities `--account` did not narrow to one. Only
+   the few commands that run without an identity are listed (`login` among
+   them) and a line says why. Everything else is still registered, still runs,
+   and **still prints its own `--help`**; only the root listing changes. Re-run
+   as `dr --help --server <key>` — adding `--account <email>` when that server
+   holds more than one identity — to see the real tree.
+2. **A scope-restricted credential** — an identity DID resolve, and its token's
+   scope claim does not cover every command. The families it may not use are
+   hidden, and targeted help does **not** stay available: `dr <family> --help`
+   for a hidden one exits **3** with its own message naming the missing
+   `resource:action`. That is a credential limit, not a missing feature —
+   `dr whoami` shows the scope the identity carries.
+
+Never tell a user `dr` cannot do something on the strength of a bare
+`dr --help`.
+
+**A server can refuse on scope too, and that also exits 3.** The hidden-command
+rules above are this CLI's own map talking; the servers enforce the ceiling
+themselves and answer `403` with a code:
+
+- **`40301` — the credential's scope does not cover this call.** The message
+  reads `POST /api/…: this identity's credential scope does not allow it
+  (needs dashboards:write); run 'dr whoami' to see the scopes this
+  identity carries`. The scope is named from the local command map, so it is
+  absent for a command the map does not classify — the refusal is the same either way. **Do not retry, and do not
+  re-`login`**: a fresh token carries the same ceiling. Report the missing
+  `resource:action` to whoever minted the credential.
+- **`40302` — the endpoint has no scope declared on the server yet.** The
+  message says `this endpoint is not yet scope-declared on the server; report
+  to #dr-cli`. Nothing about the credential is wrong; the CLI reached a route
+  the server's scope table does not know. Retrying cannot help — report it.
+
+Neither goes through the JWT refresh ladder (a ceiling is not an expiry), so
+neither can present as `session expired`. Any other `403` is an ordinary
+permission / tenant / feature-flag refusal, still exits **1**, and is worth a
+second look at `--server`, the org context, and the request body.
+
+**JWT refresh is automatic** — the CLI refreshes before each request and on
+401/403, except on the two scope codes above, which no refresh can lift. Only
+re-`login` when you see `session expired` as the *final* error after an
+auto-refresh attempt. Do not re-login proactively on an expiry countdown.
+
+**Connectors over VPN (TLS):** `dr connectors …` reaches the control-plane over
+the corporate VPN. A TLS/certificate error there (`self signed certificate in
+chain`, `unable to verify the first certificate`) means the VPN is inspecting
+TLS — trust its gateway root CA via `NODE_EXTRA_CA_CERTS=<gateway-ca.pem>`,
+which keeps verification on. Never set `NODE_TLS_REJECT_UNAUTHORIZED=0` (it also
+exposes the monolith connection carrying the JWT). The CLI appends this fix to
+the error inline; full steps in `dr connectors --help`.
+
+## Command map (don't improvise)
+
+Every entry is a real subcommand. If it's not here, it doesn't exist. Names only
+— run `dr <command> --help` for flags. `→` points to the reference file with that
+area's gotchas.
+
+**Session:** `login`, `whoami`, `logout`, `update` (self-upgrade the CLI).
+
+**Templates / tables / ranges** → [reference/templates.md](reference/templates.md)
+- `templates list|get|create|sample|distinct|aggregate|set-alias|set-field-alias|set-field-type`
+  - `set-alias` / `set-field-alias` set what the Datarails UI calls a table's or
+    field's **system name** — same value, different word. Read them with
+    `templates get <id> --json`.
+- `data-models list|get`
+- `dynamic-ranges list|get|create|update|delete|data`
+- `scans status`, `rescan table`, `dataflow get`
+
+**Datamappers** → [reference/datamappers.md](reference/datamappers.md)
+- `datamappers list|get|update|delete|custom-functions|preview|bind|processed-versions|connected-fileboxes`
+- `datamappers create flat|dimension|multiple|from-file`
+- `mapper-recipes list|get|save`
+
+**Calc models** → [reference/calcmodels.md](reference/calcmodels.md)
+- `calcmodels list|get|create|update|set-flow|recalculate|delete` (alias `calc-models`)
+
+**Calculated values (per-table)** → [reference/calc-vals.md](reference/calc-vals.md)
+- `calc-vals list|get|create|update|delete` (alias `calcvals`) — `--table <id>` required on every subcommand
+
+**Metrics (KPIs) & functions** → [reference/metrics.md](reference/metrics.md)
+- `metrics list|get|data|drilldown`
+- `metrics create base|calc`, `metrics update|delete`
+- `metrics re-aggregate` — rebuild pre-aggregated metric values (targeted ids, or `--all` org-wide); add `--wait [--timeout <s>]` on targeted ids to block until done (exits non-zero on failure/timeout)
+- `metrics migrate` — org-wide metrics+dimensions migration (V1→V2 backfill; `--dry-run` first)
+- `metrics categories list|get|create|update|delete`
+- `metrics dimensions list|get|create|update|delete|preview`
+- `metrics suggestions list|refresh` + `metrics dimensions suggestions list|refresh` — AI suggestion agents (list shows suggestions + `last_run` status; `refresh` triggers a run, `--wait [--timeout <s>]` polls to completion). Gated per-org by Unleash flags; a successful `metrics migrate` auto-triggers both agents, so a 409 from `refresh` right after usually means it's already running — check `list`.
+- `metrics suggestions profile` — read-only: profiles every table and returns, per table, the `reporting_axis` (WHICH date column a BASE metric should bucket by, with `chosen_by` naming the rule), `row_grain.reads_as` (`movements` -> time_aggregation SUM, `balances` -> EOP), candidate `measures`, `categoricals`, and the metrics already defined there. Use this BEFORE proposing any metric: `date_field` cannot be read off the payload (no field marks the reporting column) and guessing it produces a silently wrong number that passes validation. `reporting_axis: null` and `reads_as: "unknown"` are real answers - do not substitute a guess. All measure statistics are SAMPLED from storage-ordered windows and named `sampled_*`; there is deliberately no sum/avg. Needs no Unleash flag. ~30s and ~230 requests on a 43-table org.
+- `metrics dimensions suggestions profile` — read-only: profiles every table/field and returns scored candidate dimension groups (value-overlap grouping, existing-dimension dedupe, machine-readable rejection reasons) in ONE call. Use this instead of looping `templates distinct` per field when reasoning about what dimensions an org should have. Needs no Unleash flag. `--json` for the payload, `--out <file>` when only `summary`/`groups` matter, `--suppression <file>` when you already hold the existing-dimension and dismissed lists. Also emits `near_misses` — pairs just under the merge threshold, for you to judge rather than silently dropped.
+- `functions list|get|create|update|delete|set-filters` — a function's **definition** only.
+  - _`set-filters <id> --file <json> [--confirm]` is the **only** way to author a
+    function's row-level filters (create/update don't touch them). FULL REPLACE —
+    an empty array clears all; dimension `values` are a plain list, date filters
+    carry the add-in's opaque From/To blob. Dry-run unless `--confirm`._
+  To write a function's `DR.GET` into a raw `.xlsx`, that's `documents
+  add-functions` (see the Fileboxes/documents group), not a `functions`
+  subcommand.
+
+**Dashboards, widgets, storyboards, reports, extables** → [reference/dashboards-widgets.md](reference/dashboards-widgets.md)
+- `dashboards list|get|create|delete|prepare|set-date-picker`
+- `dashboards push <id> --to <orgs> [--override]` — copy a dashboard into other
+  organizations (two-step confirm). Destinations must come from
+  `organizations push-targets`.
+- `widgets list|get|data|create|update|delete|chart|kpi|pie|table|gauge|waterfall|published-item|text` (alias `widget`)
+  — `widgets data` applies the dashboard's saved filter bar + date picker by
+  default so results match the product UI; `--no-dashboard-context` computes
+  from the widget's own settings only.
+- `storyboards list|get|slides|prepare|delete`
+- `reports list|get|clone|delete`
+- `extables list|get|clone|delete`
+
+**Budget Builder (Budget management templates)** → [reference/budget-builder.md](reference/budget-builder.md)
+- `budget-builder build|validate-row|add-row|save` — preview/build a budget
+  template definition, manage custom rows, persist to Budget management.
+  **Run the pre-flight questionnaire in the reference before building** —
+  scaffold-inherited values (actuals ending, fill mode, budget year) are the
+  #1 source of silently-wrong templates.
+- `documents split create|list|status|undo` — split a saved budget file into
+  per-department child files (create/undo are two-step confirms).
+
+**Fileboxes & documents** → [reference/filebox-documents.md](reference/filebox-documents.md)
+- `filebox list|get|versions|tags|sheets|preview|create|upload|upload-version|update|download` (alias `fileboxes`)
+- `filebox archive|archive-version|restore-version|set-version-include|set-version-date-tag|set-version-workflow|set-version-file-status|set-version-cycle`
+  - _archived versions (opt-in; defaults unchanged): `versions --archived|--all` to discover them; `archive-version`/`restore-version` also take `--doc` + `--version-number <n>` or `--latest-archived`/`--latest-active`_
+  - _include in database: `versions --included` lists the versions whose `include_file` flag is on (intent, not delivered rows); `set-version-include <vid> --include on|off` writes the flag (two-step confirm both ways — off deletes the version's table rows, on queues an ETL scan). `--doc <id> --all-except-latest` is the bulk cleanup; it never targets the latest, and warns in the plan if the latest is itself excluded_
+- `filebox share|shares|set-option|set-tag-config|set-parent|lock|unlock|lock-date-tag|unlock-date-tag|locked-date-tags`
+- `filebox get-auto-calc-settings|set-auto-calc-frequency|set-sync-frequency`
+- `filebox push <id> --to <orgs> [--override]` — copy a filebox's latest version
+  and its dependent objects into other organizations (two-step confirm).
+  Destinations must come from `organizations push-targets`.
+- `filebox data-query get|set|set-sync-interval|clear|sync` (alias `dq`)
+- `filebox validation-rules options|set`
+- `documents support-api set`, `documents calculate|sheets|debug-zip`
+- `documents auto-calculate|add-functions|add-extables|add-dynamic-ranges` —
+  push a raw `.xlsx` through the server with **no filebox**: `auto-calculate`
+  recomputes it; `add-functions` injects Datarails functions' `DR.GET` formulas
+  into it by function id; `add-extables` registers ExTables into it by extable
+  id; `add-dynamic-ranges` registers Dynamic Ranges into it by range id. These
+  "add X to an Excel file" commands live under `documents`, **not** under
+  `functions`/`extables`/`dynamic-ranges`.
+
+**Lookups (LUTs)** → [reference/lookups.md](reference/lookups.md)
+- `lut list|list-by-doc|unmapped|data|create|create-table-lookup|update|update-table-lookup|delete|reorder|save-mappings|export` (alias `lookups`)
+  - Filebox vs table: **filebox lookups** use `create`/`update` (payload file; source is an uploaded file, keys in leading columns, **surfaces unmapped items** via `lut unmapped`). **table lookups** use `create-table-lookup`/`update-table-lookup` (flags — `--source-table`/`--keys`/`--fields`; source is another table, keys anywhere, **no unmapped-item surfacing**). Full decision guide in the reference.
+
+**Integrations & company data sources** → [reference/integrations.md](reference/integrations.md)
+- `integrations list|get|types|status|query-status|errors|sync|test-connection|add|update|delete|revoke`
+  - _`revoke <id>` is the OAuth **Disconnect** for a `DatarailsConnector` data source: it clears the
+    grant (`authorised=false`, `oauth` + `oauth_secrets` kept) and then revokes it at the vendor,
+    best-effort, when `oauth.revoke_url` is set. Two-step confirm (Tier A on prod); the output
+    names the vendor outcome (`revoked`, `rejected`, `not_supported`, ...). The customer must
+    reconnect before the next sync._
+- `integrations share users|groups`
+- `integrations it list|get|add|update|delete|resync` (IT-admin file-sync; redacts secrets by default)
+- `entities list|qbd-availability|netsuite-connections|rename|rename-group|delete|mark-completed` (alias `companies`)
+- `entities create qbo|xero|qbd|netsuite` (connected accounting systems)
+- `error-enrichments list|stats|get|create|update|delete|test-regex|export|import` — the
+  regex→readable-message rules shown when a sync fails. `get`/`update`/`delete` take
+  one **or more** ids (`update` applies the same patch to each); `create` and
+  `update` also accept an **array** `--payload-file` (rule objects for `create`,
+  `{id, ...fields}` patches for `update`) for batch writes. Rules are **per server**;
+  `list`/`stats` take `--all-servers`, writes take one `--server`. `import` is
+  wipe-and-replace and zeroes hits/feedback counters — it is not the reconcile
+  tool: fleet changes are batch `create`/`update`, and `import` runs only when the
+  user names it and confirms the analytics loss and id reassignment. Start at the
+  **`dr-error-enrichment` skill** (router + shared reference on matching, safety,
+  and groundcover), then go straight to the task skill: **`dr-error-enrichment-author`**
+  to write/edit/delete rules, **`dr-error-enrichment-reconcile`** to diff and align
+  rules across servers, **`dr-error-enrichment-maintain`** to approve high-hit drafts
+  and fix thumbs-down rules, **`dr-error-enrichment-improve`** to mine groundcover
+  for unmatched errors and propose new rules.
+
+**Reconciliation & MEC close-dates** → [reference/reconciliation-mec.md](reference/reconciliation-mec.md)
+- `reconciliation accounts list|entities|entity-currencies|info|progress|settings|update-settings|set-assignee|clear-assignee|set-due-date|sign` (alias `recon`)
+- `reconciliation processes dates|accounts`
+- `reconciliation evidences list|get|process|supporting|file|create`
+- `reconciliation filebox list|get|progress|create|delete|unlinked`
+- `reconciliation audit status`
+- `mec close-dates get|set`
+
+**Workflows v2 (close & non-MEC) + collection processes** → [reference/workflows.md](reference/workflows.md)
+- `workflow` and `mec workflow` share the same surface: `list|get|create|update|activate|deactivate|archive|restore|delete|clone|periods`, plus sub-groups `process`, `step`, `task`, `member`, `group` (`mec workflow` also has `accounts`)
+- `collection-processes list|get|create|set-tag-config|add-fileboxes|add-folders|calculate` (alias `collection-process`)
+
+**Forecast (Planning)** → [reference/forecast.md](reference/forecast.md)
+- `forecast cycles list|get|documents|lock|unlock|set-default|roll-forward`
+- `forecast scenarios list|get|versions|lock|unlock|set-default|delete|clone|clone-from-budget|bulk-edit|create`
+
+**Cash** (own module) → [reference/cash.md](reference/cash.md)
+- `cash currencies list|prefs|set-prefs`, `cash transactions`, `cash rescan-rules`, `cash set-default-currency`
+- `cash rules list|get|create|update|delete|delete-all|reorder|import-csv|export-csv|ai-trigger`
+- `cash tags list`, `cash hidden-rules upsert|delete`
+
+**Spend Control** (own module) → [reference/spend-control.md](reference/spend-control.md)
+- `spend-control billing-frequencies list`, `spend-control contracts list|get|extract-from-files|bulk-create|update|archive|restore|delete`, `spend-control files upload|list|get|delete`
+- Attaching a document whose field values you already know? `spend-control files upload` returns file_ids with NO AI extraction cost; `extract-from-files` is for when you need the fields parsed.
+- Need a contract UUID for `get`/`update`/`archive`/`delete`? `spend-control contracts list --all` is the only source.
+
+**Multi-product (product-content catalog & per-org assignment)** → [reference/multi-product.md](reference/multi-product.md)
+- `multi-product product-content list`
+- `multi-product org-products list|set` — `set` has replace semantics; two-step confirm gated
+
+**Legacy RH_CONFIG inspection (read-only)** → [reference/rh-config.md](reference/rh-config.md)
+- `rh_config config|tables|download <bucket-id>` — inspect / download the bucket's config workbook (the Excel with the `RH_Config` sheet that the legacy parser reads).
+  - _`rh_config download` is broken (its endpoint rejects the JWT and it saves the login HTML page). Download instead with `filebox download <document> --doc-version <id>`, using `id` + `document` from `rh_config config <bucket-id> --json`._
+- `rh_config doc-templates <doc-id> [--legacy-only]` / `rh_config version-templates <ver-id> [--v2] [--legacy-only]` — list TableTemplates with the `is_rh_config` flag surfaced.
+
+**IT / admin / misc** → [reference/admin.md](reference/admin.md)
+- `users list|get|can-login-as|me|set-password|set-email|set-email-notifications|bulk-create|bulk-set-email|bulk-set-email-notifications|register-identity|permissions|bulk-permissions`
+  - _`set-email <user_id> <new_email>` changes one user's **login email** via
+    `PUT /api/it/users/<id>` (the IT admin edit dialog's endpoint; preserves
+    `excel_online_email` and triggers the server's SSO email sync). **Dry-run by
+    default** — it GETs the user and prints `current -> new`; add `--confirm` to
+    apply. A target already in use errors (`email already in use`)._
+  - _`bulk-set-email --file <csv>` renames many users' login emails in one go
+    (CSV header `source,target`, one row per user). Same safety model as
+    `bulk-create`: resolves + validates EVERYTHING first — an unknown source,
+    sources spanning **more than one organization**, a target that collides with
+    an existing user, or a swap/chain all abort **before any write**. Dry-run
+    unless `--confirm`; on execute each row is isolated (a failure is recorded,
+    the batch continues, a non-empty failure set exits non-zero). Template:
+    `docs/examples/users-bulk-set-email.csv`._
+  - _`set-email-notifications <user_id> --enable|--disable` is the admin form's
+    **"Enable notifications"** toggle (`disable_emails`), written through the same
+    `PUT /api/it/users/<id>`. Exactly one of `--enable`/`--disable` required.
+    **Dry-run unless `--confirm`.** Refuses sync-service and support accounts
+    (provisioned notifications-off; the bulk verb skips them for the same
+    reason). Only `disable_emails` changes — the body
+    echoes the current `email` and `excel_online_email` verbatim so the server's
+    SSO email-sync never fires. **Blocked users:** the write lands, but reads
+    stay `off` until the user is unblocked (the server reports
+    `disable_emails OR is_blocked`) — the command says so; don't retry. To find
+    affected users, `users list` has an `EMAIL_NOTIF` column and
+    `--email-notifications on|off`._
+  - _`bulk-set-email-notifications --organization <id> --enable|--disable`
+    applies that toggle to a whole org (per-user writes — there is no org-level
+    notification setting). **Always skips** sync-service users, support users,
+    and users whose state the server didn't report; `--only-changed` also skips
+    users already in the target state, making re-runs cheap — but **never**
+    skips a blocked user, whose read state (`_disable_emails OR is_blocked`)
+    says nothing about the stored column. Aborts before any
+    write if the org matches no users. Dry-run unless `--confirm`; per-user
+    isolation on execute, failed ids named, non-zero exit._
+  - _`bulk-create --file <csv>` invites many users in one go, each scoped to
+    permission groups (the UI's "Invite Users → Set Permissions" flow, automated).
+    **Dry-run by default — add `--confirm` to actually create** (it sends real
+    invite emails). CSV header:
+    `email,first_name,last_name,role,permission_groups,department,job_role`
+    plus an **optional 8th column `register_identity`** (blank/absent ⇒ `true`;
+    set `false` to create that user WITHOUT identity-provider registration /
+    invite email — deferred setup). Blank `role` = VIEWER; `permission_groups`
+    are `;`-separated group **names**. Target org auto-resolves from the tenant's
+    permission groups, or pass `--organization <id>`. Existing emails aren't
+    recreated but ARE re-scoped (their listed groups get assigned), so re-runs
+    are idempotent and repair a prior partial failure. **`--no-register-identity`**
+    forces the deferred behavior for the whole batch; send the invites later with
+    `register-identity`._
+  - _`register-identity --file <csv>` sends the deferred invites for a
+    `bulk-create --no-register-identity` batch: feed it the SAME CSV (only `email` is
+    read), it resolves each email to its user and calls
+    `PUT /api/it/users/<id>/register_identity` to register + invite. Dry-run
+    unless `--confirm`; honest per-row status `registered`/`already_exists`/
+    `failed` (only `failed` exits non-zero, so re-runs are idempotent —
+    already-registered users report `already_exists`)._
+  - _`permissions <get|set-role|grant-table|revoke-table|grant-element|revoke-element|set-filters|remove-group>`
+    is the Permission Manager, one user at a time: data-table roles, element roles
+    (filebox/lookup/model/report/dashboard/storyboard/datasource), org role, and
+    row-level data-access filters. Requires the `use_new_table_perms` flag.
+    **Dry-run unless `--confirm`.**_
+  - _`bulk-permissions --file <csv>` applies many of those grants at once. Header:
+    `email,resource,type,ids,role,filter_values,filter_excluded` — one row per
+    grant, `resource` ∈ `table|element|role|filter`. Resolves everything first
+    and fails loud before any write (unknown email or table/element role aborts
+    the run); `filter` rows for a user aggregate into one full-replace. **Dry-run
+    unless `--confirm`.** Template: `docs/examples/users-bulk-permissions.csv`._
+- `organizations list|get|add|contacts|permission-groups|push-targets|create-group|update-group|delete-group|bulk-groups` (alias `orgs`), `support-manager list`
+  - _`push-targets` lists the organizations this account may push a dashboard or filebox into — always run it before `dashboards push` / `filebox push`_
+  - _`create-group|update-group|delete-group` manage permission groups on the IT
+    app; `bulk-groups --file <csv>` provisions and augments many groups + their
+    membership from one CSV (header `group_name,role,members`). Dry-run unless
+    `--confirm`; `delete-group` uses the two-step confirm-token flow._
+- `organizations export create|delete`, `organizations import run|delete-orgs` — full-org
+  migration between servers (export → email → import → email → export delete).
+  - _Both POSTs return immediately; **completion is email-only — there is no status
+    API to poll**. `import run` is permanent by default (`--temporary` opts into a
+    GC'd throwaway) and skips unknown model types by default (`--no-skip-models` to
+    fail instead). `import delete-orgs` **permanently deletes the whole organization**
+    (word-gated on prod). Renamed copies get RANDOMIZED user passwords (per-org
+    secret, recorded nowhere — use impersonation); real migrations pass
+    `--keep-user-passwords`. Full runbook: [reference/admin.md](reference/admin.md)._
+- `devices list|get|logs|request-logs|received-logs|download-logs|commands|command-delete`
+- `features list`, `features groups list|get`, `features orgs list|add|remove`
+- `semantictables list|get|data|distinct` (alias `semtables`), `fx rates`
+- `fx set-posting|set-reporting` (Monetary field FX roles; `--all-tables` sweeps the org), `fx default-currency` (org-wide default, Super Admin), `fx add-currency` (org custom currency, e.g. BUSD), `fx convert-functions|convert-widgets` (bulk currency-aware sweeps, `--off` to roll back)
+- `kb search|get|categories|sections|articles-in-section|recent|attachments|article-images`
+- `mcp register|unregister|list|serve`, `skill list|print|install|init-project`
+
+**Desk** → [reference/desk.md](reference/desk.md)
+- `desk teams list` — the org's Desk teams with their support emails; the only way
+  to get a `team_id` (no email-to-team lookup exists anywhere in the platform)
+- `desk smtp set <team>` — store + verify a customer app password; `<team>` is an
+  id, a support email, or a team name (resolved against `teams list`)
+- `desk smtp rotate <team>` — replace a stored app password in place when `set`
+  reports an existing ACTIVE connection; the row is never deactivated, so the
+  team keeps sending authenticated throughout
+- `desk smtp get|test <team>` — inspect a stored connection (does it actually
+  route?) and re-test the credential without re-submitting it
+- `desk support-email set <team> <email>` — register the team's
+  inbound address; do this BEFORE the customer creates their auto-forward rule
+- `desk sendgrid register <domain>|status|verify` — SendGrid domain authentication
+- `desk ticket create <team> --title … --requester-email … [--attach <path> …]` — open a
+  ticket; `<team>` resolves like `smtp set`'s. **Desk emails a confirmation to the
+  requester**, so it is confirm-gated and keeps the interactive word gate on production
+- `desk clone --source-org <id> --target-org <id> [--dry-run]` — copy a reference
+  org's Desk (missing users with the e-mail domain swapped, missing teams + members,
+  config, tickets with history) into the token's org; match-or-create, safe to re-run.
+  Does NOT copy the org's `desk*` feature flags — `features orgs add` them first
+  - _Every `desk` verb is **org-scoped from the token** and takes no `org_id`: the
+    org is whatever `--server` + `--account` resolve to. Every one EXCEPT
+    `ticket create` is admin-only. `ticket create` instead needs Desk access — a
+    membership in some Desk team, or platform admin. Either way an integrations
+    engineer's own identity in a customer org is refused, so the working identity is
+    `dr login-as <customer-admin>` then `--account <that-email>`._
+  - _`--attach` is **create-then-upload**, not one call: the confirmation email goes out
+    before the files exist, a failed upload exits non-zero naming which files landed, and
+    the fix is to attach from the UI — re-running opens a SECOND ticket and re-emails the
+    requester. Extensions and the 25 MB cap are checked locally, before the create, and
+    `--json` becomes `{ticket, attachments}` (bare ticket when `--attach` is unused), so
+    read `.ticket.ticket_number` not `.ticket_number` when attaching._
+  - _The description is ALSO posted as the requester's first inbound message by default
+    (`--no-thread` opts out), because the UI's conversation pane renders the `messages`
+    table and not the `description` column - without it a CLI-created ticket looks empty.
+    Sends no email (`direction: inbound`). It does NOT clear the "requester not linked to
+    any record" banner - matching only runs in desk-ai's inbound handler; use
+    `--contact-id`._
+  - _`ticket create` may come back with a different team, status, priority or assignee
+    than you sent: an assignee forces `to_do`, an omitted `--due-date` is back-filled
+    from the computed SLA, and a routing rule can move the ticket to another team or
+    set the priority/assignee **for a flag you did not pass** (passing one suppresses
+    the matching rule). The command says so in its output — it is the server, not a
+    dropped flag._
+  - _`smtp set` reads the password from `--password-file` or `--password-stdin`
+    **only** — it is never a command-line argument. A `200` with `verified: false`
+    is the normal "customer gave us the wrong credential" outcome, not an error._
+
+## Core workflows
+
+Add `--json` to any `list`/`get`/`data` when you'll parse the output; the default
+table form is for humans. On Windows, pipe large `--json` to a file first
+(`dr … --json > out.json`) — direct piping into `ConvertFrom-Json` can truncate.
+**Read that file as UTF-8** — dr JSON carries non-ASCII and HTML-escaped entities
+(`&amp;`, `&#x27;`, smart quotes); Python's default `cp1252` on Windows raises
+`UnicodeDecodeError` mid-parse (`open(path, encoding="utf-8")`). And note some
+`list` endpoints are **paginated** — `--json` returns a `{count,next,previous,results}`
+envelope with only the first page, not the whole set (e.g. `features list`); pull
+the rest with `--page`/`--page-size` rather than assuming one call is complete.
+
+**KB-first when the user speaks product, not CLI.** If the request is a symptom
+or how-to in product terms ("reconciliation isn't pairing", "how do I explain X
+to the customer"), search the Help Center *before* acting: `dr kb search
+"<query>"` (global content — no `--server`) or the `dr-zendesk-kb` MCP. It
+returns the current article as markdown + URL — ground and cite your answer, then
+map to the right `dr` command. Don't rely on memorized KB content; each reference
+file also names the relevant KB folder for its area.
+
+**Explore a tenant.** `dr whoami --server US` (confirm tenant) → `templates list`
+→ `dashboards list` → `functions list` → `metrics list`. Pick an ID and drill:
+`templates get <id>` shows field names + IDs you'll need downstream.
+
+**Peek at table data.** `templates sample <template_id> --rows 10 --server US`
+(latest version, newest rows). `--fields "A,B"` projects columns; `--offset N`
+pages; `--filter "Region=EU"` / `--filter-range "Period=2026-01..2026-12"`
+narrow rows (dates as calendar dates or epoch seconds — see
+reference/templates.md).
+
+**Pull a function definition.** `functions get <id> --server US` returns the
+*definition* — template, field, aggregator, and a **FILTERS** section (each
+persisted filter's field/name/type/excluded/values), plus the default agg date
+field; `--json` adds `filters` + `default_agg_*`. It is **not** the live value
+(that's computed in Excel via `DR.GET`). A date filter's From/To lives inside
+that filter's `values` — read it there instead of asking the customer.
+
+**Pull raw rows from a dynamic range.** Ranges nest under a table:
+`dynamic-ranges list --table <template_id>` → `dynamic-ranges data <range_id>
+--table <template_id> --json`.
+
+**Pull a KPI value.** `metrics list` → `metrics data --id <id> --scenario Actuals
+--from 2026-03-01 --to 2026-03-31 --server US`. `metrics drilldown --id <id> …`
+returns the source rows behind the number.
+
+**Trigger a rescan.** `scans status <template_id>` → `rescan table <template_id>`
+(two-step confirm: the first run prints the blast radius — document + version
+counts — and a token; re-run with `--confirm-token` to fire it) → poll `scans
+status` again. This is a **full historical** rescan (every calc field × every
+version). To only pick up a datamapper change on the live template, prefer
+`datamappers update <id> --rescan latest` (latest version only; mirrors "Publish
+and scan") — far cheaper and lower-blast.
+
+**Build a `create` body from plain-English intent** (calc models, datamappers,
+metrics): you resolve names → integer IDs yourself against the tenant
+(`templates list`, `templates get <id>`, `whoami`), construct the body, write it
+to a tmpfile, then `… create --file <tmpfile>`. The operator never captures
+network traffic or hand-edits JSON. Full recipes in the relevant reference file.
+
+## Foot-guns
+
+- **"System name" is spelled `alias` here.** The Datarails UI, Help Center, and
+  most operators say **system name** for a table's or field's stable machine
+  identifier — the thing `DR.GET(value,"{department}")` resolves in `{braces}`,
+  and the thing template-library import maps on. dr-cli and the monolith API
+  both call it `alias`. If an operator asks for a system name, reach for
+  `templates set-alias` / `templates set-field-alias`, and read current values
+  with `templates get <id> --json` (the text table does not show them). Do not
+  report it as unsupported. Note the word is overloaded: command aliases
+  (`orgs` → `organizations`), `entities rename --alias` (a *display* name), and
+  filebox alias-matching are **not** system names. See reference/templates.md.
+- **Metric value-field aggregators** are `SUM`, `COUNT`, `CUMULATIVE_SUM`,
+  `CUMULATIVE_COUNT` only — `AVG`/`MIN`/`MAX` are rejected. See reference/metrics.md.
+- **CALC metric formulas:** each referenced metric name in `[brackets]`;
+  constants-only is rejected; reserved tokens `DAYS_IN_PERIOD` /
+  `PERIODS_IN_YEAR` are bare (not bracketed); time modifiers are
+  `[M].SHIFT(...)` / `[M].AS_OF(...)` — SHIFT unit `consumption_period`
+  follows the query grain; `PERIODS_IN_YEAR` metrics reject day-grain
+  queries. See reference/metrics.md.
+- **`metrics data --agg`** is `DEFAULT|MTD|QTD|YTD|MTG|QTG|YTG`. The `*TG` "to
+  go" values accumulate **forward** from the current bucket (inclusive) to the
+  period end — the mirror of `*TD`. See reference/metrics.md.
+- **Calc-model types** are `BEGINNING_BALANCE_Y_TO_M`, `BEGINNING_BALANCE_ONE_TO_M`
+  (`ONE_TO_M`, not `ONETIME_TO_M`), `CUMULATIVE_TO_M`. Self-loop models use
+  `DAILY`, not `AUTO`. See reference/calcmodels.md.
+- **Calculated values are per-table** — `calc-vals` needs `--table <id>` on every
+  subcommand (incl. `get`/`delete`), and is distinct from calc models, functions,
+  and metrics. Flag-mode `update` leaves the value's FE "From" source untouched;
+  use `--file` to change it. See reference/calc-vals.md.
+- **`templates set-field-type`** accepts `Text|Float|Date|Integer` and is
+  confirm-token gated.
+- **Adding a calc column that references a LUT-injected column** (e.g.
+  `Amount = [Posting Amount] * [Sign]` where `[Sign]` comes from a lookup and
+  lands as **Text**): a plain `datamappers update … --rescan all` 500s
+  (`ETLError: … incorrect formula syntax`) because the server *infers* the LUT
+  column as Text and `Text * number` won't materialise. The UI "Publish and
+  scan" avoids this by sending `fields_to_change`. Replicate it from the CLI
+  with `datamappers update <id> --payload-file <p> --field <LUT_col>:Integer
+  --rescan all` (repeatable). Caveat: the server **rejects the type change with
+  HTTP 400** when the template has more than one mapper. See
+  reference/datamappers.md.
+- **`datamappers create` needs the type up-front** — pick `flat`/`dimension`/
+  `multiple`/`from-file`. Use `--doc-version` (not `--version`, which collides
+  with the global `dr --version`).
+- **Duplicating a mapper onto another table** — `datamappers get <mapper>
+  --table <src> --json` emits the source `template_id`; feed the (reshaped) body
+  to `datamappers create from-file <target>` and every `map_to` field type is
+  auto-resolved from the source template — no manual `--field` per field. It
+  **fails loudly** if any `map_to` target can't be resolved on the source rather
+  than mis-inferring it (DR-51801). Override with `--field NAME:TYPE`. See
+  reference/datamappers.md.
+- **`--table` is required** on `dynamic-ranges list|data` and `lut list` — get the
+  template ID from `templates list` first.
+- **`functions get`** returns the definition, never the live value.
+- **Chart type** accepts either a composite literal (`column-stacked-percent`) or
+  flags (`--type column --stacked --percent`) — pick one.
+- **`filebox data-query sync`** — scope to a period with `--date YYYY-MM-DD`
+  (e.g. `--date 2026-07-01`), not raw `--tag` JSON. The CLI truncates the
+  date to whatever granularity the filebox's own DATE tag actually uses —
+  no need to know if it's yearly/quarterly/monthly/daily/weekly. `--tag` is
+  an unvalidated escape hatch that forwards straight to the server; a
+  malformed value 500s with no error body. See reference/filebox-documents.md.
+- **"User has no table permissions" is almost always a misread.** To see which
+  tables a user can access, use `dr users permissions get <id>` — never the raw
+  `GET /api/it/users/<id>` object's `permissions` field. That field is Django
+  **global capability flags** (`user.user_permissions`), empty for essentially
+  every VIEWER, and says nothing about data access; real table access lives in the
+  `user_to_check_role_id` sweep that `get` runs. See reference/admin.md.
+
+## Reference files
+
+Read the matching file before operating that area; it carries the valid enums,
+required-flag traps, and create-body recipes that `--help` doesn't spell out.
+Each also names the relevant Help Center (KB) folder for customer-facing docs.
+
+- [reference/safety.md](reference/safety.md) — confirm-token flow, interactive prod gate, escalation
+- [reference/templates.md](reference/templates.md) — templates, fields/aliases, data-models, dynamic ranges, scans
+- [reference/datamappers.md](reference/datamappers.md) — datamappers, calc-field formulas, recipes
+- [reference/calcmodels.md](reference/calcmodels.md) — calc-model types, flow, create bodies
+- [reference/calc-vals.md](reference/calc-vals.md) — per-table Calculated Values (formula refs, field/format semantics)
+- [reference/metrics.md](reference/metrics.md) — metrics, categories, dimensions, functions
+- [reference/dashboards-widgets.md](reference/dashboards-widgets.md) — dashboards, widgets, storyboards, reports, extables
+- [reference/filebox-documents.md](reference/filebox-documents.md) — fileboxes, documents
+- [reference/lookups.md](reference/lookups.md) — lookups (LUTs): filebox-sourced + table-sourced
+- [reference/integrations.md](reference/integrations.md) — customer + IT-admin integrations, company data sources (entities)
+- [reference/reconciliation-mec.md](reference/reconciliation-mec.md) — reconciliation, MEC close-dates
+- [reference/workflows.md](reference/workflows.md) — workflow / mec workflow engine, collection processes
+- [reference/forecast.md](reference/forecast.md) — forecast cycles & scenarios (Planning)
+- [reference/cash.md](reference/cash.md) — Cash module
+- [reference/spend-control.md](reference/spend-control.md) — Spend Control module
+- [reference/multi-product.md](reference/multi-product.md) — product-content catalog + per-org assignment (replace-semantics PUT)
+- [reference/desk.md](reference/desk.md) — Desk: outbound-email onboarding (SMTP app password + SendGrid domain auth) and ticket creation
+- [reference/rh-config.md](reference/rh-config.md) — legacy RH_CONFIG inspection (read-only)
+- [reference/admin.md](reference/admin.md) — users, orgs, devices, feature flags, semantic tables, fx, kb, mcp, skill
+
+Everything else is discoverable: `dr --help` (families) → `dr <family> --help`
+(subcommands) → `dr <family> <sub> --help` (flags). The binary is the source of
+truth; `docs/reference.html` is a generated dump of all of it.
+
+One catch on the first step: `dr --help` enumerates every family only when an
+identity resolves AND that identity's credential scope covers them (see Auth).
+A scope-restricted credential lists fewer families, and for a hidden one
+`dr <family> --help` is refused with exit 3 naming the missing
+`resource:action` — check `dr whoami` before concluding anything. Otherwise the short
+listing is a missing identity: run it as `dr --help --server <key>`, plus
+`--account <email>` where that server holds several identities, and the
+per-family and per-command `--help` render in full either way. A short root
+listing is never a missing command.