@datarails-ai/dr-cli 1.6.123 → 1.6.124

package/dist/scopes-map.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "cliVersion": "1.6.123",
+  "cliVersion": "1.6.124",
   "_contract": "Resolve a command path through `aliases` (canonical prefix + alias segment -> canonical path) before any lookup. A path listed in `pendingCommands`, or whose first segment is a key of `pending`, is UNDECIDED, not unrestricted: fail closed or skip it, and never read a path's absence from `commands` as 'no requirement'. An entry carrying `denied` is UNAVAILABLE to any AGENT-SCOPED credential — one whose `scopes` claim carries at least one `resource:action` entry; a claim that is absent, empty, capability-only or wholly unparseable is UNRESTRICTED, and this mark does not apply to it — whatever else that entry says: it is not a ceiling and it is not always-available, its `denied.reason` says why and `denied.until` names the ticket that lifts it, and the absence of `requires` on it must NEVER be read as 'no requirement'. Only an entry in `commands` with an empty `requires` means always-available.",
   "commands": {
     "login": {
@@ -2315,6 +2315,22 @@
         }
       ]
     },
+    "filebox kind-explain": {
+      "requires": [
+        {
+          "resource": "fileboxes",
+          "action": "read"
+        }
+      ]
+    },
+    "filebox kind-summary": {
+      "requires": [
+        {
+          "resource": "fileboxes",
+          "action": "read"
+        }
+      ]
+    },
     "filebox rescan-version": {
       "requires": [
         {

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

@@ -1,6 +1,6 @@
 ---
 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.
+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", "why does filebox N have its type", "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
@@ -296,6 +296,10 @@ area's gotchas.
   Destinations must come from `organizations push-targets`.
 - `filebox data-query get|set|set-sync-interval|clear|sync` (alias `dq`)
 - `filebox validation-rules options|set`
+- `filebox kind-explain <id…> [--history] [--as-of DATE] [--json]` / `filebox kind-summary [--json]` —
+  why a filebox has its type and whether it still matches its connections, and
+  how far an organization is typed. Read-only, **support seat of that
+  organization only** (`login-as` it, then `--account`).
 - `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`
@@ -636,7 +640,11 @@ network traffic or hand-edits JSON. Full recipes in the relevant reference file.
   an unvalidated escape hatch that forwards straight to the server; a
   malformed value 500s with no error body. To know when it finished, add
   `--wait` — never poll `status` or the version count: an unchanged result
-  writes no new version and still reads `SYNCED`. See
+  writes no new version and still reads `SYNCED`. Never backfill
+  **balances** from an aggregator (Plaid, Quiltt, Salt Edge, Flinks): it
+  returns today's balance for every `--date`, so each period gets an
+  identical copy. Backfill transactions only; sync balances for the current
+  period and let the nightly schedule build the history. 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
@@ -658,7 +666,7 @@ Each also names the relevant Help Center (KB) folder for customer-facing docs.
 - [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/filebox-documents.md](reference/filebox-documents.md) — fileboxes, documents, filebox type
 - [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

package/dist/skills/dr-cli/reference/filebox-documents.md

@@ -21,6 +21,97 @@ listed here before (or without) its rows landing in the mapped tables — track
 that separately with `dr scans status <table_id>`. Change the flag with `filebox
 set-version-include` (below).
 
+### Why a filebox has its type (support seat only)
+
+- `filebox kind-explain <id> [<id> …] [--history] [--as-of YYYY-MM-DD] [--json]`
+  — why each filebox has its stored type, and whether its connections still
+  say the same. Read-only; it answers before the organization's flag is on,
+  and says when the organization is outside the rollout.
+  - **Output fields.** `meaning` first, in plain words: who set the type,
+    whether its connections still say the same and, when they do not,
+    whether a hand-set type is meant to stay or who may retype it. A type is
+    hand-set when either slot was set by a user or support, and slots set by
+    different hands are named one by one. Then `stored` (each slot and who
+    set it: the migration; a flow, at creation or when a connection was
+    added later; a user; support; default; `source not recorded` when the
+    server has none), `rules` (what the migration's rules make of it today,
+    and whether the two agree), `rule`, `unsure`, `why`, `dropped`,
+    `why not`, `evidence` (mappers, tables, data source, drive, email / API
+    upload) and, with an integration connected or an upload on,
+    `integration`: whether it counts as Integration, a connected data query
+    or drive with whether it is quiet and the dates that decided, an upload
+    with no quiet rule and no dates.
+  - **Who may retype.** The support seat, for any move with Lookup or
+    Integration held before or after it (Lookup + Model → Lookup too),
+    except Report added or removed beside an Integration that stays, or a
+    new format there. The owner or the support seat, for that exception and
+    for moves among Manual input, Model and Report. The support seat may
+    make any move. The CLI has no retype command: a retype is made in the
+    filebox settings of the web app.
+  - **Upload rule.** Email or API upload on is an Integration signal, with
+    no quiet rule, whatever the content. The migration (and `rules`) puts
+    Integration in place of a Model: Model → Integration, Model + Report →
+    Integration + Report, Lookup + Model → Lookup + Integration. A Lookup
+    becomes Lookup + Integration, Report content gives Integration +
+    Report, anything else gives Integration. Turning an upload on later,
+    as the owner or the support seat, adds Integration to the stored type
+    the same way, except that it keeps a Model: Model, Model + Report and
+    Lookup + Model keep their type. So a Model whose upload was turned on
+    after it was typed stays Model while `rules` holds Integration. That
+    drift is expected, not an error, and the `meaning` says so: "Email
+    upload is on: the migration puts Integration in place of a Model, but
+    turning the upload on after it was typed keeps the Model, so the stored
+    type stays Model." A hand-set Model gets no such line: a type set by
+    hand stays anyway.
+  - **`--history`** adds the recorded type changes, newest first, each with
+    its reason in words: a retype in the filebox settings, a table attaching
+    it as a lookup, a LUT/FX label set or removed (by the old "Filebox type"
+    setting or the report builder), a data source (data query, SFTP) or
+    synced cloud-drive file connected to an empty filebox or to a Report, an
+    email / API upload turned on, or its first file setting a Report's
+    format. A reason the CLI does not know prints as sent. Empty is normal:
+    the migration and a creation record nothing, so a flow's slot with no
+    event was set at creation. It is empty too when the audit server could
+    not be read.
+  - **`--as-of`** moves only the quiet-integration answer. With a connected
+    integration a disagreement can come from time alone (quiet after 90
+    days with no file, sync attempt or schedule), so
+    `--as-of <backfill day>` judges it as the migration did. Not with an
+    upload on: an upload counts on any day, and the `meaning` then says
+    nothing about time.
+  - **Not found** lists the ids with no answer: another organization's
+    filebox, a folder, an id that does not exist. Another organization's
+    filebox needs that organization's support seat.
+- `filebox kind-summary [--json]` — for the seat's organization: live and
+  archived fileboxes, typed and untyped, who set the types (`flow` is a flow
+  at creation or a connection added later, not only the creation;
+  `source not recorded` is the server's `(none)`), every stored combination, and
+  `uploads` (the server's `upload_channel_kinds`): the stored type of every
+  live filebox with email or API upload on. A Model there is expected, not
+  an error: its upload was turned on after it was typed (the upload rule
+  above), or it was set by hand. Its untyped ones are keyed
+  `untyped` in the readable output and `(untyped)` under `--json`.
+- **Both answer only the support seat of the organization asked about** (405
+  otherwise, even for a support person sitting in a customer user's seat).
+  Find that seat with `dr users can-login-as --search <org> --server <S>`:
+  the row of that organization with `SUPPORT` `true` gives its email, and
+  its `ID` also works as `dr login-as <email> --user-id <ID>`. Then run
+  `dr login-as <support seat email> --server <S>`, and the command with
+  `--account <that email>`. A 403 means a blocked seat; a 404 means the
+  server does not have the endpoints yet (dr-datarails-server PR #8010).
+- Over 200 ids (20 with `--history`) are sent as several requests; `--json`
+  then prints one merged body in the server's shape. A single request's
+  `--json` is the server's body unchanged. Either way `--json` keeps the HTML
+  entities the server sends (`P&amp;L`): unlike `filebox list --json`, names
+  are not decoded.
+- The answer names the organization's tables and connections, and
+  `--history` adds the email addresses of the people who changed a type,
+  login-as operators included. That is fine for the organization's own
+  support seat, the only caller allowed, but do not paste a full answer or a
+  `--json` file outside that organization's context: quote the lines you need.
+- A request the server finds too heavy answers 503
+  `kind_explanation_too_heavy`: ask for fewer ids at a time.
+
 ## Filebox — create / upload
 
 - `filebox create` — empty filebox + date tag. `--folder` makes a folder filebox
@@ -49,6 +140,13 @@ set-version-include` (below).
   editable here** — the server returns 200 but silently drops them. Use
   `set-tag-config` for tags; set scenario at create time via
   `filebox create --scenario`.
+  - `use_type` can change the stored **filebox type** where the
+    organization's filebox-type flag is on (DR-53666): a LUT / FX label set by
+    the owner or the support seat adds Lookup, and moving a Lookup off its
+    LUT / FX label is a retype that can answer 405 `kind_change_support_only`
+    or 409 `kind_still_connected` (a table still reads it). Check the result
+    with `filebox kind-explain` (see "Why a filebox has its type" above). The
+    CLI has no retype command: a retype is made in the web app.
 - `filebox set-tag-config <doc_id> --add NAME [--add …] [--remove NAME …]` —
   merge semantics (adds/removes against the existing config, not full-replace);
   tag names matched case-insensitively against the tenant tag pool.
@@ -289,6 +387,30 @@ set-version-include` (below).
   constant — varies per tenant) and the epoch just needs to fall within the
   target period (the server normalizes it). Prefer `--date`; reach for raw
   `--tag` only when it doesn't cover your case.
+- **Backfilling balances: which connections can do it.** `--date` only tags
+  the version; whether the data changes with it depends on the connection
+  (the data-query's `objectType` and the data source's type):
+  - **Aggregator balances (Plaid, Quiltt, Salt Edge, Flinks) — do not
+    backfill.** The aggregator returns **today's** balance whatever date is
+    requested, so N `--date` values write N identical versions, each tagged a
+    different period — the filebox looks populated but asserts balances that
+    were never true on those dates, and any trend over that window reads flat.
+    Sync balances for the **current period only** (one `--date` of today, or
+    no `--date`) and let the nightly schedule build the history from there.
+    When a `sync --date` on an aggregator balances query names a period other
+    than today's (today by the local or the UTC date), it prints a `warning:`
+    on stderr before syncing (and, with `--wait --json`, the same text in
+    `warnings`). It still syncs: the warning never blocks. It is best-effort —
+    it reads the data-query and its data source, so a user or scoped
+    credential that cannot read the data source (a viewer, a token without the
+    integrations scope) gets no warning; the rule still applies.
+  - **Aggregator transactions — backfill freely.** Aggregators serve real
+    transaction history, so a full-period transactions backfill is correct.
+  - **Direct bank API connections — backfill balances if needed.** These can
+    request a historical balance, so multi-period balance backfill is the one
+    case where it makes sense.
+  - **SFTP — nothing to backfill.** The bank pushes the files on its own
+    schedule and no date is requested, so `--date` has nothing to vary.
 - **Waiting for a sync: `filebox data-query sync <fb_id> --date … --wait`.**
   Never poll `status` or the version count yourself — both lie:
   - With `sync_only_changes` (the default), a sync whose output is identical
@@ -310,7 +432,8 @@ set-version-include` (below).
   the data-query goes to `ERROR` (with the server's `last_sync_error`) or on
   `--timeout <seconds>` (default 1800). `--json` prints one object:
   `{outcome, periods: [{period, result: new_version|no_change|pending,
-  version_id, version}], unmatched_new_versions, error, waited_seconds}`.
+  version_id, version}], unmatched_new_versions, error, waited_seconds,
+  warnings}` — `warnings` repeats any pre-sync `warning:` lines (empty when none).
   Without `--date`, it waits for the first period to finish. It cannot be
   combined with `--tag`. One blind spot: a sync that returns **no rows**
   writes no version and re-confirms none, so it ends in a timeout whose
@@ -395,7 +518,11 @@ with `filebox list --account <destination>`.
   version, scoped to a target template's mapping context.
 - `documents support-api set <doc_id> --on|--off` — toggle the doc's
   `support_api` flag. The server rejects turning it **off** while a
-  Workato/WorkatoBased connection is in play.
+  Workato/WorkatoBased connection is in play. Where the organization's
+  filebox-type flag is on, turning it **on** as the owner or the support seat
+  also adds Integration to the stored filebox type (Model, Model + Report and
+  Lookup + Model keep theirs); turning it off changes no type. See "Why a
+  filebox has its type" under Fileboxes.
 - `documents calculate <doc_id> --year|--quarter|--month|--day|--week … [--backward] [--no-roll]`
   — human-readable target (e.g. `--month 2026-04`); the CLI resolves the matching
   tag and posts calculate. Errors list the doc's available dimensions when the

package/dist/skills/dr-filebox-api-setup/SKILL.md

@@ -14,6 +14,8 @@ Automates the two-step filebox setup that enables external systems (e.g. Workato
 
 Both steps are run for every target filebox. Fileboxes can be specified directly by ID/name or resolved from a parent folder.
 
+**Both steps can change a filebox's type.** Where the organization's filebox-type flag is on, `support-api set --on` adds Integration to the stored type (Model, Model + Report and Lookup + Model keep theirs), and `data-query set` adds it to an empty filebox or one typed exactly Report, when the seat is the filebox's owner or its organization's support seat. After Step 5, verify each one with `dr filebox kind-explain <id> --server <S> --account <support seat email>`, run as that organization's support seat (`dr login-as <support seat email> --server <S>` first); the `dr-cli` skill's filebox reference, "Why a filebox has its type", says how to find that seat and how to read the answer.
+
 ---
 
 ## Inputs to gather before running

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datarails-ai/dr-cli",
-  "version": "1.6.123",
+  "version": "1.6.124",
   "description": "Datarails CLI",
   "type": "module",
   "engines": {