@@ -6272,6 +6272,98 @@
           "ref": "#27438"
         }
       ]
+    },
+    {
+      "id": "records-forms.multi-currency-invoice",
+      "title": "A multi-currency invoice stores its home-currency amount at the rate in force on its document date, refuses a date no rate covers, and keeps a currency-less amount blank",
+      "since": "v18",
+      "status": "active",
+      "revision": 1,
+      "priority": "P2",
+      "surface": "mixed",
+      "personas": [
+        "seeded admin (admin@objectos.ai / admin123) — the Default Organization owner; the only persona that may read Setup → Exchange Rates"
+      ],
+      "fixtures": {
+        "app": "showcase",
+        "requires": [
+          "a showcase boot whose home currency is USD. `os dev` / `os serve` / `os start` read examples/app-showcase/.env, which pins OS_LOCALIZATION_CURRENCY=USD; an in-process harness must set that variable itself (packages/qa/dogfood/test/showcase-boot.ts#bootShowcase does). Read the value back first with GET /api/settings/localization and confirm currency is USD before any clause",
+          "the stock seed's exchange rates (examples/app-showcase/src/data/seed/index.ts#exchangeRates): EUR 0.92 from 2025-01-01 and 0.9 from 30 days before the boot, JPY 151.5 from 2025-01-01 and 149.25 from 30 days before the boot, all source manual. No JPY or EUR rate exists before 2025-01-01, which is what the steps[3] refusal probe relies on",
+          "the stock seed's invoices carry a currency_code: INV-1004 / INV-1009 / INV-1010 are EUR, INV-1007 / INV-1008 are JPY (INV-1008 has two yen-priced lines), the rest USD",
+          "the console bundle for the browser legs (pnpm console:build)"
+        ],
+        "knownGaps": [
+          "invoice lines and the Subtotal (`total`) roll-up stay dynamic-mode currency: a child amount cannot take its parent's record currency, and a summary over a record-mode child amount is refused (packages/objectql/src/record-currency-aggregate-door.ts#RecordCurrencySummaryRefusedError). On a EUR or JPY invoice those two show the home currency's symbol while `amount` shows the record's own. That is the platform's current shape, not a failure of this item",
+          "a host with no .env reader and no other currency source has no home currency, so every coded seed invoice is refused ERR_HOME_CURRENCY_UNSET and dropped by the seeder with a warning: the invoice list is empty. That is a fixture failure (requires[0]), scored blocked(fixture), never a FAIL of these clauses"
+        ]
+      },
+      "steps": [
+        "GET /api/v1/data/showcase_invoice?filter currency_code in EUR, JPY and read amount, currency_code, invoice_date, amount_home and amount_rate on each; GET /api/v1/data/sys_exchange_rate for the rows those dates select",
+        "POST a showcase_invoice with no currency_code (name, account, status draft) and read it back",
+        "PATCH a USD draft invoice's currency_code to EUR and read amount_home / amount_rate again",
+        "POST a showcase_invoice with currency_code JPY and invoice_date 2024-06-01 (before any JPY rate)",
+        "in the console, open a EUR invoice's detail page, then its edit form, and change currency_code and invoice_date on the form without saving"
+      ],
+      "acceptance": [
+        {
+          "clause": "a foreign-currency invoice stores `amount_rate` = the sys_exchange_rate row for its currency with the greatest effective_date on or before its invoice_date, and `amount_home` = amount ÷ that rate rounded to the home currency's 2 decimals",
+          "oracle": "api",
+          "verify": "for each EUR and JPY seed invoice, pick the governing rate row by hand from the steps[0] rate read and recompute amount ÷ rate; both stored fields must match. A rate taken from a later row, or a home amount computed as amount × rate, is a FAIL",
+          "evidence": "the invoice and rate reads, and the hand computation per invoice"
+        },
+        {
+          "clause": "a home-currency invoice stores rate 1 and amount_home = amount",
+          "oracle": "api",
+          "verify": "the USD seed invoices with a non-blank amount read amount_rate 1 and amount_home equal to amount",
+          "evidence": "the reads"
+        },
+        {
+          "clause": "an invoice with no currency_code is accepted and keeps amount, amount_home and amount_rate blank (a record-mode amount with no currency is not projected)",
+          "oracle": "api",
+          "verify": "the steps[1] POST answers 201 and its read-back has all three null",
+          "evidence": "the response and the read"
+        },
+        {
+          "clause": "changing currency_code re-projects: after the steps[2] PATCH the invoice carries the EUR rate in force on its invoice_date and the matching amount_home",
+          "oracle": "api",
+          "verify": "before and after reads of the same id; the after values match the clause-0 computation for EUR",
+          "evidence": "the two reads"
+        },
+        {
+          "clause": "a foreign invoice dated before any rate for its currency is refused ERR_EXCHANGE_RATE_MISSING, naming the currency and the date, and no row is written",
+          "oracle": "api",
+          "verify": "the steps[3] POST answers 400 with code ERR_EXCHANGE_RATE_MISSING (packages/objectql/src/home-amount-projection.ts#EXCHANGE_RATE_MISSING_CODE) and a message naming JPY and 2024-06-01; a follow-up list by that name returns nothing",
+          "evidence": "the response body and the empty list"
+        },
+        {
+          "clause": "the console shows the home amount read-only with its 'Converted at RATE on DATE' hint on a EUR invoice, and the edit form shows the live '≈ AMOUNT at RATE on DATE' preview, which follows a changed currency or date before save",
+          "oracle": "screenshot",
+          "verify": "screenshots at deviceScaleFactor 2 of the detail page and of the form before and after the steps[4] edits (ui/packages/fields/src/widgets/homeAmountPreview.tsx#HomeAmountPreview draws the preview)",
+          "evidence": "the screenshots"
+        }
+      ],
+      "negative": [
+        "a foreign invoice stored at rate 1, at a rate dated after its invoice_date, or with amount_home computed by multiplication is a FAIL; so is a currency-less invoice refused, or one stored with a home amount; so is a missing-rate write that stores a row"
+      ],
+      "traps": [
+        "seed-data-thin",
+        "clock-skew"
+      ],
+      "source": [
+        "docs/adr/0144-multi-currency-record-currency-dated-rates-write-time-home-projection.md (record currency, home amount, rate direction)",
+        "packages/objectql/src/home-amount-projection.ts#HOME_CURRENCY_UNSET_CODE",
+        "examples/app-showcase/src/data/objects/invoice.object.ts (currency_code, invoice_date, amount, amount_home, amount_rate)",
+        "examples/app-showcase/src/automation/flows/exchange-rate-sync.flow.ts (the rates-feed template, shipped switched off)",
+        "#27197"
+      ],
+      "history": [
+        {
+          "revision": 1,
+          "date": "2026-11-09",
+          "change": "initial: the showcase invoice became the multi-currency example (#27197); verified live in the same PR, clause table in its body",
+          "ref": "#31757"
+        }
+      ]
     }
   ]
 }
