jaz-clio 5.21.0 → 5.23.0

package/README.md

@@ -3,11 +3,11 @@
 <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-356-blue?style=for-the-badge" alt="356 tools">
+  <img src="https://img.shields.io/badge/tools-357-blue?style=for-the-badge" alt="357 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>
 
-356 tools. 65 command groups. 13 calculators. 12 job playbooks. 158 API rules. 16 IFRS recipes.
+357 tools. 66 command groups. 13 calculators. 12 job playbooks. 158 API rules. 16 IFRS recipes.
 
 ```bash
 npm install -g jaz-clio
@@ -18,8 +18,8 @@ Requires **Node.js 18+** ([nodejs.org](https://nodejs.org)). Also fully compatib
 ## Contents
 
 - [Three Ways In](#three-ways-in) · CLI, MCP, Skills
-- [CLI](#cli) · 65 command groups
-- [MCP Server](#mcp-server) · 356 tools for AI agents
+- [CLI](#cli) · 66 command groups
+- [MCP Server](#mcp-server) · 357 tools for AI agents
 - [Skills](#skills) · Teach any AI the Jaz API
 - [Setup](#setup) · Auth, multi-org, automation
 - [Semantic help-center search](#help-center-semantic-search-optional) · Optional OpenAI-backed retrieval
@@ -48,13 +48,13 @@ clio invoices search --query 'status:unpaid AND $500+'  # Structured per-entity
 clio invoices search --query 'status:unpaid' --view lean # Compact summary rows (id + key fields), then drill in with get
 ```
 
-65 command groups. 16 report types. 13 calculators. 12 job playbooks. Every command supports `--json`. Run `clio --help` for the full list.
+66 command groups. 16 report types. 13 calculators. 12 job playbooks. Every command supports `--json`. Run `clio --help` for the full list.
 
 ---
 
 ## MCP Server
 
