experiment: chat UX fixes, structured role cards, plan parser improvements

Chat fixes:
- Comment order: sort chronologically (oldest first)
- Reopen+interrupt: user messages reassign task to CEO so it always wakes up
- Strip markdown links from CEO messages to keep user focused on wizard
- Cycling status messages (rotate every 5s) with elapsed timer
- "Review plan" CTA properly disappears when user sends follow-up
- Fetch plan document (not comment summary) for richer role data

Structured role cards:
- 7 fields: Summary, Expertise, Priorities, Boundaries, Tools, Communication, Collaboration
- Collapsible card view with "Show more" / "Show less"
- Full edit mode with labeled textareas per field
- Hire tasks include structured role spec in description

Plan parser:
- Handles "## Role N: Name" format with ### sub-sections
- Handles "### N. Name" format with **Label:** bullets
- Maps CEO's labels (Why→Summary, Responsibilities→Expertise, etc.)
- Skips non-role sections (Summary, Next Steps, Mission, etc.)

Other:
- localStorage persistence for wizard state (survives page refresh)
- Cleaned up step 6 summary (removed redundant company/CEO entries)

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

UX-EXPERIMENTS.md

@@ -0,0 +1,36 @@
+# Onboarding UX Experiments
+
+Tracking file for UX prototyping on the `sockmonster-UX-experimentation` branch.
+
+## Ideas & Feedback
+
+<!-- Add your onboarding feedback and ideas here. We'll update status as we go. -->
+
+| # | Idea | Status | Commit(s) | Notes |
+|---|------|--------|-----------|-------|
+| 1 | Mission mandatory + two paths | Done | a35fac7 | Questionnaire + direct input, prompt chips |
+| 2 | Launch celebration (step 2) | Done | a35fac7 | "Company is live!" moment after mission |
+| 3 | CEO creation reframed | Done | a35fac7 | "Bring your CEO to life" / "give it a heartbeat" |
+| 4 | Chat with CEO | Done | b4ef061 | OnboardingChat polls comments, detects plans |
+| 5 | Hiring plan review | Done | b60fcd8 | Editable role cards, add/edit/remove, revise with CEO |
+| 6 | Make your first hires | Done | b60fcd8 | Creates hire tasks per approved role |
+| 7 | Chat comment order fix | Done | pending | Sort chronologically (oldest first) |
+| 8 | Chat reopen/interrupt fix | Done | pending | User comments reopen + interrupt so CEO wakes up |
+| 9 | Rich heartbeat status in chat | Done | — | Cycling status messages with elapsed timer |
+| 10 | Merge steps 5+6, add guided tour | Todo | — | Remove redundant confirm step, add post-wizard orientation |
+| 11 | Re-invokable guided tour | Todo | — | User can re-trigger tour from settings or help menu |
+| 12 | Persistent CEO chat in dashboard | Future | — | Long-term: CEO chat as command center, drives toward tasks/goals/projects |
+
+## Experiment Log
+
+### 2026-03-17: Initial 6-step wizard prototype
+
+Rewrote the onboarding wizard from 4 steps to 6 steps:
+1. Define mission (required) — two paths: direct or questionnaire
+2. Launch celebration — "Your company is live!"
+3. Create CEO — reframed as "bring to life" / heartbeat
+4. Chat with CEO — placeholder (needs OnboardingChat)
+5. Review hiring plan — placeholder (needs editable cards)
+6. Make first hires — placeholder (needs task creation logic)
+
+Steps 1-3 are functional. Steps 4-6 have placeholder UI.

ui/src/components/OnboardingChat.tsx

@@ -1,17 +1,20 @@
-import { useState, useRef, useEffect, useCallback } from "react";
+import { useState, useRef, useEffect, useCallback, useMemo } from "react";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
 import type { IssueComment } from "@paperclipai/shared";
 import { issuesApi } from "../api/issues";
+import { heartbeatsApi } from "../api/heartbeats";
 import { queryKeys } from "../lib/queryKeys";
 import { Button } from "@/components/ui/button";
 import { MarkdownBody } from "./MarkdownBody";
 import { cn } from "../lib/utils";
