jaz-clio 5.66.0 → 5.68.0

package/README.md

@@ -3,13 +3,13 @@
 <p align="center">
   <a href="https://www.npmjs.com/package/jaz-clio"><img src="https://img.shields.io/npm/v/jaz-clio?style=for-the-badge&logo=npm" alt="npm"></a>
   <a href="https://www.npmjs.com/package/jaz-clio"><img src="https://img.shields.io/npm/dm/jaz-clio?style=for-the-badge&label=downloads" alt="npm downloads"></a>
-  <img src="https://img.shields.io/badge/tools-371-blue?style=for-the-badge" alt="371 tools">
+  <img src="https://img.shields.io/badge/tools-379-blue?style=for-the-badge" alt="379 tools">
   <a href="https://github.com/teamtinvio/jaz-ai/blob/main/LICENSE"><img src="https://img.shields.io/github/license/teamtinvio/jaz-ai?style=for-the-badge&color=green" alt="License"></a>
 </p>
 
 <p align="center"><b>Jaz accounting on the command line, and inside any AI agent.</b></p>
 
-371 tools · 73 command groups · 7 skills · 13 calculators · 12 close playbooks · 159 field-tested API rules.
+379 tools · 74 command groups · 7 skills · 13 calculators · 12 close playbooks · 159 field-tested API rules.
 
 ```bash
 npm install -g jaz-clio
@@ -51,7 +51,7 @@ clio invoices search --query 'status:unpaid AND $500+' # structured per-entity s
 clio ledger-find-fix preview --level TRANSACTIONS --input recode.json  # find & fix (recode) across record types
 ```
 
-73 command groups, 16 report types, 13 calculators, 12 job playbooks. Every command takes `--json`. Run `clio --help` for the full list.
+74 command groups, 16 report types, 13 calculators, 12 job playbooks. Every command takes `--json`. Run `clio --help` for the full list.
 
 ### Foreign currency
 
@@ -78,7 +78,7 @@ that ends up in a journal.
 
 ## MCP server
 
-371 tools for any AI agent that speaks MCP. Runs locally: no cloud, no ports.
+379 tools for any AI agent that speaks MCP. Runs locally: no cloud, no ports.
 
 > **No install at all?** Claude.ai, ChatGPT, Cowork, and Microsoft Copilot Studio can use Jaz through the hosted connector. Add `https://mcp.jaz.ai/mcp` as a custom connector and sign in with OAuth, no key. The local setup below is for terminal use, scripting, and editors that run MCP servers as local processes.
 

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 5.66.0
+version: 5.68.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,13 +192,13 @@ 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".
+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 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"`, `"SUPPLIER_CREDIT_NOTE"`, `"SALE_QUOTE"`, `"SALE_ORDER"`, `"PURCHASE_REQUEST"`, or `"PURCHASE_ORDER"`; `EXPENSE` rejected; a quote/request lands DRAFT, an order lands PENDING until the order update's `isPendingToActive*` flag), `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; refused for the four quote/order/request types) and `internalNotes` (max 3000 characters, set on the created record). Max 10 MB per file. 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`.
 61. **Extraction is asynchronous** — the API response is immediate (file upload confirmation only). The actual Magic pipeline — OCR, line item extraction, contact matching, CoA learning, and autofill — runs asynchronously. Use `POST /magic/workflows/search` with `filter.resourceId.eq: "<workflowResourceId>"` to check status (SUBMITTED → PROCESSING → COMPLETED/FAILED). When COMPLETED, `businessTransactionDetails.businessTransactionResourceId` contains the created draft BT ID. The `subscriptionFBPath` in the response is a Firebase Realtime Database path for real-time status updates (alternative to polling).
 62. **Accepts PDF and JPG/JPEG** — both file types confirmed working. Handwritten documents are accepted at upload stage (extraction quality varies). `fileType` in response reflects actual format: `"PDF"`, `"JPEG"`.
