jaz-clio 3.3.0 → 3.4.0

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: api
-version: 3.3.0
+version: 3.4.0
 description: Complete reference for the Jaz/Juan 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/Juan API key (x-jk-api-key header). Works with Claude Code, Claude Cowork, Claude.ai, and any agent that reads markdown.

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: conversion
-version: 3.3.0
+version: 3.4.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: jobs
-version: 3.3.0
+version: 3.4.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 transaction-recipes skill.
@@ -41,7 +41,7 @@ Period-close jobs build on each other. Quarter = month + extras. Year = quarter
 | Job | CLI Command | Description |
 |-----|-------------|-------------|
 | **Bank Recon** | `clio jobs bank-recon` | Clear unreconciled items: match, categorize, resolve. Paired tool: `clio jobs bank-recon match`. |
-| **Document Collection** | `clio jobs document-collection` | Scan, classify, and upload client documents (invoices, bills, bank statements). Paired tool: `clio jobs document-collection ingest`. |
+| **Document Collection** | `clio jobs document-collection` | Scan and classify client documents from local directories and cloud links (Dropbox, Drive, OneDrive). Outputs file paths for agent upload. Paired tool: `clio jobs document-collection ingest`. |
 | **GST/VAT Filing** | `clio jobs gst-vat --period YYYY-QN` | Tax ledger review, discrepancy check, filing summary. |
 | **Payment Run** | `clio jobs payment-run` | Select outstanding bills by due date, process payments. |
 | **Credit Control** | `clio jobs credit-control` | AR aging review, overdue chase list, bad debt assessment. |
@@ -99,6 +99,8 @@ clio jobs fa-review [--json]
 - **[references/quarter-end-close.md](./references/quarter-end-close.md)** — Quarter-end close: monthly + quarterly extras
 - **[references/year-end-close.md](./references/year-end-close.md)** — Year-end close: quarterly + annual extras
 - **[references/bank-recon.md](./references/bank-recon.md)** — Bank reconciliation catch-up
+- **[references/bank-match.md](./references/bank-match.md)** — Bank reconciliation matcher: 5-phase cascade algorithm (1:1, N:1, 1:N, N:M matches)
+- **[references/document-collection.md](./references/document-collection.md)** — Document collection: scan, classify, upload — local + cloud (Dropbox, Drive, OneDrive)
 - **[references/gst-vat-filing.md](./references/gst-vat-filing.md)** — GST/VAT filing preparation
 - **[references/payment-run.md](./references/payment-run.md)** — Payment run (bulk bill payments)
 - **[references/credit-control.md](./references/credit-control.md)** — Credit control / AR chase

package/assets/skills/jobs/references/bank-recon.md

@@ -79,7 +79,7 @@ Work through each unreconciled item. There are four resolution paths.
 
 The bank record matches an invoice payment, bill payment, or journal already in the books. This is the ideal case — the transaction exists, it just hasn't been linked to the bank record.
 
-**For large volumes:** Use `clio jobs bank-recon match --input data.json --json` to auto-match bank records to transactions before manual review. The calculator finds 1:1, N:1, 1:N, and N:M matches with confidence scores. See the [bank-match reference](../../transaction-recipes/references/bank-match.md) for input format and algorithm details.
+**For large volumes:** Use `clio jobs bank-recon match --input data.json --json` to auto-match bank records to transactions before manual review. The calculator finds 1:1, N:1, 1:N, and N:M matches with confidence scores. See the [bank-match reference](./bank-match.md) for input format and algorithm details.
 
 **How to find the match manually:** Search cashflow transactions for the same amount and approximate date:
 

package/assets/skills/jobs/references/document-collection.md

@@ -1,42 +1,45 @@
 # Document Collection
 
-Scan, classify, and upload client documents (invoices, bills, bank statements) to Jaz via the Magic API endpoints.
+Scan and classify client documents (invoices, bills, bank statements) from local directories or cloud share links (Dropbox, Google Drive, OneDrive). Outputs classified file paths with metadata — the AI agent handles uploads via the api skill.
 
 ## When to Use
 
-- Client sends a folder of PDFs (invoices, bills, receipts) for bulk upload
+- Client sends a folder of PDFs (invoices, bills, receipts) for bulk processing
 - Processing bank statement CSVs/OFX files for import
 - Migrating documents from file dumps (Dropbox, shared folders, email attachments)
