projmux 0.15.2 → 0.16.0

package/docs/codex-installed-compatibility.md

@@ -2,9 +2,10 @@
 
 The machine-readable ledger is retained as historical liveness evidence only.
 It is **not** capability authority for `durable-zero-turn-resume` or
-`remote-new-session`; those predicates require the exact executable tuple and
-the Phase-1 conformance record described in
-[`codex-native-required-migration.md`](codex-native-required-migration.md).
+`remote-new-session`. The private generation pool that once owned that
+conformance record has been removed; see
+[`codex-native-required-migration.md`](codex-native-required-migration.md) for
+the payload-free create behavior that remains.
 The legacy [`codex-installed-capabilities.json`](codex-installed-capabilities.json)
 schema separates method evidence from the semantic result:
 
@@ -42,8 +43,8 @@ observation. It must not be cited as payload-free support.
 The observation historically extended the earlier `pre-turn-attach` owner.
 That hosted evidence remains run `33560743314`,
 aggregate artifact `9821171919`, where the same tuple's direct pre-turn
-qualification was `pass`. Neither pass is an input to the new exact
-payload-free capability authority.
+qualification was `pass`. Neither pass is capability authority for the
+payload-free predicates above.
 
 Scheduled and manual `Installed Codex Qualification` artifacts use
 qualification schema v2 and embed this schema-versioned capability ledger.
@@ -59,11 +60,5 @@ records `github-actions:33566050834:1`.
 - `TestInstalledIsolatedPreTurnBootstrapSmoke` — historical owner for
   turn-free start/read/loaded observation and live-Pane liveness; not a
   payload-free support verdict.
-- `TestInstalledExactPayloadFreeCapabilityMatrix` — exact private owner for
-  zero-turn start/read/stored-resume plus content-free remote-new liveness. It
-  sends no input or turn, so remote-new remains unknown.
 - `TestInstalledCensusDeletionReceiptHasOneOwnerPerPrimitive` — topology and
   protocol ownership plus the Phase 2 merge receipt.
-
-The maintained repository-wide list in `docs/agent-workflow.md` records the
-current Phase-1 authority separately.

package/docs/codex-native-required-migration.md

@@ -21,61 +21,7 @@ provider response is stored to produce that signal.
 The Phase-7 zero-turn durable-readiness failure is retained only as historical
 negative safety evidence. A typed Failed Agent with no Pane is not functional
 create success. Prompted native create, app-server picker resume, existing
-Agent resume, and generation-pinned routes keep their native contracts.
-
-## Exact payload-free capability authority (Phase 1)
-
-Payload-free qualification is now owned by
-`internal/integrations/agents/codexgeneration`. A record is valid for exactly
-one tuple: RoleTUI binary SHA-256 and size, RoleAppServer binary SHA-256 and
-size, app-server version, protocol transport/schema, private socket locator and
-bound-runtime digests, state-domain identity/path digest, and platform/arch.
-Changing any one axis is a cache miss. A missing, corrupt, trailing, future
-schema, stopped, or rebound tuple projects `unknown` and the Phase-0
-`plain-fallback`; no semver family, changelog, or successful `thread/read` is an
-authority substitute.
-
-The record reduces two independent executable predicates:
-
-- `durable-zero-turn-resume` requires the same hashed exact thread to pass
-  zero-turn start, independent read, and stored resume. Read visibility alone
-  cannot promote it. Exact 0.153.0 private evidence is read-visible but stored
-  resume is `unsupported/no-rollout-found`.
-- `remote-new-session` requires more than a living TUI. The remote-new thread
-  and the exact first real input's thread must match, the turn identity must be
-  present, and the content-free turn cardinality must be exactly one. An
-  unrelated first-turn event or liveness-only observation stays `unknown`.
-
-Evidence stores timestamps, digests, closed outcomes, cardinality, and boolean
-identity facts only. It has no field for prompts, provider output, turns,
-transcripts, socket paths, or state paths. Doctor JSON/text and the create
-planner consume the same immutable record projection. Phase 1 intentionally
-maps every verdict—including a supported private observation—to
-`plain-fallback`; the remote-new production launch belongs to Phase 2.
-
-The private installed matrix is opt-in and starts/stops only exact root-owned
-app-server and tmux fixtures:
-
-```sh
-smoke_root="$(mktemp -d /tmp/projmux-payload-free-XXXXXX)"
-env -u TMUX -u TMUX_PANE \
-  PROJMUX_CODEX_PAYLOAD_FREE_SMOKE_ROOT="$smoke_root" \
-  PROJMUX_CODEX_PAYLOAD_FREE_SOURCE_HOME=/absolute/private/copied-source-home \
-  PROJMUX_CODEX_PAYLOAD_FREE_0152_0=/absolute/0.152.0/bin/codex \
-  PROJMUX_CODEX_PAYLOAD_FREE_0152_1=/absolute/0.152.1/bin/codex \
-  PROJMUX_CODEX_PAYLOAD_FREE_0153_0=/absolute/0.153.0/bin/codex \
-  go test ./internal/testutil/codexinstalled \
-    -run '^TestInstalledExactPayloadFreeCapabilityMatrix$' -count=1 -v
-```
-
-An unset binary row is logged `unavailable`; the fixture never synthesizes a
-tuple. The installed probe sends no input, prompt, or turn. It may record
-content-free TUI liveness/loaded state, but remote-new remains `unknown`
-without a separately supplied exact first-real-input thread/turn observation.
-Use the documented short smoke-root shape: an overlong private tmux socket path
-is rejected before any lifecycle operation and cannot masquerade as liveness.
-After fixture cleanup the socket has no current route identity, so transient
-private evidence cannot be reused by another route.
+Agent resume, and stored-endpoint routes keep their native contracts.
 
 ## Native-required prompted create (0.14.0)
 