-import { Loader2, Send, CheckCircle2 } from "lucide-react";
+import { Loader2, Send, CheckCircle2, ArrowRight } from "lucide-react";
 
 interface OnboardingChatProps {
   taskId: string;
+  agentId: string;
   agentName: string;
   onPlanDetected?: (planMarkdown: string) => void;
+  onReviewPlan?: () => void;
 }
 
 /**
@@ -28,10 +31,58 @@ function detectHiringPlan(body: string): boolean {
   return planPatterns.some((pattern) => pattern.test(body));
 }
 
+const QUEUED_MESSAGES = [
+  "Heartbeat triggered, waking up...",
+  "Initializing...",
+  "Getting ready...",
+];
+
+const RUNNING_MESSAGES = [
+  "Working on a response...",
+  "Reading the conversation...",
+  "Thinking through the plan...",
+  "Drafting a response...",
+  "Still working...",
+  "Almost there...",
+];
+
+const WAITING_MESSAGES = [
+  "Waiting to wake up...",
+  "Heartbeat pending...",
+  "Should wake up soon...",
+];
+
+function getCyclingMessage(messages: string[], elapsed: number, agentName: string): string {
+  // Cycle through messages every 5 seconds
+  const idx = Math.floor(elapsed / 5) % messages.length;
+  return `${agentName} · ${messages[idx]}`;
+}
+
+function getRunStatusMessage(status: string, agentName: string, elapsed: number): string {
+  switch (status) {
+    case "queued":
+      return getCyclingMessage(QUEUED_MESSAGES, elapsed, agentName);
+    case "running":
+      return getCyclingMessage(RUNNING_MESSAGES, elapsed, agentName);
+    case "succeeded":
+      return `${agentName} finished`;
+    case "failed":
+      return `${agentName} encountered an error`;
+    case "cancelled":
+      return `${agentName}'s run was cancelled`;
+    case "timed_out":
+      return `${agentName}'s run timed out`;
+    default:
+      return `${agentName} is thinking...`;
+  }
+}
+
 export function OnboardingChat({
   taskId,
+  agentId,
   agentName,
   onPlanDetected,
+  onReviewPlan,
 }: OnboardingChatProps) {
   const queryClient = useQueryClient();
   const [input, setInput] = useState("");
@@ -39,11 +90,16 @@ export function OnboardingChat({
   const [detectedPlanCommentId, setDetectedPlanCommentId] = useState<
     string | null
   >(null);
+  // Track the comment ID after which we should ignore old plan detections
+  // (set when user sends a new message to request revisions)
+  const [ignoreBeforeCommentId, setIgnoreBeforeCommentId] = useState<
+    string | null
+  >(null);
   const scrollRef = useRef<HTMLDivElement>(null);
   const inputRef = useRef<HTMLTextAreaElement>(null);
 
   const {
-    data: comments,
+    data: rawComments,
     isLoading,
   } = useQuery({
     queryKey: queryKeys.issues.comments(taskId),
@@ -51,6 +107,25 @@ export function OnboardingChat({
     refetchInterval: 4000,
   });
 
+  // Poll for active heartbeat run on this task
+  const { data: activeRun } = useQuery({
+    queryKey: queryKeys.issues.activeRun(taskId),
+    queryFn: () => heartbeatsApi.activeRunForIssue(taskId),
+    refetchInterval: 3000,
+  });
+
+  // Sort comments chronologically (oldest first) for chat-style display
+  const comments = useMemo(
+    () =>
+      rawComments
+        ? [...rawComments].sort(
+            (a, b) =>
+              new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime(),
+          )
+        : undefined,
+    [rawComments],
+  );
+
   // Auto-scroll to bottom when new comments arrive
   useEffect(() => {
     if (scrollRef.current) {
@@ -58,27 +133,64 @@ export function OnboardingChat({
     }
   }, [comments?.length]);
 
-  // Detect hiring plan in agent comments
+  // Detect hiring plan in agent comments.
+  // Only considers agent comments newer than the user's last message AND
+  // newer than any "ignore" marker (set when user asks for revisions).
   useEffect(() => {
     if (!comments || !onPlanDetected || detectedPlanCommentId) return;
-    // Scan from newest to oldest for a plan-like comment from the agent
+
+    // Find the cutoff — the later of the user's last message or the ignore marker
+    let cutoffIdx = -1;
     for (let i = comments.length - 1; i >= 0; i--) {
+      if (comments[i].authorUserId) { cutoffIdx = i; break; }
+    }
+    if (ignoreBeforeCommentId) {
+      const ignoreIdx = comments.findIndex((c) => c.id === ignoreBeforeCommentId);
+      if (ignoreIdx >= 0) cutoffIdx = Math.max(cutoffIdx, ignoreIdx);
+    }
+
+    // Only scan agent comments after the cutoff
+    for (let i = comments.length - 1; i > cutoffIdx; i--) {
       const c = comments[i];
       if (c.authorAgentId && detectHiringPlan(c.body)) {
         setDetectedPlanCommentId(c.id);
-        onPlanDetected(c.body);
+        // Fetch the full plan document — it has richer role descriptions
+        issuesApi.getDocument(taskId, "plan").then((doc) => {
+          onPlanDetected(doc.body ?? c.body);
+        }).catch(() => {
+          onPlanDetected(c.body);
+        });
         break;
       }
     }
-  }, [comments, onPlanDetected, detectedPlanCommentId]);
+  }, [comments, onPlanDetected, detectedPlanCommentId, ignoreBeforeCommentId, taskId]);
 
   const handleSend = useCallback(async () => {
     const body = input.trim();
     if (!body || sending) return;
     setSending(true);
     try {
-      await issuesApi.addComment(taskId, body);
+      // Ensure the task is assigned to the CEO and in_progress before commenting.
+      // The CEO tends to unassign itself and set status to in_review after responding,
+      // which prevents the comment wakeup from working.
+      try {
+        await issuesApi.update(taskId, { assigneeUserId: null });
+      } catch { /* may already be null */ }
+      try {
+        await issuesApi.update(taskId, {
+          assigneeAgentId: agentId,
+          status: "in_progress",
+        });
+      } catch { /* may already be assigned */ }
+
+      await issuesApi.addComment(taskId, body, true, true);
       setInput("");
+      // Clear detected plan — user is asking for revisions, so the old plan
+      // is stale. A new plan will be detected when the CEO responds again.
+      // Mark the last known comment so the detector ignores older plans.
+      const latestId = comments?.[comments.length - 1]?.id ?? null;
+      setIgnoreBeforeCommentId(latestId);
+      setDetectedPlanCommentId(null);
       queryClient.invalidateQueries({
         queryKey: queryKeys.issues.comments(taskId),
       });
