jaz-clio 5.47.1 → 5.47.3

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 5.47.1
+version: 5.47.3
 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
@@ -129,9 +129,9 @@ The rest of this skill — field names, gotchas, error catalog, dependency order
 34. **Bookmarks use `items` array wrapper** with `name`, `value`, `categoryCode`, `datatypeCode`.
 
 ### Custom Fields
-35. **Do NOT send `appliesTo` on custom field POST** — causes "Invalid request body". Only send `name`, `type`, `printOnDocuments`.
+35. **Custom fields: `appliesTo` WORKS and `type` does nothing** (re-probed live 2026-09-02, reversing the previous entry). Send `appliesTo` as an OBJECT — `{invoices, bills, customerCredits, supplierCredits, payments}` sets the matching `applyTo*` to `SHOW`; **omit it and the field appears on nothing**. The old "do not send appliesTo" note came from an ARRAY example, which does 400. `format` is the ONLY control over the kind of field and the datatype is derived, not chosen: `CUSTOM` (default) yields `datatypeCode: TEXT`, any `ALL_*` value (`ALL_CUSTOMERS`/`ALL_SUPPLIERS`/`ALL_CONTACTS`/`ALL_EMPLOYEES`/`ALL_USERS`) yields `LIST`, a picklist of that population. **There is no NUMBER, DATE or DROPDOWN custom field**: `type`, `fieldType`, `entityType`, `datatypeCode` and `options` all return 200 and are silently dropped (an int on `datatypeCode` also returns 200, so the DTO does not declare it). `printOnDocuments` is required and not defaulted server-side.
 35a. **Custom field values on transactions**: Set via `customFields: [{ customFieldName: "PO Number", actualValue: "PO-123" }]` on invoice/bill/customer-CN/supplier-CN/payment/item/fixed-asset create/update. NOT on journals, cash entries, or cash transfers. Read from GET responses in the same shape.
-35b. **Custom field search**: `POST /custom-fields/search` with filter/sort/limit/offset. Filter by `customFieldName` (StringExpression), `datatypeCode` (StringExpression: TEXT, DATE, DROPDOWN).
+35b. **Custom field search**: `POST /custom-fields/search` with filter/sort/limit/offset. Filter by `customFieldName` (StringExpression), `datatypeCode` (StringExpression: TEXT, LIST, DATE — there is no DROPDOWN; see rule 35).
 35c. **Custom field GET**: `GET /custom-fields/:resourceId` returns full definition including `applyToSales`, `applyToPurchase`, `applyToCreditNote`, `applyToPayment`, `printOnDocuments`, `listOptions`.
 
 ### Tags on Transactions
@@ -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)**: Contact groups PUT (nil pointer on search response), custom fields PUT (dangling stack pointers in mapping), capsules POST (upstream returns nil), catalogs POST, inventory balances by status GET (`/inventory-balances/:status`, missing `c.Bind`) — all return 500.
+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.
 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>`. **Response shape is non-standard**: `{ reference, resourceId, attachments: [{fileName, fileType, fileId, attachmentResourceId}] }` — NOT `{ data: [...] }`. The attachment ID field is `attachmentResourceId` (not `resourceId`).

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

@@ -866,26 +866,23 @@ Always wrap in `{ payments: [...] }` even for single payment.
 ### POST /api/v1/custom-fields
 
 ```json
-// Request (TEXT type):
-{ "name": "PO Number", "type": "TEXT", "printOnDocuments": false }
+// Request (free-text field on invoices and bills):
+{ "name": "PO Number", "printOnDocuments": false, "appliesTo": { "invoices": true, "bills": true } }
 
-// Request (DROPDOWN type with options):
-{ "name": "Priority", "type": "DROPDOWN", "printOnDocuments": false, "options": ["Low", "Medium", "High"] }
+// Request (picklist of every customer):
+{ "name": "Account Manager", "printOnDocuments": false, "format": "ALL_CUSTOMERS", "appliesTo": { "invoices": true } }
 
