jaz-clio 5.65.0 → 5.66.0

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 5.65.0
+version: 5.66.0
 description: >-
   Use this skill whenever you call, debug, or review code that touches the Jaz
   REST API. Covers field names, response shapes, 159 production gotchas, error
@@ -206,7 +206,7 @@ The rest of this skill — field names, gotchas, error catalog, dependency order
 
 ### Response Shape Gotchas
 66. **Contact boolean fields are `customer`/`supplier`** — NOT `isCustomer`/`isSupplier`. These are plain booleans on the contact object: `{ "customer": true, "supplier": false }`. Using `isCustomer` or `isSupplier` in code will be `undefined`.
-67. **Finalized statuses differ by resource type** — NOT `"FINALIZED"`, `"FINAL"`, or `"POSTED"`. Journals → `"ACTIVE"` (journals have no approval state — their lifecycle is `ACTIVE | VOID | DRAFT`; live-verified 2026-08-03). Invoices/Bills → `"UNPAID"` (progresses to `"PAID"`, `"OVERDUE"`). Customer/Supplier Credit Notes → `"UNAPPLIED"` (progresses to `"APPLIED"`). All types support `"DRAFT"` and `"VOID"` (not `"VOIDED"`). When creating with `saveAsDraft: false`, the response status matches the type's finalized status.
+67. **Finalized statuses differ by resource type** — NOT `"FINALIZED"`, `"FINAL"`, or `"POSTED"`. Journals → `"ACTIVE"` (journals have no approval state — their lifecycle is `ACTIVE | VOID | DRAFT`; live-verified 2026-08-03). Invoices/Bills → `"UNPAID"` (progresses to `"PARTIALLY_PAID"`, `"PAID"`). `OVERDUE` is not a status (a list with it returns 422 and a search matches nothing), so find overdue documents with `status in [UNPAID, PARTIALLY_PAID]` plus `dueDate lt <today in the organization's timezone>`. Customer/Supplier Credit Notes → `"UNAPPLIED"` (progresses to `"PARTIALLY_APPLIED"`, `"APPLIED"`). All types support `"DRAFT"` and `"VOID"` (not `"VOIDED"`). When creating with `saveAsDraft: false`, the response status matches the type's finalized status.
 68. **Create/pay responses are minimal by default** — POST create endpoints (invoices, bills, journals, contacts, payments) return only `{ resourceId: "..." }` (plus a few metadata fields). They do NOT return the full entity. To verify field values after creation, do a subsequent `GET /:type/:resourceId`. **MCP tool shortcut:** `create_invoice` / `create_bill` / `create_journal` / `create_contact` / `create_item` accept `returnFullEntity: true` — the executor performs the GET server-side and returns the full entity inline, saving a turn. The raw REST `POST` is still minimal-only; only the MCP tools collapse the round trip. **If the post-create GET fails** (transient 5xx, network blip), the tool returns the minimal create envelope augmented with `_hydration: { status: 'failed', resourceId, message }` — the write committed; the agent should retry only the `get_*` call, NEVER the create (would duplicate the document). **`_fx` on transaction creates:** invoice/bill/credit-note create results may carry a sibling `_fx` field, e.g. `FX: 1 SGD (your base) = 0.74 USD (applied rate for 2026-04-03)` — the exchange rate the record was ACTUALLY created with. Relay that line to the user verbatim; it matters most when the caller supplied no rate (the organization rate was applied silently, and a rate stored the wrong way round reads as an obviously absurd number the user can catch on sight).
 69. **No `amountDue` field** — Invoices and bills do NOT have an `amountDue` field. To check if a transaction is fully paid, inspect the `paymentRecords` array: if `paymentRecords.length > 0`, payments exist. Compare `totalAmount` with the sum of `paymentRecords[].transactionAmount` to determine remaining balance.
 70. **Response dates include time component** — Even though request dates are `YYYY-MM-DD`, response dates are epoch milliseconds (see Rule 52). When comparing dates from responses, always convert with `new Date(epochMs).toISOString().slice(0, 10)` — never string-match against the raw epoch value. Remember: business dates are org-timezone (see Rule 52).
@@ -351,7 +351,7 @@ Bills, invoices, and credit notes share identical mandatory field specs. Adding
 103. **Journal entries must balance** — Sum of all DEBIT amounts must exactly equal sum of all CREDIT amounts. Unbalanced journals are rejected with 422. Agent tools pre-flight check this client-side before hitting the API.
 
 ### Transaction References
-104. **References must be unique per org — NEVER invent one** — A duplicate `reference` causes 422 `Sale Reference already exists` (or `Purchase Reference`). Ask whose number it is. **Purchase side (bills, supplier credit notes): use the SUPPLIER'S own document number**, read off the document; only if it genuinely has none, set `autoReference: true`. **Everything we issue (invoices, customer credit notes, quotes, sale orders, purchase requests, purchase orders, journals, expense claims): set `autoReference: true`** to take the next number from the organization's own series, or call `get_next_reference` to preview it first. Never a timestamp, never a guess, never a pattern inferred from other documents. This covers the business transaction families only; payments, cash entries, transfers, employee payouts, scheduled invoices, scheduled bills, scheduled journals and subscriptions have no series here and keep their own references. The scheduled bodies additionally REQUIRE a literal reference: they mint per occurrence upstream, so `autoReference` is rejected there even though the published schema shows the field. Sending both `reference` and `autoReference` is not an error here: the client resolves the number before the request and your explicit `reference` wins, costing one wasted series read. Send one. The assigned number always carries today's date even on a back-dated document, and reading the series does not reserve it.
+104. **References must be unique per org — NEVER invent one** — On invoices, customer credit notes, quotes and orders a duplicate `reference` causes 422 `Sale Reference already exists`. Bills, supplier credit notes and manual journals accept a duplicate silently, so both documents keep the same number and nobody is told: search by reference before creating one again after an unconfirmed result. Ask whose number it is. **Purchase side (bills, supplier credit notes): use the SUPPLIER'S own document number**, read off the document; only if it genuinely has none, set `autoReference: true`. **Everything we issue (invoices, customer credit notes, quotes, sale orders, purchase requests, purchase orders, journals, expense claims): set `autoReference: true`** to take the next number from the organization's own series, or call `get_next_reference` to preview it first. Never a timestamp, never a guess, never a pattern inferred from other documents. This covers the business transaction families only; payments, cash entries, transfers, employee payouts, scheduled invoices, scheduled bills, scheduled journals and subscriptions have no series here and keep their own references. The scheduled bodies additionally REQUIRE a literal reference: they mint per occurrence upstream, so `autoReference` is rejected there even though the published schema shows the field. Sending both `reference` and `autoReference` is not an error here: the client resolves the number before the request and your explicit `reference` wins, costing one wasted series read. Send one. The assigned number always carries today's date even on a back-dated document, and reading the series does not reserve it.
 
 ### Currency Rates
 105. **`add_currency_rate` for new rates, `update_currency_rate` only for editing existing records** — When a user says "update the rate" or "set the rate", use `add_currency_rate` (POST — creates a new rate entry for a date). Only use `update_currency_rate` (PUT) when explicitly modifying an existing rate record by its resourceId.