@@ -98,9 +210,36 @@ export function OnboardingChat({
     [handleSend],
   );
 
+  // Determine if we should show a status indicator
   const lastComment = comments?.[comments.length - 1];
   const isWaitingForAgent =
     lastComment && lastComment.authorUserId && !lastComment.authorAgentId;
+  const hasActiveRun = activeRun && (activeRun.status === "queued" || activeRun.status === "running");
+  const showStatus = isWaitingForAgent || hasActiveRun;
+
+  // Elapsed timer — ticks every second while waiting
+  const [elapsed, setElapsed] = useState(0);
+  const waitingSince = useMemo(() => {
+    if (!showStatus || !lastComment) return null;
+    // Use the user's last message timestamp as the start time
+    if (lastComment.authorUserId) return new Date(lastComment.createdAt).getTime();
+    // If an active run exists, use its creation time
+    if (hasActiveRun && activeRun.createdAt) return new Date(activeRun.createdAt).getTime();
+    return null;
+  }, [showStatus, lastComment, hasActiveRun, activeRun]);
+
+  useEffect(() => {
+    if (!waitingSince) { setElapsed(0); return; }
+    setElapsed(Math.floor((Date.now() - waitingSince) / 1000));
+    const interval = setInterval(() => {
+      setElapsed(Math.floor((Date.now() - waitingSince) / 1000));
+    }, 1000);
+    return () => clearInterval(interval);
+  }, [waitingSince]);
+
+  const elapsedStr = elapsed >= 60
+    ? `${Math.floor(elapsed / 60)}m ${elapsed % 60}s`
+    : `${elapsed}s`;
 
   if (isLoading) {
     return (
@@ -156,32 +295,76 @@ export function OnboardingChat({
                 )}
               </div>
               <div className="prose prose-sm dark:prose-invert max-w-none [&>*:first-child]:mt-0 [&>*:last-child]:mb-0">
-                <MarkdownBody>{comment.body}</MarkdownBody>
+                <MarkdownBody>
+                  {isAgent
+                    ? comment.body.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+                    : comment.body}
+                </MarkdownBody>
               </div>
             </div>
           );
         })}
 
-        {/* Thinking indicator */}
+        {/* Status indicator — shows real heartbeat run status */}
-        {isWaitingForAgent && (
+        {showStatus && (
-          <div className="flex items-center gap-2 text-sm text-muted-foreground px-3 py-2">
+          <div className="flex items-center justify-between text-sm text-muted-foreground px-3 py-2">
-            <Loader2 className="h-3.5 w-3.5 animate-spin" />
+            <div className="flex items-center gap-2">
-            {agentName} is thinking...
+              {hasActiveRun ? (
+                <>
+                  <span className="relative flex h-2.5 w-2.5 shrink-0">
+                    <span className="animate-ping absolute inline-flex h-full w-full rounded-full bg-cyan-400 opacity-75" />
+                    <span className="relative inline-flex rounded-full h-2.5 w-2.5 bg-cyan-500" />
+                  </span>
+                  {getRunStatusMessage(activeRun.status, agentName, elapsed)}
+                </>
+              ) : (
+                <>
+                  <Loader2 className="h-3.5 w-3.5 animate-spin shrink-0" />
+                  {getCyclingMessage(WAITING_MESSAGES, elapsed, agentName)}
+                </>
+              )}
+            </div>
+            <span className="text-[11px] text-muted-foreground/60 tabular-nums shrink-0">
+              {elapsedStr}
+            </span>
           </div>
         )}
       </div>
 
+      {/* Plan ready CTA */}
+      {detectedPlanCommentId && onReviewPlan && (
+        <div className="rounded-md border border-green-500/30 bg-green-500/5 px-3 py-3 mb-3">
+          <div className="flex items-center justify-between gap-3">
+            <div className="flex items-center gap-2">
+              <CheckCircle2 className="h-4 w-4 text-green-500 shrink-0" />
+              <div>
+                <p className="text-sm font-medium">
+                  Your CEO has prepared a hiring plan
+                </p>
+                <p className="text-[11px] text-muted-foreground">
+                  Review it, make edits, then approve.
+                </p>
+              </div>
+            </div>
+            <Button size="sm" onClick={onReviewPlan}>
+              Review plan
+              <ArrowRight className="h-3.5 w-3.5 ml-1" />
+            </Button>
+          </div>
+        </div>
+      )}
+
       {/* Input area */}
       <div className="flex items-end gap-2 border-t border-border pt-3">
         <textarea
           ref={inputRef}
           className="flex-1 rounded-md border border-border bg-transparent px-3 py-2 text-sm outline-none focus:ring-1 focus:ring-ring placeholder:text-muted-foreground/50 resize-none min-h-[40px] max-h-[100px]"
-          placeholder="Message your CEO..."
+          placeholder={detectedPlanCommentId ? "Ask your CEO to revise the plan, or review it above..." : "Message your CEO..."}
           value={input}
           onChange={(e) => setInput(e.target.value)}
           onKeyDown={handleKeyDown}
           rows={1}
-          autoFocus
+          autoFocus={!detectedPlanCommentId}
         />
         <Button
           size="sm"
@@ -196,16 +379,6 @@ export function OnboardingChat({
           )}
         </Button>
       </div>
-
-      {/* Manual plan selection */}
-      {!detectedPlanCommentId &&
-        comments &&
-        comments.some((c) => c.authorAgentId) && (
-          <p className="text-[10px] text-muted-foreground mt-2">
-            If the CEO has proposed a plan, click "Next" once you're satisfied,
-            or keep chatting to refine it.
-          </p>
-        )}
     </div>
   );
 }

ui/src/components/OnboardingWizard.tsx

