jaz-clio 4.49.1 → 4.50.1

package/README.md

@@ -51,7 +51,7 @@ clio search "overdue"                             # Find it across all entities
 
 ## MCP Server
 
-243 CLI tools, available to any AI agent that speaks MCP. Runs locally — no cloud, no ports.
+242 CLI tools, available to any AI agent that speaks MCP. Runs locally — no cloud, no ports.
 
 **Claude Code:**
 ```bash

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 4.49.1
+version: 4.50.1
 description: >-
   Use this skill whenever you call, debug, or review code that touches the Jaz
   REST API. Covers field names, response shapes, 117 production gotchas, error

package/assets/skills/api/references/search-enums.md

@@ -271,7 +271,7 @@ No enum fields. String filters only: `categoryCode`, `typeName`, `typeCode`, `re
 |-------|-------------|
 | `status` | `ACTIVE`, `INACTIVE` |
 | `subscriptionStatus` | `ACTIVE`, `CANCELLED`, `INACTIVE` |
-| `interval` | `ONE_TIME`, `DAILY`, `WEEKLY`, `MONTHLY`, `YEARLY` |
+| `interval` | `ONE_TIME`, `DAILY`, `WEEKLY`, `MONTHLY`, `QUARTERLY`, `YEARLY` |
 
 **Amount fields**: `totalAmount`, `paymentRecordedAmount`
 **Date fields**: `startDate`, `endDate`, `lastScheduleDate`, `nextScheduleDate`, `proratedStartDate`

package/assets/skills/api/references/search-reference.md

@@ -169,7 +169,7 @@ To convert response dates: `new Date(epochMs).toISOString().slice(0, 10)` → `Y
 | `contact` | ContactNestedFilter | Nested: name, resourceId, status, taxId |
 | `valueDate` | DateExpression | |
 | `dueDate` | DateExpression | |
-| `tags` | StringExpression | |
+| `tags` | Nested: `name` (StringExpression) | |
 | `currencyCode` | StringExpression | |
 | `approvalStatus` | StringExpression | |
 | `approvedAt` | DateExpression | |
@@ -206,7 +206,7 @@ To convert response dates: `new Date(epochMs).toISOString().slice(0, 10)` → `Y
 | `valueDate` | DateExpression | |
 | `dueDate` | DateExpression | |
 | `terms` | IntExpression | |
-| `tags` | StringExpression | |
+| `tags` | Nested: `name` (StringExpression) | |
 | `currencyCode` | StringExpression | |
 | `approvalStatus` | StringExpression | |
 | `submittedBy` | UserNestedFilter | |
@@ -239,7 +239,7 @@ To convert response dates: `new Date(epochMs).toISOString().slice(0, 10)` → `Y
 | `contactResourceId` | StringExpression |
 | `status` | StringExpression |
 | `reference` | StringExpression |
-| `tags` | StringExpression |
+| `tags` | Nested: `name` (StringExpression) |
 | `valueDate` | DateExpression |
 | `contact` | ContactNestedFilter |
 | `currencyCode` | StringExpression |
@@ -274,7 +274,7 @@ To convert response dates: `new Date(epochMs).toISOString().slice(0, 10)` → `Y
 | Field | Type | Notes |
 |-------|------|-------|
 | `resourceId` | StringExpression | |
-| `tags` | StringExpression | |
+| `tags` | Nested: `name` (StringExpression) | |
 | `reference` | StringExpression | |
 | `status` | StringExpression | |
 | `contact` | ContactNestedFilter | |
@@ -548,7 +548,7 @@ To convert response dates: `new Date(epochMs).toISOString().slice(0, 10)` → `Y
 | `disposalType` | StringExpression |
 | `typeName` | StringExpression |
 | `typeCode` | StringExpression |
-| `tags` | StringExpression |
+| `tags` | Nested: `name` (StringExpression) |
 | `status` | StringExpression |
 | `registrationType` | StringExpression |
 | `purchaseBusinessTransactionType` | StringExpression |

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 4.49.1
+version: 4.50.1
 description: >-
   Use this skill when running Clio CLI commands, building shell scripts with
   Clio, debugging auth issues, understanding --json output, paginating results,
@@ -26,6 +26,18 @@ You are working with **Clio** (`jaz-clio`) — the CLI for the Jaz accounting pl
 - Chaining multi-step accounting workflows (create -> finalize -> pay -> verify)
 - Answering "what commands are available?" or "how do I do X from the CLI?"
 
+## Skill Relationships
+
+| Need | Skill |
+|------|-------|
+| CLI command syntax, flags, output | **jaz-cli** (this skill) |
+| API field names, error codes, 117 gotchas | **jaz-api** |
+| IFRS transaction recipes (depreciation, leases, loans) | **jaz-recipes** |
+| Month-end close, bank recon, GST filing workflows | **jaz-jobs** |
+| Migration from Xero/QuickBooks/Sage | **jaz-conversion** |
+
+Use **jaz-cli** when running commands. Use **jaz-api** when debugging API errors or understanding field mappings.
+
 ## Auth Precedence
 
 Resolution stops at the first match. Higher priority wins silently.
@@ -93,6 +105,8 @@ clio journals create --account "Bank - SGD"     # Resolves by account name
 clio journals create --account "1000"           # Resolves by account code
 ```
 
