jaz-clio 5.55.15 → 5.56.0

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 5.55.15
+version: 5.56.0
 description: >-
   Use this skill whenever you call, debug, or review code that touches the Jaz
   REST API. Covers field names, response shapes, 159 production gotchas, error
@@ -192,6 +192,7 @@ The rest of this skill — field names, gotchas, error catalog, dependency order
 ### Jaz Magic — Extraction & Autofill
 57. **When the user starts from an attachment, always use Jaz Magic** — if the input is a PDF, JPG, or any document image (invoice, bill, receipt), the correct path is `POST /magic/createBusinessTransactionFromAttachment`. Do NOT manually construct a `POST /invoices` or `POST /bills` payload from an attachment — Jaz Magic handles the entire extraction-and-autofill pipeline server-side: OCR, line item detection, contact matching, CoA auto-mapping via ML learning, and draft creation with all fields pre-filled. Only use `POST /invoices` or `POST /bills` when building transactions from structured data (JSON, CSV, database rows) where the fields are already known. If you hold the invoice/bill as raw HTML (e.g. an email body), pass it via `sourceType: "HTML"` with an `html` field — the backend renders it to a PDF then extracts, so you do NOT need to save it to a file first.
 58. **Three upload modes with different content types** — `sourceType: "FILE"` requires **multipart/form-data** with `sourceFile` blob (JSON body fails with 400 "sourceFile is a required field"). `sourceType: "URL"` accepts **application/json** with `sourceURL` string. `sourceType: "HTML"` accepts the raw HTML body in an `html` field (JSON or multipart) — the backend renders it to a PDF, then extracts (use this for an email body you already hold; no file needed). The OAS only documents URL mode — FILE and HTML modes are undocumented there.
+58a. **The server FETCHES the source — a local path is not a source at any spelling** — in URL mode `sourceURL` is opened by the Jaz server, so it must be reachable from the public internet; in FILE mode you send the bytes yourself as a multipart blob. A path on the calling machine (`/mnt/user-data/uploads/x.zip`, `/tmp/invoice.pdf`) is neither: it is not a URL the server can open, and putting it in `sourceURL` — or in an MCP `file.download_url`, which the HOST populates and a caller must never author — fails after a round-trip with no indication that re-spelling the path is hopeless. Same rule for `classify_documents`: its `source` is fetched server-side, and a local folder/zip path is accepted only when the client is running on the caller's own machine. When you hold bytes but no shareable URL, switch to FILE mode, upload in the dashboard and pass the `attachmentId`, or ask for a Dropbox/Drive/OneDrive share link — do not retry the path.
 59. **Three required fields + one optional**: the source (`sourceFile` multipart blob — NOT `file` — for FILE, `sourceURL` for URL, or `html` for HTML), `businessTransactionType` (`"INVOICE"`, `"BILL"`, `"CUSTOMER_CREDIT_NOTE"`, or `"SUPPLIER_CREDIT_NOTE"` — `EXPENSE` rejected), `sourceType` (`"FILE"`, `"URL"`, or `"HTML"`). For HTML mode, `html` is the raw HTML string (max 5 MB). Optional: `uploadMode` (`"SEPARATE"` default, or `"MERGED"` for a single PDF containing multiple documents — the backend splits it via boundary detection before extraction). All required fields are validated server-side. **CRITICAL: multipart form field names are camelCase** — `businessTransactionType`, `sourceType`, `sourceFile`, `uploadMode`, NOT snake_case. Using `business_transaction_type` returns 422 "businessTransactionType is a required field". The File blob must include a filename and correct MIME type (e.g. `application/pdf`, `image/jpeg`) — bare `application/octet-stream` blobs are rejected with 400 "Invalid file type".
 59a. **MERGED upload workflow tracking** — When `uploadMode: "MERGED"`, the upload response `workflowResourceId` is a **parent** tracking ID. The backend splits the PDF, then creates **child** workflows for each split page — these child IDs appear in `POST /magic/workflows/search` (by fileName or createdAt), NOT the parent ID. To track MERGED progress, search by `fileName` rather than the parent `workflowResourceId`.
 60. **Response maps transaction types**: Request `INVOICE` → response `SALE`. Request `BILL` → response `PURCHASE`. Request `CUSTOMER_CREDIT_NOTE` → response `SALE_CREDIT_NOTE`. Request `SUPPLIER_CREDIT_NOTE` → response `PURCHASE_CREDIT_NOTE`. S3 paths follow the response type. The response `validFiles[]` array contains `workflowResourceId` for tracking extraction progress via `POST /magic/workflows/search`.

