From 363ef2ef4001ea97f76e4cde58dce21dfb0d4eb3 Mon Sep 17 00:00:00 2001
From: Janic Duplessis <janicduplessis@gmail.com>
Date: Sat, 10 Oct 2026 12:55:14 -0400
Subject: [PATCH 1/2] docs: add agent instructions and a before/after pull
 request template

---
 .github/pull_request_template.md | 14 ++++++++++++++
 .gitignore                       |  1 +
 AGENTS.md                        |  3 +++
 CLAUDE.md                        |  1 +
 4 files changed, 19 insertions(+)
 create mode 100644 .github/pull_request_template.md
 create mode 100644 AGENTS.md
 create mode 100644 CLAUDE.md

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 0000000..a744766
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,14 @@
+<!-- One line: what changed and why. -->
+
+| Before | After |
+| --- | --- |
+| ![Before](./screenshots/before.png) | ![After](./screenshots/after.png) |
+
+### How it was verified
+
+- **Device:** <!-- simulator name, model and runtime, e.g. stim-tour (iPhone 18 Pro 27.0) -->
+- **Readiness:** Stim waited for the app to report ready before the screenshots
+- **Build:** <!-- build time, and whether it came from Stim's cache -->
+- **Logs:** `stim logs --errors` found no errors
+
+Built and verified with [Stim](https://github.com/appandflow/stim).
diff --git a/.gitignore b/.gitignore
index 508d707..902b038 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,3 +5,4 @@ dist/
 /android
 *.log
 .DS_Store
+/screenshots/
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..55d192e
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,3 @@
+# Agent instructions
+
+This is the Stim tutorial app. Follow `stim guide tutorial run` (or `npx stim guide tutorial run` when `stim` is not installed), and `stim guide tutorial share` before you open a pull request.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..8b7cbf4
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+See [AGENTS.md](AGENTS.md).

From 729e24c2fd1aa760b1be7265e9ce46f08f85a0a2 Mon Sep 17 00:00:00 2001
From: Janic Duplessis <janicduplessis@gmail.com>
Date: Sat, 10 Oct 2026 12:57:49 -0400
Subject: [PATCH 2/2] docs: template fill-ins, attach note and README share
 step

---
 .github/pull_request_template.md | 9 ++++++---
 AGENTS.md                        | 4 +++-
 CLAUDE.md                        | 2 +-
 README.md                        | 2 +-
 4 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index a744766..d20fba0 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -1,3 +1,6 @@
+<!-- Screenshots: `gh pr create --body-file <body> --attach screenshots/before.png --attach screenshots/after.png`
+uploads both and rewrites the links below. In the browser, drag each image into its cell instead. -->
+
 <!-- One line: what changed and why. -->
 
 | Before | After |
@@ -6,9 +9,9 @@
 
 ### How it was verified
 
-- **Device:** <!-- simulator name, model and runtime, e.g. stim-tour (iPhone 18 Pro 27.0) -->
-- **Readiness:** Stim waited for the app to report ready before the screenshots
+- **Device:** <!-- simulator name, model and runtime, e.g. stim-tour (iPhone 18 Pro, iOS 27.0) -->
+- **Readiness:** <!-- e.g. Stim waited for the app to report ready (3.5s) -->
 - **Build:** <!-- build time, and whether it came from Stim's cache -->
-- **Logs:** `stim logs --errors` found no errors
+- **Logs:** <!-- result of stim logs --errors -->
 
 Built and verified with [Stim](https://github.com/appandflow/stim).
diff --git a/AGENTS.md b/AGENTS.md
index 55d192e..b2e1371 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,3 +1,5 @@
 # Agent instructions
 
-This is the Stim tutorial app. Follow `stim guide tutorial run` (or `npx stim guide tutorial run` when `stim` is not installed), and `stim guide tutorial share` before you open a pull request.
+This is the Stim tutorial app. Follow `stim guide tutorial run` (or `npx stim guide tutorial run` when `stim` is not installed).
+
+Before you open a pull request, follow `stim guide tutorial share`.
diff --git a/CLAUDE.md b/CLAUDE.md
index 8b7cbf4..43c994c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1 +1 @@
-See [AGENTS.md](AGENTS.md).
+@AGENTS.md
diff --git a/README.md b/README.md
index 4e35319..6e7ddbd 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +17,7 @@ If `stim` is installed globally, drop `npx`. The Android version is `stim androi
 
 ## Tutorial pull requests
 
-The last tutorial step can open a pull request to this repo with a screenshot at `finish/<github-login>.png`. A workflow (`.github/workflows/tutorial-finish.yml`) comments, adds the `tutorial-finish` label and closes the PR without merging. It uses `pull_request_target` and only calls the GitHub API; it never checks out or runs the PR's code.
+The optional share step can open a pull request to this repo with before and after screenshots of your change, following `.github/pull_request_template.md` (older Stim versions commit one screenshot at `finish/<github-login>.png`). A workflow (`.github/workflows/tutorial-finish.yml`) comments, adds the `tutorial-finish` label and closes the PR without merging. It uses `pull_request_target` and only calls the GitHub API; it never checks out or runs the PR's code.
 
 ## License