@@ -492,9 +492,9 @@ Bills, invoices, and credit notes share identical mandatory field specs. Adding
 
 155. **Pseudo-SQL schema is canonical — call `get_pseudo_sql_schema` before any query.** The response returns the live curated catalog (tables / columns / joins / functions) PLUS the canonical `jaz-pseudo-sql.md` skill body in `agentSkillsDoc.content`. Drop the `.md` body into context as the syntax-rules source; treat `tables[] / joins[] / functions[]` as the column-list source. **Cache contract:** the `version` field is a stable 16-char hex hash; within a session, cache by version and don't re-call unless you have reason to believe the schema changed (e.g. a fresh backend deploy mid-session). Don't re-fetch on a wall-clock timer (upstream is `private, no-cache, must-revalidate`). A static curated-schema snapshot used to ship with the `jaz-pseudo-sql` skill before v5.6.0; it was dropped because it was structurally guaranteed to drift. Never write a query from a memorized column list.
 
-156. **v1 capsule recipes are single-currency — `ERR_RECIPE_ACCOUNT_CURRENCY_MISMATCH`.** The recipe `currency` field, every `*AccountResourceId` account's `currencyCode`, and the base transaction's `currencyCode` ALL MUST match. Preview returns 422 `ERR_RECIPE_ACCOUNT_CURRENCY_MISMATCH` with a concrete message (e.g. "account X is denominated in USD but the recipe currency is SGD"). **Trigger mutation silently nulls `capsuleRecipeJob`** (Rule 143). Practical recipe: never hardcode `currency`; derive from `get_account(prepaidAssetAccountResourceId).currencyCode` (or the base trx currency) and use the same value as the recipe input. The recipe descriptor's `currency.x-baseTrxBinding: "strict"` field marks this — when present, the value is bound to (and must equal) `trx.currencyCode` post-commit. Caught by smoke runs since v5.5.0 — tests 65/66 hardcoded `SGD` and silently nulled against a USD fire-test org for 20+ hours.
+156. **v1 capsule recipes are single-currency — `ERR_RECIPE_ACCOUNT_CURRENCY_MISMATCH`.** The recipe `currency` field, every `*AccountResourceId` account's `currencyCode`, and the base transaction's `currencyCode` ALL MUST match. Preview returns 422 `ERR_RECIPE_ACCOUNT_CURRENCY_MISMATCH` with a concrete message (e.g. "account X is denominated in USD but the recipe currency is SGD"). **Trigger mutation silently nulls `capsuleRecipeJob`** (Rule 143). Practical recipe: never hardcode `currency`; derive from the account's `currencyCode` (`search_accounts(filter: {resourceId: {eq: <prepaidAssetAccountResourceId>}})`) (or the base trx currency) and use the same value as the recipe input. The recipe descriptor's `currency.x-baseTrxBinding: "strict"` field marks this — when present, the value is bound to (and must equal) `trx.currencyCode` post-commit. Caught by smoke runs since v5.5.0 — tests 65/66 hardcoded `SGD` and silently nulled against a USD fire-test org for 20+ hours.
 
-157. **Recipe input `*AccountResourceId` fields are account-class-locked — `x-accountClass` in inputSchema is authoritative.** Each `*AccountResourceId` slot on a recipe's input schema carries an `x-accountClass` constraint (`"Asset"`, `"Liability"`, `"Expense"`, `"Revenue"`, `"Equity"`). Passing an account whose class doesn't match the slot's `x-accountClass` is rejected post-commit and silently nulls `capsuleRecipeJob` (Rule 143). Schema location: `get_capsule_recipe(name).data.versions[0].inputSchema.properties.<fieldName>['x-accountClass']` — **note `versions[0].inputSchema`, NOT `inputSchema` at the top level**. Examples: PREPAID_AMORTIZATION needs `prepaidAssetAccountResourceId: Asset` + `expenseAccountResourceId: Expense`; DEFERRED_REVENUE needs `deferredRevenueAccountResourceId: Liability` + `revenueAccountResourceId: Revenue`; ACCRUAL_REVERSAL needs `expenseAccountResourceId: Expense` + `accruedLiabilityAccountResourceId: Liability`. Always pre-validate via `get_account(resourceId).accountClass` against the slot constraint, or just call `preview_capsule_recipe(recipeName, inputs)` to surface every class violation as a clean 422.
+157. **Recipe input `*AccountResourceId` fields are account-class-locked — `x-accountClass` in inputSchema is authoritative.** Each `*AccountResourceId` slot on a recipe's input schema carries an `x-accountClass` constraint (`"Asset"`, `"Liability"`, `"Expense"`, `"Revenue"`, `"Equity"`). Passing an account whose class doesn't match the slot's `x-accountClass` is rejected post-commit and silently nulls `capsuleRecipeJob` (Rule 143). Schema location: `get_capsule_recipe(name).data.versions[0].inputSchema.properties.<fieldName>['x-accountClass']` — **note `versions[0].inputSchema`, NOT `inputSchema` at the top level**. Examples: PREPAID_AMORTIZATION needs `prepaidAssetAccountResourceId: Asset` + `expenseAccountResourceId: Expense`; DEFERRED_REVENUE needs `deferredRevenueAccountResourceId: Liability` + `revenueAccountResourceId: Revenue`; ACCRUAL_REVERSAL needs `expenseAccountResourceId: Expense` + `accruedLiabilityAccountResourceId: Liability`. Always pre-validate the account's `accountClass` (`search_accounts(filter: {resourceId: {eq: <id>}})`) against the slot constraint, or just call `preview_capsule_recipe(recipeName, inputs)` to surface every class violation as a clean 422.
 
 ## Supporting Files
 

package/assets/skills/api/references/errors.md

@@ -851,8 +851,8 @@ The same applies on update: `PUT /cash-in-entries/:id` with `saveAsDraft: true`
 ## Invoices / Bills
 
 ### "Sale Reference already exists" (422) — duplicate reference
