jaz-clio 4.30.11 → 4.30.13

package/README.md

@@ -235,7 +235,7 @@ Every command supports `--json` for structured output — ideal for piping to ot
 
 ## MCP Server
 
-Expose all 207 CLI tools to AI coding and coworking agents via the Model Context Protocol (MCP). The server runs locally on your machine — no cloud, no ports. API calls go directly from your machine to the Jaz API.
+Expose all 210 CLI tools to AI coding and coworking agents via the Model Context Protocol (MCP). The server runs locally on your machine — no cloud, no ports. API calls go directly from your machine to the Jaz API.
 
 **Claude Code:**
 

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 4.30.11
+version: 4.30.13
 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.

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 4.30.11
+version: 4.30.13
 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.30.11
+version: 4.30.13
 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.30.11
+version: 4.30.13
 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/core/registry/namespaces.js

@@ -26,9 +26,14 @@ export const TOOL_NAMESPACES = [
         groups: ['journals'],
     },
     {
-        name: 'cashflows',
-        description: 'Cash-in receipts, cash-out disbursements, cash transfers between own accounts, petty cash. WHEN TO USE: external cash received → cash-in. External cash paid → cash-out. Moving funds between own accounts → cash transfer.',
-        groups: ['cash_entries', 'cash_transfers'],
+        name: 'cash_entries',
+        description: 'Cash-in receipts and cash-out disbursements for external cash movements. WHEN TO USE: money received from customers/external → cash-in. Money paid to suppliers/external → cash-out. For internal account-to-account transfers, use cash_transfers namespace.',
+        groups: ['cash_entries'],
+    },
+    {
+        name: 'cash_transfers',
+        description: 'Cash transfers between your own bank/cash accounts and cashflow transaction search. WHEN TO USE: moving funds between own accounts (main bank → petty cash, USD → SGD). For external receipts/payments, use cash_entries namespace.',
+        groups: ['cash_transfers'],
     },
     // ── Banking ─────────────────────────────────────────────────
     {

package/dist/core/registry/tools.js

@@ -22,7 +22,7 @@ import { planRecipe, extractBlueprint } from '../recipe/plan.js';
 import { executeRecipe } from '../recipe/engine.js';
 import { resolveRecipeAccounts, resolveRecipeContact, resolveRecipeBankAccount } from '../intelligence/recipe-resolver.js';
 import { getBankAccount, searchBankRecords } from '../api/bank.js';
-import { searchCashflowTransactions } from '../api/cashflow.js';
+import { deleteCashflowJournal, searchCashflowTransactions } from '../api/cashflow.js';
 import { listBookmarks, getBookmark, createBookmarks, updateBookmark } from '../api/bookmarks.js';
 import { listOrgUsers, searchOrgUsers, inviteOrgUser, updateOrgUser, removeOrgUser } from '../api/org-users.js';
 import { listPayments, searchPayments } from '../api/payments.js';
@@ -653,6 +653,18 @@ export const TOOL_DEFINITIONS = [
         execute: async (ctx, input) => {
             const { resourceId: rid, ...overrides } = input;
             const merged = await fetchAndMerge(ctx.client, 'invoice', rid, overrides);
+            // Dedup guard: if reference already exists on another invoice, auto-suffix to avoid 422
+            if (merged.reference) {
+                const ref = merged.reference;
+                const existing = await searchInvoices(ctx.client, {
+                    filter: { reference: { eq: ref } }, limit: 1, offset: 0,
+                    sort: { sortBy: ['valueDate'], order: 'DESC' },
+                });
+                const dupes = (existing.data ?? []).filter((inv) => inv.resourceId !== rid);
+                if (dupes.length > 0) {
+                    merged.reference = `${ref}-${Date.now() % 10000}`;
+                }
+            }
             return finalizeInvoice(ctx.client, rid, merged);
         },
     },
@@ -1793,8 +1805,8 @@ Steps: 1) search_customer_credit_notes with status UNAPPLIED for the same contac
 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.
