jaz-cli 2.3.0 → 2.5.0

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: api
-version: 2.3.0
+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`.

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.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

@@ -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.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.
 ---
@@ -17,7 +17,14 @@ 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 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
@@ -27,12 +34,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 +48,24 @@ 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 |
+| 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
 
@@ -68,17 +85,110 @@ 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.
+
+### 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. **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 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
 

package/assets/skills/transaction-recipes/references/bad-debt-provision.md

@@ -0,0 +1,145 @@
+# Recipe: Bad Debt Provision / Expected Credit Loss (IFRS 9)
+
+## Scenario
+
+Your company has $185,000 in trade receivables across five aging buckets. IFRS 9.5.5.15 requires you to recognize lifetime expected credit losses using the simplified approach (provision matrix). You apply historical loss rates to each aging bucket, calculate the total required allowance, compare it to the existing provision balance, and post a journal for the difference.
+
+**Pattern:** Manual journal + capsule (provision amount recalculated each quarter)
+
+---
+
+## Accounts Involved
+
+| Account | Type | Subtype | Role |
+|---|---|---|---|
+| Bad Debt Expense | Expense | Expense | Period charge for provision increase |
+| Allowance for Doubtful Debts | Asset | Current Asset (contra) | Contra-asset reducing receivables on balance sheet |
+| Accounts Receivable | Asset | Current Asset | Trade receivables (affected on write-off only) |
+
+> **Note on write-offs:** When a specific debt is confirmed uncollectible, the write-off journal is: Dr Allowance for Doubtful Debts / Cr Accounts Receivable. Use the `DEBT_WRITE_OFF` payment method in Jaz to record this against the specific invoice.
+
+---
+
+## Journal Entries
+
+### Step 1: Calculate Provision Matrix
+
+Run the aged receivables report and apply loss rates:
+
+| Aging Bucket | Balance | Loss Rate | ECL |
+|---|---|---|---|
+| Current (not overdue) | | *%* | |
+| 1-30 days overdue | | *%* | |
+| 31-60 days overdue | | *%* | |
+| 61-90 days overdue | | *%* | |
+| 91+ days overdue | | *%* | |
+| **Total** | | | **Total ECL** |
+
+### Step 2: Provision Adjustment
+
+```
+Adjustment = Total ECL − Existing Provision Balance
+```
+
+**If increase (ECL > existing provision):**
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Bad Debt Expense | *adjustment* | |
+| 2 | Allowance for Doubtful Debts | | *adjustment* |
+
+**If release (ECL < existing provision):**
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Allowance for Doubtful Debts | *adjustment* | |
+| 2 | Bad Debt Expense | | *adjustment* |
+
+### Step 3: Write-Off (when confirmed uncollectible)
+
+Use the `DEBT_WRITE_OFF` payment method against the specific invoice:
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Allowance for Doubtful Debts | *write-off amount* | |
+| 2 | Accounts Receivable | | *write-off amount* |
+
+---
+
+## Capsule Structure
+
+**Capsule:** "ECL Provision — Q4 2025"
+**Capsule Type:** "ECL Provision"
+
+Contents:
+- 1 provision adjustment journal per quarter
+- Write-off entries as they occur
+- **Total entries:** Varies (typically 1 per quarter + write-offs)
+
+---
+
+## Worked Example
+
+**Setup:**
+- Reporting date: December 31, 2025
+- Existing provision balance: $3,000
+
+**Aged receivables and loss rates:**
+
+| Aging Bucket | Balance | Loss Rate | ECL |
+|---|---|---|---|
+| Current | $100,000 | 0.5% | $500 |
+| 1-30 days | $50,000 | 2% | $1,000 |
+| 31-60 days | $20,000 | 5% | $1,000 |
+| 61-90 days | $10,000 | 10% | $1,000 |
+| 91+ days | $5,000 | 50% | $2,500 |
+| **Total** | **$185,000** | **3.24%** | **$6,000** |
+
+**Adjustment:**
+```
+Required provision: $6,000
+Existing provision: $3,000
+Increase needed:    $3,000
+```
+
+**Dec 31, 2025 — Provision journal:**
+- Dr Bad Debt Expense $3,000
+- Cr Allowance for Doubtful Debts $3,000
+- Description: "ECL provision increase — Q4 2025"
+- Assign to capsule
+
+**Use the calculator:** `jaz calc ecl --current 100000 --30d 50000 --60d 20000 --90d 10000 --120d 5000 --rates 0.5,2,5,10,50 --existing-provision 3000`
+
+---
+
+## Enrichment Suggestions
+
+| Enrichment | Value | Why |
+|---|---|---|
+| Tracking Tag | "ECL" | Filter all provision-related entries |
+| Tracking Tag | "Bad Debt" | Broader filter including write-offs |
+| Custom Field | "Reporting Period" → "Q4 2025" | Link to specific reporting quarter |
+| Custom Field | "Aged Receivables Report Date" → "2025-12-31" | Audit trail to source report |
+
+---
+
+## Verification
+
+1. **Trial Balance** → Allowance for Doubtful Debts should equal the Total ECL amount ($6,000) after the adjustment.
+2. **P&L for the quarter** → Bad Debt Expense shows only the delta ($3,000), not the full provision.
+3. **Balance Sheet** → Accounts Receivable minus Allowance for Doubtful Debts = net realizable value ($185,000 − $6,000 = $179,000).
+4. **Group General Ledger by Capsule** → Shows all provision adjustments and write-offs for the period.
+
+---
+
+## Variations
+
+**First-time adoption:** If no existing provision, the full ECL amount is the initial charge. No "adjustment" calculation needed — just post the total.
+
+**Quarterly vs. annual:** IFRS 9 requires assessment at each reporting date. Listed companies do quarterly; SMEs typically do semi-annually or annually. Adjust frequency to match your reporting calendar.
+
+**Specific provision overlay:** In addition to the matrix (general provision), you may identify specific receivables that require a higher provision (e.g., a customer in bankruptcy). Add the specific overlay amount to the matrix total.
+
+**Recovery of written-off debt:** If a previously written-off customer pays, record: Dr Cash / Cr Bad Debt Expense (or Cr Allowance). This can be handled as a regular receipt against the original invoice using the "Payment" method in Jaz.
+
+**Loss rate calibration:** Loss rates should be based on historical data (typically 3-5 years of actual write-offs by aging bucket). Forward-looking adjustments may be needed for macroeconomic conditions (IFRS 9.5.5.17).

package/assets/skills/transaction-recipes/references/building-blocks.md

@@ -21,6 +21,13 @@ Capsules group related transactions into a single logical unit for a specific ac
 - Loan Repayment
 - Lease Accounting (IFRS 16)
 - Depreciation (Non-Standard)
+- FX Revaluation
+- ECL Provision
+- Employee Benefits
+- Provisions
+- Dividends
+- Intercompany
+- Capital Projects
 
 **Reporting:** Capsules are the **only enrichment that supports group-by** in the General Ledger. Grouping by capsule shows the complete lifecycle of a multi-step transaction in one view.
 
@@ -106,7 +113,23 @@ Each recipe lists the specific CoA accounts needed. Common patterns:
 | Right-of-Use Asset | Asset | Non-Current Asset | IFRS 16 |
 | Lease Liability | Liability | Non-Current Liability | IFRS 16 |
 | Lease Liability (Current) | Liability | Current Liability | IFRS 16 |
-| Accumulated Depreciation | Asset | Non-Current Asset | Declining balance |
-| Depreciation Expense | Expense | Expense | Declining balance |
+| Accumulated Depreciation | Asset | Non-Current Asset | Declining balance, Capital WIP |
+| Depreciation Expense | Expense | Expense | Declining balance, Capital WIP |
+| FX Unrealized Gain | Revenue | Other Income | FX revaluation |
+| FX Unrealized Loss | Expense | Other Expense | FX revaluation |
+| Bad Debt Expense | Expense | Expense | ECL provision |
+| Allowance for Doubtful Debts | Asset | Current Asset (contra) | ECL provision |
+| Leave Expense | Expense | Expense | Employee accruals |
+| Accrued Leave Liability | Liability | Current Liability | Employee accruals |
+| Bonus Expense | Expense | Expense | Employee accruals |
+| Accrued Bonus Liability | Liability | Current Liability | Employee accruals |
+| Provision Expense | Expense | Expense | IAS 37 provisions |
+| Provision for Obligations | Liability | Non-Current Liability | IAS 37 provisions |
+| Finance Cost — Unwinding | Expense | Expense | IAS 37 provisions, Lease |
+| Retained Earnings | Equity | Retained Earnings | Dividends |
+| Dividends Payable | Liability | Current Liability | Dividends |
+| Intercompany Receivable | Asset | Current Asset | Intercompany |
+| Intercompany Payable | Liability | Current Liability | Intercompany |
+| Capital Work-in-Progress | Asset | Non-Current Asset | Capital WIP |
 
 **API:** `POST /chart-of-accounts` or `POST /chart-of-accounts/bulk-upsert`