jaz-clio 5.74.2 → 6.0.0

package/assets/skills/transaction-recipes/references/accrued-expenses.md

@@ -1,57 +1,47 @@
-# Recipe: Accrued Expenses (engine name: `accrued-expense`)
+# Recipe: Accrued Expenses (calculator type: `accrued-expense`)
 
-> Canonical recipe for month-end expense accruals (utilities, professional fees, cleaning, employee bonuses), incurred but not yet billed. The engine creates dual-entry accrual + reversal journal pairs, all dated and DRAFT, attached to one capsule.
+> Canonical recipe for month-end expense accruals (utilities, professional fees, cleaning, employee bonuses), incurred but not yet billed. Each period is a pair of journals: the accrual at period-end and its reversal in the next period, all in one capsule. You calculate, create the capsule and post each journal 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: 'accrued-expense', ...)`**, used in step 2: returns RecipePlan with N accrual + N reversal journals (2N total), capsule shape, required accounts, vendor metadata.
-- **`execute_recipe(recipe: 'accrued-expense', ...)`**, used in step 4: posts 2N future-dated DRAFT journals (one accrual at period-end, one reversal at next-period-start, repeated for `periods`) all attached to the same capsule.
+### Calculator (offline, posts nothing)
+- **MCP: `calculate(type: 'accrued-expense', amount, periods, frequency, startDate, currency)`** (step 1).
+- **CLI: `clio calc accrued-expense --amount <per-period> --periods <n> --start-date <YYYY-MM-DD> --currency <code> --json`** (step 1): the same result.
 
-### Calculator (cross-check, no API key needed)
-- **`clio calc accrued-expense --amount <per-period> --periods <n> --start-date <YYYY-MM-DD> --currency <code> --json`**, used in step 1: independently produce the schedule. Returns `{ totalAccrued, schedule[n] }` where each row carries `accrualDate`, `reversalDate`, `accrualJournal`, `reversalJournal`.
+### Posting tools
+- **`list_capsule_types` / `create_capsule_type(displayName: 'Accrued Expenses')` / `create_capsule(...)`** (step 3).
+- **`create_journal(...)`** (step 4): one per accrual and one per reversal, each with `capsuleResourceId`.
 
-### Tools (jaz-api / direct)
-- **`search_journals(filter: {tags: {eq: <accrual.name>}, valueDate: <prior-period>-end})`**, step 1 estimation: pull last period's posted accrual amount when `estimation_method: 'prior_month'`.
-- **`search_journals(filter: {tags: {eq: <accrual.name>}, valueDate: {between: [<-3 months>, <today>]}})`**, step 1 alt: trailing 3-month average when `estimation_method: 'trailing_3m_avg'`.
-- **`search_contacts(filter: {name: {eq: <vendor>}})`**, step 3: resolve the accrual's vendor.
-- **`search_accounts(filter: {name: {in: ['<expense GL>', '<accrued liability GL>']}})`**, step 3: confirm both sides of the journal exist in CoA.
-- **`get_journal(resourceId)` per candidate DRAFT**: step 5 monthly: find this period's pre-emitted DRAFT for finalization; journals cannot be filtered by capsule: check each candidate with `get_journal` (its `capsule.resourceId`) and confirm the set with the practitioner.
-- **`bulk_update_journals(items: [{resourceId: <id>, saveAsDraft: false}, ...])`**, step 5: finalize this period's accrual + reversal pair.
-- **`generate_trial_balance(endDate: <date>)`**, step 5 verification: confirm Accrued Expenses balance and net P&L impact.
+### Lookup and verification tools
+- **`search_journals(filter: {tags: {eq: <accrual tag>}, valueDate: {between: [<-3 months>, <today>]}})`** (step 1 estimation): pull the posted accrual amounts for the prior month or the trailing three months.
+- **`search_contacts(filter: {name: {eq: <vendor>}})`** (step 2): resolve the accrual's vendor for the journal narrative.
+- **`search_accounts(filter: {name: {in: ['<expense GL>', '<accrued liability GL>']}})`** (step 2): confirm both sides of the journal exist in the CoA.
+- **`update_journal(resourceId: <id>, saveAsDraft: false)`** (step 5): finalize a draft accrual or reversal.
+- **`generate_trial_balance(endDate: <date>)`** (step 5 verification): confirm the Accrued Expenses balance and net P&L impact.
 
 ### Cross-references
 - Operational context: invoked during month-end close, once per recurring accrual whose last-posted period precedes the current period end. The close loop supplies the estimation method, GL account, vendor, and fixed/budget amount for each accrual.
-- Sibling recipes: `prepaid-amortization.md` (mirror: paid upfront, recognized over time vs incurred over time, billed later); `employee-accruals.md` (the same engine for leave / 13th month bonuses, but with monthly-only, no reversal needed since those accumulate).
+- Sibling recipes: `prepaid-amortization.md` (mirror: paid upfront, recognized over time vs incurred over time, billed later); `employee-accruals.md` (bonus accruals use this same calculator; leave uses `leave-accrual`, monthly-only with no reversal, since leave accumulates).
 - IFRS / accounting context: matching principle (IFRS Conceptual Framework). The reversal pattern eliminates double-counting when the actual bill arrives.
 
 ---
 
 ## Step-by-step
 
-### Step 1: Compute the per-period amount
+### Step 1: Compute the per-period amount and calculate
 
 Per the accrual's estimation method:
 
-- **`prior_month`**: pull last period's posted amount via `search_journals(filter: {tags: {eq: <accrual.name>}, valueDate: <prior-period>-end})`. Use that amount.
+- **`prior_month`**: pull last period's posted amount via `search_journals` on the accrual's tag and the prior period's dates. Use that amount.
 - **`trailing_3m_avg`**: pull last 3 months' posted amounts and average.
 - **`budget`**: use the accrual's budget amount.
 - **`fixed_amount`**: use the accrual's fixed amount directly.
 
-Cross-check with the calculator:
+Then run the calculator:
 
 ```
