jaz-clio 5.65.1 → 5.67.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.65.1
+version: 5.67.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
@@ -351,7 +351,7 @@ Bills, invoices, and credit notes share identical mandatory field specs. Adding
 103. **Journal entries must balance** — Sum of all DEBIT amounts must exactly equal sum of all CREDIT amounts. Unbalanced journals are rejected with 422. Agent tools pre-flight check this client-side before hitting the API.
 
 ### Transaction References
-104. **References must be unique per org — NEVER invent one** — A duplicate `reference` causes 422 `Sale Reference already exists` (or `Purchase Reference`). Ask whose number it is. **Purchase side (bills, supplier credit notes): use the SUPPLIER'S own document number**, read off the document; only if it genuinely has none, set `autoReference: true`. **Everything we issue (invoices, customer credit notes, quotes, sale orders, purchase requests, purchase orders, journals, expense claims): set `autoReference: true`** to take the next number from the organization's own series, or call `get_next_reference` to preview it first. Never a timestamp, never a guess, never a pattern inferred from other documents. This covers the business transaction families only; payments, cash entries, transfers, employee payouts, scheduled invoices, scheduled bills, scheduled journals and subscriptions have no series here and keep their own references. The scheduled bodies additionally REQUIRE a literal reference: they mint per occurrence upstream, so `autoReference` is rejected there even though the published schema shows the field. Sending both `reference` and `autoReference` is not an error here: the client resolves the number before the request and your explicit `reference` wins, costing one wasted series read. Send one. The assigned number always carries today's date even on a back-dated document, and reading the series does not reserve it.
+104. **References must be unique per org — NEVER invent one** — On invoices, customer credit notes, quotes and orders a duplicate `reference` causes 422 `Sale Reference already exists`. Bills, supplier credit notes and manual journals accept a duplicate silently, so both documents keep the same number and nobody is told: search by reference before creating one again after an unconfirmed result. Ask whose number it is. **Purchase side (bills, supplier credit notes): use the SUPPLIER'S own document number**, read off the document; only if it genuinely has none, set `autoReference: true`. **Everything we issue (invoices, customer credit notes, quotes, sale orders, purchase requests, purchase orders, journals, expense claims): set `autoReference: true`** to take the next number from the organization's own series, or call `get_next_reference` to preview it first. Never a timestamp, never a guess, never a pattern inferred from other documents. This covers the business transaction families only; payments, cash entries, transfers, employee payouts, scheduled invoices, scheduled bills, scheduled journals and subscriptions have no series here and keep their own references. The scheduled bodies additionally REQUIRE a literal reference: they mint per occurrence upstream, so `autoReference` is rejected there even though the published schema shows the field. Sending both `reference` and `autoReference` is not an error here: the client resolves the number before the request and your explicit `reference` wins, costing one wasted series read. Send one. The assigned number always carries today's date even on a back-dated document, and reading the series does not reserve it.
 
 ### Currency Rates
 105. **`add_currency_rate` for new rates, `update_currency_rate` only for editing existing records** — When a user says "update the rate" or "set the rate", use `add_currency_rate` (POST — creates a new rate entry for a date). Only use `update_currency_rate` (PUT) when explicitly modifying an existing rate record by its resourceId.

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

@@ -2746,6 +2746,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

@@ -851,8 +851,8 @@ The same applies on update: `PUT /cash-in-entries/:id` with `saveAsDraft: true`
 ## Invoices / Bills
 
 ### "Sale Reference already exists" (422) — duplicate reference
-**Cause**: Creating an invoice/bill/CN with a `reference` that already exists in the org.
-**Fix**: Do not invent a number. For a bill or supplier credit note use the supplier's own document number. For anything the organization issues, set `autoReference: true` (or call `get_next_reference` first) to take the next number from its own series. References must be unique per org.
+**Cause**: Creating an invoice, customer credit note, quote or order with a `reference` that already exists in the org.
+**Fix**: Do not invent a number. For anything the organization issues, set `autoReference: true` (or call `get_next_reference` first) to take the next number from its own series. Bills, supplier credit notes and manual journals never return this error: they accept a duplicate reference silently and book a second document, so search by reference before re-creating one after an uncertain result. For a bill or supplier credit note use the supplier's own document number.
 
 ---
 

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.
 >

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 5.65.1
+version: 5.67.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.
 
 ---
 
@@ -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.65.1
+version: 5.67.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.65.1
+version: 5.67.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.65.1
+version: 5.67.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.65.1
+version: 5.67.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.65.1
+version: 5.67.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.