-63. **Workflow search tracks all magic uploads** — `POST /magic/workflows/search` searches across BT extractions AND bank statement imports. Filter by `resourceId` (eq), `documentType` (SALE, PURCHASE, SALE_CREDIT_NOTE, PURCHASE_CREDIT_NOTE, BANK_STATEMENT), `status` (SUBMITTED, PROCESSING, COMPLETED, FAILED), `fileName` (contains), `fileType`, `createdAt` (date range). Response: paginated `MagicWorkflowItem` with `businessTransactionDetails.businessTransactionResourceId` (the draft BT ID when COMPLETED) or `bankStatementDetails` (for bank imports). Standard search sort: `{ sortBy: ["createdAt"], order: "DESC" }`.
+63. **Workflow search tracks all magic uploads**: `POST /magic/workflows/search` searches across BT extractions AND bank statement imports. Filter by `resourceId` (eq), `documentType` (SALE, PURCHASE, SALE_CREDIT_NOTE, PURCHASE_CREDIT_NOTE, SALE_QUOTE, SALE_ORDER, PURCHASE_REQUEST, PURCHASE_ORDER, BANK_STATEMENT), `status` (SUBMITTED, PROCESSING, COMPLETED, FAILED), `fileName` (contains), `fileType`, `createdAt` (date range). Response: paginated `MagicWorkflowItem` with `businessTransactionDetails.businessTransactionResourceId` (the draft BT ID when COMPLETED) or `bankStatementDetails` (for bank imports). Standard search sort: `{ sortBy: ["createdAt"], order: "DESC" }`.
 
 ### Cashflow & Unified Ledger
 64. **Four ways to read payments — pick by scope.** `GET /payments` (list) and `POST /payments/search` do NOT exist and never did. What does exist: (a) **per-payment CRUD** — `GET/PUT/DELETE /payments/:resourceId`; (b) **payment-scoped search** — `POST /sales/payments/search` and `POST /purchases/payments/search` (added 2026-08-13), one side of the ledger each, plus `POST /batch-payments/search` for batches; (c) **cross-entity ledger** — `POST /cashflow-transactions/search`, the unified transaction ledger spanning invoices, bills, credit notes, journals, cash entries and payments. Filter it by `businessTransactionType` (e.g. `SALE`, `PURCHASE`) and `direction` (`PAYIN`, `PAYOUT`). Response dates are epoch milliseconds. **Naming trap**: the `search_payments` tool is a wrapper over `/cashflow-transactions/search`, NOT over the sales/purchases payment searches — its name is narrower than what it calls. Reach the per-side searches with a raw request; they have no tool. (d) **Per-document settlements** — `GET /invoices/:id/payments` and `GET /bills/:id/payments`, and for credit notes `GET /customer-credit-notes/:id/refunds` / `GET /supplier-credit-notes/:id/refunds` (the domain distinguishes a refund from a payment; a journal has neither). This is the right call for **one known document's own settlements** and the one to reach for first — no filter to get wrong. All four answer `{ data: [...] }` (measured raw 2026-09-07). It is listed here because it was missing from this rule while (c) sat one line away, and `get_transaction_summary` consequently filtered the ledger by `businessTransactionResourceId` — a field `TransactionsFilter` does not declare — for its entire life, 400ing on every call behind a silent catch.

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

@@ -1141,6 +1141,14 @@ Processing is **asynchronous** — the API response confirms file upload immedia
 - `BILL` → creates a draft purchase (response type: `PURCHASE`)
 - `CUSTOMER_CREDIT_NOTE` → creates a draft customer CN (response type: `SALE_CREDIT_NOTE`)
 - `SUPPLIER_CREDIT_NOTE` → creates a draft supplier CN (response type: `PURCHASE_CREDIT_NOTE`)
+- `SALE_QUOTE` → creates a DRAFT sale quote (response type: `SALE_QUOTE`); issue it with `isDraftToActiveSaleQuote`
+- `SALE_ORDER` → creates a PENDING sale order (response type: `SALE_ORDER`); take it live with `isPendingToActiveSaleOrder`
+- `PURCHASE_REQUEST` → creates a DRAFT purchase request (response type: `PURCHASE_REQUEST`); issue it with `isDraftToActivePurchaseRequest`
+- `PURCHASE_ORDER` → creates a PENDING purchase order (response type: `PURCHASE_ORDER`); take it live with `isPendingToActivePurchaseOrder`
+
+A PENDING order is on the dashboard's For Review tab, not in the live order lists. Activate it with the order update (`PUT /sale-orders/:id` / `PUT /purchase-orders/:id`); if that call sends `lineItems`, send every stored line with its `resourceId`.
+
+Optional `internalNotes` (max 3000 characters) is set on the created record, e.g. a tag to find an automated upload again. Optional `uploadMode: "MERGED"` splits one PDF into several documents; it is refused (`MAGIC_MERGED_UPLOAD_NOT_SUPPORTED`) for the four quote/order/request types.
 
 **Three modes** — content type depends on `sourceType`:
 
