jaz-cli 2.2.1 → 2.5.0

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: api
-version: 2.2.1
+version: 2.5.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.
@@ -61,32 +61,33 @@ You are working with the **Jaz/Juan REST API** — the backend for Jaz (Singapor
 
 ### Journals & Cash
 23. **Journals use `journalEntries`** with `amount` + `type: "DEBIT"|"CREDIT"` — NOT `debit`/`credit` number fields.
-24. **Journals have NO `currency` field** at top level — sending it causes "Invalid request body".
-25. **Cash entries use `accountResourceId`** at top level for the BANK account + `journalEntries` array for offsets.
+24. **Journals support multi-currency via `currency` object** — same format as invoices/bills: `"currency": { "sourceCurrency": "USD" }` (auto-fetch platform rate) or `"currency": { "sourceCurrency": "USD", "exchangeRate": 1.35 }` (custom rate). Must be enabled for the org. Omit for base currency. Three restrictions apply to foreign currency journals: (a) **no controlled accounts** — accounts with `controlFlag` (AR, AP) are off-limits (use invoices/bills instead), (b) **no FX accounts** — FX Unrealized Gain/Loss/Rounding are system-managed, (c) **bank accounts must match** — can only post to bank accounts in the same currency as the journal (e.g., USD journal → USD bank account only, not SGD bank account). All other non-controlled accounts (expenses, revenue, assets, liabilities) are available.
+25. **`currency` object is the SAME everywhere** — invoices, bills, credit notes, AND journals all use `currency: { sourceCurrency: "USD", exchangeRate?: number }`. Never use `currencyCode: "USD"` (silently ignored on invoices/bills) or `currency: "USD"` (string — causes 400 on invoices/bills).
+26. **Cash entries use `accountResourceId`** at top level for the BANK account + `journalEntries` array for offsets.
 
 ### Credit Notes & Refunds
-26. **Credit note application wraps in `credits` array** with `amountApplied` — not flat.
-27. **CN refunds use `refunds` wrapper** with `refundAmount` + `refundMethod` — NOT `payments`/`paymentAmount`/`paymentMethod`.
+27. **Credit note application wraps in `credits` array** with `amountApplied` — not flat.
+28. **CN refunds use `refunds` wrapper** with `refundAmount` + `refundMethod` — NOT `payments`/`paymentAmount`/`paymentMethod`.
 
 ### Inventory Items
-28. **Inventory items require**: `unit` (e.g., `"pcs"`), `costingMethod` (`"FIXED"` or `"WAC"`), `cogsResourceId`, `blockInsufficientDeductions`, `inventoryAccountResourceId`. `purchaseAccountResourceId` MUST be Inventory-type CoA.
-29. **Delete inventory items via `DELETE /items/:id`** — not `/inventory-items/:id`.
+29. **Inventory items require**: `unit` (e.g., `"pcs"`), `costingMethod` (`"FIXED"` or `"WAC"`), `cogsResourceId`, `blockInsufficientDeductions`, `inventoryAccountResourceId`. `purchaseAccountResourceId` MUST be Inventory-type CoA.
+30. **Delete inventory items via `DELETE /items/:id`** — not `/inventory-items/:id`.
 
 ### Cash Transfers
-30. **Cash transfers use `cashOut`/`cashIn` sub-objects** — NOT flat `fromAccountResourceId`/`toAccountResourceId`. Each: `{ accountResourceId, amount }`.
+31. **Cash transfers use `cashOut`/`cashIn` sub-objects** — NOT flat `fromAccountResourceId`/`toAccountResourceId`. Each: `{ accountResourceId, amount }`.
 
 ### Schedulers
-31. **Scheduled invoices/bills wrap in `{ invoice: {...} }` or `{ bill: {...} }`** — not flat. Recurrence field is `repeat` (NOT `frequency`/`interval`). `saveAsDraft: false` required.
-32. **Scheduled journals use FLAT structure** with `schedulerEntries` — not nested in `journal` wrapper.
+32. **Scheduled invoices/bills wrap in `{ invoice: {...} }` or `{ bill: {...} }`** — not flat. Recurrence field is `repeat` (NOT `frequency`/`interval`). `saveAsDraft: false` required.
+33. **Scheduled journals use FLAT structure** with `schedulerEntries` — not nested in `journal` wrapper.
 
 ### Bookmarks
-33. **Bookmarks use `items` array wrapper** with `name`, `value`, `categoryCode`, `datatypeCode`.
+34. **Bookmarks use `items` array wrapper** with `name`, `value`, `categoryCode`, `datatypeCode`.
 
 ### Custom Fields
-34. **Do NOT send `appliesTo` on custom field POST** — causes "Invalid request body". Only send `name`, `type`, `printOnDocuments`.
+35. **Do NOT send `appliesTo` on custom field POST** — causes "Invalid request body". Only send `name`, `type`, `printOnDocuments`.
 
 ### Reports
-35. **Report field names differ by type** — this is the most error-prone area:
+36. **Report field names differ by type** — this is the most error-prone area:
 
 | Report | Required Fields |
 |--------|----------------|
@@ -101,32 +102,32 @@ You are working with the **Jaz/Juan REST API** — the backend for Jaz (Singapor
 | Bank balance summary | `primarySnapshotDate` |
 | Equity movement | `primarySnapshotStartDate`, `primarySnapshotEndDate` |
 
-36. **Data exports use simpler field names**: P&L export uses `startDate`/`endDate` (NOT `primarySnapshotDate`). AR/AP export uses `endDate`.
+37. **Data exports use simpler field names**: P&L export uses `startDate`/`endDate` (NOT `primarySnapshotDate`). AR/AP export uses `endDate`.
 
 ### Pagination
-37. **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, data: [...] }`.
 
 ### Other
-38. **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 48 for direction). Cannot set rates for org base currency. Full CRUD: POST (create), GET (list), GET/:id, PUT/:id, DELETE/:id.
-39. **FX invoices/bills MUST use `currency` object** — `currencyCode: "USD"` (string) is **silently ignored** (transaction created in base currency!). Use `currency: { sourceCurrency: "USD" }` to auto-fetch platform rate (ECB/FRANKFURTER), or `currency: { sourceCurrency: "USD", exchangeRate: 1.35 }` for a custom rate. Rate hierarchy: org rate → platform/ECB → transaction-level.
-40. **Invoice GET uses `organizationAccountResourceId`** for line item accounts — POST uses `accountResourceId`. Request-side aliases resolve `issueDate` → `valueDate`, `bankAccountResourceId` → `accountResourceId`, etc.
-41. **Scheduler GET returns `interval`** — POST uses `repeat`. (Response-side asymmetry remains.)
-42. **Search sort is an object** — `{ sort: { sortBy: ["valueDate"], order: "DESC" } }`. Required when `offset` is present (even `offset: 0`).
-43. **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. **Withholding tax** on bills/supplier CNs only. Retry pattern: if `WITHHOLDING_CODE_NOT_FOUND`, strip field and retry.
-45. **Known API bugs (500s)**: Contact groups PUT, custom fields PUT, capsules POST, catalogs POST, inventory balances GET — all return 500.
-46. **Non-existent endpoints**: `POST /deposits` and `POST /inventory/adjustments` return 404 — these endpoints are not implemented.
-47. **Attachments require PDF/PNG**: `POST /:type/:id/attachments` uses multipart `file` field but rejects `text/plain`. Use `application/pdf` or `image/png`.
-48. **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).
+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.
+40. **FX invoices/bills MUST use `currency` object** — `currencyCode: "USD"` (string) is **silently ignored** (transaction created in base currency!). Use `currency: { sourceCurrency: "USD" }` to auto-fetch platform rate (ECB/FRANKFURTER), or `currency: { sourceCurrency: "USD", exchangeRate: 1.35 }` for a custom rate. Rate hierarchy: org rate → platform/ECB → transaction-level.
+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, ...}] }`.
+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.
+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).
 
 ### Search & Filter
