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

package/dist/skills/mec-table-validation/SKILL.md

@@ -0,0 +1,383 @@
+---
+name: mec-table-validation
+description: Read-only audit of a Datarails tenant's MEC `trial_balance` table against UDM standards via dr-cli. Runs 8 structural and data-quality checks (table existence, mandatory aliases, types, population, currency uniqueness, rate uniqueness, reporting-month shape) and emits a pass/fail report. Use whenever the user wants to verify, audit, debug, or sanity-check an MEC environment, trial_balance setup, or asks "is this tenant set up correctly?" — even when they don't say "mec-table-validation" by name. Trigger especially when a user is investigating why MEC reconciliation, FX translation, or close numbers look wrong on a tenant — config drift on the TB table is the most common root cause and this skill surfaces it in seconds before deeper debugging starts. Also trigger on phrases like "check trial_balance standards", "is MEC compliant", "audit MEC config", "MEC sanity check", "TB structure check".
+---
+
+# mec-table-validation — Datarails MEC trial_balance verifier
+
+## What this skill does
+
+Read-only audit of a Datarails tenant's MEC `trial_balance` table
+against UDM standards. Runs 8 checks via `dr-cli` and emits a pass/fail
+report.
+
+The point is **fast triage**: when MEC reconciliation, FX translation,
+or close numbers look wrong on a tenant, config drift on the TB table is
+the most common root cause. Running this first surfaces the broken
+config before the operator wastes time debugging downstream symptoms.
+
+## When to use
+
+- "Verify MEC setup on this tenant"
+- "Is this tenant's MEC compliant?"
+- "Audit trial_balance"
+- "Check MEC standards"
+- "Why is MEC reconciliation broken on this tenant?" (run this before
+  deep debugging)
+- "Sanity-check TB structure"
+- "Debug MEC config"
+
+## Prerequisites
+
+- `dr` CLI installed and on PATH (see `~/.claude/skills/dr-cli/SKILL.md`).
+- Logged in to the target server (`dr login --server <key>`); JWT
+  refresh is automatic so an expired access token is fine.
+- Operator is impersonated as the right tenant. The skill verifies
+  whoever is currently impersonated — the pre-flight `whoami` exists so
+  you can confirm before running.
+
+## Inputs
+
+- `--server <key>` — required. Valid: `US`, `US2`, `UK`, `CA`, `EU`, `DEV`,
+  `DEV-1`, `TEST`, `TEST-1`, `TEST-2`, `TEST-3`, `TEST-4`, `TEST-5`,
+  `TEST-6`, `TEST-7`, `DEMO` (case-insensitive). Default per project
+  convention: `US`.
+- `--report` — optional. Writes a markdown report to cwd in addition to
+  terminal output (filename: `mec-table-validation-<orgId>-<YYYY-MM-DD>.md`).
+- `--json` — optional. Emits structured JSON instead of the human
+  report. Use when piping or scripting.
+
+That's it. The skill runs against whoever is currently impersonated on
+that server.
+
+## Pre-flight (always)
+
+Run first, before any check, and echo the result to the user:
+
+```
+dr whoami --server <key>
+```
+
+This decodes the local JWT (no network call) and reveals who you'll be
+auditing. Auditing the wrong tenant is the only way this skill produces
+misleading-but-confident results, so this step is non-negotiable. Do
+not proceed if the user hasn't confirmed it's the right tenant.
+
+## The standard
+
+The 8 checks below are the source of truth. They derive from the
+"Month End Close (MEC) UDM Data Scheme Set up Instructions"
+Confluence page (id `1467482113`) plus operator-confirmed conventions
+that aren't in that doc.
+
+### Mandatory field aliases + expected types
+
+The MEC TB table must expose these 8 fields by their **system alias**
+(not display name). Aliases follow "lowercase, spaces → `_`"
+EXCEPT for the Account Group L0/L1/L2/L3 series, which use the
+UDM-standard `dr_acc_lN` aliases — that's a known and documented
+convention exception, not a tenant misconfiguration.
+
+| Required alias                         | Expected type    | Notes |
+|---------------------------------------:|:-----------------|:------|
+| `account_full`                         | Text             | account number + name |
+| `posting_amount`                       | Float            | balance in posting currency |
+| `entity`                               | Text             | |
+| `posting_currency`                     | Text             | local currency, e.g. `USD`/`GBP`/`EUR` |
+| `reporting_month`                      | Date             | epoch on the wire |
+| `reporting_rate`                       | Text **or** Float | either accepted — Text is legitimate |
+| L3 grouping field (see below)          | Text             | |
+| `reporting_currency`                   | Text             | consolidation target |
+
+**L3 alias resolution.** The L3 grouping field can ship under either
+of two aliases. Resolve in this order:
+
+1. If `mec_grouping` is set on a field, use it. (Newer MEC convention.)
+2. Else if `dr_acc_l3` is set, use that.
+3. If neither alias appears in `fields[]`, check 2 fails for L3 and
+   any data check that depends on L3 is reported as `skip` with a note
+   explaining why.
+
+### The 8 checks
+
+1. **TB table exists.** `dr semantictables get trial_balance` returns
+   a valid response.
+2. **All 8 mandatory aliases present.** Walk `fields[]` from check 1
+   and confirm every required alias appears (using the L3 resolution
+   rule above).
+3. **Each mandatory field has the expected type.** Same response;
+   compare each field's `type` to the table.
+4. **Each mandatory field is populated.** For each alias, distinct
+   values across the table is non-empty. (A field can exist with the
+   right type but be entirely null on this tenant — that's a real
+   misconfig.)
+5. **Each `entity` → exactly one `posting_currency`.** A given entity
+   should not change posting currency across rows; if it does, FX
+   translation will silently produce nonsense.
+6. **Whole table → exactly one `reporting_currency`.** Reporting
+   currency is the single consolidation target for the org; multiple
+   distinct values means the FX translation chain is broken or the
+   table has been mis-fed.
+7. **Each `(account_full, reporting_month, entity)` → exactly one
+   `reporting_rate`.** Same account, same month, same entity should
+   resolve to one rate. Multiple rates means the FX-rate join landed
+   on multiple matches.
+8. **`reporting_month` is always last-day-of-month at 00:00:00 UTC.**
+   Wire format is unix-seconds epoch. Each distinct value must decode
+   to the last calendar day of its month (28/29/30/31 depending on
+   month and leap year) with no intra-day component.
+
+## Recipe — how to execute
+
+Sequence matters. Checks 1–3 read metadata once and feed checks 4–8.
+
+### Step 1 — identify tenant
+
+```
+dr whoami --server <key>
+```
+
+Echo the resolved server, email, user_id to the user. Do not proceed
+unless the user has confirmed (or it's already established) that this
+is the tenant they want to audit.
+
+### Step 2 — fetch trial_balance metadata
+
+```
+dr semantictables get trial_balance --server <key> --json
+```
+
+If this fails (404, no such alias, error response), check 1 fails and
+the rest of the run is skipped — there's nothing to audit.
+
+From the response, capture:
+
+- `id` — needed for `templates aggregate` calls (which take a numeric
+  template id, not an alias).
+- `fields[]` — for alias presence + type checks.
+- An **alias → name map** built from `fields[]` — `templates aggregate`
+  takes display field NAMES (e.g. `Entity`, `Posting Currency`), not
+  aliases. Without this map the aggregate calls won't resolve. (This is
+  the one asymmetry between the two CLI surfaces.)
+
+### Step 3 — resolve the L3 alias
+
+Look in `fields[]` for `mec_grouping`. If present, use it. Else look
+for `dr_acc_l3`. If neither, mark check 2 as fail for L3 and `skip`
+any L3-dependent data check.
+
+### Step 4 — checks 2 + 3 (alias + type, in-memory)
+
+Walk the required-aliases table and verify each appears in `fields[]`
+with the expected type. No additional CLI calls — both checks come from
+the response captured in Step 2.
+
+For `reporting_rate`, accept either `Text` or `Float`. For all other
+mandatory fields, the type must match exactly.
+
+### Step 5 — check 4 (population)
+
+For each mandatory alias that exists on this tenant:
+
+```
+dr semantictables distinct trial_balance --field <alias> --server <key> --json
+```
+
+Pass if the returned array has length ≥ 1. Fail (with the empty result)
+if the column has no non-null values across the table.
+
+### Step 6 — check 6 (single reporting_currency)
+
+```
+dr semantictables distinct trial_balance --field reporting_currency --server <key> --json
+```
+
+Pass if length = 1. On fail, surface the distinct values found.
+
+### Step 7 — check 5 (entity → one posting_currency)
+
+Use the alias→name map from Step 2 and the template id captured there:
+
+```
+dr templates aggregate <id> \
+  --group-by <name_of_entity_field> \
+  --metric "<name_of_posting_currency_field>:COUNT_UNIQUE" \
+  --server <key> --json
+```
+
+The response is a JSON array containing **three kinds of entries**, in
+this order:
+
+```json
+[
+  {"<entity_name>": "FR01", "<posting_currency_name>": 1},
+  {"<entity_name>": "UK01", "<posting_currency_name>": 1},
+  {"<entity_name>": "DE01", "<posting_currency_name>": 1},
+  {"<posting_currency_name>": 5},                 // totals row — skip
+  {"col_keys": [], "row_keys": [["DE01"], ...]}   // envelope — skip
+]
+```
+
+Filter to entries that have the entity field set (per-group rows).
+For each such row, the metric column must equal 1. Surface any entity
+with count > 1 as a fail.
+
+### Step 8 — check 7 (rate uniqueness)
+
+```
+dr templates aggregate <id> \
+  --group-by <account_full_name> \
+  --group-by <reporting_month_name> \
+  --group-by <entity_name> \
+  --metric "<reporting_rate_name>:COUNT_UNIQUE" \
+  --server <key> --json
+```
+
+Same response shape — filter to per-group rows, check the metric
+column is 1 for each. Surface up to 10 violating tuples on fail (don't
+dump thousands of rows).
+
+### Step 9 — check 8 (reporting_month shape)
+
+```
+dr semantictables distinct trial_balance --field reporting_month --server <key> --json
+```
+
+Returns an array of unix-seconds epochs (as JSON strings). For each:
+
+- Decode to UTC date.
+- Verify time component is 00:00:00 UTC.
+- Verify the day-of-month equals the last calendar day of that month
+  (28/29 for Feb, 30 for Apr/Jun/Sep/Nov, 31 for the rest; account for
+  leap years on Feb).
+
+Pass if every epoch decodes cleanly to last-of-month at midnight UTC.
+Fail otherwise; list each offending epoch with its decoded date so the
+operator can spot whether it's an off-by-one (first-of-month was
+configured) or a different shape entirely.
+
+### Step 10 — render report
+
+After all 8 checks have run, render the report (terminal default;
+`--json` for structured; `--report` for markdown to disk).
+
+## Output format
+
+### Default (human-readable terminal)
+
+Open with the tenant block, then one line per check, then a summary.
+Failures expand under the check line with details.
+
+```
+Server:   US (https://app.datarails.com)
+Email:    support@mec-demo.com
+User ID:  73825
+Table:    trial_balance (id 36928, name "TB")
+
+Check 1   ✓  trial_balance table exists
+Check 2   ✓  all 8 mandatory aliases present
+              L3 resolved to: dr_acc_l3
+Check 3   ✓  all field types match
+Check 4   ✓  all fields populated
+Check 5   ✓  every entity → 1 posting_currency
+Check 6   ✓  whole table → 1 reporting_currency (USD)
+Check 7   ✓  reporting_rate unique per (account_full, reporting_month, entity)
+Check 8   ✓  reporting_month always last-of-month UTC
+
+Result: 8/8 checks pass
+```
+
+On any fail:
+
+```
+Check 3   ✗  field type mismatch
+              posting_amount expected Float, got Text
+
+Check 5   ✗  entity → multiple posting_currency
+              DE01 has 2 distinct posting_currency values
+              FR01 has 3 distinct posting_currency values
+
+Check 8   ✗  reporting_month is not last-of-month UTC
+              1738368000 → 2025-02-01 00:00:00 UTC  (first-of-month, not last)
+              1740787200 → 2025-03-01 00:00:00 UTC  (first-of-month, not last)
+```
+
+### `--json` flag
+
+Emit a structured object for scripting. Status enum:
+`pass | fail | warn | skip | error`.
+
+```json
+{
+  "tenant": {
+    "server": "US",
+    "email": "support@mec-demo.com",
+    "user_id": 73825
+  },
+  "table": {"id": 36928, "name": "TB", "alias": "trial_balance"},
+  "l3_alias_resolved_to": "dr_acc_l3",
+  "checks": [
+    {"id": 1, "name": "trial_balance exists", "status": "pass"},
+    {"id": 2, "name": "mandatory aliases present", "status": "pass"},
+    {"id": 3, "name": "field types", "status": "fail",
+     "details": [{"alias": "posting_amount", "expected": "Float", "actual": "Text"}]}
+  ],
+  "summary": {"pass": 7, "fail": 1, "warn": 0, "skip": 0, "error": 0, "total": 8}
+}
+```
+
+### `--report` flag (markdown report on disk)
+
+Writes `mec-table-validation-<orgId>-<YYYY-MM-DD>.md` to cwd. Same content as
+the terminal output plus a metadata block at the top, matching the
+project's report-naming convention:
+
+```
+**Date:** YYYY-MM-DD
+**Operator:** <email running the audit>
+**Server:** <key>
+**Authenticated as:** <impersonated email> (user_id N)
+**CLI version:** dr-cli X.Y.Z
+**Tool:** mec-table-validation
+```
+
+## Edge cases
+
+| Situation | Behavior |
+|---|---|
+| TB table missing (semantictables get fails) | Check 1 fails; checks 2–8 are reported as `skip` with note "no trial_balance to audit". Exit early. |
+| Required alias missing | Check 2 fails for that alias. Data checks that depend on the missing field (e.g. check 7 needs `reporting_rate`) are `skip` with note "depends on missing alias <X>". |
+| TB exists but is empty (zero rows) | Checks 4–8 are `warn`, not `fail`. A fresh tenant pre-rescan can legitimately have zero rows — flagging this as `fail` would cry wolf. |
+| `templates aggregate` 500 / timeout | Default 60s polling budget can be too short for large tenants. Re-run that single check with `--timeout 180000`. If it still fails, surface the error verbatim and mark the check `error`. |
+| L3 has both `mec_grouping` and `dr_acc_l3` set | Use `mec_grouping` (newer convention). Note this in the report so the operator knows which alias the audit used. |
+| `reporting_rate` field type is Text | Pass check 3 — Text is documented as legitimate (rate is sometimes stored as a formula expression). Float also passes. Anything else (Integer, Boolean) fails. |
+
+## Guard rails
+
+- **Read-only.** This skill never writes. No confirmation gates needed.
+- **Always pass `--json`** to every `dr` call. Table output is for
+  humans; the recipe parses everything programmatically and table
+  formatting will silently truncate.
+- **Never paste credentials.** Session tokens live in the OS keychain;
+  JWTs and session IDs are off-limits per project convention.
+- **Always run `whoami` first.** Auditing the wrong tenant produces
+  confidently-wrong findings — the worst kind. Two seconds of
+  pre-flight prevents this.
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| Using aliases in `templates aggregate --group-by` | aggregate takes display field NAMES (`Entity`, not `entity`); resolve via the alias→name map captured from `semantictables get` in Step 2 |
+| Treating `reporting_month` as ISO date | Wire format is unix-seconds epoch (as a JSON string). Decode before comparing. |
+| Reading the totals or envelope row as a per-entity row | `templates aggregate` returns per-group rows + a totals row + a `{col_keys, row_keys}` envelope. Filter to entries that have the group-by field set before checking metric values. |
+| Failing the run because TB has zero rows | Empty TB on a fresh tenant is `warn`, not `fail` — let the operator know without crying wolf. |
+| Re-running `dr login` because `whoami` shows JWT expired | Don't. JWT refresh is automatic on the next API call. Re-login only after a real `session expired` error post-call. |
+
+## Related skills
+
+- `~/.claude/skills/mec-implementation/SKILL.md` — sets up an MEC tenant
+  from scratch. If this verifier fails, that skill is what the operator
+  uses to fix it.
+- `~/.claude/skills/dr-cli/SKILL.md` — the underlying CLI inventory.
+  All commands this skill issues are documented there.

