jaz-cli 2.8.0 → 2.9.0

package/assets/skills/jobs/references/sg-tax/data-extraction.md

@@ -0,0 +1,408 @@
+# Data Extraction for SG CIT Computation
+
+Step-by-step guide to extracting the data you need from the Jaz API to build the `SgFormCsInput` JSON for `jaz tax sg-cs`. Each phase pulls specific data and maps it to input fields.
+
+**CLI:** `jaz tax sg-cs --input tax-data.json --json`
+
+---
+
+## Before You Start
+
+**Confirm the basis period.** The financial year determines which date ranges to use for every API call. Ask the user:
+- "What is your financial year-end?" (most SG companies: 31 December)
+- "What Year of Assessment are we computing for?"
+
+**Example:** YA 2026 with a Dec year-end means basis period = 1 Jan 2025 to 31 Dec 2025.
+
+**All API calls assume:**
+- `Authorization: Bearer <token>` header
+- `x-api-key: <key>` header
+- Base URL from the organization's Jaz instance
+- All dates in `YYYY-MM-DD` format
+
+---
+
+## Phase 1: Organization Context
+
+### Step 1: Get organization details
+
+```
+GET /api/v1/organization
+```
+
+**What to extract:**
+
+| Response Field | Maps To | Purpose |
+|---------------|---------|---------|
+| `data.currency` | `currency` input field | Confirm it is `SGD`. If not, FX considerations apply. |
+| `data.name` | Display only | Company name for the workpaper header |
+| `data.resourceId` | Internal reference | Needed for subsequent API calls |
+
+**Tip:** If the response `currency` is not SGD, the company may have multi-currency transactions. All tax computation must be in SGD — ensure all amounts are converted before feeding into the CLI.
+
+### Step 2: Confirm financial year dates
+
+The Jaz API does not expose financial year settings directly. Confirm the basis period dates with the user:
+
+```
+Input fields:
+  basisPeriodStart: "2025-01-01"
+  basisPeriodEnd:   "2025-12-31"
+  ya:               2026
+```
+
+---
+
+## Phase 2: Profit & Loss Report
+
+The P&L provides the two most important input fields: `revenue` and `accountingProfit`.
+
+### Step 3: Generate P&L for the basis period
+
+```
+POST /api/v1/generate-reports/profit-and-loss
+{
+  "primarySnapshotDate": "2025-12-31",
+  "secondarySnapshotDate": "2025-01-01"
+}
+```
+
+**What to extract:**
+
+| P&L Line | Maps To | Notes |
+|----------|---------|-------|
+| Total Revenue / Total Income | `revenue` | Top line — used for C-S eligibility check |
+| Net Profit / (Loss) | `accountingProfit` | Bottom line — starting point for tax computation. Use negative for a loss. |
+| Depreciation Expense | `addBacks.depreciation` | Always add back — first pass estimate before drilling into GL |
+| Interest Expense | Review for `addBacks.leaseInterest` | Only the IFRS 16 lease interest portion |
+| Other Expense lines | Scan for add-back candidates | Entertainment, donations, penalties, FX losses |
+| Dividend Income | `addBacks.exemptDividends` | SG one-tier dividends are exempt |
+| Interest Income | Review for taxability | Usually taxable under Section 10(1)(d) |
+
+**Important:** The P&L gives you summary totals. For add-back classification, you need transaction-level detail from the General Ledger (Phase 5). Use the P&L as a roadmap — identify which account lines need drill-down.
+
+### Step 4: Export P&L for records (optional)
+
+```
+POST /api/v1/data-exports/profit-and-loss
+{
+  "startDate": "2025-01-01",
+  "endDate": "2025-12-31"
+}
+```
+
+**Note:** The data export endpoint uses `startDate`/`endDate` field names, not the `primarySnapshotDate`/`secondarySnapshotDate` used by the report generator.
+
+---
+
+## Phase 3: Trial Balance
+
+The trial balance provides a cross-reference point and catches items that might not appear clearly on the P&L.
+
+### Step 5: Generate trial balance
+
+```
+POST /api/v1/generate-reports/trial-balance
+{
+  "startDate": "2025-01-01",
+  "endDate": "2025-12-31"
+}
+```
+
+**What to check:**
+
+| TB Account | Purpose |
+|-----------|---------|
+| Depreciation Expense | Must match P&L depreciation. If different, investigate. |
+| Accumulated Depreciation | Cross-reference to FA register (Phase 4) |
+| Provision accounts (ECL, warranty, restructuring) | Identify general provisions for add-back |
+| Unrealized FX Gain/Loss | May need to add back unrealized FX loss and deduct unrealized FX gain |
+| Donation accounts | Identify IPC donations for 250% claim |
+| Penalty/Fine accounts | Non-deductible — always add back |
+
+**Tip:** Look for balance sheet accounts with P&L impact — provisions that increased during the year indicate a general provision expense that may need to be added back.
+
+---
+
+## Phase 4: Fixed Asset Summary
+
+Fixed assets drive two key tax adjustments: depreciation add-back and capital allowance claims.
+
+### Step 6: Get FA summary
+
+```
+POST /api/v1/generate-reports/fixed-assets-summary
+```
+
+**What to extract:**
+
+| FA Data | Maps To | Notes |
+|---------|---------|-------|
+| Total depreciation charge for the period | `addBacks.depreciation` | Verify this matches the P&L depreciation line |
+| Asset list with cost, type, useful life | `capitalAllowances.assets[]` | Each asset needs classification by CA category |
+| Net book value per asset | Reference only | For the tax working paper |
+
+### Step 7: Get FA reconciliation (movements)
+
+```
+POST /api/v1/generate-reports/fixed-assets-recon-summary
+```
+
+This shows opening NBV, additions, disposals, depreciation, and closing NBV. Use the depreciation figure to confirm the P&L charge.
+
+### Step 8: Search fixed assets for per-item detail
+
+```
+POST /api/v1/fixed-assets/search
+{
+  "filter": { "status": { "eq": "ACTIVE" } },
+  "sort": { "sortBy": ["purchaseDate"], "order": "ASC" },
+  "limit": 1000
+}
+```
+
+**What to extract per asset:**
+
+| FA Field | Maps To (`CaAsset`) | Notes |
+|----------|---------------------|-------|
+| `name` | `description` | Asset description |
+| `purchaseAmount` | `cost` | Original cost |
+| `purchaseDate` | `acquisitionDate` | Date acquired |
+| `typeName` | Used to determine `category` | Map to: computer, automation, low-value, general, ip, renovation |
+| Prior years CA | `priorYearsClaimed` | User must provide — not stored in Jaz |
+
+**Mapping asset types to CA categories:** See `capital-allowances-guide.md` for the full classification guide. The key question for each asset: "Which ITA section applies?"
+
+---
+
+## Phase 5: General Ledger Drill-Down
+
+The GL provides transaction-level detail for accounts that need add-back classification. Do NOT pull the entire GL — target specific accounts identified in Phase 2.
+
+### Step 9: Drill into specific accounts
+
+```
+POST /api/v1/generate-reports/general-ledger
+{
+  "startDate": "2025-01-01",
+  "endDate": "2025-12-31",
+  "groupBy": "ACCOUNT"
+}
+```
+
+**Target these account categories:**
+
+| GL Account Keywords | Add-Back Category | What to Look For |
+|--------------------|--------------------|------------------|
+| "Depreciation", "Amortization" | `depreciation`, `amortization` | Full amount — always add back |
+| "Right-of-Use", "ROU" | `rouDepreciation` | IFRS 16 lease depreciation |
+| "Lease Interest", "Lease Liability" | `leaseInterest` | IFRS 16 interest on lease liability |
+| "Provision", "ECL", "Allowance" | `generalProvisions` | Only general (estimated) provisions — not specific write-offs |
+| "Donation" | `donations` | Confirm if to approved IPC recipients |
+| "Entertainment", "Meals" | `entertainment` | Non-deductible portion only |
+| "Penalty", "Fine", "Surcharge" | `penalties` | Always non-deductible |
+| "Motor Vehicle", "Car", "Parking" | `privateCar` | Only S-plated vehicles |
+| "Unrealized", "FX", "Foreign Exchange" | `unrealizedFxLoss` / `deductions.unrealizedFxGain` | Separate gains from losses |
+| "Dividend Income" | `exemptDividends` | SG one-tier dividends only |
+
+**Tip:** For large GLs, you may need to paginate. Check the response for pagination metadata and follow up with offset/limit parameters.
+
+### Step 10: Search for capital items on P&L
+
+Look for large one-off expenses that might be capital in nature but were expensed on the P&L:
+
+```
+POST /api/v1/generate-reports/general-ledger
+{
+  "startDate": "2025-01-01",
+  "endDate": "2025-12-31",
+  "groupBy": "ACCOUNT"
+}
+```
+
+Review expense accounts like "Miscellaneous Expenses", "Office Expenses", "Repairs & Maintenance" for items that:
+- Exceed $5,000 in a single transaction
+- Describe a new asset (e.g., "Purchase of air-conditioning unit")
+- Improve or extend the useful life of an existing asset
+
+These should be added back via `addBacks.capitalExpOnPnl` and may qualify for capital allowances.
+
+---
+
+## Phase 6: Transaction Search for Specific Items
+
+For specific line items that need verification, use the transaction search endpoints.
+
+### Step 11: Search invoices for revenue verification
+
+```
+POST /api/v1/invoices/search
+{
+  "filter": {
+    "status": { "eq": "POSTED" },
+    "valueDate": { "between": ["2025-01-01", "2025-12-31"] }
+  },
+  "sort": { "sortBy": ["valueDate"], "order": "ASC" },
+  "limit": 1000
+}
+```
+
+Use this to verify the `revenue` figure if the P&L total seems inconsistent with invoice volume.
+
+### Step 12: Search journals for specific adjustments
+
+```
+POST /api/v1/journals/search
+{
+  "filter": {
+    "valueDate": { "between": ["2025-01-01", "2025-12-31"] }
+  },
+  "sort": { "sortBy": ["valueDate"], "order": "ASC" },
+  "limit": 1000
+}
+```
+
+Manual journal entries often contain year-end adjustments (provisions, accruals, write-offs) that are relevant to add-back classification.
+
+### Step 13: Search for FX transactions
+
+```
+POST /api/v1/cashflow-transactions/search
+{
+  "filter": {
+    "businessTransactionType": { "eq": "FX_REVALUATION" },
+    "valueDate": { "between": ["2025-01-01", "2025-12-31"] }
+  },
+  "sort": { "sortBy": ["valueDate"], "order": "ASC" },
+  "limit": 1000
+}
+```
+
+FX revaluation journals create unrealized gains and losses. The loss portion maps to `addBacks.unrealizedFxLoss` and the gain portion maps to `deductions.unrealizedFxGain`.
+
+---
+
+## Handling Pagination
+
+All search endpoints support pagination. The standard pattern:
+
+```json
+{
+  "limit": 1000,
+  "offset": 0
+}
+```
+
+**Check the response metadata:**
+- If `totalCount` exceeds your `limit`, make additional requests incrementing `offset` by `limit`
+- Always aggregate totals across all pages before mapping to input fields
+- Do not assume a single page contains all results
+
+---
+
+## Building the Input JSON
+
+After completing all phases, assemble the `SgFormCsInput`:
+
+```json
+{
+  "ya": 2026,
+  "basisPeriodStart": "2025-01-01",
+  "basisPeriodEnd": "2025-12-31",
+  "currency": "SGD",
+  "revenue": 1200000.00,
+  "accountingProfit": 180000.00,
+  "addBacks": {
+    "depreciation": 45000.00,
+    "amortization": 0.00,
+    "rouDepreciation": 12000.00,
+    "leaseInterest": 3500.00,
+    "generalProvisions": 8000.00,
+    "donations": 5000.00,
+    "entertainment": 3200.00,
+    "penalties": 500.00,
+    "privateCar": 6000.00,
+    "capitalExpOnPnl": 0.00,
+    "unrealizedFxLoss": 2800.00,
+    "exemptDividends": 10000.00,
+    "otherNonDeductible": 0.00
+  },
+  "deductions": {
+    "actualLeasePayments": 14400.00,
+    "unrealizedFxGain": 1500.00,
+    "exemptIncome": 10000.00,
+    "otherDeductions": 0.00
+  },
+  "capitalAllowances": {
+    "currentYearClaim": 52000.00,
+    "balanceBroughtForward": 0.00,
+    "assets": [
+      {
+        "description": "MacBook Pro M3",
+        "cost": 4500.00,
+        "acquisitionDate": "2025-03-15",
+        "category": "computer",
+        "priorYearsClaimed": 0
+      },
+      {
+        "description": "Office Renovation",
+        "cost": 85000.00,
+        "acquisitionDate": "2024-06-01",
+        "category": "renovation",
+        "priorYearsClaimed": 28333.33
+      }
+    ]
+  },
+  "enhancedDeductions": {
+    "rdExpenditure": 0.00,
+    "rdMultiplier": 2.5,
+    "ipRegistration": 0.00,
+    "ipMultiplier": 2.0,
+    "donations250Base": 5000.00,
+    "s14qRenovation": 0.00
+  },
+  "losses": {
+    "broughtForward": 0.00
+  },
+  "donationsCarryForward": {
+    "broughtForward": 0.00
+  },
+  "exemptionType": "pte"
+}
+```
+
+---
+
+## Data Extraction Checklist
+
+| # | Step | Phase | API Endpoint | Input Fields Populated |
+|---|------|-------|-------------|----------------------|
+| 1 | Organization context | Org | `GET /organization` | `currency` |
+| 2 | Confirm FY dates | Org | User-provided | `ya`, `basisPeriodStart`, `basisPeriodEnd` |
+| 3 | P&L report | P&L | `POST /generate-reports/profit-and-loss` | `revenue`, `accountingProfit`, initial add-back estimates |
+| 4 | P&L export | P&L | `POST /data-exports/profit-and-loss` | Working paper backup |
+| 5 | Trial balance | TB | `POST /generate-reports/trial-balance` | Cross-reference all amounts |
+| 6 | FA summary | FA | `POST /generate-reports/fixed-assets-summary` | `addBacks.depreciation` verification |
+| 7 | FA reconciliation | FA | `POST /generate-reports/fixed-assets-recon-summary` | Depreciation charge confirmation |
+| 8 | FA search | FA | `POST /fixed-assets/search` | `capitalAllowances.assets[]` |
+| 9 | GL drill-down | GL | `POST /generate-reports/general-ledger` | All `addBacks.*` and `deductions.*` fields |
+| 10 | Capital items on P&L | GL | `POST /generate-reports/general-ledger` | `addBacks.capitalExpOnPnl` |
+| 11 | Invoice search | Txn | `POST /invoices/search` | `revenue` verification |
+| 12 | Journal search | Txn | `POST /journals/search` | Year-end adjustment review |
+| 13 | FX transactions | Txn | `POST /cashflow-transactions/search` | `addBacks.unrealizedFxLoss`, `deductions.unrealizedFxGain` |
+
+---
+
+## Practitioner Tips
+
+**Work top-down.** Start with the P&L summary (Phase 2) to identify which accounts are material. Only drill into the GL (Phase 5) for accounts that need classification. For a typical SMB with 20-30 expense accounts, you will drill into 5-8 accounts.
+
+**Depreciation is the easiest add-back.** Get it from the FA summary (Phase 4), verify it matches the P&L. This single item is often the largest add-back and requires zero judgment.
+
+**Ask the user for carry-forwards.** The Jaz API does not store prior-year tax computation data. You MUST ask: "Do you have any unabsorbed losses, capital allowances, or donations brought forward from previous YAs?" If they have a prior-year Form C-S or tax computation, the carry-forward figures are on that document.
+
+**IFRS 16 is a common gotcha.** If the company has operating leases accounted for under IFRS 16, the P&L will show ROU depreciation and lease interest instead of the actual lease payments. For tax purposes: add back the ROU depreciation (`addBacks.rouDepreciation`) and lease interest (`addBacks.leaseInterest`), then deduct the actual lease payments (`deductions.actualLeasePayments`). Ask: "Do you have any operating leases (office, equipment) accounted for under IFRS 16?"
+
+**Currency matters.** If the company's base currency in Jaz is SGD, all report figures are already in SGD. If the base currency is different (e.g., USD for a holding company), every amount must be converted to SGD at the appropriate exchange rate before building the input JSON.
+
+**Do not over-extract.** Pulling every single transaction is unnecessary and slow. The phased approach (P&L summary first, then targeted GL drill-down) is faster and produces the same result. Only go to Phase 6 (transaction search) if Phases 2-5 leave ambiguity.

