@davmash/bygone 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.8.0
+
+- Added full-surface search across visible panes, comparison panels, unopened change-set files, file history, authored tours, and repositories, plus previewable safe repository replacement
+- Made authored tours native `.bygone` documents with repository discovery, direct desktop opening on macOS, multiple presentation windows, persistent anchor markers, focused multi-panel navigation, and resizable readable layouts
+- Moved VS Code comparisons into independent, restorable editor tabs with unsaved-document support, contextual commands, editable document bridging, and active file history
+- Simplified desktop discovery and menus, clarified panel mutability, and hardened tour focus restoration, deep-file transitions, performance, and narrow layouts
+
 ## 0.7.1
 
 - Fixed the standalone npm package so the installed `bygone` command includes its tour coverage runtime
@@ -16,7 +23,7 @@
 - Added authored, code-connected change tours, bounded LLM context, coverage reporting, stacked and deconstructed explanations, the PR Tour Guide skill, and independent narrative and file navigation
 - Added refreshable sessions, pane-local find, persistent line wrapping, resizable sidebars, and horizontal multi-panel scrolling
 - Adopted the crisp-hybrid Bygone icon and strengthened release packaging across npm, VS Code, desktop, and Homebrew artifacts
-- Added a [guided 0.7 release tour](./tours/v0.7.bygone.yaml) covering the complete range from `v0.6.3`
+- Added a [guided 0.7 release tour](./tours/v0.7.bygone) covering the complete range from `v0.6.3`
 
 ## 0.2.0
 

package/README.md

@@ -24,7 +24,7 @@ Bygone is a VS Code extension and standalone desktop app for visual diff and fil
 - Dynamic adjacent multi-panel diff view
 - Flowing connectors, block contours, and inline change highlighting
 - Git file history viewer with commit-by-commit navigation
-- Local branch-review workspace using merge-base-to-tip semantics and changed-file progress
+- Local branch-change exploration using merge-base-to-tip semantics and changed-file progress
 - Binary-aware comparisons with side-by-side image previews and byte-equality reporting
 
 ## Status
@@ -113,9 +113,13 @@ Branch review compares the selected head directly with `merge-base(base, head)`,
 
 Two-file and directory drill-down comparisons detect binary content before decoding it as text. Images render side by side when they are small enough to preview inline; all binary comparisons report whether the underlying bytes are identical.
 
-Change tours can layer an authored, code-connected narrative over the complete generated change set. Pass a `.bygone.yaml` file with `--tour`; named source anchors compile to exact commit and line references, while an independent Files rail keeps every changed file available without adding filler scenes to the narrative. Try the self-referencing example with `bygone present --tour examples/bygone-history.bygone.yaml`, then see the [change tour format](./docs/change-tour-format.md).
+Change tours can layer an authored, code-connected narrative over the complete generated change set. Pass a `.bygone` file with `--tour`; named source anchors compile to exact commit and line references, while an independent Files rail keeps every changed file available without adding filler scenes to the narrative. The legacy `.bygone.yaml` spelling remains supported. Try the self-referencing example with `bygone present --tour examples/bygone-history.bygone`, then see the [change tour format](./docs/change-tour-format.md).
 
-Agents can validate anchors and structure with `bygone tour validate <file.bygone.yaml> --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), or give a compatible agent the repository's vendor-neutral [`pr-tour-guide` skill](./skills/pr-tour-guide/SKILL.md).
+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), or give a compatible agent the repository's vendor-neutral [`pr-tour-guide` skill](./skills/pr-tour-guide/SKILL.md).
+
+Contributors should consult the internal [product surface overview](./docs/product-surface.md) before adding a command, mode, tour scene, or packaged artifact.
 
 `bygone tour context [<head>] --base <base>` produces a provider-neutral change dossier with bounded patches, changed ranges, file roles, symbol hints, commits, renames, and explicit binary omissions for an LLM to consume.
 
@@ -236,14 +240,23 @@ The wrapper scripts are:
 
 ## Commands
 
-- `Bygone: Compare Files`
-- `Bygone: Compare Directories`
-- `Bygone: Compare Multiple Directories`
-- `Bygone: Compare Multiple Files`
+- `Bygone: Compare Active File With…`
+- `Bygone: Compare Selected Files`
 - `Bygone: Compare with Selected`
-- `Bygone: Compare Test Files`
-- `Bygone: Compare File History`
-- `Bygone: Compare Active File History`
+- `Bygone: Cancel Staged Comparison`
+- `Bygone: View Active File History`
+- `Bygone: Open This Comparison in Desktop`
+- `Bygone: Compare Directories in Desktop…`
+- `Bygone: Compare Three or More Files in Desktop…`
+- `Bygone: Explore Current Branch in Desktop`
+- `Bygone: Present Current Branch in Desktop`
+- `Bygone: Open Authored Tour in Desktop…`
+- `Bygone: Install or Open Desktop App`
+
+Two-file comparisons open as independent editor tabs. Trusted local worktree
+panes edit through VS Code documents, so changes participate in dirty state,
+undo, save, and external-document updates. Historical and non-local inputs are
+read-only. Desktop hand-offs are unavailable in remote extension hosts.
 
 ## Limitations
 

package/cli/commandSpec.js

@@ -11,11 +11,11 @@ const CLI_SPEC = Object.freeze({
         'bygone --history <path>',
         'bygone --git-diff <ref1> <ref2> [<ref3>...]',
         'bygone review [<head>] [--base <base>]',
-        'bygone present [<head>] [--base <base>] [--tour <file.bygone.yaml>]',
-        'bygone tour validate <file.bygone.yaml> [--json]',
-        'bygone tour compile <file.bygone.yaml> [--output <tour.json>]',
+        'bygone present [<head>] [--base <base>] [--tour <file.bygone>]',
+        'bygone tour validate <file.bygone> [--json]',
+        'bygone tour compile <file.bygone> [--output <tour.json>]',
         'bygone tour context [<head>] [--base <base>] [--output <context.json>]',
-        'bygone tour coverage <file.bygone.yaml> [--json] [--minimum-coverage <0-100>]',
+        'bygone tour coverage <file.bygone> [--json] [--minimum-coverage <0-100>]',
         'bygone tour schema',
         'bygone --branch-diff [-b BRANCH] [-m MAIN]',
         'bygone completion <zsh|bash|fish>',
@@ -103,7 +103,7 @@ const CLI_SPEC = Object.freeze({
             id: 'tour',
             kind: 'option',
             tokens: ['--tour'],
-            description: 'Use an authored change-tour YAML file',
+            description: 'Use an authored .bygone presentation',
             argument: 'path'
         },
         {

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' '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 portable manifest' 'schema:Print the source schema')
 
     if (( CURRENT == 2 )); then
         _describe 'bygone command' root_items
@@ -99,8 +99,8 @@ ${historyOptions}
                     compadd -- --base --output -o --max-patch-bytes --max-total-patch-bytes
                     _bygone_git_refs
                 fi
-            elif [[ "$words[3]" == "validate" || "$words[3]" == "compile" ]]; then
-                _files -g '*.bygone.yaml'
+            elif [[ "$words[3]" == "coverage" || "$words[3]" == "validate" || "$words[3]" == "compile" ]]; then
+                _files -g '*.bygone' -g '*.bygone.yaml'
             fi
             ;;
         review)
@@ -113,7 +113,7 @@ ${historyOptions}
             ;;
         present)
             if [[ "$previous" == ${shellAlternation(tokensFor('tour'))} ]]; then
-                _files -g '*.bygone.yaml'
+                _files -g '*.bygone' -g '*.bygone.yaml'
             elif [[ "$previous" == ${shellAlternation(tokensFor('base'))} ]]; then
                 _bygone_git_refs
             else
@@ -183,7 +183,7 @@ _bygone() {
             ;;
         tour)
             if (( COMP_CWORD == 2 )); then
-                COMPREPLY=( $(compgen -W 'context validate compile schema' -- "$cur") )
+                COMPREPLY=( $(compgen -W 'context coverage validate compile schema' -- "$cur") )
             elif [[ "\${COMP_WORDS[2]}" == "context" ]]; then
                 refs="$(_bygone_git_refs)"
                 if [[ "$prev" =~ ^(${baseTokens})$ ]]; then
@@ -210,7 +210,7 @@ _bygone() {
         present)
             refs="$(_bygone_git_refs)"
             if [[ "$prev" == "--tour" ]]; then
-                COMPREPLY=( $(compgen -f -X '!*.bygone.yaml' -- "$cur") )
+                COMPREPLY=( $(compgen -f -- "$cur") )
                 compopt -o filenames 2>/dev/null || true
             elif [[ "$prev" =~ ^(${baseTokens})$ ]]; then
                 COMPREPLY=( $(compgen -W "$refs" -- "$cur") )
@@ -262,7 +262,7 @@ function generateFishCompletion() {
 
     lines.push(
         "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 validate compile schema' -d 'Tour action'",
+        "complete -c bygone -n '__fish_seen_subcommand_from tour' -a 'context coverage validate compile 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/cli/tour.js

@@ -55,7 +55,7 @@ function runTourCommand(args, cwd, packageRoot, output = process.stdout) {
 function parseTourArgs(args) {
     const [action, ...rest] = args;
     if (!TOUR_ACTIONS.includes(action)) {
-        throw new Error(`Usage: bygone tour <${TOUR_ACTIONS.join('|')}> [file.bygone.yaml]`);
+        throw new Error(`Usage: bygone tour <${TOUR_ACTIONS.join('|')}> [file.bygone]`);
     }
     if (action === 'schema') {
         if (rest.length > 0) throw new Error('tour schema does not accept additional arguments.');
@@ -88,7 +88,7 @@ function parseTourArgs(args) {
         if (sourcePath) throw new Error(`tour ${action} accepts exactly one source file.`);
         sourcePath = arg;
     }
-    if (!sourcePath) throw new Error(`tour ${action} requires a .bygone.yaml source file.`);
+    if (!sourcePath) throw new Error(`tour ${action} requires a .bygone source file.`);
     if (action === 'validate' && outputPath) throw new Error('--output is only valid with tour compile.');
     if (action === 'compile' && json) throw new Error('--json is only valid with tour validate or coverage.');
     if (action !== 'coverage' && minimumCoverage !== undefined) {

package/cli/tourFile.js

@@ -1,14 +1,74 @@
-const { readFileSync } = require('fs');
+const { readFileSync, statSync } = require('fs');
 const path = require('path');
-const { load: loadYaml } = require('js-yaml');
+const { TextDecoder } = require('util');
+const { loadAll: loadYamlDocuments } = require('js-yaml');
 const { buildChangeTourManifest, parseChangeTourSource } = require('../out/changeTour.js');
 
+const DEFAULT_MAX_TOUR_SOURCE_BYTES = 1024 * 1024;
+
 function loadTourSource(cwd, sourcePath) {
     const resolvedPath = path.resolve(cwd, sourcePath);
-    const source = parseChangeTourSource(loadYaml(readFileSync(resolvedPath, 'utf8')));
+    const source = readTourSourceDocument(resolvedPath);
     return { resolvedPath, source };
 }
 
+function readTourSourceDocument(sourcePath, options = {}) {
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_TOUR_SOURCE_BYTES;
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) {
+        throw new Error('The Bygone source size limit must be a positive safe integer.');
+    }
+
+    const sourceLabel = path.resolve(sourcePath);
+    let stats;
+    let bytes;
+    try {
+        stats = statSync(sourceLabel);
+        if (!stats.isFile()) {
+            throw new Error('path is not a regular file');
+        }
+        if (stats.size > maxBytes) {
+            throw new Error(`file is ${stats.size} bytes; limit is ${maxBytes} bytes`);
+        }
+        bytes = readFileSync(sourceLabel);
+    } catch (error) {
+        throw new Error(`Could not read Bygone source ${sourceLabel}: ${errorMessage(error)}`, { cause: error });
+    }
+
+    if (bytes.length > maxBytes) {
+        throw new Error(`Could not read Bygone source ${sourceLabel}: file is ${bytes.length} bytes; limit is ${maxBytes} bytes`);
+    }
+    if (bytes.includes(0)) {
+        throw new Error(`Could not decode Bygone source ${sourceLabel}: NUL bytes are not allowed.`);
+    }
+
+    let text;
+    try {
+        text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    } catch (error) {
+        throw new Error(`Could not decode Bygone source ${sourceLabel} as UTF-8: ${errorMessage(error)}`, { cause: error });
+    }
+
+    let documents;
+    try {
+        documents = loadYamlDocuments(text);
+    } catch (error) {
+        throw new Error(`Could not parse Bygone source ${sourceLabel} as YAML: ${errorMessage(error)}`, { cause: error });
+    }
+    if (documents.length !== 1) {
+        throw new Error(`Could not parse Bygone source ${sourceLabel}: expected one YAML document, found ${documents.length}.`);
+    }
+
+    try {
+        return parseChangeTourSource(documents[0]);
+    } catch (error) {
+        throw new Error(`Invalid Bygone source ${sourceLabel}: ${errorMessage(error)}`, { cause: error });
+    }
+}
+
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+
 function buildManifestForTourSource(cwd, source, options = {}) {
     return buildChangeTourManifest(cwd, {
         headRef: options.headRef || source.range?.head,
@@ -21,6 +81,8 @@ function buildManifestForTourSource(cwd, source, options = {}) {
 }
 
 module.exports = {
+    DEFAULT_MAX_TOUR_SOURCE_BYTES,
     buildManifestForTourSource,
-    loadTourSource
+    loadTourSource,
+    readTourSourceDocument
 };

package/completions/_bygone

@@ -38,7 +38,7 @@ _bygone() {
         '--base:Set the branch-review base ref'
         '-m:Set the branch-review base ref'
         '--main:Set the branch-review base ref'
-        '--tour:Use an authored change-tour YAML file'
+        '--tour:Use an authored .bygone presentation'
         '-h:Show command help'
         '--help:Show command help'
     )
@@ -58,7 +58,7 @@ _bygone() {
         '--help:Show command help'
     )
     shells=('zsh:Z shell' 'bash:Bash' 'fish:Fish shell')
-    tour_actions=('context:Build structured change evidence' '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 portable manifest' 'schema:Print the source schema')
 
     if (( CURRENT == 2 )); then
         _describe 'bygone command' root_items
@@ -82,8 +82,8 @@ _bygone() {
                     compadd -- --base --output -o --max-patch-bytes --max-total-patch-bytes
                     _bygone_git_refs
                 fi
-            elif [[ "$words[3]" == "validate" || "$words[3]" == "compile" ]]; then
-                _files -g '*.bygone.yaml'
+            elif [[ "$words[3]" == "coverage" || "$words[3]" == "validate" || "$words[3]" == "compile" ]]; then
+                _files -g '*.bygone' -g '*.bygone.yaml'
             fi
             ;;
         review)
@@ -96,7 +96,7 @@ _bygone() {
             ;;
         present)
             if [[ "$previous" == (--tour) ]]; then
-                _files -g '*.bygone.yaml'
+                _files -g '*.bygone' -g '*.bygone.yaml'
             elif [[ "$previous" == (--base|-m|--main) ]]; then
                 _bygone_git_refs
             else

package/completions/bygone

@@ -23,7 +23,7 @@ _bygone() {
             ;;
         tour)
             if (( COMP_CWORD == 2 )); then
-                COMPREPLY=( $(compgen -W 'context validate compile schema' -- "$cur") )
+                COMPREPLY=( $(compgen -W 'context coverage validate compile schema' -- "$cur") )
             elif [[ "${COMP_WORDS[2]}" == "context" ]]; then
                 refs="$(_bygone_git_refs)"
                 if [[ "$prev" =~ ^(--base|-m|--main)$ ]]; then
@@ -50,7 +50,7 @@ _bygone() {
         present)
             refs="$(_bygone_git_refs)"
             if [[ "$prev" == "--tour" ]]; then
-                COMPREPLY=( $(compgen -f -X '!*.bygone.yaml' -- "$cur") )
+                COMPREPLY=( $(compgen -f -- "$cur") )
                 compopt -o filenames 2>/dev/null || true
             elif [[ "$prev" =~ ^(--base|-m|--main)$ ]]; then
                 COMPREPLY=( $(compgen -W "$refs" -- "$cur") )

package/completions/bygone.fish

@@ -16,7 +16,7 @@ complete -c bygone -n '__fish_use_subcommand' -l test -d 'Open the built-in test
 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 validate compile schema' -d 'Tour action'
+complete -c bygone -n '__fish_seen_subcommand_from tour' -a 'context coverage validate compile 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'
@@ -27,7 +27,7 @@ complete -c bygone -n 'string match -q "*--history*" -- (commandline -opc)' -l i
 complete -c bygone -n '__fish_seen_subcommand_from review' -l base -s m -l main -r -a '(__bygone_git_refs)' -d 'Set the branch-review base ref'
 complete -c bygone -n '__fish_seen_subcommand_from review' -a '(__bygone_git_refs)' -d 'Git ref'
 complete -c bygone -n '__fish_seen_subcommand_from present' -l base -s m -l main -r -a '(__bygone_git_refs)' -d 'Set the branch-review base ref'
-complete -c bygone -n '__fish_seen_subcommand_from present' -l tour -r -d 'Use an authored change-tour YAML file'
+complete -c bygone -n '__fish_seen_subcommand_from present' -l tour -r -d 'Use an authored .bygone presentation'
 complete -c bygone -n '__fish_seen_subcommand_from present' -a '(__bygone_git_refs)' -d 'Git ref'
 complete -c bygone -n 'string match -q "*--branch-diff*" -- (commandline -opc)' -s b -l branch -r -a '(__bygone_git_refs)' -d 'Set the branch-review head ref'
 complete -c bygone -n 'string match -q "*--branch-diff*" -- (commandline -opc)' -l base -s m -l main -r -a '(__bygone_git_refs)' -d 'Set the branch-review base ref'

package/docs/change-explanation-plan.md

@@ -185,7 +185,7 @@ Support deterministic rendering of scenes to PNG, SVG where practical, or HTML f
 
 ### Live PR Tour Guide Loop
 
-Treat the saved `.bygone.yaml` as the shared boundary between an author, an agent, and the open presenter. When the author asks a question, the PR Tour Guide can revise the narrative or its evidence links and save the file; Bygone should validate, compile, and refresh the browser without restarting the presentation.
+Treat the saved `.bygone` as the shared boundary between an author, an agent, and the open presenter. When the author asks a question, the PR Tour Guide can revise the narrative or its evidence links and save the file; Bygone should validate, compile, and refresh the browser without restarting the presentation.
 
 The refresh loop should:
 

package/docs/change-tour-format.md

@@ -1,15 +1,39 @@
 # Change tour authoring format
 
-A `.bygone.yaml` file contains the human-authored reading order and narrative. It points to code with named anchors; it does not store generated hunk indexes or line numbers.
+A `.bygone` file is a UTF-8, single-document YAML source containing the
+human-authored reading order and narrative. It points to code with named
+anchors; it does not store generated hunk indexes or line numbers. The legacy
+`.bygone.yaml` spelling remains supported for editors that depend on a `.yaml`
+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.
+
+Packaged macOS builds register `.bygone` with Bygone, allowing a presentation
+inside its repository to open directly from Finder. Windows and Linux builds
+currently do not install an operating-system file association; open the source
+through Bygone or pass it explicitly to `bygone present --tour`. Direct opening
+discovers the repository from the source file's real location, including when
+the selected path is a symbolic link, and reports an error when no containing
+Git worktree can be found.
 
 Run it against a committed branch range, or omit the refs when the source file pins its own range:
 
 ```sh
-bygone present <head> --base <base> --tour path/to/review.bygone.yaml
-bygone present --tour path/to/self-contained-review.bygone.yaml
+bygone present <head> --base <base> --tour path/to/review.bygone
+bygone present --tour path/to/pinned-review.bygone
 ```
 
-The optional `range` makes a tour self-contained and reproducible; explicit command-line refs take precedence. 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. Compilation fails if an anchor has no match or has multiple matches without an explicit `occurrence`.
+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.
+Compilation fails if an anchor has no match or has multiple matches without an
+explicit `occurrence`.
 
 ## Structure
 
@@ -57,6 +81,19 @@ chapters:
 
 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.
 
-See [Bygone's self-referencing history tour](../examples/bygone-history.bygone.yaml) for a complete narrative that pins and explains the commit where branch review was introduced.
+The presenter search (`Cmd/Ctrl+Shift+F`) can search narrative and code together
+or restrict either scope. Narrative results open the exact scene or step. Code
+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.
+
+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.
+
+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.
 
 For agent workflows, see [Generating change tours with an LLM](./generating-change-tours.md) and the machine-readable [JSON Schema](../schemas/change-tour-source.schema.json).

package/docs/explore.md

@@ -0,0 +1,66 @@
+# Explore with Bygone
+
+Explore is the standalone workspace for investigating differences without a
+prescribed reading order.
+
+## Start a comparison
+
+- **Compare Files…** accepts two or more files. Two files open a side-by-side
+  comparison; additional files open the focused multi-panel strip.
+- **Compare Directories…** accepts two or more directories and compares their
+  trees.
+- Drag files or directories into the window for the same selection-count
+  behavior.
+- Start without paths to get a blank, writable two-panel comparison.
+
+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.
+
+## Ask Git questions
+
+- **View File or Directory History…** follows one path through commits and
+  supported index/worktree states.
+- **Explore Current Branch Change** compares the branch tip with its merge
+  base and shows the complete changed-file inventory.
+- CLI `--git-diff` compares explicit revisions when you already know the refs.
+
+Branch exploration uses committed content. Dirty index and worktree changes
+are reported separately and are never silently folded into a commit snapshot.
+
+## Navigate and search
+
+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.
+
+- `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.
+- `Cmd/Ctrl+H` replaces only in the active writable pane.
+- `Alt+Z` toggles long-line wrapping.
+- `Cmd/Ctrl+R` refreshes sessions whose source can be rebuilt safely.
+
+Search results identify the panel and line they came from. In a directory or
+branch session, choose **Current change set** to search changed text files that are not
+currently open; selecting a result opens its comparison and reveals the exact
+side and line.
+
+While viewing one file's history, choose **Git history** and then select the
+query meaning: **Content occurrence** finds every revision snapshot containing
+the text, while **Introduction or removal** finds revisions where the number of
+matches changed. Selecting a result opens that exact parent-to-commit comparison.
+
+Use **Edit → Search in Files…** for a read-only filesystem search rooted at a
+directory you choose. It supports literal or regular-expression queries,
+case and whole-word matching, include/exclude globs, hidden files, ignore-file
+policy, cancellation, and explicit result limits. It requires ripgrep 14 or
+newer; **Help → Repository Search Status…** reports the detected capability.
+The [search scopes and semantics](./search.md) reference records the different
+engines, options, limits, provenance, and stale-result rules.
+
+## Move into Present
+
+**Present Current Branch** creates a guided tour of the committed branch range.
+**Open Authored Tour…** opens a checked and compiled `.bygone` narrative in
+its own presentation window, leaving the Explore window available.