@@ -254,10 +200,6 @@ go test ./internal/integrations/agents/codexappserver/ -run TestStartDefaultThre
 | Both `--interactive-only` spellings are equivalent, and non-Codex providers refuse it at zero transactions | `TestInteractiveOnlyIsTheOnlyPlainCodexLaneAndBothSpellingsAreEquivalent` |
 | Payload cardinality × `--interactive-only` × readiness stays a closed pre-provider decision table | `TestCodexCreatePayloadCardinalityInteractiveOnlyAndReadinessOutcomeTable` |
 | Canonical and shortcut payload-free create are byte/argv-equivalent to the explicit plain lane and touch no provider route | `TestPayloadFreeCodexCreateUsesSafePlainFallbackAndInteractiveOnlyEquivalentLane` |
-| Exact tuple keys, immutable cache fixed points, and one-axis drift/corrupt/future/trailing fail closed | `TestCapabilityCacheInvalidatesEveryExactTupleAxis`, `TestCapabilityCacheCorruptFutureAndTrailingRecordsResolveUnknown` |
-| Read visibility and stored resume reduce independently; remote-new requires the exact first real thread/turn | `TestExactPayloadFreeCapabilitySeparatesReadVisibleFromStoredResumable`, `TestRemoteNewCapabilityRequiresExactFirstRealInputThreadAndTurn` |
-| Doctor and create plan consume byte-semantic identical capability projections while Phase 1 stays plain | `TestCodexPayloadFreeDoctorAndCreatePlannerShareExactRecordProjection`, `TestCodexPayloadFreeUnknownCapabilityCannotBypassPhaseZeroFallback` |
-| Available exact installed binaries are qualified independently in creator-live/closed private rows | `TestInstalledExactPayloadFreeCapabilityMatrix` |
 | Saved-default, provider-picker, and direct-provider AI intents produce one managed plain lane without native mutation | `TestEmptyPromptCodexSplitProducersKeepOnePlainCLILane` |
 | A failed plain launch rolls Registry and tmux back and never tries a provider lane | `TestPayloadFreeCodexPlainLaunchFailureRollsBackWithoutProviderMutation` |
 | The installed outcome requires a Running plain Agent/Pane, no session ref, zero provider-thread delta, diagnostic signals, isolated socket cleanup, and ambient mutation zero | `TestInstalledPayloadFreePlainFallbackOutcomeSmoke` |

package/docs/configuration.md

@@ -38,13 +38,15 @@ those folders exist:
 
 It does not assume a canonical repo root.
 
-Use Settings > Project Picker for the normal interactive flow:
+Use `Settings > Global > Projects` for the normal interactive flow:
 
-- `Project Root` sets, changes, or clears the saved primary root.
-- `+ Add Workdir...` appends one directory to the saved workdirs list.
-- `Workdirs` reviews and removes saved workdirs.
+- `Primary discovery root` sets, changes, or clears the saved primary root.
+- `Additional discovery roots > Add path` appends one directory to the saved
+  workdirs list.
+- `Additional discovery roots` reviews saved workdirs; each root's
+  `Remove discovery root` removes it.
 
-`Add Workdir > Type path manually...` skips the filesystem scan and is useful
+`Add path > Type path manually...` skips the filesystem scan and is useful
 for large mounts, WSL paths, NFS paths, or temporary project roots.
 
 The saved workdir file is:
@@ -56,7 +58,7 @@ The saved workdir file is:
 It stores one absolute path per line. Lines beginning with `#` are comments.
 The file is read only when no env root list is set.
 
-Workdirs are a **scan source and nothing else**. Adding a root, and scanning one,
+Saved workdirs are a **scan source and nothing else**. Adding a root, and scanning one,
 never registers a Registry Project: a discovered child is an unregistered
 candidate until `projmux create project --root <path>` or opening it once from the
 Projects sidebar registers that exact path. See
