jaz-clio 5.50.0 → 5.52.0

package/README.md

@@ -9,7 +9,7 @@
 
 <p align="center"><b>Jaz accounting on the command line, and inside any AI agent.</b></p>
 
-369 tools · 67 command groups · 7 skills · 13 calculators · 12 close playbooks · 159 field-tested API rules.
+369 tools · 68 command groups · 7 skills · 13 calculators · 12 close playbooks · 159 field-tested API rules.
 
 ```bash
 npm install -g jaz-clio
@@ -50,7 +50,7 @@ clio magic create --file receipt.pdf                   # AI extracts, drafts the
 clio invoices search --query 'status:unpaid AND $500+' # structured per-entity search
 ```
 
-67 command groups, 16 report types, 13 calculators, 12 job playbooks. Every command takes `--json`. Run `clio --help` for the full list.
+68 command groups, 16 report types, 13 calculators, 12 job playbooks. Every command takes `--json`. Run `clio --help` for the full list.
 
 ### Foreign currency
 

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 5.50.0
+version: 5.52.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

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 5.50.0
+version: 5.52.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
-  67 command groups and 369 tools, including employee-expense claims.
+  68 command groups and 369 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. 67 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. 68 command groups, 13 calculators, 12 job blueprints, 369 tools. Also fully compatible with Juan Accounting (same API, same endpoints).
 
 ## When to Use This Skill
 
@@ -299,8 +299,15 @@ The navigation tool (`navigate` — no destination to discover keys, a destinati
 
 CLI commands exit with standard codes:
 - **Exit 0** — success
-- **Exit 1** — user error (missing flags, invalid input, validation failure)
-- **Exit 2** — auth error (invalid key, unreachable API)
+- **Exit 1** — your input needs changing (missing flags, malformed id, over-limit or duplicate batch, blank required text, unknown enum value). Also a business refusal on some commands, e.g. `approvals`.
+- **Exit 2** — the request was fine and the API refused or failed, OR an internal defect
+- **Exit 3** — auth (invalid, missing or unresolvable key)
+
+**Branch on the `code` in the `--json` error envelope, not on the number alone.** Exit 1 is
+`VALIDATION_ERROR` for bad input but is also used by commands that report a refusal (there the
+outcome is on stdout, not stderr). Exit 2 splits into `API_ERROR` (the server refused; a
+different request may work) and `UNKNOWN_ERROR` (our defect; an identical retry fails
+identically). The code is the signal for whether retrying with different input can help.
 
 Error messages go to stderr. When `--json` is set, the error is still on stderr so stdout stays parseable. Common errors:
 

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

@@ -1,6 +1,6 @@
 # Clio Command Catalog
 
-Complete reference for all 67 command groups. Organized by domain.
+Complete reference for all 68 command groups. Organized by domain.
 
 ---
 
@@ -382,10 +382,23 @@ The other end of `drafts submit-for-approval`. Approving POSTS THE LEDGER and is
 
 `request-changes` accepts more families than `approve`: also `purchase-orders`, `purchase-requests`, `sale-orders`, `sale-quotes`, `claims`.
 
-**Exit codes carry the outcome, because a refusal is not always an error.** Credit notes refuse with HTTP 200, `isSuccess:false`, and an `approvalStatus` that still reads `APPROVED` — the document's state, not the call's. `0` = approved · `1` = refused (reason printed) or UNCONFIRMED (no per-record outcome came back) · `2` = API error. Never read HTTP 200 or `approvalStatus` as success.
+**Exit codes carry the outcome, because a refusal is not always an error.** Credit notes refuse with HTTP 200, `isSuccess:false`, and an `approvalStatus` that still reads `APPROVED` — the document's state, not the call's. `0` = approved · `1` = refused, UNCONFIRMED, **or your input was rejected before anything was sent** · `2` = API error. Never read HTTP 200 or `approvalStatus` as success.
+
+Exit 1 carries three meanings here, so **read the JSON, not the number**: a refusal or UNCONFIRMED writes an outcome to **stdout** (`{"approved": false}` / `null`), while a rejected input writes `{"error":{"code":"VALIDATION_ERROR"}}` to **stderr** and nothing to stdout. Only the first two mean the request reached the API.
 
 Claims approve via `clio claims approve` (a different endpoint), not through this group.
 
+### `clio purchase-items` — Purchase-side catalog (read-only, 3 tools)
+What the organization can be billed for. No create/update/delete upstream; maintain via `clio items`.
+
+| Subcommand | Key flags |
+|------------|-----------|
+| `list` | `--limit`, `--offset`, `--all`, `--max-rows` |
+| `get <resourceId>` | — |
+| `search` | `--name`, `--reference`, `--currency-code` — all EXACT plain-string matches |
+
+No free-text `--query`: the endpoint rejects it (`The query field is not supported for this entity`). Filters here are **plain strings, not expression objects** — `PurchaseItemFilter` declares them as bare `string`, so there is no `contains`. `purchaseResourceId` and `resourceId` also exist upstream and are reachable via `--filter`.
+
 ### `clio inventory` (alias: `inv`) — Inventory tracking
 | Subcommand | Key flags |
 |------------|-----------|

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 5.50.0
+version: 5.52.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.50.0
+version: 5.52.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.50.0
+version: 5.52.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.50.0
+version: 5.52.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: 5.50.0
+version: 5.52.0
 description: >-
   Use this skill when modeling complex multi-step accounting transactions —
   anything that spans multiple periods, involves changing amounts, or requires