Pro Website — Admin Setup Wizard Journey

Who this is for

A pastor or office admin who just signed up for Pro Website (plan=cwa_pro_website) and received the welcome email. They click the magic link, land on /admin/{admin_token}, and see the Setup Guide on the Overview tab.

The core UX promise

The wizard is the pop-out experience. Every step the customer needs to complete to make their Pro Website look like their church lives inside the slide-over panel — same visual surface, consistent save pattern, explicit user confirmation before anything persists. The wizard does not yank the user to other tabs mid-flow.

The 8-step journey (Pro Website plan)

#	Step id	Title	Type	Form component	What saves it
1	website-design	Website Design	slide-over	HeroVideoPickerForm	Click "Save video selections"
2	church-profile	Church Profile	slide-over	ChurchProfileForm	Click "Save profile"
3	office-hours	Office Hours & Timezone	slide-over	OfficeHoursForm	Click "Save hours"
4	notifications	Notification Email	slide-over	NotificationsForm	Click "Save"
5	theology	Theology & Tradition	slide-over	TheologySettings	Click "Save tradition" (explicit, not auto)
6	church-knowledge	Staff & Ministries	navigate	Training tab → Church Knowledge sub-tab	Saves happen on the Training tab
7	what-to-expect	What to Expect	slide-over	WhatToExpectForm	Click "Save"
8	sharing	Share Your Website	slide-over	SharingForm	"I've shared it" button

Optional follow-ups after the core 8: this-week, faqs, agent-personality (all NAVIGATE to Training tab).

Expected behaviors — the non-negotiables

B1 — "Setup Guide" header and progress

• Welcome header: "Let's set up your church website" + progress bar showing "X of N complete"
• Progress percentage updates as steps complete.

B2 — Step cards on the main page

• Each step renders as a gold card in a vertical list.
• States:
  • upcoming — white card, "Set Up →" button
  • current — gold-gradient card with step number badge, highlighted border, Learn More expandable
  • complete — stone card, green check circle, "Complete" badge, "Edit" link
  • skipped — stone card, "Skipped" pill
• Clicking anywhere on an upcoming/current card triggers handleSetUp(stepId).

B3 — Pop-out slide-over (SLIDE_OVER_STEPS)

For step ids in the SLIDE_OVER_STEPS set (website-design, church-profile, office-hours, notifications, theology, what-to-expect, sharing):

