bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/dist/ai/recipes/nuxt/onboarding.md

@@ -0,0 +1,1724 @@
+---
+title: Workspace Onboarding (Nuxt)
+summary: Full-anatomy workspace onboarding for Nuxt — a live BbProgress header, an accordion checklist whose steps do the real work inline (integration switches, tag-input invites, a mini project form, CSV import with real byte progress), data loaded with useAsyncData and mutations resolved through $fetch + refresh(), all through one coopting page context.
+---
+
+# Recipe: Workspace Onboarding (Nuxt)
+
+The onboarding checklist adapted for **Nuxt**: the same live progress header,
+single-open accordion whose steps carry the real actions inline, and "see
+what you'll get" preview peeks — but the checklist state loads through
+`useAsyncData` and every mutation is a `$fetch` call followed by `refresh()`,
+so the server stays the single source of truth for step statuses. Anatomy,
+components, the context shape, copy and data are identical to the Vue
+recipe; only the data/mutation layer changes.
+
+Sibling recipes: [Vue](../vue/onboarding.md) ·
+[Inertia](../inertia/onboarding.md).
+
+## Prerequisites
+
+- **[Layout Scaffold](./layout-scaffold.md) — build it first.** This recipe
+  imports `PageShell` and `usePageShellContext` from your own app.
+  They are not package exports; the scaffold recipe is their source. Copy
+  those files before anything below, and do not hand-roll replacements —
+  the peek stack, the close semantics and the sidebar's out-of-flow
+  behaviour are all load-bearing here.
+- `<BbConfirm />` and `<BbToast />` mounted once in `app.vue` — never in a page.
+- [App Layout](../../guides/app-layout.md) and
+  [Page Shell](../../guides/page-shell.md) copied into `src/components/layout/`
+  per their guides — this page assumes the chrome exists and renders inside
+  it.
+- Server routes: `GET /api/onboarding` (returns `{ steps, connectedIntegrations,
+workspace, invites, firstProject, importedCustomers, reminders }`), plus the
+  mutation routes referenced below (`PATCH /api/onboarding/steps/:id`,
+  `POST /api/onboarding/integrations/:id/connect`,
+  `POST /api/onboarding/invites`, `POST /api/onboarding/project`,
+  `POST /api/onboarding/customers/import`, `PATCH /api/onboarding/reminders`,
+  `POST /api/onboarding/dismiss`).
+
+## Key ideas
+
+- **One coopting page context.** `provideOnboardingWorkspace()` joins the
+  page-shell stack once, owns the step statuses, the integration and invite
+  state, and every action. Every leaf calls `useOnboardingWorkspace()` and
+  nothing else — zero prop drilling anywhere on the page.
+- **`useAsyncData` loads the checklist once; every mutation ends in
+  `refresh()`.** There is exactly one status writer path: `$fetch` the
+  mutation, then `refresh()` re-pulls `/api/onboarding` and a single watcher
+  re-seeds every local field (`steps`, `integrations`, `invites`,
+  `firstProject`, `reminders`) from the fresh response — no mutation patches
+  local state by hand except the optimistic switches.
+- **Steps act inline; the checklist ticks itself.** Each step body _is_ the
+  feature: switches connect integrations, a tag input sends invites, a mini
+  form creates the project, a dropzone imports the CSV. Completing the real
+  action persists the step status through one private `persistStatus` —
+  the same verb the manual "Mark as done" / "Skip for now" ghosts use.
+- **Single-open accordion, modeled — not wrapped.** `BbAccordion` is one
+  panel per boolean; there is no group component by design. One
+  `activeStep` key in the context derives every panel's `model-value`, and
+  finishing a step advances the key to the next unfinished one.
+- **CSV upload progress needs raw `XMLHttpRequest`.** `ofetch` (Nuxt's
+  `$fetch`) has no upload-progress hook, so the one import mutation wraps
+  `XMLHttpRequest` directly to drive real bytes into `BbProgress`; every
+  other mutation on the page uses `$fetch`.
+- **Previews ride the shell stack.** "See what you'll get" pushes a
+  `step-preview` peek (replace semantics — previews never stack); the peek
+  is a workbench: identity header, benefit list, a stat, and a "Set it up
+  now" action that jumps back to the step.
+- **Checklist archetype, so rows 4/5/7/8 of the standard anatomy don't
+  apply**: no filter rail, no tabs, no pagination, no selection/bulk bar —
+  and no page search, since the page has no filterable collection. Page
+  Shell, breadcrumbs topbar and the stacked peek sidebar stay.
+- **Buttons are `md` by default**; one `variant="primary"` on the page
+  ("Go to dashboard" in the topbar); step submits are `secondary`,
+  done/skip/preview are `ghost`; "Dismiss onboarding" rides `useConfirm`.
+
+## Page anatomy
+
+```
+OnboardingChecklist/
+	Index.vue                ← assembly: PageShell slots, accordion loop, thin
+	context.ts               ← coopting page context (shell + useAsyncData + actions)
+	ProgressHeader.vue       ← title, dismiss, BbProgress + "4 of 7 complete"
+	StepHeader.vue           ← status icon, title, minutes, chevron (in the header button)
+	StepActions.vue          ← per-step done / skip / preview footer row
+	ProfileStep.vue          ← step 1 body: completed-at-signup summary + edit link
+	IntegrationsStep.vue     ← step 2 body: BbSwitch rows (Stripe, QuickBooks, Slack, Drive)
+	InviteStep.vue           ← step 3 body: BbTag emails + role BbSelect + send
+	FirstProjectStep.vue     ← step 4 body: mini create-project form
+	ImportCustomersStep.vue  ← step 5 body: BbDropzone CSV + BbProgress upload
+	FirstInvoiceStep.vue     ← step 6 body: link-out to the invoice composer
+	RemindersStep.vue        ← step 7 body: reminders switch + cadence select
+	StepPreviewPeek.vue      ← sidebar "what you'll get" workbench per step
+```
+
+Chrome assumed from the guides: [App Layout](../../guides/app-layout.md)
+(left nav + fat footer) and [Page Shell](../../guides/page-shell.md). The
+dismiss confirmation renders through the app-wide `useConfirm` host, so this
+page needs no `#dialogs` content of its own.
+
+## Action inventory
+
+| #   | Action                           | Trigger                             | Mechanism                                                          |
+| --- | -------------------------------- | ----------------------------------- | ------------------------------------------------------------------ |
+| 1   | Go to dashboard                  | topbar, the page's one `primary`    | navigation (`/dashboard`)                                          |
+| 2   | Dismiss onboarding               | progress header, ghost              | `useConfirm` (destructive) → `$fetch` + `navigateTo` + toast       |
+| 3   | Expand / collapse a step         | accordion header (single-open)      | `activeStep` key derives each panel's `model-value`                |
+| 4   | See what you'll get              | every step footer                   | `previewStep(id)` → shell peek (replace)                           |
+| 5   | Mark step done / skip step       | step footer ghosts                  | `completeStep` / `skipStep` → `$fetch` + `refresh()`               |
+| 6   | Connect / disconnect integration | switch rows in _Connect your tools_ | optimistic toggle, `readonly` in flight, revert + toast on failure |
+| 7   | Compose the invite list          | `BbTag` (Enter/comma, max 10)       | local ref; `duplicate`/`max` surfaced via `errors`                 |
+| 8   | Choose the invite role           | `BbSelect` beside the tags          | local ref                                                          |
+| 9   | Send invitations                 | secondary button in step body       | `sendInvites` → `$fetch` + auto-complete + toast                   |
+| 10  | Create the first project         | mini form submit                    | `createProject` → `$fetch` + auto-complete + toast                 |
+| 11  | Import customers CSV             | `BbDropzone` + Import button        | `importCustomers`; `BbProgress` driven by real XHR upload bytes    |
+| 12  | Open the invoice composer        | outline button in step 6            | navigation (`/invoices/create`)                                    |
+| 13  | Turn reminders on / pick cadence | switch + select in step 7           | `setReminders` / `setReminderCadence` + toast                      |
+| 14  | Jump to a step from its preview  | peek footer                         | `jumpToStep(id)` → open step + close peek                          |
+| 15  | Edit the workspace profile       | link in the completed profile step  | navigation (`/settings/general`)                                   |
+| 16  | Close the peek                   | shell chrome                        | shell stack close                                                  |
+
+## The code
+
+### context.ts
+
+```ts
+// OnboardingChecklist/context.ts
+import {
+	computed,
+	inject,
+	provide,
+	reactive,
+	ref,
+	watch,
+	type ComputedRef,
+	type InjectionKey,
+	type Ref,
+} from 'vue';
+import { useConfirm, useToast } from 'bitboss-ui';
+import {
+	usePageShellContext,
+	type PageShellContext,
+} from '@/components/layout/usePageShellContext';
+import type {
+	InviteRole,
+	PendingInvite,
+	Project,
+	ProjectDraft,
+	ReminderCadence,
+	WorkspaceProfile,
+} from '@/types';
+
+export type StepId =
+	| 'profile'
+	| 'integrations'
+	| 'invites'
+	| 'first-project'
+	| 'import-customers'
+	| 'first-invoice'
+	| 'reminders';
+
+export type StepStatus = 'todo' | 'complete' | 'skipped';
+
+export interface OnboardingStep {
+	id: StepId;
+	title: string;
+	description: string;
+	/** Rough time estimate shown in the header while the step is open. */
+	minutes: number;
+	status: StepStatus;
+}
+
+export interface WorkspaceIntegration {
+	id: string;
+	name: string;
+	description: string;
+	/** Full static literal — the production icon scanner only bundles names it can see. */
+	icon: string;
+	connected: boolean;
+	/** True while a connect/disconnect request is in flight (drives `readonly`). */
+	busy: boolean;
+}
+
+/** What the stacked sidebar can show: the per-step "what you'll get" preview. */
+export type PeekItem = { type: 'step-preview'; stepId: StepId };
+
+/** The whole `/api/onboarding` response — the single source of truth. */
+type OnboardingState = {
+	steps: Record<StepId, StepStatus>;
+	connectedIntegrations: string[];
+	workspace: WorkspaceProfile;
+	invites: PendingInvite[];
+	firstProject: Project | null;
+	importedCustomers: number | null;
+	reminders: { enabled: boolean; cadence: ReminderCadence };
+};
+
+export interface OnboardingWorkspaceContext {
+	// -- Coopted contexts ------------------------------------------------------
+	shell: PageShellContext<PeekItem>;
+	// -- Page-owned state ------------------------------------------------------
+	steps: OnboardingStep[];
+	/** The one open panel; `null` collapses everything (single-open accordion). */
+	activeStep: Ref<StepId | null>;
+	/** Steps no longer todo (complete or skipped) — drives the progress bar. */
+	doneCount: ComputedRef<number>;
+	allDone: ComputedRef<boolean>;
+	workspace: Ref<WorkspaceProfile | null>;
+	integrations: WorkspaceIntegration[];
+	invites: Ref<PendingInvite[]>;
+	firstProject: Ref<Project | null>;
+	importState: {
+		uploading: boolean;
+		sentBytes: number;
+		totalBytes: number;
+		importedCount: number | null;
+	};
+	reminders: { enabled: boolean; cadence: ReminderCadence };
+	// -- Step grammar ----------------------------------------------------------
+	openStep: (id: StepId | null) => void;
+	previewStep: (id: StepId) => void;
+	jumpToStep: (id: StepId) => void;
+	// -- Actions (complete: $fetch + refresh + toast) ----------------------------
+	completeStep: (id: StepId) => Promise<void>;
+	skipStep: (id: StepId) => Promise<void>;
+	toggleIntegration: (
+		integration: WorkspaceIntegration,
+		next: boolean
+	) => Promise<void>;
+	sendInvites: (emails: string[], role: InviteRole) => Promise<void>;
+	createProject: (draft: ProjectDraft) => Promise<void>;
+	importCustomers: (file: File) => Promise<void>;
+	setReminders: (enabled: boolean) => Promise<void>;
+	setReminderCadence: (cadence: ReminderCadence) => Promise<void>;
+	dismissOnboarding: () => Promise<void>;
+}
+
+const key: InjectionKey<OnboardingWorkspaceContext> = Symbol(
+	'onboarding-workspace'
+);
+
+// ofetch has no upload-progress hook, so the one import mutation drives real
+// bytes through a plain XMLHttpRequest instead — every other mutation below
+// uses $fetch.
+const uploadWithProgress = (
+	url: string,
+	body: FormData,
+	onProgress: (sentBytes: number, totalBytes: number) => void
+): Promise<{ imported: number }> =>
+	new Promise((resolve, reject) => {
+		const xhr = new XMLHttpRequest();
+		xhr.open('POST', url);
+		xhr.upload.addEventListener('progress', (event) => {
+			if (event.lengthComputable) onProgress(event.loaded, event.total);
+		});
+		xhr.addEventListener('load', () => {
+			if (xhr.status >= 200 && xhr.status < 300) {
+				resolve(JSON.parse(xhr.responseText));
+			} else {
+				reject(new Error(`Import failed (${xhr.status}).`));
+			}
+		});
+		xhr.addEventListener('error', () => reject(new Error('Import failed.')));
+		xhr.send(body);
+	});
+
+export function provideOnboardingWorkspace(): OnboardingWorkspaceContext {
+	const { toast } = useToast();
+	const { confirm } = useConfirm();
+
+	// -- Coopt the specific contexts: once, here, for the whole page. ----------
+	const shell = usePageShellContext<PeekItem>();
+
+	// -- The checklist definition lives client-side; the server owns statuses. -
+	const steps = reactive<OnboardingStep[]>([
+		{
+			id: 'profile',
+			title: 'Set up your company profile',
+			description: 'Legal name, billing address and tax details.',
+			minutes: 2,
+			status: 'todo',
+		},
+		{
+			id: 'integrations',
+			title: 'Connect your tools',
+			description:
+				'Stripe for payments, QuickBooks for the books, Slack for alerts.',
+			minutes: 3,
+			status: 'todo',
+		},
+		{
+			id: 'invites',
+			title: 'Invite your teammates',
+			description:
+				'Billing works better when the whole team sees the same numbers.',
+			minutes: 2,
+			status: 'todo',
+		},
+		{
+			id: 'first-project',
+			title: 'Create your first project',
+			description:
+				'Projects group invoices, budgets and time entries per client.',
+			minutes: 1,
+			status: 'todo',
+		},
+		{
+			id: 'import-customers',
+			title: 'Import your customers',
+			description: 'Bring your existing customer list over as a CSV.',
+			minutes: 5,
+			status: 'todo',
+		},
+		{
+			id: 'first-invoice',
+			title: 'Send your first invoice',
+			description: 'Compose, preview and send — payment link included.',
+			minutes: 4,
+			status: 'todo',
+		},
+		{
+			id: 'reminders',
+			title: 'Turn on payment reminders',
+			description: 'Stop chasing overdue invoices by hand.',
+			minutes: 1,
+			status: 'todo',
+		},
+	]);
+
+	// Icon names are full static literals: the production icon scanner bundles
+	// only literals it can see, and brand SVGs live in the app's iconDir.
+	const integrations = reactive<WorkspaceIntegration[]>([
+		{
+			id: 'stripe',
+			name: 'Stripe',
+			description: 'Accept card payments; payouts reconcile against invoices.',
+			icon: 'local:stripe',
+			connected: false,
+			busy: false,
+		},
+		{
+			id: 'quickbooks',
+			name: 'QuickBooks Online',
+			description: 'Push paid invoices straight into your accounting.',
+			icon: 'local:quickbooks',
+			connected: false,
+			busy: false,
+		},
+		{
+			id: 'slack',
+			name: 'Slack',
+			description: 'A message in #finance when an invoice is paid or overdue.',
+			icon: 'local:slack',
+			connected: false,
+			busy: false,
+		},
+		{
+			id: 'google-drive',
+			name: 'Google Drive',
+			description: 'Attach contracts and receipts from your shared drives.',
+			icon: 'local:google-drive',
+			connected: false,
+			busy: false,
+		},
+	]);
+
+	const activeStep = ref<StepId | null>(null);
+	const workspace = ref<WorkspaceProfile | null>(null);
+	const invites = ref<PendingInvite[]>([]);
+	const firstProject = ref<Project | null>(null);
+	const importState = reactive({
+		uploading: false,
+		sentBytes: 0,
+		totalBytes: 0,
+		importedCount: null as number | null,
+	});
+	const reminders = reactive({
+		enabled: false,
+		cadence: '3-7-14' as ReminderCadence,
+	});
+
+	// Skipped counts as done: the bar rewards moving on, like Linear's checklist.
+	const doneCount = computed(
+		() => steps.filter((step) => step.status !== 'todo').length
+	);
+	const allDone = computed(() => doneCount.value === steps.length);
+
+	const step = (id: StepId): OnboardingStep =>
+		steps.find((candidate) => candidate.id === id)!;
+
+	// -- Data: one useAsyncData load; every mutation ends in refresh(). --------
+	const { data, refresh } = useAsyncData<OnboardingState>('onboarding', () =>
+		$fetch<OnboardingState>('/api/onboarding')
+	);
+
+	let hasOpenedFirstStep = false;
+	watch(
+		data,
+		(state) => {
+			if (!state) return;
+			for (const item of steps) item.status = state.steps[item.id];
+			const connected = new Set(state.connectedIntegrations);
+			for (const integration of integrations)
+				integration.connected = connected.has(integration.id);
+			workspace.value = state.workspace;
+			invites.value = state.invites;
+			firstProject.value = state.firstProject;
+			importState.importedCount = state.importedCustomers;
+			reminders.enabled = state.reminders.enabled;
+			reminders.cadence = state.reminders.cadence;
+			// Open the first unfinished step once, the first time data arrives.
+			if (!hasOpenedFirstStep) {
+				activeStep.value =
+					steps.find((candidate) => candidate.status === 'todo')?.id ?? null;
+				hasOpenedFirstStep = true;
+			}
+		},
+		{ immediate: true }
+	);
+
+	// -- Step grammar ----------------------------------------------------------------
+	const openStep = (id: StepId | null) => {
+		activeStep.value = id;
+	};
+	// Previews replace: a checklist preview never stacks on another preview.
+	const previewStep = (id: StepId) =>
+		shell.push({ type: 'step-preview', stepId: id }, true);
+	// From the peek back into the page: open the step and drop the sidebar.
+	const jumpToStep = (id: StepId) => {
+		activeStep.value = id;
+		shell.close();
+	};
+	const openNextTodo = (after: StepId) => {
+		const index = steps.findIndex((candidate) => candidate.id === after);
+		const next = [...steps.slice(index + 1), ...steps.slice(0, index)].find(
+			(candidate) => candidate.status === 'todo'
+		);
+		activeStep.value = next?.id ?? null;
+	};
+
+	// -- Actions --------------------------------------------------------------------
+	// The one status writer: $fetch then refresh() re-seeds the whole page from
+	// the server response. Domain actions (send invites, import…) auto-check
+	// their step through it; the manual done/skip ghosts use the same verb.
+	const persistStatus = async (id: StepId, status: StepStatus) => {
+		if (step(id).status === status) return;
+		await $fetch(`/api/onboarding/steps/${id}`, {
+			method: 'PATCH',
+			body: { status },
+		});
+		await refresh();
+	};
+
+	const completeStep = async (id: StepId) => {
+		const title = step(id).title;
+		await persistStatus(id, 'complete');
+		toast({ title: `"${title}" checked off.`, variant: 'success' });
+		openNextTodo(id);
+	};
+
+	// Skipping is quiet: it is a dismissal, not an achievement.
+	const skipStep = async (id: StepId) => {
+		await persistStatus(id, 'skipped');
+		openNextTodo(id);
+	};
+
+	// Optimistic, per the BbSwitch doctrine: flip now, revert + toast on failure.
+	// `busy` drives `readonly` so conflicting toggles cannot queue.
+	const toggleIntegration = async (
+		integration: WorkspaceIntegration,
+		next: boolean
+	) => {
+		integration.busy = true;
+		integration.connected = next;
+		try {
+			await $fetch(
+				`/api/onboarding/integrations/${integration.id}/${next ? 'connect' : 'disconnect'}`,
+				{ method: 'POST' }
+			);
+			toast({
+				title: `${integration.name} ${next ? 'connected' : 'disconnected'}.`,
+				variant: 'success',
+			});
+			if (next) await persistStatus('integrations', 'complete');
+		} catch {
+			integration.connected = !next;
+			toast({
+				title: `Could not ${next ? 'connect' : 'disconnect'} ${integration.name}.`,
+				variant: 'destructive',
+			});
+		} finally {
+			integration.busy = false;
+		}
+	};
+
+	const sendInvites = async (emails: string[], role: InviteRole) => {
+		await $fetch('/api/onboarding/invites', {
+			method: 'POST',
+			body: { emails, role },
+		});
+		await persistStatus('invites', 'complete');
+		toast({
+			title: `${emails.length} invitation${emails.length === 1 ? '' : 's'} sent.`,
+			variant: 'success',
+		});
+	};
+
+	const createProject = async (draft: ProjectDraft) => {
+		await $fetch('/api/onboarding/project', { method: 'POST', body: draft });
+		await persistStatus('first-project', 'complete');
+		toast({ title: `${draft.name} created.`, variant: 'success' });
+	};
+
+	const importCustomers = async (file: File) => {
+		importState.uploading = true;
+		importState.totalBytes = file.size;
+		importState.sentBytes = 0;
+		try {
+			const body = new FormData();
+			body.append('file', file);
+			const result = await uploadWithProgress(
+				'/api/onboarding/customers/import',
+				body,
+				(sentBytes, totalBytes) => {
+					importState.sentBytes = sentBytes;
+					importState.totalBytes = totalBytes;
+				}
+			);
+			importState.importedCount = result.imported;
+			await persistStatus('import-customers', 'complete');
+			toast({
+				title: `${result.imported} customers imported.`,
+				variant: 'success',
+			});
+		} finally {
+			importState.uploading = false;
+		}
+	};
+
+	const setReminders = async (enabled: boolean) => {
+		reminders.enabled = enabled;
+		try {
+			await $fetch('/api/onboarding/reminders', {
+				method: 'PATCH',
+				body: { enabled, cadence: reminders.cadence },
+			});
+			if (enabled) await persistStatus('reminders', 'complete');
+			toast({
+				title: enabled
+					? 'Payment reminders are on.'
+					: 'Payment reminders turned off.',
+				variant: 'success',
+			});
+		} catch {
+			reminders.enabled = !enabled;
+			toast({ title: 'Could not update reminders.', variant: 'destructive' });
+		}
+	};
+
+	const setReminderCadence = async (cadence: ReminderCadence) => {
+		reminders.cadence = cadence;
+		await $fetch('/api/onboarding/reminders', {
+			method: 'PATCH',
+			body: { enabled: reminders.enabled, cadence },
+		});
+		toast({ title: 'Reminder schedule updated.', variant: 'success' });
+	};
+
+	const dismissOnboarding = async () => {
+		const ok = await confirm({
+			variant: 'destructive',
+			title: 'Dismiss onboarding',
+			text: 'Hide the setup checklist for everyone in this workspace? Unfinished steps stay available under Settings → Setup.',
+			yes: 'Dismiss',
+			no: 'Keep it',
+		});
+		if (!ok) return;
+		await $fetch('/api/onboarding/dismiss', { method: 'POST' });
+		toast({
+			title: 'Onboarding dismissed. Find it again under Settings → Setup.',
+			variant: 'success',
+		});
+		await navigateTo('/dashboard');
+	};
+
+	const ctx: OnboardingWorkspaceContext = {
+		shell,
+		steps,
+		activeStep,
+		doneCount,
+		allDone,
+		workspace,
+		integrations,
+		invites,
+		firstProject,
+		importState,
+		reminders,
+		openStep,
+		previewStep,
+		jumpToStep,
+		completeStep,
+		skipStep,
+		toggleIntegration,
+		sendInvites,
+		createProject,
+		importCustomers,
+		setReminders,
+		setReminderCadence,
+		dismissOnboarding,
+	};
+	provide(key, ctx);
+	return ctx;
+}
+
+export function useOnboardingWorkspace(): OnboardingWorkspaceContext {
+	const ctx = inject(key);
+	if (!ctx)
+		throw new Error(
+			'useOnboardingWorkspace() called outside OnboardingChecklist'
+		);
+	return ctx;
+}
+```
+
+### Index.vue — the assembly
+
+```vue
+<!-- OnboardingChecklist/Index.vue -->
+<template>
+	<PageShell>
+		<!-- Topbar: breadcrumbs left, the page's one primary action right. -->
+		<template #topbar>
+			<div class="flex items-center justify-between gap-4 border-b px-4 py-2">
+				<!-- Breadcrumbs take the row's slack on a stable basis (min-w-0 flex-auto);
+				     without it their overflow recompute fights the flex layout every frame. -->
+				<BbBreadcrumbs
+					class="min-w-0 flex-auto"
+					:items="[
+						{ key: 'dashboard', text: 'Dashboard', to: '/dashboard' },
+						{ key: 'getting-started', text: 'Getting started' },
+					]"
+				/>
+				<BbButton
+					append:icon="lucide:arrow-right"
+					class="shrink-0"
+					to="/dashboard"
+					variant="primary"
+				>
+					Go to dashboard
+				</BbButton>
+			</div>
+		</template>
+
+		<div class="mx-auto flex w-full max-w-3xl flex-col gap-6 p-4">
+			<ProgressHeader />
+
+			<!-- Single-open checklist: one active key in the context derives every
+			     panel's model-value; opening one closes the rest, and clicking the
+			     open header collapses everything (payload is false → key null). -->
+			<div class="flex flex-col divide-y rounded-[var(--bb-radius)] border">
+				<BbAccordion
+					v-for="item in ctx.steps"
+					:key="item.id"
+					:model-value="ctx.activeStep.value === item.id"
+					@update:model-value="(open) => ctx.openStep(open ? item.id : null)"
+				>
+					<template #header="{ value }">
+						<StepHeader :open="value" :step="item" />
+					</template>
+					<div class="flex flex-col gap-4 px-11 pb-4">
+						<component :is="stepBodies[item.id]" />
+						<StepActions :step="item" />
+					</div>
+				</BbAccordion>
+			</div>
+
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				Stuck on a step?
+				<BbButton size="sm" to="/docs/setup" variant="link"
+					>Read the setup guide</BbButton
+				>
+				— it covers every integration and the CSV format.
+			</p>
+		</div>
+
+		<!-- The peek sidebar: the shell owns back/close; we render by type. -->
+		<template #sidebar>
+			<StepPreviewPeek
+				v-if="ctx.shell.current.value?.type === 'step-preview'"
+				:step-id="ctx.shell.current.value.stepId"
+			/>
+		</template>
+	</PageShell>
+</template>
+
+<script setup lang="ts">
+import type { Component } from 'vue';
+import { BbAccordion, BbBreadcrumbs, BbButton } from 'bitboss-ui';
+import PageShell from '@/components/layout/PageShell.vue';
+import { provideOnboardingWorkspace, type StepId } from './context';
+import FirstInvoiceStep from './FirstInvoiceStep.vue';
+import FirstProjectStep from './FirstProjectStep.vue';
+import ImportCustomersStep from './ImportCustomersStep.vue';
+import IntegrationsStep from './IntegrationsStep.vue';
+import InviteStep from './InviteStep.vue';
+import ProfileStep from './ProfileStep.vue';
+import ProgressHeader from './ProgressHeader.vue';
+import RemindersStep from './RemindersStep.vue';
+import StepActions from './StepActions.vue';
+import StepHeader from './StepHeader.vue';
+import StepPreviewPeek from './StepPreviewPeek.vue';
+
+const ctx = provideOnboardingWorkspace();
+
+// Each step body is its own component — a lookup, not a `type` prop.
+const stepBodies: Record<StepId, Component> = {
+	profile: ProfileStep,
+	integrations: IntegrationsStep,
+	invites: InviteStep,
+	'first-project': FirstProjectStep,
+	'import-customers': ImportCustomersStep,
+	'first-invoice': FirstInvoiceStep,
+	reminders: RemindersStep,
+};
+</script>
+```
+
+### ProgressHeader.vue
+
+```vue
+<!-- OnboardingChecklist/ProgressHeader.vue -->
+<template>
+	<header class="flex flex-col gap-3">
+		<div class="flex items-start justify-between gap-4">
+			<div class="flex flex-col gap-1">
+				<h1 class="text-xl font-semibold">Set up Acme</h1>
+				<p class="text-sm text-[color:var(--bb-text-muted)]">
+					A few steps to get your billing workspace ready for the whole team.
+				</p>
+			</div>
+			<BbButton variant="ghost" @click="ctx.dismissOnboarding">
+				Dismiss onboarding
+			</BbButton>
+		</div>
+
+		<div class="flex flex-col gap-1.5">
+			<div class="flex items-center justify-between gap-4 text-sm">
+				<span class="font-medium">
+					{{
+						ctx.allDone.value
+							? 'All set — your workspace is ready.'
+							: 'Your setup checklist'
+					}}
+				</span>
+				<span class="text-[color:var(--bb-text-muted)]">
+					{{ ctx.doneCount.value }} of {{ ctx.steps.length }} complete
+				</span>
+			</div>
+			<!-- Real units in, no pre-computed percentage: max = number of steps. -->
+			<BbProgress
+				aria-label="Setup progress"
+				:aria-valuetext="`${ctx.doneCount.value} of ${ctx.steps.length} steps complete`"
+				:max="ctx.steps.length"
+				:model-value="ctx.doneCount.value"
+			/>
+		</div>
+	</header>
+</template>
+
+<script setup lang="ts">
+import { BbButton, BbProgress } from 'bitboss-ui';
+import { useOnboardingWorkspace } from './context';
+
+const ctx = useOnboardingWorkspace();
+</script>
+```
+
+### StepHeader.vue
+
+```vue
+<!-- OnboardingChecklist/StepHeader.vue -->
+<template>
+	<!-- Rendered INSIDE the accordion's header button: everything here is
+	     non-interactive and click-transparent by design — the whole row toggles. -->
+	<span class="flex w-full items-center gap-3 px-3 py-3 text-left">
+		<BbIcon
+			class="shrink-0"
+			:class="
+				step.status === 'complete'
+					? 'text-green-600'
+					: 'text-[color:var(--bb-text-muted)]'
+			"
+			:icon="statusIcon"
+			size="20"
+		/>
+		<span class="flex min-w-0 flex-1 flex-col">
+			<span
+				class="text-sm font-medium"
+				:class="
+					step.status === 'todo' ? '' : 'text-[color:var(--bb-text-muted)]'
+				"
+			>
+				{{ step.title }}
+			</span>
+			<span class="truncate text-xs text-[color:var(--bb-text-muted)]">{{
+				step.description
+			}}</span>
+		</span>
+		<span
+			v-if="step.status === 'skipped'"
+			class="shrink-0 text-xs uppercase tracking-wide text-[color:var(--bb-text-muted)]"
+		>
+			Skipped
+		</span>
+		<span
+			v-else-if="step.status === 'todo'"
+			class="shrink-0 text-xs text-[color:var(--bb-text-muted)]"
+		>
+			~{{ step.minutes }} min
+		</span>
+		<BbIcon
+			class="shrink-0 text-[color:var(--bb-text-muted)] transition-transform"
+			:class="open ? 'rotate-180' : ''"
+			icon="lucide:chevron-down"
+			size="16"
+		/>
+	</span>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { BbIcon } from 'bitboss-ui';
+import type { OnboardingStep } from './context';
+
+const props = defineProps<{ open: boolean; step: OnboardingStep }>();
+
+// Full literals — the production icon scanner needs complete names.
+const icons = {
+	todo: 'lucide:circle-dashed',
+	complete: 'lucide:circle-check',
+	skipped: 'lucide:circle-check',
+} as const;
+const statusIcon = computed(() => icons[props.step.status]);
+</script>
+```
+
+### StepActions.vue
+
+```vue
+<!-- OnboardingChecklist/StepActions.vue -->
+<template>
+	<footer class="flex flex-wrap items-center gap-2 border-t pt-3">
+		<template v-if="step.status === 'todo'">
+			<BbButton
+				prepend:icon="lucide:check"
+				variant="ghost"
+				@click="() => ctx.completeStep(step.id)"
+			>
+				Mark as done
+			</BbButton>
+			<BbButton variant="ghost" @click="() => ctx.skipStep(step.id)">
+				Skip for now
+			</BbButton>
+		</template>
+		<span v-else class="text-xs text-[color:var(--bb-text-muted)]">
+			{{ step.status === 'complete' ? 'Completed' : 'Skipped' }} — revisit any
+			time from Settings → Setup.
+		</span>
+		<BbButton
+			append:icon="lucide:chevron-right"
+			class="ml-auto"
+			variant="ghost"
+			@click="() => ctx.previewStep(step.id)"
+		>
+			See what you'll get
+		</BbButton>
+	</footer>
+</template>
+
+<script setup lang="ts">
+import { BbButton } from 'bitboss-ui';
+import { useOnboardingWorkspace } from './context';
+import type { OnboardingStep } from './context';
+
+defineProps<{ step: OnboardingStep }>();
+
+const ctx = useOnboardingWorkspace();
+</script>
+```
+
+### ProfileStep.vue
+
+```vue
+<!-- OnboardingChecklist/ProfileStep.vue -->
+<template>
+	<div v-if="ctx.workspace.value" class="flex flex-col gap-3 text-sm">
+		<p class="text-[color:var(--bb-text-muted)]">
+			Done at signup — these details appear on every invoice you send.
+		</p>
+		<dl class="grid grid-cols-[auto_1fr] gap-x-6 gap-y-1.5">
+			<dt class="text-[color:var(--bb-text-muted)]">Company</dt>
+			<dd>{{ ctx.workspace.value.company }}</dd>
+			<dt class="text-[color:var(--bb-text-muted)]">Billing address</dt>
+			<dd>{{ ctx.workspace.value.address }}</dd>
+			<dt class="text-[color:var(--bb-text-muted)]">Tax ID</dt>
+			<dd>{{ ctx.workspace.value.taxId }}</dd>
+			<dt class="text-[color:var(--bb-text-muted)]">Currency</dt>
+			<dd>{{ ctx.workspace.value.currency }}</dd>
+		</dl>
+		<div>
+			<BbButton
+				prepend:icon="lucide:pencil"
+				size="sm"
+				to="/settings/general"
+				variant="link"
+			>
+				Edit workspace profile
+			</BbButton>
+		</div>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { BbButton } from 'bitboss-ui';
+import { useOnboardingWorkspace } from './context';
+
+const ctx = useOnboardingWorkspace();
+</script>
+```
+
+### IntegrationsStep.vue
+
+```vue
+<!-- OnboardingChecklist/IntegrationsStep.vue -->
+<template>
+	<div class="flex flex-col text-sm">
+		<p class="pb-1 text-[color:var(--bb-text-muted)]">
+			Flip a switch to connect — you'll be sent through the provider's consent
+			screen the first time.
+		</p>
+		<div
+			v-for="integration in ctx.integrations"
+			:key="integration.id"
+			class="flex items-center gap-3 border-b py-2.5 last:border-b-0"
+		>
+			<BbIcon class="shrink-0" :icon="integration.icon" size="20" />
+			<div class="flex min-w-0 flex-1 flex-col">
+				<span class="font-medium">{{ integration.name }}</span>
+				<span class="truncate text-xs text-[color:var(--bb-text-muted)]">
+					{{ integration.description }}
+				</span>
+			</div>
+			<!-- Instant-effect toggle: the context flips optimistically, holds the
+			     switch readonly while in flight, and reverts + toasts on failure. -->
+			<BbSwitch
+				hide-label
+				:label="`Connect ${integration.name}`"
+				:model-value="integration.connected"
+				:name="`integration-${integration.id}`"
+				:readonly="integration.busy"
+				@update:model-value="(next) => ctx.toggleIntegration(integration, next)"
+			/>
+		</div>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { BbIcon, BbSwitch } from 'bitboss-ui';
+import { useOnboardingWorkspace } from './context';
+
+const ctx = useOnboardingWorkspace();
+</script>
+```
+
+### InviteStep.vue
+
+```vue
+<!-- OnboardingChecklist/InviteStep.vue -->
+<template>
+	<div class="flex flex-col gap-3 text-sm">
+		<p class="text-[color:var(--bb-text-muted)]">
+			Paste addresses or type them — Enter or a comma adds each one.
+		</p>
+
+		<div class="flex flex-wrap items-end gap-2">
+			<BbTag
+				v-model="emails"
+				class="min-w-64 flex-1"
+				compact
+				:divider="['Enter', ',']"
+				:errors="inviteError"
+				label="Email addresses"
+				:max="10"
+				placeholder="ada.rossi@acme.com"
+				prepend:icon="lucide:mail"
+				@duplicate="
+					(email) => (inviteError = `${email} is already in the list.`)
+				"
+				@max="() => (inviteError = 'You can invite up to 10 people at once.')"
+			/>
+			<BbSelect
+				v-model="role"
+				class="w-44"
+				compact
+				item-text="label"
+				item-value="value"
+				:items="roles"
+				label="Role"
+				label-mode="outside"
+			/>
+			<BbButton prepend:icon="lucide:send" variant="secondary" @click="send">
+				Send invitations
+			</BbButton>
+		</div>
+
+		<ul v-if="ctx.invites.value.length" class="flex flex-col gap-1">
+			<li
+				v-for="invite in ctx.invites.value"
+				:key="invite.email"
+				class="flex items-center justify-between gap-2 text-xs"
+			>
+				<span>{{ invite.email }}</span>
+				<span class="text-[color:var(--bb-text-muted)]"
+					>{{ invite.role }} · invited {{ invite.sentAt }}</span
+				>
+			</li>
+		</ul>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbSelect, BbTag } from 'bitboss-ui';
+import { useOnboardingWorkspace } from './context';
+import type { InviteRole } from '@/types';
+
+const ctx = useOnboardingWorkspace();
+
+// Draft state only this leaf touches: local refs, not context fields.
+const emails = ref<string[]>([]);
+const role = ref<InviteRole>('member');
+const inviteError = ref('');
+
+const roles: { value: InviteRole; label: string }[] = [
+	{ value: 'admin', label: 'Admin' },
+	{ value: 'member', label: 'Member' },
+	{ value: 'accountant', label: 'Accountant' },
+];
+
+// Returning the promise lets the button's automatic loading track the send.
+const send = async () => {
+	inviteError.value = '';
+	if (emails.value.length === 0) {
+		inviteError.value = 'Add at least one email address.';
+		return;
+	}
+	const invalid = emails.value.filter((email) => !email.includes('@'));
+	if (invalid.length > 0) {
+		inviteError.value = `${invalid.join(', ')} ${invalid.length === 1 ? 'is' : 'are'} not a valid address.`;
+		return;
+	}
+	await ctx.sendInvites(emails.value, role.value);
+	emails.value = [];
+};
+</script>
+```
+
+### FirstProjectStep.vue
+
+```vue
+<!-- OnboardingChecklist/FirstProjectStep.vue -->
+<template>
+	<!-- Already created (by this session or a teammate): show it, not the form. -->
+	<div v-if="ctx.firstProject.value" class="flex items-center gap-2 text-sm">
+		<BbIcon class="text-green-600" icon="lucide:circle-check" size="16" />
+		<span>
+			<span class="font-medium">{{ ctx.firstProject.value.name }}</span>
+			is ready for its first invoice.
+		</span>
+		<BbButton
+			append:icon="lucide:arrow-up-right"
+			size="sm"
+			:to="`/projects/${ctx.firstProject.value.id}`"
+			variant="link"
+		>
+			Open project
+		</BbButton>
+	</div>
+
+	<form
+		v-else
+		class="flex flex-col gap-3 text-sm"
+		novalidate
+		@submit.prevent="submit"
+	>
+		<p class="text-[color:var(--bb-text-muted)]">
+			A project keeps one client's invoices, budget and time entries together.
+		</p>
+		<div class="flex flex-wrap items-end gap-2">
+			<BbTextInput
+				v-model="draft.name"
+				class="min-w-56 flex-1"
+				compact
+				:errors="nameError"
+				label="Project name"
+				label-mode="outside"
+				placeholder="Website redesign"
+			/>
+			<BbTextInput
+				v-model="draft.client"
+				class="min-w-56 flex-1"
+				compact
+				label="Client"
+				label-mode="outside"
+				placeholder="Globex Corporation"
+			/>
+			<BbButton prepend:icon="lucide:plus" type="submit" variant="secondary">
+				Create project
+			</BbButton>
+		</div>
+	</form>
+</template>
+
+<script setup lang="ts">
+import { reactive, ref } from 'vue';
+import { BbButton, BbIcon, BbTextInput } from 'bitboss-ui';
+import { useOnboardingWorkspace } from './context';
+
+const ctx = useOnboardingWorkspace();
+
+const draft = reactive({ name: '', client: '' });
+const nameError = ref('');
+
+// Returning the promise lets the submit button track the async work.
+const submit = () => {
+	nameError.value = '';
+	if (!draft.name.trim()) {
+		nameError.value = 'Give the project a name.';
+		return;
+	}
+	return ctx.createProject({ ...draft });
+};
+</script>
+```
+
+### ImportCustomersStep.vue
+
+```vue
+<!-- OnboardingChecklist/ImportCustomersStep.vue -->
+<template>
+	<div class="flex flex-col gap-3 text-sm">
+		<!-- Already imported: report it instead of showing an empty dropzone. -->
+		<div
+			v-if="ctx.importState.importedCount !== null"
+			class="flex items-center gap-2"
+		>
+			<BbIcon class="text-green-600" icon="lucide:circle-check" size="16" />
+			<span>
+				<span class="font-medium">{{ ctx.importState.importedCount }}</span>
+				customers imported.
+			</span>
+			<BbButton
+				append:icon="lucide:arrow-up-right"
+				size="sm"
+				to="/customers"
+				variant="link"
+			>
+				View customers
+			</BbButton>
+		</div>
+
+		<template v-else>
+			<!-- MIME + extension pairing: Excel exports often carry a non-CSV MIME
+			     type (or none at all on drag-drop) — '.csv' is what admits them. -->
+			<BbDropzone
+				v-model="file"
+				:accept="['text/csv', '.csv']"
+				:disabled="ctx.importState.uploading"
+				:errors="fileError"
+				:max-size="10 * 1024 * 1024"
+				@error="onReject"
+			>
+				<template #default="{ dragging, focused, open }">
+					<div
+						class="flex flex-col items-center gap-2 rounded-[var(--bb-radius)] border-2 border-dashed p-6 text-center transition-colors"
+						:class="[
+							dragging
+								? 'border-[color:var(--bb-primary)] bg-[color:var(--bb-panel)]'
+								: '',
+							focused ? 'ring-2 ring-[color:var(--bb-ring)]' : '',
+						]"
+					>
+						<BbIcon
+							class="text-[color:var(--bb-text-muted)]"
+							icon="lucide:file-spreadsheet"
+							size="24"
+						/>
+						<p class="font-medium">
+							{{
+								dragging ? 'Drop your CSV here' : 'Drag your customers CSV here'
+							}}
+						</p>
+						<p class="text-xs text-[color:var(--bb-text-muted)]">
+							We map name, email, VAT number and address columns. Up to 10 MB.
+						</p>
+						<BbButton size="sm" variant="ghost" @click="open"
+							>or browse files</BbButton
+						>
+					</div>
+				</template>
+			</BbDropzone>
+
+			<!-- Captured, not yet imported: confirm before touching the workspace. -->
+			<div v-if="file" class="flex items-center gap-2">
+				<BbIcon
+					class="shrink-0 text-[color:var(--bb-text-muted)]"
+					icon="lucide:file-text"
+					size="16"
+				/>
+				<span class="min-w-0 flex-1 truncate">
+					{{ file.name }}
+					<span class="text-xs text-[color:var(--bb-text-muted)]"
+						>· {{ formatSize(file.size) }}</span
+					>
+				</span>
+				<BbButton
+					aria-label="Remove selected file"
+					:disabled="ctx.importState.uploading"
+					icon="lucide:x"
+					size="sm"
+					variant="ghost"
+					@click="() => (file = null)"
+				/>
+				<BbButton
+					:disabled="ctx.importState.uploading"
+					prepend:icon="lucide:upload"
+					variant="secondary"
+					@click="startImport"
+				>
+					Import customers
+				</BbButton>
+			</div>
+
+			<!-- The dropzone captures; the context uploads and drives the bar. -->
+			<div v-if="ctx.importState.uploading" class="flex flex-col gap-1">
+				<BbProgress
+					aria-label="Upload progress"
+					:max="ctx.importState.totalBytes"
+					:model-value="ctx.importState.sentBytes"
+				/>
+				<span class="text-xs text-[color:var(--bb-text-muted)]">
+					Uploading… {{ formatSize(ctx.importState.sentBytes) }} of
+					{{ formatSize(ctx.importState.totalBytes) }}
+				</span>
+			</div>
+		</template>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbDropzone, BbIcon, BbProgress } from 'bitboss-ui';
+import type { DropZoneError } from 'bitboss-ui';
+import { useOnboardingWorkspace } from './context';
+
+const ctx = useOnboardingWorkspace();
+
+// The captured-but-not-imported file is this leaf's own state.
+const file = ref<File | null>(null);
+const fileError = ref('');
+
+// Rejects never reach the model — map the typed error to a message and feed
+// it back through `errors` (the display is a round-trip, not automatic).
+const onReject = (error: DropZoneError) => {
+	fileError.value =
+		error.type === 'maxSize'
+			? `${error.filename} is ${error.formattedSize} — the limit is ${error.formattedMaxSize}.`
+			: error.type === 'accept'
+				? `${error.filename} is not a CSV file.`
+				: `${error.filename} was rejected.`;
+};
+
+const startImport = async () => {
+	if (!file.value) return;
+	fileError.value = '';
+	await ctx.importCustomers(file.value);
+	file.value = null;
+};
+
+const formatSize = (bytes: number) =>
+	bytes >= 1024 * 1024
+		? `${(bytes / 1024 / 1024).toFixed(1)} MB`
+		: `${Math.max(1, Math.round(bytes / 1024))} KB`;
+</script>
+```
+
+### FirstInvoiceStep.vue
+
+```vue
+<!-- OnboardingChecklist/FirstInvoiceStep.vue -->
+<template>
+	<div class="flex flex-col gap-3 text-sm">
+		<p class="text-[color:var(--bb-text-muted)]">
+			The composer walks you through line items, taxes and payment terms. Every
+			invoice goes out with a payment link — customers pay by card or bank
+			transfer without creating an account. This step checks itself off when
+			your first invoice is sent.
+		</p>
+		<div>
+			<BbButton
+				append:icon="lucide:arrow-up-right"
+				prepend:icon="lucide:receipt"
+				to="/invoices/create"
+				variant="outline"
+			>
+				Open the invoice composer
+			</BbButton>
+		</div>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { BbButton } from 'bitboss-ui';
+</script>
+```
+
+### RemindersStep.vue
+
+```vue
+<!-- OnboardingChecklist/RemindersStep.vue -->
+<template>
+	<div class="flex flex-col gap-3 text-sm">
+		<!-- Instant-effect switch: the context applies optimistically and reverts
+		     with a toast if the server rejects the change. -->
+		<BbSwitch
+			description="Email customers automatically when an invoice goes overdue. Replies land in your inbox."
+			label="Automatic payment reminders"
+			:model-value="ctx.reminders.enabled"
+			name="payment-reminders"
+			@update:model-value="(next) => ctx.setReminders(next)"
+		/>
+		<BbSelect
+			v-if="ctx.reminders.enabled"
+			class="max-w-72"
+			compact
+			item-text="label"
+			item-value="value"
+			:items="cadences"
+			label="Reminder schedule"
+			label-mode="outside"
+			:model-value="ctx.reminders.cadence"
+			@update:model-value="(cadence) => ctx.setReminderCadence(cadence)"
+		/>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { BbSelect, BbSwitch } from 'bitboss-ui';
+import { useOnboardingWorkspace } from './context';
+import type { ReminderCadence } from '@/types';
+
+const ctx = useOnboardingWorkspace();
+
+const cadences: { value: ReminderCadence; label: string }[] = [
+	{ value: '3-7-14', label: '3, 7 and 14 days overdue' },
+	{ value: '7', label: '7 days overdue' },
+	{ value: '7-30', label: '7 and 30 days overdue' },
+];
+</script>
+```
+
+### StepPreviewPeek.vue
+
+```vue
+<!-- OnboardingChecklist/StepPreviewPeek.vue -->
+<template>
+	<div class="flex flex-col gap-4 text-sm">
+		<!-- Identity header. -->
+		<header class="flex items-center gap-3">
+			<span
+				class="flex h-9 w-9 shrink-0 items-center justify-center rounded-[var(--bb-radius)] border"
+			>
+				<BbIcon :icon="preview.icon" size="18" />
+			</span>
+			<div class="flex min-w-0 flex-col">
+				<h2 class="text-base font-semibold">{{ preview.title }}</h2>
+				<p class="text-xs text-[color:var(--bb-text-muted)]">
+					{{ preview.tagline }}
+				</p>
+			</div>
+		</header>
+
+		<p
+			v-if="step.status !== 'todo'"
+			class="flex items-center gap-1.5 text-xs text-[color:var(--bb-text-muted)]"
+		>
+			<!-- Green is earned: skipped reads as reached-but-unmeasured, not done. -->
+			<BbIcon
+				:class="
+					step.status === 'complete'
+						? 'text-green-600'
+						: 'text-[color:var(--bb-text-muted)]'
+				"
+				icon="lucide:circle-check"
+				size="14"
+			/>
+			{{
+				step.status === 'complete'
+					? 'Already done in this workspace.'
+					: 'Skipped — you can still set it up.'
+			}}
+		</p>
+
+		<!-- What you'll get. -->
+		<section class="flex flex-col gap-2.5">
+			<h3
+				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
+			>
+				What you'll get
+			</h3>
+			<ul class="flex flex-col gap-2.5">
+				<li
+					v-for="bullet in preview.bullets"
+					:key="bullet.title"
+					class="flex gap-2"
+				>
+					<BbIcon
+						class="mt-0.5 shrink-0 text-[color:var(--bb-text-muted)]"
+						:icon="bullet.icon"
+						size="14"
+					/>
+					<div class="flex flex-col">
+						<span class="font-medium">{{ bullet.title }}</span>
+						<span class="text-xs text-[color:var(--bb-text-muted)]">{{
+							bullet.text
+						}}</span>
+					</div>
+				</li>
+			</ul>
+		</section>
+
+		<!-- One concrete number beats three adjectives. -->
+		<div class="rounded-[var(--bb-radius)] border p-3">
+			<p class="text-lg font-semibold">{{ preview.stat.value }}</p>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				{{ preview.stat.label }}
+			</p>
+		</div>
+
+		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
+			<BbButton
+				v-if="step.status === 'todo'"
+				prepend:icon="lucide:check"
+				variant="secondary"
+				@click="() => ctx.jumpToStep(stepId)"
+			>
+				Set it up now
+			</BbButton>
+			<BbButton v-else variant="ghost" @click="() => ctx.jumpToStep(stepId)">
+				Review this step
+			</BbButton>
+		</footer>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { BbButton, BbIcon } from 'bitboss-ui';
+import { useOnboardingWorkspace, type StepId } from './context';
+
+const props = defineProps<{ stepId: StepId }>();
+
+const ctx = useOnboardingWorkspace();
+
+const step = computed(
+	() => ctx.steps.find((candidate) => candidate.id === props.stepId)!
+);
+const preview = computed(() => previews[props.stepId]);
+
+interface StepPreview {
+	icon: string;
+	title: string;
+	tagline: string;
+	bullets: { icon: string; title: string; text: string }[];
+	stat: { value: string; label: string };
+}
+
+// Presentation content with a single consumer: it lives in the leaf, not the
+// context. Icon names are full static literals for the production scanner.
+const previews: Record<StepId, StepPreview> = {
+	profile: {
+		icon: 'lucide:building-2',
+		title: 'A complete company profile',
+		tagline: 'Set once, printed on every document.',
+		bullets: [
+			{
+				icon: 'lucide:file-text',
+				title: 'Compliant invoices',
+				text: 'Legal name, address and tax ID appear on every PDF automatically.',
+			},
+			{
+				icon: 'lucide:euro',
+				title: 'One currency for the books',
+				text: 'Amounts, totals and reports all use your workspace currency.',
+			},
+		],
+		stat: {
+			value: '2 min',
+			label: 'to update it later under Settings → General',
+		},
+	},
+	integrations: {
+		icon: 'lucide:link',
+		title: 'Your tools, wired together',
+		tagline:
+			'Payments, accounting and alerts stop being three separate chores.',
+		bullets: [
+			{
+				icon: 'lucide:credit-card',
+				title: 'Payments reconcile themselves',
+				text: 'Stripe payouts are matched against open invoices automatically.',
+			},
+			{
+				icon: 'lucide:receipt',
+				title: 'Books stay current',
+				text: 'Paid invoices flow into QuickBooks the moment they settle.',
+			},
+			{
+				icon: 'lucide:bell',
+				title: 'The team finds out in Slack',
+				text: '#finance gets a message on every paid and overdue invoice.',
+			},
+		],
+		stat: {
+			value: '9 days',
+			label: 'faster average payment for teams with Stripe connected',
+		},
+	},
+	invites: {
+		icon: 'lucide:users',
+		title: 'Everyone on the same numbers',
+		tagline: 'Roles keep access right-sized from day one.',
+		bullets: [
+			{
+				icon: 'lucide:user-plus',
+				title: 'Sign-in with work email',
+				text: 'Invitees join with their address — no shared passwords.',
+			},
+			{
+				icon: 'lucide:key-round',
+				title: 'Permissions per role',
+				text: 'Accountants see reports; members see their own projects.',
+			},
+			{
+				icon: 'lucide:clock',
+				title: 'Invitations expire safely',
+				text: 'Unaccepted invites lapse after 7 days and can be re-sent.',
+			},
+		],
+		stat: { value: '10', label: 'invitations per batch' },
+	},
+	'first-project': {
+		icon: 'lucide:folder',
+		title: 'A home for each client',
+		tagline: 'Projects keep invoices, budgets and time in one place.',
+		bullets: [
+			{
+				icon: 'lucide:folder-open',
+				title: 'Everything grouped',
+				text: 'Invoices, budgets and time entries organized per client.',
+			},
+			{
+				icon: 'lucide:chart-line',
+				title: 'Profitability from day one',
+				text: 'A per-project margin view as soon as the first invoice is paid.',
+			},
+		],
+		stat: {
+			value: '3',
+			label: 'projects created by the average team in week one',
+		},
+	},
+	'import-customers': {
+		icon: 'lucide:file-spreadsheet',
+		title: 'Your customer list, moved over',
+		tagline: 'The CSV you already have is enough.',
+		bullets: [
+			{
+				icon: 'lucide:upload',
+				title: 'Columns mapped for you',
+				text: 'Name, email, VAT number and address are detected automatically.',
+			},
+			{
+				icon: 'lucide:check',
+				title: 'No double imports',
+				text: 'Rows are merged by email — re-running an import never duplicates.',
+			},
+		],
+		stat: { value: '5,000', label: 'rows per import' },
+	},
+	'first-invoice': {
+		icon: 'lucide:receipt',
+		title: 'Your first invoice, out the door',
+		tagline: 'Composed, sent and tracked in one flow.',
+		bullets: [
+			{
+				icon: 'lucide:send',
+				title: 'Sent from your domain',
+				text: 'Invoices arrive from billing@your-company, not a noreply void.',
+			},
+			{
+				icon: 'lucide:banknote',
+				title: 'Payment link included',
+				text: 'Customers pay by card or bank transfer without an account.',
+			},
+			{
+				icon: 'lucide:clock',
+				title: 'Overdue tracking starts itself',
+				text: 'Due dates and aging are tracked from the moment you hit send.',
+			},
+		],
+		stat: {
+			value: '2×',
+			label: 'faster payment on invoices with a payment link',
+		},
+	},
+	reminders: {
+		icon: 'lucide:bell',
+		title: 'Overdue chasing, automated',
+		tagline: 'Polite nudges on a schedule you choose.',
+		bullets: [
+			{
+				icon: 'lucide:clock',
+				title: 'A schedule, not a scramble',
+				text: 'Reminders at 3, 7 and 14 days overdue — or the cadence you pick.',
+			},
+			{
+				icon: 'lucide:mail',
+				title: 'Replies reach a human',
+				text: 'Customers answer straight into your inbox thread.',
+			},
+		],
+		stat: {
+			value: '38%',
+			label: 'fewer invoices reach 30 days overdue with reminders on',
+		},
+	},
+};
+</script>
+```
+
+## Why it is built this way
+
+- **The context coopts the shell, leaves consume.** The only specific
+  context on a checklist page is the peek stack; `provideOnboardingWorkspace()`
+  joins it once and thirteen components share step state, integration
+  state and every action through one `useOnboardingWorkspace()` call. No
+  component receives a callback prop; the only data props are the `step` /
+  `stepId` an item renders (`StepHeader`, `StepActions`, `StepPreviewPeek`)
+  — everything else is injection.
+- **One fetch, one refresh path.** `useAsyncData('onboarding', …)` loads the
+  whole checklist once; `persistStatus` is the single place that `$fetch`s a
+  mutation and calls `refresh()` — a `watch(data, …, { immediate: true })`
+  re-seeds every local field from the fresh response, so `steps`,
+  `integrations`, `invites`, `firstProject` and `reminders` can never drift
+  from what the server actually persisted.
+- **Single-open is one key, per the BbAccordion doctrine.** `BbAccordion`
+  is deliberately one panel per boolean with no group wrapper; the
+  `activeStep` key derives each `model-value`, the `update:modelValue`
+  payload (`false` on closing the open header) resets it to `null`, and
+  `openNextTodo` gives the Linear feel of the checklist walking itself
+  forward. No watchers force-closing siblings.
+- **Headers stay passive, actions live in the body.** The accordion header
+  is already a `<button>`; the status icon, minutes estimate and chevron in
+  `StepHeader` are click-transparent metadata. Everything interactive —
+  done, skip, preview, the step's real controls — is body content, so the
+  markup stays valid and the click target stays whole.
+- **`ofetch` has no upload-progress hook.** Every mutation on this page is a
+  plain `$fetch` except the CSV import, which needs real bytes for
+  `BbProgress` — that one call drops to a raw `XMLHttpRequest` wrapped in a
+  promise. It is the only exception, called out explicitly so it doesn't
+  read as an inconsistency.
+- **Every rung of the state ladder is deliberate.** Draft state one leaf
+  touches is a local ref (invite emails and role, the project draft, the
+  captured CSV file, the reject message); everything two components read
+  sits on the context (statuses, `importState` driving `BbProgress`,
+  reminders); nothing on this page outlives it, so no store is involved.
+- **The switch promise is kept.** Integration and reminder toggles apply
+  optimistically, hold the control `readonly` while the request flies, and
+  revert with a `destructive` toast on failure — the async-save pattern
+  from the BbSwitch guide, owned by context actions so no leaf ever talks
+  to `$fetch` or toasts on its own.
+- **The dropzone captures; the context uploads.** `BbDropzone` has no
+  request surface by design: the leaf holds the captured `File`, maps the
+  typed `@error` union back through `errors` (the display round-trip), and
+  `importCustomers` drives `BbProgress` from real bytes — `max` is the file
+  size, never a pre-computed percentage.
+- **Previews are peeks, not dialogs.** "See what you'll get" is the
+  checklist's version of clicking a record's name: `previewStep` pushes
+  onto the coopted shell stack with `replace` (previews never stack), and
+  `jumpToStep` owns the way back — leaves never touch the stack grammar
+  directly.
+- **Sizing and variants:** `md`-first throughout the bodies (28px buttons
+  flush beside `compact` inputs in the invite and project rows); `sm` only
+  for genuinely dense spots (inline links, the file-row remove); exactly
+  one `variant="primary"` (Go to dashboard); step submits are `secondary`;
+  dismissal is a ghost gated by a `destructive` `useConfirm`.
+
+## Variations
+
+- **Personal onboarding**: scope statuses per user instead of per
+  workspace (`$fetch('/api/onboarding', { query: { scope: 'user' } })`)
+  and drop the workspace-wide dismiss confirm copy; the page shape is
+  unchanged.
+- **Sequential (gated) steps**: lock each accordion until the previous
+  step is done by rendering the body's controls `disabled` with an
+  explanatory line; for hard gates with per-step validation, the
+  wizard-form recipe is the full treatment.
+- **Preview follows the open step**: call `previewStep(id)` from
+  `openStep` so the sidebar always previews the active step; keep the
+  explicit footer button for touch users.
+- **All-done celebration**: when `allDone` flips, swap `ProgressHeader`'s
+  copy block for a success panel with the dashboard CTA and a "book an
+  onboarding call" link.