projmux 0.15.3 → 0.16.1

package/docs/configuration.md

@@ -4,6 +4,31 @@ Most users can configure projmux from `projmux settings`. Environment variables
 are available for repeatable shell setup, managed machines, or advanced
 overrides.
 
+## XDG Base Directories
+
+Paths in this guide written as `${XDG_CONFIG_HOME:-$HOME/.config}` and the like
+follow one rule for `XDG_CONFIG_HOME`, `XDG_STATE_HOME`, `XDG_DATA_HOME`, and
+`XDG_CACHE_HOME`. Surrounding whitespace is trimmed, and the value is used only
+when it is an absolute path. An unset, empty, blank, or relative value
+(`rel`, `./rel`, or an unexpanded `~/x`) is ignored as unset, as the
+[XDG Base Directory specification](https://specifications.freedesktop.org/basedir-spec/latest/)
+requires, and the default under `$HOME` applies instead:
+
+| Variable | Default |
+| --- | --- |
+| `XDG_CONFIG_HOME` | `$HOME/.config` |
+| `XDG_STATE_HOME` | `$HOME/.local/state` |
+| `XDG_DATA_HOME` | `$HOME/.local/share` |
+| `XDG_CACHE_HOME` | `$HOME/.cache` |
+
+When `HOME` is unset or empty and the variable a path needs is not an
+absolute path, that path has no location, and projmux never falls back to a
+path relative to the working directory. A read of saved settings or state
+keeps the built-in default and touches no file. A write writes nothing and
+exits non-zero with a one-line reason naming the variables, such as
+`HOME or an absolute XDG_CONFIG_HOME is required`. A path display such as
+`projmux hook list` shows that reason in place of the path.
+
 ## Operational diagnostics state
 
 Projmux keeps a private bounded operational journal at:
@@ -38,25 +63,30 @@ 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:
 
 ```text
-~/.config/projmux/workdirs
+$HOME/.config/projmux/workdirs
 ```
 
+This file does not follow `XDG_CONFIG_HOME`; see
+[Setting Layers](#setting-layers).
+
 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
@@ -67,7 +97,7 @@ Projects sidebar registers that exact path. See
 Pins are presentation preferences, stored typed:
 
 ```text
-~/.config/projmux/pins
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/pins
 ```
 
 ```text
@@ -92,51 +122,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
-
-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:
+## Legacy Project Layout Files
 
-```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
 
@@ -155,8 +145,9 @@ terminal-layer remediation, first try the key in `projmux shell`, then run
 `projmux setup` from the raw terminal, then use `projmux setup terminal` for
 supported terminal adapters.
 
-`~/.config/projmux/keymap.toml` can also be edited by hand. When the file is
-absent, generated tmux config stays on the built-in defaults.
+`${XDG_CONFIG_HOME:-$HOME/.config}/projmux/keymap.toml` can also be edited by
+hand. When the file is absent, generated tmux config stays on the built-in
+defaults.
 
 Supported schema:
 
@@ -234,7 +225,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
@@ -261,13 +252,14 @@ Theme is a global user preference. The effective theme resolves from the global
 user theme plus a built-in fallback only:
 
 ```text
-~/.config/projmux/config.toml
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/config.toml
 built-in fallback preset
 ```
 
-Settings edits the global `[theme]` in `~/.config/projmux/config.toml`. The
-Effective theme view shows the final global > built-in fallback value for each
-field with source labels: `global` or `fallback`. Saving or resetting a theme
+Settings edits the global `[theme]` in
+`${XDG_CONFIG_HOME:-$HOME/.config}/projmux/config.toml`. The Effective theme
+view shows the final global > built-in fallback value for each field with
+source labels: `global` or `fallback`. Saving or resetting a theme
 value live-applies it: projmux regenerates the generated tmux config and, when
 Settings runs inside tmux, `tmux source-file`-reloads it so a running server
 repaints immediately. Outside tmux the save still succeeds and the report
@@ -402,7 +394,7 @@ Preferred interactive path:
 Global config path:
 
 ```text
-~/.config/projmux/config.toml
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/config.toml
 ```
 
 Schema:
@@ -465,30 +457,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
@@ -499,21 +472,33 @@ or a method-not-found response are reported explicitly as unavailable. The
 initial `review/start` response is projected into Agent interaction lifecycle;
 the lifecycle observer described below owns later app-server terminal events.
 
-A natively created or resumed Codex Agent keeps a content-free lifecycle
+A natively created or resumed Codex Agent keeps a lifecycle
 observer on its exact Agent UID, Pane UID/runtime handle, activation generation,
 and thread ID. While its initialized proxy connection and snapshot are current,
 the app server is the only attention authority: active, idle, waiting for input,
 and exact unresolved approval requests project the Agent interaction and badge.
-Only an exact successful `turn/completed` projects response-complete and queues a
-completion notification; failed and interrupted turns become idle. Disconnect
+The native observer refreshes a continuing turn or wait before the 30-minute
+interaction freshness window expires. A `requestUserInput` request projects
+`input_required` even before a separate thread-status update arrives; its
+resolution or the turn's completion releases that state. When the question
+channel is on, blocking Codex questions can be listed and answered through
+`agent question list` and `agent question answer`.
+An exact successful `turn/completed` projects response-complete and queues a
+completion notification with the last agent message (or `Ready` if none is
+available). A failed turn or `systemError` queues a critical `error` notification
+and sends an OS notification when desktop delivery is enabled. HTTP 401 is
+identified without copying the provider error text or credentials. Interrupted
+turns become idle. Disconnect
 and thread unload first invalidate the epoch and clear stale attention, then
 enable hook fallback. A reconnect starts a new epoch from `thread/read`; events
 from older epochs or other identities are ignored.
 
 `describe agent` and the Codex Agent event Settings page report the effective
 lifecycle source, a closed reason, and active/pending/inactive epoch status.
-These diagnostics never retain prompts, reasoning, output, approval reasons, or
-diff content. Settings aggregates multiple live Codex Panes as counts and says
+The observer holds the latest agent message only until completion delivery;
+the notify queue applies its 80-rune text limit. These diagnostics never retain
+prompts, reasoning, output, approval reasons, or diff content. Settings
+aggregates multiple live Codex Panes as counts and says
 `mixed` when native and fallback authority coexist.
 
 Projmux does not install, bootstrap, restart, stop, or reconfigure the Codex
@@ -536,8 +521,8 @@ 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
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/config.toml  # global
+<project>/.projmux/config.toml                        # project
 ```
 
 Schema:
@@ -582,6 +567,40 @@ 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.
+
+## New AI Window Default
+
+The mode a new AI window opens with has a central default, one word stored
+at:
+
+```text
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/ai-new-window-mode
+```
+
+The word is one of `claude`, `codex`, `antigravity`, `selective`, `resume`,
+or `shell`. In the terminal the mode resolves in this order: the TUI split
+default `tmux-ai-split-mode` when it holds one of those words, then this
+central file, then `selective`. A missing, empty, or invalid TUI value falls
+through to the central file; a missing, empty, or invalid central file means
+not set.
+
+`projmux settings` and `projmux config edit --set` keep writing
+`tmux-ai-split-mode`. `projmux config edit --set` rejects any other word with
+exit 2 and leaves the file unchanged. No command writes the central file yet;
+edit it by hand or from another front end.
+
 ## AI Resume Picker
 
 The Agent resume picker lists the most recent
@@ -591,13 +610,13 @@ 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):
 
 ```text
-~/.config/projmux/config.toml      # global
-<project>/.projmux/config.toml     # project
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/config.toml  # global
+<project>/.projmux/config.toml                        # project
 ```
 
 Schema:
@@ -649,17 +668,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
 
@@ -669,7 +679,7 @@ to the install path: every installer can be judged on either channel.
 Files:
 
 ```text
-~/.config/projmux/config.toml      # global/user
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/config.toml  # global/user
 ```
 
 Schema:
@@ -703,7 +713,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 `$HOME/.config/projmux/projdir` (see [Setting Layers](#setting-layers)). 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. |
@@ -715,12 +725,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. |
@@ -771,7 +781,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:
 
@@ -782,6 +792,134 @@ set-option -g @projmux_projdir /path/to/repos
 An env `PROJMUX_PROJDIR` value takes priority over the tmux option. The tmux
 option takes priority over the saved projdir file.
 
+The saved projdir file is `$HOME/.config/projmux/projdir`. It does not follow
+`XDG_CONFIG_HOME`; see [Setting Layers](#setting-layers).
+
+## Agent Question Answering
+
+How a Claude Agent's `AskUserQuestion` or a Codex Agent's blocking
+`requestUserInput` is answered is one word stored at:
+
+```text
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/agent-question-answering
+```
+
+| Value | Way | Meaning |
+| --- | --- | --- |
+| `claude` (default) | 1 | The provider shows its own question prompt; projmux stays out of it |
+| `projmux` | 2 | projmux records the question for `projmux agent question list` and `answer`; Claude and native Codex also open the question picker in a tmux popup |
+
+Set it with `projmux config agent-questions --answering <claude|projmux>`,
+or write the file. The setting applies to every Claude and native Codex Agent on this machine. The value
+is read case-insensitively with surrounding whitespace ignored. A
+missing, empty, or unreadable file, and any other value, is way 1. An Agent
+opted in with `projmux agent question enable` is way 2 whatever the file
+says. Codex handles only blocking app-server requests; a Codex Agent on the
+plain CLI lane has no app-server question channel. A Codex question set with an
+`isSecret` question stays in Codex's own input surface: projmux does not open
+an unmasked popup. `agent question list` points the operator to that window,
+and `agent question answer` refuses that set so secret text is not passed in
+command arguments. Other blocking Codex questions use the same popup and CLI
+answer paths as Claude. For Claude, the setting
+applies only to a projmux Agent's own conversation; other Claude sessions and
+subagents always get way 1. See
+[hooks.md](hooks.md#answering-askuserquestion-in-projmux).
+
+## Agent Question Window
+
+In way 2 the Claude question hook or Codex native observer holds the question
+for a command-line answer for a seconds window stored at:
+
+```text
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/agent-question-window-seconds
+```
+
+Set it with `projmux config agent-questions --window <seconds|unlimited>`, or
+write the file. The value is integer seconds, default `900`, in `60`–`86400`, or the
+word `unlimited` (case-insensitive), which holds the question until it is
+answered. Claude Code has no "no timeout" hook value, so `unlimited` is
+effectively capped at `604785` seconds (about 7 days): the installed hook
+timeout ceiling less the 15 second margin that lets the hook, not Claude Code,
+end the wait. A value outside the range, or a file that holds neither one
+integer nor `unlimited`, reads as `900`; a projmux older than the word also
+reads `unlimited` as `900`, and a projmux from before the maximum was raised
+from `3600` reads a value above `3600` as `900`, so downgrading only shortens
+the wait. It applies only in way 2 (see
+[Agent Question Answering](#agent-question-answering)); way 1 never waits.
+For Codex, an expired or disabled held request is closed in the question list.
+The same question remains visible and answerable in Codex's own input surface;
+projmux does not send a substitute answer. The Codex turn continues when the
+operator answers there.
+If Codex's input surface answers first, the question list records
+`answered-elsewhere`, and a later `agent question answer` is refused with that
+reason. A resolution after the command-line deadline remains `expired`.
+
+The installed Claude Code hook `timeout` is the fixed ceiling `604800` seconds
+(7 days) and does not depend on this file. The ceiling is the safety net for a
+stuck hook, and this hook has no recover: 7 days is 7 times the longest
+bounded window (86400 seconds), so it never cuts a normal window, while a
+broken hook is reclaimed within a week. The hook rereads the window for every
+question, so a changed window applies to the next question without re-running
+`projmux agent integrate claude`.
+
+Hooks installed by an older projmux carry an old timeout: the window read at
+integration plus 15 seconds (`915` by default), or the earlier, longer
+ceiling of about 25 days. After installing this version, run
+`projmux agent integrate claude` once to rewrite either entry to the
+ceiling; until then Claude Code still ends the hook at the old timeout and a
+longer window gives the question back to the ordinary prompt then.
+See [hooks.md](hooks.md#answering-askuserquestion-in-projmux).
+
+## Agent Approval Answering
+
+How an Agent's permission request ("Do you want to proceed?") is answered is
+one word stored at:
+
+```text
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/agent-approval-answering
+```
+
+It is a separate setting from [Agent Question Answering](#agent-question-answering).
+Its effect is to capture Claude permission requests and to allow remote
+(non-interactive) answers with `projmux agent approval answer` for both Claude
+and Codex Agents. Codex approvals are never captured, since the Codex
+app-server holds them: `projmux agent approval list` shows them and
+`projmux agent approval review` answers them in either way.
+
+| Value | Meaning |
+| --- | --- |
+| `claude` (default) | Claude Code shows its own permission prompt; the permission hook prints nothing and records nothing; `projmux agent approval answer` is refused for Claude and Codex Agents |
+| `projmux` | projmux also records a Claude request, and `projmux agent approval answer` can allow or deny it once; it can also allow once (`accept`) or deny a pending Codex approval (`decline` when offered, otherwise `cancel`, which also interrupts the turn). The provider's own prompt stays usable, and the first answer wins |
+
+Set it with `projmux config agent-approvals --answering <claude|projmux>`, or
+write the file. The value is read case-insensitively with surrounding
+whitespace ignored; a missing, empty, or unreadable file, and any other value,
+is `claude`. It applies to every Claude Agent on this machine, but only to
+requests from a projmux Claude Agent's own conversation, including its
+subagents; other Claude sessions, and a session in `bypassPermissions` or
+`dontAsk` mode, never have a request captured. See
+[hooks.md](hooks.md#answering-claude-permission-requests-in-projmux).
+
+## Agent Approval Window
+
+While the setting is `projmux`, the permission hook holds each request open
+for an answer for a seconds window stored at:
+
+```text
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/agent-approval-window-seconds
+```
+
+Set it with `projmux config agent-approvals --window <seconds>`, or write the
+file. The value is integer seconds in `60`–`3600`, default `900`. There is no
+`unlimited` value: a value outside the range, `unlimited`, and a file that does
+not hold one integer read as `900`. A request nobody answers in the window
+expires with no decision, and Claude Code's own prompt decides it.
+
+The installed hook `timeout` is the fixed ceiling `3615` seconds (the longest
+window plus a 15 second margin) and does not depend on this file. The hook
+rereads the window for every request, so a changed window applies to the next
+request without re-running `projmux agent integrate claude`.
+
 ## Notifications
 
 When `PROJMUX_NOTIFY_HOOK` is unset, projmux uses:
@@ -833,7 +971,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.
@@ -865,6 +1004,11 @@ precedence only during hook fallback; catalog defaults do not override this
 semantic store. Saving this file does not infer from, rewrite, or normalize the
 raw hook override file.
 
+Codex native failures are always delivered as critical `error` notifications,
+independent of those two completion/approval policy choices. A hook fallback
+`Stop` uses Codex's `last-assistant-message` payload when present; without it,
+the completion text is `Ready`.
+
 Delivery depends on the event handler. Specialized notify handlers, such as
 Codex `PermissionRequest` and `Stop`, can write the in-app notify queue and use
 the configured OS desktop notification path. Known Codex events without a
@@ -918,7 +1062,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
@@ -964,28 +1108,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.
@@ -997,62 +1148,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
 
@@ -1066,13 +1172,13 @@ Settings > Appearance controls optional icon decoration per surface:
 The per-surface saved values live at:
 
 ```text
-~/.config/projmux/statusbar-decoration-cwd
-~/.config/projmux/statusbar-decoration-git
-~/.config/projmux/statusbar-decoration-notify
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/statusbar-decoration-cwd
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/statusbar-decoration-git
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/statusbar-decoration-notify
 ```
 
-The legacy `~/.config/projmux/statusbar-decoration` value is still read as the
-fallback default when a per-surface file is absent.
+The legacy `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/statusbar-decoration`
+value is still read as the fallback default when a per-surface file is absent.
 
 ## Row 0 HUD Visibility
 
@@ -1081,29 +1187,28 @@ 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:
 
 ```text
-~/.config/projmux/statusbar-visibility-notifications-hud
-~/.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
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/statusbar-visibility-notifications-hud
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/statusbar-visibility-agent-usage-hud
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/statusbar-visibility-agent-usage-provider-claude
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/statusbar-visibility-agent-usage-provider-codex
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/statusbar-visibility-agent-usage-window-claude-5h
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/statusbar-visibility-agent-usage-window-claude-weekly
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/statusbar-visibility-agent-usage-window-codex-5h
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/statusbar-visibility-agent-usage-window-codex-weekly
 ```
 
-Missing, empty, and invalid values resolve to `on` except the Codex `5h`
-window, whose ambient HUD default is `off`; an explicit saved `on` restores it.
-Settings shows whether the effective value came from `saved` or `default` and
-marks an invalid saved value as ignored. Saving a toggle regenerates the app
+Missing, empty, and invalid values fall back to the
+[central status bar default](#central-status-bar-defaults) for that file, and
+without one resolve to `on` except the Codex `5h` window, whose ambient HUD
+default is `off`; an explicit saved `on` restores it. Settings shows whether
+the effective value came from `saved`, `central`, or `default` and marks an
+invalid saved value as ignored. Saving a toggle regenerates the app
 and standalone tmux output, and Settings source-reloads the generated app config
 when it is running inside tmux.
 
@@ -1111,8 +1216,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
@@ -1135,15 +1241,18 @@ components independently:
 Their global saved values are `on` or `off` in:
 
 ```text
-~/.config/projmux/statusbar-visibility-project
-~/.config/projmux/statusbar-visibility-working-directory
-~/.config/projmux/statusbar-visibility-git
-~/.config/projmux/statusbar-visibility-clock
-~/.config/projmux/statusbar-visibility-settings-launcher
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/statusbar-visibility-project
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/statusbar-visibility-working-directory
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/statusbar-visibility-git
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/statusbar-visibility-clock
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/statusbar-visibility-settings-launcher
 ```
 
-Missing, empty, and invalid values resolve to `on`; Settings reports the
-effective value and whether it came from `saved` or `default`. Each save is an
+Missing, empty, and invalid values fall back to the
+[central status bar default](#central-status-bar-defaults) for that file, and
+without one resolve to `on`; the settings launcher has no central default.
+Settings reports the effective value and whether it came from `saved`,
+`central`, or `default`. Each save is an
 atomic 0600 replacement, regenerates both app and standalone output, and
 source-loads the generated app config when Settings is inside tmux. Off removes
 the complete segment, including its mouse range and owned spacing. Working
@@ -1152,8 +1261,57 @@ text visible. Settings launcher `off` removes only its mouse chip; CLI and
 keybinding entry remain.
 
 Resources intentionally does not use one of these visibility files. Its
-existing `~/.config/projmux/live-resources` value is the only enabled source
-and controls both the segment and sampler/cache mutation.
+existing `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/live-resources` value is
+the only enabled source and controls both the segment and sampler/cache
+mutation.
+
+## Central Status Bar Defaults
+
+The status bar visibility files above, except the settings launcher, have a
+central default layer under them in:
+
+```text
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/statusbar-defaults.json
+```
+
+It holds `on` or `off` per visibility file, keyed by the file name without its
+`statusbar-visibility-` prefix (`clock`, `agent-usage-window-codex-5h`):
+
+```json
+{
+  "visibility": {
+    "clock": "off"
+  }
+}
+```
+
+A visibility value resolves in this order: a valid value in the file above,
+then its central default, then the built-in default. Values other than `on` or
+`off` in the central file are ignored.
+
+Nothing edits the central file yet. `projmux config apply` fills it once from
+the valid values of the visibility files, so it starts out matching what the
+status bar shows:
+
+- Once. A record at
+  `${XDG_STATE_HOME:-~/.local/state}/projmux/statusbar-defaults-seeded` marks
+  the copy done, and later applies copy nothing, whatever the visibility files
+  say by then. The two copies may drift apart after that.
+- Per key, never overwriting. A central value already stored stays.
+- Valid values only. A missing, empty, or invalid visibility file copies
+  nothing, so that key keeps following the built-in default.
+
+When it copies anything, the apply prints one
+`seeded central status bar defaults: copied N TUI value(s)` line. A failure is
+reported on the same line, never fails the apply, and writes no record, so the
+next apply tries again. Deleting both the central file and the record makes the
+next apply copy again.
+
+`make install` and `projmux update apply` run `projmux config apply`, so an
+install through either copies right away. A plain `npm install -g projmux` runs
+no install script, so it copies on the next `projmux config apply`. Until then
+the central file is empty and the status bar is unchanged, because the
+visibility files still decide.
 
 ## Live System Resources
 
@@ -1161,7 +1319,7 @@ and controls both the segment and sampler/cache mutation.
 CPU/memory segment on the lower status row. The saved global value is:
 
 ```text
-~/.config/projmux/live-resources
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/live-resources
 ```
 
 Accepted values are `off` (default) and `on`. A missing, empty, or invalid
@@ -1196,12 +1354,326 @@ The CPU delta cache is internal state at
 CPU reference samples older than 30 seconds are ignored and replaced on the
 next refresh.
 
+## Agent Profiles
+
+An Agent profile is a named set of Agent start settings stored at
+`<config dir>/profiles/<name>.toml` (by default
+`${XDG_CONFIG_HOME:-$HOME/.config}/projmux/profiles/`).
+Manage profiles with `projmux profile list|show|set|delete`, and start an
+Agent from one with `projmux create agent --profile <name>` or a `role` label
+(see [CLI guide](cli-guide.md#agent-profiles-at-create)).
+
+A profile is one combination: the provider it is for, the stored instructions
+it starts with, its model and effort, the roles that select it, and its
+permissions. Every key is optional. Which items each provider applies, and
+which it discloses as not applied or refuses, is in the
+[CLI guide](cli-guide.md#agent-profiles-at-create).
+
+A profile file is a strict subset of TOML:
+
+- blank lines and `#` comments, on their own line or after a value;
+- top-level `key = value` lines with a bare key;
+- at most one `[permissions]` table; every key after it belongs to that table;
+- values that are double-quoted strings or arrays of them. The only escapes are
+  `\"` and `\\`; tabs, other control characters, and line breaks inside a
+  string are refused. An array may span lines, hold comments, and end with a
+  trailing comma.
+
+Everything else is refused: unknown keys or tables, a second `[permissions]`, a
+key given twice, quoted or dotted keys, literal or multi-line strings, numbers,
+booleans, and inline tables. The file limit is 64 KiB.
+
+| Key | Value |
+| --- | --- |
+| `provider` | the Agent provider the profile is for: one of the ids `create agent --provider` accepts (`claude`, `codex`, `antigravity`), spelled exactly. Omitted, the profile is provider-neutral |
+| `instructions` | the name of stored instructions (`projmux instructions list`); the file must exist |
+| `model` | a Claude model alias or name, the same shape `create --model` accepts; `projmux agent models` lists suggestions, and names outside that list are accepted too |
+| `effort` | `low`, `medium`, `high`, `xhigh`, or `max` |
+| `roles` | array of role names; each non-empty, without surrounding whitespace, listed once, and not listed by another profile |
+| `[permissions]` `sandbox` | `read-only`, `workspace-write`, or `full-access` |
+| `[permissions]` `approval` | `never`, `on-request`, or `untrusted` |
+| `[permissions]` `allow`, `deny` | arrays of Claude permission rules: a tool name (`[A-Za-z][A-Za-z0-9_-]*`) optionally followed by one non-empty `(...)` specifier, such as `Edit`, `Bash(git status *)`, `Read(./docs/**)`, `WebFetch(domain:example.com)`, or `mcp__srv__tool` |
+
+```toml
+provider = "claude"
+instructions = "reviewer"
+model = "opus"
+effort = "high"
+roles = ["review"]
+
+[permissions]
+sandbox = "workspace-write"
+approval = "on-request"
+allow = ["Bash(git status *)", "Read(./docs/**)"]
+deny = ["WebFetch(domain:example.com)"]
+```
+
+`provider` binds the profile to one provider. A create of any other provider
+-- `create agent --provider`, a `create <provider>` shortcut, a `role` label,
+or a create from the UI -- refuses with exit 2 (`profile-provider-mismatch`,
+naming both providers) before anything is written. A profile without
+`provider` applies to every provider, and parses, digests, and applies exactly
+as it did before the key existed. `create agent` may omit `--provider` when
+the profile it selects names one: the profile's `provider` is then the Agent's
+provider. A provider-neutral profile does not choose one, so `create agent`
+still needs `--provider` with it. `profile set` refuses an unknown value with
+exit 2 (`profile-provider-unknown`, listing the accepted providers) and writes
+nothing. `model` is checked only for its shape, whatever the provider, and
+`effort` takes the one vocabulary above.
+
+`instructions` names the stored files `projmux instructions` manages: one
+store, `<config dir>/personas/<name>.md`, and one profile key. What the
+instructions do depends on the lane, exactly as for `create --instructions`:
+Claude appends them to the system prompt, and
+Codex takes them only on a prompted create that opens its own thread (see
+[CLI guide](cli-guide.md#agent-profiles-at-create)); a promptless Codex create
+with Profile instructions is refused before creating anything. Codex keeps
+the developer instructions recorded when the thread started; a relaunch and a
+resume cannot replace them (`codex-instructions-immutable`). A profile
+keeps the instructions it names: `instructions delete <name>` refuses with
+exit 2 (`profile-instructions-in-use`) while any stored profile that parses
+names them, valid or not, and names each such profile. Change the profile with
+`projmux profile set <name>` or remove it with `projmux profile delete <name>
+--yes` first. Instructions removed by hand still make the profile invalid
+(`profile-instructions-not-found`), and Agents that record it then refuse to
+resume (`profile-resume-unavailable`) rather than resume without its
+permissions.
+
+Roles fail closed. Every profile that parses holds the roles it lists, valid
+or not: `profile set` refuses a role another profile lists
+(`profile-role-claimed`), `profile list` shows an invalid profile's roles, and
+a `role` label whose one listing profile is invalid refuses the create
+(`profile-role-profile-invalid`, naming the profile and its reason) instead of
+creating the Agent without a profile. A valid profile that shares a role with
+an invalid one is marked `profile-role-claimed`; the invalid one keeps its own
+reason. Pass `--profile none` to create without a profile.
+
+Profile names follow the instructions name rule, and `none` is reserved.
+No profile is compiled into projmux: every profile is a file in
+`<config dir>/profiles/`, and a name without a file is `profile-not-found`.
+A profile that lets an Agent read and never write lists no roles and sets
+only its permissions:
+
+```toml
+# readonly.toml
+[permissions]
+sandbox = "read-only"
+approval = "never"
+deny = ["Edit", "Write", "NotebookEdit"]
+```
+
+Store it with `projmux profile set readonly --file readonly.toml`.
+
+When a profile with `allow` or `deny` rules is applied to a Claude Agent, its
+rules are written as a Claude settings file,
+`{"permissions":{"allow":[...],"deny":[...]}}` (an empty list left out), to
+`${XDG_STATE_HOME:-~/.local/state}/projmux/profile-settings/sha256-<hex>.json`
+(directory 0700, file 0600, named by the sha256 of the bytes), and Claude is
+started with `--settings <that file>`. Each resume writes it again from the
+current profile.
+
+When a profile with `sandbox` or `approval` is applied to a Codex Agent, the
+native lane sends them as the thread's `sandbox` and `approvalPolicy` on
+`thread/start` and every native `thread/resume`. The thread's answer must
+report the same policy, or create or resume is refused
+(`codex-thread-policy-mismatch`). Promptless and `--interactive-only` creates,
+and CLI resumes, pass the current profile policy as `codex -s <sandbox> -a
+<approval>` or `codex -s <sandbox> -a <approval> resume`. On both lanes,
+`full-access` becomes Codex's `danger-full-access`. Codex CLI accepts
+`approval = "on-request"` and `"never"`; a profile with `approval = "untrusted"`
+is refused on CLI lanes (`codex-cli-untrusted-approval-unsupported`) before
+creating a Pane or resuming the Agent. The native lane still accepts it.
+`allow` and `deny` are not given to Codex and appear as not applied in create
+receipts.
+
+## Project Link Rules
+
+Project link rules turn a Project's labels into links, for example a
+`jira=ABC-123` label into `https://jira.example.com/browse/ABC-123`. Each
+Project has at most one rule file, `<config dir>/project-links/<project-uid>.json`
+(by default `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/project-links/`), named
+by the Project UID (`proj-...`) so renaming the Project or moving its root
+keeps its rules. The rules belong to the Project, and every surface shares
+them: a Claude Agent's system prompt shows them (see below), and a client that
+edits them, such as the web client, reads and writes this same file. There is
+no CLI command that edits them. A missing file means the Project has no rules.
+
+```json
+{
+  "jira": ["https://jira.example.com", "https://jira.partner.example.com"],
+  "repo": ["https://github.com/example/repo"],
+  "urls": {"wiki": "https://wiki.example.com/spaces/APP"},
+  "links": [
+    {"labelKey": "jira", "template": "{jira}/browse/{value}"},
+    {"labelKey": "partner", "template": "{jira[1]}/browse/{value}"},
+    {"labelKey": "pr", "template": "{repo}/pull/{value}"},
+    {"labelKey": "doc", "template": "{wiki}/{project.labels.team}/{value}"}
+  ]
+}
+```
+
+`jira` and `repo` are lists of base URLs, and `urls` names more base URLs.
+projmux always writes all four fields.
+
+| Placeholder | Becomes |
+| --- | --- |
+| `{value}` | The label value, path-escaped (`a/b c` becomes `a%2Fb%20c`). Required in every template. |
+| `{jira[N]}`, `{repo[N]}` | The `N`th URL of `jira` or `repo`, counting from 0. `N` is decimal with no leading zero (`{jira[01]}` is refused). |
+| `{jira}`, `{repo}` | The same as `{jira[0]}` and `{repo[0]}`. |
+| `{<name>}` | The URL `urls` names `<name>`, such as `{wiki}`. |
+| `{project.uid}` | The Project UID, path-escaped. |
+| `{project.name}` | The Project name, path-escaped. |
+| `{project.labels.<key>}` | The value of the Project's label `<key>`, path-escaped. |
+
+A base URL is substituted with any trailing `/` trimmed. Every placeholder is
+substituted in one pass, so text a substitution inserts is never expanded
+again. A label value is one value: `a,b` makes one link (`a%2Cb`), not two.
+
+The Project variables are the Project's UID, name and labels in the Registry,
+and nothing else: its root directory, its annotations and its Windows are not
+placeholders, and `{project.root}` is refused. A label whose rule uses a
+Project label the Project does not have, or has empty, gets no link.
+
+A rule file must pass these checks, both when it is written and when it is
+read; a file that fails them, is not one JSON object of exactly these fields,
+or is larger than 64 KiB is an error, never treated as empty. An error names
+the field as a JSON path, such as `jira[3]`, `urls.wiki` or
+`links[2].template`.
+
+- `jira` and `repo` hold at most 16 URLs each, and `urls` at most 32. Each
+  URL is an absolute `http` or `https` URL with a host, at most 2048 bytes,
+  with no credentials (`user@`), no query, no fragment and no `{` or `}`.
+- A `urls` name is a lowercase ASCII letter followed by at most 31 lowercase
+  letters, digits, `_` or `-`. `value`, `jira`, `repo` and `project` are
+  reserved and refused.
+- `links` holds at most 64 rules.
+- `labelKey` is 1 to 64 ASCII letters, digits, `.`, `_` or `-`, compared
+  exactly (case-sensitive), and unique in the file.
+- `template` is at most 2048 bytes, contains `{value}`, has no `{` or `}`
+  outside a placeholder, and uses only the placeholders above: an index within
+  its list (`{jira}` needs at least one Jira URL), a name `urls` defines, and
+  a Project field that exists. `{project.labels.<key>}` is checked only for
+  its key's syntax (the `labelKey` rules), because the label may be added
+  later. Expanded with a sample value and a sample Project, the template is an
+  absolute `http` or `https` URL without credentials.
+
+Removing a URL that a template still uses is refused, like any other invalid
+rule set, and leaves the file as it was.
+
+### Rules in a Claude Agent's system prompt
+
+A Claude Agent gets its Project's current rules in its system prompt: the
+heading, the placeholders, the Jira and Repo URLs with their indices, the
+named URLs, the Project variables with their current values, and each rule
+with an example link resolved for that Project, as text appended with
+`--append-system-prompt-file`. The Project is the one that owns
+the Agent's Window in the Registry, never the one its working directory is
+under. Only Claude Agents get the rules; Codex Agents and the Claude
+reply-only lane do not.
+
+- Create passes the rules and records their digest on the Agent
+  (`projmux.io/project-link-rules-digest`). With instructions too, Claude is
+  given one file holding the instructions, a `---` separator, and the rules,
+  because Claude keeps only the last `--append-system-prompt-file`. A
+  resume-picker create also runs with the system prompt snapshot off, since
+  the picked conversation recorded a prompt without the rules.
+- A running Agent is not restarted when the rules change. The change applies
+  from its next resume (`agent resume`, Continue, or the resume picker): when
+  the Project's rules differ from the recorded digest (added, changed or
+  removed, or the Project renamed or its labels changed, since the Project
+  variables are part of the rendered rules), that resume passes the current
+  rules, runs with `--system-prompt-snapshot off`, and records the new digest
+  and `projmux.io/system-prompt-snapshot=off`, which stays off from then on.
+  Rules equal to the recorded digest change nothing.
+- A rule file that cannot be read does not stop the Agent: it starts without
+  the rules, one `project-link-rules-unavailable` line on stderr says so, and
+  its recorded digest is left as it was.
+
+The rendered rules and the instructions-and-rules files are content-addressed
+below the state directory, in `project-links/`.
+
+## Agent Guidance
+
+Every managed Claude Agent gets a short agent guidance text at the front of
+its system prompt, and a Codex Agent gets it at the front of its thread's
+developer instructions when it starts its own thread. It tells the Agent to
+create other agents with `projmux create agent` instead of a subagent built
+into its provider, and to
+message them with `projmux agent message send` instead of a message channel
+local to its provider. The guidance lives in one file,
+`<config dir>/agent-guidance.md` (by default
+`${XDG_CONFIG_HOME:-$HOME/.config}/projmux/agent-guidance.md`), and there is no
+CLI command that edits it.
+
+| File | Guidance |
+| --- | --- |
+| Missing | The built-in default text. This is the state of a new install. |
+| Only whitespace (an empty file included) | Off: nothing is added and nothing is recorded. |
+| Any other content | That content, byte for byte, in place of the default. |
+
+To turn the guidance off, leave the file empty (`: > agent-guidance.md`). To
+use your own text, write it to the file. To go back to the default, delete
+the file. The file is at most 64 KiB.
+
+- The guidance, the instructions and the Project's label link rules reach Claude
+  as one `--append-system-prompt-file`, in that order, each present only when
+  the Agent has it and separated by a `---` line, because Claude keeps only
+  the last file it is given.
+- Create passes the current guidance and records its digest on the Agent
+  (`projmux.io/agent-guidance-digest`).
+- A change applies from the next Claude create or resume (`agent resume`,
+  `agent relaunch`, Continue, or the resume picker). Running sessions are not
+  restarted. A resume whose guidance differs from the recorded digest (changed,
+  added to an Agent created before the guidance existed, or turned off) passes
+  the current guidance, runs with `--system-prompt-snapshot off`, and records
+  the new digest (or removes it) and `projmux.io/system-prompt-snapshot=off`.
+  A resume-picker create always runs with the snapshot off while the guidance
+  is on, since the picked conversation's recorded prompt cannot be shown to
+  hold it. Guidance equal to the recorded digest changes nothing.
+- A guidance file that cannot be read, is not a regular file, or is larger
+  than 64 KiB does not stop the Agent: it starts without the guidance, one
+  `agent-guidance-unavailable` line on stderr says so, and nothing is
+  recorded.
+- A Codex Agent receives the guidance on a fresh create that starts its own
+  thread (a create with a prompt): the guidance and the instructions go to that
+  thread as its developer instructions, in that order, each present only when
+  the Agent has it and separated by the same `---` line, and the Agent records
+  the guidance digest. A Codex resume, and a Codex create without a prompt or
+  with `--interactive-only`, do not receive it. A thread keeps the developer
+  instructions it was started with, so a changed guidance reaches a Codex
+  Agent only through a new create.
+- The Claude reply-only lane does not receive the guidance.
+
+The guidance and the files composed from it are content-addressed below the
+state directory, in `agent-guidance/`.
+
+## 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`, `ai-new-window-mode`, `live-resources`, `statusbar-defaults.json`, `projdir`, `workdirs`, `pins`, `tags`, `project-hooks`, `desktop-notify-mode`, `ai-notify-dedupe-seconds`, `agent-question-window-seconds`, `agent-question-answering`, `agent-approval-window-seconds`, `agent-approval-answering`, `ai-hook-actions.json`, `ai-semantic-policies.json`, `ai-hooks.d/`, `hooks/`, `personas/`, `profiles/`, `project-links/` | 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 |
+
+Central files live under `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/`, except
+`projdir` and `workdirs`, which always live under `$HOME/.config/projmux/` and
+do not follow `XDG_CONFIG_HOME`.
+
+Named Agent instructions continue to use the central `personas/` directory, which keeps its older name. The `projmux instructions` commands read and write its files.
+
+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. |