[backnotprop]

Builds the owner-approved Inbox onboarding tour (approval inbox-onboarding-tour, 2026-10-24; record, prototype and BRIEF in .product/approved/inbox-onboarding-tour/, not in this repo). All seven §7 choices are built as recommended.

What it is

The idea: "To show you how the Inbox works, here is how we used it to build the Inbox."

The tour replays the real thread Guided Reviews in VS Code: spec and prototype. It uses the window's own InboxList, MessageBody (the real question card with #2144's picture tiles) and Sidebar, fed from a fixture instead of the person's store.

• Entry, "Two paths": on a first run, two equal cards, Start the tour and Connect my agents. The second opens the existing first-run screen, unchanged (Inbox first run: notifications ask on the first-run screen; your sent reply in your own words #2148's screen is untouched).
• Steps 1–5:
  1. Open the question.
  2. Pick a picture. The magnifier opens a viewer that offers "Pick A".
  3. Send. This is a replay: nothing is written.
  4. Watch the next messages arrive: the reply is delivered, then the 12:18 PM message, then PR VS Code Guided Reviews: our guide reader in one tab #2134 with its screenshots. Each is tagged Replay.
  5. Open the 77 KB prototype.html in a sandbox="allow-scripts" frame.
• Coach cards: at most two sentences each. They sit beside their target, and on a phone they are a sheet that never covers it. The bar's Exit tour is there at every step.
• Step 6 is real: the person's own first-run screen, headed "Now, let's connect your agents". It never runs installs. Notifications are asked only on a click; if they are skipped, the first real thread asks once more, inline.
• A pick other than A is replayed with an honest note.
• A real message during the tour adds a chip to the tour bar; the chip leaves the tour and opens that thread. Over the replay (steps 1–5) with the tab in front, nothing notifies or rings. On step 6, and whenever the tab is in the background, notifications and the sound work as always. ⌘K search does nothing over the replay.
• Returning users get Settings → General → "Getting started" → Take the tour, and a quiet What's new line that stops once the tour is skipped or finished. There is no dialog. Exit and Finish go back where the tour started (Settings stays Settings) through the browser's Back, so a later Back never reopens the tour.
• Picture labels: "Mockup · VS Code" ("Mockup" on a phone) and "Screenshot · Inbox", through a new optional ui seam, QuestionBlock's pictureBadge (absent by default, so every other card is unchanged).
• Step 6's Try it carries the brief's prompt (one real question, with pictures), only in the tour.
• The first real thread's inline ask follows the ask above the list (never when notifications are off or dismissed), uses a real thread's words, and the list's line stands down while it shows.

Server

• GET /api/inbox/tour/fixture.json and GET /api/inbox/tour/assets/<name> (packages/server/inbox-tour.ts):
  • read only, GET and HEAD;
  • only names in the manifest are served;
  • nosniff, same-origin CORP, ETag;
  • pictures are sandboxed, and the mock gets sandbox allow-scripts, never allow-same-origin.
• The content (about 775 KB) lives in packages/inbox/tour/content/. It is embedded through literal type: "file" imports (inbox-tour-content.ts) and served lazily, never inlined into inbox.html.
• POST /api/inbox/settings takes { tour: { seen?, finished?, skipped?, notify_again? } }. It is stored as config.json inboxTour and returned in GET as tour. No other routes were added.

Rules kept

• No new keyboard shortcuts.
• Component tooltips only.
• 44 px targets on a phone.
• Reduced motion: no pulse and a shorter replay.
• Keyboard focus never stays on the page.
• Light and dark.
• Phone (WebKit) and stacked windows.
• Over the tailnet the tour plays in full; step 6 says to connect agents from their own computer.

Tests

• Unit: packages/inbox/tour/model.test.ts covers:

  • the state machine and coach cards;
  • that every question block parses with core's parser;
  • assets: each one exists and is in the manifest;
  • the content stays under 800 KB;
  • the privacy lint.

  packages/server/inbox-tour.test.ts covers the routes and the tour key.

• DOM: packages/inbox/tour.test.tsx, added to test.yml's DOM list. It covers:

  • Two paths;
  • the walk writing nothing;
  • Exit at every step;
  • the note;
  • the chip;
  • Settings;
  • the tailnet.

• e2e: tests/e2e/inbox-tour.spec.ts, against the compiled binary:

  • the paced newcomer walk, timed and filmed;
  • keyboard only;
  • an iPhone in WebKit;
  • reduced motion and a 900 px stacked window;
  • Exit at every step, with the person's list read before and after and found unchanged;
  • a real message mid-tour;
  • the routes.

• Existing first-run specs and DOM tests now mark the tour decided first (tests/helpers/tour-decided.ts; the DOM server's first-run mode does it). inbox.spec.ts's rhythm check now counts the new quiet "Take the 2-minute tour" line.

Results:

• bun run typecheck passes.
• The inbox DOM list (--isolate), with the ui picture tests: 780 pass.
• The new spec passes on a freshly compiled plannotator binary, and so do inbox, inbox-first-run, notifications, inbox-agents, inbox-phones, inbox-tailscale, inbox-settings, inbox-sound and inbox-mobile.

Timing (the brief's paced model: 220 wpm, 1.5 s to find a control, 3 s for the closer look, 5 s in the mock; screenshot time left out):

• the aha moment (the 12:18 PM message arriving): 36.8 s after Start;
• steps 1–5 done: 74.9 s;
• Finish, after reading step 6 for 35 s: 110 s.

Differs from the prototype

• Step 6 reuses the real first-run screen ("One next step" plus its lists) instead of the prototype's list of agent rows. The record puts changes to the connect logic out of scope.
• The folded "Quiet 9" band is not drawn: drawing it would mean inventing rows.
• Graphite's three full-size screenshots were dropped to keep the content under budget. That side thread's zoom shows its thumbnails.
• The What's new line shows while the tour was never started, skipped or finished, rather than being tied to one release's version.
• Finish returns to the person's Inbox with a toast, rather than a "Waiting for Claude Code's question" card. A first question sent from compose appears in the list as Sent.

🤖 Generated with Claude Code