-- Batch-uploading scanned documents during onboarding
+- Processing documents from a shared Dropbox, Google Drive, or OneDrive link
+- Batch-processing scanned documents during onboarding
 
 ## How It Works
 
 ```
-Local folder                    Jaz Magic API
-┌───────────────┐               ┌──────────────────────────────────────────┐
-│ invoices/     │──── PDF/JPG ──► POST /magic/createBusinessTransaction    │
-│   inv-001.pdf │               │   FromAttachment                        │
-│   inv-002.jpg │               │   → OCR + extraction + contact match    │
-│               │               │   → Draft invoice created               │
-│ bills/        │──── PDF/JPG ──► POST /magic/createBusinessTransaction    │
-│   acme-jan.pdf│               │   FromAttachment                        │
-│               │               │   → Draft bill created                  │
-│ bank/         │──── CSV/OFX ──► POST /magic/importBankStatement         │
-│   dbs-jan.csv │               │   FromAttachment                        │
-│               │               │   → Bank records imported               │
-└───────────────┘               └──────────────────────────────────────────┘
+Source (local or cloud)              CLI Output (IngestPlan)
+┌───────────────┐                    ┌──────────────────────────────────────────┐
+│ invoices/     │── scan + classify ─► absolutePath, documentType: INVOICE      │
+│   inv-001.pdf │                    │ sizeBytes: 45230                         │
+│   inv-002.jpg │                    │                                          │
+│ bills/        │── scan + classify ─► absolutePath, documentType: BILL         │
+│   acme-jan.pdf│                    │                                          │
+│ bank/         │── scan + classify ─► absolutePath, documentType: BANK_STATEMENT│
+│   dbs-jan.csv │                    │                                          │
+└───────────────┘                    └──────────────────────────────────────────┘
+                                                    │
+                                            AI Agent reads plan,
+                                        uploads via api skill (curl)
 ```
 
+Cloud links are downloaded to a temp directory first, then scanned through the same pipeline.
+
 ## Folder Classification
 
 The tool auto-classifies documents by **folder name** (case-insensitive prefix match):
 
-| Folder name pattern | Classification | API Endpoint |
-|---|---|---|
-| `invoice*`, `sales*`, `ar*`, `receivable*`, `revenue*` | INVOICE | `createBusinessTransactionFromAttachment` |
-| `bill*`, `purchase*`, `expense*`, `ap*`, `payable*`, `supplier*`, `vendor*`, `cost*` | BILL | `createBusinessTransactionFromAttachment` |
-| `bank*`, `statement*`, `recon*` | BANK_STATEMENT | `importBankStatementFromAttachment` |
-| (unknown) | UNKNOWN — skipped unless `--type` forced | — |
+| Folder name pattern | Classification |
+|---|---|
+| `invoice*`, `sales*`, `ar*`, `receivable*`, `revenue*` | INVOICE |
+| `bill*`, `purchase*`, `expense*`, `ap*`, `payable*`, `supplier*`, `vendor*`, `cost*` | BILL |
+| `bank*`, `statement*`, `recon*` | BANK_STATEMENT |
+| (unknown) | UNKNOWN — skipped unless `--type` forced |
 
 ### File Extension Filters
 
