feat(onboarding/phase-2): settings hub, setup wizard shell, first-run redirect

Phase 2 of hospital onboarding & self-service plan
(docs/superpowers/plans/2026-04-06-hospital-onboarding-self-service.md
checked in here for the helix-engage repo).

Frontend foundations for the staff-portal Settings hub and 6-step setup
wizard. Backend was Phase 1 (helix-engage-server commit).

New shared components (src/components/setup/):
- wizard-shell.tsx — fullscreen layout with left step navigator, progress
  bar, and Skip-for-now affordance
- wizard-step.tsx — single-step wrapper with Mark Complete + Prev/Next/
  Finish navigation, completion badge
- section-card.tsx — Settings hub card with title/description/icon, links
  to a section page, optional status badge mirroring setup-state

New pages:
- pages/setup-wizard.tsx — top-level /setup route, fullscreen (no AppShell),
  loads setup-state from sidecar, renders the active step. Each step has a
  placeholder body for now; Phase 5 swaps placeholders for real form
  components from the matching settings pages. Already functional end-to-end:
  Mark Complete writes to PUT /api/config/setup-state/steps/<step>, Skip
  posts to /dismiss, Finish navigates to /.
- pages/team-settings.tsx — moved the existing workspace member listing out
  of the old monolithic settings.tsx into its own /settings/team route. No
  functional change; Phase 3 will add the invite form + role editor here.
- pages/settings-placeholder.tsx — generic "Coming in Phase X" stub used by
  routes for clinics, doctors, telephony, ai, widget until those pages land.

Modified pages:
- pages/settings.tsx — rewritten as the Settings hub (the new /settings
  route). Renders SectionCards in 3 groups (Hospital identity, Care
  delivery, Channels & automation) with completion badges sourced from
  /api/config/setup-state. The hub links to existing pages (/branding,
  /rules) and to placeholder pages for the not-yet-built sections.
- pages/login.tsx — after successful login, calls getSetupState() and
  redirects to /setup if wizardRequired. Failures fall through to / so an
  older sidecar without the setup-state endpoint still works.
- components/layout/sidebar.tsx — collapsed the Configuration group
  (Rules Engine + Branding standalone entries) into the single Settings
  entry that opens the hub. Removes the IconSlidersUp import that's no
  longer used.

New types and helpers (src/lib/setup-state.ts):
- SetupState / SetupStepName / SetupStepStatus types mirroring the sidecar
  shape
- SETUP_STEP_NAMES constant + SETUP_STEP_LABELS map (title + description
  per step) — single source of truth used by the wizard, hub, and any
  future surface that wants to render step metadata
- getSetupState / markSetupStepComplete / markSetupStepIncomplete /
  dismissSetupWizard / resetSetupState helpers wrapping the api-client

Other:
- lib/api-client.ts — added apiClient.put() helper for the setup-state
  step update mutations (PUT was the only verb missing from the existing
  get/post/graphql helpers)
- main.tsx — registered new routes:
    /setup                       (fullscreen, no AppShell)
    /settings                    (the hub, replaces old settings.tsx)
    /settings/team               (moved member listing)
    /settings/clinics            (placeholder, Phase 3)
    /settings/doctors            (placeholder, Phase 3)
    /settings/telephony          (placeholder, Phase 4)
    /settings/ai                 (placeholder, Phase 4)
    /settings/widget             (placeholder, Phase 4)

Tested via npx tsc --noEmit and npm run build (clean, only pre-existing
chunk-size and dynamic-import warnings unrelated to this change).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

src/pages/setup-wizard.tsx

