@davmash/bygone 0.8.14 → 0.8.16

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.8.16
+
+- Clarified authored-tour errors when a document requires a newer format version
+- Made tag-triggered npm release checks fetch repository history needed by checked-in tour fixtures
+
+## 0.8.15
+
+- Fixed v2 deconstructed-tour coverage so authored Final-mode walkthrough anchors determine coverage while Explanation assignment completeness remains a separate metric
+- Added distinct Final walkthrough coverage and Explanation assignment indicators to authored tours in the Present sidebar
+
 ## 0.8.14
 
 - Reorganized desktop menus around familiar File, Edit, Git, Present, Navigate, View, and Window responsibilities while exposing file, directory, revision, branch, history, tour, and blank-comparison workflows

package/README.md

@@ -123,7 +123,7 @@ Change tours can layer an authored, code-connected narrative over the complete g
 
 Packaged macOS builds register `.bygone` with the desktop app, so Finder can open a presentation directly. Windows and Linux builds currently require opening the file through Bygone or the `bygone` command; they do not install an operating-system file association.
 
-Agents can validate anchors and structure with `bygone tour validate <file.bygone> --json`, compile a portable manifest with `bygone tour compile`, and retrieve the authoring contract with `bygone tour schema`. See [Generating change tours with an LLM](./docs/generating-change-tours.md).
+Agents can validate anchors and structure with `bygone tour validate <file.bygone> --json`, compile a repository-bound manifest with `bygone tour compile`, and retrieve the authoring contract with `bygone tour schema`. See [Generating change tours with an LLM](./docs/generating-change-tours.md).
 
 Install the agent skill:
 