@@ -1152,8 +1160,9 @@ Content-Type: multipart/form-data
 
 Fields:
   - sourceFile: PDF or JPG file blob (NOT "file")
-  - businessTransactionType: "INVOICE", "BILL", "CUSTOMER_CREDIT_NOTE", or "SUPPLIER_CREDIT_NOTE"
+  - businessTransactionType: "INVOICE", "BILL", "CUSTOMER_CREDIT_NOTE", "SUPPLIER_CREDIT_NOTE", "SALE_QUOTE", "SALE_ORDER", "PURCHASE_REQUEST", or "PURCHASE_ORDER"
   - sourceType: "FILE"
+  - internalNotes: optional, max 3000 characters
 ```
 
 ```json
@@ -1230,13 +1239,14 @@ Content-Type: application/json
 
 **Key gotchas:**
 - `sourceFile` is the field name (NOT `file`) — same pattern as bank statement endpoint
-- `EXPENSE` returns 422 — use one of the 4 valid types above
-- Response maps types: `INVOICE` → `SALE`, `BILL` → `PURCHASE`, `CUSTOMER_CREDIT_NOTE` → `SALE_CREDIT_NOTE`, `SUPPLIER_CREDIT_NOTE` → `PURCHASE_CREDIT_NOTE`
+- `EXPENSE` returns 422: use one of the 8 valid types above
+- Response maps types: `INVOICE` → `SALE`, `BILL` → `PURCHASE`, `CUSTOMER_CREDIT_NOTE` → `SALE_CREDIT_NOTE`, `SUPPLIER_CREDIT_NOTE` → `PURCHASE_CREDIT_NOTE`; the four quote/order/request types keep their names
+- There is no attachment-id source: the sources are `sourceFile`, `sourceURL` and `html` only
 - JSON body with `sourceType: "FILE"` always fails (400) — MUST use multipart
 - `workflowResourceId` in `validFiles[]` is for tracking via `POST /magic/workflows/search`
 - `subscriptionFBPath` is the Firebase path for real-time status updates
 - All three fields (the source — `sourceFile`/`sourceURL`/`html` — plus `businessTransactionType` and `sourceType`) are required — omitting any returns 422
-- File types confirmed: PDF, JPG/JPEG, PNG, HEIC, XLS, XLSX, EML (max 1 MB). HTML mode (`sourceType: "HTML"`) takes the raw HTML body instead of a file (max 5 MB); an `.eml` file is still FILE mode, not HTML mode.
+- File types confirmed: PDF, JPG/JPEG, PNG, HEIC, XLS, XLSX, EML (max 10 MB). HTML mode (`sourceType: "HTML"`) takes the raw HTML body instead of a file (max 5 MB); an `.eml` file is still FILE mode, not HTML mode.
 
 ---
 
@@ -1287,7 +1297,7 @@ Content-Type: application/json
 
 **Filter fields:**
 - `resourceId`: StringExpression (eq, contains) — workflow ID from magic create response
-- `documentType`: Array — SALE, PURCHASE, SALE_CREDIT_NOTE, PURCHASE_CREDIT_NOTE, BANK_STATEMENT
+- `documentType`: Array: SALE, PURCHASE, SALE_CREDIT_NOTE, PURCHASE_CREDIT_NOTE, SALE_QUOTE, SALE_ORDER, PURCHASE_REQUEST, PURCHASE_ORDER, BANK_STATEMENT
 - `status`: Array — SUBMITTED, PROCESSING, COMPLETED, FAILED
 - `fileName`: StringExpression — original uploaded filename
 - `fileType`: Array — PDF, PNG, JPEG, JPG, HEIC, CSV, XLS, XLSX, EML
@@ -1297,7 +1307,7 @@ Content-Type: application/json
 1. Upload via `POST /magic/createBusinessTransactionFromAttachment` → get `workflowResourceId`
 2. Search with `filter.resourceId.eq` → check `status`
 3. When `COMPLETED` → read `businessTransactionDetails.businessTransactionResourceId`
-4. Use the BT resource ID with `GET /invoices/:id`, `GET /bills/:id`, `GET /customer-credit-notes/:id`, or `GET /supplier-credit-notes/:id`
+4. Use the BT resource ID with `GET /invoices/:id`, `GET /bills/:id`, `GET /customer-credit-notes/:id`, `GET /supplier-credit-notes/:id`, or the matching quote/order/request GET
 
 
 ---
