jaz-clio 5.72.0 → 5.73.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-380-blue?style=for-the-badge" alt="380 tools">
+  <img src="https://img.shields.io/badge/tools-381-blue?style=for-the-badge" alt="381 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>
 
-380 tools · 74 command groups · 7 skills · 13 calculators · 12 close playbooks · 159 field-tested API rules.
+381 tools · 76 command groups · 7 skills · 13 calculators · 12 close playbooks · 159 field-tested API rules.
 
 ```bash
 npm install -g jaz-clio
@@ -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)
 ```
 
-74 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
 
@@ -78,16 +107,16 @@ that ends up in a journal.
 
 ## MCP server
 
-380 tools for any AI agent that speaks MCP. Runs locally: no cloud, no ports.
+381 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.
 
-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.72.0
+version: 5.73.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

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

@@ -251,6 +251,28 @@ Name must be unique (422 if duplicate). Agent tools auto-guard with search-befor
 
 Key filters: `appliesToSale`, `appliesToPurchase`, `appliesToSaleCreditNote`, `appliesToPurchaseCreditNote` (all BooleanExpression). Use to avoid picking a sales-only profile for a bill.
 
+### POST /api/v1/filing-submissions/search
+
+Tax return filings (PH BIR forms such as 2550Q, SG GST F5): period, due date, tax payable, lifecycle and payment status. Read only. Tool: `search_filing_submissions`; CLI: `clio filing-submissions search`.
+
+```json
+// Request:
+{
+  "filter": {
+    "formType": { "eq": "2550Q" },
+    "periodYear": { "eq": 2026 },
+    "lifecycleStatus": { "in": ["READY_TO_FILE", "SENT_TO_CLIENT"] }
+  },
+  "sort": { "sortBy": ["filingDueDate"], "order": "ASC" },
+  "limit": 100, "offset": 0
+}
+```
+
+- Filter fields: `resourceId`, `organizationResourceId`, `formType`, `displayFilingGroupings`, `periodStartDate`, `periodEndDate`, `filingDueDate`, `periodType`, `periodYear`, `periodValue` (month 1-12 or quarter 1-4), `lifecycleStatus`, `paymentStatus`, `taxDueAmount`, `taxForm.categoryCode`, `taxType.categoryCode`, plus `and` / `or` / `andGroup` / `orGroup`. The filter decodes strictly: any other key is a 400.
+- Sort fields: `resourceId`, `createdAt`, `updatedAt`, `formType`, `periodType`, `periodYear`, `periodValue`, `periodStartDate`, `periodEndDate`, `filingDueDate`, `lifecycleStatus`, `taxDueAmount`. Default `createdAt` DESC. Sort is required when `offset` is set.
+- `limit` 1-1000, default 100. `offset` is treated as a 0-indexed PAGE number, the platform norm. Row vs page is NOT measured here: the orgs probed held 0 and 1 filings, and the handler passes `offset` through unchanged, which both page and row endpoints also do.
+- Rows carry `taxForm { formType, formName, categoryCode, ... }`, `periodType`, `periodYear`, `periodStartDate`, `periodEndDate`, `filingDueDate`, `taxDueAmount` (a decimal STRING, e.g. `"-659.11"`), `lifecycleStatus`, `paymentStatus`, `filingMode`.
+
 ### PUT /api/v1/cash-in-entries/:parentEntityResourceId
 
 ```json
@@ -262,6 +284,8 @@ Key filters: `appliesToSale`, `appliesToPurchase`, `appliesToSaleCreditNote`, `a
 
 Same pattern for `PUT /cash-out-entries/:id`. URL uses `parentEntityResourceId` (from CREATE response). `accountEntryResourceId` is optional — API auto-populates from existing journal entry.
 
+Measured 2026-09-24 (Global SG Demo): a reference-only PUT succeeds and keeps a taxed entry's tax. Any PUT carrying `internalNotes` returns **500**, on taxed and untaxed entries alike, and any PUT carrying `lines` on a taxed entry (or adding a tax profile to an untaxed one) returns **500**, with or without `saveAsDraft: false` / `taxInclusion`. A `lines` PUT on an untaxed entry succeeds. So a taxed cash entry's lines cannot currently be edited through the API: void it and create a new one.
+
 ---
 
 ## 4. Currencies
@@ -664,12 +688,29 @@ Bills and supplier credit notes support withholding tax per line item:
 **CRITICAL corrections from live testing**:
 - Each entry uses `amount` (number) + `type`: `"DEBIT"` or `"CREDIT"` (UPPERCASE strings)
 - Do NOT use `debit`/`credit` as separate number fields — that is WRONG
