Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.
Python agent-orchestrationai-agentai-coding-assistantclaude-codecoding-agentcomputer-usedesktop-applocal-firstmcppersonal-jarvisvoice-assistantvoice-coding
feat(onboarding): guide new users to an agent subscription and a wake word
rubenluetke10-beep3223dd01c91c
diff --git a/jarvis/setup/onboarding_meta.py b/jarvis/setup/onboarding_meta.pyindex a34059e714..8de9333313 100644--- a/jarvis/setup/onboarding_meta.py+++ b/jarvis/setup/onboarding_meta.py@@ -16,8 +16,8 @@ CURRENT_TERMS_VERSION = "1.0"# Canonical step order — must match SETUP_STEP_IDS in the frontend# (components/onboarding/setup/setupSteps.ts). Setup runs INSIDE the real app:-# each step opens the app's own place for the job (the API Keys page, the-# wake-word group in Settings) and points at it. The tour of the app runs+# each step opens the app's own place for the job (the API Keys page and its+# Agents tab, the wake-word group in Settings) and points at it. The tour of the app runs# AFTER the completion restart and is tracked separately# (``tour_completed_at`` in jarvis.setup.state).# Restart batching (maintainer mandate 2026-07-18): permissions and voice sit@@ -28,6 +28,7 @@ CURRENT_TERMS_VERSION = "1.0"ONBOARDING_STEPS: list[str] = ["welcome","keys",+ "subscriptions","permissions","voice","ready",diff --git a/jarvis/ui/web/frontend/src/components/onboarding/OnboardingGate.test.tsx b/jarvis/ui/web/frontend/src/components/onboarding/OnboardingGate.test.tsxindex 6057d71346..bfcc66511c 100644--- a/jarvis/ui/web/frontend/src/components/onboarding/OnboardingGate.test.tsx+++ b/jarvis/ui/web/frontend/src/components/onboarding/OnboardingGate.test.tsx@@ -2,7 +2,9 @@ import { act, cleanup, render, screen, waitFor } from "@testing-library/react";import { afterEach, expect, it, vi } from "vitest";vi.mock("./setup/SetupTour", () => ({- SetupTour: ({ preview }: { preview: boolean }) => <div data-testid="guide" data-preview={String(preview)} />,+ SetupTour: ({ preview, startAt }: { preview: boolean; startAt?: string }) => (+ <div data-testid="guide" data-preview={String(preview)} data-start={startAt ?? ""} />+ ),}));vi.mock("./tour/GuidedTour", () => ({GuidedTour: ({ onDone }: { onDone: () => void }) => (@@ -13,7 +15,7 @@ vi.mock("./tour/GuidedTour", () => ({}));import { OnboardingGate } from "./OnboardingGate";-import { TOUR_START_EVENT } from "./tourEvents";+import { SETUP_REPLAY_EVENT, TOUR_START_EVENT } from "./tourEvents";afterEach(() => {cleanup();@@ -133,3 +135,15 @@ it("replays the setup on a finished install without completing it", async () =>window.history.replaceState(null, "", "/");}});++it("replays setup from the API Keys page on request from Settings", async () => {+ stub({ ...base, completed: true, tour_completed: true });+ render(<OnboardingGate activeSection="profile" />);+ await new Promise((r) => setTimeout(r, 20));+ expect(screen.queryByTestId("guide")).toBeNull();+ act(() => {+ window.dispatchEvent(new CustomEvent(SETUP_REPLAY_EVENT));+ });+ await waitFor(() => expect(screen.getByTestId("guide").dataset.preview).toBe("true"));+ expect(screen.getByTestId("guide").dataset.start).toBe("keys");+});diff --git a/jarvis/ui/web/frontend/src/components/onboarding/OnboardingGate.tsx b/jarvis/ui/web/frontend/src/components/onboarding/OnboardingGate.tsxindex ae145960fc..c5e95992cb 100644--- a/jarvis/ui/web/frontend/src/components/onboarding/OnboardingGate.tsx+++ b/jarvis/ui/web/frontend/src/components/onboarding/OnboardingGate.tsx@@ -1,6 +1,6 @@import { lazy, Suspense, useEffect, useMemo, useState } from "react";import { useOnboarding } from "@/hooks/useOnboarding";-import { TOUR_START_EVENT } from "./tourEvents";+import { SETUP_REPLAY_EVENT, TOUR_START_EVENT } from "./tourEvents";/*** Code-split: a finished install renders this gate as `null` forever, so the@@ -30,8 +30,11 @@ function param(name: string): string | null {* loading or on a fetch error it renders nothing, so a broken guide never* traps anyone.* 2. The tour: after the completion restart, a spotlight explains the app- * one control at a time. Shown once (`tour_completed`), replayable from- * Settings via `jarvis:tour-start`.+ * one control at a time. Shown once (`tour_completed`); `jarvis:tour-start`+ * replays it alone.+ *+ * Settings' replay (`jarvis:setup-replay`) walks setup again as a preview,+ * from the API Keys page on (the consent is already given), then the tour.** Replay, never destructive: `?onboarding=force` walks the setup on a* finished install without completing or restarting anything, then hands@@ -44,6 +47,9 @@ export function OnboardingGate({ activeSection }: { activeSection?: string } = {const [dismissed, setDismissed] = useState(false);const [tourRequested, setTourRequested] = useState(() => param("tour") === "force");const [tourDone, setTourDone] = useState(false);+ // Bumped by each Settings replay; > 0 means a setup preview is requested,+ // and the value remounts the guide so every replay starts fresh.+ const [setupReplay, setSetupReplay] = useState(0);const forced = useMemo(() => param("onboarding") === "force", []);useEffect(() => {@@ -55,11 +61,19 @@ export function OnboardingGate({ activeSection }: { activeSection?: string } = {setTourDone(false);setTourRequested(true);};+ const onSetupReplay = () => {+ setDismissed(false);+ setTourDone(false);+ setTourRequested(false);+ setSetupReplay((n) => n + 1);+ };window.addEventListener("jarvis:onboarding-changed", onChanged);window.addEventListener(TOUR_START_EVENT, onTour);+ window.addEventListener(SETUP_REPLAY_EVENT, onSetupReplay);return () => {window.removeEventListener("jarvis:onboarding-changed", onChanged);window.removeEventListener(TOUR_START_EVENT, onTour);+ window.removeEventListener(SETUP_REPLAY_EVENT, onSetupReplay);};}, [onb]);@@ -67,14 +81,19 @@ export function OnboardingGate({ activeSection }: { activeSection?: string } = {if (onb.loading || onb.error || !onb.state) return null;- const showSetup = (forced || !onb.state.completed) && !dismissed && (forced || !inIde);+ const replaying = setupReplay > 0;+ const asked = forced || replaying;+ const showSetup = (asked || !onb.state.completed) && !dismissed && (asked || !inIde);if (showSetup) {return (<Suspense fallback={null}><SetupTour+ key={setupReplay}onb={onb}- preview={forced && onb.state.completed}+ preview={asked && onb.state.completed}+ startAt={replaying && onb.state.completed ? "keys" : undefined}onFinished={() => {+ setSetupReplay(0);setDismissed(true);setTourDone(false);setTourRequested(true);diff --git a/jarvis/ui/web/frontend/src/components/onboarding/setup/SetupTour.test.tsx b/jarvis/ui/web/frontend/src/components/onboarding/setup/SetupTour.test.tsxindex 2c8c62d0f0..eeeadf88e6 100644--- a/jarvis/ui/web/frontend/src/components/onboarding/setup/SetupTour.test.tsx+++ b/jarvis/ui/web/frontend/src/components/onboarding/setup/SetupTour.test.tsx@@ -3,6 +3,7 @@ import { afterEach, beforeAll, beforeEach, expect, it, vi } from "vitest";import { _resetProvidersCacheForTests } from "@/hooks/useProviders";import type { useOnboarding } from "@/hooks/useOnboarding";import { loadLocaleChunk } from "@/i18n";+import { requestedApiKeysTab } from "@/lib/apiKeysTab";import { useEventStore } from "@/store/events";import { SetupTour } from "./SetupTour";@@ -36,6 +37,8 @@ const plan = {};let providers = [openai];+let agentRows: Array<{ jarvis: string; label?: string; oauth_connected?: boolean }> = [];+let wakeWord = { phrase: "", enabled: false };let calls: Array<{ url: string; method: string }> = [];function stubFetch() {@@ -49,7 +52,8 @@ function stubFetch() {if (url === "/api/permissions/status") return reply({ platform: "win32" });if (url === "/api/providers") return reply({ providers });if (url === "/api/setup/starter-plans") return reply({ plans: [plan], selected: null, custom_id: "custom" });- if (url === "/api/settings/wake-word") return reply({ phrase: "", enabled: false });+ if (url === "/api/settings/wake-word") return reply(wakeWord);+ if (url === "/api/jarvis-agent/status") return reply({ mapping: agentRows });if (url === "/api/settings/autostart") return reply({ enabled: false, supported: true });return reply({ ok: true });}),@@ -88,6 +92,8 @@ beforeAll(async () => {beforeEach(() => {providers = [{ ...openai, secrets_set: {} }];+ agentRows = [];+ wakeWord = { phrase: "", enabled: false };_resetProvidersCacheForTests();useEventStore.getState().setActiveSection("chats");stubFetch();@@ -120,9 +126,47 @@ it("waits for a key, and lets the user go on later", async () => {await screen.findByTestId("setup-keys-waiting");expect((screen.getByTestId("onboarding-primary") as HTMLButtonElement).disabled).toBe(true);fireEvent.click(screen.getByTestId("setup-keys-later"));+ await waitFor(() => expect(screen.getByTestId("setup-card").dataset.step).toBe("subscriptions"));+ expect(onb.saveStep).toHaveBeenLastCalledWith("subscriptions", ["keys"]);+});++it("opens the Agents tab and waits for a subscription", async () => {+ const onb = fakeOnb({ ...accepted, current_step: "subscriptions" });+ render(<SetupTour onb={onb} preview={false} onFinished={vi.fn()} />);+ const status = await screen.findByTestId("setup-subscriptions-status");+ expect(useEventStore.getState().activeSection).toBe("apikeys");+ expect(requestedApiKeysTab()).toBe("subagents");+ expect((screen.getByTestId("onboarding-primary") as HTMLButtonElement).disabled).toBe(true);+ expect(status.textContent).not.toContain("Claude");+ fireEvent.click(screen.getByTestId("setup-subscriptions-later"));await waitFor(() => expect(screen.getByTestId("setup-card").dataset.step).toBe("voice"));- expect(onb.saveStep).toHaveBeenLastCalledWith("voice", ["keys"]);+ expect(onb.saveStep).toHaveBeenLastCalledWith("voice", ["subscriptions"]);await waitFor(() => expect(useEventStore.getState().activeSection).toBe("settings"));+ expect(requestedApiKeysTab()).toBeNull();+});++it("lets the user on once a subscription is signed in", async () => {+ agentRows = [{ jarvis: "claude-api", label: "Claude (API-Key)", oauth_connected: true }];+ render(<SetupTour onb={fakeOnb({ ...accepted, current_step: "subscriptions" })} preview={false} onFinished={vi.fn()} />);+ await waitFor(() => expect(screen.getByTestId("setup-subscriptions-status").textContent).toContain("Claude"));+ expect((screen.getByTestId("onboarding-primary") as HTMLButtonElement).disabled).toBe(false);+});++it("asks for a wake word before going on, with a way to leave it for later", async () => {+ const onb = fakeOnb({ ...accepted, current_step: "voice" });+ render(<SetupTour onb={onb} preview={false} onFinished={vi.fn()} />);+ await screen.findByTestId("setup-voice-later");+ expect((screen.getByTestId("onboarding-primary") as HTMLButtonElement).disabled).toBe(true);+ fireEvent.click(screen.getByTestId("setup-voice-later"));+ await waitFor(() => expect(screen.getByTestId("setup-card").dataset.step).toBe("ready"));+ expect(onb.saveStep).toHaveBeenLastCalledWith("ready", ["voice"]);+});++it("goes on from the wake word once one is saved", async () => {+ wakeWord = { phrase: "Hey George", enabled: true };+ render(<SetupTour onb={fakeOnb({ ...accepted, current_step: "voice" })} preview={false} onFinished={vi.fn()} />);+ await waitFor(() => expect((screen.getByTestId("onboarding-primary") as HTMLButtonElement).disabled).toBe(false));+ expect(screen.queryByTestId("setup-voice-later")).toBeNull();});it("switches on the plan a key saved during the step completes", async () => {@@ -167,8 +211,10 @@ it("walks a replay from the start and never writes, completes or restarts", asyn});await waitFor(() => expect(screen.getByTestId("setup-card").dataset.step).toBe("keys"));fireEvent.click(await screen.findByTestId("setup-keys-later"));+ await waitFor(() => expect(screen.getByTestId("setup-card").dataset.step).toBe("subscriptions"));+ fireEvent.click(await screen.findByTestId("setup-subscriptions-later"));await waitFor(() => expect(screen.getByTestId("setup-card").dataset.step).toBe("voice"));- fireEvent.click(screen.getByTestId("onboarding-primary"));+ fireEvent.click(await screen.findByTestId("setup-voice-later"));const start = await screen.findByTestId("onboarding-start");await act(async () => {fireEvent.click(start);@@ -186,3 +232,10 @@ it("dims the app and keeps its card above every dialog", async () => {expect(layer.hasAttribute("data-tour-layer")).toBe(true);expect(screen.getByTestId("tour-dim").className).toContain("pointer-events-auto");});++it("starts a replay from Settings at the API Keys page, with no way back to the consent", async () => {+ const onb = fakeOnb({ ...accepted, completed: true });+ render(<SetupTour onb={onb} preview startAt="keys" onFinished={vi.fn()} />);+ await waitFor(() => expect(screen.getByTestId("setup-card").dataset.step).toBe("keys"));+ expect(screen.queryByTestId("setup-back")).toBeNull();+});diff --git a/jarvis/ui/web/frontend/src/components/onboarding/setup/SetupTour.tsx b/jarvis/ui/web/frontend/src/components/onboarding/setup/SetupTour.tsxindex 98a3a5023f..6efd486b2b 100644--- a/jarvis/ui/web/frontend/src/components/onboarding/setup/SetupTour.tsx+++ b/jarvis/ui/web/frontend/src/components/onboarding/setup/SetupTour.tsx@@ -6,6 +6,8 @@ import type { useOnboarding } from "@/hooks/useOnboarding";import { switchBrainProvider, useProviders } from "@/hooks/useProviders";import { applyStarterPlan, getStarterPlans, selectStarterPlan, type StarterPlan } from "@/hooks/useStarterPlans";import { useWakeWord } from "@/hooks/useWakeWord";+import { fetchAgentConnections } from "@/lib/agentChatApi";+import { clearApiKeysTabRequest, requestApiKeysTab } from "@/lib/apiKeysTab";import { fill, setUiLanguage, useLocaleChunk, useT, useUiLanguage, type UiLanguage } from "@/i18n";import { cn } from "@/lib/utils";import { useEventStore } from "@/store/events";@@ -21,6 +23,7 @@ type Onb = ReturnType<typeof useOnboarding>;const MASCOT: Record<SetupStepId, MascotAction> = {welcome: "wave",keys: "look-left",+ subscriptions: "spin",voice: "look-right",permissions: "look-left",ready: "jump",@@ -33,7 +36,8 @@ const LANGS: UiLanguage[] = ["en", "de", "es"];** There is no setup screen of its own: the window dims, and the guide walks* the user to the places where each thing is really set — the API Keys page- * for one key, the wake-word group in Settings, on macOS the permissions —+ * for one key, its Agents tab for a subscription, the wake-word group in+ * Settings, on macOS the permissions —* and waits there with a small card. The dim takes clicks, the hole does* not: only the part being set up can be used, so nothing else starts before* setup is done. Every step but the consent has a way on without doing it.@@ -41,15 +45,18 @@ const LANGS: UiLanguage[] = ["en", "de", "es"];* The last step completes onboarding; the backend then restarts the app once* and the tour of the app follows. `preview` (a replay) never completes and* never restarts — it only walks the steps and hands over to the tour.+ * `startAt` lets a replay from Settings begin past the consent.*/export function SetupTour({onb,preview,onFinished,+ startAt,}: {onb: Onb;preview: boolean;onFinished: () => void;+ startAt?: SetupStepId;}) {const t = useT();const ready = useLocaleChunk("onboarding");@@ -59,7 +66,7 @@ export function SetupTour({// it left off (never past the consent).const [stepId, setStepId] = useState<SetupStepId>(() =>preview- ? "welcome"+ ? (startAt ?? "welcome"): resumeStep(stepsFor(null), onb.state?.current_step ?? null, Boolean(onb.state?.terms.accepted)),);const [skipped, setSkipped] = useState<string[]>(() => onb.state?.skipped_steps ?? []);@@ -83,12 +90,18 @@ export function SetupTour({};}, []);- // Open the app's own place for this step before pointing at it.+ // Open the app's own place for this step before pointing at it — on the+ // API Keys page also the right tab.useEffect(() => {if (!ready || !step.section) return;+ if (step.section === "apikeys") requestApiKeysTab(step.apiKeysTab ?? null);+ else clearApiKeysTabRequest();const nav = useEventStore.getState();if (nav.activeSection !== step.section) nav.setActiveSection(step.section);- }, [ready, step.section, stepId]);+ }, [ready, step.section, step.apiKeysTab, stepId]);++ // Later visits to the API Keys page open on its own default tab again.+ useEffect(() => clearApiKeysTabRequest, []);const rect = useAnchorRect(ready ? step.anchor : undefined, Boolean(step.scrollTo), stepId);@@ -105,7 +118,9 @@ export function SetupTour({const index = Math.max(0, steps.indexOf(stepId));const nextId = steps[index + 1] ?? null;- const prevId = index > 1 ? steps[index - 1] : null; // never back behind the consent+ // Never back behind the consent, nor behind where a replay started.+ const firstId = preview && startAt ? startAt : steps[1];+ const prevId = index > 1 && stepId !== firstId ? steps[index - 1] : null;const next = useCallback(() => {if (nextId) goTo(nextId, skipped);@@ -162,7 +177,8 @@ export function SetupTour({<div className="mt-4">{stepId === "welcome" && <WelcomeStep onb={onb} preview={preview} onAccepted={() => { cheer(); next(); }} />}{stepId === "keys" && <KeysStep next={next} later={later} cheer={cheer} />}- {stepId === "voice" && <VoiceStep next={next} />}+ {stepId === "subscriptions" && <SubscriptionsStep next={next} later={later} />}+ {stepId === "voice" && <VoiceStep next={next} later={later} />}{stepId === "permissions" && <PermissionsStep next={next} />}{stepId === "ready" && <ReadyStep onb={onb} preview={preview} onFinished={onFinished} />}</div>@@ -403,8 +419,88 @@ function KeysStep({ next, later, cheer }: { next: () => void; later: () => void;);}-/** The wake-word group of Settings is open behind the card; the step only says what is set. */-function VoiceStep({ next }: { next: () => void }) {+/** Poll interval while the subscriptions step waits for a sign-in. */+const SUBSCRIPTION_POLL_MS = 3000;++/**+ * The Agents tab of the API Keys page is open behind the card. Agents run+ * best on a subscription (Claude, ChatGPT/Codex, …): a flat monthly price+ * instead of paying per call. The step waits for one to be signed in; the+ * sign-in itself happens on the tab.+ */+function SubscriptionsStep({ next, later }: { next: () => void; later: () => void }) {+ const t = useT();+ const connected = useConnectedSubscriptions(SUBSCRIPTION_POLL_MS);+ const has = connected.length > 0;+ return (+ <div className="space-y-3">+ <Status tone={has ? "ok" : "muted"} testId="setup-subscriptions-status">+ {has+ ? fill(t("first_run.subscriptions.connected"), { names: connected.join(", ") })+ : t("first_run.subscriptions.waiting")}+ </Status>+ <p className="text-xs leading-relaxed text-muted-foreground">{t("first_run.subscriptions.why")}</p>+ <PrimaryAction onClick={next} disabled={!has}>+ {t("first_run.continue")}+ </PrimaryAction>+ {!has && (+ <div className="text-center">+ <QuietAction onClick={later} testId="setup-subscriptions-later" className="text-xs">+ {t("first_run.subscriptions.later")}+ </QuietAction>+ </div>+ )}+ </div>+ );+}++/**+ * Subscription names for the status rows whose own label names the API side+ * ("Claude (API-Key)") or is missing; anything else shows its own label.+ */+const SUBSCRIPTION_NAMES: Record<string, string> = {+ "claude-api": "Claude",+ "openai-codex": "ChatGPT (Codex)",+ antigravity: "Antigravity",+ "grok-build": "Grok Build",+};++/**+ * Names of the agent providers signed in with a subscription. `pollMs`+ * re-reads while a step waits for a sign-in; 0 reads once.+ */+function useConnectedSubscriptions(pollMs: number): string[] {+ const [names, setNames] = useState<string[]>([]);+ useEffect(() => {+ let cancelled = false;+ let timer = 0;+ const read = async () => {+ try {+ const rows = await fetchAgentConnections();+ if (!cancelled) {+ const found = rows.filter((r) => r.oauth_connected).map((r) => SUBSCRIPTION_NAMES[r.jarvis] ?? (r.label || r.jarvis));+ setNames((prev) => (prev.join("|") === found.join("|") ? prev : found));+ }+ } catch {+ // Best-effort: a warming backend just reads as "nothing connected yet".+ }+ if (!cancelled && pollMs > 0) timer = window.setTimeout(() => void read(), pollMs);+ };+ void read();+ return () => {+ cancelled = true;+ window.clearTimeout(timer);+ };+ }, [pollMs]);+ return names;+}++/**+ * The wake-word group of Settings is open behind the card. Continue waits+ * for a saved wake word; without one the Call shortcut is the way in, so the+ * step can still be left for later.+ */+function VoiceStep({ next, later }: { next: () => void; later: () => void }) {const t = useT();const { config } = useWakeWord();const on = Boolean(config?.enabled && config.phrase.trim());@@ -413,7 +509,16 @@ function VoiceStep({ next }: { next: () => void }) {<Status tone={on ? "ok" : "muted"} testId="setup-voice-status">{on ? fill(t("first_run.voice.on"), { phrase: config!.phrase }) : t("first_run.voice.off")}</Status>- <PrimaryAction onClick={next}>{t("first_run.continue")}</PrimaryAction>+ <PrimaryAction onClick={next} disabled={!on}>+ {t("first_run.continue")}+ </PrimaryAction>+ {!on && (+ <div className="text-center">+ <QuietAction onClick={later} testId="setup-voice-later" className="text-xs">+ {t("first_run.voice.later")}+ </QuietAction>+ </div>+ )}</div>);}@@ -450,6 +555,7 @@ function ReadyStep({ onb, preview, onFinished }: { onb: Onb; preview: boolean; oconst t = useT();const { providers } = useProviders();const { config } = useWakeWord();+ const subscriptions = useConnectedSubscriptions(0);const [autostart, setAutostart] = useState<{ enabled: boolean; supported: boolean } | null>(null);const [busy, setBusy] = useState(false);const [error, setError] = useState<string | null>(null);@@ -507,6 +613,11 @@ function ReadyStep({ onb, preview, onFinished }: { onb: Onb; preview: boolean; o<div className="space-y-3"><dl className="overflow-hidden rounded-xl border border-border bg-background" data-testid="onboarding-review"><ReviewRow label={t("first_run.ready.row_brain")} value={brainOk ? brain!.label : t("first_run.ready.no_key")} ok={brainOk} />+ <ReviewRow+ label={t("first_run.ready.row_agents")}+ value={subscriptions.length > 0 ? subscriptions.join(", ") : t("first_run.ready.no_subscription")}+ ok={subscriptions.length > 0}+ /><ReviewRowlabel={t("first_run.ready.row_voice")}value={wakeOn ? config!.phrase : t("first_run.ready.shortcut")}diff --git a/jarvis/ui/web/frontend/src/components/onboarding/setup/setupSteps.test.ts b/jarvis/ui/web/frontend/src/components/onboarding/setup/setupSteps.test.tsindex 8c112fada2..7f595b0393 100644--- a/jarvis/ui/web/frontend/src/components/onboarding/setup/setupSteps.test.ts+++ b/jarvis/ui/web/frontend/src/components/onboarding/setup/setupSteps.test.ts@@ -53,6 +53,8 @@ describe("setup steps", () => {it("open the app's own place for each job", () => {expect(SETUP_STEPS.keys.section).toBe("apikeys");+ expect(SETUP_STEPS.subscriptions.section).toBe("apikeys");+ expect(SETUP_STEPS.subscriptions.apiKeysTab).toBe("subagents");expect(SETUP_STEPS.voice.section).toBe("settings");expect(SETUP_STEPS.voice.anchor).toBe("settings-wake-word");expect(SETUP_STEPS.welcome.anchor).toBeUndefined();diff --git a/jarvis/ui/web/frontend/src/components/onboarding/setup/setupSteps.ts b/jarvis/ui/web/frontend/src/components/onboarding/setup/setupSteps.tsindex af3b2882b9..95ccc47a5f 100644--- a/jarvis/ui/web/frontend/src/components/onboarding/setup/setupSteps.ts+++ b/jarvis/ui/web/frontend/src/components/onboarding/setup/setupSteps.ts@@ -1,7 +1,8 @@/*** First-run setup as data: the steps the guide walks through INSIDE the real* app. There is no separate setup screen — each step opens the app's own- * place for the job (the API Keys page, the wake-word group in Settings) and+ * place for the job (the API Keys page and its Agents tab, the wake-word+ * group in Settings) and* points at it, so what the user learns on day one is where things live.*/import type { SectionId } from "@/store/events";@@ -10,7 +11,7 @@ import type { TourPlacement } from "../tour/tourSteps";/** Must match `ONBOARDING_STEPS` in jarvis/setup/onboarding_meta.py. */// Permissions precede voice so the macOS microphone grant exists before the// wake-word group's own microphone test.-export const SETUP_STEP_IDS = ["welcome", "keys", "permissions", "voice", "ready"] as const;+export const SETUP_STEP_IDS = ["welcome", "keys", "subscriptions", "permissions", "voice", "ready"] as const;export type SetupStepId = (typeof SETUP_STEP_IDS)[number];@@ -20,6 +21,8 @@ export interface SetupStep {section?: SectionId;/** The `data-tour` element the step points at; omitted = a centred card. */anchor?: string;+ /** The API Keys tab to show; omitted = the page's default tab. */+ apiKeysTab?: string;/** Scroll the anchor to the top of its scrolling page first (a Settings group). */scrollTo?: boolean;placement: TourPlacement;@@ -30,6 +33,14 @@ export interface SetupStep {export const SETUP_STEPS: Record<SetupStepId, SetupStep> = {welcome: { id: "welcome", placement: "inside", width: 420 },keys: { id: "keys", section: "apikeys", anchor: "apikeys-page", placement: "left", width: 320 },+ subscriptions: {+ id: "subscriptions",+ section: "apikeys",+ apiKeysTab: "subagents",+ anchor: "apikeys-page",+ placement: "left",+ width: 340,+ },voice: {id: "voice",section: "settings",diff --git a/jarvis/ui/web/frontend/src/components/onboarding/tourEvents.ts b/jarvis/ui/web/frontend/src/components/onboarding/tourEvents.tsindex 26ad88eed5..20720635d5 100644--- a/jarvis/ui/web/frontend/src/components/onboarding/tourEvents.ts+++ b/jarvis/ui/web/frontend/src/components/onboarding/tourEvents.ts@@ -7,6 +7,12 @@/** Window event that asks the onboarding gate to replay the app tour. */export const TOUR_START_EVENT = "jarvis:tour-start";+/**+ * Window event that asks the onboarding gate to replay setup (API keys, agent+ * subscriptions, wake word) as a preview, followed by the app tour.+ */+export const SETUP_REPLAY_EVENT = "jarvis:setup-replay";+/** Marks the guide's dim and card, so dialogs can tell its clicks apart. */export const TOUR_LAYER_ATTR = "data-tour-layer";diff --git a/jarvis/ui/web/frontend/src/i18n/locales/onboarding/de.json b/jarvis/ui/web/frontend/src/i18n/locales/onboarding/de.jsonindex 3b5bef5624..bb38ea2a07 100644--- a/jarvis/ui/web/frontend/src/i18n/locales/onboarding/de.json+++ b/jarvis/ui/web/frontend/src/i18n/locales/onboarding/de.json@@ -36,6 +36,14 @@"security": "Schlüssel liegen im Schlüsselbund deines Systems und gehen nur an den Anbieter, den du gewählt hast.","later": "Ich trage später einen Schlüssel ein"},+ "subscriptions": {+ "title": "Verbinde ein Abo für deine Agents",+ "lede": "Das ist der Agents-Tab. Melde dich mit einem Abo an, das du schon bezahlst. Wir empfehlen Claude (Pro oder Max) oder ChatGPT (Codex). Klick in der Zeile auf Connect; dein Browser öffnet sich einmal.",+ "waiting": "Noch kein Abo verbunden…",+ "connected": "Verbunden: {names}.",+ "why": "Ein Abo kostet einen festen Monatspreis. So rechnen die größeren Aufgaben deiner Agents nicht pro Aufruf über deinen API-Schlüssel ab.",+ "later": "Ich verbinde später eins"+ },"permissions": {"title": "Zugriff auf diesem Mac erlauben","lede": "Das sind die Mac-Berechtigungen. Erlaube die, die du möchtest; jede Zeile aktualisiert sich selbst.",@@ -45,13 +53,16 @@"title": "Wähle dein Weckwort","lede": "Tippe hier dein Wort nach „Hey“ ein und speichere es. Das Wort wird auch der Name deines Assistenten. Kein Weckwort? Das Anruf-Kürzel funktioniert immer.","on": "„{phrase}“ ist an. Sag es jederzeit.",- "off": "Noch kein Weckwort. Bis dahin funktioniert das Anruf-Kürzel."+ "off": "Noch kein Weckwort. Bis dahin funktioniert das Anruf-Kürzel.",+ "later": "Überspringen, ich nutze das Anruf-Kürzel"},"ready": {"title": "Alles bereit","lede": "Die App startet einmal neu, damit alles eingeschaltet ist. Danach zeigt dir eine kurze Tour die App.","row_brain": "Gehirn",+ "row_agents": "Agents","row_voice": "Aktivierung",+ "no_subscription": "Kein Abo","no_key": "Noch kein Schlüssel","shortcut": "Anruf-Kürzel","autostart": "Bei der Anmeldung starten",@@ -69,9 +80,9 @@"finish": "Fertig","skip": "Tour überspringen","step_of": "{current} von {total}",- "replay_title": "App-Tour",- "replay_body": "Ein kurzer Rundgang durch die App mit dem Scheinwerfer, derselbe wie nach der Einrichtung.",- "replay": "Tour wiederholen",+ "replay_title": "Einrichtung und App-Tour",+ "replay_body": "Führt dich noch einmal durch die Einrichtung (API-Schlüssel, Abos für Agents, Weckwort) und danach durch den kurzen Rundgang. Nichts startet neu.",+ "replay": "Wiederholen","steps": {"voice": "So sprichst du mit {name}. Klick auf die Leiste, sag dein Weckwort oder drück dein Anruf-Kürzel, dann sprich einfach. Die Welle zeigt, wer gerade redet.","new_chat": "Lieber tippen? Hier startest du einen neuen Chat, als Text oder mit Stimme. Jedes Gespräch landet unter Letzte Chats.",diff --git a/jarvis/ui/web/frontend/src/i18n/locales/onboarding/en.json b/jarvis/ui/web/frontend/src/i18n/locales/onboarding/en.jsonindex 3ed2a8210a..3cdb994369 100644--- a/jarvis/ui/web/frontend/src/i18n/locales/onboarding/en.json+++ b/jarvis/ui/web/frontend/src/i18n/locales/onboarding/en.json@@ -36,6 +36,14 @@"security": "Keys go into your system's keychain and only ever to the provider you picked.","later": "I'll add a key later"},+ "subscriptions": {+ "title": "Connect a subscription for your agents",+ "lede": "This is the Agents tab. Sign in with a subscription you already pay for. We recommend Claude (Pro or Max) or ChatGPT (Codex). Click Connect on its row; your browser opens once.",+ "waiting": "No subscription connected yet…",+ "connected": "Connected: {names}.",+ "why": "A subscription is a flat monthly price, so your agents' bigger jobs do not bill your API key per call.",+ "later": "I'll connect one later"+ },"permissions": {"title": "Allow access on this Mac","lede": "These are the Mac permissions. Allow the ones you want; each row updates by itself.",@@ -45,13 +53,16 @@"title": "Choose your wake word","lede": "Type your word after \"Hey\" here and save it. The word also becomes the assistant's name. No wake word? The Call shortcut works anytime.","on": "\"{phrase}\" is on. Say it anytime.",- "off": "No wake word yet. The Call shortcut works meanwhile."+ "off": "No wake word yet. The Call shortcut works meanwhile.",+ "later": "Skip, I'll use the Call shortcut"},"ready": {"title": "All set","lede": "The app restarts once to switch everything on. Then a short tour shows you around.","row_brain": "Brain",+ "row_agents": "Agents","row_voice": "Activation",+ "no_subscription": "No subscription","no_key": "No key yet","shortcut": "Call shortcut","autostart": "Start at login",@@ -69,9 +80,9 @@"finish": "Finish","skip": "Skip tour","step_of": "{current} of {total}",- "replay_title": "App tour",- "replay_body": "A short walk through the app with the spotlight, the same one you saw after setup.",- "replay": "Replay tour",+ "replay_title": "Setup and app tour",+ "replay_body": "Walks you through setup again (API keys, agent subscriptions, wake word), then the short tour of the app. Nothing restarts.",+ "replay": "Replay","steps": {"voice": "This is how you talk to {name}. Click the bar, say your wake word or press your Call keys, then just speak. The wave shows who is talking.","new_chat": "Rather type? Start a new chat here, as text or voice. Every conversation lands under Recent chats.",diff --git a/jarvis/ui/web/frontend/src/i18n/locales/onboarding/es.json b/jarvis/ui/web/frontend/src/i18n/locales/onboarding/es.jsonindex bdf72b4abe..0e3cca9126 100644--- a/jarvis/ui/web/frontend/src/i18n/locales/onboarding/es.json+++ b/jarvis/ui/web/frontend/src/i18n/locales/onboarding/es.json@@ -36,6 +36,14 @@"security": "Las claves se guardan en el llavero de tu sistema y solo van al proveedor que elegiste.","later": "Añadiré una clave más tarde"},+ "subscriptions": {+ "title": "Conecta una suscripción para tus agentes",+ "lede": "Esta es la pestaña Agentes. Inicia sesión con una suscripción que ya pagas. Te recomendamos Claude (Pro o Max) o ChatGPT (Codex). Pulsa Connect en su fila; tu navegador se abre una vez.",+ "waiting": "Aún no hay ninguna suscripción conectada…",+ "connected": "Conectado: {names}.",+ "why": "Una suscripción tiene un precio mensual fijo, así las tareas grandes de tus agentes no se cobran por llamada a tu clave de API.",+ "later": "Conectaré una más tarde"+ },"permissions": {"title": "Permitir acceso en este Mac","lede": "Estos son los permisos del Mac. Permite los que quieras; cada fila se actualiza sola.",@@ -45,13 +53,16 @@"title": "Elige tu palabra de activación","lede": "Escribe aquí tu palabra después de «Hey» y guárdala. La palabra también será el nombre de tu asistente. ¿Sin palabra? El atajo de llamada funciona siempre.","on": "«{phrase}» está activada. Dila cuando quieras.",- "off": "Aún no hay palabra de activación. Mientras tanto funciona el atajo de llamada."+ "off": "Aún no hay palabra de activación. Mientras tanto funciona el atajo de llamada.",+ "later": "Omitir, usaré el atajo de llamada"},"ready": {"title": "Todo listo","lede": "La aplicación se reinicia una vez para activarlo todo. Después, una breve visita te enseña la aplicación.","row_brain": "Cerebro",+ "row_agents": "Agentes","row_voice": "Activación",+ "no_subscription": "Sin suscripción","no_key": "Sin clave todavía","shortcut": "Atajo de llamada","autostart": "Iniciar al entrar en la sesión",@@ -69,9 +80,9 @@"finish": "Terminar","skip": "Saltar visita","step_of": "{current} de {total}",- "replay_title": "Visita guiada",- "replay_body": "Un recorrido breve por la aplicación con el foco, el mismo que viste tras la configuración.",- "replay": "Repetir visita",+ "replay_title": "Configuración y visita guiada",+ "replay_body": "Te guía de nuevo por la configuración (claves de API, suscripciones de agentes, palabra de activación) y luego por la visita breve de la aplicación. Nada se reinicia.",+ "replay": "Repetir","steps": {"voice": "Así hablas con {name}. Haz clic en la barra, di tu palabra de activación o pulsa tu atajo de llamada, y habla. La onda muestra quién está hablando.","new_chat": "¿Prefieres escribir? Empieza aquí un chat nuevo, por texto o por voz. Cada conversación queda en Chats recientes.",diff --git a/jarvis/ui/web/frontend/src/lib/apiKeysTab.ts b/jarvis/ui/web/frontend/src/lib/apiKeysTab.tsnew file mode 100644index 0000000000..4ba97c2bae--- /dev/null+++ b/jarvis/ui/web/frontend/src/lib/apiKeysTab.ts@@ -0,0 +1,28 @@+/**+ * Lets another part of the app open the API Keys page on one tab — the+ * first-run guide uses it to land on the Agents tab for subscriptions.+ *+ * The request is remembered, not just announced: the page loads lazily, so+ * it may mount after the event fired. It stays in force until the user picks+ * a tab themselves or the requester clears it, so a later engine-mode sync+ * of the page does not yank it back to the first tab.+ */+export const APIKEYS_TAB_EVENT = "jarvis:apikeys-tab";++let requested: string | null = null;++/** Ask the API Keys page to show `tab`; `null` means its default tab. */+export function requestApiKeysTab(tab: string | null): void {+ requested = tab;+ window.dispatchEvent(new CustomEvent<string | null>(APIKEYS_TAB_EVENT, { detail: tab }));+}++/** The tab another part of the app asked for, if any. */+export function requestedApiKeysTab(): string | null {+ return requested;+}++/** Forget a request without moving the page (the user chose a tab). */+export function clearApiKeysTabRequest(): void {+ requested = null;+}diff --git a/jarvis/ui/web/frontend/src/views/ApiKeysView.tsx b/jarvis/ui/web/frontend/src/views/ApiKeysView.tsxindex 6ebbb478da..067a95254d 100644--- a/jarvis/ui/web/frontend/src/views/ApiKeysView.tsx+++ b/jarvis/ui/web/frontend/src/views/ApiKeysView.tsx@@ -37,6 +37,11 @@ import {} from "@/hooks/useProviders";import { useVoiceMode } from "@/hooks/useVoiceMode";import { useLocalMode } from "@/lib/localMode";+import {+ APIKEYS_TAB_EVENT,+ clearApiKeysTabRequest,+ requestedApiKeysTab,+} from "@/lib/apiKeysTab";import { cn } from "@/lib/utils";import { useT } from "@/i18n";@@ -90,10 +95,29 @@ export function ApiKeysView() {// Reset the selected tab to the mode's first tab whenever the mode changes,// so switching Pipeline→Realtime never leaves `active` pointing at a tab// that no longer exists in the new mode (e.g. "tts").+ // A tab another part of the app asked for (the first-run guide) wins over+ // the mode's first tab while it is still in force.+ useEffect(() => {+ const tabs = engineMode === "realtime" ? REALTIME_TABS : PIPELINE_TABS;+ const wanted = requestedApiKeysTab() as CategoryKey | null;+ setActive(wanted && tabs.includes(wanted) ? wanted : tabs[0]);+ }, [engineMode]);+useEffect(() => {- setActive(engineMode === "realtime" ? "realtime" : "brain");+ const onRequest = (event: Event) => {+ const wanted = (event as CustomEvent<string | null>).detail as CategoryKey | null;+ const tabs = engineMode === "realtime" ? REALTIME_TABS : PIPELINE_TABS;+ setActive(wanted && tabs.includes(wanted) ? wanted : tabs[0]);+ };+ window.addEventListener(APIKEYS_TAB_EVENT, onRequest);+ return () => window.removeEventListener(APIKEYS_TAB_EVENT, onRequest);}, [engineMode]);+ const selectTab = (key: CategoryKey) => {+ clearApiKeysTabRequest();+ setActive(key);+ };+// Open the view on the engine that is actually LIVE (once, when the mode// query resolves) — a user whose voice runs on Realtime should not land on// the Pipeline tab set. Later live-mode changes never yank the view.@@ -128,7 +152,7 @@ export function ApiKeysView() {<CategoryTabsactive={active}- onSelect={setActive}+ onSelect={selectTab}health={health}tabs={modeTabs}/>diff --git a/jarvis/ui/web/frontend/src/views/settings/AppSettingsGroup.tsx b/jarvis/ui/web/frontend/src/views/settings/AppSettingsGroup.tsxindex f02074aafd..36a54b4c03 100644--- a/jarvis/ui/web/frontend/src/views/settings/AppSettingsGroup.tsx+++ b/jarvis/ui/web/frontend/src/views/settings/AppSettingsGroup.tsx@@ -1,6 +1,6 @@import { useState } from "react";import { Compass, Monitor, Moon, Power, Sun, Zap } from "lucide-react";-import { TOUR_START_EVENT } from "@/components/onboarding/tourEvents";+import { SETUP_REPLAY_EVENT } from "@/components/onboarding/tourEvents";import { Switch } from "@/components/ui/switch";import { useAutostart } from "@/hooks/useAutostart";import { useTheme, type ThemePreference } from "@/hooks/useTheme";@@ -53,7 +53,7 @@ function TourRow() {<h4 className="font-medium">{t("app_tour.replay_title")}</h4><buttontype="button"- onClick={() => window.dispatchEvent(new CustomEvent(TOUR_START_EVENT))}+ onClick={() => window.dispatchEvent(new CustomEvent(SETUP_REPLAY_EVENT))}data-testid="settings-replay-tour"className="inline-flex items-center rounded-md border border-border bg-background px-2.5 py-1.5 text-xs font-medium text-foreground transition-colors hover:bg-secondary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring">diff --git a/tests/unit/setup/test_onboarding_meta.py b/tests/unit/setup/test_onboarding_meta.pyindex b232d05f2a..e3e18c42cc 100644--- a/tests/unit/setup/test_onboarding_meta.py+++ b/tests/unit/setup/test_onboarding_meta.py@@ -4,8 +4,9 @@ from jarvis.setup import onboarding_meta as mdef test_meta_constants():assert m.CURRENT_TERMS_VERSION == "1.0"# Setup runs inside the real app (2026-09-30): consent, one key on the API- # Keys page, macOS permissions, the wake word in Settings, then the start.- assert m.ONBOARDING_STEPS == ["welcome", "keys", "permissions", "voice", "ready"]+ # Keys page, a subscription for the agents on its Agents tab (2026-10-01),+ # macOS permissions, the wake word in Settings, then the start.+ assert m.ONBOARDING_STEPS == ["welcome", "keys", "subscriptions", "permissions", "voice", "ready"]# Restart batching (2026-07-18): permissions + voice sit LAST before the# final step so the single unconditional completion restart covers both.assert m.ONBOARDING_STEPS.index("permissions") < m.ONBOARDING_STEPS.index("voice")