jaz-clio 5.61.3 → 5.63.0

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 5.61.3
+version: 5.63.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/feature-glossary.md

@@ -48,7 +48,7 @@ Transaction fees are added to cash spent (not deducted like invoices), and a pay
 
 Pre-invoice / pre-bill documents. Sales pipeline: **Sale Quote** (estimate/quotation) → **Sale Order** → Invoice. Purchase pipeline: **Purchase Request** (requisition) → **Purchase Order** (PO) → Bill.
 
-Key capabilities: a Sale Order links to its source quote via `saleQuoteResourceId` (and a PO to its request via `purchaseRequestResourceId`) — the parent must be **issued** (created with `saveAsDraft:false`, i.e. CREATED/ACTIVE), not a DRAFT. Quotes/requests advance with **accept** (from the issued state), orders with **confirm**. Fulfillment is tracked on the parent via `orderState` (NOT_ORDERED / PARTIALLY_ORDERED / FULLY_INVOICED for quotes, FULLY_BILLED for requests — an order+invoice rollup, arap 2026-06; FULLY_ORDERED retired). Orders convert to invoices/bills via `convert_sale_order_to_invoice` / `convert_purchase_order_to_bill`, and the reverse link is exposed as create-time fields (see orders.md). Delete is draft-only; use void otherwise.
+Key capabilities: a Sale Order links to its source quote via `saleQuoteResourceId` (and a PO to its request via `purchaseRequestResourceId`) — the parent must be **issued** (CREATED/ACTIVE), not a DRAFT: create it with `saveAsDraft:false`, or issue an existing draft in place with the update tool's `isDraftToActive*` flag. Orders made by Jaz Magic start PENDING until the update tool's `isPendingToActive*` flag takes them live. Order updates edit lines by `resourceId` and add any line without one (see orders.md). Quotes/requests advance with **accept** (from the issued state), orders with **confirm**. Fulfillment is tracked on the parent via `orderState` (NOT_ORDERED / PARTIALLY_ORDERED / FULLY_INVOICED for quotes, FULLY_BILLED for requests — an order+invoice rollup, arap 2026-06; FULLY_ORDERED retired). Orders convert to invoices/bills via `convert_sale_order_to_invoice` / `convert_purchase_order_to_bill`, and the reverse link is exposed as create-time fields (see orders.md). Delete is draft-only; use void otherwise.
 
 **API**: per entity (`sale-quotes`, `sale-orders`, `purchase-requests`, `purchase-orders`): CRUD `GET/POST/PUT/DELETE`, `POST /…/search`, `POST /…/:id/{accept|confirm}`, `POST /…/:id/void`, `POST /…/:id/fast-fix`, `POST /…/bulk-{accept|confirm|void|delete}`; orders also `POST /…/line-items/bulk-upsert`. Agent surface: `sale_orders` + `purchase_orders` namespaces (create/get/search/update/transition). See `references/orders.md`.
 

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

