jaz-cli 2.5.0 → 2.7.0

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: api
-version: 2.5.0
+version: 2.7.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.
@@ -22,7 +22,7 @@ You are working with the **Jaz/Juan REST API** — the backend for Jaz (Singapor
 
 **Base URL**: `https://api.getjaz.com`
 **Auth**: `x-jk-api-key: <key>` header on every request — key has `jk-` prefix (e.g., `jk-a1b2c3...`). NOT `Authorization: Bearer` or `x-api-key`.
-**Content-Type**: `application/json` for all POST/PUT/PATCH
+**Content-Type**: `application/json` for all POST/PUT/PATCH (except multipart endpoints: `createBusinessTransactionFromAttachment` FILE mode, `importBankStatementFromAttachment`, and attachment uploads)
 **All paths are prefixed**: `/api/v1/` (e.g., `https://api.getjaz.com/api/v1/invoices`)
 
 ## Critical Rules
@@ -129,6 +129,14 @@ You are working with the **Jaz/Juan REST API** — the backend for Jaz (Singapor
 55. **Scheduled endpoints support date aliases** — `txnDateAliases` middleware (mapping `issueDate`/`date` → `valueDate`) now applies to all scheduled create/update endpoints: `POST/PUT /scheduled/invoices`, `POST/PUT /scheduled/bills`, `POST/PUT /scheduled/journals`, `POST/PUT /scheduled/subscriptions`.
 56. **Kebab-case URL aliases** — `capsuleTypes` endpoints also accept kebab-case paths: `/capsule-types` (list, search, CRUD). `moveTransactionCapsules` also accepts `/move-transaction-capsules`. Both camelCase and kebab-case work identically.
 
+### Jaz Magic — Extraction & Autofill
+57. **When the user starts from an attachment, always use Jaz Magic** — if the input is a PDF, JPG, or any document image (invoice, bill, receipt), the correct path is `POST /magic/createBusinessTransactionFromAttachment`. Do NOT manually construct a `POST /invoices` or `POST /bills` payload from an attachment — Jaz Magic handles the entire extraction-and-autofill pipeline server-side: OCR, line item detection, contact matching, CoA auto-mapping via ML learning, and draft creation with all fields pre-filled. Only use `POST /invoices` or `POST /bills` when building transactions from structured data (JSON, CSV, database rows) where the fields are already known.
+58. **Two upload modes with different content types** — `sourceType: "FILE"` requires **multipart/form-data** with `sourceFile` blob (JSON body fails with 400 "sourceFile is a required field"). `sourceType: "URL"` accepts **application/json** with `sourceURL` string. The OAS only documents URL mode — FILE mode (the common case) is undocumented.
+59. **Three required fields**: `sourceFile` (multipart blob — NOT `file`), `businessTransactionType` (`"INVOICE"` or `"BILL"` only — `EXPENSE` rejected), `sourceType` (`"FILE"` or `"URL"`). All three are validated server-side.
+60. **Response maps transaction types**: Request `BILL` → response `businessTransactionType: "PURCHASE"`. Request `INVOICE` → response `businessTransactionType: "SALE"`. S3 paths follow: `/purchases/` vs `/sales/`.
+61. **Extraction is asynchronous** — the API response is immediate (file upload confirmation only). The actual Magic pipeline — OCR, line item extraction, contact matching, CoA learning, and autofill — runs asynchronously. The `subscriptionFBPath` in the response (e.g., `magic_transactions/{orgId}/purchase/{fileId}`) is a Firebase Realtime Database path for subscribing to extraction status updates.
+62. **Accepts PDF and JPG/JPEG** — both file types confirmed working. Handwritten documents are accepted at upload stage (extraction quality varies). `fileType` in response reflects actual format: `"PDF"`, `"JPEG"`.
+
 ## Supporting Files
 
 For detailed reference, read these files in this skill directory:
@@ -154,6 +162,8 @@ The backend DX overhaul is live. Key improvements now available:
 
 ## Recommended Client Patterns
 
+- **Starting from an attachment?** → Use Jaz Magic (`POST /magic/createBusinessTransactionFromAttachment`). Never manually parse a PDF/JPG to construct `POST /invoices` or `POST /bills` — let the extraction & autofill pipeline handle it.
+- **Starting from structured data?** → Use `POST /invoices` or `POST /bills` directly with the known field values.
 - **Serialization (Python)**: `model_dump(mode="json", by_alias=True, exclude_unset=True, exclude_none=True)`
 - **Field names**: All request bodies use camelCase
 - **Date serialization**: Python `date` type → `YYYY-MM-DD` strings

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

@@ -54,8 +54,9 @@ Resources MUST be created in this order. Steps at the same level can run in para
 - `POST /items` → create items (needs CoA + tax profile IDs from Levels 0-1)
 
 ### Level 3: Transactions (parallel)
-- `POST /invoices` → create invoices (needs contacts + CoA + tax profiles)
-- `POST /bills` → create bills (same deps, can embed payments)
+- `POST /magic/createBusinessTransactionFromAttachment` → **starting from an attachment (PDF/JPG)?** Use Jaz Magic — extraction & autofill creates a draft invoice or bill with all fields pre-filled. See SKILL.md Rules 57-62.
+- `POST /invoices` → create invoices from structured data (needs contacts + CoA + tax profiles)
+- `POST /bills` → create bills from structured data (same deps, can embed payments)
 - `POST /journals` → create journal entries (needs CoA)
 - `POST /cash-in-journals` → cash receipts (needs bank account from CoA)
 - `POST /cash-out-journals` → cash payments (needs bank account from CoA)

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

@@ -790,6 +790,84 @@ Valid `datatypeCode`: `TEXT`, `NUMBER`, `BOOLEAN`, `DATE`, `LINK`.
 
 ---
 
+## 14g. Jaz Magic — Extraction & Autofill
+
+### POST /api/v1/magic/createBusinessTransactionFromAttachment
+
+**When the user starts from an attachment (PDF, JPG, document image), this is the endpoint to use.** Do not manually parse files to construct `POST /invoices` or `POST /bills` — Jaz Magic handles the full extraction-and-autofill pipeline server-side: OCR, line item detection, contact matching, and CoA auto-mapping via ML learning. Creates a complete draft transaction with all fields pre-filled. Use `POST /invoices` or `POST /bills` only when building from structured data where the fields are already known.
+
+Processing is **asynchronous** — the API response confirms file upload immediately. The extraction pipeline runs server-side and pushes status updates via Firebase Realtime Database.
+
+**Two modes** — content type depends on `sourceType`:
+
+#### FILE mode (multipart/form-data) — most common
+
+```
+POST /api/v1/magic/createBusinessTransactionFromAttachment
+Content-Type: multipart/form-data
+
+Fields:
+  - sourceFile: PDF or JPG file blob (NOT "file")
+  - businessTransactionType: "INVOICE" or "BILL" (NOT "EXPENSE")
+  - sourceType: "FILE"
+```
+
+```json
+/ Response (201):
+{
+  "data": {
+    "businessTransactionType": "PURCHASE",
+    "filename": "NB64458.pdf",
+    "invalidFiles": [],
+    "validFiles": [{
+      "subscriptionFBPath": "magic_transactions/{orgId}/purchase/{fileId}",
+      "errorCode": null,
+      "errorMessage": null,
+      "fileDetails": {
+        "fileId": "6e999313b8b53ccef0757394ee6c7e6a",
+        "fileType": "PDF",
+        "fileURL": "https://s3.ap-southeast-1.amazonaws.com/.../{resourceId}.PDF",
+        "fileName": "NB64458.pdf"
+      }
+    }]
+  }
+}
+```
+
+#### URL mode (application/json) — for remote files
+
+```json
+/ Request:
+POST /api/v1/magic/createBusinessTransactionFromAttachment
+Content-Type: application/json
+
+{
+  "businessTransactionType": "BILL",
+  "sourceType": "URL",
+  "sourceURL": "https://example.com/invoice.pdf"
+}
+
+/ Response: same shape as FILE mode
+```
+
+**What Jaz Magic extracts and autofills:**
+- Line items (description, quantity, unit price, amounts)
+- Contact name and details (matched against existing contacts)
+- Chart of Accounts mapping (ML-based learning from past transactions)
+- Tax amounts and profiles
+- Document reference numbers, dates, currency
+
+**Key gotchas:**
+- `sourceFile` is the field name (NOT `file`) — same pattern as bank statement endpoint
+- Only `INVOICE` and `BILL` accepted — `EXPENSE` returns 422
+- Response maps types: `INVOICE` → `SALE`, `BILL` → `PURCHASE`
+- JSON body with `sourceType: "FILE"` always fails (400) — MUST use multipart
+- `subscriptionFBPath` is the Firebase path for tracking extraction progress
+- All three fields (`sourceFile`/`sourceURL`, `businessTransactionType`, `sourceType`) are required — omitting any returns 422
+- File types confirmed: PDF, JPG/JPEG (handwritten documents accepted — extraction quality varies)
+
+---
+
 ## 15. Bank Records
 
 ### POST /api/v1/magic/importBankStatementFromAttachment (multipart)

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

@@ -14,7 +14,7 @@ Key capabilities: draft/approval workflows, multi-currency (auto-fetch ECB rates
 
 If payment date equals invoice date, it's recorded as a cash transaction (not AR). Transaction fees are deducted from cash received. RGL = `(Invoice payment / Transaction Rate) - (Cash received / Payment Rate)`.
 
-**API**: CRUD `GET/POST/PUT/DELETE /invoices`, `POST /invoices/search`, `POST /invoices/:id/payments`, `GET /invoices/:id/payments`, `POST /invoices/:id/credits`, `GET /invoices/:id/download`, `POST/GET/DELETE /invoices/:id/attachments`, `PUT /invoices/:id/approve`, `POST /scheduled/invoices` (CRUD), `POST /scheduled/subscriptions` (recurring). Generic payment ops: `GET/PUT/DELETE /payments/:id`
+**API**: CRUD `GET/POST/PUT/DELETE /invoices`, `POST /invoices/search`, `POST /invoices/:id/payments`, `GET /invoices/:id/payments`, `POST /invoices/:id/credits`, `GET /invoices/:id/download`, `POST/GET/DELETE /invoices/:id/attachments`, `PUT /invoices/:id/approve`, `POST /scheduled/invoices` (CRUD), `POST /scheduled/subscriptions` (recurring). Generic payment ops: `GET/PUT/DELETE /payments/:id`. **Starting from a PDF/JPG attachment?** Use `POST /magic/createBusinessTransactionFromAttachment` instead — Jaz Magic handles extraction & autofill (see AI Agents section).
 
 ---
 
@@ -26,7 +26,7 @@ Key capabilities: bill receipts (short-form template creating bill + payment tog
 
 Transaction fees are added to cash spent (not deducted like invoices). RGL = `(Cash spent / Payment rate) - (Bill payment / Transaction rate)`.
 
-**API**: CRUD `GET/POST/PUT/DELETE /bills`, `POST /bills/search`, `POST /bills/:id/payments`, `GET /bills/:id/payments`, `POST /bills/:id/credits`, `POST/GET/DELETE /bills/:id/attachments`, `PUT /bills/:id/approve`, `POST /scheduled/bills` (CRUD). Generic payment ops: `GET/PUT/DELETE /payments/:id`
+**API**: CRUD `GET/POST/PUT/DELETE /bills`, `POST /bills/search`, `POST /bills/:id/payments`, `GET /bills/:id/payments`, `POST /bills/:id/credits`, `POST/GET/DELETE /bills/:id/attachments`, `PUT /bills/:id/approve`, `POST /scheduled/bills` (CRUD). Generic payment ops: `GET/PUT/DELETE /payments/:id`. **Starting from a PDF/JPG attachment?** Use `POST /magic/createBusinessTransactionFromAttachment` instead — Jaz Magic handles extraction & autofill (see AI Agents section).
 
 ---
 
@@ -66,7 +66,7 @@ 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).
+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}}`).
 
@@ -173,9 +173,9 @@ Fixed assets lock their linked line items — cannot edit account, amounts, or e
 
 **Agent Builder**: Configure custom AI agents in Settings > Agent Builder with name, email (a-z, 0-9, + symbol), and workflow preferences.
 
-**Jaz Magic**: Contact-level setting controlling auto-extraction behavior — line items (detailed extraction), summary totals (single amount), or none. Up to 10 images can be merged into a single PDF.
+**Jaz Magic**: The extraction & autofill engine. When users start from an attachment (PDF, JPG, document image), Jaz Magic is the correct path — it handles OCR, line item detection, contact matching, and CoA auto-mapping via ML learning, producing a complete draft transaction. Contact-level settings control extraction behavior: line items (detailed extraction), summary totals (single amount), or none. Up to 10 images can be merged into a single PDF. **Do not manually parse attachments to construct `POST /invoices` or `POST /bills` — always use Jaz Magic when the input is a file.**
 
-**API**: `POST /magic/createBusinessTransactionFromAttachment` (OCR PDF → draft transaction), `POST /magic/importBankStatementFromAttachment`, `PUT /invoices/magic-update`, `PUT /bills/magic-update`, `PUT /journals/magic-update`, `GET /invoices/magic-search`, `GET /bills/magic-search` (all magic endpoints use `x-magic-api-key`)
+**API**: `POST /magic/createBusinessTransactionFromAttachment` (**attachment → draft transaction** — the primary endpoint for file-based creation), `POST /magic/importBankStatementFromAttachment` (bank statements), `PUT /invoices/magic-update`, `PUT /bills/magic-update`, `PUT /journals/magic-update`, `GET /invoices/magic-search`, `GET /bills/magic-search` (all magic endpoints use `x-magic-api-key`)
 
 ---
 

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

@@ -260,6 +260,23 @@ When POSTing, `classificationType` must be one of these exact strings (same as `
 
 ---
 
+## Jaz Magic — Extraction & Autofill
+
+| What You'd Guess | Actual API Field | Notes |
+|------------------|-------------------|-------|
+| `file` | `sourceFile` | Multipart blob — same pattern as bank statement |
+| `type: "BILL"` | `businessTransactionType: "BILL"` | Request accepts `INVOICE` or `BILL` only |
+| Response `"BILL"` | Response `"PURCHASE"` | Response maps: `BILL` → `PURCHASE`, `INVOICE` → `SALE` |
+| JSON body | multipart/form-data | FILE mode requires multipart — JSON returns 400 |
+| Sync response | Async extraction | Response = upload confirmation; extraction & autofill run async |
+| `status` field | `subscriptionFBPath` | Firebase path for tracking extraction progress |
+
+**Content-Type depends on sourceType:**
+- `sourceType: "FILE"` → `Content-Type: multipart/form-data` (MUST use multipart)
+- `sourceType: "URL"` → `Content-Type: application/json` (JSON body works)
+
+---
+
 ## Bank Records
 
 | What You'd Guess | Actual API Field | Notes |

package/assets/skills/api/references/full-api-surface.md

@@ -386,7 +386,7 @@
 
 | Method | Path | Description |
 |--------|------|-------------|
-| POST | `/magic/createBusinessTransactionFromAttachment` | OCR: Convert PDF → transaction |
+| POST | `/magic/createBusinessTransactionFromAttachment` | **Jaz Magic: Extraction & Autofill.** Upload PDF/JPG → full extraction pipeline (OCR, line items, contact matching, CoA ML learning) → draft invoice or bill with all fields autofilled. FILE mode = multipart (`sourceFile` blob), URL mode = JSON (`sourceURL`). Async — returns `subscriptionFBPath` for tracking extraction progress. Request `INVOICE` → response `SALE`, `BILL` → `PURCHASE`. |
 | POST | `/magic/importBankStatementFromAttachment` | Convert bank statement → entries |
 | PUT | `/invoices/magic-update` | AI-enhanced invoice update |
 | PUT | `/bills/magic-update` | AI-enhanced bill update |

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: conversion
-version: 2.5.0
+version: 2.7.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.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.
+version: 2.7.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,10 @@ 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 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)
@@ -61,7 +64,10 @@ Jaz schedulers generate **fixed-amount** recurring entries. This determines whic
 | 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 |
