jaz-clio 4.32.1 → 4.32.3

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 4.32.1
+version: 4.32.3
 description: Complete reference for the Jaz REST API — the accounting platform backend. Use this skill whenever building, modifying, debugging, or extending any code that calls the API — including API clients, integrations, data seeding, test data, or new endpoint work. Contains every field name, response shape, error, gotcha, and edge case discovered through live production testing.
 license: MIT
 compatibility: Requires Jaz API key (x-jk-api-key header). Works with Claude Code, Google Antigravity, OpenAI Codex, GitHub Copilot, Cursor, and any agent that reads markdown.
@@ -281,7 +281,7 @@ Bills, invoices, and credit notes share identical mandatory field specs. Adding
 106. **Contact PUT uses `email` (string), not `emails` (array)** — GET returns `emails: [{email, label}]` (array) but PUT accepts `email: "user@example.com"` (string). Sending the `emails` array in PUT body causes 400 "Invalid request body". The CLI and tool executor handle this automatically via read-modify-write with the correct field.
 
 ### Quick Fix (Bulk Update)
-107. **20 Quick Fix endpoints for bulk-updating transactions and line items** — `POST /api/v1/quick-fix/{entity}` with `{ resourceIds: [...], attributes: {...} }`. Response: `{ updated: [...], failed: [{ resourceId, error, errorCode }] }`. Entities grouped by domain: **ARAP**: invoices, bills, customer-credit-notes, supplier-credit-notes. **Accounting**: journals, cash-entries. **Schedulers**: sale-schedules, purchase-schedules, subscription-schedules, journal-schedules. Line-item endpoints add `/line-items` suffix. ARAP line items use `{ lineItemResourceIds, attributes }`. Scheduler line items use `{ schedulerUpdates: [{ schedulerResourceId, lineItemUpdates }] }`. **Known gotcha**: `valueDate` (and `dueDate` for ARAP) must currently be included in `attributes` even when unchanged — absent fields are treated as "remove" rather than "keep existing". This will be fixed server-side.
+107. **20 Quick Fix endpoints for bulk-updating transactions and line items** — `POST /api/v1/quick-fix/{entity}` with `{ resourceIds: [...], attributes: {...} }`. Response: `{ updated: string[], failed: [{ resourceId, error, errorCode }] }`. **HTTP status codes**: 200 = complete success (`failed` always empty). **207 Multi-Status** = partial or total failure with per-item detail (same response shape as 200 — check `failed` array). 422 = total failure with no per-item breakdown (rare, standard error shape). On 207, retry only `failed` resourceIds — `updated` ones are already done. Entities grouped by domain: **ARAP**: invoices, bills, customer-credit-notes, supplier-credit-notes. **Accounting**: journals, cash-entries. **Schedulers**: sale-schedules, purchase-schedules, subscription-schedules, journal-schedules. Line-item endpoints add `/line-items` suffix. ARAP line items use `{ lineItemResourceIds, attributes }`. Scheduler line items use `{ schedulerUpdates: [{ schedulerResourceId, lineItemUpdates }] }`. **Known gotcha**: `valueDate` (and `dueDate` for ARAP) must currently be included in `attributes` even when unchanged — absent fields are treated as "remove" rather than "keep existing". This will be fixed server-side.
 
 ### Transfer Trial Balance
 108. **Transfer Trial Balance** (`POST /api/v1/transfer-trial-balance`) creates opening balance entries. Uses `journalEntries` (NOT `lines` — this is a journal type). Always ACTIVE (no draft mode), reference auto-generated as "Transfer Trial Balance", minimum 1 entry, entries cannot have 0 amounts, skips lock date validation. Each entry: `{ accountResourceId, type: "DEBIT"|"CREDIT", amount }`.

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

@@ -1882,6 +1882,8 @@ POST /api/v1/quick-fix/sale-schedules/line-items
 
 ### Response (all 20 endpoints)
 
