jaz-clio 5.59.0 → 5.59.2

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 5.59.0
+version: 5.59.2
 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
 
@@ -286,8 +286,8 @@ Bills, invoices, and credit notes share identical mandatory field specs. Adding
 ### Bank Rules
 89. **Bank rules GET by ID has double-nested response** — `GET /bank-rules/:id` returns `{ data: { data: [...], totalElements, totalPages } }` (double `data` wrapper). Unlike standard `GET /:type/:id` which returns `{ data: {...} }`. The inner `data` is an array containing the single rule. Unwrap with `response.data.data[0]`. **Field asymmetry**: Request uses `appliesToReconciliationAccount` (string UUID), response returns it as an object `{ code, currencyCode, name }`.
 90. **Bank rules search uses `/bank-rules/search`** — Standard search pattern with filter/sort/limit/offset. Filter fields: `appliesToReconciliationAccount`, `name`, `reference`, `resourceId`, `actionType`, `businessTransactionType`. Sort fields: `resourceId`, `name`, `actionType`, `businessTransactionType`, `reference`, `appliesToReconciliationAccount`, `createdAt`.
-90a. **Bank rules create field is `appliesToReconciliationAccount`** (NOT `appliesToReconciliationAccountResourceId`) — the bank account UUID. `configuration` must nest under `reconcileWithDirectCashEntry` key. `configuration.reconcileWithDirectCashEntry.reference` is REQUIRED (omitting causes GENERAL_ERROR). `amountAllocationType`: use `"PERCENTAGE"` or `"FIXED"` — `"FIXED_AND_PERCENTAGE"` is read-only (include both `fixedAllocation` + `percentageAllocation` arrays and the server infers it). Optional config fields: `contactResourceId`, `internalNotes`, `tags`, `currencySettings`, `taxCurrencySettings`, `classifierConfig` on allocation lines.
-90b. **Bank rules PUT is FULL REPLACEMENT** — `PUT /bank-rules/:id` replaces the entire rule. Must send `resourceId`, `appliesToReconciliationAccount`, and full `configuration` every time. Omitting any required field causes GENERAL_ERROR. Use read-modify-write pattern: GET current rule, merge changes, PUT full payload. Same pattern as items PUT (Rule 72) and capsules PUT (Rule 73).
+90a. **Bank rules create field is `appliesToReconciliationAccount`** (NOT `appliesToReconciliationAccountResourceId`) — the bank account UUID. `configuration` must nest under `reconcileWithDirectCashEntry` key. `configuration.reconcileWithDirectCashEntry.reference` is REQUIRED (omitting causes GENERAL_ERROR). `amountAllocationType`: use `"PERCENTAGE"` or `"FIXED"` — `"FIXED_AND_PERCENTAGE"` is read-only (include both `fixedAllocation` + `percentageAllocation` arrays and the server infers it). Optional config fields: `contactResourceId`, `internalNotes`, `tags`, `currencySettings`, `taxCurrencySettings`, `classifierConfig` on allocation lines. **Send `searchFilter` too** — see 90d; a rule without one is never suggested.
+90b. **Bank rules PUT is FULL REPLACEMENT** — `PUT /bank-rules/:id` replaces the entire rule. Must send `resourceId`, `appliesToReconciliationAccount`, and full `configuration` every time. Omitting any required field causes GENERAL_ERROR. Use read-modify-write pattern: GET current rule, merge changes, PUT full payload. Same pattern as items PUT (Rule 72) and capsules PUT (Rule 73). **`searchFilter` is the one exception**: omit it and the API keeps the stored condition, send `null` to remove it, send an object to replace it.
 90c. **Bank rule POST canonical create payload** (verified live 2026-04, NOT obvious from any single field error):
 ```json
 {
@@ -315,7 +315,7 @@ Bills, invoices, and credit notes share identical mandatory field specs. Adding
 
 **actionShortcutResourceId** for `apply_bank_rule` IS the rule's own `resourceId` from create response (no separate "action shortcut" entity).
 
-90d. **Bank rules support column-value mapping** — `reconcileWithDirectCashEntry` can resolve fields per row from a custom bank-statement column: `amountSourceColumnKey` (set amount by a column; mutually exclusive with `amount`), `organizationAccountResourceIdMap`/`taxProfileResourceIdMap`/`classifierConfigMap` on each `fixedAllocation` line, and `contactResourceIdMap`/`tagsMap` on the shortcut. Each `*Map` is a `ColumnValueMapConfig` (`columnKey` + ordered `mappings[]`, first match wins, blank `matchValue` = catch-all); `targetResourceId` is a UUID (tag NAME for `tagsMap`). `reference` also takes `{{column:<key>}}` / `{{column_abs:<key>}}` tokens. Full shape: `references/bank-rule-column-mapping.md`.
+90d. **Bank rules support column-value mapping** — `reconcileWithDirectCashEntry` can resolve fields per row from a custom bank-statement column: `amountSourceColumnKey` (set amount by a column; mutually exclusive with `amount`), `organizationAccountResourceIdMap`/`taxProfileResourceIdMap`/`classifierConfigMap` on each `fixedAllocation` line, and `contactResourceIdMap`/`tagsMap` on the shortcut. Each `*Map` is a `ColumnValueMapConfig` (`columnKey` + ordered `mappings[]`, first match wins, blank `matchValue` = catch-all); `targetResourceId` is a UUID (tag NAME for `tagsMap`). `reference` also takes `{{column:<key>}}` / `{{column_abs:<key>}}` tokens. Full shape: `references/bank-rule-column-mapping.md`. **The rule's WHEN side is the inline `searchFilter`, and without one the rule is never suggested.** Auto-reconciliation only considers rules whose stored condition is non-null, so a rule created without it exists, lists, and applies manually, but is never offered. Shape: `{"version": 1, "raw": "description:grab", "parsed": {"description": {"contains": "grab"}}}` — `raw` is the one-line form shown in the app and **may be blank**; `parsed` is what the matcher compiles. Condition fields: `description`, `extReference`, `extContactName`, `netAmount`, `valueDate`, plus the account's active custom Bank Fields. Operators (15, from the matcher's own map): TEXT `eq`/`contains`/`notContains`/`startWith`/`notStartWith`/`isBlank`/`isNotBlank`, compared case-insensitively, the blank pair taking no value; NUMERIC `eq`/`gt`/`gte`/`lt`/`lte`/`inRange`/`notInRange`; DATE `eq`/`gt`/`gte`/`lt`/`lte`/`between`/`notBetween`. Combine with `{"and": {...}}` or `{"orGroup": [{"and": {...}}]}`. **An unsupported field path does not error** — the rule saves, lists, and then never fires, because the matcher logs a warning server-side and skips it; use only the fields above. `relatedSearchShortcutResourceIds` (the retired saved-search path) is not exposed by this API at all; the platform rejects a request that sets both.
 
 ### Fixed Assets
 91. **Fixed asset search does NOT support `createdAt` sort** — Valid sort fields: `resourceId`, `name`, `purchaseDate`, `typeName`, `purchaseAmount`, `bookValueNetBookValueAmount`, `depreciationMethod`, `status`. Using `createdAt` returns 422. Default to `purchaseDate` DESC.

package/assets/skills/api/references/bank-rule-column-mapping.md

@@ -6,7 +6,7 @@ A bank rule's `reconcileWithDirectCashEntry` shortcut can resolve fields **per r
 
 The columns referenced by `columnKey` are **Bank Fields** — typed custom columns (`DATE` / `STRING` / `AMOUNT`) defined per bank account and captured when a statement is imported. They make any statement column (branch code, bank charge, cost centre, settlement ref) first-class: usable in a rule's **conditions** (matching) and in its **outputs** (the maps below). `AMOUNT` fields keep their sign; `amountSourceColumnKey` uses the **absolute** value.
 
-Scope note: the maps here are the rule **outputs** (what `create_bank_rule` / `update_bank_rule` set via `configuration`). The rule **conditions** (which statement lines the rule matches, including by Bank Field) are held in a linked search shortcut (`relatedSearchShortcutResourceIds`) configured in the product, not by these tools.
+Scope note: the maps here are the rule **outputs** (what `create_bank_rule` / `update_bank_rule` set via `configuration`). The rule **conditions** (which statement lines the rule matches) are a separate field, `searchFilter`, which those same tools now set directly — `{ version: 1, raw, parsed }`, and a rule without one is never suggested by magic reconciliation. See jaz-api skill rule 90d for the condition grammar. The older linked-search-shortcut path (`relatedSearchShortcutResourceIds`) was retired upstream and is not exposed by this API.
 
 ## ColumnValueMapConfig shape
 

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

@@ -2535,4 +2535,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).
 

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 5.59.0
+version: 5.59.2
 description: >-
   Use this skill when running Clio CLI commands, building shell scripts with
   Clio, debugging auth issues, understanding --json output, paginating results,
@@ -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`
 

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

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

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 5.59.0
+version: 5.59.2
 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.0
