From df6f956cde5fa00a9d6d59c3083628ce77708691 Mon Sep 17 00:00:00 2001 From: lucaronin Date: Mon, 13 Apr 2026 08:01:24 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20add=20ADR-0058=20and=20ADR-0059=20for?= =?UTF-8?q?=20Claude=20Code=20onboarding=20gate=20and=20local-only=20commi?= =?UTF-8?q?ts=20(guard=20=E2=80=94=20from=20commits=20fd9de04,=20a13e36a)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...laude-code-first-launch-onboarding-gate.md | 35 +++++++++++++++++++ ...9-local-only-git-commits-without-remote.md | 33 +++++++++++++++++ docs/adr/README.md | 2 ++ 3 files changed, 70 insertions(+) create mode 100644 docs/adr/0058-claude-code-first-launch-onboarding-gate.md create mode 100644 docs/adr/0059-local-only-git-commits-without-remote.md diff --git a/docs/adr/0058-claude-code-first-launch-onboarding-gate.md b/docs/adr/0058-claude-code-first-launch-onboarding-gate.md new file mode 100644 index 00000000..ff633851 --- /dev/null +++ b/docs/adr/0058-claude-code-first-launch-onboarding-gate.md @@ -0,0 +1,35 @@ +--- +type: ADR +id: "0058" +title: "Claude Code first-launch onboarding gate" +status: active +date: 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 `claude` CLI 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, reuses `useClaudeCodeStatus` for 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 `claude` CLI gains an in-app auto-install path, making the manual prompt unnecessary. diff --git a/docs/adr/0059-local-only-git-commits-without-remote.md b/docs/adr/0059-local-only-git-commits-without-remote.md new file mode 100644 index 00000000..9bd946c1 --- /dev/null +++ b/docs/adr/0059-local-only-git-commits-without-remote.md @@ -0,0 +1,33 @@ +--- +type: ADR +id: "0059" +title: "Local-only git commits for vaults without a remote" +status: active +date: 2026-04-12 +--- + +## Context + +ADR-0034 mandates a git repo for every vault, but never required a remote. In practice, the commit flow always attempted a `git push` after staging and committing. Users with purely local vaults (no remote configured) would hit a push error on every commit. + +The fix required distinguishing between two commit modes at the point of user action: +- **Push mode**: repo has a remote → commit then push (existing behavior). +- **Local mode**: repo has no remote → commit only, no push attempted. + +## Decision + +**`useCommitFlow` detects the vault's remote status before opening the commit dialog and at commit time. When `hasRemote === false`, it commits locally and skips the push step entirely, showing "Committed locally (no remote configured)" as the confirmation toast.** + +## Options considered + +- **Option A** (chosen): Runtime detection via a new `useGitRemoteStatus` hook + `CommitMode` type (`push` | `local`). Pros: transparent to the user, no configuration needed, adapts if a remote is added later. Cons: adds an async remote-status check to the commit open flow. +- **Option B**: Require all vaults to have a remote (keep blocking behavior). Pros: simpler model. Cons: breaks the valid use case of a local-only knowledge base; contradicts ADR-0056 which removed provider-specific OAuth. +- **Option C**: Let the push fail silently and always show success. Pros: no new logic. Cons: misleading feedback; users wouldn't know the push was skipped vs. succeeded. + +## Consequences + +- `useGitRemoteStatus` is a new hook that exposes `remoteStatus` and `refreshRemoteStatus`; it is called both when opening the commit dialog and after each commit. +- `CommitDialog` now receives a `commitMode` prop and adjusts its CTA label accordingly (`Commit & Push` vs `Commit`). +- The `commitAndPush` callback in `CommitFlowConfig` is replaced by `resolveRemoteStatus` + `vaultPath`; the actual git operations (`git_commit`, `git_push`) are invoked directly inside `useCommitFlow`. +- Local-only commits fire `trackEvent('commit_made')` the same as push commits for analytics continuity. +- Re-evaluation warranted if a remote is later added to a previously-local vault and the UX should prompt the user to push accumulated commits. diff --git a/docs/adr/README.md b/docs/adr/README.md index e23d0d76..5bdc994a 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -113,3 +113,5 @@ proposed → active → superseded | [0055](0055-h1-is-the-only-editor-title-surface.md) | H1 is the only editor title surface | active | | [0056](0056-system-git-cli-auth-no-provider-oauth.md) | System git auth only — no provider-specific OAuth or repo APIs | active | | [0057](0057-alpha-stable-release-channels-and-beta-cohorts.md) | Alpha/stable release channels with PostHog beta cohorts | active | +| [0058](0058-claude-code-first-launch-onboarding-gate.md) | Claude Code first-launch onboarding gate | active | +| [0059](0059-local-only-git-commits-without-remote.md) | Local-only git commits for vaults without a remote | active |