jaz-clio 5.34.0 → 5.35.0

package/README.md

@@ -52,6 +52,29 @@ clio invoices search --query 'status:unpaid AND $500+' # structured per-entity s
 
 66 command groups, 16 report types, 13 calculators, 12 job playbooks. Every command takes `--json`. Run `clio --help` for the full list.
 
+### Foreign currency
+
+Rates read **base→source**: `1` unit of your organization's base currency `= N` units of the
+foreign one. Whether that matches how the rate was quoted to you depends on which side your base
+currency is on — an SGD-base org quoting "1 USD = 1.35 SGD" has it backwards and needs `0.74`, while
+a USD-base org quoting "1 USD = 56.5 PHP" already has it right and sends `56.5` unchanged.
+
+You do not have to flip it. Pass the number as you have it and say which way it reads:
+
+```bash
+# "1 USD = 1.35 SGD", from a bank statement, on an SGD-base org
+clio invoices create --currency USD --exchange-rate 1.35 \
+  --rate-direction SOURCE_TO_FUNCTIONAL ...
+
+# 0.74, straight out of clio currency-rates list
+clio invoices create --currency USD --exchange-rate 0.74 ...
+```
+
+Omit `--exchange-rate` entirely to use the organization's stored rate, or the platform daily rate
+when none is set. `clio calc fx-reval` requires `--rate-direction` explicitly — that calculator
+takes rates in the opposite direction to the API, and guessing would silently change a number
+that ends up in a journal.
+
 ## MCP server
 
 358 tools for any AI agent that speaks MCP. Runs locally: no cloud, no ports.

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 5.34.0
+version: 5.35.0
 description: >-
   Use this skill whenever you call, debug, or review code that touches the Jaz
   REST API. Covers field names, response shapes, 158 production gotchas, error
@@ -106,8 +106,8 @@ The rest of this skill — field names, gotchas, error catalog, dependency order
 
 ### Journals & Cash
 23. **Journals use `journalEntries`** with `amount` + `type: "DEBIT"|"CREDIT"` — NOT `debit`/`credit` number fields.
-24. **Journals support multi-currency via `currency` object** — same format as invoices/bills: `"currency": { "sourceCurrency": "USD" }` (auto-fetch platform rate) or `"currency": { "sourceCurrency": "USD", "exchangeRate": 1.35 }` (custom rate). Must be enabled for the org. Omit for base currency. Three restrictions apply to foreign currency journals: (a) **no controlled accounts** — accounts with `controlFlag` (AR, AP) are off-limits (use invoices/bills instead), (b) **no FX accounts** — FX Unrealized Gain/Loss/Rounding are system-managed, (c) **bank accounts must match** — can only post to bank accounts in the same currency as the journal (e.g., USD journal → USD bank account only, not SGD bank account). All other non-controlled accounts (expenses, revenue, assets, liabilities) are available.
-25. **`currency` object is the SAME everywhere** — invoices, bills, credit notes, AND journals all use `currency: { sourceCurrency: "USD", exchangeRate?: number }`. Never use `currencyCode: "USD"` (silently ignored on invoices/bills) or `currency: "USD"` (string — causes 400 on invoices/bills).
+24. **Journals support multi-currency via `currency` object** — same format as invoices/bills: `"currency": { "sourceCurrency": "USD" }` (auto-fetch platform rate) or `"currency": { "sourceCurrency": "USD", "exchangeRate": 0.74 }` (custom rate). Must be enabled for the org. Omit for base currency. **Direction**: `exchangeRate` is functionalToSource (1 org-base unit = N `sourceCurrency`) — usually the inverse of a quoted rate. Pass your figure as-is with `rateDirection` rather than inverting by hand; Rule 49. Three restrictions apply to foreign currency journals: (a) **no controlled accounts** — accounts with `controlFlag` (AR, AP) are off-limits (use invoices/bills instead), (b) **no FX accounts** — FX Unrealized Gain/Loss/Rounding are system-managed, (c) **bank accounts must match** — can only post to bank accounts in the same currency as the journal (e.g., USD journal → USD bank account only, not SGD bank account). All other non-controlled accounts (expenses, revenue, assets, liabilities) are available.
+25. **`currency` object is the SAME everywhere** — invoices, bills, credit notes, AND journals all use `currency: { sourceCurrency: "USD", exchangeRate?: number, rateDirection?: "FUNCTIONAL_TO_SOURCE" | "SOURCE_TO_FUNCTIONAL" }`. **Direction**: `exchangeRate` is functionalToSource (1 org-base unit = N `sourceCurrency`) — usually the inverse of a quoted rate. Pass your figure as-is with `rateDirection` rather than inverting by hand; Rule 49. Never use `currencyCode: "USD"` (silently ignored on invoices/bills) or `currency: "USD"` (string — causes 400 on invoices/bills).
 26. **Cash entries use `accountResourceId`** at top level for the BANK account + `lines` array for offsets.
 
 ### Credit Notes & Refunds