+> **IMPORTANT for agents:** Fuzzy matching works for `--contact` and top-level `--account` flags. It does NOT work inside `--lines` JSON arrays. Line item `accountResourceId` must be a UUID or exact account name.
+
 ## Pagination
 
 All list/search commands support pagination. Two modes:
@@ -173,6 +187,8 @@ When `--input` or stdin provides a body, CLI flags are ignored.
 
 **Organization**: `org` (info), `org-users`, `auth`
 
+**Introspection**: `schema` (list groups, inspect tools, show params), `health` (version, connectivity, environment checks)
+
 **Utilities**: `help-center` (alias: `hc`), `context`, `mcp`, `serve`, `init`, `versions`, `update`
 
 See `references/command-catalog.md` for the full catalog with subcommands and flags.
@@ -259,6 +275,16 @@ clio ct loan --principal 100000 --rate 5 --term 60 --start-date 2026-01-01 \
 
 See `references/common-workflows.md` for end-to-end multi-command patterns.
 
+## Agent Gotchas (Top 5)
+
+1. **Create returns only {resourceId}.** Always `get` afterward for full data.
+2. **Line-item accounts don't fuzzy-resolve.** Use UUID or exact name.
+3. **Cash entries finalize immediately.** Unlike invoices which default to draft.
+4. **--offset is page number (0-indexed), not row count.**
+5. **JAZ_API_KEY env overrides --org.** Unset to use profiles.
+
+See [references/agent-gotchas.md](./references/agent-gotchas.md) for the full list of 15 gotchas. See [references/output-shapes.md](./references/output-shapes.md) for `--json` output structures. See [references/error-recovery.md](./references/error-recovery.md) for 30+ error patterns with fixes.
+
 ## See Also
 
 - **jaz-api** — Field names, endpoints, error codes, and 117 production gotchas

package/assets/skills/cli/references/agent-gotchas.md

@@ -0,0 +1,36 @@
+# Agent Gotchas
+
+> 15 critical gotchas for AI agents using the CLI. Learned from production testing.
+> Violating these causes silent data errors or wasted API calls.
+
+---
+
+1. **Cash entries finalize immediately.** `clio cash-in` and `clio cash-out` default to `saveAsDraft: false` (API default). Unlike invoices/bills/journals which the CLI overrides to draft. Use `--finalize` on invoices to finalize; cash entries are already final.
+
+2. **Line-item account resolution is NOT fuzzy.** The `accountResourceId` field inside `--lines` JSON arrays requires a UUID or exact account name. Fuzzy matching only works for top-level flags (`--contact`, `--account`). Always resolve accounts first: `clio accounts list --json | jq '.data[] | {name, id: .resourceId}'`.
+
+3. **Create responses are minimal.** All create commands return only `{ "resourceId": "uuid" }`. To get the full entity (status, amounts, line items), run `clio <entity> get <id> --json` afterward.
+
+4. **--offset is page number (0-indexed), not row skip count.** `--offset 0 --limit 100` = rows 1-100. `--offset 1 --limit 100` = rows 101-200. This is not the same as SQL OFFSET.
+
+5. **--all caps at 10,000 rows by default.** For large orgs, pass `--max-rows 50000` explicitly. The CLI auto-paginates with concurrent requests and shows progress on stderr.
+
+6. **JAZ_API_KEY env var overrides --org and active profile.** If set, all commands use that key regardless of `--org` or `clio auth switch`. Run `unset JAZ_API_KEY` to restore profile-based auth. Run `echo $JAZ_API_KEY` to check.
+
+7. **--json output goes to stdout; errors go to stderr.** Piping `clio invoices list --json | jq .` works cleanly. Resolution feedback ("Contact: Acme Corp (abc1234...)") is on stderr and won't corrupt JSON. Always parse stdout only.
+
+8. **Dates are YYYY-MM-DD in org-local timezone.** Not UTC, not epoch. The API stores dates without time component. `--date 2026-03-15` means March 15 in the org's configured timezone.
+
+9. **Currency codes are uppercase ISO 4217.** `SGD`, `USD`, `EUR` -- not `sgd`, `usd`. Lowercase will be rejected by the API with a validation error.
+
+10. **The `customer` and `supplier` fields on contacts are booleans.** `{ "customer": true, "supplier": false }` -- not strings. A contact can be both customer and supplier simultaneously.
+
+11. **Search returns results grouped by entity type, not a flat array.** `clio search "Acme" --json` returns `{ contacts: [...], sales: [...], purchases: [...], ... }`. Each key may be empty. Always access the specific entity key you need.
+
+12. **`clio schema` is for tool introspection, not data.** `clio schema --json` lists command groups and tool counts. `clio schema invoices --json` shows tool definitions. `clio schema invoices create --json` shows parameter schema. None of these hit the API.
+
+13. **Job blueprints output plain text by default.** `clio jobs month-end` prints a checklist. Add `--json` for structured output. Some job tools (`match`, `outstanding`, `sg-cs`) require auth; blueprint generators are offline.
+
+14. **Capsule-transaction recipes: always `--plan` first.** `clio ct loan --plan` shows what accounts and transactions will be created, offline. Only run without `--plan` when you know the account mapping is correct. Recipes create real finalized transactions.
+
+15. **The `--input` flag reads JSON from a file.** For complex payloads (multi-line-item invoices, detailed journals), write JSON to a temp file and pass `--input payload.json` instead of long `--lines` flags with shell escaping issues. When `--input` is provided, all other body flags are ignored.