package/assets/skills/api/references/errors.md

@@ -628,6 +628,24 @@ account. Full model: SKILL.md Rule 47a, `endpoints.md` → Deposits, `feature-gl
 
 ---
 
+## Jaz Magic / Document-Source Errors
+
+### A local path silently fails at every spelling
+**Cause**: Treating `sourceURL` (or an MCP `file.download_url`, or `classify_documents`'s `source`) as somewhere to put a path on the calling machine — `/mnt/user-data/uploads/Archive.zip`, `/tmp/invoice.pdf`, `C:\Users\...`. The server FETCHES the source; it does not receive bytes through these fields. A path visible only to the caller is not a URL the server can open, so it fails no matter how it is written.
+**Note**: This is the same class as the inventory-adjustment endpoints — the thing being reached for does not exist at any spelling, so re-spelling never helps. Four consecutive re-tries of the same path in different shapes is the signature.
+**Fix**: Pick a route that actually delivers the bytes or a reachable address:
+- **FILE mode** — send the bytes yourself: `sourceType: "FILE"` with a `sourceFile` multipart blob (see Rule 58/59).
+- **attachmentId** — upload in the Jaz dashboard first, then reference it.
+- **Share link** — Dropbox / Google Drive / OneDrive, or any public https URL.
+- **Attach it to the conversation** — on MCP surfaces the host then populates `file` itself. Never author that object by hand.
+- **Local folder or `.zip`** — valid for `classify_documents` ONLY when the client is running on the caller's own machine, not on a hosted server.
+
+### "The file reference has no fetchable https download_url"
+**Cause**: A `file` object was constructed by the caller rather than supplied by the host, usually with a sandbox path in `download_url`.
+**Fix**: Omit `file` entirely when the user attached nothing, and pass `sourceUrl` or `attachmentId` instead. `file` is host-populated; there is no way to synthesize one.
+
+---
+
 ## Journal Errors
 
 ### Multi-currency journals — `currency` object

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 5.55.15
+version: 5.56.0
 description: >-
   Use this skill when running Clio CLI commands, building shell scripts with
   Clio, debugging auth issues, understanding --json output, paginating results,

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 5.55.15
+version: 5.56.0
 description: >-
   Use this skill when migrating accounting data into Jaz — importing from Xero,
   QuickBooks, Sage, MYOB, or Excel exports. Covers the full conversion pipeline:

package/assets/skills/jaz-kit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-kit
-version: 5.55.15
+version: 5.56.0
 description: >-
   Use this skill when an accountant, bookkeeper, or owner is running real books
   in Jaz across one or more organizations from the terminal — setting up a

package/assets/skills/jaz-pseudo-sql/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-pseudo-sql
-version: 5.55.15
+version: 5.56.0
 description: >-
   Use this skill when answering ad-hoc data questions that aren't covered by
   download_export (canonical reports — anomaly, audit, aging, P&L, BS, GL,

package/assets/skills/jobs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-jobs
-version: 5.55.15
+version: 5.56.0
 description: >-
   Use this skill for recurring accounting workflows — month/quarter/year-end
   close, bank reconciliation, GST/VAT filing, payment runs, credit control,

package/assets/skills/transaction-recipes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-recipes
-version: 5.55.15
+version: 5.56.0
 description: >-
   Use this skill when modeling complex multi-step accounting transactions —
   anything that spans multiple periods, involves changing amounts, or requires