jaz-clio 7.0.1 → 9.0.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-382-blue?style=for-the-badge" alt="382 tools">
+  <img src="https://img.shields.io/badge/tools-387-blue?style=for-the-badge" alt="387 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>Fastest ledger for agents.</b><br>Jaz accounting on the command line, and inside any AI agent.</p>
 
-382 tools · 74 command groups · 7 skills · 13 calculators · 12 job playbooks · 148 field-tested API rules.
+387 tools · 74 command groups · 7 skills · 13 calculators · 12 job playbooks · 148 field-tested API rules.
 
 ```bash
 npm install -g jaz-clio
@@ -109,7 +109,7 @@ that ends up in a journal.
 
 ## MCP server
 
-382 tools for any AI agent that speaks MCP. Runs locally: no cloud, no ports.
+387 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: 7.0.1
+version: 9.0.0
 description: >-
   Use this skill whenever you call, debug, or review code that touches the Jaz
   REST API. Covers field names, response shapes, 148 production gotchas, error
@@ -170,7 +170,7 @@ The rest of this skill (field names, gotchas, error catalog, dependency order, s
 42. **Scheduler GET returns `interval`**; POST uses `repeat`. (Response-side asymmetry remains.)
 43. **Search sort is an object**: `{ sort: { sortBy: ["valueDate"], order: "DESC" } }`. Required when `offset` is present (even `offset: 0`).
 44. **Bank records**. **Create**: Multipart CSV/OFX via `POST /magic/importBankStatementFromAttachment` or JSON via `POST /bank-records/:accountResourceId` with `{ records: [{amount, transactionDate, description?, payerOrPayee?, reference?}] }` (positive = cash-in, negative = cash-out, response: `{data: {errors: []}}`). **Search**: `POST /bank-records/:accountResourceId/search`; filter fields: `valueDate` (DateExpression), `status` (StringExpression: UNRECONCILED, RECONCILED, ARCHIVED, POSSIBLE_DUPLICATE), `description`, `extContactName` (payer/payee), `extReference`, `netAmount` (BigDecimalExpression), `extAccountNumber`. Sort by `valueDate` DESC default.
-45. **Withholding tax** on bills/supplier CNs only. Retry pattern: if `WITHHOLDING_CODE_NOT_FOUND`, strip field and retry.
+45. **Withholding tax (PH) has two sides.** Expanded withholding (EWT) on what you pay sits on each bill / supplier credit note line as `withholdingTax`: copy `code`, `rate`, `type` and `description` from one `list_withholding_codes` row (a field left out is not stored, measured 2026-10-06). Creditable withholding (CWT) a customer deducts is recorded from the customer's BIR Form 2307 with `record_withholding_tax_certificate`, never on the invoice lines (rule 98). On `WITHHOLDING_CODE_NOT_FOUND`, check the code against `list_withholding_codes` (codes contain a space: `WC 158`); never strip the field silently, because the tax disappears from the bill.
 46. **Known API bugs (500s)**: none on this list today. **Capsules POST, catalogs POST, inventory balances by status GET, contact groups PUT and custom fields PUT are NO LONGER on this list.** Capsules POST creates the capsule and returns its `resourceId`. Catalogs POST returned 201 on a live probe 2026-09-23 (item `unit` omitted, it is optional); its response is counts (`createdCatalogs`, `createdCatalogItems`), not a resourceId, so find the new catalog with `search_catalogs`. Inventory balances by status works (Rule 97). Contact groups PUT and custom fields PUT were re-probed live 2026-09-02 and returned 200 and applied the change. Do not route around any of them.
 47. **Non-existent endpoints**: `POST /inventory/adjustments` (and `/inventory-adjustments`, `/inventory-items/:id/adjustments`, `/items/:id/inventory-adjustments`; no stock-adjustment write path exists at any spelling), `GET /payments` (list), and `POST /payments/search` return 404; these endpoints are not implemented. For payments, per-payment CRUD is `GET/PUT/DELETE /payments/:resourceId` and there ARE two payment-scoped searches; see Rule 64. `POST /deposits` also 404s, but for a different reason, see Rule 47a; do not read it as a missing feature.
 47a. **Deposits are not an entity; the 404 on `/deposits` is by design.** A deposit is a **flag on a Chart of Accounts account**, not a document: the account carries `depositContactType` = `CUSTOMER` (advance received, a liability) or `SUPPLIER` (advance paid, an asset). Once flagged, a deposit movement is an **ordinary transaction against that account**: top up with `POST /journals` / `POST /cash-in-entries` / `POST /cash-out-entries` (one leg on the flagged account), draw down with `POST /invoices/:id/payments` or `POST /bills/:id/payments` passing `accountResourceId` = the flagged account **and `paymentMethod` set to something other than BANK_TRANSFER / CASH / CHEQUE** (use `OTHER`; those three force a bank/cash account and 422 here, see Rule 80), read with `POST /cashflow-transactions/search`. **Flagging the account is a web-app action**: `depositContactType` is on no chart-of-accounts request or response model here, and the platform-backend mutation that sets it (`configureDepositAccounts`) is not proxied, so `POST /chart-of-accounts` cannot create a deposit account. Over the API you can only read and post against an account someone already flagged. Full walkthrough: `references/endpoints.md` → Deposits.
@@ -201,7 +201,7 @@ The rest of this skill (field names, gotchas, error catalog, dependency order, s
 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.
+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. The cashflow ledger tool is `search_cashflow_transactions`; its `resourceId` is a ledger row, not a payment record, so it 404s on `get_payment` / `update_payment`, which take a document's `paymentRecords` id. The per-side payment searches (b) have no tool; reach them with a raw request. (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.
 65. **Contacts search uses `name`**, NOT `billingName`. The filter field for searching contacts by name is `name` (maps to `billingName` internally). Sort field is also `name`. Using `billingName` in a search filter returns zero results.
 
 ### Response Shape Gotchas
@@ -334,7 +334,7 @@ Bills, invoices, and credit notes share identical mandatory field specs. Adding
 97. **Inventory balances: one item or all.** One item: `GET /inventory-item-balance/:itemResourceId` (`get_inventory_balance`) returns `{ itemResourceId, latestAverageCostAmount, baseQty, baseUnit }`; the id is the ITEM resourceId, not an inventory-specific ID. All items: `GET /inventory-balances/:balanceStatus` (`list_inventory_balances`, `clio inventory balances --status`) with `balanceStatus` one of `ALL`, `AVAILABLE`, `FULLY_DRAWN` (anything else is 422); rows carry `itemCode`, `internalName`, `totalQuantity`, `baseUnit`, `averageCostAmount`, `balanceAmount`. The API answers an empty result with 404; the tool and CLI return it as `data: []`. `offset` is a page number here, though the spec says row (probed live 2026-09-23).
 
 ### Withholding Tax
-98. **Withholding tax codes via `GET /withholding-tax-codes`**: Returns a flat array of 1,360+ entries (PH PSIC codes). Each entry: `{ code, description, taxRate, ... }`. No pagination; full list in one call. Use for PH/SG tax compliance.
+98. **Withholding codes are `GET /withholding-codes`** (`list_withholding_codes`, `clio tax-profiles withholding-codes`): the BIR ATCs with `code`, `rate`, `rateType`, `type` (corp, ind, final, wvat), `description` and `resourceId`; filters `countryCode`, `code` (contains, space included) and `type`; `limit` max 100, `offset` is a page. `GET /withholding-tax-codes` is a different list (MSIC/PSIC industry codes) that no withholding field accepts. A customer's 2307 is a sale batch payment with method `WITHHOLDING_TAX_CERTIFICATE` (`record_withholding_tax_certificate`): PH orgs only, sales only, account = the system "Creditable Withholding Tax" account, one allocation per code by `resourceId`, and each allocation's `baseAmount` is the TAX WITHHELD (the dashboard's "Withholding" column; `amount` is the income); the `baseAmount`s must add up to the payment total within 0.01.
 99. **Duplicate detection fields**. API rejects duplicates with 422: Contacts on `name` (NOT `billingName`), Items on `itemCode`, Accounts on `name`, Tax Profiles on `name`. Agent tools auto-search before creating; if a match is found, the existing entity is returned instead of hitting a 422.
 
 ### Tax Profile Scoping

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

@@ -643,7 +643,7 @@ The `payments` array uses the same 6-field structure as standalone payments. pro
 
 ### Withholding Tax on Line Items
 
-Bills and supplier credit notes support withholding tax per line item:
+Bills and supplier credit notes support expanded withholding tax (EWT, Philippines) per line item. Copy `code`, `rate`, `type` and `description` from one `GET /withholding-codes` row (`list_withholding_codes`); a field left out is not stored:
 
 ```json
 {
@@ -653,15 +653,18 @@ Bills and supplier credit notes support withholding tax per line item:
     "quantity": 1,
     "accountResourceId": "expense-uuid",
     "withholdingTax": {
-      "code": "WC010",
-      "rate": 10,
-      "description": "Professional fees"
+      "code": "WC 158",
+      "rate": 1,
+      "type": "corp",
+      "description": "Income Payment Made By Top Withholding Agents To Their Local/Resident Supplier Of Goods Other Than Those Covered By Other Rates Of Withholding Tax"
     }
   }]
 }
 ```
 
-**Retry pattern**: If the organization doesn't support withholding tax, the API returns `WITHHOLDING_CODE_NOT_FOUND`. On this error, remove the `withholdingTax` field from all line items and retry the request.
+**On `WITHHOLDING_CODE_NOT_FOUND`**: check the code against `list_withholding_codes` (codes contain a space). If the organization does not use withholding (non-PH), remove `withholdingTax` and say so; never strip it silently. See errors.md.
+
+Customer-side withholding (CWT) is not a line field: record the customer's BIR Form 2307 with `record_withholding_tax_certificate` (`POST /sales/batch-payments`, `paymentMethod: WITHHOLDING_TAX_CERTIFICATE`, `ph2307Details`). SKILL.md rule 98 has the rules.
 
 ---
 

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

@@ -749,13 +749,7 @@ The same applies on update: `PUT /cash-in-entries/:id` with `saveAsDraft: true`
 **Request**: POST /api/v1/bills with `withholdingTax` on line items
 **Error**: `"WITHHOLDING_CODE_NOT_FOUND"` or similar withholding-related error
 **Cause**: The organization does not have withholding tax enabled, or the code is invalid for this region.
-**Fix**: Remove the `withholdingTax` field from ALL line items and retry. This is a common pattern for cross-region compatibility: Singapore orgs typically don't use withholding tax, but Philippines orgs do.
-
-**Retry pattern** (from production):
-1. Submit bill/credit note with `withholdingTax` fields
-2. If error contains "WITHHOLDING" (case-insensitive), strip `withholdingTax` from all line items
-3. Retry the same request without withholding tax
-4. Log which org doesn't support withholding tax to avoid future retries
+**Fix**: First check the code against `list_withholding_codes` (`GET /withholding-codes`): codes contain a space (`WC 158`, not `WC158`). If the organization does not use withholding (Singapore orgs typically don't; Philippines orgs do), remove `withholdingTax` from the line items, retry, and tell the user the bill was recorded without it. Never strip it silently: the withholding disappears from the bill.
 
 ---
 

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

@@ -231,7 +231,7 @@ Fixed assets lock their linked line items: cannot edit account, amounts, or exch
 
 **User Roles**: Admin (full access), Preparer (create drafts, submit for approval), Member (own drafts only). Granular permissions by module (AR, AP, Treasury, Journals).
 
-**API**: CRUD `GET/POST/PUT/DELETE /chart-of-accounts`, `POST /chart-of-accounts/bulk-upsert`, `POST /chart-of-accounts/search`, `GET /tax-profiles`, `POST /tax-profiles/search`, CRUD `GET/POST/PUT/DELETE /tags`, `POST /tags/search`, CRUD `GET/POST/PUT/DELETE /custom-fields`, `POST /custom-fields/search`, `POST /organization/currencies` (enable), `DELETE /organization/currencies/:code` (disable), `POST /organization/currencies/:code/rates` (set FX rate, CRUD), `GET /organization` (org details), CRUD `GET/POST/PUT/DELETE /organization/bookmarks`, CRUD `GET/POST/PUT/DELETE /nano-classifiers`, `POST /nano-classifiers/search`, `GET /organization-users`, `POST /organization-users/search`. Reference data: `GET /account-classifications`, `GET /withholding-tax-codes`, `GET /tax-types`, `GET /modules`
+**API**: CRUD `GET/POST/PUT/DELETE /chart-of-accounts`, `POST /chart-of-accounts/bulk-upsert`, `POST /chart-of-accounts/search`, `GET /tax-profiles`, `POST /tax-profiles/search`, CRUD `GET/POST/PUT/DELETE /tags`, `POST /tags/search`, CRUD `GET/POST/PUT/DELETE /custom-fields`, `POST /custom-fields/search`, `POST /organization/currencies` (enable), `DELETE /organization/currencies/:code` (disable), `POST /organization/currencies/:code/rates` (set FX rate, CRUD), `GET /organization` (org details), CRUD `GET/POST/PUT/DELETE /organization/bookmarks`, CRUD `GET/POST/PUT/DELETE /nano-classifiers`, `POST /nano-classifiers/search`, `GET /organization-users`, `POST /organization-users/search`. Reference data: `GET /account-classifications`, `GET /withholding-codes` (withholding ATCs), `GET /withholding-tax-codes` (MSIC/PSIC industry codes), `GET /tax-types`, `GET /modules`
 
 ---
 

package/assets/skills/api/references/field-map.md

@@ -208,11 +208,14 @@ COGS maps to `"Direct Costs"`; "Cost of Goods Sold" is the default account name
 | What You'd Guess | Actual API Field | Notes |
 |---|---|---|
 | `tax` | `withholdingTax` | Nested object on each line item |
-| `withholdingTaxCode` | `withholdingTax.code` | String code (e.g., "WC010") |
-| `withholdingTaxRate` | `withholdingTax.rate` | Numeric percentage (e.g., 10) |
-| `withholdingTaxDescription` | `withholdingTax.description` | Optional description |
+| `withholdingTaxCode` | `withholdingTax.code` | The ATC, space included (e.g., "WC 158") |
+| `withholdingTaxRate` | `withholdingTax.rate` | Numeric percentage (e.g., 1) |
+| `withholdingTaxType` | `withholdingTax.type` | corp, ind, final or wvat |
+| `withholdingTaxDescription` | `withholdingTax.description` | The code's description |
 
-**Not supported on**: Invoices, customer credit notes, journals, cash entries. Only bills and supplier credit notes.
+Copy all four from one `list_withholding_codes` row; a field left out is not stored on the line.
+
+**Line-level only on**: bills and supplier credit notes (EWT). Customer-side withholding (CWT) on invoices is recorded from the customer's BIR Form 2307 with `record_withholding_tax_certificate`, not on invoice lines.
 
 ---
 

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 468 spec paths and 599 spec operations and is the authoritative list; check it before concluding
+> carries 475 spec paths and 607 spec 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.
 >
@@ -848,11 +848,12 @@ incomplete. Reaching them needs a raw HTTP call.
 | POST | `/bank-records/:accountResourceId/archive` | Archive bank records |
 | POST | `/bank-records/:accountResourceId/unarchive` | Unarchive bank records |
 
-### Withholding (1): 2026-07-31
+### Withholding (2): 2026-07-31, withholding-codes 2026-10-06
 
 | Method | Path | Description |
 |--------|------|-------------|
 | POST | `/payments/withholding` | Record withholding on a sale / sale credit note payment (see SKILL.md Rule 45) |
+| GET | `/withholding-codes` | Withholding codes (BIR ATCs) for line `withholdingTax` and 2307 allocations (Rule 98) |
 
 ---
 

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

@@ -18,7 +18,7 @@ Two MCP namespaces wrap these: **`sale_orders`** (Sale Quotes + Sale Orders) and
 | `PURCHASE_REQUEST` | DRAFT (default) / ACTIVE (saveAsDraft:false) | **accept** (ACTIVE → ACCEPTED) | VOID | yes (default true) |
 | `PURCHASE_ORDER` | DRAFT (default) / ACTIVE (saveAsDraft:false) | **confirm** → CONFIRMED | VOID | yes (default true) |
 
-- **Quotes & Requests use `accept`. Orders use `confirm`.** (`transition_*` enforces this via a documentType × action matrix.)
+- **Quotes & Requests use `accept`. Orders use `confirm`.** Each is its own tool: `accept_sale_quote`, `confirm_sale_order`, `accept_purchase_request`, `confirm_purchase_order`.
 - **`accept` works on the ISSUED state, not DRAFT**: a Sale Quote must be CREATED, a Purchase Request must be ACTIVE. Accepting a DRAFT returns `422 Invalid status` (verified live). **Issue an existing DRAFT in place** with the update tool's flag: `update_sale_order` `isDraftToActiveSaleQuote: true` (→ CREATED), `update_purchase_order` `isDraftToActivePurchaseRequest: true` (→ ACTIVE). Send every stored line with its `resourceId` in the SAME update: a flag-only update is refused with `422 SALE_LINE_ITEMS_REQUIRED` (verified live 2026-09-23 on a sale quote). It keeps the document's number and line ids (verified live: DRAFT → CREATED, same reference, same line `resourceId`; a line without an account issued fine), so never create a second quote/request to issue one. (Update with `saveAsDraft:false` does NOT issue a DRAFT, verified live.) To create one already issued, pass `saveAsDraft:false` on create.
 - **Sale Orders have no draft state**: `saveAsDraft` is ignored; created directly as `CREATED`.
 - **PENDING orders.** Jaz Magic creates Sale Orders and Purchase Orders as `PENDING`. Take one live with `update_sale_order` `isPendingToActiveSaleOrder: true` / `update_purchase_order` `isPendingToActivePurchaseOrder: true`. Search accepts `status: PENDING`.
@@ -85,13 +85,13 @@ To change a few fields on some lines without resending the document, use `quick_
 
 ## Delete vs Void
 
