jaz-clio 4.30.16 → 4.30.18

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 4.30.16
+version: 4.30.18
 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,6 +281,15 @@ Bills, invoices, and credit notes share identical mandatory field specs. Adding
 ### 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.
 
+### Scheduler Dynamic Strings
+108. **Scheduler placeholder strings** — All scheduled transactions (invoices, bills, journals, subscriptions) support dynamic strings in any free text field (`reference`, line item `name`, `notes`). Strings are replaced with values relative to the **transaction date**: `{{Day}}` → day name (Monday), `{{Date}}` → full date (09 Mar 2026), `{{Date+X}}` → date + X days, `{{DateRange:X}}` → date range spanning X days (min 1, max 999), `{{Month}}` → month name (March), `{{Month+X}}` → month + X months, `{{MonthRange:X}}` → month range spanning X months, `{{Year}}` → year (2026), `{{Year+X}}` → year + X years. Example: `reference: "INV-{{Month}}-{{Year}}"` → `"INV-March-2026"` for a March transaction.
+
+### Bank Rule Dynamic Strings
+109. **Bank rule placeholder strings** — Bank reconciliation rules support dynamic strings in any free text field (`name`, `reference`, cash entry description). Strings are replaced with actual **bank record** values during reconciliation: `{{bankReference}}` → bank record reference (e.g., INV-03/01/2025-01), `{{bankPayee}}` → payer/payee name (e.g., Fruit Planet), `{{bankDescription}}` → transaction description (e.g., QR Payment), `{{bankDate}}` → transaction date (e.g., 09 Mar 2026). Example: `reference: "{{bankPayee}} - {{bankReference}}"`.
+
+### Quick Fix Tag Field
+110. **Quick-fix uses `tags` (string array) — e.g., `"tags": ["Q1"]`** — The `attributes` object in quick-fix transaction endpoints accepts `tags` as a string array (e.g., `"tags": ["Q1"]`). `tag` (singular) is silently ignored. This matches the `tags` array format used on create/update for all transaction types. The CLI `--tag` flag auto-wraps to `tags: [name]`.
+
 ## Supporting Files
 
 For detailed reference, read these files in this skill directory:

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 4.30.16
+version: 4.30.18
 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.16
+version: 4.30.18
 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.16
+version: 4.30.18
 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/bank-rules.js

