[IanMayo]

Summary

This PR delivers Phase 3's Onboarding and Web demo rows. The product owner decided both on 17 Oct 2026. Each decision is a dated entry in docs/delivery-plan.md, with notes in the SRD. A second round (second commit) acts on the product owner's answers and an independent panel's review; see Round 2 below. A third round (third commit) moves the browser's walkthroughs to a column on the right on wide screens; see Round 3 below.

Walkthroughs (CAP-25). There are four. Each runs on a fresh copy of the sample's serial 1, titled after it, and never touches the sample itself (debrief_sample.walkthrough):

Walkthrough	Steps
Open and explore a serial	open a copy; move current time; select in the Outline; compare in the Tote; read the Timeline
Import and collate	open a copy; import BLUE ONE's navigation log (REP); see coverage; take the new data; choose a source for a period
Tidy a track	open a copy with GPS glitches in RED ONE (a step of their own); remove jumps; smooth; mark and label a fix; shear a leg (TMA)
Annotate and export a figure	open a copy; draw an annotation; label frequencies; export a traceable image; find its source

• One source of words: vscode/walkthroughs/tours.json.
  • VS Code's contributes.walkthroughs is generated from it (npm run walkthroughs), and a unit test fails if package.json drifts.
  • The playground's panel reads the same file.
  • Each step has an SVG picture drawn from the sample in theme colours, and its keyboard equivalent.
• Ticked by doing, on the walkthrough's own copy only.
  • In VS Code, a step is done when one of these succeeds on that copy: the tool service's request for the change, or the analyst moving time, selecting two tracks by hand, choosing Tote tracks, picking a Timeline entry, or opening Coverage once the log is imported.
  • That sets the step's context key (onContext:debrief.walkthrough.<event>).
  • VS Code's Get Started service only notices a context key that changes after the service starts. So the extension also calls VS Code's internal welcome.markStepComplete and welcome.markStepIncomplete. A failure there is logged, and the integration test checks that VS Code still has both commands.
• Buttons act only on the walkthrough's copy.
  • Every step after the first goes through debrief.walkthrough.do, which opens the copy first.
  • Before a copy exists, the button refuses and says why.
  • The playground's panel does the same.
• Starting again deletes the old copy and unticks the steps. A second press while a copy is being made makes none.
• Playground panel: Walkthroughs. From 1200 px wide it is a column of its own on the right of the map; below that it is the first panel in the side column (Round 3). It is open in the web demo and folded elsewhere. It works from the keyboard and says done to screen readers. Neither it nor the page scrolls sideways at 1440, 1366, 1280, 1200, 1199, 1024, 750, 700, 650, 390, 280 or 210 px, including in a wide font.

Onboarding trial (NFR-09). docs/notes/onboarding-trial.md is a formative protocol for the product owner to run. The human trial has not been run yet.

• Pass rule (pre-registered): at least 80% of participants complete without help above the first rung, the median silent run is 40 minutes or less, and no one takes over 60.
• Set-up: a pilot first, fixed hardware and VS Code version, and a catalogue already added.
• Conduct: a neutral observer with a four-rung help ladder; a silent run, then think-aloud.
• Tasks: import serial 2's red-one.rep and a legacy .dpf plot, then tidy, annotate, and export a traceable figure. The task wording does not mirror the walkthroughs.
• Scoring: the area must fall within 2 nmi, and every failure gets a reason.

An automated speed run does the same tasks, in the playground only: 32 actions in about 12 s (import REP + .dpf 5, tidy 10, annotate 12, export and trace 5). It fails above 36.

Web demo (DEP-06, DEP-07).

• The playground's page runs full screen at /demo/, with every panel and the walkthroughs (open, in their right-hand column on a wide screen). It opens the fixed sample serials by default, and the home page links to it.
• Files the analyst chooses open there too. They are read only in the browser, never sent or stored, with no label or banner. DEP-07 now reads: "The public instance shall ship with fixed sample data. It may open files the analyst chooses, read only in the browser, never sent or stored."
• Content-Security-Policy: every playground page carries one in a meta element (the page, each frame, the geodesic demo). Only the site and jsDelivr are allowed; there are no forms or plugins, and base-uri 'self' covers the demo's <base>.
• Pyodide is loaded from jsDelivr with no integrity check. The product owner accepts that risk. A meta policy does not reach the Python worker, and GitHub Pages cannot send a policy as a header.

The blog embeds are unchanged and still tested. They are narrower than 1200 px, so their walkthroughs stay in the side column, folded.

