jaz-cli 2.7.0 → 2.9.0

package/assets/skills/jobs/references/sg-tax/exemptions-and-rebates.md

@@ -0,0 +1,197 @@
+# Tax Exemptions and Rebates for SG Corporate Tax
+
+Singapore applies a flat 17% corporate income tax rate, but two exemption schemes reduce the effective rate for most SMBs. After the exemption, a CIT rebate may further reduce the tax payable depending on the Year of Assessment.
+
+---
+
+## 1. Start-Up Tax Exemption (SUTE)
+
+For newly incorporated companies in their first 3 Years of Assessment.
+
+| Item | Detail |
+|------|--------|
+| **Eligibility** | First 3 YAs of a newly incorporated SG company |
+| **Conditions** | <= 20 shareholders AND >= 1 individual shareholder holding >= 10% of shares |
+| **Band 1** | 75% exemption on first $100,000 of chargeable income |
+| **Band 2** | 50% exemption on next $100,000 of chargeable income |
+| **Maximum exemption** | $75,000 + $50,000 = **$125,000** per YA |
+
+### How the bands work
+
+Bands fill in order — Band 1 must be fully consumed before Band 2 applies.
+
+| Chargeable income | Band 1 exempt (75% of first $100K) | Band 2 exempt (50% of next $100K) | Total exempt | Taxable | Tax at 17% | Effective rate |
+|-------------------|------------------------------------|------------------------------------|-------------|---------|------------|---------------|
+| $50,000 | $37,500 | $0 | $37,500 | $12,500 | $2,125 | 4.25% |
+| $100,000 | $75,000 | $0 | $75,000 | $25,000 | $4,250 | 4.25% |
+| $150,000 | $75,000 | $25,000 | $100,000 | $50,000 | $8,500 | 5.67% |
+| $200,000 | $75,000 | $50,000 | $125,000 | $75,000 | $12,750 | **6.375%** |
+| $300,000 | $75,000 | $50,000 | $125,000 | $175,000 | $29,750 | 9.92% |
+| $500,000 | $75,000 | $50,000 | $125,000 | $375,000 | $63,750 | 12.75% |
+
+**Benchmark:** A company with $200,000 chargeable income under SUTE pays an effective rate of **6.375%** — less than half the headline 17%.
+
+### Input mapping
+
+```
+exemptionType: 'sute'
+```
+
+### SUTE conditions in detail
+
+Both conditions must be met throughout the basis period:
+
+1. **<= 20 shareholders** — all shareholders are individuals, OR a mix of individuals and corporate shareholders with at least one individual holding >= 10%
+2. **>= 1 individual holding >= 10%** — at least one natural person holds 10% or more of the issued ordinary shares
+
+Companies that are **investment holding companies** or **property development companies** are specifically excluded from SUTE, regardless of their incorporation date or shareholder structure.
+
+---
+
+## 2. Partial Tax Exemption (PTE)
+
+For all companies not on SUTE — the default exemption from Year 4 onwards.
+
+| Item | Detail |
+|------|--------|
+| **Eligibility** | All Singapore tax-resident companies not claiming SUTE |
+| **Conditions** | None — automatic |
+| **Band 1** | 75% exemption on first $10,000 of chargeable income |
+| **Band 2** | 50% exemption on next $190,000 of chargeable income |
+| **Maximum exemption** | $7,500 + $95,000 = **$102,500** per YA |
+
+### How the bands work
+
+| Chargeable income | Band 1 exempt (75% of first $10K) | Band 2 exempt (50% of next $190K) | Total exempt | Taxable | Tax at 17% | Effective rate |
+|-------------------|-----------------------------------|------------------------------------|-------------|---------|------------|---------------|
+| $10,000 | $7,500 | $0 | $7,500 | $2,500 | $425 | 4.25% |
+| $50,000 | $7,500 | $20,000 | $27,500 | $22,500 | $3,825 | 7.65% |
+| $100,000 | $7,500 | $45,000 | $52,500 | $47,500 | $8,075 | 8.08% |
+| $200,000 | $7,500 | $95,000 | $102,500 | $97,500 | $16,575 | **8.29%** |
+| $500,000 | $7,500 | $95,000 | $102,500 | $397,500 | $67,575 | 13.52% |
+| $1,000,000 | $7,500 | $95,000 | $102,500 | $897,500 | $152,575 | 15.26% |
+
+**Benchmark:** A company with $200,000 chargeable income under PTE pays an effective rate of **8.29%** — roughly half the headline rate.
+
+### Input mapping
+
+```
+exemptionType: 'pte'
+```
+
+---
+
+## 3. No Exemption
+
+In rare cases, a company may elect (or be required) to forgo exemptions.
+
+| Item | Detail |
+|------|--------|
+| **When** | Company elects out, or exemption conditions are not met (e.g., SUTE disqualification) |
+| **Rate** | Full 17% on entire chargeable income |
+
+### Input mapping
+
+```
+exemptionType: 'none'
+```
+
+---
+
+## 4. CIT Rebate (by Year of Assessment)
+
+After applying the exemption and computing gross tax at 17%, a CIT rebate may further reduce the tax payable. Rebates are announced in the annual Singapore Budget and vary by YA.
+
+**Formula:** `CIT rebate = min(gross tax x rebate rate, rebate cap)`
+
+| YA | Rebate Rate | Cap | Notes |
+|----|-------------|-----|-------|
+| 2020 | 25% | $15,000 | Budget 2020 |
+| 2021 | 0% | $0 | No CIT rebate (separate COVID relief measures) |
+| 2022 | 0% | $0 | No CIT rebate |
+| 2023 | 0% | $0 | No CIT rebate |
+| 2024 | 50% | $40,000 | Budget 2024 — Enterprise Support Package |
+| 2025 | 50% | $40,000 | Budget 2024 — extended |
+| 2026 | 40% | $40,000 | Budget 2025 |
+
+### How the rebate works
+
+The rebate is applied AFTER computing gross tax (chargeable income minus exemption, times 17%).
+
+**Example — YA 2026, PTE, $200,000 chargeable income:**
+
+```
+Chargeable income:      $200,000
+Less: PTE exemption:   ($102,500)
+Taxable income:          $97,500
+Gross tax (17%):         $16,575
+Less: CIT rebate:       ($6,630)   ← min($16,575 x 40%, $40,000) = min($6,630, $40,000)
+                        ──────────
+Net tax payable:          $9,945
+```
+
+Effective rate: $9,945 / $200,000 = **4.97%**
+
+### For YAs not in the schedule
+
+If the YA is not listed in the rebate schedule (e.g., YA 2027 and beyond), the rebate is $0. Check the latest Singapore Budget announcements for updates.
+
+---
+
+## Decision Tree for the Wizard
+
+Use this sequence during Phase 1 (Step 3) of the wizard workflow to determine the correct exemption type:
+
+```
+1. "When was the company incorporated?"
+   |
+   +-- YA <= incorporation year + 2?
+       |
+       +-- YES → SUTE-eligible (potentially)
+       |   |
+       |   +-- "Does the company have <= 20 shareholders,
+       |   |    with at least 1 individual holding >= 10%?"
+       |   |
+       |   +-- YES → exemptionType: 'sute'
+       |   +-- NO  → exemptionType: 'pte'
+       |
+       +-- NO → exemptionType: 'pte'
+```
+
+### Worked example: incorporation year determination
+
+| Incorporated | FY ending | YA | Year since incorporation | SUTE eligible? |
+|-------------|-----------|------|------------------------|----------------|
+| 2024 | 31 Dec 2024 | 2025 | Year 1 | Yes |
+| 2024 | 31 Dec 2025 | 2026 | Year 2 | Yes |
+| 2024 | 31 Dec 2026 | 2027 | Year 3 | Yes |
+| 2024 | 31 Dec 2027 | 2028 | Year 4 | No -> PTE |
+
+**Edge case — mid-year incorporation:** If a company was incorporated on 1 Jul 2024 with a Dec year-end, its first YA (2025) covers only 6 months (Jul-Dec 2024). The SUTE still applies for 3 YAs: 2025, 2026, 2027.
+
+---
+
+## SUTE vs PTE Comparison
+
+| Chargeable income | SUTE tax | SUTE eff. rate | PTE tax | PTE eff. rate | SUTE saves |
+|-------------------|----------|---------------|---------|---------------|------------|
+| $100,000 | $4,250 | 4.25% | $8,075 | 8.08% | $3,825 |
+| $200,000 | $12,750 | 6.38% | $16,575 | 8.29% | $3,825 |
+| $300,000 | $29,750 | 9.92% | $33,575 | 11.19% | $3,825 |
+| $500,000 | $63,750 | 12.75% | $67,575 | 13.52% | $3,825 |
+
+The absolute tax saving of SUTE over PTE is always **$3,825** regardless of income level (because the difference in exemption is $125,000 - $102,500 = $22,500, and $22,500 x 17% = $3,825). SUTE is worth claiming whenever eligible.
+
+---
+
+## Common Mistakes
+
+1. **Using PTE when SUTE applies.** SUTE saves $3,825 per year for 3 years = $11,475. Always check incorporation year.
+
+2. **Counting YAs wrong.** The YA is the year after the FY end, not the FY year itself. A company incorporated in 2024 with FY ending Dec 2024 has its first YA in 2025.
+
+3. **Forgetting SUTE shareholder conditions.** SUTE is not automatic for new companies — the shareholding conditions must be met. A startup with a single corporate shareholder (e.g., a wholly-owned subsidiary of a holding company with no individual shareholder) does not qualify.
+
+4. **Ignoring the CIT rebate.** For YA 2024-2026, the rebate is significant (40-50%, capped at $40K). On $200K chargeable income with PTE, the YA 2026 rebate saves $6,630 additional tax.
+
+5. **Applying the exemption to gross revenue instead of chargeable income.** The exemption applies to **chargeable income** (after all adjustments, CA, losses, and donations). A company with $5M revenue may still have chargeable income under $200K.

