@arcforgelabs/flow 2026.10.25 → 2026.10.26

package/server/db/migrations/meta/_journal.json

@@ -57,6 +57,20 @@
       "when": 1792391146736,
       "tag": "0007_integration_settings",
       "breakpoints": true
+    },
+    {
+      "idx": 8,
+      "version": "7",
+      "when": 1792396463612,
+      "tag": "0008_people_appearance",
+      "breakpoints": true
+    },
+    {
+      "idx": 9,
+      "version": "7",
+      "when": 1792404377371,
+      "tag": "0009_pipeline_matcher",
+      "breakpoints": true
     }
   ]
 }

package/server/db/schema.js

@@ -9,6 +9,7 @@ import {
   integer,
   jsonb,
   pgTable,
+  primaryKey,
   text,
   timestamp,
   unique,
@@ -153,7 +154,9 @@ export const PERSON_STATUSES = ['active', 'pending', 'disabled'];
 // someone is; this table decides what they may do. One installation serves one
 // lab, so people are installation-wide and carry no organisation_id. Emails
 // are stored lower-case. `clerk_user_id` is set on the person's first verified
-// sign-in; until then the row is an invitation.
+// sign-in; until then the row is an invitation. `appearance` is the person's
+// own design system, light or dark and accent (server/auth/people.js,
+// normaliseAppearance); null until they first choose.
 export const people = pgTable('people', {
   id: id(),
   email: text('email').notNull(),
@@ -163,6 +166,7 @@ export const people = pgTable('people', {
   clerkUserId: text('clerk_user_id'),
   invitedBy: uuid('invited_by').references(() => people.id, { onDelete: 'set null' }),
   linkedAt: timestamp('linked_at', { withTimezone: true }),
+  appearance: jsonb('appearance'),
   createdAt: createdAt(),
   updatedAt: updatedAt(),
 }, (t) => [
@@ -202,6 +206,9 @@ export const billingObligations = pgTable('billing_obligations', {
   contactId: uuid('contact_id'),
   practitioner: text('practitioner'),
   shippedOn: date('shipped_on'),
+  // The day of the work, for matching it to an accounting invoice: the work
+  // system's invoice date, else its due date, else its order date.
+  jobDate: date('job_date'),
   // The lines as the work system reported them, normalised.
   lines: jsonb('lines').notNull().default(sql`'[]'::jsonb`),
   lineFingerprint: text('line_fingerprint').notNull(),
@@ -316,7 +323,9 @@ export const obligationWritebacks = pgTable('obligation_writebacks', {
 // one active link per external record and per Flow record, in each system. A
 // link that is not exact stays `proposed` until a person confirms it.
 export const LINK_ENTITIES = ['contact', 'price_item', 'obligation', 'invoice', 'payment', 'credit_note'];
-export const LINK_MATCHES = ['created_by_flow', 'exact_id', 'imported', 'name', 'person'];
+// `exact_name`: the same name, after spacing and case are evened out, held by
+// exactly one record on each side.
+export const LINK_MATCHES = ['created_by_flow', 'exact_id', 'exact_name', 'imported', 'name', 'person'];
 export const LINK_STATES = ['active', 'proposed', 'superseded'];
 
 export const externalLinks = pgTable('external_links', {
@@ -490,3 +499,63 @@ export const integrationSettingEvents = pgTable('integration_setting_events', {
   index('integration_setting_events_adapter').on(t.adapterId, t.createdAt),
   check('integration_setting_events_kind_valid', inList('kind', INTEGRATION_SETTING_EVENTS)),
 ]);
+
+// The pipeline (server/core/pipeline.js, issue 58). Where each step that reads
+// another system's records stands, by name, so a restart goes on from there.
+export const pipelineCursors = pgTable('pipeline_cursors', {
+  organisationId: organisationId().references(() => organisations.id),
+  name: text('name').notNull(),
+  cursor: text('cursor'),
+  updatedAt: updatedAt(),
+}, (t) => [
+  primaryKey({ name: 'pipeline_cursors_pk', columns: [t.organisationId, t.name] }),
+]);
+
+// The matcher's suggestions: accounting invoices that could bill a job, with
+// the signals that agreed. Only exact evidence links a job by itself; a
+// suggestion waits for a person. A newer run marks the ones it no longer
+// makes `stale`.
+export const LINK_SUGGESTION_STATES = ['open', 'accepted', 'rejected', 'stale'];
+
+export const linkSuggestions = pgTable('link_suggestions', {
+  id: id(),
+  organisationId: organisationId().references(() => organisations.id),
+  obligationId: uuid('obligation_id').notNull(),
+  system: text('system').notNull(),
+  externalId: text('external_id').notNull(),
+  externalNumber: text('external_number'),
+  score: integer('score').notNull(),
+  rank: integer('rank').notNull(),
+  signals: jsonb('signals').notNull().default(sql`'[]'::jsonb`),
+  state: text('state').notNull().default('open'),
+  decidedBy: text('decided_by'),
+  decidedAt: timestamp('decided_at', { withTimezone: true }),
+  createdAt: createdAt(),
+  updatedAt: updatedAt(),
+}, (t) => [
+  unique('link_suggestions_pair').on(t.organisationId, t.obligationId, t.system, t.externalId),
+  index('link_suggestions_open').on(t.organisationId, t.state, t.obligationId),
+  foreignKey({
+    name: 'link_suggestions_obligation_same_org',
+    columns: [t.organisationId, t.obligationId],
+    foreignColumns: [billingObligations.organisationId, billingObligations.id],
+  }),
+  check('link_suggestions_state_valid', inList('state', LINK_SUGGESTION_STATES)),
+]);
+
+// A person's "not this one": the matcher never suggests the pair again.
+export const linkRejections = pgTable('link_rejections', {
+  organisationId: organisationId().references(() => organisations.id),
+  obligationId: uuid('obligation_id').notNull(),
+  system: text('system').notNull(),
+  externalId: text('external_id').notNull(),
+  actor: text('actor').notNull(),
+  createdAt: createdAt(),
+}, (t) => [
+  primaryKey({ name: 'link_rejections_pk', columns: [t.organisationId, t.obligationId, t.system, t.externalId] }),
+  foreignKey({
+    name: 'link_rejections_obligation_same_org',
+    columns: [t.organisationId, t.obligationId],
+    foreignColumns: [billingObligations.organisationId, billingObligations.id],
+  }),
+]);

package/server/index.js

@@ -6,6 +6,7 @@ import { createPersonAuth } from './auth/session.js';
 import { resolveSignInSettings } from './auth/settings.js';
 import { migrateDatabase, openDatabase } from './db/index.js';
 import { importEarlierAtStart, importEarlierLinksAtStart, resolveImportAtStart } from './import/at-start.js';
+import { createPipelineWorker } from './core/pipeline.js';
 import { resolveSecretsKey } from './core/secrets.js';
 import { adapters as shippedAdapters } from './integrations/adapters.js';
 import { createIntegrations, resolveEnabledIntegrations } from './integrations/index.js';
@@ -79,6 +80,14 @@ try {
 const integrationsOn = integrations.list().filter((a) => a.enabled).map((a) => `${a.id}${a.state === 'ready' ? '' : ` (${a.state})`}`);
 console.log(`[integrations] on: ${integrationsOn.join(', ') || 'none'}; secrets key ${secrets ? `from ${secrets.source}` : 'not set (FLOW_SECRETS_KEY)'}`);
 
+// The pipeline (server/core/pipeline.js) joins what the integrations copy into
+// Flow: jobs into the ledger, and each job to its accounting invoice. It runs
+// only while an integration that feeds it is on, and writes to no other
+// system. FLOW_PIPELINE=off stops it.
+if (process.env.FLOW_PIPELINE !== 'off') {
+  createPipelineWorker({ db: database.db, integrations }).start();
+}
+
 let auth = null;
 if (settings.mode === 'clerk') {
   const { keys } = settings;

package/server/integrations/port.js

@@ -14,6 +14,9 @@ export const CAPABILITIES = Object.freeze([
   'pushInvoice', // send an issued invoice; the Flow record id is the idempotency key
   'pushBill', // send an approved bill; the Flow record id is the idempotency key
   'pullPayments', // payments since a cursor, matched to invoices and bills
+  'checkInvoice', // does the accounting system hold an invoice for a billable job? (the ledger's liveCheck)
+  'listCustomers', // the system's customers, by id and name, for the identity map (Seazona: clients; Xero: contacts)
+  'findInvoices', // sales invoices in the accounting system's copy, for the matcher; never a live call
   'health', // connection state for Settings
 ]);
 

package/server/integrations/seazona/feed.js

@@ -102,3 +102,14 @@ export async function readBillableWork(db, { cursor = null, limit = 200 } = {})
     more: rows.length === pageSize,
   };
 }
+
+// Seazona clients, by id and the company name an invoice bills. A client
+// with no company name is listed by its full name.
+export async function listClients(db) {
+  const rows = await db.select({ id: seazonaClients.id, company: seazonaClients.company, fullName: seazonaClients.fullName, active: seazonaClients.active })
+    .from(seazonaClients);
+  return rows
+    .filter((r) => r.active !== false)
+    .map((r) => ({ id: r.id, name: (r.company || r.fullName || '').trim() }))
+    .filter((r) => r.name);
+}

package/server/integrations/seazona/index.js

@@ -1,5 +1,5 @@
 import { createSeazonaClient } from './client.js';
-import { readBillableWork } from './feed.js';
+import { listClients, readBillableWork } from './feed.js';
 import { readSeazonaSyncHealth, runSeazonaSync } from './lanes.js';
 import { createSeazonaScheduler } from './scheduler.js';
 import { describeSeazonaSettings, resolveSeazonaSettings } from './settings.js';
@@ -99,6 +99,12 @@ export function createSeazonaAdapter({ env = null, fetchImpl = null, now = Date.
       async pullWorkItems(cursor = null, options = {}) {
         return readBillableWork(current().db, { cursor, ...options });
       },
+
+      // Seazona clients by id and company name, for the identity map. Reads
+      // Flow's copy only.
+      async listCustomers() {
+        return listClients(current().db);
+      },
     },
   };
 }

package/server/integrations/seazona/ledger.js

@@ -46,6 +46,8 @@ export function toLedgerJob(item) {
     practitioner: item.doctorName ?? null,
     // The Seazona API gives a shipped status but no shipped date.
     shippedOn: null,
+    // The day of the work, for matching it to its accounting invoice.
+    jobDate: item.invoice?.invoiceDate ?? item.dueOn ?? item.orderedOn ?? null,
     lines: ledgerLinesFor(item).lines,
     observedAt: item.syncedAt,
     actor: SEAZONA_SOURCE_SYSTEM,

package/server/integrations/xero/import.js

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { sql } from 'drizzle-orm';
 import { enqueueJob, runNextJob } from '../../core/queue.js';
+import { lastSync, syncCatalogue } from './catalogue.js';
 import { MIRROR_RESOURCES, mirrorXero } from './mirror.js';
 
 // The history import. When an owner connects Xero, Flow copies the
@@ -17,6 +18,9 @@ const LEASE_MS = 30 * 60 * 1000;
 // Xero's day limit resets on a rolling day; an hour is a cheap re-check.
 const BUDGET_WAIT_MS = 60 * 60 * 1000;
 const IDLE_MS = 30 * 1000;
+// Contacts and items are read again once a day, so the matcher can link each
+// customer (server/core/pipeline.js) without a person pressing Sync.
+const CATALOGUE_EVERY_MS = 24 * 60 * 60 * 1000;
 
 export async function queueHistoryImport(db, organisationId, { reason = 'connected', runAfter = null } = {}) {
   return enqueueJob(db, organisationId, { kind: IMPORT_KIND, dedupeKey: IMPORT_KEY, payload: { reason }, runAfter });
@@ -63,6 +67,23 @@ export async function runImportOnce(db, runtime, { workerId = `xero-import-${ran
   return ran;
 }
 
+// Reads the contacts and items of each connected organisation whose last good
+// read is older than a day. A failure is logged and tried again next hour.
+export async function refreshStaleCatalogues(db, runtime, { now = Date.now, log = console } = {}) {
+  const { rows } = await db.execute(sql`select organisation_id from xero_connections where mode = ${runtime.settings.mode}`);
+  for (const { organisation_id: organisationId } of rows) {
+    const last = await lastSync(db, organisationId);
+    const at = last?.finishedAt ?? last?.startedAt;
+    if (last && at && Number(now()) - new Date(at) < (last.status === 'succeeded' ? CATALOGUE_EVERY_MS : BUDGET_WAIT_MS)) continue;
+    try {
+      const run = await syncCatalogue(db, runtime, organisationId);
+      log.info?.(`[xero] contacts and items read for organisation ${organisationId}: ${run.contactCount} contacts, ${run.itemCount} items`);
+    } catch (error) {
+      log.error?.(`[xero] reading contacts and items for organisation ${organisationId} failed: ${error?.code ?? 'error'}`);
+    }
+  }
+}
+
 // The background worker: runs due slices one at a time, then waits. Started
 // by the adapter outside replay mode; stop() waits for a slice in flight.
 export function createImportWorker({ db, runtime, log = console, timers = { setTimeout, clearTimeout }, firstDelayMs = 10_000 }) {
@@ -83,6 +104,7 @@ export function createImportWorker({ db, runtime, log = console, timers = { setT
     let busy = false;
     running = (async () => {
       try {
+        await refreshStaleCatalogues(db, runtime, { log });
         const ran = await runImportOnce(db, runtime, { workerId });
         if (ran) {
           busy = true;

package/server/integrations/xero/index.js

@@ -2,7 +2,8 @@ import { fileURLToPath } from 'node:url';
 import { sql } from 'drizzle-orm';
 import { pushInvoice } from './drafts.js';
 import { createImportWorker } from './import.js';
-import { readPayments } from './ledger.js';
+import { readPayments, xeroLiveCheck } from './ledger.js';
+import { findInvoices, listCustomers } from './lookup.js';
 import { createXeroRouter } from './routes.js';
 import { createXeroRuntime, requireXeroSettings } from './runtime.js';
 import { writesAllowed } from './settings.js';
@@ -30,7 +31,7 @@ export const XERO_SETUP = {
   },
   fields: [
     { name: 'XERO_MODE', label: 'Mode', kind: 'choice', choices: [{ value: 'live', label: 'Live: your Xero organisation' }, { value: 'sandbox', label: 'Sandbox: a Xero Demo Company' }] },
-    { name: 'XERO_REDIRECT_URI', label: 'Redirect URI', kind: 'url', suggest: 'callback', help: 'This installation\'s address plus /api/xero/oauth/callback. Register the same address on the Xero app.' },
+    { name: 'XERO_REDIRECT_URI', label: 'Redirect URI', kind: 'url', suggest: 'callback', help: 'Register the same address on the Xero app.' },
     { name: 'XERO_CLIENT_ID', label: 'Client id', help: 'From the Xero app\'s Configuration.' },
     { name: 'XERO_CLIENT_SECRET', label: 'Client secret', secret: true, help: 'Stored encrypted. Flow never shows it again.' },
     { name: 'XERO_TENANT_NAME', label: 'Xero organisation name', help: 'Live mode connects only the organisation with this exact name.' },
@@ -88,6 +89,13 @@ export function createXeroAdapter({ runtime: given = null } = {}) {
       // Sales invoice payments changed since `since` (ledger.js). The answer's
       // cursor is the next `since`.
       pullPayments: ({ organisationId, since }) => readPayments(database, current(), organisationId, { since: new Date(since) }),
+      // Xero's invoice for one billable job, looked up live (ledger.js): the
+      // `liveCheck` for draftInvoiceForObligation.
+      checkInvoice: ({ organisationId, obligation }) => xeroLiveCheck(database, current(), organisationId)(obligation),
+      // Active Xero contacts, from Flow's copy (lookup.js).
+      listCustomers: ({ organisationId }) => listCustomers(database, organisationId),
+      // Sales invoices from the mirror, with the mirror's state (lookup.js).
+      findInvoices: ({ organisationId, ...query }) => findInvoices(database, organisationId, query),
     },
     routes: ({ db, personAuth, log, messagePage }) => createXeroRouter({ db, personAuth, runtime: current(), log, messagePage }),
   };

package/server/integrations/xero/lookup.js

@@ -0,0 +1,94 @@
+import { sql } from 'drizzle-orm';
+import { ledgerState } from './ledger.js';
+import { MIRROR_RESOURCES } from './mirror.js';
+
+// What the core's matcher (server/core/pipeline.js) reads from Xero: the
+// customers and the sales invoices in Flow's own copy. It never calls Xero, so
+// matching a whole history costs no API calls.
+
+// How old the mirror's last finished pass may be before "no invoice found"
+// stops counting as proof.
+export const MIRROR_FRESH_MS = 24 * 60 * 60 * 1000;
+
+export async function listCustomers(db, organisationId) {
+  const { rows } = await db.execute(sql`
+    select xero_contact_id, name, status from xero_contacts
+    where organisation_id = ${organisationId} and status = 'ACTIVE'
+    order by name`);
+  return rows.map((r) => ({ id: r.xero_contact_id, name: r.name }));
+}
+
+// Whether the mirror holds the whole history and was read lately. Until then a
+// search that finds nothing proves nothing.
+export async function mirrorState(db, organisationId, { now = new Date() } = {}) {
+  const { rows } = await db.execute(sql`
+    select resource, passes, last_pass_finished_at from xero_mirror_cursors
+    where organisation_id = ${organisationId}`);
+  const byResource = new Map(rows.map((r) => [r.resource, r]));
+  const invoices = byResource.get('invoices');
+  const finished = MIRROR_RESOURCES.every((r) => (byResource.get(r)?.passes ?? 0) > 0);
+  const lastPass = invoices?.last_pass_finished_at ? new Date(invoices.last_pass_finished_at) : null;
+  const { rows: [changed] } = await db.execute(sql`
+    select max(last_changed_at) as at from xero_invoices where organisation_id = ${organisationId}`);
+  return {
+    complete: finished,
+    fresh: Boolean(lastPass && now - lastPass <= MIRROR_FRESH_MS),
+    lastPassAt: lastPass,
+    // The latest change the mirror copied, so the matcher looks at a job again
+    // only when the mirror moved on.
+    changedAt: changed?.at ? new Date(changed.at) : null,
+  };
+}
+
+const ids = (list) => sql.param([...new Set(list.map(String))]);
+
+function invoiceRow(r) {
+  return {
+    id: r.xero_invoice_id,
+    number: r.invoice_number,
+    contactId: r.xero_contact_id,
+    status: r.status,
+    // The ledger's accounting state for this invoice.
+    state: ledgerState({ Status: r.status, AmountPaid: Number(r.amount_paid_cents ?? 0), AmountCredited: Number(r.amount_credited_cents ?? 0) }),
+    issuedOn: r.issued_on instanceof Date ? r.issued_on.toISOString().slice(0, 10) : r.issued_on,
+    subtotalCents: r.subtotal_cents === null ? null : Number(r.subtotal_cents),
+    totalCents: r.total_cents === null ? null : Number(r.total_cents),
+    amountDueCents: r.amount_due_cents === null ? null : Number(r.amount_due_cents),
+    amountPaidCents: r.amount_paid_cents === null ? null : Number(r.amount_paid_cents),
+    amountCreditedCents: r.amount_credited_cents === null ? null : Number(r.amount_credited_cents),
+    itemCodes: [...new Set((r.lines ?? []).map((l) => l.itemCode).filter(Boolean))],
+    flowInvoiceId: r.flow_invoice_id ?? null,
+    changedAt: r.last_changed_at,
+  };
+}
+
+// Sales invoices from the mirror, by any of: Xero ids, invoice numbers, the
+// Flow invoices Flow sent, or one customer within a date range. Answers the
+// mirror's state with them, and the latest change time it holds.
+export async function findInvoices(db, organisationId, query = {}) {
+  const { invoiceIds = [], numbers = [], flowInvoiceIds = [], contactId = null, from = null, to = null } = query;
+  const where = [];
+  if (invoiceIds.length) where.push(sql`i.xero_invoice_id = any(${ids(invoiceIds)}::text[])`);
+  if (numbers.length) where.push(sql`upper(i.invoice_number) = any(${sql.param([...new Set(numbers.map((n) => String(n).toUpperCase()))])}::text[])`);
+  if (flowInvoiceIds.length) where.push(sql`p.invoice_id = any(${ids(flowInvoiceIds)}::uuid[])`);
+  if (contactId) {
+    where.push(sql`(i.xero_contact_id = ${contactId}
+      ${from ? sql`and i.issued_on >= ${from}::date` : sql``}
+      ${to ? sql`and i.issued_on <= ${to}::date` : sql``})`);
+  }
+  const state = await mirrorState(db, organisationId);
+  if (!where.length) return { ...state, invoices: [] };
+  const { rows } = await db.execute(sql`
+    select i.*, p.invoice_id as flow_invoice_id
+    from xero_invoices i
+    left join lateral (
+      select invoice_id from xero_invoice_pushes
+      where organisation_id = i.organisation_id and xero_invoice_id = i.xero_invoice_id
+      order by version desc limit 1
+    ) p on true
+    where i.organisation_id = ${organisationId} and i.type = 'ACCREC'
+      and (${sql.join(where, sql` or `)})
+    order by i.issued_on, i.xero_invoice_id
+    limit 500`);
+  return { ...state, invoices: rows.map(invoiceRow) };
+}

package/server/theme/color-contrast.js

@@ -1,5 +1,6 @@
-// WCAG 2.1 contrast helpers for theme tokens (server/theme/themes.js and
-// scripts/port-openclaw-themes.mjs). Colours are #rrggbb.
+// WCAG 2.1 contrast helpers for theme tokens (server/theme/themes.js,
+// server/theme/contrast-audit.js and scripts/port-openclaw-themes.mjs).
+// Colours are #rrggbb, except where parseColor reads a translucent one.
 
 export const HEX = /^#[0-9a-f]{6}$/i;
 
@@ -37,6 +38,16 @@ export function readableOn(color, bg, target = 4.5) {
   return toward[0] ? '#ffffff' : '#000000';
 }
 
+/** readableOn for every surface in turn, until the colour reads on all of them. */
+export function readableOnEvery(color, surfaces, target = 4.5) {
+  let out = color;
+  for (let pass = 0; pass < 3; pass += 1) {
+    for (const bg of surfaces) out = readableOn(out, bg, target);
+    if (surfaces.every((bg) => !HEX.test(out) || !HEX.test(bg) || contrast(out, bg) >= target)) break;
+  }
+  return out;
+}
+
 /**
  * A boundary colour for controls on `bg` (an input's or an outlined button's
  * edge): `bg` mixed toward `ink` just enough to stand out at `target`
@@ -52,3 +63,29 @@ export function boundaryOn(bg, ink, target = 3) {
   }
   return ink;
 }
+
+/** [r, g, b, a] (0-255, alpha 0-1) for #rrggbb, rgb()/rgba() or color-mix(in srgb, X N%, transparent). */
+export function parseColor(value) {
+  const v = String(value).trim();
+  let m = v.match(/^#([0-9a-f]{6})$/i);
+  if (m) return [0, 2, 4].map((i) => Number.parseInt(m[1].slice(i, i + 2), 16)).concat(1);
+  m = v.match(/^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)(?:[\s,/]+([\d.]+%?))?\s*\)$/i);
+  if (m) {
+    const a = m[4] === undefined ? 1 : m[4].endsWith('%') ? Number.parseFloat(m[4]) / 100 : Number(m[4]);
+    return [Number(m[1]), Number(m[2]), Number(m[3]), a];
+  }
+  m = v.match(/^color-mix\(in srgb,\s*(.+?)\s+([\d.]+)%,\s*transparent\)$/i);
+  if (m) {
+    const [r, g, b, a] = parseColor(m[1]);
+    return [r, g, b, a * Number(m[2]) / 100];
+  }
+  throw new Error(`contrast audit cannot read colour "${value}"`);
+}
+
+/** `top` painted over `under` (each a colour string), as an opaque #rrggbb. */
+export function over(top, under) {
+  const [r, g, b, a] = parseColor(top);
+  const base = parseColor(under);
+  if (base[3] < 1) throw new Error(`contrast audit needs an opaque surface, got "${under}"`);
+  return `#${[r, g, b].map((c, i) => Math.round(c * a + base[i] * (1 - a)).toString(16).padStart(2, '0')).join('')}`;
+}

package/server/theme/contrast-audit.js

@@ -0,0 +1,63 @@
+// The WCAG AA contrast audit for every design system (server/theme/themes.js).
+// Each pair is a foreground a screen really draws on a surface it really sits
+// on: Flow's components (server/ui/flow.css) and Clerk's account and sign-in
+// screens (server/ui/clerk-appearance.js). Translucent tokens (rgba() and
+// color-mix() toward transparent) are laid over the surface they sit on before
+// the ratio is taken, the way a browser paints them. test/theme-contrast.test.js
+// runs it in CI; `npm run theme:contrast` prints the table.
+import { contrast, over, parseColor } from './color-contrast.js';
+
+// WCAG 2.1: 4.5:1 for text (1.4.3), 3:1 for the edge or fill that shows a
+// control or its state (1.4.11).
+export const TEXT = 4.5;
+export const UI = 3;
+
+function withAlpha(color, alpha) {
+  const [r, g, b, a] = parseColor(color);
+  return `rgba(${r}, ${g}, ${b}, ${a * alpha})`;
+}
+
+// [id, what it is, minimum, (tokens) => [foreground, surface]]. A surface
+// given as an array is laid bottom first, so a tinted badge on a card is
+// [paper, tint].
+const PAIRS = [
+  ['text/bg', 'Body text on the page', TEXT, (k) => [k['--t-text'], k['--t-bg']]],
+  ['text/paper', 'Body text on a card', TEXT, (k) => [k['--t-text'], k['--t-paper']]],
+  ['strong/paper', 'Headings and names on a card', TEXT, (k) => [k['--t-strong'], k['--t-paper']]],
+  ['strong/bg', 'Page titles on the page', TEXT, (k) => [k['--t-strong'], k['--t-bg']]],
+  ['dim/bg', 'Secondary text on the page', TEXT, (k) => [k['--t-dim'], k['--t-bg']]],
+  ['dim/paper', 'Secondary text on a card (Clerk muted text)', TEXT, (k) => [k['--t-dim'], k['--t-paper']]],
+  ['dim/s1', 'Table headings, Clerk side menu', TEXT, (k) => [k['--t-dim'], k['--t-s1']]],
+  ['dim/s2', 'Segmented control labels', TEXT, (k) => [k['--t-dim'], k['--t-s2']]],
+  ['mute/paper', 'Muted text on a card', TEXT, (k) => [k['--t-mute'], k['--t-paper']]],
+  ['accent/bg', 'Links on the page', TEXT, (k) => [k['--t-accent'], k['--t-bg']]],
+  ['accent/paper', 'Links on a card', TEXT, (k) => [k['--t-accent'], k['--t-paper']]],
+  ['accent/accent-bg', 'Status and role badges', TEXT, (k) => [k['--t-accent'], [k['--t-paper'], k['--t-accent-bg']]]],
+  ['strong/accent-bg', 'Current page in the menu', TEXT, (k) => [k['--t-strong'], [k['--t-bg'], k['--t-accent-bg']]]],
+  ['text/accent-bg', 'Notices', TEXT, (k) => [k['--t-text'], [k['--t-paper'], k['--t-accent-bg']]]],
+  ['on-primary/primary', 'Primary buttons', TEXT, (k) => [k['--t-on-primary'], k['--t-primary']]],
+  ['brand-ink/brand', 'Text on the brand colour', TEXT, (k) => [k['--t-brand-ink'], k['--t-brand']]],
+  ['success/success-bg', 'Success badges', TEXT, (k) => [k['--t-success'], [k['--t-paper'], k['--t-success-bg']]]],
+  ['warn/warn-bg', 'Warning badges', TEXT, (k) => [k['--t-warn'], [k['--t-paper'], k['--t-warn-bg']]]],
+  ['danger/danger-bg', 'Error notices', TEXT, (k) => [k['--t-danger'], [k['--t-paper'], k['--t-danger-bg']]]],
+  ['paper/danger', 'Danger buttons and error toasts', TEXT, (k) => [k['--t-paper'], k['--t-danger']]],
+  ['bg/strong', 'Toasts', TEXT, (k) => [k['--t-bg'], k['--t-strong']]],
+  // server/ui/clerk-appearance.js: badge.
+  ['clerk-badge', 'Clerk "Primary" badge by an email', TEXT, (k) => [k['--t-dim'], [k['--t-paper'], withAlpha(k['--t-text'], 0.05)]]],
+  ['control/paper', 'Input and outlined button edges', UI, (k) => [k['--t-control'], k['--t-paper']]],
+  ['ring/paper', 'Focus ring', UI, (k) => [k['--t-ring'], k['--t-paper']]],
+  ['brand/paper', 'Selected theme card ring', UI, (k) => [k['--t-brand'], k['--t-paper']]],
+  ['primary/paper', 'Primary button edge on a card', UI, (k) => [k['--t-primary'], k['--t-paper']]],
+];
+
+/** Every pair for one family and mode: { id, label, min, fg, bg, ratio, pass }. */
+export function auditTokens(tokens) {
+  return PAIRS.map(([id, label, min, pick]) => {
+    const [fgRaw, surface] = pick(tokens);
+    const layers = Array.isArray(surface) ? surface : [surface];
+    const bg = layers.slice(1).reduce((under, top) => over(top, under), over(layers[0], '#ffffff'));
+    const fg = over(fgRaw, bg);
+    const ratio = contrast(fg, bg);
+    return { id, label, min, fg, bg, ratio: Math.round(ratio * 100) / 100, pass: ratio >= min };
+  });
+}

package/server/theme/themes.js

@@ -9,7 +9,7 @@
  * ./openclaw-palettes.js (docs/DESIGN.md). The engine is Arc Forge Labs'
  * Field's, so a family looks the same in both apps.
  */
-import { boundaryOn, HEX, inkOn, readableOn } from './color-contrast.js';
+import { boundaryOn, contrast, HEX, inkOn, over, readableOn, readableOnEvery } from './color-contrast.js';
 import { OPENCLAW_FAMILIES } from './openclaw-palettes.js';
 
 export { boundaryOn, contrast, inkOn, readableOn } from './color-contrast.js';
@@ -125,12 +125,20 @@ const MERIDIAN = {
 const { beacon, tide, claw, knot, dash, ...otherOpenclaw } = OPENCLAW_FAMILIES;
 const FAMILIES = { harbour: HARBOUR, meridian: MERIDIAN, beacon, tide, claw, knot, dash, ...otherOpenclaw };
 
+// Every family keeps WCAG AA (test/theme-contrast.test.js). A ported palette
+// that misses it on a surface Flow uses is nudged here, just far enough:
+// secondary text on every surface, accent text on the page, cards and its own
+// tint, and the ink on the brand colour. Harbour and Meridian already pass.
 // --t-control: the edge of an input or an outlined button on --t-paper, the
 // text colour faded toward the paper only as far as it still reads at 3:1.
 for (const family of Object.values(FAMILIES)) {
   for (const mode of ['light', 'dark']) {
     const tokens = family[mode];
-    tokens['--t-control'] = boundaryOn(tokens['--t-paper'], tokens['--t-text']);
+    const { '--t-bg': bg, '--t-paper': paper, '--t-s1': s1, '--t-s2': s2 } = tokens;
+    tokens['--t-dim'] = readableOnEvery(tokens['--t-dim'], [bg, paper, s1, s2]);
+    tokens['--t-accent'] = readableOnEvery(tokens['--t-accent'], [bg, paper, over(tokens['--t-accent-bg'], paper)]);
+    if (contrast(tokens['--t-brand-ink'], tokens['--t-brand']) < 4.5) tokens['--t-brand-ink'] = inkOn(tokens['--t-brand']);
+    tokens['--t-control'] = boundaryOn(paper, tokens['--t-text']);
   }
 }
 

package/server/ui/app-page.js

@@ -12,11 +12,6 @@ const BODY = `<div class="fx-app">
     <div class="fx-auth__brand">
       <span class="fx-brand fx-brand--large">${FLOW_MARK}<span>Flow</span></span>
       <h1 class="fx-auth__title" id="auth-title">Every job billed, every invoice paid.</h1>
-      <ul class="fx-auth__points">
-        <li>Jobs come in from the lab system.</li>
-        <li>Invoices go out to Xero.</li>
-        <li>Payments come back and close the job.</li>
-      </ul>
     </div>
     <div class="fx-auth__form">
       <p class="fx-auth__note" id="sign-in-note"></p>
@@ -40,20 +35,20 @@ const BODY = `<div class="fx-app">
   </section>
 
   <div class="fx-state-signed-in fx-shell">
-    <header class="fx-top">
+    <aside class="fx-side">
       <a class="fx-brand" href="/">${FLOW_MARK}<span>Flow</span></a>
       <nav class="fx-nav" id="nav" aria-label="Flow"></nav>
-      <div class="fx-top__end">
+      <div class="fx-side__end">
+        <div id="user-button" class="fx-side__user"></div>
         <button type="button" class="fx-btn fx-btn--ghost fx-btn--icon fx-mode-toggle" data-mode-toggle>Light or dark</button>
-        <div id="user-button" class="fx-top__user"></div>
       </div>
-    </header>
+    </aside>
     <main id="main" class="fx-main" tabindex="-1"></main>
   </div>
   <div id="toasts" class="fx-toasts" aria-live="polite"></div>
 </div>`;
 
-export const APP_PATHS = ['/sign-in', '/people', '/integrations', '/account', '/appearance'];
+export const APP_PATHS = ['/sign-in', '/jobs', '/invoices', '/invoices/:id', '/people', '/integrations', '/integrations/:id', '/account', '/appearance'];
 
 export function appPage({ defaultFamily }) {
   return renderPage({