package/docs/generating-change-tours.md

@@ -1,6 +1,6 @@
 # Generating change tours with an LLM
 
-Bygone treats an LLM as a narrative planner and evidence selector, not as the authority on Git or source locations. The model writes `.bygone.yaml`; Bygone resolves its anchors against pinned commits and rejects missing, ambiguous, or structurally invalid references.
+Bygone treats an LLM as a narrative planner and evidence selector, not as the authority on Git or source locations. The model writes `.bygone`; Bygone resolves its anchors against pinned commits and rejects missing, ambiguous, or structurally invalid references.
 
 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.
 
@@ -19,18 +19,18 @@ For agents that support repository skills, use the agent-agnostic [`pr-tour-guid
 4. Arrange those questions into conceptual chapters rather than filename order.
 5. Attach every walkthrough step to an exact snippet in either the base or head revision.
 6. Add a connection only when it explains a meaningful relationship between two pieces of evidence.
-7. Write the `.bygone.yaml` source.
+7. Write the `.bygone` source.
 8. Validate it and repair every reported problem:
 
    ```sh
-   bygone tour validate review.bygone.yaml --json
+   bygone tour validate review.bygone --json
    ```
 
 9. Compile or present the verified result:
 
    ```sh
-   bygone tour compile review.bygone.yaml --output review.tour.json
-   bygone present --tour review.bygone.yaml
+   bygone tour compile review.bygone --output review.tour.json
+   bygone present --tour review.bygone
    ```
 
 Use `bygone tour schema` to print the current JSON Schema. The checked-in schema is also available at [`schemas/change-tour-source.schema.json`](../schemas/change-tour-source.schema.json).

package/docs/present.md

@@ -0,0 +1,41 @@
+# Present changes with Bygone
+
+Present is the guided-reading surface. It combines narrative scenes with exact
+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.
+- **Open Authored Tour…** or `bygone present --tour path.bygone` opens a
+  narrative whose anchors have been compiled to exact source locations.
+
+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.
+
+## Read provenance correctly
+
+- Normal walkthrough scenes point to exact committed source evidence.
+- A stacked-diff panel represents a real revision and retains its Git identity.
+- A deconstructed-diff panel is an **Explanation stage** assembled from exact
+  change units. It is synthetic and must not be described as a real commit.
+
+Tour content is read-only. Author or revise the YAML and recompile it rather
+than editing historical or synthetic panels in the presenter.
+
+## Authoring workflow
+
+Use the CLI or the repository's tour-generation skill:
+
+```bash
+bygone tour context HEAD --base origin/main
+bygone tour validate tour.bygone --json
+bygone tour compile tour.bygone --output tour.json
+bygone tour schema
+```
+
+See [the change tour format](./change-tour-format.md) and
+[LLM-assisted generation](./generating-change-tours.md) for the complete
+contract. Checked-in examples include real stacked revisions and explicitly
+synthetic deconstructed stages.