jaz-clio 5.30.2 → 5.31.0

package/README.md

@@ -3,13 +3,13 @@
 <p align="center">
   <a href="https://www.npmjs.com/package/jaz-clio"><img src="https://img.shields.io/npm/v/jaz-clio?style=for-the-badge&logo=npm" alt="npm"></a>
   <a href="https://www.npmjs.com/package/jaz-clio"><img src="https://img.shields.io/npm/dm/jaz-clio?style=for-the-badge&label=downloads" alt="npm downloads"></a>
-  <img src="https://img.shields.io/badge/tools-357-blue?style=for-the-badge" alt="357 tools">
+  <img src="https://img.shields.io/badge/tools-358-blue?style=for-the-badge" alt="358 tools">
   <a href="https://github.com/teamtinvio/jaz-ai/blob/main/LICENSE"><img src="https://img.shields.io/github/license/teamtinvio/jaz-ai?style=for-the-badge&color=green" alt="License"></a>
 </p>
 
 <p align="center"><b>Jaz accounting on the command line, and inside any AI agent.</b></p>
 
-357 tools · 66 command groups · 7 skills · 13 calculators · 12 close playbooks · 158 field-tested API rules.
+358 tools · 66 command groups · 7 skills · 13 calculators · 12 close playbooks · 158 field-tested API rules.
 
 ```bash
 npm install -g jaz-clio
@@ -54,7 +54,7 @@ clio invoices search --query 'status:unpaid AND $500+' # structured per-entity s
 
 ## MCP server
 
-357 tools for any AI agent that speaks MCP. Runs locally: no cloud, no ports.
+358 tools for any AI agent that speaks MCP. Runs locally: no cloud, no ports.
 
 > **No install at all?** Claude.ai, ChatGPT, Cowork, and Microsoft Copilot Studio can use Jaz through the hosted connector. Add `https://mcp.jaz.ai/mcp` as a custom connector and sign in with OAuth, no key. The local setup below is for terminal use, scripting, and editors that run MCP servers as local processes.
 

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 5.30.2
+version: 5.31.0
 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
@@ -399,14 +399,14 @@ Bills, invoices, and credit notes share identical mandatory field specs. Adding
 
 ### Reconciliation actions (write-side)
 
-123. **11 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*):
+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[]}`.
+    - **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.
 
 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.
 
-125. **The 6 sync recon endpoints are NOT idempotent** — calling twice on the same `bankStatementEntryResourceId` creates duplicate journals. Before retrying, confirm the entry's reconciled state via `view_auto_reconciliation` or `search_bank_records` filtered by `status`. Concurrent calls on the same entry race — last-write-wins.
+125. **The 6 sync recon endpoints are NOT idempotent** — calling twice on the same `bankStatementEntryResourceId` creates duplicate journals. Before retrying, confirm the entry's reconciled state via `view_auto_reconciliation` or `search_bank_records` filtered by `status`. Concurrent calls on the same entry race — last-write-wins. **`undo_reconciliations` is the reverse and behaves differently**: it UNLINKS but does NOT delete the record that was matched, so undoing any of the 6 CREATE endpoints (`direct_cash_entry`, `cash_journal`, `manual_journal`, `cash_transfer`, `invoice_receipt`, `bill_receipt`) leaves that record on the books against an unmatched bank line — a discrepancy the undo introduced. Delete it via `linkedRecords[]` (captured BEFORE the unlink, since the unlink is what makes it unfindable by bank entry): cash in/out/transfer by `parentEntityResourceId`, everything else by `businessTransactionResourceId`. Never just re-reconcile after undoing — that creates a SECOND record. Undo never double-applies (a repeat returns per-entry `FAILED`/`INVALID_BANK_STATEMENT_ENTRY_STATUS`), and unresolved ids are OMITTED from the response, so compare returned ids against what you sent.
 
 126. **Sync recon → AR/AP via `invoice_receipt` / `bill_receipt`** — these endpoints CREATE a transaction (invoice for AR, bill for AP) and immediately reconcile it to the bank entry. The two endpoints stay separate (not unified) because the invoice side carries `billTo` / `billFrom` that bills don't have. Cash-in vs cash-out, by contrast, IS unified into `reconcile_direct_cash_entry` — direction is encoded in the bank entry sign.
 

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

@@ -2380,7 +2380,17 @@ Batch-record judgment entries (1-100 per call). Per-entry independent: acks come
 { "data": { "records": [{ "resourceId": "...", "replayed": false, "duplicateCount": 0 }] } }
 ```
 
