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

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

@@ -0,0 +1,237 @@
+---
+name: dr-error-enrichment-maintain
+description: Recurring health pass over the integration error-enrichment rules — aggregate hits and feedback across servers, review and approve high-hit draft rules one at a time, and fix the rules users are voting down. Use when the user wants to know whether the readable-error messages are any good, or to clear the backlog of unapproved rules. Triggers - "approve enrichment rules", "high-hit rules with no message", "which rules are getting thumbs down", "review the draft enrichment rules", "error enrichment health check", "are our error messages any good".
+---
+
+# dr-error-enrichment-maintain — maintenance pass
+
+Use for the recurring "are our error messages any good" pass over rules that
+already exist. For errors that have **no** rule at all, use
+`dr-error-enrichment-improve`; for authoring a specific rule, use
+`dr-error-enrichment-author`.
+
+## Read first
+
+- [../dr-error-enrichment/reference/core.md](../dr-error-enrichment/reference/core.md)
+  — what rules are, permissions, the full command surface, how matching works.
+- [../dr-error-enrichment/reference/safety-backup.md](../dr-error-enrichment/reference/safety-backup.md)
+  — target-server confirmation, backup-first, revert path, write gating, batch
+  etiquette. This flow ends in writes to prod; back up before the first one:
+
+  ```bash
+  dr error-enrichments export --all-servers --out /tmp/ee-backup/
+  ```
+
+  With a sweep, `--out` is a **directory** and you get one `<SERVER>.csv` per
+  server, with unreachable servers reported rather than silently skipped. Check
+  the list of files against the servers you are about to write to before the
+  first write.
+
+## 1. Read the fleet — two commands, two different jobs
+
+Run both. They are not alternatives, and mixing up which one answers which
+question is the classic failure of this pass.
+
+```bash
+dr error-enrichments list  --all-servers --json > /tmp/ee-fleet.json   # the data you rank on
+dr error-enrichments stats --all-servers --json                        # the per-server narrative
+```
+
+**`list --all-servers --json` is the source for everything in step 2.** It
+returns whole rules — including `re_pattern`, and `hits` / `thumbs_up` /
+`thumbs_down` for **every** rule, not a top-N slice. It is the only source of the
+roll-up key and of a complete thumbs-down ranking, and it is the same source
+`dr-error-enrichment-reconcile` keys on. With a sweep the JSON is one bucket per
+server (`{server: {rules|skipped|error}}`); read each server's `rules` array and
+carry the server name with it.
+
+**`stats --all-servers --json` is the per-server triage narrative** — what each
+region looks like today, and what you quote in the step-5 report:
+
+| Field | What it gives you |
+|---|---|
+| `needs_attention` | high `hits` **and** `approved: false` — the drafts users are hitting today |
+| `top_hits` | busiest rules; the ones whose wording matters most |
+| `most_helpful` | best `thumbs_up`; your style reference for new wording |
+| `approved_pct` | share of the table that is production-reviewed |
+| per-vendor rollups | which `integration_type` carries the backlog |
+
+Do **not** try to build the fleet roll-up out of those digests. They are compact
+summaries — `id, rank, integration_type, description, classification, approved,
+hits, thumbs_up, thumbs_down` — with **no `re_pattern`**, so there is nothing to
+key on across servers; and there is no thumbs-down digest at all (`most_helpful`
+ranks by `thumbs_up`), so a badly-rated rule that is neither a high-hit draft nor
+a top-hit rule never appears in any of them.
+
+Servers with no stored login are skipped with a warning by both commands — log in
+or say the fleet picture is partial before ranking work across regions. A
+non-zero exit on either means a server errored: the picture is partial, so
+investigate before ranking off it.
+
+## 2. Roll the per-server rules up into one fleet ranking
+
+`stats` answers per server. Ranking off per-server lists directly works the same
+rule three times, or works it last: a rule that is a 400-hit draft on US, 300 on
+UK and 200 on CA is the single highest-value item on the fleet and appears
+mid-list in each of the three reports.
+
+So before touching anything, combine the `list` output from step 1:
+
+1. Key every rule by **`(integration_type, re_pattern)`** — the same key the
+   reconcile flow and `core.md` use. Never by `id`: ids are per-server database
+   ids and collide across regions by coincidence. Never by `description` either:
+   two rules can share one, and a rule reworded on a single region would split
+   into two keys.
+2. Sum `hits`, `thumbs_up`, and `thumbs_down` across servers for each key, and
+   keep the per-server breakdown next to the total — you need `(server, id)` to
+   write, and the split is what tells you whether a rule is approved in one
+   region and a draft in another.
+3. Rank on the **fleet totals**, and note which servers each key is present on.
+   Two rankings come out of this, and the sections below use one each: the
+   `approved: false` keys by fleet `hits` (§3), and every key by fleet
+   `thumbs_down` (§4).
+
+Work the sections below off that fleet ranking, and carry the per-server id list
+for each key so one review produces the write for every region that has the rule.
+A key that is approved on some servers and a draft on others is a
+`dr-error-enrichment-reconcile` job as much as an approval one — the approved
+version is the review baseline.
+
+## 3. Approve the drafts — one at a time
+
+An unapproved rule is a **draft that has not been reviewed for production**, and
+a draft steals the hit while showing the user nothing (core.md, matching rule 4).
+A high-hit draft is therefore an active user-facing gap, not a backlog item. This
+is the highest-value work in this skill.
+
+Work the fleet-ranked drafts from step 2 **highest fleet hits first, one rule per
+cycle**:
+
+1. **Pull the whole rule**: `dr error-enrichments get <id> --server <S>`.
+2. **Show the user** its `re_pattern`, `description`, and `resolution_steps`, with
+   its `hits` and feedback — they are reviewing a production message, so they
+   need to read it, not a summary of it.
+3. **Pull two or three approved siblings** for the same vendor as the style
+   baseline:
+   `dr error-enrichments list --server <S> --integration-type <T> --approved true --json`
+4. **Compare the draft against them**, and say which way it falls:
+   - *Style* — same voice and length as the approved set; no stack traces, no
+     internal identifiers, no raw vendor error codes standing in for a message.
+   - *Content accuracy* — does the `description` actually describe what this
+     pattern matches (not a neighbouring error), and are the `resolution_steps`
+     something the customer or a CSM can genuinely act on?
+5. **Prove the pattern against a real error before approving it.** Style review
+   cannot catch a wrong pattern: `.*TIMEOUT.*` with the description "NetSuite
+   rejected your login credentials" reads perfectly and, once approved, shows
+   that message to every customer hitting a NetSuite timeout. So get a real
+   sample of the error this rule claims to explain — the rule's own `examples`
+   if it has any, otherwise the raw text off a tenant that hit it
+   (`integrations get <id> --json`, or
+   `integrations query-status --query-id <n> --json` for the failing query) — and
+   run it through the server's own matcher together with a neighbouring error
+   that must **not** match:
+
+   ```bash
+   dr error-enrichments test-regex --server <S> --pattern '<the draft pattern>' \
+     --sample '<real error this rule is for>' \
+     --sample '<neighbouring error that must not match>'
+   ```
+
+   The sample must match and the neighbour must not. If it matches the
+   neighbour, the pattern is too broad for the message and the fix is a
+   narrower pattern, not an approval.
+
+   **If no real sample can be obtained, say so and treat approval as blocked** —
+   report the rule as "needs a real sample" and move to the next one. Hits are
+   not evidence: they prove the pattern matched *something*, which is the very
+   thing in question.
+6. **State a verdict and the exact edits you would make** — not "looks fine".
+7. **Get the user's confirmation on that rule**, then either
+   - `dr error-enrichments update <id> --approved true --server <S>` when it is
+     already right, or
+   - fix the wording with `update` first and approve once the text is agreed.
+
+**Never approve a list of drafts in one sweep because their hit counts are high.**
+A hit count says the rule matches something; it says nothing about whether the
+message is correct — and approving a wrong message publishes it to customers.
+
+Once several drafts have each been reviewed, pattern-tested and confirmed
+individually, flipping them together is fine and is what the batch form is for —
+it is the closing step of this protocol, and this skill owns it:
+
+```bash
+dr error-enrichments update 12 19 27 --approved true --server <S>
+```
+
+One plan, one token, one server. The batch token binds the ids **and** the values
+being written, so if the set changes after the plan — you drop a rule the user
+had second thoughts about — re-run the plan step and relay the new plan. Read the
+summary table afterwards rather than the exit code: per-item failures do not stop
+the run. If only one rule survived the review, that line is a single-target
+update — you get the one-line success message and, on failure, the server's own
+error, with no table to read (core.md, *Execution semantics*).
+
+## 4. Fix the disliked rules
+
+Rank on the fleet totals from step 2, by **both** `thumbs_down` and
+`thumbs_down / (thumbs_up + thumbs_down)` — 2 down out of 2 is a worse message
+than 3 down out of 90, and raw counts alone hide it behind the busy rules. The
+ratio ranking is the reason step 2 is built off `list` and not the `stats`
+digests: a 2-down-out-of-2 rule with modest traffic is in no digest at all. A rule
+disliked in one region is usually the same text in the others, so fix it once and
+carry the fix to every server that shares the key.
+
+The two usual causes, and their fixes:
+
+| Cause | Fix |
+|---|---|
+| Pattern matches too broadly, so one message answers several distinct errors | Split into narrower rules, the specific ones ranked above the general one |
+| `resolution_steps` don't actually resolve it | Rewrite the steps with the user; check them against `most_helpful` rules for the same vendor |
+
+Re-validate any pattern change server-side before writing it — including a sample
+that must *not* match, so you can see what the narrowed rule gave up:
+
+```bash
+dr error-enrichments test-regex --server <S> --pattern '.*NEEDLE.*' \
+  --sample '<real error that must match>' --sample '<neighbour that must not>'
+```
+
+Splitting a rule keeps the original's counters only on the original row; a rule
+created from a split starts at zero hits and zero feedback. Say so before you
+propose deleting the parent.
+
+## 5. Report and hand off
+
+Report against the fleet ranking from step 2, then per server: which drafts were
+approved, which rules were reworded or split, and what is still open with the
+reason it was left (usually "needs a real sample" or "user has not agreed the
+wording"). A rule left unapproved because no sample could be found is a result to
+state plainly, not a gap to gloss.
+
+Then close the loop:
+
+- A fix that should reach the other regions is a **reconcile** job — offer
+  `dr-error-enrichment-reconcile` rather than repeating the review per server.
+  Maintenance findings are the most common source of drift worth propagating.
+- Errors with **no rule at all** are out of scope here — hand off to
+  `dr-error-enrichment-improve`, which mines groundcover for unmatched errors and
+  proposes new rules.
+
+## Pitfalls
+
+| Pitfall | Fix |
+|---|---|
+| Bulk-approving `needs_attention` because the hits are high | Hits prove the pattern matches, not that the message is right — review one at a time |
+| Approving a draft without ever testing its pattern | Style review passes a broad pattern with the wrong message — `test-regex` a real sample plus a neighbour that must not match |
+| Approving anyway when no real sample can be found | Approval is blocked, not confirmed — report "needs a real sample" and move on |
+| Ranking work off each server's `stats` list separately | Roll the servers up by `(integration_type, re_pattern)` and rank on fleet totals, or the biggest rule gets worked three times or last |
+| Building the fleet roll-up out of the `stats` digests | They carry no `re_pattern` to key on and no thumbs-down list — roll up from `list --all-servers --json` |
+| Keying the fleet roll-up by `id`, or by `description` | Ids are per-server and cross-server matches are coincidences; descriptions merge distinct rules and split reworded ones |
+| Treating an unapproved rule as harmless until reviewed | It consumes the hit and shows the user nothing; it is the gap, not a placeholder |
+| Judging the draft's wording in isolation | Compare against approved rules for the same `integration_type`; the fleet has a house voice |
+| Ranking thumbs-down by raw count only | Also rank by the down ratio — a 2/2 rule is worse than a 3/90 one |
+| Rewriting a pattern without `test-regex` | The server runs the real `re.match` + newline stripping; local reasoning is not evidence |
+| Deleting a broadly-matching rule to replace it | Deletion drops its feedback history; re-point it with `update` where you can |
+| Recomputing a *single server's* triage narrative from `list --json` | `stats` already returns `needs_attention`, `top_hits`, `most_helpful` per server — but the *fleet* roll-up is the other way round, and must come from `list --all-servers --json` |
+| Fixing a rule on one server and stopping | Per-server drift is the problem the tooling exists to fix — offer the reconcile skill |
+| Reaching for `import` to apply a batch of approvals | It wipes the table and zeroes every counter, destroying the feedback this pass runs on |

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

@@ -0,0 +1,167 @@
+---
+name: dr-error-enrichment-reconcile
+description: Diff the integration error-enrichment rules across Datarails servers and reconcile the drift — collect every server's rules, key them by (integration_type, re_pattern), report what is missing, divergent, or server-only, and propagate the user's chosen version with batch create/update writes (never import). Use when rules have drifted between regions or a rule needs to reach the rest of the fleet. Triggers - "compare enrichment rules across servers", "reconcile the enrichment rules", "which servers are missing this rule", "why does UK show a different error message than US", "propagate this rule to the other servers", "are the error rules the same everywhere".
+---
+
+# dr-error-enrichment-reconcile — diff and reconcile across servers
+
+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 closes that gap.
+
+## Read first
+
+- [../dr-error-enrichment/reference/core.md](../dr-error-enrichment/reference/core.md)
+  — what a rule is, permissions, the full command surface, how matching works.
+- [../dr-error-enrichment/reference/safety-backup.md](../dr-error-enrichment/reference/safety-backup.md)
+  — target-server confirmation, backup-first, revert path, write gating, import
+  policy, batch-write etiquette.
+
+Back up **every** reachable server before the first write, not just the target: a
+reconcile session usually touches more than one, and the backup doubles as the
+diff baseline. That is one command:
+
+```bash
+dr error-enrichments export --all-servers --out /tmp/ee-backup/
+```
+
+With a sweep, `--out` is a **directory** and each server lands as its own
+`<SERVER>.csv`; add `--servers A,B` to narrow it and `--include-test` if test
+servers are in scope. Servers that fail are reported, not swallowed — read that
+list and confirm every server you intend to write to has a file before the first
+write.
+
+## 1. Collect
+
+```bash
+dr error-enrichments list --all-servers --json > /tmp/ee-all.json
+```
+
+Add `--include-test` only if test servers are genuinely in scope.
+
+Servers with no stored login are **skipped with a warning** — log in and re-run,
+or get the user to accept the gap explicitly, before calling the diff complete. A
+skipped server is invisible in every bucket below, so an unnoticed skip reads as
+"already consistent".
+
+A **non-zero exit** means a server errored. The data is partial; investigate
+before diffing it.
+
+## 2. Key by `(integration_type, re_pattern)`
+
+Never by `id`. Ids are per-server database ids — the same rule has a different id
+on every server, and `id` collisions across servers are coincidences, not matches.
+
+## 3. Report three buckets
+
+- **Missing** — present on some servers, absent on others. The default action is
+  to create it on the servers that lack it.
+- **Divergent** — same key, differing `description`, `resolution_steps`, `rank`,
+  `classification`, or `approved`. The action is to patch the outliers to the
+  canonical version.
+- **Server-only** — exists on exactly one server. Often a deliberate regional
+  rule; ask before propagating rather than assuming drift.
+
+Include per-server `hits` in the report. The version living on the server with
+real traffic is the battle-tested one, and an approved-on-one/draft-on-another
+split is the most common divergence worth fixing — a draft steals the hit and
+shows the user nothing, so those users currently see no explanation at all while
+the other region does.
+
+## 4. The user picks the canonical version
+
+Per rule, never auto-pick. "Newest `updated_at`" is not the same as "correct" —
+the newest edit is as likely to be the one that broke the pattern. Show the
+competing versions side by side with their hits and feedback and let the user
+choose.
+
+## 5. Propagate with batch writes
+
+Assemble the chosen versions into **batch writes, one server per run**, each
+through its own confirm cycle: run without `--confirm-token`, relay the printed
+plan (it lists every affected rule) to the user, then re-run with the token.
+
+For rules that already exist on the target — an array of per-rule patches, each
+carrying that server's own `id`:
+
+```bash
+cat > /tmp/uk-patches.json <<'JSON'
+[
+  {"id": 41, "description": "...", "resolution_steps": ["...", "..."], "approved": true},
+  {"id": 58, "rank": 3}
+]
+JSON
+dr error-enrichments update --payload-file /tmp/uk-patches.json --server UK
+```
+
+For rules missing on the target — an array of full rule objects:
+
+```bash
+cat > /tmp/uk-new.json <<'JSON'
+[
+  {"integration_type": "...", "rank": 4, "re_pattern": ".*INVALID_LOGIN.*",
+   "description": "...", "resolution_steps": ["..."], "classification": "DataSource",
+   "approved": true}
+]
+JSON
+dr error-enrichments create --payload-file /tmp/uk-new.json --server UK
+```
+
+Batch writes are sequential and a per-item failure does not abort the run: read
+the summary table afterwards for exactly which rules landed (with their new ids
+for `create`) and which failed, and retry only the failures. A zero exit means
+every write in the run returned 2xx — nothing more. It does not mean the fleet
+converged: a bulk `create` shifts sibling ranks on the target, and every
+divergence you did not include in this run is still there. Convergence is proven
+only by step 6.
+
+Three mechanics to keep the plan honest:
+
+- The batch confirm token binds the targets **and** the values being written, so
+  editing the patch file after the plan is printed invalidates the token. If the
+  user changes their mind about one rule, re-run the plan step and relay the new
+  plan — do not edit the file and reuse the printed token.
+- Array entries are type-validated before anything is sent, and a repeated `id`
+  across entries is rejected; the error names the entry by its position in the
+  file (`entry 3: …`). Merge the two
+  patches for that rule into one entry rather than listing the id twice.
+- `--rank` is rejected on a multi-id shared patch (`update 41 58 --rank 3`) —
+  ranks are per rule. Set a rank one rule at a time, or give each entry its own
+  `rank` in the array payload as above.
+
+**`import` is never the reconcile mechanism.** It is wipe-and-replace: it would
+delete every rule on that server — including its server-only rules, which are the
+one bucket you explicitly decided not to touch — and zero `hits`, `thumbs_up`,
+and `thumbs_down` on everything it recreates, destroying the exact traffic
+evidence you used in step 4 to pick a winner. It also reassigns every id, which
+invalidates the patch files you just built. Reconcile is many `update`s and
+`create`s, and nothing else.
+
+If the user asks for `import` by name anyway, follow the import policy in
+safety-backup.md: state the analytics loss and the id reassignment, get explicit
+confirmation, and only then run it.
+
+## 6. Prove convergence
+
+Re-run step 1 and re-diff. Report per server what changed, what failed, and which
+divergences the user deliberately left in place — a knowingly-kept regional
+difference is a result, not an omission.
+
+## Pitfalls
+
+| Mistake | Fix |
+|---|---|
+| Matching rules across servers by `id` | Key on `(integration_type, re_pattern)` |
+| Treating a skipped (not-logged-in) server as consistent | It appears in no bucket — log in or record the gap before reporting |
+| Diffing after a non-zero exit from `list --all-servers` | A server errored; the data is partial |
+| Using `import` to push one server's table onto another | Wipes server-only rules and zeroes all counters — batch `create`/`update` instead |
+| Auto-picking the newest `updated_at` as canonical | Newest is not correct; the user chooses per rule |
+| Propagating a server-only rule without asking | It is often a deliberate regional rule |
+| Reusing the source server's `id` in a target patch file | Patch ids must be the **target** server's ids |
+| Assuming a batch write is all-or-nothing | Per-item failures are recorded and the run continues — read the summary table |
+| Reading a zero exit as "the fleet converged" | It only means every write returned 2xx — re-collect and re-diff |
+| Editing the patch file and reusing the printed token | The batch token binds the values too — re-plan and relay the new plan |
+| Listing the same target `id` in two array entries | Rejected by index — merge them into one entry |
+| Hand-rolling a shell loop to back up each server | `export --all-servers --out <dir>` reports failures instead of swallowing them |
+| One `--confirm-token` cycle for several servers | Writes are one server per run, each with its own plan and token |
+| Declaring convergence from the write output alone | Re-run the collect step and re-diff |

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

@@ -0,0 +1,170 @@
+---
+name: dr-filebox-api-setup
+description: Enable "Upload via API" (support_api) on one or more Datarails fileboxes and configure a Workato/WorkatoBased data-query connection with object type and date range. Use when the user wants to set up API upload access and a data connection on a filebox or a set of fileboxes in a folder. Triggers - "turn on upload via API", "enable API upload", "set the data connection", "set up the data query", "configure the filebox API settings", "set start date and end date on the filebox".
+---
+
+# dr-filebox-api-setup — Enable API upload + configure data-query on fileboxes
+
+## What this skill does
+
+Automates the two-step filebox setup that enables external systems (e.g. Workato, Oracle) to push data into Datarails fileboxes via API:
+
+1. **Enable Upload via API** — turns on `support_api` on each target filebox (`dr documents support-api set <id> --on`). Returns the filebox UUID, which is the identifier used in API upload calls.
+2. **Set the data-query** — configures the Workato/WorkatoBased connection, object type, and date range on each filebox (`dr filebox data-query set <id> --payload-file`).
+
+Both steps are run for every target filebox. Fileboxes can be specified directly by ID/name or resolved from a parent folder.
+
+---
+
+## Inputs to gather before running
+
+Before issuing any commands, confirm the following with the user if not already clear from context:
+
+| Input | How to resolve |
+|---|---|
+| **Target fileboxes** | IDs/names, or a folder name to expand — run `dr filebox list --server <S>` and filter by parent folder ID |
+| **Server** | Ask if not obvious from context (`US`, `US2`, `UK`, `CA`, `EU`, `DEV`, `DEV-1`, `TEST`, `TEST-1`, `TEST-2`, `TEST-3`, `TEST-4`, `TEST-5`, `TEST-6`, `TEST-7`, `DEMO`) |
+| **Connection** | Run `dr integrations list --server <S>` and show the WorkatoBased options; ask the user to pick |
+| **Object type** | Ask — commonly `table`; surface the value from a reference filebox if one exists |
+| **Start date / End date** | Ask — commonly "start of month" / "end of month", which maps to `{{date_tag|somonth}}` / `{{date_tag|eomonth}}` |
+| **Reference filebox** | Optional — if another filebox in the same folder is already configured correctly, copy its data-query shape instead of building from scratch |
+
+---
+
+## Step 1 — Resolve target fileboxes
+
+If the user names a folder (e.g. "Account Analysis"), find its filebox ID first:
+
+```bash
+dr filebox list --json --server <S> > fb_list.json
+```
+
+Then filter in PowerShell to find the folder and its children:
+
+```powershell
+$data = Get-Content fb_list.json | ConvertFrom-Json
+# Find the folder ID
+$folder = $data | Where-Object { $_.name -like "*Account Analysis*" -and $_.is_folder -eq $true }
+# List children
+$data | Where-Object { $_.parent -eq $folder.id } | Select-Object id, name, is_folder, scenario
+```
+
+Confirm the list with the user before proceeding.
+
+---
+
+## Step 2 — Check for a reference filebox
+
+Before building the payload manually, check whether any filebox in the same folder already has a correctly configured data-query — this is the most reliable source of truth for the payload shape:
+
+```bash
+dr filebox data-query get <candidate_id> --json --server <S>
+```
+
+If a valid reference is found, copy its `connection`, `config`, `sync_only_changes`, `sync_interval`, and `sync_offset_array` exactly. Only substitute fields the user explicitly wants to change.
+
+If no reference exists, build the payload from the gathered inputs (see Step 4).
+
+---
+
+## Step 3 — Enable Upload via API on all target fileboxes
+
+Run in parallel for efficiency. This is a prod write — confirm with the user before running on `US`, `US2`, `UK`, `CA`, `EU`, `DEMO`.
+
+```bash
+dr documents support-api set <id1> --on --server <S> &
+dr documents support-api set <id2> --on --server <S> &
+# … one per filebox
+```
+
+After enabling, collect the UUID for each filebox from the saved `fb_list.json`:
+
+```powershell
+$ids = @(<id1>, <id2>, ...)
+$data | Where-Object { $ids -contains $_.id } | Select-Object id, name, uuid
+```
+
+---
+
+## Step 4 — Build the data-query payload
+
+Write the payload to a temp file. The canonical shape for a WorkatoBased connection with start-of-month / end-of-month date range:
+
+```json
+{
+  "connection": <integration_id>,
+  "config": {
+    "query": {
+      "startDate": "{{date_tag|somonth}}",
+      "endDate": "{{date_tag|eomonth}}"
+    },
+    "objectType": "table",
+    "type": null
+  },
+  "sync_only_changes": true,
+  "sync_interval": "",
+  "sync_offset_array": [0, -1]
+}
+```
+
+**Date range tokens:**
+
+| UI label | Token |
+|---|---|
+| Start of month | `{{date_tag|somonth}}` |
+| End of month | `{{date_tag|eomonth}}` |
+
+**`objectType`** — use `"table"` unless the user specifies otherwise.
+
+Save to a temp file (avoid spaces in the path on Windows):
+
+```powershell
+$payload | ConvertTo-Json -Depth 5 | Out-File -Encoding utf8 "C:\Users\<user>\dq_payload.json"
+```
+
+---
+
+## Step 5 — Set the data-query on all target fileboxes
+
+Run in parallel. Quote the file path to handle spaces:
+
+```bash
+dr filebox data-query set <id1> --payload-file "C:\path\to\dq_payload.json" --server <S> &
+dr filebox data-query set <id2> --payload-file "C:\path\to\dq_payload.json" --server <S> &
+# … one per filebox
+```
+
+Each success line prints: `Saved data-query #<N> (connection=<id>) on filebox <id>.`
+
+---
+
+## Step 6 — Return results
+
+Present a summary table of filebox name → UUID for all configured fileboxes:
+
+| Filebox Name | UUID |
+|---|---|
+| Example Filebox | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
+
+Offer to export the table as a CSV if the user wants it.
+
+---
+
+## Guard rails
+
+- **Prod confirmation required.** `support_api` and `data-query set` are writes. On `US`, `US2`, `UK`, `CA`, `EU`, `DEMO`, confirm in-chat before running.
+- **Never read out tokens or JWTs.** The UUID returned is not a secret, but session tokens are — do not surface them.
+- **Always verify the integration ID from `dr integrations list`** — do not guess or reuse IDs from a prior session without confirming they match the current tenant.
+- **Always quote file paths** in `--payload-file` on Windows to handle spaces in directory names.
+- **Use `--json` when parsing** — never parse the human-readable table output.
+
+---
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| Unquoted path with spaces in `--payload-file` | Always quote: `--payload-file "C:\path with spaces\file.json"` |
+| Reusing an integration ID from a different tenant | Run `dr integrations list --server <S>` on the target tenant to confirm |
+| Setting data-query before `support_api` | Either order works — the two are independent — but do `support_api` first so you can surface the UUID earlier |
+| Forgetting to check for a reference filebox | A sibling filebox with the right config is the most reliable payload source — always check before building manually |