AgentHub/docs/plans/onboarding/README.md

First-run setup and tour (per account)

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

• The wizard never offers bypass. It remembers a default permission mode (Auto / Accept edits / Ask / Plan). Since 2026-10-19 Settings → AI tools → Session defaults may make Bypass the default (Claude's bypassPermissions, Codex's bypass switch), behind a confirm; the pet chat still never starts in it.
• 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

• The user_prefs table: user_key (u<id>, or local), prefs (JSON), onboarded_at, updated_at. It is migration-safe (CREATE IF NOT EXISTS).
• 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.
• 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.
• 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

• 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).

• New preference keys:

  • agenthub.defaultTool, read by AddLaneModal before the install default;
  • agenthub.permissionMode, read by WorkspaceHome. bypassPermissions is accepted only as set from Settings → Session defaults.

• 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 on the Dashboard (/).

• 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 sidebar's + (the rail's tree icon while the sidebar is folded)
  • the folder field (its suggestions list included while it is open) — or the folder browser while it is open over it
  • Create
  • the prompt box
  • sending the prompt
  • the session pane
  • done

• "Run setup again" lives in Settings → Appearance (every account can open it; System is not a member's page).

• i18n in English and Vietnamese. Tests: the server route; the client wizard, tour and prefs; snapshots.

• Docs: docs/API.md, docs/SERVER-MODE.md and the CLAUDE.md marker.