jaz-clio 5.45.0 → 5.46.1

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-358-blue?style=for-the-badge" alt="358 tools">
+  <img src="https://img.shields.io/badge/tools-367-blue?style=for-the-badge" alt="367 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>
 
-358 tools · 66 command groups · 7 skills · 13 calculators · 12 close playbooks · 159 field-tested API rules.
+367 tools · 66 command groups · 7 skills · 13 calculators · 12 close playbooks · 159 field-tested API rules.
 
 ```bash
 npm install -g jaz-clio
@@ -77,7 +77,7 @@ that ends up in a journal.
 
 ## MCP server
 
-358 tools for any AI agent that speaks MCP. Runs locally: no cloud, no ports.
+367 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.45.0
+version: 5.46.1
 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
@@ -148,7 +148,7 @@ The rest of this skill — field names, gotchas, error catalog, dependency order
 | Trial balance | `startDate`, `endDate` |
 | Balance sheet | `primarySnapshotDate` |
 | P&L | `primarySnapshotDate`, `secondarySnapshotDate` |
-| General ledger | `startDate`, `endDate`, `groupBy: "ACCOUNT"` (also `TRANSACTION`, `CAPSULE`) |
+| General ledger | `startDate`, `endDate`, `groupBy: "ACCOUNT"` (also `CONTACT`, `TRANSACTION`, `RELATIONSHIP`) |
 | Cashflow | `primaryStartDate`, `primaryEndDate` |
 | Cash balance | `reportDate` |
 | AR/AP report | `endDate` |

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

@@ -3,7 +3,7 @@
 > **The endpoints clio wraps — the REST surface is larger.** This file catalogues roughly 200
 > paths, organized by resource, including undocumented endpoints, magic AI features, admin
 > APIs, and advanced search/filter syntax. The committed OpenAPI spec (`spec/openapi.yaml`)
-> carries 440 paths / 358 operations and is the authoritative list; check it before concluding
+> carries 440 paths / 367 operations and is the authoritative list; check it before concluding
 > an endpoint does not exist. For request/response examples of core endpoints, see
 > endpoints.md.
 >

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 5.45.0
+version: 5.46.1
 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
-  66 command groups and 358 tools, including employee-expense claims.
+  66 command groups and 367 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, 358 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, 367 tools. Also fully compatible with Juan Accounting (same API, same endpoints).
 
 ## When to Use This Skill
 

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

@@ -406,7 +406,7 @@ Types: `trial-balance`, `balance-sheet`, `profit-loss`, `cashflow`, `aged-ar`, `
 | `--from` | Start date (P&L, cashflow, equity, recon) |
 | `--to` | End/snapshot date |
 | `--currency` | Currency code override |
-| `--group-by` | ACCOUNT, TRANSACTION, or CAPSULE (for GL/FA) |
+| `--group-by` | GL: ACCOUNT, CONTACT, TRANSACTION, RELATIONSHIP · FA summary: ACCOUNT, TYPE, CATEGORY, STATUS |
 | `--bank-account` | Bank account ID (for bank-recon-*) |
 
 Also: `clio reports pdf` — generate PDF from a message/document.
@@ -586,7 +586,7 @@ Valid entity types: INVOICE, BILL, CUSTOMER_CREDIT_NOTE, SUPPLIER_CREDIT_NOTE, S
 Universal async tracker — any operation returning a jobId (contacts bulk-upsert, items bulk-upsert, bank import, magic processing) can be polled here.
 
 ### `clio mcp` — MCP stdio server
-Starts an MCP server for Claude Code / AI tool integration. Exposes all 358 operations.
+Starts an MCP server for Claude Code / AI tool integration. Exposes all 367 operations.
 
 ### `clio serve` — HTTP daemon
 Starts the HTTP daemon for ChatKit and email channel integrations.

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 5.45.0
+version: 5.46.1
 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.45.0
+version: 5.46.1
 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.45.0
+version: 5.46.1
 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.45.0
+version: 5.46.1
 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/jobs/references/building-blocks.md

@@ -87,7 +87,7 @@ Capsule types used by jobs:
 
 Group GL by capsule for the auditor:
 ```
-generate_general_ledger(period_start, period_end, groupBy: 'CAPSULE')
+get_capsule(resourceId)   # returns the capsule's transactions; GL cannot group by capsule
 ```
 
 ## Platform tools every job uses

package/assets/skills/jobs/references/credit-control.md

