jaz-clio 4.58.5 → 5.0.0

package/README.md

@@ -3,11 +3,11 @@
 <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-266-blue?style=for-the-badge" alt="266 Tools">
+  <img src="https://img.shields.io/badge/tools-265-blue?style=for-the-badge" alt="265 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>
 
-266 tools. 13 financial calculators. 12 job playbooks. 130 API rules. 16 IFRS recipes.
+265 tools. 13 financial calculators. 12 job playbooks. 130 API rules. 16 IFRS recipes.
 
 ```bash
 npm install -g jaz-clio
@@ -19,7 +19,7 @@ Requires **Node.js 18+** ([nodejs.org](https://nodejs.org)). Also fully compatib
 
 - [Three Ways In](#three-ways-in) — CLI, MCP, Skills
 - [CLI](#cli) — 53 command groups
-- [MCP Server](#mcp-server) — 266 tools for AI agents
+- [MCP Server](#mcp-server) — 265 tools for AI agents
 - [Skills](#skills) — Teach any AI the Jaz API
 - [Setup](#setup) — Auth, multi-org, automation
 
@@ -51,7 +51,7 @@ clio search "overdue"                             # Find it across all entities
 
 ## MCP Server
 
-266 CLI tools, available to any AI agent that speaks MCP. Runs locally — no cloud, no ports.
+265 CLI tools, available to any AI agent that speaks MCP. Runs locally — no cloud, no ports.
 
 **Claude Code:**
 ```bash

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 4.58.5
+version: 5.0.0
 description: >-
   Use this skill whenever you call, debug, or review code that touches the Jaz
   REST API. Covers field names, response shapes, 117 production gotchas, error
@@ -413,7 +413,7 @@ Bills, invoices, and credit notes share identical mandatory field specs. Adding
 
 132. **Manual-journal recon: caller provides ONLY the offset side(s)** — `reconcile_manual_journal` AUTO-ADDS the bank-side leg from the bank statement entry. If the caller sends both debit AND credit legs covering the bank side, the API doubles-up after auto-add → 422 "sum of debit and credit amounts are not equal in a journal". Send only the offset journal entries (the non-bank side); the API balances them against the bank entry.
 
-133. **`reconcile_invoice_receipt` and `reconcile_bill_receipt` require statement-imported BSE** — the `bankStatementEntryResourceId` MUST come from a `bank import` (CSV/OFX/XLSX upload, BT type = `BANK_STATEMENT_ENTRY`). Entries from `bank add-records` produce BT type `BANK_RECORD` and are rejected with cryptic 422 "Invalid business transaction type". To bridge: import a CSV first OR file an API issue to widen acceptance.
+133. **`reconcile_invoice_receipt` and `reconcile_bill_receipt` gate on `paymentDirection`, not BSE entry type** — error code `INVALID_BUSINESS_TRANSACTION_TYPE_ERROR` ("Invalid business transaction type", 422) is misleadingly named. The actual gate is the BSE's `paymentDirection`. **`invoice_receipt` requires `PAYIN`** (AR — money in — positive amount in `bank add-records`, producing `credit_amount > 0`). **`bill_receipt` requires `PAYOUT`** (AP — money out — NEGATIVE amount, producing `debit_amount > 0`). `bank add-records` produces both directions based on amount sign. Statement-imported BSEs (`bank import`) also work — direction is set from the CSV. No need for the async magic-OCR `bank import` path; sync `bank add-records` with the correct sign is sufficient.
 
 134. **Bulk-upsert FLAT vs NESTED variants** — for invoices and bills, there are TWO bulk-upsert endpoints. **FLAT** (`bulk_upsert_invoices` / `bulk_upsert_bills`) — one line per row, set at row level via `itemDescription` + `totalAmount` + `invoiceAccountResourceId` (or `billAccountResourceId`). **NESTED** (`bulk_upsert_invoice_line_items` / `bulk_upsert_bill_line_items`) — multi-line per row via nested `lineItems[]`, each with `itemDescription` + `quantity` + `unitPrice` + `accountResourceId`. Use FLAT when one line per transaction is fine (CSV import, simple bills); use NESTED when each transaction needs multiple lines. Sending `lineItems[]` to the FLAT endpoint silently ignores them and creates a $0 invoice.
 

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 4.58.5
+version: 5.0.0
 description: >-
   Use this skill when running Clio CLI commands, building shell scripts with
   Clio, debugging auth issues, understanding --json output, paginating results,

