@davmash/bygone 0.8.14 → 0.9.2

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 |
@@ -30,7 +69,7 @@ renderer does not make every workflow appropriate in every host.
 | Compare directories | File → Compare Directories; drag/drop; two or more directory arguments | Directory comparison | Directory rows are read-only; writable file drill-down depends on source/review state | Core | directory smoke and directory-diff tests |
 | Follow one file or directory through Git | File → View File or Directory History; one path; `--history` | Git commits plus supported index/worktree states | Commits are read-only; worktree/index provenance is explicit | Core | Git history and directory-history tests |
 | Compare named revisions | Git → Compare Revisions; `bygone --git-diff <refs…>` | Git blobs/revisions | Read-only snapshots | Core | Git comparison tests and desktop menu contract |
-| Explore a branch change | Git → Review Branch Change; `bygone review` | Merge-base-to-tip branch inventory for a selected head and optional base | Read-only review snapshots; dirty state is reported, not silently included | Core | branch comparison, review-path, and desktop menu tests |
+| Explore a branch change | Git → Review Branch Change; `bygone review` | Deterministic start-here overview plus the complete merge-base-to-tip inventory | Read-only review snapshots; attention is a reading-order hint, viewed state remains session-local, and dirty state is reported rather than included | Core | attention-model, branch comparison, review-path, and desktop menu tests |
 | Search comparison code | Edit → Find or Search Comparison | Active, visible, all loaded panels, unopened changed text snapshots, or one file's Git history | Search is read-only; history distinguishes content occurrence from introduction/removal; Replace requires the active writable model | Core | find, comparison-search, change-set-search, and history-search tests |
 | Search or safely replace in a filesystem tree | Edit → Search in Files; explicit directory root | System ripgrep 14+ with include/exclude, hidden, ignore, and result-limit controls | Search is read-only and cancellable; completed case-sensitive literal searches can build an exclusion-aware, revalidated, atomic replacement preview with guarded undo | Optional system capability | repository search/replace contracts, benchmark, and host-protocol tests |
 | Move through a multi-panel comparison | Strip buttons, panel headers, gutters, wheel, or `Alt+Arrow` | Active panel and adjacent pair | Does not change source identity | Core | focused-strip controller and standalone smoke tests |
@@ -46,16 +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 for the current or selected head/base | Read-only | Core | presentation launch, generated-tour, and desktop menu tests |
+| Explain a branch automatically | Present → Present Current Branch or Present Branch or Ref; `bygone present` | Committed merge-base-to-tip range with a deterministic overview first scene and complete Files 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 |
+| 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 |
@@ -78,22 +131,25 @@ VS Code's native Search rather than another bundled ripgrep process.
 
 | Surface | Purpose | Mutability/maturity |
 | --- | --- | --- |
-| `bygone`, paths, `--diff`, `--history`, `--git-diff`, `review` | Launch Explore sessions | Core launcher; desktop owns writes |
+| `bygone`, paths, `--diff`, `--history`, `--git-diff`, `--read-only`, `review` | Launch Explore sessions | Core launcher; desktop owns writes; `--read-only` is a persisted capability ceiling for that launch |
 | `present` and `present --tour` | Launch Present sessions | Core, read-only presentation |
 | `tour context` | Produce a bounded provider-neutral change dossier | Authoring support, read-only |
-| `tour validate`, `compile`, `schema`, and coverage options | Validate exact evidence and build portable manifests | Advanced authoring, read-only except explicit output files |
+| `tour validate`, `compile`, `schema`, and coverage options | Validate exact evidence and build repository-bound manifests | Advanced authoring, read-only except explicit output files |
 | `completion` | Generate shell completions from the shared command specification | Supporting tooling |
 
 ## Provenance and mutability vocabulary
 
 Use these labels consistently:
 
-- **Writable file:** filesystem/worktree content participating in dirty, undo,
+- **Writable file:** filesystem content and a live `WORKTREE` column participating in dirty, undo,
   save, reload, watcher, and refresh behavior.
+- **Read-only file:** live filesystem content intentionally opened with editing
+  disabled; external changes and explicit session refresh remain available.
 - **Read-only snapshot:** committed Git, history, tour, or supplied content that
   cannot be replaced or saved over a source file.
 - **INDEX** and **WORKTREE:** repository work states; do not describe them as
-  commits.
+  commits. `INDEX` is a read-only snapshot; `WORKTREE` is live and writable in
+  revision comparisons unless the launch uses `--read-only`.
 - **Explanation stage:** synthetic deconstructed content; never imply that it
   is a real commit.
 - **Real revision:** a panel resolved from an exact Git object identity.

package/docs/releasing.md

