jaz-clio 5.61.2 → 5.62.0

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 5.61.2
+version: 5.62.0
 description: >-
   Use this skill whenever you call, debug, or review code that touches the Jaz
   REST API. Covers field names, response shapes, 159 production gotchas, error
@@ -148,7 +148,7 @@ The rest of this skill — field names, gotchas, error catalog, dependency order
 | Trial balance | `startDate`, `endDate` |
 | Balance sheet | `primarySnapshotDate` |
 | P&L | `primarySnapshotDate`, `secondarySnapshotDate` |
-| General ledger | `startDate`, `endDate`, `groupBy: "ACCOUNT"` (also `CONTACT`, `TRANSACTION`, `RELATIONSHIP`) |
+| General ledger | `startDate`, `endDate`, `groupBy: "ACCOUNT"` (also `CONTACT`, `TRANSACTION`, `RELATIONSHIP`, `CAPSULE`). Optional `limit` (1-1000; omitted = whole report in one response), `offset` (ROW offset, see Rule 38), `filter.account.resourceId: { in: [...] }` |
 | Cashflow | `primaryStartDate`, `primaryEndDate` |
 | Cash balance | `reportDate` |
 | AR/AP report | `endDate` |
@@ -161,7 +161,7 @@ The rest of this skill — field names, gotchas, error catalog, dependency order
 37a. **Data exports use simpler field names**: P&L export uses `startDate`/`endDate` (NOT `primarySnapshotDate`). AR/AP export uses `endDate`.
 
 ### Pagination
-38. **All list/search endpoints use `limit`/`offset` pagination** — NOT `page`/`size`. **`offset` is a 0-indexed PAGE NUMBER, not a row-skip** (offset=1 = second page of `limit` rows). Default limit=100, offset=0. Max limit=1000, max offset=65536. `page`/`size` params are silently ignored. Response shape: `{ totalPages, totalElements, truncated, data: [...] }`. When `truncated: true`, a `_meta: { fetchedRows, maxRows }` field explains why (offset cap or `--max-rows` soft cap — default 10,000). Use `--max-rows <n>` to override. Always check `truncated` before assuming the full dataset was returned. **Payload tier (`view`) — page-then-drill:** `search_*` and the lean `list_*` tools (invoices, bills, contacts, items, journals, customer/supplier credit notes, sale/purchase orders) return a **compact summary row by default** (`view:"lean"` — id + reference/status/date/contact/amount). Search lean to FIND a record, then read it in full via its `get_*`; pass `view:"full"` only when you need whole rows up front (heavier — avoid for broad searches). Other collections always return full. CLI defaults to full; use `--view lean`.
+38. **All list/search endpoints use `limit`/`offset` pagination**: NOT `page`/`size`. **`offset` is a 0-indexed PAGE NUMBER, not a row-skip** (offset=1 = second page of `limit` rows). **Exceptions, where `offset` is a 0-indexed ROW offset (next page = offset + limit):** `POST /generate-reports/general-ledger` and `templated-general-ledger`, the AR/AP details reports (`ar-details-report`, `ap-details-report`, `templated-ar-details-report`, `templated-ap-details-report`), `/purchase-items` (list and search), `GET /organization/currencies/{code}/rates`, and `POST /employees/payouts/search`. Paging one of these by page number re-reads overlapping rows and skips the rest. Default limit=100, offset=0. Max limit=1000, max offset=65536. `page`/`size` params are silently ignored. Response shape: `{ totalPages, totalElements, truncated, data: [...] }`. When `truncated: true`, a `_meta: { fetchedRows, maxRows }` field explains why (offset cap or `--max-rows` soft cap: default 10,000). Use `--max-rows <n>` to override. Always check `truncated` before assuming the full dataset was returned. **Payload tier (`view`): page-then-drill:** `search_*` and the lean `list_*` tools (invoices, bills, contacts, items, journals, customer/supplier credit notes, sale/purchase orders) return a **compact summary row by default** (`view:"lean"`: id + reference/status/date/contact/amount). Search lean to FIND a record, then read it in full via its `get_*`; pass `view:"full"` only when you need whole rows up front (heavier: avoid for broad searches). Other collections always return full. CLI defaults to full; use `--view lean`.
 
 ### Other
 39. **Currency rates use `/organization/currencies/:code/rates`** — enable currencies first via `POST /organization/currencies`, then set rates via `POST /organization/currencies/:code/rates` with body `{ "rate": 0.74, "rateApplicableFrom": "YYYY-MM-DD" }` (see Rule 49 for direction). The older hyphenated `/organization-currencies/...` rate paths still resolve but are **superseded**: treat the nested form as the only supported path. The reference is migrating away from the hyphenated form, so do not rely on it being documented. Cannot set rates for org base currency. Full CRUD: POST (create), GET (list), GET/:id, PUT/:id, DELETE/:id.