SRD: CAP-25, NFR-09, OUT-05, DEP-06, DEP-07 (amended), DEP-08, CON-09, CON-10, DEV-06, NFR-13.

Round 2: product owner's answers and the panel's review (17 Oct 2026)

Every fix has a regression test that fails without it.

Finding	Fix	Test
H1: /demo kept content-derived state	In the demo, the Timeline's remembered filter keeps only kinds and view settings, never sources, types or highlighted phrases (contentFree)	Play: marker REP + Word narrative + export + find-source-from-file, filtered and highlighted; local, session, IndexedDB, Cache API and OPFS hold nothing, before and after the tab closes; unit test for contentFree
H2: buttons and ticks could act on another plot	debrief.walkthrough.do and the panel open the copy first, or refuse before one exists; ticks need the walkthrough's copy, in the walkthrough shown	Integration and play: a button before a copy refuses, a button switches back to the copy, and Serial 1 itself gains no steps (checked from its history, replacing the static-file check)
M1: event scoping	command dropped from BY_HAND; a selection needs two or more tracks; Coverage counts only after the import; a stretch is not a shear; only the walkthrough's log counts as its import	Unit, integration and play, one case each
M2: restart and double-click	Restart unticks the steps (also on Get Started); a guard stops a second copy being made	Unit (forgetTour/restart), integration and play (double click makes one copy)
M3: internal VS Code commands	Failures of welcome.markStep* and the context key are logged	Unit (logging) and integration (getCommands has them)
M5: "never sent" coverage	The test now also covers Word/PDF, export, find-source from file, WebSockets and after the tab closes	Play
M6: speed run	Labelled playground-only; imports the .dpf; smooths over 5 fixes; fails above 36	Play
Low	Outline keyboard hint in VS Code (Ctrl+Shift+Enter); time controller and Import fit at 601–750 px; .catch removed in tracks.mjs; the fixed wait after the import dialog replaced by waiting for it to close; the area drawn away from the tracks; install notes name debrief-sample and pyarrow (and Open a copy says so if they are missing); walkthrough commands no longer injected into package.json's menus	Unit (menus hold only contributed commands; whyNotPrepared; CSP placement) and play (widths)

Round 3: the walkthroughs in a right-hand column (product owner, 22 Oct 2026)

Problem. In the playground and /demo, the walkthroughs sat at the top of the side column. Doing a step meant scrolling that column up and down between the step's text and the panel being used.

Change.

• From 1200 px wide, the walkthroughs are a column of their own on the right of the map. The side panels stay on the left and the map in the middle.
  • The column scrolls on its own, so the step's text stays in sight while the analyst works in the left panels and on the map.
  • It is a landmark named Walkthroughs. It folds by its heading, with the pointer or with Enter/Space. Folded, it is a 25 px vertical tab and the map widens. Its status line still speaks to screen readers.
  • It is open in /demo and folded in the playground, as before.
  • Notes (toasts) show over the map, not over the column.
