jaz-clio 5.12.2 → 5.13.1

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-297-blue?style=for-the-badge" alt="297 Tools">
+  <img src="https://img.shields.io/badge/tools-301-blue?style=for-the-badge" alt="301 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>
 
-297 tools. 13 financial calculators. 12 job playbooks. 130 API rules. 16 IFRS recipes.
+301 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) — 55 command groups
-- [MCP Server](#mcp-server) — 297 tools for AI agents
+- [MCP Server](#mcp-server) — 301 tools for AI agents
 - [Skills](#skills) — Teach any AI the Jaz API
 - [Setup](#setup) — Auth, multi-org, automation
 
@@ -54,7 +54,7 @@ clio practice create-engagement acme-pte-ltd --type monthly-close --period 2026-
 
 ## MCP Server
 
-295 CLI tools, available to any AI agent that speaks MCP. Runs locally — no cloud, no ports. Includes the v5.2.0 `practice_*` tools (init, onboard_client, list_clients, load_client, create_engagement, load_engagement) so an agent in Claude Desktop or Claude Code can scaffold and load client workspaces conversationally.
+301 CLI tools, available to any AI agent that speaks MCP. Runs locally — no cloud, no ports. Includes the v5.2.0 `practice_*` tools (init, onboard_client, list_clients, load_client, create_engagement, load_engagement) so an agent in Claude Desktop or Claude Code can scaffold and load client workspaces conversationally.
 
 **Claude Code:**
 ```bash

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 5.12.2
+version: 5.13.1
 description: >-
   Use this skill whenever you call, debug, or review code that touches the Jaz
   REST API. Covers field names, response shapes, 141 production gotchas, error

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

@@ -3,11 +3,11 @@
 Pre-invoice / pre-bill documents in the sales and purchase pipelines.
 
 ```
-Sales:     Sale Quote ──(accept)──► Sale Order ──► Invoice
-Purchases: Purchase Request ──(accept)──► Purchase Order ──► Bill
+Sales:     Sale Quote ──(accept)──► Sale Order ──(convert-to-invoice)──► Invoice
+Purchases: Purchase Request ──(accept)──► Purchase Order ──(convert-to-bill)──► Bill
 ```
 
-Two MCP namespaces wrap these: **`sale_orders`** (Sale Quotes + Sale Orders) and **`purchase_orders`** (Purchase Requests + Purchase Orders). Each tool takes a `documentType` discriminator. The full long-tail (list, bulk-*, fast-fix, line-item bulk-upsert) lives in the CLI (`clio sale-orders …`, `clio purchase-orders …`).
+Two MCP namespaces wrap these: **`sale_orders`** (Sale Quotes + Sale Orders) and **`purchase_orders`** (Purchase Requests + Purchase Orders). Each tool takes a `documentType` discriminator. The full long-tail (list, bulk-*, fast-fix, line-item bulk-upsert) lives in the CLI (`clio sale-orders …`, `clio purchase-orders …`). Attachments on any order document go through the generic `get_attachments` / `add_attachment` / `delete_attachment` tools (`transactionType: sale-quotes | sale-orders | purchase-requests | purchase-orders`).
 
 ## Document types & lifecycle
 
@@ -23,9 +23,9 @@ Two MCP namespaces wrap these: **`sale_orders`** (Sale Quotes + Sale Orders) and
 - **Sale Orders have no draft state** — `saveAsDraft` is ignored; created directly as `CREATED`.
 - Statuses verified live: SQ create → `DRAFT` (or `CREATED` with `saveAsDraft:false`); SQ accept (from CREATED) → `ACCEPTED`; SO create → `CREATED`; SO confirm → `CONFIRMED`; PR create → `DRAFT` (or `ACTIVE` with `saveAsDraft:false`); PR accept (from ACTIVE) → `ACCEPTED`; PO `saveAsDraft:false` → `ACTIVE`; PO confirm → `CONFIRMED`.
 
-## Linking (this is how "conversion" works today)
+## Linking (quote → order, request → PO)
 
-There is **no convert endpoint** (`/convert-to-invoice` → 404). Linking is a **create-time reference field**:
+Quote→Order / Request→PO linking is a **create-time reference field**:
 
 - **Quote → Order**: pass `saleQuoteResourceId` on `create_sale_order` (documentType `SALE_ORDER`).
 - **Request → PO**: pass `purchaseRequestResourceId` on `create_purchase_order` (documentType `PURCHASE_ORDER`).
@@ -34,9 +34,18 @@ There is **no convert endpoint** (`/convert-to-invoice` → 404). Linking is a *
 
 Once an order is created from an issued quote, the parent quote's `orderState` advances to `FULLY_ORDERED` (verified live). `orderState` (`NOT_ORDERED` / `PARTIALLY_ORDERED` / `FULLY_ORDERED`) is a **response field**, not a search filter.
 
-### Order → Invoice / Order → Bill
+## Conversion: Order → Invoice / Order → Bill
 
-**Not exposed by the REST API yet.** There is no `saleOrderResourceId` on invoice-create and no `purchaseOrderResourceId` on bill-create at this layer. To raise an invoice "from" a confirmed Sale Order, call `create_invoice` separately (no order reference is recorded today). Fulfillment back-reference (`invoiceState`/`billState`) is tracked server-side but not surfaced here. Do **not** fabricate an order→invoice link.
+Both directions are now first-class endpoints:
+
+- **`convert_sale_order_to_invoice`** (documentType `SALE_QUOTE` | `SALE_ORDER`) → creates a new Invoice from the source.
+- **`convert_purchase_order_to_bill`** (documentType `PURCHASE_REQUEST` | `PURCHASE_ORDER`) → creates a new Bill from the source.
+
+Body: `valueDate` + `dueDate` + `reference` required; if `reference` is omitted the tool sends a unique placeholder — pass your own to follow your org's numbering sequence. Optional `terms`, `notes` (sales → `invoiceNotes`), `internalNotes`, `tag`, `saveAsDraft` (defaults false → the new document is ACTIVE).
+
+- **NON-IDEMPOTENT.** Each call creates ANOTHER invoice/bill. On a timeout or uncertain result, do NOT blind-retry — search for one already linked to this order (via the linkage fields below) first.
+- **Source must not be VOID.** The convert tools pre-flight this and return a `repair` hint instead of a bare 422.
+- The reverse link is also exposed as create-time fields: `create_invoice` accepts `saleOrderResourceId` / `saleQuoteResourceId`; `create_bill` accepts `purchaseOrderResourceId` / `purchaseRequestResourceId`. Use these when you build the invoice/bill yourself instead of converting.
 
 ## Fields (create)
 
@@ -53,16 +62,20 @@ Required: `valueDate`. Recommended: `reference` (auto-generated, timestamped, if
 
 ## MCP tools
 
-`sale_orders`: `create_sale_order`, `get_sale_order`, `search_sale_orders`, `update_sale_order`, `transition_sale_order` (action: ACCEPT | CONFIRM | VOID | DELETE).
-`purchase_orders`: `create_purchase_order`, `get_purchase_order`, `search_purchase_orders`, `update_purchase_order`, `transition_purchase_order`.
+`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`.
+
+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`.
 
 ## CLI (full surface incl. long-tail)
 
 ```
-clio sale-orders     list|get|search|create|update|accept|confirm|void|delete|fast-fix \
+clio sale-orders     list|get|search|search-line-items|create|update|accept|confirm|convert-to-invoice|void|delete|fast-fix \
                      |bulk-void|bulk-accept|bulk-confirm|bulk-delete|bulk-upsert-line-items   (-t quote|order)
-clio purchase-orders list|get|search|create|update|accept|confirm|void|delete|fast-fix \
+clio purchase-orders list|get|search|search-line-items|create|update|accept|confirm|convert-to-bill|void|delete|fast-fix \
                      |bulk-void|bulk-accept|bulk-confirm|bulk-delete|bulk-upsert-line-items   (-t request|order)
+clio bills download <id>                     # bill PDF
+clio supplier-credit-notes download <id>     # supplier CN PDF
 ```
 
 ## Worked example — issued quote → accept → linked order → confirmed
@@ -79,12 +92,16 @@ clio sale-orders create -t order --quote <quoteId> --contact <id> --lines '[…]
 clio sale-orders confirm <orderId> --json
 # 5. The parent quote now shows orderState = FULLY_ORDERED
 clio sale-orders get <quoteId> -t quote --json | jq .orderState
+# 6. Convert the confirmed order into an invoice (creates a NEW invoice)
+clio sale-orders convert-to-invoice <orderId> -t order --date 2026-05-30 --due 2026-06-29 --json
 ```
 
-Purchase side is symmetric: `create -t request --finalize` (→ ACTIVE) → (optional) `accept` → `create -t order --request <id> --finalize` → `confirm`.
+Purchase side is symmetric: `create -t request --finalize` (→ ACTIVE) → (optional) `accept` → `create -t order --request <id> --finalize` → `confirm` → `convert-to-bill <orderId> -t order --date … --due …`.
 
 ## Search
 
 `search_sale_orders` / `search_purchase_orders` take `documentType` plus the standard filter set (reference, status, contact, contactResourceId, currencyCode, date range, amount range, tag). The `status` enum is the per-side union (sales: DRAFT/CREATED/ACCEPTED/CONFIRMED/VOID; purchases: DRAFT/ACTIVE/ACCEPTED/CONFIRMED/VOID). For advanced/nested queries (e.g. filter by `saleQuoteResourceId`), pass the raw `filter` object. See `search-reference.md` §24–25 and `search-enums.md` §25–26.
 
 Search behaves exactly like the other entities: `sortBy` is an array, `order` is `ASC`/`DESC`, and an `offset` must be paired with a sort. Duplicate `sortBy` values are rejected (`422 — must contain unique values`).
+
+**Line-item-level search** — `search_sale_order_line_items` / `search_purchase_order_line_items` (CLI: `search-line-items -t …`) search the individual lines rather than the document headers. Filter by line text (`name`), parent order (`orderId` → `btResourceId`), contact, account, tax profile, amount range, open state (`isOpen`), and date. Use this for questions like "every order line still open for contact X over $500". A default sort is always applied, so paginating with `offset` is safe.

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 5.12.2
+version: 5.13.1
 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/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 5.12.2
+version: 5.13.1
 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-pseudo-sql/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-pseudo-sql
-version: 5.12.2
+version: 5.13.1
 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.12.2
+version: 5.13.1
 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/practice/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-practice
-version: 5.12.2
+version: 5.13.1
 description: >-
   Use this skill whenever an accounting practitioner is doing client work in
   Jaz — closing the books, filing GST, year-end statutory, onboarding a new

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

@@ -1,6 +1,6 @@
 ---
 name: jaz-recipes
-version: 5.12.2
+version: 5.13.1
 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,7 +6,7 @@ Source of truth lives in the installed skills (`.claude/skills/jaz-*/SKILL.md` o
 
 ## Discovery
 
-The Jaz MCP server exposes 295 tools across 37 namespaces via 3 meta-tools. **Use the meta-tool flow — never enumerate tools blindly.**
+The Jaz MCP server exposes 301 tools across 37 namespaces via 3 meta-tools. **Use the meta-tool flow — never enumerate tools blindly.**
 
 1. `search_tools(query)` → top-N tool names + namespaces.
 2. `describe_tools(names)` → full parameter schemas.