jaz-clio 5.74.2 → 6.0.0

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

@@ -1,21 +1,23 @@
-# Recipe: Dividend (engine name: `dividend`)
+# Recipe: Dividend (calculator type: `dividend`)
 
-> Two-step (or three-step with withholding) recipe for board-declared dividends. Engine emits 1 journal (declaration) + 1 cash-out (payment) + optional 1 cash-out (withholding tax remit). One-shot recipe: no schedule. Used annually (final dividend) or interim (mid-year).
+> Two-step (or three-step with withholding) recipe for board-declared dividends. One journal (declaration), one cash-out (payment) and, with withholding tax, the withholding entries. One-shot recipe: no schedule. Used annually (final dividend) or interim (mid-year). You calculate, create the capsule and post each entry yourself (see `building-blocks.md` § The three-step flow).
 
-## Tools, recipes, calculators this recipe uses
+## Tools and calculator this recipe uses
 
-### Recipe engine entry point
-- **`plan_recipe(recipe: 'dividend', ...)`** (used in step 2): returns RecipePlan with declaration journal + payment cash-out + optional withholding cash-out.
-- **`execute_recipe(recipe: 'dividend', ...)`** (used in step 4): posts 2-3 entries (no future-dated DRAFTs: dividend is point-in-time).
+### Calculator (offline, posts nothing)
+- **MCP: `calculate(type: 'dividend', amount, declarationDate, paymentDate, withholdingRate, currency)`** (step 1).
+- **CLI: `clio calc dividend --amount <gross> --declaration-date <YYYY-MM-DD> --payment-date <YYYY-MM-DD> --withholding-rate <%> --currency <code> --json`** (step 1): the same result. Both dates are required.
 
-### Calculator (cross-check, no API key needed)
-- **`clio calc dividend --amount <gross> --withholding-rate <%> --currency <code> --json`** (used in step 1): computes net dividend payable to shareholder + withholding tax to remit. Returns `{ grossAmount, withholdingTax, netToShareholder }`.
+### Posting tools
+- **`list_capsule_types` / `create_capsule_type(displayName: 'Dividends')` / `create_capsule(...)`** (step 3).
+- **`create_journal(...)`** (step 4): the declaration, and the withholding transfer when tax is withheld.
+- **`create_cash_out(...)`** (step 4): the payment to shareholders, and later the remittance of the withheld tax.
 
-### Tools (jaz-api / direct)
-- **`search_capsules(filter: {title: {eq: <capsule.name>}})`**: step 0 idempotency check. Each declared dividend gets its own capsule; duplicate setup means double-declaration.
-- **`search_accounts(filter: {name: {in: ['Retained Earnings', 'Dividends Payable', 'Withholding Tax Payable']}})`**: step 3.
-- **`search_contacts(filter: {name: {eq: <shareholder>}})`**: step 3 (the payee, typically a shareholder or a holding entity).
-- **`generate_balance_sheet(snapshotDate: <date>)`** (step 5 verification): Retained Earnings reduced; Dividends Payable nil after payment.
+### Lookup and verification tools
+- **`search_capsules(filter: {title: {eq: <capsule title>}})`**: step 0 idempotency check. Each declared dividend gets its own capsule; duplicate setup means double-declaration.
+- **`search_accounts(filter: {name: {in: ['Retained Earnings', 'Dividends Payable', 'Withholding Tax Payable']}})`**: step 2.
+- **`search_contacts(filter: {name: {eq: <shareholder>}})`**: step 2 (the payee, typically a shareholder or a holding entity).
+- **`generate_balance_sheet(snapshotDate: <date>)`** (step 2 pre-check and step 5 verification): Retained Earnings available before declaring; reduced after; Dividends Payable nil after payment.
 - **`generate_equity_movement(primarySnapshotStartDate, primarySnapshotEndDate)`** (step 5): dividends appear as a distinct line item in equity movement, separate from net profit.
 
 ### Cross-references
@@ -33,65 +35,101 @@
 search_capsules(filter: {title: {eq: 'FY2025 Final Dividend'}})
 ```
 
-If a result returns: halt and surface "Dividend capsule `<name>` already exists. Re-running would create a duplicate declaration. Confirm: if posting an interim dividend, use a different capsule name (e.g., `Q3 2025 Interim Dividend`)."
+If a result returns: halt and surface "Dividend capsule `<name>` already exists. Re-posting would create a duplicate declaration. Confirm: if posting an interim dividend, use a different capsule title (e.g., `Q3 2025 Interim Dividend`)."
 
-### Step 1: Independent cross-check (calculator)
+### Step 1: Calculate
 
 ```
-clio calc dividend --amount 200000 --withholding-rate 0 --currency SGD --json
+calculate(
+  type: 'dividend',
+  amount: 200000,
+  withholdingRate: 0,
+  declarationDate: '2025-12-31',
+  paymentDate: '2026-03-15',
+  currency: 'SGD'
+)
 ```
 
-Returns: `{ grossAmount: 200000, withholdingTax: 0, netToShareholder: 200000 }` for SG (no withholding on dividends from SG-resident companies: SG operates a one-tier corporate tax system, dividends are tax-exempt at the shareholder level under ITA s13(1)(z)).
-
-For PH or jurisdictions with withholding (e.g., 10% PH dividend WHT to non-resident foreign corporations under NIRC §28(B)(5)(b)):
-
 ```
