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): the pet explains Jarvis on a walk through the app, then ten first steps

rubenluetke10-beep2e24877f29db
diff --git a/jarvis/setup/onboarding_meta.py b/jarvis/setup/onboarding_meta.py
index 8de9333313..3d9018dffe 100644
--- a/jarvis/setup/onboarding_meta.py
+++ b/jarvis/setup/onboarding_meta.py
@@ -25,8 +25,12 @@ CURRENT_TERMS_VERSION = "1.0"
# relaunch — and onboarding already ends with one unconditional fresh restart
# (onboarding_routes._schedule_fresh_restart). Permissions precede voice so the
# macOS microphone grant exists before the wake-word group's microphone test.
+# "how" (2026-10-01) is an interactive explainer of what the assistant is and
+# how its parts connect, shown before anything is set up — new users went
+# through setup without understanding the product.
ONBOARDING_STEPS: list[str] = [
"welcome",
+ "how",
"keys",
"subscriptions",
"permissions",
diff --git a/jarvis/ui/web/frontend/src/components/agentchat/AgentComposer.tsx b/jarvis/ui/web/frontend/src/components/agentchat/AgentComposer.tsx
index ce01259c28..ce37a3a7a0 100644
--- a/jarvis/ui/web/frontend/src/components/agentchat/AgentComposer.tsx
+++ b/jarvis/ui/web/frontend/src/components/agentchat/AgentComposer.tsx
@@ -562,6 +562,7 @@ export function AgentComposer({ autoFocus = false }: { autoFocus?: boolean }) {
<div
ref={cardRef}
data-testid="agent-composer"
+ data-tour="chat-composer"
data-dragging={files.dragging ? "true" : undefined}
// The whole card is the drop target, not just the text box: someone
// dragging a screenshot aims at the composer, and a target smaller than
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 7d25b67421..2cd5298c6f 100644
--- a/jarvis/ui/web/frontend/src/components/onboarding/OnboardingGate.test.tsx
+++ b/jarvis/ui/web/frontend/src/components/onboarding/OnboardingGate.test.tsx
@@ -16,11 +16,20 @@ vi.mock("./tour/GuidedTour", () => ({
),
}));
+vi.mock("./firstSteps/FirstStepsGuide", () => ({
+ FirstStepsGuide: ({ onClose }: { onClose: () => void }) => (
+ <button type="button" data-testid="first-steps" onClick={onClose}>
+ first steps
+ </button>
+ ),
+}));
+
import { OnboardingGate } from "./OnboardingGate";
-import { SETUP_REPLAY_EVENT, TOUR_START_EVENT } from "./tourEvents";
+import { FIRST_STEPS_START_EVENT, SETUP_REPLAY_EVENT, TOUR_START_EVENT } from "./tourEvents";
afterEach(() => {
cleanup();
+ window.localStorage.clear();
vi.restoreAllMocks();
vi.unstubAllGlobals();
});
@@ -138,7 +147,7 @@ it("replays the setup on a finished install without completing it", async () =>
}
});
-it("replays setup from the API Keys page on request from Settings", async () => {
+it("replays setup from the explainer on request from Settings", async () => {
stub({ ...base, completed: true, tour_completed: true });
render(<OnboardingGate activeSection="profile" />);
await new Promise((r) => setTimeout(r, 20));
@@ -147,7 +156,7 @@ it("replays setup from the API Keys page on request from Settings", async () =>
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");
+ expect(screen.getByTestId("guide").dataset.start).toBe("how");
});
it("goes from setup straight into the tour and completes when the tour ends", async () => {
@@ -179,3 +188,45 @@ it("never completes onboarding after a replayed setup", async () => {
await new Promise((r) => setTimeout(r, 20));
expect(fetchMock.mock.calls.map((c) => String(c[0]))).not.toContain("/api/onboarding/complete");
});
+
+it("hands the first tour over to the first-steps guide, and keeps it after a reload", async () => {
+ stub({ ...base, completed: true, tour_completed: false });
+ render(<OnboardingGate activeSection="chats" />);
+ const tour = await screen.findByTestId("tour");
+ act(() => tour.click());
+ await waitFor(() => expect(screen.getByTestId("first-steps")).toBeDefined());
+ cleanup();
+ // The completion restart reloads the window: the guide comes back from storage.
+ stub({ ...base, completed: true, tour_completed: true });
+ render(<OnboardingGate activeSection="chats" />);
+ await waitFor(() => expect(screen.getByTestId("first-steps")).toBeDefined());
+});
+
+it("does not bring the first-steps guide back once it was closed", async () => {
+ stub({ ...base, completed: true, tour_completed: false });
+ render(<OnboardingGate activeSection="chats" />);
+ const tour = await screen.findByTestId("tour");
+ act(() => tour.click());
+ const guide = await screen.findByTestId("first-steps");
+ act(() => guide.click());
+ await waitFor(() => expect(screen.queryByTestId("first-steps")).toBeNull());
+ // A later tour replay must not restart a guide the user already met.
+ act(() => {
+ window.dispatchEvent(new CustomEvent(TOUR_START_EVENT));
+ });
+ const again = await screen.findByTestId("tour");
+ act(() => again.click());
+ await new Promise((r) => setTimeout(r, 20));
+ expect(screen.queryByTestId("first-steps")).toBeNull();
+});
+
+it("starts the first-steps guide 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("first-steps")).toBeNull();
+ act(() => {
+ window.dispatchEvent(new CustomEvent(FIRST_STEPS_START_EVENT));
+ });
+ await waitFor(() => expect(screen.getByTestId("first-steps")).toBeDefined());
+});
diff --git a/jarvis/ui/web/frontend/src/components/onboarding/OnboardingGate.tsx b/jarvis/ui/web/frontend/src/components/onboarding/OnboardingGate.tsx
index 9f8c4a6cc8..031bb3b124 100644
--- a/jarvis/ui/web/frontend/src/components/onboarding/OnboardingGate.tsx
+++ b/jarvis/ui/web/frontend/src/components/onboarding/OnboardingGate.tsx
@@ -1,6 +1,7 @@
import { lazy, Suspense, useEffect, useMemo, useState } from "react";
import { useOnboarding } from "@/hooks/useOnboarding";
-import { SETUP_REPLAY_EVENT, TOUR_START_EVENT } from "./tourEvents";
+import { freshState, readFirstSteps, writeFirstSteps, type FirstStepsState } from "./firstSteps/firstSteps";
+import { FIRST_STEPS_START_EVENT, SETUP_REPLAY_EVENT, TOUR_START_EVENT } from "./tourEvents";
/**
* Code-split: a finished install renders this gate as `null` forever, so the
@@ -13,6 +14,9 @@ const SetupTour = lazy(() =>
const GuidedTour = lazy(() =>
import("./tour/GuidedTour").then((m) => ({ default: m.GuidedTour })),
);
+const FirstStepsGuide = lazy(() =>
+ import("./firstSteps/FirstStepsGuide").then((m) => ({ default: m.FirstStepsGuide })),
+);
/** Where the IDE keeps working without app-wide setup — no guide over it. */
const IDE_SECTIONS = ["agentic-ide", "chat-workspace", "agentic-ide-classic"];
@@ -34,11 +38,18 @@ function param(name: string): string | null {
* 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.
+ * from the "how it works" explainer on, then the tour.
+ *
+ * 3. First steps: when the tour ends for the first time, a small guide in
+ * the corner walks ten real things to do with the assistant and explains
+ * each one after it happened. It survives the completion restart
+ * (localStorage) and never blocks the app; `jarvis:first-steps-start`
+ * (Settings) starts it again.
*
* Replay, never destructive: `?onboarding=force` walks the setup on a
* finished install without completing or restarting anything, then hands
- * over to the tour; `?tour=force` opens the tour alone.
+ * over to the tour; `?tour=force` opens the tour alone; `?firststeps=force`
+ * opens the first-steps guide from the start.
*/
export function OnboardingGate({ activeSection }: { activeSection?: string } = {}) {
const onb = useOnboarding();
@@ -54,6 +65,11 @@ export function OnboardingGate({ activeSection }: { activeSection?: string } = {
// completed — and the app restarted once — only when that tour ends.
const [completeAfterTour, setCompleteAfterTour] = useState(false);
const forced = useMemo(() => param("onboarding") === "force", []);
+ const [firstSteps, setFirstSteps] = useState<FirstStepsState | null>(() =>
+ param("firststeps") === "force" ? freshState() : readFirstSteps(),
+ );
+ // Remounts the guide on a restart from Settings.
+ const [firstStepsRun, setFirstStepsRun] = useState(0);
useEffect(() => {
const onChanged = () => {
@@ -70,10 +86,18 @@ export function OnboardingGate({ activeSection }: { activeSection?: string } = {
setTourRequested(false);
setSetupReplay((n) => n + 1);
};
+ const onFirstSteps = () => {
+ const fresh = freshState();
+ writeFirstSteps(fresh);
+ setFirstSteps(fresh);
+ setFirstStepsRun((n) => n + 1);
+ };
+ window.addEventListener(FIRST_STEPS_START_EVENT, onFirstSteps);
window.addEventListener("jarvis:onboarding-changed", onChanged);
window.addEventListener(TOUR_START_EVENT, onTour);
window.addEventListener(SETUP_REPLAY_EVENT, onSetupReplay);
return () => {
+ window.removeEventListener(FIRST_STEPS_START_EVENT, onFirstSteps);
window.removeEventListener("jarvis:onboarding-changed", onChanged);
window.removeEventListener(TOUR_START_EVENT, onTour);
window.removeEventListener(SETUP_REPLAY_EVENT, onSetupReplay);
@@ -94,7 +118,7 @@ export function OnboardingGate({ activeSection }: { activeSection?: string } = {
key={setupReplay}
onb={onb}
preview={asked && onb.state.completed}
- startAt={replaying && onb.state.completed ? "keys" : undefined}
+ startAt={replaying && onb.state.completed ? "how" : undefined}
onFinished={() => {
if (!(asked && onb.state?.completed)) setCompleteAfterTour(true);
setSetupReplay(0);
@@ -117,6 +141,13 @@ export function OnboardingGate({ activeSection }: { activeSection?: string } = {
onDone={() => {
setTourDone(true);
setTourRequested(false);
+ // The first tour hands over to the first-steps guide. Written
+ // before the completion restart, so the guide is there after it.
+ if (readFirstSteps() === null) {
+ const fresh = freshState();
+ writeFirstSteps(fresh);
+ setFirstSteps(fresh);
+ }
void (async () => {
await onb.completeTour();
if (!completeAfterTour) return;
@@ -134,5 +165,13 @@ export function OnboardingGate({ activeSection }: { activeSection?: string } = {
);
}
+ if (firstSteps?.status === "active") {
+ return (
+ <Suspense fallback={null}>
+ <FirstStepsGuide key={firstStepsRun} initial={firstSteps} onClose={() => setFirstSteps(null)} />
+ </Suspense>
+ );
+ }
+
return null;
}
diff --git a/jarvis/ui/web/frontend/src/components/onboarding/firstSteps/FirstStepsGuide.tsx b/jarvis/ui/web/frontend/src/components/onboarding/firstSteps/FirstStepsGuide.tsx
new file mode 100644
index 0000000000..44b0017932
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/components/onboarding/firstSteps/FirstStepsGuide.tsx
@@ -0,0 +1,342 @@
+import { motion, useReducedMotion } from "framer-motion";
+import { Check, ChevronDown, ChevronUp, X } from "lucide-react";
+import { useCallback, useEffect, useRef, useState, type ReactNode } from "react";
+import { FOCUS_RING } from "@/components/agentic/controls";
+import { fill, useLocaleChunk, useT } from "@/i18n";
+import { sendChatMessage } from "@/lib/chat";
+import type { PetState } from "@/lib/petStates";
+import { cn } from "@/lib/utils";
+import { useEventStore } from "@/store/events";
+import { useHomeStore } from "@/store/home";
+import { GuidePetFigure, PetSays } from "../pet/GuidePet";
+import { EASE_OUT, QuietAction } from "../ui";
+import {
+ nextOpenQuest,
+ questDone,
+ QUESTS,
+ writeFirstSteps,
+ type FirstStepsState,
+ type Quest,
+ type QuestId,
+} from "./firstSteps";
+
+/** How the pet looks while it waits for each quest. */
+const PET: Record<QuestId, PetState> = {
+ wake: "listening",
+ ask: "idle",
+ tool: "working",
+ screen: "searching",
+ memory: "thinking",
+ artifact: "working",
+ agent: "working",
+ team: "success",
+ plugin: "searching",
+ ide: "working",
+};
+
+/** How often the guide re-checks the live state for the current quest. */
+const CHECK_MS = 700;
+
+/**
+ * The "first steps" guide: the user's pet in the corner of the real app,
+ * speaking in a bubble — never over the app.
+ *
+ * It walks ten real things to do with the assistant — wake it, ask, let it
+ * use a tool, look at the screen, remember something, make an artifact,
+ * hand a job to an agent, meet the agents, connect an app, open the coding
+ * workspace. Each quest says one concrete example and waits until the app
+ * reports it really happened; then the pet explains what went on behind the
+ * scenes and where to see the result. The app stays fully usable the whole
+ * time: the pet can be tucked into a pill, a quest skipped, or the guide
+ * closed.
+ */
+export function FirstStepsGuide({
+ initial,
+ onClose,
+}: {
+ initial: FirstStepsState;
+ onClose: () => void;
+}) {
+ const t = useT();
+ const ready = useLocaleChunk("onboarding");
+ const reduced = useReducedMotion() ?? false;
+ const [state, setState] = useState<FirstStepsState>(initial);
+ const [sent, setSent] = useState(false);
+ // When the current quest was armed: only what happens after counts.
+ const armedAt = useRef(Date.now());
+
+ const quest = QUESTS.find((q) => q.id === state.current) ?? QUESTS[0];
+ const index = QUESTS.indexOf(quest);
+ const isDone = state.done.includes(quest.id);
+ const finished = state.status === "finished";
+
+ const update = useCallback((next: FirstStepsState) => {
+ setState(next);
+ writeFirstSteps(next);
+ }, []);
+
+ const goTo = useCallback(
+ (id: QuestId) => {
+ armedAt.current = Date.now();
+ setSent(false);
+ update({ ...state, current: id, collapsed: false });
+ },
+ [state, update],
+ );
+
+ // Watch the live app for the current quest.
+ useEffect(() => {
+ if (isDone || finished) return;
+ const check = () => {
+ const s = useEventStore.getState();
+ const hit = questDone(quest, {
+ events: s.events,
+ messages: s.messages,
+ voiceState: s.voiceState,
+ activeSection: s.activeSection,
+ since: armedAt.current,
+ });
+ if (hit) {
+ update({
+ ...state,
+ done: state.done.includes(quest.id) ? state.done : [...state.done, quest.id],
+ skipped: state.skipped.filter((q) => q !== quest.id),
+ });
+ }
+ };
+ check();
+ const timer = window.setInterval(check, CHECK_MS);
+ return () => window.clearInterval(timer);
+ }, [quest, isDone, finished, state, update]);
+
+ const advance = useCallback(
+ (skipping: boolean) => {
+ const base = skipping
+ ? { ...state, skipped: state.skipped.includes(quest.id) ? state.skipped : [...state.skipped, quest.id] }
+ : state;
+ const next = nextOpenQuest(base, quest.id);
+ if (next) {
+ armedAt.current = Date.now();
+ setSent(false);
+ update({ ...base, current: next });
+ } else {
+ update({ ...base, status: "finished" });
+ }
+ },
+ [state, quest.id, update],
+ );
+
+ const tryIt = useCallback(
+ async (q: Quest) => {
+ const nav = useEventStore.getState();
+ if (q.action.kind === "open") {
+ if (nav.activeSection !== q.action.section) nav.setActiveSection(q.action.section);
+ return;
+ }
+ // Voice and messages both happen on the front page's chat.
+ if (nav.activeSection !== "chats") nav.setActiveSection("chats");
+ if (q.action.kind === "voice") {
+ if (useHomeStore.getState().surface !== "voice") useHomeStore.getState().setSurface("voice");
+ return;
+ }
+ if (useHomeStore.getState().surface !== "chat") useHomeStore.getState().setSurface("chat");
+ // The user pressed "send it" for exactly this example: one message, once.
+ const ok = await sendChatMessage(t(`first_steps.quests.${q.id}.prompt`));
+ setSent(ok);
+ },
+ [t],
+ );
+
+ const show = (section: NonNullable<Quest["showSection"]>) => {
+ const nav = useEventStore.getState();
+ if (nav.activeSection !== section) nav.setActiveSection(section);
+ };
+
+ const close = () => {
+ update({ ...state, status: finished ? "finished" : "dismissed" });
+ onClose();
+ };
+
+ if (!ready) return null;
+
+ const doneCount = state.done.length;
+ const progress = fill(t("first_steps.progress"), { done: doneCount, total: QUESTS.length });
+
+ if (state.collapsed && !finished) {
+ return (
+ <div className="fixed bottom-4 right-4 z-[100]" data-testid="first-steps-pill">
+ <button
+ type="button"
+ onClick={() => update({ ...state, collapsed: false })}
+ className={cn(
+ "flex items-center gap-2 rounded-full border border-border bg-popover py-1 pl-1 pr-3 text-sm text-popover-foreground shadow-float transition-colors hover:bg-secondary",
+ FOCUS_RING,
+ )}
+ >
+ <GuidePetFigure state="idle" px={32} />
+ <span className="font-medium">{t("first_steps.title")}</span>
+ <span className="text-xs text-muted-foreground">{progress}</span>
+ <ChevronUp aria-hidden className="h-3.5 w-3.5 text-muted-foreground" />
+ </button>
+ </div>
+ );
+ }
+
+ const line = finished
+ ? fill(t("first_steps.finished.body"), { done: doneCount, total: QUESTS.length })
+ : isDone
+ ? `${t(`first_steps.quests.${quest.id}.explain`)} ${t(`first_steps.quests.${quest.id}.how`)}`
+ : t(`first_steps.quests.${quest.id}.ask`);
+
+ const heading = (
+ <div className="mb-1.5 flex items-center gap-2">
+ <span className="inline-flex items-center gap-1.5 text-sm font-semibold text-foreground" id="first-steps-title">
+ {!finished && isDone && <Check aria-hidden className="h-4 w-4 text-success" />}
+ {finished ? t("first_steps.finished.title") : t(`first_steps.quests.${quest.id}.title`)}
+ </span>
+ <span className="ml-auto text-xs text-muted-foreground">{progress}</span>
+ {!finished && (
+ <IconAction label={t("first_steps.collapse")} onClick={() => update({ ...state, collapsed: true })}>
+ <ChevronDown aria-hidden className="h-4 w-4" />
+ </IconAction>
+ )}
+ <IconAction label={t("first_steps.close")} onClick={close} testId="first-steps-close">
+ <X aria-hidden className="h-4 w-4" />
+ </IconAction>
+ </div>
+ );
+
+ return (
+ <motion.section
+ initial={reduced ? false : { opacity: 0, y: 16 }}
+ animate={{ opacity: 1, y: 0 }}
+ transition={{ duration: 0.28, ease: EASE_OUT }}
+ className="fixed bottom-4 right-4 z-[100] w-[min(460px,calc(100vw-32px))]"
+ aria-labelledby="first-steps-title"
+ data-testid="first-steps"
+ data-quest={finished ? "finished" : quest.id}
+ data-state={finished ? "finished" : isDone ? "done" : "open"}
+ >
+ <PetSays
+ key={`${finished ? "finished" : quest.id}-${isDone}`}
+ text={line}
+ state={finished || isDone ? "success" : PET[quest.id]}
+ heading={heading}
+ px={88}
+ testId="first-steps-say"
+ >
+ {!finished && !isDone && quest.action.kind === "send" && (
+ <p className="mt-2 rounded-lg bg-secondary/70 px-3 py-2 text-sm text-foreground" data-testid="first-steps-prompt">
+ “{t(`first_steps.quests.${quest.id}.prompt`)}”
+ </p>
+ )}
+ {!finished && !isDone && sent && (
+ <p className="mt-2 text-xs text-muted-foreground" role="status">
+ {t("first_steps.waiting")}
+ </p>
+ )}
+ <div className="mt-3 flex items-center gap-3">
+ {finished ? (
+ <SmallAction onClick={close} testId="first-steps-finish">
+ {t("first_steps.finished.close")}
+ </SmallAction>
+ ) : isDone ? (
+ <SmallAction onClick={() => advance(false)} testId="first-steps-next">
+ {nextOpenQuest(state, quest.id) ? t("first_steps.next") : t("first_steps.finish")}
+ </SmallAction>
+ ) : (
+ <SmallAction onClick={() => void tryIt(quest)} disabled={sent} testId="first-steps-try">
+ {t(`first_steps.try.${quest.action.kind}`)}
+ </SmallAction>
+ )}
+ {!finished && isDone && quest.showSection && (
+ <QuietAction onClick={() => show(quest.showSection!)} className="text-xs" testId="first-steps-show">
+ {t(`first_steps.show.${quest.id}`)}
+ </QuietAction>
+ )}
+ {!finished && !isDone && (
+ <QuietAction onClick={() => advance(true)} className="ml-auto text-xs" testId="first-steps-skip">
+ {t("first_steps.skip")}
+ </QuietAction>
+ )}
+ </div>
+ {/* One mark per quest: filled when done. Click to jump. */}
+ <div className="mt-3 flex gap-1" role="tablist" aria-label={t("first_steps.title")}>
+ {QUESTS.map((q, i) => (
+ <button
+ key={q.id}
+ type="button"
+ role="tab"
+ aria-selected={!finished && i === index}
+ aria-label={t(`first_steps.quests.${q.id}.title`)}
+ title={t(`first_steps.quests.${q.id}.title`)}
+ onClick={() => goTo(q.id)}
+ className={cn(
+ "h-1 flex-1 rounded-full transition-colors",
+ state.done.includes(q.id)
+ ? "bg-accent"
+ : state.skipped.includes(q.id)
+ ? "bg-foreground/25"
+ : "bg-border-strong",
+ !finished && i === index && "outline outline-2 outline-offset-1 outline-accent/50",
+ FOCUS_RING,
+ )}
+ />
+ ))}
+ </div>
+ </PetSays>
+ </motion.section>
+ );
+}
+
+function SmallAction({
+ children,
+ onClick,
+ disabled,
+ testId,
+}: {
+ children: ReactNode;
+ onClick: () => void;
+ disabled?: boolean;
+ testId?: string;
+}) {
+ return (
+ <button
+ type="button"
+ onClick={onClick}
+ disabled={disabled}
+ data-testid={testId}
+ className={cn(
+ "h-8 rounded-lg bg-accent px-3.5 text-sm font-medium text-accent-foreground transition-opacity hover:opacity-90 disabled:opacity-50",
+ FOCUS_RING,
+ )}
+ >
+ {children}
+ </button>
+ );
+}
+
+function IconAction({
+ children,
+ label,
+ onClick,
+ testId,
+}: {
+ children: ReactNode;
+ label: string;
+ onClick: () => void;
+ testId?: string;
+}) {
+ return (
+ <button
+ type="button"
+ onClick={onClick}
+ aria-label={label}
+ title={label}
+ data-testid={testId}
+ className={cn("rounded-md p-0.5 text-muted-foreground hover:bg-secondary hover:text-foreground", FOCUS_RING)}
+ >
+ {children}
+ </button>
+ );
+}
diff --git a/jarvis/ui/web/frontend/src/components/onboarding/firstSteps/firstSteps.test.ts b/jarvis/ui/web/frontend/src/components/onboarding/firstSteps/firstSteps.test.ts
new file mode 100644
index 0000000000..cd8ad07aed
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/components/onboarding/firstSteps/firstSteps.test.ts
@@ -0,0 +1,60 @@
+import { afterEach, describe, expect, it } from "vitest";
+import type { EventItem } from "@/store/events";
+import { freshState, nextOpenQuest, questDone, QUESTS, readFirstSteps, writeFirstSteps, type DetectInput, type QuestId } from "./firstSteps";
+
+const quest = (id: QuestId) => QUESTS.find((q) => q.id === id)!;
+
+function input(over: Partial<DetectInput> = {}): DetectInput {
+ return { events: [], messages: [], voiceState: "idle", activeSection: "chats", since: 1_000, ...over };
+}
+
+const ev = (name: string, ts: number, payload?: unknown): EventItem => ({ id: `${name}-${ts}`, name, ts, payload });
+
+afterEach(() => window.localStorage.clear());
+
+describe("first steps", () => {
+ it("has ten quests, each with a way to try it", () => {
+ expect(QUESTS).toHaveLength(10);
+ expect(new Set(QUESTS.map((q) => q.id)).size).toBe(10);
+ });
+
+ it("counts only what happened after the quest was armed", () => {
+ const old = input({ events: [ev("ToolCallStarted", 500)] });
+ expect(questDone(quest("tool"), old)).toBe(false);
+ const fresh = input({ events: [ev("ToolCallStarted", 1_500)] });
+ expect(questDone(quest("tool"), fresh)).toBe(true);
+ });
+
+ it("needs the right tool, not just any tool", () => {
+ const other = input({ events: [ev("ToolCallStarted", 2_000, { tool: "navigate" })] });
+ expect(questDone(quest("screen"), other)).toBe(false);
+ const screen = input({ events: [ev("ToolCallStarted", 2_000, { tool: "screen-snapshot" })] });
+ expect(questDone(quest("screen"), screen)).toBe(true);
+ expect(questDone(quest("memory"), input({ events: [ev("WikiPageChanged", 2_000)] }))).toBe(true);
+ expect(questDone(quest("agent"), input({ events: [ev("JarvisAgentTaskStarted", 2_000)] }))).toBe(true);
+ expect(questDone(quest("artifact"), input({ events: [ev("ToolCallStarted", 2_000, { tool: "create-artifact" })] }))).toBe(true);
+ });
+
+ it("sees a reply, a woken voice loop and a visited section", () => {
+ const reply = input({ messages: [{ id: "m", role: "assistant", content: "hi", ts: 2_000 }] });
+ expect(questDone(quest("ask"), reply)).toBe(true);
+ expect(questDone(quest("wake"), input({ voiceState: "listening" }))).toBe(true);
+ expect(questDone(quest("wake"), input({ voiceState: "idle" }))).toBe(false);
+ expect(questDone(quest("ide"), input({ activeSection: "agentic-ide" }))).toBe(true);
+ expect(questDone(quest("plugin"), input({ activeSection: "chats" }))).toBe(false);
+ });
+
+ it("moves on to the next quest that is neither done nor skipped", () => {
+ expect(nextOpenQuest({ done: [], skipped: [] }, "wake")).toBe("ask");
+ expect(nextOpenQuest({ done: ["ask"], skipped: ["tool"] }, "wake")).toBe("screen");
+ expect(nextOpenQuest({ done: [], skipped: [] }, "ide")).toBeNull();
+ });
+
+ it("keeps its progress across a reload and ignores a broken record", () => {
+ expect(readFirstSteps()).toBeNull();
+ writeFirstSteps({ ...freshState(), done: ["wake"], current: "ask" });
+ expect(readFirstSteps()).toMatchObject({ status: "active", done: ["wake"], current: "ask" });
+ window.localStorage.setItem("jarvis.firstSteps.v1", "{not json");
+ expect(readFirstSteps()).toBeNull();
+ });
+});
diff --git a/jarvis/ui/web/frontend/src/components/onboarding/firstSteps/firstSteps.ts b/jarvis/ui/web/frontend/src/components/onboarding/firstSteps/firstSteps.ts
new file mode 100644
index 0000000000..ad24bc419e
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/components/onboarding/firstSteps/firstSteps.ts
@@ -0,0 +1,205 @@
+/**
+ * "First steps": ten small, real things a new user does with the assistant
+ * right after setup, as data.
+ *
+ * The explainer in setup says what the assistant is; this guide lets the
+ * user feel it. Each quest gives one concrete thing to say or open, waits
+ * until the app reports that it really happened (a live event, a reply, a
+ * visited section), and then explains what just went on behind the scenes.
+ *
+ * The guide never starts work on its own. "Try it" either navigates, or —
+ * for a quest that IS a message — sends the shown example once, because the
+ * user pressed the button for exactly that.
+ */
+import type { ChatMessage, EventItem, SectionId, VoiceState } from "@/store/events";
+
+export type QuestId =
+ | "wake"
+ | "ask"
+ | "tool"
+ | "screen"
+ | "memory"
+ | "artifact"
+ | "agent"
+ | "team"
+ | "plugin"
+ | "ide";
+
+/** What "Try it" does: send the example, open voice mode, or open a section. */
+export type QuestAction = { kind: "send" } | { kind: "voice" } | { kind: "open"; section: SectionId };
+
+export interface EventRule {
+ names: readonly string[];
+ includes?: readonly string[];
+}
+
+export interface QuestDetect {
+ /**
+ * Backend events (WS `event_name`) that prove the quest happened. A rule
+ * with `includes` also needs one of those words (case-insensitive) in the
+ * event's payload — "a tool ran" is not yet "the screen tool ran".
+ */
+ events?: readonly EventRule[];
+ /** An assistant reply after the quest started counts. */
+ assistantReply?: boolean;
+ /** The voice loop leaving idle counts (the wake word or the voice button). */
+ voiceActive?: boolean;
+ /** Being on this section counts. */
+ section?: SectionId;
+}
+
+export interface Quest {
+ id: QuestId;
+ action: QuestAction;
+ detect: QuestDetect;
+ /** Where the result can be seen, offered after the quest is done. */
+ showSection?: SectionId;
+}
+
+export const QUESTS: readonly Quest[] = [
+ { id: "wake", action: { kind: "voice" }, detect: { voiceActive: true, events: [{ names: ["WakeWordDetected", "VoiceTurnStarted"] }] } },
+ { id: "ask", action: { kind: "send" }, detect: { assistantReply: true, events: [{ names: ["BrainTurnCompleted", "VoiceTurnCompleted"] }] } },
+ { id: "tool", action: { kind: "send" }, detect: { events: [{ names: ["ToolCallStarted", "ActionExecuted", "CliInvoked"] }] } },
+ {
+ id: "screen",
+ action: { kind: "send" },
+ detect: {
+ events: [
+ { names: ["ScreenCaptureCompleted", "ObservationCaptured", "AppshotTaken"] },
+ { names: ["ToolCallStarted"], includes: ["screen", "appshot", "snapshot"] },
+ ],
+ },
+ },
+ {
+ id: "memory",
+ action: { kind: "send" },
+ detect: {
+ events: [
+ { names: ["WikiPageChanged"] },
+ { names: ["ToolCallStarted"], includes: ["wiki", "profile", "memory", "remember"] },
+ ],
+ },
+ showSection: "memory",
+ },
+ {
+ id: "artifact",
+ action: { kind: "send" },
+ detect: { events: [{ names: ["ToolCallStarted", "JarvisAgentTaskStarted"], includes: ["artifact"] }] },
+ showSection: "visualization",
+ },
+ {
+ id: "agent",
+ action: { kind: "send" },
+ detect: {
+ events: [
+ { names: ["JarvisAgentTaskStarted"] },
+ { names: ["ToolCallStarted"], includes: ["spawn-worker", "delegate"] },
+ ],
+ },
+ showSection: "agents",
+ },
+ { id: "team", action: { kind: "open", section: "agents" }, detect: { section: "agents" } },
+ { id: "plugin", action: { kind: "open", section: "plugins" }, detect: { section: "plugins" } },
+ { id: "ide", action: { kind: "open", section: "agentic-ide" }, detect: { section: "agentic-ide" } },
+];
+
+export interface DetectInput {
+ /** Newest first, as the event store keeps them. */
+ events: readonly EventItem[];
+ messages: readonly ChatMessage[];
+ voiceState: VoiceState;
+ activeSection: SectionId;
+ /** Wall-clock ms the quest was armed; nothing older counts. */
+ since: number;
+}
+
+function payloadText(payload: unknown): string {
+ if (payload === undefined || payload === null) return "";
+ try {
+ return JSON.stringify(payload).toLowerCase();
+ } catch {
+ // A payload that cannot be serialised simply never matches a keyword.
+ return "";
+ }
+}
+
+/** True when the app shows the quest really happened after `since`. */
+export function questDone(quest: Quest, input: DetectInput): boolean {
+ const d = quest.detect;
+ if (d.section && input.activeSection === d.section) return true;
+ if (d.voiceActive && input.voiceState !== "idle" && input.voiceState !== "connecting") return true;
+ if (d.assistantReply && input.messages.some((m) => m.role === "assistant" && m.ts >= input.since)) return true;
+ if (d.events) {
+ for (const e of input.events) {
+ if (e.ts < input.since) break; // newest first: everything after is older
+ for (const rule of d.events) {
+ if (!rule.names.includes(e.name)) continue;
+ if (!rule.includes) return true;
+ const text = payloadText(e.payload);
+ if (rule.includes.some((w) => text.includes(w.toLowerCase()))) return true;
+ }
+ }
+ }
+ return false;
+}
+
+/* ---------------------------------------------------------------- storage */
+
+export type FirstStepsStatus = "active" | "dismissed" | "finished";
+
+export interface FirstStepsState {
+ status: FirstStepsStatus;
+ /** Quests the app saw happen. */
+ done: QuestId[];
+ /** Quests the user skipped. */
+ skipped: QuestId[];
+ current: QuestId;
+ collapsed: boolean;
+}
+
+const STORAGE_KEY = "jarvis.firstSteps.v1";
+
+export function freshState(): FirstStepsState {
+ return { status: "active", done: [], skipped: [], current: QUESTS[0].id, collapsed: false };
+}
+
+function isQuestId(value: unknown): value is QuestId {
+ return QUESTS.some((q) => q.id === value);
+}
+
+export function readFirstSteps(): FirstStepsState | null {
+ try {
+ const raw = window.localStorage.getItem(STORAGE_KEY);
+ if (!raw) return null;
+ const data = JSON.parse(raw) as Partial<FirstStepsState>;
+ if (data.status !== "active" && data.status !== "dismissed" && data.status !== "finished") return null;
+ return {
+ status: data.status,
+ done: Array.isArray(data.done) ? data.done.filter(isQuestId) : [],
+ skipped: Array.isArray(data.skipped) ? data.skipped.filter(isQuestId) : [],
+ current: isQuestId(data.current) ? data.current : QUESTS[0].id,
+ collapsed: data.collapsed === true,
+ };
+ } catch {
+ // Blocked or corrupted storage: the guide simply does not resume.
+ return null;
+ }
+}
+
+export function writeFirstSteps(state: FirstStepsState): void {
+ try {
+ window.localStorage.setItem(STORAGE_KEY, JSON.stringify(state));
+ } catch {
+ // Storage may be blocked; the guide then lives for this window only.
+ }
+}
+
+/** The quest after `id` that is neither done nor skipped, or null at the end. */
+export function nextOpenQuest(state: Pick<FirstStepsState, "done" | "skipped">, id: QuestId): QuestId | null {
+ const start = QUESTS.findIndex((q) => q.id === id);
+ for (let i = start + 1; i < QUESTS.length; i++) {
+ const q = QUESTS[i].id;
+ if (!state.done.includes(q) && !state.skipped.includes(q)) return q;
+ }
+ return null;
+}
diff --git a/jarvis/ui/web/frontend/src/components/onboarding/pet/GuidePet.tsx b/jarvis/ui/web/frontend/src/components/onboarding/pet/GuidePet.tsx
new file mode 100644
index 0000000000..f85b59f975
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/components/onboarding/pet/GuidePet.tsx
@@ -0,0 +1,155 @@
+/**
+ * The pet that guides a new user: the user's own desktop pet (Settings → My
+ * Pets), drawn from its sprite sheet, speaking in a bubble.
+ *
+ * Used by every guide surface — the "how it works" walk, the setup steps,
+ * the app tour and the first-steps guide — so one character explains the
+ * whole first run. While a line is being "said" the text types itself out
+ * and the pet plays its talking row; then it settles into the beat's own
+ * state (thinking, working, success …). A click on the bubble finishes the
+ * line at once; reduced motion shows it whole.
+ *
+ * The pet comes from `/api/pets` (read once per window). With no pet chosen
+ * the built-in default stands in; without the endpoint (an older backend,
+ * a test) the Gigi mascot does.
+ */
+import { useReducedMotion } from "framer-motion";
+import { useEffect, useState, type ReactNode } from "react";
+import { MascotGigi } from "@/components/MascotGigi";
+import { PetSprite } from "@/components/pets/PetSprite";
+import { NO_PET_ID, type PetState } from "@/lib/petStates";
+import type { Pet } from "@/lib/petsApi";
+import { cn } from "@/lib/utils";
+
+/** The pet shown when none is chosen. */
+const DEFAULT_PET_ID = "gigi";
+/** Typing speed of a line, ms per character. */
+const TYPE_MS = 18;
+
+let cached: Promise<Pet | null> | null = null;
+
+function loadGuidePet(): Promise<Pet | null> {
+ cached ??= (async () => {
+ try {
+ const res = await fetch("/api/pets");
+ if (!res.ok) return null;
+ const data = (await res.json()) as { active?: string; pets?: Pet[] };
+ const pets = Array.isArray(data.pets) ? data.pets : [];
+ const id = data.active && data.active !== NO_PET_ID ? data.active : DEFAULT_PET_ID;
+ return pets.find((p) => p.id === id) ?? pets.find((p) => p.id === DEFAULT_PET_ID) ?? pets[0] ?? null;
+ } catch {
+ // No pets endpoint: the mascot stands in.
+ return null;
+ }
+ })();
+ return cached;
+}
+
+/** The user's pet, or null while loading / when there is none. */
+export function useGuidePet(): Pet | null {
+ const [pet, setPet] = useState<Pet | null>(null);
+ useEffect(() => {
+ let cancelled = false;
+ void loadGuidePet().then((p) => {
+ if (!cancelled) setPet(p);
+ });
+ return () => {
+ cancelled = true;
+ };
+ }, []);
+ return pet;
+}
+
+/** Test seam: forget the cached pet. */
+export function _resetGuidePetForTests(): void {
+ cached = null;
+}
+
+/** Reveals `text` character by character; `done` once it is all there. */
+export function useTypedText(text: string): { shown: string; done: boolean; finish: () => void } {
+ const reduced = useReducedMotion() ?? false;
+ const [count, setCount] = useState(reduced ? text.length : 0);
+ useEffect(() => {
+ if (reduced) {
+ setCount(text.length);
+ return;
+ }
+ setCount(0);
+ let n = 0;
+ const timer = window.setInterval(() => {
+ n += 2;
+ setCount(Math.min(n, text.length));
+ if (n >= text.length) window.clearInterval(timer);
+ }, TYPE_MS * 2);
+ return () => window.clearInterval(timer);
+ }, [text, reduced]);
+ return { shown: text.slice(0, count), done: count >= text.length, finish: () => setCount(text.length) };
+}
+
+/** The pet itself at `px` size, or the mascot when there is no pet. */
+export function GuidePetFigure({ state, px = 96, className }: { state: PetState; px?: number; className?: string }) {
+ const pet = useGuidePet();
+ if (!pet) {
+ return (
+ <div className={cn("flex shrink-0 items-end justify-center", className)} style={{ width: px, height: px }}>
+ <MascotGigi size={Math.round(px * 0.7)} reactToVoice={false} enableComments={false} />
+ </div>
+ );
+ }
+ return (
+ <PetSprite
+ pet={pet}
+ state={state}
+ scale={Math.max(1, Math.floor(px / pet.frame_size))}
+ label={pet.name}
+ className={className}
+ />
+ );
+}
+
+/**
+ * The pet next to a speech bubble saying `text`. `children` (the actions)
+ * appear under the line once it is fully typed, so a button never jumps.
+ */
+export function PetSays({
+ text,
+ state = "idle",
+ heading,
+ children,
+ px = 96,
+ testId,
+}: {
+ text: string;
+ state?: PetState;
+ heading?: ReactNode;
+ children?: ReactNode;
+ px?: number;
+ testId?: string;
+}) {
+ const { shown, done, finish } = useTypedText(text);
+ return (
+ <div className="flex items-end gap-2" data-testid={testId}>
+ <GuidePetFigure state={done ? state : "talking"} px={px} className="-mb-1" />
+ <div
+ className="relative min-w-0 flex-1 rounded-2xl rounded-bl-md border border-border bg-popover px-4 py-3 text-popover-foreground shadow-float"
+ onClick={done ? undefined : finish}
+ >
+ {/* The bubble's tail, pointing at the pet. */}
+ <span
+ aria-hidden
+ className="absolute -left-[7px] bottom-3 h-3 w-3 rotate-45 border-b border-l border-border bg-popover"
+ />
+ {heading}
+ {/* The full line is laid out invisibly underneath, so the bubble
+ has its final size from the first letter on. */}
+ <p className="relative text-[15px] leading-relaxed text-foreground">
+ <span aria-hidden className="invisible">{text}</span>
+ <span className="absolute inset-0" aria-live="polite" data-testid={testId ? `${testId}-text` : undefined}>
+ {shown}
+ </span>
+ </p>
+ {children && <div className={cn("transition-opacity duration-200", done ? "opacity-100" : "pointer-events-none opacity-0")}>{children}</div>}
+ </div>
+ </div>
+ );
+}
diff --git a/jarvis/ui/web/frontend/src/components/onboarding/setup/HowWalk.tsx b/jarvis/ui/web/frontend/src/components/onboarding/setup/HowWalk.tsx
new file mode 100644
index 0000000000..aa392c697f
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/components/onboarding/setup/HowWalk.tsx
@@ -0,0 +1,138 @@
+/**
+ * "How it works": the first-run explanation of what the assistant is, told
+ * by the user's pet while it walks the REAL app.
+ *
+ * New users went through setup without understanding the product. Before
+ * anything is set up, the window dims and the pet moves from place to place
+ * in the actual interface — the composer, the sidebar entries for tools,
+ * agents, the coding workspace and Artifacts — and says in a speech bubble
+ * how each part connects to the one assistant the user talks to. Lines with
+ * no single place (memory, safety, the summary) are said from the middle.
+ *
+ * Purely explanatory: it only navigates, never presses or writes anything.
+ */
+import { ArrowLeft } from "lucide-react";
+import { useCallback, useEffect, useState } from "react";
+import { FOCUS_RING } from "@/components/agentic/controls";
+import { fill, useT } from "@/i18n";
+import type { PetState } from "@/lib/petStates";
+import { cn } from "@/lib/utils";
+import type { SectionId } from "@/store/events";
+import { useEventStore } from "@/store/events";
+import { useHomeStore } from "@/store/home";
+import { PetSays, useGuidePet } from "../pet/GuidePet";
+import { Spotlight } from "../tour/Spotlight";
+import type { TourPlacement } from "../tour/tourSteps";
+import { QuietAction } from "../ui";
+import { useAnchorRect } from "./useAnchorRect";
+
+export interface HowBeat {
+ /** Also the i18n key: `first_run.how.beats.<id>`. */
+ id: string;
+ /** The real element the pet stands next to; omitted = said from the middle. */
+ anchor?: string;
+ /** Where the app goes first, so the anchor is on screen. */
+ section?: SectionId;
+ placement: TourPlacement;
+ /** How the pet looks once the line is said. */
+ pet: PetState;
+}
+
+export const HOW_BEATS: readonly HowBeat[] = [
+ { id: "hello", placement: "inside", pet: "success" },
+ { id: "talk", anchor: "chat-composer", section: "chats", placement: "above", pet: "listening" },
+ { id: "brain", anchor: "settings", placement: "right", pet: "thinking" },
+ { id: "tools", anchor: "nav-plugins", placement: "right", pet: "working" },
+ { id: "agents", anchor: "nav-agents", placement: "right", pet: "working" },
+ { id: "ide", anchor: "nav-agentic-ide", placement: "right", pet: "searching" },
+ { id: "results", anchor: "nav-visualization", placement: "right", pet: "success" },
+ { id: "memory", placement: "inside", pet: "thinking" },
+ { id: "safety", placement: "inside", pet: "idle" },
+ { id: "done", placement: "inside", pet: "success" },
+];
+
+const BUBBLE_W = 500;
+
+export function HowWalk({ onDone }: { onDone: () => void }) {
+ const t = useT();
+ const pet = useGuidePet();
+ const [index, setIndex] = useState(0);
+ const beat = HOW_BEATS[index];
+ const last = index === HOW_BEATS.length - 1;
+
+ // Bring the beat's place on screen first: the composer lives on the chat.
+ useEffect(() => {
+ if (!beat.section) return;
+ const nav = useEventStore.getState();
+ if (nav.activeSection !== beat.section) nav.setActiveSection(beat.section);
+ if (beat.anchor === "chat-composer" && useHomeStore.getState().surface !== "chat") {
+ useHomeStore.getState().setSurface("chat");
+ }
+ }, [beat]);
+
+ const rect = useAnchorRect(beat.anchor, false, beat.id);
+
+ const next = useCallback(() => {
+ if (last) onDone();
+ else setIndex((i) => i + 1);
+ }, [last, onDone]);
+
+ // Arrow keys move through the walk.
+ useEffect(() => {
+ const onKey = (event: KeyboardEvent) => {
+ if (event.key === "ArrowRight") next();
+ else if (event.key === "ArrowLeft") setIndex((i) => Math.max(0, i - 1));
+ };
+ window.addEventListener("keydown", onKey);
+ return () => window.removeEventListener("keydown", onKey);
+ }, [next]);
+
+ const text = fill(t(`first_run.how.beats.${beat.id}`), { pet: pet?.name ?? "Gigi" });
+
+ return (
+ <Spotlight rect={rect} placement={beat.placement} blocking cardWidth={BUBBLE_W}>
+ <div
+ role="dialog"
+ aria-modal="true"
+ aria-label={t("first_run.how.title")}
+ data-testid="setup-card"
+ data-step="how"
+ data-beat={beat.id}
+ >
+ <PetSays key={beat.id} text={text} state={beat.pet} testId="how-say">
+ <div className="mt-3 flex items-center gap-3">
+ <button
+ type="button"
+ onClick={next}
+ data-testid="how-next"
+ className={cn(
+ "h-8 rounded-lg bg-accent px-3.5 text-sm font-medium text-accent-foreground transition-opacity hover:opacity-90",
+ FOCUS_RING,
+ )}
+ >
+ {last ? t("first_run.how.finish") : t("first_run.how.next")}
+ </button>
+ {index > 0 && (
+ <QuietAction
+ onClick={() => setIndex((i) => i - 1)}
+ className="inline-flex items-center gap-1 text-xs"
+ testId="how-prev"
+ >
+ <ArrowLeft aria-hidden className="h-3 w-3" />
+ {t("first_run.how.prev")}
+ </QuietAction>
+ )}
+ <span className="ml-auto text-xs text-muted-foreground">
+ {fill(t("first_run.how.beat_of"), { current: index + 1, total: HOW_BEATS.length })}
+ </span>
+ {!last && (
+ <QuietAction onClick={onDone} className="text-xs" testId="how-skip">
+ {t("first_run.how.skip")}
+ </QuietAction>
+ )}
+ </div>
+ </PetSays>
+ </div>
+ </Spotlight>
+ );
+}
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 be87e7fbaf..9b69917fe5 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
@@ -5,6 +5,7 @@ import type { useOnboarding } from "@/hooks/useOnboarding";
import { loadLocaleChunk } from "@/i18n";
import { requestedApiKeysTab } from "@/lib/apiKeysTab";
import { useEventStore } from "@/store/events";
+import { HOW_BEATS } from "./HowWalk";
import { SetupTour } from "./SetupTour";
type Onb = ReturnType<typeof useOnboarding>;
@@ -117,6 +118,10 @@ it("starts with a welcome and no consent gate, then opens the API Keys page", as
fireEvent.click(start);
});
expect(onb.acceptTerms).not.toHaveBeenCalled();
+ // First the explainer of what the assistant is, then the API Keys page.
+ await waitFor(() => expect(screen.getByTestId("setup-card").dataset.step).toBe("how"));
+ expect(onb.saveStep).toHaveBeenCalledWith("how", []);
+ fireEvent.click(await screen.findByTestId("how-skip"));
await waitFor(() => expect(screen.getByTestId("setup-card").dataset.step).toBe("keys"));
expect(onb.saveStep).toHaveBeenCalledWith("keys", []);
await waitFor(() => expect(useEventStore.getState().activeSection).toBe("apikeys"));
@@ -220,6 +225,8 @@ it("walks a replay from the start and never writes, completes or restarts", asyn
await act(async () => {
fireEvent.click(screen.getByTestId("onboarding-primary"));
});
+ await waitFor(() => expect(screen.getByTestId("setup-card").dataset.step).toBe("how"));
+ fireEvent.click(await screen.findByTestId("how-skip"));
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"));
@@ -250,3 +257,31 @@ it("starts a replay from Settings at the API Keys page, with no way back to the
await waitFor(() => expect(screen.getByTestId("setup-card").dataset.step).toBe("keys"));
expect(screen.queryByTestId("setup-back")).toBeNull();
});
+
+it("explains the assistant with the pet walking the real app, then goes on to the keys", async () => {
+ const onb = fakeOnb({ ...accepted, current_step: "how" });
+ render(<SetupTour onb={onb} preview={false} onFinished={vi.fn()} />);
+ const card = await screen.findByTestId("setup-card");
+ expect(card.dataset.step).toBe("how");
+ expect(card.dataset.beat).toBe("hello");
+ // The pet says each line in a bubble; the composer beat moves the app home.
+ fireEvent.click(screen.getByTestId("how-next"));
+ expect(screen.getByTestId("setup-card").dataset.beat).toBe("talk");
+ await waitFor(() => expect(useEventStore.getState().activeSection).toBe("chats"));
+ fireEvent.click(screen.getByTestId("how-prev"));
+ expect(screen.getByTestId("setup-card").dataset.beat).toBe("hello");
+ for (let i = 0; i < HOW_BEATS.length - 1; i++) fireEvent.click(screen.getByTestId("how-next"));
+ expect(screen.getByTestId("setup-card").dataset.beat).toBe("done");
+ // Nothing was written while the pet explained.
+ expect(onb.saveStep).not.toHaveBeenCalled();
+ fireEvent.click(screen.getByTestId("how-next"));
+ await waitFor(() => expect(screen.getByTestId("setup-card").dataset.step).toBe("keys"));
+ expect(onb.saveStep).toHaveBeenCalledWith("keys", []);
+});
+
+it("starts a replay from Settings at the explainer", async () => {
+ const onb = fakeOnb({ ...accepted, completed: true });
+ render(<SetupTour onb={onb} preview startAt="how" onFinished={vi.fn()} />);
+ await waitFor(() => expect(screen.getByTestId("setup-card").dataset.step).toBe("how"));
+ 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 802951d294..33743274d6 100644
--- a/jarvis/ui/web/frontend/src/components/onboarding/setup/SetupTour.tsx
+++ b/jarvis/ui/web/frontend/src/components/onboarding/setup/SetupTour.tsx
@@ -1,6 +1,5 @@
import { ArrowLeft, Lock } from "lucide-react";
import { useCallback, useEffect, useMemo, useState, type ReactNode } from "react";
-import { MascotGigi, type MascotAction } from "@/components/MascotGigi";
import { Switch } from "@/components/ui/switch";
import type { useOnboarding } from "@/hooks/useOnboarding";
import { switchBrainProvider, useProviders } from "@/hooks/useProviders";
@@ -9,6 +8,7 @@ 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 type { PetState } from "@/lib/petStates";
import { cn } from "@/lib/utils";
import { useEventStore } from "@/store/events";
import { planKeysComplete, slotEffective, startableProviders } from "../brainPlans";
@@ -16,17 +16,21 @@ import { ProgressDots } from "../ProgressDots";
import { Spotlight } from "../tour/Spotlight";
import { PrimaryAction, QuietAction, Status } from "../ui";
import { resumeStep, SETUP_STEPS, stepsFor, type SetupStepId } from "./setupSteps";
+import { GuidePetFigure } from "../pet/GuidePet";
+import { HowWalk } from "./HowWalk";
import { useAnchorRect } from "./useAnchorRect";
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",
+/** How the guiding pet looks on each step's card. */
+const PET: Record<SetupStepId, PetState> = {
+ welcome: "success",
+ how: "talking",
+ keys: "searching",
+ subscriptions: "working",
+ voice: "listening",
+ permissions: "idle",
+ ready: "success",
};
const LANGS: UiLanguage[] = ["en", "de", "es"];
@@ -146,6 +150,9 @@ export function SetupTour({
if (!ready) return null;
+ // The explanation is its own walk through the real app, told by the pet.
+ if (stepId === "how") return <HowWalk onDone={() => { cheer(); next(); }} />;
+
const footer = (
<div className="mt-4 grid grid-cols-[1fr_auto_1fr] items-center gap-2">
<div>
@@ -173,12 +180,12 @@ export function SetupTour({
role="dialog"
aria-modal="true"
aria-labelledby="setup-title"
- className="rounded-2xl border border-border bg-popover p-5 text-popover-foreground shadow-float"
+ className="max-h-[calc(100vh-24px)] overflow-y-auto rounded-2xl border border-border bg-popover p-5 text-popover-foreground shadow-float"
data-testid="setup-card"
data-step={stepId}
>
<div className="flex items-start gap-3">
- <MascotGigi size={40} reactToVoice={false} enableComments={false} cue={{ action: MASCOT[stepId], key: cue }} />
+ <GuidePetFigure key={cue} state={PET[stepId]} px={48} />
<div className="min-w-0 flex-1">
<h2 id="setup-title" className="text-base font-semibold tracking-tight text-foreground">
{t(`first_run.${stepId}.title`)}
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 0aa02d5c23..e6644a989d 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
@@ -1,6 +1,7 @@
import { readdirSync, readFileSync, statSync } from "node:fs";
import { join } from "node:path";
import { describe, expect, it } from "vitest";
+import { HOW_BEATS } from "./HowWalk";
import { resumeStep, SETUP_STEP_IDS, SETUP_STEPS, stepsFor } from "./setupSteps";
const SRC = join(__dirname, "..", "..", "..");
@@ -51,6 +52,20 @@ describe("setup steps", () => {
}
});
+ it("let the pet's walk point only at anchors the app actually sets", () => {
+ const code = sources(SRC)
+ .filter((f) => !f.includes(join("components", "onboarding")))
+ .map((f) => readFileSync(f, "utf8"))
+ .join("
+");
+ for (const beat of HOW_BEATS) {
+ if (!beat.anchor) continue;
+ const literal = code.includes(`data-tour="${beat.anchor}"`);
+ const nav = beat.anchor.startsWith("nav-") && code.includes("data-tour={`nav-${item.id}`}");
+ expect(literal || nav, beat.anchor).toBe(true);
+ }
+ });
+
it("open the app's own place for each job", () => {
expect(SETUP_STEPS.keys.section).toBe("apikeys");
expect(SETUP_STEPS.subscriptions.section).toBe("apikeys");
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 272f87c3f5..159b7dc472 100644
--- a/jarvis/ui/web/frontend/src/components/onboarding/setup/setupSteps.ts
+++ b/jarvis/ui/web/frontend/src/components/onboarding/setup/setupSteps.ts
@@ -11,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", "subscriptions", "permissions", "voice", "ready"] as const;
+export const SETUP_STEP_IDS = ["welcome", "how", "keys", "subscriptions", "permissions", "voice", "ready"] as const;
export type SetupStepId = (typeof SETUP_STEP_IDS)[number];
@@ -32,6 +32,8 @@ export interface SetupStep {
export const SETUP_STEPS: Record<SetupStepId, SetupStep> = {
welcome: { id: "welcome", placement: "inside", width: 420 },
+ // The pet's walk through the real app (HowWalk) places itself beat by beat.
+ how: { id: "how", placement: "inside", width: 500 },
keys: { id: "keys", section: "apikeys", anchor: "apikeys-page", placement: "left", width: 320 },
subscriptions: {
id: "subscriptions",
diff --git a/jarvis/ui/web/frontend/src/components/onboarding/tour/GuidedTour.tsx b/jarvis/ui/web/frontend/src/components/onboarding/tour/GuidedTour.tsx
index 5ff732d931..28329143d9 100644
--- a/jarvis/ui/web/frontend/src/components/onboarding/tour/GuidedTour.tsx
+++ b/jarvis/ui/web/frontend/src/components/onboarding/tour/GuidedTour.tsx
@@ -1,11 +1,11 @@
import { useCallback, useEffect, useRef, useState } from "react";
-import { MascotGigi } from "@/components/MascotGigi";
import { fill, useLocaleChunk, useT } from "@/i18n";
import { useEventStore } from "@/store/events";
import { useHomeStore } from "@/store/home";
import type { HomeSurface } from "@/lib/homeSurface";
import { cn } from "@/lib/utils";
import { FOCUS_RING } from "@/components/agentic/controls";
+import { PetSays } from "../pet/GuidePet";
import { QuietAction } from "../ui";
import { Spotlight } from "./Spotlight";
import { nextStepIndex, TOUR_STEPS, type Rect, type TourEffect } from "./tourSteps";
@@ -77,7 +77,6 @@ export function GuidedTour({ onDone }: { onDone: () => void }) {
const ready = useLocaleChunk("onboarding");
const [index, setIndex] = useState(readSavedStep);
const [rect, setRect] = useState<Rect | null>(null);
- const [cue, setCue] = useState(0);
const anchorRef = useRef<HTMLElement | null>(null);
const originalSurface = useRef<HomeSurface>(useHomeStore.getState().surface);
const doneRef = useRef(false);
@@ -119,7 +118,6 @@ export function GuidedTour({ onDone }: { onDone: () => void }) {
}
saveStep(target);
setIndex(target);
- setCue((c) => c + 1);
}, [index, run, finish]);
// Enter the step: move the app if the step asks, then wait for its element.
@@ -216,48 +214,32 @@ export function GuidedTour({ onDone }: { onDone: () => void }) {
const last = nextStepIndex(index) === null;
return (
- <Spotlight rect={rect} placement={step.placement}>
- <div
- role="dialog"
- aria-live="polite"
- aria-label={t("app_tour.label")}
- className="rounded-2xl border border-border bg-popover p-4 text-popover-foreground shadow-float"
- data-testid="tour-card"
- data-step={step.id}
- >
- <div className="flex items-start gap-3">
- <MascotGigi
- size={36}
- reactToVoice={false}
- enableComments={false}
- cue={{ action: step.mascot, key: cue }}
- />
- <p className="min-w-0 flex-1 text-sm leading-relaxed text-foreground" data-testid="tour-text">
- {t(`app_tour.steps.${step.id}`)}
- </p>
- </div>
- <div className="mt-4 flex items-center gap-3">
- <button
- ref={nextButton}
- type="button"
- onClick={advance}
- data-testid="tour-next"
- className={cn(
- "h-8 rounded-lg bg-accent px-3.5 text-sm font-medium text-accent-foreground transition-opacity hover:opacity-90",
- FOCUS_RING,
+ <Spotlight rect={rect} placement={step.placement} cardWidth={460}>
+ <div role="dialog" aria-live="polite" aria-label={t("app_tour.label")} data-testid="tour-card" data-step={step.id}>
+ <PetSays key={step.id} text={t(`app_tour.steps.${step.id}`)} state={step.pet} px={80} testId="tour-text">
+ <div className="mt-3 flex items-center gap-3">
+ <button
+ ref={nextButton}
+ type="button"
+ onClick={advance}
+ data-testid="tour-next"
+ className={cn(
+ "h-8 rounded-lg bg-accent px-3.5 text-sm font-medium text-accent-foreground transition-opacity hover:opacity-90",
+ FOCUS_RING,
+ )}
+ >
+ {last ? t("app_tour.finish") : t("app_tour.next")}
+ </button>
+ <span className="text-xs text-muted-foreground">
+ {fill(t("app_tour.step_of"), { current: index + 1, total: TOUR_STEPS.length })}
+ </span>
+ {!last && (
+ <QuietAction onClick={finish} className="ml-auto text-xs" testId="tour-skip">
+ {t("app_tour.skip")}
+ </QuietAction>
)}
- >
- {last ? t("app_tour.finish") : t("app_tour.next")}
- </button>
- <span className="text-xs text-muted-foreground">
- {fill(t("app_tour.step_of"), { current: index + 1, total: TOUR_STEPS.length })}
- </span>
- {!last && (
- <QuietAction onClick={finish} className="ml-auto text-xs" testId="tour-skip">
- {t("app_tour.skip")}
- </QuietAction>
- )}
- </div>
+ </div>
+ </PetSays>
</div>
</Spotlight>
);
diff --git a/jarvis/ui/web/frontend/src/components/onboarding/tour/tourSteps.ts b/jarvis/ui/web/frontend/src/components/onboarding/tour/tourSteps.ts
index b4c28f42e7..5317a768ec 100644
--- a/jarvis/ui/web/frontend/src/components/onboarding/tour/tourSteps.ts
+++ b/jarvis/ui/web/frontend/src/components/onboarding/tour/tourSteps.ts
@@ -9,7 +9,7 @@
* one, opens a paid call, so the tour points at it and leaves the click to
* the user.
*/
-import type { MascotAction } from "@/components/MascotGigi";
+import type { PetState } from "@/lib/petStates";
/** What a step may do to the app. Every effect is plain navigation. */
export type TourEffect = "home-voice" | "open-agents" | "back-home";
@@ -25,13 +25,16 @@ export interface TourStep {
onExit?: TourEffect;
/** Drop the step when its anchor never shows (e.g. a section this build lacks). */
skipIfMissing?: boolean;
- mascot: MascotAction;
+ /** How the guiding pet looks on this step. */
+ pet: PetState;
}
+// The pet's "how it works" walk in setup already explained tools, agents,
+// the coding workspace and Artifacts; the tour after the restart shows the
+// everyday places around them and does not repeat it.
export const TOUR_STEPS: readonly TourStep[] = [
- { id: "voice", anchor: "voice-bar", placement: "below", onEnter: "home-voice", mascot: "wave" },
- { id: "new_chat", anchor: "new-chat", placement: "right", mascot: "look-right" },
- { id: "agents", anchor: "nav-agents", placement: "right", onExit: "open-agents", mascot: "look-left" },
+ { id: "voice", anchor: "voice-bar", placement: "below", onEnter: "home-voice", pet: "talking" },
+ { id: "new_chat", anchor: "new-chat", placement: "right", pet: "idle" },
{
id: "agents_world",
anchor: "agents-page",
@@ -39,14 +42,11 @@ export const TOUR_STEPS: readonly TourStep[] = [
onEnter: "open-agents",
onExit: "back-home",
skipIfMissing: true,
- mascot: "jump",
+ pet: "working",
},
- { id: "voice_hub", anchor: "nav-dictation", placement: "right", onEnter: "back-home", mascot: "look-right" },
- { id: "artifacts", anchor: "nav-visualization", placement: "right", skipIfMissing: true, mascot: "look-left" },
- { id: "ide", anchor: "nav-agentic-ide", placement: "right", skipIfMissing: true, mascot: "spin" },
- { id: "plugins", anchor: "nav-plugins", placement: "right", skipIfMissing: true, mascot: "look-right" },
- { id: "settings", anchor: "settings", placement: "right", mascot: "look-left" },
- { id: "done", anchor: "voice-bar", placement: "below", onEnter: "home-voice", mascot: "jump" },
+ { id: "voice_hub", anchor: "nav-dictation", placement: "right", onEnter: "back-home", pet: "listening" },
+ { id: "settings", anchor: "settings", placement: "right", pet: "thinking" },
+ { id: "done", anchor: "voice-bar", placement: "below", onEnter: "home-voice", pet: "success" },
];
export function nextStepIndex(index: number): number | null {
diff --git a/jarvis/ui/web/frontend/src/components/onboarding/tourEvents.ts b/jarvis/ui/web/frontend/src/components/onboarding/tourEvents.ts
index 20720635d5..1d9aeb3215 100644
--- a/jarvis/ui/web/frontend/src/components/onboarding/tourEvents.ts
+++ b/jarvis/ui/web/frontend/src/components/onboarding/tourEvents.ts
@@ -13,6 +13,9 @@ export const TOUR_START_EVENT = "jarvis:tour-start";
*/
export const SETUP_REPLAY_EVENT = "jarvis:setup-replay";
+/** Window event that (re)starts the first-steps guide from its first quest. */
+export const FIRST_STEPS_START_EVENT = "jarvis:first-steps-start";
+
/** 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 d529e458aa..47ddb280e4 100644
--- a/jarvis/ui/web/frontend/src/i18n/locales/onboarding/de.json
+++ b/jarvis/ui/web/frontend/src/i18n/locales/onboarding/de.json
@@ -5,13 +5,34 @@
"step_of": "{current} von {total}",
"welcome": {
"title": "Willkommen",
- "lede": "Wir richten deinen Assistenten direkt hier in der App ein: einen API-Schlüssel, ein Abo für deine Agents und dein Weckwort. Danach zeigt dir eine kurze Tour die App.",
+ "lede": "Zuerst ein kurzer Blick darauf, was {name} ist und wie es funktioniert. Danach richten wir es direkt hier in der App ein: einen API-Schlüssel, ein Abo für deine Agents und dein Weckwort.",
"language": "Sprache",
"lang_en": "English",
"lang_de": "Deutsch",
"lang_es": "Español",
"start": "Los geht's"
},
+ "how": {
+ "title": "So funktioniert {name}",
+ "lede": "Dein Pet führt dich durch die App und erklärt, wie {name} funktioniert.",
+ "next": "Weiter",
+ "prev": "Zurück",
+ "skip": "Überspringen",
+ "finish": "Jetzt einrichten",
+ "beat_of": "{current} / {total}",
+ "beats": {
+ "hello": "Hi, ich bin {pet}! Bevor wir etwas einrichten, zeig ich dir, wie {name} funktioniert. Geht schnell, und du siehst dabei die echte App.",
+ "talk": "Hier fängt alles an. Du sprichst mit einem einzigen Assistenten: {name}. Tipp hier oder drück den runden Knopf und sprich einfach. Du wählst nie selbst ein Werkzeug oder Modell; {name} entscheidet, was gebraucht wird.",
+ "brain": "Zum Denken braucht {name} ein Gehirn: ein KI-Modell von OpenAI, Google, Anthropic oder einem anderen Anbieter, oder eins auf deinem eigenen Computer. Ein Schlüssel reicht, den fügen wir gleich zusammen hinzu.",
+ "tools": "Dann braucht {name} Hände. Es kann deinen Computer und Browser selbst bedienen, dazu jede App, die du hier verbindest: Mail, Kalender, Notizen, Smart Home. Wenn du etwas willst, sucht es sich das passende Werkzeug selbst.",
+ "agents": "Große Aufgaben wie eine Recherche, ein Bericht oder eine Webseite gehen an Agents. Das ist das Team von {name}: {name} gibt ihnen die Arbeit, redet weiter mit dir, und ein Prüfer kontrolliert das Ergebnis, bevor es bei dir ankommt.",
+ "ide": "Hier arbeiten Coding-Agents wie Claude Code und Codex, in echten Terminals an deinen eigenen Projekten. Tipp ihnen direkt, oder lass {name} sie per Stimme steuern.",
+ "results": "Was dabei herauskommt, also Seiten, Berichte oder Bilder, landet in Artifacts. Kurze Antworten kommen direkt im Chat oder laut gesprochen zurück.",
+ "memory": "{name} merkt sich auch Dinge. Was du erzählst, landet in seinen Notizen und deinem Profil, gespeichert auf deinem Computer. So musst du dich nie wiederholen.",
+ "safety": "Und du behältst die Kontrolle. Harmloses passiert einfach. Alles, was etwas sendet, löscht oder Geld kostet, wartet zuerst auf dein Ja.",
+ "done": "Das ist die ganze Idee: Du sprichst, {name} denkt nach, nutzt Werkzeuge, holt Agents dazu und bringt dir das Ergebnis. Jetzt geben wir ihm ein Gehirn."
+ }
+ },
"keys": {
"title": "Einen API-Schlüssel eintragen",
"lede": "Dein Assistent braucht einen KI-Schlüssel, um zu denken und zu sprechen; ohne ihn bleiben Chat und Sprache aus. Das ist die Seite API-Keys: Füge einen Schlüssel in eine Anbieter-Karte ein und speichere ihn. Mit OpenAI oder Gemini reicht ein einziger Schlüssel für Live-Sprache.",
@@ -66,19 +87,113 @@
"skip": "Tour überspringen",
"step_of": "{current} von {total}",
"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_body": "Erklärt noch einmal, wie {name} funktioniert, führt dich 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.",
- "agents": "Agenten sind dein Team: Helfer, die größere Aufgaben im Hintergrund übernehmen. Schauen wir rein.",
"agents_world": "Das ist das Verse, deine Agenten bei der Arbeit. Klick einen an, um mit ihm zu chatten oder ihm eine Aufgabe zu geben. Weiter bringt dich zurück.",
"voice_hub": "Unter Stimme findest du Diktat in jede App, deine eigene Wortliste und gesprochene Kürzel.",
- "artifacts": "Alles, was {name} erstellt, von Seiten über Bilder bis zu Berichten, liegt unter Artefakte.",
- "ide": "Die Agentic IDE lässt Coding-Agenten nebeneinander in echten Terminals an deinen Projekten arbeiten.",
- "plugins": "Plugins, Skills und MCP verbinden {name} mit deinen Apps. Das Laden-Symbol unten öffnet den Marketplace.",
"settings": "Hier findest du Einstellungen, API-Schlüssel, Kosten und dein Profil. Die Tour kannst du jederzeit unter Einstellungen → App wiederholen.",
"done": "Das war die Tour. Du bist startklar: Sprich mit {name}, wann immer du willst."
}
+ },
+ "first_steps": {
+ "title": "Erste Schritte",
+ "progress": "{done}/{total}",
+ "collapse": "Minimieren",
+ "close": "Schließen",
+ "quest_of": "Schritt {current} von {total}",
+ "how_label": "So funktioniert's:",
+ "waiting": "Gesendet. Schau in den Chat: {name} ist dran.",
+ "next": "Nächster Schritt",
+ "finish": "Abschließen",
+ "skip": "Diesen überspringen",
+ "try": {
+ "send": "Für mich senden",
+ "voice": "Sprachmodus öffnen",
+ "open": "Hinbringen"
+ },
+ "show": {
+ "memory": "Notizen öffnen",
+ "artifact": "Artifacts öffnen",
+ "agent": "In Agents ansehen"
+ },
+ "replay_title": "Erste Schritte mit {name}",
+ "replay": "Starten",
+ "replay_body": "Zehn kleine, echte Dinge zum Ausprobieren mit {name}: sprechen, Werkzeuge nutzen, sich etwas merken, etwas bauen, an Agents abgeben. Jedes wird erklärt, nachdem es passiert ist.",
+ "finished": {
+ "title": "Du kennst jetzt die Grundlagen!",
+ "body": "Du hast {done} von {total} ersten Schritten geschafft. Ab jetzt sprichst du einfach mit {name}: Es entscheidet selbst, ob es antwortet, ein Werkzeug nutzt oder einen Agent dazuholt.",
+ "close": "Schließen"
+ },
+ "quests": {
+ "wake": {
+ "title": "Weck {name} auf",
+ "ask": "Sag dein Weckwort laut, zum Beispiel „Hey {name}“. Oder öffne den Sprachmodus und drück den runden Knopf in der Chatleiste. Dann frag einfach los.",
+ "explain": "{name} hört zu. Mehr braucht es nicht: aufwecken und reden wie mit einem Menschen.",
+ "how": "Dein Weckwort wird direkt hier auf deinem Computer erkannt. Erst danach geht deine Sprache an das Gehirn, und die Antwort kommt als Stimme zurück."
+ },
+ "ask": {
+ "title": "Stell deine erste Frage",
+ "ask": "Tipp oder sag eine Frage. Probier diese:",
+ "prompt": "Was kannst du für mich tun? Nenn mir drei Beispiele aus meinem Alltag.",
+ "explain": "Das war der einfachste Weg: Deine Worte gingen an das Gehirn, und es hat direkt geantwortet.",
+ "how": "Das Gehirn ist das KI-Modell, das du verbunden hast. Einfache Fragen brauchen keine Werkzeuge, deshalb kommt die Antwort in Sekunden. Jeder Chat wird unter „Letzte Chats“ gespeichert."
+ },
+ "tool": {
+ "title": "Lass es ein Werkzeug benutzen",
+ "ask": "Jetzt bitte um etwas, wofür es seine Hände braucht, nicht nur seinen Kopf:",
+ "prompt": "Öffne wikipedia.org in meinem Browser.",
+ "explain": "Diesmal hat das Gehirn nicht nur geantwortet: Es hat ein Werkzeug benutzt, um an deinem Computer zu handeln.",
+ "how": "Werkzeuge sind die Hände von {name}. Das Gehirn wählt eines, der Sicherheitscheck gibt es frei, und es läuft. Unter jeder Antwort kannst du die Schritte aufklappen und jedes benutzte Werkzeug sehen."
+ },
+ "screen": {
+ "title": "Lass es auf deinen Bildschirm schauen",
+ "ask": "{name} kann deinen Bildschirm sehen, aber nur, wenn du fragst. Probier:",
+ "prompt": "Was ist gerade auf meinem Bildschirm? Beschreib es kurz.",
+ "explain": "{name} hat einmal auf deinen Bildschirm geschaut und ihn beschrieben.",
+ "how": "Ein Blick auf den Bildschirm ist ein einzelnes Foto, nur dann, wenn eine Anfrage es braucht. Es geht wie ein Bild an das Gehirn. Nichts zeichnet deinen Bildschirm im Hintergrund auf."
+ },
+ "memory": {
+ "title": "Bring ihm etwas bei",
+ "ask": "Erzähl {name} etwas, das es sich merken soll:",
+ "prompt": "Merk dir, dass meine Lieblingsfarbe Blau ist und dass ich kurze Antworten mag.",
+ "explain": "{name} hat das in seinem Gedächtnis gespeichert und nutzt es ab jetzt.",
+ "how": "Fakten landen in deinem Wiki und Profil, gespeichert auf deinem Computer. Bevor {name} antwortet, schaut es nach, was es über dich weiß. In den Notizen kannst du alles lesen und bearbeiten."
+ },
+ "artifact": {
+ "title": "Lass es etwas bauen",
+ "ask": "{name} kann fertige Dinge bauen: Seiten, Übersichten, kleine Tools. Sag „Artifact“, um eins anzufordern:",
+ "prompt": "Erstelle ein Artifact: eine einseitige Übersicht über die Planeten unseres Sonnensystems, mit je einem spannenden Fakt.",
+ "explain": "{name} hat angefangen, die Seite zu bauen. Sobald sie fertig ist, erscheint sie in Artifacts.",
+ "how": "Ein Artifact ist eine größere Arbeit, deshalb gibt {name} sie an einen Helfer auf einem starken Modell ab. Der baut eine eigenständige Seite, und Artifacts bewahrt sie auf, damit du sie später wieder öffnen kannst."
+ },
+ "agent": {
+ "title": "Gib einem Agent eine große Aufgabe",
+ "ask": "Für längere Arbeit holt {name} einen Agent dazu. Du kannst weiterreden, während er arbeitet:",
+ "prompt": "Recherchiere die drei besten günstigen Laptops gerade und schreib mir einen kurzen Vergleich.",
+ "explain": "{name} hat die Aufgabe an einen Agent abgegeben. Er arbeitet im Hintergrund; das Ergebnis kommt in deinen Chat.",
+ "how": "{name} bleibt dein einziger Ansprechpartner. Es plant die Aufgabe und startet einen Agent, und ein Prüfer kontrolliert das Ergebnis, bevor es bei dir ankommt. Den Fortschritt siehst du unter Agents."
+ },
+ "team": {
+ "title": "Lern dein Team kennen",
+ "ask": "Agents sind Helfer mit einer eigenen Rolle. Öffne den Bereich Agents, um sie kennenzulernen.",
+ "explain": "Hier wohnen und arbeiten deine Agents.",
+ "how": "Leg einen eigenen Agent an, mit eigener Rolle, eigenem Modell und eigenen Anweisungen, zum Beispiel einen Rechercheur oder eine Texterin. Klick einen Agent an, um mit ihm zu chatten oder ihm einen Auftrag zu geben. {name} kann ihm auch für dich Arbeit geben."
+ },
+ "plugin": {
+ "title": "Verbinde eine App",
+ "ask": "Plugins verbinden {name} mit den Apps, die du nutzt: E-Mail, Kalender, Notizen, Smart Home und mehr.",
+ "explain": "Hier verbindest du deine Apps. Wähl eine, die du täglich nutzt, und klick auf Verbinden; dein Browser öffnet sich einmal zum Anmelden.",
+ "how": "Jede verbundene App wird ein neues Werkzeug für {name}. Danach fragst du einfach, zum Beispiel „Was steht morgen in meinem Kalender?“. Alles, was etwas sendet oder ändert, fragt dich trotzdem vorher."
+ },
+ "ide": {
+ "title": "Lass Agents programmieren",
+ "ask": "Die Agentic IDE lässt Coding-Agents wie Claude Code und Codex in echten Terminals laufen, an deinen eigenen Projekten.",
+ "explain": "Das ist die Agentic IDE. Öffne einen Projektordner und starte in einem Fenster einen Coding-Agent.",
+ "how": "Jedes Fenster ist ein echtes Terminal mit eigenem Agent. Sprich mit ihnen per Tastatur oder per Stimme über {name}. Mehrere können nebeneinander am selben Projekt arbeiten."
+ }
+ }
}
}
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 609758b6b4..27e391cb28 100644
--- a/jarvis/ui/web/frontend/src/i18n/locales/onboarding/en.json
+++ b/jarvis/ui/web/frontend/src/i18n/locales/onboarding/en.json
@@ -5,13 +5,34 @@
"step_of": "{current} of {total}",
"welcome": {
"title": "Welcome",
- "lede": "Let's set up your assistant right here in the app: an API key, a subscription for your agents and your wake word. Then a short tour shows you around.",
+ "lede": "First a short look at what {name} is and how it works. Then we set it up right here in the app: an API key, a subscription for your agents and your wake word.",
"language": "Language",
"lang_en": "English",
"lang_de": "Deutsch",
"lang_es": "Español",
"start": "Let's start"
},
+ "how": {
+ "title": "How {name} works",
+ "lede": "Your pet walks you through the app and explains how {name} works.",
+ "next": "Next",
+ "prev": "Back",
+ "skip": "Skip",
+ "finish": "Let's set it up",
+ "beat_of": "{current} / {total}",
+ "beats": {
+ "hello": "Hi, I'm {pet}! Before we set anything up, let me show you how {name} works. It's quick, and you'll see the real app while I explain.",
+ "talk": "Everything starts here. You talk to one assistant: {name}. Type here, or press the round button and just speak. You never pick a tool or a model yourself; {name} decides what's needed.",
+ "brain": "To think, {name} needs a brain: an AI model from OpenAI, Google, Anthropic or another provider, or one on your own computer. One key is enough, and we'll add it together in a moment.",
+ "tools": "Then {name} needs hands. It can use your computer and browser on its own, plus every app you connect here: mail, calendar, notes, smart home. When you ask for something, it picks the right tool itself.",
+ "agents": "Big jobs like research, a report or a website go to agents. They're {name}'s team: {name} hands them the work and keeps talking with you, and a reviewer checks the result before it reaches you.",
+ "ide": "Coding agents such as Claude Code and Codex work here, in real terminals on your own projects. Type to them directly, or let {name} steer them by voice.",
+ "results": "Whatever comes out, like pages, reports or images, lands in Artifacts. Short answers come straight back in the chat or spoken aloud.",
+ "memory": "{name} also remembers. What you tell it goes into its notes and your profile, stored on your computer, so you never have to repeat yourself.",
+ "safety": "And you stay in control. Harmless things just happen. Anything that sends, deletes or costs money waits for your yes first.",
+ "done": "That's the whole idea: you talk, {name} thinks, uses tools, brings in agents and hands you the result. Now let's give it a brain."
+ }
+ },
"keys": {
"title": "Add one API key",
"lede": "Your assistant needs one AI key to think and talk; without it, chat and voice stay off. This is the API Keys page: paste one key into a provider card and save it. OpenAI or Gemini gives you live voice with a single key.",
@@ -66,19 +87,113 @@
"skip": "Skip tour",
"step_of": "{current} of {total}",
"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_body": "Explains again how {name} works, walks you through setup (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.",
- "agents": "Agents are your team: helpers that take on bigger jobs in the background. Let's look inside.",
"agents_world": "This is the Verse, your agents at work. Click one to chat with it or hand it a job. Next brings you back.",
"voice_hub": "Voice holds dictation into any app, your own word list and spoken shortcuts.",
- "artifacts": "Everything {name} makes, from pages to images to reports, is kept in Artifacts.",
- "ide": "The Agentic IDE runs coding agents side by side in real terminals, on your own projects.",
- "plugins": "Plugins, skills and MCP connect {name} to your apps. The store icon at the bottom opens the Marketplace.",
"settings": "Settings, API keys, costs and your profile live here. You can replay this tour anytime from Settings → App.",
"done": "That's the tour. You're ready: talk to {name} whenever you like."
}
+ },
+ "first_steps": {
+ "title": "First steps",
+ "progress": "{done}/{total}",
+ "collapse": "Minimise",
+ "close": "Close",
+ "quest_of": "Step {current} of {total}",
+ "how_label": "How it works:",
+ "waiting": "Sent. Watch the chat: {name} is on it.",
+ "next": "Next step",
+ "finish": "Finish",
+ "skip": "Skip this one",
+ "try": {
+ "send": "Send it for me",
+ "voice": "Open voice mode",
+ "open": "Take me there"
+ },
+ "show": {
+ "memory": "Open Notes",
+ "artifact": "Open Artifacts",
+ "agent": "Watch in Agents"
+ },
+ "replay_title": "First steps with {name}",
+ "replay": "Start",
+ "replay_body": "Ten small, real things to try with {name}: talk, use tools, remember, build, hand off to agents. Each one is explained after it happened.",
+ "finished": {
+ "title": "You've got the basics!",
+ "body": "You completed {done} of {total} first steps. From now on, just talk to {name}: it decides whether to answer, use a tool or bring in an agent.",
+ "close": "Close"
+ },
+ "quests": {
+ "wake": {
+ "title": "Wake {name} up",
+ "ask": "Say your wake word out loud, for example \"Hey {name}\". Or open voice mode and press the round button in the chat bar. Then just ask anything.",
+ "explain": "{name} is listening. That's all it takes: wake it up and talk like you would to a person.",
+ "how": "Your wake word is recognised right here on your computer. Only after it does your speech go to the brain, and the answer comes back as a voice."
+ },
+ "ask": {
+ "title": "Ask your first question",
+ "ask": "Type or say a question. Try this one:",
+ "prompt": "What can you do for me? Give me three examples from my everyday life.",
+ "explain": "That was the simplest path: your words went to the brain, and it answered directly.",
+ "how": "The brain is the AI model you connected. Plain questions need no tools, so the answer comes in seconds. Every chat is saved under Recent chats."
+ },
+ "tool": {
+ "title": "Let it use a tool",
+ "ask": "Now ask for something that needs its hands, not just its head:",
+ "prompt": "Open wikipedia.org in my browser.",
+ "explain": "This time the brain did not just answer: it used a tool to act on your computer.",
+ "how": "Tools are {name}'s hands. The brain picks one, the safety check approves it, and it runs. Under each reply you can open the steps and see every tool it used."
+ },
+ "screen": {
+ "title": "Let it look at your screen",
+ "ask": "{name} can see your screen, but only when you ask. Try:",
+ "prompt": "What's on my screen right now? Describe it briefly.",
+ "explain": "{name} took one look at your screen and described it.",
+ "how": "A screen look is a single snapshot, taken only when a request needs it. It goes to the brain like a photo. Nothing records your screen in the background."
+ },
+ "memory": {
+ "title": "Teach it something",
+ "ask": "Tell {name} something worth keeping:",
+ "prompt": "Remember that my favourite colour is blue and that I prefer short answers.",
+ "explain": "{name} saved this to its memory and will use it from now on.",
+ "how": "Facts land in your Wiki and profile, stored on your computer. Before answering, {name} looks up what it knows about you. You can read and edit every note in Notes."
+ },
+ "artifact": {
+ "title": "Have it make something",
+ "ask": "{name} can build finished things: pages, overviews, small tools. Say \"artifact\" to ask for one:",
+ "prompt": "Create an artifact: a one-page overview of the planets in our solar system, with one fun fact each.",
+ "explain": "{name} started building the page. When it is ready, it appears in Artifacts.",
+ "how": "An artifact is a bigger piece of work, so {name} hands it to a worker on a strong model. It builds one self-contained page, and Artifacts keeps it for you to open again later."
+ },
+ "agent": {
+ "title": "Hand a big job to an agent",
+ "ask": "For longer work, {name} brings in an agent. You can keep talking while it works:",
+ "prompt": "Research the three best budget laptops right now and write me a short comparison.",
+ "explain": "{name} handed the job to an agent. It works in the background; the result comes back to your chat.",
+ "how": "{name} stays your single contact. It plans the job and starts an agent, and a reviewer checks the result before it reaches you. You can watch the progress in Agents."
+ },
+ "team": {
+ "title": "Meet your team",
+ "ask": "Agents are helpers with their own role. Open the Agents area to meet them.",
+ "explain": "This is where your agents live and work.",
+ "how": "Create your own agent with its own role, model and instructions, for example a researcher or a writer. Click an agent to chat with it or give it a job. {name} can also hand work to it for you."
+ },
+ "plugin": {
+ "title": "Connect an app",
+ "ask": "Plugins connect {name} to the apps you use: email, calendar, notes, smart home and more.",
+ "explain": "Here you connect your apps. Pick one you use every day and click Connect; your browser opens once to sign in.",
+ "how": "Each connected app becomes a new tool for {name}. Afterwards just ask, for example \"What's on my calendar tomorrow?\". Anything that sends or changes something still asks you first."
+ },
+ "ide": {
+ "title": "Let agents write code",
+ "ask": "The Agentic IDE runs coding agents such as Claude Code and Codex in real terminals, on your own projects.",
+ "explain": "This is the Agentic IDE. Open a project folder and start a coding agent in a pane.",
+ "how": "Each pane is a real terminal with its own agent. Talk to them by typing, or by voice through {name}. Several can work side by side on the same project."
+ }
+ }
}
}
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 b797d3d6c5..43cfb04b9e 100644
--- a/jarvis/ui/web/frontend/src/i18n/locales/onboarding/es.json
+++ b/jarvis/ui/web/frontend/src/i18n/locales/onboarding/es.json
@@ -5,13 +5,34 @@
"step_of": "{current} de {total}",
"welcome": {
"title": "Bienvenido",
- "lede": "Configuramos tu asistente aquí mismo, en la aplicación: una clave de API, una suscripción para tus agentes y tu palabra de activación. Después, una breve visita te enseña la aplicación.",
+ "lede": "Primero, un vistazo rápido a qué es {name} y cómo funciona. Después lo configuramos aquí mismo, en la aplicación: una clave de API, una suscripción para tus agentes y tu palabra de activación.",
"language": "Idioma",
"lang_en": "English",
"lang_de": "Deutsch",
"lang_es": "Español",
"start": "Empezar"
},
+ "how": {
+ "title": "Cómo funciona {name}",
+ "lede": "Tu mascota te guía por la aplicación y te explica cómo funciona {name}.",
+ "next": "Siguiente",
+ "prev": "Atrás",
+ "skip": "Saltar",
+ "finish": "A configurarlo",
+ "beat_of": "{current} / {total}",
+ "beats": {
+ "hello": "¡Hola, soy {pet}! Antes de configurar nada, te enseño cómo funciona {name}. Es rápido, y verás la aplicación real mientras te lo explico.",
+ "talk": "Todo empieza aquí. Hablas con un solo asistente: {name}. Escribe aquí, o pulsa el botón redondo y habla. Nunca eliges tú una herramienta o un modelo; {name} decide lo que hace falta.",
+ "brain": "Para pensar, {name} necesita un cerebro: un modelo de IA de OpenAI, Google, Anthropic u otro proveedor, o uno en tu propio ordenador. Basta con una clave, y la añadimos juntos en un momento.",
+ "tools": "Luego {name} necesita manos. Puede usar tu ordenador y tu navegador por sí mismo, además de cada app que conectes aquí: correo, calendario, notas, hogar inteligente. Cuando pides algo, elige solo la herramienta adecuada.",
+ "agents": "Los trabajos grandes, como una investigación, un informe o una web, van a los agentes. Son el equipo de {name}: {name} les pasa el trabajo y sigue hablando contigo, y un revisor comprueba el resultado antes de que te llegue.",
+ "ide": "Aquí trabajan agentes de programación como Claude Code y Codex, en terminales reales y en tus propios proyectos. Escríbeles directamente, o deja que {name} los dirija por voz.",
+ "results": "Lo que salga, como páginas, informes o imágenes, va a Artifacts. Las respuestas cortas vuelven directamente al chat o en voz alta.",
+ "memory": "{name} también recuerda. Lo que le cuentas va a sus notas y a tu perfil, guardados en tu ordenador, para que nunca tengas que repetirte.",
+ "safety": "Y tú mantienes el control. Lo inofensivo simplemente ocurre. Todo lo que envía, borra o cuesta dinero espera primero tu sí.",
+ "done": "Esa es toda la idea: hablas, {name} piensa, usa herramientas, llama a agentes y te entrega el resultado. Ahora démosle un cerebro."
+ }
+ },
"keys": {
"title": "Añade una clave de API",
"lede": "Tu asistente necesita una clave de IA para pensar y hablar; sin ella, el chat y la voz siguen apagados. Esta es la página Claves API: pega una clave en la tarjeta de un proveedor y guárdala. Con OpenAI o Gemini basta una sola clave para la voz en directo.",
@@ -66,19 +87,113 @@
"skip": "Saltar visita",
"step_of": "{current} de {total}",
"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_body": "Vuelve a explicar cómo funciona {name}, te guía 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.",
- "agents": "Los agentes son tu equipo: ayudantes que se encargan de trabajos grandes en segundo plano. Echemos un vistazo.",
"agents_world": "Este es el Verse, tus agentes trabajando. Haz clic en uno para chatear con él o darle una tarea. Siguiente te lleva de vuelta.",
"voice_hub": "En Voz tienes el dictado en cualquier aplicación, tu propia lista de palabras y atajos hablados.",
- "artifacts": "Todo lo que {name} crea, desde páginas hasta imágenes e informes, se guarda en Artefactos.",
- "ide": "El Agentic IDE ejecuta agentes de programación uno al lado del otro en terminales reales, sobre tus proyectos.",
- "plugins": "Plugins, skills y MCP conectan a {name} con tus aplicaciones. El icono de la tienda, abajo, abre el Marketplace.",
"settings": "Aquí están los ajustes, las claves de API, los costes y tu perfil. Puedes repetir esta visita cuando quieras en Ajustes → Aplicación.",
"done": "Esa es la visita. Ya está todo listo: habla con {name} cuando quieras."
}
+ },
+ "first_steps": {
+ "title": "Primeros pasos",
+ "progress": "{done}/{total}",
+ "collapse": "Minimizar",
+ "close": "Cerrar",
+ "quest_of": "Paso {current} de {total}",
+ "how_label": "Cómo funciona:",
+ "waiting": "Enviado. Mira el chat: {name} está en ello.",
+ "next": "Siguiente paso",
+ "finish": "Terminar",
+ "skip": "Saltar este",
+ "try": {
+ "send": "Envíalo por mí",
+ "voice": "Abrir el modo de voz",
+ "open": "Llévame allí"
+ },
+ "show": {
+ "memory": "Abrir Notas",
+ "artifact": "Abrir Artifacts",
+ "agent": "Ver en Agentes"
+ },
+ "replay_title": "Primeros pasos con {name}",
+ "replay": "Empezar",
+ "replay_body": "Diez cosas pequeñas y reales para probar con {name}: hablar, usar herramientas, recordar, construir, pasar trabajo a agentes. Cada una se explica después de ocurrir.",
+ "finished": {
+ "title": "¡Ya dominas lo básico!",
+ "body": "Completaste {done} de {total} primeros pasos. A partir de ahora, simplemente habla con {name}: decide si responde, usa una herramienta o llama a un agente.",
+ "close": "Cerrar"
+ },
+ "quests": {
+ "wake": {
+ "title": "Despierta a {name}",
+ "ask": "Di tu palabra de activación en voz alta, por ejemplo «Hey {name}». O abre el modo de voz y pulsa el botón redondo de la barra del chat. Después pregunta lo que quieras.",
+ "explain": "{name} te escucha. No hace falta más: despiértalo y habla como con una persona.",
+ "how": "Tu palabra de activación se reconoce aquí mismo, en tu ordenador. Solo después tu voz va al cerebro, y la respuesta vuelve hablada."
+ },
+ "ask": {
+ "title": "Haz tu primera pregunta",
+ "ask": "Escribe o di una pregunta. Prueba esta:",
+ "prompt": "¿Qué puedes hacer por mí? Dame tres ejemplos de mi día a día.",
+ "explain": "Ese fue el camino más simple: tus palabras fueron al cerebro y respondió directamente.",
+ "how": "El cerebro es el modelo de IA que conectaste. Las preguntas sencillas no necesitan herramientas, así que la respuesta llega en segundos. Cada chat se guarda en Chats recientes."
+ },
+ "tool": {
+ "title": "Deja que use una herramienta",
+ "ask": "Ahora pide algo que necesite sus manos, no solo su cabeza:",
+ "prompt": "Abre wikipedia.org en mi navegador.",
+ "explain": "Esta vez el cerebro no solo respondió: usó una herramienta para actuar en tu ordenador.",
+ "how": "Las herramientas son las manos de {name}. El cerebro elige una, el control de seguridad la aprueba y se ejecuta. Bajo cada respuesta puedes abrir los pasos y ver cada herramienta usada."
+ },
+ "screen": {
+ "title": "Deja que mire tu pantalla",
+ "ask": "{name} puede ver tu pantalla, pero solo cuando lo pides. Prueba:",
+ "prompt": "¿Qué hay ahora mismo en mi pantalla? Descríbelo brevemente.",
+ "explain": "{name} miró una vez tu pantalla y la describió.",
+ "how": "Mirar la pantalla es una sola captura, tomada solo cuando una petición la necesita. Va al cerebro como una foto. Nada graba tu pantalla en segundo plano."
+ },
+ "memory": {
+ "title": "Enséñale algo",
+ "ask": "Cuéntale a {name} algo que valga la pena guardar:",
+ "prompt": "Recuerda que mi color favorito es el azul y que prefiero respuestas cortas.",
+ "explain": "{name} lo guardó en su memoria y lo usará a partir de ahora.",
+ "how": "Los datos van a tu Wiki y a tu perfil, guardados en tu ordenador. Antes de responder, {name} consulta lo que sabe de ti. Puedes leer y editar cada nota en Notas."
+ },
+ "artifact": {
+ "title": "Haz que cree algo",
+ "ask": "{name} puede construir cosas terminadas: páginas, resúmenes, pequeñas herramientas. Di «artifact» para pedir uno:",
+ "prompt": "Crea un artifact: un resumen de una página sobre los planetas del sistema solar, con un dato curioso de cada uno.",
+ "explain": "{name} empezó a construir la página. Cuando esté lista, aparecerá en Artifacts.",
+ "how": "Un artifact es un trabajo más grande, así que {name} se lo pasa a un ayudante con un modelo potente. Construye una página independiente, y Artifacts la guarda para que la abras más tarde."
+ },
+ "agent": {
+ "title": "Pasa un trabajo grande a un agente",
+ "ask": "Para trabajos largos, {name} llama a un agente. Puedes seguir hablando mientras trabaja:",
+ "prompt": "Investiga los tres mejores portátiles baratos ahora mismo y escríbeme una comparación corta.",
+ "explain": "{name} pasó el trabajo a un agente. Trabaja en segundo plano; el resultado llega a tu chat.",
+ "how": "{name} sigue siendo tu único contacto. Planifica el trabajo y pone en marcha un agente, y un revisor comprueba el resultado antes de que te llegue. Puedes ver el progreso en Agentes."
+ },
+ "team": {
+ "title": "Conoce a tu equipo",
+ "ask": "Los agentes son ayudantes con su propio papel. Abre el área Agentes para conocerlos.",
+ "explain": "Aquí viven y trabajan tus agentes.",
+ "how": "Crea tu propio agente con su papel, modelo e instrucciones, por ejemplo un investigador o una redactora. Haz clic en un agente para chatear con él o darle un encargo. {name} también puede pasarle trabajo por ti."
+ },
+ "plugin": {
+ "title": "Conecta una app",
+ "ask": "Los plugins conectan {name} con las apps que usas: correo, calendario, notas, hogar inteligente y más.",
+ "explain": "Aquí conectas tus apps. Elige una que uses a diario y pulsa Conectar; tu navegador se abre una vez para iniciar sesión.",
+ "how": "Cada app conectada se convierte en una nueva herramienta para {name}. Después solo pregunta, por ejemplo «¿Qué tengo mañana en el calendario?». Todo lo que envía o cambia algo te pregunta antes."
+ },
+ "ide": {
+ "title": "Deja que los agentes programen",
+ "ask": "El Agentic IDE ejecuta agentes de programación como Claude Code y Codex en terminales reales, en tus propios proyectos.",
+ "explain": "Este es el Agentic IDE. Abre una carpeta de proyecto e inicia un agente de programación en un panel.",
+ "how": "Cada panel es una terminal real con su propio agente. Háblales escribiendo, o por voz a través de {name}. Varios pueden trabajar lado a lado en el mismo proyecto."
+ }
+ }
}
}
diff --git a/jarvis/ui/web/frontend/src/views/settings/AppSettingsGroup.tsx b/jarvis/ui/web/frontend/src/views/settings/AppSettingsGroup.tsx
index 36a54b4c03..3900612a9c 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 { SETUP_REPLAY_EVENT } from "@/components/onboarding/tourEvents";
+import { Compass, Monitor, Moon, Power, Sparkles, Sun, Zap } from "lucide-react";
+import { FIRST_STEPS_START_EVENT, 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";
@@ -31,6 +31,7 @@ export function AppSettingsGroup() {
<AppearanceRow />
<AutostartRow />
<TourRow />
+ <FirstStepsRow />
</div>
);
}
@@ -67,6 +68,37 @@ function TourRow() {
);
}
+/**
+ * Starts the first-steps guide again: ten small, real things to do with the
+ * assistant, each explained after it happened.
+ */
+function FirstStepsRow() {
+ const t = useT();
+ const ready = useLocaleChunk("onboarding");
+ if (!ready) return null;
+ return (
+ <div className="rounded-lg border border-border bg-card p-4">
+ <div className="flex items-start gap-3">
+ <Sparkles className="mt-0.5 h-4 w-4 shrink-0 text-muted-foreground" />
+ <div className="min-w-0 flex-1">
+ <div className="flex flex-wrap items-center justify-between gap-3">
+ <h4 className="font-medium">{t("first_steps.replay_title")}</h4>
+ <button
+ type="button"
+ onClick={() => window.dispatchEvent(new CustomEvent(FIRST_STEPS_START_EVENT))}
+ data-testid="settings-first-steps"
+ 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"
+ >
+ {t("first_steps.replay")}
+ </button>
+ </div>
+ <p className="mt-0.5 text-xs text-muted-foreground">{t("first_steps.replay_body")}</p>
+ </div>
+ </div>
+ </div>
+ );
+}
+
const THEME_OPTIONS: ReadonlyArray<{
value: ThemePreference;
icon: typeof Sun;
diff --git a/tests/unit/setup/test_onboarding_meta.py b/tests/unit/setup/test_onboarding_meta.py
index e3e18c42cc..354c54ce4a 100644
--- a/tests/unit/setup/test_onboarding_meta.py
+++ b/tests/unit/setup/test_onboarding_meta.py
@@ -5,8 +5,12 @@ 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, 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"]
+ # macOS permissions, the wake word in Settings, then the start. The "how"
+ # step (2026-10-01) explains the product before anything is set up.
+ assert m.ONBOARDING_STEPS == [
+ "welcome", "how", "keys", "subscriptions", "permissions", "voice", "ready",
+ ]
+ assert m.ONBOARDING_STEPS.index("how") < m.ONBOARDING_STEPS.index("keys")
# 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")