Skip to content

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.

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.py
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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; o
const 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}
+ />
<ReviewRow
label={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.ts
index 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.ts
index 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.ts
index 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.json
index 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.json
index 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.json
index 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.ts
new file mode 100644
index 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.tsx
index 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() {
<CategoryTabs
active={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.tsx
index 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>
<button
type="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.py
index 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 m
def 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")