@davmash/bygone 0.9.8 → 0.10.0

package/cli/tourHistory.js

@@ -2,6 +2,7 @@ const { execFileSync } = require('child_process');
 const { realpathSync } = require('fs');
 const { TextDecoder } = require('util');
 const path = require('path');
+const { buildHistoryDirectoryEntries } = require('../out/historyDirectory.js');
 const { parseNameStatusZ } = require('../out/gitComparison.js');
 
 const DEFAULT_HISTORY_MAX_FILE_BYTES = 2 * 1024 * 1024;
@@ -412,6 +413,30 @@ function createTourHistory(manifest) {
                 rightLabel: `${rightPath} @ ${commit.slice(0, 7)}` };
         },
         compare,
+        changedFiles(input) {
+            input = requireInput(input);
+            if (!Array.isArray(input.commits) || input.commits.length > 32) throw new Error('Expected displayed revisions.');
+            const commits = input.commits.map(commit => commit === null ? null : validateCommit(root, commit));
+            const paths = new Set();
+            for (let index = 1; index < commits.length; index++) {
+                const pair = [commits[index - 1], commits[index]];
+                if (pair[0] === pair[1]) continue;
+                const output = pair.includes(null)
+                    ? git(root, ['ls-tree', '-r', '--name-only', '-z', pair.find(Boolean)])
+                    : git(root, ['diff', '--name-only', '--no-renames', '--no-ext-diff', '-z', ...pair, '--']);
+                output.split('\0').filter(Boolean).forEach(file => paths.add(file));
+            }
+            const changed = [...paths].sort();
+            const inventories = input.includeEntries || input.includeFiles ? commits.map(commit => new Set(commit
+                ? git(root, ['ls-tree', '-r', '--name-only', '-z', commit]).split('\0').filter(Boolean) : [])) : [];
+            return { paths: changed, ...(input.includeFiles ? {
+                files: [...new Set(inventories.flatMap(inventory => [...inventory]))].sort().map(path => ({
+                    kind: 'text-diff', path, changeKind: paths.has(path) ? 'modified' : 'unchanged'
+                }))
+            } : {}), ...(input.includeEntries ? {
+                entries: buildHistoryDirectoryEntries(changed, inventories)
+            } : {}) };
+        },
         compareMany(input) {
             input = requireInput(input);
             if (!Array.isArray(input.commits) || input.commits.length < 2) throw new Error('Comparison requires at least two commits.');
@@ -422,9 +447,14 @@ function createTourHistory(manifest) {
                 to: commits[index + 1],
                 ...(input.path !== undefined ? { path: input.path } : {})
             }));
+            const files = aggregateComparisonFiles(commits, comparisons);
             return {
                 commits,
-                files: aggregateComparisonFiles(commits, comparisons)
+                files,
+                entries: buildHistoryDirectoryEntries(files.map(file => file.path), commits.map((commit, index) => {
+                    const inventory = new Set(git(root, ['ls-tree', '-r', '--name-only', '-z', commit]).split('\0').filter(Boolean));
+                    return new Set(files.filter(file => inventory.has(file.comparisonPanels[index].path)).map(file => file.path));
+                }))
             };
         }
     };

package/completions/_bygone

@@ -60,7 +60,7 @@ _bygone() {
         '--help:Show command help'
     )
     shells=('zsh:Z shell' 'bash:Bash' 'fish:Fish shell')
-    tour_actions=('context:Build structured change evidence' 'coverage:Measure authored tour coverage' 'validate:Validate source and anchors' 'compile:Compile a repository-bound manifest' 'schema:Print the source schema')
+    tour_actions=('context:Build structured change evidence' 'coverage:Measure authored tour coverage' 'validate:Validate source and anchors' 'compile:Compile a repository-bound manifest' 'export:Export a portable HTML tour' 'schema:Print the source schema')
 
     if (( CURRENT == 2 )); then
         _describe 'bygone command' root_items

package/completions/bygone

@@ -23,7 +23,7 @@ _bygone() {
             ;;
         tour)
             if (( COMP_CWORD == 2 )); then