@@ -164,8 +164,8 @@ The rest of this skill — field names, gotchas, error catalog, dependency order
 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`.
 
 ### Other
-39. **Currency rates use `/organization-currencies/:code/rates`** — note the HYPHENATED path (NOT `/organization/currencies`). 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). Cannot set rates for org base currency. Full CRUD: POST (create), GET (list), GET/:id, PUT/:id, DELETE/:id.
-40. **FX invoices/bills MUST use `currency` object** — `currencyCode: "USD"` (string) is **silently ignored** (transaction created in base currency!). Use `currency: { sourceCurrency: "USD" }` to auto-fetch platform rate (ECB/FRANKFURTER), or `currency: { sourceCurrency: "USD", exchangeRate: 1.35 }` for a custom rate. Rate hierarchy: org rate → platform/ECB → transaction-level.
+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 marked **deprecated** in the OpenAPI spec — prefer the nested form. Cannot set rates for org base currency. Full CRUD: POST (create), GET (list), GET/:id, PUT/:id, DELETE/:id.
+40. **FX invoices/bills MUST use `currency` object** — `currencyCode: "USD"` (string) is **silently ignored** (transaction created in base currency!). Use `currency: { sourceCurrency: "USD" }` to auto-fetch platform rate (ECB/FRANKFURTER), or `currency: { sourceCurrency: "USD", exchangeRate: 0.74 }` for a custom rate. Rate hierarchy: org rate → platform/ECB → transaction-level. **Direction**: `exchangeRate` is functionalToSource (1 org-base unit = N `sourceCurrency`) — usually the inverse of a quoted rate. Pass your figure as-is with `rateDirection` rather than inverting by hand; Rule 49.
 41. **Invoice GET uses `organizationAccountResourceId`** for line item accounts — POST uses `accountResourceId`. Request-side aliases resolve `issueDate` → `valueDate`, `bankAccountResourceId` → `accountResourceId`, etc.
 42. **Scheduler GET returns `interval`** — POST uses `repeat`. (Response-side asymmetry remains.)
 43. **Search sort is an object** — `{ sort: { sortBy: ["valueDate"], order: "DESC" } }`. Required when `offset` is present (even `offset: 0`).
@@ -174,7 +174,7 @@ The rest of this skill — field names, gotchas, error catalog, dependency order
 46. **Known API bugs (500s)**: Contact groups PUT (nil pointer on search response), custom fields PUT (dangling stack pointers in mapping), capsules POST (upstream returns nil), catalogs POST, inventory balances by status GET (`/inventory-balances/:status`, missing `c.Bind`) — all return 500.
 47. **Non-existent endpoints**: `POST /deposits`, `POST /inventory/adjustments`, `GET /payments` (list), and `POST /payments/search` return 404 — these endpoints are not implemented. To list/search payments, use `POST /cashflow-transactions/search` (the unified transaction ledger — see Rule 63).
 48. **Attachments — full CRUD**: **Add**: `POST /:type/:id/attachments` (multipart, `file` field, `application/pdf` or `image/*` — NOT `text/plain`). **List**: `GET /:type/:id/attachments`. **Delete**: `DELETE /:type/:id/attachments/:attachmentResourceId` (HTTP 200). CLI: `clio attachments add --file <path>` or `--url <url>`, `clio attachments list`, `clio attachments delete <attachmentResourceId>`. **Response shape is non-standard**: `{ reference, resourceId, attachments: [{fileName, fileType, fileId, attachmentResourceId}] }` — NOT `{ data: [...] }`. The attachment ID field is `attachmentResourceId` (not `resourceId`).
-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).
+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`, the same enum `bulk_upsert_currency_rates` sends on the wire) — declare how your figure reads and pass it verbatim; the client inverts and strips the label, which is never transmitted. Prefer this 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.
@@ -532,7 +532,7 @@ When the user wants to OPEN, SEE, or SHARE something in the Jaz dashboard ("open
 - **Bank records**: Create via JSON `POST /bank-records/:id` or multipart `POST /magic/importBankStatementFromAttachment`. Search via `POST /bank-records/:id/search` with filters (valueDate, status, description, extContactName, netAmount, extReference).
 - **Scheduled invoices/bills**: Wrap as `{ status, startDate, endDate, repeat, invoice/bill: { reference, valueDate, dueDate, contactResourceId, lineItems, saveAsDraft: false } }`. `reference` is required.
 - **Scheduled journals**: Flat: `{ status, startDate, endDate, repeat, valueDate, schedulerEntries, reference }`. `valueDate` is required.
-- **FX currency (invoices, bills, credit notes, AND journals)**: `currency: { sourceCurrency: "USD" }` (auto-fetches platform rate) or `currency: { sourceCurrency: "USD", exchangeRate: 1.35 }` (custom rate). Same object form on all transaction types. **Never use `currencyCode` string** — silently ignored.
+- **FX currency (invoices, bills, credit notes, AND journals)**: `currency: { sourceCurrency: "USD" }` (auto-fetches platform rate) or `currency: { sourceCurrency: "USD", exchangeRate: 0.74 }` (custom rate). Same object form on all transaction types. **Never use `currencyCode` string** — silently ignored.
 
 158. **Match-to-EXISTING reconciliation — `reconcile_with_payments` / `reconcile_magic_match` / `reconcile_learned_prediction`.** These reconcile a bank entry against transactions/payments the org ALREADY has, vs `invoice_receipt`/`bill_receipt` which CREATE new ones. Prefer match-to-existing to avoid duplicates.
     - **`reconcile_with_payments`** — the headline. `businessTransactionPayments[]` each carry an open bill/invoice's `cashflowTransactionResourceId` (from `search_cashflow_transactions` or a suggestion's `cftBtResourceId`) + `transactionAmount`; the endpoint CREATES the payment AND reconciles in one call — **no `pay_bill`/`pay_invoice` first.** Also accepts `matchedPayments[]` (existing payments) / `matchedBatchPayments[]` / `adjustment` (over/under-payment + FX write-off). Guard: ≥1 match array non-empty. **FX is auto-resolved server-side — pass NO `currencySettings`/rate for the common case.** Only the rare bill-currency ≠ bank-currency case needs explicit `paymentAmount` (bank ccy) + `currencySettings`. FX gain/loss is NOT auto-posted — post it via `adjustment.cashAdjustmentEntries[]` to an FX account. Errors: `PAYMENT_AMOUNT_REQUIRED_IN_BUSINESS_TRANSACTION_SOURCE_CURRENCY` (cross-ccy missing paymentAmount), `INVALID_EXCHANGE_RATE_ERROR` (adjustment leg in non-functional ccy missing rate), `TOTAL_RECONCILIATION_AMOUNT_MISMATCHED_WITH_STATEMENT_ENTRY_AMOUNT` (sum ≠ entry → add adjustment leg). **NOT idempotent, no client key — a blind retry double-creates a payment; re-check `search_bank_records(status:'RECONCILED')` before retry.**

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

@@ -289,11 +289,11 @@ Enable currencies first, then set rates via the **separate** rate endpoints belo
 - To check before enabling: `GET /organization/currencies` and check if the code is already in the list.
 - Sending an empty array `{ "currencies": [] }` returns 400.
 
-### Currency Rates — `/organization-currencies` (hyphenated path)
+### Currency Rates — `/organization/currencies/:code/rates`
 
-**CRITICAL path difference**: Enable uses `/organization/currencies` (nested). Rates use `/organization-currencies` (hyphenated). Using the wrong path returns 404.
+**Path note**: both enable and rates live under the nested `/organization/currencies` family. The older hyphenated `/organization-currencies/...` rate paths still resolve but are marked **deprecated** in the OpenAPI spec — use the nested form.
 
-#### POST /api/v1/organization-currencies/:currencyCode/rates
+#### POST /api/v1/organization/currencies/:currencyCode/rates
 
 ```json
 // Request:
@@ -304,16 +304,16 @@ Enable currencies first, then set rates via the **separate** rate endpoints belo
 // HTTP 201
 ```
 
-**CRITICAL**: Response `data` is a **plain string** `"Rate added successfully"` — NOT a CurrencyRate object. You do NOT get back a `resourceId`. If you need the rate's `resourceId` (e.g., for later PUT/DELETE), you must follow up with `GET /organization-currencies/:code/rates` and match by `rateApplicableFrom` date.
+**CRITICAL**: Response `data` is a **plain string** `"Rate added successfully"` — NOT a CurrencyRate object. You do NOT get back a `resourceId`. If you need the rate's `resourceId` (e.g., for later PUT/DELETE), you must follow up with `GET /organization/currencies/:code/rates` and match by `rateApplicableFrom` date.
 
 **Required fields**:
-- `rate` — positive number (must be > 0). Direction is **functionalToSource** (1 base = X foreign). Example for SGD org setting USD rate: `rate: 0.74` means 1 SGD = 0.74 USD. **If your data is sourceToFunctional (1 USD = 1.35 SGD), invert: `rate = 1 / yourRate`.**
+- `rate` — positive number (must be > 0). Direction is **functionalToSource** (1 base = X foreign). Example for SGD org setting USD rate: `rate: 0.74` means 1 SGD = 0.74 USD. **If your data is sourceToFunctional (1 USD = 1.35 SGD), invert: `rate = 1 / yourRate`.** You do not have to do this by hand: pass your figure as-is with `rateDirection` (`FUNCTIONAL_TO_SOURCE` | `SOURCE_TO_FUNCTIONAL`) and the client inverts and strips it. See SKILL.md Rule 49.
 - `rateApplicableFrom` — `YYYY-MM-DD` string (NOT ISO datetime — `"2026-02-10T00:00:00Z"` is rejected with "does not match 2006-01-02 format")
 
 **Optional fields**:
 - `rateApplicableTo` — `YYYY-MM-DD` string. Must be after `rateApplicableFrom` (422 `INVALID_DATE_RANGE` otherwise).
 
-#### GET /api/v1/organization-currencies/:currencyCode/rates
+#### GET /api/v1/organization/currencies/:currencyCode/rates
 
 ```json
 // Response:
@@ -335,7 +335,7 @@ Enable currencies first, then set rates via the **separate** rate endpoints belo
 }
 ```
 
-#### PUT /api/v1/organization-currencies/:currencyCode/rates/:resourceId
+#### PUT /api/v1/organization/currencies/:currencyCode/rates/:resourceId
 
 ```json
 // Request:
@@ -346,7 +346,7 @@ Enable currencies first, then set rates via the **separate** rate endpoints belo
 // HTTP 200
 ```
 
-#### DELETE /api/v1/organization-currencies/:currencyCode/rates/:resourceId
+#### DELETE /api/v1/organization/currencies/:currencyCode/rates/:resourceId
 
 ```json
 // Response:
@@ -371,12 +371,12 @@ Create exchange rates in bulk (max 500). **Auto-enables currencies not yet enabl
     {
       "sourceCurrencyCode": "USD",
       "rate": 1.35,
-      "rateDirection": "FUNCTIONAL_TO_SOURCE",
+      "rateDirection": "SOURCE_TO_FUNCTIONAL",
       "rateApplicableFrom": "2026-03-29"
     },
     {
       "sourceCurrencyCode": "EUR",
-      "rate": 1.48,
+      "rate": 0.68,
       "rateDirection": "FUNCTIONAL_TO_SOURCE",
       "rateApplicableFrom": "2026-03-29",
       "rateApplicableTo": "2026-04-30"
@@ -388,7 +388,7 @@ Create exchange rates in bulk (max 500). **Auto-enables currencies not yet enabl
 { "data": { "resourceId": null, "resourceIds": ["uuid1", "uuid2"] } }
 ```
 
-`rateDirection`: `FUNCTIONAL_TO_SOURCE` (e.g., 1 SGD = 1.35 USD) or `SOURCE_TO_FUNCTIONAL` (e.g., 1 USD = 0.74 SGD). Unlike the single-rate POST endpoint, this returns `resourceIds` directly.
+`rateDirection` (SGD-base org, USD source): `FUNCTIONAL_TO_SOURCE` means the value is source-per-base — 1 SGD = 0.74 USD → send `0.74`. `SOURCE_TO_FUNCTIONAL` means base-per-source — 1 USD = 1.35 SGD → send `1.35` as-is, no inversion. This is the ONLY rate endpoint that accepts the everyday quote directly; the single-rate POST always wants `FUNCTIONAL_TO_SOURCE`. Unlike the single-rate POST endpoint, this returns `resourceIds` directly.
 
 ---
 
@@ -547,7 +547,7 @@ Create defaults: `status=ACTIVE`, `itemCategory=NON_INVENTORY`. Update: only sen
 - **`currency: "USD"` (string)** causes "Invalid request body" error (400).
 
 **Rate hierarchy** (when using `currency: { sourceCurrency }` without `exchangeRate`):
-1. Org-level rate (set via `/organization-currencies/:code/rates`) — auto-filled if exists
+1. Org-level rate (set via `/organization/currencies/:code/rates`) — auto-filled if exists
 2. Platform rate (ECB via FRANKFURTER) — auto-fetched if no org rate
 3. Transaction-level rate (via `exchangeRate` in the `currency` object) — overrides all
 
@@ -2078,7 +2078,7 @@ Update an existing payment record. All fields optional — only included fields
   "valueDate": "2026-03-02",
   "paymentMethod": "BANK_TRANSFER",
   "accountResourceId": "uuid-bank",
-  "currency": { "sourceCurrency": "USD", "exchangeRate": 1.35 },
+  "currency": { "sourceCurrency": "USD", "exchangeRate": 0.74 },
   "transactionFee": 5.00,
   "transactionFeeCollected": true
 }

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

@@ -175,21 +175,23 @@ Valid `type` values: `"TEXT"`, `"DATE"`, `"DROPDOWN"` (UPPERCASE).
 
 ## Currency Errors
 
-### 404 on rate endpoints — WRONG PATH (common mistake)
-**Cause**: Using `/organization/currencies` (nested) instead of `/organization-currencies` (hyphenated) for rate endpoints.
+### 404 on rate endpoints — MALFORMED PATH (common mistake)
+**Cause**: Omitting the currency code, or using singular `rate` instead of `rates`.
 **Endpoints that 404 (wrong paths)**:
-- `/api/v1/organization/currencies/rates` → 404
-- `/api/v1/organization/currencies/USD/rate` → 404
-- `/api/v1/organization/currencies/{id}/rate` → 404
-**Fix**: Rate endpoints use the **hyphenated** path `/organization-currencies` (NOT `/organization/currencies`):
+- `/api/v1/organization/currencies/rates` → 404 (no currency code)
+- `/api/v1/organization/currencies/USD/rate` → 404 (singular)
+- `/api/v1/organization/currencies/{id}/rate` → 404 (singular)
+**Fix**: Rate endpoints live under the nested `/organization/currencies` family. The older
+hyphenated `/organization-currencies/...` rate paths still resolve but are marked
+**deprecated** in the OpenAPI spec — prefer the nested form:
 ```
-POST   /api/v1/organization-currencies/:currencyCode/rates          Set rate
-GET    /api/v1/organization-currencies/:currencyCode/rates          List rates
-GET    /api/v1/organization-currencies/:currencyCode/rates/:id      Get rate
-PUT    /api/v1/organization-currencies/:currencyCode/rates/:id      Update rate
-DELETE /api/v1/organization-currencies/:currencyCode/rates/:id      Delete rate
+POST   /api/v1/organization/currencies/:currencyCode/rates          Set rate
+GET    /api/v1/organization/currencies/:currencyCode/rates          List rates
+GET    /api/v1/organization/currencies/:currencyCode/rates/:id      Get rate
+PUT    /api/v1/organization/currencies/:currencyCode/rates/:id      Update rate
+DELETE /api/v1/organization/currencies/:currencyCode/rates/:id      Delete rate
 ```
-Enable currencies first via `POST /organization/currencies`, then set rates via `/organization-currencies/:code/rates`.
+Enable currencies first via `POST /organization/currencies`, then set rates via `/organization/currencies/:code/rates`.
 
 ### "Cannot set rate for organization base currency" (400)
 **Cause**: Trying to POST/PUT a rate for the org's base currency (e.g., SGD for a Singapore org).
@@ -208,7 +210,7 @@ Enable currencies first via `POST /organization/currencies`, then set rates via
 **Fix**: Ensure `rateApplicableTo` is after `rateApplicableFrom`, or omit `rateApplicableTo` entirely.
 
 ### Rates appear inverted (wrong direction)
-**Cause**: POSTing a sourceToFunctional rate (1 foreign = X base) as the `rate` field, which expects functionalToSource (1 base = X foreign).
+**Cause**: POSTing a sourceToFunctional rate (1 foreign = X base) as the `rate` field, which expects functionalToSource (1 base = X foreign). You do not have to do this by hand: pass your figure as-is with `rateDirection` (`FUNCTIONAL_TO_SOURCE` | `SOURCE_TO_FUNCTIONAL`) and the client inverts and strips it. See SKILL.md Rule 49.
 **Symptom**: UI shows "1 SGD = 0.0088 JPY" instead of "1 SGD ≈ 111 JPY" — the reciprocal of what you intended.
 **Fix**: Invert before POSTing: `rate = 1 / yourRate`. If your data says "1 JPY = 0.009 SGD", POST `rate: 111.11`.
 
@@ -241,11 +243,11 @@ Enable currencies first via `POST /organization/currencies`, then set rates via
 **Rate sources in response** (inspect `currencyExchange.rateSource`):
 - `rateSource: "EXTERNAL"`, `providerName: "FRANKFURTER"` — auto-fetched from ECB
 - `rateSource: "INTERNAL_TRANSACTION"`, `providerName: "CUSTOM"` — user-specified `exchangeRate`
-- `rateSource: "INTERNAL_ORG"` — org-level rate (set via `/organization-currencies/:code/rates`)
+- `rateSource: "INTERNAL_ORG"` — org-level rate (set via `/organization/currencies/:code/rates`)
 
 ### "Invalid request body" (400) — `currency` as string
 **Cause**: Using `currency: "USD"` (string) instead of object form.
-**Fix**: Use object form `currency: { sourceCurrency: "USD" }` or `currency: { sourceCurrency: "USD", exchangeRate: 1.35 }`.
+**Fix**: Use object form `currency: { sourceCurrency: "USD" }` or `currency: { sourceCurrency: "USD", exchangeRate: 0.74 }`.
 
 ---
 
@@ -617,7 +619,7 @@ if (acct.code) ctx.coaIds[acct.code] = acct.resourceId;
 ## Journal Errors
 
 ### Multi-currency journals — `currency` object
-Journals support a top-level `currency` object to create entries in a foreign currency — **same format as invoices/bills**: `{ "sourceCurrency": "USD" }` (auto-fetch platform rate) or `{ "sourceCurrency": "USD", "exchangeRate": 1.35 }` (custom rate). The currency must be enabled for the org. Omit the field for base currency journals.
+Journals support a top-level `currency` object to create entries in a foreign currency — **same format as invoices/bills**: `{ "sourceCurrency": "USD" }` (auto-fetch platform rate) or `{ "sourceCurrency": "USD", "exchangeRate": 0.74 }` (custom rate). The currency must be enabled for the org. Omit the field for base currency journals.
 
 ```json
 // Base currency journal (omit currency):
@@ -627,7 +629,7 @@ Journals support a top-level `currency` object to create entries in a foreign cu
 { "saveAsDraft": false, "reference": "JV-001", "valueDate": "2026-02-08", "currency": { "sourceCurrency": "USD" }, "journalEntries": [...] }
 
 // Foreign currency journal (custom rate):
-{ "saveAsDraft": false, "reference": "JV-001", "valueDate": "2026-02-08", "currency": { "sourceCurrency": "USD", "exchangeRate": 1.35 }, "journalEntries": [...] }
+{ "saveAsDraft": false, "reference": "JV-001", "valueDate": "2026-02-08", "currency": { "sourceCurrency": "USD", "exchangeRate": 0.74 }, "journalEntries": [...] }
 ```
 
 **Three restrictions apply to foreign currency journals:**

package/assets/skills/api/references/feature-glossary.md

@@ -229,7 +229,7 @@ Fixed assets lock their linked line items — cannot edit account, amounts, or e
 
 **User Roles**: Admin (full access), Preparer (create drafts, submit for approval), Member (own drafts only). Granular permissions by module (AR, AP, Treasury, Journals).
 
-**API**: CRUD `GET/POST/PUT/DELETE /chart-of-accounts`, `POST /chart-of-accounts/bulk-upsert`, `POST /chart-of-accounts/search`, `GET /tax-profiles`, `POST /tax-profiles/search`, CRUD `GET/POST/PUT/DELETE /tags`, `POST /tags/search`, CRUD `GET/POST/PUT/DELETE /custom-fields`, `POST /custom-fields/search`, `POST /organization/currencies` (enable), `DELETE /organization/currencies/:code` (disable), `POST /organization-currencies/:code/rates` (set FX rate, CRUD), `GET /organization` (org details), CRUD `GET/POST/PUT/DELETE /organization/bookmarks`, CRUD `GET/POST/PUT/DELETE /nano-classifiers`, `POST /nano-classifiers/search`, `GET /organization-users`, `POST /organization-users/search`. Reference data: `GET /account-classifications`, `GET /withholding-tax-codes`, `GET /tax-types`, `GET /modules`
+**API**: CRUD `GET/POST/PUT/DELETE /chart-of-accounts`, `POST /chart-of-accounts/bulk-upsert`, `POST /chart-of-accounts/search`, `GET /tax-profiles`, `POST /tax-profiles/search`, CRUD `GET/POST/PUT/DELETE /tags`, `POST /tags/search`, CRUD `GET/POST/PUT/DELETE /custom-fields`, `POST /custom-fields/search`, `POST /organization/currencies` (enable), `DELETE /organization/currencies/:code` (disable), `POST /organization/currencies/:code/rates` (set FX rate, CRUD), `GET /organization` (org details), CRUD `GET/POST/PUT/DELETE /organization/bookmarks`, CRUD `GET/POST/PUT/DELETE /nano-classifiers`, `POST /nano-classifiers/search`, `GET /organization-users`, `POST /organization-users/search`. Reference data: `GET /account-classifications`, `GET /withholding-tax-codes`, `GET /tax-types`, `GET /modules`
 
 ---
 

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

@@ -213,7 +213,7 @@ When POSTing, `classificationType` must be one of these exact strings (same as `
 | `lines` | `journalEntries` | Same |
 | `entries` | `journalEntries` | Same |
 | `debit` / `credit` (entry) | `amount` + `type` | `amount`: number, `type`: `"DEBIT"` or `"CREDIT"` (UPPERCASE) |
-| `currency: "USD"` (string) | `currency: { sourceCurrency: "USD" }` | **Object form** — same as invoices/bills. Auto-fetches platform rate. Add `exchangeRate: 1.35` for custom rate. Omit for base currency. |
+| `currency: "USD"` (string) | `currency: { sourceCurrency: "USD" }` | **Object form** — same as invoices/bills. Auto-fetches platform rate. Add `exchangeRate: 0.74` for custom rate. Omit for base currency. |
 
 ### Bulk upsert (`POST /journals/bulk-upsert`)
 
@@ -460,7 +460,7 @@ DELETE → expects "A" (parentEntityResourceId, via /cash-entries/:id)
 
 | What You'd Guess | Actual API Field | Notes |
 |------------------|-------------------|-------|
-| `/organization/currencies/:code/rates` | `/organization-currencies/:code/rates` | **Hyphenated** path for rates (NOT nested) |
+| `/organization-currencies/:code/rates` (older docs) | `/organization/currencies/:code/rates` | Nested path is current; hyphenated form is **deprecated** in the spec |
 | `exchangeRate` (rate POST body) | `rate` | Just `rate`, not `exchangeRate` |
 | `effectiveDate` / `valueDate` / `date` | `rateApplicableFrom` | Rate start date, `YYYY-MM-DD` only |
 | `expiryDate` | `rateApplicableTo` | Optional rate end date |
@@ -470,9 +470,9 @@ DELETE → expects "A" (parentEntityResourceId, via /cash-entries/:id)
 | `baseCurrency` (GET response) | `functionalCurrencyCode` | The org's base currency code in rate response |
 | `notes` (GET response) | `notes: { date, name }` | Metadata object — `date` is the creation date, `name` is the creator |
 
-> **Rate direction cheat-sheet**: POST `rate` = GET `rateFunctionalToSource` = "1 base → X foreign". If your data is "1 foreign → X base", **invert before POSTing**.
+> **Rate direction cheat-sheet**: POST `rate` = GET `rateFunctionalToSource` = "1 base → X foreign". If your data is "1 foreign → X base", **invert before POSTing** — or set `rateDirection: "SOURCE_TO_FUNCTIONAL"` and let the client do it (Rule 49).
 
-**Rate POST response gotcha**: `POST /organization-currencies/:code/rates` returns `{ "data": "Rate added successfully" }` — a **plain string**, NOT a CurrencyRate object. No `resourceId` is returned. To get the rate's `resourceId` for later PUT/DELETE, follow up with GET and match by `rateApplicableFrom`.
+**Rate POST response gotcha**: `POST /organization/currencies/:code/rates` returns `{ "data": "Rate added successfully" }` — a **plain string**, NOT a CurrencyRate object. No `resourceId` is returned. To get the rate's `resourceId` for later PUT/DELETE, follow up with GET and match by `rateApplicableFrom`.
 
 ---
 
@@ -582,8 +582,8 @@ DELETE → expects "A" (parentEntityResourceId, via /cash-entries/:id)
 | `GET /organization/currencies` | `{ data: { data: [...] } }` | `{ data: [...] }` |
 | `POST /chart-of-accounts/bulk-upsert` | `{ data: { resourceIds: [...] } }` | Individual results |
 | `POST /organization/currencies` | `{ data: { resourceIds: [...] } }` | Confirmation object |
-| `POST /organization-currencies/:code/rates` | `{ data: "Rate added successfully" }` (string!) | `{ data: { resourceId } }` (object) |
-| `PUT /organization-currencies/:code/rates/:id` | `{ data: "Rate updated successfully" }` (string!) | `{ data: { resourceId } }` (object) |
+| `POST /organization/currencies/:code/rates` | `{ data: "Rate added successfully" }` (string!) | `{ data: { resourceId } }` (object) |
+| `PUT /organization/currencies/:code/rates/:id` | `{ data: "Rate updated successfully" }` (string!) | `{ data: { resourceId } }` (object) |
 | `GET /invoices/{id}` line items | `organizationAccountResourceId` | `accountResourceId` (POST uses `accountResourceId`) |
 | `POST /invoices` (create) | `{ resourceId }` only | Full entity (minimal response!) |
 | `POST /bills` (create) | `{ resourceId }` only | Full entity (minimal response!) |
@@ -606,7 +606,7 @@ Battle-tested patterns from production Jaz API clients:
 | Bill payments | Always embedded in bill creation body, never standalone |
 | Bank records | JSON POST `/bank-records/:id` or multipart `/magic/importBankStatementFromAttachment`. Search via `/bank-records/:id/search`. |
 | Scheduled bills | Wrapped as `{ repeat, startDate, endDate, bill: {...} }`. Field is `repeat` (NOT `frequency`/`interval`) |
-| FX currency | MUST use `currency` OBJECT on ALL transaction types (invoices, bills, credit notes, journals): `{ sourceCurrency: "USD" }` (auto platform rate) or `{ sourceCurrency: "USD", exchangeRate: 1.35 }` (custom). String `currencyCode` silently ignored. |
+| FX currency | MUST use `currency` OBJECT on ALL transaction types (invoices, bills, credit notes, journals): `{ sourceCurrency: "USD" }` (auto platform rate) or `{ sourceCurrency: "USD", exchangeRate: 0.74 }` (custom). String `currencyCode` silently ignored. `exchangeRate` = functionalToSource; invert an everyday "1 USD = 1.35 SGD" quote (Rule 49). |
 
 ---
 

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

@@ -307,17 +307,17 @@ Body for all three: `{ items: [{btResourceId: "<uuid>", btType: "SALE|PURCHASE|S
 | GET | `/organization/currencies/:currencyCode` | Get by code |
 | DELETE | `/organization/currencies/:currencyCode` | Disable currency |
 
-### Currency Rates (via /organization-currencies)
+### Currency Rates (via /organization/currencies)
 | Method | Path | Description |
 |--------|------|-------------|
-| POST | `/organization-currencies/:currencyCode/rates` | Set custom rate |
-| GET | `/organization-currencies/:currencyCode/rates` | List rates |
-| GET | `/organization-currencies/:currencyCode/rates/:resourceId` | Get rate |
-| PUT | `/organization-currencies/:currencyCode/rates/:resourceId` | Update rate |
-| DELETE | `/organization-currencies/:currencyCode/rates/:resourceId` | Delete rate |
+| POST | `/organization/currencies/:currencyCode/rates` | Set custom rate |
+| GET | `/organization/currencies/:currencyCode/rates` | List rates |
+| GET | `/organization/currencies/:currencyCode/rates/:resourceId` | Get rate |
+| PUT | `/organization/currencies/:currencyCode/rates/:resourceId` | Update rate |
+| DELETE | `/organization/currencies/:currencyCode/rates/:resourceId` | Delete rate |
 | POST | `/organization/currencies/rates/bulk-upsert` | Bulk create exchange rates (max 500, auto-enables currencies) |
 
-**CRITICAL path difference**: Currency rate management uses `/organization-currencies` (hyphenated), while basic enable/disable uses `/organization/currencies` (nested). The bulk-upsert endpoint uses the nested path (`/organization/currencies/rates/bulk-upsert`). Using the wrong path returns 404. POST body: `{ "rate": 0.74, "rateApplicableFrom": "YYYY-MM-DD" }` (rate = 1 base → X foreign; see endpoints.md for direction details). Base currency rates return 400. See endpoints.md for full examples.
+**Path note**: rate management, enable/disable and bulk-upsert all live under the nested `/organization/currencies` family. The older hyphenated `/organization-currencies/...` rate paths still resolve but are marked **deprecated** in the OpenAPI spec — prefer the nested form. POST body: `{ "rate": 0.74, "rateApplicableFrom": "YYYY-MM-DD" }` (rate = 1 base → X foreign; see endpoints.md for direction details). Base currency rates return 400. See endpoints.md for full examples.
 
 ---
 

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 5.34.0
+version: 5.35.0
 description: >-
   Use this skill when running Clio CLI commands, building shell scripts with
   Clio, debugging auth issues, understanding --json output, paginating results,

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

@@ -183,9 +183,8 @@ Same subcommands and flags as `cash-in`.
 |------------|-----------|
 | `list <code>` | `--limit`, `--offset`, `--all`, `--format`, `--json` |
 | `add <code>` | `--rate`, `--from`, `--to` |
-| `update <rateId>` | `--rate`, `--from`, `--to` |
-| `import <code>` | `--from`, `--to` (auto-fetch from ECB/MAS) |
-| `import-status <jobId>` | Check import job status |
+| `update <code> <rateId>` | `--rate`, `--from`, `--to` |
+| `bulk-upsert` | `--input <file>` (max 500 rates; requires `rateDirection` per rate) |
 
 ### `clio tax-profiles` — Tax profiles and tax types
 | Subcommand | Key flags |
@@ -472,7 +471,7 @@ All calculators work offline (no auth). Use `--json` for structured output.
 | `depreciation` | `--cost`, `--salvage`, `--life`, `--method` |
 | `prepaid-expense` | `--amount`, `--start-date`, `--months` |
 | `deferred-revenue` | `--amount`, `--start-date`, `--months` |
-| `fx-reval` | `--amount`, `--original-rate`, `--new-rate`, `--currency` |
+| `fx-reval` | `--amount`, `--book-rate`, `--closing-rate`, `--rate-direction`, `--currency` |
 | `ecl` | `--receivables`, `--aging-buckets` (via `--input`) |
 | `provision` | `--amount`, `--rate`, `--periods` |
 | `fixed-deposit` | `--principal`, `--rate`, `--term` |

package/assets/skills/cli/references/common-workflows.md

@@ -98,8 +98,10 @@ Handle a foreign currency invoice from start to finish.
 # Add USD currency to the org (idempotent — safe to re-run)
 clio currencies add USD
 
-# Set the exchange rate for the period
-clio currency-rates add USD --rate 1.3450 --from 2026-03-01 --to 2026-03-31
+# Set the exchange rate for the period.
+# --rate is functionalToSource: 1 SGD = 0.7435 USD. Invert an everyday
+# "1 USD = 1.3450 SGD" quote before sending (1 / 1.3450 = 0.7435).
+clio currency-rates add USD --rate 0.7435 --from 2026-03-01 --to 2026-03-31
 
 # For bulk updates, prepare a JSON file and use bulk-upsert (max 500 rates/call)
 clio currency-rates bulk-upsert --input rates.json
@@ -111,7 +113,7 @@ clio invoices create \
   --due 2026-04-15 \
   --ref "INV-USD-001" \
   --currency USD \
-  --rate 1.3450 \
+  --exchange-rate 0.7435 \
   --lines '[{"name":"Software License","quantity":1,"unitPrice":2000,"accountResourceId":"Revenue"}]' \
   --finalize
 

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 5.34.0
+version: 5.35.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/conversion/references/edge-cases.md

@@ -9,11 +9,11 @@ Enable currencies and set FYE closing rates before creating any FX transactions:
 POST /api/v1/organization/currencies          // Enable currency
 { "currencies": ["USD"] }
 
-POST /api/v1/organization-currencies/USD/rates  // Set FYE rate
-{ "rate": 1.35, "rateApplicableFrom": "2024-12-31" }
+POST /api/v1/organization/currencies/USD/rates  // Set FYE rate
+{ "rate": 0.74, "rateApplicableFrom": "2024-12-31" }
 ```
 
-**Rate direction:** Jaz uses `functionalToSource` — how many functional currency units per 1 source currency unit. If base = SGD and "1 USD = 1.35 SGD", then `rate = 1.35`.
+**Rate direction:** Jaz uses `functionalToSource` — how many SOURCE (foreign) units per 1 FUNCTIONAL (base) unit. If base = SGD and the quote is "1 USD = 1.35 SGD", that quote is the inverse: `rate = 1 / 1.35 = 0.74`. Invert only when the quote is written foreign-first; a USD-base org quoting "1 USD = 56.5 PHP" already has the right direction and sends `56.5`. Rather than deciding, set `rateDirection` and pass the figure verbatim (SKILL.md Rule 49).
 
 **CRITICAL:** `currencyCode: "USD"` (string) is **silently ignored** by the API — it creates the transaction in base currency. You MUST use the `currency` object form.
 
@@ -27,7 +27,7 @@ FX conversion transactions use **original dates** (for aging) but an **explicit
   "dueDate": "2024-07-15",
   "currency": {
     "sourceCurrency": "USD",
-    "exchangeRate": 1.35
+    "exchangeRate": 0.74
   }
 }
 ```

package/assets/skills/conversion/references/mapping-rules.md

@@ -222,16 +222,16 @@ POST /api/v1/organization/currencies
 For Quick Conversion, all conversion transactions use the FYE closing rate. Rates MUST be set AFTER currencies are enabled:
 
 ```
-POST /api/v1/organization-currencies/<code>/rates
+POST /api/v1/organization/currencies/<code>/rates
 {
-  "rate": 1.35,
+  "rate": 0.74,
   "rateApplicableFrom": "2023-12-31"
 }
 ```
 
-**Rate direction:** `functionalToSource` — how many units of functional (base) currency = 1 unit of source (foreign) currency. Example: If base is SGD and rate is 1 SGD = 0.74 USD, then rate = 0.74.
+**Rate direction:** `functionalToSource` — how many units of SOURCE (foreign) currency = 1 unit of FUNCTIONAL (base) currency. Example: base SGD, 1 SGD = 0.74 USD → rate = 0.74. A quote written foreign-first ("1 USD = 1.35 SGD") is the inverse — send 1/1.35 = 0.74, or send 1.35 with `rateDirection: "SOURCE_TO_FUNCTIONAL"` and let the client invert.
 
-**Note:** Rate endpoints use `/organization-currencies` (hyphenated). Enable/disable uses `/organization/currencies` (nested path). These are DIFFERENT endpoints.
+**Note:** Rate endpoints and enable/disable both live under the nested `/organization/currencies` family. The older hyphenated `/organization-currencies/...` rate paths are **deprecated** in the OpenAPI spec.
 
 **CRITICAL:** The field is `rateApplicableFrom` (NOT `effectiveDate`). Using the wrong field name will silently fail.
 

package/assets/skills/conversion/references/option2-quick.md

@@ -93,7 +93,7 @@ POST /api/v1/invoices
 
 **Dates:** Use original dates from the aging report (preserves aging schedules). Fall back to FYE date if not available.
 
-**FX invoices:** Use `currency: { sourceCurrency: "USD", exchangeRate: 1.35 }` (object form with explicit FYE rate). The `exchangeRate` field overrides Jaz's auto-fetch, ensuring zero UGL on day 1. See "FX Invoices/Bills — Dates vs. Rates" in Edge Cases below.
+**FX invoices:** Use `currency: { sourceCurrency: "USD", exchangeRate: 0.74 }` (object form with explicit FYE rate). The `exchangeRate` field overrides Jaz's auto-fetch, ensuring zero UGL on day 1. See "FX Invoices/Bills — Dates vs. Rates" in Edge Cases below.
 
 #### 2.2 Conversion Bills (AP)
 For each line in the AP Aging report:
@@ -193,7 +193,7 @@ POST /api/v1/invoices
   "dueDate": "<original due date>",           // preserves aging buckets
   "currency": {
     "sourceCurrency": "USD",
-    "exchangeRate": 1.35                      // explicit FYE rate — overrides auto-fetch
+    "exchangeRate": 0.74                      // explicit FYE rate — overrides auto-fetch
   },
   ...
 }
@@ -207,7 +207,7 @@ POST /api/v1/invoices
 
 **When dates aren't available:** Some aging reports only show contact name + amount (no individual dates). In this case, fall back to FYE date for both valueDate and dueDate. Aging schedules will be flat ("current") but FX handling remains correct.
 
-**Rate source:** FYE rates come from the exchange rates file (e.g., MAS closing rates). They're set on the org in Phase 1 via `POST /organization-currencies/:code/rates` and also passed explicitly on each FX transaction to guarantee the rate is used regardless of valueDate.
+**Rate source:** FYE rates come from the exchange rates file (e.g., MAS closing rates). They're set on the org in Phase 1 via `POST /organization/currencies/:code/rates` and also passed explicitly on each FX transaction to guarantee the rate is used regardless of valueDate.
 
 ### Partially Paid Invoices in AR Aging
 The AR Aging shows only the **outstanding** balance. Create the conversion invoice for the outstanding amount only — the historical payments are not relevant for Quick Conversion.

package/assets/skills/conversion/references/verification.md

@@ -108,11 +108,11 @@ Conversion Bills (AP)       XX
 TTB Journal                 1
 Lock Date Set               <FYE date>
 
-FX RATES APPLIED
+FX RATES APPLIED (functionalToSource — 1 base unit = N foreign)
 --------------------------------------------
-USD                         1.3500
-EUR                         1.4500
-JPY                         0.0092
+USD                         0.7407
+EUR                         0.6897
+JPY                       108.6957
 
 ERRORS (if any)
 --------------------------------------------

package/assets/skills/jaz-kit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-kit
-version: 5.34.0
+version: 5.35.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.34.0
+version: 5.35.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.34.0
+version: 5.35.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/month-end-close.md

@@ -164,7 +164,9 @@ generate_general_ledger(period_end: '2025-01-31', accountResourceIds: [<FX accou
 
 2. For each foreign-currency monetary balance at period end (from a separate `generate_general_ledger` filtered to non-base-currency accounts), independently compute:
 ```
-clio calc fx-reval --amount <foreign> --book-rate <historical> --closing-rate <list_currency_rates valueDate: '2025-01-31'> --currency <code> --base-currency <base currency> --json
+# --rate-direction is REQUIRED. A list_currency_rates value is FUNCTIONAL_TO_SOURCE
+# and can be passed as-is; an everyday "1 USD = 1.35 SGD" quote is SOURCE_TO_FUNCTIONAL.
+clio calc fx-reval --amount <foreign> --book-rate <historical> --closing-rate <rateFunctionalToSource at 2025-01-31> --rate-direction FUNCTIONAL_TO_SOURCE --currency <code> --base-currency <base currency> --json
 ```
 
 3. Sum your independent gain/loss across all foreign balances. Compare against Jaz's auto-posted FX totals from step 1. Variance > materiality threshold → investigate (see the `fx-reval` recipe for likely causes — settlement-realized FX shifts, explicit `currency.exchangeRate` overrides, multi-leg FX through bank-side spreads).

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

@@ -1,6 +1,6 @@
 ---
 name: jaz-recipes
-version: 5.34.0
+version: 5.35.0
 description: >-
   Use this skill when modeling complex multi-step accounting transactions —
   anything that spans multiple periods, involves changing amounts, or requires
@@ -189,7 +189,9 @@ clio calc asset-disposal --cost 50000 --salvage 5000 --life 5 --acquired 2022-01
 
 # FX revaluation — unrealized gain/loss on non-AR/AP items (IAS 21)
 # Typical context: month-end close (period-end FX reval) + year-end (revaluation)
-clio calc fx-reval --amount 50000 --book-rate 1.35 --closing-rate 1.38 [--currency USD] [--base-currency SGD] [--json]
+# --rate-direction is REQUIRED — these rates read foreign-first (1 USD = 1.35 SGD).
+# A list_currency_rates value would be FUNCTIONAL_TO_SOURCE instead.
+clio calc fx-reval --amount 50000 --book-rate 1.35 --closing-rate 1.38 --rate-direction SOURCE_TO_FUNCTIONAL [--position ASSET|LIABILITY] [--currency USD] [--base-currency SGD] [--json]
 
 # Expected credit loss provision matrix (IFRS 9)
 # Typical context: GST/VAT filing cycle (ECL reviewed alongside the return prep) + year-end (ECL true-up)