@@ -178,7 +178,7 @@ The rest of this skill — field names, gotchas, error catalog, dependency order
 49. **Currency rate direction: `rate` = functionalToSource (1 base = X foreign)** — POST `rate: 0.74` for a SGD org means 1 SGD = 0.74 USD. **If your data stores rates as "1 USD = 1.35 SGD" (sourceToFunctional), you MUST invert: `rate = 1 / 1.35 = 0.74`.** GET confirms both: `rateFunctionalToSource` (what you POSTed) and `rateSourceToFunctional` (the inverse). **You do not have to do the arithmetic**: `add_currency_rate`, `update_currency_rate` and the `currency` object on the 8 FX create tools (invoice, bill, journal, both credit notes, both cash entries, TTB) accept an optional `rateDirection` (`FUNCTIONAL_TO_SOURCE` | `SOURCE_TO_FUNCTIONAL`) — declare how your figure reads and pass it verbatim. Omitting it always means `FUNCTIONAL_TO_SOURCE`. The two families differ only in where the label is applied: the rate-table tools (plus `bulk_upsert_currency_rates`) send it on the wire and the server applies it, while the 8 FX create tools have no such field, so the client inverts and strips it there. Prefer either to inverting by hand: a wrong inversion is silent and wrong by rate². `clio calc fx-reval` REQUIRES the direction — that calculator historically assumed the opposite convention to the API.
 
 ### Search & Filter
-50. **Search endpoint universal pattern** — All 32 `POST /*/search` endpoints share identical structure: `{ filter?, sort: { sortBy: ["field"], order: "ASC"|"DESC" }, limit: 1-1000, offset: 0-65536 }`. `offset` is a 0-indexed page number (not row-skip). Sort is REQUIRED when offset is present (even `offset: 0`). Default limit: 100. `sortBy` is always an array on all endpoints (no exceptions). See `references/search-reference.md` for per-endpoint filter/sort fields.
+50. **Search endpoint universal pattern**: All 32 `POST /*/search` endpoints share identical structure: `{ filter?, sort: { sortBy: ["field"], order: "ASC"|"DESC" }, limit: 1-1000, offset: 0-65536 }`. `offset` is a 0-indexed page number (not row-skip), except on the row-offset endpoints listed in Rule 38. Sort is REQUIRED when offset is present (even `offset: 0`). Default limit: 100. `sortBy` is always an array on all endpoints (no exceptions). See `references/search-reference.md` for per-endpoint filter/sort fields.
 50a. **`query` field — Jaz search operators** — 14 endpoints accept an optional `query` string alongside `filter`: invoices, bills, customer/supplier credit notes, journals, cashflow-transactions, bank-records, contacts, items, capsules, fixed-assets, scheduled-transactions, chart-of-accounts, tax-profiles. Example: `{ "query": "status:unpaid AND $500+", "limit": 50 }`. Key syntax: amounts (`$500+`, `$100-500`, `amount:>2m`, magnitude suffixes `5k`/`2m`/`1b`), negative (`$-500`), absolute value (`abs:1000+`), dates (`date:this month`, `date:-30d`, `due:overdue`, `submitted:last week`, `lastpayment:-7d`), status/enum (`status:unpaid`, `currency:SGD,USD` — comma = OR), string fields (`customer:acme`, `ref:INV-*` wildcard, `=ref:INV-001` exact, `ref:/\d{4}/` regex), blank checks (`ref:blank`, `tag:!blank`), booleans (`hasattachment:yes`, `customer:yes`), negation (`!status:paid` or `NOT status:void` — **never `-`** for negation), logic (`AND`/`OR` with implicit AND on space), grouping, inline sort (`sort:amount:desc`). Full syntax spec (all fields, aliases, entity field lists, examples): **`references/search-syntax.md`**.
 50b. **`query` + `filter` merge** — When both are present, they are merged at the filter level. Explicit `filter` keys win on conflict. Use `query` for human-readable shorthand, `filter` for programmatic precision, or combine both: `{ "query": "date:this year", "filter": { "currencyCode": { "in": ["SGD"] } } }`.
 50c. **`query` error handling** — Unknown field name → `query_not_understood` (400). Bad enum value (e.g. `status:BADVALUE`) → **empty results, no error** (silent miss). Unsupported endpoint → `query_not_supported` (400). Parser unavailable → `query_parse_error` (502). Empty/null/whitespace query → passthrough (ignored). In CLI/MCP: use `--query` / `query` param only on supported entities — unsupported entities have no `--query` flag.

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

