projmux 0.16.0 → 0.16.1

package/docs/cli-guide.md

@@ -20,8 +20,18 @@ Exit codes:
 
 - `0` — success.
 - `1` — runtime failure.
-- `2` — usage error (unknown flag, bad enum, missing required flag) or a
-  deterministic semantic exit (e.g. `focus` cannot resolve the target).
+- `2` — usage error (unknown flag, bad enum, missing required flag, a
+  positional argument the route does not accept, or an unknown or missing
+  subcommand) or a deterministic semantic exit (e.g. `focus` cannot resolve
+  the target).
+- A flag parse failure on a public route (an unknown flag, a missing flag
+  value, or a malformed boolean) prints the reason line first and then the
+  route's `Usage:` block, byte-identical to the one `projmux <route> --help`
+  prints, on stderr; stdout stays empty and the exit code is `2`. The Go flag
+  package's own `Usage of <route>:` flag listing is never printed.
+- The hidden `projmux internal …` plumbing is outside this table: it follows
+  its caller's contract (generated tmux config, provider hooks, supervisors),
+  so a flag error there keeps its existing exit code and output.
 
 ## Help boundary
 
@@ -48,8 +58,12 @@ with it keeps one notion of help; the boundary never interprets a flag value:
   unchanged.
 - An unknown command keeps its `unknown command: <token>` error and exit `1`
   even with `--help`, and `projmux help` / bare `projmux` keep printing the
-  top-level list. A bare `help` word nested under a command
-  (`projmux pin help`) still reaches that command's own handler.
+  top-level list.
+- On a command that has sub-commands, a bare `help` word right after it (before
+  any `--`) prints that command's help, whatever follows it: `projmux agent help`
+  and `projmux agent help instructions` both print `projmux agent --help`. A
+  command without sub-commands receives `help` as an ordinary argument, and a
+  `help` after `--` is payload.
 - Because a help invocation runs no handler, it is never recorded as a state
   change in the operations journal, at any depth — `projmux agent topic set --help`
   logs neither an error nor a state-changing success.
@@ -97,6 +111,21 @@ invocation context. Mixed Registry/Runtime pickers keep KIND in both profiles.
 Wide stdout preserves full values at every terminal width. See [Column profiles](column-profiles.md)
 for the exact per-kind matrix and migration from the previous default output.
 
+STATUS in `get` and `describe` is observed on the tmux server the caller is
+attached to (`$TMUX`). Outside tmux -- another terminal, an IDE, a script --
+they observe the app server `-L projmux`, so a live Window reads `live` there
+too; with no app server running, rows read `offline`.
+
+STATUS is one of `live`, `offline`, `unknown`, or `missing-root`. `offline`
+means the server was read and no runtime object mirrors the resource.
+`unknown` means the server could not be read, so the resource was neither seen
+running nor seen absent. An `unknown` row offers only `delete` in ACTIONS -- no
+`start`, `resume`, or `open` -- because starting something that may already be
+running is not safe. A Project's STATUS and ACTIONS both come from the same
+observation of its session, not from the stored session projection. `-o json`
+is unchanged: it carries no STATUS, and `context.observed` still reports
+whether the context was observed.
+
 The resource routes (`get`, `describe`, `create`, `rename`, `label`, `rebind`,
 `delete`, `agent resume`) address stored resources through one shared selector
 grammar.
