jaz-clio 4.24.0 → 4.25.1

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 4.24.0
+version: 4.25.1
 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.
@@ -85,7 +85,7 @@ You are working with the **Jaz REST API** — the accounting platform backend. A
 
 ### Custom Fields
 35. **Do NOT send `appliesTo` on custom field POST** — causes "Invalid request body". Only send `name`, `type`, `printOnDocuments`.
-35a. **Custom field values on transactions**: Set via `customFields: [{ customFieldName: "PO Number", actualValue: "PO-123" }]` on invoice/bill/customer-CN/supplier-CN create/update. NOT on journals, cash entries, or cash transfers. Read from GET responses in the same shape.
+35a. **Custom field values on transactions**: Set via `customFields: [{ customFieldName: "PO Number", actualValue: "PO-123" }]` on invoice/bill/customer-CN/supplier-CN/payment/item create/update. NOT on journals, cash entries, or cash transfers. Read from GET responses in the same shape.
 35b. **Custom field search**: `POST /custom-fields/search` with filter/sort/limit/offset. Filter by `customFieldName` (StringExpression), `datatypeCode` (StringExpression: TEXT, DATE, DROPDOWN).
 35c. **Custom field GET**: `GET /custom-fields/:resourceId` returns full definition including `applyToSales`, `applyToPurchase`, `applyToCreditNote`, `applyToPayment`, `printOnDocuments`, `listOptions`.
 

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 4.24.0
+version: 4.25.1
 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.24.0
+version: 4.25.1
 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.24.0
+version: 4.25.1
 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/bills.js

