jaz-clio 5.53.1 → 5.55.0

package/README.md

@@ -9,7 +9,7 @@
 
 <p align="center"><b>Jaz accounting on the command line, and inside any AI agent.</b></p>
 
-369 tools · 69 command groups · 7 skills · 13 calculators · 12 close playbooks · 159 field-tested API rules.
+369 tools · 72 command groups · 7 skills · 13 calculators · 12 close playbooks · 159 field-tested API rules.
 
 ```bash
 npm install -g jaz-clio
@@ -50,7 +50,7 @@ clio magic create --file receipt.pdf                   # AI extracts, drafts the
 clio invoices search --query 'status:unpaid AND $500+' # structured per-entity search
 ```
 
-69 command groups, 16 report types, 13 calculators, 12 job playbooks. Every command takes `--json`. Run `clio --help` for the full list.
+72 command groups, 16 report types, 13 calculators, 12 job playbooks. Every command takes `--json`. Run `clio --help` for the full list.
 
 ### Foreign currency
 

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 5.53.1
+version: 5.55.0
 description: >-
   Use this skill whenever you call, debug, or review code that touches the Jaz
   REST API. Covers field names, response shapes, 159 production gotchas, error
@@ -526,7 +526,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 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.)
+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 `navigate` — one operation, on both surfaces (`clio navigate` on the CLI, offline). 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/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 5.53.1
+version: 5.55.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: >-
   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
-  69 command groups and 369 tools, including employee-expense claims.
+  72 command groups and 369 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. 69 command groups, 13 calculators, 12 job blueprints, 369 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. 72 command groups, 13 calculators, 12 job blueprints, 369 tools. Also fully compatible with Juan Accounting (same API, same endpoints).
 
 ## When to Use This Skill
 
@@ -291,9 +291,19 @@ Offline commands (no auth needed): `calc`, `jobs` (blueprints only), `capsule-tr
 
 Everything else requires authentication (API key).
 
-## Dashboard Deep Links (no CLI command — by design)
+## 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".
+`clio navigate` (alias `nav`) builds dashboard URLs for the user ("open this invoice", "take me to the P&L"). Offline — no API key, no request.
+
+```
+clio navigate --query "profit"           # discover the key
+clio navigate reports.profit-and-loss    # build the link
+clio navigate sales.modal.view-sale --resource-id <id>
+```
+
+Only the URL goes to stdout, so `clio nav <key> | pbcopy` copies a link and nothing else. **Never hand-construct a dashboard URL and never guess a key** — routes are not guessable and a wrong link is worse than no link. An unknown key comes back with near-matches; follow them rather than improvising.
+
+The same operation is `navigate` on the MCP surface. Full usage rules live in the jaz-api skill under "Dashboard Deep Links"; the flag reference is in `references/command-catalog.md`.
 
 ## Error Handling
 

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

@@ -1,6 +1,6 @@
 # Clio Command Catalog
 
-Complete reference for all 69 command groups. Organized by domain.
+Complete reference for all 72 command groups. Organized by domain.
 
 ---
 
@@ -399,6 +399,49 @@ What the organization can be billed for. No create/update/delete upstream; maint
 
 No free-text `--query`: the endpoint rejects it (`The query field is not supported for this entity`). Filters here are **plain strings, not expression objects** — `PurchaseItemFilter` declares them as bare `string`, so there is no `contains`. `purchaseResourceId` and `resourceId` also exist upstream and are reachable via `--filter`.
 
+### `clio navigate` (alias: `nav`) — Dashboard deep links (offline, 1 tool)
+```
+clio navigate                                    # discover: all destinations, capped
+clio navigate --query invoice --kind modal      # discover: narrow the search
+clio navigate reports.profit-and-loss            # build: a screen link
+clio navigate sales.modal.view-sale --resource-id <id>   # build: focus one record
+clio navigate reports.profit-and-loss --org-id <orgResourceId>
+```
+**Offline** — no API key, no request. The route manifest is generated in the dashboard and committed here.
+
+Omit the destination to SEARCH; give one to BUILD a link. Discovery caps its output and reports the true total, so narrow with `--query`, `--resource` or `--kind` when it says it truncated.
+
+The `--query` search bridges accounting vocabulary to dashboard vocabulary: `invoice` finds the `sale` destinations, `bill` finds `purchase`, `credit note` finds `credit`. Without that, the word an accountant would type returns nothing.
+
+`--resource-id` attaches a record and is valid only on a record-modal destination (`<resource>.modal.view-*`); a screen rejects it rather than silently dropping it. An unknown key comes back with near-matches.
+
+The URL is the only thing on stdout — the label goes to stderr — so `clio nav <key> | pbcopy` copies a link and nothing else. Links carry no `&org=` unless you pass `--org-id`; without it the link opens in whichever organization the reader is already viewing.
+
+### `clio modules` — Which features are enabled for the organization (read-only, 2 tools)
+Provisioned upstream; no create/update/delete exists.
+
+| Subcommand | Key flags |
+|------------|-----------|
+| `list` | `--limit`, `--offset`, `--all`, `--max-rows` |
+| `get <resourceId>` | — |
+
+`roleCodes` is the column that matters: a module can be enabled and still deny the caller, because access is per role. "The module is on" and "I can use it" are different questions.
+
+### `clio report-templates` — Saved report layouts (read-only, 3 tools)
+Authored in the dashboard; no create/update/delete exists.
+
+| Subcommand | Key flags |
+|------------|-----------|
+| `list` | `--json`, `--format` — **no paging flags, deliberately** |
+| `get <resourceId>` | — |
+| `search` | `--report-type`, `--report-category`, `--default`, `--filter`, `--sort`, `--order` — **no paging flags** |
+
+Neither `list` nor `search` declares `--limit`/`--offset`/`--all`/`--max-rows`: both ignore them upstream, returning the full set in one response regardless. The flags are omitted rather than accepted-and-ignored.
+
+Two of the three search filters 500 upstream today (measured 2026-09-07): `--report-category` fails alone but works when `--report-type` is also supplied, and `--default` fails. `--report-type` alone is reliable.
+
+`templateConfiguration` is a JSON **string**, not an object — read it with `--json`.
+
 ### `clio pseudo-sql` (alias: `sql`) — Read-only SQL over the curated reporting tables (6 tools)
 A restricted SQL subset against Jaz's curated reporting schema, **not** the customer's database. SELECT only, single statement, 16384-char cap — the engine rejects DML, so there is no write verb.
 

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 5.53.1
+version: 5.55.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.53.1
+version: 5.55.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.53.1
+version: 5.55.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.53.1
+version: 5.55.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.53.1
+version: 5.55.0
 description: >-
   Use this skill when modeling complex multi-step accounting transactions —
   anything that spans multiple periods, involves changing amounts, or requires