package/assets/skills/cli/references/agent-gotchas.md

@@ -25,20 +25,20 @@
 
 10. **The `customer` and `supplier` fields on contacts are booleans.** `{ "customer": true, "supplier": false }` -- not strings. A contact can be both customer and supplier simultaneously.
 
-11. **Search returns results grouped by entity type, not a flat array.** `clio search "Acme" --json` returns `{ contacts: [...], sales: [...], purchases: [...], ... }`. Each key may be empty. Always access the specific entity key you need.
+11. **`clio schema` is for tool introspection, not data.** `clio schema --json` lists command groups and tool counts. `clio schema invoices --json` shows tool definitions. `clio schema invoices create --json` shows parameter schema. None of these hit the API.
 
-12. **`clio schema` is for tool introspection, not data.** `clio schema --json` lists command groups and tool counts. `clio schema invoices --json` shows tool definitions. `clio schema invoices create --json` shows parameter schema. None of these hit the API.
+12. **Job blueprints output plain text by default.** `clio jobs month-end` prints a checklist. Add `--json` for structured output. Some job tools (`match`, `outstanding`, `sg-cs`) require auth; blueprint generators are offline.
 
-13. **Job blueprints output plain text by default.** `clio jobs month-end` prints a checklist. Add `--json` for structured output. Some job tools (`match`, `outstanding`, `sg-cs`) require auth; blueprint generators are offline.
+13. **Capsule-transaction recipes: always `--plan` first.** `clio ct loan --plan` shows what accounts and transactions will be created, offline. Only run without `--plan` when you know the account mapping is correct. Recipes create real finalized transactions.
 
-14. **Capsule-transaction recipes: always `--plan` first.** `clio ct loan --plan` shows what accounts and transactions will be created, offline. Only run without `--plan` when you know the account mapping is correct. Recipes create real finalized transactions.
+14. **The `--input` flag reads JSON from a file.** For complex payloads (multi-line-item invoices, detailed journals), write JSON to a temp file and pass `--input payload.json` instead of long `--lines` flags with shell escaping issues. When `--input` is provided, all other body flags are ignored.
 
-15. **The `--input` flag reads JSON from a file.** For complex payloads (multi-line-item invoices, detailed journals), write JSON to a temp file and pass `--input payload.json` instead of long `--lines` flags with shell escaping issues. When `--input` is provided, all other body flags are ignored.
+15. **`bills draft list` (also `invoices/customer-credit-notes/supplier-credit-notes draft list`) fans out one attachment lookup per draft** (5 in flight). On accounts with hundreds of drafts this hangs >30s by default. Pass `--max-rows 10` for spot checks. Long-term: a `--with-attachments` flag is on the roadmap.
 
-16. **`bills draft list` (also `invoices/customer-credit-notes/supplier-credit-notes draft list`) fans out one attachment lookup per draft** (5 in flight). On accounts with hundreds of drafts this hangs >30s by default. Pass `--max-rows 10` for spot checks. Long-term: a `--with-attachments` flag is on the roadmap.
+16. **Bulk-upsert is TWO endpoints per entity for invoices/bills.** `clio invoices bulk-upsert` is FLAT (one line per row via `itemDescription` + `totalAmount` + `invoiceAccountResourceId` at row level). `clio invoices bulk-upsert-line-items` is NESTED (multi-line via `lineItems[]`). Sending `lineItems[]` to FLAT is silently ignored → $0 invoices. Match your data shape to the variant.
 
-17. **Bulk-upsert is TWO endpoints per entity for invoices/bills.** `clio invoices bulk-upsert` is FLAT (one line per row via `itemDescription` + `totalAmount` + `invoiceAccountResourceId` at row level). `clio invoices bulk-upsert-line-items` is NESTED (multi-line via `lineItems[]`). Sending `lineItems[]` to FLAT is silently ignored → $0 invoices. Match your data shape to the variant.
+17. **Reconciliation `lineItems[]` use `name` + `organizationAccountResourceId`.** The `reconciliations invoice-receipt` and `reconciliations bill-receipt` payloads use a DIFFERENT line-item field naming than `bulk-upsert-line-items`. Recon-create uses `name` (description) + `organizationAccountResourceId` (revenue/expense account). Bulk uses `itemDescription` + `accountResourceId`. Don't copy-paste line-items between the two.
 
