jaz-clio 9.2.4 → 9.2.6

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 9.2.4
+version: 9.2.6
 description: >-
   Use this skill whenever you call, debug, or review code that touches the Jaz
   REST API. Covers field names, response shapes, 148 production gotchas, error
@@ -407,7 +407,7 @@ Bills, invoices, and credit notes share identical mandatory field specs. Adding
 123. **12 reconciliation action endpoints under `/api/v1/reconciliations/*`**. These *commit* a reconciliation decision against a bank statement entry, distinct from `view_auto_reconciliation` (which queries `/search-magic-reconciliation` for *suggestions*):
     - **Async (jobId):** `quick_reconcile` (bulk match entries to journals, max 500), `apply_bank_rule` (bulk apply a rule to entries, max 500). Poll `search_background_jobs` filtered by `resourceId`; on `PARTIAL_SUCCESS` read `data[0].errorDetails` for per-row failures.
     - **Sync (single bank entry):** `reconcile_direct_cash_entry`, `reconcile_cash_journal`, `reconcile_manual_journal`, `reconcile_cash_transfer`, `reconcile_invoice_receipt`, `reconcile_bill_receipt`, `reconcile_with_payments` (match EXISTING; see Rule 158), `reconcile_learned_prediction`. Each returns `{bankStatementEntryResourceId, status, reference, valueDate}`.
-    - **Sync bulk:** `reconcile_magic_match` (bulk-accept MAGIC_MATCH suggestions, max 500) returns `{reconciled[], failed[]}`; `undo_reconciliations` (unlink, 1-500) returns `{resetReconciliationResponse[], linkedRecords[]}`; see Rule 125.
+    - **Sync bulk:** `reconcile_magic_match` (bulk-accept MAGIC_MATCH and MAGIC_RECONCILE_WITH_CASH_IN_OUT suggestions, max 500) returns `{reconciled[], failed[]}`; `undo_reconciliations` (unlink, 1-500) returns `{resetReconciliationResponse[], linkedRecords[]}`; see Rule 125.
 
 124. **Recon prefill from the bank statement entry**: when caller omits `valueDate`, `dueDate`, payment `amount`, or direction (cash-in vs cash-out), the API fills these from the bank entry. Best-effort: a missing entry lookup logs a warning and forwards the payload as-is. Caller can always override by passing the field explicitly.
 
@@ -508,10 +508,10 @@ When the user wants to OPEN, SEE, or SHARE something in the Jaz dashboard ("open
 
 158. **Match-to-EXISTING reconciliation: `reconcile_with_payments` / `reconcile_magic_match` / `reconcile_learned_prediction`.** These reconcile a bank entry against transactions/payments the org ALREADY has, vs `invoice_receipt`/`bill_receipt` which CREATE new ones. Prefer match-to-existing to avoid duplicates.
     - **`reconcile_with_payments`**: the headline. `businessTransactionPayments[]` each carry an open bill/invoice's `cashflowTransactionResourceId` (from `search_cashflow_transactions` or a suggestion's `cftBtResourceId`) + `transactionAmount`; the endpoint CREATES the payment AND reconciles in one call; **no `pay_bill`/`pay_invoice` first.** Also accepts `matchedPayments[]` (existing payments) / `matchedBatchPayments[]` / `adjustment` (over/under-payment + FX write-off). Guard: ≥1 match array non-empty. **FX is auto-resolved server-side; pass NO `currencySettings`/rate for the common case.** Only the rare bill-currency ≠ bank-currency case needs explicit `paymentAmount` (bank ccy) + `currencySettings`. FX gain/loss is NOT auto-posted; post it via `adjustment.cashAdjustmentEntries[]` to an FX account. Errors: `PAYMENT_AMOUNT_REQUIRED_IN_BUSINESS_TRANSACTION_SOURCE_CURRENCY` (cross-ccy missing paymentAmount), `INVALID_EXCHANGE_RATE_ERROR` (adjustment leg in non-functional ccy missing rate), `TOTAL_RECONCILIATION_AMOUNT_MISMATCHED_WITH_STATEMENT_ENTRY_AMOUNT` (sum ≠ entry → add adjustment leg). **NOT idempotent, no client key: a blind retry double-creates a payment; re-check `search_bank_records(status:'RECONCILED')` before retry.**
