docs(v1.10.0): adopt pi's fullscreen default and document the way back

Decision: keep pi 1.0.0's default (tuiMode "fullscreen"). No tuiMode is baked,
so the image follows upstream rather than pinning the fleet to either mode -
but "we inherited a changed default" is only acceptable if the revert is
written down, so it now is.

README gains a "Terminal UI mode" section ahead of the pi-atelier section,
because the two interact. It gives all three scopes, taken from pi 1.0.0's own
docs/settings.md and docs/cli.md rather than from the changelog prose:

  - permanent: "tuiMode": "regular" in ~/.pi/agent/settings.json
  - one session: pi --tui-mode regular   (the flag is real: cli.md:221)
  - one project: the same key in .pi/settings.json, which overrides the agent
    directory

It also documents the four related settings (fullscreenExitOutput,
fullscreenScrollbar, fullscreenCopyOnSelect, fullscreenWheelScrollLines) and
two things specific to this image:

  - tmux: fullscreen uses the alternate screen, so tmux copy-mode shows the
    pane history AROUND pi, not pi's transcript. That is the concrete reason
    someone here would want "regular" back.
  - fullscreenWheelScrollLines "auto" behaves differently over SSH (caps fast
    wheel spins at 6 lines/event) than in a local macOS terminal (1 line) -
    worth naming because this container is normally driven over SSH.
  - pi-atelier works in BOTH modes (upstream has handled regular vs fullscreen
    renderers separately since pi 0.84), so reverting costs nothing. Stated so
    nobody assumes the sidebar is the price of the old scrollback.

The python3 merge snippet in that section was RUN before being documented:
against a realistic settings.json under an overridden HOME, twice, confirming
it is idempotent and preserves sibling keys including nested objects and the
_comment fields the seeded file uses. Documented code that has never been
executed is a guess.

DOCKER_HUB.md gets a short version of the same note, because CI reads it from
the TAG and POSTs it to Docker Hub as full_description - a behaviour change
this visible should not require reading the repo to undo.

Gates: doc-drift 23 OK / 0 DRIFT / 0 SKIP / 0 FAIL; base-hash, workflow-shell,
skill-floor, lint-shell all rc=0.

CHANGELOG.md

@@ -111,12 +111,19 @@ jump, four new base packages and a new mailbox feature. The release carrying a
   are `*`, so a mismatch is silent at runtime) and that the atelier sidebar
   **paints**.
 
-  **User-visible behaviour change, deliberately not overridden.** 1.0.0 makes
+  **User-visible behaviour change: the TUI is now fullscreen.** 1.0.0 changed the
-  the TUI fullscreen by default, replacing the terminal's normal scrollback;
+  default `tuiMode` to `"fullscreen"`, which draws into the terminal's alternate
-  `tuiMode: "regular"` restores the old behaviour. No baked default is set, so
+  screen — so the transcript no longer accumulates in the terminal's (or tmux's)
-  the image inherits upstream's choice rather than silently pinning the fleet to
+  native scrollback. **Upstream's default is adopted deliberately**, not
-  either one. If the fleet wants the old scrollback, that is a one-line settings
+  inherited by omission: no `tuiMode` is baked, so the image follows pi rather
-  change, not a rebuild.
+  than pinning the fleet to either mode. The way back is documented in README
+  → *Terminal UI mode*: `"tuiMode": "regular"` in `~/.pi/agent/settings.json`
+  for every session, `pi --tui-mode regular` for one, or the same key in a
+  project's `.pi/settings.json` for one project. That section also covers the
+  four related `fullscreen*` settings — including `fullscreenWheelScrollLines`,
+  whose `"auto"` behaviour differs over SSH, which is how this container is
+  normally driven — and records that pi-atelier's sidebar works in both modes,
+  so reverting costs nothing.
 
 - **pi-atelier `v0.10.3` (`ed3837b`) → `v0.13.0` (`34d26f1`)** — closes the
   two-minor gap v1.9.5 named as the pi bump's residual risk. `peerDependencies`

DOCKER_HUB.md

@@ -56,6 +56,8 @@ Full setup guide — authentication for each provider (Anthropic, OpenAI, Gemini
 
 The entrypoint deploys/registers all of these on first container start. Re-running is idempotent and preserves user edits.
 
+**Terminal UI mode — fullscreen by default.** pi 1.0.0 made the TUI fullscreen, and this image adopts upstream's default. Fullscreen uses the terminal's alternate screen, so the transcript no longer lands in your terminal's (or tmux's) native scrollback. To get the previous behaviour back, set `"tuiMode": "regular"` in `~/.pi/agent/settings.json`, or pass `pi --tui-mode regular` for a single session. The bundled pi-atelier sidebar works in both modes. See the README for the related `fullscreenExitOutput` / `fullscreenScrollbar` / `fullscreenCopyOnSelect` / `fullscreenWheelScrollLines` settings — the last one behaves differently over SSH, which is how this container is usually driven.
+
 ### MemPalace (persistent agent memory)
 
 - **MemPalace** + MCP server — semantic search over conversation history, knowledge graph, diary; queryable via 29 `mempalace_*` tools inside pi

