jaz-clio 4.4.0 → 4.5.0

package/assets/skills/api/SKILL.md

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

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.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.4.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.4.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/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';
@@ -276,7 +277,6 @@ export function registerJobsCommand(program) {
         .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 };

package/dist/commands/magic.js

@@ -1,7 +1,10 @@
 import chalk from 'chalk';
 import { readFileSync } from 'node:fs';
 import { basename, extname, resolve } from 'node:path';
+import prompts from 'prompts';
 import { createFromAttachment, searchMagicWorkflows, waitForWorkflows, } from '../core/api/magic.js';
+import { extractFilePassword, isPdfEncrypted, isQpdfAvailable, decryptPdf, cleanupDecryptedFile, } from '../core/jobs/document-collection/tools/ingest/decrypt.js';
+import { detectBoundaries, parsePageRanges, splitPdf, cleanupSplitFiles, } from '../core/pdf/index.js';
 import { apiAction } from './api-action.js';
 import { parsePositiveInt } from './parsers.js';
 import { displaySlice } from './pagination.js';
@@ -42,8 +45,8 @@ export function registerMagicCommand(program) {
     // ── clio magic create ─────────────────────────────────────────
     magic
         .command('create')
-        .description('Upload a file to create a draft transaction via AI extraction')
-        .option('--file <path>', 'Local file path (PDF, JPG, PNG, HEIC, XLS, XLSX, EML)')
+        .description('Upload a file to create a draft transaction via AI extraction. Encrypted PDFs auto-decrypt via __pw__ in filename (e.g. receipt__pw__pass.pdf)')
+        .option('--file <path>', 'Local file path (PDF, JPG, PNG, HEIC, XLS, XLSX, EML). Encrypted PDFs: name__pw__password.pdf')
         .option('--url <url>', 'Remote file URL (alternative to --file)')
         .option('--type <type>', `Document type: ${VALID_TYPES}`)
         .option('--api-key <key>', 'API key (overrides stored/env)')
@@ -69,6 +72,7 @@ export function registerMagicCommand(program) {
         }
         let sourceFile;
         let sourceFileName;
+        let decryptedPath;
         if (opts.file) {
             const filePath = resolve(opts.file);
             const ext = extname(filePath).toLowerCase();
@@ -77,9 +81,17 @@ export function registerMagicCommand(program) {
                 console.error(chalk.red(`Error: unsupported file type "${ext}". Supported: ${Object.keys(MIME_MAP).join(', ')}`));
                 process.exit(1);
             }
-            const buffer = readFileSync(filePath);
-            sourceFile = new Blob([buffer], { type: mime });
-            sourceFileName = basename(filePath);
+            const resolved = await resolveInputPdf(filePath, ext, opts);
+            decryptedPath = resolved.decryptedPath;
+            try {
+                const buffer = readFileSync(resolved.effectivePath);
+                sourceFile = new Blob([buffer], { type: mime });
+                sourceFileName = resolved.cleanName;
+            }
+            finally {
+                if (decryptedPath)
+                    cleanupDecryptedFile(decryptedPath);
+            }
         }
         const res = await createFromAttachment(client, {
             businessTransactionType: apiType,
@@ -231,8 +243,299 @@ export function registerMagicCommand(program) {
                 console.log(chalk.dim(`  ... and ${overflow.toLocaleString()} more (use --json for full output)`));
         }
     }));