-                COMPREPLY=( $(compgen -W 'context coverage validate compile schema' -- "$cur") )
+                COMPREPLY=( $(compgen -W 'context coverage validate compile export schema' -- "$cur") )
             elif [[ "${COMP_WORDS[2]}" == "context" ]]; then
                 refs="$(_bygone_git_refs)"
                 if [[ "$prev" =~ ^(--base|-m|--main)$ ]]; then

package/completions/bygone.fish

@@ -18,7 +18,7 @@ complete -c bygone -n '__fish_use_subcommand' -s C -r -d 'Run as if Bygone start
 complete -c bygone -n '__fish_use_subcommand' -s h -l help -d 'Show command help'
 complete -c bygone -n '__fish_use_subcommand' -s v -l version -d 'Show the installed version'
 complete -c bygone -n '__fish_seen_subcommand_from completion' -a 'zsh bash fish' -d 'Shell'
-complete -c bygone -n '__fish_seen_subcommand_from tour' -a 'context coverage validate compile schema' -d 'Tour action'
+complete -c bygone -n '__fish_seen_subcommand_from tour' -a 'context coverage validate compile export schema' -d 'Tour action'
 complete -c bygone -n 'string match -q "*tour context*" -- (commandline -opc)' -l base -r -a '(__bygone_git_refs)' -d 'Set the change-context base ref'
 complete -c bygone -n 'string match -q "*tour context*" -- (commandline -opc)' -l output -s o -r -d 'Write the change context'
 complete -c bygone -n 'string match -q "*tour context*" -- (commandline -opc)' -l max-patch-bytes -r -d 'Maximum included patch size per file'

package/docs/change-tour-format.md

@@ -8,54 +8,89 @@ suffix, and explicitly supplied files are validated by content rather than
 rejected by extension.
 
 An authored source is Git-backed, not portable: resolving refs and anchors
-requires the corresponding local repository and Git objects. Version 2 and 3
+requires the corresponding local repository and Git objects. Version 2, 4, and 5
 compiled manifests remain bound to that repository so the presenter can load
 live file history. Version 1 manifests remain readable as legacy portable
-artifacts, without the mode switcher. Version 3 adds independent authored
-tours, scene directory overviews, and review notes; versions 1 and 2 remain
-accepted without those fields.
+artifacts, without the mode switcher. Version 4 supports independent authored
+tours and scene directory overviews; versions 1 and 2 remain accepted without
+those fields.
 
-## Version 3 stability and compatibility
+## Version 5 stability and compatibility
 
-Format version **3 is the stable authoring contract for Bygone 0.9.2**. The
-application version (`0.9.2`) and document version (`version: 3`) are separate:
-UI fixes, navigation changes, and application patch releases do not require
-rewriting a tour or incrementing its format version.
+Format version **5** is the current authoring contract. Application and document
+versions are separate; UI fixes do not require rewriting a tour.
 
-| Document version | Reader support in 0.9.2 | Contract |
+| Document version | Reader support | Contract |
 | --- | --- | --- |
 | 1 | Supported | Legacy source and portable compiled manifests |
 | 2 | Supported | Repository-bound manifests, real revision stacks, and endpoint walkthroughs |
-| 3 | Supported; use for new sources | Version 2 capabilities plus independent authored tours, scene directory overviews, and review notes |
-| Greater than 3 | Rejected with an upgrade message | Never interpreted as version 3 |
-
-The v3 field names, types, required fields, enum values, and meanings are fixed
+| 3 | Retired | Remove the top-level `review` block, set source `version: 4`, and recompile |
+| 4 | Supported | Independent authored tours and scene directory overviews; no Review Notes |
+| 5 | Use for new sources | Optional opening, conclusion, and chapter previews; explicit overview purpose |
+| Greater than 5 | Rejected with an upgrade message | Never interpreted as version 5 |
+
+Version 4 removes the `review` field and the separate Review Notes panel.
+Concepts, boundaries, tradeoffs, and unresolved questions belong in scene or
+step narrative. Clearly distinguish an unknown from a supported conclusion and
+state the next check that would resolve it. Neither source nor compiled manifests
+accept a `review` field; existing v3 documents receive a migration error.
+
+The v5 field names, types, required fields, enum values, and meanings are fixed
 by the [source schema](../schemas/change-tour-source.schema.json) and the
