gentle-pi 4.2.0 → 4.4.0

package/docs/gentle-agents-activity.md

@@ -49,7 +49,11 @@ Aliases are display hints, never authentication or routing identities.
 
 Aliases are optional envelope metadata in the existing branch-local state record,
 restored with `getBranch()` on start/reload/tree navigation. State replacement or
-withdrawal preserves them; no subject preserves both. Subject-only declarations
+withdrawal preserves them; no subject preserves both. When a publication includes
+`state.work` with an explicit `topic` and no `subject`, the topic refreshes Current
+(the first such classification also sets Initial on a new record); an explicit
+`subject` in the same publication wins, and state-only refreshes never re-derive
+the alias from previously stored work. Subject-only declarations
 preserve state contents, recorded cwd and `recordedAt`: old progress is not a fresh
 status update. Publish subject and state together when changing work. New records
 use null/null until the first declaration; legacy records without aliases keep
@@ -104,7 +108,9 @@ receipts. Complete model-facing output and permissions remain unchanged.
 
 `orchestrator_session_id` also accepts optional `state`: strings named `objective`,
 `progress`, `decisions`, and `blockers` (2,048 UTF-8 bytes total). An object replaces
-all fields, `null` withdraws, and omission leaves the current record unchanged.
+all fields, `null` withdraws, and omission leaves the current record unchanged. An object
+without `progress` keeps the automatic todo progress line still published (dropped only
+when the merge would exceed the byte budget); an explicit `progress` replaces it.
 Extra keys, controls, and oversized input are rejected before naming or persistence;
 records additionally fit 4 KiB. Never include credentials, internal instructions,
 or raw prompts. Whitelisting is not automatic secret redaction.
@@ -266,10 +272,14 @@ are unchanged; caller replacement prevents a stale `recorded` result.
 Call `orchestrator_consult` with required stable `recipient_session_id`, optional
 `kind: "metadata"` (default), and optional existing opaque catalog `cursor`.
 No free-form question, owner request, human picker or read-consent dialog is used
-for this profile's explicitly published data. Publish `subject` and `state` together
-before work beyond small direct tasks; update at task changes and completion. Keep
-small direct tasks exempt. Batch with setup/progress; do not add a model turn solely
-to publish or emit per-tool/token updates.
+for this profile's explicitly published data. Declare a `subject` before work beyond
+small direct tasks. Progress is published automatically: after each todo write the
+runtime sets `progress` to `<done>/<total> done`, merged into the owner's curated
+fields, so the model never spends a turn reporting status. Todo titles are private work
+text and are never published; a cleared list removes the line, and a withdrawn state
+stays withdrawn until the owner publishes again.
+Keep small direct tasks exempt. Do not add a model turn solely to publish or emit
+per-tool/token updates.
 
 Use `objective` for the goal, `progress` for current and next scope, and `blockers`
 for anything preventing progress. Use `state.work` for relevant area/topic and

package/docs/gentle-music.md