@@ -53,7 +53,7 @@ search_invoices(
 get_contact(resourceId: <customer id>)
 ```
 
-For each customer build a chase record: `{customerName, totalOverdue, oldestDaysOverdue, invoices: [{reference, valueDate, dueDate, daysOverdue, balanceAmount}], primaryContact}`.
+For each customer build a chase record: `{customerName, totalOverdue, oldestDaysOverdue, invoices: [{reference, valueDate, dueDate, daysOverdue, outstanding}], primaryContact}`.
 
 ## Step 3 — Contact-signals pull (Mid-7)
 

package/assets/skills/jobs/references/fa-review.md

@@ -109,7 +109,7 @@ For assets at salvage value AND no longer in use:
 
 For each FA category (e.g., Vehicles, Office Equipment, Computers, Buildings):
 ```
-generate_general_ledger(accountResourceId: <FA cost GL>, period_start: '2025-01-01', period_end: '2025-12-31', groupBy: 'CAPSULE')
+generate_general_ledger(accountResourceId: <FA cost GL>, period_start: '2025-01-01', period_end: '2025-12-31', groupBy: 'ACCOUNT')
 ```
 
 Group by capsule shows per-asset / per-disposal trail. Auditor sample-test will pick 2-3 assets per category and trace GL → original purchase bill → FA registration → depreciation history → disposal (if any).

package/assets/skills/jobs/references/payment-run.md

@@ -54,7 +54,7 @@ search_bills(
 
 Paginate via `offset` if `totalElements > 200`. Add a 7-day grace window (`dueDate.lte: <cutoff + 7 days>`) — pay slightly early beats missing day-after.
 
-For each bill, also collect: `contactResourceId`, `currency`, `originalAmount`, `balanceAmount`, `dueDate`, `reference`. Per `jaz-api/SKILL.md` rule 52, `dueDate` arrives as epoch ms — convert with `new Date(ms)` before display.
+For each bill, also collect: `contactResourceId`, `currency`, `originalAmount`, `paymentRecords`, `creditsApplied`, `dueDate`, `reference`. `balanceAmount` is a FILTER key only — the API accepts it in a filter but never returns it on a bill or invoice. Reading it back yields undefined. Derive outstanding instead: `totalAmount - sum(paymentRecords[].transactionAmount) - sum(creditsApplied[].amountApplied)`, and fetch with `view: 'full'` because a lean row omits `paymentRecords` entirely. Per `jaz-api/SKILL.md` rule 52, `dueDate` arrives as epoch ms — convert with `new Date(ms)` before display.
 
 ## Step 3 — AP aging cross-check
 
@@ -62,7 +62,7 @@ For each bill, also collect: `contactResourceId`, `currency`, `originalAmount`,
 generate_aged_ap(period_end: '2025-02-28')
 ```
 
-Verify: `sum(search_bills.balanceAmount) ≈ generate_aged_ap.totalOutstanding` (within the materiality threshold). Mismatch indicates pending bills in non-`UNPAID` status (e.g., `PARTIALLY_PAID`) that need separate handling — surface to the user.
+Verify: `sum(derived outstanding) ≈ generate_aged_ap.totalOutstanding` (within the materiality threshold). Mismatch indicates pending bills in non-`UNPAID` status (e.g., `PARTIALLY_PAID`) that need separate handling — surface to the user.
 
 Flag any bill in the 60d+ bucket — these need priority OR dispute resolution. Exclude bills the user has flagged as disputed.
 
@@ -106,7 +106,7 @@ create_bill_payment(
 
 **FX bills (e.g., USD bill paid from SGD account):** `paymentAmount` is the SGD amount that left the bank, `transactionAmount` is the USD amount applied to the bill. The platform calculates the implied rate and posts the FX gain/loss. Per `jaz-api/SKILL.md` rule 4: same-currency means both fields equal; FX means they differ.
 
-**Partial payment:** Set both fields to the partial amount; bill remains `UNPAID` with reduced `balanceAmount`.
+**Partial payment:** Set both fields to the partial amount; bill remains `UNPAID`; the payment appears in `paymentRecords[]` and outstanding is derived from it.
 
 **Reference convention:** `PAYRUN-YYYY-MM-DD-NNN` (zero-padded sequence). Bank reconciliation downstream relies on this prefix to auto-match bank statement lines.
 
@@ -123,7 +123,7 @@ search_payments(filter: {reference: {startsWith: 'PAYRUN-2025-02-28-'}, valueDat
 
 Assert:
 - AP aging total reduced by `sum(payments.transactionAmount)` (in base currency, FX-converted at value date).
-- Bills fully paid no longer appear in aging; partials show reduced `balanceAmount`.
+- Bills fully paid no longer appear in aging; partials carry the payment in `paymentRecords[]`; derive outstanding from it.
 - `search_payments` returns N rows where N = bills paid in step 6.
 
 ```
@@ -152,7 +152,7 @@ Assert: per-account balance reduced by `sum(paymentAmount per accountResourceId)
 - **Priority-based payment ordering:** `sort: 'dueDate:asc'` covers chronological. For overdue-first, sort by `daysOverdue:desc`. For supplier-strategic, ask the user which suppliers are priority and process those first.
 - **Multi-currency runs:** Split the run by currency. SGD bills → SGD bank; USD bills → USD bank or SWIFT-routed. The actual bank disbursement is handled outside Jaz (via the bank's portal); Jaz records the payment after it clears.
 - **Approval workflow (multi-signatory SMBs):** Build the batch in step 5, get out-of-band approval, then execute step 6 only after sign-off. Do NOT post payments before the actual bank transfer is initiated — Jaz payments are not "payment instructions", they record completed payments.
-- **Early-payment discounts:** If supplier offers `2% 10 Net 30`, computing the equivalent annualized return is `(2% / 98%) × (365 / 20) ≈ 37.2%`. Take it when cash allows. Apply the discount as: pay `transactionAmount = bill.balanceAmount × 0.98`, then post a separate journal Dr Bank Charges/Discount Income for the 2% saved (cleaner than partial payment of the original bill).
+- **Early-payment discounts:** If supplier offers `2% 10 Net 30`, computing the equivalent annualized return is `(2% / 98%) × (365 / 20) ≈ 37.2%`. Take it when cash allows. Apply the discount as: pay `transactionAmount = (derived outstanding) × 0.98`, then post a separate journal Dr Bank Charges/Discount Income for the 2% saved (cleaner than partial payment of the original bill).
 
 ---
 

package/assets/skills/jobs/references/supplier-recon.md

@@ -47,7 +47,7 @@ search_bills(
 )
 ```
 
-Per bill: `{resourceId, reference, valueDate, currency, originalAmount, balanceAmount, status, dueDate}`. Keep the Jaz-side bill list for the recon pack.
+Per bill: `{resourceId, reference, valueDate, currency, originalAmount, paymentRecords, status, dueDate}`. `balanceAmount` is a FILTER key only — the API accepts it in a filter but never returns it on a bill or invoice. Reading it back yields undefined. Derive outstanding instead: `totalAmount - sum(paymentRecords[].transactionAmount) - sum(creditsApplied[].amountApplied)`, and fetch with `view: 'full'` because a lean row omits `paymentRecords` entirely. Keep the Jaz-side bill list for the recon pack.
 
 For an opening-balance recon: also pull the supplier's pre-period balance via `generate_aged_ap(period_end: <period-start - 1 day>)` and filter to this supplier.
 

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

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

package/assets/skills/transaction-recipes/references/building-blocks.md

@@ -63,7 +63,7 @@ The recipe engine uses capsules automatically. But capsules also enable advanced
 
 2. **Use Capsule Types as the search axis, not Capsule Name.** Capsule names are unique per instance ("FY2025 Office Insurance"); types are reusable ("Prepaid Expenses"). `search_capsules(filter: {capsuleType: {eq: 'Prepaid Expenses'}})` returns ALL prepaid capsules across history.
 
-3. **Group GL by capsule for the auditor.** Capsules are the ONLY enrichment that supports `groupBy: 'CAPSULE'` in `generate_general_ledger`. Auditor sample-test: pick 3 capsules per type, pull the full GL by capsule, tie the entries back to the source documents (bills, invoices, journals). This is the highest-leverage capsule use.
+3. **Tie capsule entries back for the auditor.** `generate_general_ledger` does NOT group by capsule -- `groupBy` is ACCOUNT, CONTACT, TRANSACTION or RELATIONSHIP, and `CAPSULE` returns 422 (verified live 2026-09-01). Auditor sample-test: pick 3 capsules per type, read each with `get_capsule` to get its transaction resource ids, then pull those documents (bills, invoices, journals) directly. Same evidence, one more hop.
 
 **MCP tool shape:**
 
@@ -91,7 +91,7 @@ search_capsules(filter: {capsuleType: {eq: 'Loan Repayment'}}, status: {eq: 'ACT
   # All open loan capsules — feed into year-end-close.md Y6 reclassification
 search_journals(filter: {capsuleResourceId: {eq: <id>}}, sort: 'valueDate:asc')
   # Full GL for one capsule — the auditor's view
-generate_general_ledger(period_start, period_end, groupBy: 'CAPSULE')
+get_capsule(resourceId)   # returns the capsule's transactions; GL cannot group by capsule
   # Period activity grouped by capsule — the practitioner's view
 ```
 
@@ -241,7 +241,7 @@ Apply enrichments to recipe transactions for richer reporting and record-keeping
    }
    ```
 4. **Supported transaction types**: invoices, bills, credit notes, journals, cash entries
-5. **Reports**: Classified transactions appear in General Ledger grouped by capsule when using `groupBy: "CAPSULE"`
+5. **Reports**: General Ledger cannot group by capsule (`groupBy` accepts ACCOUNT, CONTACT, TRANSACTION, RELATIONSHIP only). Read the capsule with `get_capsule` and pull its transactions.
 
 ---
 

package/assets/templates/platform-rules/jaz-agent-rules.md

@@ -6,11 +6,11 @@ Source of truth lives in the installed skills (`.claude/skills/jaz-*/SKILL.md` o
 
 ## Discovery
 
-Jaz exposes **358 tools across 43 namespaces**. Your tool list shows **3, 43, or 358** entries depending on packaging — **never infer capability from its length.**
+Jaz exposes **367 tools across 45 namespaces**. Your tool list shows **3, 45, or 367** entries depending on packaging — **never infer capability from its length.**
 
 - **3** — `search_tools(query)` → `describe_tools(names)` → `execute_tool(name, args)`. Empty query returns the namespace map.
 - **43** — namespace routers; call one with `{ operation, arguments }`. Its description lists its operations.
-- **358** — call operations directly by name.
+- **367** — call operations directly by name.
 
 `describe_capabilities` returns the capability map on all three. **Call it before telling the user Jaz cannot do something.**