The canonical worked example. Vendor cost changes → recompute every bid line that uses that ingredient → propose new NS price levels.
Start here — if you’re new
Four guides · pinned for first-day reading
If you’ve never touched the platform before, read these four in order. They’re the floor — how the system records what happens, how you approve things, the canonical worked example, and how the AI flags at-risk accounts.
01 · The approval gate
How Mike approves things
Every AI-proposed write to NetSuite or business state parks in proposed_actions and waits for human approval. Read this first — it’s the standing rule.
02 · The canonical example
Bid price update, end to end
Cost change → recompute bid-line prices → propose updates to NS. The most-walked workflow on the platform — if you understand this one, you understand the pattern.
Open bid price update wiki03 · The system memory
How the system records what happens
Every meaningful state change appends to the event ledger. CDC for the platform: subscribers drain, audits replay, future me knows what past me did.
Open event ledger wiki04 · The AI in action
How the AI flags churn risk
AR slippage, order cadence drop, sentiment, margin erosion — rolled into a leading-indicator score. The first AI feature that earns trust by being right early.
Open customer health wikiWorkflows
All 22 v2 contracts · AI proposes, admin approves
Each workflow is a contract. AI plans the steps, gathers evidence, drafts an action; you approve. Every card links to the plain-English wiki and the flow diagram.
Every K-12 contract rolls at school-year boundary. Capture last year’s, recalc with new costs, queue HITL.
Substrate detects something off (margin, AR, ops) → triage → propose action → HITL queue.
AR aging buckets → propose dunning, calls, holds, statements per customer. Reads like a finance ops playbook.
Walk every assembly item: verify BOM components, costs, yield, ingredient lineage.
Segmented mass email/SMS push. Preview cohort, draft copy, throttle, log delivery.
New amendment lands in inbox → diff vs prior version → propose spec/price updates.
Bid awarded → propagate to NS, alert PM/finance, kick off onboarding for new accounts.
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.
Per-customer/brand margin walk. Flag 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 → 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.
Substrate
The runtime under every workflow
Workflows don’t live by themselves. The substrate is what makes them work: a runner, a ledger that records every state change, the knowledge corpus that gives the AI context, and the HITL lifecycle that gates every write.
Append-only CDC. Every meaningful state change writes an event; subscribers drain; audits replay.
AR slip + order cadence + sentiment + margin → leading-indicator risk score per customer.
3,360 chunks of docs, ADRs, runbooks, and historical decisions. The AI’s long-term memory.
executeWorkflowContract — the one entrypoint that runs every v2 contract end-to-end.
proposed_actions state machine. Every AI write parks here before NS push.
The end-to-end approval gate. Preview, confirm, push, log. The standing rule for every write.
Pricing
Cost-in, price-out · the pillar that touches everything
Pricing is the spine. Vendor costs come in, bid lines and customer quotes go out, margin gets reviewed monthly, and the school-year roll captures it all once a year.
Canonical example — ingredient cost moves, bid lines recompute, NS gets new price levels.
Cost change inbound → diff against current → cascade to downstream prices.
Inbound quote → catalog → pricing cascade → HTML quote draft.
Per-customer/brand walk. Flag slips, propose price moves or vendor renegotiation.
SY rollover — every K-12 contract, every July 1, with new ingredient costs locked in.
Bids
Inbound RFPs · amendments · awards · eligibility
The K-12 + USDA + NYC schools bid pipeline is where revenue starts. Amendment arrives, we diff and respond; award lands, we propagate; quarterly we refresh eligibility.
New amendment hits the inbox → diff vs prior → propose spec/price updates.
Award lands → NS propagation, PM/finance alert, new-account onboarding kickoff.
Every customer’s eligibility against active bids; flag drift, propose corrections.
Operator-initiated quote — pick items, terms, HITL approve before send.
Customer
Onboard · quote · dispute · health · hold
The customer lifecycle in five doors: bringing them on, quoting them, resolving disputes, watching for churn, and pulling the brake when AR or compliance demands it.
Inbound new account → credit check → NS record → tier assignment → kickoff comms.
Dispute lands → gather evidence → propose credit memo or hold.
Inbound quote → pricing cascade → HTML quote draft → HITL approve to send.
Leading-indicator scoring: AR, cadence, sentiment, margin → risk score per customer.
Trigger conditions → propose hold → notify CSM and customer.
NetSuite expansion
4 lifecycle areas · system of record meets system of action
NetSuite is the system of record. D1 mirrors it for read; we push back via NS_PUSH_QUEUE. These guides cover the four NS object lifecycles we’re standing up next: work orders, assembly builds, inventory reconciliation, sales orders.
Create → release → build → close. Where production gets requested and tracked.
BOM → build transaction → component consumption → finished-good inventory.
D1 mirror vs NS source-of-truth — drift detection, propose adjustments, push back.
Quote → SO → fulfillment → invoice → cash. The revenue path through NS.
Memory + AI
How the system learns · how the AI gets context
The AI isn’t one model — it’s the council, the knowledge corpus, the event ledger, and the patterns we’ve trained over time. These three explain how memory and AI fit together.
The short-term memory. Every state change is recorded so future me knows what past me did.
3,360 chunks of docs, ADRs, runbooks, decisions. The long-term memory the council retrieves from.
The diagram: how chat, council, eval set, and corpus feed each other. Cross-link to the flow gallery.
Security & HITL
The standing rules · every write goes through Mike
Three documents define the safety floor: the lifecycle of a proposed action, the standing approval rule, and the security invariant that no AI write reaches NS unattended.
Preview → confirm → push → log. The standing rule for every AI-proposed write.
The proposed_actions state machine, in detail: pending → approved → pushed → logged.
The diagram of the standing rule: no AI write reaches NS without admin approval. Cross-link to flow gallery.
Items, specs & assemblies
Master data · BOMs · spec sheets · USDA
The product side of the business: every item, every spec sheet, every assembly BOM. These guides cover audit, new-item onboarding, spec deviations during bidding, and the USDA barrel-cheddar lot drawdown.
Audit every item record for completeness (UOMs, costs, allergens, NS parity); push fixes back.
Walk every assembly: BOM components, costs, yield, ingredient lineage.
Spec sheet → BOM → ingredient mapping → NS item record → first PO.
Bid line spec doesn’t match what we can deliver — note deviation, submit price anyway.
Vendor add → COI + W9 + spec sheets → NS vendor record → initial cost capture.
FIFO drawdown for USDA barrel cheddar — commit to a customer order, update inventory.
Anomaly + triage
Detection · classification · routing
When the system spots something off — an anomaly in the substrate, an email that lands in an inbox, a batch of customers that need a heads-up — these are the workflows that triage and act.
Substrate-detected anomaly (margin, AR, ops) → triage → propose action → HITL queue.
5 mailboxes → classify intent → route to the right workflow or shelve as FYI.
Segmented mass email/SMS. Preview cohort, draft copy, throttle, log delivery.