jaz-clio 5.69.0 → 5.71.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-379-blue?style=for-the-badge" alt="379 tools">
+  <img src="https://img.shields.io/badge/tools-380-blue?style=for-the-badge" alt="380 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>Jaz accounting on the command line, and inside any AI agent.</b></p>
 
-379 tools · 74 command groups · 7 skills · 13 calculators · 12 close playbooks · 159 field-tested API rules.
+380 tools · 74 command groups · 7 skills · 13 calculators · 12 close playbooks · 159 field-tested API rules.
 
 ```bash
 npm install -g jaz-clio
@@ -78,7 +78,7 @@ that ends up in a journal.
 
 ## MCP server
 
-379 tools for any AI agent that speaks MCP. Runs locally: no cloud, no ports.
+380 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: 5.69.0
+version: 5.71.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
@@ -171,7 +171,7 @@ The rest of this skill — field names, gotchas, error catalog, dependency order
 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.
-46. **Known API bugs (500s)**: capsules POST (upstream returns nil), catalogs POST, inventory balances by status GET (`/inventory-balances/:status`, missing `c.Bind`). **Contact groups PUT and custom fields PUT are NO LONGER on this list** — both were re-probed live 2026-09-02 and returned 200 and applied the change. Do not route around them.
+46. **Known API bugs (500s)**: capsules POST (upstream returns nil). **Catalogs POST, inventory balances by status GET, contact groups PUT and custom fields PUT are NO LONGER on this list.** 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.
 48. **Attachments — full CRUD**: **Add**: `POST /:type/:id/attachments` (multipart, `file` field, `application/pdf` or `image/*` — NOT `text/plain`). **List**: `GET /:type/:id/attachments`. **Delete**: `DELETE /:type/:id/attachments/:attachmentResourceId` (HTTP 200). CLI: `clio attachments add --file <path>` or `--url <url>`, `clio attachments list`, `clio attachments delete <attachmentResourceId>`. **The list response shape depends on the entity** — measured raw 2026-09-07: `/invoices/:id/attachments` returns `{ reference, resourceId, attachments: [{fileName, fileType, fileId, attachmentResourceId}] }`, while `/bills/:id/attachments` and `/journals/:id/attachments` return the conventional `{ data: [...] }`. Both credit-note types were unmeasured (every sampled record was void — see below). `listAttachments` in `core/api/attachments.ts` reads either key, so through the CLI or a tool you get `.data` in all cases; only a raw request sees the split. The attachment ID field is `attachmentResourceId` (not `resourceId`). **A VOIDED record 404s on three of the five types.** Measured 2026-09-07: a voided invoice, customer credit note and supplier credit note each answer `404 not_found` with `"<Entity> is voided"`, while a voided bill and a voided journal return 200 and list normally. The 404 is about the record's status, not its existence — `GET /invoices/:id` on the same id works — so never read this 404 as a bad resourceId. Anything fanning out to attachments alongside other calls must treat that leg as degradable, or one voided record destroys the whole response; `get_transaction_summary` did exactly that until 5.55.1.
@@ -325,14 +325,14 @@ Bills, invoices, and credit notes share identical mandatory field specs. Adding
 92c. **Valid enums** — `depreciationMethod`: `STRAIGHT_LINE`, `NO_DEPRECIATION`. `category`: `TANGIBLE`, `INTANGIBLE`. `accumulatedDepreciationAccountResourceId` and `capsuleResourceId` can be safely omitted — the API ignores empty values. **`purchaseBusinessTransactionResourceId` is omittable ON DRAFTS ONLY** — and because `saveAsDraft` defaults to `true` here (Rule 92b — fixed assets are the one transaction type that drafts by default), omitting it looks like it worked right up until you set `saveAsDraft: false` and the create is rejected. On an ACTIVE asset it is required, and it is the purchase LINE ITEM's id — Rule 92a.
 
 ### Subscriptions & Scheduled Transactions
-93. **Subscription endpoints are under `/scheduled/subscriptions`** — List, GET, POST, PUT, DELETE all at `/api/v1/scheduled/subscriptions[/:id]`. Cancel is **PUT** (not POST) at `/api/v1/scheduled/cancel-subscriptions/:id` (different path pattern). **Subscriptions are invoices only** (SALE) — no bills. Different from scheduled invoices: subscriptions auto-prorate partial periods (generate credit notes for mid-period changes), but currency/tax/account are immutable after creation. Use scheduled invoices for fixed-amount recurring invoices where you need per-occurrence flexibility. **All subscription CRUD requires `proratedConfig: { proratedAdjustmentLineText: string }`** — Clio auto-injects this; do not add manually. **`repeat` is required on POST** (valid: `ONE_TIME`, `DAILY`, `WEEKLY`, `MONTHLY`, `YEARLY`) — Clio maps from the `interval` parameter. Cancel requires `cancelDateType` (`END_OF_CURRENT_PERIOD`, `END_OF_LAST_PERIOD`, `CUSTOM_DATE`) + `proratedAdjustmentLineText` + `resourceId` in body. Must cancel before delete. `businessTransactionType` is NOT in the OAS — the API ignores it.
+93. **Subscription endpoints are under `/scheduled/subscriptions`** — List, GET, POST, PUT, DELETE all at `/api/v1/scheduled/subscriptions[/:id]`. Cancel is **PUT** (not POST) at `/api/v1/scheduled/cancel-subscriptions/:id` (different path pattern). **Subscriptions are invoices only** (SALE) — no bills. Different from scheduled invoices: subscriptions auto-prorate partial periods (generate credit notes for mid-period changes), but currency/tax/account are immutable after creation. Use scheduled invoices for fixed-amount recurring invoices where you need per-occurrence flexibility. **Create requires `proratedConfig: { proratedAdjustmentLineText: string }`**: Clio injects it on create; do not add it manually. Update does not need it (an update without `proratedConfig` succeeded, measured 2026-09-24); send it only to amend proration. **`repeat` is required on POST** (valid: `ONE_TIME`, `DAILY`, `WEEKLY`, `MONTHLY`, `YEARLY`) — Clio maps from the `interval` parameter. Cancel requires `cancelDateType` (`END_OF_CURRENT_PERIOD`, `END_OF_LAST_PERIOD`, `CUSTOM_DATE`) + `proratedAdjustmentLineText` + `resourceId` in body. Must cancel before delete. `businessTransactionType` is NOT in the OAS — the API ignores it. **Update needs the `invoice` template every time** (create shape; without it the PUT is a 422 `GENERAL_ERROR`), and **an update without `status` activates a paused subscription**: Clio restates the stored status when you omit it (see errors.md, Subscriptions).
 94. **Scheduled transaction search does NOT support `createdAt` sort** — `POST /scheduled-transaction/search` sort fields: `startDate`, `nextScheduleDate`, etc. Default to `startDate` DESC. This is a cross-entity search across all scheduled types (invoices, bills, journals, subscriptions). Filter by `businessTransactionType` (SALE, PURCHASE, JOURNAL) and/or `schedulerType` (RECURRING, SUBSCRIPTION) to narrow results.
 
 ### Contact Groups
 96. **Contact groups have `associatedContacts` array** — Each group contains `{ name, resourceId, associatedContacts: [{ name, resourceId }] }`. Search via `POST /contact-groups/search`. Known bug: PUT returns 500 (Rule 46).
 
 ### Inventory
-97. **Inventory balance uses `GET /inventory-item-balance/:itemResourceId`** — Returns `{ itemResourceId, latestAverageCostAmount, baseQty, baseUnit }`. Note: this is the ITEM resourceId, not an inventory-specific ID. The `/inventory-balances/:status` endpoint returns 500 (Rule 46).
+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.
@@ -440,11 +440,11 @@ Bills, invoices, and credit notes share identical mandatory field specs. Adding
 
 136. **Sync bulk-upsert response carries per-row failures** — `bulk_upsert_currency_rates` and `bulk_upsert_chart_of_accounts` return `{ resourceIds: string[], failedRows: ImportedRowError[], failedCount: number }` synchronously (no jobId polling needed). Each `failedRows` entry: `{ rowIndex, columnName, columnValue, errorCode, errorMessage }`. Empty `failedRows: []` + `failedCount: 0` on full success. For `bulk_upsert_currency_rates` specifically: omitting `rateApplicableTo` defaults it to `rateApplicableFrom - 0.999ms` (prevents temporal gaps in rate lookups). Contrast with async bulk-upserts (contacts, invoices, journals, etc.) which return `{ jobId }` and need `search_background_jobs` polling — there, per-row failures live in the job's `errorDetails` field instead.
 
-137. **`bulk_upsert_contacts` request-level validation** — fails the WHOLE batch with HTTP 422 (no per-row partial success at this layer). Five rules to satisfy before submitting: (a) every contact must have `customer: true` OR `supplier: true` after defaults+backfill — for updates, the API backfills omitted flags from the existing contact; for creates, you must explicitly set at least one. (b) email entries within a contact must be case-insensitively unique (the tool takes `emails: string[]` and expands them to `emailList[{email,label}]`). (c) **Do NOT send payment terms here at all** — see rule 137c. The documented `{name, value}` shape returns SUCCESS and silently destroys the row. The tool does not expose the field. (d) `name` must be unique within the batch (after whitespace+case normalize). (e) When `billingAddress` or `shippingAddress` is provided, BOTH `addressLine1` and `country` are required (the tool calls the first one `address` and renames it for you). Pre-validate client-side before calling; one bad row rejects the entire batch and the agent loses any successful work-in-progress.
+137. **`bulk_upsert_contacts` request-level validation**: fails the WHOLE batch with HTTP 422 (no per-row partial success at this layer). Five rules to satisfy before submitting: (a) every contact must have `customer: true` OR `supplier: true` after defaults+backfill; for updates, the API backfills omitted flags from the existing contact; for creates, you must explicitly set at least one. (b) email entries within a contact must be case-insensitively unique (the tool takes `emails: string[]` and expands them to `emailList[{email,label}]`). (c) a payment term whose `name` is `CUSTOM` must carry `value` (rule 137c). (d) `name` must be unique within the batch (after whitespace+case normalize). (e) When `billingAddress` or `shippingAddress` is provided, BOTH `addressLine1` and `country` are required (the tool calls the first one `address` and renames it for you). Pre-validate client-side before calling; one bad row rejects the entire batch and the agent loses any successful work-in-progress.
 
 137a. **`bulk_upsert_contacts` — the tool speaks its own vocabulary and the client renames six keys at the wire boundary** (`toWireContactRows`): `billingName`→`contactBillingName`, `currencyCode`→`currency`, `registrationNumber`→`registrationId`, `notes`→`customerInvoiceNotes`, `shippingAddress`→`deliveryAddress`, `emails: string[]`→`emailList: [{email,label}]`, plus `address`→`addressLine1` inside either address. **Send the TOOL names.** Both addresses require `address` AND `country` — omit either and the API 422s the WHOLE batch, so the client rejects it first with the field named. Note `notes` maps to the customer's DEFAULT INVOICE notes, not an internal memo. **`taxIdType` is not supported** — it appears on no contact definition. All verified live 2026-09-02 with a `taxId` control that stored correctly.
 
-137c. **`paymentTerms` is a SILENT ROW-KILL on `bulk_upsert_contacts` and is not exposed by the tool.** The wire shape `customerPaymentTerms: {name, value}` returns HTTP 200 with `status: SUCCESS`, `processedCount: 1`, `failedCount: 0`, `errorDetails: []` — **and the contact is never created.** A scalar returns a plain 400. Verified live twice. Nothing in the job result distinguishes this from a successful import, so a bulk run that sets payment terms silently loses those rows while reporting complete success. Import without terms, then set them per contact. This supersedes any earlier guidance to send `customerPaymentTerms.value`.
+137c. **Payment terms on contacts.** `bulk_upsert_contacts` takes `customerPaymentTerms` / `supplierPaymentTerms` as `{name, value?}`: `name` is `ON_DELIVERY`, `NET_7`, `NET_15`, `NET_30`, `NET_45`, `NET_60` or `CUSTOM` (any case). `value` is the number of days as a string: required for `CUSTOM` as a positive whole number (the client refuses anything else before the call). With any other name the name carries its days, and a `value` that is not a positive whole number fails the WHOLE batch with 422, so the client drops it. A term is stored only for a side the contact is on: a customer term on a supplier-only contact is dropped with a 200. Verified live 2026-09-23: `{name: "NET_30"}` stored `paymentDetail.customerPaymentTerms [{name: "Net 30", value: "30"}]`, the same as a single create. **Bulk UPDATE trap:** a row that omits a term makes the API back-fill it from the stored display name, which is no term name, so Net 30 is re-stored as `Custom`/"30" (measured 2026-09-24). The client re-sends each stored term the row omits under its real name (one contact search per 100 ids). The single-contact create and update take a bare name and store `CUSTOM` with no days, so a term of any other length (21 days) is reachable only through bulk upsert. `clio contacts create|update --payment-terms` / `--supplier-payment-terms` accept a name in any case (not `CUSTOM`) or days 0/7/15/30/45/60; `create` makes the contact that side, `update` refuses a term for a side the contact is not on. This replaces the earlier warning that the bulk shape silently dropped the row, which the API has since fixed. **A contact's status cannot be changed through the API either.** The update (`PUT /contacts/{id}`) has no `status` field and, per the API source, always writes ACTIVE. `bulk_upsert_contacts` with `status: "INACTIVE"` returns job SUCCESS with processedCount 1 and applies nothing: an update's other fields in that row were dropped too, and a create with it left no contact findable (measured 2026-09-24). The client refuses INACTIVE on bulk rows and `clio contacts update --status`. Change status in the Jaz app.
 
 138. **`get_contact_signals` — read-only contact-history pattern lookup** — `GET /api/v1/contacts/{resourceId}/signals?btType=…` returns the contact's modal patterns (currency, payment-terms, tax-inclusion/presence, top-COA, top-item), cadence (median interval days, days-since-last, interval ratio), and outstanding-balance snapshot for one (contact × business-transaction-type) pair. `btType` is required: `SALE` | `PURCHASE` | `SALE_CREDIT_NOTE` | `PURCHASE_CREDIT_NOTE`. Returns null `data` when sampleSize < 5 or the freshness layer is unavailable. Cache key is per-(contactId, btType) pair, so repeated calls for the same pair are cheap. **Three slices are always empty/null on this endpoint** — `severitySummary`, `outlierFlags`, `revealedDivergences` — because they require a draft to compare against; those populate only on the per-result `contactSignals` object inside `validate_drafts` responses. Use this tool for "what does this contact normally look like?" questions before drafting; use `validate_drafts` for "how does this draft compare to the contact's history?" questions after drafting.
 

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

@@ -985,7 +985,7 @@ Returns full custom field definition including `applyToSales`, `applyToPurchase`
 - There is no `inventoryAccountResourceId` — it appears in no request schema and a create succeeds without it
 - Delete inventory items via `DELETE /items/:id` (NOT `/inventory-items/:id`)
 - `GET /inventory-item-balance/:id` returns balance per item
-- `GET /inventory-balances/:status` currently returns 500 (known bug)
+- `GET /inventory-balances/:balanceStatus` lists balances across items; `balanceStatus` is `ALL`, `AVAILABLE` or `FULLY_DRAWN` (else 422). An empty result is a 404, which `list_inventory_balances` returns as `data: []`
 
 ---
 
@@ -1464,7 +1464,7 @@ Note the different path pattern from CRUD: cancel is at `/scheduled/cancel-subsc
 
 - `GET /api/v1/scheduled/subscriptions` — List all subscriptions
 - `GET /api/v1/scheduled/subscriptions/:id` — Get subscription details
-- `PUT /api/v1/scheduled/subscriptions/:id` — Update subscription (requires `proratedConfig`, `repeat`, `resourceId`)
+- `PUT /api/v1/scheduled/subscriptions/:id` — Update subscription. The `invoice` template is required on every update (create shape; without it every update is a 422 `GENERAL_ERROR`, even endDate-only). `startDate` and `repeat` are kept when omitted. `status` is NOT: an update without it made an INACTIVE subscription ACTIVE (measured 2026-09-24), so Clio restates the stored status when you omit it.
 - `DELETE /api/v1/scheduled/subscriptions/:id` — Delete subscription (must be cancelled first)
 
 ---
@@ -1833,7 +1833,7 @@ POST /api/v1/fixed-assets
 - `depreciationMethod`: `"STRAIGHT_LINE"` or `"NO_DEPRECIATION"`
 - `effectiveLife`: Integer (months)
 - `category`: `"TANGIBLE"` or `"INTANGIBLE"`
-- `saveAsDraft`: Defaults to `true`. Set `false` to activate — requires `purchaseBusinessTransactionType` (`PURCHASE`/`JOURNAL_MANUAL`) + `purchaseBusinessTransactionResourceId`
+- `saveAsDraft`: Defaults to `true`. Set `false` to activate — requires `purchaseBusinessTransactionType` (`PURCHASE`, `SALE`, `JOURNAL_MANUAL`, `JOURNAL_CASHFLOW`, `JOURNAL_DIRECT_CASH_IN`, `JOURNAL_DIRECT_CASH_OUT` or `JOURNAL_CASH_TRANSFER`) + `purchaseBusinessTransactionResourceId`
 - Optional string fields (`purchaseBusinessTransactionResourceId`, `capsuleResourceId`) can be safely omitted for drafts
 
 ### Response
@@ -1886,7 +1886,7 @@ The complete inventory surface is three routes plus the item create/list pair:
 | POST | `/api/v1/inventory-items` | Create an inventory-tracked item |
 | GET | `/api/v1/inventory-items` | List inventory-tracked items |
 | GET | `/api/v1/inventory-item-balance/:resourceId` | Balance for one item |
-| GET | `/api/v1/inventory-balances/:balanceStatus` | Balances by status — **returns 500**, see SKILL.md Rule 46 |
+| GET | `/api/v1/inventory-balances/:balanceStatus` | Balances across items by status: `ALL`, `AVAILABLE`, `FULLY_DRAWN` (SKILL.md Rule 97) |
 
 Stock moves only as a side effect of a transaction that carries the item (invoice, bill,
 credit note). There is no direct quantity write.

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

@@ -562,20 +562,28 @@ if (acct.code) ctx.coaIds[acct.code] = acct.resourceId;
 
 ## Catalogs POST Errors
 
-### 500 Internal Server Error on POST (known bug)
-**Cause**: `POST /catalogs` returns 500 after passing field validation.
-**Correct field names** (discovered via 422 validation errors):
+### POST works; the response has no resourceId
+`POST /catalogs` returned 201 on a live probe 2026-09-23 (it used to 500). The item `unit` is optional: a null unit means "use the item's own unit".
+**Field names**:
 - `catalogName` (NOT `name`)
 - `items` array with objects: `{ itemResourceId, itemName, price }` (NOT `itemResourceIds` flat array)
-**Workaround**: Create catalogs through the Jaz UI.
+**Response**: `{ createdCatalogs, createdCatalogItems, createContactGroups }` counts, no resourceId. Find the new catalog with `search_catalogs` by `catalogName`.
 
 ---
 
 ## Subscriptions Errors
 
-### 500 Internal Server Error — missing `proratedConfig`
-**Cause**: `POST /scheduled/subscriptions` and `PUT /scheduled/subscriptions/:id` return 500 when `proratedConfig` is omitted. The server null-pointer dereferences on the missing field. OAS marks it required but the 500 is misleading.
-**Fix**: Always include `proratedConfig: { proratedAdjustmentLineText: "Prorated adjustment" }` in create and update bodies.
+### Create without `proratedConfig`
+**Cause**: `proratedConfig` is required on `POST /scheduled/subscriptions`. It is NOT required on `PUT /scheduled/subscriptions/:id`: measured 2026-09-24, an update carrying `invoice` and no `proratedConfig` succeeded, and adding `proratedConfig` did not rescue an update without `invoice` (see the next entry).
+**Fix**: On create, include `proratedConfig: { proratedAdjustmentLineText: "Prorated adjustment" }` (Clio does this for you). On update, send it only to amend proration.
+
+### 422 GENERAL_ERROR "Internal Server Error" on update: missing `invoice` template
+**Cause**: `PUT /scheduled/subscriptions/:id` without `invoice` fails for every body (endDate alone, endDate + startDate + repeat, repeat alone), with or without `proratedConfig`. Measured on 2026-09-24.
+**Fix**: Send the full `invoice` template in the create shape (reference, valueDate, dueDate as YYYY-MM-DD, contactResourceId, lineItems with accountResourceId). The template GET returns (`data`) is in a different shape (`discount` object, `organizationAccountResourceId`, RFC3339 dates, `billFrom` without `billingAddress`) and is rejected if sent back as is. `update_subscription` / `clio subscriptions update` refuse locally without it.
+
+### Update without `status` activates a paused subscription
+**Cause**: `PUT /scheduled/subscriptions/:id` with no `status` turned an INACTIVE subscription ACTIVE (measured 2026-09-24). An ACTIVE subscription generates invoices.
+**Fix**: Always send `status`. `update_subscription` / `clio subscriptions update` read and restate the stored status when you omit it, and refuse the update if that read fails.
 
 ### 422 on cancel — wrong method or missing fields
 **Cause**: Cancel endpoint is **PUT** `/scheduled/cancel-subscriptions/:id` (not POST). Requires body: `{ cancelDateType, proratedAdjustmentLineText, resourceId }`. Empty `{}` returns 422.
@@ -616,7 +624,7 @@ account. Full model: SKILL.md Rule 47a, `endpoints.md` → Deposits, `feature-gl
 
 ### 404 — Endpoint does not exist
 **Cause**: `POST /inventory/adjustments` returns 404. Also tested: `/inventory-adjustments`, `/inventory-items/:id/adjustments`, `/items/:id/inventory-adjustments` — all 404. None of the four is registered; there is no stock-adjustment write path at any spelling.
-**Note**: The whole inventory surface is `POST|GET /inventory-items`, `GET /inventory-item-balance/:resourceId` and `GET /inventory-balances/:balanceStatus` (that last one 500s — Rule 46). Inventory items can be created, and stock moves as a side effect of a transaction carrying the item, but quantity cannot be written directly. See `endpoints.md` → Inventory.
+**Note**: The whole inventory surface is `POST|GET /inventory-items`, `GET /inventory-item-balance/:resourceId` and `GET /inventory-balances/:balanceStatus` (balances across items: `ALL`, `AVAILABLE` or `FULLY_DRAWN`, Rule 97). Inventory items can be created, and stock moves as a side effect of a transaction carrying the item, but quantity cannot be written directly. See `endpoints.md` → Inventory.
 
 ---
 

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

@@ -265,7 +265,7 @@ DIFFERENT shape from single create — easier to confuse.
 | `purchaseAssetAccountResourceId` | recommended | Asset account UUIDv4 |
 | `depreciationExpenseAccountResourceId` | recommended | Depreciation expense account UUIDv4 |
 | `accumulatedDepreciationAccountResourceId` | recommended | Accum dep account UUIDv4 |
-| `purchaseBusinessTransactionType` | required for `NEW` | `"PURCHASE"` \| `"SALE"` \| `"JOURNAL_MANUAL"` |
+| `purchaseBusinessTransactionType` | required for `NEW` | `"PURCHASE"` \| `"SALE"` \| `"JOURNAL_MANUAL"` \| `"JOURNAL_CASHFLOW"` \| `"JOURNAL_DIRECT_CASH_IN"` \| `"JOURNAL_DIRECT_CASH_OUT"` \| `"JOURNAL_CASH_TRANSFER"` |
 | `purchaseBusinessTransactionResourceId` | required for `NEW` | Purchase LINE ITEM resourceId, must be UNLINKED |
 | `accumulatedDepreciationAtTransferDate` | `TRANSFER` only | Depreciation already booked in the source system |
 | `bookValueAtTransferDate` | `TRANSFER` only | Remaining undepreciated value |

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 454 paths / 379 operations and is the authoritative list; check it before concluding
+> carries 454 paths / 380 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.
 >
@@ -262,7 +262,7 @@ Body for all three: `{ items: [{btResourceId: "<uuid>", btType: "SALE|PURCHASE|S
 | POST | `/inventory-items` | Create inventory item (needs `name`, `itemCode`, `unit`, `costingMethod`, `cogsResourceId` (Direct Costs), `purchaseAccountResourceId` (Inventory), `saleAccountResourceId`, `blockInsufficientDeductions`) |
 | GET | `/inventory-items` | List inventory items |
 | GET | `/inventory-item-balance/:resourceId` | Get inventory balance |
-| GET | `/inventory-balances/:balanceStatus` | List by status (**known 500 bug**) |
+| GET | `/inventory-balances/:balanceStatus` | List by status: `ALL`, `AVAILABLE`, `FULLY_DRAWN` (empty = 404) |
 | DELETE | (use `/items/:id`) | Delete inventory items via standard items endpoint |
 
 ### Tax Profiles

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 5.69.0
+version: 5.71.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 379 tools, including employee-expense claims.
+  74 command groups and 380 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 blueprints, 379 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 blueprints, 380 tools. Also fully compatible with Juan Accounting (same API, same endpoints).
 
 ## When to Use This Skill
 

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

@@ -482,7 +482,7 @@ All seven of `--item-code`, `--name`, `--unit`, `--costing-method`, `--cogs-acco
 | `list` | `--limit`, `--offset`, `--all`, `--format`, `--json` |
 | `get <id>` | `--json` |
 | `create` | `--input` (full JSON body) |
-| `update <id>` | `--input` |
+| `update <id>` | `--input` (must include the `invoice` template; `status` kept when omitted) |
 | `delete <id>` | |
 | `cancel <id>` | |
 | `search-scheduled` | `--limit`, `--offset`, `--all` |
@@ -722,7 +722,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 379 operations.
+Starts an MCP server for Claude Code / AI tool integration. Exposes all 380 operations.
 
 ### `clio serve` — HTTP daemon
 Starts the HTTP daemon for ChatKit and email channel integrations.

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 5.69.0
+version: 5.71.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.69.0
+version: 5.71.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.69.0
+version: 5.71.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.69.0
+version: 5.71.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.69.0
+version: 5.71.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,7 +4,7 @@ Jaz accounting guidance for this workspace. Load the installed Jaz skills for de
 
 ## Discovery
 
-Jaz exposes **379 tools across 46 namespaces**. Your tool list shows **3, 45, or 371** entries depending on packaging — **never infer capability from its length.**
+Jaz exposes **380 tools across 46 namespaces**. Your tool list shows **3, 45, or 371** 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.
 - **45** — namespace routers; call one with `{ operation, arguments }`. Its description lists its operations.