@@ -23,7 +23,6 @@ Publish everything:
 
 ```bash
 export BYGONE_HOMEBREW_TAP=/path/to/homebrew-tap
-npm whoami
 gh auth status
 npm run release:publish
 ```
@@ -34,10 +33,9 @@ aborts unless the worktree is clean and the current branch is `main`, pushes
 installs the artifacts locally, then publishes npm, GitHub, and Homebrew.
 The Homebrew tap defaults to the sibling `homebrew-bygone` checkout; set
 `BYGONE_HOMEBREW_TAP` only when the tap is elsewhere.
-If npm authentication is missing, the command launches browser login. For an
-unpublished version, it checks authentication again and pauses immediately
-before `npm publish`; press Enter only when ready to complete npm's time-limited
-passkey prompt.
+Creating the GitHub release pushes the version tag. That tag starts the
+protected Release workflow, which waits for approval and publishes npm through
+OIDC trusted publishing without a long-lived npm token.
 
 Upload `bygone-<version>.vsix` from the Visual Studio Marketplace publisher
 page. GitHub OIDC support has merged into `vsce`, but Marketplace has not yet
@@ -62,12 +60,11 @@ The main scripts are:
   - requires a clean `main` worktree
   - pushes `main` and waits for that commit's GitHub Release Check workflow
   - rebuilds and installs the release locally, including a graceful desktop restart
-  - logs into npm when needed and pauses immediately before the interactive npm publish challenge
-  - publishes npm
   - creates a GitHub release with desktop artifacts
+  - triggers the protected GitHub Actions workflow that publishes npm through OIDC
   - updates and pushes the Homebrew tap
 - `npm run release:publish:npm`
-  - publishes only the staged npm package
+  - manual fallback that publishes only the staged npm package
 
 Related packaging commands:
 
@@ -91,17 +88,16 @@ You need accounts on three services:
 
 ### 1. npm
 
-This is required for publishing the standalone package.
+This is required for publishing the standalone package. Routine releases use
+npm trusted publishing from GitHub Actions, so no npm token is stored in the
+repository.
 
 - Sign up: [npm signup](https://www.npmjs.com/signup)
 - Docs: [npm getting started](https://docs.npmjs.com/getting-started)
 
-After creating the account:
-
-```bash
-npm login
-npm whoami
-```
+Configure `@davmash/bygone` with a trusted publisher for the
+`davidmashburn/bygone` repository, the `release.yml` workflow, and the
+`npm-publish` environment.
 
 ### 2. GitHub
 
@@ -165,17 +161,12 @@ This repository should contain the tap structure used by the release script:
 - `Formula/`
 - `Casks/`
 
-### 1. npm authentication
-
-```bash
-npm whoami
-```
-
-If that fails:
+### 1. npm trusted publishing
 
-```bash
-npm login
-```
+The npm package must trust `.github/workflows/release.yml` in
+`davidmashburn/bygone`, scoped to the `npm-publish` environment. The GitHub
+environment should require a reviewer so pushing a tag does not publish by
+itself.
 
 ### 2. GitHub authentication
 
@@ -305,9 +296,11 @@ npm run release:publish
 
 This runs the full publish path:
 
-1. `npm publish dist/npm-package --access public`
-2. `gh release create v<version> ... --notes-file CHANGELOG.md`
-3. update, commit, and push the Homebrew tap
+1. `gh release create v<version> ... --notes-file CHANGELOG.md`
+2. the pushed tag starts `.github/workflows/release.yml`
+3. after environment approval, Actions validates the tag and package metadata,
+   runs `npm run release:check`, and publishes `dist/npm-package` through OIDC
+4. update, commit, and push the Homebrew tap
 
 Publish the VS Code extension separately by uploading the already-built
 `bygone-<version>.vsix` through the Marketplace publisher page.
@@ -344,10 +337,13 @@ The repository-local packaging notes are also in:
 
 Check:
 
-- `npm whoami`
 - `gh auth status`
 - `echo $BYGONE_HOMEBREW_TAP`
 
+If the GitHub release succeeds but npm publishing does not, inspect the Release
+workflow and confirm that both the GitHub `npm-publish` environment and npm
+trusted-publisher configuration match `.github/workflows/release.yml`.
+
 ### VS Code publishing is not automated
 
 This is currently intentional. `vsce` has merged GitHub OIDC support, but the

package/examples/bygone-history.bygone

@@ -1,10 +1,52 @@
-version: 1
+version: 3
 title: How Bygone learned to review a branch
 sourceUrl: https://github.com/davidmashburn/bygone/commit/75b6d7c0303124ec314aa790d6b808c4a9d9ea0e
 range:
   base: 292fe9248c5c49f762489dc688296fc100d120bc
   head: 75b6d7c0303124ec314aa790d6b808c4a9d9ea0e
 
+review:
+  baseOid: 292fe9248c5c49f762489dc688296fc100d120bc
+  headOid: 75b6d7c0303124ec314aa790d6b808c4a9d9ea0e
+  items:
+    - id: merge-base-contract
+      kind: concept
+      title: Merge-base defines the reviewed history
+      body: "resolveBranchReviewRange selects one merge base, then derives changed paths and commits from that boundary. The review is the merge-base-to-head story."
+      evidence:
+        - sceneId: review-pipeline
+          stepId: establish-boundary
+        - sceneId: review-pipeline
+          stepId: lock-the-semantics
+    - id: git-directory-boundary
+      kind: boundary
+      title: Git-specific work ends at two trees
+      body: "The Git layer discovers the range and materializes snapshots; FileComparator then hands those temporary roots to the ordinary directory comparison. A reader needs the range model before the reusable directory surface is meaningful."
+      evidence:
+        - sceneId: review-pipeline
+          stepId: make-range-portable
+        - sceneId: review-pipeline
+          stepId: turn-history-into-files
+        - sceneId: review-pipeline
+          stepId: reuse-the-diff-surface
+    - id: setup-owns-complexity
+      kind: tradeoff
+      title: Review support moves complexity into range and snapshot setup
+      body: "Reusing directory comparison avoids a branch-only renderer, while range resolution and temporary snapshot creation add complexity before that renderer."
+      evidence:
+        - sceneId: review-pipeline
+          stepId: establish-boundary
+        - sceneId: review-pipeline
+          stepId: turn-history-into-files
+        - sceneId: review-pipeline
+          stepId: reuse-the-diff-surface
+    - id: partial-materialization-cleanup
+      kind: question
+      title: Does a failed materialization clean up both temporary roots?
+      body: "The focused walkthrough follows the successful handoff, but it does not prove cleanup when git show fails after one root has been partially populated."
+      evidence: []
+      nextCheck: "Inspect the preparation-error path and add a fault-injection fixture only if a failed materialization leaves either temporary root behind."
+
 anchors:
   choose-merge-base:
     file: src/gitComparison.ts
@@ -47,34 +89,34 @@ chapters:
     scenes:
       - id: review-pipeline
         title: From Git history to a visual workspace
-        summary: Follow the branch-review feature through its historical boundary, portable model, presentation seam, and proof.
+        summary: Follow the branch-review feature from its historical boundary to the reusable comparison surface and the test that fixes its semantics.
         bullets:
-          - The comparison starts at merge-base rather than whichever ref happens to be named as the base.
-          - Git-specific work ends once two temporary trees have been materialized.
-          - Existing directory comparison then provides navigation and drill-down without a second renderer.
+          - Resolve the range before materializing files for the comparison.
+          - Keep Git-specific preparation at the temporary-tree handoff.
+          - Read the fixture as a proof of range semantics, separate from the renderer.
         tags: [git, architecture, dogfood]
         takeaway: Bygone reviews its own history using the same boundary it introduced in this commit.
         steps:
           - id: establish-boundary
             title: Establish the historical boundary
-            body: The review represents everything introduced since the branch diverged, including changes made around merges.
+            body: Using the unique merge base makes the review start at branch divergence; the resolver rejects multiple merge bases instead of silently choosing one.
             focus: choose-merge-base
           - id: make-range-portable
             title: Describe the review as data
-            body: Changed paths and commits are collected into a range that neither renderer needs to rediscover.
+            body: BranchReviewRange carries changed paths and commits once, so the renderer can consume prepared history rather than rediscovering Git state.
             focus: describe-range
           - id: turn-history-into-files
             title: Materialize two review trees
-            body: The Git-specific layer creates base and head snapshots for only the changed paths.
+            body: Materializing only changed paths creates the two snapshots the diff can read; the temporary roots add setup and cleanup around the read-only comparison.
             focus: materialize-boundary
             connection: range-to-snapshot
           - id: reuse-the-diff-surface
             title: Reuse directory comparison
-            body: VS Code hands those snapshots to Bygone's existing directory workflow instead of introducing a branch-only view.
+            body: Passing the roots to compareDirectories keeps branch review on the established directory workflow, so navigation and drill-down are reused instead of implemented in a branch-specific renderer.
             focus: open-review-surface
             connection: snapshot-to-surface
           - id: lock-the-semantics
             title: Prove the range starts at divergence
-            body: The test creates a real repository and asserts the selected merge base, changed paths, and commits.
+            body: The fixture asserts the merge base, changed paths, and commit count; renderer behavior needs separate checks.
             focus: prove-merge-base
             connection: semantics-to-proof