jaz-clio 4.3.0 → 4.5.0

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 4.3.0
+version: 4.5.0
 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.
@@ -211,8 +211,12 @@ Step 3:  For each draft where ready = true:
 
 81. **`--account` bulk patches line items** — when used with `clio bills draft finalize`, `--account` resolves the name to a UUID then sets `accountResourceId` on EVERY line item where it's currently null. Existing accounts are NOT overwritten. Same for `--tax-profile`. `--lines` takes priority (full replacement).
 82. **`--dry-run` validates without modifying** — returns the same validation structure as `draft list` (per-field status/hint), so agents can preview what would happen before committing. No API write occurs.
-83. **Finalization is a single PUT** — `updateBill()` with `saveAsDraft: false` transitions DRAFT → UNPAID (per Rule 67) and updates all fields in one call. No delete-and-recreate.
+83. **Finalization is a single PUT** — `updateBill()` with `saveAsDraft: false` transitions DRAFT → UNPAID (per Rule 67) and updates all fields in one call. No delete-and-recreate. The CLI handles all field normalization automatically (date format, line item sanitization, account field name mapping).
 84. **Draft list attachment count** — `draft list` includes `attachmentCount` per draft (from `GET /bills/:id/attachments`). Use `draft attachments <id>` for full details including `fileUrl` download links.
+85. **PUT body requires `resourceId`** — The UpdateBill PUT endpoint requires `resourceId` in the body (in addition to the URL path). Dates must be `YYYY-MM-DD` (not ISO with time). `taxInclusion` is boolean (`true`/`false`), not string. Line items must use `accountResourceId` (not `organizationAccountResourceId` from GET).
+86. **GET→PUT field asymmetry** — GET returns `organizationAccountResourceId` on line items; PUT requires `accountResourceId`. GET returns dates as `2026-02-27T00:00:00Z`; PUT requires `2026-02-27`. GET returns `taxProfile: { resourceId }` object; PUT requires `taxProfileResourceId` string. The CLI `draft finalize` command normalizes all of these automatically.
+87. **Magic workflow status may be null immediately after creation** — The `POST /magic/workflows/search` endpoint may return a workflow with `status: null` right after `POST /magic/create-from-attachment`. Allow 2-3 seconds before polling, or default to `SUBMITTED`. The CLI `magic status` command defaults null status to `SUBMITTED`.
+88. **Finalized invoices/bills need `accountResourceId` on all line items** — When `saveAsDraft: false` (or using `--finalize`), every `lineItems[i].accountResourceId` must be set. Omitting it causes 422: "lineItems[0].accountResourceId is required if [saveAsDraft] is false". The CLI validates this pre-flight.
 
 #### DRY Extension Pattern
 

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

@@ -985,6 +985,12 @@ Content-Type: application/json
 - Tax amounts and profiles
 - Document reference numbers, dates, currency
 
+**Encrypted PDFs:** Magic cannot process password-protected PDFs. The CLI auto-detects and decrypts before upload:
+- Embed password in filename: `receipt__pw__s3cRetP@ss.pdf` → decrypts with password `s3cRetP@ss`, uploads as `receipt.pdf`
+- `__pw__` delimiter is case-insensitive; password is case-sensitive
+- Requires `qpdf` installed (`brew install qpdf`)
+- If no password in filename, CLI prompts interactively (or errors in `--json` mode with actionable rename instructions)
+
 **Key gotchas:**
 - `sourceFile` is the field name (NOT `file`) — same pattern as bank statement endpoint
 - `EXPENSE` returns 422 — use one of the 4 valid types above
@@ -1056,6 +1062,41 @@ Content-Type: application/json
 3. When `COMPLETED` → read `businessTransactionDetails.businessTransactionResourceId`
 4. Use the BT resource ID with `GET /invoices/:id`, `GET /bills/:id`, `GET /customer-credit-notes/:id`, or `GET /supplier-credit-notes/:id`
 
