@arcforgelabs/flow 2026.11.2 → 2026.11.4

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

@@ -190,6 +190,20 @@
       "when": 1794019099844,
       "tag": "0026_bitter_sersi",
       "breakpoints": true
+    },
+    {
+      "idx": 27,
+      "version": "7",
+      "when": 1794454051454,
+      "tag": "0027_high_doctor_strange",
+      "breakpoints": true
+    },
+    {
+      "idx": 28,
+      "version": "7",
+      "when": 1794456064675,
+      "tag": "0028_sharp_power_pack",
+      "breakpoints": true
     }
   ]
 }

package/server/db/schema.js

@@ -715,6 +715,27 @@ export const invoiceRules = pgTable('invoice_rules', {
   check('invoice_rules_icon_valid', sql`${t.icon} is null or (length(${t.icon}) between 1 and 64 and ${t.icon} !~ '[^a-z0-9-]')`),
 ]);
 
+// A person's exception to one invoice rule for one job (docs/INVOICE_RULES.md,
+// "Exceptions"): the rule matched, and a person said this job is fine as it
+// is, with a reason. The rule then leaves that job alone, and its card counts
+// and lists each exception, so none is hidden.
+export const invoiceRuleExceptions = pgTable('invoice_rule_exceptions', {
+  id: id(),
+  organisationId: organisationId().references(() => organisations.id),
+  ruleId: uuid('rule_id').notNull().references(() => invoiceRules.id, { onDelete: 'cascade' }),
+  obligationId: uuid('obligation_id').notNull().references(() => billingObligations.id),
+  reason: text('reason').notNull(),
+  actor: text('actor').notNull(),
+  // What the exception was given for: the rule's item and the job's lines
+  // then. A change to either ends it, so a person looks again.
+  itemCode: text('item_code'),
+  lineFingerprint: text('line_fingerprint'),
+  createdAt: createdAt(),
+}, (t) => [
+  uniqueIndex('invoice_rule_exceptions_rule_job').on(t.ruleId, t.obligationId),
+  check('invoice_rule_exceptions_reason_valid', sql`length(${t.reason}) between 1 and 200`),
+]);
+
 // Automations (server/core/automations.js): Flow's routines, each on or off,
 // with its own settings. The routines are defined in code; a row holds an
 // organisation's choice. No row means the routine's default.

package/server/integrations/seazona/feed.js

@@ -217,9 +217,16 @@ export const WORK_FINISHED_DAYS = 30;
 const WORK_LIMIT = 2000;
 const FINAL_SQL = sql`coalesce(${seazonaOrders.status}, '') ~* '(shipped|delivered|cancelled|canceled|void|closed|archived|deleted)'`;
 
+// A finished order that still has no invoice stays on the board past
+// WORK_FINISHED_DAYS: its job has no Flow invoice and no accounting invoice
+// linked, and the order was not cancelled. It leaves when it is billed.
+const UNBILLED_SQL = sql`(coalesce(${seazonaOrders.status}, '') !~* '(cancelled|canceled|void|deleted)' and exists (
+  select 1 from billing_obligations o where o.source_system = 'seazona' and o.source_job_ref = ${seazonaOrders.id}
+    and o.invoice_id is null and o.accounting_ref is null))`;
+
 // The orders behind the port's listWork, for the Jobs board: every open
-// order, and each final order that changed in the last WORK_FINISHED_DAYS
-// days, newest change first. An order deleted in Seazona is never listed.
+// order, each final order that changed in the last WORK_FINISHED_DAYS
+// days, and each finished order not billed yet, newest change first. An order deleted in Seazona is never listed.
 // The client name is the Seazona client's company (or full name), else the
 // order's own company. `statuses` lists each status once, with the first time
 // Flow saw an order in it, so the board can order its columns.