@@ -85,9 +85,9 @@ Four entities sharing one shape. Replace `{entity}` with `sale-quotes`, `sale-or
 |--------|------|-------------|
 | GET | `/{entity}` | List |
 | GET | `/{entity}/:resourceId` | Get single |
-| POST | `/{entity}` | Create. Sale Order links via `saleQuoteResourceId`; Purchase Order via `purchaseRequestResourceId` (parent must be issued — saveAsDraft:false — not a draft). |
+| POST | `/{entity}` | Create. Optional `currency { sourceCurrency, exchangeRate? }`. Sale Order links via `saleQuoteResourceId`; Purchase Order via `purchaseRequestResourceId` (parent must be issued, not a DRAFT/VOID, and in the same currency). |
 | POST | `/{entity}/search` | Advanced search with filters |
-| PUT | `/{entity}/:resourceId` | Update |
+| PUT | `/{entity}/:resourceId` | Update. `lineItems` edits by line `resourceId` (`deleted: true` removes; a line without one is ADDED): send every stored line once any names a resourceId. `isDraftToActiveSaleQuote` / `isDraftToActivePurchaseRequest` issue a DRAFT; `isPendingToActiveSaleOrder` / `isPendingToActivePurchaseOrder` take a PENDING order live. |
 | DELETE | `/{entity}/:resourceId` | Delete (DRAFT only — else use void) |
 | POST | `/{entity}/:resourceId/void` | Void (cancel) |
 | POST | `/sale-quotes\|purchase-requests/:resourceId/accept` | Accept (→ ACCEPTED) |
@@ -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/orders.md

@@ -19,8 +19,10 @@ Two MCP namespaces wrap these: **`sale_orders`** (Sale Quotes + Sale Orders) and
 | `PURCHASE_ORDER` | DRAFT (default) / ACTIVE (saveAsDraft:false) | **confirm** → CONFIRMED | VOID | yes (default true) |
 
 - **Quotes & Requests use `accept`. Orders use `confirm`.** (`transition_*` enforces this via a documentType × action matrix.)
-- **`accept` works on the ISSUED state, not DRAFT** — a Sale Quote must be CREATED, a Purchase Request must be ACTIVE. Accepting a DRAFT returns `422 Invalid status` (verified live). There is no exposed DRAFT→issued verb: **issue a document by creating it with `saveAsDraft:false`** (update with `saveAsDraft:false` does NOT issue an existing DRAFT — verified live).
-- **Sale Orders have no draft state** — `saveAsDraft` is ignored; created directly as `CREATED`.
+- **`accept` works on the ISSUED state, not DRAFT**: a Sale Quote must be CREATED, a Purchase Request must be ACTIVE. Accepting a DRAFT returns `422 Invalid status` (verified live). **Issue an existing DRAFT in place** with the update tool's flag: `update_sale_order` `isDraftToActiveSaleQuote: true` (→ CREATED), `update_purchase_order` `isDraftToActivePurchaseRequest: true` (→ ACTIVE). Send every stored line with its `resourceId` in the SAME update: a flag-only update is refused with `422 SALE_LINE_ITEMS_REQUIRED` (verified live 2026-09-23 on a sale quote). It keeps the document's number and line ids (verified live: DRAFT → CREATED, same reference, same line `resourceId`; a line without an account issued fine), so never create a second quote/request to issue one. (Update with `saveAsDraft:false` does NOT issue a DRAFT, verified live.) To create one already issued, pass `saveAsDraft:false` on create.
+- **Sale Orders have no draft state**: `saveAsDraft` is ignored; created directly as `CREATED`.
+- **PENDING orders.** Jaz Magic creates Sale Orders and Purchase Orders as `PENDING`. Take one live with `update_sale_order` `isPendingToActiveSaleOrder: true` / `update_purchase_order` `isPendingToActivePurchaseOrder: true`. Search accepts `status: PENDING`.
+- **Each activation flag belongs to one documentType** (`isDraftToActiveSaleQuote` → SALE_QUOTE, `isPendingToActiveSaleOrder` → SALE_ORDER, `isDraftToActivePurchaseRequest` → PURCHASE_REQUEST, `isPendingToActivePurchaseOrder` → PURCHASE_ORDER). The update tools refuse a flag sent for the other type.
 - Statuses verified live: SQ create → `DRAFT` (or `CREATED` with `saveAsDraft:false`); SQ accept (from CREATED) → `ACCEPTED`; SO create → `CREATED`; SO confirm → `CONFIRMED`; PR create → `DRAFT` (or `ACTIVE` with `saveAsDraft:false`); PR accept (from ACTIVE) → `ACCEPTED`; PO `saveAsDraft:false` → `ACTIVE`; PO confirm → `CONFIRMED`.
 
 ## Linking (quote → order, request → PO)
@@ -30,7 +32,9 @@ Quote→Order / Request→PO linking is a **create-time reference field**:
 - **Quote → Order**: pass `saleQuoteResourceId` on `create_sale_order` (documentType `SALE_ORDER`).
 - **Request → PO**: pass `purchaseRequestResourceId` on `create_purchase_order` (documentType `PURCHASE_ORDER`).
 
-**The parent must be ISSUED (not DRAFT/VOID).** A CREATED/ACCEPTED quote (or ACTIVE/ACCEPTED request) is linkable — accept is **optional** (CREATED already links). Linking to a `DRAFT`/`VOID` parent returns `SALE_QUOTE_STATUS_INVALID_FOR_ORDER_CONVERSION` ("must not be in VOID or DRAFT status to create sale order"). The `create_*` tools pre-flight this: for a DRAFT parent the `repair` hint says to issue it (create with `saveAsDraft:false`) — **not** to accept it (accept fails on DRAFT). So: to order from a quote/request, create the quote/request with `saveAsDraft:false`.
+**The parent must be ISSUED (not DRAFT/VOID).** A CREATED/ACCEPTED quote (or ACTIVE/ACCEPTED request) is linkable — accept is **optional** (CREATED already links). Linking to a `DRAFT`/`VOID` parent returns `SALE_QUOTE_STATUS_INVALID_FOR_ORDER_CONVERSION` ("must not be in VOID or DRAFT status to create sale order"). The `create_*` tools pre-flight this: for a DRAFT parent the `repair` hint points at issuing THAT document in place (`update_sale_order` `isDraftToActiveSaleQuote: true` / `update_purchase_order` `isDraftToActivePurchaseRequest: true`), **not** at accepting it (accept fails on DRAFT) and not at creating a duplicate.
+
+**Currency.** A linked order must use the same currency as its quote/request: a linked order in a different currency is refused.
 
 Creating and confirming an order from an issued quote rolls the parent quote's `orderState` up to reflect downstream progress (arap order-status rollup, 2026-06): a confirmed order **not yet invoiced** shows `PARTIALLY_ORDERED` (verified live); the terminal `FULLY_INVOICED` is reached only once every linked order is fully invoiced. Purchase requests mirror this with `FULLY_BILLED`. `orderState` is a **response field**, not a search filter — values: `NOT_ORDERED` / `PARTIALLY_ORDERED` / `FULLY_INVOICED` (quotes) / `FULLY_BILLED` (requests). The older `FULLY_ORDERED` value was retired by this rollup.
 
@@ -49,12 +53,34 @@ Body: `valueDate` + `dueDate` required; `reference` is required unless you set `
 
 ## Fields (create)
 
