projmux 0.16.0 → 0.16.1

package/docs/cli.md

@@ -39,7 +39,7 @@ Root parser bridges outside the route graph are censused from their parser token
 
 Every route declares one allowed-effect record over seven independent resource axes. A pipe separates conditional success outcomes; preflight refusal remains zero-effect. `domain-effect=null` means the route has no typed extension beyond this resource tuple.
 
-The machine-readable manifest contains 194 route-effect records, including hidden plumbing that the public route sections omit.
+The machine-readable manifest contains 239 route-effect records, including hidden plumbing that the public route sections omit.
 
 | Axis | Closed vocabulary |
 | --- | --- |
@@ -63,7 +63,7 @@ projmux <command> [args...]
 | [`projmux agent`](#projmux-agent) | canonical | Manage Agent state, messages, waits, capabilities, integrations, and account usage |
 | [`projmux attention`](#projmux-attention) | canonical | View and manage live tmux pane attention state |
 | [`projmux attach`](#projmux-attach) | canonical | Enter a Project runtime from outside tmux |
-| [`projmux config`](#projmux-config) | canonical | Edit AI split-mode and enabled-provider settings; render or apply generated tmux configuration |
+| [`projmux config`](#projmux-config) | canonical | Edit AI split-mode, enabled-provider, locale, and agent-question settings; render or apply generated tmux configuration |
 | [`projmux create`](#projmux-create) | canonical | Create Projmux resources |
 | [`projmux delete`](#projmux-delete) | canonical | Delete Projmux resources with an explicit cascade plan |
 | [`projmux describe`](#projmux-describe) | canonical | Describe one Projmux resource |
@@ -75,7 +75,8 @@ projmux <command> [args...]
 | [`projmux label`](#projmux-label) | canonical | Set or remove Projmux resource metadata.labels after creation |
 | [`projmux notification`](#projmux-notification) | canonical | Manage pending notification workflow state |
 | [`projmux open`](#projmux-open) | canonical | Open a Project runtime and move the current client to it |
-| [`projmux persona`](#projmux-persona) | canonical | List, show, edit, set, and delete Agent persona files |
+| [`projmux instructions`](#projmux-instructions) | canonical | List, show, edit, set, and delete Agent instruction files |
+| [`projmux profile`](#projmux-profile) | canonical | List, show, set, and delete named Agent profiles |
 | [`projmux pin`](#projmux-pin) | canonical | Manage pinned project directories |
 | [`projmux prune`](#projmux-prune) | canonical | Prune stale Projects and Agents |
 | [`projmux quit`](#projmux-quit) | shortcut | Quit the app-owned projmux tmux runtime |
@@ -118,24 +119,30 @@ Allowed effects:
 projmux agent status [get [<agent-ref>] | set <unknown|idle|in_progress|approval_required|input_required|response_complete> [<agent-ref>]] [--agent <ref>]
 projmux agent topic get|clear [<agent-ref>] [--agent <ref>]
 projmux agent topic set <text> [<agent-ref>] [--agent <ref>]
-projmux agent resume <ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]...
-projmux agent persona attach <agent-ref> <persona> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--yes] [--dry-run] [--socket <name> | --socket-path <absolute>] [-o json]
-projmux agent persona detach <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--yes] [--dry-run] [--socket <name> | --socket-path <absolute>] [-o json]
+projmux agent resume <ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]... [--model <model>] [--effort <level>] [--dialogue-reply-only]
+projmux agent relaunch <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]... [--profile <name>|none] [--instructions <name>|none] [--model <model>] [--effort <level>] [--reset <item>[,...]|all] [--yes] [--dry-run] [--socket <name> | --socket-path <absolute>] [-o json]
 projmux agent turn start|steer <agent-ref> -- <text>
-projmux agent turn interrupt <agent-ref>
+projmux agent turn interrupt <agent-ref> [--via <client>]
 projmux agent approval review <agent-ref> [--request <normalized-id>]
+projmux agent approval list <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]... [-o json]
+projmux agent approval answer <agent-ref> <request-id> (--allow | --deny) [--via <popup|cli|client>] [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]...
 projmux agent review [<agent-ref>] [--agent <ref>] [--base <branch> | --commit <sha> | --instructions <text>]
 projmux agent integrate <codex|claude|antigravity|tmux-bell> [--remove] [--dry-run]
 projmux agent usage [--model <codex|claude|all>] [--window <name>] [--json] [--force]
-projmux agent capabilities [<agent-ref> | --provider <codex|claude|antigravity>] [-o json]
+projmux agent capabilities [<agent-ref> | --provider <codex|claude|antigravity>] [-o json] [--json]
+projmux agent models [--provider <claude|codex>] [-o json]
 projmux agent message send <agent-ref> [--source <agent-ref>] [--message-ref <ref>] [--reply-to <ref>] [--ttl <duration>] -- <text>
 projmux agent message status <message-ref> [-o json]
-projmux agent message qualify <claude-agent-ref> --evidence <absolute-private-json> --confirm-isolated-provider-push -o json
+projmux agent message qualify <claude-agent-ref> --evidence <absolute-private-json> --confirm-isolated-provider-push -o json [--timeout <duration>]
 projmux agent wait <agent-ref> [--until idle] [--timeout <duration>] [-o json]
-projmux agent question enable <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]...
-projmux agent question disable <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]...
-projmux agent question list <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [-o json]
-projmux agent question answer <agent-ref> <question-id> [--option <n>=<label>]... [--index <n>=<k>]... [--text <n>=<text>]... [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]...
+projmux agent question enable <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]...
+projmux agent question disable <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]...
+projmux agent question list <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]... [-o json]
+projmux agent question answer <agent-ref> <question-id> [--option <n>=<label>]... [--index <n>=<k>]... [--text <n>=<text>]... [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]...
+projmux agent sessions list <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]... [-o json]
+projmux agent sessions backfill [--dry-run] [-o json]
+projmux agent sessions project <project-ref> [-o json]
+projmux agent sessions attribute [--dry-run] [-o json]
 ```
 
 Subcommands:
@@ -145,18 +152,20 @@ Subcommands:
 | [`projmux agent status`](#projmux-agent-status) | Read or set semantic Agent interaction independently of lifecycle |
 | [`projmux agent topic`](#projmux-agent-topic) | Read, set, or clear one exact Agent topic annotation |
 | [`projmux agent resume`](#projmux-agent-resume) | Rebind an Offline or Failed Agent detached on its Window's exact shell or Agent anchor |
-| [`projmux agent persona`](#projmux-agent-persona) | Attach or detach a persona on one exact Claude Agent and resume it on the same conversation |
-| [`projmux agent turn`](#projmux-agent-turn) | Send, steer, or interrupt one exact native Codex turn |
-| [`projmux agent approval`](#projmux-agent-approval) | Review one exact pending native Codex approval |
+| [`projmux agent relaunch`](#projmux-agent-relaunch) | Restart one exact Claude or Codex Agent on the same conversation with another profile, instructions, model, or effort |
+| [`projmux agent turn`](#projmux-agent-turn) | Send or steer one exact native Codex turn, or interrupt an exact Codex or Claude turn |
+| [`projmux agent approval`](#projmux-agent-approval) | Review one exact pending native Codex approval, or list and answer Claude and Codex permission requests |
 | [`projmux agent review`](#projmux-agent-review) | Start a native review on an exact-bound Codex Agent |
 | [`projmux agent integrate`](#projmux-agent-integrate) | Install, remove, or preview provider hooks and tmux-bell integration |
 | [`projmux agent usage`](#projmux-agent-usage) | Read provider account usage quota snapshots |
 | [`projmux agent capabilities`](#projmux-agent-capabilities) | Read static provider support or one exact Agent's Registry-backed runtime eligibility |
+| [`projmux agent models`](#projmux-agent-models) | List model suggestions for Claude (default) or Codex (app-server); other names are still accepted |
 | [`projmux agent message`](#projmux-agent-message) | Exchange bounded untrusted coordination messages; --source selects a source Agent anchor, not caller authentication (default: active Pane) |
 | [`projmux agent wait`](#projmux-agent-wait) | Wait read-only for one exact Agent's Registry-backed idle observation |
-| [`projmux agent question`](#projmux-agent-question) | Answer one exact opted-in Claude Agent's AskUserQuestion prompts from the command line |
+| [`projmux agent question`](#projmux-agent-question) | Answer one exact opted-in Claude or Codex Agent's questions from the command line |
+| [`projmux agent sessions`](#projmux-agent-sessions) | List the Claude or Codex conversations an Agent or a Project has moved through, backfill past Claude sessions from delivered message frames, or persist their current Registry affiliation |
 
-Canonical spelling: `projmux agent status`, `projmux agent topic`, `projmux agent resume`, `projmux agent persona attach`, `projmux agent persona detach`, `projmux agent turn start`, `projmux agent turn steer`, `projmux agent turn interrupt`, `projmux agent approval review`, `projmux agent review`, `projmux agent integrate`, `projmux agent usage`, `projmux agent capabilities`, `projmux agent message send`, `projmux agent message status`, `projmux agent message qualify`, `projmux agent wait`, `projmux agent question enable`, `projmux agent question disable`, `projmux agent question list`, `projmux agent question answer`
+Canonical spelling: `projmux agent status`, `projmux agent topic`, `projmux agent resume`, `projmux agent relaunch`, `projmux agent turn start`, `projmux agent turn steer`, `projmux agent turn interrupt`, `projmux agent approval review`, `projmux agent approval list`, `projmux agent approval answer`, `projmux agent review`, `projmux agent integrate`, `projmux agent usage`, `projmux agent capabilities`, `projmux agent models`, `projmux agent message send`, `projmux agent message status`, `projmux agent message qualify`, `projmux agent wait`, `projmux agent question enable`, `projmux agent question disable`, `projmux agent question list`, `projmux agent question answer`, `projmux agent sessions list`, `projmux agent sessions backfill`, `projmux agent sessions project`, `projmux agent sessions attribute`
 
 ### `projmux agent status`
 
@@ -219,43 +228,22 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux agent resume <ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]...
+projmux agent resume <ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]... [--model <model>] [--effort <level>] [--dialogue-reply-only]
 ```
 
-### `projmux agent persona`
+A Codex CLI resume reapplies the Agent's current Profile sandbox and approval. Codex CLI cannot apply approval=untrusted; that resume is refused before creating a Pane.
 
-Attach or detach a persona on one exact Claude Agent and resume it on the same conversation
+Codex keeps the developer instructions its thread started with; resume cannot replace them.
 
-Selectorless authority: `explicit-target` — the route or caller must name the exact target.
-
-Allowed effects:
+--model and --effort are recorded on the Agent with the source resume (projmux.io/model-source, projmux.io/effort-source).
 
-- `identity=unchanged`
-- `address=unchanged`
-- `topology=unchanged`
-- `desired-state=unchanged`
-- `runtime=unchanged`
-- `focus=unchanged`
-- `cardinality=exact-one`
-- `domain-effect=null`
+Items the Agent does not override take its profile's current instructions, model, and effort; the model is passed only when it changed.
 
-```
-projmux agent persona attach <agent-ref> <persona> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--yes] [--dry-run] [--socket <name> | --socket-path <absolute>] [-o json]
-projmux agent persona detach <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--yes] [--dry-run] [--socket <name> | --socket-path <absolute>] [-o json]
-```
+The new Pane carries the name of the Agent's old Pane row; when delete pane left no such row, it is named <agent-name>-pane as create agent names it. A name that cannot be used leaves the automatic one, and a held name is disclosed in one stderr line.
 
-Subcommands:
+### `projmux agent relaunch`
 
-| Route | Summary |
-| --- | --- |
-| [`projmux agent persona attach`](#projmux-agent-persona-attach) | Give one exact Claude Agent a persona and restart it on the same conversation |
-| [`projmux agent persona detach`](#projmux-agent-persona-detach) | Take the persona off one exact Claude Agent and restart it on the same conversation |
-
-Canonical spelling: `projmux agent persona attach`, `projmux agent persona detach`
-
-#### `projmux agent persona attach`
-
-Give one exact Claude Agent a persona and restart it on the same conversation
+Restart one exact Claude or Codex Agent on the same conversation with another profile, instructions, model, or effort
 
 Selectorless authority: `explicit-target` — the route or caller must name the exact target.
 
@@ -271,37 +259,22 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux agent persona attach <agent-ref> <persona> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--yes] [--dry-run] [--socket <name> | --socket-path <absolute>] [-o json]
+projmux agent relaunch <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]... [--profile <name>|none] [--instructions <name>|none] [--model <model>] [--effort <level>] [--reset <item>[,...]|all] [--yes] [--dry-run] [--socket <name> | --socket-path <absolute>] [-o json]
 ```
 
-Output modes (`-o`): `json`
-
-#### `projmux agent persona detach`
-
-Take the persona off one exact Claude Agent and restart it on the same conversation
+The model and effort are recorded on the Agent (projmux.io/model, projmux.io/effort) with the source relaunch (projmux.io/model-source, projmux.io/effort-source); later resumes re-pass the effort but not the model.
 
-Selectorless authority: `explicit-target` — the route or caller must name the exact target.
+--profile switches the Agent's profile (none: no profile) and clears every override but the ones given with it; naming the profile it has keeps its overrides. --instructions overrides the instructions (none: no instructions), and --reset removes the overrides of instructions, model, or effort (all: every one) so they follow the profile again. It is all one restart.
 
-Allowed effects:
-
-- `identity=unchanged|reused`
-- `address=unchanged`
-- `topology=unchanged|replaced`
-- `desired-state=unchanged|replaced`
-- `runtime=unchanged|materialized`
-- `focus=unchanged`
-- `cardinality=exact-one`
-- `domain-effect=null`
+A Codex Agent refuses a change of its instructions (codex-instructions-immutable) and a profile switch that would keep the old sandbox or approval (relaunch-codex-permissions-kept).
 
-```
-projmux agent persona detach <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--yes] [--dry-run] [--socket <name> | --socket-path <absolute>] [-o json]
-```
+Without flags it restarts the Agent with the settings its profile and overrides resolve to now, or reports unchanged; -o json carries currentSettings, newSettings, and relaunchReasons.
 
 Output modes (`-o`): `json`
 
 ### `projmux agent turn`
 
-Send, steer, or interrupt one exact native Codex turn
+Send or steer one exact native Codex turn, or interrupt an exact Codex or Claude turn
 
 Selectorless authority: `explicit-target` — the route or caller must name the exact target.
 
@@ -318,7 +291,7 @@ Allowed effects:
 
 ```
 projmux agent turn start|steer <agent-ref> -- <text>
-projmux agent turn interrupt <agent-ref>
+projmux agent turn interrupt <agent-ref> [--via <client>]
 ```
 
 Subcommands:
@@ -327,7 +300,7 @@ Subcommands:
 | --- | --- |
 | [`projmux agent turn start`](#projmux-agent-turn-start) | Send a new turn to one exact idle Codex thread |
 | [`projmux agent turn steer`](#projmux-agent-turn-steer) | Request provider acceptance for one exact current Codex turn; delivery remains unconfirmed |
-| [`projmux agent turn interrupt`](#projmux-agent-turn-interrupt) | Interrupt one exact current Codex turn |
+| [`projmux agent turn interrupt`](#projmux-agent-turn-interrupt) | Interrupt one exact current Codex turn or send Esc to one fresh in-progress Claude turn |
 
 Canonical spelling: `projmux agent turn start`, `projmux agent turn steer`, `projmux agent turn interrupt`
 
@@ -375,7 +348,7 @@ projmux agent turn steer <agent-ref> -- <text>
 
 #### `projmux agent turn interrupt`
 
-Interrupt one exact current Codex turn
+Interrupt one exact current Codex turn or send Esc to one fresh in-progress Claude turn
 
 Selectorless authority: `explicit-target` — the route or caller must name the exact target.
 
@@ -391,12 +364,14 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux agent turn interrupt <agent-ref>
+projmux agent turn interrupt <agent-ref> [--via <client>]
 ```
 
+Claude requires explicit --via <client>: cli, popup, or an operator client name of 1-32 lowercase ASCII letters, digits, and '-', starting with a letter; another name is refused as operator-client-invalid. The source is reported by the caller and does not prove which client was used or who the user is. A sent Esc confirms tmux delivery, not Claude cancellation. The private state file agent-turn-interrupt-audit.jsonl records the exact Agent and Pane UIDs, time, source, and delivery outcome.
+
 ### `projmux agent approval`
 
-Review one exact pending native Codex approval
+Review one exact pending native Codex approval, or list and answer Claude and Codex permission requests
 
 Selectorless authority: `explicit-target` — the route or caller must name the exact target.
 
@@ -413,6 +388,8 @@ Allowed effects:
 
 ```
 projmux agent approval review <agent-ref> [--request <normalized-id>]
+projmux agent approval list <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]... [-o json]
+projmux agent approval answer <agent-ref> <request-id> (--allow | --deny) [--via <popup|cli|client>] [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]...
 ```
 
 Subcommands:
@@ -420,8 +397,10 @@ Subcommands:
 | Route | Summary |
 | --- | --- |
 | [`projmux agent approval review`](#projmux-agent-approval-review) | Review one exact pending native Codex approval |
+| [`projmux agent approval list`](#projmux-agent-approval-list) | List one exact Claude or Codex Agent's waiting permission requests with their full tool input |
+| [`projmux agent approval answer`](#projmux-agent-approval-answer) | Allow or deny one waiting Claude or Codex permission request once; the first answer wins |
 
-Canonical spelling: `projmux agent approval review`
+Canonical spelling: `projmux agent approval review`, `projmux agent approval list`, `projmux agent approval answer`
 
 #### `projmux agent approval review`
 
@@ -444,6 +423,64 @@ Allowed effects:
 projmux agent approval review <agent-ref> [--request <normalized-id>]
 ```
 
+#### `projmux agent approval list`
+
+List one exact Claude or Codex Agent's waiting permission requests with their full tool input
+
+Selectorless authority: `explicit-target` — the route or caller must name the exact target.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=exact-one`
+- `domain-effect=null`
+
+```
+projmux agent approval list <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]... [-o json]
+```
+
+A Claude Agent lists the permission requests captured while `config agent-approvals --answering projmux` is set.
+
+A Codex Agent lists the pending approvals of its exact native control binding in either answering way: toolName is the approval kind, toolInput its details, answers the flags `agent approval answer` can send, and denyDecision what --deny sends (decline: the turn continues; cancel: the turn stops). An ambiguous request id, or one offering neither allow nor deny, is marked for `agent approval review`.
+
+A listed request may already have been answered in Claude Code's own prompt, the Codex TUI, or `agent approval review`, which stay usable; the first answer wins.
+
+Output modes (`-o`): `json`
+
+#### `projmux agent approval answer`
+
+Allow or deny one waiting Claude or Codex permission request once; the first answer wins
+
+Selectorless authority: `explicit-target` — the route or caller must name the exact target.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=exact-one`
+- `domain-effect=null`
+
+```
+projmux agent approval answer <agent-ref> <request-id> (--allow | --deny) [--via <popup|cli|client>] [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]...
+```
+
+--allow runs that one tool call as requested; it never changes a permission rule or the tool input. --deny blocks it. Exactly one of them is required.
+
+--via (default cli) is recorded in the audit log as the caller reports it; it is not verified. It takes popup, cli, or an operator client name under the same rule as `agent turn interrupt --via`; another name is refused as operator-client-invalid.
+
+A second or late answer, or one on a request already answered in Claude Code's own prompt, is refused as permission-not-pending.
+
+For a Codex Agent, --allow sends accept, never a widened grant; --deny sends decline when offered, otherwise cancel, which also interrupts the turn; nothing runs either way. A request offering no fitting decision is refused as permission-decision-unavailable, and the result line names the decision sent. It needs `config agent-approvals --answering projmux`, an unknown or ambiguous id is permission-not-pending, and the allowed or denied audit line is written before the answer is sent. `agent approval review` keeps every decision and the picker.
+
 ### `projmux agent review`
 
 Start a native review on an exact-bound Codex Agent
@@ -525,7 +562,30 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux agent capabilities [<agent-ref> | --provider <codex|claude|antigravity>] [-o json]
+projmux agent capabilities [<agent-ref> | --provider <codex|claude|antigravity>] [-o json] [--json]
+```
+
+Output modes (`-o`): `json`
+
+### `projmux agent models`
+
+List model suggestions for Claude (default) or Codex (app-server); other names are still accepted
+
+Selectorless authority: `natural-omitted` — omission resolves one predictable current resource or documented contextual read/scope; any selector replaces it.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=unchanged`
+- `domain-effect=null`
+
+```
+projmux agent models [--provider <claude|codex>] [-o json]
 ```
 
 Output modes (`-o`): `json`
@@ -550,7 +610,7 @@ Allowed effects:
 ```
 projmux agent message send <agent-ref> [--source <agent-ref>] [--message-ref <ref>] [--reply-to <ref>] [--ttl <duration>] -- <text>
 projmux agent message status <message-ref> [-o json]
-projmux agent message qualify <claude-agent-ref> --evidence <absolute-private-json> --confirm-isolated-provider-push -o json
+projmux agent message qualify <claude-agent-ref> --evidence <absolute-private-json> --confirm-isolated-provider-push -o json [--timeout <duration>]
 ```
 
 Subcommands:
@@ -625,7 +685,7 @@ Allowed effects:
 - `domain-effect=agent-delivery`
 
 ```
-projmux agent message qualify <claude-agent-ref> --evidence <absolute-private-json> --confirm-isolated-provider-push -o json
+projmux agent message qualify <claude-agent-ref> --evidence <absolute-private-json> --confirm-isolated-provider-push -o json [--timeout <duration>]
 ```
 
 Output modes (`-o`): `json`
@@ -655,7 +715,7 @@ Output modes (`-o`): `json`
 
 ### `projmux agent question`
 
-Answer one exact opted-in Claude Agent's AskUserQuestion prompts from the command line
+Answer one exact opted-in Claude or Codex Agent's questions from the command line
 
 Selectorless authority: `explicit-target` — the route or caller must name the exact target.
 
@@ -671,26 +731,26 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux agent question enable <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]...
-projmux agent question disable <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]...
-projmux agent question list <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [-o json]
-projmux agent question answer <agent-ref> <question-id> [--option <n>=<label>]... [--index <n>=<k>]... [--text <n>=<text>]... [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]...
+projmux agent question enable <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]...
+projmux agent question disable <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]...
+projmux agent question list <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]... [-o json]
+projmux agent question answer <agent-ref> <question-id> [--option <n>=<label>]... [--index <n>=<k>]... [--text <n>=<text>]... [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]...
 ```
 
 Subcommands:
 
 | Route | Summary |
 | --- | --- |
-| [`projmux agent question enable`](#projmux-agent-question-enable) | Opt one exact Claude Agent into answering its AskUserQuestion prompts from the command line |
-| [`projmux agent question disable`](#projmux-agent-question-disable) | Opt one exact Claude Agent out and hand its waiting questions back to its own prompt |
-| [`projmux agent question list`](#projmux-agent-question-list) | List one exact Claude Agent's waiting and recent questions |
+| [`projmux agent question enable`](#projmux-agent-question-enable) | Opt one exact Claude or Codex Agent into answering questions from the command line |
+| [`projmux agent question disable`](#projmux-agent-question-disable) | Opt one exact Claude or Codex Agent out of command-line answers |
+| [`projmux agent question list`](#projmux-agent-question-list) | List one exact Claude or Codex Agent's waiting and recent questions |
 | [`projmux agent question answer`](#projmux-agent-question-answer) | Answer one waiting question by option label, option number, or explicit free text |
 
 Canonical spelling: `projmux agent question enable`, `projmux agent question disable`, `projmux agent question list`, `projmux agent question answer`
 
 #### `projmux agent question enable`
 
-Opt one exact Claude Agent into answering its AskUserQuestion prompts from the command line
+Opt one exact Claude or Codex Agent into answering questions from the command line
 
 Selectorless authority: `explicit-target` — the route or caller must name the exact target.
 
@@ -706,12 +766,12 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux agent question enable <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]...
+projmux agent question enable <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]...
 ```
 
 #### `projmux agent question disable`
 
-Opt one exact Claude Agent out and hand its waiting questions back to its own prompt
+Opt one exact Claude or Codex Agent out of command-line answers
 
 Selectorless authority: `explicit-target` — the route or caller must name the exact target.
 
@@ -727,12 +787,12 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux agent question disable <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]...
+projmux agent question disable <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]...
 ```
 
 #### `projmux agent question list`
 
-List one exact Claude Agent's waiting and recent questions
+List one exact Claude or Codex Agent's waiting and recent questions
 
 Selectorless authority: `explicit-target` — the route or caller must name the exact target.
 
@@ -748,7 +808,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux agent question list <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [-o json]
+projmux agent question list <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]... [-o json]
 ```
 
 Output modes (`-o`): `json`
@@ -771,9 +831,136 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux agent question answer <agent-ref> <question-id> [--option <n>=<label>]... [--index <n>=<k>]... [--text <n>=<text>]... [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]...
+projmux agent question answer <agent-ref> <question-id> [--option <n>=<label>]... [--index <n>=<k>]... [--text <n>=<text>]... [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]...
+```
+
+### `projmux agent sessions`
+
+List the Claude or Codex conversations an Agent or a Project has moved through, backfill past Claude sessions from delivered message frames, or persist their current Registry affiliation
+
+Selectorless authority: `explicit-target` — the route or caller must name the exact target.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=exact-one`
+- `domain-effect=null`
+
+```
+projmux agent sessions list <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]... [-o json]
+projmux agent sessions backfill [--dry-run] [-o json]
+projmux agent sessions project <project-ref> [-o json]
+projmux agent sessions attribute [--dry-run] [-o json]
+```
+
+Subcommands:
+
+| Route | Summary |
+| --- | --- |
+| [`projmux agent sessions list`](#projmux-agent-sessions-list) | List one exact Claude or Codex Agent's recorded and current conversations in time order |
+| [`projmux agent sessions backfill`](#projmux-agent-sessions-backfill) | Append past Claude sessions attributable to exactly one Agent by their delivered message frames as estimated history |
+| [`projmux agent sessions project`](#projmux-agent-sessions-project) | List the Claude and Codex conversations attributed to one exact Project, by recorded affiliation or the current Registry |
+| [`projmux agent sessions attribute`](#projmux-agent-sessions-attribute) | Append the current Registry affiliation of Claude and Codex sessions whose history rows carry no Project, so they stay attributed after their Agent is deleted |
+
+Canonical spelling: `projmux agent sessions list`, `projmux agent sessions backfill`, `projmux agent sessions project`, `projmux agent sessions attribute`
+
+#### `projmux agent sessions list`
+
+List one exact Claude or Codex Agent's recorded and current conversations in time order
+
+Selectorless authority: `explicit-target` — the route or caller must name the exact target.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=exact-one`
+- `domain-effect=null`
+
+```
+projmux agent sessions list <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]... [-o json]
+```
+
+Output modes (`-o`): `json`
+
+#### `projmux agent sessions backfill`
+
+Append past Claude sessions attributable to exactly one Agent by their delivered message frames as estimated history
+
+Selectorless authority: `explicit-target` — the route or caller must name the exact target.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=unchanged`
+- `domain-effect=null`
+
+```
+projmux agent sessions backfill [--dry-run] [-o json]
+```
+
+Output modes (`-o`): `json`
+
+#### `projmux agent sessions project`
+
+List the Claude and Codex conversations attributed to one exact Project, by recorded affiliation or the current Registry
+
+Selectorless authority: `explicit-target` — the route or caller must name the exact target.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=exact-one`
+- `domain-effect=null`
+
+```
+projmux agent sessions project <project-ref> [-o json]
 ```
 
+Output modes (`-o`): `json`
+
+#### `projmux agent sessions attribute`
+
+Append the current Registry affiliation of Claude and Codex sessions whose history rows carry no Project, so they stay attributed after their Agent is deleted
+
+Selectorless authority: `explicit-target` — the route or caller must name the exact target.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=unchanged`
+- `domain-effect=null`
+
+```
+projmux agent sessions attribute [--dry-run] [-o json]
+```
+
+Output modes (`-o`): `json`
+
 ## `projmux attention`
 
 View and manage live tmux pane attention state
@@ -792,7 +979,11 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux attention toggle|clear|arm|list|window
+projmux attention toggle [pane]
+projmux attention clear [pane]
+projmux attention arm [pane]
+projmux attention list [--json] [--all]
+projmux attention window [window] [style]
 ```
 
 Subcommands:
@@ -888,7 +1079,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux attention list
+projmux attention list [--json] [--all]
 ```
 
 ### `projmux attention window`
@@ -909,7 +1100,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux attention window
+projmux attention window [window] [style]
 ```
 
 ## `projmux attach`
@@ -964,7 +1155,7 @@ projmux attach project <ref>
 
 ## `projmux config`
 
-Edit AI split-mode and enabled-provider settings; render or apply generated tmux configuration
+Edit AI split-mode, enabled-provider, locale, and agent-question settings; render or apply generated tmux configuration
 
 Selectorless authority: `refusal` — there is no safe selectorless action; refuse before output or mutation.
 
@@ -982,8 +1173,11 @@ Allowed effects:
 ```
 projmux config edit [--get|--set <mode>]
 projmux config providers [--enable <id>|--disable <id>]
+projmux config locale [--set <value>]
+projmux config agent-questions [--answering <claude|projmux>] [--window <seconds|unlimited>]
+projmux config agent-approvals [--answering <claude|projmux>] [--window <seconds>]
 projmux config render standalone|app [--bin <path>]
-projmux config apply [--bin <path>] [--config <path>] [--socket <name>]
+projmux config apply [--bin <path>] [--config <path>] [--socket <name>] [--no-reload]
 ```
 
 Subcommands:
@@ -992,10 +1186,13 @@ Subcommands:
 | --- | --- |
 | [`projmux config edit`](#projmux-config-edit) | Edit the AI split-mode configuration |
 | [`projmux config providers`](#projmux-config-providers) | List AI providers as enabled or disabled; --enable or --disable changes one |
+| [`projmux config locale`](#projmux-config-locale) | Show the [ui] locale setting and its config.toml; --set stores a new one |
+| [`projmux config agent-questions`](#projmux-config-agent-questions) | Show how Claude and Codex agent questions are answered and how long they wait; --answering or --window changes them |
+| [`projmux config agent-approvals`](#projmux-config-agent-approvals) | Show how agent permission requests are answered and how long a captured one waits; --answering or --window changes them |
 | [`projmux config render`](#projmux-config-render) | Print a generated tmux config to stdout; writes nothing |
 | [`projmux config apply`](#projmux-config-apply) | Write the generated app tmux config and reload the live projmux server |
 
-Canonical spelling: `projmux config edit`, `projmux config providers`, `projmux config render`, `projmux config apply`
+Canonical spelling: `projmux config edit`, `projmux config providers`, `projmux config locale`, `projmux config agent-questions`, `projmux config agent-approvals`, `projmux config render`, `projmux config apply`
 
 ### `projmux config edit`
 
@@ -1018,6 +1215,8 @@ Allowed effects:
 projmux config edit [--get|--set <mode>]
 ```
 
+`--get` prints the TUI split default `tmux-ai-split-mode` when it holds a valid mode, else the central `ai-new-window-mode`, else `selective`. `--set` writes only `tmux-ai-split-mode`.
+
 ### `projmux config providers`
 
 List AI providers as enabled or disabled; --enable or --disable changes one
@@ -1041,6 +1240,78 @@ projmux config providers --enable <id>
 projmux config providers --disable <id>
 ```
 
+### `projmux config locale`
+
+Show the [ui] locale setting and its config.toml; --set stores a new one
+
+Selectorless authority: `natural-omitted` — omission resolves one predictable current resource or documented contextual read/scope; any selector replaces it.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=unchanged`
+- `domain-effect=null`
+
+```
+projmux config locale
+projmux config locale --set <value>
+```
+
+### `projmux config agent-questions`
+
+Show how Claude and Codex agent questions are answered and how long they wait; --answering or --window changes them
+
+Selectorless authority: `natural-omitted` — omission resolves one predictable current resource or documented contextual read/scope; any selector replaces it.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=unchanged`
+- `domain-effect=null`
+
+```
+projmux config agent-questions
+projmux config agent-questions --answering <claude|projmux>
+projmux config agent-questions --window <seconds|unlimited>
+```
+
+### `projmux config agent-approvals`
+
+Show how agent permission requests are answered and how long a captured one waits; --answering or --window changes them
+
+Selectorless authority: `natural-omitted` — omission resolves one predictable current resource or documented contextual read/scope; any selector replaces it.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=unchanged`
+- `domain-effect=null`
+
+```
+projmux config agent-approvals [--answering <claude|projmux>] [--window <seconds>]
+```
+
+`claude` (default) leaves every Claude request to Claude Code's own prompt and refuses `agent approval answer`. `projmux` also captures Claude permission requests and lets `agent approval answer` allow or deny Claude and Codex requests remotely; the provider's own prompt stays usable and the first answer wins.
+
+Codex approvals are never captured: the provider holds them, `agent approval list` shows them in either way, and `agent approval review` answers them in either way.
+
+--window is 60..3600 seconds (default 900); there is no unlimited value. An unanswered request expires with no decision.
+
 ### `projmux config render`
 
 Print a generated tmux config to stdout; writes nothing
@@ -1134,7 +1405,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux config apply [--bin <path>] [--config <path>] [--socket <name>]
+projmux config apply [--bin <path>] [--config <path>] [--socket <name>] [--no-reload]
 ```
 
 ## `projmux create`
@@ -1156,12 +1427,13 @@ Allowed effects:
 
 ```
 projmux create project --root <absolute-path> [--name <name>] [--label key=value]... [-o <mode>]
-projmux create window [--project <ref> | -p <ref>] [--provider shell|<provider>] [--name <name>] [--label key=value]... [-o <mode>] [-- <payload>]
-projmux create pane [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--pane <ref>]... [--create-window] [--all-windows | --primary-window] [--placement right|down] [--cwd-from project|pane] [-o <mode>] [-- <payload>]
-projmux create agent --provider <provider> [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--interactive-only] [--model <model>] [--effort <level>] [--persona <name>] [--window <ref> | -w <ref>]... [--pane <ref>]... [--create-window] [--all-windows | --primary-window] [--placement right|down] [--cwd-from project|pane] [-o <mode>] [-- <payload>]
-projmux create codex [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--interactive-only] [--persona <name>] [--window <ref> | -w <ref>]... [--create-window] [--all-windows | --primary-window] [--placement right|down] [--cwd-from project|pane] [-o <mode>] [-- <payload>]
-projmux create claude|antigravity [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--window <ref> | -w <ref>]... [--create-window] [--all-windows | --primary-window] [--placement right|down] [--cwd-from project|pane] [-o <mode>] [-- <payload>]
-projmux create notification --text <s> --target <SESSION[:WINDOW[.PANE]]> [--socket <s>]
+projmux create window [--project <ref> | -p <ref>] [--provider shell|<provider>] [--creator uid:<agent>] [--name <name>] [--label key=value]... [-o <mode>] [-- <payload>]
+projmux create pane [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--all-windows | --primary-window] [--name <name>] [--label key=value]... [--placement right|down] [--cwd-from project|pane] [-o <mode>] [-- <payload>]
+projmux create agent [--provider <provider>] [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--interactive-only] [--model <model>] [--effort <level>] [--instructions <name>] [--profile <name>] [--dialogue-reply-only] [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--all-windows | --primary-window] [--creator uid:<agent>] [--name <name>] [--label key=value]... [--placement right|down] [--cwd-from project|pane] [-o <mode>] [-- <payload>]
+projmux create codex [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--interactive-only] [--model <model>] [--effort <level>] [--instructions <name>] [--profile <name>] [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--all-windows | --primary-window] [--creator uid:<agent>] [--name <name>] [--label key=value]... [--placement right|down] [--cwd-from project|pane] [-o <mode>] [-- <payload>]
+projmux create claude [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--model <model>] [--effort <level>] [--instructions <name>] [--profile <name>] [--dialogue-reply-only] [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--all-windows | --primary-window] [--creator uid:<agent>] [--name <name>] [--label key=value]... [--placement right|down] [--cwd-from project|pane] [-o <mode>] [-- <payload>]
+projmux create antigravity [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--profile <name>] [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--all-windows | --primary-window] [--creator uid:<agent>] [--name <name>] [--label key=value]... [--placement right|down] [--cwd-from project|pane] [-o <mode>] [-- <payload>]
+projmux create notification --text <s> --target <SESSION[:WINDOW[.PANE]]> [--socket <s>] [--severity info|warn|critical] [--source <source>] [--ttl <seconds>] [--id <id>] [--json]
 ```
 
 Subcommands:
@@ -1171,7 +1443,7 @@ Subcommands:
 | [`projmux create project`](#projmux-create-project) | Register one exact filesystem path as a Registry Project; no runtime is materialized |
 | [`projmux create window`](#projmux-create-window) | Create a Window below one Project, opening on a shell Pane or on one Agent; the runtime is materialized detached |
 | [`projmux create pane`](#projmux-create-pane) | Create a shell Pane detached on an explicit Pane or the Window's exact shell or Agent anchor |
-| [`projmux create agent`](#projmux-create-agent) | Create an Agent detached on an explicit Pane or the Window's exact shell or Agent anchor; --provider is required |
+| [`projmux create agent`](#projmux-create-agent) | Create an Agent detached on an explicit Pane or the Window's exact shell or Agent anchor; --provider or the selected profile names the provider |
 | [`projmux create notification`](#projmux-create-notification) | Create a pending notification row |
 
 Provider shortcuts:
@@ -1229,9 +1501,11 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux create window [--project <ref> | -p <ref>] [--provider shell|<provider>] [--name <name>] [--label key=value]... [-o <mode>] [-- <payload>]
+projmux create window [--project <ref> | -p <ref>] [--provider shell|<provider>] [--creator uid:<agent>] [--name <name>] [--label key=value]... [-o <mode>] [-- <payload>]
 ```
 
+`--creator uid:<agent>` declares the Agent that created this one. It is recorded as `projmux.io/creator-basis=explicit` with `projmux.io/creator-agent` only when no pane chain is observed; an observed pane chain always wins, and a different declaration is reported on stderr. A value that names no Agent refuses the create before anything changes. The record is provenance, never authentication.
+
 Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `pane-id`, `none`, `receipt`
 
 ### `projmux create pane`
@@ -1259,7 +1533,7 @@ Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `pane-id`, `none`
 
 ### `projmux create agent`
 
-Create an Agent detached on an explicit Pane or the Window's exact shell or Agent anchor; --provider is required
+Create an Agent detached on an explicit Pane or the Window's exact shell or Agent anchor; --provider or the selected profile names the provider
 
 Selectorless authority: `natural-omitted` — omission resolves one predictable current resource or documented contextual read/scope; any selector replaces it.
 
@@ -1275,9 +1549,17 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux create agent --provider <provider> [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--interactive-only] [--model <model>] [--effort <level>] [--persona <name>] [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--all-windows | --primary-window] [--name <name>] [--label key=value]... [--placement right|down] [--cwd-from project|pane] [-o <mode>] [-- <payload>]
+projmux create agent [--provider <provider>] [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--interactive-only] [--model <model>] [--effort <level>] [--instructions <name>] [--profile <name>] [--dialogue-reply-only] [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--all-windows | --primary-window] [--creator uid:<agent>] [--name <name>] [--label key=value]... [--placement right|down] [--cwd-from project|pane] [-o <mode>] [-- <payload>]
 ```
 
+An explicit `--provider` wins, and a profile that names another provider is refused. Without `--provider`, the provider is the one named by the profile that `--profile <name>` or a `role` creation label selects.
+
+When neither decides it -- no profile, `--profile none`, or a profile without `provider` -- the create is refused as requiring `--provider`.
+
+Codex applies --instructions only when a new Agent starts with a prompt through its native thread. A promptless or --interactive-only Codex create with instructions is refused before creation.
+
+`--creator uid:<agent>` declares the Agent that created this one. It is recorded as `projmux.io/creator-basis=explicit` with `projmux.io/creator-agent` only when no pane chain is observed; an observed pane chain always wins, and a different declaration is reported on stderr. A value that names no Agent refuses the create before anything changes. The record is provenance, never authentication.
+
 Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `pane-id`, `none`, `receipt`
 
 ### `projmux create notification`
@@ -1298,7 +1580,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux create notification --text <s> --target <SESSION[:WINDOW[.PANE]]> [--socket <s>]
+projmux create notification --text <s> --target <SESSION[:WINDOW[.PANE]]> [--socket <s>] [--severity info|warn|critical] [--source <source>] [--ttl <seconds>] [--id <id>] [--json]
 ```
 
 ### `projmux create codex`
@@ -1319,9 +1601,13 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux create codex [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--interactive-only] [--persona <name>] [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--all-windows | --primary-window] [--name <name>] [--label key=value]... [--placement right|down] [--cwd-from project|pane] [-o <mode>] [-- <payload>]
+projmux create codex [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--interactive-only] [--model <model>] [--effort <level>] [--instructions <name>] [--profile <name>] [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--all-windows | --primary-window] [--creator uid:<agent>] [--name <name>] [--label key=value]... [--placement right|down] [--cwd-from project|pane] [-o <mode>] [-- <payload>]
 ```
 
+Profile sandbox and approval apply on native and plain CLI creates. A plain CLI create with approval=untrusted is refused before creating an Agent.
+
+Instructions from --instructions or a Profile apply when the create includes a prompt and opens a native thread. Promptless and --interactive-only creates with instructions are refused.
+
 Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `pane-id`, `none`, `receipt`
 
 ### `projmux create claude`
@@ -1342,7 +1628,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux create claude [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--model <model>] [--effort <level>] [--persona <name>] [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--all-windows | --primary-window] [--name <name>] [--label key=value]... [--placement right|down] [--cwd-from project|pane] [-o <mode>] [-- <payload>]
+projmux create claude [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--model <model>] [--effort <level>] [--instructions <name>] [--profile <name>] [--dialogue-reply-only] [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--all-windows | --primary-window] [--creator uid:<agent>] [--name <name>] [--label key=value]... [--placement right|down] [--cwd-from project|pane] [-o <mode>] [-- <payload>]
 ```
 
 Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `pane-id`, `none`, `receipt`
@@ -1365,7 +1651,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux create antigravity [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--all-windows | --primary-window] [--name <name>] [--label key=value]... [--placement right|down] [--cwd-from project|pane] [-o <mode>] [-- <payload>]
+projmux create antigravity [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--profile <name>] [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--all-windows | --primary-window] [--creator uid:<agent>] [--name <name>] [--label key=value]... [--placement right|down] [--cwd-from project|pane] [-o <mode>] [-- <payload>]
 ```
 
 Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `pane-id`, `none`, `receipt`
@@ -1388,10 +1674,11 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux delete project [<ref>...] [--selector key=value]... [--all] [--dry-run] [--yes]
-projmux delete window [<ref>...] [--project <ref> | -p <ref>] [--selector key=value]... [--all] [--socket <name> | --socket-path <absolute>] [--dry-run] [--yes]
-projmux delete pane [<ref>...] [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--all] [--socket <name> | --socket-path <absolute>] [--dry-run] [--yes]
-projmux delete agent [<ref>...] [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--all] [--socket <name> | --socket-path <absolute>] [--dry-run] [--yes]
+projmux delete project [<ref>...] [--project <ref> | -p <ref>] [--selector key=value]... [--all] [--socket <name> | --socket-path <absolute>] [--dry-run] [--yes]
+projmux delete window [<ref>...] [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]... [--all] [--socket <name> | --socket-path <absolute>] [--dry-run] [--yes]
+projmux delete pane [<ref>...] [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [--all] [--socket <name> | --socket-path <absolute>] [--dry-run] [--yes]
+projmux delete agent [<ref>...] [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]... [--all] [--socket <name> | --socket-path <absolute>] [--dry-run] [--yes]
+projmux delete notification <id> | --all
 ```
 
 Subcommands:
@@ -1424,7 +1711,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux delete project [<ref>...] [--selector key=value]... [--all] [--dry-run] [--yes]
+projmux delete project [<ref>...] [--project <ref> | -p <ref>] [--selector key=value]... [--all] [--socket <name> | --socket-path <absolute>] [--dry-run] [--yes]
 ```
 
 Aliases: `projects`
@@ -1449,7 +1736,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux delete window [<ref>...] [--project <ref> | -p <ref>] [--selector key=value]... [--all] [--socket <name> | --socket-path <absolute>] [--dry-run] [--yes]
+projmux delete window [<ref>...] [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]... [--all] [--socket <name> | --socket-path <absolute>] [--dry-run] [--yes]
 ```
 
 Aliases: `windows`
@@ -1472,11 +1759,13 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux delete pane [<ref>...] [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--all] [--socket <name> | --socket-path <absolute>] [--dry-run] [--yes]
+projmux delete pane [<ref>...] [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [--all] [--socket <name> | --socket-path <absolute>] [--dry-run] [--yes]
 ```
 
 Aliases: `panes`
 
+A selector that resolves to exactly one Pane deletes it without confirmation. No selector (the active Pane), --all, or several Panes need --yes, or a yes at the terminal prompt; without a terminal the delete is refused with exit 2. --dry-run only prints the plan.
+
 ### `projmux delete agent`
 
 Delete Agents and their managed Panes; no selector inside tmux means the active Agent, and --all means every Agent in the registry
@@ -1495,7 +1784,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux delete agent [<ref>...] [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--all] [--socket <name> | --socket-path <absolute>] [--dry-run] [--yes]
+projmux delete agent [<ref>...] [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]... [--all] [--socket <name> | --socket-path <absolute>] [--dry-run] [--yes]
 ```
 
 Aliases: `agents`
@@ -1518,7 +1807,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux delete notification
+projmux delete notification <id> | --all
 ```
 
 Aliases: `notifications`
@@ -1541,10 +1830,10 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux describe project [<ref>] [--project <ref> | -p <ref>] [-o <mode>]
-projmux describe window [<ref>] [--project <ref> | -p <ref>] [-o <mode>]
-projmux describe pane [<ref>] [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [-o <mode>]
-projmux describe agent [<ref>] [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [-o <mode>]
+projmux describe project [<ref>] [--project <ref> | -p <ref>] [--selector key=value]... [-o <mode>]
+projmux describe window [<ref>] [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]... [-o <mode>]
+projmux describe pane [<ref>] [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [-o <mode>]
+projmux describe agent [<ref>] [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]... [-o <mode>]
 ```
 
 Subcommands:
@@ -1576,7 +1865,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux describe project [<ref>] [--project <ref> | -p <ref>] [-o <mode>]
+projmux describe project [<ref>] [--project <ref> | -p <ref>] [--selector key=value]... [-o <mode>]
 ```
 
 Aliases: `projects`
@@ -1601,7 +1890,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux describe window [<ref>] [--project <ref> | -p <ref>] [-o <mode>]
+projmux describe window [<ref>] [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]... [-o <mode>]
 ```
 
 Aliases: `windows`
@@ -1626,7 +1915,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux describe pane [<ref>] [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [-o <mode>]
+projmux describe pane [<ref>] [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [-o <mode>]
 ```
 
 Aliases: `panes`
@@ -1651,7 +1940,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux describe agent [<ref>] [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [-o <mode>]
+projmux describe agent [<ref>] [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]... [-o <mode>]
 ```
 
 Aliases: `agents`
@@ -1697,7 +1986,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux diagnostics log [--json] [--tail <n>]
+projmux diagnostics log [--json] [--tail <n>] [--level info|warn|error] [--component <name>] [--path]
 projmux diagnostics agent-hook [--tail <n>] [--json] [--path]
 projmux diagnostics report [--output <path>]
 ```
@@ -1730,7 +2019,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux diagnostics log
+projmux diagnostics log [--json] [--tail <n>] [--level info|warn|error] [--component <name>] [--path]
 ```
 
 ### `projmux diagnostics agent-hook`
@@ -1772,7 +2061,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux diagnostics report
+projmux diagnostics report [--output <path>]
 ```
 
 ## `projmux focus`
@@ -1793,11 +2082,11 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux focus project <ref>
-projmux focus window <ref> {--project <ref> | -p <ref>}
-projmux focus window uid:<uid> [--project <ref> | -p <ref>]
-projmux focus pane <ref> {--project <ref> | -p <ref>} {--window <ref> | -w <ref>}
-projmux focus pane uid:<uid> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]
+projmux focus project <ref> [--socket <path>] [--client <tty>] [--source <source>] [--kind <kind>] [--json]
+projmux focus window <ref> {--project <ref> | -p <ref>} [--socket <path>] [--client <tty>] [--source <source>] [--kind <kind>] [--json]
+projmux focus window uid:<uid> [--project <ref> | -p <ref>] [--socket <path>] [--client <tty>] [--source <source>] [--kind <kind>] [--json]
+projmux focus pane <ref> {--project <ref> | -p <ref>} {--window <ref> | -w <ref>} [--socket <path>] [--client <tty>] [--source <source>] [--kind <kind>] [--json]
+projmux focus pane uid:<uid> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>] [--socket <path>] [--client <tty>] [--source <source>] [--kind <kind>] [--json]
 ```
 
 Subcommands:
@@ -1828,7 +2117,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux focus project <ref> [--socket <path>] [--client <tty>] [--json]
+projmux focus project <ref> [--socket <path>] [--client <tty>] [--source <source>] [--kind <kind>] [--json]
 ```
 
 `<ref>` is the live tmux session name, or `uid:<uid>` for a Registry Project, which resolves to its `status.session.name`. A `uid:` ref uses the Project's recorded socket; an explicit `--socket` naming another server exits 2. The resolved session must still be live.
@@ -1851,8 +2140,8 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux focus window <ref> {--project <ref> | -p <ref>} [--socket <path>] [--client <tty>] [--json]
-projmux focus window uid:<uid> [--project <ref> | -p <ref>] [--socket <path>] [--client <tty>] [--json]
+projmux focus window <ref> {--project <ref> | -p <ref>} [--socket <path>] [--client <tty>] [--source <source>] [--kind <kind>] [--json]
+projmux focus window uid:<uid> [--project <ref> | -p <ref>] [--socket <path>] [--client <tty>] [--source <source>] [--kind <kind>] [--json]
 ```
 
 A plain `<ref>` is a live window name or `@id` and requires `--project`. `uid:<uid>` names a Registry Window, which resolves to its `status.runtimeID` inside its owning Project's session, so `--project` is optional; when given it must be that Project (`uid:` or its session name) or the route exits 2. `--project uid:<uid>` also works with a plain `<ref>`.
@@ -1877,8 +2166,8 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux focus pane <ref> {--project <ref> | -p <ref>} {--window <ref> | -w <ref>} [--socket <path>] [--json]
-projmux focus pane uid:<uid> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>] [--socket <path>] [--json]
+projmux focus pane <ref> {--project <ref> | -p <ref>} {--window <ref> | -w <ref>} [--socket <path>] [--client <tty>] [--source <source>] [--kind <kind>] [--json]
+projmux focus pane uid:<uid> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>] [--socket <path>] [--client <tty>] [--source <source>] [--kind <kind>] [--json]
 ```
 
 A plain `<ref>` is a live pane name or `%id` and requires `--project` and `--window`. `uid:<uid>` names a Registry Pane, which resolves to its `status.activation.runtimeID` inside its owning Window and Project, so both flags are optional; when given they must match that owner chain or the route exits 2. `--project` and `--window` also accept `uid:<uid>` with a plain `<ref>`.
@@ -1908,8 +2197,9 @@ projmux get windows [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]...
 projmux get panes [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [--all-projects | -A] [-o <mode>]
 projmux get agents [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]... [--all-projects | -A] [-o <mode>]
 projmux get pane --current -o cwd
-projmux get pane [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [-o <mode>]
+projmux get pane [--current] [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [-o <mode>]
 projmux get runtime sessions|windows|panes [--socket <name> | --socket-path <absolute>] [-o wide|json|none]
+projmux get notifications [--json] [--live] [--limit <n>] [--ui table|sidebar] [--client <tty>] [--severity <severity>]... [--source <source>]...
 ```
 
 Subcommands:
@@ -2144,7 +2434,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux get notifications
+projmux get notifications [--json] [--live] [--limit <n>] [--ui table|sidebar] [--client <tty>] [--severity <severity>]... [--source <source>]...
 ```
 
 Aliases: `notification`
@@ -2192,9 +2482,16 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux hook list|edit|validate|trust|untrust
+projmux hook list [--global | --project | --effective]
+projmux hook edit [--global | --project] [--editor] <event>
+projmux hook validate
+projmux hook trust [<project>]
+projmux hook untrust [<project>]
 ```
 
+Events:
+  post-attach, post-create, pre-create, send-noti
+
 Subcommands:
 
 | Route | Summary |
@@ -2225,7 +2522,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux hook list
+projmux hook list [--global | --project | --effective]
 ```
 
 ### `projmux hook edit`
@@ -2246,7 +2543,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux hook edit
+projmux hook edit [--global | --project] [--editor] <event>
 ```
 
 ### `projmux hook validate`
@@ -2288,7 +2585,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux hook trust
+projmux hook trust [<project>]
 ```
 
 ### `projmux hook untrust`
@@ -2309,7 +2606,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux hook untrust
+projmux hook untrust [<project>]
 ```
 
 ## `projmux label`
@@ -2330,10 +2627,10 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux label project [<ref>] <key=value|key->... [--project <ref> | -p <ref>]
-projmux label window [<ref>] <key=value|key->... [--project <ref> | -p <ref>]
-projmux label pane [<ref>] <key=value|key->... [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]...
-projmux label agent [<ref>] <key=value|key->... [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]...
+projmux label project [<ref>] <key=value|key->... [--project <ref> | -p <ref>] [--selector key=value]...
+projmux label window [<ref>] <key=value|key->... [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]...
+projmux label pane [<ref>] <key=value|key->... [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]...
+projmux label agent [<ref>] <key=value|key->... [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]...
 ```
 
 Subcommands:
@@ -2365,7 +2662,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux label project [<ref>] <key=value|key->... [--project <ref> | -p <ref>]
+projmux label project [<ref>] <key=value|key->... [--project <ref> | -p <ref>] [--selector key=value]...
 ```
 
 Aliases: `projects`
@@ -2388,7 +2685,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux label window [<ref>] <key=value|key->... [--project <ref> | -p <ref>]
+projmux label window [<ref>] <key=value|key->... [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]...
 ```
 
 Aliases: `windows`
@@ -2411,7 +2708,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux label pane [<ref>] <key=value|key->... [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]...
+projmux label pane [<ref>] <key=value|key->... [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]...
 ```
 
 Aliases: `panes`
@@ -2434,7 +2731,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux label agent [<ref>] <key=value|key->... [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]...
+projmux label agent [<ref>] <key=value|key->... [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]...
 ```
 
 Aliases: `agents`
@@ -2564,9 +2861,9 @@ projmux open project <ref> [-o receipt|none]
 
 Output modes (`-o`): `receipt`, `none`
 
-## `projmux persona`
+## `projmux instructions`
 
-List, show, edit, set, and delete Agent persona files
+List, show, edit, set, and delete Agent instruction files
 
 Selectorless authority: `refusal` — there is no safe selectorless action; refuse before output or mutation.
 
@@ -2582,28 +2879,28 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux persona list
-projmux persona show <name>
-projmux persona edit <name>
-projmux persona set <name> [--file <path> | -]
-projmux persona delete <name> --yes
+projmux instructions list
+projmux instructions show <name>
+projmux instructions edit <name>
+projmux instructions set <name> [--file <path> | -]
+projmux instructions delete <name> --yes
 ```
 
 Subcommands:
 
 | Route | Summary |
 | --- | --- |
-| [`projmux persona list`](#projmux-persona-list) | List every stored persona with its digest, size, and modification time |
-| [`projmux persona show`](#projmux-persona-show) | Print one persona's content exactly as stored |
-| [`projmux persona edit`](#projmux-persona-edit) | Edit one persona in $EDITOR or $VISUAL, creating it when missing |
-| [`projmux persona set`](#projmux-persona-set) | Write one persona from a file or stdin without an editor |
-| [`projmux persona delete`](#projmux-persona-delete) | Delete one persona file; Agents already started with it keep their snapshot |
+| [`projmux instructions list`](#projmux-instructions-list) | List every stored instructions with their digest, size, and modification time |
+| [`projmux instructions show`](#projmux-instructions-show) | Print one instruction's content exactly as stored |
+| [`projmux instructions edit`](#projmux-instructions-edit) | Edit one instruction in $EDITOR or $VISUAL, creating it when missing |
+| [`projmux instructions set`](#projmux-instructions-set) | Write one instruction from a file or stdin without an editor |
+| [`projmux instructions delete`](#projmux-instructions-delete) | Delete one instruction file no profile names; Agents already started with it keep their snapshot |
 
-Canonical spelling: `projmux persona list`, `projmux persona show`, `projmux persona edit`, `projmux persona set`, `projmux persona delete`
+Canonical spelling: `projmux instructions list`, `projmux instructions show`, `projmux instructions edit`, `projmux instructions set`, `projmux instructions delete`
 
-### `projmux persona list`
+### `projmux instructions list`
 
-List every stored persona with its digest, size, and modification time
+List every stored instructions with their digest, size, and modification time
 
 Selectorless authority: `explicit-fan-out` — the route spelling is an intentional global or whole-set opt-in.
 
@@ -2619,12 +2916,12 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux persona list
+projmux instructions list
 ```
 
-### `projmux persona show`
+### `projmux instructions show`
 
-Print one persona's content exactly as stored
+Print one instruction's content exactly as stored
 
 Selectorless authority: `explicit-target` — the route or caller must name the exact target.
 
@@ -2640,12 +2937,133 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux persona show <name>
+projmux instructions show <name>
+```
+
+### `projmux instructions edit`
+
+Edit one instruction in $EDITOR or $VISUAL, creating it when missing
+
+Selectorless authority: `explicit-target` — the route or caller must name the exact target.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=unchanged`
+- `domain-effect=null`
+
+```
+projmux instructions edit <name>
+```
+
+### `projmux instructions set`
+
+Write one instruction from a file or stdin without an editor
+
+Selectorless authority: `explicit-target` — the route or caller must name the exact target.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=unchanged`
+- `domain-effect=null`
+
+```
+projmux instructions set <name> [--file <path> | -]
+```
+
+### `projmux instructions delete`
+
+Delete one instruction file no profile names; Agents already started with it keep their snapshot
+
+Selectorless authority: `explicit-target` — the route or caller must name the exact target.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=unchanged`
+- `domain-effect=null`
+
+```
+projmux instructions delete <name> --yes
+```
+
+## `projmux profile`
+
+List, show, set, and delete named Agent profiles
+
+Selectorless authority: `refusal` — there is no safe selectorless action; refuse before output or mutation.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=unchanged`
+- `domain-effect=null`
+
+```
+projmux profile list
+projmux profile show <name>
+projmux profile set <name> [--file <path> | -]
+projmux profile delete <name> --yes
+```
+
+Codex applies Profile sandbox and approval on native and CLI lanes. Codex CLI accepts approval=on-request or never; approval=untrusted requires the native lane.
+
+Subcommands:
+
+| Route | Summary |
+| --- | --- |
+| [`projmux profile list`](#projmux-profile-list) | List every stored profile with its source, the provider, instructions, model, effort, and roles it names, its digest, and validity |
+| [`projmux profile show`](#projmux-profile-show) | Print one profile's content exactly as stored |
+| [`projmux profile set`](#projmux-profile-set) | Validate one profile from a file or stdin and write it only when valid |
+| [`projmux profile delete`](#projmux-profile-delete) | Delete one stored profile file |
+
+Canonical spelling: `projmux profile list`, `projmux profile show`, `projmux profile set`, `projmux profile delete`
+
+### `projmux profile list`
+
+List every stored profile with its source, the provider, instructions, model, effort, and roles it names, its digest, and validity
+
+Selectorless authority: `explicit-fan-out` — the route spelling is an intentional global or whole-set opt-in.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=unchanged`
+- `domain-effect=null`
+
+```
+projmux profile list
 ```
 
-### `projmux persona edit`
+### `projmux profile show`
 
-Edit one persona in $EDITOR or $VISUAL, creating it when missing
+Print one profile's content exactly as stored
 
 Selectorless authority: `explicit-target` — the route or caller must name the exact target.
 
@@ -2661,12 +3079,12 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux persona edit <name>
+projmux profile show <name>
 ```
 
-### `projmux persona set`
+### `projmux profile set`
 
-Write one persona from a file or stdin without an editor
+Validate one profile from a file or stdin and write it only when valid
 
 Selectorless authority: `explicit-target` — the route or caller must name the exact target.
 
@@ -2682,12 +3100,12 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux persona set <name> [--file <path> | -]
+projmux profile set <name> [--file <path> | -]
 ```
 
-### `projmux persona delete`
+### `projmux profile delete`
 
-Delete one persona file; Agents already started with it keep their snapshot
+Delete one stored profile file
 
 Selectorless authority: `explicit-target` — the route or caller must name the exact target.
 
@@ -2703,7 +3121,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux persona delete <name> --yes
+projmux profile delete <name> --yes
 ```
 
 ## `projmux pin`
@@ -2724,7 +3142,12 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux pin project list|add|remove|toggle|clear
+projmux pin project list [--kind project|candidate]
+projmux pin project add <dir|uid:uid>
+projmux pin project remove <dir|uid:uid>
+projmux pin project toggle <dir|uid:uid>
+projmux pin project clear
+projmux pin project migrate [--dry-run]
 ```
 
 Subcommands:
@@ -2753,7 +3176,155 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux pin project list|add|remove|toggle|clear
+projmux pin project list [--kind project|candidate]
+projmux pin project add <dir|uid:uid>
+projmux pin project remove <dir|uid:uid>
+projmux pin project toggle <dir|uid:uid>
+projmux pin project clear
+projmux pin project migrate [--dry-run]
+```
+
+Pins are presentation preferences in two kinds:
+  project    a Registry Project uid; its root and name are projected from the Registry
+  candidate  a filesystem path that no Registry Project claims
+
+Discovery roots (workdirs) are a separate collection; manage them in `projmux settings`.
+
+Subcommands:
+
+| Route | Summary |
+| --- | --- |
+| [`projmux pin project list`](#projmux-pin-project-list) | List every pin as a typed row, optionally limited to one pin kind |
+| [`projmux pin project add`](#projmux-pin-project-add) | Pin one project directory or Registry Project uid |
+| [`projmux pin project remove`](#projmux-pin-project-remove) | Unpin one project directory or Registry Project uid |
+| [`projmux pin project toggle`](#projmux-pin-project-toggle) | Pin or unpin one project directory or Registry Project uid |
+| [`projmux pin project clear`](#projmux-pin-project-clear) | Remove every pin |
+| [`projmux pin project migrate`](#projmux-pin-project-migrate) | Store the typed form of a legacy pin file, or report it with --dry-run |
+
+#### `projmux pin project list`
+
+List every pin as a typed row, optionally limited to one pin kind
+
+Selectorless authority: `explicit-fan-out` — the route spelling is an intentional global or whole-set opt-in.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=unchanged`
+- `domain-effect=null`
+
+```
+projmux pin project list [--kind project|candidate]
+```
+
+#### `projmux pin project add`
+
+Pin one project directory or Registry Project uid
+
+Selectorless authority: `explicit-target` — the route or caller must name the exact target.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=exact-one`
+- `domain-effect=null`
+
+```
+projmux pin project add <dir|uid:uid>
+```
+
+#### `projmux pin project remove`
+
+Unpin one project directory or Registry Project uid
+
+Selectorless authority: `explicit-target` — the route or caller must name the exact target.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=exact-one`
+- `domain-effect=null`
+
+```
+projmux pin project remove <dir|uid:uid>
+```
+
+#### `projmux pin project toggle`
+
+Pin or unpin one project directory or Registry Project uid
+
+Selectorless authority: `explicit-target` — the route or caller must name the exact target.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=exact-one`
+- `domain-effect=null`
+
+```
+projmux pin project toggle <dir|uid:uid>
+```
+
+#### `projmux pin project clear`
+
+Remove every pin
+
+Selectorless authority: `explicit-fan-out` — the route spelling is an intentional global or whole-set opt-in.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=zero-or-more`
+- `domain-effect=null`
+
+```
+projmux pin project clear
+```
+
+#### `projmux pin project migrate`
+
+Store the typed form of a legacy pin file, or report it with --dry-run
+
+Selectorless authority: `explicit-fan-out` — the route spelling is an intentional global or whole-set opt-in.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=zero-or-more`
+- `domain-effect=null`
+
+```
+projmux pin project migrate [--dry-run]
 ```
 
 ## `projmux prune`
@@ -2868,7 +3439,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux reconcile resources [--dry-run] [--materialize-project <name|uid:uid>] [--socket <name> | --socket-path <absolute>] [-o json]
+projmux reconcile resources [--dry-run] [--materialize-project <name|uid:uid>] [--import-orphan-mirrors] [--yes] [--socket <name> | --socket-path <absolute>] [-o json]
 projmux reconcile registry [--dry-run] [--source <name|absolute-path>] [--expect-source-checksum <sha256:hex>] [--expect-current-checksum <sha256:hex>] [--socket <name> | --socket-path <absolute>] [-o json]
 ```
 
@@ -2899,9 +3470,11 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux reconcile resources [--dry-run] [--materialize-project <name|uid:uid>] [--socket <name> | --socket-path <absolute>] [-o json]
+projmux reconcile resources [--dry-run] [--materialize-project <name|uid:uid>] [--import-orphan-mirrors] [--yes] [--socket <name> | --socket-path <absolute>] [-o json]
 ```
 
+Output modes (`-o`): `json`
+
 ### `projmux reconcile registry`
 
 Plan Registry state-loss recovery with zero writes, then restore one explicitly named verified source
@@ -2923,6 +3496,8 @@ Allowed effects:
 projmux reconcile registry [--dry-run] [--source <name|absolute-path>] [--expect-source-checksum <sha256:hex>] [--expect-current-checksum <sha256:hex>] [--socket <name> | --socket-path <absolute>] [-o json]
 ```
 
+Output modes (`-o`): `json`
+
 ## `projmux rebind`
 
 Rebind a Project to a new absolute root without moving files
@@ -2941,7 +3516,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux rebind project [<ref>] [--project <ref> | -p <ref>] --root <absolute-path>
+projmux rebind project [<ref>] [--project <ref> | -p <ref>] [--selector key=value]... --root <absolute-path>
 ```
 
 Subcommands:
@@ -2970,7 +3545,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux rebind project [<ref>] [--project <ref> | -p <ref>] --root <absolute-path>
+projmux rebind project [<ref>] [--project <ref> | -p <ref>] [--selector key=value]... --root <absolute-path>
 ```
 
 ## `projmux rename`
@@ -2991,10 +3566,10 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux rename project [<ref>] [--project <ref> | -p <ref>] --name <name>
-projmux rename window [<ref>] --name <name> [--project <ref> | -p <ref>]
-projmux rename pane [<ref>] --name <name> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]...
-projmux rename agent [<ref>] --name <name> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]...
+projmux rename project [<ref>] [--project <ref> | -p <ref>] [--selector key=value]... --name <name> [-o <mode>]
+projmux rename window [<ref>] --name <name> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]... [-o <mode>]
+projmux rename pane [<ref>] --name <name> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [-o <mode>]
+projmux rename agent [<ref>] --name <name> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]... [-o <mode>]
 ```
 
 Subcommands:
@@ -3026,7 +3601,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux rename project [<ref>] [--project <ref> | -p <ref>] --name <name>
+projmux rename project [<ref>] [--project <ref> | -p <ref>] [--selector key=value]... --name <name> [-o <mode>]
 ```
 
 Aliases: `projects`
@@ -3051,7 +3626,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux rename window [<ref>] --name <name> [--project <ref> | -p <ref>]
+projmux rename window [<ref>] --name <name> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]... [-o <mode>]
 ```
 
 Aliases: `windows`
@@ -3076,7 +3651,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux rename pane [<ref>] --name <name> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]...
+projmux rename pane [<ref>] --name <name> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [-o <mode>]
 ```
 
 Aliases: `panes`
@@ -3101,7 +3676,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux rename agent [<ref>] --name <name> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]...
+projmux rename agent [<ref>] --name <name> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]... [-o <mode>]
 ```
 
 Aliases: `agents`
@@ -3147,12 +3722,14 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux runtime sessions [--ui=popup|sidebar]
-projmux runtime diagnostics [--socket <name> | --socket-path <absolute>] [--ui=popup|sidebar]
-projmux runtime attach [--keep=N] [--fallback=home|ephemeral]
+projmux runtime sessions [--ui popup|sidebar]
+projmux runtime diagnostics [--socket <name> | --socket-path <absolute>] [--ui popup|sidebar]
+projmux runtime attach [--keep <n>] [--fallback home|ephemeral]
 projmux runtime stop [<session>...]
-projmux runtime tag list|toggle|clear
-projmux runtime prune [--keep=N]
+projmux runtime tag list
+projmux runtime tag clear
+projmux runtime tag toggle <name>
+projmux runtime prune [--keep <n>]
 ```
 
 Subcommands:
@@ -3186,7 +3763,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux runtime sessions
+projmux runtime sessions [--ui popup|sidebar]
 ```
 
 ### `projmux runtime diagnostics`
@@ -3207,7 +3784,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux runtime diagnostics [--socket <name> | --socket-path <absolute>] [--ui=popup|sidebar]
+projmux runtime diagnostics [--socket <name> | --socket-path <absolute>] [--ui popup|sidebar]
 ```
 
 ### `projmux runtime attach`
@@ -3228,7 +3805,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux runtime attach
+projmux runtime attach [--keep <n>] [--fallback home|ephemeral]
 ```
 
 ### `projmux runtime stop`
@@ -3249,7 +3826,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux runtime stop
+projmux runtime stop [<session>...]
 ```
 
 ### `projmux runtime tag`
@@ -3270,7 +3847,80 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux runtime tag
+projmux runtime tag list
+projmux runtime tag clear
+projmux runtime tag toggle <name>
+```
+
+Subcommands:
+
+| Route | Summary |
+| --- | --- |
+| [`projmux runtime tag list`](#projmux-runtime-tag-list) | Print the tagged session names, one per line |
+| [`projmux runtime tag clear`](#projmux-runtime-tag-clear) | Clear the whole tagged session selection |
+| [`projmux runtime tag toggle`](#projmux-runtime-tag-toggle) | Tag or untag one tmux session name |
+
+#### `projmux runtime tag list`
+
+Print the tagged session names, one per line
+
+Selectorless authority: `explicit-fan-out` — the route spelling is an intentional global or whole-set opt-in.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=unchanged`
+- `domain-effect=null`
+
+```
+projmux runtime tag list
+```
+
+#### `projmux runtime tag clear`
+
+Clear the whole tagged session selection
+
+Selectorless authority: `explicit-fan-out` — the route spelling is an intentional global or whole-set opt-in.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=zero-or-more`
+- `domain-effect=null`
+
+```
+projmux runtime tag clear
+```
+
+#### `projmux runtime tag toggle`
+
+Tag or untag one tmux session name
+
+Selectorless authority: `explicit-target` — the route or caller must name the exact target.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=exact-one`
+- `domain-effect=null`
+
+```
+projmux runtime tag toggle <name>
 ```
 
 ### `projmux runtime prune`
@@ -3291,7 +3941,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux runtime prune
+projmux runtime prune [--keep <n>]
 ```
 
 ## `projmux settings`
@@ -3333,8 +3983,8 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux setup
-projmux setup terminal [terminal] [--apply]
+projmux setup [--timeout <duration>] [--non-interactive]
+projmux setup terminal [terminal] [--apply] [--config <path>] [--allow-symlink]
 ```
 
 Subcommands:
@@ -3384,7 +4034,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux shell [--session <name>]
+projmux shell [--session <name>] [--socket <name>] [--config <path>] [--bin <path>] [--no-install]
 ```
 
 ## `projmux start`
@@ -3509,7 +4159,246 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux switch [<project>]
+projmux switch [--ui popup|sidebar] [--anchor <pane>]
+projmux switch open <path>
+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>]
+```
+
+Subcommands:
+
+| Route | Summary |
+| --- | --- |
+| [`projmux switch open`](#projmux-switch-open) | Open the project at a path the way the picker opens a selected row |
+| [`projmux switch toggle-tag`](#projmux-switch-toggle-tag) | Toggle the picker tag on a project path; no path means the current directory |
+| [`projmux switch toggle-pin`](#projmux-switch-toggle-pin) | Toggle the pin on a project path; no path means the current directory |
+| [`projmux switch kill`](#projmux-switch-kill) | Stop the tmux session of a project path; no path means the current directory |
+| [`projmux switch preview`](#projmux-switch-preview) | Render the picker preview of a project path; no path means the current directory |
+| [`projmux switch settings`](#projmux-switch-settings) | Open the picker's pin settings menu |
+| [`projmux switch cycle-pane`](#projmux-switch-cycle-pane) | Advance the picker preview pane cursor of a project path |
+| [`projmux switch cycle-window`](#projmux-switch-cycle-window) | Advance the picker preview window cursor of a project path |
+| [`projmux switch sidebar-focus`](#projmux-switch-sidebar-focus) | Move the client to the live session of a project path; a path with no live session does nothing |
+| [`projmux switch sidebar-open`](#projmux-switch-sidebar-open) | Open a project the sidebar selected, anchored on an exact tmux Pane |
+
+Canonical spelling: `projmux create project`, `projmux open project`
+
+### `projmux switch open`
+
+Open the project at a path the way the picker opens a selected row
+
+Selectorless authority: `explicit-target` — the route or caller must name the exact target.
+
+Allowed effects:
+
+- `identity=unchanged|created|reused|replaced`
+- `address=unchanged|allocated|released`
+- `topology=unchanged|established|replaced`
+- `desired-state=unchanged|created|reused|replaced`
+- `runtime=unchanged|materialized|already-live`
+- `focus=unchanged|moved-current-client|attached-caller`
+- `cardinality=unchanged|exact-one`
+- `domain-effect=null`
+
+```
+projmux switch open <path>
+```
+
+Canonical spelling: `projmux create project`, `projmux open project`
+
+### `projmux switch toggle-tag`
+
+Toggle the picker tag on a project path; no path means the current directory
+
+Selectorless authority: `natural-omitted` — omission resolves one predictable current resource or documented contextual read/scope; any selector replaces it.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=exact-one`
+- `domain-effect=null`
+
+```
+projmux switch toggle-tag [path]
+```
+
+### `projmux switch toggle-pin`
+
+Toggle the pin on a project path; no path means the current directory
+
+Selectorless authority: `natural-omitted` — omission resolves one predictable current resource or documented contextual read/scope; any selector replaces it.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=exact-one`
+- `domain-effect=null`
+
+```
+projmux switch toggle-pin [path]
+```
+
+### `projmux switch kill`
+
+Stop the tmux session of a project path; no path means the current directory
+
+Selectorless authority: `natural-omitted` — omission resolves one predictable current resource or documented contextual read/scope; any selector replaces it.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged|stopped`
+- `focus=unchanged|moved-current-client`
+- `cardinality=unchanged|exact-one`
+- `domain-effect=null`
+
+```
+projmux switch kill [path]
+```
+
+### `projmux switch preview`
+
+Render the picker preview of a project path; no path means the current directory
+
+Selectorless authority: `natural-omitted` — omission resolves one predictable current resource or documented contextual read/scope; any selector replaces it.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=unchanged`
+- `domain-effect=null`
+
+```
+projmux switch preview [--ui popup|sidebar] [path]
+```
+
+### `projmux switch settings`
+
+Open the picker's pin settings menu
+
+Selectorless authority: `natural-omitted` — omission resolves one predictable current resource or documented contextual read/scope; any selector replaces it.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=unchanged`
+- `domain-effect=null`
+
+```
+projmux switch settings
+```
+
+### `projmux switch cycle-pane`
+
+Advance the picker preview pane cursor of a project path
+
+Selectorless authority: `explicit-target` — the route or caller must name the exact target.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=unchanged`
+- `domain-effect=null`
+
+```
+projmux switch cycle-pane <path> <next|prev>
+```
+
+### `projmux switch cycle-window`
+
+Advance the picker preview window cursor of a project path
+
+Selectorless authority: `explicit-target` — the route or caller must name the exact target.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=unchanged`
+- `domain-effect=null`
+
+```
+projmux switch cycle-window <path> <next|prev>
+```
+
+### `projmux switch sidebar-focus`
+
+Move the client to the live session of a project path; a path with no live session does nothing
+
+Selectorless authority: `explicit-target` — the route or caller must name the exact target.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged|moved-current-client`
+- `cardinality=unchanged|exact-one`
+- `domain-effect=null`
+
+```
+projmux switch sidebar-focus <path>
+```
+
+### `projmux switch sidebar-open`
+
+Open a project the sidebar selected, anchored on an exact tmux Pane
+
+Selectorless authority: `explicit-target` — the route or caller must name the exact target.
+
+Allowed effects:
+
+- `identity=unchanged|created|reused|replaced`
+- `address=unchanged|allocated|released`
+- `topology=unchanged|established|replaced`
+- `desired-state=unchanged|created|reused|replaced`
+- `runtime=unchanged|materialized|already-live`
+- `focus=unchanged|moved-current-client|attached-caller`
+- `cardinality=unchanged|exact-one`
+- `domain-effect=null`
+
+```
+projmux switch sidebar-open --path <path> --anchor <pane> [--session <name>] [--mode <mode>] [--query <text>] [--client <client>]
 ```
 
 Canonical spelling: `projmux create project`, `projmux open project`
@@ -3532,7 +4421,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux unregister project [<ref>...] [--selector key=value]... [--all] [--dry-run] [--yes]
+projmux unregister project [<ref>...] [--project <ref> | -p <ref>] [--selector key=value]... [--all] [--socket <name> | --socket-path <absolute>] [--dry-run] [--yes]
 ```
 
 Subcommands:
@@ -3561,7 +4450,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux unregister project [<ref>...] [--selector key=value]... [--all] [--dry-run] [--yes]
+projmux unregister project [<ref>...] [--project <ref> | -p <ref>] [--selector key=value]... [--all] [--socket <name> | --socket-path <absolute>] [--dry-run] [--yes]
 ```
 
 Aliases: `projects`
@@ -3584,7 +4473,9 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux update status|check|apply
+projmux update status [--json]
+projmux update check [--json]
+projmux update apply [--dry-run] [--no-apply]
 ```
 
 Subcommands:
@@ -3615,7 +4506,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux update status
+projmux update status [--json]
 ```
 
 ### `projmux update check`
@@ -3636,7 +4527,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux update check
+projmux update check [--json]
 ```
 
 ### `projmux update apply`
@@ -3657,7 +4548,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux update apply
+projmux update apply [--dry-run] [--no-apply]
 ```
 
 ## `projmux welcome`
@@ -3699,7 +4590,8 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux window record|recent
+projmux window record
+projmux window recent
 ```
 
 Subcommands: