jaz-clio 5.6.7 → 5.6.9

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 5.6.7
+version: 5.6.9
 description: >-
   Use this skill whenever you call, debug, or review code that touches the Jaz
   REST API. Covers field names, response shapes, 141 production gotchas, error
@@ -489,6 +489,10 @@ Bills, invoices, and credit notes share identical mandatory field specs. Adding
 
 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.
 
+### Error Recovery
+
+158. **Tool error envelopes may carry a structured `repair` suggestion (W1.3).** When a `create_*` / `update_*` / `get_*` tool fails with a high-confidence pattern (404 not found, 422 missing FK, duplicate reference, tax-profile direction mismatch), the response is enriched with `repair: { tool, arguments, reason }`. The `tool` field is ALWAYS read-only AND verified to exist in the registry. Consumption pattern: if `repair` is present, call `execute_tool(repair.tool, repair.arguments)` directly to recover; do NOT retry the original write tool until the repair surfaces the correct resourceId/reference. Full envelope shape, pattern list, and worked example in `references/errors.md` (Repair Suggestions section). Purely additive — no match → no `repair`, fall back to free-text `hint`. Infinite-loop protection comes from the agent-loop repetition guard (same tool+input retried 3× is blocked).
+
 ## Supporting Files
 
 For detailed reference, read these files in this skill directory:

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

@@ -858,3 +858,57 @@ Journals support a top-level `currency` object to create entries in a foreign cu
 ---
 
 *Last updated: 2026-03-13 — Added: Nano-classifier errors (classes field, double-wrapped GET), payment record errors (cashflow vs payment IDs), sub-resource raw array errors. Previous: Cash entry path migration, Quick Fix errors.*
+
+---
+
+## Repair Suggestions (W1.3)
+
+When a Jaz tool call fails, the MCP `execute_tool` response (and the daemon-side executor return) may now carry a structured `repair` block alongside the existing `error` / `hint` fields. The block is built by the motherboard registry (`src/core/registry/repair-hints.ts`); the API server is unchanged.
+
+### Shape
+
+```json
+{
+  "error": "lineItems[0].accountResourceId is required if [saveAsDraft] is false",
+  "status": 422,
+  "endpoint": "/api/v1/invoices",
+  "hint": "Validation error — check field values against the tool description.",
+  "repair": {
+    "tool": "search_accounts",
+    "arguments": {},
+    "reason": "Line item missing accountResourceId. Search for the right GL account first (e.g. by name or accountType), then retry with the resourceId on each line item."
+  }
+}
+```
+
+The `repair` field is OMITTED entirely when no high-confidence pattern matches. The agent then falls back to the free-text `hint` field (existing behavior).
+
+### Safety invariants
+
+- `repair.tool` always starts with a read-only prefix: `search_*`, `list_*`, `get_*`, `view_*`, `describe_*`. Never a write or destructive tool.
+- `repair.tool` is verified to exist in the registry before the suggestion ships. Bogus names (typos, naive plurals) are silently dropped.
+- Recursion bounded by the existing agent-loop repetition guard (`MAX_REPEAT = 2`): same tool+input retried 3× is blocked.
+
+### Patterns matched in v1
+
+| Trigger | Suggested tool | Used when input contains |
+|---|---|---|
+| `status === 404` or `not found` | `search_contacts` | `contactResourceId` (string) AND error mentions "contact" |
+| `status === 404` on `get_*` / `update_*` / `delete_*` / `finalize_*` / `pay_*` | `search_<entity>s` (only if exists in registry) | any `resourceId` |
+| `status === 422` mentioning `accountResourceId` | `search_accounts` | (no input requirement) |
+| `status === 422` + `duplicate` / `already exists` on `create_*` | `search_<entity>s` filtered by `reference` | `reference` (string) |
+| `status === 422` + tax-profile direction mismatch | `search_tax_profiles` | (no input requirement) |
+
+Non-API errors (validation, schema, network) do NOT carry a repair suggestion — pattern-matching free-text is too brittle. The existing `hint` field covers those cases.
+
+### Recommended agent consumption
+
+```
+1. Receive tool error result with `repair` field present.
+2. Call execute_tool(repair.tool, repair.arguments).
+3. Use the search result to construct a corrected payload.
+4. Retry the original tool ONCE with the corrected payload.
+5. If it still fails, do NOT loop — surface the error to the user.
+```
+
+Repair suggestions are advisory, not authoritative. The agent may ignore them when context (recent tool calls, user intent) suggests a different approach is better.

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 5.6.7
+version: 5.6.9
 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/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 5.6.7
+version: 5.6.9
 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-pseudo-sql/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-pseudo-sql
-version: 5.6.7
+version: 5.6.9
 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.6.7
+version: 5.6.9
 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/practice/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-practice
-version: 5.6.7
+version: 5.6.9
 description: >-
   Use this skill whenever an accounting practitioner is doing client work in
   Jaz — closing the books, filing GST, year-end statutory, onboarding a new

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

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