jaz-clio 5.74.2 → 6.0.0

package/assets/skills/jobs/references/year-end-close.md

@@ -1,8 +1,8 @@
 # Year-End Close
 
-> Annual close = quarter-end close × 4 + annual-only extras (FA reconciliation, true-ups, dividends, retained earnings rollover, statutory tax provision). Walk the phases below in order, calling the named platform tools directly. (Local CLI convenience: `clio jobs year-end --period <YYYY>` prints this same phased checklist.) For most SMBs, annual extras add 2-5 days on top of the quarterly close cadence.
+> Annual close = quarter-end close × 4 + annual-only extras (FA reconciliation, true-ups, dividends, retained earnings rollover, statutory tax provision). Walk the phases below in order, calling the named platform tools directly. For most SMBs, annual extras add 2-5 days on top of the quarterly close cadence.
 
-## Tools, recipes, calculators this job uses
+## Tools and calculators this job uses
 
 ### Orchestration
 - **`quarter-end-close.md`**: invoked four times in standalone mode (Q1, Q2, Q3, Q4) before annual extras run.
@@ -13,9 +13,9 @@
 - **`search_fixed_assets(filter: {status: {in: ['ACTIVE', 'DISPOSED']}})`**: Y1 enumeration of FAs.
 - **`mark_fixed_asset_sold(...)` for a sale or `discard_fixed_asset(...)` for a write-off (both are operations, not status mutations)**: Y1 fallback if any FA has incorrect status at FY-end.
 - **`search_journals(filter: {tags: {eq: 'leave-accrual'}, valueDate: {between: [<FY-start>, <FY-end>]}})` / `search_journals(filter: {tags: {eq: 'bonus-accrual'}, ...})`**: Y2 true-up: pull all FY accrual journals to compare against actuals.
-- **`create_journal(...)`**: Y2 true-up adjustment journals (manual one-off, not recipe-driven).
-- **`plan_recipe(recipe: 'dividend', ...)` + `execute_recipe(...)`**: Y3 dividend declaration + payment (engine emits the 2-step pattern: declaration journal + payment cash-out).
-- **`plan_recipe(recipe: 'ecl', ...)` + `execute_recipe(...)`**: Y4 IFRS 9 ECL year-end true-up against `generate_aged_ar`.
+- **`create_journal(...)`**: Y2 true-up adjustment journals (manual one-off, no calculator).
+- **`calculate(type: 'dividend', ...)`**, then `create_capsule` + `create_journal` (declaration) + `create_cash_out` (payment), each with `capsuleResourceId`: Y3 dividend declaration + payment.
+- **`calculate(type: 'ecl', ...)`**, then `create_capsule` + `create_journal` with `capsuleResourceId`: Y4 IFRS 9 ECL year-end true-up against `generate_aged_ar`.
 - **`update_account(resourceId: <CoA root>, lockDate: <FY-end>)`**: Y8 final lock.
 
 ### Platform tools: current/non-current reclassification (manual annual journals)
@@ -30,26 +30,26 @@
 - **`clio calc depreciation --cost --salvage --life --method --frequency annual --json`**: Y1 per-asset cross-check.
 - **`clio calc loan --principal --rate --term --json`**: Y6 reclassification: identify the next-12-months principal portion.
 - **`clio calc lease --payment --term --rate --json`**: Y6 reclassification for IFRS 16.