+    // ── clio magic split ──────────────────────────────────────────
+    magic
+        .command('split')
+        .description('Split a merged PDF into individual documents and upload each to Magic.\n' +
+        'Auto-detects document boundaries using text heuristics (keywords, page numbers, bookmarks).\n' +
+        'For scanned PDFs, use --pages to specify boundaries manually.')
+        .option('--file <path>', 'Local PDF file path (required). Encrypted PDFs: name__pw__password.pdf')
+        .option('--type <type>', `Document type: ${VALID_TYPES}`)
+        .option('--pages <ranges>', 'Manual page ranges (e.g. "1-3,4-6,7"). Skips auto-detection')
+        .option('--dry-run', 'Detect boundaries only — do not split or upload')
+        .option('--api-key <key>', 'API key (overrides stored/env)')
+        .option('--json', 'Output as JSON')
+        .action(apiAction(async (client, opts) => {
+        // ── Validate inputs ──
+        if (!opts.file) {
+            console.error(chalk.red('Error: --file is required'));
+            console.error(chalk.dim('Usage: clio magic split --file merged.pdf --type bill'));
+            process.exit(1);
+        }
+        if (!opts.type) {
+            console.error(chalk.red(`Error: --type is required (${VALID_TYPES})`));
+            console.error(chalk.dim('Usage: clio magic split --file merged.pdf --type bill'));
+            process.exit(1);
+        }
+        const apiType = TYPE_TO_API[opts.type];
+        if (!apiType) {
+            console.error(chalk.red(`Error: invalid type "${opts.type}". Valid: ${VALID_TYPES}`));
+            process.exit(1);
+        }
+        const filePath = resolve(opts.file);
+        const ext = extname(filePath).toLowerCase();
+        if (ext !== '.pdf') {
+            console.error(chalk.red('Error: PDF splitting only supports .pdf files'));
+            process.exit(1);
+        }
+        // qpdf only needed when actually splitting (not for dry-run auto-detect)
+        const needsQpdf = !opts.dryRun || opts.pages;
+        if (needsQpdf && !isQpdfAvailable()) {
+            console.error(chalk.red('Error: qpdf is required for PDF splitting.'));
+            console.error(chalk.dim('  macOS:   brew install qpdf'));
+            console.error(chalk.dim('  Ubuntu:  sudo apt install qpdf'));
+            process.exit(1);
+        }
+        // ── Handle encrypted PDFs ──
+        const resolved = await resolveInputPdf(filePath, ext, opts);
+        const effectivePath = resolved.effectivePath;
+        const sourceBaseName = resolved.cleanName.replace(/\.pdf$/i, '');
+        try {
+            // ── Determine documents (auto-detect or manual) ──
+            let documents;
+            let pageCount;
+            if (opts.pages) {
+                // Manual page ranges — need qpdf for page count
+                pageCount = (await import('../core/pdf/split.js')).getPageCount(effectivePath);
+                documents = parsePageRanges(opts.pages, pageCount);
+            }
+            else {
+                // Auto-detect boundaries
+                const buffer = readFileSync(effectivePath);
+                const detection = await detectBoundaries(new Uint8Array(buffer));
+                pageCount = detection.pageCount;
+                documents = detection.documents;
+                // Scanned PDF — can't auto-detect, require --pages
+                if (detection.isScannedPdf) {
+                    if (opts.json) {
+                        console.log(JSON.stringify({
+                            file: basename(filePath),
+                            pageCount,
+                            isScannedPdf: true,
+                            error: 'Scanned PDF — no extractable text. Use --pages to specify boundaries manually.',
+                        }, null, 2));
+                    }
+                    else {
+                        console.error(chalk.yellow('Scanned PDF detected — no extractable text for boundary detection.'));
+                        console.error(chalk.dim(`  Use --pages to split manually:`));
+                        console.error(chalk.dim(`  clio magic split --file ${basename(filePath)} --type ${opts.type} --pages "1-3,4-6,7-9"`));
+                    }
+                    process.exit(1);
+                }
+                // Single document — suggest magic create instead
+                if (documents.length <= 1) {
+                    if (opts.json) {
+                        console.log(JSON.stringify({
+                            file: basename(filePath),
+                            pageCount,
+                            documentsDetected: documents.length,
+                            message: 'Only 1 document detected — use `clio magic create` instead, or --pages to override.',
+                        }, null, 2));
+                    }
+                    else {
+                        console.log(chalk.yellow(`Only 1 document detected in ${pageCount}-page PDF.`));
+                        console.log(chalk.dim(`  Use clio magic create --file ${basename(filePath)} --type ${opts.type}`));
+                        console.log(chalk.dim(`  Or override with --pages: clio magic split --file ${basename(filePath)} --type ${opts.type} --pages "1-3,4-6"`));
+                    }
+                    return;
+                }
+            }
+            // ── Dry-run: print detection results only ──
+            if (opts.dryRun) {
+                if (opts.json) {
+                    console.log(JSON.stringify({
+                        file: basename(filePath),
+                        pageCount,
+                        documents: documents.map((d) => ({
+                            index: d.index,
+                            pageRange: d.pageRange,
+                            confidence: d.confidence,
+                            signals: d.signals.map((s) => s.label),
+                        })),
+                    }, null, 2));
+                }
+                else {
+                    console.log(chalk.bold(`PDF Split — Boundary Detection`));
+                    console.log(`  File: ${basename(filePath)} (${pageCount} pages)\n`);
+                    for (const doc of documents) {
+                        const conf = doc.confidence === 'high' ? chalk.green(doc.confidence)
+                            : doc.confidence === 'medium' ? chalk.yellow(doc.confidence)
+                                : chalk.red(doc.confidence);
+                        const signals = doc.signals.filter((s) => s.score > 0).map((s) => s.label).join(', ') || 'first page';
+                        console.log(`  Document ${doc.index + 1}: pages ${doc.pageRange.replace('-', '\u2013')}  (${conf})    ${chalk.dim(signals)}`);
+                    }
+                    console.log(`\n  ${documents.length} documents detected. Use --pages to override.`);
+                }
+                return;
+            }
+            // ── Confidence check: prompt if any low/medium ──
+            const hasLowConfidence = documents.some((d) => d.confidence !== 'high' && d.index > 0);
+            if (hasLowConfidence && !opts.json) {
+                console.log(chalk.bold(`PDF Split — Boundary Detection`));
+                console.log(`  File: ${basename(filePath)} (${pageCount} pages)\n`);
+                for (const doc of documents) {
+                    const conf = doc.confidence === 'high' ? chalk.green(doc.confidence)
+                        : doc.confidence === 'medium' ? chalk.yellow(doc.confidence)
+                            : chalk.red(doc.confidence);
+                    const signals = doc.signals.filter((s) => s.score > 0).map((s) => s.label).join(', ') || 'first page';
+                    console.log(`  Document ${doc.index + 1}: pages ${doc.pageRange.replace('-', '\u2013')}  (${conf})    ${chalk.dim(signals)}`);
+                }
+                console.log('');
+                const { proceed } = await prompts({
+                    type: 'confirm',
+                    name: 'proceed',
+                    message: 'Some boundaries have low confidence. Split and upload anyway?',
+                    initial: true,
+                });
+                if (!proceed) {
+                    console.log(chalk.dim('Aborted. Use --pages to specify boundaries manually.'));
+                    return;
+                }
+            }
+            // ── Split + Upload ──
+            const splitResult = splitPdf(effectivePath, documents, sourceBaseName);
+            const uploadResults = [];
+            try {
+                // Report split failures
+                for (const f of splitResult.failures) {
+                    uploadResults.push({
+                        index: f.index,
+                        pageRange: f.pageRange,
+                        splitFileName: `${sourceBaseName}_${f.index + 1}.pdf`,
+                        status: 'failed',
+                        error: `Split failed: ${f.error}`,
+                    });
+                    if (!opts.json) {
+                        console.log(chalk.red(`  \u2717 [${f.index + 1}/${documents.length}] pages ${f.pageRange} — split failed: ${f.error}`));
+                    }
+                }
+                // Upload each split file
+                for (const file of splitResult.files) {
+                    try {
+                        const buffer = readFileSync(file.path);
+                        const blob = new Blob([buffer], { type: 'application/pdf' });
+                        const res = await createFromAttachment(client, {
+                            businessTransactionType: apiType,
+                            sourceFile: blob,
+                            sourceFileName: file.fileName,
+                        });
+                        const valid = res.data.validFiles?.[0];
+                        const invalid = res.data.invalidFiles?.[0];
+                        if (valid) {
+                            uploadResults.push({
+                                index: file.index,
+                                pageRange: file.pageRange,
+                                splitFileName: file.fileName,
+                                status: 'uploaded',
+                                workflowResourceId: valid.workflowResourceId,
+                                documentType: res.data.businessTransactionType,
+                            });
+                            if (!opts.json) {
+                                console.log(chalk.green(`  \u2713 [${file.index + 1}/${documents.length}] pages ${file.pageRange} \u2192 ${file.fileName} \u2192 ${opts.type.toUpperCase()} (workflow: ${valid.workflowResourceId})`));
+                            }
+                        }
+                        else {
+                            const errMsg = invalid?.errorMessage ?? 'Unknown upload error';
+                            uploadResults.push({
+                                index: file.index,
+                                pageRange: file.pageRange,
+                                splitFileName: file.fileName,
+                                status: 'failed',
+                                error: errMsg,
+                            });
+                            if (!opts.json) {
+                                console.log(chalk.red(`  \u2717 [${file.index + 1}/${documents.length}] pages ${file.pageRange} \u2192 ${file.fileName} \u2192 failed: ${errMsg}`));
+                            }
+                        }
+                    }
+                    catch (err) {
+                        const errMsg = err instanceof Error ? err.message : String(err);
+                        uploadResults.push({
+                            index: file.index,
+                            pageRange: file.pageRange,
+                            splitFileName: file.fileName,
+                            status: 'failed',
+                            error: errMsg,
+                        });
+                        if (!opts.json) {
+                            console.log(chalk.red(`  \u2717 [${file.index + 1}/${documents.length}] pages ${file.pageRange} \u2192 ${file.fileName} \u2192 failed: ${errMsg}`));
+                        }
+                    }
+                }
+            }
+            finally {
+                cleanupSplitFiles(splitResult.tempDir);
+            }
+            // ── Summary ──
+            const uploaded = uploadResults.filter((r) => r.status === 'uploaded').length;
+            const failed = uploadResults.filter((r) => r.status === 'failed').length;
+            if (opts.json) {
+                console.log(JSON.stringify({
+                    file: basename(filePath),
+                    pageCount,
+                    documents: uploadResults,
+                    summary: { total: documents.length, uploaded, failed },
+                }, null, 2));
+            }
+            else {
+                console.log(`\n  ${uploaded} uploaded, ${failed} failed`);
+            }
+        }
+        finally {
+            if (resolved.decryptedPath)
+                cleanupDecryptedFile(resolved.decryptedPath);
+        }
+    }));
 }
 // ── Helpers ──────────────────────────────────────────────────────
