@arcforgelabs/flow 2026.11.2 → 2026.11.3

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; }

package/server/ui/home.js

@@ -0,0 +1,120 @@
+// Home: the page a person lands on. One job first: send the invoices that
+// are ready. The big number is the Ready tab's count, and Send sends them
+// all with the same step as the Invoices page (POST /invoices/send-ready).
+// Beside it, at most three things that need a person most days: invoices
+// that need a look, jobs and invoices to match (Reconcile), and form photos
+// to check (Capture). Each opens its page. No calls of its own to other
+// systems: every number is its page's own.
+import { formatCents, localDate } from '/assets/ui/invoicing.js';
+import { sendModeNote } from '/assets/ui/invoice-notes.js';
+import { lucide } from '/assets/ui/custom-fields.js';
+
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+
+function greeting(person, now = new Date()) {
+  const hour = now.getHours();
+  const part = hour < 12 ? 'Good morning' : hour < 18 ? 'Good afternoon' : 'Good evening';
+  const first = String(person?.name ?? '').trim().split(/\s+/)[0];
+  return first ? `${part}, ${first}` : part;
+}
+
+export async function renderHome(main, ui) {
+  const { h, flow, toast, notice, pageHeader, dialog, go, me } = ui;
+  const host = h('div', { class: 'fx-home' });
+  main.append(pageHeader(greeting(me?.person)), host);
+  const tabQuery = (tab) => `/api/invoicing/invoices?${new URLSearchParams({ status: tab, limit: '1' })}`;
+
+  async function load() {
+    let context;
+    let body;
+    let pending;
+    let toMatch;
+    let forms;
+    try {
+      [context, body, pending, toMatch, forms] = await Promise.all([
+        flow('/api/invoicing/context'),
+        flow(tabQuery('ready')),
+        flow(tabQuery('pending')),
+        // The two below are extras: Home still shows without them.
+        flow('/api/invoicing/reconcile').catch(() => null),
+        flow('/api/captures').catch(() => null),
+      ]);
+    } catch (error) {
+      host.replaceChildren(notice(error.message, 'danger', 'Flow could not load your invoices.'));
+      return;
+    }
+    if (!host.isConnected) return;
+    draw(context, body, [
+      { href: '/invoices?tab=pending', icon: 'circle-alert', label: 'Need a look', tone: 'danger', count: pending.total, sum: pending.totalCents },
+      toMatch && { href: '/reconcile', icon: 'link', label: 'To match', tone: 'warn', count: (toMatch.jobs?.length ?? 0) + (toMatch.invoices?.length ?? 0) },
+      forms && { href: '/captures', icon: 'camera', label: 'Forms to check', tone: 'info', count: forms.captures.filter((c) => c.state === 'ready').length },
+    ].filter(Boolean));
+  }
+
+  function draw(context, body, items) {
+    const to = body.sendsTo;
+    const counts = body.counts ?? {};
+    const ready = counts.ready ?? 0;
+    const blocked = to && body.sendMode && (!body.sendMode.connected || !body.sendMode.writesAllowed);
+    const canSend = context.canIssue && !blocked;
+
+    const hero = ready
+      ? h('section', { class: 'fx-home__send', 'aria-labelledby': 'home-ready' },
+        h('p', { class: 'fx-home__count', id: 'home-ready' }, String(ready),
+          h('span', {}, ready === 1 ? 'invoice ready' : 'invoices ready')),
+        h('p', { class: 'fx-home__sum' }, formatCents(body.totalCents)),
+        h('button', {
+          class: 'fx-btn fx-btn--primary fx-home__btn', type: 'button', disabled: !canSend,
+          onclick: (event) => send(to, ready, body.sendMode, event.currentTarget),
+        }, lucide(h, 'send'), h('span', {}, 'Send')),
+        context.canIssue ? null : h('p', { class: 'fx-home__note' }, 'An owner or admin sends.'),
+        blocked ? h('p', { class: 'fx-home__note' }, sendModeNote(to, body.sendMode)) : null)
+      : h('section', { class: 'fx-home__send', 'data-done': '', 'aria-labelledby': 'home-ready' },
+        h('span', { class: 'fx-home__done', 'aria-hidden': 'true' }, lucide(h, 'check')),
+        h('p', { class: 'fx-home__count', id: 'home-ready' }, h('span', {}, 'All caught up')),
+        h('p', { class: 'fx-home__sum' }, 'Nothing waits to be sent.'));
+
+    const needs = h('section', { class: 'fx-home__needs', 'aria-labelledby': 'home-needs' },
+      h('h2', { class: 'fx-label', id: 'home-needs' }, 'Needs you'),
+      h('ul', {}, items.map((item) => h('li', {},
+        h('a', { href: item.href, onclick: open, 'data-tone': item.count ? item.tone : 'clear' },
+          h('span', { class: 'fx-home__dot', 'aria-hidden': 'true' }, lucide(h, item.count ? item.icon : 'check')),
+          h('span', { class: 'fx-home__what' }, item.label,
+            item.count && item.sum ? h('small', {}, formatCents(item.sum)) : null),
+          h('span', { class: 'fx-home__n' }, String(item.count)))))));
+
+    host.replaceChildren(hero, needs);
+  }
+
+  function open(event) {
+    if (event.metaKey || event.ctrlKey || event.shiftKey || event.button !== 0) return;
+    event.preventDefault();
+    go(event.currentTarget.getAttribute('href'));
+  }
+
+  async function send(to, ready, sendMode, button) {
+    const ok = await dialog({
+      title: `Send ${plural(ready, 'invoice', 'invoices')}?`,
+      body: h('p', {}, to ? sendModeNote(to, sendMode, 'each one') : 'Each one gets the next number and is locked.'),
+      confirm: 'Send',
+    });
+    if (!ok) return;
+    button.disabled = true;
+    button.lastChild.textContent = 'Sending';
+    try {
+      const res = await flow('/api/invoicing/invoices/send-ready', { method: 'POST', body: JSON.stringify({ issueDate: localDate() }) });
+      const notes = [
+        to ? `${res.issued} on the way to ${to}.` : `${res.issued} approved.`,
+        res.held ? `${res.held} need a look.` : '',
+        res.waiting ? `${res.waiting} could not be checked with the work system yet: press Send again.` : '',
+        res.remaining ? `${res.remaining} more are ready: press Send again.` : '',
+      ].filter(Boolean);
+      toast(notes.join(' '), res.held || res.waiting || res.remaining ? 'info' : 'success', { stay: Boolean(res.held || res.waiting) });
+    } catch (error) {
+      toast(error.message, 'danger', { stay: true });
+    }
+    await load();
+  }
+
+  await load();
+}