@@ -88,39 +88,168 @@ function buildMissionFromQuestionnaire(q1: string, q2: string, q3: string, q4: s
 interface HiringRole {
   id: string;
   name: string;
-  description: string;
+  summary: string;
+  expertise: string;
+  priorities: string;
+  boundaries: string;
+  tools: string;
+  communication: string;
+  collaboration: string;
   enabled: boolean;
   editing: boolean;
 }
 
-let roleIdCounter = 0;
 function nextRoleId(): string {
-  return `role-${++roleIdCounter}`;
+  return crypto.randomUUID();
+}
+
+const EMPTY_ROLE: Omit<HiringRole, "id"> = {
+  name: "", summary: "", expertise: "", priorities: "",
+  boundaries: "", tools: "", communication: "", collaboration: "",
+  enabled: true, editing: true,
+};
+
+function cleanMd(s: string): string {
+  return s
+    .replace(/\*\*([^*]+)\*\*/g, "$1")
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+    .replace(/^\s*[-*]\s+/, "")
+    .trim();
+}
+
+/**
+ * Map a bullet label (e.g. "Why:", "Responsibilities:") to a structured field.
+ */
+function classifyBullet(label: string): keyof HiringRole | null {
+  const l = label.toLowerCase();
+  if (/^why|^purpose|^overview/.test(l)) return "summary";
+  if (/^responsibilit|^expertise|^duties|^scope|^what they do/.test(l)) return "expertise";
+  if (/^priorit|^focus|^goals|^kpi|^metric/.test(l)) return "priorities";
+  if (/^boundar|^limit|^should not|^don.?t|^avoid|^out of scope/.test(l)) return "boundaries";
+  if (/^tool|^permission|^access|^tech|^stack/.test(l)) return "tools";
+  if (/^communic|^tone|^style|^voice/.test(l)) return "communication";
+  if (/^collaborat|^escalat|^report|^works with|^interact|^coordinat/.test(l)) return "collaboration";
+  if (/^recommend|^profile|^ideal|^skills|^qualif/.test(l)) return "expertise";
+  return null;
 }
 
 /**
  * Parse a markdown hiring plan into structured roles.
- * Looks for bullet points with bold role names: "- **Role Name**: description"
+ * Handles two document formats:
- * Falls back to any bold text in bullet points.
+ *   Format A: "## Role N: Name" with ### sub-sections (Priorities, Boundaries, etc.)
+ *   Format B: "### N. Name" with **Label:** bullets
+ * Fallback: comment-style bullet/table patterns.
  */
 function parseHiringPlan(markdown: string): HiringRole[] {
   const roles: HiringRole[] = [];
-  const lines = markdown.split("\n");
+  const seen = new Set<string>();
-  for (const line of lines) {
+
-    // Match "- **Role Name**: description" or "- **Role Name** - description"
+  // Split into ## sections (each role is a ## heading)
-    const match = line.match(
+  const roleSections = markdown.split(/^##\s+/m).slice(1).filter(Boolean);
-      /^\s*[-*]\s+\*\*([^*]+)\*\*[:\s-]*(.*)$/
+
-    );
+  for (const section of roleSections) {
-    if (match) {
+    const lines = section.split("\n");
+    const titleLine = lines[0]?.trim() ?? "";
+
+    // Extract role name — match "Role N: Name" or just "N. Name" or plain name
+    let name = titleLine
+      .replace(/^role\s*\d*[:.]\s*/i, "")
+      .replace(/^\d+[.)]\s*/, "")
+      .replace(/\*\*/g, "")
+      .trim();
+
+    // Skip non-role sections
+    const skipPatterns = /^(mission|hiring approach|hiring|roles|approach|open|phase|deferred|timeline|budget|summary|next steps|overview|notes|questions|appendix|---)/i;
+    if (skipPatterns.test(name) || name.length < 3) continue;
+    if (seen.has(name.toLowerCase())) continue;
+
+    // Parse content: **Label:** bullets and ### sub-sections
+    const fields: Record<string, string[]> = {};
+    let currentField: string | null = null;
+
+    for (let i = 1; i < lines.length; i++) {
+      const raw = lines[i];
+      const trimmed = raw.trim();
+      if (!trimmed) continue;
+
+      // ### sub-section heading (e.g. "### Priorities")
+      const subHeadingMatch = trimmed.match(/^###\s+(.+)/);
+      if (subHeadingMatch) {
+        const label = subHeadingMatch[1].trim();
+        const field = classifyBullet(label);
+        currentField = (field && field !== "id" && field !== "name" && field !== "enabled" && field !== "editing")
+          ? field : "expertise";
+        continue;
+      }
+
+      // **Label:** inline (e.g. "**Why:** text")
+      const boldLabelMatch = trimmed.match(/^\*\*([^*:]+)[*:]*\*\*[:\s]*(.*)/);
+      const bulletLabelMatch = !boldLabelMatch && trimmed.match(/^\s*[-*]\s+\*\*([^*:]+)[*:]*\*\*[:\s]*(.*)/);
+      const labelMatch = boldLabelMatch ?? bulletLabelMatch;
+
+      if (labelMatch) {
+        const label = labelMatch[1]!.trim();
+        const value = cleanMd(labelMatch[2] ?? "");
+        const field = classifyBullet(label);
+        currentField = (field && field !== "id" && field !== "name" && field !== "enabled" && field !== "editing")
+          ? field : "expertise";
+        if (!fields[currentField]) fields[currentField] = [];
+        if (value) fields[currentField].push(value);
+        continue;
+      }
+
+      // Regular content line under current field
+      if (currentField) {
+        const cleaned = cleanMd(trimmed);
+        if (cleaned) {
+          if (!fields[currentField]) fields[currentField] = [];
+          fields[currentField].push(cleaned);
+        }
+      }
+    }
+
+    const join = (arr?: string[]) => (arr ?? []).join("\n");
+
+    seen.add(name.toLowerCase());
+    roles.push({
+      id: nextRoleId(),
+      name,
+      summary: join(fields.summary),
+      expertise: join(fields.expertise),
+      priorities: join(fields.priorities),
+      boundaries: join(fields.boundaries),
+      tools: join(fields.tools),
+      communication: join(fields.communication),
+      collaboration: join(fields.collaboration),
+      enabled: true,
+      editing: false,
+    });
+  }
+
+  // Fallback: simple bullet parsing from comment text
+  if (roles.length === 0) {
+    const lines = markdown.split("\n");
+    for (const line of lines) {
+      const bulletMatch = line.match(
+        /^\s*(?:[-*]|\d+[.)]\s*)\s*\*\*([^*]+)\*\*[:\s—–-]*(.*)$/
+      );
+      if (!bulletMatch) continue;
+      const name = bulletMatch[1].trim();
+      const summary = cleanMd(bulletMatch[2]);
+      if (seen.has(name.toLowerCase())) continue;
+      const skip = /^(phase|month|step|update|note|question|summary|timeline|priority|plan|total|budget|immediate|hire|\d+ immediate)/i;
+      if (skip.test(name) || name.length < 3) continue;
+
+      seen.add(name.toLowerCase());
       roles.push({
-        id: nextRoleId(),
+        id: nextRoleId(), name, summary,
-        name: match[1].trim(),
+        expertise: "", priorities: "", boundaries: "",
-        description: match[2].trim(),
+        tools: "", communication: "", collaboration: "",
-        enabled: true,
+        enabled: true, editing: false,
-        editing: false,
       });
     }
   }
+
   return roles;
 }
 
@@ -132,6 +261,17 @@ Ensure you have a folder agents/ceo and then download this AGENTS.md, and siblin
 
 After that, hire yourself a Founding Engineer agent and then plan the roadmap and tasks for your new company.`;
 
+const ONBOARDING_STORAGE_KEY = "paperclip-onboarding-state";
+
+function loadSavedState(): Record<string, unknown> | null {
+  try {
+    const raw = localStorage.getItem(ONBOARDING_STORAGE_KEY);
+    return raw ? JSON.parse(raw) : null;
+  } catch {
+    return null;
+  }
+}
+
 export function OnboardingWizard() {
   const { onboardingOpen, onboardingOptions, closeOnboarding } = useDialog();
   const { selectedCompanyId, companies, setSelectedCompanyId } = useCompany();
@@ -141,31 +281,34 @@ export function OnboardingWizard() {
   const initialStep = onboardingOptions.initialStep ?? 1;
   const existingCompanyId = onboardingOptions.companyId;
 
-  const [step, setStep] = useState<Step>(initialStep);
+  // Restore saved state from localStorage (read once on mount)
+  const saved = useMemo(loadSavedState, []);
+
+  const [step, setStep] = useState<Step>((saved?.step as Step) ?? initialStep);
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const [modelOpen, setModelOpen] = useState(false);
   const [modelSearch, setModelSearch] = useState("");
 
   // Step 1
-  const [companyName, setCompanyName] = useState("");
+  const [companyName, setCompanyName] = useState((saved?.companyName as string) ?? "");
-  const [companyGoal, setCompanyGoal] = useState("");
+  const [companyGoal, setCompanyGoal] = useState((saved?.companyGoal as string) ?? "");
-  const [missionPath, setMissionPath] = useState<"direct" | "questionnaire" | null>(null);
+  const [missionPath, setMissionPath] = useState<"direct" | "questionnaire" | null>((saved?.missionPath as "direct" | "questionnaire" | null) ?? null);
-  const [missionConfirmed, setMissionConfirmed] = useState(false);
+  const [missionConfirmed, setMissionConfirmed] = useState((saved?.missionConfirmed as boolean) ?? false);
   // Questionnaire answers
-  const [q1, setQ1] = useState(""); // What do you do?
+  const [q1, setQ1] = useState((saved?.q1 as string) ?? ""); // What do you do?
-  const [q2, setQ2] = useState(""); // Who do you serve?
+  const [q2, setQ2] = useState((saved?.q2 as string) ?? ""); // Who do you serve?
-  const [q3, setQ3] = useState(""); // Biggest bottleneck?
+  const [q3, setQ3] = useState((saved?.q3 as string) ?? ""); // Biggest bottleneck?
-  const [q4, setQ4] = useState(""); // What would success look like?
+  const [q4, setQ4] = useState((saved?.q4 as string) ?? ""); // What would success look like?
 
   // Step 2
-  const [agentName, setAgentName] = useState("CEO");
+  const [agentName, setAgentName] = useState((saved?.agentName as string) ?? "CEO");
-  const [adapterType, setAdapterType] = useState<AdapterType>("claude_local");
+  const [adapterType, setAdapterType] = useState<AdapterType>((saved?.adapterType as AdapterType) ?? "claude_local");
-  const [cwd, setCwd] = useState("");
+  const [cwd, setCwd] = useState((saved?.cwd as string) ?? "");
-  const [model, setModel] = useState("");
+  const [model, setModel] = useState((saved?.model as string) ?? "");
-  const [command, setCommand] = useState("");
+  const [command, setCommand] = useState((saved?.command as string) ?? "");
-  const [args, setArgs] = useState("");
+  const [args, setArgs] = useState((saved?.args as string) ?? "");
-  const [url, setUrl] = useState("");
+  const [url, setUrl] = useState((saved?.url as string) ?? "");
   const [adapterEnvResult, setAdapterEnvResult] =
     useState<AdapterEnvironmentTestResult | null>(null);
   const [adapterEnvError, setAdapterEnvError] = useState<string | null>(null);
@@ -191,30 +334,33 @@ export function OnboardingWizard() {
   }, []);
 
   // Planning task + hiring plan
-  const [planningTaskId, setPlanningTaskId] = useState<string | null>(null);
+  const [planningTaskId, setPlanningTaskId] = useState<string | null>((saved?.planningTaskId as string) ?? null);
-  const [planContent, setPlanContent] = useState<string | null>(null);
+  const [planContent, setPlanContent] = useState<string | null>((saved?.planContent as string) ?? null);
-  const [hiringRoles, setHiringRoles] = useState<HiringRole[]>([]);
+  const [hiringRoles, setHiringRoles] = useState<HiringRole[]>((saved?.hiringRoles as HiringRole[]) ?? []);
   const [showRawPlan, setShowRawPlan] = useState(false);
 
   // Created entity IDs — pre-populate from existing company when skipping step 1
   const [createdCompanyId, setCreatedCompanyId] = useState<string | null>(
-    existingCompanyId ?? null
+    existingCompanyId ?? (saved?.createdCompanyId as string) ?? null
   );
   const [createdCompanyPrefix, setCreatedCompanyPrefix] = useState<
     string | null
-  >(null);
+  >((saved?.createdCompanyPrefix as string) ?? null);
-  const [createdAgentId, setCreatedAgentId] = useState<string | null>(null);
+  const [createdAgentId, setCreatedAgentId] = useState<string | null>((saved?.createdAgentId as string) ?? null);
   const [createdIssueRef, setCreatedIssueRef] = useState<string | null>(null);
 
-  // Sync step and company when onboarding opens with options.
+  // Sync step and company when onboarding opens with explicit options.
-  // Keep this independent from company-list refreshes so Step 1 completion
+  // Only override saved state when onboardingOptions explicitly provides values.
-  // doesn't get reset after creating a company.
   useEffect(() => {
     if (!onboardingOpen) return;
-    const cId = onboardingOptions.companyId ?? null;
+    // If explicit options are provided, they take precedence over saved state
-    setStep(onboardingOptions.initialStep ?? 1);
+    if (onboardingOptions.initialStep) {
-    setCreatedCompanyId(cId);
+      setStep(onboardingOptions.initialStep);
-    setCreatedCompanyPrefix(null);
+    }
+    if (onboardingOptions.companyId) {
+      setCreatedCompanyId(onboardingOptions.companyId);
+      setCreatedCompanyPrefix(null);
+    }
   }, [
     onboardingOpen,
     onboardingOptions.companyId,
@@ -228,6 +374,23 @@ export function OnboardingWizard() {
     if (company) setCreatedCompanyPrefix(company.issuePrefix);
   }, [onboardingOpen, createdCompanyId, createdCompanyPrefix, companies]);
 
+  // Persist wizard state to localStorage on every change
+  useEffect(() => {
+    if (!onboardingOpen) return;
+    const state = {
+      step, companyName, companyGoal, missionPath, missionConfirmed,
+      q1, q2, q3, q4, agentName, adapterType, cwd, model, command, args, url,
+      createdCompanyId, createdCompanyPrefix, createdAgentId,
+      planningTaskId, planContent, hiringRoles,
+    };
+    localStorage.setItem(ONBOARDING_STORAGE_KEY, JSON.stringify(state));
+  }, [
+    onboardingOpen, step, companyName, companyGoal, missionPath, missionConfirmed,
+    q1, q2, q3, q4, agentName, adapterType, cwd, model, command, args, url,
+    createdCompanyId, createdCompanyPrefix, createdAgentId,
+    planningTaskId, planContent, hiringRoles,
+  ]);
+
   // Resize textarea when step 3 is shown or description changes
   useEffect(() => {
     // Auto-resize removed — task description textarea no longer used in onboarding
@@ -316,6 +479,7 @@ export function OnboardingWizard() {
   }, [filteredModels, adapterType]);
 
   function reset() {
+    localStorage.removeItem(ONBOARDING_STORAGE_KEY);
     setStep(1);
     setLoading(false);
     setError(null);
@@ -603,11 +767,18 @@ export function OnboardingWizard() {
         (r) => r.enabled && r.name.trim()
       );
       for (const role of approvedRoles) {
+        const roleSpec = [
+          role.summary && `**Summary:** ${role.summary}`,
+          role.expertise && `**Expertise & Responsibilities:**\n${role.expertise}`,
+          role.priorities && `**Priorities:**\n${role.priorities}`,
+          role.boundaries && `**Boundaries:**\n${role.boundaries}`,
+          role.tools && `**Tools & Permissions:**\n${role.tools}`,
+          role.communication && `**Communication:**\n${role.communication}`,
+          role.collaboration && `**Collaboration:**\n${role.collaboration}`,
+        ].filter(Boolean).join("\n\n");
         await issuesApi.create(createdCompanyId, {
           title: `Hire: ${role.name}`,
-          description: role.description
+          description: `Hire a ${role.name} for the company.\n\n${roleSpec}`,
-            ? `Hire a ${role.name} for the company.\n\n${role.description}`
-            : `Hire a ${role.name} for the company.`,
           assigneeAgentId: createdAgentId,
           status: "todo"
         });
@@ -1430,8 +1601,26 @@ export function OnboardingWizard() {
                   {planningTaskId ? (
                     <OnboardingChat
                       taskId={planningTaskId}
+                      agentId={createdAgentId!}
                       agentName={agentName}
                       onPlanDetected={(md) => setPlanContent(md)}
+                      onReviewPlan={async () => {
+                        // Always fetch the latest plan document for the richest content
+                        try {
+                          const doc = await issuesApi.getDocument(planningTaskId!, "plan");
+                          if (doc.body) {
+                            setPlanContent(doc.body);
+                            setHiringRoles(parseHiringPlan(doc.body));
+                          } else if (planContent) {
+                            setHiringRoles(parseHiringPlan(planContent));
+                          }
+                        } catch {
+                          if (planContent) {
+                            setHiringRoles(parseHiringPlan(planContent));
+                          }
+                        }
+                        setStep(5);
+                      }}
                     />
                   ) : (
                     <div className="rounded-md border border-border p-4 min-h-[200px] flex items-center justify-center">
@@ -1468,15 +1657,7 @@ export function OnboardingWizard() {
                         variant="outline"
                         size="sm"
                         onClick={() =>
-                          setHiringRoles([
+                          setHiringRoles([{ ...EMPTY_ROLE, id: nextRoleId() }])
-                            {
-                              id: nextRoleId(),
-                              name: "",
-                              description: "",
-                              enabled: true,
-                              editing: true,
-                            },
-                          ])
                         }
                       >
                         <Plus className="h-3.5 w-3.5 mr-1" />
@@ -1484,120 +1665,22 @@ export function OnboardingWizard() {
                       </Button>
                     </div>
                   ) : (
-                    <div className="space-y-2">
+                    <div className="space-y-3">
                       {hiringRoles.map((role) => (
-                        <div
+                        <RoleCard
                           key={role.id}
-                          className={cn(
+                          role={role}
-                            "rounded-md border px-3 py-2.5 transition-colors",
+                          onChange={(updated) =>
-                            role.enabled
+                            setHiringRoles((prev) =>
-                              ? "border-border bg-background"
+                              prev.map((r) => (r.id === role.id ? updated : r))
-                              : "border-border/50 bg-muted/30 opacity-60"
+                            )
-                          )}
+                          }
-                        >
+                          onDelete={() =>
-                          {role.editing ? (
+                            setHiringRoles((prev) =>
-                            <div className="space-y-2">
+                              prev.filter((r) => r.id !== role.id)
-                              <input
+                            )
-                                className="w-full rounded border border-border bg-transparent px-2 py-1 text-sm font-medium outline-none focus:ring-1 focus:ring-ring"
+                          }
-                                placeholder="Role name"
+                        />
-                                value={role.name}
-                                onChange={(e) =>
-                                  setHiringRoles((prev) =>
-                                    prev.map((r) =>
-                                      r.id === role.id
-                                        ? { ...r, name: e.target.value }
-                                        : r
-                                    )
-                                  )
-                                }
-                                autoFocus
-                              />
-                              <textarea
-                                className="w-full rounded border border-border bg-transparent px-2 py-1 text-sm outline-none focus:ring-1 focus:ring-ring resize-none min-h-[40px]"
-                                placeholder="Role description"
-                                value={role.description}
-                                onChange={(e) =>
-                                  setHiringRoles((prev) =>
-                                    prev.map((r) =>
-                                      r.id === role.id
-                                        ? { ...r, description: e.target.value }
-                                        : r
-                                    )
-                                  )
-                                }
-                              />
-                              <Button
-                                size="sm"
-                                variant="outline"
-                                onClick={() =>
-                                  setHiringRoles((prev) =>
-                                    prev.map((r) =>
-                                      r.id === role.id
-                                        ? { ...r, editing: false }
-                                        : r
-                                    )
-                                  )
-                                }
-                              >
-                                <Check className="h-3 w-3 mr-1" />
-                                Done
-                              </Button>
-                            </div>
-                          ) : (
-                            <div className="flex items-start gap-2.5">
-                              <input
-                                type="checkbox"
-                                checked={role.enabled}
-                                onChange={(e) =>
-                                  setHiringRoles((prev) =>
-                                    prev.map((r) =>
-                                      r.id === role.id
-                                        ? { ...r, enabled: e.target.checked }
-                                        : r
-                                    )
-                                  )
-                                }
-                                className="mt-1 shrink-0"
-                              />
-                              <div className="flex-1 min-w-0">
-                                <p className="text-sm font-medium">
-                                  {role.name || "Untitled role"}
-                                </p>
-                                {role.description && (
-                                  <p className="text-xs text-muted-foreground mt-0.5">
-                                    {role.description}
-                                  </p>
-                                )}
-                              </div>
-                              <div className="flex items-center gap-1 shrink-0">
-                                <button
-                                  className="p-1 text-muted-foreground hover:text-foreground transition-colors"
-                                  onClick={() =>
-                                    setHiringRoles((prev) =>
-                                      prev.map((r) =>
-                                        r.id === role.id
-                                          ? { ...r, editing: true }
-                                          : r
-                                      )
-                                    )
-                                  }
-                                >
-                                  <Pencil className="h-3 w-3" />
-                                </button>
-                                <button
-                                  className="p-1 text-muted-foreground hover:text-destructive transition-colors"
-                                  onClick={() =>
-                                    setHiringRoles((prev) =>
-                                      prev.filter((r) => r.id !== role.id)
-                                    )
-                                  }
-                                >
-                                  <Trash2 className="h-3 w-3" />
-                                </button>
-                              </div>
-                            </div>
-                          )}
-                        </div>
                       ))}
                     </div>
                   )}
@@ -1609,13 +1692,7 @@ export function OnboardingWizard() {
                     onClick={() =>
                       setHiringRoles((prev) => [
                         ...prev,
-                        {
+                        { ...EMPTY_ROLE, id: nextRoleId() },
-                          id: nextRoleId(),
-                          name: "",
-                          description: "",
-                          enabled: true,
-                          editing: true,
-                        },
                       ])
                     }
                   >
@@ -1674,31 +1751,7 @@ export function OnboardingWizard() {
                       </p>
                     </div>
                   </div>
-                  <div className="border border-border divide-y divide-border">
+                  <div className="border border-border divide-y divide-border rounded-md">
-                    <div className="flex items-center gap-3 px-3 py-2.5">
-                      <Building2 className="h-4 w-4 text-muted-foreground shrink-0" />
-                      <div className="flex-1 min-w-0">
-                        <p className="text-sm font-medium truncate">
-                          {companyName}
-                        </p>
-                        <p className="text-xs text-muted-foreground">
-                          {companyGoal}
-                        </p>
-                      </div>
-                      <Check className="h-4 w-4 text-green-500 shrink-0" />
-                    </div>
-                    <div className="flex items-center gap-3 px-3 py-2.5">
-                      <Bot className="h-4 w-4 text-muted-foreground shrink-0" />
-                      <div className="flex-1 min-w-0">
-                        <p className="text-sm font-medium truncate">
-                          {agentName}
-                        </p>
-                        <p className="text-xs text-muted-foreground">
-                          CEO · {getUIAdapter(adapterType).label}
-                        </p>
-                      </div>
-                      <Check className="h-4 w-4 text-green-500 shrink-0" />
-                    </div>
                     {hiringRoles
                       .filter((r) => r.enabled && r.name.trim())
                       .map((role) => (
@@ -1712,7 +1765,7 @@ export function OnboardingWizard() {
                               {role.name}
                             </p>
                             <p className="text-xs text-muted-foreground truncate">
-                              {role.description || "New hire"}
+                              {role.summary || "New hire"}
                             </p>
                           </div>
                           <span className="text-[10px] text-amber-500 font-medium">
@@ -1786,34 +1839,14 @@ export function OnboardingWizard() {
                       {loading ? "Bringing to life..." : "Give it a heartbeat"}
                     </Button>
                   )}
-                  {step === 4 && (
+                  {step === 4 && !planContent && (
-                    <>
+                    <Button
-                      <Button
+                      variant="ghost"
-                        variant="ghost"
+                      size="sm"
-                        size="sm"
+                      onClick={() => setStep(5)}
-                        onClick={() => {
+                    >
-                          if (planContent) {
+                      Skip chat
-                            setHiringRoles(parseHiringPlan(planContent));
+                    </Button>
-                          }
-                          setStep(5);
-                        }}
-                      >
-                        Skip chat
-                      </Button>
-                      <Button
-                        size="sm"
-                        disabled={loading}
-                        onClick={() => {
-                          if (planContent) {
-                            setHiringRoles(parseHiringPlan(planContent));
-                          }
-                          setStep(5);
-                        }}
-                      >
-                        <ArrowRight className="h-3.5 w-3.5 mr-1" />
-                        Next
-                      </Button>
-                    </>
                   )}
                   {step === 5 && (
                     <Button
@@ -1855,6 +1888,124 @@ export function OnboardingWizard() {
   );
 }
 
+const ROLE_FIELDS: Array<{ key: keyof HiringRole; label: string; placeholder: string }> = [
+  { key: "summary", label: "Summary", placeholder: "One-line description of this role" },
+  { key: "expertise", label: "Expertise & Responsibilities", placeholder: "What this agent does, its skills, and detailed responsibilities" },
+  { key: "priorities", label: "Priorities", placeholder: "What this role focuses on first, in order of importance" },
+  { key: "boundaries", label: "Boundaries", placeholder: "What this role should NOT do, out-of-scope areas" },
+  { key: "tools", label: "Tools & Permissions", placeholder: "What tools, systems, or access this role needs" },
+  { key: "communication", label: "Communication", placeholder: "Tone, style, and interaction guidelines" },
+  { key: "collaboration", label: "Collaboration & Escalation", placeholder: "Who this role works with, escalation paths" },
+];
+
+function RoleCard({
+  role,
+  onChange,
+  onDelete,
+}: {
+  role: HiringRole;
+  onChange: (updated: HiringRole) => void;
+  onDelete: () => void;
+}) {
+  const [expanded, setExpanded] = useState(false);
+  const update = (field: keyof HiringRole, value: string) =>
+    onChange({ ...role, [field]: value });
+
+  if (role.editing) {
+    return (
+      <div
+        className={cn(
+          "rounded-md border px-3 py-3 transition-colors space-y-3",
+          role.enabled ? "border-border bg-background" : "border-border/50 bg-muted/30 opacity-60"
+        )}
+      >
+        <input
+          className="w-full rounded border border-border bg-transparent px-2 py-1.5 text-sm font-medium outline-none focus:ring-1 focus:ring-ring"
+          placeholder="Role name"
+          value={role.name}
+          onChange={(e) => update("name", e.target.value)}
+          autoFocus
+        />
+        {ROLE_FIELDS.map(({ key, label, placeholder }) => (
+          <div key={key}>
+            <label className="text-[11px] text-muted-foreground mb-0.5 block font-medium">
+              {label}
+            </label>
+            <textarea
+              className="w-full rounded border border-border bg-transparent px-2 py-1.5 text-sm outline-none focus:ring-1 focus:ring-ring resize-y min-h-[60px] max-h-[200px]"
+              placeholder={placeholder}
+              value={(role[key] as string) || ""}
+              onChange={(e) => update(key, e.target.value)}
+            />
+          </div>
+        ))}
+        <Button
+          size="sm"
+          variant="outline"
+          onClick={() => onChange({ ...role, editing: false })}
+        >
+          <Check className="h-3 w-3 mr-1" />
+          Done
+        </Button>
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className={cn(
+        "rounded-md border px-3 py-2.5 transition-colors",
+        role.enabled ? "border-border bg-background" : "border-border/50 bg-muted/30 opacity-60"
+      )}
+    >
+      <div className="flex items-start gap-2.5">
+        <input
+          type="checkbox"
+          checked={role.enabled}
+          onChange={(e) => onChange({ ...role, enabled: e.target.checked })}
+          className="mt-1 shrink-0"
+        />
+        <div className="flex-1 min-w-0">
+          <p className="text-sm font-medium">{role.name || "Untitled role"}</p>
+          {role.summary && (
+            <p className="text-xs text-muted-foreground mt-0.5">{role.summary}</p>
+          )}
+          {expanded && (
+            <div className="mt-2 space-y-1.5">
+              {ROLE_FIELDS.filter(({ key }) => key !== "summary" && (role[key] as string)?.trim()).map(({ key, label }) => (
+                <div key={key}>
+                  <p className="text-[10px] font-medium text-muted-foreground uppercase tracking-wide">{label}</p>
+                  <p className="text-xs text-muted-foreground whitespace-pre-line">{role[key] as string}</p>
+                </div>
+              ))}
+            </div>
+          )}
+          <button
+            className="text-[10px] text-muted-foreground hover:text-foreground transition-colors mt-1"
+            onClick={() => setExpanded(!expanded)}
+          >
+            {expanded ? "Show less" : "Show more"}
+          </button>
+        </div>
+        <div className="flex items-center gap-1 shrink-0">
+          <button
+            className="p-1 text-muted-foreground hover:text-foreground transition-colors"
+            onClick={() => onChange({ ...role, editing: true })}
+          >
+            <Pencil className="h-3 w-3" />
+          </button>
+          <button
+            className="p-1 text-muted-foreground hover:text-destructive transition-colors"
+            onClick={onDelete}
+          >
+            <Trash2 className="h-3 w-3" />
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
 function AdapterEnvironmentResult({
   result
 }: {