ContributingDraft

Onboarding v2: a step per import

The user's direction (28 Sep): onboarding leads. Every import and setup gets its own dedicated, interactive step, not a line item inside a bigger step. launch owns the whole flow, its order, and each step's "wow"; the owner team named per step builds that step's engine (the data, the tools, the events). Two of these already have their own design docs, linked below; this file is the frame they sit inside, and the spec for the steps that do not have one yet.

The step-shell (launch owns; every step plugs into it)#

One shell, reused by all ten steps:

• Skippable. Every step has a visible "Skip for now" that never blocks the next step. A skipped step can be finished later from Settings or a vyre command (existing convention, deck/onboard/onboard.js's current steps already do this for Tailscale, Claude and history).
• Resumable. Reloading, closing the tab, or a Mac and a phone both mid-onboarding: state lives on the box (core/onboard/index.js's existing onboard.status), never only in the page. A step's own progress (a scan in flight, an import mid-stage) survives a reload too, by asking the owning module's own status tool (import.status, and the vault-import equivalent once it exists), not by the shell inventing its own copy of that state.
• Progress, live. Every step that does real work (a scan, an import, a connection) shows progress as it happens, not just a spinner: the existing progressRow(label, state, note, since) checklist-row component (todo/doing/done/failed, a spinner/check glyph, elapsed time) is the shape every step's "doing" state renders through, so a person options-checking a multi-source step (secrets, step 5) sees each source's own row advance independently.
• A small celebration per step. Not a modal, not confetti: a one-line, specific win in the step's own voice when it finishes ("Vyre now manages 14 keys", not "Done!"). Silent for a skipped step. Off under prefers-reduced-motion same as the rest of onboarding.
• A summary at the end. After the last step, one screen totalling what happened: sessions imported, keys imported, accounts connected, drives synced, devices paired, what was skipped and where to finish it later. Read from each step's own final state, not tracked separately by the shell.

Terminology#

ADR 0038 (docs, status: draft as of this writing): "server" and "device" apply everywhere user-facing, not only onboarding, no alias window on marketing surfaces. "Box" survives only as the literal vyre box <sub> CLI form during 0.1.1's alias window (vyre server <sub> is the new form, not yet shipped) and as the unrenamed role: "box" config value, neither of which this flow's own copy quotes except where it is literally showing real CLI output (step 2's pairing instructions, which quote vyre up's live menu text verbatim and must stay in sync with whatever that command actually prints, not with this doc's wording).

One onboarding for every device#

The lead's decision (29 Sep), resolving federation's question about the second-device flow: one onboarding-v2, not a second experience. A new Mac or PC runs the exact same steps.

• Step 2 detects an existing server. If this device finds one it can pair to, the step becomes "Add this device to your Vyre server" instead of the first-server flow. Steps already done at the server level (naming, the Claude sign-in) show as done and are skipped for this run.
• Device-level steps run again for this device: step 4 (import this device's own sessions), step 5 (import this device's own secrets), step 9 (the Capsule tour) all run fresh per device, since each device has its own history, its own local secrets and its own Capsule.
• Add a device from the Deck. Settings > Devices gets an "Add a device" entry: the one-line install command and a pairing code, so a person does not have to leave the Deck to start a second device's onboarding.
• Windows. Follows the windows teammate's guide (docs/using/windows.md, in progress); asked them directly rather than guessing at Windows-specific install steps.
• Only the upload wiring (federation's transport, import.start) waits on e2e's review; the design and the UI for all of this can proceed now.

The ten steps#

Reconciled (the lead, 29 Sep): the client STEPS array (deck/onboard/onboard.js) now has 11 entries, in the same order as this table, with two intentional differences kept on purpose rather than forced into a false 1:1 mapping:

• Step 2 is two client screens, tailscale then name: connecting to Tailscale and reserving an address are different enough pieces of work (one is a sign-in and a wait, the other is a certificate request with its own multi-row progress) that merging them into one screen would lose the per-piece progress each already shows. They're adjacent and both still called "Pair this device with the server" in spirit.
• Step 10 (the Capsule tour) is its own screen, capsule, split out of the old devices step. devices (Mac and phone pairing, step 9) used to be the mandatory, non-skippable final screen; that property moved to capsule, which is genuinely last now and triggers finish(). devices is a normal, skippable middle step today.

No step is silently combined or renumbered without a note here.

Step 2: Pair this device with the server#

Built: the existing tailscale screen now has an "Advanced: your tailnet policy" collapsible, shown once signed in, with the merged policy snippet (Taildrive, Taildrop, SSH, egress when on) from tailnet's onboard.tailscale {action: "policy"} (work/tailnet ecd89c0c), replacing the four separate placeholder snippets in docs/adr/0014-tailnet.md: pretty-printed JSON, a Copy button, tailnet's own notes. ready: false shows tailnet's why instead. A person who onboarded before this shipped would want the same panel in Settings > Network; not built there yet.

The existing-server detection (this step becoming "Add this device to your Vyre server" when one is found) still waits on tailnet's proposed names.discover tool (peer scan + an unauthenticated /v1/whoami probe on each online peer), not yet built (design agreed): tailnet is on another 0.1.1 item first.

Step 4: Import your sessions#

Full spec: docs/design/import.md on work/memory-iq (8702ab66). Built (deck/onboard/onboard.js history(), provisional pending memory-iq's real tool shapes): Discover (import.scan, sources with counts/date range/size, dev and Vyre folders unticked with the reason, nothing leaves the device), Choose (import.plan {include}, "N sessions, X MB, from these folders, to your server", a "Keep them in sync" checkbox unticked by default, a Fast/Gentle reading-pace choice with neither preselected, and the note that Claude Code keeps sessions 30 days so import now, Vyre never changes Claude Code's own settings; confirms with import.start {plan, mode, pace}), Watch it fill (import.status, polled every 5 s since the loopback's event stream carries only onboard.*, in three plain-language stages: Searchable now, Understood, The graph growing; a question box wired to memory.ask (not memory.answer, which can't see freshly imported sessions) as soon as the first sessions are searchable, showing the answer and sources, or "Not sure yet." plus known facts when it abstains). import.start's pace field is confirmed correct by memory-iq. This step replaces today's "Your history" step rather than extending it, keeping the step's id and CLI label ("Your history") unchanged so test/journey.test.js's CLI-output assertion still holds.

Step 5: Import your secrets#

Stubbed for now (secrets in deck/onboard/onboard.js's STEPS, a "Coming soon" card, Skip/Continue, no backend call). Lead's spec (28 Sep): discover keys on the device, recognise their providers, show them masked and grouped by project, one Touch ID for the batch, animate each key into the vault with its connection created, end on "Vyre now manages N keys". Each source is its own card inside the step: .env files, shell exports (~/.zshrc and the like), password managers (1Password, Bitwarden, Apple Passwords), Chrome passwords, SSH keys, and the MCP and Claude settings env. The board is ready (VaultImport.dc.html, work/app-design 19a96abd); asked vault for the discover/import tool shapes per source before building the real screen.

Step 6: Connect accounts#

Stubbed for now (accounts in deck/onboard/onboard.js's STEPS, a "Coming soon" card, Skip/Continue, no backend call). Google and email, MCP servers, through vault and connectors. Spec needed; likely close to existing connectors flows, reframed as its own step with the shell's progress/celebration.

Step 7: Agent computers#

Built (computers in deck/onboard/onboard.js's STEPS). The lead's choice (29 Sep): Off / Browser only / Browser + desktops, a warm one-line explanation of what each gives an agent (a browser to look things up in, live to watch; a full desktop for anything a browser alone can't do), and the server size each needs. glass-live owns the backend (docs/design/agent-browsers.md, not written yet) and the real size numbers; both are placeholder "still measuring" text for now, since e2e hasn't measured them. No server call yet: the choice is kept locally only, same degrade-gracefully shape as every stub step here.

Step 8: Vyre Drive#

The user's decisions (the lead, 29 Sep): files on demand by default, a what-to-sync folder picker with sizes, per-folder agent access, a receive-files switch, no quota ("warn when the server's disk is low" instead). Full spec: docs/design/drive-onboarding.md on work/federation (e69a544a), which is candid about what each piece needs: on-demand mounting is real (files.drive.share/mount); the folder picker and per-folder access are M each (no picker UI, no grant table for shares yet); the receive-files switch is S but not wired to a settings UI yet (it's a config.json key today; federation tried the settings-hub route and reverted it rather than ship unreviewed); the "watch it appear on your other device" celebration needs the phone app and a Capsule drop target, neither of which exist, so it can't be the real celebration yet. Still a stub (drive in deck/onboard/onboard.js's STEPS, "Coming soon", Skip/Continue), but the copy now names the decided design accurately instead of a placeholder line. Building the real picker/access/switch and the celebration waits on federation's and the phone team's tools landing; nothing to wire safely yet.

Step 9: Your phone#

Lead: "later". A stub for 0.1.1: shown, explained, skippable, no engine yet, so the step order and the summary screen are correct once mobile's swipe-to-approve pairing lands.

Step 10: A tour of the Capsule#

Press ⌥Space (the corrected default hotkey, team/archive/work-journals/launch-surfaces.md). The landing page's hero Capsule demo (site/index.html, site/app.js's .keys/demo wiring) is sample-data only and public-facing, but its shape, tabs (Typing/Recall/Held/Waiting) and the ⌥Space open/close handling are a reasonable starting point for capsule-pro's real, signed-in tour.

Open items (tracked in team/archive/work-journals/launch-surfaces.md "Needs from others")#

• vault: tool shapes for step 5 and step 6.
• connectors: confirm step 6's scope (which of today's connector flows this step wraps).
• app-design: the step-shell's progress/celebration board (shared by every step); still owed.
• glass-live: docs/design/agent-browsers.md (not written yet), and the real server-size numbers for step 7, once e2e measures them.
• mobile: confirm step 9 is fine as a stub for 0.1.1.
• federation: step 8's drafted options, once the lead brings the user's decisions back.
• tailnet: the proposed names.discover tool for step 2's existing-server detection (design agreed, not built).
• windows: confirm docs/using/windows.md covers what step 2 needs to point a fresh Windows PC at for install, once that guide exists.