@@ -1319,6 +1329,8 @@ Fields:
   - sourceType: "FILE" (valid values: URL, FILE)
 ```
 
+Max 10 MB per file. There is no attachment-id source.
+
 CSV format: `Date,Description,Debit,Credit` — maps to Date, Description, Cash-out, Cash-in.
 
 Multipart import is the more reliable method. Use it when JSON POST returns errors.
@@ -2746,6 +2758,68 @@ Searches rules. Filter fields: `name`, `resourceId`, `actionType`, `appliesToRec
 
 **There is no filter on `searchFilter`**, so "which of my rules have no condition" cannot be asked server-side — list the rules and check the field client-side.
 
+
+## 27. Unapplied Payments
+
+Cash received (or paid) before anyone says what it pays for. Stored as a payment batch, so there is **no GET**: read it back through `POST /api/v1/batch-payments/search` with `"origin": ["UNAPPLIED"]` (a sibling of `filter`; the search defaults to `ALL`, which mixes ordinary batches in). Each row carries `hash`, `unappliedStatus` (`DRAFT` / `UNAPPLIED` / `APPLIED`), `consumedAmount` and `unappliedBalance`.
+
+Rules that hold on every route below:
+- **Every write after the create takes `hash`** (optimistic lock), from the search row or the previous write's response. A stale hash is refused (422 `INVALID_CHECK_SUM`). Writes that return the record return its new hash; delete and unbatch return only `{ resourceId }`.
+- **`totalAmount` is the cash that arrived; attributions consume it** (`unappliedBalance = totalAmount - consumedAmount`). On an ordinary batch the total is the sum of its records instead.
+- **Using up the balance converts the record into an ordinary batch payment, one-way** (attributions or attach). The response cannot say so (it has no `origin`): detect it from `unappliedBalance` reaching 0. Its `origin` becomes `BATCH`, so the `UNAPPLIED` search no longer returns it: a record missing from that search may have become a batch payment, so check the batch-payment search with `origin` `BATCH` or `ALL` before concluding it is gone.
+- `paymentMethod` is the same 11-value enum as payments; lowercase or unknown values are 422.
+- Not idempotent. Clio sends every one of these once and reports a lost answer as UNCONFIRMED with the read-back, never as success.
+
+### POST /api/v1/unapplied-payments
+
+```json
+{ "businessTransactionType": "SALE", "organizationAccountResourceId": "<bank-uuid>", "paymentMethod": "BANK_TRANSFER",
+  "amount": 500, "valueDate": "2026-09-23", "currencyCode": "SGD", "contactResourceId": "<contact-uuid>",
+  "reference": "DEP-1", "saveAsDraft": true }
+```
+
+Required: `businessTransactionType` (`SALE` received / `PURCHASE` paid), `organizationAccountResourceId`, `paymentMethod`, `amount` (> 0), `valueDate`, `currencyCode`. `rateToFunctional` is required for a foreign currency. `contactResourceId` is optional. `saveAsDraft: true` posts nothing until activate. Optional: `functionalCurrencyCode`, `externalReference`, `notes`, `customFields`, `attachments`.
+
+### PUT /api/v1/unapplied-payments/{resourceId}
+
+`hash` plus any of `reference`, `externalReference`, `notes`, `paymentMethod`, `amount`, `organizationAccountResourceId`, `valueDate`, `rateToFunctional`, `customFields`, `attachments`, `children`. Changing `amount`, the account or the date releases an existing bank match. There is no `currencyCode`: the currency follows the account, and a move to an account in another currency needs `amount` restated in the new currency (or it is refused `CONTAINER_CURRENCY_CHANGE_INCOMPLETE`) and `rateToFunctional` when that currency is not the organization's own. The agent tool does not expose `children`; send them with `clio unapplied-payments update <id> --hash <hash> --input body.json`. `children` is a replacement list where a row LEFT OUT is KEPT: send `{ "resourceId": "<payment>", "deleted": true }` to remove one.
+
+### DELETE /api/v1/unapplied-payments/{resourceId}
+
+Body `{ "hash": "..." }` (a DELETE with a body). Deletes the record AND every payment record under it, so each document it settled is unpaid again, and reverses its unapplied remainder. **A reconciled record is not refused: its bank match is released and the delete proceeds**, leaving the bank record unreconciled. When `bankStatementEntryResourceId` is set, warn the user and confirm before deleting. Returns `{ resourceId }`.
+
+### POST /api/v1/unapplied-payments/{resourceId}/activate
+
+Body `{ "hash": "..." }`. Draft to active; the ledger entry posts here.
+
+### POST /api/v1/unapplied-payments/{resourceId}/attributions
+
+```json
+{ "hash": "...", "attributions": [ { "businessTransactionResourceId": "<invoice-uuid>", "businessTransactionType": "SALE", "amount": 200 } ] }
+```
+
+1-500 entries; `businessTransactionType` is `SALE`, `PURCHASE`, `SALE_CREDIT_NOTE` or `PURCHASE_CREDIT_NOTE`. Each creates a payment record on that document. Optional per entry: `transactionAmount` (document currency), `transactionFee`, `transactionFeeCollected`. **The fee shape differs from a payment record's fee**: `{ feeValue, feeType: "AMOUNT" | "PERCENTAGE", feeOrganizationAccountResourceId, taxVatProfileResourceId?, feeTaxVatApplicable?, feeDescription? }` (not `FLAT`, not `feeAccountResourceId`).
+
+### POST /api/v1/unapplied-payments/{resourceId}/payments
+
+Body `{ "hash": "...", "paymentResourceId": "<payment-uuid>" }`. Groups an EXISTING standalone payment under this record: the payment keeps its document, the balance falls, the total stays.
+
+### DELETE /api/v1/unapplied-payments/{resourceId}/children/{childResourceId}
+
+Body `{ "hash": "..." }`. Removes one child; its cash returns to the balance. The child's `childOrigin` decides the rest: `ATTRIBUTED` (created here) is deleted, `ATTACHED` (existed before) survives as a standalone payment.
+
+### POST /api/v1/unapplied-payments/{resourceId}/unbatch
+
+Body `{ "hash": "..." }`. Deletes the record but RELEASES its payment records as standalone payments, each keeping its document, and reverses its unapplied remainder. Refused while reconciled: unmatch first. Returns `{ resourceId }`.
+
+### POST /api/v1/reconciliations/unapplied-payment
+
+```json
+{ "bankStatementEntryResourceId": "<bse-uuid>", "unappliedPaymentDetails": { "paymentMethod": "BANK_TRANSFER", "contactResourceId": "<contact-uuid>" } }
+```
+
+Records an unapplied payment for the bank record and matches the two. Direction, account, currency, date and amount come from the bank record. `amount` is optional and, when sent, must EQUAL the bank record's amount (`TOTAL_RECONCILIATION_AMOUNT_MISMATCHED_WITH_STATEMENT_ENTRY_AMOUNT` otherwise); there is no partial match. `rateToFunctional` is required for a foreign-currency account. `amount` belongs INSIDE `unappliedPaymentDetails`: at the top level it is silently dropped. Returns `{ bankStatementEntryResourceId, status, reference, valueDate, unappliedPaymentResourceId }`.
+
 ---
 
