jaz-clio 5.20.29 → 5.20.30

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-305-blue?style=for-the-badge" alt="305 tools">
+  <img src="https://img.shields.io/badge/tools-323-blue?style=for-the-badge" alt="323 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>
 
-305 tools. 60 command groups. 13 calculators. 12 job playbooks. 158 API rules. 16 IFRS recipes.
+323 tools. 63 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) · 60 command groups
-- [MCP Server](#mcp-server) · 305 tools for AI agents
+- [CLI](#cli) · 63 command groups
+- [MCP Server](#mcp-server) · 323 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
@@ -47,13 +47,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
 ```
 
-60 command groups. 16 report types. 13 calculators. 12 job playbooks. Every command supports `--json`. Run `clio --help` for the full list.
+63 command groups. 16 report types. 13 calculators. 12 job playbooks. Every command supports `--json`. Run `clio --help` for the full list.
 
 ---
 
 ## MCP Server
 
-305 tools, available to any AI agent that speaks MCP. Runs locally: no cloud, no ports.
+323 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,13 +1,13 @@
 ---
 name: jaz-api
-version: 5.20.29
+version: 5.20.30
 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
   recovery (422/400/404/500), search filters, pagination, and edge cases for
   every endpoint — invoices, bills, credit notes, journals, cash entries,
   payments, contacts, CoA, items, tax profiles, bank records, fixed assets,
-  schedulers, subscriptions, attachments, and Jaz Magic extraction. Also use
+  schedulers, subscriptions, attachments, claim settings, and Jaz Magic extraction. Also use
   when building API clients, seeding test data, or adding new endpoint support.
 license: MIT
 compatibility: Requires Jaz API key (x-jk-api-key header). Works with Claude Code, Google Antigravity, OpenAI Codex, GitHub Copilot, Cursor, and any agent that reads markdown.
@@ -31,7 +31,7 @@ The rest of this skill — field names, gotchas, error catalog, dependency order
 
 **Core fundamentals (read first, every integration):** Identifiers & Dates 1–3; Names & Fields 9–13; Transaction Creation 14–16; Chart of Accounts 17–22; Payments / Cross-Currency 4–8; Journals & Cash 23–26; Credit Notes & Refunds 27–28; Reports 36–37; Tax Profile Scoping 100; Transaction References 104; Draft Finalization Pipeline 81–88; Jaz Magic / PDF-JPG 57–63; Currency Rates 39, 49, 105; Withholding Tax 45, 98.
 
-**Integration depth (API clients, pipelines, batch jobs, MCP/CLI):** Bulk Upsert (Items/Contacts/Rates); Background Jobs (filter `resourceId` not `jobId`); Export Records; Pagination (38); Search & Filter (50–56); Response Shape Gotchas (66–73); Cash Entry Response Shape (74–77); Entity Resolution (78–80); Bank Rules (89–90c); Fixed Assets (91–92c); Subscriptions & Scheduled (93–94); niche endpoints (95–102); Journals balance (103); Quick Fix (107, 111); TTB (108); Dynamic Strings (109–110); Sub-Resource Shapes (112); Nano-Classifier (113); Scheduler Asymmetry (114); Payment Record CRUD (115–117); Bulk Upserts transactions (118–122); Reconciliation write-side (123–127); Drafts lifecycle (128–135); Orders — Sale Quotes / Sale Orders / Purchase Requests / Purchase Orders (`references/orders.md`).
+**Integration depth (API clients, pipelines, batch jobs, MCP/CLI):** Bulk Upsert (Items/Contacts/Rates); Background Jobs (filter `resourceId` not `jobId`); Export Records; Pagination (38); Search & Filter (50–56); Response Shape Gotchas (66–73); Cash Entry Response Shape (74–77); Entity Resolution (78–80); Bank Rules (89–90c); Fixed Assets (91–92c); Subscriptions & Scheduled (93–94); niche endpoints (95–102); Journals balance (103); Quick Fix (107, 111); TTB (108); Dynamic Strings (109–110); Sub-Resource Shapes (112); Nano-Classifier (113); Scheduler Asymmetry (114); Payment Record CRUD (115–117); Bulk Upserts transactions (118–122); Reconciliation write-side (123–127); Drafts lifecycle (128–135); Orders — Sale Quotes / Sale Orders / Purchase Requests / Purchase Orders (`references/orders.md`); Claim Settings — Claim Types / Claim Profiles / Posting Rules (`references/claims.md`).
 
 ## When to Use This Skill
 

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

@@ -0,0 +1,39 @@
+# Claim Settings — Claim Types, Claim Profiles, Posting Rules
+
+Configuration for the employee-expense **Claims** feature (Settings → Claim Settings).
+Three master-data entities, each with full CRUD + search. Employees, claims, and
+claim → journal conversion build on top of this config (separate surface).
+
+One MCP namespace wraps all three: **`claim_settings`**. CLI: `clio claim-types …`,
+`clio claim-profiles …`, `clio posting-rules …`. Each entity supports
+`list / get / search / create / update / delete`.
+
+## Entities
+
+| Entity | What it is | Key fields |
+|--------|-----------|-----------|
+| **Claim Type** | An expense category (e.g. "Travel", "Meals"). | `name` (unique/org), `expenseAccountResourceId`, `taxProfileResourceId`, `classifierConfig`, `isDefault` |
+| **Claim Profile** | A per-employee policy bundle (who approves, spend limits, which types are visible, the liability account). | `name` (unique/org), `approverUserResourceId`, `visibleClaimTypeIds[]`, `visibleTaxProfileIds[]`, `visibleClassifierIds[]`, `visibleVendorResourceIds[]`, `allowedCurrencies[]`, `minClaimAmount`, `maxClaimAmount`, `maxPerPeriodAmount`, `perPeriod`, `employeeBalanceAccountResourceId`, `digestEmailEnabled`, `taxMode`, `isDefault` |
+| **Posting Rule** | How approved claims group into journals at conversion (the "Posting Rules" tab). | `name` (unique/org), `outerAxis`, `innerAxis`, `lineDescriptionTemplate`, `journalReferenceTemplate`, `defaultBankAccountResourceId`, `defaultIncludeReimbursementPayout`, `isDefault` |
+
+## Enums (use EXACT values)
+
+- **Claim Profile `perPeriod`**: `DAILY` `WEEKLY` `MONTHLY` `QUARTERLY` `YEARLY`
+- **Claim Profile `taxMode`**: `NO_TAX` `INCLUSIVE` — `EXCLUSIVE` is reserved and **rejected** server-side.
+- **Posting Rule `outerAxis`** (outer grouping): `PER_EMPLOYEE` `PER_VENDOR` `PER_PAIR` `ONE_BATCH` `PER_CLAIM`
+- **Posting Rule `innerAxis`** (line aggregation): `RAW` `BY_CT_TP_NC` `BY_CT_TP_NC_EMPLOYEE` `BY_CT_TP_NC_VENDOR`
+
+## Gotchas (verified live)
+
+1. **Create returns the FULL entity** in `{ data: { … } }` (not just `{ resourceId }`). No follow-up `get_*` needed.
+2. **Names are unique per org** (case-insensitive for claim types + posting rules). The `create_*` tools dedup by name and return the existing entity (`_guard: duplicate_skipped`) instead of 422-ing.
+3. **`isDefault` auto-true for the first entity.** When an org has zero posting rules, the first one created becomes the default automatically.
+4. **The default posting rule cannot be deleted** while it is the default → `422` ("set another rule as default first"). Promote another rule first, then delete.
+5. **Updates are partial.** Omitted fields are unchanged. To NULL an optional field, pass it in `clearFields` (tool) / `--clear a,b` (CLI) — these map to the API's `clear<Field>` flags. Posting rules have no clear flags (all fields stay set).
+6. **`employeeBalanceAccountResourceId` must be a CURRENT_LIABILITY account** and is required before a profile's employees can be reimbursed at conversion. Once an employee on the profile has a non-zero balance, it can't be changed/cleared.
+7. **Profile constraints (server-enforced):** `minClaimAmount ≤ maxClaimAmount`; `maxPerPeriodAmount` requires `perPeriod`.
+8. **Posting Rule templates** are Handlebars-style: `lineDescriptionTemplate` (required, e.g. `"{employeeName} - {claimType}"`) and the optional `journalReferenceTemplate` for the parent journal header.
+
+## Search
+
+Standard `{ filter, sort }` envelope (filter-only — no natural-language `query`). Sort keys: `resourceId`, `name`, `isDefault`, `createdAt`, `updatedAt`. Filterable fields mirror the key fields above (name = contains; ids = eq; amounts = gte/lte; flags = boolean).

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 5.20.29
+version: 5.20.30
 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 60 command groups and 305 tools.
+  Covers all 63 command groups and 323 tools.
 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. 60 command groups, 13 calculators, 12 job blueprints, 305 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. 63 command groups, 13 calculators, 12 job blueprints, 323 tools. Also fully compatible with Juan Accounting (same API, same endpoints).
 
 ## When to Use This Skill
 

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 5.20.29
+version: 5.20.30
 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.20.29
+version: 5.20.30
 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.20.29
+version: 5.20.30
 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.20.29
+version: 5.20.30
 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 305 tools across 36 namespaces via 3 meta-tools. **Use the meta-tool flow — never enumerate tools blindly.**
+The Jaz MCP server exposes 323 tools across 38 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.