-- journalEntries are the offsetting entries (e.g., revenue account). Each needs accountResourceId, type (DEBIT/CREDIT), and amount.
-- The API enforces account separation: cash-in accounts cannot be used for cash-out.`,
+- journalEntries 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 journalEntries.`,
         params: {
             reference: { type: 'string', description: 'Reference number' },
             valueDate: { type: 'string', description: 'Date (YYYY-MM-DD)' },
@@ -1822,8 +1834,8 @@ WHEN NOT TO USE: moving money between your own bank/cash accounts — use create
 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.
-- journalEntries are the offsetting entries (e.g., expense account). Each needs accountResourceId, type (DEBIT/CREDIT), and amount.
-- The API enforces account separation: cash-out accounts cannot be used for cash-in.`,
+- journalEntries 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: Utilities Expense, Office Supplies, Service Revenue.
+- The API enforces account separation: cash-out bank account cannot appear in journalEntries.`,
         params: {
             reference: { type: 'string', description: 'Reference number' },
             valueDate: { type: 'string', description: 'Date (YYYY-MM-DD)' },
@@ -1872,7 +1884,7 @@ WHEN NOT TO USE: moving money between your own bank/cash accounts — use create
         readOnly: false,
         execute: async (ctx, input) => {
             const { resourceId: rid, ...data } = input;
-            return updateCashIn(ctx.client, rid, { ...data, resourceId: rid });
+            return updateCashIn(ctx.client, rid, data);
         },
     },
     {
@@ -1903,7 +1915,7 @@ WHEN NOT TO USE: moving money between your own bank/cash accounts — use create
         readOnly: false,
         execute: async (ctx, input) => {
             const { resourceId: rid, ...data } = input;
-            return updateCashOut(ctx.client, rid, { ...data, resourceId: rid });
+            return updateCashOut(ctx.client, rid, data);
         },
     },
     // ── Cash Transfers ─────────────────────────────────────────────
@@ -1949,6 +1961,9 @@ WHEN NOT TO USE: receiving money from external parties (use create_cash_in) or p
             return createCashTransfer(ctx.client, data);
         },
     },
+    deleteTool('delete_cash_in', 'Delete (void) a cash-in entry. Uses parentEntityResourceId from create response.', 'cash_entries', (client, id) => deleteCashflowJournal(client, id)),
+    deleteTool('delete_cash_out', 'Delete (void) a cash-out entry. Uses parentEntityResourceId from create response.', 'cash_entries', (client, id) => deleteCashflowJournal(client, id)),
+    deleteTool('delete_cash_transfer', 'Delete (void) a cash transfer. Uses parentEntityResourceId from create response.', 'cash_transfers', (client, id) => deleteCashflowJournal(client, id)),
     // ── Scheduled Transactions ─────────────────────────────────────
     listTool('list_scheduled_invoices', 'List scheduled (recurring) invoices. Paginated.', 'schedulers', (client, off, lim) => listScheduledInvoices(client, { limit: lim, offset: off })),
     listTool('list_scheduled_bills', 'List scheduled (recurring) bills. Paginated.', 'schedulers', (client, off, lim) => listScheduledBills(client, { limit: lim, offset: off })),
@@ -2237,7 +2252,8 @@ Available export types: trial-balance, balance-sheet, profit-and-loss, general-l
     // ── Recipes ───────────────────────────────────────────────────
     {
         name: 'plan_recipe',
-        description: `Plan a transaction recipe — run a financial calculator and show what accounts, contacts, and bank accounts are needed. This is READ-ONLY (no API calls, no transactions created). To actually create the transactions, call execute_recipe.
+        description: `Plan a transaction recipe — run a financial calculator and show what accounts, contacts, and bank accounts are needed. This is READ-ONLY (no API calls, no transactions created).
+After planning, ALWAYS use execute_recipe to create all transactions in one call — do NOT manually create journals/invoices/bills.
 Supported recipes: ${RECIPE_TYPES.join(', ')}
 Returns: capsule type/name, required accounts, step breakdown (journal/bill/invoice/cash-in/cash-out), and full calculator results.
 Use this BEFORE execute_recipe to verify requirements. Parameters vary by recipe — see recipe skill docs for per-recipe params.
@@ -2295,8 +2311,8 @@ CRITICAL: ALWAYS call this tool for ANY calculation involving: depreciation, amo
     },
     {
         name: 'execute_recipe',
-        description: `Execute a transaction recipe end-to-end — run calculator, create capsule, post all entries.
-Replaces ~20 manual tool calls with 1 call. Use plan_recipe first to verify requirements.
+        description: `Execute a transaction recipe end-to-end — run calculator, create capsule, post all entries in one call.
+PREFERRED over manual transaction creation — replaces ~20 manual tool calls. After plan_recipe, ALWAYS use this tool (not create_journal/create_invoice/create_cash_out).
 Supported recipes: ${RECIPE_TYPES.join(', ')}
 Requires startDate (to generate blueprint with dated steps).
 Auto-resolves accounts from chart of accounts. Provide bankAccountName for recipes with cash-in/cash-out steps, contactName for recipes with invoice/bill steps.`,
@@ -3065,14 +3081,15 @@ CRITICAL:
     {
         name: 'create_bank_rule',
         description: `Create a bank reconciliation rule. Rules auto-match bank records to transactions during reconciliation.
-- actionType: "RECONCILE_WITH_DIRECT_CASH_ENTRY" (most common)
+- actionType: "RECONCILE_WITH_DIRECT_CASH_ENTRY" (most common — creates cash-in/cash-out on match)
 - appliesToReconciliationAccountResourceId: the bank account this rule applies to
-- configuration: allocation settings (fixed amounts, percentages, accounts, tax)`,
+- configuration MUST include: allocationType ("PERCENTAGE" or "FIXED"), allocationDetails array with organizationAccountResourceId + percentage (or fixedAmount) + optional taxProfileResourceId
+Example configuration: { "allocationType": "PERCENTAGE", "allocationDetails": [{ "organizationAccountResourceId": "<revenue-account-id>", "percentage": 100 }] }`,
         params: {
-            name: { type: 'string', description: 'Rule name (e.g., "PayNow Sales")' },
-            actionType: { type: 'string', description: 'Action type (e.g., "RECONCILE_WITH_DIRECT_CASH_ENTRY")' },
+            name: { type: 'string', description: 'Rule name (e.g., "PayNow Sales", "STRIPE Payouts")' },
+            actionType: { type: 'string', description: 'Action type: "RECONCILE_WITH_DIRECT_CASH_ENTRY" (creates cash entry on match)' },
             appliesToReconciliationAccountResourceId: { type: 'string', description: 'Bank account resourceId this rule applies to' },
-            configuration: { type: 'object', description: 'Rule configuration (allocation type, accounts, percentages, tax settings)' },
+            configuration: { type: 'object', description: 'Required structure: { allocationType: "PERCENTAGE"|"FIXED", allocationDetails: [{ organizationAccountResourceId: "<account-id>", percentage: 100, taxProfileResourceId?: "<tax-id>" }] }' },
         },
         required: ['name', 'actionType', 'appliesToReconciliationAccountResourceId', 'configuration'],
         group: 'bank_rules',
@@ -3320,7 +3337,7 @@ Use for: software licenses, retainer services, recurring SaaS billing. Invoices
                 description: 'Line items (name, unitPrice, quantity only — account/tax set at top level)',
             },
         },