-clio calc dividend --amount 200000 --withholding-rate 10 --currency PHP --json
-# → { grossAmount: 200000, withholdingTax: 20000, netToShareholder: 180000 }
+clio calc dividend --amount 200000 --declaration-date 2025-12-31 --payment-date 2026-03-15 --withholding-rate 0 --currency SGD --json
 ```
 
-### Step 2: Plan the recipe
+Returns `{ grossAmount: 200000, netToShareholders: 200000, withholdingTax: 0, declarationJournal, paymentJournal, withholdingJournal: null, blueprint }` for SG (no withholding on dividends from SG-resident companies: SG operates a one-tier corporate tax system, dividends are tax-exempt at the shareholder level under ITA s13(1)(z)).
+
+For PH or jurisdictions with withholding (e.g., 10% PH dividend WHT to non-resident foreign corporations under NIRC §28(B)(5)(b)):
 
 ```
-plan_recipe(
-  // Accounts, capsule and counterparty are not plan_recipe params: execute_recipe resolves accounts from the CoA and takes bankAccountName / contactName.
-  recipe: 'dividend',
-  amount: 200000,
-  withholdingRate: 0,
-  declarationDate: '2025-12-31',
-  paymentDate: '2026-03-15',
-  currency: 'SGD'
-)
+clio calc dividend --amount 200000 --declaration-date 2025-12-31 --payment-date 2026-03-15 --withholding-rate 10 --currency PHP --json
+# → { grossAmount: 200000, netToShareholders: 180000, withholdingTax: 20000, ... }
 ```
 
-Returns `RecipePlan` with `requiredAccounts: ['Retained Earnings', 'Dividends Payable', 'Cash / Bank Account']` (+ `Withholding Tax Payable` if `withholdingRate > 0`), `needsContact: false` (shareholder is metadata only), `needsBankAccount: true`, `steps`:
-- Step 1: declaration journal dated `declarationDate`, Dr Retained Earnings 200,000 / Cr Dividends Payable 200,000
-- Step 2: payment cash-out dated `paymentDate`, Dr Dividends Payable 200,000 / Cr Cash 200,000 (or net amount if withholding)
-- Step 3 (if withholdingRate > 0): withholding cash-out dated `paymentDate`, Dr Dividends Payable (withholding portion) / Cr Withholding Tax Payable
+`blueprint.steps`:
+- Step 1, `journal`, dated `declarationDate`: Dr Retained Earnings 200,000 / Cr Dividends Payable 200,000.
+- Step 2, `cash-out`, dated `paymentDate`: Dr Dividends Payable 200,000 / Cr Cash / Bank Account 200,000. With withholding: Dr Dividends Payable 200,000 / Cr Cash / Bank Account 180,000 / Cr Withholding Tax Payable 20,000.
+- Step 3 (only if `withholdingRate > 0`), `cash-out`, dated `paymentDate`: the remittance to the tax authority, Dr Withholding Tax Payable 20,000 / Cr Cash / Bank Account 20,000.
 
-### Step 3: Resolve dependencies
+### Step 2: Resolve accounts, bank account and distributable profits
 
-For each account in `requiredAccounts`:
-- `search_accounts(filter: {name: {eq: <accountName>}})`. Suggested classifications: `Retained Earnings` → `Shareholders Equity`; `Dividends Payable` → `Current Liability`; `Withholding Tax Payable` → `Current Liability`.
+The blueprint's account names are labels. Map each to the real account:
+- `search_accounts(filter: {name: {in: ['Retained Earnings', 'Dividends Payable', 'Withholding Tax Payable']}})`. Suggested classifications: `Retained Earnings` → `Shareholders Equity`; `Dividends Payable` → `Current Liability`; `Withholding Tax Payable` → `Current Liability`.
 
 If `Dividends Payable` doesn't exist: `create_account(name: 'Dividends Payable', code: <unused account code>, accountType: 'Current Liability', currencyCode: <base currency>)` first. This is a common gap in CoAs that haven't paid dividends before.
 
-Bank account: resolve `bankAccountResourceId` via `list_bank_accounts()` if the bank account resourceId isn't already known.
+Bank account: `list_bank_accounts()` if the bank account resourceId isn't already known.
 
 Shareholder contact: optional but recommended for narrative tagging. `search_contacts(filter: {name: {eq: <shareholder>}})`. If empty: `create_contact(name: <shareholder>, customer: false, supplier: false)`; mark as "other" / shareholder type if your CoA has a custom field for that.
 
-### Step 4: Execute
+**Distributable profits check.** Nothing blocks a declaration that exceeds retained earnings, so check it yourself: `generate_balance_sheet(snapshotDate: <declarationDate>)`. If the dividend would push Retained Earnings negative, halt and surface: "Declaration would result in a dividend out of capital. Verify available retained earnings." In Singapore a dividend is payable only out of profits (Companies Act s403).
+
+### Step 3: Create the capsule
+
+```
+list_capsule_types()
+create_capsule(
+  capsuleTypeResourceId: <id of 'Dividends'>,
+  title: 'FY2025 Final Dividend',
+  description: <blueprint.capsuleDescription>
+)
+```
+
+If `Dividends` is not in the list: `create_capsule_type(displayName: 'Dividends')` first.
+
+### Step 4: Post the entries
+
+**4a. Declaration** (blueprint step 1), dated the board resolution date:
+
+```
+create_journal(
+  valueDate: '2025-12-31',
+  reference: 'DIV-FY2025-DECL',
+  journalEntries: [
+    { accountResourceId: <Retained Earnings>, type: 'DEBIT', amount: 200000, description: 'Dividend declaration, FY2025 final' },
+    { accountResourceId: <Dividends Payable>, type: 'CREDIT', amount: 200000, description: 'Dividend declaration, FY2025 final' }
+  ],
+  saveAsDraft: false,
+  capsuleResourceId: <capsule id>
+)
+```
+
+**4b. Payment** (blueprint step 2). Post it on the actual payment date, once the money has left the bank account: a cash entry posts ACTIVE immediately and has no draft state, so a payment recorded ahead of time is a live bank payment that has not happened, which the bank reconciliation will not match until the real payment arrives.
 
 ```