Dockerfile.variant

@@ -190,11 +190,13 @@ ARG USER_NAME=developer
 # (published 2026-10-01T19:15Z) and neither obsmem nor atelier has a commit
 # naming it. Acceptance must prove the obsmem workers CAP TURNS (peerDeps are
 # `*`, so a mismatch is silent) and that the atelier sidebar PAINTS.
-# USER-VISIBLE BEHAVIOUR CHANGE, deliberately NOT overridden here: 1.0.0 makes
+# USER-VISIBLE BEHAVIOUR CHANGE, decided rather than inherited: 1.0.0 makes the
-# the TUI fullscreen by default, which replaces the terminal's normal
+# TUI fullscreen by default, which replaces the terminal's normal scrollback.
-# scrollback. `tuiMode: "regular"` restores the old behaviour. No baked default
+# Upstream's default is ADOPTED on purpose and no `tuiMode` is baked here, so
-# is set, so the image inherits upstream's choice rather than silently pinning
+# the image follows pi instead of pinning the fleet to either mode. The revert
-# the fleet to either one.
+# is documented (README -> "Terminal UI mode"): `"tuiMode": "regular"` in
+# ~/.pi/agent/settings.json, `pi --tui-mode regular` for one session, or the
+# same key in a project's .pi/settings.json.
 ARG PI_VERSION=1.0.0
 ARG PI_TOOLKIT_REF=main
 ARG PI_EXTENSIONS_REF=main

README.md

@@ -358,6 +358,61 @@ DOT syntax errors instead of crashing. Then in Studio: open the PNG (or a
 `.md` that embeds it) and hit **refresh-from-disk** after each edit.
 Note: SVG is **not** in Studio's local-image-link allowlist — use PNG.
 
+## Terminal UI mode: fullscreen is the default (since v1.10.0)
+
+pi **1.0.0** changed the default terminal UI mode to **fullscreen**, and this
+image adopts upstream's default rather than overriding it. Fullscreen draws into
+the terminal's alternate screen, so pi's transcript no longer accumulates in your
+terminal's native scrollback — you scroll inside pi instead, and on exit pi
+prints the transcript (`fullscreenExitOutput`).
+
+That is a real behaviour change if you were used to the old mode, so here is the
+way back. Nothing in the image is pinned, so all three routes below work:
+
+| Scope | How |
+|---|---|
+| **Permanently, for every session** | add `"tuiMode": "regular"` to `~/.pi/agent/settings.json` |
+| **One session** | `pi --tui-mode regular` |
+| **One project only** | add `"tuiMode": "regular"` to that project's `.pi/settings.json` — project settings override the agent directory |
+
+The settings file is plain JSON and `tuiMode` is top-level, so the minimal
+permanent change is:
+
+```bash
+# merge the key without disturbing the rest of the file (python3 is always present)
+python3 - <<'PY'
+import json, pathlib
+p = pathlib.Path.home() / ".pi/agent/settings.json"
+d = json.loads(p.read_text()) if p.exists() else {}
+d["tuiMode"] = "regular"        # "fullscreen" is pi's default
+p.write_text(json.dumps(d, indent=2) + "\n")
+PY
+```
+
+If you stay on fullscreen, four related settings are worth knowing — all
+documented in pi's own `docs/settings.md` under *Terminal and display*:
+
+- `fullscreenExitOutput` — `"transcript"` (default) or `"resume-hint"`: what pi
+  leaves behind in the terminal when fullscreen exits.
+- `fullscreenScrollbar` — `"auto"` (default), `"always"`, `"hidden"`.
+- `fullscreenCopyOnSelect` — `true` by default; selecting text copies it.
+- `fullscreenWheelScrollLines` — `"auto"` by default. Relevant **here** in
+  particular: this container is normally driven over SSH, and over SSH `"auto"`
+  accelerates fast wheel spins to at most 6 lines per event (local macOS
+  terminals accelerate on their own, so there it moves one line). `Alt`+wheel
+  moves five times as far.
+
+Two notes specific to this image:
+
+- **tmux.** Fullscreen uses the alternate screen, so `tmux` copy-mode scrollback
+  shows the pane's history *around* pi, not pi's transcript. Scroll within pi,
+  or use `"tuiMode": "regular"` if you rely on tmux copy-mode to search the
+  conversation.
+- **pi-atelier.** The bundled sidebar works in both modes — upstream has handled
+  regular and fullscreen renderers separately since pi 0.84, including
+  fullscreen divider dragging and keeping sidebar text out of fullscreen
+  selection — so switching back to `regular` does not cost you the sidebar.
+
 ## Using pi-atelier (TUI sidebar)
 
 `pi-atelier` is bundled in **both** variants (vendored at `/opt/pi-atelier`,