WFDASH-WEBAPP/docs/order-assistant.md

AI order assistant runbook

Design: docs/superpowers/specs/2026-10-24-ai-order-assistant-design.md. Plan: docs/superpowers/plans/2026-10-24-ai-order-assistant.md.

What it does

An order that came from a quote should point at that quote. Today only an order created from a quote carries the link; every other order — a walk-in, an email intake, a counter sale — has to be linked by hand.

The order assistant works out which quote an order came from. On a schedule it looks at orders that have no quote yet, asks the AI which of the candidate quotes the order came from, and then either:

• links the order to the quote itself (when it is sure), or
• suggests the quote, and a person accepts it.

Once the order points at a quote, the assistant can also fill the order's lines from that quote — the cost, the supplier, the SKU and the part number — leaving them in purple until a person checks them.

The AI never changes a line's status, never creates a purchase order and never sends anything. It decides which quote an order belongs to, and it may pre-fill a line's prices from that quote.

The auto-link rule, in plain words

The assistant links an order to a quote only when all of these are true:

• The "Auto-link when sure" setting is on (it is on by default).
• The AI says it is sure about the match.
• Every real order line is paired to a quote line, and each of those pairs is a sure match.
• Every pair points at a line of the one chosen quote (not a mixture of two quotes).
• The chosen quote belongs to the same company as the order.

If any of those fail, the assistant only writes a suggestion. The order page then shows "AI suggests Q…" with the reason, the doubts and the line-by-line pairing, and the existing Link button is there to accept it.

The assistant also refuses to link when PocketBase says no — for example when a line on the order has already moved past pending, or when another order already points at that quote. A refusal is not an error: the assistant falls back to a suggestion.

Filling the lines from the quote

With "Fill lines from the quote" on, the assistant prices the order's lines from the quote they are paired with. This is a copy, not a new price: no AI call is involved, the pairing is already on the lines.

A line may be filled only when all of these are true:

• It is still pending.
• It carries no cost of its own (cost_price is 0).
• Its pricing_source is not manual and not quote — a price a person set is never overwritten.
• It has no reviewed AI fill on it.
• It is paired to a quote line (quote_item is set) that actually has a cost.

What the fill writes:

Field	Rule
cost_price	The quote line's cost
selling_price	Only when the order line has none of its own
supplier, sku, matched_price_list_id	Only when the order line has none of its own
markup + markup_percent	Written together, from cost and selling
pricing_source	ai_quote
ai_fill	The audit record of the fill (see below)

Every line is re-read immediately before it is written, so a cost a person typed in the meantime wins over the AI's.

If the customer's price and the quoted price both exist and differ by more than 5%, the fill records a doubt, e.g. customer price R16.64, quoted R18.20. Doubts show on the line's marker.

The purple review

A filled line is pending review while all three are true:

• ai_fill.status is filled,
• ai_fill.reviewed_at is empty, and
• pricing_source is still ai_quote.

While a line is pending it shows up purple on the order Process page, with the bot marker next to it. Hover or focus the marker to see the quote it was filled from, the cost, the selling price, the markup, the reason and any doubts.

The purple ends the moment somebody touches the line:

• Saving the line records the review on ai_fill (reviewed_at, reviewed_by, and whether the prices were accepted unchanged or changed). The pricing source stays ai_quote.
• The one-click "use this cost" copy writes pricing_source: "quote" — the operator chose the quote's cost themselves — so the AI's provenance ends too.
• A line whose price the operator types by hand becomes pricing_source: "manual".

The board badge

The Orders board shows an "AI x/y" badge on an order when the AI filled some of its lines: x is how many lines still need a review, y is how many the AI filled. The badge is hidden when nothing is pending.

order_items.ai_fill

Field	Meaning
status	filled, skipped or error
source	quote
quote_id, quote_number, quote_item_id	Where the numbers came from
cost_price, selling_price, markup	What was written
supplier_id, sku	What was written
reason	Why the line was paired with that quote line
doubts	Anything a person should check (e.g. the 5% price difference)
model, attempted_at	Which model, and when
reviewed_at, reviewed_by	Set when a person checked the line
accepted_unchanged	True when the person kept both prices
supplier_changed	True when the person changed the supplier

Going live (manual steps, in this order)

1. Migrate PocketBase. Run against the live PB: npm run pb:migrate:order-assistant (adds orders.ai_quote_match, order_items.ai_fill and the order_assistant_* fields on ai_settings). If the app is deployed before this, PocketBase drops the unknown fields silently and the assistant's result lands nowhere.
2. Publish the PB hook change. ai_quote_match and ai_fill were added to IGNORED_FIELDS in pocketbase/pb_hooks/audit_log_utils.js, so the AI's own writes do not flood the audit log. Publish it the same way the other hook changes are published (npm run pb:hooks:publish).
3. Deploy the app. Pushing to main does not auto-deploy; it is a manual deploy that takes 5 to 10 minutes.
4. Clean up the stale suggestions. The old rule-based matcher wrote soft suggestions that were not backed by a matching line (one quote was suggested to 16 different orders). Run the clean-up script against the live PB — dry run first:

   npx tsx scripts/2026-10-24-rematch-quote-suggestions.ts
   npx tsx scripts/2026-10-24-rematch-quote-suggestions.ts --apply
   

   The dry run only reads. Read its report before running it with --apply.
