From 76805a9a77686114fdd2fdd7b4df1578ae7c46d0 Mon Sep 17 00:00:00 2001
From: "Julia.Shilova" <Julia.Shilova@MacBook-Pro-5.local>
Date: Mon, 24 Aug 2026 20:19:06 +0300
Subject: [PATCH 01/23] build(cli): bundle To Do App demo template + embed it
 in the binary

Adds packages/server/assets/demo/to-do-app (a tiny, dependency-free
working to-do app) and embeds it into the single-file binary via a new
demo-assets manifest, staged on boot to THINKRAIL_DEMO_DIR (mirrors the
web/skills/runtime asset pipeline). No consumer yet.
---
 apps/cli/SPEC.md                              | 13 ++-
 apps/cli/scripts/build-binary.ts              | 16 ++++
 apps/cli/src/compiled-entry.ts                |  3 +
 apps/cli/src/demo-assets.generated.d.ts       | 16 ++++
 biome.json                                    |  8 +-
 .../server/assets/demo/to-do-app/README.md    | 23 +++++
 .../server/assets/demo/to-do-app/index.html   | 28 ++++++
 .../server/assets/demo/to-do-app/src/app.js   | 67 ++++++++++++++
 .../assets/demo/to-do-app/src/storage.js      | 15 ++++
 .../server/assets/demo/to-do-app/styles.css   | 89 +++++++++++++++++++
 10 files changed, 273 insertions(+), 5 deletions(-)
 create mode 100644 apps/cli/src/demo-assets.generated.d.ts
 create mode 100644 packages/server/assets/demo/to-do-app/README.md
 create mode 100644 packages/server/assets/demo/to-do-app/index.html
 create mode 100644 packages/server/assets/demo/to-do-app/src/app.js
 create mode 100644 packages/server/assets/demo/to-do-app/src/storage.js
 create mode 100644 packages/server/assets/demo/to-do-app/styles.css

diff --git a/apps/cli/SPEC.md b/apps/cli/SPEC.md
index c54d55c4c..079e4b506 100644
--- a/apps/cli/SPEC.md
+++ b/apps/cli/SPEC.md
@@ -161,9 +161,10 @@ entrypoint honors it (including `packages/server/src/dev.ts`, which parses no ar
 platform — via `bun build --compile`. Bun bundles the host *and* transparently embeds the `bun-pty` native
 lib; the extra steps are the **web UI** (a directory the host normally serves), the **bundled pi
 extensions** (which the server path-loads out of `node_modules` in dev — impossible inside a binary),
-and `trash`'s **native helper sidecars** (which macOS/Windows must execute from real filesystem paths):
+`trash`'s **native helper sidecars** (which macOS/Windows must execute from real filesystem paths), and
+the **bundled demo project templates** (which the server copies out of `packages/server/assets` in dev):
 
-- `scripts/build-binary.ts` writes three **transient** generated modules, runs
+- `scripts/build-binary.ts` writes four **transient** generated modules, runs
   `bun build --compile --no-compile-autoload-bunfig --target=<host|--target>` on
   `src/compiled-entry.ts`, then deletes them (so the artifact cannot execute a project-local
   `bunfig.toml` preload before ThinkRail boots, and the working tree + `tsc` stay clean); each generated
@@ -181,12 +182,16 @@ and `trash`'s **native helper sidecars** (which macOS/Windows must execute from
     `@earendil-works/pi-coding-agent`.
   - `src/runtime-assets.generated.ts` — embeds `trash`'s `macos-trash` and `windows-trash.exe` helper
     binaries, resolved from the server package's dependency context, as a content-hashed manifest.
+  - `src/demo-assets.generated.ts` — enumerates `packages/server/assets/demo` (the bundled demo project
+    templates, e.g. `to-do-app/…`): a Bun file-attribute import per file + a `{ route, data }[]` manifest
+    + a content-hash version, embedded like web assets.
 - `src/compiled-entry.ts` is the binary's entry: on startup it stages the embedded web + skills +
-  runtime-helper files to per-build cache dirs (`$XDG_CACHE_HOME`/`~/.cache`/temp; files written straight into the versioned dir,
+  runtime-helper + demo-template files to per-build cache dirs (`$XDG_CACHE_HOME`/`~/.cache`/temp; files written straight into the versioned dir,
   then a sibling `<dir>.complete` marker written **last** — readiness is gated on the marker, so a killed
   first run leaves an incomplete cache that's re-extracted next launch. **No stage-then-rename**: Bun's
   `renameSync` of a fresh non-empty dir `EPERM`s on Windows, so the marker replaces the directory-rename
-  publish), makes the macOS helper executable, sets `THINKRAIL_STATIC_DIR`, then **awaits** the server's
+  publish), makes the macOS helper executable, sets `THINKRAIL_STATIC_DIR` and `THINKRAIL_DEMO_DIR` (the
+  staged demo-template root the server materializes lazily from), then **awaits** the server's
   **`registerBundledRuntime`** seam — which injects the factories + staged skills dir + real trash-helper
   paths **and** performs pi's binary-only registrations (the
   statically-bundled OAuth flows + the Bedrock provider module, replacing pi's binary-hostile dynamic
diff --git a/apps/cli/scripts/build-binary.ts b/apps/cli/scripts/build-binary.ts
index 708d7e087..40a7fdff5 100644
--- a/apps/cli/scripts/build-binary.ts
+++ b/apps/cli/scripts/build-binary.ts
@@ -20,6 +20,8 @@ const webDist = join(repoRoot, "apps", "web", "dist");
 const webGeneratedPath = join(cliDir, "src", "web-assets.generated.ts");
 const extGeneratedPath = join(cliDir, "src", "bundled-extensions.generated.ts");
 const runtimeGeneratedPath = join(cliDir, "src", "runtime-assets.generated.ts");
+const demoGeneratedPath = join(cliDir, "src", "demo-assets.generated.ts");
+const demoDir = join(repoRoot, "packages", "server", "assets", "demo");
 const entryPath = join(cliDir, "src", "compiled-entry.ts");
 const outDir = join(cliDir, "dist");
 const serverRequire = createRequire(join(repoRoot, "packages", "server", "package.json"));
@@ -105,6 +107,18 @@ function generateRuntimeManifest(): void {
 	);
 }
 
+function generateDemoManifest(): void {
+	if (!existsSync(demoDir)) throw new Error(`demo assets not found at ${demoDir}`);
+	const files = listFiles(demoDir)
+		.sort()
+		.map((file) => ({ root: demoDir, file }));
+	const { imports, entries, version } = embedFiles(files, "d");
+	writeFileSync(
+		demoGeneratedPath,
+		`// GENERATED by scripts/build-binary.ts — do not edit. Embeds the bundled demo project templates.\n${imports.join("\n")}\n\nexport const demoAssetsVersion = ${JSON.stringify(version)};\nexport const embeddedDemoAssets = [\n${entries.join("\n")}\n];\n`,
+	);
+}
+
 const target = process.argv.find((a) => a.startsWith("--target="))?.slice("--target=".length);
 const outFile = join(outDir, binaryArtifactName(target));
 
@@ -112,6 +126,7 @@ mkdirSync(outDir, { recursive: true });
 generateWebManifest();
 generateBundledExtensions();
 generateRuntimeManifest();
+generateDemoManifest();
 try {
 	const proc = Bun.spawnSync(
 		[
@@ -131,5 +146,6 @@ try {
 	rmSync(webGeneratedPath, { force: true });
 	rmSync(extGeneratedPath, { force: true });
 	rmSync(runtimeGeneratedPath, { force: true });
+	rmSync(demoGeneratedPath, { force: true });
 }
 console.log(`\nBuilt single-file binary: ${outFile}`);
diff --git a/apps/cli/src/compiled-entry.ts b/apps/cli/src/compiled-entry.ts
index 6b551490b..9efd9c65b 100644
--- a/apps/cli/src/compiled-entry.ts
+++ b/apps/cli/src/compiled-entry.ts
@@ -8,6 +8,7 @@ import {
 	bundledSkillsVersion,
 	embeddedSkillFiles,
 } from "./bundled-extensions.generated";
+import { demoAssetsVersion, embeddedDemoAssets } from "./demo-assets.generated";
 import { stagingRoot } from "./paths";
 import { embeddedRuntimeAssets, runtimeAssetsVersion } from "./runtime-assets.generated";
 import { embeddedWebAssets, webAssetsVersion } from "./web-assets.generated";
@@ -35,6 +36,8 @@ if (parseSubcommand(Bun.argv.slice(2)) === undefined) {
 	const staticDir = await stage("web", webAssetsVersion, embeddedWebAssets);
 	const skillsDir = await stage("skills", bundledSkillsVersion, embeddedSkillFiles);
 	const runtimeDir = await stage("runtime", runtimeAssetsVersion, embeddedRuntimeAssets);
+	const demoDir = await stage("demo", demoAssetsVersion, embeddedDemoAssets);
+	process.env.THINKRAIL_DEMO_DIR ??= demoDir;
 	const macosTrash = join(runtimeDir, "macos-trash");
 	const windowsTrash = join(runtimeDir, "windows-trash.exe");
 	if (process.platform !== "win32") chmodSync(macosTrash, 0o755);
diff --git a/apps/cli/src/demo-assets.generated.d.ts b/apps/cli/src/demo-assets.generated.d.ts
new file mode 100644
index 000000000..c4618e9d8
--- /dev/null
+++ b/apps/cli/src/demo-assets.generated.d.ts
@@ -0,0 +1,16 @@
+// Type contract for the build-time-generated demo-assets module (`src/demo-assets.generated.ts`), which
+// `bun run build:binary` writes just before `bun build --compile` and deletes afterward. This committed
+// declaration keeps `compiled-entry.ts` typecheckable while the generated source is absent.
+
+export interface EmbeddedDemoAsset {
+	/** Path relative to the staged demo root, posix-style — e.g. `to-do-app/index.html`. */
+	route: string;
+	/** Embedded-file path (a Bun `import … with { type: "file" }`), readable at runtime via `Bun.file`. */
+	data: string;
+}
+
+/** Every file under the bundled demo project templates, embedded into the single-file binary. */
+export declare const embeddedDemoAssets: EmbeddedDemoAsset[];
+
+/** Content hash of the embedded demo templates — keys the on-disk staging dir so a new build re-extracts. */
+export declare const demoAssetsVersion: string;
diff --git a/biome.json b/biome.json
index 1af30c8ad..c4743a775 100644
--- a/biome.json
+++ b/biome.json
@@ -7,7 +7,13 @@
 	},
 	"files": {
 		"ignoreUnknown": true,
-		"includes": ["**", "!designs", "!**/.claude", "!apps/web/src/styles/generated"]
+		"includes": [
+			"**",
+			"!designs",
+			"!**/.claude",
+			"!apps/web/src/styles/generated",
+			"!packages/server/assets"
+		]
 	},
 	"formatter": {
 		"enabled": true,
diff --git a/packages/server/assets/demo/to-do-app/README.md b/packages/server/assets/demo/to-do-app/README.md
new file mode 100644
index 000000000..52eb5ba2e
--- /dev/null
+++ b/packages/server/assets/demo/to-do-app/README.md
@@ -0,0 +1,23 @@
+# To Do App
+
+A tiny, dependency-free to-do list you open straight in the browser — the bundled ThinkRail demo
+project. It is a real git repository once opened, so you can cut isolated workspaces from it and pair
+with the agent on real changes.
+
+## Run it
+
+Open `index.html` in a browser. Tasks persist in `localStorage`.
+
+## Layout
+
+- `index.html` — the page shell.
+- `styles.css` — presentation only.
+- `src/storage.js` — load/save the task list (localStorage).
+- `src/app.js` — rendering + add/toggle/delete wiring.
+
+## Try an onboarding task
+
+Cut a workspace and ask the agent to:
+
+- **Add search functionality** — filter the visible tasks by a text query.
+- **Add a filter for completed tasks** — show all / active / completed.
diff --git a/packages/server/assets/demo/to-do-app/index.html b/packages/server/assets/demo/to-do-app/index.html
new file mode 100644
index 000000000..8806c77dd
--- /dev/null
+++ b/packages/server/assets/demo/to-do-app/index.html
@@ -0,0 +1,28 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<title>To Do App</title>
+		<link rel="stylesheet" href="styles.css" />
+	</head>
+	<body>
+		<main class="app">
+			<h1>To Do</h1>
+			<form id="new-task" class="new-task" autocomplete="off">
+				<input
+					id="new-task-input"
+					class="new-task__input"
+					type="text"
+					name="title"
+					placeholder="Add a task…"
+					aria-label="Task title"
+				/>
+				<button class="new-task__add" type="submit">Add</button>
+			</form>
+			<ul id="task-list" class="task-list"></ul>
+			<p id="empty" class="empty" hidden>Nothing to do yet.</p>
+		</main>
+		<script type="module" src="src/app.js"></script>
+	</body>
+</html>
diff --git a/packages/server/assets/demo/to-do-app/src/app.js b/packages/server/assets/demo/to-do-app/src/app.js
new file mode 100644
index 000000000..46e0d78db
--- /dev/null
+++ b/packages/server/assets/demo/to-do-app/src/app.js
@@ -0,0 +1,67 @@
+import { loadTasks, saveTasks } from "./storage.js";
+
+const listEl = document.getElementById("task-list");
+const emptyEl = document.getElementById("empty");
+const formEl = document.getElementById("new-task");
+const inputEl = document.getElementById("new-task-input");
+
+let tasks = loadTasks();
+
+function persist() {
+	saveTasks(tasks);
+	render();
+}
+
+function addTask(title) {
+	const trimmed = title.trim();
+	if (!trimmed) return;
+	tasks = [...tasks, { id: crypto.randomUUID(), title: trimmed, done: false }];
+	persist();
+}
+
+function toggleTask(id) {
+	tasks = tasks.map((task) => (task.id === id ? { ...task, done: !task.done } : task));
+	persist();
+}
+
+function deleteTask(id) {
+	tasks = tasks.filter((task) => task.id !== id);
+	persist();
+}
+
+function render() {
+	listEl.replaceChildren();
+	for (const task of tasks) {
+		const item = document.createElement("li");
+		item.className = task.done ? "task task--done" : "task";
+
+		const checkbox = document.createElement("input");
+		checkbox.type = "checkbox";
+		checkbox.checked = task.done;
+		checkbox.addEventListener("change", () => toggleTask(task.id));
+
+		const title = document.createElement("span");
+		title.className = "task__title";
+		title.textContent = task.title;
+
+		const remove = document.createElement("button");
+		remove.type = "button";
+		remove.className = "task__delete";
+		remove.textContent = "✕";
+		remove.setAttribute("aria-label", `Delete ${task.title}`);
+		remove.addEventListener("click", () => deleteTask(task.id));
+
+		item.append(checkbox, title, remove);
+		listEl.append(item);
+	}
+	emptyEl.hidden = tasks.length > 0;
+}
+
+formEl.addEventListener("submit", (event) => {
+	event.preventDefault();
+	addTask(inputEl.value);
+	inputEl.value = "";
+	inputEl.focus();
+});
+
+render();
diff --git a/packages/server/assets/demo/to-do-app/src/storage.js b/packages/server/assets/demo/to-do-app/src/storage.js
new file mode 100644
index 000000000..042dc28a1
--- /dev/null
+++ b/packages/server/assets/demo/to-do-app/src/storage.js
@@ -0,0 +1,15 @@
+const STORAGE_KEY = "thinkrail-todo-app";
+
+export function loadTasks() {
+	try {
+		const raw = localStorage.getItem(STORAGE_KEY);
+		const parsed = raw ? JSON.parse(raw) : [];
+		return Array.isArray(parsed) ? parsed : [];
+	} catch {
+		return [];
+	}
+}
+
+export function saveTasks(tasks) {
+	localStorage.setItem(STORAGE_KEY, JSON.stringify(tasks));
+}
diff --git a/packages/server/assets/demo/to-do-app/styles.css b/packages/server/assets/demo/to-do-app/styles.css
new file mode 100644
index 000000000..1865ffac0
--- /dev/null
+++ b/packages/server/assets/demo/to-do-app/styles.css
@@ -0,0 +1,89 @@
+:root {
+	color-scheme: light dark;
+	font-family: system-ui, sans-serif;
+}
+
+body {
+	margin: 0;
+	display: flex;
+	justify-content: center;
+	background: Canvas;
+	color: CanvasText;
+}
+
+.app {
+	width: 100%;
+	max-width: 32rem;
+	padding: 2rem 1rem;
+}
+
+h1 {
+	margin: 0 0 1rem;
+	font-size: 1.75rem;
+}
+
+.new-task {
+	display: flex;
+	gap: 0.5rem;
+	margin-bottom: 1rem;
+}
+
+.new-task__input {
+	flex: 1;
+	padding: 0.5rem 0.75rem;
+	font: inherit;
+	border: 1px solid GrayText;
+	border-radius: 0.5rem;
+	background: Field;
+	color: FieldText;
+}
+
+.new-task__add {
+	padding: 0.5rem 1rem;
+	font: inherit;
+	border: 0;
+	border-radius: 0.5rem;
+	background: Highlight;
+	color: HighlightText;
+	cursor: pointer;
+}
+
+.task-list {
+	list-style: none;
+	margin: 0;
+	padding: 0;
+	display: flex;
+	flex-direction: column;
+	gap: 0.25rem;
+}
+
+.task {
+	display: flex;
+	align-items: center;
+	gap: 0.5rem;
+	padding: 0.5rem 0.25rem;
+	border-bottom: 1px solid ButtonBorder;
+}
+
+.task__title {
+	flex: 1;
+}
+
+.task--done .task__title {
+	text-decoration: line-through;
+	opacity: 0.6;
+}
+
+.task__delete {
+	border: 0;
+	background: transparent;
+	color: GrayText;
+	cursor: pointer;
+	font-size: 1rem;
+}
+
+.empty {
+	color: GrayText;
+	text-align: center;
+	margin-top: 2rem;
+}

From b2e346c337e5d8efb8f1857a50886fac4270d2c9 Mon Sep 17 00:00:00 2001
From: "Julia.Shilova" <Julia.Shilova@MacBook-Pro-5.local>
Date: Mon, 24 Aug 2026 20:21:59 +0300
Subject: [PATCH 02/23] =?UTF-8?q?feat(server):=20demo=20module=20=E2=80=94?=
 =?UTF-8?q?=20lazily=20materialize=20the=20To=20Do=20App=20demo=20as=20a?=
 =?UTF-8?q?=20real=20repo?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds packages/server/src/demo: ensureDemoProject() copies the bundled
template into dataDir/demo/to-do-app (never mutating the source) and
hands off to the existing initProject (git init + open); idempotent.
removeDemoFiles() is the file half of reset. Adds deleteProject() to the
projects module for the record half. Specs + unit tests included.
---
 packages/server/SPEC.md                  |  4 +-
 packages/server/src/demo/SPEC.md         | 43 ++++++++++++++++++
 packages/server/src/demo/demo.test.ts    | 57 ++++++++++++++++++++++++
 packages/server/src/demo/demo.ts         | 30 +++++++++++++
 packages/server/src/demo/index.ts        |  1 +
 packages/server/src/projects/SPEC.md     |  2 +-
 packages/server/src/projects/projects.ts |  9 ++++
 7 files changed, 144 insertions(+), 2 deletions(-)
 create mode 100644 packages/server/src/demo/SPEC.md
 create mode 100644 packages/server/src/demo/demo.test.ts
 create mode 100644 packages/server/src/demo/demo.ts
 create mode 100644 packages/server/src/demo/index.ts

diff --git a/packages/server/SPEC.md b/packages/server/SPEC.md
index 23560b62f..2a1718a7a 100644
--- a/packages/server/SPEC.md
+++ b/packages/server/SPEC.md
@@ -54,6 +54,7 @@ internals**. The edges between them are owned here (see the dependency graph), n
 | `settings` | server-synced app config, including layout preset/default/side-limit settings | [settings/SPEC.md](src/settings/SPEC.md) |
 | `layout` | validated, revisioned, persisted per-workspace workbench snapshots | [layout/SPEC.md](src/layout/SPEC.md) |
 | `projects` | stable known-repo registry: open/recent views + lossless close/reopen (validate, dedupe, slug) | [projects/SPEC.md](src/projects/SPEC.md) |
+| `demo` | materialize the bundled To Do App demo as a real user-owned repo (lazy copy + `git init`) | [demo/SPEC.md](src/demo/SPEC.md) |
 | `workspaces` | workspaces = `git worktree`s on their own branch | [workspaces/SPEC.md](src/workspaces/SPEC.md) |
 | `git` | the `git(cwd, args)` runner + worktree status/diff vs base + branch list | [git/SPEC.md](src/git/SPEC.md) |
 | `github` | read-only local `gh` auth status (shell-out) for the New-Workspace surface | [github/SPEC.md](src/github/SPEC.md) |
@@ -80,10 +81,11 @@ the host from env via `bootHost` for dev/e2e.
 
 `host` is the **only composition root** — it wires each feature's handlers into the WS registry.
 
-- `host` → `projects`, `workspaces`, `git`, `github`, `branch-review`, `fs`, `spec`, `todos`, `reviews`, `watch`, `terminal`, `dialog`, `editors`, `agent`, `auth`, `assist`, `settings`, `layout`, `history`, `templates`, `analytics`, `persistence` (`dataDir`, for the crash report)
+- `host` → `projects`, `demo`, `workspaces`, `git`, `github`, `branch-review`, `fs`, `spec`, `todos`, `reviews`, `watch`, `terminal`, `dialog`, `editors`, `agent`, `auth`, `assist`, `settings`, `layout`, `history`, `templates`, `analytics`, `persistence` (`dataDir`, for the crash report)
 - `workspaces` → `projects`, `git`, `persistence`
 - `branch-review` → `git`
 - `projects` → `git` (shared runner), `persistence`
+- `demo` → `projects` (`initProject`), `persistence` (`dataDir`)
 - `git`, `fs`, `spec`, `watch`, `terminal`, `settings`, `layout`, `analytics` → `persistence` (`spec` also → `pi-spec-graph/core`, external; `analytics` also → the pi-ai built-in provider/model catalog + `posthog-node`, external — the identity-bucketing vocabulary and the delivery SDK)
 - `todos` → `workspaces` (worktree path lookup) + `pi-todos/core` (external, value-imported, pi-free)
 - `reviews` → `workspaces` (worktree path lookup), `persistence` (data dir), `git` (the review's baseSha
diff --git a/packages/server/src/demo/SPEC.md b/packages/server/src/demo/SPEC.md
new file mode 100644
index 000000000..aadc1dc4d
--- /dev/null
+++ b/packages/server/src/demo/SPEC.md
@@ -0,0 +1,43 @@
+---
+id: submodule-server-demo
+type: submodule-design
+status: active
+title: demo — bundled demo project
+parent: module-server
+depends-on: [module-contracts, submodule-server-projects]
+tags: [v1]
+---
+
+## Responsibility
+
+Materialize the bundled **To Do App** demo as a real, user-owned git repository so first-run onboarding
+needs no repo of the user's own. The demo is a **normal Project** the moment it exists — it participates
+in the ordinary Project → Workspace → git-worktree flow with no separate/fake project model — so this
+module only owns the *materialization* (copy template + `git init`) and *file cleanup*; opening,
+workspaces, sessions, and worktrees are the existing modules' jobs, unchanged.
+
+**Lazy, never eager.** The copy happens only when the user explicitly starts the demo (the `demo.ensure`
+wire door), never at host startup.
+
+## Boundary
+
+- **Owns:**
+  - `demoProjectPath()` — the fixed user-local location `dataDir()/demo/to-do-app` (honours
+    `THINKRAIL_DATA_DIR`). Deliberately **not** under `dataDir()/worktrees` — that tree is reserved for
+    managed worktree dirs keyed by project slug ([[submodule-server-workspaces]]).
+  - `ensureDemoProject()` — idempotent: when the target is absent, copy the bundled template into it
+    (never mutating the bundled source), then hand off to `initProject` (git init + initial commit, or a
+    short-circuit `openProject` when the repo already exists). Returns the `Project`. A second call
+    re-opens the existing record rather than re-initialising.
+  - `removeDemoFiles()` — `rm -rf` the user-local copy. The *domain* half of a reset (archiving the
+    demo's workspaces + dropping the project record via `deleteProject`) is orchestrated by `host`, which
+    can reach the per-workspace teardown seams this module must not (terminals, spec index, reviews,
+    watch, layout).
+  - Template source resolution: `THINKRAIL_DEMO_DIR` (the staged root the binary sets — see the CLI
+    SPEC) when present, else the in-repo dev path `packages/server/assets/demo`. Both point at the parent
+    that contains `to-do-app/`.
+- **Public surface (barrel):** `demoProjectPath`, `ensureDemoProject`, `removeDemoFiles`, `DEMO_APP_DIR`.
+- **Allowed deps:** `projects` (`initProject`); `persistence` (`dataDir`); `contracts` (`Project`);
+  Node/Bun.
+- **Forbidden:** `host`; sibling features other than `projects` (no `workspaces`/`agent`/`terminal`
+  reach — reset orchestration lives in `host`); mutating the bundled template under `packages/server/assets`.
diff --git a/packages/server/src/demo/demo.test.ts b/packages/server/src/demo/demo.test.ts
new file mode 100644
index 000000000..70738df33
--- /dev/null
+++ b/packages/server/src/demo/demo.test.ts
@@ -0,0 +1,57 @@
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { listProjects, setProjectPublisher } from "../projects";
+import { DEMO_APP_DIR, demoProjectPath, ensureDemoProject, removeDemoFiles } from "./demo";
+
+function gitOut(cwd: string, ...args: string[]): string {
+	const r = Bun.spawnSync(["git", "-C", cwd, ...args], { stdout: "pipe", stderr: "ignore" });
+	return new TextDecoder().decode(r.stdout).trim();
+}
+
+let dataDir: string;
+const savedDataDir = process.env.THINKRAIL_DATA_DIR;
+
+beforeEach(() => {
+	dataDir = mkdtempSync(join(tmpdir(), "trpi-demo-test-"));
+	process.env.THINKRAIL_DATA_DIR = dataDir;
+});
+
+afterEach(() => {
+	setProjectPublisher(null);
+	rmSync(dataDir, { recursive: true, force: true });
+	if (savedDataDir === undefined) delete process.env.THINKRAIL_DATA_DIR;
+	else process.env.THINKRAIL_DATA_DIR = savedDataDir;
+});
+
+test("demoProjectPath is dataDir/demo/to-do-app, never under worktrees", () => {
+	expect(demoProjectPath()).toBe(join(dataDir, "demo", DEMO_APP_DIR));
+});
+
+test("ensureDemoProject copies the template, inits a real repo, and opens it", () => {
+	const project = ensureDemoProject();
+
+	expect(project.path).toBe(realpathSync(demoProjectPath()));
+	expect(existsSync(join(demoProjectPath(), "index.html"))).toBe(true);
+	expect(existsSync(join(demoProjectPath(), "src", "app.js"))).toBe(true);
+	expect(gitOut(demoProjectPath(), "rev-parse", "HEAD")).not.toBe("");
+	expect(gitOut(demoProjectPath(), "ls-tree", "-r", "HEAD", "--name-only")).toContain("index.html");
+	expect(listProjects().map((p) => p.id)).toEqual([project.id]);
+});
+
+test("ensureDemoProject is idempotent — a second call reopens the same project", () => {
+	const first = ensureDemoProject();
+	const second = ensureDemoProject();
+
+	expect(second.id).toBe(first.id);
+	expect(listProjects()).toHaveLength(1);
+});
+
+test("removeDemoFiles deletes the user-local copy", () => {
+	ensureDemoProject();
+	expect(existsSync(demoProjectPath())).toBe(true);
+
+	removeDemoFiles();
+	expect(existsSync(demoProjectPath())).toBe(false);
+});
diff --git a/packages/server/src/demo/demo.ts b/packages/server/src/demo/demo.ts
new file mode 100644
index 000000000..df81829eb
--- /dev/null
+++ b/packages/server/src/demo/demo.ts
@@ -0,0 +1,30 @@
+import { cpSync, existsSync, mkdirSync, rmSync } from "node:fs";
+import { join, resolve } from "node:path";
+import type { Project } from "@thinkrail/contracts";
+import { dataDir } from "../persistence";
+import { initProject } from "../projects";
+
+export const DEMO_APP_DIR = "to-do-app";
+
+function templateRoot(): string {
+	return process.env.THINKRAIL_DEMO_DIR ?? resolve(import.meta.dir, "../../assets/demo");
+}
+
+export function demoProjectPath(): string {
+	return join(dataDir(), "demo", DEMO_APP_DIR);
+}
+
+export function ensureDemoProject(): Project {
+	const target = demoProjectPath();
+	if (!existsSync(target)) {
+		const source = join(templateRoot(), DEMO_APP_DIR);
+		if (!existsSync(source)) throw new Error(`Demo template not found: ${source}`);
+		mkdirSync(join(dataDir(), "demo"), { recursive: true });
+		cpSync(source, target, { recursive: true });
+	}
+	return initProject(target);
+}
+
+export function removeDemoFiles(): void {
+	rmSync(demoProjectPath(), { recursive: true, force: true });
+}
diff --git a/packages/server/src/demo/index.ts b/packages/server/src/demo/index.ts
new file mode 100644
index 000000000..d0845380e
--- /dev/null
+++ b/packages/server/src/demo/index.ts
@@ -0,0 +1 @@
+export * from "./demo";
diff --git a/packages/server/src/projects/SPEC.md b/packages/server/src/projects/SPEC.md
index 83b43a22c..6d9124f34 100644
--- a/packages/server/src/projects/SPEC.md
+++ b/packages/server/src/projects/SPEC.md
@@ -41,7 +41,7 @@ bootstrap it into one so it can be opened.
   — `host` answers the lazy `project.hasSpecs` query via `spec.projectHasSpecs`, keeping this module free
   of any spec dependency.)
 - **Public surface (barrel):** `openProject`, `listProjects`, `listRecentProjects`, `closeProject`,
-  `getProjects`, `setProjectPublisher`, `inspectProjectPath`, `initProject`.
+  `deleteProject`, `getProjects`, `setProjectPublisher`, `inspectProjectPath`, `initProject`.
 - **Allowed deps:** `persistence`; the `git` sub-module (shared `git()` runner, bound to live `env` for
   config overrides); `contracts` (`Project`, `ProjectPathStatus`); Node/Bun.
 - **Forbidden:** `host`; sibling features other than `git` (`workspaces` depends on `projects`, never the
diff --git a/packages/server/src/projects/projects.ts b/packages/server/src/projects/projects.ts
index 4b647e0b6..207705b1d 100644
--- a/packages/server/src/projects/projects.ts
+++ b/packages/server/src/projects/projects.ts
@@ -105,6 +105,15 @@ export function listRecentProjects(): Project[] {
 	return newestFirst(getProjects());
 }
 
+export function deleteProject(id: string): Project | null {
+	const projects = getProjects();
+	const index = projects.findIndex((candidate) => candidate.id === id);
+	if (index === -1) return null;
+	const [removed] = projects.splice(index, 1);
+	saveProjects(projects);
+	return removed ?? null;
+}
+
 export function closeProject(id: string): Project {
 	const projects = getProjects();
 	const project = projects.find((candidate) => candidate.id === id);

From 5383719bd9ed3f5fc40b7ec4a308d11cf971942d Mon Sep 17 00:00:00 2001
From: "Julia.Shilova" <Julia.Shilova@MacBook-Pro-5.local>
Date: Mon, 24 Aug 2026 20:28:31 +0300
Subject: [PATCH 03/23] feat(server): wire demo.ensure / demo.reset
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

demo.ensure materializes + opens the bundled To Do App demo (idempotent).
demo.reset archives the demo's workspaces (reusing the shared per-workspace
teardown, now factored out of workspace.remove), drops the project record,
and deletes the user-local copy — so onboarding can be restarted safely.
No project/workspace persistence, session lifecycle, or tab-close semantics
change.
---
 packages/contracts/src/wsProtocol.ts |  4 +++
 packages/server/src/host/handlers.ts | 46 ++++++++++++++++++++++------
 2 files changed, 41 insertions(+), 9 deletions(-)

diff --git a/packages/contracts/src/wsProtocol.ts b/packages/contracts/src/wsProtocol.ts
index 40eedf59b..7e2fbe52b 100644
--- a/packages/contracts/src/wsProtocol.ts
+++ b/packages/contracts/src/wsProtocol.ts
@@ -114,6 +114,8 @@ export const WS_METHODS = {
 	projectAliasSkills: "project.aliasSkills",
 	projectSetGroupEnabled: "project.setGroupEnabled",
 	projectSkills: "project.skills",
+	demoEnsure: "demo.ensure",
+	demoReset: "demo.reset",
 	workspaceCreate: "workspace.create",
 	workspaceListExisting: "workspace.listExisting",
 	workspaceOpenExisting: "workspace.openExisting",
@@ -278,6 +280,8 @@ export interface WsMethodMap {
 		result: Project;
 	};
 	"project.skills": { params: { projectId: string }; result: SkillCatalogEntry[] };
+	"demo.ensure": { params: Record<string, never>; result: Project };
+	"demo.reset": { params: Record<string, never>; result: Ack };
 	"workspace.create": {
 		params: { projectId: string; name?: string; baseRef?: string };
 		result: Workspace;
diff --git a/packages/server/src/host/handlers.ts b/packages/server/src/host/handlers.ts
index e7e0c6b99..7e4948f37 100644
--- a/packages/server/src/host/handlers.ts
+++ b/packages/server/src/host/handlers.ts
@@ -66,10 +66,18 @@ import {
 	updateJbcentral,
 } from "../auth";
 import { findOpenBranchReview } from "../branch-review";
+import { demoProjectPath, ensureDemoProject, removeDemoFiles } from "../demo";
 import { selectDirectory } from "../dialog";
 import { listAvailableEditors, openEditor, revealInFileManager } from "../editors";
 import { readDir, readFile } from "../fs";
-import { gitDiffFile, gitStatus, listBranches, listCommits, prefetchBranch } from "../git";
+import {
+	canonicalPath,
+	gitDiffFile,
+	gitStatus,
+	listBranches,
+	listCommits,
+	prefetchBranch,
+} from "../git";
 import { githubAuthStatus, githubRefresh } from "../github";
 import { clampLimit, getHistoryIndex } from "../history";
 import {
@@ -81,6 +89,8 @@ import {
 import {
 	acknowledgeProjectSkills,
 	closeProject,
+	deleteProject,
+	getProjects,
 	initProject,
 	inspectProjectPath,
 	listProjects,
@@ -166,6 +176,15 @@ async function archiveTeardown(ws: Workspace): Promise<void> {
 	}
 }
 
+function teardownWorkspace(ws: Workspace): Promise<void> {
+	removeWorkspaceLayout(ws.id);
+	evictSpecIndex(ws.id);
+	removeWorkspaceReviews(ws.id);
+	stopWatch(ws.id);
+	closeWorkspaceTerminals(ws.id);
+	return archiveTeardown(ws);
+}
+
 function trackSend(mode: SendMode, text: string): void {
 	if (isControlMessage(text)) return;
 	track({ name: "message_sent", params: { mode } });
@@ -250,6 +269,22 @@ const handlers: Record<string, Handler> = {
 		closeProject((params as { id: string }).id);
 		return { ok: true } as const;
 	},
+	"demo.ensure": () => ensureDemoProject(),
+	"demo.reset": async () => {
+		const target = canonicalPath(demoProjectPath());
+		const project = getProjects().find((p) => canonicalPath(p.path) === target);
+		if (project) {
+			await Promise.all(
+				listWorkspaceRecords(project.id).map((record) => {
+					const ws = forgetWorkspace(record.id);
+					return ws ? teardownWorkspace(ws) : Promise.resolve();
+				}),
+			);
+			deleteProject(project.id);
+		}
+		removeDemoFiles();
+		return { ok: true } as const;
+	},
 	"project.setTrust": async (params) => {
 		const p = params as { id: string; trusted: boolean };
 		const project = listProjects().find((candidate) => candidate.id === p.id);
@@ -278,14 +313,7 @@ const handlers: Record<string, Handler> = {
 	"workspace.remove": (params) => {
 		const id = (params as { id: string }).id;
 		const ws = forgetWorkspace(id);
-		if (ws) {
-			removeWorkspaceLayout(ws.id);
-			evictSpecIndex(ws.id);
-			removeWorkspaceReviews(ws.id);
-			stopWatch(ws.id);
-			closeWorkspaceTerminals(ws.id);
-			void archiveTeardown(ws);
-		}
+		if (ws) void teardownWorkspace(ws);
 		return { ok: true } as const;
 	},
 	"workspace.diffStats": (params) => workspaceDiffStats((params as { id: string }).id),

From d53fb9ceaabcf0945ed5ded49598365af6548abf Mon Sep 17 00:00:00 2001
From: "Julia.Shilova" <Julia.Shilova@MacBook-Pro-5.local>
Date: Mon, 24 Aug 2026 20:46:37 +0300
Subject: [PATCH 04/23] feat(server): ship a small SPEC.md in the To Do App
 demo template
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The bundled demo now carries a goal-and-requirements spec node, so it is
a specced project from first open: project.hasSpecs is true, the Specs
side-tool has content, and Welcome leads with Start building — the
natural onboarding path. Demo SPEC notes the reset-as-replay door.
---
 packages/server/assets/demo/to-do-app/SPEC.md | 34 +++++++++++++++++++
 packages/server/src/demo/SPEC.md              | 10 ++++++
 packages/server/src/demo/demo.test.ts         |  4 ++-
 3 files changed, 47 insertions(+), 1 deletion(-)
 create mode 100644 packages/server/assets/demo/to-do-app/SPEC.md

diff --git a/packages/server/assets/demo/to-do-app/SPEC.md b/packages/server/assets/demo/to-do-app/SPEC.md
new file mode 100644
index 000000000..5c3f8be51
--- /dev/null
+++ b/packages/server/assets/demo/to-do-app/SPEC.md
@@ -0,0 +1,34 @@
+---
+id: to-do-app
+type: goal-and-requirements
+status: active
+title: To Do App
+tags: [demo]
+---
+
+## Goal
+
+A tiny, dependency-free to-do list that runs straight in the browser — the bundled ThinkRail demo
+project. It exists so a new user can try the ThinkRail loop (create a workspace, pair with the agent,
+review changes) on a real git repository without bringing one of their own.
+
+## Scope
+
+- Add a task from a text input.
+- Toggle a task complete / active.
+- Delete a task.
+- Persist the list across reloads (browser `localStorage`).
+
+## Structure
+
+- `index.html` — the page shell and the new-task form.
+- `styles.css` — presentation only (system color tokens, no framework).
+- `src/storage.js` — load/save the task list.
+- `src/app.js` — rendering plus add / toggle / delete wiring.
+
+## Suggested next steps
+
+Good first tasks to pair with the agent on:
+
+- **Add search** — filter the visible tasks by a text query.
+- **Filter by status** — show all / active / completed tasks.
diff --git a/packages/server/src/demo/SPEC.md b/packages/server/src/demo/SPEC.md
index aadc1dc4d..e3063ff23 100644
--- a/packages/server/src/demo/SPEC.md
+++ b/packages/server/src/demo/SPEC.md
@@ -19,6 +19,16 @@ workspaces, sessions, and worktrees are the existing modules' jobs, unchanged.
 **Lazy, never eager.** The copy happens only when the user explicitly starts the demo (the `demo.ensure`
 wire door), never at host startup.
 
+**Ships its own spec.** The bundled template carries a small `SPEC.md` (a `goal-and-requirements` node
+describing the To Do App), so the demo is a *specced* project from first open: `project.hasSpecs` is true,
+the Specs side-tool has content, and the Welcome fork leads with "Start building" rather than the
+spec-first "Set up project" — the natural path for the onboarding tour.
+
+**Reset is the onboarding replay door.** `demo.reset` (host-orchestrated, below) archives the demo's
+workspaces, drops the project record, and deletes the user-local copy, returning the app to the empty
+first-run state — the frontend "Reset demo" control that lets a user replay the onboarding tour is built
+on it (see the web onboarding SPEC).
+
 ## Boundary
 
 - **Owns:**
diff --git a/packages/server/src/demo/demo.test.ts b/packages/server/src/demo/demo.test.ts
index 70738df33..053ac6cca 100644
--- a/packages/server/src/demo/demo.test.ts
+++ b/packages/server/src/demo/demo.test.ts
@@ -36,7 +36,9 @@ test("ensureDemoProject copies the template, inits a real repo, and opens it", (
 	expect(existsSync(join(demoProjectPath(), "index.html"))).toBe(true);
 	expect(existsSync(join(demoProjectPath(), "src", "app.js"))).toBe(true);
 	expect(gitOut(demoProjectPath(), "rev-parse", "HEAD")).not.toBe("");
-	expect(gitOut(demoProjectPath(), "ls-tree", "-r", "HEAD", "--name-only")).toContain("index.html");
+	const tracked = gitOut(demoProjectPath(), "ls-tree", "-r", "HEAD", "--name-only");
+	expect(tracked).toContain("index.html");
+	expect(tracked).toContain("SPEC.md");
 	expect(listProjects().map((p) => p.id)).toEqual([project.id]);
 });
 

From f11ac13f72f7685e453d6a36dac15a16cc514e9f Mon Sep 17 00:00:00 2001
From: "Julia.Shilova" <Julia.Shilova@MacBook-Pro-5.local>
Date: Mon, 24 Aug 2026 20:50:34 +0300
Subject: [PATCH 05/23] feat(web): onboarding store slice + persistence

Adds an onboarding state slice (flow/demoProjectId/dismissed) with
start/dismiss/reset/hydrate actions, per-browser localStorage persistence
(host-qualified key, mirrors projectExpansion), and derived selectors:
the current step (0..3) is computed from real domain state (demo
workspace count + whether each has a sent user turn), so it auto-advances
and self-heals across reloads. Unit tests for the advance predicates.
---
 apps/web/src/main.tsx                  |  2 +
 apps/web/src/onboarding/persistence.ts | 40 +++++++++++
 apps/web/src/store/appStore.ts         | 28 ++++++++
 apps/web/src/store/onboarding.test.ts  | 95 ++++++++++++++++++++++++++
 apps/web/src/store/selectors.ts        | 61 ++++++++++++++++-
 5 files changed, 225 insertions(+), 1 deletion(-)
 create mode 100644 apps/web/src/onboarding/persistence.ts
 create mode 100644 apps/web/src/store/onboarding.test.ts

diff --git a/apps/web/src/main.tsx b/apps/web/src/main.tsx
index c9ab58830..b99be9af3 100644
--- a/apps/web/src/main.tsx
+++ b/apps/web/src/main.tsx
@@ -3,6 +3,7 @@ import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
 import { ErrorBoundary } from "./components/ErrorBoundary";
 import { initNavigation } from "./navigation";
+import { initOnboardingPersistence } from "./onboarding/persistence";
 import { initProjectExpansionPersistence } from "./panels/projectExpansion";
 import { Shell } from "./shell/Shell";
 import { applyTheme, initializeBundledThemes, readThemeHint } from "./themes";
@@ -12,6 +13,7 @@ initializeBundledThemes();
 applyTheme(readThemeHint());
 initTransport();
 initProjectExpansionPersistence();
+initOnboardingPersistence();
 initNavigation();
 
 const root = document.getElementById("root");
diff --git a/apps/web/src/onboarding/persistence.ts b/apps/web/src/onboarding/persistence.ts
new file mode 100644
index 000000000..d52b9f7a9
--- /dev/null
+++ b/apps/web/src/onboarding/persistence.ts
@@ -0,0 +1,40 @@
+import { STORAGE_PREFIX } from "../constants/branding";
+import { NO_ONBOARDING, type OnboardingState, useAppStore } from "../store";
+import { getTransport } from "../transport";
+
+function storageKey(): string {
+	return `${STORAGE_PREFIX}onboarding:${getTransport().httpBase()}`;
+}
+
+export function readPersistedOnboarding(): OnboardingState {
+	try {
+		const raw = localStorage.getItem(storageKey());
+		if (!raw) return NO_ONBOARDING;
+		const parsed = JSON.parse(raw) as unknown;
+		if (!parsed || typeof parsed !== "object") return NO_ONBOARDING;
+		const value = parsed as Record<string, unknown>;
+		return {
+			flow: value.flow === "demo" ? "demo" : null,
+			demoProjectId: typeof value.demoProjectId === "string" ? value.demoProjectId : null,
+			dismissed: value.dismissed === true,
+		};
+	} catch {
+		return NO_ONBOARDING;
+	}
+}
+
+function persistOnboarding(onboarding: OnboardingState): void {
+	try {
+		localStorage.setItem(storageKey(), JSON.stringify(onboarding));
+	} catch {}
+}
+
+export function initOnboardingPersistence(): void {
+	useAppStore.getState().hydrateOnboarding(readPersistedOnboarding());
+	let previous = useAppStore.getState().onboarding;
+	useAppStore.subscribe((state) => {
+		if (state.onboarding === previous) return;
+		previous = state.onboarding;
+		persistOnboarding(previous);
+	});
+}
diff --git a/apps/web/src/store/appStore.ts b/apps/web/src/store/appStore.ts
index 2155dc21a..6cd9446a4 100644
--- a/apps/web/src/store/appStore.ts
+++ b/apps/web/src/store/appStore.ts
@@ -260,6 +260,20 @@ export interface ChatLocationRequest {
 	navigation?: CenterNavigationStamp | null;
 }
 
+export type OnboardingFlow = "demo";
+
+export interface OnboardingState {
+	flow: OnboardingFlow | null;
+	demoProjectId: string | null;
+	dismissed: boolean;
+}
+
+export const NO_ONBOARDING: OnboardingState = {
+	flow: null,
+	demoProjectId: null,
+	dismissed: false,
+};
+
 export interface SessionRuntime {
 	turns: ChatTurn[];
 	turnIdByMessageIndex?: (string | null)[];
@@ -645,6 +659,7 @@ interface AppState {
 	terminalReplayKb: number;
 	layoutSettings: LayoutSettings;
 	toasts: Toast[];
+	onboarding: OnboardingState;
 	setStatus: (status: ConnectionStatus) => void;
 	installWelcomeSnapshot: (
 		protocolVersion: number,
@@ -812,6 +827,10 @@ interface AppState {
 	applyReviewChanged: (payload: ReviewChangedPayload) => void;
 	pushToast: (toast: Omit<Toast, "id">) => string;
 	dismissToast: (id: string) => void;
+	startOnboarding: (demoProjectId: string) => void;
+	dismissOnboarding: () => void;
+	resetOnboarding: () => void;
+	hydrateOnboarding: (onboarding: OnboardingState) => void;
 }
 
 function sortProjects(projects: Project[]): Project[] {
@@ -1303,6 +1322,7 @@ export const useAppStore = create<AppState>((set, get) => ({
 	terminalReplayKb: DEFAULT_CONFIG.terminalReplayKb,
 	layoutSettings: DEFAULT_CONFIG.layout,
 	toasts: [],
+	onboarding: NO_ONBOARDING,
 	setStatus: (status) =>
 		set((state) => ({
 			status,
@@ -2759,6 +2779,14 @@ export const useAppStore = create<AppState>((set, get) => ({
 		set((s) =>
 			s.toasts.some((t) => t.id === id) ? { toasts: s.toasts.filter((t) => t.id !== id) } : {},
 		),
+	startOnboarding: (demoProjectId) =>
+		set({ onboarding: { flow: "demo", demoProjectId, dismissed: false } }),
+	dismissOnboarding: () =>
+		set((s) =>
+			s.onboarding.dismissed ? {} : { onboarding: { ...s.onboarding, dismissed: true } },
+		),
+	resetOnboarding: () => set({ onboarding: NO_ONBOARDING }),
+	hydrateOnboarding: (onboarding) => set({ onboarding }),
 }));
 
 export const toast = {
diff --git a/apps/web/src/store/onboarding.test.ts b/apps/web/src/store/onboarding.test.ts
new file mode 100644
index 000000000..fa336e811
--- /dev/null
+++ b/apps/web/src/store/onboarding.test.ts
@@ -0,0 +1,95 @@
+import { expect, test } from "bun:test";
+import type { Workspace } from "@thinkrail/contracts";
+import {
+	type ChatTab,
+	EMPTY_RUNTIME,
+	NO_ONBOARDING,
+	type OnboardingState,
+	type SessionRuntime,
+} from "./appStore";
+import {
+	selectAgentStarted,
+	selectDemoWorkspaces,
+	selectOnboardingActive,
+	selectOnboardingStep,
+} from "./selectors";
+
+const DEMO = "demo-project";
+
+function ws(id: string, kind?: "default"): Workspace {
+	return {
+		id,
+		projectId: DEMO,
+		name: id,
+		branch: id,
+		worktreePath: `/wt/${id}`,
+		baseBranch: "main",
+		...(kind ? { kind } : {}),
+	};
+}
+
+function chatTab(workspaceId: string, sessionId: string): ChatTab {
+	return { kind: "chat", id: `tab-${sessionId}`, workspaceId, name: "Chat", sessionId };
+}
+
+function withUserTurn(): SessionRuntime {
+	return {
+		...EMPTY_RUNTIME,
+		turns: [{ kind: "user", id: "u1", message: { role: "user", content: "hi", timestamp: 0 } }],
+	};
+}
+
+const onboarding: OnboardingState = { flow: "demo", demoProjectId: DEMO, dismissed: false };
+
+function baseState(workspaces: Workspace[]) {
+	return {
+		onboarding,
+		workspaces: { [DEMO]: workspaces },
+		sessions: {} as Record<string, SessionRuntime>,
+		tabsByWorkspace: {} as Record<string, ChatTab[]>,
+		closedChatsByWorkspace: {},
+	};
+}
+
+test("selectOnboardingActive: true only for an armed, undismissed demo flow", () => {
+	expect(selectOnboardingActive({ onboarding })).toBe(true);
+	expect(selectOnboardingActive({ onboarding: { ...onboarding, dismissed: true } })).toBe(false);
+	expect(selectOnboardingActive({ onboarding: NO_ONBOARDING })).toBe(false);
+});
+
+test("selectDemoWorkspaces: excludes the Default workspace", () => {
+	const list = selectDemoWorkspaces({
+		onboarding,
+		workspaces: { [DEMO]: [ws("default", "default"), ws("a"), ws("b")] },
+	});
+	expect(list.map((w) => w.id)).toEqual(["a", "b"]);
+});
+
+test("step 0 until two non-Default workspaces exist", () => {
+	expect(selectOnboardingStep(baseState([ws("default", "default")]))).toBe(0);
+	expect(selectOnboardingStep(baseState([ws("default", "default"), ws("a")]))).toBe(0);
+	expect(selectOnboardingStep(baseState([ws("a"), ws("b")]))).toBe(1);
+});
+
+test("step 1 → 2 once the first workspace's agent has a user turn", () => {
+	const state = baseState([ws("a"), ws("b")]);
+	state.tabsByWorkspace = { a: [chatTab("a", "s-a")] };
+	state.sessions = { "s-a": withUserTurn() };
+	expect(selectAgentStarted(state, "a")).toBe(true);
+	expect(selectAgentStarted(state, "b")).toBe(false);
+	expect(selectOnboardingStep(state)).toBe(2);
+});
+
+test("step 3 (done) once both workspaces have started an agent", () => {
+	const state = baseState([ws("a"), ws("b")]);
+	state.tabsByWorkspace = { a: [chatTab("a", "s-a")], b: [chatTab("b", "s-b")] };
+	state.sessions = { "s-a": withUserTurn(), "s-b": withUserTurn() };
+	expect(selectOnboardingStep(state)).toBe(3);
+});
+
+test("a chat tab with no user turn does not count as started", () => {
+	const state = baseState([ws("a"), ws("b")]);
+	state.tabsByWorkspace = { a: [chatTab("a", "s-a")] };
+	state.sessions = { "s-a": EMPTY_RUNTIME };
+	expect(selectOnboardingStep(state)).toBe(1);
+});
diff --git a/apps/web/src/store/selectors.ts b/apps/web/src/store/selectors.ts
index fca2dcefc..ae847e365 100644
--- a/apps/web/src/store/selectors.ts
+++ b/apps/web/src/store/selectors.ts
@@ -15,7 +15,14 @@ import {
 	normalizePath,
 	readLayoutSelection,
 } from "../lib";
-import type { ClosedChat, EditorTab, RouteChatTarget, TerminalTab } from "./appStore";
+import type {
+	ClosedChat,
+	EditorTab,
+	OnboardingState,
+	RouteChatTarget,
+	SessionRuntime,
+	TerminalTab,
+} from "./appStore";
 
 interface ConnectionGenerationState {
 	status: string;
@@ -418,6 +425,58 @@ export function selectLastOpenChatSession(
 	return null;
 }
 
+export type OnboardingStep = 0 | 1 | 2 | 3;
+
+interface OnboardingDomainState {
+	onboarding: OnboardingState;
+	workspaces: Record<string, Workspace[]>;
+	sessions: Record<string, SessionRuntime>;
+	tabsByWorkspace: Record<string, EditorTab[]>;
+	closedChatsByWorkspace: Record<string, ClosedChat[]>;
+	layoutDocumentsByWorkspace?: Record<string, WorkspaceLayoutDocument>;
+}
+
+export function selectOnboardingActive(state: { onboarding: OnboardingState }): boolean {
+	return (
+		state.onboarding.flow === "demo" &&
+		!state.onboarding.dismissed &&
+		state.onboarding.demoProjectId !== null
+	);
+}
+
+export function selectDemoWorkspaces(state: {
+	onboarding: OnboardingState;
+	workspaces: Record<string, Workspace[]>;
+}): Workspace[] {
+	const projectId = state.onboarding.demoProjectId;
+	if (!projectId) return [];
+	return (state.workspaces[projectId] ?? []).filter((ws) => !isDefaultWorkspace(ws));
+}
+
+export function selectAgentStarted(
+	state: {
+		sessions: Record<string, SessionRuntime>;
+		tabsByWorkspace: Record<string, EditorTab[]>;
+		closedChatsByWorkspace: Record<string, ClosedChat[]>;
+		layoutDocumentsByWorkspace?: Record<string, WorkspaceLayoutDocument>;
+	},
+	workspaceId: string,
+): boolean {
+	return selectWorkspaceSessionIds(state, workspaceId).some((id) => {
+		const rt = state.sessions[id];
+		return rt ? rt.turns.some((turn) => turn.kind === "user") : false;
+	});
+}
+
+export function selectOnboardingStep(state: OnboardingDomainState): OnboardingStep {
+	const demoWorkspaces = selectDemoWorkspaces(state);
+	if (demoWorkspaces.length < 2) return 0;
+	const [first, second] = demoWorkspaces;
+	if (!first || !selectAgentStarted(state, first.id)) return 1;
+	if (!second || !selectAgentStarted(state, second.id)) return 2;
+	return 3;
+}
+
 export function selectReviewDraftCount(
 	state: { reviewsByWorkspace: Record<string, { comments: { status: string }[] }> },
 	workspaceId: string | null,

From 77fedeaf44bff60194ba8c64c1e7070c7e4f271d Mon Sep 17 00:00:00 2001
From: "Julia.Shilova" <Julia.Shilova@MacBook-Pro-5.local>
Date: Mon, 24 Aug 2026 20:59:04 +0300
Subject: [PATCH 06/23] =?UTF-8?q?feat(web):=20onboarding=20coach=20?=
 =?UTF-8?q?=E2=80=94=20contextual=20coach-marks=20for=20the=20demo=20tour?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds apps/web/src/onboarding: OnboardingCoach (one shell-mounted overlay
that anchors a Radix popover to real UI elements by stable attribute,
tracked per animation frame), the pure selectCoach step mapping, and the
startDemo/resetDemo orchestration. Three steps: create two workspaces →
start the first agent → run a second agent in parallel; each advances on
the real action. Adds anchor attributes to the rail (attributes only) and
mounts the coach in the shell. New submodule-web-onboarding SPEC.
---
 apps/web/SPEC.md                            |   4 +-
 apps/web/src/onboarding/OnboardingCoach.tsx | 104 ++++++++++++++++++++
 apps/web/src/onboarding/SPEC.md             |  76 ++++++++++++++
 apps/web/src/onboarding/coach.ts            |  85 ++++++++++++++++
 apps/web/src/onboarding/demo.ts             |  34 +++++++
 apps/web/src/onboarding/index.ts            |   4 +
 apps/web/src/panels/ProjectTree.tsx         |   3 +
 apps/web/src/shell/Shell.tsx                |   2 +
 8 files changed, 311 insertions(+), 1 deletion(-)
 create mode 100644 apps/web/src/onboarding/OnboardingCoach.tsx
 create mode 100644 apps/web/src/onboarding/SPEC.md
 create mode 100644 apps/web/src/onboarding/coach.ts
 create mode 100644 apps/web/src/onboarding/demo.ts
 create mode 100644 apps/web/src/onboarding/index.ts

diff --git a/apps/web/SPEC.md b/apps/web/SPEC.md
index c0624c563..c1217bb07 100644
--- a/apps/web/SPEC.md
+++ b/apps/web/SPEC.md
@@ -34,6 +34,7 @@ convention; their boundary is held by convention + spec. Sibling edges live here
 | `transport` | the WS client + its singleton/store wiring | yes | [transport/SPEC.md](src/transport/SPEC.md) |
 | `store` | Zustand: domain projections, accepted workspace-layout snapshots, local attention, chat runtimes | yes | [store/SPEC.md](src/store/SPEC.md) |
 | `panels` | layout-agnostic, store-driven feature views | no | [panels/SPEC.md](src/panels/SPEC.md) |
+| `onboarding` | the first-run demo tour: entry + contextual coach-mark steps + reset | yes | [onboarding/SPEC.md](src/onboarding/SPEC.md) |
 | `chat` | pi conversation UI primitives: content-block renderers + the tool-renderer registry | no | [chat/SPEC.md](src/chat/SPEC.md) |
 | `auth` | in-app provider login: the presentational OAuth dialog + its client-side state reducer | yes | [auth/SPEC.md](src/auth/SPEC.md) |
 | `shell` | the responsive frame + synchronized workbench composition (with bounded child `layout/`) | no | [shell/SPEC.md](src/shell/SPEC.md) |
@@ -58,7 +59,8 @@ screen, not a blank root).
 ### Dependency graph
 
 - `navigation` → `store`, `transport`, `contracts` (type-only); neither dependency imports it, and `main.tsx` initializes the integration
-- `shell` → child `shell/layout`, `panels`, `chat` (app-integration render/hydration only), `store`, `transport`, `contracts` (type-only), `components/ui`, `components` (`ErrorBoundary` around each mounted region), `constants`, `lib` (platform shortcut semantics), `themes` (the single owner of the atomic `applyTheme` DOM effect, driven by `store.theme`)
+- `shell` → child `shell/layout`, `panels`, `onboarding` (mounts `OnboardingCoach` beside `Toaster`), `chat` (app-integration render/hydration only), `store`, `transport`, `contracts` (type-only), `components/ui`, `components` (`ErrorBoundary` around each mounted region), `constants`, `lib` (platform shortcut semantics), `themes` (the single owner of the atomic `applyTheme` DOM effect, driven by `store.theme`)
+- `onboarding` → `store`, `transport`, `components/ui`, `lib`, `contracts`; mounted by `shell`, initialized in `main.tsx`; `panels/WelcomePanel` calls its `startDemo`/`resetDemo` (one-way panels→onboarding edge, no cycle)
 - `shell/layout` → `contracts` (types only), `lib` (attention/id primitives), and React / `react-resizable-panels` / `@dnd-kit/core`; the parent injects store state, commit callbacks, and feature renderers, so the child has no feature-module runtime edge
 - `panels` → `store`, `transport`, `components/ui`, `components` (`ErrorBoundary` for feature bodies), `lib`, `contracts`, `constants` (`WelcomePanel`'s wordmark), `chat` (`NewWorkspaceDialog` eagerly reuses `chat/ModelSelector`+`ThinkingSelector`+`useModelCatalog` — these are shiki-free, so the eager import stays split-safe; `TemplatesSettings` reuses `chat/TemplateEditorDialog` for its New/Edit flows — see `panels/SPEC.md`'s `TemplatesSettings` paragraph), `auth` (`ProvidersSettings` mounts `auth/LoginDialog`), `themes` (`AppearanceSettings` consumes the live catalog; code surfaces consume generic theme variables/syntax mapping)
 - `chat` → `contracts` (pi message types, **type-only**), `components/ui`, `lib`; `store` + `transport`
diff --git a/apps/web/src/onboarding/OnboardingCoach.tsx b/apps/web/src/onboarding/OnboardingCoach.tsx
new file mode 100644
index 000000000..7d0bf107a
--- /dev/null
+++ b/apps/web/src/onboarding/OnboardingCoach.tsx
@@ -0,0 +1,104 @@
+import { useEffect, useState } from "react";
+import { useShallow } from "zustand/react/shallow";
+import { Button } from "../components/ui/button";
+import { Popover, PopoverAnchor, PopoverContent } from "../components/ui/popover";
+import { useAppStore } from "../store";
+import { type CoachStep, selectCoach } from "./coach";
+import { resetDemo } from "./demo";
+
+export function OnboardingCoach() {
+	const coach = useAppStore(useShallow(selectCoach));
+	if (!coach) return null;
+	if (coach.done) return <DonePopover />;
+	return <StepPopover coach={coach} />;
+}
+
+function useTargetRect(selector: string): DOMRect | null {
+	const [rect, setRect] = useState<DOMRect | null>(null);
+	useEffect(() => {
+		let frame = 0;
+		const measure = () => {
+			const element = document.querySelector(selector);
+			setRect(element ? element.getBoundingClientRect() : null);
+			frame = requestAnimationFrame(measure);
+		};
+		measure();
+		return () => cancelAnimationFrame(frame);
+	}, [selector]);
+	return rect;
+}
+
+function StepPopover({ coach }: { coach: CoachStep }) {
+	const rect = useTargetRect(coach.selector);
+	const dismiss = useAppStore((s) => s.dismissOnboarding);
+	const setChatDraft = useAppStore((s) => s.setChatDraft);
+	if (!rect) return null;
+
+	return (
+		<Popover open>
+			<PopoverAnchor asChild>
+				<div
+					aria-hidden
+					className="pointer-events-none fixed z-40 rounded-[var(--radius-sm)] border-2 border-primary-muted"
+					style={{ left: rect.left, top: rect.top, width: rect.width, height: rect.height }}
+				/>
+			</PopoverAnchor>
+			<PopoverContent
+				data-testid="onboarding-coach"
+				align="start"
+				side="bottom"
+				className="w-[280px] p-md"
+			>
+				<p className="tr-text-label-pill text-primary">Step {coach.index} of 3</p>
+				<p className="mt-xs tr-title-card text-text-default">{coach.title}</p>
+				<p className="mt-xs text-text-muted tr-text-metadata leading-snug">{coach.body}</p>
+				<div className="mt-md flex items-center justify-between gap-sm">
+					<Button variant="ghost" size="sm" data-testid="onboarding-skip" onClick={() => dismiss()}>
+						Skip tour
+					</Button>
+					{coach.insertPrompt && coach.sessionId ? (
+						<Button
+							variant="outline"
+							size="sm"
+							data-testid="onboarding-insert-prompt"
+							onClick={() => setChatDraft(coach.sessionId as string, coach.insertPrompt as string)}
+						>
+							Insert prompt
+						</Button>
+					) : null}
+				</div>
+			</PopoverContent>
+		</Popover>
+	);
+}
+
+function DonePopover() {
+	const dismiss = useAppStore((s) => s.dismissOnboarding);
+	return (
+		<div className="pointer-events-none fixed inset-0 z-40 flex items-end justify-center pb-xl">
+			<div
+				data-testid="onboarding-coach"
+				className="pointer-events-auto w-[320px] rounded-[var(--radius-md)] border border-border-default bg-container-elevated-bg p-lg text-center shadow-[var(--shadow-md)]"
+			>
+				<p className="tr-title-card text-text-default">You're all set</p>
+				<p className="mt-xs text-text-muted tr-text-metadata leading-snug">
+					You created two isolated workspaces and ran agents in parallel — that's the ThinkRail
+					loop.
+				</p>
+				<div className="mt-md flex items-center justify-center gap-sm">
+					<Button
+						variant="outline"
+						size="sm"
+						data-testid="onboarding-reset"
+						onClick={() => void resetDemo()}
+					>
+						Reset demo
+					</Button>
+					<Button size="sm" data-testid="onboarding-done" onClick={() => dismiss()}>
+						Done
+					</Button>
+				</div>
+			</div>
+		</div>
+	);
+}
diff --git a/apps/web/src/onboarding/SPEC.md b/apps/web/src/onboarding/SPEC.md
new file mode 100644
index 000000000..40398db17
--- /dev/null
+++ b/apps/web/src/onboarding/SPEC.md
@@ -0,0 +1,76 @@
+---
+id: submodule-web-onboarding
+type: submodule-design
+status: active
+title: onboarding — the demo tour
+parent: module-web
+depends-on: [module-contracts, submodule-web-store, submodule-web-transport, submodule-server-demo]
+tags: [v1, ui, onboarding]
+---
+
+## Responsibility
+
+The first-run **demo tour**: enter the bundled To Do App demo, then guide a newcomer through three
+**contextual coach-mark steps** that ride on the *real* ThinkRail interface (not a separate wizard), and
+let them reset the demo to replay. It owns the tour's orchestration + overlay; the demo project itself is
+a normal Project (server `demo` module) and every step advances by the user performing a **real** action,
+never a synthetic one.
+
+## Behaviour
+
+- **Entry (`startDemo`).** `demo.ensure` → adopt the returned Project (`applyProjectUpdated`), arm the
+  flow (`store.startOnboarding(projectId)`), select the project (lands on its Welcome), and load its
+  workspaces so the rail reveals it. Errors degrade to a toast. Invoked by the Welcome "Try the To Do
+  App" card (panels).
+- **The three steps** (`selectCoach`, pure over store state; the current step is *derived*, never a stored
+  counter, so it auto-advances and self-heals across reloads):
+  1. **Create separate workspaces** — teaches the worktree/workspace model *before* any prompt. Anchors
+     the demo Welcome's "Start building" card while zero non-Default workspaces exist, then re-anchors the
+     rail `+` for the demo project once one exists. Completes at **two** non-Default demo workspaces.
+  2. **Start the first agent** — anchors the **first** workspace's chat composer (guiding a switch to it
+     first if it isn't active) and offers one-click **Insert** of *"Add search functionality to the To Do
+     app."* Completes when that workspace's session has a sent user turn.
+  3. **Run agents in parallel** — anchors the **second** (already-created) workspace: guides the user to
+     switch to it, then anchors its composer and offers **Insert** of *"Add a filter for completed
+     tasks."* Completes when that workspace's session has a sent user turn. The first agent keeps running,
+     so parallelism is shown directly. This step never *creates* the second workspace — creation is step 1.
+  A fourth **done** state ("You're all set") offers **Reset demo** + **Done**.
+- **Auto-advance** is a consequence of the derived step: the step selectors read domain state (demo
+  workspace count; whether each workspace's chat has a `kind: "user"` turn — `selectOnboardingStep` /
+  `selectAgentStarted` / `selectDemoWorkspaces` in `store`). No wire traffic, no per-step store writes.
+- **Reset (`resetDemo`).** `demo.reset` (archives the demo's workspaces, drops the record, deletes the
+  copy) → re-`project.list` and re-install the snapshot (dropping the demo from Recents) → clear the
+  onboarding slice. The demo's archived workspaces self-clear via the server's `workspace.removed`
+  broadcasts. Replayable: back at the empty first-run Welcome, the "Try the To Do App" card returns.
+- **Skip** dismisses the whole flow (`store.dismissOnboarding`) without touching the demo project.
+
+## Coach-mark mechanism
+
+- **One shell-mounted overlay** (`OnboardingCoach`); the shell composes it beside `Toaster`. Panels stay
+  layout-agnostic — the coach never imports panels, and resolves each step's anchor by a stable
+  attribute (`[data-testid="welcome-cta"]`, `[data-testid="chat-input"]`, `[data-onboarding="rail-add"]`
+  + `[data-project-id]`, `[data-onboarding-ws]`) via `document.querySelector`, measured each animation
+  frame so it tracks scroll/layout/late mounts. A missing target simply hides the popover (never
+  mispoints).
+- Renders the existing Radix `components/ui/popover` against a zero-size `PopoverAnchor` placed at the
+  target's rect (fixed position); a `border-primary-muted` ring marks the target. **No full-screen
+  scrim** — the real UI the user must click stays interactive (the ring/anchor is `pointer-events-none`).
+- Geometry (left/top/width/height) is the only inline `style`; all colour/spacing/typography use semantic
+  token utilities (precedent: `chat/turns` uses inline style for a dynamic transition duration).
+
+## Persistence
+
+Per-browser localStorage under a host-qualified key (mirrors `panels/projectExpansion`): the slice
+(`flow` / `demoProjectId` / `dismissed`) is hydrated at boot (`initOnboardingPersistence`, wired in
+`main.tsx`) and written on change, so the tour resumes where the user left it. Untrusted reads,
+best-effort writes.
+
+## Boundary
+
+- **Public surface (barrel):** `OnboardingCoach`, `startDemo`, `resetDemo`, `selectCoach`,
+  `initOnboardingPersistence`, `readPersistedOnboarding`.
+- **Allowed deps:** `store` (slice + selectors + `toast`), `transport` (`getTransport`/`errorText`),
+  `components/ui` (`popover`, `button`), `lib`, `contracts`, `lucide-react`.
+- **Forbidden:** `panels`, `shell` internals, `server`/`shared`/`pi`. (`panels/WelcomePanel` may call the
+  `startDemo`/`resetDemo` orchestration — a one-way panels→onboarding edge; onboarding never imports
+  panels, so there is no cycle.)
diff --git a/apps/web/src/onboarding/coach.ts b/apps/web/src/onboarding/coach.ts
new file mode 100644
index 000000000..ec6ede0f0
--- /dev/null
+++ b/apps/web/src/onboarding/coach.ts
@@ -0,0 +1,85 @@
+import {
+	selectDemoWorkspaces,
+	selectLastOpenChatSession,
+	selectOnboardingActive,
+	selectOnboardingStep,
+	type useAppStore,
+} from "../store";
+
+type AppStoreState = ReturnType<typeof useAppStore.getState>;
+
+export const SEARCH_PROMPT = "Add search functionality to the To Do app.";
+export const FILTER_PROMPT = "Add a filter for completed tasks.";
+
+export interface CoachStep {
+	done?: false;
+	index: 1 | 2 | 3;
+	title: string;
+	body: string;
+	selector: string;
+	insertPrompt?: string;
+	sessionId?: string;
+}
+
+export interface CoachDone {
+	done: true;
+}
+
+export type CoachView = CoachStep | CoachDone | null;
+
+export function selectCoach(state: AppStoreState): CoachView {
+	if (!selectOnboardingActive(state)) return null;
+	const demoProjectId = state.onboarding.demoProjectId;
+	if (!demoProjectId) return null;
+
+	const step = selectOnboardingStep(state);
+	if (step === 3) return { done: true };
+
+	const demoWorkspaces = selectDemoWorkspaces(state);
+
+	if (step === 0) {
+		if (demoWorkspaces.length === 0) {
+			return {
+				index: 1,
+				title: "Create your first workspace",
+				body: "ThinkRail runs each task in its own isolated worktree and branch. Create two workspaces so you can work on two tasks side by side — start with this one.",
+				selector: '[data-testid="welcome-cta"]',
+			};
+		}
+		return {
+			index: 1,
+			title: "Create a second workspace",
+			body: "One down. Create a second workspace for the other task — each stays isolated on its own branch.",
+			selector: `[data-onboarding="rail-add"][data-project-id="${demoProjectId}"]`,
+		};
+	}
+
+	const target = demoWorkspaces[step === 1 ? 0 : 1];
+	if (!target) return null;
+	const index = step === 1 ? 2 : 3;
+
+	if (state.activeWorkspaceId !== target.id) {
+		return {
+			index,
+			title: step === 1 ? "Open your first workspace" : "Switch to your second workspace",
+			body:
+				step === 1
+					? "Open the first workspace to start its agent."
+					: "Switch to your second workspace — your first agent keeps running while this one starts.",
+			selector: `[data-onboarding-ws="${target.id}"]`,
+		};
+	}
+
+	const sessionId = selectLastOpenChatSession(state, target.id);
+	return {
+		index,
+		title: step === 1 ? "Start the first agent" : "Run a second agent in parallel",
+		body:
+			step === 1
+				? "Ask the agent to build the first feature, then send it."
+				: "Start the second task here. Both agents run at the same time — that's parallel work.",
+		selector: '[data-testid="chat-input"]',
+		insertPrompt: step === 1 ? SEARCH_PROMPT : FILTER_PROMPT,
+		...(sessionId ? { sessionId } : {}),
+	};
+}
diff --git a/apps/web/src/onboarding/demo.ts b/apps/web/src/onboarding/demo.ts
new file mode 100644
index 000000000..b9df9838f
--- /dev/null
+++ b/apps/web/src/onboarding/demo.ts
@@ -0,0 +1,34 @@
+import { toast, useAppStore } from "../store";
+import { errorText, getTransport } from "../transport";
+
+export async function startDemo(): Promise<void> {
+	const store = useAppStore.getState();
+	try {
+		const project = await getTransport().request("demo.ensure", {});
+		store.applyProjectUpdated(project);
+		store.startOnboarding(project.id);
+		store.selectProject(project.id, { reveal: true });
+		const rows = await getTransport().request("workspace.list", { projectId: project.id });
+		useAppStore.getState().setWorkspaces(project.id, rows);
+	} catch (err) {
+		toast.error(errorText(err, "Couldn't start the To Do App demo."));
+	}
+}
+
+export async function resetDemo(): Promise<void> {
+	const demoProjectId = useAppStore.getState().onboarding.demoProjectId;
+	try {
+		await getTransport().request("demo.reset", {});
+	} catch (err) {
+		toast.error(errorText(err, "Couldn't reset the demo."));
+		return;
+	}
+	try {
+		const open = await getTransport().request("project.list", {});
+		const recent = useAppStore
+			.getState()
+			.recentProjects.filter((project) => project.id !== demoProjectId);
+		useAppStore.getState().installProjectSnapshot(open, recent);
+	} catch {}
+	useAppStore.getState().resetOnboarding();
+}
diff --git a/apps/web/src/onboarding/index.ts b/apps/web/src/onboarding/index.ts
new file mode 100644
index 000000000..2a5c1f9f0
--- /dev/null
+++ b/apps/web/src/onboarding/index.ts
@@ -0,0 +1,4 @@
+export { selectCoach } from "./coach";
+export { resetDemo, startDemo } from "./demo";
+export { OnboardingCoach } from "./OnboardingCoach";
+export { initOnboardingPersistence, readPersistedOnboarding } from "./persistence";
diff --git a/apps/web/src/panels/ProjectTree.tsx b/apps/web/src/panels/ProjectTree.tsx
index 9d58cbf77..8336426c1 100644
--- a/apps/web/src/panels/ProjectTree.tsx
+++ b/apps/web/src/panels/ProjectTree.tsx
@@ -386,6 +386,8 @@ function ProjectRow({
 			<button
 				type="button"
 				data-testid="add-workspace"
+				data-onboarding="rail-add"
+				data-project-id={project.id}
 				aria-label="Create workspace"
 				onClick={onAddWorkspace}
 				className="flex size-5 shrink-0 items-center justify-center rounded-[var(--radius-sm)] text-text-muted transition-colors hover:bg-container-elevated-bg hover:text-text-default focus-visible:bg-container-elevated-bg focus-visible:text-text-default"
@@ -508,6 +510,7 @@ function WorkspaceRow({
 			<fieldset
 				aria-label={workspace.name}
 				data-testid="workspace-item"
+				data-onboarding-ws={workspace.id}
 				data-active={isActive}
 				data-kind={workspace.kind ?? "worktree"}
 				onContextMenu={openMenuFromContext}
diff --git a/apps/web/src/shell/Shell.tsx b/apps/web/src/shell/Shell.tsx
index adc7a8027..314b5b92e 100644
--- a/apps/web/src/shell/Shell.tsx
+++ b/apps/web/src/shell/Shell.tsx
@@ -1,6 +1,7 @@
 import { ChevronRight, GitBranch, Settings } from "lucide-react";
 import { useEffect, useRef } from "react";
 import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from "../components/ui/resizable";
+import { OnboardingCoach } from "../onboarding";
 import { ProjectTree } from "../panels/ProjectTree";
 import { SettingsDialog } from "../panels/SettingsDialog";
 import { Toaster } from "../panels/Toaster";
@@ -217,6 +218,7 @@ export function Shell() {
 				</div>
 			)}
 			<Toaster />
+			<OnboardingCoach />
 		</div>
 	);
 }

From 857681b997b9687724fd646d10b9e388217c5c46 Mon Sep 17 00:00:00 2001
From: "Julia.Shilova" <Julia.Shilova@MacBook-Pro-5.local>
Date: Mon, 24 Aug 2026 21:00:56 +0300
Subject: [PATCH 07/23] feat(web): Welcome demo entry card + Reset demo button
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds the 'Try the To Do App' card to the no-projects Welcome state
(calls onboarding.startDemo) and a quiet 'Reset demo' button on the demo
project's Welcome (calls onboarding.resetDemo). Panels SPEC documents the
cards and the one-way panels→onboarding edge.
---
 apps/web/src/panels/SPEC.md          | 12 +++++++++---
 apps/web/src/panels/WelcomePanel.tsx | 24 +++++++++++++++++++++++-
 2 files changed, 32 insertions(+), 4 deletions(-)

diff --git a/apps/web/src/panels/SPEC.md b/apps/web/src/panels/SPEC.md
index 7cfa7eac6..ed999193d 100644
--- a/apps/web/src/panels/SPEC.md
+++ b/apps/web/src/panels/SPEC.md
@@ -169,7 +169,9 @@ label + explainer bottom-left; the primary is a filled-primary card carrying the
 hook, others quiet `welcome-action`s). Welcome is **the mode fork**: with a project shown it always pairs
 **"Start building"** (isolated worktree) with **"Work in project folder"** (the Default workspace) so the
 two working modes are a visible choice, not a hidden default. The cards by state: **no projects** →
-**"Open project"** (one card); **project + `hasSpecs`** → **"Start building"** (primary) + "Work in
+**"Open project"** + **"Try the To Do App"** (`data-testid="welcome-demo"`, `Sparkles`) — the demo entry
+that calls `onboarding`'s `startDemo` (materialize the bundled demo via `demo.ensure`, arm the onboarding
+tour, land on the demo's Welcome); **project + `hasSpecs`** → **"Start building"** (primary) + "Work in
 project folder"; **project + no specs** → a spec-first **"Set up project"** (primary) + "Start building"
 + "Work in project folder". **"Open project" appears only in the no-projects state** — where it's the
 only possible action; once a project is shown, opening another is the projects-rail **"+"** (the same
@@ -178,7 +180,10 @@ dropdown), so Welcome stays the *work-in-this-project* surface. That card hangs
 / Recents). Recents is the store's `recentProjects`: one last-opened path list containing open + closed
 records with no status badge; selecting either runs the shared open flow and lands at Project Home, with a
 closed record retaining its id and workspace state. `Card` is a `forwardRef` usable as a Radix `asChild`
-trigger. **"Work in project folder"**
+trigger. When the shown project **is** the active demo (`store.onboarding.demoProjectId`), Welcome also
+renders a quiet **"Reset demo"** text button (`data-testid="welcome-reset-demo"`) that calls
+`onboarding`'s `resetDemo` — the replay door (see [[submodule-web-onboarding]]). The demo entry/reset
+orchestration lives in `onboarding` (a one-way panels→onboarding edge); Welcome never owns the tour. **"Work in project folder"**
 (`House` icon, matching the rail's Default row) **direct-enters** the Default workspace — no dialog: the
 shared `enterDefaultWorkspace` helper lists the project's workspaces, stores them, and activates the
 `kind === "default"` row; an older host with no Default row degrades to an error toast. **"Start building"** is the
@@ -450,7 +455,8 @@ a project picker, the prompt hero, and the reused
   panes, singleton side tools, terminal bodies, Settings, and `Toaster`), imported **per-file** so
   Monaco/shiki/xterm stay lazy. Tab strips, group headers, side stacks, and center topology are not panel
   surfaces; the shell layout module wraps these renderers.
-- **Allowed deps:** `store`, `transport`, `components/ui` (incl. `popover`/`command`/`textarea` for the
+- **Allowed deps:** `onboarding` (`WelcomePanel` calls its `startDemo`/`resetDemo` orchestration — one-way,
+  no cycle); `store`, `transport`, `components/ui` (incl. `popover`/`command`/`textarea` for the
   dialog), `chat` (`ModelSelector`/`ThinkingSelector` + the `useModelCatalog` hook that feeds them,
   reused by `NewWorkspaceDialog`; `Markdown`,
   reused by `MarkdownPreview`; `TemplateEditorDialog`, reused by `TemplatesSettings`), `lib`, `themes` (catalog + generic application contract),
diff --git a/apps/web/src/panels/WelcomePanel.tsx b/apps/web/src/panels/WelcomePanel.tsx
index 791ae1dac..7cdc3282f 100644
--- a/apps/web/src/panels/WelcomePanel.tsx
+++ b/apps/web/src/panels/WelcomePanel.tsx
@@ -3,6 +3,7 @@ import { FolderOpen, House, type LucideIcon, Rocket, Sparkles } from "lucide-rea
 import { type ComponentPropsWithoutRef, forwardRef, useEffect, useState } from "react";
 import { cn } from "@/lib/utils";
 import { PRODUCT_NAME } from "../constants/branding";
+import { resetDemo, startDemo } from "../onboarding/demo";
 import { useAppStore } from "../store";
 import { getTransport } from "../transport";
 import { AddProjectMenu } from "./AddProjectMenu";
@@ -21,6 +22,7 @@ export function WelcomePanel() {
 	const projects = useAppStore((s) => s.projects);
 	const recentProjects = useAppStore((s) => s.recentProjects);
 	const selectedProjectId = useAppStore((s) => s.selectedProjectId);
+	const demoProjectId = useAppStore((s) => s.onboarding.demoProjectId);
 	const [dialog, setDialog] = useState<{
 		projectId: string;
 		prompt: string;
@@ -109,7 +111,16 @@ export function WelcomePanel() {
 
 			<div className="mt-xl flex flex-wrap justify-center gap-md">
 				{noProjects ? (
-					openProjectCard()
+					<>
+						{openProjectCard()}
+						<Card
+							icon={Sparkles}
+							title="Try the To Do App"
+							subtitle="Spin up a ready-made demo project and learn the ThinkRail loop in three quick steps."
+							data-testid="welcome-demo"
+							onClick={() => void startDemo()}
+						/>
+					</>
 				) : hasSpecs === null ? null : hasSpecs ? (
 					<>
 						<Card
@@ -150,6 +161,17 @@ export function WelcomePanel() {
 				)}
 			</div>
 
+			{project && demoProjectId === project.id ? (
+				<button
+					type="button"
+					data-testid="welcome-reset-demo"
+					onClick={() => void resetDemo()}
+					className="mt-lg text-text-muted tr-text-metadata underline underline-offset-2 hover:text-text-default"
+				>
+					Reset demo
+				</button>
+			) : null}
+
 			{dialog ? (
 				<NewWorkspaceDialog
 					open

From 85874579cd4b6a1ee227fed25f9e1e3a159483cb Mon Sep 17 00:00:00 2001
From: "Julia.Shilova" <Julia.Shilova@MacBook-Pro-5.local>
Date: Mon, 24 Aug 2026 21:06:44 +0300
Subject: [PATCH 08/23] fix(server): demo.reset drops all workspace records
 incl Default
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

demo.reset called forgetWorkspace on the demo's Default workspace, which
throws by design (Default is non-removable). Add forgetProjectWorkspaces
— a project-deletion primitive that drops every record for a project
(including user-owned kinds) and emits removed for each — and have
demo.reset tear down + reclaim worktrees, then bulk-forget, deleteProject,
and remove files. Worktree reclaim still refuses user-owned kinds.
---
 packages/server/src/host/handlers.ts         |  9 +++------
 packages/server/src/workspaces/SPEC.md       | 11 +++++++++--
 packages/server/src/workspaces/workspaces.ts |  9 +++++++++
 3 files changed, 21 insertions(+), 8 deletions(-)

diff --git a/packages/server/src/host/handlers.ts b/packages/server/src/host/handlers.ts
index 7e4948f37..803007b17 100644
--- a/packages/server/src/host/handlers.ts
+++ b/packages/server/src/host/handlers.ts
@@ -144,6 +144,7 @@ import { ensureWatch, stopWatch } from "../watch";
 import {
 	createWorkspace,
 	ensureWorkspaceScratchDir,
+	forgetProjectWorkspaces,
 	forgetWorkspace,
 	getWorkspace,
 	listExistingWorktrees,
@@ -274,12 +275,8 @@ const handlers: Record<string, Handler> = {
 		const target = canonicalPath(demoProjectPath());
 		const project = getProjects().find((p) => canonicalPath(p.path) === target);
 		if (project) {
-			await Promise.all(
-				listWorkspaceRecords(project.id).map((record) => {
-					const ws = forgetWorkspace(record.id);
-					return ws ? teardownWorkspace(ws) : Promise.resolve();
-				}),
-			);
+			await Promise.all(listWorkspaceRecords(project.id).map((ws) => teardownWorkspace(ws)));
+			forgetProjectWorkspaces(project.id);
 			deleteProject(project.id);
 		}
 		removeDemoFiles();
diff --git a/packages/server/src/workspaces/SPEC.md b/packages/server/src/workspaces/SPEC.md
index a5a3313c9..9325c1697 100644
--- a/packages/server/src/workspaces/SPEC.md
+++ b/packages/server/src/workspaces/SPEC.md
@@ -105,7 +105,13 @@ place as `kind: "external"` — outside the data dir, never created or mutated h
   defense-in-depth, any record whose `worktreePath` resolves to the project folder** — the rm-fallback must
   never see the user's repo or an attached checkout, however a corrupt/hand-edited record got there), and
   `removeWorkspace(id)` (the synchronous composition of the two, kept for callers/tests that want the whole
-  archive in one call).
+  archive in one call), and **`forgetProjectWorkspaces(projectId)`** — the **project-deletion** drop:
+  removes **every** record for a project (including the user-owned `default`/`external` kinds that
+  `forgetWorkspace` protects), emits `removed` for each, and returns them. Unlike `forgetWorkspace`, it is
+  allowed to drop a Default record because the *project itself is going away* (the demo-reset door in
+  `host`, paired with `deleteProject` + `removeDemoFiles`); it never touches git — worktree reclaim for the
+  managed rows is the caller's separate `reclaimWorktree`/`archiveTeardown` step, which still refuses the
+  user-owned kinds.
 - **Default workspace (`kind: "default"`):** exactly one per project. `listWorkspaces` **ensures** it
   — find-or-create by `projectId`+`kind` (id a plain `randomUUID`; the `kind` field is the marker,
   never an id convention), **collapsing duplicates** defensively if out-of-band state churn ever
@@ -160,7 +166,8 @@ place as `kind: "external"` — outside the data dir, never created or mutated h
   module the **single source of workspace lifecycle pushes** (the auto-rename tee no longer pushes — rename
   self-publishes), so registry membership stays shared domain state across every client (architecture #9).
 - **Public surface (barrel):** `createWorkspace`, `listExistingWorktrees`, `openExistingWorktree`,
-  `listWorkspaces`, `listWorkspaceRecords`, `forgetWorkspace`, `reclaimWorktree`, `removeWorkspace`,
+  `listWorkspaces`, `listWorkspaceRecords`, `forgetWorkspace`, `forgetProjectWorkspaces`,
+  `reclaimWorktree`, `removeWorkspace`,
   `workspaceDiffStats`, `getWorkspace`, `renameWorkspace`, `refreshUserOwnedWorkspace`,
   `ensureWorkspaceScratchDir`, `setWorkspacePublisher`, `WorkspaceLifecycleEvent`.
 - **Allowed deps:** `projects` (repo lookup), `git` (the runner), `persistence`; `contracts`;
diff --git a/packages/server/src/workspaces/workspaces.ts b/packages/server/src/workspaces/workspaces.ts
index 48fdb784a..d5bcfa55b 100644
--- a/packages/server/src/workspaces/workspaces.ts
+++ b/packages/server/src/workspaces/workspaces.ts
@@ -450,6 +450,15 @@ export function forgetWorkspace(id: string): Workspace | null {
 	return ws;
 }
 
+export function forgetProjectWorkspaces(projectId: string): Workspace[] {
+	const all = loadWorkspaces();
+	const removed = all.filter((w) => w.projectId === projectId);
+	if (removed.length === 0) return [];
+	saveWorkspaces(all.filter((w) => w.projectId !== projectId));
+	for (const ws of removed) emit({ kind: "removed", projectId: ws.projectId, id: ws.id });
+	return removed;
+}
+
 export function reclaimWorktree(ws: Workspace): void {
 	if (ws.kind === "default" || ws.kind === "external") return;
 	const project = loadProjects().find((p) => p.id === ws.projectId);

From 3650543ca18432442b6b5be5c5d0c9f63e0a078b Mon Sep 17 00:00:00 2001
From: "Julia.Shilova" <Julia.Shilova@MacBook-Pro-5.local>
Date: Mon, 24 Aug 2026 21:07:17 +0300
Subject: [PATCH 09/23] =?UTF-8?q?test(e2e):=20onboarding=20demo=20?=
 =?UTF-8?q?=E2=80=94=20entry,=20two-workspace=20coaching,=20reset,=20skip?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

No-agent spec: the demo card enters the demo, the coach guides creating
two workspaces (step 1 → step 2), Reset demo returns to the empty
first-run state, and Skip hides the coach while keeping the project.
---
 e2e/onboarding-demo.spec.ts | 60 +++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)
 create mode 100644 e2e/onboarding-demo.spec.ts

diff --git a/e2e/onboarding-demo.spec.ts b/e2e/onboarding-demo.spec.ts
new file mode 100644
index 000000000..03e9ec8af
--- /dev/null
+++ b/e2e/onboarding-demo.spec.ts
@@ -0,0 +1,60 @@
+import { rmSync } from "node:fs";
+import { join } from "node:path";
+import { expect, test } from "@playwright/test";
+import { createWorkspaceViaDialog, openAppFresh, worktreeRows } from "./fixtures/app";
+import { E2E_DATA_DIR } from "./fixtures/paths";
+
+test.beforeEach(() => {
+	rmSync(join(E2E_DATA_DIR, "demo"), { recursive: true, force: true });
+});
+
+test("enter the demo, the coach guides creating two workspaces, then reset replays it", async ({
+	page,
+}) => {
+	await openAppFresh(page);
+
+	const demoCard = page.getByTestId("welcome-demo");
+	await expect(demoCard).toBeVisible();
+	await expect(page.getByTestId("welcome-cta")).toContainText("Open project");
+	await demoCard.click();
+
+	await expect(page.getByTestId("project-item")).toHaveCount(1);
+	await expect(page.getByTestId("welcome-cta")).toContainText("Start building");
+
+	const coach = page.getByTestId("onboarding-coach");
+	await expect(coach).toContainText("Step 1 of 3");
+	await page.getByTestId("welcome-cta").click();
+	await expect(page.getByTestId("new-workspace-dialog")).toBeVisible();
+	await page.getByTestId("create-workspace").click();
+	await expect(worktreeRows(page)).toHaveCount(1);
+
+	await expect(coach).toContainText("Step 1 of 3");
+	await createWorkspaceViaDialog(page);
+	await expect(worktreeRows(page)).toHaveCount(2);
+
+	await expect(coach).toContainText("Step 2 of 3");
+
+	await page.getByTestId("project-item").first().getByTestId("project-name").click();
+	await expect(page.getByTestId("welcome")).toBeVisible();
+	await page.getByTestId("welcome-reset-demo").click();
+
+	await expect(page.getByTestId("project-item")).toHaveCount(0);
+	await expect(page.getByTestId("welcome-demo")).toBeVisible();
+	await expect(page.getByTestId("onboarding-coach")).toHaveCount(0);
+});
+
+test("skipping the tour hides the coach but keeps the demo project", async ({ page }) => {
+	await openAppFresh(page);
+	await page.getByTestId("welcome-demo").click();
+
+	const coach = page.getByTestId("onboarding-coach");
+	await expect(coach).toContainText("Step 1 of 3");
+	await page.getByTestId("onboarding-skip").click();
+
+	await expect(page.getByTestId("onboarding-coach")).toHaveCount(0);
+	await expect(page.getByTestId("project-item")).toHaveCount(1);
+
+	await page.getByTestId("project-item").first().getByTestId("project-name").click();
+	await page.getByTestId("welcome-reset-demo").click();
+	await expect(page.getByTestId("project-item")).toHaveCount(0);
+});

From 1f0c01c785a7329438908eb1bbcab81865660d00 Mon Sep 17 00:00:00 2001
From: "Julia.Shilova" <Julia.Shilova@MacBook-Pro-5.local>
Date: Mon, 24 Aug 2026 21:17:05 +0300
Subject: [PATCH 10/23] feat(server): display the demo project as "To Do App"

Uses the Project model's existing display-name field (name, distinct from
the path-derived slug): ensureDemoProject sets name via a new
setProjectName registry setter, leaving the folder + slug as to-do-app.
No new naming concept, no directory rename. e2e asserts the hero title.
---
 e2e/onboarding-demo.spec.ts              |  1 +
 packages/server/src/demo/SPEC.md         |  6 ++++--
 packages/server/src/demo/demo.test.ts    |  2 ++
 packages/server/src/demo/demo.ts         |  5 +++--
 packages/server/src/projects/SPEC.md     |  6 +++++-
 packages/server/src/projects/projects.ts | 11 +++++++++++
 6 files changed, 26 insertions(+), 5 deletions(-)

diff --git a/e2e/onboarding-demo.spec.ts b/e2e/onboarding-demo.spec.ts
index 03e9ec8af..d363448fa 100644
--- a/e2e/onboarding-demo.spec.ts
+++ b/e2e/onboarding-demo.spec.ts
@@ -19,6 +19,7 @@ test("enter the demo, the coach guides creating two workspaces, then reset repla
 	await demoCard.click();
 
 	await expect(page.getByTestId("project-item")).toHaveCount(1);
+	await expect(page.getByTestId("welcome-title")).toHaveText("To Do App");
 	await expect(page.getByTestId("welcome-cta")).toContainText("Start building");
 
 	const coach = page.getByTestId("onboarding-coach");
diff --git a/packages/server/src/demo/SPEC.md b/packages/server/src/demo/SPEC.md
index e3063ff23..acc5dfd5f 100644
--- a/packages/server/src/demo/SPEC.md
+++ b/packages/server/src/demo/SPEC.md
@@ -37,8 +37,10 @@ on it (see the web onboarding SPEC).
     managed worktree dirs keyed by project slug ([[submodule-server-workspaces]]).
   - `ensureDemoProject()` — idempotent: when the target is absent, copy the bundled template into it
     (never mutating the bundled source), then hand off to `initProject` (git init + initial commit, or a
-    short-circuit `openProject` when the repo already exists). Returns the `Project`. A second call
-    re-opens the existing record rather than re-initialising.
+    short-circuit `openProject` when the repo already exists) and set the display **`name`** to
+    "To Do App" via `projects`' `setProjectName` (the folder + `slug` stay `to-do-app`; the existing
+    display-name field, not a new naming concept). Returns the `Project`. A second call re-opens the
+    existing record rather than re-initialising.
   - `removeDemoFiles()` — `rm -rf` the user-local copy. The *domain* half of a reset (archiving the
     demo's workspaces + dropping the project record via `deleteProject`) is orchestrated by `host`, which
     can reach the per-workspace teardown seams this module must not (terminals, spec index, reviews,
diff --git a/packages/server/src/demo/demo.test.ts b/packages/server/src/demo/demo.test.ts
index 053ac6cca..b57c3e64c 100644
--- a/packages/server/src/demo/demo.test.ts
+++ b/packages/server/src/demo/demo.test.ts
@@ -33,6 +33,8 @@ test("ensureDemoProject copies the template, inits a real repo, and opens it", (
 	const project = ensureDemoProject();
 
 	expect(project.path).toBe(realpathSync(demoProjectPath()));
+	expect(project.name).toBe("To Do App");
+	expect(project.slug).toBe("to-do-app");
 	expect(existsSync(join(demoProjectPath(), "index.html"))).toBe(true);
 	expect(existsSync(join(demoProjectPath(), "src", "app.js"))).toBe(true);
 	expect(gitOut(demoProjectPath(), "rev-parse", "HEAD")).not.toBe("");
diff --git a/packages/server/src/demo/demo.ts b/packages/server/src/demo/demo.ts
index df81829eb..147411a09 100644
--- a/packages/server/src/demo/demo.ts
+++ b/packages/server/src/demo/demo.ts
@@ -2,9 +2,10 @@ import { cpSync, existsSync, mkdirSync, rmSync } from "node:fs";
 import { join, resolve } from "node:path";
 import type { Project } from "@thinkrail/contracts";
 import { dataDir } from "../persistence";
-import { initProject } from "../projects";
+import { initProject, setProjectName } from "../projects";
 
 export const DEMO_APP_DIR = "to-do-app";
+export const DEMO_DISPLAY_NAME = "To Do App";
 
 function templateRoot(): string {
 	return process.env.THINKRAIL_DEMO_DIR ?? resolve(import.meta.dir, "../../assets/demo");
@@ -22,7 +23,7 @@ export function ensureDemoProject(): Project {
 		mkdirSync(join(dataDir(), "demo"), { recursive: true });
 		cpSync(source, target, { recursive: true });
 	}
-	return initProject(target);
+	return setProjectName(initProject(target).id, DEMO_DISPLAY_NAME);
 }
 
 export function removeDemoFiles(): void {
diff --git a/packages/server/src/projects/SPEC.md b/packages/server/src/projects/SPEC.md
index 6d9124f34..4d68564ba 100644
--- a/packages/server/src/projects/SPEC.md
+++ b/packages/server/src/projects/SPEC.md
@@ -41,7 +41,11 @@ bootstrap it into one so it can be opened.
   — `host` answers the lazy `project.hasSpecs` query via `spec.projectHasSpecs`, keeping this module free
   of any spec dependency.)
 - **Public surface (barrel):** `openProject`, `listProjects`, `listRecentProjects`, `closeProject`,
-  `deleteProject`, `getProjects`, `setProjectPublisher`, `inspectProjectPath`, `initProject`.
+  `deleteProject`, `setProjectName`, `getProjects`, `setProjectPublisher`, `inspectProjectPath`,
+  `initProject`. **`setProjectName(id, name)`** overwrites the **display `name`** only (never the
+  path-derived `slug`), persists, and emits `project.updated` — the demo project uses it for a friendly
+  "To Do App" title while its folder/slug stay `to-do-app`. `name` is display-only; `openProject` seeds it
+  from the folder basename at first open and never overwrites it on reopen, so a set name survives.
 - **Allowed deps:** `persistence`; the `git` sub-module (shared `git()` runner, bound to live `env` for
   config overrides); `contracts` (`Project`, `ProjectPathStatus`); Node/Bun.
 - **Forbidden:** `host`; sibling features other than `git` (`workspaces` depends on `projects`, never the
diff --git a/packages/server/src/projects/projects.ts b/packages/server/src/projects/projects.ts
index 207705b1d..9a827188a 100644
--- a/packages/server/src/projects/projects.ts
+++ b/packages/server/src/projects/projects.ts
@@ -124,6 +124,17 @@ export function closeProject(id: string): Project {
 	return project;
 }
 
+export function setProjectName(id: string, name: string): Project {
+	const projects = getProjects();
+	const project = projects.find((p) => p.id === id);
+	if (!project) throw new Error(`Unknown project: ${id}`);
+	if (project.name === name) return project;
+	project.name = name;
+	saveProjects(projects);
+	emit(project);
+	return project;
+}
+
 export function setProjectTrust(
 	id: string,
 	trusted: boolean,

From 4b4bde30b2665ac3d028a823a14e6b014fff14b1 Mon Sep 17 00:00:00 2001
From: "Julia.Shilova" <Julia.Shilova@MacBook-Pro-5.local>
Date: Mon, 24 Aug 2026 21:35:21 +0300
Subject: [PATCH 11/23] =?UTF-8?q?chore(web):=20TEMP=20=E2=80=94=20show=20d?=
 =?UTF-8?q?emo=20card=20in=20project=20Welcome=20for=20design=20review?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Renders the existing 'Try the To Do App' card (same demoCard element,
same demo.ensure behavior/copy/styling) alongside the project Welcome
cards in both has-specs and no-specs states, not only the empty first-run
state. Frontend-only, no wire/contract change. Temporary review aid for
this branch — revert this commit to restore empty-state-only placement.
---
 apps/web/src/panels/WelcomePanel.tsx | 20 +++++++++++++-------
 1 file changed, 13 insertions(+), 7 deletions(-)

diff --git a/apps/web/src/panels/WelcomePanel.tsx b/apps/web/src/panels/WelcomePanel.tsx
index 7cdc3282f..02436a820 100644
--- a/apps/web/src/panels/WelcomePanel.tsx
+++ b/apps/web/src/panels/WelcomePanel.tsx
@@ -77,6 +77,16 @@ export function WelcomePanel() {
 		/>
 	);
 
+	const demoCard = () => (
+		<Card
+			icon={Sparkles}
+			title="Try the To Do App"
+			subtitle="Spin up a ready-made demo project and learn the ThinkRail loop in three quick steps."
+			data-testid="welcome-demo"
+			onClick={() => void startDemo()}
+		/>
+	);
+
 	const openProjectCard = () => (
 		<AddProjectMenu
 			recentProjects={recentProjects}
@@ -113,13 +123,7 @@ export function WelcomePanel() {
 				{noProjects ? (
 					<>
 						{openProjectCard()}
-						<Card
-							icon={Sparkles}
-							title="Try the To Do App"
-							subtitle="Spin up a ready-made demo project and learn the ThinkRail loop in three quick steps."
-							data-testid="welcome-demo"
-							onClick={() => void startDemo()}
-						/>
+						{demoCard()}
 					</>
 				) : hasSpecs === null ? null : hasSpecs ? (
 					<>
@@ -132,6 +136,7 @@ export function WelcomePanel() {
 							onClick={() => setDialog({ projectId: project.id, prompt: "" })}
 						/>
 						{projectFolderCard(project.id)}
+						{demoCard()}
 					</>
 				) : (
 					<>
@@ -157,6 +162,7 @@ export function WelcomePanel() {
 							onClick={() => setDialog({ projectId: project.id, prompt: "" })}
 						/>
 						{projectFolderCard(project.id)}
+						{demoCard()}
 					</>
 				)}
 			</div>

From e073f8b3365bae25140c9205db9bb90bca46b384 Mon Sep 17 00:00:00 2001
From: "Julia.Shilova" <Julia.Shilova@MacBook-Pro-5.local>
Date: Mon, 24 Aug 2026 22:06:12 +0300
Subject: [PATCH 12/23] feat(web): manual-launch demo tour from a simulated
 empty state
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a persistent Help-style OnboardingLauncher at the bottom of the left
panel (ProjectTree footer) that starts the demo from a simulated empty
first-run state — view-only, never touching the real project registry.

Flow: step 1 spotlights a simulated empty Welcome 'Open project' card,
then a simulated (frontend-only) folder picker offering a single
'to-do-app' folder; selecting it runs the real demo.ensure and continues
into the existing live coach (steps 2-4: create two workspaces, first
agent, parallel agent). All steps now use one Spotlight treatment: a
container-workspace-overlay (workspace bg @ veil/70% alpha, a sanctioned
color token) dim around a clear, interactive target + a tooltip with an
arrow; coach marks are non-dismissible, with a separate Exit control that
restores the normal UI. Replaces the temporary always-visible Welcome
demo card (empty-state card retained as a direct entry). Frontend-only;
no wire/contract/backend changes. Specs + e2e updated.
---
 apps/web/src/components/ui/popover.tsx        |  11 +-
 apps/web/src/onboarding/OnboardingCoach.tsx   |  73 +++--------
 apps/web/src/onboarding/OnboardingDemo.tsx    | 123 ++++++++++++++++++
 .../web/src/onboarding/OnboardingLauncher.tsx |  19 +++
 apps/web/src/onboarding/SPEC.md               |  77 +++++++----
 apps/web/src/onboarding/Spotlight.tsx         |  97 ++++++++++++++
 apps/web/src/onboarding/anchor.ts             |  20 +++
 apps/web/src/onboarding/coach.ts              |  10 +-
 apps/web/src/onboarding/index.ts              |   2 +
 apps/web/src/onboarding/persistence.ts        |   2 +
 apps/web/src/panels/ProjectTree.tsx           |   7 +-
 apps/web/src/panels/SPEC.md                   |   8 +-
 apps/web/src/panels/WelcomePanel.tsx          |   2 -
 apps/web/src/shell/Shell.tsx                  |   4 +-
 apps/web/src/store/appStore.ts                |  11 +-
 apps/web/src/store/onboarding.test.ts         |   8 +-
 apps/web/src/store/selectors.ts               |   1 +
 apps/web/src/styles/colors.json               |  11 +-
 apps/web/src/styles/generated/colors.css      |   4 +-
 e2e/onboarding-demo.spec.ts                   |  43 +++---
 20 files changed, 412 insertions(+), 121 deletions(-)
 create mode 100644 apps/web/src/onboarding/OnboardingDemo.tsx
 create mode 100644 apps/web/src/onboarding/OnboardingLauncher.tsx
 create mode 100644 apps/web/src/onboarding/Spotlight.tsx
 create mode 100644 apps/web/src/onboarding/anchor.ts

diff --git a/apps/web/src/components/ui/popover.tsx b/apps/web/src/components/ui/popover.tsx
index fe8274dfa..1d1a7dbc5 100644
--- a/apps/web/src/components/ui/popover.tsx
+++ b/apps/web/src/components/ui/popover.tsx
@@ -6,6 +6,15 @@ const Popover = PopoverPrimitive.Root;
 const PopoverTrigger = PopoverPrimitive.Trigger;
 const PopoverAnchor = PopoverPrimitive.Anchor;
 
+function PopoverArrow({
+	className,
+	...props
+}: React.ComponentProps<typeof PopoverPrimitive.Arrow>) {
+	return (
+		<PopoverPrimitive.Arrow className={cn("fill-container-elevated-bg", className)} {...props} />
+	);
+}
+
 function PopoverContent({
 	className,
 	align = "center",
@@ -30,4 +39,4 @@ function PopoverContent({
 	);
 }
 
-export { Popover, PopoverAnchor, PopoverContent, PopoverTrigger };
+export { Popover, PopoverAnchor, PopoverArrow, PopoverContent, PopoverTrigger };
diff --git a/apps/web/src/onboarding/OnboardingCoach.tsx b/apps/web/src/onboarding/OnboardingCoach.tsx
index 7d0bf107a..ed6827ac1 100644
--- a/apps/web/src/onboarding/OnboardingCoach.tsx
+++ b/apps/web/src/onboarding/OnboardingCoach.tsx
@@ -1,62 +1,27 @@
-import { useEffect, useState } from "react";
 import { useShallow } from "zustand/react/shallow";
 import { Button } from "../components/ui/button";
-import { Popover, PopoverAnchor, PopoverContent } from "../components/ui/popover";
 import { useAppStore } from "../store";
 import { type CoachStep, selectCoach } from "./coach";
 import { resetDemo } from "./demo";
+import { CoachBody, Spotlight } from "./Spotlight";
 
 export function OnboardingCoach() {
 	const coach = useAppStore(useShallow(selectCoach));
 	if (!coach) return null;
-	if (coach.done) return <DonePopover />;
-	return <StepPopover coach={coach} />;
+	if (coach.done) return <DoneCard />;
+	return <StepSpotlight coach={coach} />;
 }
 
-function useTargetRect(selector: string): DOMRect | null {
-	const [rect, setRect] = useState<DOMRect | null>(null);
-	useEffect(() => {
-		let frame = 0;
-		const measure = () => {
-			const element = document.querySelector(selector);
-			setRect(element ? element.getBoundingClientRect() : null);
-			frame = requestAnimationFrame(measure);
-		};
-		measure();
-		return () => cancelAnimationFrame(frame);
-	}, [selector]);
-	return rect;
-}
-
-function StepPopover({ coach }: { coach: CoachStep }) {
-	const rect = useTargetRect(coach.selector);
-	const dismiss = useAppStore((s) => s.dismissOnboarding);
+function StepSpotlight({ coach }: { coach: CoachStep }) {
 	const setChatDraft = useAppStore((s) => s.setChatDraft);
-	if (!rect) return null;
-
 	return (
-		<Popover open>
-			<PopoverAnchor asChild>
-				<div
-					aria-hidden
-					className="pointer-events-none fixed z-40 rounded-[var(--radius-sm)] border-2 border-primary-muted"
-					style={{ left: rect.left, top: rect.top, width: rect.width, height: rect.height }}
-				/>
-			</PopoverAnchor>
-			<PopoverContent
-				data-testid="onboarding-coach"
-				align="start"
-				side="bottom"
-				className="w-[280px] p-md"
-			>
-				<p className="tr-text-label-pill text-primary">Step {coach.index} of 3</p>
-				<p className="mt-xs tr-title-card text-text-default">{coach.title}</p>
-				<p className="mt-xs text-text-muted tr-text-metadata leading-snug">{coach.body}</p>
-				<div className="mt-md flex items-center justify-between gap-sm">
-					<Button variant="ghost" size="sm" data-testid="onboarding-skip" onClick={() => dismiss()}>
-						Skip tour
-					</Button>
-					{coach.insertPrompt && coach.sessionId ? (
+		<Spotlight selector={coach.selector}>
+			<CoachBody
+				step={coach.index}
+				title={coach.title}
+				body={coach.body}
+				action={
+					coach.insertPrompt && coach.sessionId ? (
 						<Button
 							variant="outline"
 							size="sm"
@@ -65,17 +30,17 @@ function StepPopover({ coach }: { coach: CoachStep }) {
 						>
 							Insert prompt
 						</Button>
-					) : null}
-				</div>
-			</PopoverContent>
-		</Popover>
+					) : undefined
+				}
+			/>
+		</Spotlight>
 	);
 }
 
-function DonePopover() {
-	const dismiss = useAppStore((s) => s.dismissOnboarding);
+function DoneCard() {
+	const resetOnboarding = useAppStore((s) => s.resetOnboarding);
 	return (
-		<div className="pointer-events-none fixed inset-0 z-40 flex items-end justify-center pb-xl">
+		<div className="pointer-events-none fixed inset-0 z-50 flex items-end justify-center pb-xl">
 			<div
 				data-testid="onboarding-coach"
 				className="pointer-events-auto w-[320px] rounded-[var(--radius-md)] border border-border-default bg-container-elevated-bg p-lg text-center shadow-[var(--shadow-md)]"
@@ -94,7 +59,7 @@ function DonePopover() {
 					>
 						Reset demo
 					</Button>
-					<Button size="sm" data-testid="onboarding-done" onClick={() => dismiss()}>
+					<Button size="sm" data-testid="onboarding-done" onClick={() => resetOnboarding()}>
 						Done
 					</Button>
 				</div>
diff --git a/apps/web/src/onboarding/OnboardingDemo.tsx b/apps/web/src/onboarding/OnboardingDemo.tsx
new file mode 100644
index 000000000..43a55db41
--- /dev/null
+++ b/apps/web/src/onboarding/OnboardingDemo.tsx
@@ -0,0 +1,123 @@
+import { Folder, FolderOpen, X } from "lucide-react";
+import { PRODUCT_NAME } from "../constants/branding";
+import { useAppStore } from "../store";
+import { startDemo } from "./demo";
+import { OnboardingCoach } from "./OnboardingCoach";
+import { CoachBody, Spotlight } from "./Spotlight";
+
+export function OnboardingDemo() {
+	const stage = useAppStore((s) => s.onboarding.stage);
+	const resetOnboarding = useAppStore((s) => s.resetOnboarding);
+	if (!stage) return null;
+	return (
+		<>
+			{stage === "welcome" ? <DemoEmptyWelcome /> : null}
+			{stage === "picker" ? <DemoFolderPicker /> : null}
+			{stage === "live" ? <OnboardingCoach /> : null}
+			<button
+				type="button"
+				data-testid="onboarding-exit"
+				onClick={() => resetOnboarding()}
+				className="fixed top-md right-md z-50 inline-flex items-center gap-xs rounded-[var(--radius-sm)] border border-border-default bg-container-elevated-bg px-sm py-xs text-text-muted tr-text-metadata shadow-[var(--shadow-sm)] outline-none transition-colors hover:text-text-default focus-visible:ring-2 focus-visible:ring-primary"
+			>
+				<X className="size-3.5" />
+				Exit demo
+			</button>
+		</>
+	);
+}
+
+function DemoScaffold({ children }: { children: React.ReactNode }) {
+	return (
+		<div className="fixed inset-0 z-30 flex flex-col bg-container-workspace-bg">
+			<div className="flex h-12 shrink-0 items-center border-border-default border-b bg-container-header-bg px-lg">
+				<span className="tr-title-card text-primary">{PRODUCT_NAME}</span>
+			</div>
+			<div className="flex min-h-0 flex-1">
+				<aside className="w-[18%] min-w-[160px] border-border-default border-r bg-container-sidebar-bg p-md">
+					<span className="tr-text-eyebrow text-text-muted">Projects</span>
+				</aside>
+				<div className="flex min-h-0 flex-1 items-center justify-center bg-container-content-bg p-xl">
+					{children}
+				</div>
+			</div>
+		</div>
+	);
+}
+
+function DemoEmptyWelcome() {
+	const setDemoStage = useAppStore((s) => s.setDemoStage);
+	return (
+		<>
+			<DemoScaffold>
+				<div className="flex flex-col items-center text-center">
+					<h1 className="tr-brand-hero text-primary">{PRODUCT_NAME}</h1>
+					<div className="mt-xl">
+						<button
+							type="button"
+							data-onboarding="demo-open"
+							data-testid="demo-open-project"
+							onClick={() => setDemoStage("picker")}
+							className="relative flex h-[150px] w-[220px] flex-col items-start justify-between rounded-[var(--radius-sm)] border border-primary-muted bg-clip-padding bg-primary-subtle p-lg text-left transition-colors hover:bg-primary-soft"
+						>
+							<span className="flex size-9 items-center justify-center rounded-[var(--radius-sm)] bg-primary text-text-on-primary">
+								<FolderOpen className="size-4" />
+							</span>
+							<span className="w-full">
+								<span className="block tr-title-card text-text-default">Open project</span>
+								<span className="mt-0.5 block text-text-muted tr-text-metadata leading-snug">
+									Choose a local git repository to work in.
+								</span>
+							</span>
+						</button>
+					</div>
+				</div>
+			</DemoScaffold>
+			<Spotlight selector='[data-onboarding="demo-open"]' side="right" align="center">
+				<CoachBody
+					step={1}
+					title="Open a project"
+					body="Choose a project folder from your computer."
+				/>
+			</Spotlight>
+		</>
+	);
+}
+
+function DemoFolderPicker() {
+	return (
+		<>
+			<DemoScaffold>
+				<div className="w-[520px] overflow-hidden rounded-[var(--radius-lg)] border border-border-default bg-container-elevated-bg shadow-[var(--shadow-lg)]">
+					<div className="flex items-center gap-xs border-border-default border-b px-lg py-md tr-text-metadata text-text-muted">
+						<Folder className="size-3.5" />
+						<span>Home</span>
+						<span>/</span>
+						<span>Projects</span>
+					</div>
+					<ul className="p-sm">
+						<li>
+							<button
+								type="button"
+								data-onboarding="demo-folder"
+								data-testid="demo-folder-todo"
+								onClick={() => void startDemo()}
+								className="flex w-full items-center gap-sm rounded-[var(--radius-sm)] px-md py-sm text-left tr-text-ui text-text-default transition-colors hover:bg-control-bg-hovered"
+							>
+								<Folder className="size-4 text-primary" />
+								<span>to-do-app</span>
+							</button>
+						</li>
+					</ul>
+				</div>
+			</DemoScaffold>
+			<Spotlight selector='[data-onboarding="demo-folder"]' side="right" align="center">
+				<CoachBody
+					step={1}
+					title="Choose your project folder"
+					body="Select the To Do App folder to open it in ThinkRail."
+				/>
+			</Spotlight>
+		</>
+	);
+}
diff --git a/apps/web/src/onboarding/OnboardingLauncher.tsx b/apps/web/src/onboarding/OnboardingLauncher.tsx
new file mode 100644
index 000000000..dfa36408a
--- /dev/null
+++ b/apps/web/src/onboarding/OnboardingLauncher.tsx
@@ -0,0 +1,19 @@
+import { GraduationCap } from "lucide-react";
+import { useAppStore } from "../store";
+
+export function OnboardingLauncher() {
+	const startDemoTour = useAppStore((s) => s.startDemoTour);
+	return (
+		<button
+			type="button"
+			data-testid="onboarding-launch"
+			aria-label="Start the onboarding demo"
+			title="Start the onboarding demo"
+			onClick={() => startDemoTour()}
+			className="flex h-7 items-center gap-sm rounded-[var(--radius-sm)] px-sm text-text-muted tr-text-ui outline-none transition-colors hover:bg-control-bg-hovered hover:text-text-default focus-visible:ring-2 focus-visible:ring-primary"
+		>
+			<GraduationCap className="size-4 shrink-0" />
+			<span className="truncate">Onboarding demo</span>
+		</button>
+	);
+}
diff --git a/apps/web/src/onboarding/SPEC.md b/apps/web/src/onboarding/SPEC.md
index 40398db17..7f8de50dc 100644
--- a/apps/web/src/onboarding/SPEC.md
+++ b/apps/web/src/onboarding/SPEC.md
@@ -10,11 +10,32 @@ tags: [v1, ui, onboarding]
 
 ## Responsibility
 
-The first-run **demo tour**: enter the bundled To Do App demo, then guide a newcomer through three
-**contextual coach-mark steps** that ride on the *real* ThinkRail interface (not a separate wizard), and
-let them reset the demo to replay. It owns the tour's orchestration + overlay; the demo project itself is
-a normal Project (server `demo` module) and every step advances by the user performing a **real** action,
-never a synthetic one.
+The **demo tour**: launchable any time from a persistent left-panel control, it opens on a **simulated
+empty-first-run state** (view-only — the real project registry is never touched), teaches opening a
+project through a **simulated folder picker**, then materializes the bundled To Do App demo and guides a
+newcomer through the remaining **contextual coach-mark steps** on the *real* ThinkRail interface. Every
+live step advances by the user performing a **real** action, never a synthetic one.
+
+All coach marks use one **spotlight** treatment: the viewport is dimmed with the
+`container-workspace-overlay` scrim (the workspace surface at the `veil` 70% alpha step — a sanctioned
+color token, see `styles/colors.json`), the single actionable target stays clear + interactive, and a
+tooltip with an arrow points at it. A coach mark is **non-dismissible** — no close/Skip/Next, no
+outside-click or Escape; it clears only when its action completes. Leaving the tour is a **separate** Exit
+control (and the final done card), not a coach-mark dismissal.
+
+### Stages (`onboarding.stage`)
+
+- **`welcome`** (simulated) — a full-viewport opaque scaffold (`container-workspace-bg` shell chrome)
+  showing an empty Welcome with an "Open project" card, spotlighted ("Step 1 of 4 · Open a project").
+  Clicking it advances to `picker`. No real project exists yet.
+- **`picker`** (simulated) — a lightened Finder-like surface with a single selectable `to-do-app` folder,
+  spotlighted ("Choose your project folder"). This is a **controlled frontend simulation** — no real OS
+  picker, no filesystem/backend. Selecting it runs `startDemo` (real `demo.ensure`), which moves to `live`.
+- **`live`** — the real ThinkRail UI with the real demo project; `OnboardingCoach` spotlights the real
+  controls for steps 2–4 (create two workspaces → first agent → second agent in parallel).
+
+The manual launcher enters at `welcome`; the empty-state Welcome "Try the To Do App" card enters directly
+at `live` (skipping the simulation, since a genuinely-empty user needs no simulated empty state).
 
 ## Behaviour
 
@@ -22,19 +43,20 @@ never a synthetic one.
   flow (`store.startOnboarding(projectId)`), select the project (lands on its Welcome), and load its
   workspaces so the rail reveals it. Errors degrade to a toast. Invoked by the Welcome "Try the To Do
   App" card (panels).
-- **The three steps** (`selectCoach`, pure over store state; the current step is *derived*, never a stored
-  counter, so it auto-advances and self-heals across reloads):
-  1. **Create separate workspaces** — teaches the worktree/workspace model *before* any prompt. Anchors
+- **The live steps** (`selectCoach`, pure over store state; the current step is *derived*, never a stored
+  counter, so it auto-advances and self-heals across reloads; numbered *of 4* since the simulated
+  open-project stage is step 1):
+  2. **Create separate workspaces** — teaches the worktree/workspace model *before* any prompt. Anchors
      the demo Welcome's "Start building" card while zero non-Default workspaces exist, then re-anchors the
      rail `+` for the demo project once one exists. Completes at **two** non-Default demo workspaces.
-  2. **Start the first agent** — anchors the **first** workspace's chat composer (guiding a switch to it
+  3. **Start the first agent** — anchors the **first** workspace's chat composer (guiding a switch to it
      first if it isn't active) and offers one-click **Insert** of *"Add search functionality to the To Do
      app."* Completes when that workspace's session has a sent user turn.
-  3. **Run agents in parallel** — anchors the **second** (already-created) workspace: guides the user to
+  4. **Run agents in parallel** — anchors the **second** (already-created) workspace: guides the user to
      switch to it, then anchors its composer and offers **Insert** of *"Add a filter for completed
      tasks."* Completes when that workspace's session has a sent user turn. The first agent keeps running,
-     so parallelism is shown directly. This step never *creates* the second workspace — creation is step 1.
-  A fourth **done** state ("You're all set") offers **Reset demo** + **Done**.
+     so parallelism is shown directly. This step never *creates* the second workspace — creation is step 2.
+  A final **done** state ("You're all set") offers **Reset demo** + **Done**.
 - **Auto-advance** is a consequence of the derived step: the step selectors read domain state (demo
   workspace count; whether each workspace's chat has a `kind: "user"` turn — `selectOnboardingStep` /
   `selectAgentStarted` / `selectDemoWorkspaces` in `store`). No wire traffic, no per-step store writes.
@@ -42,33 +64,38 @@ never a synthetic one.
   copy) → re-`project.list` and re-install the snapshot (dropping the demo from Recents) → clear the
   onboarding slice. The demo's archived workspaces self-clear via the server's `workspace.removed`
   broadcasts. Replayable: back at the empty first-run Welcome, the "Try the To Do App" card returns.
-- **Skip** dismisses the whole flow (`store.dismissOnboarding`) without touching the demo project.
+- **Exit** (`onboarding-exit`, a fixed corner control shown for every stage) clears the tour view state
+  (`store.resetOnboarding`) and restores the normal UI; any real demo project already created remains as a
+  normal project. This is the only manual escape — coach marks themselves never dismiss.
 
 ## Coach-mark mechanism
 
-- **One shell-mounted overlay** (`OnboardingCoach`); the shell composes it beside `Toaster`. Panels stay
-  layout-agnostic — the coach never imports panels, and resolves each step's anchor by a stable
+- **One shell-mounted overlay** (`OnboardingDemo`); the shell composes it beside `Toaster`. It renders the
+  simulated `welcome`/`picker` scaffolds itself and delegates the `live` stage to `OnboardingCoach`.
+  Panels stay layout-agnostic — the overlay never imports panels, and resolves each target by a stable
   attribute (`[data-testid="welcome-cta"]`, `[data-testid="chat-input"]`, `[data-onboarding="rail-add"]`
-  + `[data-project-id]`, `[data-onboarding-ws]`) via `document.querySelector`, measured each animation
-  frame so it tracks scroll/layout/late mounts. A missing target simply hides the popover (never
-  mispoints).
-- Renders the existing Radix `components/ui/popover` against a zero-size `PopoverAnchor` placed at the
-  target's rect (fixed position); a `border-primary-muted` ring marks the target. **No full-screen
-  scrim** — the real UI the user must click stays interactive (the ring/anchor is `pointer-events-none`).
+  + `[data-project-id]`, `[data-onboarding-ws]`, and the simulated `[data-onboarding="demo-open"]` /
+  `[data-onboarding="demo-folder"]`) via `document.querySelector`, measured each animation frame so it
+  tracks scroll/layout/late mounts. A missing target simply hides the tooltip (never mispoints).
+- The shared **`Spotlight`** primitive draws four `container-workspace-overlay` dim rects around the target
+  rect (each `pointer-events-auto`, so the dimmed area both reads as inert and absorbs any outside click —
+  the non-dismissible guarantee), leaving the target hole clear + interactive, and renders the existing
+  Radix `components/ui/popover` (with a `PopoverArrow`) against a zero-size `PopoverAnchor` at the rect,
+  with Escape / outside-interaction handlers prevented.
 - Geometry (left/top/width/height) is the only inline `style`; all colour/spacing/typography use semantic
   token utilities (precedent: `chat/turns` uses inline style for a dynamic transition duration).
 
 ## Persistence
 
 Per-browser localStorage under a host-qualified key (mirrors `panels/projectExpansion`): the slice
-(`flow` / `demoProjectId` / `dismissed`) is hydrated at boot (`initOnboardingPersistence`, wired in
-`main.tsx`) and written on change, so the tour resumes where the user left it. Untrusted reads,
+(`flow` / `stage` / `demoProjectId` / `dismissed`) is hydrated at boot (`initOnboardingPersistence`, wired
+in `main.tsx`) and written on change, so the tour resumes where the user left it. Untrusted reads,
 best-effort writes.
 
 ## Boundary
 
-- **Public surface (barrel):** `OnboardingCoach`, `startDemo`, `resetDemo`, `selectCoach`,
-  `initOnboardingPersistence`, `readPersistedOnboarding`.
+- **Public surface (barrel):** `OnboardingDemo`, `OnboardingCoach`, `OnboardingLauncher`, `startDemo`,
+  `resetDemo`, `selectCoach`, `initOnboardingPersistence`, `readPersistedOnboarding`.
 - **Allowed deps:** `store` (slice + selectors + `toast`), `transport` (`getTransport`/`errorText`),
   `components/ui` (`popover`, `button`), `lib`, `contracts`, `lucide-react`.
 - **Forbidden:** `panels`, `shell` internals, `server`/`shared`/`pi`. (`panels/WelcomePanel` may call the
diff --git a/apps/web/src/onboarding/Spotlight.tsx b/apps/web/src/onboarding/Spotlight.tsx
new file mode 100644
index 000000000..f2eef9de5
--- /dev/null
+++ b/apps/web/src/onboarding/Spotlight.tsx
@@ -0,0 +1,97 @@
+import type { ReactNode } from "react";
+import { Popover, PopoverAnchor, PopoverArrow, PopoverContent } from "../components/ui/popover";
+import { useTargetRect } from "./anchor";
+
+const DIM = "pointer-events-auto fixed z-40 bg-container-workspace-overlay";
+
+export function Spotlight({
+	selector,
+	side = "bottom",
+	align = "start",
+	children,
+}: {
+	selector: string;
+	side?: "top" | "right" | "bottom" | "left";
+	align?: "start" | "center" | "end";
+	children: ReactNode;
+}) {
+	const rect = useTargetRect(selector);
+	if (!rect) return null;
+	return (
+		<>
+			<div
+				aria-hidden
+				className={DIM}
+				style={{ left: 0, top: 0, width: "100vw", height: rect.top }}
+			/>
+			<div
+				aria-hidden
+				className={DIM}
+				style={{
+					left: 0,
+					top: rect.bottom,
+					width: "100vw",
+					height: `calc(100vh - ${rect.bottom}px)`,
+				}}
+			/>
+			<div
+				aria-hidden
+				className={DIM}
+				style={{ left: 0, top: rect.top, width: rect.left, height: rect.height }}
+			/>
+			<div
+				aria-hidden
+				className={DIM}
+				style={{
+					left: rect.right,
+					top: rect.top,
+					width: `calc(100vw - ${rect.right}px)`,
+					height: rect.height,
+				}}
+			/>
+			<Popover open>
+				<PopoverAnchor asChild>
+					<div
+						aria-hidden
+						className="pointer-events-none fixed z-40"
+						style={{ left: rect.left, top: rect.top, width: rect.width, height: rect.height }}
+					/>
+				</PopoverAnchor>
+				<PopoverContent
+					data-testid="onboarding-coach"
+					side={side}
+					align={align}
+					className="z-50 w-[280px] p-md"
+					onOpenAutoFocus={(event) => event.preventDefault()}
+					onEscapeKeyDown={(event) => event.preventDefault()}
+					onPointerDownOutside={(event) => event.preventDefault()}
+					onInteractOutside={(event) => event.preventDefault()}
+				>
+					{children}
+					<PopoverArrow />
+				</PopoverContent>
+			</Popover>
+		</>
+	);
+}
+
+export function CoachBody({
+	step,
+	title,
+	body,
+	action,
+}: {
+	step: number;
+	title: string;
+	body: string;
+	action?: ReactNode;
+}) {
+	return (
+		<>
+			<p className="tr-text-label-pill text-primary">Step {step} of 4</p>
+			<p className="mt-xs tr-title-card text-text-default">{title}</p>
+			<p className="mt-xs text-text-muted tr-text-metadata leading-snug">{body}</p>
+			{action ? <div className="mt-md flex items-center justify-end">{action}</div> : null}
+		</>
+	);
+}
diff --git a/apps/web/src/onboarding/anchor.ts b/apps/web/src/onboarding/anchor.ts
new file mode 100644
index 000000000..eb3b115cb
--- /dev/null
+++ b/apps/web/src/onboarding/anchor.ts
@@ -0,0 +1,20 @@
+import { useEffect, useState } from "react";
+
+export function useTargetRect(selector: string | null): DOMRect | null {
+	const [rect, setRect] = useState<DOMRect | null>(null);
+	useEffect(() => {
+		if (!selector) {
+			setRect(null);
+			return;
+		}
+		let frame = 0;
+		const measure = () => {
+			const element = document.querySelector(selector);
+			setRect(element ? element.getBoundingClientRect() : null);
+			frame = requestAnimationFrame(measure);
+		};
+		measure();
+		return () => cancelAnimationFrame(frame);
+	}, [selector]);
+	return rect;
+}
diff --git a/apps/web/src/onboarding/coach.ts b/apps/web/src/onboarding/coach.ts
index ec6ede0f0..f1aa0bf78 100644
--- a/apps/web/src/onboarding/coach.ts
+++ b/apps/web/src/onboarding/coach.ts
@@ -13,7 +13,7 @@ export const FILTER_PROMPT = "Add a filter for completed tasks.";
 
 export interface CoachStep {
 	done?: false;
-	index: 1 | 2 | 3;
+	index: 2 | 3 | 4;
 	title: string;
 	body: string;
 	selector: string;
@@ -21,6 +21,8 @@ export interface CoachStep {
 	sessionId?: string;
 }
 
+export const COACH_STEP_COUNT = 4;
+
 export interface CoachDone {
 	done: true;
 }
@@ -40,14 +42,14 @@ export function selectCoach(state: AppStoreState): CoachView {
 	if (step === 0) {
 		if (demoWorkspaces.length === 0) {
 			return {
-				index: 1,
+				index: 2,
 				title: "Create your first workspace",
 				body: "ThinkRail runs each task in its own isolated worktree and branch. Create two workspaces so you can work on two tasks side by side — start with this one.",
 				selector: '[data-testid="welcome-cta"]',
 			};
 		}
 		return {
-			index: 1,
+			index: 2,
 			title: "Create a second workspace",
 			body: "One down. Create a second workspace for the other task — each stays isolated on its own branch.",
 			selector: `[data-onboarding="rail-add"][data-project-id="${demoProjectId}"]`,
@@ -56,7 +58,7 @@ export function selectCoach(state: AppStoreState): CoachView {
 
 	const target = demoWorkspaces[step === 1 ? 0 : 1];
 	if (!target) return null;
-	const index = step === 1 ? 2 : 3;
+	const index = step === 1 ? 3 : 4;
 
 	if (state.activeWorkspaceId !== target.id) {
 		return {
diff --git a/apps/web/src/onboarding/index.ts b/apps/web/src/onboarding/index.ts
index 2a5c1f9f0..79002ea70 100644
--- a/apps/web/src/onboarding/index.ts
+++ b/apps/web/src/onboarding/index.ts
@@ -1,4 +1,6 @@
 export { selectCoach } from "./coach";
 export { resetDemo, startDemo } from "./demo";
 export { OnboardingCoach } from "./OnboardingCoach";
+export { OnboardingDemo } from "./OnboardingDemo";
+export { OnboardingLauncher } from "./OnboardingLauncher";
 export { initOnboardingPersistence, readPersistedOnboarding } from "./persistence";
diff --git a/apps/web/src/onboarding/persistence.ts b/apps/web/src/onboarding/persistence.ts
index d52b9f7a9..32e871dc3 100644
--- a/apps/web/src/onboarding/persistence.ts
+++ b/apps/web/src/onboarding/persistence.ts
@@ -13,8 +13,10 @@ export function readPersistedOnboarding(): OnboardingState {
 		const parsed = JSON.parse(raw) as unknown;
 		if (!parsed || typeof parsed !== "object") return NO_ONBOARDING;
 		const value = parsed as Record<string, unknown>;
+		const stage = value.stage;
 		return {
 			flow: value.flow === "demo" ? "demo" : null,
+			stage: stage === "welcome" || stage === "picker" || stage === "live" ? stage : null,
 			demoProjectId: typeof value.demoProjectId === "string" ? value.demoProjectId : null,
 			dismissed: value.dismissed === true,
 		};
diff --git a/apps/web/src/panels/ProjectTree.tsx b/apps/web/src/panels/ProjectTree.tsx
index 8336426c1..2cbbb9437 100644
--- a/apps/web/src/panels/ProjectTree.tsx
+++ b/apps/web/src/panels/ProjectTree.tsx
@@ -33,6 +33,7 @@ import {
 	DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
 import { copyText } from "@/lib";
+import { OnboardingLauncher } from "../onboarding/OnboardingLauncher";
 import {
 	isDefaultWorkspace,
 	isExternalWorkspace,
@@ -209,7 +210,7 @@ export function ProjectTree() {
 	};
 
 	return (
-		<nav className="flex flex-col gap-sm">
+		<nav className="flex h-full flex-col gap-sm">
 			<header className="flex h-7 items-center justify-between pr-xs pl-sm">
 				<span className="tr-text-eyebrow text-text-muted">Projects</span>
 				<AddProjectMenu
@@ -302,6 +303,10 @@ export function ProjectTree() {
 			) : null}
 
 			{dialogs}
+
+			<div className="mt-auto flex flex-col border-border-default border-t pt-sm">
+				<OnboardingLauncher />
+			</div>
 		</nav>
 	);
 }
diff --git a/apps/web/src/panels/SPEC.md b/apps/web/src/panels/SPEC.md
index ed999193d..7a81fe505 100644
--- a/apps/web/src/panels/SPEC.md
+++ b/apps/web/src/panels/SPEC.md
@@ -20,6 +20,9 @@ arrangement (so the mobile shell is an additive layer, not a rewrite).
   **always-visible chevron** + folder/name + a collapsed-only plain workspace count + a **bare muted Create
   workspace `+` always visible in a fixed right-edge column** (the Projects-header Add project `+` is unchanged).
   Long names truncate before the count/action; there is deliberately **no visible Close or overflow icon**.
+  The nav is a full-height column with a **bottom-pinned footer** hosting the onboarding
+  **`OnboardingLauncher`** (a Help-style icon button that starts the demo tour from its simulated empty
+  state — see [[submodule-web-onboarding]]).
   Hover highlights the full row and the highlight remains while its **project context menu** is open.
   Right-click opens that PR-#167-styled menu at the pointer without selecting/navigating; a scroll-cancelled
   ~700ms long press is its touch equivalent. With a project-name button focused, the standard Context Menu
@@ -455,8 +458,9 @@ a project picker, the prompt hero, and the reused
   panes, singleton side tools, terminal bodies, Settings, and `Toaster`), imported **per-file** so
   Monaco/shiki/xterm stay lazy. Tab strips, group headers, side stacks, and center topology are not panel
   surfaces; the shell layout module wraps these renderers.
-- **Allowed deps:** `onboarding` (`WelcomePanel` calls its `startDemo`/`resetDemo` orchestration — one-way,
-  no cycle); `store`, `transport`, `components/ui` (incl. `popover`/`command`/`textarea` for the
+- **Allowed deps:** `onboarding` (`WelcomePanel` calls its `startDemo`/`resetDemo` orchestration and
+  `ProjectTree` mounts its `OnboardingLauncher` at the left-panel footer — one-way panels→onboarding, no
+  cycle); `store`, `transport`, `components/ui` (incl. `popover`/`command`/`textarea` for the
   dialog), `chat` (`ModelSelector`/`ThinkingSelector` + the `useModelCatalog` hook that feeds them,
   reused by `NewWorkspaceDialog`; `Markdown`,
   reused by `MarkdownPreview`; `TemplateEditorDialog`, reused by `TemplatesSettings`), `lib`, `themes` (catalog + generic application contract),
diff --git a/apps/web/src/panels/WelcomePanel.tsx b/apps/web/src/panels/WelcomePanel.tsx
index 02436a820..d1d7a7c32 100644
--- a/apps/web/src/panels/WelcomePanel.tsx
+++ b/apps/web/src/panels/WelcomePanel.tsx
@@ -136,7 +136,6 @@ export function WelcomePanel() {
 							onClick={() => setDialog({ projectId: project.id, prompt: "" })}
 						/>
 						{projectFolderCard(project.id)}
-						{demoCard()}
 					</>
 				) : (
 					<>
@@ -162,7 +161,6 @@ export function WelcomePanel() {
 							onClick={() => setDialog({ projectId: project.id, prompt: "" })}
 						/>
 						{projectFolderCard(project.id)}
-						{demoCard()}
 					</>
 				)}
 			</div>
diff --git a/apps/web/src/shell/Shell.tsx b/apps/web/src/shell/Shell.tsx
index 314b5b92e..74b93ba88 100644
--- a/apps/web/src/shell/Shell.tsx
+++ b/apps/web/src/shell/Shell.tsx
@@ -1,7 +1,7 @@
 import { ChevronRight, GitBranch, Settings } from "lucide-react";
 import { useEffect, useRef } from "react";
 import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from "../components/ui/resizable";
-import { OnboardingCoach } from "../onboarding";
+import { OnboardingDemo } from "../onboarding";
 import { ProjectTree } from "../panels/ProjectTree";
 import { SettingsDialog } from "../panels/SettingsDialog";
 import { Toaster } from "../panels/Toaster";
@@ -218,7 +218,7 @@ export function Shell() {
 				</div>
 			)}
 			<Toaster />
-			<OnboardingCoach />
+			<OnboardingDemo />
 		</div>
 	);
 }
diff --git a/apps/web/src/store/appStore.ts b/apps/web/src/store/appStore.ts
index 6cd9446a4..16717d743 100644
--- a/apps/web/src/store/appStore.ts
+++ b/apps/web/src/store/appStore.ts
@@ -262,14 +262,18 @@ export interface ChatLocationRequest {
 
 export type OnboardingFlow = "demo";
 
+export type OnboardingStage = "welcome" | "picker" | "live";
+
 export interface OnboardingState {
 	flow: OnboardingFlow | null;
+	stage: OnboardingStage | null;
 	demoProjectId: string | null;
 	dismissed: boolean;
 }
 
 export const NO_ONBOARDING: OnboardingState = {
 	flow: null,
+	stage: null,
 	demoProjectId: null,
 	dismissed: false,
 };
@@ -827,6 +831,8 @@ interface AppState {
 	applyReviewChanged: (payload: ReviewChangedPayload) => void;
 	pushToast: (toast: Omit<Toast, "id">) => string;
 	dismissToast: (id: string) => void;
+	startDemoTour: () => void;
+	setDemoStage: (stage: OnboardingStage) => void;
 	startOnboarding: (demoProjectId: string) => void;
 	dismissOnboarding: () => void;
 	resetOnboarding: () => void;
@@ -2779,8 +2785,11 @@ export const useAppStore = create<AppState>((set, get) => ({
 		set((s) =>
 			s.toasts.some((t) => t.id === id) ? { toasts: s.toasts.filter((t) => t.id !== id) } : {},
 		),
+	startDemoTour: () =>
+		set({ onboarding: { flow: "demo", stage: "welcome", demoProjectId: null, dismissed: false } }),
+	setDemoStage: (stage) => set((s) => ({ onboarding: { ...s.onboarding, stage } })),
 	startOnboarding: (demoProjectId) =>
-		set({ onboarding: { flow: "demo", demoProjectId, dismissed: false } }),
+		set({ onboarding: { flow: "demo", stage: "live", demoProjectId, dismissed: false } }),
 	dismissOnboarding: () =>
 		set((s) =>
 			s.onboarding.dismissed ? {} : { onboarding: { ...s.onboarding, dismissed: true } },
diff --git a/apps/web/src/store/onboarding.test.ts b/apps/web/src/store/onboarding.test.ts
index fa336e811..0ad141bb7 100644
--- a/apps/web/src/store/onboarding.test.ts
+++ b/apps/web/src/store/onboarding.test.ts
@@ -39,7 +39,12 @@ function withUserTurn(): SessionRuntime {
 	};
 }
 
-const onboarding: OnboardingState = { flow: "demo", demoProjectId: DEMO, dismissed: false };
+const onboarding: OnboardingState = {
+	flow: "demo",
+	stage: "live",
+	demoProjectId: DEMO,
+	dismissed: false,
+};
 
 function baseState(workspaces: Workspace[]) {
 	return {
@@ -54,6 +59,7 @@ function baseState(workspaces: Workspace[]) {
 test("selectOnboardingActive: true only for an armed, undismissed demo flow", () => {
 	expect(selectOnboardingActive({ onboarding })).toBe(true);
 	expect(selectOnboardingActive({ onboarding: { ...onboarding, dismissed: true } })).toBe(false);
+	expect(selectOnboardingActive({ onboarding: { ...onboarding, stage: "welcome" } })).toBe(false);
 	expect(selectOnboardingActive({ onboarding: NO_ONBOARDING })).toBe(false);
 });
 
diff --git a/apps/web/src/store/selectors.ts b/apps/web/src/store/selectors.ts
index ae847e365..50436e837 100644
--- a/apps/web/src/store/selectors.ts
+++ b/apps/web/src/store/selectors.ts
@@ -439,6 +439,7 @@ interface OnboardingDomainState {
 export function selectOnboardingActive(state: { onboarding: OnboardingState }): boolean {
 	return (
 		state.onboarding.flow === "demo" &&
+		state.onboarding.stage === "live" &&
 		!state.onboarding.dismissed &&
 		state.onboarding.demoProjectId !== null
 	);
diff --git a/apps/web/src/styles/colors.json b/apps/web/src/styles/colors.json
index 8f056b77c..1bcbee19c 100644
--- a/apps/web/src/styles/colors.json
+++ b/apps/web/src/styles/colors.json
@@ -1,7 +1,7 @@
 {
 	"$schema": "./colors.schema.json",
 	"metadata": {
-		"version": "1.1.0",
+		"version": "1.2.0",
 		"note": "The semantic colour layer. Palettes live in themes/bundled/*.theme.json; this file says what each palette entry is FOR, and is the only place a derivation is written. A role's `from` names a theme manifest key; the CSS variable that key writes to is derived (kebab-case), not tabulated. See COLOR.md."
 	},
 
@@ -10,7 +10,8 @@
 		"wash": 12,
 		"soft": 20,
 		"muted": 40,
-		"strong": 60
+		"strong": 60,
+		"veil": 70
 	},
 
 	"roles": {
@@ -35,6 +36,12 @@
 			"publish": true,
 			"note": "the app surface, and with it the opened-document canvas — a document reads as part of the workspace (Monaco's EDITOR_THEME, the markdown/spec preview, the chat column, the tab strip)"
 		},
+		"container-workspace-overlay": {
+			"from": "background",
+			"alpha": "veil",
+			"publish": true,
+			"note": "the onboarding spotlight scrim: the workspace surface at the `veil` (70%) alpha step, dimming the viewport while a coach mark spotlights one target"
+		},
 		"container-sidebar-bg": { "from": "sidebar", "publish": true },
 		"container-terminal-bg": { "from": "sidebar", "publish": true },
 		"container-header-bg": { "from": "header", "publish": true },
diff --git a/apps/web/src/styles/generated/colors.css b/apps/web/src/styles/generated/colors.css
index 3c6d00620..37567d933 100644
--- a/apps/web/src/styles/generated/colors.css
+++ b/apps/web/src/styles/generated/colors.css
@@ -1,5 +1,5 @@
 /*
- * GENERATED — do not edit. Source: `src/styles/colors.json` (v1.1.0).
+ * GENERATED — do not edit. Source: `src/styles/colors.json` (v1.2.0).
  * Regenerate with `bun run colors:generate`; `colors:check` fails when this file is stale.
  *
  * The semantic roles, then the Tailwind utility map. The palette they read is written to the
@@ -14,6 +14,7 @@
 	--text-on-primary: var(--on-accent);
 	--text-link: var(--info); /* global.css `a {}` is the only consumer; no component styles a bare link */
 	--container-workspace-bg: var(--background); /* the app surface, and with it the opened-document canvas — a document reads as part of the workspace (Monaco's EDITOR_THEME, the markdown/spec preview, the chat column, the tab strip) */
+	--container-workspace-overlay: color-mix(in srgb, var(--background) 70%, transparent); /* the onboarding spotlight scrim: the workspace surface at the `veil` (70%) alpha step, dimming the viewport while a coach mark spotlights one target */
 	--container-sidebar-bg: var(--sidebar);
 	--container-terminal-bg: var(--sidebar);
 	--container-header-bg: var(--header);
@@ -83,6 +84,7 @@
 	--color-text-disabled: var(--text-disabled);
 	--color-text-on-primary: var(--text-on-primary);
 	--color-container-workspace-bg: var(--container-workspace-bg);
+	--color-container-workspace-overlay: var(--container-workspace-overlay);
 	--color-container-sidebar-bg: var(--container-sidebar-bg);
 	--color-container-terminal-bg: var(--container-terminal-bg);
 	--color-container-header-bg: var(--container-header-bg);
diff --git a/e2e/onboarding-demo.spec.ts b/e2e/onboarding-demo.spec.ts
index d363448fa..9d7a06e7b 100644
--- a/e2e/onboarding-demo.spec.ts
+++ b/e2e/onboarding-demo.spec.ts
@@ -8,54 +8,47 @@ test.beforeEach(() => {
 	rmSync(join(E2E_DATA_DIR, "demo"), { recursive: true, force: true });
 });
 
-test("enter the demo, the coach guides creating two workspaces, then reset replays it", async ({
+test("the left-panel launcher runs the simulated empty-state flow into the live demo", async ({
 	page,
 }) => {
 	await openAppFresh(page);
 
-	const demoCard = page.getByTestId("welcome-demo");
-	await expect(demoCard).toBeVisible();
-	await expect(page.getByTestId("welcome-cta")).toContainText("Open project");
-	await demoCard.click();
+	await page.getByTestId("onboarding-launch").click();
+
+	const coach = page.getByTestId("onboarding-coach");
+	await expect(coach).toContainText("Step 1 of 4");
+	await expect(coach).toContainText("Open a project");
+	await page.getByTestId("demo-open-project").click();
+
+	await expect(coach).toContainText("Choose your project folder");
+	await page.getByTestId("demo-folder-todo").click();
 
 	await expect(page.getByTestId("project-item")).toHaveCount(1);
 	await expect(page.getByTestId("welcome-title")).toHaveText("To Do App");
-	await expect(page.getByTestId("welcome-cta")).toContainText("Start building");
+	await expect(coach).toContainText("Step 2 of 4");
 
-	const coach = page.getByTestId("onboarding-coach");
-	await expect(coach).toContainText("Step 1 of 3");
 	await page.getByTestId("welcome-cta").click();
 	await expect(page.getByTestId("new-workspace-dialog")).toBeVisible();
 	await page.getByTestId("create-workspace").click();
 	await expect(worktreeRows(page)).toHaveCount(1);
 
-	await expect(coach).toContainText("Step 1 of 3");
+	await expect(coach).toContainText("Step 2 of 4");
 	await createWorkspaceViaDialog(page);
 	await expect(worktreeRows(page)).toHaveCount(2);
 
-	await expect(coach).toContainText("Step 2 of 3");
-
-	await page.getByTestId("project-item").first().getByTestId("project-name").click();
-	await expect(page.getByTestId("welcome")).toBeVisible();
-	await page.getByTestId("welcome-reset-demo").click();
+	await expect(coach).toContainText("Step 3 of 4");
 
-	await expect(page.getByTestId("project-item")).toHaveCount(0);
-	await expect(page.getByTestId("welcome-demo")).toBeVisible();
+	await page.getByTestId("onboarding-exit").click();
 	await expect(page.getByTestId("onboarding-coach")).toHaveCount(0);
 });
 
-test("skipping the tour hides the coach but keeps the demo project", async ({ page }) => {
+test("the empty-state Welcome card starts the demo directly at the live coach", async ({ page }) => {
 	await openAppFresh(page);
 	await page.getByTestId("welcome-demo").click();
 
-	const coach = page.getByTestId("onboarding-coach");
-	await expect(coach).toContainText("Step 1 of 3");
-	await page.getByTestId("onboarding-skip").click();
-
-	await expect(page.getByTestId("onboarding-coach")).toHaveCount(0);
 	await expect(page.getByTestId("project-item")).toHaveCount(1);
+	await expect(page.getByTestId("onboarding-coach")).toContainText("Step 2 of 4");
 
-	await page.getByTestId("project-item").first().getByTestId("project-name").click();
-	await page.getByTestId("welcome-reset-demo").click();
-	await expect(page.getByTestId("project-item")).toHaveCount(0);
+	await page.getByTestId("onboarding-exit").click();
+	await expect(page.getByTestId("onboarding-coach")).toHaveCount(0);
 });

From 8226240ec7cb0f557e39b963d45fbe39155c76e6 Mon Sep 17 00:00:00 2001
From: "Julia.Shilova" <Julia.Shilova@MacBook-Pro-5.local>
Date: Mon, 24 Aug 2026 22:27:23 +0300
Subject: [PATCH 13/23] feat(web): self-contained mocked onboarding simulation

Replaces the onboarding entry behavior with a fully self-contained,
frontend-only interactive simulation in a ~90vw x 90vh modal card
(OnboardingSimulation). It renders a faithful but mocked ThinkRail
(header / left panel / center) driven entirely by local React state:
scripted flow of open project -> fake folder picker (to-do-app) -> create
two isolated workspaces -> run agent 1 -> run agent 2 in parallel (first
shown done while the second works) -> completion. Non-dismissible coach
marks with a card-scoped container-workspace-overlay spotlight + arrow;
only the current target is interactive.

Touches NO domain state: no demo.ensure/reset, no Projects/Workspaces/
Sessions, no pi, no OS picker, no persistence. Launcher + Welcome card
now flip a top-level store.demoOpen flag (openDemo/closeDemo). The prior
real-domain onboarding coach + client demo orchestration are retained but
unwired (dormant) for easy iteration; the server bundled-demo capability
is untouched. Specs + e2e updated (e2e asserts the real registry stays
empty throughout).
---
 apps/web/SPEC.md                              |   4 +-
 .../web/src/onboarding/OnboardingLauncher.tsx |   4 +-
 .../src/onboarding/OnboardingSimulation.tsx   | 574 ++++++++++++++++++
 apps/web/src/onboarding/SPEC.md               | 132 ++--
 apps/web/src/onboarding/index.ts              |   1 +
 apps/web/src/panels/SPEC.md                   |  21 +-
 apps/web/src/panels/WelcomePanel.tsx          |  19 +-
 apps/web/src/shell/Shell.tsx                  |   4 +-
 apps/web/src/store/appStore.ts                |   6 +
 e2e/onboarding-demo.spec.ts                   |  64 +-
 10 files changed, 684 insertions(+), 145 deletions(-)
 create mode 100644 apps/web/src/onboarding/OnboardingSimulation.tsx

diff --git a/apps/web/SPEC.md b/apps/web/SPEC.md
index c1217bb07..a932a9d9c 100644
--- a/apps/web/SPEC.md
+++ b/apps/web/SPEC.md
@@ -59,8 +59,8 @@ screen, not a blank root).
 ### Dependency graph
 
 - `navigation` → `store`, `transport`, `contracts` (type-only); neither dependency imports it, and `main.tsx` initializes the integration
-- `shell` → child `shell/layout`, `panels`, `onboarding` (mounts `OnboardingCoach` beside `Toaster`), `chat` (app-integration render/hydration only), `store`, `transport`, `contracts` (type-only), `components/ui`, `components` (`ErrorBoundary` around each mounted region), `constants`, `lib` (platform shortcut semantics), `themes` (the single owner of the atomic `applyTheme` DOM effect, driven by `store.theme`)
-- `onboarding` → `store`, `transport`, `components/ui`, `lib`, `contracts`; mounted by `shell`, initialized in `main.tsx`; `panels/WelcomePanel` calls its `startDemo`/`resetDemo` (one-way panels→onboarding edge, no cycle)
+- `shell` → child `shell/layout`, `panels`, `onboarding` (mounts `OnboardingSimulation` beside `Toaster`), `chat` (app-integration render/hydration only), `store`, `transport`, `contracts` (type-only), `components/ui`, `components` (`ErrorBoundary` around each mounted region), `constants`, `lib` (platform shortcut semantics), `themes` (the single owner of the atomic `applyTheme` DOM effect, driven by `store.theme`)
+- `onboarding` → `store`, `components/ui`, `constants`, `lib`, `contracts`; mounted by `shell`; `panels` (`WelcomePanel` + `ProjectTree` footer) call `openDemo` (one-way panels→onboarding edge, no cycle). The active `OnboardingSimulation` is fully mocked (no `transport`); the retained-but-dormant real-domain coach still carries the `transport`/`demo` edges (see [[submodule-web-onboarding]])
 - `shell/layout` → `contracts` (types only), `lib` (attention/id primitives), and React / `react-resizable-panels` / `@dnd-kit/core`; the parent injects store state, commit callbacks, and feature renderers, so the child has no feature-module runtime edge
 - `panels` → `store`, `transport`, `components/ui`, `components` (`ErrorBoundary` for feature bodies), `lib`, `contracts`, `constants` (`WelcomePanel`'s wordmark), `chat` (`NewWorkspaceDialog` eagerly reuses `chat/ModelSelector`+`ThinkingSelector`+`useModelCatalog` — these are shiki-free, so the eager import stays split-safe; `TemplatesSettings` reuses `chat/TemplateEditorDialog` for its New/Edit flows — see `panels/SPEC.md`'s `TemplatesSettings` paragraph), `auth` (`ProvidersSettings` mounts `auth/LoginDialog`), `themes` (`AppearanceSettings` consumes the live catalog; code surfaces consume generic theme variables/syntax mapping)
 - `chat` → `contracts` (pi message types, **type-only**), `components/ui`, `lib`; `store` + `transport`
diff --git a/apps/web/src/onboarding/OnboardingLauncher.tsx b/apps/web/src/onboarding/OnboardingLauncher.tsx
index dfa36408a..df6f0b6a5 100644
--- a/apps/web/src/onboarding/OnboardingLauncher.tsx
+++ b/apps/web/src/onboarding/OnboardingLauncher.tsx
@@ -2,14 +2,14 @@ import { GraduationCap } from "lucide-react";
 import { useAppStore } from "../store";
 
 export function OnboardingLauncher() {
-	const startDemoTour = useAppStore((s) => s.startDemoTour);
+	const openDemo = useAppStore((s) => s.openDemo);
 	return (
 		<button
 			type="button"
 			data-testid="onboarding-launch"
 			aria-label="Start the onboarding demo"
 			title="Start the onboarding demo"
-			onClick={() => startDemoTour()}
+			onClick={() => openDemo()}
 			className="flex h-7 items-center gap-sm rounded-[var(--radius-sm)] px-sm text-text-muted tr-text-ui outline-none transition-colors hover:bg-control-bg-hovered hover:text-text-default focus-visible:ring-2 focus-visible:ring-primary"
 		>
 			<GraduationCap className="size-4 shrink-0" />
diff --git a/apps/web/src/onboarding/OnboardingSimulation.tsx b/apps/web/src/onboarding/OnboardingSimulation.tsx
new file mode 100644
index 000000000..1c807d64c
--- /dev/null
+++ b/apps/web/src/onboarding/OnboardingSimulation.tsx
@@ -0,0 +1,574 @@
+import { Check, Folder, FolderOpen, GitBranch, House, Plus, Send } from "lucide-react";
+import { type ReactNode, useEffect, useRef, useState } from "react";
+import { Button } from "../components/ui/button";
+import { Popover, PopoverAnchor, PopoverArrow, PopoverContent } from "../components/ui/popover";
+import { PRODUCT_NAME } from "../constants/branding";
+import { useAppStore } from "../store";
+import { useTargetRect } from "./anchor";
+
+const TASK_1 = "Add search functionality to the To Do app.";
+const TASK_2 = "Add a filter for completed tasks.";
+const RESULT_1 =
+	"Added a live search box that filters tasks as you type — a new searchTasks() in src/app.js wired to an input in index.html.";
+const RESULT_2 =
+	"Added an All / Active / Completed filter above the list, with the chosen filter remembered across reloads.";
+
+type Step =
+	| "open"
+	| "picker"
+	| "ws1-create"
+	| "ws2-create"
+	| "agent1"
+	| "agent2-switch"
+	| "agent2"
+	| "done";
+
+type WsStatus = "idle" | "working" | "done";
+type Msg = { id: string; role: "user" | "assistant" | "working"; text?: string };
+
+const COACH: Record<
+	Exclude<Step, "done">,
+	{ n: number; title: string; body: string; selector: string; side: "top" | "right"; task?: string }
+> = {
+	open: {
+		n: 1,
+		title: "Open a project",
+		body: "Choose a project folder from your computer.",
+		selector: '[data-sim="open-project"]',
+		side: "top",
+	},
+	picker: {
+		n: 1,
+		title: "Choose your project folder",
+		body: "Select the To Do App folder to open it in ThinkRail.",
+		selector: '[data-sim="folder"]',
+		side: "right",
+	},
+	"ws1-create": {
+		n: 2,
+		title: "Create a workspace",
+		body: "ThinkRail runs each task in its own isolated worktree and branch. Create one for the first task.",
+		selector: '[data-sim="rail-add"]',
+		side: "right",
+	},
+	"ws2-create": {
+		n: 2,
+		title: "Create a second workspace",
+		body: "Now create a second workspace so two tasks can run side by side, each on its own branch.",
+		selector: '[data-sim="rail-add"]',
+		side: "right",
+	},
+	agent1: {
+		n: 3,
+		title: "Start the first agent",
+		body: "Ask the agent to build the first feature, then send it.",
+		selector: '[data-sim="composer"]',
+		side: "top",
+		task: TASK_1,
+	},
+	"agent2-switch": {
+		n: 4,
+		title: "Switch to your second workspace",
+		body: "Your first agent keeps working independently — switch over to start the next one.",
+		selector: '[data-sim="ws-1"]',
+		side: "right",
+	},
+	agent2: {
+		n: 4,
+		title: "Run a second agent in parallel",
+		body: "Start the second task here. Both agents now run at the same time, each in its own workspace.",
+		selector: '[data-sim="composer"]',
+		side: "top",
+		task: TASK_2,
+	},
+};
+
+const WS_NAMES = ["Add search", "Completed filter"];
+
+export function OnboardingSimulation() {
+	const open = useAppStore((s) => s.demoOpen);
+	if (!open) return null;
+	return <Simulation />;
+}
+
+function useElementRect(el: HTMLElement | null): DOMRect | null {
+	const [rect, setRect] = useState<DOMRect | null>(null);
+	useEffect(() => {
+		if (!el) return;
+		let frame = 0;
+		const measure = () => {
+			setRect(el.getBoundingClientRect());
+			frame = requestAnimationFrame(measure);
+		};
+		measure();
+		return () => cancelAnimationFrame(frame);
+	}, [el]);
+	return rect;
+}
+
+function Simulation() {
+	const closeDemo = useAppStore((s) => s.closeDemo);
+	const [cardEl, setCardEl] = useState<HTMLDivElement | null>(null);
+	const cardRect = useElementRect(cardEl);
+	const [step, setStep] = useState<Step>("open");
+	const [workspaces, setWorkspaces] = useState<string[]>([]);
+	const [activeWs, setActiveWs] = useState(0);
+	const [drafts, setDrafts] = useState<Record<number, string>>({});
+	const [messages, setMessages] = useState<Record<number, Msg[]>>({});
+	const [status, setStatus] = useState<Record<number, WsStatus>>({});
+	const timers = useRef<ReturnType<typeof setTimeout>[]>([]);
+	useEffect(() => () => timers.current.forEach(clearTimeout), []);
+
+	const projectOpen = step !== "open" && step !== "picker";
+	const coach = step === "done" ? null : COACH[step];
+
+	const onRailAdd = () => {
+		if (step === "ws1-create") {
+			setWorkspaces([WS_NAMES[0] as string]);
+			setStep("ws2-create");
+		} else if (step === "ws2-create") {
+			setWorkspaces([WS_NAMES[0] as string, WS_NAMES[1] as string]);
+			setActiveWs(0);
+			setStep("agent1");
+		}
+	};
+
+	const onWsClick = (index: number) => {
+		if (step === "agent2-switch" && index === 1) {
+			setActiveWs(1);
+			setStep("agent2");
+		}
+	};
+
+	const insertTask = () => {
+		if (coach?.task) setDrafts((d) => ({ ...d, [activeWs]: coach.task as string }));
+	};
+
+	const send = () => {
+		const ws = activeWs;
+		const text = (drafts[ws] ?? "").trim();
+		if (!text || status[ws] === "working") return;
+		const result = ws === 0 ? RESULT_1 : RESULT_2;
+		setDrafts((d) => ({ ...d, [ws]: "" }));
+		setStatus((s) => ({ ...s, [ws]: "working" }));
+		setMessages((m) => ({
+			...m,
+			[ws]: [
+				...(m[ws] ?? []),
+				{ id: crypto.randomUUID(), role: "user", text },
+				{ id: crypto.randomUUID(), role: "working" },
+			],
+		}));
+		const timer = setTimeout(() => {
+			setMessages((m) => ({
+				...m,
+				[ws]: [
+					...(m[ws] ?? []).filter((msg) => msg.role !== "working"),
+					{ id: crypto.randomUUID(), role: "assistant", text: result },
+				],
+			}));
+			setStatus((s) => ({ ...s, [ws]: "done" }));
+			setStep(ws === 0 ? "agent2-switch" : "done");
+		}, 1400);
+		timers.current.push(timer);
+	};
+
+	return (
+		<div className="fixed inset-0 z-40 flex items-center justify-center bg-overlay p-lg">
+			<div
+				ref={setCardEl}
+				role="dialog"
+				aria-modal="true"
+				aria-label="ThinkRail onboarding demo"
+				data-testid="onboarding-sim"
+				className="relative flex h-[90vh] w-[90vw] flex-col overflow-hidden rounded-[var(--radius-lg)] border border-border-default bg-container-workspace-bg shadow-[var(--shadow-lg)]"
+			>
+				<div className="flex h-11 shrink-0 items-center gap-md border-border-default border-b bg-container-header-bg px-lg">
+					<span className="tr-title-card text-primary">{PRODUCT_NAME}</span>
+					{projectOpen ? (
+						<span className="tr-text-ui text-text-muted">
+							To Do App
+							{workspaces[activeWs] ? ` · ${workspaces[activeWs]}` : ""}
+						</span>
+					) : null}
+				</div>
+
+				<div className="flex min-h-0 flex-1">
+					<SimLeftPanel
+						projectOpen={projectOpen}
+						workspaces={workspaces}
+						activeWs={activeWs}
+						status={status}
+						step={step}
+						onRailAdd={onRailAdd}
+						onWsClick={onWsClick}
+					/>
+					<SimCenter
+						step={step}
+						activeWs={activeWs}
+						messages={messages}
+						status={status}
+						draft={drafts[activeWs] ?? ""}
+						onDraft={(v) => setDrafts((d) => ({ ...d, [activeWs]: v }))}
+						onOpenProject={() => setStep("picker")}
+						onPickFolder={() => setStep("ws1-create")}
+						onSend={send}
+					/>
+				</div>
+
+				{coach ? (
+					<CardSpotlight
+						cardRect={cardRect}
+						selector={coach.selector}
+						side={coach.side}
+						step={coach.n}
+						title={coach.title}
+						body={coach.body}
+						{...(coach.task ? { onInsert: insertTask } : {})}
+					/>
+				) : (
+					<Completion onFinish={() => closeDemo()} />
+				)}
+			</div>
+		</div>
+	);
+}
+
+function SimLeftPanel({
+	projectOpen,
+	workspaces,
+	activeWs,
+	status,
+	step,
+	onRailAdd,
+	onWsClick,
+}: {
+	projectOpen: boolean;
+	workspaces: string[];
+	activeWs: number;
+	status: Record<number, WsStatus>;
+	step: Step;
+	onRailAdd: () => void;
+	onWsClick: (index: number) => void;
+}) {
+	return (
+		<aside className="flex w-[220px] shrink-0 flex-col gap-sm border-border-default border-r bg-container-sidebar-bg p-md">
+			<span className="tr-text-eyebrow text-text-muted">Projects</span>
+			{projectOpen ? (
+				<>
+					<div className="flex h-7 items-center justify-between gap-xs pr-xs pl-sm">
+						<span className="flex min-w-0 items-center gap-sm tr-text-ui text-text-default">
+							<Folder className="size-4 shrink-0 text-primary" />
+							<span className="truncate">To Do App</span>
+						</span>
+						<button
+							type="button"
+							data-sim="rail-add"
+							data-testid="sim-add-workspace"
+							aria-label="Create workspace"
+							onClick={onRailAdd}
+							className="flex size-5 shrink-0 items-center justify-center rounded-[var(--radius-sm)] text-text-muted transition-colors hover:bg-container-elevated-bg hover:text-text-default"
+						>
+							<Plus className="size-4" />
+						</button>
+					</div>
+					<ul className="flex flex-col">
+						<li>
+							<span className="flex h-7 items-center gap-sm rounded-[var(--radius-sm)] pr-xs pl-xl tr-text-ui text-text-muted">
+								<House className="size-4 shrink-0" />
+								Default
+							</span>
+						</li>
+						{workspaces.map((name, index) => (
+							<li key={name}>
+								<button
+									type="button"
+									data-sim={`ws-${index}`}
+									data-testid={`sim-ws-${index}`}
+									onClick={() => onWsClick(index)}
+									className={`flex h-7 w-full items-center gap-sm rounded-[var(--radius-sm)] pr-xs pl-xl text-left tr-text-ui transition-colors ${
+										index === activeWs
+											? "bg-control-bg-selected text-primary"
+											: "text-text-muted hover:bg-control-bg-hovered"
+									}`}
+								>
+									<GitBranch className="size-4 shrink-0" />
+									<span className="flex-1 truncate">{name}</span>
+									{status[index] === "working" ? (
+										<span className="size-2 shrink-0 animate-pulse rounded-full bg-primary" />
+									) : null}
+									{status[index] === "done" ? (
+										<Check className="size-3.5 shrink-0 text-feedback-success" />
+									) : null}
+								</button>
+							</li>
+						))}
+					</ul>
+					{step === "agent2" || step === "agent2-switch" ? (
+						<span className="mt-sm pl-sm text-text-subtle tr-text-metadata leading-snug">
+							Both workspaces keep their own agent session — switching tabs never stops them.
+						</span>
+					) : null}
+				</>
+			) : (
+				<span className="pl-sm text-text-subtle tr-text-metadata">No project open</span>
+			)}
+		</aside>
+	);
+}
+
+function SimCenter({
+	step,
+	activeWs,
+	messages,
+	status,
+	draft,
+	onDraft,
+	onOpenProject,
+	onPickFolder,
+	onSend,
+}: {
+	step: Step;
+	activeWs: number;
+	messages: Record<number, Msg[]>;
+	status: Record<number, WsStatus>;
+	draft: string;
+	onDraft: (value: string) => void;
+	onOpenProject: () => void;
+	onPickFolder: () => void;
+	onSend: () => void;
+}) {
+	if (step === "open") {
+		return (
+			<Center>
+				<h1 className="tr-brand-hero text-primary">{PRODUCT_NAME}</h1>
+				<div className="mt-xl">
+					<button
+						type="button"
+						data-sim="open-project"
+						data-testid="sim-open-project"
+						onClick={onOpenProject}
+						className="relative flex h-[150px] w-[220px] flex-col items-start justify-between rounded-[var(--radius-sm)] border border-primary-muted bg-clip-padding bg-primary-subtle p-lg text-left transition-colors hover:bg-primary-soft"
+					>
+						<span className="flex size-9 items-center justify-center rounded-[var(--radius-sm)] bg-primary text-text-on-primary">
+							<FolderOpen className="size-4" />
+						</span>
+						<span className="w-full">
+							<span className="block tr-title-card text-text-default">Open project</span>
+							<span className="mt-0.5 block text-text-muted tr-text-metadata leading-snug">
+								Choose a local git repository to work in.
+							</span>
+						</span>
+					</button>
+				</div>
+			</Center>
+		);
+	}
+	if (step === "picker") {
+		return (
+			<Center>
+				<div className="w-[440px] overflow-hidden rounded-[var(--radius-lg)] border border-border-default bg-container-elevated-bg shadow-[var(--shadow-md)]">
+					<div className="flex items-center gap-xs border-border-default border-b px-lg py-md tr-text-metadata text-text-muted">
+						<Folder className="size-3.5" />
+						<span>Home</span>
+						<span>/</span>
+						<span>Projects</span>
+					</div>
+					<ul className="p-sm">
+						<li>
+							<button
+								type="button"
+								data-sim="folder"
+								data-testid="sim-folder"
+								onClick={onPickFolder}
+								className="flex w-full items-center gap-sm rounded-[var(--radius-sm)] px-md py-sm text-left tr-text-ui text-text-default transition-colors hover:bg-control-bg-hovered"
+							>
+								<Folder className="size-4 text-primary" />
+								<span>to-do-app</span>
+							</button>
+						</li>
+					</ul>
+				</div>
+			</Center>
+		);
+	}
+	if (step === "ws1-create" || step === "ws2-create") {
+		return (
+			<Center>
+				<p className="tr-title-card text-text-default">To Do App</p>
+				<p className="mt-xs max-w-[420px] text-text-muted tr-text-metadata leading-snug">
+					Create a workspace for each task. Every workspace is an isolated git worktree on its own
+					branch, so two features never collide.
+				</p>
+			</Center>
+		);
+	}
+	const rows = messages[activeWs] ?? [];
+	return (
+		<div className="flex min-h-0 flex-1 flex-col bg-container-content-bg">
+			<div className="flex min-h-0 flex-1 flex-col gap-sm overflow-auto p-lg">
+				{rows.length === 0 ? (
+					<p className="m-auto text-text-subtle tr-text-metadata">
+						Start the agent below to build this task.
+					</p>
+				) : (
+					rows.map((msg) =>
+						msg.role === "user" ? (
+							<div
+								key={msg.id}
+								className="max-w-[80%] self-end rounded-[var(--radius-md)] border border-bubble-user-border bg-bubble-user-bg px-md py-sm tr-text-ui text-text-default"
+							>
+								{msg.text}
+							</div>
+						) : msg.role === "working" ? (
+							<div
+								key={msg.id}
+								className="inline-flex items-center gap-sm self-start text-text-muted tr-text-metadata"
+							>
+								<span className="size-2 animate-pulse rounded-full bg-primary" />
+								Working…
+							</div>
+						) : (
+							<div key={msg.id} className="max-w-[80%] self-start tr-text-ui text-text-default">
+								{msg.text}
+							</div>
+						),
+					)
+				)}
+			</div>
+			<div data-sim="composer" className="border-border-default border-t p-md">
+				<div className="flex items-end gap-sm rounded-[var(--radius-md)] border border-control-border-default bg-container-workspace-bg p-sm">
+					<textarea
+						data-testid="sim-composer"
+						value={draft}
+						onChange={(event) => onDraft(event.target.value)}
+						placeholder="Ask the agent…"
+						rows={2}
+						className="min-h-[40px] flex-1 resize-none bg-transparent tr-text-ui text-text-default outline-none placeholder:text-text-subtle"
+					/>
+					<Button
+						size="sm"
+						data-testid="sim-send"
+						disabled={!draft.trim() || status[activeWs] === "working"}
+						onClick={onSend}
+					>
+						<Send className="size-4" />
+						Send
+					</Button>
+				</div>
+			</div>
+		</div>
+	);
+}
+
+function Center({ children }: { children: ReactNode }) {
+	return (
+		<div className="flex min-h-0 flex-1 flex-col items-center justify-center bg-container-content-bg p-xl text-center">
+			{children}
+		</div>
+	);
+}
+
+function CardSpotlight({
+	cardRect,
+	selector,
+	side,
+	step,
+	title,
+	body,
+	onInsert,
+}: {
+	cardRect: DOMRect | null;
+	selector: string;
+	side: "top" | "right";
+	step: number;
+	title: string;
+	body: string;
+	onInsert?: () => void;
+}) {
+	const rect = useTargetRect(selector);
+	if (!rect || !cardRect) return null;
+	const left = rect.left - cardRect.left;
+	const top = rect.top - cardRect.top;
+	const dim = "pointer-events-auto absolute bg-container-workspace-overlay";
+	const clamp = (value: number) => Math.max(0, value);
+	return (
+		<div className="pointer-events-none absolute inset-0 z-40 overflow-hidden">
+			<div className={dim} style={{ left: 0, top: 0, width: cardRect.width, height: clamp(top) }} />
+			<div
+				className={dim}
+				style={{
+					left: 0,
+					top: top + rect.height,
+					width: cardRect.width,
+					height: clamp(cardRect.height - (top + rect.height)),
+				}}
+			/>
+			<div className={dim} style={{ left: 0, top, width: clamp(left), height: rect.height }} />
+			<div
+				className={dim}
+				style={{
+					left: left + rect.width,
+					top,
+					width: clamp(cardRect.width - (left + rect.width)),
+					height: rect.height,
+				}}
+			/>
+			<Popover open>
+				<PopoverAnchor asChild>
+					<div
+						aria-hidden
+						className="pointer-events-none fixed"
+						style={{ left: rect.left, top: rect.top, width: rect.width, height: rect.height }}
+					/>
+				</PopoverAnchor>
+				<PopoverContent
+					data-testid="onboarding-coach"
+					side={side}
+					align="center"
+					className="z-50 w-[260px] p-md"
+					onOpenAutoFocus={(event) => event.preventDefault()}
+					onEscapeKeyDown={(event) => event.preventDefault()}
+					onPointerDownOutside={(event) => event.preventDefault()}
+					onInteractOutside={(event) => event.preventDefault()}
+				>
+					<p className="tr-text-label-pill text-primary">Step {step} of 4</p>
+					<p className="mt-xs tr-title-card text-text-default">{title}</p>
+					<p className="mt-xs text-text-muted tr-text-metadata leading-snug">{body}</p>
+					{onInsert ? (
+						<div className="mt-md flex justify-end">
+							<Button
+								variant="outline"
+								size="sm"
+								data-testid="onboarding-insert-prompt"
+								onClick={onInsert}
+							>
+								Insert prompt
+							</Button>
+						</div>
+					) : null}
+					<PopoverArrow />
+				</PopoverContent>
+			</Popover>
+		</div>
+	);
+}
+
+function Completion({ onFinish }: { onFinish: () => void }) {
+	return (
+		<div className="absolute inset-0 z-40 flex items-center justify-center bg-container-workspace-overlay">
+			<div className="w-[360px] rounded-[var(--radius-md)] border border-border-default bg-container-elevated-bg p-lg text-center shadow-[var(--shadow-md)]">
+				<p className="tr-title-card text-text-default">You're ready to build</p>
+				<p className="mt-xs text-text-muted tr-text-metadata leading-snug">
+					You opened a project, created two isolated workspaces, and ran two agents in parallel —
+					that's the ThinkRail loop.
+				</p>
+				<div className="mt-md flex justify-center">
+					<Button size="sm" data-testid="onboarding-finish" onClick={onFinish}>
+						Finish
+					</Button>
+				</div>
+			</div>
+		</div>
+	);
+}
diff --git a/apps/web/src/onboarding/SPEC.md b/apps/web/src/onboarding/SPEC.md
index 7f8de50dc..b0894d16a 100644
--- a/apps/web/src/onboarding/SPEC.md
+++ b/apps/web/src/onboarding/SPEC.md
@@ -10,94 +10,64 @@ tags: [v1, ui, onboarding]
 
 ## Responsibility
 
-The **demo tour**: launchable any time from a persistent left-panel control, it opens on a **simulated
-empty-first-run state** (view-only — the real project registry is never touched), teaches opening a
-project through a **simulated folder picker**, then materializes the bundled To Do App demo and guides a
-newcomer through the remaining **contextual coach-mark steps** on the *real* ThinkRail interface. Every
-live step advances by the user performing a **real** action, never a synthetic one.
+A **fully self-contained, mocked onboarding simulation**: a large modal card that lets the user *feel*
+the complete ThinkRail loop — open a project, create two isolated workspaces, run two agents in parallel —
+with **zero** touch of real domain state. Nothing here calls `demo.ensure`/`demo.reset`, creates
+Projects/Workspaces/Sessions, invokes pi, opens the OS file picker, or mutates persistence. The fake
+project, two fake workspaces, folder picker, prompts, agent responses, and progress all live only in this
+component's **local React state**. It is a visual/interaction prototype, easy to iterate or remove.
 
-All coach marks use one **spotlight** treatment: the viewport is dimmed with the
-`container-workspace-overlay` scrim (the workspace surface at the `veil` 70% alpha step — a sanctioned
-color token, see `styles/colors.json`), the single actionable target stays clear + interactive, and a
-tooltip with an arrow points at it. A coach mark is **non-dismissible** — no close/Skip/Next, no
-outside-click or Escape; it clears only when its action completes. Leaving the tour is a **separate** Exit
-control (and the final done card), not a coach-mark dismissal.
+Launched from the persistent left-panel `OnboardingLauncher` (or the empty-state Welcome "Try the To Do
+App" card); both flip one **view flag** (`store.demoOpen`, a top-level, non-persisted boolean via
+`openDemo`/`closeDemo`). While open, `OnboardingSimulation` renders above the real (dimmed) UI.
 
-### Stages (`onboarding.stage`)
+## The simulated card
 
-- **`welcome`** (simulated) — a full-viewport opaque scaffold (`container-workspace-bg` shell chrome)
-  showing an empty Welcome with an "Open project" card, spotlighted ("Step 1 of 4 · Open a project").
-  Clicking it advances to `picker`. No real project exists yet.
-- **`picker`** (simulated) — a lightened Finder-like surface with a single selectable `to-do-app` folder,
-  spotlighted ("Choose your project folder"). This is a **controlled frontend simulation** — no real OS
-  picker, no filesystem/backend. Selecting it runs `startDemo` (real `demo.ensure`), which moves to `live`.
-- **`live`** — the real ThinkRail UI with the real demo project; `OnboardingCoach` spotlights the real
-  controls for steps 2–4 (create two workspaces → first agent → second agent in parallel).
+- A centered modal (~`90vw × 90vh`) over a `bg-overlay` scrim; the card is an opaque `container-workspace-bg`
+  sandbox rendering a simplified but faithful ThinkRail chrome (header / left `Projects` panel / center),
+  built from the existing semantic tokens and `components/ui` — **not** wired to any store domain state.
+- **Coach marks** reuse the tooltip + arrow treatment: a card-scoped **spotlight** dims everything inside
+  the card except the current target with the `container-workspace-overlay` scrim (the workspace surface at
+  the `veil` 70% alpha step — a sanctioned color token, see `styles/colors.json`), drawn as four
+  `pointer-events-auto` rects computed relative to the measured card rect (so only the card interior dims,
+  the raised card stays legible). The Radix `components/ui/popover` (+ `PopoverArrow`) anchors to the
+  target; Escape / outside-interaction / auto-focus are all prevented. A coach mark is **non-dismissible**
+  (no close/Skip/Next/Escape/outside-click) and advances only when its scripted action completes.
+- Only the current target is interactive; everything else is present but inert (covered by the dim).
 
-The manual launcher enters at `welcome`; the empty-state Welcome "Try the To Do App" card enters directly
-at `live` (skipping the simulation, since a genuinely-empty user needs no simulated empty state).
+## Scripted flow (local `step` state machine, numbered "of 4")
 
-## Behaviour
+1. **Open a project** — empty-state Welcome with an "Open project" card (arrow points down to it); clicking
+   opens a **fake** picker showing one `to-do-app` folder; selecting it opens the fake "To Do App" project.
+2. **Create separate workspaces** — coach sits right of the left panel, arrow pointing back at the rail
+   `+`; two clicks create two fake workspaces (`Add search`, `Completed filter`), teaching the isolated
+   worktree-per-task model. No real worktrees.
+3. **Start the first agent** — switches into the first workspace's fake composer; **Insert** fills the
+   predetermined *"Add search functionality to the To Do app."*, **Send** shows a brief "Working…" then a
+   predetermined successful result (a `setTimeout`, no model call), using the existing chat treatment.
+4. **Run agents in parallel** — coach guides switching to the second workspace and sending *"Add a filter
+   for completed tasks."*; the first workspace's row shows it already **done** while the second works —
+   the payoff that separate workspaces hold independent, concurrent sessions. A left-panel note reinforces
+   that switching tabs never stops a session.
 
-- **Entry (`startDemo`).** `demo.ensure` → adopt the returned Project (`applyProjectUpdated`), arm the
-  flow (`store.startOnboarding(projectId)`), select the project (lands on its Welcome), and load its
-  workspaces so the rail reveals it. Errors degrade to a toast. Invoked by the Welcome "Try the To Do
-  App" card (panels).
-- **The live steps** (`selectCoach`, pure over store state; the current step is *derived*, never a stored
-  counter, so it auto-advances and self-heals across reloads; numbered *of 4* since the simulated
-  open-project stage is step 1):
-  2. **Create separate workspaces** — teaches the worktree/workspace model *before* any prompt. Anchors
-     the demo Welcome's "Start building" card while zero non-Default workspaces exist, then re-anchors the
-     rail `+` for the demo project once one exists. Completes at **two** non-Default demo workspaces.
-  3. **Start the first agent** — anchors the **first** workspace's chat composer (guiding a switch to it
-     first if it isn't active) and offers one-click **Insert** of *"Add search functionality to the To Do
-     app."* Completes when that workspace's session has a sent user turn.
-  4. **Run agents in parallel** — anchors the **second** (already-created) workspace: guides the user to
-     switch to it, then anchors its composer and offers **Insert** of *"Add a filter for completed
-     tasks."* Completes when that workspace's session has a sent user turn. The first agent keeps running,
-     so parallelism is shown directly. This step never *creates* the second workspace — creation is step 2.
-  A final **done** state ("You're all set") offers **Reset demo** + **Done**.
-- **Auto-advance** is a consequence of the derived step: the step selectors read domain state (demo
-  workspace count; whether each workspace's chat has a `kind: "user"` turn — `selectOnboardingStep` /
-  `selectAgentStarted` / `selectDemoWorkspaces` in `store`). No wire traffic, no per-step store writes.
-- **Reset (`resetDemo`).** `demo.reset` (archives the demo's workspaces, drops the record, deletes the
-  copy) → re-`project.list` and re-install the snapshot (dropping the demo from Recents) → clear the
-  onboarding slice. The demo's archived workspaces self-clear via the server's `workspace.removed`
-  broadcasts. Replayable: back at the empty first-run Welcome, the "Try the To Do App" card returns.
-- **Exit** (`onboarding-exit`, a fixed corner control shown for every stage) clears the tour view state
-  (`store.resetOnboarding`) and restores the normal UI; any real demo project already created remains as a
-  normal project. This is the only manual escape — coach marks themselves never dismiss.
+**Completion** — a "You're ready to build" card with a single **Finish** action (`closeDemo`). Because the
+whole thing is local state, replaying (reopen) starts fresh at step 1.
 
-## Coach-mark mechanism
-
-- **One shell-mounted overlay** (`OnboardingDemo`); the shell composes it beside `Toaster`. It renders the
-  simulated `welcome`/`picker` scaffolds itself and delegates the `live` stage to `OnboardingCoach`.
-  Panels stay layout-agnostic — the overlay never imports panels, and resolves each target by a stable
-  attribute (`[data-testid="welcome-cta"]`, `[data-testid="chat-input"]`, `[data-onboarding="rail-add"]`
-  + `[data-project-id]`, `[data-onboarding-ws]`, and the simulated `[data-onboarding="demo-open"]` /
-  `[data-onboarding="demo-folder"]`) via `document.querySelector`, measured each animation frame so it
-  tracks scroll/layout/late mounts. A missing target simply hides the tooltip (never mispoints).
-- The shared **`Spotlight`** primitive draws four `container-workspace-overlay` dim rects around the target
-  rect (each `pointer-events-auto`, so the dimmed area both reads as inert and absorbs any outside click —
-  the non-dismissible guarantee), leaving the target hole clear + interactive, and renders the existing
-  Radix `components/ui/popover` (with a `PopoverArrow`) against a zero-size `PopoverAnchor` at the rect,
-  with Escape / outside-interaction handlers prevented.
-- Geometry (left/top/width/height) is the only inline `style`; all colour/spacing/typography use semantic
-  token utilities (precedent: `chat/turns` uses inline style for a dynamic transition duration).
-
-## Persistence
+## Boundary
 
-Per-browser localStorage under a host-qualified key (mirrors `panels/projectExpansion`): the slice
-(`flow` / `stage` / `demoProjectId` / `dismissed`) is hydrated at boot (`initOnboardingPersistence`, wired
-in `main.tsx`) and written on change, so the tour resumes where the user left it. Untrusted reads,
-best-effort writes.
+- **Public surface (barrel):** `OnboardingSimulation`, `OnboardingLauncher`, `useTargetRect` (anchor hook).
+  The store exposes `demoOpen` + `openDemo`/`closeDemo`.
+- **Allowed deps:** `store` (`demoOpen`/open/close), `components/ui` (`popover`, `button`), `constants`
+  (`PRODUCT_NAME`), `lib`, `lucide-react`, React.
+- **Forbidden:** `panels`, `shell` internals, `server`/`shared`/`pi`, `transport` (the simulation makes no
+  network/wire calls). `panels` (`WelcomePanel` card, `ProjectTree` footer launcher) call `openDemo` — a
+  one-way panels→onboarding edge, no cycle.
 
-## Boundary
+## Dormant (retained, not wired)
 
-- **Public surface (barrel):** `OnboardingDemo`, `OnboardingCoach`, `OnboardingLauncher`, `startDemo`,
-  `resetDemo`, `selectCoach`, `initOnboardingPersistence`, `readPersistedOnboarding`.
-- **Allowed deps:** `store` (slice + selectors + `toast`), `transport` (`getTransport`/`errorText`),
-  `components/ui` (`popover`, `button`), `lib`, `contracts`, `lucide-react`.
-- **Forbidden:** `panels`, `shell` internals, `server`/`shared`/`pi`. (`panels/WelcomePanel` may call the
-  `startDemo`/`resetDemo` orchestration — a one-way panels→onboarding edge; onboarding never imports
-  panels, so there is no cycle.)
+The earlier **real-domain** onboarding coach — `OnboardingDemo`, `OnboardingCoach`, `coach.ts`,
+`Spotlight.ts`, `demo.ts` (`startDemo`/`resetDemo`), `persistence.ts`, the `onboarding` store slice +
+selectors + `demo.ensure`/`demo.reset` wire — is **kept intact but unwired** (the shell mounts
+`OnboardingSimulation`, not `OnboardingDemo`; entry points call `openDemo`). It is preserved deliberately
+so this mocked prototype stays easy to iterate on or swap back, and so the server-side bundled-demo
+capability (`submodule-server-demo`) remains available for a future real flow. It touches no live UI path.
diff --git a/apps/web/src/onboarding/index.ts b/apps/web/src/onboarding/index.ts
index 79002ea70..e71c64ebc 100644
--- a/apps/web/src/onboarding/index.ts
+++ b/apps/web/src/onboarding/index.ts
@@ -3,4 +3,5 @@ export { resetDemo, startDemo } from "./demo";
 export { OnboardingCoach } from "./OnboardingCoach";
 export { OnboardingDemo } from "./OnboardingDemo";
 export { OnboardingLauncher } from "./OnboardingLauncher";
+export { OnboardingSimulation } from "./OnboardingSimulation";
 export { initOnboardingPersistence, readPersistedOnboarding } from "./persistence";
diff --git a/apps/web/src/panels/SPEC.md b/apps/web/src/panels/SPEC.md
index 7a81fe505..f6cf46695 100644
--- a/apps/web/src/panels/SPEC.md
+++ b/apps/web/src/panels/SPEC.md
@@ -21,8 +21,8 @@ arrangement (so the mobile shell is an additive layer, not a rewrite).
   workspace `+` always visible in a fixed right-edge column** (the Projects-header Add project `+` is unchanged).
   Long names truncate before the count/action; there is deliberately **no visible Close or overflow icon**.
   The nav is a full-height column with a **bottom-pinned footer** hosting the onboarding
-  **`OnboardingLauncher`** (a Help-style icon button that starts the demo tour from its simulated empty
-  state — see [[submodule-web-onboarding]]).
+  **`OnboardingLauncher`** (a Help-style icon button that opens the mocked onboarding simulation — see
+  [[submodule-web-onboarding]]).
   Hover highlights the full row and the highlight remains while its **project context menu** is open.
   Right-click opens that PR-#167-styled menu at the pointer without selecting/navigating; a scroll-cancelled
   ~700ms long press is its touch equivalent. With a project-name button focused, the standard Context Menu
@@ -173,9 +173,8 @@ hook, others quiet `welcome-action`s). Welcome is **the mode fork**: with a proj
 **"Start building"** (isolated worktree) with **"Work in project folder"** (the Default workspace) so the
 two working modes are a visible choice, not a hidden default. The cards by state: **no projects** →
 **"Open project"** + **"Try the To Do App"** (`data-testid="welcome-demo"`, `Sparkles`) — the demo entry
-that calls `onboarding`'s `startDemo` (materialize the bundled demo via `demo.ensure`, arm the onboarding
-tour, land on the demo's Welcome); **project + `hasSpecs`** → **"Start building"** (primary) + "Work in
-project folder"; **project + no specs** → a spec-first **"Set up project"** (primary) + "Start building"
+that calls `onboarding`'s `openDemo` (opens the fully mocked onboarding simulation — no real project is
+created); **project + `hasSpecs`** → **"Start building"** (primary) + "Work in project folder"; **project + no specs** → a spec-first **"Set up project"** (primary) + "Start building"
 + "Work in project folder". **"Open project" appears only in the no-projects state** — where it's the
 only possible action; once a project is shown, opening another is the projects-rail **"+"** (the same
 dropdown), so Welcome stays the *work-in-this-project* surface. That card hangs the shared
@@ -183,10 +182,8 @@ dropdown), so Welcome stays the *work-in-this-project* surface. That card hangs
 / Recents). Recents is the store's `recentProjects`: one last-opened path list containing open + closed
 records with no status badge; selecting either runs the shared open flow and lands at Project Home, with a
 closed record retaining its id and workspace state. `Card` is a `forwardRef` usable as a Radix `asChild`
-trigger. When the shown project **is** the active demo (`store.onboarding.demoProjectId`), Welcome also
-renders a quiet **"Reset demo"** text button (`data-testid="welcome-reset-demo"`) that calls
-`onboarding`'s `resetDemo` — the replay door (see [[submodule-web-onboarding]]). The demo entry/reset
-orchestration lives in `onboarding` (a one-way panels→onboarding edge); Welcome never owns the tour. **"Work in project folder"**
+trigger. The demo entry lives in `onboarding` (a one-way panels→onboarding edge); Welcome never owns the
+tour (see [[submodule-web-onboarding]]). **"Work in project folder"**
 (`House` icon, matching the rail's Default row) **direct-enters** the Default workspace — no dialog: the
 shared `enterDefaultWorkspace` helper lists the project's workspaces, stores them, and activates the
 `kind === "default"` row; an older host with no Default row degrades to an error toast. **"Start building"** is the
@@ -458,9 +455,9 @@ a project picker, the prompt hero, and the reused
   panes, singleton side tools, terminal bodies, Settings, and `Toaster`), imported **per-file** so
   Monaco/shiki/xterm stay lazy. Tab strips, group headers, side stacks, and center topology are not panel
   surfaces; the shell layout module wraps these renderers.
-- **Allowed deps:** `onboarding` (`WelcomePanel` calls its `startDemo`/`resetDemo` orchestration and
-  `ProjectTree` mounts its `OnboardingLauncher` at the left-panel footer — one-way panels→onboarding, no
-  cycle); `store`, `transport`, `components/ui` (incl. `popover`/`command`/`textarea` for the
+- **Allowed deps:** `onboarding` (`WelcomePanel` + `ProjectTree`'s footer `OnboardingLauncher` call
+  `openDemo` to open the mocked simulation — one-way panels→onboarding, no cycle); `store`, `transport`,
+  `components/ui` (incl. `popover`/`command`/`textarea` for the
   dialog), `chat` (`ModelSelector`/`ThinkingSelector` + the `useModelCatalog` hook that feeds them,
   reused by `NewWorkspaceDialog`; `Markdown`,
   reused by `MarkdownPreview`; `TemplateEditorDialog`, reused by `TemplatesSettings`), `lib`, `themes` (catalog + generic application contract),
diff --git a/apps/web/src/panels/WelcomePanel.tsx b/apps/web/src/panels/WelcomePanel.tsx
index d1d7a7c32..d71d3987e 100644
--- a/apps/web/src/panels/WelcomePanel.tsx
+++ b/apps/web/src/panels/WelcomePanel.tsx
@@ -3,7 +3,7 @@ import { FolderOpen, House, type LucideIcon, Rocket, Sparkles } from "lucide-rea
 import { type ComponentPropsWithoutRef, forwardRef, useEffect, useState } from "react";
 import { cn } from "@/lib/utils";
 import { PRODUCT_NAME } from "../constants/branding";
-import { resetDemo, startDemo } from "../onboarding/demo";
+
 import { useAppStore } from "../store";
 import { getTransport } from "../transport";
 import { AddProjectMenu } from "./AddProjectMenu";
@@ -22,7 +22,7 @@ export function WelcomePanel() {
 	const projects = useAppStore((s) => s.projects);
 	const recentProjects = useAppStore((s) => s.recentProjects);
 	const selectedProjectId = useAppStore((s) => s.selectedProjectId);
-	const demoProjectId = useAppStore((s) => s.onboarding.demoProjectId);
+	const openDemo = useAppStore((s) => s.openDemo);
 	const [dialog, setDialog] = useState<{
 		projectId: string;
 		prompt: string;
@@ -81,9 +81,9 @@ export function WelcomePanel() {
 		<Card
 			icon={Sparkles}
 			title="Try the To Do App"
-			subtitle="Spin up a ready-made demo project and learn the ThinkRail loop in three quick steps."
+			subtitle="Take a guided, interactive tour of the ThinkRail loop — no setup required."
 			data-testid="welcome-demo"
-			onClick={() => void startDemo()}
+			onClick={() => openDemo()}
 		/>
 	);
 
@@ -165,17 +165,6 @@ export function WelcomePanel() {
 				)}
 			</div>
 
-			{project && demoProjectId === project.id ? (
-				<button
-					type="button"
-					data-testid="welcome-reset-demo"
-					onClick={() => void resetDemo()}
-					className="mt-lg text-text-muted tr-text-metadata underline underline-offset-2 hover:text-text-default"
-				>
-					Reset demo
-				</button>
-			) : null}
-
 			{dialog ? (
 				<NewWorkspaceDialog
 					open
diff --git a/apps/web/src/shell/Shell.tsx b/apps/web/src/shell/Shell.tsx
index 74b93ba88..baacc98bf 100644
--- a/apps/web/src/shell/Shell.tsx
+++ b/apps/web/src/shell/Shell.tsx
@@ -1,7 +1,7 @@
 import { ChevronRight, GitBranch, Settings } from "lucide-react";
 import { useEffect, useRef } from "react";
 import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from "../components/ui/resizable";
-import { OnboardingDemo } from "../onboarding";
+import { OnboardingSimulation } from "../onboarding";
 import { ProjectTree } from "../panels/ProjectTree";
 import { SettingsDialog } from "../panels/SettingsDialog";
 import { Toaster } from "../panels/Toaster";
@@ -218,7 +218,7 @@ export function Shell() {
 				</div>
 			)}
 			<Toaster />
-			<OnboardingDemo />
+			<OnboardingSimulation />
 		</div>
 	);
 }
diff --git a/apps/web/src/store/appStore.ts b/apps/web/src/store/appStore.ts
index 16717d743..dcbd76a3f 100644
--- a/apps/web/src/store/appStore.ts
+++ b/apps/web/src/store/appStore.ts
@@ -664,6 +664,7 @@ interface AppState {
 	layoutSettings: LayoutSettings;
 	toasts: Toast[];
 	onboarding: OnboardingState;
+	demoOpen: boolean;
 	setStatus: (status: ConnectionStatus) => void;
 	installWelcomeSnapshot: (
 		protocolVersion: number,
@@ -831,6 +832,8 @@ interface AppState {
 	applyReviewChanged: (payload: ReviewChangedPayload) => void;
 	pushToast: (toast: Omit<Toast, "id">) => string;
 	dismissToast: (id: string) => void;
+	openDemo: () => void;
+	closeDemo: () => void;
 	startDemoTour: () => void;
 	setDemoStage: (stage: OnboardingStage) => void;
 	startOnboarding: (demoProjectId: string) => void;
@@ -1329,6 +1332,7 @@ export const useAppStore = create<AppState>((set, get) => ({
 	layoutSettings: DEFAULT_CONFIG.layout,
 	toasts: [],
 	onboarding: NO_ONBOARDING,
+	demoOpen: false,
 	setStatus: (status) =>
 		set((state) => ({
 			status,
@@ -2785,6 +2789,8 @@ export const useAppStore = create<AppState>((set, get) => ({
 		set((s) =>
 			s.toasts.some((t) => t.id === id) ? { toasts: s.toasts.filter((t) => t.id !== id) } : {},
 		),
+	openDemo: () => set({ demoOpen: true }),
+	closeDemo: () => set({ demoOpen: false }),
 	startDemoTour: () =>
 		set({ onboarding: { flow: "demo", stage: "welcome", demoProjectId: null, dismissed: false } }),
 	setDemoStage: (stage) => set((s) => ({ onboarding: { ...s.onboarding, stage } })),
diff --git a/e2e/onboarding-demo.spec.ts b/e2e/onboarding-demo.spec.ts
index 9d7a06e7b..fba725dee 100644
--- a/e2e/onboarding-demo.spec.ts
+++ b/e2e/onboarding-demo.spec.ts
@@ -1,54 +1,56 @@
-import { rmSync } from "node:fs";
-import { join } from "node:path";
 import { expect, test } from "@playwright/test";
-import { createWorkspaceViaDialog, openAppFresh, worktreeRows } from "./fixtures/app";
-import { E2E_DATA_DIR } from "./fixtures/paths";
+import { openAppFresh } from "./fixtures/app";
 
-test.beforeEach(() => {
-	rmSync(join(E2E_DATA_DIR, "demo"), { recursive: true, force: true });
-});
-
-test("the left-panel launcher runs the simulated empty-state flow into the live demo", async ({
+test("the launcher runs the fully mocked onboarding simulation, never touching real projects", async ({
 	page,
 }) => {
 	await openAppFresh(page);
+	await expect(page.getByTestId("project-item")).toHaveCount(0);
 
 	await page.getByTestId("onboarding-launch").click();
-
+	await expect(page.getByTestId("onboarding-sim")).toBeVisible();
 	const coach = page.getByTestId("onboarding-coach");
+
 	await expect(coach).toContainText("Step 1 of 4");
 	await expect(coach).toContainText("Open a project");
-	await page.getByTestId("demo-open-project").click();
+	await page.getByTestId("sim-open-project").click();
 
 	await expect(coach).toContainText("Choose your project folder");
-	await page.getByTestId("demo-folder-todo").click();
+	await page.getByTestId("sim-folder").click();
 
-	await expect(page.getByTestId("project-item")).toHaveCount(1);
-	await expect(page.getByTestId("welcome-title")).toHaveText("To Do App");
 	await expect(coach).toContainText("Step 2 of 4");
-
-	await page.getByTestId("welcome-cta").click();
-	await expect(page.getByTestId("new-workspace-dialog")).toBeVisible();
-	await page.getByTestId("create-workspace").click();
-	await expect(worktreeRows(page)).toHaveCount(1);
-
+	await page.getByTestId("sim-add-workspace").click();
 	await expect(coach).toContainText("Step 2 of 4");
-	await createWorkspaceViaDialog(page);
-	await expect(worktreeRows(page)).toHaveCount(2);
+	await page.getByTestId("sim-add-workspace").click();
 
 	await expect(coach).toContainText("Step 3 of 4");
-
-	await page.getByTestId("onboarding-exit").click();
-	await expect(page.getByTestId("onboarding-coach")).toHaveCount(0);
+	await page.getByTestId("onboarding-insert-prompt").click();
+	await expect(page.getByTestId("sim-composer")).toHaveValue(
+		"Add search functionality to the To Do app.",
+	);
+	await page.getByTestId("sim-send").click();
+
+	await expect(coach).toContainText("Step 4 of 4");
+	await expect(coach).toContainText("Switch to your second workspace");
+	await page.getByTestId("sim-ws-1").click();
+
+	await expect(coach).toContainText("Run a second agent in parallel");
+	await page.getByTestId("onboarding-insert-prompt").click();
+	await expect(page.getByTestId("sim-composer")).toHaveValue("Add a filter for completed tasks.");
+	await page.getByTestId("sim-send").click();
+
+	await expect(page.getByTestId("onboarding-finish")).toBeVisible();
+	await page.getByTestId("onboarding-finish").click();
+	await expect(page.getByTestId("onboarding-sim")).toHaveCount(0);
+
+	await expect(page.getByTestId("project-item")).toHaveCount(0);
 });
 
-test("the empty-state Welcome card starts the demo directly at the live coach", async ({ page }) => {
+test("the empty-state Welcome card also opens the mocked simulation", async ({ page }) => {
 	await openAppFresh(page);
 	await page.getByTestId("welcome-demo").click();
 
-	await expect(page.getByTestId("project-item")).toHaveCount(1);
-	await expect(page.getByTestId("onboarding-coach")).toContainText("Step 2 of 4");
-
-	await page.getByTestId("onboarding-exit").click();
-	await expect(page.getByTestId("onboarding-coach")).toHaveCount(0);
+	await expect(page.getByTestId("onboarding-sim")).toBeVisible();
+	await expect(page.getByTestId("onboarding-coach")).toContainText("Step 1 of 4");
+	await expect(page.getByTestId("project-item")).toHaveCount(0);
 });

From 6e57f4848f17817470fe27192736283b37d2c5d0 Mon Sep 17 00:00:00 2001
From: "Julia.Shilova" <Julia.Shilova@MacBook-Pro-5.local>
Date: Tue, 25 Aug 2026 11:14:52 +0300
Subject: [PATCH 14/23] feat(web): refine the mocked onboarding demo
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Animated intro: three staggered fade/translate lines (Welcome / product
  one-liner / ~2-min setup note) before the first coach mark, then auto-
  advance into opening the demo project. Reduced-motion shows them static.
- Persistent quiet 'Close demo' (ghost Button, top-right), available during
  the intro and every step; the only pre-completion exit. Coach marks stay
  non-dismissible. Closes only the mocked experience.
- Overlay softened 70%→50%: retuned the container-workspace-overlay's veil
  alpha step (still derived from the workspace background), so the ThinkRail
  interface reads clearly under the spotlight. colors bumped to v1.3.0.
- Coach tooltips drop the 'Step N of 4' line — title + instruction only.
- Added one global 1px bg-primary progress line on the card's bottom edge,
  advancing across the scripted flow with a smooth width transition.
- Active target gets a temporary ring-2 ring-primary pulse (motion-safe;
  static under reduced motion), moving with the coach, never a permanent
  component state.

Scripted flow, mocked isolation, and design-system usage unchanged; no
backend/wire/domain calls. Specs + e2e updated.
---
 .../src/onboarding/OnboardingSimulation.tsx   | 105 ++++++++++++++----
 apps/web/src/onboarding/SPEC.md               |  24 +++-
 apps/web/src/styles/colors.json               |   6 +-
 apps/web/src/styles/generated/colors.css      |   4 +-
 e2e/onboarding-demo.spec.ts                   |  27 ++---
 5 files changed, 121 insertions(+), 45 deletions(-)

diff --git a/apps/web/src/onboarding/OnboardingSimulation.tsx b/apps/web/src/onboarding/OnboardingSimulation.tsx
index 1c807d64c..176d3b84e 100644
--- a/apps/web/src/onboarding/OnboardingSimulation.tsx
+++ b/apps/web/src/onboarding/OnboardingSimulation.tsx
@@ -1,5 +1,5 @@
-import { Check, Folder, FolderOpen, GitBranch, House, Plus, Send } from "lucide-react";
-import { type ReactNode, useEffect, useRef, useState } from "react";
+import { Check, Folder, FolderOpen, GitBranch, House, Plus, Send, X } from "lucide-react";
+import { type ReactNode, useCallback, useEffect, useRef, useState } from "react";
 import { Button } from "../components/ui/button";
 import { Popover, PopoverAnchor, PopoverArrow, PopoverContent } from "../components/ui/popover";
 import { PRODUCT_NAME } from "../constants/branding";
@@ -14,6 +14,7 @@ const RESULT_2 =
 	"Added an All / Active / Completed filter above the list, with the chosen filter remembered across reloads.";
 
 type Step =
+	| "intro"
 	| "open"
 	| "picker"
 	| "ws1-create"
@@ -23,43 +24,50 @@ type Step =
 	| "agent2"
 	| "done";
 
+const STEP_ORDER: Step[] = [
+	"intro",
+	"open",
+	"picker",
+	"ws1-create",
+	"ws2-create",
+	"agent1",
+	"agent2-switch",
+	"agent2",
+	"done",
+];
+
 type WsStatus = "idle" | "working" | "done";
 type Msg = { id: string; role: "user" | "assistant" | "working"; text?: string };
 
 const COACH: Record<
-	Exclude<Step, "done">,
-	{ n: number; title: string; body: string; selector: string; side: "top" | "right"; task?: string }
+	Exclude<Step, "intro" | "done">,
+	{ title: string; body: string; selector: string; side: "top" | "right"; task?: string }
 > = {
 	open: {
-		n: 1,
 		title: "Open a project",
 		body: "Choose a project folder from your computer.",
 		selector: '[data-sim="open-project"]',
 		side: "top",
 	},
 	picker: {
-		n: 1,
 		title: "Choose your project folder",
 		body: "Select the To Do App folder to open it in ThinkRail.",
 		selector: '[data-sim="folder"]',
 		side: "right",
 	},
 	"ws1-create": {
-		n: 2,
 		title: "Create a workspace",
 		body: "ThinkRail runs each task in its own isolated worktree and branch. Create one for the first task.",
 		selector: '[data-sim="rail-add"]',
 		side: "right",
 	},
 	"ws2-create": {
-		n: 2,
 		title: "Create a second workspace",
 		body: "Now create a second workspace so two tasks can run side by side, each on its own branch.",
 		selector: '[data-sim="rail-add"]',
 		side: "right",
 	},
 	agent1: {
-		n: 3,
 		title: "Start the first agent",
 		body: "Ask the agent to build the first feature, then send it.",
 		selector: '[data-sim="composer"]',
@@ -67,14 +75,12 @@ const COACH: Record<
 		task: TASK_1,
 	},
 	"agent2-switch": {
-		n: 4,
 		title: "Switch to your second workspace",
 		body: "Your first agent keeps working independently — switch over to start the next one.",
 		selector: '[data-sim="ws-1"]',
 		side: "right",
 	},
 	agent2: {
-		n: 4,
 		title: "Run a second agent in parallel",
 		body: "Start the second task here. Both agents now run at the same time, each in its own workspace.",
 		selector: '[data-sim="composer"]',
@@ -110,7 +116,8 @@ function Simulation() {
 	const closeDemo = useAppStore((s) => s.closeDemo);
 	const [cardEl, setCardEl] = useState<HTMLDivElement | null>(null);
 	const cardRect = useElementRect(cardEl);
-	const [step, setStep] = useState<Step>("open");
+	const [step, setStep] = useState<Step>("intro");
+	const startTour = useCallback(() => setStep("open"), []);
 	const [workspaces, setWorkspaces] = useState<string[]>([]);
 	const [activeWs, setActiveWs] = useState(0);
 	const [drafts, setDrafts] = useState<Record<number, string>>({});
@@ -119,8 +126,9 @@ function Simulation() {
 	const timers = useRef<ReturnType<typeof setTimeout>[]>([]);
 	useEffect(() => () => timers.current.forEach(clearTimeout), []);
 
-	const projectOpen = step !== "open" && step !== "picker";
-	const coach = step === "done" ? null : COACH[step];
+	const projectOpen = step !== "intro" && step !== "open" && step !== "picker";
+	const coach = step === "intro" || step === "done" ? null : COACH[step];
+	const progress = STEP_ORDER.indexOf(step) / (STEP_ORDER.length - 1);
 
 	const onRailAdd = () => {
 		if (step === "ws1-create") {
@@ -183,6 +191,16 @@ function Simulation() {
 				data-testid="onboarding-sim"
 				className="relative flex h-[90vh] w-[90vw] flex-col overflow-hidden rounded-[var(--radius-lg)] border border-border-default bg-container-workspace-bg shadow-[var(--shadow-lg)]"
 			>
+				<Button
+					variant="ghost"
+					size="sm"
+					data-testid="onboarding-close"
+					onClick={() => closeDemo()}
+					className="absolute top-sm right-sm z-50"
+				>
+					<X className="size-4" />
+					Close demo
+				</Button>
 				<div className="flex h-11 shrink-0 items-center gap-md border-border-default border-b bg-container-header-bg px-lg">
 					<span className="tr-title-card text-primary">{PRODUCT_NAME}</span>
 					{projectOpen ? (
@@ -216,19 +234,26 @@ function Simulation() {
 					/>
 				</div>
 
+				{step === "intro" ? <Intro onDone={startTour} /> : null}
 				{coach ? (
 					<CardSpotlight
 						cardRect={cardRect}
 						selector={coach.selector}
 						side={coach.side}
-						step={coach.n}
 						title={coach.title}
 						body={coach.body}
 						{...(coach.task ? { onInsert: insertTask } : {})}
 					/>
-				) : (
-					<Completion onFinish={() => closeDemo()} />
-				)}
+				) : null}
+				{step === "done" ? <Completion onFinish={() => closeDemo()} /> : null}
+
+				<div className="pointer-events-none absolute inset-x-0 bottom-0 z-50 h-px">
+					<div
+						data-testid="onboarding-progress"
+						className="h-full bg-primary transition-[width] duration-500 ease-out motion-reduce:transition-none"
+						style={{ width: `${progress * 100}%` }}
+					/>
+				</div>
 			</div>
 		</div>
 	);
@@ -473,7 +498,6 @@ function CardSpotlight({
 	cardRect,
 	selector,
 	side,
-	step,
 	title,
 	body,
 	onInsert,
@@ -481,7 +505,6 @@ function CardSpotlight({
 	cardRect: DOMRect | null;
 	selector: string;
 	side: "top" | "right";
-	step: number;
 	title: string;
 	body: string;
 	onInsert?: () => void;
@@ -514,6 +537,12 @@ function CardSpotlight({
 					height: rect.height,
 				}}
 			/>
+			<div
+				aria-hidden
+				data-testid="onboarding-target-glow"
+				className="pointer-events-none absolute rounded-[var(--radius-sm)] ring-2 ring-primary motion-safe:animate-pulse"
+				style={{ left, top, width: rect.width, height: rect.height }}
+			/>
 			<Popover open>
 				<PopoverAnchor asChild>
 					<div
@@ -532,8 +561,7 @@ function CardSpotlight({
 					onPointerDownOutside={(event) => event.preventDefault()}
 					onInteractOutside={(event) => event.preventDefault()}
 				>
-					<p className="tr-text-label-pill text-primary">Step {step} of 4</p>
-					<p className="mt-xs tr-title-card text-text-default">{title}</p>
+					<p className="tr-title-card text-text-default">{title}</p>
 					<p className="mt-xs text-text-muted tr-text-metadata leading-snug">{body}</p>
 					{onInsert ? (
 						<div className="mt-md flex justify-end">
@@ -554,6 +582,39 @@ function CardSpotlight({
 	);
 }
 
+function Intro({ onDone }: { onDone: () => void }) {
+	const [shown, setShown] = useState(0);
+	useEffect(() => {
+		const timers = [
+			setTimeout(() => setShown(1), 200),
+			setTimeout(() => setShown(2), 1100),
+			setTimeout(() => setShown(3), 2100),
+			setTimeout(onDone, 3400),
+		];
+		return () => timers.forEach(clearTimeout);
+	}, [onDone]);
+	const reveal = (index: number) =>
+		`transition-all duration-500 ease-out motion-reduce:transition-none ${
+			shown >= index ? "translate-y-0 opacity-100" : "translate-y-2 opacity-0"
+		}`;
+	return (
+		<div
+			data-testid="onboarding-intro"
+			className="absolute inset-0 z-30 flex flex-col items-center justify-center gap-md bg-container-workspace-bg p-xl text-center"
+		>
+			<h1 className={`tr-brand-hero text-primary ${reveal(1)}`}>Welcome to ThinkRail</h1>
+			<p className={`max-w-[520px] tr-text-ui text-text-default ${reveal(2)}`}>
+				ThinkRail is a worktree IDE built for working with AI agents in parallel.
+			</p>
+			<p
+				className={`max-w-[520px] whitespace-pre-line text-text-muted tr-text-metadata ${reveal(3)}`}
+			>
+				{"Let's set up a demo project first.\nIt takes about 2 minutes."}
+			</p>
+		</div>
+	);
+}
+
 function Completion({ onFinish }: { onFinish: () => void }) {
 	return (
 		<div className="absolute inset-0 z-40 flex items-center justify-center bg-container-workspace-overlay">
diff --git a/apps/web/src/onboarding/SPEC.md b/apps/web/src/onboarding/SPEC.md
index b0894d16a..da7a3642f 100644
--- a/apps/web/src/onboarding/SPEC.md
+++ b/apps/web/src/onboarding/SPEC.md
@@ -26,13 +26,27 @@ App" card); both flip one **view flag** (`store.demoOpen`, a top-level, non-pers
 - A centered modal (~`90vw × 90vh`) over a `bg-overlay` scrim; the card is an opaque `container-workspace-bg`
   sandbox rendering a simplified but faithful ThinkRail chrome (header / left `Projects` panel / center),
   built from the existing semantic tokens and `components/ui` — **not** wired to any store domain state.
+- **Animated intro** (`step: "intro"`, first): three lines reveal in sequence with restrained
+  fade/translate transitions (`motion-reduce:transition-none`) — "Welcome to ThinkRail" (`tr-brand-hero`),
+  the one-line product explanation (`tr-text-ui`), the ~2-minute setup note (`tr-text-metadata`) — then it
+  auto-advances into the first interactive action. No coach mark shows during the intro.
+- **Close demo** (`onboarding-close`, a quiet `Button variant="ghost"` in the card's top-right) is present
+  throughout — intro included — and is the only explicit pre-completion exit. It only clears the mocked
+  experience (`closeDemo`); it touches no real state. Coach marks themselves stay non-dismissible.
 - **Coach marks** reuse the tooltip + arrow treatment: a card-scoped **spotlight** dims everything inside
   the card except the current target with the `container-workspace-overlay` scrim (the workspace surface at
-  the `veil` 70% alpha step — a sanctioned color token, see `styles/colors.json`), drawn as four
-  `pointer-events-auto` rects computed relative to the measured card rect (so only the card interior dims,
-  the raised card stays legible). The Radix `components/ui/popover` (+ `PopoverArrow`) anchors to the
-  target; Escape / outside-interaction / auto-focus are all prevented. A coach mark is **non-dismissible**
-  (no close/Skip/Next/Escape/outside-click) and advances only when its scripted action completes.
+  the `veil` **50%** alpha step — a sanctioned color token, light enough to keep the interface legible;
+  see `styles/colors.json`), drawn as four `pointer-events-auto` rects computed relative to the measured
+  card rect (so only the card interior dims, the raised card stays legible). The Radix
+  `components/ui/popover` (+ `PopoverArrow`) anchors to the target; Escape / outside-interaction /
+  auto-focus are all prevented. The tooltip carries **only the title + instruction** — no step number,
+  progress, or pagination. A coach mark is **non-dismissible** and advances only when its scripted action
+  completes.
+- The current actionable target wears a **temporary pulsing emphasis** — a `ring-2 ring-primary` glow at
+  the target rect (`motion-safe:animate-pulse`; static under reduced motion), rendered by the spotlight
+  and moving with it. It is onboarding-only emphasis, never a permanent hover/focus/selected/active state.
+- A single **1px progress line** (`onboarding-progress`, `bg-primary`, smooth `transition-[width]`) sits on
+  the card's bottom edge and advances across the scripted `STEP_ORDER`. No labels/percentages/dots.
 - Only the current target is interactive; everything else is present but inert (covered by the dim).
 
 ## Scripted flow (local `step` state machine, numbered "of 4")
diff --git a/apps/web/src/styles/colors.json b/apps/web/src/styles/colors.json
index 1bcbee19c..09cd479a0 100644
--- a/apps/web/src/styles/colors.json
+++ b/apps/web/src/styles/colors.json
@@ -1,7 +1,7 @@
 {
 	"$schema": "./colors.schema.json",
 	"metadata": {
-		"version": "1.2.0",
+		"version": "1.3.0",
 		"note": "The semantic colour layer. Palettes live in themes/bundled/*.theme.json; this file says what each palette entry is FOR, and is the only place a derivation is written. A role's `from` names a theme manifest key; the CSS variable that key writes to is derived (kebab-case), not tabulated. See COLOR.md."
 	},
 
@@ -11,7 +11,7 @@
 		"soft": 20,
 		"muted": 40,
 		"strong": 60,
-		"veil": 70
+		"veil": 50
 	},
 
 	"roles": {
@@ -40,7 +40,7 @@
 			"from": "background",
 			"alpha": "veil",
 			"publish": true,
-			"note": "the onboarding spotlight scrim: the workspace surface at the `veil` (70%) alpha step, dimming the viewport while a coach mark spotlights one target"
+			"note": "the onboarding spotlight scrim: the workspace surface at the `veil` (50%) alpha step, dimming the demo card while a coach mark spotlights one target — light enough to keep the interface legible underneath"
 		},
 		"container-sidebar-bg": { "from": "sidebar", "publish": true },
 		"container-terminal-bg": { "from": "sidebar", "publish": true },
diff --git a/apps/web/src/styles/generated/colors.css b/apps/web/src/styles/generated/colors.css
index 37567d933..34394b88a 100644
--- a/apps/web/src/styles/generated/colors.css
+++ b/apps/web/src/styles/generated/colors.css
@@ -1,5 +1,5 @@
 /*
- * GENERATED — do not edit. Source: `src/styles/colors.json` (v1.2.0).
+ * GENERATED — do not edit. Source: `src/styles/colors.json` (v1.3.0).
  * Regenerate with `bun run colors:generate`; `colors:check` fails when this file is stale.
  *
  * The semantic roles, then the Tailwind utility map. The palette they read is written to the
@@ -14,7 +14,7 @@
 	--text-on-primary: var(--on-accent);
 	--text-link: var(--info); /* global.css `a {}` is the only consumer; no component styles a bare link */
 	--container-workspace-bg: var(--background); /* the app surface, and with it the opened-document canvas — a document reads as part of the workspace (Monaco's EDITOR_THEME, the markdown/spec preview, the chat column, the tab strip) */
-	--container-workspace-overlay: color-mix(in srgb, var(--background) 70%, transparent); /* the onboarding spotlight scrim: the workspace surface at the `veil` (70%) alpha step, dimming the viewport while a coach mark spotlights one target */
+	--container-workspace-overlay: color-mix(in srgb, var(--background) 50%, transparent); /* the onboarding spotlight scrim: the workspace surface at the `veil` (50%) alpha step, dimming the demo card while a coach mark spotlights one target — light enough to keep the interface legible underneath */
 	--container-sidebar-bg: var(--sidebar);
 	--container-terminal-bg: var(--sidebar);
 	--container-header-bg: var(--header);
diff --git a/e2e/onboarding-demo.spec.ts b/e2e/onboarding-demo.spec.ts
index fba725dee..bc0b69820 100644
--- a/e2e/onboarding-demo.spec.ts
+++ b/e2e/onboarding-demo.spec.ts
@@ -1,7 +1,7 @@
 import { expect, test } from "@playwright/test";
 import { openAppFresh } from "./fixtures/app";
 
-test("the launcher runs the fully mocked onboarding simulation, never touching real projects", async ({
+test("the mocked onboarding simulation runs intro → scripted flow, never touching real projects", async ({
 	page,
 }) => {
 	await openAppFresh(page);
@@ -9,28 +9,29 @@ test("the launcher runs the fully mocked onboarding simulation, never touching r
 
 	await page.getByTestId("onboarding-launch").click();
 	await expect(page.getByTestId("onboarding-sim")).toBeVisible();
-	const coach = page.getByTestId("onboarding-coach");
+	await expect(page.getByTestId("onboarding-intro")).toContainText("Welcome to ThinkRail");
+	await expect(page.getByTestId("onboarding-progress")).toBeAttached();
 
-	await expect(coach).toContainText("Step 1 of 4");
+	const coach = page.getByTestId("onboarding-coach");
 	await expect(coach).toContainText("Open a project");
+	await expect(coach).not.toContainText("Step");
 	await page.getByTestId("sim-open-project").click();
 
 	await expect(coach).toContainText("Choose your project folder");
 	await page.getByTestId("sim-folder").click();
 
-	await expect(coach).toContainText("Step 2 of 4");
+	await expect(coach).toContainText("Create a workspace");
 	await page.getByTestId("sim-add-workspace").click();
-	await expect(coach).toContainText("Step 2 of 4");
+	await expect(coach).toContainText("Create a second workspace");
 	await page.getByTestId("sim-add-workspace").click();
 
-	await expect(coach).toContainText("Step 3 of 4");
+	await expect(coach).toContainText("Start the first agent");
 	await page.getByTestId("onboarding-insert-prompt").click();
 	await expect(page.getByTestId("sim-composer")).toHaveValue(
 		"Add search functionality to the To Do app.",
 	);
 	await page.getByTestId("sim-send").click();
 
-	await expect(coach).toContainText("Step 4 of 4");
 	await expect(coach).toContainText("Switch to your second workspace");
 	await page.getByTestId("sim-ws-1").click();
 
@@ -39,18 +40,18 @@ test("the launcher runs the fully mocked onboarding simulation, never touching r
 	await expect(page.getByTestId("sim-composer")).toHaveValue("Add a filter for completed tasks.");
 	await page.getByTestId("sim-send").click();
 
-	await expect(page.getByTestId("onboarding-finish")).toBeVisible();
 	await page.getByTestId("onboarding-finish").click();
 	await expect(page.getByTestId("onboarding-sim")).toHaveCount(0);
-
 	await expect(page.getByTestId("project-item")).toHaveCount(0);
 });
 
-test("the empty-state Welcome card also opens the mocked simulation", async ({ page }) => {
+test("Close demo leaves the demo at any time without touching real state", async ({ page }) => {
 	await openAppFresh(page);
-	await page.getByTestId("welcome-demo").click();
+	await page.getByTestId("onboarding-launch").click();
 
-	await expect(page.getByTestId("onboarding-sim")).toBeVisible();
-	await expect(page.getByTestId("onboarding-coach")).toContainText("Step 1 of 4");
+	await expect(page.getByTestId("onboarding-intro")).toBeVisible();
+	await page.getByTestId("onboarding-close").click();
+
+	await expect(page.getByTestId("onboarding-sim")).toHaveCount(0);
 	await expect(page.getByTestId("project-item")).toHaveCount(0);
 });

From 9258dfd72c005a40a906b3f01690ccb8262d073c Mon Sep 17 00:00:00 2001
From: "Julia.Shilova" <Julia.Shilova@MacBook-Pro-5.local>
Date: Tue, 25 Aug 2026 11:22:32 +0300
Subject: [PATCH 15/23] feat(web): mocked Git-readiness moment in the
 onboarding intro
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a short environment-readiness beat between the product one-liner and
the 'set up a demo project' note, inside the existing demo container: a
'Before we start' message plus one compact, fully mocked Git row that
animates 'Checking Git…' (spinner) → 'Git is ready' (semantic success
role + check), then auto-continues into the interactive walkthrough. No
clicks needed; always ends ready.

Purely presentational: no Git detection/invocation, no terminal, no
server/contract calls, no domain state. Uses existing semantic typography
+ default/muted/success color roles; success uses the success role (not
primary). Not a numbered step. Scripted demo, Close demo, coach marks,
50% spotlight, target pulse, and 1px progress line unchanged. Spec + e2e
updated.
---
 .../src/onboarding/OnboardingSimulation.tsx   | 43 +++++++++++++++----
 apps/web/src/onboarding/SPEC.md               | 14 ++++--
 e2e/onboarding-demo.spec.ts                   |  2 +
 3 files changed, 47 insertions(+), 12 deletions(-)

diff --git a/apps/web/src/onboarding/OnboardingSimulation.tsx b/apps/web/src/onboarding/OnboardingSimulation.tsx
index 176d3b84e..35215662e 100644
--- a/apps/web/src/onboarding/OnboardingSimulation.tsx
+++ b/apps/web/src/onboarding/OnboardingSimulation.tsx
@@ -1,4 +1,4 @@
-import { Check, Folder, FolderOpen, GitBranch, House, Plus, Send, X } from "lucide-react";
+import { Check, Folder, FolderOpen, GitBranch, House, Loader2, Plus, Send, X } from "lucide-react";
 import { type ReactNode, useCallback, useEffect, useRef, useState } from "react";
 import { Button } from "../components/ui/button";
 import { Popover, PopoverAnchor, PopoverArrow, PopoverContent } from "../components/ui/popover";
@@ -583,19 +583,22 @@ function CardSpotlight({
 }
 
 function Intro({ onDone }: { onDone: () => void }) {
-	const [shown, setShown] = useState(0);
+	const [phase, setPhase] = useState(0);
+	const [gitReady, setGitReady] = useState(false);
 	useEffect(() => {
 		const timers = [
-			setTimeout(() => setShown(1), 200),
-			setTimeout(() => setShown(2), 1100),
-			setTimeout(() => setShown(3), 2100),
-			setTimeout(onDone, 3400),
+			setTimeout(() => setPhase(1), 200),
+			setTimeout(() => setPhase(2), 1000),
+			setTimeout(() => setPhase(3), 1900),
+			setTimeout(() => setGitReady(true), 3200),
+			setTimeout(() => setPhase(4), 3900),
+			setTimeout(onDone, 5200),
 		];
 		return () => timers.forEach(clearTimeout);
 	}, [onDone]);
 	const reveal = (index: number) =>
 		`transition-all duration-500 ease-out motion-reduce:transition-none ${
-			shown >= index ? "translate-y-0 opacity-100" : "translate-y-2 opacity-0"
+			phase >= index ? "translate-y-0 opacity-100" : "translate-y-2 opacity-0"
 		}`;
 	return (
 		<div
@@ -606,8 +609,32 @@ function Intro({ onDone }: { onDone: () => void }) {
 			<p className={`max-w-[520px] tr-text-ui text-text-default ${reveal(2)}`}>
 				ThinkRail is a worktree IDE built for working with AI agents in parallel.
 			</p>
+			<div className={`flex flex-col items-center gap-sm ${reveal(3)}`}>
+				<p className="tr-title-card text-text-default">Before we start</p>
+				<p className="max-w-[460px] text-text-muted tr-text-metadata">
+					ThinkRail works with Git projects. Let's make sure your computer is ready.
+				</p>
+				<div
+					data-testid="onboarding-git"
+					className="mt-xs inline-flex items-center gap-sm rounded-[var(--radius-sm)] border border-border-default bg-container-elevated-bg px-md py-sm"
+				>
+					<GitBranch className="size-4 shrink-0 text-text-muted" />
+					<span className="tr-text-ui text-text-default">Git</span>
+					{gitReady ? (
+						<span className="inline-flex items-center gap-xs tr-text-metadata text-feedback-success">
+							<Check className="size-3.5" />
+							Git is ready
+						</span>
+					) : (
+						<span className="inline-flex items-center gap-xs text-text-muted tr-text-metadata">
+							<Loader2 className="size-3.5 motion-safe:animate-spin" />
+							Checking Git…
+						</span>
+					)}
+				</div>
+			</div>
 			<p
-				className={`max-w-[520px] whitespace-pre-line text-text-muted tr-text-metadata ${reveal(3)}`}
+				className={`max-w-[520px] whitespace-pre-line text-text-muted tr-text-metadata ${reveal(4)}`}
 			>
 				{"Let's set up a demo project first.\nIt takes about 2 minutes."}
 			</p>
diff --git a/apps/web/src/onboarding/SPEC.md b/apps/web/src/onboarding/SPEC.md
index da7a3642f..0e4489b09 100644
--- a/apps/web/src/onboarding/SPEC.md
+++ b/apps/web/src/onboarding/SPEC.md
@@ -26,10 +26,16 @@ App" card); both flip one **view flag** (`store.demoOpen`, a top-level, non-pers
 - A centered modal (~`90vw × 90vh`) over a `bg-overlay` scrim; the card is an opaque `container-workspace-bg`
   sandbox rendering a simplified but faithful ThinkRail chrome (header / left `Projects` panel / center),
   built from the existing semantic tokens and `components/ui` — **not** wired to any store domain state.
-- **Animated intro** (`step: "intro"`, first): three lines reveal in sequence with restrained
-  fade/translate transitions (`motion-reduce:transition-none`) — "Welcome to ThinkRail" (`tr-brand-hero`),
-  the one-line product explanation (`tr-text-ui`), the ~2-minute setup note (`tr-text-metadata`) — then it
-  auto-advances into the first interactive action. No coach mark shows during the intro.
+- **Animated intro** (`step: "intro"`, first): lines reveal in sequence with restrained fade/translate
+  transitions (`motion-reduce:transition-none`) — "Welcome to ThinkRail" (`tr-brand-hero`), the one-line
+  product explanation (`tr-text-ui`), then a short **environment-readiness moment** ("Before we start" /
+  "ThinkRail works with Git projects…") with **one compact, fully mocked Git row** that animates
+  `Checking Git…` (spinner) → `Git is ready` (the semantic **success** role + check) — no clicks, always
+  ends ready, no terminal/install/Git-config detail; it exists to reveal the Git prerequisite before a
+  real project could error. Then the ~2-minute setup note (`tr-text-metadata`) and auto-advance into the
+  first interactive action. **Nothing here detects/invokes Git** or touches any real state; it is not a
+  numbered onboarding step, and no coach mark shows during the intro. (The missing-Git install flow is
+  deliberately out of scope — a future state once Git is bundled vs. externally installed is decided.)
 - **Close demo** (`onboarding-close`, a quiet `Button variant="ghost"` in the card's top-right) is present
   throughout — intro included — and is the only explicit pre-completion exit. It only clears the mocked
   experience (`closeDemo`); it touches no real state. Coach marks themselves stay non-dismissible.
diff --git a/e2e/onboarding-demo.spec.ts b/e2e/onboarding-demo.spec.ts
index bc0b69820..d21ced894 100644
--- a/e2e/onboarding-demo.spec.ts
+++ b/e2e/onboarding-demo.spec.ts
@@ -11,6 +11,8 @@ test("the mocked onboarding simulation runs intro → scripted flow, never touch
 	await expect(page.getByTestId("onboarding-sim")).toBeVisible();
 	await expect(page.getByTestId("onboarding-intro")).toContainText("Welcome to ThinkRail");
 	await expect(page.getByTestId("onboarding-progress")).toBeAttached();
+	await expect(page.getByTestId("onboarding-intro")).toContainText("Before we start");
+	await expect(page.getByTestId("onboarding-git")).toContainText("Git is ready");
 
 	const coach = page.getByTestId("onboarding-coach");
 	await expect(coach).toContainText("Open a project");

From ed094fb5a259275b8ee638d79a2d0be57d03ea21 Mon Sep 17 00:00:00 2001
From: "Julia.Shilova" <Julia.Shilova@MacBook-Pro-5.local>
Date: Tue, 25 Aug 2026 11:24:50 +0300
Subject: [PATCH 16/23] feat(web): soft primary brand glow behind the demo
 project card
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a blurred, diffused glow behind the mocked onboarding 'Open project'
card using the existing semantic primary alpha token (bg-primary-soft) on
a pointer-events-none layer inset slightly beyond the card — no hardcoded
color, no raw variable, no new token, not feedback-success. The card's
background, border, layout, dimensions, position, and other states are
unchanged; only the demo card is affected. Spec updated.
---
 apps/web/src/onboarding/OnboardingSimulation.tsx | 6 +++++-
 apps/web/src/onboarding/SPEC.md                  | 3 +++
 2 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/apps/web/src/onboarding/OnboardingSimulation.tsx b/apps/web/src/onboarding/OnboardingSimulation.tsx
index 35215662e..d1ab36185 100644
--- a/apps/web/src/onboarding/OnboardingSimulation.tsx
+++ b/apps/web/src/onboarding/OnboardingSimulation.tsx
@@ -367,7 +367,11 @@ function SimCenter({
 		return (
 			<Center>
 				<h1 className="tr-brand-hero text-primary">{PRODUCT_NAME}</h1>
-				<div className="mt-xl">
+				<div className="relative mt-xl">
+					<div
+						aria-hidden
+						className="pointer-events-none absolute -inset-3 rounded-[var(--radius-lg)] bg-primary-soft blur-xl"
+					/>
 					<button
 						type="button"
 						data-sim="open-project"
diff --git a/apps/web/src/onboarding/SPEC.md b/apps/web/src/onboarding/SPEC.md
index 0e4489b09..73c3256d4 100644
--- a/apps/web/src/onboarding/SPEC.md
+++ b/apps/web/src/onboarding/SPEC.md
@@ -59,6 +59,9 @@ App" card); both flip one **view flag** (`store.demoOpen`, a top-level, non-pers
 
 1. **Open a project** — empty-state Welcome with an "Open project" card (arrow points down to it); clicking
    opens a **fake** picker showing one `to-do-app` folder; selecting it opens the fake "To Do App" project.
+   The demo card carries a soft **brand glow** — a blurred `bg-primary-soft` layer behind it (not
+   `feedback-success`; onboarding emphasis, not a success state), extending slightly beyond the card
+   without altering its background, border, or layout.
 2. **Create separate workspaces** — coach sits right of the left panel, arrow pointing back at the rail
    `+`; two clicks create two fake workspaces (`Add search`, `Completed filter`), teaching the isolated
    worktree-per-task model. No real worktrees.

From 0d6db0ecb57c8b0aed12a256fb9abbc280335f18 Mon Sep 17 00:00:00 2001
From: "Julia.Shilova" <Julia.Shilova@MacBook-Pro-5.local>
Date: Tue, 25 Aug 2026 12:19:30 +0300
Subject: [PATCH 17/23] feat(web): onboarding uses the real composer + real
 Create-workspace dialog
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Prompt steps: the predetermined task is now prefilled in the composer when
the step becomes active (no Insert button); the coach highlights the real
Send button with the pulsing primary emphasis and the user just clicks
Send. Prompts: 'Add search functionality to the To Do app.' and 'Add a
filter for completed tasks.'

Workspace-creation step: opens the real panels/NewWorkspaceDialog instead
of a mocked control, teaching the exact production UI. To keep the demo
isolated, the shared dialog gains an inert, default-off 'preview' seam
(preview + onPreviewCreate) that skips all its wire reads and scripts
submit — no workspace/session/wire work. The shell injects the dialog into
OnboardingSimulation via a renderCreateDialog render-prop, so onboarding
never imports panels (no cycle); its coach uses a viewport-scoped spotlight
while the portaled dialog is visible.

Frontend-only; production dialog path unchanged (verified). Specs + e2e
updated.
---
 apps/web/SPEC.md                              |   2 +-
 .../src/onboarding/OnboardingSimulation.tsx   | 238 ++++++++++++------
 apps/web/src/onboarding/SPEC.md               |  35 ++-
 apps/web/src/panels/NewWorkspaceDialog.tsx    |  37 +--
 apps/web/src/panels/SPEC.md                   |   7 +
 apps/web/src/shell/Shell.tsx                  |  16 +-
 e2e/onboarding-demo.spec.ts                   |  10 +-
 7 files changed, 244 insertions(+), 101 deletions(-)

diff --git a/apps/web/SPEC.md b/apps/web/SPEC.md
index a932a9d9c..f31834664 100644
--- a/apps/web/SPEC.md
+++ b/apps/web/SPEC.md
@@ -59,7 +59,7 @@ screen, not a blank root).
 ### Dependency graph
 
 - `navigation` → `store`, `transport`, `contracts` (type-only); neither dependency imports it, and `main.tsx` initializes the integration
-- `shell` → child `shell/layout`, `panels`, `onboarding` (mounts `OnboardingSimulation` beside `Toaster`), `chat` (app-integration render/hydration only), `store`, `transport`, `contracts` (type-only), `components/ui`, `components` (`ErrorBoundary` around each mounted region), `constants`, `lib` (platform shortcut semantics), `themes` (the single owner of the atomic `applyTheme` DOM effect, driven by `store.theme`)
+- `shell` → child `shell/layout`, `panels`, `onboarding` (mounts `OnboardingSimulation` beside `Toaster`, injecting the real `panels/NewWorkspaceDialog` in `preview` mode via its `renderCreateDialog` prop so `onboarding` never imports `panels`), `chat` (app-integration render/hydration only), `store`, `transport`, `contracts` (type-only), `components/ui`, `components` (`ErrorBoundary` around each mounted region), `constants`, `lib` (platform shortcut semantics), `themes` (the single owner of the atomic `applyTheme` DOM effect, driven by `store.theme`)
 - `onboarding` → `store`, `components/ui`, `constants`, `lib`, `contracts`; mounted by `shell`; `panels` (`WelcomePanel` + `ProjectTree` footer) call `openDemo` (one-way panels→onboarding edge, no cycle). The active `OnboardingSimulation` is fully mocked (no `transport`); the retained-but-dormant real-domain coach still carries the `transport`/`demo` edges (see [[submodule-web-onboarding]])
 - `shell/layout` → `contracts` (types only), `lib` (attention/id primitives), and React / `react-resizable-panels` / `@dnd-kit/core`; the parent injects store state, commit callbacks, and feature renderers, so the child has no feature-module runtime edge
 - `panels` → `store`, `transport`, `components/ui`, `components` (`ErrorBoundary` for feature bodies), `lib`, `contracts`, `constants` (`WelcomePanel`'s wordmark), `chat` (`NewWorkspaceDialog` eagerly reuses `chat/ModelSelector`+`ThinkingSelector`+`useModelCatalog` — these are shiki-free, so the eager import stays split-safe; `TemplatesSettings` reuses `chat/TemplateEditorDialog` for its New/Edit flows — see `panels/SPEC.md`'s `TemplatesSettings` paragraph), `auth` (`ProvidersSettings` mounts `auth/LoginDialog`), `themes` (`AppearanceSettings` consumes the live catalog; code surfaces consume generic theme variables/syntax mapping)
diff --git a/apps/web/src/onboarding/OnboardingSimulation.tsx b/apps/web/src/onboarding/OnboardingSimulation.tsx
index d1ab36185..e0dafc974 100644
--- a/apps/web/src/onboarding/OnboardingSimulation.tsx
+++ b/apps/web/src/onboarding/OnboardingSimulation.tsx
@@ -39,62 +39,105 @@ const STEP_ORDER: Step[] = [
 type WsStatus = "idle" | "working" | "done";
 type Msg = { id: string; role: "user" | "assistant" | "working"; text?: string };
 
-const COACH: Record<
-	Exclude<Step, "intro" | "done">,
-	{ title: string; body: string; selector: string; side: "top" | "right"; task?: string }
-> = {
-	open: {
-		title: "Open a project",
-		body: "Choose a project folder from your computer.",
-		selector: '[data-sim="open-project"]',
-		side: "top",
-	},
-	picker: {
-		title: "Choose your project folder",
-		body: "Select the To Do App folder to open it in ThinkRail.",
-		selector: '[data-sim="folder"]',
-		side: "right",
-	},
-	"ws1-create": {
-		title: "Create a workspace",
-		body: "ThinkRail runs each task in its own isolated worktree and branch. Create one for the first task.",
-		selector: '[data-sim="rail-add"]',
-		side: "right",
-	},
-	"ws2-create": {
-		title: "Create a second workspace",
-		body: "Now create a second workspace so two tasks can run side by side, each on its own branch.",
-		selector: '[data-sim="rail-add"]',
-		side: "right",
-	},
-	agent1: {
-		title: "Start the first agent",
-		body: "Ask the agent to build the first feature, then send it.",
-		selector: '[data-sim="composer"]',
-		side: "top",
-		task: TASK_1,
-	},
-	"agent2-switch": {
-		title: "Switch to your second workspace",
-		body: "Your first agent keeps working independently — switch over to start the next one.",
-		selector: '[data-sim="ws-1"]',
-		side: "right",
-	},
-	agent2: {
-		title: "Run a second agent in parallel",
-		body: "Start the second task here. Both agents now run at the same time, each in its own workspace.",
-		selector: '[data-sim="composer"]',
-		side: "top",
-		task: TASK_2,
-	},
+type CoachInfo = {
+	selector: string;
+	side: "top" | "right";
+	scope: "card" | "viewport";
+	title: string;
+	body: string;
 };
 
+function activeCoach(step: Step, dialogOpen: boolean): CoachInfo | null {
+	switch (step) {
+		case "open":
+			return {
+				selector: '[data-sim="open-project"]',
+				side: "top",
+				scope: "card",
+				title: "Open a project",
+				body: "Choose a project folder from your computer.",
+			};
+		case "picker":
+			return {
+				selector: '[data-sim="folder"]',
+				side: "right",
+				scope: "card",
+				title: "Choose your project folder",
+				body: "Select the To Do App folder to open it in ThinkRail.",
+			};
+		case "ws1-create":
+			return dialogOpen
+				? {
+						selector: '[data-testid="create-workspace"]',
+						side: "top",
+						scope: "viewport",
+						title: "Create the workspace",
+						body: "This cuts an isolated worktree on its own branch. Click Create.",
+					}
+				: {
+						selector: '[data-sim="rail-add"]',
+						side: "right",
+						scope: "card",
+						title: "Create a workspace",
+						body: "ThinkRail runs each task in its own isolated worktree and branch. Open the New workspace dialog.",
+					};
+		case "ws2-create":
+			return dialogOpen
+				? {
+						selector: '[data-testid="create-workspace"]',
+						side: "top",
+						scope: "viewport",
+						title: "Create the second workspace",
+						body: "One more isolated workspace for the second task. Click Create.",
+					}
+				: {
+						selector: '[data-sim="rail-add"]',
+						side: "right",
+						scope: "card",
+						title: "Create a second workspace",
+						body: "Add a second workspace so two tasks run side by side, each on its own branch.",
+					};
+		case "agent1":
+			return {
+				selector: '[data-sim="send"]',
+				side: "top",
+				scope: "card",
+				title: "Start the first agent",
+				body: "The prompt is ready — send it to the agent.",
+			};
+		case "agent2-switch":
+			return {
+				selector: '[data-sim="ws-1"]',
+				side: "right",
+				scope: "card",
+				title: "Switch to your second workspace",
+				body: "Your first agent keeps working — switch over to start the next one.",
+			};
+		case "agent2":
+			return {
+				selector: '[data-sim="send"]',
+				side: "top",
+				scope: "card",
+				title: "Run a second agent in parallel",
+				body: "Both agents run at the same time, each in its own workspace. Send to start.",
+			};
+		default:
+			return null;
+	}
+}
+
 const WS_NAMES = ["Add search", "Completed filter"];
 
-export function OnboardingSimulation() {
+export type CreateDialogArgs = { onCreate: () => void; onClose: () => void };
+
+export function OnboardingSimulation({
+	renderCreateDialog,
+}: {
+	renderCreateDialog: (args: CreateDialogArgs) => ReactNode;
+}) {
 	const open = useAppStore((s) => s.demoOpen);
 	if (!open) return null;
-	return <Simulation />;
+	return <Simulation renderCreateDialog={renderCreateDialog} />;
 }
 
 function useElementRect(el: HTMLElement | null): DOMRect | null {
@@ -112,7 +155,11 @@ function useElementRect(el: HTMLElement | null): DOMRect | null {
 	return rect;
 }
 
-function Simulation() {
+function Simulation({
+	renderCreateDialog,
+}: {
+	renderCreateDialog: (args: CreateDialogArgs) => ReactNode;
+}) {
 	const closeDemo = useAppStore((s) => s.closeDemo);
 	const [cardEl, setCardEl] = useState<HTMLDivElement | null>(null);
 	const cardRect = useElementRect(cardEl);
@@ -123,20 +170,28 @@ function Simulation() {
 	const [drafts, setDrafts] = useState<Record<number, string>>({});
 	const [messages, setMessages] = useState<Record<number, Msg[]>>({});
 	const [status, setStatus] = useState<Record<number, WsStatus>>({});
+	const [dialogOpen, setDialogOpen] = useState(false);
 	const timers = useRef<ReturnType<typeof setTimeout>[]>([]);
 	useEffect(() => () => timers.current.forEach(clearTimeout), []);
 
 	const projectOpen = step !== "intro" && step !== "open" && step !== "picker";
-	const coach = step === "intro" || step === "done" ? null : COACH[step];
+	const coach = activeCoach(step, dialogOpen);
 	const progress = STEP_ORDER.indexOf(step) / (STEP_ORDER.length - 1);
 
 	const onRailAdd = () => {
+		if (step === "ws1-create" || step === "ws2-create") setDialogOpen(true);
+	};
+
+	const onPreviewCreate = () => {
 		if (step === "ws1-create") {
 			setWorkspaces([WS_NAMES[0] as string]);
+			setDialogOpen(false);
 			setStep("ws2-create");
 		} else if (step === "ws2-create") {
 			setWorkspaces([WS_NAMES[0] as string, WS_NAMES[1] as string]);
 			setActiveWs(0);
+			setDrafts((d) => ({ ...d, 0: TASK_1 }));
+			setDialogOpen(false);
 			setStep("agent1");
 		}
 	};
@@ -144,14 +199,11 @@ function Simulation() {
 	const onWsClick = (index: number) => {
 		if (step === "agent2-switch" && index === 1) {
 			setActiveWs(1);
+			setDrafts((d) => ({ ...d, 1: TASK_2 }));
 			setStep("agent2");
 		}
 	};
 
-	const insertTask = () => {
-		if (coach?.task) setDrafts((d) => ({ ...d, [activeWs]: coach.task as string }));
-	};
-
 	const send = () => {
 		const ws = activeWs;
 		const text = (drafts[ws] ?? "").trim();
@@ -235,16 +287,26 @@ function Simulation() {
 				</div>
 
 				{step === "intro" ? <Intro onDone={startTour} /> : null}
-				{coach ? (
+				{coach?.scope === "card" ? (
 					<CardSpotlight
 						cardRect={cardRect}
 						selector={coach.selector}
 						side={coach.side}
 						title={coach.title}
 						body={coach.body}
-						{...(coach.task ? { onInsert: insertTask } : {})}
 					/>
 				) : null}
+				{coach?.scope === "viewport" ? (
+					<ViewportCoach
+						selector={coach.selector}
+						side={coach.side}
+						title={coach.title}
+						body={coach.body}
+					/>
+				) : null}
+				{dialogOpen
+					? renderCreateDialog({ onCreate: onPreviewCreate, onClose: () => setDialogOpen(false) })
+					: null}
 				{step === "done" ? <Completion onFinish={() => closeDemo()} /> : null}
 
 				<div className="pointer-events-none absolute inset-x-0 bottom-0 z-50 h-px">
@@ -477,6 +539,7 @@ function SimCenter({
 					/>
 					<Button
 						size="sm"
+						data-sim="send"
 						data-testid="sim-send"
 						disabled={!draft.trim() || status[activeWs] === "working"}
 						onClick={onSend}
@@ -504,14 +567,12 @@ function CardSpotlight({
 	side,
 	title,
 	body,
-	onInsert,
 }: {
 	cardRect: DOMRect | null;
 	selector: string;
 	side: "top" | "right";
 	title: string;
 	body: string;
-	onInsert?: () => void;
 }) {
 	const rect = useTargetRect(selector);
 	if (!rect || !cardRect) return null;
@@ -567,18 +628,6 @@ function CardSpotlight({
 				>
 					<p className="tr-title-card text-text-default">{title}</p>
 					<p className="mt-xs text-text-muted tr-text-metadata leading-snug">{body}</p>
-					{onInsert ? (
-						<div className="mt-md flex justify-end">
-							<Button
-								variant="outline"
-								size="sm"
-								data-testid="onboarding-insert-prompt"
-								onClick={onInsert}
-							>
-								Insert prompt
-							</Button>
-						</div>
-					) : null}
 					<PopoverArrow />
 				</PopoverContent>
 			</Popover>
@@ -586,6 +635,51 @@ function CardSpotlight({
 	);
 }
 
+function ViewportCoach({
+	selector,
+	side,
+	title,
+	body,
+}: {
+	selector: string;
+	side: "top" | "right";
+	title: string;
+	body: string;
+}) {
+	const rect = useTargetRect(selector);
+	if (!rect) return null;
+	const box = { left: rect.left, top: rect.top, width: rect.width, height: rect.height };
+	return (
+		<>
+			<div
+				aria-hidden
+				data-testid="onboarding-target-glow"
+				className="pointer-events-none fixed z-[60] rounded-[var(--radius-sm)] ring-2 ring-primary motion-safe:animate-pulse"
+				style={box}
+			/>
+			<Popover open>
+				<PopoverAnchor asChild>
+					<div aria-hidden className="pointer-events-none fixed" style={box} />
+				</PopoverAnchor>
+				<PopoverContent
+					data-testid="onboarding-coach"
+					side={side}
+					align="center"
+					className="z-[60] w-[260px] p-md"
+					onOpenAutoFocus={(event) => event.preventDefault()}
+					onEscapeKeyDown={(event) => event.preventDefault()}
+					onPointerDownOutside={(event) => event.preventDefault()}
+					onInteractOutside={(event) => event.preventDefault()}
+				>
+					<p className="tr-title-card text-text-default">{title}</p>
+					<p className="mt-xs text-text-muted tr-text-metadata leading-snug">{body}</p>
+					<PopoverArrow />
+				</PopoverContent>
+			</Popover>
+		</>
+	);
+}
+
 function Intro({ onDone }: { onDone: () => void }) {
 	const [phase, setPhase] = useState(0);
 	const [gitReady, setGitReady] = useState(false);
diff --git a/apps/web/src/onboarding/SPEC.md b/apps/web/src/onboarding/SPEC.md
index 73c3256d4..8e6d1fb82 100644
--- a/apps/web/src/onboarding/SPEC.md
+++ b/apps/web/src/onboarding/SPEC.md
@@ -39,6 +39,14 @@ App" card); both flip one **view flag** (`store.demoOpen`, a top-level, non-pers
 - **Close demo** (`onboarding-close`, a quiet `Button variant="ghost"` in the card's top-right) is present
   throughout — intro included — and is the only explicit pre-completion exit. It only clears the mocked
   experience (`closeDemo`); it touches no real state. Coach marks themselves stay non-dismissible.
+- **Reusing the real Create-workspace dialog.** Step 2 renders the production `panels/NewWorkspaceDialog`
+  verbatim via a small **injected** `renderCreateDialog` render-prop (the shell composition root supplies
+  it — same inversion it uses for `SettingsDialog`'s Layout section — so `onboarding` never imports
+  `panels`, no cycle). The dialog runs in an **inert `preview` mode** (a new optional prop on the shared
+  component, default off): all its wire reads are skipped and submit is short-circuited to a
+  `onPreviewCreate` callback, so the exact real dialog UI is taught while **no** workspace/session/wire
+  work happens. Its coach uses a **viewport-scoped** spotlight (the dialog is a portaled modal), a pulse
+  ring on its Create button + a tooltip; every other step uses the card-scoped spotlight.
 - **Coach marks** reuse the tooltip + arrow treatment: a card-scoped **spotlight** dims everything inside
   the card except the current target with the `container-workspace-overlay` scrim (the workspace surface at
   the `veil` **50%** alpha step — a sanctioned color token, light enough to keep the interface legible;
@@ -62,14 +70,18 @@ App" card); both flip one **view flag** (`store.demoOpen`, a top-level, non-pers
    The demo card carries a soft **brand glow** — a blurred `bg-primary-soft` layer behind it (not
    `feedback-success`; onboarding emphasis, not a success state), extending slightly beyond the card
    without altering its background, border, or layout.
-2. **Create separate workspaces** — coach sits right of the left panel, arrow pointing back at the rail
-   `+`; two clicks create two fake workspaces (`Add search`, `Completed filter`), teaching the isolated
-   worktree-per-task model. No real worktrees.
-3. **Start the first agent** — switches into the first workspace's fake composer; **Insert** fills the
-   predetermined *"Add search functionality to the To Do app."*, **Send** shows a brief "Working…" then a
+2. **Create separate workspaces** — coach sits right of the left panel (arrow at the rail `+`); clicking
+   it opens the **real** `NewWorkspaceDialog` (see the preview seam below) and the coach re-points at that
+   dialog's **Create** button. Doing this twice yields two fake workspaces (`Add search`,
+   `Completed filter`), teaching the isolated worktree-per-task model on the real dialog UI. No real
+   worktrees are created.
+3. **Start the first agent** — switches into the first workspace's composer with the predetermined
+   *"Add search functionality to the To Do app."* **already prefilled** (no Insert button); the coach
+   highlights the existing **Send** button (pulsing primary ring). Send shows a brief "Working…" then a
    predetermined successful result (a `setTimeout`, no model call), using the existing chat treatment.
-4. **Run agents in parallel** — coach guides switching to the second workspace and sending *"Add a filter
-   for completed tasks."*; the first workspace's row shows it already **done** while the second works —
+4. **Run agents in parallel** — coach guides switching to the second workspace, whose composer is
+   **prefilled** with *"Add a filter for completed tasks."* (Send highlighted); the first workspace's row
+   shows it already **done** while the second works —
    the payoff that separate workspaces hold independent, concurrent sessions. A left-panel note reinforces
    that switching tabs never stops a session.
 
@@ -78,13 +90,14 @@ whole thing is local state, replaying (reopen) starts fresh at step 1.
 
 ## Boundary
 
-- **Public surface (barrel):** `OnboardingSimulation`, `OnboardingLauncher`, `useTargetRect` (anchor hook).
-  The store exposes `demoOpen` + `openDemo`/`closeDemo`.
+- **Public surface (barrel):** `OnboardingSimulation` (takes a `renderCreateDialog` render-prop),
+  `OnboardingLauncher`, `useTargetRect` (anchor hook). The store exposes `demoOpen` + `openDemo`/`closeDemo`.
 - **Allowed deps:** `store` (`demoOpen`/open/close), `components/ui` (`popover`, `button`), `constants`
   (`PRODUCT_NAME`), `lib`, `lucide-react`, React.
 - **Forbidden:** `panels`, `shell` internals, `server`/`shared`/`pi`, `transport` (the simulation makes no
-  network/wire calls). `panels` (`WelcomePanel` card, `ProjectTree` footer launcher) call `openDemo` — a
-  one-way panels→onboarding edge, no cycle.
+  network/wire calls). It reuses the real `NewWorkspaceDialog` **without importing `panels`** — the shell
+  injects it through `renderCreateDialog`. `panels` (`WelcomePanel` card, `ProjectTree` footer launcher)
+  call `openDemo` — a one-way panels→onboarding edge, no cycle.
 
 ## Dormant (retained, not wired)
 
diff --git a/apps/web/src/panels/NewWorkspaceDialog.tsx b/apps/web/src/panels/NewWorkspaceDialog.tsx
index 0039dc552..13c656af1 100644
--- a/apps/web/src/panels/NewWorkspaceDialog.tsx
+++ b/apps/web/src/panels/NewWorkspaceDialog.tsx
@@ -67,6 +67,8 @@ export function NewWorkspaceDialog({
 	promptNote,
 	onOpenChange,
 	onCreated,
+	preview = false,
+	onPreviewCreate,
 }: {
 	open: boolean;
 	projectId: string;
@@ -74,6 +76,8 @@ export function NewWorkspaceDialog({
 	promptNote?: string;
 	onOpenChange: (open: boolean) => void;
 	onCreated: (workspace: Workspace) => void;
+	preview?: boolean;
+	onPreviewCreate?: () => void;
 }) {
 	const projects = useAppStore((s) => s.projects);
 
@@ -122,14 +126,14 @@ export function NewWorkspaceDialog({
 	}, [open, projectId, initialPrompt]);
 
 	useEffect(() => {
-		if (!open) return;
+		if (!open || preview) return;
 		if (projects.some((p) => p.id === selectedProjectId)) return;
 		onOpenChange(false);
 		toast.info("That project was closed");
-	}, [open, projects, selectedProjectId, onOpenChange]);
+	}, [open, projects, selectedProjectId, onOpenChange, preview]);
 
 	useEffect(() => {
-		if (!open) return;
+		if (!open || preview) return;
 		let cancelled = false;
 		setSkillCommands([]);
 		void slashCommandCatalogOrEmpty(() =>
@@ -140,10 +144,10 @@ export function NewWorkspaceDialog({
 		return () => {
 			cancelled = true;
 		};
-	}, [open, selectedProjectId]);
+	}, [open, selectedProjectId, preview]);
 
 	useEffect(() => {
-		if (!open) return;
+		if (!open || preview) return;
 		let cancelled = false;
 		setAliasSkills([]);
 		getTransport()
@@ -155,14 +159,14 @@ export function NewWorkspaceDialog({
 		return () => {
 			cancelled = true;
 		};
-	}, [open, selectedProjectId]);
+	}, [open, selectedProjectId, preview]);
 
 	const {
 		models,
 		refreshing: modelsRefreshing,
 		refresh: onRefreshModels,
 		fresh: catalogFresh,
-	} = useModelCatalog(open);
+	} = useModelCatalog(open && !preview);
 
 	const applyHostDefault = useCallback(() => {
 		let cancelled = false;
@@ -180,12 +184,12 @@ export function NewWorkspaceDialog({
 	}, []);
 
 	useEffect(() => {
-		if (!open) return;
+		if (!open || preview) return;
 		return applyHostDefault();
-	}, [open, applyHostDefault]);
+	}, [open, preview, applyHostDefault]);
 
 	useEffect(() => {
-		if (!open || !model) return;
+		if (!open || preview || !model) return;
 		const next = reconcileModel(models, model, catalogFresh);
 		if (next === null) return;
 		if (next !== "unavailable") {
@@ -195,10 +199,10 @@ export function NewWorkspaceDialog({
 		if (hostDefaultAsked.current) return;
 		hostDefaultAsked.current = true;
 		return applyHostDefault();
-	}, [open, models, model, catalogFresh, applyHostDefault]);
+	}, [open, models, model, catalogFresh, applyHostDefault, preview]);
 
 	useEffect(() => {
-		if (!open || !model) return;
+		if (!open || preview || !model) return;
 		if (model.thinkingLevels.includes(thinkingLevel)) return;
 		let cancelled = false;
 		getTransport()
@@ -214,7 +218,7 @@ export function NewWorkspaceDialog({
 		return () => {
 			cancelled = true;
 		};
-	}, [open, model, thinkingLevel]);
+	}, [open, model, thinkingLevel, preview]);
 
 	const prefetchBase = (ref: string) => {
 		if (!ref.startsWith("origin/")) return;
@@ -232,13 +236,18 @@ export function NewWorkspaceDialog({
 		branches,
 		refreshing,
 		refresh: refreshBranches,
-	} = useBranchList(open ? selectedProjectId : null, (list) => {
+	} = useBranchList(open && !preview ? selectedProjectId : null, (list) => {
 		setBaseRef(list.defaultBranch);
 		prefetchBase(list.defaultBranch);
 	});
 
 	const create = async () => {
 		if (creating) return;
+		if (preview) {
+			onPreviewCreate?.();
+			onOpenChange(false);
+			return;
+		}
 		setCreating(true);
 		let workspace: Workspace;
 		if (target === "default") {
diff --git a/apps/web/src/panels/SPEC.md b/apps/web/src/panels/SPEC.md
index f6cf46695..aa457082b 100644
--- a/apps/web/src/panels/SPEC.md
+++ b/apps/web/src/panels/SPEC.md
@@ -227,6 +227,13 @@ skills' (attacker-controlled) names before trust. The full manager (`chat/Skills
 pre-session half of the user's skill settings; the chat header opens the same dialog in workspace mode
 (with Reload).
 
+**`NewWorkspaceDialog`** carries an optional, default-off **`preview` seam** (`preview` + `onPreviewCreate`)
+for the onboarding simulation to teach this exact dialog UI: when `preview` is set, every wire read (skills,
+aliases, model default/clamp, branch list, prefetch, model catalog) and the project-closed guard are
+skipped and submit is short-circuited to `onPreviewCreate` instead of `workspace.create`/`session.create`
+— so the real component renders with no network calls and creates no domain object. Production callers pass
+neither prop and are unaffected; the demo injects it via the shell (see [[submodule-web-onboarding]]).
+
 **`NewWorkspaceDialog`** is the start-working surface: **a target control** (a two-option segment — a
 native radio group, `fieldset` + sr-only `legend` over visually-hidden radio inputs, so assistive tech
 hears one mutually-exclusive choice — both always visible: the two-mode model in one glance) chooses **where** the work runs, and the header is
diff --git a/apps/web/src/shell/Shell.tsx b/apps/web/src/shell/Shell.tsx
index baacc98bf..3a2a94118 100644
--- a/apps/web/src/shell/Shell.tsx
+++ b/apps/web/src/shell/Shell.tsx
@@ -2,6 +2,7 @@ import { ChevronRight, GitBranch, Settings } from "lucide-react";
 import { useEffect, useRef } from "react";
 import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from "../components/ui/resizable";
 import { OnboardingSimulation } from "../onboarding";
+import { NewWorkspaceDialog } from "../panels/NewWorkspaceDialog";
 import { ProjectTree } from "../panels/ProjectTree";
 import { SettingsDialog } from "../panels/SettingsDialog";
 import { Toaster } from "../panels/Toaster";
@@ -218,7 +219,20 @@ export function Shell() {
 				</div>
 			)}
 			<Toaster />
-			<OnboardingSimulation />
+			<OnboardingSimulation
+				renderCreateDialog={({ onCreate, onClose }) => (
+					<NewWorkspaceDialog
+						open
+						preview
+						projectId="onboarding-demo"
+						onOpenChange={(next) => {
+							if (!next) onClose();
+						}}
+						onCreated={() => {}}
+						onPreviewCreate={onCreate}
+					/>
+				)}
+			/>
 		</div>
 	);
 }
diff --git a/e2e/onboarding-demo.spec.ts b/e2e/onboarding-demo.spec.ts
index d21ced894..02b4e034c 100644
--- a/e2e/onboarding-demo.spec.ts
+++ b/e2e/onboarding-demo.spec.ts
@@ -24,11 +24,18 @@ test("the mocked onboarding simulation runs intro → scripted flow, never touch
 
 	await expect(coach).toContainText("Create a workspace");
 	await page.getByTestId("sim-add-workspace").click();
+	await expect(page.getByTestId("new-workspace-dialog")).toBeVisible();
+	await expect(coach).toContainText("Create the workspace");
+	await page.getByTestId("create-workspace").click();
+
 	await expect(coach).toContainText("Create a second workspace");
 	await page.getByTestId("sim-add-workspace").click();
+	await expect(page.getByTestId("new-workspace-dialog")).toBeVisible();
+	await expect(coach).toContainText("Create the second workspace");
+	await page.getByTestId("create-workspace").click();
 
 	await expect(coach).toContainText("Start the first agent");
-	await page.getByTestId("onboarding-insert-prompt").click();
+	await expect(page.getByTestId("onboarding-insert-prompt")).toHaveCount(0);
 	await expect(page.getByTestId("sim-composer")).toHaveValue(
 		"Add search functionality to the To Do app.",
 	);
@@ -38,7 +45,6 @@ test("the mocked onboarding simulation runs intro → scripted flow, never touch
 	await page.getByTestId("sim-ws-1").click();
 
 	await expect(coach).toContainText("Run a second agent in parallel");
-	await page.getByTestId("onboarding-insert-prompt").click();
 	await expect(page.getByTestId("sim-composer")).toHaveValue("Add a filter for completed tasks.");
 	await page.getByTestId("sim-send").click();
 

From 4e589d09948087b6c8b52037534cbce093bf3118 Mon Sep 17 00:00:00 2001
From: "Julia.Shilova" <Julia.Shilova@MacBook-Pro-5.local>
Date: Tue, 25 Aug 2026 12:23:07 +0300
Subject: [PATCH 18/23] feat(web): Finder-style three-column folder picker in
 the demo
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replaces the small single-folder picker card with a simplified macOS
Finder-style folder window that fills the content area below the coach
mark: Locations (Home selected) → Home contents (Projects selected) →
Projects (my-app / notes / to-do-app), plus a minimal toolbar. Only
to-do-app is interactive (pulsing primary emphasis; coach moved above it
with a downward arrow); the rest stays under the 50% spotlight and does
nothing. Selecting to-do-app continues the existing mocked flow.

Fully mocked — no OS picker, filesystem, paths, or backend. Built from
existing ThinkRail semantic typography/color tokens (no macOS assets or
hardcoded colors); container size and the rest of the flow unchanged.
Spec + e2e coverage updated.
---
 .../src/onboarding/OnboardingSimulation.tsx   | 128 ++++++++++++++----
 apps/web/src/onboarding/SPEC.md               |   7 +-
 2 files changed, 110 insertions(+), 25 deletions(-)

diff --git a/apps/web/src/onboarding/OnboardingSimulation.tsx b/apps/web/src/onboarding/OnboardingSimulation.tsx
index e0dafc974..1d2043b89 100644
--- a/apps/web/src/onboarding/OnboardingSimulation.tsx
+++ b/apps/web/src/onboarding/OnboardingSimulation.tsx
@@ -1,8 +1,22 @@
-import { Check, Folder, FolderOpen, GitBranch, House, Loader2, Plus, Send, X } from "lucide-react";
+import {
+	Check,
+	ChevronLeft,
+	ChevronRight,
+	Folder,
+	FolderOpen,
+	GitBranch,
+	House,
+	Loader2,
+	type LucideIcon,
+	Plus,
+	Send,
+	X,
+} from "lucide-react";
 import { type ReactNode, useCallback, useEffect, useRef, useState } from "react";
 import { Button } from "../components/ui/button";
 import { Popover, PopoverAnchor, PopoverArrow, PopoverContent } from "../components/ui/popover";
 import { PRODUCT_NAME } from "../constants/branding";
+import { cn } from "../lib";
 import { useAppStore } from "../store";
 import { useTargetRect } from "./anchor";
 
@@ -60,7 +74,7 @@ function activeCoach(step: Step, dialogOpen: boolean): CoachInfo | null {
 		case "picker":
 			return {
 				selector: '[data-sim="folder"]',
-				side: "right",
+				side: "top",
 				scope: "card",
 				title: "Choose your project folder",
 				body: "Select the To Do App folder to open it in ThinkRail.",
@@ -457,30 +471,35 @@ function SimCenter({
 	}
 	if (step === "picker") {
 		return (
-			<Center>
-				<div className="w-[440px] overflow-hidden rounded-[var(--radius-lg)] border border-border-default bg-container-elevated-bg shadow-[var(--shadow-md)]">
-					<div className="flex items-center gap-xs border-border-default border-b px-lg py-md tr-text-metadata text-text-muted">
-						<Folder className="size-3.5" />
-						<span>Home</span>
-						<span>/</span>
-						<span>Projects</span>
+			<div className="flex min-h-0 flex-1 bg-container-content-bg p-lg">
+				<div className="flex min-h-0 flex-1 flex-col overflow-hidden rounded-[var(--radius-md)] border border-border-default bg-container-elevated-bg shadow-[var(--shadow-md)]">
+					<div className="flex h-9 shrink-0 items-center gap-sm border-border-default border-b px-md text-text-muted">
+						<ChevronLeft className="size-4" />
+						<ChevronRight className="size-4" />
+						<span className="ml-sm tr-text-ui text-text-default">Projects</span>
+					</div>
+					<div className="flex min-h-0 flex-1">
+						<PickerColumn className="w-[180px] bg-container-sidebar-bg" label="Locations">
+							<PickerRow icon={Folder} name="Desktop" />
+							<PickerRow icon={Folder} name="Documents" />
+							<PickerRow icon={Folder} name="Downloads" />
+							<PickerRow icon={House} name="Home" selected />
+						</PickerColumn>
+						<PickerColumn className="w-[220px]">
+							<PickerRow icon={Folder} name="Applications" />
+							<PickerRow icon={Folder} name="Desktop" />
+							<PickerRow icon={Folder} name="Documents" />
+							<PickerRow icon={Folder} name="Downloads" />
+							<PickerRow icon={Folder} name="Projects" selected chevron />
+						</PickerColumn>
+						<PickerColumn className="min-w-0 flex-1" last>
+							<PickerRow icon={Folder} name="my-app" />
+							<PickerRow icon={Folder} name="notes" />
+							<PickerRow icon={Folder} name="to-do-app" target onSelect={onPickFolder} />
+						</PickerColumn>
 					</div>
-					<ul className="p-sm">
-						<li>
-							<button
-								type="button"
-								data-sim="folder"
-								data-testid="sim-folder"
-								onClick={onPickFolder}
-								className="flex w-full items-center gap-sm rounded-[var(--radius-sm)] px-md py-sm text-left tr-text-ui text-text-default transition-colors hover:bg-control-bg-hovered"
-							>
-								<Folder className="size-4 text-primary" />
-								<span>to-do-app</span>
-							</button>
-						</li>
-					</ul>
 				</div>
-			</Center>
+			</div>
 		);
 	}
 	if (step === "ws1-create" || step === "ws2-create") {
@@ -553,6 +572,67 @@ function SimCenter({
 	);
 }
 
+function PickerColumn({
+	className,
+	label,
+	last,
+	children,
+}: {
+	className?: string;
+	label?: string;
+	last?: boolean;
+	children: ReactNode;
+}) {
+	return (
+		<div
+			className={cn(
+				"flex min-h-0 flex-col gap-0.5 overflow-auto p-xs",
+				!last && "border-border-default border-r",
+				className,
+			)}
+		>
+			{label ? (
+				<span className="px-sm pt-xs pb-1 tr-text-eyebrow text-text-muted">{label}</span>
+			) : null}
+			{children}
+		</div>
+	);
+}
+
+function PickerRow({
+	icon: Icon,
+	name,
+	selected,
+	chevron,
+	target,
+	onSelect,
+}: {
+	icon: LucideIcon;
+	name: string;
+	selected?: boolean;
+	chevron?: boolean;
+	target?: boolean;
+	onSelect?: () => void;
+}) {
+	return (
+		<button
+			type="button"
+			{...(target ? { "data-sim": "folder", "data-testid": "sim-folder" } : {})}
+			{...(onSelect ? { onClick: onSelect } : {})}
+			className={cn(
+				"flex h-7 shrink-0 items-center gap-sm rounded-[var(--radius-sm)] px-sm text-left tr-text-ui transition-colors",
+				selected
+					? "bg-control-bg-selected text-primary"
+					: "text-text-default hover:bg-control-bg-hovered",
+			)}
+		>
+			<Icon className={cn("size-4 shrink-0", selected ? "text-primary" : "text-text-muted")} />
+			<span className="min-w-0 flex-1 truncate">{name}</span>
+			{chevron ? <ChevronRight className="size-3.5 shrink-0 text-text-muted" /> : null}
+		</button>
+	);
+}
+
 function Center({ children }: { children: ReactNode }) {
 	return (
 		<div className="flex min-h-0 flex-1 flex-col items-center justify-center bg-container-content-bg p-xl text-center">
diff --git a/apps/web/src/onboarding/SPEC.md b/apps/web/src/onboarding/SPEC.md
index 8e6d1fb82..0afb84750 100644
--- a/apps/web/src/onboarding/SPEC.md
+++ b/apps/web/src/onboarding/SPEC.md
@@ -66,7 +66,12 @@ App" card); both flip one **view flag** (`store.demoOpen`, a top-level, non-pers
 ## Scripted flow (local `step` state machine, numbered "of 4")
 
 1. **Open a project** — empty-state Welcome with an "Open project" card (arrow points down to it); clicking
-   opens a **fake** picker showing one `to-do-app` folder; selecting it opens the fake "To Do App" project.
+   opens a **fake, simplified macOS-Finder-style folder picker** — a large three-column browser filling
+   the content area (Locations with **Home** selected → Home contents with **Projects** selected →
+   `my-app` / `notes` / `to-do-app`) plus a minimal toolbar, so it reads as a system folder window without
+   recreating Finder. Only `to-do-app` is interactive (spotlit with the pulsing primary emphasis, coach
+   above it, arrow down); everything else stays under the dim and does nothing. Selecting `to-do-app`
+   opens the fake "To Do App" project. Built from ThinkRail semantic tokens — no macOS assets/colors.
    The demo card carries a soft **brand glow** — a blurred `bg-primary-soft` layer behind it (not
    `feedback-success`; onboarding emphasis, not a success state), extending slightly beyond the card
    without altering its background, border, or layout.

From 3c2852364528063d9e7278eae1d9bf8d03556f7b Mon Sep 17 00:00:00 2001
From: "Julia.Shilova" <Julia.Shilova@MacBook-Pro-5.local>
Date: Tue, 25 Aug 2026 12:42:11 +0300
Subject: [PATCH 19/23] feat(web): onboarding prefills create-dialog tasks,
 inverts coach marks
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- The two predetermined tasks are now 'Implement a search feature in my To
  Do app.' and 'Add filtering by tags so I can quickly show tasks with a
  specific tag.', used in both the create dialog and the composer/chat.
- Each Create-workspace step opens the real NewWorkspaceDialog (preview
  seam) with its prompt prefilled + focused (blinking caret, no typing
  animation); the Create button is emphasized and the coach sits to the
  dialog's right with its arrow on Create.
- Composer prompts are prefilled; the coach highlights the real Send button
  (no Insert button).
- All coach marks now use an inverted/high-contrast surface (bg-primary +
  text-on-primary + fill-primary arrow) so they stand out from the dark UI;
  every coach keeps a directional Popover arrow that reorients with side.
- Preview-only: the Create button's ↵ key-badge is hidden (text-only
  'Create') via the existing preview seam — production button unchanged.

Fully mocked/isolated; reduced-motion keeps a static ring. Specs + e2e
updated.

Design-system flag: the semantic layer has no neutral light/inverse surface
role, so coaches reuse the closest existing high-contrast combo (primary/
on-primary) rather than a new token — a true near-white inverse would need
a sanctioned role.
---
 .../src/onboarding/OnboardingSimulation.tsx   | 36 ++++++++--------
 apps/web/src/onboarding/SPEC.md               | 41 ++++++++++++-------
 apps/web/src/panels/NewWorkspaceDialog.tsx    |  8 ++--
 apps/web/src/panels/SPEC.md                   |  8 ++--
 apps/web/src/shell/Shell.tsx                  |  3 +-
 e2e/onboarding-demo.spec.ts                   | 16 +++++---
 6 files changed, 68 insertions(+), 44 deletions(-)

diff --git a/apps/web/src/onboarding/OnboardingSimulation.tsx b/apps/web/src/onboarding/OnboardingSimulation.tsx
index 1d2043b89..b1f45dd9e 100644
--- a/apps/web/src/onboarding/OnboardingSimulation.tsx
+++ b/apps/web/src/onboarding/OnboardingSimulation.tsx
@@ -20,8 +20,8 @@ import { cn } from "../lib";
 import { useAppStore } from "../store";
 import { useTargetRect } from "./anchor";
 
-const TASK_1 = "Add search functionality to the To Do app.";
-const TASK_2 = "Add a filter for completed tasks.";
+const TASK_1 = "Implement a search feature in my To Do app.";
+const TASK_2 = "Add filtering by tags so I can quickly show tasks with a specific tag.";
 const RESULT_1 =
 	"Added a live search box that filters tasks as you type — a new searchTasks() in src/app.js wired to an input in index.html.";
 const RESULT_2 =
@@ -83,10 +83,10 @@ function activeCoach(step: Step, dialogOpen: boolean): CoachInfo | null {
 			return dialogOpen
 				? {
 						selector: '[data-testid="create-workspace"]',
-						side: "top",
+						side: "right",
 						scope: "viewport",
 						title: "Create the workspace",
-						body: "This cuts an isolated worktree on its own branch. Click Create.",
+						body: "A workspace isolates this task on its own branch. The prepared task will start here — click Create.",
 					}
 				: {
 						selector: '[data-sim="rail-add"]',
@@ -99,10 +99,10 @@ function activeCoach(step: Step, dialogOpen: boolean): CoachInfo | null {
 			return dialogOpen
 				? {
 						selector: '[data-testid="create-workspace"]',
-						side: "top",
+						side: "right",
 						scope: "viewport",
 						title: "Create the second workspace",
-						body: "One more isolated workspace for the second task. Click Create.",
+						body: "A second isolated workspace so the tasks run in parallel. Its prepared task starts here — click Create.",
 					}
 				: {
 						selector: '[data-sim="rail-add"]',
@@ -142,7 +142,7 @@ function activeCoach(step: Step, dialogOpen: boolean): CoachInfo | null {
 
 const WS_NAMES = ["Add search", "Completed filter"];
 
-export type CreateDialogArgs = { onCreate: () => void; onClose: () => void };
+export type CreateDialogArgs = { onCreate: () => void; onClose: () => void; prompt: string };
 
 export function OnboardingSimulation({
 	renderCreateDialog,
@@ -319,7 +319,11 @@ function Simulation({
 					/>
 				) : null}
 				{dialogOpen
-					? renderCreateDialog({ onCreate: onPreviewCreate, onClose: () => setDialogOpen(false) })
+					? renderCreateDialog({
+							onCreate: onPreviewCreate,
+							onClose: () => setDialogOpen(false),
+							prompt: step === "ws1-create" ? TASK_1 : TASK_2,
+						})
 					: null}
 				{step === "done" ? <Completion onFinish={() => closeDemo()} /> : null}
 
@@ -700,15 +704,15 @@ function CardSpotlight({
 					data-testid="onboarding-coach"
 					side={side}
 					align="center"
-					className="z-50 w-[260px] p-md"
+					className="z-50 w-[260px] border-primary bg-primary p-md text-text-on-primary"
 					onOpenAutoFocus={(event) => event.preventDefault()}
 					onEscapeKeyDown={(event) => event.preventDefault()}
 					onPointerDownOutside={(event) => event.preventDefault()}
 					onInteractOutside={(event) => event.preventDefault()}
 				>
-					<p className="tr-title-card text-text-default">{title}</p>
-					<p className="mt-xs text-text-muted tr-text-metadata leading-snug">{body}</p>
-					<PopoverArrow />
+					<p className="tr-title-card text-text-on-primary">{title}</p>
+					<p className="mt-xs tr-text-metadata leading-snug text-text-on-primary">{body}</p>
+					<PopoverArrow className="fill-primary" />
 				</PopoverContent>
 			</Popover>
 		</div>
@@ -745,15 +749,15 @@ function ViewportCoach({
 					data-testid="onboarding-coach"
 					side={side}
 					align="center"
-					className="z-[60] w-[260px] p-md"
+					className="z-[60] w-[260px] border-primary bg-primary p-md text-text-on-primary"
 					onOpenAutoFocus={(event) => event.preventDefault()}
 					onEscapeKeyDown={(event) => event.preventDefault()}
 					onPointerDownOutside={(event) => event.preventDefault()}
 					onInteractOutside={(event) => event.preventDefault()}
 				>
-					<p className="tr-title-card text-text-default">{title}</p>
-					<p className="mt-xs text-text-muted tr-text-metadata leading-snug">{body}</p>
-					<PopoverArrow />
+					<p className="tr-title-card text-text-on-primary">{title}</p>
+					<p className="mt-xs tr-text-metadata leading-snug text-text-on-primary">{body}</p>
+					<PopoverArrow className="fill-primary" />
 				</PopoverContent>
 			</Popover>
 		</>
diff --git a/apps/web/src/onboarding/SPEC.md b/apps/web/src/onboarding/SPEC.md
index 0afb84750..2547bb69c 100644
--- a/apps/web/src/onboarding/SPEC.md
+++ b/apps/web/src/onboarding/SPEC.md
@@ -39,14 +39,18 @@ App" card); both flip one **view flag** (`store.demoOpen`, a top-level, non-pers
 - **Close demo** (`onboarding-close`, a quiet `Button variant="ghost"` in the card's top-right) is present
   throughout — intro included — and is the only explicit pre-completion exit. It only clears the mocked
   experience (`closeDemo`); it touches no real state. Coach marks themselves stay non-dismissible.
+- **The two predetermined tasks** (used in the dialog prompt *and* later in the composer/chat, one source
+  of truth): *"Implement a search feature in my To Do app."* and *"Add filtering by tags so I can quickly
+  show tasks with a specific tag."*
 - **Reusing the real Create-workspace dialog.** Step 2 renders the production `panels/NewWorkspaceDialog`
   verbatim via a small **injected** `renderCreateDialog` render-prop (the shell composition root supplies
   it — same inversion it uses for `SettingsDialog`'s Layout section — so `onboarding` never imports
-  `panels`, no cycle). The dialog runs in an **inert `preview` mode** (a new optional prop on the shared
-  component, default off): all its wire reads are skipped and submit is short-circuited to a
-  `onPreviewCreate` callback, so the exact real dialog UI is taught while **no** workspace/session/wire
-  work happens. Its coach uses a **viewport-scoped** spotlight (the dialog is a portaled modal), a pulse
-  ring on its Create button + a tooltip; every other step uses the card-scoped spotlight.
+  `panels`, no cycle). The dialog runs in an **inert `preview` mode** (optional props on the shared
+  component, default off): all its wire reads are skipped, submit is short-circuited to `onPreviewCreate`,
+  and the Create button's `↵` key-badge is hidden (Create is text-only) — so the exact real dialog UI is
+  taught while **no** workspace/session/wire work happens. The task is passed through as the dialog's
+  `initialPrompt`. Its coach uses a **viewport-scoped** spotlight (the dialog is a portaled modal): a
+  pulse ring on Create + a tooltip to the dialog's right; every other step uses the card-scoped spotlight.
 - **Coach marks** reuse the tooltip + arrow treatment: a card-scoped **spotlight** dims everything inside
   the card except the current target with the `container-workspace-overlay` scrim (the workspace surface at
   the `veil` **50%** alpha step — a sanctioned color token, light enough to keep the interface legible;
@@ -59,6 +63,13 @@ App" card); both flip one **view flag** (`store.demoOpen`, a top-level, non-pers
 - The current actionable target wears a **temporary pulsing emphasis** — a `ring-2 ring-primary` glow at
   the target rect (`motion-safe:animate-pulse`; static under reduced motion), rendered by the spotlight
   and moving with it. It is onboarding-only emphasis, never a permanent hover/focus/selected/active state.
+- **Coach surface = inverted/high-contrast.** Every coach tooltip (both card- and viewport-scoped) renders
+  on `bg-primary` with `text-text-on-primary` and a `fill-primary` arrow, so it stands out from the dark
+  ThinkRail UI. **Design-system note:** the semantic layer has **no neutral light/inverse surface role**
+  (there is no `container-inverse`/`text-on-inverse`); per the design constraints we use the closest
+  existing high-contrast semantic combo (`primary` / `on-primary`) rather than inventing an
+  onboarding-specific token. If a literal neutral near-white inverse is wanted, that needs a new sanctioned
+  role — flagged, not bypassed.
 - A single **1px progress line** (`onboarding-progress`, `bg-primary`, smooth `transition-[width]`) sits on
   the card's bottom edge and advances across the scripted `STEP_ORDER`. No labels/percentages/dots.
 - Only the current target is interactive; everything else is present but inert (covered by the dim).
@@ -76,17 +87,17 @@ App" card); both flip one **view flag** (`store.demoOpen`, a top-level, non-pers
    `feedback-success`; onboarding emphasis, not a success state), extending slightly beyond the card
    without altering its background, border, or layout.
 2. **Create separate workspaces** — coach sits right of the left panel (arrow at the rail `+`); clicking
-   it opens the **real** `NewWorkspaceDialog` (see the preview seam below) and the coach re-points at that
-   dialog's **Create** button. Doing this twice yields two fake workspaces (`Add search`,
-   `Completed filter`), teaching the isolated worktree-per-task model on the real dialog UI. No real
-   worktrees are created.
-3. **Start the first agent** — switches into the first workspace's composer with the predetermined
-   *"Add search functionality to the To Do app."* **already prefilled** (no Insert button); the coach
-   highlights the existing **Send** button (pulsing primary ring). Send shows a brief "Working…" then a
-   predetermined successful result (a `setTimeout`, no model call), using the existing chat treatment.
+   it opens the **real** `NewWorkspaceDialog` (see the preview seam below) with its prompt **prefilled**
+   (focused, blinking caret — no fake typing) with that workspace's predetermined task, and the coach
+   re-points **to the right of the dialog** with its arrow at the emphasized **Create** button. Doing this
+   twice yields two fake workspaces. No real worktrees are created.
+3. **Start the first agent** — switches into the first workspace's composer with the first task **already
+   prefilled** (no Insert button); the coach highlights the existing **Send** button (pulsing primary
+   ring). Send shows a brief "Working…" then a predetermined successful result (a `setTimeout`, no model
+   call), using the existing chat treatment.
 4. **Run agents in parallel** — coach guides switching to the second workspace, whose composer is
-   **prefilled** with *"Add a filter for completed tasks."* (Send highlighted); the first workspace's row
-   shows it already **done** while the second works —
+   **prefilled** with the second task (Send highlighted); the first workspace's row shows it already
+   **done** while the second works —
    the payoff that separate workspaces hold independent, concurrent sessions. A left-panel note reinforces
    that switching tabs never stops a session.
 
diff --git a/apps/web/src/panels/NewWorkspaceDialog.tsx b/apps/web/src/panels/NewWorkspaceDialog.tsx
index 13c656af1..6cadff7bf 100644
--- a/apps/web/src/panels/NewWorkspaceDialog.tsx
+++ b/apps/web/src/panels/NewWorkspaceDialog.tsx
@@ -498,9 +498,11 @@ export function NewWorkspaceDialog({
 						className="flex h-8 shrink-0 items-center gap-sm rounded-[var(--radius-sm)] bg-control-primary-bg px-md tr-text-action text-control-primary-text outline-none transition-colors hover:bg-control-primary-bg-hovered focus-visible:ring-2 focus-visible:ring-primary disabled:bg-control-primary-disabled-bg disabled:text-control-primary-disabled-text"
 					>
 						{isolated ? "Create" : "Start"}
-						<span className="inline-flex h-4 min-w-4 items-center justify-center rounded-[var(--radius-sm)] bg-on-primary-soft px-1 tr-code-text">
-							↵
-						</span>
+						{preview ? null : (
+							<span className="inline-flex h-4 min-w-4 items-center justify-center rounded-[var(--radius-sm)] bg-on-primary-soft px-1 tr-code-text">
+								↵
+							</span>
+						)}
 					</button>
 				</div>
 				<SkillsDialog
diff --git a/apps/web/src/panels/SPEC.md b/apps/web/src/panels/SPEC.md
index aa457082b..1b203b45a 100644
--- a/apps/web/src/panels/SPEC.md
+++ b/apps/web/src/panels/SPEC.md
@@ -230,9 +230,11 @@ pre-session half of the user's skill settings; the chat header opens the same di
 **`NewWorkspaceDialog`** carries an optional, default-off **`preview` seam** (`preview` + `onPreviewCreate`)
 for the onboarding simulation to teach this exact dialog UI: when `preview` is set, every wire read (skills,
 aliases, model default/clamp, branch list, prefetch, model catalog) and the project-closed guard are
-skipped and submit is short-circuited to `onPreviewCreate` instead of `workspace.create`/`session.create`
-— so the real component renders with no network calls and creates no domain object. Production callers pass
-neither prop and are unaffected; the demo injects it via the shell (see [[submodule-web-onboarding]]).
+skipped, submit is short-circuited to `onPreviewCreate` instead of `workspace.create`/`session.create`, and
+the Create button's `↵` key-badge is hidden (Create renders text-only) — so the real component renders with
+no network calls and creates no domain object. The demo's predetermined task rides in through the normal
+`initialPrompt` (prefilled, focused). Production callers pass none of these and are unaffected; the demo
+injects it via the shell (see [[submodule-web-onboarding]]).
 
 **`NewWorkspaceDialog`** is the start-working surface: **a target control** (a two-option segment — a
 native radio group, `fieldset` + sr-only `legend` over visually-hidden radio inputs, so assistive tech
diff --git a/apps/web/src/shell/Shell.tsx b/apps/web/src/shell/Shell.tsx
index 3a2a94118..a823b7e2b 100644
--- a/apps/web/src/shell/Shell.tsx
+++ b/apps/web/src/shell/Shell.tsx
@@ -220,11 +220,12 @@ export function Shell() {
 			)}
 			<Toaster />
 			<OnboardingSimulation
-				renderCreateDialog={({ onCreate, onClose }) => (
+				renderCreateDialog={({ onCreate, onClose, prompt }) => (
 					<NewWorkspaceDialog
 						open
 						preview
 						projectId="onboarding-demo"
+						initialPrompt={prompt}
 						onOpenChange={(next) => {
 							if (!next) onClose();
 						}}
diff --git a/e2e/onboarding-demo.spec.ts b/e2e/onboarding-demo.spec.ts
index 02b4e034c..59688b9d5 100644
--- a/e2e/onboarding-demo.spec.ts
+++ b/e2e/onboarding-demo.spec.ts
@@ -22,30 +22,34 @@ test("the mocked onboarding simulation runs intro → scripted flow, never touch
 	await expect(coach).toContainText("Choose your project folder");
 	await page.getByTestId("sim-folder").click();
 
+	const task1 = "Implement a search feature in my To Do app.";
+	const task2 = "Add filtering by tags so I can quickly show tasks with a specific tag.";
+
 	await expect(coach).toContainText("Create a workspace");
 	await page.getByTestId("sim-add-workspace").click();
 	await expect(page.getByTestId("new-workspace-dialog")).toBeVisible();
+	await expect(page.getByTestId("ws-prompt")).toHaveValue(task1);
+	const createButton = page.getByTestId("create-workspace");
+	await expect(createButton).toHaveText("Create");
 	await expect(coach).toContainText("Create the workspace");
-	await page.getByTestId("create-workspace").click();
+	await createButton.click();
 
 	await expect(coach).toContainText("Create a second workspace");
 	await page.getByTestId("sim-add-workspace").click();
 	await expect(page.getByTestId("new-workspace-dialog")).toBeVisible();
-	await expect(coach).toContainText("Create the second workspace");
+	await expect(page.getByTestId("ws-prompt")).toHaveValue(task2);
 	await page.getByTestId("create-workspace").click();
 
 	await expect(coach).toContainText("Start the first agent");
 	await expect(page.getByTestId("onboarding-insert-prompt")).toHaveCount(0);
-	await expect(page.getByTestId("sim-composer")).toHaveValue(
-		"Add search functionality to the To Do app.",
-	);
+	await expect(page.getByTestId("sim-composer")).toHaveValue(task1);
 	await page.getByTestId("sim-send").click();
 
 	await expect(coach).toContainText("Switch to your second workspace");
 	await page.getByTestId("sim-ws-1").click();
 
 	await expect(coach).toContainText("Run a second agent in parallel");
-	await expect(page.getByTestId("sim-composer")).toHaveValue("Add a filter for completed tasks.");
+	await expect(page.getByTestId("sim-composer")).toHaveValue(task2);
 	await page.getByTestId("sim-send").click();
 
 	await page.getByTestId("onboarding-finish").click();

From 58c3b8fcd50be193ecd9cdab713c951da185c37e Mon Sep 17 00:00:00 2001
From: "Julia.Shilova" <Julia.Shilova@MacBook-Pro-5.local>
Date: Tue, 25 Aug 2026 12:50:03 +0300
Subject: [PATCH 20/23] feat(web): light/inverse surface for the onboarding
 folder picker
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The fake folder picker now reads as a system 'your computer' window: a
light/inverse neutral surface (radius-lg), a 'Your computer' header with a
plain 'Your computer › My Documents › Projects' breadcrumb (no /Users
path), and three columns communicating Your computer → My Documents →
Projects → to-do-app. Only to-do-app is actionable (primary pulse, coach
above with a downward arrow). Rest of the onboarding stays dark.

Since the semantic layer had no light/inverse surface (flagged last
iteration), the color model is extended with a small reusable inverse
family in colors.json — container-inverse-bg / container-inverse-selected
/ text-on-inverse(-muted) / border-inverse, derived from existing palette
keys + the shared alpha scale (no hardcoded grays, no picker-specific
tokens). colors bumped to v1.4.0; COLOR.md documents the family.

Fully mocked; no OS picker/filesystem/paths/backend. Specs + e2e green.
---
 .../src/onboarding/OnboardingSimulation.tsx   | 37 +++++++++----------
 apps/web/src/onboarding/SPEC.md               | 30 +++++++++------
 apps/web/src/styles/COLOR.md                  |  4 +-
 apps/web/src/styles/colors.json               | 30 ++++++++++++++-
 apps/web/src/styles/generated/colors.css      | 12 +++++-
 5 files changed, 79 insertions(+), 34 deletions(-)

diff --git a/apps/web/src/onboarding/OnboardingSimulation.tsx b/apps/web/src/onboarding/OnboardingSimulation.tsx
index b1f45dd9e..88d877622 100644
--- a/apps/web/src/onboarding/OnboardingSimulation.tsx
+++ b/apps/web/src/onboarding/OnboardingSimulation.tsx
@@ -1,6 +1,5 @@
 import {
 	Check,
-	ChevronLeft,
 	ChevronRight,
 	Folder,
 	FolderOpen,
@@ -476,24 +475,24 @@ function SimCenter({
 	if (step === "picker") {
 		return (
 			<div className="flex min-h-0 flex-1 bg-container-content-bg p-lg">
-				<div className="flex min-h-0 flex-1 flex-col overflow-hidden rounded-[var(--radius-md)] border border-border-default bg-container-elevated-bg shadow-[var(--shadow-md)]">
-					<div className="flex h-9 shrink-0 items-center gap-sm border-border-default border-b px-md text-text-muted">
-						<ChevronLeft className="size-4" />
-						<ChevronRight className="size-4" />
-						<span className="ml-sm tr-text-ui text-text-default">Projects</span>
+				<div className="flex min-h-0 flex-1 flex-col overflow-hidden rounded-[var(--radius-lg)] border border-border-inverse bg-container-inverse-bg text-text-on-inverse shadow-[var(--shadow-lg)]">
+					<div className="flex h-10 shrink-0 items-center gap-xs border-border-inverse border-b px-md">
+						<House className="size-4 shrink-0 text-text-on-inverse-muted" />
+						<span className="tr-text-ui text-text-on-inverse">Your computer</span>
+						<ChevronRight className="size-3.5 shrink-0 text-text-on-inverse-muted" />
+						<span className="tr-text-ui text-text-on-inverse-muted">My Documents</span>
+						<ChevronRight className="size-3.5 shrink-0 text-text-on-inverse-muted" />
+						<span className="tr-text-ui text-text-on-inverse-muted">Projects</span>
 					</div>
 					<div className="flex min-h-0 flex-1">
-						<PickerColumn className="w-[180px] bg-container-sidebar-bg" label="Locations">
+						<PickerColumn className="w-[200px]" label="Locations">
+							<PickerRow icon={House} name="Your computer" />
 							<PickerRow icon={Folder} name="Desktop" />
-							<PickerRow icon={Folder} name="Documents" />
+							<PickerRow icon={Folder} name="My Documents" selected />
 							<PickerRow icon={Folder} name="Downloads" />
-							<PickerRow icon={House} name="Home" selected />
 						</PickerColumn>
 						<PickerColumn className="w-[220px]">
-							<PickerRow icon={Folder} name="Applications" />
-							<PickerRow icon={Folder} name="Desktop" />
-							<PickerRow icon={Folder} name="Documents" />
-							<PickerRow icon={Folder} name="Downloads" />
+							<PickerRow icon={Folder} name="Notes" />
 							<PickerRow icon={Folder} name="Projects" selected chevron />
 						</PickerColumn>
 						<PickerColumn className="min-w-0 flex-1" last>
@@ -591,12 +590,12 @@ function PickerColumn({
 		<div
 			className={cn(
 				"flex min-h-0 flex-col gap-0.5 overflow-auto p-xs",
-				!last && "border-border-default border-r",
+				!last && "border-border-inverse border-r",
 				className,
 			)}
 		>
 			{label ? (
-				<span className="px-sm pt-xs pb-1 tr-text-eyebrow text-text-muted">{label}</span>
+				<span className="px-sm pt-xs pb-1 tr-text-eyebrow text-text-on-inverse-muted">{label}</span>
 			) : null}
 			{children}
 		</div>
@@ -626,13 +625,13 @@ function PickerRow({
 			className={cn(
 				"flex h-7 shrink-0 items-center gap-sm rounded-[var(--radius-sm)] px-sm text-left tr-text-ui transition-colors",
 				selected
-					? "bg-control-bg-selected text-primary"
-					: "text-text-default hover:bg-control-bg-hovered",
+					? "bg-container-inverse-selected text-text-on-inverse"
+					: "text-text-on-inverse hover:bg-container-inverse-selected",
 			)}
 		>
-			<Icon className={cn("size-4 shrink-0", selected ? "text-primary" : "text-text-muted")} />
+			<Icon className="size-4 shrink-0 text-text-on-inverse-muted" />
 			<span className="min-w-0 flex-1 truncate">{name}</span>
-			{chevron ? <ChevronRight className="size-3.5 shrink-0 text-text-muted" /> : null}
+			{chevron ? <ChevronRight className="size-3.5 shrink-0 text-text-on-inverse-muted" /> : null}
 		</button>
 	);
 }
diff --git a/apps/web/src/onboarding/SPEC.md b/apps/web/src/onboarding/SPEC.md
index 2547bb69c..b3d5b3930 100644
--- a/apps/web/src/onboarding/SPEC.md
+++ b/apps/web/src/onboarding/SPEC.md
@@ -65,11 +65,15 @@ App" card); both flip one **view flag** (`store.demoOpen`, a top-level, non-pers
   and moving with it. It is onboarding-only emphasis, never a permanent hover/focus/selected/active state.
 - **Coach surface = inverted/high-contrast.** Every coach tooltip (both card- and viewport-scoped) renders
   on `bg-primary` with `text-text-on-primary` and a `fill-primary` arrow, so it stands out from the dark
-  ThinkRail UI. **Design-system note:** the semantic layer has **no neutral light/inverse surface role**
-  (there is no `container-inverse`/`text-on-inverse`); per the design constraints we use the closest
-  existing high-contrast semantic combo (`primary` / `on-primary`) rather than inventing an
-  onboarding-specific token. If a literal neutral near-white inverse is wanted, that needs a new sanctioned
-  role — flagged, not bypassed.
+  ThinkRail UI.
+- **Inverse system surface (design-system extension).** The fake folder picker needed a neutral
+  light/inverse surface, which the semantic layer previously lacked. Rather than a picker-specific token,
+  the color model was **extended** with a small, reusable **inverse-surface family** in `styles/colors.json`:
+  `container-inverse-bg` (the theme *foreground* used as a surface — off-white on the dark themes, dark on
+  the light ones, i.e. always contrasting the app), `text-on-inverse` (+ `-muted`), `border-inverse`, and
+  `container-inverse-selected`, all derived from existing palette keys + the shared alpha scale. Any future
+  "this is the operating system / a system overlay" surface reuses it. Coach marks keep the `primary`
+  high-contrast treatment (brand emphasis), distinct from this neutral inverse.
 - A single **1px progress line** (`onboarding-progress`, `bg-primary`, smooth `transition-[width]`) sits on
   the card's bottom edge and advances across the scripted `STEP_ORDER`. No labels/percentages/dots.
 - Only the current target is interactive; everything else is present but inert (covered by the dim).
@@ -77,12 +81,16 @@ App" card); both flip one **view flag** (`store.demoOpen`, a top-level, non-pers
 ## Scripted flow (local `step` state machine, numbered "of 4")
 
 1. **Open a project** — empty-state Welcome with an "Open project" card (arrow points down to it); clicking
-   opens a **fake, simplified macOS-Finder-style folder picker** — a large three-column browser filling
-   the content area (Locations with **Home** selected → Home contents with **Projects** selected →
-   `my-app` / `notes` / `to-do-app`) plus a minimal toolbar, so it reads as a system folder window without
-   recreating Finder. Only `to-do-app` is interactive (spotlit with the pulsing primary emphasis, coach
-   above it, arrow down); everything else stays under the dim and does nothing. Selecting `to-do-app`
-   opens the fake "To Do App" project. Built from ThinkRail semantic tokens — no macOS assets/colors.
+   opens a **fake, simplified macOS-Finder-style folder picker** rendered on a **light / inverse system
+   surface** so it reads as "your computer" opened on top of the dark app (not another ThinkRail panel):
+   a header labelled **"Your computer"** with a plain **Your computer › My Documents › Projects**
+   breadcrumb (no technical `/Users/…` path), a `radius-lg` window, and three columns — Locations
+   (**My Documents** selected) → My Documents contents (**Projects** selected) → `my-app` / `notes` /
+   `to-do-app`. Only `to-do-app` is interactive (spotlit with the pulsing primary emphasis, coach above
+   it, arrow down); everything else stays under the dim and does nothing. Selecting `to-do-app` opens the
+   fake "To Do App" project. The light surface is the sanctioned **`container-inverse-*` / `text-on-inverse*`
+   / `border-inverse`** semantic family (see below) — no macOS assets or hardcoded grays. The rest of the
+   onboarding stays dark; only the picker inverts.
    The demo card carries a soft **brand glow** — a blurred `bg-primary-soft` layer behind it (not
    `feedback-success`; onboarding emphasis, not a success state), extending slightly beyond the card
    without altering its background, border, or layout.
diff --git a/apps/web/src/styles/COLOR.md b/apps/web/src/styles/COLOR.md
index 0c631218c..9434b2574 100644
--- a/apps/web/src/styles/COLOR.md
+++ b/apps/web/src/styles/COLOR.md
@@ -57,8 +57,8 @@ equals `border-default` is not a second weight, it is a second name).
 
 | family | tokens | notes |
 | --- | --- | --- |
-| Text | `text-default` · `text-muted` · `text-subtle` · `text-disabled` · `text-on-primary` | `text-subtle` (from the `hint` palette key) is the secondary-metadata tier (branch lines, spec role labels); `text-disabled` (the default `text` colour @ 60% — a disabled element inherits its enabled semantic colour, dimmed at the token level) is reserved for genuinely disabled UI text (e.g. the Settings "Soon" item) |
-| Container | `container-workspace-bg` · `container-sidebar-bg` · `container-terminal-bg` · `container-header-bg` · `container-content-bg` · `container-elevated-bg` | **The opened-document canvas is `workspace`, not `content`**: the Monaco file editor and the markdown/spec preview sit on the same surface as the chat column and the tab strip, so a document reads as part of the workspace. `content` is the **recessed diff canvas** — the Changes diff, rendered diffs, Shiki code blocks, and the Center Workbench backdrop behind them — which is why Monaco defines two themes (`EDITOR_THEME` = workspace, `THEME` = content). `terminal` is a terminal body + xterm canvas (currently sourced from the same palette key as `sidebar`); `elevated` is every raised surface |
+| Text | `text-default` · `text-muted` · `text-subtle` · `text-disabled` · `text-on-primary` · `text-on-inverse` · `text-on-inverse-muted` | `text-subtle` (from the `hint` palette key) is the secondary-metadata tier (branch lines, spec role labels); `text-disabled` (the default `text` colour @ 60% — a disabled element inherits its enabled semantic colour, dimmed at the token level) is reserved for genuinely disabled UI text (e.g. the Settings "Soon" item) |
+| Container | `container-workspace-bg` · `container-sidebar-bg` · `container-terminal-bg` · `container-header-bg` · `container-content-bg` · `container-elevated-bg` · `container-workspace-overlay` · `container-inverse-bg` · `container-inverse-selected` · `border-inverse` | **The opened-document canvas is `workspace`, not `content`**: the Monaco file editor and the markdown/spec preview sit on the same surface as the chat column and the tab strip, so a document reads as part of the workspace. `content` is the **recessed diff canvas** — the Changes diff, rendered diffs, Shiki code blocks, and the Center Workbench backdrop behind them — which is why Monaco defines two themes (`EDITOR_THEME` = workspace, `THEME` = content). `terminal` is a terminal body + xterm canvas (currently sourced from the same palette key as `sidebar`); `elevated` is every raised surface. `container-workspace-overlay` is the onboarding spotlight scrim (workspace bg @ `veil` 50%). The **`*-inverse*` family** is a neutral system/overlay surface that contrasts the app (the theme *foreground* used as a surface — off-white on the dark themes, dark on the light ones) with `text-on-inverse`(`-muted`), `border-inverse`, and `container-inverse-selected`; used for "this is your operating system" surfaces like the onboarding demo's fake folder picker |
 | Control | `control-bg` · `control-bg-hovered` · `control-bg-selected` · `control-primary-bg` · `control-primary-bg-hovered` · `control-primary-text` · `control-border-default` · `control-border-active` · `control-disabled-bg` · `control-disabled-text` · `control-disabled-border` · `control-primary-disabled-bg` · `control-primary-disabled-text` | The three `control-primary-*` tokens are the primary button/control, and they are **per-theme derivations like every other role** — `control-primary-bg` (from `accent`) fill, `control-primary-bg-hovered` (from `accentHover`) hover fill, `control-primary-text` (from `onAccent`) label. `accentHover` is the accent's **hover step**, its own manifest key so a theme owns that step: a primary button hovers to `control-primary-bg-hovered` (a colour token), never `hover:opacity-*`. Because the fill comes from `accent`, `bg-control-primary-bg` and `bg-primary` are the same colour by construction — a primary button can never drift from the theme's accent. `control-bg-hovered` is pointer hover only; `control-bg-selected` is the persistent selected/open/active/highlight fill (currently the same palette source). `control-border-default` is the resting form-control border; `control-border-active` (from `borderStrong`) is the **stronger neutral** border of an *active* control — pressed/`active:` buttons, an open selector (`data-[open=true]`), and a focused text input/textarea. It is the border only: the accent focus **ring** stays as the focus indicator (so accent = focus, neutral-strong = active). Never on inactive/default controls, nor on selected nav rows, tabs, or static surfaces. **Disabled is a first-class control state**, not an opacity utility: **a disabled element inherits the same semantic colour it uses when enabled, resolved at the `strong` (60%) alpha step** — derived at the token level so background, text, icon and border keep explicit ownership and nested content is never dimmed. So the disabled roles are the enabled ones @ 60%: `control-disabled-bg` (from `input`, i.e. `control-bg`), `control-disabled-text` (from `text`, i.e. `text-default`), `control-disabled-border` (from `border`, i.e. `control-border-default`), and the primary pair `control-primary-disabled-bg` (from `accent`, i.e. `control-primary-bg`) + `control-primary-disabled-text` (from `onAccent`, i.e. `control-primary-text`). There are **no** dedicated `disabled` / `primaryDisabled` / `onPrimaryDisabled` palette keys — a disabled state never carries a colour of its own. Text/icon-only controls take just `control-disabled-text`; non-control disabled text stays on `text-disabled`. Do **not** use `disabled:opacity-*` on a component (it dims nested content and bypasses token ownership) |
 | Border | `border-default` · `border-muted` | |
 | Primary | `primary` + `primary-subtle` · `-soft` · `-muted`, `on-primary-soft` | |
diff --git a/apps/web/src/styles/colors.json b/apps/web/src/styles/colors.json
index 09cd479a0..30cb9b8ec 100644
--- a/apps/web/src/styles/colors.json
+++ b/apps/web/src/styles/colors.json
@@ -1,7 +1,7 @@
 {
 	"$schema": "./colors.schema.json",
 	"metadata": {
-		"version": "1.3.0",
+		"version": "1.4.0",
 		"note": "The semantic colour layer. Palettes live in themes/bundled/*.theme.json; this file says what each palette entry is FOR, and is the only place a derivation is written. A role's `from` names a theme manifest key; the CSS variable that key writes to is derived (kebab-case), not tabulated. See COLOR.md."
 	},
 
@@ -42,6 +42,34 @@
 			"publish": true,
 			"note": "the onboarding spotlight scrim: the workspace surface at the `veil` (50%) alpha step, dimming the demo card while a coach mark spotlights one target — light enough to keep the interface legible underneath"
 		},
+		"container-inverse-bg": {
+			"from": "text",
+			"publish": true,
+			"note": "an inverted/system surface that contrasts the app — the theme's foreground colour used AS a surface (an off-white light panel on the dark themes, a dark panel on the light ones); for temporary 'this is your operating system' surfaces like the onboarding demo's fake folder picker"
+		},
+		"container-inverse-selected": {
+			"from": "background",
+			"alpha": "soft",
+			"publish": true,
+			"note": "selected-row fill on a `container-inverse` surface: the app background tinted onto the inverse surface"
+		},
+		"text-on-inverse": {
+			"from": "background",
+			"publish": true,
+			"note": "primary text/icons on a `container-inverse` surface (the app background colour, dark on the dark themes)"
+		},
+		"text-on-inverse-muted": {
+			"from": "background",
+			"alpha": "strong",
+			"publish": true,
+			"note": "secondary text/icons on a `container-inverse` surface: the on-inverse colour at the `strong` (60%) alpha step"
+		},
+		"border-inverse": {
+			"from": "background",
+			"alpha": "wash",
+			"publish": true,
+			"note": "separators/borders on a `container-inverse` surface"
+		},
 		"container-sidebar-bg": { "from": "sidebar", "publish": true },
 		"container-terminal-bg": { "from": "sidebar", "publish": true },
 		"container-header-bg": { "from": "header", "publish": true },
diff --git a/apps/web/src/styles/generated/colors.css b/apps/web/src/styles/generated/colors.css
index 34394b88a..d0af2bbb2 100644
--- a/apps/web/src/styles/generated/colors.css
+++ b/apps/web/src/styles/generated/colors.css
@@ -1,5 +1,5 @@
 /*
- * GENERATED — do not edit. Source: `src/styles/colors.json` (v1.3.0).
+ * GENERATED — do not edit. Source: `src/styles/colors.json` (v1.4.0).
  * Regenerate with `bun run colors:generate`; `colors:check` fails when this file is stale.
  *
  * The semantic roles, then the Tailwind utility map. The palette they read is written to the
@@ -15,6 +15,11 @@
 	--text-link: var(--info); /* global.css `a {}` is the only consumer; no component styles a bare link */
 	--container-workspace-bg: var(--background); /* the app surface, and with it the opened-document canvas — a document reads as part of the workspace (Monaco's EDITOR_THEME, the markdown/spec preview, the chat column, the tab strip) */
 	--container-workspace-overlay: color-mix(in srgb, var(--background) 50%, transparent); /* the onboarding spotlight scrim: the workspace surface at the `veil` (50%) alpha step, dimming the demo card while a coach mark spotlights one target — light enough to keep the interface legible underneath */
+	--container-inverse-bg: var(--text); /* an inverted/system surface that contrasts the app — the theme's foreground colour used AS a surface (an off-white light panel on the dark themes, a dark panel on the light ones); for temporary 'this is your operating system' surfaces like the onboarding demo's fake folder picker */
+	--container-inverse-selected: color-mix(in srgb, var(--background) 20%, transparent); /* selected-row fill on a `container-inverse` surface: the app background tinted onto the inverse surface */
+	--text-on-inverse: var(--background); /* primary text/icons on a `container-inverse` surface (the app background colour, dark on the dark themes) */
+	--text-on-inverse-muted: color-mix(in srgb, var(--background) 60%, transparent); /* secondary text/icons on a `container-inverse` surface: the on-inverse colour at the `strong` (60%) alpha step */
+	--border-inverse: color-mix(in srgb, var(--background) 12%, transparent); /* separators/borders on a `container-inverse` surface */
 	--container-sidebar-bg: var(--sidebar);
 	--container-terminal-bg: var(--sidebar);
 	--container-header-bg: var(--header);
@@ -85,6 +90,11 @@
 	--color-text-on-primary: var(--text-on-primary);
 	--color-container-workspace-bg: var(--container-workspace-bg);
 	--color-container-workspace-overlay: var(--container-workspace-overlay);
+	--color-container-inverse-bg: var(--container-inverse-bg);
+	--color-container-inverse-selected: var(--container-inverse-selected);
+	--color-text-on-inverse: var(--text-on-inverse);
+	--color-text-on-inverse-muted: var(--text-on-inverse-muted);
+	--color-border-inverse: var(--border-inverse);
 	--color-container-sidebar-bg: var(--container-sidebar-bg);
 	--color-container-terminal-bg: var(--container-terminal-bg);
 	--color-container-header-bg: var(--container-header-bg);

From 80b0a74ae985f1694b6156acdf01e992ec0b9995 Mon Sep 17 00:00:00 2001
From: "Julia.Shilova" <Julia.Shilova@MacBook-Pro-5.local>
Date: Tue, 25 Aug 2026 13:04:37 +0300
Subject: [PATCH 21/23] feat(web): parallel-agents payoff in the onboarding
 demo
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The second half now demonstrates working with two agents in parallel,
fully mocked inside the demo container:

- Create Workspace: both dialogs animate the task typing into the real
  NewWorkspaceDialog prompt (preview seam) with Create inactive until the
  text finishes; reduced-motion populates instantly. onPreviewReady gates
  the Create coach.
- First workspace: agent shows concise activity (reads → plan → Working…)
  and keeps running when the user moves on.
- Second workspace: a faithful mocked workbench — active agent chat +
  right-side Files/Specs/Changes strip + bottom Terminal strip — then the
  agent pauses with a mocked question widget (options + custom field).
  A coach guides answering; on answer the agent resumes.
- Parallel payoff: coach moves to the left nav and highlights the first
  workspace (still running); returning to it shows the first task
  completed (result + Changes summary).
- Final state: central primary-subtle 'That's the workflow.' surface with
  Finish + a 'Learn more in the docs' link (existing https://thinkrail.ai);
  progress line at 100%.

Faithful mocks for the chat/workbench/terminal/question surfaces (the real
ones are chat-runtime/store-coupled); only NewWorkspaceDialog is the real
component via the preview seam. No agents/sessions/workspaces/wire/fs.
Coach-mark behavior, spotlight, progress, Close demo, intro/Git-readiness,
light picker all preserved. Specs + e2e updated.
---
 .../src/onboarding/OnboardingSimulation.tsx   | 600 +++++++++++-------
 apps/web/src/onboarding/SPEC.md               |  54 +-
 apps/web/src/panels/NewWorkspaceDialog.tsx    |  39 +-
 apps/web/src/panels/SPEC.md                   |   5 +-
 apps/web/src/shell/Shell.tsx                  |   3 +-
 e2e/onboarding-demo.spec.ts                   |  42 +-
 6 files changed, 467 insertions(+), 276 deletions(-)

diff --git a/apps/web/src/onboarding/OnboardingSimulation.tsx b/apps/web/src/onboarding/OnboardingSimulation.tsx
index 88d877622..86c771914 100644
--- a/apps/web/src/onboarding/OnboardingSimulation.tsx
+++ b/apps/web/src/onboarding/OnboardingSimulation.tsx
@@ -1,6 +1,7 @@
 import {
 	Check,
 	ChevronRight,
+	FileText,
 	Folder,
 	FolderOpen,
 	GitBranch,
@@ -8,7 +9,7 @@ import {
 	Loader2,
 	type LucideIcon,
 	Plus,
-	Send,
+	SquareTerminal,
 	X,
 } from "lucide-react";
 import { type ReactNode, useCallback, useEffect, useRef, useState } from "react";
@@ -19,38 +20,95 @@ import { cn } from "../lib";
 import { useAppStore } from "../store";
 import { useTargetRect } from "./anchor";
 
+const DOCS_URL = "https://thinkrail.ai";
+
 const TASK_1 = "Implement a search feature in my To Do app.";
 const TASK_2 = "Add filtering by tags so I can quickly show tasks with a specific tag.";
-const RESULT_1 =
-	"Added a live search box that filters tasks as you type — a new searchTasks() in src/app.js wired to an input in index.html.";
-const RESULT_2 =
-	"Added an All / Active / Completed filter above the list, with the chosen filter remembered across reloads.";
+const WS_NAMES = ["Search feature", "Tag filtering"];
+
+const QUESTION = "Where should tag filters appear?";
+const QUESTION_OPTIONS = ["Above the task list", "In the sidebar", "Next to the search field"];
+
+type Activity =
+	| { id: string; kind: "user" | "note" | "result"; text: string }
+	| { id: string; kind: "tool"; text: string }
+	| { id: string; kind: "working"; text: string }
+	| { id: string; kind: "changes"; text: string };
+
+const uid = () => crypto.randomUUID();
+
+function ws1Working(): Activity[] {
+	return [
+		{ id: uid(), kind: "user", text: TASK_1 },
+		{ id: uid(), kind: "tool", text: "Read index.html" },
+		{ id: uid(), kind: "tool", text: "Read src/app.js" },
+		{ id: uid(), kind: "note", text: "Plan: add a search box that filters tasks as you type." },
+		{ id: uid(), kind: "working", text: "Implementing search…" },
+	];
+}
+
+function ws1Done(): Activity[] {
+	return [
+		{ id: uid(), kind: "user", text: TASK_1 },
+		{ id: uid(), kind: "tool", text: "Edit src/app.js" },
+		{ id: uid(), kind: "tool", text: "Edit index.html" },
+		{
+			id: uid(),
+			kind: "result",
+			text: "Search is live — a searchTasks() filter wired to a new input; tasks narrow as you type.",
+		},
+		{ id: uid(), kind: "changes", text: "2 files changed · +38 −4" },
+	];
+}
+
+function ws2Thinking(): Activity[] {
+	return [
+		{ id: uid(), kind: "user", text: TASK_2 },
+		{ id: uid(), kind: "tool", text: "Read src/app.js" },
+		{
+			id: uid(),
+			kind: "note",
+			text: "Thinking about where the tag filters should live in the UI…",
+		},
+	];
+}
+
+function ws2Resume(choice: string): Activity[] {
+	return [
+		{ id: uid(), kind: "note", text: `Got it — placing the filters ${choice.toLowerCase()}.` },
+		{ id: uid(), kind: "tool", text: "Edit src/app.js" },
+		{ id: uid(), kind: "working", text: "Adding tag parsing and the filter row…" },
+	];
+}
 
 type Step =
 	| "intro"
 	| "open"
 	| "picker"
 	| "ws1-create"
+	| "ws1-working"
 	| "ws2-create"
-	| "agent1"
-	| "agent2-switch"
-	| "agent2"
-	| "done";
+	| "ws2-working"
+	| "ws2-question"
+	| "ws2-resume"
+	| "ws1-done"
+	| "final";
 
 const STEP_ORDER: Step[] = [
 	"intro",
 	"open",
 	"picker",
 	"ws1-create",
+	"ws1-working",
 	"ws2-create",
-	"agent1",
-	"agent2-switch",
-	"agent2",
-	"done",
+	"ws2-working",
+	"ws2-question",
+	"ws2-resume",
+	"ws1-done",
+	"final",
 ];
 
 type WsStatus = "idle" | "working" | "done";
-type Msg = { id: string; role: "user" | "assistant" | "working"; text?: string };
 
 type CoachInfo = {
 	selector: string;
@@ -60,7 +118,7 @@ type CoachInfo = {
 	body: string;
 };
 
-function activeCoach(step: Step, dialogOpen: boolean): CoachInfo | null {
+function activeCoach(step: Step, dialogOpen: boolean, dialogReady: boolean): CoachInfo | null {
 	switch (step) {
 		case "open":
 			return {
@@ -79,69 +137,59 @@ function activeCoach(step: Step, dialogOpen: boolean): CoachInfo | null {
 				body: "Select the To Do App folder to open it in ThinkRail.",
 			};
 		case "ws1-create":
-			return dialogOpen
-				? {
-						selector: '[data-testid="create-workspace"]',
-						side: "right",
-						scope: "viewport",
-						title: "Create the workspace",
-						body: "A workspace isolates this task on its own branch. The prepared task will start here — click Create.",
-					}
-				: {
-						selector: '[data-sim="rail-add"]',
-						side: "right",
-						scope: "card",
-						title: "Create a workspace",
-						body: "ThinkRail runs each task in its own isolated worktree and branch. Open the New workspace dialog.",
-					};
-		case "ws2-create":
-			return dialogOpen
-				? {
-						selector: '[data-testid="create-workspace"]',
-						side: "right",
-						scope: "viewport",
-						title: "Create the second workspace",
-						body: "A second isolated workspace so the tasks run in parallel. Its prepared task starts here — click Create.",
-					}
-				: {
-						selector: '[data-sim="rail-add"]',
-						side: "right",
-						scope: "card",
-						title: "Create a second workspace",
-						body: "Add a second workspace so two tasks run side by side, each on its own branch.",
-					};
-		case "agent1":
+		case "ws2-create": {
+			if (!dialogOpen)
+				return {
+					selector: '[data-sim="rail-add"]',
+					side: "right",
+					scope: "card",
+					title: step === "ws1-create" ? "Create a workspace" : "Create a second workspace",
+					body: "Each task runs in its own isolated worktree and branch. Open the New workspace dialog.",
+				};
+			if (!dialogReady) return null;
 			return {
-				selector: '[data-sim="send"]',
-				side: "top",
+				selector: '[data-testid="create-workspace"]',
+				side: "right",
+				scope: "viewport",
+				title: "Create the workspace",
+				body: "The task is ready. Create the workspace to start it on its own branch.",
+			};
+		}
+		case "ws1-working":
+			return {
+				selector: '[data-sim="rail-add"]',
+				side: "right",
 				scope: "card",
-				title: "Start the first agent",
-				body: "The prompt is ready — send it to the agent.",
+				title: "Now start a second task",
+				body: "Your first agent keeps working here. Open a second workspace for the next task.",
 			};
-		case "agent2-switch":
+		case "ws2-question":
 			return {
-				selector: '[data-sim="ws-1"]',
+				selector: '[data-sim="question"]',
 				side: "right",
 				scope: "card",
-				title: "Switch to your second workspace",
-				body: "Your first agent keeps working — switch over to start the next one.",
+				title: "Give the agent feedback",
+				body: "Choose one of the suggestions or write your own.",
 			};
-		case "agent2":
+		case "ws2-resume":
 			return {
-				selector: '[data-sim="send"]',
-				side: "top",
+				selector: '[data-sim="ws-0"]',
+				side: "right",
 				scope: "card",
-				title: "Run a second agent in parallel",
-				body: "Both agents run at the same time, each in its own workspace. Send to start.",
+				title: "Your agents work in parallel",
+				body: "Your first task kept running in another workspace. Check its progress.",
 			};
 		default:
 			return null;
 	}
 }
 
-const WS_NAMES = ["Add search", "Completed filter"];
-
-export type CreateDialogArgs = { onCreate: () => void; onClose: () => void; prompt: string };
+export type CreateDialogArgs = {
+	onCreate: () => void;
+	onClose: () => void;
+	onReady: () => void;
+	prompt: string;
+};
 
 export function OnboardingSimulation({
 	renderCreateDialog,
@@ -180,70 +228,67 @@ function Simulation({
 	const startTour = useCallback(() => setStep("open"), []);
 	const [workspaces, setWorkspaces] = useState<string[]>([]);
 	const [activeWs, setActiveWs] = useState(0);
-	const [drafts, setDrafts] = useState<Record<number, string>>({});
-	const [messages, setMessages] = useState<Record<number, Msg[]>>({});
+	const [messages, setMessages] = useState<Record<number, Activity[]>>({});
 	const [status, setStatus] = useState<Record<number, WsStatus>>({});
 	const [dialogOpen, setDialogOpen] = useState(false);
+	const [dialogReady, setDialogReady] = useState(false);
 	const timers = useRef<ReturnType<typeof setTimeout>[]>([]);
-	useEffect(() => () => timers.current.forEach(clearTimeout), []);
+	const after = useCallback((ms: number, fn: () => void) => {
+		timers.current.push(setTimeout(fn, ms));
+	}, []);
+	useEffect(() => {
+		const list = timers.current;
+		return () => list.forEach(clearTimeout);
+	}, []);
 
 	const projectOpen = step !== "intro" && step !== "open" && step !== "picker";
-	const coach = activeCoach(step, dialogOpen);
+	const coach = activeCoach(step, dialogOpen, dialogReady);
 	const progress = STEP_ORDER.indexOf(step) / (STEP_ORDER.length - 1);
 
 	const onRailAdd = () => {
-		if (step === "ws1-create" || step === "ws2-create") setDialogOpen(true);
+		if (step === "ws1-working") setStep("ws2-create");
+		if (step === "ws1-create" || step === "ws2-create" || step === "ws1-working") {
+			setDialogReady(false);
+			setDialogOpen(true);
+		}
 	};
 
 	const onPreviewCreate = () => {
 		if (step === "ws1-create") {
 			setWorkspaces([WS_NAMES[0] as string]);
+			setActiveWs(0);
+			setStatus({ 0: "working" });
+			setMessages({ 0: ws1Working() });
 			setDialogOpen(false);
-			setStep("ws2-create");
+			setStep("ws1-working");
 		} else if (step === "ws2-create") {
 			setWorkspaces([WS_NAMES[0] as string, WS_NAMES[1] as string]);
-			setActiveWs(0);
-			setDrafts((d) => ({ ...d, 0: TASK_1 }));
-			setDialogOpen(false);
-			setStep("agent1");
-		}
-	};
-
-	const onWsClick = (index: number) => {
-		if (step === "agent2-switch" && index === 1) {
 			setActiveWs(1);
-			setDrafts((d) => ({ ...d, 1: TASK_2 }));
-			setStep("agent2");
+			setStatus({ 0: "working", 1: "working" });
+			setMessages((m) => ({ ...m, 1: ws2Thinking() }));
+			setDialogOpen(false);
+			setStep("ws2-working");
+			after(1600, () => setStep("ws2-question"));
 		}
 	};
 
-	const send = () => {
-		const ws = activeWs;
-		const text = (drafts[ws] ?? "").trim();
-		if (!text || status[ws] === "working") return;
-		const result = ws === 0 ? RESULT_1 : RESULT_2;
-		setDrafts((d) => ({ ...d, [ws]: "" }));
-		setStatus((s) => ({ ...s, [ws]: "working" }));
+	const onAnswer = (choice: string) => {
+		if (step !== "ws2-question") return;
 		setMessages((m) => ({
 			...m,
-			[ws]: [
-				...(m[ws] ?? []),
-				{ id: crypto.randomUUID(), role: "user", text },
-				{ id: crypto.randomUUID(), role: "working" },
-			],
+			1: [...(m[1] ?? []), { id: uid(), kind: "user", text: choice }, ...ws2Resume(choice)],
 		}));
-		const timer = setTimeout(() => {
-			setMessages((m) => ({
-				...m,
-				[ws]: [
-					...(m[ws] ?? []).filter((msg) => msg.role !== "working"),
-					{ id: crypto.randomUUID(), role: "assistant", text: result },
-				],
-			}));
-			setStatus((s) => ({ ...s, [ws]: "done" }));
-			setStep(ws === 0 ? "agent2-switch" : "done");
-		}, 1400);
-		timers.current.push(timer);
+		setStep("ws2-resume");
+	};
+
+	const onWsClick = (index: number) => {
+		if (step === "ws2-resume" && index === 0) {
+			setActiveWs(0);
+			setStatus((s) => ({ ...s, 0: "done" }));
+			setMessages((m) => ({ ...m, 0: ws1Done() }));
+			setStep("ws1-done");
+			after(1900, () => setStep("final"));
+		}
 	};
 
 	return (
@@ -286,16 +331,13 @@ function Simulation({
 						onRailAdd={onRailAdd}
 						onWsClick={onWsClick}
 					/>
-					<SimCenter
+					<SimMain
 						step={step}
-						activeWs={activeWs}
-						messages={messages}
-						status={status}
-						draft={drafts[activeWs] ?? ""}
-						onDraft={(v) => setDrafts((d) => ({ ...d, [activeWs]: v }))}
+						rows={messages[activeWs] ?? []}
 						onOpenProject={() => setStep("picker")}
 						onPickFolder={() => setStep("ws1-create")}
-						onSend={send}
+						onAnswer={onAnswer}
+						onFinish={() => closeDemo()}
 					/>
 				</div>
 
@@ -321,10 +363,10 @@ function Simulation({
 					? renderCreateDialog({
 							onCreate: onPreviewCreate,
 							onClose: () => setDialogOpen(false),
+							onReady: () => setDialogReady(true),
 							prompt: step === "ws1-create" ? TASK_1 : TASK_2,
 						})
 					: null}
-				{step === "done" ? <Completion onFinish={() => closeDemo()} /> : null}
 
 				<div className="pointer-events-none absolute inset-x-0 bottom-0 z-50 h-px">
 					<div
@@ -355,6 +397,7 @@ function SimLeftPanel({
 	onRailAdd: () => void;
 	onWsClick: (index: number) => void;
 }) {
+	const parallel = step === "ws2-working" || step === "ws2-question" || step === "ws2-resume";
 	return (
 		<aside className="flex w-[220px] shrink-0 flex-col gap-sm border-border-default border-r bg-container-sidebar-bg p-md">
 			<span className="tr-text-eyebrow text-text-muted">Projects</span>
@@ -390,11 +433,12 @@ function SimLeftPanel({
 									data-sim={`ws-${index}`}
 									data-testid={`sim-ws-${index}`}
 									onClick={() => onWsClick(index)}
-									className={`flex h-7 w-full items-center gap-sm rounded-[var(--radius-sm)] pr-xs pl-xl text-left tr-text-ui transition-colors ${
+									className={cn(
+										"flex h-7 w-full items-center gap-sm rounded-[var(--radius-sm)] pr-xs pl-xl text-left tr-text-ui transition-colors",
 										index === activeWs
 											? "bg-control-bg-selected text-primary"
-											: "text-text-muted hover:bg-control-bg-hovered"
-									}`}
+											: "text-text-muted hover:bg-control-bg-hovered",
+									)}
 								>
 									<GitBranch className="size-4 shrink-0" />
 									<span className="flex-1 truncate">{name}</span>
@@ -408,9 +452,9 @@ function SimLeftPanel({
 							</li>
 						))}
 					</ul>
-					{step === "agent2" || step === "agent2-switch" ? (
+					{parallel ? (
 						<span className="mt-sm pl-sm text-text-subtle tr-text-metadata leading-snug">
-							Both workspaces keep their own agent session — switching tabs never stops them.
+							Each workspace keeps its own agent session — switching views never stops them.
 						</span>
 					) : null}
 				</>
@@ -421,26 +465,20 @@ function SimLeftPanel({
 	);
 }
 
-function SimCenter({
+function SimMain({
 	step,
-	activeWs,
-	messages,
-	status,
-	draft,
-	onDraft,
+	rows,
 	onOpenProject,
 	onPickFolder,
-	onSend,
+	onAnswer,
+	onFinish,
 }: {
 	step: Step;
-	activeWs: number;
-	messages: Record<number, Msg[]>;
-	status: Record<number, WsStatus>;
-	draft: string;
-	onDraft: (value: string) => void;
+	rows: Activity[];
 	onOpenProject: () => void;
 	onPickFolder: () => void;
-	onSend: () => void;
+	onAnswer: (choice: string) => void;
+	onFinish: () => void;
 }) {
 	if (step === "open") {
 		return (
@@ -473,37 +511,7 @@ function SimCenter({
 		);
 	}
 	if (step === "picker") {
-		return (
-			<div className="flex min-h-0 flex-1 bg-container-content-bg p-lg">
-				<div className="flex min-h-0 flex-1 flex-col overflow-hidden rounded-[var(--radius-lg)] border border-border-inverse bg-container-inverse-bg text-text-on-inverse shadow-[var(--shadow-lg)]">
-					<div className="flex h-10 shrink-0 items-center gap-xs border-border-inverse border-b px-md">
-						<House className="size-4 shrink-0 text-text-on-inverse-muted" />
-						<span className="tr-text-ui text-text-on-inverse">Your computer</span>
-						<ChevronRight className="size-3.5 shrink-0 text-text-on-inverse-muted" />
-						<span className="tr-text-ui text-text-on-inverse-muted">My Documents</span>
-						<ChevronRight className="size-3.5 shrink-0 text-text-on-inverse-muted" />
-						<span className="tr-text-ui text-text-on-inverse-muted">Projects</span>
-					</div>
-					<div className="flex min-h-0 flex-1">
-						<PickerColumn className="w-[200px]" label="Locations">
-							<PickerRow icon={House} name="Your computer" />
-							<PickerRow icon={Folder} name="Desktop" />
-							<PickerRow icon={Folder} name="My Documents" selected />
-							<PickerRow icon={Folder} name="Downloads" />
-						</PickerColumn>
-						<PickerColumn className="w-[220px]">
-							<PickerRow icon={Folder} name="Notes" />
-							<PickerRow icon={Folder} name="Projects" selected chevron />
-						</PickerColumn>
-						<PickerColumn className="min-w-0 flex-1" last>
-							<PickerRow icon={Folder} name="my-app" />
-							<PickerRow icon={Folder} name="notes" />
-							<PickerRow icon={Folder} name="to-do-app" target onSelect={onPickFolder} />
-						</PickerColumn>
-					</div>
-				</div>
-			</div>
-		);
+		return <FolderPicker onPickFolder={onPickFolder} />;
 	}
 	if (step === "ws1-create" || step === "ws2-create") {
 		return (
@@ -516,59 +524,218 @@ function SimCenter({
 			</Center>
 		);
 	}
-	const rows = messages[activeWs] ?? [];
+	if (step === "final") {
+		return (
+			<div className="flex min-h-0 flex-1 items-center justify-center bg-container-content-bg p-xl">
+				<div className="w-[420px] rounded-[var(--radius-md)] border border-primary-muted bg-clip-padding bg-primary-subtle p-lg text-center">
+					<p className="tr-brand-hero text-primary">That's the workflow.</p>
+					<p className="mt-sm text-text-muted tr-text-ui">Now try it with your own project.</p>
+					<div className="mt-lg flex items-center justify-center gap-md">
+						<Button size="sm" data-testid="onboarding-finish" onClick={onFinish}>
+							Finish
+						</Button>
+						<a
+							href={DOCS_URL}
+							target="_blank"
+							rel="noreferrer"
+							data-testid="onboarding-docs"
+							className="tr-text-ui text-primary underline underline-offset-2 hover:text-text-default"
+						>
+							Learn more in the docs
+						</a>
+					</div>
+				</div>
+			</div>
+		);
+	}
 	return (
 		<div className="flex min-h-0 flex-1 flex-col bg-container-content-bg">
-			<div className="flex min-h-0 flex-1 flex-col gap-sm overflow-auto p-lg">
-				{rows.length === 0 ? (
-					<p className="m-auto text-text-subtle tr-text-metadata">
-						Start the agent below to build this task.
-					</p>
-				) : (
-					rows.map((msg) =>
-						msg.role === "user" ? (
-							<div
-								key={msg.id}
-								className="max-w-[80%] self-end rounded-[var(--radius-md)] border border-bubble-user-border bg-bubble-user-bg px-md py-sm tr-text-ui text-text-default"
-							>
-								{msg.text}
-							</div>
-						) : msg.role === "working" ? (
-							<div
-								key={msg.id}
-								className="inline-flex items-center gap-sm self-start text-text-muted tr-text-metadata"
-							>
-								<span className="size-2 animate-pulse rounded-full bg-primary" />
-								Working…
-							</div>
-						) : (
-							<div key={msg.id} className="max-w-[80%] self-start tr-text-ui text-text-default">
-								{msg.text}
-							</div>
-						),
-					)
-				)}
+			<div className="flex min-h-0 flex-1">
+				<AgentChat rows={rows} question={step === "ws2-question"} onAnswer={onAnswer} />
+				<WorkbenchSides />
 			</div>
-			<div data-sim="composer" className="border-border-default border-t p-md">
-				<div className="flex items-end gap-sm rounded-[var(--radius-md)] border border-control-border-default bg-container-workspace-bg p-sm">
-					<textarea
-						data-testid="sim-composer"
-						value={draft}
-						onChange={(event) => onDraft(event.target.value)}
-						placeholder="Ask the agent…"
-						rows={2}
-						className="min-h-[40px] flex-1 resize-none bg-transparent tr-text-ui text-text-default outline-none placeholder:text-text-subtle"
-					/>
+			<TerminalStrip />
+		</div>
+	);
+}
+
+function AgentChat({
+	rows,
+	question,
+	onAnswer,
+}: {
+	rows: Activity[];
+	question: boolean;
+	onAnswer: (choice: string) => void;
+}) {
+	return (
+		<div className="flex min-h-0 flex-1 flex-col gap-sm overflow-auto p-lg">
+			{rows.map((row) => (
+				<ActivityRow key={row.id} row={row} />
+			))}
+			{question ? <QuestionWidget onAnswer={onAnswer} /> : null}
+		</div>
+	);
+}
+
+function ActivityRow({ row }: { row: Activity }) {
+	switch (row.kind) {
+		case "user":
+			return (
+				<div className="max-w-[80%] self-end rounded-[var(--radius-md)] border border-bubble-user-border bg-bubble-user-bg px-md py-sm tr-text-ui text-text-default">
+					{row.text}
+				</div>
+			);
+		case "note":
+			return <div className="max-w-[85%] self-start tr-text-ui text-text-default">{row.text}</div>;
+		case "tool":
+			return (
+				<div className="inline-flex items-center gap-sm self-start rounded-[var(--radius-sm)] border border-border-default bg-container-elevated-bg px-sm py-0.5 text-text-muted tr-code-text">
+					<FileText className="size-3.5 shrink-0" />
+					{row.text}
+				</div>
+			);
+		case "working":
+			return (
+				<div className="inline-flex items-center gap-sm self-start text-text-muted tr-text-metadata">
+					<span className="size-2 animate-pulse rounded-full bg-primary" />
+					{row.text}
+				</div>
+			);
+		case "result":
+			return (
+				<div className="flex max-w-[85%] items-start gap-sm self-start tr-text-ui text-text-default">
+					<Check className="mt-0.5 size-4 shrink-0 text-feedback-success" />
+					<span>{row.text}</span>
+				</div>
+			);
+		case "changes":
+			return (
+				<div className="inline-flex items-center gap-sm self-start rounded-[var(--radius-sm)] border border-border-default bg-container-elevated-bg px-sm py-0.5 text-text-muted tr-text-metadata">
+					<GitBranch className="size-3.5 shrink-0" />
+					{row.text}
+				</div>
+			);
+	}
+}
+
+function QuestionWidget({ onAnswer }: { onAnswer: (choice: string) => void }) {
+	const [custom, setCustom] = useState("");
+	return (
+		<div
+			data-sim="question"
+			data-testid="onboarding-question"
+			className="w-full max-w-[85%] self-start rounded-[var(--radius-md)] border border-border-default bg-container-elevated-bg p-md"
+		>
+			<p className="tr-text-ui text-text-default">{QUESTION}</p>
+			<div className="mt-sm flex flex-col gap-xs">
+				{QUESTION_OPTIONS.map((option) => (
 					<Button
+						key={option}
+						variant="outline"
 						size="sm"
-						data-sim="send"
-						data-testid="sim-send"
-						disabled={!draft.trim() || status[activeWs] === "working"}
-						onClick={onSend}
+						data-testid="sim-question-option"
+						className="justify-start"
+						onClick={() => onAnswer(option)}
 					>
-						<Send className="size-4" />
-						Send
+						{option}
 					</Button>
+				))}
+			</div>
+			<div className="mt-sm flex items-end gap-sm rounded-[var(--radius-sm)] border border-control-border-default bg-container-workspace-bg p-sm">
+				<input
+					data-testid="sim-question-custom"
+					value={custom}
+					onChange={(event) => setCustom(event.target.value)}
+					placeholder="Or write your own…"
+					className="min-w-0 flex-1 bg-transparent tr-text-ui text-text-default outline-none placeholder:text-text-subtle"
+				/>
+				<Button
+					size="sm"
+					disabled={!custom.trim()}
+					onClick={() => onAnswer(custom.trim())}
+					data-testid="sim-question-send"
+				>
+					Send
+				</Button>
+			</div>
+		</div>
+	);
+}
+
+function WorkbenchSides() {
+	return (
+		<div className="hidden w-[220px] shrink-0 flex-col border-border-default border-l bg-container-sidebar-bg md:flex">
+			<div className="flex h-8 shrink-0 items-center gap-md border-border-default border-b px-md tr-text-eyebrow text-text-muted">
+				<span className="text-text-default">Files</span>
+				<span>Specs</span>
+				<span>Changes</span>
+			</div>
+			<ul className="flex flex-col gap-0.5 overflow-auto p-xs tr-text-ui text-text-muted">
+				<SideRow name="index.html" />
+				<SideRow name="styles.css" />
+				<SideRow name="src/app.js" />
+				<SideRow name="src/storage.js" />
+				<SideRow name="SPEC.md" />
+			</ul>
+		</div>
+	);
+}
+
+function SideRow({ name }: { name: string }) {
+	return (
+		<span className="flex h-6 items-center gap-sm rounded-[var(--radius-sm)] px-sm">
+			<FileText className="size-3.5 shrink-0 text-text-subtle" />
+			<span className="truncate">{name}</span>
+		</span>
+	);
+}
+
+function TerminalStrip() {
+	return (
+		<div className="h-[104px] shrink-0 border-border-default border-t bg-container-terminal-bg">
+			<div className="flex h-7 items-center gap-sm border-border-default border-b px-md tr-text-eyebrow text-text-muted">
+				<SquareTerminal className="size-3.5" />
+				Terminal
+			</div>
+			<pre className="overflow-hidden px-md py-sm text-text-muted tr-code-text leading-relaxed">
+				{"~/to-do-app "}
+				<span className="text-text-subtle">(tag-filtering)</span>
+				{" $ git status\nOn branch tag-filtering\nnothing to commit, working tree clean\n$ "}
+				<span className="animate-pulse motion-reduce:animate-none">▊</span>
+			</pre>
+		</div>
+	);
+}
+
+function FolderPicker({ onPickFolder }: { onPickFolder: () => void }) {
+	return (
+		<div className="flex min-h-0 flex-1 bg-container-content-bg p-lg">
+			<div className="flex min-h-0 flex-1 flex-col overflow-hidden rounded-[var(--radius-lg)] border border-border-inverse bg-container-inverse-bg text-text-on-inverse shadow-[var(--shadow-lg)]">
+				<div className="flex h-10 shrink-0 items-center gap-xs border-border-inverse border-b px-md">
+					<House className="size-4 shrink-0 text-text-on-inverse-muted" />
+					<span className="tr-text-ui text-text-on-inverse">Your computer</span>
+					<ChevronRight className="size-3.5 shrink-0 text-text-on-inverse-muted" />
+					<span className="tr-text-ui text-text-on-inverse-muted">My Documents</span>
+					<ChevronRight className="size-3.5 shrink-0 text-text-on-inverse-muted" />
+					<span className="tr-text-ui text-text-on-inverse-muted">Projects</span>
+				</div>
+				<div className="flex min-h-0 flex-1">
+					<PickerColumn className="w-[200px]" label="Locations">
+						<PickerRow icon={House} name="Your computer" />
+						<PickerRow icon={Folder} name="Desktop" />
+						<PickerRow icon={Folder} name="My Documents" selected />
+						<PickerRow icon={Folder} name="Downloads" />
+					</PickerColumn>
+					<PickerColumn className="w-[220px]">
+						<PickerRow icon={Folder} name="Notes" />
+						<PickerRow icon={Folder} name="Projects" selected chevron />
+					</PickerColumn>
+					<PickerColumn className="min-w-0 flex-1" last>
+						<PickerRow icon={Folder} name="my-app" />
+						<PickerRow icon={Folder} name="notes" />
+						<PickerRow icon={Folder} name="to-do-app" target onSelect={onPickFolder} />
+					</PickerColumn>
 				</div>
 			</div>
 		</div>
@@ -822,22 +989,3 @@ function Intro({ onDone }: { onDone: () => void }) {
 		</div>
 	);
 }
-
-function Completion({ onFinish }: { onFinish: () => void }) {
-	return (
-		<div className="absolute inset-0 z-40 flex items-center justify-center bg-container-workspace-overlay">
-			<div className="w-[360px] rounded-[var(--radius-md)] border border-border-default bg-container-elevated-bg p-lg text-center shadow-[var(--shadow-md)]">
-				<p className="tr-title-card text-text-default">You're ready to build</p>
-				<p className="mt-xs text-text-muted tr-text-metadata leading-snug">
-					You opened a project, created two isolated workspaces, and ran two agents in parallel —
-					that's the ThinkRail loop.
-				</p>
-				<div className="mt-md flex justify-center">
-					<Button size="sm" data-testid="onboarding-finish" onClick={onFinish}>
-						Finish
-					</Button>
-				</div>
-			</div>
-		</div>
-	);
-}
diff --git a/apps/web/src/onboarding/SPEC.md b/apps/web/src/onboarding/SPEC.md
index b3d5b3930..0cad5497e 100644
--- a/apps/web/src/onboarding/SPEC.md
+++ b/apps/web/src/onboarding/SPEC.md
@@ -48,9 +48,11 @@ App" card); both flip one **view flag** (`store.demoOpen`, a top-level, non-pers
   `panels`, no cycle). The dialog runs in an **inert `preview` mode** (optional props on the shared
   component, default off): all its wire reads are skipped, submit is short-circuited to `onPreviewCreate`,
   and the Create button's `↵` key-badge is hidden (Create is text-only) — so the exact real dialog UI is
-  taught while **no** workspace/session/wire work happens. The task is passed through as the dialog's
-  `initialPrompt`. Its coach uses a **viewport-scoped** spotlight (the dialog is a portaled modal): a
-  pulse ring on Create + a tooltip to the dialog's right; every other step uses the card-scoped spotlight.
+  taught while **no** workspace/session/wire work happens. The task is passed as `initialPrompt` and the
+  seam **types it in** character-by-character (instant under reduced motion), keeping Create inactive
+  until done and firing `onPreviewReady` so the sim only shows the Create coach once typing finishes. Its
+  coach uses a **viewport-scoped** spotlight (the dialog is a portaled modal): a pulse ring on Create + a
+  tooltip to the dialog's right; every other step uses the card-scoped spotlight.
 - **Coach marks** reuse the tooltip + arrow treatment: a card-scoped **spotlight** dims everything inside
   the card except the current target with the `container-workspace-overlay` scrim (the workspace surface at
   the `veil` **50%** alpha step — a sanctioned color token, light enough to keep the interface legible;
@@ -78,7 +80,7 @@ App" card); both flip one **view flag** (`store.demoOpen`, a top-level, non-pers
   the card's bottom edge and advances across the scripted `STEP_ORDER`. No labels/percentages/dots.
 - Only the current target is interactive; everything else is present but inert (covered by the dim).
 
-## Scripted flow (local `step` state machine, numbered "of 4")
+## Scripted flow (local `step` state machine)
 
 1. **Open a project** — empty-state Welcome with an "Open project" card (arrow points down to it); clicking
    opens a **fake, simplified macOS-Finder-style folder picker** rendered on a **light / inverse system
@@ -94,23 +96,35 @@ App" card); both flip one **view flag** (`store.demoOpen`, a top-level, non-pers
    The demo card carries a soft **brand glow** — a blurred `bg-primary-soft` layer behind it (not
    `feedback-success`; onboarding emphasis, not a success state), extending slightly beyond the card
    without altering its background, border, or layout.
-2. **Create separate workspaces** — coach sits right of the left panel (arrow at the rail `+`); clicking
-   it opens the **real** `NewWorkspaceDialog` (see the preview seam below) with its prompt **prefilled**
-   (focused, blinking caret — no fake typing) with that workspace's predetermined task, and the coach
-   re-points **to the right of the dialog** with its arrow at the emphasized **Create** button. Doing this
-   twice yields two fake workspaces. No real worktrees are created.
-3. **Start the first agent** — switches into the first workspace's composer with the first task **already
-   prefilled** (no Insert button); the coach highlights the existing **Send** button (pulsing primary
-   ring). Send shows a brief "Working…" then a predetermined successful result (a `setTimeout`, no model
-   call), using the existing chat treatment.
-4. **Run agents in parallel** — coach guides switching to the second workspace, whose composer is
-   **prefilled** with the second task (Send highlighted); the first workspace's row shows it already
-   **done** while the second works —
-   the payoff that separate workspaces hold independent, concurrent sessions. A left-panel note reinforces
-   that switching tabs never stops a session.
+2. **Create the first workspace** — coach at the rail `+` opens the **real** `NewWorkspaceDialog` (preview
+   seam below); the task **types itself** into the real prompt field (focused, blinking caret; instant
+   under reduced motion), Create stays inactive until typing finishes, then the coach re-points to the
+   right of the dialog with its arrow on the emphasized **Create**. Clicking Create enters the first
+   workspace.
+3. **First agent starts, and keeps running** — the first workspace shows concise, believable agent
+   activity (reads files → plan → "Working…") in the real chat visual language and **stays running**; its
+   rail row keeps a working indicator. The coach points back at the rail `+`: "start a second task — your
+   first agent keeps working here."
+4. **Create the second workspace** — same real dialog + typed task for *"Add filtering by tags…"*.
+5. **Second agent + full workbench** — entering the second workspace shows the integrated workbench, all
+   **mocked** with the real visual language: an active agent chat (center), a right-side
+   Files/Specs/Changes strip, and a bottom **Terminal** strip — so it reads as ThinkRail, not a bare chat.
+6. **Agent asks for feedback** — the second agent pauses with a **question widget** ("Where should tag
+   filters appear?" + options + a custom field); a coach points at it ("Give the agent feedback"). The
+   user must choose an option or type their own; on answer the agent acknowledges and resumes.
+7. **Parallel payoff** — while the second agent continues, the coach moves to the **left nav** and
+   highlights the **first** workspace (pulsing primary): "Your agents work in parallel — your first task
+   kept running. Check its progress." The second workspace visibly stays active; a left-panel note states
+   switching views never stops a session.
+8. **Return to the first workspace** — clicking it shows the first agent **completed** (result + a small
+   Changes summary), making the "I left, worked elsewhere, came back done" point.
 
-**Completion** — a "You're ready to build" card with a single **Finish** action (`closeDemo`). Because the
-whole thing is local state, replaying (reopen) starts fresh at step 1.
+**Completion** (`step: "final"`, progress 100%) — a central **primary-subtle** surface: **"That's the
+workflow." / "Now try it with your own project."** with a **Finish** action (`closeDemo`) and a **"Learn
+more in the docs"** link to the existing `https://thinkrail.ai`. Local state, so reopening replays from
+the intro. The agent activity, workbench sides, terminal, and question widget are **faithful mocks** (the
+real chat/panels/terminal/question components are chat-runtime/store-coupled and can't mount in an
+isolated mock); only `NewWorkspaceDialog` is the real component (preview seam).
 
 ## Boundary
 
diff --git a/apps/web/src/panels/NewWorkspaceDialog.tsx b/apps/web/src/panels/NewWorkspaceDialog.tsx
index 6cadff7bf..17e155ede 100644
--- a/apps/web/src/panels/NewWorkspaceDialog.tsx
+++ b/apps/web/src/panels/NewWorkspaceDialog.tsx
@@ -69,6 +69,7 @@ export function NewWorkspaceDialog({
 	onCreated,
 	preview = false,
 	onPreviewCreate,
+	onPreviewReady,
 }: {
 	open: boolean;
 	projectId: string;
@@ -78,6 +79,7 @@ export function NewWorkspaceDialog({
 	onCreated: (workspace: Workspace) => void;
 	preview?: boolean;
 	onPreviewCreate?: () => void;
+	onPreviewReady?: () => void;
 }) {
 	const projects = useAppStore((s) => s.projects);
 
@@ -90,6 +92,9 @@ export function NewWorkspaceDialog({
 	const [model, setModel] = useState<WireModel | null>(null);
 	const [thinkingLevel, setThinkingLevel] = useState<ThinkingLevel>("medium");
 	const [creating, setCreating] = useState(false);
+	const [previewTyped, setPreviewTyped] = useState(false);
+	const previewReadyRef = useRef(onPreviewReady);
+	previewReadyRef.current = onPreviewReady;
 	const [trusting, setTrusting] = useState(false);
 	const [manageSkills, setManageSkills] = useState(false);
 	const promptRef = useRef<HTMLTextAreaElement>(null);
@@ -119,11 +124,39 @@ export function NewWorkspaceDialog({
 	useEffect(() => {
 		if (!open) return;
 		setSelectedProjectId(projectId);
-		setPrompt(initialPrompt ?? "");
+		setPrompt(preview ? "" : (initialPrompt ?? ""));
+		setPreviewTyped(!preview);
 		setTarget("worktree");
 		setCreating(false);
 		hostDefaultAsked.current = false;
-	}, [open, projectId, initialPrompt]);
+	}, [open, projectId, initialPrompt, preview]);
+
+	useEffect(() => {
+		if (!open || !preview) return;
+		const full = initialPrompt ?? "";
+		const reduce =
+			typeof window !== "undefined" &&
+			window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+		if (!full || reduce) {
+			setPrompt(full);
+			setPreviewTyped(true);
+			previewReadyRef.current?.();
+			return;
+		}
+		setPrompt("");
+		setPreviewTyped(false);
+		let index = 0;
+		const id = setInterval(() => {
+			index += 1;
+			setPrompt(full.slice(0, index));
+			if (index >= full.length) {
+				clearInterval(id);
+				setPreviewTyped(true);
+				previewReadyRef.current?.();
+			}
+		}, 26);
+		return () => clearInterval(id);
+	}, [open, preview, initialPrompt]);
 
 	useEffect(() => {
 		if (!open || preview) return;
@@ -493,7 +526,7 @@ export function NewWorkspaceDialog({
 					<button
 						type="button"
 						data-testid="create-workspace"
-						disabled={creating}
+						disabled={creating || (preview && !previewTyped)}
 						onClick={() => void create()}
 						className="flex h-8 shrink-0 items-center gap-sm rounded-[var(--radius-sm)] bg-control-primary-bg px-md tr-text-action text-control-primary-text outline-none transition-colors hover:bg-control-primary-bg-hovered focus-visible:ring-2 focus-visible:ring-primary disabled:bg-control-primary-disabled-bg disabled:text-control-primary-disabled-text"
 					>
diff --git a/apps/web/src/panels/SPEC.md b/apps/web/src/panels/SPEC.md
index 1b203b45a..1838e1e32 100644
--- a/apps/web/src/panels/SPEC.md
+++ b/apps/web/src/panels/SPEC.md
@@ -233,8 +233,9 @@ aliases, model default/clamp, branch list, prefetch, model catalog) and the proj
 skipped, submit is short-circuited to `onPreviewCreate` instead of `workspace.create`/`session.create`, and
 the Create button's `↵` key-badge is hidden (Create renders text-only) — so the real component renders with
 no network calls and creates no domain object. The demo's predetermined task rides in through the normal
-`initialPrompt` (prefilled, focused). Production callers pass none of these and are unaffected; the demo
-injects it via the shell (see [[submodule-web-onboarding]]).
+`initialPrompt` and, in preview, is **typed in** character-by-character (instant under reduced motion) with
+Create disabled until it finishes; `onPreviewReady` fires when typing completes. Production callers pass
+none of these and are unaffected; the demo injects it via the shell (see [[submodule-web-onboarding]]).
 
 **`NewWorkspaceDialog`** is the start-working surface: **a target control** (a two-option segment — a
 native radio group, `fieldset` + sr-only `legend` over visually-hidden radio inputs, so assistive tech
diff --git a/apps/web/src/shell/Shell.tsx b/apps/web/src/shell/Shell.tsx
index a823b7e2b..d21c54f9d 100644
--- a/apps/web/src/shell/Shell.tsx
+++ b/apps/web/src/shell/Shell.tsx
@@ -220,7 +220,7 @@ export function Shell() {
 			)}
 			<Toaster />
 			<OnboardingSimulation
-				renderCreateDialog={({ onCreate, onClose, prompt }) => (
+				renderCreateDialog={({ onCreate, onClose, onReady, prompt }) => (
 					<NewWorkspaceDialog
 						open
 						preview
@@ -231,6 +231,7 @@ export function Shell() {
 						}}
 						onCreated={() => {}}
 						onPreviewCreate={onCreate}
+						onPreviewReady={onReady}
 					/>
 				)}
 			/>
diff --git a/e2e/onboarding-demo.spec.ts b/e2e/onboarding-demo.spec.ts
index 59688b9d5..2c6c0624f 100644
--- a/e2e/onboarding-demo.spec.ts
+++ b/e2e/onboarding-demo.spec.ts
@@ -1,7 +1,10 @@
 import { expect, test } from "@playwright/test";
 import { openAppFresh } from "./fixtures/app";
 
-test("the mocked onboarding simulation runs intro → scripted flow, never touching real projects", async ({
+const TASK_1 = "Implement a search feature in my To Do app.";
+const TASK_2 = "Add filtering by tags so I can quickly show tasks with a specific tag.";
+
+test("the mocked demo runs intro → parallel-agents payoff, never touching real projects", async ({
 	page,
 }) => {
 	await openAppFresh(page);
@@ -10,49 +13,40 @@ test("the mocked onboarding simulation runs intro → scripted flow, never touch
 	await page.getByTestId("onboarding-launch").click();
 	await expect(page.getByTestId("onboarding-sim")).toBeVisible();
 	await expect(page.getByTestId("onboarding-intro")).toContainText("Welcome to ThinkRail");
-	await expect(page.getByTestId("onboarding-progress")).toBeAttached();
-	await expect(page.getByTestId("onboarding-intro")).toContainText("Before we start");
 	await expect(page.getByTestId("onboarding-git")).toContainText("Git is ready");
+	await expect(page.getByTestId("onboarding-progress")).toBeAttached();
 
 	const coach = page.getByTestId("onboarding-coach");
 	await expect(coach).toContainText("Open a project");
-	await expect(coach).not.toContainText("Step");
 	await page.getByTestId("sim-open-project").click();
 
 	await expect(coach).toContainText("Choose your project folder");
 	await page.getByTestId("sim-folder").click();
 
-	const task1 = "Implement a search feature in my To Do app.";
-	const task2 = "Add filtering by tags so I can quickly show tasks with a specific tag.";
-
 	await expect(coach).toContainText("Create a workspace");
 	await page.getByTestId("sim-add-workspace").click();
 	await expect(page.getByTestId("new-workspace-dialog")).toBeVisible();
-	await expect(page.getByTestId("ws-prompt")).toHaveValue(task1);
-	const createButton = page.getByTestId("create-workspace");
-	await expect(createButton).toHaveText("Create");
-	await expect(coach).toContainText("Create the workspace");
-	await createButton.click();
+	await expect(page.getByTestId("ws-prompt")).toHaveValue(TASK_1);
+	await page.getByTestId("create-workspace").click();
 
-	await expect(coach).toContainText("Create a second workspace");
+	await expect(coach).toContainText("Now start a second task");
 	await page.getByTestId("sim-add-workspace").click();
 	await expect(page.getByTestId("new-workspace-dialog")).toBeVisible();
-	await expect(page.getByTestId("ws-prompt")).toHaveValue(task2);
+	await expect(page.getByTestId("ws-prompt")).toHaveValue(TASK_2);
 	await page.getByTestId("create-workspace").click();
 
-	await expect(coach).toContainText("Start the first agent");
-	await expect(page.getByTestId("onboarding-insert-prompt")).toHaveCount(0);
-	await expect(page.getByTestId("sim-composer")).toHaveValue(task1);
-	await page.getByTestId("sim-send").click();
-
-	await expect(coach).toContainText("Switch to your second workspace");
-	await page.getByTestId("sim-ws-1").click();
+	const question = page.getByTestId("onboarding-question");
+	await expect(question).toBeVisible();
+	await expect(coach).toContainText("Give the agent feedback");
+	await page.getByTestId("sim-question-option").first().click();
 
-	await expect(coach).toContainText("Run a second agent in parallel");
-	await expect(page.getByTestId("sim-composer")).toHaveValue(task2);
-	await page.getByTestId("sim-send").click();
+	await expect(coach).toContainText("Your agents work in parallel");
+	await page.getByTestId("sim-ws-0").click();
 
+	await expect(page.getByTestId("onboarding-finish")).toBeVisible();
+	await expect(page.getByTestId("onboarding-docs")).toHaveAttribute("href", "https://thinkrail.ai");
 	await page.getByTestId("onboarding-finish").click();
+
 	await expect(page.getByTestId("onboarding-sim")).toHaveCount(0);
 	await expect(page.getByTestId("project-item")).toHaveCount(0);
 });

From 7040e32340f715bf5b377d268110254f6c3fcc29 Mon Sep 17 00:00:00 2001
From: "Julia.Shilova" <Julia.Shilova@MacBook-Pro-5.local>
Date: Fri, 28 Aug 2026 17:47:04 +0300
Subject: [PATCH 22/23] feat(web): share one intro/outro layout for the demo
 onboarding
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Refine the mocked demo's first and final screens onto a single shared
OnboardingScreen: same full-card overlay, content width, sequential reveal,
vertical rhythm, and a single primary CTA — no separate final card.

Intro: hero on one line, 32px to an 18px (tr-heading-md) subtitle, 64px to
'Before we start', 32px to the kept Git-readiness row. No auto-advance — a
'Start demo project' CTA gates entry and the intro persists until clicked.

Final: drop the primary-subtle success card and the docs link; render the
same layout with 'That's the workflow.' / 'Now try it with your own project.'
and a single 'Start working on your own project' CTA.

Add xxl/xxxl (~32/64px) spacing steps for the layout rhythm — named outside
Tailwind's --container-* scale so they can't shadow max-w-3xl in ChatView.
---
 apps/web/src/index.css                        |   2 +
 .../src/onboarding/OnboardingSimulation.tsx   | 247 ++++++++++++------
 apps/web/src/onboarding/SPEC.md               |  42 ++-
 apps/web/src/styles/tokens.css                |   2 +
 e2e/onboarding-demo.spec.ts                   |  60 ++++-
 5 files changed, 259 insertions(+), 94 deletions(-)

diff --git a/apps/web/src/index.css b/apps/web/src/index.css
index 2e86b57a3..ebc74df67 100644
--- a/apps/web/src/index.css
+++ b/apps/web/src/index.css
@@ -47,6 +47,8 @@
 	--spacing-md: var(--space-md);
 	--spacing-lg: var(--space-lg);
 	--spacing-xl: var(--space-xl);
+	--spacing-xxl: var(--space-xxl);
+	--spacing-xxxl: var(--space-xxxl);
 	--spacing-panel-header-row: var(--panel-header-row-height);
 
 	/* A block appearing in place (e.g. the ask-question card's atomic reveal once its args are final). */
diff --git a/apps/web/src/onboarding/OnboardingSimulation.tsx b/apps/web/src/onboarding/OnboardingSimulation.tsx
index 86c771914..8708a9be2 100644
--- a/apps/web/src/onboarding/OnboardingSimulation.tsx
+++ b/apps/web/src/onboarding/OnboardingSimulation.tsx
@@ -20,8 +20,6 @@ import { cn } from "../lib";
 import { useAppStore } from "../store";
 import { useTargetRect } from "./anchor";
 
-const DOCS_URL = "https://thinkrail.ai";
-
 const TASK_1 = "Implement a search feature in my To Do app.";
 const TASK_2 = "Add filtering by tags so I can quickly show tasks with a specific tag.";
 const WS_NAMES = ["Search feature", "Tag filtering"];
@@ -337,11 +335,11 @@ function Simulation({
 						onOpenProject={() => setStep("picker")}
 						onPickFolder={() => setStep("ws1-create")}
 						onAnswer={onAnswer}
-						onFinish={() => closeDemo()}
 					/>
 				</div>
 
-				{step === "intro" ? <Intro onDone={startTour} /> : null}
+				{step === "intro" ? <IntroScreen onStart={startTour} /> : null}
+				{step === "final" ? <FinalScreen onFinish={() => closeDemo()} /> : null}
 				{coach?.scope === "card" ? (
 					<CardSpotlight
 						cardRect={cardRect}
@@ -471,14 +469,12 @@ function SimMain({
 	onOpenProject,
 	onPickFolder,
 	onAnswer,
-	onFinish,
 }: {
 	step: Step;
 	rows: Activity[];
 	onOpenProject: () => void;
 	onPickFolder: () => void;
 	onAnswer: (choice: string) => void;
-	onFinish: () => void;
 }) {
 	if (step === "open") {
 		return (
@@ -524,30 +520,6 @@ function SimMain({
 			</Center>
 		);
 	}
-	if (step === "final") {
-		return (
-			<div className="flex min-h-0 flex-1 items-center justify-center bg-container-content-bg p-xl">
-				<div className="w-[420px] rounded-[var(--radius-md)] border border-primary-muted bg-clip-padding bg-primary-subtle p-lg text-center">
-					<p className="tr-brand-hero text-primary">That's the workflow.</p>
-					<p className="mt-sm text-text-muted tr-text-ui">Now try it with your own project.</p>
-					<div className="mt-lg flex items-center justify-center gap-md">
-						<Button size="sm" data-testid="onboarding-finish" onClick={onFinish}>
-							Finish
-						</Button>
-						<a
-							href={DOCS_URL}
-							target="_blank"
-							rel="noreferrer"
-							data-testid="onboarding-docs"
-							className="tr-text-ui text-primary underline underline-offset-2 hover:text-text-default"
-						>
-							Learn more in the docs
-						</a>
-					</div>
-				</div>
-			</div>
-		);
-	}
 	return (
 		<div className="flex min-h-0 flex-1 flex-col bg-container-content-bg">
 			<div className="flex min-h-0 flex-1">
@@ -930,62 +902,181 @@ function ViewportCoach({
 	);
 }
 
-function Intro({ onDone }: { onDone: () => void }) {
+type Gap = "md" | "xxl" | "xxxl";
+
+const GAP_CLASS: Record<Gap, string> = {
+	md: "mt-md",
+	xxl: "mt-xxl",
+	xxxl: "mt-xxxl",
+};
+
+type OnboardingSection = {
+	key: string;
+	gapBefore?: Gap;
+	render: () => ReactNode;
+};
+
+function useSequentialReveal(count: number): number {
 	const [phase, setPhase] = useState(0);
-	const [gitReady, setGitReady] = useState(false);
 	useEffect(() => {
-		const timers = [
-			setTimeout(() => setPhase(1), 200),
-			setTimeout(() => setPhase(2), 1000),
-			setTimeout(() => setPhase(3), 1900),
-			setTimeout(() => setGitReady(true), 3200),
-			setTimeout(() => setPhase(4), 3900),
-			setTimeout(onDone, 5200),
-		];
+		const timers: ReturnType<typeof setTimeout>[] = [];
+		for (let index = 1; index <= count; index++) {
+			timers.push(setTimeout(() => setPhase(index), 200 + (index - 1) * 700));
+		}
 		return () => timers.forEach(clearTimeout);
-	}, [onDone]);
-	const reveal = (index: number) =>
-		`transition-all duration-500 ease-out motion-reduce:transition-none ${
-			phase >= index ? "translate-y-0 opacity-100" : "translate-y-2 opacity-0"
-		}`;
+	}, [count]);
+	return phase;
+}
+
+function revealClass(shown: boolean): string {
+	return cn(
+		"transition-all duration-500 ease-out motion-reduce:transition-none",
+		shown ? "translate-y-0 opacity-100" : "translate-y-2 opacity-0",
+	);
+}
+
+function OnboardingScreen({
+	testId,
+	sections,
+	cta,
+}: {
+	testId: string;
+	sections: OnboardingSection[];
+	cta: { label: string; testId: string; onClick: () => void };
+}) {
+	const steps = sections.length + 1;
+	const phase = useSequentialReveal(steps);
+	const ctaRevealed = phase >= steps;
 	return (
 		<div
-			data-testid="onboarding-intro"
-			className="absolute inset-0 z-30 flex flex-col items-center justify-center gap-md bg-container-workspace-bg p-xl text-center"
+			data-testid={testId}
+			className="absolute inset-0 z-30 flex flex-col items-center justify-center bg-container-workspace-bg p-xl text-center"
 		>
-			<h1 className={`tr-brand-hero text-primary ${reveal(1)}`}>Welcome to ThinkRail</h1>
-			<p className={`max-w-[520px] tr-text-ui text-text-default ${reveal(2)}`}>
-				ThinkRail is a worktree IDE built for working with AI agents in parallel.
-			</p>
-			<div className={`flex flex-col items-center gap-sm ${reveal(3)}`}>
-				<p className="tr-title-card text-text-default">Before we start</p>
-				<p className="max-w-[460px] text-text-muted tr-text-metadata">
-					ThinkRail works with Git projects. Let's make sure your computer is ready.
-				</p>
-				<div
-					data-testid="onboarding-git"
-					className="mt-xs inline-flex items-center gap-sm rounded-[var(--radius-sm)] border border-border-default bg-container-elevated-bg px-md py-sm"
-				>
-					<GitBranch className="size-4 shrink-0 text-text-muted" />
-					<span className="tr-text-ui text-text-default">Git</span>
-					{gitReady ? (
-						<span className="inline-flex items-center gap-xs tr-text-metadata text-feedback-success">
-							<Check className="size-3.5" />
-							Git is ready
-						</span>
-					) : (
-						<span className="inline-flex items-center gap-xs text-text-muted tr-text-metadata">
-							<Loader2 className="size-3.5 motion-safe:animate-spin" />
-							Checking Git…
-						</span>
-					)}
+			<div className="flex w-full max-w-[720px] flex-col items-center">
+				{sections.map((section, index) => {
+					const revealed = phase >= index + 1;
+					return (
+						<div
+							key={section.key}
+							data-revealed={revealed ? "true" : "false"}
+							className={cn(
+								section.gapBefore && GAP_CLASS[section.gapBefore],
+								revealClass(revealed),
+							)}
+						>
+							{section.render()}
+						</div>
+					);
+				})}
+				<div className={cn("mt-xxxl", revealClass(ctaRevealed))}>
+					<Button
+						data-testid={cta.testId}
+						data-revealed={ctaRevealed ? "true" : "false"}
+						onClick={cta.onClick}
+					>
+						{cta.label}
+					</Button>
 				</div>
 			</div>
-			<p
-				className={`max-w-[520px] whitespace-pre-line text-text-muted tr-text-metadata ${reveal(4)}`}
-			>
-				{"Let's set up a demo project first.\nIt takes about 2 minutes."}
-			</p>
 		</div>
 	);
 }
+
+function GitReadinessRow() {
+	const [ready, setReady] = useState(false);
+	useEffect(() => {
+		const timer = setTimeout(() => setReady(true), 3500);
+		return () => clearTimeout(timer);
+	}, []);
+	return (
+		<div
+			data-testid="onboarding-git"
+			className="inline-flex items-center gap-sm rounded-[var(--radius-sm)] border border-border-default bg-container-elevated-bg px-md py-sm"
+		>
+			<GitBranch className="size-4 shrink-0 text-text-muted" />
+			<span className="tr-text-ui text-text-default">Git</span>
+			{ready ? (
+				<span className="inline-flex items-center gap-xs tr-text-metadata text-feedback-success">
+					<Check className="size-3.5" />
+					Git is ready
+				</span>
+			) : (
+				<span className="inline-flex items-center gap-xs text-text-muted tr-text-metadata">
+					<Loader2 className="size-3.5 motion-safe:animate-spin" />
+					Checking Git…
+				</span>
+			)}
+		</div>
+	);
+}
+
+function IntroScreen({ onStart }: { onStart: () => void }) {
+	const sections: OnboardingSection[] = [
+		{
+			key: "title",
+			render: () => <h1 className="tr-brand-hero text-primary">Welcome to {PRODUCT_NAME}</h1>,
+		},
+		{
+			key: "lede",
+			gapBefore: "xxl",
+			render: () => (
+				<p className="max-w-[560px] tr-heading-md text-text-default">
+					{PRODUCT_NAME} is a worktree IDE built for working with AI agents in parallel.
+				</p>
+			),
+		},
+		{
+			key: "before",
+			gapBefore: "xxxl",
+			render: () => <p className="tr-heading-sm text-text-default">Before we start</p>,
+		},
+		{
+			key: "git",
+			gapBefore: "xxl",
+			render: () => (
+				<div className="flex flex-col items-center gap-md">
+					<p className="max-w-[520px] tr-text-ui text-text-muted">
+						{PRODUCT_NAME} works with Git projects. Let's make sure your computer is ready.
+					</p>
+					<GitReadinessRow />
+				</div>
+			),
+		},
+	];
+	return (
+		<OnboardingScreen
+			testId="onboarding-intro"
+			sections={sections}
+			cta={{ label: "Start demo project", testId: "onboarding-start", onClick: onStart }}
+		/>
+	);
+}
+
+function FinalScreen({ onFinish }: { onFinish: () => void }) {
+	const sections: OnboardingSection[] = [
+		{
+			key: "title",
+			render: () => <p className="tr-brand-hero text-primary">That's the workflow.</p>,
+		},
+		{
+			key: "lede",
+			gapBefore: "xxl",
+			render: () => (
+				<p className="max-w-[560px] tr-heading-md text-text-default">
+					Now try it with your own project.
+				</p>
+			),
+		},
+	];
+	return (
+		<OnboardingScreen
+			testId="onboarding-final"
+			sections={sections}
+			cta={{
+				label: "Start working on your own project",
+				testId: "onboarding-finish",
+				onClick: onFinish,
+			}}
+		/>
+	);
+}
diff --git a/apps/web/src/onboarding/SPEC.md b/apps/web/src/onboarding/SPEC.md
index 0cad5497e..fe03a38e8 100644
--- a/apps/web/src/onboarding/SPEC.md
+++ b/apps/web/src/onboarding/SPEC.md
@@ -26,15 +26,30 @@ App" card); both flip one **view flag** (`store.demoOpen`, a top-level, non-pers
 - A centered modal (~`90vw × 90vh`) over a `bg-overlay` scrim; the card is an opaque `container-workspace-bg`
   sandbox rendering a simplified but faithful ThinkRail chrome (header / left `Projects` panel / center),
   built from the existing semantic tokens and `components/ui` — **not** wired to any store domain state.
-- **Animated intro** (`step: "intro"`, first): lines reveal in sequence with restrained fade/translate
-  transitions (`motion-reduce:transition-none`) — "Welcome to ThinkRail" (`tr-brand-hero`), the one-line
-  product explanation (`tr-text-ui`), then a short **environment-readiness moment** ("Before we start" /
-  "ThinkRail works with Git projects…") with **one compact, fully mocked Git row** that animates
-  `Checking Git…` (spinner) → `Git is ready` (the semantic **success** role + check) — no clicks, always
-  ends ready, no terminal/install/Git-config detail; it exists to reveal the Git prerequisite before a
-  real project could error. Then the ~2-minute setup note (`tr-text-metadata`) and auto-advance into the
-  first interactive action. **Nothing here detects/invokes Git** or touches any real state; it is not a
-  numbered onboarding step, and no coach mark shows during the intro. (The missing-Git install flow is
+- **Shared intro/outro layout (`OnboardingScreen`).** The first (`step: "intro"`) and final
+  (`step: "final"`) screens render through **one** private `OnboardingScreen` component — same full-card
+  overlay (`absolute inset-0`, `bg-container-workspace-bg`, centered, `text-center`), same content column
+  (`max-w-[720px]`, hero heading unconstrained so it sits on one line and wraps only when the viewport is
+  genuinely narrow — the future mobile single-view), same sequential fade/translate reveal
+  (`useSequentialReveal`, `motion-reduce:transition-none`; each section + the CTA carry
+  `data-revealed`), and a **single primary `Button` CTA** revealed last as the only action in the content
+  area. Vertical rhythm is layout-owned via per-section `gapBefore` mapped to the spacing scale — the
+  requested 32px / 64px use the `xxl` / `xxxl` scale steps (`mt-xxl` / `mt-xxxl`) — named outside
+  Tailwind's `--container-*` t-shirt scale on purpose: `2xl`/`3xl` there would make Tailwind v4 emit a
+  spacing-derived `max-w-3xl` that silently shadows the container one `ChatView` relies on
+  (`mx-auto max-w-3xl`), collapsing the chat column. Typography is mapped to
+  existing semantic roles only (`tr-brand-hero` hero, `tr-heading-md` subtitle, `tr-heading-sm` section
+  heading, `tr-text-ui`/`tr-text-metadata` support) — no component-specific type — and colour uses the
+  existing Primary/text/container/border semantics only (no card, no success-green surface).
+- **Intro** (`onboarding-intro`, first): reveals in sequence — "Welcome to ThinkRail" (`tr-brand-hero`),
+  32px, the product subtitle (`tr-heading-md`), 64px, a **"Before we start"** heading (`tr-heading-sm`),
+  32px, the Git prerequisite explanation (`tr-text-ui`) with **one compact, fully mocked Git row**
+  (`onboarding-git`) that animates `Checking Git…` (spinner) → `Git is ready` (the semantic **success**
+  role + check) — no clicks, always ends ready, no terminal/install/Git-config detail; it reveals the Git
+  prerequisite before a real project could error. The intro **does not auto-advance**: it stays visible
+  indefinitely until the user clicks the **"Start demo project"** CTA (`onboarding-start`), which enters
+  the first interactive action. **Nothing here detects/invokes Git** or touches any real state; it is not
+  a numbered onboarding step, and no coach mark shows during the intro. (The missing-Git install flow is
   deliberately out of scope — a future state once Git is bundled vs. externally installed is decided.)
 - **Close demo** (`onboarding-close`, a quiet `Button variant="ghost"` in the card's top-right) is present
   throughout — intro included — and is the only explicit pre-completion exit. It only clears the mocked
@@ -119,10 +134,11 @@ App" card); both flip one **view flag** (`store.demoOpen`, a top-level, non-pers
 8. **Return to the first workspace** — clicking it shows the first agent **completed** (result + a small
    Changes summary), making the "I left, worked elsewhere, came back done" point.
 
-**Completion** (`step: "final"`, progress 100%) — a central **primary-subtle** surface: **"That's the
-workflow." / "Now try it with your own project."** with a **Finish** action (`closeDemo`) and a **"Learn
-more in the docs"** link to the existing `https://thinkrail.ai`. Local state, so reopening replays from
-the intro. The agent activity, workbench sides, terminal, and question widget are **faithful mocks** (the
+**Completion** (`step: "final"`, progress 100%) — the **same `OnboardingScreen` layout** as the intro
+(no card, no success-green treatment): **"That's the workflow."** (`tr-brand-hero`), 32px, **"Now try it
+with your own project."** (`tr-heading-md`), revealed sequentially, then a single **"Start working on your
+own project"** CTA (`onboarding-finish`, `closeDemo`) as the only action in the content area — no docs
+link. The global **Close demo** control stays. Local state, so reopening replays from the intro. The agent activity, workbench sides, terminal, and question widget are **faithful mocks** (the
 real chat/panels/terminal/question components are chat-runtime/store-coupled and can't mount in an
 isolated mock); only `NewWorkspaceDialog` is the real component (preview seam).
 
diff --git a/apps/web/src/styles/tokens.css b/apps/web/src/styles/tokens.css
index 46878a39a..92218ef2c 100644
--- a/apps/web/src/styles/tokens.css
+++ b/apps/web/src/styles/tokens.css
@@ -35,6 +35,8 @@
 	--space-md: calc(var(--space-base) * 0.92);
 	--space-lg: calc(var(--space-base) * 1.23);
 	--space-xl: calc(var(--space-base) * 1.85);
+	--space-xxl: calc(var(--space-base) * 2.46);
+	--space-xxxl: calc(var(--space-base) * 4.92);
 
 	/* Shared chrome geometry stays independent from typography. */
 	--panel-header-row-height: 28px;
diff --git a/e2e/onboarding-demo.spec.ts b/e2e/onboarding-demo.spec.ts
index 2c6c0624f..39151d0c7 100644
--- a/e2e/onboarding-demo.spec.ts
+++ b/e2e/onboarding-demo.spec.ts
@@ -17,6 +17,12 @@ test("the mocked demo runs intro → parallel-agents payoff, never touching real
 	await expect(page.getByTestId("onboarding-progress")).toBeAttached();
 
 	const coach = page.getByTestId("onboarding-coach");
+
+	await expect(page.getByTestId("onboarding-start")).toHaveAttribute("data-revealed", "true");
+	await expect(coach).toHaveCount(0);
+
+	await page.getByTestId("onboarding-start").click();
+
 	await expect(coach).toContainText("Open a project");
 	await page.getByTestId("sim-open-project").click();
 
@@ -43,14 +49,62 @@ test("the mocked demo runs intro → parallel-agents payoff, never touching real
 	await expect(coach).toContainText("Your agents work in parallel");
 	await page.getByTestId("sim-ws-0").click();
 
-	await expect(page.getByTestId("onboarding-finish")).toBeVisible();
-	await expect(page.getByTestId("onboarding-docs")).toHaveAttribute("href", "https://thinkrail.ai");
-	await page.getByTestId("onboarding-finish").click();
+	await expect(page.getByTestId("onboarding-final")).toBeVisible();
+	await expect(page.getByTestId("onboarding-final")).toContainText("That's the workflow.");
+	await expect(page.getByTestId("onboarding-final")).toContainText(
+		"Now try it with your own project.",
+	);
+	await expect(page.getByTestId("onboarding-docs")).toHaveCount(0);
+	const finish = page.getByTestId("onboarding-finish");
+	await expect(finish).toHaveText("Start working on your own project");
+	await finish.click();
 
 	await expect(page.getByTestId("onboarding-sim")).toHaveCount(0);
 	await expect(page.getByTestId("project-item")).toHaveCount(0);
 });
 
+test("the intro reveals sequentially and only the CTA starts the demo", async ({ page }) => {
+	await openAppFresh(page);
+	await page.getByTestId("onboarding-launch").click();
+
+	const intro = page.getByTestId("onboarding-intro");
+	await expect(intro).toBeVisible();
+	await expect(intro).toContainText("Before we start");
+
+	const start = page.getByTestId("onboarding-start");
+	await expect(start).toHaveAttribute("data-revealed", "false");
+	await expect(start).toHaveAttribute("data-revealed", "true");
+
+	await expect(page.getByTestId("onboarding-coach")).toHaveCount(0);
+	await page.getByTestId("onboarding-start").click();
+	await expect(intro).toHaveCount(0);
+	await expect(page.getByTestId("onboarding-coach")).toContainText("Open a project");
+});
+
+test("the final screen shares the intro layout and reveals sequentially", async ({ page }) => {
+	await openAppFresh(page);
+	await page.getByTestId("onboarding-launch").click();
+	await page.getByTestId("onboarding-start").click();
+
+	// Drive to the final screen.
+	await page.getByTestId("sim-open-project").click();
+	await page.getByTestId("sim-folder").click();
+	await page.getByTestId("sim-add-workspace").click();
+	await page.getByTestId("create-workspace").click();
+	await page.getByTestId("sim-add-workspace").click();
+	await page.getByTestId("create-workspace").click();
+	await page.getByTestId("sim-question-option").first().click();
+	await page.getByTestId("sim-ws-0").click();
+
+	await expect(page.getByTestId("onboarding-final")).toBeVisible();
+	await expect(page.getByTestId("onboarding-progress")).toBeAttached();
+	await expect(page.getByTestId("onboarding-close")).toBeVisible();
+
+	const finish = page.getByTestId("onboarding-finish");
+	await expect(finish).toHaveAttribute("data-revealed", "false");
+	await expect(finish).toHaveAttribute("data-revealed", "true");
+});
+
 test("Close demo leaves the demo at any time without touching real state", async ({ page }) => {
 	await openAppFresh(page);
 	await page.getByTestId("onboarding-launch").click();

From c0d2e11433170ae96da086579d87103f224d66ca Mon Sep 17 00:00:00 2001
From: "Julia.Shilova" <Julia.Shilova@MacBook-Pro-5.local>
Date: Mon, 31 Aug 2026 14:30:29 +0300
Subject: [PATCH 23/23] feat(web): simplify demo intro layout and Git readiness
 into one action row
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Drop the 'Before we start' section heading and merge the Git readiness check
with the demo-start action into a single coherent block on the shared
onboarding intro layout.

- Subtitle frame capped at max-w-[400px]; 48px before the Git prerequisite
  copy, which now reads as two deliberate lines (each its own block, so the
  second never wraps up onto the first) and 16px before the actions.
- Actions are one horizontal row (Git status control + CTA, same h-8 height,
  flex-wrap for the mobile single-view).
- Git readiness is one status control: 'Git:' + spinner while checking →
  'Git: is Ready' (success role) when ready — no redundant labels.
- 'Start demo project' stays explicit and is disabled (existing disabled
  semantics) until the mocked readiness confirms, then enables; no auto-start.

Add a 48px spacing step: xxl/xxxl/xxxxl now map to 32/48/64px (names kept
outside Tailwind's --container-* scale to avoid shadowing max-w-*).
---
 apps/web/src/index.css                        |  1 +
 .../src/onboarding/OnboardingSimulation.tsx   | 90 ++++++++++---------
 apps/web/src/onboarding/SPEC.md               | 38 ++++----
 apps/web/src/styles/tokens.css                |  3 +-
 e2e/onboarding-demo.spec.ts                   | 30 +++++--
 5 files changed, 98 insertions(+), 64 deletions(-)

diff --git a/apps/web/src/index.css b/apps/web/src/index.css
index ebc74df67..151659113 100644
--- a/apps/web/src/index.css
+++ b/apps/web/src/index.css
@@ -49,6 +49,7 @@
 	--spacing-xl: var(--space-xl);
 	--spacing-xxl: var(--space-xxl);
 	--spacing-xxxl: var(--space-xxxl);
+	--spacing-xxxxl: var(--space-xxxxl);
 	--spacing-panel-header-row: var(--panel-header-row-height);
 
 	/* A block appearing in place (e.g. the ask-question card's atomic reveal once its args are final). */
diff --git a/apps/web/src/onboarding/OnboardingSimulation.tsx b/apps/web/src/onboarding/OnboardingSimulation.tsx
index 8708a9be2..f13744274 100644
--- a/apps/web/src/onboarding/OnboardingSimulation.tsx
+++ b/apps/web/src/onboarding/OnboardingSimulation.tsx
@@ -902,12 +902,13 @@ function ViewportCoach({
 	);
 }
 
-type Gap = "md" | "xxl" | "xxxl";
+type Gap = "lg" | "xxl" | "xxxl" | "xxxxl";
 
 const GAP_CLASS: Record<Gap, string> = {
-	md: "mt-md",
+	lg: "mt-lg",
 	xxl: "mt-xxl",
 	xxxl: "mt-xxxl",
+	xxxxl: "mt-xxxxl",
 };
 
 type OnboardingSection = {
@@ -942,7 +943,14 @@ function OnboardingScreen({
 }: {
 	testId: string;
 	sections: OnboardingSection[];
-	cta: { label: string; testId: string; onClick: () => void };
+	cta: {
+		label: string;
+		testId: string;
+		onClick: () => void;
+		gapBefore: Gap;
+		disabled?: boolean;
+		leading?: ReactNode;
+	};
 }) {
 	const steps = sections.length + 1;
 	const phase = useSequentialReveal(steps);
@@ -968,49 +976,50 @@ function OnboardingScreen({
 						</div>
 					);
 				})}
-				<div className={cn("mt-xxxl", revealClass(ctaRevealed))}>
-					<Button
-						data-testid={cta.testId}
-						data-revealed={ctaRevealed ? "true" : "false"}
-						onClick={cta.onClick}
-					>
-						{cta.label}
-					</Button>
+				<div className={cn(GAP_CLASS[cta.gapBefore], revealClass(ctaRevealed))}>
+					<div className="flex flex-wrap items-center justify-center gap-sm">
+						{cta.leading}
+						<Button
+							data-testid={cta.testId}
+							data-revealed={ctaRevealed ? "true" : "false"}
+							disabled={cta.disabled}
+							onClick={cta.onClick}
+						>
+							{cta.label}
+						</Button>
+					</div>
 				</div>
 			</div>
 		</div>
 	);
 }
 
-function GitReadinessRow() {
-	const [ready, setReady] = useState(false);
-	useEffect(() => {
-		const timer = setTimeout(() => setReady(true), 3500);
-		return () => clearTimeout(timer);
-	}, []);
+function GitStatus({ ready }: { ready: boolean }) {
 	return (
 		<div
 			data-testid="onboarding-git"
-			className="inline-flex items-center gap-sm rounded-[var(--radius-sm)] border border-border-default bg-container-elevated-bg px-md py-sm"
+			data-ready={ready ? "true" : "false"}
+			className="inline-flex h-8 items-center gap-sm rounded-[var(--radius-sm)] border border-border-default bg-container-elevated-bg px-md tr-text-ui"
 		>
-			<GitBranch className="size-4 shrink-0 text-text-muted" />
-			<span className="tr-text-ui text-text-default">Git</span>
+			<span className="text-text-default">Git:</span>
 			{ready ? (
-				<span className="inline-flex items-center gap-xs tr-text-metadata text-feedback-success">
+				<span className="inline-flex items-center gap-xs text-feedback-success">
 					<Check className="size-3.5" />
-					Git is ready
+					is Ready
 				</span>
 			) : (
-				<span className="inline-flex items-center gap-xs text-text-muted tr-text-metadata">
-					<Loader2 className="size-3.5 motion-safe:animate-spin" />
-					Checking Git…
-				</span>
+				<Loader2 className="size-3.5 shrink-0 text-text-muted motion-safe:animate-spin" />
 			)}
 		</div>
 	);
 }
 
 function IntroScreen({ onStart }: { onStart: () => void }) {
+	const [gitReady, setGitReady] = useState(false);
+	useEffect(() => {
+		const timer = setTimeout(() => setGitReady(true), 3500);
+		return () => clearTimeout(timer);
+	}, []);
 	const sections: OnboardingSection[] = [
 		{
 			key: "title",
@@ -1020,26 +1029,19 @@ function IntroScreen({ onStart }: { onStart: () => void }) {
 			key: "lede",
 			gapBefore: "xxl",
 			render: () => (
-				<p className="max-w-[560px] tr-heading-md text-text-default">
+				<p className="max-w-[400px] tr-heading-md text-text-default">
 					{PRODUCT_NAME} is a worktree IDE built for working with AI agents in parallel.
 				</p>
 			),
 		},
 		{
-			key: "before",
+			key: "git-copy",
 			gapBefore: "xxxl",
-			render: () => <p className="tr-heading-sm text-text-default">Before we start</p>,
-		},
-		{
-			key: "git",
-			gapBefore: "xxl",
 			render: () => (
-				<div className="flex flex-col items-center gap-md">
-					<p className="max-w-[520px] tr-text-ui text-text-muted">
-						{PRODUCT_NAME} works with Git projects. Let's make sure your computer is ready.
-					</p>
-					<GitReadinessRow />
-				</div>
+				<p className="tr-text-ui text-text-muted">
+					<span className="block">{PRODUCT_NAME} works with Git projects</span>
+					<span className="block">Let's make sure your computer is ready.</span>
+				</p>
 			),
 		},
 	];
@@ -1047,7 +1049,14 @@ function IntroScreen({ onStart }: { onStart: () => void }) {
 		<OnboardingScreen
 			testId="onboarding-intro"
 			sections={sections}
-			cta={{ label: "Start demo project", testId: "onboarding-start", onClick: onStart }}
+			cta={{
+				label: "Start demo project",
+				testId: "onboarding-start",
+				onClick: onStart,
+				gapBefore: "lg",
+				disabled: !gitReady,
+				leading: <GitStatus ready={gitReady} />,
+			}}
 		/>
 	);
 }
@@ -1076,6 +1085,7 @@ function FinalScreen({ onFinish }: { onFinish: () => void }) {
 				label: "Start working on your own project",
 				testId: "onboarding-finish",
 				onClick: onFinish,
+				gapBefore: "xxxxl",
 			}}
 		/>
 	);
diff --git a/apps/web/src/onboarding/SPEC.md b/apps/web/src/onboarding/SPEC.md
index fe03a38e8..badef4cfd 100644
--- a/apps/web/src/onboarding/SPEC.md
+++ b/apps/web/src/onboarding/SPEC.md
@@ -33,24 +33,32 @@ App" card); both flip one **view flag** (`store.demoOpen`, a top-level, non-pers
   genuinely narrow — the future mobile single-view), same sequential fade/translate reveal
   (`useSequentialReveal`, `motion-reduce:transition-none`; each section + the CTA carry
   `data-revealed`), and a **single primary `Button` CTA** revealed last as the only action in the content
-  area. Vertical rhythm is layout-owned via per-section `gapBefore` mapped to the spacing scale — the
-  requested 32px / 64px use the `xxl` / `xxxl` scale steps (`mt-xxl` / `mt-xxxl`) — named outside
-  Tailwind's `--container-*` t-shirt scale on purpose: `2xl`/`3xl` there would make Tailwind v4 emit a
+  area. The **CTA area is one horizontal action row** (`flex flex-wrap`) so a screen may seat a
+  **leading control** left of the CTA (the intro's Git status) at the same `h-8` height; it wraps/stacks
+  on genuinely narrow viewports. Vertical rhythm is layout-owned via per-section `gapBefore` (and a
+  per-CTA `gapBefore`) mapped to the spacing scale — 16/32/48/64px use `lg`/`xxl`/`xxxl`/`xxxxl`
+  (`mt-lg`/`mt-xxl`/`mt-xxxl`/`mt-xxxxl`). The large steps are named **outside** Tailwind's
+  `--container-*` t-shirt scale on purpose: `2xl`/`3xl` there would make Tailwind v4 emit a
   spacing-derived `max-w-3xl` that silently shadows the container one `ChatView` relies on
   (`mx-auto max-w-3xl`), collapsing the chat column. Typography is mapped to
-  existing semantic roles only (`tr-brand-hero` hero, `tr-heading-md` subtitle, `tr-heading-sm` section
-  heading, `tr-text-ui`/`tr-text-metadata` support) — no component-specific type — and colour uses the
-  existing Primary/text/container/border semantics only (no card, no success-green surface).
+  existing semantic roles only (`tr-brand-hero` hero, `tr-heading-md` subtitle,
+  `tr-text-ui`/`tr-text-metadata` support) — no component-specific type — and colour uses the
+  existing Primary/text/container/border/disabled semantics only (no card, no success-green surface).
 - **Intro** (`onboarding-intro`, first): reveals in sequence — "Welcome to ThinkRail" (`tr-brand-hero`),
-  32px, the product subtitle (`tr-heading-md`), 64px, a **"Before we start"** heading (`tr-heading-sm`),
-  32px, the Git prerequisite explanation (`tr-text-ui`) with **one compact, fully mocked Git row**
-  (`onboarding-git`) that animates `Checking Git…` (spinner) → `Git is ready` (the semantic **success**
-  role + check) — no clicks, always ends ready, no terminal/install/Git-config detail; it reveals the Git
-  prerequisite before a real project could error. The intro **does not auto-advance**: it stays visible
-  indefinitely until the user clicks the **"Start demo project"** CTA (`onboarding-start`), which enters
-  the first interactive action. **Nothing here detects/invokes Git** or touches any real state; it is not
-  a numbered onboarding step, and no coach mark shows during the intro. (The missing-Git install flow is
-  deliberately out of scope — a future state once Git is bundled vs. externally installed is decided.)
+  32px, the product subtitle (`tr-heading-md`, `max-w-[400px]`), 48px, a two-line Git prerequisite
+  copy (`tr-text-ui`, each sentence its own `block` so the second never wraps up onto the first, yet each
+  still wraps within a narrow viewport), 16px, then the **action row**: a **single Git status control**
+  (`onboarding-git`) beside the **"Start demo project"** CTA (`onboarding-start`). There is no
+  "Before we start" heading. The Git status is one control whose content evolves — `Git:` + the existing
+  `Loader2` spinner while checking → `Git: is Ready` (`Check` + the semantic **success** role) when
+  ready (`data-ready`); it is a fully mocked status (a `setTimeout`, no clicks, always ends ready, no
+  terminal/install detail) that reveals the Git prerequisite before a real project could error. The CTA
+  is **disabled** (existing disabled control semantics) until the mocked readiness confirms, then
+  enables. The intro **does not auto-advance**: it stays visible indefinitely until the user clicks the
+  enabled CTA, which enters the first interactive action. **Nothing here detects/invokes Git** or touches
+  any real state; it is not a numbered onboarding step, and no coach mark shows during the intro. (The
+  missing-Git install flow is deliberately out of scope — a future state once Git is bundled vs.
+  externally installed is decided.)
 - **Close demo** (`onboarding-close`, a quiet `Button variant="ghost"` in the card's top-right) is present
   throughout — intro included — and is the only explicit pre-completion exit. It only clears the mocked
   experience (`closeDemo`); it touches no real state. Coach marks themselves stay non-dismissible.
diff --git a/apps/web/src/styles/tokens.css b/apps/web/src/styles/tokens.css
index 92218ef2c..db574403c 100644
--- a/apps/web/src/styles/tokens.css
+++ b/apps/web/src/styles/tokens.css
@@ -36,7 +36,8 @@
 	--space-lg: calc(var(--space-base) * 1.23);
 	--space-xl: calc(var(--space-base) * 1.85);
 	--space-xxl: calc(var(--space-base) * 2.46);
-	--space-xxxl: calc(var(--space-base) * 4.92);
+	--space-xxxl: calc(var(--space-base) * 3.69);
+	--space-xxxxl: calc(var(--space-base) * 4.92);
 
 	/* Shared chrome geometry stays independent from typography. */
 	--panel-header-row-height: 28px;
diff --git a/e2e/onboarding-demo.spec.ts b/e2e/onboarding-demo.spec.ts
index 39151d0c7..05af1586f 100644
--- a/e2e/onboarding-demo.spec.ts
+++ b/e2e/onboarding-demo.spec.ts
@@ -13,15 +13,19 @@ test("the mocked demo runs intro → parallel-agents payoff, never touching real
 	await page.getByTestId("onboarding-launch").click();
 	await expect(page.getByTestId("onboarding-sim")).toBeVisible();
 	await expect(page.getByTestId("onboarding-intro")).toContainText("Welcome to ThinkRail");
-	await expect(page.getByTestId("onboarding-git")).toContainText("Git is ready");
+	await expect(page.getByTestId("onboarding-intro")).toContainText(
+		"ThinkRail works with Git projects",
+	);
 	await expect(page.getByTestId("onboarding-progress")).toBeAttached();
 
 	const coach = page.getByTestId("onboarding-coach");
+	const start = page.getByTestId("onboarding-start");
 
-	await expect(page.getByTestId("onboarding-start")).toHaveAttribute("data-revealed", "true");
+	await expect(start).toBeDisabled();
+	await expect(page.getByTestId("onboarding-git")).toContainText("is Ready");
+	await expect(start).toBeEnabled();
 	await expect(coach).toHaveCount(0);
-
-	await page.getByTestId("onboarding-start").click();
+	await start.click();
 
 	await expect(coach).toContainText("Open a project");
 	await page.getByTestId("sim-open-project").click();
@@ -63,20 +67,31 @@ test("the mocked demo runs intro → parallel-agents payoff, never touching real
 	await expect(page.getByTestId("project-item")).toHaveCount(0);
 });
 
-test("the intro reveals sequentially and only the CTA starts the demo", async ({ page }) => {
+test("the intro reveals sequentially, gates the CTA on Git readiness, and needs an explicit click", async ({
+	page,
+}) => {
 	await openAppFresh(page);
 	await page.getByTestId("onboarding-launch").click();
 
 	const intro = page.getByTestId("onboarding-intro");
 	await expect(intro).toBeVisible();
-	await expect(intro).toContainText("Before we start");
+	await expect(intro).not.toContainText("Before we start");
+	await expect(intro).toContainText("ThinkRail works with Git projects");
+	await expect(intro).toContainText("Let's make sure your computer is ready.");
 
 	const start = page.getByTestId("onboarding-start");
 	await expect(start).toHaveAttribute("data-revealed", "false");
 	await expect(start).toHaveAttribute("data-revealed", "true");
 
+	const git = page.getByTestId("onboarding-git");
+	await expect(git).toHaveAttribute("data-ready", "false");
+	await expect(start).toBeDisabled();
+	await expect(git).toHaveAttribute("data-ready", "true");
+	await expect(git).toContainText("is Ready");
+	await expect(start).toBeEnabled();
+
 	await expect(page.getByTestId("onboarding-coach")).toHaveCount(0);
-	await page.getByTestId("onboarding-start").click();
+	await start.click();
 	await expect(intro).toHaveCount(0);
 	await expect(page.getByTestId("onboarding-coach")).toContainText("Open a project");
 });
@@ -86,7 +101,6 @@ test("the final screen shares the intro layout and reveals sequentially", async
 	await page.getByTestId("onboarding-launch").click();
 	await page.getByTestId("onboarding-start").click();
 
-	// Drive to the final screen.
 	await page.getByTestId("sim-open-project").click();
 	await page.getByTestId("sim-folder").click();
 	await page.getByTestId("sim-add-workspace").click();