jaz-cli 2.3.0 → 2.6.0

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: api
-version: 2.3.0
+version: 2.6.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 — the entire journal can be in the org's base currency or any enabled foreign 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`.

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.3.0
+version: 2.6.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

@@ -1,7 +1,7 @@
 ---
 name: transaction-recipes
-version: 2.3.0
-description: Step-by-step recipes for modeling complex multi-step accounting scenarios in Jaz — prepaid amortization, deferred revenue, accrued expenses, bank loans, IFRS 16 leases, and declining balance depreciation. Each recipe shows the journal entries, capsule structure, and verification steps.
+version: 2.6.0
+description: 16 IFRS-compliant recipes for complex multi-step accounting in Jaz — prepaid amortization, deferred revenue, loan schedules, IFRS 16 leases, hire purchase, fixed deposits, asset disposal, FX revaluation, ECL provisioning, IAS 37 provisions, dividends, intercompany, and capital WIP. Each recipe includes journal entries, capsule structure, and verification steps. Paired with 10 financial calculators that produce execution-ready blueprints with workings.
 license: MIT
 compatibility: Works with Claude Code, Claude Cowork, Claude.ai, and any agent that reads markdown. For API payloads, load the jaz-api skill alongside this one.
 ---
@@ -17,7 +17,17 @@ You are modeling **complex multi-step accounting scenarios** in Jaz — transact
 - 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 (e.g., declining balance)
