Skip to main content

Onboarding: one front door

The intro page's "Get set up" flow — three labelled steps that cover everything a fresh node needs before it can do anything: a local model, an account, and the connectors your agent reaches through.

The first-run wizard around it (packages/ui/src/desktop/Oobe.tsx) is four steps: welcome, how the desktop starts, look, setup. "How should the desktop start?" is deliberately its own step ahead of "Pick a look": choosing between the home surface, a widget board and a plain wallpaper decides whether the app has a front door at all, and it used to sit fifth of seven in a list of wallpapers, weighted identically to a decorative gradient. Backdrop choices in both steps now carry a selected state — they had none, so clicking one confirmed nothing on the one screen whose job is to teach the app.

Status: implemented. packages/ui/src/home/SetupCard.tsx, rendered from HomeView. The sign-in half is packages/core/src/SignInCard.tsx; shared state is packages/core/src/account-store.ts and packages/core/src/connectors/store.ts.

Why it exists​

The three things a new user has to do lived in three unrelated places, and only one of them was on the home page.

  • The model was a card on home (OnboardingCard), shown only while the agent was unconfigured.
  • The account existed only inside the games lobby and HorribleAssault's front door. The way to discover this app has an account at all was to open a game.
  • The connectors were a row of tiles above the ask bar with no label explaining what they were for.

So the flow is one card with three numbered steps. A step already satisfied collapses to a check and a one-line summary rather than vanishing, so the card doesn't reflow underneath you and you can see what you already have. It hides itself entirely once all three are done, and home.setupDismissed hides it early; the Show setup command (shell.setup) brings it back.

shell.setup clears home.setupDismissed and forces the desktop to the splash backdrop, so it is only ever wired to a control that means "show me setup" — the Start menu and app-menu entries. It is deliberately not how any other surface reaches a connector; see Connectors.

Identity and connectors are two steps, on purpose​

They look like the same thing — both say "GitHub", both open a consent page — and they are not. Collapsing them into one button would quietly change what a click grants.