+### CLI: clio magic split — Merged PDF Splitting
+
+Splits a merged PDF containing multiple documents (invoices, bills, credit notes) into individual files and uploads each to Magic. Uses structural PDF signals (bookmarks, page labels) + text heuristics (keywords, "Page 1 of N" patterns) for boundary detection. **No AI tokens used.**
+
+```bash
+# Auto-detect boundaries + upload
+clio magic split --file merged.pdf --type bill
+
+# Manual page ranges (for scanned PDFs or override)
+clio magic split --file merged.pdf --type bill --pages "1-3,4-6,7-9"
+
+# Dry-run: detect boundaries only (no qpdf needed)
+clio magic split --file merged.pdf --type bill --dry-run
+
+# JSON output (for agents)
+clio magic split --file merged.pdf --type bill --dry-run --json
+```
+
+**Detection signals (score-based, threshold >= 50):**
+- outline-bookmark (+80): PDF bookmark points to this page
+- page-label-reset (+70): PDF page label restarts at "1"
+- keyword in header (+40): Document keyword (INVOICE, BILL, etc.) in upper 40%
+- page-one-of (+35): "Page 1 of N" pattern
+- keyword-large (+25): Large font (>18pt) keyword bonus
+- doc-ref (+20): Document reference (INV-001, SO-2024-100, etc.)
+- continuation (-60): "Page N>1 of M" anti-signal
+- continuation-text (-40): "Continued" anti-signal
+
+**Edge cases:**
+- Scanned PDFs (no extractable text): warns and requires `--pages` manual override
+- Mixed scanned+digital: low confidence on scanned portions triggers confirmation prompt
+- Single document detected: suggests `clio magic create` instead
+- Encrypted PDFs: same `__pw__` pattern as `magic create`
+- Requires `qpdf` for splitting (not needed for `--dry-run` auto-detect mode)
+
 ---
 
 ## 15. Bank Records

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 4.3.0
+version: 4.5.0
 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.3.0
+version: 4.5.0
 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/jobs/references/document-collection.md

@@ -97,8 +97,10 @@ clio jobs document-collection ingest --source "https://www.dropbox.com/..." --ti
 clio jobs document-collection ingest --source ./scans/ --type invoice [--json]
 clio jobs document-collection ingest --source ./scans/ --type credit-note-customer [--json]
 
-# Scan + upload (decrypt encrypted PDFs with password)
-clio jobs document-collection ingest --source ./bank-docs/ --upload --bank-account "DBS Checking" --pdf-password "mypass" --json
+# Scan + upload (encrypted PDFs with password embedded in filename)
+clio jobs document-collection ingest --source ./bank-docs/ --upload --bank-account "DBS Checking" --json
+# To decrypt: rename encrypted PDF to: receipt__pw__actualPassword.pdf
+# The __pw__ delimiter is case-insensitive; the password itself is case-sensitive.
 ```
 
 ### Options
@@ -109,12 +111,21 @@ clio jobs document-collection ingest --source ./bank-docs/ --upload --bank-accou
 | `--type <type>` | Force all files to: `invoice`, `bill`, `credit-note-customer`, `credit-note-supplier`, or `bank-statement` |
 | `--upload` | Upload classified files to Jaz after scanning (requires auth) |
 | `--bank-account <name-or-id>` | Bank account name or resourceId (required for bank statements) |
-| `--pdf-password <password>` | Password for encrypted PDFs — same password applied to all. Requires `qpdf` installed (`brew install qpdf`) |
 | `--api-key <key>` | API key for upload (or use `JAZ_API_KEY` env var) |
 | `--timeout <ms>` | Download timeout in milliseconds (default: 30000 for files, 120000 for folders) |
 | `--currency <code>` | Functional/reporting currency label |
 | `--json` | Structured JSON output with absolute file paths |
 
+### Encrypted PDF Passwords
+
+Embed the password in the filename using the `__pw__` pattern:
+```
+receipt__pw__s3cRetP@ss.pdf  →  password: "s3cRetP@ss", display name: "receipt.pdf"
+```
+- `__pw__` is case-insensitive (`__PW__`, `__Pw__`, etc.)
+- The password after `__pw__` is case-sensitive
+- Requires `qpdf` installed (`brew install qpdf`)
+
 ### JSON Output
 
 The `--json` output includes absolute file paths, classification, and size for each file. The AI agent uses these paths to upload via the api skill.
@@ -171,7 +182,7 @@ sudo apt install qpdf    # Ubuntu/Debian
 choco install qpdf       # Windows
 ```
 
-When `--upload` is used with `--pdf-password`, encrypted PDFs are decrypted to a temp file, uploaded, then cleaned up. The same password is applied to all encrypted files in the batch.
+Passwords are embedded in the filename using the `__pw__` pattern: `receipt__pw__myPass.pdf`. During upload, encrypted PDFs with a filename password are decrypted to a temp file, uploaded, then cleaned up.
 
 ### Error Handling (JSON mode)
 
