[janicduplessis]

Description

The tutorial's optional share step opened a thin pull request: gh pr create --fill built the body from the commit message, with one screenshot of the result and no before state. appandflow/stim-tutorial now ships a pull request template (one-line summary, before/after table, "How it was verified", Stim link) and an AGENTS.md that routes agents to stim guide tutorial (appandflow/stim-tutorial#2, #5). This moves the instructions for that pull request into the version-matched guide.

Solution

• stim guide tutorial run tells the agent, for each change, to screenshot the running app with agent-device before editing and again after Fast Refresh, same screen and device, into .expo/screenshots/. .expo/ is already ignored by the tutorial repo and is not an Expo fingerprint source, so the files never get committed, never change the native cache key, and never block a plain stim worktree remove. A /screenshots/ .gitignore entry was tried first and dropped: Expo's fingerprint hashes .gitignore.
• stim guide tutorial share writes the body from the repo template, filling "How it was verified" only with what the agent observed (ios.name, the app reported ready line, lastBuilds.ios.durationMs and cacheHit, stim logs --errors). It opens the pull request with --body-file plus two --attach flags. gh rewrites the matching ./.expo/screenshots/*.png references in the table to uploaded assets. When a before shot is missing, the agent shows the original screen with git checkout origin/main -- <files>, captures it, and restores the change with git checkout HEAD -- <files>; the change is already committed at that point. The fallback for a gh without --attach no longer commits a PNG with a relative link, which does not render in a pull request body: the user drags the images into the table instead.
• The share step's manual commands, its Desktop ask ("with before and after screenshots") and the website's Share Your Finish line follow. TutorialSteps.swift is regenerated from tutorial-data.ts.

#3365 also edits tutorial.ts, tutorial-data.ts and the generated TutorialSteps.swift (restart, not share). The branches merge cleanly. Whichever merges second should rerun node apps/desktop/scripts/generate-tokens.mjs.

Test plan

• Dry run on the tutorial app (stim 1.19.0, gh 2.99.0, iPhone 18 Pro iOS 27.0 simulator, real ~/.stim, own worktrees only): agent-device before/after shots and the git checkout origin/main fallback both captured the expected screens. A plain stim worktree remove refused only for unpushed commits, not for ignored screenshots. npx fingerprint fingerprint:generate --platform ios gave the same hash with and without .expo/screenshots/ files.
• --attach rewrite confirmed on real pull requests: docs: agent instructions and a before/after PR template stim-tutorial#2 (./screenshots/) and fix(gc): reap orphaned sims that are shut down #5 (./.expo/screenshots/). Their bodies follow the template, and both table cells render the uploaded images with no duplicates appended.
• pnpm test packages/stim-cli/src/__tests__/guide.test.ts: 96 passed. The share contract test now also checks that the attached paths match the body's image references. format:check, lint, typecheck and knip pass. The full pnpm test run had timeouts in unrelated suites (doctor, web, monorepo-resolution) at load average 140-375; CI is the evidence there. Swift was not built locally because of that load; CI builds Desktop.

Fixes #3362

[janicduplessis]

Fresh review: clear, no actionable findings.

Checked:

• Run, share, manual commands, Desktop ask and website line agree on .expo/screenshots/{before,after}.png, the --body-file plus two --attach flags, and ./.expo/screenshots/*.png references. These match the stim-tutorial template, and .expo/ is ignored in that repo's .gitignore.
• gh pr create --help confirms --attach 'file#alt' rewrites body references. The agent-device open ... --udid form is already used in tutorial-data.ts.
• Safety rules are kept: public PR only on explicit request, fork push, never the booted udid, and no committed screenshots. The no---attach fallback is now drag-and-drop.
• node apps/desktop/scripts/generate-tokens.mjs leaves TutorialSteps.swift unchanged. guide.test.ts passes (96). The test change ties the attached paths to the body's image references, which is a real contract.
• The change stays inside the screenshot and PR parts.

Nit, not blocking: the manual commands run git checkout origin/main -- theme.js and screenshot immediately, with no Fast Refresh wait. The guide text says to capture once Fast Refresh applies.