@arcforgelabs/flow 2026.11.3 → 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/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.
@@ -132,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)
@@ -147,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);
   }
@@ -159,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/flow.css

@@ -1021,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; }

package/server/ui/invoice-rules.js

@@ -41,7 +41,8 @@ export function ruleSummary(rule, meta) {
     return `${field.label} ${test} ${value}`;
   };
   const then = rule.action.kind === 'pending' ? `Pending: ${rule.action.note}` : ACTION_LABELS[rule.action.kind] ?? rule.action.kind;
-  return `${rule.conditions.map(part).join(' and ')} · ${then}`;
+  const excepted = rule.exceptions ? ` · ${rule.exceptions} ${rule.exceptions === 1 ? 'exception' : 'exceptions'}` : '';
+  return `${rule.conditions.map(part).join(' and ')} · ${then}${excepted}`;
 }
 
 export function rulesSection(ui, title = 'Rules') {
@@ -169,7 +170,13 @@ export function rulesSection(ui, title = 'Rules') {
       placeholder: 'Type a note',
     });
     const noteField = h('div', { class: 'fx-field' }, h('span', { class: 'fx-label' }, 'Note on the draft'), note);
-    const showNote = () => { noteField.hidden = action.value !== 'pending'; };
+    // Optional: a price list code the draft offers to add in one press.
+    const addItem = h('input', {
+      class: 'fx-input', maxlength: '40', value: draft?.action.addItem ?? '', 'aria-label': 'Item to add',
+      placeholder: 'Price list code',
+    });
+    const addField = h('div', { class: 'fx-field' }, h('span', { class: 'fx-label' }, 'Offer to add'), addItem);
+    const showNote = () => { noteField.hidden = action.value !== 'pending'; addField.hidden = action.value !== 'pending'; };
     action.addEventListener('change', showNote);
     showNote();
     let editors = [];
@@ -218,6 +225,7 @@ export function rulesSection(ui, title = 'Rules') {
         label('If all of these match', list, more),
         label('Then', action),
         noteField,
+        addField,
         remove),
       confirm: rule ? 'Save' : 'Add rule',
     });
@@ -231,7 +239,7 @@ export function rulesSection(ui, title = 'Rules') {
       name: name.value,
       icon: icon.value(),
       conditions: editors.map((e) => e.read()),
-      action: action.value === 'pending' ? { kind: 'pending', note: note.value } : { kind: action.value },
+      action: action.value === 'pending' ? { kind: 'pending', note: note.value, ...(addItem.value.trim() ? { addItem: addItem.value.trim() } : {}) } : { kind: action.value },
     };
     const body = rule
       ? await send(`/api/invoicing/rules/${rule.id}`, 'PUT', payload)

package/server/ui/invoicing.js