@@ -35,6 +35,10 @@ All GET list endpoints and POST `/search` endpoints use **`limit`/`offset` pagin
 
 **IMPORTANT: `offset` is a page number (0-indexed), NOT a row-skip count.** `offset=0` returns the first page, `offset=1` returns the second page, etc. Example: `offset=2, limit=50` returns items 100–149.
 
+**Exceptions, where `offset` is a 0-indexed ROW offset (next page = offset + limit):** `POST /generate-reports/general-ledger` and `templated-general-ledger`, the AR/AP details reports (`ar-details-report`, `ap-details-report`, `templated-ar-details-report`, `templated-ap-details-report`), `/purchase-items` (list and search), `GET /organization/currencies/{code}/rates`, and `POST /employees/payouts/search`. There, `offset=2, limit=50` returns items 2-51.
+
+Paging one of these by page number reads overlapping windows: duplicates in, the rest never reached, while `totalElements` still looks right.
+
 | Property | Value |
 |----------|-------|
 | **GET list endpoints** | `?limit=100&offset=0` (query params) |
@@ -1486,10 +1490,15 @@ Both `primarySnapshotDate` and `secondarySnapshotDate` required. NOT `startDate`
 
 ```json
 // Request:
-{ "startDate": "2026-01-01", "endDate": "2026-02-28", "groupBy": "ACCOUNT" }
+{ "startDate": "2026-01-01", "endDate": "2026-02-28", "groupBy": "ACCOUNT", "limit": 200, "offset": 0,
+  "filter": { "account": { "resourceId": { "in": ["<accountResourceId>"] } } } }
 ```
 
-`groupBy` is required. Valid values: `"ACCOUNT"`. Uses `startDate`/`endDate` like trial balance.
+`groupBy` is required. Valid values: `"ACCOUNT"`, `"CONTACT"`, `"TRANSACTION"`, `"RELATIONSHIP"`, `"CAPSULE"`. Uses `startDate`/`endDate` like trial balance.
+
+**Paging**: `limit` 1-1000; **omit it and the whole report comes back in one response** (630 rows is ~628KB). `offset` is a 0-indexed **ROW** offset, not a page number: the next page is `offset + limit`. Max offset 65536; past that, narrow the dates. Rows sit under `data.searchGeneralLedgersReport.data`, with `totalElements` and `totalPages` beside them.
+
+**Filter**: `filter.account.resourceId` (StringExpression, e.g. `{ "in": [...] }`, max 100) narrows to accounts; `filter.account.accountType`, `contactResourceId.name`, `businessTransactionType`, `businessTransactionReference`, `description`, `tags` and the amount expressions are also accepted.
 
 ### POST /api/v1/generate-reports/cashflow
 
@@ -1718,7 +1727,7 @@ POST /api/v1/invoices/search
 
 ### Pagination
 - `limit`: max 1000 per page (default 100)
-- `offset`: page number, 0-indexed (max 65536)
+- `offset`: page number, 0-indexed (max 65536); a ROW offset on the exceptions listed under "Pagination (All List Endpoints)"
 - `sort`: **REQUIRED when `offset` is present** (even `offset: 0`)
 - Response includes `totalElements` and `totalPages`
 

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

@@ -765,7 +765,7 @@ The same applies on update: `PUT /cash-in-entries/:id` with `saveAsDraft: true`
 
 ### "limit must be 1000 or less" (422)
 **Cause**: Sending `?limit=1001` or higher on a GET endpoint.