+- Recording hire purchase agreements (ownership transfers, depreciate over useful life)
+- Recording depreciation using methods Jaz doesn't natively support (declining balance, 150DB)
+- Managing fixed deposit placements with interest accrual schedules (IFRS 9)
+- Disposing of fixed assets — sale, scrap, or write-off with gain/loss calculation (IAS 16)
+- 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
@@ -27,12 +37,13 @@ Every recipe uses a combination of these Jaz features. See `references/building-
 | Building Block | Role in Recipes |
 |---|---|
 | **Capsules** | Group all related entries into one workflow container |
-| **Schedulers** | Automate fixed-amount recurring journals (prepaid, deferred) |
-| **Manual Journals** | Record variable-amount entries (loan interest, IFRS 16 unwinding, declining balance) |
-| **Fixed Assets** | Native straight-line depreciation for ROU assets |
+| **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) |
+| **Custom Fields** | Record reference numbers (policy, loan, lease contract, intercompany ref) |
 
 ## Key Principle: Schedulers vs Manual Journals
 
@@ -40,15 +51,27 @@ Jaz schedulers generate **fixed-amount** recurring entries. This determines whic
 
 - **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 (or manual for one-offs) | Accrual + reversal cycle with end dates |
+| 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 (native FA); liability unwinding changes each month |
+| 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 |
+| Fixed Deposit | Cash-out + manual journals + cash-in + capsule | Placement, monthly accruals, maturity |
+| Hire Purchase | Manual journals + FA registration + capsule | Like IFRS 16 but depreciate over useful life |
+| Asset Disposal | Manual journal + FA deregistration | One-off compound entry + FA update |
+| Provisions (IAS 37) | Manual journals + cash-out + 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
 
@@ -68,17 +91,138 @@ Each recipe includes: scenario description, accounts involved, journal entries,
 
 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)** — Double declining balance method with switch-to-straight-line logic, for assets where Jaz's native straight-line isn't appropriate.
+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.
+
+7. **[Fixed Deposit](references/fixed-deposit.md)** — Placement, monthly interest accrual (simple or compound), and maturity settlement. IFRS 9 amortized cost. *Paired calculator: `jaz calc fixed-deposit`*
+
+8. **[Hire Purchase](references/hire-purchase.md)** — Like IFRS 16 lease but ownership transfers — ROU depreciation over useful life (not lease term). *Paired calculator: `jaz calc lease --useful-life <months>`*
+
+9. **[Asset Disposal](references/asset-disposal.md)** — Sale at gain, sale at loss, or scrap/write-off. Computes accumulated depreciation to disposal date and gain/loss. *Paired calculator: `jaz calc asset-disposal`*
+
+### Tier 3 — Month-End Close Recipes
+
+10. **[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`*
+
+11. **[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`*
+
+12. **[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
+
+13. **[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`*
+
+14. **[Dividend Declaration & Payment](references/dividend.md)** — Board-declared dividend: two journals (declaration reducing retained earnings, then payment).
+
+15. **[Intercompany Transactions](references/intercompany.md)** — Mirrored invoices/bills or journals across two Jaz entities with matching intercompany reference, quarterly settlement.
+
+16. **[Capital WIP to Fixed Asset](references/capital-wip.md)** — Cost accumulation in CIP account during construction/development, transfer to FA on completion, auto-depreciation via Jaz FA module.
 
 ## 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. **Record the initial transaction** (bill, invoice, or journal) — assign it to the capsule.
-5. **For scheduler recipes**: Create the scheduler with the same capsule — it generates all subsequent entries automatically.
-6. **For manual journal recipes**: Record each period's journal manually using the calculations in the worked example, always assigning to the same capsule.
-7. **Verify** using the steps in each recipe (ledger grouping by capsule, trial balance checks).
+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 10 IFRS-compliant financial calculators. Each produces a formatted schedule + per-period journal entries + human-readable workings. Use `--json` for structured output with a complete **blueprint** — capsule type/name, tags, custom fields, workings (capsuleDescription), and every step with action type, date, accounts, and amounts.
+
+All calculators support `--currency <code>` and `--json`.
+
+```bash
+# ── Tier 2 Calculators ──────────────────────────────────────────
+
+# Loan amortization (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]
+
+# Hire purchase (lease + ownership transfer — depreciate over useful life)
+jaz calc lease --payment 5000 --term 36 --rate 5 --useful-life 60 [--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]
+
+# Fixed deposit — simple or compound interest accrual (IFRS 9)
+jaz calc fixed-deposit --principal 100000 --rate 3.5 --term 12 [--compound monthly|quarterly|annually] [--start-date 2025-01-01] [--currency SGD] [--json]
+
+# Asset disposal — gain/loss on sale or scrap (IAS 16)
+jaz calc asset-disposal --cost 50000 --salvage 5000 --life 5 --acquired 2022-01-01 --disposed 2025-06-15 --proceeds 20000 [--method sl|ddb|150db] [--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 for creating the capsule and posting all transactions in Jaz:
+
+```json
+{
+  "type": "loan",
+  "currency": "SGD",
+  "blueprint": {
+    "capsuleType": "Loan Repayment",
+    "capsuleName": "Bank Loan — SGD 100,000 — 6% — 60 months",
+    "capsuleDescription": "Loan Amortization Workings\nPrincipal: SGD 100,000.00 | Rate: 6% p.a. ...",
+    "tags": ["Bank Loan"],
+    "customFields": { "Loan Reference": null },
+    "steps": [
+      {
+        "step": 1,
+        "action": "cash-in",
+        "description": "Record loan proceeds received from bank",
+        "date": "2025-01-01",
+        "lines": [
+          { "account": "Cash / Bank Account", "debit": 100000, "credit": 0 },
+          { "account": "Loan Payable", "debit": 0, "credit": 100000 }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Blueprint action types** — each step tells you HOW to execute it in Jaz:
+
+| Action | When used | Jaz module |
+|---|---|---|
+| `bill` | Supplier document (prepaid expense) | Bills |
+| `invoice` | Customer document (deferred revenue) | Invoices |
+| `cash-in` | Cash arrives in bank (loan disbursement, FD maturity) | Bank / Manual Journal |
+| `cash-out` | Cash leaves bank (FD placement, provision settlement) | Bank / Manual Journal |
+| `journal` | No cash movement (accrual, depreciation, unwinding, reval) | Manual Journals |
+| `fixed-asset` | Register/update FA module (ROU asset, capital project) | Fixed Assets |
+| `note` | Instruction only (deregister FA on disposal) | N/A |
+
+**Math guarantees:**
+- `financial` npm package (TypeScript port of numpy-financial) for PV, PMT — no hand-rolled TVM
+- 2dp 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
+- All journal entries balanced (debits = credits in every step)
 
 ## Cross-References
 

package/assets/skills/transaction-recipes/references/asset-disposal.md

@@ -0,0 +1,174 @@
+# Recipe: Asset Disposal
+
+## Scenario
+
+Your company disposes of a fixed asset — either selling it, trading it in, or scrapping it. IAS 16.67-72 requires derecognition on disposal or when no future economic benefits are expected. The gain or loss is the difference between net disposal proceeds and the carrying amount (IAS 16.68), and gains are NOT classified as revenue (IAS 16.71) — they appear separately in the P&L under Other Income.
+
+**Pattern:** One-shot calculator (not a schedule) — computes accumulated depreciation to disposal date, net book value, and gain/loss, then produces a single disposal journal
+
+**Why manual:** Jaz's fixed asset register tracks depreciation automatically, but the disposal journal (removing cost + accumulated depreciation + recognizing gain/loss) must be recorded manually. After the journal, the asset is marked as sold or discarded in the FA register.
+
+---
+
+## Accounts Involved
+
+| Account | Type | Subtype | Role |
+|---|---|---|---|
+| Fixed Asset (at cost) | Asset | Non-Current Asset | Original cost being removed |
+| Accumulated Depreciation | Asset | Non-Current Asset (contra) | Contra-asset being cleared |
+| Gain on Disposal | Revenue | Other Income | If proceeds > NBV |
+| Loss on Disposal | Expense | Other Expense | If proceeds < NBV |
+| Cash / Bank Account | Asset | Bank | Receives sale proceeds |
+
+> **Note:** Gain on Disposal is NOT revenue — IAS 16.71 requires it to be classified separately. Use an "Other Income" account, not a sales revenue account.
+
+---
+
+## Journal Entries
+
+### Scenario A: Sale at a Gain (Proceeds > NBV)
+
+Proceeds $12,000, NBV $10,000 — Gain of $2,000:
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Cash / Bank Account | $12,000 | |
+| 2 | Accumulated Depreciation | $40,000 | |
+| 3 | Fixed Asset (at cost) | | $50,000 |
+| 4 | Gain on Disposal | | $2,000 |
+
+### Scenario B: Sale at a Loss (Proceeds < NBV)
+
+Proceeds $8,000, NBV $10,000 — Loss of $2,000:
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Cash / Bank Account | $8,000 | |
+| 2 | Accumulated Depreciation | $40,000 | |
+| 3 | Loss on Disposal | $2,000 | |
+| 4 | Fixed Asset (at cost) | | $50,000 |
+
+### Scenario C: Scrap / Write-Off (Zero Proceeds)
+
+No proceeds, NBV $10,000 — Loss of $10,000:
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Accumulated Depreciation | $40,000 | |
+| 2 | Loss on Disposal | $10,000 | |
+| 3 | Fixed Asset (at cost) | | $50,000 |
+
+**In all scenarios:** Debits = Credits = Original cost ($50,000).
+
+---
+
+## Capsule Structure
+
+**Capsule:** "Asset Disposal — Delivery Van VH-1234"
+**Capsule Type:** "Asset Disposal"
+
+Contents:
+- 1 disposal journal (removing cost, clearing accumulated depreciation, recognizing gain/loss)
+- **Total entries:** 1
+
+> **Note:** After recording the disposal journal, update the Jaz FA register to mark the asset as sold or discarded. This is a separate step — the register update does not create a journal entry but ensures the asset stops depreciating.
+
+---
+
+## Worked Example
+
+**Asset details:**
+- Asset: Delivery Van VH-1234
+- Original cost: $50,000
+- Salvage value: $5,000
+- Useful life: 5 years (60 months)
+- Depreciation method: Straight-line
+- Acquired: January 1, 2022
+- Disposed: June 15, 2025
+- Sale proceeds: $12,000
+
+**Step 1 — Calculate months held:**
+```
+Acquired:  Jan 1, 2022
+Disposed:  Jun 15, 2025
+Months held: 42 months (Jan 2022 through Jun 2025)
+```
+
+**Step 2 — Calculate monthly depreciation (straight-line):**
+```
+Depreciable base = Cost − Salvage = $50,000 − $5,000 = $45,000
+Monthly depreciation = $45,000 / 60 months = $750.00/month
+```
+
+**Step 3 — Calculate accumulated depreciation to disposal date:**
+```
+Accumulated depreciation = $750.00 × 42 months = $31,500.00
+```
+
+**Step 4 — Calculate net book value (NBV):**
+```
+NBV = Cost − Accumulated depreciation
+NBV = $50,000 − $31,500 = $18,500.00
+```
+
+**Step 5 — Calculate gain or loss:**
+```
+Gain/(Loss) = Proceeds − NBV
+Gain/(Loss) = $12,000 − $18,500 = −$6,500.00  (Loss)
+```
+
+**Disposal journal (Jun 15, 2025):**
+- Dr Cash $12,000.00
+- Dr Accumulated Depreciation $31,500.00
+- Dr Loss on Disposal $6,500.00
+- Cr Fixed Asset (at cost) $50,000.00
+- Description: "Disposal of Delivery Van VH-1234 — sold at loss"
+- Assign to capsule
+
+**Verification of debits = credits:**
+```
+Debits:  $12,000 + $31,500 + $6,500 = $50,000
+Credits: $50,000
+Balanced: Yes
+```
+
+**Use the calculator:** `jaz calc asset-disposal --cost 50000 --salvage 5000 --life 5 --acquired 2022-01-01 --disposed 2025-06-15 --proceeds 12000`
+
+The CLI generates a `capsuleDescription` with full workings (cost, accumulated depreciation, NBV, gain/loss breakdown) that can be attached to the capsule for audit trail.
+
+---
+
+## Enrichment Suggestions
+
+| Enrichment | Value | Why |
+|---|---|---|
+| Tracking Tag | "Asset Disposal" | Filter all disposal transactions in reports |
+| Nano Classifier | Disposal Type → "Sale" or "Scrap" | Distinguish sales from write-offs |
+| Custom Field | "Asset Description" → "Delivery Van VH-1234" | Identify the specific asset disposed |
+
+---
+
+## Verification
+
+1. **Fixed Asset account** → The original cost for this asset is fully removed (zeroed out).
+2. **Accumulated Depreciation account** → The accumulated depreciation for this asset is fully cleared (zeroed out).
+3. **P&L** → Gain or Loss on Disposal appears under "Other Income" or "Other Expense" (not revenue).
+4. **FA register** → Asset is marked as sold or discarded. No further depreciation is posted.
+
+---
+
+## Variations
+
+**DDB/150DB depreciation:** If the asset uses declining balance instead of straight-line, use `--method ddb` or `--method 150db` in the calculator. The accumulated depreciation will differ, changing the NBV and gain/loss.
+
+**Partial-year depreciation:** The calculator pro-rates automatically based on the acquisition and disposal dates. No manual adjustment needed for mid-month or mid-year disposals.
+
+**Fully depreciated asset:** If the asset is fully depreciated, NBV = salvage value. Gain = proceeds − salvage. If scrapped, loss = salvage value (the remaining book value written off).
+
+**Trade-in:** Record as a disposal (this recipe) plus a new asset acquisition in the same capsule. The trade-in allowance is the "proceeds" for the old asset. The new asset is recorded at its full cost, with the trade-in reducing the cash paid.
+
+**Insurance claim (involuntary disposal):** If the asset is destroyed (fire, theft, accident), the insurance payout is the "proceeds." Same journal structure — the only difference is the source of cash (insurer instead of buyer).
+
+**Jaz FA register update:** After recording the disposal journal, update the FA register:
+- Sold: `POST /mark-as-sold/fixed-assets` — marks the asset as sold with the disposal date
+- Scrapped: `POST /discard-fixed-assets/:id` — marks the asset as discarded