The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
Rebuild the onboarding agent arc on the prototype's step design (#11905)
Tonio3d366ba15ff1
diff --git a/.claude/launch.json b/.claude/launch.jsonindex 7cbc05c40a..6258bdc8cc 100644--- a/.claude/launch.json+++ b/.claude/launch.json@@ -4,9 +4,12 @@{"name": "paperclip","runtimeExecutable": "/bin/sh",- "runtimeArgs": ["-c", "TMPDIR=/tmp pnpm dev"],+ "runtimeArgs": [+ "-c",+ "TMPDIR=/tmp pnpm dev"+ ],"port": 3108,- "autoPort": false+ "autoPort": true}]}diff --git a/tests/e2e/conference-room-typing-intro.spec.ts b/tests/e2e/conference-room-typing-intro.spec.tsindex 6d528bc99f..4bffe5f5eb 100644--- a/tests/e2e/conference-room-typing-intro.spec.ts+++ b/tests/e2e/conference-room-typing-intro.spec.ts@@ -81,10 +81,11 @@ async function runOnboardingWizard(page: Page, companyName: string) {await page.getByPlaceholder("What is your team trying to achieve?").fill(MISSION);await page.getByRole("button", { name: /Confirm mission/ }).click();- // Step 3: lead name (prefilled) → Next.- await page.waitForSelector('input[placeholder="Chief of staff"]', {- timeout: 15_000,- });+ // Step 3: the lead's role, then its name. The role gates "Next", and+ // choosing one fills the name — so the walk only types here to override it.+ await page.waitForSelector("#onboarding-agent-role", { timeout: 15_000 });+ await page.locator("#onboarding-agent-role").click();+ await page.getByRole("option", { name: "CEO", exact: true }).click();await page.getByRole("button", { name: /^Next/ }).click();// Step 4: adapter (claude_local default); heartbeat is intercepted.diff --git a/tests/e2e/nux-phase4-screenshots.spec.ts b/tests/e2e/nux-phase4-screenshots.spec.tsindex c872f5712b..d5b56929e4 100644--- a/tests/e2e/nux-phase4-screenshots.spec.ts+++ b/tests/e2e/nux-phase4-screenshots.spec.ts@@ -83,7 +83,7 @@ test.describe("NUX Phase 4 visual QA", () => {// Step 2 advances via "Confirm mission" (creates the company + goal);// step 3 is the team-lead naming step of the capsule wizard.await page.getByRole("button", { name: /Confirm mission/ }).click();- await page.waitForSelector('input[placeholder="Chief of staff"]', {+ await page.waitForSelector("#onboarding-agent-role", {timeout: 30_000,});await page.screenshot({ path: shot("04-hire-team-lead.png") });diff --git a/tests/e2e/onboarding.spec.ts b/tests/e2e/onboarding.spec.tsindex a29078a724..ecd077d332 100644--- a/tests/e2e/onboarding.spec.ts+++ b/tests/e2e/onboarding.spec.ts@@ -71,7 +71,7 @@ test.describe("Onboarding wizard", () => {// "Confirm mission" creates the company + a company-level goal, then// advances to the team-lead naming step of the capsule wizard.await page.getByRole("button", { name: /Confirm mission/ }).click();- await page.waitForSelector('input[placeholder="Chief of staff"]', {+ await page.waitForSelector("#onboarding-agent-role", {timeout: 30_000,});diff --git a/tests/e2e/planning-mode-visual-verification.spec.ts b/tests/e2e/planning-mode-visual-verification.spec.tsindex 47053beb38..fb362d40e9 100644--- a/tests/e2e/planning-mode-visual-verification.spec.ts+++ b/tests/e2e/planning-mode-visual-verification.spec.ts@@ -4,7 +4,8 @@ import {instrumentNavLog,} from "./helpers/onboarding-landing";-const AGENT_NAME = "Chief of staff";+/** The name the CEO role fills in — see AGENT_ROLE_LABELS. */+const AGENT_NAME = "CEO";const TASK_TITLE = "Paperclip onboarding";test("captures planning mode UI for desktop and mobile", async ({ page }) => {@@ -64,8 +65,12 @@ test("captures planning mode UI for desktop and mobile", async ({ page }) => {.fill("Capture planning mode visual evidence for the graduated task UI.");await page.getByRole("button", { name: /Confirm mission/ }).click();- await page.waitForSelector('input[placeholder="Chief of staff"]', { timeout: 30_000 });- await expect(page.locator('input[placeholder="Chief of staff"]')).toHaveValue(AGENT_NAME);+ // The lead is no longer pre-named. Choosing a role fills the name from the+ // role's label, which is also what gates "Next".+ await page.waitForSelector("#onboarding-agent-role", { timeout: 30_000 });+ await page.locator("#onboarding-agent-role").click();+ await page.getByRole("option", { name: "CEO", exact: true }).click();+ await expect(page.locator("#onboarding-agent-name")).toHaveValue(AGENT_NAME);await page.getByRole("button", { name: /^Next/ }).click();await page.getByRole("button", { name: /^Connect$/ }).click();diff --git a/tests/release-smoke/docker-auth-onboarding.spec.ts b/tests/release-smoke/docker-auth-onboarding.spec.tsindex dd02b0e40f..031d5862d9 100644--- a/tests/release-smoke/docker-auth-onboarding.spec.ts+++ b/tests/release-smoke/docker-auth-onboarding.spec.ts@@ -61,10 +61,12 @@ test.describe("Docker authenticated onboarding smoke", () => {.fill(MISSION);await page.getByRole("button", { name: "Confirm mission" }).click();- // Step 3: name the team lead.- const leadNameInput = page.locator('input[placeholder="Chief of staff"]');- await expect(leadNameInput).toBeVisible({ timeout: 20_000 });- await leadNameInput.fill(AGENT_NAME);+ // Step 3: give the team lead a role, then a name. The role gates "Next".+ const roleSelect = page.locator("#onboarding-agent-role");+ await expect(roleSelect).toBeVisible({ timeout: 20_000 });+ await roleSelect.click();+ await page.getByRole("option", { name: "CEO", exact: true }).click();+ await page.locator("#onboarding-agent-name").fill(AGENT_NAME);await page.getByRole("button", { name: "Next" }).click();// Step 4: keep the default adapter and connect (hire) the lead. Thediff --git a/ui/package.json b/ui/package.jsonindex 6b626670ef..ae0c33915f 100644--- a/ui/package.json+++ b/ui/package.json@@ -60,6 +60,7 @@"lexical": "0.49.0","lucide-react": "^0.577.0","mermaid": "^11.16.1",+ "motion": "^12.42.2","radix-ui": "^1.6.7","react": "^19.2.8","react-dom": "^19.2.8",diff --git a/ui/src/components/AgentCapsule.test.tsx b/ui/src/components/AgentCapsule.test.tsxindex 87eff2c090..87285eb032 100644--- a/ui/src/components/AgentCapsule.test.tsx+++ b/ui/src/components/AgentCapsule.test.tsx@@ -90,4 +90,28 @@ describe("AgentCapsule", () => {expect(render(<AgentCapsule state="online" gradient={0} />).dataset.gradient).toBe("10");expect(render(<AgentCapsule state="online" gradient={-1} />).dataset.gradient).toBe("9");});++ it("traces the outline instead of cross-fading it when strokeDraw is set", () => {+ // The cross-fade renders a bordered <span>; the trace renders an SVG rect+ // animated from pathLength 0 to 1.+ const cap = render(<AgentCapsule state="configured" strokeDraw />);+ expect(cap.querySelector("svg rect")).not.toBeNull();+ expect(cap.querySelector(".agent-cap-stroke")).toBeNull();+ });++ it("keeps the cross-fade when strokeDraw is not asked for", () => {+ // Everywhere outside the onboarding arc the quieter default applies.+ const cap = render(<AgentCapsule state="configured" />);+ expect(cap.querySelector(".agent-cap-stroke")).not.toBeNull();+ expect(cap.querySelector("svg rect")).toBeNull();+ });++ it("holds the dashed outline until the trace finishes", () => {+ // Fading the dashed layer on the usual schedule would leave the capsule+ // briefly outline-less in the middle of its own birth.+ const cap = render(<AgentCapsule state="configured" strokeDraw />);+ const dashed = cap.querySelector(".agent-cap-dash") as HTMLElement;+ expect(dashed).not.toBeNull();+ expect(dashed.style.transitionDelay).not.toBe("");+ });});diff --git a/ui/src/components/AgentCapsule.tsx b/ui/src/components/AgentCapsule.tsxindex 817a9dbb76..b696a3a9b6 100644--- a/ui/src/components/AgentCapsule.tsx+++ b/ui/src/components/AgentCapsule.tsx@@ -1,3 +1,4 @@+import { motion, useReducedMotion } from "motion/react";import * as React from "react";import { cn } from "@/lib/utils";@@ -60,10 +61,24 @@ export interface AgentCapsulePropssize?: AgentCapsuleSizePreset | { width: number; height: number };/** Online-pulse colour (only applies in the `online` state). Defaults to `green`. */glow?: AgentCapsuleGlow;+ /**+ * Render the slot→configured morph as a draw-on: the solid outline is traced+ * around the perimeter over the still-visible dashed outline, which fades+ * once the draw completes, instead of the two layers cross-fading.+ *+ * This is the agent's "birth" moment in the onboarding wizard, where the+ * customer has just named it and the capsule should read as being drawn into+ * existence. Everywhere else the cross-fade is the right, quieter default.+ */+ strokeDraw?: boolean;/** Accessible label; defaults to a description of the state. */"aria-label"?: string;}+/** Duration of the strokeDraw perimeter trace; the dashed layer fades after it. */+const STROKE_DRAW_SECONDS = 0.9;+const STROKE_DRAW_EASE = [0.16, 1, 0.3, 1] as const;+/** Normalize a (possibly out-of-range) gradient index to 1…AGENT_GRADIENT_COUNT. */function normalizeGradient(gradient: number): number {const n = Math.trunc(gradient);@@ -75,12 +90,15 @@ export function AgentCapsule({gradient = 1,size = "md",glow = "green",+ strokeDraw = false,className,style,"aria-label": ariaLabel,...rest}: AgentCapsuleProps) {const dims = typeof size === "string" ? SIZE_PRESETS[size] : size;+ const reducedMotion = useReducedMotion();+ const drawn = state === "configured" || state === "online";const idx = normalizeGradient(gradient);const fill = `linear-gradient(to bottom, var(--agent-${idx}a), var(--agent-${idx}b))`;@@ -107,16 +125,53 @@ export function AgentCapsule({"agent-cap-dash agent-cap-layer pointer-events-none absolute inset-0 rounded-full border-2 border-dashed border-muted-foreground/60",state === "slot" ? "agent-cap-slot opacity-100" : "opacity-0",)}+ // In strokeDraw mode the dashed outline stays put while the solid one+ // is traced over it, and only then fades — otherwise the capsule would+ // be briefly outline-less midway through its own birth.+ style={+ strokeDraw && state === "configured" && !reducedMotion+ ? { transitionDelay: `${STROKE_DRAW_SECONDS}s` }+ : undefined+ }/>- {/* Solid stroke — agent configured, not yet live. Cross-fades in on top- of the dashed layer, then out as the liquid rises. */}- <span- aria-hidden="true"- className={cn(- "agent-cap-stroke agent-cap-layer pointer-events-none absolute inset-0 rounded-full border-2 border-solid border-foreground/70",- state === "configured" ? "opacity-100" : "opacity-0",- )}- />+ {/* Solid stroke — agent configured, not yet live. Default: cross-fades in+ on top of the dashed layer, then out as the liquid rises. strokeDraw:+ an SVG outline traced around the perimeter (pathLength 0→1). */}+ {strokeDraw ? (+ <svg+ aria-hidden="true"+ className="pointer-events-none absolute inset-0"+ width="100%"+ height="100%"+ viewBox={`0 0 ${dims.width} ${dims.height}`}+ fill="none"+ >+ <motion.rect+ x={1}+ y={1}+ width={dims.width - 2}+ height={dims.height - 2}+ rx={(dims.width - 2) / 2}+ strokeWidth={2}+ className="stroke-foreground/70"+ initial={false}+ animate={{ pathLength: drawn ? 1 : 0 }}+ transition={+ reducedMotion+ ? { duration: 0 }+ : { duration: STROKE_DRAW_SECONDS, ease: STROKE_DRAW_EASE }+ }+ />+ </svg>+ ) : (+ <span+ aria-hidden="true"+ className={cn(+ "agent-cap-stroke agent-cap-layer pointer-events-none absolute inset-0 rounded-full border-2 border-solid border-foreground/70",+ state === "configured" ? "opacity-100" : "opacity-0",+ )}+ />+ )}{/* Brand-gradient liquid — rises to fill the capsule when online. */}{state === "online" ? (<spandiff --git a/ui/src/components/OnboardingWizard.step.test.tsx b/ui/src/components/OnboardingWizard.step.test.tsxindex 97f57e2800..78ab9b166f 100644--- a/ui/src/components/OnboardingWizard.step.test.tsx+++ b/ui/src/components/OnboardingWizard.step.test.tsx@@ -105,7 +105,9 @@ function currentStep(): "mission" | "agent" | "closed" | "other" {if (!body.querySelector("[role='dialog'], .fixed.inset-0")) return "closed";const headings = [...body.querySelectorAll("h3")].map((h) => h.textContent);if (headings.includes("Define your mission")) return "mission";- if (body.querySelector("input[placeholder='Chief of staff']")) return "agent";+ // Keyed on the role control rather than the name field: the name is optional+ // and starts empty, so its placeholder is the generic "Name".+ if (body.querySelector("#onboarding-agent-role")) return "agent";return "other";}@@ -753,12 +755,37 @@ describe("OnboardingWizard — which step it lands on", () => {expect(currentStep()).toBe("agent");}+ /**+ * Choose a role, which the step now requires before it will advance — it+ * asks rather than assuming one. Driven by keyboard because the control is+ * a Radix listbox: its pointer path needs `hasPointerCapture`, which jsdom+ * does not implement, while its keyboard path does not.+ */+ async function pickRole(label = "CEO") {+ const trigger = document.getElementById("onboarding-agent-role")!;+ await act(async () => {+ trigger.dispatchEvent(+ new KeyboardEvent("keydown", { key: "Enter", bubbles: true }),+ );+ });+ await settle();+ const option = [...document.body.querySelectorAll('[role="option"]')].find(+ (o) => o.textContent?.trim() === label,+ ) as HTMLElement | undefined;+ expect(option).toBeDefined();+ await act(async () => {+ option!.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter", bubbles: true }));+ });+ await settle();+ }+it("seeds the lead agent's instructions with the mission it was never asked for", async () => {// The regression this exists for. The agent step feeds// `composeCeoInstructions` from the mission field, and a company entered// here never types one — so the agent was hired knowing nothing of the// mission the customer gave at signup, and nothing reported it.await openOnAgentStep();+ await pickRole();const next = [...document.body.querySelectorAll("button")].find((b) =>b.textContent?.includes("Next"),@@ -790,6 +817,7 @@ describe("OnboardingWizard — which step it lands on", () => {// nothing — the same "retained data is not an answer" rule the draft// ownership gate follows.await openOnAgentStep();+ await pickRole();const next = [...document.body.querySelectorAll("button")].find((b) =>b.textContent?.includes("Next"),@@ -847,6 +875,7 @@ describe("OnboardingWizard — which step it lands on", () => {await rerender();await settle();expect(currentStep()).toBe("agent");+ await pickRole();const next = [...document.body.querySelectorAll("button")].find((b) =>b.textContent?.includes("Next"),@@ -868,6 +897,39 @@ describe("OnboardingWizard — which step it lands on", () => {expect(file.content).toContain("Scale the marketplace");});+ it("hires the agent with the role the customer picked", async () => {+ // The role was hardcoded to "ceo" before the role select existed. A+ // dropdown that renders but does not reach the hire call would look+ // entirely correct on screen and silently mis-file every agent.+ await openOnAgentStep();+ // Deliberately not the first option: "ceo" is what the hardcoded value+ // was, so a test that picked it could not tell a wired dropdown from an+ // ignored one.+ await pickRole("Engineer");++ const next = [...document.body.querySelectorAll("button")].find((b) =>+ b.textContent?.includes("Next"),+ )!;+ await act(async () => {+ next.dispatchEvent(new MouseEvent("click", { bubbles: true }));+ });+ await settle();+ const connect = [...document.body.querySelectorAll("button")].find((b) =>+ b.textContent?.includes("Connect"),+ )!;+ await act(async () => {+ connect.dispatchEvent(new MouseEvent("click", { bubbles: true }));+ });+ await settle();++ expect(mockAgentsApi.hire).toHaveBeenCalled();+ const [, payload] = mockAgentsApi.hire.mock.calls.at(-1)!;+ expect(payload.role).toBe("engineer");+ // Picking a role also renamed the agent, since the field still held the+ // name the wizard supplied.+ expect(payload.name).toBe("Engineer");+ });+it("does not offer a way back behind the step it entered on", async () => {// Step 1 creates a company. A run that already holds one must not be// able to walk into it, by the Back button or the progress bar.@@ -878,10 +940,20 @@ describe("OnboardingWizard — which step it lands on", () => {);expect(back).toBeUndefined();- const nameSegment = document.body.querySelector(- '[aria-label="Step 1"]',- ) as HTMLButtonElement | null;- expect(nameSegment?.disabled).toBe(true);+ // The progress strip's segments are the only jump controls on this+ // screen. Entering here means there is nowhere behind to return to, so+ // every one of them is inert — asserted over the whole set rather than+ // one segment, since a single enabled one is the whole defect.+ const segments = [...document.body.querySelectorAll("button")].filter((b) =>+ ["Create your first agent", "Connect a model", "Review"].includes(+ b.getAttribute("aria-label") ?? "",+ ),+ ) as HTMLButtonElement[];+ expect(segments).toHaveLength(3);+ expect(segments.every((segment) => segment.disabled)).toBe(true);++ // And company creation is genuinely unreachable, not merely unlinked.+ expect(document.body.textContent).not.toContain("Name your company");});});});diff --git a/ui/src/components/OnboardingWizard.test.tsx b/ui/src/components/OnboardingWizard.test.tsxindex 8fe95e65bc..cb7e184721 100644--- a/ui/src/components/OnboardingWizard.test.tsx+++ b/ui/src/components/OnboardingWizard.test.tsx@@ -259,11 +259,16 @@ describe("OnboardingWizard restore-gate (stale localStorage across accounts)", (// (step 0, "Chief of staff").expect(document.body.textContent).toContain("Create your first agent");const nameInput = document.body.querySelector(- 'input[placeholder="Chief of staff"]',+ "#onboarding-agent-name",) as HTMLInputElement | null;expect(nameInput?.value).toBe("Ops Lead");+ // The run entered on the agent arc, so the arc strip is the progress+ // indicator and counts 1-3 over the wizard's steps 3-5. Segments are+ // labelled by destination: the wizard has its own numbering, and two+ // controls both announcing "Step 1" would mean different things.const currentStep = document.body.querySelector('[aria-current="step"]');- expect(currentStep?.getAttribute("aria-label")).toBe("Step 3");+ expect(currentStep?.getAttribute("aria-label")).toBe("Create your first agent");+ expect(document.body.textContent).toContain("Step 1 of 3");await act(async () => {root.unmount();@@ -344,7 +349,7 @@ describe("OnboardingWizard restore-gate (stale localStorage across accounts)", (expect(document.body.textContent).not.toBe("");// The draft is not restored, because ownership cannot be verified...const nameInput = document.body.querySelector(- 'input[placeholder="Chief of staff"]',+ "#onboarding-agent-name",) as HTMLInputElement | null;expect(nameInput?.value ?? "").not.toBe("Ops Lead");// ...and not deleted either. The wizard is open in this harness, so the@@ -433,7 +438,7 @@ describe("OnboardingWizard restore-gate (stale localStorage across accounts)", (expect(document.body.textContent).not.toBe("");// ...but the draft was not restored, because the list cannot be trusted.const nameInput = document.body.querySelector(- 'input[placeholder="Chief of staff"]',+ "#onboarding-agent-name",) as HTMLInputElement | null;expect(nameInput?.value ?? "").not.toBe("Ops Lead");@@ -558,7 +563,7 @@ describe("OnboardingWizard restore-gate (stale localStorage across accounts)", (// Account A's agent name must not appear in account B's wizard.expect(document.body.textContent).not.toContain("A's Lead");const nameInput = document.body.querySelector(- 'input[placeholder="Chief of staff"]',+ "#onboarding-agent-name",) as HTMLInputElement | null;expect(nameInput?.value ?? "").not.toBe("A's Lead");@@ -613,7 +618,7 @@ describe("OnboardingWizard restore-gate (stale localStorage across accounts)", (expect(document.body.textContent).not.toBe("");expect(document.body.textContent).not.toContain("A's Lead");const nameInput = document.body.querySelector(- 'input[placeholder="Chief of staff"]',+ "#onboarding-agent-name",) as HTMLInputElement | null;expect(nameInput?.value ?? "").not.toBe("A's Lead");@@ -687,7 +692,7 @@ describe("OnboardingWizard restore-gate (stale localStorage across accounts)", (expect(document.body.textContent).not.toBe("");expect(document.body.textContent).not.toContain("A's Lead");const nameInput = document.body.querySelector(- 'input[placeholder="Chief of staff"]',+ "#onboarding-agent-name",) as HTMLInputElement | null;expect(nameInput?.value ?? "").not.toBe("A's Lead");diff --git a/ui/src/components/OnboardingWizard.tsx b/ui/src/components/OnboardingWizard.tsxindex c549dcb5f9..25c4af41cd 100644--- a/ui/src/components/OnboardingWizard.tsx+++ b/ui/src/components/OnboardingWizard.tsx@@ -1,11 +1,17 @@import { useEffect, useState, useMemo, useRef } from "react";import type { CSSProperties } from "react";import { useQuery, useQueryClient } from "@tanstack/react-query";+import { MotionConfig, motion } from "motion/react";import type {AdapterEnvironmentTestResult,+ AgentRole,Environment,InstanceSettings,} from "@paperclipai/shared";+import { AGENT_ROLES, AGENT_ROLE_LABELS } from "@paperclipai/shared";+import { Label } from "./ui/label";+import { Input } from "./ui/input";+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "./ui/select";import { useLocation, useNavigate, useParams } from "@/lib/router";import { useDialog } from "../context/DialogContext";import { useCompany } from "../context/CompanyContext";@@ -72,6 +78,12 @@ import {import { AsciiArtAnimation } from "./AsciiArtAnimation";import { FrontDoor } from "./FrontDoor";import { AgentCapsule } from "./AgentCapsule";+import { AGENT_ARC_WIZARD_STEPS, Stepper, agentArcStepFor } from "./onboarding/Stepper";+import { AgentPreview } from "./onboarding/AgentPreview";+import { FooterNav } from "./onboarding/FooterNav";+import { OnboardingHeading } from "./onboarding/OnboardingPrimitives";+import { DEFAULT_AGENT_NAME, nextAgentNameForRole } from "../lib/onboarding-agent-role";+import { capsuleHeroMotion } from "./onboarding/onboarding-motion";import { Badge } from "@/components/ui/badge";import {Building2,@@ -398,7 +410,12 @@ function OnboardingWizardInner({const [q4, setQ4] = useState((saved?.q4 as string) ?? ""); // What would success look like?// Step 2- const [agentName, setAgentName] = useState((saved?.agentName as string) ?? "Chief of staff");+ // Neither is defaulted. The prototype asks for a role before it will create+ // anything, and leaves the name optional — a pre-filled "Chief of staff" is a+ // choice made on the customer's behalf that they then have to notice and+ // undo. Picking a role fills the name; see nextAgentNameForRole.+ const [agentName, setAgentName] = useState((saved?.agentName as string) ?? "");+ const [agentRole, setAgentRole] = useState<AgentRole | "">((saved?.agentRole as AgentRole) ?? "");const [adapterType, setAdapterType] = useState<AdapterType>((saved?.adapterType as AdapterType) ?? "claude_local");const [cwd, setCwd] = useState((saved?.cwd as string) ?? "");const [model, setModel] = useState((saved?.model as string) ?? "");@@ -631,7 +648,7 @@ function OnboardingWizardInner({if (!effectiveOnboardingOpen) return;const state = {step, companyName, companyGoal, missionPath, missionConfirmed,- q1, q2, q3, q4, agentName, adapterType, cwd, model, command, args, url,+ q1, q2, q3, q4, agentName, agentRole, adapterType, cwd, model, command, args, url,createdCompanyId, createdCompanyPrefix, createdAgentId,createdCompanyGoalId, createdProjectId, createdIssueRef,onboardingPath, growWorkflows, growPainPoints, growAutomate,@@ -639,7 +656,7 @@ function OnboardingWizardInner({onboardingDraftStorage.write(JSON.stringify(state));}, [effectiveOnboardingOpen, step, companyName, companyGoal, missionPath, missionConfirmed,- q1, q2, q3, q4, agentName, adapterType, cwd, model, command, args, url,+ q1, q2, q3, q4, agentName, agentRole, adapterType, cwd, model, command, args, url,createdCompanyId, createdCompanyPrefix, createdAgentId,createdCompanyGoalId, createdProjectId, createdIssueRef,onboardingPath, growWorkflows, growPainPoints, growAutomate,@@ -811,7 +828,11 @@ function OnboardingWizardInner({setQ2("");setQ3("");setQ4("");- setAgentName("Chief of staff");+ // Both cleared, matching the mount defaults: a reset that left a name+ // behind without its role would put the walker back on a step whose CTA+ // is disabled, next to a name nobody chose.+ setAgentName("");+ setAgentRole("");setAdapterType("claude_local");setModel("");setCommand("");@@ -1232,9 +1253,12 @@ function OnboardingWizardInner({}}+ if (!agentRole) return;const hire = await agentsApi.hire(createdCompanyId, {- name: agentName.trim(),- role: "ceo",+ // The name is optional; an agent that reaches here without one is+ // named for the job it was hired to do rather than left blank.+ name: agentName.trim() || AGENT_ROLE_LABELS[agentRole],+ role: agentRole,adapterType,adapterConfig: buildAdapterConfig(),runtimeConfig: buildNewAgentRuntimeConfig()@@ -1363,6 +1387,12 @@ function OnboardingWizardInner({if (!effectiveOnboardingOpen) return null;+ // The arc strip stands in for the full-length bar only when the run began on+ // the arc — the Cloud-first path, where the company already exists and steps+ // 1-2 never happen. A run that started at step 1 keeps one continuous count.+ const isAgentArcStep = agentArcStepFor(step) !== null;+ const showsAgentArcStepper = isAgentArcStep && entryStep >= 3;+const launchStateIncomplete = step === 5 && (!createdCompanyId || !createdAgentId);const visibleError = error ?? (launchStateIncomplete ? INCOMPLETE_ONBOARDING_STATE_MESSAGE : null);@@ -1408,9 +1438,25 @@ function OnboardingWizardInner({step === 1 || step === 2 ? "md:w-1/2" : "md:w-full")}>- <div className="w-full max-w-md mx-auto my-auto px-8 py-12 shrink-0">+ <div+ className={cn(+ "mx-auto my-auto shrink-0",+ // The arc sits in the prototype's card frame; the earlier steps+ // keep the split-panel layout they were designed for. One+ // element styled two ways, not two wrappers, so the step+ // content below renders exactly once.+ isAgentArcStep+ ? "w-(--sz-560px) max-w-full rounded-xl border border-border bg-card px-8 py-10 sm:px-10 sm:py-11"+ : "w-full max-w-md px-8 py-12",+ )}+ >{/* 5-segment progress bar (brand .wsteps/.wstep) — segment N- filled once step ≥ N. Completed segments jump back. */}+ filled once step ≥ N. Completed segments jump back.+ Hidden for a run that entered on the agent arc: the arc strip+ below counts that run's three steps, and showing both put two+ progress bars on the same screen. A run that started at step 1+ keeps this one throughout, so its count never restarts. */}+ {!showsAgentArcStepper && (<div className="flex items-center gap-1.5 mb-8">{([1, 2, 3, 4, 5] as const).map((s) => {const filled = step >= s;@@ -1436,75 +1482,85 @@ function OnboardingWizardInner({);})}</div>+ )}- {/* Persistent evolving capsule (steps 3–5): a single AgentCapsule- held in the same tree slot so React reuses the DOM node and the- morph reads as one capsule coming to life — dashed slot →- solid (configured) → liquid fill + blue glow (online). */}+ {/* The agent arc's progress strip. Numbered 1–3 over the wizard's+ steps 3–5, because company creation already happened in Cloud+ and the mission step is skipped when it did. */}+ {showsAgentArcStepper && (+ <Stepper+ step={agentArcStepFor(step)!}+ canJumpToStep={(target) =>+ canJumpToOnboardingStep({+ targetStep: AGENT_ARC_WIZARD_STEPS[target - 1]!,+ currentStep: step,+ entryStep,+ })+ }+ onJumpToStep={(target) => setStep(AGENT_ARC_WIZARD_STEPS[target - 1]! as Step)}+ />+ )}++ {/* The hero, above the heading, as the prototype has it: one+ AgentCapsule held in the same tree slot across steps 3–5, so+ React reuses the DOM node and the morph reads as a single+ capsule coming to life — dashed slot → traced outline →+ liquid fill. Moving between steps never replays the entrance. */}{step >= 3 && step <= 5 && (- <div className="mb-6 space-y-4">- <div className="flex items-center gap-3 mb-1">- <div className="bg-muted/50 p-2">- {step === 5 ? (- <Check className="h-5 w-5 text-muted-foreground" />- ) : (- <Bot className="h-5 w-5 text-muted-foreground" />- )}- </div>- <div>- <h3 className="font-medium">- {step === 3+ // reducedMotion="user" defers to the OS setting, so the hero+ // arrives in place for anyone who asked for less movement. The+ // token layer zeroes the CSS durations; this covers the JS half.+ <MotionConfig reducedMotion="user">+ {/* mb-6 continues the prototype's single rhythm past this+ block: it groups the hero and heading, and the step's own+ controls sit a step below on the same spacing. */}+ <div className="mb-6 space-y-6">+ <motion.div+ initial={capsuleHeroMotion.initial}+ animate={capsuleHeroMotion.animate}+ transition={capsuleHeroMotion.transition}+ className="flex flex-col items-center gap-2"+ >+ <AgentCapsule+ state={step === 3 ? "slot" : step === 4 ? "configured" : "online"}+ gradient={5}+ glow="blue"+ size="md"+ // The arc is where the agent is born, so the+ // slot→configured morph traces the outline on.+ strokeDraw+ />+ <AgentPreview+ agentName={agentName}+ agentRole={agentRole ? AGENT_ROLE_LABELS[agentRole] : ""}+ />+ </motion.div>++ <OnboardingHeading+ center+ title={+ step === 3? "Create your first agent": step === 4? "Connect a model"- : "Review"}- </h3>- <p className="text-xs text-muted-foreground">- {step === 3 ? (+ : "Review"+ }+ // The agent step carries no lede, as the prototype has it:+ // the capsule and the heading say what this is, and a+ // sentence restating it only pushes the fields down.+ lede={+ step === 3 ? undefined : step === 4 ? (<>- They'll help drive{" "}- <span className="font-medium text-foreground">{companyName}</span>{" "}- toward its mission. We default to{" "}- <span className="font-medium text-foreground">Chief of staff</span>.- Rename it to anything you like.+ What model would you like your first agent to use? You can+ choose different models when creating additional agents.</>- ) : step === 4 ? (- <>Pick the adapter and model your lead will run on, then check the environment.</>) : (<>Your first agent is online and ready to work.</>- )}- </p>- </div>- </div>-- <div- className={cn(- "flex flex-col items-center py-1 text-center",- step === 5 ? "mt-8 gap-2.5" : "gap-1.5"- )}- >- <AgentCapsule- state={step === 3 ? "slot" : step === 4 ? "configured" : "online"}- gradient={5}- glow="blue"- size="md"+ )+ }/>- {step !== 3 && (- <p- className={cn(- "text-muted-foreground",- step === 5 ? "text-sm" : "text-(length:--text-micro)"- )}- >- {step === 4 ? (- "your team lead, taking shape"- ) : (- <span className="font-medium text-foreground">{agentName}</span>- )}- </p>- )}</div>- </div>+ </MotionConfig>)}{/* Step content */}@@ -1834,25 +1890,47 @@ function OnboardingWizardInner({</div>)}- {/* Step 3: Create your team lead — name only (capsule above) */}+ {/* Step 3: role, then an optional name — the prototype's field+ pair, in its order and its widths. */}{step === 3 && (- <div className="space-y-5">- <div>- <label className="text-xs text-muted-foreground mb-1 block">- Name- </label>- <input- className="w-full 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"- placeholder="Chief of staff"+ <div className="mx-auto flex w-full max-w-(--sz-320px) flex-col gap-6">+ <div className="flex flex-col gap-2">+ <Label htmlFor="onboarding-agent-role">Role</Label>+ {/* Options come from the AgentRole enum, not the prototype's+ mock list: four of that list's seven entries have no+ equivalent here, and one ("Coder") would fail validation+ at hire time. */}+ <Select+ value={agentRole || undefined}+ onValueChange={(value) => {+ const nextRole = value as AgentRole;+ setAgentRole(nextRole);+ setAgentName((current) =>+ nextAgentNameForRole({ currentName: current, nextRole }),+ );+ }}+ >+ <SelectTrigger id="onboarding-agent-role" className="w-full">+ <SelectValue placeholder="Select a role…" />+ </SelectTrigger>+ <SelectContent>+ {AGENT_ROLES.map((role) => (+ <SelectItem key={role} value={role}>+ {AGENT_ROLE_LABELS[role]}+ </SelectItem>+ ))}+ </SelectContent>+ </Select>+ </div>+ <div className="flex flex-col gap-2">+ <Label htmlFor="onboarding-agent-name">+ Name <span className="font-normal text-muted-foreground">(optional)</span>+ </Label>+ <Input+ id="onboarding-agent-name"+ placeholder="Name"value={agentName}onChange={(e) => setAgentName(e.target.value)}- onKeyDown={(e) => {- if (e.key === "Enter" && agentName.trim()) {- e.preventDefault();- setStep(4);- }- }}- autoFocus/></div></div>@@ -2267,7 +2345,37 @@ function OnboardingWizardInner({</div>)}+ {isAgentArcStep && (+ <FooterNav+ onBack={+ canGoBackFromOnboardingStep({ currentStep: step, entryStep })+ ? () => setStep((step - 1) as Step)+ : undefined+ }+ // The prototype's cloud flow hires on this step and calls the+ // action "Create". Here the model step sits between, so this+ // one advances — which is exactly the distinction the+ // prototype's own local flow draws with "Next".+ primaryLabel={step === 3 ? "Next" : step === 4 ? "Connect" : "Get started"}+ loadingLabel={step === 4 ? "Connecting..." : "Launching..."}+ loading={step === 3 ? false : loading}+ primaryDisabled={+ step === 3+ ? !agentRole+ : step === 4+ ? loading || adapterEnvLoading || missionUnresolvedForHire+ : loading || launchStateIncomplete+ }+ onPrimary={() => {+ if (step === 3) setStep(4);+ else if (step === 4) handleGiveHeartbeat();+ else handleLaunchToDashboard();+ }}+ />+ )}+{/* Footer navigation */}+ {!isAgentArcStep && (<div className="flex items-center justify-between mt-8"><div>{canGoBackFromOnboardingStep({ currentStep: step, entryStep }) && (@@ -2355,6 +2463,7 @@ function OnboardingWizardInner({)}</div></div>+ )}</div></div>)}diff --git a/ui/src/components/onboarding/AgentPreview.tsx b/ui/src/components/onboarding/AgentPreview.tsxnew file mode 100644index 0000000000..7a624b8c50--- /dev/null+++ b/ui/src/components/onboarding/AgentPreview.tsx@@ -0,0 +1,46 @@+import { motion } from "motion/react";+import { PREVIEW_REVEAL_DURATION, STEP_EASE } from "./onboarding-motion";++/**+ * Name/role preview under the capsule. Collapsed to zero height until an+ * identity exists, so the step opens compact; on selection the block grows to+ * full height — the centered card re-centers each frame, so the capsule slides+ * up into place — while the labels fade in without moving. Slide and fade share+ * one duration; the fade starts after 25% of it. Both lines keep fixed heights+ * once visible, so typing a name afterwards never shifts the layout again.+ */+export function AgentPreview({+ agentName,+ agentRole,+}: {+ agentName: string;+ agentRole: string;+}) {+ const previewVisible = Boolean(agentName || agentRole);+ return (+ <motion.div+ className="overflow-hidden"+ initial={false}+ animate={{ height: previewVisible ? "auto" : 0 }}+ transition={{ duration: PREVIEW_REVEAL_DURATION, ease: STEP_EASE }}+ >+ <motion.div+ className="mt-1 flex flex-col items-center gap-1"+ initial={false}+ animate={{ opacity: previewVisible ? 1 : 0 }}+ transition={{+ duration: PREVIEW_REVEAL_DURATION,+ ease: STEP_EASE,+ delay: previewVisible ? PREVIEW_REVEAL_DURATION * 0.25 : 0,+ }}+ >+ <span className="flex h-6 items-center text-base font-semibold tracking-tight text-foreground">+ {agentName || " "}+ </span>+ <span className="flex h-4 items-center text-xs text-muted-foreground">+ {agentRole || " "}+ </span>+ </motion.div>+ </motion.div>+ );+}diff --git a/ui/src/components/onboarding/FooterNav.tsx b/ui/src/components/onboarding/FooterNav.tsxnew file mode 100644index 0000000000..2636d714e3--- /dev/null+++ b/ui/src/components/onboarding/FooterNav.tsx@@ -0,0 +1,57 @@+import { ArrowLeft, ArrowRight, Loader2 } from "lucide-react";+import { Button } from "../ui/button";++/**+ * Shared footer for the arc's step cards: a ghost pill "Back" and a primary+ * pill CTA that shows a spinner and a loading label while its action runs.+ *+ * `onBack` is optional — a run that entered on this step has nowhere behind it+ * to return to, and an inert Back button reads as a dead control rather than a+ * boundary.+ */+export function FooterNav({+ onBack,+ primaryLabel,+ primaryDisabled,+ loading,+ loadingLabel,+ onPrimary,+}: {+ onBack?: () => void;+ primaryLabel: string;+ primaryDisabled?: boolean;+ loading?: boolean;+ loadingLabel?: string;+ onPrimary: () => void;+}) {+ return (+ <div className="flex items-center justify-between pt-6">+ {onBack ? (+ // has-[>svg]:pr-4 gives "Back" room from the pill's right edge,+ // overriding size="sm"'s symmetric padding on that side only.+ <Button+ variant="ghost"+ size="sm"+ className="rounded-full has-[>svg]:pr-4"+ onClick={onBack}+ disabled={loading}+ >+ <ArrowLeft className="mr-1 size-3.5" />+ Back+ </Button>+ ) : (+ <span />+ )}+ <Button+ size="lg"+ className="rounded-full px-6"+ onClick={onPrimary}+ disabled={primaryDisabled || loading}+ >+ {loading ? <Loader2 className="mr-1 size-4 animate-spin" /> : null}+ {loading && loadingLabel ? loadingLabel : primaryLabel}+ {!loading ? <ArrowRight className="ml-1 size-3.5" /> : null}+ </Button>+ </div>+ );+}diff --git a/ui/src/components/onboarding/OnboardingPrimitives.tsx b/ui/src/components/onboarding/OnboardingPrimitives.tsxnew file mode 100644index 0000000000..da3b997c19--- /dev/null+++ b/ui/src/components/onboarding/OnboardingPrimitives.tsx@@ -0,0 +1,45 @@+// Presentational primitives for the onboarding wizard's agent arc, ported from+// the onboarding prototype onto the repo's design tokens. No backend logic+// lives here — these are pure view pieces.+import type { ReactNode } from "react";+import { cn } from "../../lib/utils";++/** The centered card frame each step of the arc sits in. */+export function OnboardingCard({+ children,+ className,+}: {+ children: ReactNode;+ className?: string;+}) {+ return (+ <div+ className={cn(+ "w-(--sz-560px) max-w-full rounded-xl border border-border bg-card px-8 py-10 sm:px-10 sm:py-11",+ className,+ )}+ >+ {children}+ </div>+ );+}++/** Display heading + supporting lede, ported from the prototype's hero type. */+export function OnboardingHeading({+ title,+ lede,+ center,+}: {+ title: ReactNode;+ lede?: ReactNode;+ center?: boolean;+}) {+ return (+ <div className={cn("space-y-2", center && "text-center")}>+ <h1 className="text-4xl font-semibold tracking-tight text-foreground">{title}</h1>+ {lede ? (+ <p className="text-base leading-relaxed text-muted-foreground">{lede}</p>+ ) : null}+ </div>+ );+}diff --git a/ui/src/components/onboarding/Stepper.test.ts b/ui/src/components/onboarding/Stepper.test.tsnew file mode 100644index 0000000000..990e512ef9--- /dev/null+++ b/ui/src/components/onboarding/Stepper.test.ts@@ -0,0 +1,32 @@+import { describe, expect, it } from "vitest";+import { AGENT_ARC_TOTAL_STEPS, agentArcStepFor } from "./Stepper";++describe("agentArcStepFor", () => {+ it("numbers the arc from the agent step, not from the wizard's first step", () => {+ // The wizard's step 3 is the customer's step 1: company creation happened+ // in Cloud, and the mission step is skipped when it did.+ expect(agentArcStepFor(3)).toBe(1);+ expect(agentArcStepFor(4)).toBe(2);+ expect(agentArcStepFor(5)).toBe(3);+ });++ it("has no position for steps outside the arc", () => {+ // The front door and the company/mission steps are not part of the+ // sequence the strip counts, so they must not render one.+ for (const wizardStep of [0, 1, 2, 6]) {+ expect(agentArcStepFor(wizardStep)).toBeNull();+ }+ });++ it("never numbers a step past the total it advertises", () => {+ // "Step 4 of 3" is the failure an arithmetic mapping produces the first+ // time a step is added ahead of the arc.+ for (const wizardStep of [-1, 0, 1, 2, 3, 4, 5, 6, 7, 99]) {+ const position = agentArcStepFor(wizardStep);+ if (position !== null) {+ expect(position).toBeGreaterThanOrEqual(1);+ expect(position).toBeLessThanOrEqual(AGENT_ARC_TOTAL_STEPS);+ }+ }+ });+});diff --git a/ui/src/components/onboarding/Stepper.tsx b/ui/src/components/onboarding/Stepper.tsxnew file mode 100644index 0000000000..1db18c62d5--- /dev/null+++ b/ui/src/components/onboarding/Stepper.tsx@@ -0,0 +1,90 @@+import { cn } from "../../lib/utils";++/**+ * The agent arc — create the agent, connect it, review — is the part of the+ * wizard a customer walks as a numbered sequence. Company creation happens in+ * Cloud before the tenant is ever reached, so it is not one of these steps.+ */+export const AGENT_ARC_TOTAL_STEPS = 3;++/**+ * What each segment goes to. These are the labels assistive tech reads, in+ * place of a bare number: the wizard has its own step numbering, and two+ * controls both announcing "Step 1" while meaning different steps is worse+ * than no number at all. The visible "Step N of 3" line carries the count.+ */+export const AGENT_ARC_STEP_LABELS = [+ "Create your first agent",+ "Connect a model",+ "Review",+] as const;++/** Wizard step numbers that make up the arc, in order. */+export const AGENT_ARC_WIZARD_STEPS = [3, 4, 5] as const;++/**+ * Map a wizard step onto its position in the arc, or `null` when the step is+ * outside it.+ *+ * The two numbering schemes exist for different reasons and must not be+ * conflated: the wizard's own step numbers include entries the customer may+ * never see (the front door, and the company/mission steps that are skipped+ * when Cloud already created the company), while the strip counts only what+ * this leg of the walk actually shows. Deriving one from the other with+ * arithmetic would silently produce "Step 0 of 3" the first time a step is+ * inserted ahead of the arc.+ */+export function agentArcStepFor(wizardStep: number): number | null {+ const index = AGENT_ARC_WIZARD_STEPS.indexOf(wizardStep as (typeof AGENT_ARC_WIZARD_STEPS)[number]);+ return index === -1 ? null : index + 1;+}++/**+ * Segmented progress strip with a "Step N of M" label.+ *+ * Segments double as the way back to a step already completed, which is the+ * affordance the wizard's full-length bar provides outside the arc. A segment+ * the customer may not return to stays a disabled button rather than+ * disappearing: the wizard can be entered partway in, and a strip that simply+ * omitted the steps behind the entry point would misreport how far along they+ * are.+ */+export function Stepper({+ step,+ total = AGENT_ARC_TOTAL_STEPS,+ canJumpToStep,+ onJumpToStep,+}: {+ step: number;+ total?: number;+ canJumpToStep?: (target: number) => boolean;+ onJumpToStep?: (target: number) => void;+}) {+ return (+ <div className="mb-7 flex flex-col gap-3.5">+ <div className="flex items-center gap-2">+ {Array.from({ length: total }, (_, index) => index + 1).map((segment) => {+ const jumpable = Boolean(canJumpToStep?.(segment) && onJumpToStep);+ return (+ <button+ key={segment}+ type="button"+ aria-label={AGENT_ARC_STEP_LABELS[segment - 1] ?? `Step ${segment}`}+ aria-current={segment === step ? "step" : undefined}+ disabled={!jumpable}+ onClick={() => jumpable && onJumpToStep?.(segment)}+ className={cn(+ "h-(--sz-3px) flex-1 rounded-full transition-colors",+ segment <= step ? "bg-foreground" : "bg-border",+ jumpable ? "cursor-pointer" : "cursor-default",+ )}+ />+ );+ })}+ </div>+ <span className="text-(length:--text-micro) font-medium uppercase tracking-widest text-muted-foreground">+ Step {step} of {total}+ </span>+ </div>+ );+}diff --git a/ui/src/components/onboarding/onboarding-motion.ts b/ui/src/components/onboarding/onboarding-motion.tsnew file mode 100644index 0000000000..ca28408883--- /dev/null+++ b/ui/src/components/onboarding/onboarding-motion.ts@@ -0,0 +1,54 @@+// Shared motion constants for the onboarding wizard's agent arc (steps 3–5).+// Ported from the onboarding prototype so the capsule choreography reads the+// same here as it does there. Reduced motion is honoured at the token layer+// (ui/src/index.css collapses --motion-duration-* under the media query) and+// by <MotionConfig reducedMotion="user"> where these are consumed.++/** Step crossfade easing — the house signature curve, also used for in-step reveals. */+export const STEP_EASE = [0.16, 1, 0.3, 1] as const;++/** Per-step enter/exit crossfade for the keyed step container. */+export const stepMotion = {+ initial: { opacity: 0, y: 8 },+ animate: { opacity: 1, y: 0 },+ exit: { opacity: 0, y: -8 },+ transition: { duration: 0.28, ease: STEP_EASE },+};++/**+ * The dashed slot's entrance on the agent step: fades and scales up from 50%+ * about its own centre. Deliberately no y offset — that would bias the growth+ * upward and read as a drop-in rather than something forming in place.+ */+export const CAPSULE_ENTER_DURATION = 1.0;+export const capsuleMotion = {+ initial: { opacity: 0, scale: 0.5 },+ animate: { opacity: 1, scale: 1 },+ transition: { type: "spring" as const, duration: CAPSULE_ENTER_DURATION, bounce: 0.4 },+};++/** The name/role reveal: the label fade is staggered by 25% of this. */+export const PREVIEW_REVEAL_DURATION = 0.45;++/**+ * The hand-off that makes the capsule read as one object across all three+ * steps rather than three separate renders: it eases out with the departing+ * step, then resurfaces on the next one, springing back to full size so it+ * lands rather than snapping. The exit duration mirrors the step transition so+ * the two travel together.+ */+export const capsuleHandoffExit = {+ scale: 0.5,+ opacity: 0,+ transition: { duration: 0.28, ease: STEP_EASE },+};+export const capsuleHeroMotion = {+ initial: { scale: 0.5, opacity: 0 },+ animate: { scale: 1, opacity: 1 },+ transition: {+ // A soft spring: slow enough that the scale-up is noticeable, damped+ // enough that it still settles. The fade is lengthened to travel with it.+ scale: { type: "spring" as const, stiffness: 150, damping: 16 },+ opacity: { duration: 0.55, ease: STEP_EASE },+ },+};diff --git a/ui/src/lib/onboarding-agent-role.test.ts b/ui/src/lib/onboarding-agent-role.test.tsnew file mode 100644index 0000000000..69f4d42880--- /dev/null+++ b/ui/src/lib/onboarding-agent-role.test.ts@@ -0,0 +1,38 @@+import { describe, expect, it } from "vitest";+import { AGENT_ROLE_LABELS } from "@paperclipai/shared";+import { DEFAULT_AGENT_NAME, nextAgentNameForRole } from "./onboarding-agent-role";++describe("nextAgentNameForRole", () => {+ it("fills the name from the role when the field is empty", () => {+ expect(nextAgentNameForRole({ currentName: "", nextRole: "cto" })).toBe(+ AGENT_ROLE_LABELS.cto,+ );+ });++ it("replaces the default name the wizard supplied", () => {+ expect(nextAgentNameForRole({ currentName: DEFAULT_AGENT_NAME, nextRole: "designer" })).toBe(+ AGENT_ROLE_LABELS.designer,+ );+ });++ it("replaces a label left by a previous role", () => {+ // Picking CTO then CMO should leave "CMO", not "CTO".+ expect(nextAgentNameForRole({ currentName: AGENT_ROLE_LABELS.cto, nextRole: "cmo" })).toBe(+ AGENT_ROLE_LABELS.cmo,+ );+ });++ it("keeps a name the customer typed", () => {+ // The failure this prevents is silent: the field still holds a plausible+ // name afterwards, so the loss is invisible until the agent is hired.+ expect(nextAgentNameForRole({ currentName: "Ada", nextRole: "engineer" })).toBe("Ada");+ });++ it("keeps a typed name that only differs by surrounding space", () => {+ expect(nextAgentNameForRole({ currentName: " Ada ", nextRole: "engineer" })).toBe(" Ada ");+ });++ it("treats a whitespace-only field as empty", () => {+ expect(nextAgentNameForRole({ currentName: " ", nextRole: "qa" })).toBe(AGENT_ROLE_LABELS.qa);+ });+});diff --git a/ui/src/lib/onboarding-agent-role.ts b/ui/src/lib/onboarding-agent-role.tsnew file mode 100644index 0000000000..7dfaea7a2d--- /dev/null+++ b/ui/src/lib/onboarding-agent-role.ts@@ -0,0 +1,37 @@+import { AGENT_ROLE_LABELS, type AgentRole } from "@paperclipai/shared";++/**+ * The name the wizard offers before the customer picks a role. It is a job+ * title rather than a role label because it reads as a person on the very+ * first screen where the agent appears.+ */+export const DEFAULT_AGENT_NAME = "Chief of staff";++/**+ * Names the wizard put there itself, and may therefore replace. Anything the+ * customer typed is theirs and survives a role change.+ *+ * The prototype's version of this step simply overwrote the name whenever the+ * role changed, which is fine in a mock with no real input to lose. Here it+ * would silently discard a name someone chose deliberately, and the loss is+ * invisible: the field still has *a* plausible name in it afterwards.+ */+const WIZARD_SUPPLIED_NAMES: ReadonlySet<string> = new Set([+ DEFAULT_AGENT_NAME,+ ...Object.values(AGENT_ROLE_LABELS),+]);++/**+ * The name to show after a role change — the new role's label when the field+ * still holds something the wizard supplied, otherwise the customer's own text.+ */+export function nextAgentNameForRole(params: {+ currentName: string;+ nextRole: AgentRole;+}): string {+ const current = params.currentName.trim();+ if (current === "" || WIZARD_SUPPLIED_NAMES.has(current)) {+ return AGENT_ROLE_LABELS[params.nextRole];+ }+ return params.currentName;+}diff --git a/ui/storybook/.storybook/main.ts b/ui/storybook/.storybook/main.tsindex af2dcbd2b9..0192e08658 100644--- a/ui/storybook/.storybook/main.ts+++ b/ui/storybook/.storybook/main.ts@@ -20,7 +20,14 @@ const config: StorybookConfig = {viteFinal: async (baseConfig) =>mergeConfig(baseConfig, {plugins: [tailwindcss()],+ optimizeDeps: { include: ["motion/react", "react", "react-dom"] },resolve: {+ // Storybook's core and the react-vite builder each resolve their own+ // React under pnpm's strict tree. Any component that calls a hook from+ // a third-party package — `motion`'s useReducedMotion, in the agent+ // capsule — then gets a second copy and fails with "Invalid hook call".+ // The app's own dev server hoists one React and never hit this.+ dedupe: ["react", "react-dom"],alias: {"@": path.resolve(storybookConfigDir, "../../src"),lexical: path.resolve(storybookConfigDir, "../../node_modules/lexical/dist/Lexical.mjs"),diff --git a/ui/storybook/stories/onboarding-agent-arc.stories.tsx b/ui/storybook/stories/onboarding-agent-arc.stories.tsxnew file mode 100644index 0000000000..710827d1a8--- /dev/null+++ b/ui/storybook/stories/onboarding-agent-arc.stories.tsx@@ -0,0 +1,64 @@+import type { Meta, StoryObj } from "@storybook/react-vite";+import { AgentCapsule } from "@/components/AgentCapsule";+import { Stepper } from "@/components/onboarding/Stepper";++/**+ * The onboarding wizard's agent arc: create the agent, connect it, review.+ * These are the three steps a customer walks inside the tenant — company+ * creation happens in Cloud before they arrive, which is why the strip counts+ * to three rather than to the wizard's own step numbers.+ */+const meta = {+ title: "Onboarding/Agent arc",+ parameters: { layout: "centered" },+} satisfies Meta;++export default meta;++export const ProgressStrip: StoryObj = {+ render: () => (+ <div className="w-[420px] space-y-10">+ {[1, 2, 3].map((step) => (+ <Stepper key={step} step={step} />+ ))}+ </div>+ ),+};++/**+ * The capsule's three states, which the wizard holds in one tree slot so the+ * morph reads as a single object coming to life rather than three renders.+ */+export const CapsuleStates: StoryObj = {+ render: () => (+ <div className="flex items-center gap-12">+ {(["slot", "configured", "online"] as const).map((state) => (+ <div key={state} className="flex flex-col items-center gap-3">+ <AgentCapsule state={state} gradient={5} glow="blue" size="md" strokeDraw />+ <span className="text-(length:--text-micro) uppercase tracking-widest text-muted-foreground">+ {state}+ </span>+ </div>+ ))}+ </div>+ ),+};++/**+ * The same three states rendered with the default cross-fade, for comparison+ * with the traced outline above.+ */+export const CapsuleStatesCrossfade: StoryObj = {+ render: () => (+ <div className="flex items-center gap-12">+ {(["slot", "configured", "online"] as const).map((state) => (+ <div key={state} className="flex flex-col items-center gap-3">+ <AgentCapsule state={state} gradient={5} glow="blue" size="md" />+ <span className="text-(length:--text-micro) uppercase tracking-widest text-muted-foreground">+ {state}+ </span>+ </div>+ ))}+ </div>+ ),+};