-`kind`: CLASSIFICATION, MATCH, SCOPE, ASSUMPTION, RISK, METHOD, RECOVERY, DEVIATION, NOTE (the neutral fallback for a judgment logged without a declared type; a missing or blank `kind` defaults to NOTE and is flagged, not rejected). `tier`: LOW, MEDIUM, HIGH, CRITICAL. `refs` entries are OBJECTS: the string grammar `TYPE:resourceId[#field][:RELATION]` travels in `raw` (an unparseable ref is stored with `parsed: false`, never bounced). Optional fields: `ruledOut`, `frame`, `confidence`, `citedRule`, `workflowLabel`, `agentLabel`. `idempotencyKey` makes retries safe: a replay returns the existing entry with `replayed: true`.
+`kind`: CLASSIFICATION, MATCH, SCOPE, ASSUMPTION, RISK, METHOD, RECOVERY, DEVIATION, NOTE (the neutral fallback for a judgment logged without a declared type; a missing or blank `kind` defaults to NOTE and is flagged, not rejected — never declare NOTE deliberately). `tier`: LOW, MEDIUM, HIGH, CRITICAL. `refs` entries are OBJECTS: the string grammar `TYPE:resourceId[#field][:RELATION]` travels in `raw` (an unparseable ref is stored with `parsed: false`, never bounced). Optional fields: `ruledOut`, `frame`, `confidence`, `citedRule`, `workflowLabel`, `agentLabel`. `idempotencyKey` makes retries safe: a replay returns the existing entry with `replayed: true`.
+
+**Jot doctrine (fill fields consistently — the server re-scores tier from kind + refs, and declared-vs-computed agreement is a review signal):**
+
+- **When**: log a judgment when you chose among real alternatives and a write followed, or when you deliberately decided NOT to write. Skip mechanical actions. Jot AFTER the write succeeds; carry the written record's resourceId in `refs`.
+- **Tier anchors** (mirror the server's rules): CRITICAL = money leaves (`PAY` ref), data destroyed (`DELETE` ref), external send or period lock (`FINALIZE` ref), or a RECOVERY that still drove a write. HIGH = the withheld write (RECOVERY with no mutation ref — it pins via withheld-write, not tier), or RISK/MATCH backed by a write. LOW = a DEVIATION detached from any write. MEDIUM = everything else.
+- **Kind boundaries**: where a value LANDS (account, tax code) = CLASSIFICATION; how it is COMPUTED = METHOD. Filling one missing fact = ASSUMPTION; drawing a set boundary = SCOPE (carry `frame`). A decided omission after failure = RECOVERY, never DEVIATION.
+- **Refs relation** is load-bearing: state what the write did (CREATE/UPDATE/DELETE/FINALIZE/PAY/RECONCILE/TRIGGER); SUBJECT only for no-write entries. PAY/DELETE/FINALIZE pin the jot regardless of declared tier.
+- **confidence**: HIGH = clear rule or precedent; MEDIUM = pattern inference; LOW = a guess a reviewer should check.
+- **workflowLabel**: use a canonical job name when one fits (`month-end-close`, `quarter-end-close`, `year-end-close`, `bank-recon`, `gst-vat-filing`, `payment-run`, `credit-control`, `supplier-recon`, `audit-prep`, `fa-review`, `document-collection`, `statutory-filing`), else short kebab-case.
+- **Style**: tight, factual, plain punctuation; one line per field; never repeat content across fields; a call without a `why` is half a record. `duplicateCount > 0` on the ack = already recorded — do not re-jot; search first on repeated workflows.
 
 ### POST /api/v1/jots/search
 

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 5.30.2
+version: 5.31.0
 description: >-
   Use this skill when running Clio CLI commands, building shell scripts with
   Clio, debugging auth issues, understanding --json output, paginating results,
@@ -8,7 +8,7 @@ description: >-
   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 357 tools, including employee-expense claims.
+  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.
 ---
@@ -17,7 +17,7 @@ compatibility: Requires Node.js >= 18.0.0. Install via npm install -g jaz-clio.
 
 > **Audience note:** for power users and CI/automation. Load this skill only when you're scripting from a terminal, building shell pipelines, or debugging from `clio --json` output. For day-to-day accounting inside Claude Desktop / Cowork, the MCP tools cover the common flows without dropping to the CLI.
 
-You are working with **Clio** (`jaz-clio`) — the CLI for the Jaz accounting platform. 66 command groups, 13 calculators, 12 job blueprints, 357 tools. Also fully compatible with Juan Accounting (same API, same endpoints).
+You are working with **Clio** (`jaz-clio`) — the CLI for the Jaz accounting platform. 66 command groups, 13 calculators, 12 job blueprints, 358 tools. Also fully compatible with Juan Accounting (same API, same endpoints).
 
 ## When to Use This Skill
 
@@ -158,7 +158,7 @@ Rules:
 | `--all` | List/search commands | Auto-paginate all pages |
 | `--max-rows <n>` | With `--all` | Cap total rows (default 10,000) |
 | `--finalize` | Create commands | Approve immediately (skip draft) |
-| `--jot <text>` | Write commands (create/update/delete/pay/finalize/…) | Log the judgment behind this write in one line, inline (piggybacks a judgment-journal entry after the write succeeds; optional leading kind, e.g. `"MATCH: …"`). Without it, a successful write prints a one-line reminder to stderr — silence with `JAZ_JOTS_NUDGES=0`. |
+| `--jot <text>` | Write commands (create/update/delete/pay/finalize/…) | Log the judgment behind this write in one line, inline (piggybacks a judgment-journal entry after the write succeeds; optional leading kind, e.g. `"MATCH: …"`). Quick LOW/MEDIUM one-liners only — for HIGH or CRITICAL calls, or when the why matters, use `clio jots create` (doctrine in its `--help`: tier anchors, kind boundaries, style). Without it, a successful write prints a one-line reminder to stderr — silence with `JAZ_JOTS_NUDGES=0`. |
 | `--date <YYYY-MM-DD>` | Create/update commands | Transaction date |
 | `--due <YYYY-MM-DD>` | Create/update commands | Due date |
 | `--query <expression>` | Search commands (14 entities) | Jaz search expression (see below) |

package/assets/skills/conversion/SKILL.md

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

@@ -1,6 +1,6 @@
 ---
 name: jaz-jobs
-version: 5.30.2
+version: 5.31.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/transaction-recipes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-recipes
-version: 5.30.2
+version: 5.31.0
 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,7 +6,7 @@ Source of truth lives in the installed skills (`.claude/skills/jaz-*/SKILL.md` o
 
 ## Discovery
 
-The Jaz MCP server exposes 357 tools across 42 namespaces via 3 meta-tools. **Use the meta-tool flow — never enumerate tools blindly.**
+The Jaz MCP server exposes 358 tools across 42 namespaces via 3 meta-tools. **Use the meta-tool flow — never enumerate tools blindly.**
 
 1. `search_tools(query)` → top-N tool names + namespaces.
 2. `describe_tools(names)` → full parameter schemas.