projmux 0.16.0 → 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:
@@ -52,9 +77,12 @@ 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.
 
@@ -69,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
@@ -117,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:
 
@@ -223,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
@@ -364,7 +394,7 @@ Preferred interactive path:
 Global config path:
 
 ```text
-~/.config/projmux/config.toml
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/config.toml
 ```
 
 Schema:
@@ -442,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
@@ -479,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:
@@ -538,6 +580,27 @@ that re-enables it.
 `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
@@ -552,8 +615,8 @@ Preferred interactive path:
 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:
@@ -616,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:
@@ -650,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`. The legacy `PROJDIR` and `RP` env vars are no longer honored. |
+| `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. |
@@ -729,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:
@@ -813,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
@@ -976,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
 
@@ -997,20 +1193,22 @@ independent global presentation preferences:
 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-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
+${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.
 
@@ -1043,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
@@ -1060,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
 
@@ -1069,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
@@ -1104,15 +1354,314 @@ 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`, `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 |
+| 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