-clio calc accrued-expense --amount 3000 --periods 1 --start-date 2025-01-31 --currency SGD --json
-```
-
-Returns `{ totalAccrued: 3000, schedule: [{accrualDate: '2025-01-31', reversalDate: '2025-02-01', accrualJournal: {...}, reversalJournal: {...}}] }`. For a single-period accrual, `periods: 1`. For a multi-period rolling accrual (e.g. quarterly bill arriving in month 3), use `periods: 3`.
-
-### Step 2: Plan the recipe
-
-```
-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: 3000,
   periods: 1,
   startDate: '2025-01-31',
@@ -59,62 +49,97 @@ plan_recipe(
 )
 ```
 
-For multi-period rolling: pass `periods: 3` (engine emits 3 accrual + 3 reversal pairs across the rolling window).
+```
+clio calc accrued-expense --amount 3000 --periods 1 --start-date 2025-01-31 --currency SGD --json
+```
+
+Returns `{ totalAccruals: 3000, schedule: [{ period, accrualDate: '2025-01-31', reversalDate: '2025-02-28', amount: 3000, accrualJournal, reversalJournal }], blueprint }`. For a single-period accrual, `periods: 1`. For a multi-period rolling accrual (e.g. quarterly bill arriving in month 3), use `periods: 3`.
+
+`blueprint.steps` (2 journals for `periods: 1`; 6 for `periods: 3`):
+- Step 1, `journal`, dated `2025-01-31`: Dr Expense Account 3,000 / Cr Accrued Liability 3,000.
+- Step 2, `journal`, dated `2025-02-28`: Dr Accrued Liability 3,000 / Cr Expense Account 3,000.
 
-Returns: `RecipePlan` with `requiredAccounts: [<expense GL>, 'Accrued Expenses']`, `needsContact: false` (vendor metadata only, no AR/AP transaction in this recipe), `steps: [{action: 'journal', date: '2025-01-31', ...}, {action: 'journal', date: '2025-02-01', ...}]` (2 journals for `periods: 1`; 6 for `periods: 3`).
+The calculator dates each reversal one period after its accrual. If the entity reverses on day 1 of the next period (the usual convention), post the reversal with `valueDate: '2025-02-01'` instead: both dates fall in the next period, so the monthly P&L is the same.
 
-### Step 3: Resolve dependencies
+### Step 2: Resolve accounts
 
-For both accounts in `requiredAccounts`:
-- `search_accounts(filter: {name: {eq: <accountName>}})`. If empty: halt and surface "Accrual references GL account `<accountName>` not in Jaz CoA. Create via `create_account` (suggested classifications: expense → `Operating Expense`; accrued liability → `Current Liability`) or remap the account before retry."
+The blueprint's `Expense Account` and `Accrued Liability` are labels. Map each to the real account:
+- `search_accounts(filter: {name: {in: ['<expense GL>', 'Accrued Expenses']}})`. If one is missing: halt and surface "Accrual needs GL account `<accountName>`, which is not in the Jaz CoA. Create via `create_account` (suggested classifications: expense → `Operating Expense`; accrued liability → `Current Liability`) or remap the account."
 
-Vendor: confirm via `search_contacts(filter: {name: {eq: <vendor>}})` for tagging on the journal narrative, but this recipe does NOT require a contact for posting (no AR/AP).
+Vendor: confirm via `search_contacts(filter: {name: {eq: <vendor>}})` for the journal narrative. The accrual itself needs no contact (no AR/AP document).
 
-### Step 4: Execute
+### Step 3: Create the capsule
 
 ```
-execute_recipe(recipe: 'accrued-expense', ...same args...)  // accounts auto-resolved from CoA; pass `bankAccountName` / `contactName` for fuzzy resolve
+list_capsule_types()
+create_capsule(
+  capsuleTypeResourceId: <id of 'Accrued Expenses'>,
+  title: 'Utilities Accrual, PowerCo, FY2025',
+  description: <blueprint.capsuleDescription>
+)
 ```
 
-Returns: `{ capsule: {resourceId, type, title}, steps: [{step, action, status, resourceId}, ...], summary: {total: 2N, created: 2N, ...} }`. The recipe creates **2N future-dated DRAFT journals** (for `periods: 1`, that's 2 journals: 1 accrual + 1 reversal). All attach to the same capsule.
+If `Accrued Expenses` is not in the list: `create_capsule_type(displayName: 'Accrued Expenses')` first. A recurring accrual keeps ONE capsule: later periods post into the same one.
+
+### Step 4: Post the journals
+
+```
+create_journal(
+  valueDate: '2025-01-31',
+  reference: 'ACCR-POWERCO-2025-01',
+  journalEntries: [
+    { accountResourceId: <expense GL>, type: 'DEBIT', amount: 3000, description: 'Accrued utilities: Jan 2025' },
+    { accountResourceId: <Accrued Expenses>, type: 'CREDIT', amount: 3000, description: 'Accrued utilities: Jan 2025' }
+  ],
+  saveAsDraft: false,
+  capsuleResourceId: <capsule id>
+)
+create_journal(
+  valueDate: '2025-02-01',
+  reference: 'ACCR-POWERCO-2025-01-REV',
+  journalEntries: [
+    { accountResourceId: <Accrued Expenses>, type: 'DEBIT', amount: 3000, description: 'Reverse accrued utilities: Jan 2025' },
+    { accountResourceId: <expense GL>, type: 'CREDIT', amount: 3000, description: 'Reverse accrued utilities: Jan 2025' }
+  ],
+  saveAsDraft: true,
+  capsuleResourceId: <capsule id>
+)
+```
 
-Engine output journals:
-- Step 1 (date `2025-01-31`): Dr `<expense GL>` 3000 / Cr Accrued Expenses 3000. DRAFT.
-- Step 2 (date `2025-02-01`): Dr Accrued Expenses 3000 / Cr `<expense GL>` 3000. DRAFT; reverses step 1 in February.
+The reversal stays a DRAFT until February's close.
 
-### Step 5: Monthly action (finalize)
+### Step 5: Monthly action
 
-For the current period (Jan 2025), the accrual journal exists in DRAFT in the capsule. Monthly close action:
+January close: the accrual is posted (step 4). February close: find the reversal by its reference and finalize it, then post February's accrual if the bill still has not arrived (run step 1 again for February's amount and post the new pair into the same capsule).
 
 ```