@@ -0,0 +1,138 @@
+import { useEffect, useState } from 'react';
+import { useNavigate } from 'react-router';
+import { WizardShell } from '@/components/setup/wizard-shell';
+import { WizardStep } from '@/components/setup/wizard-step';
+import {
+    SETUP_STEP_NAMES,
+    SETUP_STEP_LABELS,
+    type SetupState,
+    type SetupStepName,
+    getSetupState,
+    markSetupStepComplete,
+    dismissSetupWizard,
+} from '@/lib/setup-state';
+import { notify } from '@/lib/toast';
+import { useAuth } from '@/providers/auth-provider';
+
+// Top-level onboarding wizard. Auto-shown by login.tsx redirect when the
+// workspace has incomplete setup steps. Each step renders a placeholder card
+// in Phase 2 — Phase 5 swaps the placeholders for real form components from
+// the matching settings pages (clinics, doctors, team, telephony, ai).
+//
+// The wizard is functional even at placeholder level: each step has a
+// "Mark complete" button that calls PUT /api/config/setup-state/steps/<name>,
+// which lets the operator click through and verify first-run detection +
+// dismiss flow without waiting for Phase 5.
+export const SetupWizardPage = () => {
+    const navigate = useNavigate();
+    const { user } = useAuth();
+    const [state, setState] = useState<SetupState | null>(null);
+    const [activeStep, setActiveStep] = useState<SetupStepName>('identity');
+    const [loading, setLoading] = useState(true);
+    const [saving, setSaving] = useState(false);
+
+    useEffect(() => {
+        let cancelled = false;
+        getSetupState()
+            .then(s => {
+                if (cancelled) return;
+                setState(s);
+                // Land on the first incomplete step so the operator picks
+                // up where they left off.
+                const firstIncomplete = SETUP_STEP_NAMES.find(name => !s.steps[name].completed);
+                if (firstIncomplete) setActiveStep(firstIncomplete);
+            })
+            .catch(err => {
+                console.error('Failed to load setup state', err);
+                notify.error('Setup', 'Could not load setup state. Please reload.');
+            })
+            .finally(() => {
+                if (!cancelled) setLoading(false);
+            });
+        return () => {
+            cancelled = true;
+        };
+    }, []);
+
+    if (loading || !state) {
+        return (
+            <div className="flex min-h-screen items-center justify-center bg-primary">
+                <p className="text-sm text-tertiary">Loading setup…</p>
+            </div>
+        );
+    }
+
+    const activeIndex = SETUP_STEP_NAMES.indexOf(activeStep);
+    const isLastStep = activeIndex === SETUP_STEP_NAMES.length - 1;
+    const onPrev = activeIndex > 0 ? () => setActiveStep(SETUP_STEP_NAMES[activeIndex - 1]) : null;
+    const onNext = !isLastStep ? () => setActiveStep(SETUP_STEP_NAMES[activeIndex + 1]) : null;
+
+    const handleMarkComplete = async () => {
+        setSaving(true);
+        try {
+            const updated = await markSetupStepComplete(activeStep, user?.email);
+            setState(updated);
+            notify.success('Step complete', SETUP_STEP_LABELS[activeStep].title);
+            // Auto-advance to next incomplete step (or stay if this was the last).
+            if (!isLastStep) {
+                setActiveStep(SETUP_STEP_NAMES[activeIndex + 1]);
+            }
+        } catch {
+            notify.error('Setup', 'Could not save step status. Please try again.');
+        } finally {
+            setSaving(false);
+        }
+    };
+
+    const handleFinish = () => {
+        notify.success('Setup complete', 'Welcome to your workspace!');
+        navigate('/', { replace: true });
+    };
+
+    const handleDismiss = async () => {
+        try {
+            await dismissSetupWizard();
+            notify.success('Setup dismissed', 'You can finish setup later from Settings.');
+            navigate('/', { replace: true });
+        } catch {
+            notify.error('Setup', 'Could not dismiss the wizard. Please try again.');
+        }
+    };
+
+    return (
+        <WizardShell
+            state={state}
+            activeStep={activeStep}
+            onSelectStep={setActiveStep}
+            onDismiss={handleDismiss}
+        >
+            <WizardStep
+                step={activeStep}
+                isCompleted={state.steps[activeStep].completed}
+                isLast={isLastStep}
+                onPrev={onPrev}
+                onNext={onNext}
+                onMarkComplete={handleMarkComplete}
+                onFinish={handleFinish}
+                saving={saving}
+            >
+                <StepPlaceholder step={activeStep} />
+            </WizardStep>
+        </WizardShell>
+    );
+};
+
+// Placeholder body for each step. Phase 5 will replace this dispatcher with
+// real form components (clinic-form, doctor-form, invite-member-form, etc).
+const StepPlaceholder = ({ step }: { step: SetupStepName }) => {
+    const meta = SETUP_STEP_LABELS[step];
+    return (
+        <div className="rounded-lg border border-dashed border-secondary bg-secondary px-6 py-12 text-center">
+            <p className="text-sm font-semibold text-secondary">Coming in Phase 5</p>
+            <p className="mt-2 text-xs text-tertiary">
+                The {meta.title.toLowerCase()} form will live here. For now, click <b>Mark complete</b> below
+                to test the wizard flow end-to-end.
+            </p>
+        </div>
+    );
+};