-Required: `valueDate`. Recommended: `reference` (omit it to take the next number from your org's own series — must be unique per org), `contactResourceId`, `lineItems`.
+Required: `valueDate`, and `reference` unless you set `autoReference: true` (takes the next number from your org's own series). Omitting both is refused: omitting `reference` does NOT auto-number. `reference` must be unique per org. Recommended: `contactResourceId`, `lineItems`.
+
+- `currency: { sourceCurrency, exchangeRate?, rateDirection? }` (all four documents). Omit for the org's base currency; the currency must be enabled on the org. A linked order must name the same currency as its quote/request. Currency is fixed at create: the update body has no currency field. CLI: `--currency <code>` (+ `--exchange-rate`, `--rate-direction`), same as invoices.
 
 - Line items reuse the standard shape: `{ name, quantity, unitPrice, accountResourceId?, taxProfileResourceId?, … }`. `accountResourceId` is **required on each line when the document is not a draft** (i.e. always for Sale Orders; for quotes/requests/POs when `saveAsDraft:false`). The `create_*` tools pre-flight this.
 - Notes field differs by side: **sales** use `invoiceNotes`, **purchases** use `purchaseNotes`. The `notes` tool param maps to the right one automatically.
 - Other optional fields: `dueDate`, `terms` (0/7/15/30/45/60), `tag`, `customFields`, `billTo`, `billFrom`, `capsuleResourceId`, `expectedTotal`.
 
+## Editing line items (update)
+
+`lineItems` on `update_sale_order` / `update_purchase_order` **edits lines, it does not replace them.** The API pairs each sent line with a stored line by its `resourceId`:
+
+| Sent line | Effect |
+|-----------|--------|
+| has the `resourceId` of a stored line | that line is edited in place |
+| has a stored `resourceId` + `deleted: true` | that line is removed |
+| has no `resourceId` | a NEW line is added |
+| stored line not sent (when any line names a resourceId) | whole update refused: `422 lineItems must include every line item on this … when any line names a resourceId; N not sent` |
+
+Measured live (2026-09-23, one-line sale quote): resending the lines without ids answered **200 and left 2 lines** (the "replace" reading duplicates every line); naming some ids but not all → 422; every id sent (+ `deleted: true` on one) → edited in place.
+
+To change lines:
+1. `get_sale_order` / `get_purchase_order` and copy every `lineItems[].resourceId`.
+2. Send EVERY stored line with its `resourceId`, in display order: edit fields in place, `deleted: true` to remove, and add new lines without a `resourceId`.
+3. An edited line keeps only what you send: resend every stored field you want kept (tax profile, `taxVatAdjustment`, `withholdingTax`, `discount`, `unit`, `itemResourceId`). Dropping a stored tax profile or a non-zero `taxVatAdjustment` is refused; dropping `withholdingTax` (or the others) is NOT refused, it is silently lost. A GET returns the account as `organizationAccountResourceId`; send it back as `accountResourceId`.
+
+The update tools (and `clio … update --lines`) pre-flight this against the stored document: lines with no `resourceId` at all on a document that already has lines are refused locally (nothing is written) unless `appendLines: true` (CLI `--append-lines`) says adding is the intent; naming some stored lines but not all is refused locally with the missing ids.
+
 ## Delete vs Void
 
 - **DELETE is draft-only** (422 on anything non-draft). `transition_* action:DELETE` pre-flights status and returns a `repair` hint to use `VOID` for non-draft records.
@@ -82,12 +108,13 @@ clio supplier-credit-notes download <id>     # supplier CN PDF
 
 ```bash
 # 1. Issue the quote (--finalize → saveAsDraft:false → status CREATED). A plain
-#    draft (no --finalize) stays DRAFT and cannot be linked or accepted.
-clio sale-orders create -t quote --finalize --contact <id> --lines '[{"name":"Widget","quantity":2,"unitPrice":50,"accountResourceId":"<acct>"}]' --date 2026-05-30 --json
+#    draft (no --finalize) stays DRAFT and cannot be linked or accepted until issued
+#    in place: clio sale-orders update <quoteId> -t quote --activate --lines '[{"resourceId":"<lineId>",…}]'
+clio sale-orders create -t quote --finalize --ref Q-1001 --contact <id> --lines '[{"name":"Widget","quantity":2,"unitPrice":50,"accountResourceId":"<acct>"}]' --date 2026-05-30 --json
 # 2. (Optional) accept it (CREATED → ACCEPTED). A CREATED quote is already linkable.
 clio sale-orders accept <quoteId> --json
 # 3. Create the order linked to the issued quote (created as CREATED)
-clio sale-orders create -t order --quote <quoteId> --contact <id> --lines '[…]' --date 2026-05-30 --json
+clio sale-orders create -t order --auto-ref --quote <quoteId> --contact <id> --lines '[…]' --date 2026-05-30 --json
 # 4. Confirm the order (CREATED → CONFIRMED)
 clio sale-orders confirm <orderId> --json
 # 5. The parent quote now rolls up to orderState = PARTIALLY_ORDERED (confirmed order, not yet invoiced)
@@ -100,7 +127,7 @@ Purchase side is symmetric: `create -t request --finalize` (→ ACTIVE) → (opt
 
 ## Search
 
-`search_sale_orders` / `search_purchase_orders` take `documentType` plus the standard filter set (reference, status, contact, contactResourceId, currencyCode, date range, amount range, tag). The `status` enum is the per-side union (sales: DRAFT/CREATED/ACCEPTED/CONFIRMED/VOID; purchases: DRAFT/ACTIVE/ACCEPTED/CONFIRMED/VOID). For advanced/nested queries (e.g. filter by `saleQuoteResourceId`), pass the raw `filter` object. See `search-reference.md` §24–25 and `search-enums.md` §25–26.
+`search_sale_orders` / `search_purchase_orders` take `documentType` plus the standard filter set (reference, status, contact, contactResourceId, currencyCode, date range, amount range, tag). The `status` enum is the per-side union (sales: DRAFT/PENDING/CREATED/ACCEPTED/CONFIRMED/VOID; purchases: DRAFT/PENDING/ACTIVE/ACCEPTED/CONFIRMED/VOID). For advanced/nested queries (e.g. filter by `saleQuoteResourceId`), pass the raw `filter` object. See `search-reference.md` §24–25 and `search-enums.md` §25–26.
 
 Search behaves exactly like the other entities: `sortBy` is an array, `order` is `ASC`/`DESC`, and an `offset` must be paired with a sort. Duplicate `sortBy` values are rejected (`422 — must contain unique values`).
 

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

@@ -414,7 +414,7 @@ No enum fields. Plain string filters (no operators): `currencyCode`, `name`, `pu
 
 | Field | Valid Values |
 |-------|-------------|
-| `status` | `DRAFT`, `CREATED`, `ACCEPTED`, `CONFIRMED`, `VOID` |
+| `status` | `DRAFT`, `PENDING`, `CREATED`, `ACCEPTED`, `CONFIRMED`, `VOID` |
 | `currencyCode` | ISO 4217 (see above) |
 | `terms` | `0`, `7`, `15`, `30`, `45`, `60` (integer — payment terms in days) |
 
@@ -422,7 +422,7 @@ No enum fields. Plain string filters (no operators): `currencyCode`, `name`, `pu
 **Date fields**: `valueDate`, `dueDate`, `createdAt` (DateTime), `updatedAt` (DateTime), `approvedAt`
 **Link field**: `saleQuoteResourceId` (on Sale Orders — the source quote)
 
-> The `status` enum is the union across both sale documents: a **Sale Quote** moves `DRAFT → CREATED → ACCEPTED` (then `VOID`); a **Sale Order** is created as `CREATED → CONFIRMED` (then `VOID`). Fulfillment is reported on the parent quote via `orderState` (`NOT_ORDERED`, `PARTIALLY_ORDERED`, `FULLY_INVOICED`) — an order+invoice rollup (arap, 2026-06; `FULLY_ORDERED` retired), response field only, not a search filter.
+> The `status` enum is the union across both sale documents: a **Sale Quote** moves `DRAFT → CREATED → ACCEPTED` (then `VOID`); a **Sale Order** is created as `CREATED → CONFIRMED` (then `VOID`). An order made by Jaz Magic starts `PENDING` until `update_sale_order` with `isPendingToActiveSaleOrder: true` takes it live. Fulfillment is reported on the parent quote via `orderState` (`NOT_ORDERED`, `PARTIALLY_ORDERED`, `FULLY_INVOICED`) — an order+invoice rollup (arap, 2026-06; `FULLY_ORDERED` retired), response field only, not a search filter.
 
 ---
 
@@ -430,7 +430,7 @@ No enum fields. Plain string filters (no operators): `currencyCode`, `name`, `pu
 
 | Field | Valid Values |
 |-------|-------------|
-| `status` | `DRAFT`, `ACTIVE`, `ACCEPTED`, `CONFIRMED`, `VOID` |
+| `status` | `DRAFT`, `PENDING`, `ACTIVE`, `ACCEPTED`, `CONFIRMED`, `VOID` |
 | `currencyCode` | ISO 4217 |
 | `terms` | `0`, `7`, `15`, `30`, `45`, `60` |
 
@@ -438,7 +438,7 @@ No enum fields. Plain string filters (no operators): `currencyCode`, `name`, `pu
 **Date fields**: `valueDate`, `dueDate`, `createdAt` (DateTime), `updatedAt` (DateTime), `approvedAt`
 **Link field**: `purchaseRequestResourceId` (on Purchase Orders — the source request)
 
-> The `status` enum is the union across both purchase documents: a **Purchase Request** moves `DRAFT → ACTIVE → ACCEPTED` (then `VOID`); a **Purchase Order** moves `DRAFT → ACTIVE → CONFIRMED` (then `VOID`). Fulfillment is reported on the parent request via `orderState` (`NOT_ORDERED`, `PARTIALLY_ORDERED`, `FULLY_BILLED`) — an order+invoice rollup (arap, 2026-06; `FULLY_ORDERED` retired), response field only, not a search filter.
+> The `status` enum is the union across both purchase documents: a **Purchase Request** moves `DRAFT → ACTIVE → ACCEPTED` (then `VOID`); a **Purchase Order** moves `DRAFT → ACTIVE → CONFIRMED` (then `VOID`). An order made by Jaz Magic starts `PENDING` until `update_purchase_order` with `isPendingToActivePurchaseOrder: true` takes it live. Fulfillment is reported on the parent request via `orderState` (`NOT_ORDERED`, `PARTIALLY_ORDERED`, `FULLY_BILLED`) — an order+invoice rollup (arap, 2026-06; `FULLY_ORDERED` retired), response field only, not a search filter.
 
 ---
 

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).
 
@@ -723,7 +723,7 @@ Also covers `POST /api/v1/sale-quotes/search` — same filter shape (`SaleOrderF
 |-------|------|-------|
 | `resourceId` | StringExpression | |
 | `reference` | StringExpression | Order/quote number |
-| `status` | StringExpression | DRAFT, CREATED, ACCEPTED, CONFIRMED, VOID |
+| `status` | StringExpression | DRAFT, PENDING, CREATED, ACCEPTED, CONFIRMED, VOID |
 | `contactResourceId` | StringExpression | |
 | `contact` | ContactNestedFilter | Nested: name, resourceId, status |
 | `saleQuoteResourceId` | StringExpression | (Sale Orders) source quote link |
@@ -755,7 +755,7 @@ Also covers `POST /api/v1/purchase-requests/search` — same filter shape (`Purc
 |-------|------|-------|
 | `resourceId` | StringExpression | |
 | `reference` | StringExpression | Order/request number |
-| `status` | StringExpression | DRAFT, ACTIVE, ACCEPTED, CONFIRMED, VOID |
+| `status` | StringExpression | DRAFT, PENDING, ACTIVE, ACCEPTED, CONFIRMED, VOID |
 | `contactResourceId` | StringExpression | Supplier |
 | `contact` | ContactNestedFilter | Nested: name, resourceId, status |
 | `purchaseRequestResourceId` | StringExpression | (Purchase Orders) source request link |

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 5.61.3
+version: 5.63.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.3
+version: 5.63.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.3
+version: 5.63.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.3
+version: 5.63.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.3
+version: 5.63.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.3
+version: 5.63.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