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

package/dist/skills/dr-cli/reference/spend-control.md

@@ -0,0 +1,206 @@
+# Spend Control
+
+Datarails Spend Control is its own FinanceOS application (vendor contracts, spend
+tracking, alerts), not part of Planning.
+
+- `spend-control billing-frequencies list` — catalog of billing-frequency UUIDs.
+- `spend-control files upload <paths…> [--is-additional] [--json]` — upload
+  documents and get back `file_id`s **without running AI extraction**. Use this
+  when the contract field values are already known: pass the ids as `file_ids` in
+  a `contracts bulk-create` draft or `contracts update` body. One request per file
+  (the endpoint takes one file), and deliberately **no retry** — a re-sent upload
+  creates a second blob and a second record that nothing references and the
+  operator cannot see. On partial failure it exits non-zero naming the failed
+  paths; re-run with only those. `--json` emits `{ uploaded, failed }` so a caller
+  gets the failed paths machine-readably rather than from stderr.
+- `spend-control files list <contract_id> [--all] [--json]` — the files attached
+  to a contract. The table omits the download URL on purpose: every read enriches
+  `file_path` into a presigned URL that grants access on its own for ~1h, so a
+  listing would print one credential per row. `--json` does include them.
+- `spend-control files get <file_id> [--json]` — one file's metadata plus its
+  presigned download URL. The endpoint is POST and named `download`, but it
+  returns **metadata, not bytes** — fetch the URL yourself (e.g. `curl -o`) to get
+  the content.
+- `spend-control files delete <file_ids…> [--from <file>]` — two-step,
+  **permanent**: removes the blob and the record. The service does **not** check
+  whether a contract still references the file, so deleting one that a contract's
+  `file_ids` points at leaves a dangling reference. Tier A on production tenants.
+- `spend-control contracts list [--all] [--json] [filters…]` — **start here.**
+  Every mutation below needs a contract UUID and this is the only way to get one.
+  Filters: `--search <vendor>` (case-insensitive), `--status`, `--payment-terms`,
+  `--payment-method`, `--vendor-id`, `--owner-id`, `--currency`, `--external-id`,
+  `--is-archived <true|false>`, `--start-date-from`, `--end-date-to`,
+  `--order-by`, `--page`, `--size`. Comma-separate multi-value filters
+  (`--status active,expired`). To sort descending write `--order-by value:desc` —
+  **not** `--order-by -value`, which the argument parser reads as the `-v` flag
+  and answers with the version string instead of a listing. (`--order-by=-value`,
+  with the `=`, also works.) Statuses are **lowercase**: `active`,
+  `pending_renewal`, `expired`, `upcoming`, `cancelled`.
+  The server caps `--size` at 100 — use `--all` to walk every page (progress goes
+  to stderr, so `--json --all | jq` stays clean). Archived contracts are included
+  by default and flagged in the ARCHIVED column; pass `--is-archived false` to
+  exclude them. `--currency` filters on the contract's own currency;
+  `--convert-to` converts the monetary fields server-side and filters nothing.
+- `spend-control contracts get <id> [--convert-to <code>] [--json]` — one contract.
+- `spend-control contracts archive <ids…> [--from <file>]` — two-step; sets
+  `is_archived=true` on each id. Reversible with `restore`. Takes ids space- or
+  comma-separated, or one per line via `--from` (`#` comments and blanks are
+  skipped, so a `list` capture can be hand-edited). Each id is attempted even if
+  an earlier one fails; the summary prints `unprocessed ids:` for a retry, and the
+  command exits non-zero if any failed.
+- `spend-control contracts restore <ids…> [--from <file>]` — inverse of `archive`.
+- `spend-control contracts delete <ids…> [--from <file>]` — two-step, **permanent**:
+  drops the contract, its files in blob storage, and its alerts. No undo, no
+  tombstone. Prefer `archive` for cleanup you might want to reverse. On a
+  production tenant this needs the interactive word confirmation on top of the
+  token (Tier A), so it can't be completed headlessly there.
+- `spend-control contracts extract-from-files <files…> [--default key=value]…
+  [-o <path>] [--poll-interval <s>] [--poll-timeout <s>] [--no-async] [--retry <n>]`
+  — PDF/DOCX/PNG/JPG → AI-extracted draft JSON. 25 MB per file; magic bytes are
+  checked locally before anything uploads. Returned file_ids don't expire, so
+  editing the draft over hours/days before create is safe.
+  **Async by default:** one upload request per file against the v2 endpoint, then
+  extraction is polled. Nothing is capped at 10 files and no request waits on AI,
+  so the gateway timeouts the synchronous path produced are structurally absent.
+  `--poll-interval` (default 2s) and `--poll-timeout` (default 10m) tune the wait;
+  the whole-command `--timeout` defaults to `--poll-timeout` plus 15s per file for
+  the uploads, so raising `--poll-timeout` actually takes effect instead of being
+  capped by the command deadline.
+  Whenever a file does not finish, the draft still carries whatever did, and the
+  reason is specific: `--poll-timeout` expired, the command budget expired, or the
+  status call itself failed. Each names the `contract_file_id` and says to re-check
+  rather than re-upload — a re-upload pays for the extraction twice.
+  **Partial success (both paths):** a file that fails does not discard the ones
+  that succeeded. The draft is written with what worked, a per-file table goes to
+  stderr, and the command exits non-zero naming the failures. Re-run with ONLY
+  those paths and merge the drafts — re-sending a file that already succeeded
+  uploads and re-extracts it again (fresh AI cost, orphaned file_id). A file whose
+  AI step FAILED was still uploaded, so it must not be re-uploaded either.
+  **`--no-async`** falls back to the legacy synchronous endpoint: 10 files per
+  request with AI running inside the request. Only on that path does `--retry <n>`
+  (default 0) apply, re-attempting a failed chunk **only where re-sending is
+  safe** — 429, 500/503, network errors — with exponential backoff (1s, 2s, 4s,
+  capped at 8s). **Not** retried there: 4xx, because the server rejected the files
+  on their merits; and 502/504/524, because a gateway timeout means the upstream is
+  probably still extracting, so re-sending would orphan a paid extraction (those
+  report as `upstream may still be processing`). A client-side timeout is never
+  retried on either path and stops the run, with remaining files reported as
+  `not attempted`.
+- `spend-control contracts bulk-create --from <draft.json> [--owner <email>]
+  [--billing-frequency <name>] [--allow-cross-tenant] [--dry-run]
+  [--timeout <seconds>]` — two-step.
+  The draft has `_meta` (read `review_required` / `optional_unfilled` for what AI
+  couldn't extract), `defaults`, `contracts[]`. **Tenant safety:** refuses if
+  `_meta.tenant_server` ≠ `--server` unless `--allow-cross-tenant`. Per-batch
+  all-or-nothing (max 10); on mid-batch failure earlier batches are NOT rolled
+  back — created IDs land in a `<draft>.created.txt` sidecar. Vendor via
+  `vendor_name` (get-or-create) **or** `vendor_id`, never both. Extract and
+  create are separate commands by design (no one-shot).
+  **Timeouts and duplicates:** the whole command runs under one budget, now
+  30s + 20s per 10-contract batch (37 contracts → 4 batches → 110s); override
+  with `--timeout <seconds>`. When a batch fails the CLI always reports how many
+  earlier batches committed — including zero — and whether the failure was a
+  client-side timeout. A timeout says **nothing** about whether the server
+  committed that batch, so verify with `contracts list --search <vendor>` before
+  re-running; re-sending the draft unchanged duplicates every row that already
+  exists.
+- `spend-control contracts update <id> --from <patch.json>` — partial PATCH.
+
+## Vendors (the App Store)
+
+A vendor is the App Store unit: `is_visible` decides whether an app is listed
+to the org, categories structure the catalog, owners is who an access request
+routes to. `contracts bulk-create` creates vendors implicitly by `vendor_name`
+(`get_or_create`), so these commands are for the state *around* that.
+
+- `spend-control vendors list [--name <text>] [--is-visible <bool>] [--page <n>]
+  [--size <n>] [--all] [--json]` — `GET /vendors/`. `--name` is a
+  case-insensitive partial match (`name__ilike`). `--all` walks every page in
+  100-row chunks, terminating on a short page.
+- `spend-control vendors app-store [--category <name>] [same list flags]` — the
+  App Store projection. **Not** the same as `list --is-visible true`: the
+  service applies its own rules on top of the filter, so use this one when the
+  question is "what does the org actually see".
+- `spend-control vendors with-contracts [--target-date <YYYY-MM-DD>]
+  [--without-invoices] [--category <name>] [--page <n>] [--size <n>] [--all]
+  [--json]` — adds `total_value` + `currency`
+  aggregated over the vendor's contracts for the month containing
+  `--target-date` (default today). `--without-invoices` is the "vendors we have
+  contracts for but no invoices from" cut.
+- `spend-control vendors duplicates` — vendors with more than one non-archived
+  contract; the signal behind the duplicate-contract alert.
+- `spend-control vendors categories` — the vendor category catalog (`value` +
+  display name). Distinct from contract categories.
+- `spend-control vendors owners <vendor_id>` — the owner ids behind a vendor.
+  Read-only: owners are derived from the vendor's contracts, so to change one,
+  patch the contract.
+- `spend-control vendors create <name>` — two-step, but `get_or_create`: a
+  repeat run returns the existing vendor rather than duplicating it. Name is
+  2–255 characters, checked locally before the request.
+- `spend-control vendors set-visibility <ids…> --visible <true|false>
+  [--from <file>]` — two-step, **admin-only** (a non-admin session gets a 403).
+  Unlike `contracts archive`, this endpoint is genuinely bulk: one request
+  carries every id, so there is no partial-application state — it applies to
+  all the ids or to none.
+  The command reads current visibility first and sends **only the vendors that
+  actually change**, because a uniform write over a mixed set is not reversible
+  (`[visible, hidden] → all true → all false` leaves both hidden). The plan step
+  prints a per-vendor `before → after` plus the exact `to undo:` command, which
+  restores a mixed set correctly. Vendors already at the target are reported and
+  skipped; an id matching no vendor is an error, not a silent no-op. Resolving
+  prior state costs one read-only page walk of the vendor list (there is no
+  `GET /vendors/{id}`).
+
+Icon URLs are presigned (~1h bearer credentials), so the tables print icon
+presence only; `--json` includes the URL. Same rule as `files list`.
+
+Not wrapped, deliberately: `GET /vendors/search` (deprecated server-side — use
+`list --name`) and `POST /vendors/request-access` (an end-user action that
+emails the vendor owner, not an operator one).
+
+## Alerts and renewal alert settings
+
+Alerts are derived notifications (renewal, duplication, upcoming/already
+started, already ended) generated from contract data by the `handle_alerts`
+background task. The settings document is org-wide and decides how far ahead of
+an end date they fire and who gets emailed.
+
+- `spend-control alerts list [--status active|dismissed] [--all] [--json]` —
+  **the service defaults `status` to `active`**, so a bare `list` silently hides
+  dismissed alerts. The command prints a note to stderr saying so; to see the
+  full set, run it twice. Path is `/alerts` with **no** trailing slash, unlike
+  `/contracts/` and `/vendors/`.
+- `spend-control alerts dismiss <ids…> [--from <file>]` — two-step, one POST per
+  id (no batch route). **One-way through the API**: the service binds no
+  un-dismiss route, so the CLI cannot restore a dismissed alert. The background
+  job may re-raise it on its own schedule. Every id is attempted; the summary
+  prints `unprocessed ids:` and the command exits non-zero if any failed.
+- `spend-control alerts settings [--json]` — the org's renewal alert settings. A
+  null result means the org has never saved them, which is a legitimate state:
+  there is no create route, so they must be saved once in the UI first.
+- `spend-control alerts set-settings [--days-before-end-date <n>]
+  [--send-to-contract-owner <bool>] [--ignore-cancellation-policy <bool>]
+  [--email-notifications <bool>] [--user-ids <a,b,c>]` — two-step. The route is
+  a `PUT` over a schema where **every field is required**, so the command reads
+  the current document and merges rather than exposing a bare PUT; flags you do
+  not pass keep their current values instead of being blanked. The plan step
+  prints `before → after` for each changed field, and a no-op update
+  short-circuits before minting a token. `--user-ids ""` (explicit empty string)
+  clears the extra-recipient list; omitting the flag leaves it alone.
+
+## Contract categories and change history
+
+- `spend-control contracts categories [--unused] [--json]` — the contract
+  category catalog (`value` + display name). `--unused` maps to
+  `contract_is_null=true`: categories no contract currently uses. Distinct from
+  `vendors categories`.
+- `spend-control contracts change-history <contract_id> [--json]` — **value
+  changes only**. The history row carries `previous_amount` / `new_amount`, so
+  edits to dates, owner, or category leave no trace here; an empty result means
+  "never repriced", not "no such contract".
+
+## Customer-facing docs (KB)
+
+Help Center → **"Spend Control"** category. Find current articles with
+`dr kb search "spend control contract"` (or browse `dr kb categories` /
+`dr kb sections`). Cite the article; don't paraphrase from memory.

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

@@ -0,0 +1,163 @@
+# Templates, fields, data-models, dynamic ranges, scans
+
+Templates are the customer's data sources ("tables"). Each has a numeric
+**template ID** you need on most downstream commands. `templates get <id>` shows
+field names + **field IDs** (needed for functions, ranges, set-field-type, calc
+models, metrics).
+
+## "System name" = `alias`
+
+The Datarails UI and Help Center call a table's or field's stable machine
+identifier its **system name**. dr-cli and the monolith API both spell the same
+value `alias`. They are the same thing — if an operator asks you to read or set
+a **system name** on a table or a field, use the `alias` commands below.
+
+It is the value that:
+
+- `DR.GET(value,"{department}")` resolves against — `{braces}` in an Excel
+  function mean "look this up by system name", vs `[brackets]` for the display
+  field name.
+- template-library import matches on when mapping a template's tables and
+  fields onto the tenant's own (a table or field that already has one cannot be
+  reassigned).
+- planning defaults key off (e.g. giving a `Scenario_version` field the system
+  name `scenario_cycle` makes default-filter logic recognise it).
+
+Unrelated uses of the word "alias" elsewhere in this CLI — command aliases
+(`orgs` → `organizations`), `entities rename --alias` (an entity's *display*
+name), and filebox alias-matching on push — are **not** system names.
+
+## Read
+
+- `templates list` — `--my-org-only` filters to the operator org's own tables
+  (the source the FE target-table pickers use).
+- `templates get <id>` — fields, field IDs, field types. **System names are not
+  in the text table** — add `--json` to see the table's `alias` and each
+  `fields[].alias`. That is the read path for a system name, so use
+  it before assigning one (a table or field that already has a system name
+  cannot be remapped by template-library import).
+- `templates sample <id> --rows 10` — newest rows, latest document version only
+  (there is no all-versions switch on this route). `--rows` up to 1000 per call;
+  `--offset N` pages deeper; `--fields "A,B,C"` projects columns server-side
+  (names or field ids); the same filter flags as `aggregate` (below) narrow the
+  rows; `--json` for piping (full envelope: `data`, `metadata.pagination`).
+- `templates distinct <id> --field Region` — distinct values of a field, by
+  **name or field id** (`--field 47960` works). A Date field returns
+  epoch-seconds strings (`"1796083200"`); pass them straight back into a filter.
+- `templates aggregate <id> --group-by Region --metric Amount:SUM` — server-side
+  aggregate, no raw rows. Every field token (`--group-by`, the FIELD of
+  `--metric`, filter names) is a field **name or id**; an unknown one fails
+  before any call, listing the valid `"name" (id)` pairs. A field may be
+  aggregated once per call, and not both grouped and aggregated.
+- `data-models list` / `data-models get` — read-only.
+
+### Filters on `aggregate` / `sample`
+
+- `--filter "NAME=V1,V2"` (include) / `--exclude "NAME=V1,V2"` — list
+  filters, repeatable.
+- `--filter-gte "NAME=V"` / `--filter-lte "NAME=V"` /
+  `--filter-range "NAME=FROM..TO"` (inclusive) — ordered filters, repeatable.
+- **Date fields:** a value may be a calendar date (`2026-12-01`, `2026-12`,
+  `2026-12-01T00:00:00Z`, `12/01/2026`) or Unix epoch **seconds**
+  (`1796083200`, the form `distinct` prints). Calendar dates are read as UTC
+  midnight (a month alone is its first day) and converted before the call;
+  epochs pass through unchanged. Example:
+  `--filter-range "Period=2026-01-01..2026-12-01"`,
+  `--filter "Period=2026-12"`. (The server matches a Date only through an
+  ordered/`equals` condition; the CLI picks that form for you, so never
+  hand-build an advanced filter for a date.) A calendar date on a non-Date
+  field is refused client-side.
+- Aggregate result rows key a Date dimension by epoch seconds (a number);
+  `distinct` returns the same values as strings.
+
+### `aggregate` output shape
+
+- Text: one table row per group, `(N rows)` footer. `--totals` adds a
+  `Totals: <metric>=<value> …` line (the engine grand total).
+- `--json`: a bare **array of group rows only** — no grand-total row and no
+  `{"col_keys":…,"row_keys":…}` trailer, so `for r in rows: r["Period"]` is
+  safe. With `--totals` the shape is `{"rows": [...], "totals": {...}}`
+  (`totals` is `null` when the engine sent none). Totals are exact for
+  SUM/COUNT/MIN/MAX, not for AVG or COUNT_UNIQUE.
+
+## Write
+
+- `templates create`.
+- `templates set-alias <id> --alias <s>` — set a **table's system name**; pass
+  `--alias ""` to clear. (The flag is spelled `--alias`; there is no
+  `--system-name` spelling.)
+- `templates set-field-alias <field_id> --alias <s>` — set a **field's system
+  name** (field id is `fields[].id` from `templates get`); `--alias ""` clears.
+- `templates set-field-type <field_id> --type <Text|Float|Date|Integer>` —
+  **two-step confirm** (it can break widgets / dynamic ranges, since the server
+  rescans latest versions when the type change requires it). Notes:
+  - Allowed types: `Text`, `Float`, `Date`, `Integer`.
+  - Bulk: `--file <path>` with a JSON array `[{field_id, type}, …]`. One failed
+    field doesn't abort the rest; failures are summarized as `K of N failed` and
+    the exit code reflects partial failure.
+  - The CLI preserves the field's existing `is_hidden` when flipping type
+    (omitting it would silently un-hide hidden fields).
+  - `--enforce` bypasses the server's numeric-downgrade guard (which otherwise
+    rejects Float/Integer → non-numeric when widgets/Excel reference the field).
+    Off by default.
+  - A no-op invocation (every requested type already matches) exits success
+    without issuing a token.
+
+## Dynamic ranges (nested under a template)
+
+Always pass `--table <template_id>` (get it from `templates list` first) —
+except on `update`, which resolves the range's own table automatically.
+
+- `dynamic-ranges list --table <tid>`, `dynamic-ranges get <range_id> --table <tid>`.
+  `get --json` includes the range's current `filters` and rich `fields`.
+- `dynamic-ranges data <range_id> --table <tid> --json` — returns a flat
+  list-of-lists; each inner list is one row, values ordered to match the range's
+  fields. Drop `--json` for a human table.
+- `dynamic-ranges create --table <tid> --name <s> --fields <csv>` — plus
+  optional filters (below).
+- `dynamic-ranges update <range_id>` — read-modify-write; pass only what
+  changes (`--name`, `--fields`, filter flags). Omitted parts stay untouched.
+- `dynamic-ranges delete` (two-step confirm).
+
+### Filters on create/update
+
+- `--filter "FIELD_ID=V1,V2"` (include) / `--exclude "FIELD_ID=V1,V2"`
+  (exclude) — repeatable list filters. Keys are numeric **field IDs** from
+  `templates get <tid>`, not field names. Values are sent as strings; the
+  server coerces them to the field's type. A filter's field does **not**
+  have to be in `--fields`.
+- `--filters-json '<array>'` — raw wire objects
+  `{field, values, is_excluded?, override_global_filter?}` for advanced
+  (`{"type":"advanced","val":[{"condition":"contains","value":"x"}]}`) and
+  date (`{"datetype":"range","val":{"fromdate":<epoch>,"todate":<epoch>}}`)
+  filters. Advanced conditions: `bw ew contains dn_contains equals gt gte
+  lt lte in range total_range "is null"` (`dn_*` = negated).
+- **Update replaces, never merges:** any filter flag on `update` REPLACES
+  all existing filters on the range. To add one filter, `get --json` the
+  current filters first and resend the full set. `--clear-filters` removes
+  them all.
+- Filter field ids are validated against the table before sending (the
+  server doesn't check this; a wrong id would silently bind the filter to
+  another table's field).
+
+## Scans / rescan / data flow
+
+- `scans status <template_id>` — current scan state.
+- `rescan table <template_id>` — trigger a **full historical rescan** (re-executes
+  every calculated field against every document version ever uploaded, not just the
+  latest), then poll `scans status`. **Two-step confirm (Tier B):** run once to see
+  the blast radius (document + version counts) and get a token, then re-run with
+  `--confirm-token` — token-only, no word gate even on prod (a rescan re-derives
+  data, it doesn't delete it). To pick up a datamapper change on the live template
+  **without** touching history, use `datamappers update <id> --rescan latest`
+  instead (mirrors the UI "Publish and scan"); a full rescan will re-run pre-existing
+  calc fields against old rows, so a latent divide-by-null there fails the whole
+  scan. Refuses `UsageStats` on every tenant (system data, not customer-owned).
+- `dataflow get` — the dependency graph: inputs → mappers → LUTs → table →
+  outputs.
+
+## Customer-facing docs (KB)
+
+Help Center → **"Getting Data into Datarails"** → Data Management. Find current articles with `dr kb search "tables data management"` (or
+browse `dr kb categories` / `dr kb sections`). Cite the article; don't
+paraphrase from memory.

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

@@ -0,0 +1,137 @@
+# Workflows v2 (`workflow` + `mec workflow`) and collection processes
+
+`workflow` (non-MEC close, budget, forecast, etc.) and `mec workflow` (Month-End
+Close) share one command surface. Each leaf probes a feature flag before any
+other call: `workflow` checks `enable_workflow_v2` (and redirects to
+`mec workflow` if off); `mec workflow` checks `month_end_close`.
+
+The only real differences are the **type enum** and a few MEC-only reads (below);
+everything else is identical. Confirm tokens are scoped per family
+(`workflow-*` vs `mec-workflow-*`).
+
+## Read
+
+- `list [--archived]` (`workflow` also has `--planning`), `get <id>`.
+- `process list [--template <id>] [--active|--inactive]`, `process get <id>`.
+- `step get <process-id> <step-id>`.
+- `task list <pid> <sid>`, `task get <pid> <sid> <tid>`.
+- `member list <template-id>`, `member check <template-id> --emails <e1,e2>`
+  (read-only pre-share audit — per-email missing-doc diagnostics).
+- `group list <template-id>`.
+- **MEC-only:** `mec workflow periods` (active close periods);
+  `mec workflow accounts tasks --date-tag <unix> --account-name <s>
+  --account-group <s> [--entity]` (all three required — tasks for one account in
+  a period); `mec workflow accounts task-statuses --date-tag <unix> [--entity]`
+  (overview across all accounts in a period).
+
+## Write (mutations are two-step confirm)
+
+- `create --file <path>` — new template starts inactive.
+  - `workflow` type enum: `Financial Reporting | Budget | Forecast | Other`
+    (`Month End Close` is rejected with a redirect to `mec workflow`).
+  - `mec workflow` requires `type: "Month End Close"` (the four non-MEC types are
+    rejected with a redirect to `workflow`).
+- `update <id> --file <path>` (same type check).
+- `activate <id> [--yes-share-data]` — **fires async emails** to assignees on
+  every step with `notify_automatically=true`; the plan-step previews the
+  recipients and refuses without `--yes-share-data` when any step has tasks.
+- `deactivate <id>`; `archive <id>` / `restore <id>` / `delete <id>` (`delete` is
+  an alias for archive — there is no v2 hard-delete).
+- `clone <id> --date-tag <unix> [--copy-from <pid>] [--name <text>]
+  [--start-time <unix>] [--tag <id>=<value>] --yes-share-data` — carries
+  existing members forward (share flag mandatory).
+  - `--date-tag` is **required**; the endpoint 500s without a tag array.
+  - `--copy-from` defaults to the template's newest instance by `date_tag_value`.
+    Passing nothing does **not** mean "empty instance" — clone always copies.
+    If several instances exist and none carries a readable DATE tag, there is no
+    "newest" to pick and the command fails asking for an explicit `--copy-from`.
+    The plan step's confirm command always pins the resolved id, so a newer
+    instance appearing between plan and commit cannot change the source.
+  - Omit `--name` and the server derives the period label (e.g.
+    `September 2026`). Names must be unique per template; a collision is
+    rejected client-side with the taken names listed.
+  - `--start-time` is the only way to set the new instance's start time — there
+    is no `process update` verb for it.
+  - `--tag <id>=<value>` is repeatable, for templates that carry a non-date
+    dimension tag (budget cycle / scenario) alongside the period. Tag ids come
+    from `config.tags_config[].id` in `workflow get <id> --json`.
+  - Under the hood this is the one template route with **no `v2`** segment
+    (`POST /api/processes/process_templates/<id>/processes`); the server routes
+    both workflow versions through it.
+- `process delete <id>` — cascades all tasks.
+- `step create <pid> --file` / `step update` / `step delete` / `step reorder
+  <tid> --file <path> | --order id:n,id:n,…`.
+- `task add-file <pid> <sid> --file <path>` (bulk array), `task add-checklist …`
+  (name + description + assignee), `task update --type file|non-file --file`,
+  `task update-one <pid> <sid> <tid> --file` (single checklist row),
+  `task delete --ids 1,2,3` (token bound to the id set + step id; always sends an
+  array body), `task notify --type file|non-file --file` (**fires async email** —
+  200 means queued, not delivered; the plan lists every recipient),
+  `task approve --file` / `task reject --file`, `task sign-off --type
+  file|non-file --ids 1,2,3 --is-sign-off true|false` (true = complete, false =
+  re-open). MEC tasks additionally carry `reconciliation_tags`,
+  `assignee_close_date_condition`, `reviewer_close_date_condition`.
+  In every task `--file`, `assignee`/`reviewer` are **bare user ids**
+  (`"assignee": 78`) — the server field is an integer PK, so a nested
+  `{"id": 78}` 400s with "A valid integer is required." An `{"id": 78}`
+  object is still accepted as input for convenience and flattened before send.
+- `member add <tid> --file {emails,role} --yes-share-data` (runs a `/users/check`
+  first and shows per-email missing-doc diagnostics in the plan),
+  `member update <tid> <uid> --role ROLE [--yes-share-data]` (share flag required
+  when escalating to the owner role), `member remove <tid> <uid>` (does **not**
+  revoke document permissions), `member grant-bulk --file
+  {emails,entities_ids,role} --yes-share-data` (cascades table permissions for
+  linked LUT templates). `group add|update|remove|grant-bulk` mirror this for
+  permission groups.
+
+## Enums & wire-format gotchas
+
+- **Step type:** `Input | Output | Mapping | Tasks | Text | BudgetInput`.
+- **Step position:** `index` and `y_index` are the step's canvas grid slot, not
+  pixels. `index` is the column and `y_index` the row within that column, both
+  1-based. The columns in use must run 1..N with no gaps: four steps in a line
+  are `index` 1, 2, 3, 4 with `y_index` 1; two parallel steps share an `index`
+  with `y_index` 1 and 2. A step whose `index` falls outside 1..N renders
+  stacked at the canvas origin, and nothing else in the workflow is affected.
+  The CLI rejects 0, and the `step create` / `step update` plan prints a
+  `warning:` line naming every step the change would leave off the grid. To fix
+  a workflow already built that way, run `step update` on each step with a
+  corrected `index` / `y_index`.
+- **Roles:** `WORKFLOW_V2_OWNER_ROLE` / `WORKFLOW_V2_EDITOR_ROLE`.
+- The server field is `recurrency_*` (misspelled) — the CLI rejects
+  `recurrence_*` with a hint.
+- `process_start_time` and `tag.value` are 10-digit **Unix-seconds** epochs;
+  small ints are rejected with a "did you pass day-of-month?" hint.
+
+## Collection processes
+
+CPs are `COLLECTION`-type buckets — a container of N child fileboxes that share
+the same `tags_config` and mapping. Alias `collection-process`.
+
+- `collection-processes list [--scenario S] [--name <substr>] [--owner <email>]`,
+  `collection-processes get <id> [--no-cp-data]`.
+- `collection-processes create --name <n> --dimension-name <d>
+  (--filebox <name>… | --fileboxes @<path>) [--date-sub-type <t> | --no-date]
+  [--scenario S] [--parent <id>] [--config-file <p>] [--template-file <p>]
+  [--use-type <id>] [--split-integration <id>]` — two-step; child fileboxes are
+  provisioned asynchronously, so poll `get <id>` to confirm.
+- `collection-processes set-tag-config <id> --add NAME… --remove NAME…` —
+  two-step; root-document only (existing children keep their snapshots; fileboxes
+  added later via `add-fileboxes` inherit the new config).
+- `collection-processes add-fileboxes <id> (--filebox <name>… | --fileboxes @<path>)
+  --parent-folder <doc-id> [--dimension-name <d>] [--template-file <p>]` — two-step;
+  async.
+- `collection-processes add-folders <id> (--folder <name>… | --folders @<path>)
+  --parent-folder <doc-id> [--dimension-name <d>]` — two-step.
+- `collection-processes calculate <id> [--multiple-dimension-tags]` — two-step;
+  idempotent server-side.
+- There is no `delete` verb — deletion is UI-gated.
+- `--filebox`/`--fileboxes` use the BE wire format: newline-joined names (the
+  `@<path>` file mode reads a newline-separated text file verbatim; no comma
+  translation).
+
+## Customer-facing docs (KB)
+
+Help Center → **"Managing Environment"** → Workflow. Find current articles with `dr kb search "workflow"` (or
+browse `dr kb categories` / `dr kb sections`). Cite the article; don't
+paraphrase from memory.

package/dist/skills/dr-error-enrichment/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: dr-error-enrichment
+description: Router for the integration error-enrichment rules (regex to readable message + resolution steps) that Datarails shows users when a sync fails. Points at four separately callable task skills — dr-error-enrichment-author, -reconcile, -maintain, -improve — and owns the shared reference material (command surface, matching semantics, safety and backup rules, groundcover mining, known-bug triage) that all four read. Use only when the request names the feature without naming a task, or when you need to choose between the four; each task skill triggers on its own work and does not need this one first. Triggers - "work on the error enrichment rules", "the error-enrichment rules", "the readable-errors feature", "which error-enrichment skill do I need", "where do I start with enrichment rules".
+---
+
+# dr-error-enrichment — router
+
+## What this is
+
+When an integration sync fails, Datarails matches the raw vendor error against a
+table of **enrichment rules**. A rule maps a regex to a readable `description`
+plus `resolution_steps`, and collects thumbs up/down feedback. Rules live
+**per server** in each region's own database — there is no global table and no
+cross-server sync, so the same rule can exist on US and be missing (or wrong)
+on UK.
+
+This skill only routes. The actual work lives in four task-specific skills, each
+of which triggers on its own kind of request and is complete on its own — if the
+user already named the task ("approve these drafts", "why does this error show
+no explanation", "compare the servers"), go straight to that skill instead of
+reading this one. Use this page when the request names the feature but not the
+task, or when you are unsure which of the four applies.
+
+## Pick a skill
+
+| Skill | Use when |
+|---|---|
+| `dr-error-enrichment-author` | The user wants one specific rule written or fixed — create a rule for an error, edit a wrong pattern or message, delete a rule |
+| `dr-error-enrichment-reconcile` | Rules have drifted between regions — diff the servers and converge them on a chosen canonical version |
+| `dr-error-enrichment-maintain` | The recurring health pass — approve high-hit drafts one by one, and fix rules collecting thumbs-down |
+| `dr-error-enrichment-improve` | Continuous improvement — mine groundcover for errors no rule matches, split the ones caused by our own bugs off from the ones worth a rule, and propose rules for the rest |
+
+Each one is callable directly; the user does not have to come through this
+skill. If the request names a single rule, go to author; if it names *the
+fleet*, go to reconcile; if it is "are our error messages any good", go to
+maintain, then improve.
+
+Sessions often chain: a maintain pass usually ends in author edits, and an
+author change on one server usually ends in reconcile.
+
+## Shared reference
+
+Read the file that covers what you are about to do — the sub-skills assume it.
+
+- [reference/core.md](reference/core.md) — what rules are, who may call the admin
+  API, the full `dr error-enrichments` command surface, how matching actually
+  works (`re.match` anchoring, rank order, drafts stealing hits), where to get
+  raw error text off a tenant, guard rails, common mistakes.
+- [reference/safety-backup.md](reference/safety-backup.md) — target-server
+  confirmation, the backup-first commands, the surgical revert path, write
+  gating tiers, the `import` policy, and batch-write etiquette.
+- [reference/groundcover.md](reference/groundcover.md) — gcQL for mining
+  unmatched errors, groundcover-env to server mapping, and the hash-not-text
+  caveat on the `No matching rule` marker.
+- [reference/jira-bugs.md](reference/jira-bugs.md) — the integration-bug sweep
+  that decides whether an unmatched error deserves a rule or a bug report: the
+  `System area` field, JQL that returns rows, the four verdicts, and how to file
+  the missing bug.
+
+Confirm-token and prod-gate mechanics themselves live in
+[the `dr-cli` skill's reference/safety.md](../dr-cli/reference/safety.md) — a
+different skill's file, not one of this skill's own `reference/*.md`.
+
+## Non-negotiables
+
+These hold in every sub-skill; the detail is in
+[reference/safety-backup.md](reference/safety-backup.md).
+
+1. **Confirm the target server explicitly** — ask, never infer it from earlier
+   conversation. `US`, `US2`, `UK`, `CA`, `EU`, `DEMO` are all prod.
+2. **Back up every reachable server before the first write** of a session, not
+   just the target — the export is also the diff baseline. One command:
+   `dr error-enrichments export --all-servers --out <dir>`. Tell the user the
+   backup path **and which servers actually backed up** — the sweep skips servers
+   with no stored login and exits non-zero when one fails, and a server with no
+   backup line has no revert path.
+3. **Never reach for `import`** unless the user asked for it by name, and then
+   only after telling them it zeroes `hits` / `thumbs_up` / `thumbs_down` and
+   reassigns every rule id on that server. It is a restore-from-catastrophe
+   tool, not an edit tool.