-**Fix**: Maximum limit is 1000. To fetch all records, paginate with `limit=1000&offset=0`, then `limit=1000&offset=1` (offset is a page number, not row-skip), etc.
+**Fix**: Maximum limit is 1000. To fetch all records, paginate with `limit=1000&offset=0`, then `limit=1000&offset=1` (offset is a page number, not row-skip), etc. On the row-offset endpoints the second page is `offset=1000` instead. Exceptions, where `offset` is a 0-indexed ROW offset (next page = offset + limit): `POST /generate-reports/general-ledger` and `templated-general-ledger`, the AR/AP details reports (`ar-details-report`, `ap-details-report`, `templated-ar-details-report`, `templated-ap-details-report`), `/purchase-items` (list and search), `GET /organization/currencies/{code}/rates`, and `POST /employees/payouts/search`.
 
 ### "offset must be 65536 or less" (422)
 **Cause**: Offset exceeds maximum.

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

@@ -581,9 +581,9 @@ DELETE → expects "A" (parentEntityResourceId, via /cash-entries/:id)
 | `size` | NOT SUPPORTED | Silently ignored — use `limit`/`offset` |
 | `pageSize` | NOT SUPPORTED | Use `limit` |
 | `per_page` | NOT SUPPORTED | Use `limit` |
-| `page_number` | `offset` | **offset IS the page number (0-indexed)**, not a row-skip count. `offset=0` = page 1, `offset=1` = page 2. |
+| `page_number` / (page number) | `offset` (default: 0) | **offset IS the page number (0-indexed)**, not a row-skip count. `offset=0` = page 1, `offset=1` = page 2; `offset=2, limit=50` returns items 100–149. |
 | (default page size) | `limit` (default: 100) | Query param for GET, JSON body for POST /search |
-| (page number) | `offset` (default: 0) | 0-indexed page number. `offset=2, limit=50` returns items 100–149. |
+| (row offset) | `offset` on the exceptions only | Exceptions, where `offset` is a 0-indexed ROW offset (next page = offset + limit): `POST /generate-reports/general-ledger` and `templated-general-ledger`, the AR/AP details reports (`ar-details-report`, `ap-details-report`, `templated-ar-details-report`, `templated-ap-details-report`), `/purchase-items` (list and search), `GET /organization/currencies/{code}/rates`, and `POST /employees/payouts/search`. |
 
 **GET list endpoints**: `?limit=100&offset=0` (query params)
 **POST /search endpoints**: `{ "limit": 100, "offset": 0 }` (JSON body)

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

@@ -645,7 +645,7 @@ All 28 `POST /*/search` endpoints accept this filter structure in the POST body:
 
 ### Pagination
 
-See `endpoints.md` § "Pagination (All List Endpoints)" for the full spec (limit/offset semantics, defaults, constraints, sort requirement, examples). Key points: `offset` is a 0-indexed page number (not row-skip), default limit=100, max 1000, sort required on POST /search when offset is present. Exception: `GET organization-report-template` returns rows under a `reportTemplates` key with no counts (its /search is conventional); the tools normalize it to the standard envelope.
+See `endpoints.md` § "Pagination (All List Endpoints)" for the full spec (limit/offset semantics, defaults, constraints, sort requirement, examples). Key points: `offset` is a 0-indexed page number (not row-skip); Exceptions, where `offset` is a 0-indexed ROW offset (next page = offset + limit): `POST /generate-reports/general-ledger` and `templated-general-ledger`, the AR/AP details reports (`ar-details-report`, `ap-details-report`, `templated-ar-details-report`, `templated-ap-details-report`), `/purchase-items` (list and search), `GET /organization/currencies/{code}/rates`, and `POST /employees/payouts/search`. Default limit=100, max 1000, sort required on POST /search when offset is present. Exception: `GET organization-report-template` returns rows under a `reportTemplates` key with no counts (its /search is conventional); the tools normalize it to the standard envelope.
 
 ### Date Format Asymmetry (CRITICAL)
 

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

@@ -24,7 +24,7 @@ All search endpoints share this identical structure:
 | `filter` | object | No | Per-endpoint fields (see tables below) |
 | `sort` | object | **Yes if `offset` is present** | `sortBy`: array of field names; `order`: `"ASC"` or `"DESC"` |
 | `limit` | int | No | Default: 100, min: 1, max: 1000 |
-| `offset` | int | No | **Page number** (0-indexed, not row-skip). Default: 0, min: 0, max: 65536 |
+| `offset` | int | No | **Page number** (0-indexed, not row-skip). Default: 0, min: 0, max: 65536. Exceptions, where `offset` is a 0-indexed ROW offset (next page = offset + limit): `POST /generate-reports/general-ledger` and `templated-general-ledger`, the AR/AP details reports (`ar-details-report`, `ap-details-report`, `templated-ar-details-report`, `templated-ap-details-report`), `/purchase-items` (list and search), `GET /organization/currencies/{code}/rates`, and `POST /employees/payouts/search`. |
 
 **Response shape**: `{ totalElements, totalPages, data: [...] }` — all search/list endpoints return this flat structure directly (no outer `data` wrapper).
 

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

@@ -52,7 +52,7 @@ Space between conditions = AND (implicit). AND binds tighter than OR. Parenthese
 
 ## Amount Search
 
-Prefix with any currency symbol or type a numeric range.
+Prefix with any currency symbol, or use the `amount:` field. A number with no symbol or field key is plain text.
 
 | Input | Meaning |
 |-------|---------|
@@ -68,9 +68,9 @@ Prefix with any currency symbol or type a numeric range.
 | `$500+` | amount >= 500 |
 | `$<200` | amount < 200 |
 | `$>=1000` | amount >= 1000 |
-| `100-500` | amount range (no symbol needed for ranges) |
-| `>500` | amount > 500 (no symbol needed for comparisons) |
-| `500+` | amount >= 500 (no symbol needed) |
+| `$100-500` | amount range |
+| `$>500` | amount > 500 |
+| `$500+` | amount >= 500 |
 
 ### Magnitude Suffixes
 
@@ -104,7 +104,7 @@ Supported currency symbols: `$` `€` `£` `¥` `₱` `₹` `₩` `฿` `₫` `
 
 Also works with ISO codes: `SGD500`, `PHP1000`, `EUR200-500`
 
-A bare number like `500` searches all text fields (reference, ID, etc.). Add `$` or use range/comparison syntax to search amounts specifically.
+A bare number like `500` — and any keyless expression like `100-500`, `>500`, or `5k` — searches all text fields (reference, ID, etc.). Add `$` or use `amount:` to search amounts specifically.
 
 ---
 
@@ -448,6 +448,9 @@ Aliases: `reference:` = `ref:`, `valuedate:` = `date:`
 
 Aliases: `reference:` = `ref:`, `customer:` / `supplier:` = `contact:`, `total:` = `amount:`, `valuedate:` = `date:`
 
+### Deposit Transactions
+`contact` `ref` `date` `amount` `currency`
+
 ### Bank Accounts
 `name` `code` `status` `currency` `id` `balance`
 
@@ -493,31 +496,31 @@ Aliases: `bttype:` = `type:`, `documenttype:` = `doctype:`, `workflowstatus:` =
 `id` `ref` `date` `due` `approved` `currency` `amount` `customer` `regid` `taxid` `tag` `created` `status` `customfields`
 
 ### Sale Order Line Items
-`id` `name` `currency` `amount` `customer` `status` `ref` `date`
+`id` `name` `currency` `amount` `customer` `status` `ref` `date` `createdby` `createdat`
 
 ### Sale Quotes
 `id` `ref` `date` `due` `currency` `amount` `customer` `regid` `taxid` `tag` `created` `status` `customfields` `signing` `changesrequested`
 
 ### Sale Quote Line Items
-`id` `name` `currency` `amount` `customer` `status` `ref` `date`
+`id` `name` `currency` `amount` `customer` `status` `ref` `date` `createdby` `createdat`
 
 ### Purchase Orders
 `id` `ref` `date` `due` `approved` `currency` `amount` `supplier` `regid` `taxid` `tag` `created` `status` `customfields`
 
 ### Purchase Order Line Items
-`id` `name` `currency` `amount` `supplier` `status` `ref` `date`
+`id` `name` `currency` `amount` `supplier` `status` `ref` `date` `createdby` `createdat`
 
 ### Purchase Requests
 `id` `ref` `date` `due` `currency` `amount` `supplier` `regid` `taxid` `tag` `created` `status` `customfields` `signing` `changesrequested`
 
 ### Purchase Request Line Items
-`id` `name` `currency` `amount` `supplier` `status` `ref` `date`
+`id` `name` `currency` `amount` `supplier` `status` `ref` `date` `createdby` `createdat`
 
 ### Employees / Directory
 `id` `name` `email` `phone` `currency` `employmenttype` `beneficiary` `paymentmethod` `manager` `claimprofile` `created` `updated`
 
 ### Employees / Claims
-`id` `ref` `currency` `date` `created` `amount` `employee` `vendor` `customfields` `hasattachment` `createdby` `changesrequested`
+`id` `ref` `currency` `date` `created` `amount` `employee` `vendor` `customfields` `hasattachment` `createdby` `changesrequested` `tags`
 
 ### Employees / Payouts
 `employee` `ref` `type` `valuedate`

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 5.61.2
+version: 5.62.0
 description: >-
   Use this skill when running Clio CLI commands, building shell scripts with
   Clio, debugging auth issues, understanding --json output, paginating results,
@@ -400,7 +400,7 @@ See `references/common-workflows.md` for end-to-end multi-command patterns.
 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.**
+4. **--offset is page number (0-indexed), not row count.** Exceptions, where `--offset` is a ROW offset (next page = offset + limit): `purchase-items list/search`, `currency-rates list`, `claims payouts` and `reports generate general-ledger`. Each command's `--offset` help says which it is, and `--all` pages both kinds correctly.
 5. **Explicit organization selection wins.** `--org` uses the selected OAuth organization or saved key profile even when `JAZ_API_KEY` is set.
 
 See [references/agent-gotchas.md](./references/agent-gotchas.md) for the full list of 19 critical 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.

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

@@ -11,7 +11,7 @@
 
 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.
+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. Exceptions, where `--offset` is a ROW offset (next page = offset + limit): `purchase-items list/search`, `currency-rates list`, `claims payouts` and `reports generate general-ledger`. Each command's `--offset` help says which it is, and `--all` pages both kinds correctly.
 
 5. **--all caps at 1,000 rows by default** (lowered from 10,000 in 2026-04). For large orgs, pass `--max-rows 50000` explicitly. The CLI auto-paginates with concurrent requests and **stops fetching once `--max-rows` is reached** (early-stop, not slice-after — the previous behavior would pull every page and discard the excess, causing minute-long hangs on busy sandboxes).
 

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

@@ -515,8 +515,11 @@ Types: `trial-balance`, `balance-sheet`, `profit-loss`, `cashflow`, `aged-ar`, `
 | `--from` | Start date (P&L, cashflow, equity, recon) |
 | `--to` | End/snapshot date |
 | `--currency` | Currency code override |
-| `--group-by` | GL: ACCOUNT, CONTACT, TRANSACTION, RELATIONSHIP · FA summary: ACCOUNT, TYPE, CATEGORY, STATUS |
+| `--group-by` | GL: ACCOUNT, CONTACT, TRANSACTION, RELATIONSHIP, CAPSULE · FA summary: ACCOUNT, TYPE, CATEGORY, STATUS |
 | `--bank-account` | Bank account ID (for bank-recon-*) |
+| `--limit` / `--offset` | GL only: rows per response (1-1000; omitted = whole report) and a ROW offset (next page = offset + limit) |
+| `--all` / `--max-rows` | GL only: fetch every row in row-offset pages of `--limit` (default 1000), optionally stopping at `--max-rows` |
+| `--account <id...>` | GL only: only these accounts (repeatable, max 100) |
 
 Also: `clio reports pdf` — generate PDF from a message/document.
 

package/assets/skills/cli/references/field-guide.md

@@ -69,7 +69,7 @@ Use in search: `clio invoices search --status UNPAID --json`
 1. **Create returns minimal response** — only `{ "resourceId": "uuid" }`. Run `clio invoices get <id> --json` for full data.
 2. **Line-item accounts don't fuzzy-resolve** — `--lines` JSON requires exact account name or UUID. Top-level `--account` fuzzy-resolves.
 3. **Transaction creates default to draft** — invoices, bills, journals, credit notes and orders. Use `--finalize` to create as finalized (UNPAID for invoices, ACTIVE for journals). Cash entries and cash transfers are the exception: they post ACTIVE and accept no `--finalize`. Master data has no draft state either: contacts, items, accounts, tags, tax profiles and the rest are created live.
-4. **`--offset` is page number (0-indexed)** — not row skip count. offset=0 + limit=100 = page 1.
+4. **`--offset` is page number (0-indexed)**: not row skip count. offset=0 + limit=100 = page 1. Exceptions, where `--offset` is a ROW offset (next page = offset + limit): `purchase-items list/search`, `currency-rates list`, `claims payouts` and `reports generate general-ledger`. Each command's `--offset` help says which it is, and `--all` pages both kinds correctly.
 5. **`customer` is boolean** — `--customer true`, not `--customer "Acme"`.
 6. **Dates are YYYY-MM-DD** — org-local timezone. API returns epoch ms but CLI formats them.
 7. **`--all` caps at 1,000 rows** — lowered from 10,000 in 2026-04 (DEFAULT_MAX_ROWS in commands/pagination.ts). Pass `--max-rows 50000` for larger datasets, and check `truncated` in the response before treating a page as complete.

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 5.61.2
+version: 5.62.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-kit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-kit
-version: 5.61.2
+version: 5.62.0
 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.61.2