@@ -12,7 +12,14 @@ const BANK_RULES_COLUMNS = [
 export function registerBankRulesCommand(program) {
     const cmd = program
         .command('bank-rules')
-        .description('Manage bank reconciliation rules');
+        .description('Manage bank reconciliation rules')
+        .addHelpText('after', `
+Dynamic Strings (usable in name, reference — any free text field):
+  {{bankReference}}   Bank record reference (e.g., INV-03/01/2025-01)
+  {{bankPayee}}       Payer/payee name (e.g., Fruit Planet)
+  {{bankDescription}} Transaction description (e.g., QR Payment)
+  {{bankDate}}        Transaction date (e.g., 09 Mar 2026)
+Strings are replaced with actual bank record values during reconciliation.`);
     cmd
         .command('list')
         .description('List bank rules')

package/dist/commands/quick-fix.js

@@ -24,7 +24,7 @@ Entities (grouped by domain):
   Schedulers:  sale-schedules, purchase-schedules, subscription-schedules, journal-schedules
 
 Examples:
-  clio quick-fix invoices --ids id1,id2 --attributes '{"valueDate":"2026-01-15","tags":["Q1"]}'
+  clio quick-fix invoices --ids id1,id2 --attributes '{"valueDate":"2026-01-15","tag":"Q1"}'
   clio quick-fix bills --ids id1 --date 2026-02-01 --due 2026-03-01 --tag Marketing
   clio quick-fix journals --line-items --ids li1,li2 --attributes '{"organizationAccountResourceId":"<uuid>"}'
   clio quick-fix sale-schedules --line-items --input scheduler-updates.json`)
@@ -34,7 +34,7 @@ Examples:
         .option('--input <file>', 'Read attributes/body from JSON file')
         .option('--date <date>', 'Shorthand: set valueDate (YYYY-MM-DD)')
         .option('--due <date>', 'Shorthand: set dueDate (YYYY-MM-DD)')
-        .option('--tag <name>', 'Shorthand: set tags to [name]')
+        .option('--tag <name>', 'Shorthand: set tag')
         .option('--contact <id>', 'Shorthand: set contactResourceId')
         .option('--account <id>', 'Shorthand: set organizationAccountResourceId (line items)')
         .option('--tax-profile <id>', 'Shorthand: set taxProfileResourceId (line items)')

package/dist/commands/schedulers.js

@@ -17,7 +17,19 @@ const SCHEDULER_COLUMNS = [
 export function registerSchedulersCommand(program) {
     const cmd = program
         .command('schedulers')
-        .description('Manage scheduled (recurring) transactions');
+        .description('Manage scheduled (recurring) transactions')
+        .addHelpText('after', `
+Dynamic Strings (usable in reference, line item name, notes):
+  {{Day}}          Day name (Monday)
+  {{Date}}         Full date (09 Mar 2026)
+  {{Date+X}}       Date + X days (e.g., {{Date+7}} → 16 Mar 2026)
+  {{DateRange:X}}  Date range spanning X days (e.g., {{DateRange:7}} → 09 Mar - 15 Mar 2026)
+  {{Month}}        Month name (March)
+  {{Month+X}}      Month + X months (e.g., {{Month+1}} → April)
+  {{MonthRange:X}} Month range spanning X months
+  {{Year}}         Year (2026)
+  {{Year+X}}       Year + X years (e.g., {{Year+1}} → 2027)
+Strings are replaced with values relative to the transaction date.`);
     // ── clio schedulers list-invoices ──────────────────────────────
     cmd
         .command('list-invoices')

package/dist/core/recipe/engine.js

@@ -20,16 +20,19 @@ export async function executeRecipe(client, input) {
     validateInputs(input);
     // 2. Resolve or create capsule type
     const capsuleTypeId = await resolveCapsuleType(client, blueprint.capsuleType);
-    // 3. Create capsule
+    // 3. Create capsule (append date to avoid name collisions from repeated runs)
+    // Prefer the first step's accounting date over wall-clock UTC for audit traceability
+    const capsuleDate = blueprint.steps[0]?.date ?? new Date().toISOString().slice(0, 10);
+    const capsuleTitle = `${blueprint.capsuleName} (${capsuleDate})`;
     const capsuleRes = await createCapsule(client, {
         capsuleTypeResourceId: capsuleTypeId,
-        title: blueprint.capsuleName,
+        title: capsuleTitle,
         description: blueprint.capsuleDescription,
     });
     const capsule = {
         resourceId: capsuleRes.data.resourceId,
         type: blueprint.capsuleType,
-        title: blueprint.capsuleName,
+        title: capsuleTitle,
     };
     // 4. Determine which step to skip (attach mode)
     const attachStepIndex = findAttachStep(input);

package/dist/core/registry/tools.js

@@ -1026,7 +1026,7 @@ Steps: 1) search_customer_credit_notes with status UNAPPLIED for the same contac
     },
     {
         name: 'generate_cash_balance',
-        description: 'Generate a cash balance report showing cash position at a specific date. Use for questions about total cash, cash on hand, or cash position across all bank accounts.',
+        description: 'Generate a cash balance report showing cash position at a specific date. PREFERRED for cash position questions — use this (NOT balance sheet) when asked about total cash, cash on hand, available cash, or cash position across all bank accounts.',
         params: {
             endDate: { type: 'string', description: 'Snapshot date (YYYY-MM-DD)' },
         },
@@ -1834,7 +1834,7 @@ 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. 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.
+- journalEntries 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 journalEntries.`,
         params: {
             reference: { type: 'string', description: 'Reference number' },
@@ -1869,7 +1869,7 @@ WHEN NOT TO USE: moving money between your own bank/cash accounts — use create
     },
     {
         name: 'update_cash_in',
-        description: 'Update an existing cash-in entry (change amount, date, reference, notes, tags, or journal entries). Use when the user says "update", "change", "fix", or "adjust" a cash-in that was just created or found. Do NOT create a new entry — use this tool instead.',
+        description: 'Update an existing cash-in entry (change amount, date, reference, notes, tags, or journal entries). Use when the user says "update", "change", "fix", or "adjust" a cash-in that was just created or found. Do NOT create a new entry — use this tool instead. NOTE: cash entries created without saveAsDraft:true are ACTIVE (finalized) and cannot be updated — they must be deleted and recreated.',
         params: {
             resourceId: { type: 'string', description: 'Cash-in resourceId (parentEntityResourceId from create response)' },
             accountResourceId: { type: 'string', description: 'Bank account resourceId (required for update)' },
@@ -1900,7 +1900,7 @@ WHEN NOT TO USE: moving money between your own bank/cash accounts — use create
     },
     {
         name: 'update_cash_out',
-        description: 'Update an existing cash-out entry (change amount, date, reference, notes, tags, or journal entries). Use when the user says "update", "change", "fix", or "adjust" a cash-out that was just created or found. Do NOT create a new entry — use this tool instead.',
+        description: 'Update an existing cash-out entry (change amount, date, reference, notes, tags, or journal entries). Use when the user says "update", "change", "fix", or "adjust" a cash-out that was just created or found. Do NOT create a new entry — use this tool instead. NOTE: cash entries created without saveAsDraft:true are ACTIVE (finalized) and cannot be updated — they must be deleted and recreated.',
         params: {
             resourceId: { type: 'string', description: 'Cash-out resourceId (parentEntityResourceId from create response)' },
             accountResourceId: { type: 'string', description: 'Bank account resourceId (required for update)' },
@@ -1982,7 +1982,7 @@ WHEN NOT TO USE: receiving money from external parties (use create_cash_in) or p
     },
     {
         name: 'search_bank_records',
-        description: 'Search bank records (imported bank transactions) for a specific account. Use this to find unreconciled items, match deposits to invoices, or identify bank charges. Filter by status (UNRECONCILED/RECONCILED), date range, description, payer/payee, reference, and amount range. Call list_bank_accounts first to get the accountResourceId.',
+        description: 'Search bank records (imported bank transactions) for a specific account. Use this to find unreconciled items, match deposits to invoices, or identify bank charges. For duplicate detection, also cross-reference with search_cashflow_transactions to check if matching payments/cash entries exist. Filter by status (UNRECONCILED/RECONCILED/POSSIBLE_DUPLICATE), date range, description, payer/payee, reference, and amount range. Call list_bank_accounts first to get the accountResourceId.',
         params: {
             accountResourceId: { type: 'string', description: 'Bank account resourceId' },
             status: { type: 'string', enum: ['UNRECONCILED', 'RECONCILED', 'ARCHIVED', 'POSSIBLE_DUPLICATE'], description: 'Filter by reconciliation status' },
@@ -2402,7 +2402,8 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
 - Use schedulerEntries (NOT journalEntries) — each needs accountResourceId, amount, type (DEBIT/CREDIT), name.
 - Use repeat (NOT frequency/interval): WEEKLY, MONTHLY, QUARTERLY, YEARLY.
 - Total debits MUST equal total credits.
-- Flat structure — reference, valueDate, saveAsDraft at top level (not nested).`,
+- Flat structure — reference, valueDate, saveAsDraft at top level (not nested).
+Dynamic strings for reference/name/notes: {{Day}}, {{Date}}, {{Date+X}}, {{DateRange:X}}, {{Month}}, {{Month+X}}, {{MonthRange:X}}, {{Year}}, {{Year+X}} — replaced with values relative to the transaction date.`,
         params: {
             reference: { type: 'string', description: 'Journal reference' },
             valueDate: { type: 'string', description: 'Template date (YYYY-MM-DD)' },
@@ -2445,7 +2446,8 @@ DIFFERENT from subscriptions: no proration, but currency/tax/items can differ pe
 CRITICAL:
 - saveAsDraft MUST be false (API rejects INVALID_SALE_STATUS otherwise).
 - Use repeat (NOT frequency/interval): WEEKLY, MONTHLY, QUARTERLY, YEARLY.
-- Each lineItem needs name, unitPrice, quantity, accountResourceId.`,
+- Each lineItem needs name, unitPrice, quantity, accountResourceId.
+Dynamic strings for reference/name/notes: {{Day}}, {{Date}}, {{Date+X}}, {{DateRange:X}}, {{Month}}, {{Month+X}}, {{MonthRange:X}}, {{Year}}, {{Year+X}} — replaced with values relative to the transaction date.`,
         params: {
             startDate: { type: 'string', description: 'First occurrence (YYYY-MM-DD)' },
             endDate: { type: 'string', description: 'Last occurrence (YYYY-MM-DD, optional)' },
@@ -2494,7 +2496,8 @@ CRITICAL:
         description: `Create a scheduled (recurring) bill. CRITICAL:
 - saveAsDraft MUST be false (API rejects INVALID_PURCHASE_STATUS otherwise).
 - Use repeat (NOT frequency/interval): WEEKLY, MONTHLY, QUARTERLY, YEARLY.
-- Each lineItem needs name, unitPrice, quantity, accountResourceId.`,
+- Each lineItem needs name, unitPrice, quantity, accountResourceId.
+Dynamic strings for reference/name/notes: {{Day}}, {{Date}}, {{Date+X}}, {{DateRange:X}}, {{Month}}, {{Month+X}}, {{MonthRange:X}}, {{Year}}, {{Year+X}} — replaced with values relative to the transaction date.`,
         params: {
             startDate: { type: 'string', description: 'First occurrence (YYYY-MM-DD)' },
             endDate: { type: 'string', description: 'Last occurrence (YYYY-MM-DD, optional)' },
@@ -3083,13 +3086,15 @@ CRITICAL:
         description: `Create a bank reconciliation rule. Rules auto-match bank records to transactions during reconciliation.
 - actionType: "RECONCILE_WITH_DIRECT_CASH_ENTRY" (most common — creates cash-in/cash-out on match)
 - appliesToReconciliationAccountResourceId: the bank account this rule applies to
-- 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 }] }`,
+- configuration MUST be nested under reconcileWithDirectCashEntry key. Structure:
+  { reconcileWithDirectCashEntry: { amountAllocationType: "PERCENTAGE"|"FIXED"|"FIXED_AND_PERCENTAGE", percentageAllocation: [{ organizationAccountResourceId: "<acct-id>", amount: 100, index: 0 }], fixedAllocation: [{ organizationAccountResourceId: "<acct-id>", amount: 0.50, index: 0 }], reference: "{{bankReference}}", tags: [], taxInclusion: false, taxVatApplicable: false } }
+- For simple 100% allocation: { reconcileWithDirectCashEntry: { amountAllocationType: "PERCENTAGE", percentageAllocation: [{ organizationAccountResourceId: "<revenue-acct>", amount: 100, index: 0 }], reference: "", tags: [], taxInclusion: false, taxVatApplicable: false } }
+Dynamic strings for name/reference: {{bankReference}} (e.g., INV-03/01/2025-01), {{bankPayee}} (e.g., Fruit Planet), {{bankDescription}} (e.g., QR Payment), {{bankDate}} (e.g., 09 Mar 2026) — replaced with actual bank record values during reconciliation.`,
         params: {
-            name: { type: 'string', description: 'Rule name (e.g., "PayNow Sales", "STRIPE Payouts")' },
+            name: { type: 'string', description: 'Rule name — supports dynamic strings: {{bankReference}}, {{bankPayee}}, {{bankDescription}}, {{bankDate}}' },
             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: 'Required structure: { allocationType: "PERCENTAGE"|"FIXED", allocationDetails: [{ organizationAccountResourceId: "<account-id>", percentage: 100, taxProfileResourceId?: "<tax-id>" }] }' },
+            configuration: { type: 'object', description: 'MUST nest under reconcileWithDirectCashEntry key. Required fields: amountAllocationType, percentageAllocation (array), reference, tags, taxInclusion, taxVatApplicable. See tool description for full example.' },
         },
         required: ['name', 'actionType', 'appliesToReconciliationAccountResourceId', 'configuration'],
         group: 'bank_rules',
@@ -3098,11 +3103,11 @@ Example configuration: { "allocationType": "PERCENTAGE", "allocationDetails": [{
     },
     {
         name: 'update_bank_rule',
-        description: 'Update an existing bank reconciliation rule (conditions, actions, or name). Fetches current rule first — only send fields to change.',
+        description: 'Update an existing bank reconciliation rule (conditions, actions, or name). Fetches current rule first — only send fields to change. Dynamic strings: {{bankReference}}, {{bankPayee}}, {{bankDescription}}, {{bankDate}}.',
         params: {
             resourceId: { type: 'string', description: 'Bank rule resourceId' },
-            name: { type: 'string', description: 'New rule name' },
-            configuration: { type: 'object', description: 'Updated configuration' },
+            name: { type: 'string', description: 'New rule name — supports dynamic strings: {{bankReference}}, {{bankPayee}}, etc.' },
+            configuration: { type: 'object', description: 'Updated configuration — must nest under reconcileWithDirectCashEntry key (same structure as create)' },
         },
         required: ['resourceId'],
         group: 'bank_rules',
@@ -3317,13 +3322,15 @@ Example configuration: { "allocationType": "PERCENTAGE", "allocationDetails": [{
 DIFFERENT from scheduled invoices: subscriptions auto-prorate partial periods (credit notes for mid-period changes), but currency/tax/account are immutable after creation.
 Use for: software licenses, retainer services, recurring SaaS billing. Invoices only (no bills).
 - accountResourceId and taxProfileResourceId apply to ALL line items (same for all — immutable after creation)
-- interval: "WEEKLY", "MONTHLY", "QUARTERLY", "YEARLY"`,
+- interval: "WEEKLY", "MONTHLY", "QUARTERLY", "YEARLY"
+- reference is REQUIRED (API rejects without it)
+Dynamic strings for reference/line item name/notes: {{Day}}, {{Date}}, {{Date+X}}, {{DateRange:X}}, {{Month}}, {{Month+X}}, {{MonthRange:X}}, {{Year}}, {{Year+X}} — replaced with values relative to the transaction date (e.g., {{Month}} → "March", {{Date+7}} → "16 Mar 2026").`,
         params: {
             interval: { type: 'string', enum: ['WEEKLY', 'MONTHLY', 'QUARTERLY', 'YEARLY'], description: 'Billing interval' },
             startDate: { type: 'string', description: 'Start date (YYYY-MM-DD)' },
             endDate: { type: 'string', description: 'End date (YYYY-MM-DD, optional for ongoing)' },
             contactResourceId: { type: 'string', description: 'Customer contact resourceId' },
-            reference: { type: 'string', description: 'Invoice reference' },
+            reference: { type: 'string', description: 'Invoice reference (REQUIRED). Supports dynamic strings: {{Month}}, {{Year}}, etc.' },
             valueDate: { type: 'string', description: 'Invoice date (YYYY-MM-DD)' },
             dueDate: { type: 'string', description: 'Due date (YYYY-MM-DD)' },
             accountResourceId: { type: 'string', description: 'Revenue account resourceId (applied to ALL line items — must be same)' },
@@ -3337,7 +3344,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', 'valueDate', 'dueDate'],
+        required: ['interval', 'startDate', 'contactResourceId', 'lineItems', 'accountResourceId', 'valueDate', 'dueDate', 'reference'],
         group: 'subscriptions',
         readOnly: false,
         execute: async (ctx, input) => {
@@ -3353,7 +3360,7 @@ Use for: software licenses, retainer services, recurring SaaS billing. Invoices
                 repeat: interval, startDate, status: 'ACTIVE',
                 proratedConfig: { proratedAdjustmentLineText: 'Prorated adjustment' },
                 invoice: {
-                    contactResourceId, reference, valueDate, dueDate,
+                    contactResourceId, reference: reference || `SUB-${Date.now()}`, valueDate, dueDate,
                     lineItems: items, saveAsDraft: false,
                 },
             };
@@ -3382,7 +3389,7 @@ Use for: software licenses, retainer services, recurring SaaS billing. Invoices
     deleteTool('delete_subscription', 'Delete a subscription. Removes the recurring schedule.', 'subscriptions', (client, id) => deleteSubscription(client, id)),
     {
         name: 'cancel_subscription',
-        description: 'Cancel an active subscription. Prorates remaining period and stops future billing. Must cancel before delete.',
+        description: 'Cancel an active subscription. Prorates remaining period and stops future billing. Safe to call — subscriptions can be reactivated after cancellation. Always use this tool when the user asks to cancel a subscription. Must cancel before delete.',
         params: {
             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)' },
@@ -3473,7 +3480,7 @@ Use for: software licenses, retainer services, recurring SaaS billing. Invoices
     },
     {
         name: 'generate_bank_recon_summary',
-        description: 'Generate bank reconciliation summary for a specific bank account. 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 — always include this in month-end checklists. 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)' },
@@ -3991,11 +3998,15 @@ Returns per-contact result: created, skipped (duplicate), or failed.`,
     // ══════════════════════════════════════════════════════════════
     {
         name: 'quick_fix_transactions',
-        description: 'Bulk-update multiple transactions of the same type in one call. Pass resourceIds + attributes — only present fields are changed. 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, capsuleResourceId. Entity-specific: dueDate (invoices/bills/CNs), invoiceNotes, templateResourceId, currencySettings, taxCurrencySettings, customFields. NOTE: valueDate (and dueDate for invoices/bills) must currently be included even if unchanged.',
+        description: `Bulk-update multiple transactions of the same type in one call. Pass resourceIds + attributes object — only present fields are changed.
+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".
+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' },
             resourceIds: { type: 'array', items: { type: 'string' }, description: 'Array of transaction resourceIds to update' },
-            attributes: { type: 'object', description: 'Fields to update — only present fields are changed. Common: valueDate, contactResourceId, tags, capsuleResourceId. Invoices/bills: dueDate, currencySettings, taxCurrencySettings, customFields. Invoices/CNs: invoiceNotes, templateResourceId, billFrom, billTo. Schedulers: endDate, interval.' },
+            attributes: { type: 'object', description: 'Fields to update (REQUIRED — must be an object). Common: valueDate, contactResourceId, tags (string array, e.g. ["Q1"]), capsuleResourceId. ARAP: dueDate, currencySettings, taxCurrencySettings, customFields. Invoices/CNs: invoiceNotes, templateResourceId, billFrom, billTo. Schedulers: endDate, interval. IMPORTANT: always include valueDate (and dueDate for ARAP) even if unchanged.' },
         },
         required: ['entity', 'resourceIds', 'attributes'],
         group: 'quick_fix',
@@ -4007,7 +4018,12 @@ Returns per-contact result: created, skipped (duplicate), or failed.`,
     },
     {
         name: 'quick_fix_line_items',
-        description: 'Bulk-update line items across multiple transactions. 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.',
+        description: `Bulk-update line items across multiple transactions. Use this to reclassify accounts, change tax profiles, or update line item details in bulk.
+Works for ALL entity types including cash-in and cash-out entries — use for bulk account reclassification on cash entry line items.
+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.`,
         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.30.16",
+  "version": "4.30.18",
   "description": "Clio — Command Line Interface Orchestrator for Jaz AI.",
   "type": "module",
   "bin": {