package/assets/skills/jobs/references/sg-tax/enhanced-deductions.md

@@ -0,0 +1,248 @@
+# Enhanced Deductions for SG Corporate Tax
+
+Enhanced deductions allow companies to claim more than 100% of certain qualifying expenditures as tax deductions. The "base" 100% is already in the P&L (as an expense that reduces accounting profit). The "enhanced" portion is the uplift above 100% — this is the additional tax deduction that must be explicitly claimed.
+
+**Key concept:** The `enhancedDeductions` fields in `SgFormCsInput` capture only the **uplift portion** (the amount above the base 100%). The base is already reflected in accounting profit.
+
+---
+
+## 1. R&D Tax Deduction (S14C / S14E)
+
+Research and development expenditure qualifies for enhanced deductions under two schemes.
+
+### S14C — Standard R&D deduction (no pre-approval needed)
+
+| Item | Detail |
+|------|--------|
+| **Total deduction** | 250% of qualifying expenditure |
+| **Breakdown** | 100% (already in P&L) + 150% uplift |
+| **Pre-approval** | Not required |
+| **Eligible expenditure** | Staff costs, consumables, IP costs for R&D, outsourced R&D (to SG research institutions) |
+| **Cap** | None |
+
+### S14E — Enhanced R&D deduction (requires IRAS pre-approval)
+
+| Item | Detail |
+|------|--------|
+| **Total deduction** | 400% of qualifying expenditure |
+| **Breakdown** | 100% (already in P&L) + 300% uplift |
+| **Pre-approval** | Required — must be approved by IRAS before the R&D project starts |
+| **Eligible expenditure** | Same categories as S14C, but must meet additional innovation criteria |
+| **Cap** | None (but subject to IRAS approval of the specific project) |
+
+### What qualifies as R&D
+
+| Qualifying | NOT qualifying |
+|-----------|---------------|
+| Staff costs for R&D personnel | Market research or surveys |
+| Consumables used in R&D | Routine quality testing |
+| Payments to SG research institutions | Capital equipment purchases (claim CA instead) |
+| IP costs directly related to R&D | Product adaptation for individual customers |
+| Software development for new products | Maintenance of existing software |
+
+### Input mapping
+
+```
+enhancedDeductions.rdExpenditure = [qualifying R&D spend]
+enhancedDeductions.rdMultiplier = 2.5   (for S14C)
+                              or  4.0   (for S14E)
+```
+
+The computation engine calculates the uplift as: `rdExpenditure * (rdMultiplier - 1)`
+
+**Example:** $100,000 qualifying R&D under S14C:
+- Base deduction (in P&L): $100,000
+- Enhanced uplift (150%): $150,000
+- Total tax deduction: $250,000
+- Additional tax saving: $150,000 x 17% = $25,500
+
+### Questions for the wizard
+
+1. "Does the company perform research and development activities?"
+2. "How much was spent on qualifying R&D during the basis period? (Staff costs, consumables, outsourced R&D.)"
+3. "Is this under S14C (standard, 250%) or S14E (enhanced, 400%, requires pre-approval)?"
+4. "For S14E: has IRAS approval been obtained?"
+
+---
+
+## 2. IP Registration Costs (S14A)
+
+Intellectual property registration costs qualify for enhanced deduction.
+
+| Item | Detail |
+|------|--------|
+| **Total deduction** | 200% of qualifying costs (first $100,000 per YA) |
+| **Breakdown** | 100% (already in P&L) + 100% uplift |
+| **Alternative** | 400% if under the IP Development Incentive (IDI) scheme |
+| **Cap** | $100,000 of qualifying costs per YA (= max $100,000 uplift at 200%, or $300,000 uplift at 400%) |
+
+### What qualifies
+
+| Qualifying | NOT qualifying |
+|-----------|---------------|
+| Patent registration (SG or overseas) | Purchase of existing IP rights |
+| Trademark registration | IP licensing fees |
+| Registered design costs | Copyright (no registration in SG) |
+| Plant variety registration | Internal costs of developing the IP |
+
+### Input mapping
+
+```
+enhancedDeductions.ipRegistration = [qualifying IP costs, max $100,000]
+enhancedDeductions.ipMultiplier = 2.0   (standard)
+                              or  4.0   (IDI scheme)
+```
+
+The computation engine calculates the uplift as: `ipRegistration * (ipMultiplier - 1)`
+
+**Example:** $30,000 trademark and patent registration costs:
+- Base deduction (in P&L): $30,000
+- Enhanced uplift (100%): $30,000
+- Total tax deduction: $60,000
+- Additional tax saving: $30,000 x 17% = $5,100
+
+### Questions for the wizard
+
+1. "Did the company register any patents, trademarks, or designs during the basis period?"
+2. "What was the total cost of IP registration?"
+3. "Is this under the standard scheme (200%) or the IP Development Incentive (400%)?"
+
+---
+
+## 3. Donation Deductions (S37)
+
+Donations to approved Institutions of a Public Character (IPCs) qualify for a 250% tax deduction.
+
+| Item | Detail |
+|------|--------|
+| **Total deduction** | 250% of qualifying donations |
+| **Breakdown** | 100% (added back from P&L) + 250% claimed as donation relief |
+| **Eligible donations** | Cash donations to approved IPCs |
+| **Cap** | None per YA |
+| **Carry-forward** | Unused donations can be carried forward up to 5 years (FIFO) |
+
+### How donations work in the computation
+
+Donations are handled differently from R&D and IP because they are set off **after** loss relief, not in the enhanced deductions step:
+
+1. **Add-back:** The donation expense is added back to accounting profit (it's in the P&L, but the deduction comes later at 250%)
+2. **Enhanced deduction step:** The uplift portion (250% - 100% = 150%) is claimed here as `donations250Base * 1.5`
+3. **Donation relief step:** The full 250% amount is set off against chargeable income after loss relief
+
+**Important:** The `addBacks.donations` and `enhancedDeductions.donations250Base` fields must contain the same amount (the base donation amount). The computation engine handles the 250% multiplier and the correct set-off order.
+
+### Input mapping
+
+```
+addBacks.donations = [total IPC donations]
+enhancedDeductions.donations250Base = [same amount as addBacks.donations]
+```
+
+**Example:** $10,000 cash donation to approved IPC:
+- Add-back: $10,000 (removes the P&L expense)
+- Donation relief: $10,000 x 250% = $25,000 (claimed after loss relief)
+- Net tax benefit: $25,000 x 17% = $4,250
+- Effective tax saving per dollar donated: 42.5 cents
+
+### Carry-forward rules
+
+- Unused donation deductions carry forward up to **5 years**
+- Used on a **FIFO basis** (oldest donations used first)
+- Subject to the same shareholding test as loss carry-forwards (>= 50% continuity)
+- Input: `donationsCarryForward.broughtForward` (total from prior years, not yet used)
+
+### Questions for the wizard
+
+1. "Were any donations made to approved IPCs during the basis period?"
+2. "What was the total donation amount?"
+3. "Does the company have any unused donation deductions from prior years? If so, how much and from which YA?"
+
+---
+
+## 4. Renovation & Refurbishment Deduction (S14Q)
+
+Renovation costs for business premises qualify for a special deduction spread over 3 years.
+
+| Item | Detail |
+|------|--------|
+| **Total deduction** | 100% of qualifying costs over 3 years (33.33% per year) |
+| **Cap** | $300,000 per rolling 3-year period |
+| **Claimed via** | Capital allowances schedule (category: `renovation`, section S14Q) |
+| **Enhanced uplift** | Only if there is a net uplift above what is already claimed via CA |
+
+### What qualifies
+
+| Qualifying | NOT qualifying |
+|-----------|---------------|
+| General renovation of business premises | New construction or building extension |
+| Electrical wiring, plumbing | Land and structural improvements to property |
+| Flooring, wall finishes, painting | Purchase of furniture or equipment (use CA instead) |
+| Built-in furniture (e.g., reception desk) | Renovation of residential property |
+| Signage and window displays | Motor vehicle modifications |
+| Doors, windows, partitions | Landscaping |
+
+### How S14Q works in the computation
+
+S14Q renovation costs are primarily claimed through the **capital allowances schedule** — each qualifying renovation cost is entered as a `CaAsset` with `category: 'renovation'`. The CA engine computes the 33.33% annual claim.
+
+The `enhancedDeductions.s14qRenovation` field captures only the **net uplift** — the portion of the S14Q deduction that is not already reflected in the CA schedule. In most cases, this is zero because the full deduction flows through the CA schedule.
+
+Use the uplift field when renovation costs were expensed on the P&L (instead of capitalized) and you need to capture the additional deduction above what the CA schedule provides.
+
+### Input mapping
+
+For capitalized renovation (the normal case):
+```
+capitalAllowances.assets = [
+  {
+    description: "Office renovation - FY2025",
+    cost: 120000,
+    acquisitionDate: "2025-03-15",
+    category: "renovation",
+    priorYearsClaimed: 0
+  }
+]
+enhancedDeductions.s14qRenovation = 0  (already in CA schedule)
+```
+
+For expensed renovation (unusual):
+```
+enhancedDeductions.s14qRenovation = [net uplift amount]
+```
+
+### 3-year rolling cap
+
+The $300,000 cap applies per **rolling 3-year period**, not per YA. If the company spent $200,000 in Year 1, only $100,000 of new renovation in Years 2-3 qualifies. The AI agent should ask about prior year renovation claims to check the cap.
+
+### Questions for the wizard
+
+1. "Did the company incur renovation or refurbishment costs for business premises during the basis period?"
+2. "What was the total renovation cost? Was it capitalized as a fixed asset or expensed on the P&L?"
+3. "Were any renovation claims made in the prior 2 years? (To check the $300,000 rolling cap.)"
+
+---
+
+## Summary: Enhanced Deduction Input Fields
+
+| Scheme | Input field | Multiplier field | Default | Uplift formula |
+|--------|------------|-----------------|---------|----------------|
+| R&D (S14C) | `enhancedDeductions.rdExpenditure` | `rdMultiplier` | 2.5 | expenditure x (2.5 - 1) = 150% |
+| R&D (S14E) | `enhancedDeductions.rdExpenditure` | `rdMultiplier` | 4.0 | expenditure x (4.0 - 1) = 300% |
+| IP (S14A) | `enhancedDeductions.ipRegistration` | `ipMultiplier` | 2.0 | costs x (2.0 - 1) = 100% |
+| IP (IDI) | `enhancedDeductions.ipRegistration` | `ipMultiplier` | 4.0 | costs x (4.0 - 1) = 300% |
+| Donations (S37) | `enhancedDeductions.donations250Base` | (fixed 250%) | n/a | base x 1.5 (enhanced step) |
+| Renovation (S14Q) | `enhancedDeductions.s14qRenovation` | (net uplift) | n/a | typically 0 (flows via CA) |
+
+---
+
+## Common Mistakes
+
+1. **Claiming the full 250% R&D deduction as an add-back.** The base 100% is already in the P&L. Only the uplift (150% or 300%) is the enhanced deduction. If you also add back the R&D expense, you've effectively claimed 350% or 500%.
+
+2. **Not matching donations in add-backs and enhanced deductions.** `addBacks.donations` and `enhancedDeductions.donations250Base` must be the same amount. The add-back removes the P&L expense; the donation relief step claims the full 250%.
+
+3. **Exceeding the IP registration cap.** Only the first $100,000 of qualifying IP costs per YA qualifies. If the company spent $150,000, only $100,000 goes into `enhancedDeductions.ipRegistration`.
+
+4. **Forgetting the S14Q rolling cap.** The $300,000 cap spans 3 years. If $250,000 was claimed in Year 1, only $50,000 of new renovation qualifies in Years 2-3.
+
+5. **Claiming S14E without pre-approval.** The 400% R&D deduction requires IRAS pre-approval BEFORE the project starts. Without it, only S14C (250%) applies.