jaz-clio 4.2.1 → 4.3.0

package/README.md

@@ -12,6 +12,12 @@ CLI for the [Jaz](https://jaz.ai) accounting platform. Create invoices, record b
 
 > Also fully compatible with [Juan Accounting](https://juan.ac).
 
+## Prerequisites
+
+**Node.js 18 or later** is required. If `node --version` works, skip ahead.
+
+Otherwise: download the LTS installer from [nodejs.org](https://nodejs.org). It includes `npm`.
+
 ## Install
 
 ```bash

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 4.2.1
+version: 4.3.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.
@@ -94,7 +94,7 @@ You are working with the **Jaz REST API** — the accounting platform backend. A
 | Trial balance | `startDate`, `endDate` |
 | Balance sheet | `primarySnapshotDate` |
 | P&L | `primarySnapshotDate`, `secondarySnapshotDate` |
-| General ledger | `startDate`, `endDate`, `groupBy: "ACCOUNT"` |
+| General ledger | `startDate`, `endDate`, `groupBy: "ACCOUNT"` (also `TRANSACTION`, `CAPSULE`) |
 | Cashflow | `primaryStartDate`, `primaryEndDate` |
 | Cash balance | `reportDate` |
 | AR/AP report | `endDate` |
@@ -105,7 +105,7 @@ You are working with the **Jaz REST API** — the accounting platform backend. A
 37. **Data exports use simpler field names**: P&L export uses `startDate`/`endDate` (NOT `primarySnapshotDate`). AR/AP export uses `endDate`.
 
 ### Pagination
-38. **All list/search endpoints use `limit`/`offset` pagination** — NOT `page`/`size`. Default limit=100, offset=0. Max limit=1000, max offset=65536. `page`/`size` params are silently ignored. Response shape: `{ totalPages, totalElements, data: [...] }`.
+38. **All list/search endpoints use `limit`/`offset` pagination** — NOT `page`/`size`. Default limit=100, offset=0. Max limit=1000, max offset=65536. `page`/`size` params are silently ignored. Response shape: `{ totalPages, totalElements, truncated, data: [...] }`. When `truncated: true`, a `_meta: { fetchedRows, maxRows }` field explains why (offset cap or `--max-rows` soft cap — default 10,000). Use `--max-rows <n>` to override. Always check `truncated` before assuming the full dataset was returned.
 
 ### Other
 39. **Currency rates use `/organization-currencies/:code/rates`** — note the HYPHENATED path (NOT `/organization/currencies`). Enable currencies first via `POST /organization/currencies`, then set rates via `POST /organization-currencies/:code/rates` with body `{ "rate": 0.74, "rateApplicableFrom": "YYYY-MM-DD" }` (see Rule 49 for direction). Cannot set rates for org base currency. Full CRUD: POST (create), GET (list), GET/:id, PUT/:id, DELETE/:id.
@@ -132,11 +132,12 @@ You are working with the **Jaz REST API** — the accounting platform backend. A
 ### Jaz Magic — Extraction & Autofill
 57. **When the user starts from an attachment, always use Jaz Magic** — if the input is a PDF, JPG, or any document image (invoice, bill, receipt), the correct path is `POST /magic/createBusinessTransactionFromAttachment`. Do NOT manually construct a `POST /invoices` or `POST /bills` payload from an attachment — Jaz Magic handles the entire extraction-and-autofill pipeline server-side: OCR, line item detection, contact matching, CoA auto-mapping via ML learning, and draft creation with all fields pre-filled. Only use `POST /invoices` or `POST /bills` when building transactions from structured data (JSON, CSV, database rows) where the fields are already known.
 58. **Two upload modes with different content types** — `sourceType: "FILE"` requires **multipart/form-data** with `sourceFile` blob (JSON body fails with 400 "sourceFile is a required field"). `sourceType: "URL"` accepts **application/json** with `sourceURL` string. The OAS only documents URL mode — FILE mode (the common case) is undocumented.
-59. **Three required fields**: `sourceFile` (multipart blob — NOT `file`), `businessTransactionType` (`"INVOICE"` or `"BILL"` only — `EXPENSE` rejected), `sourceType` (`"FILE"` or `"URL"`). All three are validated server-side. **CRITICAL: multipart form field names are camelCase** — `businessTransactionType`, `sourceType`, `sourceFile`, NOT snake_case. Using `business_transaction_type` returns 422 "businessTransactionType is a required field". The File blob must include a filename and correct MIME type (e.g. `application/pdf`, `image/jpeg`) — bare `application/octet-stream` blobs are rejected with 400 "Invalid file type".
-60. **Response maps transaction types**: Request `BILL` → response `businessTransactionType: "PURCHASE"`. Request `INVOICE` → response `businessTransactionType: "SALE"`. S3 paths follow: `/purchases/` vs `/sales/`.
-61. **Extraction is asynchronous** — the API response is immediate (file upload confirmation only). The actual Magic pipeline — OCR, line item extraction, contact matching, CoA learning, and autofill — runs asynchronously. The `subscriptionFBPath` in the response (e.g., `magic_transactions/{orgId}/purchase/{fileId}`) is a Firebase Realtime Database path for subscribing to extraction status updates.
+59. **Three required fields**: `sourceFile` (multipart blob — NOT `file`), `businessTransactionType` (`"INVOICE"`, `"BILL"`, `"CUSTOMER_CREDIT_NOTE"`, or `"SUPPLIER_CREDIT_NOTE"` — `EXPENSE` rejected), `sourceType` (`"FILE"` or `"URL"`). All three are validated server-side. **CRITICAL: multipart form field names are camelCase** — `businessTransactionType`, `sourceType`, `sourceFile`, NOT snake_case. Using `business_transaction_type` returns 422 "businessTransactionType is a required field". The File blob must include a filename and correct MIME type (e.g. `application/pdf`, `image/jpeg`) — bare `application/octet-stream` blobs are rejected with 400 "Invalid file type".
+60. **Response maps transaction types**: Request `INVOICE` → response `SALE`. Request `BILL` → response `PURCHASE`. Request `CUSTOMER_CREDIT_NOTE` → response `SALE_CREDIT_NOTE`. Request `SUPPLIER_CREDIT_NOTE` → response `PURCHASE_CREDIT_NOTE`. S3 paths follow the response type. The response `validFiles[]` array contains `workflowResourceId` for tracking extraction progress via `POST /magic/workflows/search`.
+61. **Extraction is asynchronous** — the API response is immediate (file upload confirmation only). The actual Magic pipeline — OCR, line item extraction, contact matching, CoA learning, and autofill — runs asynchronously. Use `POST /magic/workflows/search` with `filter.resourceId.eq: "<workflowResourceId>"` to check status (SUBMITTED → PROCESSING → COMPLETED/FAILED). When COMPLETED, `businessTransactionDetails.businessTransactionResourceId` contains the created draft BT ID. The `subscriptionFBPath` in the response is a Firebase Realtime Database path for real-time status updates (alternative to polling).
 62. **Accepts PDF and JPG/JPEG** — both file types confirmed working. Handwritten documents are accepted at upload stage (extraction quality varies). `fileType` in response reflects actual format: `"PDF"`, `"JPEG"`.
 63. **Never use magic-search endpoints** — `GET /invoices/magic-search` and `GET /bills/magic-search` require a separate `x-magic-api-key` (not available to agents). Always use `POST /invoices/search` or `POST /bills/search` with standard `x-jk-api-key` auth instead.
+63b. **Workflow search tracks all magic uploads** — `POST /magic/workflows/search` searches across BT extractions AND bank statement imports. Filter by `resourceId` (eq), `documentType` (SALE, PURCHASE, SALE_CREDIT_NOTE, PURCHASE_CREDIT_NOTE, BANK_STATEMENT), `status` (SUBMITTED, PROCESSING, COMPLETED, FAILED), `fileName` (contains), `fileType`, `createdAt` (date range). Response: paginated `MagicWorkflowItem` with `businessTransactionDetails.businessTransactionResourceId` (the draft BT ID when COMPLETED) or `bankStatementDetails` (for bank imports). Standard search sort: `{ sortBy: ["createdAt"], order: "DESC" }`.
 
 ### Cashflow & Unified Ledger
 64. **No standalone payments list/search** — `GET /payments`, `POST /payments/search`, and `GET /payments` do NOT exist. Per-payment CRUD (`GET/PUT/DELETE /payments/:resourceId`) exists for individual payment records, but to **list or search** payments, use `POST /cashflow-transactions/search` — the unified transaction ledger that spans invoices, bills, credit notes, journals, cash entries, and payments. Filter by `businessTransactionType` (e.g., `SALE`, `PURCHASE`) and `direction` (`PAYIN`, `PAYOUT`). Response dates are epoch milliseconds.
@@ -163,6 +164,60 @@ You are working with the **Jaz REST API** — the accounting platform backend. A
 79. **`capsule-transaction` recipes auto-resolve accounts** — when `--input` is omitted, the CLI searches the org's chart of accounts for each blueprint account name (e.g., "Interest Expense", "Loan Payable"). If all accounts resolve with high confidence, no JSON mapping file is needed. If any fail, the error message shows exactly which accounts could not be found and suggests close matches. `--contact` and `--bank-account` on recipes also accept names.
 80. **Payment/refund account filter is conditional on `--method`** — for BANK_TRANSFER, CASH, and CHEQUE, the `--account` resolver filters to bank/cash accounts only. For other payment methods, all account types are considered.
 
+### Draft Finalization Pipeline (Convert & Next)
+
+The `clio bills draft` subcommand group enables the full "review → fill missing → convert" workflow that mirrors the Jaz UI's "Convert and Next" button. Designed for AI agents processing a queue of draft bills.
+
+#### Commands
+
+| Command | Purpose |
+|---------|---------|
+| `clio bills draft list [--ids <ids>] [--json]` | Queue view: all drafts with per-field validation + attachment count |
+| `clio bills draft finalize <id> [flags] [--json]` | Fill missing fields + convert DRAFT → UNPAID in one PUT |
+| `clio bills draft attachments <id> [--json]` | List attachments with download URLs for agent inspection |
+
+#### Mandatory Fields for Bill Finalization
+
+| Field | JSON Path | CLI Flag | Resolver |
+|-------|-----------|----------|----------|
+| Contact | `contactResourceId` | `--contact <name/UUID>` | Fuzzy resolved |
+| Bill date | `valueDate` | `--date <YYYY-MM-DD>` | Literal |
+| Due date | `dueDate` | `--due <YYYY-MM-DD>` | Literal |
+| Line items | `lineItems` (non-empty) | `--lines <json>` | — |
+| Item name | `lineItems[i].name` | via `--lines` | — |
+| Item price | `lineItems[i].unitPrice` | via `--lines` | — |
+| Item account | `lineItems[i].accountResourceId` | `--account <name/UUID>` (bulk) | Fuzzy resolved |
+
+Optional: `--ref`, `--notes`, `--tag`, `--tax-profile <name/UUID>` (bulk, fuzzy resolved), `--tax`, `--tax-inclusive`, `--dry-run`, `--input <file>`.
+
+#### Agent Workflow Pattern
+
+```
+Step 1:  clio bills draft list --json
+         → Batch queue: every DRAFT with per-field validation + attachment count
+
+Step 2:  For each draft where ready = false:
+         a) Read validation.missingFields from Step 1 output
+         b) Optional: clio bills draft attachments <id> --json
+            → Download fileUrl, read PDF/image, extract or verify values
+         c) Resolve values (ask user, or infer from attachment + context)
+         d) clio bills draft finalize <id> --contact "Acme" --date 2025-01-15 ... --json
+            → Updates + converts to UNPAID in one PUT (Rule 67: bills/invoices → UNPAID, journals → APPROVED)
+
+Step 3:  For each draft where ready = true:
+         clio bills draft finalize <id> --json
+         → Converts directly (all mandatory fields already present)
+```
+
+81. **`--account` bulk patches line items** — when used with `clio bills draft finalize`, `--account` resolves the name to a UUID then sets `accountResourceId` on EVERY line item where it's currently null. Existing accounts are NOT overwritten. Same for `--tax-profile`. `--lines` takes priority (full replacement).
+82. **`--dry-run` validates without modifying** — returns the same validation structure as `draft list` (per-field status/hint), so agents can preview what would happen before committing. No API write occurs.
+83. **Finalization is a single PUT** — `updateBill()` with `saveAsDraft: false` transitions DRAFT → UNPAID (per Rule 67) and updates all fields in one call. No delete-and-recreate.
+84. **Draft list attachment count** — `draft list` includes `attachmentCount` per draft (from `GET /bills/:id/attachments`). Use `draft attachments <id>` for full details including `fileUrl` download links.
+
+#### DRY Extension Pattern
+
+Bills, invoices, and credit notes share identical mandatory field specs. Adding `clio invoices draft` or `clio customer-credit-notes draft` later reuses all validation, formatting, and CLI flag logic from `draft-helpers.ts` — only the API calls differ.
+
 ## Supporting Files
 
 For detailed reference, read these files in this skill directory:

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

@@ -919,6 +919,12 @@ Valid `datatypeCode`: `TEXT`, `NUMBER`, `BOOLEAN`, `DATE`, `LINK`.
 
 Processing is **asynchronous** — the API response confirms file upload immediately. The extraction pipeline runs server-side and pushes status updates via Firebase Realtime Database.
 
+**Supported document types:**
+- `INVOICE` → creates a draft sale (response type: `SALE`)
+- `BILL` → creates a draft purchase (response type: `PURCHASE`)
+- `CUSTOMER_CREDIT_NOTE` → creates a draft customer CN (response type: `SALE_CREDIT_NOTE`)
+- `SUPPLIER_CREDIT_NOTE` → creates a draft supplier CN (response type: `PURCHASE_CREDIT_NOTE`)
+
 **Two modes** — content type depends on `sourceType`:
 
 #### FILE mode (multipart/form-data) — most common
@@ -929,7 +935,7 @@ Content-Type: multipart/form-data
 
 Fields:
   - sourceFile: PDF or JPG file blob (NOT "file")
-  - businessTransactionType: "INVOICE" or "BILL" (NOT "EXPENSE")
+  - businessTransactionType: "INVOICE", "BILL", "CUSTOMER_CREDIT_NOTE", or "SUPPLIER_CREDIT_NOTE"
   - sourceType: "FILE"
 ```
 