-    - **`reconcile_magic_match`**: bulk-accept MAGIC_MATCH suggestions (max 500 entries). Returns `{reconciled[], failed[]}`; a 200 with non-empty `failed[]` is a PARTIAL success (per-entry `errorCode`); loop on failed only. Entry-level idempotency-keyed server-side (re-submit returns done entries in `reconciled[]`).
+    - **`reconcile_magic_match`**: bulk-accept suggestions (max 500 entries, at most 100 of them `MAGIC_RECONCILE_WITH_CASH_IN_OUT`; each bank entry once per call). A `MAGIC_MATCH` entry matches existing transactions/payments; a `MAGIC_RECONCILE_WITH_CASH_IN_OUT` entry carries `learnedPredictionResourceId` + `predictedPayload` + `predictedPayloadSchemaVersion` verbatim from the suggestion (optional `retryToken`), exactly as `reconcile_learned_prediction` takes them for one entry. Pass each suggestion's `recommendationId` on its entry (and on `reconcile_learned_prediction`) so the accept is credited to it. Returns `{reconciled[], failed[]}` (either may be absent or empty); a 200 with non-empty `failed[]` is a PARTIAL success (per-entry `errorCode`); when nothing reconciled the call fails with 422. An entry carries only its own workflow's fields (no matches on a CASH_IN_OUT entry, no learned-prediction fields on MAGIC_MATCH). A `failed[]` entry may still have posted (an unexpected failure reports the whole group failed), so re-read each line's state before any retry. `MAGIC_MATCH` entries are NOT idempotent: never blind-retry a timed-out batch; re-read the line state (`search_bank_records`) first. A `MAGIC_RECONCILE_WITH_CASH_IN_OUT` entry is keyed on bank entry + prediction + `retryToken`, so resending it unchanged never books a second journal.
     - **`reconcile_learned_prediction`**: accept an ML prediction. `predictedPayload` + `predictedPayloadSchemaVersion` come VERBATIM from a `view_auto_reconciliation` (MAGIC_RECONCILE_WITH_CASH_IN_OUT) suggestion; never hand-construct. `retryToken` forces a fresh journal on edit-retry; omit for idempotent replay. On failure (stale payload), fall back to `reconcile_with_payments`; don't retry the blob.
 
