Skip to content

The open-source app everyone uses to manage agents at work

Rebuild the onboarding agent arc on the prototype's step design (#11905)

Tonio3d366ba15ff1
diff --git a/.claude/launch.json b/.claude/launch.json
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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. The
diff --git a/ui/package.json b/ui/package.json
index 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.tsx
index 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.tsx
index 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 AgentCapsuleProps
size?: 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" ? (
<span
diff --git a/ui/src/components/OnboardingWizard.step.test.tsx b/ui/src/components/OnboardingWizard.step.test.tsx
index 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.tsx
index 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.tsx
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.ts
new file mode 100644
index 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.tsx
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.tsx
new file mode 100644
index 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>
+ ),
+};