-49. **Search endpoint universal pattern** — All 28 `POST /*/search` endpoints share identical structure: `{ filter?, sort: { sortBy: ["field"], order: "ASC"|"DESC" }, limit: 1-1000, offset: 0-65536 }`. Sort is REQUIRED when offset is present (even `offset: 0`). Default limit: 100. `sortBy` is always an array on all endpoints (no exceptions). See `references/search-reference.md` for per-endpoint filter/sort fields.
-50. **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).
-51. **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)`.
-52. **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.
-53. **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. **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`.
-55. **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.
+50. **Search endpoint universal pattern** — All 28 `POST /*/search` endpoints share identical structure: `{ filter?, sort: { sortBy: ["field"], order: "ASC"|"DESC" }, limit: 1-1000, offset: 0-65536 }`. Sort is REQUIRED when offset is present (even `offset: 0`). Default limit: 100. `sortBy` is always an array on all endpoints (no exceptions). See `references/search-reference.md` for per-endpoint filter/sort fields.
+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`.
+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.
 
 ## Supporting Files
 
@@ -159,4 +160,4 @@ The backend DX overhaul is live. Key improvements now available:
 - **Bill payments**: Embed in bill creation body (safest). Standalone `POST /bills/{id}/payments` also works.
 - **Bank records**: Use multipart `POST /magic/importBankStatementFromAttachment`
 - **Scheduled bills**: Wrap as `{ status, startDate, endDate, repeat, bill: {...} }`
-- **FX currency**: `currency: { sourceCurrency: "USD" }` (auto-fetches platform rate) or `currency: { sourceCurrency: "USD", exchangeRate: 1.35 }` (custom rate). **Never use `currencyCode` string** — silently ignored.
+- **FX currency (invoices, bills, credit notes, AND journals)**: `currency: { sourceCurrency: "USD" }` (auto-fetches platform rate) or `currency: { sourceCurrency: "USD", exchangeRate: 1.35 }` (custom rate). Same object form on all transaction types. **Never use `currencyCode` string** — silently ignored.

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

@@ -601,17 +601,25 @@ if (acct.code) ctx.coaIds[acct.code] = acct.resourceId;
 
 ## Journal Errors
 
-### "Invalid request body" (400) — currency field
-**Cause**: Including `currency` at the top level of journal POST body.
-**Fix**: Do NOT include `currency` in journal requests. The correct journal body only needs `saveAsDraft`, `reference`, `valueDate`, and `journalEntries`.
-```json
-// WRONG:
-{ "saveAsDraft": false, "reference": "JV-001", "valueDate": "2026-02-08", "currency": "SGD", "journalEntries": [...] }
+### Multi-currency journals — `currency` object
+Journals support a top-level `currency` object to create entries in a foreign currency — **same format as invoices/bills**: `{ "sourceCurrency": "USD" }` (auto-fetch platform rate) or `{ "sourceCurrency": "USD", "exchangeRate": 1.35 }` (custom rate). The currency must be enabled for the org. Omit the field for base currency journals.
 
