jaz-clio 5.31.0 → 5.32.1

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 5.31.0
+version: 5.32.1
 description: >-
   Use this skill whenever you call, debug, or review code that touches the Jaz
   REST API. Covers field names, response shapes, 158 production gotchas, error
@@ -539,7 +539,7 @@ When the user wants to OPEN, SEE, or SHARE something in the Jaz dashboard ("open
     - **`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_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.** 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). **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. Pass `includeRaw:true` for the unmapped payload. On 500 (high-volume OOM) it returns `{degraded:true}` — scope by period or 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 — merge `bankAccountResourceId` for `reconcile_magic_match`), `confidenceTier` (high/medium/low, code-derived), and `autoCommitEligible` (true ⇒ high confidence + executable plan + under any `autoCommitMaxAmount` cap). **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. Pass `includeRaw:true` for the unmapped payload. Cost tracks the entries you pass — batch large backlogs. On 500 it returns `{degraded:true}` — use the `clio jobs bank-recon match` cascade. NOT idempotent applies to every commit — see Rules 125 + 158.
 
 ## See Also
 

package/assets/skills/cli/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: jaz-cli
-version: 5.31.0
+version: 5.32.1
 description: >-
   Use this skill when running Clio CLI commands, building shell scripts with
   Clio, debugging auth issues, understanding --json output, paginating results,
-  or chaining multi-step accounting workflows from the terminal. Covers all 65
-  command groups, auth precedence, output formats, entity resolution, and common
-  workflow patterns. Also use when the user asks how to use clio, what commands
-  are available, or how to automate accounting tasks from the command line.
-  Covers all 66 command groups and 358 tools, including employee-expense claims.
+  or chaining multi-step accounting workflows from the terminal. Covers auth
+  precedence, output formats, entity resolution, and common workflow patterns.
+  Also use when the user asks how to use clio, what commands are available, or
+  how to automate accounting tasks from the command line. Covers all
+  66 command groups and 358 tools, including employee-expense claims.
 license: MIT
 compatibility: Requires Node.js >= 18.0.0. Install via npm install -g jaz-clio.
 ---
@@ -34,7 +34,7 @@ You are working with **Clio** (`jaz-clio`) — the CLI for the Jaz accounting pl
 | Need | Skill |
 |------|-------|
 | CLI command syntax, flags, output | **jaz-cli** (this skill) |
-| API field names, error codes, 141 gotchas | **jaz-api** |
+| API field names, error codes, 158 API rules | **jaz-api** |
 | IFRS transaction recipes (depreciation, leases, loans) | **jaz-recipes** |
 | Month-end close, bank recon, GST filing workflows | **jaz-jobs** |
 | Migration from Xero/QuickBooks/Sage | **jaz-conversion** |
@@ -377,7 +377,7 @@ See `references/common-workflows.md` for end-to-end multi-command patterns.
 4. **--offset is page number (0-indexed), not row count.**
 5. **JAZ_API_KEY env overrides --org.** Unset to use profiles.
 
-See [references/agent-gotchas.md](./references/agent-gotchas.md) for the full list of 15 gotchas. See [references/output-shapes.md](./references/output-shapes.md) for `--json` output structures. See [references/error-recovery.md](./references/error-recovery.md) for 30+ error patterns with fixes.
+See [references/agent-gotchas.md](./references/agent-gotchas.md) for the full list of 19 critical gotchas. See [references/output-shapes.md](./references/output-shapes.md) for `--json` output structures. See [references/error-recovery.md](./references/error-recovery.md) for 30+ error patterns with fixes.
 
 ## See Also
 

package/assets/skills/cli/references/command-catalog.md

@@ -1,6 +1,6 @@
 # Clio Command Catalog
 
-Complete reference for all 65 command groups. Organized by domain.
+Complete reference for all 66 command groups. Organized by domain.
 
 ---
 
@@ -300,7 +300,7 @@ EmploymentType: `FULL_TIME` · `PART_TIME` · `CONTRACTOR` · `INTERN` · `TEMPO
 | `records <accountId>` | `--from`, `--to`, `--status`, `--description`, `--limit`, `--offset`, `--all` |
 | `add-records <accountId>` | `--input` (JSON array of bank records) |
 | `import <accountId> <file>` | Supports CSV, OFX, XLS, XLSX |
-| `auto-recon <accountId>` | Trigger auto-reconciliation |
+| `auto-recon` | READ-ONLY reconciliation suggestions. `--type <workflow>` and `--entries <id,...>` are both REQUIRED (per-entry; no account-wide mode). `--account` optional. |
 
 ### `clio bank-rules` — Bank reconciliation rules
 | Subcommand | Key flags |
@@ -587,7 +587,7 @@ Valid entity types: INVOICE, BILL, CUSTOMER_CREDIT_NOTE, SUPPLIER_CREDIT_NOTE, S
 Universal async tracker — any operation returning a jobId (contacts bulk-upsert, items bulk-upsert, bank import, magic processing) can be polled here.
 
 ### `clio mcp` — MCP stdio server
-Starts an MCP server for Claude Code / AI tool integration. Exposes all 247 tools.
+Starts an MCP server for Claude Code / AI tool integration. Exposes all 358 operations.
 
 ### `clio serve` — HTTP daemon
 Starts the HTTP daemon for ChatKit and email channel integrations.

package/assets/skills/cli/references/common-workflows.md

@@ -50,8 +50,9 @@ BANK_ID="<bank-account-resourceId>"
 # Import statement file (CSV, OFX, XLS, or XLSX)
 clio bank import "$BANK_ID" ./march-2026-statement.csv
 
-# Trigger auto-reconciliation
-clio bank auto-recon "$BANK_ID"
+# Reconciliation suggestions (READ-ONLY, per-entry — --type and --entries are required)
+ENTRY_IDS=$(clio bank records "$BANK_ID" --status UNRECONCILED --limit 20 --json | jq -r '[.data[].resourceId] | join(",")')
+clio bank auto-recon --account "$BANK_ID" --type MAGIC_MATCH --entries "$ENTRY_IDS"
 
 # Review unreconciled records
 clio bank records "$BANK_ID" --status UNRECONCILED --from 2026-03-01 --to 2026-03-31 --json

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 5.31.0
+version: 5.32.1
 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.31.0
+version: 5.32.1
 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.31.0
+version: 5.32.1
 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: 5.31.0
+version: 5.32.1
 description: >-
   Use this skill for recurring accounting workflows — month/quarter/year-end
   close, bank reconciliation, GST/VAT filing, payment runs, credit control,
@@ -55,7 +55,7 @@ Period-close jobs build on each other. Quarter = month + extras. Year = quarter
 
 | Job | CLI (local convenience) | Description |
 |-----|-------------------------|-------------|
-| **Bank Recon** | `clio jobs bank-recon` | Clear unreconciled items: match, categorize, resolve. **Match to EXISTING open bills/invoices/payments (`reconcile_with_payments`) is the primary path — create-new only when nothing matches.** Drive end-to-end via the `view_auto_reconciliation` decision gate (auto-commit high-confidence, checkpoint the rest — see `references/bank-recon.md` Step 4a). Cascade matcher: `clio jobs bank-recon match`. |
+| **Bank Recon** | `clio jobs bank-recon` | Clear unreconciled items: match, categorize, resolve. **Match to EXISTING open bills/invoices/payments (`reconcile_with_payments`) is the primary path — create-new only when nothing matches.** Drive end-to-end via the `view_auto_reconciliation` decision gate — per-entry, so fetch ids with `search_bank_records` first (auto-commit high-confidence, checkpoint the rest — see `references/bank-recon.md` Step 4a). Cascade matcher: `clio jobs bank-recon match`. |
 | **Document Collection** | `clio jobs document-collection` | Scan and classify client documents from local directories and cloud links (Dropbox, Drive, OneDrive). Outputs file paths for upload via Jaz Magic. Ingest helper: `clio jobs document-collection ingest`. |
 | **GST/VAT Filing** | `clio jobs gst-vat --period YYYY-QN` | Tax ledger review, discrepancy check, filing summary. |
 | **Payment Run** | `clio jobs payment-run` | Select outstanding bills by due date, process payments. |

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

@@ -9,7 +9,7 @@
 - **`search_accounts(filter: {accountType: {eq: 'Bank Accounts'}})`** — step 1 alternative: same data via standard CoA-search envelope if downstream wants pagination.
 - **`search_bank_records(accountResourceId: <id>, status: 'UNRECONCILED', valueDateRange: {from, to}, limit: 200, sort: 'valueDate:asc')`** — step 2: per-account work queue.
 - **`search_bank_records(accountResourceId: <id>, status: 'POSSIBLE_DUPLICATE')`** — step 3: handle dups FIRST or you'll double-create reconciling them.
-- **`view_auto_reconciliation(bankAccountResourceId: <id>, recommendationType: 'MAGIC_MATCH' | 'MAGIC_RECONCILE_WITH_CASH_TRANSFER' | 'MAGIC_RECONCILE_WITH_BANK_RULE' | 'MAGIC_QUICK_RECONCILE' | 'MAGIC_RECONCILE_WITH_CASH_IN_OUT', autoCommitMaxAmount?: <number>)`** — step 4: READ-ONLY auto-match suggestions. Returns **execution-ready `suggestions[]`** — each carries `recommendedTool`, `execute` (ready-to-pass args), `confidenceTier`, and `autoCommitEligible`. This is the entry point for the auto-match decision gate (step 4a). `MAGIC_RECONCILE_WITH_CASH_IN_OUT` returns Learned-Predictions. Does NOT write. NOTE: 500 quirk on high-volume accounts → degrades to `{degraded:true}`; scope by period or fall back to the cascade matcher (see error table).
+- **`view_auto_reconciliation(bankStatementEntryResourceIds: [<id>, ...], recommendationType: 'MAGIC_MATCH' | 'MAGIC_RECONCILE_WITH_CASH_TRANSFER' | 'MAGIC_RECONCILE_WITH_BANK_RULE' | 'MAGIC_QUICK_RECONCILE' | 'MAGIC_RECONCILE_WITH_CASH_IN_OUT', bankAccountResourceId?: <id>, autoCommitMaxAmount?: <number>)`** — step 4: READ-ONLY auto-match suggestions. **`bankStatementEntryResourceIds` is REQUIRED — this endpoint is per-entry and there is no account-wide mode.** Source the ids from `search_bank_records` with status `UNRECONCILED`. Pass `bankAccountResourceId` too: it is merged into each suggestion's `execute` args for `reconcile_magic_match`. Returns **execution-ready `suggestions[]`** — each carries `recommendedTool`, `execute` (ready-to-pass args), `confidenceTier`, and `autoCommitEligible`. This is the entry point for the auto-match decision gate (step 4a). `MAGIC_RECONCILE_WITH_CASH_IN_OUT` returns Learned-Predictions. Does NOT write. NOTE: cost tracks the entries you pass — batch large backlogs. On a 500 it degrades to `{degraded:true}`; fall back to the cascade matcher (see error table).
 - **`search_cashflow_transactions(filter: {organizationAccountResourceId: <bank-id>, totalAmount: {eq: <amt>}, valueDate: {between: [<-3d>, <+3d>]}})`** — step 5 manual match: search book-side transactions for the same amount within ±3 day window.
 
 ### Platform tools — execute reconciliation (NOT idempotent — see error table)
@@ -119,7 +119,7 @@ Returns matches with confidence scores: `exact` (Phase 1 hash), `fuzzy-high` (Ph
 
 ## Step 4a — Auto-match decision gate (the end-to-end driver)
 
-Call `view_auto_reconciliation`. It returns execution-ready `suggestions[]`. On high-volume accounts the engine can 500 (OOM) 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:
+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) 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) → **auto-commit**: call the suggestion's `recommendedTool` with its `execute` args. For many high-confidence matches, prefer ONE `reconcile_magic_match` call (server idempotency-keyed) over looping `reconcile_with_payments` (non-idempotent).
 - **everything else** (medium/low tier, `recommendedTool` undefined, CREATE-NEW, or amount over threshold) → **checkpoint**: surface to the user for confirmation. **The amount threshold is a HARD VETO over confidence** — a high-confidence but large match still checkpoints (pass `autoCommitMaxAmount` to enforce in code).

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

