jaz-clio 4.30.0 → 4.30.2

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 4.30.0
+version: 4.30.2
 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.0
+version: 4.30.2
 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.0
+version: 4.30.2
 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.0
+version: 4.30.2
 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/accounts.js

@@ -1,6 +1,6 @@
 import chalk from 'chalk';
 import { listAccounts, searchAccounts, createAccount, deleteAccount } from '../core/api/chart-of-accounts.js';
-import { findExistingAccount } from '../core/api/guards.js';
+import { findExistingAccount, normalizeAccountType } from '../core/api/guards.js';
 import { apiAction } from './api-action.js';
 import { outputList } from './output.js';
 import { parsePositiveInt, parseNonNegativeInt, readBodyInput, requireFields } from './parsers.js';
@@ -93,7 +93,7 @@ export function registerAccountsCommand(program) {
             const data = {
                 code: opts.code,
                 name: opts.name,
-                accountType: opts.type,
+                accountType: normalizeAccountType(opts.type),
             };
             if (opts.currency)
                 data.currencyCode = opts.currency;

package/dist/core/api/chart-of-accounts.js

@@ -4,6 +4,9 @@ export async function listAccounts(client, params) {
 export async function searchAccounts(client, params) {
     return client.search('/api/v1/chart-of-accounts/search', params);
 }
+export async function getAccount(client, resourceId) {
+    return client.get(`/api/v1/chart-of-accounts/${resourceId}`);
+}
 export async function createAccount(client, data) {
     return client.post('/api/v1/chart-of-accounts', data);
 }

package/dist/core/api/client.js

@@ -1,7 +1,9 @@
 const DEFAULT_BASE_URL = 'https://api.getjaz.com';
 const DEFAULT_TIMEOUT = 30_000;
 const MAX_RETRIES = 3;
-const RETRY_STATUS_CODES = [429, 503];
+/** Status codes safe to retry. 500/502/503 only retried on idempotent methods (GET/HEAD). */
+const ALWAYS_RETRY = [429];
+const IDEMPOTENT_RETRY = [500, 502, 503];
 export class JazApiError extends Error {
     status;
     body;
@@ -72,7 +74,10 @@ export class JazClient {
             const attemptStart = Date.now();
             try {
                 const response = await fetch(url.toString(), fetchOptions);
-                if (RETRY_STATUS_CODES.includes(response.status) && attempt < this.maxRetries) {
+                const isIdempotent = ['GET', 'HEAD'].includes(method);
+                const shouldRetry = ALWAYS_RETRY.includes(response.status)
+                    || (isIdempotent && IDEMPOTENT_RETRY.includes(response.status));
+                if (shouldRetry && attempt < this.maxRetries) {
                     this.onRequest?.({
                         method, path, statusCode: response.status,
                         durationMs: Date.now() - attemptStart, attempt, retried: true,

package/dist/core/api/guards.js

@@ -1,6 +1,7 @@
 import { searchContacts } from './contacts.js';
 import { searchItems } from './items.js';
 import { searchAccounts } from './chart-of-accounts.js';
+import { searchCapsules } from './capsules.js';
 /** Find existing contact by name. Returns first match or undefined. */
 export async function findExistingContact(client, name) {
     if (!name)
@@ -15,6 +16,38 @@ export async function findExistingItem(client, itemCode) {
     const result = await searchItems(client, { filter: { itemCode: { eq: itemCode } }, limit: 1 });
     return result.totalElements > 0 ? result.data[0] : undefined;
 }
+// ── Account type normalization ───────────────────────────────────
+/** Normalize common accountType variations to exact API values.
+ *  Pure map lookup — no network calls, no perf impact. */
+const ACCOUNT_TYPE_MAP = {
+    'current assets': 'Current Asset', 'current asset': 'Current Asset',
+    'fixed assets': 'Fixed Asset', 'fixed asset': 'Fixed Asset',
+    'bank account': 'Bank Accounts', 'bank accounts': 'Bank Accounts', 'bank': 'Bank Accounts',
+    'current liabilities': 'Current Liability', 'current liability': 'Current Liability',
+    'non-current liabilities': 'Non-current Liability', 'non-current liability': 'Non-current Liability',
+    'equity': 'Shareholders Equity', 'shareholders equity': 'Shareholders Equity',
+    "shareholders' equity": 'Shareholders Equity', "shareholder's equity": 'Shareholders Equity',
+    'revenue': 'Operating Revenue', 'operating revenue': 'Operating Revenue',
+    'other revenue': 'Other Revenue', 'other income': 'Other Revenue',
+    'expense': 'Operating Expense', 'operating expense': 'Operating Expense', 'expenses': 'Operating Expense',
+    'direct costs': 'Direct Costs', 'cost of goods sold': 'Direct Costs', 'cogs': 'Direct Costs',
+    'cash': 'Cash', 'inventory': 'Inventory',
+};
+export function normalizeAccountType(raw) {
+    if (typeof raw !== 'string')
+        return String(raw ?? '');
+    const trimmed = raw.trim();
+    return ACCOUNT_TYPE_MAP[trimmed.toLowerCase()] ?? trimmed;
+}
+// ── Duplicate detection ─────────────────────────────────────────
+/** Find existing capsule by title. Normalizes whitespace/case for comparison. */
+export async function findExistingCapsule(client, title) {
+    if (!title?.trim())
+        return undefined;
+    const normalized = title.trim().toLowerCase();
+    const result = await searchCapsules(client, { filter: { title: { contains: title.trim() } }, limit: 20 });
+    return result.data.find(c => c.title?.trim().toLowerCase() === normalized);
+}
 /** Find existing account by name. Returns first match or undefined. */
 export async function findExistingAccount(client, name) {
     if (!name)

package/dist/core/registry/namespaces.js

@@ -1,47 +1,145 @@
 export const TOOL_NAMESPACES = [
+    // ── Transactions ────────────────────────────────────────────
     {
-        name: 'sales',
-        description: 'Sales invoices (INV/SI), customer credit notes, scheduled invoices. Create, search, update, delete, pay, finalize, apply credits, download PDF. Also: receivables, AR, billing, overdue invoices.',
-        groups: ['invoices', 'customer_credit_notes'],
+        name: 'invoices',
+        description: 'Sales invoices (INV/SI). Create, search, get, update, delete, pay, finalize, apply credits, download PDF. Also: receivables, AR, billing, overdue invoices.',
+        groups: ['invoices'],
     },
     {
-        name: 'purchases',
-        description: 'Purchase bills (PO/PI), supplier credit notes, scheduled bills. Create, search, update, delete, pay, finalize, apply credits. Also: payables, AP, vendor, supplier, overdue bills.',
-        groups: ['bills', 'supplier_credit_notes'],
+        name: 'customer_credit_notes',
+        description: 'Customer credit notes (CN). Create, search, update, delete, finalize, refund, download PDF. Also: sales returns, customer CN.',
+        groups: ['customer_credit_notes'],
     },
     {
-        name: 'journals_and_cash',
-        description: 'Journal entries (JE), cash-in receipts, cash-out disbursements, cash transfers, petty cash, scheduled journals. Create, search, update, delete.',
-        groups: ['journals', 'cash_entries', 'cash_transfers', 'schedulers'],
+        name: 'bills',
+        description: 'Purchase bills (PO/PI). Create, search, get, update, delete, pay, finalize, apply credits. Also: payables, AP, vendor invoices, supplier bills.',
+        groups: ['bills'],
     },
     {
-        name: 'banking',
-        description: 'Bank accounts, bank statement imports, bank records, bank reconciliation rules, auto-reconciliation, unreconciled transactions.',
-        groups: ['bank', 'bank_rules'],
+        name: 'supplier_credit_notes',
+        description: 'Supplier credit notes. Create, search, update, delete, finalize, refund. Also: purchase returns, debit notes, supplier CN.',
+        groups: ['supplier_credit_notes'],
     },
     {
-        name: 'reports',
-        description: 'Financial reports: trial balance (TB), balance sheet (BS/B/S), profit & loss (PnL/P&L/PL/income statement), cash flow, aged receivables (AR), aged payables (AP), cash balance/position, general ledger (GL), VAT ledger, equity movement, bank balance, fixed asset reports. Data exports (CSV/Excel). Also: how profitable, how much owed, overdue.',
-        groups: ['reports', 'exports'],
+        name: 'journals',
+        description: 'Journal entries (JE). Create, search, update, delete manual journals. Also: adjusting entries, accruals, reclassifications, corrections.',
+        groups: ['journals'],
     },
     {
-        name: 'contacts_and_items',
-        description: 'Contacts (customers/suppliers/vendors), items (products/services/inventory), tags, contact groups, custom fields.',
-        groups: ['contacts', 'items', 'tags', 'contact_groups', 'custom_fields', 'inventory'],
+        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'],
     },
+    // ── Banking ─────────────────────────────────────────────────
     {
-        name: 'accounting_setup',
-        description: 'Chart of accounts (COA), currencies, exchange rates (FX/forex), tax profiles, withholding tax (WHT) codes, bookmarks.',
-        groups: ['accounts', 'currencies', 'tax_profiles', 'bookmarks'],
+        name: 'bank_accounts',
+        description: 'Bank accounts, bank statement imports (CSV/OFX), bank records search, auto-reconciliation. For unreconciled queries: ALWAYS search bank records with status UNRECONCILED after listing accounts. Also: bank feeds, bank balance.',
+        groups: ['bank'],
     },
+    {
+        name: 'bank_rules',
+        description: 'Bank reconciliation rules (action shortcuts). Create, search, update, delete bank rules. Configure auto-matching rules for bank records.',
+        groups: ['bank_rules'],
+    },
+    // ── Reports ─────────────────────────────────────────────────
+    {
+        name: 'financial_reports',
+        description: 'Core financial statements: trial balance (TB), balance sheet (BS/B/S), profit & loss (PnL/P&L/income statement), cash flow, general ledger (GL), cash balance/position, equity movement, VAT/GST ledger. Also: how profitable, what is the balance.',
+        groups: ['financial_reports'],
+    },
+    {
+        name: 'operational_reports',
+        description: 'Aging and operational reports: aged receivables (AR aging), aged payables (AP aging), AR report, bank balance summary, bank reconciliation reports, fixed asset (FA) summary, FA reconciliation. Data exports (CSV/Excel). Also: overdue analysis, how much owed.',
+        groups: ['operational_reports', 'exports'],
+    },
+    // ── Master Data ─────────────────────────────────────────────
+    {
+        name: 'contacts',
+        description: 'Contacts (customers/suppliers/vendors), contact groups. Create, search, get, update, delete, bulk create contacts. List/create contact groups.',
+        groups: ['contacts', 'contact_groups'],
+    },
+    {
+        name: 'items_and_inventory',
+        description: 'Products, services, inventory items. Create, search, get, update, delete items. Check inventory balance. Also: SKU, catalog, stock.',
+        groups: ['items', 'inventory'],
+    },
+    {
+        name: 'tags_and_custom_fields',
+        description: 'Tags for categorizing transactions. Custom fields for adding metadata (text, date, dropdown). Create, search, delete tags and custom fields.',
+        groups: ['tags', 'custom_fields'],
+    },
+    // ── Accounting Setup ────────────────────────────────────────
+    {
+        name: 'chart_of_accounts',
+        description: 'Chart of accounts (COA/GL accounts). Create, search, update accounts. Bookmarks (favorites/shortcuts). Also: ledger codes, account types.',
+        groups: ['accounts', 'bookmarks'],
+    },
+    {
+        name: 'currencies',
+        description: 'Currencies, exchange rates (FX/forex). List/add org currencies. Set, update, import currency rates. Also: multi-currency, FX rates.',
+        groups: ['currencies'],
+    },
+    {
+        name: 'tax_profiles',
+        description: 'Tax profiles (GST/VAT/sales tax), withholding tax codes (WHT/ATC). Search, create, update tax profiles. List WHT codes.',
+        groups: ['tax_profiles'],
+    },
+    // ── Capsules & Recipes ──────────────────────────────────────
     {
         name: 'capsules_and_recipes',
-        description: 'Capsules (transaction groupings), recurring/scheduled transactions, subscriptions, and financial recipes: amortization, depreciation, deferred revenue, loan schedules, IFRS 16 leases, hire purchase, fixed deposits, FX revaluation, ECL provisioning, IAS 37 provisions, dividends, leave accrual, asset disposal.',
-        groups: ['capsules', 'recipes', 'subscriptions'],
+        description: 'Capsules (transaction groupings/capsule types). Financial recipes: amortization, depreciation, deferred revenue, IFRS 16 leases, hire purchase, fixed deposits, FX revaluation, loan schedules, ECL/expected credit loss, IAS 37 provisions, asset disposal. Plan and execute recipes. Keywords: calculate, provision, schedule, expected credit loss, revaluation.',
+        groups: ['capsules', 'recipes'],
+    },
+    // ── Scheduling ──────────────────────────────────────────────
+    {
+        name: 'scheduled_transactions',
+        description: 'Scheduled/recurring invoices, bills, journals. Create scheduled invoices/bills/journals, search scheduled transactions. Also: recurring, auto-generate.',
+        groups: ['schedulers'],
+    },
+    {
+        name: 'subscriptions',
+        description: 'Subscriptions (recurring billing/payment plans). Create, update, cancel, search subscriptions. Also: recurring charges, subscription schedules.',
+        groups: ['subscriptions'],
+    },
+    // ── Organization ────────────────────────────────────────────
+    {
+        name: 'organization',
+        description: 'Organization info (name, currency, country, fiscal year). User management: invite, update, remove, search org users. Bulk invite.',
+        groups: ['organization', 'org_users'],
+    },
+    // ── Documents & AI ──────────────────────────────────────────
+    {
+        name: 'document_ai',
+        description: 'File attachments, AI document extraction (magic/OCR). Upload/list attachments. Create transactions from PDFs/images (invoice scanning, bill extraction). Track extraction workflows.',
+        groups: ['attachments', 'magic'],
+    },
+    // ── Fixed Assets ────────────────────────────────────────────
+    {
+        name: 'fixed_assets',
+        description: 'Fixed assets (PP&E/property, plant, equipment). Search, create, update, discard, sell, transfer, undo disposal. Also: depreciation, asset register.',
+        groups: ['fixed_assets'],
+    },
+    // ── Payments & Search ───────────────────────────────────────
+    {
+        name: 'payments_and_search',
+        description: 'Payments search/list across all transaction types. Cashflow transaction ledger. Universal cross-entity search. Transaction summary (fetch any transaction + attachments + payment history in one call).',
+        groups: ['payments', 'cashflow', 'search'],
+    },
+    // ── Drafts ──────────────────────────────────────────────────
+    {
+        name: 'drafts',
+        description: 'Draft validation for invoices, bills, journals, credit notes. Bulk finalize multiple drafts at once. Check if drafts are ready to finalize.',
+        groups: ['drafts'],
+    },
+    // ── Job Blueprints ──────────────────────────────────────────
+    {
+        name: 'close_procedures',
+        description: 'Period-end close checklists: month-end, quarter-end, year-end close. Bank reconciliation job. GST/VAT filing job. Audit preparation. Returns structured blueprints.',
+        groups: ['close_jobs'],
     },
     {
-        name: 'operations',
-        description: 'Organization info, user management (invite/remove users), file attachments/uploads, payments search, cashflow ledger, fixed assets (list/create/dispose/sell), AI extraction from documents (magic/OCR), universal search, accounting jobs and drafts.',
-        groups: ['organization', 'org_users', 'attachments', 'payments', 'cashflow', 'magic', 'fixed_assets', 'search', 'jobs', 'drafts'],
+        name: 'operational_jobs',
+        description: 'Operational job checklists: payment runs, credit control/collections, supplier reconciliation, fixed asset review, document collection, statutory filing. Returns structured blueprints.',
+        groups: ['operational_jobs'],
     },
 ];

package/dist/core/registry/tools.js

@@ -1,6 +1,6 @@
-import { findExistingContact, findExistingItem, findExistingAccount } from '../api/guards.js';
+import { findExistingContact, findExistingItem, findExistingAccount, findExistingCapsule, normalizeAccountType } from '../api/guards.js';
 import { getOrganization } from '../api/organization.js';
-import { listAccounts, searchAccounts, createAccount, updateAccount, deleteAccount, } from '../api/chart-of-accounts.js';
+import { listAccounts, searchAccounts, getAccount, createAccount, updateAccount, deleteAccount, } from '../api/chart-of-accounts.js';
 import { listContacts, searchContacts, getContact, createContact, updateContact, deleteContact, } from '../api/contacts.js';
 import { listInvoices, searchInvoices, getInvoice, createInvoice, updateInvoice, deleteInvoice, createInvoicePayment, createScheduledInvoice, finalizeInvoice, applyCreditsToInvoice, downloadInvoicePdf, } from '../api/invoices.js';
 import { listBills, searchBills, getBill, createBill, updateBill, deleteBill, createBillPayment, createScheduledBill, finalizeBill, applyCreditsToBill, } from '../api/bills.js';
@@ -61,8 +61,7 @@ const PAGINATION_PARAMS = {
 };
 const SEARCH_PARAMS = {
     ...PAGINATION_PARAMS,
-    sortBy: { type: 'string', description: 'Sort field (always sent with queries). Common: valueDate, reference, status, name. Default: valueDate' },
-    order: { type: 'string', enum: ['ASC', 'DESC'], description: 'Sort direction' },
+    // sortBy/order removed — hardcoded per-tool to prevent LLM sending invalid sort fields
 };
 const CURRENCY_PARAM = {
     type: 'object',
@@ -124,10 +123,8 @@ const LINE_ITEM_PARAM = {
 function extractPaginationInput(input) {
     const limit = input.limit;
     const offset = input.offset;
-    const sortBy = input.sortBy;
-    const rawOrder = input.order;
-    const sortOrder = rawOrder === 'ASC' || rawOrder === 'DESC' ? rawOrder : undefined;
-    return { limit, offset, sortBy, sortOrder };
+    // sortBy/order not exposed to LLM — each search tool uses its own hardcoded default
+    return { limit, offset, sortBy: undefined, sortOrder: undefined };
 }
 // ── List tool factory (DRY — all 10 list tools share this) ───────
 function listTool(name, description, group, fetcher) {
@@ -171,14 +168,137 @@ function deleteTool(name, description, group, deleter) {
         },
     };
 }
-/** Fetch lineItems from an existing transaction (API requires them on finalize PUT). */
-async function fetchLineItems(client, type, resourceId) {
+/**
+ * Writable fields per entity type (allowlist — only these go to PUT).
+ * Derived from the finalize/update function signatures in src/core/api/.
+ */
+const WRITABLE_FIELDS = {
+    invoice: new Set([
+        'reference', 'valueDate', 'dueDate', 'contactResourceId',
+        'lineItems', 'notes', 'invoiceNotes', 'internalNotes', 'tag', 'tags',
+        'isTaxVatApplicable', 'isTaxVATApplicable', 'taxInclusion',
+        'terms', 'currency', 'customFields', 'capsuleResourceId',
+        'taxProfileResourceId', 'customerPaymentProfileResourceId',
+    ]),
+    bill: new Set([
+        'reference', 'valueDate', 'dueDate', 'contactResourceId',
+        'lineItems', 'notes', 'internalNotes', 'tag', 'tags',
+        'isTaxVatApplicable', 'isTaxVATApplicable', 'taxInclusion',
+        'terms', 'currency', 'customFields', 'capsuleResourceId',
+        'taxProfileResourceId',
+    ]),
+    customer_credit_note: new Set([
+        'reference', 'valueDate', 'contactResourceId',
+        'lineItems', 'notes', 'tag', 'tags',
+        'isTaxVatApplicable', 'isTaxVATApplicable', 'taxInclusion',
+        'currency', 'customFields', 'capsuleResourceId',
+        'taxProfileResourceId',
+    ]),
+    supplier_credit_note: new Set([
+        'reference', 'valueDate', 'contactResourceId',
+        'lineItems', 'notes', 'tag', 'tags',
+        'isTaxVatApplicable', 'isTaxVATApplicable', 'taxInclusion',
+        'currency', 'customFields', 'capsuleResourceId',
+        'taxProfileResourceId',
+    ]),
+};
+/** Normalize a date string to YYYY-MM-DD (strip time component). */
+function toDateOnly(v) {
+    if (typeof v !== 'string')
+        return v;
+    if (/^\d{4}-\d{2}-\d{2}$/.test(v))
+        return v;
+    const m = /^(\d{4}-\d{2}-\d{2})T/.exec(v);
+    return m ? m[1] : v;
+}
+/** Writable line item fields for PUT (allowlist). */
+const WRITABLE_LI_FIELDS = new Set([
+    'name', 'quantity', 'unitPrice', 'unit', 'accountResourceId',
+    'taxProfileResourceId', 'description', 'classifierConfig',
+    'itemResourceId', 'discount',
+]);
+/** Normalize GET line items to PUT format (field name asymmetries + allowlist). */
+function normalizeLineItems(items) {
+    if (!Array.isArray(items))
+        return items;
+    return items.map((li) => {
+        const out = {};
+        for (const [k, v] of Object.entries(li)) {
+            if (v === null || v === undefined)
+                continue;
+            // GET returns organizationAccountResourceId, PUT wants accountResourceId
+            if (k === 'organizationAccountResourceId') {
+                out.accountResourceId = v;
+            }
+            else if (k === 'taxProfile' && typeof v === 'object' && v !== null) {
+                const rid = v.resourceId;
+                if (rid)
+                    out.taxProfileResourceId = rid;
+            }
+            else if (k === 'discount' && typeof v === 'object' && v !== null) {
+                // Only include discount if it has a non-zero value (zero defaults cause 400)
+                const rv = v.rateValue;
+                if (rv && Number(rv) !== 0)
+                    out.discount = v;
+            }
+            else if (WRITABLE_LI_FIELDS.has(k)) {
+                out[k] = v;
+            }
+        }
+        return out;
+    });
+}
+/**
+ * Fetch full entity, pick only writable fields, normalize GET→PUT asymmetries,
+ * then merge LLM overrides on top. Bulletproof for finalize/update PUTs.
+ */
+async function fetchAndMerge(client, type, resourceId, overrides) {
     const fetcher = type === 'invoice' ? getInvoice
         : type === 'bill' ? getBill
             : type === 'customer_credit_note' ? getCustomerCreditNote
                 : getSupplierCreditNote;
     const result = await fetcher(client, resourceId);
-    return result.data.lineItems ?? [];
+    const existing = result.data;
+    const allowed = WRITABLE_FIELDS[type];
+    // Pick only writable fields from existing entity
+    const base = {};
+    for (const [k, v] of Object.entries(existing)) {
+        if (allowed.has(k) && v !== null && v !== undefined)
+            base[k] = v;
+    }
+    // Normalize dates to YYYY-MM-DD (GET returns ISO datetime)
+    if (base.valueDate)
+        base.valueDate = toDateOnly(base.valueDate);
+    if (base.dueDate)
+        base.dueDate = toDateOnly(base.dueDate);
+    // Normalize line items (field name asymmetries)
+    if (base.lineItems)
+        base.lineItems = normalizeLineItems(base.lineItems);
+    // Overrides win (LLM may supply updated lineItems, notes, etc.)
+    for (const [k, v] of Object.entries(overrides)) {
+        if (v !== undefined)
+            base[k] = v;
+    }
+    // Auto-resolve missing accountResourceId for finalize (exact name match, auditable)
+    const items = base.lineItems;
+    if (items?.length) {
+        const missing = items.filter(li => !li.accountResourceId);
+        if (missing.length > 0) {
+            const defaultName = type === 'invoice' || type === 'customer_credit_note'
+                ? 'Operating Revenue' : 'Operating Expense';
+            const acctResult = await searchAccounts(client, { filter: { name: { eq: defaultName } }, limit: 1 });
+            const defaultAcct = acctResult.data?.[0];
+            if (defaultAcct?.resourceId) {
+                for (const li of missing)
+                    li.accountResourceId = defaultAcct.resourceId;
+            }
+            const stillMissing = items.filter(li => !li.accountResourceId);
+            if (stillMissing.length > 0) {
+                throw new Error(`Cannot finalize: ${stillMissing.length} line item(s) missing accountResourceId and no default account found.`);
+            }
+        }
+    }
+    return base;
 }
 // ── Tool Definitions ─────────────────────────────────────────────
 export const TOOL_DEFINITIONS = [
@@ -233,22 +353,7 @@ export const TOOL_DEFINITIONS = [
             if (existingAcct) {
                 return { _guard: 'duplicate_skipped', message: `Account "${acctName}" already exists.`, existing: existingAcct };
             }
-            // Normalize common LLM variations to exact API values
-            const typeMap = {
-                'current assets': 'Current Asset', 'current asset': 'Current Asset',
-                'fixed assets': 'Fixed Asset', 'fixed asset': 'Fixed Asset',
-                'bank account': 'Bank Accounts', 'bank accounts': 'Bank Accounts', 'bank': 'Bank Accounts',
-                'current liabilities': 'Current Liability', 'current liability': 'Current Liability',
-                'non-current liabilities': 'Non-current Liability', 'non-current liability': 'Non-current Liability',
-                'equity': 'Shareholders Equity', 'shareholders equity': 'Shareholders Equity', "shareholders' equity": 'Shareholders Equity', "shareholder's equity": 'Shareholders Equity',
-                'revenue': 'Operating Revenue', 'operating revenue': 'Operating Revenue',
-                'other revenue': 'Other Revenue', 'other income': 'Other Revenue',
-                'expense': 'Operating Expense', 'operating expense': 'Operating Expense', 'expenses': 'Operating Expense',
-                'direct costs': 'Direct Costs', 'cost of goods sold': 'Direct Costs', 'cogs': 'Direct Costs',
-                'cash': 'Cash', 'inventory': 'Inventory',
-            };
-            const rawType = input.accountType;
-            const accountType = typeMap[rawType.toLowerCase()] ?? rawType;
+            const accountType = normalizeAccountType(input.accountType);
             return createAccount(ctx.client, {
                 code: input.code,
                 name: acctName,
@@ -268,10 +373,22 @@ export const TOOL_DEFINITIONS = [
         required: ['resourceId'],
         group: 'accounts',
         readOnly: false,
-        execute: async (ctx, input) => updateAccount(ctx.client, input.resourceId, {
-            name: input.name,
-            code: input.code,
-        }),
+        execute: async (ctx, input) => {
+            // Fetch existing account — only keep writable fields (not server-managed ones)
+            const rid = input.resourceId;
+            const existing = (await getAccount(ctx.client, rid)).data;
+            const ACCOUNT_WRITABLE = ['name', 'code', 'classificationType', 'taxProfileResourceId', 'currency', 'description'];
+            const merged = Object.fromEntries(ACCOUNT_WRITABLE.filter(k => existing[k] !== undefined && existing[k] !== null).map(k => [k, existing[k]]));
+            // GET→PUT asymmetry: GET returns accountType, PUT requires classificationType (Rule 21)
+            if (!merged.classificationType && existing.accountType) {
+                merged.classificationType = existing.accountType;
+            }
+            if (input.name !== undefined)
+                merged.name = input.name;
+            if (input.code !== undefined)
+                merged.code = input.code;
+            return updateAccount(ctx.client, rid, merged);
+        },
     },
     // ── Contacts ───────────────────────────────────────────────────
     listTool('list_contacts', 'List contacts (customers/suppliers). Returns billingName, name, emails, status. Paginated — response includes totalElements. Use limit/offset to page.', 'contacts', (client, off, lim) => listContacts(client, { limit: lim, offset: off })),
@@ -404,6 +521,7 @@ export const TOOL_DEFINITIONS = [
         description: `Create a new invoice. IMPORTANT:
 - Line items use "name" (not "description") for the item label.
 - saveAsDraft defaults to true. Set to false only if user says "finalize".
+- accountResourceId is REQUIRED on each lineItem for finalized invoices. Search accounts first (e.g. Operating Revenue).
 - Currency format: { sourceCurrency: "USD", exchangeRate: 1.35 }
 - contactResourceId is required — search contacts first to get the ID.
 - Dates must be YYYY-MM-DD format.`,
@@ -496,7 +614,7 @@ export const TOOL_DEFINITIONS = [
     },
     {
         name: 'finalize_invoice',
-        description: 'Finalize a draft invoice (set saveAsDraft=false). Can optionally update fields in the same call.',
+        description: 'Finalize a draft invoice (set saveAsDraft=false). Can optionally update fields in the same call. IMPORTANT: Every lineItem MUST have accountResourceId. If the draft was created without it, pass lineItems with accountResourceId added (search accounts first, e.g. Operating Revenue for sales).',
         params: {
             resourceId: { type: 'string', description: 'Invoice resourceId' },
             reference: { type: 'string' },
@@ -509,10 +627,9 @@ export const TOOL_DEFINITIONS = [
         group: 'invoices',
         readOnly: false,
         execute: async (ctx, input) => {
-            const { resourceId: rid, ...data } = input;
-            if (!data.lineItems)
-                data.lineItems = await fetchLineItems(ctx.client, 'invoice', rid);
-            return finalizeInvoice(ctx.client, rid, data);
+            const { resourceId: rid, ...overrides } = input;
+            const merged = await fetchAndMerge(ctx.client, 'invoice', rid, overrides);
+            return finalizeInvoice(ctx.client, rid, merged);
         },
     },
     {
@@ -594,7 +711,7 @@ export const TOOL_DEFINITIONS = [
     },
     {
         name: 'create_bill',
-        description: 'Create a new bill. Same rules as create_invoice (name not description, saveAsDraft default).',
+        description: 'Create a new bill. Same rules as create_invoice: name not description, saveAsDraft defaults true, accountResourceId REQUIRED on lineItems for finalized bills (search accounts first, e.g. Operating Expense).',
         params: {
             reference: { type: 'string' },
             valueDate: { type: 'string' },
@@ -680,7 +797,7 @@ export const TOOL_DEFINITIONS = [
     },
     {
         name: 'finalize_bill',
-        description: 'Finalize a draft bill (set saveAsDraft=false). Can optionally update fields in the same call.',
+        description: 'Finalize a draft bill (set saveAsDraft=false). Can optionally update fields in the same call. IMPORTANT: Every lineItem MUST have accountResourceId. If the draft was created without it, pass lineItems with accountResourceId added (search accounts first, e.g. Operating Expense for purchases).',
         params: {
             resourceId: { type: 'string', description: 'Bill resourceId' },
             reference: { type: 'string' },
@@ -693,10 +810,9 @@ export const TOOL_DEFINITIONS = [
         group: 'bills',
         readOnly: false,
         execute: async (ctx, input) => {
-            const { resourceId: rid, ...data } = input;
-            if (!data.lineItems)
-                data.lineItems = await fetchLineItems(ctx.client, 'bill', rid);
-            return finalizeBill(ctx.client, rid, data);
+            const { resourceId: rid, ...overrides } = input;
+            const merged = await fetchAndMerge(ctx.client, 'bill', rid, overrides);
+            return finalizeBill(ctx.client, rid, merged);
         },
     },
     {
@@ -792,7 +908,7 @@ export const TOOL_DEFINITIONS = [
         readOnly: false,
         execute: async (ctx, input) => deleteJournal(ctx.client, input.resourceId),
     },
-    // ── Reports ────────────────────────────────────────────────────
+    // ── Financial Reports (core statements) ──────────────────────
     {
         name: 'generate_trial_balance',
         description: 'Generate a trial balance report.',
@@ -801,7 +917,7 @@ export const TOOL_DEFINITIONS = [
             currencyCode: { type: 'string', description: 'Currency override' },
         },
         required: ['endDate'],
-        group: 'reports',
+        group: 'financial_reports',
         readOnly: true,
         execute: async (ctx, input) => generateTrialBalance(ctx.client, input),
     },
@@ -813,7 +929,7 @@ export const TOOL_DEFINITIONS = [
             currencyCode: { type: 'string' },
         },
         required: [],
-        group: 'reports',
+        group: 'financial_reports',
         readOnly: true,
         execute: async (ctx, input) => {
             const date = input.snapshotDate ?? new Date().toISOString().slice(0, 10);
@@ -829,7 +945,7 @@ export const TOOL_DEFINITIONS = [
             currencyCode: { type: 'string' },
         },
         required: ['startDate', 'endDate'],
-        group: 'reports',
+        group: 'financial_reports',
         readOnly: true,
         execute: async (ctx, input) => generateProfitAndLoss(ctx.client, input),
     },
@@ -841,7 +957,7 @@ export const TOOL_DEFINITIONS = [
             endDate: { type: 'string' },
         },
         required: ['startDate', 'endDate'],
-        group: 'reports',
+        group: 'financial_reports',
         readOnly: true,
         execute: async (ctx, input) => generateCashflow(ctx.client, input),
     },
@@ -852,7 +968,7 @@ export const TOOL_DEFINITIONS = [
             endDate: { type: 'string' },
         },
         required: ['endDate'],
-        group: 'reports',
+        group: 'operational_reports',
         readOnly: true,
         execute: async (ctx, input) => generateArSummary(ctx.client, input),
     },
@@ -863,7 +979,7 @@ export const TOOL_DEFINITIONS = [
             endDate: { type: 'string' },
         },
         required: ['endDate'],
-        group: 'reports',
+        group: 'operational_reports',
         readOnly: true,
         execute: async (ctx, input) => generateApSummary(ctx.client, input),
     },
@@ -874,7 +990,7 @@ export const TOOL_DEFINITIONS = [
             endDate: { type: 'string', description: 'Snapshot date (YYYY-MM-DD)' },
         },
         required: ['endDate'],
-        group: 'reports',
+        group: 'financial_reports',
         readOnly: true,
         execute: async (ctx, input) => generateCashBalance(ctx.client, input),
     },
@@ -887,7 +1003,7 @@ export const TOOL_DEFINITIONS = [
             groupBy: { type: 'string', description: 'Group by: ACCOUNT (default), TRANSACTION, or CAPSULE' },
         },
         required: ['startDate', 'endDate'],
-        group: 'reports',
+        group: 'financial_reports',
         readOnly: true,
         execute: async (ctx, input) => {
             const i = input;
@@ -1108,11 +1224,19 @@ export const TOOL_DEFINITIONS = [
         required: ['capsuleTypeResourceId', 'title'],
         group: 'capsules',
         readOnly: false,
-        execute: async (ctx, input) => createCapsule(ctx.client, {
-            capsuleTypeResourceId: input.capsuleTypeResourceId,
-            title: input.title,
-            description: input.description,
-        }),
+        execute: async (ctx, input) => {
+            const capsuleTitle = input.title;
+            // Guard: check for existing capsule with same title
+            const existingCapsule = await findExistingCapsule(ctx.client, capsuleTitle);
+            if (existingCapsule) {
+                return { _guard: 'duplicate_skipped', message: `Capsule "${capsuleTitle}" already exists.`, existing: existingCapsule };
+            }
+            return createCapsule(ctx.client, {
+                capsuleTypeResourceId: input.capsuleTypeResourceId,
+                title: capsuleTitle,
+                description: input.description,
+            });
+        },
     },
     {
         name: 'update_capsule',
@@ -1260,8 +1384,9 @@ export const TOOL_DEFINITIONS = [
         group: 'customer_credit_notes',
         readOnly: false,
         execute: async (ctx, input) => {
-            const { resourceId: rid, ...data } = input;
-            return finalizeCustomerCreditNote(ctx.client, rid, data);
+            const { resourceId: rid, ...overrides } = input;
+            const merged = await fetchAndMerge(ctx.client, 'customer_credit_note', rid, overrides);
+            return finalizeCustomerCreditNote(ctx.client, rid, merged);
         },
     },
     {
@@ -1434,8 +1559,9 @@ export const TOOL_DEFINITIONS = [
         group: 'supplier_credit_notes',
         readOnly: false,
         execute: async (ctx, input) => {
-            const { resourceId: rid, ...data } = input;
-            return finalizeSupplierCreditNote(ctx.client, rid, data);
+            const { resourceId: rid, ...overrides } = input;
+            const merged = await fetchAndMerge(ctx.client, 'supplier_credit_note', rid, overrides);
+            return finalizeSupplierCreditNote(ctx.client, rid, merged);
         },
     },
     {
@@ -1508,7 +1634,22 @@ export const TOOL_DEFINITIONS = [
         required: ['currencies'],
         group: 'currencies',
         readOnly: false,
-        execute: async (ctx, input) => addCurrency(ctx.client, input.currencies),
+        execute: async (ctx, input) => {
+            const requested = input.currencies;
+            // Guard: fetch all enabled currencies once, filter locally (not N API calls)
+            const allCurrencies = await listCurrencies(ctx.client);
+            const enabledSet = new Set(allCurrencies.data.map(c => c.currencyCode.toUpperCase()));
+            const alreadyEnabled = requested.filter(code => enabledSet.has(code.toUpperCase()));
+            const toAdd = requested.filter(code => !enabledSet.has(code.toUpperCase()));
+            if (toAdd.length === 0) {
+                return { _guard: 'duplicate_skipped', message: `All currencies already enabled: ${requested.join(', ')}.`, existing: alreadyEnabled };
+            }
+            const result = await addCurrency(ctx.client, toAdd);
+            if (alreadyEnabled.length > 0) {
+                return { ...result, _note: `Skipped already-enabled: ${alreadyEnabled.join(', ')}` };
+            }
+            return result;
+        },
     },
     {
         name: 'list_currency_rates',
@@ -1610,10 +1751,12 @@ export const TOOL_DEFINITIONS = [
     listTool('list_cash_in', 'List cash-in entries (direct cash receipts). Paginated.', 'cash_entries', (client, off, lim) => listCashIn(client, { limit: lim, offset: off })),
     {
         name: 'create_cash_in',
-        description: `Record money received INTO a bank account (customer payment, refund received, deposit). NOT for transfers between your own accounts — use create_cash_transfer instead. IMPORTANT:
+        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 is the bank/cash account receiving the money.
 - 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 and vice versa.`,
+- The API enforces account separation: cash-in accounts cannot be used for cash-out.`,
         params: {
             reference: { type: 'string', description: 'Reference number' },
             valueDate: { type: 'string', description: 'Date (YYYY-MM-DD)' },
@@ -1649,10 +1792,12 @@ export const TOOL_DEFINITIONS = [
     listTool('list_cash_out', 'List cash-out entries (direct cash disbursements). Paginated.', 'cash_entries', (client, off, lim) => listCashOut(client, { limit: lim, offset: off })),
     {
         name: 'create_cash_out',
-        description: `Record money paid OUT FROM a bank account (expense, supplier payment, reimbursement, withdrawal). NOT for transfers between your own accounts — use create_cash_transfer instead. IMPORTANT:
+        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 is the bank/cash account disbursing the money.
 - 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 and vice versa.`,
+- The API enforces account separation: cash-out accounts cannot be used for cash-in.`,
         params: {
             reference: { type: 'string', description: 'Reference number' },
             valueDate: { type: 'string', description: 'Date (YYYY-MM-DD)' },
@@ -1749,9 +1894,11 @@ export const TOOL_DEFINITIONS = [
     listTool('list_cash_transfers', 'List cash transfer entries. Paginated.', 'cash_transfers', (client, off, lim) => listCashTransfers(client, { limit: lim, offset: off })),
     {
         name: 'create_cash_transfer',
-        description: `Move money between two of YOUR OWN bank/cash accounts (internal transfer). NOT for recording payments to/from contacts — use create_cash_in or create_cash_out instead.
-- cashOut = source (money leaves), cashIn = destination (money arrives).
-- Each side needs accountResourceId + amount. That's it for simple transfers.
+        description: `Move money between two of YOUR OWN bank/cash accounts (internal transfer, e.g., main bank to petty cash, USD account to SGD account).
+WHEN TO USE: petty cash top-ups from bank, inter-account transfers, currency conversions between own accounts.
+WHEN NOT TO USE: receiving money from external parties (use create_cash_in) or paying external parties (use create_cash_out).
+- cashOut = source account (money leaves), cashIn = destination account (money arrives).
+- Each side needs accountResourceId + amount.
 - reference is auto-generated if not provided.
 - Do NOT send currency/exchangeRate — derived server-side from bank account currencies.`,
         params: {
@@ -2077,13 +2224,14 @@ Available export types: trial-balance, balance-sheet, profit-and-loss, general-l
         description: `Plan a transaction recipe — run a financial calculator and show what accounts, contacts, and bank accounts are needed. Read-only (no API calls).
 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.`,
+Use this BEFORE execute_recipe to verify requirements. Parameters vary by recipe — see recipe skill docs for per-recipe params.
+CRITICAL: ALWAYS call this tool for ANY calculation involving: depreciation, amortization, ECL/expected credit loss, FX revaluation, lease/IFRS 16, hire purchase, loan schedules, provisions, deferred revenue, fixed deposits, or asset disposal. Never compute these manually.`,
         params: {
             recipe: { type: 'string', enum: [...RECIPE_TYPES], description: 'Recipe type' },
             // Universal params
             amount: { type: 'number', description: 'Amount (for amortization, accrued-expense, dividend, ecl, provision, fx-reval)' },
             principal: { type: 'number', description: 'Principal (for loan, fixed-deposit)' },
-            startDate: { type: 'string', description: 'Start date YYYY-MM-DD (enables blueprint generation for most recipes)' },
+            startDate: { type: 'string', description: 'Start date YYYY-MM-DD (REQUIRED for blueprint generation — default to today if user does not specify)' },
             currency: { type: 'string', description: 'Currency code (e.g. SGD, USD)' },
             periods: { type: 'number', description: 'Number of periods (for amortization, accrued-expense, leave-accrual)' },
             frequency: { type: 'string', enum: ['monthly', 'quarterly', 'annual'], description: 'Frequency (for depreciation, amortization, accrued-expense)' },
@@ -2609,7 +2757,7 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
         }),
     },
     // ══════════════════════════════════════════════════════════════
-    // ── Job Blueprint Tools (offline — no API calls) ─────────────
+    // ── Close Procedure Jobs (offline — no API calls) ────────────
     // ══════════════════════════════════════════════════════════════
     {
         name: 'generate_month_end_blueprint',
@@ -2619,7 +2767,7 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
             currency: { type: 'string', description: 'Base currency (e.g., "SGD"). Defaults to SGD.' },
         },
         required: ['period'],
-        group: 'jobs',
+        group: 'close_jobs',
         readOnly: true,
         execute: async (_ctx, input) => generateMonthEndBlueprint({
             period: input.period,
@@ -2635,7 +2783,7 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
             incremental: { type: 'boolean', description: 'Skip month-end phases (assumes months already closed)' },
         },
         required: ['period'],
-        group: 'jobs',
+        group: 'close_jobs',
         readOnly: true,
         execute: async (_ctx, input) => generateQuarterEndBlueprint({
             period: input.period,
@@ -2652,7 +2800,7 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
             incremental: { type: 'boolean', description: 'Skip quarter/month phases (assumes already closed)' },
         },
         required: ['period'],
-        group: 'jobs',
+        group: 'close_jobs',
         readOnly: true,
         execute: async (_ctx, input) => generateYearEndBlueprint({
             period: input.period,
@@ -2669,7 +2817,7 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
             currency: { type: 'string', description: 'Base currency (e.g., "SGD"). Defaults to SGD.' },
         },
         required: [],
-        group: 'jobs',
+        group: 'close_jobs',
         readOnly: true,
         execute: async (_ctx, input) => generateBankReconBlueprint({
             account: input.account,
@@ -2685,7 +2833,7 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
             currency: { type: 'string', description: 'Base currency (e.g., "SGD"). Defaults to SGD.' },
         },
         required: ['period'],
-        group: 'jobs',
+        group: 'close_jobs',
         readOnly: true,
         execute: async (_ctx, input) => generateGstVatBlueprint({
             period: input.period,
@@ -2700,7 +2848,7 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
             currency: { type: 'string', description: 'Base currency (e.g., "SGD"). Defaults to SGD.' },
         },
         required: [],
-        group: 'jobs',
+        group: 'operational_jobs',
         readOnly: true,
         execute: async (_ctx, input) => generatePaymentRunBlueprint({
             dueBefore: input.dueBefore,
@@ -2715,7 +2863,7 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
             currency: { type: 'string', description: 'Base currency (e.g., "SGD"). Defaults to SGD.' },
         },
         required: [],
-        group: 'jobs',
+        group: 'operational_jobs',
         readOnly: true,
         execute: async (_ctx, input) => generateCreditControlBlueprint({
             overdueDays: input.overdueDays,
@@ -2731,7 +2879,7 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
             currency: { type: 'string', description: 'Base currency (e.g., "SGD"). Defaults to SGD.' },
         },
         required: [],
-        group: 'jobs',
+        group: 'operational_jobs',
         readOnly: true,
         execute: async (_ctx, input) => generateSupplierReconBlueprint({
             supplier: input.supplier,
@@ -2747,7 +2895,7 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
             currency: { type: 'string', description: 'Base currency (e.g., "SGD"). Defaults to SGD.' },
         },
         required: ['period'],
-        group: 'jobs',
+        group: 'close_jobs',
         readOnly: true,
         execute: async (_ctx, input) => generateAuditPrepBlueprint({
             period: input.period,
@@ -2761,7 +2909,7 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
             currency: { type: 'string', description: 'Base currency (e.g., "SGD"). Defaults to SGD.' },
         },
         required: [],
-        group: 'jobs',
+        group: 'operational_jobs',
         readOnly: true,
         execute: async (_ctx, input) => generateFaReviewBlueprint({
             currency: input.currency,
@@ -2774,7 +2922,7 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
             currency: { type: 'string', description: 'Base currency (e.g., "SGD"). Defaults to SGD.' },
         },
         required: [],
-        group: 'jobs',
+        group: 'operational_jobs',
         readOnly: true,
         execute: async (_ctx, input) => generateDocumentCollectionBlueprint({
             currency: input.currency,
@@ -2789,7 +2937,7 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
             currency: { type: 'string', description: 'Base currency (e.g., "SGD"). Defaults to SGD.' },
         },
         required: [],
-        group: 'jobs',
+        group: 'operational_jobs',
         readOnly: true,
         execute: async (_ctx, input) => generateStatutoryFilingBlueprint({
             ya: input.ya,
@@ -3189,12 +3337,12 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
             return handlePagination((off, lim) => searchScheduledTransactions(ctx.client, {
                 filter: Object.keys(filter).length > 0 ? filter : undefined,
                 limit: lim, offset: off,
-                sort: { sortBy: [sortBy ?? 'valueDate'], order: (sortOrder ?? 'DESC') },
+                sort: { sortBy: [sortBy ?? 'startDate'], order: (sortOrder ?? 'DESC') },
             }), limit, offset, 20);
         },
     },
     // ══════════════════════════════════════════════════════════════
-    // ── Reports (8 new) ────────────────────────────────────────
+    // ── Financial Reports (continued) ─────────────────────────
     // ══════════════════════════════════════════════════════════════
     {
         name: 'generate_vat_ledger',
@@ -3204,7 +3352,7 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
             endDate: { type: 'string', description: 'End date (YYYY-MM-DD)' },
         },
         required: ['startDate', 'endDate'],
-        group: 'reports',
+        group: 'financial_reports',
         readOnly: true,
         execute: async (ctx, input) => generateVatLedger(ctx.client, {
             startDate: input.startDate,
@@ -3222,7 +3370,7 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
             compareCount: { type: 'number', description: 'Number of comparison periods' },
         },
         required: ['primarySnapshotStartDate', 'primarySnapshotEndDate'],
-        group: 'reports',
+        group: 'financial_reports',
         readOnly: true,
         execute: async (ctx, input) => generateEquityMovement(ctx.client, input),
     },
@@ -3234,7 +3382,7 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
             currencyCode: { type: 'string', description: 'Currency code (e.g., "SGD")' },
         },
         required: ['primarySnapshotDate'],
-        group: 'reports',
+        group: 'operational_reports',
         readOnly: true,
         execute: async (ctx, input) => generateBankBalanceSummary(ctx.client, {
             primarySnapshotDate: input.primarySnapshotDate,
@@ -3252,7 +3400,7 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
             tags: { type: 'array', items: { type: 'string' }, description: 'Filter by tags' },
         },
         required: ['bankAccountResourceId', 'primarySnapshotStartDate', 'primarySnapshotEndDate'],
-        group: 'reports',
+        group: 'operational_reports',
         readOnly: true,
         execute: async (ctx, input) => generateBankReconSummary(ctx.client, input),
     },
@@ -3267,7 +3415,7 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
             currencyCode: { type: 'string', description: 'Currency code' },
         },
         required: ['bankAccountResourceId', 'primarySnapshotStartDate', 'primarySnapshotEndDate', 'filter'],
-        group: 'reports',
+        group: 'operational_reports',
         readOnly: true,
         execute: async (ctx, input) => generateBankReconDetails(ctx.client, input),
     },
@@ -3281,7 +3429,7 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
             currencyCode: { type: 'string', description: 'Currency code' },
         },
         required: ['primarySnapshotStartDate', 'primarySnapshotEndDate', 'groupBy'],
-        group: 'reports',
+        group: 'operational_reports',
         readOnly: true,
         execute: async (ctx, input) => generateFaSummary(ctx.client, input),
     },
@@ -3295,7 +3443,7 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
             currencyCode: { type: 'string', description: 'Currency code' },
         },
         required: ['primarySnapshotStartDate', 'primarySnapshotEndDate'],
-        group: 'reports',
+        group: 'operational_reports',
         readOnly: true,
         execute: async (ctx, input) => generateFaReconSummary(ctx.client, input),
     },
@@ -3306,7 +3454,7 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
             endDate: { type: 'string', description: 'Report date (YYYY-MM-DD) — point-in-time snapshot' },
         },
         required: ['endDate'],
-        group: 'reports',
+        group: 'operational_reports',
         readOnly: true,
         execute: async (ctx, input) => generateArReport(ctx.client, { endDate: input.endDate }),
     },
@@ -3535,7 +3683,7 @@ Works for invoices, bills, customer credit notes, supplier credit notes, and jou
             resourceId: { type: 'string', description: 'Transaction resourceId' },
         },
         required: ['transactionType', 'resourceId'],
-        group: 'invoices',
+        group: 'search',
         readOnly: true,
         execute: async (ctx, input) => {
             const type = input.transactionType;
@@ -3602,18 +3750,18 @@ Works for invoices, bills, customer credit notes, supplier credit notes, and jou
             const results = [];
             for (const item of items) {
                 try {
-                    const lineItems = await fetchLineItems(ctx.client, item.type, item.resourceId);
+                    const merged = await fetchAndMerge(ctx.client, item.type, item.resourceId, {});
                     if (item.type === 'invoice') {
-                        await finalizeInvoice(ctx.client, item.resourceId, { lineItems });
+                        await finalizeInvoice(ctx.client, item.resourceId, merged);
                     }
                     else if (item.type === 'bill') {
-                        await finalizeBill(ctx.client, item.resourceId, { lineItems });
+                        await finalizeBill(ctx.client, item.resourceId, merged);
                     }
                     else if (item.type === 'customer_credit_note') {
-                        await finalizeCustomerCreditNote(ctx.client, item.resourceId, { lineItems });
+                        await finalizeCustomerCreditNote(ctx.client, item.resourceId, merged);
                     }
                     else if (item.type === 'supplier_credit_note') {
-                        await finalizeSupplierCreditNote(ctx.client, item.resourceId, { lineItems });
+                        await finalizeSupplierCreditNote(ctx.client, item.resourceId, merged);
                     }
                     results.push({ ...item, success: true });
                 }

package/package.json

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