-// Request (DATE type):
-{ "name": "Delivery Date", "type": "DATE", "printOnDocuments": true }
-
-// Response (includes both canonical and alias names):
+// Response:
 { "data": { "customFieldName": "PO Number", "name": "PO Number", "status": "ACTIVE", "resourceId": "uuid" } }
 ```
 
-**CRITICAL notes from live testing**:
+**CRITICAL notes — re-probed live 2026-09-02, correcting several earlier entries**:
+- **PUT works.** The 500 this file and SKILL.md rule 46 recorded is gone: a PUT returned 200 and applied the change. But it is a FULL REPLACE of `appliesTo` + `printOnDocuments`, and the GET returns `printOnDocuments` as null — the truth is in the `applyTo*` enum, where `PRINT` means it prints and `SHOW` means it does not. `updateCustomField` hydrates from that enum; a raw caller that omits `printOnDocuments` will silently turn printing off.
 - POST uses `name`, GET returns both `customFieldName` and `name`
-- Valid `type` values: `"TEXT"`, `"DATE"`, `"DROPDOWN"` (UPPERCASE)
-- `printOnDocuments` is REQUIRED and is not defaulted server-side — omitting it returns 422 `printOnDocuments is a required field` (probed 2026-09-02; recorded as a 400 before that). `create_custom_field` sends `false` when you omit it.
-- Do NOT send `appliesTo` field — causes "Invalid request body"
-- Only send: `name`, `type`, `printOnDocuments` (and `options` for DROPDOWN)
-- For DROPDOWN type, `options` array works (without `appliesTo`)
+- `printOnDocuments` is REQUIRED and is not defaulted server-side — omitting it returns 422 `printOnDocuments is a required field` (recorded as a 400 before that). `create_custom_field` sends `false` when you omit it.
+- **`appliesTo` WORKS and you should send it.** `{ invoices, bills, customerCredits, supplierCredits, payments }` sets the matching `applyTo*` response fields to `SHOW`. Omit it and every one stays `NULL`, i.e. the field appears on nothing. The previous "do NOT send appliesTo, causes Invalid request body" entry is wrong.
+- **`format` is the only control over the KIND of field**, and the datatype is derived from it, not chosen: `CUSTOM` (default) yields `datatypeCode: TEXT`; any `ALL_*` value (`ALL_CUSTOMERS`, `ALL_SUPPLIERS`, `ALL_CONTACTS`, `ALL_EMPLOYEES`, `ALL_USERS`) yields `datatypeCode: LIST`, a picklist of that population.
+- **There is no NUMBER, DATE or DROPDOWN custom field, and `type`/`fieldType`/`entityType`/`datatypeCode`/`options` are all silently dropped** — sent with a value, they return 200 and the field is created as plain TEXT. Verified by readback across five spellings; `datatypeCode: 12345` also returns 200, so the DTO does not declare it. `datatypeCode` on the response is derived and read-only; `format` is settable on POST **and** PUT (both verified 2026-09-02).
 
 ### GET /api/v1/custom-fields/:resourceId
 

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

@@ -95,20 +95,18 @@ Or call `list_account_classifications` — authoritative for that organisation.
 **Fix**: Always include `printOnDocuments: false` (or `true`) in POST body. `create_custom_field` now sends `false` when you omit it, so this only bites a direct API caller.
 **Note**: recorded here as a 400 "Invalid request body" until 2026-09-02, when a live probe returned `422 validation_error` with the field named. Either the API tightened or the original entry generalised from a different malformed body; the 422 is what it returns today.
 ```json
