jaz-clio 4.2.0 → 4.3.0

package/README.md

@@ -1,299 +1,140 @@
-# Jaz AI
+# Clio — Jaz AI Command Line Tool
 
 <p align="center">
-  <a href="https://github.com/teamtinvio/jaz-ai/releases"><img src="https://img.shields.io/github/v/release/teamtinvio/jaz-ai?style=for-the-badge&color=blue" alt="GitHub Release"></a>
-  <img src="https://img.shields.io/badge/API_rules-70-green?style=for-the-badge" alt="70 API Rules">
-  <img src="https://img.shields.io/badge/skills-4-purple?style=for-the-badge" alt="4 Skills">
-  <img src="https://img.shields.io/badge/recipes-16-orange?style=for-the-badge" alt="16 Recipes">
+  <a href="https://www.npmjs.com/package/jaz-clio"><img src="https://img.shields.io/npm/v/jaz-clio?style=for-the-badge&logo=npm" alt="npm"></a>
+  <a href="https://www.npmjs.com/package/jaz-clio"><img src="https://img.shields.io/npm/dm/jaz-clio?style=for-the-badge&label=downloads" alt="npm downloads"></a>
   <img src="https://img.shields.io/badge/calculators-10-red?style=for-the-badge" alt="10 Calculators">
   <img src="https://img.shields.io/badge/jobs-12-teal?style=for-the-badge" alt="12 Jobs">
   <a href="https://github.com/teamtinvio/jaz-ai/blob/main/LICENSE"><img src="https://img.shields.io/github/license/teamtinvio/jaz-ai?style=for-the-badge&color=green" alt="License"></a>
 </p>
 
