School-year rollover for every K-12 contract — capture last year's prices, recalculate with new costs, queue HITL approvals.
Workflows
Substrate-detected anomaly (margin, AR, ops) → triage → propose action → HITL queue.
AR aging buckets → propose dunning, calls, holds, and statements per customer.
Walk every assembly item: verify BOM components, costs, yield, and ingredient lineage.
Segmented mass email/SMS push — preview cohort, draft copy, throttle, log delivery.
New bid amendment lands in inbox → diff against prior version → propose spec/price updates.
Bid awarded → propagate to NS, alert PM/finance, kick off onboarding of any new accounts.
Cost change → recompute bid-line prices → propose updates to NS price levels.
Customer disputes an invoice line — gather evidence, propose credit memo or hold.
Inbound quote request — pull catalog, apply pricing cascade, draft HTML quote.
Operator-initiated draft quote — pick items, pricing tier, terms; HITL approve before send.
5 mailboxes → classify intent → route to the right workflow or shelve as FYI.
Audit item records for completeness (UOMs, costs, allergens, NS parity); push fixes back.
Walk each customer/brand — flag margin slips, propose price moves or vendor renegotiation.
Full lifecycle: spec sheet → BOM → ingredient mapping → NS item record → first PO.
Inbound new account → credit check → NS customer record → tier assignment → kickoff comms.
Vendor add → docs (COI, W9, spec sheets) → NS vendor record → initial cost capture.
Refresh every customer's eligibility against active bids — flag drift, propose corrections.
Trigger conditions (AR, credit, compliance) → propose hold → notify CSM + customer.
Bid line spec doesn't match what we can deliver — note deviation, submit price anyway.
FIFO drawdown for USDA barrel cheddar lots — commit to a customer order, update inventory.
Vendor sends a cost change → diff items → propose downstream price/margin moves.
Workflow Graphs
Visual node-edge render of the SY rollover workflow.
Detect → triage → propose action visual.
AR buckets → dunning + holds visual.
First half of the assembly + BOM audit graph.
Second half of the assembly + BOM audit graph.
Segment → draft → throttle → log visual.
Inbox amendment → diff → propose updates.
Award → NS propagate + comms visual.
First half of the bid-price recompute graph.
Second half of the bid-price recompute graph.
Evidence → credit memo / hold visual.
Inbound quote → cascade → HTML quote visual.
First half of the draft-quote graph.
Second half of the draft-quote graph.
5 mailboxes → classify → route visual.
First half of the item-audit graph.
Second half of the item-audit graph.
Per-customer margin walk visual.
First half of the assembly-item lifecycle graph.
Second half of the assembly-item lifecycle graph.
Onboard → credit → NS visual.
Docs → NS vendor record → cost capture visual.
Quarterly eligibility drift visual.
Trigger → propose hold + comms visual.
Pack/format mismatch → submit + note visual.
FIFO commit + inventory move visual.
Cost diff → downstream price moves visual.
Substrate
executeWorkflowContract — the one entrypoint that runs every v2 contract end-to-end.
events + drainEvents — append-only CDC + subscriber drain across the platform.
proposed_actions state machine — every AI write parks here before NS push.
Leading-indicator scoring — AR, order cadence, sentiment, margin → risk score.
System
Post-R524 module map — index.ts split into 12 files, ~41K LOC across them.
Every entry point — email, chat, upload, webhook — routes through one workflow runner.
3,360 knowledge chunks + decision corpus — what AI remembers and how curation works.
3 models parallel + anonymized peer review + chairman synthesis. ~$0.007/query.
Driscoll's journey end-to-end — discovery → first PO → health scoring → growth.
The 4 gates between AI and NetSuite — preview, edit token, queue, drainer.
Where the money actually goes — every CF, AI, and NS dollar attributed.
From NetSuite to a chat answer — every hop, transform, and cache traced.
124+ products → template → PDF · 8 brand themes · D1 spec_items mirror.
Canonical bid example — NYC DOE B5875, intake → submission → award.
Every HITL-approved write lands in NS_PUSH_QUEUE → drainer reconciles to NetSuite.
50 chat tools · 10 roles · role-aware filtering decides which tools any session sees.
Work-order create → release → build → assemble → close · the NS shopfloor state path.
Assembly build mechanics inside NetSuite — BOM consume, finished-goods receipt, costing.
Pillars
AR, AP, GL, margin reporting, dunning, statements — finance pillar daily flow.
Spec sheets, allergens, USDA child-nutrition labels, K-12 menu validation.
Pricing cascade — vendor cost in, customer prices out · all 6 tiers traced.
B5875 + every K-12 + USDA bid · intake, eligibility, submission, award.
SO intake → pick/pack → ship → invoice · the order-to-cash backbone.
Customer + vendor contacts, segmentation, touchpoint cadence, sentiment.
281 NS reports · the analytical surface every other pillar leans on.
On-hand, lot tracking, location moves — absorbed into order-mgmt pillar.
Carriers, BOLs, freight, lanes — absorbed into order-mgmt pillar.
Assembly builds, BOM, yield, copack — overlaps the assembly-item workflow.
Brown-box, drawdown, dispensing — most of this is now the USDA drawdown workflow.
Pipelines
Email + upload + form → parse → enqueue → route. The front door for inbound work.
Frontend → council → tool calls → auto-context → answer. The full chat stack.
NS → D1 tiered sync · 2/5/60-min bands · 14+ tables live · 311K+ rows mirrored.
proposed_actions → admin review → ns_push_queue → drainer → NS. The write path.
SO → fulfillment → invoice → payment. The full order revenue cycle.
62 D1 tables · 13 migrations · ADRs 000-021 · July 1 anchor · observability live.
Master meta-diagram — vendor cost → bid price → quote price → invoice price.
R474+ coverage audit — find sync gaps, queue backfills, restore parity.
31 cron triggers in 11 bands — sync, drainers, audits, decay, rollups.
Cloudflare Workflow class powering the SY price-rollover lifecycle.
Canvases
One canvas, every box · the system at maximum altitude.
Layered cake of NS · D1 · Worker · Pages · AI · folder sources.
Workers · D1 · R2 · KV · Queues · Workflows · DOs · Email · Browser · Pages · all in one frame.
Every SaaS we run, every internal service, every integration · the full vendor map.
Wiki
Wiki · AR aging action plan
Plain-English walkthrough of the AR collections workflow. Bucket thresholds, escalation ladder, dunning copy, hold criteria, and the comms record trail.
Wiki · Bid price update
Plain-English deep-dive on the canonical bid-price recompute workflow. Triggers, lanes, side effects, HITL gates, and edge cases all walked through.
Wiki · Customer quote
How an inbound quote request becomes an HTML quote. Pricing cascade hops, tier mapping, terms boilerplate, and approve-before-send invariants explained.
Wiki · Vendor cost update
Vendor sends a cost change · what changes downstream. Item map, blast radius, recompute order, and which prices auto-propose vs require fresh approval.
What is a workflow contract?
A v2 workflow is a typed JSON contract executed by the substrate runner. Inputs, lanes, tools, side effects, and HITL gates are all declared up front — no free-form prose, no surprises.
What's a lane?
Lanes are vertical swimlanes in each diagram. They map to the actor (Customer · AI · Admin · NS · Folder · D1) so you can see at a glance who does what at each step.
Risk score (0-5)
Workflow risk reflects blast radius if it fires unattended. 5 = touches school-year revenue. 2 = read-only triage. Every step routed to HITL queue if risk ≥ 3.
REAL vs STUB
REAL = wired end-to-end in src/index.ts with green tool calls. STUB = diagram first, code TBD. Mixed = some lanes live, some scaffolded.
What's a graph file?
Each workflow has a paired -graph.html — an archify node-edge render of the same contract for visual scanning. Big workflows split into part-1 / part-2.
HITL invariant
Every write to NetSuite passes 4 gates: preview, edit-token header, proposed_actions queue, ns_push_queue drainer. Zero AI writes bypass.