jaz-clio 5.59.1 → 5.60.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-369-blue?style=for-the-badge" alt="369 tools">
+  <img src="https://img.shields.io/badge/tools-371-blue?style=for-the-badge" alt="371 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>
 
-369 tools · 72 command groups · 7 skills · 13 calculators · 12 close playbooks · 159 field-tested API rules.
+371 tools · 73 command groups · 7 skills · 13 calculators · 12 close playbooks · 159 field-tested API rules.
 
 ```bash
 npm install -g jaz-clio
@@ -48,9 +48,10 @@ clio calc lease --payment 5000 --term 36 --rate 5      # IFRS 16, offline, insta
 clio jobs month-end --period 2026-03                   # step-by-step close playbook
 clio magic create --file receipt.pdf                   # AI extracts, drafts the transaction
 clio invoices search --query 'status:unpaid AND $500+' # structured per-entity search
+clio ledger-find-fix preview --level TRANSACTIONS --input recode.json  # find & fix (recode) across record types
 ```
 
-72 command groups, 16 report types, 13 calculators, 12 job playbooks. Every command takes `--json`. Run `clio --help` for the full list.
+73 command groups, 16 report types, 13 calculators, 12 job playbooks. Every command takes `--json`. Run `clio --help` for the full list.
 
 ### Foreign currency
 
@@ -77,7 +78,7 @@ that ends up in a journal.
 
 ## MCP server
 
-369 tools for any AI agent that speaks MCP. Runs locally: no cloud, no ports.
+371 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.59.1
+version: 5.60.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
@@ -31,7 +31,7 @@ The rest of this skill — field names, gotchas, error catalog, dependency order
 
 **Core fundamentals (read first, every integration):** Identifiers & Dates 1–3; Names & Fields 9–13; Transaction Creation 14–16; Chart of Accounts 17–22; Payments / Cross-Currency 4–8; Journals & Cash 23–26; Credit Notes & Refunds 27–28; Reports 36–37; Tax Profile Scoping 100; Transaction References 104; Draft Finalization Pipeline 81–88; Jaz Magic / PDF-JPG 57–63; Currency Rates 39, 49, 105; Withholding Tax 45, 98.
 
-**Integration depth (API clients, pipelines, batch jobs, MCP/CLI):** Bulk Upsert (Items/Contacts/Rates); Background Jobs (filter `resourceId` not `jobId`); Export Records; Pagination (38); Search & Filter (50–56); Response Shape Gotchas (66–73); Cash Entry Response Shape (74–77); Entity Resolution (78–80); Bank Rules (89–90c); Fixed Assets (91–92c); Subscriptions & Scheduled (93–94); niche endpoints (95–102); Journals balance (103); Quick Fix (107, 111); TTB (108); Dynamic Strings (109–110); Sub-Resource Shapes (112); Nano-Classifier (113); Scheduler Asymmetry (114); Payment Record CRUD (115–117); Bulk Upserts transactions (118–122); Reconciliation write-side (123–127); Drafts lifecycle (128–135); Orders — Sale Quotes / Sale Orders / Purchase Requests / Purchase Orders (`references/orders.md`); Claims — records / lifecycle / bulk + conversion + payouts + Employees + Claim Settings (`references/claims.md`).
+**Integration depth (API clients, pipelines, batch jobs, MCP/CLI):** Bulk Upsert (Items/Contacts/Rates); Background Jobs (filter `resourceId` not `jobId`); Export Records; Pagination (38); Search & Filter (50–56); Response Shape Gotchas (66–73); Cash Entry Response Shape (74–77); Entity Resolution (78–80); Bank Rules (89–90d); Fixed Assets (91–92c); Subscriptions & Scheduled (93–94); niche endpoints (95–102); Journals balance (103); Quick Fix (107, 111); TTB (108); Dynamic Strings (109–110); Sub-Resource Shapes (112); Nano-Classifier (113); Scheduler Asymmetry (114); Payment Record CRUD (115–117); Bulk Upserts transactions (118–122); Reconciliation write-side (123–127); Drafts lifecycle (128–135); Orders — Sale Quotes / Sale Orders / Purchase Requests / Purchase Orders (`references/orders.md`); Claims — records / lifecycle / bulk + conversion + payouts + Employees + Claim Settings (`references/claims.md`).
 
 ## When to Use This Skill
 
