9b41d51231
Some checks are pending
Auto-update PR branches / Update open PR branches (push) Waiting to run
CI / Frontend Static Quality Checks (push) Waiting to run
CI / Frontend Tests & Coverage (push) Waiting to run
CI / Rust Tests & Quality Checks (push) Waiting to run
CI / Linux build verification (push) Waiting to run
Deploy docs / Build VitePress site (push) Waiting to run
Deploy docs / Deploy to GitHub Pages (push) Blocked by required conditions
Release (Alpha) / Compute alpha version (push) Waiting to run
Release (Alpha) / Build release artifacts (push) Blocked by required conditions
Release (Alpha) / GitHub Release (alpha) (push) Blocked by required conditions
Release (Alpha) / Update docs and release pages (push) Blocked by required conditions
Source snapshot: 514ab1975951d94342ea38e64101d5a0f1c51c77
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.