jaz-clio 5.5.2 → 5.6.0

package/README.md

@@ -54,7 +54,7 @@ clio practice create-engagement acme-pte-ltd --type monthly-close --period 2026-
 
 ## MCP Server
 
-284 CLI tools, available to any AI agent that speaks MCP. Runs locally — no cloud, no ports. Includes the v5.2.0 `practice_*` tools (init, onboard_client, list_clients, load_client, create_engagement, load_engagement) so an agent in Claude Desktop or Claude Code can scaffold and load client workspaces conversationally.
+285 CLI tools, available to any AI agent that speaks MCP. Runs locally — no cloud, no ports. Includes the v5.2.0 `practice_*` tools (init, onboard_client, list_clients, load_client, create_engagement, load_engagement) so an agent in Claude Desktop or Claude Code can scaffold and load client workspaces conversationally.
 
 **Claude Code:**
 ```bash

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 5.5.2
+version: 5.6.0
 description: >-
   Use this skill whenever you call, debug, or review code that touches the Jaz
   REST API. Covers field names, response shapes, 141 production gotchas, error
@@ -473,6 +473,8 @@ Bills, invoices, and credit notes share identical mandatory field specs. Adding
 
 154. **`rollback_capsule_recipe` on a non-recipe capsule** (a capsule created by the legacy `create_capsule` tool or imported, not by the recipe engine) returns 422 `RECIPE_ROLLBACK_JOB_NOT_FOUND` ("No CAPSULE_RECIPE job found for capsule X in organization Y — nothing to roll back"). Rollback only works on capsules whose lifecycle was managed by the recipe engine. For legacy capsules, use `delete_capsule` instead.
 
+155. **Pseudo-SQL schema is canonical — call `get_pseudo_sql_schema` before any query.** The response returns the live curated catalog (tables / columns / joins / functions) PLUS the canonical `jaz-pseudo-sql.md` skill body in `agentSkillsDoc.content`. Drop the `.md` body into context as the syntax-rules source; treat `tables[] / joins[] / functions[]` as the column-list source. **Cache contract:** the `version` field is a stable 16-char hex hash; within a session, cache by version and don't re-call unless you have reason to believe the schema changed (e.g. a fresh backend deploy mid-session). Don't re-fetch on a wall-clock timer (upstream is `private, no-cache, must-revalidate`). A static curated-schema snapshot used to ship with the `jaz-pseudo-sql` skill before v5.6.0; it was dropped because it was structurally guaranteed to drift. Never write a query from a memorized column list.
+
 ## Supporting Files
 
 For detailed reference, read these files in this skill directory:

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 5.5.2
+version: 5.6.0
 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.5.2
+version: 5.6.0
 description: >-
   Use this skill when migrating accounting data into Jaz — importing from Xero,
   QuickBooks, Sage, MYOB, or Excel exports. Covers the full conversion pipeline:

package/assets/skills/jaz-pseudo-sql/SKILL.md

@@ -1,14 +1,15 @@
 ---
 name: jaz-pseudo-sql
-version: 5.5.2
+version: 5.6.0
 description: >-
   Use this skill when answering ad-hoc data questions that aren't covered by
   download_export (canonical reports — anomaly, audit, aging, P&L, BS, GL,
   statement of account) or search_* tools (entity listings with structured
   filters). Pseudo-SQL is a read-only DSL against Jaz's curated reporting
   schema — single SELECT statement, ≤100 row sync preview or full async CSV
-  export. Tools: preview_pseudo_sql, export_pseudo_sql, get_pseudo_sql_export,
-  run_pseudo_sql_and_download.
+  export. Tools: get_pseudo_sql_schema (call FIRST — returns live catalog +
+  downloadable jaz-pseudo-sql.md skill body), preview_pseudo_sql,
+  export_pseudo_sql, get_pseudo_sql_export, run_pseudo_sql_and_download.
 license: MIT
 compatibility: Works with Claude Code, Claude Cowork, Claude.ai, and any agent that reads markdown. For canonical report types and the standard analytics surface, load the jaz-api skill alongside this one.
 ---
@@ -23,6 +24,14 @@ You are running ad-hoc data queries against the **curated reporting schema** in
 
 > **NOT a general-purpose database surface.** Curated schema only — no DML (DELETE/UPDATE/INSERT), no multi-statement input, no access to private columns. Validators reject anything that isn't a single SELECT against an allowed table. See `references/error-catalog.md` for the full error vocabulary.
 
+## Source of truth for the schema
+
+**Always call `get_pseudo_sql_schema` first.** The response returns the live curated catalog (~70 tables, 91 join edges, 47 functions) AND the canonical `jaz-pseudo-sql.md` skill body in `agentSkillsDoc.content`. That `.md` body is the authoritative syntax guide — drop it into your context and use it instead of any cached column list.
+
+The `version` field is a stable 16-char hex hash; cache by it. If you've already called the tool this session and the version is unchanged on a re-call, the schema and skill body are identical to your cached copy — no need to re-read.
+
+Don't write a pseudo-SQL query from memory. The catalog grows; column names change; the live schema is the only source you should trust.
+
 ## When NOT to use this skill
 
 | Use this instead | When |
@@ -35,6 +44,7 @@ You are running ad-hoc data queries against the **curated reporting schema** in
 
 ## Tool selection within pseudo-SQL
 
+- **`get_pseudo_sql_schema`** — call FIRST. Returns the live curated catalog (tables/columns/joins/functions) plus the canonical `jaz-pseudo-sql.md` skill body in `agentSkillsDoc.content`. Drop the `.md` body into context as the syntax guide. Use the response's `version` (16-char hex) as a session-stable cache key. Org-agnostic.
 - **`preview_pseudo_sql`** — sync, ≤100 rows. Use for any agent-loop question where you need to look at the data quickly.
 - **`export_pseudo_sql` + `get_pseudo_sql_export`** — async kickoff + polling. Use when you want explicit job control (manual retry, parallel jobs, polling at your own cadence) or when the result set is too big for preview's 100-row cap.
 - **`run_pseudo_sql_and_download`** — one-shot composite: kickoff + poll + fetch CSV. Use for "give me the file" flows. Default returns the CSV buffer; pass `downloadToFile=true` to write to `~/Downloads/`.
@@ -45,14 +55,14 @@ You are running ad-hoc data queries against the **curated reporting schema** in
 2. **Single statement.** `SELECT 1; SELECT 2;` → 422 `PSEUDOSQL_PARSE_ERROR` "only a single SELECT statement is allowed per query". A trailing semicolon on one statement is fine.
 3. **Must SELECT FROM at least one table.** `SELECT 1` (no FROM) → 422 `PSEUDOSQL_VALIDATION_ERROR`.
 4. **Max 16,384 characters.** Over → 422 `validation_error` "query must be a maximum of 16,384 characters in length". Note: this is the request-shape validator (different error_type from the SQL-engine validators).
-5. **Curated tables only.** Unknown table → 422 `PSEUDOSQL_VALIDATION_ERROR` "unknown table <name>" (lowercased in the error message). See `references/curated-schema.md` for the inventory.
+5. **Curated tables only.** Unknown table → 422 `PSEUDOSQL_VALIDATION_ERROR` "unknown table <name>" (lowercased in the error message). Call `get_pseudo_sql_schema` for the live inventory.
 6. **Preview cap is 100 rows.** `truncated:true` means "MORE rows matched than were returned in this preview" — NOT "you hit the cap". To interpret: compare `rowCount` against your `LIMIT` clause or the preview cap (100). If you need every row, switch to `export_pseudo_sql`.
 7. **Export `downloadUrl` is short-lived.** S3 pre-signed, ~15min expiry (`X-Amz-Expires=900`). Fetch immediately. If a fetch returns 403, call `get_pseudo_sql_export(jobId)` again for a fresh URL.
 8. **`Idempotency-Key` dedups server-side.** Same key + DIFFERENT query body returns the prior job's result (the server doesn't cross-check). `run_pseudo_sql_and_download` auto-keys from `sha256(query).slice(0,16)` so dedup is query-tied automatically. If you call `export_pseudo_sql` directly with a manual key, don't reuse it across different intents.
 
 ## Reference docs
 
-- **[Curated schema](references/curated-schema.md)** — table + column inventory with types (live-probed 2026-05-27).
+- **Schema inventory** — call `get_pseudo_sql_schema` (live, ~30 KB response with tables / joins / functions + the canonical `jaz-pseudo-sql.md` body for context).
 - **[Query patterns](references/query-patterns.md)** — example SELECTs by user intent (top customers, unpaid invoices, FX-exposed bills, etc.).
 - **[Error catalog](references/error-catalog.md)** — every observed error code + recovery action.
 
@@ -73,6 +83,3 @@ preview_pseudo_sql({
 → { data: { columns: [...], rows: [...], rowCount: 10, truncated: false } }
 ```
 
