[aledbf]

Plan step R8, its last part: the site's screenshots come from the spin release the site documents, with no person in the loop.

Where the screenshots come from: spin's release, straight (A)

brand's cmd/shots did no processing. It copied the PNGs byte for byte and recorded the release, the commit and each test's title. The spin checkout at the pin already holds all three. So the website takes site-shots.tar.gz from the documented release itself, and brand stops holding the screenshots (spin-stack/brand, the companion PR).

Option (B), brand kept up to date by the daily sync, would need the sync App to write to brand, and a second PR every release. (A) needs no new permission. The sources App already reads spin's contents, and that covers release assets. The sync App still writes only to website.

What changes

• tools/sources: after it fetches spin, it unpacks the release's site-shots.tar.gz into .sources/spin-site-shots/. The download goes through the API with SOURCES_TOKEN. The directory is stamped <tag> <pin> last, so the later task reference in sync.yml, which runs with no token, asks nothing again. The archive must hold only flat PNGs; anything else in it is refused.
• A release without the asset fails, and the error says how to backfill it:
  spin-stack/spin v20261019.02 has no site-shots.tar.gz: ... give it one with gh workflow run site-shots.yml -R spin-stack/spin -f tag=v20261019.02 and fetch again
  A pin that is not a release fails too. Nothing falls back to the pictures already in the repository.
• refgen:
  • releaseShots copies the PNG of each site.spec.ts test that shoots, and removes any other.
  • It writes shots.json with the release, the commit and the test titles.
  • It fails when the stamp is of another release, or when spin is not at a release.
  • checkShots now holds shots.json to the documented release (reference.json spin.tag and spin.commit), no longer to installs. In -check the PNG bytes are compared with the release's own.
  • In the public half (no token), the record is held to reference.json.
  • brandFiles no longer copies screenshots from brand.
• pinReleases skips use/dashboard.md: that page names its screenshots' release, which installations may not run yet. Without the skip, refgen and pinReleases kept rewriting each other's line.
• Install label unchanged: installs is still the newest release in images.json (v20261019.02).
• The regenerated screenshots, shots.json and the dashboard page are now spin v20261024.01's. README, the Taskfile (SHOTS=) and brand's note in versions.yaml are updated to match.

No workflow changes. sync.yml's "Bump the pins" step (task sources:bump) fetches the asset with the token it already has. The screenshots therefore land in the same sync PR as the pin move, and a release without them turns that step red.

Verified

• go test ./... and go vet ./.... The new tests use no network (httptest, a temp dir). A mutation that drops the release comparison, or the missing-asset error, makes them fail.
• SOURCES_TOKEN=$(gh auth token) go tool task check passes: reference:check, the gate with reference:public, the build and every link. Before the regeneration, reference:check failed with: the dashboard's screenshots are of spin v20261019.02 at 617175ff..., and the site documents spin "v20261024.01" at b3598142....
• Dry run of the sync on a copy, with spin pinned back at v20261019.02:
  • task sources failed with the backfill command above.
  • task sources:bump printed spin: v20261019.02 ... -> v20261024.01 b3598142db... and spin: site-shots.tar.gz of v20261024.01: workspace.png, workspaces.png.
  • task reference, with no token, then changed exactly versions.yaml, src/assets/shots/workspace{,s}.png, src/data/shots.json and src/content/docs/use/dashboard.md.

For the reviewer

• spin's release.yml sends no sources-released dispatch, so the sync runs once a day. site-shots.yml finishes about an hour after Release. If a release is cut shortly before 05:23 UTC, that day's sync fails with the backfill message, and the next day's run succeeds. The fix would be for spin's site-shots.yml to send the dispatch after its upload.
• spin's site-shots.yml header still names "brand's screenshots step" as a consumer.

🤖 Generated with Claude Code