jaz-cli 2.3.0 → 2.5.0

package/assets/skills/transaction-recipes/references/capital-wip.md

@@ -0,0 +1,167 @@
+# Recipe: Capital WIP to Fixed Asset Transfer
+
+## Scenario
+
+Your company is renovating its office at a total estimated cost of $150,000, incurred over 4 months through multiple bills (contractor, materials, permits). During construction, all costs are accumulated in a Capital Work-in-Progress (CIP/CWIP) account. Once the renovation is complete, the total cost is transferred to a Fixed Asset and registered in Jaz's FA module for automatic straight-line depreciation.
+
+**Pattern:** Bills/journals coded to CIP (accumulation phase) + transfer journal + FA registration + capsule
+
+---
+
+## Accounts Involved
+
+| Account | Type | Subtype | Role |
+|---|---|---|---|
+| Capital Work-in-Progress | Asset | Non-Current Asset | Accumulates costs during construction/development |
+| Fixed Asset — [Asset Name] | Asset | Non-Current Asset | Completed asset (after transfer) |
+| Accumulated Depreciation | Asset | Non-Current Asset (contra) | Depreciation reserve (auto by Jaz FA module) |
+| Depreciation Expense | Expense | Expense | Monthly depreciation charge (auto by Jaz FA module) |
+| Cash / Bank Account | Asset | Bank | Pays supplier bills |
+| Accounts Payable | Liability | Current Liability | When bills are recorded |
+
+---
+
+## Journal Entries
+
+### Phase 1: Cost Accumulation (during construction)
+
+Each supplier bill or expense is coded to the CIP account — **not** to expense.
+
+**Supplier bill example:**
+- Create bill: $40,000 to "ABC Contractors"
+- Code to: Capital Work-in-Progress
+- Assign to capsule
+
+**Internal labor capitalization (if applicable):**
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Capital Work-in-Progress | *labor cost* | |
+| 2 | Salaries Expense | | *labor cost* |
+
+### Phase 2: Transfer to Fixed Asset (on completion)
+
+When the project is complete, transfer the total accumulated cost from CIP to the fixed asset account:
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Fixed Asset — Office Renovation | $150,000 | |
+| 2 | Capital Work-in-Progress | | $150,000 |
+
+### Phase 3: Register Fixed Asset
+
+Register the completed asset in Jaz's Fixed Asset module:
+- Asset name: "Office Renovation — 2025"
+- Cost: $150,000 (must match the transfer amount)
+- Salvage value: $0 (or estimated residual)
+- Useful life: 60 months (5 years for leasehold improvements)
+- Method: Straight-line (Jaz native FA module)
+
+Jaz will then auto-post monthly depreciation:
+- Dr Depreciation Expense $2,500 / Cr Accumulated Depreciation $2,500
+
+---
+
+## Capsule Structure
+
+**Capsule:** "Office Renovation — 2025"
+**Capsule Type:** "Capital Projects"
+
+Contents:
+- Multiple supplier bills (Phase 1)
+- Internal labor journals (if any)
+- 1 transfer journal (Phase 2)
+- **Total entries:** Varies (typically 5-20 depending on project complexity)
+
+> **Note:** The auto-generated depreciation entries from the FA module are separate from the capsule. If you want them tracked, assign the FA to the same capsule tags.
+
+---
+
+## Worked Example
+
+**Project: Office Renovation**
+- Budget: $150,000
+- Duration: Jan 2025 — Apr 2025
+- Useful life after completion: 5 years (60 months)
+- Salvage value: $0
+
+**Jan 15 — Contractor deposit:**
+- Create bill: $40,000 to "ABC Contractors"
+- Code to Capital Work-in-Progress
+- Capsule: "Office Renovation — 2025"
+- Pay bill when due
+
+**Feb 10 — Materials purchase:**
+- Create bill: $35,000 to "BuildMart Supplies"
+- Code to Capital Work-in-Progress
+- Capsule: same
+
+**Mar 5 — Permits and fees:**
+- Create bill: $5,000 to "City Planning Authority"
+- Code to Capital Work-in-Progress
+- Capsule: same
+
+**Mar 28 — Contractor final payment:**
+- Create bill: $60,000 to "ABC Contractors"
+- Code to Capital Work-in-Progress
+- Capsule: same
+
+**Apr 1 — Internal labor capitalized:**
+- Journal: Dr CIP $10,000 / Cr Salaries Expense $10,000
+- Description: "Capitalize internal project management labor — Office Renovation"
+- Capsule: same
+
+**Apr 15 — CIP balance check:**
+- CIP account: $150,000 debit ($40K + $35K + $5K + $60K + $10K)
+
+**Apr 15 — Transfer journal:**
+- Dr Fixed Asset — Office Renovation $150,000
+- Cr Capital Work-in-Progress $150,000
+- Description: "Transfer CIP to Fixed Asset — renovation complete"
+- Capsule: same
+
+**Apr 15 — Register in FA module:**
+- Name: "Office Renovation — 2025"
+- Cost: $150,000
+- Salvage: $0
+- Life: 60 months
+- Start date: April 2025
+
+**May 31 onwards — Auto-depreciation:**
+- $150,000 / 60 months = $2,500/month
+- Jaz auto-posts: Dr Depreciation Expense $2,500 / Cr Accumulated Depreciation $2,500
+
+---
+
+## Enrichment Suggestions
+
+| Enrichment | Value | Why |
+|---|---|---|
+| Tracking Tag | "Capital Project" | Filter all CWIP and transfer entries |
+| Tracking Tag | "Office Renovation" | Project-specific filter |
+| Nano Classifier | Cost Category → "Contractor" / "Materials" / "Permits" | Break down project costs by category |
+| Custom Field | "Project #" → "CAPEX-2025-001" | Internal project reference |
+
+---
+
+## Verification
+
+1. **Trial Balance during accumulation** → Capital Work-in-Progress balance should equal the sum of all bills and journals coded to CIP.
+2. **After transfer** → CIP balance should be $0. Fixed Asset balance should equal the total project cost.
+3. **After FA registration** → Monthly depreciation should start from the completion month. Check first month's entry.
+4. **Group General Ledger by Capsule** → "Office Renovation — 2025" shows all bills + transfer. Complete project audit trail.
+5. **Fixed Asset Register** → Asset appears with correct cost, salvage, life, and monthly depreciation amount.
+
+---
+
+## Variations
+
+**Software development capitalization (IAS 38):** Same pattern but for internal software development. Research phase costs are expensed; development phase costs (once feasibility is established) are capitalized to CIP. Transfer to "Intangible Asset — Software" on go-live.
+
+**Multi-phase project:** If a large project has distinct milestones (e.g., Building A, Building B), you can create sub-capsules per phase or use nano classifiers to tag costs by phase. Transfer each phase to a separate fixed asset when that phase completes.
+
+**Cost overrun:** If actual costs exceed budget, the full actual cost is capitalized. The higher cost simply means higher depreciation per period. No separate treatment needed — CIP captures everything.
+
+**Borrowing costs (IAS 23):** If the project is funded by a specific loan, the interest during construction can be capitalized: Dr CIP / Cr Interest Expense. Stop capitalizing when the asset is ready for use.
+
+**Asset under construction — partial use:** If part of the asset starts being used before the project is complete (e.g., one floor of a building), transfer and register that portion. Continue accumulating costs for the remainder in CIP.

package/assets/skills/transaction-recipes/references/dividend.md

@@ -0,0 +1,111 @@
+# Recipe: Dividend Declaration and Payment
+
+## Scenario
+
+Your company's board declares a final dividend of $200,000 for FY2025, payable on March 15, 2026. Two journal entries are needed: one at the declaration date (creating the obligation) and one at the payment date (settling it). The dividend reduces retained earnings, not current-year profit.
+
+**Pattern:** Two manual journals + capsule (declaration + payment)
+
+---
+
+## Accounts Involved
+
+| Account | Type | Subtype | Role |
+|---|---|---|---|
+| Retained Earnings | Equity | Retained Earnings | Reduced by declared dividend |
+| Dividends Payable | Liability | Current Liability | Obligation from declaration to payment |
+| Cash / Bank Account | Asset | Bank | Settlement on payment date |
+
+> **Note:** Some companies use an "Dividends Declared" equity contra account instead of debiting Retained Earnings directly. Either approach is acceptable — the effect on equity is the same.
+
+---
+
+## Journal Entries
+
+### Step 1: Declaration (board resolution date)
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Retained Earnings | $200,000 | |
+| 2 | Dividends Payable | | $200,000 |
+
+### Step 2: Payment (settlement date)
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Dividends Payable | $200,000 | |
+| 2 | Cash / Bank Account | | $200,000 |
+
+---
+
+## Capsule Structure
+
+**Capsule:** "FY2025 Final Dividend"
+**Capsule Type:** "Dividends"
+
+Contents:
+- 1 declaration journal
+- 1 payment journal
+- **Total entries:** 2
+
+---
+
+## Worked Example
+
+**Setup:**
+- Declared amount: $200,000
+- Declaration date: February 15, 2026 (board resolution)
+- Payment date: March 15, 2026
+
+**Feb 15, 2026 — Declaration:**
+- Dr Retained Earnings $200,000
+- Cr Dividends Payable $200,000
+- Description: "FY2025 final dividend declared — Board Resolution #BR-2026-003"
+- Assign to capsule
+
+**Mar 15, 2026 — Payment:**
+- Dr Dividends Payable $200,000
+- Cr Cash / Bank Account $200,000
+- Description: "FY2025 final dividend payment"
+- Assign to same capsule
+
+**After both entries:**
+- Retained Earnings reduced by $200,000
+- Dividends Payable cleared to $0
+- Cash reduced by $200,000
+
+---
+
+## Enrichment Suggestions
+
+| Enrichment | Value | Why |
+|---|---|---|
+| Tracking Tag | "Dividend" | Filter all dividend-related entries |
+| Custom Field | "Board Resolution #" → "BR-2026-003" | Audit trail to authorization |
+| Custom Field | "Fiscal Year" → "FY2025" | Link to the year the dividend relates to |
+
+---
+
+## Verification
+
+1. **Trial Balance at Feb 28 (after declaration, before payment)** → Dividends Payable shows $200,000 credit. Retained Earnings reduced by $200,000.
+2. **Trial Balance at Mar 31 (after payment)** → Dividends Payable shows $0. Cash reduced by $200,000.
+3. **Statement of Changes in Equity** → Shows the $200,000 dividend reducing retained earnings.
+4. **Group General Ledger by Capsule** → Both entries visible under "FY2025 Final Dividend."
+
+---
+
+## Variations
+
+**Interim dividend:** Same structure, just declared mid-year (e.g., after H1 results). Use a separate capsule: "FY2025 Interim Dividend." Some jurisdictions require interim dividends to be based on audited interim accounts.
+
+**Dividend in specie (non-cash):** If the dividend is settled with assets (e.g., property, shares in a subsidiary), replace the Cash credit with the appropriate asset account. Record any gain/loss on the asset transfer in the same journal.
+
+**Withholding tax:** If your jurisdiction requires dividend withholding tax, the payment journal splits into net payment + tax payable:
+- Dr Dividends Payable $200,000
+- Cr Cash $170,000 (net to shareholders)
+- Cr Withholding Tax Payable $30,000 (15% tax)
+
+Then a separate payment when tax is remitted: Dr WHT Payable $30,000 / Cr Cash $30,000.
+
+**Multiple shareholders:** If dividends are paid pro-rata to multiple shareholders, use one multi-line payment journal with a line per shareholder's bank account, or record separate payment journals per shareholder — all in the same capsule.

package/assets/skills/transaction-recipes/references/employee-accruals.md

@@ -0,0 +1,154 @@
+# Recipe: Employee Benefit Accruals — Leave + Bonus (IAS 19)
+
+## Scenario
+
+Your company has 20 employees, each entitled to 14 days annual leave. Total annual leave cost is $84,000. IAS 19.13 requires the leave obligation to be accrued over the year as employees earn it. Separately, you accrue a quarterly bonus of 5% of revenue, settled annually after year-end performance review.
+
+**Pattern:** Scheduler (leave — fixed monthly) + manual journals (bonus — variable quarterly)
+
+---
+
+## Accounts Involved
+
+| Account | Type | Subtype | Role |
+|---|---|---|---|
+| Leave Expense | Expense | Expense | Monthly leave accrual charge |
+| Accrued Leave Liability | Liability | Current Liability | Obligation for earned but unused leave |
+| Bonus Expense | Expense | Expense | Quarterly bonus accrual charge |
+| Accrued Bonus Liability | Liability | Current Liability | Obligation for estimated bonus |
+| Cash / Bank Account | Asset | Bank | Settlement on payout |
+
+---
+
+## Journal Entries
+
+### Part A: Annual Leave Accrual (Monthly — Scheduler)
+
+**Monthly amount:** Total annual leave cost / 12
+
+```
+$84,000 / 12 = $7,000 per month
+```
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Leave Expense | $7,000 | |
+| 2 | Accrued Leave Liability | | $7,000 |
+
+**Scheduler settings:**
+- Frequency: Monthly
+- Start date: 2025-01-31
+- End date: 2025-12-31
+- Description: `Annual leave accrual — {{MONTH_NAME}} {{YEAR}}`
+- Capsule: "FY2025 Annual Leave Accrual"
+
+### Part A — Year-End True-Up
+
+At year-end, compare the accrued balance ($84,000) against actual leave liability:
+- If employees used less leave than expected → liability stays higher, no adjustment needed (or reduce if policy allows forfeit)
+- If employees used more leave → reduce the liability with an adjustment journal
+
+**Payout on resignation/termination:**
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Accrued Leave Liability | *payout amount* | |
+| 2 | Cash / Bank Account | | *payout amount* |
+
+### Part B: Bonus Accrual (Quarterly — Manual Journals)
+
+**Quarterly calculation:** 5% × quarterly revenue
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Bonus Expense | *estimated bonus* | |
+| 2 | Accrued Bonus Liability | | *estimated bonus* |
+
+### Part B — Year-End True-Up and Settlement
+
+When the actual bonus is determined (e.g., board approves $180,000 against $200,000 accrued):
+
+**Reversal of over-accrual:**
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Accrued Bonus Liability | $20,000 | |
+| 2 | Bonus Expense | | $20,000 |
+
+**Payment:**
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Accrued Bonus Liability | $180,000 | |
+| 2 | Cash / Bank Account | | $180,000 |
+
+---
+
+## Capsule Structure
+
+**Leave Capsule:** "FY2025 Annual Leave Accrual"
+**Capsule Type:** "Employee Benefits"
+
+Contents:
+- 12 monthly accrual journals (from scheduler)
+- Year-end true-up journal (if needed)
+- Payout journals for resignations
+- **Total entries:** 12-15
+
+**Bonus Capsule:** "FY2025 Performance Bonus"
+**Capsule Type:** "Employee Benefits"
+
+Contents:
+- 4 quarterly accrual journals
+- Year-end true-up journal
+- Settlement payment journal
+- **Total entries:** 6
+
+---
+
+## Worked Example
+
+**Leave accrual setup:**
+- 20 employees × 14 days × $300/day = $84,000 annual leave cost
+- Monthly accrual: $7,000
+- Create scheduler: Dr Leave Expense $7,000 / Cr Accrued Leave $7,000, monthly Jan-Dec
+
+**Bonus accrual by quarter:**
+
+| Quarter | Revenue | Bonus (5%) | Journal |
+|---|---|---|---|
+| Q1 | $800,000 | $40,000 | Dr Bonus Expense $40,000 / Cr Accrued Bonus $40,000 |
+| Q2 | $950,000 | $47,500 | Dr Bonus Expense $47,500 / Cr Accrued Bonus $47,500 |
+| Q3 | $1,100,000 | $55,000 | Dr Bonus Expense $55,000 / Cr Accrued Bonus $55,000 |
+| Q4 | $1,150,000 | $57,500 | Dr Bonus Expense $57,500 / Cr Accrued Bonus $57,500 |
+| **Total** | **$4,000,000** | **$200,000** | |
+
+**Year-end true-up:** Board approves $180,000 bonus → reverse $20,000 over-accrual, then pay $180,000.
+
+---
+
+## Enrichment Suggestions
+
+| Enrichment | Value | Why |
+|---|---|---|
+| Tracking Tag | "Employee Benefits" | Filter all leave + bonus entries |
+| Nano Classifier | Department → "Engineering" / "Sales" / etc. | Allocate leave/bonus cost by department |
+| Custom Field | "Fiscal Year" → "FY2025" | Link to fiscal year |
+
+---
+
+## Verification
+
+1. **Trial Balance at Jun 30** → Accrued Leave Liability shows $42,000 credit (6 months × $7,000). Accrued Bonus shows $87,500 (Q1 + Q2).
+2. **P&L for Q2** → Leave Expense: $21,000 (3 months). Bonus Expense: $47,500.
+3. **Trial Balance at Dec 31 (before true-up)** → Accrued Leave: $84,000. Accrued Bonus: $200,000.
+4. **After true-up and payment** → Accrued Bonus clears to $0. Bonus Expense net = $180,000.
+
+---
+
+## Variations
+
+**Proportional leave by hire date:** New employees hired mid-year get prorated leave. Adjust the scheduler amount per employee or use manual journals for partial-year hires.
+
+**Bonus based on profit (not revenue):** Same structure, but the quarterly estimate uses profit before bonus. The true-up at year-end adjusts for the circular reference (bonus reduces profit which reduces bonus).
+
+**13th month salary (Philippines / Juan):** Similar to leave accrual — fixed monthly accrual of 1/12 of annual salary, settled in December. Use the scheduler pattern.
+
+**Leave encashment policy:** If unused leave can be cashed out, the accrued liability stays on the balance sheet until encashment or termination. No year-end reversal — only adjustment for forfeited leave (if policy allows).

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).