@@ -254,17 +254,20 @@ export function registerBillsCommand(program) {
         .option('--method <method>', 'Payment method (BANK_TRANSFER, CASH, CHEQUE, etc.)', 'BANK_TRANSFER')
         .option('--ref <reference>', 'Payment reference')
         .option('--draft', 'Save as draft instead of finalizing')
+        .option('--custom-fields <json>', 'Custom field values as JSON array')
         .option('--input <file>', 'Read full payment body from JSON file (or pipe via stdin)')
         .option('--api-key <key>', 'API key (overrides stored/env)')
         .option('--json', 'Output as JSON')
         .action((resourceId, opts) => apiAction(async (client) => {
         const body = readBodyInput(opts);
+        const customFields = opts.customFields ? parseCustomFields(opts.customFields) : undefined;
         let res;
         if (body) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any -- user-provided JSON, API validates
             res = await createBillPayment(client, resourceId, {
                 ...body,
                 saveAsDraft: body.saveAsDraft ?? (opts.draft ?? false),
+                customFields: body.customFields ?? customFields,
             });
         }
         else {
@@ -287,6 +290,7 @@ export function registerBillsCommand(program) {
                 paymentMethod: opts.method,
                 reference: opts.ref ?? '',
                 saveAsDraft: opts.draft ?? false,
+                customFields,
             });
         }
         if (opts.json) {

package/dist/commands/help-examples.js

@@ -0,0 +1,127 @@
+/**
+ * Centralized help examples for CLI commands.
+ * All examples in ONE file — zero changes to existing command files.
+ * After all register*Command() calls, one call to applyAllExamples() walks the
+ * command tree and attaches examples via Commander.js .addHelpText().
+ */
+import chalk from 'chalk';
+const EXAMPLES = {
+    'invoices list': [
+        { description: 'List first 100 invoices', command: 'clio invoices list' },
+        { description: 'Export all invoices as CSV', command: 'clio invoices list --all --format csv' },
+        { description: 'Get JSON for piping to other tools', command: 'clio invoices list --limit 50 --json' },
+    ],
+    'invoices search': [
+        { description: 'Search by reference', command: 'clio invoices search --reference INV-001' },
+        { description: 'Find overdue invoices', command: 'clio invoices search --status APPROVED --dueDateTo 2025-12-31' },
+        { description: 'Search by contact and export', command: 'clio invoices search --contactName "Acme" --format json' },
+    ],
+    'invoices create': [
+        { description: 'Create a simple invoice', command: 'clio invoices create --contact "Acme Corp" --date 2025-06-01 --due 2025-07-01 --line "Consulting,10,150"' },
+        { description: 'Create with tax profile', command: 'clio invoices create --contact "Acme Corp" --date 2025-06-01 --due 2025-07-01 --line "Service,1,1000,,,tp-sr" --status APPROVED' },
+        { description: 'Create from JSON file', command: 'clio invoices create --body invoice.json' },
+    ],
+    'invoices pay': [
+        { description: 'Record a full payment', command: 'clio invoices pay <resourceId> --amount 1000 --date 2025-06-15 --account "Cash"' },
+    ],
+    'bills list': [
+        { description: 'List all bills', command: 'clio bills list' },
+        { description: 'Export as YAML', command: 'clio bills list --format yaml' },
+        { description: 'Fetch every page as JSON', command: 'clio bills list --all --json' },
+    ],
+    'bills search': [
+        { description: 'Search by supplier name', command: 'clio bills search --contactName "Supplier Co"' },
+        { description: 'Find draft bills', command: 'clio bills search --status DRAFT' },
+    ],
+    'bills create': [
+        { description: 'Create a bill', command: 'clio bills create --contact "Supplier Co" --date 2025-06-01 --due 2025-07-01 --line "Office supplies,5,20"' },
+        { description: 'Create from JSON body', command: 'clio bills create --body bill.json' },
+    ],
+    'contacts list': [
+        { description: 'List contacts', command: 'clio contacts list' },
+        { description: 'Export all as CSV', command: 'clio contacts list --all --format csv' },
+    ],
+    'contacts search': [
+        { description: 'Find customers', command: 'clio contacts search --customer true' },
+        { description: 'Search by name', command: 'clio contacts search --name "Acme"' },
+    ],
+    'contacts create': [
+        { description: 'Create a customer', command: 'clio contacts create --name "New Client" --customer' },
+        { description: 'Create a supplier', command: 'clio contacts create --name "Vendor Inc" --supplier' },
+    ],
+    'journals create': [
+        { description: 'Create a journal entry', command: 'clio journals create --date 2025-06-01 --ref "ADJ-001" --debit "Office Expenses,500" --credit "Cash,500"' },
+        { description: 'Create with description', command: 'clio journals create --date 2025-06-01 --ref "ADJ-002" --debit "Rent,2000" --credit "Bank,2000" --description "Monthly rent"' },
+    ],
+    'reports generate': [
+        { description: 'Generate trial balance', command: 'clio reports generate trial-balance --date 2025-06-30' },
+        { description: 'Profit & Loss for a period', command: 'clio reports generate profit-and-loss --from 2025-01-01 --to 2025-06-30' },
+        { description: 'Balance sheet as JSON', command: 'clio reports generate balance-sheet --date 2025-06-30 --json' },
+        { description: 'Export AR summary as CSV', command: 'clio reports generate ar-summary --date 2025-06-30 --format csv' },
+    ],
+    'accounts list': [
+        { description: 'List chart of accounts', command: 'clio accounts list' },
+        { description: 'Export as JSON', command: 'clio accounts list --json' },
+    ],
+    'items search': [
+        { description: 'Search items by name', command: 'clio items search --name "Widget"' },
+        { description: 'Find sale items', command: 'clio items search --saleItem true' },
+    ],
+    'bank import': [
+        { description: 'Import a bank statement', command: 'clio bank import --file statement.csv --account "DBS Current"' },
+    ],
+    search: [
+        { description: 'Search across all entities', command: 'clio search "Acme Corp"' },
+        { description: 'Search with limit', command: 'clio search "INV-001" --limit 5' },
+    ],
+    'capsules create': [
+        { description: 'Create a capsule', command: 'clio capsules create --name "Q2 Prepaid" --type PREPAID_EXPENSES --class ASSET' },
+    ],
+    'customer-credit-notes create': [
+        { description: 'Create a credit note', command: 'clio customer-credit-notes create --contact "Acme" --date 2025-06-01 --line "Refund,1,500"' },
+    ],
+    'magic create': [
+        { description: 'Extract data from a document', command: 'clio magic create --file invoice.pdf' },
+        { description: 'Check extraction status', command: 'clio magic status <jobId>' },
+    ],
+    schema: [
+        { description: 'List all API groups', command: 'clio schema' },
+        { description: 'Show tools in a group', command: 'clio schema invoices' },
+        { description: 'Inspect a specific tool\'s params', command: 'clio schema invoices create' },
+        { description: 'Get full schema as JSON', command: 'clio schema invoices create --json' },
+    ],
+};
+/** Format examples block for Commander help text. */
+function formatExamples(examples) {
+    const lines = ['\nEXAMPLES'];
+    for (const ex of examples) {
+        if (ex.description)
+            lines.push(`  ${chalk.dim(ex.description)}`);
+        lines.push(`  $ ${ex.command}`);
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+/** Recursively find a subcommand by dot-separated path (e.g., "invoices.list"). */
+function findCommand(root, path) {
+    const parts = path.split(' ');
+    let cmd = root;
+    for (const part of parts) {
+        cmd = cmd?.commands.find((c) => c.name() === part);
+        if (!cmd)
+            return undefined;
+    }
+    return cmd;
+}
+/**
+ * Walk the Commander tree and attach examples to matching commands.
+ * Call once after all register*Command() calls.
+ */
+export function applyAllExamples(program) {
+    for (const [path, examples] of Object.entries(EXAMPLES)) {
+        const cmd = findCommand(program, path);
+        if (cmd) {
+            cmd.addHelpText('after', formatExamples(examples));
+        }
+    }
+}

package/dist/commands/invoices.js

@@ -256,17 +256,20 @@ export function registerInvoicesCommand(program) {
         .option('--method <method>', 'Payment method (BANK_TRANSFER, CASH, CHEQUE, etc.)', 'BANK_TRANSFER')
         .option('--ref <reference>', 'Payment reference')
         .option('--draft', 'Save as draft instead of finalizing')
+        .option('--custom-fields <json>', 'Custom field values as JSON array')
         .option('--input <file>', 'Read full payment body from JSON file (or pipe via stdin)')
         .option('--api-key <key>', 'API key (overrides stored/env)')
         .option('--json', 'Output as JSON')
         .action((resourceId, opts) => apiAction(async (client) => {
         const body = readBodyInput(opts);
+        const customFields = opts.customFields ? parseCustomFields(opts.customFields) : undefined;
         let res;
         if (body) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any -- user-provided JSON, API validates
             res = await createInvoicePayment(client, resourceId, {
                 ...body,
                 saveAsDraft: body.saveAsDraft ?? (opts.draft ?? false),
+                customFields: body.customFields ?? customFields,
             });
         }
         else {
@@ -289,6 +292,7 @@ export function registerInvoicesCommand(program) {
                 paymentMethod: opts.method,
                 reference: opts.ref ?? '',
                 saveAsDraft: opts.draft ?? false,
+                customFields,
             });
         }
         if (opts.json) {

package/dist/commands/items.js

@@ -2,7 +2,7 @@ import chalk from 'chalk';
 import { listItems, getItem, searchItems, createItem, updateItem, deleteItem, } from '../core/api/items.js';
 import { apiAction } from './api-action.js';
 import { outputList } from './output.js';
-import { parsePositiveInt, parseNonNegativeInt, parseMoney, readBodyInput, requireFields } from './parsers.js';
+import { parsePositiveInt, parseNonNegativeInt, parseMoney, readBodyInput, requireFields, parseCustomFields } from './parsers.js';
 import { paginatedFetch } from './pagination.js';
 import { formatId } from './format-helpers.js';
 const ITEMS_COLUMNS = [
@@ -101,6 +101,7 @@ export function registerItemsCommand(program) {
         .option('--purchase-account <resourceId>', 'Purchase account resourceId')
         .option('--sale-tax <resourceId>', 'Sale tax profile resourceId')
         .option('--purchase-tax <resourceId>', 'Purchase tax profile resourceId')
+        .option('--custom-fields <json>', 'Custom field values as JSON array: [{"customFieldName":"PO Number","actualValue":"PO-123"}]')
         .option('--input <file>', 'Read full request body from JSON file (or pipe via stdin)')
         .option('--api-key <key>', 'API key (overrides stored/env)')
         .option('--format <type>', 'Output format: table, json, csv, yaml')
@@ -117,6 +118,7 @@ export function registerItemsCommand(program) {
                 { flag: '--name', key: 'name' },
                 { flag: '--code', key: 'code' },
             ]);
+            const customFields = opts.customFields ? parseCustomFields(opts.customFields) : undefined;
             res = await createItem(client, {
                 internalName: opts.name,
                 itemCode: opts.code,
@@ -128,6 +130,7 @@ export function registerItemsCommand(program) {
                 purchaseAccountResourceId: opts.purchaseAccount,
                 saleTaxProfileResourceId: opts.saleTax,
                 purchaseTaxProfileResourceId: opts.purchaseTax,
+                customFields,
             });
         }
         if (opts.json) {
@@ -147,6 +150,7 @@ export function registerItemsCommand(program) {
         .option('--sale-price <n>', 'New sale price', parseMoney)
         .option('--purchase-price <n>', 'New purchase price', parseMoney)
         .option('--status <status>', 'Status (ACTIVE/INACTIVE)')
+        .option('--custom-fields <json>', 'Custom field values as JSON array')
         .option('--input <file>', 'Read full update body from JSON file (or pipe via stdin)')
         .option('--api-key <key>', 'API key (overrides stored/env)')
         .option('--format <type>', 'Output format: table, json, csv, yaml')
@@ -169,6 +173,8 @@ export function registerItemsCommand(program) {
                 data.purchasePrice = opts.purchasePrice;
             if (opts.status !== undefined)
                 data.status = opts.status;
+            if (opts.customFields)
+                data.customFields = parseCustomFields(opts.customFields);
         }
         const res = await updateItem(client, resourceId, data);
         if (opts.json) {

package/dist/commands/schema.js

@@ -0,0 +1,240 @@
+/**
+ * `clio schema` — offline API schema introspection.
+ * No auth required — reads from compiled tool registry.
+ *
+ * Three levels:
+ *   clio schema                        → list all groups with tool counts
+ *   clio schema <group>                → show tools in a group
+ *   clio schema <group> <action>       → show detailed params for a tool
+ */
+import chalk from 'chalk';
+import { getAllTools, getToolsByGroup } from '../core/registry/lookup.js';
+import { formatTable } from './table-formatter.js';
+import { resolveFormat, outputRecord } from './output.js';
+import { formatId } from './format-helpers.js';
+// ── Group → CLI command mapping ─────────────────────────────────
+const GROUP_CLI_MAP = {
+    cash_entries: 'cash-in / cash-out',
+    cash_transfers: 'cash-transfer',
+    customer_credit_notes: 'customer-credit-notes',
+    supplier_credit_notes: 'supplier-credit-notes',
+    bank_rules: 'bank-rules',
+    org_users: 'org-users',
+    tax_profiles: 'tax-profiles',
+    contact_groups: 'contact-groups',
+    custom_fields: 'custom-fields',
+    fixed_assets: 'fixed-assets',
+};
+function groupToCliCommand(group) {
+    return GROUP_CLI_MAP[group] ?? group.replace(/_/g, '-');
+}
+// ── Singularize helper ──────────────────────────────────────────
+function singularize(word) {
+    if (word.endsWith('ies'))
+        return word.slice(0, -3) + 'y';
+    if (word.endsWith('ses'))
+        return word.slice(0, -2);
+    if (word.endsWith('s') && !word.endsWith('ss'))
+        return word.slice(0, -1);
+    return word;
+}
+// ── Tool name resolution ────────────────────────────────────────
+function resolveToolName(group, action, tools) {
+    // Try exact: action_group (e.g., list_invoices)
+    const exactPlural = `${action}_${group}`;
+    const found1 = tools.find((t) => t.name === exactPlural);
+    if (found1)
+        return found1;
+    // Try singular: action_singular (e.g., create_invoice)
+    const singular = singularize(group);
+    const exactSingular = `${action}_${singular}`;
+    const found2 = tools.find((t) => t.name === exactSingular);
+    if (found2)
+        return found2;
+    // Try with group prefix removed for compound groups (e.g., customer_credit_notes → credit_note)
+    // and also try action_group_singular for multi-word groups
+    const found3 = tools.find((t) => t.name === `${action}_${group.replace(/_/g, '_')}`);
+    if (found3)
+        return found3;
+    // Fuzzy: find any tool in group whose name contains the action
+    return tools.find((t) => t.name.includes(action));
+}
+function flattenParams(params, required, prefix = '', depth = 0) {
+    if (depth > 3)
+        return [];
+    const result = [];
+    for (const [key, def] of Object.entries(params)) {
+        const fullName = prefix ? `${prefix}.${key}` : key;
+        const isRequired = required.includes(key) && !prefix;
+        result.push({
+            name: fullName,
+            type: def.type,
+            required: isRequired,
+            values: def.enum?.join(',') ?? '-',
+            description: def.description ?? '-',
+        });
+        // Recurse into object properties
+        if (def.type === 'object' && def.properties) {
+            result.push(...flattenParams(def.properties, def.required ?? [], fullName, depth + 1));
+        }
+        // Recurse into array items
+        if (def.type === 'array' && def.items) {
+            if (def.items.type === 'object' && def.items.properties) {
+                result.push(...flattenParams(def.items.properties, def.items.required ?? [], `${fullName}[]`, depth + 1));
+            }
+        }
+    }
+    return result;
+}
+// ── Output helpers ──────────────────────────────────────────────
+function outputGroupList(opts) {
+    const all = getAllTools();
+    const groupMap = new Map();
+    for (const tool of all) {
+        const list = groupMap.get(tool.group) ?? [];
+        list.push(tool);
+        groupMap.set(tool.group, list);
+    }
+    const groups = Array.from(groupMap.entries())
+        .sort(([, a], [, b]) => b.length - a.length)
+        .map(([group, tools]) => ({
+        group,
+        tools: tools.length,
+        read: tools.filter((t) => t.readOnly).length,
+        write: tools.filter((t) => !t.readOnly).length,
+        cliCommand: `clio ${groupToCliCommand(group)}`,
+    }));
+    const fmt = resolveFormat(opts);
+    if (fmt !== 'table') {
+        outputRecord({ totalTools: all.length, totalGroups: groups.length, groups }, opts);
+        return;
+    }
+    console.log(chalk.bold(`Schema — ${all.length} tools across ${groups.length} groups\n`));
+    const columns = [
+        { key: 'group', header: 'Group', format: (v) => chalk.cyan(String(v)) },
+        { key: 'tools', header: 'Tools', align: 'right' },
+        { key: 'read', header: 'Read', align: 'right' },
+        { key: 'write', header: 'Write', align: 'right' },
+        { key: 'cliCommand', header: 'CLI Command', format: (v) => chalk.dim(String(v)) },
+    ];
+    console.log(formatTable(groups, columns));
+}
+function outputGroupDetail(group, tools, opts) {
+    const readCount = tools.filter((t) => t.readOnly).length;
+    const writeCount = tools.filter((t) => !t.readOnly).length;
+    const fmt = resolveFormat(opts);
+    if (fmt !== 'table') {
+        outputRecord({
+            group,
+            cliCommand: `clio ${groupToCliCommand(group)}`,
+            toolCount: tools.length,
+            read: readCount,
+            write: writeCount,
+            tools: tools.map((t) => ({
+                name: t.name,
+                type: t.readOnly ? 'read' : 'write',
+                params: Object.keys(t.params).length,
+                description: t.description.slice(0, 120),
+            })),
+        }, opts);
+        return;
+    }
+    console.log(chalk.bold(`${group} — ${tools.length} tools (${readCount} read, ${writeCount} write)\n`));
+    const columns = [
+        { key: 'name', header: 'Tool', format: formatId },
+        { key: 'type', header: 'Type' },
+        { key: 'params', header: 'Params', align: 'right' },
+        { key: 'description', header: 'Description' },
+    ];
+    const rows = tools.map((t) => ({
+        name: t.name,
+        type: t.readOnly ? 'read' : 'write',
+        params: Object.keys(t.params).length,
+        description: t.description.length > 80 ? t.description.slice(0, 79) + '\u2026' : t.description,
+    }));
+    console.log(formatTable(rows, columns));
+    console.log(chalk.dim(`\n  Use: clio schema ${groupToCliCommand(group)} <action>`));
+}
+function outputToolDetail(tool, opts) {
+    const flat = flattenParams(tool.params, tool.required);
+    const fmt = resolveFormat(opts);
+    if (fmt !== 'table') {
+        outputRecord({
+            tool: tool.name,
+            group: tool.group,
+            description: tool.description,
+            readOnly: tool.readOnly,
+            requiredParams: tool.required,
+            params: tool.params,
+        }, opts);
+        return;
+    }
+    console.log(chalk.bold(`${tool.name}`) + chalk.dim(` — ${tool.description}\n`));
+    if (flat.length === 0) {
+        console.log('  No parameters.');
+        return;
+    }
+    const columns = [
+        { key: 'name', header: 'Parameter', format: (v) => chalk.cyan(String(v)) },
+        { key: 'type', header: 'Type' },
+        { key: 'required', header: 'Required', format: (v) => (v === true || v === 'true') ? chalk.green('Yes') : 'No' },
+        { key: 'values', header: 'Values' },
+        { key: 'description', header: 'Description' },
+    ];
+    console.log(formatTable(flat, columns));
+}
+// ── Command registration ────────────────────────────────────────
+export function registerSchemaCommand(program) {
+    program
+        .command('schema')
+        .description('Introspect API schema — discover fields, types, and constraints')
+        .argument('[group]', 'Entity group (e.g., invoices, contacts)')
+        .argument('[action]', 'Action (e.g., create, search, list)')
+        .option('--format <type>', 'Output format: table, json, csv, yaml')
+        .option('--json', 'Output as JSON')
+        .action((group, action, opts) => {
+        // Level 1: list all groups
+        if (!group) {
+            outputGroupList(opts);
+            return;
+        }
+        // Normalize group: hyphens → underscores to match ToolGroup
+        const normalizedGroup = group.replace(/-/g, '_');
+        const tools = getToolsByGroup(normalizedGroup);
+        if (tools.length === 0) {
+            // Try as-is in case it's already correct
+            const directTools = getToolsByGroup(group);
+            if (directTools.length === 0) {
+                console.error(chalk.red(`Unknown group: ${group}`));
+                console.error(chalk.dim('Run `clio schema` to see available groups.'));
+                process.exit(1);
+            }
+            // Level 2: show group tools
+            if (!action) {
+                outputGroupDetail(group, directTools, opts);
+                return;
+            }
+            const tool = resolveToolName(group, action, directTools);
+            if (!tool) {
+                console.error(chalk.red(`Unknown action: ${action} in group ${group}`));
+                console.error(chalk.dim(`Available: ${directTools.map((t) => t.name).join(', ')}`));
+                process.exit(1);
+            }
+            outputToolDetail(tool, opts);
+            return;
+        }
+        // Level 2: show tools in group
+        if (!action) {
+            outputGroupDetail(normalizedGroup, tools, opts);
+            return;
+        }
+        // Level 3: show tool detail
+        const tool = resolveToolName(normalizedGroup, action, tools);
+        if (!tool) {
+            console.error(chalk.red(`Unknown action: ${action} in group ${group}`));
+            console.error(chalk.dim(`Available: ${tools.map((t) => t.name).join(', ')}`));
+            process.exit(1);
+        }
+        outputToolDetail(tool, opts);
+    });
+}

package/dist/core/registry/tools.js

@@ -417,6 +417,7 @@ export const TOOL_DEFINITIONS = [
                 enum: ['CASH', 'BANK_TRANSFER', 'CREDIT_CARD', 'CHEQUE', 'E_WALLET', 'OTHER'],
                 description: 'Payment method (default BANK_TRANSFER)',
             },
+            customFields: CUSTOM_FIELDS_PARAM,
         },
         required: ['resourceId', 'paymentAmount', 'accountResourceId', 'valueDate'],
         group: 'invoices',
@@ -439,6 +440,7 @@ export const TOOL_DEFINITIONS = [
                 reference: input.reference ?? '',
                 paymentMethod: (input.paymentMethod ?? 'BANK_TRANSFER'),
                 saveAsDraft: false,
+                customFields: input.customFields, // eslint-disable-line @typescript-eslint/no-explicit-any
             });
         },
     },
@@ -603,6 +605,7 @@ export const TOOL_DEFINITIONS = [
             valueDate: { type: 'string' },
             reference: { type: 'string' },
             paymentMethod: { type: 'string' },
+            customFields: CUSTOM_FIELDS_PARAM,
         },
         required: ['resourceId', 'paymentAmount', 'accountResourceId', 'valueDate'],
         group: 'bills',
@@ -625,6 +628,7 @@ export const TOOL_DEFINITIONS = [
                 reference: input.reference ?? '',
                 paymentMethod: (input.paymentMethod ?? 'BANK_TRANSFER'),
                 saveAsDraft: false,
+                customFields: input.customFields, // eslint-disable-line @typescript-eslint/no-explicit-any
             });
         },
     },
@@ -904,6 +908,7 @@ export const TOOL_DEFINITIONS = [
             purchasePrice: { type: 'number', description: 'Default purchase price' },
             saleAccountResourceId: { type: 'string', description: 'Revenue account for sales' },
             purchaseAccountResourceId: { type: 'string', description: 'Expense account for purchases' },
+            customFields: CUSTOM_FIELDS_PARAM,
         },
         required: ['itemCode', 'internalName'],
         group: 'items',
@@ -920,6 +925,7 @@ export const TOOL_DEFINITIONS = [
             salePrice: { type: 'number' },
             purchasePrice: { type: 'number' },
             status: { type: 'string', enum: ['ACTIVE', 'INACTIVE'] },
+            customFields: CUSTOM_FIELDS_PARAM,
         },
         required: ['resourceId'],
         group: 'items',

package/dist/index.js

@@ -49,6 +49,8 @@ import { registerContactGroupsCommand } from './commands/contact-groups.js';
 import { registerInventoryCommand } from './commands/inventory.js';
 import { registerSearchCommand } from './commands/search.js';
 import { registerCustomFieldsCommand } from './commands/custom-fields.js';
+import { registerSchemaCommand } from './commands/schema.js';
+import { applyAllExamples } from './commands/help-examples.js';
 import { shouldShowPicker, showCommandPicker, attachSubcommandPickers } from './commands/picker.js';
 import { getActiveLabel, setProfile, listProfiles } from './core/auth/credentials.js';
 import { getOrganization } from './core/api/organization.js';
@@ -159,6 +161,8 @@ registerContactGroupsCommand(program);
 registerInventoryCommand(program);
 registerSearchCommand(program);
 registerCustomFieldsCommand(program);
+registerSchemaCommand(program);
+applyAllExamples(program);
 // Add --org to every command that has --api-key (DRY: zero changes to command files)
 function addOrgOption(cmd) {
     for (const sub of cmd.commands) {

package/package.json

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