jaz-clio 5.73.0 → 5.73.2

package/README.md

@@ -20,11 +20,11 @@ Node.js 18+. Works with [Jaz](https://jaz.ai) and [Juan Accounting](https://juan
 ## Contents
 
 - [Three ways in](#three-ways-in)
+- [Auth](#auth)
 - [CLI](#cli)
 - [MCP server](#mcp-server)
 - [Skills](#skills)
 - [Jaz Kit · run your practice](#jaz-kit--run-your-practice)
-- [Auth](#auth)
 - [Semantic help-center search](#semantic-help-center-search-optional)
 - [Privacy](#privacy) · [Support](#support) · [License](#license)
 
@@ -38,6 +38,19 @@ Node.js 18+. Works with [Jaz](https://jaz.ai) and [Juan Accounting](https://juan
 
 On top of these, one layer for accountants closing real books across many companies: **[Jaz Kit](#jaz-kit--run-your-practice)**.
 
+## Auth
+
+```bash
+clio auth login           # sign in to Jaz in your browser (OAuth, the default)
+clio auth whoami          # verify
+```
+
+`clio auth login` opens Jaz sign-in. The CLI and local MCP share the session and refresh its tokens automatically. Add `--no-browser` to open the printed link yourself on the same computer. Agents can use `--json`: the sign-in link goes to stderr, and stdout carries only the result and the organization choices.
+
+Use `clio auth organizations --json` to list accessible organizations, `clio auth select <resourceId>` to select one, and `--org oauth:<resourceId>` on every organization-scoped command to pin it. `clio auth logout` removes the local session and keeps any API-key profiles; revoke the grant in Jaz to remove remote access.
+
+API-key profiles, `--api-key`, `JAZ_API_KEY`, and PATs remain supported. Use `--org oauth:<resourceId>` for OAuth or `--org <label>` for a saved key profile (`clio auth add <key>`); either overrides an inherited `JAZ_API_KEY`. Without `--org`, the environment key still takes precedence. Do not combine `--api-key` with `--org`. Do not share OAuth storage or commit it to a workspace. Every command takes `--json` for structured output.
+
 ## CLI
 
 ```bash
@@ -49,9 +62,25 @@ clio jobs month-end --period 2026-03                   # step-by-step close play
 clio magic create --file receipt.pdf                   # AI extracts, drafts the transaction
 clio invoices search --query 'status:unpaid AND $500+' # structured per-entity search
 clio ledger-find-fix preview --level TRANSACTIONS --input recode.json  # find & fix (recode) across record types
+clio approvals approve <resourceId> --entity invoices  # approve a document waiting on you
+clio sql preview "SELECT invoice_number, balance FROM invoices WHERE balance > 0 LIMIT 10"  # read-only pseudo-SQL
+clio report-templates list                             # the organization's saved report layouts
+clio modules list                                      # which features are switched on
+clio navigate reports.profit-and-loss                  # deep link into the Jaz dashboard (offline)
 ```
 
-76 command groups, 16 report types, 13 calculators, 12 job playbooks. Every command takes `--json`. Run `clio --help` for the full list.
+76 command groups, 17 report types, 13 calculators, 12 job playbooks. Every command takes `--json`. Run `clio --help` for the full list.
+
+Command groups by area:
+
+- **Sales and purchases**: `invoices`, `bills`, `customer-credit-notes`, `supplier-credit-notes`, `sale-orders`, `purchase-orders`, `payments`, `unapplied-payments`, `approvals`, `drafts`, `schedulers`, `subscriptions`
+- **Ledger and banking**: `journals`, `cash-in`, `cash-out`, `cash-transfer`, `cashflow`, `bank`, `bank-rules`, `reconciliations` (`recon`), `ledger-find-fix`, `quick-fix`, `fixed-assets` (`fa`)
+- **Master data**: `accounts`, `contacts`, `contact-groups`, `items`, `purchase-items`, `catalogs`, `inventory` (`inv`), `tags`, `custom-fields`, `nano-classifiers`, `tax-profiles`, `currencies`, `currency-rates`, `capsules`, `capsule-recipes`
+- **Claims**: `claims`, `claim-types`, `claim-profiles`, `posting-rules`, `employees`
+- **Reports and data**: `reports`, `exports`, `export-records`, `report-templates`, `pseudo-sql` (`sql`), `filing-submissions`, `background-jobs`
+- **Organization**: `org`, `org-users`, `references`, `modules` (`features`), `bookmarks`, `attachments`, `magic`, `jots`, `navigate` (`nav`), `help-center` (`hc`)
+- **Offline**: `calc`, `capsule-transaction` (`ct`), `jobs`
+- **Setup and tooling**: `auth`, `init`, `update`, `versions`, `version`, `health`, `completion`, `context`, `schema`, `resolve`, `mcp`, `mcp-call`, `serve`
 
 ### Foreign currency
 
@@ -82,12 +111,12 @@ that ends up in a journal.
 
 > **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.
 
-Run `clio auth login` once on this computer before enabling local MCP.
+Run `clio auth login` once on this computer before enabling local MCP, then pin the organization with `--org` (`clio auth organizations` lists the IDs).
 
 **Claude Code**
 
 ```bash
-claude mcp add jaz -- npx jaz-clio mcp
+claude mcp add jaz -- npx -y jaz-clio@latest mcp --org oauth:<resourceId>
 ```
 
 **Cursor · VS Code · Windsurf**
@@ -97,13 +126,13 @@ claude mcp add jaz -- npx jaz-clio mcp
   "mcpServers": {
     "jaz": {
       "command": "npx",
-      "args": ["-y", "jaz-clio", "mcp"]
+      "args": ["-y", "jaz-clio@latest", "mcp", "--org", "oauth:<resourceId>"]
     }
   }
 }
 ```
 
-OAuth can reach the organizations granted at sign-in; name the organization on each call. Optional key-based access also supports comma-separated keys or a personal access token.
+OAuth can reach the organizations granted at sign-in; `--org` pins one, and without it name the organization on each call. Optional key-based access also supports comma-separated keys or a personal access token.
 
 ```json
 { "env": { "JAZ_API_KEY": "jk-org1-key,jk-org2-key" } }
@@ -128,7 +157,7 @@ The workspace layer for closing real books, whether that is one company or fifty
 A close is not one conversation. Month-end runs many steps over several days, and an accountant serving eight clients runs it eight times, with eight different sets of bank accounts, materiality thresholds, and recurring entries. Jaz Kit gives each company a folder that remembers all of it, so no session re-asks what it should already know.
 
 ```
-/jk-setup                 create a company workspace, connect its key
+/jk-setup                 create a company workspace, connect it with OAuth
 /jk-open acme             load its context, verify the connection
 /jk-close 2026-06         run the close, resumable across sessions
 /jk-review                approve the drafts waiting on you
@@ -142,15 +171,6 @@ Each company lives under `~/Documents/Jaz Kit/orgs/<company>/`, holding its clos
 
 Everything is drafted first, every record carries a link into Jaz for you to review, and an interrupted close resumes exactly where it stopped. Multi-company work needs this CLI, which you already have. Full guide in the [repository README](https://github.com/teamtinvio/jaz-ai#jaz-kit--run-your-practice).
 
-## Auth
-
-```bash
-clio auth login           # Sign in to Jaz in your browser
-clio auth whoami          # verify
-```
-
-Pin an OAuth organization with `--org oauth:<resourceId>`. For optional API-key access, set `JAZ_API_KEY` or register a key using `clio auth add` and pass `--org <label>`. Every command takes `--json` for structured output.
-
 ## Semantic help-center search (optional)
 
 `search_help_center` runs keyword search over the bundled help-center corpus by default. Set `CLIO_HELP_CENTER_OPENAI_API_KEY` to add semantic search, which matches on intent rather than exact keywords: the CLI embeds only your query through the OpenAI embeddings API (`text-embedding-3-small`, the model the bundled index was built with) and merges both rankings. On an auth failure it warns once and falls back to keyword search. Use a project-scoped key restricted to embedding models with a low monthly cap. CLI only: MCPB installs ship without the embedding index and always use keyword search.
@@ -166,11 +186,3 @@ Runs on your machine. Calls go to the Jaz API over HTTPS. No telemetry, no data
 ## License
 
 [MIT](LICENSE)
-
-## OAuth sign-in (default)
-
-Run `clio auth login` to open Jaz sign-in. CLI and local MCP share the session and refresh tokens automatically. Add `--no-browser` to open the printed link yourself on the same computer. Agents can use `--json`; the sign-in link is printed to stderr, and stdout contains only the result and organization choices.
-
-Use `clio auth organizations --json` to list accessible organizations, `clio auth select <resourceId>` to select one, and `--org oauth:<resourceId>` on every organization-scoped command to pin it. `clio auth logout` removes the local session without deleting API-key profiles; revoke its grant in Jaz to remove remote access.
-
-API-key profiles, `--api-key`, `JAZ_API_KEY`, and PATs remain supported. Use `--org oauth:<resourceId>` for OAuth or `--org <label>` for a saved key profile; either overrides an inherited `JAZ_API_KEY`. Without `--org`, the environment key still takes precedence. Do not combine `--api-key` with `--org`. Do not share OAuth storage or commit it to a workspace.

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 5.73.0
+version: 5.73.2
 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
@@ -215,7 +215,7 @@ The rest of this skill — field names, gotchas, error catalog, dependency order
 73. **Capsules PUT requires `resourceId` + `capsuleTypeResourceId`** — Even for partial updates, `PUT /capsules/:id` requires `resourceId` and `capsuleTypeResourceId` in the body. Omitting either causes 422 or "Capsule type not found". Use read-modify-write pattern: GET current capsule, merge updates, PUT full payload. Clio handles this automatically.
 
 ### Cash Entry Response Shape (CRITICAL)
-74. **Cash-in/out/transfer CREATE returns `parentEntityResourceId`** — The resourceId in the POST response (`{ data: { resourceId: "X" } }`) is the journal header's `parentEntityResourceId`. This ID is used for DELETE (`DELETE /cash-entries/X`). But it is **NOT** the same ID used for GET (`GET /cash-in-entries/:id`). GET expects the cashflow-transaction `resourceId` from the LIST response. Three different IDs exist per cash entry: `parentEntityResourceId` (from CREATE + in LIST), `resourceId` (cashflow-transaction ID, from LIST — use for GET), `businessTransactionResourceId` (underlying journal ID — do NOT use for anything).
+74. **Cash-in/out/transfer CREATE returns `parentEntityResourceId`**: the resourceId in the POST response (`{ data: { resourceId: "X" } }`) is the journal header's `parentEntityResourceId`. This ID is used for DELETE (`DELETE /cash-entries/X`) and PUT. GET (`GET /cash-in-entries/:id`) accepts either the cashflow-transaction `resourceId` from the LIST response or this `parentEntityResourceId`. Three different IDs exist per cash entry: `parentEntityResourceId` (from CREATE + in LIST), `resourceId` (cashflow-transaction ID, from LIST, also accepted by GET), `businessTransactionResourceId` (underlying journal ID, do NOT use for anything).
 75. **Cash-in/out/transfer LIST/GET return cashflow-transaction shape** — NOT journal shape. Key field differences from journals: `transactionReference` (NOT `reference`), `transactionStatus` (NOT `status` — values: `ACTIVE`/`VOID`), `valueDate` is epoch ms (NOT ISO string), no `journalEntries` array, has `direction` (`PAYIN`/`PAYOUT`), has nested `account` object with bank name, has `businessTransactionType` (`JOURNAL_DIRECT_CASH_IN`/`JOURNAL_DIRECT_CASH_OUT`/`JOURNAL_CASH_TRANSFER`).
 76. **Cash-in/out/transfer search uses `/cashflow-transactions/search`** — Filter by `businessTransactionType: { eq: "JOURNAL_DIRECT_CASH_IN" }` (or `JOURNAL_DIRECT_CASH_OUT` or `JOURNAL_CASH_TRANSFER`). Other useful filters: `organizationAccountResourceId` (bank account), `businessTransactionReference` (reference), `valueDate` (date range). The search endpoint is shared across all cashflow transaction types.
 77. **DELETE for cash entries uses `/cash-entries/:id`** — NOT the individual resource paths. The ID used is the `parentEntityResourceId` (= the resourceId returned by CREATE). This is a shared endpoint for all cash entry types (cash-in, cash-out, cash-transfer).
@@ -329,7 +329,7 @@ Bills, invoices, and credit notes share identical mandatory field specs. Adding
 94. **Scheduled transaction search does NOT support `createdAt` sort** — `POST /scheduled-transaction/search` sort fields: `startDate`, `nextScheduleDate`, etc. Default to `startDate` DESC. This is a cross-entity search across all scheduled types (invoices, bills, journals, subscriptions). Filter by `businessTransactionType` (SALE, PURCHASE, JOURNAL) and/or `schedulerType` (RECURRING, SUBSCRIPTION) to narrow results.
 
 ### Contact Groups
-96. **Contact groups have `associatedContacts` array** — Each group contains `{ name, resourceId, associatedContacts: [{ name, resourceId }] }`. Search via `POST /contact-groups/search`. Known bug: PUT returns 500 (Rule 46).
+96. **Contact groups have `associatedContacts` array**: each group contains `{ name, resourceId, associatedContacts: [{ name, resourceId }] }`. Search via `POST /contact-groups/search`.
 
 ### Inventory
 97. **Inventory balances: one item or all.** One item: `GET /inventory-item-balance/:itemResourceId` (`get_inventory_balance`) returns `{ itemResourceId, latestAverageCostAmount, baseQty, baseUnit }`; the id is the ITEM resourceId, not an inventory-specific ID. All items: `GET /inventory-balances/:balanceStatus` (`list_inventory_balances`, `clio inventory balances --status`) with `balanceStatus` one of `ALL`, `AVAILABLE`, `FULLY_DRAWN` (anything else is 422); rows carry `itemCode`, `internalName`, `totalQuantity`, `baseUnit`, `averageCostAmount`, `balanceAmount`. The API answers an empty result with 404; the tool and CLI return it as `data: []`. `offset` is a page number here, though the spec says row (probed live 2026-09-23).
@@ -374,7 +374,7 @@ Bills, invoices, and credit notes share identical mandatory field specs. Adding
 111. **Quick-fix uses `tags` (string array) — e.g., `"tags": ["Q1"]`** — The `attributes` object in quick-fix transaction endpoints accepts `tags` as a string array (e.g., `"tags": ["Q1"]`). `tag` (singular) is silently ignored. This matches the `tags` array format used on create/update for all transaction types. The CLI `--tag` flag auto-wraps to `tags: [name]`.
 
 ### Sub-Resource Response Shapes
-112. **Invoice/bill payment & credit sub-resources return raw arrays** — `GET /invoices/:id/payments` and `GET /bills/:id/payments` return `[{paymentRecord}, ...]` — NOT `{data: [...]}`. Same for `GET /invoices/:id/credits` and `GET /bills/:id/credits`. The CLI wraps these into `{data: [...]}` for consistency. `DELETE /invoices/:id/credits/:creditsAppliedResourceId` reverses a credit application.
+112. **Invoice/bill payment & credit sub-resources: two shapes** (read from the API source; payments and the empty-credits case measured raw 2026-09-24). `GET /invoices/:id/payments` and `GET /bills/:id/payments` return `{ data: [{paymentRecord}, ...] }` (Rule 64). `GET /invoices/:id/credits` and `GET /bills/:id/credits` return `{ TotalElements, data: [...] }` when credits are applied but a BARE `[]` when none are. The CLI and tools normalize all of these to `{data: [...]}`. `DELETE /invoices/:id/credits/:creditsAppliedResourceId` reverses a credit application.
 
 ### Nano-Classifier API
 113. **Nano-classifier API gotchas** — CREATE uses `classes: string[]` (NOT `classNames` or `[{className}]`). `printable: boolean` is required — defaults to `false` (most classifiers are not printable). GET single is double-wrapped: `{data: {data: [...], totalElements, totalPages}}` — extract the first element from the inner paginated response. GET/LIST response returns classes as `[{className, resourceId}]` (objects), while CREATE accepts plain `string[]`.

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

@@ -20,7 +20,8 @@ employee** automatically (server resolves it at enqueue) — no `search_claims`
 don't pre-check). No bound employee on the uploader (a service / shared-key identity) →
 the server leaves it unbound; relay that ("not set up for claims"), don't invent one. The
 OCR'd draft may also carry no `reference` — if a later submit returns
-`CLAIM_REFERENCE_REQUIRED_AT_SUBMIT`, set one via `update_claim`.
+`CLAIM_REFERENCE_REQUIRED_AT_SUBMIT`, read the next number with `get_next_reference` (type
+`CLAIM`) and pass it as `reference` on `update_claim` (it has no autoReference).
 
 ## Claim records (`claims` + `claim_processing` namespaces)
 

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

@@ -787,7 +787,7 @@ Same shape as list items, wrapped in `{ data: {...} }`. Use the `resourceId` fro
 ### PUT /api/v1/cash-in-entries/:resourceId
 ### PUT /api/v1/cash-out-entries/:resourceId
 
-Same request body as POST. Use cashflow-transaction `resourceId` from LIST.
+Same request body as POST. Use the `parentEntityResourceId` (= the CREATE-returned resourceId).
 
 ### DELETE /api/v1/cash-entries/:resourceId
 
@@ -801,7 +801,7 @@ Shared delete endpoint for ALL cash entry types (cash-in, cash-out, cash-transfe
 **CRITICAL ID gotcha (verified via live testing)**:
 - CREATE returns `resourceId = A` (this is `parentEntityResourceId`)
 - LIST returns `resourceId = B` (cashflow-transaction ID), `parentEntityResourceId = A`
-- GET expects `B` (cashflow-transaction ID)
+- GET accepts `B` (cashflow-transaction ID) or `A` (parentEntityResourceId; a transfer's two rows share one `A`, so GET by `A` returns the first)
 - DELETE expects `A` (parentEntityResourceId, via `/cash-entries/A`)
 - `businessTransactionResourceId = C` (underlying journal ID) — do NOT use for any CRUD operation
 
@@ -1056,7 +1056,7 @@ Same cashflow-transaction response shape as cash-in/out list. `businessTransacti
 
 ### GET /api/v1/cash-transfers/:resourceId
 
-Use cashflow-transaction `resourceId` from LIST. Returns same shape wrapped in `{ data: {...} }`.
+Accepts the cashflow-transaction `resourceId` from LIST or the `parentEntityResourceId` from CREATE (both legs share it; GET by it returns the first). Returns same shape wrapped in `{ data: {...} }`.
 
 **Cash transfers have NO update (PUT) endpoint.**
 
@@ -2345,37 +2345,40 @@ Update an existing payment record. All fields optional — only included fields
 
 ## 19b. Invoice/Bill Sub-Resource Endpoints
 
-### GET /api/v1/invoices/{resourceId}/payments — Raw array response
+### GET /api/v1/invoices/{resourceId}/payments
 
 ```json
-// Response (RAW ARRAY — no {data: [...]} wrapper):
-[
-  {
-    "resourceId": "uuid-payment",
-    "paymentAmount": 2250.00,
-    "transactionAmount": 2250.00,
-    "valueDate": 1709251200000,
-    "paymentMethod": "BANK_TRANSFER",
-    "reference": "PAY-001"
-  }
-]
+// Response ({data: [...]} envelope):
+{
+  "data": [
+    {
+      "resourceId": "uuid-payment",
+      "paymentAmount": 2250.00,
+      "transactionAmount": 2250.00,
+      "valueDate": 1709251200000,
+      "paymentMethod": "BANK_TRANSFER",
+      "reference": "PAY-001"
+    }
+  ]
+}
 ```
 
-Same for `GET /bills/{resourceId}/payments`, `GET /invoices/{resourceId}/credits`, `GET /bills/{resourceId}/credits`.
+Same envelope for `GET /bills/{resourceId}/payments`.
 
-**CRITICAL**: These sub-resource endpoints return raw arrays, NOT `{data: [...]}`. The CLI wraps them into `{data: [...]}` for consistency.
+**CRITICAL**: `GET /invoices/{resourceId}/credits` and `GET /bills/{resourceId}/credits` differ:
+`{ "TotalElements": n, "data": [...] }` when credits are applied, but a BARE `[]` when none
+are (read from the API source; the empty case measured raw 2026-09-24). The CLI and tools normalize both to `{data: [...]}`.
 
 ---
 
-## 19c. Request Changes (REST only — no CLI or MCP wrapper)
+## 19c. Request Changes
 
 Sends a **submitted** record back to its creator for edits: the record returns to draft, its
 approval markers are cleared, and `message` is posted as the first comment on a new
 collaboration thread. Records in any other state are skipped and reported in the response.
 
-> **No wrapper exists.** These 18 routes have no `clio` subcommand, no MCP tool, and no
-> `src/core/api/` client function. Call them with a raw HTTP request — do not go looking for a
-> tool that does not exist.
+> **Wrapped.** MCP tools `request_document_changes` / `bulk_request_document_changes`, CLI
+> `clio approvals request-changes` / `clio approvals bulk-request-changes`.
 
 Nine entities, each with a single-record and a bulk form:
 
@@ -2440,6 +2443,34 @@ the job was accepted.
 
 ---
 
+## 19d. Approve
+
+Approves a record awaiting approval. **Irreversible**: it posts the ledger (and for invoices and
+bills also confirms a linked order and consumes the document reference). There is nothing to undo, and approving is one-shot
+(a record not awaiting approval, including an already-approved one, is refused).
+MCP tools `approve_documents` / `bulk_approve_documents`, CLI `clio approvals approve` /
+`clio approvals bulk-approve`. Four entities: `invoices`, `bills`, `customer-credit-notes`,
+`supplier-credit-notes` (claims approve through their own claims routes).
+
+| Form | Route | Response |
+|------|-------|----------|
+| Single | `POST /api/v1/{entity}/:resourceId/approve` (no body) | 200, `{ "data": { "records": [ { resourceId, status, approvalStatus, isSuccess, failureReason, errorCode } ] } }` |
+| Bulk | `POST /api/v1/{entity}/bulk-approve` | 202, job handle (same shape as 19c bulk); poll `POST /api/v1/background-jobs/search` |
+
+- Bulk body `{ "resourceIds": [...] }`: 1-100 **unique** UUIDs. Over 100 or a duplicate is 422
+  with nothing written.
+- Single form: an id not found in your organization is 404.
+- An id not found in your organization rejects the **whole** bulk batch with 422 and no job is
+  dispatched: fix the list and retry.
+- Bulk: records not awaiting approval are skipped and reported on the job tasks; only a foreign
+  id fails the batch.
+- Refusal channel differs: invoices/bills return 422 on a refused single approve; credit notes
+  return 200 with `isSuccess: false` while `approvalStatus` still reads the document's state.
+  Check `isSuccess`, never `approvalStatus`.
+- On a timeout or 500, read the record back and check its approval status before retrying.
+
+---
+
 ## 20. Nano-Classifier CRUD
 
 ### POST /api/v1/nano-classifiers — Create

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

@@ -869,7 +869,7 @@ The same applies on update: `PUT /cash-in-entries/:id` with `saveAsDraft: true`
 
 **"INACTIVE_OR_DELETED_ACCOUNT"** — The account referenced in the update is deleted or inactive. Verify the account UUID is valid and active.
 
-**"Cannot update ACTIVE entry"** — Journal or cash entry is already active. Must void and recreate to change.
+**"Cannot update ACTIVE entry"**: a per-record quick-fix failure. Do NOT void and recreate; edit the record with its own update tool: `update_invoice` / `update_bill` / `update_cash_in` / `update_cash_out` / `update_journal`.
 
 **"TRANSACTION_LOCKED"** — Transaction is in a locked period. Cannot update.
 
@@ -914,7 +914,7 @@ Two of the seven never reach you through this path: a zero `adjustmentValue` and
 
 ### Sub-Resource Response Errors
 
-**`Cannot read property 'data'` / TypeError** — Invoice/bill sub-resource endpoints (`GET /invoices/:id/payments`, `GET /invoices/:id/credits`, etc.) return raw arrays `[{...}]`, NOT `{data: [...]}`. Trying to access `.data` on the response fails. Wrap the raw array yourself.
+**`Cannot read property 'data'` / TypeError**: `GET /invoices/:id/credits` and `GET /bills/:id/credits` return a BARE `[]` when no credits are applied (else `{TotalElements, data}`), so `.data` on the empty case fails. Accept both shapes. The `/payments` sub-resources always answer `{data: [...]}`.
 
 ---
 

package/assets/skills/api/references/feature-glossary.md

@@ -14,7 +14,7 @@ Key capabilities: draft/approval workflows, multi-currency (auto-fetch ECB rates
 
 If payment date equals invoice date, it's recorded as a cash transaction (not AR). Transaction fees are deducted from cash received, and a payment `adjustment` shifts the cash leg further (net cash = paymentAmount - feesCharged + feesCollected +/- adjustmentValue) without touching AR. RGL = `(Invoice payment / Transaction Rate) - (Cash received / Payment Rate)`.
 
-**API**: CRUD `GET/POST/PUT/DELETE /invoices`, `POST /invoices/search`, `POST /invoices/:id/payments`, `GET /invoices/:id/payments`, `POST /invoices/:id/credits`, `GET /invoices/:id/download`, `POST/GET/DELETE /invoices/:id/attachments`, `PUT /invoices/:id/approve`, `POST /scheduled/invoices` (CRUD), `POST /scheduled/subscriptions` (recurring). Generic payment ops: `GET/PUT/DELETE /payments/:id`. **Starting from a PDF/JPG attachment?** Use `POST /magic/createBusinessTransactionFromAttachment` instead — Jaz Magic handles extraction & autofill (see AI Agents section).
+**API**: CRUD `GET/POST/PUT/DELETE /invoices`, `POST /invoices/search`, `POST /invoices/:id/payments`, `GET /invoices/:id/payments`, `POST /invoices/:id/credits`, `GET /invoices/:id/download`, `POST/GET/DELETE /invoices/:id/attachments`, `POST /invoices/:id/approve`, `POST /scheduled/invoices` (CRUD), `POST /scheduled/subscriptions` (recurring). Generic payment ops: `GET/PUT/DELETE /payments/:id`. **Starting from a PDF/JPG attachment?** Use `POST /magic/createBusinessTransactionFromAttachment` instead: Jaz Magic handles extraction & autofill (see AI Agents section).
 
 ---
 
@@ -40,7 +40,7 @@ Key capabilities: bill receipts (short-form template creating bill + payment tog
 
 Transaction fees are added to cash spent (not deducted like invoices), and a payment `adjustment` shifts the cash leg further without touching AP. RGL = `(Cash spent / Payment rate) - (Bill payment / Transaction rate)`.
 
-**API**: CRUD `GET/POST/PUT/DELETE /bills`, `POST /bills/search`, `POST /bills/:id/payments`, `GET /bills/:id/payments`, `POST /bills/:id/credits`, `POST/GET/DELETE /bills/:id/attachments`, `PUT /bills/:id/approve`, `POST /scheduled/bills` (CRUD). Generic payment ops: `GET/PUT/DELETE /payments/:id`. **Starting from a PDF/JPG attachment?** Use `POST /magic/createBusinessTransactionFromAttachment` instead — Jaz Magic handles extraction & autofill (see AI Agents section).
+**API**: CRUD `GET/POST/PUT/DELETE /bills`, `POST /bills/search`, `POST /bills/:id/payments`, `GET /bills/:id/payments`, `POST /bills/:id/credits`, `POST/GET/DELETE /bills/:id/attachments`, `POST /bills/:id/approve`, `POST /scheduled/bills` (CRUD). Generic payment ops: `GET/PUT/DELETE /payments/:id`. **Starting from a PDF/JPG attachment?** Use `POST /magic/createBusinessTransactionFromAttachment` instead: Jaz Magic handles extraction & autofill (see AI Agents section).
 
 ---
 
@@ -179,7 +179,7 @@ Statement amounts are recorded in the bank account's currency — no auto-conver
 
 Workflow for draft invoices and bills requiring admin sign-off before activation. Three user roles: Admins (approve + create active), Preparers (submit drafts for approval), Members (submit own drafts only). Status progression: Draft → For Approval → Approved (active). Approval PDFs capture Submitted By / Approved By audit trail.
 
-**API**: `PUT /invoices/:id/approve`, `PUT /bills/:id/approve`
+**API**: `POST /{invoices|bills|customer-credit-notes|supplier-credit-notes}/:id/approve` and `/bulk-approve` (irreversible: posts the ledger), `POST /{entity}/:id/request-changes` (endpoints.md sections 19c, 19d)
 
 ---
 

package/assets/skills/api/references/field-map.md

@@ -327,10 +327,10 @@ PUT URL: `/cash-in-entries/:parentEntityResourceId` (or `/cash-out-entries/:id`)
 
 ```
 CREATE → { resourceId: "A" }         ← This is parentEntityResourceId
-LIST   → { resourceId: "B",          ← This is the cashflow-transaction ID (use for GET)
+LIST   → { resourceId: "B",          ← This is the cashflow-transaction ID (GET accepts it)
             businessTransactionResourceId: "C",   ← underlying journal ID (don't use)
             parentEntityResourceId: "A" }          ← matches CREATE response
-GET    → expects "B" (cashflow-transaction ID)
+GET    → accepts "B" (cashflow-transaction ID) or "A" (parentEntityResourceId)
 PUT    → expects "A" (parentEntityResourceId) — body needs resourceId: "A"
 DELETE → expects "A" (parentEntityResourceId, via /cash-entries/:id)
 ```

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

@@ -3,13 +3,13 @@
 > **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 454 paths / 381 operations and is the authoritative list; check it before concluding
+> carries 466 spec paths and 594 spec 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.
 >
 > **Paths below are written without the `/api/v1` prefix.** Every one of them is really
 > `/api/v1/<path>`. Recent additions not yet folded into the tables are listed at the end
-> under "2026-08 additions".
+> under "Additions since 2026-07-11".
 
 ---
 
@@ -48,9 +48,9 @@
 | DELETE | `/invoices/:resourceId` | Delete invoice |
 | GET | `/invoices/:resourceId/download` | Download PDF |
 | POST | `/invoices/:resourceId/payments` | Record payment(s) |
-| GET | `/invoices/:resourceId/payments` | List recorded payments — **raw array response** |
+| GET | `/invoices/:resourceId/payments` | List recorded payments (`{data: [...]}`) |
 | POST | `/invoices/:resourceId/credits` | Apply credit note(s) |
-| GET | `/invoices/:resourceId/credits` | List applied credits — **raw array response** |
+| GET | `/invoices/:resourceId/credits` | List applied credits (**bare `[]` when none applied**, else `{TotalElements, data}`) |
 | DELETE | `/invoices/:resourceId/credits/:creditsAppliedResourceId` | Reverse credit |
 | GET | `/invoices/:resourceId/attachments` | List attachments |
 | POST | `/invoices/:resourceId/attachments` | Upload attachment |
@@ -705,7 +705,7 @@ These features exist in the Jaz platform and may affect API responses or cause u
 - Bills and invoices can be submitted for approval workflow
 - Only admin users (AP permission) can approve submitted bills
 - API-created transactions with `saveAsDraft: false` bypass approval workflow
-- Approval records are read-only via API
+- Approve and request-changes are writable via API: `POST /{entity}/:resourceId/approve` + `bulk-approve` (invoices, bills, both credit notes; irreversible) and `request-changes` (endpoints.md sections 19c, 19d)
 
 ### Lock Dates
 - Organizations can set a lock date preventing changes before that cutoff
@@ -779,8 +779,8 @@ See endpoints.md section 25 for request/response shapes and the `refs` grammar (
 
 ## Additions since 2026-07-11
 
-Live routes added after the tables above were last regenerated. None has a `clio` subcommand
-or an MCP tool — call them with a raw request.
+Live routes added after the tables above were last regenerated. Unless a subsection names its
+wrapper, it has no `clio` subcommand or MCP tool: call it with a raw request.
 
 ### Request changes (18) — 2026-08-06
 
@@ -788,7 +788,8 @@ or an MCP tool — call them with a raw request.
 `invoices`, `bills`, `customer-credit-notes`, `supplier-credit-notes`, `purchase-orders`,
 `purchase-requests`, `sale-orders`, `sale-quotes`. Claims uses a different bulk shape:
 `POST /claims/:resourceId/request-changes` + `POST /claims/bulk/request-changes`.
-Bodies and per-record outcome semantics: endpoints.md section 19c.
+Bodies and per-record outcome semantics: endpoints.md section 19c. Wrapped by
+`request_document_changes` / `bulk_request_document_changes` and `clio approvals`.
 
 ### Payments, bulk and batch (9) — 2026-08-13
 

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 5.73.0
+version: 5.73.2
 description: >-
   Use this skill when running Clio CLI commands, building shell scripts with
   Clio, debugging auth issues, understanding --json output, paginating results,

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 5.73.0
+version: 5.73.2
 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.73.0
+version: 5.73.2
 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.73.0
+version: 5.73.2
 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.73.0
+version: 5.73.2
 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.73.0
+version: 5.73.2
 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

@@ -4,11 +4,11 @@ Jaz accounting guidance for this workspace. Load the installed Jaz skills for de
 
 ## Discovery
 
-Jaz exposes **381 tools across 46 namespaces**. Your tool list shows **3, 45, or 371** entries depending on packaging — **never infer capability from its length.**
+Jaz exposes **381 tools across 46 namespaces**. Your tool list shows **3, 46, or 381** 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.
-- **45** — namespace routers; call one with `{ operation, arguments }`. Its description lists its operations.
-- **371** — call operations directly by name.
+- **46** — namespace routers; call one with `{ operation, arguments }`. Its description lists its operations.
+- **381** — call operations directly by name.
 
 `describe_capabilities` returns the capability map on all three. **Call it before telling the user Jaz cannot do something.**