jaz-clio 5.40.0 → 5.40.2

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 5.40.0
+version: 5.40.2
 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
@@ -447,7 +447,7 @@ Bills, invoices, and credit notes share identical mandatory field specs. Adding
 
 142. **`capsuleRecipe` payload is mutually exclusive with `capsuleResourceId`** on trigger mutations (create/update of invoice, bill, journal, cash_in, cash_out). Use `capsuleRecipe` to CREATE a new capsule via the recipe engine; use `capsuleResourceId` to ATTACH a base-trx to an existing capsule. Sending both returns 422 (`excluded_with` validator).
 
-143. **Capsule recipe publish is best-effort post-commit — silent-null failure mode.** On success the trigger-mutation response carries `capsuleRecipeJob: { jobResourceId, capsuleResourceId, subscriptionFBPath, totalRecords, idempotentHit, recipeKey }` (verified live 2026-05-27). **Note `jobResourceId` (NOT `resourceId`)** on the trigger-mutation payload — this is the polling key. **On publish failure, `capsuleRecipeJob` is absent (or null) from the response, the trigger mutation STILL returns 201, the base-trx is committed, and NO error reason is surfaced to the caller.** The response echoes `capsuleRecipe.{recipeName, inputs}` back unchanged, which can look like success at a glance. **Three known causes** of silent null `capsuleRecipeJob` (must pre-validate before sending):
+143. **Capsule recipe publish is best-effort post-commit — silent-null failure mode.** On success the trigger-mutation response carries `capsuleRecipeJob: { jobResourceId, capsuleResourceId, subscriptionFBPath, totalRecords, idempotentHit, recipeKey }` (verified live 2026-05-27). **Note `jobResourceId` (NOT `resourceId`)** on the trigger-mutation payload — this is the polling key. **On publish failure, `capsuleRecipeJob` is absent (or null) from the response, the trigger mutation STILL returns its normal success status (201 on create, 200 on update — see endpoints.md "Success Status Codes"), the base-trx is committed, and NO error reason is surfaced to the caller.** The response echoes `capsuleRecipe.{recipeName, inputs}` back unchanged, which can look like success at a glance. **Three known causes** of silent null `capsuleRecipeJob` (must pre-validate before sending):
   - **(a) Wrong `recipeName` for the base trx type** — every recipe is locked to `allowedBaseTransactionTypes` (e.g. PREPAID_AMORTIZATION = PURCHASE only; DEFERRED_REVENUE = SALE only; ACCRUAL_REVERSAL, IFRS16_LEASE = JOURNAL_MANUAL only; LOAN_AMORTIZATION = JOURNAL_DIRECT_CASH_IN or JOURNAL_MANUAL). On `preview_capsule_recipe`, mismatch surfaces as 422 `RECIPE_INVALID_BASE_TRANSACTION_TYPE`. **On the trigger mutation, it silently nulls the job** — the validation happens post-commit in customer-service and arap catches the exception. Always check `get_capsule_recipe(name).allowedBaseTransactionTypes` matches the trigger mutation you're calling.
   - **(b) Currency mismatch** — see Rule 156 (single-currency v1 recipes — recipe `currency`, every `*AccountResourceId` account's `currencyCode`, and the base trx currency MUST all match). Mismatch surfaces as 422 `ERR_RECIPE_ACCOUNT_CURRENCY_MISMATCH` on `preview_capsule_recipe` but silently nulls on the trigger mutation.
   - **(c) Wrong `x-accountClass` on an input field** — see Rule 157 (each `*AccountResourceId` slot has a required account class). Mismatch silently nulls; preview returns the matching `RECIPE_FIELDS_*` 422.
@@ -548,4 +548,4 @@ When the user wants to OPEN, SEE, or SHARE something in the Jaz dashboard ("open
 - **jaz-conversion** — Data migration workflows from Xero, QuickBooks, Sage, MYOB, and Excel
 - **jaz-cli** — CLI command reference, auth, output formats, pagination, and workflow patterns
 
-160. **Payment `adjustment` is a CASH-LEG-only correction — it never moves the document balance.** Records an overpayment or a rounding difference on the bank side of a payment: `netCash = paymentAmount -/+ fees +/- adjustmentValue` (fees are deducted from cash received on an invoice and added to cash spent on a bill). AR/AP is untouched, so an overpaid invoice stays PAID with the excess sitting on the account you chose and NO credit note is created. Shape: `adjustment: { adjustmentValue, adjustmentAccountResourceId, adjustmentDescription? }` — signed, non-zero, max 2dp, always FLAT (never a percentage), never taxed. Accepted on `pay_invoice` / `pay_bill` / both credit-note refunds / `update_payment` / both receipt reconciliations. **NOT** on batch payments, and not for `DEBT_WRITE_OFF` / `CLEARING_SETTLEMENT` / `INTER_COMPANY` / `WITHHOLDING_TAX_CERTIFICATE` (those record a settlement, so there is no cash leg). The account must be non-controlled: not AR/AP, not the VAT or FX accounts, not bank/cash, not deposit-linked. **Write/read asymmetry:** you WRITE the nested `adjustment.adjustmentValue` but READ a flat `adjustmentAmount` on the payment record, alongside `adjustmentOrganizationAccountResourceId`. Don't confuse either with `lineItems[].taxVatAdjustment.adjustmentAmount`, which is line-item tax and unrelated. **On `update_payment`, omitting `adjustment` CLEARS it** — same as `transactionFee`, but NOT the same as `transactionFeeCollected`, which is preserved when omitted. On a reconciled payment that carries one, any update omitting it returns `PAYMENT_ADJUSTMENT_CANNOT_CHANGE_WHEN_RECONCILED` even if you only touched the reference.
+160. **Payment `adjustment` is a CASH-LEG-only correction — it never moves the document balance.** Records an overpayment or a rounding difference on the bank side of a payment: `netCash = paymentAmount -/+ fees +/- adjustmentValue` (fees are deducted from cash received on an invoice and added to cash spent on a bill). AR/AP is untouched, so an overpaid invoice stays PAID with the excess sitting on the account you chose and NO credit note is created. Shape: `adjustment: { adjustmentValue, adjustmentAccountResourceId, adjustmentDescription? }` — signed, non-zero, max 2dp, always FLAT (never a percentage), never taxed. Accepted on `pay_invoice` / `pay_bill` / both credit-note refunds / `update_payment` / both receipt reconciliations. **NOT** on batch payments, and not for `DEBT_WRITE_OFF` / `CLEARING_SETTLEMENT` / `INTER_COMPANY` / `WITHHOLDING_TAX_CERTIFICATE` (those record a settlement, so there is no cash leg). The account must be non-controlled: not AR/AP, not the VAT or FX accounts, not bank/cash, not deposit-linked. **Write/read asymmetry:** you WRITE the nested `adjustment.adjustmentValue` but READ a flat `adjustmentAmount` on the payment record, alongside `adjustmentOrganizationAccountResourceId`. Don't confuse either with `lineItems[].taxVatAdjustment.adjustmentAmount`, which is line-item tax and unrelated. **On `update_payment`, adding an adjustment and changing an existing one both APPLY.** Both paths verified separately against production on 2026-08-10 on arap `v10.7.20`: changing an existing one moved it 5.00 to 9.00, and adding one to a payment that had none set it to 7.25 with its account and description. `paymentAmount` and `transactionAmount` were untouched in both. **Removing one does NOT work.** `adjustmentValue: 0` is rejected at the edge with a 422, and `"adjustment": null` is indistinguishable from omitting the field, so both leave the stored value unchanged. To remove an adjustment, delete the payment record and record it again without one. An explicit clear flag is being added upstream; zero stays rejected, so omit-to-clear will never be the answer. Because update applies again, `PAYMENT_ADJUSTMENT_CANNOT_CHANGE_WHEN_RECONCILED` is reachable through this API again. Anything written between arap `v10.7.19` and `v10.7.20` describing this field as inert on update is stale.

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

@@ -54,6 +54,23 @@ All GET list endpoints and POST `/search` endpoints use **`limit`/`offset` pagin
 
 ---
 
+## Success Status Codes (All Endpoints)
+
+**Never branch on the exact 2xx — check `response.ok` (or `status < 300`) and read the body.** Every success carries the same `{ data: ... }` envelope regardless of code.
+
+| Shape | Code |
+|---|---|
+| `POST` that creates a NEW record — `/invoices`, `/bills`, `/journals`, `/contacts`, `/items`, `/chart-of-accounts`, `/tags`, `/tax-profiles`, `/capsules`, `/bookmarks`, `/bank-records/:acct`, `/:type/:id/payments`, `/:type/:id/refunds`, `/organization[-]currencies/:code/rates`, `/scheduled/*`, `/magic/*`, `/sale-orders/:id/convert-to-invoice` (and the other `convert-to-*`), the fixed-asset disposal actions (`/discard-fixed-assets/:id`, `/mark-as-sold/fixed-assets`, `/transfer-fixed-assets`) | **201** |
+| `PUT` (update) — all 40 of them, no exceptions | **200** |
+| `GET` (all), `DELETE` (all) | **200** |
+| `POST /search`, `POST /bulk-upsert`, and action POSTs that mutate an EXISTING record (`/:id/request-changes`, `/:id/credits`, `/:id/attachments`) | **200** |
+| Async batch kickoff (`/bulk-request-changes`, claims `bulk/*`) | **202** |
+| Quick Fix / bulk partial failure | **207** (body shape identical to 200 — check `failed[]`) |
+
+**Changed 2026-08-10**: seven `PUT` endpoints moved 201 → 200 — `/bills/{id}`, `/contacts/{id}`, `/nano-classifiers/{id}`, `/items/{id}`, `/journals/{id}`, `/scheduled/journals/{id}`, `/organization-currencies/{code}/rates/{id}`. Request shapes and response bodies are byte-identical; only the status changed. The same release corrected 114 published success codes that disagreed with what the endpoints actually returned, so the API reference now matches runtime everywhere. A client that asserted `status === 201` on an update breaks; one that checks `response.ok` does not.
+
+---
+
 ## 1. Organization
 
 ### GET /api/v1/organization
@@ -2095,7 +2112,8 @@ Update an existing payment record. All fields optional — only included fields
     "feeTaxVatApplicable": false
   },
   // Cash-leg adjustment: overpayment or rounding. Bank leg only, never AR/AP.
-  // Omitting this on an update CLEARS an existing adjustment.
+  // Only applies when RECORDING a payment. On update it is inert: add, change
+  // and remove all return 200 and do nothing. See rule 160.
   "adjustment": {
     "adjustmentValue": -0.03,
     "adjustmentAccountResourceId": "uuid-rounding-account",

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

@@ -864,7 +864,7 @@ Two of the seven never reach you through this path: a zero `adjustmentValue` and
 | `INVALID_PAYMENT_ADJUSTMENT_ACCOUNT` | Account is a control account (AR, AP, the VAT pair, the FX accounts, Retained Earnings, withholding tax), a bank or cash account, deposit-linked, missing, or deleted | Pick an ordinary postable account. Most seeded accounts qualify — Rounding, Other Income, Bank Charges |
 | `PAYMENT_ADJUSTMENT_MAKES_NET_CASH_INVALID` | Net cash would not remain above zero | Reduce the magnitude of a negative adjustment |
 | `PAYMENT_ADJUSTMENT_NOT_APPLICABLE_FOR_PAYMENT_METHOD` | Method is `DEBT_WRITE_OFF`, `CLEARING_SETTLEMENT`, `INTER_COMPANY` or `WITHHOLDING_TAX_CERTIFICATE` | Those record a settlement, not a bank movement, so there is no cash leg to adjust. Drop the adjustment |
-| `PAYMENT_ADJUSTMENT_CANNOT_CHANGE_WHEN_RECONCILED` | The payment is matched to a bank statement entry and the request would change its adjustment | Un-reconcile first, or resend the existing adjustment unchanged. **This fires even when you are only editing `reference`**, because omitting `adjustment` reads as clearing it |
+| `PAYMENT_ADJUSTMENT_CANNOT_CHANGE_WHEN_RECONCILED` | The payment is matched to a bank statement entry and the request would change its adjustment | **Unreachable through this API since 2026-08-10.** The update path never reads the caller's adjustment, so nothing can present a changed value for this rule to reject. Editing the `reference` on a reconciled adjusted payment now succeeds. Still listed because it fires for other clients and will return here when the upstream regression is fixed |
 | `PAYMENT_ADJUSTMENT_NOT_APPLICABLE_FOR_BATCH_PAYMENT` | Batch payments do not support adjustments | Record the adjustment on an individual payment |
 
 ---

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 5.40.0
+version: 5.40.2
 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.40.0
+version: 5.40.2
 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.40.0
+version: 5.40.2
 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.40.0
+version: 5.40.2
 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.40.0
+version: 5.40.2
 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.40.0
+version: 5.40.2
 description: >-
   Use this skill when modeling complex multi-step accounting transactions —
   anything that spans multiple periods, involves changing amounts, or requires
@@ -307,7 +307,7 @@ A second path: 5 IFRS recipes (Loan Amortization, Accrual Reversal, Prepaid Amor
 
 ### Three pre-flight gates BEFORE sending `capsuleRecipe` (else the response silently nulls)
 
-The trigger mutation is **best-effort post-commit**: if the recipe publish fails inside customer-service, the base-trx still commits, the response still returns 201, but `capsuleRecipeJob` is null and **no error reason is surfaced on the response body**. Three causes of silent null — gate every one of them before sending:
+The trigger mutation is **best-effort post-commit**: if the recipe publish fails inside customer-service, the base-trx still commits, the response still returns its normal success status (201 on create, 200 on update), but `capsuleRecipeJob` is null and **no error reason is surfaced on the response body**. Three causes of silent null — gate every one of them before sending:
 
 | Gate | Constraint | Pre-flight check |
 |---|---|---|
@@ -315,7 +315,7 @@ The trigger mutation is **best-effort post-commit**: if the recipe publish fails
 | **Currency** | Recipe `currency`, every `*AccountResourceId` account's `currencyCode`, and base trx `currencyCode` ALL must match (v1 recipes are single-currency) | `get_account(<id>).currencyCode` for every input account |
 | **Account class** | Each `*AccountResourceId` slot has an `x-accountClass` constraint in the recipe inputSchema (Asset/Liability/Expense/Revenue) | `get_capsule_recipe(name).versions[0].inputSchema.properties.<field>['x-accountClass']` vs `get_account(<id>).accountClass` |
 
-**The canonical pre-flight is one call**: `preview_capsule_recipe(recipeName, inputs)`. Pure-compute (no side effects). Surfaces every input/class/currency violation as a clean 422 with a concrete `error_type`. The trigger mutation does NOT surface these — it just returns 201 with no `capsuleRecipeJob`. Always preview first if you can't trust the inputs.
+**The canonical pre-flight is one call**: `preview_capsule_recipe(recipeName, inputs)`. Pure-compute (no side effects). Surfaces every input/class/currency violation as a clean 422 with a concrete `error_type`. The trigger mutation does NOT surface these — it just returns its normal success status with no `capsuleRecipeJob`. Always preview first if you can't trust the inputs.
 
 See `jaz-api` Rule 143 (silent-null failure mode + diagnosis sequence), Rule 144 (closed enum on `recipeName`), Rule 150 (RECIPE_INVALID_BASE_TRANSACTION_TYPE — preview-only, NOT trigger), Rule 156 (ERR_RECIPE_ACCOUNT_CURRENCY_MISMATCH), Rule 157 (x-accountClass slot constraint).