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

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

@@ -0,0 +1,373 @@
+# Fileboxes & documents
+
+## Filebox — read
+
+`filebox list`, `filebox get`, `filebox versions`, `filebox tags`,
+`filebox sheets`, `filebox preview`, `filebox shares <doc_id>` (current user +
+group shares). Names are HTML-decoded before render.
+
+`filebox versions <doc_id>` lists **active** versions by default (unchanged).
+To see archived (auto_save) versions, pass `--archived` (archived only) or
+`--all` (active + archived); both add an `ARCHIVED` column. This is the only
+way to discover an archived version's id from the CLI — archived rows are
+absent from the default listing and from `list --include-versions`.
+
+`--included` narrows any of those to the versions whose **`include_file` flag is
+on** and adds an `INCLUDED` column. The flag is the server's intent, not proof
+of delivered rows: turning it on only queues an ETL scan, so a version can be
+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).
+
+## Filebox — create / upload
+
+- `filebox create` — empty filebox + date tag. `--folder` makes a folder filebox
+  for nesting (no date tag). `--no-date` allocates the doc with no date tag.
+  `--scenario <s>` sets scenario **at create time** (the only working way to set
+  it — see update below). `--date-sub-type <t>` sets the initial tag config;
+  `--parent <id>` nests it.
+- `filebox upload` — one-shot create + populate. **Known failure on
+  freshly-bootstrapped tenants:** returns 401 even with a valid JWT (re-running
+  `dr login` does not help). Workaround: `filebox create --no-date` to allocate
+  the doc id, then `filebox upload-version <id>` to push the data.
+- `filebox upload-version <id>` — push a new version. Accepts `--date <date>
+  --scenario <name>` to validate-then-tag at upload time in one call (planning
+  fileboxes — same validation and read-back confirmation as
+  `set-version-cycle`).
+- `filebox download` — download document content.
+
+## Filebox — update / config
+
+- `filebox update <id> [--name <s>] [--payload-file <p>]` — PUT editable fields:
+  `name`, `parent`, `auto_save`, `date_format`, `use_type`,
+  `is_present_in_dashboard_reports`. **`scenario` and `tags_config_str` are NOT
+  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`.
+- `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.
+- `filebox set-parent <doc_id> --parent <pid> | --detach` — `--detach` moves to
+  root; mutually exclusive with `--parent`.
+- `filebox archive` (two-step; sets `is_archive`, recoverable until async
+  cleanup), `filebox archive-version <vid>` (two-step),
+  `filebox restore-version <vid>` (no confirm — non-destructive).
+  - Both `archive-version` / `restore-version` also accept the version by its
+    per-filebox **number** instead of the global id: `restore-version --doc
+    <doc_id> --version-number <n>` or `--latest-archived` (un-archive the
+    newest archived version); `archive-version --doc <doc_id> --version-number
+    <n>` or `--latest-active`. The CLI maps number → global id client-side
+    (there is no by-number endpoint). Success output names both, e.g.
+    `Restored version 12 (id 90001).` Typical flow: `filebox versions <doc>
+    --archived` to find it, then `restore-version --doc <doc> --version-number
+    <n>`.
+- `filebox lock | unlock | lock-date-tag | unlock-date-tag | locked-date-tags` —
+  filebox / per-date-tag locks. `lock-date-tag`/`unlock-date-tag` take a
+  dimension flag (`--month 2026-04`, `--day 2026-04-15`, …) and resolve the
+  target epoch from the filebox's **actual version tags** (`tags[].value`), so
+  the lock matches real versions — a period with no matching version errors
+  loudly instead of silently no-op'ing (DR-51292). Pass `--value <epoch>` to
+  lock a raw stored value directly (from `filebox versions <id> --json`).
+- `filebox get-auto-calc-settings`, `filebox set-option`, `filebox set-tag-config`,
+  `filebox share`, `filebox shares`, `filebox set-parent` — see `--help`.
+
+### Version include-in-database
+
+- `filebox set-version-include <vid> --include on|off [--json]` — write the
+  per-version **Include in database** flag (`include_file`), the switch that
+  decides whether that version's rows reach its mapped tables. Read it with
+  `filebox versions <doc_id> --included`.
+  - Address it like `archive-version`: by global version id, or `--doc <doc_id>`
+    with `--version-number <n>` / `--latest-active`, or `--doc <doc_id>
+    --all-except-latest` for the bulk sweep (every active version behind the
+    latest). The sweep never **targets** the latest — but that is not a promise
+    that something still feeds the table: if the latest is itself excluded, an
+    exclude sweep leaves nothing included, and the plan step says so in its
+    `latest:` line.
+  - **Two-step confirm in both directions**, because both change table data:
+    `--include off` deletes that version's rows from every table it feeds,
+    `--include on` queues an ETL scan. The plan step prints the current → new
+    flag per version and, for the bulk sweep, every target plus the kept latest.
+  - A version already at the requested value is reported and skipped — the
+    server answers 200 without writing in that case, so a blind PUT looks like a
+    change it never made. Same guard catches the server's other silent
+    early-return: including a version whose filebox has an active budget split
+    for that dimension leaves the flag alone, and the CLI errors instead of
+    claiming success.
+  - Only reaches **non-archived** versions of **non-config** fileboxes (the
+    endpoint's queryset filters both) — a 404 usually means one of those, not a
+    bad id. `versions --all` shows which.
+  - `--all-except-latest` reads "latest" as the **single highest per-filebox
+    version number**, and refuses (rather than guessing) when two active
+    versions tie on it. On a filebox whose versions carry **dimension tags**
+    (per-department splits and the like) that is the newest upload overall, not
+    the newest per dimension — so the sweep would exclude the current version of
+    every *other* dimension. Read the plan's target list before confirming; for
+    those fileboxes address versions individually.
+  - Typical cleanup on a CoA-style filebox where stale monthly snapshots are all
+    still feeding the table: `filebox versions <doc> --included` to see the
+    damage, then `filebox set-version-include --doc <doc> --all-except-latest
+    --include off`.
+
+### Version tagging
+
+- `filebox set-version-date-tag <vid> --doc <id> --month|--quarter|--day|--year|--week …
+  [--json]` — set the date tag on one version (resolves the tag id from the doc's
+  config; other tags untouched).
+- `filebox set-version-workflow <vid> --doc <id> --status <Not Started|In Progress|Pending|Approved|Rejected>`
+  — set the workflow LIST-tag value (setting `Approved` requires `approve_workflow`).
+- `filebox set-version-file-status <vid> --doc <id> --status <Draft|Final> [--json]`
+  — set the File Status LIST-tag value (other tags untouched). This is how a
+  version uploaded with `upload-version` (always Draft) is made Final without the
+  UI. Final needs `assign_final`. Only one version per period can be Final: if
+  another one already is, the command also needs `override_final`, and the server
+  moves that version to Draft (the output names it). The status is read back and
+  re-applied once if it did not stick. The write queues a rescan of the version,
+  so mapped tables show the new `File Status` only after it finishes.
+- `filebox set-version-cycle <vid> --doc <id> --date <date> --scenario <name>
+  [--date-tag-name <n>] [--json]` — **forecast/budget (planning) fileboxes only.**
+  Sets the cycle date tag and the scenario LIST-tag together (both flags
+  required), mirroring the planning UI. **Validates the `(date, scenario)` pair
+  against `dr forecast scenarios` before writing**, so a version can never be
+  tagged into a non-existent cycle/scenario — create the cycle/scenario first
+  with `forecast scenarios create`. `--date-tag-name` disambiguates when a budget
+  filebox exposes more than one DATE tag.
+  **The tag is confirmed by reading the version back**, because a 2xx from the
+  write does not prove it stuck: on a filebox with an active auto-calculate
+  cascade the recalculation can replace the version or its tags moments later,
+  which used to leave an untagged version behind a successful command
+  (DR-52508). The read waits ~2s first — an immediate read sees a tag that is
+  about to be clobbered. If the pair is not there the command re-applies it
+  once, and only then fails, naming what the server actually holds and the
+  command to re-run. **This adds ~2s to a tagged write** (~4s when a re-apply
+  is needed); `set-version-cycle` therefore runs on the 5-minute call budget,
+  not the 30s default.
+  The date tag is compared **by period, never by exact epoch** — the server
+  normalizes what it is sent (`use_end_of_period_for_date`) and stored values
+  carry a noon/midnight offset, so equality would fail writes that succeeded
+  (same reason as `lock-date-tag`, DR-51292). Granularity comes from the date
+  tag's `sub_type`/name; a forecast filebox's `Forecast (New)` tag has none, so
+  only the tag's presence is checked there. The scenario tag is compared
+  exactly.
+  On an upload the confirmed row is also cross-checked against the upload
+  response (version number, name, filebox) — if the response only carried a
+  `latest_version_id` the cascade had already moved, the tag went to the wrong
+  version and the command says so instead of confirming.
+  `--json` always reports `verified: true|false`, and still emits the record
+  (with `error`) when the tag fails, so a scripted retry has the version id.
+  Cases the command deliberately does **not** fail on, since the write itself
+  returned 2xx: a version it cannot read back, and a confirmation cut short by
+  the call budget — both give `verified: false` plus an `unverified_reason` and
+  a stderr warning.
+
+### Share / options / sync
+
+- `filebox share <doc_id> --user EMAIL:ROLE [--user …]` — ROLE is
+  `ADMIN|CONTRIBUTOR|VIEWER` or numeric `1|2|3`. Discover email candidates via
+  `organizations contacts`; groups via `organizations permission-groups`.
+- `filebox set-option <doc_id> --bank-integration on|off [--option KEY=VALUE …]` —
+  only allow-listed keys are accepted (currently `is_bank_integration`); unknown
+  keys are rejected client-side (the server silently accepts dead keys).
+- `filebox data-query get|set|clear|sync <fb_id>` — read/write/delete/poke the
+  Workato data-query. `get` shows `sync_interval` (cron) + `last_sync`; `set
+  --payload-file` PUTs a create/update body; `clear` is two-step.
+- `filebox data-query sync <fb_id> [--date YYYY-MM-DD]` — trigger an async
+  sync, optionally scoped to specific period(s). `--date` is repeatable and
+  takes one plain calendar date — the CLI reads the filebox's own DATE
+  tag(s) from `tags_config` and truncates the date to whatever granularity
+  each one uses, so `--date 2026-07-01` syncs "July 2026" on a monthly
+  filebox, "Q3 2026" on a quarterly one, "2026" on a yearly one, or the
+  exact day/ISO week on a daily/weekly one — no need to know or care which
+  granularity a given filebox uses. A filebox with more than one DATE tag
+  resolves all of them into one sync target. Repeat `--date` to backfill
+  several periods in one call (one sync target per value). With no `--date`,
+  the sync targets whatever period the connector resolves as
+  current/default. **`--tag <json>`** still exists as an escape hatch for
+  tag dimensions `--date` doesn't cover (e.g. LIST tags like Plan/Forecast)
+  — it forwards the given string completely unvalidated to
+  `POST /api/documents/<id>/data_query_sync` as one `multiple_tags` element.
+  The server does an unguarded `json.loads()` + `tag['id']`/`tag['name']`
+  dict access on each element, so a malformed value throws an uncaught
+  exception that surfaces as a **bare HTTP 500 with no error body** — if you
+  ever need it directly, the required shape is
+  `[{"id":<tag_id>,"name":"<TagName>","value":<epoch_in_target_period>}]`,
+  where `id`/`name` come from that tenant's `dr filebox tags` (not a
+  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.
+- `filebox data-query set-sync-interval <fb_id> --cron "<expr>"` — change how
+  often the data-query polls (Workato-backed **and** connector-platform /
+  `DatarailsConnector` fileboxes both use this cron). **Use this for sync
+  frequency, not `set-auto-calc-frequency`.** The cron is stored/evaluated as
+  **5-field UTC** — an optional 6th field is folded into UTC, so `0 */3 * * *`
+  fires every 3h on UTC boundaries, not local time. Known behavior: any PUT to
+  the data-query resets `status` from `SYNCED` to `null` (write = "sync state
+  uncertain until next run"); it heals on the next cron fire — do not try to
+  "fix" it.
+  - **`--offsets` / `sync_offset_array`.** Every scheduled run syncs a set of
+    **period offsets** stored as `sync_offset_array`: `0` = the filebox's
+    current period, `-1` = the previous one, etc.
+    (`DataIntegrationQuery.get_default_tags_with_offset_array` iterates them; the
+    `{{ date_tag }}` placeholders in a connector Sync-query render against each
+    offset's period — so offsets, not the cron, decide *which* periods a run
+    pulls). `set-sync-interval` resolves them so it **never PUTs an empty array**
+    (the server's write serializer is `ListField(allow_empty=False)` and 400s on
+    `[]`, which is what a freshly-created data-query has): explicit `--offsets`
+    wins, else the existing non-empty array is preserved, else it defaults to
+    `[0]` ("re-fetch the current period each run"). So the bare command now works
+    on a data-query that never had offsets:
+    ```bash
+    dr filebox data-query set-sync-interval <fb_id> --cron "0 */3 * * *"          # -> offsets [0]
+    dr filebox data-query set-sync-interval <fb_id> --cron "0 */3 * * *" --offsets 0,-1
+    ```
+    `--offsets` is a comma-separated integer list; server constraints (validated
+    client-side first): non-empty, **max 10** items, each int in **[-100, 100]**.
+    (If you hand-build a `data-query set --payload-file` body instead, you must
+    include a non-empty `sync_offset_array` yourself — that path does no
+    defaulting.)
+- `filebox set-auto-calc-frequency <doc_id> --cron "<expr>" [--enable]` —
+  two-step. Controls Datarails **auto-calculate** scheduling, a **different**
+  feature from the Workato sync cron. `--enable` bootstraps auto-calc if it's
+  currently off. (`set-sync-frequency` is a deprecated alias that warns.)
+- `filebox validation-rules options` — fetch the rule schema. `filebox
+  validation-rules set <doc_uuid> [flags] | --file <path>` — idempotent
+  create/update; **takes the document UUID, not the integer id.**
+
+### Push a filebox to other organizations
+
+`filebox push <id> --to <orgs> [--override]` — two-step confirm, max 50
+destinations per run. **Only the filebox's latest version travels.**
+
+1. `organizations push-targets` lists the eligible destinations. `--to` takes
+   their ids or names, comma-separated or repeated. 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 without `--confirm-token` for the plan, then re-run with the token.
+
+The push carries the filebox's data mappers, data queries, functions,
+ex-tables, dynamic ranges and LUTs with it. If any of those can't be cloned
+into a given destination, **that whole destination is skipped** — the others
+still run.
+
+There is no flag for pushing full version history. The endpoint accepts one, but
+only the newer of the server's two export implementations reads it — a
+destination on the older path takes the request and clones the latest version
+alone, with nothing in the response to say so, and the pushing user cannot read
+the destination's flags to find out. To move earlier versions, upload them in the
+destination or use the web UI, which sends the same field with the same caveat.
+
+**`--override` off does not guarantee a new filebox.** When the destination org
+has the alias-matching behavior enabled server-side, a source filebox whose
+alias *and* tags match an existing destination filebox pushes a new version into
+that filebox instead of creating one. `--override` additionally targets the
+filebox a previous push created (matched by source id); if both match, both
+receive a version. To be certain what happened, check the destination after the
+push.
+
+Queued and returns no job id — results arrive as in-app notifications. Confirm
+with `filebox list --account <destination>`.
+
+## Documents
+
+- `documents sheets <doc_id> --template <tid>` — sheet names on the doc's latest
+  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.
+- `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
+  requested one is missing.
+- `documents debug-zip <doc_version_id> --output <path>.zip [--type published_item|presentation]`
+  — **`<doc_version_id>` is a DocumentVersion id, not a doc id** (get it from
+  `filebox versions <doc_id>`). `--type` defaults to `published_item`. A 400
+  "no debug file" is surfaced verbatim.
+- `documents auto-calculate <file.xlsx> [--out <path>] [--poll-interval <s>] [--timeout <s>]`
+  — **filebox-less** one-shot calc (DR-48445). Uploads a raw `.xlsx` to
+  `POST /api/documents/auto_calculate`, polls
+  `GET /api/documents/auto_calculate/<request_id>`, and writes the calculated
+  workbook to disk (default `<name>_auto_calculated.xlsx` next to the input).
+  Distinct from `filebox get-auto-calc-settings` / `set-auto-calc-frequency`,
+  which schedule auto-calc **on an existing filebox** — this one needs no
+  document at all. The result is one-shot: the server discards its copy once
+  downloaded, so a re-run means re-uploading. `--poll-interval` defaults to 2s,
+  `--timeout` to 300s; a server-side calc failure surfaces the BE error (e.g.
+  `incorrect formula syntax`) verbatim.
+- `documents add-functions <file.xlsx> --function <id> [--function <id> …] [--out <path>] [--poll-interval <s>] [--timeout <s>]`
+  — **filebox-less** function registration (DR-50743): the CLI sibling of
+  `auto-calculate`. This is the **"add a function to an Excel file"** command —
+  it lives under `documents`, **not** under `functions` (which only read/write a
+  function's definition). Each `--function <id>` is resolved to its canonical
+  name (`GET /api/functions/<id>`); the workbook + the `[{id,name}]` list are
+  uploaded to `POST /api/documents/add_functions`, polled, and the result is
+  written to disk (default `<name>_functions_added.xlsx` next to the input).
+  Fails fast **before any upload** on an empty `--function` list or an unknown
+  id. `--poll-interval` defaults to 2s, `--timeout` to 300s. Same one-shot
+  contract as `auto-calculate` — the server discards its copy once downloaded,
+  so a re-run means re-uploading. To find the ids, `functions list`.
+- `documents add-extables <file.xlsx> --extable <id> [--extable <id> …] [--out <path>] [--poll-interval <s>] [--timeout <s>]`
+  — **filebox-less** ExTable registration (DR-50832): the ExTable counterpart of
+  `add-functions`. This is the **"add an ExTable to an Excel file"** command; it
+  lives under `documents`, **not** under `extables` (which only
+  `list|get|clone|delete`). Each `--extable <id>` is resolved to its name from
+  the tenant; the workbook + list are uploaded to
+  `POST /api/documents/add_extables`, polled, and written to disk (default
+  `<name>_extables_added.xlsx` next to the input). Same one-shot contract as
+  `auto-calculate` / `add-functions`. To find the ids, `extables list`.
+- `documents add-dynamic-ranges <file.xlsx> --range <id> [--range <id> …] [--formula <formula>] [--preserve-static-values] [--out <path>] [--poll-interval <s>] [--timeout <s>]`
+  — **filebox-less** Dynamic Range registration (DR-50909): the Dynamic Range
+  counterpart of `add-extables`. This is the **"add a Dynamic Range to an Excel
+  file"** command; it lives under `documents`, **not** under `dynamic-ranges`
+  (which `list|get|create|update|delete|data`). Each `--range <id>` is resolved
+  to its name from the tenant (`GET /api/templates/dynamic_range/<id>` — the
+  per-id endpoint, so **no `--table` is needed**); the workbook + `[{id,name}]`
+  list are uploaded to `POST /api/documents/add_dynamic_ranges`, polled, and
+  written to disk (default `<name>_dynamic_ranges_added.xlsx` next to the input).
+  Unlike ExTables/functions, the **server resolves and pushes each range's row
+  data to xl-calculate itself** (dynamic ranges have no pull endpoint) — the CLI
+  only supplies `{id, name}`.
+  - **Formula column (optional, server PR #6772):** attach a formula column to
+    the range with `--formula "<formula>"`, e.g. `--formula "=DR.QTD(rev)"`.
+    One formula per range and **no id prefix**, so `--formula` requires **exactly
+    one `--range`** (to formula-annotate several ranges, run the command once per
+    range). The string is **verbatim pass-through** — the server does no
+    resolution and forwards it to xl-calculate, which draws the formula column
+    next to the range list. A range added with no `--formula` is drawn
+    **list-only** (no `formula_columns` key sent). Because the formula is
+    caller-supplied, the CLI does not derive it from a Datarails function — pass
+    the literal Excel formula you want. **The formula must invoke a recognized
+    Datarails `DR.*` function** as its leading function (e.g. `DR.GET`, `DR.YTD`,
+    `DR.QTD`, `DR.MTD`, `DR.YTG`, `DR.QTG`, `DR.MTG`, `DR.ROLLINGMONTHS`,
+    `DR.CUMULATIVE`, and the rest of the `NewCustomFunctions.cs` table) —
+    validated case-insensitively, tolerating a leading `=` / `=@`. A typo or a
+    plain Excel formula (`=SUM(...)`) is rejected before any upload.
+  - **Preserve static values (optional, DR-52682):** pass
+    `--preserve-static-values` to register every `--range` with
+    `Preserve_Static_Values: true` in the workbook's `dr_control ->
+    _dr_dynamic_ranges` section. That flag is what keeps **hand-entered values**
+    in a dynamic range when it refreshes; without it a refresh or category
+    update can **wipe values the user typed**, which on a budget template is the
+    whole deliverable. Omitting the flag sends no key, which is **not** the same
+    as safe: a range the uploaded workbook already carries keeps its stored
+    value, but a range being registered for the **first time** — the normal case
+    for this command — gets xl-calculate's `false` default. So on a budget file
+    you are building from scratch, **pass the flag**; leaving it off ships the
+    exact data-loss risk DR-52682 is about. The CLI never sends an explicit
+    `false`, so re-running without the flag will not clear a range that already
+    has it set. Requires a server that accepts the field (monolith PR #7437) —
+    older servers silently ignore it.
+  - Same one-shot contract as `auto-calculate` / `add-functions` /
+    `add-extables`. To find the ids, `dynamic-ranges list --table <template_id>`.
+
+> **Lookups (LUTs)** moved to their own reference — see
+> [reference/lookups.md](lookups.md) for `lut …` (both filebox-sourced and
+> table-sourced). A filebox document is the *source* for a filebox-sourced LUT,
+> but the lookup commands live there now.
+
+## Customer-facing docs (KB)
+
+Help Center → **"Getting Data into Datarails"** → Filebox. Find current articles with `dr kb search "filebox"` (or
+browse `dr kb categories` / `dr kb sections`). Cite the article; don't
+paraphrase from memory.

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

@@ -0,0 +1,51 @@
+# Forecast management (Planning)
+
+Date inputs accept `YYYY-MM-DD` or a 10-digit Unix timestamp.
+
+**Two planning-scenario families exist: `Forecast` and `Budget`.** The list
+commands default to **`Forecast`**, so budget cycles are invisible unless you
+pass `--scenario Budget`. The same scenario NAME can exist in both families, so
+omitting the flag returns a plausible wrong answer rather than nothing. A budget
+file that "isn't in the Budget module" is often one whose cycle was read from
+the wrong family. When working on a budget, pass it every time.
+
+Read:
+
+- `forecast cycles list [--year] [--scenario Forecast|Budget]`,
+  `forecast cycles get <date>`,
+  `forecast cycles documents <date> [--with-names]`.
+- `forecast scenarios list [--cycle <date>] [--year <Y>] [--scenario Forecast|Budget]`,
+  `forecast scenarios get <id> [--no-versions] [--no-splits] [--no-collection-processes]`,
+  `forecast scenarios versions <id>`.
+
+Write (all two-step confirm):
+
+- `forecast cycles lock|unlock|set-default <date>`.
+- `forecast cycles roll-forward <src> --to <dest> [--raw-tags <json>]`.
+- `forecast scenarios create --cycle <date> --name <value> [--scenario <family>]
+  [--default] [--locked]` — `--scenario` picks the planning family and defaults
+  to `Forecast`. **Pass `--scenario Budget` to create a budget cycle**; without
+  it the row lands in the Forecast family under a budget-looking name and the
+  Budget module never shows it.
+- `forecast scenarios delete|lock|unlock|set-default <id>`.
+- `forecast scenarios clone <src-id> --to-cycle <dest-date> --to-scenario <name>
+  [--raw-tags <json>]` — the destination is a `(cycle, scenario-name)` **pair**;
+  `--to-scenario` is required unless `--raw-tags` is given (they're mutually
+  exclusive). `--to` is a deprecated alias for `--to-cycle`. **Empty-source
+  guard:** clone refuses (non-zero exit) if the source scenario has no versions —
+  use `scenarios create` for an empty shell.
+- `forecast scenarios clone-from-budget --source-budget-cycle <id>
+  --to-cycle <dest> --to-scenario <name> [--documents <ids>] [--raw-tags <json>]`
+  — same `--to-cycle`/`--to-scenario`/`--raw-tags` rules.
+- `forecast scenarios bulk-edit --cycle <date> [--add a,b] [--delete c,d]`.
+
+`clone` and `clone-from-budget` auto-build the destination date-tag + scenario-
+name-tag; `--raw-tags '[{"id":…,"value":…}, …]'` overrides for edge cases. The
+CLI does not pre-check destination-name collisions — the server is authoritative
+(appends versions or rejects; the response is surfaced verbatim).
+
+## Customer-facing docs (KB)
+
+Help Center → **"Planning"** category (Forecast / Budget). Find current articles
+with `dr kb search "forecast cycle scenario"` (or browse `dr kb categories` /
+`dr kb sections`). Cite the article; don't paraphrase from memory.

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

@@ -0,0 +1,57 @@
+# Integrations & company data sources
+
+## Customer connectors (`integrations`, alias `integration`)
+
+Read:
+
+- `integrations list`, `integrations get` (`--show-secrets` for cleartext config),
+  `integrations types`, `integrations status`, `integrations query-status`,
+  `integrations errors`.
+
+Write:
+
+- `integrations add` (payload-file), `integrations sync`,
+  `integrations test-connection`, `integrations update`,
+  `integrations delete` (two-step confirm).
+- `integrations revoke <id>` (two-step confirm; Tier A on prod) — Disconnect a
+  `DatarailsConnector` OAuth data source: `POST /api/v2/data_integrations/<id>/revoke`.
+  The grant is cleared locally first (`oauth_tokens`/`oauth_pending` dropped,
+  `authorised=false`; `oauth` and `oauth_secrets` kept, so reconnecting needs no
+  re-setup), then revoked at the vendor best-effort via `oauth.revoke_url`
+  (`revoke_auth_style`, `revoke_body` describe the request). A failed vendor revoke
+  never undoes the disconnect — read `vendor_revoke` in the output: anything but
+  `revoked` may leave the grant live at the vendor. Legacy vendors are refused.
+- `integrations share users` / `integrations share groups`.
+
+## IT-admin file-sync (`integrations it`)
+
+File-sync connectors only — OneDrive / SharePoint / Egnyte. Output redacts
+secrets by default.
+
+- `integrations it list`, `integrations it get` (`--show-secrets` or `--json` to
+  expose creds).
+- `integrations it add` (payload-file), `integrations it update` (payload-file or
+  `--set-config KEY=VAL`), `integrations it delete` (two-step confirm),
+  `integrations it resync`.
+
+## Entities — company data sources (`entities`, alias `companies`)
+
+The connected accounting systems (QuickBooks Online/Desktop, Xero, NetSuite) —
+i.e. integration data sources at the company level.
+
+- `entities list`, `entities qbd-availability` (discoverability for `create qbd`),
+  `entities netsuite-connections` (discoverability for `create netsuite`).
+- `entities create qbo|xero|qbd|netsuite` — **source system required up-front**
+  (ask "QBO, Xero, QBD, or NetSuite?"). `qbo`/`xero` require `--credential <s>`
+  (OAuth token) plus optional `--group --first --ignore-credential-conflict`;
+  `qbd` requires `--company-files <list>`; `netsuite` requires `--connection <id>`.
+- `entities rename <doc_ids> --alias <s>` (CSV doc ids),
+  `entities rename-group <doc_ids> --group <s>` (move into a group).
+- `entities delete <doc_ids>` — two-step confirm.
+- `entities mark-completed <doc_id>` — IT-support override for a stuck state.
+
+## Customer-facing docs (KB)
+
+Help Center → **"Integrations"** category. Find current articles with
+`dr kb search "integration <system>"` (or browse `dr kb categories` /
+`dr kb sections`). Cite the article; don't paraphrase from memory.

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

@@ -0,0 +1,168 @@
+# Lookups (LUTs)
+
+Command group `lut` (alias `lookups`). A LUT enriches a target table by joining
+on a key and pulling in one or more value columns. The data feeding a lookup
+comes from **one of two sources** — a filebox document, or another table — see
+[Two source types](#two-source-types) below.
+
+`lut list` is by template — pass `--table <template_id>` (get it from
+`templates list`).
+
+## Read
+
+- `lut list --table <tid>` — LUTs configured on a template.
+- `lut list-by-doc <doc_id>` — LUTs sourced from a given filebox document.
+- `lut data <doc_id> <lut_id>` — a LUT's mapped key→value data.
+- `lut unmapped [--all] [--limit N]` — **filebox** LUT documents with unmapped
+  items (a.k.a. `lut_misses`). Table lookups have `document: null` and never
+  appear here — they don't surface misses (see [Choosing a type](#choosing-a-type)).
+
+## Create
+
+- `lut create --table <tid> --payload-file <p>` — **filebox-sourced** LUT
+  (`document: <id>`), body supplied as JSON. See [Two source types](#two-source-types)
+  for the positional-keys / name-override behavior.
+- `lut create-table-lookup --table <tid> --source-table <sid> --keys A,B --fields C,D`
+  — **table-sourced** LUT: a lookup on `--table` fed by columns from another
+  table (`--source-table`). Flag-based, no payload file. `--keys` and `--fields`
+  are comma-separated **source** column names; `--key-len` defaults to the count
+  of `--keys`; optional `--name`, `--order` (default 0), `--rescan-option`
+  (default `LATEST_IN_DIM`), `--no-check-misses`, `--no-validate-loops`,
+  `--json`. The source table must differ from the target.
+
+## Update / delete / order
+
+- `lut update-table-lookup <id> --table <tid> [--source-table <sid>] [--keys A,B]
+  [--fields C,D] [--key-len <n>] [--name <n>] [--order <n>] [--rescan-option <opt>]
+  [--check-misses true|false] [--no-validate-loops] [--json]` — **table lookups.**
+  Overlays only the flags you pass onto the lookup's current config and PUTs the
+  full shape. `--table` (the target) is required to locate the LUT — there is no
+  per-id fetch. Prefer this over `lut update` for table lookups.
+- `lut update <id> --payload-file <p>` — generic update (either source type). For
+  a **table** lookup the server re-runs full validation on every PUT, so a raw
+  payload MUST re-send `source_template_id` + non-empty `keys`/`fields` even to
+  change one field (no partial update) — which is why `update-table-lookup`
+  exists. Use this raw path for filebox lookups.
+- `lut delete <id>` — two-step confirm (works for either source type).
+- `lut reorder [--ids a,b,c | --payload-file <p>]` — reorder LUTs under a template.
+
+## Mapping data / export
+
+- `lut save-mappings <doc_id> --file <path>` — the FE "Save" action, and the way
+  to resolve unmapped items / seed a lookup from the CLI.
+
+  `--file` holds a **bare JSON array** of sheet objects. Not an object — the
+  endpoint deserializes with `many=True`, so a top-level object comes back as
+  `400 {"non_field_errors":["Expected a list of items but got type \"dict\"."]}`.
+
+  ```json
+  [
+    {
+      "sheet_name": "USER to DR Mapping",
+      "document_version_id": 9001,
+      "create": [
+        [
+          {"column_header": "USER_TO_DR_ACC_KEY", "value": "4000"},
+          {"column_header": "Account Group L2", "value": "Revenue"}
+        ]
+      ]
+    }
+  ]
+  ```
+
+  - A **row** is a list of `{column_header, value}` cells — key columns first,
+    in `header` order. A flat array of values is rejected.
+  - `document_version_id` must be the document's **latest** version
+    (`filebox versions <doc_id>`), else the server answers
+    `"DocumentVersion is not the latest"`.
+  - **`create` only.** `update` and `delete` are refused: the server addresses
+    their rows by a position it computes wrongly — `delete_rows` deletes by
+    indexes it never adjusts after each removal, and `update_rows` reads a
+    sheet-ordered, matched-only index map by the caller's array position — so
+    either can write to or remove the wrong rows and still report success.
+    Neither depends on key length. Edit or remove existing rows in the web app.
+  - **Leave `header` out.** The CLI reads the sheet's own row 1 and sends that.
+    A `header` that differs from row 1 makes the server *rename* the columns in
+    the customer's file, so a supplied one is checked against the sheet and
+    refused on mismatch; `--allow-header-rename` is the deliberate override.
+  - A bucket may also be an object keyed by row (the shape the web app holds in
+    memory); the CLI flattens it. Omitted buckets default to `[]`.
+  - Every cell's `column_header` must appear in the sheet's header. Everything
+    is validated locally first, so a malformed body fails naming the sheet index
+    and field instead of costing a round-trip.
+  - **The write is async and the command waits for it.** The server runs the
+    save as a Celery task and answers `409 {task_id, cache_key}` after 0.5s —
+    which any payload that actually writes a row will hit, since the task
+    reopens the workbook and recalculates it through the Xl service. The CLI
+    re-POSTs to `?cache_key=…` until the task reports a result, then prints the
+    server's own message (`Mapping has been saved. Version number is <id>`).
+    `--poll-interval <s>` and `--timeout <s>` (default 2 / 300) tune that. On
+    timeout the write is still running server-side — re-running the same
+    command rejoins it rather than starting a second one.
+  - **Unrecognized sheet keys are passed through, not rejected** (so a payload
+    captured from the browser keeps `key_len` etc.). A misspelled `"crate"`
+    therefore saves nothing and still returns success — the command's
+    `N created, N updated, N deleted` summary is how you catch it.
+
+  Assembling a payload from unmapped items, end to end:
+
+  ```bash
+  dr lut unmapped --server US                     # which documents have misses
+  dr lut list-by-doc <doc_id> --server US --json  # lut id, sheet_name, keys, fields
+  dr filebox versions <doc_id> --server US        # latest version id
+  ```
+
+  Each miss in `lut_misses` becomes one `create` row: the key cell first, then
+  one cell per field. Column names come from `list-by-doc`'s `keys` + `fields`;
+  don't put them in a `header` field — the CLI reads the sheet's own.
+
+- `lut export <doc_id> --output <path>` — downloads the document's LUT data as
+  `.xlsx`.
+
+## Choosing a type
+
+Both types join a **source** to the target table on shared key field(s) — like
+`VLOOKUP` but with support for multiple keys — and pull extra columns in. Pick
+by where the source lives and what you need:
+
+| If… | Use | Command |
+|---|---|---|
+| Source is an uploaded mapping **file** (e.g. a simple Chart of Accounts) | Filebox lookup | `lut create` |
+| Source is **another table** already in the environment (e.g. a large dataset) | Table lookup | `lut create-table-lookup` |
+| You need **unmapped-item detection** (misses surfaced) | Filebox lookup only | `lut create` |
+| The key is **not** in the source file's leading columns | Table lookup (no position constraint) | `lut create-table-lookup` |
+
+Deciding factors:
+
+- **Unmapped items.** A **filebox lookup surfaces unmapped items** — raw-data
+  keys with no match in the source — via `dr lut unmapped`, the Home Page Data
+  Status, and `lut_misses`. A **table lookup does NOT surface unmapped items**:
+  table-sourced lookups have `document: null`, so they never appear in
+  `dr lut unmapped`; monitor misses via a dashboard instead. If data-integrity
+  alerting matters, prefer a filebox lookup.
+- **Key column position.** A filebox lookup resolves keys **positionally** — the
+  key field(s) must be the **leading column(s)** of the source file. A table
+  lookup honors **named** keys/fields, so the key can be any column.
+
+## The two shapes on the wire
+
+- **Filebox-sourced** (`document: <id>`, `source_template_id` omitted) — created
+  by `lut create` from a `--payload-file`. The engine **resolves keys
+  positionally** from the source file's header row (first `key_len` columns →
+  keys, rest → fields; the JSON `keys`/`fields` arrays are ignored), and
+  **overrides the requested `name`** with the source filebox's name. After
+  `create`, the CLI re-fetches and warns on a shape/name mismatch; the fix is to
+  reshape/rename the source file, then `lut update`.
+- **Table-sourced** (`source_template_id: <sid>`, `document: null`) — created by
+  `lut create-table-lookup`. The write field is `source_template_id` (NOT the
+  read-only `source_template`); the named `--keys`/`--fields` are honored
+  verbatim (no positional resolution). The source table must differ from the
+  target. The endpoint returns 202 (data materializes asynchronously) — rerun
+  `lut list --table <tid>` to confirm the row; joined values populate only after
+  the target table is rescanned.
+
+## Customer-facing docs (KB)
+
+Help Center → **"Getting Data into Datarails"** → Lookups. Find current articles
+with `dr kb search "lookup"` (or browse `dr kb categories` / `dr kb sections`).
+Cite the article; don't paraphrase from memory.