-**Cause**: Creating an invoice/bill/CN with a `reference` that already exists in the org.
-**Fix**: Do not invent a number. For a bill or supplier credit note use the supplier's own document number. For anything the organization issues, set `autoReference: true` (or call `get_next_reference` first) to take the next number from its own series. References must be unique per org.
+**Cause**: Creating an invoice, customer credit note, quote or order with a `reference` that already exists in the org.
+**Fix**: Do not invent a number. For anything the organization issues, set `autoReference: true` (or call `get_next_reference` first) to take the next number from its own series. Bills, supplier credit notes and manual journals never return this error: they accept a duplicate reference silently and book a second document, so search by reference before re-creating one after an uncertain result. For a bill or supplier credit note use the supplier's own document number.
 
 ---
 

package/assets/skills/api/references/search-enums.md

@@ -2,7 +2,7 @@
 
 > Valid enum values for every searchable field, organized by entity.
 > For filter syntax and operators, see [search-reference.md](./search-reference.md).
-> For complex composition and recipes, see [search-recipes.md](./search-recipes.md).
+> For the `query` expression language and composition examples, see [search-syntax.md](./search-syntax.md).
 
 ---
 
@@ -110,7 +110,7 @@ org has no such account". `search_accounts` does not normalise — only
 **Amount fields**: `totalAmount`, `balanceAmount`, `reconciledAmount`, `paymentRecordedAmount`, `creditAppliedAmount`
 **Date fields**: `valueDate`, `dueDate`, `createdAt` (DateTime), `updatedAt` (DateTime), `approvedAt`, `submittedAt`
 
