jaz-clio 5.73.3 → 5.74.0

package/README.md

@@ -3,13 +3,13 @@
 <p align="center">
   <a href="https://www.npmjs.com/package/jaz-clio"><img src="https://img.shields.io/npm/v/jaz-clio?style=for-the-badge&logo=npm" alt="npm"></a>
   <a href="https://www.npmjs.com/package/jaz-clio"><img src="https://img.shields.io/npm/dm/jaz-clio?style=for-the-badge&label=downloads" alt="npm downloads"></a>
-  <img src="https://img.shields.io/badge/tools-381-blue?style=for-the-badge" alt="381 tools">
+  <img src="https://img.shields.io/badge/tools-386-blue?style=for-the-badge" alt="386 tools">
   <a href="https://github.com/teamtinvio/jaz-ai/blob/main/LICENSE"><img src="https://img.shields.io/github/license/teamtinvio/jaz-ai?style=for-the-badge&color=green" alt="License"></a>
 </p>
 
 <p align="center"><b>Jaz accounting on the command line, and inside any AI agent.</b></p>
 
-381 tools · 76 command groups · 7 skills · 13 calculators · 12 close playbooks · 159 field-tested API rules.
+386 tools · 76 command groups · 7 skills · 13 calculators · 12 close playbooks · 160 field-tested API rules.
 
 ```bash
 npm install -g jaz-clio
@@ -64,7 +64,8 @@ clio invoices search --query 'status:unpaid AND $500+' # structured per-entity s
 clio ledger-find-fix preview --level TRANSACTIONS --input recode.json  # find & fix (recode) across record types
 clio approvals approve <resourceId> --entity invoices  # approve a document waiting on you
 clio sql preview "SELECT invoice_number, balance FROM invoices WHERE balance > 0 LIMIT 10"  # read-only pseudo-SQL
-clio report-templates list                             # the organization's saved report layouts
+clio report-templates update "Board P&L" --set colorTheme=calm  # customize a report layout
+clio exports download --type profit-and-loss --template "Board P&L" --format PDF --start-date 2026-01-01 --end-date 2026-06-30
 clio modules list                                      # which features are switched on
 clio navigate reports.profit-and-loss                  # deep link into the Jaz dashboard (offline)
 ```
@@ -107,7 +108,7 @@ that ends up in a journal.
 
 ## MCP server
 
-381 tools for any AI agent that speaks MCP. Runs locally: no cloud, no ports.
+386 tools for any AI agent that speaks MCP. Runs locally: no cloud, no ports.
 
 > **No install at all?** Claude.ai, ChatGPT, Cowork, and Microsoft Copilot Studio can use Jaz through the hosted connector. Add `https://mcp.jaz.ai/mcp` as a custom connector and sign in with OAuth, no key. The local setup below is for terminal use, scripting, and editors that run MCP servers as local processes.
 
@@ -140,7 +141,7 @@ OAuth can reach the organizations granted at sign-in; `--org` pins one, and with
 
 ## Skills
 
