Onboarding: polish + design system + docs

- New "Soft sheets" subsection in `docs/design-system.md` § Component patterns: documents the `--sheet-*` tokens (added in M1), when to use a soft sheet vs `ModalDialog`, and points at `OnboardingWizard.svelte` as the canonical implementation.
- `lib/ui/CLAUDE.md` opens with an "Not part of this module: soft sheets" note explaining the wizard isn't a `ModalDialog` variant and cross-references the design-system entry.
- `docs/architecture.md` AI row clarifies the wizard owns first-launch consent now; the AI module only tracks runtime states.
- `accessibility.spec.ts` extended with a wizard scan (re-entry path, axe over each step). Per-FDA-branch banner coverage stays in tier-3 Vitest.

Author: vdavid

apps/desktop/src/lib/ui/CLAUDE.md

@@ -19,6 +19,17 @@ Reusable UI components used across the entire desktop app.
 | `ToggleGroup.svelte`     | Generic segmented-control primitive: tabs ARIA shape or Ark toggle-group ARIA shape            |
 | `toast/`                 | Centralized toast notification system: store, container, item                                  |
 
+## Not part of this module: soft sheets
+
+`OnboardingWizard.svelte` (in `$lib/onboarding/`) is the canonical soft-sheet implementation: ~90% viewport coverage,
+frosted backdrop, no drag / Escape / × button, body owns the close gesture. It's NOT a `ModalDialog` variant — sheets
+break almost every `ModalDialog` constraint (full-bleed sizing, no title bar, no Escape, no draggable). Adding sheet
+variants to `ModalDialog` would dilute its contract; sheets get their own shell, their own `--sheet-*` design tokens
+(see [`docs/design-system.md`](../../../../docs/design-system.md) § "Soft sheets"), and their own focus-trap. They still
+plug into the same dialog registry (`'onboarding'`) so MCP tracking works through the same id-based surface.
+
+Reach for a sheet when you have a multi-step flow the user must commit to. Reach for `ModalDialog` for everything else.
+
 ## ModalDialog
 
 Props:

apps/desktop/test/e2e-playwright/accessibility.spec.ts

@@ -409,6 +409,77 @@ for (const mode of ['light', 'dark'] as const) {
       }
     })
 
+    test(`Onboarding wizard (re-entry)`, async ({ tauriPage }) => {
+      // The wizard is mounted via the same re-entry path the menu / palette use.
+      // On macOS the E2E fixture grants FDA so re-entry shows step 1 (already-granted variant);
+      // on Linux re-entry lands directly on step 2 (the Linux skip-step-1 path).
+      // Step 3 is reached by clicking "One more optional setup step" on step 2.
+      // Per-FDA-branch banner coverage stays in tier-3 Vitest (`StepAi.a11y.test.ts`).
+      await ensureAppReady(tauriPage)
+
+      const WIZARD_SELECTOR = '[data-dialog-id="onboarding"]'
+
+      await dispatchMenuCommand(tauriPage, 'cmdr.openOnboarding')
+      await tauriPage.waitForSelector(WIZARD_SELECTOR, 3000)
+
+      // Scan the wizard at its opening step (step 1 on macOS, step 2 on Linux).
+      const { all: openingViolations } = await runAxeAudit(tauriPage, `Onboarding wizard opening (${mode})`, WIZARD_SELECTOR)
+      expect(openingViolations, `Violations on wizard opening step (${mode})`).toHaveLength(0)
+
+      const isMac = process.platform === 'darwin'
+      if (isMac) {
+        // Advance step 1 (already-granted) → step 2 so we can scan it too.
+        await tauriPage.evaluate(`(function() {
+          var btn = document.querySelector('${WIZARD_SELECTOR} .primary-slot button');
+          if (btn) btn.click();
+        })()`)
+        await expect
+          .poll(async () => {
+            return tauriPage.evaluate<number | null>(`(function() {
+              var dots = document.querySelectorAll('${WIZARD_SELECTOR} .step-dot');
+              for (var i = 0; i < dots.length; i++) {
+                if (dots[i].getAttribute('aria-current') === 'step') return i + 1;
+              }
+              return null;
+            })()`)
+          }, { timeout: 3000 })
+          .toBe(2)
+        const { all: step2Violations } = await runAxeAudit(tauriPage, `Onboarding wizard step 2 (${mode})`, WIZARD_SELECTOR)
+        expect(step2Violations, `Violations on wizard step 2 (${mode})`).toHaveLength(0)
+      }
+
+      // Advance step 2 → step 3 via the "One more optional setup step" button (primary slot, last).
+      await tauriPage.evaluate(`(function() {
+        var btns = document.querySelectorAll('${WIZARD_SELECTOR} .primary-slot button');
+        for (var i = 0; i < btns.length; i++) {
+          if ((btns[i].textContent || '').indexOf('One more optional') !== -1) {
+            btns[i].click();
+            return;
+          }
+        }
+      })()`)
+      await expect
+        .poll(async () => {
+          return tauriPage.evaluate<number | null>(`(function() {
+            var dots = document.querySelectorAll('${WIZARD_SELECTOR} .step-dot');
+            for (var i = 0; i < dots.length; i++) {
+              if (dots[i].getAttribute('aria-current') === 'step') return i + 1;
+            }
+            return null;
+          })()`)
+        }, { timeout: 3000 })
+        .toBe(3)
+      const { all: step3Violations } = await runAxeAudit(tauriPage, `Onboarding wizard step 3 (${mode})`, WIZARD_SELECTOR)
+      expect(step3Violations, `Violations on wizard step 3 (${mode})`).toHaveLength(0)
+
+      // Finish so the wizard doesn't leak into the next test (the safety net would otherwise fire).
+      await tauriPage.evaluate(`(function() {
+        var btns = document.querySelectorAll('${WIZARD_SELECTOR} .primary-slot button');
+        if (btns.length > 0) btns[btns.length - 1].click();
+      })()`)
+      await expect.poll(async () => !(await tauriPage.isVisible(WIZARD_SELECTOR)), { timeout: 3000 }).toBeTruthy()
+    })
+
     test(`File viewer with text file`, async ({ tauriPage }) => {
       await ensureAppReady(tauriPage)
 

docs/architecture.md

@@ -32,7 +32,7 @@ All under `apps/desktop/src/lib/`.
 | `logging/`                  | Unified logging: LogTape config, batching bridge to Rust, verbose toggle                                                                                                                                                                                                                                                                      |
 | `error-reporter/`           | Error report dialog (Flow A preview), auto-send toast (Flow B), shared `error-report-flow` entry point                                                                                                                                                                                                                                        |
 | `crash-reporter/`           | Frontend half of the crash pipeline: detects the persisted crash file on next launch and offers to send it                                                                                                                                                                                                                                    |
-| `ai/`                       | Local LLM features (folder suggestions), download flow                                                                                                                                                                                                                                                                                        |
+| `ai/`                       | Local LLM features (folder suggestions), download flow. Runtime states only (`downloading`, `installing`, `ready`, `starting`); first-launch consent is owned by `lib/onboarding/`                                                                                                                                                            |
 | `indexing/`                 | Drive index state, events, priority triggers, scan status overlay                                                                                                                                                                                                                                                                             |
 | `query-ui/`                 | Shared filter-and-act-on primitives consumed by Search and (M7+) Selection: `QueryBar`, `ModeChips`, `AiPromptStrip`, `FilterChips` (size/modified/scope/pattern), `QueryResults` (path pills + row menus), `EmptyState`, `recent-items/` footer + popover with adapter pattern, `createQueryFilterState()` factory, shared keyboard contract |
 | `search/`                   | Whole-drive file search dialog (first `query-ui` consumer): thin orchestrator + Search-only extras (scope, system-dir exclusions, AI label/pattern), snapshot store + virtual `search-results` volume, "Open in pane" handoff, MCP `open_search_dialog` tool, index lifecycle                                                                 |

docs/design-system.md

@@ -488,6 +488,35 @@ All dialogs use `ModalDialog.svelte`.
 Overlay: `background: rgba(0,0,0, 0.4)` in light mode, `rgba(0,0,0, 0.6)` in dark mode (higher opacity needed for
 contrast against dark chrome).
 
+### Soft sheets (app)
+
+Soft sheets cover ~90% of the viewport over the running app and host multi-step flows the user must commit to (consent,
+setup, onboarding). The canonical implementation is `OnboardingWizard.svelte`. Unlike `ModalDialog`, sheets have no
+title bar, no drag, no Escape close, no × button: the body owns the close gesture (Next / Finish / Allow / Deny). The
+sheet is centered, lifted off the canvas with a frosted backdrop, and sized via the `--sheet-*` tokens below.
+
+| Token                     | Value                       | Role                                                                                         |
+| ------------------------- | --------------------------- | -------------------------------------------------------------------------------------------- |
+| `--sheet-width-fraction`  | `90vw`                      | Sheet width target. Pair with `min(var(--sheet-max-width), var(--sheet-width-fraction))`.    |
+| `--sheet-height-fraction` | `90vh`                      | Sheet height target. Pair with `min(var(--sheet-max-height), var(--sheet-height-fraction))`. |
+| `--sheet-max-width`       | `1200px`                    | Hard cap so the sheet stays readable on ultra-wide displays.                                 |
+| `--sheet-max-height`      | `900px`                     | Hard cap so the sheet stays compact on 4K+ vertical setups.                                  |
+| `--sheet-radius`          | `var(--radius-lg)` (8px)    | Matches macOS sheet convention.                                                              |
+| `--sheet-backdrop-blur`   | `10px`                      | Frosted-glass amount. GPU-composited; the sheet is the only consumer today.                  |
+| `--sheet-backdrop-color`  | `var(--color-overlay-heavy)` | Dim layer behind the sheet. Resolves to `rgba(0,0,0,0.6)` in both themes (heavier than `ModalDialog`'s scrim because sheets sit over the full app, not a centered cluster). |
+
+**When to use a sheet vs `ModalDialog`:**
+
+| Use a sheet for                                                                | Use `ModalDialog` for                                                |
+| ------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
+| Multi-step flows the user must commit to (onboarding, paid licensing later)    | Single-decision confirmations (delete, discard, overwrite)           |
+| Content that needs > 480px width (provider picker grids, comparison tables)    | Short prose + a two-button choice                                    |
+| Flows where Escape-to-dismiss would lose meaningful state                      | Flows where Escape-to-dismiss is safe (re-openable, idempotent)      |
+| First-launch consent (user must choose, can't cancel)                          | Any everyday dialog (drag, blur, focus trap all come from the prim.) |
+
+Sheets are heavier: they own their own backdrop, focus trap, MCP dialog-registry entry (`'onboarding'`), and footer
+chrome. Only use one when the contract genuinely needs it.
+
 ### Inputs (app)
 
 ```css