-// CORRECT:
+```json
+// Base currency journal (omit currency):
 { "saveAsDraft": false, "reference": "JV-001", "valueDate": "2026-02-08", "journalEntries": [...] }
+
+// Foreign currency journal (auto platform rate):
+{ "saveAsDraft": false, "reference": "JV-001", "valueDate": "2026-02-08", "currency": { "sourceCurrency": "USD" }, "journalEntries": [...] }
+
+// Foreign currency journal (custom rate):
+{ "saveAsDraft": false, "reference": "JV-001", "valueDate": "2026-02-08", "currency": { "sourceCurrency": "USD", "exchangeRate": 1.35 }, "journalEntries": [...] }
 ```
 
+**Three restrictions apply to foreign currency journals:**
+1. **No controlled accounts** — accounts with `controlFlag` (AR, AP) cannot be used. Use invoices/bills for AR/AP entries instead.
+2. **No FX accounts** — FX Unrealized Gain/Loss/Rounding accounts are system-managed and cannot be posted to directly.
+3. **Bank accounts must match currency** — a USD journal can only post to USD-denominated bank accounts, not SGD bank accounts. All other non-controlled accounts (expenses, revenue, assets, liabilities) are available regardless of journal currency.
+
 ### Journal entry field format
 **Cause**: Using `debit`/`credit` as separate number fields on journal entries.
 **Fix**: Each entry uses `amount` (number) + `type` (`"DEBIT"` or `"CREDIT"`, UPPERCASE strings).

package/assets/skills/api/references/feature-glossary.md

@@ -66,6 +66,8 @@ There is no dedicated `/deposits` endpoint (returns 404). Deposits are managed t
 
 Manual accounting entries for non-payment transactions. Three types: Manual Journals (multi-line debit/credit entries), Cash Journals (2-line cash transfers between bank accounts with cross-currency support), and Transfer Journals (year-end trial balance transfers, non-editable).
 
+Manual journals support multi-currency — set `currency: { sourceCurrency: "USD" }` (same object form as invoices/bills) to create a journal in a foreign currency. Omit for base currency. Foreign currency journal restrictions: (1) no controlled accounts (AR/AP — use invoices/bills instead), (2) no FX system accounts (Unrealized Gain/Loss/Rounding), (3) bank accounts must match the journal's currency (e.g., USD journal → USD bank only).
+
 Minimum 2 balanced entries required. Cash journals are restricted to exactly 2 lines. Bank/cash/current asset/equity/liability accounts cannot have tax profiles applied. Supports scheduled/recurring journals with dynamic scheduler strings (`{{YEAR}}`, `{{MONTH}}`).
 
 Cash transfer FX logic: if either side is base currency, keep as-is; if both non-base, fetch rate for cash-out and derive cash-in. Transfer rate = `Cash-in amount / Cash-out amount`.
@@ -78,7 +80,7 @@ Cash transfer FX logic: if either side is base currency, keep as-is; if both non
 
 Containers that group related transactions for complex accounting scenarios. Use cases: prepaid expenses (annual insurance amortization), deferred revenue, accrued expenses, fixed asset acquisitions (CIP), intercompany transactions, renovation projects.
 
-A capsule links invoices, bills, journals, and schedulers into a single logical unit. The ledger can be filtered and grouped by capsule. Capsule Types are customizable labels. A capsule must be empty before deletion. Clio (AI assistant) can auto-detect complex transactions and suggest capsule creation with linked schedulers.
+A capsule links invoices, bills, journals, and schedulers into a single logical unit. If a scheduler belongs to a capsule, every recurring entry it generates is automatically created under that same capsule — this is how prepaid expenses, deferred revenue, and accruals spread entries across periods while keeping them grouped. The ledger can be filtered and grouped by capsule (the only enrichment that supports group-by). Capsule Types are customizable labels. A capsule must be empty before deletion. Transactions can be bulk-attached via Quick Fix or moved between capsules.
 
 **API**: CRUD `GET/POST/PUT/DELETE /capsules`, `POST /capsules/search`, `POST /move-transaction-capsules`, CRUD `GET/POST/PUT/DELETE /capsuleTypes`, `POST /capsuleTypes/search` (also available as `/capsule-types/*` kebab-case aliases)
 