-{ "name": "PO Number", "type": "TEXT", "printOnDocuments": false }
+{ "name": "PO Number", "printOnDocuments": false, "appliesTo": { "invoices": true } }
 ```
 
-### "Invalid request body" (400) — appliesTo field
-**Cause**: Sending the `appliesTo` array field in the POST body.
-**Fix**: Do NOT send `appliesTo` — it causes "Invalid request body". Only send: `name`, `type`, `printOnDocuments` (and `options` for DROPDOWN type).
+### WITHDRAWN — "do not send appliesTo" on custom fields
+This entry said `appliesTo` caused "Invalid request body" and told callers to send `type` and `options` instead. Re-probed live 2026-09-02: the opposite is true.
+- `appliesTo` as an OBJECT works — `{ "invoices": true, "bills": true }` returns 200 and sets `applyToSales`/`applyToPurchase` to `SHOW`. **Omitting it leaves every `applyTo*` at `NULL`, so the field appears on nothing.** The old entry's example sent an ARRAY (`["INVOICE"]`), which is the likely source of the original 400.
+- `type`, `fieldType`, `entityType`, `datatypeCode` and `options` are all silently dropped: sent with a value they return 200 and the field is created as plain TEXT. There is no NUMBER/DATE/DROPDOWN custom field.
+- `format` is the real control: `CUSTOM` (default) = free text, `ALL_*` = a picklist of that population.
 ```json
-// WRONG:
-{ "name": "PO Number", "type": "TEXT", "printOnDocuments": false, "appliesTo": ["INVOICE"] }
-
-// CORRECT:
-{ "name": "PO Number", "type": "TEXT", "printOnDocuments": false }
+// Correct:
+{ "name": "PO Number", "printOnDocuments": false, "appliesTo": { "invoices": true, "bills": true } }
 ```
-Valid `type` values: `"TEXT"`, `"DATE"`, `"DROPDOWN"` (UPPERCASE).
 
 ---
 

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

@@ -383,8 +383,8 @@ DELETE → expects "A" (parentEntityResourceId, via /cash-entries/:id)
 | `name` (in GET response) | `customFieldName` | GET returns both `customFieldName` and `name` alias. |
 | `name` (in POST body) | `name` | POST accepts `name`. |
 | `showOnPdf` | `printOnDocuments` | Required boolean |
-| `appliesTo` | DO NOT SEND | Causes "Invalid request body" |
-| `type` values | `"TEXT"`, `"DATE"`, `"DROPDOWN"` | UPPERCASE strings |
+| `appliesTo` | `appliesTo` (OBJECT) | `{invoices,bills,customerCredits,supplierCredits,payments,contacts,employeeClaims,fixedAssets,items,purchaseOrders,saleOrders}`. SEND IT — omit it and the field appears on nothing. An ARRAY 400s, which is what the old "do not send" note measured |
+| `type` / `fieldType` / `entityType` | — (silently dropped) | Use `format`: CUSTOM = free text, ALL_* = a picklist. `datatypeCode` is derived (TEXT or LIST); there is no NUMBER/DATE/DROPDOWN field |
 
 ### Custom Field Values on Transactions
 

package/assets/skills/api/references/full-api-surface.md

@@ -246,7 +246,7 @@ Body for all three: `{ items: [{btResourceId: "<uuid>", btType: "SALE|PURCHASE|S
 | GET | `/contact-groups/:resourceId` | Get by ID |
 | POST | `/contact-groups` | Create |
 | POST | `/contact-groups/search` | Advanced search |
-| PUT | `/contact-groups/:resourceId` | Update (**known 500 bug**) |
+| PUT | `/contact-groups/:resourceId` | Update — membership field is `associatedContactResourceIds`, not `contactResourceIds` |
 | DELETE | `/contact-groups/:resourceId` | Delete |
 
 ### Items
@@ -293,7 +293,7 @@ Body for all three: `{ items: [{btResourceId: "<uuid>", btType: "SALE|PURCHASE|S
 | GET | `/custom-fields/:resourceId` | Get by ID |
 | POST | `/custom-fields` | Create |
 | POST | `/custom-fields/search` | Advanced search |
-| PUT | `/custom-fields/:resourceId` | Update (**known 500 bug** — requires `appliesTo` but crashes) |
+| PUT | `/custom-fields/:resourceId` | Update — full replace of `appliesTo`+`printOnDocuments`; omitting either resets it |
 | DELETE | `/custom-fields/:resourceId` | Delete |
 
 ---

package/assets/skills/cli/SKILL.md

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