• Below 1200 px (phones, the blog's embeds, the 601–900 px layouts), nothing changes: the walkthroughs are the side column's first panel. When the window crosses 1200 px, host.ts moves the panel between the two places, and the keyboard focus moves with it.
• Why 1200 px. From 901 px a tool's form opens beside the map. At 1200 px the map keeps 669 px beside both columns, and about 290 px with the form open too. At 1024 px it would keep about 150 px with the form open.
  • The column is 20% of the window, 240–300 px.
  • Map widths with the column open: 1280 px gives 733; 1366 px gives 802; 1440 px gives 861.
• A fix the change exposed. The next step's button is now always in sight, so it can be pressed while the previous step is still saving. Removing jumps and applying smoothing now close only their own side panel, not the fix list the next step opened. Without the fix, 1 of 3 test runs failed here.
• Docs. The walkthroughs guide, Try Debrief and the blog post are updated, and so are the post's two playground and demo images. The decision is a dated entry in docs/delivery-plan.md.

Check	Test (onboarding.mjs)
In the right-hand column at 1200–1440 px, right of the map, at the window's edge; the side column starts with Time	rightColumn, at start, at every wide width, in /demo
Fold and unfold by pointer and keyboard narrow and widen the map (≥ 200 px); folded tab ≤ 40 px	play, at start of the walkthroughs
The step's text and button stay in sight with the side column scrolled to its end, and while the step is done; the page never scrolls	Move current time step
The step stays in sight as the side column scrolls to the Timeline	Read the narrative step
No sideways scroll (page, both columns, every step) at 1440, 1366, 1280, 1200, 1199, 1024, 750, 700, 650, 390, 280, 210 px, in a wide font too; the map ≥ 640 px from 1200 px	widths loop
Phone and narrow layouts unchanged: no right-hand column, walkthroughs first in the side column, Time second	widths loop below 1200 px; /demo at 390 px

Before (1366 px, /demo, step 2 pressed: the side column has scrolled to Time, and the step's text has scrolled away):

After (1366 px, the same moment; then with the side column scrolled to the Timeline; then folded):

Phone (390 px), before and after: unchanged.

Blog post (DEV-02, DEV-03, DEV-05)

• A post is needed, and it is in this pull request: site/docs/blog/posts/2026-10-22-first-hour.md. Its screenshots use sample data only. It links to the web demo, embeds a demo with the walkthroughs, and states the accepted CDN risk.
• No post is needed, because:

Guides (DEV-07 to DEV-10)

• User-facing text follows the style guide's language section (npm run check:language also checks tours.json and the playground's panel)
• Any new or changed interaction follows, or extends, an interaction model: new guides/interaction-models/walkthroughs.md (scoping, restarting, walkthrough.do, internal commands, CSP, the right-hand column), plus a row in Keyboard equivalents
• Guides updated in this pull request where the change needs it: the walkthroughs model, the interaction-models index, keyboard equivalents, sample data, Try Debrief, the home page and the extension README

Sensitivity (DEV-05)

• The post, screenshots, sample data and guides contain nothing sensitive: unclassified sample data only, no real exercise or deployment data, organisations by initial only

Screenshots

These are from round 1, when the walkthroughs were at the top of the side column. Round 3's screenshots are above.

VS Code Get Started page, steps ticked:

Playground panel, Tidy a track done:

Explore, Import and collate, and Annotate and export, each done:

At 280 px:

Web demo, full screen, and with a walkthrough started:

VS Code, Import and collate (Coverage) and Tidy a track:

The 20 walkthrough pictures (dark theme):

Test plan

Round 3 changes only the playground (vscode/play/), its tests and the docs. These results are for the head commit:

• vscode: typecheck clean; vitest 641 passed; check:theme and check:language clean.
• scripts/build_site.sh (mkdocs --strict): clean.
• npm run test:play, 3 runs green in a row: 576 s, 576 s and 582 s. The speed run took 32 actions in 12.4, 12.5 and 12.2 s, within its bound of 36. CSP refusals count as errors throughout.

Not rerun in round 3, since nothing they cover changed. Results from round 2:

• uv run ruff check . and ruff format --check .: clean.
• uv run pytest: 1674 passed, 9 skipped. python/debrief-sample/tests/test_walkthrough.py covers:
  • the copies leave the sample untouched;
  • each copy is titled and complete, and Tidy a track has its 3 jumps;
  • the navigation log is new data for the copy;
  • the CLI, and running without pyarrow (Pyodide);
  • the pictures are up to date.
• Schemas, Python and TS --check: clean in round 1. Round 2 changed no schema or TS package, so these were not rerun then either.
• walkthroughs.test.ts has 18 tests: drift, buttons routed through walkthrough.do, event scoping, restart, failure logging, whyNotPrepared, menus, CSP placement, contentFree and the demo page. walkthroughs.mjs --check was clean.
• VS Code integration (npm run test:integration under xvfb): passed. test/integration/walkthroughs.ts runs every walkthrough on its fresh copy. It also checks:
  • do refuses before a copy and switches to the copy after;
  • opening twice makes one copy;
  • selection by command, or of one track, does not tick;
  • Coverage before the import does not tick;
  • smoothing the analyst's own serial 1 does not tick;
  • a stretch or a move is not a shear;
  • restarting unticks only that walkthrough;
  • welcome.markStep* exist;
  • the analyst's catalogues are unchanged.

https://claude.ai/code/session_018c8QiHtanE5rfymqfArUYT

🤖 Generated with Claude Code

Site preview

Live preview: https://debrief.github.io/fuudee/pr-preview/pr-49/ (updated for 30f8b89; it can take a minute to appear). It is kept after this pull request closes; all previews.

The first hour: walkthroughs, and a web demo to try them in (blog/posts/2026-10-22-first-hour.md)

Interaction models (guides/interaction-models/index.md)

Keyboard equivalents (guides/interaction-models/keyboard-equivalents.md)

Walkthroughs (guides/interaction-models/walkthroughs.md)

Sample data (guides/sample-data.md)

Debrief v4 (index.md)

And 1 more changed page(s); see the preview.

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://debrief.github.io/fuudee/pr-preview/pr-49/
Built to branch gh-pages at 2026-10-22 19:53 UTC. Preview will be ready when the GitHub Pages deployment is complete.