-execute_recipe(recipe: 'dividend', ...same args...)  // accounts auto-resolved from CoA; pass `bankAccountName` / `contactName` for fuzzy resolve
+create_cash_out(
+  valueDate: '2026-03-15',
+  accountResourceId: <bank account>,
+  reference: 'DIV-FY2025-PAY',
+  lines: [{ accountResourceId: <Dividends Payable>, amount: 200000, description: 'Dividend payment to shareholders' }],
+  capsuleResourceId: <capsule id>
+)
 ```
 
-Returns: `{ capsule: {resourceId, type, title}, steps: [{step, action, status, resourceId}, ...], summary: {total: 2 or 3, created: 2 or 3} }`. The recipe creates 2 entries (or 3 with withholding), all attached to the same capsule:
-- Declaration journal (DRAFT or ACTIVE per `finalize` flag)
-- Payment cash-out: posted ACTIVE immediately, dated `paymentDate`. Cash entries have no draft state, so `finalize` does not apply and there is nothing to finalize later.
-- Withholding cash-out: same, posted ACTIVE immediately, dated `paymentDate`.
+**With withholding tax** the payment step has a credit to Withholding Tax Payable beside the bank line, and a cash-out can only debit its lines. Split it in two, both dated `paymentDate`:
+- `create_cash_out` for the NET amount (180,000) against Dividends Payable.
+- `create_journal`: Dr Dividends Payable 20,000 / Cr Withholding Tax Payable 20,000.
+
+Together they clear Dividends Payable (200,000) and leave the withheld tax owing to the authority.
 
-**Run the recipe on the actual payment date**, once the money has left the bank account. The declaration journal still carries `declarationDate`, so booking it late puts it in the right period. Running at declaration time instead posts a live bank payment that has not happened yet, which the bank reconciliation will not match until the real payment arrives. If the declaration must be booked before the payment (for example at FY-end), post the declaration alone with `create_journal` (Dr Retained Earnings / Cr Dividends Payable) and record the payment with `create_cash_out` when the money leaves the account.
+**4c. Withholding remittance** (blueprint step 3). When the tax is actually remitted: `create_cash_out` for 20,000 against Withholding Tax Payable, with `capsuleResourceId`.
 
 ### Step 5: Verify (after the declaration is finalized and the payment is posted)
 
@@ -110,22 +148,21 @@ After payment posted (Mar 15, 2026):
 
 After payment AND WHT remittance:
 - `balance['Withholding Tax Payable']` back to 0.
-- Capsule lifecycle complete; close via a manual `update_capsule(title: '<original> [CLOSED]')` (the API has no `status` field for capsules; closure is informational only).
+- Capsule lifecycle complete; close via a manual `update_capsule(resourceId: <id>, title: '<original> [CLOSED]')` (the API has no `status` field for capsules; closure is informational only).
 
 ---
 
-## Common error classes and recovery
+## Common problems and recovery
 
-| Source | Error | Recovery |
+| Where | Problem | Recovery |
 |--------|-------|----------|
-| `plan_recipe` | 422 `unsupported_recipe` | Use canonical engine name `dividend` (already canonical). |
-| `plan_recipe` | 422 `withholding_rate_invalid` | Rate must be 0-100. Verify jurisdiction; SG = 0; PH non-resident foreign = 10% (NIRC §28(B)(5)(b)); others vary by treaty. |
-| `execute_recipe` | 422 `account_not_found` | Step 3 incomplete. `Dividends Payable` is the most-commonly-missing account. Create via `create_account`. |
-| `execute_recipe` | 422 `negative_retained_earnings` | The dividend would push Retained Earnings negative. SG ITA s403(2): companies cannot declare dividends out of capital (must be from accumulated profits). Halt and surface to practitioner: "Declaration would result in dividend out of capital. Verify available retained earnings via `generate_balance_sheet`." |
-| `execute_recipe` | 422 `currency_mismatch_bank_account` | Dividend currency ≠ bank account currency. Pass `currency` matching the disbursement bank, or model as FX cash-out (different `paymentAmount` and `transactionAmount`). |
-| Step 5 verification | Net Profit affected by dividend | Should NEVER happen via recipe (engine debits Retained Earnings, not P&L). If TB shows P&L impact: practitioner posted a manual journal mis-mapping. Reverse and re-run via recipe. |
-| Withholding tax remitted but `Withholding Tax Payable` still nonzero | (process gap) | Practitioner forgot to post the WHT remittance to authority. Post `create_cash_out` with line: Dr Withholding Tax Payable / Cr Cash for the WHT amount. |
-| Interim dividend declared after final dividend already in capsule | (process) | Use a NEW capsule name (e.g., `Q1 2026 Interim Dividend` if it's the next FY's interim). Idempotency check protects against duplicate same-name. |
+| Calculator | Withholding rate questioned | The rate is a percentage (10 = 10%). Verify jurisdiction; SG = 0; PH non-resident foreign = 10% (NIRC §28(B)(5)(b)); others vary by treaty. |
+| Step 2 | `Dividends Payable` is missing | The most-commonly-missing account. Create via `create_account`. |
+| Step 2 | Dividend exceeds retained earnings | Halt (see the distributable profits check). Do not post the declaration. |
+| `create_cash_out` | Dividend currency ≠ bank account currency | Pay from a bank account in the dividend's currency, or record the FX on the cash-out. |
+| Step 5 verification | Net Profit affected by dividend | Should NEVER happen: the declaration debits Retained Earnings, not P&L. If the TB shows P&L impact, a journal was mis-mapped to an expense account. Reverse it and re-post against Retained Earnings. |
+| Withholding tax remitted but `Withholding Tax Payable` still nonzero | (process gap) | The WHT remittance to the authority was not posted. Post `create_cash_out` with a line against Withholding Tax Payable for the WHT amount. |
+| Interim dividend declared after final dividend already in capsule | (process) | Use a NEW capsule title (e.g., `Q1 2026 Interim Dividend` if it's the next FY's interim). The idempotency check protects against a duplicate same-title capsule. |
 
 ---
 
@@ -133,16 +170,15 @@ After payment AND WHT remittance:
 
 - **Interim dividend** (mid-year, ad-hoc): same recipe, different `declarationDate` and capsule name. Sometimes paid same day as declaration → `paymentDate == declarationDate`.
 - **Stock dividend** (bonus shares, no cash): NOT supported by this recipe. Manual journal pattern: Dr Retained Earnings / Cr Share Capital (or Bonus Issue Reserve) for the par value of new shares issued.
-- **Multiple shareholders with different proportions**: For each shareholder, run `plan_recipe + execute_recipe` separately with their portion of the dividend. Each gets its own capsule for traceability. Or run one combined recipe with the total amount and use journal narratives + tags to split.
-- **Cross-border dividend with treaty rate**: pass the treaty `withholdingRate` (e.g., SG-MY DTA dividend WHT is 0%-10% depending on shareholding). Practitioner confirms treaty applicability before invoking.
+- **Multiple shareholders with different proportions**: Either calculate and post each shareholder's portion separately (each with its own capsule for traceability), or post one combined dividend for the total and use journal narratives + tags to split.
+- **Cross-border dividend with treaty rate**: pass the treaty `withholdingRate` (e.g., SG-MY DTA dividend WHT is 0%-10% depending on shareholding). Practitioner confirms treaty applicability before posting.
 - **Dividend in foreign currency**: pass `currency: 'USD'` (e.g., dividend to USD-denominated holding company). Per `jaz-api/SKILL.md` rule 25, payment cash-out uses `currency: { sourceCurrency: 'USD' }`. Jaz auto-handles FX revaluation of any USD-denominated `Dividends Payable` outstanding at period-end.
-- **Scrip dividend** (option to receive cash or shares): NOT supported. Two recipe invocations OR manual pattern depending on take-up.
+- **Scrip dividend** (option to receive cash or shares): NOT supported. Cash portion via this recipe, share portion via the stock-dividend manual pattern, depending on take-up.
 
 ---
 
 ## Cross-references
 
-- Year-end close (Y3 in year-end-close): final FY dividend declaration AFTER the FY's audited net profit is determined. The declared amount and withholding rate drive the recipe inputs.
-- Month-end close: interim dividends declared mid-year are posted in the month they were declared. The payment cash-outs post ACTIVE the moment the recipe runs, so run it once the bank disbursement has happened (typically next month), or book the declaration alone with `create_journal` in the declaration month and record the payment with `create_cash_out` when it is made.
+- Year-end close (Y3 in year-end-close): final FY dividend declaration AFTER the FY's audited net profit is determined. The declared amount and withholding rate are the calculator inputs.
+- Month-end close: interim dividends declared mid-year are posted in the month they were declared. Book the declaration with `create_journal` in the declaration month; record the payment with `create_cash_out` only when the bank disbursement has happened (typically next month), because a cash entry posts ACTIVE immediately.
 - `audit-prep.md` step 8: auditor reviews `generate_equity_movement` to verify dividends are correctly classified as equity reduction (not P&L expense).
-- `statutory-filing.md`: SG Form C-S Box 12 (dividends paid during YA) reads from this capsule's payment cash-out entries.

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

@@ -1,138 +1,176 @@
-# Recipe: Employee Benefit Accruals (engine names: `leave-accrual` + `accrued-expense`)
+# Recipe: Employee Benefit Accruals (calculator types: `leave-accrual` + `accrued-expense`)
 
-> Two distinct patterns in one reference: monthly leave accrual (engine `leave-accrual`, no reversal) + quarterly/annual bonus accrual (engine `accrued-expense`, reversal pattern). IAS 19 employee benefits.
+> Two distinct patterns in one reference: monthly leave accrual (calculator `leave-accrual`, no reversal) + quarterly/annual bonus accrual (calculator `accrued-expense`, reversal pattern). IAS 19 employee benefits. You calculate, create the capsule and post each entry yourself (see `building-blocks.md` § The three-step flow).
 
-## Why two engines
+## Why two calculators
 
-- **Leave accrual**: accumulates monthly as employees earn leave entitlement. NO reversal pattern (employees don't unaccumulate leave). Released into actual leave taken / paid out via separate journals. Engine: `leave-accrual`.
-- **Bonus accrual**: accrues each quarter against an estimate, reversed at quarter-start, fresh accrual at quarter-end. Same pattern as utility/electricity accrual. Engine: `accrued-expense`.
+- **Leave accrual**: accumulates monthly as employees earn leave entitlement. NO reversal pattern (employees don't unaccumulate leave). Released into actual leave taken / paid out via separate journals. Calculator: `leave-accrual`.
+- **Bonus accrual**: accrues each quarter against an estimate, reversed at quarter-start, fresh accrual at quarter-end. Same pattern as utility/electricity accrual. Calculator: `accrued-expense`.
 
-The two patterns share the same `Employee Benefits` capsule type but use different engines. Each gets its own capsule invocation per FY.
+The two patterns share the `Employee Benefits` capsule type but use different calculators. Each gets its own capsule per FY.
 
-## Tools, recipes, calculators this recipe uses
+## Tools and calculators this recipe uses
 
-### Recipe engine entry points
+### Calculators (offline, post nothing)
 
-**Leave (engine: `leave-accrual`):**
-- **`plan_recipe(recipe: 'leave-accrual', ...)`** (used in step 2A): returns RecipePlan with N future-dated DRAFT accrual journals (one per month, fixed amount). NO reversal.
-- **`execute_recipe(recipe: 'leave-accrual', ...)`** (used in step 4A): posts N future-dated DRAFT journals upfront.
+**Leave:**
+- **MCP: `calculate(type: 'leave-accrual', employees, daysPerYear, dailyRate, periods, startDate, currency)`** (step 1A).
+- **CLI: `clio calc leave-accrual --employees <n> --days <days per employee per year> --daily-rate <amt> --periods <months> --start-date <YYYY-MM-DD> --currency <code> --json`**: the same result. Returns `{ totalAnnualCost, periodAccrual, schedule[periods], blueprint }`.
 
-**Bonus (engine: `accrued-expense`):**
-- **`plan_recipe(recipe: 'accrued-expense', amount: <quarterly bonus est>, periods: 1, ...)`** (used in step 2B): returns 2-journal pair (accrual at period-end + reversal at next-period-start). See `accrued-expenses.md` for the full pattern.
+**Bonus:**
+- **MCP: `calculate(type: 'accrued-expense', amount: <quarterly bonus est>, periods: 1, startDate, currency)`** (step 1B): returns the accrual + reversal pair. See `accrued-expenses.md` for the full pattern.
+- **CLI: `clio calc accrued-expense --amount <quarterly bonus> --periods 1 --start-date <YYYY-MM-DD> --json`**.
 
-### Calculators
-- **`clio calc leave-accrual --headcount <n> --days-per-employee <days> --daily-rate <amt> --periods <months> --start-date <YYYY-MM-DD> --currency <code> --json`**: leave cross-check. Returns `{ totalAnnualCost, perPeriodAmount, schedule[periods] }`.
-- **`clio calc accrued-expense --amount <quarterly bonus> --periods 1 --json`**: bonus cross-check.
+### Posting tools
+- **`list_capsule_types` / `create_capsule_type(displayName: 'Employee Benefits')` / `create_capsule(...)`**.
+- **`create_scheduled_journal(...)`** (leave: the same amount every month) or **`create_journal(...)`** per period.
+- **`create_journal(...)`** (bonus: accrual and reversal).
 
-### Tools (jaz-api / direct)
-- **`search_capsules(filter: {status: {eq: 'ACTIVE'}}) (capsule type is not filterable; see `jobs/references/building-blocks.md` § Filter limits)`** (step 0): discover existing leave + bonus capsules.
-- **`search_accounts(filter: {name: {in: ['Leave Expense', 'Leave Liability', 'Bonus Expense', 'Bonus Payable']}})`**: step 3.
-- **`search_journals(filter: {tags: {eq: 'leave-accrual'}, valueDate: {between: [<period-start>, <period-end>]}, status: {eq: 'DRAFT'}})`** (step 5 monthly): pull this period's pre-emitted leave DRAFT.
-- **`bulk_update_journals(items: [{resourceId: <id>, saveAsDraft: false}, ...])`**: monthly finalize.
+### Lookup and verification tools
+- **`search_capsules(filter: {status: {eq: 'ACTIVE'}})`** (step 0; capsule type is not filterable, see `jobs/references/building-blocks.md` § Filter limits): discover existing leave + bonus capsules.
+- **`search_accounts(filter: {name: {in: ['Leave Expense', 'Leave Liability', 'Bonus Expense', 'Bonus Payable']}})`**: resolve accounts.
+- **`search_journals(filter: {reference: {eq: <period reference>}})`** (monthly): find this period's journal.
+- **`update_journal(resourceId: <id>, saveAsDraft: false)`**: monthly finalize of a draft.
 - **`generate_trial_balance(endDate: <date>)`**: verification.
 - For year-end true-up: see `year-end-close.md` Y2 (manual journal pattern with HR-supplied actuals).
 
 ### Cross-references
 - Operational context: invoked during month-end close (monthly leave) and during year-end close (Y2 in `year-end-close.md`, bonus accrual true-up).
-- Sibling: `accrued-expenses.md` (the engine that drives the bonus pattern); `dividend.md` (annual P&L distribution to shareholders, mirror to bonus).
+- Sibling: `accrued-expenses.md` (the calculator that drives the bonus pattern); `dividend.md` (annual P&L distribution to shareholders, mirror to bonus).
 - IFRS / accounting context: IAS 19.11 (short-term employee benefits, recognized as expense in the period the service is rendered); IAS 19.13 (accrual of leave entitlement); IAS 19.19 (recognition criteria for bonuses: present obligation + reliable estimate).
 
 ---
 
-## Pattern A: Monthly leave accrual (engine: `leave-accrual`)
+## Pattern A: Monthly leave accrual (calculator: `leave-accrual`)
 
 ### Step 0A: Idempotency check
 
 ```