@@ -20,7 +20,7 @@
 - **`plan_recipe(recipe: 'ecl', ...)`** — step 13: top-up bad-debt provision based on `generate_aged_ar` buckets.
 
 ### Platform tools — reconciliation execution
-- **`view_auto_reconciliation(bankAccountResourceId: <id>)`** — step 3: READ-ONLY suggestions (does NOT write).
+- **`view_auto_reconciliation(bankStatementEntryResourceIds: [<id>, ...])`** — step 3: READ-ONLY suggestions (does NOT write). Per-entry only; source ids from `search_bank_records` (status `UNRECONCILED`).
 - **`apply_bank_rule(...)`** — step 3: rule-driven recon.
 - **`quick_reconcile(...)` / `reconcile_direct_cash_entry(...)` / `reconcile_cash_journal(...)` / `reconcile_manual_journal(...)` / `reconcile_cash_transfer(...)` / `reconcile_invoice_receipt(...)` / `reconcile_bill_receipt(...)`** — step 3: per matched pair from the cascade.
 
@@ -76,7 +76,7 @@ For each bank account:
 1. If you don't already have the account's resourceId: `list_bank_accounts()`, match by `name + currency`, confirm with the user.
 2. `search_bank_records(accountResourceId: <bank account resourceId>, status: 'UNRECONCILED', valueDateRange: {from: '2025-01-01', to: '2025-01-31'}, limit: 200, sort: 'valueDate:asc')`.
 3. If results: drive the 5-phase cascade matcher (Step 4 in `bank-recon.md`; local CLI: `clio jobs bank-recon match --input <records> --tolerance 0.01 --date-window 14 --json`). For each match, invoke the matching `reconcile_*` tool.
