@davmash/bygone 0.10.1 → 0.11.1

package/cli/present.js

@@ -1,8 +1,9 @@
-const { existsSync, mkdirSync, readFile, readFileSync, realpathSync, writeFileSync } = require('fs');
+const { existsSync, mkdirSync, readFile, readFileSync, realpathSync, statSync, writeFileSync } = require('fs');
 const { createServer } = require('http');
 const path = require('path');
 const { spawn } = require('child_process');
 const { buildChangeTourManifest, parseChangeTourStory } = require('../out/changeTour.js');
+const { loadChangeCorrespondence } = require('../out/changeCorrespondence');
 const { buildTourAuthoringCoverage, buildTourCoverageReport } = require('../out/tourCoverage.js');
 const { buildTourWindowTitle } = require('../out/windowTitle.js');
 const { tokenMatches } = require('./commandSpec.js');
@@ -22,7 +23,7 @@ const MIME_TYPES = new Map([
 ]);
 
 async function startPresentation(args, cwd, packageRoot, options = {}) {
-    const { headRef, baseRef, tourPath, explicitHeadRef } = parsePresentArgs(args);
+    const { headRef, baseRef, tourPath, explicitHeadRef, correspondencePath } = parsePresentArgs(args);
     const story = !options.ignoreEnvironment && process.env.BYGONE_TOUR_STORY
         ? parseChangeTourStory(JSON.parse(readFileSync(path.resolve(cwd, process.env.BYGONE_TOUR_STORY), 'utf8')))
         : undefined;
@@ -48,6 +49,21 @@ async function startPresentation(args, cwd, packageRoot, options = {}) {
         const contained = relative && relative !== '..' && !relative.startsWith('../') && !path.isAbsolute(relative);
         manifest.localSource = { repo: pathToFileURL(root).href, tour: contained ? relative : pathToFileURL(documentPath).href };
     }
+    const repositoryRoot = builtManifest.repository?.root || cwd;
+    const authoredCorrespondencePath = source?.correspondence
+        ? path.resolve(repositoryRoot, source.correspondence)
+        : undefined;
+    const explicitCorrespondencePath = correspondencePath
+        ? path.resolve(cwd, correspondencePath)
+        : undefined;
+    if (authoredCorrespondencePath && explicitCorrespondencePath
+        && !sameActualFile(authoredCorrespondencePath, explicitCorrespondencePath)) {
+        throw new Error(`Conflicting correspondence artifacts: source.correspondence (${authoredCorrespondencePath}) and --correspondence (${explicitCorrespondencePath}) must identify the same actual file.`);
+    }
+    const correspondencePathToLoad = explicitCorrespondencePath || authoredCorrespondencePath;
+    const correspondence = correspondencePathToLoad
+        ? loadChangeCorrespondence(repositoryRoot, correspondencePathToLoad, { baseOid: manifest.range.mergeBaseOid, headOid: manifest.range.headOid })
+        : null;
     const history = createTourHistory(manifest);
     const serializedManifest = `${JSON.stringify(manifest, null, 2)}\n`;
     const outputPath = options.ignoreEnvironment ? undefined : process.env.BYGONE_TOUR_OUTPUT;
@@ -60,13 +76,16 @@ async function startPresentation(args, cwd, packageRoot, options = {}) {
 
     const tourWindowTitle = buildTourWindowTitle(manifest, 'Bygone');
     const presenterIndexPath = path.join(packageRoot, 'web', 'index.html');
-    let presenterIndexTemplate;
     // Uploaded documents remain immutable, scoped to this existing repository,
     // and addressed independently so opening one cannot mutate another tab.
     const uploadedTours = new Map();
 
     const server = createServer((request, response) => {
         const requestUrl = new URL(request.url || '/', 'http://127.0.0.1');
+        if (requestUrl.pathname === '/correspondence.json') {
+            if (request.method !== 'GET') return respondJson(response, 405, { error: 'Method not allowed' });
+            return respondJson(response, correspondence ? 200 : 404, correspondence || { error: 'No correspondence supplied' });
+        }
         if (requestUrl.pathname === '/tour/open') {
             if (request.method !== 'POST') return respondJson(response, 405, { error: 'Method not allowed' });
             if (!isSameOriginLoopbackRequest(request)) return respondJson(response, 403, { error: 'Forbidden' });
@@ -159,18 +178,20 @@ async function startPresentation(args, cwd, packageRoot, options = {}) {
             return;
         }
         if (requestUrl.pathname === '/' || requestUrl.pathname === '/index.html') {
-            if (!presenterIndexTemplate) {
-                presenterIndexTemplate = readFileSync(presenterIndexPath, 'utf8');
-            }
-            const html = presenterIndexTemplate.replace(
-                /<title>Bygone Tour<\/title>/,
-                `<title>${escapeHtml(tourWindowTitle)}</title>`
-            );
-            response.writeHead(200, {
-                'Content-Type': 'text/html; charset=utf-8',
-                'Cache-Control': 'no-store'
+            // Read HTML like the runtime assets so a rebuild cannot leave a
+            // running presentation serving old controls with new JavaScript.
+            readFile(presenterIndexPath, 'utf8', (error, template) => {
+                if (error) { respond(response, 500, 'Read failed'); return; }
+                const html = template.replace(
+                    /<title>Bygone Tour<\/title>/,
+                    `<title>${escapeHtml(tourWindowTitle)}</title>`
+                );
+                response.writeHead(200, {
+                    'Content-Type': 'text/html; charset=utf-8',
+                    'Cache-Control': 'no-store'
+                });
+                response.end(html);
             });
-            response.end(html);
             return;
         }
         const targetPath = resolveAssetPath(packageRoot, requestUrl.pathname);
@@ -203,7 +224,7 @@ async function startPresentation(args, cwd, packageRoot, options = {}) {
         server.close();
         throw new Error('Could not determine the presentation server address.');
     }
-    const url = `http://127.0.0.1:${address.port}/?manifest=/tour.json${options.location ? serializeDocumentFragment(options.location.mode, options.location.focus) : ''}`;
+    const url = `http://127.0.0.1:${address.port}/?manifest=/tour.json${correspondence ? '&correspondence=1' : ''}${options.location ? serializeDocumentFragment(options.location.mode, options.location.focus) : ''}`;
     if (options.announce !== false) {
         process.stdout.write(`Bygone change tour running at ${url}\n`);
         process.stdout.write('Press Ctrl+C to stop.\n');
@@ -225,6 +246,7 @@ function parsePresentArgs(args) {
     let explicitHeadRef;
     let baseRef;
     let tourPath;
+    let correspondencePath;
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (tokenMatches('base', arg)) {
@@ -234,6 +256,11 @@ function parsePresentArgs(args) {
             baseRef = args[++index];
             continue;
         }
+        if (arg === '--correspondence') {
+            if (!args[index + 1] || args[index + 1].startsWith('-')) throw new Error('--correspondence requires a file path.');
+            correspondencePath = args[++index];
+            continue;
+        }
         if (tokenMatches('tour', arg)) {
             if (!args[index + 1]) throw new Error(`${arg} requires a YAML file.`);
             tourPath = args[++index];
@@ -248,7 +275,7 @@ function parsePresentArgs(args) {
         headRef = arg;
         explicitHeadRef = arg;
     }
-    return { headRef, baseRef, tourPath, explicitHeadRef };
+    return { headRef, baseRef, tourPath, explicitHeadRef, ...(correspondencePath ? { correspondencePath } : {}) };
 }
 
 function resolveAssetPath(packageRoot, requestPath) {
@@ -315,6 +342,24 @@ function isSameOriginLoopbackRequest(request) {
     }
 }
 
+function sameActualFile(first, second) {
+    if (first === second) return true;
+    try {
+        const left = statSync(first);
+        const right = statSync(second);
+        if (left.dev !== undefined && left.ino !== undefined
+            && left.dev === right.dev && left.ino === right.ino
+            && left.ino !== 0 && right.ino !== 0) return true;
+    } catch {
+        // Fall back to canonical paths on filesystems without usable identity metadata.
+    }
+    try {
+        return realpathSync(first) === realpathSync(second);
+    } catch {
+        return false;
+    }
+}
+
 function escapeHtml(text) {
     return text
         .replaceAll('&', '&amp;')

package/cli/tour.js

@@ -34,12 +34,21 @@ function runTourCommand(args, cwd, packageRoot, output = process.stdout) {
         return { action: 'schema' };
     }
     if (options.action === 'context') {
+        const range = options.dependencies
+            ? require('../out/gitComparison.js').resolveBranchReviewRange(cwd, options.headRef, options.baseRef)
+            : undefined;
         const context = buildChangeTourContext(cwd, {
+            range,
             headRef: options.headRef,
             baseRef: options.baseRef,
+            correspondencePath: options.correspondencePath ? path.resolve(cwd, options.correspondencePath) : undefined,
             maxPatchBytes: options.maxPatchBytes,
             maxTotalPatchBytes: options.maxTotalPatchBytes
         });
+        if (options.dependencies) {
+            const { buildDependencyGraph } = require('../out/dependencyGraph.js');
+            context.dependencies = buildDependencyGraph(cwd, { range });
+        }
         return writeJsonResult('change-tour context', context, options.outputPath, cwd, output);
     }
 
@@ -147,7 +156,9 @@ function parseContextArgs(args) {
     let baseRef;
     let outputPath;
     let maxPatchBytes;
+    let correspondencePath;
     let maxTotalPatchBytes;
+    let dependencies = false;
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (arg === '--base' || arg === '-m' || arg === '--main') {
@@ -160,6 +171,12 @@ function parseContextArgs(args) {
             outputPath = args[++index];
             continue;
         }
+        if (arg === '--dependencies') { dependencies = true; continue; }
+        if (arg === '--correspondence') {
+            if (!args[index + 1] || args[index + 1].startsWith('-')) throw new Error('--correspondence requires a file path.');
+            correspondencePath = args[++index];
+            continue;
+        }
         if (arg === '--max-patch-bytes') {
             if (!args[index + 1]) throw new Error(`${arg} requires a positive integer.`);
             maxPatchBytes = Number.parseInt(args[++index], 10);
@@ -180,7 +197,7 @@ function parseContextArgs(args) {
         if (headRef) throw new Error('tour context accepts at most one head ref.');
         headRef = arg;
     }
-    return { action: 'context', headRef, baseRef, outputPath, maxPatchBytes, maxTotalPatchBytes };
+    return { action: 'context', headRef, baseRef, outputPath, maxPatchBytes, maxTotalPatchBytes, ...(correspondencePath ? { correspondencePath } : {}), ...(dependencies ? { dependencies } : {}) };
 }
 
 function writeJsonResult(label, value, outputPath, cwd, output) {

package/cli/tourExport.js

@@ -78,7 +78,7 @@ function materializeTour(sourcePath, profile) {
     delete manifest.localSource;
     // A source URL is optional provenance and may carry credentials or local bindings.
     delete manifest.sourceUrl;
-    const contentKeys = new Set(['leftContent', 'rightContent', 'content']);
+    const contentKeys = new Set(['leftContent', 'rightContent', 'content', 'text']);
     function pack(value) {
         if (Array.isArray(value)) return value.map(pack);
         if (!value || typeof value !== 'object') return value;

package/completions/_bygone

@@ -13,7 +13,10 @@ _bygone() {
     local previous="${words[CURRENT-1]}"
     local -a root_items review_options present_options legacy_options history_options shells tour_actions
     root_items=(
+        'evidence:Inspect, import, refresh, or present pinned review evidence'
         'review:Review a committed branch against its merge base'
+        'dependencies:Compare static JS/TS module dependencies at committed revisions'
+        'correspondence:Import externally produced symbol correspondence evidence'
         'completion:Print shell completion source'
         'present:Open an app-hosted tour of a committed branch range'
         'tour:Validate, compile, or inspect authored change tours'
@@ -41,6 +44,7 @@ _bygone() {
         '-m:Set the branch-review base ref'
         '--main:Set the branch-review base ref'
         '--tour:Use an authored .bygone presentation'
+        '--correspondence:Use pinned symbol evidence in present or tour context'
         '-h:Show command help'
         '--help:Show command help'
     )
@@ -78,16 +82,24 @@ _bygone() {
             elif [[ "$words[3]" == "context" ]]; then
                 if [[ "$previous" == (--base|-m|--main) ]]; then
                     _bygone_git_refs
-                elif [[ "$previous" == "--output" || "$previous" == "-o" ]]; then
+                elif [[ "$previous" == "--output" || "$previous" == "-o" || "$previous" == "--correspondence" ]]; then
                     _files
                 else
-                    compadd -- --base --output -o --max-patch-bytes --max-total-patch-bytes
+                    compadd -- --base --output -o --max-patch-bytes --max-total-patch-bytes --correspondence --dependencies
                     _bygone_git_refs
                 fi
             elif [[ "$words[3]" == "coverage" || "$words[3]" == "validate" || "$words[3]" == "compile" ]]; then
                 _files -g '*.bygone' -g '*.bygone.yaml'
             fi
             ;;
+        dependencies)
+            if [[ "$previous" == "--output" || "$previous" == "-o" ]]; then
+                _files
+            else
+                compadd -- --base --json --output -o
+                _bygone_git_refs
+            fi
+            ;;
         review)
             if [[ "$previous" == (--base|-m|--main) ]]; then
                 _bygone_git_refs
@@ -97,7 +109,7 @@ _bygone() {
             fi
             ;;
         present)
-            if [[ "$previous" == (--tour) ]]; then
+            if [[ "$previous" == (--tour) || "$previous" == "--correspondence" ]]; then
                 _files -g '*.bygone' -g '*.bygone.yaml'
             elif [[ "$previous" == (--base|-m|--main) ]]; then
                 _bygone_git_refs

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 --read-only -C -h --help -v --version' -- "$cur") $(compgen -f -- "$cur") )
+        COMPREPLY=( $(compgen -W 'evidence review dependencies correspondence 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
@@ -28,17 +28,25 @@ _bygone() {
                 refs="$(_bygone_git_refs)"
                 if [[ "$prev" =~ ^(--base|-m|--main)$ ]]; then
                     COMPREPLY=( $(compgen -W "$refs" -- "$cur") )
-                elif [[ "$prev" == "--output" || "$prev" == "-o" ]]; then
+                elif [[ "$prev" == "--output" || "$prev" == "-o" || "$prev" == "--correspondence" ]]; then
                     COMPREPLY=( $(compgen -f -- "$cur") )
                     compopt -o filenames 2>/dev/null || true
                 else
-                    COMPREPLY=( $(compgen -W '--base --output -o --max-patch-bytes --max-total-patch-bytes '"$refs" -- "$cur") )
+                    COMPREPLY=( $(compgen -W '--base --output -o --max-patch-bytes --max-total-patch-bytes --correspondence --dependencies '"$refs" -- "$cur") )
                 fi
             else
                 COMPREPLY=( $(compgen -W '--json --output -o' -- "$cur") $(compgen -f -- "$cur") )
                 compopt -o filenames 2>/dev/null || true
             fi
             ;;
+        dependencies)
+            if [[ "$prev" == "--output" || "$prev" == "-o" ]]; then
+                COMPREPLY=( $(compgen -f -- "$cur") )
+                compopt -o filenames 2>/dev/null || true
+            else
+                COMPREPLY=( $(compgen -W '--base --json --output -o '"$(_bygone_git_refs)" -- "$cur") )
+            fi
+            ;;
         review)
             refs="$(_bygone_git_refs)"
             if [[ "$prev" =~ ^(--base|-m|--main)$ ]]; then
@@ -49,13 +57,13 @@ _bygone() {
             ;;
         present)
             refs="$(_bygone_git_refs)"
-            if [[ "$prev" == "--tour" ]]; then
+            if [[ "$prev" == "--tour" || "$prev" == "--correspondence" ]]; then
                 COMPREPLY=( $(compgen -f -- "$cur") )
                 compopt -o filenames 2>/dev/null || true
             elif [[ "$prev" =~ ^(--base|-m|--main)$ ]]; then
                 COMPREPLY=( $(compgen -W "$refs" -- "$cur") )
             else
-                COMPREPLY=( $(compgen -W '--base -m --main --tour -h --help '"$refs" -- "$cur") )
+                COMPREPLY=( $(compgen -W '--base -m --main --tour --correspondence -h --help '"$refs" -- "$cur") )
             fi
             ;;
         --branch-diff)

package/completions/bygone.fish

@@ -4,7 +4,10 @@ function __bygone_git_refs
     printf "%s\n" HEAD INDEX WORKTREE
 end
 
+complete -c bygone -n '__fish_use_subcommand' -a evidence -r -d 'Inspect, import, refresh, or present pinned review evidence'
 complete -c bygone -n '__fish_use_subcommand' -a review -d 'Review a committed branch against its merge base'
+complete -c bygone -n '__fish_use_subcommand' -a dependencies -d 'Compare static JS/TS module dependencies at committed revisions'
+complete -c bygone -n '__fish_use_subcommand' -a correspondence -r -d 'Import externally produced symbol correspondence evidence'
 complete -c bygone -n '__fish_use_subcommand' -a completion -d 'Print shell completion source'
 complete -c bygone -n '__fish_use_subcommand' -a present -d 'Open an app-hosted tour of a committed branch range'
 complete -c bygone -n '__fish_use_subcommand' -a tour -d 'Validate, compile, or inspect authored change tours'
@@ -17,6 +20,11 @@ complete -c bygone -n '__fish_use_subcommand' -l read-only -d 'Open live Explore
 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'
+complete -c bygone -n 'string match -q "*tour context*" -- (commandline -opc)' -l dependencies -d 'Include static module dependency evidence'
+complete -c bygone -n '__fish_seen_subcommand_from dependencies' -l base -r -a '(__bygone_git_refs)' -d 'Set the dependency comparison base'
+complete -c bygone -n '__fish_seen_subcommand_from dependencies' -l json -d 'Print dependency evidence as JSON'
+complete -c bygone -n '__fish_seen_subcommand_from dependencies' -l output -s o -r -d 'Write dependency evidence'
+complete -c bygone -n '__fish_seen_subcommand_from dependencies' -a '(__bygone_git_refs)' -d 'Git ref'
 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 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'
@@ -30,6 +38,7 @@ complete -c bygone -n '__fish_seen_subcommand_from review' -l base -s m -l main
 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 .bygone presentation'
+complete -c bygone -l correspondence -r -d 'Use pinned symbol correspondence evidence'
 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-tour-format.md

@@ -8,16 +8,16 @@ 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, 4, and 5
+requires the corresponding local repository and Git objects. Version 2, 4, 5, and 6
 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 4 supports independent authored
 tours and scene directory overviews; versions 1 and 2 remain accepted without
 those fields.
 
-## Version 5 stability and compatibility
+## Version stability and compatibility
 
-Format version **5** is the current authoring contract. Application and document
+Format version **6** is the current authoring contract. Application and document
 versions are separate; UI fixes do not require rewriting a tour.
 
 | Document version | Reader support | Contract |
@@ -26,8 +26,9 @@ versions are separate; UI fixes do not require rewriting a tour.
 | 2 | Supported | Repository-bound manifests, real revision stacks, and endpoint walkthroughs |
 | 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 |
+| 5 | Supported | Optional opening, conclusion, and chapter previews; explicit overview purpose |
+| 6 | Use for new sources | Optional pinned symbol comparisons in walkthrough stops |
+| Greater than 6 | Rejected with an upgrade message | Never interpreted as version 6 |
 
 Version 4 removes the `review` field and the separate Review Notes panel.
 Concepts, boundaries, tradeoffs, and unresolved questions belong in scene or
@@ -49,7 +50,7 @@ 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/v4/v5 manifests retain repository identity and
+not a second authoring syntax; v2/v4/v5/v6 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
@@ -61,6 +62,59 @@ 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.
 
+## Symbol-focused stops
+
+Version 6 adds an optional repository-relative `correspondence` artifact and a
+`symbol` selector on walkthrough steps. Generate the artifact as described in
+[Symbol correspondence evidence](correspondence.md), then use an accepted
+relation ID or one unmatched symbol ID from its inventory:
+
+```yaml
+version: 6
+correspondence: evidence/symbols.json
+# Pin range.base and range.head to the artifact's comparison.
+anchors:
+  moved-declaration:
+    file: src/moved.py
+    revision: head
+    contains: "def transfer("
+# Within a walkthrough scene's steps:
+# - id: transfer
+#   title: Read the moved declaration
+#   body: Compare the complete declaration before and after the move.
+#   focus: moved-declaration
+#   symbol: { relation: relation-transfer }
+```
+
+The ordinary `focus` anchor remains required and must resolve inside the selected
+declaration on its revision side. It preserves source navigation and existing
+anchor validation. `symbol: { symbol: after-uncertain }` selects one unmatched
+endpoint instead. IDs are unique across the artifact's symbol inventory; matched
+endpoints must use their accepted relation ID. An ambiguous endpoint remains
+one-sided, with no invented origin. Symbol stops cannot also use an image or
+connection.
+
+Compilation revalidates the artifact against the exact Git comparison and
+embeds complete declaration text, source spans, revisions, and both full file
+contexts. The source artifact path must stay inside the repository, including
+through symlinks. Stale artifacts and selectors outside the chosen declaration
+are errors. An accepted relation is still an inferred correspondence; behavior
+remains unassessed.
+
+The viewer opens the declaration comparison. **Show file context** widens to the
+complete source and destination files, highlights both declarations, and keeps
+the current tour stop. **Return to symbol comparison** restores the slices;
+**Return to tour** restores the authored stop after exploring another file.
+The compiled evidence also works in an offline HTML export without the artifact
+or repository. Export packs repeated text once. Coverage counts only changed
+units intersecting either selected declaration, or the single available endpoint
+for an unmatched symbol; overlapping stops do not multiply coverage.
+
+Existing sources and ordinary anchor stops keep their existing behavior. Live
+presentations load the source's artifact into Symbols and Files automatically;
+offline exports retain the selected stops and their context, rather than the
+entire symbol inventory.
+
 ## Opening and conclusion passages
 
 Version 5 adds optional `opening` and `conclusion` at the document root and