-search_capsules(filter: {title: {eq: 'Annual Leave Accrual — FY2025'}})
+search_capsules(filter: {title: {eq: 'Annual Leave Accrual, FY2025'}})
 ```
 
 If returns: halt. One leave capsule per FY.
 
-### Step 1A: Cross-check (calculator)
+### Step 1A: Calculate
 
 ```
-clio calc leave-accrual --employees 20 --days 14 --daily-rate 300 --periods 12 --start-date 2025-01-01 --currency SGD --json
-```
-
-Returns: `{ totalAnnualCost: 84000, perPeriodAmount: 7000, schedule: [{period: 1, accrualDate: '2025-01-31', accrualAmount: 7000, journal: {...}}, ...12] }`. `daily-rate` should be average daily compensation rate (annual salary / 260 working days).
-
-### Step 2A: Plan + execute
-
-```
-plan_recipe(
-  // Accounts, capsule and counterparty are not plan_recipe params: execute_recipe resolves accounts from the CoA and takes bankAccountName / contactName.
-  recipe: 'leave-accrual',
+calculate(
+  type: 'leave-accrual',
   employees: 20,
   daysPerYear: 14,
   dailyRate: 300,
   periods: 12,
-  startDate: '2025-01-01',
+  startDate: '2025-01-31',
   currency: 'SGD'
 )
-execute_recipe(recipe: 'leave-accrual', ...same args...)  // accounts auto-resolved from CoA; pass `bankAccountName` / `contactName` for fuzzy resolve
 ```
 
-Engine emits **12 future-dated DRAFT journals** (one per month, fixed $7,000 each: Dr Leave Expense / Cr Leave Liability).
+```
+clio calc leave-accrual --employees 20 --days 14 --daily-rate 300 --periods 12 --start-date 2025-01-31 --currency SGD --json
+```
+
+Returns: `{ totalAnnualCost: 84000, periodAccrual: 7000, schedule: [{ period: 1, date: '2025-01-31', accrual: 7000, cumulativeBalance: 7000, journal }, ...12], blueprint }`. `dailyRate` should be the average daily compensation rate (annual salary / 260 working days). The first accrual is dated ON the start date, so pass the first month-end.
+
+`blueprint.steps`: 12 `journal` steps, one per month: Dr Leave Expense 7,000 / Cr Accrued Leave Liability 7,000.
+
+### Step 2A: Resolve accounts and create the capsule
+
+Map the labels `Leave Expense` and `Accrued Leave Liability` to real accounts with `search_accounts` (create with `create_account` if missing: expense → `Operating Expense`; liability → `Current Liability`). Then:
+
+```
+list_capsule_types()
+create_capsule(
+  capsuleTypeResourceId: <id of 'Employee Benefits'>,
+  title: 'Annual Leave Accrual, FY2025',
+  description: <blueprint.capsuleDescription>
+)
+```
+
+If `Employee Benefits` is not in the list: `create_capsule_type(displayName: 'Employee Benefits')` first.
+
+### Step 3A: Post the accruals
+
+The amount is the same every month, so one schedule replaces the twelve journals:
+
+```
+create_scheduled_journal(
+  startDate: '2025-01-31',
+  endDate: '2025-12-31',
+  repeat: 'MONTHLY',
+  valueDate: '2025-01-31',
+  reference: 'LEAVE-FY2025',
+  schedulerEntries: [
+    { accountResourceId: <Leave Expense>, type: 'DEBIT', amount: 7000, description: 'Leave accrual: {{MONTH_NAME}} {{YEAR}}' },
+    { accountResourceId: <Leave Liability>, type: 'CREDIT', amount: 7000, description: 'Leave accrual: {{MONTH_NAME}} {{YEAR}}' }
+  ],
+  capsuleResourceId: <capsule id>
+)
+```
+
+Read `building-blocks.md` § "Same amount every period" for the schedule's limits (fixed amount, so if the final period differs by a rounding cent end the schedule one period early and post the last journal by hand). With `capsuleResourceId` on the schedule, every journal it generates lands in the capsule. The alternative is one `create_journal` per blueprint step, each with `valueDate` = the step date, a findable `reference` (`LEAVE-FY2025-01` ...) and `capsuleResourceId`.
 
-### Step 5A: Monthly action
+### Step 4A: Monthly action
+
+With a schedule, confirm the month's journal posted. With dated draft journals, find this month's by its reference and finalize it:
 
 ```
-**STOP: not selectable by filter.** Journals carry no capsule or fixed-asset link in either direction (`JournalFilter` declares neither; a journal row has no such field even at `view: 'full'`; `GET /capsules/{id}` returns only a `totalTransactions` count, measured 2026-09-07). A date+status search returns every matching DRAFT in the org, so it must never feed `bulk_update_journals` or `delete_journal`. Surface the capsule and its expected count to the practitioner and let them identify the journals.
+search_journals(filter: {reference: {eq: 'LEAVE-FY2025-03'}})
 update_journal(resourceId: <journal id>, saveAsDraft: false)
 ```
 
+Journals cannot be filtered by capsule, and a date-plus-status search returns every matching DRAFT in the org: never feed one into `bulk_update_journals` or `delete_journal`.
+
 When an employee actually takes leave:
 - Manual journal: Dr Leave Liability / Cr Cash (or Salary Payable) for the days × daily-rate. This RELEASES the accrued obligation.
-- The leave-accrual recipe does NOT track per-employee balances; that's HR/payroll system territory. The recipe maintains the company-level liability.
+- The leave-accrual calculator does NOT track per-employee balances; that's HR/payroll system territory. The recipe maintains the company-level liability.
 
 Year-end true-up: see `year-end-close.md` Y2a. Compare actual unused-leave-balance × daily-rate per employee at FY-end vs the cumulative accrued. Post adjustment journal for the delta.
 
 ---
 
-## Pattern B: Quarterly/annual bonus accrual (engine: `accrued-expense`)
+## Pattern B: Quarterly/annual bonus accrual (calculator: `accrued-expense`)
 
 ### Step 0B: Idempotency check
 
 ```
-search_capsules(filter: {title: {startWith: 'Bonus Accrual — Q'}})
+search_capsules(filter: {title: {startWith: 'Bonus Accrual, Q'}})
 ```
 
 If a current-quarter result returns: halt. One bonus capsule per quarter.
 
-### Step 1B: Cross-check + estimate
+### Step 1B: Estimate + calculate
 
 Estimate quarterly bonus per the entity's bonus policy estimation method:
 - `revenue_pct` (e.g., 5% of quarterly revenue): pull `generate_profit_and_loss(startDate: <quarter-start>, endDate: <quarter-end>)`, multiply Operating Revenue by the percentage.
-- `prior_quarter`: pull last quarter's posted bonus journal via `search_journals(filter: {tags: {eq: 'bonus-accrual'}, valueDate: <prior-quarter>-end})`.
+- `prior_quarter`: pull last quarter's posted bonus journal via `search_journals` on its reference.
 - `fixed_amount`: use the bonus policy's fixed amount per quarter.
 
 ```
-clio calc accrued-expense --amount <est> --periods 1 --start-date 2025-03-31 --json
-```
-
-### Step 2B: Plan + execute
-
-```
-plan_recipe(
-  // Accounts, capsule and counterparty are not plan_recipe params: execute_recipe resolves accounts from the CoA and takes bankAccountName / contactName.
-  recipe: 'accrued-expense',
+calculate(
+  type: 'accrued-expense',
   amount: <est>,
   periods: 1,
   startDate: '2025-03-31',
   currency: 'SGD'
 )
-execute_recipe(recipe: 'accrued-expense', ...)
 ```
 
-Engine emits 2 journals: accrual (Mar 31) + reversal (Apr 1). Mirror Q2 / Q3 / Q4.
+```
+clio calc accrued-expense --amount <est> --periods 1 --start-date 2025-03-31 --json
+```
+
+Returns the accrual (dated `2025-03-31`) and its reversal (the calculator dates it one month on; post it on the first day of the next quarter, `2025-04-01`).
+
+### Step 2B: Capsule + post
+
+Create a `Bonus Accrual, Q1 2025` capsule under `Employee Benefits`, then post the pair with `create_journal`, exactly as in `accrued-expenses.md` step 4: the accrual (Dr Bonus Expense / Cr Bonus Payable) on Mar 31, the reversal as a DRAFT dated Apr 1. Mirror for Q2 / Q3 / Q4.
 
-### Step 5B: Quarterly action
+### Step 3B: Quarterly action
 
 Per quarter-end-close (`quarter-end-close.md`):
-- Finalize this quarter's accrual DRAFT (in March).
+- Post this quarter's accrual (in March).
 - April's monthly-close finalizes the reversal DRAFT.
-- Create the next quarter's accrual capsule + execute.
+- Create the next quarter's accrual capsule and post its pair.
 
 ### Year-end true-up
 
@@ -140,26 +178,26 @@ Per quarter-end-close (`quarter-end-close.md`):
 
 ---
 
-## Common error classes and recovery
+## Common problems and recovery
 
-| Source | Error | Recovery |
+| Where | Problem | Recovery |
 |--------|-------|----------|
-| `plan_recipe` (leave) | 422 `unsupported_recipe` | Use canonical engine name `leave-accrual` (file alias `employee-accruals` covers BOTH leave and bonus). |
-| `plan_recipe` (bonus) | 422 `unsupported_recipe` | Use `accrued-expense` for bonus; leave is `leave-accrual`. |
-| `execute_recipe` | 422 `account_not_found` | Step 3 incomplete. Common gap: `Bonus Payable` (most CoAs lack); create via `create_account(name: 'Bonus Payable', code: <unused account code>, accountType: 'Current Liability')`. |
-| Verification | Leave Liability balance > expected | Practitioner posted manual leave-utilization journals against the wrong account, OR the original recipe estimate was high. Year-end Y2a true-up will catch this. |
-| Verification | Bonus accrual nonzero after quarterly reversal posts | Reversal didn't finalize. Identify the reversal journal (journals cannot be filtered by capsule: check each candidate with `get_journal` (its `capsule.resourceId`) and confirm the set with the practitioner), then finalize it with `update_journal(resourceId, saveAsDraft: false)`. |
-| 13th-month bonus (PH-specific) | (process, separate from Q4 bonus) | Use `accrued-expense` recipe with `amount: <annual base / 12>`, `periods: 12`, accruing throughout FY. Settle in December via Dr Bonus Payable / Cr Cash. |
+| Calculator (leave) | "Employees must be a positive number" / "Days per year must be a positive number" | Fix the input. The CLI flags are `--employees` and `--days`; the MCP params are `employees` and `daysPerYear`. |
+| Calculator | Wrong calculator for the benefit | Leave is `leave-accrual` (no reversal); bonus is `accrued-expense` (accrual + reversal). |
+| Account resolution | An account is missing | Common gap: `Bonus Payable` (most CoAs lack); create via `create_account(name: 'Bonus Payable', code: <unused account code>, accountType: 'Current Liability')`. |
+| Verification | Leave Liability balance > expected | Practitioner posted manual leave-utilization journals against the wrong account, OR the original estimate was high. Year-end Y2a true-up will catch this. |
+| Verification | Bonus accrual nonzero after quarterly reversal posts | Reversal didn't finalize. Find the reversal journal by its reference (journals cannot be filtered by capsule), then finalize it with `update_journal(resourceId, saveAsDraft: false)`. |
+| 13th-month bonus (PH-specific) | (process, separate from Q4 bonus) | Accrue `<annual base / 12>` each month throughout the FY (Dr 13th Month Expense / Cr Bonus Payable) with NO reversal, since the obligation accumulates: a monthly `create_scheduled_journal` fits. Settle in December via Dr Bonus Payable / Cr Cash. |
 
 ---
 
 ## Variations
 
-- **Profit-share bonus** (% of net profit, declared post-audit): NOT this recipe. Mirror `dividend` recipe pattern: declaration journal + payment cash-out at year-end after audit closes.
-- **PH 13th-month pay**: monthly accrual via `accrued-expense` recipe (`amount: <annual base / 12>`, `periods: 12`). Mandatory by Philippine law (PD 851). Settle in December.
-- **Long-term employee benefits** (gratuity, severance, post-employment benefits): NOT supported by these engines. Per IAS 19.55-58, requires actuarial valuation. Manual journals only; consider hiring an actuary.
+- **Profit-share bonus** (% of net profit, declared post-audit): NOT this recipe. Mirror the `dividend.md` pattern: declaration journal + payment cash-out at year-end after audit closes.
+- **PH 13th-month pay**: monthly accrual of `<annual base / 12>` with no reversal (see the problems table). Mandatory by Philippine law (PD 851). Settle in December.
+- **Long-term employee benefits** (gratuity, severance, post-employment benefits): NOT supported by these calculators. Per IAS 19.55-58, requires actuarial valuation. Manual journals only; consider hiring an actuary.
 - **Stock-based compensation**: NOT supported. IFRS 2 (separate accounting model). Manual journals only.
-- **Multi-currency leave** (employees paid in different currencies): one leave capsule per currency. Each gets its own recipe invocation.
+- **Multi-currency leave** (employees paid in different currencies): one leave capsule per currency. Each gets its own calculation.
 
 ---
 
@@ -167,4 +205,4 @@ Per quarter-end-close (`quarter-end-close.md`):
 
 - Month-end close: monthly leave-accrual finalize per existing leave capsule.
 - Year-end close (Y2 in `year-end-close.md`): both leave and bonus true-ups against actuals; transition from accrual to actual cash payment in early Q1 next FY. (No quarterly bonus-accrual step; true-up runs annually only.)
-- Sibling `accrued-expenses.md`: the engine that drives the bonus pattern; full error table + variations there.
+- Sibling `accrued-expenses.md`: the calculator that drives the bonus pattern; full problems table + variations there.