-## Future direction (v5.5.1+)
-
-A `get_pseudo_sql_schema` tool will replace the static `references/curated-schema.md` once the canonical schema endpoint is published (parallel workstream, not blocking this skill's v1).

package/assets/skills/jaz-pseudo-sql/references/error-catalog.md

@@ -29,7 +29,7 @@ Surfaces when the query is syntactically valid but semantically rejected — wro
 |---|---|---|
 | `only SELECT queries are supported` | DELETE / UPDATE / INSERT verb | Rewrite as SELECT. The DSL is read-only by design. |
 | `a query must SELECT FROM at least one table` | `SELECT 1` (constant-only) | Add `FROM <table>` from the curated set. |
-| `unknown table "<name>"` (note: lowercased) | Table not in curated schema | Check `curated-schema.md` for the inventory. Common typos: plural vs singular (`invoice` vs `invoices`), wrong case. |
+| `unknown table "<name>"` (note: lowercased) | Table not in curated schema | Call `get_pseudo_sql_schema` for the live inventory. Common typos: plural vs singular (`invoice` vs `invoices`), wrong case. |
 
 ## Export-specific terminal states
 

package/assets/skills/jaz-pseudo-sql/references/query-patterns.md

@@ -1,6 +1,6 @@
 # Query patterns by user intent
 
-Patterns vetted against the curated schema (see `curated-schema.md`). Each example uses `preview_pseudo_sql` for quick agent-loop questions; switch to `run_pseudo_sql_and_download` (or `export_pseudo_sql` + `get_pseudo_sql_export`) when you need the full result set as a CSV.
+Patterns vetted against the curated schema (call `get_pseudo_sql_schema` for the live inventory). Each example uses `preview_pseudo_sql` for quick agent-loop questions; switch to `run_pseudo_sql_and_download` (or `export_pseudo_sql` + `get_pseudo_sql_export`) when you need the full result set as a CSV.
 
 ---
 
@@ -84,7 +84,7 @@ ORDER BY balance DESC
 
 **"FX-exposed customer credit notes"**
 
-(`customer_credit_notes` table not yet column-confirmed; see `curated-schema.md` candidates list.)
+(`customer_credit_notes` table not yet column-confirmed; call `get_pseudo_sql_schema` and inspect its `tables[]` for the current column list.)
 
 ---
 

package/assets/skills/jobs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-jobs
-version: 5.5.2
+version: 5.6.0
 description: >-
   Use this skill for recurring accounting workflows — month/quarter/year-end
   close, bank reconciliation, GST/VAT filing, payment runs, credit control,

package/assets/skills/practice/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-practice
-version: 5.5.2
+version: 5.6.0
 description: >-
   Use this skill whenever an accounting practitioner is doing client work in
   Jaz — closing the books, filing GST, year-end statutory, onboarding a new

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

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