-159 API rules from production testing: field-name maps, error-recovery patterns, response-shape quirks, plus 12 job playbooks. Installable into any agent project, no server involved.
+160 API rules from production testing: field-name maps, error-recovery patterns, response-shape quirks, plus 12 job playbooks. Installable into any agent project, no server involved.
 
 ```bash
 clio init                     # auto-detect the agent, install skills + agent-rules

package/assets/skills/api/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: jaz-api
-version: 5.73.3
+version: 5.74.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
+  REST API. Covers field names, response shapes, 160 production gotchas, error
   recovery (422/400/404/500), search filters, pagination, and edge cases for
   every endpoint: invoices, bills, credit notes, journals, cash entries,
   payments, contacts, CoA, items, tax profiles, bank records, fixed assets,
@@ -31,7 +31,7 @@ The rest of this skill (field names, gotchas, error catalog, dependency order, s
 
 **Core fundamentals (read first, every integration):** Identifiers & Dates 1 to 3; Names & Fields 9 to 13; Transaction Creation 14 to 16; Chart of Accounts 17 to 22; Payments / Cross-Currency 4 to 8; Journals & Cash 23 to 26; Credit Notes & Refunds 27 to 28; Reports 36 to 37; Tax Profile Scoping 100; Transaction References 104; Draft Finalization Pipeline 81 to 88; Jaz Magic / PDF-JPG 57 to 63; Currency Rates 39, 49, 105; Withholding Tax 45, 98.
 
-**Integration depth (API clients, pipelines, batch jobs, MCP/CLI):** Bulk Upsert (Items/Contacts/Rates); Background Jobs (filter `resourceId` not `jobId`); Export Records; Pagination (38); Search & Filter (50 to 56); Response Shape Gotchas (66 to 73); Cash Entry Response Shape (74 to 77); Entity Resolution (78 to 80); Bank Rules (89 to 90d); Fixed Assets (91 to 92c); Subscriptions & Scheduled (93 to 94); niche endpoints (95 to 102); Journals balance (103); Quick Fix (107, 111); TTB (108); Dynamic Strings (109 to 110); Sub-Resource Shapes (112); Nano-Classifier (113); Scheduler Asymmetry (114); Payment Record CRUD (115 to 117); Bulk Upserts transactions (118 to 122); Reconciliation write-side (123 to 127); Drafts lifecycle (128 to 135); Orders: Sale Quotes / Sale Orders / Purchase Requests / Purchase Orders (`references/orders.md`); Claims: records / lifecycle / bulk + conversion + payouts + Employees + Claim Settings (`references/claims.md`).
+**Integration depth (API clients, pipelines, batch jobs, MCP/CLI):** Bulk Upsert (Items/Contacts/Rates); Background Jobs (filter `resourceId` not `jobId`); Export Records; Pagination (38); Search & Filter (50 to 56); Response Shape Gotchas (66 to 73); Cash Entry Response Shape (74 to 77); Entity Resolution (78 to 80); Bank Rules (89 to 90d); Fixed Assets (91 to 92c); Subscriptions & Scheduled (93 to 94); niche endpoints (95 to 102); Journals balance (103); Quick Fix (107, 111); TTB (108); Dynamic Strings (109 to 110); Sub-Resource Shapes (112); Nano-Classifier (113); Scheduler Asymmetry (114); Payment Record CRUD (115 to 117); Bulk Upserts transactions (118 to 122); Reconciliation write-side (123 to 127); Drafts lifecycle (128 to 135); Orders: Sale Quotes / Sale Orders / Purchase Requests / Purchase Orders (`references/orders.md`); Claims: records / lifecycle / bulk + conversion + payouts + Employees + Claim Settings (`references/claims.md`); Report templates and packs (161, `references/report-templates.md`).
 
 ## When to Use This Skill
 
@@ -548,7 +548,7 @@ When the user wants to OPEN, SEE, or SHARE something in the Jaz dashboard ("open
     - **`reconcile_magic_match`**: bulk-accept MAGIC_MATCH suggestions (max 500 entries). Returns `{reconciled[], failed[]}`; a 200 with non-empty `failed[]` is a PARTIAL success (per-entry `errorCode`); loop on failed only. Entry-level idempotency-keyed server-side (re-submit returns done entries in `reconciled[]`).
     - **`reconcile_learned_prediction`**: accept an ML prediction. `predictedPayload` + `predictedPayloadSchemaVersion` come VERBATIM from a `view_auto_reconciliation` (MAGIC_RECONCILE_WITH_CASH_IN_OUT) suggestion; never hand-construct. `retryToken` forces a fresh journal on edit-retry; omit for idempotent replay. On failure (stale payload), fall back to `reconcile_with_payments`; don't retry the blob.
 
-159. **`view_auto_reconciliation` returns execution-ready `suggestions[]`, the suggestion→commit seam.** **`bankStatementEntryResourceIds` is REQUIRED: the endpoint is per-entry and has no account-wide mode; source ids from `search_bank_records` (status `UNRECONCILED`).** Each suggestion carries `recommendedTool` (the commit tool to call), `execute` (ready-to-pass args; merge `bankAccountResourceId` for `reconcile_magic_match`), `confidenceTier` (high/medium/low, code-derived), and `autoCommitEligible` (true ⇒ high confidence + executable plan + under any `autoCommitMaxAmount` cap). **Decision gate:** `autoCommitEligible===true` → auto-commit via `recommendedTool`+`execute`; everything else → surface for confirmation. **Amount threshold is a HARD VETO over confidence** (pass `autoCommitMaxAmount`). Field mapping under the hood: `cftBtResourceId`→`cashflowTransactionResourceId` (single → `reconcile_with_payments`), `cftBtResourceIds[]`/`isBatch`→`matchedBusinessTransactions` (batch → `reconcile_magic_match`), `recommendationType`→tool, `confidenceScore`→tier. **Request vs response vocabulary:** the `recommendationType` you SEND selects what to compute and additionally accepts `RECOMMENDATIONS` (every type except `MAGIC_MATCH`, ranked together, and the cheaper call; `MAGIC_MATCH` scans open transactions so it is requested on its own; nothing returns everything at once). The `recommendationType` you RECEIVE on a suggestion is always a concrete type and is never `RECOMMENDATIONS`, so the `recommendationType`→tool mapping above is unaffected by which selector you sent. Pass `includeRaw:true` for the unmapped payload. Cost tracks the entries you pass; batch large backlogs. On 500 it returns `{degraded:true}`; use the `clio jobs bank-recon match` cascade. NOT idempotent applies to every commit; see Rules 125 + 158.
+159. **`view_auto_reconciliation` returns execution-ready `suggestions[]`, the suggestion→commit seam.** **`bankStatementEntryResourceIds` is REQUIRED: the endpoint is per-entry and has no account-wide mode; source ids from `search_bank_records` (status `UNRECONCILED`).** Each suggestion carries `recommendedTool` (the commit tool to call), `execute` (ready-to-pass args; merge `bankAccountResourceId` for `reconcile_magic_match`), `confidenceTier` (high/medium/low, code-derived), and `autoCommitEligible` (true ⇒ high confidence + executable plan + under any `autoCommitMaxAmount` cap). **Decision gate:** `autoCommitEligible===true` → auto-commit via `recommendedTool`+`execute`; everything else → surface for confirmation. **Amount threshold is a HARD VETO over confidence** (pass `autoCommitMaxAmount`). Field mapping under the hood: `cftBtResourceId`→`cashflowTransactionResourceId` (single → `reconcile_with_payments`), `cftBtResourceIds[]`/`isBatch`→`matchedBusinessTransactions` (batch → `reconcile_magic_match`), `recommendationType`→tool, `confidenceScore`→tier. **Request vs response vocabulary:** the `recommendationType` you SEND selects what to compute and additionally accepts `RECOMMENDATIONS` (every type except `MAGIC_MATCH`, ranked together, and the cheaper call; `MAGIC_MATCH` scans open transactions so it is requested on its own; nothing returns everything at once). The `recommendationType` you RECEIVE on a suggestion is always a concrete type and is never `RECOMMENDATIONS`, so the `recommendationType`→tool mapping above is unaffected by which selector you sent. Pass `includeRaw:true` for the unmapped payload. Cost tracks the entries you pass; batch large backlogs. On a 500, or no answer in time (25 s in chat and on hosted MCP, 55 s on stdio MCP, 60 s from the CLI and `clio mcp-call`), it returns `{degraded:true}` with a `reason` naming the wait; use the `clio jobs bank-recon match` cascade. NOT idempotent applies to every commit; see Rules 125 + 158.
 
 ## See Also
 
@@ -558,3 +558,5 @@ When the user wants to OPEN, SEE, or SHARE something in the Jaz dashboard ("open
 - **jaz-cli**: CLI command reference, auth, output formats, pagination, and workflow patterns
 
 160. **Payment `adjustment` is a CASH-LEG-only correction; it never moves the document balance.** Records an overpayment or a rounding difference on the bank side of a payment: `netCash = paymentAmount -/+ fees +/- adjustmentValue` (fees are deducted from cash received on an invoice and added to cash spent on a bill). AR/AP is untouched, so an overpaid invoice stays PAID with the excess sitting on the account you chose and NO credit note is created. Shape: `adjustment: { adjustmentValue, adjustmentAccountResourceId, adjustmentDescription? }`, signed, non-zero, max 2dp, always FLAT (never a percentage), never taxed. Accepted on `pay_invoice` / `pay_bill` / both credit-note refunds / `update_payment` / both receipt reconciliations. **NOT** on batch payments, and not for `DEBT_WRITE_OFF` / `CLEARING_SETTLEMENT` / `INTER_COMPANY` / `WITHHOLDING_TAX_CERTIFICATE` (those record a settlement, so there is no cash leg). The account must be non-controlled: not AR/AP, not the VAT or FX accounts, not bank/cash, not deposit-linked. **Write/read asymmetry:** you WRITE the nested `adjustment.adjustmentValue` but READ a flat `adjustmentAmount` on the payment record, alongside `adjustmentOrganizationAccountResourceId`. Don't confuse either with `lineItems[].taxVatAdjustment.adjustmentAmount`, which is line-item tax and unrelated. **On `update_payment`, adding an adjustment and changing an existing one both APPLY.** Verified against production on arap `v10.7.21` (2026-08-11): an amount move and an account-plus-description move both returned 200 and applied. `paymentAmount` and `transactionAmount` are untouched. **Removing one does NOT work.** `adjustmentValue: 0` is rejected at the edge with a 422, and `"adjustment": null` is indistinguishable from omitting the field, so both leave the stored value unchanged. To remove an adjustment, delete the payment record and record it again without one. An explicit clear flag is being added upstream; zero stays rejected, so omit-to-clear will never be the answer. Anything describing this field as inert on update is stale. **arap `v10.7.21` put both guards behind one comparator, and a CHANGE now has two rejection conditions.** `PaymentAmountCalculator.adjustmentChanged` answers "did the adjustment change?" for the reconciled check AND for lock-date validation, which previously disagreed: the reconciled check compared the amount alone, and lock-date validation did not look at the adjustment at all. It compares **amount, account AND description** (amount by `compareTo`, so `5.0` and `5.00` are equal). Two conditions reject a change: **(a) the payment is RECONCILED** to a bank statement entry, giving `PAYMENT_ADJUSTMENT_CANNOT_CHANGE_WHEN_RECONCILED` (moving it to a different account trips this now, where the amount-only check let it through); **(b) an account on the payment's LEDGER ROWS carries a lock date later than the `valueDate`**, giving `DELETE_TRANSACTION_VALUE_DATE_CANNOT_BE_EARLIER_THAN_LOCK_DATE` -- an update deletes and recreates the ledger rows, so the delete half trips first and the code names a delete for a call that was an update. **The escape hatch:** resending the same adjustment, or omitting the field, compares equal and is NOT a change, so it does not by itself trip either guard. **But that is not a general exemption, and this is the trap.** `adjustmentDescription` is optional, so resending only `adjustmentValue` + `adjustmentAccountResourceId` against a payment that HAS a description compares unequal and counts as a change. Resend all three, or omit the object entirely. And lock-date validation gates on seven other fields independently: changing `reference`, `valueDate`, `paymentMethod`, `organizationAccountResourceId`, `paymentAmount`, `transactionAmount`, or converting a draft to active is lock-date validated on its own. Only edits that move no ledger row survive a lock. **Measured on production 2026-08-11**, throwaway account locked at 2026-07-31 over a payment dated 2026-06-15: change the adjustment -> 422; change ONLY `reference` -> 422; resend all three values unchanged -> 200; resend WITHOUT the description -> 422; then unlock and repeat the first call -> 200 and applied. That last row is the control. Condition (a) is read from the deployed source, not triggered: it needs a bank statement entry, which has no delete, so proving it costs permanent state on a shared org.
+
+161. **Report templates: the saved layout of a report, one default per report type, and packs.** Eight verbs on MCP and CLI (list, get, search, default-configuration, create, update, set-default, delete), each taking a template by **resourceId or exact name**; render one with `download_export` / `clio exports download --template <name>`. `templateConfiguration` is a JSON-encoded string on the wire; Clio hands it over as an object, never shows the server-owned `coaSnapshot` (a copy of the whole chart of accounts, up to 324 KB), and returns a large layout as a key map plus a row outline. Change part of one with `edits` (set / insert / remove by path; updateRow / addRow / removeRow / moveRow by row id), applied all or nothing and refused when they introduce a silent fault (an unknown enum value, a formula naming a missing row, a removed engine total). **Set default changes every export and dashboard view** of that report for the whole organization; the answer carries `previousDefault` to undo it. A pack's reports come from `packTemplates` (names or ids, in order), written to both places the server reads them from. Measured upstream quirks (2026-09-24): an export given a template it cannot use (unknown, or of another report type) answers **HTTP 200 with an empty body**, so Clio checks the template first; for P&L and cashflow only `IAS_1` and `IFRS_18` have a default layout (`GAAP` / `IND_AS` / `IFRS_SME` answer 422 `NO_TEMPLATE_FOUND` without one); profit-and-loss and balance-sheet saves drop keys the server does not model with no error (Clio reports them as `notSaved`); deleting a pack's last report leaves an empty pack whenever the pack has any other component (Clio refuses it); four of five search filters answer 500 (Clio filters the list). Full reference: `references/report-templates.md`.

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

@@ -2908,6 +2908,87 @@ Body `{ "hash": "..." }`. Deletes the record but RELEASES its payment records as
 
 Records an unapplied payment for the bank record and matches the two. Direction, account, currency, date and amount come from the bank record. `amount` is optional and, when sent, must EQUAL the bank record's amount (`TOTAL_RECONCILIATION_AMOUNT_MISMATCHED_WITH_STATEMENT_ENTRY_AMOUNT` otherwise); there is no partial match. `rateToFunctional` is required for a foreign-currency account. `amount` belongs INSIDE `unappliedPaymentDetails`: at the top level it is silently dropped. Returns `{ bankStatementEntryResourceId, status, reference, valueDate, unappliedPaymentResourceId }`.
 
+## 28. Report Templates
+
+The saved layout of a report, one default per report type, plus report packs. The layout fields, `edits`, and every measured quirk are in `references/report-templates.md`; this section is the wire.
+
+Rules that hold on every route below:
+- `templateConfiguration` is a **JSON-encoded string** in every request and response. Profit-and-loss and balance-sheet layouts come back with a server-owned `coaSnapshot` (a copy of the chart of accounts, rebuilt on every save; omit it when sending).
+- Writes return only `{ "data": { "resourceId": "..." } }`. Read the template back to see what was stored.
+- Names are unique per report type, ignoring case and treating space and `_` alike (422 `DUPLICATE_REPORT_TEMPLATE_EXISTS`).
+
+### GET /api/v1/organization-report-template
+
+Every template of the organization in one response, **under `reportTemplates`, not `data`**, and ignoring `limit`/`offset`. Rows: `resourceId`, `templateName`, `reportType`, `reportCategory`, `isDefault`, `templateConfiguration`, and on packs `reportPackType` and `packTemplates` (`[{ templateResourceId, templateName, templateOrder, reportType }]`).
+
+### GET /api/v1/organization-report-template/{resourceId}
+
+`{ "data": { ...one row... } }`. 404 `Report template not found` for an unknown id. A template read in the same second it was created can 404 once.
+
+### POST /api/v1/organization-report-template/search
+
+`{ filter, sort }`, answers a bare array. **Four of its five filters answer 500** (`reportCategory` without `reportType`, `isDefault`, `reportTypes`, `resourceId`), and there is no name filter. Clio filters the list instead.
+
+### GET /api/v1/organization-report-template/default-configuration
+
+`?reportType=PROFIT_AND_LOSS&framework=IFRS_18` returns `{ "data": { "templateConfiguration": "..." } }`, the layout a new template starts from, in the organization's own currency. The 12 single-report types only (not `REPORT_PACK`). `framework` is accepted for `PROFIT_AND_LOSS` and `CASHFLOW` only, and **only `IAS_1` and `IFRS_18` have a layout**: the other three answer 422 `NO_TEMPLATE_FOUND`. Takes 0.1-5 s (it builds a report preview).
+
+### POST /api/v1/organization-report-template
+
+```json
+{ "templateName": "Board P&L", "reportType": "PROFIT_AND_LOSS", "framework": "IAS_1", "templateConfiguration": "{...}" }
+```
+
+- **Required:** `templateName` (max 255) and `reportType`.
+- **Omit `templateConfiguration`** to start from the default layout. Any well-formed JSON is accepted as a layout, and an unusable one renders as the default.
+- **`framework`** is for P&L, balance sheet, cashflow and equity movement only; it defaults to `IAS_1` and cannot change later.
+- **`REPORT_PACK` requires both** `templateConfiguration` and `packTemplates: [{ templateResourceId, templateOrder }]`. They are refused on any other type.
+  - Keep `packTemplates` and the layout's `TEMPLATE` components in step, or the missing report renders as an error page.
+  - Refusals: `TEMPLATE_NOT_FOUND` for an unknown member, `DUPLICATE_TEMPLATE_ORDER` for a repeated position.
+- **Not made the default**, except that the first template of a type (in practice, the first pack) becomes its default.
+- Returns 201.
+
+### PUT /api/v1/organization-report-template/{resourceId}
+
+Any of `templateName`, `templateConfiguration`, `packTemplates`.
+- `templateConfiguration` and `packTemplates` each **replace** the stored value in full.
+- Report type and framework cannot change; other fields are ignored without an error.
+- `packTemplates` on a non-pack is 422.
+
+### POST /api/v1/organization-report-template/{resourceId}/set-default
+
+No body. Makes the template its report type's default and clears the previous one. **Every export and dashboard view of that report then uses it.** 404 for an unknown id.
+
+### DELETE /api/v1/organization-report-template/{resourceId}
+
+Removes the template from every pack that includes it.
+- **Refused:** the default of a report type (422 `CANNOT_DELETE_REPORT_TEMPLATE`, "Set another template as the default first"), and the only template of a type.
+- **Not refused:** a pack's last report whenever the pack has any other component, which leaves the pack with no reports. Clio refuses that one itself.
+- Packs can always be deleted. Deleting the default pack hands the default to the newest remaining pack.
+
+### Rendering with a template
+
+`POST /api/v1/data-exports/{type}` takes `templateResourceId` (or `templateName`) for these types, each rendering one report type:
+
+| Export type | Report type |
+|---|---|
+| `profit-and-loss` | `PROFIT_AND_LOSS` |
+| `balance-sheet` | `BALANCE_SHEET` |
+| `cashflow` | `CASHFLOW` |
+| `equity-movement` | `EQUITY_MOVEMENT` |
+| `trial-balance` | `TRIAL_BALANCE` |
+| `general-ledger` | `GENERAL_LEDGER` |
+| `tax-ledger` | `VAT_LEDGER` |
+| `cash-balance` | `CASH_BALANCE` |
+| `ar-report` | `AGED_RECEIVABLES_SUMMARY` |
+| `ar-details-report` | `AGED_RECEIVABLES_DETAILS` |
+| `ap-report` | `AGED_PAYABLES_SUMMARY` |
+| `ap-details-report` | `AGED_PAYABLES_DETAILS` |
+
+- **A template that is unknown, or of another report type, answers HTTP 200 with an EMPTY body.** It is not an error status, and there is no file.
+- Omit the template to render the organization's default.
+- The `generate-reports/templated-*` endpoints take `reportTemplateResourceId` and return the report as JSON; a template of the wrong type answers 404 `template_not_found`.
+
 ---
 
-*Last updated: 2026-09-23 (added Unapplied Payments, section 27). Previous: 2026-09-13 (added Bank Rules CRUD, section 26). Previous: 2026-07-11 (added Jots judgment journal, section 25). Previous: 2026-04-09, added Contacts bulk-upsert (22), Background Jobs search (23), Export Records (24). 2026-03-13: Payment record CRUD, nano-classifier, scheduler GET/PUT/DELETE.*
+*Last updated: 2026-09-24 (added Report Templates, section 28). Previous: 2026-09-23 (added Unapplied Payments, section 27). Previous: 2026-09-13 (added Bank Rules CRUD, section 26). Previous: 2026-07-11 (added Jots judgment journal, section 25). Previous: 2026-04-09, added Contacts bulk-upsert (22), Background Jobs search (23), Export Records (24). 2026-03-13: Payment record CRUD, nano-classifier, scheduler GET/PUT/DELETE.*

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

@@ -944,6 +944,30 @@ Two of the seven never reach you through this path: a zero `adjustmentValue` and
 **Cause**: `add_employee` was called without `claimProfileResourceId` ("A claim profile is required for an employee — it carries the employee balance account used to convert and pay claims"). The claim profile is **server-required**; the org default is NOT auto-applied for employees (unlike claims), even when a default profile exists.
 **Fix**: Pick a profile via `search_claim_profiles` and pass its `resourceId` as `claimProfileResourceId`. The profile is locked while the employee has unsettled claims.
 
+### "DUPLICATE_REPORT_TEMPLATE_EXISTS" (422)
+**Cause**: A report template of the same report type already has this name. Names are unique per report type, ignoring case and treating space and `_` alike ("My P&L" and "my_p&l" collide); the same name on another report type is fine.
+**Fix**: Pick another name, or update the existing template. The Clio tools refuse this before sending and name the existing template's resourceId.
+
+### "NO_TEMPLATE_FOUND" (422)
+**Cause**: A P&L or cashflow default layout was asked for (default configuration, or a create with no `templateConfiguration`) under a framework that has none. Only `IAS_1` and `IFRS_18` have one; `GAAP`, `IND_AS` and `IFRS_SME` pass validation and then land here.
+**Fix**: Use `IAS_1` or `IFRS_18`, or pass `templateConfiguration` (for example an existing template's layout, from `get_organization_report_template`).
+
+### "CANNOT_DELETE_REPORT_TEMPLATE" (422)
+**Cause**: The template is the default of its report type, or the only template of it.
+**Fix**: Make another template the default first (`set_default_organization_report_template`; CLI `clio report-templates set-default`), then delete.
+
+### "TEMPLATE_NOT_FOUND" / "DUPLICATE_TEMPLATE_ORDER" (422)
+**Cause**: A report pack's `packTemplates` lists a template that does not exist, or two reports at the same `templateOrder`.
+**Fix**: List the templates and send `packTemplates` again. The Clio tools take pack reports as names or ids in order and number them, so neither arises through them.
+
+### "template_not_found" (404, templated reports)
+**Cause**: A `generate-reports/templated-*` call named a template that exists but is of another report type. The message ("not found in organization") says the template does not exist; it does.
+**Fix**: Pass a template of that report's type.
+
+### Export returns HTTP 200 with an EMPTY body
+**Cause**: A `data-exports/{type}` call named a report template it cannot use: one that does not exist, or one of another report type (also an unknown `templateName`). Measured on all 12 template-taking exports. No status code says so.
+**Fix**: Pass a template of that export's report type (table in `references/report-templates.md`). `download_export` / `clio exports download` take `template` (a name or id) and check it first; given a raw `templateResourceId`, they report the empty answer as an error instead of retrying it.
+
 ---
 
 ## Repair Suggestions (W1.3)

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

@@ -678,6 +678,18 @@ Battle-tested patterns from production Jaz API clients:
 | `isPrintable` | `printable` | Boolean, no `is` prefix. Default `false`; most classifiers are not printable |
 | `categories` | `classes` | The "categories" or "options" are called `classes` |
 
+### Report Template Fields
+
+| What You'd Guess | Actual API Field | Notes |
+|------------------|-------------------|-------|
+| `layout` / `config` | `templateConfiguration` | A JSON-encoded **string** on the wire; the Clio tools hand it over as an object |
+| `name` | `templateName` | Unique per report type |
+| `type` | `reportType` | UPPER_SNAKE: `PROFIT_AND_LOSS`, `VAT_LEDGER` (the tax ledger), `AGED_RECEIVABLES_SUMMARY`, ... |
+| `default` | `isDefault` | One per report type; change with set-default, never on update |
+| `templateId` (exports) | `templateResourceId` | On `data-exports/{type}` |
+| `templateId` (templated reports) | `reportTemplateResourceId` | On `generate-reports/templated-*` |
+| `reports` (pack) | `packTemplates[].templateResourceId` + `templateOrder` | Must match the layout's `includedComponents` TEMPLATE entries |
+
 ## Background Jobs
 
 🚨 The single most dangerous trap in background-jobs:

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

@@ -3,7 +3,7 @@
 > **The endpoints clio wraps (the REST surface is larger).** This file catalogues roughly 200
 > paths, organized by resource, including undocumented endpoints, magic AI features, admin
 > APIs, and advanced search/filter syntax. The committed OpenAPI spec (`spec/openapi.yaml`)
-> carries 466 spec paths and 594 spec operations and is the authoritative list; check it before concluding
+> carries 468 spec paths and 599 spec operations and is the authoritative list; check it before concluding
 > an endpoint does not exist. For request/response examples of core endpoints, see
 > endpoints.md.
 >
@@ -519,7 +519,16 @@ Body for all three: `{ items: [{btResourceId: "<uuid>", btType: "SALE|PURCHASE|S
 ### Organization Report Templates
 | Method | Path | Description |
 |--------|------|-------------|
-| POST | `/organization-report-template/search` | Search report templates |
+| GET | `/organization-report-template` | List every template (rows under `reportTemplates`; ignores paging) |
+| GET | `/organization-report-template/:resourceId` | Get one |
+| POST | `/organization-report-template/search` | Search (4 of 5 filters answer 500; Clio filters the list instead) |
+| GET | `/organization-report-template/default-configuration` | The default layout a new template of a report type starts from |
+| POST | `/organization-report-template` | Create (layout defaults to the system layout; a pack needs its layout and `packTemplates`) |
+| PUT | `/organization-report-template/:resourceId` | Rename, replace the layout, or replace a pack's reports |
+| POST | `/organization-report-template/:resourceId/set-default` | Make it its report type's default (every export then uses it) |
+| DELETE | `/organization-report-template/:resourceId` | Delete (refused for a type's default) |
+
+Layouts, `edits` and measured quirks: `report-templates.md`.
 
 ### Catalogs
 | Method | Path | Description |

package/assets/skills/api/references/report-templates.md

@@ -0,0 +1,305 @@
+# Report Templates
+
+A **report template** is the saved layout of one report: its title, fonts, colours, the period it opens on, its columns and (for the financial statements) the tree of rows and totals. A **report pack** is a template that bundles several reports, plus an optional cover page, contents, signature page and appendix, into one document.
+
+Every report type can hold many templates. **Exactly one per type is the default**, and the default is what every export and every dashboard view of that report uses when no template is named.
+
+Measured against production on 2026-09-24. Everything below that says "measured" was probed live, not read from a spec.
+
+---
+
+## The surfaces
+
+Every surface uses the same eight verbs, and each takes a template by **resourceId or exact name**:
+
+| Verb | MCP tool | CLI | API |
+|---|---|---|---|
+| list | `list_organization_report_templates` | `clio report-templates list` | `GET /organization-report-template` |
+| read | `get_organization_report_template` | `clio report-templates get <template>` | `GET /organization-report-template/{id}` |
+| search | `search_organization_report_templates` | `clio report-templates search` | (evaluated over the list, see below) |
+| default layout | `get_default_organization_report_template_configuration` | `clio report-templates default-config --type <T>` | `GET /organization-report-template/default-configuration` |
+| create | `create_organization_report_template` | `clio report-templates create` | `POST /organization-report-template` |
+| update | `update_organization_report_template` | `clio report-templates update <template>` | `PUT /organization-report-template/{id}` |
+| make default | `set_default_organization_report_template` | `clio report-templates set-default <template>` | `POST /organization-report-template/{id}/set-default` |
+| delete | `delete_organization_report_template` | `clio report-templates delete <template>` | `DELETE /organization-report-template/{id}` |
+| **render** | `download_export` with `template` | `clio exports download --template <template>` | `POST /data-exports/{type}` with `templateResourceId` |
+
+Resolve a name to its id on its own with `clio resolve report-template <name>`.
+
+---
+
+## Report types
+
+| reportType | What it lays out | Renders through export | Period | `framework` |
+|---|---|---|---|---|
+| `PROFIT_AND_LOSS` | Profit and loss | `profit-and-loss` | range | yes; picks the starting layout |
+| `BALANCE_SHEET` | Balance sheet | `balance-sheet` | as at a date | accepted; one layout for all |
+| `CASHFLOW` | Cashflow statement | `cashflow` | range | yes; picks the starting layout |
+| `EQUITY_MOVEMENT` | Statement of changes in equity | `equity-movement` | range | accepted; one layout for all |
+| `TRIAL_BALANCE` | Trial balance | `trial-balance` | as at a date | no |
+| `GENERAL_LEDGER` | General ledger | `general-ledger` | range | no |
+| `VAT_LEDGER` | Tax (GST/VAT) ledger | `tax-ledger` | range | no |
+| `CASH_BALANCE` | Cash balance | `cash-balance` | as at a date | no |
+| `AGED_RECEIVABLES_SUMMARY` | Aged receivables | `ar-report` | as at a date | no |
+| `AGED_RECEIVABLES_DETAILS` | Aged receivables, per document | `ar-details-report` | as at a date | no |
+| `AGED_PAYABLES_SUMMARY` | Aged payables | `ap-report` | as at a date | no |
+| `AGED_PAYABLES_DETAILS` | Aged payables, per document | `ap-details-report` | as at a date | no |
+| `REPORT_PACK` | Several reports in one document | not through the public API | range | no |
+
+- Bank balance summary and the two bank reconciliation reports have a fixed layout. No template applies to them.
+- **`framework`** takes `IAS_1`, `IFRS_18`, `GAAP`, `IND_AS` or `IFRS_SME`, and defaults to `IAS_1`.
+  - **For P&L and cashflow, only `IAS_1` and `IFRS_18` have a default layout.** The other three pass validation, then answer `422 NO_TEMPLATE_FOUND` when no layout is given. Balance sheet and equity movement have one default layout whatever the framework, so every framework works there.
+  - To use one of them, create from an existing template's layout.
+  - The framework is set on create and cannot change. The list and get responses do not return it.
+
+---
+
+## Reading layouts
+
+`templateConfiguration` is stored as a **JSON-encoded string**. Clio tools and the CLI hand it over as an **object**, and accept an object or a string back.
+
+**`coaSnapshot` is never shown and never sent.**
+- The server adds it to profit-and-loss and balance-sheet layouts on every save: a copy of the organization's whole chart of accounts. It measured 166-324 KB on a sandbox.
+- It exists only to detect later chart changes. The server rebuilds it on every write, so sending a layout without it is safe (measured).
+
+**Layouts are large.** A real P&L or balance sheet layout is 16-59 KB even without the snapshot. So:
+- `list` / `search` return no layouts at all, only `configurationChars` (the size).
+- `get` returns the whole layout when it fits (up to 15,000 characters). Otherwise it returns:
+  - `configurationKeys`: each top-level key and its size.
+  - `rowOutline`: the row tree as ids, names, types and formulas, with no matching rules.
+- Then ask for what you need:
+  - MCP: `keys: ["pdfTitleConfigs", "columnConfigs"]`, or `row: "<row id>"` for one row in full.
+  - CLI: `--keys pdfTitleConfigs,columnConfigs`, `--row <id>`.
+  - CLI: `--config-out layout.json` writes the whole layout to a file.
+
+---
+
+## Changing layouts: `edits`
+
+Upstream replaces the whole layout on every write. To change part of it, send **`edits`**: Clio applies them to the stored layout and sends the result.
+
+- **All or nothing.** The first edit that cannot apply stops everything, names its position, and nothing is written.
+- **Checked.** An edit is refused if it *introduces* one of these problems:
+  - a value outside a fixed set
+  - a formula that names a missing row
+  - a removed total the report engine reads
+  - a period type the report cannot use
+
+  A value the layout already had is never held against you.
+
+| op | Shape | Does |
+|---|---|---|
+| `set` | `{ op, path, value }` | Set a value (any JSON). On a list position it **replaces** that entry. |
+| `insert` | `{ op, path, value }` | Insert into a list at that position (`.-` appends). Use this to add a component. |
+| `remove` | `{ op, path }` | Remove a key or a list entry. |
+| `updateRow` | `{ op, rowId, fields }` | Merge fields into a row: `name`, `actionCriteria`, `formulaConfig`, `showGroupTotal`, `hideRowIfZeroValue`, ... |
+| `addRow` | `{ op, row, parentId?, index? }` | Add a row (`id`, `name`, `rowType`, then criteria or formula). Omit `parentId` for top level. |
+| `removeRow` | `{ op, rowId }` | Remove a row and its children. Refused while a formula uses it. |
+| `moveRow` | `{ op, rowId, parentId?, index? }` | Move a row under another parent or to another position. |
+
+**Paths** are dotted keys and list positions (`pdfTitleConfigs.title`, `columnConfigs.0.type`), or a JSON Pointer (`/pdfTitleConfigs/title`).
+
+**Rows are addressed by id**, never by position, because positions shift as rows move.
+
+```jsonc
+// Retitle a P&L, calm colours, and rename a group
+{
+  "template": "Board P&L",
+  "edits": [
+    { "op": "set", "path": "pdfTitleConfigs.title", "value": "Monthly Board P&L" },
+    { "op": "set", "path": "colorTheme", "value": "calm" },
+    { "op": "updateRow", "rowId": "OPERATING_REVENUE", "fields": { "name": "Revenue from operations" } }
+  ]
+}
+```
+
+```bash
+# The same from the CLI: one flag per change, or a file of edits
+clio report-templates update "Board P&L" \
+  --set pdfTitleConfigs.title="Monthly Board P&L" --set colorTheme=calm
+clio report-templates update "Board P&L" --edits edits.json
+```
+
+**What the server did not keep.** Profit-and-loss and balance-sheet layouts pass through a fixed layout model on every save, and a key it does not model is dropped with no error. Measured 2026-09-24: `showZeroValueAccounts: true` set on a P&L through the API was not kept (older templates saved another way can still carry that key). Every write re-reads the template, and `notSaved` lists any edited path whose value did not survive. The rest of the write went through.
+
+---
+
+## Layout fields
+
+Shared by every single-report type. Every value in the table is from the report engine's own list: anything else falls back silently, so an edit that writes it is refused.
+
+| Key | Values |
+|---|---|
+| `colorTheme` | `default` `calm` `bold` `trust` `social` `ivory` `gold` `peach` |
+| `margins` | `default` `compact` `comfortable` |
+| `fontSize` | `default` `smaller` `larger` |
+| `templateFont` | `Inter` `LatoFont` `Roboto` `Figtree` `SourceSans3` |
+| `templateStyle` | `REPORT_TEMPLATE_CLASSIC` `REPORT_TEMPLATE_BALANCED` `REPORT_TEMPLATE_MODERN` `REPORT_TEMPLATE_UNIFORM` |
+| `isDecorator`, `isUppercase` | booleans |
+| `lineBreak` | `L0` `L1` `L2` `L3`: spacer rows in Excel down to that tree level |
+| `pdfTitleConfigs` | `{ title, layout, headline, dateTitle, isUppercase }`; `layout` is `left_aligned` or `center_aligned`, `headline` is `HEADLINE_COMPANY_NAME` or `HEADLINE_REPORT_TITLE` |
+| `documentDetailConfigs` | `{ documentTitle, currency: { currencyCode, currencyName, currencySymbol }, enableOrganizationName, enableReportPeriod }`. An empty currency means the organization's own. |
+| `pageFooterConfigs` | `{ enablePageNumber, enableGeneratedBy, enableDatestamp, enableTimeStamp }` |
+| `footerDetailsConfigs` | `{ enableCurrencyDetails, enableReportNotes, enableRoundedValues }` |
+| `reportNotesConfig` | `{ reportNotesValue, reportNotesJson }`, both **base64-encoded** |
+| `documentLogo` | `[{ fileId, fileUrl, fileName, fileType }]` |
+| `sortConfigs` | `{ type, primarySortBy, secondarySortBy }`; `type` is `FIXED` or `CUSTOM`, each sort `CODE_ASC` `CODE_DESC` `NAME_ASC` `NAME_DESC` `AMOUNT_ASC` `AMOUNT_DESC` |
+
+**`dateTitle` placeholders:**
+- `{{DateAt}}`: balance sheet, trial balance, aging and cash balance.
+- `{{DateFrom}}` and `{{DateTo}}`: every period report.
+
+**`basePeriodConfig.periodType`** depends on whether the report covers a range or is as at a date. Dates are epoch milliseconds and are needed only for `custom`.
+- **Range reports:**
+  - `this_month` `last_month` `this_quarter` `last_quarter` `this_year` `last_year` `this_week`
+  - `this_financial_year` `last_financial_year` (also `previous_financial_year`)
+  - `this_financial_quarter` (also `this_financial_year_this_quarter`), `last_financial_quarter` (also `previous_financial_quarter`, `this_financial_year_last_quarter`)
+  - `custom`, with `startDate` and `endDate`
+- **As-at reports:**
+  - `today` `end_of_this_month` `end_of_last_month` `end_of_last_quarter` `end_of_last_financial_quarter` `end_of_last_financial_year`
+  - `custom`, with `endDate`
+
+### Columns
+
+`columnConfigs[].type` takes one of the following. With no `COMPARE` column, the engine adds one.
+
+| type | Config |
+|---|---|
+| `COMPARE` | `{ dateRange, compareWith: PREVIOUS_DAYS \| PREVIOUS_MONTHS \| PREVIOUS_QUARTERS \| PREVIOUS_YEARS, compareCount, columnOrder: RECENT_TO_OLDEST \| OLDEST_TO_RECENT }` |
+| `YEAR_TO_DATE` | `{ periodType: CALENDAR_YEAR \| FINANCIAL_YEAR, rangeType: THROUGH_TODAY \| THROUGH_PERIOD_END, columnNameType }` |
+| `VARIANCE` | `{ displayAs: ABSOLUTE \| PERCENTAGE, firstColumn, secondColumn }` |
+| `ACCOUNT_CODE` | Shows the account code column |
+| `TOTAL` | Total column |
+| `MONTH_TO_DATE` | Month to date |
+| `CURRENT_PERIOD` | The period itself |
+
+There is no budget column.
+
+### Per report type
+
+- **Trial balance, `reportSelectedColumns`:** `accountCode` `accountName` `accountType` `status` `accountCurrency` `debitAmount` `creditAmount` `debitAmountIso` `creditAmountIso`.
+- **Aged receivables / payables summary, `reportSelectedColumns`:**
+  - Name: `customerName` (payables: `supplierName`).
+  - Buckets: `current` `lessThanOneMonth` `oneMonth` `twoMonths` `threeMonths` `older` `balance`.
+  - Optional: `customerTaxId` / `supplierTaxId`, `contactGroup`, `contactRelationship`, `balanceSource`.
+- **General ledger:**
+  - `groupByConfigs.groupBy` is one of `ACCOUNT` `CONTACT` `TRANSACTION` `RELATIONSHIP` `CAPSULE`.
+  - `groupByColumns` is `[{ type: <groupBy>, columns: [codes] }]`; the entry matching the active groupBy is used.
+  - Column codes: `vldt` date, `btty` type, `trde` description, `btrf` reference, `acna` account, `acty` account type, `cnnm` contact, `debt` debit, `crdt` credit, `amnt` balance, `scc` source currency, `rsf` rate, `sca`/`sda` source credit/debit, `tags` tags, `cpsl` capsule, `cogr` contact groups, `corl` contact relationships, `clfs` classifiers, `ntr` nature.
+- **Aging details:** `groupBy` is `CONTACT` `CONTACT_GROUP` `DUE_MONTH` `RELATIONSHIP` or `CURRENCY`.
+- **Tax ledger:** groups by tax return box (e.g. `IRAS_F5`).
+
+### Rows (profit and loss, balance sheet, cashflow)
+
+`rowConfigs` is a tree, and each row has these fields:
+
+| Field | Meaning |
+|---|---|
+| `id` | Unique in the layout. A system group (`OPERATING_REVENUE`) or an account's resourceId (an account row). |
+| `name` | Label shown on the report |
+| `rowType` | `GROUP` collects accounts. `SECTION` is structure only. `TOTAL` is a formula. `COMBINE_ACCOUNT` merges accounts into one line. `TEXT` is a label. `ROW` is one account. `GROUP_TOTAL` is a group's total line (id `<group id>__GT`), which the dashboard stores for every group that shows its total. |
+| `actionCriteria` | Which accounts a `GROUP` collects: `[{ criteriaVariable, criteriaCondition, criteriaValue }]`, all must match |
+| `formulaConfig.formula` | For `TOTAL`: row ids joined by `+` / `-`, e.g. `OPERATING_REVENUE-COST_OF_SALE`. A group whose id is a UUID is written `GT(<uuid>)`, so its dashes are not read as minus signs. **A missing id silently counts as 0.** |
+| `showGroupTotal`, `hideGroupIfAllRowsHidden`, `hideRowIfZeroValue` | Display switches |
+| `negativeBalanceCriteria` | `MOVE_TO` another group when negative (the only action the engine applies) |
+| `children` | Nested rows |
+
+**Criteria fields:**
+- `criteriaVariable`: `ACCOUNT_TYPE` `ACCOUNT_CODE` `ACCOUNT_NAME` `ACCOUNT_CLASS`.
+- `criteriaCondition`: `IS` `IS_NOT` `IS_IN` `IS_NOT_IN` `CONTAINS` `DOES_NOT_CONTAIN` `STARTS_WITH` `ENDS_WITH`. Matching ignores case.
+- `IS_IN A|B` works for `ACCOUNT_TYPE` only. Account types are written uppercase with underscores (`OPERATING_REVENUE`).
+
+**Totals the engine reads by id.** Removing one changes the report silently, so `edits` refuses it:
+- **P&L:**
+  - `TOTAL_GROSS_PROFIT`, `TOTAL_OPERATING_PROFIT`, `TOTAL_OTHER_PROFIT`
+  - `TOTAL_NET_PROFIT`, `TOTAL_NET_PROFIT_BEFORE_TAX`, `TOTAL_NET_PROFIT_AFTER_TAX`
+  - IFRS 18 only: `TOTAL_PBFIT`, `TOTAL_PROFIT_BEFORE_INCOME_TAX`, `TOTAL_PROFIT`
+- **Balance sheet:** `TOTAL_ASSETS`, `TOTAL_LIABILITIES_AND_EQUITY`.
+- **Cashflow:** `NET_CASHFLOW`, `CASH_SUMMARY_BEGINNING_CASH_BALANCE`, `CASH_SUMMARY_NET_INCREASE_IN_CASH`, `CASH_SUMMARY_ENDING_CASH_BALANCE`.
+
+---
+
+## Report packs
+
+| Key | Values |
+|---|---|
+| `reportPackType` | `ACCOUNTING` `FINANCIALS` `MANAGEMENT` `PAYABLES` `RECEIVABLES` `CUSTOM` |
+| `decorator` | `FIRST_PAGE_ONLY` `ALL_PAGES` `NO_DECORATOR` |
+| `roundedValuesMode` | `AS_PER_TEMPLATE` `ROUNDED_VALUES` `EXACT_VALUES` |
+| `basePeriodConfig`, `templateFont`, `isUppercase`, `enablePageNumber` | as above |
+| `includedComponents` | The document, in order. Each entry is `{ id, type, <config> }`. |
+
+**Component types:**
+
+| type | Config |
+|---|---|
+| `COVER_PAGE` | `coverPageConfig { title, subtitle, notes, position, logo[], enableOrganizationName, enableReportPeriod, enablePreparedBy }` |
+| `TABLE_OF_CONTENTS` | `tableOfContentsConfig { title, position, dotLeaders: DOTS \| DASHES \| NONE, startNumberingAt: <component id>, enableSerialNumber }` |
+| `TEMPLATE` | One report: `templateConfig { templateResourceId, templateName, reportType }` |
+| `SIGNATURE_PAGE` | `signaturePageConfig { title, notes, position, labelLines: [{ label, enabled }] }` |
+| `APPENDIX` | `appendixPageConfig { title, position, appendixNotesConfig }` |
+
+Cover and notes text may use `{{OrganizationName}}`, `{{PreparedBy}}`, `{{DateFrom}}` and `{{DateTo}}`.
+
+**A pack's reports are recorded twice upstream**: in its `TEMPLATE` components and in `packTemplates`. A report missing from either renders as an error page. Clio keeps them in step with one rule:
+- **`packTemplates` decides which reports** are in the pack. Give it names or resourceIds, in order. Clio writes both places from it.
+- **The layout decides everything else**: cover page, contents, signature, styling. Change those with `edits`. Use `insert` (not `set`) to add a component.
+- **Edits that would change the reports are refused** instead of silently dropping one.
+- A new pack starts with its reports and nothing else. Upstream has no default pack layout.
+- A pack cannot contain a pack. The first pack an organization creates becomes its default pack.
+
+```bash
+clio report-templates create --name "Board pack" --type REPORT_PACK \
+  --report "Board P&L" --report "Standard Balance Sheet" --set reportPackType=MANAGEMENT
+```
+
+---
+
+## Rules and refusals
+
+| Situation | Result |
+|---|---|
+| Name already used by a template of the same type | Refused before sending. Names are unique per report type, ignoring case and treating space and `_` alike. |
+| The same name on another report type | Allowed |
+| Name blank or only spaces | Refused (upstream accepts whitespace; Clio does not) |
+| `framework` on a type without one | Refused |
+| `framework` GAAP / IND_AS / IFRS_SME on a P&L or cashflow with no layout | `422 NO_TEMPLATE_FOUND`, with a hint to use IAS_1 / IFRS_18 or start from an existing layout |
+| `framework` not one of the five, or on a type without one | Refused before sending, naming the allowed values |
+| A whole replacement layout that leaves out a key the stored one has, or introduces a problem | Refused (the usual cause is a file written from part of a layout) |
+| Update with nothing to change | Refused |
+| Report type or framework on update | Cannot change. Upstream ignores them silently. |
+| Delete the default of a report type | Refused; set another default first (the error names candidates) |
+| Delete a pack's last report | Refused by Clio. Upstream deletes it whenever the pack has any other component (a cover page, say), leaving a pack with no reports. |
+| Delete a report that is in a pack with others | Allowed. It leaves each pack; the answer lists them in `removedFromPacks`. |
+| Delete the default pack | Allowed. The newest remaining pack becomes default, named in `newDefault`. |
+| Set default | Every export and dashboard view of that report changes, org-wide. The answer carries `previousDefault` to undo. Already default: nothing is sent. |
+| A new template straight after create | Can 404 for a moment; the read-back retries briefly |
+| Two edits to the same template at the same moment | The last write wins: upstream has no version check. Clio re-reads just before writing and re-applies its edits on anything changed since it first read, which keeps an earlier change; it cannot protect against one sent in the same instant. |
+| A pack whose layout and report list disagree (written by another client) | A styling edit is refused, naming both lists; pass `packTemplates` to set the reports, and both are rewritten from it |
+| A whole layout on create | Must have every top-level key the report type's default has, and no refused value |
+| `--set path=value` on the CLI | The text is read as the kind of value already stored there: a title stays text, a flag becomes true/false, a list or object is parsed as JSON |
+
+### Rendering
+
+`download_export` / `clio exports download` take `template` (name or resourceId). Clio checks that the template exists and is of that export's report type before asking for the file.
+
+**Upstream answers a template it cannot use with HTTP 200 and an EMPTY body.** That covers a template that doesn't exist, one of another report type, or an unknown `templateName`, and was measured on all 12 exports. If you pass `templateResourceId` directly, Clio turns that empty answer into a named error instead of retrying it.
+
+`fixed-assets-register` accepts a template id and ignores it.
+
+### Search
+
+Upstream's search endpoint answers 500 for four of its five filters, and has no name filter, so `search_organization_report_templates` filters the full list instead. That matches because the list is every template at once. It uses the same filter grammar, plus `templateName`:
+
+```jsonc
+{ "filter": { "or": [ { "templateName": { "contains": "board" } }, { "isDefault": { "eq": true }, "reportType": "REPORT_PACK" } ] } }
+```
+
+- **Fields:**
+  - `resourceId`, `templateName`, `reportType`, `reportCategory` (string operators)
+  - `reportTypes` (a list)
+  - `isDefault`
+  - `and` / `or`
+- **String operators:** `eq` `neq` `in` `contains` `notContains` `likeIn` `reg` `startWith` `notStartWith` `endWith` `isNull`. The `contains` family ignores case.
+- **Sort:** `reportType` `templateName` `isDefault` `resourceId`.
+- An unknown field or operator is refused rather than matching everything.

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

@@ -548,7 +548,7 @@ All search endpoints return:
 }
 ```
 
-**Exception**: `GET /organization-report-template` returns its rows under a `reportTemplates` key, not `data` (measured 2026-09-06). Its `/search` sibling returns a **bare array** with no envelope (measured 2026-09-07). The tools normalize the list; read `.data` on both.
+**Exception**: `GET /organization-report-template` returns its rows under a `reportTemplates` key, not `data` (measured 2026-09-06). Its `/search` sibling returns a **bare array** with no envelope (measured 2026-09-07). The tools normalize the list; read `.data` on both. Since 2026-09-24 the report template search tool filters the list itself instead of calling `/search`, because four of the search endpoint's five filters answer 500; it takes the same filter grammar plus `templateName` (`references/report-templates.md`).
 
 ---
 

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

@@ -28,7 +28,7 @@ All search endpoints share this identical structure:
 
 **Response shape**: `{ totalElements, totalPages, data: [...] }`; all search/list endpoints return this flat structure directly (no outer `data` wrapper).
 
-> **Exception**: the two halves of this family answer differently upstream. `POST /organization-report-template/search` returns a **bare array** with no envelope; `GET /organization-report-template` returns its rows under a **`reportTemplates`** key with no counts. Measured 2026-09-07: the two halves disagree with each other and with the house style. The tools normalize the list, so you always read `.data`.
+> **Exception**: the two halves of this family answer differently upstream. `POST /organization-report-template/search` returns a **bare array** with no envelope; `GET /organization-report-template` returns its rows under a **`reportTemplates`** key with no counts. Measured 2026-09-07: the two halves disagree with each other and with the house style. The tools normalize the list, so you always read `.data`. The report template search tool does not call `/search` at all: four of its five filters answer 500 upstream (re-measured 2026-09-24), so it filters the full list with the same grammar plus `templateName`. See `references/report-templates.md`.
 
 ---