-semantic rules in this document. Valid v3 sources and compiled manifests must
-remain readable by later compatible releases; required fields must not be
-added, existing fields removed, or evidence and mode semantics repurposed under
-the same format number. New syntax that existing v3 readers cannot accept
-requires a new document version, even when the new field is optional. Fixes
-that enforce the documented contract do not make malformed documents valid.
+semantic rules in this document. Breaking syntax or semantic changes require
+a new document version. Fixes enforcing the documented contract do not make
+malformed documents valid.
 
 The source is strict: unknown properties are errors, not an extension
 mechanism. JSON Schema covers document structure; `bygone tour validate`
 additionally checks IDs and references, Git objects, unique anchor matches,
-stage coverage, comparison endpoints, and review freshness. A schema-only pass
+stage coverage, and comparison endpoints. A schema-only pass
 does not prove that the source compiles. Validate against the intended local
 repository before sharing a tour.
 
 Keep authored YAML as the editable source. Compiled JSON is generated evidence,
-not a second authoring syntax; v2/v3 manifests retain repository identity and
+not a second authoring syntax; v2/v4/v5 manifests retain repository identity and
 resolved Git objects. Stable format support does not make missing repositories
 or pruned objects available, and does not promise byte-identical generated
 timestamps or presentation layout. Pin full commit IDs in `range` when the
 underlying comparison must stay fixed.
 
-The compatibility checks cover v1/v2 acceptance, v3-only field gates,
-independent authored modes, overview evidence and fallback semantics, review
-freshness, and rejection of future versions. Run `npm test` before releasing a
-parser, compiler, or schema change; update those checks with any new contract.
+The compatibility checks cover v1/v2 acceptance, v4-only field gates,
+independent authored modes, overview evidence and fallback semantics, retired
+v3 rejection, removed-field rejection, and rejection of future versions. Run
+`npm test` before releasing a parser, compiler, or schema change; update those
+checks with any new contract.
+
+## Opening and conclusion passages
+
+Version 5 adds optional `opening` and `conclusion` at the document root and
+inside each independently authored `tours.historical` or `tours.deconstructed`.
+Each belongs to that narrative; one mode does not inherit another mode’s prose.
+Switching modes stops narration and restores the selected mode’s reading position.
+Returning from file exploration keeps the current passage and paused speech position.
+
+```yaml
+version: 5
+opening:
+  title: What this tour will establish
+  summary: Explain the problem, the review question, and the route through the evidence.
+  bullets:
+    - Name the boundaries this tour will and will not cover.
+conclusion:
+  title: What the evidence established
+  summary: Summarize the supported behavior and its consequence for the reviewer.
+  bullets:
+    - State any remaining uncertainty and the next check that would resolve it.
+```
+
+Both passages require nonblank `title` and `summary`; optional `bullets` contain
+nonblank strings. Unknown fields are rejected. They are narrative reading
+positions, not scenes or evidence: they add no files, steps, or coverage.
+The opening extends the title page, and the conclusion follows the last step.
+Keyboard navigation, narration, search, and heading links include both, including
+image-only guides. A conclusion link uses `part=conclusion`; requesting it in a
+mode without a conclusion reports an unavailable target. Legacy tours remain
+readable and receive no invented closing.
 
 ## Opening and compiling a source
 
@@ -88,7 +123,7 @@ once. When omitted, the presenter falls back to `title`, then a generic tour lab
 
 ## Independent authored tours
 
-Version 3 can supply `tours.historical.chapters` and
+Version 4 can supply `tours.historical.chapters` and
 `tours.deconstructed.chapters`. Each uses the chapter and scene structure below,
 with the document's shared range, anchors, and connections. This lets one file
 explain actual revisions and also teach the change through synthetic stages.