package/dist/skills/plugins.json

@@ -0,0 +1,24 @@
+{
+  "dr-cli-integrations": [
+    "connector-sandbox",
+    "datarails-connect-workato",
+    "datarails-connectors-onboard-connector",
+    "dr-error-enrichment",
+    "dr-error-enrichment-author",
+    "dr-error-enrichment-improve",
+    "dr-error-enrichment-maintain",
+    "dr-error-enrichment-reconcile",
+    "dr-filebox-api-setup",
+    "validate-workato-migration"
+  ],
+  "dr-cli": [
+    "dr-cli",
+    "dr-switch-user",
+    "fx-conversion-matrix",
+    "fx-onboard"
+  ],
+  "dr-cli-pat": [
+    "dr-validate",
+    "mec-table-validation"
+  ]
+}

package/dist/skills/validate-workato-migration/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: validate-workato-migration
+description: Use when a customer's Workato feed is being migrated to a dr-connectors (DRIP) connector and the connector's output has to be proven identical to Workato's before cut-over, or when working in the Workato-migration staging org test-workato-migration.com (US 21304, US2 1691, UK 3289, CA 5106). Also for "query create" returning 422 "artifact version not registered" for a staging-org binding, and for comparing connector CSVs with Workato filebox versions. Not for building or publishing the connector itself (datarails-connectors-onboard-connector) or for reading Workato alone (datarails-connect-workato). Triggers - "validate the migration", "compare Workato vs connector", "parity check against Workato", "test the migration in the staging org", "test_workato_migration org", "are the connector files identical to Workato", "migration validation report".
+---
+
+# Validate a Workato → DRIP migration in the staging org
+
+Validation never happens in the customer's org. Parallel `(migration)` fileboxes there auto-map
+into the **same tables** as the Workato fileboxes and double-count the customer's data. It happens in a **dedicated staging org per server** instead, which has no tables. The
+customer's org is only **read**. Cut-over is out of scope.
+
+Both sides are compared as the **CSV stored in Datarails**: Workato's recipe upload in the customer
+filebox, and the connector's landed version in the staging mirror (`dr filebox download
+--doc-version` returns the stored bytes). Never compare tables/StarRocks (they come after the Data
+Mapper and hide quoting/format differences), and never re-run a Workato recipe (that's a write).
+
+## Staging orgs (domain `test-workato-migration.com`)
+
+| DRIP region folder | `--server` | Staging org id |
+|---|---|---|
+| `us/`  | `US`  | **21304** |
+| `us2/` | `US2` | **1691**  |
+| `uk/`  | `UK`  | **3289**  |
+| `ca/`  | `CA`  | **5106**  |
+
+Identity: `support@test-workato-migration.com`. The customer and the staging org are always on the
+same server, and a customer on another datacenter needs a new staging org and row first. One-time setup
+and the access rules are in [reference/staging-orgs.md](reference/staging-orgs.md).
+
+## Rules (non-negotiable)
+
+1. **Prod.** All four servers are production. Show the user each write (folder/filebox create,
+   datasource, binding, sync, teardown) and get a yes first. Reads need no confirmation.
+2. **Two identities, never mixed up.** Every `dr` call names its `--account`:
+   `STG="--server <S> --account support@test-workato-migration.com"` for **all writes**;
+   `CUS="--server <S> --account <customer support user>"` for **reads only**. The org comes from the JWT
+   (`dr filebox create` has no `--org`), so the wrong account writes into the wrong org silently.
+   Before the first write, `dr whoami $STG` must print `Impersonated by:` and the staging org id.
+3. **Byte-identical is the only pass.** sha256 equal. Same values but different quoting,
+   `-1` vs `-1.0` or CRLF vs LF is a **FAIL**: the connector must reproduce Workato's bytes.
+4. **Stop on mismatch.** Report and wait for the user. Don't edit, republish or re-sync on your own.
+5. `dr connectors` calls need VPN + `NODE_EXTRA_CA_CERTS` (see `datarails-connectors-onboard-connector`).
+6. Workato is **read-only**: GET only, via `datarails-connect-workato`.
+7. **Secrets never printed.** Credentials go from their source straight into the payload file in
+   the same shell call, and the file is deleted afterwards.
+
+## Prerequisites
+
+The connector is merged to `main` in dr-connectors, and CI has tagged and published
+`<dc>/<customer_org>/<vendor>/<dq>/vN` to JFrog (onboard skill §1–2). Scratch dir
+`<scratchpad>/<customer>-validate/` holds `inventory.json`, `mapping.json`, `wk/`, `st/`,
+`manifest.json` and `report.md`.
+
+## 0. Identities
+
+```bash
+dr login-as support@test-workato-migration.com --server <S> --as <operator-email>
+dr login-as <customer support user>        --server <S> --as <operator-email>
+dr whoami $STG ; dr whoami $CUS
+```
+Impersonation JWTs last ~5 minutes, so re-run `login-as` on a 401.
+
+## 1. Inventory from Workato (read-only)
+
+Start from the **recipes**, not the customer's fileboxes (`datarails-connect-workato`):
+1. `GET /managed_users` → the customer's `managed_user_id`; `GET /managed_users/{id}/recipes` → agree with the user which recipes are **in scope**.
+2. Per recipe: the **target filebox** it uploads to (recipe code / triggering webhook) and the **dataset + selector** it pulls (e.g. report × restaurant GUID).
+3. **Credentials:** `account_property` pills resolve to environment properties, which the API returns (`GET /managed_users/{id}/properties?prefix=<p>`). Workato **connection** secrets aren't returned by the API; get those from the vendor admin or the customer. Record the source. One credential → one datasource.
+4. `$CUS`: `dr filebox get <fb> --json` (name, parent chain, date tag config) and `dr filebox data-query get <fb>`.
+
+Save `inventory.json` (`recipe_id, recipe_name, workato_fb, name, folder_path, date_sub_type,
+dataset, selector, credential_source`) and show it to the user before creating anything.
+
+## 2. Staging tree (`$STG`, confirm first)
+
+```
+<customer org id>_<Customer name>/          e.g. 16127_Acurio International
+  <System>/                                 source system as Workato names it, e.g. Toast
+    <Workato sub-folders below System>/     e.g. Labor/Shifts
+      <Workato filebox, same name>          e.g. Jarana Aventura
+```
+Mirror the sub-folders too, because per-entity filebox names repeat across datasets. Reuse existing folders
+(`dr filebox list $STG --json`), since a re-run must never duplicate. Create folders with `dr filebox create
+--name <n> --folder [--parent <id>]`, and each mirror 1:1 with the same name, scenario and date sub-type
+(`--date-sub-type …` or `--no-date`) under `--parent <deepest folder>`. Capture `id` + `uuid` from `--json`.
+Save `mapping.json` (`workato_fb, staging_fb, staging_uuid, name, dataset, selector`).
+
+## 3. Make the artifact available to the staging org
+
+Ingest and bindings are org-scoped: a staging binding can't use the customer's ingested
+version, and `query create` returns **422**. So copy the same bytes, then ingest as the staging org:
+```bash
+gh workflow run copy-artifact-to-staging.yml -R Datarails/dr-connectors \
+  -f datacenter=<dc> -f customer_org_id=<org> -f vendor=<vendor> -f dataquery=<dq> -f version=vN
+dr connectors publish "<dc>/<staging_org>_(test-workato-migration.com)/<vendor>/dataqueries/<dq>.py" --tag vN $STG --json
+```
+The workflow can only write under the four staging orgs and refuses different bytes. The publish path
+must name the **staging** org (the CLI rejects a path/JWT org mismatch), and `--tag` is required because
+there's no git tag for that path. With `--tag`, `publish` only parses the path and never reads the file, so the
+staging-org path need not exist locally; never commit a staging-org folder. `409` = already ingested.
+
+## 4. Wire the connector (`$STG`, confirm first)
+
+As in the onboard skill §3–4, but in the staging org:
+- **Datasource** `DatarailsConnector`, `is_sync_service: true`, `organization: <staging org>`, with the
+  credential from §1. Name it `<Customer> <System> (validation)`.
+- **Filebox:** `dr documents support-api set <fb> --on`, then `dr filebox data-query set <fb>
+  --payload-file dq.json`. Write `config` and `config.query` as **nested objects** (the CLI encodes them):
+  ```json
+  {"connection": <ds>, "sync_only_changes": false,
+   "config": {"type": null, "query": {"objectType": "<dataset>", "<selector>": "<value>",
+     "startDate": "{{ date_tag|format:'%Y-%m-%d' }}", "endDate": "{{ date_tag|format:'%Y-%m-%d' }}",
+     "fileName": "<Workato's landed file name without .csv>"}}}
+  ```
+  Use the production Sync-query keys, and **no** sync interval.
+- **Binding:** `dr connectors connector create --secret-ref <ds>`, then `dr connectors query create
+  --connector-id <id> --filebox-uuid <uuid> --filebox-id <fb> --artifact-name <vendor>__<dq>
+  --artifact-version vN --runtime-flavor <flavor>`. A 422 here means §3 is missing for this `vN`.
+
+## 5. Periods (read-only, `$CUS`)
+
+`dr filebox versions <workato_fb> --json` → the **latest 3–5 distinct date tags**, newest version per
+tag. Prefer **closed** periods past the recipe's own re-sync window (e.g. re-syncs 5 days → pick days
+≥ 6 days old). **Undated fileboxes:** latest Workato version vs a staging sync now. Vendor data may have
+moved, so a mismatch there **isn't conclusive**.
+
+## 6. Sync (`$STG`, confirm first)
+
+`dr filebox data-query sync <staging_fb> --date YYYY-MM-DD`: one sync at a time per filebox (a
+running sync holds the Singleton, so the next trigger is skipped). Wait for the version in `dr filebox versions
+<staging_fb> --json` before the next one. Failures: completion verdict + Groundcover (onboard skill §5).
+
+## 7. Compare, report, stop
+
+```bash
+dr filebox download <workato_fb> --doc-version <wk_v> --output wk/<fb>_<wk_v>.csv --force $CUS
+dr filebox download <staging_fb> --doc-version <st_v> --output st/<fb>_<st_v>.csv --force $STG
+python <this skill's dir>/scripts/compare_files.py <scratch>/manifest.json --report <scratch>/report.md
+```
+`manifest.json` sits next to `wk/`/`st/` and has one entry per Workato version: `name`
+(`<System> / <filebox> / <period>`), `workato`, `workato_version`, `staging`, `staging_version`. Relative
+paths resolve against the manifest. Exit 0 = at least one pair and all byte-identical. Otherwise each `DIFFERENT` pair is
+diagnosed: encoding/BOM, line endings, trailing newline, header, rows only on one side, row order,
+per-column cell diffs, quoting only, or unparseable.
+
+Give the user `report.md` (every filebox × period, both version ids, sizes, sha256), the landed file
+names on both sides, your read of each failure's likely cause (e.g. Workato quotes empty cells, or a
+Workato recipe bug the user must decide whether to replicate), and the staging ids created. **Stop.** A fix
+goes merge → new vN → §3 → `dr connectors query repoint` → re-sync. Cut-over is a separate, approved step.
+
+## 8. Teardown (once accepted, `$STG`, confirm first)
+
+The staging datasource holds **live customer credentials**, so remove it right away:
+1. `dr connectors query list` → `dr connectors query delete <queryId>` for each binding.
+2. `dr integrations delete <ds>` (two-step confirm). dr-cli has no connector delete, so the orphaned
+   `Connector` row points at a deleted datasource. Record its id.
+3. Keep the staging fileboxes as evidence until cut-over + ticket close, then delete the `<Customer>` tree.
+4. Delete the local `wk/` and `st/` downloads: they are customer data. Keep only `report.md`.
+5. Record the report, what was deleted and what was kept in the migration ticket.
+
+Symptoms and fixes: [reference/gotchas.md](reference/gotchas.md).
+
+## Related
+
+- `datarails-connectors-onboard-connector`: build, publish and wire the connector.
+- `datarails-connect-workato`: recipes, connections, properties (GET only).
+- `dr-switch-user`: `dr login-as` details. `connector-sandbox`: local fix loop before a merge.

package/dist/skills/validate-workato-migration/reference/gotchas.md

@@ -0,0 +1,16 @@
+# Gotchas
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Filebox/datasource appears in the customer org | A write ran with `$CUS` (or no `--account`) | Always pass `$STG` for writes; delete the stray object with the user's approval |
+| `query create` → 422 "artifact version not registered" | The artifact is ingested only for the customer's org (the registry is org-scoped) | Step 3: `copy-artifact-to-staging.yml`, then `dr connectors publish <staging path> --tag vN $STG` |
+| `dr connectors publish` aborts "published under org A … authenticated as org B" | Passed the customer's dataquery path with `$STG` | Use `<dc>/<staging_org>_(test-workato-migration.com)/…` + `--tag vN` |
+| Copy workflow: "target exists with DIFFERENT bytes" | A different artifact was already copied for that `vN` | Stop and investigate. Never overwrite: the staging copy must equal what the customer runs |
+| Second sync of a filebox never runs | The previous run still holds the filebox Singleton | Wait for the version to land before re-triggering |
+| One row differs, on a recent period only | Vendor data changed after Workato's run | Re-pick older, closed periods before calling it a connector bug |
+| Only bytes differ, values equal | Quoting / float formatting / line endings | Still a FAIL: match Workato's CSV writer in the connector |
+| Sync-query shows escaped quotes / doesn't render | `config.query` written as a JSON string | Write it as a nested object; the CLI encodes it |
+| `dr filebox get <new fb>` → "has no latest version" | The filebox is empty until the first sync | Harmless; use the `--json` output of `filebox create` |
+| UI: fileboxes open by URL but the left panel is empty | support@ is ADMIN, not SUPER_ADMIN | [staging-orgs.md](staging-orgs.md) one-time setup |
+| UI: "You don't have permission for this FileBox" | The browser is on a filebox from another org, or you're logged in as your own user | Log in as support@ and open `#/document_details/<staging id>` |
+| 401 mid-run | Impersonation JWT (~5 min) expired | Re-run `dr login-as` for that identity |