-- Do NOT include `currency` at top level — causes "Invalid request body"
+- Top-level `currency: { sourceCurrency, exchangeRate? }` IS accepted: it makes a foreign-currency journal
+  whose amounts are in `sourceCurrency` (verified 2026-09-24: `{sourceCurrency: "USD", exchangeRate: 0.75}`
+  created a draft reading back `currencyExchange.sourceCurrencyCode: USD`, `baseToSourceRate: 0.75`).
+- `PUT /journals/{id}` does NOT keep `taxVatApplicable` or `taxInclusion` when they are omitted:
+  `taxVatApplicable` falls to false, which strips every line's tax profile once lines are sent, and
+  `taxInclusion` is cleared. Measured 2026-09-24: an ACTIVE taxed journal edited with its own lines and a
+  note came back with no tax profile and VAT 0 (HTTP 200). Always restate both from a GET of the journal.
+  The Clio tools and CLI do this for you (`update_journal`, `bulk_update_journals`, `clio journals update`,
+  `clio journals draft finalize`).
 - Total DEBIT amounts MUST equal total CREDIT amounts
 - `contactResourceId` is a TOP-LEVEL field, NOT per entry. Probed 2026-09-02: an entry-level
   `contactResourceId` is silently discarded (an int there is accepted like any unknown key, while an
   int on `description` or `taxProfileResourceId` returns 400), and a real contact id on an entry does
   not appear on the created journal. Put it at the top level, where it does land.
+- Per-line `exchangeRate` (optional, number): the rate from the LINE's account currency to the
+  organization's base currency. This is the OPPOSITE direction to the journal's `currency.exchangeRate`
+  (base to source). Only a line posting to an account held in another currency takes one:
+  `exchangeRate: 0` is a 422, and a rate other than exactly 1 on a base-currency line is a 422. Honoured
+  by `POST /journals`, `POST /transfer-trial-balance` and `POST /reconciliations/manual-journal` (the
+  reconcile path applies it as sent and skips the base-currency check). `PUT /journals/{id}` validates it
+  but does not apply it, so an update cannot change a line's rate. Send the top-level `exchangeRate`
+  only: a nested line `currency: { exchangeRate }` spelling is accepted upstream but unpublished, and
+  sending both with different values is a 422.
 
 ---
 
@@ -1398,6 +1439,10 @@ Same but with `"bill"` wrapper instead of `"invoice"`.
 - Since `saveAsDraft: false`, every line item MUST have `accountResourceId`.
 - Response uses `interval` field (not `repeat`): `{ "status": "ACTIVE", "interval": "MONTHLY", ... }`
 
+**`PUT /scheduled/journals/{id}`** (measured 2026-09-24):
+- Every update must send `startDate` (422 `INVALID_VALUE_OF_START_DATE` otherwise) and the full `schedulerEntries` (422 `JOURNAL_SCHEDULER_ENTRIES_MISSING_ERROR` otherwise), even for a status or reference change.
+- `taxVatApplicable` and `taxInclusion` RESET when omitted. A taxed, tax-inclusive schedule updated with its own entries and no flags stored tax off, inclusion off, VAT 0; the same update with both flags kept its VAT. `GET /scheduled/journals/{id}` returns neither flag (nor line tax profiles), so the stored values cannot be read back: state both on every update of a taxed schedule. `update_scheduled_journal` sends `taxVatApplicable: true` when an entry carries a tax profile and refuses without `taxInclusion`.
+
 ---
 
 ## 16b. Subscriptions (Recurring Invoices with Auto-Proration)
@@ -2222,6 +2267,7 @@ Create opening balance entries for an organization. Used during onboarding to tr
 - Reference is auto-generated — do not include `reference` in the request body
 - Uses `journalEntries` (NOT `lines`) — same as regular journals
 - Debit/credit must balance (same as regular journals)
+- Per-line `exchangeRate` works as on `POST /journals` (line account currency to base, foreign-currency account lines only)
 - Creates a non-editable transfer journal visible in the general ledger
 
 ---

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 454 paths / 380 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.
 >

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 5.72.0
+version: 5.73.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
-  74 command groups and 380 tools, including employee-expense claims.
+  76 command groups and 381 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. 74 command groups, 13 calculators, 12 job blueprints, 380 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. 76 command groups, 13 calculators, 12 job blueprints, 381 tools. Also fully compatible with Juan Accounting (same API, same endpoints).
 
 ## When to Use This Skill
 

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

@@ -1,6 +1,6 @@
 # Clio Command Catalog
 
-Complete reference for all 74 command groups. Organized by domain.
+Complete reference for all 76 command groups. Organized by domain.
 
 ---
 
@@ -12,7 +12,7 @@ Complete reference for all 74 command groups. Organized by domain.
 | `list` | `--limit`, `--offset`, `--all`, `--format`, `--json` |
 | `get <id>` | `--json` |
 | `search` | `--reference`, `--contact-name`, `--status`, `--from`, `--to`, `--tag`, `--sort`, `--order` |