-18. **Reconciliation `lineItems[]` use `name` + `organizationAccountResourceId`.** The `reconciliations invoice-receipt` and `reconciliations bill-receipt` payloads use a DIFFERENT line-item field naming than `bulk-upsert-line-items`. Recon-create uses `name` (description) + `organizationAccountResourceId` (revenue/expense account). Bulk uses `itemDescription` + `accountResourceId`. Don't copy-paste line-items between the two.
+18. **`reconciliations invoice-receipt` / `bill-receipt` gate on `paymentDirection`, not BSE type.** The 422 error code "Invalid business transaction type" is misleadingly named — the actual API check is on the BSE's `paymentDirection`. **`invoice-receipt` requires `PAYIN`** (positive amount via `clio bank add-records` → `credit_amount > 0`). **`bill-receipt` requires `PAYOUT`** (NEGATIVE amount → `debit_amount > 0`). Statement-imported BSEs (`clio bank import`) also work — direction is set from the CSV. For programmatic seeding, `clio bank add-records` with the correct sign is sync, fast, and reliable; no need for the async magic-OCR `bank import` path.
 
-19. **`reconciliations invoice-receipt` / `bill-receipt` require statement-imported BSE.** The bank statement entry must come from `clio bank import` (CSV/OFX/XLSX upload — produces `BANK_STATEMENT_ENTRY` type). Entries from `clio bank add-records` produce `BANK_RECORD` type and get rejected with cryptic 422 "Invalid business transaction type". For programmatic seeding use `bank import` with a tiny CSV.
+19. **No universal/cross-entity search.** The previous `clio search <q>` (Typesense-backed grouped search) was removed — it was FE-typeahead infrastructure. For agent/programmatic search use the structured `--query` syntax on per-entity search commands (`clio invoices search --query "..."`, `clio bills search --query "..."`, etc.). See `references/search-syntax.md` (in api skill) for the full DSL: AND/OR/NOT, parentheses, amount ranges (`$500+`, `$100-500`), date ranges (`date:-30d`, `date:jan-mar 2025`), wildcards, and entity-specific fields.

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

@@ -366,10 +366,6 @@ Also: `clio reports pdf` — generate PDF from a message/document.
 | `status <workflowIds>` | Comma-separated workflow IDs |
 | `search` | `--type`, `--status`, `--from`, `--to`, `--limit`, `--offset` |
 
-### `clio search <query>` — Universal cross-entity search
-Searches contacts, invoices, bills, credit notes, items. Returns grouped results.
-Flags: `--limit`, `--json`
-
 ### `clio quick-fix <entity>` — Bulk-update transactions
 Entities: `invoices`, `bills`, `customer-credit-notes`, `supplier-credit-notes`, `journals`, `cash-entries`, `sale-schedules`, `purchase-schedules`, `subscription-schedules`, `journal-schedules`
 

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

@@ -172,10 +172,10 @@ clio ct depreciation \
 Find transactions matching criteria and bulk-update them.
 
 ```bash
-# Universal search across all entities
-clio search "Acme" --json
+# Search invoices via structured --query syntax (see api skill: references/search-syntax.md)
+clio invoices search --query "customer:acme AND status:unpaid AND \$500+" --json
 
-# Search invoices with specific filters
+# Or with discrete flags
 clio invoices search --contact "Acme Corp" --status DRAFT --from 2026-01-01 --json
 
 # Extract IDs of matching drafts

package/assets/skills/cli/references/output-shapes.md

@@ -66,37 +66,6 @@ clio invoices get "$ID" --json   # Now you have the full record
 
 ---
 
-## Search Command (Multi-Entity)
-
-Universal search returns results grouped by entity type.
-
-```bash
-clio search "Acme" --json
-```
-
-```json
-{
-  "contacts": [],
-  "sales": [],
-  "purchases": [],
-  "journals": [],
-  "credit_notes": [],
-  "sale_items": [],
-  "purchase_items": [],
-  "sale_credit_note_items": [],
-  "purchase_credit_note_items": [],
-  "supplier_notes": []
-}
-```
-
-**jq examples:**
-```bash
-clio search "Acme" --json | jq '.contacts[] | {name, resourceId}'
-clio search "laptop" --json | jq 'to_entries | map({key, count: (.value | length)})'
-```
-
----
-
 ## Calc Commands (Calculator Output)
 
 Offline calculators return structured results with an amortization schedule.

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 4.58.5
+version: 5.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/jobs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-jobs
-version: 4.58.5
+version: 5.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/transaction-recipes/SKILL.md

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