@@ -3,3 +3,13 @@
 # deployment turns it on, so this example opts in. `os dev`, `os serve` and
 # `os start` read this file from the project root.
 OS_PAGE_REACT_ENABLED=true
+
+# The organization's home currency (Setup → Localization → Default currency).
+# The invoice is the multi-currency example: it converts each invoice into the
+# home currency at write, from the exchange rates the seed loads, and those
+# rates are stated against USD. So the home currency is pinned here rather than
+# derived from this host's locale: a host with no locale would otherwise leave
+# it unset, and every seeded invoice would be refused (ERR_HOME_CURRENCY_UNSET).
+# Pinned by environment, the Localization page shows it locked; edit this line
+# (and the seeded rates) to run the example in another home currency.
+OS_LOCALIZATION_CURRENCY=USD
@@ -0,0 +1,172 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { defineFlow } from '@objectstack/spec';
+
+/**
+ * Exchange Rate Sync — a TEMPLATE for keeping `sys_exchange_rate` current from
+ * a rates feed (multi-currency, ADR-0144).
+ *
+ * The platform ships no rates feed and never calls one: rates are typed in
+ * Setup → Exchange Rates, imported from a file, or written by an app. This flow
+ * is the "written by an app" kind, as an example a customer copies and turns
+ * on. Once a day it reads a JSON feed and writes one rate row per currency,
+ * marked `source: 'app'`.
+ *
+ * ## The feed, and what it must say
+ *
+ * The rate direction is the platform's one direction: 1 unit of the home
+ * currency = `rate` units of the foreign currency. So the feed must be quoted
+ * FROM the organization's home currency. The default below reads the
+ * Frankfurter API (European Central Bank reference rates) from USD, the home
+ * currency this example pins in `.env`; its answer is
+ * `{ "base": "USD", "date": "YYYY-MM-DD", "rates": { "EUR": 0.92, ... } }`.
+ * A feed quoted the other way round would store every rate inverted.
+ *
+ * ## Where the customer changes the URL
+ *
+ * `rate_feed_url` is the setting: the `http` node's `url` is the text slot
+ * `{{ rate_feed_url }}`, and the variable's `defaultValue` is the URL. Change
+ * it in Studio (Automation → this flow → Variables) to point at the bank or
+ * provider the company reconciles against, and to quote from its own home
+ * currency. A URL whose path or query carries a secret does not belong here:
+ * the flow definition is readable by everyone who can read flows, so a
+ * credentialed feed goes through a connector, whose credential lives outside
+ * the definition (`src/system/connectors/index.ts`).
+ *
+ * ## What one run does
+ *
+ *  1. `fetch_rates` GETs the feed.
+ *  2. `to_rows` turns the feed's `rates` map into a list of
+ *     `{ currency, rate }` entries, one per currency the feed quotes.
+ *  3. `each_rate` writes one `sys_exchange_rate` row per entry, dated with
+ *     the feed's own `date` (the day the rates are for, not the day the flow
+ *     ran). The table holds one row per (currency, effective date), so a
+ *     second run on the same feed day is refused row by row; each write sits
+ *     in its own `try_catch`, so a day already loaded is skipped and a run
+ *     never stops halfway through the list.
+ *
+ * Converted amounts do not move when a new rate arrives: an invoice keeps the
+ * rate in force on its own document date (`invoice_date`). A corrected rate
+ * reaches amounts already stored only through an explicit recompute
+ * (`os migrate recompute-home-amounts`).
+ *
+ * ## Why it ships switched off
+ *
+ * `status: 'obsolete'` is the platform's "loaded, not armed": Studio lists
+ * and opens the flow and its on/off switch reads Off, and no trigger fires it.
+ * A shipped example must not call a third-party service on every developer's
+ * boot and in CI. To use it, switch it on in Studio. Scheduled work shipped
+ * in a package also needs the deployment switch
+ * `OS_AUTOMATION_SCHEDULED_WORK_ENABLED` (see `ScheduledDigestFlow` in
+ * `./index.ts` for that rule and the tenancy posture it depends on).
+ *
+ * The flow writes an administrators' object: only an organization
+ * administrator may write exchange rates, so the run is `runAs: 'system'`, the
+ * principal a schedule runs as when no user started it.
+ */
+export const ExchangeRateSyncFlow = defineFlow({
+  name: 'showcase_exchange_rate_sync',
+  label: 'Exchange Rate Sync (template)',
+  description:
+    'Once a day, reads exchange rates from a feed quoted from the home currency and writes them to Setup → Exchange Rates (source: app). A template: switch it on and point rate_feed_url at your provider.',
+  type: 'schedule',
+  status: 'obsolete',
+  runAs: 'system',
+  variables: [
+    {
+      name: 'rate_feed_url',
+      type: 'text',
+      isInput: false,
+      isOutput: false,
+      defaultValue: 'https://api.frankfurter.app/latest?from=USD',
+    },
+  ],
+  nodes: [
+    {
+      id: 'start',
+      type: 'start',
+      label: 'Daily at 06:00',
+      config: {
+        schedule: { type: 'cron', expression: '0 6 * * *' },
+      },
+    },
+    {
+      id: 'fetch_rates',
+      type: 'http',
+      label: 'Fetch Rates',
+      config: {
+        url: '{{ rate_feed_url }}',
+        method: 'GET',
+      },
+    },
+    {
+      id: 'to_rows',
+      type: 'assignment',
+      label: 'One Entry per Currency',
+      config: {
+        assignments: {
+          // A CEL comprehension over the map's keys. Each entry keeps the
+          // feed's number as is: the rate table refuses a zero or negative
+          // rate, and one with more than twelve decimals, so a bad quote is
+          // refused at the write and never stored rounded.
+          rate_rows: {
+            dialect: 'cel',
+            source: "fetch_rates.response.rates.map(c, {'currency': c, 'rate': dyn(fetch_rates.response.rates[c])})",
+          },
+          rate_date: { dialect: 'cel', source: 'fetch_rates.response.date' },
+        },
+      },
+    },
+    {
+      id: 'each_rate',
+      type: 'loop',
+      label: 'For Each Currency',
+      config: {
+        collection: { dialect: 'cel', source: 'rate_rows' },
+        iteratorVariable: 'row',
+        maxIterations: 200,
+        body: {
+          nodes: [
+            {
+              id: 'guard_write',
+              type: 'try_catch',
+              label: 'Skip a Day Already Loaded',
+              config: {
+                try: {
+                  nodes: [
+                    {
+                      id: 'write_rate',
+                      type: 'create_record',
+                      label: 'Write Exchange Rate',
+                      config: {
+                        objectName: 'sys_exchange_rate',
+                        fields: {
+                          currency: { dialect: 'cel', source: 'row.currency' },
+                          rate: { dialect: 'cel', source: 'row.rate' },
+                          effective_date: { dialect: 'cel', source: 'rate_date' },
+                          source: 'app',
+                        },
+                      },
+                    },
+                  ],
+                  edges: [],
+                },
+                catch: {
+                  nodes: [{ id: 'rate_skipped', type: 'assignment', label: 'Rate Skipped' }],
+                },
+              },
+            },
+          ],
+          edges: [],
+        },
+      },
+    },
+    { id: 'end', type: 'end', label: 'End' },
+  ],
+  edges: [
+    { id: 'e1', source: 'start', target: 'fetch_rates' },
+    { id: 'e2', source: 'fetch_rates', target: 'to_rows' },
+    { id: 'e3', source: 'to_rows', target: 'each_rate' },
+    { id: 'e4', source: 'each_rate', target: 'end' },
+  ],
+});
@@ -4,6 +4,7 @@ import { defineFlow } from '@objectstack/spec';
 import { DynamicApprovalFlow } from './dynamic-approval.flow';
 import { ApproverBindingsFlow } from './approver-bindings.flow';
 import { RecalcEstimatesFlow, RecalcTaskEstimateFlow } from './recalc-estimate.flow';