+version: 5.59.2
 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.0
+version: 5.59.2
 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.0
+version: 5.59.2
 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/bank-recon.md

@@ -192,11 +192,24 @@ After creating, loop back to step 4 to reconcile.
 ```
 create_bank_rule(
   name: 'Monthly DBS Service Charge',
-  matchCriteria: {description: {contains: 'service charge'}, amount: {between: [20, 30]}},
-  action: 'RECONCILE_WITH_DIRECT_CASH_ENTRY',
-  cashEntryTemplate: {accountResourceId: <Bank Charges>, ...}
+  appliesToReconciliationAccount: '<bank-account-uuid>',
+  searchFilter: {
+    version: 1,
+    raw: 'description:service charge',
+    parsed: {and: {description: {contains: 'service charge'}, netAmount: {inRange: [20, 30]}}}
+  },
+  configuration: {
+    reconcileWithDirectCashEntry: {
+      reference: 'AUTO-{{bankReference}}',
+      amountAllocationType: 'PERCENTAGE',
+      percentageAllocation: [{organizationAccountResourceId: '<Bank Charges uuid>', amount: 100}]
+    }
+  }
 )
 ```
+`searchFilter` is the WHEN side and is what makes the rule eligible for suggestion at all — a rule
+without one is never offered by auto-reconciliation. `configuration` is the THEN side. Condition
+fields: `description`, `extReference`, `extContactName`, `netAmount`, `valueDate`.
 Next month's same charge auto-reconciles via `apply_bank_rule`.
 
 **Path D — flag for investigation:** if no match and no source document, surface to the user with the `extContactName + description` and the `netAmount`. Common: personal transactions, refunds, intercompany unrecorded, bank-feed errors. Record the unresolved item so it carries forward.

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

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