+version: 5.62.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,

package/assets/skills/jobs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-jobs
-version: 5.61.2
+version: 5.62.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/jobs/references/audit-prep.md

@@ -40,7 +40,7 @@
 - Runs after year-end-close; it's the bridge between year-end close and statutory filing.
 - Org inputs this job needs (confirm with the user when not already on file): whether a statutory audit is required, the tax jurisdiction (`SG` | `PH`), and the FY-end — these scope the deliverables.
 - Sibling jobs: `year-end-close.md` (must complete BEFORE this job — audit-prep assumes books are closed), plus the SG Form C-S / PH ITR statutory filing that consumes the pack this job produces (see step 13).
-- API rules: `jaz-api/SKILL.md` rule 36 (`endDate` not `startDate` for AR/AP point-in-time reports), rule 38 (pagination for `general-ledger`), rule 52 (response dates are epoch ms).
+- API rules: `jaz-api/SKILL.md` rule 36 (`endDate` not `startDate` for AR/AP point-in-time reports), rule 38 (`general-ledger` pages by ROW offset, not page number), rule 52 (response dates are epoch ms).
 
 ---
 
@@ -96,7 +96,7 @@ Cashflow classifies into Operating / Investing / Financing per IAS 7. Equity Mov
 generate_general_ledger(period_start: '2025-01-01', period_end: '2025-12-31', groupBy: 'ACCOUNT')
 ```
 
-Per `jaz-api/SKILL.md` rule 38, paginate via `offset` if `totalElements > <page-size>`. Keep the full GL for the pack — the auditor will sample-test from this.
+The tool returns 50 rows per call by default. Page it at `limit` 50-100: a GL row is about 1KB, so larger pages get cut to the tool's result cap and come back with `_truncated`. The offset is a ROW offset (`jaz-api/SKILL.md` rule 38): step it by the rows the call actually returned, which is what `_paging.nextOffset` holds, and stop when a result carries no `_paging`. Keep the full GL for the pack, since the auditor will sample-test from it. From the CLI, `clio reports generate general-ledger --all` pages it for you.
 
 ## Step 6 — AR / AP aging
 

package/assets/skills/jobs/references/sg-tax/data-extraction.md

@@ -186,10 +186,15 @@ POST /api/v1/generate-reports/general-ledger
 {
   "startDate": "2025-01-01",
   "endDate": "2025-12-31",
-  "groupBy": "ACCOUNT"
+  "groupBy": "ACCOUNT",
+  "filter": { "account": { "resourceId": { "in": ["<accountResourceId>", "..."] } } },
+  "limit": 1000,
+  "offset": 0
 }
 ```
 
+`filter.account.resourceId.in` (max 100 ids) keeps the pull to the accounts identified in Phase 2.
+
 **Target these account categories:**
 
 | GL Account Keywords | Add-Back Category | What to Look For |
@@ -205,7 +210,7 @@ POST /api/v1/generate-reports/general-ledger
 | "Unrealized", "FX", "Foreign Exchange" | `unrealizedFxLoss` / `deductions.unrealizedFxGain` | Separate gains from losses |
 | "Dividend Income" | `exemptDividends` | SG one-tier dividends only |
 
-**Tip:** For large GLs, you may need to paginate. Check the response for pagination metadata and follow up with offset/limit parameters.
+**Paging:** the GL reads `offset` as a **ROW offset**, unlike the search endpoints below. Read `data.searchGeneralLedgersReport.totalElements`; while rows remain, request `offset + limit` next (0, 1000, 2000, ...). Omitting `limit` returns the whole report in one response.
 
 ### Step 10: Search for capital items on P&L
 