-4. `view_auto_reconciliation(bankAccountResourceId: <id>, recommendationType: 'MAGIC_MATCH')` — READ-ONLY suggestions for residuals; commit via `quick_reconcile` / `apply_bank_rule` / per-entry `reconcile_*`.
+4. `view_auto_reconciliation(bankStatementEntryResourceIds: [<id>, ...], recommendationType: 'MAGIC_MATCH')` — READ-ONLY suggestions for residuals (per-entry; get ids from `search_bank_records`, status `UNRECONCILED`); commit via `quick_reconcile` / `apply_bank_rule` / per-entry `reconcile_*`.
 5. `generate_bank_recon_summary(period_end: '2025-01-31', accountResourceId: <id>)`. Confirm `unreconciledCount == 0` OR document the residuals for the period and surface to the user.
 
 Full detail in `bank-recon.md`. NOT idempotent — see error table.

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

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

package/assets/templates/platform-rules/jaz-agent-rules.md

@@ -6,13 +6,15 @@ Source of truth lives in the installed skills (`.claude/skills/jaz-*/SKILL.md` o
 
 ## Discovery
 
-The Jaz MCP server exposes 358 tools across 42 namespaces via 3 meta-tools. **Use the meta-tool flow — never enumerate tools blindly.**
+Jaz exposes **358 tools across 43 namespaces**. Your tool list shows **3, 43, or 358** entries depending on packaging — **never infer capability from its length.**
 
-1. `search_tools(query)` → top-N tool names + namespaces.
-2. `describe_tools(names)` → full parameter schemas.
-3. `execute_tool(name, args)` → run.
+- **3** — `search_tools(query)` → `describe_tools(names)` → `execute_tool(name, args)`. Empty query returns the namespace map.
+- **43** — namespace routers; call one with `{ operation, arguments }`. Its description lists its operations.
+- **358** — call operations directly by name.
 
-Offline tools (no API key needed): `plan_recipe`, `search_help_center`. The MCP server says `Offline.` at the start of those tools' descriptions.
+`describe_capabilities` returns the capability map on all three. **Call it before telling the user Jaz cannot do something.**
+
+No API key needed: `describe_capabilities`, `plan_recipe`, `search_help_center` (marked `Offline.`).
 
 ## API contract — the 6 rules that prevent 90% of 422s