-        required: ['interval', 'startDate', 'contactResourceId', 'lineItems', 'accountResourceId'],
+        required: ['interval', 'startDate', 'contactResourceId', 'lineItems', 'accountResourceId', 'valueDate', 'dueDate'],
         group: 'subscriptions',
         readOnly: false,
         execute: async (ctx, input) => {
@@ -3347,10 +3364,10 @@ Use for: software licenses, retainer services, recurring SaaS billing. Invoices
     },
     {
         name: 'update_subscription',
-        description: 'Update an existing subscription (interval, end date, or transaction template).',
+        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.',
         params: {
             resourceId: { type: 'string', description: 'Subscription resourceId' },
-            interval: { type: 'string', enum: ['WEEKLY', 'MONTHLY', 'YEARLY'] },
+            interval: { type: 'string', enum: ['WEEKLY', 'MONTHLY', 'QUARTERLY', 'YEARLY'] },
             endDate: { type: 'string', description: 'New end date (YYYY-MM-DD)' },
             data: { type: 'object', description: 'Updated transaction template' },
         },
@@ -3370,6 +3387,7 @@ Use for: software licenses, retainer services, recurring SaaS billing. Invoices
             resourceId: { type: 'string', description: 'Subscription resourceId' },
             cancelDateType: { type: 'string', enum: ['END_OF_CURRENT_PERIOD', 'END_OF_LAST_PERIOD', 'CUSTOM_DATE'], description: 'When to end (default: END_OF_CURRENT_PERIOD)' },
             endDate: { type: 'string', description: 'Custom cancel date YYYY-MM-DD (only with CUSTOM_DATE)' },
+            proratedAdjustmentLineText: { type: 'string', description: 'Label for proration line item (default: "Prorated adjustment")' },
         },
         required: ['resourceId'],
         group: 'subscriptions',
@@ -3377,6 +3395,7 @@ Use for: software licenses, retainer services, recurring SaaS billing. Invoices
         execute: async (ctx, input) => cancelSubscription(ctx.client, input.resourceId, {
             cancelDateType: input.cancelDateType,
             endDate: input.endDate,
+            proratedAdjustmentLineText: input.proratedAdjustmentLineText,
         }),
     },
     {
@@ -3484,11 +3503,11 @@ Use for: software licenses, retainer services, recurring SaaS billing. Invoices
     },
     {
         name: 'generate_fa_summary',
-        description: 'Generate fixed assets summary report grouped by type, contact, or currency.',
+        description: 'Generate fixed assets summary report grouped by account, type, category, or status.',
         params: {
             primarySnapshotStartDate: { type: 'string', description: 'Period start date (YYYY-MM-DD)' },
             primarySnapshotEndDate: { type: 'string', description: 'Period end date (YYYY-MM-DD)' },
-            groupBy: { type: 'string', enum: ['CONTACT', 'CONTACT_GROUP', 'DUE_MONTH', 'RELATIONSHIP', 'CURRENCY'], description: 'Grouping dimension' },
+            groupBy: { type: 'string', enum: ['ACCOUNT', 'TYPE', 'CATEGORY', 'STATUS'], description: 'Grouping dimension' },
             currencyCode: { type: 'string', description: 'Currency code' },
         },
         required: ['primarySnapshotStartDate', 'primarySnapshotEndDate', 'groupBy'],

package/package.json

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