@@ -941,6 +947,7 @@ Fields:
     "filename": "NB64458.pdf",
     "invalidFiles": [],
     "validFiles": [{
+      "workflowResourceId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
       "subscriptionFBPath": "magic_transactions/{orgId}/purchase/{fileId}",
       "errorCode": null,
       "errorMessage": null,
@@ -980,12 +987,74 @@ Content-Type: application/json
 
 **Key gotchas:**
 - `sourceFile` is the field name (NOT `file`) — same pattern as bank statement endpoint
-- Only `INVOICE` and `BILL` accepted — `EXPENSE` returns 422
-- Response maps types: `INVOICE` → `SALE`, `BILL` → `PURCHASE`
+- `EXPENSE` returns 422 — use one of the 4 valid types above
+- Response maps types: `INVOICE` → `SALE`, `BILL` → `PURCHASE`, `CUSTOMER_CREDIT_NOTE` → `SALE_CREDIT_NOTE`, `SUPPLIER_CREDIT_NOTE` → `PURCHASE_CREDIT_NOTE`
 - JSON body with `sourceType: "FILE"` always fails (400) — MUST use multipart
-- `subscriptionFBPath` is the Firebase path for tracking extraction progress
+- `workflowResourceId` in `validFiles[]` is for tracking via `POST /magic/workflows/search`
+- `subscriptionFBPath` is the Firebase path for real-time status updates
 - All three fields (`sourceFile`/`sourceURL`, `businessTransactionType`, `sourceType`) are required — omitting any returns 422
-- File types confirmed: PDF, JPG/JPEG (handwritten documents accepted — extraction quality varies)
+- File types confirmed: PDF, JPG/JPEG, PNG, HEIC, XLS, XLSX, EML (max 1 MB)
+
+---
+
+### POST /api/v1/magic/workflows/search
+
+Search across magic BT extraction workflows and bank statement imports. Use this to track the status of uploads and retrieve the created draft BT resource ID.
+
+```json
+/ Request:
+POST /api/v1/magic/workflows/search
+Content-Type: application/json
+
+{
+  "filter": {
+    "resourceId": { "eq": "f47ac10b-58cc-4372-a567-0e02b2c3d479" },
+    "documentType": ["SALE", "PURCHASE"],
+    "status": ["COMPLETED"],
+    "fileName": { "contains": "invoice" },
+    "createdAt": { "gte": "2025-01-01", "lte": "2025-12-31" }
+  },
+  "limit": 20,
+  "offset": 0,
+  "sort": { "sortBy": ["createdAt"], "order": "DESC" }
+}
+
+/ Response (200):
+{
+  "data": [{
+    "resourceId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+    "documentType": "SALE",
+    "status": "COMPLETED",
+    "fileName": "invoice.pdf",
+    "fileType": "PDF",
+    "fileUrl": "https://s3...",
+    "fileId": "6e999313...",
+    "createdAt": "2025-01-15",
+    "updatedAt": "2025-01-15",
+    "businessTransactionDetails": {
+      "businessTransactionResourceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+      "ocrJobType": "SYNC",
+      "workflowStatus": "TRANSACTION_CREATED"
+    }
+  }],
+  "totalElements": 1,
+  "totalPages": 1
+}
+```
+
+**Filter fields:**
+- `resourceId`: StringExpression (eq, contains) — workflow ID from magic create response
+- `documentType`: Array — SALE, PURCHASE, SALE_CREDIT_NOTE, PURCHASE_CREDIT_NOTE, BANK_STATEMENT
+- `status`: Array — SUBMITTED, PROCESSING, COMPLETED, FAILED
+- `fileName`: StringExpression — original uploaded filename
+- `fileType`: Array — PDF, PNG, JPEG, JPG, HEIC, CSV, XLS, XLSX, EML
+- `createdAt`: DateExpression (eq, gte, lte) — workflow creation date
+
+**Workflow for agents:**
+1. Upload via `POST /magic/createBusinessTransactionFromAttachment` → get `workflowResourceId`
+2. Search with `filter.resourceId.eq` → check `status`
+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`
 
 ---
 

package/assets/skills/api/references/full-api-surface.md

@@ -381,7 +381,8 @@
 
 | Method | Path | Description |
 |--------|------|-------------|
-| POST | `/magic/createBusinessTransactionFromAttachment` | **Jaz Magic: Extraction & Autofill.** Upload PDF/JPG → full extraction pipeline (OCR, line items, contact matching, CoA ML learning) → draft invoice or bill with all fields autofilled. FILE mode = multipart (`sourceFile` blob), URL mode = JSON (`sourceURL`). Async — returns `subscriptionFBPath` for tracking extraction progress. Request `INVOICE` → response `SALE`, `BILL` → `PURCHASE`. |
+| POST | `/magic/createBusinessTransactionFromAttachment` | **Jaz Magic: Extraction & Autofill.** Upload PDF/JPG → full extraction pipeline (OCR, line items, contact matching, CoA ML learning) → draft transaction with all fields autofilled. Supports `INVOICE`, `BILL`, `CUSTOMER_CREDIT_NOTE`, `SUPPLIER_CREDIT_NOTE`. FILE mode = multipart (`sourceFile` blob), URL mode = JSON (`sourceURL`). Async — returns `workflowResourceId` for tracking via workflow search. Request maps: `INVOICE`→`SALE`, `BILL`→`PURCHASE`, `CUSTOMER_CREDIT_NOTE`→`SALE_CREDIT_NOTE`, `SUPPLIER_CREDIT_NOTE`→`PURCHASE_CREDIT_NOTE`. |
+| POST | `/magic/workflows/search` | **Workflow search.** Track magic upload status across BT extractions and bank imports. Filter by `resourceId`, `documentType` (SALE/PURCHASE/SALE_CREDIT_NOTE/PURCHASE_CREDIT_NOTE/BANK_STATEMENT), `status` (SUBMITTED/PROCESSING/COMPLETED/FAILED), `fileName`, `fileType`, `createdAt`. Response includes `businessTransactionDetails.businessTransactionResourceId` (the draft BT ID) when COMPLETED. |
 | POST | `/magic/importBankStatementFromAttachment` | Convert bank statement → entries |
 | PUT | `/invoices/magic-update` | AI-enhanced invoice update |
 | PUT | `/bills/magic-update` | AI-enhanced bill update |

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 4.2.1
+version: 4.3.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.2.1
+version: 4.3.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

@@ -1,31 +1,34 @@
 # Document Collection
 
-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.
+Scan and classify client documents (invoices, bills, credit notes, bank statements) from local directories or cloud share links (Dropbox, Google Drive, OneDrive). Outputs classified file paths with metadata. Supports encrypted PDF detection and decryption via `qpdf`. The AI agent handles uploads via the api skill.
 
 ## When to Use
 
-- Client sends a folder of PDFs (invoices, bills, receipts) for bulk processing
+- Client sends a folder of PDFs (invoices, bills, credit notes, receipts) for bulk processing
 - Processing bank statement CSVs/OFX files for import
 - Migrating documents from file dumps (Dropbox, shared folders, email attachments)
 - Processing documents from a shared Dropbox, Google Drive, or OneDrive link
 - Batch-processing scanned documents during onboarding
+- Handling password-protected bank statement PDFs (auto-detection + decryption)
 
 ## How It Works
 
 ```
 Source (local or cloud)              CLI Output (IngestPlan)
 ┌───────────────┐                    ┌──────────────────────────────────────────┐
-│ invoices/     │── scan + classify ─► absolutePath, documentType: INVOICE      │
+│ invoices/     │── scan + classify ─► documentType: INVOICE                    │
 │   inv-001.pdf │                    │ sizeBytes: 45230                         │
-│   inv-002.jpg │                    │                                          │
-│ bills/        │── scan + classify ─► absolutePath, documentType: BILL         │
+│ credit-notes/ │── scan + classify ─► documentType: CUSTOMER_CREDIT_NOTE      │
+│   cn-001.pdf  │                    │                                          │
+│ bills/        │── scan + classify ─► documentType: BILL                       │
 │   acme-jan.pdf│                    │                                          │
-│ bank/         │── scan + classify ─► absolutePath, documentType: BANK_STATEMENT│
-│   dbs-jan.csv │                    │                                          │
+│ bank/         │── scan + classify ─► documentType: BANK_STATEMENT             │
+│   dbs-jan.csv │                    │ encrypted: true (if password-protected)  │
+│   dbs-feb.pdf │                    │                                          │
 └───────────────┘                    └──────────────────────────────────────────┘
                                                     │
                                             AI Agent reads plan,
-                                        uploads via api skill (curl)
+                                        uploads via api skill / clio magic
 ```
 
 Cloud links are downloaded to a temp directory first, then scanned through the same pipeline.
@@ -36,14 +39,18 @@ The tool auto-classifies documents by **folder name** (case-insensitive prefix m
 
 | Folder name pattern | Classification |
 |---|---|
-| `invoice*`, `sales*`, `ar*`, `receivable*`, `revenue*` | INVOICE |
+| `invoice*`, `sales*`, `ar*`, `receivable*`, `revenue*`, `customer*` | INVOICE |
+| `credit-note*`, `cn*`, `customer-credit*`, `sales-credit*` | CUSTOMER_CREDIT_NOTE |
+| `debit-note*`, `dn*`, `supplier-credit*`, `vendor-credit*`, `purchase-credit*` | SUPPLIER_CREDIT_NOTE |
 | `bill*`, `purchase*`, `expense*`, `ap*`, `payable*`, `supplier*`, `vendor*`, `cost*` | BILL |
-| `bank*`, `statement*`, `recon*` | BANK_STATEMENT |
+| `bank*`, `statement*`, `recon*`, `payment*`, `transaction*` | BANK_STATEMENT |
 | (unknown) | UNKNOWN — skipped unless `--type` forced |
 
+Multilingual support: Filipino/Tagalog, Bahasa Indonesia/Malay, Vietnamese, and Mandarin (pinyin) folder names are also recognized for all five document types.
+
 ### File Extension Filters
 
-- **Invoices/Bills**: `.pdf`, `.jpg`, `.jpeg`, `.png`
+- **Invoices/Bills/Credit Notes**: `.pdf`, `.jpg`, `.jpeg`, `.png`
 - **Bank Statements**: `.csv`, `.ofx`
 - **Skipped** (with warning): `.xlsx`, `.xls`, `.doc`, `.docx`, `.txt`, `.zip`, `.rar`, `.7z`
 
@@ -88,6 +95,10 @@ clio jobs document-collection ingest --source "https://www.dropbox.com/..." --ti
 
 # Force classification (skip auto-detect)
 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
 ```
 
 ### Options
@@ -95,7 +106,11 @@ clio jobs document-collection ingest --source ./scans/ --type invoice [--json]
 | Flag | Description |
 |------|-------------|
 | `--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` |
+| `--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 |
@@ -129,6 +144,7 @@ The `--json` output includes absolute file paths, classification, and size for e
     "uploadable": 1,
     "needClassification": 0,
     "skipped": 0,
+    "encrypted": 0,
     "byType": { "INVOICE": 1 }
   }
 }
@@ -136,6 +152,36 @@ The `--json` output includes absolute file paths, classification, and size for e
 
 For cloud sources, `localPath` points to the temp directory where files were downloaded.
 
+## Encrypted PDF Support
+
+Bank statements and some government documents are often delivered as password-protected PDFs. The Magic API cannot process encrypted PDFs, so the tool detects them during scan and decrypts before upload.
+
+### Detection
+
+During scan, each `.pdf` file is checked for a `/Encrypt` dictionary entry in the PDF binary. Encrypted files are flagged with `encrypted: true` in the plan and shown with a `(encrypted)` tag in the output.
+
+### Decryption
+
+Decryption requires `qpdf` (a system CLI tool):
+
+```bash
+# Install qpdf
+brew install qpdf        # macOS
+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.
+
+### Error Handling (JSON mode)
+
+If encrypted PDFs are found during `--upload` without the required dependencies, the tool outputs structured errors for agent consumption:
+
+| 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>` |
+
 ## Phases (Blueprint)
 
 When run without `ingest` subcommand, produces a 4-phase blueprint:

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

@@ -1,6 +1,6 @@
 ---
 name: jaz-recipes
-version: 4.2.1
+version: 4.3.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/accounts.js

@@ -2,7 +2,7 @@ import chalk from 'chalk';
 import { listAccounts, searchAccounts, createAccount, deleteAccount } from '../core/api/chart-of-accounts.js';
 import { apiAction } from './api-action.js';
 import { parsePositiveInt, parseNonNegativeInt, readBodyInput, requireFields } from './parsers.js';
-import { paginatedFetch } from './pagination.js';
+import { paginatedFetch, paginatedJson, displaySlice } from './pagination.js';
 export function registerAccountsCommand(program) {
     const accounts = program
         .command('accounts')
@@ -14,18 +14,22 @@ export function registerAccountsCommand(program) {
         .option('--limit <n>', 'Max results (default 100)', parsePositiveInt)
         .option('--offset <n>', 'Offset for pagination', parseNonNegativeInt)
         .option('--all', 'Fetch all pages')
+        .option('--max-rows <n>', 'Max rows for --all (default 10000)', parsePositiveInt)
         .option('--api-key <key>', 'API key (overrides stored/env)')
         .option('--json', 'Output as JSON')
         .action(apiAction(async (client, opts) => {
-        const { data, totalElements, totalPages } = await paginatedFetch(opts, (p) => listAccounts(client, p), { label: 'Fetching accounts' });
+        const result = await paginatedFetch(opts, (p) => listAccounts(client, p), { label: 'Fetching accounts' });
         if (opts.json) {
-            console.log(JSON.stringify({ totalElements, totalPages, data }, null, 2));
+            console.log(paginatedJson(result, opts));
         }
         else {
-            console.log(chalk.bold(`Accounts (${data.length} of ${totalElements}):\n`));
-            for (const a of data) {
+            console.log(chalk.bold(`Accounts (${result.data.length} of ${result.totalElements}):\n`));
+            const { items, overflow } = displaySlice(result.data);
+            for (const a of items) {
                 console.log(`  ${chalk.cyan(a.resourceId)}  ${a.code ?? ''}  ${a.name}  ${chalk.dim(a.accountType)}`);
             }
+            if (overflow > 0)
+                console.log(chalk.dim(`  ... and ${overflow.toLocaleString()} more (use --json for full output)`));
         }
     }));
     // ── clio accounts search ────────────────────────────────────────
@@ -37,24 +41,28 @@ export function registerAccountsCommand(program) {
         .option('--limit <n>', 'Max results (default 20)', parsePositiveInt)
         .option('--offset <n>', 'Offset for pagination', parseNonNegativeInt)
         .option('--all', 'Fetch all pages')
+        .option('--max-rows <n>', 'Max rows for --all (default 10000)', parsePositiveInt)
         .option('--api-key <key>', 'API key (overrides stored/env)')
         .option('--json', 'Output as JSON')
         .action((query, opts) => apiAction(async (client) => {
         const filter = { or: { name: { contains: query }, code: { contains: query } } };
         const sort = { sortBy: [opts.sort ?? 'code'], order: (opts.order ?? 'ASC') };
-        const { data, totalElements, totalPages } = await paginatedFetch(opts, ({ limit, offset }) => searchAccounts(client, { filter, limit, offset, sort }), { label: 'Searching accounts', defaultLimit: 20 });
+        const result = await paginatedFetch(opts, ({ limit, offset }) => searchAccounts(client, { filter, limit, offset, sort }), { label: 'Searching accounts', defaultLimit: 20 });
         if (opts.json) {
-            console.log(JSON.stringify({ totalElements, totalPages, data }, null, 2));
+            console.log(paginatedJson(result, opts));
         }
         else {
-            if (data.length === 0) {
+            if (result.data.length === 0) {
                 console.log(chalk.yellow('No accounts found.'));
                 return;
             }
-            console.log(chalk.bold(`Found ${data.length} account(s):\n`));
-            for (const a of data) {
+            console.log(chalk.bold(`Found ${result.data.length} account(s):\n`));
+            const { items, overflow } = displaySlice(result.data);
+            for (const a of items) {
                 console.log(`  ${chalk.cyan(a.resourceId)}  ${a.code ?? ''}  ${a.name}  ${chalk.dim(a.accountType)}`);
             }
+            if (overflow > 0)
+                console.log(chalk.dim(`  ... and ${overflow.toLocaleString()} more (use --json for full output)`));
         }
     })(opts));
     // ── clio accounts create ──────────────────────────────────────

package/dist/commands/bank.js

@@ -1,7 +1,15 @@
 import chalk from 'chalk';
-import { listBankAccounts, getBankAccount, searchBankRecords, } from '../core/api/bank.js';
+import { readFileSync } from 'node:fs';
+import { basename, extname, resolve } from 'node:path';
+import { listBankAccounts, getBankAccount, searchBankRecords, importBankStatement, } from '../core/api/bank.js';
 import { apiAction } from './api-action.js';
 import { parsePositiveInt } from './parsers.js';
+const BANK_MIME_MAP = {
+    '.csv': 'text/csv',
+    '.ofx': 'application/x-ofx',
+    '.xls': 'application/vnd.ms-excel',
+    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+};
 export function registerBankCommand(program) {
     const bank = program
         .command('bank')
@@ -92,4 +100,38 @@ export function registerBankCommand(program) {
             }
         }
     })(opts));
+    // ── clio bank import ──────────────────────────────────────────
+    bank
+        .command('import')
+        .description('Import a bank statement file (CSV, OFX, XLS, XLSX)')
+        .requiredOption('--file <path>', 'Bank statement file path')
+        .requiredOption('--account <resourceId>', 'Bank account resourceId')
+        .option('--api-key <key>', 'API key (overrides stored/env)')
+        .option('--json', 'Output as JSON')
+        .action(apiAction(async (client, opts) => {
+        const filePath = resolve(opts.file);
+        const ext = extname(filePath).toLowerCase();
+        const mime = BANK_MIME_MAP[ext];
+        if (!mime) {
+            console.error(chalk.red(`Error: unsupported file type "${ext}". Supported: ${Object.keys(BANK_MIME_MAP).join(', ')}`));
+            process.exit(1);
+        }
+        const buffer = readFileSync(filePath);
+        const blob = new Blob([buffer], { type: mime });
+        const fileName = basename(filePath);
+        const res = await importBankStatement(client, {
+            businessTransactionType: 'BANK_STATEMENT',
+            accountResourceId: opts.account,
+            sourceFile: blob,
+            sourceFileName: fileName,
+        });
+        if (opts.json) {
+            console.log(JSON.stringify(res.data, null, 2));
+        }
+        else {
+            console.log(chalk.green('Bank statement uploaded — processing started.'));
+            console.log(chalk.bold('File:'), fileName);
+            console.log(chalk.dim('Check status: clio magic search --type bank-statement'));
+        }
+    }));
 }