-- **DELETE is draft-only** (422 on anything non-draft). `transition_* action:DELETE` pre-flights status and returns a `repair` hint to use `VOID` for non-draft records.
-- **VOID** cancels any non-draft quote/request/order; optional `internalNotes` reason.
+- **DELETE is draft-only** (422 on anything non-draft). `delete_sale_order` / `delete_purchase_order` pre-flight the status and return a `repair` pointing at the void tool for a non-draft record.
+- **VOID** (`void_sale_order` / `void_purchase_order`) cancels any non-draft quote/request/order; optional `internalNotes` reason.
 
 ## MCP tools
 
-`sale_orders`: `create_sale_order`, `get_sale_order`, `search_sale_orders`, `search_sale_order_line_items`, `update_sale_order`, `transition_sale_order` (action: ACCEPT | CONFIRM | VOID | DELETE), `convert_sale_order_to_invoice`.
-`purchase_orders`: `create_purchase_order`, `get_purchase_order`, `search_purchase_orders`, `search_purchase_order_line_items`, `update_purchase_order`, `transition_purchase_order`, `convert_purchase_order_to_bill`.
+`sale_orders`: `create_sale_order`, `get_sale_order`, `search_sale_orders`, `search_sale_order_line_items`, `update_sale_order`, `accept_sale_quote`, `confirm_sale_order`, `void_sale_order`, `delete_sale_order`, `convert_sale_order_to_invoice`.
+`purchase_orders`: `create_purchase_order`, `get_purchase_order`, `search_purchase_orders`, `search_purchase_order_line_items`, `update_purchase_order`, `accept_purchase_request`, `confirm_purchase_order`, `void_purchase_order`, `delete_purchase_order`, `convert_purchase_order_to_bill`.
 
 PDF downloads for the documents these convert into: `download_bill_pdf` (`bills`), `download_supplier_credit_note_pdf` (`supplier_credit_notes`), alongside the existing `download_invoice_pdf` / `download_credit_note_pdf`.
 

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 7.0.1
+version: 9.0.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
-  74 command groups and 382 tools, including employee-expense claims.
+  74 command groups and 387 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. 74 command groups, 13 calculators, 12 job playbooks (jaz-jobs skill), 382 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 playbooks (jaz-jobs skill), 387 tools. Also fully compatible with Juan Accounting (same API, same endpoints).
 
 ## When to Use This Skill
 

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