@@ -180,7 +191,7 @@ If encrypted PDFs are found during `--upload` without the required dependencies,
 | Error Code | Condition | Action |
 |------------|-----------|--------|
 | `ENCRYPTED_PDF_NO_QPDF` | qpdf not installed | Install qpdf, then retry |
-| `ENCRYPTED_PDF_NO_PASSWORD` | No `--pdf-password` provided | Retry with `--pdf-password <password>` |
+| `ENCRYPTED_PDF_NO_PASSWORD` | Encrypted PDF without `__pw__` in filename | Rename file to embed password: `name__pw__password.pdf` |
 
 ## Phases (Blueprint)
 

package/assets/skills/transaction-recipes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-recipes
-version: 4.3.0
+version: 4.5.0
 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 10 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/api-action.js

@@ -51,7 +51,7 @@ export function apiAction(fn) {
                 process.exit(3);
             }
             if (err instanceof JazApiError) {
-                console.error(chalk.red(`API Error (${err.status}): ${err.endpoint}`));
+                console.error(chalk.red(`API Error (${err.status}): ${err.message}`));
                 process.exit(2);
             }
             console.error(chalk.red(`Error: ${err.message}`));

package/dist/commands/bills.js

@@ -5,7 +5,7 @@ import { apiAction } from './api-action.js';
 import { resolveContactFlag, resolveAccountFlag, resolveTaxProfileFlag } from './resolve.js';
 import { parsePositiveInt, parseNonNegativeInt, parseMoney, parseRate, parseLineItems, readBodyInput, requireFields } from './parsers.js';
 import { paginatedFetch, paginatedJson, displaySlice } from './pagination.js';
