jaz-clio 4.20.0 → 4.21.2

package/README.md

@@ -128,7 +128,7 @@ Every command supports `--json` for structured output — ideal for piping to ot
 
 ## MCP Server
 
-Expose all 145 CLI tools to AI coding assistants via the [Model Context Protocol](https://modelcontextprotocol.io). The server runs locally on your machine — no cloud, no ports. API calls go directly from your machine to the Jaz API.
+Expose all 146 CLI tools to AI coding assistants via the [Model Context Protocol](https://modelcontextprotocol.io). The server runs locally on your machine — no cloud, no ports. API calls go directly from your machine to the Jaz API.
 
 **Claude Code:**
 
@@ -167,20 +167,17 @@ clio init --platform claude            # Force a specific platform
 
 See the [full README](https://github.com/teamtinvio/jaz-ai) for skill details, reference file catalogs, and plugin installation.
 
-## Common API Gotchas
+## Privacy & Security
 
-Mistakes the CLI and skills prevent:
+Jaz AI runs entirely on your machine. API calls go directly from your machine to the Jaz API over HTTPS. This tool does not include telemetry or collect data. Your API key is stored locally in `~/.config/jaz-clio/credentials.json`.
 
-| Gotcha | Wrong | Right |
-|--------|-------|-------|
-| Auth header | `Authorization: Bearer ...` | `x-jk-api-key: ...` |
-| ID field | `id` | `resourceId` |
-| Date field | `issueDate`, `date` | `valueDate` |
-| FX currency | `currencyCode: "USD"` | `currency: { sourceCurrency: "USD" }` |
-| Org endpoint | `{ data: [...] }` | `{ data: { ... } }` (single object) |
-| Payments | `[{ ... }]` | `{ payments: [{ ... }] }` (wrapped) |
-| CN Refunds | `{ payments: [{ paymentAmount }] }` | `{ refunds: [{ refundAmount }] }` |
-| Apply credits | `{ amount: 100 }` | `{ credits: [{ creditNoteResourceId, amountApplied }] }` |
+See our full privacy policy: [jaz.ai/legal](https://jaz.ai/legal)
+
+## Support
+
+- Help center: [help.jaz.ai](https://help.jaz.ai)
+- GitHub Issues: [github.com/teamtinvio/jaz-ai/issues](https://github.com/teamtinvio/jaz-ai/issues)
+- Email: api-support@jaz.ai
 
 ## License
 

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 4.20.0
+version: 4.21.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.
@@ -77,8 +77,8 @@ You are working with the **Jaz REST API** — the accounting platform backend. A
 31. **Cash transfers use `cashOut`/`cashIn` sub-objects** — NOT flat `fromAccountResourceId`/`toAccountResourceId`. Each: `{ accountResourceId, amount }`.
 
 ### Schedulers
-32. **Scheduled invoices/bills wrap in `{ invoice: {...} }` or `{ bill: {...} }`** — not flat. Recurrence field is `repeat` (NOT `frequency`/`interval`). `saveAsDraft: false` required.
-33. **Scheduled journals use FLAT structure** with `schedulerEntries` — not nested in `journal` wrapper.
+32. **Scheduled invoices/bills wrap in `{ invoice: {...} }` or `{ bill: {...} }`** — not flat. Recurrence field is `repeat` (NOT `frequency`/`interval`). `saveAsDraft: false` required. **`reference` is required** inside the `invoice`/`bill` wrapper — omitting it causes 422.
+33. **Scheduled journals use FLAT structure** with `schedulerEntries` — not nested in `journal` wrapper. **`valueDate` is required** at the top level (alongside `startDate`, `repeat`, etc.).
 
 ### Bookmarks
 34. **Bookmarks use `items` array wrapper** with `name`, `value`, `categoryCode`, `datatypeCode`.
@@ -113,11 +113,11 @@ You are working with the **Jaz REST API** — the accounting platform backend. A
 41. **Invoice GET uses `organizationAccountResourceId`** for line item accounts — POST uses `accountResourceId`. Request-side aliases resolve `issueDate` → `valueDate`, `bankAccountResourceId` → `accountResourceId`, etc.
 42. **Scheduler GET returns `interval`** — POST uses `repeat`. (Response-side asymmetry remains.)
 43. **Search sort is an object** — `{ sort: { sortBy: ["valueDate"], order: "DESC" } }`. Required when `offset` is present (even `offset: 0`).
-44. **Bank records: two import methods** — Multipart CSV/OFX via `POST /magic/importBankStatementFromAttachment` (camelCase fields: `sourceFile`, `accountResourceId`, `businessTransactionType: "BANK_STATEMENT"`, `sourceType: "FILE"` — same camelCase rule as rule 59). JSON via `POST /bank-records/:accountResourceId` with `{ records: [{description, netAmount, valueDate, ...}] }`.
+44. **Bank records** — **Create**: Multipart CSV/OFX via `POST /magic/importBankStatementFromAttachment` or JSON via `POST /bank-records/:accountResourceId` with `{ records: [{amount, transactionDate, description?, payerOrPayee?, reference?}] }` (positive = cash-in, negative = cash-out, response: `{data: {errors: []}}`). **Search**: `POST /bank-records/:accountResourceId/search` — filter fields: `valueDate` (DateExpression), `status` (StringExpression: UNRECONCILED, RECONCILED, ARCHIVED, POSSIBLE_DUPLICATE), `description`, `extContactName` (payer/payee), `extReference`, `netAmount` (BigDecimalExpression), `extAccountNumber`. Sort by `valueDate` DESC default.
 45. **Withholding tax** on bills/supplier CNs only. Retry pattern: if `WITHHOLDING_CODE_NOT_FOUND`, strip field and retry.
 46. **Known API bugs (500s)**: Contact groups PUT, custom fields PUT, capsules POST, catalogs POST, inventory balances GET — all return 500.
 47. **Non-existent endpoints**: `POST /deposits`, `POST /inventory/adjustments`, `GET /payments` (list), and `POST /payments/search` return 404 — these endpoints are not implemented. To list/search payments, use `POST /cashflow-transactions/search` (the unified transaction ledger — see Rule 63).
-48. **Attachments require PDF/PNG**: `POST /:type/:id/attachments` uses multipart `file` field but rejects `text/plain`. Use `application/pdf` or `image/png`.
+48. **Attachments require multipart `file` field**: `POST /:type/:id/attachments` expects a binary file in the `file` form-data field — NOT a `sourceUrl` text field. Rejects `text/plain`. Use `application/pdf` or `image/png`. CLI: `clio attachments add --file <path>` (local file) or `--url <url>` (downloads first, then uploads as `file`).
 49. **Currency rate direction: `rate` = functionalToSource (1 base = X foreign)** — POST `rate: 0.74` for a SGD org means 1 SGD = 0.74 USD. **If your data stores rates as "1 USD = 1.35 SGD" (sourceToFunctional), you MUST invert: `rate = 1 / 1.35 = 0.74`.** GET confirms both: `rateFunctionalToSource` (what you POSTed) and `rateSourceToFunctional` (the inverse).
 
 ### Search & Filter
@@ -269,6 +269,7 @@ The backend DX overhaul is live. Key improvements now available:
 - **Field names**: All request bodies use camelCase
 - **Date serialization**: Python `date` type → `YYYY-MM-DD` strings
 - **Bill payments**: Embed in bill creation body (safest). Standalone `POST /bills/{id}/payments` also works.
-- **Bank records**: Use multipart `POST /magic/importBankStatementFromAttachment`
-- **Scheduled bills**: Wrap as `{ status, startDate, endDate, repeat, bill: {...} }`
+- **Bank records**: Create via JSON `POST /bank-records/:id` or multipart `POST /magic/importBankStatementFromAttachment`. Search via `POST /bank-records/:id/search` with filters (valueDate, status, description, extContactName, netAmount, extReference).
+- **Scheduled invoices/bills**: Wrap as `{ status, startDate, endDate, repeat, invoice/bill: { reference, valueDate, dueDate, contactResourceId, lineItems, saveAsDraft: false } }`. `reference` is required.
+- **Scheduled journals**: Flat: `{ status, startDate, endDate, repeat, valueDate, schedulerEntries, reference }`. `valueDate` is required.
 - **FX currency (invoices, bills, credit notes, AND journals)**: `currency: { sourceCurrency: "USD" }` (auto-fetches platform rate) or `currency: { sourceCurrency: "USD", exchangeRate: 1.35 }` (custom rate). Same object form on all transaction types. **Never use `currencyCode` string** — silently ignored.

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

@@ -322,10 +322,14 @@ if (acct.code) ctx.coaIds[acct.code] = acct.resourceId;
 
 ## Bank Record Errors
 
-### No JSON POST endpoint exists
-There is no JSON POST endpoint for creating bank records. Use multipart import:
+### Bank record creation
 
-**Workaround**: Use multipart import instead:
+Two methods for creating bank records:
+
+**Method 1: JSON POST** (programmatic)
+`POST /api/v1/bank-records/:accountResourceId` with `{ records: [{amount, transactionDate, description?, payerOrPayee?, reference?}] }`. Returns `{ data: { errors: [] } }` on success. 1-100 records per call.
+
+**Method 2: Multipart import** (file upload)
 ```
 POST /api/v1/magic/importBankStatementFromAttachment
 Content-Type: multipart/form-data
@@ -337,12 +341,7 @@ Fields:
   - sourceType: "FILE" (valid values: URL, FILE)
 ```
 
-Production clients use this multipart endpoint exclusively. Multipart import is the more reliable method.
-
-**Legacy guidance** (still valid for general bank record handling):
-1. Always use `Math.abs()` on amounts — amounts must be positive
-2. Use `type: "CREDIT"` or `type: "DEBIT"` to indicate direction
-3. Check that `bankAccountResourceId` is a valid CoA entry with `accountType: "Bank Accounts"`
+**Amount rules**: For JSON POST, positive = cash-in, negative = cash-out. Dates in YYYY-MM-DD format. `accountResourceId` must be a bank-type CoA account.
 
 ---
 

package/assets/skills/api/references/field-map.md

@@ -326,12 +326,20 @@ DELETE → expects "A" (parentEntityResourceId, via /cashflow-journals/:id)
 
 | What You'd Guess | Actual API Field | Notes |
 |------------------|-------------------|-------|
-| `date` | `transactionDate` | ISO date string |
-| `direction` | `type` | `"CREDIT"` or `"DEBIT"` (uppercase) |
+| `date` (create) | `transactionDate` | ISO date string (YYYY-MM-DD) |
+| `date` (search response) | `valueDate` | Returned as ISO 8601 UTC |
+| `amount` (create) | `amount` | Positive = cash-in, negative = cash-out |
+| `amount` (search response) | `netAmount` | Same sign convention |
+| `payer` / `payee` (create) | `payerOrPayee` | Free text |
+| `payer` / `payee` (search) | `extContactName` | Search filter field |
+| `reference` (search) | `extReference` | Search filter field |
 | `memo` | `description` | Free text |
-| (negative amount) | `amount` (positive) + `type` | Always positive, direction via type |
+| `source` | `bankStatementEntrySource` | `FILE_IMPORT` or `API` (read-only) |
+| `status` | `status` | `UNRECONCILED`, `RECONCILED`, `ARCHIVED`, `POSSIBLE_DUPLICATE` |
 
-**Creating bank records**: Use multipart `POST /api/v1/magic/importBankStatementFromAttachment` — the only endpoint for creating bank records. No JSON POST endpoint exists.
+**Creating bank records**: Two methods. JSON POST via `POST /bank-records/:accountResourceId` with `{ records: [{amount, transactionDate, ...}] }` (1-100 records). Multipart via `POST /magic/importBankStatementFromAttachment` for CSV/OFX file uploads.
+
+**Searching bank records**: `POST /bank-records/:accountResourceId/search` with filter fields: `valueDate` (DateExpression), `status` (StringExpression), `description` (StringExpression), `extContactName` (StringExpression), `extReference` (StringExpression), `netAmount` (BigDecimalExpression), `extAccountNumber` (StringExpression). Sort by `valueDate` DESC default.
 
 ---
 
@@ -510,7 +518,7 @@ Battle-tested patterns from production Jaz API clients:
 | Alias generator | `alias_generator=to_camel` (snake_case to camelCase) |
 | Date type | Python `date` type serializes to `YYYY-MM-DD` strings |
 | Bill payments | Always embedded in bill creation body, never standalone |
-| Bank records | Multipart import via `importBankStatementFromAttachment` — the only endpoint |
+| Bank records | JSON POST `/bank-records/:id` or multipart `/magic/importBankStatementFromAttachment`. Search via `/bank-records/:id/search`. |
 | Scheduled bills | Wrapped as `{ repeat, startDate, endDate, bill: {...} }`. Field is `repeat` (NOT `frequency`/`interval`) |
 | FX currency | MUST use `currency` OBJECT on ALL transaction types (invoices, bills, credit notes, journals): `{ sourceCurrency: "USD" }` (auto platform rate) or `{ sourceCurrency: "USD", exchangeRate: 1.35 }` (custom). String `currencyCode` silently ignored. |
 

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 4.20.0
+version: 4.21.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.20.0
+version: 4.21.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.20.0
+version: 4.21.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/attachments.js

@@ -1,7 +1,21 @@
 import chalk from 'chalk';
+import { readFileSync } from 'node:fs';
+import { basename, extname, resolve } from 'node:path';
 import { listAttachments, addAttachment, fetchAttachmentTable } from '../core/api/attachments.js';
 import { apiAction } from './api-action.js';
 const BT_TYPES = ['invoices', 'bills', 'journals', 'scheduled_journals', 'customer-credit-notes', 'supplier-credit-notes'];
+const ATTACHMENT_MIME_MAP = {
+    '.pdf': 'application/pdf',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
+    '.csv': 'text/csv',
+    '.xls': 'application/vnd.ms-excel',
+    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+};
 export function registerAttachmentsCommand(program) {
     const attachments = program
         .command('attachments')
@@ -35,11 +49,12 @@ export function registerAttachmentsCommand(program) {
     // ── clio attachments add ───────────────────────────────────────
     attachments
         .command('add')
-        .description('Add an attachment to a transaction')
+        .description('Add an attachment to a transaction (file upload or URL download)')
         .requiredOption('--type <type>', `Transaction type (${BT_TYPES.join(', ')})`)
         .requiredOption('--id <resourceId>', 'Transaction resourceId')
-        .option('--attachment-id <id>', 'Attachment ID')
-        .option('--url <url>', 'Source file URL')
+        .option('--file <path>', 'Local file path (PDF, PNG, JPG, etc.)')
+        .option('--url <url>', 'Download file from URL and attach')
+        .option('--attachment-id <id>', 'Link existing attachment by ID')
         .option('--api-key <key>', 'API key')
         .option('--json', 'Output as JSON')
         .action(apiAction(async (client, opts) => {
@@ -48,15 +63,41 @@ export function registerAttachmentsCommand(program) {
             console.error(chalk.red(`Invalid type. Use one of: ${BT_TYPES.join(', ')}`));
             process.exit(1);
         }
-        if (!opts.attachmentId && !opts.url) {
-            console.error(chalk.red('Provide --attachment-id or --url'));
+        if (!opts.attachmentId && !opts.url && !opts.file) {
+            console.error(chalk.red('Provide --file, --url, or --attachment-id'));
             process.exit(1);
         }
+        let file;
+        let fileName;
+        if (opts.file) {
+            // Local file upload
+            const filePath = resolve(opts.file);
+            const ext = extname(filePath).toLowerCase();
+            const mime = ATTACHMENT_MIME_MAP[ext] ?? 'application/octet-stream';
+            const buffer = readFileSync(filePath);
+            file = new Blob([buffer], { type: mime });
+            fileName = basename(filePath);
+        }
+        else if (opts.url) {
+            // Download from URL, then upload as file
+            const res = await fetch(opts.url);
+            if (!res.ok) {
+                console.error(chalk.red(`Failed to download: ${res.status} ${res.statusText}`));
+                process.exit(1);
+            }
+            const buffer = await res.arrayBuffer();
+            const contentType = res.headers.get('content-type') ?? 'application/octet-stream';
+            file = new Blob([buffer], { type: contentType });
+            // Extract filename from URL path
+            const urlPath = new URL(opts.url).pathname;
+            fileName = basename(urlPath) || 'attachment';
+        }
         const result = await addAttachment(client, {
             businessTransactionType: btType,
             businessTransactionResourceId: opts.id,
+            file,
+            fileName,
             attachmentId: opts.attachmentId,
-            sourceUrl: opts.url,
         });
         if (opts.json) {
             console.log(JSON.stringify(result, null, 2));

package/dist/commands/bank.js

@@ -1,7 +1,8 @@
 import chalk from 'chalk';
 import { readFileSync } from 'node:fs';
 import { basename, extname, resolve } from 'node:path';
-import { listBankAccounts, getBankAccount, searchBankRecords, importBankStatement, } from '../core/api/bank.js';
+import { listBankAccounts, getBankAccount, searchBankRecords, addBankRecords, importBankStatement, } from '../core/api/bank.js';
+import { buildBankRecordFilter } from '../core/registry/pagination.js';
 import { apiAction } from './api-action.js';
 import { parsePositiveInt } from './parsers.js';
 const BANK_MIME_MAP = {
@@ -61,27 +62,31 @@ export function registerBankCommand(program) {
         .description('Search bank records for a bank account')
         .option('--from <YYYY-MM-DD>', 'Filter from date (inclusive)')
         .option('--to <YYYY-MM-DD>', 'Filter to date (inclusive)')
-        .option('--status <status>', 'Filter by status (UNRECONCILED, RECONCILED)')
+        .option('--status <status>', 'Filter by status (UNRECONCILED, RECONCILED, ARCHIVED, POSSIBLE_DUPLICATE)')
+        .option('--description <text>', 'Filter by description (contains)')
+        .option('--payer <name>', 'Filter by payer/payee name (contains)')
+        .option('--reference <ref>', 'Filter by reference (contains)')
+        .option('--amount-min <n>', 'Filter by minimum amount', parseFloat)
+        .option('--amount-max <n>', 'Filter by maximum amount', parseFloat)
         .option('--limit <n>', 'Max results (default 50)', parsePositiveInt)
         .option('--api-key <key>', 'API key (overrides stored/env)')
         .option('--json', 'Output as JSON')
         .action((accountResourceId, opts) => apiAction(async (client) => {
-        const filter = {};
-        if (opts.status)
-            filter.status = { eq: opts.status };
-        if (opts.from || opts.to) {
-            const dateFilter = {};
-            if (opts.from)
-                dateFilter.gte = opts.from;
-            if (opts.to)
-                dateFilter.lte = opts.to;
-            filter.date = dateFilter;
-        }
+        const filter = buildBankRecordFilter({
+            status: opts.status,
+            from: opts.from,
+            to: opts.to,
+            description: opts.description,
+            payer: opts.payer,
+            reference: opts.reference,
+            amountMin: opts.amountMin,
+            amountMax: opts.amountMax,
+        });
         const res = await searchBankRecords(client, accountResourceId, {
-            filter: Object.keys(filter).length > 0 ? filter : undefined,
+            filter,
             limit: opts.limit ?? 50,
             offset: 0,
-            sort: { sortBy: ['date'], order: 'DESC' },
+            sort: { sortBy: ['valueDate'], order: 'DESC' },
         });
         if (opts.json) {
             console.log(JSON.stringify(res, null, 2));
@@ -93,10 +98,49 @@ export function registerBankCommand(program) {
             }
             console.log(chalk.bold(`Bank Records (${res.data.length} of ${res.totalElements}):\n`));
             for (const r of res.data) {
-                const amount = r.amount >= 0
-                    ? chalk.green(`+${r.amount.toFixed(2)}`)
-                    : chalk.red(r.amount.toFixed(2));
-                console.log(`  ${chalk.cyan(r.resourceId)}  ${r.date}  ${amount}  ${r.description}  ${chalk.dim(r.status)}`);
+                const net = typeof r.netAmount === 'number' && Number.isFinite(r.netAmount) ? r.netAmount : 0;
+                const amount = net >= 0
+                    ? chalk.green(`+${net.toFixed(2)}`)
+                    : chalk.red(net.toFixed(2));
+                const payer = r.extContactName ? `  ${chalk.yellow(r.extContactName)}` : '';
+                console.log(`  ${chalk.cyan(r.resourceId)}  ${r.valueDate}  ${amount}  ${r.description ?? ''}${payer}  ${chalk.dim(r.status)}`);
+            }
+        }
+    })(opts));
+    // ── clio bank add-records ──────────────────────────────────────
+    bank
+        .command('add-records <accountResourceId>')
+        .description('Add bank records via JSON (1-100 records per call)')
+        .requiredOption('--records <json>', 'JSON array: [{amount, transactionDate, description?, payerOrPayee?, reference?}]')
+        .option('--api-key <key>', 'API key (overrides stored/env)')
+        .option('--json', 'Output as JSON')
+        .action((accountResourceId, opts) => apiAction(async (client) => {
+        const parsed = JSON.parse(opts.records);
+        if (!Array.isArray(parsed))
+            throw new Error('--records must be a JSON array');
+        if (parsed.length < 1 || parsed.length > 100)
+            throw new Error('--records must contain 1-100 entries');
+        for (const [i, r] of parsed.entries()) {
+            if (typeof r !== 'object' || r === null)
+                throw new Error(`records[${i}] must be an object`);
+            if (typeof r.amount !== 'number' || !Number.isFinite(r.amount))
+                throw new Error(`records[${i}].amount must be a finite number`);
+            if (typeof r.transactionDate !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(r.transactionDate))
+                throw new Error(`records[${i}].transactionDate must be YYYY-MM-DD`);
+        }
+        const res = await addBankRecords(client, accountResourceId, parsed);
+        const errors = Array.isArray(res?.data?.errors) ? res.data.errors : [];
+        if (opts.json) {
+            console.log(JSON.stringify(res.data, null, 2));
+        }
+        else {
+            if (errors.length > 0) {
+                console.log(chalk.red(`${errors.length} error(s):`));
+                for (const e of errors)
+                    console.log(`  ${chalk.red(String(e))}`);
+            }
+            else {
+                console.log(chalk.green(`Created ${parsed.length} bank record(s).`));
             }
         }
     })(opts));

package/dist/commands/exports.js

@@ -28,7 +28,7 @@ export function registerExportsCommand(program) {
             params.startDate = opts.startDate;
         if (opts.endDate) {
             // Point-in-time exports (balance-sheet, trial-balance) use snapshotDate, not endDate
-            const pointInTime = ['balance-sheet', 'trial-balance'];
+            const pointInTime = ['balance-sheet'];
             if (pointInTime.includes(exportType)) {
                 params.snapshotDate = opts.endDate;
             }

package/dist/commands/schedulers.js

@@ -113,6 +113,7 @@ export function registerSchedulersCommand(program) {
                 { flag: '--start-date', key: 'startDate' },
                 { flag: '--repeat', key: 'repeat' },
                 { flag: '--contact', key: 'contact' },
+                { flag: '--reference', key: 'reference' },
                 { flag: '--value-date', key: 'valueDate' },
                 { flag: '--due-date', key: 'dueDate' },
                 { flag: '--line-items', key: 'lineItems' },
@@ -170,6 +171,7 @@ export function registerSchedulersCommand(program) {
                 { flag: '--start-date', key: 'startDate' },
                 { flag: '--repeat', key: 'repeat' },
                 { flag: '--contact', key: 'contact' },
+                { flag: '--reference', key: 'reference' },
                 { flag: '--value-date', key: 'valueDate' },
                 { flag: '--due-date', key: 'dueDate' },
                 { flag: '--line-items', key: 'lineItems' },
@@ -224,6 +226,7 @@ export function registerSchedulersCommand(program) {
             requireFields(opts, [
                 { flag: '--start-date', key: 'startDate' },
                 { flag: '--repeat', key: 'repeat' },
+                { flag: '--value-date', key: 'valueDate' },
                 { flag: '--entries', key: 'entries' },
             ]);
             // eslint-disable-next-line @typescript-eslint/no-explicit-any -- user-provided JSON, API validates
@@ -233,6 +236,7 @@ export function registerSchedulersCommand(program) {
                 startDate: opts.startDate,
                 endDate: opts.endDate,
                 repeat: opts.repeat,
+                valueDate: opts.valueDate,
                 schedulerEntries,
                 reference: opts.reference,
                 notes: opts.notes,

package/dist/core/api/attachments.js

@@ -8,10 +8,10 @@ export async function listAttachments(client, btType, btResourceId) {
 export async function addAttachment(client, data) {
     const { businessTransactionType: btType, businessTransactionResourceId: btId, ...rest } = data;
     const formData = new FormData();
+    if (rest.file)
+        formData.append('file', rest.file, rest.fileName ?? 'file');
     if (rest.attachmentId)
         formData.append('attachmentId', rest.attachmentId);
-    if (rest.sourceUrl)
-        formData.append('sourceUrl', rest.sourceUrl);
     return client.postMultipart(`/api/v1/${btType}/${btId}/attachments`, formData);
 }
 /**

package/dist/core/api/bank.js

@@ -16,6 +16,12 @@ export async function getBankAccount(client, resourceId) {
 export async function searchBankRecords(client, accountResourceId, params) {
     return client.post(`/api/v1/bank-records/${accountResourceId}/search`, params);
 }
+export async function addBankRecords(client, accountResourceId, records) {
+    return client.post(`/api/v1/bank-records/${accountResourceId}`, {
+        accountResourceId,
+        records,
+    });
+}
 export async function importBankStatement(client, data) {
     const formData = new FormData();
     formData.append('businessTransactionType', data.businessTransactionType);

package/dist/core/jobs/bank-recon/tools/match/match.js

@@ -8,8 +8,8 @@
  *   0. Normalize & index (integer cents, day offsets, text normalization)
  *   1. Exact 1:1 hash join (amount + contact + date)
  *   2. Fuzzy 1:1 greedy assignment (tolerance + scoring)
- *   3. N:1 subset-sum (multiple txns → one bank record)
- *   4. 1:N reverse subset-sum (multiple bank records → one txn)
+ *   3. N:1 subset-sum (multiple txns → one bank record, same-contact constraint)
+ *   4. 1:N reverse subset-sum (multiple bank records → one txn, no contact constraint)
  *   5. N:M two-set matching (within contact groups)
  *
  * Performance: <50ms for 500 records × 2000 transactions.
@@ -231,7 +231,7 @@ export function matchBankRecords(input) {
     let phase3Count = 0;
     for (const ri of [...recordPool]) {
         const r = records[ri];
-        // Gather same-sign candidates within date window
+        // Gather same-sign candidates within date window (enriched with contactNorm)
         const candidates = [];
         for (const ti of txnPool) {
             const t = txns[ti];
@@ -239,47 +239,54 @@ export function matchBankRecords(input) {
                 continue;
             if (Math.abs(r.day - t.day) > dateWindowDays)
                 continue;
-            candidates.push({ ti, cents: t.cents });
+            candidates.push({ ti, cents: t.cents, contactNorm: t.contactNorm });
         }
         if (candidates.length < 2)
             continue;
-        // DFS operates on absolute values (same-sign filter guarantees all same direction)
-        // Sort descending by |cents| for DFS pruning
-        candidates.sort((a, b) => Math.abs(b.cents) - Math.abs(a.cents));
-        // Build SubsetCandidate array with absolute cents (sign already filtered)
-        const subCandidates = candidates.map((c, i) => ({
-            index: i,
-            cents: Math.abs(c.cents),
-        }));
-        // Compute effective tolerance
-        const isFxRecord = r.isFx || candidates.some(c => txns[c.ti].isFx);
-        const effectiveTolCents = isFxRecord
-            ? Math.max(toleranceCents, Math.round(Math.abs(r.cents) * fxTolerancePct))
-            : toleranceCents;
-        const subsets = subsetSumDFS(subCandidates, Math.abs(r.cents), effectiveTolCents, maxK, findAll, dfsNodes);
-        if (subsets.length === 0)
-            continue;
-        // Pick best subset: fewest items, then highest composite score
-        let bestSubset = subsets[0];
-        let bestScore = -1;
-        for (const ss of subsets) {
-            const matchedTxns = ss.indices.map(i => txns[candidates[i].ti]);
-            const textSig = groupTextScore(r.contact, r.reference, r.description, matchedTxns.map(t => ({ contact: t.contact, reference: t.reference })));
-            const minDaysDiff = Math.min(...ss.indices.map(i => Math.abs(r.day - txns[candidates[i].ti].day)));
-            const dateSig = dateScore(minDaysDiff);
-            const typeSig = typeScore('N:1', ss.indices.length);
-            let score = compositeScore(textSig, dateSig, typeSig);
-            if (isFxRecord)
-                score = Math.max(0, score - FX_PENALTY);
-            // Prefer: smaller subset, then higher score
-            const rank = -ss.indices.length * 1000 + score * 100;
-            if (subsets.length === 1 || rank > bestScore || (rank === bestScore && ss.indices.length < bestSubset.indices.length)) {
-                bestSubset = ss;
-                bestScore = rank;
+        // Group by contact — all txns in a subset must share the same contact
+        const contactCandidateGroups = groupByContact(candidates);
+        let bestSubset = null;
+        let bestGroup = [];
+        let bestIsFx = false;
+        let bestRank = -Infinity;
+        let bestSignals = { text: 0, date: 0, type: 0, score: 0 };
+        for (const groupCandidates of contactCandidateGroups.values()) {
+            if (groupCandidates.length < 2)
+                continue;
+            // Sort descending by |cents| for DFS pruning
+            groupCandidates.sort((a, b) => Math.abs(b.cents) - Math.abs(a.cents));
+            const subCandidates = groupCandidates.map((c, i) => ({
+                index: i,
+                cents: Math.abs(c.cents),
+            }));
+            const isFxGroup = r.isFx || groupCandidates.some(c => txns[c.ti].isFx);
+            const effectiveTolCents = isFxGroup
+                ? Math.max(toleranceCents, Math.round(Math.abs(r.cents) * fxTolerancePct))
+                : toleranceCents;
+            const subsets = subsetSumDFS(subCandidates, Math.abs(r.cents), effectiveTolCents, maxK, findAll, dfsNodes);
+            for (const ss of subsets) {
+                const matchedTxns = ss.indices.map(i => txns[groupCandidates[i].ti]);
+                const textSig = groupTextScore(r.contact, r.reference, r.description, matchedTxns.map(t => ({ contact: t.contact, reference: t.reference })));
+                const minDaysDiff = Math.min(...ss.indices.map(i => Math.abs(r.day - txns[groupCandidates[i].ti].day)));
+                const dateSig = dateScore(minDaysDiff);
+                const typeSig = typeScore('N:1', ss.indices.length);
+                let score = compositeScore(textSig, dateSig, typeSig);
+                if (isFxGroup)
+                    score = Math.max(0, score - FX_PENALTY);
+                // Rank: prefer fewer items, then higher score, then deterministic tiebreak
+                const rank = -ss.indices.length * 1000 + score * 100;
+                if (rank > bestRank || (rank === bestRank && score > bestSignals.score)) {
+                    bestSubset = ss;
+                    bestGroup = groupCandidates;
+                    bestIsFx = isFxGroup;
+                    bestRank = rank;
+                    bestSignals = { text: textSig, date: dateSig, type: typeSig, score };
+                }
             }
         }
-        // Commit the best subset
-        const matchedTxnIndices = bestSubset.indices.map(i => candidates[i].ti);
+        if (!bestSubset)
+            continue;
+        const matchedTxnIndices = bestSubset.indices.map(i => bestGroup[i].ti);
         // Verify none already consumed
         if (matchedTxnIndices.some(ti => !txnPool.has(ti)))
             continue;
@@ -287,28 +294,21 @@ export function matchBankRecords(input) {
         for (const ti of matchedTxnIndices)
             txnPool.delete(ti);
         const matchedTxns = matchedTxnIndices.map(ti => txns[ti]);
-        const textSig = groupTextScore(r.contact, r.reference, r.description, matchedTxns.map(t => ({ contact: t.contact, reference: t.reference })));
-        const minDaysDiff = Math.min(...matchedTxns.map(t => Math.abs(r.day - t.day)));
-        const dateSig = dateScore(minDaysDiff);
-        const typeSig = typeScore('N:1', matchedTxns.length);
-        let score = compositeScore(textSig, dateSig, typeSig);
-        if (isFxRecord)
-            score = Math.max(0, score - FX_PENALTY);
-        const confidence = scoreToConfidence(score);
+        const confidence = scoreToConfidence(bestSignals.score);
         const txnTotal = round2(matchedTxns.reduce((s, t) => s + t.signedAmount, 0));
         const proposal = {
             matchType: 'N:1',
             confidence,
-            score: round2Sig(score),
+            score: round2Sig(bestSignals.score),
             bankRecords: [{ id: r.id, amount: r.originalAmount, date: r.date }],
             transactions: matchedTxns.map(t => ({ id: t.id, amount: t.originalAmount, date: t.date })),
             bankTotal: r.originalAmount,
             transactionTotal: txnTotal,
             variance: round2(r.originalAmount - txnTotal),
-            signals: { text: round2Sig(textSig), date: round2Sig(dateSig), type: round2Sig(typeSig) },
+            signals: { text: round2Sig(bestSignals.text), date: round2Sig(bestSignals.date), type: round2Sig(bestSignals.type) },
             reason: `${matchedTxns.length} transactions sum to bank record amount (${confidence} confidence)`,
         };
-        if (isFxRecord) {
+        if (bestIsFx) {
             proposal.fxVariance = round2(fromCents(Math.abs(r.cents - bestSubset.sum)));
         }
         matches.push(proposal);
@@ -321,6 +321,9 @@ export function matchBankRecords(input) {
     let phase4Count = 0;
     for (const ti of [...txnPool]) {
         const t = txns[ti];
+        // Gather same-sign candidates within date window
+        // Note: NO contact grouping here — bank record payer/payee is metadata,
+        // so different bank records can legitimately have different contacts.
         const candidates = [];
         for (const ri of recordPool) {
             const r = records[ri];
@@ -333,7 +336,6 @@ export function matchBankRecords(input) {
         if (candidates.length < 2)
             continue;
         candidates.sort((a, b) => Math.abs(b.cents) - Math.abs(a.cents));
-        // DFS operates on absolute values (same-sign filter guarantees all same direction)
         const subCandidates = candidates.map((c, i) => ({
             index: i,
             cents: Math.abs(c.cents),
@@ -345,11 +347,25 @@ export function matchBankRecords(input) {
         const subsets = subsetSumDFS(subCandidates, Math.abs(t.cents), effectiveTolCents, maxK, findAll, dfsNodes);
         if (subsets.length === 0)
             continue;
-        // Pick best: fewest items
+        // Pick best: fewer items + higher composite score (matches Phase 3 ranking)
         let bestSubset = subsets[0];
+        let bestRank = -Infinity;
+        let bestSignals = { text: 0, date: 0, type: 0, score: 0 };
         for (const ss of subsets) {
-            if (ss.indices.length < bestSubset.indices.length)
+            const matchedRecords = ss.indices.map(i => records[candidates[i].ri]);
+            const textSig = Math.max(...matchedRecords.map(r => crossFieldTextScore(r.contact, r.reference, r.description, t.contact, t.reference)));
+            const minDaysDiff = Math.min(...matchedRecords.map(r => Math.abs(r.day - t.day)));
+            const dateSig = dateScore(minDaysDiff);
+            const typeSig = typeScore('1:N', ss.indices.length);
+            let score = compositeScore(textSig, dateSig, typeSig);
+            if (isFxTxn)
+                score = Math.max(0, score - FX_PENALTY);
+            const rank = -ss.indices.length * 1000 + score * 100;
+            if (rank > bestRank || (rank === bestRank && score > bestSignals.score)) {
                 bestSubset = ss;
+                bestRank = rank;
+                bestSignals = { text: textSig, date: dateSig, type: typeSig, score };
+            }
         }
         const matchedRecordIndices = bestSubset.indices.map(i => candidates[i].ri);
         if (matchedRecordIndices.some(ri => !recordPool.has(ri)))
@@ -358,25 +374,18 @@ export function matchBankRecords(input) {
         for (const ri of matchedRecordIndices)
             recordPool.delete(ri);
         const matchedRecords = matchedRecordIndices.map(ri => records[ri]);
-        const textSig = Math.max(...matchedRecords.map(r => crossFieldTextScore(r.contact, r.reference, r.description, t.contact, t.reference)));
-        const minDaysDiff = Math.min(...matchedRecords.map(r => Math.abs(r.day - t.day)));
-        const dateSig = dateScore(minDaysDiff);
-        const typeSig = typeScore('1:N', matchedRecords.length);
-        let score = compositeScore(textSig, dateSig, typeSig);
-        if (isFxTxn)
-            score = Math.max(0, score - FX_PENALTY);
-        const confidence = scoreToConfidence(score);
+        const confidence = scoreToConfidence(bestSignals.score);
         const bankTotal = round2(matchedRecords.reduce((s, r) => s + r.originalAmount, 0));
         const proposal = {
             matchType: '1:N',
             confidence,
-            score: round2Sig(score),
+            score: round2Sig(bestSignals.score),
             bankRecords: matchedRecords.map(r => ({ id: r.id, amount: r.originalAmount, date: r.date })),
             transactions: [{ id: t.id, amount: t.originalAmount, date: t.date }],
             bankTotal,
             transactionTotal: t.signedAmount,
             variance: round2(bankTotal - t.signedAmount),
-            signals: { text: round2Sig(textSig), date: round2Sig(dateSig), type: round2Sig(typeSig) },
+            signals: { text: round2Sig(bestSignals.text), date: round2Sig(bestSignals.date), type: round2Sig(bestSignals.type) },
             reason: `${matchedRecords.length} bank records sum to transaction amount (${confidence} confidence)`,
         };
         if (isFxTxn) {
@@ -569,6 +578,20 @@ export function matchBankRecords(input) {
 function round2Sig(n) {
     return Math.round(n * 100) / 100;
 }
+/** Group candidates by contactNorm for same-contact subset constraint (Phase 3 + 4). */
+function groupByContact(candidates) {
+    const groups = new Map();
+    for (const c of candidates) {
+        const key = c.contactNorm || '';
+        let g = groups.get(key);
+        if (!g) {
+            g = [];
+            groups.set(key, g);
+        }
+        g.push(c);
+    }
+    return groups;
+}
 /** Build human-readable reason for a fuzzy 1:1 match. */
 function buildReason(matchType, confidence, p) {
     const parts = [];

package/dist/core/registry/pagination.js

@@ -52,3 +52,36 @@ export function buildCnFilter(input) {
         f.contactResourceId = { eq: input.contactResourceId };
     return Object.keys(f).length > 0 ? f : undefined;
 }
+/** Build a bank record search filter (shared by CLI + MCP tool). */
+export function buildBankRecordFilter(input) {
+    const f = {};
+    if (input.status)
+        f.status = { eq: input.status };
+    if (input.description)
+        f.description = { contains: input.description };
+    if (input.payer)
+        f.extContactName = { contains: input.payer };
+    if (input.reference)
+        f.extReference = { contains: input.reference };
+    // Date range → valueDate expression
+    if (input.from || input.to) {
+        const d = {};
+        if (input.from)
+            d.gte = input.from;
+        if (input.to)
+            d.lte = input.to;
+        f.valueDate = d;
+    }
+    // Amount range → netAmount expression (guard against NaN/Infinity)
+    const min = typeof input.amountMin === 'number' && Number.isFinite(input.amountMin) ? input.amountMin : undefined;
+    const max = typeof input.amountMax === 'number' && Number.isFinite(input.amountMax) ? input.amountMax : undefined;
+    if (min != null || max != null) {
+        const a = {};
+        if (min != null)
+            a.gte = min;
+        if (max != null)
+            a.lte = max;
+        f.netAmount = a;
+    }
+    return Object.keys(f).length > 0 ? f : undefined;
+}

package/dist/core/registry/tools.js

@@ -5,7 +5,7 @@ import { listInvoices, searchInvoices, getInvoice, createInvoice, updateInvoice,
 import { listBills, searchBills, getBill, createBill, updateBill, deleteBill, createBillPayment, createScheduledBill, finalizeBill, applyCreditsToBill, } from '../api/bills.js';
 import { listJournals, searchJournals, getJournal, createJournal, deleteJournal, updateJournal, createScheduledJournal, } from '../api/journals.js';
 import { generateTrialBalance, generateBalanceSheet, generateProfitAndLoss, generateCashflow, generateArSummary, generateApSummary, generateCashBalance, generateGeneralLedger, } from '../api/reports.js';
-import { listBankAccounts, importBankStatement } from '../api/bank.js';
+import { listBankAccounts, addBankRecords, importBankStatement } from '../api/bank.js';
 import { listItems, searchItems, getItem, createItem, updateItem, deleteItem, } from '../api/items.js';
 import { listTags, searchTags, createTag, deleteTag, } from '../api/tags.js';
 import { listCapsuleTypes, listCapsules, searchCapsules, getCapsule, createCapsule, updateCapsule, deleteCapsule, } from '../api/capsules.js';
@@ -29,7 +29,7 @@ import { downloadExport } from '../api/data-exports.js';
 import { listAttachments, addAttachment, fetchAttachmentTable } from '../api/attachments.js';
 import { createFromAttachment, searchMagicWorkflows } from '../api/magic.js';
 import { messageToPdf } from '../api/message-pdf.js';
-import { handlePaginationMode, buildCnFilter } from './pagination.js';
+import { handlePaginationMode, buildCnFilter, buildBankRecordFilter } from './pagination.js';
 // Job blueprints (offline — no API calls)
 import { generateMonthEndBlueprint } from '../jobs/month-end/blueprint.js';
 import { generateQuarterEndBlueprint } from '../jobs/quarter-end/blueprint.js';
@@ -1625,9 +1625,17 @@ export const TOOL_DEFINITIONS = [
     },
     {
         name: 'search_bank_records',
-        description: 'Search bank records (imported bank transactions) for a specific account.',
+        description: 'Search bank records (imported bank transactions) for a specific account. Supports filtering by status, date range, description, payer/payee, reference, and amount range.',
         params: {
             accountResourceId: { type: 'string', description: 'Bank account resourceId' },
+            status: { type: 'string', enum: ['UNRECONCILED', 'RECONCILED', 'ARCHIVED', 'POSSIBLE_DUPLICATE'], description: 'Filter by reconciliation status' },
+            from: { type: 'string', description: 'Filter from date inclusive (YYYY-MM-DD)' },
+            to: { type: 'string', description: 'Filter to date inclusive (YYYY-MM-DD)' },
+            description: { type: 'string', description: 'Filter by description (contains)' },
+            payer: { type: 'string', description: 'Filter by payer/payee name (contains)' },
+            reference: { type: 'string', description: 'Filter by reference (contains)' },
+            amountMin: { type: 'number', description: 'Filter by minimum amount (inclusive)' },
+            amountMax: { type: 'number', description: 'Filter by maximum amount (inclusive)' },
             ...SEARCH_PARAMS,
         },
         required: ['accountResourceId'],
@@ -1636,8 +1644,9 @@ export const TOOL_DEFINITIONS = [
         execute: async (ctx, input) => {
             const { mode, limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
             return handlePaginationMode(mode, (off, lim) => searchBankRecords(ctx.client, input.accountResourceId, {
+                filter: buildBankRecordFilter(input),
                 limit: lim, offset: off,
-                sort: { sortBy: [sortBy ?? 'date'], order: (sortOrder ?? 'DESC') },
+                sort: { sortBy: [sortBy ?? 'valueDate'], order: (sortOrder ?? 'DESC') },
             }), limit, offset, 100);
         },
     },
@@ -2038,7 +2047,7 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
             },
             notes: { type: 'string', description: 'Journal notes' },
         },
-        required: ['startDate', 'repeat', 'schedulerEntries'],
+        required: ['startDate', 'repeat', 'valueDate', 'schedulerEntries'],
         group: 'schedulers',
         readOnly: false,
         execute: async (ctx, input) => createScheduledJournal(ctx.client, {
@@ -2046,6 +2055,7 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
             startDate: input.startDate,
             endDate: input.endDate,
             repeat: input.repeat,
+            valueDate: input.valueDate,
             schedulerEntries: input.schedulerEntries,
             reference: input.reference,
             notes: input.notes,
@@ -2081,7 +2091,7 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
             },
             tag: { type: 'string', description: 'Tag name' },
         },
-        required: ['startDate', 'repeat', 'contactResourceId', 'valueDate', 'dueDate', 'lineItems'],
+        required: ['startDate', 'repeat', 'contactResourceId', 'reference', 'valueDate', 'dueDate', 'lineItems'],
         group: 'schedulers',
         readOnly: false,
         execute: async (ctx, input) => createScheduledInvoice(ctx.client, {
@@ -2130,7 +2140,7 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
             },
             tag: { type: 'string', description: 'Tag name' },
         },
-        required: ['startDate', 'repeat', 'contactResourceId', 'valueDate', 'dueDate', 'lineItems'],
+        required: ['startDate', 'repeat', 'contactResourceId', 'reference', 'valueDate', 'dueDate', 'lineItems'],
         group: 'schedulers',
         readOnly: false,
         execute: async (ctx, input) => createScheduledBill(ctx.client, {
@@ -2209,6 +2219,36 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
             });
         },
     },
+    // ── Bank Records: JSON POST ──────────────────────────────────
+    {
+        name: 'add_bank_records',
+        description: 'Create bank statement entries via JSON POST (1-100 records per call). For CSV/OFX file imports, use import_bank_statement instead.\n\nFields per record:\n- amount (required): positive = cash-in, negative = cash-out\n- transactionDate (required): YYYY-MM-DD\n- description, payerOrPayee, reference: optional strings\n\nReturns {data: {errors: []}} on success. accountResourceId must be a bank-type CoA account (find via list_bank_accounts).',
+        params: {
+            accountResourceId: {
+                type: 'string',
+                description: 'Bank account resourceId (from list_bank_accounts)',
+            },
+            records: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        amount: { type: 'number', description: 'Positive = cash-in, negative = cash-out' },
+                        transactionDate: { type: 'string', description: 'Date (YYYY-MM-DD)' },
+                        description: { type: 'string', description: 'Description' },
+                        payerOrPayee: { type: 'string', description: 'Payer or payee name' },
+                        reference: { type: 'string', description: 'Reference' },
+                    },
+                    required: ['amount', 'transactionDate'],
+                },
+                description: 'Array of 1-100 bank records',
+            },
+        },
+        required: ['accountResourceId', 'records'],
+        group: 'bank',
+        readOnly: false,
+        execute: async (ctx, input) => addBankRecords(ctx.client, input.accountResourceId, input.records),
+    },
     // ── Magic: Create BT from Attachment ──────────────────────────
     {
         name: 'create_bt_from_attachment',
@@ -2299,7 +2339,7 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
     },
     {
         name: 'add_attachment',
-        description: 'Add an attachment to a business transaction.',
+        description: 'Add an attachment to a business transaction. Provide sourceUrl (downloads and uploads as file) or attachmentId (links existing).',
         params: {
             transactionType: {
                 type: 'string',
@@ -2307,8 +2347,8 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
                 description: 'Transaction type',
             },
             transactionId: { type: 'string', description: 'Transaction resourceId' },
-            attachmentId: { type: 'string', description: 'Attachment ID to link' },
-            sourceUrl: { type: 'string', description: 'Source file URL (alternative to attachmentId)' },
+            attachmentId: { type: 'string', description: 'Attachment ID to link (alternative to sourceUrl)' },
+            sourceUrl: { type: 'string', description: 'Source file URL — downloaded and uploaded as multipart file' },
         },
         required: ['transactionType', 'transactionId'],
         group: 'attachments',
@@ -2317,11 +2357,28 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
             if (!input.attachmentId && !input.sourceUrl) {
                 throw new Error('Provide attachmentId or sourceUrl — one is required.');
             }
+            let file;
+            let fileName;
+            if (input.sourceUrl) {
+                const res = await fetch(input.sourceUrl);
+                if (!res.ok)
+                    throw new Error(`Failed to download ${input.sourceUrl}: ${res.status}`);
+                const buffer = await res.arrayBuffer();
+                const contentType = res.headers.get('content-type') ?? 'application/octet-stream';
+                file = new Blob([buffer], { type: contentType });
+                try {
+                    fileName = new URL(input.sourceUrl).pathname.split('/').pop() || 'attachment';
+                }
+                catch {
+                    fileName = 'attachment';
+                }
+            }
             return addAttachment(ctx.client, {
                 businessTransactionType: input.transactionType,
                 businessTransactionResourceId: input.transactionId,
+                file,
+                fileName,
                 attachmentId: input.attachmentId,
-                sourceUrl: input.sourceUrl,
             });
         },
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jaz-clio",
-  "version": "4.20.0",
+  "version": "4.21.2",
   "description": "Clio — Command Line Interface Orchestrator for Jaz AI.",
   "type": "module",
   "bin": {
@@ -56,9 +56,11 @@
     "update-notifier": "^7.3.1"
   },
   "devDependencies": {
+    "@anthropic-ai/mcpb": "^2.1.2",
     "@types/adm-zip": "^0.5.6",
     "@types/node": "^22.10.1",
     "@types/prompts": "^2.4.9",
+    "esbuild": "^0.27.3",
     "pino-pretty": "^13.1.3",
     "typescript": "^5.7.2",
     "vitest": "^4.0.18"