@@ -103,11 +103,9 @@ Same subcommands and flags as `cash-in`.
 | `create` | `--from-account`, `--to-account`, `--amount`, `--date`, `--ref` (generated when omitted), `--input` |
 | `delete <id>` | |
 
-### `clio payments`: Cashflow transactions (read-only)
+### `clio payments`: Payment records (search the ledger with `clio cashflow search`)
 | Subcommand | Key flags |
 |------------|-----------|
-| `list` | `--limit`, `--offset`, `--all`, `--format`, `--json` |
-| `search` | `--from`, `--to`, `--type`, `--direction`, `--ref`, `--sort`, `--order` |
 | `get <id>` | `--json` |
 | `update <id>` | `--date`, `--reference`, `--input` |
 | `delete <id>` | |
@@ -194,7 +192,7 @@ Same subcommands and flags as `cash-in`.
 | `create` | `--rate`, `--name`, `--tax-type-code` |
 | `update <id>` | `--name`, `--rate` |
 | `types` | List available tax type codes |
-| `wht-codes` | List withholding tax codes |
+| `withholding-codes` | List withholding codes (BIR ATCs) for a bill line's withholding tax and a Withholding Tax Certificate (2307) |
 
 ### `clio filing-submissions`: Tax return filings (read-only, 1 tool)
 | Subcommand | Key flags |
