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 (#304)

Ruben Lütkeadaabec264bb
diff --git a/docs/authoring/public-docs-manifest.yaml b/docs/authoring/public-docs-manifest.yaml
index 7e73d633d6..1854e68c4e 100644
--- a/docs/authoring/public-docs-manifest.yaml
+++ b/docs/authoring/public-docs-manifest.yaml
@@ -65,7 +65,7 @@ pages:
file: docs/product/start-here/first-run-setup.md
title: Complete First-Run Setup
diataxis: tutorial
- summary: Setup runs inside the app. Agree to the terms, add one key on the API Keys page, pick a wake word in Settings, then take the tour.
+ summary: Your pet explains the app, then you add one key, connect a subscription, pick a wake word and try ten first steps.
authoritative_sources:
- jarvis/ui/web/frontend/src/components/onboarding/setup/SetupTour.tsx
- jarvis/ui/web/frontend/src/components/onboarding/setup/setupSteps.ts
diff --git a/docs/product/start-here/first-run-setup.md b/docs/product/start-here/first-run-setup.md
index 657de31523..2455d35422 100644
--- a/docs/product/start-here/first-run-setup.md
+++ b/docs/product/start-here/first-run-setup.md
@@ -1,14 +1,14 @@
---
title: "Complete First-Run Setup"
slug: first-run-setup
-summary: "Setup runs inside the app. Agree to the terms, add one key on the API Keys page, pick a wake word in Settings, then take the tour."
+summary: "Your pet explains the app, then you add one key, connect a subscription, pick a wake word and try ten first steps."
section: "Start here"
section_order: 1
order: 3
diataxis: tutorial
status: active
owner: maintainers
-last_reviewed: 2026-09-30
+last_reviewed: 2026-10-01
phase: "-"
audience: end-user
tags: [setup, onboarding, tour, language, permissions, microphone, wake-word, providers]
@@ -16,9 +16,10 @@ related: [providers-and-api-keys, audio-and-wake-word, permissions, start-your-f
---
First-run setup happens inside the real app. There is no separate setup
-screen: the window dims and a small card with the mascot walks you to the
-places where each thing is really set, and waits there. Everything else is
-explained afterwards by a short tour of the app.
+screen: the window dims and your desktop pet (chosen under **Settings > My
+Pets**) walks you to the places where each thing is really set, explains them
+in a speech bubble, and waits there. A short tour and ten small first steps
+follow and let you try the assistant for real.
## Before You Start
@@ -36,67 +37,113 @@ explained afterwards by a short tour of the app.
While setup runs, only the highlighted part of the app and the card can be
used. The dots on the card show where you are. **Back** returns to the
-previous step, never behind the agreement. If the window reloads, setup
-reopens on the step you were on.
+previous step, never to the welcome. If the window reloads, setup reopens on
+the step you were on.
-### 1. Agree to the terms
+### 1. Welcome
-The first card lists what the assistant does on this computer: it runs
-commands and changes files, can see your screen when asked, sends what you say
-to the provider you choose, is billed by that provider, and can make mistakes.
+Pick **English**, **Deutsch** or **Español** on the card if you want another
+interface language (you can change it later under **Settings > Languages**),
+then select **Let's start**. There is nothing to agree to: the app is open
+source. **Skip setup, I know my way around** ends the whole first-run guide
+at once; it is recorded as done and the app restarts once.
-1. Pick **English**, **Deutsch** or **Español** on the card if you want
- another interface language. You can change it later under **Settings >
- Languages**.
-2. Optionally open **Read the full Terms of Use**.
-3. Tick the agreement, then select **Agree and continue**. **Decline and quit**
- closes the app without saving anything; setup asks again next time.
+### 2. How it works
-### 2. Add one API key
+Before anything is set up, the pet walks the real interface and explains how
+everything runs through one assistant: you talk to it in the composer, it
+thinks with an AI model, uses tools (your computer, the browser and connected
+apps from **Plugins**), hands bigger jobs to **Agents**, works with coding
+agents in the **Agentic IDE**, keeps results in **Artifacts**, remembers what
+matters, and asks before anything with real consequences. **Next** and
+**Back** move through it, the dots show where you are, **Skip** goes straight
+to the keys. Nothing is changed while the pet explains.
+
+### 3. Add one API key
Setup opens the **API Keys** page and highlights it. Paste one key into a
provider card and save it:
-- An **OpenAI** or **Gemini** key is enough on its own: setup points live voice
- and its thinking model at it and confirms **Connected**.
-- Any other provider's key becomes the Brain when none is active yet.
+- An **OpenAI** or **Gemini** key is enough on its own and also brings live
+ voice: setup points live voice and its thinking model at it and confirms
+ **Connected**.
+- Any other provider's key becomes the Brain when none is active yet. Chat
+ works, and voice runs the classic way (speech to text, answer read aloud),
+ a little slower. The card says which of the two you have.
- For a keyless start, turn on **Local Mode** on the same page and use Ollama.
+Once a key is saved, the card points on to the subscriptions.
+
**Continue** unlocks once a key is saved. **I'll add a key later** moves on;
chat and voice then stay off until a key exists.
-### 3. Allow access on this Mac (macOS only)
+### 4. Connect a subscription for your agents
+
+Setup switches the API Keys page to its **Agents** tab and scrolls to the
+**Coding CLIs** rows. Agents do the bigger
+background jobs, and they run best on a subscription you already pay for:
+**Claude** (Pro or Max) or **ChatGPT** (Codex) are recommended. Select
+**Connect** on that row; your browser opens once to sign in. A subscription is
+a flat monthly price; without one, agents use your API key and each job is
+billed per use.
+
+The card lists every subscription that is signed in, and **Continue** unlocks
+once there is one. **I'll connect one later** moves on.
+
+### 5. Allow access on this Mac (macOS only)
Setup opens **Settings > Privacy permissions**. Use **Allow** or **Open
Settings** on each row you want, return, and wait for the row to update. The
restart at the end applies the grants. Windows and Linux skip this step.
-### 4. Choose your wake word
+### 6. Choose your wake word
Setup opens **Settings** at the **Wake Word** group. **Hey** is fixed; type
your own word after it and save. The word also becomes the assistant's name,
for example **Hey Nova** makes an assistant called Nova. The card confirms when
-the wake word is on. Without a wake word, the Call keyboard shortcut starts a
-conversation.
+the wake word is on, and **Continue** unlocks once one is saved. Without a
+wake word, choose **Skip, I'll use the Call shortcut**; the Call keyboard
+shortcut then starts a conversation.
-### 5. All set
+### 7. All set
-The last card reads back the active Brain and how voice starts, and offers
-**Start at login** if your system supports it. **Start** saves the setup and
-restarts the app once so every choice takes effect together.
+The last card reads back the active Brain, the connected agent subscriptions
+and how voice starts, and offers **Start at login** if your system supports
+it. **Show me around** starts the tour.
## Take the Tour
-After the restart the app opens with a short guided tour. It dims the window,
-lights up one part of the real interface at a time, and explains it in a small
-card: the voice bar, a new chat, the agents and their world, Voice, Artifacts,
-the Agentic IDE, Plugins and the Marketplace, and Settings.
+The tour follows setup straight away. It dims the window, lights up one part
+of the real interface at a time, and the pet explains it: the voice bar, a new
+chat, the agents' world, Voice, and Settings. What the setup walk already
+covered is not repeated.
- **Next** moves on; clicking the highlighted part yourself does the same.
- The tour navigates by itself where needed (into the agents' world and back)
and ends on the home screen. It never starts a call or any work for you.
- **Skip tour** or **Escape** ends it at any point.
-- Replay it anytime under **Settings > App > App tour**.
+- When the tour ends (or is skipped), setup is saved and the app restarts once
+ so every choice takes effect together.
+- Do it all again anytime under **Settings > App > Do the onboarding again**.
+ The replay starts at the pet's explanation and never restarts anything.
+
+## Try the First Steps
+
+After the first tour, the pet stays in the bottom-right corner with ten small
+things to try for real: wake the assistant, ask a first question, let it use a
+tool, let it look at your screen, teach it something, have it make an
+artifact, hand a big job to an agent, meet your agents, connect an app, and
+open the Agentic IDE.
+
+- Each step shows one example. **Send it for me** sends exactly that message;
+ it is a real request and bills your connected model like any other.
+- The pet waits until the app reports that the step really happened, then
+ explains what went on and where to see the result.
+- **Skip this one** moves on; the arrow tucks the pet into a small pill; the
+ cross closes the guide. It never blocks the app.
+- Start it again under **Settings > App > First steps**.
+- Stuck at any point? Ask the assistant; it can open any part of the app for
+ you.
## Recover a Skipped or Deferred Choice
@@ -111,7 +158,7 @@ the Agentic IDE, Plugins and the Marketplace, and Settings.
## How It Fits Together
-1. The agreement is the only consent moment; the installer asks nothing.
+1. Nothing asks for consent: neither the installer nor setup.
2. Setup never has its own screens: each step uses the page you will use
later, so what you learn on day one is where things live.
3. One key is enough to start. A starter plan points live voice and its
@@ -120,11 +167,12 @@ the Agentic IDE, Plugins and the Marketplace, and Settings.
The Call shortcut starts voice without an always-listening wake engine.
5. Permissions allow an operating-system capability; they do not approve a
later Computer Use action or bypass its safety check.
-6. One restart at the end applies every choice; the tour runs once after it.
+6. Setup and tour run as one flow; one restart after the tour applies every
+ choice.
## Check That It Works
-1. After **Start**, confirm the app reopens and the tour begins.
+1. After the tour, confirm the app restarts and reopens on the home screen.
2. Open **API Keys**, select **Test** on the active Brain card, and look for
**Works**.
3. Start a new chat and send a harmless message. Confirm a reply arrives.
@@ -141,7 +189,8 @@ Desktop-only features report their limits rather than prevent startup.
| A card on the API Keys page reports a failing key | The provider refused the key or the account has no credit | Fix the account at the provider, or save a key from another provider |
| Microphone test reports quiet, missing, or blocked | The input has no usable signal | Check OS access and **Settings > Audio devices** |
| Saved wake word does not respond | Its local model, language, microphone, or activation switch is not ready | Use the Call shortcut; under **Settings > Wake Word**, install the offered model and run **Test wake word** |
-| The tour does not appear after the restart | The app opened in the Agentic IDE, or the tour was already seen | Leave the IDE, or replay it under **Settings > App** |
+| The tour does not appear | The tour was already seen | Replay it under **Settings > App** |
+| A first step never completes | The app did not report that action (for example no tool was needed for the answer) | Choose **Skip this one**, or try the example again |
| App does not reopen | The restart could not start a fresh process | Open the app; setup was already saved |
| First-run setup returns every launch | The completion state is not read from the same writable data location | Follow [Troubleshooting](troubleshooting) for data-directory and version checks |
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/JarvisAgentSection.tsx b/jarvis/ui/web/frontend/src/components/JarvisAgentSection.tsx
index 578f7cfcca..3899cf1fa1 100644
--- a/jarvis/ui/web/frontend/src/components/JarvisAgentSection.tsx
+++ b/jarvis/ui/web/frontend/src/components/JarvisAgentSection.tsx
@@ -384,6 +384,7 @@ export function JarvisAgentSection({
title="Coding CLIs"
hint="sign in with a subscription — no key"
testId="agent-group-clis"
+ tourId="apikeys-subscriptions"
>
{codexRow && (
<CodexConnectionCard
@@ -638,16 +639,19 @@ function AgentGroup({
title,
hint,
testId,
+ tourId,
children,
}: {
icon: LucideIcon;
title: string;
hint: string;
testId?: string;
+ /** A stable hook for the first-run guide (`data-tour`). */
+ tourId?: string;
children: React.ReactNode;
}) {
return (
- <div data-testid={testId} className="space-y-2">
+ <div data-testid={testId} data-tour={tourId} className="space-y-2">
<div className="flex min-w-0 items-center gap-2 px-0.5 text-xs">
<Icon aria-hidden="true" className="h-3.5 w-3.5 shrink-0 text-primary" />
<span className="font-display text-meta font-semibold tracking-tight">{title}</span>
diff --git a/jarvis/ui/web/frontend/src/components/agentchat/AgentComposer.tsx b/jarvis/ui/web/frontend/src/components/agentchat/AgentComposer.tsx
index 5da0c4d198..9a99142cae 100644
--- a/jarvis/ui/web/frontend/src/components/agentchat/AgentComposer.tsx
+++ b/jarvis/ui/web/frontend/src/components/agentchat/AgentComposer.tsx
@@ -476,6 +476,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 bfcc66511c..d3a0d41e4c 100644
--- a/jarvis/ui/web/frontend/src/components/onboarding/OnboardingGate.test.tsx
+++ b/jarvis/ui/web/frontend/src/components/onboarding/OnboardingGate.test.tsx
@@ -2,8 +2,25 @@ import { act, cleanup, render, screen, waitFor } from "@testing-library/react";
import { afterEach, expect, it, vi } from "vitest";
vi.mock("./setup/SetupTour", () => ({
- SetupTour: ({ preview, startAt }: { preview: boolean; startAt?: string }) => (
- <div data-testid="guide" data-preview={String(preview)} data-start={startAt ?? ""} />
+ SetupTour: ({
+ preview,
+ startAt,
+ onFinished,
+ onSkipAll,
+ }: {
+ preview: boolean;
+ startAt?: string;
+ onFinished: () => void;
+ onSkipAll?: () => void;
+ }) => (
+ <>
+ <button type="button" data-testid="guide" data-preview={String(preview)} data-start={startAt ?? ""} onClick={onFinished}>
+ guide
+ </button>
+ <button type="button" data-testid="guide-skip-all" onClick={onSkipAll}>
+ skip
+ </button>
+ </>
),
}));
vi.mock("./tour/GuidedTour", () => ({
@@ -14,11 +31,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();
});
@@ -46,7 +72,7 @@ it("shows the guide while setup is not complete", async () => {
stub({ ...base, completed: false, tour_completed: false });
render(<OnboardingGate />);
await waitFor(() => expect(screen.getByTestId("guide")).toBeDefined());
- // A first run is real: it completes and restarts at its end.
+ // A first run is real: it completes and restarts once its tour ends.
expect(screen.getByTestId("guide").dataset.preview).toBe("false");
expect(screen.queryByTestId("tour")).toBeNull();
});
@@ -136,7 +162,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));
@@ -145,5 +171,103 @@ 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 () => {
+ const fetchMock = stub({ ...base, completed: false, tour_completed: false });
+ render(<OnboardingGate activeSection="chats" />);
+ const guide = await screen.findByTestId("guide");
+ act(() => guide.click());
+ const tour = await screen.findByTestId("tour");
+ const urls = () => fetchMock.mock.calls.map((c) => String(c[0]));
+ // Nothing completes (and nothing restarts) while the tour is still showing.
+ expect(urls()).not.toContain("/api/onboarding/complete");
+ act(() => tour.click());
+ await waitFor(() => expect(urls()).toContain("/api/onboarding/complete"));
+ expect(urls().indexOf("/api/onboarding/tour-complete")).toBeLessThan(urls().indexOf("/api/onboarding/complete"));
+});
+
+it("never completes onboarding after a replayed setup", async () => {
+ const fetchMock = stub({ ...base, completed: true, tour_completed: true });
+ render(<OnboardingGate activeSection="chats" />);
+ await new Promise((r) => setTimeout(r, 20));
+ act(() => {
+ window.dispatchEvent(new CustomEvent(SETUP_REPLAY_EVENT));
+ });
+ const guide = await screen.findByTestId("guide");
+ act(() => guide.click());
+ const tour = await screen.findByTestId("tour");
+ act(() => tour.click());
+ await waitFor(() => expect(screen.queryByTestId("tour")).toBeNull());
+ 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());
+});
+
+it("skips the whole first run: tour recorded, onboarding completed, no guide left", async () => {
+ const fetchMock = stub({ ...base, completed: false, tour_completed: false });
+ render(<OnboardingGate activeSection="chats" />);
+ const skip = await screen.findByTestId("guide-skip-all");
+ act(() => skip.click());
+ const urls = () => fetchMock.mock.calls.map((c) => String(c[0]));
+ await waitFor(() => expect(urls()).toContain("/api/onboarding/complete"));
+ expect(urls()).toContain("/api/onboarding/tour-complete");
+ expect(screen.queryByTestId("guide")).toBeNull();
+ expect(screen.queryByTestId("tour")).toBeNull();
+});
+
+it("starts the first-steps guide fresh at the end of a real first run, even if an old one was closed", async () => {
+ window.localStorage.setItem(
+ "jarvis.firstSteps.v1",
+ JSON.stringify({ status: "dismissed", done: [], skipped: [], current: "wake", collapsed: false }),
+ );
+ stub({ ...base, completed: false, tour_completed: false });
+ render(<OnboardingGate activeSection="chats" />);
+ const guide = await screen.findByTestId("guide");
+ act(() => guide.click());
+ const tour = await screen.findByTestId("tour");
+ act(() => tour.click());
+ 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 c5e95992cb..49bf2e6999 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();
@@ -50,7 +61,15 @@ export function OnboardingGate({ activeSection }: { activeSection?: string } = {
// Bumped by each Settings replay; > 0 means a setup preview is requested,
// and the value remounts the guide so every replay starts fresh.
const [setupReplay, setSetupReplay] = useState(0);
+ // A real first run ends setup straight into the tour; onboarding is
+ // 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 = () => {
@@ -67,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);
@@ -91,8 +118,25 @@ 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}
+ onSkipAll={() => {
+ // A replay just closes; a real first run is recorded as done
+ // (tour included) and gets its one completion restart.
+ setSetupReplay(0);
+ setDismissed(true);
+ if (asked && onb.state?.completed) return;
+ void (async () => {
+ await onb.completeTour();
+ try {
+ await onb.complete();
+ } catch (e) {
+ // The next start offers the setup again, so nothing is lost.
+ console.warn("onboarding: skipping setup failed", e);
+ }
+ })();
+ }}
onFinished={() => {
+ if (!(asked && onb.state?.completed)) setCompleteAfterTour(true);
setSetupReplay(0);
setDismissed(true);
setTourDone(false);
@@ -113,12 +157,40 @@ export function OnboardingGate({ activeSection }: { activeSection?: string } = {
onDone={() => {
setTourDone(true);
setTourRequested(false);
- void onb.completeTour();
+ // The first tour hands over to the first-steps guide. Written
+ // before the completion restart, so the guide is there after it.
+ // A real first run always starts it fresh (an install that was
+ // reset to a new user gets it again); a later tour replay only
+ // when the guide was never met.
+ if (completeAfterTour || readFirstSteps() === null) {
+ const fresh = freshState();
+ writeFirstSteps(fresh);
+ setFirstSteps(fresh);
+ }
+ void (async () => {
+ await onb.completeTour();
+ if (!completeAfterTour) return;
+ setCompleteAfterTour(false);
+ try {
+ await onb.complete();
+ } catch (e) {
+ // The next start resumes setup at its last step, so nothing is lost.
+ console.warn("onboarding: completing after the tour failed", e);
+ }
+ })();
}}
/>
</Suspense>
);
}
+ 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..25bff46da5
--- /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: "thinking",
+ screen: "thinking",
+ memory: "thinking",
+ artifact: "thinking",
+ agent: "thinking",
+ team: "success",
+ plugin: "thinking",
+ ide: "thinking",
+};
+
+/** 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={48} />
+ <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={96}
+ 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..68637921f2
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/components/onboarding/setup/HowWalk.tsx
@@ -0,0 +1,185 @@
+/**
+ * "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: "thinking" },
+ { id: "agents", anchor: "nav-agents", placement: "right", pet: "thinking" },
+ { id: "ide", anchor: "nav-agentic-ide", placement: "right", pet: "thinking" },
+ { 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;
+const BEAT_KEY = "jarvis.setup.howBeat";
+
+/** The beat to resume on: a remount (a reload, a late locale load) keeps the place. */
+function readBeat(): number {
+ try {
+ const n = Number(window.sessionStorage.getItem(BEAT_KEY));
+ return Number.isInteger(n) && n > 0 && n < HOW_BEATS.length ? n : 0;
+ } catch {
+ return 0;
+ }
+}
+
+function saveBeat(n: number | null): void {
+ try {
+ if (n === null) window.sessionStorage.removeItem(BEAT_KEY);
+ else window.sessionStorage.setItem(BEAT_KEY, String(n));
+ } catch {
+ // Storage may be blocked; the walk then starts over after a reload.
+ }
+}
+
+export function HowWalk({ onDone }: { onDone: () => void }) {
+ const t = useT();
+ const pet = useGuidePet();
+ const [index, setIndexRaw] = useState(readBeat);
+ const setIndex = useCallback((update: (i: number) => number) => {
+ setIndexRaw((i) => {
+ const n = update(i);
+ saveBeat(n);
+ return n;
+ });
+ }, []);
+ 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 done = useCallback(() => {
+ saveBeat(null);
+ onDone();
+ }, [onDone]);
+
+ const next = useCallback(() => {
+ if (last) done();
+ else setIndex((i) => Math.min(HOW_BEATS.length - 1, i + 1));
+ }, [last, done, setIndex]);
+
+ // 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, setIndex]);
+
+ 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>
+ )}
+ {/* Progress inside this one setup step: dots, no second number
+ next to the setup's own "2 of 6". */}
+ <span
+ className="ml-auto flex items-center gap-1"
+ role="img"
+ aria-label={fill(t("first_run.how.beat_of"), { current: index + 1, total: HOW_BEATS.length })}
+ data-testid="how-progress"
+ >
+ {HOW_BEATS.map((b, i) => (
+ <span
+ key={b.id}
+ className={cn(
+ "h-1.5 rounded-full transition-all duration-200",
+ i === index ? "w-4 bg-accent" : i < index ? "w-1.5 bg-foreground/50" : "w-1.5 bg-border-strong",
+ )}
+ />
+ ))}
+ </span>
+ {!last && (
+ <QuietAction onClick={done} 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 eeeadf88e6..6509aacd95 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>;
@@ -105,16 +106,22 @@ afterEach(() => {
vi.unstubAllGlobals();
});
-it("asks for the consent first and opens the API Keys page after it", async () => {
+it("starts with a welcome and no consent gate, then opens the API Keys page", async () => {
const onb = fakeOnb();
render(<SetupTour onb={onb} preview={false} onFinished={vi.fn()} />);
const start = (await screen.findByTestId("onboarding-primary")) as HTMLButtonElement;
- expect(start.disabled).toBe(true);
- fireEvent.click(screen.getByTestId("onboarding-accept"));
+ expect(screen.getByTestId("setup-card").dataset.step).toBe("welcome");
+ expect(start.disabled).toBe(false);
+ expect(screen.queryByTestId("onboarding-accept")).toBeNull();
+ expect(screen.queryByTestId("onboarding-decline")).toBeNull();
await act(async () => {
fireEvent.click(start);
});
- expect(onb.acceptTerms).toHaveBeenCalled();
+ 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"));
@@ -188,7 +195,7 @@ it("leaves a key that was already there exactly as it is", async () => {
expect(calls.some((c) => c.url.includes("/switch"))).toBe(false);
});
-it("completes onboarding from the last step", async () => {
+it("hands over to the tour from the last step without completing yet", async () => {
const onb = fakeOnb({ ...accepted, current_step: "ready" });
const onFinished = vi.fn();
render(<SetupTour onb={onb} preview={false} onFinished={onFinished} />);
@@ -196,19 +203,30 @@ it("completes onboarding from the last step", async () => {
await act(async () => {
fireEvent.click(start);
});
- expect(onb.complete).toHaveBeenCalled();
- expect(onFinished).not.toHaveBeenCalled();
+ // The gate completes onboarding (and restarts) only once the tour ends.
+ expect(onFinished).toHaveBeenCalled();
+ expect(onb.complete).not.toHaveBeenCalled();
+});
+
+it("keeps the app on the step's page when something else moves it", async () => {
+ render(<SetupTour onb={fakeOnb({ ...accepted, current_step: "keys" })} preview={false} onFinished={vi.fn()} />);
+ await screen.findByTestId("setup-keys-waiting");
+ await waitFor(() => expect(useEventStore.getState().activeSection).toBe("apikeys"));
+ act(() => useEventStore.getState().setActiveSection("profile"));
+ await waitFor(() => expect(useEventStore.getState().activeSection).toBe("apikeys"));
});
it("walks a replay from the start and never writes, completes or restarts", async () => {
const onb = fakeOnb({ ...accepted, completed: true, current_step: "voice" });
const onFinished = vi.fn();
render(<SetupTour onb={onb} preview onFinished={onFinished} />);
- // A replay shows every step, the consent included (already ticked).
+ // A replay from the URL shows every step, the welcome included.
await waitFor(() => expect(screen.getByTestId("setup-card").dataset.step).toBe("welcome"));
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"));
@@ -239,3 +257,45 @@ 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();
+});
+
+it("lets the welcome skip the whole setup", async () => {
+ const onSkipAll = vi.fn();
+ render(<SetupTour onb={fakeOnb()} preview={false} onFinished={vi.fn()} onSkipAll={onSkipAll} />);
+ fireEvent.click(await screen.findByTestId("setup-skip-all"));
+ expect(onSkipAll).toHaveBeenCalled();
+});
+
+it("says what a key is for: live voice needs OpenAI or Gemini", async () => {
+ providers = [{ ...openai, configured: true, secrets_set: { openai_api_key: true } }];
+ render(<SetupTour onb={fakeOnb({ ...accepted, current_step: "keys" })} preview={false} onFinished={vi.fn()} />);
+ const live = await screen.findByTestId("setup-keys-live");
+ await waitFor(() => expect(live.dataset.tone).toBe("ok"));
+});
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 6efd486b2b..9a3cea2df5 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 { AlertTriangle, ArrowLeft, Cloud, CreditCard, Lock, Monitor, Terminal } from "lucide-react";
+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,24 +8,29 @@ 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";
import { ProgressDots } from "../ProgressDots";
import { Spotlight } from "../tour/Spotlight";
-import { CheckLine, PrimaryAction, QuietAction, Status } from "../ui";
+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: "thinking",
+ subscriptions: "thinking",
+ voice: "listening",
+ permissions: "idle",
+ ready: "success",
};
const LANGS: UiLanguage[] = ["en", "de", "es"];
@@ -40,22 +44,26 @@ const LANGS: UiLanguage[] = ["en", "de", "es"];
* Settings, on macOS the permissions —
* and waits there with a small card. The dim takes clicks, the hole does
* not: only the part being set up can be used, so nothing else starts before
- * setup is done. Every step but the consent has a way on without doing it.
+ * setup is done. Every step has a way on without doing it. There is no
+ * consent gate: it is an open-source app, the welcome only picks a language.
*
- * The last step completes onboarding; the backend then restarts the app once
- * and the tour of the app follows. `preview` (a replay) never completes and
- * never restarts — it only walks the steps and hands over to the tour.
- * `startAt` lets a replay from Settings begin past the consent.
+ * The last step hands over to the tour of the app straight away; the gate
+ * completes onboarding (and restarts the app once) when the tour ends.
+ * `preview` (a replay) never writes — it only walks the steps and hands over
+ * to the tour. `startAt` lets a replay from Settings begin at the API Keys.
*/
export function SetupTour({
onb,
preview,
onFinished,
+ onSkipAll,
startAt,
}: {
onb: Onb;
preview: boolean;
onFinished: () => void;
+ /** "Skip setup" on the welcome: ends the whole first-run guide. */
+ onSkipAll?: () => void;
startAt?: SetupStepId;
}) {
const t = useT();
@@ -67,7 +75,7 @@ export function SetupTour({
const [stepId, setStepId] = useState<SetupStepId>(() =>
preview
? (startAt ?? "welcome")
- : resumeStep(stepsFor(null), onb.state?.current_step ?? null, Boolean(onb.state?.terms.accepted)),
+ : resumeStep(stepsFor(null), onb.state?.current_step ?? null),
);
const [skipped, setSkipped] = useState<string[]>(() => onb.state?.skipped_steps ?? []);
const [cue, setCue] = useState(0);
@@ -100,6 +108,17 @@ export function SetupTour({
if (nav.activeSection !== step.section) nav.setActiveSection(step.section);
}, [ready, step.section, step.apiKeysTab, stepId]);
+ // Keep the app on this step's place. The dim blocks every click, so a
+ // drift is something else moving the app (a section restored late in
+ // boot) — the card would then describe a page that is not on screen.
+ useEffect(() => {
+ if (!ready || !step.section) return;
+ const target = step.section;
+ return useEventStore.subscribe((state) => {
+ if (state.activeSection !== target) state.setActiveSection(target);
+ });
+ }, [ready, step.section]);
+
// Later visits to the API Keys page open on its own default tab again.
useEffect(() => clearApiKeysTabRequest, []);
@@ -118,7 +137,7 @@ export function SetupTour({
const index = Math.max(0, steps.indexOf(stepId));
const nextId = steps[index + 1] ?? null;
- // Never back behind the consent, nor behind where a replay started.
+ // Never back to the welcome, nor behind where a replay started.
const firstId = preview && startAt ? startAt : steps[1];
const prevId = index > 1 && stepId !== firstId ? steps[index - 1] : null;
@@ -134,6 +153,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>
@@ -161,12 +183,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`)}
@@ -175,12 +197,12 @@ export function SetupTour({
</div>
</div>
<div className="mt-4">
- {stepId === "welcome" && <WelcomeStep onb={onb} preview={preview} onAccepted={() => { cheer(); next(); }} />}
+ {stepId === "welcome" && <WelcomeStep onStart={() => { cheer(); next(); }} onSkipAll={onSkipAll} />}
{stepId === "keys" && <KeysStep next={next} later={later} cheer={cheer} />}
{stepId === "subscriptions" && <SubscriptionsStep next={next} later={later} />}
{stepId === "voice" && <VoiceStep next={next} later={later} />}
{stepId === "permissions" && <PermissionsStep next={next} />}
- {stepId === "ready" && <ReadyStep onb={onb} preview={preview} onFinished={onFinished} />}
+ {stepId === "ready" && <ReadyStep preview={preview} onFinished={onFinished} />}
</div>
{footer}
</div>
@@ -190,69 +212,9 @@ export function SetupTour({
/* ------------------------------------------------------------------ steps */
-function WelcomeStep({ onb, preview, onAccepted }: { onb: Onb; preview: boolean; onAccepted: () => void }) {
+function WelcomeStep({ onStart, onSkipAll }: { onStart: () => void; onSkipAll?: () => void }) {
const t = useT();
const lang = useUiLanguage();
- const [accepted, setAccepted] = useState(Boolean(onb.state?.terms.accepted));
- const [busy, setBusy] = useState(false);
- const [error, setError] = useState<string | null>(null);
- const [declined, setDeclined] = useState(false);
- const [terms, setTerms] = useState<string | null>(null);
- const [showTerms, setShowTerms] = useState(false);
-
- async function toggleTerms() {
- setShowTerms((v) => !v);
- if (terms !== null) return;
- try {
- const res = await fetch("/api/onboarding/terms");
- setTerms(res.ok ? ((await res.json()) as { text: string }).text : "");
- } catch {
- setTerms("");
- }
- }
-
- async function proceed() {
- if (!accepted || busy) return;
- setBusy(true);
- setError(null);
- try {
- if (!preview) await onb.acceptTerms();
- onAccepted();
- } catch {
- setError(t("first_run.welcome.accept_failed"));
- } finally {
- setBusy(false);
- }
- }
-
- async function decline() {
- // The goodbye shows first: the backend ends the process right after it answers.
- setDeclined(true);
- if (preview) return;
- try {
- await fetch("/api/onboarding/decline-terms", { method: "POST" });
- } catch {
- // A warming backend cannot hold the goodbye back; the window closes either way.
- }
- }
-
- if (declined) {
- return (
- <div className="space-y-1" data-testid="onboarding-declined">
- <p className="text-sm font-medium text-foreground">{t("first_run.welcome.declined_title")}</p>
- <p className="text-sm leading-relaxed text-muted-foreground">{t("first_run.welcome.declined_body")}</p>
- </div>
- );
- }
-
- const facts: { key: string; Icon: typeof Terminal }[] = [
- { key: "commands", Icon: Terminal },
- { key: "screen", Icon: Monitor },
- { key: "cloud", Icon: Cloud },
- { key: "costs", Icon: CreditCard },
- { key: "mistakes", Icon: AlertTriangle },
- ];
-
return (
<div className="space-y-4">
<div className="flex items-center gap-0.5 self-start rounded-full border border-border p-0.5" role="radiogroup" aria-label={t("first_run.welcome.language")}>
@@ -273,42 +235,14 @@ function WelcomeStep({ onb, preview, onAccepted }: { onb: Onb; preview: boolean;
</button>
))}
</div>
-
- <ul className="space-y-1.5 rounded-xl border border-border bg-background px-3.5 py-3" data-testid="onboarding-facts">
- {facts.map(({ key, Icon }) => (
- <li key={key} className="flex items-start gap-2.5 text-sm leading-snug text-foreground">
- <Icon aria-hidden className="mt-0.5 h-3.5 w-3.5 shrink-0 text-muted-foreground" />
- <span>{t(`first_run.welcome.fact_${key}`)}</span>
- </li>
- ))}
- </ul>
-
- <div className="space-y-1.5">
- <CheckLine checked={accepted} onChange={setAccepted} testId="onboarding-accept">
- {t("first_run.welcome.accept")}
- </CheckLine>
- <QuietAction onClick={() => void toggleTerms()} className="ml-7 text-xs underline underline-offset-4">
- {showTerms ? t("first_run.welcome.hide_terms") : t("first_run.welcome.read_terms")}
- </QuietAction>
- {showTerms && (
- <pre className="ml-7 max-h-32 overflow-y-auto whitespace-pre-wrap rounded-lg border border-border bg-background p-2.5 font-sans text-xs leading-relaxed text-muted-foreground scrollbar-jarvis">
- {terms || t("first_run.welcome.terms_loading")}
- </pre>
- )}
- </div>
-
- {error && <Status tone="error">{error}</Status>}
-
- <div className="space-y-2">
- <PrimaryAction onClick={() => void proceed()} disabled={!accepted} busy={busy}>
- {t("first_run.welcome.start")}
- </PrimaryAction>
+ <PrimaryAction onClick={onStart}>{t("first_run.welcome.start")}</PrimaryAction>
+ {onSkipAll && (
<div className="text-center">
- <QuietAction onClick={() => void decline()} testId="onboarding-decline" className="text-xs">
- {t("first_run.welcome.decline")}
+ <QuietAction onClick={onSkipAll} testId="setup-skip-all" className="text-xs">
+ {t("first_run.welcome.skip_all")}
</QuietAction>
</div>
- </div>
+ )}
</div>
);
}
@@ -350,6 +284,11 @@ function KeysStep({ next, later, cheer }: { next: () => void; later: () => void;
}, []);
const withKey = providers.filter((p) => (p.secret_keys?.length ?? 0) > 0 && slotEffective(p));
+ // Live voice (talk and get an instant answer) needs a key one of the
+ // realtime starter plans runs on; any other key still runs chat and the
+ // classic voice (speech to text, answer read aloud).
+ const startableNow = startableProviders(providers);
+ const liveVoice = plans.some((p) => p.mode === "realtime" && planKeysComplete(p, startableNow));
const localBrain = providers.some((p) => p.tier === "brain" && p.active && (p.secret_keys?.length ?? 0) === 0);
const hasKey = withKey.length > 0 || localBrain;
@@ -401,6 +340,19 @@ function KeysStep({ next, later, cheer }: { next: () => void; later: () => void;
<Status tone="muted" testId="setup-keys-waiting">{t("first_run.keys.waiting")}</Status>
)}
{partial && <Status tone="warning">{fill(t("first_run.keys.partial"), { parts: partial })}</Status>}
+ {hasKey && !connecting && (
+ <Status tone={liveVoice ? "ok" : "muted"} testId="setup-keys-live">
+ {liveVoice ? t("first_run.keys.live_ready") : t("first_run.keys.live_missing")}
+ </Status>
+ )}
+ {!hasKey && (
+ <p className="text-xs leading-relaxed text-muted-foreground" data-testid="setup-keys-nokey">
+ {t("first_run.keys.no_key")}
+ </p>
+ )}
+ {hasKey && !connecting && (
+ <p className="text-xs leading-relaxed text-muted-foreground">{t("first_run.keys.next_hint")}</p>
+ )}
<p className="flex items-start gap-1.5 text-xs leading-relaxed text-muted-foreground">
<Lock aria-hidden className="mt-0.5 h-3 w-3 shrink-0" />
{t("first_run.keys.security")}
@@ -547,18 +499,15 @@ function ReviewRow({ label, value, ok }: { label: string; value: ReactNode; ok:
}
/**
- * What is set up, read back from the app itself, then the start. Completing
- * restarts the app once so every choice takes effect together; the tour of
- * the app follows the restart.
+ * What is set up, read back from the app itself, then on to the tour. The
+ * one restart that switches every choice on comes when the tour ends.
*/
-function ReadyStep({ onb, preview, onFinished }: { onb: Onb; preview: boolean; onFinished: () => void }) {
+function ReadyStep({ preview, onFinished }: { preview: boolean; onFinished: () => void }) {
const t = useT();
const { providers } = useProviders();
const { config } = useWakeWord();
const subscriptions = useConnectedSubscriptions(0);
const [autostart, setAutostart] = useState<{ enabled: boolean; supported: boolean } | null>(null);
- const [busy, setBusy] = useState(false);
- const [error, setError] = useState<string | null>(null);
useEffect(() => {
let cancelled = false;
@@ -589,22 +538,6 @@ function ReadyStep({ onb, preview, onFinished }: { onb: Onb; preview: boolean; o
}
}
- async function start() {
- if (busy) return;
- if (preview) {
- onFinished();
- return;
- }
- setBusy(true);
- setError(null);
- try {
- await onb.complete();
- } catch {
- setError(t("first_run.ready.start_failed"));
- setBusy(false);
- }
- }
-
const brain = providers.find((p) => p.tier === "brain" && p.active);
const brainOk = Boolean(brain && ((brain.secret_keys?.length ?? 0) === 0 || slotEffective(brain)));
const wakeOn = Boolean(config?.enabled && config.phrase.trim());
@@ -639,9 +572,8 @@ function ReadyStep({ onb, preview, onFinished }: { onb: Onb; preview: boolean; o
<p className="text-xs leading-relaxed text-muted-foreground">
{preview ? t("first_run.ready.preview_note") : t("first_run.ready.restart_note")}
</p>
- {error && <Status tone="error">{error}</Status>}
- <PrimaryAction onClick={() => void start()} busy={busy} testId="onboarding-start">
- {busy ? t("first_run.ready.starting") : t("first_run.ready.start")}
+ <PrimaryAction onClick={onFinished} testId="onboarding-start">
+ {t("first_run.ready.start")}
</PrimaryAction>
</div>
);
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 7f595b0393..8620ddb985 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, "..", "..", "..");
@@ -44,13 +45,27 @@ describe("setup steps", () => {
for (const id of SETUP_STEP_IDS) {
const anchor = SETUP_STEPS[id].anchor;
if (!anchor) continue;
- const literal = code.includes(`data-tour="${anchor}"`);
+ // A literal hook, or one handed to a component as its `tourId`.
+ const literal = code.includes(`data-tour="${anchor}"`) || code.includes(`tourId="${anchor}"`);
// Settings groups get theirs from a template: data-tour={`settings-${section.id}`}.
const group = anchor.startsWith("settings-") && code.includes("data-tour={`settings-${section.id}`}");
expect(literal || group, anchor).toBe(true);
}
});
+ 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("\n");
+ 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");
@@ -64,17 +79,13 @@ describe("setup steps", () => {
describe("resumeStep", () => {
const steps = stepsFor("win32");
- it("never skips the consent", () => {
- expect(resumeStep(steps, "voice", false)).toBe("welcome");
- });
-
- it("returns to the saved step once consent exists", () => {
- expect(resumeStep(steps, "voice", true)).toBe("voice");
+ it("returns to the saved step", () => {
+ expect(resumeStep(steps, "voice")).toBe("voice");
+ expect(resumeStep(steps, "subscriptions")).toBe("subscriptions");
});
- it("starts after the consent for an unknown or old step id", () => {
- expect(resumeStep(steps, "api-keys", true)).toBe("keys");
- expect(resumeStep(steps, null, true)).toBe("keys");
- expect(resumeStep(steps, "welcome", true)).toBe("keys");
+ it("starts at the welcome for a fresh run or an unknown, old step id", () => {
+ expect(resumeStep(steps, null)).toBe("welcome");
+ expect(resumeStep(steps, "api-keys")).toBe("welcome");
});
});
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 95ccc47a5f..0e454de337 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,12 +32,17 @@ 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",
section: "apikeys",
apiKeysTab: "subagents",
- anchor: "apikeys-page",
+ // The subscription rows themselves (Connect buttons), scrolled into view —
+ // the tab opens on model settings further up.
+ anchor: "apikeys-subscriptions",
+ scrollTo: true,
placement: "left",
width: 340,
},
@@ -71,14 +76,10 @@ export function stepsFor(platform: string | null): SetupStepId[] {
/**
* Where a resumed setup starts. The backend remembers the last step, so a
- * window reload lands where the user was — never past the consent.
+ * window reload lands where the user was; a fresh start (or an unknown, old
+ * step id) begins at the welcome.
*/
-export function resumeStep(
- steps: readonly SetupStepId[],
- saved: string | null,
- termsAccepted: boolean,
-): SetupStepId {
- if (!termsAccepted) return "welcome";
+export function resumeStep(steps: readonly SetupStepId[], saved: string | null): SetupStepId {
const hit = steps.find((id) => id === saved);
- return hit && hit !== "welcome" ? hit : (steps[1] ?? "welcome");
+ return hit ?? "welcome";
}
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..20bc96d2a8 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={96} 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/Spotlight.tsx b/jarvis/ui/web/frontend/src/components/onboarding/tour/Spotlight.tsx
index 9018fa185f..6fc80f79e4 100644
--- a/jarvis/ui/web/frontend/src/components/onboarding/tour/Spotlight.tsx
+++ b/jarvis/ui/web/frontend/src/components/onboarding/tour/Spotlight.tsx
@@ -6,6 +6,8 @@ import { EASE_OUT } from "../ui";
import { cutout, fitToView, padded, placeCard, type Rect, type TourPlacement } from "./tourSteps";
const CARD_W = 320;
+/** Narrowest a card may shrink to so it fits beside its element. */
+const MIN_SIDE_CARD_W = 240;
function useViewport(): { w: number; h: number } {
const [view, setView] = useState(() => ({ w: window.innerWidth, h: window.innerHeight }));
@@ -83,7 +85,14 @@ export function Spotlight({
// so the same clip-path shape still animates.
const point: Rect = { x: view.w / 2, y: view.h / 2, w: 0, h: 0 };
const clip = cutout(!settled ? whole : hole ?? point);
- const width = Math.min(cardWidth, view.w - 24);
+ // A card beside a big element (a whole settings page) must not lie over
+ // the part being set up: when the side it goes on is narrower than the
+ // card but still readable, the card narrows to fit there instead.
+ let width = Math.min(cardWidth, view.w - 24);
+ if (hole && (placement === "left" || placement === "right")) {
+ const room = placement === "left" ? hole.x - 14 - 12 : view.w - (hole.x + hole.w) - 14 - 12;
+ if (room < width && room >= MIN_SIDE_CARD_W) width = room;
+ }
const pos = placeCard(hole, placement, { w: width, h: cardH }, view);
const glide = reduced ? "none" : "clip-path 320ms cubic-bezier(0.22,1,0.36,1)";
const ringGlide = reduced
@@ -91,7 +100,15 @@ export function Spotlight({
: "transform 320ms cubic-bezier(0.22,1,0.36,1), width 320ms cubic-bezier(0.22,1,0.36,1), height 320ms cubic-bezier(0.22,1,0.36,1)";
return createPortal(
- <div className="pointer-events-none fixed inset-0 z-[110]" data-testid="tour-layer" {...{ [TOUR_LAYER_ATTR]: "" }}>
+ // aria-live keeps the guide reachable for assistive tech while a modal it
+ // points into (the Settings dialog) hides everything else from it — the
+ // modal's aria-hidden pass spares live regions.
+ <div
+ className="pointer-events-none fixed inset-0 z-[110]"
+ data-testid="tour-layer"
+ aria-live="polite"
+ {...{ [TOUR_LAYER_ATTR]: "" }}
+ >
<div
aria-hidden
className={blocking ? "pointer-events-auto absolute inset-0 bg-scrim/70" : "absolute inset-0 bg-scrim/60"}
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..351c868fa7 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: "thinking",
},
- { 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 bb38ea2a07..0139b46c7e 100644
--- a/jarvis/ui/web/frontend/src/i18n/locales/onboarding/de.json
+++ b/jarvis/ui/web/frontend/src/i18n/locales/onboarding/de.json
@@ -4,30 +4,43 @@
"continue": "Weiter",
"step_of": "{current} von {total}",
"welcome": {
+ "skip_all": "Einrichtung überspringen, ich kenne mich aus",
"title": "Willkommen",
- "lede": "Wir richten deinen Assistenten direkt hier in der App ein. Das dauert etwa zwei Minuten.",
+ "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",
- "fact_commands": "Er führt Befehle aus, öffnet Apps und ändert Dateien für dich.",
- "fact_screen": "Er kann deinen Bildschirm sehen und darauf handeln, wenn du ihn bittest.",
- "fact_cloud": "Was du sagst, geht an den KI-Anbieter, den du wählst.",
- "fact_costs": "Die Nutzung rechnet dieser Anbieter über dein Konto ab.",
- "fact_mistakes": "Er kann Fehler machen, auch solche, die schwer rückgängig zu machen sind.",
- "accept": "Ich habe das verstanden und nutze ihn auf eigenes Risiko.",
- "read_terms": "Die vollständigen Nutzungsbedingungen lesen",
- "hide_terms": "Nutzungsbedingungen ausblenden",
- "terms_loading": "Nutzungsbedingungen werden geladen…",
- "start": "Zustimmen und weiter",
- "decline": "Ablehnen und beenden",
- "accept_failed": "Deine Zustimmung konnte nicht gespeichert werden. Prüfe, ob die App läuft, und versuche es noch einmal.",
- "declined_title": "Die App wird geschlossen",
- "declined_body": "Du hast abgelehnt, also wurde nichts eingerichtet und nichts gespeichert. Starte die App jederzeit neu, dann fragt sie wieder."
+ "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": "Erklärung {current} von {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. Später nicht weiter? Frag einfach {name}. Jetzt geben wir ihm ein Gehirn."
+ }
},
"keys": {
+ "next_hint": "Als Nächstes: Verbinde die Abos, die du schon bezahlst, damit deine Agents arbeiten können.",
+ "no_key": "Noch kein Schlüssel? Ein kostenloses lokales Modell geht auch (Einstellungen → Lokale Modelle), oder überspring es und füg später einen hinzu. Ganz ohne bleiben Chat und Stimme aus.",
+ "live_missing": "Der Chat läuft. Für die Live-Stimme brauchst du einen OpenAI- oder Gemini-Schlüssel; bis dahin spricht {name} auf die klassische Art, etwas langsamer.",
+ "live_ready": "Die Live-Stimme ist an: Du sprichst, und {name} antwortet sofort.",
"title": "Einen API-Schlüssel eintragen",
- "lede": "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.",
+ "lede": "Das ist die Seite API-Schlüssel. Füg einen Schlüssel in eine Anbieter-Karte ein und speichere ihn; mehr braucht {name} nicht, um zu denken und zu sprechen. Ein OpenAI- (ChatGPT) oder Google-Gemini-Schlüssel bringt zusätzlich die Live-Stimme.",
"waiting": "Warte auf einen Schlüssel…",
"connecting": "Alles wird eingeschaltet…",
"connected": "Verbunden: {provider}.",
@@ -38,10 +51,10 @@
},
"subscriptions": {
"title": "Verbinde ein Abo für deine Agents",
- "lede": "Das ist der Agents-Tab. Melde dich mit einem Abo an, das du schon bezahlst. Wir empfehlen Claude (Pro oder Max) oder ChatGPT (Codex). Klick in der Zeile auf Connect; dein Browser öffnet sich einmal.",
+ "lede": "Das ist der Tab Agents. Agents laufen am besten mit einem Abo, das du schon bezahlst; wir empfehlen Claude (Pro oder Max) oder ChatGPT (Codex). Klick in seiner Zeile auf Verbinden, dein Browser öffnet sich einmal.",
"waiting": "Noch kein Abo verbunden…",
"connected": "Verbunden: {names}.",
- "why": "Ein Abo kostet einen festen Monatspreis. So rechnen die größeren Aufgaben deiner Agents nicht pro Aufruf über deinen API-Schlüssel ab.",
+ "why": "Ein Abo ist ein fester Monatspreis. Ohne Abo nutzen die Agents deinen API-Schlüssel, und jeder Auftrag wird einzeln abgerechnet.",
"later": "Ich verbinde später eins"
},
"permissions": {
@@ -58,7 +71,7 @@
},
"ready": {
"title": "Alles bereit",
- "lede": "Die App startet einmal neu, damit alles eingeschaltet ist. Danach zeigt dir eine kurze Tour die App.",
+ "lede": "Das ist eingerichtet. Als Nächstes zeigt dir eine kurze Tour die App.",
"row_brain": "Gehirn",
"row_agents": "Agents",
"row_voice": "Aktivierung",
@@ -67,11 +80,9 @@
"shortcut": "Anruf-Kürzel",
"autostart": "Bei der Anmeldung starten",
"no_key_note": "Ohne Schlüssel bleiben Chat und Sprache aus, bis du auf der Seite API-Keys einen einträgst.",
- "preview_note": "Das ist eine Wiederholung, deshalb startet nichts neu. Starten öffnet die Tour.",
- "restart_note": "Der Neustart dauert etwa zehn Sekunden.",
- "start_failed": "Die Einrichtung konnte nicht abgeschlossen werden. Prüfe, ob die App läuft, und versuche es noch einmal.",
- "starting": "Startet…",
- "start": "Starten"
+ "preview_note": "Das ist eine Wiederholung, deshalb startet nichts neu.",
+ "restart_note": "Nach der Tour startet die App einmal neu (etwa zehn Sekunden), damit alles eingeschaltet ist.",
+ "start": "Zeig mir die App"
}
},
"app_tour": {
@@ -80,20 +91,114 @@
"finish": "Fertig",
"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_title": "Onboarding nochmal machen",
+ "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."
+ "done": "Das war der Rundgang. Sprich mit {name}, wann immer du willst, und wenn du mal nicht weiterweißt, frag einfach {name}. Unter Einstellungen → App kannst du das Onboarding nochmal machen."
+ }
+ },
+ "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. Nicht weiter? Frag {name}.",
+ "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 3cdb994369..dadc8a0dcb 100644
--- a/jarvis/ui/web/frontend/src/i18n/locales/onboarding/en.json
+++ b/jarvis/ui/web/frontend/src/i18n/locales/onboarding/en.json
@@ -4,30 +4,43 @@
"continue": "Continue",
"step_of": "{current} of {total}",
"welcome": {
+ "skip_all": "Skip setup, I know my way around",
"title": "Welcome",
- "lede": "Let's set up your assistant right here in the app. It takes about two minutes.",
+ "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",
- "fact_commands": "It runs commands, opens apps and changes files for you.",
- "fact_screen": "It can see your screen and act on it when you ask.",
- "fact_cloud": "What you say goes to the AI provider you choose.",
- "fact_costs": "Usage is billed by that provider, on your account.",
- "fact_mistakes": "It can make mistakes, including ones that are hard to undo.",
- "accept": "I understand this and use it at my own risk.",
- "read_terms": "Read the full Terms of Use",
- "hide_terms": "Hide the Terms",
- "terms_loading": "Loading the Terms…",
- "start": "Agree and continue",
- "decline": "Decline and quit",
- "accept_failed": "Your agreement could not be saved. Check that the app is running, then try again.",
- "declined_title": "Closing the app",
- "declined_body": "You declined, so nothing was set up and nothing was saved. Start the app again anytime and it will ask again."
+ "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": "Explanation {current} of {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. Stuck later? Just ask {name}. Now let's give it a brain."
+ }
},
"keys": {
+ "next_hint": "Next: connect the subscriptions you already pay for, so your agents can work.",
+ "no_key": "No key yet? A free local model works too (Settings → Local models), or skip and add one later. Without any, chat and voice stay off.",
+ "live_missing": "Chat works. Live voice needs an OpenAI or Gemini key; until then {name} speaks the classic way, a little slower.",
+ "live_ready": "Live voice is on: talk, and {name} answers right away.",
"title": "Add one API key",
- "lede": "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.",
+ "lede": "This is the API Keys page. Paste one key into a provider card and save it; that is all {name} needs to think and talk. An OpenAI (ChatGPT) or Google Gemini key also gives you live voice.",
"waiting": "Waiting for a key…",
"connecting": "Switching everything on…",
"connected": "Connected: {provider}.",
@@ -38,10 +51,10 @@
},
"subscriptions": {
"title": "Connect a subscription for your agents",
- "lede": "This is the Agents tab. Sign in with a subscription you already pay for. We recommend Claude (Pro or Max) or ChatGPT (Codex). Click Connect on its row; your browser opens once.",
+ "lede": "This is the Agents tab. Agents run best on a subscription you already pay for; we recommend Claude (Pro or Max) or ChatGPT (Codex). Click Connect on its row, and your browser opens once.",
"waiting": "No subscription connected yet…",
"connected": "Connected: {names}.",
- "why": "A subscription is a flat monthly price, so your agents' bigger jobs do not bill your API key per call.",
+ "why": "A subscription is a flat monthly price. Without one, agents use your API key and each job is billed per use.",
"later": "I'll connect one later"
},
"permissions": {
@@ -58,7 +71,7 @@
},
"ready": {
"title": "All set",
- "lede": "The app restarts once to switch everything on. Then a short tour shows you around.",
+ "lede": "Here is what is set up. Next, a short tour shows you around the app.",
"row_brain": "Brain",
"row_agents": "Agents",
"row_voice": "Activation",
@@ -67,11 +80,9 @@
"shortcut": "Call shortcut",
"autostart": "Start at login",
"no_key_note": "Without a key, chat and voice stay off until you add one on the API Keys page.",
- "preview_note": "This is a replay, so nothing restarts. Start opens the tour.",
- "restart_note": "The restart takes about ten seconds.",
- "start_failed": "Setup could not be finished. Check that the app is running, then try again.",
- "starting": "Starting…",
- "start": "Start"
+ "preview_note": "This is a replay, so nothing restarts.",
+ "restart_note": "When the tour ends, the app restarts once (about ten seconds) to switch everything on.",
+ "start": "Show me around"
}
},
"app_tour": {
@@ -80,20 +91,114 @@
"finish": "Finish",
"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_title": "Do the onboarding again",
+ "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."
+ "done": "That's the tour. Talk to {name} whenever you like, and if you're ever stuck, just ask {name}. Settings → App runs the onboarding again."
+ }
+ },
+ "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. Stuck? Ask {name}.",
+ "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 0e3cca9126..fd6603ebd5 100644
--- a/jarvis/ui/web/frontend/src/i18n/locales/onboarding/es.json
+++ b/jarvis/ui/web/frontend/src/i18n/locales/onboarding/es.json
@@ -4,30 +4,43 @@
"continue": "Continuar",
"step_of": "{current} de {total}",
"welcome": {
+ "skip_all": "Saltar la configuración, ya me oriento",
"title": "Bienvenido",
- "lede": "Configuramos tu asistente aquí mismo, en la aplicación. Tarda unos dos minutos.",
+ "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",
- "fact_commands": "Ejecuta comandos, abre aplicaciones y cambia archivos por ti.",
- "fact_screen": "Puede ver tu pantalla y actuar sobre ella cuando se lo pidas.",
- "fact_cloud": "Lo que dices va al proveedor de IA que elijas.",
- "fact_costs": "Ese proveedor cobra el uso en tu cuenta.",
- "fact_mistakes": "Puede equivocarse, también de formas difíciles de deshacer.",
- "accept": "Lo entiendo y lo uso bajo mi propia responsabilidad.",
- "read_terms": "Leer las condiciones de uso completas",
- "hide_terms": "Ocultar las condiciones",
- "terms_loading": "Cargando las condiciones…",
- "start": "Aceptar y continuar",
- "decline": "Rechazar y salir",
- "accept_failed": "No se pudo guardar tu aceptación. Comprueba que la aplicación está en marcha y vuelve a intentarlo.",
- "declined_title": "Cerrando la aplicación",
- "declined_body": "Has rechazado, así que no se configuró ni se guardó nada. Abre la aplicación cuando quieras y volverá a preguntar."
+ "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": "Explicación {current} de {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. ¿Te atascas luego? Pregúntale a {name}. Ahora démosle un cerebro."
+ }
},
"keys": {
+ "next_hint": "Siguiente: conecta las suscripciones que ya pagas para que tus agentes puedan trabajar.",
+ "no_key": "¿Aún sin clave? También sirve un modelo local gratuito (Ajustes → Modelos locales), o sáltalo y añade una más tarde. Sin ninguna, el chat y la voz quedan apagados.",
+ "live_missing": "El chat funciona. La voz en directo necesita una clave de OpenAI o Gemini; mientras tanto {name} habla de la forma clásica, algo más lenta.",
+ "live_ready": "La voz en directo está activa: hablas y {name} responde al instante.",
"title": "Añade una clave de API",
- "lede": "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.",
+ "lede": "Esta es la página de claves de API. Pega una clave en la tarjeta de un proveedor y guárdala; es todo lo que {name} necesita para pensar y hablar. Una clave de OpenAI (ChatGPT) o de Google Gemini también te da la voz en directo.",
"waiting": "Esperando una clave…",
"connecting": "Activando todo…",
"connected": "Conectado: {provider}.",
@@ -38,10 +51,10 @@
},
"subscriptions": {
"title": "Conecta una suscripción para tus agentes",
- "lede": "Esta es la pestaña Agentes. Inicia sesión con una suscripción que ya pagas. Te recomendamos Claude (Pro o Max) o ChatGPT (Codex). Pulsa Connect en su fila; tu navegador se abre una vez.",
+ "lede": "Esta es la pestaña Agentes. Los agentes funcionan mejor con una suscripción que ya pagas; recomendamos Claude (Pro o Max) o ChatGPT (Codex). Pulsa Conectar en su fila y tu navegador se abre una vez.",
"waiting": "Aún no hay ninguna suscripción conectada…",
"connected": "Conectado: {names}.",
- "why": "Una suscripción tiene un precio mensual fijo, así las tareas grandes de tus agentes no se cobran por llamada a tu clave de API.",
+ "why": "Una suscripción es un precio mensual fijo. Sin ella, los agentes usan tu clave de API y cada encargo se cobra por uso.",
"later": "Conectaré una más tarde"
},
"permissions": {
@@ -58,7 +71,7 @@
},
"ready": {
"title": "Todo listo",
- "lede": "La aplicación se reinicia una vez para activarlo todo. Después, una breve visita te enseña la aplicación.",
+ "lede": "Esto es lo que está configurado. Ahora, una breve visita te enseña la aplicación.",
"row_brain": "Cerebro",
"row_agents": "Agentes",
"row_voice": "Activación",
@@ -67,11 +80,9 @@
"shortcut": "Atajo de llamada",
"autostart": "Iniciar al entrar en la sesión",
"no_key_note": "Sin clave, el chat y la voz siguen apagados hasta que añadas una en la página Claves API.",
- "preview_note": "Esto es una repetición, así que no se reinicia nada. Empezar abre la visita.",
- "restart_note": "El reinicio tarda unos diez segundos.",
- "start_failed": "No se pudo terminar la configuración. Comprueba que la aplicación está en marcha y vuelve a intentarlo.",
- "starting": "Iniciando…",
- "start": "Empezar"
+ "preview_note": "Esto es una repetición, así que no se reinicia nada.",
+ "restart_note": "Al terminar la visita, la aplicación se reinicia una vez (unos diez segundos) para activarlo todo.",
+ "start": "Enséñame la aplicación"
}
},
"app_tour": {
@@ -80,20 +91,114 @@
"finish": "Terminar",
"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_title": "Hacer el onboarding de nuevo",
+ "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."
+ "done": "Esa fue la visita. Habla con {name} cuando quieras, y si alguna vez te atascas, pregúntale a {name}. En Ajustes → Aplicación puedes repetir el onboarding."
+ }
+ },
+ "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. ¿Atascado? Pregúntale a {name}.",
+ "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")