> **Feature plan:** [Step 1](./tour_snapshots_step1_solution_assessment.md) · [Step 2](./tour_snapshots_step2_feature_description.md) · [Step 3](./tour_snapshots_step3_development_plan.md) · [Step 4](./tour_snapshots_step4_implementation_summary.md)

Debug mode: enabled

Effort study: `railspike-effort` / `v3/tour_snapshots`; [host ledger](../effort_estimation_trial.md). 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 refresh` renders each tour route once, in process, as a logged-out visitor, through the renderer used by `./v3 high-traffic refresh`, and writes `public/assets/tour/<name>.html` atomically, plus the tour page itself at `public/assets/tour/index.html`. Each snapshot gets `noindex` and `<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 run` cron, 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`, in `Key: value` sections (`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.html` becomes 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.html` redirecting 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.txt` then 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.php` and its controller; switch/row markup reused.
- Retraction: the sweep's generated-HTML retirement (see [retraction sweep](../../reference/retraction_sweep.md)).
- Page: the current `public/assets/tour.html` styles 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](./tour_snapshots_debug_log.md)

## Approval

2026-11-15 15:36 ET, maintainer: "Approved step 2." (covers the three decisions to confirm).