+**HTTP status codes**: 200 = complete success (`failed` always `[]`). **207 Multi-Status** = partial or total failure with per-item detail (same body shape as 200). 422/500 = total failure, standard error shape (no per-item data). On 207, retry only `failed` resourceIds — `updated` ones are done.
+
 ```json
 {
   "updated": ["uuid1", "uuid2"],

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

@@ -821,6 +821,8 @@ Journals support a top-level `currency` object to create entries in a foreign cu
 
 ### Quick Fix Errors
 
+**207 Multi-Status** — Not an error. The API returns 207 when one or more items in the batch failed. Response body is the same shape as 200: `{ updated: [...], failed: [{ resourceId, error, errorCode }] }`. Always check `failed.length` — on partial failure, some items succeeded (`updated`) while others failed (`failed`). Retry pattern: only retry the `failed` resourceIds, not the whole batch.
+
 **"Not allowed to remove valueDate of a sale/purchase/journal"** — `valueDate` absent from `attributes`. Currently must be included even if unchanged. Server-side fix pending.
 
 **"Not allowed to remove dueDate of a sale"** — Same pattern for `dueDate` on invoices.

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

@@ -708,7 +708,7 @@ Bulk-update transactions or line items in a single call. Pattern: `POST /api/v1/
 **Schedulers**: `sale-schedules`, `purchase-schedules`, `subscription-schedules`, `journal-schedules` (× 2 = 8)
 
 Request: `{ resourceIds: [...], attributes: {...} }` (transactions) or `{ lineItemResourceIds: [...], attributes: {...} }` (line items) or `{ schedulerUpdates: [...] }` (scheduler line items).
-Response: `{ updated: [...], failed: [{ resourceId, error, errorCode }] }`.
+Response: `{ updated: [...], failed: [{ resourceId, error, errorCode }] }`. HTTP 200 = all succeeded. **207 Multi-Status** = partial failure (check both arrays). 422/500 = total failure (standard error shape).
 
 ---
 

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 4.32.1
+version: 4.32.3
 description: Accounting data conversion skill — migrates customer data from Xero, QuickBooks, Sage, MYOB, and Excel exports to Jaz. Covers config, quick, and full conversion workflows, Excel parsing, CoA/contact/tax/items mapping, clearing accounts, TTB, and TB verification.
 ---
 

package/assets/skills/jobs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-jobs
-version: 4.32.1
+version: 4.32.3
 description: 12 accounting jobs for SMB bookkeepers and accountants — month-end, quarter-end, and year-end close playbooks plus 9 ad-hoc operational jobs (bank recon, document collection, GST/VAT filing, payment runs, credit control, supplier recon, audit prep, fixed asset review, statutory filing). Jobs can have paired tools as nested subcommands (e.g., `clio jobs bank-recon match`, `clio jobs document-collection ingest`, `clio jobs statutory-filing sg-cs`). Paired with an interactive CLI blueprint generator (clio jobs).
 license: MIT
 compatibility: Works with Claude Code, Claude Cowork, Claude.ai, and any agent that reads markdown. For API payloads, load the jaz-api skill. For individual transaction patterns, load the jaz-recipes skill.

package/assets/skills/transaction-recipes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-recipes
-version: 4.32.1
+version: 4.32.3
 description: 16 IFRS-compliant recipes for complex multi-step accounting in Jaz — prepaid amortization, deferred revenue, loan schedules, IFRS 16 leases, hire purchase, fixed deposits, asset disposal, FX revaluation, ECL provisioning, IAS 37 provisions, dividends, intercompany, and capital WIP. Each recipe includes journal entries, capsule structure, and verification steps. Paired with 13 financial calculators that produce execution-ready blueprints with workings.
 license: MIT
 compatibility: Works with Claude Code, Claude Cowork, Claude.ai, and any agent that reads markdown. For API payloads, load the jaz-api skill alongside this one.

package/dist/commands/quick-fix.js

