jaz-clio 4.58.1 → 4.58.4

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 4.58.1
+version: 4.58.4
 description: >-
   Use this skill whenever you call, debug, or review code that touches the Jaz
   REST API. Covers field names, response shapes, 117 production gotchas, error
@@ -272,6 +272,33 @@ Bills, invoices, and credit notes share identical mandatory field specs. Adding
 90a. **Bank rules create field is `appliesToReconciliationAccount`** (NOT `appliesToReconciliationAccountResourceId`) — the bank account UUID. `configuration` must nest under `reconcileWithDirectCashEntry` key. `configuration.reconcileWithDirectCashEntry.reference` is REQUIRED (omitting causes GENERAL_ERROR). `amountAllocationType`: use `"PERCENTAGE"` or `"FIXED"` — `"FIXED_AND_PERCENTAGE"` is read-only (include both `fixedAllocation` + `percentageAllocation` arrays and the server infers it). Optional config fields: `contactResourceId`, `internalNotes`, `tags`, `currencySettings`, `taxCurrencySettings`, `classifierConfig` on allocation lines.
 90b. **Bank rules PUT is FULL REPLACEMENT** — `PUT /bank-rules/:id` replaces the entire rule. Must send `resourceId`, `appliesToReconciliationAccount`, and full `configuration` every time. Omitting any required field causes GENERAL_ERROR. Use read-modify-write pattern: GET current rule, merge changes, PUT full payload. Same pattern as items PUT (Rule 72) and capsules PUT (Rule 73).
 