@@ -149,9 +178,12 @@ The contract:
   partially specified selector. The active *Project* is a separate rule and does
   apply to a reference -- see [Reference scope](#reference-scope-the-active-project-namespace)
   below.
-- **Only the singular routes and `create`.** The plural reads (`get
-  projects|windows|panes|agents`) stay 0..N inventories over their whole scope,
-  and `delete` is unchanged. `create` has its own spelling of the same rule --
+- **Only the singular routes, `delete`, and `create`.** The plural reads (`get
+  projects|windows|panes|agents`) stay 0..N inventories over their whole scope.
+  `delete window|pane|agent` with neither a selector nor `--all` targets the
+  active Window, Pane, or Agent and asks before removing it -- see
+  [Delete confirmation](#delete-confirmation); `--all` still means every one in
+  the registry. `create` has its own spelling of the same rule --
   see [Create scope](#create-scope) -- because a create resolves a scope to put
   something *into* rather than a target to act *on*.
 - **Inside tmux is decided by `$TMUX_PANE` plus `$TMUX`**, not by whether a tmux
@@ -172,6 +204,28 @@ and `@projmux_window_uid` on its window — and derives every ancestor from
 registry `ownerRef`. The session-scoped `@projmux_project_uid` is deliberately
 not consulted.
 
+### Delete confirmation
+
+`delete window|pane|agent` and `unregister project` ask before they remove
+anything, with one exception: a `delete pane` whose selector resolves to
+exactly one Pane deletes it without asking. The selector is anything the
+operator typed -- a positional `<ref>`, a `--project`/`-p`,
+`--window`/`-w`, or `--pane` scope, or a `--selector` label. The argv already
+names the one resource that goes away, and a Pane is a leaf: it cascades to
+nothing, an Agent that owned it stays as an Offline resource, and deleting a
+Window's last Pane starts a replacement shell first, so the Window and its
+session stay.
+
+Everything else asks: `delete pane` with no selector (the active Pane inside
+tmux), `--all`, a selector that matches several Panes, and every `delete
+window`, `delete agent`, and `unregister project`. Asking means `--yes`
+proceeds; without it, a terminal prompts and a declined answer exits `2`, and
+a caller with no terminal is refused with exit `2` and a `needs confirmation`
+message. Either way the answer is settled before anything is deleted.
+`--dry-run` prints the full target and cascade plan and deletes nothing, with
+or without `--yes`. To preview a single named Pane, pass `--dry-run`: without
+it the Pane is already gone.
+
 ### Plural read scope: the active managed root
 
 Inside tmux, selector-omitted `get windows|panes|agents` derives one exact
@@ -509,6 +563,18 @@ Two properties follow from that grammar and are worth stating outright:
   `create --label` has never had them and one field must not have two contracts
   depending on which route wrote it.
 
+Because nothing constrains the characters of a key or value, the human-readable
+lines that print a metadata map quote the ones that would break them. The
+`label` result line and the `Labels:` and `Annotations:` rows of `describe`
+spell each pair as `key=value` on one line, and a key or value renders in Go
+`strconv.Quote` form when it holds a character `strconv.IsPrint` rejects (a
+newline, tab, CR, ESC, or other control or format character; the ASCII space
+is printable), is not valid UTF-8, or starts with `"`. So a value written as
+`$'line1\nline2'` prints as `k="line1\nline2"`, and a key written as
+`$'bad\nkey'` prints as `"bad\nkey"=v`. Every other key and value, including
+printable non-ASCII text, prints exactly as stored. Quoting is display only:
+the stored value, `--selector`, and `-o json` keep the original bytes.
+
 What belongs in a label is decided by one question: is this a value you will
 ever filter on? `--selector key=value` reads labels and only labels, so
 classification that selects (`role=epic-owner`, `phase=task-0`) belongs there.
@@ -530,6 +596,15 @@ current Registry-backed `available`, and
 `completionPrecision` are separate fields. Use `-o json` for the stable machine
 projection.
 
+`projmux agent models [--provider claude] [-o json]` lists, in order, the
+Claude model names projmux suggests for `create --model` and a Profile `model`:
+one name per line, or `{"provider","models","acceptsUnlisted":true}` with
+`-o json`. It reads a fixed list without opening the Registry, tmux, a provider
+process, or the network. The list is a suggestion, not an allowlist: any other
+well-formed model name is still accepted. `--provider codex` (or any other
+provider projmux does not apply a model to) is a usage error rather than an
+empty list.
+
 The closed static modes are `generic-registry`, `provider-resume`,
 `native-exact-control`, `provider-hook`, `read-only-adapter`, and
 `unsupported`. `message.send`, `message.status`, and `wait.idle` are provider-neutral commands whose availability is decided from
@@ -557,6 +632,20 @@ correlated model reply is a separate envelope with the original
 self-claims that envelope. Message lifecycle updates neither Agent interaction
 state nor tmux badges.
 
+`--source` names the source Agent; it does not prove the caller is that Agent.
+When the source is a Claude Agent with a registered Claude process and the
+sending process does not descend from that process, the send still proceeds
+exactly as before (same receipt, delivery, and exit status), but it prints one
+`agent message send: warning:` line on stderr naming the source Agent UID, its
+registered Claude session, the caller pid, and `CLAUDE_CODE_SESSION_ID` when
+set, and records one `agent.message.foreign-source` event readable with
+`projmux diagnostics log --component agent`. It usually means another Claude
+session, such as a `claude --resume` in another terminal or a background
+session left by `/exit` "Move to background", is sending as that Agent: end
+that session, or send from the registered one. Nothing is judged when the
+process lineage cannot be read, and a Claude `--reply-to` is already refused
+for such a caller.
+
 Claude messaging is opt-in through `projmux agent integrate claude`. The
 integration installs no receiver waiter or `asyncRewake`; ingress is immediate
 through the exact registered provider socket. Capability JSON keeps Claude
@@ -576,8 +665,11 @@ and connection epoch still match exactly. `start` sends only the exact thread
 id and one text input. Immediately before that write it reads one bounded,
 content-free lifecycle snapshot: fresh active/in-progress returns
 `turn-in-progress`, fresh idle/terminal repairs stale cached state and starts
-once, and an unavailable or inconsistent snapshot returns
-`turn-state-unavailable` with no turn mutation. Broker read admission refusals
+once, and so does a fresh system-error thread (left by a provider error) whose
+latest turn is not in progress. An unavailable or inconsistent snapshot returns
+`turn-state-unavailable` with no turn mutation; its line says the read failed,
+returned a different thread, or names the observed thread and turn state
+(for example `thread=system-error turn=in-progress`). Broker read admission refusals
 remain visible as `lifecycle-retry` or `lifecycle-busy`. `steer` also reads that
 content-free snapshot before any write and submits exactly once only when it
 still proves the same exact active turn. Fresh idle, terminal, or different-turn
@@ -609,6 +701,39 @@ identity mismatch produces no provider write. Approval queue rows advertise
 advertise the exact-Agent `Open Codex` focus fallback; resolution removes the
 row. Neither route stores prompt, command, path, permission, or request content.
 
+`agent approval list` and `agent approval answer` read and settle the same
+pending Codex approvals without a picker, over the same exact binding:
+
+```sh
+projmux agent approval list <agent-ref> [-o json]
+projmux agent approval answer <agent-ref> <request-id> --allow|--deny [--via popup|cli|<client>]
+```
+
+`list` works whatever `agent-approval-answering` says and prints it. Each
+request shows its normalized id, `waiting`, the approval kind as `toolName`
+(`command`, `file-change`, `permissions`), its full details as `toolInput`,
+which of `allow` and `deny` `answer` can send (`answers`), and what `--deny`
+would send (`denyDecision`; in text `deny(decline: the turn continues)` or
+`deny(cancel: the turn stops)`). A request whose id is ambiguous across raw
+JSON-RPC ids, or that offers neither, is marked for `agent approval review`.
+`answer` needs `projmux config agent-approvals --answering projmux` (otherwise
+`permission-answering-off`, with no broker call). It sends exactly one
+decision: `accept` for `--allow`, never a widened grant or exec-policy
+amendment; for `--deny`, `decline` when the request offers it, so the turn
+continues, and otherwise `cancel`, which also interrupts the turn. Real Codex
+command approvals may offer `accept` and `cancel` without `decline`, so a deny
+there stops the turn. Nothing runs either way. A request offering no fitting
+decision (a permission grant for both flags, or `--allow` on a file change with
+a root grant) is refused as `permission-decision-unavailable`, and an unknown
+or ambiguous id as `permission-not-pending`. The result line names the
+decision sent, for example `7 denied for agent/codex (decision cancel; the turn
+stops)`. `review` keeps the picker, the grant decision, and `Open Codex`. The Codex TUI, `review`, and `answer`
+all stay usable, and the first answer wins: a later one is refused by the
+provider or finds the request gone. Before sending, `answer` appends an
+`allowed` or `denied` line to the agent approval audit log (see
+[hooks.md](hooks.md#answering-claude-permission-requests-in-projmux)); if that
+line cannot be written nothing is sent.
+
 `agent topic get|set|clear` and `agent status get|set` resolve exactly one
 Agent, either from an explicit Agent reference or from the Agent-owned active
 managed Pane. Topic is a non-identifying Registry annotation. Interaction is a
@@ -961,7 +1086,7 @@ the server, and no write verb is ever sent.
 ## runtime diagnostics
 
 ```text
-projmux runtime diagnostics [--socket <name> | --socket-path <absolute>] [--ui=popup|sidebar]
+projmux runtime diagnostics [--socket <name> | --socket-path <absolute>] [--ui popup|sidebar]
 ```
 
 The interactive half of the same read. It lists every tmux object on the exact
@@ -1115,10 +1240,17 @@ operator's question, so they stay reachable only as `projmux internal tmux ...`.
 ## switch
 
 ```
-projmux switch [--ui=popup|sidebar]
+projmux switch [--ui popup|sidebar] [--anchor <pane>]
 projmux switch open <path>
-projmux switch toggle-tag | toggle-pin | kill | settings | preview
-projmux switch cycle-pane | cycle-window | sidebar-focus
+projmux switch toggle-tag [path]
+projmux switch toggle-pin [path]
+projmux switch kill [path]
+projmux switch preview [--ui popup|sidebar] [path]
+projmux switch settings
+projmux switch cycle-pane <path> <next|prev>
+projmux switch cycle-window <path> <next|prev>
+projmux switch sidebar-focus <path>
+projmux switch sidebar-open --path <path> --anchor <pane> [--session <name>] [--mode <mode>] [--query <text>] [--client <client>]
 ```
 
 Project picker. With no positional argument, opens the configured picker popup
@@ -1252,7 +1384,7 @@ than a standalone Settings row.
 
 ```
 projmux diagnostics log [--tail N] [--json]
-                        [--level info|error] [--component NAME] [--path]
+                        [--level info|warn|error] [--component NAME] [--path]
 projmux diagnostics report [--output <path>]
 ```
 
@@ -1345,16 +1477,16 @@ which of them a command had touched.
 | `create project` | creates or reuses the Project, its canonical Window, and its shell | not started | not moved |
 | `start project` | unchanged | materialized when offline | not moved |
 | `open project` | unchanged | materialized when offline | moved to the Project |
-| `attach project` | unchanged | materialized when offline | the outside caller attaches |
+| `attach project` | unchanged; an absolute root no Project claims is registered as a new Project | materialized when offline | the outside caller attaches |
 | `focus project` | unchanged | never materialized | moved to the Project |
 | `stop project` | unchanged | the exact session ends | existing safe fallback |
 | `unregister project` | the Project subtree is removed | **preserved** | not moved |
 
 `open project` and `attach project` are the same operation seen from the two
 sides of a tmux client. Inside tmux, `open` moves the client you are in and
-`attach` refuses with a pointer at `open`; outside tmux, `attach` attaches the
-caller and `open` refuses with a pointer at `attach`. Both refusals happen
-before anything is materialized.
+`attach` refuses with a pointer at `focus project`; outside tmux, `attach`
+attaches the caller and `open` refuses with a pointer at `attach`. Both
+refusals happen before anything is materialized.
 
 `stop project` refuses an offline target rather than succeeding silently: it
 declares exactly one runtime outcome, and reporting `runtime=stopped` for a
@@ -1368,7 +1500,13 @@ one `compatibilityWarnings` entry in the receipt. It is not scheduled for
 removal in this release.
 
 The reference for a Project can be `uid:<uid>`, a bare `metadata.name`, or the
-absolute root path the Project claims.
+absolute root path the Project claims. `start`, `open`, `attach`, and `stop
+project` resolve these forms with one resolver, and a `uid:` or name that
+matches no Project is refused with exit 2 before anything is written or
+started. `attach project` also accepts an
+absolute path no Project claims yet: it registers that root as a new Project
+and then attaches, where `open project` refuses the same path and points at
+`projmux create project --root`.
 
 A Project registered without `--name` -- by `create project`, by opening an
 unregistered directory, or by `Clear layout and open` -- is named after its root
@@ -1471,8 +1609,8 @@ projmux notification reconcile [--json]
   `get notifications` and is considered only by reconcile together with a gone
   target. Reconcile also retains only the newest 256 rows. `--text` is hard-capped to 80 runes (longer text is
   truncated server-side). After a successful queue write, projmux sends a
-  best-effort refresh event to open native notify sidebars and fires
-  declarative `[hooks.send-noti]` asynchronously if configured. Event delivery
+  best-effort refresh event to open native notify sidebars and, if configured,
+  runs declarative `[hooks.send-noti]` and waits until it exits or its timeout. Event delivery
   failure does not fail the queue write; reopening the sidebar still shows the
   latest queue. The hook gets a JSON payload on stdin plus
   `PROJMUX_NOTIFY_*` env vars, and it does not replace the normal desktop
@@ -1629,19 +1767,21 @@ projmux internal status resources
 ## internal statusbar
 
 ```
-projmux internal statusbar click <range-id> [--socket <s>] [--mouse-window <id>]
-                                            [--client <tty>] [--mouse-x N] [--mouse-y N]
+projmux internal statusbar click <range-id> [--socket <s>] [--client <tty>]
+                                            [--mouse-x N] [--mouse-y N]
 projmux internal statusbar usage-refresh
 ```
 
 Click/keyboard dispatcher for the two-line status bar. Implemented range ids:
-`session pwd git resources usage notify settings`. The bare `window` /
-`window|<idx>` token (tmux's built-in window-list range) and the empty
-range fall through to `select-window -t @<mouse_window>` so the native
-click-to-switch tab affordance is preserved on row 1. Unknown range ids are
-non-specialized placeholders and no-op. `session` opens the existing-session
-popup; `pwd` shows the current pane path in a native-framed display-only
-popup; `git` opens the project switcher popup;
+`session pwd git resources usage notify settings`. Window-list clicks on
+row 1 are handled natively by the binding (`if-shell -F` on the bare `window`
+range runs `select-window -t =`); if a `window|<idx>` token reaches the
+dispatcher it selects `:<idx>`, and a bare `window` token is a no-op. The
+empty range and unknown range ids are no-ops. The binding passes only
+`#{mouse_status_range}` and `#{client_tty}`; `--mouse-window <v>` is accepted
+for compatibility with bindings from older releases and ignored. `session`
+opens the existing-session popup; `pwd` shows the current pane path in a
+native-framed display-only popup; `git` opens the project switcher popup;
 `settings` toggles the settings popup for the tmux client; `usage` opens the
 detailed cached account-usage popup. Legacy context rows are suppressed and
 named quotas retain exact identity/reset/freshness values. Claude model-scoped
@@ -1664,7 +1804,7 @@ projmux attention toggle [pane]
 projmux attention clear  [pane]
 projmux attention arm    [pane]
 projmux attention list   [--json] [--all]
-projmux attention window [window]
+projmux attention window [window] [style]
 ```
 
 Toggles the `✳` pane title prefix and the `@projmux_attention_state` pane
@@ -1695,6 +1835,7 @@ projmux agent status [get [<agent-ref>] | set <unknown|idle|in_progress|approval
 projmux agent topic get|clear [<agent-ref>] [--agent <ref>]
 projmux agent topic set <text> [<agent-ref>] [--agent <ref>]
 projmux agent capabilities [<agent-ref> | --provider <codex|claude|antigravity>] [-o json]
+projmux agent models [--provider claude] [-o json]
 projmux internal agent-hook watch-title [pane]
 projmux internal agent-hook ingest codex-hook [--pane <pane_uid|pane_id>] < payload.json
 projmux internal agent-hook ingest claude-hook [--pane <pane_uid|pane_id>] < payload.json
@@ -1761,107 +1902,261 @@ plain Agent on purpose; it is Codex-only and equivalent on `create agent
 multi-operand payloads, `agent resume`, Claude, and Antigravity are unaffected.
 See [Codex Native-Required Create Migration](codex-native-required-migration.md).
 
-An Agent can be given a persona: `create agent --provider claude
---persona <name>` (and `create claude --persona <name>`) appends the stored
-persona to the new session's system prompt through Claude's
+An Agent can be given named instructions: `create agent --provider claude
+--instructions <name>` (and `create claude --instructions <name>`) appends the
+stored content to the new session's system prompt through Claude's
 `--append-system-prompt-file`; it never replaces the system prompt, so Claude
-Code's own tool instructions stay. Personas are files in
-`<config dir>/personas/<name>.md` (by default `~/.config/projmux/personas/`),
-at most 64 KiB each, managed with `projmux persona list|show|edit|set|delete`
-(`edit` opens `$EDITOR`, then `$VISUAL`; `set <name> --file <path>` or `-` is
-the non-interactive write). A persona's content is fixed when it is given: the create
-copies the content to a content-addressed snapshot
-`<state dir>/personas/sha256-<hex>.md`, passes only that path on the Claude
-command line, and records `projmux.io/persona` and `projmux.io/persona-digest`
-on the Agent. `agent resume` and Continue/topology replay pass that same
-snapshot again, found from the recorded digest and never from the persona file,
-so editing or deleting the persona file later never changes an existing Agent.
-If the snapshot is gone, the resume still proceeds without the persona and
-discloses one `persona-unavailable` line (on stderr for `agent resume`, among
-the replay notices for Continue). A missing, oversized, or badly named persona
-refuses with `persona-not-found`, `persona-too-large`, or
-`persona-name-invalid`, all with zero Registry, tmux, and snapshot writes.
-
-A Codex Agent can be given a persona too, on one lane: a create that carries a
-prompt (`create agent --provider codex --persona <name> -- <prompt>`, and
-`create codex --persona <name> -- <prompt>`). That is the lane that opens a
-thread of its own, and starting the thread is the only moment Codex accepts a
-persona: the create sends the snapshot content as the thread's
-`developerInstructions`, and the shared app server records it once as the
+Code's own tool instructions stay. Manage the files with `projmux instructions
+list|show|edit|set|delete` (`edit` opens `$EDITOR`, then `$VISUAL`; `set
+<name> --file <path>` or `-` writes without an editor). The files are
+`<config dir>/personas/<name>.md` (by default
+`${XDG_CONFIG_HOME:-$HOME/.config}/projmux/personas/`), with a 64 KiB limit.
+The directory keeps its older name; no `instructions/` directory is created.
+The older command and flag names are listed under
+[Deprecated instruction spellings](#deprecated-instruction-spellings).
+`delete` refuses, with exit 2
+and `profile-instructions-in-use`, instructions that a stored
+[profile](configuration.md#agent-profiles) names -- valid or not -- lists
+each such profile, and deletes nothing; change or delete those profiles
+first. Instructions no profile names delete as before.
+
+The content is copied when an Agent starts: create copies it to the existing
+content-addressed snapshot `<state dir>/personas/sha256-<hex>.md`, passes only
+that path on the Claude command line, and records the existing
+`projmux.io/persona` and `projmux.io/persona-digest` keys on the Agent; the
+keys, too, keep their older name. `agent resume`,
+`agent relaunch`, Continue/topology replay, and a resume-picker create compare
+the current content of the instructions the Agent's
+[settings layers](#settings-layers) name with the recorded digest: when the
+file was edited, or the layers name other instructions, they pass a snapshot
+of the current content, record its digest and
+`projmux.io/system-prompt-snapshot=off`, and the Claude launch passes
+`--system-prompt-snapshot off`; when nothing changed they pass the recorded
+snapshot again. Instructions that cannot be read now keep the recorded
+snapshot, with one `persona-unavailable` line (on stderr for `agent resume`,
+among the replay notices for Continue; a resume-picker create, which already
+discloses what of the inherited snapshot it cannot re-pass, adds no line).
+An Agent with the old keys and snapshot resumes
+without migration. If the snapshot is gone, resume proceeds without the
+instructions and discloses one `persona-unavailable` line (on stderr for
+`agent resume`, among the replay notices for Continue). Missing, oversized,
+or badly named files refuse with the stable `persona-not-found`,
+`persona-too-large`, or `persona-name-invalid` reason and write no Registry,
+tmux, or snapshot state.
+
+A Codex Agent can be given named instructions directly or through a Profile
+when created with a prompt
+(`create agent --provider codex --instructions <name> -- <prompt>`, or
+`create codex --instructions <name> -- <prompt>`). This lane opens a thread of
+its own. Codex accepts the instructions when that thread starts: create sends
+the snapshot content as the thread's `developerInstructions`, and the shared app server records it once as the
 thread's `developer` message. The content goes over that connection and
 nowhere else -- never onto a command line, where `ps` would publish it -- and
 the create records the same `projmux.io/persona` and `projmux.io/persona-digest`
-annotations Claude records. From then on the thread carries the persona
-itself: `agent resume`, Continue/topology replay, and a resume picked from the
-Codex catalog re-send nothing and disclose nothing, because nothing was lost.
-A conversation opened from the resume picker inherits the two persona keys
-from the Agents that already record it, so the new Agent reports the persona
-its thread is running; it inherits no other launch value. A Codex Agent's
-persona cannot be changed afterwards: the instructions are fixed when the
-thread starts, `agent persona attach|detach` stays Claude-only, and starting
-over means a new Agent.
-
-Every other `--persona` create refuses with `persona-provider-unsupported` and
-zero Registry, tmux, and snapshot writes: a Codex create with no prompt or with
-`--interactive-only` (its plain lane would have to spell the persona into
-argv), `--dialogue-reply-only`, and any other provider.
-
-An existing Claude Agent can take on a persona later, or drop it:
-`projmux agent persona attach <agent-ref> <persona>` and
-`projmux agent persona detach <agent-ref>` (both with `[--project <ref>]
-[--window <ref>] [--yes] [--dry-run] [-o json]`). The Agent keeps its uid and
-its provider conversation. A Running Agent's managed Pane is closed through
-`delete pane`, which leaves it Offline, and the Agent is resumed through the
-same rebind `agent resume` uses, on a new managed Pane; an Offline or Failed
-Agent is only resumed. Before that the command writes the snapshot and records
-`projmux.io/persona`, `projmux.io/persona-digest`, and
-`projmux.io/system-prompt-snapshot=off` in one Registry change (detach removes
-the first two). The last key is sticky and makes every later resume of that
-Agent pass `--system-prompt-snapshot off`: Claude records the system prompt of
-a conversation's first request and replays that record on resume, so without
-it a persona attached after the conversation started would be ignored on the
-next resume. In steady state that costs little: each resume re-creates a
+annotations Claude records. From then on the thread carries the instructions: `agent resume`,
+Continue/topology replay, and a resume picked from the Codex catalog re-send
+nothing and disclose nothing, because nothing was lost.
+A conversation opened from the resume picker inherits the two stored
+instruction keys from Agents that already record it, so the new Agent reports
+the instructions its thread is running; it inherits no other launch value. A
+Codex Agent's instructions cannot be changed afterwards: the instructions are fixed when the
+thread starts. `agent relaunch` refuses a change of them with
+`codex-instructions-immutable` before writing a snapshot or Registry state or
+stopping a Pane. Codex resume replays the original developer message, even
+when a new instruction is supplied to its CLI or app server. Start a new Agent
+with a prompt to use different instructions.
+
+Every other `--instructions` create refuses with
+`persona-provider-unsupported` and zero Registry, tmux, and snapshot writes:
+a Codex create with no prompt or with `--interactive-only` (its plain lane
+cannot carry private developer instructions without exposing their body in
+the process arguments), `--dialogue-reply-only`, and any other provider. The
+refusal tells the operator to create a new Agent with `-- <prompt>` and omit
+`--interactive-only`.
+
+An existing Claude Agent's named instructions are changed with
+`projmux agent relaunch <agent-ref> --instructions <name>` and removed with
+`--instructions none`, both described below. A change of instructions after the
+conversation started records `projmux.io/system-prompt-snapshot=off`. The key
+is sticky and makes every later resume of that Agent pass
+`--system-prompt-snapshot off`: Claude records the system prompt of a
+conversation's first request and replays that record on resume, so without it
+instructions given after the conversation started would be ignored on the next
+resume. In steady state that costs little: each resume re-creates a
 byte-identical system prompt, so the prompt cache still hits and the extra cost
 is a few dozen cache-creation tokens per resume (measured +4 to +45); after the
 environment context in the system prompt changes (date, git state, CLAUDE.md),
-the first resume can re-cache the prompt prefix once. A Running Agent whose
-interaction is not `idle` or
-`response_complete` -- `unknown` included -- is refused with
-`persona-agent-busy` unless `--yes` confirms cutting its turn, and `--dry-run`
-(`-o json` for scripts) reports the target, its interaction, the current and
-new persona, and whether that confirmation is required without changing
-anything. The Agent owning the Pane the command runs in is refused with
-`persona-self-target`; an Agent with no stored conversation is refused with
-`persona-no-conversation`. Attaching the persona an Agent already runs with,
-same name and same content digest, reports `unchanged` and restarts nothing;
-after the persona file is edited the digest differs and the attach restarts
-with the new snapshot. Outside tmux the stop needs `--socket <name>` or
-`--socket-path <absolute>`, exactly as `delete pane` does. Refusals leave no
-snapshot, Registry, or Pane change. If the resume fails after the stop, the
-Agent stays Offline with its new annotations and stderr prints the
-`projmux agent resume uid:<agent> --project uid:<project> --window uid:<window>`
-command that finishes the job with the persona. If closing the managed Pane
-reports an error, the command checks whether that Pane is still alive: if it
-is, the previous annotations are restored; if it is already closed, the new
-annotations are kept and the resume proceeds with a warning on stderr (a failed
-resume prints the recovery command above); if it cannot tell, the previous
-annotations are restored and stderr prints the command to re-run.
+the first resume can re-cache the prompt prefix once.
 
 A Claude Agent created with `--effort <level>` records it as `projmux.io/effort`
 on the Agent, because Claude does not restore a conversation's effort on
 resume. Every resume passes it again as `--effort <level>`: `agent resume`,
-Continue/topology replay, and the restart of `agent persona attach|detach`. A
-recorded value that is not one of `low`, `medium`, `high`, `xhigh`, or `max` is
+Continue/topology replay, and the restart of `agent relaunch`. A recorded
+value that is not one of `low`, `medium`, `high`, `xhigh`, or `max` is
 skipped, the resume still proceeds, and one `effort-invalid` line is disclosed
-where a `persona-unavailable` line would be. The model given with `--model` is
-not recorded or passed again: Claude restores the conversation's model itself
-on resume, and passing the create-time model would override a `/model` switch
-made in the session.
+where a `persona-unavailable` line would be. The model given with `--model`
+(or filled in by a profile) is recorded as `projmux.io/model`, exactly as it
+was passed, but never passed again: Claude restores the conversation's model
+itself on resume, and passing the create-time model would override a `/model`
+switch made in the session. The record is the requested model, not
+necessarily the one the provider runs now. A create without `--model` records
+no model.
+
+`projmux agent resume <ref> [--model <model>] [--effort <level>]` resumes an
+Offline or Failed Claude or Codex Agent on the same UID and conversation with
+another model or effort. `--model` is passed on that launch only and recorded
+as `projmux.io/model`; the provider's conversation keeps the model on later
+resumes, which do not pass it again. `--effort` is recorded as
+`projmux.io/effort`, so later plain resumes pass it again. Both are recorded in
+the resume's own transaction, so a resume that fails rolls back and records
+neither. A resume without `--model` leaves a recorded model as it was. Both flags take create's values and refusals: any
+other provider, an invalid model or effort, and `--dialogue-reply-only` are
+refused before anything changes (`nothing was changed`).
+
+`--dialogue-reply-only` on `create agent` or `agent resume` launches a Claude
+Agent into the reply-only activation and records that on the Agent as
+`projmux.io/dialogue-reply-only=on`, in the transaction of that launch. From
+then on every resume of the Agent is the reply-only activation again:
+`agent resume` without the flag, `agent relaunch`, and the restart of
+`agent instructions attach|detach`, whether the Agent is Running or Offline
+with no managed Pane left. Nothing removes the record; an Agent that should
+run without it is a new Agent. Because that launch is fixed, a request it
+cannot carry is refused before anything changes (`nothing was changed`):
+`--profile`, `none` included (`profile-lane-unsupported`); `--instructions`,
+a `--reset` of the instructions, and `agent instructions attach|detach`
+(`persona-provider-unsupported`); and `--model`, `--effort`, or any other
+`--reset` (`reply-only-launch-fixed`), on `agent resume` too. A plain
+`agent relaunch` of a Running reply-only Agent compares only what that launch
+carries -- not the agent guidance or the Project's label link rules -- so it
+reports `unchanged`. An Agent made reply-only before the record existed
+carries none and is resumed as an ordinary Agent unless the flag is given
+again.
+
+`projmux agent relaunch <agent-ref> [--profile <name>|none] [--instructions
+<name>|none] [--model <model>] [--effort <level>] [--reset <item>[,...]|all]
+[--project <ref>] [--window <ref>] [--yes] [--dry-run] [--socket <name> |
+--socket-path <absolute>] [-o json]` restarts one existing Claude or Codex
+Agent on the same UID and the same provider conversation with other settings,
+all in one restart. It is the one way to change an Agent's
+[settings layers](#settings-layers):
+
+- `--profile <name>` switches the Agent to that profile (`none`: to no
+  profile). A switch clears every override: the instructions, model, and
+  effort take the new profile's values (none where it sets none), its
+  permissions apply, and only the overrides given with it (`--instructions`,
+  `--model`, `--effort`) are overrides again. The profile is recorded with
+  `projmux.io/profile-source=relaunch`. Naming the profile the Agent already
+  has is no switch: its overrides stay. This is how an Agent created before
+  profiles, or created without one, gets a profile; a `role` label is read
+  only when an Agent is created, never by a relaunch.
+- `--instructions <name>` overrides the instructions (`none`: explicitly no
+  instructions), `--model` and `--effort` override the model and the effort.
+- `--reset <item>[,...]` removes the override of `instructions`, `model`, or
+  `effort` (`all`: of every item), so the item takes the profile's current
+  value again, or none where the profile sets none or there is no profile. A
+  model left without a value is not passed and its recorded value is removed.
+  Giving an item a value and resetting it in the same command is a usage
+  error.
+
+Without any of them it restarts the Agent with the settings its layers resolve
+to now -- after a profile edit, for example -- and reports `unchanged` when
+they are what the Agent runs already. A Running Agent's managed
+Pane is closed through `delete pane`, and the Agent is brought back through the
+`agent resume` rebind with the overrides (outcome `restarted`, with the new
+Pane in `newPaneUID`); an Offline or Failed Agent is only resumed (outcome
+`resumed`). The new Pane carries the closed Pane's name unless that name was
+its own uid; when the name cannot be carried (another Pane took it), the new
+Pane keeps its automatic name and stderr says why in one `projmux: agent/<name>
+new Pane keeps an automatic name: <reason>` line. An Offline or Failed Agent,
+here and on `agent resume`, carries the name of its old Pane row instead; when
+no such row is left -- `delete pane` removed it -- the new Pane is named
+`<agent-name>-pane`, as `create agent` names it. That name falls back to the
+automatic one the same way: with the same stderr line when another resource
+holds it, and silently when it is too long to be a name. A name given with
+`rename pane` is not remembered once its row is gone. The settings are recorded by the rebind transaction -- the profile,
+`projmux.io/model`, `projmux.io/effort`, the instructions, and their sources --
+so a failed launch records none of them; later plain resumes pass the effort
+again but not the model. Nothing is written before the stop. On a Codex Agent the model and effort ride the
+native resume as `-m <model>` and `-c model_reasoning_effort=<level>`.
+
+The refusals all happen before any Registry, tmux, or Pane change, ending with
+`nothing was changed`: a provider other than Claude or Codex
+(`relaunch-provider-unsupported`); an invalid model or effort (create's
+refusal); an Agent with no stored conversation, one that is not Running,
+Offline, or Failed, or one whose final resume would be refused (a Codex thread
+with no durable endpoint included) (`relaunch-no-conversation`); the Agent
+whose managed Pane the command runs in (`relaunch-self-target`) -- an
+environment inherited from that Pane is not enough on its own, the command must
+be one of that Pane's processes, and when that cannot be determined the refusal
+says so; and a Running Agent whose interaction is not `idle` or
+`response_complete` -- `unknown` included -- without `--yes`
+(`relaunch-agent-busy`). An Agent that records the reply-only activation
+refuses every `--profile`, `--instructions`, `--model`, `--effort`, and
+`--reset` with the reasons given for it above. A change to the layers
+adds its own: a profile that does not exist or that `profile list` marks
+invalid (the store's reason, such as `profile-not-found`) or that names another
+provider (`profile-provider-mismatch`); instructions that cannot be read
+(`persona-not-found`), named or brought by a profile or a reset; on a Codex
+Agent, any change of its instructions -- `--instructions`, a profile with other
+instructions, or a reset of them (`codex-instructions-immutable`: its thread
+keeps the developer message it started with) -- and a profile switch that
+would leave the thread on the old profile's sandbox or approval, because the
+new profile sets none where the old one set one or cannot be read
+(`relaunch-codex-permissions-kept`: a Codex resume can set a sandbox or an
+approval but not remove one). A Codex switch to a profile with the same
+instructions and both permissions, and any model or effort, is allowed.
+Outside tmux the stop needs `--socket <name>` or `--socket-path <absolute>`,
+exactly as `delete pane` does. A Running Agent without `--model` whose
+settings, `--effort` included, resolve to exactly what it was launched with,
+whose agent guidance and Project label link rules are the ones it recorded,
+and whose `--profile`, `--instructions`, or `--reset` changes no recorded value,
+source, or profile, reports `unchanged` and restarts nothing; `--model` always restarts, because the
+recorded model is the last one requested, not necessarily the one the provider
+runs now (a `/model` switch in the session is not observed). `--dry-run` changes nothing and
+reports `would-restart` or `would-resume`.
+
+`-o json` prints exactly one object with `action` (`relaunch`), `dryRun`,
+`outcome` (`unchanged`, `restarted`, `resumed`, `would-restart`, or
+`would-resume`), `agentUID`, `agentName`, `provider`, `phase`, `interaction`,
+`paneUID`, `newPaneUID`, `currentEffort` (the recorded effort),
+`currentModel` (the recorded model, the last one requested), `newEffort`
+(the requested effort; empty when only `--model` is given, and the recorded
+effort carries on), `newModel`, `restart`, `confirmationRequired`,
+`unchanged`, `currentSettings` and `newSettings` (the settings as the Agent
+recorded them and as the relaunch runs them: `profile` with `name`, `digest`,
+and `source`, and `instructions`, `model`, and `effort` each with `value`,
+`source` -- empty when not known -- `profileValue`, and `override`), and
+`relaunchReasons` (why the relaunch would launch something other than what the
+Agent recorded, in this order: `profile-changed`, `instructions-changed`,
+`instructions-content-changed`, `model-changed`, `effort-changed`,
+`guidance-changed` (the current agent guidance digest differs from the
+recorded `projmux.io/agent-guidance-digest`: guidance added, edited, or turned
+off), `link-rules-changed` (the Project's current label link rules digest
+differs from the recorded `projmux.io/project-link-rules-digest`); empty when
+it would not. The last two are Claude only, like the guidance and the rules
+themselves, and change no setting); the empty string fields before
+`currentSettings` are omitted. A switched profile, overridden or reset items,
+and their sources show on the `newSettings` side. Without `-o json` the output
+of the stop and the resume is followed by one result line, which also names
+the profile and the instructions when their names change (`profile=role
+instructions=lead`, `none` for none).
+
+If closing the managed Pane reports an error, the command checks whether that
+Pane is still alive: if it is, the old session keeps running and the command
+fails with the Registry unchanged; if it is already closed, the resume proceeds
+with a warning on stderr; if it cannot tell, stderr prints the same
+`projmux agent relaunch` command to re-run. If the resume fails after the stop,
+the Agent stays Offline with its previous settings and stderr prints the
+`projmux agent resume uid:<agent> --project uid:<project> --window
+uid:<window> --model <model> --effort <level>` command, with the flags that
+were given, that finishes the job; after `--profile`, `--instructions`, or
+`--reset`, which `agent resume` cannot carry, it prints the same
+`projmux agent relaunch` command instead, which only resumes the Offline Agent.
 
 A Claude conversation opened from the resume picker creates a new Agent, and
 when Agents in the Registry already record that conversation (in any Project or
-Window, live or not) the new Agent inherits their launch values: the persona
-and its snapshot (`projmux.io/persona`, `projmux.io/persona-digest`), the
+Window, live or not) the new Agent inherits their launch values: the named
+instructions and their snapshot (`projmux.io/persona`, `projmux.io/persona-digest`), the
 system prompt snapshot mode (`projmux.io/system-prompt-snapshot`), and the
 effort (`projmux.io/effort`). It launches with them and records them, so its own
 later resumes behave like theirs; a snapshot that is gone or an effort Claude
@@ -1870,10 +2165,247 @@ on `agent resume`. Inheritance happens only when every such Agent records the
 same values; if they disagree, nothing is inherited and one
 `launch-values-ambiguous` notice names them. The creator, topic, and
 labels of those Agents are never inherited, and they keep their conversation
-and annotations. A Codex picker selection inherits the two persona keys under
-the same agreement rule and nothing else -- the snapshot mode and the effort
+and annotations. A Codex picker selection inherits the two stored
+instruction keys under the same agreement rule and nothing else -- the snapshot mode and the effort
 are Claude launch options -- and it changes no argv, because the thread
-already carries the persona. Antigravity picker selections inherit nothing.
+already carries the instructions. Antigravity picker selections inherit nothing.
+
+### Deprecated instruction spellings
+
+These spellings are no longer in `projmux help`, in any route's help listing or
+synopsis, or in the [CLI reference](cli.md). Each still runs with the stdout,
+`-o json`, exit code, and reason tokens it had and still answers `--help`; it
+adds one line on stderr that names its replacement:
+
+```text
+projmux: persona list is deprecated; use `projmux instructions list` instead.
+```
+
+None is scheduled for removal in this release.
+
+| Deprecated | Use |
+| --- | --- |
+| `projmux persona list\|show\|edit\|set\|delete` | `projmux instructions list\|show\|edit\|set\|delete` |
+| `--persona <name>` on `create agent`, `create claude`, and `create codex` | `--instructions <name>` |
+| `projmux agent instructions attach <agent-ref> <name>`, `projmux agent persona attach <agent-ref> <persona>` | `projmux agent relaunch <agent-ref> --instructions <name>` |
+| `projmux agent instructions detach <agent-ref>`, `projmux agent persona detach <agent-ref>` | `projmux agent relaunch <agent-ref> --instructions none` |
+
+`projmux persona` and `--persona` read and write the same files and record
+the same keys as `projmux instructions` and `--instructions`; their output says
+`persona` where the replacement says `instructions`. A create given both
+`--instructions` and `--persona` is refused.
+
+An attach (`projmux agent instructions attach <agent-ref> <name>`) or a detach
+(`projmux agent instructions detach <agent-ref>`, both with `[--project <ref>]
+[--window <ref>] [--yes] [--dry-run] [-o json]`) is the relaunch in the table
+above, recorded with the source `attach` and printed in the attach's own output: the same
+restart, the same [settings layers](#settings-layers), and the same launch.
+`agent persona attach|detach` is the same command and says `persona` where
+`agent instructions attach|detach` says `instructions`. Both names operate on
+the same Agent keys, snapshot, and digest. The Agent keeps its uid and provider
+conversation. A Running Agent's managed Pane is closed through
+`delete pane`, which leaves it Offline, and the Agent is resumed through the
+same rebind `agent resume` uses, on a new managed Pane; an Offline or Failed
+Agent is only resumed. Before that the command writes the snapshot and records
+`projmux.io/persona`, `projmux.io/persona-digest`, and
+`projmux.io/system-prompt-snapshot=off` in one Registry change (detach removes
+the first two). A Running Agent whose interaction is not `idle` or
+`response_complete` -- `unknown` included -- is refused with
+`persona-agent-busy` unless `--yes` confirms cutting its turn, and `--dry-run`
+(`-o json` for scripts) reports the target, its interaction, the current and
+new instructions, and whether that confirmation is required without changing
+anything. The Agent whose managed Pane the command runs in is refused with
+`persona-self-target`: an environment inherited from that Pane is not enough on
+its own, the command must be one of that Pane's processes, and when that cannot
+be determined the refusal says so. An Agent with no stored conversation is
+refused with `persona-no-conversation`. Attaching the instructions an Agent already runs with,
+same name and same content digest, with the snapshot mode off, reports
+`unchanged` and restarts nothing, unless the Agent's other settings resolve to
+something else (a profile edit, for example); after the instructions file is
+edited the digest differs and the attach restarts with the new snapshot. Unlike
+`agent relaunch`, which writes nothing before the stop, an attach records the
+instructions before it, so a plain `agent resume` finishes an attach whose
+resume failed. Outside tmux the stop needs `--socket <name>` or
+`--socket-path <absolute>`, exactly as `delete pane` does. Refusals leave no
+snapshot, Registry, or Pane change. If the resume fails after the stop, the
+Agent stays Offline with its new annotations and stderr prints the
+`projmux agent resume uid:<agent> --project uid:<project> --window uid:<window>`
+command that finishes the job with the instructions. If closing the managed Pane
+reports an error, the command checks whether that Pane is still alive: if it
+is, the previous annotations are restored; if it is already closed, the new
+annotations are kept and the resume proceeds with a warning on stderr (a failed
+resume prints the recovery command above); if it cannot tell, the previous
+annotations are restored and stderr prints the command to re-run.
+
+### Agent profiles at create
+
+`create agent --profile <name>` (and the provider shortcuts) starts the Agent
+from a [profile](configuration.md#agent-profiles). Without `--profile`, a
+`--label role=<role>` selects the one profile whose `roles` lists that role; a
+role no profile lists selects none. A role that several profiles list
+(`profile-role-claimed`) refuses the create: remove the role from all but one
+of the listed profiles, or pass `--profile none`. A role whose one listing
+profile is invalid (`profile-role-profile-invalid`, naming the profile and its
+own reason) refuses too, rather than create the Agent without that profile's
+permissions: fix the profile, or pass `--profile none`. `--profile none`
+applies no profile and does no role mapping. The label is read only at
+creation. A profile that is missing, or that `profile list` marks invalid --
+including `profile-role-claimed` -- refuses the create with exit 2 and its
+reason token, whether it is named with `--profile` or selected by a role.
+
+A profile that names a `provider` applies only to Agents of that provider. Any
+other provider refuses the create with exit 2 (`profile-provider-mismatch`,
+naming both providers) before anything is written or launched, on every lane:
+`create agent --provider <p>`, the `create <provider>` shortcuts, a role label,
+and a create from the UI. A profile without `provider` applies to every
+provider.
+
+`create agent` may omit `--provider` when the profile it selects -- by
+`--profile` or by a role label -- names one; the Agent is then created with
+that provider, exactly as if `--provider` had spelled it. With a profile
+`reviewer` that sets `provider = "codex"`:
+
+```sh
+projmux create agent --profile reviewer --project alpha --window main -- "review the diff"
+```
+
+An explicit `--provider` still wins and is still refused when it differs from
+the profile's. A profile that cannot be resolved refuses with its own reason.
+Without a profile, with `--profile none`, or with a profile that names no
+provider, `create agent` still requires `--provider`.
+
+An explicit flag wins over the profile item it overlaps: `--instructions` over
+`instructions`, `--model` over `model`, `--effort` over `effort`. The profile's instructions go through the same path as
+`--instructions` (snapshot and `projmux.io/persona*` annotations, and the same
+Codex lane rule), its effort is recorded as `projmux.io/effort`, and its model
+as `projmux.io/model`. On
+Claude, `allow` and `deny` are passed as `--settings <snapshot>`. Claude does
+not get `sandbox` (`claude-sandbox-bash-only`: its sandbox confines only Bash)
+or `approval` (`claude-no-matching-permission-mode`).
+
+Codex applies `sandbox` and `approval` on every create and resume lane. A
+prompted native create sends them on `thread/start`, and a native resume sends
+them on `thread/resume`; a policy mismatch refuses the operation
+(`codex-thread-policy-mismatch`). Promptless and `--interactive-only` creates
+and CLI resumes pass `-s <sandbox>` and `-a <approval>` before the workspace
+and resume arguments. `full-access` is spelled `danger-full-access` for Codex.
+The CLI accepts `approval = "on-request"` or `"never"`. It refuses a profile
+with `approval = "untrusted"` before launch
+(`codex-cli-untrusted-approval-unsupported`); the native lane still accepts it.
+Codex does not get `allow` or `deny` (`codex-command-rules-unsupported`),
+which remain visible as skipped items. Codex applies Profile `model` and
+`effort`. Any other provider refuses a profile with permissions
+(`profile-permissions-unsupported-provider`) and skips `model` and `effort`
+(`provider-option-unsupported`). The reply-only activation refuses a profile
+(`profile-lane-unsupported`).
+
+The Agent records `projmux.io/profile` and `projmux.io/profile-digest`. The
+result names the profile and each item that was not applied, with its reason:
+`profile name=<name> digest=<digest>` and `profile-not-applied item=<item>
+provider=<provider> reason=<token>` lines after the receipt line, a `profile`
+object (`name`, `digest`, `notApplied`) in `-o receipt`, and the same lines on
+stderr for the other projections. Items replaced by a flag are disclosed as
+`overridden-by-flag`. A create that applies no profile prints exactly what it
+printed before.
+
+Every Claude resume of such an Agent -- `agent resume`, Continue/topology
+replay, and the resume picker -- re-reads the profile by name, passes its
+current rules as `--settings`, and records the new digest. A profile that is
+gone or invalid -- including one now marked `profile-role-claimed` -- refuses
+the resume (`profile-resume-unavailable`, naming the underlying reason); there is no
+resume without its permissions. `agent resume`, `agent relaunch`, and
+Continue/topology replay also take the profile's current instructions, model,
+and effort for the items the Agent does not override
+([settings layers](#settings-layers)); the resume picker resolves the values it
+inherits the same way, each an override of the new Agent. A resume
+picker selection inherits the profile when every Agent recording the
+conversation records the same one, and refuses when they disagree.
+
+A native Codex resume of such an Agent -- `agent resume`, and a resume picker
+selection of an app-server thread -- re-reads the profile by name the same
+way, sends its current `sandbox` and `approval` on `thread/resume`, and
+records the new digest. A thread that is already loaded keeps the policy it
+runs with, so a resume whose answer reports another policy is refused
+(`codex-thread-policy-mismatch`) and nothing is committed. Continue/topology
+replay and a resume picker rollout row resume Codex as `codex resume <id>`,
+which cannot carry a policy: when the Agent's profile now sets any permission
+they refuse (`profile-resume-unavailable`, `profile-lane-unsupported`), and a
+profile without permissions resumes as before. An Agent without a profile
+sends exactly the request it sent before.
+
+Each of those settings records where it came from, beside its value, so
+`describe agent -o json` tells a profile item apart from an override. The
+keys are `projmux.io/profile-source`, `projmux.io/instructions-source`,
+`projmux.io/model-source`, and `projmux.io/effort-source`; the values keep
+their own keys (`projmux.io/profile`, `projmux.io/persona`, `projmux.io/model`,
+`projmux.io/effort`), whose meaning does not change.
+
+| Source | Written by |
+| --- | --- |
+| `flag` | `create agent` (and a UI create) for `--profile`, `--instructions`, `--model`, and `--effort` |
+| `role` | `projmux.io/profile-source` only: the profile a `role` label selected |
+| `profile` | item sources only: the item the create's profile filled in, or that a resume, a relaunch `--reset`, or a relaunch `--profile` switch put in the profile layer |
+| `inherited` | a resume picker selection, for the profile, instructions, and effort it inherited |
+| `resume` | `agent resume --model/--effort` |
+| `relaunch` | `agent relaunch`: `--profile` (for `projmux.io/profile-source`), `--instructions`, `--model`, and `--effort` |
+| `attach` | `projmux.io/instructions-source` only: the deprecated attach and detach ([Deprecated instruction spellings](#deprecated-instruction-spellings)) |
+
+An item source other than `profile` means the value overrides the profile.
+After a detach the Agent records `projmux.io/instructions-source=attach`
+without `projmux.io/persona`: it was explicitly given no instructions. Every
+source is written in the same transaction as its value, so a launch that fails
+rolls back both, a restored attach or detach restores both, and a command that
+writes no value writes no source. An Agent without a source key recorded its
+value before sources were, and the source is unknown. The source keys are not
+part of the resume picker's inheritance agreement: Agents that record the same
+values with different sources still agree.
+
+<a id="settings-layers"></a>
+**Settings layers.** `agent resume`, `agent relaunch`, Continue (the topology
+replay that brings a Project's Agents back), and a resume-picker create launch
+an Agent with its settings resolved from two layers: an item the Agent overrides keeps the
+recorded value, and an item it does not override takes the profile's value as
+the profile is now (none when the profile sets none). The items are the
+instructions, the model, and the effort; permissions come only from the
+profile. So an edit to a profile reaches every Agent that uses it on its next
+`agent resume`, plain `agent relaunch`, or Continue, except for the items that
+Agent overrides, and each of those launches of one Agent passes the same
+model, effort, and instructions:
+
+- The effort is passed on every launch, as before.
+- The model is passed only when the resolved model differs from the recorded
+  `projmux.io/model` (a profile whose model changed); an unchanged model is not
+  passed, so the provider restores the conversation's own, a `/model` switch
+  included.
+- The instructions are passed as a snapshot of their current content, with
+  the system prompt snapshot off, when their name or content changed, as
+  described above. A Codex thread keeps the developer instructions it started
+  with: its resume passes the rest and discloses the instructions it did not
+  apply (`codex-instructions-immutable`), recording nothing for them.
+
+The launch records each value and source it ran with in its own transaction.
+An item without a source key predates sources; its layer is decided from its
+value: equal to the profile's current value means the profile layer, which the
+launch then records as `profile`, and anything else -- a value the profile does
+not set, or no value where the profile sets one -- is an override of unknown
+source that keeps no source key. An Agent without a profile overrides every
+item. So the first resume after the upgrade launches exactly what the Agent
+launched before.
+
+A resume-picker create resolves the Agent it records the same way: the
+values and the profile it inherits from the Agents that already hold the
+conversation are that Agent's record, where each inherited value is an
+override (source `inherited`) and an item nothing inherited follows the
+profile. Inherited instructions whose file was edited therefore launch as a
+snapshot of the new content with the system prompt snapshot off, exactly as
+`agent resume` of the new Agent would. No model is inherited, so none is
+passed. Which values are inherited, and when holders disagree, is unchanged.
+
+The layers change only through `agent relaunch` (and the deprecated attach and
+detach, which run the same restart): `--profile` switches the profile
+layer and clears the overrides, `--instructions`, `--model`, and `--effort`
+add overrides, and `--reset` removes them. An item with neither a profile nor
+an override has no value and no source.
 
 Automation callers get the new pane's handle from `-o pane-id` on the canonical
 create routes: `projmux create agent --provider <p> --placement right -o pane-id`
@@ -2288,6 +2820,40 @@ servers before installing current bindings. If the current keymap assigns `C-t`
 to another action, that current action is bound after cleanup and remains the
 owner.
 
+## profile
+
+```
+projmux profile list
+projmux profile show <name>
+projmux profile set <name> [--file <path> | -]
+projmux profile delete <name> --yes
+```
+
+A profile is a named set of Agent start settings -- provider, instructions,
+model, effort, roles, and permissions -- kept in `<config dir>/profiles/<name>.toml`.
+The file format and vocabulary are in
+[Configuration](configuration.md#agent-profiles). These commands store and
+validate profiles; `create agent --profile <name>` applies one (see
+[Agent profiles at create](#agent-profiles-at-create)).
+
+- `list` prints `NAME SOURCE PROVIDER INSTRUCTIONS MODEL EFFORT ROLES DIGEST
+  VALID` for every profile. `SOURCE` is `user`, and `DIGEST` is
+  `sha256:<hex>` over the file bytes. An item the profile does not name is
+  `-`; so is `PROVIDER` for a provider-neutral profile. A file that fails
+  validation stays listed as `no (<reason>)` and does not hide the others;
+  when it still parses, it shows what it names, roles included, and a file
+  that does not parse shows `-` for each item.
+- `show` prints the stored bytes exactly.
+- `set` validates the whole file first and writes it atomically (0600) only
+  when it is valid; `-` or no `--file` reads stdin. A refusal exits 2, prints
+  one stable reason (`profile-syntax-invalid`, `profile-key-unknown`,
+  `profile-table-unknown`, `profile-value-invalid`, `profile-provider-unknown`,
+  `profile-instructions-not-found`, `profile-role-duplicate`,
+  `profile-role-claimed`, `profile-name-invalid`, `profile-name-reserved`, or
+  `profile-too-large`), and leaves any existing file unchanged.
+- `delete` removes a user file. A missing profile is `profile-not-found` (exit
+  1).
+
 ## config
 
 ```
@@ -2454,8 +3020,8 @@ human configuration work should prefer `config render` and `config apply`.
   diagnostics guides: use `projmux setup` for key-delivery diagnosis,
   `projmux setup terminal` for supported terminal remediation, and the
   read-only `projmux doctor` report for dependency/runtime diagnostics. In Project
-  Picker, `Project Root` manages the saved
-  primary root (`~/.config/projmux/projdir`) and displays whether the effective
+  Picker, `Project Root` manages the saved primary root
+  (`$HOME/.config/projmux/projdir`) and displays whether the effective
   value comes from `PROJMUX_PROJDIR`, tmux `@projmux_projdir`, saved config, or
   no configured source. When no source is configured, the direct-set prompt
   starts with `$HOME` as an editable fallback, but `$HOME` is not used as the