Repository source: docs/plans/tour_snapshots/tour_snapshots_step2_feature_description.md
Debug mode: enabled
Effort study: railspike-effort / v3/tour_snapshots; host ledger. Standing P2 enrollment.
Extended estimates: enabled
Cycle estimate: 0.6
Problem
Each tour visit makes 16 slow PHP renders at once (7–13 s each in production on 2026-11-15), and the dense grid with one-line captions says little about why each feature matters.
User stories
As a visitor, I want to scroll a calm page, one feature at a time, with a short essay and a working copy of the page beside it, so that I understand what ZenMemes is without having it explained up front.
As the maintainer, I want the tour to cost the same whether one person or a hundred open it, so that sharing it can't take the site down.
As the maintainer, I don't want to SSH in to make it work: snapshots should appear on their own when missing, and I want a button in Tools to refresh them.
As the maintainer editing essays, I want them in one plain-text file, so that I can change wording without touching HTML.
Core requirements
Snapshots.
./v3 tour refreshrenders each tour route once, in process, as a logged-out visitor, through the renderer used by./v3 high-traffic refresh, and writespublic/assets/tour/<name>.htmlatomically, plus the tour page itself atpublic/assets/tour/index.html. Each snapshot getsnoindexand<base target="_top">(clicks open the real page in the same tab). No HTTP requests to the site. A route that fails to render keeps its previous snapshot and is reported; the rest still refresh.Self-healing. When snapshots are missing, they get made without the terminal: the step that runs after Deploy now queues a tour refresh in the background if any snapshot is missing or older than the deployed code. The existing
high-traffic runcron, where installed, does the same check. Both use the existing detached task queue (src/ForumRewrite/TaskQueue/), so a refresh never blocks a page load and only one runs at a time.Tools button. Tools → Operations gets a "Tour snapshots" row: last refreshed time, a Refresh now button (root operators only) that queues the same background task, and status while it runs or the last error.
Essays. One plain-text source,
content/tour.txt, inKey: valuesections (Route:,Name:,Title:, then the essay body). The refresh command builds the page from it; editing it and refreshing (button or deploy) updates the page.Page. One snapshot per row: heading and essay (80–150 words) beside a wide frame on desktop, essay above the frame on phone. Look/Interact and Desktop/Phone toggles stay, pinned at the top. Frames load as they approach the viewport (static files, so lazy loading no longer means waiting on the server); the first two load immediately. No intro, nothing opens a new tab,
noindex, unlinked.Features (9): Board · a thread (Start here) · Agents and Prompts · Unread · Gallery · Calendar · Tags · Your key · Backup (your data as Git). Final wording in the essays.
Retraction. The retraction sweep's retirement of managed generated HTML covers
public/assets/tour/. A retired snapshot is regenerated by the next refresh (deploy, cron, or button) from the current read model, which already excludes retracted content.Old page.
/assets/tour.htmlbecomes a one-line redirect to/assets/tour/so any link already copied keeps working.
Decisions taken from the maintainer's message
Option A approved, on the condition that snapshots are created automatically when missing and can be triggered from Tools.
Refresh triggers: after Deploy now (when missing or stale), cron where installed, and the Tools button. No fixed schedule required.
Tools location: Operations (it already holds high-traffic mode, the closest relative).
Decisions to confirm
Essays drafted by Claude during implementation, delivered in the PR for your edits (rather than drafted now in Step 2).
Unread replaces Recent and Users in the list; Compose and API/llms.txt drop out (Compose is empty logged-out; the API pages are text, not features).
Frame sizes stay as in #256 (820×1100 desktop, 390×844 phone).
Delivery scope
Application change. In scope: the refresh command and task, the deploy and cron hooks, the Operations row, content/tour.txt, the generated page template, retraction coverage, redirect from the old page. Not in scope: linking the tour anywhere, per-instance feature lists beyond editing content/tour.txt, logged-in snapshots.
Completion boundary
Entry:
/assets/tour/(and the old/assets/tour.htmlredirecting there); Tools → Operations → Tour snapshots → Refresh now.End-to-end: on a fresh deploy with no snapshots, the tour appears within minutes without a terminal; a visit makes no PHP renders; editing
content/tour.txtthen pressing Refresh now shows the new essay.Recovery: a route that fails to render keeps its old snapshot and shows its error on Operations; a second Refresh while one runs reports "already running"; retracting a post shown in a snapshot removes that snapshot until the next refresh.
Release: maintainer deploys, opens the tour on his phone, scrolls smoothly, and finds it fast.
Risks
Renderer coverage. Calendar, Unread and Your key may not render through the high-traffic path. Check each early; a route that can't is dropped from the list or rendered by the ordinary page renderer.
Snapshots leak viewer state. Render strictly logged-out; a test asserts no session or username markup in snapshots.
Deploy hook adds time to Deploy now. It only queues a task; the deploy itself stays as fast as today.
Shared component inventory
Rendering:
HighTrafficCache,HighTrafficRefresh,HighTrafficRenderInput.Background work:
DetachedTaskQueueLauncher,TaskQueueWorker,SqliteTaskQueueStore.Tools:
templates/pages/operations.phpand its controller; switch/row markup reused.Retraction: the sweep's generated-HTML retirement (see retraction sweep).
Page: the current
public/assets/tour.htmlstyles and toggles, moved into the generated page template.
Concepts touched
Proposed tour snapshot (created): documented in
docs/reference/next to high-traffic mode.
Success criteria
A tour visit triggers zero PHP renders (access log check).
Snapshots appear after Deploy now with no terminal use.
Refresh now works from Operations and reports status.
Retraction test: a snapshot containing a retracted post is retired.
Phone: page scrolls smoothly over frames in Look mode; nothing opens a new tab.
Debug log: tour_snapshots_debug_log.md
Approval
2026-11-15 15:36 ET, maintainer: "Approved step 2." (covers the three decisions to confirm).