@@ -92,51 +94,11 @@ request with `projmux pin project migrate`; see
 [upgrading.md](upgrading.md#pins-are-typed-and-migrate-on-request) for the
 per-line outcomes and the ambiguity refusal.
 
-## Legacy Project Layout Snapshots
+## Legacy Project Layout Files
 
-Older checkouts may already have named layout snapshots in the legacy storage
-directory:
-
-```text
-<project>/.projmux/layouts/<name>.toml
-```
-
-The project context comes from `PROJMUX_CWD` when set, otherwise projmux walks
-upward from the current directory to the nearest `.projmux` or `.git` marker.
-Files outside that project tree are not discovered. This storage is treated as
-legacy import data for explicit conversion and preview. Closed-Project startup
-does not expose legacy snapshot choices; current user-facing surfaces describe
-the restore unit as a snapshot, not as a separate layout or preset feature.
-
-The legacy schema is intentionally close to the session-state snapshot shape:
-
-```toml
-schema_version = 1
-description = "Daily dev"
-mode = "inherit-autosave" # default; or "fresh-each-time"
-default_cwd = "${PROJMUX_CWD}"
-
-[[windows]]
-index = 0
-name = "main"
-layout = "..."
-active_pane_index = 0
-
-[[windows.panes]]
-index = 0
-cwd = "${PROJMUX_CWD}"
-command = "make watch"
-```
-
-`command` records a startup recipe, matching the supported session-state replay
-recipe. Panes without `command` may use `recipe = "shell"`. Supported
-interpolation placeholders are limited to `${PROJMUX_CWD}` and
-`${PROJMUX_SESSION}`; other `${...}` values are rejected during load.
-
-Unknown fields and unknown sections are ignored so future schema additions do
-not break older files. The built-in parser only accepts quoted strings and
-integer values for the known fields above; it does not implement the full TOML
-language.
+Older checkouts may still have named layout files under
+`<project>/.projmux/layouts/*.toml`. projmux no longer reads, writes, trusts,
+or deletes them; they have no effect and can be removed by hand.
 
 ## Keymap File
 
@@ -234,7 +196,7 @@ popup action with no built-in shortcut. Every configured alias renders the
 canonical client-scoped body
 `projmux internal tmux popup-toggle --client #{client_tty} resource-inspector`; pressing
 the same alias again closes only that client's popup. It remains available on
-Linux/tmux even when the Labs live-resource status segment is off.
+Linux/tmux even when the `Status Bar > Resources` live-resource segment is off.
 
 The Settings writer is deterministic and rewrites the supported saved subset
 only. If the existing file has parse errors or unknown action IDs, Settings
@@ -342,6 +304,7 @@ success = "#5faf87"
 action_required = "#ffaf00"
 pane_active_bg = "default"
 focus = "#00ffff"
+provenance = "#ff8700"
 ```
 
 `text_primary` controls primary content text in native terminal-rendered UI.
@@ -360,6 +323,13 @@ active-pane background tint, and `focus` is the active-pane border color. Each
 of these is a public token: leave it unset to keep the historical built-in
 color, or set it to repaint the matching chrome.
 
+`provenance` is the compact usage label color for a provider row whose numbers
+came from a fallback data source rather than its authoritative one (today: a
+Codex row outside a healthy app-server). It is independent of `warning` and
+`critical`, which stay reserved for usage thresholds, and of the ordinary AI
+label color; the fallback value is orange. See `docs/usage-tracking.md` for what
+the label looks like and `docs/theme-palette.md` for the preset contract.
+
 Supported presets are `projmux`, `high-contrast`, `blue-hour`, `carbon-violet`,
 `daylight`, `ember`, `forest`, and `rose`. `daylight` is the fully-light
 preset; the others are dark. Preset colors paint projmux chrome only (status
@@ -457,30 +427,11 @@ in-flight process decision, then retries proxy initialization with a bounded
 backoff. Projmux never automatically stops, kills, restarts, adopts, or enables
 remote control on the shared app server.
 
-The default `Codex` row in the provider picker launches immediately through the
+The `Codex` row in the provider picker launches immediately through the
 canonical create route. It does not start or probe the app-server, call
 `model/list`, or add `--model` or `model_reasoning_effort`; the Codex process
-therefore keeps its own configured defaults.
-
-The separate `Codex advanced launch` action uses the readiness path to read
-every page of the current app-server `model/list`. Its second picker shows only
-visible models and their advertised reasoning efforts. The display also carries
-the advertised default, supported input modalities, and whether personality is
-supported; the boolean personality capability is not expanded into invented
-personality choices. The selected model and effort are launch-only CLI
-overrides (`--model` and `--config model_reasoning_effort=...`); Projmux never
-writes a Codex configuration file. Each normalized catalog is tied to its live
-connection and negotiated-version epoch. Projmux retains that connection from
-picker render through pre-create validation and refreshes `model/list` before
-building argv, so a disconnect or removed option invalidates the selection. If
-advanced discovery fails, is empty, or comes from an older Codex, that action
-reports the exact unavailable reason and creates nothing; the separate default
-`Codex` row remains available.
-
-Picker chrome and semantic annotations such as default, unspecified modality,
-and personality support use the Projmux message catalog. Model display names,
-effort identifiers, and advertised modality tags remain exact provider data and
-are not translated.
+therefore keeps its own configured defaults. The picker has no per-launch model
+or effort row.
 
 `projmux agent review` starts `review/start` only for a Running Codex Agent whose
 Registry Agent, owned Pane, activation generation, stored thread, and live Pane
@@ -517,6 +468,76 @@ desktop intent for both app-server and hook-fallback authority. Existing
 runtime override exists, take precedence only while hook fallback is current;
 they are never inferred or copied into the semantic policy store.
 
+## Split Start Directory
+
+New splits start in the owner Project root. `[ai] split_cwd_from = "pane"`
+starts UI splits in the active Pane's live directory instead, while that
+directory is inside the owner Project root. Settings exposes the same value as
+`AI > New splits start in` (`Project root` / `Current Pane directory`); choosing
+one writes only the global `[ai] split_cwd_from`.
+
+Config paths (global and project both honored):
+
+```text
+~/.config/projmux/config.toml      # global
+<project>/.projmux/config.toml     # project
+```
+
+Schema:
+
+```toml
+[ai]
+split_cwd_from = "project" # project|pane; where a new shell or Agent split starts
+```
+
+Resolution depends on who starts the split.
+
+**CLI** (`create pane`, `create agent`, and the provider shortcuts) — the flag
+only:
+
+1. `--cwd-from project|pane`
+2. otherwise `project`
+
+The CLI opens no config file for this decision. A CLI result is determined by
+its arguments, so scripts and automation keep starting in the Project root when
+someone changes this setting.
+
+**UI** (keybinding splits, the launcher, the resume picker's new row, and the
+Pane menu) — the config tiers:
+
+1. an explicit per-call value (flag)
+2. project `[ai] split_cwd_from`, read from the owner Project root
+3. global/user `[ai] split_cwd_from`
+4. built-in default (`project`)
+
+There is no environment override, and an unknown value skips its own tier. The
+project tier is always read from the owner Project root, so where a Pane sits
+never changes which config decides. The Settings row shows the UI result and the
+tier that decided it (`project`, `global`, or `default`).
+
+With `pane` selected, the active Pane is the origin of the split: the Pane a
+keybinding ran in, the Pane a right-click menu was opened on, or the anchor Pane
+a CLI create resolved. Its live directory is used only when it is inside the
+owner Project root. `$HOME`, another registered Project tree, a directory that no
+longer exists, and an unreadable directory all start in the Project root and
+report one line naming the reason and that root — on stderr for a CLI create
+with `--cwd-from pane`, and as one client message for a split started from the
+UI. A split is never refused for this reason. `--cwd` on `create agent` still
+names the Agent working directory outright and ignores this setting.
+
+## Enabled AI Providers
+
+Disabled providers are a central policy, stored in
+`${XDG_CONFIG_HOME:-$HOME/.config}/projmux/ai-enabled-agents`, that the CLI
+honors as well as the UI: `create agent`, `create window --provider`, and
+`agent resume` refuse a disabled provider, and the refusal names the command
+that re-enables it.
+`projmux config providers` lists every provider as `<id> enabled` or
+`<id> disabled`; `projmux config providers --enable <id>` and
+`--disable <id>` change one through the same writer as
+`Settings > Global > AI > Enabled providers`. A missing file means every
+provider is enabled; disabling every provider persists as none enabled.
+
 ## AI Resume Picker
 
 The Agent resume picker lists the most recent
@@ -526,7 +547,7 @@ the defaults are 30 rows and depth 0 (the current directory only).
 
 Preferred interactive path:
 
-- `Settings > AI Settings > Resume picker`
+- `Settings > Global > AI > Agent Resume Picker` (`Picker limit`, `Scan depth`)
 
 Config paths (global and project both honored):
 
@@ -584,17 +605,8 @@ existence/mtime. They do not open SQLite content and do not treat `.db-wal`,
 latest-session floor rather than complete history. Missing/malformed cache,
 workspace-less metadata, and stale mappings degrade to legacy `history.jsonl`
 without changing the shared exact/depth/sort/cap behavior.
-Live hook/session-state resume metadata is a separate high-confidence lane and
-is not a disk-picker candidate. When a disk picker selection creates a pane,
-its source is persisted so Session State preview and doctor can report medium
-confidence for DB-validated cache sources or low confidence for legacy history.
-
-Session State saves the exact bound Codex session/thread id before considering
-discovery. An existing bound session id or persisted resume id is replayed
-without an app-server read. Only a thread-only candidate is validated with
-`thread/read` and `includeTurns=false`; this validation is probe-only and never
-starts the shared daemon. Failure retains the persisted id or uses the current
-rollout fallback, and a read response can never substitute a different id.
+Live hook resume metadata is a separate high-confidence lane and is not a
+disk-picker candidate.
 
 ## Release channel
 
@@ -638,7 +650,7 @@ installed; that install stays put until its stable line ships.
 
 | Variable | Purpose |
 | --- | --- |
-| `PROJMUX_PROJDIR` | Explicit primary project root. Accepts an OS-native PATH-style multi-value: the first non-empty entry is the primary root and later entries are prepended to managed-root discovery. The primary value is memoized to `~/.config/projmux/projdir`. |
+| `PROJMUX_PROJDIR` | Explicit primary project root. Accepts an OS-native PATH-style multi-value: the first non-empty entry is the primary root and later entries are prepended to managed-root discovery. The primary value is memoized to `~/.config/projmux/projdir`. The legacy `PROJDIR` and `RP` env vars are no longer honored. |
 | `PROJMUX_MANAGED_ROOTS` | Search-root override. Uses the OS-native path-list separator and takes priority over the saved workdirs file and default weak probes. |
 | `TMUX_SESSIONIZER_ROOTS` | Legacy alias still honored at runtime for managed roots. |
 | `PROJMUX_LOCALE` | UI locale override. `auto` resumes detection; `en-US` and `ko-KR` pin supported locales. Unsupported tags fall back to `en-US` and surface a Settings warning. |
@@ -650,12 +662,12 @@ installed; that install stays put until its stable line ships.
 | `PROJMUX_DESKTOP_NOTIFY_MODE` | OS desktop notification mode override. `off` / `none` / `notify` (case insensitive). When set, this takes priority over every other resolution rung. The in-app notify queue is not affected. The retired `raise` / `auto-raise` / `autoraise` literals are still accepted and read as `notify`. |
 | `PROJMUX_DESKTOP_NOTIFY` | Legacy on/off override kept for backward compatibility. `on` maps to `notify`, `off` maps to `none`. Honored only when `PROJMUX_DESKTOP_NOTIFY_MODE` is unset. |
 | `PROJMUX_WSL_TOAST_ICON_DIR` | Directory used when copying the WSL toast icon into a Windows-readable path. |
-| `PROJMUX_USAGE_STATE_DIR` | Override directory for AI usage snapshots. Defaults to `<state>/projmux/usage`. Point this at a synced directory to share authoritative usage across machines. |
+| `PROJMUX_USAGE_STATE_DIR` | Override directory for AI usage snapshots. Defaults to `<state>/projmux/usage`. Point this at a synced directory to share authoritative usage across machines. The value is used as given, with no `~` expansion. |
 | `PROJMUX_USAGE_DEBUG` | When non-empty, prints adapter errors from the `projmux internal status usage` renderer to stderr. |
 | `PROJMUX_USAGE_LIMITS_PATH` | Deprecated. Read but ignored; limits now come from upstream APIs and local Codex rollout state. |
-| `PROJMUX_SESSIONSTATE_AUTOSAVE` | Session snapshot autosave override for the global fallback. Values such as `off`, `false`, or `0` disable autosave for projects that inherit the global setting; explicit project auto-save `on`/`off` still takes precedence. |
-| `PROJMUX_SESSIONSTATE_DEBUG` | When non-empty, quiet autosave surfaces suppressed session-state errors to stderr. |
-| `PROJMUX_FOCUS_DEBUG` | When non-empty, `projmux focus` prints one telemetry line to stderr. |
+| `PROJMUX_SESSIONSTATE_AUTOSAVE` | Ignored. Project snapshots and their auto-save were removed. |
+| `PROJMUX_SESSIONSTATE_DEBUG` | Ignored. It only gated stderr for the removed quiet autosave. |
+| `PROJMUX_FOCUS_DEBUG` | When non-empty, `projmux focus` prints one telemetry line to stderr with the target, session, window, pane, socket, client, source, and kind. |
 | `PROJMUX_INSTALLER` | Installer source hint used by update flows. npm installs set this automatically; advanced release installs can set `github-release`. |
 | `PROJMUX_RELEASE_CHANNEL` | Release channel the update judgment is made against, orthogonal to `PROJMUX_INSTALLER`. Only an exact `rc` opts in; unset, empty, and unrecognised values all mean the default `stable` channel, which never sees a prerelease. An rc install is answered with whichever of the stable and rc lines is newer, so it returns to stable as soon as that line ships. Read only until `[update] release_channel` exists; see [Release channel](#release-channel). |
 | `PROJMUX_SHELL_UPDATE_CHECK_TIMEOUT_MS` | Timeout in milliseconds for the best-effort release check attempted by `projmux shell` when the update cache is missing or stale. Invalid, zero, or negative values use the default. |
@@ -706,7 +718,7 @@ export PROJMUX_PROJDIR="/main/repos:/srv/work/repos"
 On Linux and macOS the separator is `:`. On Windows-style paths the separator
 is `;`.
 
-## tmux Project Root Option
+## tmux Primary Discovery Root Option
 
 The switch command also reads this tmux option:
 
@@ -768,7 +780,8 @@ seconds window. Resolution priority is:
    `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/ai-notify-dedupe-seconds`
 3. default `120`
 
-Settings exposes this at `Settings > Notifications > AI notification dedupe`.
+Settings exposes this at
+`Settings > Global > Notifications > Desktop delivery > Dedupe window`.
 The value is stored as integer seconds and applies only to AI desktop
 notification dispatch. The tmux bell fallback keeps its fixed 5 second
 dedupe window.
@@ -853,7 +866,7 @@ Settings press through the new row writes `desktop-notify-mode`, mirrors the
 new value into `@projmux_desktop_notify_mode` when tmux is live, and leaves the
 legacy key unused. No eager rewrite of tmux state.
 
-Toggle from Settings > Notifications > `Desktop notifications`. The
+Choose it from `Settings > Global > Notifications > Desktop delivery > Delivery mode`. The
 Settings info row labels the effective source as `env`, `env (legacy)`,
 `setting`, `setting (legacy)`, or `default` so users see which rung of
 the cascade pinned the value. `projmux config apply` regenerates the live tmux
@@ -899,28 +912,35 @@ ${PROJMUX_USAGE_STATE_DIR:-${XDG_STATE_HOME:-$HOME/.local/state}/projmux/usage}/
 See [Usage tracking](usage-tracking.md) for adapter behavior, throttling, and
 failure handling.
 
-## Session State
-
-`projmux shell` autosaves session snapshots from the app tmux status tick. The
-autosave command is quiet and debounced per session, and stores snapshots under
-`${XDG_STATE_HOME:-$HOME/.local/state}/projmux/sessions`.
-
-Global auto-save defaults to `off` on a fresh install. Project auto-save is an
-override with `inherit`, `on`, and `off`; `inherit` follows the global value,
-while `on` and `off` take precedence. Auto-save only updates the latest
-snapshot. Named snapshots are manual and are never updated by auto-save.
-
-With no saved preference, Project open from the Alt-1 sidebar shows a native
-`Start project` step with exactly `Continue project` and `Recreate Project`.
-Settings > Projects > Project Sidebar > Closed Project startup reports this as
-`Continue project / Recreate Project - default`. A saved `on` keeps the same explicit
-choice and reports `Continue project / Recreate Project - on - saved`. A saved `off`
-reports `Continue project - off - saved` and skips the picker: a registered root
-continues, while an unregistered root follows the existing Fresh adjudication.
-Resolving or cancelling the missing-file default never creates the preference
-file or changes saved bytes or mtime. `Recreate Project` confirms first, then atomically replaces the old Project graph
+## Project Startup
+
+The Registry (`registry.json`) is the only saved Project state; see
+[session-restore.md](session-restore.md). projmux keeps no separate Project
+snapshot store. Nothing reads the former
+`${XDG_STATE_HOME:-$HOME/.local/state}/projmux/sessions/*.json` snapshot
+files; they are removed by `config apply`. The app tmux status tick saves
+nothing: generated status lines carry no auto-save job, and the hidden
+`internal tmux autosave-session-state` route that older generated configs
+still call is a silent no-op that writes nothing and records no diagnostics.
+The `sessionstate-autosave` and `sessionstate-autosave-interval` files and the
+per-Project `sessionstate-projects/<session>/autosave` files are removed by
+`config apply`, together with the `sessions/` and `sessionstate-projects/`
+directories once they are empty. Any other entry there is kept, and listed
+by the apply that removes the files.
+`PROJMUX_SESSIONSTATE_AUTOSAVE` is still ignored without a warning.
+
+Opening a registered closed Project from the Alt-1 sidebar shows a native
+`Start project` step with exactly `Continue project` and
+`Clear layout and open`. A root that is not a registered Project skips that
+step and opens fresh, which registers it. There is no setting that skips the
+step for a registered Project.
+An explicit `Continue project` on a root that is not a registered Project
+refuses with zero writes and points to `Clear layout and open`.
+`Clear layout and open` clears only the saved Window and Agent layout: the
+folder, its files, `.projmux/config.toml`, and trust stay. It confirms first,
+then atomically replaces the old Project graph
 with a new Project UID and a new canonical Window/shell UID pair. Exactly one
-same-root Project claimant remains. Snapshot bytes, the root directory,
+same-root Project claimant remains. The root directory,
 Git/worktree data, and the trust decision remain unchanged. Esc returns to
 Projects with zero writes. After
 the startup mode is selected, project automation trust is evaluated if needed.
@@ -932,62 +952,17 @@ Deny/cancel refreshes the original sidebar query/selection context with a
 visible status message. Existing sessions switch directly without a startup
 picker.
 
-Default `projmux shell` no longer opens a startup picker or replays session-state
-snapshots before attach. It still derives the default app session identity and
-startup directory from the current project context when available; otherwise it
-uses the `home` target and home directory. Snapshot restore is an explicit CLI
-operation that requires both the source session and the exact target Project;
-it is not a Project-startup choice.
-
-Settings > Session State is global settings only: global auto-save, auto-save
-interval, and storage/retention policy. Settings > Project > Session State
-is override/effective-focused: project identity, project auto-save
-`inherit`/`on`/`off`, effective auto-save value/source, and snapshot save
-actions. Snapshot inspection lives under `Projects > Sessions > State`, whose
-overview shows latest/named snapshot status and the window -> pane read model
-without immediate mutation.
-
-The saved global toggles live under
-`${XDG_CONFIG_HOME:-$HOME/.config}/projmux/sessionstate-autosave`,
-`${XDG_CONFIG_HOME:-$HOME/.config}/projmux/sessionstate-autosave-interval`, and
-`${XDG_CONFIG_HOME:-$HOME/.config}/projmux/sidebar-startup-picker`. Project
-auto-save overrides live under
-`${XDG_CONFIG_HOME:-$HOME/.config}/projmux/sessionstate-projects/<session>/autosave`.
-The environment variables above override the global files.
-`sidebar-startup-picker` accepts the existing `on` and `off` bytes; absence is a
-read-only effective `on - default`, not a migration or an implicit write.
-
-Manual snapshot actions are available from the CLI:
+Default `projmux shell` does not open a startup picker before attach. It
+derives the default app session identity and startup directory from the
+current project context when available; otherwise it uses the `home` target
+and home directory.
 
-```sh
-projmux get snapshots
-projmux create snapshot
-projmux delete snapshot [--session <name>]
-projmux restore snapshot --session <snapshot-session> [--project <ref> | -p <ref>] --dry-run
-projmux restore snapshot --session <snapshot-session> [--project <ref> | -p <ref>] --yes [--client <tmux-client>]
-```
+The retired closed-Project startup setting's file under
+`${XDG_CONFIG_HOME:-$HOME/.config}/projmux/` is not read, and `config apply`
+removes it; see [Upgrading](upgrading.md#closed-project-startup-setting-removed).
 
-`status` prints the source label (`autosave`, `layout(<name>)`, or `fresh`), the
-effective auto-save state, and a compact snapshot preview for the
-target session. Older snapshots without a source field display as `autosave`.
-`save` captures the current tmux session immediately and intentionally bypasses
-the autosave debounce and disabled-autosave gate; it still requires a current
-tmux session. `delete` removes the target snapshot without an interactive
-confirmation. Restore treats the snapshot as desired-state input for one exact
-closed Project, never as a global Registry replacement or tmux replay.
-`--dry-run` prints scoped projection counts with zero writes. `--yes` commits
-that target subtree atomically, runs the ordinary materializer, and performs an
-explicit client handoff last when `--client` is present. Restore never modifies
-or deletes the source snapshot.
-
-Interactive `projmux quit` also offers `Save Project snapshots and quit`. It
-recaptures the latest snapshot for every live Registry-bound Project on the
-exact app server, regardless of the global or Project auto-save toggle, and
-stops the server only after all captures succeed. A partial failure keeps the
-server running and keeps each successful atomic snapshot for inspection or
-retry. Control/Home, ephemeral, unmanaged, conflicted, and sibling-server
-sessions are never promoted into Project snapshots. `Quit without saving`,
-`quit --yes`, and `quit --force` perform no snapshot inventory or store I/O.
+Interactive `projmux quit` offers only the quit row and `Cancel`. Neither it
+nor `quit --yes` / `quit --force` saves Project state.
 
 ## Decoration Mode
 
@@ -1016,9 +991,8 @@ independent global presentation preferences:
 
 - `Notifications HUD > Visible`
 - `Agent Usage HUD > Visible`
-- `Agent Usage HUD > Claude|Codex|Antigravity > Visible`
-- each provider's supported HUD windows (`Claude`/`Codex`: `5h`, `Weekly`;
-  `Antigravity`: `Weekly`)
+- `Agent Usage HUD > Claude|Codex > Visible`
+- each provider's supported HUD windows (`5h`, `Weekly`)
 
 The saved values are `on` or `off` in these files:
 
@@ -1027,12 +1001,10 @@ The saved values are `on` or `off` in these files:
 ~/.config/projmux/statusbar-visibility-agent-usage-hud
 ~/.config/projmux/statusbar-visibility-agent-usage-provider-claude
 ~/.config/projmux/statusbar-visibility-agent-usage-provider-codex
-~/.config/projmux/statusbar-visibility-agent-usage-provider-antigravity
 ~/.config/projmux/statusbar-visibility-agent-usage-window-claude-5h
 ~/.config/projmux/statusbar-visibility-agent-usage-window-claude-weekly
 ~/.config/projmux/statusbar-visibility-agent-usage-window-codex-5h
 ~/.config/projmux/statusbar-visibility-agent-usage-window-codex-weekly
-~/.config/projmux/statusbar-visibility-agent-usage-window-antigravity-weekly
 ```
 
 Missing, empty, and invalid values resolve to `on` except the Codex `5h`
@@ -1046,8 +1018,9 @@ Parent visibility gates only the effective projection. Turning the overall HUD
 or a provider off does not rewrite its provider/window leaf files; turning the
 parent back on restores the saved child selection. Provider rows follow the
 usage-supported provider catalog. Window rows come only from the explicit HUD
-capability map, so opaque quota buckets never create settings and Antigravity
-never gains a fabricated `5h` row.
+capability map, so opaque quota buckets never create settings. Antigravity has
+no usage source; `statusbar-visibility-agent-usage-*-antigravity*` files left by
+older releases are ignored and never deleted.
 
 Visibility does not enable or disable either producer. Hiding Notifications HUD
 does not change the persistent queue, desktop delivery, or Notification
@@ -1131,12 +1104,27 @@ The CPU delta cache is internal state at
 CPU reference samples older than 30 seconds are ignored and replaced on the
 next refresh.
 
+## Setting Layers
+
+Settings live in two layers:
+
+| Layer | Where | What |
+| --- | --- | --- |
+| central | `config.toml` central keys (`[ui] locale`, `[update]`, `[startup]`, `[hooks.*]`, `[env]`, `[ai] split_cwd_from`), `ai-enabled-agents`, `live-resources`, `projdir`, `workdirs`, `pins`, `tags`, `project-hooks`, `desktop-notify-mode`, `ai-notify-dedupe-seconds`, `ai-hook-actions.json`, `ai-semantic-policies.json`, `ai-hooks.d/`, `hooks/`, `personas/` | product behavior every surface shares |
+| TUI | `statusbar-visibility-*`, `statusbar-decoration*`, `ai-badge-style`, `runtime-diagnostics-visibility`, `keymap.toml`, `tmux-ai-split-mode`, `config.toml` `[theme]`, `[ui] native_keys`, `[ai] resume_*` | how the terminal looks and launches |
+
+TUI is the front layer: only the front entry points (`settings`, `shell`,
+`switch`, `config render|apply|edit` and the internal namespace) read it. Every
+other public route reads the central layer alone, except that a route opening a
+picker may read that picker's theme and keys to paint it.
+
+
 ## Rare Tunables
 
 These are intended for debugging or local policy, not routine setup:
 
 | Variable | Purpose |
 | --- | --- |
-| `PROJMUX_TMUX_NOTIFY_DEDUPE_SECONDS` | Override the Settings/default collapse window for duplicate AI desktop notifications keyed on the pane-local AI notification key. |
+| `PROJMUX_TMUX_NOTIFY_DEDUPE_SECONDS` | Override the Settings/default collapse window for duplicate AI desktop notifications keyed on the pane-local AI notification key. The Settings value and default apply only when this env is unset or not a positive integer. |
 | `PROJMUX_CODEX_TITLE_WATCH_INTERVAL` | Title-watch loop pacing for Codex panes. |
 | `PROJMUX_CODEX_REPLY_SETTLE_LOOPS` | Reply-detection settle-loop pacing for Codex panes. |

package/docs/globalization.md

@@ -110,7 +110,6 @@ Files:
 - `internal/app/*help*`
 - `docs/cli.md`
 - `docs/cli-guide.md`
-- `docs/agent-workflow.md`
 
 Classification:
 
@@ -122,6 +121,17 @@ Classification:
 | Command syntax | `projmux shell`, `make test`, `gh pr create` | `literal` | Preserve exactly. |
 | Version strings and release tags | `vX.Y.Z`, git SHA, installer source | `data` | Preserve source content. |
 
+### Install replacement failures
+
+`internal/app/install_replacement*.go` adds the failure explanation, remaining
+target heading, impact, and recovery under `install.replacement.*` catalog keys
+with `en-US` and `ko-KR` entries (`translate`). The pre-existing summary and
+successful/pending install output remain unchanged. Role/refusal tokens,
+`pid`, `revision`, and `unknown` are `literal`; observed pids and revisions are
+`data`, preserved only in the terminal diagnostic. `Codex` and `make install`
+remain literal inside the translated guidance. No process identity is added to
+the persisted outcome or residue ledger.
+
 ## Literal Preservation Rules
 
 Do not translate these families: