pi-studio 0.9.63 → 0.10.1

package/README.md

@@ -1,212 +1,127 @@
 # pi-studio
 
-Extension for [pi](https://pi.dev) that opens a local two-pane browser workspace for working with prompts, responses, live working details, Markdown and LaTeX documents, interactive HTML previews, code files, REPL sessions, and other common text-based files side by side. Annotate responses and files, add local comments, write, edit, run prompts, send code to a REPL, browse prompt and response history, request critiques, and use live preview for code, Markdown, LaTeX, and interactive HTML.
-
-See [`ROADMAP.md`](./ROADMAP.md) for the current release plan.
-
-## Quick demo
-
-[Watch the 2-minute demo (MP4, 2x speed, no audio)](https://github.com/omaclaren/pi-studio/releases/latest/download/pi-studio-demo-2min.mp4)
-
-_The video shows an earlier version of the Studio interface. The basic workflow is the same, but there have been minor UI changes since it was recorded; the screenshots show the more recent version._
+A browser workspace for [Pi](https://pi.dev). Write and run prompts, read responses with rendered math and diagrams, edit and annotate documents, and follow what Pi is doing, side by side.
 
 ## Screenshots
 
-**Dark workspace**
-
-![Pi Studio workspace (dark)](./assets/screenshots/dark-workspace.png)
-
-**Light workspace**
-
-![Pi Studio workspace (light)](./assets/screenshots/light-workspace.png)
-
-**Zen mode**
-
-![Pi Studio Zen mode (dark)](./assets/screenshots/dark-zen.png)
-
-**Zen mode with a custom theme and rendered code preview**
-
-![Pi Studio Zen mode with custom theme and rendered code preview](./assets/screenshots/theme-zen-code.png)
-
-## What it does
-
-- Opens a two-pane browser workspace: **Editor** + **Response/Working/Editor Preview/Quarto Preview/Side questions**, side by side by default
-- Lets you choose a persisted pane layout from **View → Workspace**: side by side, Editor above, or Response above; the same divider resizes width or height and either pane can still be focused independently
-- Supports one canonical full Studio view per Pi session, plus additional editor-only companion views when you want extra editing/preview surfaces; editor-only views can also browse files and use the Studio REPL send controls without taking over the full Studio session view
-- Includes a global **Zen** mode that hides the Studio header and secondary chrome without changing the current pane layout; the header can also be hidden independently and restored from the top-right edge
-- Runs editor text directly, asks for structured critique (auto/writing/code focus), offers explicit **Show me** actions for a one-turn compact visual or structural explanation of the editor selection/document, displayed response, or current conversation topic, provides a manual **Suggest completion** action for short cursor-aware continuations (`Option/Alt+Tab` where available or `Cmd/Ctrl+Shift+Space` from the editor, `Tab` to insert a visible suggestion) with an optional editor-plus-latest-response context mode, or opens **Quiz me** for a Studio-native active-recall loop over the current editor text, selection, current file, folder, or repo, with optional focus guidance for shaping question selection
-- Treats text copied from or staged in Pi's terminal input editor as a linked draft: ordinary Studio edits retain the link, and an accepted **Run editor text** clears the terminal draft only when it has not changed in the meantime; a confirmed **Clear Pi editor text…** action remains available explicitly
-- Adds a right-pane **Side questions** thread for contextual questions that stay outside the main Pi conversation unless explicitly promoted. It can start with the editor selection, the Markdown/LaTeX heading block at the cursor, nearby unstructured text, the whole editor, the displayed response, or no starting text; independently, it can use read-only tools to map, search, and read the document folder, repository, or another chosen folder—including extracted PDF, DOCX, ODT, and EPUB text—and can optionally search the web through Brave Search.
-- Includes a live **Working** view for following current model/tool activity, with `All` / `Thinking` / `Tools` filters, image previews for image-producing tool outputs, plus **Load visible into editor** and **Copy visible** actions; optional browser-stored **Follow activity** (`Cmd/Ctrl+Option/Alt+A`; off by default under **View → Workspace**) switches to Working when the main Pi agent starts generating and to Response Preview when it completes, unless you manually choose another view during that request. When cycling response history, Working follows saved working details for the selected response when available, and `Cmd/Ctrl+Option/Alt+1–8` switches directly between right-pane views while `Cmd/Ctrl+Option/Alt+P` / `Cmd/Ctrl+Option/Alt+E` / `Cmd/Ctrl+Option/Alt+W` / `Cmd/Ctrl+Option/Alt+F` / `Cmd/Ctrl+Option/Alt+R` / `Cmd/Ctrl+Option/Alt+Q` keep quick mnemonic shortcuts for Response Preview, Editor Preview, Working, Files, REPL, and Side questions
-- Includes a right-pane **Changes** view for browsing the current git diff by file, previewing per-file diffs, opening changed files, loading the full diff into the editor, and copying the diff
-- Includes a right-pane **Files** view rooted in folders allowed for the current Studio session, with an **Allow folder…** action and location selector; exact-file grants can still be opened independently without exposing their parent folders. Files supports sorting by name/modified time/size, opening folders or the current root in Finder/the system file manager, loading text/code/CSV/TSV documents into the editor, opening a read-only **Preview (follow)** tab whose disk content is authoritative, previewing PDFs/images, opening previews in new Studio tabs, converting DOCX/ODT documents to editable Markdown when Pandoc is available after confirmation, copying paths, setting the current folder as the Studio working directory, and revealing files in the file manager
-- Imports detached text-file copies either through the browser's file picker or from a path on the computer running Pi, keeping the path option available in embedded and remote browser views; imported copies remain detached until saved or opened as file-backed documents
-- Includes an optional tmux-backed **REPL** view for Shell, Python, IPython, Julia, R, GHCi, and Clojure sessions, with a scoped **Quick send** composer (`Cmd/Ctrl+Enter`), Raw/Literate editor send modes, `Cmd/Ctrl+Shift+Enter` **Send to REPL**, session start/stop/interrupt controls, a privacy-conscious Off/Summary/Full pane-echo selector, a compact refresh-persistent **Shared REPL Record** of compatible-client submissions, a secondary raw tmux mirror, agent-facing `studio_repl_status` / `studio_repl_send` tools, and Markdown/PDF/HTML export
-- Includes a local persistent scratchpad for quick notes you want to keep out of the main editor until you're ready to copy or insert them, with a **Recent…** picker for recovering scratchpads saved under earlier file/draft identities
-- Includes a docked **Outline** rail for navigating document structure in the current editor text, with clickable entries that jump in the raw editor and reveal matching preview locations when available
-- Restores each browser tab’s editor workspace after refresh or cmux hidden-surface reconstruction, and provides an explicit **Reset editor** action when you want to discard the restored draft and return the tab to a fresh blank draft without changing responses or saved files
-- Tracks an SHA-256 disk revision for file-backed editors: `Cmd/Ctrl+S` checks that revision before staging and again immediately before atomic replacement, external changes produce an explicit **Reload / Save As… / Overwrite / Cancel** decision, and even **Overwrite** / Save As **Replace** must still match the revision Studio reported when confirmation opened. `Cmd/Ctrl+Shift+S` performs no-clobber Save As unless you explicitly confirm the current target. Studio preserves ordinary mode and ownership metadata where the platform permits and refuses to split hard-linked files; file-system-specific ACLs and extended attributes may not survive atomic replacement. As with other file system editors, unrelated writers do not participate in a shared atomic compare-and-swap, so version control remains appropriate for highly concurrent files.
-- Opens text/code documents as read-only followed previews through **Preview file (follow changes)**, Files' **Preview (follow)** action, or `/studio --watch <file>`; updates are debounced and content-hashed, atomic-save replacements are followed, reading position is restored by a stable content anchor with ratio fallback, and temporary read/render failures retain the last good preview
-- Turns local preview links, including links inside sandboxed HTML previews, into Studio actions: PDFs open in the embedded viewer, images open in a zoomable focus viewer, PDF/image links can open in a new Studio preview tab, text/code/CSV/TSV document links can open in a new editor tab, DOCX/ODT links can be converted to editable Markdown, and right-click menus provide **Open here**, **Reveal in file manager**, and **Copy path** for local resources
-- Includes local comments anchored to selections/lines, shown in a docked **Comments** rail, with transient **Comment** / **Jump** actions from raw-editor selections plus editor-preview selections for Markdown, LaTeX, code/text/diff previews, and an opt-in comment mode for editor HTML previews; source-anchored comments can be toggled into inline `[an: ...]` annotations when you want comments reflected in the document text
-- Browses response history (`Prev/Next/Last`) and loads either:
-  - response text, with **Annotate response** (`Cmd/Ctrl+Option/Alt+Enter` from either main pane) also opening **Editor (Preview)**; add Shift (`Cmd/Ctrl+Option/Alt+Shift+Enter`) for **Load response into editor** without switching views (choose another view first if file-backed Quarto Preview is active)
-  - critique notes/full critique
-  - the prompt that generated a selected response
-- Keeps the prompt → accepted Run → **Annotate response** loop confirmation-free when the submitted editor text is unchanged. **Annotate response** and **Load response into editor** ask before replacing unsubmitted edits or unsaved file changes; Cancel preserves the editor and its view so you can save or copy first. A failed submission or late acknowledgement cannot mark later typing as submitted, and sending file text does not save it. This bounded accepted-prompt baseline stays in page memory, is not restored after a page reload, and is separate from Pi-terminal draft cleanup.
-- Supports an annotation workflow for `[an: ...]` markers:
-  - inserts/removes the annotated-reply header
-  - shows/hides annotation markers in preview
-  - strips markers before send (optional)
-  - saves `.annotated.md`
-- Renders Markdown/LaTeX/code previews (math + Mermaid) plus lightweight CSV/TSV table previews, theme-synced with pi, with an explicit H1–H6 hierarchy, zoomable images across Studio-owned Markdown surfaces, and copy buttons for code blocks and blockquotes; already allowed local media loads silently, while blocked images and embedded PDFs remain unloaded behind an explicit per-file or containing-folder allow action; Mermaid previews include Lucide/Logos icon nodes and accessible label contrast over custom fills
-- Adds a contextual **Editor (Quarto Preview)** right-pane view for file-backed `.qmd`, `.md`, and `.markdown` documents. Studio checks Quarto and the document/project configuration before showing an explicit start action, launches a single loopback `quarto preview` process with `--no-execute`, embeds Quarto's authoritative saved-file output without restyling it, and provides open-in-browser, restart, stop, logs, and unsaved-editor warnings. If Quarto is missing, the view remains available with an actionable dependency message.
-- Renders straight, unfenced interactive HTML in preview via a sandboxed browser iframe with zoom controls, while fenced `html` blocks remain source code
-- Embeds local PDFs in Studio Markdown previews via explicit `studio-pdf` fenced blocks and opens existing PDFs directly with `/studio <path.pdf>`, with visible enlarge, browser-tab, system-viewer, show-in-folder, copy-path, manual refresh, and opt-in stable-file auto-refresh actions; true browser fullscreen is offered only when the browser supports it
-- Ships optional `pi-studio-dark` and `pi-studio-light` themes tuned for Studio's browser workspace
-- Exports right-pane preview as PDF (pandoc + LaTeX) or standalone HTML into the source file directory, Studio working directory, or Pi session directory; PDF export can open in a Studio preview tab or the default PDF viewer, and HTML export can open in the default browser or in a new Studio editor tab for inspection/commenting, while preserving authored HTML previews as HTML and rendering CSV/TSV editor previews as tables
-- Exports local files headlessly via `/studio-pdf <path>` to `<name>.studio.pdf` or `/studio-html <path>` to `<name>.studio.html`; without a path, those commands export the last model response to a timestamped file. Agent tools `studio_export_pdf` and `studio_export_html` expose the same export pipeline for remote/Telegram-style sessions.
-- Shows model/session/context usage in the footer, plus compact-context and active-theme controls
-
-## Pi input-draft handoff
-
-Tools such as [`pi-nvim-context`](https://github.com/omaclaren/pi-nvim-context) deliberately accumulate visible context in Pi's terminal input draft without submitting it. **Load from pi editor** (`Cmd/Ctrl+Shift+L`) copies that draft into Studio without clearing it and records only a transient SHA-256 fingerprint and byte length for the handoff—no additional snapshot copy beyond the text already in Studio. You can then edit the text freely in Studio.
-
-When Pi accepts **Run editor text**, Studio clears the linked terminal draft only if its current fingerprint and byte length still match those captured at load time. Terminal typing, additional Neovim context, or another client changing the draft causes Studio to preserve it silently. A failed or rejected run also leaves it intact. **Send current text to Pi editor** establishes the same safe link, while **Clear Pi editor text…** provides a separate confirmed, unconditional cleanup action. Studio never clears terminal history or its own editor through this handoff.
-
-## Commands
+**The Prompt: a question, plus a section added from the Document, and its preview:**
 
-| Command | Description |
-|---|---|
-| `/studio` | Open in Muxy or cmux when available, otherwise the system browser, with the last assistant response (fallback: blank) |
-| `/studio <path>` | Open a text file in the editor, or a PDF in a read-only companion preview tab |
-| `/studio --watch <file>` | Open a local text/code file in a read-only preview that follows disk changes, or a PDF with stable-file auto-refresh enabled |
-| `/studio --last` | Force last response |
-| `/studio --blank` | Force blank editor |
-| `/studio --no-browser` | Start/print the Studio URL without opening a browser, useful for forwarded or phone/browser sessions |
-| `/studio --port <port>` | Bind Studio to a fixed port instead of a random free port; the default host remains localhost |
-| `/studio --listen-all` | Explicitly bind Studio to all IPv4 interfaces (`0.0.0.0`) for a container or trusted private-network workflow |
-| `/studio --status` | Show studio server status, including its listening address |
-| `/studio --stop` | Stop studio server |
-| `/studio --help` | Show help |
-| `/studio-replace [path\|--blank\|--last]` | Replace the current full Studio view with a new full Studio view |
-| `/studio-editor-only [path\|--blank\|--last]` | Open an editor-only view, or a read-only PDF preview; add `--watch <file>` for a followed text/PDF companion view |
-| `/studio-current <path>` | Load a file into currently open Studio tab(s) without opening a new browser window |
-| `/studio-pdf [path] [options]` | Export a local file, or the last model response when no path is given, via the Studio PDF pipeline |
-| `/studio-html [path]` | Export a local file, or the last model response when no path is given, to standalone HTML via the Studio preview pipeline |
-
-## Agent tools
+![The Prompt with a section added from the Document, and its preview (pi-studio-dark theme)](./assets/screenshots/dark-workspace.png)
 
-| Tool | Description |
-|---|---|
-| `studio_export_pdf` | Export direct Markdown/LaTeX, a local file, or the last model response to PDF. Defaults to writing a file without opening a viewer. |
-| `studio_export_html` | Export direct Markdown/LaTeX, a local file, or the last model response to standalone HTML. Defaults to writing a file without opening a viewer. |
-| `studio_repl_status` | Inspect tmux-backed REPL sessions, including shared clean-record identity, compatible-client entries, and raw-mirror details. |
-| `studio_repl_send` | Send code to a visible REPL under the cross-client send lease, optionally choose its raw-pane `echoMode`, and add its captured output to the shared clean record. |
+**The Document: the file you're working on, with its preview:**
 
-## Install
+![The Document with its rendered preview (pi-studio-light theme)](./assets/screenshots/light-workspace.png)
 
-```bash
-# npm
-pi install npm:pi-studio
+**Zen mode, on the code (rose-pine-dawn theme):**
 
-# GitHub
-pi install https://github.com/omaclaren/pi-studio
-```
+![Zen mode with a rendered code preview (rose-pine-dawn theme)](./assets/screenshots/theme-zen-code.png)
 
-Run once without installing:
+There's also a [2-minute demo](https://github.com/omaclaren/pi-studio/releases/latest/download/pi-studio-demo-2min.mp4) (MP4, 2x speed, no audio) of an earlier version; the workflow is the same.
 
-```bash
-pi -e https://github.com/omaclaren/pi-studio
-```
-
-## Container and network access
-
-Studio binds to `127.0.0.1` by default. For a container or sandbox whose port must be published to the host, opt in explicitly and choose a stable port:
-
-```text
-/studio --no-browser --listen-all --port 4321
-```
+## Features
 
-This listens on `0.0.0.0:4321` while still printing a tokenized `http://127.0.0.1:4321/...` browser URL. With a same-port mapping such as `sbx run --publish 4321:4321`, open that URL unchanged on the host. `--listen-all` is a server-lifetime setting: if Studio is already running on localhost, use `/studio --stop` before restarting it with the flag.
+- **Prompt and Document** — the default, dual editor mode. The Prompt holds what you send to Pi; the Document holds the file you're working on. Each keeps its own edits, preview and place. See [Single and dual editor mode](#single-and-dual-editor-mode).
+- **Run, critique, annotate** — run the Prompt, ask for a critique, or annotate a response with `[an: ...]` markers and send it back.
+- **Response history** — step back through earlier responses, and load a response, its critique or the prompt that produced it.
+- **Working** — follow Pi's thinking and tool use as it happens. **Follow activity** switches to it during a run and back to the response afterwards.
+- **Rendering** — Markdown and LaTeX with math, syntax highlighting, Mermaid diagrams (with Lucide and Logos icons), CSV tables, interactive HTML and embedded PDFs, themed to match Pi.
+- **Files and Changes** — browse folders you've allowed, open or preview files, and see the current git diff.
+- **Comments and scratchpad** — comments anchored to lines or selections, and a scratchpad per document.
+- **Side questions** — ask about the text, a folder or the repository in a separate thread that stays out of the main conversation, optionally with web search.
+- **REPL** — send code to tmux-backed Shell, Python, IPython, Julia, R, GHCi or Clojure sessions, shared with [pi-repl](https://github.com/omaclaren/pi-repl).
+- **Quiz me, Show me, completions** — active-recall quizzes over the text or a folder, one-turn visual explanations, and short completions at the cursor.
+- **Export** — PDF (Pandoc and LaTeX) or standalone HTML, from the preview, a file or the last response.
+- **Careful saving** — a save checks the file hasn't changed on disk since you opened it, and asks if it has.
+- **Quarto** — preview a saved Quarto document through `quarto preview`, without running its code.
+- **Layout** — side by side or stacked panes, and a Zen mode that hides everything but the text.
 
-Treat wildcard binding as a security-sensitive mode. The URL token remains required, but anyone who obtains the full URL can control Studio for that Pi process: they can submit prompts, read or write files through Studio, and expand local-resource access. Studio does not add TLS. Treat the URL like a password, never expose the port directly to the public internet, and bind the host side of a container mapping to loopback when possible—for example, `-p 127.0.0.1:4321:4321`. For access across an untrusted network, keep Studio on its localhost default and use SSH local port forwarding instead.
+## Requirements
 
-## Shared REPL record
+- [Pi](https://pi.dev)
+- [Pandoc](https://pandoc.org/installing.html) for full previews and exports (`brew install pandoc` on macOS), and LaTeX (TeX Live or MacTeX) for PDF export
+- Optional:
+  - `tmux` for the REPL;
+  - `quarto` for Quarto previews;
+  - Mermaid CLI 11.12+ for diagrams in exported PDFs;
+  - `pdftotext` so side questions can read PDFs;
+  - `BRAVE_API_KEY` for side-question web search.
 
-Studio remains a standalone REPL client: it can create and use its own tmux sessions without `pi-repl`. When a compatible `pi-repl` installation uses the same tmux session, both clients automatically discover one session-owned clean record and see each other's code and captured output. No package imports or depends on the other.
+Studio is developed on macOS. It should work on Linux, which has had less testing.
 
-Compatible clients publish a versioned opaque record ID in tmux and keep the bounded JSON record in a private per-user temporary directory. The record is tied to the exact tmux session ID and creation time, uses atomic locked updates, and serializes compatible sends from pre-capture through output capture so concurrent Studio and `pi-repl` submissions do not claim each other's output. Existing sessions attach lazily; Studio's legacy browser-local entries are imported once with stable IDs.
-
-The clean record covers only submissions and notes whose boundaries a compatible client knows. Text typed directly into an attached tmux pane remains in the secondary raw pane/history mirror and is not presented as reliably parsed code/output. **Export record** produces a canonical Markdown representation with origin, mode, status, runtime, timestamp, and this limitation; PDF and HTML exports are derived from that Markdown.
-
-**Quick send** is a small command composer beneath the Shared REPL Record and above the secondary raw mirror, not a second persistent editor or terminal emulator. Its compact target shows the selected session name and doubles as a link back to the session controls; the hover and accessibility label retain the runtime and exact tmux pane details. Plain Enter adds a line, and `Cmd/Ctrl+Enter` submits the exact text through the same cross-client lease, control-file, and Shared REPL Record path as editor sends. Unsaved drafts stay in browser memory per exact tmux lifetime/runtime, survive session switching, and clear only after Studio acknowledges the submission; rejected text remains available to edit or retry.
-
-### Submission display and alignment anchors
-
-Optional pane echo places submitted code after a compact begin anchor, followed by a plain `── output ──` divider and a completion anchor. The anchors contain a stable 12-character hash derived from the Shared REPL Record entry ID, so compatible clients can align known sends in future derived transcripts without exposing the entry ID itself. Studio strips the exact header, source preview, divider, and footer from captured tool output and the clean record; they remain visible only in the raw pane/history.
+## Install
 
-The REPL footer selector offers:
+```bash
+pi install npm:pi-studio
+```
 
-- **Off** (default): no optional submission display or anchors; the runtime's unavoidable temporary-file control command can still be echoed by the REPL.
-- **Summary**: short submissions in full, truncating after 6 lines or 600 source characters, with compact begin/end anchors and a plain output divider.
-- **Full**: up to 40 lines or 4,000 source characters with the same anchors and divider. Full mode writes source code into persistent raw terminal history, so use it only when that is acceptable.
+Or from GitHub, `pi install https://github.com/omaclaren/pi-studio`, or once without installing, `pi -e https://github.com/omaclaren/pi-studio`.
 
-The browser choice is stored locally for that Studio origin. `studio_repl_send` accepts the same per-call `echoMode`; `PI_STUDIO_REPL_ECHO_MODE=off|summary|full` changes the tool-send startup default from Off. Display text escapes terminal, line-separator, and bidirectional control characters. The anchors improve raw-history alignment but do not make direct pane activity without instrumentation authoritative or alter protocol-v1 entries.
+## Usage
 
-Runtime wrappers use compact request-unique paths such as `/tmp/pi-rc-<user-key>/<token>.py` rather than a long Studio/session directory tree. The per-user root is current-user-owned mode `0700`, source files are mode `0600`, and files are removed after capture or by the timeout/abort watcher once execution settles. This keeps the unavoidable echoed loader command short without reverting to a collision-prone shared filename.
+| Command | Description |
+|---|---|
+| `/studio` | Open Studio with the last response. In dual editor mode, reopen your last workspace if its tab is gone |
+| `/studio <file>` | Open a text file, or a PDF in a read-only preview |
+| `/studio --watch <file>` | Open a read-only preview that follows changes on disk |
+| `/studio --blank`, `--last` | Start with a blank editor, or the last response |
+| `/studio --single`, `--dual` | Switch editor mode, and remember it |
+| `/studio --no-browser` | Print the URL without opening a browser |
+| `/studio --port <port>` | Use a fixed port |
+| `/studio --listen-all` | Listen on all interfaces, for containers ([see below](#network-and-ssh)) |
+| `/studio --status`, `--stop` | Show the server's status, or stop it |
+| `/studio-replace` | Replace the open Studio view. In dual editor mode, move it to a new tab here |
+| `/studio-editor-only [file]` | Open an extra editor tab (single editor mode) |
+| `/studio-current <file>` | Load a file into the open Studio tab (single editor mode) |
+| `/studio-pdf [file]` | Export a file, or the last response, to PDF |
+| `/studio-html [file]` | Export a file, or the last response, to HTML |
+
+Studio opens in Muxy's or cmux's built-in browser when Pi runs there, and otherwise in the system browser. Press `?` in Studio for keyboard shortcuts.
+
+Pi's agent can also use these tools:
 
-See [`shared/REPL_SESSION_RECORD_PROTOCOL.md`](./shared/REPL_SESSION_RECORD_PROTOCOL.md) for protocol, safety, retention, and compatibility details.
+| Tool | Description |
+|---|---|
+| `studio_export_pdf`, `studio_export_html` | Export Markdown/LaTeX, a file or the last response |
+| `studio_repl_status` | List REPL sessions |
+| `studio_repl_send` | Send code to a REPL and record its output |
 
-## Side questions and research context
+## Single and dual editor mode
 
-Open **Review → Side question**, select **Side questions** in the right pane, or press **Cmd/Ctrl+Option/Alt+Q**. A new side thread captures its starting text while keeping related-file access separate:
+**Dual editor mode** is the default. The left pane has a **Prompt**, which is what Run sends to Pi, and a **Document**, the file you're working on. Switch with the tabs or Cmd/Ctrl+Shift+1 and 2. Selecting the Document never changes what Run sends.
 
-- **Starting text** controls what unsaved text begins the thread. The compact **Automatic: selection → heading block at cursor → nearby text** disclosure explains the fallback order; when expanded, it defines the heading boundary. The summary below reports the resolved starting text, editor line range when applicable, and character count separately from the related-file scope.
-- Explicit **Editor selection only** no longer falls back to the whole document when no text is selected; the summary instead reports that no editor text is selected.
-- In the initial-question and follow-up boxes, **Cmd/Ctrl+Enter** submits while plain **Enter** adds a new line. The button remains available for pointer and ordinary keyboard activation.
-- **Also use files from** controls the read-only boundary available to the side agent: no other files, the document folder, the current repository, or another chosen folder. Related-file access requires an allowed folder for the current Studio session; if the selected root is not already allowed, Studio names the canonical folder and asks before starting the thread. An exact-file grant never exposes its parent folder.
-- With **Repository** selected, **Include Git context** can capture status, staged and unstaged tracked-file changes, and up to 20 recent commit summaries. The bounded snapshot is frozen when the thread starts and exposed through fixed read-only tools; untracked contents remain available only through the existing root-confined file reader.
-- **Include the current main conversation snapshot** is opt-in. Side questions and answers otherwise never enter the main Pi history; **Bring to main conversation** is the explicit handoff.
-- **Thinking** defaults to **Low** for quick asides. **X-high** and **Max** appear when the active model advertises support, for complex side questions where the extra latency is worthwhile.
-- Local context tools can map filenames, search readable text, and read selected ranges. Studio revalidates the allowed context root before prompts and built-in local tool calls; symlinks, root replacement, and traversal outside that root are rejected. PDF extraction uses `pdftotext`; DOCX, ODT, and EPUB extraction uses Pandoc.
-- **Allow web search** is opt-in and appears when `BRAVE_API_KEY` is available to the Pi process. Model-chosen search queries are sent to Brave Search; the side agent is instructed not to copy private local passages into queries. Web answers cite result URLs and identify when they rely on search-result snippets rather than full page content.
-- **Additional Pi tools** lists eligible tools already registered by the user's installed Pi extensions. Selection is explicit, remembered locally, and frozen when the thread starts. Studio reloads only the extensions owning the selected tools into the isolated side runtime and activates only those tool names; it does not import or depend on any particular third-party extension. Gateway tools are labelled and require an additional confirmation because selecting one may expose further services configured behind it.
+- **Add to Prompt** copies the Document's selection, or all of it, into the Prompt as a labelled snapshot, with Undo.
+- **File** opens a file in the Document, or in a new Document window. Each file has one editor; opening a file that's already open finds that editor.
+- Unsaved Prompt and Document text survives reloads and dropped connections. If you close the tab, `/studio` reopens the same workspace, asking first if the tab didn't close cleanly. This isn't a backup: save work you want to keep.
+- If Studio opened somewhere you can't find, such as another browser, `/studio-replace` moves it here, or open its URL and choose **Move it here**.
+- `/studio-current`, editable `/studio-editor-only` and Office-to-Markdown conversion aren't available in dual editor mode.
 
-The current side thread is ephemeral but survives Studio browser refreshes while the same Pi Studio server remains running. **Export thread** can save the visible discussion and context summary as Markdown, copy that Markdown, open it as an unsaved editor copy, or render it to PDF or HTML. Markdown is the canonical durable format; exports omit hidden starting-text contents, inherited main-conversation contents, and raw tool output. Studio never supplies the side agent with shell or file-writing tools, and known execution/mutation surfaces are excluded from the picker. Selected third-party tools retain their own behavior, permissions, and downstream scope, so choose tools you trust for read-only research.
+**Single editor mode** is the one-editor Studio of earlier versions, where Run sends the editor's text.
 
-## Studio Markdown extras
+To switch, use the footer button or `/studio --single` and `/studio --dual`. Studio restarts and reopens the tab, carrying over the Prompt's text, and the choice is kept for your Pi profile. The footer button waits, and says why, while there's unsaved text in the Document or a closed Document window, another Studio tab is open, or a run, save or side question is in progress. The commands work even if the page won't load; they disconnect open tabs, which keep their text, and ask before dropping anything only Studio's server holds.
 
-Studio previews standard Markdown, code fences, display math, Mermaid, and local images. The opened document directory and other explicitly allowed folders are available for local preview resources during the current Studio session. Media already inside those locations loads without interruption. An image or embedded PDF outside them stays unloaded and shows **Allow local image/PDF…**; activating that control offers an exact-file grant, a containing-folder grant for the session, or cancellation. Passive rendering itself never opens the permission decision.
+## Details
 
-When adding companion files such as generated plots or PDFs, prefer the project's existing folder convention. If there is no convention, `attachments/` is a reasonable default for newly generated assets. Use relative paths from the opened Markdown file or a folder allowed for the current Studio session, and wrap paths in angle brackets when spaces are possible:
+### Local files
 
-```md
-![Short descriptive caption](<attachments/plot.png>)
-```
+Studio reads files in the opened document's folder and in folders you allow from **Files**. A link or image elsewhere asks first, offering that file or its folder, for the rest of the session.
 
-Local PDFs can be embedded with an explicit Studio-only fenced block:
+Embed a PDF in a Markdown preview with a `studio-pdf` block. `path` is relative to the document; the other fields are optional:
 
 ````md
 ```studio-pdf
 path: attachments/paper.pdf
-title: Optional title
+title: A title
 page: 3
 height: 760
 watch: true
-caption: Optional caption
 ```
 ````
 
-`path` must point to a local `.pdf`. Relative paths resolve from the opened document's directory, or from Studio's working directory for non-file-backed content; the resolved file must be inside a location allowed for the current Studio session before it loads. `page` is an initial page hint for the browser PDF viewer, `height` controls the embedded frame height in pixels, and `watch: true` enables auto-refresh after Studio observes the changed file in a stable state. Use normal Markdown links for PDFs when embedding is not useful.
-
-To view an existing PDF directly, run `/studio report.pdf` (or `/studio "path with spaces/report.pdf"`). The PDF opens read-only in a focused companion preview, even when the full Studio workspace is already open. A `#page=N` suffix selects the initial page. Auto-refresh is off by default; use `/studio --watch report.pdf` to start with it on, or toggle **Auto-refresh** in the PDF card or focused viewer. Studio checks only while the tab is visible and waits for two matching file-version observations before reloading, which avoids reading a PDF while LaTeX is still writing it. **Cmd/Ctrl+Option/Alt+Shift+R** manually refreshes the focused or visible PDF. This is distinct from `/studio-pdf`, which exports Markdown, LaTeX, code, or the last response to a new PDF.
-
-For a disk-authoritative text or code preview, run `/studio --watch notes.md` or choose **Preview file (follow changes)** from a local-link menu / **Preview (follow)** in Files. This opens a transient read-only companion tab with the preview pane focused; leaving pane focus reveals the same disk-following text as **Source** with a visible **Read-only · follows disk** badge rather than as an editable buffer. Studio polls the canonical file, debounces change bursts, compares SHA-256 content revisions, accepts ordinary and atomic-replacement saves, and never writes back. Each watcher socket is bound to the exact path in a bounded, expiring server-created tab capability; if that identity expires before a reload or reconnect, the tab stays read-only and asks you to open a fresh watched preview. A missing, unreadable, oversized, binary, or path-replaced source leaves the last good preview visible and automatically recovers when the same canonical file becomes readable again. Render failures likewise retain the last successfully staged document rather than replacing it with partial output. On successful updates, Studio restores a nearby stable content anchor where possible and falls back to the previous scroll ratio.
+To view a PDF, run `/studio report.pdf`; it opens read-only, and `#page=N` picks the page. `/studio --watch report.pdf` also reloads it when the file changes: Studio waits for two matching file-version observations, so it doesn't read a PDF that LaTeX is still writing. This is distinct from `/studio-pdf`, which exports to a new PDF.
 
 ### Mermaid icons
 
-Studio's live previews and standalone HTML exports support Mermaid's `lucide:*` and `logos:*` icon nodes. The corresponding Iconify packs load lazily, so Studio does not fetch either pack unless a diagram uses it. Mermaid and the browser icon-pack URLs are pinned to tested versions.
+Diagrams can use `lucide:*` and `logos:*` icons; the icon packs load only when a diagram uses them.
 
 ````md
 ```mermaid
@@ -217,40 +132,42 @@ flowchart LR
 ```
 ````
 
-Studio also corrects low-contrast Mermaid icon paints and node labels after browser rendering while preserving authored colours that already meet a 4.5:1 contrast ratio. For PDF output, Studio adds or corrects label colours on `classDef` and `style` declarations with solid hex/RGB fills and supplies targeted icon CSS to Mermaid CLI; this also covers Logos icons whose SVG paths use literal fills.
+Icons in exported PDFs need Mermaid CLI 11.12+ (`npm install -g @mermaid-js/mermaid-cli`, or set `MERMAID_CLI_PATH`).
 
-PDF icon nodes require Mermaid CLI 11.12+ so Studio can use pinned icon-pack URLs. Install a current CLI, or set `MERMAID_CLI_PATH` to one:
+### Pi's input editor
 
-```bash
-npm install -g @mermaid-js/mermaid-cli@11.16.0
-mmdc --version
-```
+**Load from pi editor** (Cmd/Ctrl+Shift+L) copies the draft in Pi's terminal input into Studio, as tools like [pi-nvim-context](https://github.com/omaclaren/pi-nvim-context) build it up. When Studio runs that text, it clears the terminal draft only if the draft hasn't changed since.
+
+### REPL
+
+The REPL pane runs code in tmux sessions. It can start its own, and it shares a record of submissions and output with [pi-repl](https://github.com/omaclaren/pi-repl) when both use the same session. Pane echo (Off, Summary, Full) controls how much submitted code appears in the raw tmux history; Full writes your code into that history. The record format is in [`shared/REPL_SESSION_RECORD_PROTOCOL.md`](./shared/REPL_SESSION_RECORD_PROTOCOL.md).
+
+### Side questions
+
+**Review → Side question**, or Cmd/Ctrl+Option/Alt+Q, opens a separate thread. It starts from the selection, the section at the cursor or the whole text, and can read the document's folder, the repository or another folder you allow, including PDF, DOCX, ODT and EPUB text. Its tools are read-only. With `BRAVE_API_KEY` set, it can also search the web; queries go to Brave Search. Nothing enters the main conversation unless you choose **Bring to main conversation**.
+
+### Network and SSH
+
+Studio listens on `127.0.0.1` only, and every URL carries a token. Over SSH, forward the port and open the printed URL with its token; `/studio --no-browser --port <port>` gives a stable port to forward.
+
+For a container, `/studio --no-browser --listen-all --port 4321` listens on all interfaces. Anyone with the full URL can control Studio, including running prompts and reading or writing files, and there's no TLS. Treat the URL like a password, never expose the port to the internet, and bind the host side to loopback (`-p 127.0.0.1:4321:4321`). Quarto previews use a second port, which must be forwarded too.
+
+### Environment variables
+
+| Variable | Effect |
+|---|---|
+| `PANDOC_PATH`, `PANDOC_PDF_ENGINE` | Pandoc binary, and the LaTeX engine for PDFs (default `xelatex`) |
+| `MERMAID_CLI_PATH` | Mermaid CLI for diagrams in PDFs |
+| `BRAVE_API_KEY` | Enables web search in side questions |
+| `PI_STUDIO_FONT_MONO`, `PI_STUDIO_FONT_UI`, `PI_STUDIO_FONT_PROSE` | CSS font stacks for code, interface and previews |
+| `PI_STUDIO_REPL_ECHO_MODE` | Default pane echo for `studio_repl_send`: `off`, `summary` or `full` |
+| `PI_STUDIO_PANDOC_TIMEOUT_MS`, `PI_STUDIO_LATEX_TIMEOUT_MS`, `PI_STUDIO_MERMAID_TIMEOUT_MS` | Export time limits |
 
-Studio only passes icon-pack arguments when a diagram actually references `lucide:` or `logos:`, so ordinary Mermaid PDF diagrams remain compatible with older CLI versions.
+Installing pi-studio also adds `pi-studio-dark` and `pi-studio-light` to Pi's themes, without changing your current theme.
 
 ## Acknowledgements
 
-Thanks to [Hal Gumbert / CampSoftware](https://github.com/campsoftware) for publishing [Pi Studio Activity](https://campsoftware.com/blog/post.php?post=20260507-ai-ollama-pi-studio-activity). Its Working-to-Preview following and vertical-layout experiments inspired Studio's built-in **Follow activity** option and stacked pane layouts; the built-in implementation uses Studio's own lifecycle events and layout system.
-
-## Notes
-
-- The Studio server is localhost-only (`127.0.0.1`) by default and every Studio URL carries a server-lifetime token. The explicit `--listen-all` option changes the listening address to `0.0.0.0` without changing the advertised loopback URL or removing token authentication; `/studio --status` reports the active binding.
-- When Pi runs inside Muxy or cmux, Studio opens in that terminal app’s built-in browser. Muxy is detected from its pane/socket environment without installing global hooks; cmux targets and focuses the caller’s workspace. If the detected terminal browser is unavailable, disabled, or declines the request, Studio falls back once to the system browser.
-- For remote SSH sessions, keep Studio bound to localhost and use SSH local port forwarding; `/studio` and `/studio --status` print the full tokenized localhost URL. The SSH hint repeats the full URL so it is visible even if your terminal only shows the latest notification. Open that URL through the tunnel, preserving the `?token=...` parameter. If SSH is not auto-detected, use `/studio --no-browser`; for stable forwarding, use `/studio --port <port>` or combine them, e.g. `/studio --no-browser --port 3417`.
-- Full Studio is a singleton per Pi session: use `/studio` to open it, `/studio-replace` to explicitly replace it, and `/studio-editor-only` for extra editing/preview tabs that do not take over the full Studio session view.
-- Studio is designed as a complement to terminal pi, not a replacement.
-- Installing pi-studio makes the optional `pi-studio-dark` and `pi-studio-light` themes available in pi's theme selector; it does not change your active theme.
-- Editor/code font uses a best-effort terminal-monospace match when the current terminal config exposes it; set `PI_STUDIO_FONT_MONO` to force a specific CSS `font-family` stack. Use `PI_STUDIO_FONT_UI` or `PI_STUDIO_FONT_PROSE` to override the Studio UI or rendered-preview font stacks.
-- The optional REPL view requires `tmux`. Studio can start and stop Studio-owned `pi-studio-repl-*` sessions and can mirror detected `pi-repl-*` sessions, but it will not stop external `pi-repl-*` sessions. Compatible clients synchronize their clean record automatically; direct pane interaction remains available only in the raw mirror. A send timeout or tool abort does not stop submitted runtime code, so Studio keeps that session's cross-client lease until the runtime completion signal appears or the exact tmux session ends. The visible request-specific completion anchor is separate presentation metadata and stays in raw history when pane echo is enabled.
-- Side-question web search requires `BRAVE_API_KEY`; without it, local and conversation context still work, and the web option is shown as unavailable. Side sub-sessions are deliberately read-only and can run independently while the main Pi agent is busy.
-- Full preview/PDF quality depends on `pandoc` (and `xelatex` for PDF):
-  - `brew install pandoc`
-  - install TeX Live/MacTeX for PDF export
-- LaTeX browser previews and **Export right preview** are semantic Pandoc conversions rather than authoritative compilation of the original source layout. If a local legacy `.sty` package overrides LaTeX document startup in a way that prevents Pandoc from reading the document, Studio omits that package from the conversion only, preserves local includes, and shows a warning; compile the original source directly with LaTeX for exact package-specific layout.
-- **Editor (Quarto Preview)** is optional and requires the `quarto` CLI on Studio's `PATH`. It supports saved `.qmd`, `.md`, and `.markdown` files, whether standalone or part of a Quarto project. Selecting the view only inspects the saved document; starting the preview is explicit. Studio passes `--no-execute`, which prevents computational cells from running, but trusted Quarto project extensions, filters, configuration, and render hooks are still processed, and Quarto may create or update its normal rendered output files. The preview reflects disk, not unsaved editor text.
-- Quarto serves its embedded page on a second random loopback port. When Studio itself is reached through SSH port forwarding, that Quarto port (shown in **Show log**) must also be forwarded, or the preview should be opened from a Studio process running on the browser's machine.
-- Export subprocess timeouts default to bounded values and can be tuned with `PI_STUDIO_PANDOC_TIMEOUT_MS`, `PI_STUDIO_LATEX_TIMEOUT_MS`, `PI_STUDIO_MERMAID_TIMEOUT_MS`, and `PI_STUDIO_HTML_RENDER_OUTPUT_MAX_BYTES` for unusually large embedded-asset HTML exports.
-- Mermaid diagrams in exported PDFs require Mermaid CLI (`mmdc` / `@mermaid-js/mermaid-cli`) when you want diagram blocks rendered as diagrams rather than left as code; PDF icon nodes require Mermaid CLI 11.12+.
+Thanks to [Hal Gumbert / CampSoftware](https://github.com/campsoftware) for [Pi Studio Activity](https://campsoftware.com/blog/post.php?post=20260507-ai-ollama-pi-studio-activity), which inspired **Follow activity** and the stacked layouts.
 
 ## License
 

package/ROADMAP.md

@@ -2,6 +2,10 @@
 
 This is the current planning source of truth for Studio work. `NEXT-STAGE.md` is historical; `TODO.md` tracks smaller backlog items that are not yet assigned to a release.
 
+## Current status (14 Oct 2026)
+
+`0.10.0` ships the buffer-first workspace as **dual editor mode** (Prompt and Document), on by default, with **single editor mode** one switch away (footer button, `/studio --single`). It went through real course use as private alpha candidates 49–69. The `PI_STUDIO_*` flags described further down are now development overrides only: when any is set it decides, and the mode switch is hidden. Fixes follow in `0.10.x`. The sections below are the history up to this point.
+
 ## Release approach
 
 Studio development follows two tracks:
@@ -21,17 +25,64 @@ Each release should finish with:
 
 Committing, publishing, pushing, and tagging remain explicit actions rather than automatic consequences of implementation or planning approval.
 
-## Agreed next sequence (2026-09-07)
+## Hosting candidate — 2026-09-27
+
+The approved alpha now also includes single-owner Document hosting behind recovery + switching + `PI_STUDIO_DOCUMENT_HOSTING=1`. Move, detached copy, registered blank/text-file editors, existing-owner reuse and atomic file replacement are distinct; Prompt stays anchored. Retained save/metadata decisions, permission checks and uncertain-operation backups remain required. See [README](README.md#additional-opt-in-prototype-single-owner-document-hosting) for deliberate entrypoint restrictions. All flags remain off by default.
+
+The source46 checkpoint passed998 full tests, TypeScript, all eight flag combinations and the bounded hosting workflows. Those are historical source-tree results, not a claim that the subsequent copy-warning fix or a new tarball is validated. Finish candidate-specific checks, dependency/content audits and private installation before any release decision. No feature expansion, publication, commit or normal-install change is authorized by this status update.
+
+## Earlier toolbar follow-up — 2026-09-23
+
+The first exact `0.10.0-alpha.1` artifact passed its fresh-install checks and was tried manually in an isolated runtime through Oliver's existing browser, without browser automation. He then approved a small UI cleanup: group **Add to Prompt → Selection / Whole document**, consolidate **Open / load** with explicit destinations/replacement descriptions, and remove permanent help and duplicate Run-target rows. Keep annotations, the fixed pair and all existing source/copy semantics. This follow-up is uncommitted; rebuild/recheck in new candidate-scoped evidence rather than changing the first tarball. No multiple-document or role-switching work, publication or normal-install change is authorized.
+
+## Previous checkpoint — 2026-09-22
+
+The opt-in **one Prompt ↔ one Document** runtime/tests are locally committed through `40d4462` on `feature/buffer-recovery-foundation`. Development remains in `pi-studio-buffer-dev`; the original checkout is frozen. Bounded local alpha preparation is approved, with unused version `0.10.0-alpha.1` selected after checking npm. The stable installation remains `0.9.60`. Documentation/package preparation is uncommitted; nothing from this branch has been published or enabled by default.
+
+Implemented scope now includes:
+
+- independent Prompt/Document editing, previews, temporary recovery and switching during an identified Run;
+- explicit selection and whole-document snapshot appends, without saving, switching or submitting;
+- guarded response/critique loading and a leading-only annotation header in opt-in Prompt, with copied body text left intact;
+- fixes for stale file-open/grant decisions, mixed-input append activation, history rollover and separate response/Working reading positions;
+- the latest fixes preserving an outstanding response-scroll reset across buffer switches and preventing a delayed numeric restore from being adopted by another view.
+
+Whole-document and composed-Prompt hands-on trials, prepared-payload checks and rendered-preview checks have been completed. Later review findings were reproduced and fixed in separate local checkpoints. Validation of that committed checkpoint includes **718 recorded full-suite tests** on the same runtime/test bytes, plus **202 focused tests and normal typecheck/static checks freshly passed on 2026-09-20**. The latest browser groups cover **41 cases in Brave**, and the same 41 cases across **29 Chrome-app checks plus 12 Chrome Headless Shell 153 checks**. Those Chrome results span two variants, not one full Chrome-app run. The earlier Safari smoke covers the foundation, not the current switcher. No fresh-package or current live-provider release sign-off is implied.
+
+The separate **immediate pane-pointer → view-change scroll race**, whose helper predates this branch, is fixed in approved local commit `40d4462`. Snapshots retain their DOM/view generation and, with recovery enabled, existing buffer/editor consent. Of 38 new VM cases, 29 failed before the fix and 9 controls passed; all 38 now pass. On 2026-09-21, dedicated **Chrome Headless Shell 153** confirmed both stale callback windows in default and two-buffer modes: the old client moves Working from 10259px to 0; the fixed client stays at 10259px. Settled/same-view controls and unaffected-source restoration pass. Timing uses trusted pane input plus deliberately scheduled programmatic view changes, not measured human timing. **240 focused tests, normal typecheck and syntax/whitespace/runtime-boundary checks** freshly pass. The full suite and supplemental check-JS were not rerun; the earlier supplemental baseline was 493 diagnostics, not a passing check.
+
+Oliver's reported **Working appearing empty until interacted with** remains unreproduced and is not claimed fixed. Native view/buffer returns retained Working content and visible geometry; inspected screenshots show content before interaction. Headless Shell did not enter a hidden state during tab switching, so background-tab/visible-browser painting remains unverified. No rendering/CSS workaround was added. All six test attempts, including two retained harness-calibration failures, had backup-first disposal and verified process/port cleanup; 25 samples stayed at normal pressure with no per-trial swap growth. Evidence: `context/pane-scroll-native-20260921_225607/`.
+
+## Next — bounded opt-in prerelease
+
+Follow [PRERELEASE-CHECKLIST.md](PRERELEASE-CHECKLIST.md) for the approved local `0.10.0-alpha.1` preparation. This is a way to try the tested fixed-slot workflow, not a claim that the full architecture below is complete. Eventual npm publication would use `next` and needs separate approval.
+
+1. The pane-scroll fix/tests are checkpointed. Keep the unreproduced blank-Working report open as a documented limitation, accepted for local preparation; publication still needs an explicit decision on the exact artifact and its limitations.
+2. Align the public documentation and validate one exact package candidate: full tests, static/dependency checks, package-content/byte audit, isolated fresh installation and a short credential-free workflow smoke. Record fresh results separately from the historical counts above.
+3. Keep recovery/switching/hosting opt-in and the normal `0.9.60` installation untouched. Further commits, publishing, pushing/tagging, live-provider trials, changing the installed source and default activation remain separate decisions.
+
+Use a dedicated test-only browser with resource monitoring; do not run browser trials alongside full tests/typecheck on a constrained host. The existing suite includes a browser-launching test, so an unconfigured `npm test` is not a browser-free check. Do not begin another broad review loop unless a concrete finding changes the release decision.
+
+After this bounded prerelease, the next proposed functional slice is explicit **Prompt-role switching between the existing buffers**, preserving the previous buffer. Prompt is a submission role an editable document can take; in-place annotation and making a detached prompt copy are distinct operations. This direction is not implemented or approved for execution. Keep annotation/comments in both roles and preserve editor space rather than adding toolbar rows. The separately approved third-flag scope above now covers single-owner Document handoff and independent editor hosts. Linked views, Prompt-role migration and parked prompts remain separate work, not additions to this alpha.
+
+## Agreed architecture sequence (2026-09-07)
 
 1. Ship **`0.9.60`** as the bounded networking/shortcut release. Do not start buffer architecture in this batch.
 2. After that release, implement **`0.10.0`** around an explicit active Prompt, independently editable documents, context transfer, and parked prompt drafts. The design is in [`BUFFER-DESIGN.md`](https://github.com/omaclaren/pi-studio/blob/main/BUFFER-DESIGN.md).
 3. Keep Derived REPL Transcript, editor-engine migration, and arbitrary pane arrangements outside both batches.
 
-Current status:
+### Historical implementation milestones through 2026-09-11
+
+The counts and pending steps below describe those earlier checkpoints; the current status and next actions are above.
 
 - `0.9.60` combines the networking fix with Follow activity, Annotate response, and view-preserving Load response shortcuts, plus accurate draft-replacement protection. The published networking RC remains unchanged.
 - The reporter has not replied to the RC invitation on [issue #4](https://github.com/omaclaren/pi-studio/issues/4) as of 2026-09-07. Exact `sbx` validation remains outstanding; the release proceeds with that limitation documented and the issue open for confirmation or a follow-up fix.
-- `0.10.0` remains design-only. Approval to release `0.9.60` does not authorize buffer implementation.
+- After releasing `0.9.60`, Oliver approved starting the `0.10.0` store/recovery foundation with the current UI unchanged. Stage 1a is implemented and tested. Stage 1b now has an isolated, development-flagged single-editor binding, acknowledged v2 server fallback, explicit recovery inspection/export/choice/retry, and locally completed callback/metadata ownership coverage. The isolated host matrix passes in Brave and Google Chrome, with the earlier targeted foundation matrix also passing Safari 26.5. Seven independent Codex safety findings and two later in-session Astra findings have been reproduced, fixed, and regression-tested. The latest fixes protect empty dirty-file comments-prompt replacement and prevent unread saved comments/scratchpads from being overwritten. All 432 tests and the expanded isolated Brave/Chrome checks pass. The current targeted Safari 26.5 smoke also passes after Allow Remote Automation was re-enabled. Oliver approved a local checkpoint commit on `feature/buffer-recovery-foundation` on 2026-09-09. Recovery remains opt-in; default activation, source switching and release still require separate explicit approval.
+
+- On 2026-09-09, after the local foundation/header checkpoints and visual guide, Oliver approved a small **Prompt ↔ one document** prototype. It is now implemented locally under a second `PI_STUDIO_BUFFER_SWITCHING=1` flag, requiring recovery and a full editable workspace. All **472 tests**, static checks, and isolated Brave/Chrome switching and foundation-only workflows pass. After the first hands-on trial, a fresh read-only review identified held-Enter submission and queued-Follow defects; both were reproduced and fixed with unit/native regressions. This increment is a local, unreleased checkpoint; installed Studio and defaults remain untouched. General tabs, context transfer and parked drafts are still future work.
+- On 2026-09-10, following the successful isolated hands-on/live-model trial, Oliver approved allowing existing-buffer selection during an identified direct Run. This follow-up is implemented as a local, unreleased checkpoint. It keeps local save/open/recovery locks, submitted-Prompt identity and global Stop; queues completion for Prompt, preserves Document's live preview and rejects stale failure settlement. A fresh read-only review found a queued response surviving an empty tree change and hidden activity ownership surviving a disabled policy. Both were reproduced, then fixed with separate approval and failing regressions first. All **500 tests** and isolated Brave/Chrome Run-switching/regression checks pass. These last two fixes used controlled browser events. The resulting checkpoint subsequently passed an isolated live-model hands-on trial; Oliver confirmed the interaction worked and approved backing up/stopping that trial. Further checkpoint/release/installation changes remain separate decisions.
+- Oliver then separately approved **Add selection to Prompt**, limited to Document editor selections. It is a separately approved local, unreleased checkpoint, with **522 tests /80 focused tests** and credential-free Brave/Chrome checks. The action appends a labelled in-memory snapshot without changing Document, replacing existing Prompt content, transferring metadata/resource authority, saving files or submitting. It stays in Document and can prepare the next draft during an identified Run. A fresh read-only review found a literal-label boundary defect and a held press surviving selection A→B→A. Both were reproduced, then fixed with separate approval and failing regressions first. The actual label failure is reachable through a trailing-backtick imported filename; the reviewer's leading-backtick image example did not reproduce. Nine fix cases and eleven existing selection groups per browser, plus ten prior compatibility runs, pass. Preview/companion copying and general tabs remain deferred; no provider trial or independent post-fix sign-off is claimed for this slice. The committed selection slice subsequently passed Oliver's credential-free hands-on trial; both drafts were backed up before stopping.
+- Oliver separately approved the scoped **Add document to Prompt** follow-up. It is a local, unreleased checkpoint, with **549 tests /107 focused tests** and twenty sequential credential-free Brave/Chrome runs passing. It adds the full in-memory Document from raw-editor view without requiring/changing selection, preserves Prompt text and both buffer owners, displays exact addition/capacity counts, and retains the identified-Run and local-operation safeguards. Eighteen new regressions failed before implementation. A fresh read-only review then found stale-open control state and cancelled-press issues; both were reproduced in Brave/Chrome and fixed with separate approval, adding nine regressions. Native overlap testing also covered completed Space-key cancellation. Click-only assistive activation was simulated, not tested through VoiceOver. At this checkpoint, post-fix review and a hands-on trial were still pending. Subsequent trials, reviews and fixes are reflected in the current checkpoint above; installation/default changes and release remain unapproved.
 
 ## 0.9.52 — Rendering and media consistency (shipped 2026-08-28)
 
@@ -163,17 +214,23 @@ The networking review and production lifecycle tests support the reported fix; a
 
 Do not include buffer tabs, context-transfer messages, recovery schema v2, or REPL transcript work in this release.
 
-## 0.10.0 — Active Prompt and editable document buffers (planned)
+## 0.10.0 — Active Prompt and editable document buffers
+
+The first opt-in prerelease is limited to the current two-buffer workflow. The wider architecture and acceptance scenarios remain the target for the full release; see the [prerelease checklist](PRERELEASE-CHECKLIST.md) for the smaller candidate's gates.
+
+The local foundation includes the browser-safe store/codec/migration modules plus a `PI_STUDIO_BUFFER_RECOVERY=1` single-editor/server integration, available through the explicit process-scoped recovery flag. With switching off, the default v1 recovery path, successful editor layout, Run's visible-text destination, and browser-opening actions remain unchanged. Native isolated production tests cover reload, file baselines, metadata persistence/ordering, local-resource grants, PDF focus replacement, comments-prompt consent, late save/refresh, reconnect ownership, independent editors/disk conflicts, watched-to-editable browser tabs, reset retention and startup typing. The opt-in **Source & context → Recover unsaved text…** action inspects/exports retained copies, prepares verified fresh namespaces for explicit recovery/reset, and retries current-text persistence without adopting another branch. Focused ownership regressions now cover completion/import/Pi-editor loads, committed preview DOM and focus actions, Quarto request sources, metadata associations, failed writes, unload beacons and initialization/reset races. Metadata POSTs retain only one in-flight and one latest snapshot per key, time out conservatively, preserve intervening autosave timers, and advance same-writer server ordering only after the persistent-state write succeeds. The opt-in comments-prompt action also protects empty or unknown-baseline file edits and rechecks the captured disk baseline/revision after confirmation. Comments and scratchpad editing/persistence wait for the first successful per-document read; failed, malformed or timed-out reads stay protected and reopening the panel retries. Previously loaded page-local notes remain editable during refresh. Additional native regressions cover corrupt/unscoped copies, stale consent, full exports, server-only recovery, reconnect, failed refresh, pending/failed metadata reads and preserved saved notes. See [the foundation contract](shared/STUDIO_BUFFER_FOUNDATION.md) for contracts and the separate switching opt-in. This remains unreleased, not default activation or the complete `0.10.0` architecture.
+
+The current second-flag prototype has two fixed entries, **Prompt** and **Document**, not a general tab manager. A fresh/v1 file-backed editor remains the Prompt; older v2 roles require an explicit choice. Opening a separate document preserves the Prompt; Files also offers explicit **Use as Prompt…**. Document view returns to Prompt without sending, including under held Enter; a distinct activation sends its visible text. Both buffers retain independent text, baselines, metadata and reading positions through switching/reload. A Follow-on Prompt catches up with a queued response on return without reusing the old response's scroll offset; paused reading remains preserved. An identified connected direct Run permits selecting kept buffers, without relaxing local save/open/recovery or unresolved Pi-draft locks. Stop remains global; Return through the Prompt tab or Run shortcut does not submit or cancel. Completed responses wait for Prompt's Follow setting, and history notifications do not reconstruct Document's live preview. Local mutating operations still gate switching; stale file reads and background responses cannot replace another buffer or steal its view. Recovery retains the pair, and Reset confirms both. Local selection and whole-document actions now append explicit Document editor snapshots to Prompt; neither copies rendered previews or performs companion handoff. Parked drafts and close/add navigation are not implemented. Review this interaction before expanding the UI; see [the current prototype scope](BUFFER-DESIGN.md#current-prototype--before-general-tabs).
 
 Studio's primary loop is prompt construction and response reading. Documents remain useful editable sources, not implicit submission targets or a replacement for Neovim. The design is **one clearly active Prompt, other prompt drafts that can be parked, and independently editable documents**.
 
-The first architectural release should add:
+The full architectural release—not the first opt-in alpha—should add:
 
 - a `StudioBufferStore` with stable buffer identity, explicit prompt/document roles, and separate selected-buffer and active-prompt identities;
 - a prominent **Prompt** view with response/Working alongside it, plus editable document tabs with their own previews;
 - recovery schema v2 with non-destructive migration from the single-document schema;
 - buffer-specific text/baseline, dirty state, cursor, selection, scroll, preview context, annotations, and resource directory, preserving existing disk-revision checks;
-- **Add selection to prompt** and **Copy document to prompt**, including an acknowledged handoff from editable companion views to the full workspace's explicit prompt destination;
+- **Add selection to Prompt** and **Add document to Prompt**, including an acknowledged handoff from editable companion views to the full workspace's explicit prompt destination;
 - editable context snapshots of the visible text, including unsaved edits and source labels/ranges where known; no automatic submission, replacement, file write, or later live update of the copied text;
 - a lightweight parked-prompt picker, with one active submission draft at a time and no per-draft conversation forks;
 - tabs at ordinary widths, a compact searchable picker at narrow widths, and MRU/next/previous/close/reopen navigation;

package/WORKFLOW.md

@@ -19,7 +19,7 @@ Studio uses a **single workspace**:
 
 ## 1) Insert annotated reply header (optional prep)
 
-Adds/updates an `annotated-reply` compatible scaffold in the editor:
+Toggles an `annotated-reply` compatible scaffold in the editor. Studio's generated opener and metadata wording remain unchanged:
 
 ```md
 annotated reply: below
@@ -35,6 +35,36 @@ annotated reply: below
 
 Studio does **not** auto-send this scaffold; it is an explicit editor transform.
 
+### Header recognition contract (local compatibility work; not yet released)
+
+The parser accepts these **whole first lines**, case-insensitively:
+
+- `annotations below`
+- `annotations below:`
+- `annotated reply: below`
+- `annotated reply below:`
+
+Each opener works with the known minimal Neovim block, the full Studio bullet metadata above, or the older plain metadata layout (`original source`, `user annotation syntax`, optional `precedence`, without bullet prefixes or a blank line after the opener). Bullet layouts require a blank line after the opener. Metadata order and the known syntax/precedence wording must match; arbitrary edited instructions are not silently consumed. The accepted syntax examples are `[an: note]` / `[an: your note]`, optionally backticked; the backticked form may carry Neovim's parenthetical below. Full legacy headers remain recognisable when **Strip annotations…** has removed their unbackticked hint.
+
+The minimal Neovim block is:
+
+```md
+annotations below
+
+- user annotation syntax: `[an: note]` (user comments on the accompanying selections)
+
+---
+
+```
+
+All layouts require a blank line before the exact `---` divider and a blank line after it. LF and CRLF are accepted without normalising or trimming the remaining body. Source/precedence lines and a footer are not required for the minimal form, whose entire remaining text is body. A backticked syntax example is not an annotation.
+
+Detection, toolbar summaries, toggling and header removal share the same parser. Prose mentions, opener prefixes, quoted/indented/fenced examples, and arbitrary later dividers do not count. An exact opener with an unknown or malformed following block prompts a warning and leaves the editor unchanged rather than adding a duplicate header.
+
+Full source-bearing legacy wrappers retain their optional footer convention: only the exact terminal `\n\n--- end annotations ---\n\n` suffix (or its all-CRLF equivalent), outside a Markdown backtick/tilde fence, is removed. Quoted/indented/prose marker text and extra trailing whitespace are preserved. Minimal headers never remove a footer. Inserting Studio's usual wrapper preserves any pre-existing body marker; its generated footer is omitted if it would fall inside an unclosed fence, so toggling still preserves the body.
+
+This compatibility change does not switch the installed Studio version or change Neovim's emitted wording. Deployment/release is a separate decision.
+
 ## 2) Run editor text (plain send)
 
 Sends current editor text to the model. If `Annotations: Hidden`, `[an: ...]` markers are stripped before send.
@@ -111,7 +141,7 @@ Rules of thumb:
 
 1. `/studio --last` opens with editor loaded and no required mode selection.
 2. **Run editor text** respects annotation mode (`On` send as-is, `Off` strip `[an: ...]`) and returns response to right pane.
-3. **Insert annotation header** updates the scaffold source metadata without duplicating headers.
+3. **Annotation header** recognises all supported openers without duplication; toggling preserves the body and refuses malformed leading header blocks.
 4. **Critique editor text** runs on current editor text and returns structured package when model complies.
 5. Structured critique helpers (`Load critique (notes)` / `Load critique (full)`) enable only when critique structure is present.
 6. Loading response/critique back into editor never loses draft unexpectedly.