jaz-cli 2.3.0 → 2.6.0

package/assets/skills/transaction-recipes/references/fixed-deposit.md

@@ -0,0 +1,164 @@
+# Recipe: Fixed Deposit
+
+## Scenario
+
+Your company places $100,000 in a 12-month fixed deposit at 3.5% annual interest. Under IFRS 9, this is classified as a financial asset at amortized cost (hold-to-collect business model, passes the SPPI test — solely payments of principal and interest). Interest is accrued monthly using the effective interest rate method and recognized in profit or loss. At maturity, the bank returns the principal plus accumulated interest.
+
+**Pattern:** Manual journals + capsule (monthly accrual, single maturity settlement)
+
+---
+
+## Accounts Involved
+
+| Account | Type | Subtype | Role |
+|---|---|---|---|
+| Fixed Deposit | Asset | Current Asset | Carries the principal for the deposit term |
+| Accrued Interest Receivable | Asset | Current Asset | Accumulates monthly interest accruals |
+| Interest Income | Revenue | Other Income | P&L recognition of interest earned |
+| Cash / Bank Account | Asset | Bank | Outflow on placement, inflow at maturity |
+
+---
+
+## Journal Entries
+
+### Step 1: Placement (Day 1) — cash-out
+
+Record the transfer from operating account to the fixed deposit. This is a **cash-out** entry in Jaz (cash leaves the bank account):
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Fixed Deposit | $100,000 | |
+| 2 | Cash / Bank Account | | $100,000 |
+
+> In Jaz, record this via the bank module (match the outgoing bank feed entry) or as a manual journal.
+
+### Step 2: Monthly Interest Accrual (each month)
+
+**Simple interest (default):** Equal monthly accrual amount.
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Accrued Interest Receivable | $291.67 | |
+| 2 | Interest Income | | $291.67 |
+
+**Calculation:**
+- Annual interest = $100,000 × 3.5% = $3,500
+- Monthly accrual = $3,500 / 12 = $291.67
+
+**Compound interest:** Interest is calculated on the carrying amount (principal + previously accrued interest) using the effective interest rate. Each month's accrual is slightly higher than the last. Use `jaz calc fixed-deposit --principal 100000 --rate 3.5 --term 12 --compound monthly` to generate the exact schedule.
+
+### Step 3: Maturity (final day) — cash-in
+
+Principal plus accrued interest returns to the bank account. This is a **cash-in** entry in Jaz (cash arrives in the bank account):
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Cash / Bank Account | $103,500 | |
+| 2 | Fixed Deposit | | $100,000 |
+| 3 | Accrued Interest Receivable | | $3,500 |
+
+> After this entry, Fixed Deposit and Accrued Interest Receivable both zero out. The net P&L impact is $3,500 of Interest Income recognized over the 12 months. In Jaz, record via the bank module (match the incoming bank feed entry) or as a manual journal.
+
+---
+
+## Capsule Structure
+
+**Capsule:** "Fixed Deposit — DBS — 2025"
+**Capsule Type:** "Fixed Deposit"
+
+Contents:
+- 1 placement journal
+- 12 monthly interest accrual journals
+- 1 maturity journal
+- **Total entries:** 14
+
+The CLI generates a `capsuleDescription` field with full workings — including the interest calculation method, per-period accrual amounts, and maturity value — so the capsule is self-documenting.
+
+---
+
+## Worked Example
+
+**Deposit terms:**
+- Principal: $100,000
+- Annual rate: 3.5%
+- Term: 12 months (simple interest)
+- Monthly accrual: $100,000 × 3.5% / 12 = $291.67
+- Total interest: $3,500.00
+- Maturity value: $103,500.00
+
+**CLI command:**
+```
+jaz calc fixed-deposit --principal 100000 --rate 3.5 --term 12 --currency SGD
+```
+
+### Accrual Schedule (first 3 months + last month)
+
+| Month | Accrual Amount | Cumulative Interest | Accrued Interest Receivable |
+|---|---|---|---|
+| 1 | $291.67 | $291.67 | $291.67 |
+| 2 | $291.67 | $583.34 | $583.34 |
+| 3 | $291.67 | $875.01 | $875.01 |
+| ... | ... | ... | ... |
+| 12 | $291.63* | $3,500.00 | $3,500.00 |
+
+> *Final month adjusted by $0.04 to close the balance exactly to $3,500.00 (rounding correction).
+
+**Month 1 journal entry:**
+- Dr Accrued Interest Receivable $291.67
+- Cr Interest Income $291.67
+- Description: "FD interest accrual — Month 1 of 12 (DBS)"
+- Assign to capsule
+
+**Month 3 journal entry:**
+- Dr Accrued Interest Receivable $291.67
+- Cr Interest Income $291.67
+- Description: "FD interest accrual — Month 3 of 12 (DBS)"
+- Assign to capsule
+
+**Maturity journal entry:**
+- Dr Cash $103,500.00
+- Cr Fixed Deposit $100,000.00
+- Cr Accrued Interest Receivable $3,500.00
+- Description: "FD maturity — principal + interest received (DBS)"
+- Assign to capsule
+
+**Totals over 12 months:**
+- Total interest income: $3,500.00
+- Net cash impact: −$100,000 at placement, +$103,500 at maturity = +$3,500
+
+---
+
+## Enrichment Suggestions
+
+| Enrichment | Value | Why |
+|---|---|---|
+| Tracking Tag | "Fixed Deposit" | Filter all FD-related transactions in reports |
+| Nano Classifier | Instrument → "Term Deposit" | Distinguish from savings accounts or money market funds |
+| Custom Field | "Deposit Reference" → "TD-2025-001" | Record the bank's deposit certificate number |
+| Custom Field | "Bank Name" → "DBS" | Identify the issuing bank for multi-bank portfolios |
+
+Set the tag and nano classifier on each accrual journal. Custom fields go on the placement journal (the capsule groups everything together).
+
+---
+
+## Verification
+
+1. **Accrued Interest Receivable should accumulate monthly** → Trial Balance at month 6 should show $1,750.02 (6 × $291.67). The balance grows each month until maturity.
+2. **Interest Income P&L line = total accrual to date** → P&L at any date should equal the sum of accrual entries posted up to that date.
+3. **At maturity, Fixed Deposit account zeros out** → After the maturity journal, Fixed Deposit balance = $0 and Accrued Interest Receivable balance = $0.
+4. **Cash flow: Cash decreased by principal on placement, increased by maturity value at end** → Net cash movement over the 12 months = +$3,500 (the interest earned).
+5. **Group General Ledger by Capsule** → "Fixed Deposit — DBS — 2025" should show all 14 entries. Fixed Deposit nets to $0 and Interest Income totals $3,500.
+
+---
+
+## Variations
+
+**Compound interest:** Use `jaz calc fixed-deposit --principal 100000 --rate 3.5 --term 12 --compound monthly` to generate a schedule where each month's interest is calculated on the carrying amount (principal + accrued interest to date). Total interest will be slightly higher than simple interest ($3,556.46 vs $3,500.00 for monthly compounding). The effective interest rate method applies the same logic — each period's income = carrying amount × periodic rate.
+
+**FX-denominated deposit:** If the deposit is in USD but your base currency is SGD, record the placement journal with `currency: { sourceCurrency: "USD" }`. Monthly accruals should use the spot rate at each month-end. At maturity, any difference between the cumulative translated amounts and the actual SGD received is an FX gain/loss. Cross-reference the fx-revaluation recipe for month-end revaluation of the outstanding balance.
+
+**Premature withdrawal:** The bank may impose a penalty (reduced interest rate or flat fee). Record the maturity journal with the reduced interest amount. If interest already accrued exceeds the actual payout, reverse the excess: Dr Interest Income / Cr Accrued Interest Receivable. Note the penalty in the journal description.
+
+**Auto-rollover:** When the bank automatically rolls over the deposit at maturity, close the original capsule with a maturity journal (Dr Fixed Deposit New / Cr Fixed Deposit Old + Cr Accrued Interest Receivable), then create a new capsule for the rolled deposit. The new principal may include the prior interest if the bank compounds on rollover.
+
+**PH withholding tax (20% final WHT on interest income):** In jurisdictions that withhold tax on interest at source, the maturity cash received is net of WHT. Record: Dr Cash (net) + Dr WHT Receivable or Tax Expense / Cr Fixed Deposit + Cr Accrued Interest Receivable. This variation is deferred to a future recipe update.

