Repository source: docs/plans/tour_snapshots/tour_snapshots_step1_solution_assessment.md
Debug mode: enabled
Effort study: railspike-effort / v3/tour_snapshots; host ledger. Standing P2 enrollment.
Extended estimates: enabled
Cycle estimate: 0.45
Original Query
After live_feature_tour (#255) and live_feature_tour_quiet (#256), the maintainer wrote (2026-11-15):
There's a bit of a performance issue in that all the frames take a long time to load, and I imagine it would kill the site very quickly if a lot of people started loading this page.
Then, after options were offered:
I support the idea of pre-generated screenshots, but what if the screenshots are actually HTML? So they're like screenshots, but static pages that like are ready to interact with. Also, I would like a little more like essays to go with the screenshots. And I'm torn about having this gallery, but I think the gallery is a little too dense. I think we should have like one screenshot per row and a little essay to go with it. How does that sound? This would also reduce our need to load multiple frames at once.
Understood Intent
Turn /assets/tour.html into a long read: one wide snapshot per row, each with a short essay about that feature. Each snapshot is a saved HTML copy of a real page: it looks and behaves like the page, but costs the server a static file instead of a PHP render. Opening the tour should cost about the same whether one person or a hundred open it.
Problem Statement
Each tour visit makes 16 full PHP renders at once. On 2026-11-15 single renders of the board, a thread, Prompts and Recent took 7–13 s to first byte in production, so even a handful of simultaneous visitors queue up many slow renders. The grid also crowds 16 small frames together with one-line captions, which says little about why each feature matters.
Concepts touched
All options: proposed tour snapshot (a saved, logged-out HTML copy of one page, shown in the tour). Related to the existing high-traffic cached pages, but its own files, refreshed on its own schedule, and never served at the page's real URL.
What stays the same in every option
Layout: one snapshot per row, full content width, with a heading and an essay of roughly 80–150 words beside it (desktop) or under it (phone). Look/Interact toggle and pinned bar stay; Desktop/Phone frame toggle stays.
Order and set: about 8–10 features instead of 16, chosen for the essays (board, a thread, agents and Prompts, Unread, Gallery, Calendar, Tags, your key, Backup/Git, offline). Final list in Step 2.
Essays: Claude drafts, the maintainer edits. Stored as plain
Key: value/ text sections (one file the page is built from), not JSON and not hand-edited inside the HTML.Still unlinked and
noindexuntil the maintainer says otherwise.
Solution Options
Option A: Snapshots written by a ./v3 command, reusing the high-traffic renderer (recommended)
Estimate: 0.45
New
./v3 tour refreshrenders each tour route once through the same in-process renderer./v3 high-traffic refreshuses (HighTrafficCache (source unavailable)), as a logged-out visitor, and writespublic/assets/tour/<name>.htmlatomically. No HTTP requests to the site.Each snapshot gets
<meta name="robots" content="noindex">and<base target="_top">, so a click inside a snapshot in Interact mode opens the real page in the same tab rather than a page inside a tiny frame.The tour page is generated by the same command from the essay file plus the snapshot list, so text and snapshots never drift apart.
Freshness: run after deploys, or from cron (e.g. hourly). Stale snapshots are harmless; they show an older board.
Retraction: snapshot files are generated HTML under the public root, so the existing retraction sweep's retirement of managed generated HTML must cover
public/assets/tour/(or the command must skip retracted content on refresh). Step 2 decides which.Pros: tour costs static files only; reuses an existing renderer instead of writing a new one; works on any instance; snapshots look exactly like the site.
Cons: a new command and a refresh to remember (or schedule); retraction coverage is a real requirement, not an afterthought.
Driver: wiring the renderer for a fixed route list and generating the page. Uncertainty: whether every route (Compose, Your key, Calendar) renders through the high-traffic path; any that don't are dropped or rendered another way.
Option B: Snapshots saved by fetching the live pages over HTTP
Estimate: 0.35
Same layout and essays, but the refresh command (or a script run anywhere) fetches each live URL once with curl and saves the HTML.
Pros: no coupling to renderer internals; any page that loads can be snapshotted.
Cons: refresh costs 10 slow requests through the front door, during which the site is slow (as now); needs the site up and reachable from where it runs; same retraction and freshness concerns as A without the shared code.
Driver: script and page generation. Uncertainty: authentication modes (members-only instances return a gate page).
Option C: Point the tour at the real URLs and rely on high-traffic mode
Estimate: 0.2
Same layout and essays; frames keep loading real URLs, and the tour routes are added to high-traffic mode's cache so Apache serves cached copies.
Pros: least new code; frames are always the current cached page.
Cons: only helps while high-traffic mode is on and the routes are cached; a cache miss is still a 7–13 s render per frame; Compose and account pages are not cacheable pages today. Does not meet "costs the same for one or a hundred visitors."
Recommendation
Option A. It is the one that makes the tour's cost independent of traffic, and it reuses the renderer the site already trusts for cached pages. B is the fallback if the high-traffic renderer cannot render the chosen routes.
Questions for Step 2
Refresh: after each deploy, hourly cron, or both?
Retraction: extend the sweep to tour snapshots, or have refresh skip retracted content (or both)?
Final feature list, and whether Desktop/Phone frame sizes stay as in #256 (820×1100 and 390×844).
Essays: draft all in Step 2 for your edits, or write them during implementation?
Debug log: tour_snapshots_debug_log.md
Approval
2026-11-15, maintainer: "I support option A as long as we remember to do it at some point if they don't exist, so that I don't necessarily have to log into the terminal and run the command. And perhaps somewhere in the tools, in the most appropriate page, we should also have the ability to trigger this command." Two conditions carried into Step 2: automatic creation when missing, and a Tools trigger.
2026-11-15 15:34 ET, maintainer: "approved step 1".