Onboarding — Technical Mapping

The decision tree made buildable: data model, state machine, the swarm as services, event catalog, flows, routing logic, and the production rigor. Grounded in the real precon_web schema — this extends the app, it doesn't reinvent it.

Perch · CRO cockpit · Jun 25 2026 · real exists in code · extend add fields to real · new greenfield

Architecture — capture to close

Data model

TS-ish types. real already in precon_web · extend add columns to an existing table · new greenfield table.

Enums

State machine — OnboardingSession

Happy paths first, then the full transition table (incl. fallbacks/terminals). States map 1:1 to decision-tree gates.

Shared front-end

Self-serve tail ⚡

White-glove tail 🤝

Transition table

From	Event	Guard	To
S0 ENTRY	lead.captured	warmth==cold	S1 AWAIT_EMAIL
S0 ENTRY	lead.identified	warmth>=warm	S2 ENRICHING (prefetched)
S1 AWAIT_EMAIL	email.submitted	—	S2 ENRICHING
S2 ENRICHING	enrichment.complete	conf>=θ all gating fields	S3 CONFIRM
S2 ENRICHING	enrichment.partial	some fields low-conf	S3 CONFIRM (ask only those)
S2 ENRICHING	enrichment.failed	retries exhausted / killed	→ FALLBACK_FORM
S3 CONFIRM	onboarding.confirmed	warm & role known	S4 ROUTED (skip ask)
S3 CONFIRM	onboarding.role_captured	role was unknown	S4 ROUTED
S4 ROUTED	route.decided	track==self_serve	S5 VALUE
S4 ROUTED	route.decided	track==wg_*	W5 BATTLEPACK
S4 ROUTED	route.decided	orgType==consumer	→ DISQUALIFIED (route to HO product)
S5→S8	value.revealed · takeoff.completed	—	S9 TRIAL
S9 TRIAL	card.captured	post-wow trigger	S10 CLOSED_WON
S5..S9 (self-serve)	expansion.detected	seats/ACV cross threshold	→ W5 (hand to white-glove)
W7 DISCOVERY	meddpicc.qualified	champion+EB confirmed	W8 DEMO
W9 SEAT	deal.closed_won	contract signed	W10 CLOSED_WON
any active	session.timeout	no event > TTL	→ ABANDONED (re-engage queue)
FALLBACK_FORM	manual steps done	—	→ today's 6-step flow → activate

The swarm — six agents as services

Agent	Input	Output (signals)	Sources	Mode / budget
domain_site	email domain	company, website, HQ	web	sync ~1s
classifier	website text	orgType, trade, sectors, project mix	site, LLM	sync ~2s
size_estimator	company	sizeBand, revenueEst, acvEst	aggregators, bonding	sync ~2s
role_resolver	email, name	role, persona	signature, LinkedIn	sync ~2s
project_finder	company, trade, geo	pursuits[]	permits, public bids, news	async — can lag
network_seeder	company	network[] (subs/GCs)	CRM, bid invites (consent)	async — can lag

Orchestration: fan-out in parallel; the 4 sync agents gate S2→S3 (the confirm needs them), the 2 async agents can resolve after the user is already in the workspace (pipeline fills in live). Warm = all six run as async_prefetch before arrival, so none are on the critical path.

Event catalog

Event	Emitted when	Consumers
lead.captured / lead.identified	entry (cold / warm)	enrichment, session, analytics
enrichment.requested	email known (or pre-capture)	swarm orchestrator
enrichment.agent.completed	each agent returns	signal store, confidence gate
profile.field_resolved	a field crosses confidence θ	router (may recompute)
enrichment.complete / .partial / .failed	run terminal	session FSM, retry engine
onboarding.confirmed / .role_captured	user taps confirm	session, router
route.decided	router runs	session, surfaces, sales
value.revealed / next_question.asked / takeoff.completed	self-serve value loop	analytics, close trigger
team.invited	invite sent	spawns a new warm Lead per invitee
trial.started / card.captured / account.activated	self-serve close	billing, CRM
deal.battlepack_ready / outreach.sent / meeting.booked / demo.delivered / deal.closed_won	white-glove	AE tooling, CRM, MEDDPICC
session.abandoned / session.handed_off	timeout / expansion	re-engage, sales queue

Flows

Cold · self-serve (Squires, cold)

Warm · self-serve (Squires, warm)

White-glove (CVE)

Routing logic — the pure function

// Router: Profile -> RouteDecision. Pure, deterministic, re-runnable.
const θ = 0.85; // confidence threshold to assert vs ask

function route(p: Profile): RouteDecision {
  // G2 — type (homeowner exits the B2B funnel)
  if (p.orgType === "consumer") return disqualify("route_to_homeowner_product");

  // G3 — track by size, ACV wins ties (open Q). Thresholds differ GC vs sub.
  const band = sizeBand(p);              // GC: <10M | 10–500M | 500M+   sub: <10M | 10–100M | 100M+
  const track =
    band === "micro_small"      ? "self_serve"
    : band === "mid"             ? "wg_mid"
    :                              "wg_enterprise";
  if (disagree(p.revenueBand, p.acvBand)) prefer(p.acvBand); // ACV gate

  // G4 — persona -> surface; field roles leave chat entirely
  const persona = p.role ?? "ask";     // unknown -> the one allowed ask
  const surface = { estimator:"jobs", owner_exec:"analytics",
                    pm:"network", field:"field_ops" }[persona];

  // G5 — trade lander + Sarah recipe (subs only)
  const trade = p.orgType === "sub_contractor" ? tradeConfig(p.trade) : null;

  // G6/G7 — compose the question + pick the close
  return {
    track, persona, primarySurface: surface,
    nextQuestion: composeQuestion(persona, band, trade),
    closeMotion: track === "self_serve" ? "in_flow_card" : "ae_meddpicc",
    gateTrace: trace(),
  };
}

// The "smart" rule, applied everywhere we read a field:
const use = (f) => p.confidence[f] >= θ ? assert(p[f]) : ask(f); // never re-ask what's known

Cross-cutting concerns

Maps to the real app

New concept	Real precon_web anchor	Change
Profile.orgType	OrgType (account-profiles.ts)	real reuse enum + AccountProfile features
Confirm step	organization_type · service_area · trades · market_sectors	collapse 4 backend steps → 1 confirm
OnboardingSession FSM	OnboardingStep store (zustand)	replace FE store w/ server FSM
route.persona → surface	AccountProfile.features + sidebar gating	new capture role; field → fieldOps
TeamInvite.surface	TeamInvite{email,role}	extend add surface; stop hardcoding "member"
Pursuit	Job (kanban)	new seeds real Jobs pre-signup
TradeConfig (×34)	trades-data.ts TRADES[]	seed the trade-library — 6 families, per-trade levers
Value proof	Sarah (precon_agents)	real tune recipe per type/trade
Close (self-serve)	plan_selection + Stripe 21-day trial	trigger move ask to post-wow
Deal / MEDDPICC	Zwick MEDDPICC scorecard	seed from research vs by hand
context_notes	Company Brain	auto pre-fill from enrichment

Build order — ship dark, cut over one flag at a time

This is the implementation spec for the decision tree; the Squires & CVE walkthroughs are its acceptance tests. Closes Brock's technical-mapping ask.