@@ -185,9 +187,19 @@ Fixed assets lock their linked line items — cannot edit account, amounts, or e
 
 **Currencies & FX Rates**: Enable currencies before use. Rate priority: transaction-level custom rate > org-level custom rate > ECB/Frankfurter auto-fetch. Rate direction: `rate` = functionalToSource (1 base = X foreign).
 
-**Tracking Tags**: Custom labels for reporting. Apply to line items or transaction headers. Filter reports by tags but cannot group by them (except capsules in ledger).
+**Transaction Data Enrichments** — four optional metadata layers at different granularities:
+
+| Layer | Scope | Purpose | Reporting | PDF | Scheduler |
+|-------|-------|---------|-----------|-----|-----------|
+| **Tracking Tags** | Transaction only | Hashtags for advanced reporting | Filter | No | Inherited |
+| **Nano Classifiers** | Line item only | Classification intent (department, cost center) | Filter | Yes (line items) | Inherited |
+| **Capsules** | Group of transactions | Workflow container for multi-step accounting | Filter + Group by | No | All entries land in capsule |
+| **Custom Fields** | Transaction | Additional record-keeping | No impact | Yes | No |
 
-**Custom Fields**: Text/number/date/dropdown fields. Apply to invoices/bills/journals/contacts. Can show on PDFs and be made mandatory.
+- **Tracking Tags**: Like hashtags on transactions — data enrichment for advanced reporting. Transaction-level only (not line items). Can be set on schedulers — generated entries inherit them. Cannot group by tags in reports, only filter.
+- **Nano Classifiers**: Data enrichment with a classification intent — group line items into named classes within a classifier (e.g., Department: Engineering/Sales/Finance). Line-item-level only (not transaction headers). Can be displayed on PDF line items. Can be set on schedulers — generated entries inherit them. Assigning classifiers to items auto-applies them to line items in transactions.
+- **Capsules**: Not a classification — a workflow container that groups related transactions for a specific accounting scenario (prepaid, deferred, accrual, CIP). The only enrichment supporting group-by in reports. See dedicated Capsules section above.
+- **Custom Fields**: Text/number/date/dropdown fields for additional record-keeping. Transaction-level, applied to invoices/bills/journals/contacts. Can show on PDFs and be made mandatory. No reporting impact, not available on schedulers.
 
 **Lock Dates**: Prevent edits to transactions before a date (org-wide or per-account). Prevents backdated entries.
 

package/assets/skills/api/references/field-map.md