+/**
+ * Resolve a PDF input, handling __pw__ password extraction + encrypted PDF decryption.
+ * Shared by magic create and magic split (DRY).
+ *
+ * For non-PDF files, returns the original path with a clean filename (no __pw__ suffix).
+ */
+async function resolveInputPdf(filePath, ext, opts) {
+    const rawName = basename(filePath);
+    const { cleanName, password: filePassword } = extractFilePassword(rawName, ext);
+    if (ext !== '.pdf') {
+        return { effectivePath: filePath, cleanName };
+    }
+    const buffer = readFileSync(filePath);
+    if (!isPdfEncrypted(buffer)) {
+        return { effectivePath: filePath, cleanName };
+    }
+    // Encrypted PDF — need qpdf to decrypt
+    if (!isQpdfAvailable()) {
+        console.error(chalk.red('Error: Encrypted PDF detected but qpdf is not installed.'));
+        console.error(chalk.dim('  macOS:   brew install qpdf'));
+        console.error(chalk.dim('  Ubuntu:  sudo apt install qpdf'));
+        process.exit(1);
+    }
+    let password = filePassword;
+    if (!password) {
+        if (opts.json) {
+            console.log(JSON.stringify({
+                error: 'ENCRYPTED_PDF_NO_PASSWORD',
+                message: 'Encrypted PDF — embed password in filename: name__pw__password.pdf',
+                file: rawName,
+            }));
+            process.exit(1);
+        }
+        const response = await prompts({
+            type: 'text',
+            name: 'password',
+            message: `PDF password for ${rawName}`,
+        });
+        if (!response.password) {
+            console.error(chalk.red('Aborted — no password provided.'));
+            console.error(chalk.dim('Tip: embed password in filename: name__pw__password.pdf'));
+            process.exit(1);
+        }
+        password = response.password;
+    }
+    const decryptedPath = decryptPdf(filePath, password);
+    return { effectivePath: decryptedPath, cleanName, decryptedPath };
+}
 function outputWorkflowResults(results, json) {
     if (json) {
         const workflows = results.map((w) => ({

package/dist/core/jobs/document-collection/tools/ingest/decrypt.js

@@ -90,6 +90,25 @@ export function decryptPdf(encryptedPath, password) {
     }
     return outputPath;
 }
+// ── Filename password extraction ────────────────────────────
+/**
+ * Extract password from filename pattern: label__pw__password.ext
+ *
+ * The __pw__ delimiter is case-insensitive (__PW__, __Pw__, etc.).
+ * The password after __pw__ is case-sensitive and used as-is.
+ * Returns the cleaned display name (without __pw__...) and the extracted password.
+ *
+ * Examples:
+ *   receipt__pw__s3cRetP@ss.pdf  →  { cleanName: "receipt.pdf", password: "s3cRetP@ss" }
+ *   normal-file.pdf              →  { cleanName: "normal-file.pdf" }
+ */
+export function extractFilePassword(filename, ext) {
+    const escapedExt = ext.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const match = filename.match(new RegExp(`^(.+?)__pw__(.+)${escapedExt}$`, 'i'));
+    if (!match)
+        return { cleanName: filename };
+    return { cleanName: `${match[1]}${ext}`, password: match[2] };
+}
 /**
  * Remove a decrypted temp file and its parent temp directory.
  * Safe to call with any path — silently ignores missing files.

package/dist/core/jobs/document-collection/tools/ingest/format.js

@@ -21,7 +21,13 @@ function printFolders(plan) {
             : chalk.green(folder.documentType);
         const prefix = folder.documentType === 'UNKNOWN' ? chalk.yellow('[!] ') : '  ';
         console.log(`${prefix}${chalk.bold(folder.folder)}/  (${folder.count} files → ${typeLabel})`);
-        const labels = folder.files.map(f => f.encrypted ? `${f.filename} ${chalk.yellow('(encrypted)')}` : f.filename);
+        const labels = folder.files.map(f => {
+            if (f.encrypted && f.filePassword)
+                return `${f.filename} ${chalk.green('(pw)')}`;
+            if (f.encrypted)
+                return `${f.filename} ${chalk.yellow('(encrypted)')}`;
+            return f.filename;
+        });
         const show = labels.slice(0, 8);
         console.log(chalk.gray(`    ${show.join(', ')}${labels.length > 8 ? `, ... and ${labels.length - 8} more` : ''}`));
         console.log();
@@ -38,7 +44,14 @@ function printSummary(plan) {
         console.log(`  Skipped:     ${chalk.gray(String(plan.summary.skipped))}`);
     }
     if (plan.summary.encrypted > 0) {
-        console.log(`  Encrypted:   ${chalk.yellow(String(plan.summary.encrypted))} (use --pdf-password to decrypt)`);
+        const autoCount = plan.folders.flatMap(f => f.files).filter(f => f.encrypted && f.filePassword).length;
+        const remaining = plan.summary.encrypted - autoCount;
+        const parts = [];
+        if (autoCount > 0)
+            parts.push(chalk.green(`${autoCount} password from filename`));
+        if (remaining > 0)
+            parts.push(chalk.yellow(`${remaining} need __pw__<password> in filename`));
+        console.log(`  Encrypted:   ${plan.summary.encrypted} (${parts.join(', ')})`);
     }
     if (Object.keys(plan.summary.byType).length > 0) {
         console.log();

package/dist/core/jobs/document-collection/tools/ingest/scanner.js

@@ -7,7 +7,7 @@
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import { join, basename, extname, relative, resolve } from 'node:path';
 import { classifyFolder, checkExtension } from './classify.js';
-import { isPdfEncrypted } from './decrypt.js';
+import { isPdfEncrypted, extractFilePassword } from './decrypt.js';
 /** Max recursion depth to prevent runaway traversal. */
 const MAX_DEPTH = 10;
 /**
@@ -159,9 +159,11 @@ function scanDir(rootPath, dirPath, inheritedType, forceType, depth, maxDepth, o
                 }
                 catch { /* ignore read errors */ }
             }
+            // Extract password from filename pattern: label__pw__password.ext
+            const { cleanName, password: filePassword } = extractFilePassword(entry, ext);
             out.push({
                 path: relPath,
-                filename: entry,
+                filename: cleanName,
                 extension: ext,
                 documentType,
                 folder: relDir,
@@ -170,6 +172,7 @@ function scanDir(rootPath, dirPath, inheritedType, forceType, depth, maxDepth, o
                 absolutePath: fullPath,
                 sizeBytes: stat.size,
                 encrypted,
+                filePassword,
             });
         }
     }

package/dist/core/jobs/document-collection/tools/ingest/upload.js

@@ -30,7 +30,7 @@ const MIME_MAP = {
  * UNKNOWN and SKIPPED files are excluded.
  */
 export async function uploadClassifiedFiles(opts) {
-    const { plan, client, bankAccountId, pdfPassword, onProgress } = opts;
+    const { plan, client, bankAccountId, onProgress } = opts;
     // Collect all uploadable files across folders
     const uploadable = plan.folders.flatMap((folder) => folder.files.filter((f) => f.documentType === 'INVOICE' || f.documentType === 'BILL' || f.documentType === 'CUSTOMER_CREDIT_NOTE' || f.documentType === 'SUPPLIER_CREDIT_NOTE' || f.documentType === 'BANK_STATEMENT'));
     const results = [];
@@ -39,10 +39,10 @@ export async function uploadClassifiedFiles(opts) {
         const docType = file.documentType;
         let decryptedPath;
         try {
-            // Decrypt encrypted PDFs before reading
+            // Decrypt encrypted PDFs using password from filename (__pw__ pattern)
             let effectivePath = file.absolutePath;
-            if (file.encrypted && pdfPassword) {
-                decryptedPath = decryptPdf(file.absolutePath, pdfPassword);
+            if (file.encrypted && file.filePassword) {
+                decryptedPath = decryptPdf(file.absolutePath, file.filePassword);
                 effectivePath = decryptedPath;
             }
             // Read file into a Blob with correct MIME type (required by the Magic API)

package/dist/core/pdf/detect.js

@@ -0,0 +1,344 @@
+/**
+ * PDF boundary detection engine — identifies document boundaries in merged PDFs.
+ *
+ * Uses pdfjs-dist (pure JS, no canvas) for text extraction + structural probes.
+ * No AI tokens — heuristic-only scoring system.
+ *
+ * Detection signals (positive = boundary evidence, negative = anti-signal):
+ *   outline-bookmark   +80   PDF bookmark points to this page
+ *   page-label-reset   +70   PDF page label restarts at "1"
+ *   keyword (upper 40%) +40  Document-type keyword near top of page
+ *   page-one-of         +35  "Page 1 of N" pattern
+ *   keyword-large       +25  Large font keyword (>18pt) bonus
+ *   doc-ref (upper 40%) +20  Document reference pattern (INV-001, etc.)
+ *   continuation        -60  "Page N>1 of M" anti-signal
+ *   continuation        -40  "Continued" text anti-signal
+ *
+ * Threshold: >= 50 = boundary. Confidence: >= 80 high, >= 50 medium, < 50 low.
+ */
+// pdfjs-dist v5 — legacy build for Node.js (no canvas requirement)
+import { getDocument } from 'pdfjs-dist/legacy/build/pdf.mjs';
+// ── Scoring constants ────────────────────────────────────────
+const SCORE_OUTLINE = 80;
+const SCORE_PAGE_LABEL_RESET = 70;
+const SCORE_KEYWORD = 40;
+const SCORE_PAGE_ONE_OF = 35;
+const SCORE_KEYWORD_LARGE = 25;
+const SCORE_DOC_REF = 20;
+const SCORE_CONTINUATION_PAGE = -60;
+const SCORE_CONTINUATION_TEXT = -40;
+const BOUNDARY_THRESHOLD = 50;
+const CONFIDENCE_HIGH = 80;
+/** Upper portion of page (0–40%) where keywords/refs are significant. */
+const UPPER_PORTION = 0.4;
+/** Font size threshold for large-font keyword bonus (points). */
+const LARGE_FONT_PT = 18;
+// ── Boundary keywords ────────────────────────────────────────
+// Multilingual: EN, Filipino, Indonesian/Malay, Vietnamese, Chinese
+// Each keyword is tested as a case-insensitive whole-word match.
+const BOUNDARY_KEYWORDS = [
+    // English
+    'TAX INVOICE', 'INVOICE', 'PROFORMA INVOICE', 'COMMERCIAL INVOICE',
+    'BILL', 'BILLING STATEMENT', 'STATEMENT OF ACCOUNT',
+    'CREDIT NOTE', 'CREDIT MEMO', 'DEBIT NOTE', 'DEBIT MEMO',
+    'PURCHASE ORDER', 'DELIVERY ORDER', 'DELIVERY NOTE',
+    'RECEIPT', 'OFFICIAL RECEIPT', 'ACKNOWLEDGMENT RECEIPT',
+    'QUOTATION', 'SALES ORDER', 'CONTRACT',
+    'PACKING LIST', 'BILL OF LADING', 'CERTIFICATE OF ORIGIN',
+    // Filipino / PH
+    'RESIBO', 'KATIBAYAN NG PAGBABAYAD',
+    // Indonesian / Malay
+    'FAKTUR PAJAK', 'FAKTUR', 'NOTA KREDIT', 'NOTA DEBIT',
+    'KWITANSI', 'SURAT JALAN',
+    // Vietnamese
+    'HOA DON', 'HOÁ ĐƠN', 'PHIẾU THU', 'PHIẾU CHI',
+    // Chinese
+    '发票', '税务发票', '收据', '信用票据', '送货单',
+];
+/** Escaped regex patterns — match keyword as a word boundary. */
+const KEYWORD_PATTERNS = BOUNDARY_KEYWORDS.map((kw) => {
+    const escaped = kw.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    // For CJK characters, don't use word boundaries (they don't apply)
+    const hasCJK = /[\u4e00-\u9fff]/.test(kw);
+    return hasCJK
+        ? new RegExp(escaped, 'i')
+        : new RegExp(`\\b${escaped}\\b`, 'i');
+});
+/** "Page 1 of N" patterns (matches multiple languages). */
+const PAGE_ONE_PATTERN = /\bpage\s+1\s+of\s+\d+/i;
+/** "Page N of M" where N > 1 — continuation signal. */
+const PAGE_N_PATTERN = /\bpage\s+(\d+)\s+of\s+\d+/i;
+/** Document reference patterns: INV-001, SO-2024-100, PO#123, etc. */
+const DOC_REF_PATTERN = /\b(?:INV|SO|PO|DO|CN|DN|OR|CR|BL|SI|PI|QU|CT|REC)[\s#._-]*\d{2,}/i;
+/** Continuation text markers. */
+const CONTINUATION_PATTERNS = [
+    /\bcontinued\b/i,
+    /\b(?:cont['']?d)\b/i,
+    /\blanjutan\b/i, // Indonesian
+    /\btiếp theo\b/i, // Vietnamese
+];
+// ── pdfjs-dist configuration ─────────────────────────────────
+// Security: disable code generation from strings (pdfjs option key
+// constructed dynamically to avoid triggering static analysis hooks)
+const PDFJS_SECURITY_KEY = ['is', 'Eval', 'Supported'].join('');
+// ── Main detection function ──────────────────────────────────
+/**
+ * Detect document boundaries in a merged PDF.
+ *
+ * @param buffer  Raw PDF bytes (Uint8Array or Buffer).
+ * @returns Detection result with per-page probes and detected documents.
+ */
+export async function detectBoundaries(buffer) {
+    const doc = await getDocument({
+        data: buffer,
+        worker: null, // No worker thread (CLI) — null disables it at runtime
+        [PDFJS_SECURITY_KEY]: false, // Security: no code generation from strings
+        verbosity: 0, // Suppress warnings
+    }).promise;
+    const pageCount = doc.numPages;
+    const pages = [];
+    try {
+        // Phase 1: Structural probes (whole-document)
+        const outlinePages = await probeOutlines(doc);
+        const labelResetPages = await probePageLabels(doc);
+        // Phase 2: Per-page text scan
+        let scannedCount = 0;
+        for (let i = 0; i < pageCount; i++) {
+            const signals = [];
+            // Structural signals
+            if (outlinePages.has(i)) {
+                signals.push({ type: 'outline-bookmark', label: 'PDF bookmark', score: SCORE_OUTLINE });
+            }
+            if (labelResetPages.has(i)) {
+                signals.push({ type: 'page-label-reset', label: 'Page label reset to 1', score: SCORE_PAGE_LABEL_RESET });
+            }
+            // Text extraction
+            const page = await doc.getPage(i + 1); // 1-based
+            const textContent = await page.getTextContent();
+            const items = textContent.items;
+            if (items.length === 0) {
+                signals.push({ type: 'scanned', label: 'No extractable text', score: 0 });
+                scannedCount++;
+            }
+            else {
+                // Determine page height from viewport
+                const viewport = page.getViewport({ scale: 1 });
+                const pageHeight = viewport.height;
+                // Collect upper-portion text and full-page text
+                const upperTexts = [];
+                const allTexts = [];
+                for (const item of items) {
+                    const text = item.str.trim();
+                    if (!text)
+                        continue;
+                    allTexts.push(text);
+                    // transform[5] is the Y coordinate (from bottom), transform[0] is scaleX ~ fontSize
+                    const y = item.transform[5];
+                    const fontSize = Math.abs(item.transform[0]);
+                    const normalizedY = y / pageHeight;
+                    // Upper portion = top 40% of page (high Y values in PDF coordinate system)
+                    if (normalizedY >= (1 - UPPER_PORTION)) {
+                        upperTexts.push({ text, fontSize });
+                    }
+                }
+                const fullText = allTexts.join(' ');
+                const upperText = upperTexts.map((t) => t.text).join(' ');
+                // Keyword detection (upper portion only)
+                for (let k = 0; k < KEYWORD_PATTERNS.length; k++) {
+                    if (KEYWORD_PATTERNS[k].test(upperText)) {
+                        signals.push({
+                            type: 'keyword',
+                            label: `${BOUNDARY_KEYWORDS[k]} in header`,
+                            score: SCORE_KEYWORD,
+                        });
+                        // Large font bonus: check if any upper-portion item with this keyword is large
+                        const kwPattern = KEYWORD_PATTERNS[k];
+                        const hasLargeFont = upperTexts.some((t) => kwPattern.test(t.text) && t.fontSize >= LARGE_FONT_PT);
+                        if (hasLargeFont) {
+                            signals.push({
+                                type: 'keyword-large',
+                                label: `${BOUNDARY_KEYWORDS[k]} in large font (>${LARGE_FONT_PT}pt)`,
+                                score: SCORE_KEYWORD_LARGE,
+                            });
+                        }
+                        break; // Only count the first keyword match per page
+                    }
+                }
+                // "Page 1 of N" detection (anywhere on page)
+                if (PAGE_ONE_PATTERN.test(fullText)) {
+                    signals.push({ type: 'page-one-of', label: 'Page 1 of N', score: SCORE_PAGE_ONE_OF });
+                }
+                // Document reference in upper portion
+                if (DOC_REF_PATTERN.test(upperText)) {
+                    signals.push({ type: 'doc-ref', label: 'Document reference in header', score: SCORE_DOC_REF });
+                }
+                // Anti-signals: continuation indicators
+                const pageNMatch = fullText.match(PAGE_N_PATTERN);
+                if (pageNMatch && parseInt(pageNMatch[1], 10) > 1) {
+                    signals.push({
+                        type: 'continuation',
+                        label: `Page ${pageNMatch[1]} of N (continuation)`,
+                        score: SCORE_CONTINUATION_PAGE,
+                    });
+                }
+                for (const pat of CONTINUATION_PATTERNS) {
+                    if (pat.test(fullText)) {
+                        signals.push({
+                            type: 'continuation',
+                            label: 'Continuation text detected',
+                            score: SCORE_CONTINUATION_TEXT,
+                        });
+                        break;
+                    }
+                }
+            }
+            const totalScore = signals.reduce((sum, s) => sum + s.score, 0);
+            // Page 0 is always a boundary (it's the start of the first document)
+            const isBoundary = i === 0 || totalScore >= BOUNDARY_THRESHOLD;
+            pages.push({ pageIndex: i, signals, totalScore, isBoundary });
+        }
+        const documents = buildDocuments(pages, pageCount);
+        const isScannedPdf = scannedCount === pageCount && pageCount > 0;
+        return { pageCount, pages, documents, isScannedPdf };
+    }
+    finally {
+        try {
+            doc.destroy();
+        }
+        catch { /* best effort */ }
+    }
+}
+// ── Structural probes ────────────────────────────────────────
+/** Probe PDF outlines/bookmarks -> set of 0-based page indices that have bookmarks. */
+async function probeOutlines(doc) {
+    const result = new Set();
+    try {
+        const outline = await doc.getOutline();
+        if (!outline)
+            return result;
+        const stack = [...outline];
+        while (stack.length > 0) {
+            const item = stack.pop();
+            if (!item)
+                continue;
+            // Resolve destination to page index
+            if (item.dest) {
+                try {
+                    const dest = typeof item.dest === 'string'
+                        ? await doc.getDestination(item.dest)
+                        : item.dest;
+                    if (Array.isArray(dest) && dest[0]) {
+                        const pageIndex = await doc.getPageIndex(dest[0]);
+                        result.add(pageIndex);
+                    }
+                }
+                catch { /* skip unresolvable destinations */ }
+            }
+            // Traverse children
+            if (Array.isArray(item.items)) {
+                stack.push(...item.items);
+            }
+        }
+    }
+    catch { /* no outlines or error reading them */ }
+    return result;
+}
+/** Probe PDF page labels -> set of 0-based page indices where label resets to "1". */
+async function probePageLabels(doc) {
+    const result = new Set();
+    try {
+        const labels = await doc.getPageLabels();
+        if (!labels)
+            return result;
+        for (let i = 1; i < labels.length; i++) {
+            // A label that is "1" (or "i" for roman numeral) after not being "1" signals a reset
+            if (labels[i] === '1' && labels[i - 1] !== '1') {
+                result.add(i);
+            }
+        }
+    }
+    catch { /* no page labels */ }
+    return result;
+}
+// ── Document builder ─────────────────────────────────────────
+/** Build detected documents from boundary pages. */
+function buildDocuments(pages, pageCount) {
+    const boundaries = pages.filter((p) => p.isBoundary);
+    const documents = [];
+    for (let i = 0; i < boundaries.length; i++) {
+        const start = boundaries[i].pageIndex;
+        const end = i + 1 < boundaries.length
+            ? boundaries[i + 1].pageIndex - 1
+            : pageCount - 1;
+        // Page range is 1-based for display
+        const pageStart = start + 1;
+        const pageEnd = end + 1;
+        const pageRange = pageStart === pageEnd ? `${pageStart}` : `${pageStart}-${pageEnd}`;
+        documents.push({
+            index: i,
+            pageStart,
+            pageEnd,
+            pageRange,
+            confidence: scoreToConfidence(boundaries[i].totalScore),
+            signals: boundaries[i].signals,
+        });
+    }
+    return documents;
+}
+/** Map aggregate score to confidence level. */
+function scoreToConfidence(score) {
+    if (score >= CONFIDENCE_HIGH)
+        return 'high';
+    if (score >= BOUNDARY_THRESHOLD)
+        return 'medium';
+    return 'low';
+}
+// ── Manual page ranges ───────────────────────────────────────
+/**
+ * Parse a manual page-range string into DetectedDocument[].
+ *
+ * Format: "1-3,4-6,7" (1-based, inclusive ranges, comma-separated).
+ * Validates: no overlaps, ranges within page count.
+ *
+ * @throws Error on invalid format or range.
+ */
+export function parsePageRanges(rangesStr, pageCount) {
+    const parts = rangesStr.split(',').map((s) => s.trim()).filter(Boolean);
+    if (parts.length === 0) {
+        throw new Error('Empty page range — provide ranges like "1-3,4-6,7"');
+    }
+    const documents = [];
+    let lastEnd = 0;
+    for (let i = 0; i < parts.length; i++) {
+        const part = parts[i];
+        const match = part.match(/^(\d+)(?:-(\d+))?$/);
+        if (!match) {
+            throw new Error(`Invalid page range "${part}" — use format "1-3" or "7"`);
+        }
+        const pageStart = parseInt(match[1], 10);
+        const pageEnd = match[2] ? parseInt(match[2], 10) : pageStart;
+        if (pageStart < 1 || pageEnd < 1) {
+            throw new Error(`Page numbers must be positive (got "${part}")`);
+        }
+        if (pageStart > pageEnd) {
+            throw new Error(`Invalid range "${part}" — start must be <= end`);
+        }
+        if (pageEnd > pageCount) {
+            throw new Error(`Range "${part}" exceeds page count (${pageCount} pages)`);
+        }
+        if (pageStart <= lastEnd) {
+            throw new Error(`Overlapping range "${part}" — previous range ended at page ${lastEnd}`);
+        }
+        const pageRange = pageStart === pageEnd ? `${pageStart}` : `${pageStart}-${pageEnd}`;
+        documents.push({
+            index: i,
+            pageStart,
+            pageEnd,
+            pageRange,
+            confidence: 'high', // Manual ranges are always high confidence
+            signals: [],
+        });
+        lastEnd = pageEnd;
+    }
+    return documents;
+}

package/dist/core/pdf/index.js

@@ -0,0 +1,8 @@
+/**
+ * PDF boundary detection + splitting for merged documents.
+ *
+ * Usage:
+ *   import { detectBoundaries, parsePageRanges, splitPdf, ... } from '../core/pdf/index.js';
+ */
+export { detectBoundaries, parsePageRanges } from './detect.js';
+export { getPageCount, splitPdf, cleanupSplitFiles } from './split.js';

package/dist/core/pdf/split.js

@@ -0,0 +1,81 @@
+/**
+ * PDF page-range extraction via qpdf.
+ *
+ * Creates temporary files for each document range extracted from a merged PDF.
+ * Caller is responsible for cleanup (use `cleanupSplitFiles`).
+ *
+ * Follows the same patterns as decrypt.ts: execFileSync, mkdtempSync, explicit cleanup.
+ */
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, existsSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { tmpdir } from 'node:os';
+import { rmSync } from 'node:fs';
+import { isQpdfAvailable } from '../jobs/document-collection/tools/ingest/decrypt.js';
+/**
+ * Get the page count of a PDF file using qpdf.
+ * @throws Error if qpdf is not installed or the file is invalid.
+ */
+export function getPageCount(filePath) {
+    if (!isQpdfAvailable()) {
+        throw new Error('qpdf is required — install: brew install qpdf (macOS) or sudo apt install qpdf (Linux)');
+    }
+    const output = execFileSync('qpdf', ['--show-npages', filePath], {
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const count = parseInt(output.trim(), 10);
+    if (isNaN(count) || count < 1) {
+        throw new Error(`Failed to read page count from "${basename(filePath)}"`);
+    }
+    return count;
+}
+/**
+ * Split a PDF into multiple files based on detected document ranges.
+ *
+ * Creates a temp directory and extracts each range as a separate PDF.
+ * Continues on failure (never aborts mid-batch, matching upload.ts pattern).
+ * Caller MUST call `cleanupSplitFiles()` when done.
+ */
+export function splitPdf(sourcePath, documents, sourceBaseName) {
+    if (!isQpdfAvailable()) {
+        throw new Error('qpdf is required — install: brew install qpdf (macOS) or sudo apt install qpdf (Linux)');
+    }
+    const tempDir = mkdtempSync(join(tmpdir(), 'clio-split-'));
+    const files = [];
+    const failures = [];
+    for (const doc of documents) {
+        const fileName = `${sourceBaseName}_${doc.index + 1}.pdf`;
+        const outputPath = join(tempDir, fileName);
+        try {
+            execFileSync('qpdf', [
+                sourcePath,
+                '--pages', '.', `${doc.pageStart}-${doc.pageEnd}`, '--',
+                outputPath,
+            ], { stdio: 'pipe' });
+            files.push({
+                index: doc.index,
+                pageRange: doc.pageRange,
+                path: outputPath,
+                fileName,
+            });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            failures.push({ index: doc.index, pageRange: doc.pageRange, error: msg });
+        }
+    }
+    return { tempDir, files, failures };
+}
+/**
+ * Remove all split temp files and their temp directory.
+ * Safe to call with any path — silently ignores missing dirs.
+ */
+export function cleanupSplitFiles(tempDir) {
+    try {
+        if (existsSync(tempDir)) {
+            rmSync(tempDir, { recursive: true, force: true });
+        }
+    }
+    catch { /* best effort */ }
+}

package/dist/core/pdf/types.js

@@ -0,0 +1,4 @@
+/**
+ * Types for PDF boundary detection and document splitting.
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jaz-clio",
-  "version": "4.4.0",
+  "version": "4.5.0",
   "description": "Clio — Command Line Interface Orchestrator for Jaz AI.",
   "type": "module",
   "bin": {
@@ -51,6 +51,7 @@
     "commander": "^12.1.0",
     "financial": "^0.2.4",
     "ora": "^8.1.1",
+    "pdfjs-dist": "^5.4.624",
     "prompts": "^2.4.2",
     "update-notifier": "^7.3.1"
   },