-| `create` | `--contact`, `--date`, `--due`, `--ref`, `--currency`, `--exchange-rate`, `--lines`, `--finalize`, `--input` |
+| `create` | `--contact`, `--date`, `--due`, `--ref` or `--auto-ref`, `--currency`, `--exchange-rate`, `--lines`, `--finalize`, `--input` |
 | `update <id>` | `--date`, `--due`, `--ref`, `--lines`, `--input` |
 | `delete <id>` | |
 | `pay <id>` | `--amount`, `--transaction-amount`, `--account`, `--method`, `--ref`, `--date` |
@@ -29,7 +29,7 @@ Complete reference for all 74 command groups. Organized by domain.
 | `list` | `--limit`, `--offset`, `--all`, `--format`, `--json` |
 | `get <id>` | `--json` |
 | `search` | `--reference`, `--contact-name`, `--status`, `--from`, `--to`, `--tag`, `--sort`, `--order` |
-| `create` | `--contact`, `--date`, `--due`, `--ref`, `--currency`, `--exchange-rate`, `--lines`, `--finalize`, `--input` |
+| `create` | `--contact`, `--date`, `--due`, `--ref` or `--auto-ref`, `--currency`, `--exchange-rate`, `--lines`, `--finalize`, `--input` |
 | `update <id>` | `--date`, `--due`, `--ref`, `--lines`, `--input` |
 | `delete <id>` | |
 | `pay <id>` | `--amount`, `--transaction-amount`, `--account`, `--method`, `--ref`, `--date` |
@@ -45,7 +45,7 @@ Complete reference for all 74 command groups. Organized by domain.
 | `list` | `--limit`, `--offset`, `--all`, `--format`, `--json` |
 | `get <id>` | `--json` |
 | `search` | `--reference`, `--contact-name`, `--status`, `--from`, `--to`, `--tag`, `--sort`, `--order` |
-| `create` | `--contact`, `--date`, `--ref`, `--currency`, `--exchange-rate`, `--lines`, `--finalize`, `--input` |
+| `create` | `--contact`, `--date`, `--ref` or `--auto-ref`, `--currency`, `--exchange-rate`, `--lines`, `--finalize`, `--input` |
 | `update <id>` | `--date`, `--ref`, `--lines`, `--input` |
 | `delete <id>` | |
 | `refund <id>` | `--amount`, `--account`, `--method`, `--ref`, `--date` |
@@ -60,7 +60,7 @@ Complete reference for all 74 command groups. Organized by domain.
 | `list` | `--limit`, `--offset`, `--all`, `--format`, `--json` |
 | `get <id>` | `--json` |
 | `search` | `--reference`, `--contact-name`, `--status`, `--from`, `--to`, `--tag`, `--sort`, `--order` |
-| `create` | `--contact`, `--date`, `--ref`, `--currency`, `--exchange-rate`, `--lines`, `--finalize`, `--input` |
+| `create` | `--contact`, `--date`, `--ref` or `--auto-ref`, `--currency`, `--exchange-rate`, `--lines`, `--finalize`, `--input` |
 | `update <id>` | `--date`, `--ref`, `--lines`, `--input` |
 | `delete <id>` | |
 | `refund <id>` | `--amount`, `--account`, `--method`, `--ref`, `--date` |
@@ -74,7 +74,7 @@ Complete reference for all 74 command groups. Organized by domain.
 | `list` | `--limit`, `--offset`, `--all`, `--format`, `--json` |
 | `get <id>` | `--json` |
 | `search` | `--reference`, `--from`, `--to`, `--status`, `--tag`, `--type`, `--sort`, `--order` |
-| `create` | `--date`, `--ref`, `--entries`, `--finalize`, `--input` |
+| `create` | `--date`, `--ref` or `--auto-ref`, `--entries` (a line may carry `exchangeRate`: account currency to base), `--finalize`, `--input` |
 | `update <id>` | `--date`, `--ref`, `--entries`, `--input` |
 | `delete <id>` | |
 | `transfer-trial-balance` (alias: `ttb`) | `--date`, `--entries`, `--input`, `--currency`, `--exchange-rate`, `--rate-direction` |
@@ -87,7 +87,7 @@ Complete reference for all 74 command groups. Organized by domain.
 | `list` | `--limit`, `--offset`, `--all`, `--format`, `--json` |
 | `get <id>` | `--json` |
 | `search` | `--ref`, `--from`, `--to`, `--status` |
-| `create` | `--account`, `--date`, `--ref`, `--entries`, `--input` |
+| `create` | `--account`, `--date`, `--ref` (generated when omitted), `--entries`, `--input` |
 | `update <id>` | `--date`, `--ref`, `--entries`, `--input` |
 | `delete <id>` | |
 
