feat: Introduce an onboarding review step and remove the initial welcome step from the onboarding flow.

frontend/src/components/ComponentOverlay.tsx

@@ -11,7 +11,7 @@ interface ComponentOverlayProps {
 }
 
 // Components that render full-screen (TV-distance readable)
-const FULLSCREEN_COMPONENTS = new Set(["HeadacheLog", "MedLog", "MedStatus", "SessionSummary", "OnboardingProgress", "OnboardingSummary", "MyMedsList", "QuickReply", "ConfirmationCard"]);
+const FULLSCREEN_COMPONENTS = new Set(["HeadacheLog", "MedLog", "MedStatus", "SessionSummary", "OnboardingProgress", "OnboardingSummary", "OnboardingReview", "MyMedsList", "QuickReply", "ConfirmationCard"]);
 
 export function ComponentOverlay({ component, onDismiss }: ComponentOverlayProps) {
   const isFullscreen = FULLSCREEN_COMPONENTS.has(component.name);

frontend/src/registry/OnboardingProgress.tsx

@@ -1,16 +1,16 @@
 "use client";
 
-import { Check, User, Pill, Users, PartyPopper } from "lucide-react";
+import { Check, User, Pill, Users, PartyPopper, ClipboardCheck } from "lucide-react";
 
 interface OnboardingProgressProps {
-  currentStep: "welcome" | "name" | "medications" | "contacts" | "complete";
+  currentStep: "name" | "medications" | "contacts" | "review" | "complete";
 }
 
 const steps = [
-  { id: "welcome", label: "Welcome", icon: PartyPopper },
   { id: "name", label: "Your Name", icon: User },
   { id: "medications", label: "Medications", icon: Pill },
   { id: "contacts", label: "Contacts", icon: Users },
+  { id: "review", label: "Review", icon: ClipboardCheck },
   { id: "complete", label: "All Set!", icon: Check },
 ];
 

frontend/src/registry/OnboardingReview.tsx

@@ -0,0 +1,194 @@
+"use client";
+
+import { User, Pill, Stethoscope, Heart, ClipboardCheck, ArrowLeft, Check } from "lucide-react";
+
+interface Medication {
+  medicationName: string;
+  dose?: string | null;
+  frequency?: string | null;
+}
+
+interface Contact {
+  name?: string | null;
+  email?: string | null;
+}
+
+interface OnboardingReviewProps {
+  displayName?: string | null;
+  medications?: Medication[];
+  neurologist?: Contact;
+  caregiver?: Contact;
+}
+
+export function OnboardingReview({
+  displayName,
+  medications = [],
+  neurologist,
+  caregiver,
+}: OnboardingReviewProps) {
+  const handleConfirm = () => {
+    window.dispatchEvent(
+      new CustomEvent("confirmation-card-action", {
+        detail: { action: "confirm", text: "Yes, that all looks correct. Please complete my setup." },
+      })
+    );
+  };
+
+  const handleGoBack = () => {
+    window.dispatchEvent(
+      new CustomEvent("confirmation-card-action", {
+        detail: { action: "cancel", text: "I'd like to make some changes before we finalise." },
+      })
+    );
+  };
+
+  const hasNeurologist = neurologist?.name || neurologist?.email;
+  const hasCaregiver = caregiver?.name || caregiver?.email;
+
+  return (
+    <div
+      className="relative flex flex-col h-full w-full overflow-hidden px-12 py-10
+                 animate-in zoom-in-95 fade-in duration-700"
+    >
+      {/* Top accent line */}
+      <div className="absolute top-0 left-[20%] right-[20%] h-1 bg-gradient-to-r from-transparent via-cta to-transparent opacity-60" />
+
+      {/* Header */}
+      <div className="flex items-center gap-6 mb-8">
+        <div
+          className="w-16 h-16 rounded-xl flex items-center justify-center
+                     bg-cta/15 border border-cta/30"
+        >
+          <ClipboardCheck className="w-8 h-8 text-cta" />
+        </div>
+        <div>
+          <h3 className="text-3xl font-bold tracking-tight text-primary">Review Your Setup</h3>
+          <p className="text-lg text-muted mt-1">Check everything looks right before we finish</p>
+        </div>
+      </div>
+
+      {/* Content sections */}
+      <div className="flex-1 space-y-5 overflow-y-auto pr-2">
+        {/* Name */}
+        <div className="flex items-center gap-5 p-5 rounded-2xl bg-surface-subtle/50 border border-surface-overlay">
+          <div className="w-12 h-12 rounded-xl bg-cta/15 flex items-center justify-center flex-shrink-0">
+            <User className="w-6 h-6 text-cta" />
+          </div>
+          <div>
+            <p className="text-sm text-muted uppercase tracking-wide font-medium">Your Name</p>
+            <p className={`text-2xl font-semibold ${displayName ? "text-primary" : "text-muted/50 italic"}`}>
+              {displayName || "Not set"}
+            </p>
+          </div>
+        </div>
+
+        {/* Medications */}
+        <div className="p-5 rounded-2xl bg-surface-subtle/50 border border-surface-overlay">
+          <div className="flex items-center gap-3 mb-3">
+            <div className="w-12 h-12 rounded-xl bg-accent-cyan/15 flex items-center justify-center flex-shrink-0">
+              <Pill className="w-6 h-6 text-accent-cyan" />
+            </div>
+            <div>
+              <p className="text-sm text-muted uppercase tracking-wide font-medium">Medications</p>
+              <p className="text-lg text-muted">
+                {medications.length > 0
+                  ? `${medications.length} medication${medications.length !== 1 ? "s" : ""} tracked`
+                  : "None set up"}
+              </p>
+            </div>
+          </div>
+          {medications.length > 0 && (
+            <div className="flex flex-wrap gap-3 mt-2 ml-15">
+              {medications.map((med, i) => (
+                <span
+                  key={i}
+                  className="px-4 py-2 rounded-xl bg-accent-cyan/10 border border-accent-cyan/20 text-lg font-medium text-accent-cyan"
+                >
+                  {med.medicationName}
+                  {med.dose && <span className="text-accent-cyan/60 ml-1.5">({med.dose})</span>}
+                  {med.frequency && <span className="text-accent-cyan/40 ml-1.5">· {med.frequency}</span>}
+                </span>
+              ))}
+            </div>
+          )}
+        </div>
+
+        {/* Contacts row */}
+        <div className="flex gap-4">
+          {/* Neurologist */}
+          <div className="flex-1 p-5 rounded-2xl bg-surface-subtle/50 border border-surface-overlay">
+            <div className="flex items-center gap-3 mb-2">
+              <div className="w-10 h-10 rounded-lg bg-cta/15 flex items-center justify-center flex-shrink-0">
+                <Stethoscope className="w-5 h-5 text-cta" />
+              </div>
+              <p className="text-sm text-muted uppercase tracking-wide font-medium">Neurologist</p>
+            </div>
+            {hasNeurologist ? (
+              <div className="ml-13">
+                <p className="text-xl font-semibold text-primary truncate">{neurologist?.name}</p>
+                {neurologist?.email && (
+                  <p className="text-base text-muted truncate">{neurologist.email}</p>
+                )}
+              </div>
+            ) : (
+              <p className="text-lg text-muted/50 italic ml-13">Not set</p>
+            )}
+          </div>
+
+          {/* Caregiver */}
+          <div className="flex-1 p-5 rounded-2xl bg-surface-subtle/50 border border-surface-overlay">
+            <div className="flex items-center gap-3 mb-2">
+              <div className="w-10 h-10 rounded-lg bg-accent-pink/15 flex items-center justify-center flex-shrink-0">
+                <Heart className="w-5 h-5 text-accent-pink" />
+              </div>
+              <p className="text-sm text-muted uppercase tracking-wide font-medium">Caregiver</p>
+            </div>
+            {hasCaregiver ? (
+              <div className="ml-13">
+                <p className="text-xl font-semibold text-primary truncate">{caregiver?.name}</p>
+                {caregiver?.email && (
+                  <p className="text-base text-muted truncate">{caregiver.email}</p>
+                )}
+              </div>
+            ) : (
+              <p className="text-lg text-muted/50 italic ml-13">Not set</p>
+            )}
+          </div>
+        </div>
+      </div>
+
+      {/* Action buttons */}
+      <div className="flex gap-4 mt-6 pt-4 border-t border-white/5">
+        <button
+          onClick={handleGoBack}
+          className="flex-1 flex items-center justify-center gap-3 px-6 py-5
+                     rounded-xl bg-surface-overlay/50 text-secondary
+                     border border-white/10
+                     hover:bg-surface-overlay/80 hover:text-primary active:scale-[0.98]
+                     transition-all min-h-[64px]
+                     text-xl font-bold"
+        >
+          <ArrowLeft className="w-6 h-6" />
+          Go Back
+        </button>
+        <button
+          onClick={handleConfirm}
+          className="flex-1 flex items-center justify-center gap-3 px-6 py-5
+                     rounded-xl bg-cta text-gray-900 hover:brightness-110
+                     active:scale-[0.98] transition-all min-h-[64px]
+                     text-xl font-bold"
+        >
+          <Check className="w-6 h-6" />
+          Looks Good!
+        </button>
+      </div>
+
+      {/* Voice hint */}
+      <div className="flex items-center justify-center gap-2 mt-4">
+        <span className="text-sm text-muted uppercase tracking-[0.12em] font-semibold">
+          Say &quot;looks good&quot; to confirm or tell me what to change
+        </span>
+      </div>
+    </div>
+  );
+}

frontend/src/registry/index.tsx

@@ -33,6 +33,7 @@ import { OnboardingProgress } from "./OnboardingProgress";
 import { ProfileCard } from "./ProfileCard";
 import { MedicationCard } from "./MedicationCard";
 import { OnboardingSummary } from "./OnboardingSummary";
+import { OnboardingReview } from "./OnboardingReview";
 // New GenUI components for real-time health tracking
 import { MedStatus } from "./MedStatus";
 import { HeadacheLog } from "./HeadacheLog";
@@ -66,6 +67,7 @@ export const ComponentRegistry: ComponentRegistryMap = {
   ProfileCard,
   MedicationCard,
   OnboardingSummary,
+  OnboardingReview,
   // New GenUI components
   MedStatus,
   HeadacheLog,

src/reachy_mini_conversation_app/database.py

@@ -52,7 +52,7 @@ CREATE TABLE IF NOT EXISTS user_profile (
     id INTEGER PRIMARY KEY CHECK (id = 1),
     display_name TEXT,
     onboarding_completed INTEGER DEFAULT 0,
-    onboarding_step TEXT DEFAULT 'welcome',
+    onboarding_step TEXT DEFAULT 'name',
     timezone TEXT DEFAULT 'local',
     -- AI provider (currently openai only)
     preferred_provider TEXT DEFAULT 'openai',
@@ -404,7 +404,7 @@ h1 {{ color: #333; }}
             return dict(row)
         # Create default profile
         conn.execute(
-            "INSERT INTO user_profile (id, onboarding_step) VALUES (1, 'welcome')"
+            "INSERT INTO user_profile (id, onboarding_step) VALUES (1, 'name')"
         )
         conn.commit()
         row = conn.execute("SELECT * FROM user_profile WHERE id = 1").fetchone()

src/reachy_mini_conversation_app/openai_realtime.py

@@ -36,6 +36,20 @@ logger = logging.getLogger(__name__)
 OPEN_AI_INPUT_SAMPLE_RATE: Final[Literal[24000]] = 24000
 OPEN_AI_OUTPUT_SAMPLE_RATE: Final[Literal[24000]] = 24000
 
+# Tools available during onboarding flow — prevents the model from wandering
+# off to robot_expression, media_control, etc. instead of following the script.
+_ONBOARDING_ONLY_TOOLS: Final[frozenset[str]] = frozenset(
+    {
+        "show_onboarding_step",
+        "show_onboarding_review",
+        "get_current_datetime",
+        "setup_medication",
+        "get_my_medications",
+        "complete_onboarding",
+        "update_settings",
+    }
+)
+
 
 class OpenaiRealtimeHandler(RealtimeHandler):
     """An OpenAI realtime handler for fastrtc Stream."""
@@ -62,7 +76,7 @@ class OpenaiRealtimeHandler(RealtimeHandler):
         # Track whether the current response had tool calls so we can
         # defer response.create() until response.done (after ALL parallel
         # tool outputs have been submitted).
-        self._pending_tool_response: bool = False
+        self._pending_tool_response: dict | None = None
 
         # Two-phase proactive greeting: after the forced-speech greeting
         # completes, trigger onboarding tool calls automatically.
@@ -458,7 +472,7 @@ class OpenaiRealtimeHandler(RealtimeHandler):
             tools: Pre-built tool specs list.
             voice: Pre-resolved voice name.
         """
-        self._pending_tool_response = False
+        self._pending_tool_response = None
 
         # Fallbacks for callers that don't pre-build (e.g. _restart_session)
         if instructions is None:
@@ -685,6 +699,24 @@ class OpenaiRealtimeHandler(RealtimeHandler):
                                 )
                             except Exception as e:
                                 logger.error("Phase 2 FAILED: %s", e, exc_info=True)
+                        elif self._pending_tool_response is not None:
+                            # Deferred response.create from tool-result handler.
+                            # Sending here ensures the previous response is fully
+                            # complete and all tool outputs are committed.
+                            pending = self._pending_tool_response
+                            self._pending_tool_response = None
+                            logger.info(
+                                "response.done: sending deferred tool response (tools=%s)",
+                                "restricted" if "tools" in pending else "default",
+                            )
+                            try:
+                                await conn.response.create(response=pending)
+                            except Exception as e:
+                                logger.error(
+                                    "Deferred response.create FAILED: %s",
+                                    e,
+                                    exc_info=True,
+                                )
                         else:
                             logger.info(
                                 "response.done: no onboarding followup needed (flag=%s)",
@@ -882,6 +914,7 @@ class OpenaiRealtimeHandler(RealtimeHandler):
                         }
                         # Determine if we need to force speech (no more tools)
                         force_speech = False
+                        restrict_to_onboarding = False
                         if is_error:
                             force_speech = True
                             resp_instructions = (
@@ -895,35 +928,75 @@ class OpenaiRealtimeHandler(RealtimeHandler):
                             # Let the model continue the onboarding flow —
                             # it needs tools (show_onboarding_step, etc.)
                             # so do NOT strip them with force_speech.
+                            # IMPORTANT: restrict to onboarding tools only to
+                            # prevent the model wandering to robot_expression etc.
                             resp_instructions = (
                                 "The onboarding status has been checked and the progress UI "
                                 "is already shown on screen. Now continue the onboarding flow. "
                                 "Follow the Onboarding Steps from your system prompt. "
-                                "If on the 'welcome' or 'name' step, call "
+                                "If on the 'name' step, call "
                                 "show_onboarding_step(current_step='name') and warmly introduce "
                                 "yourself as Mini-Minder AND ask 'What should I call you?' in "
                                 "the same breath. "
                                 "You MUST speak out loud AND call the appropriate tools. "
-                                "You MUST respond in British English only."
+                                "You MUST respond in British English only.\n"
+                                "IMPORTANT: You MUST call show_onboarding_step as your NEXT action. "
+                                "Do NOT call robot_expression or any other tool first."
                             )
+                            onboarding_tool_specs = [
+                                t
+                                for t in (tools or get_tool_specs())
+                                if t.get("name") in _ONBOARDING_ONLY_TOOLS
+                            ]
+                            restrict_to_onboarding = True
                         elif tool_name in _ONBOARDING_CHAIN_TOOLS:
-                            # After getting datetime, call the next tool
+                            # After getting datetime, call the next tool.
+                            # Restrict to onboarding tools to stay on track.
                             resp_instructions = (
                                 "Continue following the Onboarding Flow from your system prompt. "
                                 "Use the tool result to decide what to do next. "
                                 "Call the next required tool (e.g. show_onboarding_step). "
                                 "You MUST respond in British English only."
                             )
+                            onboarding_tool_specs = [
+                                t
+                                for t in (tools or get_tool_specs())
+                                if t.get("name") in _ONBOARDING_ONLY_TOOLS
+                            ]
+                            restrict_to_onboarding = True
                         elif tool_name == "show_onboarding_step":
                             # After showing the UI step, the robot MUST speak
                             force_speech = True
+                            # Check which step was just shown from tool args
+                            shown_step = parsed_args.get(
+                                "current_step"
+                            ) or parsed_args.get("step", "")
+                            if shown_step == "name":
+                                resp_instructions = (
+                                    "The onboarding progress UI is now showing the 'name' step. "
+                                    "You MUST speak out loud and ask the user for their name. "
+                                    "Say something brief like: 'Let's get you set up — what should I call you?' "
+                                    "The user MUST hear you ask for their name. This is the MOST IMPORTANT "
+                                    "part of this step. Do NOT skip the name question. "
+                                    "You MUST respond in British English only."
+                                )
+                            else:
+                                resp_instructions = (
+                                    "The onboarding progress UI has been updated. "
+                                    "Now you MUST speak out loud to the user. "
+                                    "Follow your system prompt's Onboarding Steps instructions "
+                                    "for this step. Speak warmly and guide the user. "
+                                    "You MUST respond in British English only."
+                                )
+                        elif tool_name == "show_onboarding_review":
+                            # After showing the review card, the robot MUST speak
+                            force_speech = True
                             resp_instructions = (
-                                "The onboarding progress UI has been updated. "
-                                "Now you MUST speak out loud to the user. "
-                                "Follow your system prompt's Session Start Behavior: "
-                                "if this is NOT the welcome/name step, ask the user if they'd like to resume onboarding. "
-                                "If this IS the welcome or name step, introduce yourself warmly "
-                                "AND ask 'What should I call you?' — both in one short speech turn. "
+                                "The onboarding review card is now displayed on screen "
+                                "showing everything collected during setup. "
+                                "You MUST speak out loud to the user. Say something like: "
+                                "'Here's everything I've got. Does it all look right, or would you like to change anything?' "
+                                "Wait for their response before proceeding. "
                                 "You MUST respond in British English only."
                             )
                         elif tool_name in (
@@ -977,8 +1050,17 @@ class OpenaiRealtimeHandler(RealtimeHandler):
                             # is a redundant safety net.
                             resp_config["tools"] = []
                             resp_config["tool_choice"] = "none"
-                        await self.connection.response.create(
-                            response=resp_config,
+                        elif restrict_to_onboarding:
+                            # Onboarding flow: restrict to onboarding tools only
+                            resp_config["tools"] = onboarding_tool_specs
+                        # Defer sending response.create until response.done
+                        # so the API has committed all tool outputs first.
+                        self._pending_tool_response = resp_config
+                        logger.info(
+                            "Tool '%s': deferred response.create (force_speech=%s, restrict=%s)",
+                            tool_name,
+                            force_speech,
+                            restrict_to_onboarding,
                         )
 
                     # Event-driven prompt re-resolve: if a state-changing tool
@@ -1294,7 +1376,7 @@ class OpenaiRealtimeHandler(RealtimeHandler):
         timestamp_msg = (
             f"[Idle time update: {self.format_timestamp()} - No activity for {idle_duration:.1f}s] "
             f"Recent tools used: {recent}. "
-            f"ONLY use physical movement tools: dance, look_around, show_emotion, or do nothing. "
+            f"ONLY use robot_expression (dance, emotion, sweep_look) or do nothing. "
             f"Do NOT play music, show UI components, log data, or speak. "
             f"Avoid repeating the same action type as recent tools."
         )
@@ -1313,7 +1395,7 @@ class OpenaiRealtimeHandler(RealtimeHandler):
                 "instructions": (
                     "You MUST respond with physical movement function calls only - "
                     "no speech, no text, no music, no UI components. "
-                    "Only use movement/emotion tools like dance, look_around, show_emotion."
+                    "Only use robot_expression for movement/emotion."
                 ),
                 "tool_choice": "required",
             },

src/reachy_mini_conversation_app/profiles/_reachy_mini_minder_locked_profile/get_onboarding_status.py

@@ -38,7 +38,7 @@ class GetOnboardingStatus(Tool):
         medications = deps.database.get_scheduled_medications()
 
         completed = bool(profile.get("onboarding_completed", 0))
-        current_step = profile.get("onboarding_step", "welcome")
+        current_step = profile.get("onboarding_step", "name")
 
         # Following the headache-logging pattern: emit the UI directly
         # so the model doesn't need to call show_onboarding_step separately.

src/reachy_mini_conversation_app/profiles/_reachy_mini_minder_locked_profile/instructions.txt

@@ -323,30 +323,24 @@ Many users have cognitive challenges (memory issues, executive dysfunction, proc
 
 When `get_onboarding_status` shows `onboarding_completed: false`:
 
-1. **Welcome**: "Hi! I'm Mini-Minder, your care companion. I'll help you track your medications and headaches. Let's get you set up!"
-2. **Name**: "First, what should I call you? Or just say 'skip' if you'd rather not say."
-   - If they give a name, remember it for later
+1. **Name**: "Hi! I'm Mini-Minder, your care companion. Let's get you set up — what should I call you?"
+   - If they give a name, confirm: "Lovely to meet you, [name]!"
    - If they skip, that's fine
-3. **Medications**: "Would you like to set up your regular medications now? This helps me know what you usually take. You can always add more later or skip for now."
-   - If YES: Continue to medication setup
-   - If SKIP: Skip to Doctor setup
-4. **For each medication**:
-   - "What's a medication you take regularly?"
-   - Extract: name, dose, frequency, times of day
-   - "So you take [dose] [name] [frequency] at [times]. Is that right?"
-   - If confirmed, call `setup_medication`
-   - "Do you take any other regular medications?"
-   - If YES: repeat
-   - If NO: proceed to doctor setup
-5. **Doctor Setup**: "Would you like to set up your doctor's email? This lets me send them reports about your headaches and medications."
-   - If YES: "What's your doctor's name?" then "What's their email address?"
-   - Remember both for `complete_onboarding`
-   - If SKIP: That's fine, proceed
-6. **Caregiver Setup**: "Do you have a caregiver or family member you'd like me to keep informed?"
-   - If YES: "What's their name?" then "What's their email?"
-   - Remember both for `complete_onboarding`
+2. **Medications**: "Would you like to set up your regular medications now?"
+   - If YES: For each medication, gather name, dose, frequency, times of day
+   - Confirm each: "Got it — [dose] [name], [frequency]."
+   - Call `setup_medication` with all details, then ask "Any others?"
+   - If SKIP: Proceed to contacts
+3. **Neurologist**: "Would you like to set up your neurologist's details for reports? I'll need their name and email."
+   - If YES: Collect name + email, confirm back
    - If SKIP: That's fine
-7. **Finish**: "All set!" Call `complete_onboarding` with all collected info (name, neurologist_name, neurologist_email, caregiver_name, caregiver_email).
+4. **Caregiver**: "Do you have a caregiver or family member you'd like me to keep informed?"
+   - If YES: Collect name + email, confirm back
+   - If SKIP: That's fine
+5. **Review**: Call `show_onboarding_review` to display all collected data. Say: "Here's everything I've got. Does it all look right?"
+   - If confirmed → proceed to Finish
+   - If changes needed → go back to relevant step
+6. **Finish**: "All set!" Call `complete_onboarding` with all collected info (display_name, neurologist_name, neurologist_email, caregiver_name, caregiver_email).
 
 The user can skip onboarding at any time. If they say "skip" or "later", call `complete_onboarding` immediately with whatever info you have.
 

src/reachy_mini_conversation_app/profiles/_reachy_mini_minder_locked_profile/show_onboarding_review.py

@@ -0,0 +1,124 @@
+"""Tool to display the onboarding review UI before completing setup."""
+
+import logging
+from typing import Any, Dict, Optional
+
+from reachy_mini_conversation_app.tools.core_tools import Tool, ToolDependencies
+from reachy_mini_conversation_app.stream_api import emit_ui_component
+
+
+logger = logging.getLogger(__name__)
+
+
+class ShowOnboardingReview(Tool):
+    """Show a review card with all collected onboarding data for user confirmation."""
+
+    name = "show_onboarding_review"
+    description = (
+        "Display a review card showing all data collected during onboarding "
+        "(name, medications, neurologist, caregiver) so the user can verify "
+        "everything before completing setup. Call this after the contacts step "
+        "and before complete_onboarding. Pass any contact details you have "
+        "collected so they are saved and shown on the review card."
+    )
+    parameters_schema = {
+        "type": "object",
+        "properties": {
+            "neurologist_name": {
+                "type": "string",
+                "description": "Name of the user's neurologist/doctor, if collected",
+            },
+            "neurologist_email": {
+                "type": "string",
+                "description": "Email address of the neurologist, if collected",
+            },
+            "caregiver_name": {
+                "type": "string",
+                "description": "Name of the user's caregiver, if collected",
+            },
+            "caregiver_email": {
+                "type": "string",
+                "description": "Email address of the caregiver, if collected",
+            },
+        },
+        "required": [],
+    }
+
+    async def __call__(
+        self,
+        deps: ToolDependencies,
+        neurologist_name: Optional[str] = None,
+        neurologist_email: Optional[str] = None,
+        caregiver_name: Optional[str] = None,
+        caregiver_email: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Dict[str, Any]:
+        """Persist contact details, gather all onboarding data, and emit review component."""
+        logger.info(
+            "Tool call: show_onboarding_review (neuro=%s, carer=%s)",
+            neurologist_name,
+            caregiver_name,
+        )
+
+        if deps.database is None:
+            return {"error": "Database not initialized"}
+
+        # Persist any contact details passed in so they survive to complete_onboarding
+        updates: Dict[str, Any] = {"onboarding_step": "review"}
+        if neurologist_name:
+            updates["neurologist_name"] = neurologist_name
+        if neurologist_email:
+            updates["neurologist_email"] = neurologist_email
+        if caregiver_name:
+            updates["caregiver_name"] = caregiver_name
+        if caregiver_email:
+            updates["caregiver_email"] = caregiver_email
+        deps.database.update_profile(updates)
+
+        # Re-read profile with persisted data
+        profile = deps.database.get_or_create_profile()
+        display_name = profile.get("display_name")
+        neuro_name = profile.get("neurologist_name")
+        neuro_email = profile.get("neurologist_email")
+        carer_name = profile.get("caregiver_name")
+        carer_email = profile.get("caregiver_email")
+
+        # Gather medications
+        medications = deps.database.get_scheduled_medications()
+        med_list = [
+            {
+                "medicationName": med.get("medication_name", "Unknown"),
+                "dose": med.get("dose"),
+                "frequency": med.get("frequency"),
+            }
+            for med in medications
+        ]
+
+        # Emit the review component
+        await emit_ui_component(
+            "OnboardingReview",
+            {
+                "displayName": display_name,
+                "medications": med_list,
+                "neurologist": {
+                    "name": neuro_name,
+                    "email": neuro_email,
+                },
+                "caregiver": {
+                    "name": carer_name,
+                    "email": carer_email,
+                },
+            },
+        )
+
+        return {
+            "status": "displayed",
+            "display_name": display_name,
+            "medications_count": len(med_list),
+            "neurologist_configured": neuro_name is not None,
+            "caregiver_configured": carer_name is not None,
+            "message": (
+                "Review card shown on screen. Ask the user to confirm "
+                "or tell you what they'd like to change."
+            ),
+        }

src/reachy_mini_conversation_app/profiles/_reachy_mini_minder_locked_profile/show_onboarding_step.py

@@ -12,7 +12,7 @@ from reachy_mini_conversation_app.stream_api import (
 
 logger = logging.getLogger(__name__)
 
-OnboardingStep = Literal["welcome", "name", "medications", "contacts", "complete"]
+OnboardingStep = Literal["name", "medications", "contacts", "review", "complete"]
 
 
 class ShowOnboardingStep(Tool):
@@ -30,10 +30,10 @@ class ShowOnboardingStep(Tool):
         "properties": {
             "current_step": {
                 "type": "string",
-                "enum": ["welcome", "name", "medications", "contacts", "complete"],
+                "enum": ["name", "medications", "contacts", "review", "complete"],
                 "description": (
-                    "The current onboarding step: 'welcome', 'name', 'medications', "
-                    "'contacts', or 'complete'."
+                    "The current onboarding step: 'name', 'medications', "
+                    "'contacts', 'review', or 'complete'."
                 ),
             },
             "display_name": {
@@ -57,7 +57,7 @@ class ShowOnboardingStep(Tool):
         """Emit the OnboardingProgress component."""
         # LLM sometimes sends "step" instead of "current_step"
         if current_step is None:
-            current_step = kwargs.get("step", "welcome")
+            current_step = kwargs.get("step", "name")
         if display_name is None:
             display_name = kwargs.get("name")
         logger.info(

src/reachy_mini_conversation_app/profiles/_reachy_mini_minder_locked_profile/tools.txt

@@ -14,6 +14,7 @@ check_health_patterns
 get_current_datetime
 get_onboarding_status
 show_onboarding_step
+show_onboarding_review
 setup_medication
 get_my_medications
 update_my_medication

src/reachy_mini_conversation_app/prompts/sections/onboarding.txt

@@ -9,8 +9,8 @@ At the very start of each session:
 2. Call `get_onboarding_status` to check if onboarding is complete
 3. If onboarding is NOT complete:
    - Immediately call `show_onboarding_step` with the current step (from get_onboarding_status) to display the GenUI progress tracker
-   - If the step is NOT "welcome", the user has been here before — say "Welcome back! We were setting up your [current step]. Shall we carry on, or would you rather skip for now?"
-   - If the step IS "welcome", follow the full Onboarding Flow below
+   - If the step is NOT "name", the user has been here before — say "Welcome back! We were setting up your [current step]. Shall we carry on, or would you rather skip for now?"
+   - If the step IS "name", follow the full Onboarding Flow below
    - Call `show_onboarding_step` each time you transition to a new step
 4. If onboarding IS complete, greet the user by name if known and switch to normal conversation
 
@@ -18,26 +18,37 @@ At the very start of each session:
 
 **IMPORTANT**: You MUST call `show_onboarding_step` at EVERY step transition to update the on-screen progress tracker. The UI will NOT update unless you call this tool.
 
-### Step 1: Welcome & Name
+### Step 1: Name (Welcome + Name Collection)
 - CALL `show_onboarding_step(current_step="name")`
 - Say: "Hi! I'm Mini-Minder, your care companion. I'll help you track your medications and headaches. Let's get you set up — what should I call you?"
 - Wait for the user's response.
-- When they give a name, remember it. Then proceed to Step 2.
-- If they say "skip", that's fine. Proceed to Step 2.
+- When they give a name, **confirm it back**: "Lovely to meet you, [name]!" Then proceed to Step 2.
+- If they say "skip", that's fine — say "No worries!" and proceed to Step 2.
 
 ### Step 2: Medications
 - CALL `show_onboarding_step(current_step="medications")`
 - Say: "Would you like to set up your regular medications now? You can always add more later."
-- If YES: For each medication, gather ALL details (name, dose, frequency, times of day) through conversation BEFORE calling `setup_medication` once with all the information. Do NOT call `setup_medication` until you have collected all available details for that medication. After confirming, ask "Any others?" and repeat until done.
+- If YES: For each medication, gather ALL details (name, dose, frequency, times of day) through conversation BEFORE calling `setup_medication` once with all the information. Do NOT call `setup_medication` until you have collected all available details for that medication.
+- After each medication is saved, **confirm it back**: "Got it — [dose] [name], [frequency]." Then ask "Any others?" and repeat until done.
 - If NO/SKIP: Proceed to Step 3.
 
 ### Step 3: Contacts
 - CALL `show_onboarding_step(current_step="contacts")`
-- Say: "Would you like to set up your doctor's email for reports?"
-- If YES: Ask for doctor's name and email. Then ask about a caregiver.
-- If NO/SKIP: Ask about caregiver. If skip again, proceed to Step 4.
-
-### Step 4: Complete
+- **Neurologist first**: Say "Would you like to set up your neurologist's details? This lets me send them reports about your headaches and medications. I'll need their name and email address."
+  - If YES: Ask for neurologist's name, then email. **Confirm back**: "Got it — Dr [name] at [email]."
+  - If NO/SKIP: That's fine.
+- **Then caregiver**: Say "Do you have a caregiver or family member you'd like me to keep informed?"
+  - If YES: Ask for their name, then email. **Confirm back**: "Noted — [name] at [email]."
+  - If NO/SKIP: That's fine, proceed to Step 4.
+
+### Step 4: Review
+- CALL `show_onboarding_review` to display a summary of everything collected on screen.
+- Say: "Here's everything I've got. Does it all look right?"
+- Wait for the user to confirm or request changes.
+- If they confirm ("yes", "looks good", "that's right") → proceed to Step 5.
+- If they want to change something → go back to the relevant step and re-collect that data, then return here.
+
+### Step 5: Complete
 - CALL `show_onboarding_step(current_step="complete")`
 - CALL `complete_onboarding` with all collected info (display_name, neurologist_name, neurologist_email, caregiver_name, caregiver_email).
 - Say: "You're all set! I'm ready to help you."

src/reachy_mini_conversation_app/schemas.py

@@ -54,7 +54,7 @@ class OnboardingState(BaseModel):
 
     completed: bool = Field(default=False)
     step: str = Field(
-        default="welcome", description="Current step: welcome, name, medications, done"
+        default="name", description="Current step: name, medications, contacts, done"
     )
     display_name: Optional[str] = None
     medications_count: int = Field(

tests/test_database_onboarding.py

@@ -22,7 +22,7 @@ def test_get_or_create_profile(db: MiniMinderDB) -> None:
     assert profile is not None
     assert profile["id"] == 1
     assert profile["onboarding_completed"] == 0
-    assert profile["onboarding_step"] == "welcome"
+    assert profile["onboarding_step"] == "name"
 
 
 def test_get_or_create_profile_idempotent(db: MiniMinderDB) -> None:

tests/test_onboarding_tools.py

@@ -26,6 +26,9 @@ from reachy_mini_conversation_app.profiles._reachy_mini_minder_locked_profile.up
 from reachy_mini_conversation_app.profiles._reachy_mini_minder_locked_profile.complete_onboarding import (
     CompleteOnboarding,
 )
+from reachy_mini_conversation_app.profiles._reachy_mini_minder_locked_profile.show_onboarding_review import (
+    ShowOnboardingReview,
+)
 
 
 @pytest.fixture
@@ -82,7 +85,7 @@ async def test_get_onboarding_status_initial(deps: ToolDependencies) -> None:
     result = await tool(deps)
 
     assert result["onboarding_completed"] is False
-    assert result["onboarding_step"] == "welcome"
+    assert result["onboarding_step"] == "name"
     assert result["medications_count"] == 0
 
 
@@ -323,6 +326,7 @@ async def test_all_tool_specs() -> None:
         GetMyMedications(),
         UpdateMyMedication(),
         CompleteOnboarding(),
+        ShowOnboardingReview(),
     ]
     for tool in tools:
         spec = tool.spec()
@@ -330,3 +334,55 @@ async def test_all_tool_specs() -> None:
         assert isinstance(spec["name"], str)
         assert isinstance(spec["description"], str)
         assert "parameters" in spec
+
+
+# -----------------------------------------------------------------------------
+# show_onboarding_review Tests
+# -----------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_show_onboarding_review(deps: ToolDependencies) -> None:
+    """Should return all collected data and persist contacts."""
+    # Set up profile name and a medication
+    deps.database.update_profile({"display_name": "Alice"})
+    deps.database.add_scheduled_medication(
+        {"medication_name": "Topiramate", "dose": "50mg", "frequency": "twice daily"}
+    )
+
+    tool = ShowOnboardingReview()
+    result = await tool(
+        deps,
+        neurologist_name="Dr Smith",
+        neurologist_email="dr.smith@nhs.uk",
+        caregiver_name="Bob",
+        caregiver_email="bob@example.com",
+    )
+
+    # Check return values
+    assert result["status"] == "displayed"
+    assert result["display_name"] == "Alice"
+    assert result["medications_count"] == 1
+    assert result["neurologist_configured"] is True
+    assert result["caregiver_configured"] is True
+
+    # Verify contacts persisted to database
+    profile = deps.database.get_or_create_profile()
+    assert profile["neurologist_name"] == "Dr Smith"
+    assert profile["neurologist_email"] == "dr.smith@nhs.uk"
+    assert profile["caregiver_name"] == "Bob"
+    assert profile["caregiver_email"] == "bob@example.com"
+    assert profile["onboarding_step"] == "review"
+
+
+@pytest.mark.asyncio
+async def test_show_onboarding_review_empty(deps: ToolDependencies) -> None:
+    """Should handle review with no data collected (all skipped)."""
+    tool = ShowOnboardingReview()
+    result = await tool(deps)
+
+    assert result["status"] == "displayed"
+    assert result["display_name"] is None
+    assert result["medications_count"] == 0
+    assert result["neurologist_configured"] is False
+    assert result["caregiver_configured"] is False