-356 tools, available to any AI agent that speaks MCP. Runs locally: no cloud, no ports.
+357 tools, available to 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 via the **hosted connector**: add `https://mcp.jaz.ai/mcp` as a custom connector (Claude/ChatGPT) or MCP tool (Copilot Studio) and sign in (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.21.0
+version: 5.23.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
@@ -519,7 +519,7 @@ Supports `--json` for structured output. 186 articles across 20 sections. Automa
 
 ## Dashboard Deep Links (navigation tools)
 
-When the user wants to OPEN, SEE, or SHARE something in the Jaz dashboard ("open this invoice", "take me to the P&L"), hand them a real URL via two agent (MCP) tools — deliberately no CLI command: `find_dashboard_destinations` discovers the destination key (filter by `query`/`resource`/`kind`; keys are named by product area, not task wording — on zero matches retry broader: "billing", not "card"), and `get_dashboard_url` turns a key into `{ url, kind, label }`. Screens are dotted route paths (`reports.profit-and-loss`); record modals are `<resource>.modal.<type>` (`sales.modal.view-sale`). Record-specific modals (view/edit/duplicate one record) REQUIRE `resourceId` — the same Jaz resourceId from the search/get that found the record; screens and create/"new" modals take none (a resourceId on a screen is rejected). NEVER write a dashboard URL by hand and NEVER guess a destination key — routes are not guessable, and a wrong link is worse than no link; if `get_dashboard_url` errors, follow its hint (near-matches + discovery pointer) and say the link could not be built rather than improvising one. The org query param is appended automatically when the surface knows the acting org; API-key surfaces open in the user's current org on the app.jaz.ai host. Examples: "open invoice INV-042" → `search_invoices` → `get_dashboard_url("sales.modal.view-sale", resourceId)`; "take me to the P&L" → `get_dashboard_url("reports.profit-and-loss")`; "where do I manage users?" → `find_dashboard_destinations("user")` → `get_dashboard_url("settings.modal.user_management")`.
+When the user wants to OPEN, SEE, or SHARE something in the Jaz dashboard ("open this invoice", "take me to the P&L"), hand them a real URL via ONE agent (MCP) tool — deliberately no CLI command: `navigate`. Called with no `destination` it discovers destination keys (filter by `query`/`resource`/`kind`; keys are named by product area, not task wording — on zero matches retry broader: "billing", not "card"); called with a `destination` it turns the key into `{ url, kind, label }`. Screens are dotted route paths (`reports.profit-and-loss`); record modals are `<resource>.modal.<type>` (`sales.modal.view-sale`). Record-specific modals (view/edit/duplicate one record) REQUIRE `resourceId` — the same Jaz resourceId from the search/get that found the record; screens and create/"new" modals take none (a resourceId on a screen is rejected). NEVER write a dashboard URL by hand and NEVER guess a destination key — routes are not guessable, and a wrong link is worse than no link; if `navigate` errors, follow its hint (near-matches + discovery pointer) and say the link could not be built rather than improvising one. The org query param is appended automatically when the surface knows the acting org; API-key surfaces open in the user's current org on the app.jaz.ai host. Examples: "open invoice INV-042" → `search_invoices` → `navigate("sales.modal.view-sale", resourceId)`; "take me to the P&L" → `navigate("reports.profit-and-loss")`; "where do I manage users?" → `navigate(query: "user")` → `navigate("settings.modal.user_management")`. (The pre-merge tool names `find_dashboard_destinations` / `get_dashboard_url` still resolve as aliases.)
 
 ## Recommended Client Patterns
 

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

@@ -2355,4 +2355,53 @@ Note: `previewRows` keys are column **headers** (not paths). `filter` and `query
 
 ---
 
-*Last updated: 2026-04-09 — Added: Contacts bulk-upsert (22), Background Jobs search (23), Export Records (24). Previous: 2026-03-13 — Payment record CRUD, nano-classifier, scheduler GET/PUT/DELETE.*
+## 25. Jots (Judgment Journal)
+
+### POST /api/v1/jots
+
+Batch-record judgment entries (1-100 per call). Per-entry independent: acks come back in input order, and a bad entry never fails the batch, it acks with `error` + `errorCode` while siblings persist. Rate valve: 600 writes per organization per minute.
+
+```json
+// Request
+{
+  "entries": [
+    {
+      "kind": "CLASSIFICATION",
+      "tier": "MEDIUM",
+      "call": "Posted to 6420 Travel: recurring vendor pattern",
+      "why": "Same vendor posted to 6420 in 11 prior bills",
+      "refs": [{ "raw": "BILL:41f626a3-...:CREATE" }],
+      "idempotencyKey": "close-2026-06-bill-41f626a3"
+    }
+  ]
+}
+
+// Response
+{ "data": { "records": [{ "resourceId": "...", "replayed": false, "duplicateCount": 0 }] } }
+```
+
+`kind`: CLASSIFICATION, MATCH, SCOPE, ASSUMPTION, RISK, METHOD, RECOVERY, DEVIATION. `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`.
+
+### POST /api/v1/jots/search
+
+Plain-value filter (no expression envelopes): `ref` (TYPE:resourceId containment), `kind`, `tier`, `dispositionVerb`, `freetext` (case-insensitive substring over call and why), `createdFrom` / `createdTo` (epoch ms, inclusive). Sort is pinned server-side (CRITICAL and withheld-write entries first, then newest); no client sort. `includeStats: true` adds per-credential disposition counts alongside the page.
+
+```json
+// Request
+{ "limit": 100, "offset": 0, "filter": { "kind": "CLASSIFICATION" }, "includeStats": true }
+```
+
+### POST /api/v1/jots/:resourceId/disposition
+
+Append one review verb to a jot (append-only: annotates, never mutates).
+
+```json
+// Request
+{ "verb": "FLAG", "note": "Re-check the account mapping next close" }
+```
+
+`verb`: FLAG, REJECT, ENDORSE. The response may carry a `rollbackHandoff` pointer; execution lives in the rollback module.
+
+---
+
+*Last updated: 2026-07-11 (added Jots judgment journal, section 25). Previous: 2026-04-09 — Added: Contacts bulk-upsert (22), Background Jobs search (23), Export Records (24). 2026-03-13 — Payment record CRUD, nano-classifier, scheduler GET/PUT/DELETE.*

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

@@ -754,6 +754,16 @@ Universal async tracking layer. Any operation returning a `jobId` can be polled
 
 `outputFormat: "XLSX"` is required. Pass `query` OR `filter`, never both (server enforces). Entity types: INVOICE, BILL, CUSTOMER_CREDIT_NOTE, SUPPLIER_CREDIT_NOTE, SALE_PAYMENT, PURCHASE_PAYMENT, BATCH_PAYMENT, CONTACT, ITEM, CAPSULE, SCHEDULED_TRANSACTION, JOURNAL, BANK_RECORD, CASHFLOW_TRANSACTION, FIXED_ASSET, CHART_OF_ACCOUNT, TAX_PROFILE.
 
+### Jots (Judgment Journal)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/jots` | Batch-record judgment entries (1-100, per-entry acks; a bad entry never fails the batch) |
+| POST | `/jots/search` | Search judgment entries. Server-pinned sort: critical and withheld-write first, then newest. `includeStats` adds per-credential disposition counts |
+| POST | `/jots/:resourceId/disposition` | Append a review disposition (FLAG / REJECT / ENDORSE), append-only |
+
+See endpoints.md section 25 for request/response shapes and the `refs` grammar (`TYPE:resourceId[#field][:RELATION]` in `raw`).
+
 ---
 
-*Last updated: 2026-04-29 — Added 3 drafts lifecycle endpoints (validate, convert-to-active, submit-for-approval) — bulk-friendly, mixed-type batches up to 500. Previous same day: 8 reconciliation action endpoints; 8 bulk-upsert endpoints. 2026-04-09 — Background Jobs, Export Records, contacts bulk-upsert.*
+*Last updated: 2026-07-11 (added Jots judgment journal: 3 endpoints). Previous: 2026-04-29 — Added 3 drafts lifecycle endpoints (validate, convert-to-active, submit-for-approval) — bulk-friendly, mixed-type batches up to 500. Same day: 8 reconciliation action endpoints; 8 bulk-upsert endpoints. 2026-04-09 — Background Jobs, Export Records, contacts bulk-upsert.*

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 5.21.0
+version: 5.23.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 65 command groups and 356 tools, including employee-expense claims.
+  Covers all 66 command groups and 357 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. 65 command groups, 13 calculators, 12 job blueprints, 356 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, 357 tools. Also fully compatible with Juan Accounting (same API, same endpoints).
 
 ## When to Use This Skill
 
@@ -268,6 +268,8 @@ Sending `lineItems[]` to the FLAT endpoint silently ignores them and creates a $
 
 **AI & Automation**: `magic` (create, status, search, split), `quick-fix`, `capsules`, `capsule-transaction` (alias: `ct`, 13 recipe types)
 
+**Judgment journal**: `jots` (create, recall, dispose)
+
 **Calculators**: `calc` (loan, lease, depreciation, prepaid-expense, deferred-revenue, fx-reval, ecl, provision, fixed-deposit, asset-disposal, accrued-expense, leave-accrual, dividend)
 
 **Jobs**: `jobs` (month-end, quarter-end, year-end, bank-recon, gst-vat, payment-run, credit-control, supplier-recon, audit-prep, fa-review, document-collection, statutory-filing) + tools (match, outstanding, ingest, sg-cs, sg-ca)
@@ -288,7 +290,7 @@ Everything else requires authentication (API key).
 
 ## Dashboard Deep Links (no CLI command — by design)
 
-The navigation tools (`get_dashboard_url`, `find_dashboard_destinations`) build dashboard URLs for the user ("open this invoice", "take me to the P&L"). They are agent/MCP tools only — read-only tools get no CLI twin (one canonical surface per operation). Never hand-construct a dashboard URL in a script; if you need a link, call the MCP tool. Full usage rules live in the jaz-api skill under "Dashboard Deep Links".
+The navigation tool (`navigate` — no destination to discover keys, a destination to build the deep link) builds dashboard URLs for the user ("open this invoice", "take me to the P&L"). It is an agent/MCP tool only — read-only tools get no CLI twin (one canonical surface per operation). Never hand-construct a dashboard URL in a script; if you need a link, call the MCP tool. Full usage rules live in the jaz-api skill under "Dashboard Deep Links".
 
 ## Error Handling
 

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

@@ -512,6 +512,19 @@ Blueprints are offline (no auth). Tools require auth.
 
 ---
 
+## Judgment Journal
+
+### `clio jots` · Judgment journal
+| Subcommand | Key flags |
+|------------|-----------|
+| `create` | `--kind` (CLASSIFICATION, MATCH, SCOPE, ASSUMPTION, RISK, METHOD, RECOVERY, DEVIATION), `--tier` (LOW, MEDIUM, HIGH, CRITICAL), `--call`, `--why`, `--ruled-out`, `--ref` (repeatable, grammar `TYPE:resourceId[#field][:RELATION]`), `--frame`, `--confidence`, `--cited-rule`, `--workflow-label`, `--agent-label`, `--idempotency-key`, `--input` (batch JSON), `--json` |
+| `recall` | `--ref`, `--kind`, `--tier`, `--disposition-verb` (FLAG, REJECT, ENDORSE), `--freetext`, `--created-from`, `--created-to`, `--stats`, `--limit`, `--offset`, `--all`, `--max-rows`, `--format`, `--json` |
+| `dispose <resourceId>` | `--verb` (FLAG, REJECT, ENDORSE), `--note`, `--json` |
+
+Batch create via `--input` file or stdin (`{ "entries": [...] }`, 1-100 per call, per-entry acks). `recall` sort is pinned server-side: critical and withheld-write entries first, then newest. `--stats` adds per-credential disposition counts (in the JSON/YAML envelope for machine formats). An all-error batch exits 1.
+
+---
+
 ## Organization
 
 ### `clio org` — Organization info

package/assets/skills/conversion/SKILL.md

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

@@ -1,6 +1,6 @@
 ---
 name: jaz-pseudo-sql
-version: 5.21.0
+version: 5.23.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.21.0
+version: 5.23.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.21.0
+version: 5.23.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 356 tools across 41 namespaces via 3 meta-tools. **Use the meta-tool flow — never enumerate tools blindly.**
+The Jaz MCP server exposes 357 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.