@arcforgelabs/flow 2026.10.41 → 2026.10.43

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.41",
+  "version": "2026.10.43",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@arcforgelabs/flow",
-      "version": "2026.10.41",
+      "version": "2026.10.43",
       "license": "MIT",
       "dependencies": {
         "@clerk/backend": "3.25.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.41",
+  "version": "2026.10.43",
   "description": "Invoicing, bill entry and a financial dashboard for labs, with Seazona and Xero integrations.",
   "license": "MIT",
   "repository": {

package/server/api/invoicing.js

@@ -43,7 +43,8 @@ import {
 //   POST  /invoices/mark-ready        { invoiceIds }: a person checked these drafts; one with a problem stays
 //   POST  /invoices/mark-not-ready    { invoiceIds }: back to To check
 //   POST  /invoices/send-ready        owner or admin: issue every ready draft and queue it for the
-//                                     accounting system { issueDate, invoiceIds? (only these, each ready) }
+//                                     accounting system { issueDate, invoiceIds? (only these; one that fails
+//                                     a check now stays on Pending and counts as held) }
 //   POST  /invoices/send-again        owner or admin: queue failed sends again { invoiceIds? }
 //   GET   /invoices/:id               one invoice: lines, contact, job, issued versions, and where it sends
 //   GET   /invoices/:id/pdf?version=  the invoice as a PDF, drawn by Flow (server/core/invoice-pdf.js),
@@ -542,8 +543,10 @@ export function createInvoicingRouter({
     // the job at its source or adopt the change (ledger.js), as Move to
     // Ready and Send do.
     const { problems } = await invoiceView(db, organisationId, await getInvoice(db, organisationId, invoiceId));
-    const held = problems.find((p) => p.code === 'job_review');
-    if (held) throw new FlowError('not_ready', `${held.message} Nothing was approved.`);
+    // A lab's pending rule (invoice-rules.js) is a gate too: fix its cause
+    // or turn the rule off.
+    const held = problems.find((p) => p.code === 'job_review' || p.code === 'rule');
+    if (held) throw new FlowError('not_ready', `${held.message.replace(/\.?$/, '.')} Nothing was approved.`);
     const issued = await issueInvoice(db, organisationId, invoiceId, { issuedBy: `person:${req.person.id}`, issueDate });
     log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} issued invoice ${issued.number} (version ${issued.issuedVersion})`);
     res.json({ ok: true, invoice: await invoiceDetail(db, organisationId, invoiceId, accounting(), work()) });
@@ -773,7 +776,7 @@ export function createInvoicingRouter({
   // with their tests, and the values Flow already holds for each kind of menu.
   router.get('/rule-fields', ...signedIn, handle(log, async (req, res) => {
     const organisationId = await organisationOf(req);
-    const [statuses, customers, items] = await Promise.all([
+    const [statuses, customers, items, practitioners] = await Promise.all([
       workStatuses(db, organisationId),
       db.select({ value: contacts.id, label: contacts.name }).from(contacts)
         .where(and(eq(contacts.organisationId, organisationId), eq(contacts.kind, 'customer')))
@@ -781,13 +784,20 @@ export function createInvoicingRouter({
       db.select({ value: priceItems.code, label: priceItems.name }).from(priceItems)
         .where(and(eq(priceItems.organisationId, organisationId), isNull(priceItems.archivedAt)))
         .orderBy(asc(priceItems.code)).limit(1000),
+      // The practitioners on the jobs, as the work system wrote them, most used first.
+      db.select({ value: billingObligations.practitioner, n: sql`count(*)::int` }).from(billingObligations)
+        .where(and(eq(billingObligations.organisationId, organisationId), sql`coalesce(trim(${billingObligations.practitioner}), '') <> ''`))
+        .groupBy(billingObligations.practitioner).orderBy(sql`count(*) desc`, asc(billingObligations.practitioner)).limit(500),
     ]);
     res.json({
       ok: true,
-      fields: Object.entries(FIELDS).map(([key, f]) => ({ key, label: f.label, kind: f.kind, options: f.options ?? null, tests: TESTS[f.kind] })),
+      fields: Object.entries(FIELDS).map(([key, f]) => ({
+        key, label: f.label, kind: f.kind, options: f.options ?? null, tests: TESTS[f.kind], draftOnly: Boolean(f.draftOnly),
+      })),
       actions: ACTIONS,
       options: {
         statuses: statuses.map((s) => ({ value: s.value, label: s.label })),
+        practitioners: practitioners.map((p) => ({ value: p.value, label: `${p.value} (${p.n})` })),
         customers,
         items: [
           ...items.map((i) => ({ value: i.value, label: `${i.value} · ${i.label}` })),

package/server/core/invoice-rules.js

@@ -9,7 +9,10 @@ import { FlowError, notFound } from './errors.js';
 //   When  job_ready: the job is ready to invoice and has no invoice yet.
 //   If    every condition matches: a field of the job, its customer or its
 //         lines, a test, and a value.
-//   Then  wait: the job waits for a person; skip: rules never draft it.
+//   Then  wait: the job waits for a person; skip: rules never draft it;
+//         pending: Flow drafts it, and the draft is Pending with the rule's
+//         note, which says what to fix (for example a Reference with no
+//         real practitioner).
 //
 // The rules read only Flow's own records, so they work with or without an
 // accounting integration. The earlier fixed settings (old job limit, required
@@ -19,6 +22,7 @@ const MAX_RULES = 100;
 const MAX_CONDITIONS = 10;
 const invalid = (message) => new FlowError('invalid', message);
 
+const MAX_NOTE = 200;
 const day = (date) => new Date(`${String(date).slice(0, 10)}T00:00:00Z`);
 const norm = (value) => String(value ?? '').trim().replace(/\s+/g, ' ').toLowerCase();
 // A line's key: its price item code, else the label line mapping gave it (a
@@ -40,7 +44,9 @@ export const FIELDS = Object.freeze({
   job_age_days: { label: 'Job age (days)', kind: 'number', read: (j, { now }) => (j.jobDate ? Math.floor((now - day(j.jobDate)) / 86_400_000) : null) },
   job_total: { label: 'Job total', kind: 'money', read: (j) => (j.totalCents ?? 0) / 100 },
   job_status: { label: 'Job status', kind: 'choice', options: 'statuses', read: (j) => norm(j.sourceStatus) || null },
-  practitioner: { label: 'Practitioner', kind: 'text', read: (j, { customer }) => j.practitioner || customer.defaultPractitioner || null },
+  practitioner: { label: 'Practitioner', kind: 'text', options: 'practitioners', read: (j, { customer }) => j.practitioner || customer.defaultPractitioner || null },
+  // Only a draft has a Reference, so only a pending rule may read it.
+  reference: { label: 'Reference', kind: 'text', draftOnly: true, read: (j) => j.reference || null },
   customer: { label: 'Customer', kind: 'choice', options: 'customers', read: (j) => j.contactId },
   customer_billable: { label: 'Customer is billable', kind: 'boolean', read: (j, { customer }) => customer.billable !== false },
   line_item: { label: 'Line item', kind: 'items', options: 'items', read: (j) => (j.lines ?? []).flatMap((l) => [norm(l.itemCode), norm(l.label)].filter(Boolean)) },
@@ -51,13 +57,15 @@ export const TESTS = Object.freeze({
   number: ['more_than', 'at_most', 'is', 'is_not', 'is_empty'],
   money: ['more_than', 'at_most', 'is', 'is_not'],
   choice: ['is', 'is_not', 'is_one_of', 'is_empty'],
-  text: ['is', 'is_not', 'is_empty', 'is_not_empty'],
+  text: ['is', 'is_not', 'is_one_of', 'is_not_one_of', 'contains', 'does_not_contain', 'starts_with', 'does_not_start_with', 'has_number', 'one_word', 'is_empty', 'is_not_empty'],
   boolean: ['is'],
   items: ['has', 'has_not'],
   share: ['is', 'is_not'],
 });
 
-export const ACTIONS = Object.freeze(['wait', 'skip']);
+export const ACTIONS = Object.freeze(['wait', 'skip', 'pending']);
+// Tests that take no value.
+const NO_VALUE = new Set(['is_empty', 'is_not_empty', 'has_number', 'one_word']);
 
 function readCondition(raw, index) {
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw invalid(`condition ${index + 1} must be an object`);
@@ -65,13 +73,13 @@ function readCondition(raw, index) {
   if (!field) throw invalid(`condition ${index + 1}: unknown field ${raw.field}`);
   if (!TESTS[field.kind].includes(raw.test)) throw invalid(`condition ${index + 1}: ${field.label} takes ${TESTS[field.kind].join(', ')}`);
   const out = { field: raw.field, test: raw.test };
-  if (['is_empty', 'is_not_empty'].includes(raw.test)) return out;
+  if (NO_VALUE.has(raw.test)) return out;
   const { value } = raw;
   if (field.kind === 'boolean') {
     if (typeof value !== 'boolean') throw invalid(`condition ${index + 1}: the value must be true or false`);
   } else if (['number', 'money', 'share'].includes(field.kind)) {
     if (typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > 1e9) throw invalid(`condition ${index + 1}: the value must be a number`);
-  } else if (raw.test === 'is_one_of') {
+  } else if (['is_one_of', 'is_not_one_of'].includes(raw.test)) {
     if (!Array.isArray(value) || !value.length || value.length > 50 || value.some((v) => typeof v !== 'string' || !v.trim() || v.length > 200)) {
       throw invalid(`condition ${index + 1}: pick 1 to 50 values`);
     }
@@ -98,7 +106,17 @@ export function readRule(raw) {
     throw invalid(`the rule needs 1 to ${MAX_CONDITIONS} conditions`);
   }
   if (!ACTIONS.includes(raw.action?.kind)) throw invalid(`the action must be one of ${ACTIONS.join(', ')}`);
-  return { name, enabled, conditions: raw.conditions.map(readCondition), action: { kind: raw.action.kind } };
+  const conditions = raw.conditions.map(readCondition);
+  const action = { kind: raw.action.kind };
+  if (action.kind === 'pending') {
+    const note = typeof raw.action.note === 'string' ? raw.action.note.trim() : '';
+    if (!note || note.length > MAX_NOTE) throw invalid(`a pending rule needs a note of ${MAX_NOTE} characters at most: what a person must fix`);
+    action.note = note;
+  } else {
+    const early = conditions.find((c) => FIELDS[c.field].draftOnly);
+    if (early) throw invalid(`${FIELDS[early.field].label} is on the draft only: use Then "Pending, with a note"`);
+  }
+  return { name, enabled, conditions, action };
 }
 
 function matches(condition, job, context) {
@@ -107,6 +125,18 @@ function matches(condition, job, context) {
   const { test, value } = condition;
   if (test === 'is_empty') return have === null || have === '' || have === undefined;
   if (test === 'is_not_empty') return !(have === null || have === '' || have === undefined);
+  if (field.kind === 'text' && !['is', 'is_not', 'is_one_of'].includes(test)) {
+    // An empty text matches no test that reads its words; is_empty finds it.
+    const left = norm(have);
+    if (!left) return false;
+    if (test === 'is_not_one_of') return !value.some((v) => norm(v) === left);
+    if (test === 'has_number') return /\d/.test(left);
+    if (test === 'one_word') return !left.includes(' ');
+    if (test === 'contains') return left.includes(norm(value));
+    if (test === 'does_not_contain') return !left.includes(norm(value));
+    if (test === 'starts_with') return left.startsWith(norm(value));
+    if (test === 'does_not_start_with') return !left.startsWith(norm(value));
+  }
   switch (field.kind) {
     case 'items': {
       const found = have.includes(norm(value));
@@ -142,13 +172,24 @@ export function ruleReasons(rules, job, { customer = {}, now = new Date() } = {}
   const context = { customer, now };
   const reasons = [];
   for (const rule of rules) {
-    if (!rule.enabled || rule.trigger !== 'job_ready') continue;
+    if (!rule.enabled || rule.trigger !== 'job_ready' || rule.action.kind === 'pending') continue;
     if (!rule.conditions.every((c) => matches(c, job, context))) continue;
     reasons.push(rule.action.kind === 'skip' ? `rule "${rule.name}": not drafted by rule` : `rule "${rule.name}": waits for a person`);
   }
   return reasons;
 }
 
+// The notes of the enabled pending rules that match one draft, as problems:
+// they put the draft on Pending (sending.js). `job` is the draft's job with
+// `reference`, the draft's Reference. A pending rule never stops a draft.
+export function rulePending(rules, job, { customer = {}, now = new Date() } = {}) {
+  const context = { customer, now };
+  return rules
+    .filter((r) => r.enabled && r.trigger === 'job_ready' && r.action.kind === 'pending')
+    .filter((r) => r.conditions.every((c) => matches(c, job, context)))
+    .map((r) => ({ code: 'rule', message: r.action.note, short: r.name.slice(0, 40), rule: r.id ?? null }));
+}
+
 // The starter rules made from the earlier fixed settings.
 export function starterRules(settings) {
   const rules = [

package/server/core/sending.js

@@ -2,6 +2,8 @@ import { randomUUID } from 'node:crypto';
 import { and, asc, desc, eq, inArray, sql } from 'drizzle-orm';
 import { billingObligations, invoiceLines, invoices } from '../db/schema.js';
 import { FlowError } from './errors.js';
+import { listRules, rulePending } from './invoice-rules.js';
+import { customerBillingByContact, effectiveSettings, readInvoicingSettings } from './invoicing-rules.js';
 import { issueInvoice } from './invoices.js';
 import { CHANGED_REASON, diffJobLines, STATUS_BACK_REASON } from './ledger.js';
 import { soleOrganisation } from './pipeline.js';
@@ -14,7 +16,8 @@ import { deadHoldSince, deadSince, enqueueJob, runNextJob } from './queue.js';
 // a total above zero, and a price item (or, for a line such as a rush
 // charge, an account) on every line. When an accounting
 // system is connected, its own checks are added (for Xero: the customer
-// matches one Xero contact, every item is in Xero). A draft with a problem is
+// matches one Xero contact, every item is in Xero), and the lab's pending
+// rules (invoice-rules.js) add their notes. A draft with a problem is
 // Pending (the "problem" view). A draft without one is Ready.
 //
 // Send all ready issues every ready draft (each gets its number) and, when an
@@ -77,10 +80,25 @@ async function checkDrafts(db, organisationId, drafts, accounting) {
     const found = draftProblems(draft, linesOf.get(draft.id) ?? []);
     if (found.length) problems.set(draft.id, found);
   }
+  const jobs = await db.select({ obligation: billingObligations, reference: invoices.reference }).from(billingObligations)
+    .innerJoin(invoices, eq(invoices.id, billingObligations.invoiceId))
+    .where(and(eq(billingObligations.organisationId, organisationId), inArray(billingObligations.invoiceId, ids)));
+  // The lab's pending rules (invoice-rules.js): a draft from a job that
+  // matches one waits on Pending with the rule's note, such as a Reference
+  // with no real practitioner.
+  const rules = (await listRules(db, organisationId)).filter((r) => r.enabled && r.action.kind === 'pending');
+  if (rules.length && jobs.length) {
+    const settings = await readInvoicingSettings(db, organisationId);
+    const customers = await customerBillingByContact(db, organisationId, jobs.map((j) => j.obligation.contactId));
+    for (const { obligation, reference } of jobs) {
+      const customer = effectiveSettings(settings, customers.get(obligation.contactId));
+      const found = rulePending(rules, { ...obligation, reference }, { customer });
+      if (found.length) problems.set(obligation.invoiceId, [...(problems.get(obligation.invoiceId) ?? []), ...found]);
+    }
+  }
   // A draft whose job the ledger sent to review (the job changed after the
   // draft was made, or the work system deleted it) waits for a person.
-  const reviewed = await db.select().from(billingObligations)
-    .where(and(eq(billingObligations.organisationId, organisationId), inArray(billingObligations.invoiceId, ids), eq(billingObligations.holdState, 'review')));
+  const reviewed = jobs.map((j) => j.obligation).filter((o) => o.holdState === 'review');
   for (const obligation of reviewed) {
     const { invoiceId, holdReason: reason } = obligation;
     const found = problem('job_review', `The job needs a look before this invoice goes: ${reason ?? 'it was sent to review'}.`, reviewShort(obligation));
@@ -201,11 +219,21 @@ export async function sendAllReady(db, organisationId, { accounting = null, work
   let views = await invoiceViews(db, organisationId, { accounting });
   const accountingRead = views.ready.length ? await readAccountingFirst(db, organisationId, { accounting, now }) : { outcome: 'fresh' };
   if (accountingRead.changed) views = await invoiceViews(db, organisationId, { accounting });
+  // Every check runs again at the press, as a gate: a ticked draft that
+  // fails one now (someone edited it, its job changed, a rule matches) is not
+  // sent and stays on Pending with its problem. The rest go.
   let { ready } = views;
+  let held = 0;
   if (invoiceIds) {
     const wanted = new Set(invoiceIds);
     ready = ready.filter((id) => wanted.has(id));
-    if (ready.length !== wanted.size) throw new FlowError('not_ready', 'Only a ready invoice can be sent. Mark it ready first.');
+    held = wanted.size - ready.length;
+    if (!ready.length) {
+      const reason = invoiceIds.map((id) => views.problems.get(id)?.[0]?.message).find(Boolean);
+      throw new FlowError('not_ready', reason
+        ? `Not sent: ${reason.replace(/\.?$/, '.')} The invoice is on Pending.`
+        : 'Only a ready invoice can be sent. Mark it ready first.');
+    }
   }
   const { go, waiting } = accountingRead.outcome === 'waiting'
     ? { go: [], waiting: ready.slice(0, SEND_BATCH) }
@@ -229,7 +257,7 @@ export async function sendAllReady(db, organisationId, { accounting = null, work
     }
     issued += 1;
   }
-  return { issued, queued: accounting ? issued : 0, remaining: Math.max(0, ready.length - SEND_BATCH), waiting: waiting.length };
+  return { issued, queued: accounting ? issued : 0, remaining: Math.max(0, ready.length - SEND_BATCH), waiting: waiting.length, held };
 }
 
 // Send again: issued invoices that failed go back on the queue. With no ids,

package/server/integrations/sentry/index.js

@@ -42,6 +42,7 @@ export const SENTRY_SETUP = {
   fields: [
     { name: 'SENTRY_DSN', label: 'DSN', kind: 'url', help: 'From the Sentry project\'s Client Keys. Browsers see it, so it is not a secret.' },
     { name: 'SENTRY_ENVIRONMENT', label: 'Environment', help: 'How Sentry labels this installation, for example production. Empty: production, or workspace in a Replit workspace.' },
+    { name: 'SENTRY_CLIENT', label: 'Client', help: 'The name your support desk files this installation\'s reports under. Sent as the client tag. Empty: no client tag.' },
     { name: 'SENTRY_FEEDBACK', label: 'Report a problem button', kind: 'onoff', help: 'On: everyone signed in can send a report, with a screenshot, to this Sentry project.' },
     { name: 'SENTRY_TRACES_SAMPLE_RATE', label: 'Traces', help: 'The share of clicks, page loads and requests timed, from 0 (off) to 1 (all). Empty: 0.2.' },
   ],
@@ -60,7 +61,12 @@ export function readSentrySettings(env) {
   if (!/^\d*\.?\d+$/.test(rate || '0') || !(tracesSampleRate >= 0 && tracesSampleRate <= 1)) {
     throw new Error('SENTRY_TRACES_SAMPLE_RATE must be a number from 0 to 1, such as 0.2.');
   }
-  return { dsn, environment, feedback, tracesSampleRate };
+  const client = String(env.SENTRY_CLIENT ?? '').trim();
+  if (client.length > 60 || /[\r\n]/.test(client)) throw new Error('SENTRY_CLIENT must be one short line.');
+  // Every event says which product and, when set, which client it is from,
+  // so one support desk can serve many installations.
+  const tags = client ? { product: 'flow', client } : { product: 'flow' };
+  return { dsn, environment, feedback, tracesSampleRate, tags };
 }
 
 // No trace for the host's health check: it is not a person waiting.
@@ -92,6 +98,7 @@ export function createSentryAdapter({ sdk = SentryNode, env: hostEnv = process.e
         dsn: settings.dsn,
         environment: settings.environment,
         release: release ?? undefined,
+        initialScope: { tags: settings.tags },
         // Flow sends what it logs; no request bodies, cookies or IP addresses.
         sendDefaultPii: false,
         // A request the browser traced keeps the browser's choice, so a
@@ -132,6 +139,7 @@ export function createSentryAdapter({ sdk = SentryNode, env: hostEnv = process.e
           environment: settings.environment,
           release,
           feedback: settings.feedback,
+          tags: settings.tags,
           tracesSampleRate,
           script: tracesSampleRate > 0 ? SENTRY_BROWSER_TRACING : SENTRY_BROWSER,
         };

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', '/invoices', '/invoices/:id', '/reconcile', '/reconcile/:id', '/xero-import', '/people', '/integrations', '/integrations/:id', '/account', '/appearance', '/invoicing-settings', '/price-list', '/custom-fields'];
+export const APP_PATHS = ['/sign-in', '/jobs', '/invoices', '/invoices/:id', '/reconcile', '/reconcile/:id', '/xero-import', '/people', '/integrations', '/integrations/:id', '/account', '/appearance', '/invoicing-settings', '/invoicing-settings/:id', '/automations', '/price-list', '/custom-fields'];
 
 export function appPage({ defaultFamily }) {
   return renderPage({

package/server/ui/app.js

@@ -10,7 +10,7 @@ import { getAppearance, onAppearanceChange, setAppearance, loadFonts } from '/as
 import { flowClerkAppearance } from '/assets/ui/clerk-appearance.js';
 import { ACCENT_PRESETS, normalizeAccent, THEME_FAMILIES, tokensFor } from '/assets/theme/themes.js';
 import { renderInvoice, renderInvoiceList } from '/assets/ui/invoicing.js';
-import { automationSection } from '/assets/ui/automations.js';
+import { automationSection, renderAutomations } from '/assets/ui/automations.js';
 import { renderInvoicingSettings, sendModeSection } from '/assets/ui/invoicing-settings.js';
 import { renderPriceList } from '/assets/ui/price-list.js';
 import { renderPriceReconcile } from '/assets/ui/price-reconcile.js';
@@ -21,6 +21,7 @@ import { renderXeroImport } from '/assets/ui/xero-import.js';
 import { startMonitoring } from '/assets/ui/monitoring.js';
 import { openSearch } from '/assets/ui/search.js';
 import { alertStrip } from '/assets/ui/alerts.js';
+import { named, startTips } from '/assets/ui/tip.js';
 
 const $ = (id) => document.getElementById(id);
 
@@ -164,14 +165,28 @@ function holdButton(button, ms) {
 
 // ── Shared pieces ──────────────────────────────────────────────────────────
 
-function pageHeader(title, { subtitle, actions = [] } = {}) {
+// The page's name and nothing under it: the page shows what it is for.
+// `count` is a live number beside the name (2 to check); `help` is a docs
+// link, an icon with its name as a tip.
+function pageHeader(title, { count = null, help = null, actions = [] } = {}) {
   return h('header', { class: 'fx-ph' },
     h('div', { class: 'fx-ph__text' },
       h('h1', { class: 'fx-title' }, title),
-      subtitle ? h('p', { class: 'fx-ph__sub' }, subtitle) : null),
+      count != null ? h('span', { class: 'fx-ph__count' }, count) : null,
+      help ? helpLink(help) : null),
     actions.length ? h('div', { class: 'fx-ph__actions' }, actions) : null);
 }
 
+// A docs link as a small "?" icon whose tip names it (How sending works).
+function helpLink({ href, label }) {
+  return named(h('a', { class: 'fx-help', href, target: '_blank', rel: 'noopener' }, lucide(h, 'circle-help')), label);
+}
+
+// A settings section's heading, with its docs link beside it.
+function sectionTitle(text, help = null) {
+  return h('h2', { class: 'fx-set__title' }, text, help ? helpLink(help) : null);
+}
+
 function notice(text, tone = 'info', title = null) {
   return h('div', { class: 'fx-notice', 'data-tone': tone, role: tone === 'danger' ? 'alert' : 'status' },
     title ? h('strong', {}, title) : null,
@@ -235,7 +250,8 @@ const VIEWS = {
   jobs: { label: 'Jobs', icon: 'jobs', group: 'Work', render: (main) => renderJobs(main, ui()) },
   invoices: { label: 'Invoices', icon: 'invoices', group: 'Work', render: (main, id) => (id ? renderInvoice(main, ui(), id) : renderInvoiceList(main, ui())) },
   reconcile: { label: 'Reconcile', icon: 'reconcile', group: 'Work', render: (main, id) => renderReconcile(main, ui(), id) },
-  'invoicing-settings': { label: 'Invoice rules', icon: 'invoices', group: 'Settings', render: (main) => renderInvoicingSettings(main, ui()) },
+  'invoicing-settings': { label: 'Rules', icon: 'rules', group: 'Settings', render: (main, id) => renderInvoicingSettings(main, ui(), id) },
+  automations: { label: 'Automations', icon: 'bolt', group: 'Settings', render: (main) => renderAutomations(main, ui()) },
   'price-list': { label: 'Price list', icon: 'tag', group: 'Settings', render: (main, id) => (id === 'reconcile' ? renderPriceReconcile(main, ui()) : renderPriceList(main, ui())) },
   'custom-fields': { label: 'Custom fields', icon: 'fields', group: 'Settings', render: (main) => renderCustomFields(main, ui()) },
   people: { label: 'People', icon: 'people', group: 'Settings', ownerOnly: true, render: renderPeople },
@@ -252,6 +268,9 @@ const VIEWS = {
 const ICON_PATHS = {
   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"/>',
+  draft: '<path d="M14 3H6v18h5M14 3l4 4v3M14 3v4h4"/><path d="M13 21v-2.5l6-6 2.5 2.5-6 6z"/>',
+  bolt: '<path d="M13 3L5 13h6l-1 8 8-10h-6z"/>',
+  rules: '<path d="M3 6l2 2 4-4M3 16l2 2 4-4M13 6h8M13 12h8M13 18h8"/>',
   reconcile: '<path d="M4 8h13M13 4l4 4-4 4M20 16H7M11 12l-4 4 4 4"/>',
   people: '<circle cx="9" cy="8" r="3"/><path d="M3 20c0-3.5 2.7-6 6-6s6 2.5 6 6"/><path d="M16 5a3 3 0 010 6M21 20c0-3-1.6-5-4-5.7"/>',
   tag: '<path d="M3 12V4h8l10 10-8 8z"/><circle cx="7.5" cy="8.5" r="1.5"/>',
@@ -292,11 +311,11 @@ function drawMenu() {
   const label = NARROW.matches ? (open ? 'Close the menu' : 'Open the menu') : (folded ? 'Show the sidebar' : 'Hide the sidebar');
   toggle.setAttribute('aria-expanded', String(open));
   toggle.setAttribute('aria-label', label);
-  toggle.title = label;
+  toggle.dataset.tip = label;
   // Folded, a page's name shows when the pointer rests on its icon.
   for (const link of document.querySelectorAll('[data-nav]')) {
-    if (folded && !NARROW.matches) link.title = link.dataset.label;
-    else link.removeAttribute('title');
+    if (folded && !NARROW.matches) Object.assign(link.dataset, { tip: link.dataset.label, tipSide: 'right' });
+    else { delete link.dataset.tip; delete link.dataset.tipSide; }
   }
 }
 
@@ -403,7 +422,7 @@ function navigate(event) {
 // The shared pieces a view module (invoicing.js) builds with. Its `go`
 // takes a path, or a link's click event.
 const ui = () => ({
-  h, flow, toast, notice, pageHeader, dialog, me, holdButton,
+  h, flow, toast, notice, pageHeader, sectionTitle, dialog, me, holdButton, tileCard, crumbs,
   go: (target, options) => (typeof target === 'string' ? go(target, options) : navigate(target)),
 });
 
@@ -641,9 +660,9 @@ async function renderIntegrations(main) {
   const notices = h('div', { class: 'fx-fields' });
   const content = h('div', { class: 'fx-int-sections' }, h('div', { class: 'fx-skeleton' }));
   main.append(
-    h('header', { class: 'fx-ph' }, h('div', { class: 'fx-ph__text' }, h('h1', { class: 'fx-title' }, 'Integrations'))),
+    pageHeader('Integrations'),
     alertStrip(ui(), 'integrations').element,
-    h('div', { class: 'fx-int-bar' }, tabs, search),
+    h('div', { class: 'fx-int-bar' }, tabs, h('div', { class: 'fx-row' }, category, search)),
     notices, content);
   let body;
   try {
@@ -655,13 +674,14 @@ async function renderIntegrations(main) {
   const canChange = Boolean(me.ownerActions?.allowed);
   notices.replaceChildren(...[
     canChange ? null : notice('Changing integrations needs a verified owner sign-in: Google Workspace on the owner domain with no password, or a second factor.', 'warn', 'Read only.'),
-    body.secretsKey ? null : notice('Flow has no secrets key, so it cannot store a client secret. Ask whoever hosts Flow to set FLOW_SECRETS_KEY (64 hex characters), then restart Flow.', 'warn', 'No secrets key.'),
+    body.secretsKey ? null : notice('Flow cannot store a client secret. Set FLOW_SECRETS_KEY (64 hex characters), then restart Flow.', 'warn', 'No secrets key.'),
   ].filter(Boolean));
   const list = [...body.integrations].sort((a, b) => a.name.localeCompare(b.name));
   const connected = (i) => i.enabled;
 
   const draw = () => {
-    tabs.replaceChildren(...[['all', 'All integrations'], ['yours', 'Your integrations']].map(([id, label]) => h('button', {
+    category.hidden = state.tab !== 'all';
+    tabs.replaceChildren(...[['all', 'All'], ['yours', 'Connected']].map(([id, label]) => h('button', {
       type: 'button', role: 'tab', class: 'fx-seg__item', 'aria-selected': String(state.tab === id), 'aria-checked': String(state.tab === id),
       onclick: () => { state.tab = id; draw(); },
     }, label)));
@@ -672,7 +692,7 @@ async function renderIntegrations(main) {
       const yours = list.filter(connected).filter(matches);
       sections.push(h('section', { class: 'fx-int-section-list' },
         yours.length ? h('div', { class: 'fx-int-grid' }, yours.map(integrationTile))
-          : h('p', { class: 'fx-empty' }, q ? 'No integration matches.' : 'Nothing is connected yet. Pick one under All integrations.')));
+          : h('p', { class: 'fx-empty' }, q ? 'No integration matches.' : 'Nothing is connected yet. Pick one under All.')));
     } else {
       // Recommended: what is not connected yet, once the catalogue is long
       // enough that a short row helps (with a few, it would repeat the grid).
@@ -684,7 +704,7 @@ async function renderIntegrations(main) {
       }
       const all = list.filter(matches).filter((i) => state.category === 'all' || CATALOGUE[i.id]?.category === state.category);
       sections.push(h('section', { class: 'fx-int-section-list' },
-        h('div', { class: 'fx-int-heading-row' }, h('h2', { class: 'fx-int-heading' }, 'All integrations'), category),
+        recommended.length ? h('h2', { class: 'fx-int-heading' }, 'All') : null,
         all.length ? h('div', { class: 'fx-int-grid' }, all.map(integrationTile)) : h('p', { class: 'fx-empty' }, 'No integration matches.')));
     }
     content.replaceChildren(...sections);
@@ -695,17 +715,39 @@ async function renderIntegrations(main) {
 }
 
 function integrationTile(integration) {
-  const href = `/integrations/${integration.id}`;
   const entry = CATALOGUE[integration.id];
   const on = integration.enabled;
   const attention = ['failed', 'restart_needed'].includes(integration.state);
-  return h('a', { class: 'fx-int-card', href, onclick: navigate },
+  return tileCard({
+    href: `/integrations/${integration.id}`,
+    mark: integrationLogo(integration),
+    title: integration.name,
+    status: on ? { label: STATE_LABEL[integration.state] ?? integration.state, tone: STATE_TONE[integration.state] } : null,
+    blurb: entry?.blurb,
+    action: attention ? 'Fix' : on ? 'Manage' : '+ Connect',
+  });
+}
+
+// One card in a grid of choices (Integrations, Rules): its mark (a node, or
+// an ICON_PATHS name), the name, a status pill, two lines at most (only when
+// they help), and the action. The whole card is the link.
+function tileCard({ href, mark, title, status, blurb, action = 'Manage' }) {
+  const logo = typeof mark === 'string' ? h('span', { class: 'fx-logo fx-logo--icon', 'aria-hidden': 'true' }, icon(mark)) : mark;
+  return h('a', { class: `fx-int-card${blurb ? '' : ' fx-int-card--bare'}`, href, onclick: navigate },
     h('header', { class: 'fx-int-card__head' },
-      integrationLogo(integration),
-      h('h3', {}, integration.name),
-      on ? h('span', { class: 'fx-status', 'data-tone': STATE_TONE[integration.state] ?? 'mute' }, STATE_LABEL[integration.state] ?? integration.state) : null),
-    h('p', { class: 'fx-int-card__blurb' }, entry?.blurb ?? ''),
-    h('span', { class: 'fx-int-card__btn' }, attention ? 'Fix' : on ? 'Manage' : '+ Connect'));
+      logo,
+      h('h3', {}, title),
+      status ? h('span', { class: 'fx-status', 'data-tone': status.tone ?? 'mute' }, status.label) : null),
+    blurb ? h('p', { class: 'fx-int-card__blurb' }, blurb) : null,
+    h('span', { class: 'fx-int-card__btn' }, action));
+}
+
+// The trail above a page one level down: crumbs(['/integrations', 'Integrations'], 'Xero').
+function crumbs(...trail) {
+  const here = trail.pop();
+  return h('nav', { class: 'fx-crumbs', 'aria-label': 'Breadcrumb' },
+    ...trail.flatMap(([href, label]) => [h('a', { href, onclick: navigate }, label), h('span', { 'aria-hidden': 'true' }, '›')]),
+    h('span', {}, here));
 }
 
 // One integration's page (/integrations/<id>): its logo and maker, Connect
@@ -842,8 +884,7 @@ async function renderIntegration(main, id) {
         busy ? h('span', { class: 'fx-spinner fx-spinner--sm', 'aria-hidden': 'true' }) : null, busy ? 'Connecting' : 'Connect');
 
     host.replaceChildren(
-      h('nav', { class: 'fx-crumbs', 'aria-label': 'Breadcrumb' },
-        h('a', { href: '/integrations', onclick: navigate }, 'Integrations'), h('span', { 'aria-hidden': 'true' }, '›'), h('span', {}, current.name)),
+      crumbs(['/integrations', 'Integrations'], current.name),
       h('header', { class: 'fx-int-hero' },
         integrationLogo(current, 'xl'),
         h('div', { class: 'fx-int-hero__text' },
@@ -858,7 +899,7 @@ async function renderIntegration(main, id) {
         h('div', { class: 'fx-int-page__main' }, ...[
           alerts.element,
           !canChange ? notice('Changing integrations needs a verified owner sign-in: Google Workspace on the owner domain with no password, or a second factor.', 'warn', 'Read only.') : null,
-          !body.secretsKey ? notice('Flow has no secrets key, so it cannot store a client secret. Ask whoever hosts Flow to set FLOW_SECRETS_KEY (64 hex characters), then restart Flow.', 'warn', 'No secrets key.') : null,
+          !body.secretsKey ? notice('Flow cannot store a client secret. Set FLOW_SECRETS_KEY (64 hex characters), then restart Flow.', 'warn', 'No secrets key.') : null,
           current.state === 'failed' && current.error ? notice(current.error, 'danger', 'It could not start.') : null,
           current.id === 'xero' && current.state === 'ready' ? h('section', { class: 'fx-int-section' }, xeroConnection(body.organisations, canChange)) : null,
           current.id === 'seazona' ? h('section', { class: 'fx-int-section fx-card', style: { padding: '8px 20px 16px' } }, automationSection(ui(), 'seazona', 'Ready to invoice')) : null,
@@ -1103,7 +1144,7 @@ function renderAccount(main) {
 // in it at once.
 function renderAppearance(main) {
   main.append(
-    pageHeader('Appearance', { subtitle: 'Saved with your account, on every device.' }),
+    pageHeader('Appearance'),
     h('div', { class: 'fx-appearance', id: 'appearance' }));
   drawAppearance();
 }
@@ -1169,13 +1210,16 @@ function drawAppearance() {
     (p) => chooseAppearance({ accent: p.hex ? p.id : null }),
     (p) => p.hex
       ? h('button', { type: 'button', class: 'fx-swatch', title: p.label, 'aria-label': p.label, style: { background: p.hex } })
-      : h('button', { type: 'button', class: 'fx-swatch fx-swatch--default', title: `${active.label}'s own`, 'aria-label': `${active.label}'s own accent` },
-        h('span', { 'aria-hidden': 'true', style: { background: `linear-gradient(135deg, ${active.swatches[mode].primary} 50%, ${active.swatches[mode].accent} 50%)` } })));
+      // The design system's own accent, named "Default" on the swatch: a
+      // click puts it back.
+      : h('button', { type: 'button', class: 'fx-swatch fx-swatch--default', 'aria-label': `Default: ${active.label}'s own accent` },
+        h('span', { class: 'fx-swatch__dot', 'aria-hidden': 'true', style: { background: `linear-gradient(135deg, ${active.swatches[mode].primary} 50%, ${active.swatches[mode].accent} 50%)` } }),
+        'Default'));
   accents.classList.add('fx-swatches');
   const custom = h('label', { class: 'fx-swatch-custom' },
     h('input', { type: 'color', 'aria-label': 'Custom accent colour', value: customHex ?? '#0d4e5f', onchange: (event) => chooseAppearance({ accent: event.target.value }) }),
     'Custom');
-  const accentLabel = customHex ? `Custom ${customHex}` : presetIndex > 0 ? ACCENT_PRESETS[presetIndex].label : `${active.label}'s own`;
+  const accentLabel = customHex ? `Custom ${customHex}` : presetIndex > 0 ? ACCENT_PRESETS[presetIndex].label : `the default, ${active.label}'s own`;
 
   host.replaceChildren(h('div', { class: 'fx-settings' },
     settingRow({ label: 'Mode', hint: 'Auto follows this device.', control: modeGroup }),
@@ -1230,7 +1274,7 @@ function drawModeToggles() {
     button.innerHTML = dark ? SUN : MOON;
     if (!button.classList.contains('fx-btn--icon')) button.append(` ${dark ? 'Light' : 'Dark'}`);
     button.setAttribute('aria-label', label);
-    button.title = label;
+    button.dataset.tip = label;
   }
 }
 
@@ -1291,4 +1335,5 @@ async function start() {
   await renderShell();
 }
 
+startTips();
 start();

package/server/ui/automations.js

@@ -1,6 +1,6 @@
 // Automation rows (server/core/automations.js, /api/invoicing/automations).
 // Each automation shows where its trigger lives: the work system's ready rule
-// on that integration's page, the draft rule on Settings, Invoicing. One row
+// on that integration's page, the invoicing ones on Settings, Automations. One row
 // for each: its name, one short line, and its switch, plus a row for each of
 // its settings. A change saves at once. Everyone can read them; an owner or
 // admin changes them. The caller passes in app.js's shared pieces as `ui`.
@@ -86,11 +86,17 @@ export function automationSection(ui, place, title) {
   (async () => {
     try {
       const { automations } = await flow(`/api/invoicing/automations?place=${encodeURIComponent(place)}`);
-      section.replaceChildren(h('h2', { class: 'fx-set__title' }, title), ...automations.flatMap(rowsOf),
-        h('p', { class: 'fx-dim', style: { margin: '8px 0 0' } }, h('a', { href: DOCS, target: '_blank', rel: 'noopener' }, 'How automations work')));
+      section.replaceChildren(ui.sectionTitle(title, { href: DOCS, label: 'How automations work' }), ...automations.flatMap(rowsOf));
     } catch (error) {
       section.replaceChildren(h('h2', { class: 'fx-set__title' }, title), notice(error.message, 'danger'));
     }
   })();
   return section;
 }
+
+// Settings, Automations (/automations): the invoicing automations. A work
+// system's own automations stay on its integration page.
+export function renderAutomations(main, ui) {
+  const { h, pageHeader } = ui;
+  main.append(pageHeader('Automations'), h('div', { class: 'fx-card', style: { padding: '8px 20px 16px' } }, automationSection(ui, 'invoicing', 'Invoicing')));
+}