5. Activate the n8n clock (below).
6. Turn it on in Settings, AI: the global "AI enabled" switch must be on, then switch on "Order assistant enabled" in the Order assistant section and click Save. Defaults: every 10 minutes, auto-link on, fill lines on.

The tick does nothing until both switches are on, so steps 5 and 6 are safe in either order.

n8n workflow: "WFDASH Order assistant tick"

n8n only acts as a clock. The app decides whether a run is due (AI and the assistant on, and at least "Run every" minutes since the last run), so the setting in the app controls the real frequency.

Spec:

Node	Setting
Name	WFDASH Order assistant tick
Trigger	Schedule Trigger, every 5 minutes
Action	HTTP Request
Method / URL	POST https://wfdash.apphub.co.za/api/v1/orders/assistant/tick
Authentication	Generic Credential Type, Header Auth, the same credential the quote assistant tick workflow uses (an Authorization: Bearer <AGENT_API_KEY> header). Do not create a new secret.
Body	none
Settings tab	Retry On Fail: off; Timeout: 120000 ms (120 s)
Status	inactive until the app is deployed and migrated

Click-by-click:

1. n8n, Workflows, Create workflow. Name it WFDASH Order assistant tick.
2. Add node, Schedule Trigger. Trigger Interval: Minutes, Minutes Between Triggers: 5.
3. Add node, HTTP Request, connect it after the trigger.
   • Method: POST.
   • URL: https://wfdash.apphub.co.za/api/v1/orders/assistant/tick.
   • Authentication: Generic Credential Type, Generic Auth Type: Header Auth. Pick the credential used by the quote assistant tick workflow (open that workflow and read its HTTP Request node to see which one).
   • Options, Add option, Timeout: 120000.
   • Settings tab on the node: turn Retry On Fail off.
4. Save. Leave the workflow inactive until the steps above are done.
5. After deploy, click Execute workflow once. Expected response while the assistant is off: {"ran":false,"reason":"disabled"}. When on and not yet due: {"ran":false,"reason":"not_due"}. While an earlier run is still going: {"ran":false,"reason":"running"}. When it ran: {"ran":true,"summary":{...}}.
6. Toggle the workflow Active.

A 401 means the credential is wrong (it must send the app's AGENT_API_KEY as a Bearer token). A tick that takes long is normal when there is work. Each run is bounded: it matches at most 10 orders and fills at most 10 orders, and it stops starting new orders once 90 seconds have passed, so a run normally answers inside the 120 s timeout; leftovers carry to the next run.

An order the tick has nothing to do with does not use up that budget: the run looks through up to 200 unlinked orders to find 10 it can work on, and an order whose lines the fill could not write is skipped rather than counted.

Runs never overlap. A run stamps its start time before it does any work and writes its summary when it ends. While a start is newer than the last summary and less than 10 minutes old, other ticks answer {"ran":false,"reason":"running"}. If a run dies without writing its summary, the next tick after those 10 minutes takes over.

Running it by hand

• Order page — the "Match with AI" button on the quote match card runs the assistant for that one order and reloads the order. It also fills the lines when the order ends up linked.
• MCP tool — orders.assistant_match with {"orderId": "..."}.

Both force a run past the "already looked at these lines" rule.

Reading ai_quote_match

orders.ai_quote_match (JSON) is the record of what the assistant decided about an order. Read it in the PB admin.

Field	Meaning
status	matched (the order was linked), suggested, no_match or error
quote_id, quote_number	The quote the assistant chose
confidence	high, medium or low
reason, doubts	The AI's plain-language reasoning and anything to check
lines	The pairing: order line id → quote line id, with same_item (sure / likely / unsure)
auto_linked	True only when the assistant itself created the link
lines_hash	Fingerprint of the order lines the run looked at — the same lines are not looked at twice
model	The model that answered
run_at	When the run happened
error	Set when status is error

Settings (Settings → AI → Order assistant)

Setting	Default	Meaning
Order assistant enabled	off	The tick does nothing while this is off
Run every (minutes)	10	How often the tick may run
Auto-link when sure	on	May the assistant link the order itself?
Fill lines from the quote	on	May the assistant pre-fill the order's lines from the linked quote?
Prompt	empty	Overrides the built-in prompt when set

orders.ai_quote_match and order_items.ai_fill are in IGNORED_FIELDS of the audit hook, so the assistant's own writes do not flood the audit log.

Not in this phase

• The assistant does not price a line from scratch — it only copies the cost, supplier, SKU and part number from the quote line the order line is already paired with.
• It never creates a purchase order, never sends an email and never changes a line's status.
• There is no POS fallback: the assistant fills only from a quote.