-*Last updated: 2026-09-13 (added Bank Rules CRUD, section 26). Previous: 2026-07-11 — added Jots judgment journal, section 25. Previous: 2026-04-09 — Added: Contacts bulk-upsert (22), Background Jobs search (23), Export Records (24). 2026-03-13 — Payment record CRUD, nano-classifier, scheduler GET/PUT/DELETE.*
+*Last updated: 2026-09-23 (added Unapplied Payments, section 27). Previous: 2026-09-13 — added Bank Rules CRUD, section 26. Previous: 2026-07-11 — added Jots judgment journal, section 25. Previous: 2026-04-09 — Added: Contacts bulk-upsert (22), Background Jobs search (23), Export Records (24). 2026-03-13 — Payment record CRUD, nano-classifier, scheduler GET/PUT/DELETE.*

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

@@ -635,14 +635,13 @@ account. Full model: SKILL.md Rule 47a, `endpoints.md` → Deposits, `feature-gl
 **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.
+**Fix**: Omit `file` entirely when the user attached nothing, and pass `sourceUrl` instead (the Magic uploads have no attachment-id source). `file` is host-populated; there is no way to synthesize one.
 
 ---
 

package/assets/skills/api/references/full-api-surface.md

@@ -3,7 +3,7 @@
 > **The endpoints clio wraps — the REST surface is larger.** This file catalogues roughly 200
 > paths, organized by resource, including undocumented endpoints, magic AI features, admin
 > APIs, and advanced search/filter syntax. The committed OpenAPI spec (`spec/openapi.yaml`)
-> carries 454 paths / 371 operations and is the authoritative list; check it before concluding
+> carries 454 paths / 379 operations and is the authoritative list; check it before concluding
 > an endpoint does not exist. For request/response examples of core endpoints, see
 > endpoints.md.
 >
@@ -448,8 +448,8 @@ Body for all three: `{ items: [{btResourceId: "<uuid>", btType: "SALE|PURCHASE|S
 
 | Method | Path | Description |
 |--------|------|-------------|
-| POST | `/magic/createBusinessTransactionFromAttachment` | **Jaz Magic: Extraction & Autofill.** Upload PDF/JPG → full extraction pipeline (OCR, line items, contact matching, CoA ML learning) → draft transaction with all fields autofilled. Supports `INVOICE`, `BILL`, `CUSTOMER_CREDIT_NOTE`, `SUPPLIER_CREDIT_NOTE`. FILE mode = multipart (`sourceFile` blob), URL mode = JSON (`sourceURL`). Async — returns `workflowResourceId` for tracking via workflow search. Request maps: `INVOICE`→`SALE`, `BILL`→`PURCHASE`, `CUSTOMER_CREDIT_NOTE`→`SALE_CREDIT_NOTE`, `SUPPLIER_CREDIT_NOTE`→`PURCHASE_CREDIT_NOTE`. |
-| POST | `/magic/workflows/search` | **Workflow search.** Track magic upload status across BT extractions and bank imports. Filter by `resourceId`, `documentType` (SALE/PURCHASE/SALE_CREDIT_NOTE/PURCHASE_CREDIT_NOTE/BANK_STATEMENT), `status` (SUBMITTED/PROCESSING/COMPLETED/FAILED), `fileName`, `fileType`, `createdAt`. Response includes `businessTransactionDetails.businessTransactionResourceId` (the draft BT ID) when COMPLETED. |
+| POST | `/magic/createBusinessTransactionFromAttachment` | **Jaz Magic: Extraction & Autofill.** Upload PDF/JPG → full extraction pipeline (OCR, line items, contact matching, CoA ML learning) → draft transaction with all fields autofilled. Supports `INVOICE`, `BILL`, `CUSTOMER_CREDIT_NOTE`, `SUPPLIER_CREDIT_NOTE`, `SALE_QUOTE`, `SALE_ORDER`, `PURCHASE_REQUEST`, `PURCHASE_ORDER` (orders land PENDING). Max 10 MB; optional `internalNotes` (max 3000). FILE mode = multipart (`sourceFile` blob), URL mode = JSON (`sourceURL`). Async: returns `workflowResourceId` for tracking via workflow search. Request maps: `INVOICE`→`SALE`, `BILL`→`PURCHASE`, `CUSTOMER_CREDIT_NOTE`→`SALE_CREDIT_NOTE`, `SUPPLIER_CREDIT_NOTE`→`PURCHASE_CREDIT_NOTE`. |
+| POST | `/magic/workflows/search` | **Workflow search.** Track magic upload status across BT extractions and bank imports. Filter by `resourceId`, `documentType` (SALE/PURCHASE/SALE_CREDIT_NOTE/PURCHASE_CREDIT_NOTE/SALE_QUOTE/SALE_ORDER/PURCHASE_REQUEST/PURCHASE_ORDER/BANK_STATEMENT), `status` (SUBMITTED/PROCESSING/COMPLETED/FAILED), `fileName`, `fileType`, `createdAt`. Response includes `businessTransactionDetails.businessTransactionResourceId` (the draft BT ID) when COMPLETED. |
 | POST | `/magic/importBankStatementFromAttachment` | Convert bank statement → entries |
 
 ---

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 5.66.0
+version: 5.68.0
 description: >-
   Use this skill when running Clio CLI commands, building shell scripts with
   Clio, debugging auth issues, understanding --json output, paginating results,
@@ -8,7 +8,7 @@ description: >-
   precedence, output formats, entity resolution, and common workflow patterns.
   Also use when the user asks how to use clio, what commands are available, or
   how to automate accounting tasks from the command line. Covers all
-  73 command groups and 371 tools, including employee-expense claims.
+  74 command groups and 379 tools, including employee-expense claims.
 license: MIT
 compatibility: Requires Node.js >= 18.0.0. Install via npm install -g jaz-clio.
 ---
@@ -17,7 +17,7 @@ compatibility: Requires Node.js >= 18.0.0. Install via npm install -g jaz-clio.
 
 > **Audience note:** for power users and CI/automation. Load this skill only when you're scripting from a terminal, building shell pipelines, or debugging from `clio --json` output. For day-to-day accounting inside Claude Desktop / Cowork, the MCP tools cover the common flows without dropping to the CLI.
 
-You are working with **Clio** (`jaz-clio`) — the CLI for the Jaz accounting platform. 73 command groups, 13 calculators, 12 job blueprints, 371 tools. Also fully compatible with Juan Accounting (same API, same endpoints).
+You are working with **Clio** (`jaz-clio`) — the CLI for the Jaz accounting platform. 74 command groups, 13 calculators, 12 job blueprints, 379 tools. Also fully compatible with Juan Accounting (same API, same endpoints).
 
 ## When to Use This Skill
 
@@ -262,7 +262,7 @@ Sending `lineItems[]` to the FLAT endpoint silently ignores them and creates a $
 
 ## Command Quick Reference
 
-**Transactions**: `invoices`, `bills`, `customer-credit-notes`, `supplier-credit-notes`, `journals`, `cash-in`, `cash-out`, `cash-transfer`, `payments`, `cashflow`
+**Transactions**: `invoices`, `bills`, `customer-credit-notes`, `supplier-credit-notes`, `journals`, `cash-in`, `cash-out`, `cash-transfer`, `payments`, `unapplied-payments`, `cashflow`
 
 **Contacts & Configuration**: `contacts`, `contact-groups`, `accounts`, `items`, `tags`, `currencies`, `currency-rates`, `tax-profiles`, `custom-fields`, `bookmarks`, `nano-classifiers`
 

package/assets/skills/cli/references/command-catalog.md

@@ -1,6 +1,6 @@
 # Clio Command Catalog
 
-Complete reference for all 73 command groups. Organized by domain.
+Complete reference for all 74 command groups. Organized by domain.
 
 ---
 
@@ -535,7 +535,7 @@ Also: `clio reports pdf` — generate PDF from a message/document.
 ### `clio magic` — AI document extraction
 | Subcommand | Key flags |
 |------------|-----------|
-| `create` | one of `--file <path>` / `--url <url>` / `--html <string\|@file>`; `--type` (invoice, bill, credit-note-customer, credit-note-supplier); `--merged` (split a multi-doc PDF). `--html` takes raw HTML (e.g. an email body), rendered to a PDF server-side. Encrypted PDFs: `name__pw__password.pdf`. |
+| `create` | one of `--file <path>` / `--url <url>` / `--html <string\|@file>`; `--type` (invoice, bill, credit-note-customer, credit-note-supplier, sale-quote, sale-order, purchase-request, purchase-order); `--merged` (split a multi-doc PDF; not for quotes/orders/requests); `--internal-notes` (max 3000). Max 10 MB per file. `--html` takes raw HTML (e.g. an email body), rendered to a PDF server-side. Encrypted PDFs: `name__pw__password.pdf`. |
 | `status <workflowIds>` | Comma-separated workflow IDs |
 
 ### `clio quick-fix <entity>` — Bulk-update transactions
@@ -557,6 +557,22 @@ Types: `INVOICE`, `BILL`, `CUSTOMER_CREDIT_NOTE`, `SUPPLIER_CREDIT_NOTE`, `JOURN
 | `preview` | `--level` (`TRANSACTIONS`: contact, date, capsule, tags; `LINE_ITEMS`: account, classifiers; required), `--filter <json>`, `--change <json>`, `--input <file>` (`{"filter": …, "change": …}`; the flags replace its keys), `--json` |
 | `apply <previewId>` | `--jot`, `--json`. Runs the preview once, within 30 minutes. Type it as `apply -- <previewId>`: a previewId can start with `-`, which would read as an option. Options go before `--`: `apply --json -- <previewId>`. Exits 1 unless every record changed (PARTIAL, FAILED, UNKNOWN) |
 
+### `clio unapplied-payments` — Cash not yet applied to invoices or bills
+Every write after `record` takes `--hash` (from `search` or the last write). A lost answer prints UNCONFIRMED with the read-back and exits 2 (never re-run it blind).
+
+| Subcommand | Key flags |
+|------------|-----------|
+| `search` | `--id`, `--type` (`AR`/`AP`), `--ref`, `--account`, `--from`, `--to`, `--limit`, `--all`, `--json` |
+| `record` | `--type` (`SALE`/`PURCHASE`), `--account`, `--method`, `--amount`, `--date`, `--currency`, `--rate`, `--contact`, `--reference`, `--notes`, `--draft`, `--input` |
+| `update <id>` | `--hash`, `--reference`, `--notes`, `--method`, `--amount`, `--account`, `--date`, `--input` (for `children`) |
+| `activate <id>` | `--hash`. Posts the draft |
+| `attribute <id>` | `--hash`, `--attributions <json>` |
+| `attach <id>` | `--hash`, `--payment <id>` |
+| `detach <id> <childId>` | `--hash` |
+| `delete <id>` | `--hash`. Deletes its payment records too, and releases a bank match (confirm first when matched) |
+| `unbatch <id>` | `--hash`. Deletes it, keeps its payment records |
+| `reconcile` | `--bank-record`, `--method`, `--contact`, `--reference`, `--amount` (must equal the bank record), `--rate` |
+
 ### `clio capsules` — Transaction grouping
 | Subcommand | Key flags |
 |------------|-----------|
@@ -706,7 +722,7 @@ Valid entity types: INVOICE, BILL, CUSTOMER_CREDIT_NOTE, SUPPLIER_CREDIT_NOTE, S
 Universal async tracker — any operation returning a jobId (contacts bulk-upsert, items bulk-upsert, bank import, magic processing) can be polled here.
 
 ### `clio mcp` — MCP stdio server
-Starts an MCP server for Claude Code / AI tool integration. Exposes all 371 operations.
+Starts an MCP server for Claude Code / AI tool integration. Exposes all 379 operations.
 
 ### `clio serve` — HTTP daemon
 Starts the HTTP daemon for ChatKit and email channel integrations.

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 5.66.0
+version: 5.68.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.66.0
+version: 5.68.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.66.0
+version: 5.68.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.66.0
+version: 5.68.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/jobs/references/document-collection.md

@@ -7,7 +7,7 @@
 ### Platform tools
 - **`mcp magic create --file <pdf>` / `create_bt_from_attachment(businessTransactionType: 'BILL'|'INVOICE'|'CUSTOMER_CREDIT_NOTE'|'SUPPLIER_CREDIT_NOTE', sourceUrl)`** — step 4: OCR + line-item extraction + contact + CoA suggestion. Creates DRAFT transaction.
 - **`finalize_bill(...)` / `finalize_invoice(...)` / `finalize_customer_credit_note(...)`** — step 5: finalize practitioner-reviewed Magic-extracted DRAFTs.
-- **`import_bank_statement(accountResourceId, sourceUrl | attachmentId)`** — step 6: bank statements (CSV / OFX / PDF); creates bank records pending reconciliation per `bank-recon.md`.
+- **`import_bank_statement(accountResourceId, sourceUrl | attached file)`**: step 6: bank statements (CSV / OFX / PDF); creates bank records pending reconciliation per `bank-recon.md`.
 - **`search_background_jobs(filter: {resourceId: {eq: <jobId>}})`** — step 7: poll Magic / bank-import async jobs to terminal status.
 
 ### CLI tools (jaz-cli — offline)
@@ -133,7 +133,7 @@ Match by name + currency to the statement (typically the bank logo + account num
 ```
 import_bank_statement(
   accountResourceId: <bank id>,
-  sourceUrl: <statement file URL>   // or attachmentId
+  sourceUrl: <statement file URL>   // or a file attached to the call (max 10 MB)
 )
 ```
 

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

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

package/assets/templates/platform-rules/jaz-agent-rules.md

@@ -4,7 +4,7 @@ Jaz accounting guidance for this workspace. Load the installed Jaz skills for de
 
 ## Discovery
 
-Jaz exposes **371 tools across 45 namespaces**. Your tool list shows **3, 45, or 371** entries depending on packaging — **never infer capability from its length.**
+Jaz exposes **379 tools across 46 namespaces**. Your tool list shows **3, 45, or 371** entries depending on packaging — **never infer capability from its length.**
 
 - **3** — `search_tools(query)` → `describe_tools(names)` → `execute_tool(name, args)`. Empty query returns the namespace map.
 - **45** — namespace routers; call one with `{ operation, arguments }`. Its description lists its operations.