-> **Note**: `OVERDUE` is not a direct status value. To find overdue invoices, use a compound filter: `status IN [UNPAID, PARTIALLY_PAID] AND dueDate < {today}`. See [search-recipes.md](./search-recipes.md#virtual-statuses).
+> **Note**: `OVERDUE` is not a status value (a list with it returns 422, a search matches nothing). To find overdue invoices, filter `{"status": {"in": ["UNPAID", "PARTIALLY_PAID"]}, "dueDate": {"lt": "<today in the organization's timezone>"}}`. With `search_invoices`: `status: "UNPAID,PARTIALLY_PAID"` and `dueDateTo` set to yesterday in the organization's timezone. Same for bills.
 
 ---
 

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 5.65.0
+version: 5.66.0
 description: >-
   Use this skill when running Clio CLI commands, building shell scripts with
   Clio, debugging auth issues, understanding --json output, paginating results,

package/assets/skills/cli/references/error-recovery.md

@@ -46,7 +46,7 @@
 | `At least one line item is required` | Empty --lines array | Provide at least one line item object |
 | `Invalid date format` | Date not in YYYY-MM-DD | Use ISO format: `--date 2026-03-15` |
 | `unitPrice must be a number` | String passed for numeric field | Remove quotes from numeric values in JSON |
-| `Invalid status filter` | Wrong status value for entity type | Check valid statuses per type (Rule 67): invoices/bills DRAFT, UNPAID, PARTIALLY_PAID, PAID, OVERDUE, VOID; journals DRAFT, ACTIVE, VOID |
+| `Invalid status filter` | Wrong status value for entity type | Check valid statuses per type (Rule 67): invoices/bills DRAFT, UNPAID, PARTIALLY_PAID, PAID, VOID (no OVERDUE status: use `--status UNPAID,PARTIALLY_PAID --due-date-to <yesterday in the organization's timezone>`); journals DRAFT, ACTIVE, VOID |
 
 ---
 

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 5.65.0
+version: 5.66.0
 description: >-
   Use this skill when migrating accounting data into Jaz — importing from Xero,
   QuickBooks, Sage, MYOB, or Excel exports. Covers the full conversion pipeline:

package/assets/skills/jaz-kit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-kit
-version: 5.65.0
+version: 5.66.0
 description: >-
   Use this skill when an accountant, bookkeeper, or owner is running real books
   in Jaz across one or more organizations from the terminal — setting up a

package/assets/skills/jaz-pseudo-sql/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-pseudo-sql
-version: 5.65.0
+version: 5.66.0
 description: >-
   Use this skill when answering ad-hoc data questions that aren't covered by
   download_export (canonical reports — anomaly, audit, aging, P&L, BS, GL,

package/assets/skills/jaz-pseudo-sql/references/error-catalog.md

@@ -38,7 +38,7 @@ running. Delivered as a **422**, which reads like a validation failure and is no
 
 | Message | Trigger | Recovery |
 |---|---|---|
-| `The SQL query feature is not available.` | The reporting service has no read-only query pool: its connection string is unset for this deployment, or the pool failed to build, ping, or match the catalog at startup | None available to you. Do not rewrite the query. Use the report tools (`generate_report`, the operational report family) and tell the user the engine is off. |
+| `The SQL query feature is not available.` | The reporting service has no read-only query pool: its connection string is unset for this deployment, or the pool failed to build, ping, or match the catalog at startup | None available to you. Do not rewrite the query. Use the report tools (`generate_trial_balance`, `generate_profit_and_loss`, the operational report family) and tell the user the engine is off. |
 
 **The catalog stays readable while the engine is off.** `get_pseudo_sql_schema` is served from a
 static in-process snapshot and never touches the query pool, so it keeps returning the full table,

package/assets/skills/jobs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-jobs
-version: 5.65.0
+version: 5.66.0
 description: >-
   Use this skill for recurring accounting workflows — month/quarter/year-end
   close, bank reconciliation, GST/VAT filing, payment runs, credit control,

package/assets/skills/jobs/references/audit-prep.md

@@ -5,19 +5,19 @@
 ## Tools, recipes, calculators this job uses
 
 ### Platform tools — financial statements
-- **`generate_trial_balance(period_end: <FY-end>)`** — step 2: master reconciliation. Every other report ties back to this.
-- **`generate_balance_sheet(period_end: <FY-end>)`** — step 3.
-- **`generate_profit_and_loss(period_start: <FY-start>, period_end: <FY-end>)`** — step 3.
-- **`generate_cashflow(period_start, period_end)`** — step 4.
-- **`generate_equity_movement(period_start, period_end)`** — step 4.
-- **`generate_general_ledger(period_start, period_end, groupBy: 'ACCOUNT')`** — step 5: the auditor's primary working document.
+- **`generate_trial_balance(endDate: <FY-end>)`** — step 2: master reconciliation. Every other report ties back to this.
+- **`generate_balance_sheet(snapshotDate: <FY-end>)`** — step 3.
+- **`generate_profit_and_loss(startDate: <FY-start>, endDate: <FY-end>)`** — step 3.
+- **`generate_cashflow(startDate, endDate)`** — step 4.
+- **`generate_equity_movement(primarySnapshotStartDate, primarySnapshotEndDate)`** — step 4.
+- **`generate_general_ledger(startDate, endDate, groupBy: 'ACCOUNT')`** — step 5: the auditor's primary working document.
 
 ### Platform tools — supporting schedules
-- **`generate_aged_ar(period_end)` / `generate_aged_ap(period_end)`** — step 6.
-- **`generate_bank_recon_summary(period_end)` / `generate_bank_recon_details(period_end)`** — step 7. NON-NEGOTIABLE deliverable.
-- **`generate_bank_balance_summary(period_end)`** — step 7. Cross-reference to bank confirmation letters.
-- **`generate_fa_summary(period_end)` / `generate_fa_recon_summary(period_start, period_end)`** — step 8.
-- **`generate_vat_ledger(period_start, period_end)`** — step 9. Annual total ties to sum of quarterly F5 returns.
+- **`generate_aged_ar(endDate)` / `generate_aged_ap(endDate)`** — step 6.
+- **`generate_bank_recon_summary(bankAccountResourceId, primarySnapshotStartDate, primarySnapshotEndDate)` / `generate_bank_recon_details(bankAccountResourceId, primarySnapshotStartDate, primarySnapshotEndDate, filter)` per bank account** — step 7. NON-NEGOTIABLE deliverable.
+- **`generate_bank_balance_summary(primarySnapshotDate)`** — step 7. Cross-reference to bank confirmation letters.
+- **`generate_fa_summary(primarySnapshotStartDate, primarySnapshotEndDate, groupBy)` / `generate_fa_recon_summary(primarySnapshotStartDate, primarySnapshotEndDate)`** — step 8.
+- **`generate_vat_ledger(startDate, endDate)`** — step 9. Annual total ties to sum of quarterly F5 returns.
 
 ### Platform tools — XLSX deliverables
 - **`download_export(exportType: '<type>', startDate, endDate)`** — step 10: pre-signed XLSX URL (~5 min expiry). Per `jaz-api/SKILL.md` rule (data-exports), supported types include `trial-balance`, `profit-and-loss`, `balance-sheet`, `general-ledger`, `ar-report`, `ap-report`, `cashflow`, `analysis-anomalous-bills`, `analysis-anomalous-invoices`, `analysis-cashflow-anomalies`, `analysis-gl-journal-audit`, `analysis-exchange-rate-audit`, `analysis-receivables-customer-risk`, `analysis-cash-expense-health`. The audit-analyses are essential pre-emptive flags for the auditor.
@@ -61,7 +61,7 @@ The jurisdiction-specific deliverable list. SG: TB / BS / P&L / CF / EM / AR agi
 ## Step 2 — Trial balance (the master)
 
 ```
-generate_trial_balance(period_end: '2025-12-31', currency: <base currency>)
+generate_trial_balance(endDate: '2025-12-31', currencyCode: <base currency>)
 ```
 
 Save the FY trial balance. Verify: every report from step 3 onwards must tie back to a TB line.
@@ -69,14 +69,14 @@ Save the FY trial balance. Verify: every report from step 3 onwards must tie bac
 ## Step 3 — Primary financial statements
 
 ```
-generate_balance_sheet(period_end: '2025-12-31')
-generate_profit_and_loss(period_start: '2025-01-01', period_end: '2025-12-31')
+generate_balance_sheet(snapshotDate: '2025-12-31')
+generate_profit_and_loss(startDate: '2025-01-01', endDate: '2025-12-31')
 ```
 
 Optional comparative:
 ```
-generate_profit_and_loss(period_start: '2024-01-01', period_end: '2024-12-31')
-generate_balance_sheet(period_end: '2024-12-31')
+generate_profit_and_loss(startDate: '2024-01-01', endDate: '2024-12-31')
+generate_balance_sheet(snapshotDate: '2024-12-31')
 ```
 
 Assert: BS Total Assets = Total Liabilities + Total Equity. P&L Net Profit ties to Equity Movement (step 4) `netProfit` line.
@@ -84,8 +84,8 @@ Assert: BS Total Assets = Total Liabilities + Total Equity. P&L Net Profit ties
 ## Step 4 — Cashflow + Equity Movement
 
 ```
-generate_cashflow(period_start: '2025-01-01', period_end: '2025-12-31')
-generate_equity_movement(period_start: '2025-01-01', period_end: '2025-12-31')
+generate_cashflow(startDate: '2025-01-01', endDate: '2025-12-31')
+generate_equity_movement(primarySnapshotStartDate: '2025-01-01', primarySnapshotEndDate: '2025-12-31')
 ```
 
 Cashflow classifies into Operating / Investing / Financing per IAS 7. Equity Movement reconciles opening equity → net profit → dividends → other movements → closing equity. The closing equity must tie to BS step 3 Total Equity.
@@ -93,7 +93,7 @@ Cashflow classifies into Operating / Investing / Financing per IAS 7. Equity Mov
 ## Step 5 — General Ledger (auditor's working document)
 
 ```
-generate_general_ledger(period_start: '2025-01-01', period_end: '2025-12-31', groupBy: 'ACCOUNT')
+generate_general_ledger(startDate: '2025-01-01', endDate: '2025-12-31', groupBy: 'ACCOUNT')
 ```
 
 The tool returns 50 rows per call by default. Page it at `limit` 50-100: a GL row is about 1KB, so larger pages get cut to the tool's result cap and come back with `_truncated`. The offset is a ROW offset (`jaz-api/SKILL.md` rule 38): step it by the rows the call actually returned, which is what `_paging.nextOffset` holds, and stop when a result carries no `_paging`. Keep the full GL for the pack, since the auditor will sample-test from it. From the CLI, `clio reports generate general-ledger --all` pages it for you.
@@ -101,8 +101,8 @@ The tool returns 50 rows per call by default. Page it at `limit` 50-100: a GL ro
 ## Step 6 — AR / AP aging
 
 ```
-generate_aged_ar(period_end: '2025-12-31')
-generate_aged_ap(period_end: '2025-12-31')
+generate_aged_ar(endDate: '2025-12-31')
+generate_aged_ap(endDate: '2025-12-31')
 ```
 
 Use `endDate` not `startDate` (rule 36 — point-in-time snapshot). Assert:
@@ -111,16 +111,16 @@ Use `endDate` not `startDate` (rule 36 — point-in-time snapshot). Assert:
 
 If ECL provision feels inadequate for the > 90d bucket, run the ECL recipe immediately:
 ```
-plan_recipe(recipe: 'ecl', receivables: <aged_ar.buckets converted to ECL input>, ...)
+plan_recipe(recipe: 'ecl', buckets: <aged AR buckets as [{name, balance, rate}]>, existingProvision, startDate, ...)
 ```
 And post any top-up provision via `execute_recipe`. This avoids an auditor-proposed adjustment at fieldwork.
 
 ## Step 7 — Bank reconciliation (NON-NEGOTIABLE)
 
 ```
-generate_bank_recon_summary(period_end: '2025-12-31')
-generate_bank_recon_details(period_end: '2025-12-31')
-generate_bank_balance_summary(period_end: '2025-12-31')
+generate_bank_recon_summary(bankAccountResourceId: <each bank account>, primarySnapshotStartDate: '2025-01-01', primarySnapshotEndDate: '2025-12-31')
+generate_bank_recon_details(bankAccountResourceId: <each bank account>, primarySnapshotStartDate: '2025-01-01', primarySnapshotEndDate: '2025-12-31', filter: {valueDate: {range: ['2025-01-01', '2025-12-31']}})
+generate_bank_balance_summary(primarySnapshotDate: '2025-12-31')
 ```
 
 For each bank account: `unreconciledCount` MUST be 0 OR every unreconciled item has a documented timing-difference explanation. The auditor will request bank confirmation letters DIRECTLY from your banks — `generate_bank_balance_summary` total must reconcile to those letters within tolerance.
@@ -130,8 +130,8 @@ If `unreconciledCount > 0`: halt audit-prep and route back to `bank-recon.md` jo
 ## Step 8 — Fixed assets + supporting schedules
 
 ```
-generate_fa_summary(period_end: '2025-12-31')
-generate_fa_recon_summary(period_start: '2025-01-01', period_end: '2025-12-31')
+generate_fa_summary(primarySnapshotStartDate: '2025-01-01', primarySnapshotEndDate: '2025-12-31', groupBy: 'CATEGORY')
+generate_fa_recon_summary(primarySnapshotStartDate: '2025-01-01', primarySnapshotEndDate: '2025-12-31')
 ```
 
 Assert: `fa_recon.openingNbv + additions - disposals - depreciation == fa_recon.closingNbv == TB['Fixed Assets'].balance`.
@@ -145,7 +145,7 @@ For each capsule, run the matching `clio calc <type>` to produce the independent
 ## Step 9 — Tax ledger
 
 ```
-generate_vat_ledger(period_start: '2025-01-01', period_end: '2025-12-31')
+generate_vat_ledger(startDate: '2025-01-01', endDate: '2025-12-31')
 ```
 
 For SG: annual total ties to sum of 4 quarterly GST F5 returns. For PH: annual total ties to monthly VAT returns + quarterly summary. The annual reconciliation should already be clean if the `gst-vat-filing.md` job ran each period.
@@ -223,8 +223,8 @@ The SG Form C-S wizard walks the user field-by-field through the C-S form, prefi
 | `generate_bank_recon_*` | `unreconciledCount > 0` | Route to `bank-recon.md`; do NOT hand pack with this open. |
 | `download_export` | 422 `period_too_long` | GL XLSX rejected for >12 months. Split into per-quarter exports. |
 | `download_export` | 504 timeout | Large org. Re-run with smaller `endDate` range or contact infrastructure team. |
-| `update_account` | 422 `lock_date_in_future` | The CoA `lockDate` must be ≤ `period_end`. Use today if unsure. |
-| Reconciliation | TB AR ≠ AR aging | Likely a mid-period credit-note application missed. `search_customer_credit_notes(filter: {valueDate: {between: ...}})` and verify each was applied via `apply_credit_to_invoice`. |
+| `update_account` | 422 `lock_date_in_future` | The CoA `lockDate` must be ≤ the period end date. Use today if unsure. |
+| Reconciliation | TB AR ≠ AR aging | Likely a mid-period credit-note application missed. `search_customer_credit_notes(filter: {valueDate: {between: ...}})` and verify each was applied via `apply_credits_to_invoice`. |
 | Reconciliation | TB Cash ≠ bank balance summary | Unposted bank journal or unreconciled item. Re-run step 7. |
 | Step 12 gate | Drafts present at year-end | Either clear (finalize) or document the residuals and surface to the user. NEVER hand the pack over with drafts in the audit period. |
 

package/assets/skills/jobs/references/bank-recon.md

@@ -29,14 +29,14 @@
 - **`reconcile_cash_transfer(...)`** — inter-account transfer.
 
 ### Platform tools — create missing transactions
-- **`mcp magic create --file <pdf>` / `create_business_transaction_from_attachment(...)`** — step 6 path B: OCR + autofill bill or invoice from receipt PDF/JPG.
-- **`create_cash_in_entry(...)` / `create_cash_out_entry(...)`** — step 6 path C: bank fees, interest, FX charges that have no source document.
+- **`mcp magic create --file <pdf>` / `create_bt_from_attachment(...)`** — step 6 path B: OCR + autofill bill or invoice from receipt PDF/JPG.
+- **`create_cash_in(...)` / `create_cash_out(...)`** — step 6 path C: bank fees, interest, FX charges that have no source document.
 - **`create_bank_rule(...)`** — preventive: build a rule for any recurring pattern you handled this run (subscription, rent, utility) so it auto-applies next time.
 
 ### Platform tools — verification
-- **`generate_bank_recon_summary(period_end, accountResourceId)`** — step 7: per-account formal recon statement.
-- **`generate_bank_recon_details(period_end, accountResourceId)`** — step 7: line-level recon detail for audit pack.
-- **`generate_bank_balance_summary(period_end)`** — step 8: book balance vs bank statement balance per account.
+- **`generate_bank_recon_summary(bankAccountResourceId, primarySnapshotStartDate, primarySnapshotEndDate)`** — step 7: per-account formal recon statement.
+- **`generate_bank_recon_details(bankAccountResourceId, primarySnapshotStartDate, primarySnapshotEndDate, filter: {valueDate: {range: [from, to]}})`** — step 7: line-level recon detail for audit pack.
+- **`generate_bank_balance_summary(primarySnapshotDate)`** — step 8: book balance vs bank statement balance per account.
 
 ### CLI tools — bulk auto-match cascade (offline)
 - **`clio jobs bank-recon match --input <records.json> --tolerance 0.01 --date-window 14 --max-group 5 --json`** — the 5-phase cascade matcher (Phase 1 exact 1:1 hash join, Phase 2 fuzzy 1:1 greedy with weighted scoring, Phase 3 N:1, Phase 4 1:N, Phase 5 N:M). Returns matches sorted by confidence — feed each into the appropriate `reconcile_*` tool. See `bank-match.md` for the full algorithm.
@@ -83,7 +83,7 @@ Flag any item older than 60 days as red — surface to practitioner.
 search_bank_records(accountResourceId: B.resourceId, status: 'POSSIBLE_DUPLICATE', limit: 200)
 ```
 
-Two bank-feed entries with same `valueDate + netAmount + description` = system-flagged duplicate. Review each pair: archive the duplicate via `archive_bank_record(resourceId: <id>)` BEFORE running step 4. If you reconcile a duplicated row, you'll create double cashflow entries.
+Two bank-feed entries with same `valueDate + netAmount + description` = system-flagged duplicate. Review each pair and ask the user to archive the duplicate in the Jaz app BEFORE running step 4 (no tool archives a bank record). Until it is archived, reconcile neither row of the pair: reconciling a duplicated row creates double cashflow entries.
 
 Record the judgment per archived pair: `jot(kind: MATCH)` naming the kept entry, the archived entry, and the tie-breaker used.
 
@@ -158,33 +158,30 @@ For unreconciled rows that have no book-side counterpart yet:
 ```
 mcp magic create --file <invoice-or-receipt-path>
 # OR equivalent MCP call:
-create_business_transaction_from_attachment(
-  sourceFile: <base64 or upload>,
+create_bt_from_attachment(
   businessTransactionType: 'BILL' | 'INVOICE',
-  sourceType: 'FILE'
+  sourceUrl: <file URL>   // omit when the host attaches the file to the call
 )
 ```
 Magic does OCR + line item extraction + contact matching + CoA suggestion. Returns draft. Review, finalize via `finalize_bill` / `finalize_invoice`, then loop back to step 4 to reconcile.
 
 **Path C — bank fees / interest / FX charges (no document):**
 ```
-create_cash_out_entry(
+create_cash_out(
   reference: 'BANK-FEE-2025-01-15-001',
   valueDate: '2025-01-15',
   accountResourceId: <bank-account-id>,
   lines: [{
     accountResourceId: <Bank Charges expense GL>,
     amount: 25.00,
-    type: 'DEBIT',
-    name: 'Monthly service charge — Jan 2025'
-  }],
-  saveAsDraft: false
+    description: 'Monthly service charge, Jan 2025'
+  }]
 )
 ```
 
-Per rule 26: `accountResourceId` at top level is the BANK account; `lines[]` carries the offset (expense / income).
+Per rule 26: `accountResourceId` at top level is the BANK account; `lines[]` carries the offset (expense / income). Cash lines take no `type`: the endpoint sets the direction.
 
-For interest income: `create_cash_in_entry(...)` with `type: 'CREDIT'` line against `Interest Income`.
+For interest income: `create_cash_in(...)` with a line against `Interest Income`.
 
 After creating, loop back to step 4 to reconcile.
 
@@ -223,8 +220,8 @@ search_bank_records(accountResourceId: B.resourceId, status: 'UNRECONCILED', lim
 Target: zero rows OR all remaining are documented timing differences (outstanding cheques, deposits in transit clearing next period — practitioner annotates). Record the judgment: `jot(kind: SCOPE)` naming each residual accepted as a timing difference and why it clears next period.
 
 ```
-generate_bank_recon_summary(period_end: '2025-01-31', accountResourceId: B.resourceId)
-generate_bank_recon_details(period_end: '2025-01-31', accountResourceId: B.resourceId)
+generate_bank_recon_summary(bankAccountResourceId: B.resourceId, primarySnapshotStartDate: '2025-01-01', primarySnapshotEndDate: '2025-01-31')
+generate_bank_recon_details(bankAccountResourceId: B.resourceId, primarySnapshotStartDate: '2025-01-01', primarySnapshotEndDate: '2025-01-31', filter: {valueDate: {range: ['2025-01-01', '2025-01-31']}})
 ```
 
 Keep both the summary and the line-level detail per account — audit-prep step 7 will require them.
@@ -232,7 +229,7 @@ Keep both the summary and the line-level detail per account — audit-prep step
 ## Step 8 — Cross-account verify
 
 ```
-generate_bank_balance_summary(period_end: '2025-01-31')
+generate_bank_balance_summary(primarySnapshotDate: '2025-01-31')
 ```
 
 Per account: `bookBalance == bankStatementBalance ± documentedTimingDifference`. Discrepancy = unreconciled item missed → loop back to step 2 for that account.
@@ -253,9 +250,9 @@ Per account: `bookBalance == bankStatementBalance ± documentedTimingDifference`
 | `reconcile_with_payments` | 422 `TOTAL_RECONCILIATION_AMOUNT_MISMATCHED...` | Payments + adjustments ≠ bank entry amount. Add the delta as an `adjustment.cashAdjustmentEntries[]` leg (over/under-payment or FX write-off) so the total matches, then resend. |
 | `reconcile_with_payments` | 422 `...does not exist` / invalid status | The BT isn't an open bill/invoice (wrong id, already paid, or draft). Re-fetch via `search_cashflow_transactions`; finalize if draft. |
 | `reconcile_invoice_receipt` | 422 `invoice_status_invalid` | Matched invoice still DRAFT. `finalize_invoice(resourceId: <id>)` first. |
-| `reconcile_invoice_receipt` | 422 `amount_mismatch` | Bank amount ≠ invoice balance. Either partial payment (post via `create_invoice_payment` with partial amount, then reconcile), or wrong match (revisit step 4/5). |
+| `reconcile_invoice_receipt` | 422 `amount_mismatch` | Bank amount ≠ invoice balance. Either partial payment (post via `pay_invoice` with partial amount, then reconcile), or wrong match (revisit step 4/5). |
 | `apply_bank_rule` | 422 `rule_action_unsupported` | Rule's configured action doesn't match the bank entry shape (e.g., rule expects positive amount, entry is negative). Edit the rule via `update_bank_rule`. |
-| `create_cash_out_entry` | 422 `lock_date_violated` | `valueDate` in locked period. Lift lock via `update_account` lockDate, post, re-lock. |
+| `create_cash_out` | 422 `lock_date_violated` | `valueDate` in locked period. Lift lock via `update_account` lockDate, post, re-lock. |
 | Step 7 `unreconciledCount > 0` after step 6 | (residual misses) | Surface to the user with categorized residual ("3 bank charges to expense via path C, 1 unidentified deposit pending client query"). Record the residuals. Do NOT progress the month-end close with open items. |
 
 ---

package/assets/skills/jobs/references/building-blocks.md

@@ -18,7 +18,7 @@ Period derivation:
 
 **Period boundaries matter for:**
 - `search_*` filters — `{valueDate: {between: [<period-start>, <period-end>]}}` per `jaz-api/SKILL.md` rule 2.
-- Reports — `period_end` for snapshots; `period_start + period_end` for ranges.
+- Reports — each tool names its own dates: `endDate` (trial balance, aged AR/AP, cash balance), `snapshotDate` (balance sheet), `startDate` + `endDate` (P&L, cashflow, general ledger, VAT ledger), `primarySnapshotStartDate` + `primarySnapshotEndDate` (FA summary/recon, equity movement, bank recon), `primarySnapshotDate` (bank balance summary).
 - Lock dates — `update_account` lockDate sets the close marker.
 
 ## Lock dates
@@ -36,17 +36,17 @@ Per-account locks (rare): set `lockDate` on a specific bank account or controlle
 Run after every period close:
 
 ```
-generate_trial_balance(period_end: <period-end>)
-generate_profit_and_loss(period_start: <period-start>, period_end: <period-end>)
-generate_balance_sheet(period_end: <period-end>)
+generate_trial_balance(endDate: <period-end>)
+generate_profit_and_loss(startDate: <period-start>, endDate: <period-end>)
+generate_balance_sheet(snapshotDate: <period-end>)
 ```
 
 Standard assertions:
 - TB: `Debits == Credits` (always; if not, system bug).
 - BS: `Total Assets == Total Liabilities + Total Equity`.
-- TB AR == `generate_aged_ar(period_end)` total.
-- TB AP == `generate_aged_ap(period_end)` total.
-- TB Cash == `generate_bank_balance_summary(period_end)` per-bank total (via `bank-recon.md`).
+- TB AR == `generate_aged_ar(endDate)` total.
+- TB AP == `generate_aged_ap(endDate)` total.
+- TB Cash == `generate_bank_balance_summary(primarySnapshotDate)` per-bank total (via `bank-recon.md`).
 
 ## Pre-emitted DRAFT journal pattern
 

package/assets/skills/jobs/references/credit-control.md

@@ -5,12 +5,12 @@
 ## Tools, recipes, calculators this job uses
 
 ### Platform tools
-- **`generate_aged_ar(period_end: <date>)`** — step 1: AR aging report with bucket breakdown.
+- **`generate_aged_ar(endDate: <date>)`** — step 1: AR aging report with bucket breakdown.
 - **`search_invoices(filter: {status: {eq: 'UNPAID'}, dueDate: {lt: <date>}, contactResourceId: <customer>}, sortBy: 'dueDate', sortOrder: 'ASC', limit: 200)`** — step 2: per-customer overdue detail. Paginate.
 - **`get_contact(resourceId: <customer id>)`** — step 2: pull contact info (email, phone, primary contact).
 - **`get_contact_signals(resourceId: <id>, btType: 'SALE')`** — step 3: pull cadence + outlier signals + outstanding balance for the customer. Mid-7 endpoint.
-- **`apply_credit_to_invoice(...)`** / **`create_customer_credit_note(...)`** — step 6: write-off path A for stage-3 specific impairment.
-- **`create_invoice_payment(... paymentMethod: 'DEBT_WRITE_OFF' ...)`** — step 6: write-off path B (direct).
+- **`apply_credits_to_invoice(...)`** / **`create_customer_credit_note(...)`** — step 6: write-off path A for stage-3 specific impairment.
+- **`pay_invoice(... paymentMethod: 'DEBT_WRITE_OFF' ...)`** — step 6: write-off path B (direct).
 - **`plan_recipe(recipe: 'ecl', ...)` + `execute_recipe(...)`** — step 7: ECL collective top-up if material change in aging.
 - **`download_export(exportType: 'analysis-receivables-customer-risk', startDate, endDate)`** — step 8: pre-empt audit by surfacing high-risk customers.
 
@@ -28,7 +28,7 @@ Walk steps 1-8 below. (Local CLI: `clio jobs credit-control --overdue-days 30` p
 ## Step 1 — AR aging snapshot
 
 ```
-generate_aged_ar(period_end: '2025-01-31')
+generate_aged_ar(endDate: '2025-01-31')
 ```
 
 Save the AR aging snapshot. Returns aging buckets (current, 30d, 60d, 90d, 120d+) per customer. Total per bucket informs collection priority.
@@ -93,7 +93,7 @@ For each customer chased: keep a chase log with:
 - Promised payment date (if any)
 - Next action date
 
-Capsule alternative: `create_capsule(capsuleType: 'Bad Debt Write-off', title: 'Credit Control — <customer> — FY2025')` with the chase log as the description; attach any eventual write-off journal / credit note to the same capsule for audit trail.
+Capsule alternative: `create_capsule(capsuleTypeResourceId: <id of 'Bad Debt Write-off' from list_capsule_types>, title: 'Credit Control — <customer> — FY2025')` with the chase log as the description; attach any eventual write-off journal / credit note to the same capsule for audit trail.
 
 ## Step 6 — Specific write-off (stage-3 impairment)
 
@@ -108,26 +108,25 @@ create_customer_credit_note(
   lineItems: [{
     name: 'Write-off — uncollectible (formal insolvency)',
     accountResourceId: <Bad Debt Expense GL>,
-    amount: <balance to write off>,
-    saveAsDraft: false
+    quantity: 1,
+    unitPrice: <balance to write off>
   }],
+  saveAsDraft: false,
   capsuleResourceId: <credit-control capsule>
 )
-apply_credit_to_invoice(invoiceResourceId: <inv>, creditNoteResourceId: <cn>, amount: <balance>)
+apply_credits_to_invoice(resourceId: <inv>, credits: [{creditNoteResourceId: <cn>, amountApplied: <balance>}])
 ```
 
 **Path B — direct write-off**:
 ```
-create_invoice_payment(
-  invoiceResourceId: <inv>,
-  payments: [{
-    paymentAmount: <balance>,
-    transactionAmount: <balance>,
-    accountResourceId: <Bad Debt Expense GL>,
-    paymentMethod: 'DEBT_WRITE_OFF',
-    reference: 'WRITE-OFF-<inv>',
-    valueDate: '2025-01-31'
-  }]
+pay_invoice(
+  resourceId: <inv>,
+  paymentAmount: <balance>,
+  transactionAmount: <balance>,
+  accountResourceId: <Bad Debt Expense GL>,
+  paymentMethod: 'DEBT_WRITE_OFF',
+  reference: 'WRITE-OFF-<inv>',
+  valueDate: '2025-01-31'
 )
 ```
 
@@ -145,9 +144,9 @@ clio calc ecl --current <c> --30d <30> --60d <60> --90d <90> --120d <120> --rate
 
 If `topUpRequired > materiality threshold`:
 ```
-plan_recipe(recipe: 'ecl', ..., capsuleResourceId: <credit-control capsule OR new ECL Provision capsule>)
-execute_recipe(...)
-bulk_finalize_drafts({kind: 'journal'}, resourceIds: [...]})
+plan_recipe(recipe: 'ecl', ...)
+execute_recipe(...)   // creates its own ECL Provision capsule; regroup with move_transaction_capsules if needed
+bulk_update_journals(items: [{resourceId: <id>, saveAsDraft: false}, ...])
 ```
 
 Note: monthly ECL is typically a mental check; formal ECL provision recompute is quarterly (per `quarter-end-close.md` Q2). Trigger this monthly only on material shifts.
@@ -168,7 +167,7 @@ Returns XLSX with high-risk customer flags (rising aging trends, recently-defaul
 |--------|-------|----------|
 | Step 2 | `search_invoices` returns 0 despite aging shows overdue | Aging report may include `PARTIALLY_PAID` invoices; expand filter `status: {in: ['UNPAID', 'PARTIALLY_PAID']}`. |
 | Step 3 | `get_contact_signals` returns `null` | The freshness layer is offline; skip the signals step and use aging alone. Don't halt the job. |
-| Step 6 Path A | `apply_credit_to_invoice` 422 `credit_exceeds_balance` | Split the credit across multiple invoices, OR reduce the credit amount to match the bill balance. |
+| Step 6 Path A | `apply_credits_to_invoice` 422 `credit_exceeds_balance` | Split the credit across multiple invoices, OR reduce the credit amount to match the bill balance. |
 | Step 6 Path B | `paymentMethod: 'DEBT_WRITE_OFF'` rejected | Verify the enum value via `jaz-api/SKILL.md` (some orgs may have custom payment-method config; default supports DEBT_WRITE_OFF). |
 | Step 7 ECL recipe | Top-up causes Bad Debt Expense to spike | Expected — material aging shift = material P&L impact. Surface to practitioner; potentially split across multiple periods if it's a known one-off (rare). |
 | Customer files insolvency mid-chase | (process) | Stop chase. Move directly to step 6 specific write-off. Document the insolvency filing reference. |

package/assets/skills/jobs/references/document-collection.md

@@ -5,9 +5,9 @@
 ## Tools, recipes, calculators this job uses
 
 ### Platform tools
-- **`mcp magic create --file <pdf>` / `create_business_transaction_from_attachment(sourceFile, businessTransactionType: 'BILL'|'INVOICE'|'CREDIT_NOTE', sourceType: 'FILE')`** — step 4: OCR + line-item extraction + contact + CoA suggestion. Creates DRAFT transaction.
+- **`mcp magic create --file <pdf>` / `create_bt_from_attachment(businessTransactionType: 'BILL'|'INVOICE'|'CUSTOMER_CREDIT_NOTE'|'SUPPLIER_CREDIT_NOTE', sourceUrl)`** — step 4: OCR + line-item extraction + contact + CoA suggestion. Creates DRAFT transaction.
 - **`finalize_bill(...)` / `finalize_invoice(...)` / `finalize_customer_credit_note(...)`** — step 5: finalize practitioner-reviewed Magic-extracted DRAFTs.
-- **`import_bank_statement(bankAccountResourceId, sourceFile, sourceType: 'FILE')`** — step 6: bank statements (CSV / OFX / PDF); creates bank records pending reconciliation per `bank-recon.md`.
+- **`import_bank_statement(accountResourceId, sourceUrl | attachmentId)`** — step 6: bank statements (CSV / OFX / PDF); creates bank records pending reconciliation per `bank-recon.md`.
 - **`search_background_jobs(filter: {resourceId: {eq: <jobId>}})`** — step 7: poll Magic / bank-import async jobs to terminal status.
 
 ### CLI tools (jaz-cli — offline)
@@ -88,10 +88,9 @@ For each file with `suggestedAction: 'magic-create-bill' | 'magic-create-invoice
 ```
 mcp magic create --file <decrypted path> --type bill
 # OR equivalent MCP call:
-create_business_transaction_from_attachment(
-  sourceFile: <multipart upload>,
+create_bt_from_attachment(
   businessTransactionType: 'BILL',
-  sourceType: 'FILE'
+  sourceUrl: <file URL>   // omit when the host attaches the file to the call
 )
 ```
 
@@ -117,7 +116,7 @@ When approved:
 ```
 finalize_bill(resourceId: <id>)
 # OR for batch:
-bulk_finalize_drafts({kind: 'bill', resourceIds: [...]})
+bulk_finalize_drafts(items: [{type: 'bill', resourceId: <id>}, ...])
 ```
 
 ## Step 6 — Bank statement import
@@ -133,9 +132,8 @@ Match by name + currency to the statement (typically the bank logo + account num
 
 ```
 import_bank_statement(
-  bankAccountResourceId: <bank id>,
-  sourceFile: <statement file>,
-  sourceType: 'FILE'
+  accountResourceId: <bank id>,
+  sourceUrl: <statement file URL>   // or attachmentId
 )
 ```
 
@@ -174,9 +172,9 @@ Auditor sample-test traces from a posted bill back to the source PDF. Audit trai
 | Step 4 Magic | 422 `unsupported_file_type` | Convert to PDF / JPG first. Excel / Word formats not supported by Magic OCR. |
 | Step 4 Magic | Job stays in QUEUED for > 5 minutes | Magic queue is backed up. Check status; consider manual posting if blocking close. |
 | Step 4 Magic | `PARTIAL_SUCCESS` with low-confidence extractions | Review each in step 5; practitioner overrides. Magic confidence < 0.7 = manual review required. |
-| Step 5 review | Wrong contact assigned | `update_bill(contactResourceId: <correct id>)` before finalize. |
+| Step 5 review | Wrong contact assigned | `update_bill(resourceId: <bill id>, ...)` does not take `contactResourceId`: delete the draft and re-create it against the correct contact, then finalize. |
 | Step 5 review | Wrong line-item GL | `update_bill(lineItems: [<corrected>])` before finalize. |
-| Step 6 bank import | 422 `bank_format_unsupported` | Bank format not supported (some niche banks). Manual `add_bank_records(bankAccountResourceId, records: [...])` per statement line. |
+| Step 6 bank import | 422 `bank_format_unsupported` | Bank format not supported (some niche banks). Manual `add_bank_records(accountResourceId, records: [...])` per statement line. |
 | Step 7 polling | Job stuck in PROCESSING > 10 minutes | Escalate; usually a Magic backend issue. |
 
 ---