@@ -210,7 +210,7 @@ Publishing is intentionally explicit:
 npm run release:publish
 ```
 
-Run `release:publish` after committing the version and release changes. It aborts unless the worktree is clean and the current branch is `main`, pushes `main`, waits for that exact commit's GitHub Release Check workflow, rebuilds and installs all local artifacts, publishes the npm package, creates a GitHub release for desktop artifacts, and updates the Homebrew tap. It launches npm browser login when needed and pauses immediately before an unpublished version's time-limited passkey challenge. The tap checkout defaults to the sibling `homebrew-bygone` directory; set `BYGONE_HOMEBREW_TAP` to override it. Until Marketplace trusted-publisher policies are publicly configurable, upload the packaged VSIX from the Visual Studio Marketplace publisher page.
+Run `release:publish` after committing the version and release changes. It aborts unless the worktree is clean and the current branch is `main`, pushes `main`, waits for that exact commit's GitHub Release Check workflow, rebuilds and installs all local artifacts, creates a GitHub release for desktop artifacts, and updates the Homebrew tap. The release tag triggers the protected GitHub Actions Release workflow, which publishes the npm package through trusted publishing after approval. The tap checkout defaults to the sibling `homebrew-bygone` directory; set `BYGONE_HOMEBREW_TAP` to override it. Until Marketplace trusted-publisher policies are publicly configurable, upload the packaged VSIX from the Visual Studio Marketplace publisher page.
 
 Reinstall the current built artifacts without rebuilding:
 

package/cli/commandSpec.js

@@ -10,6 +10,7 @@ const CLI_SPEC = Object.freeze({
         'bygone --diff <file1> <file2> <file3> [...]',
         'bygone --history <path>',
         'bygone --git-diff <ref1> <ref2> [<ref3>...]',
+        'bygone --read-only <desktop-arguments...>',
         'bygone review [<head>] [--base <base>]',
         'bygone -C <directory> <command-or-path> [...]',
         'bygone present [<head>] [--base <base>] [--tour <file.bygone>]',
@@ -107,6 +108,13 @@ const CLI_SPEC = Object.freeze({
             description: 'Use an authored .bygone presentation',
             argument: 'path'
         },
+        {
+            id: 'readOnly',
+            kind: 'global',
+            tokens: ['--read-only'],
+            description: 'Open live Explore sources without allowing edits',
+            argument: 'none'
+        },
         {
             id: 'directory',
             kind: 'global',
@@ -144,13 +152,15 @@ const CLI_SPEC = Object.freeze({
         'Two positional paths auto-select file diff or directory compare.',
         'Three or more positional paths auto-select multi-panel file diff or multi-directory compare.',
         '`--git-diff` accepts branches, tags, SHAs, HEAD~1, stash@{0}, INDEX, and WORKTREE.',
+        'In `--git-diff`, committed refs and INDEX are read-only; WORKTREE (also WORKDIR or WORKINGTREE) is live and writable.',
+        '`--read-only` prevents editing every live file or WORKTREE panel in the launched Explore session.',
         '`review` compares merge-base(BASE,HEAD) with HEAD and detects the default base when omitted.',
         '`present` turns the same range into an app-hosted, ordered change tour.',
         '`-C <directory>` resolves relative paths and Git refs from that directory without changing the shell working directory.',
         '`tour validate` resolves every authored anchor; add `--json` for agent-readable output.',
-        '`tour compile` writes a portable manifest to stdout or `--output`; `tour schema` prints its source schema.',
+        '`tour compile` writes a repository-bound manifest to stdout or `--output`; `tour schema` prints its source schema.',
         '`tour context` emits compact, structured Git evidence for an LLM without invoking a model.',
-        '`tour coverage` reports referenced changed hunks and author-declared explanation depth.',
+        '`tour coverage` reports authored walkthrough anchor coverage and author-declared explanation depth; for v2 tours it reads Final mode and reports deconstructed Explanation assignment separately, while `--minimum-coverage` gates the walkthrough metric.',
         '`--branch-diff` is retained as an alias for `review`.',
         '`completion` prints a completion script for Zsh, Bash, or Fish.',
         'In the standalone app, drop 1 file for history, 2 files/directories for compare, or 3+ matching paths for multi-panel compare.'

package/cli/completions.js

@@ -75,7 +75,7 @@ ${legacyOptions}
 ${historyOptions}
     )
     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 portable 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' 'schema:Print the source schema')
 
     if (( CURRENT == 2 )); then
         _describe 'bygone command' root_items

package/cli/present.js

@@ -3,9 +3,11 @@ const { createServer } = require('http');
 const path = require('path');
 const { spawn } = require('child_process');
 const { buildChangeTourManifest, parseChangeTourStory } = require('../out/changeTour.js');
+const { buildTourAuthoringCoverage, buildTourCoverageReport } = require('../out/tourCoverage.js');
 const { buildTourWindowTitle } = require('../out/windowTitle.js');
 const { tokenMatches } = require('./commandSpec.js');
 const { loadTourSource } = require('./tourFile.js');
+const { createTourHistory } = require('./tourHistory.js');
 
 const MIME_TYPES = new Map([
     ['.css', 'text/css; charset=utf-8'],
@@ -23,7 +25,7 @@ async function startPresentation(args, cwd, packageRoot, options = {}) {
         ? parseChangeTourStory(JSON.parse(readFileSync(path.resolve(cwd, process.env.BYGONE_TOUR_STORY), 'utf8')))
         : undefined;
     const source = tourPath ? loadTourSource(cwd, tourPath).source : undefined;
-    const manifest = buildChangeTourManifest(cwd, {
+    const builtManifest = buildChangeTourManifest(cwd, {
         headRef: explicitHeadRef || source?.range?.head || headRef,
         baseRef: baseRef || source?.range?.base,
         title: process.env.BYGONE_TOUR_TITLE,
@@ -31,6 +33,10 @@ async function startPresentation(args, cwd, packageRoot, options = {}) {
         story,
         source
     });
+    const manifest = source
+        ? { ...builtManifest, authoringCoverage: buildTourAuthoringCoverage(buildTourCoverageReport(cwd, source)) }
+        : builtManifest;
+    const history = createTourHistory(manifest);
     const serializedManifest = `${JSON.stringify(manifest, null, 2)}\n`;
     const outputPath = process.env.BYGONE_TOUR_OUTPUT;
     if (outputPath) {
@@ -46,6 +52,31 @@ async function startPresentation(args, cwd, packageRoot, options = {}) {
 
     const server = createServer((request, response) => {
         const requestUrl = new URL(request.url || '/', 'http://127.0.0.1');
+        if (requestUrl.pathname === '/history/list' || requestUrl.pathname === '/history/diff') {
+            if (request.method !== 'POST') return respondJson(response, 405, { error: 'Method not allowed' });
+            if (!isSameOriginLoopbackRequest(request)) return respondJson(response, 403, { error: 'Forbidden' });
+            if (!history) return respondJson(response, 404, { error: 'History requires a version 2 tour.' });
+            let body = '';
+            request.setEncoding('utf8');
+            request.on('data', chunk => {
+                body += chunk;
+                if (body.length > 8192) {
+                    respondJson(response, 413, { error: 'Request too large' });
+                    request.destroy();
+                }
+            });
+            request.on('end', () => {
+                if (response.writableEnded) return;
+                try {
+                    const input = JSON.parse(body);
+                    const result = requestUrl.pathname === '/history/list' ? history.list(input) : history.diff(input);
+                    respondJson(response, 200, result);
+                } catch {
+                    respondJson(response, 400, { error: 'Could not load history for this file and revision.' });
+                }
+            });
+            return;
+        }
         if (requestUrl.pathname === '/narration/claim') {
             if (request.method !== 'POST') {
                 respond(response, 405, 'Method not allowed');
@@ -194,6 +225,16 @@ function respond(response, statusCode, message) {
     response.end(message);
 }
 
+function respondJson(response, statusCode, body) {
+    if (!response.headersSent) {
+        response.writeHead(statusCode, {
+            'Content-Type': 'application/json; charset=utf-8',
+            'Cache-Control': 'no-store'
+        });
+    }
+    response.end(JSON.stringify(body));
+}
+
 function isSameOriginLoopbackRequest(request) {
     const origin = request.headers.origin;
     const host = request.headers.host;

package/cli/tour.js

@@ -27,7 +27,8 @@ function runTourCommand(args, cwd, packageRoot, output = process.stdout) {
         const report = buildTourCoverageReport(cwd, source);
         output.write(options.json ? `${JSON.stringify(report, null, 2)}\n` : renderCoverageReport(report));
         if (options.minimumCoverage !== undefined && report.totals.coveragePercent < options.minimumCoverage) {
-            throw new Error(`Tour coverage ${report.totals.coveragePercent}% is below the required ${options.minimumCoverage}%.`);
+            const label = report.version === 2 ? 'Final walkthrough coverage' : 'Tour coverage';
+            throw new Error(`${label} ${report.totals.coveragePercent}% is below the required ${options.minimumCoverage}%.`);
         }
         return { action: 'coverage', sourcePath: resolvedPath, report };
     }
@@ -98,10 +99,20 @@ function parseTourArgs(args) {
 }
 
 function renderCoverageReport(report) {
+    const coverageLabel = report.version === 2 ? 'Final walkthrough coverage' : 'Tour coverage';
     const lines = [
-        `Tour coverage: ${report.totals.coveredUnits}/${report.totals.includedUnits} hunks (${report.totals.coveragePercent}%)`,
+        `${coverageLabel}: ${report.totals.coveredUnits}/${report.totals.includedUnits} hunks (${report.totals.coveragePercent}%)`,
         `Depth: ${report.depth.mentioned} mentioned · ${report.depth.explained} explained · ${report.depth.contextualized} contextualized`
     ];
+    if (report.version === 2) {
+        for (const assignment of report.explanationAssignments) {
+            const suffix = report.explanationAssignments.length > 1 ? ` (${assignment.sceneId})` : '';
+            lines.push(
+                `Explanation assignment${suffix}: ${assignment.completeUnits}/${assignment.totalUnits} hunks `
+                + `(${assignment.assignmentPercent}%; ${assignment.assignedUnits} assigned, ${assignment.excludedUnits} excluded)`
+            );
+        }
+    }
     if (report.totals.excludedUnits > 0) lines.push(`Excluded: ${report.totals.excludedUnits}/${report.totals.originalUnits} hunks`);
     for (const file of report.files.filter((entry) => entry.uncoveredHunks.length > 0)) {
         lines.push(`${file.path}: ${file.uncoveredHunks.length} uncovered (${file.uncoveredHunks.join(', ')})`);

package/cli/tourHistory.js

@@ -0,0 +1,90 @@
+const { execFileSync } = require('child_process');
+const { realpathSync } = require('fs');
+const path = require('path');
+const { parseNameStatusZ } = require('../out/gitComparison.js');
+
+function git(root, args) {
+    return execFileSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 8 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] });
+}
+
+function validatePath(value) {
+    if (typeof value !== 'string' || !value || value.includes('\0') || value.includes('\\') ||
+        path.posix.isAbsolute(value) || value.split('/').some(part => part === '..' || part === '.' || !part)) {
+        throw new Error('History requires a repository-relative file path.');
+    }
+    return value;
+}
+
+function validateCommit(root, value) {
+    if (typeof value !== 'string' || !/^[a-f0-9]{40,64}$/i.test(value)) {
+        throw new Error('History requires a full Git commit ID.');
+    }
+    const resolved = git(root, ['rev-parse', '--verify', `${value}^{commit}`]).trim();
+    if (resolved !== value.toLowerCase()) throw new Error('History commit could not be resolved.');
+    return resolved;
+}
+
+function createTourHistory(manifest) {
+    if (manifest.version !== 2) return null;
+    let root;
+    try {
+        root = realpathSync(manifest.repository.root);
+        if (realpathSync(git(root, ['rev-parse', '--show-toplevel']).trim()) !== root) throw new Error('Wrong repository root');
+        validateCommit(root, manifest.range.headOid);
+        validateCommit(root, manifest.range.mergeBaseOid);
+    } catch {
+        throw new Error('This v2 tour requires its originating Git repository. Restore the repository before presenting it.');
+    }
+    return {
+        list(input) {
+            const filePath = validatePath(input.path);
+            const commit = validateCommit(root, input.commit || manifest.range.headOid);
+            // Follow the file backwards from the requested revision, including deleted
+            // files and rename records; no working-tree file needs to exist.
+            const output = git(root, ['--literal-pathspecs', 'log', '--follow', '-M', '--max-count=250',
+                '--format=%x1e%H%x00%P%x00%s%x00%cI%x00', '--name-status', '-z', commit, '--', filePath]);
+            const entries = [];
+            let historicalPath = filePath;
+            for (const record of output.split('\x1e').slice(1)) {
+                const fields = record.split('\0');
+                const [oid, parents, summary, timestamp] = fields;
+                const changes = parseNameStatusZ(fields.slice(4).join('\0').replace(/^\0?\n/, ''));
+                const change = changes.find(item => item.path === historicalPath || item.previousPath === historicalPath) || changes[0];
+                if (!change) continue;
+                entries.push({ commit: oid, oid, parentCommit: parents.split(' ')[0] || null,
+                    shortCommit: oid.slice(0, 7), summary, timestamp, path: change.path,
+                    ...(change.previousPath ? { previousPath: change.previousPath } : {}) });
+                historicalPath = change.previousPath || change.path;
+            }
+            return { entries, selectedIndex: entries.length ? 0 : -1, selectedCommit: entries[0]?.commit || null,
+                ...(entries[0]?.commit !== commit ? { fallback: entries.length
+                    ? 'Showing the closest preceding commit that changed this file.'
+                    : 'No file history exists at this revision.' } : {}) };
+        },
+        diff(input) {
+            const filePath = validatePath(input.path);
+            const commit = validateCommit(root, input.commit);
+            const parents = git(root, ['show', '-s', '--format=%P', commit]).trim();
+            const parentCommit = parents.split(' ')[0] || null;
+            const changes = parseNameStatusZ(git(root, ['diff-tree', '--root', '--no-commit-id', '-r', '-M', '--name-status', '-z',
+                ...(parentCommit ? [parentCommit, commit] : [commit])]));
+            const change = changes.find(item => item.path === filePath || item.previousPath === filePath);
+            const rightPath = change?.path || filePath;
+            const leftPath = change?.previousPath || filePath;
+            function read(oid, name, absent) {
+                if (!oid || absent) return '';
+                const content = git(root, ['show', `${oid}:${name}`]);
+                if (content.includes('\0') || content.length > 2 * 1024 * 1024) throw new Error('History file is binary or too large to display.');
+                return content;
+            }
+            return { commit, parentCommit, path: rightPath,
+                ...(change?.previousPath ? { previousPath: change.previousPath } : {}),
+                leftContent: read(parentCommit, leftPath, change?.kind === 'added'),
+                rightContent: read(commit, rightPath, change?.kind === 'deleted'),
+                leftLabel: `${leftPath} @ ${parentCommit ? parentCommit.slice(0, 7) : 'empty'}`,
+                rightLabel: `${rightPath} @ ${commit.slice(0, 7)}` };
+        }
+    };
+}
+
+module.exports = { createTourHistory, validatePath };

package/completions/_bygone

@@ -22,6 +22,7 @@ _bygone() {
         '--git-diff:Compare two or more Git sources'
         '--branch-diff:Legacy alias for branch review'
         '--test:Open the built-in test comparison'
+        '--read-only:Open live Explore sources without allowing edits'
         '-C:Run as if Bygone started in this directory'
         '-h:Show command help'
         '--help:Show command help'
@@ -59,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 portable 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' 'schema:Print the source schema')
 
     if (( CURRENT == 2 )); then
         _describe 'bygone command' root_items

package/completions/bygone

@@ -12,7 +12,7 @@ _bygone() {
     first="${COMP_WORDS[1]}"
 
     if (( COMP_CWORD == 1 )); then
-        COMPREPLY=( $(compgen -W 'review completion present tour --diff --history --git-diff --branch-diff --test -C -h --help -v --version' -- "$cur") $(compgen -f -- "$cur") )
+        COMPREPLY=( $(compgen -W 'review completion present tour --diff --history --git-diff --branch-diff --test --read-only -C -h --help -v --version' -- "$cur") $(compgen -f -- "$cur") )
         compopt -o filenames 2>/dev/null || true
         return
     fi

package/completions/bygone.fish

@@ -13,6 +13,7 @@ complete -c bygone -n '__fish_use_subcommand' -l history -r -d 'Open Git history
 complete -c bygone -n '__fish_use_subcommand' -l git-diff -d 'Compare two or more Git sources'
 complete -c bygone -n '__fish_use_subcommand' -l branch-diff -d 'Legacy alias for branch review'
 complete -c bygone -n '__fish_use_subcommand' -l test -d 'Open the built-in test comparison'
+complete -c bygone -n '__fish_use_subcommand' -l read-only -d 'Open live Explore sources without allowing edits'
 complete -c bygone -n '__fish_use_subcommand' -s C -r -d 'Run as if Bygone started in this directory'
 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'

package/docs/change-tour-format.md

@@ -8,9 +8,10 @@ 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. A compiled
-`.tour.json` manifest contains the resolved source snapshots and is the
-portable artifact, although those snapshots may contain sensitive code.
+requires the corresponding local repository and Git objects. Version 2
+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.
 
 Packaged macOS builds register `.bygone` with Bygone, allowing a presentation
 inside its repository to open directly from Finder. Windows and Linux builds
@@ -31,7 +32,7 @@ The optional `range` pins the source's revisions for reproducibility; explicit
 command-line refs take precedence. Pinned OIDs still require their Git object
 database. The compiler resolves every anchor against the exact merge-base or
 head commit and writes the resulting commit IDs, line ranges, excerpts, file
-contents, and diffs into the portable JSON manifest served by the presenter.
+contents, and diffs into the JSON manifest served by the presenter.
 Compilation fails if an anchor has no match or has multiple matches without an
 explicit `occurrence`.
 
@@ -42,7 +43,7 @@ once. When omitted, the presenter falls back to `title`, then a generic tour lab
 ## Structure
 
 ```yaml
-version: 1
+version: 2
 title: A reviewer-facing title
 windowTitle: PR-1234
 sourceUrl: https://example.test/pull/123
@@ -82,8 +83,35 @@ chapters:
             body: This exact line establishes the ordering guarantee.
             focus: durable-decision
             connection: contract-to-write
+            requirement:
+              id: R1
+              text: Decisions must be durable before any side effect runs.
+              status: fulfilled
+              source: tracker:PROJ-123
+              confidence: high
 ```
 
+## Requirements
+
+A walkthrough step may carry an optional `requirement` that names the stated
+requirement the focused code fulfills. It turns a walkthrough into a
+requirements tour: each step answers which requirement it satisfies, where that
+requirement was stated, and how confident the author is in the mapping.
+
+| Field | Required | Value |
+|-------|----------|-------|
+| `id` | yes | Short requirement label, such as `R1` |
+| `text` | yes | The requirement statement in its original wording |
+| `status` | no | `fulfilled` or `gap` |
+| `source` | no | Where the requirement was stated, such as `pr-description` or `tracker:PROJ-123` |
+| `confidence` | no | `high`, `medium`, or `low` |
+
+The presenter shows a chip with the id and status beside the step title, the
+requirement text next to it, and the source and confidence on a secondary line.
+Steps without a requirement render unchanged. A `gap` status records a
+requirement the author judged unmet at the anchored code; it does not fail
+validation, since the judgment is narrative rather than mechanical.
+
 Only the active step's connection is shown. This keeps relationships useful without adding a permanent second layer of curves to Bygone's diff view. The Tour rail contains only authored scenes; the adjacent Files rail independently lists the complete change set. Browsing a file does not move the narrative, and “Return to tour” restores the file and annotation focused by the current scene.
 
 The presenter search (`Cmd/Ctrl+Shift+F`) can search narrative and code together
@@ -92,12 +120,24 @@ 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 tours show one mode control for jumping directly among the authored
+explanation, real revisions, the final endpoint diff, and live Git history.
+Only modes at or above the tour's maximum authored depth appear. A two-panel
+stack therefore collapses into Final diff rather than creating a duplicate
+Revisions mode. Each mode retains its own location; switching back without
+navigating restores that location exactly.
+
 Use a walkthrough by default. Use a [stacked-diff example](../examples/stacked-diff.bygone)
 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. Every changed hunk must be assigned once or explicitly excluded.
+commits. In version 2, every deconstructed scene must also provide the regular
+endpoint tour's `steps` and an explicit `stack` of the real revisions with the
+same base and final endpoints. Final diff presents those authored walkthrough
+steps, while Explanation stages presents the synthetic reconstruction. Bygone
+does not infer the stack from Git history. Every changed hunk must be assigned
+once or explicitly excluded.
 
 See [Bygone's self-referencing history tour](../examples/bygone-history.bygone) for a complete walkthrough that pins and explains the commit where branch review was introduced.
 

package/docs/explore.md

@@ -20,15 +20,35 @@ Writable filesystem panels are labeled **Writable file**. Git revisions,
 history, tours, and supplied snapshots are labeled **Read-only snapshot**.
 Replace and save operations are unavailable for read-only content.
 
+Pass `--read-only` anywhere in a desktop launch command to keep otherwise-live
+files visible and refreshable without allowing edits or saves. For example,
+`bygone --read-only --diff old.txt current.txt` and
+`bygone -C repo --git-diff HEAD WORKTREE --read-only` label their live sources
+**Read-only file**. The restriction remains in effect when the session refreshes;
+it does not change new comparisons opened later from the app menus.
+
 ## Ask Git questions
 
 - **File → View File or Directory History…** follows one path through commits and
   supported index/worktree states.
 - **Git → Review Branch Change…** accepts a head and optional base ref, compares the
-  head with its merge base, and shows the complete changed-file inventory.
+  head with its merge base, and opens a deterministic overview before the complete
+  changed-file inventory. **Start here** identifies one production entry point when
+  the range supports a reliable choice, **Pay attention** keeps the first-pass
+  production set small, and **Usually skip** collapses mechanical and background
+  files without removing them. Use **Files** to reach the full directory tree.
 - **Git → Compare Revisions…** accepts two or more refs, including `INDEX` and
   `WORKTREE`, matching CLI `--git-diff`.
 
+In a revision comparison, committed refs and `INDEX` are read-only snapshots.
+`WORKTREE` (also accepted as `WORKDIR` or `WORKINGTREE`) is the live repository
+tree and is writable unless the launch uses `--read-only`. For example,
+`bygone -C repo --git-diff HEAD WORKTREE`
+opens the HEAD snapshot on the left and editable worktree files on the right;
+saving updates the repository file, including recreating a deleted file. The
+directory inventory follows `git ls-files -co --exclude-standard`, so ignored
+files and `.git` internals are not included.
+
 Branch exploration uses committed content. Dirty index and worktree changes
 are reported separately and are never silently folded into a commit snapshot.
 

package/docs/present.md

@@ -6,7 +6,10 @@ source evidence while keeping the complete changed-file set available.
 ## Generated and authored tours
 
 - **Present Current Branch** or `bygone present` generates a deterministic
-  reading order for the committed merge-base-to-tip range.
+  reading order for the committed merge-base-to-tip range. It begins with a
+  change overview that reports range size, recommends a **Start here** file when
+  the evidence supports one, and separates **Pay attention** from **Usually
+  skip** first-pass reading hints. Next advances to the recommended file.
 - **Open Authored Tour…** or `bygone present --tour path.bygone` opens a
   narrative whose anchors have been compiled to exact source locations.
 
@@ -14,6 +17,11 @@ The Files rail is independent of the narrative. Browsing another file keeps
 the active tour anchor visible and offers **Return to Tour** to restore the
 scene's intended focus.
 
+Generated overview ranking is deterministic for the resolved Git object IDs.
+It never hides files and does not invent an entry point for a test-only,
+lockfile-only, binary, or generated-only change. Authored tours keep their
+authored first scene and order.
+
 ## Listen to a tour
 
 Use **Listen** in the narrative header or **Present → Listen to Tour** in the

package/docs/product-surface.md

@@ -30,7 +30,7 @@ renderer does not make every workflow appropriate in every host.
 | Compare directories | File → Compare Directories; drag/drop; two or more directory arguments | Directory comparison | Directory rows are read-only; writable file drill-down depends on source/review state | Core | directory smoke and directory-diff tests |
 | Follow one file or directory through Git | File → View File or Directory History; one path; `--history` | Git commits plus supported index/worktree states | Commits are read-only; worktree/index provenance is explicit | Core | Git history and directory-history tests |
 | Compare named revisions | Git → Compare Revisions; `bygone --git-diff <refs…>` | Git blobs/revisions | Read-only snapshots | Core | Git comparison tests and desktop menu contract |
-| Explore a branch change | Git → Review Branch Change; `bygone review` | Merge-base-to-tip branch inventory for a selected head and optional base | Read-only review snapshots; dirty state is reported, not silently included | Core | branch comparison, review-path, and desktop menu tests |
+| Explore a branch change | Git → Review Branch Change; `bygone review` | Deterministic start-here overview plus the complete merge-base-to-tip inventory | Read-only review snapshots; attention is a reading-order hint, viewed state remains session-local, and dirty state is reported rather than included | Core | attention-model, branch comparison, review-path, and desktop menu tests |
 | Search comparison code | Edit → Find or Search Comparison | Active, visible, all loaded panels, unopened changed text snapshots, or one file's Git history | Search is read-only; history distinguishes content occurrence from introduction/removal; Replace requires the active writable model | Core | find, comparison-search, change-set-search, and history-search tests |
 | Search or safely replace in a filesystem tree | Edit → Search in Files; explicit directory root | System ripgrep 14+ with include/exclude, hidden, ignore, and result-limit controls | Search is read-only and cancellable; completed case-sensitive literal searches can build an exclusion-aware, revalidated, atomic replacement preview with guarded undo | Optional system capability | repository search/replace contracts, benchmark, and host-protocol tests |
 | Move through a multi-panel comparison | Strip buttons, panel headers, gutters, wheel, or `Alt+Arrow` | Active panel and adjacent pair | Does not change source identity | Core | focused-strip controller and standalone smoke tests |
@@ -46,8 +46,9 @@ appear only when Electron is not packaged.
 
 | User question | Discovery and launch | Identity/provenance | Mutability | Maturity | Verification |
 | --- | --- | --- | --- | --- | --- |
-| Explain a branch automatically | Present → Present Current Branch or Present Branch or Ref; `bygone present` | Committed merge-base-to-tip range for the current or selected head/base | Read-only | Core | presentation launch, generated-tour, and desktop menu tests |
+| Explain a branch automatically | Present → Present Current Branch or Present Branch or Ref; `bygone present` | Committed merge-base-to-tip range with a deterministic overview first scene and complete Files rail | Read-only; authored tours retain their authored order | Core | attention-model, presentation launch, generated-tour, and desktop menu tests |
 | Open an authored walkthrough | Present → Open Authored Tour; `bygone present --tour`; VS Code hand-off | Manifest range, scene, step, exact source anchor | Read-only | Core | reproducible example and tour validation tests |
+| Assess authored tour coverage | Coverage indicators in the Present sidebar | Distinct hunks referenced by authored walkthrough anchors; v2 Final walkthrough coverage remains separate from deconstructed Explanation assignment completeness | Read-only authoring diagnostics; generated tours have no authored coverage metric | Advanced authoring | v1/v2 coverage and presenter-host tests |
 | Listen to a generated or authored tour | Narrative Listen controls; Present → Listen to Tour | Existing manifest narrative segmented locally by scene/step and visible sentence | Read-only device TTS; voice/rate preferences remain local; continuous playback follows tour navigation and direct exploration pauses it | Core | narration model/controller and presenter-host tests |
 | Explain a real stack | `stacked-diff` scene | Exact real Git revisions per panel | Read-only | Advanced | `examples/stacked-diff.bygone` |
 | Explain a change in conceptual stages | `deconstructed-diff` scene | Explicitly labeled synthetic explanation stages backed by exact hunk IDs | Read-only | Advanced/experimental authoring | `examples/deconstructed-diff.bygone` |
@@ -78,22 +79,25 @@ VS Code's native Search rather than another bundled ripgrep process.
 
 | Surface | Purpose | Mutability/maturity |
 | --- | --- | --- |
-| `bygone`, paths, `--diff`, `--history`, `--git-diff`, `review` | Launch Explore sessions | Core launcher; desktop owns writes |
+| `bygone`, paths, `--diff`, `--history`, `--git-diff`, `--read-only`, `review` | Launch Explore sessions | Core launcher; desktop owns writes; `--read-only` is a persisted capability ceiling for that launch |
 | `present` and `present --tour` | Launch Present sessions | Core, read-only presentation |
 | `tour context` | Produce a bounded provider-neutral change dossier | Authoring support, read-only |
-| `tour validate`, `compile`, `schema`, and coverage options | Validate exact evidence and build portable manifests | Advanced authoring, read-only except explicit output files |
+| `tour validate`, `compile`, `schema`, and coverage options | Validate exact evidence and build repository-bound manifests | Advanced authoring, read-only except explicit output files |
 | `completion` | Generate shell completions from the shared command specification | Supporting tooling |
 
 ## Provenance and mutability vocabulary
 
 Use these labels consistently:
 
-- **Writable file:** filesystem/worktree content participating in dirty, undo,
+- **Writable file:** filesystem content and a live `WORKTREE` column participating in dirty, undo,
   save, reload, watcher, and refresh behavior.
+- **Read-only file:** live filesystem content intentionally opened with editing
+  disabled; external changes and explicit session refresh remain available.
 - **Read-only snapshot:** committed Git, history, tour, or supplied content that
   cannot be replaced or saved over a source file.
 - **INDEX** and **WORKTREE:** repository work states; do not describe them as
-  commits.
+  commits. `INDEX` is a read-only snapshot; `WORKTREE` is live and writable in
+  revision comparisons unless the launch uses `--read-only`.
 - **Explanation stage:** synthetic deconstructed content; never imply that it
   is a real commit.
 - **Real revision:** a panel resolved from an exact Git object identity.