@@ -940,6 +940,29 @@ const LINE_CARD_READ = { areas: ['desc desc amount', 'qty price gst'], columns:
 const brief = (text) => String(text ?? '').match(/^.*?[.!?](?=\s|$)/s)?.[0] ?? String(text ?? '');
 
 // A draft, or a new invoice before its first save.
+// Lines this invoice has that its job in the work system does not (the
+// invoice detail's sourceGap). Flow cannot add them there, so a yellow line
+// says what to add and links to the job.
+function sourceGapNotice(ui, invoice) {
+  const gap = invoice?.sourceGap ?? [];
+  if (!gap.length || !invoice.job) return null;
+  const system = invoice.job.systemName ?? 'the work system';
+  const what = gap.map((l) => `${l.description} (${formatCents(l.unitAmountCents * (l.quantity ?? 1))})`).join(', ');
+  const line = ui.notice(`This invoice has ${what}; the job in ${system} does not. Add it there so both agree.`, 'warn', `Not in ${system}.`);
+  if (!invoice.job.link?.url) return line;
+  return ui.h('div', { class: 'fx-offer' }, line,
+    ui.h('a', { class: 'fx-btn fx-btn--sm fx-btn--ghost', href: invoice.job.link.url, target: '_blank', rel: 'noopener' }, `Open in ${system}`));
+}
+
+// The exceptions people gave this job: the rule, why, and whether it still
+// holds (it ends when the job's lines or the rule's item change).
+function exceptionsNotice(ui, invoice) {
+  const list = invoice?.ruleExceptions ?? [];
+  if (!list.length) return null;
+  const text = list.map((e) => `${e.rule}: ${e.reason}${e.current ? '' : ' (ended: the job changed)'}`).join('; ');
+  return ui.notice(text, 'info', list.length === 1 ? 'Exception.' : 'Exceptions.');
+}
+
 function draftView(invoice, ui, context, redraw) {
   const { h, flow, toast, go, notice, fieldError } = ui;
   const isNew = !invoice;
@@ -1274,11 +1297,33 @@ function draftView(invoice, ui, context, redraw) {
     : [];
   // Every matching rule links to its own conditions and existing controls,
   // including custom rules. The target enforces read-only roles itself.
+  // A rule with an item to add offers it in one press, and Skip records an
+  // exception with a reason (POST .../rules/:rule/add-item and /exception).
+  const ruleFix = async (path, payload, done) => {
+    try {
+      const body = await flow(`/api/invoicing/invoices/${invoice.id}/rules/${path}`, { method: 'POST', body: JSON.stringify(payload ?? {}) });
+      ui.toast(done, 'success');
+      redraw(body.invoice);
+    } catch (error) {
+      ui.toast(error.message, 'danger');
+    }
+  };
+  const skipRule = async (p) => {
+    const reason = h('textarea', { class: 'fx-input', rows: 2, maxlength: 200, 'aria-label': 'Reason' });
+    const ok = await ui.dialog({ title: `Skip ${p.short ?? 'this rule'} for this job?`, body: h('div', {}, h('p', {}, 'The rule lists this job as an exception, with your reason.'), reason), confirm: 'Skip' });
+    if (!ok) return;
+    if (!reason.value.trim()) { ui.toast('Give a reason.', 'danger'); return; }
+    await ruleFix(`${p.rule}/exception`, { reason: reason.value.trim() }, 'Skipped. The rule shows the exception.');
+  };
   const ruleActions = [...new Map(problemList.filter(hasRuleReview).map((p) => [p.rule, p])).values()]
-    .map((p) => h('a', { class: 'fx-btn fx-btn--sm',
-      href: `/invoicing-settings/invoices?rule=${encodeURIComponent(p.rule)}`,
-      onclick: (event) => go(event),
-    }, `Review ${p.short ?? 'rule'}`));
+    .flatMap((p) => [
+      p.addItem && context.canIssue ? h('button', { class: 'fx-btn fx-btn--sm fx-btn--primary', type: 'button', onclick: () => ruleFix(`${p.rule}/add-item`, null, `${p.addItem} added.`) }, `Add ${p.addItem}`) : null,
+      p.addItem && context.canIssue ? h('button', { class: 'fx-btn fx-btn--sm fx-btn--ghost', type: 'button', onclick: () => skipRule(p) }, 'Skip') : null,
+      h('a', { class: 'fx-btn fx-btn--sm',
+        href: `/invoicing-settings/invoices?rule=${encodeURIComponent(p.rule)}`,
+        onclick: (event) => go(event),
+      }, `Review ${p.short ?? 'rule'}`),
+    ].filter(Boolean));
   // Non-change holds use the Jobs workflow's existing instructions, not a
   // comparison that does not exist. Reading them never releases the hold.
   const holdSteps = fixes({ view: 'review_required', holdState: 'review',
@@ -1330,6 +1375,8 @@ function draftView(invoice, ui, context, redraw) {
     draftNote(to, invoice) ? ui.notice(draftNote(to, invoice), 'warn') : null,
     nonChargeable ? ui.notice(brief(invoice.nonChargeable?.[0]?.message ?? 'Non-chargeable.')) : null,
     ...problems,
+    sourceGapNotice(ui, invoice),
+    exceptionsNotice(ui, invoice),
     h('div', { class: 'fx-invoice__grid' },
       h('div', { class: 'fx-invoice__main' },
         h('section', { class: 'fx-card fx-invoice__head' },
@@ -1491,7 +1538,26 @@ function issuedView(invoice, ui, context, redraw) {
     target: '_blank',
     rel: 'noopener',
   }, 'Open in Xero') : null;
-  const problemRow = problemNotice ? (openXero ? h('div', { class: 'fx-offer' }, problemNotice, openXero) : problemNotice) : null;
+  // Send stopped it for a Xero invoice of the same client and Reference: that
+  // Xero invoice is the bill. One press voids this copy and gives the job the
+  // Xero invoice (POST /api/xero/invoices/:id/use-xero), never a bare void.
+  const useXero = matched?.code === 'xero_same_reference_different_amount' && invoice.status === 'issued' && context.canIssue && organisationId
+    ? h('button', {
+      class: 'fx-btn fx-btn--sm', type: 'button',
+      onclick: async (event) => {
+        event.currentTarget.disabled = true;
+        try {
+          const body = await ui.flow(`/api/xero/invoices/${invoice.id}/use-xero`, { method: 'POST', body: JSON.stringify({ organisationId, xeroInvoiceId: matched.xero.invoiceId }) });
+          ui.toast(`${invoice.number} is void. The job has ${matched.xero.number ?? 'the Xero invoice'}.`, 'success');
+          ui.go(`/invoices/${body.invoice.id}`);
+        } catch (error) {
+          event.currentTarget.disabled = false;
+          ui.toast(error.message, 'danger');
+        }
+      },
+    }, 'Use Xero invoice') : null;
+  const offers = [useXero, openXero].filter(Boolean);
+  const problemRow = problemNotice ? (offers.length ? h('div', { class: 'fx-offer' }, problemNotice, ...offers) : problemNotice) : null;
   const header = h('header', { class: 'fx-ph' },
     h('div', { class: 'fx-ph__text' },
       h('h1', { class: 'fx-title' }, invoice.number),
@@ -1519,6 +1585,8 @@ function issuedView(invoice, ui, context, redraw) {
     chrome.pager,
     header,
     problemRow,
+    sourceGapNotice(ui, invoice),
+    exceptionsNotice(ui, invoice),
     h('div', { class: 'fx-invoice__grid' },
       h('div', { class: 'fx-invoice__main' },
         h('section', { class: 'fx-card fx-doc' },

package/server/ui/jobs.js

@@ -12,6 +12,7 @@
 // shows what to do there and the card waits in its new lane. On a phone a
 // long press opens Move to. With a keyboard, the job's panel has the same moves.
 
+import { alertStrip } from '/assets/ui/alerts.js';
 import { bulkBar } from '/assets/ui/bulk-bar.js';
 import { captureButton } from '/assets/ui/captures.js';
 import { columnTable, dateCell, fieldColumn, groupHead, personCell, rowCells, viewSaver } from '/assets/ui/columns.js';
@@ -128,7 +129,10 @@ export async function renderJobs(main, ui) {
   const frame = listFrame(main, host);
   // A form photo from the Jobs page; Capture lists it with its result.
   const shoot = captureButton(ui, { icon: true, added: () => ui.toast('Sent to Capture.', 'success') });
-  main.append(...listHead('Jobs', { views: views.element, controls, end: [find.element, toggle, ...shoot.nodes] }).nodes, frame.element, bulk.element);
+  // Finished jobs that nothing is billing (server/core/alerts.js).
+  const alerts = alertStrip(ui, 'jobs');
+  const [title, ...top] = listHead('Jobs', { views: views.element, controls, end: [find.element, toggle, ...shoot.nodes] }).nodes;
+  main.append(title, alerts.element, ...top, frame.element, bulk.element);
 
   const drawToggle = () => toggle.replaceChildren(...[['board', 'Board'], ['list', 'List']].map(([id, label]) => h('button', {
     type: 'button', role: 'radio', class: 'fx-seg__item', 'aria-checked': String(state.view.layout === id),
@@ -336,6 +340,9 @@ export async function renderJobs(main, ui) {
       state.systemFields = fields?.systemFields ?? [];
       state.people = fields?.people ?? [];
       state.values = new Map((values?.values ?? []).map((v) => [valueKey(v, v.fieldId), { value: v.value, updatedAt: v.updatedAt }]));
+      // The strip loads itself once; a later load follows a change.
+      if (state.loaded) alerts.refresh();
+      state.loaded = true;
     } catch (error) {
       host.replaceChildren(notice(error.message, 'danger'));
       return;
@@ -378,7 +385,12 @@ export async function renderJobs(main, ui) {
       h('span', { class: 'fx-job__space' }),
       problemMark(job),
       h('span', { class: 'fx-job__amount' }, job.totalCents == null ? '—' : formatCents(job.totalCents))),
-    job.pendingMove ? h('span', { class: 'fx-job__wait', title: `Set the status to ${job.pendingMove.to} in ${system}. Flow then reads the change.` }, `Waiting for ${system}`) : null);
+    job.pendingMove ? h('span', { class: 'fx-job__wait', title: `Set the status to ${job.pendingMove.to} in ${system}. Flow then reads the change.` }, `Waiting for ${system}`) : null,
+    // A rule asks for an item the job lacks in the work system (job-board.js).
+    // Fix it there: the lab prints from it too.
+    ...(job.obligation?.sourceNeeds ?? []).map((need) => h('span', {
+      class: 'fx-job__wait fx-job__wait--warn', title: `${need.note} Add it in ${system}.`,
+    }, `${system} needs ${need.item}`)));
     cardJobs.set(card, job);
     return card;
   }

package/skills/flow/SKILL.md

@@ -54,11 +54,21 @@ for sends, voids and deletes get the person's yes in the chat.
 | Add a rule | `flow.sh post invoicing/rules '{"name":"...","conditions":[{"field":"job_total","test":"at_most","value":0}],"action":{"kind":"wait"}}'` |
 | Change or turn off a rule | `flow.sh put invoicing/rules/<id> '{"enabled":false}'` |
 | Delete a rule | `flow.sh delete invoicing/rules/<id>` |
+| Rule that offers an item (shipping) | `flow.sh post invoicing/rules '{"name":"Shipping","conditions":[{"field":"line_item","test":"has_not","value":"S/H"}],"action":{"kind":"pending","note":"Add shipping, or skip with a reason.","addItem":"S/H"}}'` |
+| Add the rule's item to a draft | `flow.sh post invoicing/invoices/<id>/rules/<ruleId>/add-item '{}'` |
+| Skip a rule for one job | on its draft: `flow.sh post invoicing/invoices/<id>/rules/<ruleId>/exception '{"reason":"..."}'`; no draft yet: `flow.sh post invoicing/jobs/<jobId>/rules/<ruleId>/exception '{"reason":"..."}'` |
+| Jobs the work system must fix | `flow.sh get 'invoicing/jobs?limit=200'`: each job's `sourceNeeds` lists the items a rule wants that the work system's job lacks |
+| A rule's exceptions | `flow.sh get invoicing/rules/<id>/exceptions`; take one back: `flow.sh delete invoicing/rules/<id>/exceptions/<exceptionId>` |
 | Automations | `flow.sh get invoicing/automations` |
 | Flow settings | `flow.sh get invoicing/settings` |
 
-Rule actions: `wait` (hold the job) or `skip` (never invoice it). Take field,
-test and value only from `rule-fields`.
+Rule actions: `wait` (hold the job), `skip` (never invoice it), `pending`
+(draft it, but hold it on Pending with a note) or `non_chargeable`. Take
+field, test and value only from `rule-fields`. A pending rule with `addItem`
+offers that item. Add it or skip it only when the person says so, and give
+the person's reason for a skip. An exception ends when the job's lines change
+(`current: false` in the rule's exceptions list): ask the person again. The work system must get the item too: tell
+the person which jobs show "needs <item>" on the job board.
 
 Voids: the Void tab holds invoices voided in Flow **or voided or deleted in
 Xero**. Before a clean-up, list the tab, group the rows (Flow void, Xero void,
@@ -68,6 +78,34 @@ confirm.
 Sending: Flow sends each invoice to Xero as a draft unless the "Approve and
 email" setting is on (`invoicing/settings`). Say which one applies before a send.
 
+## Share links
+
+When you name an invoice, a job or a contact to a person, give its Flow link.
+Never search GitHub or guess a path: `flow.sh link` prints the address.
+
+| Link to | Command | Id to use |
+| --- | --- | --- |
+| An invoice | `flow.sh link invoice <id>` | the invoice's `id`, or a job's `invoiceId`. Never the invoice number |
+| A job's Reconcile page | `flow.sh link reconcile <id>` | a job's `id` from `invoicing/jobs` only (never an invoice id) |
+| A job on the Jobs board | `flow.sh link job <case number>` | the job's `caseRef`; if it is empty, its `sourceJobRef` |
+| A contact | `flow.sh link contact <id>` | the contact's `id` |
+
+For a job that has an `invoiceId`, give the invoice link: it opens that one
+record. The Jobs link is a search, so it can also show other jobs whose text
+holds the same number. Use it only for a job with no invoice.
+
+Paste the command's output as a Markdown link with a short label, one per line.
+For example, the commands print addresses like these:
+
+```
+- [INV-0123](https://flow.example.com/invoices/3f6c2a1e-8b4d-4c2f-9a7e-1d2b3c4d5e6f)  $242.00, Pending: add shipping
+- [Case 3716](https://flow.example.com/jobs?q=3716)  shipped, no invoice yet
+```
+
+Never type or change an address yourself. If `flow.sh link` says the id is not
+a UUID, read the record first (`flow.sh get 'invoicing/invoices?q=<number>'`)
+and use its `id`.
+
 ## Prices and price codes
 
 Flow's price list is the lab's own list of codes and prices
@@ -141,6 +179,32 @@ turned on "Hide patient details", patient, note, file and clinical fields are
 left out. Do not copy patient names outside this chat. 429: wait a
 minute and try once more.
 
+## Fix a problem Flow shows
+
+Flow's message is a flag, not the answer. Flow keeps three systems in line:
+Seazona (the jobs), Flow (its invoices) and Xero (the invoices and payments).
+No one system is always right. Find out what is true, then fix the wrong one.
+
+1. Read all three, through Flow:
+   - Flow: `flow.sh get invoicing/invoices/<id>` and
+     `flow.sh get invoicing/jobs/<job id>/reconcile`.
+   - Seazona: `flow.sh get seazona/api/orders/<order id>` (the job's
+     `sourceJobRef`, also its case number). Its invoice number is the job's
+     `sourceInvoiceRef`.
+   - Xero: `flow.sh post xero/invoices/status '{"organisationId":"<org>","invoiceIds":["<Flow invoice id>"]}'`.
+2. If they do not explain it, look deeper in the related records: history
+   import batches, older Seazona invoices, earlier Xero invoices for the same
+   client and reference, voids and credit notes. The cause is often one step
+   away from the job.
+3. Say what is true and show the evidence. If the evidence does not decide it,
+   ask the person. A field in one system can be wrong while the invoice is
+   right (for example a Seazona subtotal of 0 with a total that matches the
+   lines): say so, and do not change Flow to hide it.
+4. Fix the wrong system. Flow cannot write to Seazona: give the person the
+   exact fix and its link. Then read all three again to show they agree.
+
+Ask the person before any send, void or tax change.
+
 ## Reconcile: Seazona jobs, Flow invoices, Xero
 
 When the person says "reconcile", "tidy up" or "why is this job not
@@ -162,6 +226,11 @@ short groups, then act on the group they confirm.
      draft by itself. It refuses a live Flow invoice: void that first, only
      after the person says yes to that invoice
      (`flow.sh post invoicing/invoices/<id>/void`).
+   - **Xero already bills the job** (Send stopped it: "same client and
+     reference", or its Flow copy was voided for that): after the person says
+     yes, `flow.sh post xero/invoices/<Flow invoice id>/use-xero '{"organisationId":"<org>","xeroInvoiceId":"<Xero InvoiceID>"}'`.
+     Flow voids its copy (if not void yet), makes its Flow invoice from the
+     Xero one and gives it to the job. Same client only; one job per copy.
    - **Held or in review:** `flow.sh get invoicing/jobs/<job id>/activity`
      shows why. Release it: `flow.sh post invoicing/jobs/<job id>/hold '{"state":"none","reason":"<why>"}'`;
      hold it: `'{"state":"held","reason":"<why>"}'` (or `"review"`).