@@ -0,0 +1,61 @@
+# Gentle Music
+
+`/gentle:music` plays [gentle-stream](https://github.com/Gentleman-Programming/gentle-stream) music from inside Gentle Shell.
+
+## Open the player
+
+```text
+/gentle:music
+/gentle:music rainy lo-fi night
+```
+
+The command hands the whole terminal to gentle-stream's own TUI, the same way Pi's external editor (`ctrl+g`) does. Any text after the command is passed as the mood (`--mood`), and the session's current model is passed as `--model provider/id`, so gentle-stream interprets the mood with the model you already use.
+
+Leave the player with:
+
+| Key | Result |
+| :-- | :-- |
+| `b` | Back to Pi; the music keeps playing. |
+| `q` | Back to Pi; the music stops. |
+
+Pi returns exactly as it was: the draft, the transcript, and the layout are redrawn. While the player is open, `ctrl+c` goes to gentle-stream, not to Pi. If gentle-stream exits with an error, Pi shows a short notice.
+
+Opening `/gentle:music` again while music plays attaches to the same music.
+
+## Control the music without leaving Pi
+
+A single control word runs `gentle-stream ctl …` in the background and shows the result as a notice. The terminal stays with Pi.
+
+| Command | Result |
+| :-- | :-- |
+| `/gentle:music next` | Next track. |
+| `/gentle:music pause` | Pause. |
+| `/gentle:music play` | Resume. |
+| `/gentle:music stop` | Stop the music. |
+| `/gentle:music status` | One line, for example `♪ Neon Rain · synthwave · playing`, or `nothing is playing`. |
+
+Only an exact single word is a control word. `/gentle:music next to the sea` opens the player with the mood `next to the sea`.
+
+## Stopping on exit
+
+When you quit Pi after using `/gentle:music`, Gentle Shell runs `gentle-stream ctl stop` so no music outlives the shell. It waits at most about 2 seconds. Starting a new session, resuming, forking, or reloading keeps the music playing.
+
+## Installation
+
+Gentle Shell looks for gentle-stream in this order:
+
+1. `gentle-stream` on `PATH`.
+2. `uvx`, running gentle-stream straight from its repository (the first run downloads it).
+3. `uv`, through `uv tool run`.
+
+With none of them, `/gentle:music` explains how to install and does nothing else. Install [uv](https://docs.astral.sh/uv/getting-started/installation/), or install gentle-stream permanently:
+
+```bash
+uv tool install 'gentle-stream[samples] @ git+https://github.com/Gentleman-Programming/gentle-stream'
+```
+
+## Limits
+
+- The player needs the interactive terminal. In RPC, JSON, and print modes, `/gentle:music` shows a notice and does nothing.
+- There is no default shortcut.
+- gentle-stream starts its own `gentle-shell` process to interpret moods; Gentle Shell does not pass its own launcher path.

package/docs/gentle-shell-uninstall.md

@@ -36,6 +36,11 @@ In this order:
      `GENTLE_SHELL_HOME` directory is removed only when Gentle Shell created it
      (its `.gentle-shell-home` marker, or its setup record in
      `~/.gentle-shell/config.json`); otherwise it is listed as kept.
+   - `~/.gentle-shell/gentle-ai`: the isolated home's own settings (profiles,
+     banner and the other preferences). The `gentle-ai` folder next to a
+     `GENTLE_SHELL_HOME` is only listed as kept, since it may not be Gentle
+     Shell's. When `GENTLE_PI_CONFIG_HOME` names it, the config home rules
+     below apply instead.
    - `~/.gentle-shell/config.json`: the launcher settings.
 2. **Shared Gentle AI configuration**, only when you accept it (see below).
 3. **The `gentle-pi` package**, with the package manager that owns it:
@@ -43,7 +48,9 @@ In this order:
    `npm uninstall -g gentle-pi`.
 4. **`~/.gentle-shell`**, only when it is empty.
 
-The config home is `GENTLE_PI_CONFIG_HOME`, or `~/.pi/gentle-ai`.
+The config home is `GENTLE_PI_CONFIG_HOME`, or `~/.pi/gentle-ai`: the one Pi
+with Gentle AI, `--link` and custom homes use, and where the main channel keeps
+its builds. The isolated home's own folder is removed with the data above.
 
 ## Shared configuration
 

package/docs/gentle-shell.md

@@ -8,10 +8,19 @@ Source map: [shell extension](../extensions/gentle-shell.ts), [shell bar](../lib
 
 ## Updating Pi safely
 
-Run `gentle-shell update` to update the Pi this launcher runs. Shell verifies npm/pnpm global listing JSON and canonical package roots before installing exactly one supplying package. This supports pnpm v11 linked stores without relying on `PNPM_HOME` containment. When the launcher runs its adjacent Pi peer, the supplier is the listed `gentle-pi` package itself: Shell is reinstalled at its current version so the package manager re-resolves the peer, because updating a separate global Pi never changes the peer a Shell install runs. A Pi found on `PATH` or through `GENTLE_SHELL_PI` is updated through its own listed global package; a package-manager shim is followed to the single `cli.js` it names. Pi and Shell are never combined into a comma install.
+Run `gentle-shell update` to update the Pi this launcher runs. It also works when that Pi is older than the required minimum version, which every other command refuses. Shell verifies npm/pnpm global listing JSON and canonical package roots before installing exactly one supplying package. This supports pnpm v11 linked stores without relying on `PNPM_HOME` containment. When the launcher runs its adjacent Pi peer, the supplier is the listed `gentle-pi` package itself: Shell is reinstalled at its current version so the package manager re-resolves the peer, because updating a separate global Pi never changes the peer a Shell install runs. A main-channel Shell (`<version>-main.<sha12>`) is never published, so it is reinstalled from the tarball `gentle-shell upgrade --channel main` packed under `<config home>/main/packages/` (an absolute `GENTLE_PI_CONFIG_HOME`, else `~/.pi/gentle-ai`; a relative override is refused); when that tarball is missing, `update` installs nothing and names the rebuild path (`gentle-shell upgrade --channel release`, then `--channel main`), because `upgrade --channel main` alone is a no-op when already at the latest main. A Pi found on `PATH` or through `GENTLE_SHELL_PI` is updated through its own listed global package; a package-manager shim is followed to the single `cli.js` it names. Pi and Shell are never combined into a comma install.
 
 Unknown or ambiguous ownership, npm source/link packages, and pnpm groups shared with other top-level packages refuse without installation changes. Separate groups in one aggregated listing are allowed. After the install, Shell reads the supplied Pi version back from a fresh listing and reports whether it changed. pnpm installs only releases older than its `minimumReleaseAge` setting (pnpm 11 defaults to 4320 minutes), so a very recent Pi release is picked up once it is old enough; Shell reports that rule instead of overriding it. Package managers run from the system temporary directory so a project's `packageManager` pin never changes which pnpm answers. Use the supplying package manager for source checkouts or unsupported layouts. `gentle-shell update --extensions-only` remains an extension-only Pi command; prefix-bundled Pi still updates with `gentle-shell upgrade`. See [managing packages](readme-reference.md#managing-packages) for the ownership contract.
 
+When the install fails, `update` names the package manager and the exact command it ran, then one sanitized line of that manager's own output. That line is the last error line (`Error:` or an `ERR_` code) in its stdout or stderr, stderr's when both have one, because npm prints its error on stderr while pnpm 11 prints `ERR_PNPM_*` on stdout. A warning on stderr never hides that error. Without any error line, it is the last line of stderr, else of stdout. Terminal escapes and control characters are removed, your home directory becomes `~`, and the line is at most 300 characters. For example:
+
+```text
+gentle-shell update: pnpm (/usr/local/bin/pnpm) could not install /Users/you/.pi/gentle-ai/main/packages/gentle-pi-<version>.tgz
+[ERR_PNPM_INVALID_VERSION_UNION] Invalid versions union. Found: "gentle-pi@file:...". Use exact versions only.
+```
+
+`ERR_PNPM_INVALID_VERSION_UNION` during `update` usually means more than one pnpm is installed: an older pnpm on `PATH` cannot read the `allowBuilds` key a newer pnpm wrote to the global `pnpm-workspace.yaml`. Keep a single standalone pnpm.
+
 ## v2.6.0 workspace updates
 
 The [v2.6.0 release](https://github.com/Gentleman-Programming/gentle-pi/releases/tag/v2.6.0) makes the workspace state more durable and inspectable:
@@ -21,7 +30,7 @@ The [v2.6.0 release](https://github.com/Gentleman-Programming/gentle-pi/releases
 - The Agents List and Details views preserve the orchestrator/session hierarchy and completion, abort, and lost-exit history. Parent-child queries and notifications have an explicit handoff path, while model, effort, and usage stay observable per task.
 - Named `/gentle:profiles` atomically route the orchestrator separately from packaged and review roles; see the [technical reference](readme-reference.md#agent-model-profiles) for the profile model.
 
-The source checkout prepares `gentle-pi` `4.0.0` with a package-local Gentle AI `v4.1.1` pin; this does not imply that the package release has been published.
+The source checkout prepares `gentle-pi` `4.0.0` with a package-local Gentle AI `v4.3.1` pin; this does not imply that the package release has been published.
 
 ## Shell interactions and runtime behavior
 
@@ -36,12 +45,12 @@ At 140 columns or wider, fullscreen defaults to a live header over a transcript-
 ```
 
 - The header carries live session data: session identity on the left (brand, cwd, branch, dirty count, model · effort · profile) and the two live counters right-aligned (the context gauge and session cost). The effort reads `auto` for NaN models that manage their reasoning depth themselves (DeepSeek V4 Flash, Qwen 3.8 Flash, MiMo), with a one-time notice explaining that the selected level does not change the depth. It never shows the working/thinking state or extension statuses — those stay in the prompt indicator and the Status surface. When the terminal is too narrow for everything, segments give way in a fixed order — profile, then effort, then the whole cwd/branch/dirty group — before the counters are touched; below that, only the brand survives, and below that the header renders nothing.
-- The right rail scrolls **Status → Changes → TODO**. Cards cache their rendered content until their own digest or an explicit invalidation changes. `neon` keeps the rounded border and accent title; `float` uses a tone background, a full-height `▎` accent, one-column transparent margins, painted padding above and below, and a blank painted separator between heading and body. Warning/error/success panels retain their tone colors.
+- The right rail scrolls **Status → Changes → Agents → TODO**. Cards cache their rendered content until their own digest or an explicit invalidation changes. `neon` keeps the rounded border and accent title; `float` uses a tone background, a full-height `▎` accent, one-column transparent margins, painted padding above and below, and a blank painted separator between heading and body. Warning/error/success panels retain their tone colors.
 - The Status card carries Project (cwd, branch, session name, active profile), Changes, and Integrations (other extensions' statuses); its live digest detects changes without requiring an event. Model, effort, context, cost, and the per-model usage table live in the header instead — the header ticks every frame, so duplicating them in a card would just make that card repaint every frame too.
-- Gentle Agents is not part of the rail in any mode: its one card stays above the editor, where it already lived, with fixed right-aligned columns for `model · effort`, tokens, cost, and elapsed, each sized to the widest value among the shown tasks — so the numbers line up vertically even when one row's values are much shorter than another's. A queued task fills only the elapsed column with the word `queued`, leaving the other columns blank rather than overwriting the row.
+- Gentle Agents follows TODO: while the fullscreen rail is showing, the Agents card moves into it and lists every shown task; without the rail (narrow fullscreen or regular mode) it stays above the editor. Its card has fixed right-aligned columns for `model · effort`, tokens, cost, and elapsed, each sized to the widest value among the shown tasks — so the numbers line up vertically even when one row's values are much shorter than another's. A queued task fills only the elapsed column with the word `queued`, leaving the other columns blank rather than overwriting the row.
 - The sidebar reuses its last frame until something it paints changes, so silent frames stay cheap; a per-section cache means one card's changing digest (or the header's) never forces an unrelated card to redraw.
 - Header placement is configurable. Above input, the float header has a full-width background, painted padding above and below its content, and a transparent `▔` bottom edge. Below input, the float footer groups Changes (when the session's roots have uncommitted work), header data, and locally owned integration statuses under one upper edge; it never duplicates statuses owned by the rail.
-- Below 140 columns, fullscreen has no sidebar. A configured top header owns the narrow status surface; otherwise the bottom bar owns it, unless Status is hidden. Regular mode keeps the compact one-line bottom bar and the above-editor Agents widget, without a fullscreen header or sidebar.
+- Below 140 columns, fullscreen has no sidebar. A configured top header owns the narrow status surface; otherwise the bottom bar owns it, unless Status is hidden. The Agents and TODO cards then return above the editor. Regular mode keeps the compact one-line bottom bar and the above-editor Agents widget, without a fullscreen header or sidebar.
 
 The regular-mode compact bar replaces pi's three-line footer with a single line of segments:
 
@@ -66,8 +75,32 @@ The prompt follows the selected card style. `neon` keeps pi's editor in its roun
 - The petal is still with a `waiting for input` label in float while pi waits, spins with a `working` label while the agent works, and turns amber with a `queued` label when messages are waiting behind the current turn. In float it lives inside the painted top row; in neon it lives in the top rule. Pi's own "Working" row above the editor is hidden.
 - The empty-editor typing hint appears only while the editor is empty; Esc/queued hints remain inside the painted top row even with a nonempty float draft. Widths below 10 columns or a missing/unusable background keep the complete neon prompt path.
 - With Vim editing off, the prompt selects text natively: `shift+home` / `shift+end` select to the line edge and `alt+e` selects the whole draft; backspace, delete, a printable key or a paste replaces the selection in one undoable edit. `alt+a` also selects all, but only when no extension shortcut claims it: by default it opens Gentle Agents. A registered extension shortcut always wins over these selection keys.
+- Pi's paste-image key (`app.clipboard.pasteImage`: `ctrl+v`, or `alt+v` on Windows) turns a clipboard image into an `[Image#N]` chip instead of a temp-file path. One Backspace or Delete removes the whole chip; cursor and word motions, word deletion, wrapping and Vim NORMAL treat it as one unit. On submit, every chip still in the draft is sent as a real image attachment, so the model sees it without calling `read`. A deleted chip is never sent. The bytes stay in memory; no temp file is written. See [Pasted images](#pasted-images).
 - If another extension already installed a custom editor, Gentle Shell leaves it alone.
 
+### Pasted images
+
+While a draft holds chips, a strip above the prompt lists each one:
+
+```text
+[Image#1] png · 1280×720 · 84 KB
+```
+
+- **Preview:** terminals with an image protocol (Kitty, Ghostty, WezTerm, Warp, iTerm2) draw a small thumbnail under each label while the agent is idle. While it works, and in terminals or multiplexers that hide the protocol (such as tmux), the label alone is shown, so streaming never re-sends the image to the terminal.
+- **Clipboard sources:** the native clipboard on macOS and Windows; `wl-paste` or `xclip` on Linux. On WSL, a Windows screenshot (`Win+Shift+S`) is read from the Windows clipboard through `powershell.exe`, because the Linux clipboard never receives it.
+- **What stays Pi's:** files copied in a file manager, text, and image formats other than PNG, JPEG, WebP and GIF go through Pi's own paste handler unchanged.
+- **Models without image input:** the strip warns before you send. If you send anyway, each chip becomes `[Image#N omitted: the current model does not accept images]` and a notice explains why, so nothing is dropped silently.
+- **Numbering:** numbers keep counting up for the whole session, so a chip recalled from prompt history never points at a newer image. A recalled chip is plain text; paste the image again to attach it.
+- **Sending while the clipboard is read:** reading the Windows clipboard on WSL takes about a second. If you send the message before it finishes, the image is discarded with a notice instead of landing in the next draft; paste again to attach it.
+- **Vim NORMAL:** the paste key enters INSERT and pastes the chip. NORMAL motions step over a chip as one unit; an operator whose range covers a chip removes it whole.
+- **Terminals that capture the paste key:** some terminals keep `ctrl+v` for their own paste, and nothing reaches Pi when the clipboard holds only an image (Warp on Windows does this). Bind a second key in `~/.pi/agent/keybindings.json`, then restart:
+
+  ```json
+  { "app.clipboard.pasteImage": ["ctrl+v", "alt+v"] }
+  ```
+
+### Changes
+
 Changes shows the **current Git state** — working tree against HEAD, untracked files included — of the session's repository and of every worktree or repository its subagents used that still exists. Nothing is scanned at startup; the list fills at the first turn end or when the panel opens, then refreshes at each turn end and while the panel is open. Fullscreen, the sidebar, and mouse interaction are unchanged.
 
 ```text
@@ -90,12 +123,13 @@ Captured evidence (`gentle-pi.session-change/v1`) is still stored for session st
 
 ### Browse changes
 
-`/gentle:changes` or `alt+g` opens the two-pane viewer. Worktrees are accordion groups on the left; each file row leads with its name, then its line counts and its directory. Selecting a file shows its full path on the first row of the right pane (clipped from the left so the name stays visible) and its diff against HEAD below it; untracked files show their full content.
+`/gentle:changes` or `alt+g` opens the two-pane viewer full screen, like Gentle Agents. Worktrees are accordion groups on the left; each file row leads with its status marker (`M` modified, `A` new and staged, `U` new and untracked, `D` deleted, `R` renamed), then its name, its line counts and its directory. Selecting a file shows its full path on the first row of the right pane (clipped from the left so the name stays visible) and its diff against HEAD below it; untracked files show their full content.
 
 - `j`/`k` or arrows navigate. On a group, Enter, Space or Right expands it; Left returns to its parent or collapses it. `ctrl+j/k` or Page Up/Down scroll the diff; Escape or `q` closes.
+- `F` toggles diff-only mode at any width: the file list and its separator hide so the diff uses the full width. There `j`/`k` still move between files (across worktrees; the path row shows which), the scroll keys and the wheel scroll the diff, `o`/Enter and `r` keep working, the first Escape returns to the file list, and `q` closes. Every opening starts with the file list visible.
 - Fullscreen left-click selects files; mouse wheels scroll the file list and diff independently. Hovering an unselected row (worktree or file, in either pane's list) paints it in the same shared hover role every clickable surface in the shell uses; it never opens or selects the file, and never overrides the already-selected row's own role.
 - Opening, pressing `r`, and the overlay's refresh cadence re-read each root's Git status; a same-line-count edit reloads the open diff.
-- On a file, `o` or Enter opens the actual current file in `$VISUAL` or `$EDITOR`, with its worktree as cwd.
+- On a file, `o` or Enter opens the actual current file in `$VISUAL` or `$EDITOR`, with its worktree as cwd. Editor launches pass paths as literal arguments, never through a shell. On Windows, configure a direct executable (for example `notepad.exe`); `.cmd`/`.bat` editor shims are refused. Launch failures appear as warnings after the terminal UI is restored. This also applies when opening an Agents session transcript. Editor commands retain literal-space splitting: quoted executable paths and shell expressions are not supported.
 - `GENTLE_PI_SHELL_CHANGES_KEY` rebinds the shortcut; `off` disables it. `GENTLE_PI_SHELL_CHANGES_POLL_MS` controls how often the open overlay re-reads Git. `GENTLE_PI_SHELL_CHANGES_WATCH_MS` no longer enables filesystem polling.
 - No uncommitted changes in the session's roots means no widget and an informational notice.
 
@@ -254,7 +288,7 @@ In the isolated Gentle Shell home, `settings.json` does not declare gentle-pi; t
 - Presence refresh is paged while the overlay is open. Graceful shutdown withdraws an instance; after abrupt closure its last heartbeat may remain visible for up to 15 seconds plus the time to complete the next directory refresh. A recent heartbeat is a heuristic, not proof that a process is alive. Same-profile, same-user processes share retained activity text; this is not an authorization channel.
 - `alt+s` confirms stopping the current active or queued subagents owned by the current process. `GENTLE_PI_AGENTS_STOP_KEY` rebinds it; `off` disables it.
 - Finished tasks are written to `~/.pi/agent/gentle-agents/tasks/` (one JSON per task, newest `history_max_tasks` kept, default 200) and come back on demand for `subagent_result` and `subagent_continue`; an id looked up this way from an unrelated session never enters the overlay or becomes cancellable. Child sessions live under `~/.pi/agent/gentle-agents/sessions/`.
-- `ctrl+shift+a` collapses the card to its first row (`GENTLE_PI_AGENTS_KEY`), `GENTLE_PI_AGENTS_VIEW_KEY` rebinds the overlay, `GENTLE_PI_AGENTS_PI` overrides the pi command used for children, and `GENTLE_PI_AGENTS=0` disables the tools and the card.
+- `ctrl+shift+a` or a left click on the card's `▾ Collapse` / `▸ Expand` header control collapses the card to its first row (`GENTLE_PI_AGENTS_KEY` rebinds the key), `GENTLE_PI_AGENTS_VIEW_KEY` rebinds the overlay, `GENTLE_PI_AGENTS_PI` overrides the pi command used for children, and `GENTLE_PI_AGENTS=0` disables the tools and the card.
 
 ### Background jobs
 
@@ -291,7 +325,7 @@ The `todo` tool and its card replace the third-party todo extension (remove `npm
 The runtime helps keep the list current beyond a static tool description:
 
 - `write` replaces the whole list in one call, so the model rewrites the plan instead of patching it; `add`, `update`, `clear`, and `list` remain for single moves.
-- Each agent run's system prompt carries the same byte-stable rules block (in_progress before starting, done right after finishing, update before ending the run), so the cached prompt prefix never changes because of the list. While tasks stay open, the current list reaches the model as a hidden, request-local message at the end of each request; it is never persisted and never enters the system prompt, so status, title, note and ordering changes cost only the tail of the request.
+- Each agent run's system prompt carries the same byte-stable rules block (in_progress before starting, done right after finishing, update before ending the run), so the cached prompt prefix never changes because of the list. While tasks stay open, the current list reaches the model as a hidden conversation message appended whenever the list changes, and closing the list appends a hidden "no open tasks" marker; the list never enters the system prompt and requests stay append-only, so status, title, note and ordering changes cost only the tail of the conversation and keep the provider prompt cache (Anthropic breakpoints, openai-codex input deltas) warm. When the conversation no longer holds the current list (after compaction, branch navigation, or in a session recorded before this behavior), the next request carries it once and it is appended again.
 - A list that goes two agent runs untouched while pending or in-progress tasks remain turns amber with `stale · N turns` on the card; that age is shown to the human only.
 - Within a long run, after four tool-use model turns without a successful todo write, the next model request receives one hidden, request-local reminder to review the plan. A successful `write`, `add`, `update`, or `clear` resets and rearms it; `list` and rejected writes do not. The turn containing the write does not count toward the threshold. Empty, finished and blocked-only plans receive no reminder. Reminder tracking restarts when the session loads; it does not change the existing card freshness, persist a message, start an extra model turn, change task statuses, or connect to subagents.
 
@@ -328,6 +362,43 @@ Expanded cards reserve at most one third of the terminal height (up to 16 rows,
 - Only top-level session files are read: subagent runs are not included, and the panel says so. The first opening scans every file; later openings reread only files that changed.
 - There is no default shortcut. Set `GENTLE_PI_STATS_VIEW_KEY` (for example `alt+t`) to bind one; `off` or empty leaves it unbound.
 
+### Gentle Design
+
+`/gentle:design <brief>` asks the session model to design the brief with the bundled `gentle-design` skill. It works with any provider: the model writes several clearly different directions (3 by default), each labeled with its tradeoff, as self-contained HTML artboards under `design/<slug>/`, plus a `design.json` manifest. Artboards inline their CSS, JS, and SVG and use system fonts, so they open offline in any browser. When `design/system.md` exists, the skill follows its tokens. Ask for changes to one artboard and only that file changes; "save and try a different approach" adds an artboard and keeps the others.
+
+You do not need the command: ask in plain language for a screen, mockup, landing page, or a few visual directions, and the session uses the gentle-design skill by default with any provider. After it writes or changes a design under `design/<slug>/`, the model opens the canvas on it (or refreshes the running one) through the `gentle_design` tool, unless you ask it not to. The same tool lists the designs and their artboards, shows whether the canvas is running and at which URL, stops the canvas, and starts the handoff of an artboard (`<slug>/<artboard>`) to the project's real stack, using exactly the text `/gentle:design implement` sends. Briefs and the design-system sync go through the skill itself. The `/gentle:design` subcommands remain available as optional shortcuts, and they share the same canvas server as the tool. Delegated subagents (`GENTLE_PI_AGENTS_CHILD=1`) do not get the default design flow.
+
+The canvas opens in navigation mode: the mouse wheel, trackpad, and drag always pan or zoom the canvas, even over an artboard, and Ctrl/Cmd + wheel zooms. Hovering an artboard shows "Click to use this design"; clicking it enters focus mode, which shows that artboard at its designed width at 100% and lets it own the pointer and keyboard, so its own scrolling, hovers, buttons, and inputs behave like the real page. While an artboard is in focus, the comments panel hides to make room, the rest of the canvas is dimmed and does not pan or zoom, and an artboard taller than the window scrolls inside its frame. To return to navigation mode, press the floating "Back to canvas" button or `Shift+Esc`, which works even while typing inside the artboard; plain `Esc` stays with the design, and the previous zoom, position, and comments panel are restored. Comment mode keeps working in both modes: a click picks an element instead of entering focus mode.
+
+- While the agent is busy, the run is queued as a follow-up.
+- `/gentle:design open [slug]` shows a design on a local canvas in the default browser: every artboard side by side at its manifest size, with its title and tradeoff; zoom with the buttons or Ctrl/Cmd + wheel, pan by dragging or scrolling, and Fit to the window. The canvas reloads an artboard when its file changes and the whole design when `design.json` changes. Without a slug it opens the most recent design. The URL is always printed; when the browser cannot be opened, open it manually.
+- `/gentle:design` with no arguments opens the most recent design (by `design.json` modification time) the same way. When the project has no design yet but has `design/system.html`, it and `open` show the canvas with only the system board; with neither, they print usage.
+- Comments: turn on Comment mode, click an element in an artboard, and type a comment. Every comment is saved in `design/<slug>/comments.json` with its artboard, CSS selector, text excerpt, date, and status (`open` or `resolved`), so any agent or later session can read it.
+  - **Send now** (the default) also sends the session one message with the design, the comment id, the artboard file, the selector, the excerpt, and the comment; while the agent is busy, it is queued as a follow-up.
+  - A comment can carry one screenshot, useful for what only shows between states, such as an animation or a transition: paste an image into the comment popover, drop one onto it, or use **Attach screenshot** (PNG, JPEG, WebP, or GIF, up to 5 MB). It is saved as `design/<slug>/.screenshots/<id>.<ext>`, named in the comment's optional `screenshot` field, shown as a thumbnail in the Comments panel, and reaches the session as an image attached to the comment message (a Send all message attaches at most 6; the rest are named for the read tool).
+  - **Collect** only saves the comment. **Send all (N)** then sends every open, unsent comment as one message. The canvas remembers the mode while the canvas server runs.
+  - A numbered pin marks each commented element and follows zoom and pan. The Comments panel lists open and resolved comments; selecting one highlights its pin and scrolls the canvas to it, and each comment can be resolved or reopened there. A comment whose element no longer exists shows as **Detached**.
+  - The agent applies a comment by editing only that artboard, then marks it resolved with the `gentle_design_comments` tool (`list` and `resolve`), or by editing `comments.json` when it has no tool. The canvas updates live when the file changes, whoever wrote it. Pi's `sendUserMessage` is fire-and-forget, so the canvas reports a delivery as failed (the comment stays saved and unsent) only when sending throws synchronously; a failure later inside the session is not visible to the canvas.
+- `/gentle:design stop` closes the canvas; quitting or replacing the session closes it too. There is one canvas server per session, and a second `open` reuses it.
+- `open` reuses the canvas tab that is already open: while a canvas page is connected, the command and the `gentle_design` tool tell that page to show the requested design and reload it from disk (keeping zoom, pan, and focus mode when it is the same design), and report "Design canvas refreshed" with the URL. The browser opens a new tab only when no canvas page is connected, for example after you closed it or when the server had to start.
+- `/gentle:design sync` (it takes no arguments; extra words warn and send nothing) asks the session model to capture the project's design system with the same skill (queued as a follow-up while the agent is busy). It reads, and never edits, the project's design sources: CSS custom properties (`:root`, `@theme`, `[data-theme]`), the Tailwind config or v4 `@theme`, component library folders, existing token files, and fonts. It writes two files:
+  - `design/system.md`: colors (token, value, usage), typography, spacing, radius, shadows, and component rules, each with the path it came from. Later design runs use only these tokens, and the skill checks every finished artboard's colors and fonts against them and fixes any deviation.
+  - `design/system.html`: a self-contained 1440 px artboard that renders those tokens and the core components.
+
+  When the project has no design sources, the model says so and proposes a minimal starter system instead of inventing project tokens.
+
+  You rarely need to run `sync` yourself. Before a new design, the skill calls the `gentle_design` tool's `list` action, which reports the project's design sources (the first 20 paths and a total) and the state of `design/system.md`. When the project has design sources but no `design/system.md`, the model syncs first, says so in one line, and then designs with those tokens. When the project has no design sources, it designs freely. When a source changed after `design/system.md` was written (by modification time), the model names it, says the tokens may be outdated, and offers to sync again; it re-syncs only with your OK. A design source is a `tailwind.config.{js,cjs,mjs,ts}`; a `.css`, `.scss`, or `.pcss` file that uses `@theme` or declares a custom property in a `:root` or `[data-theme]` rule; a `.json`, `.js`, `.ts`, or `.css` file whose name has `tokens` as a whole word (`tokens.json`, `design-tokens.ts`, `theme.tokens.css`; never `token.ts`, `refreshToken.ts`, `tokenizer.ts`, or a `.test`/`.spec` file); or a `theme.js`/`theme.ts` that exports a `colors` key. The detection walk skips `node_modules`, `dist`, `build`, `out`, `coverage`, every dot-directory (such as `.git`, `.next`, `.worktrees`), and the project's own `design/` folder; it does not follow symlinks, goes at most 6 directories deep, stops after 5000 files, and reads at most 256 KiB of each file.
+- When `design/system.html` exists, the canvas shows it as the first board of every design, labeled **Design system** with "Project tokens (design/system.md)", and reloads it when the file changes. Comment mode does not apply to that board (its tooltip says so): change the system by updating the design sources and running `sync` again.
+- `/gentle:design implement <slug>/<artboard>`, or **Implement this** on an artboard's header in the canvas (after a confirm step; never on the system board), sends the session one handoff message, queued as a follow-up while the agent is busy. Both send the same text: the artboard path, title, and tradeoff; an instruction to build it in the project's real stack with the artboard as the visual spec, mapped to existing components rather than copied; `design/system.md` as the token source when it exists; and every open comment on that artboard, to apply and then resolve with `gentle_design_comments`. An unknown design or artboard warns with the valid `<slug>/<artboard>` values and sends nothing. An invalid `feature` link in `design.json` is reported as a warning, and the handoff goes out unlinked. The handoff itself commits nothing.
+- ODD link: a design that comes from a tracked ODD feature records it in `design.json` as `"feature": "odd/tasks/<feature>.md"`, and the skill appends a Log entry naming the design to that document; small, untracked work has no `feature` and stays standalone. The canvas top bar shows **Feature: <path>** for a linked design, and the handoff asks to track the implementation in that document instead of sizing it from scratch. Only a relative `odd/tasks/<name>.md` path is accepted; any other value is ignored and reported as a warning in the canvas.
+- Handoff state: every handoff (the canvas button, the command, or the tool's `implement`) is recorded in `design/<slug>/handoffs.json` before it is sent, and the handed-off artboard becomes the design's **chosen** direction: its header shows a **Chosen** badge and an accent frame, and the other artboards show **Alternative**. Handing off another artboard moves the mark. After **Send**, a toast confirms it, and the artboard's header shows **Queued** (the agent was busy) or **Implementing…** (it was idle), then **In progress** and **Implemented ✓** as the agent reports them with the `gentle_design` tool's `handoff` action, which the handoff message asks it to call. The canvas updates live, the badge names the linked feature document, and `list` reports each design's chosen artboard and handoff states. When the agent marks an artboard implemented with the `previewUrl` of the running app, **Compare** shows the artboard and the app side by side at the artboard's size, at 100%, with **Scale to fit** when the pair is wider than the window; exit with **Back to canvas** or `Shift+Esc`. The preview must be an `http`/`https` URL on `localhost`, `127.0.0.1`, or `[::1]` (any port, no credentials, at most 2048 characters); the tool and the server refuse anything else. Prefer `localhost` or `127.0.0.1`: CSP has no IPv6 source form, so browsers do not frame a `[::1]` preview, and Compare says so and offers the new tab. An app that refuses to be framed (`X-Frame-Options` or `frame-ancestors`) still opens with **Open in new tab**, which the Compare view always shows.
+
+The canvas server binds `127.0.0.1` on a random port and needs a random per-server token in every URL. It rejects any `Host` other than its own loopback address, accepts every write (comments, Send all, resolve/reopen, Implement) only with its own `Origin` (`http://127.0.0.1:<port>` or `http://localhost:<port>`), a JSON body, and bounded lengths, keeps at most 500 comments per design, and serves only files under `design/` in the session cwd (design folders, plus exactly `design/system.html` for the system board), resolved by real path so neither `..` nor a symlink can escape. Artboards run in iframes sandboxed without `allow-same-origin`, so they cannot read the canvas or post comments themselves. The canvas may frame only loopback origins (its `frame-src`), and the Compare preview frame keeps its own origin (`allow-scripts allow-same-origin allow-forms allow-popups`, never top navigation) only because it is another origin than the canvas: the canvas refuses a preview on its own port, and sends no referrer, so the app never sees the token. No other network traffic is involved. The server and the tool write `comments.json` and `handoffs.json` one at a time through an atomic replace, and never overwrite a file they cannot parse.
+
+### Gentle Music
+
+`/gentle:music [mood]` hands the terminal to the [gentle-stream](https://github.com/Gentleman-Programming/gentle-stream) player, like Pi's external editor, passing the mood and the session model. In the player, `b` returns to Pi with the music playing and `q` returns and stops it. `/gentle:music next`, `pause`, `play`, `stop`, and `status` control the music without leaving Pi. Quitting Pi after using the command stops the music. gentle-stream runs from `PATH`, or through `uvx`/`uv` when it is not installed. See [Gentle Music](gentle-music.md).
+
 ### Bridge providers
 
 Idle Claude Bridge continuation uses the normal user-prompt lifecycle so prompt preparation and tool declarations are retained. Gentle Agents hides only its exact, uniquely generated reserved wake in Pi's interactive transcript; child result and query cards remain visible. Native providers keep their hidden `display: false` custom wake.

package/docs/install-wizard.md

@@ -59,7 +59,7 @@ it lets the window close.
 Current requirements come from `package.json` and
 [`gentle-ai-installer.mjs`](../scripts/gentle-ai-installer.mjs): Node ≥22.19.0,
 Pi ≥1.2.0, pnpm acquisition 11.1.1, Gentle Shell package 4.0.0 and package-local
-Gentle AI 4.1.1. Windows native source builds require Go ≥1.25.10 when the
+Gentle AI 4.3.1. Windows native source builds require Go ≥1.25.10 when the
 required usable native binary is missing. A reusable binary does not require Go.
 When a build needs Go and the user's Go is missing, older or unchecked, the installer uses
 its own [pinned Go](#pinned-go) instead of blocking.
@@ -787,9 +787,13 @@ publishes main builds, so main is built on this computer
      Gentleman-Programming/gentle-ai (GitHub API, raw SHA), runs
      `go install github.com/gentleman-programming/gentle-ai/v4/cmd/gentle-ai@<sha>`
      in a sealed Go environment (`GOPROXY=https://proxy.golang.org`,
-     `GOSUMDB=sum.golang.org`, `GOTOOLCHAIN=local`, `GOFLAGS=-modcacherw`), requires
-     the binary's version to end in that commit's first 12 characters, keeps it
-     under `<config home>/main/gentle-ai/<sha>/` and registers it as the
+     `GOSUMDB=sum.golang.org`, `GOTOOLCHAIN=local`, `GOFLAGS=-modcacherw`),
+     asks Go (`go list -m -json`, same environment) which module version that
+     commit is (a release tag such as `v4.2.0`, or a pseudo-version) and requires
+     its origin to be that exact commit, requires the binary to embed that module
+     version (`go version -m`) and to report it, all in the `.build` work
+     folder, and only then moves it to `<config home>/main/gentle-ai/<sha>/`
+     (a failed rebuild leaves an already registered build in place) and registers it as the
      `gentle-pi.dev-binary/v1` override, which never falls back to the pinned
      binary silently.
   2. `install-shell-main`: downloads the latest `main` commit's source tarball,
@@ -812,8 +816,28 @@ publishes main builds, so main is built on this computer
   a version it cannot check) it builds with the pinned Go under
   `<config home>/tools/go`, downloading and verifying it there with the same
   `acquireGo` as the wizard when no earlier run published it, and only when
-  Gentle AI is rebuilt. A failed download stops with `main-requires-tools`
-  before anything is built; the user's Go is never run for the build.
+  Gentle AI is rebuilt. A failed download stops the Gentle AI build with
+  `main-requires-tools` before it starts (a main Shell that moved is still
+  installed, as below); the user's Go is never run for the build.
+- When the Gentle AI step of `gentle-shell upgrade --channel main` fails (the
+  build, its verification, or getting the pinned Go) and the main Shell moved,
+  the upgrade still packs and installs that Shell, records no channel, prints
+  `Updated Gentle Shell to the latest main (<sha12>); Gentle AI was not updated.`
+  and exits 1 with the original error (code and message) followed by
+  `; Gentle Shell was updated to main <sha12> but Gentle AI was not: run
+  gentle-shell upgrade --channel main to finish`. The retry then rebuilds Gentle
+  AI with the new Shell's code, so a fix in the main-channel upgrade path reaches
+  an install whose own copy of it is broken; a cause the new Shell does not fix
+  (a Go download that keeps failing, for example) still has to be resolved first. Until then Gentle AI stays the
+  previously registered main build or the pinned binary: a rejected build is
+  never registered. When the Shell install fails as well, its error is reported
+  with `; Gentle AI was not updated either (<Gentle AI error>)`. An unexpected
+  error that has no main-channel code (a filesystem `EACCES`, for example) is
+  reported as `main-upgrade-incomplete` with its own message and the same
+  suffix, so neither the retry advice nor either error is lost. When the Shell
+  is already current, a failed Gentle AI step fails as before, with nothing
+  installed or recorded. The wizard's runner is the one bundled with the
+  downloaded installer and does not get this behavior from a newer main.
 - Trust: Gentle AI source is verified by Go's checksum database; the Gentle Shell
   source is fetched over TLS from GitHub by exact commit SHA, with no pinned
   digest. Main builds are development builds.
@@ -1029,6 +1053,13 @@ again, or add `$PNPM_HOME/bin` to PATH manually. For `acquire-go`, a detail
 starting with `Conflicting Go destination: ` selects
 `guidance.goDestinationConflict`: a folder from an earlier, interrupted run is in
 the way and is never replaced; remove that folder and run the installer again.
+For `install-version` and `install-global`, a detail with `spawn UNKNOWN` selects
+`guidance.codeIntegrityBlocked`: libuv reports a Windows code integrity refusal
+(Smart App Control, CodeIntegrity event 3077) of the `gentle-ai.exe` that
+gentle-pi's postinstall builds as `spawn UNKNOWN`. Windows has no per-program
+exception, so the guidance offers WSL or turning Smart App Control off (on
+Windows 11 it cannot be turned back on without reinstalling Windows) instead of
+network and registry advice.
 `scripts/installer-runner.mjs` exports the frozen
 arrays `blockedReasons` and `failedSteps`; a test requires guidance for exactly
 those entries, and the runner tests check that every reason and step their

package/docs/permission-modes.md

@@ -52,15 +52,16 @@ Changing the default does **not** change the current session. To return this ses
 | --- | --- |
 | **Normal** | Existing permission behavior; the default when no valid global preference exists. |
 | **Auto** | A separate reviewer using the current session model checks eligible actions against live user intent before execution. Local reads are classified too; locality does not exempt an action from explicit restrictions. |
-| **YOLO** | Standing permission for ordinary already-authorized work and delivery; no Auto classifier. Destructive and independent consent boundaries remain. [Full YOLO details](yolo-mode.md). |
+| **YOLO** | Standing permission for ordinary already-authorized work and delivery; no Auto classifier. Destructive and independent consent boundaries remain, except recursive removal of the session's own [temp scratch](yolo-mode.md#temp-scratch-removal). [Full YOLO details](yolo-mode.md). |
+| **Super Yolo** | No permission prompts at all, including data-loss confirmations and configured guardrail actions. The only remaining line is the sensitive-path guard: read/write/edit of `.env`, `.ssh`, keychains, `*.pem/*.key/*.p12/*.pfx`, `secrets/` and cloud credential files stays hard-blocked. Code-level catastrophic denies (`rm -rf /`, `--no-preserve-root`, `git reset --hard`, forced clean, force push) also remain. |
 
 ## Commands and menu
 
 | Command | Effect |
 | --- | --- |
-| `/gentle:mode normal`, `auto`, or `yolo` | Select exactly one mode for the current interactive primary session. |
+| `/gentle:mode normal`, `auto`, `yolo`, or `super-yolo` | Select exactly one mode for the current interactive primary session. |
 | `/gentle:mode status` or `/gentle:mode` | Show current mode and saved default. |
-| `/gentle:mode default normal`, `auto`, or `yolo` | Save the default for new primary sessions, leaving the current mode unchanged. |
+| `/gentle:mode default normal`, `auto`, `yolo`, or `super-yolo` | Save the default for new primary sessions, leaving the current mode unchanged. |
 | `/gentle:yolo enable`, `disable`, or `status` | Existing shortcut; enable selects YOLO, disable selects Normal. |
 
 In `/gentle:customize` → **Editor**, use **Session permissions** to change the current mode, or **Default permissions** to save a future-session preference. The original **YOLO: ON/OFF · session only** row still toggles the live mode; it does not save a default. Browsing, previews, and closing the menu do not grant permission.
@@ -116,6 +117,10 @@ The **Auto checks** status and `gentle-auto-permission` session entries account
 
 The dedicated `permission-mode.json` in Gentle Pi's resolved user config home contains a strict versioned preference. Saving uses a private atomic replacement; malformed or unreadable existing preferences fall back to Normal and refuse an overwrite until repaired. Use the human command/menu path rather than asking model tools to edit this authority file.
 
+Model `write`/`edit` calls keep the config home protected except for the main-channel updater's `dev-binary.json`, `channel.json`, `main/` and `tools/go`. Those destinations select or build executable code, so they still require authorization under the current mode's ordinary checks; Auto classifies them and can deny an update. They are not automatically allowed. Permission preferences, global and project `runtime-guardrails.json`, their parent directories and symlink aliases resolving to them stay blocked even if a classifier would allow the action. Other config-home state, including model routing, persona and privacy preferences, remains protected.
+
+Shell recognition remains deliberately conservative: commands mentioning the config home or policy filenames can still be blocked. This change does not relax shell protection, authorize routing around a denial, or turn the hook into a sandbox.
+
 Live mode selection is bound to the SessionManager, session ID and canonical Git clone identity, or the canonical workspace directory outside Git. Session replacement, shutdown and reload revoke live callbacks and pending actions. A newly initialized primary session may select its saved default; this is a new application of the global preference, not restoration of an old session grant. Disable the saved default as well if future sessions must stay Normal.
 
 ## Limits