jaz-clio 3.4.1 → 4.1.0

package/README.md

@@ -1,79 +1,88 @@
-# Clio — Command Line Interface Orchestrator for Jaz AI
+# Jaz AI
 
-Agent skills + financial calculators + tax computation for the [Jaz](https://jaz.ai) and [Juan](https://juan.ac) accounting platforms.
+<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">
+  <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>
 
-Works with Claude Code, OpenAI Codex, GitHub Copilot, Cursor, and any tool supporting the [Agent Skills](https://agentskills.io) open standard.
+<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>
 
-## Install
+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.
 
-```bash
-npm install -g jaz-clio
-```
+Agent skills for [Jaz](https://jaz.ai) and [Juan](https://juan.ac) accounting platforms. Works with [Claude Code](https://claude.com/claude-code), [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.
 
 ## Skills
 
-Install agent skills into your project — auto-detects your AI tool.
+| 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 |
+
+## Installation
+
+### Using Clio CLI (Recommended)
+
+Works with any AI tool. Auto-detects your platform and installs to the right path.
 
 ```bash
-clio init                            # All skills (auto-detect platform)
-clio init --skill api                # API only
-clio init --skill conversion         # Conversion only
-clio init --skill transaction-recipes # Transaction recipes only
-clio init --skill jobs               # Jobs only
+# Install CLI globally
+npm install -g jaz-clio
 
-clio init --platform claude          # Force Claude Code path
-clio init --platform codex           # Force Codex/Agent Skills path
-```
+# Go to your project
+cd /path/to/your/project
 
-| Skill | What It Does |
-|-------|-------------|
-| **api** | 56 rules, full endpoint catalog, error catalog, field mapping |
-| **conversion** | Xero, QuickBooks, Sage, Excel migration playbook |
-| **transaction-recipes** | 16 IFRS-compliant recipes + 10 financial calculators |
-| **jobs** | 12 accounting jobs + Singapore Form C-S tax computation |
+# Install all skills (auto-detects platform)
+clio init
 
-## Financial Calculators
+# 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
 
-```bash
-clio calc loan --principal 100000 --rate 6 --term 60 [--json]
-clio calc lease --payment 5000 --term 36 --rate 5 [--json]
-clio calc depreciation --cost 50000 --salvage 5000 --life 5 --method ddb [--json]
-clio calc prepaid-expense --amount 12000 --periods 12 [--json]
-clio calc deferred-revenue --amount 36000 --periods 12 [--json]
-clio calc fixed-deposit --principal 100000 --rate 3.5 --term 12 [--json]
-clio calc asset-disposal --cost 50000 --salvage 5000 --life 5 --acquired 2022-01-01 --disposed 2025-06-15 --proceeds 20000 [--json]
-clio calc fx-reval --amount 50000 --book-rate 1.35 --closing-rate 1.38 [--json]
-clio calc ecl --current 100000 --30d 50000 --60d 20000 --90d 10000 --120d 5000 --rates 0.5,2,5,10,50 [--json]
-clio calc provision --amount 500000 --rate 4 --term 60 [--json]
+# Force a specific platform
+clio init --platform claude      # → .claude/skills/
+clio init --platform codex       # → .agents/skills/
+clio init --platform agents      # → .agents/skills/ (universal)
 ```
 
-Add `--json` for structured blueprint output with capsule type, journal entries, workings, and step-by-step execution plan. All calculators support `--currency <code>`.
+### Claude Code Marketplace
 
-## Job Tools
-
-Jobs can have paired tools as nested subcommands:
+```
+/plugin marketplace add teamtinvio/jaz-ai
+/plugin install jaz-ai@jaz-plugins
+```
 
-```bash
-# Bank reconciliation matcher (5-phase cascade: 1:1, N:1, 1:N, N:M)
-clio jobs bank-recon match --input bank-data.json [--tolerance 0.01] [--date-window 14] [--json]
+### OpenAI Codex
 
-# Document collection — scan and classify client documents (outputs file paths for agent upload)
-clio jobs document-collection ingest --source ./client-docs/ [--json]                              # local directory
-clio jobs document-collection ingest --source "https://www.dropbox.com/scl/fo/..." [--json]        # Dropbox folder
-clio jobs document-collection ingest --source "https://drive.google.com/file/d/..." [--json]       # Google Drive file
+```
+$skill-installer https://github.com/teamtinvio/jaz-ai
 ```
 
-## Tax Computation (Singapore Form C-S)
+### Manual Install
 
-Tax computation is under the `statutory-filing` job:
+Copy the skill directories into your project:
 
 ```bash
-clio jobs statutory-filing sg-cs --input tax-data.json [--json]
-clio jobs statutory-filing sg-cs --ya 2026 --revenue 500000 --profit 120000 --depreciation 15000 --exemption pte [--json]
-clio jobs statutory-filing sg-ca --ya 2026 --cost 50000 --category general --acquired 2024-06-15 [--json]
+# For 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/
 ```
 
-## Other Commands
+### Other CLI Commands
 
 ```bash
 clio versions    # List available versions
@@ -81,11 +90,219 @@ clio update      # Update to latest version
 clio --help      # Show all commands
 ```
 
-## Documentation
+## Usage
+
+Skills activate automatically when you or your agent work with Jaz/Juan 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
+
+```
+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
+```
+
+### Transaction Recipes Skill
+
+```
+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
+
+Record prepaid insurance with monthly amortization via capsule
+```
+
+### Jobs Skill
+
+```
+Close the books for January 2025
+
+Run bank reconciliation for DBS Current account
+
+Prepare GST return for Q1 2025
+
+Generate a payment run for all overdue bills
+
+Prepare audit pack for FY 2025
+```
+
+### Financial Calculators & Job Tools (CLI)
+
+```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
+```
+
+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
+```
+
+## Common API Gotchas
+
+Mistakes the skill prevents — for agents and humans alike:
 
-- [Full documentation](https://github.com/teamtinvio/jaz-ai)
-- [Jaz Help Center](https://help.jaz.ai)
+| Gotcha | Wrong | Right |
+|--------|-------|-------|
+| Auth header | `Authorization: Bearer ...` | `x-jk-api-key: ...` |
+| ID field | `id` | `resourceId` |
+| Date field | `issueDate`, `date` | `valueDate` |
+| FX currency | `currencyCode: "USD"` | `currency: { sourceCurrency: "USD" }` |
+| Org endpoint | `{ data: [...] }` | `{ data: { ... } }` (single object) |
+| Payments | `[{ ... }]` | `{ payments: [{ ... }] }` (wrapped) |
+| CN Refunds | `{ payments: [{ paymentAmount }] }` | `{ refunds: [{ refundAmount }] }` |
+| Apply credits | `{ amount: 100 }` | `{ credits: [{ creditNoteResourceId, amountApplied }] }` |
 
 ## License
 
-[MIT](https://github.com/teamtinvio/jaz-ai/blob/main/LICENSE) - Copyright (c) 2026 Tinvio / Jaz
+[MIT](LICENSE) - Copyright (c) 2026 Tinvio / Jaz

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: api
-version: 3.4.1
+name: jaz-api
+version: 4.1.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.
@@ -53,7 +53,7 @@ You are working with the **Jaz/Juan REST API** — the backend for Jaz (Singapor
 
 ### Chart of Accounts
 17. **Tax profiles pre-exist** — NEVER create them. Only GET and map.
-18. **Bank accounts are CoA entries** with `accountType: "Bank Accounts"`. No separate endpoint.
+18. **Bank accounts are CoA entries** with `accountType: "Bank Accounts"`. A convenience endpoint `GET /bank-accounts` exists but returns a **flat array** `[{...}]` — NOT the standard paginated `{ data, totalElements, totalPages }` shape. Normalize before use.
 19. **CoA bulk-upsert wrapper is `accounts`** — not `chartOfAccounts`.
 20. **CoA POST uses `currency`** — not `currencyCode`. (Asymmetry — GET returns `currencyCode`.)
 21. **CoA POST uses `classificationType`** — GET returns `accountType`. Same values.
@@ -113,10 +113,10 @@ You are working with the **Jaz/Juan REST API** — the backend for Jaz (Singapor
 41. **Invoice GET uses `organizationAccountResourceId`** for line item accounts — POST uses `accountResourceId`. Request-side aliases resolve `issueDate` → `valueDate`, `bankAccountResourceId` → `accountResourceId`, etc.
 42. **Scheduler GET returns `interval`** — POST uses `repeat`. (Response-side asymmetry remains.)
 43. **Search sort is an object** — `{ sort: { sortBy: ["valueDate"], order: "DESC" } }`. Required when `offset` is present (even `offset: 0`).
-44. **Bank records: two import methods** — Multipart CSV/OFX via `POST /magic/importBankStatementFromAttachment` (fields: `sourceFile`, `accountResourceId`, `businessTransactionType: "BANK_STATEMENT"`, `sourceType: "FILE"`). JSON via `POST /bank-records/:accountResourceId` with `{ records: [{description, netAmount, valueDate, ...}] }`.
+44. **Bank records: two import methods** — Multipart CSV/OFX via `POST /magic/importBankStatementFromAttachment` (camelCase fields: `sourceFile`, `accountResourceId`, `businessTransactionType: "BANK_STATEMENT"`, `sourceType: "FILE"` — same camelCase rule as rule 59). JSON via `POST /bank-records/:accountResourceId` with `{ records: [{description, netAmount, valueDate, ...}] }`.
 45. **Withholding tax** on bills/supplier CNs only. Retry pattern: if `WITHHOLDING_CODE_NOT_FOUND`, strip field and retry.
 46. **Known API bugs (500s)**: Contact groups PUT, custom fields PUT, capsules POST, catalogs POST, inventory balances GET — all return 500.
-47. **Non-existent endpoints**: `POST /deposits` and `POST /inventory/adjustments` return 404 — these endpoints are not implemented.
+47. **Non-existent endpoints**: `POST /deposits`, `POST /inventory/adjustments`, `GET /payments` (list), and `POST /payments/search` return 404 — these endpoints are not implemented. To list/search payments, use `POST /cashflow-transactions/search` (the unified transaction ledger — see Rule 63).
 48. **Attachments require PDF/PNG**: `POST /:type/:id/attachments` uses multipart `file` field but rejects `text/plain`. Use `application/pdf` or `image/png`.
 49. **Currency rate direction: `rate` = functionalToSource (1 base = X foreign)** — POST `rate: 0.74` for a SGD org means 1 SGD = 0.74 USD. **If your data stores rates as "1 USD = 1.35 SGD" (sourceToFunctional), you MUST invert: `rate = 1 / 1.35 = 0.74`.** GET confirms both: `rateFunctionalToSource` (what you POSTed) and `rateSourceToFunctional` (the inverse).
 
@@ -125,17 +125,43 @@ You are working with the **Jaz/Juan REST API** — the backend for Jaz (Singapor
 51. **Filter operator reference** — String: `eq`, `neq`, `contains`, `in` (array, max 100), `likeIn` (array, max 100), `reg` (regex array, max 100), `isNull` (bool). Numeric: `eq`, `gt`, `gte`, `lt`, `lte`, `in`. Date (YYYY-MM-DD): `eq`, `gt`, `gte`, `lt`, `lte`, `between` (exactly 2 values). DateTime (RFC3339): same operators, converted to epoch ms internally. Boolean: `eq`. JSON: `jsonIn`, `jsonNotIn`. Logical: nest with `and`/`or`/`not` objects, or use `andGroup`/`orGroup` arrays (invoices, bills, journals, credit notes).
 52. **Date format asymmetry (CRITICAL)** — Request dates: `YYYY-MM-DD` strings (all create/update and DateExpression filters). Request datetimes: RFC3339 strings (DateTimeExpression filters for `createdAt`, `updatedAt`, `approvedAt`, `submittedAt`). **ALL response dates**: `int64` epoch milliseconds — including `valueDate`, `createdAt`, `updatedAt`, `approvedAt`, `submittedAt`, `matchDate`. Convert: `new Date(epochMs).toISOString().slice(0,10)`.
 53. **Field aliases on create endpoints** — Middleware transparently maps: `issueDate`/`date` → `valueDate` (invoices, bills, credit notes, journals). `name` → `tagName` (tags) or `internalName` (items). `paymentDate` → `valueDate`, `bankAccountResourceId` → `accountResourceId` (payments). `paymentAmount` → `refundAmount`, `paymentMethod` → `refundMethod` (credit note refunds). `accountType` → `classificationType`, `currencyCode` → `currency` (CoA). Canonical names always work; aliases are convenience only.
-54. **All search/list responses are flat** — every search and list endpoint returns `{ totalElements, totalPages, data: [...] }` directly (no outer `data` wrapper). Access the array via `response.data`, pagination via `response.totalElements`.
+54. **All search/list responses are flat** — every search and list endpoint returns `{ totalElements, totalPages, data: [...] }` directly (no outer `data` wrapper). Access the array via `response.data`, pagination via `response.totalElements`. **Two exceptions**: (a) `GET /bank-accounts` returns a plain array `[{...}]` (see Rule 18), (b) `GET /invoices/:id` returns a flat object `{...}` (no `data` wrapper) — unlike `GET /bills/:id`, `GET /contacts/:id`, `GET /journals/:id` which wrap in `{ data: {...} }`. Normalize the invoice GET response before use.
 55. **Scheduled endpoints support date aliases** — `txnDateAliases` middleware (mapping `issueDate`/`date` → `valueDate`) now applies to all scheduled create/update endpoints: `POST/PUT /scheduled/invoices`, `POST/PUT /scheduled/bills`, `POST/PUT /scheduled/journals`, `POST/PUT /scheduled/subscriptions`.
 56. **Kebab-case URL aliases** — `capsuleTypes` endpoints also accept kebab-case paths: `/capsule-types` (list, search, CRUD). `moveTransactionCapsules` also accepts `/move-transaction-capsules`. Both camelCase and kebab-case work identically.
 
 ### 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.
+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.
 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.
+
+### 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.
+65. **Contacts search uses `name`** — NOT `billingName`. The filter field for searching contacts by name is `name` (maps to `billingName` internally). Sort field is also `name`. Using `billingName` in a search filter returns zero results.
+
+### Response Shape Gotchas
+66. **Contact boolean fields are `customer`/`supplier`** — NOT `isCustomer`/`isSupplier`. These are plain booleans on the contact object: `{ "customer": true, "supplier": false }`. Using `isCustomer` or `isSupplier` in code will be `undefined`.
+67. **Finalized statuses differ by resource type** — NOT `"FINALIZED"`, `"FINAL"`, or `"POSTED"`. Journals → `"APPROVED"`. Invoices/Bills → `"UNPAID"` (progresses to `"PAID"`, `"OVERDUE"`). Customer/Supplier Credit Notes → `"UNAPPLIED"` (progresses to `"APPLIED"`). All types support `"DRAFT"` and `"VOIDED"`. When creating without `saveAsDraft: true`, the response status matches the type's finalized status.
+68. **Create/pay responses are minimal** — POST create endpoints (invoices, bills, journals, contacts, payments) return only `{ resourceId: "..." }` (plus a few metadata fields). They do NOT return the full entity. To verify field values after creation, you MUST do a subsequent `GET /:type/:resourceId`. Never assert on field values from a create response.
+69. **No `amountDue` field** — Invoices and bills do NOT have an `amountDue` field. To check if a transaction is fully paid, inspect the `paymentRecords` array: if `paymentRecords.length > 0`, payments exist. Compare `totalAmount` with the sum of `paymentRecords[].transactionAmount` to determine remaining balance.
+70. **Response dates include time component** — Even though request dates are `YYYY-MM-DD`, response dates are epoch milliseconds (see Rule 52). When comparing dates from responses, always convert with `new Date(epochMs).toISOString().slice(0, 10)` — never string-match against the raw epoch value.
+71. **Items POST requires `saleItemName`/`purchaseItemName`** — When creating items with `appliesToSale: true` or `appliesToPurchase: true`, you MUST include `saleItemName` and/or `purchaseItemName` respectively. These are the display names shown on sale/purchase documents. Omitting them causes 422: "saleItemName is a required field". If not specified, default to the `internalName` value.
+72. **Items PUT requires `itemCode` + `internalName`** — Even for partial updates, `PUT /items/:id` requires both `itemCode` and `internalName` in the body. Omitting either causes 422. Use read-modify-write pattern: GET current item, merge your updates, PUT the full payload. Clio handles this automatically.
+73. **Capsules PUT requires `resourceId` + `capsuleTypeResourceId`** — Even for partial updates, `PUT /capsules/:id` requires `resourceId` and `capsuleTypeResourceId` in the body. Omitting either causes 422 or "Capsule type not found". Use read-modify-write pattern: GET current capsule, merge updates, PUT full payload. Clio handles this automatically.
+
+### Cash Entry Response Shape (CRITICAL)
+74. **Cash-in/out/transfer CREATE returns `parentEntityResourceId`** — The resourceId in the POST response (`{ data: { resourceId: "X" } }`) is the journal header's `parentEntityResourceId`. This ID is used for DELETE (`DELETE /cashflow-journals/X`). But it is **NOT** the same ID used for GET (`GET /cash-in-journals/:id`). GET expects the cashflow-transaction `resourceId` from the LIST response. Three different IDs exist per cash entry: `parentEntityResourceId` (from CREATE + in LIST), `resourceId` (cashflow-transaction ID, from LIST — use for GET), `businessTransactionResourceId` (underlying journal ID — do NOT use for anything).
+75. **Cash-in/out/transfer LIST/GET return cashflow-transaction shape** — NOT journal shape. Key field differences from journals: `transactionReference` (NOT `reference`), `transactionStatus` (NOT `status` — values: `ACTIVE`/`VOID`), `valueDate` is epoch ms (NOT ISO string), no `journalEntries` array, has `direction` (`PAYIN`/`PAYOUT`), has nested `account` object with bank name, has `businessTransactionType` (`JOURNAL_DIRECT_CASH_IN`/`JOURNAL_DIRECT_CASH_OUT`/`JOURNAL_CASH_TRANSFER`).
+76. **Cash-in/out/transfer search uses `/cashflow-transactions/search`** — Filter by `businessTransactionType: { eq: "JOURNAL_DIRECT_CASH_IN" }` (or `JOURNAL_DIRECT_CASH_OUT` or `JOURNAL_CASH_TRANSFER`). Other useful filters: `organizationAccountResourceId` (bank account), `businessTransactionReference` (reference), `valueDate` (date range). The search endpoint is shared across all cashflow transaction types.
+77. **DELETE for cash entries uses `/cashflow-journals/:id`** — NOT the individual resource paths. The ID used is the `parentEntityResourceId` (= the resourceId returned by CREATE). This is a shared endpoint for all cash journal types (cash-in, cash-out, cash-transfer).
+
+### Entity Resolution (Fuzzy Matching)
+78. **`--contact`, `--account`, and `--bank-account` accept names** — any CLI flag that takes a contact, chart of accounts entry, or bank account accepts EITHER a UUID resourceId OR a fuzzy name. Examples: `--contact "ACME Corp"`, `--account "DBS Operating"`, `--bank-account "Business"`. The CLI auto-resolves to the best match (strict thresholds) and shows the resolved entity on stderr. UUIDs are passed through without API calls. If the match is ambiguous, the CLI errors with a list of candidates — never silently picks the wrong entity.
+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.
 
 ## Supporting Files
 

package/assets/skills/api/help-center-mirror/ai-agents.md

@@ -0,0 +1,142 @@
+### Agent Builder
+Source: https://help.jaz.ai/en/articles/10631219-agent-builder
+
+**Q1. What is an AI Agent?**
+
+- Jaz’s AI Agent allows you to send emails to perform accounting and finance tasks for your organizations.
+- All actions taken by your agent are recorded as your own in Jaz.
+- Agent tasks follow your user permissions and execute actions on your behalf.
+
+**Q2. How do I set up my AI Agent?**
+
+- Head over to Settings > Agent Builder and set the following according to your preferences:
+  - Name
+  - Email
+    - Create an agent's email using letters (a-z), numbers (0-9), and the plus (+) symbol.
+    - Using the plus (+) symbol is a good way to differentiate agents per organization, for example: [myagent+greengrocery@sendjaz.com](mailto:myagent+greengrocery@sendjaz.com)
+  - Tone
+    - Friendly
+    - Formal
+    - Focused
+  - Skill Level
+    - Assistant
+    - Analyst (Growth Plan only)
+    - Associate (Coming soon)
+  - Memory
+    - Predefined
+    - Progressive (Growth Plan only)
+  - Preferred Language
+
+**Q3. What tasks can the AI Agent perform?**
+
+The AI Agent can perform the following functions for paid organizations:
+- Bookmarks
+  - Create, review, and manage bookmarks.
+- Chart of Accounts
+  - Create, update, and search accounts and types.
+- Contacts & Items
+  - Create, update, and search contacts and items.
+- Currency Management
+  - Add, update, and retrieve currencies and exchange rates.
+- Draft Transactions
+  - Create draft invoices, bills, and journals.
+- Jaz Magic (Invoices & Bills)
+  - Autofill invoice and bill drafts from emails or attachments.
+- Reports & Data Exports
+  - Generate balance sheets, P&L, cash flow, and other reports.
+- Tax Profiles
+  - Create tax profiles.
+- Direct Cash Transactions
+  - Record direct cash inflows, outflows, or transfers.
+  - Note: Only available for organizations under Growth Plan.
+- Updates, Voids, & Deletes
+  - Modify or void transactions, contacts, or accounts.
+  - Note: Only available for organizations under Growth Plan.
+
+**Q4. How does the agent receive instructions?**
+
+- Send tasks via email to your agent's assigned email address.
+- Use the ‘To’ field for direct actions and replies.
+- Use ‘Cc’ to keep the agent informed but it will only respond to your verified email.
+
+**Q5. Can the AI Agent reply to emails with other recipients?**
+
+- No, it only responds to your verified email for security reasons.
+
+**Q6. What happens when I update my agent's email?**
+
+- Updating your agent’s email cancels all ongoing actions and the previous email will be unavailable for up to 72 hours.
+
+**Q7. What happens if I cancel or downgrade my organization plan?**
+
+- Your agent will be deactivated and its email will be released.
+
+**Q8. Why am I not receiving responses from my agent?**
+
+- Ensure you've included instructions in the ‘To**’** field and the email body.
+- Make sure the agent's email is in your email contacts.
+- Whitelist @sendjaz.com (@sendjaz.com), and check spam or other folders.
+
+**Q9. Why can’t I add new instructions to the AI Agent?**
+
+- Only organizations under the Growth Plan can add new instructions and turn off specific workflows.
+
+**Q10. Is it possible to whitelist external email addresses for my agent builder?**
+
+- Yes. You can whitelist specific email addresses or domains in your agent builder.
+- Whitelisting allows your agent to CC email addresses in replies, only when these addresses or domains were in your original email to the agent.
+
+---
+
+### Clio
+Source: https://help.jaz.ai/en/articles/10631206-clio
+
+**Q1. What is Clio?**
+
+- Clio stands for **Command Line Interface Operator**designed to help with accounting and finance tasks on Jaz.
+
+**Q2. Is Clio available to all users?**
+
+- No, Clio is available only for paid organizations.
+
+**Q3. Can I use Clio on the Jaz mobile app?**
+
+- Yes, Clio is available on Android (soon for IOS). Go to **Home > Clio AI Support** to access it.**Q4. How does Clio process queries?**
+
+- It processes all queries in real-time and does not retain personal or query-related data unless explicitly saved in accounting records or reports.
+
+**Q5. What happens when I log out or switch organizations?**
+
+- Clio is session-based, meaning it resets when you log out, close the tab, or switch organizations. Chat history is not retained.
+
+**Q6. Can Clio handle multiple tasks at once?**
+
+- Yes, Clio can process multiple tasks in a single query.
+
+**Q7. Are there any restrictions on Clio’s capabilities?**
+
+- Yes, Clio's functionality is limited to tasks and features within the Jaz ecosystem.
+​
+- Its functions are also limited to the user’s access permissions within an organization (e.g., a user without report access cannot generate reports).
+
+**Q8. Does Clio store my chat history?**
+
+- No, users cannot download or export chat history.
+
+**Q9. What happens when I edit a sent query?**
+
+- Editing a query replaces the previous one instead of updating it.
+
+**Q10. What file formats does Clio support?**
+
+- Clio supports all file formats that are compatible within Jaz. This includes:
+  - PDFs
+  - .xlsx
+  - JPG/JPEG
+  - PNG
+
+**Q11. What languages does Clio support?**
+
+- Both chat and voice queries support **all languages** available in Jaz.
+
+---