[janicduplessis]

Description

The Desktop tutorial asked people to read more than act: every step carried a commands disclosure and both Skip and Mark Done, the parallel change had no prompt, the agent never exercised the app so Agent Actions often had nothing to show, the Live View ticks only counted the first change's simulator, Share could not tell a PR was opened, and Make a Change did not point at the launch notice. This PR reworks the steps, one commit per item from #3366.

Solution

• (a) No commands disclosure. The Desktop disclosure, TutorialStep.commands, tutorialCommands() and the tutorial.commandsExpanded preference are gone. The CLI step command lists only fed stim guide tutorial manual (and the finish section), so the merge with docs: tutorial share step with before/after screenshots and a template PR body #3367 drops them and the manual section too; finish now spells out its seven commands inline. The website no longer links guide tutorial manual.
• (b) One Next. Skip, Mark Done (and its 2-minute gate) and the footer Skip Step are replaced by a Next on every step. It records done when the step's non-optional ticks are all done or its checkpoint completed, else skipped. Detected steps still advance on their own; Restart keeps its confirmation.
• (c) Parallel prompt. "While that builds, make the Tap me button green in a new worktree and check it on the simulator." with Copy. The guide's overview and pause no longer describe a second worktree; finish and delete still name {tour} and {second}. Share stays one PR from {tour}.
• (d) Agent checks on device. stim guide tutorial run now tells the agent, next to docs: tutorial share step with before/after screenshots and a template PR body #3367's before/after screenshots, to tap tap-button, toggle dark-accent-switch, type in name-input and screenshot, re-snapshotting before each action. stim guide agent has no "agent-device not installed" path, so the guide uses agentDevice.installed from stim status --json and falls back to the build result plus stim logs --errors without installing anything.
• (h) Glow + launch notice. Folds polish(desktop): tutorial highlights only on controls, as a fading glow #3164's fading glow (pulsing halo, capsule label, fades after 4 s, Reduce Motion aware) and drops the dead anchors (build section, cache badge, sidebar row, viewer Control). On Make a Change the "launched for " notice's Show button glows when it belongs to the first change's worktree; the step says "Click Show to watch the build." with an Open the build link that does what Show does.
• (e) Agent Actions and Replay. No prompt; one line. The glow goes to the first change's device tile, then its Agent Actions list, then Replay. New viewer events tick "Agent actions viewed" (the list stayed on screen for the glow's 4 s) and "Replay played" (playback rate > 0), only for the first change's simulator. Actions are counted from the tutorial start, since the agent now acts during the change steps. With none recorded the step says so and Next skips it. The step does not auto-advance, so Play does not collapse it mid-replay; Next records it done once both ticks are set.
• (f) Live View and Control. The ticks only matched the first change's simulator while the copy said "either simulator"; they now accept either tutorial simulator (StimKit test tutorialDeviceTicksTheSecondChangesLiveViewToo). I could not reproduce a failure on the first simulator itself. The glow goes to the tile's Control label, then the viewer's screen ("Tap the Tap me button and watch the counter"), and the step auto-advances with both ticks. Because the viewer is a window-sized sheet, a small floating card inside it shows the step line and both ticks; it needs no layout change to the viewer and the panel is simply there again on close.
• (g) Share detection. The step ticks "Pull request opened", links it and completes when stim status reports worktree.pullRequest for the first change's worktree. Fork PRs are covered: selectPullRequest keeps a cross-repository PR whose head repo is one of the checkout's remotes, and the share guide adds the fork as the fork remote (packages/stim-cli/src/workspace/pull-request.ts localRemoteRepos). The status cache refreshes at most every 5 minutes, so the tick can lag. Any state counts, since the tutorial bot closes the PR. The prompt keeps docs: tutorial share step with before/after screenshots and a template PR body #3367's wording.

Test plan

Dev Desktop from this worktree via stim macos (real ~/.stim; a scratch STIM_HOME bundle under /private/tmp cannot be resolved by LaunchServices, so agent-device could not open it), driven with the patched agent-device and --surface app, on a scratch tutorial clone in my scratchpad (never ~/stim-tutorial*). I seeded the dev app's own tutorial.progress default with a fresh begin record to open the panel, since the Help menu is not reachable through the native backend. I acted as the agent: cloned, stim doctor, two worktrees, stim ios --remote local --remote-build local, then the run section's agent-device checks on the tour simulator.

Item	Evidence
a, b: no disclosure, one Next
c: parallel prompt; launch notice
h: build step line and Open the build
f: Control glow on the tutorial tile (Tapped 1 time, Hello, Janic from the agent)
b, e: Next recorded skipped; agent step
d, e: agent's press/fill/screenshot in Agent Actions, glow on the list
glow on Logs
g: share copy, prompt and tick
#3365 Restart: confirmation names the scratch clone
Restart result: clone gone, unregistered, back at Get the Test App

stim logs --source agent on the tour listed the open, wait, screenshots, presses, fill and snapshots; stim logs --errors for the dev app was empty.

Not exercised live:

• The glow on the launch notice's Show button: a cache-hit build finished before the notice could be captured, and delivering the launch URL to the dev bundle also opens its SwiftUI Playground window over the main window. The notice, its Show button and the step text were confirmed through the accessibility tree.
• The viewer's floating card, the screen glow, "Device controlled", "Agent actions viewed" and "Replay played": the native backend cannot click inside the viewer (input needs real mouse events, and the snapshot of the sheet was truncated). These rest on the StimKit tests and the code path above.
• PR detection against a real PR: I did not open a public PR on appandflow/stim-tutorial. Covered by tutorialShareCompletesWithAPullRequestFromTheFirstChangesWorktree.

Fixes #3366
Closes #3154

[janicduplessis]

Fresh review of f55829e (issue #3366 a-h, diff vs origin/main, tests, guide, website, README).

Checks run: swift build --build-tests -Xswiftc -warnings-as-errors + swift test --skip-build --filter Tutorial (51 passed), generate-tokens.mjs --check, check-ascii.mjs, format.sh --check (all clean), pnpm test packages/stim-cli/src/__tests__/guide.test.ts (97 passed). No needs-human category applies.

Actionable findings:

1. apps/desktop/Sources/StimDesktop/Views/DeviceViewer.swift:304-306 - TutorialViewerCard was inserted between the /// Re-renders its content as the replay starts or stops... doc comment and ReplayingContent (now line 330), so that comment now documents the wrong type. Move the card below ReplayingContent or move the comment back onto it.
2. apps/desktop/Sources/StimDesktop/Views/DeviceViewer.swift:143 (card at ~306-326) - TutorialViewerCard is overlaid on the canvas top-left and is hit-testable. In a narrow viewer, or a non-fit scaling mode where the device fills/scrolls past the canvas, it sits over the device screen and swallows clicks there, which is exactly what the device step asks the user to do. The card has no controls; add .allowsHitTesting(false).
3. packages/stim-cli/src/guide/agent.ts:400 - the topic list still says stim guide tutorial # tutorial sections and manual commands; the manual section is removed in this PR.
4. website/docs/desktop.md:100-101 - App Logs is listed before Agent Actions and Replay, but TUTORIAL_STEPS / TutorialSteps.all order is device, agent, logs. Swap the two bullets.
5. apps/desktop/README.md:1868 - "The commands include that name." refers to the step command lists this PR removes. (The surrounding Add Remote Machine paragraph describes a step that is not in TutorialSteps at all; that is pre-existing, out of scope here.)

Looked at and fine: next done/skipped via finished (only the current step is evaluated, consistent with auto-advance); agent step does not auto-advance and counts actions from startedAt; device ticks accept either tutorial simulator while actions/replay ticks are tour-only; share completes on worktree.pullRequest of the tour (fork PRs are kept by selectPullRequest / localRemoteRepos already on main); glow target selection (onPage vs global launch notice / archived filter), Show Me gating and TutorialGlow restart key; launch-notice anchor keyed on device-launch:; no remaining references to tutorialCommands, commandsExpanded, Mark Done or Skip Step; guide run text matches #3367's screenshot flow and the website summary. The new guide contract test asserts testIDs and the open command, which is a real contract.

[janicduplessis]

Fresh review of fd45335 (diff vs origin/main). Review is clear.

The five findings from the previous review are fixed in fd45335:

1. The ReplayingContent doc comment in DeviceViewer.swift is back on ReplayingContent.
2. TutorialViewerCard has .allowsHitTesting(false), so taps reach the device screen.
3. agent.ts topic line no longer mentions manual commands.
4. In website/docs/desktop.md, Agent Actions and Replay now comes before App Logs, matching TUTORIAL_STEPS.
5. The stale "The commands include that name." is gone from the README.

Checks run: swift build --build-tests -Xswiftc -warnings-as-errors, swift test --skip-build --filter Tutorial (51 passed), generate-tokens.mjs --check, check-ascii.mjs, format.sh --check (all clean), pnpm test packages/stim-cli/src/__tests__/guide.test.ts (97 passed).

Reviewed with no findings:

• TutorialProgress.next: it records done for a step in finished and skipped otherwise. finished is refreshed for the step being evaluated, from completion or from all non-optional ticks being done.
• Viewer events: the device step accepts either tutorial simulator. Actions viewed and replay played are accepted only for the tour simulator.
• The agent step never auto-advances. It shows the "No agent actions" detail from logs since startedAt.
• Share completes on the tour's worktree.pullRequest and shows the link.
• TutorialHint.targets: the first anchor on screen wins, and it is global for the launch notice and the Archived filter. Otherwise it requires the selected page. Show Me is gated by offersShowMe.
• The glow restarts when its target key changes.
• The launch notice anchor is keyed on device-launch:.
• RootView openBuild navigates and focuses the iOS device.
• Nothing still references tutorialCommands, commandsExpanded, Mark Done, Skip Step or stim guide tutorial manual.
• The run guide's agent-device text matches the new contract test.
• The tests target real seams.

No needs-human category applies.