projmux 0.15.3 → 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 191 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 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 |
@@ -72,16 +72,18 @@ projmux <command> [args...]
 | [`projmux focus`](#projmux-focus) | canonical | Move the current client to a live resource |
 | [`projmux get`](#projmux-get) | canonical | Read Projmux resources by selector |
 | [`projmux hook`](#projmux-hook) | canonical | List, edit, validate, and trust lifecycle hook config |
+| [`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 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, Agents, and snapshots |
+| [`projmux prune`](#projmux-prune) | canonical | Prune stale Projects and Agents |
 | [`projmux quit`](#projmux-quit) | shortcut | Quit the app-owned projmux tmux runtime |
 | [`projmux reconcile`](#projmux-reconcile) | canonical | Preview or repair Registry and exact tmux resource drift |
 | [`projmux rebind`](#projmux-rebind) | canonical | Rebind a Project to a new absolute root without moving files |
 | [`projmux rename`](#projmux-rename) | canonical | Rename a Projmux resource metadata.name |
 | [`projmux resources`](#projmux-resources) | shortcut | Inspect live Project, Window, and Pane CPU/RSS attribution |
-| [`projmux restore`](#projmux-restore) | canonical | Project a saved snapshot into one exact closed Project desired state |
 | [`projmux runtime`](#projmux-runtime) | canonical | Manage the live and ephemeral tmux runtime inventory |
 | [`projmux settings`](#projmux-settings) | shortcut | Configure projmux |
 | [`projmux setup`](#projmux-setup) | canonical | Probe terminal keys or remediate them with setup terminal |
@@ -117,23 +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 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|antigravity|all>] [--window <name>] [--json] [--force]
-projmux agent app-server upgrade qualify --receipt <absolute-json>
-projmux agent app-server upgrade plan|apply --request <absolute-json>
-projmux agent app-server upgrade resume|abort --operation <ref>
-projmux agent app-server handover plan|apply --request <absolute-json>
-projmux agent app-server handover resume|abort --operation <ref>
-projmux agent capabilities [<agent-ref> | --provider <codex|claude|antigravity>] [-o json]
+projmux agent usage [--model <codex|claude|all>] [--window <name>] [--json] [--force]
+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>]... [--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:
@@ -143,17 +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 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 app-server`](#projmux-agent-app-server) | Manage explicitly requested private Codex app-server generation operations |
 | [`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 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 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 app-server upgrade qualify`, `projmux agent app-server upgrade plan`, `projmux agent app-server upgrade apply`, `projmux agent app-server upgrade resume`, `projmux agent app-server upgrade abort`, `projmux agent app-server handover plan`, `projmux agent app-server handover apply`, `projmux agent app-server handover resume`, `projmux agent app-server handover abort`, `projmux agent capabilities`, `projmux agent message send`, `projmux agent message status`, `projmux agent message qualify`, `projmux agent wait`
+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`
 
@@ -216,12 +228,53 @@ 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]
 ```
 
+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.
+
+Codex keeps the developer instructions its thread started with; resume cannot replace them.
+
+--model and --effort are recorded on the Agent with the source resume (projmux.io/model-source, projmux.io/effort-source).
+
+Items the Agent does not override take its profile's current instructions, model, and effort; the model is passed only when it changed.
+
+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.
+
+### `projmux agent relaunch`
+
+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.
+
+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`
+
+```
+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]
+```
+
+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.
+
+--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.
+
+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).
+
+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.
 
@@ -238,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:
@@ -247,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`
 
@@ -295,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.
 
@@ -311,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.
 
@@ -333,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:
@@ -340,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`
 
@@ -364,11 +423,11 @@ Allowed effects:
 projmux agent approval review <agent-ref> [--request <normalized-id>]
 ```
 
-### `projmux agent review`
+#### `projmux agent approval list`
 
-Start a native review on an exact-bound Codex Agent
+List one exact Claude or Codex Agent's waiting permission requests with their full tool input
 
-Selectorless authority: `natural-omitted` — omission resolves one predictable current resource or documented contextual read/scope; any selector replaces it.
+Selectorless authority: `explicit-target` — the route or caller must name the exact target.
 
 Allowed effects:
 
@@ -378,16 +437,24 @@ Allowed effects:
 - `desired-state=unchanged`
 - `runtime=unchanged`
 - `focus=unchanged`
-- `cardinality=unchanged`
+- `cardinality=exact-one`
 - `domain-effect=null`
 
 ```
-projmux agent review [<agent-ref>] [--agent <ref>] [--base <branch> | --commit <sha> | --instructions <text>]
+projmux agent approval list <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]... [-o json]
 ```
 
-### `projmux agent integrate`
+A Claude Agent lists the permission requests captured while `config agent-approvals --answering projmux` is set.
 
-Install, remove, or preview provider hooks and tmux-bell integration
+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.
 
@@ -399,18 +466,26 @@ Allowed effects:
 - `desired-state=unchanged`
 - `runtime=unchanged`
 - `focus=unchanged`
-- `cardinality=unchanged`
+- `cardinality=exact-one`
 - `domain-effect=null`
 
 ```
-projmux agent integrate <codex|claude|antigravity|tmux-bell> [--remove] [--dry-run]
+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 usage`
+--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.
 
-Read provider account usage quota snapshots
+--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.
 
-Selectorless authority: `explicit-fan-out` — the route spelling is an intentional global or whole-set opt-in.
+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
+
+Selectorless authority: `natural-omitted` — omission resolves one predictable current resource or documented contextual read/scope; any selector replaces it.
 
 Allowed effects:
 
@@ -424,14 +499,14 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux agent usage [--model <codex|claude|antigravity|all>] [--window <name>] [--json] [--force]
+projmux agent review [<agent-ref>] [--agent <ref>] [--base <branch> | --commit <sha> | --instructions <text>]
 ```
 
-### `projmux agent app-server`
+### `projmux agent integrate`
 
-Manage explicitly requested private Codex app-server generation operations
+Install, remove, or preview provider hooks and tmux-bell integration
 
-Selectorless authority: `refusal` — there is no safe selectorless action; refuse before output or mutation.
+Selectorless authority: `explicit-target` — the route or caller must name the exact target.
 
 Allowed effects:
 
@@ -445,23 +520,14 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux agent app-server
+projmux agent integrate <codex|claude|antigravity|tmux-bell> [--remove] [--dry-run]
 ```
 
-Subcommands:
-
-| Route | Summary |
-| --- | --- |
-| [`projmux agent app-server upgrade`](#projmux-agent-app-server-upgrade) | Plan, apply, resume, or abort one exact rolling generation operation |
-| [`projmux agent app-server handover`](#projmux-agent-app-server-handover) | Plan, apply, resume, or abort one exact generation-wide handover |
-
-Canonical spelling: `projmux agent app-server upgrade qualify`, `projmux agent app-server upgrade plan`, `projmux agent app-server upgrade apply`, `projmux agent app-server upgrade resume`, `projmux agent app-server upgrade abort`, `projmux agent app-server handover plan`, `projmux agent app-server handover apply`, `projmux agent app-server handover resume`, `projmux agent app-server handover abort`
-
-#### `projmux agent app-server upgrade`
+### `projmux agent usage`
 
-Plan, apply, resume, or abort one exact rolling generation operation
+Read provider account usage quota snapshots
 
-Selectorless authority: `refusal` — there is no safe selectorless action; refuse before output or mutation.
+Selectorless authority: `explicit-fan-out` — the route spelling is an intentional global or whole-set opt-in.
 
 Allowed effects:
 
@@ -475,26 +541,37 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux agent app-server upgrade
+projmux agent usage [--model <codex|claude|all>] [--window <name>] [--json] [--force]
 ```
 
-Subcommands:
+### `projmux agent capabilities`
 
-| Route | Summary |
-| --- | --- |
-| [`projmux agent app-server upgrade qualify`](#projmux-agent-app-server-upgrade-qualify) | Install one measured version-pair qualification receipt for the generation entry paths |
-| [`projmux agent app-server upgrade plan`](#projmux-agent-app-server-upgrade-plan) | Read the mutation-zero plan for one exact private generation upgrade |
-| [`projmux agent app-server upgrade apply`](#projmux-agent-app-server-upgrade-apply) | Apply one exact crash-resumable private generation admission switch |
-| [`projmux agent app-server upgrade resume`](#projmux-agent-app-server-upgrade-resume) | Resume one exact durable rolling generation operation |
-| [`projmux agent app-server upgrade abort`](#projmux-agent-app-server-upgrade-abort) | Abort one pre-admission operation and clean only its exact candidate |
+Read static provider support or one exact Agent's Registry-backed runtime eligibility
+
+Selectorless authority: `natural-omitted` — omission resolves one predictable current resource or documented contextual read/scope; any selector replaces it.
+
+Allowed effects:
 
-Canonical spelling: `projmux agent app-server upgrade qualify`, `projmux agent app-server upgrade plan`, `projmux agent app-server upgrade apply`, `projmux agent app-server upgrade resume`, `projmux agent app-server upgrade abort`
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=exact-one`
+- `domain-effect=null`
 
-##### `projmux agent app-server upgrade qualify`
+```
+projmux agent capabilities [<agent-ref> | --provider <codex|claude|antigravity>] [-o json] [--json]
+```
 
-Install one measured version-pair qualification receipt for the generation entry paths
+Output modes (`-o`): `json`
 
-Selectorless authority: `explicit-target` — the route or caller must name the exact target.
+### `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:
 
@@ -508,14 +585,16 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux agent app-server upgrade qualify --receipt <absolute-json>
+projmux agent models [--provider <claude|codex>] [-o json]
 ```
 
-##### `projmux agent app-server upgrade plan`
+Output modes (`-o`): `json`
+
+### `projmux agent message`
 
-Read the mutation-zero plan for one exact private generation upgrade
+Exchange bounded untrusted coordination messages; --source selects a source Agent anchor, not caller authentication (default: active Pane)
 
-Selectorless authority: `explicit-target` — the route or caller must name the exact target.
+Selectorless authority: `refusal` — there is no safe selectorless action; refuse before output or mutation.
 
 Allowed effects:
 
@@ -525,16 +604,28 @@ Allowed effects:
 - `desired-state=unchanged`
 - `runtime=unchanged`
 - `focus=unchanged`
-- `cardinality=unchanged`
-- `domain-effect=null`
+- `cardinality=exact-one`
+- `domain-effect=agent-delivery`
 
 ```
-projmux agent app-server upgrade plan --request <absolute-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 [--timeout <duration>]
 ```
 
-##### `projmux agent app-server upgrade apply`
+Subcommands:
+
+| Route | Summary |
+| --- | --- |
+| [`projmux agent message send`](#projmux-agent-message-send) | Submit bounded peer coordination; --source selects a source Agent anchor, not caller authentication (default: active Pane); exits nonzero after printing a failed, refused, expired, or stale receipt |
+| [`projmux agent message status`](#projmux-agent-message-status) | Read a payload-free broker delivery receipt |
+| [`projmux agent message qualify`](#projmux-agent-message-qualify) | Explicitly qualify one exact Claude target using owned current-version isolation evidence and one marker push |
+
+Canonical spelling: `projmux agent message send`, `projmux agent message status`, `projmux agent message qualify`
+
+#### `projmux agent message send`
 
-Apply one exact crash-resumable private generation admission switch
+Submit bounded peer coordination; --source selects a source Agent anchor, not caller authentication (default: active Pane); exits nonzero after printing a failed, refused, expired, or stale receipt
 
 Selectorless authority: `explicit-target` — the route or caller must name the exact target.
 
@@ -546,16 +637,16 @@ Allowed effects:
 - `desired-state=unchanged`
 - `runtime=unchanged`
 - `focus=unchanged`
-- `cardinality=unchanged`
-- `domain-effect=null`
+- `cardinality=exact-one`
+- `domain-effect=agent-delivery`
 
 ```
-projmux agent app-server upgrade apply --request <absolute-json>
+projmux agent message send <agent-ref> [--source <agent-ref>] [--message-ref <ref>] [--reply-to <ref>] [--ttl <duration>] -- <text>
 ```
 
-##### `projmux agent app-server upgrade resume`
+#### `projmux agent message status`
 
-Resume one exact durable rolling generation operation
+Read a payload-free broker delivery receipt
 
 Selectorless authority: `explicit-target` — the route or caller must name the exact target.
 
@@ -568,15 +659,17 @@ Allowed effects:
 - `runtime=unchanged`
 - `focus=unchanged`
 - `cardinality=unchanged`
-- `domain-effect=null`
+- `domain-effect=agent-delivery`
 
 ```
-projmux agent app-server upgrade resume --operation <ref>
+projmux agent message status <message-ref> [-o json]
 ```
 
-##### `projmux agent app-server upgrade abort`
+Output modes (`-o`): `json`
+
+#### `projmux agent message qualify`
 
-Abort one pre-admission operation and clean only its exact candidate
+Explicitly qualify one exact Claude target using owned current-version isolation evidence and one marker push
 
 Selectorless authority: `explicit-target` — the route or caller must name the exact target.
 
@@ -588,18 +681,20 @@ Allowed effects:
 - `desired-state=unchanged`
 - `runtime=unchanged`
 - `focus=unchanged`
-- `cardinality=unchanged`
-- `domain-effect=null`
+- `cardinality=exact-one`
+- `domain-effect=agent-delivery`
 
 ```
-projmux agent app-server upgrade abort --operation <ref>
+projmux agent message qualify <claude-agent-ref> --evidence <absolute-private-json> --confirm-isolated-provider-push -o json [--timeout <duration>]
 ```
 
-#### `projmux agent app-server handover`
+Output modes (`-o`): `json`
 
-Plan, apply, resume, or abort one exact generation-wide handover
+### `projmux agent wait`
 
-Selectorless authority: `refusal` — there is no safe selectorless action; refuse before output or mutation.
+Wait read-only for one exact Agent's Registry-backed idle observation
+
+Selectorless authority: `explicit-target` — the route or caller must name the exact target.
 
 Allowed effects:
 
@@ -609,27 +704,18 @@ Allowed effects:
 - `desired-state=unchanged`
 - `runtime=unchanged`
 - `focus=unchanged`
-- `cardinality=unchanged`
+- `cardinality=exact-one`
 - `domain-effect=null`
 
 ```
-projmux agent app-server handover
+projmux agent wait <agent-ref> [--until idle] [--timeout <duration>] [-o json]
 ```
 
-Subcommands:
-
-| Route | Summary |
-| --- | --- |
-| [`projmux agent app-server handover plan`](#projmux-agent-app-server-handover-plan) | Read the exact target-set generation handover plan |
-| [`projmux agent app-server handover apply`](#projmux-agent-app-server-handover-apply) | Apply one crash-resumable generation-wide handover |
-| [`projmux agent app-server handover resume`](#projmux-agent-app-server-handover-resume) | Resume one exact durable generation handover |
-| [`projmux agent app-server handover abort`](#projmux-agent-app-server-handover-abort) | Abort one exact pre-stop generation handover |
-
-Canonical spelling: `projmux agent app-server handover plan`, `projmux agent app-server handover apply`, `projmux agent app-server handover resume`, `projmux agent app-server handover abort`
+Output modes (`-o`): `json`
 
-##### `projmux agent app-server handover plan`
+### `projmux agent question`
 
-Read the exact target-set generation handover plan
+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.
 
@@ -641,16 +727,30 @@ Allowed effects:
 - `desired-state=unchanged`
 - `runtime=unchanged`
 - `focus=unchanged`
-- `cardinality=unchanged`
+- `cardinality=exact-one`
 - `domain-effect=null`
 
 ```
-projmux agent app-server handover plan --request <absolute-json>
+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 app-server handover apply`
+Subcommands:
+
+| Route | Summary |
+| --- | --- |
+| [`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`
 
-Apply one crash-resumable generation-wide handover
+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.
 
@@ -662,16 +762,16 @@ Allowed effects:
 - `desired-state=unchanged`
 - `runtime=unchanged`
 - `focus=unchanged`
-- `cardinality=unchanged`
+- `cardinality=exact-one`
 - `domain-effect=null`
 
 ```
-projmux agent app-server handover apply --request <absolute-json>
+projmux agent question enable <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]...
 ```
 
-##### `projmux agent app-server handover resume`
+#### `projmux agent question disable`
 
-Resume one exact durable generation handover
+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.
 
@@ -683,16 +783,16 @@ Allowed effects:
 - `desired-state=unchanged`
 - `runtime=unchanged`
 - `focus=unchanged`
-- `cardinality=unchanged`
+- `cardinality=exact-one`
 - `domain-effect=null`
 
 ```
-projmux agent app-server handover resume --operation <ref>
+projmux agent question disable <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]...
 ```
 
-##### `projmux agent app-server handover abort`
+#### `projmux agent question list`
 
-Abort one exact pre-stop generation handover
+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.
 
@@ -704,18 +804,20 @@ Allowed effects:
 - `desired-state=unchanged`
 - `runtime=unchanged`
 - `focus=unchanged`
-- `cardinality=unchanged`
+- `cardinality=exact-one`
 - `domain-effect=null`
 
 ```
-projmux agent app-server handover abort --operation <ref>
+projmux agent question list <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]... [-o json]
 ```
 
-### `projmux agent capabilities`
+Output modes (`-o`): `json`
 
-Read static provider support or one exact Agent's Registry-backed runtime eligibility
+#### `projmux agent question answer`
 
-Selectorless authority: `natural-omitted` — omission resolves one predictable current resource or documented contextual read/scope; any selector replaces it.
+Answer one waiting question by option label, option number, or explicit free text
+
+Selectorless authority: `explicit-target` — the route or caller must name the exact target.
 
 Allowed effects:
 
@@ -729,16 +831,14 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux agent capabilities [<agent-ref> | --provider <codex|claude|antigravity>] [-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]...
 ```
 
-Output modes (`-o`): `json`
-
-### `projmux agent message`
+### `projmux agent sessions`
 
-Exchange bounded untrusted coordination messages; --source selects a source Agent anchor, not caller authentication (default: active Pane)
+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: `refusal` — there is no safe selectorless action; refuse before output or mutation.
+Selectorless authority: `explicit-target` — the route or caller must name the exact target.
 
 Allowed effects:
 
@@ -749,27 +849,29 @@ Allowed effects:
 - `runtime=unchanged`
 - `focus=unchanged`
 - `cardinality=exact-one`
-- `domain-effect=agent-delivery`
+- `domain-effect=null`
 
 ```
-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 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 message send`](#projmux-agent-message-send) | Submit bounded peer coordination; --source selects a source Agent anchor, not caller authentication (default: active Pane); exits nonzero after printing a failed, refused, expired, or stale receipt |
-| [`projmux agent message status`](#projmux-agent-message-status) | Read a payload-free broker delivery receipt |
-| [`projmux agent message qualify`](#projmux-agent-message-qualify) | Explicitly qualify one exact Claude target using owned current-version isolation evidence and one marker push |
+| [`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 message send`, `projmux agent message status`, `projmux agent message qualify`
+Canonical spelling: `projmux agent sessions list`, `projmux agent sessions backfill`, `projmux agent sessions project`, `projmux agent sessions attribute`
 
-#### `projmux agent message send`
+#### `projmux agent sessions list`
 
-Submit bounded peer coordination; --source selects a source Agent anchor, not caller authentication (default: active Pane); exits nonzero after printing a failed, refused, expired, or stale receipt
+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.
 
@@ -782,15 +884,17 @@ Allowed effects:
 - `runtime=unchanged`
 - `focus=unchanged`
 - `cardinality=exact-one`
-- `domain-effect=agent-delivery`
+- `domain-effect=null`
 
 ```
-projmux agent message send <agent-ref> [--source <agent-ref>] [--message-ref <ref>] [--reply-to <ref>] [--ttl <duration>] -- <text>
+projmux agent sessions list <agent-ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]... [-o json]
 ```
 
-#### `projmux agent message status`
+Output modes (`-o`): `json`
 
-Read a payload-free broker delivery receipt
+#### `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.
 
@@ -803,17 +907,17 @@ Allowed effects:
 - `runtime=unchanged`
 - `focus=unchanged`
 - `cardinality=unchanged`
-- `domain-effect=agent-delivery`
+- `domain-effect=null`
 
 ```
-projmux agent message status <message-ref> [-o json]
+projmux agent sessions backfill [--dry-run] [-o json]
 ```
 
 Output modes (`-o`): `json`
 
-#### `projmux agent message qualify`
+#### `projmux agent sessions project`
 
-Explicitly qualify one exact Claude target using owned current-version isolation evidence and one marker push
+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.
 
@@ -826,17 +930,17 @@ Allowed effects:
 - `runtime=unchanged`
 - `focus=unchanged`
 - `cardinality=exact-one`
-- `domain-effect=agent-delivery`
+- `domain-effect=null`
 
 ```
-projmux agent message qualify <claude-agent-ref> --evidence <absolute-private-json> --confirm-isolated-provider-push -o json
+projmux agent sessions project <project-ref> [-o json]
 ```
 
 Output modes (`-o`): `json`
 
-### `projmux agent wait`
+#### `projmux agent sessions attribute`
 
-Wait read-only for one exact Agent's Registry-backed idle observation
+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.
 
@@ -848,11 +952,11 @@ Allowed effects:
 - `desired-state=unchanged`
 - `runtime=unchanged`
 - `focus=unchanged`
-- `cardinality=exact-one`
+- `cardinality=unchanged`
 - `domain-effect=null`
 
 ```
-projmux agent wait <agent-ref> [--until idle] [--timeout <duration>] [-o json]
+projmux agent sessions attribute [--dry-run] [-o json]
 ```
 
 Output modes (`-o`): `json`
@@ -875,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:
@@ -971,7 +1079,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux attention list
+projmux attention list [--json] [--all]
 ```
 
 ### `projmux attention window`
@@ -992,7 +1100,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux attention window
+projmux attention window [window] [style]
 ```
 
 ## `projmux attach`
@@ -1047,7 +1155,7 @@ projmux attach project <ref>
 
 ## `projmux config`
 
-Edit AI split-mode 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.
 
@@ -1064,8 +1172,12 @@ 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:
@@ -1073,10 +1185,14 @@ Subcommands:
 | Route | Summary |
 | --- | --- |
 | [`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 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`
 
@@ -1099,11 +1215,13 @@ Allowed effects:
 projmux config edit [--get|--set <mode>]
 ```
 
-### `projmux config render`
+`--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`.
 
-Print a generated tmux config to stdout; writes nothing
+### `projmux config providers`
 
-Selectorless authority: `explicit-target` — the route or caller must name the exact target.
+List AI providers as enabled or disabled; --enable or --disable changes one
+
+Selectorless authority: `natural-omitted` — omission resolves one predictable current resource or documented contextual read/scope; any selector replaces it.
 
 Allowed effects:
 
@@ -1117,22 +1235,16 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux config render standalone [--bin <path>]
-projmux config render app [--bin <path>]
+projmux config providers
+projmux config providers --enable <id>
+projmux config providers --disable <id>
 ```
 
-Subcommands:
-
-| Route | Summary |
-| --- | --- |
-| [`projmux config render standalone`](#projmux-config-render-standalone) | Print the snippet you source from your own tmux.conf |
-| [`projmux config render app`](#projmux-config-render-app) | Print the config the app-owned projmux tmux server runs from |
-
-#### `projmux config render standalone`
+### `projmux config locale`
 
-Print the snippet you source from your own tmux.conf
+Show the [ui] locale setting and its config.toml; --set stores a new one
 
-Selectorless authority: `explicit-target` — the route or caller must name the exact target.
+Selectorless authority: `natural-omitted` — omission resolves one predictable current resource or documented contextual read/scope; any selector replaces it.
 
 Allowed effects:
 
@@ -1146,16 +1258,15 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux config render standalone [--bin <path>]
+projmux config locale
+projmux config locale --set <value>
 ```
 
-Canonical spelling: `projmux config render`
-
-#### `projmux config render app`
+### `projmux config agent-questions`
 
-Print the config the app-owned projmux tmux server runs from
+Show how Claude and Codex agent questions are answered and how long they wait; --answering or --window changes them
 
-Selectorless authority: `explicit-target` — the route or caller must name the exact target.
+Selectorless authority: `natural-omitted` — omission resolves one predictable current resource or documented contextual read/scope; any selector replaces it.
 
 Allowed effects:
 
@@ -1169,16 +1280,16 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux config render app [--bin <path>]
+projmux config agent-questions
+projmux config agent-questions --answering <claude|projmux>
+projmux config agent-questions --window <seconds|unlimited>
 ```
 
-Canonical spelling: `projmux config render`
-
-### `projmux config apply`
+### `projmux config agent-approvals`
 
-Write the generated app tmux config and reload the live projmux server
+Show how agent permission requests are answered and how long a captured one waits; --answering or --window changes them
 
-Selectorless authority: `explicit-fan-out` — the route spelling is an intentional global or whole-set opt-in.
+Selectorless authority: `natural-omitted` — omission resolves one predictable current resource or documented contextual read/scope; any selector replaces it.
 
 Allowed effects:
 
@@ -1192,14 +1303,20 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux config apply [--bin <path>] [--config <path>] [--socket <name>]
+projmux config agent-approvals [--answering <claude|projmux>] [--window <seconds>]
 ```
 
-## `projmux create`
+`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.
 
-Create Projmux resources
+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.
 
-Selectorless authority: `refusal` — there is no safe selectorless action; refuse before output or mutation.
+--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
+
+Selectorless authority: `explicit-target` — the route or caller must name the exact target.
 
 Allowed effects:
 
@@ -1213,26 +1330,121 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux create project --root <absolute-path> [--name <name>] [--label key=value]... [-o <mode>]
-projmux create window [--project <ref> | -p <ref>] [--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] [--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] [--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 snapshot
+projmux config render standalone [--bin <path>]
+projmux config render app [--bin <path>]
 ```
 
 Subcommands:
 
 | Route | Summary |
 | --- | --- |
-| [`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 and its initial Pane below one Project; 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 config render standalone`](#projmux-config-render-standalone) | Print the snippet you source from your own tmux.conf |
+| [`projmux config render app`](#projmux-config-render-app) | Print the config the app-owned projmux tmux server runs from |
+
+#### `projmux config render standalone`
+
+Print the snippet you source from your own tmux.conf
+
+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 config render standalone [--bin <path>]
+```
+
+Canonical spelling: `projmux config render`
+
+#### `projmux config render app`
+
+Print the config the app-owned projmux tmux server runs from
+
+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 config render app [--bin <path>]
+```
+
+Canonical spelling: `projmux config render`
+
+### `projmux config apply`
+
+Write the generated app tmux config and reload the live projmux server
+
+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 config apply [--bin <path>] [--config <path>] [--socket <name>] [--no-reload]
+```
+
+## `projmux create`
+
+Create Projmux resources
+
+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 create project --root <absolute-path> [--name <name>] [--label key=value]... [-o <mode>]
+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:
+
+| Route | Summary |
+| --- | --- |
+| [`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 or the selected profile names the provider |
 | [`projmux create notification`](#projmux-create-notification) | Create a pending notification row |
-| [`projmux create snapshot`](#projmux-create-snapshot) | Create a session snapshot |
 
 Provider shortcuts:
 
@@ -1242,7 +1454,7 @@ Provider shortcuts:
 | [`projmux create claude`](#projmux-create-claude) | Provider shortcut for create agent --provider claude |
 | [`projmux create antigravity`](#projmux-create-antigravity) | Provider shortcut for create agent --provider antigravity |
 
-Canonical spelling: `projmux create project`, `projmux create window`, `projmux create pane`, `projmux create agent`, `projmux create notification`, `projmux create snapshot`, `projmux create codex`, `projmux create claude`, `projmux create antigravity`
+Canonical spelling: `projmux create project`, `projmux create window`, `projmux create pane`, `projmux create agent`, `projmux create notification`, `projmux create codex`, `projmux create claude`, `projmux create antigravity`
 
 ### `projmux create project`
 
@@ -1265,11 +1477,15 @@ Allowed effects:
 projmux create project --root <absolute-path> [--name <name>] [--label key=value]... [-o <mode>]
 ```
 
+Without `--name` a new Project is named after its root directory, sanitized into a valid name (`my repo` becomes `my-repo`). When that basename is empty (the filesystem root) or another Project already holds it, the Project is named by its exact uid instead; no numbered variant is ever invented.
+
+An explicit `--name` that another Project holds exits 2 with no Registry write. A root that is already registered reuses its Project; an explicit `--name` there must match the stored name.
+
 Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `none`, `receipt`
 
 ### `projmux create window`
 
-Create a Window and its initial Pane below one Project; the runtime is materialized detached
+Create a Window below one Project, opening on a shell Pane or on one Agent; the runtime is materialized detached
 
 Selectorless authority: `natural-omitted` — omission resolves one predictable current resource or documented contextual read/scope; any selector replaces it.
 
@@ -1285,9 +1501,11 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux create window [--project <ref> | -p <ref>] [--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`
@@ -1315,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.
 
@@ -1331,37 +1549,24 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux create agent --provider <provider> [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--interactive-only] [--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>]
 ```
 
-Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `pane-id`, `none`, `receipt`
-
-### `projmux create notification`
-
-Create a pending notification row
+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.
 
-Selectorless authority: `explicit-target` — the route or caller must name the exact target.
+When neither decides it -- no profile, `--profile none`, or a profile without `provider` -- the create is refused as requiring `--provider`.
 
-Allowed effects:
+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.
 
-- `identity=unchanged`
-- `address=unchanged`
-- `topology=unchanged`
-- `desired-state=unchanged`
-- `runtime=unchanged`
-- `focus=unchanged`
-- `cardinality=unchanged`
-- `domain-effect=null`
+`--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.
 
-```
-projmux create notification --text <s> --target <SESSION[:WINDOW[.PANE]]> [--socket <s>]
-```
+Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `pane-id`, `none`, `receipt`
 
-### `projmux create snapshot`
+### `projmux create notification`
 
-Create a session snapshot
+Create a pending notification row
 
-Selectorless authority: `natural-omitted` — omission resolves one predictable current resource or documented contextual read/scope; any selector replaces it.
+Selectorless authority: `explicit-target` — the route or caller must name the exact target.
 
 Allowed effects:
 
@@ -1375,7 +1580,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux create snapshot
+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`
@@ -1396,9 +1601,13 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux create codex [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--interactive-only] [--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`
@@ -1419,7 +1628,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux create claude [--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 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`
@@ -1442,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`
@@ -1465,28 +1674,28 @@ 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:
 
 | Route | Summary |
 | --- | --- |
-| [`projmux delete project`](#projmux-delete-project) | Deprecated alias of unregister project; unregisters Projects and Registry descendants while preserving roots, Git/worktrees, snapshots, and runtime |
+| [`projmux delete project`](#projmux-delete-project) | Deprecated alias of unregister project; unregisters Projects and Registry descendants while preserving roots, Git/worktrees, and runtime |
 | [`projmux delete window`](#projmux-delete-window) | Delete Registry Windows and every descendant Agent and Pane, killing an exact live tmux mirror when present; no selector inside tmux means the active Window, and --all means every Window in the registry |
 | [`projmux delete pane`](#projmux-delete-pane) | Delete Panes; an Agent-owned current Pane leaves its Agent Offline; no selector inside tmux means the active Pane, and --all means every Pane in the registry |
 | [`projmux delete agent`](#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 |
 | [`projmux delete notification`](#projmux-delete-notification) | Delete pending notification rows |
-| [`projmux delete snapshot`](#projmux-delete-snapshot) | Delete saved session snapshots |
 
-Canonical spelling: `projmux unregister project`, `projmux delete window`, `projmux delete pane`, `projmux delete agent`, `projmux delete notification`, `projmux delete snapshot`
+Canonical spelling: `projmux unregister project`, `projmux delete window`, `projmux delete pane`, `projmux delete agent`, `projmux delete notification`
 
 ### `projmux delete project`
 
-Deprecated alias of unregister project; unregisters Projects and Registry descendants while preserving roots, Git/worktrees, snapshots, and runtime
+Deprecated alias of unregister project; unregisters Projects and Registry descendants while preserving roots, Git/worktrees, and runtime
 
 Selectorless authority: `natural-omitted` — omission resolves one predictable current resource or documented contextual read/scope; any selector replaces it.
 
@@ -1502,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`
@@ -1527,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`
@@ -1550,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
@@ -1573,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`
@@ -1596,34 +1807,11 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux delete notification
+projmux delete notification <id> | --all
 ```
 
 Aliases: `notifications`
 
-### `projmux delete snapshot`
-
-Delete saved session snapshots
-
-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 delete snapshot
-```
-
-Aliases: `snapshots`
-
 ## `projmux describe`
 
 Describe one Projmux resource
@@ -1642,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:
@@ -1677,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`
@@ -1702,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`
@@ -1727,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`
@@ -1752,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`
@@ -1798,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>]
 ```
@@ -1831,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`
@@ -1873,7 +2061,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux diagnostics report
+projmux diagnostics report [--output <path>]
 ```
 
 ## `projmux focus`
@@ -1894,9 +2082,11 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux focus project <ref>
-projmux focus window <ref> {--project <ref> | -p <ref>}
-projmux focus pane <ref> {--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:
@@ -1927,9 +2117,11 @@ 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.
+
 ### `projmux focus window`
 
 Move the current client to an already-live Window in an exact live root session; never materializes
@@ -1948,9 +2140,14 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux focus window <ref> {--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>`.
+
+A `uid:` resolution uses the Project's recorded socket; an explicit `--socket` naming another server exits 2. The resolved window must still be live.
+
 ### `projmux focus pane`
 
 Move the current client to an already-live Pane in an exact live root session; never materializes
@@ -1969,9 +2166,14 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux focus pane <ref> {--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>`.
+
+A `uid:` resolution uses the Project's recorded socket; an explicit `--socket` naming another server exits 2. The resolved pane must still be live.
+
 ## `projmux get`
 
 Read Projmux resources by selector
@@ -1995,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:
@@ -2009,10 +2212,9 @@ Subcommands:
 | [`projmux get agents`](#projmux-get-agents) | List Agent resources as NAME STATUS ACTIONS AGE; route-implied KIND is omitted, shifting stdout positions; -o wide retains KIND and diagnostics, and -o json retains kind and invocation context; inside tmux defaults to the active managed root, and --all-projects lists the whole Registry |
 | [`projmux get runtime`](#projmux-get-runtime) | List every tmux Session, Window, and Pane on one exact server with its attribution |
 | [`projmux get notifications`](#projmux-get-notifications) | List pending notification rows |
-| [`projmux get snapshots`](#projmux-get-snapshots) | List saved session snapshots |
 | [`projmux get pane`](#projmux-get-pane) | Read one Pane resource; with no selector inside tmux, the active Pane |
 
-Canonical spelling: `projmux get projects`, `projmux get windows`, `projmux get panes`, `projmux get agents`, `projmux get runtime sessions`, `projmux get runtime windows`, `projmux get runtime panes`, `projmux get notifications`, `projmux get snapshots`, `projmux get pane`
+Canonical spelling: `projmux get projects`, `projmux get windows`, `projmux get panes`, `projmux get agents`, `projmux get runtime sessions`, `projmux get runtime windows`, `projmux get runtime panes`, `projmux get notifications`, `projmux get pane`
 
 ### `projmux get projects`
 
@@ -2232,34 +2434,11 @@ 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`
 
-### `projmux get snapshots`
-
-List saved session snapshots
-
-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 get snapshots
-```
-
-Aliases: `snapshot`
-
 ### `projmux get pane`
 
 Read one Pane resource; with no selector inside tmux, the active Pane
@@ -2303,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 |
@@ -2336,7 +2522,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux hook list
+projmux hook list [--global | --project | --effective]
 ```
 
 ### `projmux hook edit`
@@ -2357,7 +2543,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux hook edit
+projmux hook edit [--global | --project] [--editor] <event>
 ```
 
 ### `projmux hook validate`
@@ -2399,7 +2585,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux hook trust
+projmux hook trust [<project>]
 ```
 
 ### `projmux hook untrust`
@@ -2420,12 +2606,12 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux hook untrust
+projmux hook untrust [<project>]
 ```
 
-## `projmux notification`
+## `projmux label`
 
-Manage pending notification workflow state
+Set or remove Projmux resource metadata.labels after creation
 
 Selectorless authority: `refusal` — there is no safe selectorless action; refuse before output or mutation.
 
@@ -2441,24 +2627,28 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux notification ack <id> | --all
-projmux notification reconcile [--json]
+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:
 
 | Route | Summary |
 | --- | --- |
-| [`projmux notification ack`](#projmux-notification-ack) | Acknowledge notification rows |
-| [`projmux notification reconcile`](#projmux-notification-reconcile) | Reconcile the notification queue against live targets |
+| [`projmux label project`](#projmux-label-project) | Set or remove Project labels; with no selector inside tmux, the active Project |
+| [`projmux label window`](#projmux-label-window) | Set or remove Window labels; inside tmux a reference resolves within the active Project or ControlSession and no selector means the active Window |
+| [`projmux label pane`](#projmux-label-pane) | Set or remove Pane labels; inside tmux a reference resolves within the active Project or ControlSession and no selector means the active Pane |
+| [`projmux label agent`](#projmux-label-agent) | Set or remove Agent labels within the active Project or ControlSession without changing its name, topic, provider, or managed Pane |
 
-Canonical spelling: `projmux notification ack`, `projmux notification reconcile`
+Canonical spelling: `projmux label project`, `projmux label window`, `projmux label pane`, `projmux label agent`
 
-### `projmux notification ack`
+### `projmux label project`
 
-Acknowledge notification rows
+Set or remove Project labels; with no selector inside tmux, the active Project
 
-Selectorless authority: `explicit-target` — the route or caller must name the exact target.
+Selectorless authority: `natural-omitted` — omission resolves one predictable current resource or documented contextual read/scope; any selector replaces it.
 
 Allowed effects:
 
@@ -2468,18 +2658,20 @@ Allowed effects:
 - `desired-state=unchanged`
 - `runtime=unchanged`
 - `focus=unchanged`
-- `cardinality=unchanged`
+- `cardinality=exact-one`
 - `domain-effect=null`
 
 ```
-projmux notification ack <id> | --all
+projmux label project [<ref>] <key=value|key->... [--project <ref> | -p <ref>] [--selector key=value]...
 ```
 
-### `projmux notification reconcile`
+Aliases: `projects`
 
-Reconcile the notification queue against live targets
+### `projmux label window`
 
-Selectorless authority: `explicit-fan-out` — the route spelling is an intentional global or whole-set opt-in.
+Set or remove Window labels; inside tmux a reference resolves within the active Project or ControlSession and no selector means the active Window
+
+Selectorless authority: `natural-omitted` — omission resolves one predictable current resource or documented contextual read/scope; any selector replaces it.
 
 Allowed effects:
 
@@ -2489,18 +2681,20 @@ Allowed effects:
 - `desired-state=unchanged`
 - `runtime=unchanged`
 - `focus=unchanged`
-- `cardinality=unchanged`
+- `cardinality=exact-one`
 - `domain-effect=null`
 
 ```
-projmux notification reconcile [--json]
+projmux label window [<ref>] <key=value|key->... [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]...
 ```
 
-## `projmux open`
+Aliases: `windows`
 
-Open a Project runtime and move the current client to it
+### `projmux label pane`
 
-Selectorless authority: `refusal` — there is no safe selectorless action; refuse before output or mutation.
+Set or remove Pane labels; inside tmux a reference resolves within the active Project or ControlSession and no selector means the active Pane
+
+Selectorless authority: `natural-omitted` — omission resolves one predictable current resource or documented contextual read/scope; any selector replaces it.
 
 Allowed effects:
 
@@ -2510,26 +2704,20 @@ Allowed effects:
 - `desired-state=unchanged`
 - `runtime=unchanged`
 - `focus=unchanged`
-- `cardinality=unchanged`
+- `cardinality=exact-one`
 - `domain-effect=null`
 
 ```
-projmux open project <ref> [-o receipt|none]
+projmux label pane [<ref>] <key=value|key->... [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]...
 ```
 
-Subcommands:
-
-| Route | Summary |
-| --- | --- |
-| [`projmux open project`](#projmux-open-project) | Materialize an offline Project runtime when needed and move the current tmux client to it; outside tmux it refuses and points at attach |
-
-Canonical spelling: `projmux open project`
+Aliases: `panes`
 
-### `projmux open project`
+### `projmux label agent`
 
-Materialize an offline Project runtime when needed and move the current tmux client to it; outside tmux it refuses and points at attach
+Set or remove Agent labels within the active Project or ControlSession without changing its name, topic, provider, or managed Pane
 
-Selectorless authority: `explicit-target` — the route or caller must name the exact target.
+Selectorless authority: `natural-omitted` — omission resolves one predictable current resource or documented contextual read/scope; any selector replaces it.
 
 Allowed effects:
 
@@ -2537,20 +2725,20 @@ Allowed effects:
 - `address=unchanged`
 - `topology=unchanged`
 - `desired-state=unchanged`
-- `runtime=materialized|already-live`
-- `focus=moved-current-client`
+- `runtime=unchanged`
+- `focus=unchanged`
 - `cardinality=exact-one`
 - `domain-effect=null`
 
 ```
-projmux open project <ref> [-o receipt|none]
+projmux label agent [<ref>] <key=value|key->... [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]...
 ```
 
-Output modes (`-o`): `receipt`, `none`
+Aliases: `agents`
 
-## `projmux pin`
+## `projmux notification`
 
-Manage pinned project directories
+Manage pending notification workflow state
 
 Selectorless authority: `refusal` — there is no safe selectorless action; refuse before output or mutation.
 
@@ -2566,20 +2754,22 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux pin project list|add|remove|toggle|clear
+projmux notification ack <id> | --all
+projmux notification reconcile [--json]
 ```
 
 Subcommands:
 
 | Route | Summary |
 | --- | --- |
-| [`projmux pin project`](#projmux-pin-project) | Manage pinned project directories (canonical spelling) |
+| [`projmux notification ack`](#projmux-notification-ack) | Acknowledge notification rows |
+| [`projmux notification reconcile`](#projmux-notification-reconcile) | Reconcile the notification queue against live targets |
 
-Canonical spelling: `projmux pin project`
+Canonical spelling: `projmux notification ack`, `projmux notification reconcile`
 
-### `projmux pin project`
+### `projmux notification ack`
 
-Manage pinned project directories (canonical spelling)
+Acknowledge notification rows
 
 Selectorless authority: `explicit-target` — the route or caller must name the exact target.
 
@@ -2595,14 +2785,14 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux pin project list|add|remove|toggle|clear
+projmux notification ack <id> | --all
 ```
 
-## `projmux prune`
+### `projmux notification reconcile`
 
-Prune stale Projects, Agents, and snapshots
+Reconcile the notification queue against live targets
 
-Selectorless authority: `refusal` — there is no safe selectorless action; refuse before output or mutation.
+Selectorless authority: `explicit-fan-out` — the route spelling is an intentional global or whole-set opt-in.
 
 Allowed effects:
 
@@ -2616,71 +2806,535 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux prune snapshot [--older-than <duration>]
-projmux prune project --missing --older-than <duration> [--yes]
-projmux prune agent --older-than <duration> [--no-session-ref] [--no-pane] [--exclude <agent-ref>]... [--yes]
+projmux notification reconcile [--json]
 ```
 
-Subcommands:
+## `projmux open`
 
-| Route | Summary |
-| --- | --- |
-| [`projmux prune agent`](#projmux-prune-agent) | Delete Offline or Failed Agents past a bounded age whose session ref or managed Panes are gone; live Panes and Running Agents are never selected |
-| [`projmux prune project`](#projmux-prune-project) | Delete Projects whose spec.root has been missing for a bounded age |
-| [`projmux prune snapshot`](#projmux-prune-snapshot) | Inspect or delete preserved session snapshots (canonical spelling) |
+Open a Project runtime and move the current client to it
 
-Canonical spelling: `projmux prune agent`, `projmux prune project`, `projmux prune snapshot`
+Selectorless authority: `refusal` — there is no safe selectorless action; refuse before output or mutation.
 
-### `projmux prune agent`
+Allowed effects:
 
-Delete Offline or Failed Agents past a bounded age whose session ref or managed Panes are gone; live Panes and Running Agents are never selected
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=unchanged`
+- `domain-effect=null`
+
+```
+projmux open project <ref> [-o receipt|none]
+```
+
+Subcommands:
+
+| Route | Summary |
+| --- | --- |
+| [`projmux open project`](#projmux-open-project) | Materialize an offline Project runtime when needed and move the current tmux client to it; outside tmux it refuses and points at attach |
+
+Canonical spelling: `projmux open project`
+
+### `projmux open project`
+
+Materialize an offline Project runtime when needed and move the current tmux client to it; outside tmux it refuses and points at attach
+
+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=materialized|already-live`
+- `focus=moved-current-client`
+- `cardinality=exact-one`
+- `domain-effect=null`
+
+```
+projmux open project <ref> [-o receipt|none]
+```
+
+Output modes (`-o`): `receipt`, `none`
+
+## `projmux instructions`
+
+List, show, edit, set, and delete Agent instruction files
+
+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 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 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 instructions list`, `projmux instructions show`, `projmux instructions edit`, `projmux instructions set`, `projmux instructions delete`
+
+### `projmux instructions list`
+
+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.
 
 Allowed effects:
 
-- `identity=removed`
-- `address=released`
-- `topology=removed`
-- `desired-state=removed`
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
 - `runtime=unchanged`
 - `focus=unchanged`
-- `cardinality=zero-or-more`
+- `cardinality=unchanged`
 - `domain-effect=null`
 
 ```
-projmux prune agent --older-than <duration> [--no-session-ref] [--no-pane] [--exclude <agent-ref>]... [--yes]
+projmux instructions list
 ```
 
-### `projmux prune project`
+### `projmux instructions show`
 
-Delete Projects whose spec.root has been missing for a bounded age
+Print one instruction's content exactly as stored
+
+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 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=removed`
-- `address=released`
-- `topology=removed`
-- `desired-state=removed`
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=unchanged`
+- `domain-effect=null`
+
+```
+projmux profile list
+```
+
+### `projmux profile show`
+
+Print one profile's content exactly as stored
+
+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 profile show <name>
+```
+
+### `projmux profile set`
+
+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.
+
+Allowed effects:
+
+- `identity=unchanged`
+- `address=unchanged`
+- `topology=unchanged`
+- `desired-state=unchanged`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=unchanged`
+- `domain-effect=null`
+
+```
+projmux profile set <name> [--file <path> | -]
+```
+
+### `projmux profile delete`
+
+Delete one stored profile file
+
+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 profile delete <name> --yes
+```
+
+## `projmux pin`
+
+Manage pinned project directories
+
+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 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:
+
+| Route | Summary |
+| --- | --- |
+| [`projmux pin project`](#projmux-pin-project) | Manage pinned project directories (canonical spelling) |
+
+Canonical spelling: `projmux pin project`
+
+### `projmux pin project`
+
+Manage pinned project directories (canonical spelling)
+
+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 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 prune project --missing --older-than <duration> [--yes]
+projmux pin project clear
 ```
 
-### `projmux prune snapshot`
+#### `projmux pin project migrate`
 
-Inspect or delete preserved session snapshots (canonical spelling)
+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`
+
+Prune stale Projects and Agents
+
+Selectorless authority: `refusal` — there is no safe selectorless action; refuse before output or mutation.
+
+Allowed effects:
+
 - `identity=unchanged`
 - `address=unchanged`
 - `topology=unchanged`
@@ -2691,11 +3345,60 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux prune snapshot [--older-than <duration>]
-projmux prune snapshot delete <session>...
+projmux prune project --missing --older-than <duration> [--yes]
+projmux prune agent --older-than <duration> [--no-session-ref] [--no-pane] [--exclude <agent-ref>]... [--yes]
 ```
 
-Canonical spelling: `projmux delete snapshot`
+Subcommands:
+
+| Route | Summary |
+| --- | --- |
+| [`projmux prune agent`](#projmux-prune-agent) | Delete Offline or Failed Agents past a bounded age whose session ref or managed Panes are gone; live Panes and Running Agents are never selected |
+| [`projmux prune project`](#projmux-prune-project) | Delete Projects whose spec.root has been missing for a bounded age |
+
+Canonical spelling: `projmux prune agent`, `projmux prune project`
+
+### `projmux prune agent`
+
+Delete Offline or Failed Agents past a bounded age whose session ref or managed Panes are gone; live Panes and Running Agents are never selected
+
+Selectorless authority: `explicit-fan-out` — the route spelling is an intentional global or whole-set opt-in.
+
+Allowed effects:
+
+- `identity=removed`
+- `address=released`
+- `topology=removed`
+- `desired-state=removed`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=zero-or-more`
+- `domain-effect=null`
+
+```
+projmux prune agent --older-than <duration> [--no-session-ref] [--no-pane] [--exclude <agent-ref>]... [--yes]
+```
+
+### `projmux prune project`
+
+Delete Projects whose spec.root has been missing for a bounded age
+
+Selectorless authority: `explicit-fan-out` — the route spelling is an intentional global or whole-set opt-in.
+
+Allowed effects:
+
+- `identity=removed`
+- `address=released`
+- `topology=removed`
+- `desired-state=removed`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=zero-or-more`
+- `domain-effect=null`
+
+```
+projmux prune project --missing --older-than <duration> [--yes]
+```
 
 ## `projmux quit`
 
@@ -2736,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]
 ```
 
@@ -2767,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
@@ -2791,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
@@ -2809,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:
@@ -2838,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`
@@ -2859,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:
@@ -2894,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`
@@ -2919,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`
@@ -2944,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`
@@ -2969,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`
@@ -2988,63 +3695,13 @@ Allowed effects:
 - `address=unchanged`
 - `topology=unchanged`
 - `desired-state=unchanged`
-- `runtime=unchanged`
-- `focus=unchanged`
-- `cardinality=unchanged`
-- `domain-effect=null`
-
-```
-projmux resources
-```
-
-## `projmux restore`
-
-Project a saved snapshot into one exact closed Project desired state
-
-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 restore snapshot --session <name> [--project <ref> | -p <ref>] [--dry-run | --yes] [--client <tmux-client>]
-```
-
-Subcommands:
-
-| Route | Summary |
-| --- | --- |
-| [`projmux restore snapshot`](#projmux-restore-snapshot) | Project a saved snapshot into one exact closed Project desired state |
-
-Canonical spelling: `projmux restore snapshot`
-
-### `projmux restore snapshot`
-
-Project a saved snapshot into one exact closed Project desired state
-
-Selectorless authority: `explicit-target` — the route or caller must name the exact target.
-
-Allowed effects:
-
-- `identity=unchanged|created|reused|removed|replaced`
-- `address=unchanged|allocated|released`
-- `topology=unchanged|established|removed|replaced`
-- `desired-state=unchanged|created|removed|replaced`
-- `runtime=unchanged|materialized`
-- `focus=unchanged|moved-current-client|attached-caller`
-- `cardinality=unchanged|one-or-more`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=unchanged`
 - `domain-effect=null`
 
 ```
-projmux restore snapshot --session <name> [--project <ref> | -p <ref>] [--dry-run | --yes] [--client <tmux-client>]
+projmux resources
 ```
 
 ## `projmux runtime`
@@ -3065,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:
@@ -3104,7 +3763,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux runtime sessions
+projmux runtime sessions [--ui popup|sidebar]
 ```
 
 ### `projmux runtime diagnostics`
@@ -3125,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`
@@ -3146,7 +3805,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux runtime attach
+projmux runtime attach [--keep <n>] [--fallback home|ephemeral]
 ```
 
 ### `projmux runtime stop`
@@ -3167,7 +3826,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux runtime stop
+projmux runtime stop [<session>...]
 ```
 
 ### `projmux runtime tag`
@@ -3188,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`
@@ -3209,7 +3941,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux runtime prune
+projmux runtime prune [--keep <n>]
 ```
 
 ## `projmux settings`
@@ -3251,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:
@@ -3302,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`
@@ -3427,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`
@@ -3450,20 +4421,20 @@ 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:
 
 | Route | Summary |
 | --- | --- |
-| [`projmux unregister project`](#projmux-unregister-project) | Unregister Projects and their Registry descendants while preserving roots, Git/worktrees, snapshots, and runtime |
+| [`projmux unregister project`](#projmux-unregister-project) | Unregister Projects and their Registry descendants while preserving roots, Git/worktrees, and runtime |
 
 Canonical spelling: `projmux unregister project`
 
 ### `projmux unregister project`
 
-Unregister Projects and their Registry descendants while preserving roots, Git/worktrees, snapshots, and runtime
+Unregister Projects and their Registry descendants while preserving roots, Git/worktrees, and runtime
 
 Selectorless authority: `natural-omitted` — omission resolves one predictable current resource or documented contextual read/scope; any selector replaces it.
 
@@ -3479,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`
@@ -3502,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:
@@ -3533,7 +4506,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux update status
+projmux update status [--json]
 ```
 
 ### `projmux update check`
@@ -3554,7 +4527,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux update check
+projmux update check [--json]
 ```
 
 ### `projmux update apply`
@@ -3575,7 +4548,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux update apply
+projmux update apply [--dry-run] [--no-apply]
 ```
 
 ## `projmux welcome`
@@ -3617,7 +4590,8 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux window record|recent
+projmux window record
+projmux window recent
 ```
 
 Subcommands: