jaz-clio 4.4.0 → 4.6.0

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 4.4.0
+version: 4.6.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.

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.4.0
+version: 4.6.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.4.0
+version: 4.6.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

@@ -52,7 +52,8 @@ Multilingual support: Filipino/Tagalog, Bahasa Indonesia/Malay, Vietnamese, and
 
 - **Invoices/Bills/Credit Notes**: `.pdf`, `.jpg`, `.jpeg`, `.png`
 - **Bank Statements**: `.csv`, `.ofx`
-- **Skipped** (with warning): `.xlsx`, `.xls`, `.doc`, `.docx`, `.txt`, `.zip`, `.rar`, `.7z`
+- **Containers** (auto-extracted): `.zip` — contents extracted and processed individually
+- **Skipped** (with warning): `.xlsx`, `.xls`, `.doc`, `.docx`, `.txt`, `.rar`, `.7z`
 
 ### Traversal Rules
 
@@ -60,6 +61,7 @@ Multilingual support: Filipino/Tagalog, Bahasa Indonesia/Malay, Vietnamese, and
 2. **Root-level files** — classified as UNKNOWN (no folder context)
 3. **Max depth** — 10 levels (prevents runaway recursion)
 4. **Hidden files/dirs** — skipped (anything starting with `.`)
+5. **ZIP files** — extracted to temp dir, contents scanned through same pipeline (max 1 level, no nested ZIPs)
 
 ## Cloud Provider Support
 
@@ -85,11 +87,17 @@ The `--source` flag accepts public share links from Dropbox, Google Drive, and O
 # Scan + classify local directory
 clio jobs document-collection ingest --source ./client-docs/ [--json]
 
+# Scan + classify a ZIP file (auto-extracted)
+clio jobs document-collection ingest --source ./client-docs.zip [--json]
+
 # Cloud sources — Dropbox, Google Drive, OneDrive
 clio jobs document-collection ingest --source "https://www.dropbox.com/scl/fo/.../folder?rlkey=..." [--json]
 clio jobs document-collection ingest --source "https://drive.google.com/file/d/FILE_ID/view" [--json]
 clio jobs document-collection ingest --source "https://1drv.ms/f/s!..." [--json]
 
+# Dropbox file link to a ZIP (auto-extracted)
+clio jobs document-collection ingest --source "https://www.dropbox.com/scl/fi/.../docs.zip?rlkey=...&dl=0" [--json]
+
 # With timeout for large cloud downloads
 clio jobs document-collection ingest --source "https://www.dropbox.com/..." --timeout 120000 [--json]
 
@@ -97,24 +105,38 @@ 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
+# Upload a ZIP of invoices via Magic (all files treated as same type)
+clio magic create --file ./invoices.zip --type invoice --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
 
 | Flag | Description |
 |------|-------------|
-| `--source <path\|url>` | Local directory path or public cloud share link — Dropbox, Google Drive, OneDrive (required) |
+| `--source <path\|url>` | Local directory, .zip file, or public cloud share link — Dropbox, Google Drive, OneDrive (required). ZIPs are auto-extracted. |
 | `--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 +193,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 +202,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)
 
@@ -193,6 +215,24 @@ When run without `ingest` subcommand, produces a 4-phase blueprint:
 
 The AI agent then uses the classified file paths to upload via the Jaz Magic API (see api skill for endpoint details).
 
+## ZIP File Support
+
+ZIP files are treated as containers — their contents are extracted and each file is processed individually through the same scan/classify pipeline.
+
+### Supported Scenarios
+
+1. **ZIP in a scanned directory**: Extracted to a temp dir, contents scanned recursively
+2. **ZIP as --source**: `clio jobs document-collection ingest --source ./archive.zip` extracts and scans
+3. **ZIP from Dropbox file link**: Auto-extracted after download
+4. **ZIP via clio magic create**: `clio magic create --file archive.zip --type invoice` extracts and uploads each file
+
+### Limitations
+
+- Nested ZIPs (ZIP inside ZIP) are not extracted — only one level
+- Password-protected ZIPs are not supported (adm-zip limitation)
+- Max ZIP size: 500MB
+- `.rar` and `.7z` are still skipped (no built-in support)
+
 ## Relationship to Other Skills
 
 - **api skill** — Field names, auth headers, error codes for Magic endpoints. Agent uses this to upload classified files.

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

@@ -1,6 +1,6 @@
 ---
 name: jaz-recipes
-version: 4.4.0
+version: 4.6.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/draft-helpers.js

@@ -27,7 +27,9 @@ export const JOURNAL_REQUIRED_FIELDS = [
     { field: 'valueDate', label: 'Date', hint: '--date <YYYY-MM-DD>', check: (j) => !!j.valueDate },
     { field: 'journalEntries', label: 'Journal entries', hint: '--entries <json>', check: (j) => j.journalEntries?.length > 0 },
     { field: 'accountResourceId', label: 'Account', hint: '--account <name or UUID>', check: (e) => !!(e.accountResourceId || e.organizationAccountResourceId), perLineItem: true },
-    { field: 'amount', label: 'Amount', hint: 'via --entries', check: (e) => e.amount != null && e.amount > 0, perLineItem: true },
+    { field: 'amount', label: 'Amount', hint: 'via --entries', check: (e) => (e.amount != null && e.amount > 0) ||
+            (e.debitAmount != null && e.debitAmount > 0) ||
+            (e.creditAmount != null && e.creditAmount > 0), perLineItem: true },
 ];
 // ── Core Validation ─────────────────────────────────────────────
 /**
@@ -91,14 +93,17 @@ specs, lineItemsKey = 'lineItems') {
             ? { status: 'ok', resourceId: acctId }
             : { status: 'missing', hint: '--account <name or UUID>' };
         // Journal entries: show amount/type instead of name/unitPrice
+        // GET returns debitAmount/creditAmount (not amount/type)
         if (lineItemsKey === 'journalEntries') {
             const amountSpec = liSpecs.find((s) => s.field === 'amount');
             const amountOk = amountSpec ? amountSpec.check(li) : true;
+            const entryAmount = li.amount ?? li.debitAmount ?? li.creditAmount ?? null;
+            const entryType = li.type ?? (li.debitAmount > 0 ? 'DEBIT' : li.creditAmount > 0 ? 'CREDIT' : null);
             return {
                 index: i,
-                name: li.description || li.type || null,
+                name: li.description || entryType || null,
                 nameStatus: 'ok',
-                unitPrice: li.amount ?? null,
+                unitPrice: entryAmount,
                 unitPriceStatus: amountOk ? 'ok' : 'missing',
                 account,
             };
@@ -358,10 +363,25 @@ function sanitizeJournalEntry(e) {
     const acctId = e.accountResourceId || e.organizationAccountResourceId;
     if (acctId)
         clean.accountResourceId = acctId;
-    if (e.amount != null)
+    // Amount/type: GET uses debitAmount/creditAmount, PUT uses amount+type
+    if (e.amount != null) {
         clean.amount = e.amount;
-    if (e.type)
-        clean.type = e.type; // DEBIT or CREDIT
+    }
+    else if (e.debitAmount != null && e.debitAmount > 0) {
+        clean.amount = e.debitAmount;
+    }
+    else if (e.creditAmount != null && e.creditAmount > 0) {
+        clean.amount = e.creditAmount;
+    }
+    if (e.type) {
+        clean.type = e.type; // Already in PUT form (DEBIT or CREDIT)
+    }
+    else if (e.debitAmount != null && e.debitAmount > 0) {
+        clean.type = 'DEBIT';
+    }
+    else if (e.creditAmount != null && e.creditAmount > 0) {
+        clean.type = 'CREDIT';
+    }
     if (e.description)
         clean.description = e.description;
     if (e.contactResourceId)

package/dist/commands/jobs.js

@@ -1,4 +1,5 @@
 import chalk from 'chalk';
+import prompts from 'prompts';
 import { readFileSync } from 'node:fs';
 import { generateMonthEndBlueprint } from '../core/jobs/month-end/blueprint.js';
 import { generateQuarterEndBlueprint } from '../core/jobs/quarter-end/blueprint.js';
@@ -272,11 +273,10 @@ export function registerJobsCommand(program) {
     const ingestCmd = docCollection
         .command('ingest')
         .description('Scan and classify client documents — optionally upload via Magic API')
-        .requiredOption('--source <path>', 'Local directory path or public share URL (Dropbox, Google Drive, OneDrive)')
+        .requiredOption('--source <path>', 'Local directory, .zip file, or public share URL (Dropbox, Google Drive, OneDrive). ZIPs are auto-extracted.')
         .option('--type <type>', 'Force document type: invoice, bill, credit-note-customer, credit-note-supplier, or bank-statement')
         .option('--upload', 'Upload classified files to Jaz after scanning (requires auth)')
         .option('--bank-account <name-or-id>', 'Bank account name or resourceId (required for bank statements)')
-        .option('--pdf-password <password>', 'Password for encrypted PDFs (same password applied to all)')
         .option('--api-key <key>', 'API key (or use JAZ_API_KEY env var)')
         .option('--timeout <ms>', 'Download timeout in milliseconds for cloud sources (default: 30000)', parseInt)
         .option('--currency <code>', 'Functional/reporting currency (e.g. SGD)')
@@ -342,46 +342,55 @@ export function registerJobsCommand(program) {
             process.exit(1);
         }
         // ── Encrypted PDF checks ──────────────────────────────────────
-        const encryptedFiles = plan.folders
-            .flatMap(f => f.files.filter(file => file.encrypted))
-            .map(f => `${f.folder}/${f.filename}`);
-        if (encryptedFiles.length > 0) {
-            if (!isQpdfAvailable()) {
-                if (opts.json) {
-                    console.log(JSON.stringify({
-                        error: 'ENCRYPTED_PDF_NO_QPDF',
-                        message: 'Encrypted PDFs found but qpdf is not installed',
-                        action: 'Install qpdf: brew install qpdf (macOS) or sudo apt install qpdf (Linux), then retry',
-                        encryptedFiles,
-                    }));
-                }
-                else {
-                    console.error(chalk.red('Error: Encrypted PDFs found but qpdf is not installed.'));
-                    console.error(chalk.yellow('Install qpdf to decrypt before upload:'));
-                    console.error(chalk.dim('  macOS:   brew install qpdf'));
-                    console.error(chalk.dim('  Ubuntu:  sudo apt install qpdf'));
-                    console.error(chalk.dim('  Windows: choco install qpdf'));
-                }
+        // Files with __pw__<password> in the filename auto-supply their password.
+        // Only files without a filePassword need qpdf + user action.
+        const encryptedFiles = plan.folders.flatMap(f => f.files.filter(file => file.encrypted));
+        const needPassword = encryptedFiles.filter(f => !f.filePassword);
+        if (encryptedFiles.length > 0 && !isQpdfAvailable()) {
+            const paths = encryptedFiles.map(f => `${f.folder}/${f.filename}`);
+            if (opts.json) {
+                console.log(JSON.stringify({
+                    error: 'ENCRYPTED_PDF_NO_QPDF',
+                    message: 'Encrypted PDFs found but qpdf is not installed',
+                    action: 'Install qpdf: brew install qpdf (macOS) or sudo apt install qpdf (Linux), then retry',
+                    encryptedFiles: paths,
+                }));
+            }
+            else {
+                console.error(chalk.red('Error: Encrypted PDFs found but qpdf is not installed.'));
+                console.error(chalk.yellow('Install qpdf to decrypt before upload:'));
+                console.error(chalk.dim('  macOS:   brew install qpdf'));
+                console.error(chalk.dim('  Ubuntu:  sudo apt install qpdf'));
+                console.error(chalk.dim('  Windows: choco install qpdf'));
+            }
+            process.exit(1);
+        }
+        if (needPassword.length > 0) {
+            const paths = needPassword.map(f => `${f.folder}/${f.filename}`);
+            if (opts.json) {
+                // Agents can't type — error with actionable instructions
+                console.log(JSON.stringify({
+                    error: 'ENCRYPTED_PDF_NO_PASSWORD',
+                    message: `${needPassword.length} encrypted PDF(s) found without a password`,
+                    action: 'Embed password in filename: rename to filename__pw__password.pdf',
+                    encryptedFiles: paths,
+                }));
                 process.exit(1);
             }
-            if (!opts.pdfPassword) {
-                if (opts.json) {
-                    console.log(JSON.stringify({
-                        error: 'ENCRYPTED_PDF_NO_PASSWORD',
-                        message: `${encryptedFiles.length} encrypted PDF(s) found — password required`,
-                        action: 'Retry with --pdf-password <password>',
-                        encryptedFiles,
-                    }));
+            // Interactive mode — prompt user for each encrypted file
+            console.error(chalk.yellow(`\n${needPassword.length} encrypted PDF(s) need a password:\n`));
+            for (const f of needPassword) {
+                const { password } = await prompts({
+                    type: 'text',
+                    name: 'password',
+                    message: `PDF password for ${f.folder}/${f.filename}`,
+                });
+                if (!password) {
+                    console.error(chalk.red('Aborted — no password provided.'));
+                    console.error(chalk.dim('Tip: embed password in filename to skip prompts: filename__pw__password.pdf'));
+                    process.exit(1);
                 }
-                else {
-                    console.error(chalk.red(`Error: ${encryptedFiles.length} encrypted PDF(s) found — password required.`));
-                    console.error(chalk.dim('Encrypted files:'));
-                    for (const f of encryptedFiles)
-                        console.error(chalk.dim(`  ${f}`));
-                    console.error();
-                    console.error(chalk.dim('Retry with: --pdf-password <password>'));
-                }
-                process.exit(1);
+                f.filePassword = password;
             }
         }
         // ── Upload with auth ─────────────────────────────────────────
@@ -402,7 +411,6 @@ export function registerJobsCommand(program) {
                 plan,
                 client,
                 bankAccountId,
-                pdfPassword: opts.pdfPassword,
                 onProgress: apiOpts.json ? undefined : printUploadProgress,
             });
             const result = { ...plan, upload };