@@ -228,7 +235,7 @@ export async function listWork(db, { now = Date.now(), finishedDays = WORK_FINIS
   const rows = await db.select({ order: seazonaOrders, company: seazonaClients.company, fullName: seazonaClients.fullName })
     .from(seazonaOrders)
     .leftJoin(seazonaClients, eq(seazonaClients.id, seazonaOrders.clientId))
-    .where(and(isNull(seazonaOrders.deletedInSourceAt), or(sql`not (${FINAL_SQL})`, gte(seazonaOrders.lastChangedAt, since))))
+    .where(and(isNull(seazonaOrders.deletedInSourceAt), or(sql`not (${FINAL_SQL})`, gte(seazonaOrders.lastChangedAt, since), UNBILLED_SQL)))
     .orderBy(desc(seazonaOrders.lastChangedAt), seazonaOrders.id)
     .limit(limit);
   const firstSeen = new Map();

package/server/integrations/seazona/index.js

@@ -53,6 +53,7 @@ export const SEAZONA_SETUP = {
     { name: 'SEAZONA_API_CLIENT_SECRET', label: 'Client secret', secret: true, help: 'Stored encrypted. Flow never shows it again.' },
     { name: 'SEAZONA_ORDER_URL', label: 'Order address', kind: 'url', help: 'Optional. Open any order in Seazona and paste its address here, or write {ref} where the order id goes. Stage moves on the Jobs board and Open in Seazona use it.' },
     { name: 'SEAZONA_KEEP_PATIENT_REFERENCE', label: 'Keep patient names', kind: 'onoff', help: 'On: Flow keeps the patient name of each job for the invoice Reference.' },
+    { name: 'SEAZONA_API_READ_HIDE_PATIENT', label: 'Hide patient details', kind: 'onoff', help: 'On: an AI assistant reading Seazona through Flow gets no patient, note, file or clinical fields.' },
   ],
 };
 
@@ -85,7 +86,11 @@ export function createSeazonaAdapter({ env = null, fetchImpl = null, now = Date.
     schema: seazonaSchema,
     setup: SEAZONA_SETUP,
     // The history import's routes (routes.js), under /api/seazona.
-    routes: ({ db, personAuth, log }) => createSeazonaRouter({ db: runtime?.db ?? db, personAuth, settings: current().settings, log }),
+    routes: ({ db, personAuth, log }) => createSeazonaRouter({
+      db: runtime?.db ?? db, personAuth, settings: current().settings, log,
+      read: (path, query) => current().client.get(path, query),
+      hidePatientFields: () => Boolean(current().settings.sync.hidePatientFields),
+    }),
     // Every Seazona call goes through this call guard, inside the rate
     // governor (governor.js; docs/INTEGRATIONS.md, "Outbound calls").
     callGuard: SEAZONA_CALL_GUARD,

package/server/integrations/seazona/routes.js

@@ -36,7 +36,16 @@ import { readBackfill, startBackfill, stopBackfill } from './history/backfill.js
 //                                         (state: one state, or needs_person)
 //   POST /history/ledger/:obligationId/release   owner or admin: the job may draft
 //
-// None of these call Seazona.
+// None of these call Seazona, except one read:
+//
+//   GET  /api/<resource>[/<id>]?<query>   owner or admin: one GET to the
+//                                         Seazona REST API, through Flow's
+//                                         rate governor, answered as
+//                                         { ok, data }. resource is invoices,
+//                                         orders, clients, products or users.
+//                                         It never writes to Seazona. It is how
+//                                         an AI assistant reads Seazona with its
+//                                         Flow key (docs/AGENT_ACCESS.md).
 
 export const MAX_UPLOAD = '25mb';
 
@@ -56,7 +65,40 @@ const handle = (log, fn) => async (req, res) => {
   }
 };
 
-export function createSeazonaRouter({ db, personAuth, settings, log = console }) {
+const API_RESOURCES = ['invoices', 'orders', 'clients', 'products', 'users'];
+
+// With "Hide patient details" on (SEAZONA_API_READ_HIDE_PATIENT), any field
+// whose name says patient, note, file, prescription and the like is dropped
+// from the read, at any depth. Off by default.
+const PRIVATE_FIELD = /patient|note|comment|instruction|remark|file|attach|image|photo|prescri|shade|clinical|medical|birth|dob/i;
+// The value is parsed JSON, so it has no cycles.
+export function withoutPrivateFields(value) {
+  if (Array.isArray(value)) return value.map(withoutPrivateFields);
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(Object.entries(value)
+    .filter(([key]) => !PRIVATE_FIELD.test(key))
+    .map(([key, item]) => [key, withoutPrivateFields(item)]));
+}
+// A list read must carry the filter Flow's own sync uses. Seazona answers a
+// list without it with an error, and every error counts against the call
+// guard that also protects Flow's sync, so Flow refuses it before the call.
+const SEAZONA_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$/;
+const LIST_FILTERS = {
+  orders: { key: 'ordered', hint: 'ordered=2026-11-11T00:00:00 (one day)' },
+  invoices: { key: 'lastModified', hint: 'lastModified=2026-11-01T00:00:00' },
+  clients: { key: 'lastModified', hint: 'lastModified=2026-11-01T00:00:00' },
+};
+export function listQueryProblem(resource, query) {
+  const filter = LIST_FILTERS[resource];
+  if (filter && !SEAZONA_TIME.test(query[filter.key] ?? '')) return `A ${resource} list needs ${filter.hint}.`;
+  for (const key of ['page', 'pageSize']) {
+    if (key in query && !/^[1-9]\d{0,2}$/.test(query[key])) return `${key} must be a whole number from 1 to 999.`;
+  }
+  return null;
+}
+const API_PATH = new RegExp(`^/api/(${API_RESOURCES.join('|')})(?:/([A-Za-z0-9-]{1,64}))?/?$`);
+
+export function createSeazonaRouter({ db, personAuth, settings, read = null, hidePatientFields = () => false, log = console }) {
   const router = express.Router();
   // Sign-in off: every route answers 503, as the Xero routes do.
   const signedIn = personAuth
@@ -72,6 +114,27 @@ export function createSeazonaRouter({ db, personAuth, settings, log = console })
     return router;
   }
 
+  // One read from the Seazona API (above). Only plain query values pass on.
+  router.get(API_PATH, ...manager, handle(log, async (req, res) => {
+    if (!read) throw Object.assign(new FlowError('seazona_off', 'Seazona is not connected'), { status: 503 });
+    const [, resource, id] = API_PATH.exec(req.path);
+    const query = {};
+    for (const [key, value] of Object.entries(req.query)) {
+      if (typeof value === 'string' && /^[A-Za-z][A-Za-z0-9_]{0,40}$/.test(key)) query[key] = value.slice(0, 200);
+    }
+    const problem = id ? null : listQueryProblem(resource, query);
+    if (problem) return res.status(400).json({ ok: false, code: 'invalid', error: problem });
+    try {
+      const data = await read(id ? `${resource}/${id}` : `${resource}/`, query);
+      log.info?.(`[seazona] api read ${resource}${id ? '/:id' : ''} by ${actor(req)}`);
+      res.json({ ok: true, data: hidePatientFields() ? withoutPrivateFields(data) : data });
+    } catch (error) {
+      if (error?.name !== 'SeazonaApiError' && error?.name !== 'SeazonaCallsStopped') throw error;
+      const status = error.statusCode === 404 ? 404 : error.statusCode === 400 ? 400 : error.name === 'SeazonaCallsStopped' || error.statusCode === 429 || error.kind === 'governor_timeout' ? 429 : 502;
+      res.status(status).json({ ok: false, code: 'seazona_read_failed', error: error.message });
+    }
+  }));
+
   router.get('/history', ...signedIn, handle(log, async (req, res) => {
     res.json({ ok: true, history: await historySummary(db), backfill: await readBackfill(db), batches: await listBatches(db) });
   }));

package/server/integrations/seazona/settings.js

@@ -187,6 +187,9 @@ export function resolveSeazonaSettings(env = process.env) {
     // print one. Off by default; on, orders and invoices keep Seazona's
     // patient field as the reference.
     keepPatientReference: ['1', 'true', 'on', 'yes'].includes(text(env.SEAZONA_KEEP_PATIENT_REFERENCE).toLowerCase()),
+    // Off by default: the Seazona read (routes.js) answers what Seazona gives.
+    // On, it drops patient, note, file and clinical fields first.
+    hidePatientFields: ['1', 'true', 'on', 'yes'].includes(text(env.SEAZONA_API_READ_HIDE_PATIENT).toLowerCase()),
   };
 
   const settings = {

package/server/integrations/xero/drafts.js

@@ -532,7 +532,7 @@ async function pushOne(db, runtime, client, organisationId, invoiceId, { pushedB
     });
     if (recent) {
       throw xeroError('xero_same_reference_different_amount',
-        `Xero ${recent.InvoiceNumber || 'invoice'} has the same client and reference at ${(cents(recent.Total) / 100).toFixed(2)}. Nothing was sent. Void the extra one in Xero or in Flow.`,
+        `Xero ${recent.InvoiceNumber || 'invoice'} has the same client and reference at ${(cents(recent.Total) / 100).toFixed(2)}. Nothing was sent. If that Xero invoice bills this job, press Use Xero invoice.`,
         { status: 409, details: { xero: shownXero(recent) } });
     }
   }

package/server/integrations/xero/index.js

@@ -155,7 +155,7 @@ export function createXeroAdapter({ runtime: given = null } = {}) {
       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),
+      checkInvoice: ({ organisationId, obligation, reference = null }) => xeroLiveCheck(database, current(), organisationId)(obligation, { reference }),
       // Xero's latest changes into the copy just before Flow drafts by rule or
       // sends (webhooks.js); no call when the copy is current.
       readChanges: ({ organisationId }) => readChangesFirst(database, current(), organisationId),

package/server/integrations/xero/ledger.js

@@ -81,7 +81,7 @@ async function several(runtime, client, found, checkedAt) {
 
 // The Xero invoice for one obligation (a row of billing_obligations), looked
 // up live. Costs 1 to 4 Xero calls.
-export async function checkInvoice(db, runtime, client, organisationId, obligation) {
+export async function checkInvoice(db, runtime, client, organisationId, obligation, { reference: draftReference = null } = {}) {
   const checkedAt = new Date(runtime.now()).toISOString();
 
   // 1. The Xero invoice Flow made from the job's Flow invoice.
@@ -119,7 +119,11 @@ export async function checkInvoice(db, runtime, client, organisationId, obligati
   // 3. The work system's own invoice number, as Xero's number or reference.
   if (obligation.sourceInvoiceRef) {
     const byId = new Map();
-    for (const inv of sales(await client.findInvoicesByNumber(obligation.sourceInvoiceRef))) byId.set(inv.InvoiceID, inv);
+    // Its reissue too (a trailing R): a lab that reissued the work voided the
+    // first invoice and bills the R one. One call: Xero takes a list.
+    const base = obligation.sourceInvoiceRef.replace(/R$/i, '');
+    const numbers = [...new Set([obligation.sourceInvoiceRef, base, `${base}R`])].join(',');
+    for (const inv of sales(await client.findInvoicesByNumber(numbers))) byId.set(inv.InvoiceID, inv);
     for (const inv of sales(await client.findInvoicesByReference(obligation.sourceInvoiceRef))) byId.set(inv.InvoiceID, inv);
     const found = [...byId.values()];
     if (found.length === 1) return evidenceFor(runtime, client, found[0], 'source_invoice_ref', checkedAt);
@@ -128,8 +132,8 @@ export async function checkInvoice(db, runtime, client, organisationId, obligati
 
   // 4. The reference Flow would give the job's invoice, for the same
   // customer. Not exact: it refuses a draft and goes to a person.
-  const reference = obligation.caseRef ?? obligation.sourceJobRef;
-  if (reference) {
+  const references = [...new Set([obligation.caseRef ?? obligation.sourceJobRef, draftReference].filter(Boolean))];
+  if (references.length) {
     let customer = null;
     if (obligation.contactId) {
       const [contact] = await db.select({ name: flowContacts.name }).from(flowContacts)
@@ -143,8 +147,13 @@ export async function checkInvoice(db, runtime, client, organisationId, obligati
       }
     }
     // Another customer's invoice with the same reference is not this job's.
-    const found = sales(await client.findInvoicesByReference(reference))
-      .filter((inv) => !customer || inv.Contact?.ContactID === customer);
+    const byId = new Map();
+    for (const reference of references) {
+      for (const inv of sales(await client.findInvoicesByReference(reference))) {
+        if (!customer || inv.Contact?.ContactID === customer) byId.set(inv.InvoiceID, inv);
+      }
+    }
+    const found = [...byId.values()];
     if (found.length === 1) return evidenceFor(runtime, client, found[0], 'reference', checkedAt);
     if (found.length > 1) return several(runtime, client, found, checkedAt);
   }
@@ -155,9 +164,9 @@ export async function checkInvoice(db, runtime, client, organisationId, obligati
 //   draftInvoiceForObligation(db, org, id, { liveCheck: xeroLiveCheck(db, runtime, org), actor })
 // A Xero error throws, and the ledger then refuses the draft.
 export function xeroLiveCheck(db, runtime, organisationId) {
-  return (obligation) => withXeroLane('reads', async () => {
+  return (obligation, options = {}) => withXeroLane('reads', async () => {
     const { client } = await runtime.clientFor(db, organisationId);
-    return checkInvoice(db, runtime, client, organisationId, obligation);
+    return checkInvoice(db, runtime, client, organisationId, obligation, options);
   });
 }
 

package/server/integrations/xero/links.js

@@ -1,5 +1,5 @@
 import { and, eq, sql } from 'drizzle-orm';
-import { contacts, priceItems } from '../../db/schema.js';
+import { billingObligations, contacts, invoices, obligationEvents, priceItems } from '../../db/schema.js';
 import { createContact } from '../../core/directory.js';
 import { FlowError } from '../../core/errors.js';
 import { createDraftInvoice, issueInvoice } from '../../core/invoices.js';
@@ -234,6 +234,44 @@ export async function linkXeroInvoice(db, organisationId, xeroInvoiceId, { invoi
   return { xeroInvoiceId, invoiceId };
 }
 
+// "Use the Xero invoice": Send stopped a Flow invoice because Xero already
+// bills the same client and reference at another amount. The Xero invoice is
+// the real bill. In one step Flow voids its own copy (never sent to Xero),
+// makes its Flow invoice from the Xero one, and gives that to the job. A copy
+// a person voided earlier, whose job still points at it, is cleaned up the
+// same way. The
+// Flow copy's job is the job; an invoice billing more than one job is linked
+// by hand. The Xero invoice must be the same client's.
+export async function useXeroInvoice(db, organisationId, invoiceId, { xeroInvoiceId, actor }) {
+  if (!actor) throw new FlowError('invalid', 'actor is required');
+  const row = await rowFor(db, organisationId, xeroInvoiceId);
+  return db.transaction(async (tx) => {
+    const { rows: [invoice] } = await tx.execute(sql`select id, number, status, contact_id from invoices
+      where organisation_id = ${organisationId} and id = ${invoiceId} for update`);
+    if (!invoice) throw new FlowError('not_found', 'Flow invoice not found');
+    // A copy voided earlier, still holding its job, gives way the same way.
+    if (!['issued', 'void'].includes(invoice.status)) throw new FlowError('invalid', 'only an approved or void Flow invoice can give way to a Xero invoice');
+    if (row.contactId !== invoice.contact_id) throw new FlowError('invalid', 'the Xero invoice is for another client');
+    const { rows: pushed } = await tx.execute(sql`select 1 from xero_invoice_pushes where organisation_id = ${organisationId} and invoice_id = ${invoiceId} and xero_invoice_id is not null limit 1`);
+    if (pushed.length) throw new FlowError('invalid', 'Flow sent that invoice to Xero already');
+    const jobs = await tx.select({ id: billingObligations.id }).from(billingObligations)
+      .where(and(eq(billingObligations.organisationId, organisationId), eq(billingObligations.invoiceId, invoiceId)))
+      .for('update');
+    if (jobs.length > 1) throw new FlowError('invalid', 'the Flow invoice bills more than one job; link each by hand');
+    if (invoice.status === 'issued') await tx.update(invoices).set({ status: 'void', updatedAt: sql`now()` }).where(eq(invoices.id, invoiceId));
+    else if (!jobs.length) throw new FlowError('invalid', 'the void Flow invoice holds no job');
+    for (const job of jobs) {
+      await tx.update(billingObligations).set({ invoiceId: null, draftBasis: null, updatedAt: sql`now()` }).where(eq(billingObligations.id, job.id));
+      await tx.insert(obligationEvents).values({
+        createdAt: sql`clock_timestamp()`, organisationId, obligationId: job.id, kind: 'draft_deleted', actor,
+        evidence: { invoiceId, reason: 'used_xero_invoice', xeroInvoiceId, xeroNumber: row.number ?? null },
+      });
+    }
+    const made = await makeFrom(tx, organisationId, row, { jobId: jobs[0]?.id ?? null, actor });
+    return { voided: { id: invoiceId, number: invoice.number }, invoice: { id: made.invoice.id, number: made.invoice.number }, xeroInvoiceId, jobId: jobs[0]?.id ?? null };
+  });
+}
+
 // Makes Flow's own invoice from a Xero invoice in the copy, finalised on the
 // Xero invoice's date, and links the two. With `jobId`, the job gets it as its
 // invoice. The client is Flow's customer of the same name, or a new one.

package/server/integrations/xero/lookup.js

@@ -90,6 +90,7 @@ function invoiceRow(r) {
     id: r.xero_invoice_id,
     number: r.invoice_number,
     contactId: r.xero_contact_id,
+    reference: r.reference ?? null,
     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) }),
@@ -109,10 +110,11 @@ function invoiceRow(r) {
 // 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 { invoiceIds = [], numbers = [], references = [], 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 (references.length) where.push(sql`upper(i.reference) = any(${sql.param([...new Set(references.map((r) => String(r).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}

package/server/integrations/xero/routes.js

@@ -8,7 +8,7 @@ import { createCustomer, linkCustomer, matchCustomer } from './create-contact.js
 import { createXeroClient } from './client.js';
 import { describePush, listPushes, MAX_BATCH, previewDrafts, pushDrafts } from './drafts.js';
 import { recordXeroEvidence, recordXeroPayments } from './ledger.js';
-import { IMPORT_STATES, importOverview, linkXeroInvoice, makeFlowInvoice, matchXero, saveImportSettings } from './links.js';
+import { IMPORT_STATES, importOverview, linkXeroInvoice, makeFlowInvoice, matchXero, saveImportSettings, useXeroInvoice } from './links.js';
 import { queueHistoryImport, resetImport } from './import.js';
 import { MIRROR_RESOURCES, mirrorStatus, mirrorXero } from './mirror.js';
 import { accountingStatus, checkSentInvoices } from './reconcile.js';
@@ -43,6 +43,10 @@ import { messagePage as themedMessagePage } from '../../ui/page.js';
 //                                  status and any difference, from the copy
 //   POST /invoices/:invoiceId/recheck   owner or admin: reads Xero's changes,
 //                                  then checks that one invoice again (Mark resolved)
+//   POST /invoices/:invoiceId/use-xero  owner or admin: { xeroInvoiceId } Send
+//                                  stopped this invoice for a Xero invoice of the
+//                                  same client and reference: void the Flow copy
+//                                  and give its job the Xero invoice (links.js)
 //   POST /obligations/:obligationId/check   owner or admin: Xero's invoice for
 //                                  a billable job, recorded on the ledger
 //   POST /payments/sync            owner or admin: Xero payments to the ledger
@@ -65,6 +69,7 @@ import { messagePage as themedMessagePage } from '../../ui/page.js';
 export const XERO_ACTIONS = Object.freeze({
   sync: { cooldownMs: 5 * 60_000 },
   recheck: { cooldownMs: 30_000 },
+  useXero: { cooldownMs: 10_000 },
   push: { cooldownMs: 0, budget: false },
   createContact: { cooldownMs: 30_000 },
   obligationCheck: { cooldownMs: 30_000 },
@@ -355,6 +360,18 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, butto
     res.json({ ok: true, resolved: !status?.finding, closed: result.closed, status });
   }));
 
+  router.post('/invoices/:invoiceId/use-xero', ...manager, act('useXero', (req) => req.params.invoiceId), handle(log, async (req, res) => {
+    const organisationId = await requireOrganisation(db, req.body?.organisationId);
+    const [invoiceId] = requireInvoiceIds([req.params.invoiceId], 'invoiceId');
+    const xeroInvoiceId = typeof req.body?.xeroInvoiceId === 'string' && UUID.test(req.body.xeroInvoiceId) ? req.body.xeroInvoiceId : null;
+    if (!xeroInvoiceId) throw new FlowError('invalid', 'xeroInvoiceId must name a Xero invoice');
+    // The Xero invoice may be newer than Flow's copy: read Xero's changes first.
+    await mirrorXero(db, runtime, organisationId, { resources: ['invoices'] });
+    const result = await useXeroInvoice(db, organisationId, invoiceId, { xeroInvoiceId, actor: `person:${req.person.id}` });
+    log.info?.(`[xero] organisation ${organisationId}: person ${req.person.id} used Xero invoice ${xeroInvoiceId} for Flow invoice ${invoiceId}`);
+    res.json({ ok: true, ...result });
+  }));
+
   router.post('/invoices/push', ...manager, act('push'), handle(log, async (req, res) => {
     const organisationId = await requireOrganisation(db, req.body?.organisationId);
     const invoiceIds = requireInvoiceIds(req.body?.invoiceIds);

package/server/ui/app-page.js

@@ -51,7 +51,7 @@ const BODY = `<div class="fx-app">
   <div id="toasts" class="fx-toasts" aria-live="polite"></div>
 </div>`;
 
-export const APP_PATHS = ['/sign-in', '/jobs', '/captures', '/invoices', '/invoices/:id', '/contacts', '/contacts/:id', '/reconcile', '/reconcile/:id', '/xero-import', '/people', '/integrations', '/integrations/:id', '/account', '/appearance', '/invoicing-settings', '/invoicing-settings/:id', '/automations', '/price-list', '/price-list/:id', '/custom-fields'];
+export const APP_PATHS = ['/sign-in', '/home', '/jobs', '/captures', '/invoices', '/invoices/:id', '/contacts', '/contacts/:id', '/reconcile', '/reconcile/:id', '/xero-import', '/people', '/integrations', '/integrations/:id', '/account', '/appearance', '/invoicing-settings', '/invoicing-settings/:id', '/automations', '/price-list', '/price-list/:id', '/custom-fields'];
 
 export function appPage({ defaultFamily }) {
   return renderPage({

package/server/ui/app.js

@@ -18,6 +18,7 @@ import { renderPriceList } from '/assets/ui/price-list.js';
 import { renderPriceReconcile } from '/assets/ui/price-reconcile.js';
 import { renderCustomFields } from '/assets/ui/custom-fields.js';
 import { renderJobs } from '/assets/ui/jobs.js';
+import { renderHome } from '/assets/ui/home.js';
 import { renderReconcile } from '/assets/ui/reconcile.js';
 import { renderXeroImport } from '/assets/ui/xero-import.js';
 import { syncStatus } from '/assets/ui/sync-status.js';
@@ -153,6 +154,7 @@ let me = null;
 // menu. `sidebar: false`: opened by a link or Search only. Jobs and Invoices
 // cannot be unpinned (nav-pins.js).
 const VIEWS = {
+  home: { label: 'Home', icon: 'home', render: (main) => renderHome(main, ui()) },
   jobs: { label: 'Jobs', icon: 'jobs', render: (main) => renderJobs(main, ui()) },
   captures: { label: 'Capture', icon: 'camera', render: (main) => renderCaptures(main, ui()) },
   invoices: { label: 'Invoices', icon: 'invoices', render: (main, id) => (id ? renderInvoice(main, ui(), id) : renderInvoiceList(main, ui())) },
@@ -174,6 +176,7 @@ const VIEWS = {
 
 // Line icons for the sidebar, drawn on a 24-unit grid in the text colour.
 const ICON_PATHS = {
+  home: '<path d="M3 11l9-7 9 7"/><path d="M5 10v10h14V10"/><path d="M10 20v-6h4v6"/>',
   jobs: '<rect x="3" y="4" width="5" height="16" rx="1"/><rect x="10" y="4" width="5" height="11" rx="1"/><rect x="17" y="4" width="4" height="14" rx="1"/>',
   invoices: '<path d="M6 3h9l4 4v14H6z"/><path d="M14 3v5h5M9 13h7M9 17h5"/>',
   contacts: '<rect x="3" y="4" width="18" height="16" rx="2"/><circle cx="9" cy="10" r="2"/><path d="M6 16c.4-1.6 1.5-2.4 3-2.4s2.6.8 3 2.4M14 9h5M14 13h4"/>',
@@ -293,9 +296,9 @@ function reportMenuItem(openReport) {
   return accountMenuItem('Report a problem', 'flag', () => { openReport().catch((error) => toast(error.message, 'danger')); });
 }
 
-// The page a person lands on after sign-in, and for / or an unknown path.
-// Invoices opens on its Ready tab. A home page can take this over later.
-const START_VIEW = 'invoices';
+// The page a person lands on after sign-in, and for / or an unknown path:
+// Home, with the invoices ready to send and one Send.
+const START_VIEW = 'home';
 
 // The view and, for one record, its id: /invoices/<id> is ['invoices', '<id>'].
 function currentView() {
@@ -369,7 +372,7 @@ function sidebarViews() {
   return Object.entries(VIEWS).filter(([, view]) => view.sidebar !== false && view.place !== 'account' && (!view.ownerOnly || me?.person.role === 'owner'));
 }
 
-// Null until the shell reads the account. Jobs and Invoices are always in it.
+// Null until the shell reads the account. Home, Jobs and Invoices are always in it.
 let pinned = null;
 let pinEpoch = 0;
 let pinWrite = Promise.resolve();

package/server/ui/flow.css

@@ -359,11 +359,78 @@ a.fx-link:hover, a.fx-link:focus-visible { border-color: var(--t-strong); }
   background: #fff; box-shadow: inset 0 0 0 1px var(--fx-line);
 }
 .fx-logo--icon { background: var(--t-accent-bg); color: var(--t-accent); box-shadow: none; }
+/* Home: the invoices ready to send and one Send, then the way an invoice
+   goes after Send, drawn as one line of steps (a column on a phone). */
+.fx-home { display: grid; gap: 20px; max-width: 880px; }
+.fx-home__send {
+  position: relative; overflow: hidden;
+  display: grid; justify-items: start; gap: 6px; padding: 32px;
+  border: 1px solid var(--fx-line); border-radius: var(--t-radius-lg);
+  background:
+    radial-gradient(120% 140% at 100% 0%, color-mix(in srgb, var(--t-primary) 10%, transparent), transparent 60%),
+    var(--t-paper);
+}
+.fx-home__send[data-done] {
+  grid-template-columns: auto 1fr; align-items: center; column-gap: 16px;
+  background:
+    radial-gradient(120% 140% at 100% 0%, color-mix(in srgb, var(--t-success) 12%, transparent), transparent 60%),
+    var(--t-paper);
+}
+.fx-home__send[data-done] > :not(.fx-home__done) { grid-column: 2; }
+.fx-home__done {
+  grid-row: span 2; display: grid; place-items: center; width: 52px; height: 52px; border-radius: 50%;
+  background: var(--t-success-bg); color: var(--t-success);
+}
+.fx-home__done .fx-lucide { width: 26px; height: 26px; }
+.fx-home__count {
+  display: flex; align-items: baseline; flex-wrap: wrap; gap: 4px 12px;
+  color: var(--t-strong); font: 700 72px/1 var(--t-body); font-variant-numeric: tabular-nums; letter-spacing: -0.02em;
+}
+.fx-home__count span { font: 600 20px/1.2 var(--t-body); letter-spacing: 0; color: var(--t-text); }
+.fx-home__send[data-done] .fx-home__count span { font-size: 22px; color: var(--t-strong); }
+.fx-home__sum { color: var(--t-dim); font-size: 16px; font-variant-numeric: tabular-nums; }
+.fx-home__btn { min-height: 56px; min-width: 200px; margin-top: 14px; padding: 0 32px; font-size: 17px; border-radius: 999px; }
+.fx-home__btn .fx-lucide { width: 20px; height: 20px; }
+.fx-home__note { color: var(--t-dim); font-size: 13.5px; }
+
+/* Needs you: at most three rows beside Send; each opens its page. */
+.fx-home__needs { display: grid; align-content: start; gap: 10px; }
+.fx-home__needs h2 { margin: 0; }
+.fx-home__needs ul { display: grid; gap: 8px; margin: 0; padding: 0; list-style: none; }
+.fx-home__needs a {
+  display: grid; grid-template-columns: auto 1fr auto; align-items: center; gap: 12px;
+  min-height: 64px; padding: 10px 16px; border: 1px solid var(--fx-line); border-radius: var(--t-radius-lg);
+  background: var(--t-paper); color: var(--t-text); text-decoration: none;
+  transition: border-color 140ms var(--fx-ease), transform 140ms var(--fx-ease);
+}
+.fx-home__needs a:hover, .fx-home__needs a:focus-visible { border-color: var(--t-control); transform: translateY(-1px); }
+.fx-home__dot { display: grid; place-items: center; width: 36px; height: 36px; border-radius: 50%; background: var(--fx-hover); color: var(--t-dim); }
+.fx-home__dot .fx-lucide { width: 18px; height: 18px; }
+.fx-home__needs [data-tone="danger"] .fx-home__dot { background: var(--t-danger-bg); color: var(--t-danger); }
+.fx-home__needs [data-tone="warn"] .fx-home__dot { background: var(--t-warn-bg); color: var(--t-warn); }
+.fx-home__needs [data-tone="info"] .fx-home__dot { background: var(--t-accent-bg); color: var(--t-accent); }
+.fx-home__needs [data-tone="clear"] .fx-home__dot { background: var(--t-success-bg); color: var(--t-success); }
+.fx-home__what { display: grid; font-weight: 600; color: var(--t-strong); }
+.fx-home__what small { color: var(--t-dim); font-weight: 400; font-size: 13px; font-variant-numeric: tabular-nums; }
+.fx-home__needs [data-tone="clear"] .fx-home__what { color: var(--t-dim); font-weight: 500; }
+.fx-home__n { color: var(--t-strong); font: 700 22px/1 var(--t-body); font-variant-numeric: tabular-nums; }
+.fx-home__needs [data-tone="clear"] .fx-home__n { color: var(--t-dim); font-weight: 500; }
+
+@media (min-width: 1024px) {
+  .fx-home { grid-template-columns: minmax(0, 3fr) minmax(260px, 2fr); align-items: stretch; max-width: 1040px; }
+  .fx-home__send { align-content: center; }
+}
+@media (max-width: 639px) {
+  .fx-home__send { padding: 24px 20px; }
+  .fx-home__count { font-size: 60px; }
+  .fx-home__btn { width: 100%; }
+}
+
 .fx-tiles { display: grid; gap: 12px; }
 .fx-tiles + .fx-tiles { margin-top: 16px; }
 .fx-tiles__head { display: flex; align-items: center; justify-content: space-between; gap: 12px; }
 .fx-tiles__head h2 { color: var(--t-strong); font: 600 15px/1.3 var(--t-body); }
-.fx-tiles__more { display: inline-flex; align-items: center; gap: 4px; color: var(--t-dim); font-size: 13.5px; text-decoration: none; }
+.fx-tiles__more { display: inline-flex; align-items: center; gap: 4px; min-height: 44px; color: var(--t-dim); font-size: 13.5px; text-decoration: none; }
 .fx-tiles__more:hover, .fx-tiles__more:focus-visible { color: var(--t-strong); }
 .fx-tiles__more .fx-lucide { width: 15px; height: 15px; }
 .fx-tiles__grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(min(100%, 300px), 1fr)); gap: 12px; }
@@ -954,6 +1021,7 @@ th:hover > .fx-th-grip::after { background: var(--t-brd-hi); }
    follows the pointer, the lane that takes it, and the "Waiting for
    Seazona" chip of a stage move the work system has not made yet. */
 .fx-job__wait { justify-self: start; margin-top: 8px; padding: 1px 8px; border: 1px dashed var(--t-accent); border-radius: 999px; color: var(--t-accent); font-size: 11.5px; font-weight: 600; }
+.fx-job__wait--warn { border-color: var(--t-warn-brd); background: var(--t-warn-bg); color: var(--t-warn); }
 .fx-job--lifted { opacity: .35; }
 .fx-job--ghost { position: fixed; top: 0; left: 0; z-index: 60; pointer-events: none; box-shadow: var(--t-shadow-lg, var(--t-shadow)); cursor: grabbing; }
 .fx-board--dragging, .fx-board--dragging .fx-job { cursor: grabbing; user-select: none; }