-159. **`view_auto_reconciliation` returns execution-ready `suggestions[]`, the suggestion→commit seam.** **`bankStatementEntryResourceIds` is REQUIRED: the endpoint is per-entry and has no account-wide mode; source ids from `search_bank_records` (status `UNRECONCILED`).** Each suggestion carries `recommendedTool` (the commit tool to call), `execute` (ready-to-pass args; merge `bankAccountResourceId` for `reconcile_magic_match`), `confidenceTier` (high/medium/low, code-derived), and `autoCommitEligible` (true ⇒ high confidence + executable plan + under any `autoCommitMaxAmount` cap + for a learned prediction (`MAGIC_RECONCILE_WITH_CASH_IN_OUT`) a `lifecycleStatus` of `ACTIVE`; a `PROBATIONARY` one is still learning and checkpoints at any confidence), plus `checkpointReason` whenever it is false. **Decision gate:** `autoCommitEligible===true` → auto-commit via `recommendedTool`+`execute`; everything else → surface for confirmation. **Amount threshold is a HARD VETO over confidence** (pass `autoCommitMaxAmount`). Field mapping under the hood: `cftBtResourceId`→`cashflowTransactionResourceId` (single → `reconcile_with_payments`), `cftBtResourceIds[]`/`isBatch`→`matchedBusinessTransactions` (batch → `reconcile_magic_match`), `recommendationType`→tool, `confidenceScore`→tier. **Request vs response vocabulary:** the `recommendationType` you SEND selects what to compute and additionally accepts `RECOMMENDATIONS` (every type except `MAGIC_MATCH`, ranked together, and the cheaper call; `MAGIC_MATCH` scans open transactions so it is requested on its own; nothing returns everything at once). The `recommendationType` you RECEIVE on a suggestion is always a concrete type and is never `RECOMMENDATIONS`, so the `recommendationType`→tool mapping above is unaffected by which selector you sent. Pass `includeRaw:true` for the unmapped payload. Cost tracks the entries you pass; batch large backlogs. On a 500, or no answer in time (25 s in chat and on hosted MCP, 55 s on stdio MCP, 60 s from the CLI and `clio mcp-call`), it returns `{degraded:true}` with a `reason` naming the wait; use the `clio jobs bank-recon match` cascade. NOT idempotent applies to every commit; see Rules 125 + 158.
+159. **`view_auto_reconciliation` returns execution-ready `suggestions[]`, the suggestion→commit seam.** **`bankStatementEntryResourceIds` is REQUIRED: the endpoint is per-entry and has no account-wide mode; source ids from `search_bank_records` (status `UNRECONCILED`).** Each suggestion carries `recommendedTool` (the commit tool to call), `execute` (ready-to-pass args, including the suggestion's `recommendationId` when the platform sent one; merge `bankAccountResourceId` for `reconcile_magic_match`), `confidenceTier` (high/medium/low, code-derived), and `autoCommitEligible` (true ⇒ high confidence + executable plan + under any `autoCommitMaxAmount` cap + for a learned prediction (`MAGIC_RECONCILE_WITH_CASH_IN_OUT`) a `lifecycleStatus` of `ACTIVE`; a `PROBATIONARY` one is still learning and checkpoints at any confidence), plus `checkpointReason` whenever it is false. **Decision gate:** `autoCommitEligible===true` → auto-commit via `recommendedTool`+`execute`; everything else → surface for confirmation. **Amount threshold is a HARD VETO over confidence** (pass `autoCommitMaxAmount`). Field mapping under the hood: `cftBtResourceId`→`cashflowTransactionResourceId` (single → `reconcile_with_payments`), `cftBtResourceIds[]`/`isBatch`→`matchedBusinessTransactions` (batch → `reconcile_magic_match`), `recommendationType`→tool, `confidenceScore`→tier. **Request vs response vocabulary:** the `recommendationType` you SEND selects what to compute and additionally accepts `RECOMMENDATIONS` (every type except `MAGIC_MATCH`, ranked together, and the cheaper call; `MAGIC_MATCH` scans open transactions so it is requested on its own; nothing returns everything at once). The `recommendationType` you RECEIVE on a suggestion is always a concrete type and is never `RECOMMENDATIONS`, so the `recommendationType`→tool mapping above is unaffected by which selector you sent. Pass `includeRaw:true` for the unmapped payload. Cost tracks the entries you pass; batch large backlogs. On a 500, or no answer in time (25 s in chat and on hosted MCP, 55 s on stdio MCP, 60 s from the CLI and `clio mcp-call`), it returns `{degraded:true}` with a `reason` naming the wait; use the `clio jobs bank-recon match` cascade. NOT idempotent applies to every commit; see Rules 125 + 158.
 
 ## See Also
 

package/assets/skills/api/references/full-api-surface.md

@@ -3,7 +3,7 @@
 > **The endpoints clio wraps (the REST surface is larger).** This file catalogues roughly 200
 > paths, organized by resource, including undocumented endpoints, magic AI features, admin
 > APIs, and advanced search/filter syntax. The committed OpenAPI spec (`spec/openapi.yaml`)
-> carries 475 spec paths and 607 spec operations and is the authoritative list; check it before concluding
+> carries 510 spec paths and 648 spec operations and is the authoritative list; check it before concluding
 > an endpoint does not exist. For request/response examples of core endpoints, see
 > endpoints.md.
 >

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 9.2.4
+version: 9.2.6
 description: >-
   Use this skill when running Clio CLI commands, building shell scripts with
   Clio, debugging auth issues, understanding --json output, paginating results,
@@ -316,7 +316,7 @@ The same operation is `navigate` on the MCP surface. Full usage rules live in th
 
 CLI commands exit with standard codes:
 - **Exit 0**: success
-- **Exit 1**: your input needs changing (missing flags, malformed id, over-limit or duplicate batch, blank required text, unknown enum value). Also a business refusal on some commands, e.g. `approvals`.
+- **Exit 1**: your input needs changing (missing flags, malformed id, over-limit or duplicate batch, blank required text, unknown enum value). Also a business refusal on some commands, e.g. `approvals`, and a partial success on `reconciliations magic-match` (outcome on stdout; re-read the lines before any retry).
 - **Exit 2**: the request was fine and the API refused or failed, OR an internal defect
 - **Exit 3**: auth (invalid, missing or unresolvable key)
 

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 9.2.4
+version: 9.2.6
 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: 9.2.4
+version: 9.2.6
 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: 9.2.4
+version: 9.2.6
 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/jobs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-jobs
-version: 9.2.4
+version: 9.2.6
 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/bank-recon.md

@@ -15,8 +15,8 @@
 ### Platform tools: execute reconciliation (NOT idempotent; see error table)
 **Match to EXISTING (preferred, no duplicates):**
 - **`reconcile_with_payments(bankStatementEntryResourceId, businessTransactionPayments: [{cashflowTransactionResourceId, transactionAmount}], matchedPayments?, matchedBatchPayments?, adjustment?)`**: **the primary match path.** Match a bank entry to an EXISTING open bill/invoice/payment; creates the payment AND reconciles in one call (no `pay_bill`/`pay_invoice` first). FX auto-resolved server-side; pass no rate. Sync.
-- **`reconcile_magic_match(bankAccountResourceId, entries: [{workflowType:'MAGIC_MATCH', bankStatementEntryResourceId, matchedBusinessTransactions}])`**: bulk-accept MAGIC_MATCH suggestions (max 500). Returns `{reconciled[], failed[]}`; a non-empty `failed[]` is a partial success; loop on it.
-- **`reconcile_learned_prediction(bankStatementEntryResourceId, learnedPredictionResourceId, predictedPayload, predictedPayloadSchemaVersion, retryToken?)`**: accept an ML learned-prediction (payload passed verbatim from a `MAGIC_RECONCILE_WITH_CASH_IN_OUT` suggestion).
+- **`reconcile_magic_match(bankAccountResourceId, entries: [{workflowType:'MAGIC_MATCH', bankStatementEntryResourceId, matchedBusinessTransactions, recommendationId?} | {workflowType:'MAGIC_RECONCILE_WITH_CASH_IN_OUT', bankStatementEntryResourceId, learnedPredictionResourceId, predictedPayload, predictedPayloadSchemaVersion, retryToken?, recommendationId?}])`**: bulk-accept suggestions (max 500); learned-prediction fields pass through verbatim from the suggestion. Returns `{reconciled[], failed[]}` (either may be absent or empty); a non-empty `failed[]` is a partial success; a failed entry may still have posted, so re-read its line before any retry.
+- **`reconcile_learned_prediction(bankStatementEntryResourceId, learnedPredictionResourceId, predictedPayload, predictedPayloadSchemaVersion, retryToken?, recommendationId?)`**: accept an ML learned-prediction (payload passed verbatim from a `MAGIC_RECONCILE_WITH_CASH_IN_OUT` suggestion).
 - **`apply_bank_rule(actionShortcutResourceId, businessTransactionResourceIds)`**: rule-driven recon (async; returns jobId).
 - **`quick_reconcile(bankAccountResourceId, journalsForReconciliation)`**: bulk async (max 500); returns jobId.
 
@@ -122,7 +122,7 @@ Returns matches with confidence scores: `exact` (Phase 1 hash), `fuzzy-high` (Ph
 
 Call `search_bank_records` (status `UNRECONCILED`) to get the entry ids, then `view_auto_reconciliation` with `bankStatementEntryResourceIds`. It returns execution-ready `suggestions[]`. On high-volume accounts the engine can 500 (OOM) or not answer in time, and the tool returns `{degraded:true}`; recover via the `clio jobs bank-recon match` cascade matcher (Step 4, above), which doesn't hit this endpoint. Walk the suggestions:
 
-- **`autoCommitEligible === true`** (high confidence, has an `execute` plan, under any amount cap, and for a learned prediction an `ACTIVE` `lifecycleStatus`) → **auto-commit**: call the suggestion's `recommendedTool` with its `execute` args. For many eligible matches, prefer ONE `reconcile_magic_match` call (server idempotency-keyed) over looping `reconcile_with_payments` (non-idempotent).
+- **`autoCommitEligible === true`** (high confidence, has an `execute` plan, under any amount cap, and for a learned prediction an `ACTIVE` `lifecycleStatus`) → **auto-commit**: call the suggestion's `recommendedTool` with its `execute` args. For many eligible matches, prefer ONE `reconcile_magic_match` call over looping `reconcile_with_payments`: one write instead of many. Neither is idempotent for a `MAGIC_MATCH` entry, so the safety rule below applies to both.
 - **everything else** (medium/low tier, `recommendedTool` undefined, CREATE-NEW, amount over threshold, or a learned prediction that is not `ACTIVE`: `PROBATIONARY` is still learning, even at confidence 1.0) → **checkpoint**: surface to the user for confirmation, with the suggestion's `checkpointReason` (and, for a learned prediction or bank rule, the account, contact and tax it would post: `proposedPosting`). **The amount threshold is a HARD VETO over confidence**: a high-confidence but large match still checkpoints (pass `autoCommitMaxAmount` to enforce in code).
 - **`{degraded:true}`** (500 or no answer in time) → fall back to the `clio jobs bank-recon match` cascade (Step 4, above).
 
@@ -244,8 +244,8 @@ Per account: `bookBalance == bankStatementBalance ± documentedTimingDifference`
 | `view_auto_reconciliation` | 404 → returns `{notSupported:true}` | Endpoint not enabled for the org's plan tier. Use cascade matcher only. |
 | `quick_reconcile` | PARTIAL_SUCCESS jobId | Async result. Poll `search_background_jobs(filter: {resourceId: {eq: <jobId>}})` until terminal. Read `data[0].errorDetails[]` for per-row failures; loop back to step 4 for the failed rows. |
 | `quick_reconcile` / `reconcile_*` | (any), NOT idempotent (rule 125) | On 500 / network error, do NOT retry. Confirm reconciled state via `view_auto_reconciliation` OR `search_bank_records(status: 'RECONCILED')` first. |
-| `reconcile_with_payments` | (any 5xx/network), NOT idempotent, **no client key** | A blind retry **double-creates a payment**. ALWAYS re-check `search_bank_records(status:'RECONCILED')` for the entry before retrying. (magic_match is entry-level idempotency-keyed; learned_prediction takes a `retryToken`.) |
-| `reconcile_magic_match` | 200 with non-empty `failed[]` | PARTIAL success: `reconciled[]` succeeded, `failed[]` carries per-entry `errorCode`. Surface failures + loop only on the failed entries. **All-fail** (empty `reconciled[]`) = hard stop, surface. A re-submit returns already-done entries in `reconciled[]` (not `failed[]`); don't treat them as new failures. |
+| `reconcile_with_payments` | (any 5xx/network), NOT idempotent, **no client key** | A blind retry **double-creates a payment**. ALWAYS re-check `search_bank_records(status:'RECONCILED')` for the entry before retrying. (`reconcile_magic_match` is NOT idempotent for `MAGIC_MATCH` entries either; a learned-prediction accept, single or in a batch, is keyed on entry + prediction + `retryToken`.) |
+| `reconcile_magic_match` | 200 with non-empty `failed[]` | PARTIAL success: `reconciled[]` succeeded, `failed[]` carries per-entry `errorCode`. Surface failures. A failed entry may still have posted, so re-read each line's state before retrying it. **All-fail** = a 422 error, not a 200; entries may still have posted: hard stop, surface, re-read the lines. Never resubmit a `MAGIC_MATCH` entry whose outcome you did not see: re-read its line state first. |
 | `reconcile_learned_prediction` | error (stale/invalid `predictedPayload`) | Do NOT retry the same opaque payload. Fall back to `reconcile_with_payments` or manual match. `retryToken` forces a fresh journal on an intentional edit-retry; omit for idempotent replay. |
 | `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. |

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

@@ -1,6 +1,6 @@
 ---
 name: jaz-recipes
-version: 9.2.4
+version: 9.2.6
 description: >-
   Use this skill when modeling complex multi-step accounting transactions:
   anything that spans multiple periods, involves changing amounts, or requires