10-step guided setup wizard on Overview tab

Status

DECIDED

Context

New churches completing Stripe checkout landed on the admin dashboard with no guidance — blank tabs, no signal on what to do next, and no progressive disclosure of features. Support context would be needed to explain every step. The Overview tab was effectively unused real estate.

Simultaneously, a critical bug was found: the normalizePlanTier() function was mapping the pro_website plan to the 'pro' tier, giving $19.95 Pro Website customers 35 tools and 4 agents — the same as $34.95 CWA Pro. This was both a financial leak and a correctness failure.

Decision

Replace the Overview tab for new churches with a 10-step SetupGuide that walks churches through initial configuration.
Each step uses slide-over panels with conversational descriptions and "Learn more" expandables. Steps carry Required/Optional badges.
Wizard supports skip, minimize-to-bar, and a celebration state with OptimizationTips on completion.
Critical fix shipped in the same PR: pro_website tier normalized to 'starter' (12 tools, 2 agents) — not 'pro'.

Rationale

Churches are run by pastors, not SaaS operators. A guided setup reduces time-to- value dramatically and surfaces features in the order they matter (profile first, then knowledge base, then chatbot config). The slide-over pattern lets each step be self-contained without a page reload.

The tier normalization fix had to ship at the same time — leaving it open meant every Pro Website customer was receiving Pro-tier capabilities without paying for them.

Consequences

Good: New church onboarding has a clear, step-by-step path. Welcome email updated to reference the guided setup. 10 new components + 5 extracted form components available for reuse.
Bad: The wizard adds state management complexity (localStorage-backed completion tracking). React hydration mismatch on useState initializers from localStorage required a separate fix.
Reversible? Yes — the wizard is a feature flag candidate. The Overview tab content can be restored without touching other tabs.

Alternatives considered

Tooltip walkthroughs (Shepherd.js / Intercom-style) — rejected; requires third-party JS load on every page and is notoriously fragile with CSR route changes.
Separate onboarding page — rejected; introduces a redirect step that breaks the magic-link "lands on dashboard" contract.

Status​

Context​

Decision​

Rationale​

Consequences​

Alternatives considered​

Links​