@@ -100,7 +100,7 @@ Same subcommands and flags as `cash-in`.
 | `list` | `--limit`, `--offset`, `--all`, `--format`, `--json` |
 | `get <id>` | `--json` |
 | `search` | `--ref`, `--from`, `--to`, `--status` |
-| `create` | `--from-account`, `--to-account`, `--amount`, `--date`, `--ref`, `--input` |
+| `create` | `--from-account`, `--to-account`, `--amount`, `--date`, `--ref` (generated when omitted), `--input` |
 | `delete <id>` | |
 
 ### `clio payments` — Cashflow transactions (read-only)
@@ -196,6 +196,11 @@ Same subcommands and flags as `cash-in`.
 | `types` | List available tax type codes |
 | `wht-codes` | List withholding tax codes |
 
+### `clio filing-submissions` — Tax return filings (read-only, 1 tool)
+| Subcommand | Key flags |
+|------------|-----------|
+| `search` | `--form-type`, `--lifecycle-status`, `--period-year`, `--due-from`, `--due-to`, `--filter` (any other filing filter field, e.g. `{"periodType":{"eq":"QUARTERLY"}}`), `--sort`, `--order`, `--limit`, `--offset`, `--all` |
+
 ### `clio custom-fields` — Custom field definitions
 | Subcommand | Key flags |
 |------------|-----------|
@@ -495,7 +500,7 @@ All seven of `--item-code`, `--name`, `--unit`, `--costing-method`, `--cogs-acco
 | `list-journals` | `--limit`, `--offset`, `--all`, `--format`, `--json` |
 | `create-invoice` | `--contact`, `--reference`, `--repeat`, `--start-date`, `--line-items`, `--input` |
 | `create-bill` | `--contact`, `--reference`, `--repeat`, `--start-date`, `--line-items`, `--input` |
-| `create-journal` | `--reference`, `--repeat`, `--start-date`, `--entries`, `--input` |
+| `create-journal` | `--reference` (generated when omitted), `--repeat`, `--start-date`, `--entries`, `--input` |
 
 Dynamic strings in schedulers: `{{Day}}`, `{{Date}}`, `{{Date+X}}`, `{{DateRange:X}}`, `{{Month}}`, `{{Month+X}}`, `{{MonthRange:X}}`, `{{Year}}`, `{{Year+X}}`
 
@@ -666,6 +671,11 @@ Batch create via `--input` file or stdin (`{ "entries": [...] }`, 1-100 per call
 |------------|-----------|
 | `info` | `--json` (shows name, ID, currency, country, lock date, fiscal year) |
 
+### `clio references` — Document numbering series
+| Subcommand | Key flags |
+|------------|-----------|
+| `next` | `--type` (SALE, SALE_CREDIT_NOTE, PURCHASE, PURCHASE_CREDIT_NOTE, FIXED_ASSET, JOURNAL_MANUAL, SALE_QUOTE, SALE_ORDER, PURCHASE_REQUEST, PURCHASE_ORDER, CLAIM), `--json`. Reading does not reserve the number; to number a create, pass the create command its own auto-ref flag |
+
 ### `clio org-users` — User management
 | Subcommand | Key flags |
 |------------|-----------|
@@ -722,7 +732,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 380 operations.
+Starts an MCP server for Claude Code / AI tool integration. Exposes all 381 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.72.0
+version: 5.73.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.72.0
+version: 5.73.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.72.0
+version: 5.73.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.72.0
+version: 5.73.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/gst-vat-filing.md

@@ -12,6 +12,7 @@
 - **`quick_fix_line_items(entity: 'invoices' | 'bills', lineItemResourceIds, attributes)`** — step 5 corrections: re-assign the tax profile on the affected lines if errors are found. The tax profile sits on each line, so the fix is at line level.
 - **`download_export(exportType: 'analysis-exchange-rate-audit', startDate, endDate)`** — step 6 pre-filing check: FX rates outside expected band can shift GST on FX invoices.
 - **`generate_trial_balance(endDate: <period-end>)`** — step 7 GST account reconciliation: `GST Control` / `Input Tax Recoverable` / `Output Tax Payable` accounts.
+- **`search_filing_submissions(periodYear: <year>, sortBy: 'filingDueDate', sortOrder: 'ASC')`**: the filings already on record for the organization (PH BIR forms such as 2550Q, and SG GST F5): period, due date, tax due, lifecycle and payment status. Use it before step 8 to see whether the quarter was already filed or is awaiting the client. Read only; add `formType: '2550Q'` to narrow. CLI: `clio filing-submissions search --period-year <year>`.
 
 ### Cross-references
 - Org inputs this job needs (confirm with the user when not already on file): the GST scheme, the GST registration number, and the country code (`SG` | `PH`).

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

@@ -1,6 +1,6 @@
 ---
 name: jaz-recipes
-version: 5.72.0
+version: 5.73.1
 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 **380 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.**