package/assets/skills/cli/references/error-recovery.md

@@ -0,0 +1,112 @@
+# CLI Error Recovery Guide
+
+> 30+ error patterns with root cause and fix. Grouped by category.
+> CLI errors go to stderr. Exit codes: 0 = success, 1 = user error, 2 = API/network error, 3 = auth error.
+
+---
+
+## Auth Errors (Exit 3)
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `No API key configured` | No auth source found in resolution chain | `clio auth add jk-xxx` or `export JAZ_API_KEY=jk-xxx` |
+| `Invalid API key` | Key doesn't start with `jk-` or is malformed | Verify key format: must be `jk-` prefix + UUID |
+| `Unauthorized (401)` | Key expired, revoked, or wrong org | Run `clio auth whoami` to check; re-add key with `clio auth add` |
+| `--api-key and --org cannot be used together` | Conflicting auth flags | Use one or the other, not both |
+| `Profile 'xyz' not found` | `--org xyz` references non-existent profile | Run `clio auth list` to see available profiles |
+| `JAZ_API_KEY overrides --org` | Env var takes precedence silently | `unset JAZ_API_KEY` before using `--org` or `clio auth switch` |
+
+---
+
+## Entity Resolution Errors (Exit 1)
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Multiple contacts match 'Acme'` | Fuzzy match found 2+ candidates above threshold | Use exact billingName or UUID |
+| `Contact not found: 'xyz'` | No match in org's contact list | Run `clio contacts search xyz` to check spelling |
+| `Account not found: 'xyz'` | No matching account name or code | Run `clio accounts list --json` to see available accounts |
+| `Bank account not found` | Name doesn't match any bank-type account | Run `clio bank accounts --json` for exact names |
+| `Tax profile not found` | No match on tax profile name or code | Run `clio tax-profiles list --json` for available profiles |
+| `Multiple accounts match` | Ambiguous account name | Use account code (e.g., `1000`) or UUID instead |
+
+**Key rule**: Contact resolution is fuzzy. Account resolution in `--lines` JSON is NOT fuzzy -- use UUID or exact name.
+
+---
+
+## Validation Errors (Exit 1)
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `missing required option(s): --contact, --lines` | Required flag not provided | Add the missing flags |
+| `lineItems[0].accountResourceId is required` | Line item missing account (required for finalized) | Add accountResourceId to each line item |
+| `currency is required` | FX transaction without currency | Add `--currency SGD` (or target currency) |
+| `contactResourceId is required` | Transaction without contact | Add `--contact "Name"` or `--contact <uuid>` |
+| `valueDate is required` | Transaction without date | Add `--date YYYY-MM-DD` |
+| `journalEntries must have equal debits and credits` | Journal out of balance | Ensure DEBIT total equals CREDIT total |
+| `At least one line item is required` | Empty --lines array | Provide at least one line item object |
+| `Invalid date format` | Date not in YYYY-MM-DD | Use ISO format: `--date 2026-03-15` |
+| `unitPrice must be a number` | String passed for numeric field | Remove quotes from numeric values in JSON |
+| `Invalid status filter` | Wrong status value for entity type | Check valid statuses: DRAFT, APPROVED, PAID, VOIDED, DELETED |
+
+---
+
+## Pagination Errors (Exit 1)
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `--all and --offset cannot be combined` | Conflicting pagination modes | Use either `--all` or `--offset`, not both |
+| `offset must be >= 0` | Negative offset value | Offset is 0-indexed page number (0 = first page) |
+| `limit must be between 1 and 100` | Out-of-range page size | Max 100 per page; use `--all` for larger fetches |
+| `Result truncated (10000 row cap)` | `--all` hit default max-rows | Add `--max-rows 50000` to increase the cap |
+
+---
+
+## API / Network Errors (Exit 1 or 2)
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `ECONNREFUSED` | API server unreachable | Check network connection; verify API URL |
+| `ETIMEDOUT` | Request timed out | Retry; check for slow network or large payload |
+| `429 Too Many Requests` | Rate limited by API | Wait 30-60 seconds and retry |
+| `API error 422: ...` | Server-side validation failure | Read the error message -- it names the bad field |
+| `API error 400: ...` | Malformed request body | Check JSON syntax in `--lines` or `--input` |
+| `API error 404: ...` | Endpoint or resource not found | Verify resourceId exists; check command spelling |
+| `API error 500: ...` | Server-side error | Retry once; if persistent, check API status |
+
+---
+
+## File / Input Errors (Exit 1)
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `File not found: ./payload.json` | `--input` path doesn't exist | Check file path and working directory |
+| `Invalid JSON in input file` | Malformed JSON in `--input` file | Validate with `jq . payload.json` before passing |
+| `Unexpected token in JSON` | Bad JSON in `--lines` flag | Escape quotes properly; use single quotes around JSON |
+| `Bank file format not supported` | Unsupported statement format | Supported: CSV, OFX, QIF, XLS, XLSX |
+
+---
+
+## Recovery Patterns
+
+**Auth not working?** Systematic diagnosis:
+```bash
+clio auth whoami          # Check current auth source
+clio auth list            # See all saved profiles
+echo $JAZ_API_KEY         # Check for env override
+echo $JAZ_ORG             # Check for pinned org
+```
+
+**Entity not found?** Search before creating:
+```bash
+clio contacts search "partial name" --json | jq '.data[] | {name, resourceId}'
+clio accounts list --json | jq '.data[] | {name, code: .accountCode, id: .resourceId}'
+```
+
+**Create failed?** Check the draft first:
+```bash
+# Validate JSON offline
+echo '[{"name":"Item","quantity":1,"unitPrice":100}]' | jq .
+
+# Try without --finalize (less strict validation)
+clio invoices create --contact "Acme" --date 2026-01-15 --lines '[...]'
+```

package/assets/skills/cli/references/output-shapes.md

@@ -0,0 +1,181 @@
+# CLI Output Shapes
+
+> `--json` output shapes from real CLI runs. Use these for `jq` pipelines.
+
+---
+
+## List Commands (Paginated Envelope)
+
+```bash
+clio invoices list --json       # Any list command: invoices, contacts, bills, etc.
+```
+
+```json
+{
+  "totalElements": 7297,
+  "totalPages": 73,
+  "truncated": false,
+  "data": [{ "resourceId": "...", "reference": "INV-175", "status": "DRAFT", ... }]
+}
+```
+
+Optional when truncated: `"_meta": { "fetchedRows": 10000, "maxRows": 10000 }`
+
+**jq examples:**
+```bash
+clio invoices list --json | jq '.data[] | {ref: .reference, amount: .totalAmount, status}'
+clio contacts list --all --json | jq '[.data[].resourceId]'
+clio invoices list --all --json | jq '.truncated'
+```
+
+### Key fields by entity
+
+**Invoices/Bills**: reference, status, valueDate, dueDate, contactResourceId, terms, resourceId, isTaxVATApplicable, taxInclusion, lineItems, billFrom, contact, subTotal, totalShipping, totalVat, totalAmount, currencyCode, currencySymbol, taxCurrencyExchange
+
+**Contacts**: addresses, contactGroups, contactPeople, currencyCode, customer, jazMagicAutofill, name, billingName, organizationId, paymentDetail, resourceId, status, supplier, theyOwe, youOwe, createdAt
+
+**Journals**: reference, status, valueDate, resourceId, journalEntries, totalDebit, totalCredit, currencyCode
+
+---
+
+## Get Commands (Single Entity)
+
+Returns the full entity object directly (no envelope).
+
+```bash
+clio invoices get <id> --json   # → { resourceId, reference, status, ... }
+clio contacts get <id> --json   # → { resourceId, name, theyOwe, youOwe, ... }
+```
+
+**jq examples:**
+```bash
+clio invoices get "$ID" --json | jq '{status, totalAmount, reference}'
+clio contacts get "$ID" --json | jq '{name, theyOwe, youOwe}'
+```
+
+---
+
+## Create Commands (Minimal Response)
+
+All create commands return only `{ resourceId: string }`. Fetch full data afterward.
+
+```bash
+ID=$(clio invoices create --contact "Acme" --date 2026-01-15 --lines '[...]' --json | jq -r '.resourceId')
+clio invoices get "$ID" --json   # Now you have the full record
+```
+
+---
+
+## Search Command (Multi-Entity)
+
+Universal search returns results grouped by entity type.
+
+```bash
+clio search "Acme" --json
+```
+
+```json
+{
+  "contacts": [],
+  "sales": [],
+  "purchases": [],
+  "journals": [],
+  "credit_notes": [],
+  "sale_items": [],
+  "purchase_items": [],
+  "sale_credit_note_items": [],
+  "purchase_credit_note_items": [],
+  "supplier_notes": []
+}
+```
+
+**jq examples:**
+```bash
+clio search "Acme" --json | jq '.contacts[] | {name, resourceId}'
+clio search "laptop" --json | jq 'to_entries | map({key, count: (.value | length)})'
+```
+
+---
+
+## Calc Commands (Calculator Output)
+
+Offline calculators return structured results with an amortization schedule.
+
+```bash
+clio calc loan --principal 10000 --rate 5 --term 12 --json
+```
+
+```json
+{
+  "type": "loan",
+  "currency": null,
+  "inputs": { "principal": 10000, "annualRate": 5, "termMonths": 12, "startDate": null },
+  "monthlyPayment": 856.07,
+  "totalPayments": 10272.89,
+  "totalInterest": 272.89,
+  "totalPrincipal": 10000,
+  "schedule": [{ "period": 1, "date": "2025-02-01", "openingBalance": 10000, "payment": 856.07, "interest": 41.67, "principal": 814.40, "closingBalance": 9185.60, "journal": {...} }],
+  "blueprint": { ... }
+}
+```
+
+**jq examples:**
+```bash
+clio calc loan --principal 10000 --rate 5 --term 12 --json | jq '.monthlyPayment'
+clio calc loan --principal 10000 --rate 5 --term 12 --json | jq '.schedule[-1].closingBalance'
+```
+
+---
+
+## Health Command
+
+```bash
+clio health --json
+```
+
+```json
+{
+  "version": "4.50.0",
+  "checks": [
+    { "name": "CLI version", "status": "ok", "value": "4.50.0" },
+    { "name": "Node.js", "status": "ok", "value": "v24.6.0" },
+    { "name": "Auth", "status": "ok", "value": "global-sg-demo (Global SG Demo, SGD)", "detail": "connected" },
+    { "name": "API connection", "status": "ok", "value": "200 OK (142ms)" }
+  ],
+  "ok": true
+}
+```
+
+Each check has: `name`, `status` ("ok"/"warn"/"fail"), `value`, and optional `detail` (actionable hint).
+
+**jq examples:**
+```bash
+clio health --json | jq '.ok'
+clio health --json | jq '.checks[] | select(.status != "ok")'
+```
+
+---
+
+## Schema Command (Tool Introspection)
+
+```bash
+clio schema --json
+```
+
+```json
+{
+  "totalTools": 243,
+  "totalGroups": 39,
+  "groups": [
+    { "group": "invoices", "tools": 10, "read": 4, "write": 6, "cliCommand": "clio invoices" }
+  ]
+}
+```
+
+**jq examples:**
+```bash
+clio schema --json | jq '.groups[].group'
+clio schema --json | jq '.groups[] | select(.write > 0) | {group, write}'
+clio schema invoices --json              # Tool definitions for a group
+clio schema invoices create --json       # Parameter schema for a specific tool
+```

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 4.49.1
+version: 4.50.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/jobs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-jobs
-version: 4.49.1
+version: 4.50.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/transaction-recipes/SKILL.md

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