@@ -51,87 +54,101 @@ The tool auto-classifies documents by **folder name** (case-insensitive prefix m
 3. **Max depth** — 10 levels (prevents runaway recursion)
 4. **Hidden files/dirs** — skipped (anything starting with `.`)
 
+## Cloud Provider Support
+
+The `--source` flag accepts public share links from Dropbox, Google Drive, and OneDrive. Files are downloaded to a temp directory, then processed through the same scan/classify pipeline as local directories.
+
+| Provider | File Links | Folder Links | Auth Required |
+|----------|-----------|--------------|---------------|
+| **Dropbox** | Direct download (dl=1 trick) | ZIP download + extract | No |
+| **Google Drive** | Direct download (large file confirmation) | Not supported (requires API key) | No |
+| **OneDrive/SharePoint** | MS Graph sharing API | MS Graph sharing API (first page only) | No (best-effort) |
+
+### Cloud Limitations
+
+- **Google Drive folders** require authentication — download manually and use a local path
+- **OneDrive** is best-effort: Microsoft has restricted public link access since Feb 2025
+- **Dropbox folders** download as ZIP — extracted automatically, macOS metadata stripped
+- **Max file size**: 100MB per file, 500MB total for folder downloads
+- **Timeout**: Default 30s (files) / 120s (folders). Override with `--timeout <ms>`
+
 ## CLI Usage
 
 ```bash
-# Dry-run (default) — scan + classify, no uploads
+# Scan + classify local directory
 clio jobs document-collection ingest --source ./client-docs/ [--json]
 
-# Execute — scan + classify + upload to Jaz
-clio jobs document-collection ingest --source ./client-docs/ --execute \
-  --api-key <key> --api-url https://api.jaz.ai [--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]
 
-# Force classification (skip auto-detect)
-clio jobs document-collection ingest --source ./scans/ --type invoice --execute \
-  --api-key <key> --api-url https://api.jaz.ai
+# With timeout for large cloud downloads
+clio jobs document-collection ingest --source "https://www.dropbox.com/..." --timeout 120000 [--json]
 
-# Bank statements need --bank-account (CoA resourceId)
-clio jobs document-collection ingest --source ./bank-csvs/ --execute \
-  --bank-account <resourceId> --api-key <key> --api-url https://api.jaz.ai
+# Force classification (skip auto-detect)
+clio jobs document-collection ingest --source ./scans/ --type invoice [--json]
 ```
 
 ### Options
 
 | Flag | Description |
 |------|-------------|
-| `--source <path>` | Local directory path (required) |
+| `--source <path\|url>` | Local directory path or public cloud share link — Dropbox, Google Drive, OneDrive (required) |
 | `--type <type>` | Force all files to: `invoice`, `bill`, or `bank-statement` |
-| `--execute` | Upload to Jaz API (without this flag, only scans/classifies) |
-| `--api-key <key>` | Jaz Magic API key (required for `--execute`) |
-| `--api-url <url>` | Jaz API base URL (required for `--execute`) |
-| `--bank-account <id>` | Bank account CoA resourceId (required for bank statement uploads) |
-| `--json` | Structured JSON output |
-
-## Magic API Details
-
-### Invoices & Bills
-
-```
-POST /api/v1/magic/createBusinessTransactionFromAttachment
-Content-Type: multipart/form-data
-Header: x-magic-api-key: <key>
-
-Fields:
-  - sourceFile: PDF/JPG file blob (NOT "file")
-  - businessTransactionType: "INVOICE" or "BILL"
-  - sourceType: "FILE"
+| `--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 |
+
+### 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.
+
+```json
+{
+  "source": "./client-docs/",
+  "sourceType": "local",
+  "localPath": "/tmp/client-docs",
+  "folders": [{
+    "folder": "invoices",
+    "documentType": "INVOICE",
+    "files": [{
+      "path": "invoices/inv-001.pdf",
+      "filename": "inv-001.pdf",
+      "extension": ".pdf",
+      "documentType": "INVOICE",
+      "absolutePath": "/tmp/client-docs/invoices/inv-001.pdf",
+      "sizeBytes": 45230,
+      "confidence": "auto",
+      "reason": "Folder \"invoices\" → INVOICE"
+    }],
+    "count": 1
+  }],
+  "summary": {
+    "total": 1,
+    "uploadable": 1,
+    "needClassification": 0,
+    "skipped": 0,
+    "byType": { "INVOICE": 1 }
+  }
+}
 ```
 
-**Key points:**
-- Extraction is **asynchronous** — response confirms upload, extraction runs server-side
-- `subscriptionFBPath` in response tracks extraction progress via Firebase
-- Response maps: `INVOICE` → `SALE`, `BILL` → `PURCHASE`
-- Jaz Magic extracts: line items, contact, CoA mapping, tax, dates, currency
-
-### Bank Statements
-
-```
-POST /api/v1/magic/importBankStatementFromAttachment
-Content-Type: multipart/form-data
-Header: x-magic-api-key: <key>
-
-Fields:
-  - sourceFile: CSV/OFX file (NOT "file")
-  - accountResourceId: bank account CoA resourceId
-  - businessTransactionType: "BANK_STATEMENT"
-  - sourceType: "FILE"
-```
-
-**CSV format:** `Date,Description,Debit,Credit`
+For cloud sources, `localPath` points to the temp directory where files were downloaded.
 
 ## Phases (Blueprint)
 
-When run without `ingest` subcommand, produces a 6-phase blueprint:
+When run without `ingest` subcommand, produces a 4-phase blueprint:
 
 1. **Intake** — Identify source, validate access
 2. **Scan** — Traverse directory tree, list all files
 3. **Classify** — Auto-classify by folder name
-4. **Review** — Present plan for user approval (dry-run)
-5. **Upload** — Upload each file to correct Magic API endpoint
-6. **Verify** — Check extraction results, flag failures
+4. **Review** — Present plan for user/agent action
+
+The AI agent then uses the classified file paths to upload via the Jaz Magic API (see api skill for endpoint details).
 
 ## Relationship to Other Skills
 
-- **api skill** — Field names, auth headers, error codes for Magic endpoints
+- **api skill** — Field names, auth headers, error codes for Magic endpoints. Agent uses this to upload classified files.
 - **bank-recon job** — After bank statement import, use bank-recon to match and reconcile
 - **transaction-recipes** — After Magic creates draft transactions, use recipes for complex accounting patterns

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

@@ -1,6 +1,6 @@
 ---
 name: transaction-recipes
-version: 3.3.0
+version: 3.4.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.
@@ -117,10 +117,6 @@ Each recipe includes: scenario description, accounts involved, journal entries,
 
 16. **[Capital WIP to Fixed Asset](references/capital-wip.md)** — Cost accumulation in CIP account during construction/development, transfer to FA on completion, auto-depreciation via Jaz FA module.
 
-### Utility — Reconciliation
-
-17. **[Bank Reconciliation Matcher](references/bank-match.md)** — 5-phase cascade algorithm matching bank records to cashflow transactions. Finds 1:1, N:1, 1:N, and N:M matches with confidence scores. *Paired job tool: `clio jobs bank-recon match`*
-
 ## How to Use These Recipes
 
 1. **Read the recipe** for your scenario — understand the accounts, journal entries, and capsule structure.

package/dist/commands/jobs.js

@@ -12,8 +12,8 @@ import { generateAuditPrepBlueprint } from '../jobs/audit-prep/blueprint.js';
 import { generateFaReviewBlueprint } from '../jobs/fa-review/blueprint.js';
 import { generateDocumentCollectionBlueprint } from '../jobs/document-collection/blueprint.js';
 import { generateStatutoryFilingBlueprint } from '../jobs/statutory-filing/blueprint.js';
-import { ingestDryRun, ingestExecute, validateExecuteOptions } from '../jobs/document-collection/tools/ingest/ingest.js';
-import { printIngestPlan, printIngestPlanJson, printIngestResult, printIngestResultJson } from '../jobs/document-collection/tools/ingest/format.js';
+import { ingest } from '../jobs/document-collection/tools/ingest/ingest.js';
+import { printIngestPlan, printIngestPlanJson } from '../jobs/document-collection/tools/ingest/format.js';
 import { matchBankRecords } from '../jobs/bank-recon/tools/match/match.js';
 import { computeFormCs } from '../jobs/statutory-filing/tools/sg-tax/form-cs.js';
 import { computeCapitalAllowances } from '../jobs/statutory-filing/tools/sg-tax/capital-allowances.js';
@@ -41,6 +41,7 @@ function jobAction(fn) {
 export function registerJobsCommand(program) {
     const jobs = program
         .command('jobs')
+        .enablePositionalOptions()
         .description('Accounting job blueprints — month-end, quarter-end, year-end, bank-recon, gst-vat, payment-run, credit-control, supplier-recon, audit-prep, fa-review, document-collection, statutory-filing');
     // ── clio jobs month-end ──────────────────────────────────────────
     jobs
@@ -92,6 +93,8 @@ export function registerJobsCommand(program) {
     const bankRecon = jobs
         .command('bank-recon')
         .description('Bank reconciliation — blueprint + match tool')
+        .enablePositionalOptions()
+        .passThroughOptions()
         .option('--account <name>', 'Specific bank account name')
         .option('--period <YYYY-MM>', 'Month period to reconcile')
         .option('--currency <code>', 'Currency code (e.g. SGD, USD)')
@@ -249,12 +252,12 @@ export function registerJobsCommand(program) {
     const docCollection = jobs
         .command('document-collection')
         .description('Document collection — scan, classify, and upload client documents')
-        .option('--source <path>', 'Source path or URL hint for blueprint')
+        .enablePositionalOptions()
+        .passThroughOptions()
         .option('--currency <code>', 'Currency code (e.g. SGD, USD)')
         .option('--json', 'Output as JSON')
         .action(jobAction((opts) => {
         const bp = generateDocumentCollectionBlueprint({
-            source: opts.source,
             currency: opts.currency,
         });
         opts.json ? printBlueprintJson(bp) : printBlueprint(bp);
@@ -262,13 +265,9 @@ export function registerJobsCommand(program) {
     // ── clio jobs document-collection ingest ────────────────────────
     docCollection
         .command('ingest')
-        .description('Scan, classify, and upload client documents to Jaz')
+        .description('Scan and classify client documents — outputs file paths for agent upload')
         .requiredOption('--source <path>', 'Local directory path or public share URL (Dropbox, Google Drive, OneDrive)')
         .option('--type <type>', 'Force document type: invoice, bill, or bank-statement')
-        .option('--execute', 'Upload files to Jaz (without this flag, shows a preview)')
-        .option('--api-key <key>', 'Jaz Magic API key (required for --execute)')
-        .option('--api-url <url>', 'Jaz API base URL (required for --execute)')
-        .option('--bank-account <id>', 'Bank account CoA resourceId (required for bank statement uploads)')
         .option('--timeout <ms>', 'Download timeout in milliseconds for cloud sources (default: 30000)', parseInt)
         .option('--currency <code>', 'Functional/reporting currency (e.g. SGD)')
         .option('--json', 'Output as JSON')
@@ -284,31 +283,12 @@ export function registerJobsCommand(program) {
         if (opts.type && !forceType) {
             throw new JobValidationError(`Invalid --type "${opts.type}". Use: invoice, bill, or bank-statement`);
         }
-        const ingestOpts = {
+        ingest({
             source: opts.source,
             type: forceType,
-            execute: opts.execute,
-            apiKey: opts.apiKey,
-            apiUrl: opts.apiUrl,
-            bankAccount: opts.bankAccount,
             currency: opts.currency,
             timeout: opts.timeout,
-        };
-        if (ingestOpts.execute) {
-            validateExecuteOptions(ingestOpts);
-            // Execute mode — scan + classify + upload to Jaz Magic API
-            ingestExecute(ingestOpts).then((result) => {
-                opts.json ? printIngestResultJson(result) : printIngestResult(result);
-                if (result.summary.failed > 0)
-                    process.exit(1);
-            }).catch((err) => {
-                console.error(chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}`));
-                process.exit(1);
-            });
-            return;
-        }
-        // Dry-run mode — scan + classify (async for cloud sources)
-        ingestDryRun(ingestOpts).then((plan) => {
+        }).then((plan) => {
             opts.json ? printIngestPlanJson(plan) : printIngestPlan(plan);
         }).catch((err) => {
             console.error(chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}`));
@@ -319,6 +299,8 @@ export function registerJobsCommand(program) {
     const statFiling = jobs
         .command('statutory-filing')
         .description('Statutory filing — corporate income tax computation and filing')
+        .enablePositionalOptions()
+        .passThroughOptions()
         .option('--ya <year>', 'Year of Assessment', parseInt)
         .option('--jurisdiction <code>', 'Jurisdiction: sg (default)', 'sg')
         .option('--currency <code>', 'Currency code (e.g. SGD)')

package/dist/index.js

@@ -16,7 +16,8 @@ const program = new Command();
 program
     .name('clio')
     .description('Clio — Command Line Interface Orchestrator for Jaz AI')
-    .version(pkg.version);
+    .version(pkg.version)
+    .enablePositionalOptions();
 program
     .command('init')
     .description('Install Jaz AI skills into the current project')

package/dist/jobs/document-collection/blueprint.js

@@ -6,7 +6,6 @@
 import { buildSummary } from '../types.js';
 export function generateDocumentCollectionBlueprint(opts = {}) {
     const currency = opts.currency ?? 'SGD';
-    const source = opts.source ?? '(local folder or shared link)';
     // Phase 1: Intake
     const intake = {
         name: 'Intake',
@@ -16,7 +15,7 @@ export function generateDocumentCollectionBlueprint(opts = {}) {
                 order: 1,
                 description: 'Identify document source',
                 category: 'verify',
-                notes: `Source: ${source}. Supported: local folders, Dropbox/GDrive/OneDrive shared links.`,
+                notes: 'Supported sources: local folders, Dropbox/GDrive/OneDrive shared links.',
             },
             {
                 order: 2,
@@ -81,14 +80,14 @@ export function generateDocumentCollectionBlueprint(opts = {}) {
                 order: 8,
                 description: 'Confirm plan with user',
                 category: 'review',
-                notes: 'User reviews classification, approves or adjusts. Run with --execute to proceed.',
+                notes: 'User reviews classification, approves or adjusts. Agent then uploads each file using the api skill.',
             },
         ],
     };
-    // Phase 5: Upload
+    // Phase 5: Upload (agent-executed — uses file paths from ingest plan)
     const upload = {
         name: 'Upload',
-        description: 'Upload each classified file to the appropriate Jaz Magic API endpoint.',
+        description: 'Agent uploads each classified file to the appropriate Jaz Magic API endpoint using absolute paths from the ingest plan.',
         steps: [
             {
                 order: 9,
@@ -99,7 +98,7 @@ export function generateDocumentCollectionBlueprint(opts = {}) {
                     sourceType: 'FILE',
                     businessTransactionType: '(INVOICE or BILL per classification)',
                 },
-                notes: 'Multipart upload with sourceFile field. Extraction is async — returns subscriptionFBPath for tracking.',
+                notes: 'Agent uses curl -F "sourceFile=@<absolutePath>" for each file. Extraction is async — returns subscriptionFBPath for tracking.',
             },
             {
                 order: 10,
@@ -110,14 +109,14 @@ export function generateDocumentCollectionBlueprint(opts = {}) {
                     sourceType: 'FILE',
                     businessTransactionType: 'BANK_STATEMENT',
                 },
-                notes: 'Requires accountResourceId for the target bank account. Supports CSV and OFX.',
+                notes: 'Agent uses curl -F "sourceFile=@<absolutePath>". Requires accountResourceId for the target bank account. Supports CSV and OFX.',
             },
         ],
     };
-    // Phase 6: Verify
+    // Phase 6: Verify (agent-executed)
     const verify = {
         name: 'Verify',
-        description: 'Check extraction results and flag failures.',
+        description: 'Agent checks extraction results and flags failures.',
         steps: [
             {
                 order: 11,

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

@@ -2,7 +2,7 @@
  * Pretty-print and JSON formatters for document-collection ingest output.
  */
 import chalk from 'chalk';
-/** Print a dry-run ingestion plan in human-readable format. */
+/** Print an ingestion plan in human-readable format. */
 export function printIngestPlan(plan) {
     console.log();
     console.log(chalk.bold('Document Collection — Ingestion Plan'));
@@ -10,6 +10,7 @@ export function printIngestPlan(plan) {
     if (plan.sourceType === 'url' && plan.cloudProvider) {
         const providerName = { dropbox: 'Dropbox', gdrive: 'Google Drive', onedrive: 'OneDrive' };
         console.log(chalk.gray(`Provider: ${providerName[plan.cloudProvider] ?? plan.cloudProvider}`));
+        console.log(chalk.gray(`Local path: ${plan.localPath}`));
     }
     console.log();
     for (const folder of plan.folders) {
@@ -42,45 +43,8 @@ export function printIngestPlan(plan) {
         }
     }
     console.log();
-    console.log(chalk.gray('Add --execute --api-key <key> --api-url <url> to upload.'));
-    console.log();
 }
 /** Print ingestion plan as JSON. */
 export function printIngestPlanJson(plan) {
     console.log(JSON.stringify(plan, null, 2));
 }
-/** Print an execution result in human-readable format. */
-export function printIngestResult(result) {
-    console.log();
-    console.log(chalk.bold('Document Collection — Ingestion Result'));
-    console.log(chalk.gray(`Source: ${result.source}`));
-    console.log();
-    for (const r of result.results) {
-        const status = r.status === 'success'
-            ? chalk.green('✓')
-            : r.status === 'skipped'
-                ? chalk.gray('–')
-                : chalk.red('✗');
-        const extra = r.recordsCreated ? ` (${r.recordsCreated} records)` : '';
-        const errMsg = r.error ? chalk.red(` — ${r.error}`) : '';
-        console.log(`  ${status} ${r.file} [${r.classification}]${extra}${errMsg}`);
-    }
-    console.log();
-    console.log(chalk.bold('Summary'));
-    console.log(`  Total:    ${result.summary.total}`);
-    console.log(`  Uploaded: ${chalk.green(String(result.summary.uploaded))}`);
-    if (result.summary.skipped > 0) {
-        console.log(`  Skipped:  ${chalk.gray(String(result.summary.skipped))}`);
-    }
-    if (result.summary.failed > 0) {
-        console.log(`  Failed:   ${chalk.red(String(result.summary.failed))}`);
-        for (const err of result.summary.errors) {
-            console.log(chalk.red(`    ${err.file}: ${err.error}`));
-        }
-    }
-    console.log();
-}
-/** Print execution result as JSON. */
-export function printIngestResultJson(result) {
-    console.log(JSON.stringify(result, null, 2));
-}

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

@@ -1,17 +1,15 @@
 /**
  * Document Collection ingest tool.
  *
- * Two modes:
- * 1. Dry-run (default): Scan + classify → IngestPlan
- * 2. Execute (--execute): Scan + classify + upload to Jaz Magic API → IngestResult
+ * Scans a local directory or cloud share link, classifies documents by folder name,
+ * and produces an IngestPlan with absolute file paths for the AI agent to upload.
  *
- * Supports local directories and public share links (Dropbox, Google Drive, OneDrive).
+ * The CLI does NOT make API calls — the agent uses the api skill for that.
  */
 import { existsSync, statSync } from 'node:fs';
-import { resolve, join } from 'node:path';
+import { resolve } from 'node:path';
 import { JobValidationError } from '../../../validate.js';
 import { scanLocalDirectory } from './scanner.js';
-import { uploadFile } from './magic-upload.js';
 import { downloadCloudSource } from './cloud/index.js';
 /**
  * Detect if a source string is a URL (public share link) or local path.
@@ -40,7 +38,8 @@ function validateLocalSource(source) {
 }
 /**
  * Resolve a source (local path or URL) to a local directory path.
- * For URLs, downloads to a temp dir. Returns the path and optional cleanup.
+ * For URLs, downloads to a temp dir. The temp dir is NOT cleaned up —
+ * the agent needs the files to upload via the API.
  */
 async function resolveSource(opts) {
     if (isUrl(opts.source)) {
@@ -52,118 +51,20 @@ async function resolveSource(opts) {
     return { localPath: validateLocalSource(opts.source), originalSource: opts.source, cloud: null };
 }
 /**
- * Run the ingest tool in dry-run mode.
- * Returns an IngestPlan showing what would be uploaded.
- */
-export async function ingestDryRun(opts) {
-    const { localPath, originalSource, cloud } = await resolveSource(opts);
-    try {
-        const plan = scanLocalDirectory(localPath, { forceType: opts.type });
-        // Override source display for URL sources
-        if (cloud) {
-            plan.source = originalSource;
-            plan.sourceType = 'url';
-            plan.cloudProvider = cloud.provider;
-        }
-        return plan;
-    }
-    finally {
-        cloud?.cleanup();
-    }
-}
-/**
- * Run the ingest tool in execute mode.
- * Scans, classifies, then uploads each file to the Jaz Magic API.
+ * Scan, classify, and return an IngestPlan with absolute file paths.
+ *
+ * For cloud sources, files are downloaded to a temp directory first.
+ * The temp dir is preserved so the agent can use the file paths for uploads.
  */
-export async function ingestExecute(opts) {
+export async function ingest(opts) {
     const { localPath, originalSource, cloud } = await resolveSource(opts);
-    try {
-        const plan = scanLocalDirectory(localPath, { forceType: opts.type });
-        const results = [];
-        let uploaded = 0;
-        let skipped = 0;
-        let failed = 0;
-        const errors = [];
-        // Flatten all files from all folders
-        const allFiles = plan.folders.flatMap(f => f.files);
-        for (const file of allFiles) {
-            // Skip UNKNOWN and SKIPPED files
-            if (file.documentType === 'UNKNOWN' || file.documentType === 'SKIPPED') {
-                skipped++;
-                results.push({
-                    file: file.path,
-                    classification: 'SKIPPED',
-                    status: 'skipped',
-                    reason: file.reason,
-                });
-                continue;
-            }
-            const absolutePath = join(localPath, file.path);
-            const result = await uploadFile({
-                filePath: absolutePath,
-                relativePath: file.path,
-                documentType: file.documentType,
-                apiKey: opts.apiKey,
-                apiUrl: opts.apiUrl,
-                bankAccountId: opts.bankAccount,
-            });
-            results.push(result);
-            if (result.status === 'success') {
-                uploaded++;
-            }
-            else {
-                failed++;
-                if (result.error) {
-                    errors.push({ file: result.file, error: result.error });
-                }
-            }
-        }
-        return {
-            type: 'document-collection-ingest',
-            source: originalSource,
-            results,
-            summary: {
-                total: allFiles.length,
-                uploaded,
-                skipped,
-                failed,
-                errors,
-            },
-        };
-    }
-    finally {
-        cloud?.cleanup();
-    }
-}
-/** Allowed API hosts for execute mode. */
-const ALLOWED_API_HOSTS = new Set(['api.jaz.ai', 'api.juan.ac', 'staging-api.jaz.ai', 'localhost']);
-/**
- * Validate options for execute mode.
- * Throws JobValidationError if required options are missing or unsafe.
- */
-export function validateExecuteOptions(opts) {
-    if (!opts.apiKey) {
-        throw new JobValidationError('--api-key is required for --execute mode');
-    }
-    if (!opts.apiUrl) {
-        throw new JobValidationError('--api-url is required for --execute mode');
-    }
-    // Validate URL to prevent credential exfiltration (SSRF)
-    let parsed;
-    try {
-        parsed = new URL(opts.apiUrl);
-    }
-    catch {
-        throw new JobValidationError('--api-url must be a valid URL');
-    }
-    if (parsed.protocol !== 'https:' && parsed.hostname !== 'localhost') {
-        throw new JobValidationError('--api-url must use HTTPS');
-    }
-    if (parsed.username || parsed.password) {
-        throw new JobValidationError('--api-url must not contain credentials');
-    }
-    if (!ALLOWED_API_HOSTS.has(parsed.hostname)) {
-        throw new JobValidationError(`--api-url host "${parsed.hostname}" is not allowed. ` +
-            `Allowed: ${[...ALLOWED_API_HOSTS].join(', ')}`);
-    }
+    const plan = scanLocalDirectory(localPath, { forceType: opts.type });
+    // Override source display and localPath for URL sources
+    if (cloud) {
+        plan.source = originalSource;
+        plan.sourceType = 'url';
+        plan.cloudProvider = cloud.provider;
+        plan.localPath = localPath;
+    }
+    return plan;
 }

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

@@ -5,7 +5,7 @@
  * and produces an IngestPlan (dry-run output).
  */
 import { readdirSync, statSync } from 'node:fs';
-import { join, basename, extname, relative } from 'node:path';
+import { join, basename, extname, relative, resolve } from 'node:path';
 import { classifyFolder, checkExtension } from './classify.js';
 /** Max recursion depth to prevent runaway traversal. */
 const MAX_DEPTH = 10;
@@ -19,9 +19,10 @@ const MAX_DEPTH = 10;
  * 4. Nested subfolders (depth > 1) inherit from nearest classified ancestor.
  */
 export function scanLocalDirectory(sourcePath, opts = {}) {
+    const base = resolve(sourcePath);
     const maxDepth = opts.maxDepth ?? MAX_DEPTH;
     const files = [];
-    scanDir(sourcePath, sourcePath, null, opts.forceType ?? null, 0, maxDepth, files);
+    scanDir(base, base, null, opts.forceType ?? null, 0, maxDepth, files);
     // Group files by folder
     const folderMap = new Map();
     for (const f of files) {
@@ -75,8 +76,9 @@ export function scanLocalDirectory(sourcePath, opts = {}) {
         }
     }
     return {
-        source: sourcePath,
+        source: base,
         sourceType: 'local',
+        localPath: base,
         folders,
         summary: { total, uploadable, needClassification, skipped, byType },
     };
@@ -151,6 +153,8 @@ function scanDir(rootPath, dirPath, inheritedType, forceType, depth, maxDepth, o
                 folder: relDir,
                 confidence,
                 reason,
+                absolutePath: fullPath,
+                sizeBytes: stat.size,
             });
         }
     }

package/package.json

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

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

@@ -1,142 +0,0 @@
-/**
- * Jaz Magic API upload logic for document collection ingest.
- *
- * Two endpoints:
- * 1. POST /magic/createBusinessTransactionFromAttachment — invoices + bills (PDF/JPG/PNG)
- * 2. POST /magic/importBankStatementFromAttachment — bank statements (CSV/OFX)
- *
- * Both use multipart/form-data with `sourceFile` field (NOT "file").
- * Magic endpoints use `x-magic-api-key` header (NOT `x-jk-api-key`).
- * Extraction is asynchronous — response confirms upload, not extraction.
- */
-import { readFileSync } from 'node:fs';
-import { basename } from 'node:path';
-/**
- * Upload a single file to the appropriate Jaz Magic API endpoint.
- *
- * Returns an IngestFileResult (never throws — errors are captured in the result).
- */
-export async function uploadFile(opts) {
-    const { filePath, relativePath, documentType, apiKey, apiUrl, bankAccountId } = opts;
-    try {
-        const fileBuffer = readFileSync(filePath);
-        const fileName = basename(filePath);
-        const blob = new Blob([fileBuffer]);
-        if (documentType === 'BANK_STATEMENT') {
-            return await uploadBankStatement(blob, fileName, relativePath, apiKey, apiUrl, bankAccountId);
-        }
-        else {
-            const txType = documentType === 'INVOICE' ? 'INVOICE' : 'BILL';
-            return await uploadTransaction(blob, fileName, relativePath, txType, apiKey, apiUrl);
-        }
-    }
-    catch (err) {
-        return {
-            file: relativePath,
-            classification: documentType,
-            status: 'failed',
-            error: err instanceof Error ? err.message : String(err),
-        };
-    }
-}
-/**
- * Upload invoice/bill via POST /magic/createBusinessTransactionFromAttachment.
- */
-async function uploadTransaction(blob, fileName, relativePath, txType, apiKey, apiUrl) {
-    const formData = new FormData();
-    formData.append('sourceFile', blob, fileName);
-    formData.append('businessTransactionType', txType);
-    formData.append('sourceType', 'FILE');
-    const url = `${apiUrl.replace(/\/+$/, '')}/api/v1/magic/createBusinessTransactionFromAttachment`;
-    const response = await fetch(url, {
-        method: 'POST',
-        headers: { 'x-magic-api-key': apiKey },
-        body: formData,
-    });
-    if (!response.ok) {
-        const errorBody = await safeReadBody(response);
-        return {
-            file: relativePath,
-            classification: txType === 'INVOICE' ? 'INVOICE' : 'BILL',
-            status: 'failed',
-            error: `${response.status}: ${errorBody}`,
-        };
-    }
-    const json = (await response.json());
-    const valid = json.data?.validFiles?.[0];
-    const invalid = json.data?.invalidFiles?.[0];
-    if (invalid) {
-        return {
-            file: relativePath,
-            classification: txType === 'INVOICE' ? 'INVOICE' : 'BILL',
-            status: 'failed',
-            error: `${invalid.errorCode}: ${invalid.errorMessage}`,
-        };
-    }
-    return {
-        file: relativePath,
-        classification: txType === 'INVOICE' ? 'INVOICE' : 'BILL',
-        status: 'success',
-        subscriptionFBPath: valid?.subscriptionFBPath,
-        fileId: valid?.fileDetails?.fileId,
-    };
-}
-/**
- * Upload bank statement via POST /magic/importBankStatementFromAttachment.
- */
-async function uploadBankStatement(blob, fileName, relativePath, apiKey, apiUrl, bankAccountId) {
-    if (!bankAccountId) {
-        return {
-            file: relativePath,
-            classification: 'BANK_STATEMENT',
-            status: 'failed',
-            error: 'Missing --bank-account (accountResourceId required for bank statement uploads)',
-        };
-    }
-    const formData = new FormData();
-    formData.append('sourceFile', blob, fileName);
-    formData.append('accountResourceId', bankAccountId);
-    formData.append('businessTransactionType', 'BANK_STATEMENT');
-    formData.append('sourceType', 'FILE');
-    const url = `${apiUrl.replace(/\/+$/, '')}/api/v1/magic/importBankStatementFromAttachment`;
-    const response = await fetch(url, {
-        method: 'POST',
-        headers: { 'x-magic-api-key': apiKey },
-        body: formData,
-    });
-    if (!response.ok) {
-        const errorBody = await safeReadBody(response);
-        return {
-            file: relativePath,
-            classification: 'BANK_STATEMENT',
-            status: 'failed',
-            error: `${response.status}: ${errorBody}`,
-        };
-    }
-    // Bank statement response shape varies — extract record count if available
-    const json = (await response.json());
-    const data = json.data;
-    return {
-        file: relativePath,
-        classification: 'BANK_STATEMENT',
-        status: 'success',
-        recordsCreated: typeof data?.recordsCreated === 'number' ? data.recordsCreated : undefined,
-    };
-}
-/** Safely read response body as text, truncated to 200 chars. */
-async function safeReadBody(response) {
-    try {
-        const text = await response.text();
-        // Try to extract message from JSON error body
-        try {
-            const parsed = JSON.parse(text);
-            return parsed.message ?? parsed.error ?? text.slice(0, 200);
-        }
-        catch {
-            return text.slice(0, 200);
-        }
-    }
-    catch {
-        return response.statusText;
-    }
-}