@@ -195,7 +195,7 @@ When POSTing, `classificationType` must be one of these exact strings (same as `
 | `lines` | `journalEntries` | Same |
 | `entries` | `journalEntries` | Same |
 | `debit` / `credit` (entry) | `amount` + `type` | `amount`: number, `type`: `"DEBIT"` or `"CREDIT"` (UPPERCASE) |
-| `currency` (top level) | DO NOT SEND | Causes "Invalid request body" |
+| `currency: "USD"` (string) | `currency: { sourceCurrency: "USD" }` | **Object form** — same as invoices/bills. Auto-fetches platform rate. Add `exchangeRate: 1.35` for custom rate. Omit for base currency. |
 
 ---
 
@@ -421,8 +421,8 @@ Battle-tested patterns from production Jaz API clients:
 | Bill payments | Always embedded in bill creation body, never standalone |
 | Bank records | Multipart import via `importBankStatementFromAttachment` — the only endpoint |
 | Scheduled bills | Wrapped as `{ repeat, startDate, endDate, bill: {...} }`. Field is `repeat` (NOT `frequency`/`interval`) |
-| FX currency | MUST use `currency` OBJECT: `{ sourceCurrency: "USD", exchangeRate: 1.35 }`. String `currencyCode` is silently ignored. |
+| FX currency | MUST use `currency` OBJECT on ALL transaction types (invoices, bills, credit notes, journals): `{ sourceCurrency: "USD" }` (auto platform rate) or `{ sourceCurrency: "USD", exchangeRate: 1.35 }` (custom). String `currencyCode` silently ignored. |
 
 ---
 
-*Last updated: 2026-02-14 — Date format matrix: Added request vs response date format asymmetry (YYYY-MM-DD in, epoch ms out). Complete middleware alias table from Go source code. DateExpression vs DateTimeExpression field classification.*
+*Last updated: 2026-02-18 — Multi-currency journals: `currency` object now documented (same `{ sourceCurrency, exchangeRate? }` form as invoices/bills). Date format matrix: request vs response asymmetry (YYYY-MM-DD in, epoch ms out). Complete middleware alias table from Go source code.*

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: conversion
-version: 2.2.1
+version: 2.5.0
 description: Accounting data conversion skill — migrates customer data from Xero, QuickBooks, Sage, MYOB, and Excel exports to Jaz. Covers config, quick, and full conversion workflows, Excel parsing, CoA/contact/tax/items mapping, clearing accounts, TTB, and TB verification.
 ---
 

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

@@ -0,0 +1,199 @@
+---
+name: transaction-recipes
+version: 2.5.0
+description: 13 IFRS-compliant recipes for modeling complex multi-step accounting scenarios in Jaz — from prepaid amortization and loan schedules to FX revaluation, ECL provisioning, dividend declarations, and intercompany transactions. Each recipe includes journal entries, capsule structure, and verification steps. Paired with 8 financial calculators that produce execution-ready blueprints.
+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.
+---
+
+# Transaction Recipes Skill
+
+You are modeling **complex multi-step accounting scenarios** in Jaz — transactions that span multiple periods, involve changing amounts, or require several linked entries to complete a single business event.
+
+**This skill provides conceptual recipes with full accounting logic. For API field names and payloads, load the `jaz-api` skill alongside this one.**
+
+## When to Use This Skill
+
+- Setting up prepaid expenses, deferred revenue, or accrued liabilities
+- Modeling loan repayment schedules with amortization tables
+- Implementing IFRS 16 lease accounting (right-of-use assets + lease liabilities)
+- Recording depreciation using methods Jaz doesn't natively support (declining balance, 150DB)
+- FX revaluation of non-AR/AP monetary items at period-end (IAS 21)
+- Calculating expected credit loss provisions on aged receivables (IFRS 9)
+- Accruing employee leave and bonus obligations (IAS 19)
+- Recognizing provisions at PV with discount unwinding (IAS 37)
+- Declaring and paying dividends
+- Recording and reconciling intercompany transactions across entities
+- Capitalizing costs in WIP and transferring to fixed assets
+- Any scenario that groups related transactions in a capsule over multiple periods
+
+## Building Blocks
+
+Every recipe uses a combination of these Jaz features. See `references/building-blocks.md` for details.
+
+| Building Block | Role in Recipes |
+|---|---|
+| **Capsules** | Group all related entries into one workflow container |
+| **Schedulers** | Automate fixed-amount recurring journals (prepaid, deferred, leave) |
+| **Manual Journals** | Record variable-amount entries (loan interest, IFRS 16 unwinding, FX reval, ECL) |
+| **Fixed Assets** | Native straight-line depreciation for ROU assets and completed capital projects |
+| **Invoices / Bills** | Trade documents for intercompany, supplier bills for capital WIP |
+| **Tracking Tags** | Tag all entries in a scenario for report filtering |
+| **Nano Classifiers** | Classify line items by department, cost center, or project |
+| **Custom Fields** | Record reference numbers (policy, loan, lease contract, intercompany ref) |
+
+## Key Principle: Schedulers vs Manual Journals
+
+Jaz schedulers generate **fixed-amount** recurring entries. This determines which recipe pattern to use:
+
+- **Fixed amounts each period** → Use a scheduler inside a capsule (automated)
+- **Variable amounts each period** → Use manual journals inside a capsule (calculated per period)
+- **One-off or two-entry events** → Use manual journals (e.g., dividend declaration + payment)
+
+| Recipe | Pattern | Why |
+|---|---|---|
+| Prepaid Amortization | Scheduler + capsule | Same amount each month |
+| Deferred Revenue | Scheduler + capsule | Same amount each month |
+| Accrued Expenses | Two schedulers + capsule | Accrual + reversal cycle with end dates |
+| Employee Leave Accrual | Scheduler + capsule | Fixed monthly accrual |
+| Bank Loan | Manual journals + capsule | Interest changes as principal reduces |
+| IFRS 16 Lease | Hybrid (native FA + manual journals) + capsule | ROU depreciation is fixed; liability unwinding changes |
+| Declining Balance | Manual journals + capsule | Depreciation changes as book value reduces |
+| FX Revaluation | Manual journals + capsule | Rates change each period |
+| ECL Provision | Manual journals + capsule | Receivables and rates change each quarter |
+| Provisions (IAS 37) | Manual journals + capsule | Unwinding amount changes each month |
+| Bonus Accrual | Manual journals + capsule | Revenue/profit changes each quarter |
+| Dividends | Manual journals + capsule | One-off: declaration + payment |
+| Intercompany | Invoices/bills + capsule | Mirrored entries in two entities |
+| Capital WIP | Bills/journals + FA registration + capsule | Accumulate then transfer |
+
+## Recipe Index
+
+Each recipe includes: scenario description, accounts involved, journal entries, capsule structure, worked example with real numbers, enrichment suggestions, verification steps, and common variations.
+
+### Tier 1 — Scheduler Recipes (Automated)
+
+1. **[Prepaid Amortization](references/prepaid-amortization.md)** — Annual insurance, rent, or subscription paid upfront with monthly expense recognition via scheduler.
+
+2. **[Deferred Revenue](references/deferred-revenue.md)** — Upfront customer payment for a service delivered over time, with monthly revenue recognition via scheduler.
+
+### Tier 2 — Manual Journal Recipes (Calculated)
+
+3. **[Accrued Expenses](references/accrued-expenses.md)** — Month-end expense accrual and start-of-month reversal using two schedulers with end dates, plus the actual supplier bill.
+
+4. **[Bank Loan](references/bank-loan.md)** — Loan disbursement, monthly installments splitting principal and interest, full amortization table with worked example.
+
+5. **[IFRS 16 Lease](references/ifrs16-lease.md)** — Right-of-use asset recognition, lease liability unwinding with changing interest, native FA for ROU straight-line depreciation.
+
+6. **[Declining Balance Depreciation](references/declining-balance.md)** — DDB/150DB methods with switch-to-straight-line logic, for assets where Jaz's native SL isn't appropriate.
+
+### Tier 3 — Month-End Close Recipes
+
+7. **[FX Revaluation — Non-AR/AP Items](references/fx-revaluation.md)** — IAS 21 revaluation of non-AR/AP foreign currency monetary items (intercompany loans, term deposits, FX provisions) with Day 1 reversal. *Paired calculator: `jaz calc fx-reval`*
+
+8. **[Bad Debt Provision / ECL](references/bad-debt-provision.md)** — IFRS 9 simplified approach provision matrix using aged receivables and historical loss rates. *Paired calculator: `jaz calc ecl`*
+
+9. **[Employee Benefit Accruals](references/employee-accruals.md)** — IAS 19 leave accrual (scheduler, fixed monthly) and bonus accrual (manual journals, variable quarterly) with year-end true-up.
+
+### Tier 4 — Corporate Events & Structures
+
+10. **[Provisions with PV Unwinding](references/provisions.md)** — IAS 37 provision recognized at PV, with monthly discount unwinding schedule. For warranties, legal claims, decommissioning, restructuring. *Paired calculator: `jaz calc provision`*
+
+11. **[Dividend Declaration & Payment](references/dividend.md)** — Board-declared dividend: two journals (declaration reducing retained earnings, then payment).
+
+12. **[Intercompany Transactions](references/intercompany.md)** — Mirrored invoices/bills or journals across two Jaz entities with matching intercompany reference, quarterly settlement.
+
+13. **[Capital WIP to Fixed Asset](references/capital-wip.md)** — Cost accumulation in CIP account during construction/development, transfer to FA on completion, auto-depreciation via Jaz FA module.
+
+## How to Use These Recipes
+
+1. **Read the recipe** for your scenario — understand the accounts, journal entries, and capsule structure.
+2. **Create the accounts** listed in the "Accounts Involved" table (if they don't already exist in the CoA).
+3. **Create the capsule** with an appropriate capsule type.
+4. **Run the calculator** (if available) to generate exact amounts: `jaz calc <command> --json` gives you a complete blueprint.
+5. **Record the initial transaction** (bill, invoice, or journal) — assign it to the capsule.
+6. **For scheduler recipes**: Create the scheduler with the same capsule — it generates all subsequent entries automatically.
+7. **For manual journal recipes**: Record each period's journal using the calculator output or worked example, always assigning to the same capsule.
+8. **Verify** using the steps in each recipe (ledger grouping by capsule, trial balance checks).
+
+## Financial Calculators (CLI)
+
+The `jaz-cli` includes 8 IFRS-compliant financial calculators. Each produces a formatted schedule table with per-period journal entries. Use `--json` for structured output with a complete **blueprint** — an execution plan containing capsule type, name, tags, custom fields, and every journal entry with dates, accounts, and amounts.
+
+All calculators support `--currency <code>` for currency labeling and `--json` for agent-parseable output.
+
+```bash
+# ── Tier 2 Calculators ──────────────────────────────────────────
+
+# Loan amortization schedule (PMT, interest/principal split)
+jaz calc loan --principal 100000 --rate 6 --term 60 [--start-date 2025-01-01] [--currency SGD] [--json]
+
+# IFRS 16 lease (PV, liability unwinding, ROU depreciation)
+jaz calc lease --payment 5000 --term 36 --rate 5 [--start-date 2025-01-01] [--currency SGD] [--json]
+
+# Depreciation (DDB, 150DB, or straight-line)
+jaz calc depreciation --cost 50000 --salvage 5000 --life 5 [--method ddb|150db|sl] [--frequency annual|monthly] [--currency SGD] [--json]
+
+# Prepaid expense recognition
+jaz calc prepaid-expense --amount 12000 --periods 12 [--frequency monthly|quarterly] [--start-date 2025-01-01] [--currency SGD] [--json]
+
+# Deferred revenue recognition
+jaz calc deferred-revenue --amount 36000 --periods 12 [--frequency monthly|quarterly] [--start-date 2025-01-01] [--currency SGD] [--json]
+
+# ── Tier 3 Calculators ──────────────────────────────────────────
+
+# FX revaluation — unrealized gain/loss on non-AR/AP items (IAS 21)
+jaz calc fx-reval --amount 50000 --book-rate 1.35 --closing-rate 1.38 [--currency USD] [--base-currency SGD] [--json]
+
+# Expected credit loss provision matrix (IFRS 9)
+jaz calc ecl --current 100000 --30d 50000 --60d 20000 --90d 10000 --120d 5000 --rates 0.5,2,5,10,50 [--existing-provision 3000] [--currency SGD] [--json]
+
+# ── Tier 4 Calculator ───────────────────────────────────────────
+
+# IAS 37 provision PV + discount unwinding schedule
+jaz calc provision --amount 500000 --rate 4 --term 60 [--start-date 2025-01-01] [--currency SGD] [--json]
+```
+
+### Blueprint Output (`--json`)
+
+Every calculator's `--json` output includes a `blueprint` object — a complete execution plan that an AI agent or human can follow to create the capsule and post all transactions in Jaz:
+
+```json
+{
+  "type": "loan",
+  "currency": "SGD",
+  "blueprint": {
+    "capsuleType": "Loan Repayment",
+    "capsuleName": "Bank Loan — SGD 100,000 — 6% — 60 months",
+    "tags": ["Bank Loan"],
+    "customFields": { "Loan Reference": null },
+    "steps": [
+      {
+        "step": 1,
+        "action": "journal",
+        "description": "Loan disbursement",
+        "date": "2025-01-01",
+        "lines": [
+          { "account": "Cash / Bank Account", "debit": 100000, "credit": 0 },
+          { "account": "Loan Payable", "debit": 0, "credit": 100000 }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Math guarantees:**
+- Uses `financial` npm package (TypeScript port of numpy-financial) for PV, PMT — no hand-rolled TVM
+- 2 decimal places per period, final period closes balance to exactly $0.00
+- Input validation with clear error messages (negative values, invalid dates, salvage > cost)
+- DDB→SL switch when straight-line >= declining balance or when DDB would breach salvage floor
+- Journal entries balanced (sum of debits = sum of credits in every step)
+
+## Cross-References
+
+- **API field names and payloads**: Load the `jaz-api` skill — see `references/endpoints.md` and `references/field-map.md`
+- **Capsule API**: `POST /capsules`, `POST /capsuleTypes` — see api skill's `references/full-api-surface.md`
+- **Scheduler API**: `POST /scheduled/journals`, `POST /scheduled/invoices`, `POST /scheduled/bills`
+- **Fixed Assets API**: `POST /fixed-assets` — see api skill's `references/feature-glossary.md`
+- **Enrichments overview**: See `references/building-blocks.md` or api skill's `references/feature-glossary.md`

package/assets/skills/transaction-recipes/references/accrued-expenses.md

@@ -0,0 +1,157 @@
+# Recipe: Accrued Expenses
+
+## Scenario
+
+Your company receives electricity each month but the supplier invoices quarterly. At the end of January, you estimate $3,000 of electricity expense that hasn't been billed yet. You accrue it, reverse it next month, and record the actual bill when it arrives.
+
+**Pattern:** Two schedulers + capsule (accrual scheduler + reversal scheduler with end dates), or manual journals for one-off accruals
+
+---
+
+## Accounts Involved
+
+| Account | Type | Subtype | Role |
+|---|---|---|---|
+| Accrued Expenses | Liability | Current Liability | Holds the accrued liability |
+| Utilities Expense | Expense | Expense | Receives the expense charge |
+| Accounts Payable | Liability | Current Liability | When the actual bill arrives |
+| Cash / Bank Account | Asset | Bank | Pays the bill |
+
+---
+
+## How Reversals Work in Jaz
+
+Jaz does not have a native "reversal" concept. To automate the accrual-reversal cycle, use **two journal schedulers** — one for the accrual, one for the reversal — each with an end date. The end date stops the schedulers when the actual bill is expected.
+
+---
+
+## Journal Entries
+
+### Step 1: Accrual Scheduler (runs at month-end)
+
+Create a journal scheduler for the monthly accrual:
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Utilities Expense | $3,000 | |
+| 2 | Accrued Expenses | | $3,000 |
+
+**Scheduler settings:**
+- Frequency: Monthly
+- Start date: 2025-01-31 (last day of first accrual month)
+- **End date: 2025-03-31** — stops when you expect the bill to arrive
+- Capsule: "Q1 2025 Electricity — PowerCo"
+- Description: `Electricity accrual — {{MONTH_NAME}} {{YEAR}}`
+
+### Step 2: Reversal Scheduler (runs at start of next month)
+
+Create a second journal scheduler for the reversal (opposite entries):
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Accrued Expenses | $3,000 | |
+| 2 | Utilities Expense | | $3,000 |
+
+**Scheduler settings:**
+- Frequency: Monthly
+- Start date: 2025-02-01 (first day after first accrual)
+- **End date: 2025-04-01** — one month after the accrual scheduler's end date
+- Capsule: same capsule — "Q1 2025 Electricity — PowerCo"
+- Description: `Reversal of electricity accrual — {{MONTH_NAME}} {{YEAR}}`
+
+This clears each month's accrual so the actual bill can be recorded cleanly.
+
+### Step 3: Actual Bill (when received — e.g., Mar 15)
+
+Create a bill to the electricity supplier for the actual amount (which may differ from the estimate):
+
+- Bill: Dr Utilities Expense $9,200 / Cr AP $9,200
+- Assign to the same capsule
+
+The net effect per month:
+- Each month's P&L shows the estimated expense (accrual)
+- Each reversal clears the accrual at the start of the next month
+- The bill captures the full actual amount when it arrives
+
+---
+
+## Capsule Structure
+
+**Capsule:** "Q1 2025 Electricity — PowerCo"
+**Capsule Type:** "Accrued Expenses"
+
+Contents:
+- 3 accrual journals — generated by the accrual scheduler (one per month-end)
+- 3 reversal journals — generated by the reversal scheduler (one at start of next month)
+- 1 supplier bill (when received)
+- **Total entries:** 7
+
+---
+
+## Worked Example
+
+**Setup:**
+- Create capsule "Q1 2025 Electricity — PowerCo" with type "Accrued Expenses"
+- Create accrual scheduler (Dr Utilities $3,000 / Cr Accrued $3,000) — monthly, end date Mar 31, assign to capsule
+- Create reversal scheduler (Dr Accrued $3,000 / Cr Utilities $3,000) — monthly, end date Apr 1, assign to capsule
+
+**Jan 31, 2025 — auto-generated by accrual scheduler:**
+- Dr Utilities Expense $3,000 / Cr Accrued Expenses $3,000
+- P&L: Utilities Expense $3,000
+
+**Feb 1, 2025 — auto-generated by reversal scheduler:**
+- Dr Accrued Expenses $3,000 / Cr Utilities Expense $3,000
+- Accrued balance cleared to $0
+
+**Feb 28, 2025 — auto-generated by accrual scheduler:**
+- Dr Utilities Expense $3,000 / Cr Accrued Expenses $3,000
+
+**Mar 1, 2025 — auto-generated by reversal scheduler:**
+- Dr Accrued Expenses $3,000 / Cr Utilities Expense $3,000
+
+**Mar 15, 2025 — Actual bill received:**
+- Create bill: $9,200 to PowerCo, coded to Utilities Expense
+- Assign to same capsule
+- Pay bill when due
+
+**Mar 31, 2025 — auto-generated by accrual scheduler (final):**
+- Dr Utilities Expense $3,000 / Cr Accrued Expenses $3,000
+
+**Apr 1, 2025 — auto-generated by reversal scheduler (final):**
+- Dr Accrued Expenses $3,000 / Cr Utilities Expense $3,000
+
+**P&L impact per month:**
+- January: $3,000 (accrual, not yet reversed)
+- February: −$3,000 (reversal) + $3,000 (new accrual) = net $0 change
+- March: −$3,000 (reversal) + $9,200 (bill) + $3,000 (accrual) = net $9,200
+
+---
+
+## Enrichment Suggestions
+
+| Enrichment | Value | Why |
+|---|---|---|
+| Tracking Tag | "Utilities" | Filter all utility-related transactions |
+| Nano Classifier | Department → "Operations" | Attribute to responsible department |
+| Custom Field | "Supplier Account #" → "PWR-88201" | Record the utility account number |
+
+---
+
+## Verification
+
+1. **Group General Ledger by Capsule** → "Q1 2025 Electricity — PowerCo" shows all 7 entries. Accrued Expenses should net to zero after all reversals.
+2. **Trial Balance at Jan 31** → Accrued Expenses shows $3,000 credit (liability exists). Utilities Expense shows $3,000.
+3. **Trial Balance at Mar 31 (after bill)** → Accrued Expenses shows $3,100 credit (March accrual not yet reversed). Utilities Expense reflects year-to-date charges.
+4. **Trial Balance at Apr 1 (after reversal)** → Accrued Expenses shows $0 (all cleared).
+
+---
+
+## Variations
+
+**One-off accrual (no scheduler):** For a single accrual-reversal pair (e.g., a year-end audit adjustment), create two manual journals instead of schedulers — one accrual journal at Dec 31 and one reversal journal at Jan 1. Both go in the same capsule.
+
+**Variable estimate amounts:** If the monthly estimate changes (e.g., $3,000 in Jan, $3,100 in Feb), schedulers won't work since they produce fixed amounts. Use manual journals for each accrual and reversal instead, all in the same capsule.
+
+**No reversal method:** Some companies accrue at month-end and only reverse when the actual bill arrives (instead of reversing at the start of each month). This is simpler but less granular in monthly P&L. Use one accrual scheduler with an end date, and a single manual reversal journal when the bill comes.
+
+**Known amount, unknown timing:** If you know the quarterly bill is always ~$9,000 but don't know the exact date, set the scheduler end dates to your best estimate. Adjust by deleting or adding manual journals in the capsule if timing shifts.