@@ -129,7 +129,7 @@ function formatResult(result, json) {
     if (result.failed.length > 0) {
         console.log(chalk.red(`Failed ${result.failed.length} item(s):`));
         for (const f of result.failed) {
-            console.log(`  ${chalk.cyan(f.resourceId)}  ${chalk.red(f.error)}${f.errorCode ? ` (${f.errorCode})` : ''}`);
+            console.log(`  ${chalk.cyan(f.resourceId)}  ${chalk.red(f.error)} (${f.errorCode})`);
         }
         process.exitCode = 1;
     }

package/dist/core/api/quick-fix.js

@@ -4,6 +4,13 @@ export const QUICK_FIX_ARAP = ['invoices', 'bills', 'customer-credit-notes', 'su
 const QUICK_FIX_ACCOUNTING = ['journals', 'cash-entries'];
 const QUICK_FIX_SCHEDULERS = ['sale-schedules', 'purchase-schedules', 'subscription-schedules', 'journal-schedules'];
 export const QUICK_FIX_ENTITIES = [...QUICK_FIX_ARAP, ...QUICK_FIX_ACCOUNTING, ...QUICK_FIX_SCHEDULERS];
+/** Normalize API response — guarantee errorCode is always present. */
+export function normalizeQuickFixResult(raw) {
+    return {
+        updated: raw.updated ?? [],
+        failed: (raw.failed ?? []).map(f => ({ ...f, errorCode: f.errorCode ?? 'UNKNOWN_ERROR' })),
+    };
+}
 // ── Transaction-Level Quick Fix ──────────────────────────────────
 export async function quickFix(client, entity, body) {
     const attrs = { ...body.attributes };
@@ -13,11 +20,13 @@ export async function quickFix(client, entity, body) {
     if (QUICK_FIX_ARAP.includes(entity) && attrs.valueDate && !hasDueDate) {
         attrs.dueDate = attrs.valueDate;
     }
-    return client.post(`/api/v1/quick-fix/${entity}`, { ...body, attributes: attrs });
+    const raw = await client.post(`/api/v1/quick-fix/${entity}`, { ...body, attributes: attrs });
+    return normalizeQuickFixResult(raw);
 }
 // ── Line-Item-Level Quick Fix ────────────────────────────────────
 // ARAP: { lineItemResourceIds: string[], attributes: {...} }
 // Schedulers: { schedulerUpdates: [{ schedulerResourceId, lineItemUpdates: [...] }] }
 export async function quickFixLineItems(client, entity, body) {
-    return client.post(`/api/v1/quick-fix/${entity}/line-items`, body);
+    const raw = await client.post(`/api/v1/quick-fix/${entity}/line-items`, body);
+    return normalizeQuickFixResult(raw);
 }

package/dist/core/intelligence/account-resolver.js

@@ -26,7 +26,7 @@ export function resolveAccount(query, accounts, options = {}) {
  * Resolve a single best-matching account, or null if no good match.
  */
 export function resolveBestAccount(query, accounts) {
-    const matches = resolveAccount(query, accounts, { threshold: 0.6, limit: 1 });
+    const matches = resolveAccount(query, accounts, { threshold: 0.45, limit: 1 });
     return matches.length > 0 ? matches[0].item : null;
 }
 /**

package/dist/core/registry/tools.js

@@ -595,7 +595,7 @@ export const TOOL_DEFINITIONS = [
     },
     {
         name: 'pay_invoice',
-        description: 'Record a payment against an invoice.',
+        description: 'Record a payment against an invoice. Invoice must be APPROVED/UNPAID before payment — draft or voided invoices cannot be paid. If the invoice is still a DRAFT, call finalize_invoice first.',
         params: {
             resourceId: { type: 'string', description: 'Invoice resourceId' },
             paymentAmount: { type: 'number', description: 'Amount to pay (in bank currency)' },
@@ -1832,7 +1832,7 @@ Steps: 1) search_customer_credit_notes with status UNAPPLIED for the same contac
         description: `Record money received INTO a bank account from an EXTERNAL source (customer payment, refund received, deposit from outside).
 WHEN TO USE: customer payments received, refunds from suppliers, insurance payouts, external deposits.
 WHEN NOT TO USE: moving money between your own bank/cash accounts — use create_cash_transfer instead.
-- accountResourceId MUST be a Bank Accounts type account — use list_bank_accounts or search_accounts with accountType "Bank Accounts" to find the correct one. Non-bank accounts are rejected.
+- CRITICAL: accountResourceId MUST be a Bank/Cash account from list_bank_accounts output. Using expense, revenue, or liability accounts will fail. Always call list_bank_accounts first to find valid accounts.
 - lines are the offsetting entries. Each needs accountResourceId, type (DEBIT/CREDIT), and amount. IMPORTANT: offset accounts must be regular P&L or balance sheet accounts (expense, revenue, asset, liability) — NOT bank/cash accounts or controlled accounts (AR/AP). Example: Service Revenue, Interest Income, Other Income.
 - The API enforces account separation: cash-in bank account cannot appear in lines.`,
         params: {
@@ -1861,7 +1861,7 @@ WHEN NOT TO USE: moving money between your own bank/cash accounts — use create
         description: `Record money paid OUT FROM a bank account to an EXTERNAL party (expense, supplier payment, reimbursement, withdrawal).
 WHEN TO USE: expenses paid, supplier payments, reimbursements, withdrawals to external parties.
 WHEN NOT TO USE: moving money between your own bank/cash accounts — use create_cash_transfer instead.
-- accountResourceId MUST be a Bank Accounts type account — use list_bank_accounts or search_accounts with accountType "Bank Accounts" to find the correct one. Non-bank accounts are rejected.
+- CRITICAL: accountResourceId MUST be a Bank/Cash account from list_bank_accounts output. Using expense, revenue, or liability accounts will fail with "CashOut journal account cannot be in CashIn Entries". Always call list_bank_accounts first to find valid accounts.
 - lines are the offsetting entries. Each needs accountResourceId, type (DEBIT for cash-out expenses), and amount (must be > 0). For cash-out: use type "DEBIT" on the expense/offset account. IMPORTANT: offset accounts must be regular P&L or balance sheet accounts (expense, revenue, asset, liability) — NOT bank/cash accounts or controlled accounts (AR/AP). Example: { accountResourceId: "<expense-acct-id>", type: "DEBIT", amount: 100 }.
 - The API enforces account separation: cash-out bank account cannot appear in lines.`,
         params: {
@@ -3115,7 +3115,7 @@ Dynamic strings for reference/name/notes: {{Day}}, {{Date}}, {{Date+X}}, {{DateR
     },
     {
         name: 'create_bank_rule',
-        description: `Create a bank reconciliation rule. Rules auto-match bank records to transactions during reconciliation.
+        description: `Create a bank reconciliation rule. Rules auto-match bank records to transactions during reconciliation. When the user asks to create a bank rule, use this tool directly — do not only list existing rules.
 - appliesToReconciliationAccount: the bank account UUID this rule applies to (NOT "ResourceId" suffix)
 - configuration MUST be nested under reconcileWithDirectCashEntry key
 - configuration.reconcileWithDirectCashEntry.reference is REQUIRED (omitting causes error)
@@ -3309,7 +3309,7 @@ Dynamic strings for name/reference: {{bankReference}} (e.g., INV-03/01/2025-01),
     },
     {
         name: 'mark_fixed_asset_sold',
-        description: 'Mark a fixed asset as sold. Links to the sale transaction and records gain/loss.',
+        description: 'Mark a fixed asset as sold. Links to the sale transaction and records gain/loss. When the user asks to sell an asset, use this tool directly — retrieve the asset first with list_fixed_assets or search_fixed_assets to get the resourceId.',
         params: {
             resourceId: { type: 'string', description: 'Fixed asset resourceId' },
             depreciationEndDate: { type: 'string', description: 'Final depreciation date (YYYY-MM-DD)' },
@@ -3338,7 +3338,7 @@ Dynamic strings for name/reference: {{bankReference}} (e.g., INV-03/01/2025-01),
     },
     {
         name: 'undo_fixed_asset_disposal',
-        description: 'Undo a fixed asset disposal (discard or sale). Restores the asset to active status.',
+        description: 'Undo a fixed asset disposal (discard or sale). Restores the asset to active status. When the user asks to reverse or undo a disposal, use this tool directly.',
         params: {
             resourceId: { type: 'string', description: 'Fixed asset resourceId' },
         },
@@ -3407,7 +3407,7 @@ Dynamic strings for reference/line item name/notes: {{Day}}, {{Date}}, {{Date+X}
     },
     {
         name: 'update_subscription',
-        description: 'Update an existing subscription (interval, end date, or transaction template). NOTE: accountResourceId and taxProfileResourceId on line items are immutable after creation — to change them, cancel and recreate.',
+        description: 'Update an existing subscription (interval, end date, or transaction template). When the user asks to update a subscription, use this tool directly. NOTE: accountResourceId and taxProfileResourceId on line items are immutable after creation — to change them, cancel and recreate.',
         params: {
             resourceId: { type: 'string', description: 'Subscription resourceId' },
             interval: { type: 'string', enum: ['WEEKLY', 'MONTHLY', 'QUARTERLY', 'YEARLY'] },
@@ -3519,7 +3519,7 @@ Dynamic strings for reference/line item name/notes: {{Day}}, {{Date}}, {{Date+X}
     },
     {
         name: 'generate_bank_recon_summary',
-        description: 'Generate bank reconciliation summary for a specific bank account. Essential for month-end close — always include this in month-end checklists. Use for bank recon status, unreconciled items count, or reconciliation summaries.',
+        description: 'Generate bank reconciliation summary for a specific bank account. Essential for month-end close — call this for each in-scope bank account for the current entity and reporting period. Use for bank recon status, unreconciled items count, or reconciliation summaries.',
         params: {
             bankAccountResourceId: { type: 'string', description: 'Bank account resourceId' },
             primarySnapshotStartDate: { type: 'string', description: 'Period start date (YYYY-MM-DD)' },
@@ -3577,7 +3577,7 @@ Dynamic strings for reference/line item name/notes: {{Day}}, {{Date}}, {{Date+X}
     },
     {
         name: 'generate_ar_report',
-        description: 'Generate accounts receivable aging report. Shows outstanding invoices grouped by aging buckets.',
+        description: 'Generate accounts receivable aging report. Shows outstanding invoices grouped by aging buckets. Use this when discussing customer payment allocation, credit control, or AR status — generate the report to show the full picture.',
         params: {
             endDate: { type: 'string', description: 'Report date (YYYY-MM-DD) — point-in-time snapshot' },
         },
@@ -4041,6 +4041,7 @@ Returns per-contact result: created, skipped (duplicate), or failed.`,
 Entities — ARAP: invoices, bills, customer-credit-notes, supplier-credit-notes. Accounting: journals, cash-entries. Schedulers: sale-schedules, purchase-schedules, subscription-schedules, journal-schedules.
 Common attributes: valueDate, contactResourceId, tags (string array, e.g. ["Q1"]), capsuleResourceId. Entity-specific: dueDate (invoices/bills/CNs), invoiceNotes, templateResourceId, currencySettings, taxCurrencySettings, customFields.
 NOTE: valueDate (and dueDate for invoices/bills) MUST be included even if unchanged — the API treats absent fields as "remove".
+Response: { updated: string[], failed: [{ resourceId, error, errorCode }] }. On partial failure (HTTP 207), both arrays may be populated — always check failed.length. On 207, only retry failed resourceIds (updated ones are done).
 Example call: { entity: "invoices", resourceIds: ["id1","id2"], attributes: { valueDate: "2026-03-01", dueDate: "2026-04-01", tags: ["Q1"] } }`,
         params: {
             entity: { type: 'string', enum: [...QUICK_FIX_ENTITIES], description: 'Transaction type to update' },
@@ -4062,7 +4063,8 @@ Works for ALL entity types including cash-in and cash-out entries — use for bu
 For ARAP (invoices, bills, credit notes) and accounting (journals, cash-entries): pass lineItemResourceIds + attributes.
 For schedulers: pass schedulerUpdates array with per-scheduler lineItemUpdates.
 ARAP line item attributes: name, quantity, unit, unitPrice, discount, itemResourceId, organizationAccountResourceId, taxProfileResourceId, classifierConfig. Bill/supplier-CN also: withholdingTax.
-Journal/cash-entry line items: organizationAccountResourceId, amount, description, taxProfileResourceId, classifierConfig.`,
+Journal/cash-entry line items: organizationAccountResourceId, amount, description, taxProfileResourceId, classifierConfig.
+Response: { updated: string[], failed: [{ resourceId, error, errorCode }] }. On partial failure (HTTP 207), both arrays may be populated — always check failed.length.`,
         params: {
             entity: { type: 'string', enum: [...QUICK_FIX_ENTITIES], description: 'Transaction type' },
             lineItemResourceIds: { type: 'array', items: { type: 'string' }, description: 'Line item resourceIds to update (ARAP + accounting entities)' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jaz-clio",
-  "version": "4.32.1",
+  "version": "4.32.3",
   "description": "Clio — Command Line Interface Orchestrator for Jaz AI.",
   "type": "module",
   "bin": {