@@ -359,6 +359,7 @@ Bills, invoices, and credit notes share identical mandatory field specs. Adding
 
 ### Quick Fix (Bulk Update)
 107. **20 Quick Fix endpoints for bulk-updating transactions and line items** — `POST /api/v1/quick-fix/{entity}` with `{ resourceIds: [...], attributes: {...} }`. Only included fields are changed — omitted fields are left unchanged. Response: `{ updated: string[], failed: [{ resourceId, error, errorCode }] }`. **HTTP status codes**: 200 = complete success (`failed` always empty). **207 Multi-Status** = partial or total failure with per-item detail (same response shape as 200 — check `failed` array). 422 = total failure with no per-item breakdown (rare). On 207, retry only `failed` resourceIds. Entities: **ARAP**: invoices, bills, customer-credit-notes, supplier-credit-notes. **Accounting**: journals, cash-entries. **Schedulers**: sale-schedules, purchase-schedules, subscription-schedules, journal-schedules. **Line-item request patterns**: ARAP + accounting use `{ lineItemResourceIds, attributes }`. Schedulers (sale/purchase/subscription) use Pattern C: `{ schedulerUpdates: [{ schedulerResourceId, lineItemUpdates: [{ arrayIndex, ...attrs }] }] }`. **Journal-schedules use Pattern D**: `lineItemResourceId` (UUID) instead of `arrayIndex`. **Field gotchas**: cash entries use `currencySetting` (singular: `{ rateFunctionalToSource, exchangeToken }`), NOT `currencySettings`. Journal schedules have `startDate` in addition to `endDate`/`interval`. Tags: string array, max 50 items, max 50 chars each.