-<p align="center">
-  <a href="https://www.npmjs.com/package/jaz-clio"><img src="https://img.shields.io/npm/v/jaz-clio?style=flat-square&logo=npm&label=CLI" alt="npm"></a>
-  <a href="https://www.npmjs.com/package/jaz-clio"><img src="https://img.shields.io/npm/dm/jaz-clio?style=flat-square&label=downloads" alt="npm downloads"></a>
-  <a href="https://github.com/teamtinvio/jaz-ai/stargazers"><img src="https://img.shields.io/github/stars/teamtinvio/jaz-ai?style=flat-square&logo=github" alt="GitHub stars"></a>
-</p>
-
-API reference, financial calculators, IFRS recipes, accounting jobs, data conversion playbooks, and tax computation — directly inside the AI that builders, accountants, and developers are already using to get things done.
+CLI for the [Jaz](https://jaz.ai) accounting platform. Create invoices, record bills, manage contacts, run financial calculators, execute accounting jobs, and install AI agent skills — all from your terminal.
 
-Agent skills for [Jaz](https://jaz.ai) accounting platform. Works with [Claude Code](https://claude.com/claude-code), [Google Antigravity](https://antigravity.google), [OpenAI Codex](https://openai.com/codex), [GitHub Copilot](https://github.com/features/copilot), [Cursor](https://cursor.com), and any tool that supports the [Agent Skills](https://agentskills.io) open standard.
+> Also fully compatible with [Juan Accounting](https://juan.ac).
 
-> All skills, CLI commands, and the plugin are fully compatible with [Juan Accounting](https://juan.ac) too.
+## Prerequisites
 
-## Skills
+**Node.js 18 or later** is required. If `node --version` works, skip ahead.
 
-| Skill | What It Does |
-|-------|-------------|
-| **jaz-api** | 70 rules, full endpoint catalog, error catalog, field mapping. Agents write correct Jaz API code on the first try instead of guessing |
-| **jaz-conversion** | Xero, QuickBooks, Sage, Excel migration playbook. CoA mapping, tax profiles, FX, clearing accounts, trial balance verification |
-| **jaz-recipes** | 16 IFRS-compliant recipes (loans, leases, depreciation, FX reval, ECL, provisions, and more) + 10 CLI financial calculators with blueprint output |
-| **jaz-jobs** | 12 accounting jobs (month/quarter/year-end close, bank recon, document collection, GST/VAT filing, payment runs, credit control, supplier recon, audit prep, FA review, statutory filing) + Singapore Form C-S tax computation with AI-guided wizard workflow |
+Otherwise: download the LTS installer from [nodejs.org](https://nodejs.org). It includes `npm`.
 
-## Installation
-
-### Using Clio CLI (Recommended)
-
-Works with any AI tool. Auto-detects your platform and installs to the right path.
+## Install
 
 ```bash
-# Install CLI globally
 npm install -g jaz-clio
-
-# Go to your project
-cd /path/to/your/project
-
-# Install all skills (auto-detects platform)
-clio init
-
-# Or install a specific skill
-clio init --skill jaz-api
-clio init --skill jaz-conversion
-clio init --skill jaz-recipes
-clio init --skill jaz-jobs
-
-# Force a specific platform
-clio init --platform claude      # → .claude/skills/
-clio init --platform antigravity  # → .agents/skills/
-clio init --platform codex       # → .agents/skills/
-clio init --platform agents      # → .agents/skills/ (universal)
 ```
 
-### Claude Code Marketplace
+## Authenticate
 
-```
-/plugin marketplace add teamtinvio/jaz-ai
-/plugin install jaz-ai@jaz-plugins
-```
+```bash
+# Add your Jaz API key (get one from Settings > API in the Jaz app)
+clio auth add <your-api-key>
 
-### OpenAI Codex
+# Verify it works
+clio auth whoami
 
-```
-$skill-installer https://github.com/teamtinvio/jaz-ai
+# Manage multiple orgs
+clio auth add <another-key>     # Adds a second profile
+clio auth list                  # See all profiles
+clio auth switch <label>        # Switch active org
 ```
 
-### Manual Install
+## Commands
 
-Copy the skill directories into your project:
+### Transactions
 
 ```bash
-# For Antigravity, Codex, Copilot, Cursor (Agent Skills standard)
-cp -r .agents/skills/ /path/to/your/project/.agents/skills/
-
-# For Claude Code
-cp -r .claude/skills/ /path/to/your/project/.claude/skills/
+clio invoices list                     # List invoices
+clio invoices create --contact "ACME"  # Create a draft invoice
+clio invoices pay <id>                 # Record payment
+clio bills list --status APPROVED      # List approved bills
+clio bills pay <id>                    # Pay a bill
+clio customer-credit-notes list        # List customer credit notes
+clio supplier-credit-notes list        # List supplier credit notes
+clio journals list                     # List journal entries
+clio cash-in list                      # List cash-in entries
+clio cash-out list                     # List cash-out entries
+clio cash-transfer list                # List cash transfers
 ```
 
-### Other CLI Commands
+### Contacts, Accounts & Items
 
 ```bash
-clio versions    # List available versions
-clio update      # Update to latest version
-clio --help      # Show all commands
-```
-
-## Usage
-
-Skills activate automatically when you or your agent work with Jaz API code or data conversion tasks. Just describe what you need:
-
-### API Skill
-
-```
-Create an invoice with 3 line items and 7% GST
-
-Build a payment for invoice INV-001 in USD
-
-Query all overdue bills with pagination
-
-Set up chart of accounts for a Singapore company
-```
-
-### Conversion Skill
-
+clio contacts search "ACME"            # Fuzzy search contacts
+clio contacts create --name "ACME Ltd" # Create a contact
+clio accounts list                     # Chart of accounts
+clio items list                        # Products and services
+clio tags list                         # Tracking tags
 ```
-Convert this Xero trial balance export to Jaz
-
-Migrate QuickBooks aged receivables to conversion invoices
-
-Map this Excel chart of accounts to Jaz CoA structure
 
-Verify the trial balance after conversion
-```
+### Financial Calculators
 
-### Transaction Recipes Skill
+10 IFRS-compliant calculators that output structured blueprints with journal entries, workings, and execution plans.
 
+```bash
+clio calc loan --principal 100000 --rate 6 --term 60 --json
+clio calc depreciation --cost 50000 --salvage 5000 --life 5 --method ddb --json
+clio calc lease --value 120000 --term 36 --rate 5 --json
+clio calc ecl --receivables '[{"bucket":"0-30","balance":50000,"rate":0.5}]' --json
+clio calc provision --amount 100000 --rate 4 --periods 24 --json
+clio calc fx-reval --account "USD Cash" --balance 10000 --old-rate 1.35 --new-rate 1.34 --json
+clio calc fixed-deposit --principal 100000 --rate 3.5 --term 12 --json
+clio calc disposal --cost 50000 --accum-dep 30000 --proceeds 15000 --json
+clio calc amortization --amount 12000 --periods 12 --start 2025-01-01 --json
+clio calc hire-purchase --value 80000 --term 48 --rate 4.5 --json
 ```
-Set up a 5-year bank loan with monthly repayment schedule
-
-Model IFRS 16 lease for a 3-year office lease at 5% IBR
 
-Calculate ECL provision on aged receivables
+### Accounting Jobs
 
-Record prepaid insurance with monthly amortization via capsule
-```
+12 job blueprints that generate step-by-step playbooks with checklists and paired tools.
 
-### Jobs Skill
+```bash
+clio jobs month-end --period 2025-01                            # Month-end close
+clio jobs quarter-end --period 2025-Q1                          # Quarter-end close
+clio jobs year-end --period 2025                                # Year-end close
+clio jobs bank-recon match --input bank-data.json --json        # Bank reconciliation matcher
+clio jobs document-collection ingest --source "./receipts" --json  # Document scanner
+clio jobs gst-vat --period 2025-Q1                              # GST/VAT filing prep
+clio jobs payment-run --due-before 2025-02-28                   # Payment run
+clio jobs credit-control                                        # AR aging + chase list
+clio jobs supplier-recon                                        # AP vs supplier statements
+clio jobs audit-prep --period 2025                              # Audit pack
+clio jobs fa-review                                             # Fixed asset review
+clio jobs statutory-filing sg-cs --ya 2026 --revenue 500000 --profit 120000 --json  # SG Form C-S
+```
+
+### Other
 
+```bash
+clio org info                          # Current org details
+clio currencies list                   # Enabled currencies
+clio currency-rates list               # Exchange rates
+clio payments search                   # Search payments
+clio bank import --file statement.csv  # Import bank statement
+clio reports generate --type pnl       # Generate reports
+clio capsules list                     # List capsules (transaction groups)
+clio versions                          # Show version info
+clio update                            # Update to latest
 ```
-Close the books for January 2025
-
-Run bank reconciliation for DBS Current account
 
-Prepare GST return for Q1 2025
+Every command supports `--json` for structured output — ideal for piping to other tools or for AI agents.
 
-Generate a payment run for all overdue bills
+## Install AI Skills
 
-Prepare audit pack for FY 2025
-```
-
-### Financial Calculators & Job Tools (CLI)
+Clio also installs AI agent skills into your project. Skills are knowledge files that teach AI tools (Claude Code, Antigravity, Codex, Copilot, Cursor) how to work with the Jaz API.
 
 ```bash
-clio calc loan --principal 100000 --rate 6 --term 60 --json
-clio calc depreciation --cost 50000 --salvage 5000 --life 5 --method ddb --json
-clio jobs bank-recon match --input bank-data.json --json
-clio jobs document-collection ingest --source "https://www.dropbox.com/scl/fo/..." --json
-clio jobs statutory-filing sg-cs --ya 2026 --revenue 500000 --profit 120000 --json
+cd /path/to/your/project
+clio init                              # Auto-detects your AI tool, installs all 4 skills
+clio init --skill jaz-api              # Install a specific skill
+clio init --platform claude            # Force a specific platform
 ```
 
-10 financial calculators, 12 job blueprints, and paired tools (bank matcher, document ingest with cloud support, SG Form C-S tax computation). Add `--json` for structured blueprint output with capsule type, journal entries, workings, and step-by-step execution plan.
-
-Full command reference: [transaction-recipes skill](src/skills/transaction-recipes/SKILL.md) and [jobs skill](src/skills/jobs/SKILL.md).
-
-## What's Inside
-
-### API Skill (`jaz-api`)
-
-| Reference | Lines | Content |
-|-----------|-------|---------|
-| `SKILL.md` | 185 | 70 critical rules — auth, IDs, dates, FX, payments, field aliases, response shapes |
-| `endpoints.md` | 1,299 | Request/response examples for every core endpoint |
-| `errors.md` | 751 | Error catalog with root causes and fixes |
-| `field-map.md` | 428 | Intuitive name -> actual field name mapping |
-| `search-reference.md` | 714 | Filter fields, sort fields, operators for 28 search endpoints |
-| `full-api-surface.md` | 699 | Complete endpoint catalog (80+), enums, limits |
-| `dependencies.md` | 139 | Resource creation order (currencies -> CoA -> transactions) |
-| `feature-glossary.md` | 216 | Business context per feature |
-
-### Conversion Skill (`jaz-conversion`)
-
-| Reference | Content |
-|-----------|---------|
-| `SKILL.md` | Conversion domain knowledge, clearing account pattern, FX handling |
-| `mapping-rules.md` | CoA, contact, and tax code mapping rules |
-| `option1-full.md` | Full conversion workflow (all transactions FY + FY-1) |
-| `option2-quick.md` | Quick conversion workflow (opening balances at FYE) |
-| `file-types.md` | Supported file formats and detection heuristics |
-| `edge-cases.md` | Platform-specific quirks (Sage 300 preambles, Xero rounding) |
-| `verification.md` | Trial balance comparison and verification checklist |
-| `file-analysis.md` | Excel/CSV structure analysis and smart detection |
-
-### Transaction Recipes Skill (`jaz-recipes`)
-
-| Reference | Content |
-|-----------|---------|
-| `SKILL.md` | 16 recipes in 4 tiers, building blocks, key principles, calculator index |
-| `building-blocks.md` | Capsules, schedulers, manual journals, FA, tracking tags, nano classifiers |
-| `prepaid-amortization.md` | Annual insurance/rent paid upfront, monthly scheduler recognition |
-| `deferred-revenue.md` | Upfront customer payment, monthly revenue recognition |
-| `accrued-expenses.md` | Month-end accrual + reversal cycle using dual schedulers |
-| `bank-loan.md` | Loan disbursement, amortization table, monthly installments |
-| `ifrs16-lease.md` | ROU asset + lease liability unwinding (IFRS 16) |
-| `declining-balance.md` | DDB/150DB with switch-to-SL logic |
-| `fixed-deposit.md` | Placement, compound interest accrual, maturity (IFRS 9) |
-| `hire-purchase.md` | Like IFRS 16 but depreciate over useful life |
-| `asset-disposal.md` | Sale/scrap/write-off with gain/loss (IAS 16) |
-| `fx-revaluation.md` | Non-AR/AP FX revaluation with Day 1 reversal (IAS 21) |
-| `bad-debt-provision.md` | ECL simplified approach provision matrix (IFRS 9) |
-| `employee-accruals.md` | Leave (scheduler) + bonus (manual) accruals (IAS 19) |
-| `provisions.md` | PV recognition + monthly discount unwinding (IAS 37) |
-| `dividend.md` | Declaration + payment (two manual journals) |
-| `intercompany.md` | Mirrored invoices/bills across two entities |
-| `capital-wip.md` | CIP accumulation → FA transfer on completion |
-
-
-### Jobs Skill (`jaz-jobs`)
-
-| Reference | Content |
-|-----------|---------|
-| `SKILL.md` | 12 accounting jobs + SG tax computation, CLI commands, wizard workflow overview |
-| `building-blocks.md` | Shared concepts: accounting periods, lock dates, period verification |
-| `month-end-close.md` | 5 phases, ~18 steps — the foundation for all period closes |
-| `quarter-end-close.md` | Monthly + quarterly extras (GST/VAT, ECL, bonus accruals) |
-| `year-end-close.md` | Quarterly + annual extras (true-ups, dividends, CYE rollover) |
-| `bank-recon.md` | Match, categorize, resolve unreconciled items |
-| `bank-match.md` | Bank reconciliation matcher — 5-phase cascade algorithm (1:1, N:1, 1:N, N:M) |
-| `document-collection.md` | Scan and classify documents from local directories and cloud links (Dropbox, Google Drive, OneDrive) — outputs file paths for agent upload |
-| `gst-vat-filing.md` | Tax ledger review, discrepancy check, filing summary |
-| `payment-run.md` | Select outstanding bills by due date, process payments |
-| `credit-control.md` | AR aging review, overdue chase list, bad debt assessment |
-| `supplier-recon.md` | AP vs supplier statement, identify mismatches |
-| `audit-prep.md` | Compile reports, schedules, reconciliations for auditor |
-| `fa-review.md` | Fixed asset register review, disposal/write-off processing |
-| `sg-tax/overview.md` | SG CIT framework: 17% rate, YA concept, Form C-S eligibility |
-| `sg-tax/form-cs-fields.md` | 18 Form C-S + 6 C-S Lite fields with IRAS labels |
-| `sg-tax/wizard-workflow.md` | Step-by-step AI agent wizard procedure |
-| `sg-tax/data-extraction.md` | How to pull P&L, TB, GL, FA from Jaz API for tax |
-| `sg-tax/add-backs-guide.md` | Which expenses are non-deductible + GL patterns |
-| `sg-tax/capital-allowances-guide.md` | S19, S19A, S19B, S14Q rules per asset category |
-| `sg-tax/ifrs16-tax-adjustment.md` | IFRS 16 lease reversal for tax purposes |
-| `sg-tax/enhanced-deductions.md` | R&D (250-400%), IP, donations (250% IPC), S14Q |
-| `sg-tax/exemptions-and-rebates.md` | SUTE, PTE, CIT rebate schedule by YA |
-| `sg-tax/losses-and-carry-forwards.md` | Set-off order, carry-forward rules |
-
-## Architecture
-
-```
-.claude-plugin/                  Claude Code marketplace manifest
-├── plugin.json
-└── marketplace.json
-
-.agents/skills/                  Agent Skills standard (Codex, Copilot, Cursor)
-├── api/            → src/skills/api/
-├── conversion/     → src/skills/conversion/
-├── transaction-recipes/ → src/skills/transaction-recipes/
-└── jobs/           → src/skills/jobs/
-
-.claude/skills/                  Claude Code native path
-├── api/            → src/skills/api/
-├── conversion/     → src/skills/conversion/
-├── transaction-recipes/ → src/skills/transaction-recipes/
-└── jobs/           → src/skills/jobs/
-
-src/skills/                      Source of truth (single copy, dual discovery paths)
-├── api/                         70 rules + 7 reference files
-├── conversion/                  Conversion domain + 7 reference files
-├── transaction-recipes/         16 recipes + 18 reference files
-└── jobs/                        12 jobs + 12 job files + 10 sg-tax files
-
-src/                             npm CLI (jaz-clio)
-├── commands/                    CLI command handlers (23 command groups)
-│   ├── calc.ts                  10 financial calculator commands
-│   ├── jobs.ts                  Job blueprints + nested tools
-│   ├── invoices.ts              Invoice CRUD + pay + apply-credits + download
-│   ├── bills.ts                 Bill CRUD + pay + apply-credits
-│   ├── customer-credit-notes.ts CCN CRUD + refund + refunds (list)
-│   ├── supplier-credit-notes.ts SCN CRUD + refund + refunds (list)
-│   ├── contacts.ts              Contact CRUD + search
-│   ├── journals.ts              Journal entries + search
-│   ├── cash-entry.ts            Cash-in / cash-out journals
-│   ├── cash-transfer.ts         Cash transfer journals
-│   ├── currencies.ts            Currency list + enable
-│   ├── currency-rates.ts        Exchange rate CRUD
-│   └── ...                      10 more (auth, org, bank, accounts, reports, etc.)
-├── core/                        Shared logic
-│   ├── api/                     Jaz REST client (30+ modules, 70+ endpoints)
-│   ├── calc/                    10 financial calculators
-│   ├── jobs/                    12 job blueprints + paired tools
-│   ├── auth/                    Credential management
-│   └── intelligence/            Fuzzy matching, date parsing, contact resolution
-└── assets/skills/               Bundled skill content for npm package
-```
+See the [full README](https://github.com/teamtinvio/jaz-ai) for skill details, reference file catalogs, and plugin installation.
 
 ## Common API Gotchas
 
-Mistakes the skill prevents — for agents and humans alike:
+Mistakes the CLI and skills prevent:
 
 | Gotcha | Wrong | Right |
 |--------|-------|-------|
@@ -308,4 +149,4 @@ Mistakes the skill prevents — for agents and humans alike:
 
 ## License
 
-[MIT](LICENSE) - Copyright (c) 2026 Tinvio / Jaz
+[MIT](https://github.com/teamtinvio/jaz-ai/blob/main/LICENSE) - Copyright (c) 2026 Tinvio / Jaz

package/assets/skills/api/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: jaz-api
-version: 4.2.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.
+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/Juan API key (x-jk-api-key header). Works with Claude Code, Claude Cowork, Claude.ai, and any agent that reads markdown.
+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.
 ---
 
 # Jaz API Skill
 
-You are working with the **Jaz/Juan REST API** — the backend for Jaz (Singapore) and Juan (Philippines) accounting platforms.
+You are working with the **Jaz REST API** — the accounting platform backend. Also fully compatible with Juan Accounting (same API, same endpoints).
 
 ## When to Use This Skill
 
@@ -94,7 +94,7 @@ You are working with the **Jaz/Juan REST API** — the backend for Jaz (Singapor
 | 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/Juan REST API** — the backend for Jaz (Singapor
 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/Juan REST API** — the backend for Jaz (Singapor
 ### 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/Juan REST API** — the backend for Jaz (Singapor
 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`
 
 ---