-import { BILL_REQUIRED_FIELDS, buildDraftReport, formatDraftTable, addDraftFinalizeOptions, mergeDraftFlags, validateDraft, buildValidation, } from './draft-helpers.js';
+import { BILL_REQUIRED_FIELDS, buildDraftReport, formatDraftTable, addDraftFinalizeOptions, mergeDraftFlags, validateDraft, buildValidation, normalizeDate, sanitizeLineItem, } from './draft-helpers.js';
 export function registerBillsCommand(program) {
     const bills = program
         .command('bills')
@@ -448,12 +448,40 @@ export function registerBillsCommand(program) {
         else {
             updateData = mergeDraftFlags(bill, resolvedOpts);
         }
+        // Track which fields the user explicitly changed (before we build the full PUT body)
+        const userChangedFields = Object.keys(updateData);
         // 4. Validate after merge — apply updates to a virtual copy
         const merged = { ...bill, ...updateData };
         if (updateData.lineItems) {
             merged.lineItems = updateData.lineItems;
         }
         const { missingFields, missingCount, ready } = validateDraft(merged, BILL_REQUIRED_FIELDS);
+        // 4b. Build a full PUT-compatible body from merged state.
+        // The API PUT requires: reference, contactResourceId, dates (YYYY-MM-DD),
+        // and line items in create-request format (not GET response shape).
+        if (!body) {
+            const fullBody = {
+                reference: merged.reference || undefined,
+                contactResourceId: merged.contactResourceId,
+                valueDate: normalizeDate(updateData.valueDate) || normalizeDate(bill.valueDate),
+                dueDate: normalizeDate(updateData.dueDate) || normalizeDate(bill.dueDate),
+            };
+            // Sanitize line items: strip response-only fields, normalize account field name
+            const rawItems = (updateData.lineItems ?? bill.lineItems ?? []); // eslint-disable-line @typescript-eslint/no-explicit-any
+            fullBody.lineItems = rawItems.map((li) => sanitizeLineItem(li)); // eslint-disable-line @typescript-eslint/no-explicit-any
+            // Carry over tax settings
+            if (updateData.isTaxVatApplicable != null || bill.isTaxVATApplicable != null) {
+                fullBody.isTaxVATApplicable = updateData.isTaxVatApplicable ?? bill.isTaxVATApplicable;
+            }
+            if (updateData.taxInclusion != null || bill.taxInclusion != null) {
+                fullBody.taxInclusion = updateData.taxInclusion ?? bill.taxInclusion;
+            }
+            if (updateData.notes)
+                fullBody.notes = updateData.notes;
+            if (updateData.tag)
+                fullBody.tag = updateData.tag;
+            updateData = fullBody;
+        }
         // 5. Dry run: just report validation
         if (opts.dryRun) {
             const validation = buildValidation(merged, BILL_REQUIRED_FIELDS);
@@ -508,10 +536,12 @@ export function registerBillsCommand(program) {
             process.exit(1);
         }
         // 7. Finalize: PUT with saveAsDraft=false
-        const finalRes = await finalizeBill(client, resourceId, updateData);
-        const updated = finalRes.data;
-        // Compute which fields were updated
-        const fieldsUpdated = Object.keys(updateData).filter((k) => k !== 'saveAsDraft');
+        await finalizeBill(client, resourceId, updateData);
+        // 8. GET the finalized bill to confirm status (PUT response may not include status)
+        const verifyRes = await getBill(client, resourceId);
+        const updated = verifyRes.data;
+        // Report which fields the user explicitly changed (not the full PUT body)
+        const fieldsUpdated = userChangedFields.filter((k) => k !== 'saveAsDraft' && k !== 'resourceId');
         if (opts.json) {
             console.log(JSON.stringify({
                 finalized: true,

package/dist/commands/customer-credit-notes.js

@@ -1,9 +1,11 @@
 import chalk from 'chalk';
-import { listCustomerCreditNotes, getCustomerCreditNote, searchCustomerCreditNotes, createCustomerCreditNote, updateCustomerCreditNote, deleteCustomerCreditNote, createCustomerCreditNoteRefund, listCustomerCreditNoteRefunds, } from '../core/api/customer-cn.js';
+import { listCustomerCreditNotes, getCustomerCreditNote, searchCustomerCreditNotes, createCustomerCreditNote, updateCustomerCreditNote, deleteCustomerCreditNote, createCustomerCreditNoteRefund, listCustomerCreditNoteRefunds, finalizeCustomerCreditNote, } from '../core/api/customer-cn.js';
+import { listAttachments } from '../core/api/attachments.js';
 import { apiAction } from './api-action.js';
-import { resolveContactFlag, resolveAccountFlag } from './resolve.js';
+import { resolveContactFlag, resolveAccountFlag, resolveTaxProfileFlag } from './resolve.js';
 import { parsePositiveInt, parseNonNegativeInt, parseMoney, parseRate, parseLineItems, readBodyInput, requireFields } from './parsers.js';
 import { paginatedFetch, paginatedJson, displaySlice } from './pagination.js';
+import { CREDIT_NOTE_REQUIRED_FIELDS, buildDraftReport, formatDraftTable, addDraftFinalizeOptions, mergeDraftFlags, validateDraft, buildValidation, normalizeDate, sanitizeLineItem, } from './draft-helpers.js';
 export function registerCustomerCreditNotesCommand(program) {
     const ccn = program
         .command('customer-credit-notes')
@@ -301,4 +303,211 @@ export function registerCustomerCreditNotesCommand(program) {
             }
         }
     })(opts));
+    // ── clio customer-credit-notes draft ──────────────────────────
+    const draft = ccn
+        .command('draft')
+        .description('Manage draft customer credit notes (inspect, finalize, attachments)');
+    // ── clio customer-credit-notes draft list ─────────────────────
+    draft
+        .command('list')
+        .description('List all draft customer credit notes with per-field validation status')
+        .option('--ids <ids>', 'Comma-separated IDs to inspect (instead of all drafts)')
+        .option('--max-rows <n>', 'Max drafts to fetch (default 10000)', parsePositiveInt)
+        .option('--api-key <key>', 'API key (overrides stored/env)')
+        .option('--json', 'Output as JSON')
+        .action(apiAction(async (client, opts) => {
+        let items; // eslint-disable-line @typescript-eslint/no-explicit-any
+        if (opts.ids) {
+            const ids = opts.ids.split(',').map((s) => s.trim()).filter(Boolean);
+            items = await Promise.all(ids.map(async (id) => {
+                const res = await getCustomerCreditNote(client, id);
+                return res.data;
+            }));
+            items = items.filter((cn) => cn.status === 'DRAFT');
+        }
+        else {
+            const result = await paginatedFetch({ all: true, json: true, maxRows: opts.maxRows }, ({ limit, offset }) => searchCustomerCreditNotes(client, {
+                filter: { status: { eq: 'DRAFT' } },
+                limit,
+                offset,
+                sort: { sortBy: ['valueDate'], order: 'DESC' },
+            }), { label: 'Fetching draft customer credit notes' });
+            items = result.data;
+        }
+        const BATCH_SIZE = 5;
+        const reports = [];
+        for (let i = 0; i < items.length; i += BATCH_SIZE) {
+            const batch = items.slice(i, i + BATCH_SIZE);
+            const batchReports = await Promise.all(batch.map(async (cn) => {
+                let attachmentCount = 0;
+                try {
+                    const attRes = await listAttachments(client, 'customer-credit-notes', cn.resourceId);
+                    attachmentCount = Array.isArray(attRes.data) ? attRes.data.length : 0;
+                }
+                catch { /* Attachment listing may fail — don't block the report */ }
+                return buildDraftReport(cn, CREDIT_NOTE_REQUIRED_FIELDS, attachmentCount);
+            }));
+            reports.push(...batchReports);
+        }
+        if (opts.json) {
+            const readyCount = reports.filter((r) => r.ready).length;
+            console.log(JSON.stringify({
+                totalDrafts: reports.length,
+                readyCount,
+                needsAttentionCount: reports.length - readyCount,
+                drafts: reports,
+            }, null, 2));
+        }
+        else {
+            formatDraftTable('Customer Credit Notes', reports);
+        }
+    }));
+    // ── clio customer-credit-notes draft finalize ─────────────────
+    addDraftFinalizeOptions(draft
+        .command('finalize <resourceId>')
+        .description('Fill missing fields and convert a draft customer credit note to APPROVED')).action((resourceId, opts) => apiAction(async (client) => {
+        const body = readBodyInput(opts);
+        // 1. GET CURRENT DRAFT
+        const res = await getCustomerCreditNote(client, resourceId);
+        const cn = res.data;
+        if (cn.status !== 'DRAFT') {
+            const msg = `Customer credit note ${resourceId} is ${cn.status}, not DRAFT.`;
+            if (opts.json) {
+                console.log(JSON.stringify({ finalized: false, error: msg }));
+            }
+            else {
+                console.error(chalk.red(msg));
+            }
+            process.exit(1);
+        }
+        // 2. RESOLVE NAMES → UUIDs
+        const resolvedOpts = { ...opts }; // eslint-disable-line @typescript-eslint/no-explicit-any
+        if (opts.contact) {
+            const resolved = await resolveContactFlag(client, opts.contact, { silent: opts.json });
+            resolvedOpts.contact = resolved.resourceId;
+        }
+        if (opts.account) {
+            const resolved = await resolveAccountFlag(client, opts.account, { filter: 'line-item', silent: opts.json });
+            resolvedOpts.account = resolved.resourceId;
+        }
+        if (opts.taxProfile) {
+            const resolved = await resolveTaxProfileFlag(client, opts.taxProfile, { silent: opts.json });
+            resolvedOpts.taxProfile = resolved.resourceId;
+        }
+        // 3. MERGE FLAGS WITH EXISTING VALUES
+        let updateData;
+        if (body) {
+            updateData = body;
+        }
+        else {
+            updateData = mergeDraftFlags(cn, resolvedOpts);
+        }
+        const userChangedFields = Object.keys(updateData);
+        // 4. VALIDATE AFTER MERGE
+        const merged = { ...cn, ...updateData };
+        if (updateData.lineItems) {
+            merged.lineItems = updateData.lineItems;
+        }
+        const { missingFields, missingCount, ready } = validateDraft(merged, CREDIT_NOTE_REQUIRED_FIELDS);
+        // 4b. BUILD FULL PUT-COMPATIBLE BODY (no dueDate for credit notes)
+        if (!body) {
+            const fullBody = {
+                reference: merged.reference || undefined,
+                contactResourceId: merged.contactResourceId,
+                valueDate: normalizeDate(updateData.valueDate) || normalizeDate(cn.valueDate),
+            };
+            const rawItems = (updateData.lineItems ?? cn.lineItems ?? []); // eslint-disable-line @typescript-eslint/no-explicit-any
+            fullBody.lineItems = rawItems.map((li) => sanitizeLineItem(li)); // eslint-disable-line @typescript-eslint/no-explicit-any
+            if (updateData.isTaxVatApplicable != null || cn.isTaxVATApplicable != null) {
+                fullBody.isTaxVATApplicable = updateData.isTaxVatApplicable ?? cn.isTaxVATApplicable;
+            }
+            if (updateData.taxInclusion != null || cn.taxInclusion != null) {
+                fullBody.taxInclusion = updateData.taxInclusion ?? cn.taxInclusion;
+            }
+            if (updateData.notes)
+                fullBody.notes = updateData.notes;
+            if (updateData.tag)
+                fullBody.tag = updateData.tag;
+            updateData = fullBody;
+        }
+        // 5. DRY RUN
+        if (opts.dryRun) {
+            const validation = buildValidation(merged, CREDIT_NOTE_REQUIRED_FIELDS);
+            if (opts.json) {
+                console.log(JSON.stringify({ finalized: false, dryRun: true, resourceId, reference: merged.reference || null, ready, missingCount, missingFields, validation }, null, 2));
+            }
+            else {
+                if (ready) {
+                    console.log(chalk.green(`✓ ${merged.reference || resourceId} is ready to finalize.`));
+                }
+                else {
+                    console.log(chalk.yellow(`✗ ${merged.reference || resourceId} — ${missingCount} issue${missingCount > 1 ? 's' : ''} remaining:`));
+                    for (const f of missingFields) {
+                        const spec = CREDIT_NOTE_REQUIRED_FIELDS.find((s) => f === s.field || f.endsWith(`.${s.field}`));
+                        console.log(`  ${f}: ${chalk.red('MISSING')} — ${spec?.hint ?? ''}`);
+                    }
+                }
+            }
+            return;
+        }
+        // 6. VALIDATION FAILURE
+        if (!ready) {
+            const validation = buildValidation(merged, CREDIT_NOTE_REQUIRED_FIELDS);
+            if (opts.json) {
+                console.log(JSON.stringify({ finalized: false, resourceId, reference: merged.reference || null, ready: false, missingCount, missingFields, validation }, null, 2));
+            }
+            else {
+                console.error(chalk.red(`\n✗ Cannot finalize ${merged.reference || resourceId} — ${missingCount} issue${missingCount > 1 ? 's' : ''} remaining:\n`));
+                for (const f of missingFields) {
+                    const spec = CREDIT_NOTE_REQUIRED_FIELDS.find((s) => f === s.field || f.endsWith(`.${s.field}`));
+                    console.error(`  ${f}: ${chalk.red('MISSING')} — ${spec?.hint ?? ''}`);
+                }
+                console.error(chalk.dim(`\n  Fix the issues and retry:\n    clio customer-credit-notes draft finalize ${resourceId} ...\n`));
+            }
+            process.exit(1);
+        }
+        // 7. FINALIZE
+        await finalizeCustomerCreditNote(client, resourceId, updateData);
+        // 8. VERIFY
+        const verifyRes = await getCustomerCreditNote(client, resourceId);
+        const updated = verifyRes.data;
+        const fieldsUpdated = userChangedFields.filter((k) => k !== 'saveAsDraft' && k !== 'resourceId');
+        if (opts.json) {
+            console.log(JSON.stringify({ finalized: true, resourceId: updated.resourceId, reference: updated.reference || null, status: updated.status, fieldsUpdated }, null, 2));
+        }
+        else {
+            console.log(chalk.green(`\n✓ Customer credit note finalized: ${updated.reference || updated.resourceId}`));
+            console.log(chalk.bold('  Status:'), updated.status);
+            if (fieldsUpdated.length > 0) {
+                console.log(chalk.bold('  Updated:'), fieldsUpdated.join(', '));
+            }
+        }
+    })(opts));
+    // ── clio customer-credit-notes draft attachments ──────────────
+    draft
+        .command('attachments <resourceId>')
+        .description('List attachments for a customer credit note (URLs for agent inspection)')
+        .option('--api-key <key>', 'API key (overrides stored/env)')
+        .option('--json', 'Output as JSON')
+        .action((resourceId, opts) => apiAction(async (client) => {
+        const cnRes = await getCustomerCreditNote(client, resourceId);
+        const cn = cnRes.data;
+        const attRes = await listAttachments(client, 'customer-credit-notes', resourceId);
+        const attachments = Array.isArray(attRes.data) ? attRes.data : [];
+        if (opts.json) {
+            console.log(JSON.stringify({ creditNoteResourceId: resourceId, creditNoteReference: cn.reference || null, attachments }, null, 2));
+        }
+        else {
+            if (attachments.length === 0) {
+                console.log(chalk.yellow(`No attachments for customer credit note ${cn.reference || resourceId}.`));
+                return;
+            }
+            console.log(chalk.bold(`Attachments for ${cn.reference || resourceId}:\n`));
+            for (const att of attachments) {
+                console.log(`  ${chalk.cyan(att.resourceId)}  ${att.fileName || '(unnamed)'}`);
+                if (att.fileUrl)
+                    console.log(`    ${chalk.dim(att.fileUrl)}`);
+            }
+        }
+    })(opts));
 }