@@ -294,8 +299,9 @@ All search endpoints support pagination. The standard pattern:
 ```
 
 **Check the response metadata:**
-- `offset` is a **page number** (0-indexed), NOT a row-skip count. Increment `offset` by 1 for each subsequent page.
+- On the search endpoints, `offset` is a **page number** (0-indexed), NOT a row-skip count. Increment `offset` by 1 for each subsequent page.
 - Example: `offset=0` returns items 0–999, `offset=1` returns items 1000–1999, etc.
+- **The general ledger is the exception**: its `offset` is a ROW offset, so the second page of 1000 is `offset=1000` (see Phase 5).
 - Always aggregate totals across all pages before mapping to input fields
 - Do not assume a single page contains all results
 

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

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

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

@@ -63,7 +63,7 @@ The recipe engine uses capsules automatically. But capsules also enable advanced
 
 2. **Use Capsule Types as the search axis, not Capsule Name.** Capsule names are unique per instance ("FY2025 Office Insurance"); types are reusable ("Prepaid Expenses"). `search_capsules(filter: {status: {eq: 'ACTIVE'}}) (capsule type is not filterable — see `jobs/references/building-blocks.md` § Filter limits)` returns ALL prepaid capsules across history.
 
-3. **Tie capsule entries back for the auditor.** `generate_general_ledger` does NOT group by capsule -- `groupBy` is ACCOUNT, CONTACT, TRANSACTION or RELATIONSHIP, and `CAPSULE` returns 422 (verified live 2026-09-01). Auditor sample-test: pick 3 capsules per type, read each with `get_capsule` to get its transaction resource ids, then pull those documents (bills, invoices, journals) directly. Same evidence, one more hop.
+3. **Tie capsule entries back for the auditor.** `generate_general_ledger(groupBy: 'CAPSULE')` groups the period's GL rows by capsule, so each capsule's full lifecycle reads as one block. Auditor sample-test: pick 3 capsules per type from that report and pull the underlying documents (bills, invoices, journals) by their resource ids.
 
 **MCP tool shape:**
 
@@ -91,7 +91,7 @@ search_capsules(filter: {status: {eq: 'ACTIVE'}})  # capsule type is not filtera
   # All open loan capsules — feed into year-end-close.md Y6 reclassification
 **STOP — not selectable by filter.** Journals carry no capsule or fixed-asset link in either direction (`JournalFilter` declares neither; a journal row has no such field even at `view: 'full'`; `GET /capsules/{id}` returns only a `totalTransactions` count — measured 2026-09-07). A date+status search returns every matching DRAFT in the org, so it must never feed `bulk_update_journals` or `delete_journal`. Surface the capsule and its expected count to the practitioner and let them identify the journals.
   # Full GL for one capsule — the auditor's view
-get_capsule(resourceId)   # returns the capsule's transactions; GL cannot group by capsule
+generate_general_ledger(startDate, endDate, groupBy: 'CAPSULE')   # GL rows grouped by capsule
   # Period activity grouped by capsule — the practitioner's view
 ```
 
@@ -241,7 +241,7 @@ Apply enrichments to recipe transactions for richer reporting and record-keeping
    }
    ```
 4. **Supported transaction types**: invoices, bills, credit notes, journals, cash entries
-5. **Reports**: General Ledger cannot group by capsule (`groupBy` accepts ACCOUNT, CONTACT, TRANSACTION, RELATIONSHIP only). Read the capsule with `get_capsule` and pull its transactions.
+5. **Reports**: `generate_general_ledger` groups by ACCOUNT, CONTACT, TRANSACTION, RELATIONSHIP or CAPSULE.
 
 ---
 

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

@@ -20,7 +20,7 @@ No API key needed: `describe_capabilities`, `plan_recipe`, `search_help_center`
 2. **Transaction dates are `valueDate`** (YYYY-MM-DD) — never `issueDate` / `invoiceDate` / `date`.
 3. **Line item text field is `name`** — never `description`.
 4. **`saveAsDraft` defaults `false`** at the API; CLI/MCP create-tools default `true`. Set explicitly when the user says "finalize".
-5. **Pagination uses `limit` / `offset`** — `offset` is a 0-indexed page number (offset=1 = second page), not a row-skip. Sort is required when `offset` is set.
+5. **Pagination uses `limit` / `offset`**: `offset` is a 0-indexed page number (offset=1 = second page), not a row-skip. Exceptions, where `offset` is a 0-indexed ROW offset (next page = offset + limit): the general ledger (and templated), the AR/AP details reports (and templated), purchase items (list and search), currency rates, and employee payouts search. Sort is required when `offset` is set.
 6. **Create responses return `{ resourceId }` only** — re-GET to load the full entity.
 
 ## Transactions — never hand-construct journals for IFRS