# First-run setup and tour (per account)

Asked 2026-10-08 (modelled on Orca's 3-step welcome). Decisions:

- **Bypass is never remembered** (CLAUDE.md rule). The wizard remembers a default *permission mode* (Auto / Accept edits / Ask / Plan); bypass stays the red per-session switch.
- **Per account, on the server.** The choices follow the account to any browser. Local mode is one account, `local`.
- **The tutorial is a step-by-step spotlight tour.**

## Server

- [x] The `user_prefs` table: `user_key` (`u<id>`, or `local`), `prefs` (JSON), `onboarded_at`, `updated_at`. It is migration-safe (`CREATE IF NOT EXISTS`).
- [x] `server/routes/me.js`, mounted at `/api/me`:
  - `GET /prefs` returns `{prefs, onboardedAt}`;
  - `PUT /prefs` merges `{prefs}`, takes only keys in `PREF_KEYS`, string values of at most 8 KB each, and `null` deletes a key;
  - `POST /onboarded` marks the account as onboarded.
  - Writes are same-origin. A member may write their own prefs, and nobody else's.
- [x] S3: when a member saves a mode, the theme in their Claude Code `~/.claude/settings.json` follows it (dark or light), written through `write-as`.
- [x] P6: `agenthub-provision create` seeds the member's `~/.claude.json` with `hasCompletedOnboarding` and trust for the home folder. It runs as the member (`runuser` + the shared node). Verified: trusting the home also covers folders under it.

## Client

- [x] `lib/userPrefs.ts`:
  - **On login:** hydrate localStorage from the server, then re-apply the theme, language and pet.
  - **On save:** wrapping `localStorage.setItem` for `PREF_KEYS` pushes each change (debounced).
- [x] New preference keys:
  - `agenthub.defaultTool`, read by AddLaneModal before the install default;
  - `agenthub.permissionMode`, read by WorkspaceHome. `bypassPermissions` is never accepted here.
- [x] `components/onboarding/OnboardingWizard.tsx`, mounted in Layout. It shows when the account is not onboarded AND has no workspace (an account that already has one is marked onboarded silently). Steps:
  1. Default agent (detected tools as a grid, plus "show more") and the default permission mode.
  2. Appearance: System, Dark and Light as preview cards, a theme grid for dark and for light below them, then language and terminal font.
  3. Pet: none or an installed pet, and its size.
  4. Notifications: enable, sound and preview, send a test.

  The footer has Skip, Back and Continue (Ctrl+Enter). The last step's button is "Add your first workspace", which starts the tour.
- [x] `components/onboarding/Tour.tsx`: a spotlight on `data-tour` targets. Each step moves on when its condition holds, and the step reached is saved in prefs (`agenthub.tour`). The steps:
  - Add workspace
  - the folder field
  - Create
  - the prompt box
  - sending the prompt
  - the session pane
  - done
- [x] "Run setup again" lives in Settings → Appearance (every account can open it; System is not a member's page).
- [x] i18n in English and Vietnamese. Tests: the server route; the client wizard, tour and prefs; snapshots.
- [x] Docs: `docs/API.md`, `docs/SERVER-MODE.md` and the CLAUDE.md marker.