Pro-Website Onboarding Wizard

Summary

When a new customer activates a ChurchWiseAI subscription, they receive a magic link that lands them on /admin/[token]. If the role is admin and the account has an activated_at timestamp, the Overview tab renders SetupGuide — a 10-step guided setup with a progress bar, per-step slide-over panels (right panel on desktop, bottom sheet on mobile), skip/minimize controls, and a celebration card on completion. Required steps are: Church Profile, Office Hours & Timezone, Notification Email, Theology & Tradition, and Share Your Chatbot. Optional steps surface Staff & Ministries, What to Expect, This Week's Sermon, FAQs (tier-gated), and Voice Greeting (voice plans only). Progress is persisted in localStorage — there is no onboarding_steps DB column. After all required steps are complete and the celebration is dismissed, SetupGuide returns null and OptimizationTips surfaces post-setup improvements in the Overview sidebar.

Flow

Phase tracker

• Phase 1 — Wizard MVP: SetupGuide, SetupStepCard, SetupSlideOver, SetupCelebration, form extraction (merged 2026-04-07)
• Phase 2 — Skip/minimize + localStorage progress persistence + collapsed reminder bar (merged 2026-04-07)
• Phase 3 — OptimizationTips side panel with 10 computed suggestions, 30-day dismissal TTL (merged 2026-04-07)
• Phase 4 — Tier-differentiated wizard flows: Starter shows fewer steps than Pro/Suite; potentially different step ordering per product channel (in progress)

Code files

Authoritative list (see frontmatter code-files:). Derive check validates they exist.

File	Role
src/components/admin/SetupGuide.tsx	Main orchestrator — step definitions, state machine, localStorage hydration, slide-over and navigation dispatch
src/components/admin/SetupStepCard.tsx	Single step card — 4 visual states: complete, current, upcoming, skipped
src/components/admin/SetupSlideOver.tsx	Right-panel / bottom-sheet wrapper — overlay, slide animation, Save & Continue / Skip / Close buttons
src/components/admin/SetupCelebration.tsx	Celebration card shown when all required steps are complete before dismissal
src/components/admin/OptimizationTips.tsx	Post-setup tip card — up to 10 computed suggestions, per-tip 30-day localStorage dismissal
src/components/admin/forms/ChurchProfileForm.tsx	Name, description, hero photo (bare mode for slide-over)
src/components/admin/forms/OfficeHoursForm.tsx	Weekly office hours + timezone (bare mode)
src/components/admin/forms/NotificationsForm.tsx	Email + SMS notification routing (bare mode)
src/components/admin/forms/WhatToExpectForm.tsx	First-visit fields: parking, dress, kids, music, etc. (bare mode)
src/components/admin/forms/SharingForm.tsx	Chatbot link, embed snippet, QR code + onMarkShared callback
src/app/admin/[token]/components/DashboardOverview.tsx	Entry point — computes completion flags from DB fields, conditionally renders SetupGuide and OptimizationTips

Tests

• e2e/delivers/churchwiseai/04-onboarding.spec.ts — Playwright spec covering the onboarding wizard flow
• TODO: Add entry to knowledge/tests/registry.yaml under key cwa-04-onboarding

Decisions

• 2026-04-06-dashboard-onboarding-ux — replaced the static GettingStarted checklist with the guided wizard; slide-over panels extract forms from Settings/Training tabs to keep a single source of truth for form logic
• 2026-04-11-pricing-overhaul — plan key rename (e.g., pro → cwa_pro_both) motivates using canAccess() and planIncludesVoice() from @/lib/premium-shared rather than raw string comparisons; all future wizard tier logic must follow this pattern

Gotchas

• No DB column for wizard progress. There is no onboarding_steps column on premium_churches. All wizard state (skipped steps, celebration dismissed, sharing done, collapsed) lives in localStorage keys prefixed cwai-setup-*. The only DB-derived flags are completion checks on existing columns (custom_name, custom_description, custom_hours, notification_email, theology lens, etc.). Do NOT assert a DB column without verifying via information_schema.columns first — see feedback_verify_db_columns.md.
• Never compare plan strings directly. SetupGuide gates FAQs via canAccess(plan, 'faq_management') and voice greeting via planIncludesVoice(plan, channel) — both from @/lib/premium-shared. Do NOT add raw comparisons (plan === 'pro'). After the plan key rename, five components broke for a real customer. Always use the helpers — see feedback_never_compare_plan_directly.md.
• Step count is dynamic (up to 10, not always 10). Base = 8 steps. FAQs appended if canAccess is truthy. Voice Greeting appended if planIncludesVoice is truthy. Starter chat-only customers see 8 steps (no voice, no FAQs). Pro/Suite voice+chat customers see all 10.
• Skip is state, not data-loss. Skipping a step sets localStorage cwai-setup-skipped but never writes to the DB and never marks a step complete. The guide collapses to a reminder bar when all remaining incomplete required steps are skipped, but skips are cleared when the user clicks "Open guide" — steps remain actionable.
• Wizard only shows for role === 'admin'. Office admins, care team, volunteers, etc. see the normal dashboard regardless of setup completeness. This is intentional — only the account owner should manage setup.
• Public demos must be fully populated. Demo churches (00000000-0000-4000-a000-*) used in QA must have all DB fields populated so the wizard reflects a real completion state, not empty flags. See feedback_no_empty_public_demos.md. Empty-state testing belongs in the behavioral harness with synthetic mock data, not real DB rows.
• bare prop on form components. All extracted forms accept a bare?: boolean prop that strips the outer SectionCard wrapper so they render cleanly inside the slide-over panel. Never remove this prop — it's load-bearing for the wizard layout.

Recent activity

Reconciler (Phase 4) will populate this automatically from PR merges.