@@ -110,17 +145,35 @@ See `examples/navigation-lab.bygone.yaml` for both tours in one file, and
 [presentation navigation](./present.md#explore-and-follow-tours) for History and
 Compare.
 
+## Chapter previews
+
+Version 5 chapters may include a nonblank `summary`: one or two sentences
+explaining what comes next and why. It is optional in root chapters and each
+independently authored mode. The compiler preserves it in the corresponding
+compiled chapters and derived modes.
+
+Only chapters with summaries have presentation and narration stops. Chapters
+without summaries remain in the contents; selecting their heading or opening
+a chapter link goes to their first scene. Scene-title links alone do not create
+a chapter introduction. Earlier format versions accept chapters without this field.
+
 ## Scene directory overviews
 
-In version 3, an authored walkthrough, stacked-diff, or deconstructed-diff scene may carry a
+In versions 4 and 5, an authored walkthrough, stacked-diff, or deconstructed-diff scene may carry a
 directory overview for the presenter to render alongside the current scene:
 
 ```yaml
 overview:
   kind: directory-diff
+  purpose: See which web layers changed together before tracing their interaction.
   path: web
 ```
 
+Version 5 requires a nonblank `purpose`: explain what the inventory establishes
+and why it is useful at this point. A scene without an explicit `overview` previews
+its first step’s evidence with a “Coming up” caption and no active annotation.
+Title, chapter, discussion, and conclusion passages show narrative only.
+
 `path` is optional and is relative to the repository root. Omit it or use `.`
 for the root directory. Absolute paths, backslashes, and `..` path segments are
 rejected. The compiler preserves this evidence on the corresponding compiled
@@ -150,7 +203,7 @@ Use an explicit authored Historical scene to choose a narrower real comparison.
 ## Structure
 
 ```yaml
-version: 3
+version: 4
 title: A reviewer-facing title
 windowTitle: PR-1234
 sourceUrl: https://example.test/pull/123
@@ -207,42 +260,6 @@ the claim while the code is visible and avoids repeating it in scene framing.
 
 Narrative text supports inline Markdown links such as `[ticket](https://example.com/ticket)`. HTTP and HTTPS destinations open outside the tour; link labels remain visible and clickable during narration highlighting. Authored HTML, other URL schemes, and local-file destinations are treated as plain text. This is link support, not a general Markdown renderer.
 
-The source schema has no ad hoc `notes` field. In v3, use the top-level `review`
-block below for evidence-linked review observations and unresolved questions;
-do not present those questions as settled step rationale.
-
-## Review notes
-
-The optional v3 `review` block records authored interpretation separately from
-the narrative and deterministic evidence. It contains `baseOid`, `headOid`, and
-a nonempty `items` array. Both OIDs must be full 40- or 64-character hexadecimal
-Git IDs, matching the resolved **merge base** and head, respectively. A changed
-range makes the review stale and compilation fails rather than silently
-carrying the conclusions forward.
-
-Each item has a unique nonblank `id`, a `kind` (`concept`, `boundary`,
-`tradeoff`, or `question`), nonblank `title` and `body`, and an `evidence` array
-of `{ sceneId, stepId }` references to endpoint walkthrough steps in the root
-`chapters` (not scenes defined only inside an independent `tours` mode).
-Synthetic stage IDs and stacked-diff step IDs are not walkthrough evidence.
-Claims require at least one reference. Questions may use an empty evidence
-array but require a nonblank `nextCheck`; other items may also supply it.
-Validation confirms the references, not the truth of an author's claim or the
-state of an external deployment.
-
-For example, add this item to `review.items` alongside the structure above:
-
-```yaml
-- id: check-caller
-  kind: question
-  title: Is the caller compatible?
-  body: The source shows persistence, but the deployed caller has not been checked.
-  evidence:
-    - sceneId: decision-flow
-      stepId: persist-first
-  nextCheck: Verify the deployed caller contract against this exact head revision.
-```
-
 ## Requirements
 
 A walkthrough step may carry an optional `requirement` that names the stated
@@ -272,7 +289,7 @@ results search the compiled base and head snapshots, open the exact file and
 side, and preserve **Return to tour** so exploration does not lose authored
 context.
 
-Version 2 and 3 tours show one mode control for moving among live Git History,
+Version 2 and 4 tours show one mode control for moving among live Git History,
 arbitrary Compare ranges, and the authored tours available in that manifest.
 Previously compiled version 2 deconstructed tours retain their authored final
 endpoint walkthrough as **Final tour** beside **Deconstructed tour**. Other
@@ -285,9 +302,9 @@ only when every panel is a real selected Git revision. Use a
 [deconstructed-diff example](../examples/deconstructed-diff.bygone) when
 the teaching order is clearer than the real commit history; its cumulative
 panels are synthetic explanation stages and must never be described as
-commits. In versions 2 and 3, a `deconstructed-diff` scene in root `chapters`
+commits. In versions 2, 4, and 5, a `deconstructed-diff` scene in root `chapters`
 requires a real `stack` with the same base and final endpoints and nonempty
-walkthrough `steps` for compatibility. In version 3, a scene authored inside
+walkthrough `steps` for compatibility. In versions 4 and 5, a scene authored inside
 `tours.deconstructed` may omit both because that tour is synthetic by design.
 Explicit `tours.historical` content supplies its own explanation of real
 revisions. Bygone does not infer a real stack from Git history. Every changed

package/docs/explore.md

@@ -6,10 +6,13 @@ prescribed reading order.
 ## Start a comparison
 
 - The **File** menu contains the familiar new/open/save lifecycle. **New Blank
-  Comparison** opens a writable comparison without source paths.
-- **File → Compare Files…** accepts two or more files. Select one item at a time when
+  Comparison** opens two writable blank panels without source paths.
+- **File → Compare Files…** accepts one or more files. Select one item at a time when
   the files live in different folders, or select several together. Two files open a side-by-side
-  comparison; additional files open the focused multi-panel strip.
+  comparison; additional files open the focused multi-panel strip. Cancel the second
+  file picker to review your first selection and choose **Open File**. The summary
+  also offers **Select More…** and **Add Blank Panel**; add blank panels repeatedly
+  to include as many as you need before choosing **Compare**.
 - **File → Compare Directories…** uses the same additive selection flow for two or
   more directory trees.
 - Drag files or directories into the window for the same selection-count
@@ -58,6 +61,14 @@ The focused strip shows an adjacent pair when space permits and one readable
 panel on narrow windows. Use the strip buttons, panel headers, gutters, wheel,
 or `Alt+Left`/`Alt+Right` to change focus.
 
+In a file comparison panel strip, drag a panel title to move it, or open its **⋮** menu and choose
+**Move left** or **Move right**. Hold a drag near either edge to reach hidden
+panels; press `Escape` to cancel. Edits, undo history, and save destinations
+travel with the panel. Adjacent diffs and copy arrows follow the new order.
+Comparisons built from the commit selector keep revision order and cannot be
+rearranged. Explicitly opened comparison panels (including command-line revision
+comparisons) can still be moved. History and authored tours keep their original order.
+
 - `Cmd/Ctrl+F` searches the active pane.
 - `Cmd/Ctrl+Shift+F` searches either the panes currently displayed by the strip
   or every loaded panel in the comparison, using the explicit scope selector.

package/docs/generating-change-tours.md

@@ -4,6 +4,9 @@ Bygone treats an LLM as a narrative planner and evidence selector, not as the au
 
 For agents that support repository skills, use the agent-agnostic [`pr-tour-guide` skill](../skills/pr-tour-guide/SKILL.md). It packages the complete evidence, authoring, validation, and handoff workflow without depending on a particular agent vendor.
 
+For optional v5 audience metadata, expected-behavior framing, and the investigation
+workflow for reader concerns, see [Expectations and reader feedback](../skills/pr-tour-guide/references/expectations-and-feedback.md).
+
 Install it with the skills CLI:
 
 ```sh
@@ -50,7 +53,8 @@ Use `bygone tour schema` to print the current JSON Schema. The checked-in schema
 
 ## Narrative constraints
 
-- Prefer one reviewer question per scene and three to seven steps per scene.
+- Give each scene one explanatory job. Choose the number of steps needed to
+  develop it; do not split or pad an argument to meet a step-count target.
 - Lead with contracts, invariants, or architectural boundaries before their consumers.
 - Pair behavior with the tests or evidence that prove it.
 - Keep mechanical, generated, and lockfile changes out of the authored narrative unless they alter the reviewer’s conclusion; they remain visible in the complete Files rail.
@@ -59,7 +63,50 @@ Use `bygone tour schema` to print the current JSON Schema. The checked-in schema
 - Avoid claims about runtime behavior, safety, or intent that have no linked evidence.
 - Use connections sparingly. A connection should answer “how are these two facts related?”
 - Preserve access to the complete change instead of presenting the tour as exhaustive review.
-- In a version 3 source, keep unresolved questions and review decisions in the top-level `review` block rather than presenting them as settled scene narration.
+- Put concepts, boundaries, and tradeoffs beside their evidence in scene or step narrative. Label unresolved questions explicitly and state the next check that would resolve them; do not present them as settled conclusions.
+
+## Explain the causal link
+
+Before selecting files, write what the reader should be able to explain after
+each scene. “We inspected the handler” is an activity; “layout notifications
+could invoke synchronization without a position change” is an understanding.
+Merge scenes that produce the same answer, including a separate test scene
+when its checks simply complete the explanation already underway.
+
+Keep the connection from behavior to mechanism to evidence in the main path.
+Do not hide the reason a change works behind a scope disclosure or replace it
+with an inventory of files and revisions. Use enough prose to explain the
+inference. A shorter description can require more reader effort when it removes
+the causal link.
+
+For example, “Ignore layout events” names an action. This explains its effect:
+
+> Neither scroll position changed, so the guard redraws the connectors and
+> returns before either synchronizer runs. This prevents a layout event from
+> undoing the code reveal. Events that do change a position continue through
+> the handler.
+
+Use a title that states the important finding, then focus the code or assertion
+that supports it. Include a preserved behavior, tradeoff, or uncertainty when
+it affects that finding. These are writing responsibilities, not mandatory
+claim/cause/proof fields or repeated labels on every slide.
+
+Compare the small fix in [marker-focus.bygone](../examples/marker-focus.bygone)
+with the multi-commit [navigation lab](../examples/navigation-lab.bygone.yaml).
+The latter uses multiple questions within one comparison before deliberately
+isolating the later correction. Its synthetic mode separates teaching stages
+from real history; generated focus steps are not additional explanatory scenes.
+Each constructed stage's narration appears at its first evidence step. Later
+focuses retain their code targets and offer **Read stage explanation** instead
+of repeating the paragraph. Write the stage narration to cover its argument
+as a whole, and use the scene introduction to explain why the stages belong together.
+
+After validation, walk the compiled route. Check for repeated stage narration,
+unnecessary setup stops, and evidence that does not support the adjacent claim.
+Compiling successfully establishes source validity, not reader understanding.
+Ask an unfamiliar reader what changed, why the mechanism works, what evidence
+supports it, and what remains unverified. At a transition, also ask whether the
+comparison changed. Use those observations to choose further viewer changes.
 
 ## Anchor rules
 
@@ -75,7 +122,7 @@ The missing-tour buttons in History and Compare supply a short handoff like:
 
 ```text
 Read and follow the Bygone tour skill at /path/to/SKILL.md.
-Create a v3 deconstructed tour for /path/to/repository, from <base OID> to <head OID>.
+Create a v5 deconstructed tour for /path/to/repository, from <base OID> to <head OID>.
 Scope: <selected paths, or the whole repository>.
 Additional context: …
 ```
@@ -95,46 +142,37 @@ use **Reset prompt** to regenerate their file reference and workspace context.
 
 The generated prose remains a proposal. Validation proves that its evidence exists and is reproducible; a reviewer must still judge whether its interpretation is correct.
 
-## Optional review notes
-
-A version 3 authored source may add a top-level `review` block when a reviewer needs a
-small set of concepts, boundaries, tradeoffs, or open questions alongside the
-walkthrough. This is opt-in: the Present header shows a **Review notes** button
-only when the compiled manifest includes review notes, and the button opens a
-read-only panel. The panel is an authored interpretation layer; its linked
-scene/step evidence is checked, while its conclusions remain claims for the
-reviewer to assess. The complete Files rail remains available and unchanged.
-
-Review notes pin the exact range they describe:
-
-```yaml
-review:
-  baseOid: 292fe9248c5c49f762489dc688296fc100d120bc
-  headOid: 75b6d7c0303124ec314aa790d6b808c4a9d9ea0e
-  items:
-    - id: range-contract
-      kind: concept
-      title: The range has one historical boundary
-      body: The note explains the invariant a reviewer should keep in mind.
-      evidence:
-        - sceneId: review-pipeline
-          stepId: establish-boundary
-```
-
-Each item uses one of `concept`, `boundary`, `tradeoff`, or `question`.
-Concept, boundary, and tradeoff items need at least one link to an existing
-walkthrough scene and step. A question may leave `evidence` empty, but it must
-include a `nextCheck` describing the follow-up that would resolve it. Evidence
-resolves against the **Final walkthrough**. If the reader is in history or a
-revisions view, following an evidence link first returns to that final range
-before selecting the scene and step.
-
-The `baseOid` pin is the resolved merge-base OID, which may differ from the
-requested base ref; `headOid` is the resolved head OID. Both pins must match
-the resolved range. Compilation rejects a review whose pins describe a changed
-range, and imported manifests reject a review whose pins do not match the
-manifest range. `tour validate` checks the shape, OIDs, and scene/step
-grounding of review notes; it does not verify that an authored interpretation
-is semantically correct. It also does not run or attest to external checks such
-as tests, CI, or the `nextCheck` follow-up. Those claims belong in the note only
-when the author has evidence for them.
+## Frame the reading path
+
+Use version 5 opening and conclusion passages to state the tour’s question and
+recap what its evidence established. Give each authored mode its own framing.
+The Intro is an explicit outline entry. Its “What you'll see” route links to
+chapters, or scenes when there are no chapters. Lists use simple reference
+numbers; headings and narration use plain titles.
+Start the opening with the concrete behavior added or fixed and why it matters.
+Keep that outcome to one or two sentences, then introduce the route.
+Write the opening to explain the problem and the sequence of questions the route
+will answer. Use scene titles that communicate those questions or findings.
+The generated itinerary supplies navigation facts, not the reason the work matters.
+
+Add optional v5 `chapter.summary` only when one or two brief sentences help
+explain what comes next and why. Chapters without previews stay in the contents
+but are skipped as presentation and narration stops; scene-title links are not
+a substitute for preview prose.
+
+A scene answers one reviewer question; steps provide the supporting evidence.
+Multiple scenes may examine the same comparison when each has a different
+question. Merge scenes that merely repeat a question across files.
+
+Before the first step, explain why this scene comes next, what evidence will
+appear, and what the reader should notice in connected prose. Do not repeat the
+chapter route or list every file and revision in each introduction. Keep the
+rationale visible; evidence headers and navigation carry reference details.
+Use an explicit directory overview
+only when the inventory itself supports that question, and state its `purpose`.
+Without one, the viewer previews the first step. The comparison caption identifies
+resolved revisions or synthetic stages; prose should explain why a transition
+matters. A new scene or file does not inherently mean a new comparison. Close
+by connecting the mechanism back to the promised behavior and stating material
+limits, rather than reciting the chapter titles. Include any remaining checks without adding
+fake code stops. See [the format](change-tour-format.md) for the fields.