Sign-in (step 2)Connector (step 3)
What it proveswho you arewhat your agent may reach
Who holds the client secretthe game server (a separate process)your node
Provider token after the flowdiscardedkept, Fernet-encrypted in secrets.db
What is storeda JWT for our own server, in .data/games_token.jsonconnector:<id> credential record
Scopesread:user / email profileread:user+repo, drive.readonly, …
Wire shape{signed_in, account, handle}{connected, scopes, account}
Routes/api/games/auth/*/api/connectors/*

One button doing both would ask for repo scope in order to answer "who are you". The two halves can also fail independently, which is far harder to explain after the fact than it is to show as two steps up front. See Connectors › Why this is not the games sign-in.

One sign-in, not three​

SignInCard is the app's only sign-in UI. It renders in four places: the setup card's step 2, the games lobby sidebar, the games first-run hero, and HorribleAssault's boot overlay.

There used to be three separate copies, and the reason to care is what happened to them: they drifted. HorribleAssault's had a fallback for a blocked pop-up; the games first-run hero still called the device-only entry point, so it never opened a consent page at all and its prompt rendered Enter code at with both values blank. Nothing about that was visible from either file.

It lives in packages/core, not packages/ui, because hassault and games are core modules and a core module must not import packages/ui — the same reason Avatar3D is there.

The failure ladder​

Every "open this page for the user" in the app is a ladder, and each rung can fail silently. That is the whole difficulty: window.open returns null when a blocker eats it and the shell's invoke rejects — neither throws anything a caller notices by default.

Three rules hold it together:

  1. openExternal returns whether it opened, and callers that need the user to arrive somewhere must check it. A blocked pop-up otherwise leaves a button reading "Waiting…" for fifteen minutes while the flow polls, correctly, for a page nobody was ever shown.
  2. The blocked prompt outlives the attempt. It is cleared on success only. It used to be cleared in a finally, so the address vanished the moment the flow timed out — taking away the one thing the user had just been told to go and use.
  3. The bottom rung is not a link. CopyableLink (packages/core) shows the raw address with a Copy button once opening has failed, because clicking is precisely what just failed.

installExternalLinkBridge must report failure for the same reason: it cancels the browser's own navigation before substituting its own, so a failed substitute means the click is simply gone. It now announces through onExternalOpenFailed, which AppShell turns into a persistent toast carrying the URL.

The bug that motivated all of it​

Under the old Tauri shell, app commands were gated behind Tauri v2's ACL: a command needed an allow-* permission defined in a permissions TOML and listed in the capability file. open_external was added, registered, and shipped with neither.

So invoke('open_external') was rejected, openExternal caught it and returned false, and the link bridge discarded that false — which meant OAuth sign-in and every external link in the desktop app (docs links, the Ollama install link, connector consent pages) did nothing at all, with no error anywhere. Three layers of correct-looking code and one missing line of TOML.

The Electron shell has one place a command is allowed — its name in COMMANDS (apps/desktop/src/main.ts) — so there is no second half to forget, and scripts/desktop-smoke.mjs calls open_external against the running app.

What the wizard does not do​

It teaches the user their own name, a backdrop, a theme and three credential steps — and nothing about the product. There is no tour, no help menu and no in-app docs pane, so the moment it closes was the only moment anyone could be told what the app is.

Two deliberately small things close that, rather than a fifth step:

  • The final step signs off by naming the workspace launcher the user is about to land on (the wizard closes onto the splash home surface, where the tiles sit directly under the ask bar).
  • The Start menu's footer carries a Help entry (shell.help) opening the published documentation. It checks openExternal's boolean return and toasts the URL when it fails: window.open returns null behind a pop-up blocker and the shell's invoke rejects on an older shell, and neither throws — a Help button that silently does nothing teaches the user that the docs do not exist.

What it explicitly does not do is offer a boot-workspace picker. Booting into an empty desktop is a decision this app made on purpose (DEFAULT_BOOT_WORKSPACE, see windowing); the fix for the presets being invisible was to surface them, not to change where the app starts.

Shared state​

Two module-level stores, both useSyncExternalStore-shaped, both with a reset() test seam.

useAccount() — one fetch of /api/games/status, many subscribers. Each surface used to keep its own copy, so signing in on one left the others on a signed-out screen until they happened to remount. A failed refresh reports phase: 'unavailable' and keeps the account it already had: a backend blip must not present as a sign-out.

useConnectors() / useConnector(id) — the same for the connector list, which previously had exactly one caller in the repo (the home tile row, holding it in useState). A pane asking "is Google connected?" had no way to ask.

useConnector reports connected and known separately. A gate that hid its pane on !connected alone would flash "connect this" at an already-connected user on every single mount.

ConnectionGate​

What a pane renders instead of dead-ending on the backend's 409:

<ConnectionGate connector="github">
<RepoPicker onPick={...} />
</ConnectionGate>

It never builds a connect UI of its own — it calls requestConnect(id), an event ConnectorDialog answers at the shell level by opening the real popover as a modal over whatever you were looking at. One connect flow, reachable from anywhere, and reaching it is never a navigation: nothing about connecting a connector sends you to the splash surface or re-opens this card. The reference case is the GitHub repo viewer (packages/core/src/modules/github/RepoViewer.tsx).

Which game server sign-in talks to​

pnpm dev used to force GAMES_SERVER_URL=ws://localhost:9090, and the bundled game server it starts has no OAuth client id or secret. Since the env var beats the games.serverUrl setting, the effect was that GitHub and Google sign-in were dead in the browser layout while pnpm dev:desktop — which never set the variable — worked. Two launchers, two answers to "can I sign in", for a reason nothing on screen could explain.

Both launchers now default to the hosted server, like a packaged node. --local-gameserver (or HORRIBLE_DEV_LOCAL_GAMESERVER=1) points at the bundled one, which still starts either way. pnpm dev prints which it chose.

A provider the server reports as supporting neither flow still renders disabled — but the card names the server, because the reason lives there and a bare greyed-out button is indistinguishable from a broken one.

Testing​

FileCovers
packages/core/src/__tests__/external.test.tsopenExternal's boolean under a blocker and under a rejecting shell invoke; the bridge announcing failure
packages/core/src/__tests__/account.test.tsthe blocked prompt surviving a failed attempt; cleared on success; prefer: 'device'; the redirect→device fallback
packages/core/src/__tests__/stores.test.tsboth stores: shared publication, request de-duplication, a blip not reading as a sign-out, the connect-request bus
scripts/desktop-smoke.mjsthe shell's commands answer — open_external among them — and refuse what they must, in the packaged app