8739805f99
Some checks failed
Auto-update PR branches / Update open PR branches (push) Has been cancelled
CI / Frontend Static Quality Checks (push) Has been cancelled
CI / Frontend Tests & Coverage (push) Has been cancelled
CI / Rust Tests & Quality Checks (push) Has been cancelled
CI / Linux build verification (push) Has been cancelled
Release (Alpha) / Compute alpha version (push) Has been cancelled
Release (Alpha) / Build release artifacts (push) Has been cancelled
Release (Alpha) / GitHub Release (alpha) (push) Has been cancelled
Release (Alpha) / Update docs and release pages (push) Has been cancelled
Deploy docs / Build VitePress site (push) Has been cancelled
Deploy docs / Deploy to GitHub Pages (push) Has been cancelled
2.1 KiB
2.1 KiB
type, id, title, status, superseded_by, date
| type | id | title | status | superseded_by | date |
|---|---|---|---|---|---|
| ADR | 0058 | Claude Code first-launch onboarding gate | superseded | 0062 | 2026-04-12 |
Context
Tolaria's AI features depend on the claude CLI being installed on the user's machine. New users arriving with no prior context could open the app, try AI-powered workflows, and get silent failures with no explanation.
A dedicated first-launch prompt was needed to:
- Surface whether the
claudeCLI is already present. - Guide users to the install page if it is missing.
- Not block experienced users who want to skip the check.
The existing useOnboarding hook already handles vault setup and resolves to a ready state, but it had no mechanism for a post-vault, pre-app step.
Decision
A one-time ClaudeCodeOnboardingPrompt is shown immediately after vault onboarding resolves to ready, before the main app shell renders. Dismissal is persisted in localStorage via useClaudeCodeOnboarding, so the gate appears exactly once per install.
Options considered
- Option A (chosen): Full-screen gate after vault onboarding, dismissed once and persisted in
localStorage. Pros: cannot be missed on first launch, reusesuseClaudeCodeStatusfor live detection, zero impact on returning users. Cons: adds one extra render phase to the boot sequence. - Option B: Inline banner inside the main app. Pros: less intrusive. Cons: easy to ignore, harder to surface install link prominently.
- Option C: Check at feature use time (show error when AI action fails). Pros: no new screen. Cons: poor UX — silent failure or cryptic error at the moment the user needs AI.
Consequences
- The app boot sequence now has four phases: loading → welcome (if needed) → Claude Code check (once) → main shell.
useClaudeCodeOnboarding(enabled)takes a boolean so the gate is skipped entirely in note windows and before vault onboarding completes.- The dismissal key (
tolaria:claude-code-onboarding-dismissed) must be pre-set in Playwright storage state so smoke tests bypass the gate. - Re-evaluation warranted if the
claudeCLI gains an in-app auto-install path, making the manual prompt unnecessary.