bitboss-ui 2.1.135 → 3.0.0-alpha.4

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

@@ -0,0 +1,1791 @@
+---
+title: Workspace Onboarding (Inertia)
+summary: Full-anatomy workspace onboarding for Laravel + Inertia — 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 via useForm multipart), the checklist seeded from a page prop and mutations resolved through promise-wrapped visits, all through one page context that coopts the Inertia Helpers toolkit.
+---
+
+# Recipe: Workspace Onboarding (Inertia)
+
+The onboarding checklist adapted for **Laravel + Inertia**: 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
+arrives as a page prop, every mutation is a promise-wrapped `router.visit`
+with `only: ['onboarding']` so statuses re-arrive in the same round trip,
+the invite and project steps submit through
+[`usePromiseForm`](../../guides/inertia-helpers.md) with 422 errors mapped
+onto their fields, and the CSV import binds the file into a native `useForm`
+that serializes multipart automatically. 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) · [Nuxt](../nuxt/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 the `createInertiaApp` render root — never in a page.
+- From the [Inertia Helpers](../../guides/inertia-helpers.md) toolkit:
+  `useProp`, `usePromiseForm`.
+- Controller: `Inertia::render('Onboarding/Index', ['onboarding' => [
+'steps' => [...], 'connectedIntegrations' => [...], 'workspace' => ...,
+'invites' => [...], 'firstProject' => ..., 'importedCustomers' => ...,
+'reminders' => ['enabled' => ..., 'cadence' => ...]]])` — one compound
+  prop is the whole checklist's server truth, re-sent on every partial
+  reload the page triggers (`only: ['onboarding']`). Mutation routes are
+  plain Laravel routes that redirect back (`PATCH /onboarding/steps/:id`,
+  `POST /onboarding/integrations/:id/connect`, `POST /onboarding/invites`,
+  `POST /onboarding/project`, `POST /onboarding/customers/import`,
+  `PATCH /onboarding/reminders`, `POST /onboarding/dismiss`); the mutation
+  that changes a step's real state (connecting an integration, sending
+  invites, importing customers, enabling reminders) also flips that step's
+  status server-side, so the client never computes completion itself.
+
+## 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.
+- **`onboarding` is a page prop, not a client fetch.** `useProp<...>('onboarding')`
+  gives a reactive read of the server's current checklist state; a single
+  `watch` re-seeds `steps`, `integrations`, `invites`, `firstProject` and
+  `reminders` from it every time a visit lands a fresh copy — there is no
+  separate load call and no `persistStatus` writer, because the server
+  already recomputes step statuses as part of each mutation response.
+- **Mutations are promise-wrapped `router.visit` calls.** A tiny local
+  `visit()` helper turns Inertia's callback-based API into a promise, so
+  most context actions stay `async function`s exactly like the Vue/Nuxt
+  versions — `await ctx.toggleIntegration(...)` reads the same everywhere.
+- **Invites and the project form use `usePromiseForm`, with 422 on the
+  fields.** These two steps carry real user input, so their context actions
+  wrap `usePromiseForm` instead of the generic `visit()` helper; a failed
+  submit rejects with Laravel's field-keyed error bag, and the step's own
+  `inviteError`/`nameError` display catches and maps it — the same local
+  error slot the client-side checks already use.
+- **The CSV import binds the file into a `useForm`.** Inertia serializes a
+  bound `File` as multipart automatically and exposes real upload bytes via
+  `onProgress`, so the import step needs no manual `FormData` or XHR
+  wiring — unlike the Nuxt adaptation, which has to reach for a raw
+  `XMLHttpRequest` because `ofetch` has no progress hook.
+- **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.
+- **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 + onboarding prop + 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 (`href="/dashboard"`)                                        |
+| 2   | Dismiss onboarding               | progress header, ghost              | `useConfirm` (destructive) → `router.post` + toast, server redirects    |
+| 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` → promise-wrapped visit                     |
+| 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` → `usePromiseForm`, 422 → `inviteError`                   |
+| 10  | Create the first project         | mini form submit                    | `createProject` → `usePromiseForm`, 422 → `nameError`                   |
+| 11  | Import customers CSV             | `BbDropzone` + Import button        | `importCustomers` → `useForm` multipart; `BbProgress` from `onProgress` |
+| 12  | Open the invoice composer        | outline button in step 6            | navigation (`href="/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 (`href="/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 { router, useForm } from '@inertiajs/vue3';
+import type { RequestPayload } from '@inertiajs/core';
+import { useConfirm, useToast } from 'bitboss-ui';
+import {
+	usePageShellContext,
+	type PageShellContext,
+} from '@/components/layout/usePageShellContext';
+import { useProp } from '@/composables/useProp';
+import { usePromiseForm } from '@/composables/usePromiseForm';
+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 `onboarding` page prop — the server's checklist truth. */
+type OnboardingProp = {
+	steps: Record<StepId, StepStatus>;
+	connectedIntegrations: string[];
+	workspace: WorkspaceProfile;
+	invites: PendingInvite[];
+	firstProject: Project | null;
+	importedCustomers: number | null;
+	reminders: { enabled: boolean; cadence: ReminderCadence };
+};
+
+const RELOAD_PROPS = ['onboarding'] as const;
+
+/** Inertia's callback-based visit, wrapped as a promise — so every simple
+ * context action stays `async`, exactly like the Vue/Nuxt versions. Always a
+ * partial reload of `onboarding`, the only prop this page depends on. */
+const visit = (
+	method: 'post' | 'patch' | 'delete',
+	url: string,
+	// Inertia's own payload type — strings/numbers/booleans/arrays/files.
+	// (`Record<string, unknown>` does not satisfy it.)
+	data: RequestPayload = {}
+): Promise<void> =>
+	new Promise((resolve, reject) => {
+		router.visit(url, {
+			method,
+			data,
+			only: [...RELOAD_PROPS],
+			preserveScroll: true,
+			preserveState: true,
+			onSuccess: () => resolve(),
+			onError: (errors) => reject(errors),
+		});
+	});
+
+const STEP_DEFS: Record<StepId, Omit<OnboardingStep, 'status'>> = {
+	profile: {
+		id: 'profile',
+		title: 'Set up your company profile',
+		description: 'Legal name, billing address and tax details.',
+		minutes: 2,
+	},
+	integrations: {
+		id: 'integrations',
+		title: 'Connect your tools',
+		description:
+			'Stripe for payments, QuickBooks for the books, Slack for alerts.',
+		minutes: 3,
+	},
+	invites: {
+		id: 'invites',
+		title: 'Invite your teammates',
+		description:
+			'Billing works better when the whole team sees the same numbers.',
+		minutes: 2,
+	},
+	'first-project': {
+		id: 'first-project',
+		title: 'Create your first project',
+		description:
+			'Projects group invoices, budgets and time entries per client.',
+		minutes: 1,
+	},
+	'import-customers': {
+		id: 'import-customers',
+		title: 'Import your customers',
+		description: 'Bring your existing customer list over as a CSV.',
+		minutes: 5,
+	},
+	'first-invoice': {
+		id: 'first-invoice',
+		title: 'Send your first invoice',
+		description: 'Compose, preview and send — payment link included.',
+		minutes: 4,
+	},
+	reminders: {
+		id: 'reminders',
+		title: 'Turn on payment reminders',
+		description: 'Stop chasing overdue invoices by hand.',
+		minutes: 1,
+	},
+};
+const STEP_ORDER: StepId[] = [
+	'profile',
+	'integrations',
+	'invites',
+	'first-project',
+	'import-customers',
+	'first-invoice',
+	'reminders',
+];
+
+export interface OnboardingWorkspaceContext {
+	// -- Coopted contexts ------------------------------------------------------
+	shell: PageShellContext<PeekItem>;
+	// -- Page-owned state (seeded + re-seeded from the `onboarding` prop) ------
+	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: visit + toast; the server recomputes statuses) -----
+	completeStep: (id: StepId) => Promise<void>;
+	skipStep: (id: StepId) => Promise<void>;
+	toggleIntegration: (
+		integration: WorkspaceIntegration,
+		next: boolean
+	) => Promise<void>;
+	/** Rejects with Laravel's field-keyed error bag on 422 — steps map it locally. */
+	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'
+);
+
+export function provideOnboardingWorkspace(): OnboardingWorkspaceContext {
+	const { toast } = useToast();
+	const { confirm } = useConfirm();
+
+	// -- Coopt the specific contexts: once, here, for the whole page. ----------
+	const shell = usePageShellContext<PeekItem>();
+
+	// -- Reactive read of the server's checklist truth. -------------------------
+	const onboarding = useProp<OnboardingProp>('onboarding');
+
+	// -- The checklist definition lives client-side; the server owns statuses. -
+	const steps = reactive<OnboardingStep[]>(
+		STEP_ORDER.map((id) => ({ ...STEP_DEFS[id], 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,
+	});
+
+	// Re-seed every local field whenever a visit lands a fresh `onboarding`
+	// prop — the only place server truth flows into page state.
+	const applyState = (state: OnboardingProp) => {
+		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;
+	};
+	applyState(onboarding.value);
+	watch(onboarding, applyState);
+
+	// Open the first unfinished step, right after the initial page load —
+	// Inertia props are already hydrated before this runs, so no separate
+	// loading state is needed the way the Nuxt adaptation needs one.
+	activeStep.value =
+		steps.find((candidate) => candidate.status === 'todo')?.id ?? null;
+
+	// 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)!;
+
+	// -- 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 --------------------------------------------------------------------
+	// Manual done/skip: the same status endpoint the domain mutations below
+	// hit implicitly server-side. The response's `onboarding` prop already
+	// carries the new status by the time this promise resolves.
+	const completeStep = async (id: StepId) => {
+		const title = step(id).title;
+		await visit('patch', `/onboarding/steps/${id}`, { status: '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 visit('patch', `/onboarding/steps/${id}`, { status: 'skipped' });
+		openNextTodo(id);
+	};
+
+	// Optimistic, per the BbSwitch doctrine: flip now, revert + toast on failure.
+	// `busy` drives `readonly` so conflicting toggles cannot queue. The server
+	// flips the 'integrations' step to complete on a successful connect; the
+	// partial reload brings that back with everything else.
+	const toggleIntegration = async (
+		integration: WorkspaceIntegration,
+		next: boolean
+	) => {
+		integration.busy = true;
+		integration.connected = next;
+		try {
+			await visit(
+				'post',
+				`/onboarding/integrations/${integration.id}/${next ? 'connect' : 'disconnect'}`
+			);
+			toast({
+				title: `${integration.name} ${next ? 'connected' : 'disconnected'}.`,
+				variant: 'success',
+			});
+		} catch {
+			integration.connected = !next;
+			toast({
+				title: `Could not ${next ? 'connect' : 'disconnect'} ${integration.name}.`,
+				variant: 'destructive',
+			});
+		} finally {
+			integration.busy = false;
+		}
+	};
+
+	// Carries real user input, so it rides usePromiseForm instead of the
+	// generic visit() helper: a 422 rejects with Laravel's field-keyed error
+	// bag, which InviteStep maps onto its own `inviteError` display.
+	const invitesForm = usePromiseForm<{ emails: string[]; role: InviteRole }>({
+		emails: [],
+		role: 'member',
+	});
+	const sendInvites = async (emails: string[], role: InviteRole) => {
+		invitesForm.form.emails = emails;
+		invitesForm.form.role = role;
+		await invitesForm.post('/onboarding/invites', {
+			only: [...RELOAD_PROPS],
+		});
+		toast({
+			title: `${emails.length} invitation${emails.length === 1 ? '' : 's'} sent.`,
+			variant: 'success',
+		});
+	};
+
+	const projectForm = usePromiseForm<{ name: string; client: string }>({
+		name: '',
+		client: '',
+	});
+	const createProject = async (draft: ProjectDraft) => {
+		projectForm.form.name = draft.name;
+		projectForm.form.client = draft.client;
+		await projectForm.post('/onboarding/project', {
+			only: [...RELOAD_PROPS],
+		});
+		toast({ title: `${draft.name} created.`, variant: 'success' });
+	};
+
+	// The bound File serializes as multipart automatically; onProgress gives
+	// real upload bytes natively — no manual FormData/XHR wiring needed.
+	const importForm = useForm<{ file: File | null }>({ file: null });
+	const importCustomers = (file: File): Promise<void> => {
+		importState.uploading = true;
+		importState.totalBytes = file.size;
+		importState.sentBytes = 0;
+		importForm.file = file;
+		return new Promise((resolve, reject) => {
+			importForm.post('/onboarding/customers/import', {
+				only: [...RELOAD_PROPS],
+				forceFormData: true,
+				onProgress: (event) => {
+					if (event?.total) {
+						importState.sentBytes = event.loaded ?? 0;
+						importState.totalBytes = event.total;
+					}
+				},
+				onSuccess: () => {
+					importState.uploading = false;
+					toast({
+						title: `${onboarding.value.importedCustomers ?? 0} customers imported.`,
+						variant: 'success',
+					});
+					resolve();
+				},
+				onError: (errors) => {
+					importState.uploading = false;
+					reject(errors);
+				},
+			});
+		});
+	};
+
+	const setReminders = async (enabled: boolean) => {
+		reminders.enabled = enabled;
+		try {
+			await visit('patch', '/onboarding/reminders', {
+				enabled,
+				cadence: reminders.cadence,
+			});
+			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 visit('patch', '/onboarding/reminders', {
+			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;
+		// A full visit, not a partial reload: the server redirects to the
+		// dashboard, so there is no `onboarding` prop left to re-seed from.
+		router.visit('/onboarding/dismiss', { method: 'post' });
+		toast({
+			title: 'Onboarding dismissed. Find it again under Settings → Setup.',
+			variant: 'success',
+		});
+	};
+
+	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', href: '/dashboard' },
+						{ key: 'getting-started', text: 'Getting started' },
+					]"
+				/>
+				<BbButton
+					append:icon="lucide:arrow-right"
+					class="shrink-0"
+					href="/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 href="/docs/setup" size="sm" 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
+				href="/settings/general"
+				prepend:icon="lucide:pencil"
+				size="sm"
+				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;
+	}
+	try {
+		await ctx.sendInvites(emails.value, role.value);
+		emails.value = [];
+	} catch (errors) {
+		// Server-side (422) validation lands here as Laravel's field-keyed
+		// error bag — usePromiseForm rejects with it unchanged.
+		const bag = errors as Record<string, string | string[]>;
+		const message = bag.emails ?? bag.role;
+		inviteError.value = Array.isArray(message)
+			? message[0]
+			: (message ?? 'Could not send invitations.');
+	}
+};
+</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"
+			:href="`/projects/${ctx.firstProject.value.id}`"
+			size="sm"
+			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 = async () => {
+	nameError.value = '';
+	if (!draft.name.trim()) {
+		nameError.value = 'Give the project a name.';
+		return;
+	}
+	try {
+		await ctx.createProject({ ...draft });
+	} catch (errors) {
+		// Server-side (422) validation lands here as Laravel's field-keyed
+		// error bag — usePromiseForm rejects with it unchanged.
+		const bag = errors as Record<string, string | string[]>;
+		const message = bag.name ?? bag.client;
+		nameError.value = Array.isArray(message)
+			? message[0]
+			: (message ?? 'Could not create the project.');
+	}
+};
+</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"
+				href="/customers"
+				size="sm"
+				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"
+				href="/invoices/create"
+				prepend:icon="lucide:receipt"
+				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.
+- **The server recomputes step statuses, so the client never has to.**
+  Every mutation route — connect an integration, send invites, create the
+  project, import customers, enable reminders — flips the relevant step's
+  status server-side as part of the same request; the partial reload
+  (`only: ['onboarding']`) brings that back in one round trip. There is no
+  `persistStatus` writer like the Vue/Nuxt versions: the local `steps`
+  array is purely a mirror of `applyState`, re-run by a `watch` every time
+  the prop changes.
+- **`sendInvites`/`createProject` ride `usePromiseForm`, not the generic
+  `visit()` helper.** They carry real user input with server-side
+  validation, so a 422 needs to reach specific fields. `usePromiseForm`
+  rejects with Laravel's field-keyed error bag on failure; `InviteStep` and
+  `FirstProjectStep` are the only two leaves with a `try`/`catch` around
+  their context call, mapping the bag onto the same `inviteError`/
+  `nameError` display the client-side checks already populate — one error
+  surface per field, whether the rejection came from the browser or the
+  server.
+- **The CSV import binds the file into a `useForm`, not `FormData`.**
+  Inertia detects the bound `File` and switches the request to multipart
+  automatically, and `onProgress` reports real `loaded`/`total` bytes
+  natively — no manual `FormData` assembly and no `XMLHttpRequest`, unlike
+  the Nuxt adaptation (`ofetch` has no upload-progress hook, so that one
+  forces a raw XHR).
+- **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.
+- **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 issues
+  a visit or toasts on its own.
+- **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.
+- **Dismissal is a real redirect, not a partial reload.** `router.post`
+  with no `only` list lets the server's redirect land on the dashboard;
+  there is no `onboarding` prop left to re-seed from after it, so the
+  action doesn't await one.
+- **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 (`Inertia::render('Onboarding/Index', ['onboarding' =>
+OnboardingState::for($request->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.
+- **Lazy integration catalog**: if the integrations list grows large or
+  varies per plan, share it as `Inertia::lazy()` and read it with
+  `useLazyProp` instead of hardcoding the four entries in `context.ts`.