Skip to main content

​
Onboarding pilot, rollout, and recovery

Operational runbook for enabling onboarding Labs, staff writes, stage progression, and cloud communications. Read the integration map for IDs, flags, and API contracts first. Engine cutover (direct configuration, compute cohort review, historical-receipt reconciliation, token revoke, enablement, rollback) lives only in services/onboarding-engine/docs/RUNTIME.md. Do not duplicate that procedure here. This document is not authorization to enable flags, deploy, send messages, purchase numbers, or write production configuration. Each activation needs an explicit, named approval.

​
Decided ownership (2026-09-29)

​
Preconditions (fail-closed)

Confirm before any pilot widen or communications enablement:
  1. Current origin/main (or the exact authorized deploy SHA) and the integration map state table still match production flags.
  2. At most one sender will be active. Stop the Mac mini onboarding-engine job and revoke its CRM token before enabling ONBOARDING_ENGINE_LIVE_ENABLED. Follow RUNTIME.md for direct configuration, compute cohort review, and single-writer cutover.
  3. Do not treat the retired mini job or a local package run/bootstrap as the current sender.
  4. Labs Locations are explicit. An enabled Labs flag is not an automatic-progression or communications allowlist.
  5. General admin CRM writes (ONBOARDING_ADMIN_CRM_WRITES_ENABLED) and KYC field writes are separate gates.
  6. A Retention card must have exactly one Product Location ID matching the reviewed cohort member, as well as the correct Operations Location and contact. Missing, duplicate or conflicting mappings block the member before account signals or writes. The creation receipt must confirm that mapping and open status; an uncertain receipt requires ledger reconciliation before retrying. A card for another product account cannot satisfy the Won prerequisite.

​
Pilot cohort

Use Location IDs only. As of the September 29 audit the four Labs-enabled Locations are: Pilot Operator B mapping (revalidate before repair):
  • Operations contact: KvUhx6Luui3Vw3POkUuY
  • Onboarding opportunity: C2gg7sYKYkpgym20UrZA
Operations source Location for calendars and opportunities: ReoQmuh4ooNuHeE5stlj.

​
Acceptance gates (still open unless freshly proven)

Record dated outcomes, not green flags alone: Rollback for the Operator UI: disable the per-Location Labs flag. That does not reverse a dispatched phone purchase, appointment change, or independent engine send.

​
Rollout sequence

Enable each step only with explicit approval naming the flag/target.
  1. Labs Locations — keep the cohort explicit; expand Location-by-Location.
  2. Calendar mapping — save kickoff + FM1 + separate FM Follow-up for FM2; verify live events for a known Operations contact.
  3. Admin CRM write gate — after live synthetic API acceptance of opportunity updates, pagination, and audit trails.
  4. Automatic progression — ONBOARDING_AUTO_PROGRESS_ENABLED + ONBOARDING_AUTO_PROGRESS_LOCATION_IDS (also needs the write gate). Live still requires staff QA. Confirm native CRM workflows no longer move onboarding stages.
  5. Cloud communications — follow RUNTIME.md. Start the cohort in compute; review proposals, then promote approved members to send. Engine may stamp its own fields (never Blocked or Tech Calls Complete; on retention cards it stamps Last Credit Pull and Last App Login from operator-pulse via usageStamp, while progression alone writes all four on the onboarding opportunity), send messages, create tasks, create retention cards, move retention stages, and mark_won — never advance onboarding stages (#1807). After #1815, custom values come from the CRM every pass.
  6. Slack workspace — install the dedicated FM Bot in My Funding Machine Support, configure its credentials and staff roster, then enable the workspace and provisioning flags. Follow Slack workspace setup. Do not activate a Slack Pro upgrade reminder; this workspace flow no longer requires customers to upgrade.

​
Recovery cheatsheet

​
What not to do

  • Run two writers (mini job + cloud live).
  • Purchase a phone number or create a live Identity session “to test docs.”
  • Deploy Convex production or change CRM workflows without a named write approval.
  • Infer Slack Pro, attendance, or Payment Verified from connection, elapsed time, or subscription active/trialing alone.
  • Treat app “onboarding complete” as CRM Won or as permission to enable retention emails.
  • Document GoHighLevel / GHL in Operator-facing copy (backend and this internal file may).