1. Click card → slide-over panel animates in from the right (desktop) or up from the bottom (mobile).
2. Panel header: "Step N of M" label + step title.
3. Panel body: the relevant form component (see table above).
4. User fills the form + clicks the form's Save button.
5. Form's onSaved callback fires → handleStepSaved(stepId).
6. Ring + scroll sync: while slide-over is open, the matching main-page step card shows a gold ring (ring-2 ring-[#D4AF37] + amber shadow + scale-[1.01]). On advance, the NEW step's card gets the ring instead.
7. handleStepSaved finds the next incomplete, non-skipped step:
   • If next is SLIDE_OVER type: chain — panel updates label to "Step N+1 of M", title, form content. Ring moves to the new step's card on the main page. Main-page card auto-scrolls into view (smooth, centered).
   • If next is NAVIGATE type or no next: panel closes. User returns to the step-card list. DO NOT auto-navigate to another tab. The user clicks the next card deliberately.
   • If no next incomplete step: celebration screen renders on next server refresh.

B4 — Navigate steps (NAVIGATE_MAP)

For step ids church-knowledge, this-week, faqs, agent-personality, voice-greeting:

1. Click card → onNavigateToHash(hash) fires → router jumps to the matching tab.
2. These steps live on the Training tab (or Voice tab for voice-greeting).
3. The wizard does not auto-jump here after a slide-over save (the old behavior was to yank the user mid-flow; we fixed it 2026-04-18).

B5 — Save behavior per form

Every save is explicit — user clicks a button. No auto-save-on-pick for any step, including Theology. Rationale: clear user intent, avoids accidental persistence, and makes the onSaved→advance signal deterministic.

B5a — Theology & Tradition specifically

• User opens dropdown, picks a tradition → UI reflects the pick (badge + lens description update) BUT no API call fires.
• An "Unsaved change" amber label appears next to the "Save tradition" button.
• User clicks "Save tradition" → spinner "Saving…" → green "Saved" pill appears in the header → after 700ms, onSaved() fires and the wizard advances (to Step 6 = NAVIGATE, so panel closes).
• If user reopens the Theology step card after saving, dropdown shows the saved tradition, Save button is disabled ("No unsaved changes").

B6 — Celebration

• When all required steps are complete, SetupCelebration screen renders (confetti + summary).
• Dismissing it sets cwai-setup-celebration-done=true in localStorage.

B7 — Skip semantics

• Skip button on any step → adds stepId to skippedSteps set (localStorage-persisted).
• Skipped steps are excluded from the "next incomplete step" search.
• Skipped steps show as stone cards with "Skipped" pill; user can click to unskip and set up later.

Regression tests (what broke before)

2026-04-18 — Auto-navigate to NAVIGATE step after save

• Bug: After saving on any slide-over step, if the next incomplete step was a NAVIGATE step, handleStepSaved called onNavigateToHash() — teleporting the user to another tab mid-wizard.
• User-reported examples:
  • Click Step 5 Theology → pick a tradition (auto-saved) → 700ms later → landed on Training → Staff & Ministries. "I clicked Theology and ended up on Staff."
  • Save What to Expect → jumped to Training → This Week's Sermon.
• Fix: handleStepSaved now closes the slide-over but does NOT auto-navigate when next step is NAVIGATE. User clicks the next step card deliberately.
• Covered by Playwright assertion: test('Save on slide-over does not auto-nav when next is NAVIGATE', ...).

2026-04-18 — Theology auto-save on dropdown pick

• Bug: Selecting a tradition in the dropdown immediately called the save API. Users with fast trackpad clicks would accidentally persist the wrong tradition before scrolling through options.
• Example: Admin of Buchanan Baptist Church (plan=cwa_pro_website, denomination=Baptist) ended up with theological_lens_id=3 instead of Baptist (id=14).
• Fix: Dropdown pick only updates the draft (selectedLensId). Persistence happens on explicit "Save tradition" button click.
• Covered by Playwright assertion: test('Theology dropdown pick does NOT fire save API', ...).

2026-04-18 — Gold cards don't scroll to match slide-over step

• Bug: Slide-over advanced to next step showing correct label, but main-page step cards stayed in their original scroll position — visual disconnect.
• Fix: Each step card wrapper has data-setup-step-id attribute. useEffect on openStepId scrolls matching card into view (smooth, block='center') + adds gold ring for highlight.
• Covered by Playwright assertion: test('Main-page card ring moves on slide-over advance', ...).

Out of scope for this spec

• Chat-only plan variant (plan=cwa_starter_chat, cwa_pro_chat, etc.) — different step order; covered by a separate spec when needed.
• Voice plan variant — adds voice-greeting step.
• Overrides editor within TheologySettings (Section B) — separate touchpoint, tested separately.
• SetupCelebration — visual only, non-blocking.

Verification checklist (used by Playwright spec)

• /admin/{TOKEN} loads for a plan=cwa_pro_website + status=active row.
• Setup Guide header renders with progress bar.
• 8 gold step cards visible in order (Pro Website plan).
• Click Step 1 card → slide-over opens from right.
• Slide-over header shows "Step 1 of 8" + "Website Design".
• Step 1 card has gold ring while slide-over open.
• Fill form, click Save → panel advances to Step 2.
• Step 1 card now shows Complete state.
• Step 2 card now has the gold ring.
• Main-page scrolled so Step 2 card is vertically centered in viewport.
• Repeat through Steps 3, 4.
• Theology step (5): dropdown pick alone does NOT make a POST to /api/admin/theology (intercept network).
• After Save tradition click: panel advances only if next step is slide-over. For Pro Website plan, next step is church-knowledge (NAVIGATE) → panel closes, URL does NOT change to include #training-church-knowledge.
• Click Step 6 (Staff & Ministries) card → URL changes to Training tab via onNavigateToHash.
• Click What to Expect card → pop-out. Save. URL does NOT auto-change to #training-this-week.