@davmash/bygone 0.8.16 → 0.9.2

package/docs/change-tour-format.md

@@ -8,10 +8,56 @@ 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
+requires the corresponding local repository and Git objects. Version 2 and 3
 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.
+artifacts, without the mode switcher. Version 3 adds independent authored
+tours, scene directory overviews, and review notes; versions 1 and 2 remain
+accepted without those fields.
+
+## Version 3 stability and compatibility
+
+Format version **3 is the stable authoring contract for Bygone 0.9.2**. The
+application version (`0.9.2`) and document version (`version: 3`) are separate:
+UI fixes, navigation changes, and application patch releases do not require
+rewriting a tour or incrementing its format version.
+
+| Document version | Reader support in 0.9.2 | Contract |
+| --- | --- | --- |
+| 1 | Supported | Legacy source and portable compiled manifests |
+| 2 | Supported | Repository-bound manifests, real revision stacks, and endpoint walkthroughs |
+| 3 | Supported; use for new sources | Version 2 capabilities plus independent authored tours, scene directory overviews, and review notes |
+| Greater than 3 | Rejected with an upgrade message | Never interpreted as version 3 |
+
+The v3 field names, types, required fields, enum values, and meanings are fixed
+by the [source schema](../schemas/change-tour-source.schema.json) and the
+semantic rules in this document. Valid v3 sources and compiled manifests must
+remain readable by later compatible releases; required fields must not be
+added, existing fields removed, or evidence and mode semantics repurposed under
+the same format number. New syntax that existing v3 readers cannot accept
+requires a new document version, even when the new field is optional. Fixes
+that enforce the documented contract do not make malformed documents valid.
+
+The source is strict: unknown properties are errors, not an extension
+mechanism. JSON Schema covers document structure; `bygone tour validate`
+additionally checks IDs and references, Git objects, unique anchor matches,
+stage coverage, comparison endpoints, and review freshness. A schema-only pass
+does not prove that the source compiles. Validate against the intended local
+repository before sharing a tour.
+
+Keep authored YAML as the editable source. Compiled JSON is generated evidence,
+not a second authoring syntax; v2/v3 manifests retain repository identity and
+resolved Git objects. Stable format support does not make missing repositories
+or pruned objects available, and does not promise byte-identical generated
+timestamps or presentation layout. Pin full commit IDs in `range` when the
+underlying comparison must stay fixed.
+
+The compatibility checks cover v1/v2 acceptance, v3-only field gates,
+independent authored modes, overview evidence and fallback semantics, review
+freshness, and rejection of future versions. Run `npm test` before releasing a
+parser, compiler, or schema change; update those checks with any new contract.
+
+## Opening and compiling a source
 
 Packaged macOS builds register `.bygone` with Bygone, allowing a presentation
 inside its repository to open directly from Finder. Windows and Linux builds
@@ -40,10 +86,71 @@ The optional `windowTitle` sets the native window title for the tour presenter.
 Use a short label such as a pull request number when several tours may be open at
 once. When omitted, the presenter falls back to `title`, then a generic tour label.
 
+## Independent authored tours
+
+Version 3 can supply `tours.historical.chapters` and
+`tours.deconstructed.chapters`. Each uses the chapter and scene structure below,
+with the document's shared range, anchors, and connections. This lets one file
+explain actual revisions and also teach the change through synthetic stages.
+
+The required root `chapters` remain the compatible default tour. When a mode is
+not explicitly supplied, its authored content can come from those chapters:
+real walkthroughs and stacks supply Historical tour; deconstructed scenes supply
+Deconstructed tour. Explicit endpoint walkthrough steps on a deconstructed scene
+can supply Historical content, but a generated revision stack alone cannot.
+
+Historical tour accepts walkthroughs and real stacked diffs, including a stack
+with just two endpoints. It rejects synthetic deconstructed scenes.
+Deconstructed tour requires at least one deconstructed scene; other walkthrough
+scenes can add context and proof. Its synthetic stages do not need a matching
+authored historical step. Both modes retain their own chapter, scene, and step
+order; the presenter does not infer cross-tour mappings.
+
+See `examples/navigation-lab.bygone.yaml` for both tours in one file, and
+[presentation navigation](./present.md#explore-and-follow-tours) for History and
+Compare.
+
+## Scene directory overviews
+
+In version 3, an authored walkthrough, stacked-diff, or deconstructed-diff scene may carry a
+directory overview for the presenter to render alongside the current scene:
+
+```yaml
+overview:
+  kind: directory-diff
+  path: web
+```
+
+`path` is optional and is relative to the repository root. Omit it or use `.`
+for the root directory. Absolute paths, backslashes, and `..` path segments are
+rejected. The compiler preserves this evidence on the corresponding compiled
+scene in the root tour and any authored mode or fallback that contains it; it
+does not create a separate scene kind.
+
+The comparison is stable regardless of the saved step. Stacked and deconstructed
+scenes default to their first and last panels and compare only files materialized
+in those scene panels. Walkthroughs use the review's base-to-head comparison and
+its tour files, including omitted entries. Any of the three scene types can
+scope the overview to a subdirectory. For a narrower authored comparison, add:
+
+```yaml
+comparison:
+  from: before
+  to: hierarchy
+```
+
+Place `comparison` inside `overview`. For stacked scenes, endpoints are `stack`
+entry IDs. For deconstructed scenes, use `explanation-baseline` or
+`explanation-stage-<stage-id>`. Both endpoints must exist and differ. Walkthroughs
+reject this option. When a deconstructed scene produces a fallback Historical
+or walkthrough view, its synthetic endpoints are not mapped to real revisions:
+the fallback retains the directory scope and uses its default full comparison.
+Use an explicit authored Historical scene to choose a narrower real comparison.
+
 ## Structure
 
 ```yaml
-version: 2
+version: 3
 title: A reviewer-facing title
 windowTitle: PR-1234
 sourceUrl: https://example.test/pull/123
@@ -80,7 +187,7 @@ chapters:
         steps:
           - id: persist-first
             title: Persist the recommendation
-            body: This exact line establishes the ordering guarantee.
+            body: This exact line establishes the ordering guarantee before the side effect runs.
             focus: durable-decision
             connection: contract-to-write
             requirement:
@@ -91,6 +198,49 @@ chapters:
               confidence: high
 ```
 
+Scene fields provide framing: `summary` states the scene's purpose, `bullets`
+give supporting points, and `takeaway` states what the reader should retain.
+Step `body` is the canonical place for the evidence-specific explanation,
+including why the focused code matters and any rationale or tradeoff that the
+source supports. Keeping that explanation beside `focus` lets the reader assess
+the claim while the code is visible and avoids repeating it in scene framing.
+
+The source schema has no ad hoc `notes` field. In v3, use the top-level `review`
+block below for evidence-linked review observations and unresolved questions;
+do not present those questions as settled step rationale.
+
+## Review notes
+
+The optional v3 `review` block records authored interpretation separately from
+the narrative and deterministic evidence. It contains `baseOid`, `headOid`, and
+a nonempty `items` array. Both OIDs must be full 40- or 64-character hexadecimal
+Git IDs, matching the resolved **merge base** and head, respectively. A changed
+range makes the review stale and compilation fails rather than silently
+carrying the conclusions forward.
+
+Each item has a unique nonblank `id`, a `kind` (`concept`, `boundary`,
+`tradeoff`, or `question`), nonblank `title` and `body`, and an `evidence` array
+of `{ sceneId, stepId }` references to endpoint walkthrough steps in the root
+`chapters` (not scenes defined only inside an independent `tours` mode).
+Synthetic stage IDs and stacked-diff step IDs are not walkthrough evidence.
+Claims require at least one reference. Questions may use an empty evidence
+array but require a nonblank `nextCheck`; other items may also supply it.
+Validation confirms the references, not the truth of an author's claim or the
+state of an external deployment.
+
+For example, add this item to `review.items` alongside the structure above:
+
+```yaml
+- id: check-caller
+  kind: question
+  title: Is the caller compatible?
+  body: The source shows persistence, but the deployed caller has not been checked.
+  evidence:
+    - sceneId: decision-flow
+      stepId: persist-first
+  nextCheck: Verify the deployed caller contract against this exact head revision.
+```
+
 ## Requirements
 
 A walkthrough step may carry an optional `requirement` that names the stated
@@ -120,24 +270,26 @@ 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.
+Version 2 and 3 tours show one mode control for moving among live Git History,
+arbitrary Compare ranges, and the authored tours available in that manifest.
+Previously compiled version 2 deconstructed tours retain their authored final
+endpoint walkthrough as **Final tour** beside **Deconstructed tour**. Other
+version 2 tours appear as **Historical tour**, while their endpoint comparison
+remains available through **Final diff** in Compare. Each mode retains its own
+location; switching back 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. 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.
+commits. In versions 2 and 3, a `deconstructed-diff` scene in root `chapters`
+requires a real `stack` with the same base and final endpoints and nonempty
+walkthrough `steps` for compatibility. In version 3, a scene authored inside
+`tours.deconstructed` may omit both because that tour is synthetic by design.
+Explicit `tours.historical` content supplies its own explanation of real
+revisions. Bygone does not infer a real stack from Git history. Every changed
+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/generating-change-tours.md

@@ -30,9 +30,10 @@ The skill documents how to install Bygone itself when the CLI is missing.
 3. Identify the small set of reviewer questions that explain why the change exists and how it works.
 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` source.
-8. Validate it and repair every reported problem:
+6. Put the reason the focused code matters, including any evidence-grounded tradeoff, in that step's `body`.
+7. Add a connection only when it explains a meaningful relationship between two pieces of evidence.
+8. Write the `.bygone` source.
+9. Validate it and repair every reported problem:
 
    ```sh
    bygone tour validate review.bygone --json
@@ -53,10 +54,12 @@ Use `bygone tour schema` to print the current JSON Schema. The checked-in schema
 - Lead with contracts, invariants, or architectural boundaries before their consumers.
 - Pair behavior with the tests or evidence that prove it.
 - Keep mechanical, generated, and lockfile changes out of the authored narrative unless they alter the reviewer’s conclusion; they remain visible in the complete Files rail.
-- Make each annotation explain why the focused code matters; do not merely paraphrase its syntax.
+- Make each step body explain why the focused code matters, including a concise rationale or tradeoff when the source supports one; do not merely paraphrase its syntax.
+- Use scene summary, bullets, and takeaway for the scene's purpose and retained point. Do not repeat step bodies there when the step already carries the explanation.
 - Avoid claims about runtime behavior, safety, or intent that have no linked evidence.
 - Use connections sparingly. A connection should answer “how are these two facts related?”
 - Preserve access to the complete change instead of presenting the tour as exhaustive review.
+- In a version 3 source, keep unresolved questions and review decisions in the top-level `review` block rather than presenting them as settled scene narration.
 
 ## Anchor rules
 
@@ -68,20 +71,70 @@ Use `bygone tour schema` to print the current JSON Schema. The checked-in schema
 
 ## Suggested generation prompt
 
+The missing-tour buttons in History and Compare supply a short handoff like:
+
 ```text
-Create a Bygone change tour for the supplied Git range.
-
-First identify the central reviewer questions and the concrete code evidence for each answer.
-Then produce YAML conforming to the schema returned by `bygone tour schema`.
-
-Requirements:
-- pin the exact base and head commits;
-- organize the narrative by concepts, not filenames;
-- link every step to a unique source snippet;
-- connect code locations only when the relationship adds explanatory value;
-- include behavior and its proof;
-- leave secondary files to Bygone's complete Files rail;
-- run `bygone tour validate <file> --json` and repair all errors before finishing.
+Read and follow the Bygone tour skill at /path/to/SKILL.md.
+Create a v3 deconstructed tour for /path/to/repository, from <base OID> to <head OID>.
+Scope: <selected paths, or the whole repository>.
+Additional context: …
 ```
 
+The desktop supplies the actual installed Markdown path; the instructions are
+outside the application archive so local coding agents can read them. Use
+**Read instructions** to inspect the Markdown, **Save an editable copy** to fork
+it, and **Use my copy** after editing your file or adding project-specific context.
+Re-select a file after editing it to refresh the displayed instructions. Copies
+belong to you and are not overwritten by application updates.
+
+Browser prompts refer to an attachment instead of inventing a local filesystem
+path. Download the Markdown and attach it with the prompt. Do the same when using
+a desktop prompt with an agent that cannot access local files. The UI never
+invokes an agent automatically. Edited prompt drafts survive instruction changes;
+use **Reset prompt** to regenerate their file reference and workspace context.
+
 The generated prose remains a proposal. Validation proves that its evidence exists and is reproducible; a reviewer must still judge whether its interpretation is correct.
+
+## Optional review notes
+
+A version 3 authored source may add a top-level `review` block when a reviewer needs a
+small set of concepts, boundaries, tradeoffs, or open questions alongside the
+walkthrough. This is opt-in: the Present header shows a **Review notes** button
+only when the compiled manifest includes review notes, and the button opens a
+read-only panel. The panel is an authored interpretation layer; its linked
+scene/step evidence is checked, while its conclusions remain claims for the
+reviewer to assess. The complete Files rail remains available and unchanged.
+
+Review notes pin the exact range they describe:
+
+```yaml
+review:
+  baseOid: 292fe9248c5c49f762489dc688296fc100d120bc
+  headOid: 75b6d7c0303124ec314aa790d6b808c4a9d9ea0e
+  items:
+    - id: range-contract
+      kind: concept
+      title: The range has one historical boundary
+      body: The note explains the invariant a reviewer should keep in mind.
+      evidence:
+        - sceneId: review-pipeline
+          stepId: establish-boundary
+```
+
+Each item uses one of `concept`, `boundary`, `tradeoff`, or `question`.
+Concept, boundary, and tradeoff items need at least one link to an existing
+walkthrough scene and step. A question may leave `evidence` empty, but it must
+include a `nextCheck` describing the follow-up that would resolve it. Evidence
+resolves against the **Final walkthrough**. If the reader is in history or a
+revisions view, following an evidence link first returns to that final range
+before selecting the scene and step.
+
+The `baseOid` pin is the resolved merge-base OID, which may differ from the
+requested base ref; `headOid` is the resolved head OID. Both pins must match
+the resolved range. Compilation rejects a review whose pins describe a changed
+range, and imported manifests reject a review whose pins do not match the
+manifest range. `tour validate` checks the shape, OIDs, and scene/step
+grounding of review notes; it does not verify that an authored interpretation
+is semantically correct. It also does not run or attest to external checks such
+as tests, CI, or the `nextCheck` follow-up. Those claims belong in the note only
+when the author has evidence for them.

package/docs/present.md

@@ -9,25 +9,124 @@ source evidence while keeping the complete changed-file set available.
   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.
+  skip** first-pass reading hints. Continue through the reading flow to reach
+  the recommended file.
 - **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.
+The left navigator switches directly among **Tour**, **Files**, and **Commits**;
+only one of those lists is visible at a time. The Tour outline has independently
+collapsible chapters and scenes; selecting a title jumps to that reading stop
+without changing which sections are expanded.
+
+The reading panel flows continuously through the tour title, chapters, scene
+overviews, and steps. Scroll the narrative or use keyboard navigation to move
+through that order; the corresponding code evidence follows. Scrolling the code
+does not advance the narrative. Each scene overview is a distinct stop with its
+supporting points and takeaway. Each step keeps a collapsed **Scene context**
+disclosure above its title and explanation. Expanding that disclosure does not
+move the reading position.
+
+A direct link to a step opens that step immediately. The header reports the
+current position as `Scene N of M · Step N of M`, or identifies the overview.
+The reading panel scrolls within a bounded area above the evidence; no Start,
+Resume, or Previous/Next buttons interrupt the flow. Returning from History or
+Compare restores the tour's saved reading position. On narrow screens, the
+navigator becomes an overlay instead of stacking another permanent region
+above the diff.
+
+The code view uses the available width for an added or deleted file when only
+one side is present. An empty **Present** view keeps the regular split layout.
+When the current step has an exact source target, **Show in code** refocuses the
+corresponding file and line.
+
+Choose **Files** in the navigator to browse the complete change set without
+changing the active tour position. While reading a step, browsing another file
+keeps the active tour anchor visible; **Return to Tour** restores the scene's
+intended focus. While a directory **Overview** is active, files open in its
+comparison and files outside that comparison are disabled. Opening a file keeps
+the overview text and reading position. Select **Overview** above the diff to
+return to the tree, or continue through the narrative to the next step.
+
+**Tour details** is available on demand and contains the source link, range,
+change counts, and authored diff-hunk coverage. Coverage describes how much
+code the author anchored; it does not measure your reading progress. The
+header shows your current step. Tour search is likewise disclosed on demand or
+opened by `Cmd/Ctrl+Shift+F`.
 
 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.
 
+## Explore and follow tours
+
+Version 2 and 3 presentations expose **History**, **Compare**, and the available
+authored tours as direct mode buttons.
+Independent Historical and Deconstructed tours require version 3:
+
+- **History** uses all commits reachable from the presentation's head, in stable
+  topological order, including commits that did not change the current file.
+  Left/right moves through commits; up/down moves through the Files list without
+  changing the loaded revisions. History starts with a commit and the preceding
+  commit on this axis (or the empty tree). Panel `+` controls expand into
+  older or newer revisions; `×` removes a panel, with a minimum of two. Returning
+  from Compare restores the expanded History workspace. Activating a loaded
+  revision focuses its panel; another revision moves the history window while
+  retaining its panel count where older history is available. Shortcuts compare
+  the active revision with its parent or the review base.
+- **Compare** shows one panel per selected revision, oldest to newest, with a
+  diff between each adjacent pair. The Commit navigator remains available for
+  editing a draft selection; **Update comparison** applies it. Activating a loaded revision focuses its
+  panel. **Compare selected** includes all changed files. Parent/base shortcuts
+  stay on the current file; **Show all changed files** expands the same range.
+  **Final diff** selects the review base
+  and head across all changed files.
+
+All modes share the expanded **Commits** navigator. Check two or more revisions,
+then choose **Compare selected** (or **Update comparison** in Compare).
+Checkboxes edit a shared draft without reloading panels or leaving the tour.
+Numbered badges and highlights identify loaded real revisions independently of
+that draft. A dot marks commits that changed the current file, following renames;
+the **Tour** tag identifies commits in the authored range. Synthetic explanation
+stages are not labeled as Git revisions. Parent/base revisions outside the
+commit list appear as labeled extra rows.
+**Clear selection** unchecks draft revisions without changing modes or panels;
+**Reset selection** selects the real revisions currently loaded in the workspace.
+
+- **Historical tour** explains actual revision states, including intermediate
+  changes, updates, and reverts. It retains chapters, scenes, steps, and narration.
+- **Deconstructed tour** explains the change through authored, synthetic
+  cumulative stages. Its panels are explanation stages, not Git commits.
+
+Previously compiled version 2 deconstructed tours retain their separate
+authored **Final tour** alongside the synthetic stages. Existing `mode=final`
+links open that walkthrough; other final-diff links open Compare at the review
+endpoints.
+
+Only available authored tours appear. A real revision stack does not by itself
+create a Historical tour. Each mode remembers its own reading or browsing
+position and navigator tab during the session; entering a tour for the first time starts at its
+beginning. Entering History for the first time keeps the file currently being
+inspected; later returns restore History's own file and revision. Switching
+modes does not infer a corresponding step in another tour.
+The active tour position or comparison is also reflected in the URL for refresh.
+
+While reading a step, expand **Scene context** beneath it to keep the scene's
+summary, supporting points, and takeaway visible without leaving the step.
+
 ## Listen to a tour
 
-Use **Listen** in the narrative header or **Present → Listen to Tour** in the
+Use **Listen** beside the reading breadcrumb or **Present → Listen to Tour** in the
 desktop app to read the tour aloud with a device voice. Narration works
 offline and does not send tour text to a hosted speech service.
 
+Narration controls are available from **‹ Narration** beside the reading
+breadcrumb, with sentence navigation, Stop, voice, and speed. Use the
+right-edge chevron to collapse them again. Listen becomes Pause or Resume
+during playback. The overview opens when its
+text is spoken so the highlighted sentence remains visible.
+
 - **Pause/Resume** retains the current sentence; **Stop** clears playback. The
   outer jump controls move one sentence backward or forward within the current
   narration item.
@@ -64,6 +163,11 @@ conversation. Those remain separate from the offline, device-first baseline.
 Tour content is read-only. Author or revise the YAML and recompile it rather
 than editing historical or synthetic panels in the presenter.
 
+Version 3 authored tours may expose a separate, read-only **Review notes** panel
+for evidence-linked concepts, boundaries, tradeoffs, and open questions. Scene
+and step narrative should still explain the implemented change and the tradeoffs
+supported by its evidence.
+
 ## Authoring workflow
 
 Use the CLI or the repository's tour-generation skill:
@@ -79,3 +183,20 @@ 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.
+
+### Directory evidence in an Overview
+
+In version 3, an authored scene can show a directory comparison in its Overview. Open a file
+to inspect the same comparison while keeping the overview text, narration, and
+reading position. The **Overview** breadcrumb returns to its file tree;
+scroll through the narrative or select a step in the outline to continue the
+authored explanation.
+
+Stacked and Deconstructed scenes use a stable comparison: by default, the first
+and last scene panels, or explicit endpoints chosen by the author. Moving between
+steps never changes this comparison. The column labels identify its endpoints.
+Their overviews include only files materialized in the scene panels.
+Walkthrough scenes use the review's base-to-head comparison and the tour files,
+retaining omitted-file entries. Any scene type can limit the overview to a
+subdirectory. While browsing a file, `Overview › file path` shows where you are,
+with a reminder that narration still describes the overview.

package/docs/product-surface.md

@@ -9,7 +9,7 @@ or materially changed.
 - **Explore — desktop:** open-ended file, directory, history, revision,
   multi-panel, and branch-change investigation.
 - **Present — desktop/browser:** generated and authored tours with narrative,
-  exact source evidence, and an independent changed-files rail.
+  exact source evidence, and one task navigator for Tour, Files, or Commits.
 - **VS Code companion:** contextual file comparison and file history near the
   current editor. Repository-, directory-, multi-panel-, and tour-scale work
   should hand off to desktop.
@@ -21,6 +21,45 @@ or materially changed.
 The shared Monaco renderer supplies diff semantics and presentation. Sharing a
 renderer does not make every workflow appropriate in every host.
 
+## Shared workspace
+
+Desktop Explore uses **History · Compare · Historical tour · Deconstructed
+tour** without requiring an authored document. Missing tour buttons open an
+short, editable prompt referencing the bundled v3 tour skill and the workspace's
+repository, revisions, and selected paths. Read instructions exposes the Markdown;
+Save an editable copy and Use my copy support user-owned forks. Desktop prompts
+reference a real filesystem path outside the application archive. Browser prompts
+name a Markdown attachment to download and supply alongside the prompt; selecting
+a local file does not disclose its full path. Custom instructions and prompt drafts
+stay in the current workspace; edited prompts are preserved with a reset notice
+when the selected instructions change. No model request or shell command runs
+automatically. Prompt ranges use exact committed identities or explicitly ask for
+a range choice. Existing tour loading remains available.
+
+**Open in History** resolves the comparison's Git ownership and path scope.
+Its commit axis includes the selected revisions and their ancestry, including
+commits that did not change the active file. File-change markers and numbered
+active panels are distinct from unapplied comparison checkboxes. Clear clears
+the draft without changing modes. History retains add/remove-panel controls.
+**Back to comparison** restores the originating ordered comparison and its
+navigation. Mode transitions use the native unsaved-edit guard; writable
+working files remain writable and explicit read-only launches stay read-only.
+
+Opening an authored document from this workspace keeps the same native window.
+A different repository, range, or scoped context requires confirmation; the
+tour is read-only and the original comparison remains available. Explicit
+Present launches may use their dedicated window. Browser tour uploads are
+validated within the presentation server's existing repository and do not
+acquire local-path or desktop-write capabilities. VS Code retains its desktop
+handoff boundary.
+
+Legacy v1 presentations retain their authored tour and missing-tour help;
+History and Compare explain that a v2-or-newer repository backend is required.
+
+Verification: `test/workspace*.test.js` and the native
+`--smoke-test-workspace` launch exercise ownership, range safety, restoration,
+prompt behavior, and the normal-mode controls.
+
 ## Standalone Explore
 
 | User question | Discovery and launch | Session/source | Mutability and lifecycle | Maturity | Verification |
@@ -46,17 +85,30 @@ 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 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 |
+| 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 navigator | 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 |
+| Read optional authored review notes | Browser or desktop Present shows an opt-in **Review notes** button when a v3 manifest includes `review` | `baseOid`/`headOid` pins and evidence links into the Final walkthrough | Immutable range; read-only panel; no scores or persisted reviewer state | Local prototype | `examples/bygone-history.bygone`, `test/reviewNotes.test.js`, and manual browser navigation check |
+| Assess authored tour coverage | Coverage indicators in the Present sidebar | Distinct hunks referenced by authored walkthrough anchors; v2/v3 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/v3 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` |
-| Browse away from the narration | Files rail, change navigation | Browsed file versus active tour focus remain distinct | Read-only; Return to Tour restores narrative focus | Core | tour focus and persistent-anchor tests |
+| Browse away from the narration | Files navigator, change navigation | Browsed file versus active tour focus remain distinct | Read-only; Return to Tour restores narrative focus | Core | tour focus and persistent-anchor tests |
+| Browse commits or build a comparison while reading | Shared Commits navigator in every mode; check revisions, then Compare selected | All commits reachable from the presentation head; separate file-change markers, tour membership, and numbered loaded panels | Read-only snapshots; checkbox draft does not navigate; History preserves revision columns across files | Core | tour-history backend, stable-axis workspace tests, and browser mode-transition checks |
 
 Tour authoring remains file/CLI/agent driven. The desktop UI opens and presents
 tours but does not attempt to duplicate schema-aware authoring forms.
 
+Tour reading is one continuous document: title, chapter headings, scene
+overviews, and steps. Scrolling the narrative selects the active passage and
+its source evidence; scrolling code does not advance the narrative. The
+sidebar is a collapsible outline with separate disclosure and jump controls.
+Scene overviews are independent reading stops, and each step includes a
+collapsed scene-context disclosure above its text. Opening that disclosure
+does not navigate. Keyboard previous/next follows the same document order;
+History/Compare round-trips restore the passage and reading scroll position.
+There are no title-screen, start-steps, or resume gates. Verification:
+`test/tourReading.test.js` and `standalone/tourReadingSmoke.js`.
+
 ## VS Code companion
 
 | Command | Intended ownership | Current state | Editing contract | Follow-up |