+import { ExchangeRateSyncFlow } from './exchange-rate-sync.flow';
 
 /**
  * Task Completed → Notify — an autolaunched, record-triggered flow that fires
@@ -2167,4 +2168,6 @@ export const allFlows = [
   // `showcase_recalc_estimates_api` endpoint (src/system/apis/).
   RecalcEstimatesFlow,
   RecalcTaskEstimateFlow,
+  // Multi-currency: the rates-feed template (loaded, switched off).
+  ExchangeRateSyncFlow,
 ];
@@ -164,6 +164,80 @@ export const Invoice = ObjectSchema.create({
       label: 'Subtotal',
       summaryOperations: { object: 'showcase_invoice_line', field: 'amount', function: 'sum' },
     }),
+
+    // ── Multi-currency (ADR-0144) ─────────────────────────────────────────
+    //
+    // An invoice is billed in the customer's currency, and the company reports
+    // in its own: the organization's home currency (Setup → Localization →
+    // Default currency). Five fields make that work, and every one of them is
+    // declared here and referenced by name. The platform injects none of them
+    // and fixes none of their names.
+    //
+    //   currency_code   the currency this invoice is billed in (ISO 4217).
+    //   invoice_date    the document date; the exchange rate in force on this
+    //                   day converts the invoice.
+    //   amount          the tax-inclusive total, in `currency_code`
+    //                   (`currencyMode: 'record'`).
+    //   amount_home     the same total converted into the home currency. The
+    //                   engine writes it at every write that moves the amount,
+    //                   its currency or its date, and stores the rate it used in
+    //   amount_rate     (1 home unit = rate units of `currency_code`).
+    //
+    // Rates come from Setup → Exchange Rates (`sys_exchange_rate`). A foreign
+    // invoice dated before any rate of its currency is REFUSED, naming the
+    // currency and the date; nothing converts at 1:1 or at the nearest rate.
+    // Consolidated reporting sums `amount_home`, never `amount`: the Revenue
+    // Pulse dataset does.
+    //
+    // What does NOT follow the invoice's currency: the line items and the
+    // `total` Subtotal above. A line cannot name its invoice's code field as its
+    // own currency, and a roll-up of amounts in different currencies is refused,
+    // so the lines stay plain amounts and display in the home currency's format.
+
+    // The record currency. A `text` field declaring the ISO 4217 value domain,
+    // so a write can store only a real code. Optional: an invoice without a
+    // currency has no `amount` yet (see below).
+    currency_code: Field.text({
+      label: 'Currency',
+      maxLength: 3,
+      valueDomain: 'iso_4217_currency',
+    }),
+    // The document date, distinct from `issued_on` (blank on a draft): a
+    // foreign amount needs a date to pick its rate, so a draft dated today is
+    // convertible from its first save.
+    invoice_date: Field.date({
+      label: 'Invoice Date',
+      required: true,
+      defaultValue: 'NOW()',
+    }),
+    // The tax-inclusive total in the invoice's own currency, recomputed on every
+    // write from the Subtotal roll-up (the roll-up's recompute is itself a
+    // write, so adding a line moves it). It stays blank until a currency is
+    // chosen: an amount of money with no currency is not an amount the engine
+    // will store or convert. Rounded to two decimals, so the stored total is
+    // the one the invoice states (the seeded yen lines are whole yen, so a yen
+    // total stays whole).
+    amount: Field.currency({
+      label: 'Total incl. Tax',
+      expression: cel`record.currency_code == null || record.currency_code == '' ? null : double(round((record.total == null ? 0 : record.total) * (1 + (record.tax_rate == null ? 0 : record.tax_rate) / 100) * 100)) / 100`,
+      currencyConfig: {
+        currencyMode: 'record',
+        currencyField: 'currency_code',
+        homeAmount: { field: 'amount_home', rateDate: 'invoice_date', rateField: 'amount_rate' },
+      },
+    }),
+    // Written by the engine only (`readonly`), in `dynamic` mode: it displays
+    // in the home currency, so this metadata never names that currency.
+    amount_home: Field.currency({
+      label: 'Total incl. Tax (Home Currency)',
+      readonly: true,
+    }),
+    // The rate the conversion used, kept with every digit it was stored with
+    // (no `scale`, so nothing rounds the rate a reader is shown).
+    amount_rate: Field.number({
+      label: 'Exchange Rate',
+      readonly: true,
+    }),
   },
 
   validations: [