package/server/ui/invoicing.js

@@ -111,7 +111,7 @@ function toCents(text) {
 
 const fromCents = (cents) => (cents == null ? '' : (cents / 100).toFixed(2));
 
-function localDate(date = new Date()) {
+export function localDate(date = new Date()) {
   const pad = (n) => String(n).padStart(2, '0');
   return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
 }
@@ -146,6 +146,13 @@ function readFilters() {
 
 export async function renderInvoiceList(main, ui) {
   const { h, flow, listHead, listFrame, notice, go, toast } = ui;
+  // A link may name the tab (/invoices?tab=draft, from Home). It is kept as
+  // the open tab, and the address goes back to /invoices.
+  const linked = new URLSearchParams(globalThis.location?.search ?? '').get('tab');
+  if (linked) {
+    sessionStorage.setItem('flow_invoice_tab', linked);
+    history.replaceState(null, '', location.pathname);
+  }
   const saved = OLD_TAB[sessionStorage.getItem('flow_invoice_tab')] ?? sessionStorage.getItem('flow_invoice_tab');
   // Back from an invoice comes here with the tab, search and scroll it left.
   const back = readNav();

package/server/ui/job-board.js

@@ -81,7 +81,7 @@ const sentence = (text) => capital(String(text).trim().replace(/\.?$/, '.'));
 // wrong, what to do, and where to go to do it (`go`, see GO). A job's fix
 // speaks of Flow's own invoice only. How that invoice stands in an
 // accounting system is the invoice's business, on the invoice page.
-function reasonFix(reason) {
+function reasonFix(reason, o = {}) {
   const fix = (label, todo, go = null) => ({ label, text: sentence(reason), todo, go });
   if (reason === 'the accounting system was not checked') {
     return { label: 'Not checked yet', text: 'Flow did not check for an invoice for this job yet.', todo: 'Wait for the next check, a few minutes. If it stays, check Settings, Integrations.', go: 'integrations' };
@@ -111,7 +111,12 @@ function reasonFix(reason) {
   }
   if (/^invoice .* was (voided|deleted)$/.test(reason)) {
     const voided = /voided$/.test(reason);
-    return { label: `Invoice ${voided ? 'voided' : 'deleted'}`, text: `The invoice for this job was ${voided ? 'voided' : 'deleted'}.`, todo: 'Make a new invoice, or close the job.', go: 'invoice' };
+    const label = `Invoice ${voided ? 'voided' : 'deleted'}`;
+    const text = `The invoice for this job was ${voided ? 'voided' : 'deleted'}.`;
+    // No Flow invoice: the voided one is in the accounting system only, so
+    // the job's own buttons make its new invoice (jobs.js).
+    if (!o.invoiceId) return { label, text, todo: null, go: 'choose' };
+    return { label, text, todo: 'Make a new invoice, or close the job.', go: 'invoice' };
   }
   if (/^the accounting system reports /.test(reason)) {
     return { label: 'May be invoiced', text: 'Flow found an invoice that may be for this job.', todo: 'Check the invoice number on the job in the work system.', go: 'work' };
@@ -160,7 +165,7 @@ export const GO = ['invoice', 'work', 'price-list', 'rule', 'integrations', 'rev
 export function fixes(o) {
   if (invoiceStage(o) !== 'problem') return [];
   const found = [];
-  if (PROBLEM_VIEWS.includes(o.view)) found.push(...(o.reasons ?? []).map((r) => reasonFix(r)));
+  if (PROBLEM_VIEWS.includes(o.view)) found.push(...(o.reasons ?? []).map((r) => reasonFix(r, o)));
   found.push(...(o.waitingRules ?? []).map(ruleFix));
   if (o.invoiceStatus === 'void') {
     found.push({ label: 'Invoice void', text: 'The invoice for this job is void.', todo: 'Make a new invoice, or close the job.', go: 'invoice' });

package/server/ui/nav-pins.js

@@ -1,9 +1,10 @@
 // Which sidebar pages a person has pinned. Stored with the account in
 // people.views.nav (PUT /api/me/views/nav). No table of its own.
-// Jobs and Invoices stay pinned: a request that leaves them out is saved
+// Home, Jobs and Invoices stay pinned: a request that leaves them out is saved
 // with them put back. A page Flow does not know is dropped.
 
 export const NAV_PAGES = Object.freeze([
+  'home',
   'jobs',
   'captures',
   'invoices',
@@ -16,12 +17,13 @@ export const NAV_PAGES = Object.freeze([
   'integrations',
 ]);
 
-export const NAV_LOCKED = Object.freeze(['jobs', 'invoices']);
+export const NAV_LOCKED = Object.freeze(['home', 'jobs', 'invoices']);
 
-// Today's sidebar, before a person has chosen: daily work (Jobs, Capture,
+// Today's sidebar, before a person has chosen: Home, daily work (Jobs, Capture,
 // Invoices, Contacts, Reconcile), Price list and Rules. Automations, Custom fields
 // and Integrations start in More.
 export const NAV_DEFAULT = Object.freeze([
+  'home',
   'jobs',
   'captures',
   'invoices',

package/server/ui/reconcile.js

@@ -470,13 +470,15 @@ async function renderGap(main, ui, id) {
       };
     });
     results.replaceChildren(...[
-      job.open ? null : h('p', { class: 'fx-notice' }, 'This job has an invoice already.'),
+      job.open || job.unclear ? null : h('p', { class: 'fx-notice' }, 'This job has an invoice already.'),
       candidates.length ? compareView({ ours: jobFacts(job), oursTitle: 'This job', oursSub: system, candidates })
         : h('p', { class: 'fx-empty' }, q.trim() ? 'No Flow invoice matches the search.' : 'Flow found no invoice that may be for this job. Find one, or make it.'),
     ].flat().filter(Boolean));
     actions.replaceChildren(...[
       skip(),
-      canAct && job.open ? h('button', {
+      // An unclear job (a voided or deleted Xero link) is not open to a link,
+      // but Make invoice settles it.
+      canAct && (job.open || job.unclear) ? h('button', {
         class: `fx-btn${candidates.some((c) => c.best) ? '' : ' fx-btn--primary'}`, type: 'button',
         onclick: () => act(async () => {
           if (job.unclear) await flow(`/api/invoicing/jobs/${job.id}/no-invoice`, { method: 'POST', body: '{}' });

package/server/ui/routes.js

@@ -22,7 +22,7 @@ const themeDir = join(here, '..', 'theme');
 const logoDir = join(here, 'logos');
 const LOGO_FILES = new Set(['xero.svg', 'seazona.svg', 'sentry.svg']);
 const THEME_FILES = new Set(['themes.js', 'color-contrast.js', 'openclaw-palettes.js', 'font-families.js']);
-export const UI_FILES = new Set(['sync-status.js', 'flow.css', 'appearance.js', 'clerk-appearance.js', 'app.js', 'invoicing.js', 'invoice-notes.js', 'job-change.js', 'sidecar.js', 'invoicing-settings.js', 'automations.js', 'invoice-rules.js', 'line-mappings.js', 'price-list.js', 'price-match.js', 'price-reconcile.js', 'custom-fields.js', 'contacts.js', 'xero-contact.js', 'jobs.js', 'job-board.js', 'reconcile.js', 'xero-import.js', 'xero-usage.js', 'xero-usage-model.js', 'job-view.js', 'list-views.js', 'saved-views.js', 'monitoring.js', 'search.js', 'alerts.js', 'bulk-bar.js', 'view-bar.js', 'tip.js', 'kit.js', 'columns.js', 'mobile.js', 'person.js', 'captures.js', 'capture-fields.js', 'pager.js', 'nav-pins.js', 'flow-mark.svg']);
+export const UI_FILES = new Set(['sync-status.js', 'flow.css', 'appearance.js', 'clerk-appearance.js', 'app.js', 'invoicing.js', 'invoice-notes.js', 'job-change.js', 'sidecar.js', 'invoicing-settings.js', 'automations.js', 'invoice-rules.js', 'line-mappings.js', 'price-list.js', 'price-match.js', 'price-reconcile.js', 'custom-fields.js', 'contacts.js', 'xero-contact.js', 'jobs.js', 'home.js', 'job-board.js', 'reconcile.js', 'xero-import.js', 'xero-usage.js', 'xero-usage-model.js', 'job-view.js', 'list-views.js', 'saved-views.js', 'monitoring.js', 'search.js', 'alerts.js', 'bulk-bar.js', 'view-bar.js', 'tip.js', 'kit.js', 'columns.js', 'mobile.js', 'person.js', 'captures.js', 'capture-fields.js', 'pager.js', 'nav-pins.js', 'flow-mark.svg']);
 const iconDir = join(dirname(require.resolve('lucide-static/package.json')), 'icons');
 const ICON_FILE = /^[a-z0-9]+(?:-[a-z0-9]+)*\.svg$/;
 const MAX_AGE = '1h';

package/skills/flow/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: flow
+description: Run the lab's Flow app and read Seazona through it - invoice tabs, send ready invoices, void or delete drafts, invoice rules, jobs, reconcile Seazona jobs with Flow and Xero, compare prices across Flow, Xero and Seazona, link price codes, review items, the Seazona history import, and Seazona orders, invoices and clients.
+metadata: { "openclaw": { "requires": { "bins": ["curl", "openssl", "sha256sum"] } } }
+---
+
+# Flow
+
+Flow is the lab's invoicing app. It takes jobs from Seazona (the lab's case
+system) and sends invoices to Xero. Use `{baseDir}/flow.sh` for every call.
+It holds the Flow key; never print the key file or put the key in a message.
+
+Flow address: saved by `setup` next to the key (or `FLOW_URL`). There is no
+default: the key goes only to this lab's own Flow.
+Key file: `FLOW_AGENT_KEY_FILE` (default `~/.openclaw/credentials/flow-agent-key`).
+
+## First time only
+
+Run `{baseDir}/flow.sh setup https://<this lab's Flow>`. It saves the address,
+makes the key once and prints only `FLOW_AGENT_KEY_SHA256=<64 hex>`. That digest is safe to share: give it to the
+person who sets up Flow. Flow stores the digest, never the key. Run `setup`
+again any time to see the same digest. To change the key, delete the key file,
+run `setup`, and give the new digest to Flow.
+
+Then check: `{baseDir}/flow.sh get me` must answer `HTTP 200`.
+
+## Keep the skill current
+
+Run `{baseDir}/flow.sh update` after Flow gets a new release, and when a call
+answers 404 for a route this skill lists. It gets this skill from the Flow it
+talks to, so the skill always matches the release that Flow runs. It changes
+nothing if the answer is not a good skill. Install the skill from GitHub only
+the first time.
+
+## Calls
+
+Every answer ends with a line `HTTP <code>`. 401 or 403: the key is not set up
+in Flow, or the Flow person is turned off. Stop and tell the person.
+
+Read first. Before a change, read the record, say what you will change, and
+for sends, voids and deletes get the person's yes in the chat.
+
+| Do this | Command |
+| --- | --- |
+| Tabs and counts | `flow.sh get 'invoicing/invoices?status=ready&limit=50'` (status: pending, ready, draft, approved, sent, non_chargeable, void) |
+| Search invoices | `flow.sh get 'invoicing/invoices?q=<text>'` |
+| One invoice | `flow.sh get invoicing/invoices/<id>` |
+| Mark ready | `flow.sh post invoicing/invoices/mark-ready '{"invoiceIds":["<id>"]}'` |
+| Send all ready to Xero | `flow.sh post invoicing/invoices/send-ready '{}'` (or `'{"invoiceIds":["<id>"]}'`) |
+| Void an invoice | `flow.sh post invoicing/invoices/<id>/void` |
+| Delete a draft | `flow.sh delete invoicing/invoices/<id>` |
+| Jobs | `flow.sh get 'invoicing/jobs?limit=50'`, one job `invoicing/jobs/<id>/activity` |
+| Invoice rules | `flow.sh get invoicing/rules`; what a rule can use: `flow.sh get invoicing/rule-fields` |
+| 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>` |
+| 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`.
+
+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,
+deleted draft), show the person the groups, and act only on the group they
+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.
+
+## Prices and price codes
+
+Flow's price list is the lab's own list of codes and prices
+(`docs/PRICE_LIST.md`). Flow keeps a copy of the Xero items and the Seazona
+products and links each one to a Flow code. `price-list` reads only Flow's
+copies, so it costs no Xero or Seazona calls.
+
+| Do this | Command |
+| --- | --- |
+| Compare all prices | `flow.sh get invoicing/price-list` |
+| Flow codes only | `flow.sh get 'invoicing/price-items?q=<text>'` |
+| Change a Flow price | `flow.sh put invoicing/price-items/<id> '{"unitAmountCents":13500}'` (also `name`, `taxCode` GST or GST_FREE) |
+| Add a Flow code | `flow.sh post invoicing/price-items '{"code":"...","name":"...","unitAmountCents":13500,"taxCode":"GST"}'` |
+| Link records to codes | `flow.sh post invoicing/price-links '{"links":[{"priceItemId":"<id>","system":"xero","externalId":"<id>"}]}'` |
+| Remove a link | `flow.sh delete invoicing/price-links/<link id>` |
+| Accept a difference | `flow.sh post invoicing/price-items/<id>/resolve` |
+| Lines that wait for a code | `flow.sh get invoicing/line-labels` (rows with `unmapped` above 0) |
+| Give a line its code | `flow.sh post invoicing/line-mappings '{"kind":"saved","label":"<label>","unitAmountCents":<label price>,"itemCode":"<Flow code>"}'` |
+| Saved code choices | `flow.sh get invoicing/line-mappings`; change `put invoicing/line-mappings/<id>`, remove `delete invoicing/line-mappings/<id>` |
+
+How to read `price-list`:
+
+- `systems`: each connected list (`xero`, `seazona`), its record count and
+  `syncedAt`. An old `syncedAt` means Flow's copy can be behind.
+- `items`: each Flow code with its `links` (the linked Xero item or Seazona
+  product, as `record`) and `findings`. A finding `kind` is `price` (Flow and
+  the other system differ: `flow` and `other` in cents), `tax`, `missing` (the
+  linked record is gone) or `not_linked` (no Xero item for this code).
+- `unlinked`: Xero items and Seazona products that no Flow code has yet.
+
+Reconcile steps:
+
+1. Read `price-list` and `line-labels`. Show the person one table: each code
+   with the Flow, Xero and Seazona price, what differs, and each line label
+   that waits.
+2. For each difference, ask which price is right. Do not guess.
+3. When the person says yes, fix it in the right place:
+   - Flow price or code: the Flow commands above.
+   - Xero item: your own `xero` command (Flow never changes a Xero item).
+     Then refresh Flow's copy of Xero items and contacts:
+     `flow.sh post xero/sync '{"organisationId":"<org>"}'`.
+   - Seazona product: read only. Tell the person to change it in Seazona.
+   - A record that is the same thing as a code but has no link: link it.
+   - A difference that is correct (for example a Seazona product at $0):
+     accept it with `resolve`.
+4. Waiting lines: match each label to a code by name and price, show the
+   person the pairs, and save each pair they agree with as a line mapping.
+   The `label` and `unitAmountCents` come from that `line-labels` row. Jobs
+   with that line move on at the next Flow sync (a few minutes).
+5. Read `price-list` and `line-labels` again and show what is left.
+
+Every change on this list (price, code, link, resolve, line mapping) needs
+the person's yes in the chat first, like a send.
+
+## Seazona (read only)
+
+Flow reads Seazona for you with its own Seazona connection, so you need no
+Seazona password. Calls share Seazona's limit of 30 a minute with Flow's
+sync: make few calls, and never loop over many records.
+
+| Do this | Command |
+| --- | --- |
+| Orders on one day | `flow.sh get 'seazona/api/orders/?ordered=2026-11-11T00:00:00&page=1&pageSize=50'` |
+| One order | `flow.sh get seazona/api/orders/<order id>` |
+| Invoices changed since | `flow.sh get 'seazona/api/invoices/?lastModified=2026-11-01T00:00:00'` |
+| Clients changed since | `flow.sh get 'seazona/api/clients/?lastModified=2026-11-01T00:00:00'` |
+| Products, users | `flow.sh get seazona/api/products/`, `flow.sh get seazona/api/users/` |
+
+Answers are `{ "ok": true, "data": ... }`, as Seazona gives them. If the owner
+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.
+
+## Reconcile: Seazona jobs, Flow invoices, Xero
+
+When the person says "reconcile", "tidy up" or "why is this job not
+invoiced", work in this order. Read first, show the person what you found in
+short groups, then act on the group they confirm.
+
+1. **Jobs against Flow invoices.** `flow.sh get invoicing/reconcile` lists
+   jobs with no invoice and invoices with no job. For one row:
+   `flow.sh get invoicing/jobs/<job id>/reconcile` or
+   `flow.sh get invoicing/invoices/<id>/reconcile` (each lists the likely other
+   side; `best: true` is the top guess).
+   - Link a job to its invoice: `flow.sh post invoicing/jobs/<job id>/link '{"invoiceId":"<id>"}'`
+   - Job needs no invoice: `flow.sh post invoicing/jobs/<job id>/no-invoice`
+   - Make the invoice now: `flow.sh post invoicing/jobs/<job id>/draft`
+   - Read the job again from Seazona: `flow.sh post invoicing/jobs/<job id>/recheck`
+   - **Stuck on a void invoice** (the job shows "Invoice voided", or its Flow
+     invoice is void, and nothing drafts): `flow.sh post invoicing/jobs/<job id>/free '{"reason":"<why, in the person's words>"}'`.
+     The job lets go of the void invoice and goes on hold, so it does not
+     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`).
+   - **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"`).
+     A `history_import` hold is refused here: use the history import decisions.
+2. **Flow against Xero.** First get the lab id:
+   `flow.sh get invoicing/context` (`organisations[0].id`, below `<org>`).
+   - Refresh Flow's copy of Xero: `flow.sh post xero/mirror '{"organisationId":"<org>"}'`
+   - Xero invoices against Flow's: `flow.sh get 'xero/import?organisationId=<org>&show=check'`
+     (show: `check`, `linked`, `invoice_fits`, `job_fits`, `none`, `all`)
+   - Match them all again: `flow.sh post xero/import/match '{"organisationId":"<org>"}'`
+   - Link one Xero invoice to a Flow invoice: `flow.sh post xero/import/<xero invoice id>/link '{"organisationId":"<org>","invoiceId":"<id>"}'`
+   - Make the Flow invoice for one Xero invoice: `flow.sh post xero/import/<xero invoice id>/make '{"organisationId":"<org>","jobId":"<job id or null>"}'`
+   - Xero's state of some Flow invoices: `flow.sh post xero/invoices/status '{"organisationId":"<org>","invoiceIds":["<id>"]}'`
+   - Re-check one invoice after a fix in Xero: `flow.sh post xero/invoices/<id>/recheck '{"organisationId":"<org>"}'`
+   - Contacts: `flow.sh get 'xero/contacts/match?organisationId=<org>&contactId=<Flow contact id>'`; link to a Xero contact of another name: `flow.sh post xero/contacts/link '{"organisationId":"<org>","contactId":"<id>","xeroContactId":"<id>"}'`
+3. **Fix the cause with a rule.** If many jobs fail the same way, read
+   `invoicing/rule-fields`, propose one rule (`wait` or `skip`), and add it after
+   the person says yes. Line names that map to the wrong product:
+   `flow.sh get invoicing/line-mappings`, then change one with `put
+   invoicing/line-mappings/<id>`. Prices: `flow.sh get invoicing/price-list`.
+4. **Check Seazona itself** for one job with the Seazona read above (one order).
+
+Links, "no invoice", rules and mappings are Flow records only: say what you
+will change and do it after the person's yes. Mirror, match and recheck only
+read Xero. Sending to Xero still goes through `invoicing/invoices/send-ready`.
+
+## Review queue, health and history import
+
+Use these to find gaps in past billing: jobs Flow never saw, jobs held from
+the history import, and days where Seazona, Flow and Xero disagree.
+
+| Do this | Command |
+| --- | --- |
+| Flow health (build, Seazona sync, daily reconcile, history counts) | `flow.sh health` |
+| Open review items | `flow.sh get 'invoicing/review?limit=100'` (also `kind=`, `state=resolved`) |
+| History import state, backfill and batches | `flow.sh get seazona/history` |
+| One batch, or its rows that wait | `flow.sh get 'seazona/history/batches/<id>?outcome=needs_person'` |
+| Held history jobs that need a person | `flow.sh get 'seazona/history/ledger?state=needs_person'` (no state: all) |
+| Decide batch jobs | `flow.sh post seazona/history/batches/<id>/decisions '{"decisions":[{"jobKey":"<key>","decision":"import"}]}'` (`import`, `skip`, or `null` to undo) |
+| Apply a batch (once only) | `flow.sh post seazona/history/batches/<id>/apply` |
+| Read past Seazona days into Flow | `flow.sh post seazona/history/backfill '{"from":"2026-07-01"}'`; stop: `post seazona/history/backfill/stop` |
+| Let one held history job draft | `flow.sh post seazona/history/ledger/<job id>/release` |
+
+How to read them:
+
+- `health`: `integrations[].health.history` counts history jobs and open
+  batches; `reconcile` shows the last daily check, `daysDifferent` and
+  `openItems`; Seazona `missing` lists Seazona records Flow's copy lacks.
+- Review items: `kind` says what differs (for example `reconcile.day`,
+  `job.changed`, `job.source_totals`); `evidence` holds the numbers. An item
+  closes by itself when its cause is fixed, so fix the cause (link, mapping,
+  rule, recheck) and read the list again.
+- History jobs are held with reason `history_import`: they are past work,
+  most already billed. A matched one stays held. Release only a job that the
+  person agrees was never invoiced.
+
+Decisions, apply, backfill and release change Flow records or spend Seazona
+calls: say what you will do and act only after the person's yes. A backfill
+uses the shared Seazona limit a few calls at a time; one at a time only.
+
+## Xero
+
+Xero has its own `xero` command on this Gateway, for anything Flow does not
+cover. Flow's send and the reconcile steps above use Flow's own Xero
+connection, not yours.
+
+## Never
+
+- Never print, paste or send the key file, a Xero token or a callback URL.
+- Never send, void or delete without the person's yes in this chat.
+- Never send a turned-off person's work again without asking: a send stopped as
+  `requester_disabled` means a person turned the assistant off.
+- Never change Flow people, Integrations or owner settings: Flow refuses them.