From f07ff1a28cba5ce09530d4c06f2da40252a9c387 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Th=C3=A9o=20LAGACHE?= <theo.lagache@soluce-technologies.com>
Date: Fri, 19 Jun 2026 10:20:19 +0200
Subject: [PATCH] docs: add onboarding refactor implementation plan

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../plans/2026-06-19-onboarding-refactor.md   | 1905 +++++++++++++++++
 1 file changed, 1905 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-06-19-onboarding-refactor.md

diff --git a/docs/superpowers/plans/2026-06-19-onboarding-refactor.md b/docs/superpowers/plans/2026-06-19-onboarding-refactor.md
new file mode 100644
index 00000000..cffc5be4
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-19-onboarding-refactor.md
@@ -0,0 +1,1905 @@
+# Onboarding Feature Refactor — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Reorganise `src/features/onboarding/` into typed sub-directories (types/, constants/, schemas/, hooks/) and replace all ad-hoc `useState(loading)` + try/finally patterns with `useMutation`/`useQuery` hooks from TanStack Query.
+
+**Architecture:** Each hook calls `useOnboarding()` internally — steps pass nothing to hooks, they only call hooks and render JSX. Mutations handle API call + `updateContext`. Steps handle UI side-effects (form.reset, phase transitions) via per-call `onSuccess`.
+
+**Tech Stack:** Next.js 15 App Router, TanStack Query v5 (`@tanstack/react-query`), `@onboardjs/react`, `next-safe-action`, TypeScript.
+
+## Global Constraints
+
+- All hooks live under `src/features/onboarding/hooks/`
+- Hooks call `useOnboarding()` themselves — never accept `state`/`updateContext`/`next` as props
+- `useMutation` for write operations, `useQuery` for polling/fetch
+- `toast.error` in hook's `onError` — steps never duplicate error toasts
+- Import types from `@/features/onboarding/types` (after Task 1 migration)
+- No new UI/UX changes — refactor only
+- No hooks for: `step-login` (auth-specific), `step-preferences` (no server calls), `step-invite-members` (local-only), `step-security` (context-only), `step-db-settings` (local-only), `step-defaults` (too specific)
+
+---
+
+### Task 1: Foundation — types/, constants/, schemas/
+
+**Files:**
+- Create: `src/features/onboarding/types/index.ts`
+- Create: `src/features/onboarding/constants/steps.ts`
+- Create: `src/features/onboarding/schemas/account.schema.ts`
+- Delete: `src/features/onboarding/onboarding.types.ts` (after updating all imports)
+- Modify: all 14 files that import from `onboarding.types` (listed below)
+
+**Imports to migrate** (all `@/features/onboarding/onboarding.types` → `@/features/onboarding/types`):
+```
+src/features/onboarding/onboarding-state.ts
+src/features/onboarding/steps/step-preferences.tsx
+src/features/onboarding/steps/step-security.tsx
+src/features/onboarding/steps/step-login.tsx
+src/features/onboarding/steps/step-account-info.tsx
+src/features/onboarding/steps/step-agent-waiting.tsx
+src/features/onboarding/steps/step-storage.tsx
+src/features/onboarding/steps/step-agent-key.tsx
+src/features/onboarding/steps/step-agent-create.tsx
+src/features/onboarding/steps/step-notifier.tsx
+src/features/onboarding/steps/step-project-create.tsx
+src/features/onboarding/steps/step-invite-members.tsx
+src/features/onboarding/steps/step-db-settings.tsx
+src/features/onboarding/steps/step-defaults.tsx
+```
+
+- [ ] **Step 1: Create types/index.ts**
+
+Copy the full content of `onboarding.types.ts` verbatim:
+
+```typescript
+// src/features/onboarding/types/index.ts
+export type OnboardingSsoProvider = { id: string; label: string };
+
+export type OnboardingMeta = {
+  passkeyEnabled: boolean;
+  hasExistingUsers: boolean;
+  ssoProviders: OnboardingSsoProvider[];
+  defaultUserMode: boolean;
+  resumeStepId: string;
+  emailPasswordEnabled: boolean;
+};
+
+export type OnboardingAccountData = {
+  firstName: string;
+  lastName: string;
+  email: string;
+};
+
+export type OnboardingSecurityData = {
+  method: "passkey" | "two-factor" | "skipped";
+};
+
+export type OnboardingPreferencesData = {
+  theme: "light" | "dark";
+  avatarUrl?: string;
+};
+
+export type OnboardingOrgData = {
+  id: string;
+  name: string;
+};
+
+export type OnboardingMember = {
+  email: string;
+  role: "member" | "admin";
+};
+
+export type OnboardingChannel = {
+  id: string;
+  provider: string;
+  label: string;
+  name: string;
+  config: Record<string, unknown>;
+};
+
+export type OnboardingDefaultsData = {
+  notifierId?: string;
+  storageId?: string;
+};
+
+export type OnboardingAgent = {
+  id: string;
+  name: string;
+  notifierId?: string;
+  storageId?: string;
+};
+
+export type OnboardingDatabase = {
+  id: string;
+  name: string;
+  engine: "postgres" | "mysql" | "mongodb";
+};
+
+export type OnboardingDbSettings = {
+  retentionDays: number;
+  notifierId?: string;
+  storageId?: string;
+};
+
+export type OnboardingProjectData = {
+  id: string;
+  name: string;
+  description: string;
+  databaseIds: string[];
+};
+
+export type OnboardingFlowData = {
+  meta?: OnboardingMeta;
+  account?: OnboardingAccountData;
+  security?: OnboardingSecurityData;
+  preferences?: OnboardingPreferencesData;
+  org?: OnboardingOrgData;
+  members?: OnboardingMember[];
+  notifiers?: OnboardingChannel[];
+  storages?: OnboardingChannel[];
+  defaults?: OnboardingDefaultsData;
+  agents?: OnboardingAgent[];
+  databases?: OnboardingDatabase[];
+  project?: OnboardingProjectData;
+  dbSettings?: Record<string, OnboardingDbSettings>;
+};
+```
+
+- [ ] **Step 2: Create constants/steps.ts**
+
+```typescript
+// src/features/onboarding/constants/steps.ts
+export const STEP_IDS = {
+  LOGIN: "login",
+  ACCOUNT_INFO: "account-info",
+  SECURITY: "security",
+  PREFERENCES: "preferences",
+  ORG_CREATE: "org-create",
+  INVITE_MEMBERS: "invite-members",
+  NOTIFIER: "notifier",
+  STORAGE: "storage",
+  DEFAULTS: "defaults",
+  AGENT_CREATE: "agent-create",
+  AGENT_KEY: "agent-key",
+  AGENT_WAITING: "agent-waiting",
+  PROJECT_CREATE: "project-create",
+  DB_SETTINGS: "db-settings",
+  FINISH: "finish",
+} as const;
+
+export const STEP_ORDER: string[] = [
+  STEP_IDS.LOGIN,
+  STEP_IDS.ACCOUNT_INFO,
+  STEP_IDS.SECURITY,
+  STEP_IDS.PREFERENCES,
+  STEP_IDS.ORG_CREATE,
+  STEP_IDS.INVITE_MEMBERS,
+  STEP_IDS.NOTIFIER,
+  STEP_IDS.STORAGE,
+  STEP_IDS.DEFAULTS,
+  STEP_IDS.AGENT_CREATE,
+  STEP_IDS.AGENT_KEY,
+  STEP_IDS.AGENT_WAITING,
+  STEP_IDS.PROJECT_CREATE,
+  STEP_IDS.DB_SETTINGS,
+  STEP_IDS.FINISH,
+];
+```
+
+- [ ] **Step 3: Create schemas/account.schema.ts**
+
+Extract the two schemas currently inline in `step-account-info.tsx`:
+
+```typescript
+// src/features/onboarding/schemas/account.schema.ts
+import { z } from "zod";
+
+export const BaseSchema = z.object({
+  firstName: z.string().min(1, "First name required"),
+  lastName: z.string().min(1, "Last name required"),
+  email: z.string().email("Invalid email"),
+});
+
+export const WithPasswordSchema = BaseSchema.extend({
+  password: z.string().min(8, "Min. 8 characters"),
+});
+```
+
+- [ ] **Step 4: Update all 14 import paths**
+
+In each file listed above, replace:
+```typescript
+from "@/features/onboarding/onboarding.types"
+```
+with:
+```typescript
+from "@/features/onboarding/types"
+```
+
+Also in `step-account-info.tsx`, replace the inline schema definitions with imports:
+```typescript
+import { BaseSchema, WithPasswordSchema } from "@/features/onboarding/schemas/account.schema";
+```
+And remove the two `const BaseSchema = ...` and `const WithPasswordSchema = ...` blocks.
+
+- [ ] **Step 5: Update onboarding-shell.tsx to use constants**
+
+Replace the hardcoded `STEP_ORDER` array with an import:
+
+```typescript
+// Replace this:
+const STEP_ORDER = [
+  "login",
+  "account-info",
+  ...
+];
+
+// With:
+import { STEP_ORDER } from "@/features/onboarding/constants/steps";
+```
+
+- [ ] **Step 6: Delete onboarding.types.ts**
+
+```bash
+rm src/features/onboarding/onboarding.types.ts
+```
+
+- [ ] **Step 7: Verify TypeScript compiles**
+
+```bash
+npx tsc --noEmit
+```
+
+Expected: no errors. If errors, fix import paths.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add src/features/onboarding/types/index.ts \
+        src/features/onboarding/constants/steps.ts \
+        src/features/onboarding/schemas/account.schema.ts \
+        src/features/onboarding/onboarding-shell.tsx \
+        src/features/onboarding/steps/ \
+        src/features/onboarding/onboarding-state.ts
+git commit -m "refactor(onboarding): move types, constants, schemas to sub-directories"
+```
+
+---
+
+### Task 2: Agent hooks — useCreateAgent + useDeleteAgent
+
+**Files:**
+- Create: `src/features/onboarding/hooks/use-create-agent.ts`
+- Create: `src/features/onboarding/hooks/use-delete-agent.ts`
+- Modify: `src/features/onboarding/steps/step-agent-create.tsx`
+
+**Interfaces:**
+- Consumes: `createAgentAction` from `@/features/agents/agents.action`, `deleteAgentAction` from `@/features/agents/agent-delete.action`
+- Produces: `useCreateAgent()` → `UseMutationResult<OnboardingAgent, Error, string>`, `useDeleteAgent()` → `UseMutationResult<void, Error, string>`
+
+- [ ] **Step 1: Create use-create-agent.ts**
+
+```typescript
+// src/features/onboarding/hooks/use-create-agent.ts
+"use client";
+
+import { useMutation } from "@tanstack/react-query";
+import { useOnboarding } from "@onboardjs/react";
+import { toast } from "sonner";
+import { createAgentAction } from "@/features/agents/agents.action";
+import type { OnboardingAgent, OnboardingDefaultsData } from "@/features/onboarding/types";
+
+export const useCreateAgent = () => {
+  const { state, updateContext } = useOnboarding();
+
+  return useMutation({
+    mutationFn: async (name: string) => {
+      const orgId = (state?.context.flowData.org as any)?.id as string | undefined;
+      if (!orgId) throw new Error("Missing org ID — cannot create agent");
+
+      const defaults = (state?.context.flowData.defaults ?? {}) as OnboardingDefaultsData;
+      const result = await createAgentAction({
+        organizationId: orgId,
+        data: { name, description: "" },
+      });
+      if (!result?.data?.data) {
+        throw new Error(result?.serverError ?? `Failed to create agent "${name}"`);
+      }
+
+      const newAgent: OnboardingAgent = {
+        id: result.data.data.id,
+        name: result.data.data.name,
+        notifierId: defaults.notifierId,
+        storageId: defaults.storageId,
+      };
+      const agents = [
+        ...((state?.context.flowData.agents ?? []) as OnboardingAgent[]),
+        newAgent,
+      ];
+      await updateContext({ flowData: { ...state?.context.flowData, agents } });
+      return newAgent;
+    },
+    onError: (err: Error) => toast.error(err.message),
+  });
+};
+```
+
+- [ ] **Step 2: Create use-delete-agent.ts**
+
+```typescript
+// src/features/onboarding/hooks/use-delete-agent.ts
+"use client";
+
+import { useMutation } from "@tanstack/react-query";
+import { useOnboarding } from "@onboardjs/react";
+import { toast } from "sonner";
+import { deleteAgentAction } from "@/features/agents/agent-delete.action";
+import type { OnboardingAgent } from "@/features/onboarding/types";
+
+export const useDeleteAgent = () => {
+  const { state, updateContext } = useOnboarding();
+
+  return useMutation({
+    mutationFn: async (agentId: string) => {
+      const orgId = (state?.context.flowData.org as any)?.id as string | undefined;
+      const result = await deleteAgentAction({ agentId, organizationId: orgId });
+      if (result?.data?.success === false) throw new Error("Failed to delete agent");
+
+      const agents = (
+        (state?.context.flowData.agents ?? []) as OnboardingAgent[]
+      ).filter((a) => a.id !== agentId);
+      await updateContext({ flowData: { ...state?.context.flowData, agents } });
+    },
+    onError: (err: Error) => toast.error(err.message),
+  });
+};
+```
+
+- [ ] **Step 3: Update step-agent-create.tsx**
+
+Replace the full file content:
+
+```typescript
+// src/features/onboarding/steps/step-agent-create.tsx
+"use client";
+
+import { useState } from "react";
+import { useOnboarding } from "@onboardjs/react";
+import { X } from "lucide-react";
+import { Input } from "@/components/ui/input";
+import { Button } from "@/components/ui/button";
+import { useCreateAgent } from "@/features/onboarding/hooks/use-create-agent";
+import { useDeleteAgent } from "@/features/onboarding/hooks/use-delete-agent";
+import type { OnboardingAgent } from "@/features/onboarding/types";
+
+export const StepAgentCreate = () => {
+  const { next, state } = useOnboarding();
+  const agents = (state?.context.flowData.agents ?? []) as OnboardingAgent[];
+
+  const [name, setName] = useState("");
+  const createAgent = useCreateAgent();
+  const deleteAgent = useDeleteAgent();
+
+  const onAdd = () => {
+    if (!name.trim()) return;
+    createAgent.mutate(name.trim(), { onSuccess: () => setName("") });
+  };
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div>
+        <h1 className="text-2xl font-semibold">Create an agent</h1>
+        <p className="text-sm text-muted-foreground mt-1">
+          Optional — agents will use your default notifier and storage.
+        </p>
+      </div>
+
+      {agents.length > 0 && (
+        <div className="flex flex-col gap-1">
+          {agents.map((agent) => (
+            <div
+              key={agent.id}
+              className="flex items-center gap-2 rounded-lg border border-primary/20 bg-primary/10 p-2 text-sm text-primary"
+            >
+              <span className="flex-1 truncate">{agent.name}</span>
+              <button
+                type="button"
+                onClick={() => deleteAgent.mutate(agent.id)}
+                disabled={deleteAgent.isPending}
+                className="opacity-50 hover:opacity-100 transition-opacity"
+              >
+                <X className="size-4" />
+              </button>
+            </div>
+          ))}
+        </div>
+      )}
+
+      <div className="flex gap-2">
+        <Input
+          value={name}
+          onChange={(e) => setName(e.target.value)}
+          placeholder="agent-prod"
+          onKeyDown={(e) => e.key === "Enter" && onAdd()}
+          disabled={createAgent.isPending}
+        />
+        <Button
+          type="button"
+          variant="outline"
+          onClick={onAdd}
+          disabled={createAgent.isPending || !name.trim()}
+        >
+          {createAgent.isPending ? "Adding…" : "Add"}
+        </Button>
+      </div>
+
+      <Button type="button" onClick={() => next()}>
+        Continue
+      </Button>
+    </div>
+  );
+};
+```
+
+- [ ] **Step 4: Verify TypeScript**
+
+```bash
+npx tsc --noEmit
+```
+
+Expected: no errors.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/features/onboarding/hooks/use-create-agent.ts \
+        src/features/onboarding/hooks/use-delete-agent.ts \
+        src/features/onboarding/steps/step-agent-create.tsx
+git commit -m "refactor(onboarding): extract useCreateAgent and useDeleteAgent hooks"
+```
+
+---
+
+### Task 3: Org + Project hooks
+
+**Files:**
+- Create: `src/features/onboarding/hooks/use-create-org.ts`
+- Create: `src/features/onboarding/hooks/use-create-project.ts`
+- Modify: `src/features/onboarding/steps/step-org-create.tsx`
+- Modify: `src/features/onboarding/steps/step-project-create.tsx`
+
+**Interfaces:**
+- `useCreateOrg()` → `UseMutationResult<void, Error, string>` (mutate receives org name)
+- `useCreateProject()` → `UseMutationResult<void, Error, { name: string; description: string; databaseIds: string[] }>`
+
+- [ ] **Step 1: Create use-create-org.ts**
+
+```typescript
+// src/features/onboarding/hooks/use-create-org.ts
+"use client";
+
+import { useMutation } from "@tanstack/react-query";
+import { useOnboarding } from "@onboardjs/react";
+import { toast } from "sonner";
+import {
+  createOrganizationAction,
+  updateOrganizationAction,
+} from "@/features/organizations/organization.action";
+import { slugify } from "@/utils/slugify";
+
+export const useCreateOrg = () => {
+  const { state, updateContext, next } = useOnboarding();
+
+  return useMutation({
+    mutationFn: async (name: string) => {
+      const trimmed = name.trim();
+      if (!trimmed) throw new Error("Organisation name is required");
+      const existingOrg = state?.context.flowData.org;
+
+      if (existingOrg) {
+        const result = await updateOrganizationAction({
+          organizationId: existingOrg.id,
+          data: { name: trimmed, slug: slugify(trimmed), users: [] },
+        });
+        if (!result?.data?.success) {
+          const err = result?.data as { success: false; actionError?: any };
+          throw new Error(err?.actionError?.message ?? "Failed to update organisation");
+        }
+        await updateContext({
+          flowData: { ...state?.context.flowData, org: { id: existingOrg.id, name: trimmed } },
+        });
+      } else {
+        const result = await createOrganizationAction({ name: trimmed });
+        if (!result?.data?.success) {
+          const err = result?.data as { success: false; actionError?: any };
+          throw new Error(err?.actionError?.message ?? "Failed to create organisation");
+        }
+        const org = result.data.value;
+        if (!org) throw new Error("Failed to create organisation");
+        await updateContext({
+          flowData: { ...state?.context.flowData, org: { id: org.id, name: org.name } },
+        });
+      }
+      await next();
+    },
+    onError: (err: Error) => toast.error(err.message),
+  });
+};
+```
+
+- [ ] **Step 2: Update step-org-create.tsx**
+
+```typescript
+// src/features/onboarding/steps/step-org-create.tsx
+"use client";
+
+import { useState } from "react";
+import { useOnboarding } from "@onboardjs/react";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { Button } from "@/components/ui/button";
+import { useCreateOrg } from "@/features/onboarding/hooks/use-create-org";
+
+export const StepOrgCreate = () => {
+  const { state } = useOnboarding();
+  const existingOrg = state?.context.flowData.org;
+  const isEditMode = !!existingOrg;
+  const [name, setName] = useState(existingOrg?.name ?? "");
+
+  const mutation = useCreateOrg();
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div>
+        <h1 className="text-2xl font-semibold">
+          {isEditMode ? "Edit your organisation" : "Create your organisation"}
+        </h1>
+        <p className="text-sm text-muted-foreground mt-1">
+          {isEditMode ? "Rename your organisation." : "This step can't be skipped."}
+        </p>
+      </div>
+      <div className="flex flex-col gap-2">
+        <Label htmlFor="org-name">Organisation name</Label>
+        <Input
+          id="org-name"
+          value={name}
+          onChange={(e) => setName(e.target.value)}
+          placeholder="Acme Inc."
+        />
+      </div>
+      <Button
+        type="button"
+        onClick={() => mutation.mutate(name)}
+        disabled={!name.trim() || mutation.isPending}
+      >
+        {mutation.isPending
+          ? isEditMode ? "Saving…" : "Creating…"
+          : "Continue"}
+      </Button>
+    </div>
+  );
+};
+```
+
+- [ ] **Step 3: Create use-create-project.ts**
+
+```typescript
+// src/features/onboarding/hooks/use-create-project.ts
+"use client";
+
+import { useMutation } from "@tanstack/react-query";
+import { useOnboarding } from "@onboardjs/react";
+import { toast } from "sonner";
+import {
+  createProjectAction,
+  updateProjectAction,
+} from "@/features/projects/projects.action";
+import type { OnboardingProjectData } from "@/features/onboarding/types";
+
+type ProjectInput = { name: string; description: string; databaseIds: string[] };
+
+export const useCreateProject = () => {
+  const { state, updateContext, next } = useOnboarding();
+
+  return useMutation({
+    mutationFn: async ({ name, description, databaseIds }: ProjectInput) => {
+      const orgId = (state?.context.flowData.org as any)?.id as string | undefined;
+      if (!orgId) throw new Error("No organisation ID found");
+      const existingProject = state?.context.flowData.project as OnboardingProjectData | undefined;
+
+      if (existingProject?.id) {
+        const result = await updateProjectAction({
+          data: { name, databases: databaseIds },
+          organizationId: orgId,
+          projectId: existingProject.id,
+        });
+        if (!result?.data?.success) {
+          throw new Error(result?.data?.actionError?.message ?? "Failed to update project");
+        }
+        await updateContext({
+          flowData: {
+            ...state?.context.flowData,
+            project: { id: existingProject.id, name, description, databaseIds },
+          },
+        });
+      } else {
+        const result = await createProjectAction({
+          data: { name, databases: databaseIds },
+          organizationId: orgId,
+        });
+        if (!result?.data?.success) {
+          throw new Error(result?.data?.actionError?.message ?? "Failed to create project");
+        }
+        const project = result.data.value;
+        if (!project) throw new Error("Failed to create project");
+        await updateContext({
+          flowData: {
+            ...state?.context.flowData,
+            project: { id: project.id, name: project.name, description, databaseIds },
+          },
+        });
+      }
+      await next();
+    },
+    onError: (err: Error) => toast.error(err.message),
+  });
+};
+```
+
+- [ ] **Step 4: Update step-project-create.tsx**
+
+```typescript
+// src/features/onboarding/steps/step-project-create.tsx
+"use client";
+
+import { useState } from "react";
+import { useOnboarding } from "@onboardjs/react";
+import { Check, Database } from "lucide-react";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { Textarea } from "@/components/ui/textarea";
+import { Button } from "@/components/ui/button";
+import { useCreateProject } from "@/features/onboarding/hooks/use-create-project";
+import type { OnboardingDatabase, OnboardingProjectData } from "@/features/onboarding/types";
+
+export const StepProjectCreate = () => {
+  const { state } = useOnboarding();
+  const existingProject = state?.context.flowData.project as OnboardingProjectData | undefined;
+  const databases = (state?.context.flowData.databases ?? []) as OnboardingDatabase[];
+  const isUpdateMode = !!existingProject;
+
+  const [name, setName] = useState(existingProject?.name ?? "");
+  const [description, setDescription] = useState(existingProject?.description ?? "");
+  const [databaseIds, setDatabaseIds] = useState<string[]>(existingProject?.databaseIds ?? []);
+
+  const mutation = useCreateProject();
+
+  const toggleDb = (id: string) =>
+    setDatabaseIds((prev) => (prev.includes(id) ? prev.filter((v) => v !== id) : [...prev, id]));
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div>
+        <h1 className="text-2xl font-semibold">
+          {isUpdateMode ? "Update project" : "Create a project"}
+        </h1>
+        <p className="text-sm text-muted-foreground mt-1">Optional — group databases under a project.</p>
+      </div>
+      <div className="flex flex-col gap-2">
+        <Label htmlFor="project-name">Project name</Label>
+        <Input
+          id="project-name"
+          value={name}
+          onChange={(e) => setName(e.target.value)}
+          placeholder="My project"
+        />
+      </div>
+      <div className="flex flex-col gap-2">
+        <Label htmlFor="project-description">Description</Label>
+        <Textarea id="project-description" value={description} onChange={(e) => setDescription(e.target.value)} />
+      </div>
+      {databases.length > 0 && (
+        <div className="flex flex-col gap-2">
+          <Label>Databases</Label>
+          <div className="flex flex-col gap-2">
+            {databases.map((db) => {
+              const isSelected = databaseIds.includes(db.id);
+              return (
+                <button
+                  key={db.id}
+                  type="button"
+                  onClick={() => toggleDb(db.id)}
+                  className={`flex items-center gap-3 rounded-lg border p-3 text-sm transition-colors text-left ${
+                    isSelected
+                      ? "border-primary/20 bg-primary/10 text-primary"
+                      : "border-border hover:bg-accent/50 hover:border-primary/20"
+                  }`}
+                >
+                  <div className="size-9 rounded-md border bg-muted/50 shadow-sm flex items-center justify-center shrink-0">
+                    <Database className="size-4 text-muted-foreground" />
+                  </div>
+                  <div className="flex flex-col gap-0.5 flex-1">
+                    <span className="font-medium">{db.name}</span>
+                    <span className="text-xs text-muted-foreground">{db.engine}</span>
+                  </div>
+                  {isSelected && (
+                    <div className="size-5 rounded-full bg-primary flex items-center justify-center ml-auto">
+                      <Check className="size-3 text-primary-foreground" strokeWidth={3} />
+                    </div>
+                  )}
+                </button>
+              );
+            })}
+          </div>
+        </div>
+      )}
+      <Button
+        type="button"
+        onClick={() => mutation.mutate({ name, description, databaseIds })}
+        disabled={!name.trim() || mutation.isPending}
+      >
+        {mutation.isPending ? "Saving…" : "Continue"}
+      </Button>
+    </div>
+  );
+};
+```
+
+- [ ] **Step 5: Verify TypeScript**
+
+```bash
+npx tsc --noEmit
+```
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/features/onboarding/hooks/use-create-org.ts \
+        src/features/onboarding/hooks/use-create-project.ts \
+        src/features/onboarding/steps/step-org-create.tsx \
+        src/features/onboarding/steps/step-project-create.tsx
+git commit -m "refactor(onboarding): extract useCreateOrg and useCreateProject hooks"
+```
+
+---
+
+### Task 4: Account hook
+
+**Files:**
+- Create: `src/features/onboarding/hooks/use-update-account.ts`
+- Modify: `src/features/onboarding/steps/step-account-info.tsx`
+
+**Interfaces:**
+- `useUpdateAccount()` → `UseMutationResult<void, Error, z.infer<typeof WithPasswordSchema>>`
+
+- [ ] **Step 1: Create use-update-account.ts**
+
+```typescript
+// src/features/onboarding/hooks/use-update-account.ts
+"use client";
+
+import { useMutation } from "@tanstack/react-query";
+import { useOnboarding } from "@onboardjs/react";
+import { toast } from "sonner";
+import { z } from "zod";
+import { authClient, signUp, passkey, signIn } from "@/lib/auth/auth-client";
+import { updateAccountAction } from "@/features/onboarding/actions/update-account.action";
+import { generatePasskeyContextAction } from "@/features/onboarding/actions/generate-passkey-context.action";
+import { WithPasswordSchema } from "@/features/onboarding/schemas/account.schema";
+import type { OnboardingMeta } from "@/features/onboarding/types";
+
+type AccountInput = z.infer<typeof WithPasswordSchema>;
+
+export const useUpdateAccount = (refetchSession: () => Promise<any>) => {
+  const { state, updateContext, next } = useOnboarding();
+
+  return useMutation({
+    mutationFn: async (values: AccountInput) => {
+      const meta = state?.context.flowData.meta as OnboardingMeta | undefined;
+      const existingAccount = state?.context.flowData.account;
+      const isUpdateMode = !!existingAccount;
+      const passkeyEnabled = meta?.passkeyEnabled ?? false;
+
+      if (isUpdateMode) {
+        const result = await updateAccountAction({
+          firstName: values.firstName,
+          lastName: values.lastName,
+        });
+        if (!result?.data) throw new Error("Failed to update account");
+        await updateContext({
+          flowData: {
+            ...state?.context.flowData,
+            account: { firstName: values.firstName, lastName: values.lastName, email: values.email },
+          },
+        });
+        await next();
+        return;
+      }
+
+      if (passkeyEnabled) {
+        const name = `${values.firstName} ${values.lastName}`;
+        const context = await generatePasskeyContextAction(name, values.email);
+        const result = await passkey.addPasskey({ name: values.email, context });
+        if (result?.error) {
+          throw new Error(result.error.message ?? "Passkey registration failed");
+        }
+        await refetchSession();
+        const { data: freshSession } = await authClient.getSession();
+        if (!freshSession?.user) {
+          const signInResult = await (signIn as any).passkey();
+          if (signInResult?.error) {
+            throw new Error("Registration succeeded but sign-in failed. Please reload and sign in.");
+          }
+        }
+        await updateContext({
+          flowData: {
+            ...state?.context.flowData,
+            account: { firstName: values.firstName, lastName: values.lastName, email: values.email },
+            security: { method: "passkey" },
+          },
+        });
+        await next();
+        return;
+      }
+
+      await signUp.email(
+        {
+          name: `${values.firstName} ${values.lastName}`,
+          email: values.email,
+          password: values.password ?? "",
+        } as any,
+        {
+          onSuccess: async () => {
+            await updateContext({
+              flowData: {
+                ...state?.context.flowData,
+                account: { firstName: values.firstName, lastName: values.lastName, email: values.email },
+              },
+            });
+            await next();
+          },
+          onError: (error) => {
+            toast.error(error.error.message);
+          },
+        },
+      );
+    },
+    onError: (err: Error) => toast.error(err.message),
+  });
+};
+```
+
+- [ ] **Step 2: Update step-account-info.tsx**
+
+```typescript
+// src/features/onboarding/steps/step-account-info.tsx
+"use client";
+
+import { useEffect } from "react";
+import { useOnboarding } from "@onboardjs/react";
+import { useSession } from "@/lib/auth/auth-client";
+import { z } from "zod";
+import {
+  useZodForm,
+  Form,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormControl,
+  FormMessage,
+} from "@/components/ui/form";
+import { Input } from "@/components/ui/input";
+import { PasswordInput } from "@/components/ui/password-input";
+import { Button } from "@/components/ui/button";
+import { BaseSchema, WithPasswordSchema } from "@/features/onboarding/schemas/account.schema";
+import { useUpdateAccount } from "@/features/onboarding/hooks/use-update-account";
+import type { OnboardingMeta } from "@/features/onboarding/types";
+
+export const StepAccountInfo = () => {
+  const { next, state } = useOnboarding();
+  const { data: session, refetch: refetchSession } = useSession();
+  const meta = state?.context.flowData.meta as OnboardingMeta | undefined;
+  const existingAccount = state?.context.flowData.account;
+  const isUpdateMode = !!existingAccount;
+  const passkeyEnabled = meta?.passkeyEnabled ?? false;
+
+  useEffect(() => {
+    if (session?.user && !isUpdateMode) {
+      next();
+    }
+  }, [session?.user?.id]);
+
+  const schema = passkeyEnabled ? BaseSchema : WithPasswordSchema;
+  const form = useZodForm({ schema }) as unknown as ReturnType<
+    typeof useZodForm<typeof WithPasswordSchema>
+  >;
+
+  const mutation = useUpdateAccount(refetchSession);
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div>
+        <h1 className="text-2xl font-semibold">
+          {isUpdateMode ? "Update your account" : "Create your account"}
+        </h1>
+        <p className="text-sm text-muted-foreground mt-1">This step can&apos;t be skipped.</p>
+      </div>
+      <Form
+        form={form}
+        className="flex flex-col gap-4"
+        onSubmit={async (values) => mutation.mutateAsync(values as any)}
+      >
+        <div className="grid grid-cols-2 gap-3">
+          <FormField
+            control={form.control}
+            name="firstName"
+            defaultValue={existingAccount?.firstName ?? ""}
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel>First name</FormLabel>
+                <FormControl><Input placeholder="John" {...field} /></FormControl>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+          <FormField
+            control={form.control}
+            name="lastName"
+            defaultValue={existingAccount?.lastName ?? ""}
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel>Last name</FormLabel>
+                <FormControl><Input placeholder="Doe" {...field} /></FormControl>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+        </div>
+        <FormField
+          control={form.control}
+          name="email"
+          defaultValue={existingAccount?.email ?? ""}
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Email</FormLabel>
+              <FormControl><Input placeholder="john@example.com" {...field} /></FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        {!passkeyEnabled && !isUpdateMode && (
+          <FormField
+            control={form.control}
+            name="password"
+            defaultValue=""
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel>Password</FormLabel>
+                <FormControl><PasswordInput placeholder="Min. 8 characters" {...field} /></FormControl>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+        )}
+        <Button type="submit" disabled={mutation.isPending}>
+          {isUpdateMode
+            ? "Update account"
+            : passkeyEnabled
+              ? "Create account with passkey"
+              : "Create account"}
+        </Button>
+      </Form>
+    </div>
+  );
+};
+```
+
+- [ ] **Step 3: Verify TypeScript**
+
+```bash
+npx tsc --noEmit
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/features/onboarding/hooks/use-update-account.ts \
+        src/features/onboarding/steps/step-account-info.tsx
+git commit -m "refactor(onboarding): extract useUpdateAccount hook"
+```
+
+---
+
+### Task 5: Notifier hooks
+
+**Files:**
+- Create: `src/features/onboarding/hooks/use-add-notifier.ts`
+- Create: `src/features/onboarding/hooks/use-remove-notifier.ts`
+- Modify: `src/features/onboarding/steps/step-notifier.tsx`
+
+**Interfaces:**
+- `useAddNotifier()` → `UseMutationResult<OnboardingChannel, Error, { provider: string; name: string; config: Record<string, unknown>; label: string }>`
+- `useRemoveNotifier()` → `UseMutationResult<void, Error, string>` (mutate receives channel id)
+
+- [ ] **Step 1: Create use-add-notifier.ts**
+
+```typescript
+// src/features/onboarding/hooks/use-add-notifier.ts
+"use client";
+
+import { useMutation } from "@tanstack/react-query";
+import { useOnboarding } from "@onboardjs/react";
+import { toast } from "sonner";
+import { addNotificationChannelAction } from "@/features/channel/notifications/channel.action";
+import type { OnboardingChannel } from "@/features/onboarding/types";
+
+type NotifierInput = {
+  provider: string;
+  name: string;
+  config: Record<string, unknown>;
+  label: string;
+};
+
+export const useAddNotifier = () => {
+  const { state, updateContext } = useOnboarding();
+
+  return useMutation({
+    mutationFn: async ({ provider, name, config, label }: NotifierInput) => {
+      const orgId = (state?.context.flowData.org as any)?.id as string | undefined;
+      const result = await addNotificationChannelAction({
+        organizationId: orgId,
+        data: { provider: provider as any, name, config, enabled: true },
+      });
+      const inner = result?.data;
+      if (!inner?.success || !inner.value) throw new Error("Failed to save channel");
+
+      const channel: OnboardingChannel = { id: inner.value.id, provider, label, name, config };
+      const notifiers = [
+        ...((state?.context.flowData.notifiers ?? []) as OnboardingChannel[]),
+        channel,
+      ];
+      await updateContext({ flowData: { ...state?.context.flowData, notifiers } });
+      return channel;
+    },
+    onError: (err: Error) => toast.error(err.message),
+  });
+};
+```
+
+- [ ] **Step 2: Create use-remove-notifier.ts**
+
+```typescript
+// src/features/onboarding/hooks/use-remove-notifier.ts
+"use client";
+
+import { useMutation } from "@tanstack/react-query";
+import { useOnboarding } from "@onboardjs/react";
+import { toast } from "sonner";
+import { removeNotificationChannelAction } from "@/features/channel/notifications/channel.action";
+import type { OnboardingChannel } from "@/features/onboarding/types";
+
+export const useRemoveNotifier = () => {
+  const { state, updateContext } = useOnboarding();
+
+  return useMutation({
+    mutationFn: async (id: string) => {
+      const orgId = (state?.context.flowData.org as any)?.id as string | undefined;
+      const result = await removeNotificationChannelAction({
+        organizationId: orgId,
+        notificationChannelId: id,
+      });
+      if (result?.data?.success === false) throw new Error("Failed to remove channel");
+      const notifiers = (
+        (state?.context.flowData.notifiers ?? []) as OnboardingChannel[]
+      ).filter((c) => c.id !== id);
+      await updateContext({ flowData: { ...state?.context.flowData, notifiers } });
+    },
+    onError: (err: Error) => toast.error(err.message),
+  });
+};
+```
+
+- [ ] **Step 3: Update step-notifier.tsx**
+
+Replace the full file:
+
+```typescript
+// src/features/onboarding/steps/step-notifier.tsx
+"use client";
+
+import { useState } from "react";
+import { useOnboarding } from "@onboardjs/react";
+import { ArrowLeft, Check, X } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import {
+  useZodForm,
+  Form,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormControl,
+  FormMessage,
+} from "@/components/ui/form";
+import { notificationProviders } from "@/features/channel/channels-notification-helper";
+import { renderChannelForm } from "@/features/channel/channels-helpers";
+import { NotificationChannelFormSchema } from "@/features/channel/channel-form.schema";
+import { useAddNotifier } from "@/features/onboarding/hooks/use-add-notifier";
+import { useRemoveNotifier } from "@/features/onboarding/hooks/use-remove-notifier";
+import type { OnboardingChannel } from "@/features/onboarding/types";
+
+type Phase = { kind: "grid" } | { kind: "configuring"; provider: string };
+
+export const StepNotifier = () => {
+  const { next, updateContext, state } = useOnboarding();
+  const notifiers = (state?.context.flowData.notifiers ?? []) as OnboardingChannel[];
+  const [phase, setPhase] = useState<Phase>({ kind: "grid" });
+  const form = useZodForm({ schema: NotificationChannelFormSchema });
+
+  const addNotifier = useAddNotifier();
+  const removeNotifier = useRemoveNotifier();
+
+  const startConfiguring = (provider: string) => {
+    if (notifiers.some((c) => c.provider === provider)) return;
+    form.reset({ provider, enabled: true, name: "", config: {} } as any);
+    setPhase({ kind: "configuring", provider });
+  };
+
+  const onContinue = async () => {
+    await updateContext({ flowData: { ...state?.context.flowData, notifiers } });
+    await next();
+  };
+
+  if (phase.kind === "configuring") {
+    const providerDetails = notificationProviders.find((p) => p.value === phase.provider);
+    const Icon = providerDetails?.icon;
+
+    return (
+      <div className="flex flex-col gap-4">
+        <div className="flex items-center gap-3 p-3 bg-secondary/30 rounded-lg border border-border">
+          {Icon && (
+            <div className="size-9 rounded-md border bg-muted/50 shadow-sm flex items-center justify-center">
+              <Icon className="size-5" />
+            </div>
+          )}
+          <p className="flex-1 text-sm font-medium">Configuring {providerDetails?.label}</p>
+          <Button type="button" variant="ghost" size="sm" onClick={() => setPhase({ kind: "grid" })}>
+            <ArrowLeft className="size-4 mr-1" />
+            Back
+          </Button>
+        </div>
+        <Form
+          form={form}
+          className="flex flex-col gap-4"
+          onSubmit={async (values: any) => {
+            const details = notificationProviders.find((p) => p.value === values.provider);
+            addNotifier.mutate(
+              {
+                provider: values.provider,
+                name: values.name,
+                config: values.config,
+                label: details?.label ?? values.provider,
+              },
+              {
+                onSuccess: () => {
+                  form.reset({ enabled: true } as any);
+                  setPhase({ kind: "grid" });
+                },
+              },
+            );
+          }}
+        >
+          <FormField
+            control={form.control}
+            name="name"
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel>Channel name *</FormLabel>
+                <FormControl>
+                  <Input
+                    {...field}
+                    value={field.value ?? ""}
+                    placeholder={`e.g. ${providerDetails?.label ?? ""} alerts`}
+                  />
+                </FormControl>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+          <FormField
+            control={form.control}
+            name="provider"
+            render={({ field }) => (
+              <input type="hidden" {...field} value={field.value || ""} />
+            )}
+          />
+          {renderChannelForm(phase.provider, form)}
+          <Button type="submit" disabled={addNotifier.isPending}>
+            {addNotifier.isPending ? "Saving…" : "Add channel"}
+          </Button>
+        </Form>
+      </div>
+    );
+  }
+
+  const configuredProviderIds = notifiers.map((c) => c.provider);
+  const availableProviders = notificationProviders.filter((p) => !p.preview);
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div>
+        <h1 className="text-2xl font-semibold">Connect a notifier</h1>
+        <p className="text-sm text-muted-foreground mt-1">
+          Optional — get notified about backups, restores and health checks.
+        </p>
+      </div>
+
+      {notifiers.length > 0 && (
+        <div className="flex flex-col gap-1">
+          {notifiers.map((ch) => {
+            const details = notificationProviders.find((p) => p.value === ch.provider);
+            const Icon = details?.icon;
+            return (
+              <div
+                key={ch.id}
+                className="flex items-center gap-2 rounded-lg border border-primary/20 bg-primary/10 p-2 text-sm text-primary"
+              >
+                {Icon && (
+                  <div className="size-7 rounded-md border bg-muted/50 flex items-center justify-center shrink-0">
+                    <Icon className="size-4" />
+                  </div>
+                )}
+                <span className="flex-1 truncate">
+                  {ch.name} <span className="opacity-60">({ch.label})</span>
+                </span>
+                <button
+                  type="button"
+                  onClick={() => removeNotifier.mutate(ch.id)}
+                  disabled={removeNotifier.isPending}
+                  className="opacity-50 hover:opacity-100 transition-opacity"
+                >
+                  <X className="size-4" />
+                </button>
+              </div>
+            );
+          })}
+        </div>
+      )}
+
+      <div className="grid grid-cols-2 gap-2">
+        {availableProviders.map((provider) => {
+          const Icon = provider.icon;
+          const isConfigured = configuredProviderIds.includes(provider.value);
+          return (
+            <button
+              key={provider.value}
+              type="button"
+              onClick={() => startConfiguring(provider.value)}
+              className={`flex items-center gap-2 rounded-lg border p-2 text-sm transition-colors ${
+                isConfigured
+                  ? "border-primary/20 bg-primary/10 text-primary"
+                  : "border-border hover:bg-accent/50 hover:border-primary/20"
+              }`}
+            >
+              <div className="size-9 rounded-md border bg-muted/50 shadow-sm flex items-center justify-center shrink-0">
+                <Icon className="size-4" />
+              </div>
+              <span className="flex-1 text-left">{provider.label}</span>
+              {isConfigured && (
+                <div className="size-5 rounded-full bg-primary flex items-center justify-center ml-auto">
+                  <Check className="size-3 text-primary-foreground" strokeWidth={3} />
+                </div>
+              )}
+            </button>
+          );
+        })}
+      </div>
+
+      <Button type="button" onClick={onContinue}>
+        Continue
+      </Button>
+    </div>
+  );
+};
+```
+
+- [ ] **Step 4: Verify TypeScript**
+
+```bash
+npx tsc --noEmit
+```
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/features/onboarding/hooks/use-add-notifier.ts \
+        src/features/onboarding/hooks/use-remove-notifier.ts \
+        src/features/onboarding/steps/step-notifier.tsx
+git commit -m "refactor(onboarding): extract useAddNotifier and useRemoveNotifier hooks"
+```
+
+---
+
+### Task 6: Storage hooks
+
+**Files:**
+- Create: `src/features/onboarding/hooks/use-add-storage.ts`
+- Create: `src/features/onboarding/hooks/use-remove-storage.ts`
+- Modify: `src/features/onboarding/steps/step-storage.tsx`
+
+**Interfaces:**
+- `useAddStorage()` → `UseMutationResult<OnboardingChannel, Error, { provider: string; name: string; config: Record<string, unknown>; label: string }>`
+- `useRemoveStorage()` → `UseMutationResult<void, Error, string>`
+
+- [ ] **Step 1: Create use-add-storage.ts**
+
+```typescript
+// src/features/onboarding/hooks/use-add-storage.ts
+"use client";
+
+import { useMutation } from "@tanstack/react-query";
+import { useOnboarding } from "@onboardjs/react";
+import { toast } from "sonner";
+import { addStorageChannelAction } from "@/features/channel/storages/channel.action";
+import type { OnboardingChannel } from "@/features/onboarding/types";
+
+type StorageInput = {
+  provider: string;
+  name: string;
+  config: Record<string, unknown>;
+  label: string;
+};
+
+export const useAddStorage = () => {
+  const { state, updateContext } = useOnboarding();
+
+  return useMutation({
+    mutationFn: async ({ provider, name, config, label }: StorageInput) => {
+      const orgId = (state?.context.flowData.org as any)?.id as string | undefined;
+      const result = await addStorageChannelAction({
+        organizationId: orgId,
+        data: { provider: provider as any, name, config, enabled: true },
+      });
+      const inner = result?.data;
+      if (!inner?.success || !inner.value) throw new Error("Failed to save storage");
+
+      const channel: OnboardingChannel = { id: inner.value.id, provider, label, name, config };
+      const storages = [
+        ...((state?.context.flowData.storages ?? []) as OnboardingChannel[]),
+        channel,
+      ];
+      await updateContext({ flowData: { ...state?.context.flowData, storages } });
+      return channel;
+    },
+    onError: (err: Error) => toast.error(err.message),
+  });
+};
+```
+
+- [ ] **Step 2: Create use-remove-storage.ts**
+
+```typescript
+// src/features/onboarding/hooks/use-remove-storage.ts
+"use client";
+
+import { useMutation } from "@tanstack/react-query";
+import { useOnboarding } from "@onboardjs/react";
+import { toast } from "sonner";
+import { removeStorageChannelAction } from "@/features/channel/storages/channel.action";
+import type { OnboardingChannel } from "@/features/onboarding/types";
+
+export const useRemoveStorage = () => {
+  const { state, updateContext } = useOnboarding();
+
+  return useMutation({
+    mutationFn: async (id: string) => {
+      const orgId = (state?.context.flowData.org as any)?.id as string | undefined;
+      const result = await removeStorageChannelAction({ organizationId: orgId, id });
+      if (result?.data?.success === false) throw new Error("Failed to remove storage");
+      const storages = (
+        (state?.context.flowData.storages ?? []) as OnboardingChannel[]
+      ).filter((c) => c.id !== id);
+      await updateContext({ flowData: { ...state?.context.flowData, storages } });
+    },
+    onError: (err: Error) => toast.error(err.message),
+  });
+};
+```
+
+- [ ] **Step 3: Update step-storage.tsx**
+
+Replace the full file:
+
+```typescript
+// src/features/onboarding/steps/step-storage.tsx
+"use client";
+
+import { useState } from "react";
+import { useOnboarding } from "@onboardjs/react";
+import { ArrowLeft, Check, X } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import {
+  useZodForm,
+  Form,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormControl,
+  FormMessage,
+} from "@/components/ui/form";
+import { storageProviders } from "@/features/channel/channels-storage-helper";
+import { renderChannelForm } from "@/features/channel/channels-helpers";
+import { StorageChannelFormSchema } from "@/features/channel/channel-form.schema";
+import { useAddStorage } from "@/features/onboarding/hooks/use-add-storage";
+import { useRemoveStorage } from "@/features/onboarding/hooks/use-remove-storage";
+import type { OnboardingChannel } from "@/features/onboarding/types";
+
+type Phase = { kind: "grid" } | { kind: "configuring"; provider: string };
+
+export const StepStorage = () => {
+  const { next, updateContext, state } = useOnboarding();
+  const storages = (state?.context.flowData.storages ?? []) as OnboardingChannel[];
+  const [phase, setPhase] = useState<Phase>({ kind: "grid" });
+  const form = useZodForm({ schema: StorageChannelFormSchema });
+
+  const addStorage = useAddStorage();
+  const removeStorage = useRemoveStorage();
+
+  const startConfiguring = (provider: string) => {
+    if (storages.some((c) => c.provider === provider)) return;
+    form.reset({ provider, enabled: true, name: "", config: {} } as any);
+    setPhase({ kind: "configuring", provider });
+  };
+
+  const onContinue = async () => {
+    await updateContext({ flowData: { ...state?.context.flowData, storages } });
+    await next();
+  };
+
+  if (phase.kind === "configuring") {
+    const providerDetails = storageProviders.find((p) => p.value === phase.provider);
+    const Icon = providerDetails?.icon;
+
+    return (
+      <div className="flex flex-col gap-4">
+        <div className="flex items-center gap-3 p-3 bg-secondary/30 rounded-lg border border-border">
+          {Icon && (
+            <div className="size-9 rounded-md border bg-muted/50 shadow-sm flex items-center justify-center">
+              <Icon className="size-5" />
+            </div>
+          )}
+          <p className="flex-1 text-sm font-medium">Configuring {providerDetails?.label}</p>
+          <Button type="button" variant="ghost" size="sm" onClick={() => setPhase({ kind: "grid" })}>
+            <ArrowLeft className="size-4 mr-1" />
+            Back
+          </Button>
+        </div>
+        <Form
+          form={form}
+          className="flex flex-col gap-4"
+          onSubmit={async (values: any) => {
+            const details = storageProviders.find((p) => p.value === values.provider);
+            addStorage.mutate(
+              {
+                provider: values.provider,
+                name: values.name,
+                config: values.config,
+                label: details?.label ?? values.provider,
+              },
+              {
+                onSuccess: () => {
+                  form.reset({ enabled: true } as any);
+                  setPhase({ kind: "grid" });
+                },
+              },
+            );
+          }}
+        >
+          <FormField
+            control={form.control}
+            name="name"
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel>Channel name *</FormLabel>
+                <FormControl>
+                  <Input
+                    {...field}
+                    value={field.value ?? ""}
+                    placeholder={`e.g. ${providerDetails?.label ?? ""} backup`}
+                  />
+                </FormControl>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+          <FormField
+            control={form.control}
+            name="provider"
+            render={({ field }) => (
+              <input type="hidden" {...field} value={field.value || ""} />
+            )}
+          />
+          {renderChannelForm(phase.provider, form)}
+          <Button type="submit" disabled={addStorage.isPending}>
+            {addStorage.isPending ? "Saving…" : "Add storage"}
+          </Button>
+        </Form>
+      </div>
+    );
+  }
+
+  const availableProviders = storageProviders.filter((p) => !p.preview && p.value !== "local");
+  const configuredProviderIds = storages.map((c) => c.provider);
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div>
+        <h1 className="text-2xl font-semibold">Connect a storage</h1>
+        <p className="text-sm text-muted-foreground mt-1">
+          Optional — choose where backups and files are stored.
+        </p>
+      </div>
+
+      {storages.length > 0 && (
+        <div className="flex flex-col gap-1">
+          {storages.map((ch) => {
+            const details = storageProviders.find((p) => p.value === ch.provider);
+            const Icon = details?.icon;
+            return (
+              <div
+                key={ch.id}
+                className="flex items-center gap-2 rounded-lg border border-primary/20 bg-primary/10 p-2 text-sm text-primary"
+              >
+                {Icon && (
+                  <div className="size-7 rounded-md border bg-muted/50 flex items-center justify-center shrink-0">
+                    <Icon className="size-4" />
+                  </div>
+                )}
+                <span className="flex-1 truncate">
+                  {ch.name} <span className="opacity-60">({ch.label})</span>
+                </span>
+                <button
+                  type="button"
+                  onClick={() => removeStorage.mutate(ch.id)}
+                  disabled={removeStorage.isPending}
+                  className="opacity-50 hover:opacity-100 transition-opacity"
+                >
+                  <X className="size-4" />
+                </button>
+              </div>
+            );
+          })}
+        </div>
+      )}
+
+      <div className="grid grid-cols-2 gap-2">
+        {availableProviders.map((provider) => {
+          const Icon = provider.icon;
+          const isConfigured = configuredProviderIds.includes(provider.value);
+          return (
+            <button
+              key={provider.value}
+              type="button"
+              onClick={() => startConfiguring(provider.value)}
+              className={`flex items-center gap-2 rounded-lg border p-2 text-sm transition-colors ${
+                isConfigured
+                  ? "border-primary/20 bg-primary/10 text-primary"
+                  : "border-border hover:bg-accent/50 hover:border-primary/20"
+              }`}
+            >
+              <div className="size-9 rounded-md border bg-muted/50 shadow-sm flex items-center justify-center shrink-0">
+                <Icon className="size-4" />
+              </div>
+              <span className="flex-1 text-left">{provider.label}</span>
+              {isConfigured && (
+                <div className="size-5 rounded-full bg-primary flex items-center justify-center ml-auto">
+                  <Check className="size-3 text-primary-foreground" strokeWidth={3} />
+                </div>
+              )}
+            </button>
+          );
+        })}
+      </div>
+
+      <Button type="button" onClick={onContinue}>
+        Continue
+      </Button>
+    </div>
+  );
+};
+```
+
+- [ ] **Step 4: Verify TypeScript**
+
+```bash
+npx tsc --noEmit
+```
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/features/onboarding/hooks/use-add-storage.ts \
+        src/features/onboarding/hooks/use-remove-storage.ts \
+        src/features/onboarding/steps/step-storage.tsx
+git commit -m "refactor(onboarding): extract useAddStorage and useRemoveStorage hooks"
+```
+
+---
+
+### Task 7: Agent status + edge key hooks
+
+**Files:**
+- Create: `src/features/onboarding/hooks/use-agent-status.ts`
+- Create: `src/features/onboarding/hooks/use-generate-edge-key.ts`
+- Modify: `src/features/onboarding/steps/step-agent-waiting.tsx`
+- Modify: `src/features/onboarding/steps/step-agent-key.tsx`
+
+**Interfaces:**
+- `useAgentStatus()` → `UseQueryResult<{ connected: boolean }, Error>`
+- `useGenerateEdgeKey(agentId: string)` → `UseQueryResult<string, Error>`
+
+- [ ] **Step 1: Create use-agent-status.ts**
+
+```typescript
+// src/features/onboarding/hooks/use-agent-status.ts
+"use client";
+
+import { useQuery } from "@tanstack/react-query";
+import { useOnboarding } from "@onboardjs/react";
+import { getAgentStatusAction } from "@/features/onboarding/actions/get-agent-status.action";
+import type { OnboardingAgent } from "@/features/onboarding/types";
+
+export const useAgentStatus = () => {
+  const { state } = useOnboarding();
+  const agents = (state?.context.flowData.agents ?? []) as OnboardingAgent[];
+  const firstAgentId = agents[0]?.id;
+
+  return useQuery({
+    queryKey: ["onboarding-agent-status", firstAgentId],
+    queryFn: async () => {
+      if (!firstAgentId) return { connected: false };
+      const result = await getAgentStatusAction({ agentId: firstAgentId });
+      return result?.data ?? { connected: false };
+    },
+    refetchInterval: 3_000,
+    enabled: !!firstAgentId,
+  });
+};
+```
+
+- [ ] **Step 2: Update step-agent-waiting.tsx**
+
+```typescript
+// src/features/onboarding/steps/step-agent-waiting.tsx
+"use client";
+
+import { useEffect } from "react";
+import { useOnboarding } from "@onboardjs/react";
+import { Loader2 } from "lucide-react";
+import { useAgentStatus } from "@/features/onboarding/hooks/use-agent-status";
+import type { OnboardingAgent } from "@/features/onboarding/types";
+
+export const StepAgentWaiting = () => {
+  const { next, state } = useOnboarding();
+  const agents = (state?.context.flowData.agents ?? []) as OnboardingAgent[];
+  const { data } = useAgentStatus();
+
+  useEffect(() => {
+    if (data?.connected) {
+      next();
+    }
+  }, [data?.connected, next]);
+
+  return (
+    <div className="flex flex-col items-center justify-center gap-4 h-full text-center">
+      <Loader2 className="size-10 animate-spin text-primary" />
+      <h1 className="text-xl font-semibold">Waiting for your agent</h1>
+      <p className="text-sm text-muted-foreground">Checking connectivity every 3 seconds…</p>
+      {agents.length > 0 && (
+        <p className="text-xs text-muted-foreground">Agent: {agents[0].name}</p>
+      )}
+    </div>
+  );
+};
+```
+
+- [ ] **Step 3: Create use-generate-edge-key.ts**
+
+```typescript
+// src/features/onboarding/hooks/use-generate-edge-key.ts
+"use client";
+
+import { useQuery } from "@tanstack/react-query";
+import { generateEdgeKeyAction } from "@/features/onboarding/actions/generate-edge-key.action";
+
+export const useGenerateEdgeKey = (agentId: string) => {
+  return useQuery({
+    queryKey: ["onboarding-edge-key", agentId],
+    queryFn: async () => {
+      const result = await generateEdgeKeyAction({ agentId });
+      if (!result?.data?.key) throw new Error("Failed to generate key");
+      return result.data.key;
+    },
+    staleTime: Infinity,
+    enabled: !!agentId,
+  });
+};
+```
+
+- [ ] **Step 4: Update step-agent-key.tsx**
+
+```typescript
+// src/features/onboarding/steps/step-agent-key.tsx
+"use client";
+
+import { useOnboarding } from "@onboardjs/react";
+import { Loader2 } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { CodeSnippet } from "@/components/common/code-snippet";
+import { useGenerateEdgeKey } from "@/features/onboarding/hooks/use-generate-edge-key";
+import type { OnboardingAgent } from "@/features/onboarding/types";
+
+export const StepAgentKey = () => {
+  const { next, state } = useOnboarding();
+  const agents = (state?.context.flowData.agents ?? []) as OnboardingAgent[];
+
+  return (
+    <div className="flex flex-col gap-6">
+      <div>
+        <h1 className="text-2xl font-semibold">Connect your agent</h1>
+        <p className="text-sm text-muted-foreground mt-1">
+          Run the command below on your server. The next step waits for the agent to connect.
+        </p>
+      </div>
+      {agents.map((agent) => (
+        <AgentKeyBlock key={agent.id} agent={agent} />
+      ))}
+      <Button type="button" onClick={() => next()}>
+        I&apos;ve run the command →
+      </Button>
+    </div>
+  );
+};
+
+const AgentKeyBlock = ({ agent }: { agent: OnboardingAgent }) => {
+  const { data, isLoading } = useGenerateEdgeKey(agent.id);
+
+  if (isLoading) {
+    return (
+      <div className="flex items-center gap-2 text-sm text-muted-foreground">
+        <Loader2 className="size-4 animate-spin" />
+        Generating key for {agent.name}…
+      </div>
+    );
+  }
+
+  const command = `portabase agent "${agent.name}" --key ${data}`;
+
+  return (
+    <div className="flex flex-col gap-3 p-4 rounded-lg border border-border">
+      <p className="text-sm font-medium">{agent.name}</p>
+      <CodeSnippet title="Installation Command" code={command} />
+      <CodeSnippet title="Agent Key (manual)" code={data ?? ""} />
+    </div>
+  );
+};
+```
+
+- [ ] **Step 5: Verify TypeScript**
+
+```bash
+npx tsc --noEmit
+```
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/features/onboarding/hooks/use-agent-status.ts \
+        src/features/onboarding/hooks/use-generate-edge-key.ts \
+        src/features/onboarding/steps/step-agent-waiting.tsx \
+        src/features/onboarding/steps/step-agent-key.tsx
+git commit -m "refactor(onboarding): extract useAgentStatus and useGenerateEdgeKey hooks"
+```
+
+---
+
+### Task 8: Mark-done hook
+
+**Files:**
+- Create: `src/features/onboarding/hooks/use-mark-onboarding-done.ts`
+- Modify: `src/features/onboarding/steps/step-finish.tsx`
+
+**Interfaces:**
+- `useMarkOnboardingDone()` → `UseMutationResult<unknown, Error, void>`
+
+- [ ] **Step 1: Create use-mark-onboarding-done.ts**
+
+```typescript
+// src/features/onboarding/hooks/use-mark-onboarding-done.ts
+"use client";
+
+import { useMutation } from "@tanstack/react-query";
+import { markOnboardingDoneAction } from "@/features/onboarding/actions/onboarding-mark-done.action";
+
+export const useMarkOnboardingDone = () => {
+  return useMutation({
+    mutationFn: async () => {
+      const result = await markOnboardingDoneAction({});
+      if (!result?.data) throw new Error("Failed to mark onboarding done");
+      return result.data;
+    },
+  });
+};
+```
+
+- [ ] **Step 2: Update step-finish.tsx**
+
+```typescript
+// src/features/onboarding/steps/step-finish.tsx
+"use client";
+
+import { useEffect, useRef } from "react";
+import { useOnboarding } from "@onboardjs/react";
+import confetti from "canvas-confetti";
+import { CheckCircle2 } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { useMarkOnboardingDone } from "@/features/onboarding/hooks/use-mark-onboarding-done";
+
+export const StepFinish = () => {
+  const { next } = useOnboarding();
+  const fired = useRef(false);
+  const mutation = useMarkOnboardingDone();
+
+  useEffect(() => {
+    if (fired.current) return;
+    fired.current = true;
+    confetti({ particleCount: 150, spread: 80, origin: { y: 0.6 } });
+  }, []);
+
+  return (
+    <div className="flex flex-col items-center justify-center gap-4 h-full text-center">
+      <CheckCircle2 className="size-16 text-green-500" />
+      <h1 className="text-2xl font-semibold">You&apos;re all set!</h1>
+      <p className="text-sm text-muted-foreground">Your workspace is ready to use.</p>
+      <Button
+        type="button"
+        disabled={mutation.isPending}
+        onClick={async () => {
+          await mutation.mutateAsync();
+          await next();
+        }}
+      >
+        Go to dashboard
+      </Button>
+    </div>
+  );
+};
+```
+
+- [ ] **Step 3: Verify TypeScript**
+
+```bash
+npx tsc --noEmit
+```
+
+- [ ] **Step 4: Delete .gitkeep files now that directories are populated**
+
+```bash
+rm src/features/onboarding/constants/.gitkeep
+rm src/features/onboarding/hooks/.gitkeep
+rm src/features/onboarding/schemas/.gitkeep
+rm src/features/onboarding/types/.gitkeep
+```
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/features/onboarding/hooks/use-mark-onboarding-done.ts \
+        src/features/onboarding/steps/step-finish.tsx
+git add -u src/features/onboarding/constants/ \
+           src/features/onboarding/hooks/ \
+           src/features/onboarding/schemas/ \
+           src/features/onboarding/types/
+git commit -m "refactor(onboarding): extract useMarkOnboardingDone hook, remove .gitkeep files"
+```