+90c. **Bank rule POST canonical create payload** (verified live 2026-04, NOT obvious from any single field error):
+```json
+{
+  "name": "My Rule",
+  "appliesToReconciliationAccount": "<bank-account-uuid>",
+  "configuration": {
+    "reconcileWithDirectCashEntry": {
+      "amountAllocationType": "PERCENTAGE",
+      "reference": "AUTO-{{bankReference}}",
+      "percentageAllocation": [
+        { "organizationAccountResourceId": "<acct-uuid>", "amount": 100 }
+      ]
+    }
+  }
+}
+```
+**Required nested keys** (each missing one returns a different cryptic error):
+- `configuration` MUST nest under `reconcileWithDirectCashEntry` key (the action type — even though there's only one type today)
+- `amountAllocationType`: `"PERCENTAGE"` or `"FIXED"` only (NOT `FULL_AMOUNT` despite that sounding right)
+- For `PERCENTAGE`: `percentageAllocation: [{organizationAccountResourceId, amount}]` (ARRAY of allocations summing to 100)
+- For `FIXED`: `fixedAllocation: [{organizationAccountResourceId, amount}]` (ARRAY of fixed amounts)
+- `reference` is **required** in the action config (omitting → cryptic 422)
+
+**Dynamic strings**: `name` and `reference` support `{{bankReference}}`, `{{bankPayee}}`, `{{bankDescription}}` placeholders — replaced with bank record values during reconciliation.
+
+**actionShortcutResourceId** for `apply_bank_rule` IS the rule's own `resourceId` from create response (no separate "action shortcut" entity).
+
 ### Fixed Assets
 91. **Fixed asset search does NOT support `createdAt` sort** — Valid sort fields: `resourceId`, `name`, `purchaseDate`, `typeName`, `purchaseAmount`, `bookValueNetBookValueAmount`, `depreciationMethod`, `status`. Using `createdAt` returns 422. Default to `purchaseDate` DESC.
 92. **Fixed asset disposal/sale/transfer use different endpoint patterns** — Discard: `POST /discard-fixed-assets/:id` (body includes `resourceId` + dates). Mark sold: `POST /mark-as-sold/fixed-assets` (body-only, no path param). Transfer: `POST /transfer-fixed-assets` (body-only). Undo: `POST /undo-disposal/fixed-assets/:id`.
@@ -347,7 +374,7 @@ Bills, invoices, and credit notes share identical mandatory field specs. Adding
 
 ### Bulk Upserts (transactions)
 
-118. **8 bulk-upsert endpoints for transactions** — `POST /api/v1/{invoices,bills,customer-credit-notes,supplier-credit-notes,journals,fixed-assets}/bulk-upsert` plus line-item variants for invoices and bills (`/invoices/line-items/bulk-upsert`, `/bills/line-items/bulk-upsert`). Max **500 rows per call**. All async — return `{data: {jobId, subscriptionFBPath, status, totalRecords}}`. Poll `search_background_jobs` with `filter: {resourceId: {eq: jobId}}` until terminal status. **Natural keys**: invoices = `invoiceReference`, bills = `billReference`, credit notes = `creditNoteReference`, journals = `reference`, fixed assets = `reference`. Provide `resourceId` (UUID) to update by ID; otherwise the natural key drives upsert. `rowIndex` is optional caller-supplied for error reporting.
+118. **8 bulk-upsert endpoints for transactions** — `POST /api/v1/{invoices,bills,customer-credit-notes,supplier-credit-notes,journals,fixed-assets}/bulk-upsert` plus line-item variants for invoices and bills (`/invoices/line-items/bulk-upsert`, `/bills/line-items/bulk-upsert`). Max **500 rows per call**. All async — return `{data: {jobId, subscriptionFBPath, status, totalRecords}}`. Poll `search_background_jobs` with `filter: {resourceId: {eq: jobId}}` until terminal status. **Natural keys**: invoices = `invoiceReference`, bills = `billReference`, credit notes = `creditNoteReference`, **journals = `journalReference` (NOT `reference` — asymmetric vs other entities)**, fixed assets = `reference`. **`currencyCode` is REQUIRED** on every transaction row (invoices, bills, CCN, SCN, journals) — missing it returns errorCode `IMPORT_CURRENCY_REQUIRED`. **Journals legs use `journalEntries[]`** (NOT `entries[]` — different from `journals create` which uses entries). Provide `resourceId` (UUID) to update by ID; otherwise the natural key drives upsert. `rowIndex` is optional caller-supplied for error reporting.
 
 119. **PARTIAL_SUCCESS handling** — When `search_background_jobs` returns `PARTIAL_SUCCESS` for a bulk-upsert job, the per-row failures are in `data[0].errorDetails` on the SAME response (an array of per-row error objects). Top-level counts (`processedCount`, `failedCount`, `totalRecords`) tell you *how many* failed; `errorDetails` tells you *which rows and why*. Don't pretend the operation succeeded — surface the failed rows to the user. The rule of thumb: poll with `search_background_jobs` filtered by `resourceId: { eq: jobId }`, then read `data[0].errorDetails` for terminal states.
 
@@ -355,7 +382,7 @@ Bills, invoices, and credit notes share identical mandatory field specs. Adding
 
 121. **Intra-batch reference dedup is MERGE, not REJECT** — Two rows in the same bulk-upsert call sharing the same natural key (`invoiceReference`/`billReference`/etc.) are MERGED by the API (last row wins). If the user wants strict-uniqueness, dedup client-side first.
 
-122. **Fixed asset bulk upsert requires `registrationType` + `typeCode`** — `registrationType: "NEW" | "TRANSFER"` distinguishes newly-acquired assets from those inherited from a prior accounting system. `typeCode` selects the asset class (e.g., `COMPUTER_EQUIPMENT`). Both are required on every row. `depreciationStartDate` is `YYYY-MM-DD` only.
+122. **Fixed asset bulk upsert — date fields are inconsistent** — the bulk-upsert REQUEST has TWO different date conventions: `valueDate` is `YYYY-MM-DD` (string); `depreciationStartDate` is **epoch milliseconds** (number). Sending YYYY-MM-DD for `depreciationStartDate` returns generic 400 "Invalid request body" with no detail. The GET RESPONSE uses `purchaseDate` (different field from request `valueDate`). Sending `purchaseDate` in the request → same generic 400. Other fields: `cost` and `purchaseAmount` are synonyms; `effectiveLife` and `usefulLifeMonths` are synonyms. Required: `reference`, `registrationType` ("NEW" | "TRANSFER"). Recommended: `typeCode` (e.g. `FURNITURE_AND_FIXTURE`), `typeName`, `category` ("TANGIBLE" | "INTANGIBLE"), `cost`/`purchaseAmount`, `valueDate` (YYYY-MM-DD), `effectiveLife`/`usefulLifeMonths`, `depreciationMethod` (`STRAIGHT_LINE` | `NO_DEPRECIATION`), `purchaseAssetAccountResourceId` (UUIDv4), `depreciationExpenseAccountResourceId` (UUIDv4), `accumulatedDepreciationAccountResourceId`. To set `depreciationStartDate`: pass epoch ms OR omit (defaults to valueDate).
 
 ### Reconciliation actions (write-side)
 
@@ -382,6 +409,16 @@ Bills, invoices, and credit notes share identical mandatory field specs. Adding
 
 130. **Drafts lifecycle is NOT idempotent** — a second `convert_drafts_to_active` on already-ACTIVE drafts returns 422; a second `submit_drafts_for_approval` on drafts with an in-flight approval returns 422. Filter the draft list by `status: DRAFT` before submitting (the entity-specific search tools — `search_invoices`, `search_bills`, etc. — accept `status` filters). `validate_drafts` IS safe to call repeatedly (read-only, no state change).
 
+131. **Drafts must be COMPLETE before convert/submit** — `convert_drafts_to_active` and `submit_drafts_for_approval` reject INCOMPLETE drafts (drafts missing required fields like `accountResourceId` on every line item, contactResourceId, etc.) with 422. The `bills draft list` / `invoices draft list` etc. commands return per-draft `ready: bool` + `missingCount` + `missingFields[]` — call `validate_drafts` first to surface missing fields per row, fix client-side, then convert/submit.
+
+132. **Manual-journal recon: caller provides ONLY the offset side(s)** — `reconcile_manual_journal` AUTO-ADDS the bank-side leg from the bank statement entry. If the caller sends both debit AND credit legs covering the bank side, the API doubles-up after auto-add → 422 "sum of debit and credit amounts are not equal in a journal". Send only the offset journal entries (the non-bank side); the API balances them against the bank entry.
+
+133. **`reconcile_invoice_receipt` and `reconcile_bill_receipt` require statement-imported BSE** — the `bankStatementEntryResourceId` MUST come from a `bank import` (CSV/OFX/XLSX upload, BT type = `BANK_STATEMENT_ENTRY`). Entries from `bank add-records` produce BT type `BANK_RECORD` and are rejected with cryptic 422 "Invalid business transaction type". To bridge: import a CSV first OR file an API issue to widen acceptance.
+
+134. **Bulk-upsert FLAT vs NESTED variants** — for invoices and bills, there are TWO bulk-upsert endpoints. **FLAT** (`bulk_upsert_invoices` / `bulk_upsert_bills`) — one line per row, set at row level via `itemDescription` + `totalAmount` + `invoiceAccountResourceId` (or `billAccountResourceId`). **NESTED** (`bulk_upsert_invoice_line_items` / `bulk_upsert_bill_line_items`) — multi-line per row via nested `lineItems[]`, each with `itemDescription` + `quantity` + `unitPrice` + `accountResourceId`. Use FLAT when one line per transaction is fine (CSV import, simple bills); use NESTED when each transaction needs multiple lines. Sending `lineItems[]` to the FLAT endpoint silently ignores them and creates a $0 invoice.
+
+135. **Reconciliation `lineItems[]` use a DIFFERENT field naming convention** — for `reconcile_invoice_receipt.invoiceDetails.lineItems[]` and `reconcile_bill_receipt.billDetails.lineItems[]`, each line uses `name` (NOT `itemDescription`) for the description and `organizationAccountResourceId` (NOT `accountResourceId`) for the revenue/expense account. The bulk-upsert-line-items variants use `itemDescription` + `accountResourceId`. Memorize this: bulk = `itemDescription`+`accountResourceId`; recon-create = `name`+`organizationAccountResourceId`.
+
 ## Supporting Files
 
 For detailed reference, read these files in this skill directory:

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

@@ -205,6 +205,8 @@ When POSTing, `classificationType` must be one of these exact strings (same as `
 
 ## Journals
 
+### Single create (`POST /journals`)
+
 | What You'd Guess | Actual API Field | Notes |
 |------------------|-------------------|-------|
 | `lineItems` | `journalEntries` | Array of entries |
@@ -213,6 +215,47 @@ When POSTing, `classificationType` must be one of these exact strings (same as `
 | `debit` / `credit` (entry) | `amount` + `type` | `amount`: number, `type`: `"DEBIT"` or `"CREDIT"` (UPPERCASE) |
 | `currency: "USD"` (string) | `currency: { sourceCurrency: "USD" }` | **Object form** — same as invoices/bills. Auto-fetches platform rate. Add `exchangeRate: 1.35` for custom rate. Omit for base currency. |
 
+### Bulk upsert (`POST /journals/bulk-upsert`)
+
+DIFFERENT shape from single create — easier to confuse.
+
+| What You'd Guess | Actual API Field | Notes |
+|------------------|-------------------|-------|
+| `reference` | `journalReference` | Natural key — bulk uses `journalReference` (asymmetric vs other entities which use `<entity>Reference`) |
+| `entries` | `journalEntries` | Array of legs — same name as single create |
+| `amount` + `type: "DEBIT"` | `debitAmount` / `creditAmount` (separate fields per leg) | Bulk uses split numeric fields, NOT amount+type. Set unused side to 0. |
+| `currency: { ... }` (object) | `currencyCode: "SGD"` (flat string) | Bulk requires the flat `currencyCode` string per row — REQUIRED. Missing → `IMPORT_CURRENCY_REQUIRED` errorCode. |
+
+---
+
+## Fixed Assets
+
+### Bulk upsert (`POST /fixed-assets/bulk-upsert`) — REQUEST shape
+
+⚠️ **Date field is `valueDate`, NOT `purchaseDate`.** The GET response uses `purchaseDate`; the bulk-upsert REQUEST uses `valueDate`. Sending `purchaseDate` returns generic 400 "Invalid request body" with no detail. Most painful field-name asymmetry in the API.
+
+| Field | Required? | Notes |
+|-------|-----------|-------|
+| `reference` | required | Natural key |
+| `registrationType` | required | `"NEW"` or `"TRANSFER"` |
+| `name` | recommended | Asset name |
+| `typeCode` | recommended | e.g. `FURNITURE_AND_FIXTURE`, `COMPUTER_AND_ELECTRONIC` |
+| `typeName` | recommended | Human label, e.g. `"Furniture and Fixtures"` |
+| `category` | recommended | `"TANGIBLE"` or `"INTANGIBLE"` |
+| `cost` OR `purchaseAmount` | recommended | Synonyms — both accepted |
+| `valueDate` | recommended | Acquisition date YYYY-MM-DD (NOT `purchaseDate`!) |
+| `currencyCode` | recommended | `"SGD"` flat string |
+| `depreciationStartDate` | optional | **EPOCH MILLISECONDS** (number, NOT YYYY-MM-DD — inconsistent with `valueDate` on the same endpoint). Sending YYYY-MM-DD → generic 400. Omit to default to `valueDate`. |
+| `effectiveLife` OR `usefulLifeMonths` | recommended | Months — synonyms |
+| `depreciationMethod` | recommended | `"STRAIGHT_LINE"` or `"NO_DEPRECIATION"` |
+| `purchaseAssetAccountResourceId` | recommended | Asset account UUIDv4 |
+| `depreciationExpenseAccountResourceId` | recommended | Depreciation expense account UUIDv4 |
+| `accumulatedDepreciationAccountResourceId` | recommended | Accum dep account UUIDv4 |
+
+### Single create (`POST /fixed-assets`)
+
+Uses `purchaseAmount` + `purchaseDate` + `effectiveLife` + `purchaseAssetAccountResourceId` + `depreciationExpenseAccountResourceId`. CLI command `clio fixed-assets create` mirrors this. **Different date field from bulk-upsert** — see warning above.
+
 ---
 
 ## Cash Entries (CREATE request shape)

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 4.58.1
+version: 4.58.4
 description: >-
   Use this skill when running Clio CLI commands, building shell scripts with
   Clio, debugging auth issues, understanding --json output, paginating results,
@@ -127,9 +127,11 @@ clio invoices list --all --json       # Full dataset as JSON (progress suppresse
 
 Rules:
 - `--all` and `--offset` cannot be combined (throws error)
-- Default `--max-rows` is 10,000 (prevents runaway fetches)
+- **Default `--max-rows` is 1,000** (lowered from 10,000 in 2026-04 — fan-out lookups like attachment counts in `bills draft list` could spiral on busy accounts). Pass `--max-rows N` explicitly when you need more.
+- **`--max-rows` now caps the FETCH, not just the slice** (early-stop in `paginatedFetch`). Previously it pulled every page then sliced — multi-minute hangs on large datasets.
 - Table display caps at 500 rows regardless (use `--format json` for full output)
 - Progress display on stderr is TTY-aware (suppressed for `--json` and pipes)
+- **`bills draft list` / `invoices draft list` / `customer-credit-notes draft list` / `supplier-credit-notes draft list` fan out one attachment lookup per draft** (5 in flight). On accounts with hundreds of drafts, this is slow even with `--max-rows`. Pass `--max-rows 10` for spot checks; expect 30s+ wall time at higher counts.
 
 ## Common Flags
 
@@ -227,6 +229,15 @@ Create/update commands accept payloads three ways (priority order):
 
 When `--input` or stdin provides a body, CLI flags are ignored.
 
+### Bulk-upsert: FLAT vs NESTED variants
+
+For invoices and bills, there are TWO bulk-upsert commands per entity:
+
+- **FLAT** (`clio invoices bulk-upsert` / `clio bills bulk-upsert`) — ONE line per row. Each row carries `itemDescription` + `totalAmount` + `invoiceAccountResourceId` (or `billAccountResourceId`) at the top level. Use for CSV-like imports where each row = one transaction with a single line.
+- **NESTED** (`clio invoices bulk-upsert-line-items` / `clio bills bulk-upsert-line-items`) — multi-line per row. Each row carries nested `lineItems[]` with per-line `itemDescription` + `quantity` + `unitPrice` + `accountResourceId`. Use when each transaction needs multiple lines.
+
+Sending `lineItems[]` to the FLAT endpoint silently ignores them and creates a $0 transaction. Sending the FLAT shape to the NESTED endpoint creates an empty `lineItems` array and 422s. Match the variant to your data shape.
+
 ## Command Quick Reference
 
 **Transactions**: `invoices`, `bills`, `customer-credit-notes`, `supplier-credit-notes`, `journals`, `cash-in`, `cash-out`, `cash-transfer`, `payments`, `cashflow`

package/assets/skills/cli/references/agent-gotchas.md

@@ -1,6 +1,6 @@
 # Agent Gotchas
 
-> 15 critical gotchas for AI agents using the CLI. Learned from production testing.
+> 19 critical gotchas for AI agents using the CLI. Learned from production testing.
 > Violating these causes silent data errors or wasted API calls.
 
 ---
@@ -13,7 +13,7 @@
 
 4. **--offset is page number (0-indexed), not row skip count.** `--offset 0 --limit 100` = rows 1-100. `--offset 1 --limit 100` = rows 101-200. This is not the same as SQL OFFSET.
 
-5. **--all caps at 10,000 rows by default.** For large orgs, pass `--max-rows 50000` explicitly. The CLI auto-paginates with concurrent requests and shows progress on stderr.
+5. **--all caps at 1,000 rows by default** (lowered from 10,000 in 2026-04). For large orgs, pass `--max-rows 50000` explicitly. The CLI auto-paginates with concurrent requests and **stops fetching once `--max-rows` is reached** (early-stop, not slice-after — the previous behavior would pull every page and discard the excess, causing minute-long hangs on busy sandboxes).
 
 6. **JAZ_API_KEY env var overrides --org and active profile.** If set, all commands use that key regardless of `--org` or `clio auth switch`. Run `unset JAZ_API_KEY` to restore profile-based auth. Run `echo $JAZ_API_KEY` to check.
 
@@ -34,3 +34,11 @@
 14. **Capsule-transaction recipes: always `--plan` first.** `clio ct loan --plan` shows what accounts and transactions will be created, offline. Only run without `--plan` when you know the account mapping is correct. Recipes create real finalized transactions.
 
 15. **The `--input` flag reads JSON from a file.** For complex payloads (multi-line-item invoices, detailed journals), write JSON to a temp file and pass `--input payload.json` instead of long `--lines` flags with shell escaping issues. When `--input` is provided, all other body flags are ignored.
+
+16. **`bills draft list` (also `invoices/customer-credit-notes/supplier-credit-notes draft list`) fans out one attachment lookup per draft** (5 in flight). On accounts with hundreds of drafts this hangs >30s by default. Pass `--max-rows 10` for spot checks. Long-term: a `--with-attachments` flag is on the roadmap.
+
+17. **Bulk-upsert is TWO endpoints per entity for invoices/bills.** `clio invoices bulk-upsert` is FLAT (one line per row via `itemDescription` + `totalAmount` + `invoiceAccountResourceId` at row level). `clio invoices bulk-upsert-line-items` is NESTED (multi-line via `lineItems[]`). Sending `lineItems[]` to FLAT is silently ignored → $0 invoices. Match your data shape to the variant.
+
+18. **Reconciliation `lineItems[]` use `name` + `organizationAccountResourceId`.** The `reconciliations invoice-receipt` and `reconciliations bill-receipt` payloads use a DIFFERENT line-item field naming than `bulk-upsert-line-items`. Recon-create uses `name` (description) + `organizationAccountResourceId` (revenue/expense account). Bulk uses `itemDescription` + `accountResourceId`. Don't copy-paste line-items between the two.
+
+19. **`reconciliations invoice-receipt` / `bill-receipt` require statement-imported BSE.** The bank statement entry must come from `clio bank import` (CSV/OFX/XLSX upload — produces `BANK_STATEMENT_ENTRY` type). Entries from `clio bank add-records` produce `BANK_RECORD` type and get rejected with cryptic 422 "Invalid business transaction type". For programmatic seeding use `bank import` with a tiny CSV.

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

@@ -18,6 +18,10 @@ Complete reference for all 53 command groups. Organized by domain.
 | `pay <id>` | `--amount`, `--tx-amount`, `--account`, `--method`, `--ref`, `--date` |
 | `apply-credits <id>` | `--credit-note`, `--amount` |
 | `download <id>` | `--output` (PDF download) |
+| `draft list` | `--max-rows N`, `--ids`, `--json` — ⚠️ fans out 1 attachment lookup per draft (5 in flight); pass `--max-rows 10` for spot checks |
+| `draft finalize <id>` | `--account`, `--input` |
+| `bulk-upsert` | `--input <file>`, `--json` — **FLAT** shape (one line per row via `itemDescription`+`totalAmount`+`invoiceAccountResourceId`). Async → jobId. `currencyCode` REQUIRED |
+| `bulk-upsert-line-items` | `--input <file>`, `--json` — **NESTED** shape (multi-line per row via `lineItems[]`). Async → jobId. `currencyCode` REQUIRED |
 
 ### `clio bills` — Purchase bills
 | Subcommand | Key flags |
@@ -30,6 +34,10 @@ Complete reference for all 53 command groups. Organized by domain.
 | `delete <id>` | |
 | `pay <id>` | `--amount`, `--tx-amount`, `--account`, `--method`, `--ref`, `--date` |
 | `apply-credits <id>` | `--credit-note`, `--amount` |
+| `draft list` | `--max-rows N`, `--ids`, `--json` — same attachment fan-out warning as invoices |
+| `draft finalize <id>` | `--account`, `--input` |
+| `bulk-upsert` | `--input <file>`, `--json` — **FLAT** shape. Async → jobId. `currencyCode` REQUIRED |
+| `bulk-upsert-line-items` | `--input <file>`, `--json` — **NESTED** shape. Async → jobId. `currencyCode` REQUIRED |
 
 ### `clio customer-credit-notes` — Customer credit notes
 | Subcommand | Key flags |
@@ -43,6 +51,8 @@ Complete reference for all 53 command groups. Organized by domain.
 | `refund <id>` | `--amount`, `--account`, `--method`, `--ref`, `--date` |
 | `refunds <id>` | List refunds for a credit note |
 | `download <id>` | `--output` (PDF download) |
+| `draft list` | `--max-rows N`, `--ids`, `--json` |
+| `bulk-upsert` | `--input <file>`, `--json` — Nested `lineItems[]`. Async → jobId. `currencyCode` REQUIRED |
 
 ### `clio supplier-credit-notes` — Supplier credit notes
 | Subcommand | Key flags |
@@ -55,6 +65,8 @@ Complete reference for all 53 command groups. Organized by domain.
 | `delete <id>` | |
 | `refund <id>` | `--amount`, `--account`, `--method`, `--ref`, `--date` |
 | `refunds <id>` | List refunds for a credit note |
+| `draft list` | `--max-rows N`, `--ids`, `--json` |
+| `bulk-upsert` | `--input <file>`, `--json` — Nested `lineItems[]`. Async → jobId. `currencyCode` REQUIRED |
 
 ### `clio journals` — Journal entries
 | Subcommand | Key flags |
@@ -66,6 +78,8 @@ Complete reference for all 53 command groups. Organized by domain.
 | `update <id>` | `--date`, `--ref`, `--entries`, `--input` |
 | `delete <id>` | |
 | `transfer-trial-balance` (alias: `ttb`) | `--from-date`, `--to-date`, `--target-date` |
+| `draft list` | `--max-rows N`, `--ids`, `--json` |
+| `bulk-upsert` | `--input <file>`, `--json` — ⚠️ Natural key is `journalReference` (NOT `reference`); legs use `journalEntries[]` (NOT `entries[]`); each leg has `debitAmount`+`creditAmount` (NOT `amount`+`type`). `currencyCode` REQUIRED. Async → jobId |
 
 ### `clio cash-in` — Direct cash-in entries
 | Subcommand | Key flags |
@@ -255,6 +269,32 @@ Dynamic strings in rules: `{{bankReference}}`, `{{bankPayee}}`, `{{bankDescripti
 | `sell <id>` | `--date`, `--amount`, `--account` |
 | `transfer <id>` | `--date`, `--to-type` |
 | `undo-disposal <id>` | Reverse a discard or sale |
+| `bulk-upsert` | `--input <file>`, `--json` — ⚠️ Date field is `valueDate` (NOT `purchaseDate` — that's the GET response field; bulk request uses `valueDate`). `cost`/`purchaseAmount` synonyms accepted. `effectiveLife`/`usefulLifeMonths` synonyms accepted. Required: `reference`, `registrationType` ("NEW" or "TRANSFER"). Async → jobId |
+
+### `clio reconciliations` (alias: `recon`) — Bank reconciliation actions (8 tools)
+2 async + 6 sync. Sync endpoints are NOT idempotent — re-running creates duplicate journals.
+
+| Subcommand | Type | Key flags |
+|------------|------|-----------|
+| `quick-reconcile` | async | `--input <file>` — bulk match BSEs to journals (max 500) |
+| `bank-rule` | async | `--input <file>` — apply bank rule action to BSEs (max 500) |
+| `direct-cash-entry` | sync | `--input <file>` — single cash-in/out line; direction inferred from BSE sign |
+| `cash-journal` | sync | `--input <file>` — multi-line cashflow journal (max 200 lines) |
+| `manual-journal` | sync | `--input <file>` — ⚠️ caller provides ONLY offset side; backend auto-adds bank-side leg. Sending both → 422 unbalanced |
+| `cash-transfer` | sync | `--input <file>` — inter-account transfer; `accountResourceId` is counterparty |
+| `invoice-receipt` | sync | `--input <file>` — ⚠️ requires BSE from `bank import` (BANK_STATEMENT_ENTRY type). `bank add-records` BSEs (BANK_RECORD type) → 422 "Invalid business transaction type" |
+| `bill-receipt` | sync | `--input <file>` — same BSE-type warning as invoice-receipt |
+
+### `clio drafts` — Server-side draft lifecycle (3 tools)
+Bulk-friendly: one call accepts mixed btTypes (max 500). NOT idempotent on already-promoted drafts (422).
+
+| Subcommand | Type | Key flags |
+|------------|------|-----------|
+| `validate` | sync | `--input <file>` — pre-flight; returns per-item errors. Idempotent. |
+| `convert-to-active` | async | `--input <file>` — promote DRAFT → ACTIVE. Async → jobId |
+| `submit-for-approval` | async | `--input <file>` — route into approval workflow. Async → jobId |
+
+Body shape (all 3): `{ items: [{ btResourceId, btType }] }` with `btType ∈ {SALE | PURCHASE | SALE_CREDIT_NOTE | PURCHASE_CREDIT_NOTE}`.
 
 ### `clio inventory` (alias: `inv`) — Inventory tracking
 | Subcommand | Key flags |

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 4.58.1
+version: 4.58.4
 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/jobs/SKILL.md

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