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

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

@@ -0,0 +1,392 @@
+---
+name: dr-validate
+description: Validate a Datarails-generated financial report against a customer's own P&L or Balance Sheet mid-onboarding. Drives the `dr validate onboarding` command group (part of the dr-cli binary) to create a session, upload the source files, run reconcile + investigation on the per-env onboarding-validation service, and return a CSM-actionable report of resolved and unresolved discrepancies. The customer's own report is the only file the operator supplies; the Datarails report, Chart of Accounts, GL/transactions, and (for a Balance Sheet) the trial balance are pulled from the client's Datarails environment via dr-cli. Triggers - "validate the mapping for client X", "reconcile the customer's P&L against our Datarails export", "check the discrepancies between the client's numbers and ours", "why don't the customer's numbers match ours", "audit the onboarding mapping before we hand it back", "/dr-validate".
+---
+
+# dr-validate — Datarails onboarding reconciliation harness
+
+## When Claude should invoke this skill
+
+Use any time a CSM (or engineer) needs to validate a client's Datarails
+mapping mid-onboarding — i.e. to explain why the customer's own numbers
+don't match the Datarails-generated report. Concrete triggers:
+
+- "validate the mapping for client X"
+- "reconcile the customer's P&L against our Datarails export"
+- "the customer's numbers don't match ours — why?"
+- "audit this onboarding before we hand it back"
+- "/dr-validate" or any direct invocation
+
+## Not the same as `dr reconciliation`
+
+This skill is **onboarding-mapping validation** via `dr validate
+onboarding …`. It is a different service and a different lifecycle from
+the MEC month-end-close group `dr reconciliation` (alias `dr recon`):
+
+- **`dr validate onboarding`** (this skill) — validates a client's own
+  report against the Datarails export *before* hand-off, against the
+  per-env onboarding-validation service.
+- **`dr reconciliation`** — inspects/operates a live financial-close
+  (MEC) tenant. Unrelated. Don't reach for it here, and don't route
+  onboarding validation through it.
+
+## How the files work (read this first)
+
+Two things about this service drive everything below:
+
+1. **You hand off files; the service classifies them.** There is no
+   per-file "role" flag. Upload every relevant workbook with a repeated
+   `--file`, and the service auto-detects each one's role (client
+   report, Datarails report, Chart of Accounts, GL/transactions, trial
+   balance, ...). Don't try to label files — just get the right ones in.
+
+2. **Only the customer's own report comes from the operator.** During
+   onboarding, the client's data already lives in their Datarails
+   environment, so the **Datarails report, Chart of Accounts,
+   GL/transactions, and trial balance are fetched via dr-cli** (fileboxes
+   / file download — see the dr-cli skill for the exact commands) and
+   then uploaded. The one artifact Datarails does *not* have is the
+   **customer's own P&L/Balance Sheet export** — the "truth" they
+   produced outside Datarails. That is the only file you ask the operator
+   for. If it isn't already in the conversation, ask for it as a local
+   path (or an attachment you can save locally). Don't ask the operator
+   for the locations of the Datarails-side files.
+
+3. **Validate on the client's own env — one login.** The
+   onboarding-validation service is deployed per-env, and the CLI derives
+   each env's host from the server registry. **You do not need to know
+   which envs are supported** — pass the client's env as the single
+   `--server` for *everything* and the CLI targets the right host: one
+   `dr login` for that env, then the same `--server <ENV>` on every
+   command. Keeping the client's data on the client's own env is the right
+   default for real financials (data residency).
+
+   **Fallback — an env with no onboarding instance.** Not every registry
+   env has one deployed (mostly internal test envs); where it isn't, the
+   command simply fails to reach the host. The service never
+   queries the client tenant — it sees only the files you hand it — so you
+   *can* validate by pointing the validate commands at a working instance
+   while fetching the files from the client env.
+
+   It is **not** stateless, though: it creates a server-side session and
+   stores your uploaded files against it, so this path physically copies
+   the client's financials onto the validation env. They persist there
+   until the session goes away — sessions TTL after ~24h and a server
+   restart can drop them, but don't rely on either as cleanup: run
+   `dr validate onboarding session delete <id>` when you are done. Use
+   this path only for testing or non-sensitive data unless that env's
+   isolation and retention have been verified.
+
+   It also needs a second `dr login`, and **that login is the point** —
+   pass the *validation* env as `--server`, not the client's. The JWT
+   follows `--server`, so validating on one env while still passing the
+   client's key would hand that client's live production token to the
+   other env's pod.
+
+## Required inputs (gather before running)
+
+Which files you want depends on the report type. Core files materially
+determine the result; the recommended ones aren't hard-required but
+substantially improve the investigation.
+
+| Report type | Core files | Strongly recommended |
+|---|---|---|
+| **P&L** | Customer's own P&L · Datarails P&L · Chart of Accounts | GL / transactions |
+| **Balance Sheet** | Customer's own Balance Sheet · Datarails Balance Sheet · Chart of Accounts | Trial Balance (drives opening-balance checks) · GL / transactions |
+
+- **Customer's own report** → from the operator (the only operator-supplied file).
+- **Everything else** → fetch from the client's Datarails environment via dr-cli.
+- **Accepted formats:** `.xlsx`, `.xlsm`, `.xls`, `.xlsb`, `.csv`.
+
+Two more parameters, both of which Claude should resolve on its own —
+don't interrogate the operator:
+
+- **Report type** (`P&L` or `BS`): infer it from the request. "Reconcile
+  the P&L" → `P&L`; "check the balance sheet" → `BS`. Only ask if the
+  request is genuinely ambiguous.
+- **Period**: optional — do **not** ask for it. The reconciliation agent
+  infers the period from the files. Pass `--period` only if the operator
+  already stated one.
+
+## Prerequisites
+
+- `dr` (the Datarails CLI) installed. This skill ships inside dr-cli and
+  is auto-installed with it — no separate install step.
+- `dr login` run once for the env you'll use — the CLI reads the JWT from
+  the OS keychain. Normally that's **one** login: the client's own env
+  both fetches the Datarails files and validates.
+  Only the fallback — for an env with no onboarding instance — needs a
+  second login (the validation env). If a server isn't logged in, the
+  command errors and suggests `dr login --server <S>`.
+- **`--server` selects both the onboarding host and the identity.** On the
+  `dr validate onboarding` commands, `--server <ENV>` targets that env's
+  onboarding host using that env's JWT. The host is derived from the
+  server registry, so **every registry env is supported and there is no
+  list to check** — just pass the env you want. Never hand-build the host
+  yourself; the subdomain is not always the lowercased key, and the CLI
+  already knows the difference. Only a custom `--server` URL can't be
+  derived — use the override below for those.
+- **`DR_VALIDATE_ONBOARDING_HOST` overrides the host only** — you still
+  pass a real, logged-in `--server`, which keeps supplying the identity.
+  It takes a **literal, absolute URL including the scheme** — e.g.
+  `DR_VALIDATE_ONBOARDING_HOST=http://localhost:8000` for a local
+  instance. A bare hostname builds an invalid request URL. Point it at a
+  local/CI instance, a custom `--server` URL's pod, or an instance that
+  isn't in the registry yet.
+
+  You rarely need this for a normal env — derivation already handles those.
+  Don't hand-build a URL by substituting a key into a template: the
+  subdomain isn't always the key, and an env with no instance has nothing
+  to point at either way. Confirm a candidate first:
+  `curl -sf "$DR_VALIDATE_ONBOARDING_HOST/openapi.json" | head -c 80`.
+
+  **Match `--server` to the host you override to.** The override moves the
+  data URL only; the JWT still comes from `--server`. Pointing the override
+  at another env's pod while leaving `--server` on the client's env
+  forwards that client's token there — a production key with the override
+  aimed at a non-production pod hands that pod a live production JWT. Log
+  in to the env that owns the override host and pass *that* key.
+
+  **Only ever point this at a host you trust.** The CLI attaches your live
+  Bearer JWT to whatever absolute URL it is given, and does not validate
+  the override beyond trimming trailing slashes — so a typo'd or
+  attacker-supplied value sends a working token to that host. Reachability
+  is not trust: `/openapi.json` answering proves the pod is up, not that it
+  is ours.
+
+## Standard command sequence
+
+Run the steps in order. Capture the session id from step 1 and reuse it.
+`--server` must name the env whose onboarding instance you are actually
+hitting — normally the **client's own env** (add `--account <email>` if the
+operator has multiple identities stored).
+
+**If you are on the fallback path** — validating somewhere other than the
+client's env, whether by choice or via `DR_VALIDATE_ONBOARDING_HOST` — set
+`SERVER` to that *validation* env instead. The JWT follows `--server`, so
+leaving it on the client's env sends the client's live token to the host you
+redirected to.
+
+```bash
+# The env whose onboarding instance you're hitting. Normally the client's
+# own env (one login). On the fallback path, set this to the VALIDATION
+# env instead — the JWT follows it. Substitute your env.
+SERVER=US
+
+# 1. Create a session — prints just the session_id on stdout.
+SID=$(dr validate onboarding session create --server "$SERVER")
+
+# 2. Gather the files, then upload them all in one call (repeat --file).
+#    - the customer's own report (operator-supplied)
+#    - the Datarails report, CoA, GL/transactions, and (for BS) the
+#      trial balance, fetched from the client's env via dr-cli
+#    The service classifies each file's role automatically.
+dr validate onboarding files upload "$SID" --server "$SERVER" \
+  --file "/path/to/customer_report.xlsx" \
+  --file "/path/to/datarails_report.xlsx" \
+  --file "/path/to/coa.xlsx" \
+  --file "/path/to/gl.xlsx"
+
+# 3. Kick off reconcile + investigation. Returns in <1s with
+#    status="started"; the work continues server-side. Infer
+#    --report-type from the request; omit --period (the agent infers it).
+# Note: --report-type "P&L" must be quoted — unquoted `&` would
+# background the command in bash. "BS" is safe either way.
+dr validate onboarding reconcile "$SID" --server "$SERVER" --report-type "P&L"
+
+# 4. Poll every ~30 seconds. Investigation can take up to ~20 minutes.
+dr validate onboarding status "$SID" --server "$SERVER"
+
+# 5. Once status shows "investigation: complete", fetch the final report.
+dr validate onboarding result "$SID" --server "$SERVER"
+```
+
+## Polling loop pattern
+
+Keep polling until the synthesized top-level `status` reaches a
+terminal state. The `--json` output exposes a `status` field that
+collapses both pipeline stages into one of `pending` / `running` /
+`complete` / `failed` — match against that, not against
+`investigation_status` alone, or the loop hangs forever on failure.
+
+```bash
+until dr validate onboarding status "$SID" --server "$SERVER" --json \
+  | grep -qE '"status": "(complete|failed)"'; do
+  sleep 30
+done
+```
+
+After the loop exits, inspect the terminal state before fetching the
+result. If `status` is `failed`, surface the failure explicitly — do
+**not** blindly run `result` and pretend the investigation succeeded.
+Use `result "$SID" --reconcile` to fall back to the raw reconcile-only
+report, or read the error string out of `status "$SID" --json` and
+report it to the operator.
+
+```bash
+TERMINAL=$(dr validate onboarding status "$SID" --server "$SERVER" --json \
+  | grep -oE '"status": "[^"]+"' | cut -d'"' -f4)
+if [ "$TERMINAL" = "complete" ]; then
+  dr validate onboarding result "$SID" --server "$SERVER"
+else
+  # investigation failed — surface the error and offer the reconcile fallback
+  dr validate onboarding status "$SID" --server "$SERVER" --json
+  dr validate onboarding result "$SID" --server "$SERVER" --reconcile
+fi
+```
+
+Acceptable terminal states are `complete` and `failed`. Anything else
+(`pending` / `running`) means keep polling.
+
+## Output interpretation
+
+Default `result` output is a concise markdown report with two sections:
+
+1. **Resolved discrepancies** — annotated reconcile lines with the
+   investigator's verdict (root cause) and the recommended CSM action.
+2. **Unresolved discrepancies** — lines the investigator couldn't
+   confidently explain. The CSM owns the next step on these.
+
+Representative root-cause categories you'll see (not exhaustive):
+
+| Category | Meaning |
+|---|---|
+| aggregation / mapping error | DR rolls accounts up differently than the customer (e.g. a sub-account included on one side). Fix the mapping. |
+| sign convention | Customer uses negative expenses, DR uses positive (or vice versa). Flip the sign rule. |
+| missing ERP data / partial integration | A GL account exists on one side and not the other. Likely an integration gap. |
+| rounding | Sub-cent or sub-dollar diff. Usually safe to ignore. |
+| manual adjustment / formula override | The customer file has a hardcoded value or formula override the GL doesn't reflect. Surface to the customer. |
+| currency conversion | FX applied differently between the two sides. |
+
+Flags to know:
+
+- `--json` — emits the full structured payload (use for programmatic
+  inspection, downstream filtering, or when you want every per-line
+  flag the report writer captured).
+- `--reconcile` — falls back to the raw reconcile-only output. Use this
+  only when investigation failed (`investigation: failed` from status);
+  otherwise prefer the default (investigation has strictly more info).
+
+## Generate the HTML report (final step)
+
+Once `status` is `complete` and you've fetched `result`, render the branded HTML
+report and show it to the operator. The CLI owns every number and all structure;
+you (the agent) may enrich ONLY prose.
+
+1. Emit the faithful data block (numbers / structure / per-line detail):
+
+   ```bash
+   dr validate onboarding report "$SID" --server "$SERVER" \
+     --org "<client name>" \
+     [--client-report-name "…" --client-report-ref "Filebox <id> · v<n>"] \
+     [--dr-report-name "…" --dr-report-ref "Filebox <id> · v<n>"] \
+     --emit-data --out data.json
+   ```
+
+2. **(Optional)** Read `data.json` and write a prose overlay `prose.json` to
+   sharpen the wording:
+
+   ```json
+   { "rowProse": { "row-12": { "what": "One plain sentence about this gap." } },
+     "banner": "One-line tie-out narrative." }
+   ```
+
+   **Hard rule:** the overlay may contain ONLY `rowProse.<id>.what` and `banner`
+   — never a number and never any other field. Numbers are re-derived by the CLI
+   and cannot be changed from this file. Keep prose short; only `<strong>`,
+   `<em>`, and `<code>` tags survive sanitization.
+
+3. Render the HTML (pass `--prose` only if you wrote an overlay):
+
+   ```bash
+   dr validate onboarding report "$SID" --server "$SERVER" --org "<client name>" \
+     [--prose prose.json] --out report.html
+   ```
+
+4. Open `report.html` in the browser for the operator and print the path plus a
+   two-line summary (verdict + top action).
+
+Skipping step 2 is fine — step 3 without `--prose` still produces a correct
+report with templated prose. Notes: the tie-out card + headline verdict are
+derived for **both** P&L (does Net Income tie) and Balance Sheet (assets = L+E);
+grouped rows show member line names + the aggregate (the service does not expose
+per-line amounts for a grouped match, and there are no section dividers);
+`--from-json <result.json>` renders offline from a saved `result --json` payload.
+
+## Common pitfalls + recovery
+
+| Symptom | Fix |
+|---|---|
+| `error: not logged in: <SERVER>:<email> …` / an HTTP 401 | Operator's keychain JWT expired or missing. Run `dr login --server <S>`, then retry. |
+| `error: no known onboarding host for server "<X>"` | `<X>` is a custom `--server` URL, which has no registry subdomain to derive a host from. Set `DR_VALIDATE_ONBOARDING_HOST` to that instance's absolute URL and retry (still pass a real, logged-in `--server`). Registry env keys never hit this. |
+| `error: could not reach ...` / a DNS failure | Either a network/DNS/VPN problem, or that env genuinely has no onboarding instance deployed (mostly internal test envs). A name that doesn't resolve fails *before* any request is made, so no token was transmitted. Validate on an env that does have one, noting that this uploads the files to that env (see the fallback caveat above). |
+| a 404 on **every** call (not just after creating a session) | The host resolved and answered — so the request, and the Bearer JWT on it, did reach whatever is at that address. Usually `DR_VALIDATE_ONBOARDING_HOST` pointing at something that isn't an onboarding instance. Fix the target; and if it wasn't a host you trust, treat that token as exposed and re-login to rotate it. |
+| `error: HTTP 404` after creating a session | Session ids TTL after 24h, and a server restart can drop them. Create a new session and re-upload the files. |
+| `error: HTTP 404` from `result` (not `status`) | The investigation hasn't started yet. Poll `status` until it reports complete, then fetch `result` — don't call `result` before reconcile + investigation finish. |
+| `error: … 400 … no files uploaded for this session` | The session has no files — usually `reconcile` ran before `files upload`, but a dropped session or an all-rejected upload triggers it too. Upload the files (at minimum the customer's own report) first. |
+| `investigation: failed` in status | The investigation agent hit an unrecoverable error. Use `result "$SID" --reconcile` for the raw reconcile-only report, or inspect the error via `status "$SID" --json`. |
+| `reconcile: failed` in status | The reconcile pipeline itself blew up — usually a malformed input file or a server-side bug. Surface the error from `status --json` to engineering. |
+| Result blames a "missing" file that you didn't upload | Expected — some files are recommended, not required (e.g. GL, trial balance). If the finding needs one, fetch it via dr-cli and re-upload before re-running. |
+| Multiple dr-cli identities in the keychain | Add `--account user@datarails.com` (alongside `--server`) on each command to pin which identity to use. |
+
+## What NOT to do
+
+- **Don't tag files by role.** There is no `--pnl`/`--coa`/`--gl` flag —
+  upload with `--file` and let the service classify. Trying to force
+  roles is both impossible and unnecessary.
+- **Don't ask the operator for the Datarails-side files.** Only the
+  customer's own report is operator-supplied; fetch the rest via dr-cli.
+- **Don't ask for the period.** It's inferred. Only pass `--period` if
+  the operator volunteered one.
+- **Don't re-run `reconcile` on a completed session.** Check status
+  first. Re-running on a `complete` session does nothing useful; on a
+  `running` session it short-circuits with `already_running`.
+- **Don't delete a session before fetching the result.** `session
+  delete` is destructive — the investigation report is gone with it.
+- **Don't pass file paths the CLI can't read.** Uploaded paths must
+  resolve on the operator's local machine.
+- **Don't expect reconcile to be synchronous.** It returns in <1s with
+  `status="started"`. The actual work runs in the background and is
+  observed only via `status` / `result`.
+- **Don't paste JWTs or `Authorization` headers into chat.** The CLI
+  pulls the token from the OS keychain by design; the operator never
+  needs to see it and neither does Claude.
+
+## Quick reference — all 8 commands
+
+| Command | What it does |
+|---|---|
+| `dr validate onboarding session create` | Create a session; prints the new id on stdout. |
+| `dr validate onboarding session get SID [--json]` | Fetch one session's full state. |
+| `dr validate onboarding session delete SID` | Destroy a session (and its in-server state). Two-step: first run prints a `--confirm-token`; re-run with it to actually delete. |
+| `dr validate onboarding files upload SID --file P [--file P ...]` | Upload one or more files in a single multipart call. The service classifies each file's role automatically. |
+| `dr validate onboarding reconcile SID --report-type <"P&L"\|"BS"> [--period STR] [--csm-notes STR]` | Fast-return kickoff; reconcile + investigation run in background. Quote `"P&L"` in shells (bash treats `&` as backgrounding). `--period` is optional. |
+| `dr validate onboarding status SID [--json]` | Poll reconcile + investigation status; one line by default. `--json` adds the synthesized top-level `status`. |
+| `dr validate onboarding result SID [--json] [--reconcile]` | Fetch the final investigation report (or raw reconcile with `--reconcile`). |
+| `dr validate onboarding report SID [--emit-data] [--prose P] [--out P] [--org NAME] [--from-json P]` | Render the investigation result as a self-contained HTML report (or `--emit-data` for the raw data block the agent enriches). |
+
+Per-command flags (dr-cli convention): `--server <KEY>` selects the
+identity **and** the env's onboarding host; `--account <email>` pins the
+email when several identities are stored. `DR_VALIDATE_ONBOARDING_HOST`
+overrides the host (only) when you need it.
+
+## Guard rails
+
+- **Read-and-write.** `session create / delete` and `files upload` are
+  writes; treat them with the same care as any `dr` write command.
+- **Never read or surface tokens.** The JWT lives in the OS keychain;
+  Claude should never paste it back.
+- **Always use `--json` when parsing.** Default output is human-friendly
+  but not parser-friendly; pass `--json` and read structured fields
+  instead of regex-ing the table.
+- **One session per validation.** Don't reuse a session id across
+  unrelated client validations — create a fresh session each time.
+
+## Related skills
+
+- `~/.claude/skills/dr-cli/SKILL.md` — the broader dr-cli surface. Use it
+  to **fetch the Datarails-side files** (Datarails report, CoA,
+  GL/transactions, trial balance) from the client's fileboxes before
+  uploading, and for the shared keychain auth this skill piggybacks on.
+- `~/.claude/skills/dr-switch-user/SKILL.md` — switch the active
+  dr-cli identity if the operator has multiple emails saved.