From c86a6ab9c58e95040c061c65c0ee01610adc60c4 Mon Sep 17 00:00:00 2001 From: lucaronin Date: Mon, 20 Apr 2026 10:24:11 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20add/update=20ADR=20for=20starter=20vaul?= =?UTF-8?q?t=20local-first=20remote=20flow=20(guard=20=E2=80=94=20from=20c?= =?UTF-8?q?ommit=20374b4f66)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...l-first-with-explicit-remote-connection.md | 33 +++++++++++++++++++ docs/adr/README.md | 1 + 2 files changed, 34 insertions(+) create mode 100644 docs/adr/0070-starter-vaults-local-first-with-explicit-remote-connection.md diff --git a/docs/adr/0070-starter-vaults-local-first-with-explicit-remote-connection.md b/docs/adr/0070-starter-vaults-local-first-with-explicit-remote-connection.md new file mode 100644 index 00000000..d53a67f7 --- /dev/null +++ b/docs/adr/0070-starter-vaults-local-first-with-explicit-remote-connection.md @@ -0,0 +1,33 @@ +--- +type: ADR +id: "0070" +title: "Starter vaults are local-first with explicit remote connection" +status: active +date: 2026-04-19 +--- + +## Context + +ADR-0046 moved the Getting Started vault to a public GitHub repo cloned at runtime, and ADR-0059 established that Tolaria should support valid local-only vaults without treating a missing remote as an error. + +That still left one mismatch: a freshly cloned starter vault inherited the template repo's `origin` remote. New users therefore landed in a vault that looked remote-backed by default, even though the intended workflow was to explore locally first and only connect a personal remote later. Keeping the starter remote also risked accidental pushes to the public template repo and gave Tolaria no safe place to reject incompatible remotes before tracking started. + +## Decision + +**After cloning the public starter vault, Tolaria removes every configured git remote so the vault opens local-only by default.** Users connect a remote later through an explicit Add Remote flow exposed from the `No remote` status-bar chip and the command palette. + +**The new `git_add_remote` backend is the only path for attaching a remote to an existing local-only vault.** It adds `origin`, fetches the remote, rejects incompatible or ahead histories, and only starts tracking when the remote is safe for the current local repo. + +## Options considered + +- **Strip starter-vault remotes and add an explicit connect flow** (chosen): preserves a local-first onboarding experience, matches ADR-0059's local-only model, and prevents accidental coupling to the public template repo. Cons: users who want sync must do one extra explicit step. +- **Keep the starter repo's remote attached**: simplest implementation, but it makes the template repo look like the user's real sync target and increases the risk of accidental pushes or confusing remote state. +- **Force remote replacement during onboarding**: guarantees a personal remote up front, but adds too much setup friction to the Getting Started path and weakens Tolaria's offline/local-first story. + +## Consequences + +- Fresh Getting Started vaults now behave like any other local-only vault: commit locally first, then opt into sync later. +- The app gains a dedicated Add Remote UX (`AddRemoteModal`) plus a backend connection path (`git_add_remote`) instead of overloading clone or commit flows. +- Remote attachment is safer: Tolaria can reject unrelated or incompatible histories before the vault starts tracking a remote. +- The starter repo remains a distribution source only, not an ongoing sync destination. +- Re-evaluate if Tolaria later needs a faster "publish this local starter vault to my own repo" flow that should prefill or streamline the Add Remote step. diff --git a/docs/adr/README.md b/docs/adr/README.md index f5a41799..cfe3a830 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -125,3 +125,4 @@ proposed → active → superseded | [0067](0067-autogit-idle-and-inactive-checkpoints.md) | AutoGit idle and inactive checkpoints | active | | [0068](0068-h1-only-title-surface-with-optional-untitled-auto-rename.md) | H1-only title surface with optional untitled auto-rename | active | | [0069](0069-neighborhood-mode-for-note-list-relationship-browsing.md) | Neighborhood mode for note-list relationship browsing | active | +| [0070](0070-starter-vaults-local-first-with-explicit-remote-connection.md) | Starter vaults are local-first with explicit remote connection | active |