package/assets/skills/transaction-recipes/references/fx-revaluation.md

@@ -0,0 +1,135 @@
+# Recipe: FX Revaluation — Non-AR/AP Items (IAS 21)
+
+## Scenario
+
+Your Singapore company (base currency SGD) has a USD 50,000 intercompany loan receivable from a subsidiary, originally booked at a rate of 1.35 (SGD 67,500). At the December 31 reporting date, the USD/SGD closing rate is 1.38. IAS 21.23 requires all monetary items translated at the closing rate, so you post a revaluation journal to recognize the unrealized FX gain, then reverse it on Day 1 of the next period.
+
+**Pattern:** Manual journals + capsule (revaluation journal + Day 1 reversal, repeated each period-end)
+
+**When this recipe applies:**
+- Intercompany loan receivables/payables booked as manual journals (not invoices/bills)
+- Foreign currency term deposits or escrow outside bank accounts
+- FX-denominated provisions (e.g., USD warranty obligation)
+- Any manual journal balance in a non-AR/AP, non-cash foreign currency account
+
+**When this recipe does NOT apply — the platform handles it automatically:**
+- Invoices, bills, customer/supplier credit notes (auto-revalued)
+- Cash and bank account balances (auto-revalued)
+
+---
+
+## Accounts Involved
+
+| Account | Type | Subtype | Role |
+|---|---|---|---|
+| [Source Account] | Asset or Liability | Varies | The FX monetary item being revalued |
+| FX Unrealized Gain | Revenue | Other Income | Holds gains when closing rate > book rate |
+| FX Unrealized Loss | Expense | Other Expense | Holds losses when closing rate < book rate |
+
+> **Note:** Jaz auto-creates FX gain/loss/rounding accounts when FX features are enabled. Use the platform-created accounts — do not create duplicates.
+
+---
+
+## Journal Entries
+
+### Step 1: Revaluation Journal (period-end)
+
+Calculate the unrealized gain or loss:
+
+```
+Gain/Loss = Foreign Amount × (Closing Rate − Book Rate)
+```
+
+**If gain (closing rate > book rate):**
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | [Source Account] | *gain amount* | |
+| 2 | FX Unrealized Gain | | *gain amount* |
+
+**If loss (closing rate < book rate):**
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | FX Unrealized Loss | *loss amount* | |
+| 2 | [Source Account] | | *loss amount* |
+
+### Step 2: Reversal Journal (Day 1 of next period)
+
+Post the exact opposite of Step 1. This ensures the next period starts clean — the FX impact is recognized in the correct period only.
+
+---
+
+## Capsule Structure
+
+**Capsule:** "FX Revaluation — Non-AR/AP — Dec 2025"
+**Capsule Type:** "FX Revaluation"
+
+Contents:
+- 1 revaluation journal (period-end)
+- 1 reversal journal (Day 1 of next period)
+- **Total entries:** 2 per period
+
+For ongoing monthly revaluations, create one capsule per quarter or fiscal year (e.g., "FX Reval — FY2025") containing all months' reval/reversal pairs.
+
+---
+
+## Worked Example
+
+**Setup:**
+- Intercompany loan receivable: USD 50,000
+- Book rate (at original booking): 1.35 SGD/USD
+- Book value: SGD 67,500
+- Closing rate (Dec 31): 1.38 SGD/USD
+- Closing value: SGD 69,000
+
+**Calculation:**
+```
+Gain = USD 50,000 × (1.38 − 1.35) = USD 50,000 × 0.03 = SGD 1,500
+```
+
+**Dec 31, 2025 — Revaluation journal:**
+- Dr Intercompany Loan Receivable SGD 1,500
+- Dr/Cr FX Unrealized Gain SGD 1,500
+- Description: "FX revaluation — USD 50,000 @ 1.38 (was 1.35)"
+- Assign to capsule
+
+**Jan 1, 2026 — Reversal journal:**
+- Dr FX Unrealized Gain SGD 1,500
+- Cr Intercompany Loan Receivable SGD 1,500
+- Description: "Reversal of FX revaluation — USD 50,000"
+- Assign to same capsule
+
+**Use the calculator:** `jaz calc fx-reval --amount 50000 --book-rate 1.35 --closing-rate 1.38 --currency USD --base-currency SGD`
+
+---
+
+## Enrichment Suggestions
+
+| Enrichment | Value | Why |
+|---|---|---|
+| Tracking Tag | "FX Revaluation" | Filter all reval entries in GL |
+| Tracking Tag | "USD" | Filter by currency for multi-currency reval |
+| Custom Field | "Source Account" → "Intercompany Loan — SubCo" | Identify the item being revalued |
+| Custom Field | "Period End Date" → "2025-12-31" | Link to reporting period |
+
+---
+
+## Verification
+
+1. **Group General Ledger by Capsule** → Reval + reversal should net to zero across both entries.
+2. **Trial Balance at Dec 31** → Intercompany Loan Receivable shows SGD 69,000 (original 67,500 + 1,500 reval). FX Unrealized Gain shows SGD 1,500 credit.
+3. **Trial Balance at Jan 1 (after reversal)** → Intercompany Loan Receivable back to SGD 67,500. FX Unrealized Gain cleared.
+4. **P&L for December** → FX Unrealized Gain of SGD 1,500 recognized in the correct period.
+
+---
+
+## Variations
+
+**Multiple FX items:** If you have several non-AR/AP FX balances (e.g., USD loan + EUR deposit + JPY provision), you can combine them into a single multi-line revaluation journal. Each pair of lines handles one item. All in the same capsule.
+
+**Loss scenario:** If the closing rate is lower than the book rate, the journal debits FX Unrealized Loss instead of crediting FX Unrealized Gain. The reversal mirrors accordingly.
+
+**No reversal method:** Some firms keep the reval in place and adjust the book rate for the next period. This avoids the reversal journal but requires updating the "book rate" each period. The reversal method shown here is more conservative and widely used.
+
+**Quarterly vs. monthly:** Reval can be done monthly or quarterly depending on materiality. For material FX exposures, monthly is recommended (IAS 21 does not prescribe frequency — it's a reporting date requirement).

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/assets/skills/transaction-recipes/references/intercompany.md

@@ -0,0 +1,150 @@
+# Recipe: Intercompany Transactions
+
+## Scenario
+
+Your Singapore holding company (Entity A) provides management services to its Malaysian subsidiary (Entity B) at $15,000 per month. Both entities are on Jaz. At month-end, Entity A invoices Entity B, and each entity records mirrored journal entries. A capsule in each entity tracks the full intercompany lifecycle — charges, settlements, and reconciliation.
+
+**Pattern:** Manual journals mirrored in two entities + capsule in each entity
+
+---
+
+## Accounts Involved
+
+### Entity A (Service Provider)
+
+| Account | Type | Subtype | Role |
+|---|---|---|---|
+| Intercompany Receivable — Entity B | Asset | Current Asset | Amount owed by Entity B |
+| Management Fee Income | Revenue | Revenue | Service charge recognized |
+| Cash / Bank Account | Asset | Bank | Receives settlement payment |
+
+### Entity B (Service Recipient)
+
+| Account | Type | Subtype | Role |
+|---|---|---|---|
+| Intercompany Payable — Entity A | Liability | Current Liability | Amount owed to Entity A |
+| Management Fee Expense | Expense | Expense | Service charge incurred |
+| Cash / Bank Account | Asset | Bank | Sends settlement payment |
+
+---
+
+## Journal Entries
+
+### Step 1: Service Charge (Entity A — Provider)
+
+**Option A — Invoice:** Create an invoice from Entity A to Entity B (preferred if you want AR aging and payment tracking):
+- Invoice: $15,000 to "Entity B" contact
+- Coded to Management Fee Income
+- Assign to capsule
+
+**Option B — Manual journal:** If you want to bypass AR/AP:
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Intercompany Receivable — Entity B | $15,000 | |
+| 2 | Management Fee Income | | $15,000 |
+
+### Step 2: Corresponding Entry (Entity B — Recipient)
+
+**Option A — Bill:** Create a bill from Entity A in Entity B's books:
+- Bill: $15,000 from "Entity A" contact
+- Coded to Management Fee Expense
+- Assign to capsule
+
+**Option B — Manual journal:**
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Management Fee Expense | $15,000 | |
+| 2 | Intercompany Payable — Entity A | | $15,000 |
+
+### Step 3: Settlement (cash transfer)
+
+**Entity A (receives cash):**
+- Record receipt against the invoice, or:
+- Dr Cash / Cr Intercompany Receivable — Entity B
+
+**Entity B (sends cash):**
+- Record payment against the bill, or:
+- Dr Intercompany Payable — Entity A / Cr Cash
+
+---
+
+## Capsule Structure
+
+**Entity A Capsule:** "Intercompany — Q1 2025 — Entity A → Entity B"
+**Entity B Capsule:** "Intercompany — Q1 2025 — Entity A → Entity B"
+**Capsule Type:** "Intercompany"
+
+Contents per entity:
+- 3 monthly charge entries (invoices/bills or journals)
+- Settlement entries
+- **Total entries per entity:** 4-6 per quarter
+
+---
+
+## Worked Example
+
+**Setup:**
+- Management fee: $15,000/month
+- Entities: Entity A (Singapore) and Entity B (Malaysia)
+- Quarter: Q1 2025 (Jan, Feb, Mar)
+
+**Jan 31 — Entity A:**
+- Create invoice: $15,000 to Entity B
+- Code to Management Fee Income
+- Capsule: "Intercompany — Q1 2025 — Entity A → Entity B"
+- Custom field: "Intercompany Ref" → "IC-2025-001"
+
+**Jan 31 — Entity B:**
+- Create bill: $15,000 from Entity A
+- Code to Management Fee Expense
+- Capsule: "Intercompany — Q1 2025 — Entity A → Entity B"
+- Custom field: "Intercompany Ref" → "IC-2025-001"
+
+*Repeat for Feb and Mar with matching Intercompany Ref.*
+
+**Mar 31 — Quarterly settlement:**
+- Entity B transfers $45,000 to Entity A
+- Entity A: record receipt against 3 invoices
+- Entity B: record payment against 3 bills
+- Both capsules now show matching charge + settlement entries
+
+**Consolidation verification:**
+- Entity A: Intercompany Receivable $0, Management Fee Income $45,000
+- Entity B: Intercompany Payable $0, Management Fee Expense $45,000
+- On consolidation: both entries eliminate (income vs. expense, receivable vs. payable)
+
+---
+
+## Enrichment Suggestions
+
+| Enrichment | Value | Why |
+|---|---|---|
+| Tracking Tag | "Intercompany" | Filter all IC entries across entities |
+| Custom Field | "Intercompany Ref" → "IC-2025-001" | **Critical** — matching reference in both entities for reconciliation |
+| Custom Field | "Counterparty Entity" → "Entity B" | Identify the other party |
+| Nano Classifier | Service Type → "Management Fee" | Categorize the type of IC charge |
+
+---
+
+## Verification
+
+1. **Intercompany Reconciliation** → At any point, Entity A's Intercompany Receivable balance should equal Entity B's Intercompany Payable balance. Any mismatch indicates a missing or incorrect entry.
+2. **Trial Balance** → After settlement, both Intercompany Receivable and Intercompany Payable should be $0.
+3. **P&L match** → Entity A's Management Fee Income = Entity B's Management Fee Expense (same amounts, opposite directions).
+4. **Custom Field search** → Search both entities for matching "Intercompany Ref" values to verify every charge has a counterpart.
+
+---
+
+## Variations
+
+**Cross-currency intercompany:** If Entity A is SGD and Entity B is MYR, use the FX invoice/bill format: `currency: { sourceCurrency: "SGD" }` on Entity B's bill. FX differences are auto-handled. For manual journals, apply the spot rate and record any FX difference.
+
+**Cost allocation (not a service fee):** If Entity A allocates shared costs (rent, IT, insurance) to Entity B, the pattern is the same but the income account may be "Intercompany Cost Recovery" (contra-expense) instead of revenue.
+
+**Netting:** If both entities charge each other (e.g., A provides management, B provides warehousing), net the amounts and settle only the difference. Each entity still records the full gross charges — netting applies only to the cash settlement.
+
+**Transfer pricing:** Ensure intercompany prices are at arm's length for tax compliance. Document the pricing methodology in the capsule custom field (e.g., "TP Method" → "Cost Plus 10%").
+
+**Loan vs. trade:** If the intercompany transaction is a loan (not a service), use Intercompany Loan Receivable/Payable instead of trade accounts. Interest may apply — use the loan recipe for interest calculations.