-- **`clio calc ecl --receivables <json> --json`**: Y4 ECL calculation.
-- **`clio calc dividend --amount <total> --withholding-rate <%> --json`**: Y3 dividend computation.
+- **`clio calc ecl --current --30d --60d --90d --120d --rates --json`**: Y4 ECL calculation.
+- **`clio calc dividend --amount <total> --declaration-date <date> --payment-date <date> --withholding-rate <%> --json`**: Y3 dividend computation.
 
 ### Cross-references
 - Org inputs this job needs (confirm with the user when not already on file): the FY-end, whether a statutory audit is required, the tax jurisdiction (`SG` | `PH`), the dividend policy, and headcount (for the leave true-up).
 - Sibling jobs: `quarter-end-close.md` (must run for all 4 quarters before this job's annual extras), `audit-prep.md` (consumes year-end-close output), and the SG Form C-S statutory filing (consumes the audit-prep pack; see the SG Form C-S section in `SKILL.md`).
-- Recipes invoked: `dividend`, `ecl` (year-end bad-debt true-up), `accrued-expense` (employee true-ups, plus manual journals). See the transaction-recipes skill.
+- Calculator types used: `dividend`, `ecl` (year-end bad-debt true-up), `accrued-expense` (employee true-ups, plus manual journals). See the transaction-recipes skill for the accounting pattern behind each.
 
 ---
 
 ## Standalone vs Incremental
 
-- **Standalone (default):** Generates the full plan: all quarter-end-close steps for Q1-Q4, then annual extras. Use when quarters haven't been closed yet.
-- **Incremental** (`--incremental`): Annual extras only. Use when all 4 quarters are already closed and locked.
+- **Standalone:** all quarter-end-close steps for Q1-Q4, then annual extras. Use when quarters haven't been closed yet.
+- **Incremental:** annual extras only. Use when all 4 quarters are already closed and locked.
 
 Quarters MUST be closed in order: Q1 locked → Q2 close → ... Annual extras assume monthly + quarterly cadence is current.
 
 ## Phase sequence
 
-Standalone: run all quarter-end-close steps for Q1-Q4 (Phase 1-7), then the annual extras + final lock + audit-prep handoff (Phase 8 onward). Incremental (`--incremental` on the local CLI): annual extras only. (Local CLI: `clio jobs year-end --period 2025` prints the same phased checklist.)
+Standalone: run all quarter-end-close steps for Q1-Q4 (Phase 1-7), then the annual extras + final lock + audit-prep handoff (Phase 8 onward). Incremental: annual extras only.
 
 ## Phase 1-7: Quarterly closes (×4), IF standalone mode
 
@@ -66,7 +66,7 @@ generate_fa_recon_summary(primarySnapshotStartDate: '2025-01-01', primarySnapsho
 
 For Jaz native straight-line depreciation: should be automatic and correct. Verify the 12-month aggregate against `generate_general_ledger(accountResourceIds: [<Depreciation Expense>], startDate, endDate)`.
 
-For non-SL assets (DDB, 150DB) where `plan_recipe(recipe: 'depreciation', method: 'ddb' | '150db')` was used: each capsule pre-emitted 12 future-dated DRAFT journals at recipe-execution time. Confirm all 12 are FINALIZED via `search_journals(filter: {status: {eq: 'DRAFT'}, valueDate: {between: [<FY-start>, <FY-end>]}})` (should be empty). If non-empty: route back to `month-end-close.md` step 9.
+For non-SL assets (DDB, 150DB) depreciated from a `calculate(type: 'depreciation', method: 'ddb' | '150db')` schedule: the year's journals were posted into the asset's capsule (up front as future-dated DRAFTs, or one per monthly close). Confirm all are FINALIZED via `search_journals(filter: {status: {eq: 'DRAFT'}, valueDate: {between: [<FY-start>, <FY-end>]}})` (should be empty). If non-empty: route back to `month-end-close.md` step 9.
 
 Reconcile `generate_fa_recon_summary` formula: `openingNbv + additions − disposals − depreciation == closingNbv == TB[Fixed Assets].balance`. Mismatch beyond the materiality threshold → investigate via `search_fixed_assets(filter: {status: {eq: 'ACTIVE'}})` cross-referenced against the depreciation capsule's journals (`search_journals(filter: {valueDate: {between: [<FY-start>, <FY-end>]}})`); typical cause is a disposal posted without `mark_fixed_asset_sold` / `discard_fixed_asset`.
 
@@ -78,7 +78,7 @@ Reconcile `generate_fa_recon_summary` formula: `openingNbv + additions − dispo
 search_journals(filter: {tags: {eq: 'leave-accrual'}, valueDate: {between: ['2025-01-01', '2025-12-31']}})
 ```
 
-Sum FY accruals (the recipe-pre-emitted journals already finalized monthly). Compare against actual unused leave days × daily rate per employee at FY-end (HR data). Difference: post manual `create_journal`:
+Sum FY accruals (the scheduled leave-accrual journals already finalized monthly). Compare against actual unused leave days × daily rate per employee at FY-end (HR data). Difference: post manual `create_journal`:
 
 ```
 create_journal({
@@ -103,9 +103,8 @@ If accrued > actual: reverse the excess (Dr Leave Liability / Cr Leave Expense).
 If the org declared a final dividend for the FY:
 
 ```
-plan_recipe(
-  // Accounts, capsule and counterparty are not plan_recipe params: execute_recipe resolves accounts from the CoA and takes bankAccountName / contactName.
-  recipe: 'dividend',
+calculate(
+  type: 'dividend',
   amount: <gross-dividend>,
   withholdingRate: <dividend withholding rate>,
   declarationDate: '2025-12-31',
@@ -113,7 +112,18 @@ plan_recipe(
 )
 ```
 
-Then `execute_recipe(...)`. Engine emits a declaration journal (Dr Retained Earnings / Cr Dividends Payable) and a payment cash-out, plus a withholding cash-out when `withholdingRate > 0`. Only the declaration journal follows the `finalize` flag (DRAFT or ACTIVE). The cash-outs post ACTIVE immediately, dated `paymentDate`: cash entries have no draft state. So run `execute_recipe` on the actual payment date, not at FY-end when the dividend is only declared. If the declaration must be booked in the FY-end close, post it alone with `create_journal` and record the payment with `create_cash_out` when the money leaves the account.
+The calculator returns three dated steps: a declaration journal (Dr Retained Earnings / Cr Dividends Payable), a payment cash-out, and a withholding cash-out when `withholdingRate > 0`. It posts nothing. Then:
+
+1. `list_capsule_types` + `create_capsule` (type `Dividends`).
+2. Declaration: `create_journal(valueDate: '2025-12-31', autoReference: true, journalEntries: [<declaration lines>], capsuleResourceId: <capsule id>)`. Book this in the FY-end close.
+3. Payment, no withholding: `create_cash_out(valueDate: '<paymentDate>', accountResourceId: <bank account>, lines: [{accountResourceId: <Dividends Payable>, amount: <gross dividend>}], capsuleResourceId: <capsule id>)`.
+4. Payment, with withholding: the payment step has a credit to Withholding Tax Payable beside the bank line, and a cash-out debits every one of its lines, so it cannot carry that credit. Split it in two, both dated `<paymentDate>`:
+   - `create_cash_out(valueDate: '<paymentDate>', accountResourceId: <bank account>, lines: [{accountResourceId: <Dividends Payable>, amount: <NET dividend>}], capsuleResourceId: <capsule id>)`.
+   - `create_journal(valueDate: '<paymentDate>', autoReference: true, journalEntries: [<Dr Dividends Payable / Cr Withholding Tax Payable, for the withholding amount>], capsuleResourceId: <capsule id>)`.
+   Together they clear Dividends Payable (gross) and leave the withheld tax owing to the authority.
+5. Withholding remittance, when the tax is actually remitted: `create_cash_out(valueDate: <remittance date>, accountResourceId: <bank account>, lines: [{accountResourceId: <Withholding Tax Payable>, amount: <withholding amount>}], capsuleResourceId: <capsule id>)`.
+
+Cash-outs post ACTIVE immediately (cash entries have no draft state), so record them when the money leaves the account, not at FY-end when the dividend is only declared. Full walkthrough: `transaction-recipes/references/dividend.md` step 4.
 
 For interim dividends declared during the year: those should already be posted in their respective monthly closes. Y3 covers FY-end final dividend only.
 
@@ -132,10 +142,10 @@ clio calc ecl --current <c> --30d <30> --60d <60> --90d <90> --120d <120> --rate
 If top-up needed > the materiality threshold:
 
 ```
-plan_recipe(recipe: 'ecl', buckets: <[{name, balance, rate}]>, existingProvision: <Allowance for Doubtful Debts balance>, startDate: '2025-12-31')
+calculate(type: 'ecl', buckets: <[{name, balance, rate}]>, existingProvision: <Allowance for Doubtful Debts balance>, startDate: '2025-12-31')
 ```
 
-Then `execute_recipe(...)`. Engine emits 1 journal: Dr Bad Debt Expense / Cr Allowance for Doubtful Debts for the top-up amount. ECL recipe is one-shot per FY (no ongoing schedule); capsule closes on execution.
+Then `list_capsule_types` + `create_capsule` (type `ECL Provision`) and post the one journal the calculator returns with `create_journal` and `capsuleResourceId`: Dr Bad Debt Expense / Cr Allowance for Doubtful Debts for the top-up amount. ECL is one-shot per FY (no ongoing schedule).
 
 For specific large customers requiring stage-3 provision (specific impairment vs collective ECL): use `create_journal` directly with explicit per-customer narrative.
 
@@ -147,7 +157,7 @@ For each existing IAS 37 provision capsule (warranty, legal, decommissioning):
 search_capsules(filter: {status: {eq: 'ACTIVE'}})
 ```
 
-Per capsule, recompute the present value at FY-end (`clio calc provision`). Top-up via additional `plan_recipe(recipe: 'provision', ...)` + `execute_recipe` if required, OR reverse via `create_journal` if the obligation reduced.
+Per capsule, recompute the present value at FY-end (`clio calc provision`). Top-up via `create_journal` into the provision's capsule (amount from `calculate(type: 'provision', ...)`) if required, OR reverse via `create_journal` if the obligation reduced.
 
 ### Y6: Current/non-current reclassification (manual journals)
 
@@ -207,7 +217,7 @@ Invoke `audit-prep.md` job. Year-end-close output (TB final, all reports, all re
 |--------|-------|----------|
 | Phase 1-7 (standalone) | Quarters not all closed | One or more quarters incomplete. Route back to the missing `quarter-end-close.md`. Run annual extras only once all 4 quarters are locked. |
 | Y1 FA recon | NBV doesn't tie | Investigate disposed assets posted without status update. `search_fixed_assets(filter: {status: {eq: 'ACTIVE'}})` then check each against current physical existence. |
-| Y3 `execute_recipe` for dividend | 422 `dividends_payable_account_missing` | Create `Dividends Payable` account (`Current Liability`) via `create_account` first. |
+| Y3 dividend declaration journal | No `Dividends Payable` account to resolve the blueprint line to | Create `Dividends Payable` account (`Current Liability`) via `create_account` first. |
 | Y4 ECL | top-up amount surprisingly large | Possibly the existing provision is stale (no monthly mental ECL check ran). Confirm `--existing-provision` matches `TB[Allowance for Doubtful Debts].balance`. If yes, real impairment event occurred; surface to practitioner. |
 | Y6 reclassification | Existing reclassification entry from prior year still present | Reverse the prior-year reclassification first (it sits in opening balances). The reclassification entry is per-FY; should be reset at the start of each FY. |
 | Y7 completeness gate | Drafts present at FY-end | Either clear (finalize) or document the residuals and surface to the user. NEVER hand the pack to the auditor with FY-period drafts. |

package/assets/skills/transaction-recipes/SKILL.md

@@ -1,15 +1,16 @@
 ---
 name: jaz-recipes
-version: 5.74.2
+version: 6.0.0
 description: >-
   Use this skill when modeling complex multi-step accounting transactions:
   anything that spans multiple periods, involves changing amounts, or requires
   linked entries. Covers 16 IFRS-compliant recipes (prepaid amortization,
   deferred revenue, loans, IFRS 16 leases, hire purchase, fixed deposits,
   asset disposal, FX revaluation, ECL, IAS 37 provisions, dividends,
-  intercompany, capital WIP) and 13 financial calculators that produce
-  execution-ready blueprints. Also use when the user mentions depreciation,
-  amortization, lease accounting, loan schedules, or any IFRS calculation.
+  intercompany, capital WIP) and 13 financial calculators that return the
+  schedule and the journal lines to post. Also use when the user mentions
+  depreciation, amortization, lease accounting, loan schedules, or any IFRS
+  calculation.
 license: MIT
 compatibility: Works with Claude Code, Claude Cowork, Claude.ai, and any agent that reads markdown. For API payloads, load the jaz-api skill alongside this one. For the operational close workflows these recipes plug into (month-end close, GST/VAT filing, year-end close), load the jaz-jobs skill.
 ---
@@ -18,7 +19,7 @@ compatibility: Works with Claude Code, Claude Cowork, Claude.ai, and any agent t
 
 You are modeling **complex multi-step accounting scenarios** in Jaz: transactions that span multiple periods, involve changing amounts, or require several linked entries to complete a single business event.
 
-> **Jaz-native, not generic.** Every recipe in this skill is designed around the Jaz recipe engine (`plan_recipe` / `execute_recipe`), Jaz capsule types, Jaz CoA classifications, and Jaz scheduler primitives. It is NOT an interchangeable IFRS reference; it is the operating manual for posting these transactions through the Jaz ledger. If you find yourself hand-constructing journal entries from this skill, you have skipped step 1: invoke `plan_recipe(recipe: ...)` first and let the engine emit the entries.
+> **Jaz-native, not generic.** Every recipe in this skill is designed around the Jaz calculators (`calculate` / `clio calc`), Jaz capsule types, Jaz CoA classifications, and Jaz scheduler primitives. It is NOT an interchangeable IFRS reference; it is the operating manual for posting these transactions through the Jaz ledger. Never work the amounts by hand: run the calculator first and post the lines it returns. Nothing posts a recipe for you: the calculator posts nothing, and you create the capsule and each entry yourself (see "Posting a Recipe: Three Steps").
 
 **This skill provides Jaz-contextual recipes with full accounting logic. For API field names and payloads, load the `jaz-api` skill alongside this one. For the operational close workflows that invoke these recipes (month-end close, GST/VAT filing, year-end close), load the `jaz-jobs` skill.**
 
@@ -31,7 +32,7 @@ You are modeling **complex multi-step accounting scenarios** in Jaz: transaction
 - Recording depreciation using methods Jaz doesn't natively support (declining balance, 150DB)
 - Managing fixed deposit placements with interest accrual schedules (IFRS 9)
 - Disposing of fixed assets: sale, scrap, or write-off with gain/loss calculation (IAS 16)
-- FX revaluation of non-AR/AP monetary items at period-end (IAS 21)
+- Verifying the period-end FX revaluation Jaz posts itself (IAS 21): the calculator checks the figure, and its result is not posted
 - Calculating expected credit loss provisions on aged receivables (IFRS 9)
 - Accruing employee leave and bonus obligations (IAS 19)
 - Recognizing provisions at PV with discount unwinding (IAS 37)
@@ -47,8 +48,9 @@ Every recipe uses a combination of these Jaz features. See `references/building-
 | Building Block | Role in Recipes |
 |---|---|
 | **Capsules** | Group all related entries into one workflow container |
+| **Calculators** | Return the schedule and the journal lines for each step (offline, post nothing) |
 | **Schedulers** | Automate fixed-amount recurring journals (prepaid, deferred, leave) |
-| **Manual Journals** | Record variable-amount entries (loan interest, IFRS 16 unwinding, FX reval, ECL) |
+| **Manual Journals** | Record variable-amount entries (loan interest, IFRS 16 unwinding, ECL) |
 | **Fixed Assets** | Native straight-line depreciation for ROU assets and completed capital projects |
 | **Invoices / Bills** | Trade documents for intercompany, supplier bills for capital WIP |
 | **Tracking Tags** | Tag all entries in a scenario for report filtering |
@@ -59,9 +61,9 @@ Every recipe uses a combination of these Jaz features. See `references/building-
 
 Jaz schedulers generate **fixed-amount** recurring entries. This determines which recipe pattern to use:
 
-- **Fixed amounts each period** → Use a scheduler inside a capsule (automated)
-- **Variable amounts each period** → Use manual journals inside a capsule (calculated per period)
-- **One-off or two-entry events** → Use manual journals (e.g., dividend declaration + payment)
+- **Fixed amounts each period** → One scheduler can replace the N dated journals (it posts each occurrence itself)
+- **Variable amounts each period** → Use manual journals inside a capsule (one per period, amounts from the calculator)
+- **One-off or two-entry events** → Use manual journals (e.g., a dividend declaration; its payment is a cash-out)
 
 If a scenario genuinely fits either pattern, record the pick once the entries post: `jot(kind: METHOD)` naming the pattern chosen and the deciding fact.
 
@@ -69,19 +71,19 @@ If a scenario genuinely fits either pattern, record the pick once the entries po
 |---|---|---|
 | Prepaid Amortization | Scheduler + capsule | Same amount each month |
 | Deferred Revenue | Scheduler + capsule | Same amount each month |
-| Accrued Expenses | Two schedulers + capsule | Accrual + reversal cycle with end dates |
+| Accrued Expenses | Manual journals + capsule | Accrual + reversal pair per period, re-estimated each time |
 | Employee Leave Accrual | Scheduler + capsule | Fixed monthly accrual |
 | Bank Loan | Manual journals + capsule | Interest changes as principal reduces |
 | IFRS 16 Lease | Hybrid (native FA + manual journals) + capsule | ROU depreciation is fixed; liability unwinding changes |
 | Declining Balance | Manual journals + capsule | Depreciation changes as book value reduces |
-| FX Revaluation | Manual journals + capsule | Rates change each period |
+| FX Revaluation | Verification only: nothing posted, no capsule | Jaz revalues foreign-currency balances itself at period end; the calculator verifies that figure and its result is not posted |
 | ECL Provision | Manual journals + capsule | Receivables and rates change each quarter |
 | Fixed Deposit | Cash-out + manual journals + cash-in + capsule | Placement, monthly accruals, maturity |
 | Hire Purchase | Manual journals + FA registration + capsule | Like IFRS 16 but depreciate over useful life |
 | Asset Disposal | Manual journal + FA deregistration | One-off compound entry + FA update |
 | Provisions (IAS 37) | Manual journals + cash-out + capsule | Unwinding amount changes each month |
 | Bonus Accrual | Manual journals + capsule | Revenue/profit changes each quarter |
-| Dividends | Manual journals + capsule | One-off: declaration + payment |
+| Dividends | Manual journal + cash-out + capsule | One-off: declaration journal, then the payment as a cash-out (with withholding tax, a journal for the withheld amount too) |
 | Intercompany | Invoices/bills + capsule | Mirrored entries in two entities |
 | Capital WIP | Bills/journals + FA registration + capsule | Accumulate then transfer |
 
@@ -97,9 +99,9 @@ Each recipe includes: scenario description, accounts involved, journal entries,
 
 ### Tier 2: Manual Journal Recipes (Calculated)
 
-3. **[Accrued Expenses](references/accrued-expenses.md)**: Month-end expense accrual and start-of-month reversal using two schedulers with end dates, plus the actual supplier bill. *Paired calculator: `clio calc accrued-expense`. Typical context: month-end close (accruals step inside the month-end close).*
+3. **[Accrued Expenses](references/accrued-expenses.md)**: Month-end expense accrual and next-period reversal as a journal pair per period, plus the actual supplier bill. *Paired calculator: `clio calc accrued-expense`. Typical context: month-end close (accruals step inside the month-end close).*
 
-4. **[Bank Loan](references/bank-loan.md)**: Loan disbursement, monthly installments splitting principal and interest, full amortization table with worked example. *Typical context: ad-hoc (one-off setup at loan drawdown, then month-end close picks up each installment journal via the scheduler the recipe creates).*
+4. **[Bank Loan](references/bank-loan.md)**: Loan disbursement, monthly installments splitting principal and interest, full amortization table with worked example. *Paired calculator: `clio calc loan`. Typical context: ad-hoc (one-off setup at loan drawdown, then month-end close posts or finalizes each installment journal).*
 
 5. **[IFRS 16 Lease](references/ifrs16-lease.md)**: Right-of-use asset recognition, lease liability unwinding with changing interest, native FA for ROU straight-line depreciation. *Typical context: month-end close (depreciation + liability unwinding booking each period inside the month-end close) and year-end (ROU register sign-off inside the fixed-asset review + the year-end close).*
 
@@ -113,7 +115,7 @@ Each recipe includes: scenario description, accounts involved, journal entries,
 
 ### Tier 3: Month-End Close Recipes
 
-10. **[FX Revaluation (verification only)](references/fx-revaluation.md)**: Jaz auto-handles ALL period-end IAS 21.23 FX translation (AR, AP, cash, bank, intercompany, term deposits, FX provisions). The recipe and `clio calc fx-reval` are for VERIFICATION ONLY (independent cross-check vs what Jaz auto-posted). Do NOT invoke `execute_recipe(recipe: 'fx-reval', ...)` (would double-post). *Typical context: period-end / year-end FX verification flow.*
+10. **[FX Revaluation (verification only)](references/fx-revaluation.md)**: Jaz auto-handles ALL period-end IAS 21.23 FX translation (AR, AP, cash, bank, intercompany, term deposits, FX provisions). The recipe and `clio calc fx-reval` / `calculate(type: 'fx-reval')` are for VERIFICATION ONLY (independent cross-check vs what Jaz auto-posted). Do NOT post the calculator's result (it would double-count). *Typical context: period-end / year-end FX verification flow.*
 
 11. **[Bad Debt Provision / ECL](references/bad-debt-provision.md)**: IFRS 9 simplified approach provision matrix using aged receivables and historical loss rates. *Paired calculator: `clio calc ecl`. Typical context: GST/VAT filing cycle (ECL reviewed alongside the return prep since AR aging is already pulled) and year-end (ECL true-up inside the year-end close).*
 
@@ -123,26 +125,33 @@ Each recipe includes: scenario description, accounts involved, journal entries,
 
 13. **[Provisions with PV Unwinding](references/provisions.md)**: IAS 37 provision recognized at PV, with monthly discount unwinding schedule. For warranties, legal claims, decommissioning, restructuring. *Paired calculator: `clio calc provision`. Typical context: month-end close (monthly discount-unwinding journal inside the month-end close); initial recognition triggered ad-hoc when the obligating event occurs.*
 
-14. **[Dividend Declaration & Payment](references/dividend.md)**: Board-declared dividend: two journals (declaration reducing retained earnings, then payment). Optional withholding tax adds a third step. *Paired calculator: `clio calc dividend`. Typical context: year-end (dividend declaration is part of the year-end close after profit is finalized) or ad-hoc (interim dividends).*
+14. **[Dividend Declaration & Payment](references/dividend.md)**: Board-declared dividend: a declaration journal reducing retained earnings, then the payment as a cash-out. Optional withholding tax adds a journal for the withheld amount and a cash-out for its remittance. *Paired calculator: `clio calc dividend`. Typical context: year-end (dividend declaration is part of the year-end close after profit is finalized) or ad-hoc (interim dividends).*
 
 15. **[Intercompany Transactions](references/intercompany.md)**: Mirrored invoices/bills or journals across two Jaz entities with matching intercompany reference, quarterly settlement. *Typical context: month-end close (mirror entries booked each period inside the month-end close) and year-end (intercompany elimination + confirmation inside audit prep).*
 
 16. **[Capital WIP to Fixed Asset](references/capital-wip.md)**: Cost accumulation in CIP account during construction/development, transfer to FA on completion, auto-depreciation via Jaz FA module. *Typical context: month-end close (cost accumulation each period) and year-end (transfer to FA + commissioning review inside the fixed-asset review).*
 
-## How to Use These Recipes
+## Posting a Recipe: Three Steps
 
-1. **Read the recipe** for your scenario: understand the accounts, journal entries, and capsule structure.
-2. **Create the accounts** listed in the "Accounts Involved" table (if they don't already exist in the CoA).
-3. **Create the capsule** with an appropriate capsule type.
-4. **Run the calculator** (if available) to generate exact amounts: `clio calc <command> --json` gives you a complete blueprint. Where you picked the method yourself (e.g. `--method ddb` over `sl`), record the judgment after the entries post: `jot(kind: METHOD)` naming the method and why.
-5. **Record the initial transaction** (bill, invoice, or journal); assign it to the capsule.
-6. **For scheduler recipes**: Create the scheduler with the same capsule; it generates all subsequent entries automatically.
-7. **For manual journal recipes**: Record each period's journal using the calculator output or worked example, always assigning to the same capsule.
-8. **Verify** using the steps in each recipe (ledger grouping by capsule, trial balance checks).
+No tool runs a recipe end to end. You perform three explicit steps (full detail, the action-to-tool mapping and the draft / reference rules are in `references/building-blocks.md`):
 
-## Financial Calculators (CLI)
+1. **Calculate.** `calculate(type, ...)` (MCP) or `clio calc <type> ... --json` (CLI). Offline, read-only, no account needed. It returns the schedule and, when a start date is given, a `blueprint` with dated steps and the journal lines for each step. It posts nothing.
+2. **Create the capsule.** `list_capsule_types` (create the type with `create_capsule_type` if it is missing), then `create_capsule`.
+3. **Post each blueprint step** with the real transaction tools, each carrying `capsuleResourceId`: `create_journal`, `create_bill`, `create_invoice`, `create_cash_in`, `create_cash_out`. Where the same amount repeats every period, one `create_scheduled_journal` can replace the N dated journals. Fixed assets go through the fixed-asset tools (`create_fixed_asset`, `mark_fixed_asset_sold`, `discard_fixed_asset`).
 
-The `jaz-clio` CLI includes 13 IFRS-compliant financial calculators. Each produces a formatted schedule + per-period journal entries + human-readable workings. Use `--json` for structured output with a complete **blueprint**: capsule type/name, tags, custom fields, workings (capsuleDescription), and every step with action type, date, accounts, and amounts.
+Around those three steps:
+
+- **Read the recipe** for your scenario first: the accounts, the journal entries, the capsule structure and the worked example.
+- **Resolve every account yourself.** Blueprint lines carry labels (`Cash / Bank Account`, `Loan Payable`), not accounts. Map each with `search_accounts` / `list_accounts` (bank accounts via `list_bank_accounts`); create a missing account only after the practitioner confirms its classification.
+- **Record judgment.** Where you picked the method yourself (e.g. `method: 'ddb'` over `'sl'`), record it after the entries post: `jot(kind: METHOD)` naming the method and why.
+- **Verify** using the steps in each recipe (general ledger grouped by capsule, trial balance checks).
+- **`fx-reval` is VERIFICATION ONLY.** Jaz revalues foreign-currency balances at period end (IAS 21.23); posting the calculator's result double-counts.
+
+## Financial Calculators
+
+13 IFRS-compliant financial calculators, reachable two ways with the same result: the MCP tool `calculate(type: <type>, ...)` and the CLI `clio calc <type>`. Each produces a schedule + per-period journal entries + human-readable workings. On the CLI use `--json` for structured output with the **blueprint**: capsule type/name, tags, custom fields, workings (capsuleDescription), and every step with action type, date, accounts, and amounts.
+
+The MCP param names differ from the CLI flags: `annualRate` (`--rate`), `termMonths` (`--term`), `monthlyPayment` (`--payment`), `usefulLifeMonths` (`--useful-life`), `salvageValue` (`--salvage`), `usefulLifeYears` (`--life`), `acquisitionDate` / `disposalDate` (`--acquired` / `--disposed`), `compounding` (`--compound`), `daysPerYear` (`--days`), and `buckets: [{ name, balance, rate }]` for ECL (`--current`, `--30d` ... `--rates`).
 
 All calculators support `--currency <code>` and `--json`.
 
@@ -187,8 +196,8 @@ clio calc asset-disposal --cost 50000 --salvage 5000 --life 5 --acquired 2022-01
 
 # ── Tier 3 Calculators ──────────────────────────────────────────
 
-# FX revaluation: unrealized gain/loss on non-AR/AP items (IAS 21)
-# Typical context: month-end close (period-end FX reval) + year-end (revaluation)
+# FX revaluation (IAS 21): VERIFICATION ONLY. Checks the revaluation Jaz posts itself; never post this result.
+# Typical context: month-end close + year-end (cross-check the platform's period-end revaluation)
 # --rate-direction is REQUIRED: these rates read foreign-first (1 USD = 1.35 SGD).
 # A list_currency_rates value would be FUNCTIONAL_TO_SOURCE instead.
 clio calc fx-reval --amount 50000 --book-rate 1.35 --closing-rate 1.38 --rate-direction SOURCE_TO_FUNCTIONAL [--position ASSET|LIABILITY] [--currency USD] [--base-currency SGD] [--json]
@@ -226,7 +235,7 @@ clio jobs bank-recon match --input bank-data.json [--tolerance 0.01] [--date-win
 
 ### Blueprint Output (`--json`)
 
-Every calculator's `--json` output includes a `blueprint` object, a complete execution plan for creating the capsule and posting all transactions in Jaz:
+The result includes a `blueprint` object: the capsule to create and the steps to post, in order. The dated calculators (loan, lease, prepaid, deferred revenue, provision, fixed deposit, accrued expense, leave accrual) return `blueprint: null` when no start date is given.
 
 ```json
 {
@@ -254,17 +263,19 @@ Every calculator's `--json` output includes a `blueprint` object, a complete exe
 }
 ```
 
-**Blueprint action types** (each step tells you HOW to execute it in Jaz):
+**Blueprint action types** (each step tells you which tool posts it):
 
-| Action | When used | Jaz module |
+| Action | When used | Tool |
 |---|---|---|
-| `bill` | Supplier document (prepaid expense) | Bills |
-| `invoice` | Customer document (deferred revenue) | Invoices |
-| `cash-in` | Cash arrives in bank (loan disbursement, FD maturity) | Bank / Manual Journal |
-| `cash-out` | Cash leaves bank (FD placement, provision settlement) | Bank / Manual Journal |
-| `journal` | No cash movement (accrual, depreciation, unwinding, reval) | Manual Journals |
-| `fixed-asset` | Register/update FA module (ROU asset, capital project) | Fixed Assets |
-| `note` | Instruction only (deregister FA on disposal) | N/A |
+| `bill` | Supplier document (prepaid expense) | `create_bill` |
+| `invoice` | Customer document (deferred revenue) | `create_invoice` |
+| `cash-in` | Cash arrives in bank (loan disbursement, FD maturity) | `create_cash_in` |
+| `cash-out` | Cash leaves bank (FD placement, provision settlement) | `create_cash_out` |
+| `journal` | Accrual, depreciation, unwinding, installment split | `create_journal` |
+| `fixed-asset` | Instruction: register the asset (ROU asset) | `create_fixed_asset` |
+| `note` | Instruction: update the FA register on disposal | `mark_fixed_asset_sold` / `discard_fixed_asset` |
+
+Account names in `lines` are labels to map to real accounts, and cash entries post ACTIVE immediately (no draft state): post a future-dated cash step when the money moves. A cash step can only carry lines on the side opposite the bank: if a cash-in or cash-out step has another line on the bank's side (for example withholding tax), post the net cash entry and a separate journal for that line.
 
 **Math guarantees:**
 - `financial` npm package (TypeScript port of numpy-financial) for PV, PMT, no hand-rolled TVM
@@ -273,87 +284,13 @@ Every calculator's `--json` output includes a `blueprint` object, a complete exe
 - DDB→SL switch when straight-line >= declining balance or when DDB would breach salvage floor
 - All journal entries balanced (debits = credits in every step)
 
-## Agent Tools (Daemon)
-
-When running as a daemon agent (`clio serve`), recipes are available via two dedicated tools:
-
-- **`plan_recipe`** (read-only): Run a calculator and see what accounts, contacts, and bank accounts are needed, no API calls. Use this first to verify requirements.
-- **`execute_recipe`** (write): Full end-to-end recipe execution (run calculator, auto-resolve accounts from chart of accounts, create capsule, post all entries). **1 tool call replaces ~20 manual tool calls.**
-
-Both tools accept all 13 recipe types: loan, lease, depreciation, prepaid-expense, deferred-revenue, fx-reval, ecl, provision, fixed-deposit, asset-disposal, accrued-expense, leave-accrual, dividend.
-
-Scheduler creation tools are also available: `create_scheduled_journal`, `create_scheduled_invoice`, `create_scheduled_bill`.
-
-## Server-side recipe execution (Jaz API)
-
-A second path: 5 IFRS recipes (Loan Amortization, Accrual Reversal, Prepaid Amortization, Deferred Revenue, IFRS 16 Lease) also have a SERVER-SIDE lifecycle via Jaz REST. This produces real capsule entities + scheduler atoms (recurring journal postings), distinct from the offline `plan_recipe` / `execute_recipe` path which is client-side compute.
-
-**Two distinct execution paths:**
-
-| Path | When to use | Tools |
-|---|---|---|
-| **Offline calculator** | Plan first, post manually. Agent has CoA picked. No need for a server-side capsule entity. Works without an API key. | `plan_recipe` → `execute_recipe` |
-| **Server-side trigger** | "Create the bill AND the prepaid amortization schedule in one shot." Capsule entity needed for FE/reporting. Requires API key. | Trigger via `capsuleRecipe` payload on `create_bill` / `create_invoice` / `create_journal` / `create_cash_in` / `create_cash_out` (and their `update_*` variants), OR standalone `preview_capsule_recipe` first. |
-
-**Server-side tools** (group: `capsule_recipes`):
-
-- `list_capsule_recipes` (read-only): list registered IFRS recipes + per-version JSON Schemas. SOURCE OF TRUTH for `recipeName` values; don't hard-code.
-- `get_capsule_recipe(name)` (read-only): one descriptor by enum name with `versions[].inputSchema`.
-- `preview_capsule_recipe({recipeName, recipeVersion?, inputs, baseTransactionResourceId?, baseTransactionType?, organizationResourceId?})` (read-only): pure compute, no side effects. Returns `{legs[], expectedOutput[], previewMarkdown}`. Use BEFORE triggering via `capsuleRecipe` payload to validate inputs.
-- `resume_capsule_recipe(capsuleResourceId)` (write, NOT idempotent): retry a FAILED recipe job from its failed leg. ≤3 same-leg attempts then terminal `BLOCKED_AFTER_3_RESUME_ATTEMPTS`.
-- `rollback_capsule_recipe(capsuleResourceId, dryRun?: boolean)` (write; dryRun IS idempotent): delete every scheduler atom created by the recipe. Preview with `dryRun=true` before committing.
-
-**Trigger-mutation payload**: to create a base-trx AND fire a recipe in one shot, pass `capsuleRecipe: {recipeName, recipeVersion?, inputs}` to the create/update mutation. Mutually exclusive with `capsuleResourceId` (the "attach to existing capsule" path).
-
-### Three pre-flight gates BEFORE sending `capsuleRecipe` (else the response silently nulls)
-
-The trigger mutation is **best-effort post-commit**: if the recipe publish fails inside customer-service, the base-trx still commits, the response still returns its normal success status (201 on create, 200 on update), but `capsuleRecipeJob` is null and **no error reason is surfaced on the response body**. Three causes of silent null; gate every one of them before sending:
-
-| Gate | Constraint | Pre-flight check |
-|---|---|---|
-| **Base trx type** | `recipeName` must match a trigger mutation in the recipe's `allowedBaseTransactionTypes`. PREPAID_AMORTIZATION→PURCHASE, DEFERRED_REVENUE→SALE, ACCRUAL_REVERSAL→JOURNAL_MANUAL, IFRS16_LEASE→JOURNAL_MANUAL, LOAN_AMORTIZATION→JOURNAL_DIRECT_CASH_IN \| JOURNAL_MANUAL | `get_capsule_recipe(name).allowedBaseTransactionTypes` ↔ trigger mutation |
-| **Currency** | Recipe `currency`, every `*AccountResourceId` account's `currencyCode`, and base trx `currencyCode` ALL must match (v1 recipes are single-currency) | `currencyCode` of every input account, via `search_accounts(filter: {resourceId: {in: [<ids>]}})` |
-| **Account class** | Each `*AccountResourceId` slot has an `x-accountClass` constraint in the recipe inputSchema (Asset/Liability/Expense/Revenue) | `get_capsule_recipe(name).versions[0].inputSchema.properties.<field>['x-accountClass']` vs each account's `accountClass` from the same `search_accounts` read |
-
-**The canonical pre-flight is one call**: `preview_capsule_recipe(recipeName, inputs)`. Pure-compute (no side effects). Surfaces every input/class/currency violation as a clean 422 with a concrete `error_type`. The trigger mutation does NOT surface these; it just returns its normal success status with no `capsuleRecipeJob`. Always preview first if you can't trust the inputs.
-
-See `jaz-api` Rule 143 (silent-null failure mode + diagnosis sequence), Rule 144 (closed enum on `recipeName`), Rule 150 (RECIPE_INVALID_BASE_TRANSACTION_TYPE, preview-only, NOT trigger), Rule 156 (ERR_RECIPE_ACCOUNT_CURRENCY_MISMATCH), Rule 157 (x-accountClass slot constraint).
-
-**Recovery flow** (when `capsuleRecipeJob` is null on the response):
-
-1. **Re-run `preview_capsule_recipe`** with the same `recipeName` + `inputs`. The 422 you get back is the exact reason the trigger mutation silently nulled. Fix the input and retry.
-2. **Poll `search_background_jobs --filter '{"baseTransactionResourceId":{"eq":"<id>"}}'`**: if a `FAILED` job exists, `errorDetails` has the publish failure. If no job exists, the publish never queued (validation rejected pre-queue).
-3. **Job status `FAILED`** → `resume_capsule_recipe` (≤3 attempts) OR `rollback_capsule_recipe(dryRun=true)` first, then `rollback_capsule_recipe(dryRun=false)`. Record the judgment: `jot(kind: RECOVERY)` naming resume or rollback and the basis.
-4. **Capsule wasn't created via the recipe engine** → rollback returns 422 `RECIPE_ROLLBACK_JOB_NOT_FOUND`; use `delete_capsule` for legacy capsules.
-
-**DO NOT** use server-side execution for `fx-reval`: Jaz auto-handles ALL period-end IAS 21.23 FX translation; double-posting risk identical to the offline `execute_recipe(recipe: 'fx-reval')` warning.
-
-### Template Customization (optional): `templateOverrides`
-
-A recipe generates text for the capsule title/description, each scheduled posting's label/description, the journal-line memos, and the schedule reference. To customize any of those, pass `templateOverrides` alongside `inputs` on `preview_capsule_recipe` and on the `capsuleRecipe` trigger payload:
-
-```
-capsuleRecipe: {
-  recipeName: "LOAN_AMORTIZATION",
-  inputs: { ... },
-  templateOverrides: [
-    { slotKey: "capsule.title", template: "Loan {{loanReference}}" },
-    { slotKey: "leg.description.payment", template: "" }   // empty string clears a nullable slot
-  ]
-}
-```
-
-Discovery + rules:
-- **Discover the slots first**: `get_capsule_recipe(name).data.versions[].templateSlots[]` lists each `slotKey`, its `uiLabel`, `defaultTemplate`, `supportedVariables`, and `nullable`. Send only the slots you change.
-- Each `slotKey` MUST be one the recipe publishes; every `{{var}}` in `template` MUST be in that slot's `supportedVariables`; `template` ≤2000 chars; an empty `template` clears a `nullable` slot (omit the entry to keep the default; a non-nullable slot rejects a blank).
-- **Preview is the gate.** `preview_capsule_recipe` surfaces override mistakes as clean 422 `ERR_RECIPE_OVERRIDE_*` codes. On the trigger path, an invalid override falls under the same best-effort silent-null behavior as everything else in the payload (see the three gates above), so preview before you trigger.
-- CLI: `clio capsule-recipes get <name>` prints the slots; `clio capsule-recipes preview --recipe <name> --inputs '{...}' --template-override capsule.title='Loan {{loanReference}}'` (repeatable).
-
 ## See Also
 
 - **API field names and payloads**: Load the `jaz-api` skill (see `references/endpoints.md` and `references/field-map.md`)
+- **Three-step flow, action-to-tool mapping, capsule rules**: `references/building-blocks.md`
 - **Capsule API**: `POST /capsules`, `POST /capsuleTypes` (see api skill's `references/full-api-surface.md`)
 - **Scheduler API**: `POST /scheduled/journals`, `POST /scheduled/invoices`, `POST /scheduled/bills`
 - **Fixed Assets API**: `POST /fixed-assets` (see api skill's `references/feature-glossary.md`)
 - **Enrichments overview**: See `references/building-blocks.md` or api skill's `references/feature-glossary.md`
-- **Operational close workflows (jaz-jobs)**: For the close playbooks that drive these recipes, load the `jaz-jobs` skill: month-end close (period-end recognition + accruals + FX reval), GST/VAT filing (ECL review during return prep), and year-end close (year-end true-ups, dividends, intercompany elimination).
+- **Scheduler tools**: `create_scheduled_journal`, `create_scheduled_invoice`, `create_scheduled_bill`
+- **Operational close workflows (jaz-jobs)**: For the close playbooks that drive these recipes, load the `jaz-jobs` skill: month-end close (period-end recognition + accruals + a check of the platform's FX revaluation), GST/VAT filing (ECL review during return prep), and year-end close (year-end true-ups, dividends, intercompany elimination).