jaz-cli 2.5.0 → 2.6.0

package/assets/skills/transaction-recipes/references/hire-purchase.md

@@ -0,0 +1,190 @@
+# Recipe: Hire Purchase
+
+## Scenario
+
+Your company acquires a motor vehicle under a hire purchase (HP) agreement: $5,000/month for 36 months at 5% incremental borrowing rate. Ownership transfers to you at the end of the term. Under IFRS 16, this is accounted for the same way as any other lease — right-of-use asset, lease liability, effective interest unwinding — with **one critical difference**: the ROU asset is depreciated over its **useful life** (60 months), not the lease term (36 months), because ownership transfers at the end.
+
+**Pattern:** Hybrid — native fixed asset (straight-line ROU depreciation over useful life) + manual journals (liability unwinding) + capsule
+
+**Cross-reference:** This recipe is a variant of the [IFRS 16 Lease recipe](./ifrs16-lease.md). Everything is identical except the depreciation period. Read the IFRS 16 recipe first for the full foundational treatment, then return here for the hire purchase-specific difference.
+
+**Why the difference:** IFRS 16.32 requires that when ownership transfers (or a purchase option is reasonably certain to be exercised), the ROU asset is depreciated over the asset's useful life rather than the lease term. Hire purchase agreements always transfer ownership, so this rule always applies.
+
+---
+
+## Accounts Involved
+
+| Account | Type | Subtype | Role |
+|---|---|---|---|
+| Right-of-Use Asset | Asset | Non-Current Asset | The HP'd asset (e.g., motor vehicle) |
+| Accumulated Depreciation — ROU | Asset | Non-Current Asset | Contra-asset reducing ROU net book value |
+| Lease Liability | Liability | Non-Current Liability | PV of future HP payments |
+| Interest Expense — Leases | Expense | Finance Cost | Effective interest on lease liability |
+| Depreciation Expense — ROU | Expense | Depreciation | Straight-line over useful life (NOT lease term) |
+| Cash / Bank Account | Asset | Bank | Makes monthly HP payments |
+
+> **Same accounts as IFRS 16 lease.** The only change is the depreciation calculation — the accounts, journal structure, and liability unwinding are all identical.
+
+---
+
+## Journal Entries
+
+### Step 1: Initial Recognition (same as IFRS 16)
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Right-of-Use Asset | $166,828.51 | |
+| 2 | Lease Liability | | $166,828.51 |
+
+PV of 36 payments of $5,000 at 5% annual (0.4167% monthly).
+
+### Step 2: Monthly HP Payment (same as IFRS 16)
+
+Each $5,000 payment splits between interest (expense) and principal (liability reduction):
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Lease Liability | *principal portion* | |
+| 2 | Interest Expense — Leases | *interest portion* | |
+| 3 | Cash / Bank Account | | $5,000 |
+
+**Calculation per month:**
+- Interest = Outstanding liability x 0.4167%
+- Principal = $5,000 - Interest
+- New liability = Outstanding liability - Principal
+
+### Step 3: Monthly Depreciation — THE KEY DIFFERENCE
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Depreciation Expense — ROU | $2,780.48 | |
+| 2 | Accumulated Depreciation — ROU | | $2,780.48 |
+
+**Standard IFRS 16 lease:** $166,828.51 / 36 months = **$4,634.13/month**
+**Hire purchase:** $166,828.51 / 60 months = **$2,780.48/month**
+
+> The hire purchase depreciation rate is **$1,853.65/month LESS** than a standard lease. This is because the asset's economic life (60 months) extends well beyond the payment term (36 months). Ownership transfers, so the asset continues generating value after the last payment.
+
+---
+
+## Capsule Structure
+
+**Capsule:** "Hire Purchase — Motor Vehicle — 2025"
+**Capsule Type:** "Hire Purchase"
+
+Contents:
+- 1 initial recognition journal (ROU asset + lease liability)
+- 36 monthly payment journals (manual — interest changes each month)
+- 60 monthly depreciation entries (auto-generated by fixed asset register — these appear in the ledger but aren't manually created)
+- **Manually created entries:** 37
+
+> The fixed asset depreciation entries are not assigned to the capsule automatically. Group the General Ledger by the ROU asset account alongside the capsule view for a complete picture. Depreciation continues for 24 months after the last HP payment.
+
+---
+
+## Worked Example
+
+**HP terms:**
+- Monthly payment: $5,000
+- Lease term: 36 months
+- Incremental borrowing rate: 5% annual (0.4167% monthly)
+- Asset useful life: 60 months
+- PV of lease payments: $166,828.51
+
+**CLI command:**
+```
+jaz calc lease --payment 5000 --term 36 --rate 5 --useful-life 60 --start-date 2025-01-01
+```
+
+The `--useful-life 60` flag tells the calculator this is a hire purchase — depreciation will use 60 months instead of the 36-month lease term. The CLI generates a `capsuleDescription` with full workings so the capsule is self-documenting.
+
+### Liability Unwinding Table (first 3 months + month 36)
+
+| Month | Opening Liability | Interest (0.4167%) | Principal | Closing Liability |
+|---|---|---|---|---|
+| 1 | $166,828.51 | $695.12 | $4,304.88 | $162,523.63 |
+| 2 | $162,523.63 | $677.18 | $4,322.82 | $158,200.81 |
+| 3 | $158,200.81 | $659.17 | $4,340.83 | $153,859.98 |
+| ... | ... | ... | ... | ... |
+| 36 | $4,979.24 | $20.75 | $4,979.24 | $0.00* |
+
+> *Final payment adjusted to close the liability exactly to zero (payment = $4,999.99).
+
+**Month 1 journal entry (manual — same as IFRS 16):**
+- Dr Lease Liability $4,304.88
+- Dr Interest Expense — Leases $695.12
+- Cr Cash $5,000.00
+- Description: "HP payment — Month 1 of 36 (Motor Vehicle)"
+- Assign to capsule
+
+**Month 1 depreciation (automatic — posted by Jaz FA register):**
+- Dr Depreciation Expense — ROU $2,780.48
+- Cr Accumulated Depreciation — ROU $2,780.48
+
+### Depreciation Comparison: Hire Purchase vs Standard Lease
+
+| Item | Standard IFRS 16 Lease | Hire Purchase |
+|---|---|---|
+| Depreciation period | 36 months (lease term) | 60 months (useful life) |
+| Monthly depreciation | $4,634.13 | $2,780.48 |
+| **Difference** | — | **$1,853.65/month LESS** |
+
+### What Happens After Month 36 (Lease Payments End)
+
+| Item | Value |
+|---|---|
+| Lease Liability | $0 (fully unwound) |
+| ROU Asset (gross) | $166,828.51 |
+| Accumulated Depreciation (36 months) | $100,097.28 |
+| **ROU Net Book Value** | **$66,731.23** |
+| Remaining depreciation period | 24 more months |
+
+After the last HP payment, the lease liability is zero and no more cash leaves the account. But the ROU asset still has a book value of $66,731.23 because it was depreciated over 60 months, not 36. Depreciation of $2,780.48/month continues for another 24 months until the asset is fully depreciated.
+
+### Summary Over Full Useful Life (60 Months)
+
+| Item | Total |
+|---|---|
+| Total cash payments | $180,000 (36 x $5,000) |
+| Total interest expense | $13,171.48 |
+| Total depreciation expense | $166,828.51 |
+| **Total P&L impact** | **$180,000** |
+| Lease liability at month 36 | $0 |
+| ROU asset net book value at month 36 | $66,731.23 |
+| ROU asset net book value at month 60 | $0 |
+
+> **P&L timing differs from a standard lease.** With hire purchase, the P&L charge is spread over 60 months instead of 36. In months 1-36, both interest and depreciation hit the P&L. In months 37-60, only depreciation remains — at a lower rate than the original cash payment.
+
+---
+
+## Enrichment Suggestions
+
+| Enrichment | Value | Why |
+|---|---|---|
+| Tracking Tag | "Hire Purchase" | Filter all HP-related transactions |
+| Nano Classifier | Asset Type → "Motor Vehicle" | Break down by asset class if multiple HPs |
+| Custom Field | "HP Agreement #" → "HP-2025-0089" | Record the hire purchase agreement reference |
+
+---
+
+## Verification
+
+1. **Lease Liability should reduce to $0 at end of lease term (month 36)** → Group General Ledger by Capsule. Liability starts at $166,828.51 and closes at $0 after 36 payments.
+2. **Interest Expense total = total cash payments - PV** → $180,000 − $166,828.51 = $13,171.48 (rounding may cause ±$0.01 variance).
+3. **ROU Asset continues depreciating after lease payments end** → At month 36, ROU net book value = $66,731.23. Depreciation continues at $2,780.48/month for 24 more months.
+4. **At end of useful life (month 60), ROU asset is fully depreciated** → ROU Asset $166,828.51 − Accumulated Depreciation $166,828.51 = $0 net book value.
+5. **Balance Sheet check** → Between months 37-60, no lease liability exists but the ROU asset (net of accumulated depreciation) continues appearing on the balance sheet. This is the distinguishing feature of hire purchase vs operating lease.
+
+---
+
+## Variations
+
+**Standard operating lease (no ownership transfer):** Use `jaz calc lease --payment 5000 --term 36 --rate 5` without the `--useful-life` flag. The ROU asset is depreciated over the lease term (36 months), not useful life. See the [IFRS 16 Lease recipe](./ifrs16-lease.md).
+
+**Guaranteed residual value:** If the HP agreement includes a guaranteed residual value (e.g., $10,000 balloon payment at end of term), add the PV of the residual to the initial ROU asset and lease liability. The liability schedule must include the balloon as the final period payment.
+
+**Variable payments:** Only the fixed portion of HP payments is included in the PV calculation. Any variable component (e.g., mileage-based charges) is recognized as expense when incurred, not capitalized in the ROU asset.
+
+**SG motor vehicle specifics:** The COE (Certificate of Entitlement) is typically treated as a separate intangible asset with its own amortization schedule (10 years for Category A/B), not bundled into the HP's ROU asset. Create a separate capsule for the COE if applicable.
+
+**SG tax depreciation (IRAS):** Capital allowances for motor vehicles under Section 19/19A may differ from IFRS depreciation. The S-car cap ($35,000 for private cars) and the 3-year write-off period for commercial vehicles don't align with IFRS useful life estimates. Businesses may need to track both IFRS depreciation (for financial reporting) and tax depreciation (for S68 deductions) separately. This recipe covers IFRS only — tax depreciation adjustments are out of scope.

package/dist/calc/amortization.js

@@ -4,7 +4,7 @@
  */
 import { round2, addMonths } from './types.js';
 import { validatePositive, validatePositiveInteger, validateDateFormat } from './validate.js';
-import { journalStep, fmtCapsuleAmount } from './blueprint.js';
+import { journalStep, billStep, invoiceStep, fmtCapsuleAmount, fmtAmt } from './blueprint.js';
 export function calculatePrepaidExpense(inputs) {
     const { amount, periods, frequency = 'monthly', startDate, currency } = inputs;
     validatePositive(amount, 'Amount');
@@ -14,15 +14,24 @@ export function calculatePrepaidExpense(inputs) {
     let blueprint = null;
     if (startDate) {
         const steps = [
-            journalStep(1, 'Initial prepaid payment (bill or cash-out entry)', startDate, [
+            billStep(1, 'Create bill from supplier coded to Prepaid Asset, then pay from Cash / Bank Account', startDate, [
                 { account: 'Prepaid Asset', debit: amount, credit: 0 },
                 { account: 'Cash / Bank Account', debit: 0, credit: amount },
             ]),
             ...schedule.map((row, idx) => journalStep(idx + 2, row.journal.description, row.date, row.journal.lines)),
         ];
+        const c = currency ?? undefined;
+        const workings = [
+            `Prepaid Expense Recognition Workings`,
+            `Total prepaid: ${fmtAmt(amount, c)} | Periods: ${periods} (${frequency})`,
+            `Per period: ${fmtAmt(round2(amount / periods), c)}`,
+            `Method: Straight-line recognition over ${periods} ${frequency} periods`,
+            `Rounding: 2dp per period, final period absorbs remainder`,
+        ].join('\n');
         blueprint = {
             capsuleType: 'Prepaid Expenses',
             capsuleName: `Prepaid Expense — ${fmtCapsuleAmount(amount, currency)} — ${periods} periods`,
+            capsuleDescription: workings,
             tags: ['Prepaid Expense'],
             customFields: { 'Policy / Contract #': null },
             steps,
@@ -46,15 +55,24 @@ export function calculateDeferredRevenue(inputs) {
     let blueprint = null;
     if (startDate) {
         const steps = [
-            journalStep(1, 'Initial deferred receipt (invoice or cash-in entry)', startDate, [
+            invoiceStep(1, 'Create invoice to customer coded to Deferred Revenue, record payment to Cash / Bank Account', startDate, [
                 { account: 'Cash / Bank Account', debit: amount, credit: 0 },
                 { account: 'Deferred Revenue', debit: 0, credit: amount },
             ]),
             ...schedule.map((row, idx) => journalStep(idx + 2, row.journal.description, row.date, row.journal.lines)),
         ];
+        const c2 = currency ?? undefined;
+        const workings2 = [
+            `Deferred Revenue Recognition Workings`,
+            `Total deferred: ${fmtAmt(amount, c2)} | Periods: ${periods} (${frequency})`,
+            `Per period: ${fmtAmt(round2(amount / periods), c2)}`,
+            `Method: Straight-line recognition over ${periods} ${frequency} periods`,
+            `Rounding: 2dp per period, final period absorbs remainder`,
+        ].join('\n');
         blueprint = {
             capsuleType: 'Deferred Revenue',
             capsuleName: `Deferred Revenue — ${fmtCapsuleAmount(amount, currency)} — ${periods} periods`,
+            capsuleDescription: workings2,
             tags: ['Deferred Revenue'],
             customFields: { 'Contract #': null },
             steps,

package/dist/calc/asset-disposal.js

@@ -0,0 +1,151 @@
+/**
+ * Asset disposal gain/loss calculator.
+ *
+ * Compliance references:
+ *  - IAS 16.67-72: Derecognition on disposal or when no future economic benefits expected
+ *  - IAS 16.68: Gain/loss = Net disposal proceeds - Carrying amount
+ *  - IAS 16.71: Gain ≠ revenue (classified separately in P&L)
+ *
+ * Computes depreciation to the disposal date (pro-rated partial period),
+ * then calculates NBV and gain/loss. Supports SL, DDB, and 150DB methods.
+ */
+import { round2 } from './types.js';
+import { CalcValidationError, validatePositive, validateNonNegative, validatePositiveInteger, validateSalvageLessThanCost, validateDateFormat, } from './validate.js';
+import { journalStep, noteStep, fmtCapsuleAmount, fmtAmt } from './blueprint.js';
+/**
+ * Count full months between two YYYY-MM-DD dates.
+ * Partial months are rounded up (any day in a month counts as a full month).
+ */
+function monthsBetween(from, to) {
+    const d1 = new Date(from + 'T00:00:00');
+    const d2 = new Date(to + 'T00:00:00');
+    const months = (d2.getFullYear() - d1.getFullYear()) * 12 + (d2.getMonth() - d1.getMonth());
+    // If disposal day > acquisition day, it's a partial month — round up
+    return d2.getDate() >= d1.getDate() ? months + 1 : Math.max(months, 0);
+}
+/**
+ * Compute accumulated depreciation from acquisition to disposal date.
+ */
+function computeAccumDepreciation(cost, salvageValue, usefulLifeYears, method, monthsHeld) {
+    const totalMonths = usefulLifeYears * 12;
+    const depreciableBase = round2(cost - salvageValue);
+    // Cap at useful life — asset is fully depreciated
+    const effectiveMonths = Math.min(monthsHeld, totalMonths);
+    if (method === 'sl') {
+        // Straight-line: pro-rate by months
+        const monthlyDep = depreciableBase / totalMonths;
+        return round2(Math.min(monthlyDep * effectiveMonths, depreciableBase));
+    }
+    // DDB / 150DB: compute year-by-year then pro-rate final partial year
+    const multiplier = method === 'ddb' ? 2 : 1.5;
+    const annualRate = multiplier / usefulLifeYears;
+    let bookValue = cost;
+    let totalDep = 0;
+    let monthsRemaining = effectiveMonths;
+    for (let year = 1; year <= usefulLifeYears && monthsRemaining > 0; year++) {
+        const remainingYears = usefulLifeYears - year + 1;
+        const ddbAmount = round2(bookValue * annualRate);
+        const slAmount = round2((bookValue - salvageValue) / remainingYears);
+        const useSL = slAmount >= ddbAmount || round2(bookValue - ddbAmount) < salvageValue;
+        let annualDep = useSL ? slAmount : ddbAmount;
+        // Don't breach salvage floor
+        if (round2(bookValue - annualDep) < salvageValue) {
+            annualDep = round2(bookValue - salvageValue);
+        }
+        if (monthsRemaining >= 12) {
+            // Full year
+            totalDep = round2(totalDep + annualDep);
+            bookValue = round2(bookValue - annualDep);
+            monthsRemaining -= 12;
+        }
+        else {
+            // Partial year: pro-rate
+            const partialDep = round2(annualDep * monthsRemaining / 12);
+            totalDep = round2(totalDep + partialDep);
+            monthsRemaining = 0;
+        }
+    }
+    return Math.min(totalDep, depreciableBase);
+}
+export function calculateAssetDisposal(inputs) {
+    const { cost, salvageValue, usefulLifeYears, acquisitionDate, disposalDate, proceeds, method = 'sl', currency, } = inputs;
+    validatePositive(cost, 'Asset cost');
+    validateNonNegative(salvageValue, 'Salvage value');
+    validatePositiveInteger(usefulLifeYears, 'Useful life (years)');
+    if (salvageValue > 0)
+        validateSalvageLessThanCost(salvageValue, cost);
+    validateNonNegative(proceeds, 'Disposal proceeds');
+    validateDateFormat(acquisitionDate);
+    validateDateFormat(disposalDate);
+    // Validate disposal is after acquisition
+    if (disposalDate <= acquisitionDate) {
+        throw new CalcValidationError('Disposal date must be after acquisition date.');
+    }
+    const monthsHeld = monthsBetween(acquisitionDate, disposalDate);
+    const accumulatedDepreciation = computeAccumDepreciation(cost, salvageValue, usefulLifeYears, method, monthsHeld);
+    const netBookValue = round2(cost - accumulatedDepreciation);
+    const gainOrLoss = round2(proceeds - netBookValue);
+    const isGain = gainOrLoss >= 0;
+    // Build disposal journal entry
+    const lines = [];
+    if (proceeds > 0) {
+        lines.push({ account: 'Cash / Bank Account', debit: proceeds, credit: 0 });
+    }
+    if (accumulatedDepreciation > 0) {
+        lines.push({ account: 'Accumulated Depreciation', debit: accumulatedDepreciation, credit: 0 });
+    }
+    if (!isGain) {
+        lines.push({ account: 'Loss on Disposal', debit: Math.abs(gainOrLoss), credit: 0 });
+    }
+    lines.push({ account: 'Fixed Asset (at cost)', debit: 0, credit: cost });
+    if (isGain && gainOrLoss > 0) {
+        lines.push({ account: 'Gain on Disposal', debit: 0, credit: gainOrLoss });
+    }
+    const disposalJournal = {
+        description: `Asset disposal — ${isGain ? (gainOrLoss > 0 ? 'gain' : 'at book value') : 'loss'}`,
+        lines,
+    };
+    // Build blueprint
+    const c = currency ?? undefined;
+    const methodLabel = method === 'sl' ? 'Straight-line' : method === 'ddb' ? 'Double declining' : '150% declining';
+    const workings = [
+        `Asset Disposal Workings (IAS 16)`,
+        `Cost: ${fmtAmt(cost, c)} | Salvage: ${fmtAmt(salvageValue, c)} | Life: ${usefulLifeYears} years (${methodLabel})`,
+        `Acquired: ${acquisitionDate} | Disposed: ${disposalDate} | Held: ${monthsHeld} months`,
+        `Accumulated depreciation: ${fmtAmt(accumulatedDepreciation, c)} | NBV: ${fmtAmt(netBookValue, c)}`,
+        `Proceeds: ${fmtAmt(proceeds, c)} | ${isGain ? (gainOrLoss > 0 ? `Gain: ${fmtAmt(gainOrLoss, c)}` : 'At book value (no gain/loss)') : `Loss: ${fmtAmt(Math.abs(gainOrLoss), c)}`}`,
+        `Method: IAS 16.68 — Gain/Loss = Proceeds − NBV = ${fmtAmt(proceeds, c)} − ${fmtAmt(netBookValue, c)} = ${fmtAmt(gainOrLoss, c)}`,
+    ].join('\n');
+    let blueprint = null;
+    blueprint = {
+        capsuleType: 'Asset Disposal',
+        capsuleName: `Asset Disposal — ${fmtCapsuleAmount(cost, currency)} asset — ${disposalDate}`,
+        capsuleDescription: workings,
+        tags: ['Asset Disposal'],
+        customFields: { 'Asset Description': null },
+        steps: [
+            journalStep(1, disposalJournal.description, disposalDate, disposalJournal.lines),
+            noteStep(2, `Update Jaz FA register: use POST /mark-as-sold/fixed-assets (if sold) or POST /discard-fixed-assets/:id (if scrapped).`, disposalDate),
+        ],
+    };
+    return {
+        type: 'asset-disposal',
+        currency: currency ?? null,
+        inputs: {
+            cost,
+            salvageValue,
+            usefulLifeYears,
+            acquisitionDate,
+            disposalDate,
+            proceeds,
+            method,
+        },
+        monthsHeld,
+        accumulatedDepreciation,
+        netBookValue,
+        gainOrLoss,
+        isGain,
+        disposalJournal,
+        blueprint,
+    };
+}

package/dist/calc/blueprint.js

@@ -10,7 +10,27 @@
 export function journalStep(stepNum, description, date, lines) {
     return { step: stepNum, action: 'journal', description, date, lines };
 }
-/** Build a note step (instruction, not a journal — e.g. "register fixed asset"). */
+/** Build a bill step (create supplier bill, e.g. prepaid expense). Lines show net accounting effect. */
+export function billStep(stepNum, description, date, lines) {
+    return { step: stepNum, action: 'bill', description, date, lines };
+}
+/** Build an invoice step (create customer invoice, e.g. deferred revenue). Lines show net accounting effect. */
+export function invoiceStep(stepNum, description, date, lines) {
+    return { step: stepNum, action: 'invoice', description, date, lines };
+}
+/** Build a cash-out step (cash disbursement, e.g. deposit placement). */
+export function cashOutStep(stepNum, description, date, lines) {
+    return { step: stepNum, action: 'cash-out', description, date, lines };
+}
+/** Build a cash-in step (cash receipt, e.g. deposit maturity). */
+export function cashInStep(stepNum, description, date, lines) {
+    return { step: stepNum, action: 'cash-in', description, date, lines };
+}
+/** Build a fixed-asset registration step (e.g. register ROU asset in FA module). */
+export function fixedAssetStep(stepNum, description, date = null) {
+    return { step: stepNum, action: 'fixed-asset', description, date, lines: [] };
+}
+/** Build a note step (instruction, not a journal — e.g. "update FA register"). */
 export function noteStep(stepNum, description, date = null) {
     return { step: stepNum, action: 'note', description, date, lines: [] };
 }
@@ -19,3 +39,8 @@ export function fmtCapsuleAmount(amount, currency) {
     const formatted = amount.toLocaleString('en-US', { minimumFractionDigits: 0, maximumFractionDigits: 0 });
     return currency ? `${currency} ${formatted}` : formatted;
 }
+/** Format a currency amount for workings text (e.g. "SGD 100,000.00"). */
+export function fmtAmt(amount, currency) {
+    const formatted = amount.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+    return currency ? `${currency} ${formatted}` : formatted;
+}

package/dist/calc/depreciation.js

@@ -11,7 +11,7 @@
  */
 import { round2 } from './types.js';
 import { validatePositive, validateNonNegative, validatePositiveInteger, validateSalvageLessThanCost } from './validate.js';
-import { journalStep } from './blueprint.js';
+import { journalStep, fmtAmt } from './blueprint.js';
 export function calculateDepreciation(inputs) {
     const { cost, salvageValue, usefulLifeYears, method = 'ddb', frequency = 'annual', currency, } = inputs;
     validatePositive(cost, 'Asset cost');
@@ -105,6 +105,16 @@ function buildStraightLineResult(cost, salvageValue, usefulLifeYears, depreciabl
         });
     }
     const blueprintSteps = schedule.map((row, idx) => journalStep(idx + 1, row.journal.description, row.date, row.journal.lines));
+    const c = currency ?? undefined;
+    const workings = [
+        `Straight-Line Depreciation Workings`,
+        `Cost: ${fmtAmt(cost, c)} | Salvage: ${fmtAmt(salvageValue, c)} | Depreciable base: ${fmtAmt(depreciableBase, c)}`,
+        `Useful life: ${usefulLifeYears} years | Frequency: ${frequency}`,
+        `Per ${frequency === 'monthly' ? 'month' : 'year'}: ${fmtAmt(perPeriod, c)}`,
+        `Total depreciation: ${fmtAmt(depreciableBase, c)}`,
+        `Method: (Cost − Salvage) ÷ Life = ${fmtAmt(depreciableBase, c)} ÷ ${totalPeriods} = ${fmtAmt(perPeriod, c)}`,
+        `Rounding: 2dp per period, final period closes to salvage value`,
+    ].join('\n');
     return {
         type: 'depreciation',
         currency: currency ?? null,
@@ -114,6 +124,7 @@ function buildStraightLineResult(cost, salvageValue, usefulLifeYears, depreciabl
         blueprint: {
             capsuleType: 'Depreciation',
             capsuleName: `SL Depreciation — ${usefulLifeYears} years`,
+            capsuleDescription: workings,
             tags: ['Depreciation'],
             customFields: { 'Asset ID': null },
             steps: blueprintSteps,
@@ -160,6 +171,17 @@ function buildDecliningSchedule(cost, salvageValue, usefulLifeYears, annualRate,
         });
     }
     const blueprintSteps = schedule.map((row, idx) => journalStep(idx + 1, row.journal.description, row.date, row.journal.lines));
+    const c = currency ?? undefined;
+    const methodLabel = method === 'ddb' ? 'Double Declining Balance' : '150% Declining Balance';
+    const ratePercent = round2(annualRate * 100);
+    const workings = [
+        `${methodLabel} Depreciation Workings`,
+        `Cost: ${fmtAmt(cost, c)} | Salvage: ${fmtAmt(salvageValue, c)} | Depreciable base: ${fmtAmt(depreciableBase, c)}`,
+        `Useful life: ${usefulLifeYears} years | Rate: ${ratePercent}% (${method === 'ddb' ? '2' : '1.5'} ÷ ${usefulLifeYears})`,
+        `Total depreciation: ${fmtAmt(depreciableBase, c)}`,
+        `Method: ${method.toUpperCase()} with auto switch to SL when SL ≥ declining or floor hit`,
+        `Rounding: 2dp per period, book value never falls below salvage`,
+    ].join('\n');
     return {
         type: 'depreciation',
         currency: currency ?? null,
@@ -169,6 +191,7 @@ function buildDecliningSchedule(cost, salvageValue, usefulLifeYears, annualRate,
         blueprint: {
             capsuleType: 'Depreciation',
             capsuleName: `${method.toUpperCase()} Depreciation — ${usefulLifeYears} years`,
+            capsuleDescription: workings,
             tags: ['Depreciation'],
             customFields: { 'Asset ID': null },
             steps: blueprintSteps,

package/dist/calc/ecl.js

@@ -15,7 +15,7 @@
  */
 import { round2 } from './types.js';
 import { validateNonNegative } from './validate.js';
-import { journalStep, fmtCapsuleAmount } from './blueprint.js';
+import { journalStep, fmtCapsuleAmount, fmtAmt } from './blueprint.js';
 export function calculateEcl(inputs) {
     const { buckets, existingProvision = 0, currency } = inputs;
     // Validate each bucket
@@ -61,9 +61,21 @@ export function calculateEcl(inputs) {
         };
     }
     // Blueprint
+    const c = currency ?? undefined;
+    const bucketWorkings = bucketDetails.map(b => `  ${b.bucket}: ${fmtAmt(b.balance, c)} × ${b.lossRate}% = ${fmtAmt(b.ecl, c)}`).join('\n');
+    const workings = [
+        `ECL Provision Matrix Workings (IFRS 9)`,
+        `Total receivables: ${fmtAmt(totalReceivables, c)} | Weighted avg loss rate: ${weightedRate}%`,
+        `Provision matrix:`,
+        bucketWorkings,
+        `Total ECL required: ${fmtAmt(totalEcl, c)} | Existing provision: ${fmtAmt(existingProvision, c)}`,
+        `Adjustment: ${fmtAmt(Math.abs(adjustmentRequired), c)} (${isIncrease ? 'increase' : 'release'})`,
+        `Method: IFRS 9.5.5.15 simplified approach — lifetime ECL, provision matrix`,
+    ].join('\n');
     const blueprint = {
         capsuleType: 'ECL Provision',
         capsuleName: `ECL Provision — ${fmtCapsuleAmount(totalEcl, currency)} — ${buckets.length} buckets`,
+        capsuleDescription: workings,
         tags: ['ECL', 'Bad Debt'],
         customFields: { 'Reporting Period': null, 'Aged Receivables Report Date': null },
         steps: [