-**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.
-update_journal(resourceId: <accrual journal id>, saveAsDraft: false)
+search_journals(filter: {reference: {eq: 'ACCR-POWERCO-2025-01-REV'}})
+update_journal(resourceId: <reversal journal id>, saveAsDraft: false)
 ```
 
-The reversal journal (dated 2025-02-01) stays DRAFT until February's monthly-close. **Do NOT finalize both at once**; that defeats the period-matching purpose. February's close finalizes the reversal AND any new accrual for Feb if the bill still hasn't arrived (run `plan_recipe + execute_recipe` again for Feb's `period`).
+**Do NOT finalize an accrual and its reversal in the same period**; that defeats the period-matching purpose. 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`.
 
-Verify after January finalize:
+Verify after January:
 - `generate_trial_balance(endDate: '2025-01-31')`.
 - Assert: `balance['Accrued Expenses']` increased by 3000.
 - Assert: `balance['<expense GL>']` (period MTD) increased by 3000.
 - Net P&L impact for January: $3,000 expense.
 
-After February finalize (with reversal + new Feb accrual posted):
+After February (with reversal + new Feb accrual posted):
 - `balance['Accrued Expenses']` reflects only the Feb accrual (Jan's reversed cleanly).
 
 When the actual quarterly bill arrives (typically Mar 31, $9,000 total): post a normal `create_bill(...)` for the full $9,000 against `<expense GL>`. The capsule may or may not include this bill; practitioner's call. The accrual capsule's net P&L impact is zero across the rolling window once all reversals post.
 
 ---
 
-## Common error classes and recovery
+## Common problems and recovery
 
-| Source | Error | Recovery |
+| Where | Problem | Recovery |
 |--------|-------|----------|
-| `plan_recipe` | 422 `unsupported_recipe` | File-name alias `accrued-expenses` was used. Use canonical engine name `accrued-expense` (singular). |
-| `plan_recipe` | 422 `invalid_amount` | Amount is non-positive. Computed amount may have been a credit (e.g. `prior_month` returned a credit balance). Switch `estimation_method` to `fixed_amount` for this row this period, OR investigate the credit. |
-| `execute_recipe` | 422 `account_not_found` | Step 3 resolution incomplete. `search_accounts`; create via `create_account` if the practitioner confirms classification. |
-| `bulk_update_journals` | 422 `journal_unbalanced` | Engine-emitted journals are always balanced. If you see this, the source schema changed; escalate (do not retry). |
-| Verification | Net P&L impact stuck after reversal posts | Likely the reversal hasn't been finalized yet. Find it (journals cannot be filtered by capsule: check each candidate with `get_journal` (its `capsule.resourceId`) and confirm the set with the practitioner); if it is still DRAFT, finalize it. |
+| Calculator | "Amount must be a positive number" | The computed amount is zero or negative: `prior_month` may have returned a credit balance. Switch the estimation method to `fixed_amount` for this row this period, OR investigate the credit. |
+| Step 2 | An account is missing | `search_accounts`; create via `create_account` if the practitioner confirms classification. |
+| `create_journal` | "Unbalanced journal" | The lines were retyped incorrectly. Take both amounts from the calculator's step; debits must equal credits. |
+| Verification | Net P&L impact stuck after the reversal should have posted | The reversal is likely still a DRAFT. Find it by its reference (journals cannot be filtered by capsule) and finalize it. |
 | Verification | Accrued Expenses balance nonzero after the actual bill posts AND all reversals run | Either the bill amount diverged from the accrual estimate (post a true-up journal: Dr/Cr `<expense GL>` for the difference) OR a reversal was missed. Audit via `generate_general_ledger(accountResourceIds: [<Accrued Expenses id>], startDate: <accrual date>, endDate: <today>)`. |
 | Actual bill posted against `Accrued Expenses` instead of `<expense GL>` | (process error) | The reversal AND the bill both touch `Accrued Expenses`: net to zero on liability, but expense gets double-recognized. Reverse the bill, re-post against `<expense GL>`. Note the risk in your working notes. |
 
@@ -122,11 +147,11 @@ When the actual quarterly bill arrives (typically Mar 31, $9,000 total): post a
 
 ## Variations
 
-- **Multi-period rolling accrual** (quarterly bill, monthly accrual): `periods: 3` with `frequency: 'monthly'`. Engine emits 3 accrual + 3 reversal pairs. Each month's monthly-close finalizes that month's pair.
-- **One-shot accrual** (year-end true-up where you don't know the per-period split): `periods: 1`, `startDate: <FY-end>`. The reversal posts on FY-end+1 day. Practitioner posts the actual bill in the next FY when it arrives.
+- **Multi-period rolling accrual** (quarterly bill, monthly accrual): `periods: 3` with `frequency: 'monthly'`. The calculator returns 3 accrual + 3 reversal pairs. Each month's close posts that month's pair.
+- **One-shot accrual** (year-end true-up where you don't know the per-period split): `periods: 1`, `startDate: <FY-end>`. Post the reversal on FY-end+1 day. The practitioner posts the actual bill in the next FY when it arrives.
 - **Quarterly cadence**: `frequency: 'quarterly', periods: 4` for an annual rolling accrual (rare for SMBs).
-- **Different estimation per period**: not supported by a single `plan_recipe` call; engine assumes constant per-period amount. For variable amounts: invoke once per period with the new amount each time.
-- **Vendor unknown** (estimating an accrual but supplier not yet identified): pass `vendor: null` or skip the field. Engine still posts; practitioner can update the journal narrative later via `update_journal`.
+- **Different estimate per period**: the calculator assumes a constant per-period amount. For variable amounts, run it once per period with that period's amount.
+- **Vendor unknown** (estimating an accrual but supplier not yet identified): leave the vendor out of the narrative. The journal still posts; update the narrative later via `update_journal`.
 
 ---
 

package/assets/skills/transaction-recipes/references/asset-disposal.md

@@ -1,27 +1,28 @@
-# Recipe: Asset Disposal (engine name: `asset-disposal`)
+# Recipe: Asset Disposal (calculator type: `asset-disposal`)
 
-> One-shot recipe for fixed-asset disposal under IAS 16.67-72 (sale, scrap, write-off). Engine emits 1 disposal journal + 1 note (manual FA-register update). The note step is engine-SKIPPED; practitioner invokes the right Jaz FA endpoint manually after `execute_recipe`.
+> One-shot recipe for fixed-asset disposal under IAS 16.67-72 (sale, scrap, write-off). One disposal journal, plus the fixed-asset register update that stops depreciation. The calculator returns the accumulated depreciation, net book value, gain or loss and the journal lines; you post the journal and update the register 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: 'asset-disposal', ...)`** (used in step 2): returns RecipePlan with the disposal journal (Dr Cash + Dr Accumulated Depreciation + Dr/Cr Loss/Gain on Disposal / Cr Fixed Asset Cost) and a note step.
-- **`execute_recipe(recipe: 'asset-disposal', ...)`** (used in step 4): posts the disposal journal. The note step is SKIPPED (engine surfaces it in `summary.notes` for the practitioner to action manually).
+### Calculator (offline, posts nothing)
+- **MCP: `calculate(type: 'asset-disposal', cost, salvageValue, usefulLifeYears, acquisitionDate, disposalDate, proceeds, method, currency)`** (step 1). `method` is `sl` (the default), `ddb` or `150db`.
+- **CLI: `clio calc asset-disposal --cost <c> --salvage <s> --life <years> --acquired <YYYY-MM-DD> --disposed <YYYY-MM-DD> --proceeds <p> --method <sl|ddb|150db> --currency <code> --json`** (step 1): the same result.
 
-### Calculator (cross-check, no API key needed)
-- **`clio calc asset-disposal --cost <c> --salvage <s> --life <years> --acquired <YYYY-MM-DD> --disposed <YYYY-MM-DD> --proceeds <p> --method <sl|ddb|150db> --currency <code> --json`** (used in step 1): computes accumulated depreciation to disposal date, net book value, gain/loss. Returns `{ accumulatedDepreciation, netBookValue, proceeds, gainOrLoss, classification: 'gain' | 'loss' }`.
+### Posting tools
+- **`list_capsule_types` / `create_capsule_type(displayName: 'Asset Disposal')` / `create_capsule(...)`** (step 3).
+- **`create_journal(...)`** (step 4): the disposal journal.
+- **`mark_fixed_asset_sold(...)`** for a sale (it links the sale transaction and records gain/loss) or **`discard_fixed_asset(...)`** for a write-off (step 5). A disposal is its own operation, never a `status` change via `update_fixed_asset`.
 
-### Tools (jaz-api / direct)
-- **`get_fixed_asset(resourceId: <id>)`** (step 1): pull the asset's actual `cost`, `acquisitionDate`, `usefulLifeMonths`, `depreciationMethod`, `salvageValue` to feed the calculator (use the live FA-register values; auditor wants those, not a cached estimate).
-- **`generate_fa_summary(primarySnapshotStartDate: <FY-start>, primarySnapshotEndDate: <disposalDate>, groupBy: 'CATEGORY')`** (step 1 alt): pull NBV directly from Jaz's running FA register. If this matches your independent calc, use it as the authoritative NBV. If they diverge: investigate (likely a missing depreciation journal).
-- **`search_capsules(filter: {title: {eq: <capsule.name>}})`**: step 0 idempotency check. Each disposal is unique; duplicate disposal journals would corrupt the FA register reconciliation.
-- **`search_accounts(filter: {name: {in: ['Vehicles', 'Accumulated Depreciation (Vehicles)', 'Gain on Disposal', 'Loss on Disposal']}})`**: step 3.
-- **`mark_fixed_asset_sold(...)` for a sale (it links the sale transaction and records gain/loss) or `discard_fixed_asset(...)` for a write-off; a disposal is its own operation, never a `status` mutation via update_fixed_asset** OR **`POST /api/v1/mark-as-sold/fixed-assets`** OR **`POST /api/v1/discard-fixed-assets/{id}`**: step 5 manual FA-register update (the engine-skipped note step).
+### Lookup and verification tools
+- **`get_fixed_asset(resourceId: <id>)`** (step 1): the asset's registered cost, purchase date and net book value. Use the live FA-register values; the auditor wants those, not a cached estimate.
+- **`generate_fa_summary(primarySnapshotStartDate: <FY-start>, primarySnapshotEndDate: <disposalDate>, groupBy: 'CATEGORY')`** (step 1 alt): NBV from Jaz's running FA register. If this matches your independent calculation, use it as the authoritative NBV. If they diverge: investigate (likely a missing depreciation journal).
+- **`search_capsules(filter: {title: {eq: <capsule title>}})`**: step 0 idempotency check. Each disposal is unique; duplicate disposal journals would corrupt the FA register reconciliation.
+- **`search_accounts(filter: {name: {in: ['Vehicles', 'Accumulated Depreciation (Vehicles)', 'Gain on Disposal', 'Loss on Disposal']}})`**: step 2.
 - **`generate_trial_balance(endDate: <disposalDate>)`** (step 6): verify cost + accumulated depreciation cleared; gain/loss in P&L.
 
 ### Cross-references
 - Operational context: invoked during year-end close (FA disposals discovered during the year-end review) or ad-hoc during month-end close if a disposal happens mid-period.
-- Sibling: `declining-balance.md` (depreciation up to the disposal date; engine handles this internally via the calculator); `capital-wip.md` (the inverse: adding to FA, not disposing).
+- Sibling: `declining-balance.md` (depreciation up to the disposal date; the disposal calculator recomputes it from the same inputs); `capital-wip.md` (the inverse: adding to FA, not disposing).
 - IFRS / accounting context: IAS 16.67-72 (derecognition); IAS 16.71 (gain on disposal classified as Other Income, NOT revenue); IAS 16.68 (gain/loss = net proceeds − carrying amount).
 
 ---
@@ -31,37 +32,22 @@
 ### Step 0: Idempotency check
 
 ```
-search_capsules(filter: {title: {eq: 'Disposal — Delivery Vehicle (Truck-001) — 2026-03-15'}})
+search_capsules(filter: {title: {eq: 'Disposal, Delivery Vehicle (Truck-001), 2026-03-15'}})
 ```
 
 If a result returns: halt. Disposal capsules are unique per asset+date; duplicates would double-book the disposal.
 
-### Step 1: Pull asset details + independent cross-check
+### Step 1: Pull asset details and calculate
 
 ```
 get_fixed_asset(resourceId: <FA UUID>)
 ```
 
-Returns: `{ resourceId, name, cost: 50000, acquisitionDate: '2023-01-01', usefulLifeMonths: 60, depreciationMethod: 'sl', salvageValue: 5000, status: 'ACTIVE', capsuleResourceId: <originating cap if any> }`. Use these as the authoritative inputs to the calculator (don't accept user-provided values blindly; auditor will tie back to the FA register).
+Read the registered values off the record: `purchaseAmount` (cost), `purchaseDate` (epoch milliseconds: convert to a date), `netBookValueAmount`, `status`, and the asset's depreciation settings (life, method, residual value) as registered. Use these as the authoritative inputs to the calculator (don't accept user-provided values blindly; auditor will tie back to the FA register).
 
 ```
-clio calc asset-disposal --cost 50000 --salvage 5000 --life 5 --acquired 2023-01-01 --disposed 2026-03-15 --proceeds 18000 --method sl --currency SGD --json
-```
-
-Returns: `{ accumulatedDepreciation: 28500, netBookValue: 21500, proceeds: 18000, gainOrLoss: -3500, classification: 'loss' }`. (`(50000 - 5000) / 60 months × 38 months elapsed = 28,500` accumulated; NBV = 50,000 − 28,500 = 21,500; loss = 18,000 − 21,500 = −3,500).
-
-Cross-check with Jaz FA register:
-```
-get_fixed_asset(resourceId: <FA UUID>)
-```
-Should report `accumulatedDepreciation: 28500, netBookValue: 21500` matching the independent calc within 1 cent. Variance investigation: missing monthly depreciation journals (journals cannot be filtered by capsule: check each candidate with `get_journal` (its `capsule.resourceId`) and confirm the set with the practitioner); finalize them BEFORE disposal recipe.
-
-### Step 2: Plan the recipe
-
-```
-plan_recipe(
-  // Accounts, capsule and counterparty are not plan_recipe params: execute_recipe resolves accounts from the CoA and takes bankAccountName / contactName.
-  recipe: 'asset-disposal',
+calculate(
+  type: 'asset-disposal',
   cost: 50000,
   salvageValue: 5000,
   usefulLifeYears: 5,
@@ -73,67 +59,119 @@ plan_recipe(
 )
 ```
 
-Returns `RecipePlan` with `requiredAccounts: ['Vehicles', 'Accumulated Depreciation (Vehicles)', 'Loss on Disposal' (since classification: 'loss'), 'Cash / Bank Account']`, `needsContact: false`, `needsBankAccount: true` (proceeds receipt), `steps`:
-- Step 1: disposal journal, multi-line:
+```
+clio calc asset-disposal --cost 50000 --salvage 5000 --life 5 --acquired 2023-01-01 --disposed 2026-03-15 --proceeds 18000 --method sl --currency SGD --json
+```
+
+Returns `{ monthsHeld: 39, accumulatedDepreciation: 29250, netBookValue: 20750, gainOrLoss: -2750, isGain: false, disposalJournal, blueprint }`. The calculator counts a part month as a full month, so 2023-01-01 to 2026-03-15 is 39 months: `(50000 - 5000) / 60 months × 39 months = 29,250` accumulated; NBV = 50,000 − 29,250 = 20,750; loss = 18,000 − 20,750 = −2,750.
+
+`blueprint.steps`:
+- Step 1, `journal`, dated `2026-03-15`, multi-line:
   - Dr Cash / Bank Account 18,000 (proceeds received)
-  - Dr Accumulated Depreciation (Vehicles) 28,500 (clear contra-asset)
-  - Dr Loss on Disposal 3,500 (P&L impact)
-  - Cr Vehicles 50,000 (clear original cost)
-- Step 2: NOTE step, `Update Jaz FA register: use POST /mark-as-sold/fixed-assets (if sold) or POST /discard-fixed-assets/:id (if scrapped).` Engine SKIPS this; practitioner handles manually in step 5.
+  - Dr Accumulated Depreciation 29,250 (clear contra-asset)
+  - Dr Loss on Disposal 2,750 (P&L impact)
+  - Cr Fixed Asset (at cost) 50,000 (clear original cost)
+- Step 2, `note`: an instruction to update the FA register. For a registered asset the register books the disposal itself, so step 1 is a cross-check, not an entry to post (step 4 below).
 
-For scrap (no proceeds): `proceeds: 0` → `gainOrLoss: -netBookValue` → all loss.
-For gain (proceeds > NBV): engine debits Cash, debits Accum Dep, credits Vehicles, AND credits Gain on Disposal for the difference.
+For scrap (no proceeds): `proceeds: 0` → `gainOrLoss: -netBookValue` → all loss, and the journal has no cash line.
+For a gain (proceeds > NBV): the journal debits Cash, debits Accumulated Depreciation, credits Fixed Asset (at cost), AND credits Gain on Disposal for the difference.
 
-### Step 3: Resolve dependencies
+Cross-check with the Jaz FA register: `netBookValueAmount` from `get_fixed_asset` should match the calculator's `netBookValue` within 1 cent. The register depreciates to the posting date it has reached, so a difference of the current month's charge is timing, not error. A larger variance means depreciation is missing or was posted outside the register: resolve it BEFORE posting the disposal.
 
-For each account in `requiredAccounts`:
-- `search_accounts(filter: {name: {eq: <accountName>}})`. Suggested classifications: asset → `Non-current Asset`; accum dep → `Non-current Asset` contra; **`Gain on Disposal` → `Other Revenue`** (NOT Operating Revenue per IAS 16.71); `Loss on Disposal` → `Other Expense` (or `Operating Expense`, jurisdiction-specific).
+### Step 2: Resolve accounts and the bank account
 
-Bank account: resolve via `list_bank_accounts()` if the bank account resourceId isn't already known. For scrap (no proceeds): `bankAccountResourceId` is required only if there's a disposal-cost cash-out (e.g., scrap fee paid to disposal vendor); pass it for safety even if proceeds are zero.
+The blueprint's account names are labels. Map each to the real account:
+- `search_accounts(filter: {name: {in: ['Vehicles', 'Accumulated Depreciation (Vehicles)', 'Gain on Disposal', 'Loss on Disposal']}})`. Suggested classifications: asset → `Non-current Asset`; accum dep → `Non-current Asset` contra; **`Gain on Disposal` → `Other Revenue`** (NOT Operating Revenue per IAS 16.71); `Loss on Disposal` → `Other Expense` (or `Operating Expense`, jurisdiction-specific).
 
-### Step 4: Execute
+Bank account: `list_bank_accounts()` for the account the proceeds arrive in. For scrap (no proceeds) none is needed, unless there is a disposal cost (e.g., scrap fee paid to a disposal vendor), which is its own `create_cash_out`.
+
+### Step 3: Create the capsule
 
 ```
-execute_recipe(recipe: 'asset-disposal', ...same args...)  // accounts auto-resolved from CoA; pass `bankAccountName` / `contactName` for fuzzy resolve
+list_capsule_types()
+create_capsule(
+  capsuleTypeResourceId: <id of 'Asset Disposal'>,
+  title: 'Disposal, Delivery Vehicle (Truck-001), 2026-03-15',
+  description: <blueprint.capsuleDescription>
+)
 ```
 
-Returns: `{ capsule: {resourceId, type, title}, steps: [{step: 1, action: 'journal', status: 'created', resourceId: <journal id>}, {step: 2, action: 'note', status: 'skipped'}], summary: {total: 2, created: 1, skipped: 1, notes: ['Step 2 (note): Update Jaz FA register: use POST /mark-as-sold/fixed-assets (if sold) or POST /discard-fixed-assets/:id (if scrapped).'] } }`.
+If `Asset Disposal` is not in the list: `create_capsule_type(displayName: 'Asset Disposal')` first.
 
-The disposal journal is DRAFT. Finalize when ready: `update_journal(resourceId: <journal id>, saveAsDraft: false)`.
+### Step 4: Book the disposal
 
-### Step 5: Manual FA register update (CRITICAL)
+Which entries you post depends on whether the asset is in the Jaz fixed-asset register. **Never do both**: the register books a disposal itself, so posting the calculator's full disposal journal and then running a register tool books the disposal twice.
 
-The engine cannot auto-update the FA register status; practitioner MUST do this manually. Without this step, the FA register will continue to show the asset as `ACTIVE` and Jaz will continue to auto-post depreciation journals (for SL assets), corrupting the disposal.
+**A. The asset is in the register (the usual case).** Do NOT post the calculator's disposal journal. Its figures are your cross-check.
 
-Pick the right endpoint based on disposal type:
+*Sale (proceeds received).* Jaz requires a sale entry to exist before an asset can be marked sold: an invoice line on the asset's account, or a journal whose CREDIT line is on the asset's fixed-asset account. Post the proceeds as that entry, then mark the asset sold against the credit line:
 
-**Sale (proceeds received):**
 ```
-POST /api/v1/mark-as-sold/fixed-assets
-{
-  fixedAssetResourceId: <FA UUID>,
-  disposalDate: '2026-03-15',
-  proceeds: 18000,
-  notes: 'Sold to <buyer>; capsule <capsuleResourceId>'
-}
+create_journal(
+  valueDate: '2026-03-15',
+  reference: 'DISP-TRUCK-001',
+  journalEntries: [
+    { accountResourceId: <bank account>, type: 'DEBIT', amount: 18000, description: 'Proceeds, Truck-001' },
+    { accountResourceId: <Vehicles>, type: 'CREDIT', amount: 18000, description: 'Sale of Truck-001' }
+  ],
+  saveAsDraft: true,
+  capsuleResourceId: <capsule id>
+)
 ```
-OR the MCP tool: `mark_fixed_asset_sold(resourceId: <id>, depreciationEndDate: '2026-03-15', assetDisposalGainLossAccountResourceId: <Gain/Loss on Disposal>, saleBusinessTransactionType: 'SALE', saleItemResourceId: <sale line item id>)` for a sale, or `discard_fixed_asset(resourceId: <id>, disposalDate: '2026-03-15', depreciationEndDate: '2026-03-15')` for a write-off.
 
-**Scrap / write-off (no proceeds, asset destroyed/donated):**
+Finalize when the practitioner confirms (`update_journal(resourceId: <journal id>, saveAsDraft: false)`), read the credit line's id with `get_journal`, then:
+
 ```
-POST /api/v1/discard-fixed-assets/<FA UUID>
-{
-  disposalDate: '2026-03-15',
-  notes: 'Scrapped; capsule <capsuleResourceId>'
-}
+mark_fixed_asset_sold(
+  resourceId: <FA UUID>,
+  depreciationEndDate: '2026-03-15',
+  assetDisposalGainLossAccountResourceId: <Gain / Loss on Disposal>,
+  saleBusinessTransactionType: 'JOURNAL_MANUAL',
+  saleItemResourceId: <the journal's credit line id>
+)
+```
+
+`saleBusinessTransactionType` is the kind of document that recorded the sale (`JOURNAL_MANUAL` here; `SALE` for an invoice line; `PURCHASE` for a trade-in) and `saleItemResourceId` is the LINE on that document, not the document's id. A sale entry can be linked to one asset sale only.
+
+*Scrap / write-off (no proceeds).* No journal at all:
+
+```
+discard_fixed_asset(resourceId: <FA UUID>, disposalDate: '2026-03-15', depreciationEndDate: '2026-03-15')
+```
+
+Either tool records the final depreciation up to `depreciationEndDate` and the disposal entry (cost and accumulated depreciation cleared, gain or loss to the account you passed).
+
+CLI equivalents:
+```bash
+clio fixed-assets sell --id <FA UUID> --depreciation-end-date 2026-03-15 --gain-loss-account <account id> --sale-type JOURNAL_MANUAL --sale-item <journal credit line id> --json
+clio fixed-assets discard <FA UUID> --disposal-date 2026-03-15 --depreciation-end-date 2026-03-15 --json
+```
+
+After it: `get_fixed_asset(resourceId: <id>)` should return `status: 'DISPOSED'`. A disposal made in error is reversed with `undo_fixed_asset_disposal`.
+
+**B. The asset was never in the register** (for example one depreciated by declining-balance journals, see `declining-balance.md`). There is no register to update, so the calculator's journal is the whole disposal:
+
 ```
-OR `discard_fixed_asset(resourceId: <id>, disposalDate: '2026-03-15')` for a write-off.
+create_journal(
+  valueDate: '2026-03-15',
+  reference: 'DISP-TRUCK-001',
+  journalEntries: [
+    { accountResourceId: <bank account>, type: 'DEBIT', amount: 18000, description: 'Proceeds, Truck-001' },
+    { accountResourceId: <Accumulated Depreciation (Vehicles)>, type: 'DEBIT', amount: 29250, description: 'Clear accumulated depreciation' },
+    { accountResourceId: <Loss on Disposal>, type: 'DEBIT', amount: 2750, description: 'Loss on disposal' },
+    { accountResourceId: <Vehicles>, type: 'CREDIT', amount: 50000, description: 'Clear cost' }
+  ],
+  saveAsDraft: true,
+  capsuleResourceId: <capsule id>
+)
+```
+
+It is a DRAFT; finalize when the practitioner confirms.
 
-**Trade-in (proceeds + replacement asset):**
-1. First: invoke this recipe with `proceeds: <fair value of trade-in credit>` for the disposal of the old asset.
-2. Then: `create_fixed_asset(...)` for the new asset with cost = cash paid + trade-in credit (the trade-in is part-payment).
+### Step 5: Trade-in (proceeds + replacement asset)
 
-After the FA-register update: `get_fixed_asset(resourceId: <id>)` should return `status: 'DISPOSED'` (or `'DISCARDED'`).
+1. Dispose of the old asset as in step 4, with `proceeds: <fair value of the trade-in credit>`.
+2. `create_fixed_asset(...)` for the new asset with cost = cash paid + trade-in credit (the trade-in is part-payment).
 
 ### Step 6: Verify
 
@@ -142,15 +180,19 @@ generate_trial_balance(endDate: '2026-03-15')
 ```
 
 Assert:
-- `balance['Vehicles']` reduced by 50,000 (cost cleared).
-- `balance['Accumulated Depreciation (Vehicles)']` reduced by 28,500 (contra-asset cleared).
+- `balance['Vehicles']` reduced by 50,000 (cost cleared), once.
+- `balance['Accumulated Depreciation (Vehicles)']` reduced by 29,250 (contra-asset cleared), once.
 - `balance['Cash / Bank Account']` increased by 18,000.
-- `balance['Loss on Disposal'] (period MTD) == 3,500` (or Gain on Disposal of `gainOrLoss` if positive).
+- `balance['Loss on Disposal'] (period MTD) == 2,750` (or Gain on Disposal of `gainOrLoss` if positive).
+
+**Compare with the calculator.** For a registered asset the gain or loss the register booked should match the calculator's `gainOrLoss`; a difference of one month's depreciation is the month convention (the calculator counts a part month as a full month), anything larger needs explaining before the period closes.
+
+**Check for a double count.** If the cost, accumulated depreciation or gain/loss moved by twice the expected amount, a full manual disposal journal was posted for an asset the register also disposed of: pull `generate_general_ledger(accountResourceIds: [<Vehicles>], startDate: <disposalDate>, endDate: <disposalDate>)`, show the practitioner both entries, and remove the manual one.
 
 ```
 get_fixed_asset(resourceId: <FA UUID>)
 ```
-Should now show `status: 'DISPOSED'`, NBV = 0, no further depreciation auto-posting.
+Should now show `status: 'DISPOSED'`, and no further depreciation auto-posting.
 
 ```
 generate_fa_recon_summary(primarySnapshotStartDate: <FY-start>, primarySnapshotEndDate: <FY-end>)
@@ -159,28 +201,28 @@ Should reflect the disposal in the year's movement: `openingNbv − depreciation
 
 ---
 
-## Common error classes and recovery
+## Common problems and recovery
 
-| Source | Error | Recovery |
+| Where | Problem | Recovery |
 |--------|-------|----------|
-| `plan_recipe` | 422 `disposal_after_period_end` | `disposalDate` later than the engagement's period end. Disposal belongs to next period; halt and confirm with practitioner. |
-| `plan_recipe` | 422 `acquisition_after_disposal` | Inputs swapped. Verify and re-run. |
-| `execute_recipe` | 422 `account_not_found` for `Gain on Disposal` / `Loss on Disposal` | Step 3 incomplete. Create via `create_account(accountType: 'Other Revenue' / 'Other Expense', ...)`. |
-| Step 5 manual update missed | (process error: Jaz FA continues auto-depreciating) | Surface to practitioner: "Asset `<name>` (resourceId `<id>`) is still ACTIVE in FA register but disposal journal posted. Auto-depreciation will continue. Run `mark_fixed_asset_sold` (sale) or `discard_fixed_asset` (write-off) immediately." |
-| `mark_fixed_asset_sold` / `discard_fixed_asset` | 422 `pending_depreciation_journals` | DRAFT depreciation journals exist for periods after disposal date. Identify them (journals cannot be filtered by capsule: check each candidate with `get_journal` (its `capsule.resourceId`) and confirm the set with the practitioner), then `delete_journal` per confirmed journal. |
-| Cross-check | Calculator NBV ≠ FA register NBV | Investigate missing depreciation journals (recipe pre-emitted DRAFTs that weren't finalized monthly). Finalize all up to disposal date BEFORE running this recipe. |
-| Recipe NBV ≠ TB Vehicles − TB Accum Dep | (audit failure) | Likely a manual journal touched Vehicles or Accum Dep without going through the recipe. Audit `generate_general_ledger(accountResourceIds: [<Vehicles>], startDate: <acquisition date>, endDate: <today>)`. |
+| Calculator | "Disposal date must be after acquisition date." | Inputs swapped. Verify and re-run. |
+| Calculator | Disposal date later than the period being closed | The disposal belongs to the next period; halt and confirm with the practitioner. |
+| Step 2 | `Gain on Disposal` / `Loss on Disposal` is missing | Create via `create_account(accountType: 'Other Revenue' / 'Other Expense', ...)`. |
+| Step 5 register update missed | (process error: Jaz FA continues auto-depreciating) | Surface to practitioner: "Asset `<name>` (resourceId `<id>`) is still ACTIVE in FA register but disposal journal posted. Auto-depreciation will continue. Run `mark_fixed_asset_sold` (sale) or `discard_fixed_asset` (write-off) immediately." |
+| `mark_fixed_asset_sold` / `discard_fixed_asset` | Refused because depreciation is pending after the disposal date | DRAFT depreciation journals exist for periods after the disposal date. Identify them by their references (journals cannot be filtered by capsule) and confirm the set with the practitioner, then `delete_journal` per confirmed journal. |
+| Cross-check | Calculator NBV ≠ FA register NBV | Investigate missing depreciation (period journals posted as DRAFT that were never finalized). Finalize all up to the disposal date BEFORE this recipe. |
+| Calculator NBV ≠ TB Vehicles − TB Accum Dep | (audit failure) | Likely a manual journal touched Vehicles or Accum Dep outside the depreciation schedule. Audit `generate_general_ledger(accountResourceIds: [<Vehicles>], startDate: <acquisition date>, endDate: <today>)`. |
 
 ---
 
 ## Variations
 
-- **Scrap (no proceeds)**: `proceeds: 0`. Resulting `gainOrLoss = -netBookValue` (full NBV is loss). Step 5 uses `discard-fixed-assets` not `mark-as-sold`.
+- **Scrap (no proceeds)**: `proceeds: 0`. Resulting `gainOrLoss = -netBookValue` (full NBV is loss). Step 5 uses `discard_fixed_asset`, not `mark_fixed_asset_sold`.
 - **Donation**: `proceeds: 0`, but classify the loss as `Charitable Donation` (not `Loss on Disposal`) per practitioner judgment. May have tax implications (deductible donation); flag to practitioner for SG IRAS / PH BIR treatment.
 - **Insurance write-off after damage**: `proceeds: <insurance payout>`. The payout is taxable income; the loss may be deductible. Document the insurance reference in the journal narrative.
-- **Trade-in**: 2 recipe invocations (this one for old asset, plus `create_fixed_asset` for new) plus a manual reconciliation of the trade-in credit.
-- **Partial disposal** (e.g., dismantling part of a building): NOT supported by this recipe. Manual journal: pro-rate cost + accum dep based on the disposed portion.
-- **Disposal of a fully depreciated asset (NBV = 0)**: `proceeds > 0` → all gain. `proceeds == 0` → no entries needed in P&L; just clear the contra-asset against the cost (Dr Accum Dep / Cr Vehicles, both at full cost). Recipe still works; gain/loss = proceeds.
+- **Trade-in**: this recipe for the old asset, plus `create_fixed_asset` for the new one, plus a manual reconciliation of the trade-in credit.
+- **Partial disposal** (e.g., dismantling part of a building): NOT supported by the calculator. Manual journal: pro-rate cost + accum dep based on the disposed portion.
+- **Disposal of a fully depreciated asset (NBV = 0)**: `proceeds > 0` → all gain. `proceeds == 0` → no entries needed in P&L; just clear the contra-asset against the cost (Dr Accum Dep / Cr Vehicles, both at full cost). The calculator still works; gain/loss = proceeds.
 - **Foreign-currency proceeds**: pass `currency: 'USD'`. Per `jaz-api/SKILL.md` rule 25, journal records via `currency: { sourceCurrency: 'USD' }`. FX gain/loss between disposal-date rate and book rate is auto-handled by Jaz on the cash side.
 
 ---
@@ -190,5 +232,5 @@ Should reflect the disposal in the year's movement: `openingNbv − depreciation
 - Year-end close: FA disposals discovered during the year-end review trigger this recipe per asset.
 - Month-end close: ad-hoc invocation when a disposal happens mid-period.
 - `audit-prep.md` step 8: supporting schedule via `search_capsules(filter: {status: {eq: 'ACTIVE'}})` then narrow by date on the rows (**do not filter capsules by date**: `startDate`/`endDate` are declared on `CapsuleFilter` and pass validation, but every form of them answers `500 Internal Server Error` (measured 2026-09-07: `{gte}`, `{between}`, and `{gte}`+`{lte}` all 500)) plus per-capsule recompute via `clio calc asset-disposal`. Auditor tests proceeds against bank statements, NBV against FA register.
-- `fa-review.md` job: annual FA register review identifies candidates for disposal (assets fully depreciated, assets no longer in use, assets damaged) → invoke this recipe per identified disposal.
-- Sibling recipe `declining-balance.md`: depreciation up to the disposal date; complete all DRAFT depreciation finalizations BEFORE running this recipe to ensure NBV is correct.
+- `fa-review.md` job: annual FA register review identifies candidates for disposal (assets fully depreciated, assets no longer in use, assets damaged) → follow this recipe per identified disposal.
+- Sibling recipe `declining-balance.md`: depreciation up to the disposal date; finalize all DRAFT depreciation journals BEFORE this recipe so NBV is correct.