@@ -727,7 +725,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 382 operations.
+Starts an MCP server for Claude Code / AI tool integration. Exposes all 387 operations.
 
 ### `clio init`: Skill installer
 Installs AI agent skills into your project.

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 7.0.1
+version: 9.0.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: 7.0.1
+version: 9.0.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: 7.0.1
+version: 9.0.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: 7.0.1
+version: 9.0.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/payment-run.md

@@ -10,9 +10,9 @@
 - **`generate_bank_balance_summary(primarySnapshotDate: <cutoff>)`**, used in step 5: confirm cash availability before approving the batch.
 - **`get_contact(resourceId: <contactResourceId>)`**, used in step 4 (per supplier): pull payment terms / preferred payment method / bank details (especially `taxId`, `bankAccountNumber`, `bicSwift` for GIRO file generation).
 - **`pay_bill(resourceId: <id>, paymentAmount, transactionAmount, accountResourceId, valueDate, ...)`**, used in step 6: post the payment per bill. NO BATCH PAYMENT ENDPOINT yet; one POST per bill.
-- **`search_payments(filter: {businessTransactionReference: {startWith: <run-prefix>}, valueDate: {eq: <run-date>}})`**, used in step 8: idempotency / verification check (re-running the run won't duplicate-pay if all references match).
+- **`search_cashflow_transactions(filter: {businessTransactionReference: {startWith: <run-prefix>}, valueDate: {eq: <run-date>}})`**, used in step 8: idempotency / verification check (re-running the run won't duplicate-pay if all references match).
 
-  > **The field and the operator are both exact.** `search_payments` hits `POST /cashflow-transactions/search` → `TransactionsFilter`, which declares no `additionalProperties`, so an undeclared field is rejected outright rather than ignored. It has **no `reference`** (that is `businessTransactionReference`) and `StringExpression` has **no `startsWith`**: the prefix operator is spelled **`startWith`**, no "s". Until 5.55.3 this line asked for both wrong names, so the idempotency check (the step standing between a re-run and paying every supplier twice) could not return anything. Use `startWith`, not `contains`: measured on the sandbox 2026-09-07, `contains: 'PR-'` matched 3 rows that do **not** start with that prefix, and a looser match here silently widens what the run treats as already-paid.
+  > **The field and the operator are both exact.** `search_cashflow_transactions` hits `POST /cashflow-transactions/search` → `TransactionsFilter`, which declares no `additionalProperties`, so an undeclared field is rejected outright rather than ignored. It has **no `reference`** (that is `businessTransactionReference`) and `StringExpression` has **no `startsWith`**: the prefix operator is spelled **`startWith`**, no "s". Until 5.55.3 this line asked for both wrong names, so the idempotency check (the step standing between a re-run and paying every supplier twice) could not return anything. Use `startWith`, not `contains`: measured on the sandbox 2026-09-07, `contains: 'PR-'` matched 3 rows that do **not** start with that prefix, and a looser match here silently widens what the run treats as already-paid.
 - **`finalize_bill(resourceId: <id>)`**, used in step 0 fallback: bills must be `status: APPROVED` (not `DRAFT`) before they accept payments.
 
 ### CLI tools (jaz-cli)
@@ -30,7 +30,7 @@
 Generate a run prefix: `PAYRUN-<YYYY-MM-DD>-<seq>`. Before proceeding:
 
 ```
-search_payments(filter: {businessTransactionReference: {startWith: 'PAYRUN-2025-02-28-'}})
+search_cashflow_transactions(filter: {businessTransactionReference: {startWith: 'PAYRUN-2025-02-28-'}})
 ```
 
 If results: surface "A payment run with prefix `PAYRUN-2025-02-28-*` already executed on this date (`<n>` payments totalling `<amt>`). Confirm intent; re-run will create duplicate payments." Halt unless practitioner confirms.
@@ -117,13 +117,13 @@ After all `pay_bill` calls succeed:
 
 ```
 generate_aged_payables(endDate: '2025-02-28')
-search_payments(filter: {businessTransactionReference: {startWith: 'PAYRUN-2025-02-28-'}, valueDate: {eq: '2025-02-28'}})
+search_cashflow_transactions(filter: {businessTransactionReference: {startWith: 'PAYRUN-2025-02-28-'}, valueDate: {eq: '2025-02-28'}})
 ```
 
 Assert:
 - AP aging total reduced by `sum(payments.transactionAmount)` (in base currency, FX-converted at value date).
 - Bills fully paid no longer appear in aging; partials carry the payment in `paymentRecords[]`; derive outstanding from it.
-- `search_payments` returns N rows where N = bills paid in step 6.
+- `search_cashflow_transactions` returns N rows where N = bills paid in step 6.
 
 ```
 generate_bank_balance_summary(primarySnapshotDate: '2025-02-28')
@@ -141,7 +141,7 @@ Assert: per-account balance reduced by `sum(paymentAmount per accountResourceId)
 | `pay_bill` | 422 `currency_mismatch` | `paymentAmount` currency ≠ bank account currency. Either pay from the matching-currency bank account, or model as FX (different `paymentAmount` and `transactionAmount`). |
 | `pay_bill` | 422 `bill_already_paid` | Bill went `PAID` since step 2. Re-run `search_bills` for fresh state; remove from batch. |
 | `pay_bill` | 422 `lock_date_violated` | `valueDate` is in a locked period. Either lift the lock via `update_account` lock_date OR adjust `valueDate` to the next open period. |
-| `pay_bill` | 500 mid-run | Some payments succeeded; others didn't. NOT idempotent; re-running the loop creates duplicates. Use `search_payments` with the run prefix to identify what succeeded; resume from the next unprocessed bill. Record the judgment: `jot(kind: RECOVERY)` naming the resume point and the bills already paid. |
+| `pay_bill` | 500 mid-run | Some payments succeeded; others didn't. NOT idempotent; re-running the loop creates duplicates. Use `search_cashflow_transactions` with the run prefix to identify what succeeded; resume from the next unprocessed bill. Record the judgment: `jot(kind: RECOVERY)` naming the resume point and the bills already paid. |
 | `generate_aged_payables` | Total mismatch with `search_bills` | Likely `PARTIALLY_PAID` bills excluded from `search_bills` filter. Add `status: {in: ['UNPAID', 'PARTIALLY_PAID']}` and retry. |
 
 ---

package/assets/skills/jobs/references/supplier-recon.md

@@ -8,7 +8,7 @@
 - **`search_contacts(filter: {supplier: true, name: {eq: <supplier>}})`** (step 1): resolve the supplier resourceId. Use fuzzy match if exact fails.
 - **`get_contact(resourceId: <supplier id>)`** (step 1 detail): pull the supplier's payment terms, contact info.
 - **`search_bills(filter: {contact: {resourceId: {eq: <supplier id>}}, valueDate: {between: [<period-start>, <period-end>]}}, limit: 200)`** (step 2): pull all bills from this supplier in the period. Paginate.
-- **`search_payments(filter: {contact: {resourceId: {eq: <supplier id>}}, valueDate: {between: [<period-start>, <period-end>]}, direction: {eq: 'PAYOUT'}})`** (step 3): pull all payments to this supplier.
+- **`search_cashflow_transactions(filter: {contact: {resourceId: {eq: <supplier id>}}, valueDate: {between: [<period-start>, <period-end>]}, direction: {eq: 'PAYOUT'}})`** (step 3): pull all payments to this supplier.
 - **`search_supplier_credit_notes(filter: {contact: {resourceId: {eq: <supplier id>}}, valueDate: {between: [<period-start>, <period-end>]}})`** (step 4): pull credit notes that may have been applied.
 
   > **A filter value must be an OBJECT, not a bare scalar.** This is the trap these lines fell into:
@@ -17,7 +17,7 @@
   > **is** declared on bills, supplier credit notes and invoices; it is typed `StringExpression`, so it
   > needs an operator: `{eq: <id>}`. Measured 2026-09-07: the bare form 400s on both, `{eq: …}` returns
   > 200 on both. The nested `contact: {resourceId: {eq: <id>}}` form used above also works and is what
-  > `search_payments` requires, because `TransactionsFilter` is the one of the four that genuinely does
+  > `search_cashflow_transactions` requires, because `TransactionsFilter` is the one of the four that genuinely does
   > **not** declare `contactResourceId`; there, and only there, the field really is absent.
   >
   > The amount filter differs by endpoint: `totalAmount` is accepted on bills and on
@@ -67,7 +67,7 @@ For an opening-balance recon: also pull the supplier's pre-period balance via `g
 ## Step 3: Pull payments
 
 ```
-search_payments(filter: {contact: {resourceId: {eq: <supplier id>}}, valueDate: {between: ['2025-01-01', '2025-01-31']}, direction: {eq: 'PAYOUT'}})
+search_cashflow_transactions(filter: {contact: {resourceId: {eq: <supplier id>}}, valueDate: {between: ['2025-01-01', '2025-01-31']}, direction: {eq: 'PAYOUT'}})
 ```
 
 Per payment: `{resourceId, reference, valueDate, paymentAmount, transactionAmount, paymentMethod, billResourceId}`. Save.
@@ -98,7 +98,7 @@ Practitioner provides the supplier's statement (PDF, email, paper). Per-line-ite
 | Bill in Jaz, not on supplier statement | Supplier hasn't issued / lost the invoice | Verify with supplier; if confirmed bogus, `delete_bill` (DRAFT) OR `create_supplier_credit_note` (if ACTIVE). |
 | Different amounts on same reference | Pricing dispute | Practitioner contacts supplier for clarification. Possible adjustment journal post-resolution. |
 | Bill paid per Jaz, supplier says unpaid | Bank reconciliation gap | Pull bank statement for the payment date; verify the wire/cheque cleared. If cleared, send remittance proof to supplier. |
-| Bill unpaid per Jaz, supplier says paid | Payment recorded against wrong supplier OR bill | Audit `search_payments(filter: {valueDate: {eq: <date>}, totalAmount: {eq: <amount>}})`; identify mis-routing; post correcting journal OR re-issue payment. |
+| Bill unpaid per Jaz, supplier says paid | Payment recorded against wrong supplier OR bill | Audit `search_cashflow_transactions(filter: {valueDate: {eq: <date>}, totalAmount: {eq: <amount>}})`; identify mis-routing; post correcting journal OR re-issue payment. |
 | Supplier credit note not in Jaz | Missed credit | `create_supplier_credit_note(...)` per supplier statement. Then `apply_credits_to_bill(...)` to the offsetting bill. |
 | Currency mismatch | FX bills with different rates | Confirm Jaz used the right rate per `jaz-api/SKILL.md` rule 25; the supplier statement may use spot rate, Jaz uses recorded rate. Document the FX gap. |
 

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

@@ -1,6 +1,6 @@
 ---
 name: jaz-recipes
-version: 7.0.1
+version: 9.0.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,11 +4,11 @@ Jaz accounting guidance for this workspace. Load the installed Jaz skills for de
 
 ## Discovery
 
-Jaz exposes **382 tools across 49 namespaces**. Your tool list shows **3, 49, or 382** entries depending on packaging; **never infer capability from its length.**
+Jaz exposes **387 tools across 49 namespaces**. Your tool list shows **3, 49, or 387** 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.
 - **49**: namespace routers; call one with `{ operation, arguments }`. Its description lists its operations.
-- **382**: call operations directly by name.
+- **387**: call operations directly by name.
 
 `describe_capabilities` returns the capability map on all three. **Call it before telling the user Jaz cannot do something.**