package/dist/skills/validate-workato-migration/reference/staging-orgs.md

@@ -0,0 +1,26 @@
+# Staging orgs: setup and access
+
+Created 2026-09-29 with `dr organizations add --domain test-workato-migration.com` on each server.
+The server ignores `--name`, so each org is named after its domain.
+
+| Server | Org id | support@ SUPER_ADMIN |
+|---|---|---|
+| US  | 21304 | done 2026-09-29 |
+| US2 | 1691  | not yet |
+| UK  | 3289  | not yet |
+| CA  | 5106  | not yet |
+
+## One-time setup per server
+
+- **`support@test-workato-migration.com` must be SUPER_ADMIN** (admin Users screen). New orgs
+  create it as ADMIN, which can open fileboxes by URL but gets an **empty left-panel tree** in the UI.
+  Check: `dr organizations contacts --server <S> --account support@test-workato-migration.com --json`.
+- The org's own `permissions` list is empty. That's expected: those entries are legacy feature flags.
+- Everything created is shared only with support@. To look at it in the UI, log in as that user and
+  open `#/document_details/<id>`.
+
+## Access (proposed, pending sign-off)
+
+Only operators running migrations work in these orgs, through `dr login-as` from their own operator
+login. The orgs temporarily hold customer credentials and data, so don't add other users or share
+anything from them. The skill's teardown step removes credentials after each validation.