+107a. **Ledger Find & Fix: find and fix (recode) records across types with one filter, preview one change, apply it once.** Use it when a user asks to find & fix, recode, reclassify, retag, re-date or move records to another account across many records or several types. `POST /api/v1/ledger/find-fix/transactions/preview` (sets contact, date, capsule, tags) or `POST /api/v1/ledger/find-fix/line-items/preview` (sets account, classifiers), each with `{ filter, change }`, then `POST /api/v1/ledger/find-fix/apply` with `{ previewId }`; conditions, bodies and every code are in endpoints.md section 17a. `JOURNAL` covers manual and cashflow journals only: transfer and trial-balance journals and cash transfers never match, so their ids come back `NOT_FOUND`. **A filter with no condition besides `types` is a 422, and a condition with no operator is ignored.** **The API refuses a key it does not take, at any level, with 400 `invalid_filter` naming the key**; the tools and the CLI refuse a field of the other level before the request, naming the level that takes it. `tags` `{ add, remove }` keeps the record's other tags, so setting tags to X means removing the current ones and adding X. A classifier removal needs only `{ resourceId, deleted: true }`, even for a classifier the organization no longer has. **Preview** writes nothing, matches at most 500 records, and returns `previewId` (valid 30 minutes; absent when nothing is eligible). **A blocked field is left as it is while the record's other fields still change.** **Apply** is single use and saves the preview-time values, so a field edited between preview and apply, tags included, is overwritten. Once it has taken the preview it runs to the end even if the caller leaves, and starts no new call 3 minutes after the request arrived. 207 lists the `failed` records with an `errorCode`; `OUTCOME_UNKNOWN` means that record may have changed. 404 `PREVIEW_NOT_FOUND` (expired, used, being applied, or another caller's): preview again, never resend. **Any other 5xx, or a timeout, on apply means the outcome is unknown: if the connection drops, the apply keeps running for up to 4 minutes. Wait that long before previewing or applying again on the same records, then preview again or re-read them. Never apply this previewId again.** Several applies can run at the same time. When two applies change records on one document at once, the one saved last can undo the other's changes, including fields and line items it did not set. Preview again to check the result. Lock dates, filed tax periods and claims-backed documents fail per record, and e-invoice filings may be re-submitted. Rule 107's per-type routes stay for one document, for fields this does not change (due date, tax profile, notes, amounts, custom fields) and for scheduled transactions.
 
 ### Transfer Trial Balance
 108. **Transfer Trial Balance** (`POST /api/v1/transfer-trial-balance`) creates opening balance entries. Uses `journalEntries` (NOT `lines` — this is a journal type). Always ACTIVE (no draft mode), reference auto-generated as "Transfer Trial Balance", minimum 1 entry, entries cannot have 0 amounts, skips lock date validation. **`valueDate` must be today or in the past** — future dates are rejected with "Opening data cannot be future date". Each entry: `{ accountResourceId, type: "DEBIT"|"CREDIT", amount }`.

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

@@ -2039,6 +2039,131 @@ Note: journal-schedules use `lineItemResourceId` (UUID), NOT `arrayIndex`.
 
 ---
 
+## 17a. Ledger Find & Fix
+
+Find and fix (recode) records across invoices, bills, both credit notes, journals and cash entries with one filter: preview one change, then apply the stored preview once. SKILL.md rule 107a carries the rules an agent must follow; the conditions, shapes and codes are here.
+
+| Filter condition | Operators |
+|------------------|-----------|
+| `types` (required) | `INVOICE`, `BILL`, `CUSTOMER_CREDIT_NOTE`, `SUPPLIER_CREDIT_NOTE`, `JOURNAL` (manual and cashflow journals only), `CASH_ENTRY` |
+| `resourceIds` | Up to 500; line item ids at line level |
+| `reference` | `eq`, `in`, `contains`, `startWith` |
+| `valueDate` | `eq`, `gte`, `lte`, `between: [from, to]` |
+| `contactResourceId` | `eq`, `in` |
+| `organizationAccountResourceId` | `eq`, `in`; line level only |
+
+A filter needs a condition besides `types`, or the preview answers 422. A condition with no operator is ignored. A key or operator the API does not take, at any level of the request, is a 400 `invalid_filter` whose message names it. At line level, `resourceIds` are line item ids, and reference, date and contact conditions match the line's document.
+
+### POST /api/v1/ledger/find-fix/transactions/preview
+
+Finds records and plans one change: `contactResourceId`, `valueDate` (at most a year ahead), `capsuleResourceId` or `tags` (`{ add, remove }`; the record's other tags stay). A cash entry that is not void is always listed as changing its capsule, since its current capsule is not shown.
+
+```json
+{
+  "filter": { "types": ["INVOICE", "BILL"], "valueDate": { "between": ["2026-04-01", "2026-06-30"] } },
+  "change": { "contactResourceId": "new-contact-uuid", "tags": { "add": ["Q2"] } }
+}
+```
+
+### POST /api/v1/ledger/find-fix/line-items/preview
+
+Finds and recodes line items: `organizationAccountResourceId` (not a bank, cash or control account) or `classifierConfig` (max 50 entries, unique by resourceId, at most 100 classes each; unlisted classifiers stay, and `{ "resourceId": "classifier-uuid", "deleted": true }` removes one, with type and printable filled in by the API; a set needs type, printable and at least one class). On a set entry, a classifier the organization lacks, or a class it lacks or has deleted, is 422 `CLASSIFIER_NOT_FOUND` / `CLASS_NOT_FOUND`. A removal is not checked: removing a classifier the organization lacks is `NO_CHANGE`, so stored bad IDs can be cleaned up. A selection drawn from a record list (`entityResourceId`) is not checked either.
+
+```json
+{
+  "filter": { "types": ["JOURNAL", "CASH_ENTRY"], "organizationAccountResourceId": { "eq": "old-account-uuid" } },
+  "change": { "organizationAccountResourceId": "new-account-uuid" }
+}
+```
+
+Preview response (both levels). The contact change below reaches the invoice; on the bill the contact is blocked, so only its tags change. `after` holds only the fields that will change:
+
+```json
+{
+  "previewId": "Q2rX8vK1mZ4p",
+  "expiresAt": "2026-09-15T10:30:00Z",
+  "level": "TRANSACTIONS",
+  "counts": {
+    "matched": 3, "eligible": 2, "excluded": 1,
+    "byType": { "INVOICE": 2, "BILL": 1 },
+    "excludedByCode": { "VOID": 1 },
+    "blockedByCode": { "CONTACT_NOT_SUPPLIER": 1 }
+  },
+  "data": [
+    {
+      "type": "INVOICE", "resourceId": "invoice-uuid", "reference": "INV-12", "valueDate": "2026-04-01", "status": "ELIGIBLE",
+      "before": { "contactResourceId": "old-contact-uuid", "tags": [] },
+      "after": { "contactResourceId": "new-contact-uuid", "tags": ["Q2"] }
+    },
+    {
+      "type": "BILL", "resourceId": "bill-uuid", "reference": "BILL-7", "valueDate": "2026-04-02", "status": "ELIGIBLE",
+      "blocked": [{ "field": "contactResourceId", "code": "CONTACT_NOT_SUPPLIER" }],
+      "before": { "contactResourceId": "old-contact-uuid", "tags": [] },
+      "after": { "tags": ["Q2"] }
+    }
+  ]
+}
+```
+
+No `previewId` means nothing is eligible and nothing was stored. A row is `EXCLUDED` only for these codes:
+
+| Row `code` | Meaning |
+|------------|---------|
+| `NOT_FOUND` | A listed id matched no record of the listed types; transfer and trial-balance journals and cash transfers never match |
+| `VOID` | The record, or the line's document, is void |
+| `NO_CHANGE` | Every field the change sets already has that value |
+| `BLOCKED` | Every field the change sets is blocked on this record |
+
+A blocked field is left as it is while the record's other fields still change, and the row stays `ELIGIBLE`:
+
+| `blocked[].code` | Field | Why |
+|------------------|-------|-----|
+| `CONTACT_NOT_CUSTOMER`, `CONTACT_NOT_SUPPLIER` | contact | The new contact is not the customer or supplier the document needs |
+| `HAS_CREDIT_OFFSETS` | contact | Credits applied to the document would stay with the old contact |
+| `FOREIGN_CURRENCY_VALUE_DATE` | date | A new date on a foreign currency record would take a new exchange rate |
+| `VALUE_DATE_AFTER_DUE_DATE` | date | The new date is after the document's due date |
+| `TOO_MANY_TAGS` | tags | The record would end with more than 50 tags |
+| `CONTROL_LINE` | account | A journal line on a bank, cash or control account |
+
+### POST /api/v1/ledger/find-fix/apply
+
+```json
+{ "previewId": "Q2rX8vK1mZ4p" }
+```
+
+Single use. Saves the preview-time values, so a field edited between preview and apply, tags included, is overwritten. Once it has taken the preview, the apply runs to the end even if the caller leaves, sends calls of about 100 records (a document's lines stay together, so one call can carry more), and starts no new call 3 minutes after the request arrived. Lock dates are checked when a change is saved, so a record in a locked period comes back in `failed`. 200 when every record changed, 207 otherwise:
+
+```json
+{
+  "failed": [{ "type": "INVOICE", "resourceId": "invoice-uuid", "error": "…", "errorCode": "OUTCOME_UNKNOWN" }],
+  "updated": [{ "type": "BILL", "resourceId": "bill-uuid" }]
+}
+```
+
+| `failed[].errorCode` | Meaning |
+|----------------------|---------|
+| `OUTCOME_UNKNOWN` | The answer for this record was lost, so it may or may not have changed |
+| `NOT_ATTEMPTED` | The apply reached its 3-minute limit before sending this record, so it did not change |
+| `UPSTREAM_REJECTED` | The platform refused the update before this record changed |
+| `UNSUPPORTED_RECORD_TYPE` | The stored preview names a record type this version cannot change |
+
+Several applies can run at the same time. When two applies change records on one document at once, the one saved last can undo the other's changes, including fields and line items it did not set. Preview again to check the result.
+
+| Status | `error_details.code` | Meaning |
+|--------|----------------------|---------|
+| 404 | `PREVIEW_NOT_FOUND` | Expired, already applied or being applied, or another caller's preview. Preview again, never resend. |
+| 400 | none; `error_type` is `invalid_filter` | A key or operator the request may not carry; the message names it |
+| 422 | `CONTACT_NOT_FOUND`, `CAPSULE_NOT_FOUND` | Transactions preview: the contact or capsule the change sets does not exist; `resourceId` names it |
+| 422 | `ACCOUNT_NOT_FOUND`, `ACCOUNT_NOT_ALLOWED` | Line items preview: the account the change sets does not exist, is inactive, or is a bank, cash or control account; `resourceId` names it |
+| 422 | `CLASSIFIER_NOT_FOUND`, `CLASS_NOT_FOUND` | Line items preview, set entries only: a classifier the change sets does not exist, or a class it selects is not a current class of that classifier; `resourceId` names the classifier or class. A removal and a record-list selection (`entityResourceId`) are not checked |
+| 422 | `TOO_MANY_RECORDS` | Either preview: at least `count` records or line items match, more than `limit` |
+| 422 | `TOO_MANY_CALLS` | Transactions preview: the change needs `count` separate updates, more than `limit`, because records whose resulting values differ need separate updates. A line items preview never answers it |
+| 503 | `PREVIEW_STORE_UNAVAILABLE` | Nothing applied |
+
+Any other 5xx, or a timeout, on apply: the outcome is unknown. If the connection drops, apply keeps running for up to 4 minutes. Wait that long before previewing or applying again on the same records, then preview again or re-read them. Never apply this previewId again. A service restart can stop an apply; preview again to check.
+
+---
+
 ## 18b. Transfer Trial Balance
 
 ### POST /api/v1/transfer-trial-balance
@@ -2535,4 +2660,82 @@ Append one review verb to a jot (append-only: annotates, never mutates).
 
 ---
 
-*Last updated: 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.*
+## 26. Bank Rules CRUD
+
+A bank rule has two halves: the **WHEN** (`searchFilter`, the condition deciding which statement lines it applies to) and the **THEN** (`configuration.reconcileWithDirectCashEntry`, the allocation). **A rule with no `searchFilter` is never suggested** — auto-reconciliation only considers rules whose stored condition is non-null, so it exists, lists, and can be applied by hand, but is never offered. See jaz-api rules 90a-90d for the full payload.
+
+### GET /api/v1/bank-rules
+
+Lists bank rules. Standard pagination (`limit`, `offset`).
+
+### GET /api/v1/bank-rules/:resourceId
+
+Returns one rule, including its `searchFilter`.
+
+```json
+// Response (data):
+{
+  "resourceId": "uuid",
+  "name": "Grab rides",
+  "actionType": "RECONCILE_WITH_DIRECT_CASH_ENTRY",
+  "appliesToReconciliationAccount": { "code": "1001", "currencyCode": "SGD", "name": "Business Bank Account" },
+  "searchFilter": {
+    "version": 1,
+    "raw": "description:grab",
+    "parsed": { "description": { "contains": "grab" } }
+  },
+  "configuration": { "reconcileWithDirectCashEntry": { "...": "..." } }
+}
+```
+
+`appliesToReconciliationAccount` comes back as an OBJECT on read but is sent as a bare UUID on write, so a rule cannot be round-tripped without substituting it.
+
+### POST /api/v1/bank-rules
+
+Creates a rule. `searchFilter` is optional on the wire and effectively required in practice.
+
+```json
+// Request:
+{
+  "name": "Grab rides",
+  "appliesToReconciliationAccount": "<bank-account-uuid>",
+  "searchFilter": {
+    "version": 1,
+    "raw": "description:grab",
+    "parsed": { "description": { "contains": "grab" } }
+  },
+  "configuration": {
+    "reconcileWithDirectCashEntry": {
+      "amountAllocationType": "PERCENTAGE",
+      "reference": "AUTO-{{bankReference}}",
+      "percentageAllocation": [{ "organizationAccountResourceId": "<acct-uuid>", "amount": 100 }]
+    }
+  }
+}
+```
+
+`searchFilter` rules: `version` must be `1`; `raw` must be PRESENT but **may be the empty string** (the app itself saves conditions that way); `parsed` must be a non-empty object. Condition fields are `description`, `extReference`, `extContactName`, `netAmount`, `valueDate`, plus the account's active custom Bank Fields. An unsupported field path does NOT error — the rule saves and then never fires.
+
+### PUT /api/v1/bank-rules/:resourceId
+
+Full replacement: send `resourceId`, `appliesToReconciliationAccount` and the whole `configuration` every time.
+
+**`searchFilter` is the one exception to full replacement.** Omit the key and the stored condition is KEPT; send `null` to remove it; send an object to replace it. This matters because the obvious read-modify-write (GET, change the name, PUT) drops the condition unless you carry it across — which silently stops the rule ever being suggested again.
+
+### DELETE /api/v1/bank-rules/:resourceId
+
+Deletes a rule.
+
+### POST /api/v1/bank-rules/search
+
+Searches rules. Filter fields: `name`, `resourceId`, `actionType`, `appliesToReconciliationAccount`, `businessTransactionType`, `reference`, plus `and`/`or`.
+
+```json
+{ "filter": { "name": { "contains": "grab" } }, "sort": { "sortBy": ["name"], "order": "ASC" }, "limit": 100 }
+```
+
+**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.
+
+---
+
+*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.*

package/assets/skills/api/references/feature-glossary.md

@@ -167,7 +167,7 @@ Match bank statement lines to Jaz transactions to verify cash balances. This is
 
 **Bank Feeds**: Connect Airwallex, Aspire, Stripe, Wise, or Xendit for automated statement sync (up to 12 months history, daily auto-sync).
 
-**Bank Rules**: Auto-allocate amounts using percentage-only or fixed+percentage splits (max 10 fixed + 10 percentage lines). Support dynamic strings like `#{{bankReference}}`, `#{{payeeName}}`.
+**Bank Rules**: Two halves. The WHEN is the inline `searchFilter` condition deciding which statement lines the rule applies to — without one the rule is never suggested under Apply Rule, only applied by hand. The THEN auto-allocates amounts using percentage-only or fixed+percentage splits (max 10 fixed + 10 percentage lines). Support dynamic strings `{{bankReference}}`, `{{bankPayee}}`, `{{bankDescription}}`.
 
 Statement amounts are recorded in the bank account's currency — no auto-conversion. Cross-currency transactions prompt for cash received/spent in statement currency. Reconciled transactions become uneditable (must reset to edit).
 
@@ -255,6 +255,12 @@ Mass-edit transactions and line items in a single operation. Replaces the need t
 
 **API**: `POST /api/v1/quick-fix/{entity}` (transaction-level) + `POST /api/v1/quick-fix/{entity}/line-items` (line-item-level). 20 endpoints total.
 
+### Ledger Find & Fix
+
+Find and fix, or recode, records across record types in one pass: find invoices, bills, credit notes, journals and cash entries by a condition (reference, date range, contact, current account), preview one change to their contact, date, capsule, tags, account or classifiers, and apply it once the user has checked the preview. Users ask for it as "find & fix", "recode", "reclassify", "retag", "re-date" or "move these to account X". Quick Fix stays for a known set of records of one type and for the fields this does not change.
+
+**API**: `POST /api/v1/ledger/find-fix/transactions/preview` or `POST /api/v1/ledger/find-fix/line-items/preview`, then `POST /api/v1/ledger/find-fix/apply`. See rule 107a.
+
 ---
 
 *Maintained alongside [help.jaz.ai](https://help.jaz.ai).*

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 / 369 operations and is the authoritative list; check it before concluding
+> carries 454 paths / 371 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.
 >
@@ -404,6 +404,9 @@ Body for all three: `{ items: [{btResourceId: "<uuid>", btType: "SALE|PURCHASE|S
 | POST | `/generate-reports/fixed-assets-recon-summary` |
 | POST | `/generate-reports/templated-*` | Templated versions of above |
 | GET | `/ledger/highlights` | GL summary metadata (counts, date range, currencies) |
+| POST | `/ledger/find-fix/transactions/preview` | Ledger Find & Fix: find records across types, plan a contact, date, capsule or tag change (rule 107a) |
+| POST | `/ledger/find-fix/line-items/preview` | Ledger Find & Fix for line items: plan an account or classifier change |
+| POST | `/ledger/find-fix/apply` | Apply a Ledger Find & Fix preview once |
 
 ### Data Exports (downloadable)
 | Method | Path |

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 5.59.1
+version: 5.60.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
-  72 command groups and 369 tools, including employee-expense claims.
+  73 command groups and 371 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. 72 command groups, 13 calculators, 12 job blueprints, 369 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. 73 command groups, 13 calculators, 12 job blueprints, 371 tools. Also fully compatible with Juan Accounting (same API, same endpoints).
 
 ## When to Use This Skill
 
@@ -259,7 +259,7 @@ Sending `lineItems[]` to the FLAT endpoint silently ignores them and creates a $
 
 **Contacts & Configuration**: `contacts`, `contact-groups`, `accounts`, `items`, `tags`, `currencies`, `currency-rates`, `tax-profiles`, `custom-fields`, `bookmarks`, `nano-classifiers`
 
-**Bank & Reconciliation**: `bank` (accounts, get, records, add-records, import, auto-recon), `bank-rules`
+**Bank & Reconciliation**: `bank` (accounts, get, records, add-records, import, auto-recon), `bank-rules` (a rule needs `--search-filter` or auto-reconciliation never suggests it; on `update`, omitting the flag keeps the stored condition and `--clear-search-filter` removes it)
 
 **Employee Claims & Settings**: `claims` (lifecycle + `create` + `from-attachment` + convert + payout), `employees`, `claim-types`, `claim-profiles`, `posting-rules`
 
@@ -269,7 +269,7 @@ Sending `lineItems[]` to the FLAT endpoint silently ignores them and creates a $
 
 **Reports & Exports**: `reports` (16 report types), `exports`
 
-**AI & Automation**: `magic` (create, status), `quick-fix`, `capsules`, `capsule-transaction` (alias: `ct`, 13 recipe types)
+**AI & Automation**: `magic` (create, status), `quick-fix`, `ledger-find-fix` (preview, apply), `capsules`, `capsule-transaction` (alias: `ct`, 13 recipe types)
 
 **Judgment journal**: `jots` (create, recall, dispose). Every write command also takes `--jot "<one line>"` to log the judgment behind that specific write inline, no extra call (see `--jot` in Common Flags).
 
@@ -382,7 +382,7 @@ clio ct loan --principal 100000 --rate 5 --term 60 --start-date 2026-01-01 \
 3. **Multi-org scripts**: `clio invoices list --org acme-sg --json && clio invoices list --org acme-ph --json`
 4. **Draft-then-finalize**: The CLI defaults to saving as draft (overrides the API default of `saveAsDraft: false`). Use `--finalize` to create a finalized transaction immediately. Note: `cash-in`, `cash-out` and `cash-transfer` have no draft state and so take no `--finalize` — they always post ACTIVE.
 5. **Idempotent creates**: Use `--input` with the same JSON to get consistent results. The API dedup guards catch duplicate contacts, items, and accounts.
-6. **Check before bulk ops**: Always preview with `--json | jq length` before piping IDs into `quick-fix`.
+6. **Check before bulk ops**: Always preview with `--json | jq length` before piping IDs into `quick-fix`. To find & fix (recode, retag, re-date) records found by a condition, across record types, `clio ledger-find-fix preview` lists what would change and why anything is excluded, and `clio ledger-find-fix apply -- <previewId>` runs exactly that, once.
 7. **Offline calculators for exploration**: `clio calc` commands need no auth -- use them to explore scenarios before committing with `clio ct`.
 8. **Help center for guidance**: `clio hc "how to reconcile"` searches the full Jaz help center locally (hybrid: embeddings + keyword).
 

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

@@ -1,6 +1,6 @@
 # Clio Command Catalog
 
-Complete reference for all 72 command groups. Organized by domain.
+Complete reference for all 73 command groups. Organized by domain.
 
 ---
 
@@ -318,14 +318,16 @@ EmploymentType: `FULL_TIME` · `PART_TIME` · `CONTRACTOR` · `INTERN` · `TEMPO
 | Subcommand | Key flags |
 |------------|-----------|
 | `list` | `--limit`, `--offset`, `--all`, `--format`, `--json` |
-| `get <id>` | `--json` |
-| `search <query>` | `--limit`, `--offset` |
-| `create` | `--input` (JSON body with rule definition) |
-| `update <id>` | `--input` |
+| `get <id>` | `--json`. Prints the rule's condition, or says it has none |
+| `search <query>` | `--limit`, `--offset`, `--account` |
+| `create` | `--name`, `--account`, `--config`, `--search-filter <json>`, `--input` |
+| `update <id>` | `--account` (required), `--name`, `--config`, `--search-filter <json>`, `--clear-search-filter`, `--input` |
 | `delete <id>` | |
 
 Dynamic strings in rules: `{{bankReference}}`, `{{bankPayee}}`, `{{bankDescription}}`
 
+**A rule without a condition is never suggested.** `--search-filter` is the rule's WHEN side; auto-reconciliation only considers rules whose stored condition is non-null, so a rule created without one exists, lists and applies by hand but is never offered. On `update` the condition is the one field a full-replacement PUT need not resend: **omit `--search-filter` and the stored condition is kept**, pass `--clear-search-filter` to remove it. Shape: `{"version":1,"raw":"description:grab","parsed":{"description":{"contains":"grab"}}}` — `raw` may be blank.
+
 ---
 
 ## Fixed Assets & Inventory
@@ -544,6 +546,14 @@ Entities: `invoices`, `bills`, `customer-credit-notes`, `supplier-credit-notes`,
 | `--date`, `--due`, `--tag`, `--contact`, `--account`, `--tax-profile` | Shorthand flags |
 | `--input <file>` | Full request body from file |
 
+### `clio ledger-find-fix` — Find & fix (recode) records across types, preview one change, apply it once
+Types: `INVOICE`, `BILL`, `CUSTOMER_CREDIT_NOTE`, `SUPPLIER_CREDIT_NOTE`, `JOURNAL`, `CASH_ENTRY`
+
+| Subcommand | Key flags |
+|------------|-----------|
+| `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 capsules` — Transaction grouping
 | Subcommand | Key flags |
 |------------|-----------|
@@ -693,7 +703,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 369 operations.
+Starts an MCP server for Claude Code / AI tool integration. Exposes all 371 operations.
 
 ### `clio serve` — HTTP daemon
 Starts the HTTP daemon for ChatKit and email channel integrations.

package/assets/skills/cli/references/common-workflows.md

@@ -193,6 +193,15 @@ clio quick-fix invoices --ids "$DRAFT_IDS" --tag "Q1-Review" --due 2026-04-30
 # Bulk-update line items (e.g., reassign account)
 clio quick-fix invoices --line-items --ids "$LINE_ITEM_IDS" \
   --account "<target-account-resourceId>"
+
+# Find & fix (recode) across record types: no ID list needed. Preview moves every
+# journal and cash entry line on the old account to the new one, writing nothing
+clio ledger-find-fix preview --level LINE_ITEMS \
+  --filter '{"types":["JOURNAL","CASH_ENTRY"],"organizationAccountResourceId":{"eq":"<old-account-resourceId>"}}' \
+  --change '{"organizationAccountResourceId":"<new-account-resourceId>"}'
+
+# Apply the preview once you have checked it (-- because a previewId can start with "-")
+clio ledger-find-fix apply -- "<previewId>"
 ```
 
 ## 7. Multi-Org Management

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 5.59.1
+version: 5.60.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.59.1
+version: 5.60.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.59.1
+version: 5.60.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.59.1
+version: 5.60.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/gst-vat-filing.md

@@ -9,7 +9,7 @@
 - **`search_tax_profiles(filter: {})`** — step 2 setup verification: confirm all expected tax profiles exist (`SR`, `ZR`, `ES`, `IES`, `OS`, `TX`, `BL`, `OP`, `EP`, `RC` for SG; `VAT-RC`, `VAT-EXP`, `VAT-ZR`, `VAT-EXM`, `VAT-EXC` for PH).
 - **`search_invoices(filter: {valueDate: {between: [<period-start>, <period-end>]}}, limit: 200)`** — step 3 output-tax detail: per-invoice GST cross-check against tax ledger.
 - **`search_bills(filter: {valueDate: {between: [<period-start>, <period-end>]}, status: {neq: 'DRAFT'}}, limit: 200)`** — step 4 input-tax detail: per-bill GST cross-check, with blocked-input filter.
-- **`quick_fix_invoices(...)` / `quick_fix_bills(...)`** — step 5 corrections: bulk-update tax-profile / tax-vat-applicable across multiple transactions if errors found.
+- **`quick_fix_line_items(entity: 'invoices' | 'bills', lineItemResourceIds, attributes)`** — step 5 corrections: re-assign the tax profile on the affected lines if errors are found. The tax profile sits on each line, so the fix is at line level.
 - **`download_export(exportType: 'analysis-exchange-rate-audit', startDate, endDate)`** — step 6 pre-filing check: FX rates outside expected band can shift GST on FX invoices.
 - **`generate_trial_balance(period_end: <period-end>)`** — step 7 GST account reconciliation: `GST Control` / `Input Tax Recoverable` / `Output Tax Payable` accounts.
 
@@ -97,23 +97,17 @@ Flag bills where:
 
 ## Step 5 — Corrections (if errors found)
 
-For tax-profile errors detected in steps 3-4:
+For tax-profile errors detected in steps 3-4. The tax profile sits on each line item, so correct the lines:
 
 ```
-quick_fix_invoices({
-  resourceIds: [<list of invoice ids>],
+quick_fix_line_items({
+  entity: 'invoices',
+  lineItemResourceIds: [<line item ids from the step 3 invoices>],
   attributes: { taxProfileResourceId: <correct profile id> }
 })
 ```
 
-Mirror for bills via `quick_fix_bills`. For line-item-level fixes:
-
-```
-quick_fix_invoices({
-  lineItemResourceIds: [<list of line item ids>],
-  attributes: { taxProfileResourceId: <correct profile> }
-})
-```
+Mirror for bills with `entity: 'bills'`. Ledger Find & Fix (`preview_ledger_find_fix`) does not change tax profiles, so these per-type calls are the route for this correction.
 
 Per `jaz-api/SKILL.md` rule 107: Quick Fix returns 207 Multi-Status on partial failures; retry only failed resourceIds.
 
@@ -176,7 +170,7 @@ Save the filing summary for the quarter. The user files via the appropriate port
 | Step 2 | Tax profile missing for jurisdiction | `create_tax_profile(...)` per IRAS / BIR spec. Halt and surface to practitioner — practitioner judgment on rate. |
 | Step 3 | Per-invoice GST ≠ tax-ledger output total | Investigate per-invoice tax-profile assignment. Quick Fix typically resolves. |
 | Step 4 | BL bills coded as TX | Quick Fix re-assigns to BL. Practitioner approval required (changes input tax claim). |
-| Step 5 | `quick_fix_invoices` 207 Multi-Status | Retry only failed resourceIds (per rule 107). Likely cause: invoice in locked period. |
+| Step 5 | `quick_fix_line_items` 207 Multi-Status | Retry only failed resourceIds (per rule 107). Likely cause: invoice in locked period. |
 | Step 7 | TB GST Control ≠ tax-ledger net | Surface to practitioner. Investigate manual journals against GST accounts. Auditor will catch this if unresolved. |
 | Step 8 | Box 13 Revenue ≠ P&L Operating Revenue | Box 13 includes ALL revenue (zero-rated + exempt + standard); P&L may show split. Re-confirm Box 13 definition with IRAS. |
 | Filing rejected by myTax / BIR | (post-filing) | Pull rejection reason. Amend filing summary; refile within allowed window. Practitioner judgment on penalty exposure. |

package/assets/skills/jobs/references/quarter-end-close.md

@@ -155,7 +155,7 @@ update_account(resourceId: <CoA root>, lockDate: '2025-03-31')
 | Source | Error | Recovery |
 |--------|-------|----------|
 | Phase 1-5 (standalone) | Months not all closed | Months incomplete. Route to missing `month-end-close.md`. Run quarterly extras only once all 3 months are locked. |
-| Q1 verification | Tax ledger ≠ sum of GST per invoice/bill | Likely tax-profile assignment errors. Audit each invoice / bill for correct tax profile. Quick Fix: `quick_fix_invoices(...)` / `quick_fix_bills(...)`. |
+| Q1 verification | Tax ledger ≠ sum of GST per invoice/bill | Likely tax-profile assignment errors. Audit each invoice / bill for correct tax profile. Quick Fix: `quick_fix_line_items(entity: 'invoices' \| 'bills', ...)` on the affected lines, since the tax profile sits on each line. |
 | Q2 ECL recipe | 422 `account_not_found` | `Allowance for Doubtful Debts` missing. Create via `create_account(accountType: 'Current Asset')`. |
 | Q3 | YTD accrual mismatches monthly recipe expectations | Likely a manual journal posted directly to Bonus Liability (not via recipe). Audit `generate_general_ledger(accountResourceId: <Bonus Liability>, period_start: <FY-start>, period_end: <today>)`. |
 | Q4 IC recon | Entity A IC Receivable ≠ Entity B IC Payable (sign-flipped) | See the `intercompany` recipe error table. Common causes: timing, FX confusion, posting skipped in one entity. |

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

@@ -1,6 +1,6 @@
 ---
 name: jaz-recipes
-version: 5.59.1
+version: 5.60.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

@@ -6,11 +6,11 @@ Source of truth lives in the installed skills (`.claude/skills/jaz-*/SKILL.md` o
 
 ## Discovery
 
-Jaz exposes **369 tools across 45 namespaces**. Your tool list shows **3, 45, or 369** entries depending on packaging — **never infer capability from its length.**
+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.**
 
 - **3** — `search_tools(query)` → `describe_tools(names)` → `execute_tool(name, args)`. Empty query returns the namespace map.
-- **43** — namespace routers; call one with `{ operation, arguments }`. Its description lists its operations.
-- **369** — call operations directly by name.
+- **45** — namespace routers; call one with `{ operation, arguments }`. Its description lists its operations.
+- **371** — call operations directly by name.
 
 `describe_capabilities` returns the capability map on all three. **Call it before telling the user Jaz cannot do something.**
 
@@ -36,6 +36,7 @@ Exception: `fx-reval` is verification-only — Jaz auto-handles period-end IAS 2
 
 ## Bulk operations
 
+- Find & fix (recode) many records: `preview_ledger_find_fix`, then apply once the user confirms.
 - `bulk_upsert_*` tools accept up to 500 rows per call. Async tools return a `jobId` — poll `search_background_jobs(filter:{resourceId:{eq:jobId}})` until SUCCESS / FAILED / PARTIAL_SUCCESS.
 - On `PARTIAL_SUCCESS`: succeeded rows are committed. Inspect `errorDetails[].rowIndex` and re-submit only failed rows.
 - Sync `bulk_upsert_chart_of_accounts` returns `failedRows[]` inline — no polling.