package/assets/skills/jobs/references/sg-tax/form-cs-fields.md

@@ -0,0 +1,191 @@
+# Form C-S / C-S Lite — Field Mapping
+
+Complete mapping of every field on the IRAS Form C-S and Form C-S Lite returns to the `jaz tax sg-cs` CLI output. Use this reference when populating the IRAS myTax Portal or verifying the computation output.
+
+**CLI:** `jaz tax sg-cs --input tax-data.json --json`
+
+---
+
+## Form C-S (18 Fields)
+
+The standard simplified corporate income tax return for companies with revenue of $5 million or below.
+
+### Section A: Revenue and Adjusted Profit
+
+| Box | IRAS Label | Data Type | CLI Output Field | Source / Formula |
+|-----|-----------|-----------|------------------|------------------|
+| **1** | Adjusted Profit / Loss | Dollar amount | `adjustedProfit` | `accountingProfit + totalAddBacks - totalDeductions` |
+| **2** | Total Revenue | Dollar amount | (from input) `revenue` | Total revenue line from P&L |
+
+**Box 1 detail:** The adjusted profit is the accounting profit AFTER tax adjustments (add-backs and further deductions) but BEFORE capital allowances, enhanced deductions, and loss relief. This is the key working number.
+
+**Box 2 detail:** Total revenue as reported in the financial statements. This determines C-S vs C-S Lite eligibility. It must match the top line of the P&L.
+
+### Section B: Capital Allowances
+
+| Box | IRAS Label | Data Type | CLI Output Field | Source / Formula |
+|-----|-----------|-----------|------------------|------------------|
+| **3** | Capital Allowances Claimed | Dollar amount | `capitalAllowanceClaim` | From CA schedule (current year claim) |
+| **4** | Balances of Unabsorbed Capital Allowances b/f | Dollar amount | (from input) `capitalAllowances.balanceBroughtForward` | Prior YA carry-forward |
+| **5** | Balances of Unabsorbed Capital Allowances c/f | Dollar amount | `unabsorbedCapitalAllowances` | `b/f + current year available - amount utilized` |
+
+### Section C: Losses
+
+| Box | IRAS Label | Data Type | CLI Output Field | Source / Formula |
+|-----|-----------|-----------|------------------|------------------|
+| **6** | Current Year Unabsorbed Losses | Dollar amount | Computed from adjusted loss | Only if Box 1 is a loss |
+| **7** | Balances of Unabsorbed Losses b/f | Dollar amount | (from input) `losses.broughtForward` | Prior YA carry-forward |
+| **8** | Balances of Unabsorbed Losses c/f | Dollar amount | `unabsorbedLosses` | `b/f + current year loss - amount utilized` |
+
+### Section D: Donations
+
+| Box | IRAS Label | Data Type | CLI Output Field | Source / Formula |
+|-----|-----------|-----------|------------------|------------------|
+| **9** | Donations — Qualifying Amount (250%) | Dollar amount | `donationRelief` | `addBacks.donations x 2.50` (IPC donations at 250%) |
+| **10** | Balances of Unabsorbed Donations b/f | Dollar amount | (from input) `donationsCarryForward.broughtForward` | Prior YA carry-forward (max 5 years) |
+| **11** | Balances of Unabsorbed Donations c/f | Dollar amount | `unabsorbedDonations` | `b/f + current year qualifying - amount utilized` |
+
+### Section E: Chargeable Income and Tax
+
+| Box | IRAS Label | Data Type | CLI Output Field | Source / Formula |
+|-----|-----------|-----------|------------------|------------------|
+| **12** | Chargeable Income | Dollar amount | `chargeableIncome` | `adjustedProfit - CA - enhanced deductions - loss relief - donation relief` (floored at 0) |
+| **13** | Exempt Amount | Dollar amount | `exemptAmount` | SUTE or PTE exemption applied to chargeable income |
+| **14** | Taxable Income (after exemption) | Dollar amount | `taxableIncome` | `chargeableIncome - exemptAmount` |
+| **15** | Gross Tax | Dollar amount | `grossTax` | `taxableIncome x 17%` |
+| **16** | CIT Rebate | Dollar amount | `citRebate` | `min(grossTax x rebateRate, rebateCap)` per YA schedule |
+| **17** | Net Tax Payable | Dollar amount | `netTaxPayable` | `grossTax - citRebate` (floored at 0) |
+| **18** | Is the company claiming Start-Up Tax Exemption? | Yes / No | `exemptionType` | `'sute'` = Yes, `'pte'` or `'none'` = No |
+
+---
+
+## Form C-S Lite (6 Fields)
+
+The ultra-simplified return for companies with revenue of $200,000 or below. Only 6 fields — no breakdown of CA, losses, or donations.
+
+| Box | IRAS Label | Data Type | CLI Output Field | Source / Formula |
+|-----|-----------|-----------|------------------|------------------|
+| **1** | Total Revenue | Dollar amount | (from input) `revenue` | Must be $200,000 or below |
+| **2** | Adjusted Profit / Loss | Dollar amount | `adjustedProfit` | Same as Form C-S Box 1 |
+| **3** | Chargeable Income | Dollar amount | `chargeableIncome` | After all deductions and relief |
+| **4** | Exempt Amount | Dollar amount | `exemptAmount` | SUTE or PTE |
+| **5** | Tax Payable | Dollar amount | `grossTax` | `(chargeableIncome - exemptAmount) x 17%` |
+| **6** | Net Tax Payable (after rebate) | Dollar amount | `netTaxPayable` | `grossTax - citRebate` |
+
+**C-S Lite simplification:** The taxpayer still performs the full computation (add-backs, CA, losses, donations) to arrive at chargeable income. They just don't need to report the intermediate steps on the form itself. The `jaz tax sg-cs` engine computes everything regardless — the `formType` field in the output indicates which form applies.
+
+---
+
+## CLI Output to IRAS Form — Quick Reference
+
+### Form C-S Mapping Table
+
+| CLI `formFields[].box` | CLI `formFields[].label` | IRAS Box |
+|------------------------|--------------------------|----------|
+| 1 | Adjusted Profit / Loss | Box 1 |
+| 2 | Total Revenue | Box 2 |
+| 3 | Capital Allowances Claimed | Box 3 |
+| 4 | Unabsorbed CA b/f | Box 4 |
+| 5 | Unabsorbed CA c/f | Box 5 |
+| 6 | Current Year Unabsorbed Losses | Box 6 |
+| 7 | Unabsorbed Losses b/f | Box 7 |
+| 8 | Unabsorbed Losses c/f | Box 8 |
+| 9 | Qualifying Donations (250%) | Box 9 |
+| 10 | Unabsorbed Donations b/f | Box 10 |
+| 11 | Unabsorbed Donations c/f | Box 11 |
+| 12 | Chargeable Income | Box 12 |
+| 13 | Exempt Amount | Box 13 |
+| 14 | Taxable Income | Box 14 |
+| 15 | Gross Tax | Box 15 |
+| 16 | CIT Rebate | Box 16 |
+| 17 | Net Tax Payable | Box 17 |
+| 18 | Claiming SUTE? | Box 18 |
+
+### Using the CLI Output
+
+The `--json` flag produces structured output with a `formFields` array. Each entry contains:
+
+```json
+{
+  "box": 1,
+  "label": "Adjusted Profit / Loss",
+  "value": 150000.00,
+  "source": "accountingProfit (200,000) + addBacks (80,000) - deductions (130,000)"
+}
+```
+
+The `source` field provides a human-readable explanation of how the value was derived. This is your audit trail.
+
+### Additional Output Fields (Not on the Form)
+
+The CLI output includes fields that are not directly on the IRAS form but are essential for the tax computation workpaper:
+
+| CLI Output Field | Purpose |
+|-----------------|---------|
+| `schedule` | Line-by-line tax computation schedule (the working paper) |
+| `totalAddBacks` | Sum of all add-back items |
+| `totalDeductions` | Sum of all further deductions |
+| `capitalAllowanceClaim` | CA utilized this YA |
+| `enhancedDeductionTotal` | Total enhanced deductions (R&D, IP, S14Q) |
+| `chargeableIncomeBeforeLosses` | Chargeable income before loss/donation relief |
+| `lossRelief` | Losses utilized this YA |
+| `donationRelief` | Donations relief utilized this YA (at 250%) |
+| `workings` | Human-readable narrative of the entire computation |
+
+---
+
+## Auto-Computed vs User-Provided
+
+Understanding which values the engine computes vs which the agent must supply:
+
+### User-Provided (via `SgFormCsInput`)
+
+| Field | What the Agent Must Supply |
+|-------|---------------------------|
+| `ya` | Year of Assessment |
+| `basisPeriodStart` / `basisPeriodEnd` | FY start and end dates |
+| `revenue` | Total revenue from P&L |
+| `accountingProfit` | Net profit/loss from P&L |
+| `addBacks.*` | Each add-back amount (13 categories) |
+| `deductions.*` | Each further deduction amount (4 categories) |
+| `capitalAllowances.currentYearClaim` | Total CA for this YA |
+| `capitalAllowances.balanceBroughtForward` | Unabsorbed CA from prior YAs |
+| `enhancedDeductions.*` | R&D, IP, donations base, S14Q |
+| `losses.broughtForward` | Unabsorbed losses from prior YAs |
+| `donationsCarryForward.broughtForward` | Unabsorbed donations from prior YAs |
+| `exemptionType` | `'sute'`, `'pte'`, or `'none'` |
+
+### Engine-Computed (in `SgFormCsResult`)
+
+| Field | How It Is Computed |
+|-------|-------------------|
+| `formType` | `'C-S Lite'` if revenue <= $200K, else `'C-S'` |
+| `eligible` | `true` if revenue <= $5M |
+| `adjustedProfit` | `accountingProfit + totalAddBacks - totalDeductions` |
+| `chargeableIncomeBeforeLosses` | `adjustedProfit - CA - enhancedDeductions` |
+| `chargeableIncome` | After loss and donation relief, floored at 0 |
+| `exemptAmount` | SUTE/PTE band calculation |
+| `taxableIncome` | `chargeableIncome - exemptAmount` |
+| `grossTax` | `taxableIncome x 17%` |
+| `citRebate` | Per YA schedule |
+| `netTaxPayable` | `grossTax - citRebate` |
+| `unabsorbedLosses` | Remaining losses carried forward |
+| `unabsorbedCapitalAllowances` | Remaining CA carried forward |
+| `unabsorbedDonations` | Remaining donations carried forward |
+| `schedule` | Full line-by-line computation |
+| `formFields` | Array of 18 (C-S) or 6 (C-S Lite) form field mappings |
+| `workings` | Narrative explanation |
+
+---
+
+## Practitioner Tips
+
+**Always verify `formType` before advising.** The engine sets `formType` based on revenue. If the output says `'C-S Lite'`, the user only needs to enter 6 fields on myTax Portal. If `'C-S'`, they need all 18.
+
+**Check `eligible` first.** If `eligible` is `false`, the company must file Form C (full) and should engage a tax agent. The computation is still valid as a working paper, but the simplified form cannot be used.
+
+**Box 1 is NOT accounting profit.** A common mistake is entering the P&L net profit directly into Box 1. Box 1 is the *adjusted* profit — after add-backs and deductions. The CLI computes this correctly; verify with the `workings` output.
+
+**Carry-forward balances are the agent's responsibility.** The engine is stateless. It does not know prior-year balances. Always ask the user: "Do you have any unabsorbed losses, capital allowances, or donations carried forward from previous years?"
+
+**Round to the nearest dollar for IRAS.** IRAS accepts whole-dollar amounts (no cents). The CLI rounds to 2 decimal places for precision; for the actual form filing, round each box to the nearest dollar.