+| 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 |
@@ -87,23 +93,29 @@ Each recipe includes: scenario description, accounts involved, journal entries,
 
 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
 
-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`*
+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`*
 
-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`*
+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`*
 
-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.
+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
 
-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`*
+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`*
 
-11. **[Dividend Declaration & Payment](references/dividend.md)** — Board-declared dividend: two journals (declaration reducing retained earnings, then payment).
+14. **[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.
+15. **[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.
+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
 
@@ -118,19 +130,22 @@ Each recipe includes: scenario description, accounts involved, journal entries,
 
 ## 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.
+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>` for currency labeling and `--json` for agent-parseable output.
+All calculators support `--currency <code>` and `--json`.
 
 ```bash
 # ── Tier 2 Calculators ──────────────────────────────────────────
 
-# Loan amortization schedule (PMT, interest/principal split)
+# 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]
 
@@ -140,6 +155,12 @@ jaz calc prepaid-expense --amount 12000 --periods 12 [--frequency monthly|quarte
 # 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)
@@ -156,7 +177,7 @@ jaz calc provision --amount 500000 --rate 4 --term 60 [--start-date 2025-01-01]
 
 ### 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:
+Every calculator's `--json` output includes a `blueprint` object — a complete execution plan for creating the capsule and posting all transactions in Jaz:
 
 ```json
 {
@@ -165,13 +186,14 @@ Every calculator's `--json` output includes a `blueprint` object — a complete
   "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": "journal",
-        "description": "Loan disbursement",
+        "action": "cash-in",
+        "description": "Record loan proceeds received from bank",
         "date": "2025-01-01",
         "lines": [
           { "account": "Cash / Bank Account", "debit": 100000, "credit": 0 },
@@ -183,12 +205,24 @@ Every calculator's `--json` output includes a `blueprint` object — a complete
 }
 ```
 
+**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:**
-- 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
+- `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
-- Journal entries balanced (sum of debits = sum of credits in every step)
+- 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