package/assets/skills/jobs/references/sg-tax/ifrs16-tax-adjustment.md

@@ -0,0 +1,194 @@
+# IFRS 16 Lease Reversal for SG Tax
+
+One of the most misunderstood adjustments in Singapore corporate tax. Under IFRS 16 (effective 1 Jan 2019), lessees no longer distinguish between operating and finance leases on the balance sheet. All leases (except short-term and low-value) are recognized as a right-of-use (ROU) asset and a lease liability. This changes what appears on the P&L — and the tax treatment must reverse it.
+
+---
+
+## The Problem
+
+Under IFRS 16, the P&L shows two expenses for what used to be a single "rental expense":
+
+| IFRS 16 P&L line | Nature |
+|-------------------|--------|
+| **ROU asset depreciation** | Straight-line over the lease term (or useful life if shorter) |
+| **Interest on lease liability** | Front-loaded — higher in early years, declining over the lease term |
+
+**Neither of these is tax-deductible in Singapore.** IRAS does not follow IFRS 16 for tax purposes. Instead, the **actual operating lease payments** remain the deductible expense — exactly as they were before IFRS 16 existed.
+
+This means for every operating lease accounted under IFRS 16, you need three tax adjustments:
+
+1. **Add back** the ROU depreciation (not deductible)
+2. **Add back** the lease interest (not deductible)
+3. **Deduct** the actual lease payments (the real deductible expense)
+
+---
+
+## The Fix (3 Steps)
+
+### Step 1: Add back ROU depreciation
+
+Find the total ROU asset depreciation charged to the P&L during the basis period.
+
+**How to find it:**
+- Scan the trial balance for accounts containing "Right-of-Use", "ROU", or "Lease Asset"
+- The depreciation charge will be in an expense account, often under "Depreciation — ROU Assets" or similar
+- Cross-reference to the fixed asset summary if ROU assets are tracked there
+
+**Maps to:** `addBacks.rouDepreciation`
+
+### Step 2: Add back lease interest
+
+Find the total interest expense on lease liabilities charged to the P&L.
+
+**How to find it:**
+- Scan for accounts containing "Lease Interest", "Lease Liability Interest", or "IFRS 16 Interest"
+- This is separate from bank loan interest (which IS deductible)
+- May be grouped under "Finance Costs" on the P&L — drill into the GL to isolate lease interest from other interest
+
+**Maps to:** `addBacks.leaseInterest`
+
+### Step 3: Deduct actual lease payments
+
+Find the total cash payments made to lessors during the basis period.
+
+**How to find it:**
+- Scan bank/cash transactions for payments to the lessor
+- Or look at the lease liability account movement — the cash payment portion reduces the liability
+- Under IFRS 16 accounting, the payment is split: part reduces the lease liability (principal), part is interest expense. For tax, you deduct the **total payment** (principal + interest combined)
+
+```
+POST /api/v1/cashflow-transactions/search
+{
+  "filter": {
+    "chartOfAccountResourceId": { "eq": "<lease-liability-account-id>" },
+    "valueDate": { "between": ["2025-01-01", "2025-12-31"] }
+  },
+  "sort": { "sortBy": ["valueDate"], "order": "ASC" },
+  "limit": 1000
+}
+```
+
+Alternatively, if the company maintains a lease schedule, the total annual payment is simply: monthly payment x 12 (or per the lease agreement).
+
+**Maps to:** `deductions.actualLeasePayments`
+
+---
+
+## Net Effect
+
+The net tax adjustment for IFRS 16 is:
+
+```
+Net adjustment = (ROU depreciation + Lease interest) - Actual lease payments
+```
+
+- **Early years:** Interest is front-loaded under IFRS 16. The sum of ROU depreciation + interest **exceeds** the actual lease payment. Net effect: a positive add-back (increases taxable income slightly).
+- **Later years:** Interest declines. The sum of ROU depreciation + interest **is less than** the actual lease payment. Net effect: a net deduction (decreases taxable income slightly).
+- **Over the full lease term:** The total ROU depreciation + total interest = total lease payments. The cumulative net adjustment is zero. It is purely a timing difference.
+
+---
+
+## Worked Example
+
+**Scenario:** Office lease — $5,000/month, 36 months, 5% incremental borrowing rate (IBR).
+
+### IFRS 16 initial measurement
+
+```
+Monthly payment:     $5,000
+Lease term:          36 months
+IBR:                 5% per annum (0.4167% per month)
+PV of lease payments: $167,234.69 (this becomes both the ROU asset and lease liability)
+```
+
+**Calculator:** `jaz calc lease --payment 5000 --term 36 --rate 5 --json`
+
+### Year 1 (months 1-12)
+
+| Component | Amount |
+|-----------|--------|
+| ROU depreciation (straight-line over 36 months) | $55,744.90 ($167,234.69 / 3) |
+| Lease interest (front-loaded, per amortization schedule) | $7,306.74 |
+| **Total IFRS 16 P&L charge** | **$63,051.64** |
+| Actual lease payments (12 x $5,000) | $60,000.00 |
+| **Net tax adjustment (add-back)** | **$3,051.64** |
+
+### Tax adjustment entries for Year 1
+
+| Adjustment | Amount | Input field |
+|------------|--------|-------------|
+| Add back: ROU depreciation | $55,744.90 | `addBacks.rouDepreciation` |
+| Add back: Lease interest | $7,306.74 | `addBacks.leaseInterest` |
+| Deduct: Actual payments | $60,000.00 | `deductions.actualLeasePayments` |
+| **Net effect on taxable income** | **+$3,051.64** | (increases CI in early years) |
+
+### Year 2 (months 13-24)
+
+| Component | Amount |
+|-----------|--------|
+| ROU depreciation | $55,744.90 |
+| Lease interest (lower than Y1) | $4,620.03 |
+| **Total IFRS 16 P&L charge** | **$60,364.93** |
+| Actual lease payments | $60,000.00 |
+| **Net tax adjustment** | **$364.93** |
+
+### Year 3 (months 25-36)
+
+| Component | Amount |
+|-----------|--------|
+| ROU depreciation | $55,744.89 |
+| Lease interest (lowest year) | $1,820.76 |
+| **Total IFRS 16 P&L charge** | **$57,565.65** |
+| Actual lease payments | $60,000.00 |
+| **Net tax adjustment (deduction)** | **($2,434.35)** |
+
+### Cumulative check
+
+| | Year 1 | Year 2 | Year 3 | Total |
+|---|--------|--------|--------|-------|
+| ROU depreciation | 55,744.90 | 55,744.90 | 55,744.89 | 167,234.69 |
+| Lease interest | 7,306.74 | 4,620.03 | 1,820.76 | 13,747.53 |
+| IFRS 16 total | 63,051.64 | 60,364.93 | 57,565.65 | 180,982.22 |
+| Actual payments | 60,000.00 | 60,000.00 | 60,000.00 | 180,000.00 |
+| Net adjustment | +3,051.64 | +364.93 | -2,434.35 | +982.22 |
+
+The small residual ($982.22) is the interest cost difference — total lease payments of $180,000 vs PV of $167,234.69 means $12,765.31 total interest, which nets against $13,747.53 calculated interest (rounding across 36 periods). Over the full term the economic effect is equivalent.
+
+---
+
+## Questions for the Wizard
+
+Ask these in sequence during Phase 3 (Step 10-11 of the wizard workflow):
+
+1. **"Does the company have operating leases accounted under IFRS 16?"** If no, skip all three adjustments.
+
+2. **"What is the total ROU asset depreciation for the year?"** Record as `addBacks.rouDepreciation`.
+
+3. **"What is the total lease liability interest for the year?"** Record as `addBacks.leaseInterest`.
+
+4. **"What are the total actual lease payments made during the year?"** Record as `deductions.actualLeasePayments`. Verify with: `jaz calc lease --payment [monthly] --term [total months] --rate [IBR] --json` and check the Year N amortization.
+
+---
+
+## Short-Term and Low-Value Lease Exemptions
+
+IFRS 16 provides two optional exemptions where lessees can continue to recognize lease payments as expenses on a straight-line basis (i.e., the old treatment):
+
+| Exemption | Threshold | Tax effect |
+|-----------|-----------|------------|
+| **Short-term leases** | Lease term <= 12 months (no purchase option) | No IFRS 16 adjustment needed — the P&L expense IS the actual payment |
+| **Low-value leases** | Underlying asset value <= ~US$5,000 when new | Same — no adjustment needed |
+
+If the company has elected these exemptions for any leases, those leases do NOT need the three-step reversal. Only leases recognized under IFRS 16 (ROU asset + lease liability on balance sheet) need the adjustment.
+
+---
+
+## Common Mistakes
+
+1. **Adding back ROU depreciation but forgetting to deduct actual payments.** This overstates taxable income by the full lease payment amount. The three adjustments work as a set — never apply only one or two.
+
+2. **Including IFRS 16 lease interest in the general "depreciation" add-back.** Lease interest is a separate line item. It goes in `addBacks.leaseInterest`, not `addBacks.depreciation`.
+
+3. **Double-deducting lease payments.** If the company accounts for short-term/low-value leases as P&L expenses (not IFRS 16), those payments are already deducted in accounting profit. Do NOT add them to `deductions.actualLeasePayments` — that field is ONLY for IFRS 16 leases where the actual payment is not on the P&L.
+
+4. **Confusing ROU depreciation with regular fixed asset depreciation.** ROU assets are depreciated separately. Regular FA depreciation goes in `addBacks.depreciation`; ROU depreciation goes in `addBacks.rouDepreciation`. They are claimed differently — FA depreciation is replaced by capital allowances; ROU depreciation is replaced by actual lease payments.