projmux 0.12.1 → 0.13.0

package/docs/cli.md

@@ -44,7 +44,7 @@ projmux <command> [args...]
 | [`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 | Preview a saved session snapshot restore (--dry-run only in this release) |
+| [`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 |
@@ -64,7 +64,11 @@ Manage Agent state, topic, integrations, and account usage
 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>] [--window <ref>]...
+projmux agent resume <ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]...
+projmux agent turn start|steer <agent-ref> -- <text>
+projmux agent turn interrupt <agent-ref>
+projmux agent approval review <agent-ref> [--request <normalized-id>]
+projmux agent review [<agent-ref>] [--agent <ref>] [--base <branch> | --commit <sha> | --instructions <text>]
 projmux agent integrate <provider> [--dry-run]
 projmux agent usage [--model <name>] [--window <name>] [--json] [--force]
 ```
@@ -75,11 +79,14 @@ 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 to a new managed Pane |
+| [`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 review`](#projmux-agent-review) | Start a native review on an exact-bound Codex Agent |
 | [`projmux agent integrate`](#projmux-agent-integrate) | Install or remove provider hook integrations |
 | [`projmux agent usage`](#projmux-agent-usage) | Read provider account usage quota snapshots |
 
-Canonical spelling: `projmux agent status`, `projmux agent topic`, `projmux agent resume`, `projmux agent integrate`, `projmux agent usage`
+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 status`
 
@@ -100,10 +107,85 @@ projmux agent topic set <text> [<agent-ref>] [--agent <ref>]
 
 ### `projmux agent resume`
 
-Rebind an Offline or Failed Agent to a new managed Pane
+Rebind an Offline or Failed Agent detached on its Window's exact shell or Agent anchor
 
 ```
-projmux agent resume <ref> [--project <ref>] [--window <ref>]... [--selector key=value]...
+projmux agent resume <ref> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]...
+```
+
+### `projmux agent turn`
+
+Send, steer, or interrupt one exact native Codex turn
+
+```
+projmux agent turn start|steer <agent-ref> -- <text>
+projmux agent turn interrupt <agent-ref>
+```
+
+Subcommands:
+
+| Route | Summary |
+| --- | --- |
+| [`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) | Steer one exact current Codex turn |
+| [`projmux agent turn interrupt`](#projmux-agent-turn-interrupt) | Interrupt one exact current Codex turn |
+
+Canonical spelling: `projmux agent turn start`, `projmux agent turn steer`, `projmux agent turn interrupt`
+
+#### `projmux agent turn start`
+
+Send a new turn to one exact idle Codex thread
+
+```
+projmux agent turn start <agent-ref> -- <text>
+```
+
+#### `projmux agent turn steer`
+
+Steer one exact current Codex turn
+
+```
+projmux agent turn steer <agent-ref> -- <text>
+```
+
+#### `projmux agent turn interrupt`
+
+Interrupt one exact current Codex turn
+
+```
+projmux agent turn interrupt <agent-ref>
+```
+
+### `projmux agent approval`
+
+Review one exact pending native Codex approval
+
+```
+projmux agent approval review <agent-ref> [--request <normalized-id>]
+```
+
+Subcommands:
+
+| Route | Summary |
+| --- | --- |
+| [`projmux agent approval review`](#projmux-agent-approval-review) | Review one exact pending native Codex approval |
+
+Canonical spelling: `projmux agent approval review`
+
+#### `projmux agent approval review`
+
+Review one exact pending native Codex approval
+
+```
+projmux agent approval review <agent-ref> [--request <normalized-id>]
+```
+
+### `projmux agent review`
+
+Start a native review on an exact-bound Codex Agent
+
+```
+projmux agent review [<agent-ref>] [--agent <ref>] [--base <branch> | --commit <sha> | --instructions <text>]
 ```
 
 ### `projmux agent integrate`
@@ -283,10 +365,11 @@ projmux config apply [--bin <path>] [--config <path>] [--socket <name>]
 Create Projmux resources
 
 ```
-projmux create window --project <ref> [--name <name>] [--label key=value]... [-o <mode>] [-- <payload>]
-projmux create pane --project <ref> [--window <ref>]... [--pane <ref>]... [--create-window] [--placement right|down] [-o <mode>] [-- <payload>]
-projmux create agent --provider <provider> --project <ref> [--cwd <path>] [--add-dir <path>]... [--window <ref>]... [--pane <ref>]... [--create-window] [--placement right|down] [-o <mode>] [-- <payload>]
-projmux create codex|claude|antigravity --project <ref> [--cwd <path>] [--add-dir <path>]... [--window <ref>]... [--create-window] [--placement right|down] [-o <mode>] [-- <payload>]
+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] [--placement right|down] [-o <mode>] [-- <payload>]
+projmux create agent --provider <provider> [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--window <ref> | -w <ref>]... [--pane <ref>]... [--create-window] [--placement right|down] [-o <mode>] [-- <payload>]
+projmux create codex|claude|antigravity [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--window <ref> | -w <ref>]... [--create-window] [--placement right|down] [-o <mode>] [-- <payload>]
 projmux create notification --text <s> --target <SESSION[:WINDOW[.PANE]]> [--socket <s>]
 projmux create snapshot
 ```
@@ -295,9 +378,10 @@ 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; --project splits the resolved Windows detached, without it the current Window |
-| [`projmux create agent`](#projmux-create-agent) | Create an Agent and its managed Pane; --provider is required, and --project splits the resolved Windows detached |
+| [`projmux create pane`](#projmux-create-pane) | Create a shell Pane detached on an explicit Pane or the Window's exact shell or Agent anchor |
+| [`projmux create agent`](#projmux-create-agent) | Create an Agent detached on an explicit Pane or the Window's exact shell or Agent anchor; --provider is required |
 | [`projmux create notification`](#projmux-create-notification) | Create a pending notification row |
 | [`projmux create snapshot`](#projmux-create-snapshot) | Create a session snapshot |
 
@@ -309,36 +393,44 @@ 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 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 snapshot`, `projmux create codex`, `projmux create claude`, `projmux create antigravity`
+
+### `projmux create project`
+
+Register one exact filesystem path as a Registry Project; no runtime is materialized
+
+```
+projmux create project --root <absolute-path> [--name <name>] [--label key=value]... [-o <mode>]
+```
+
+Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `none`
 
 ### `projmux create window`
 
 Create a Window and its initial Pane below one Project; the runtime is materialized detached
 
 ```
-projmux create window --project <ref> [--name <name>] [--label key=value]... [-o <mode>] [-- <payload>]
+projmux create window [--project <ref> | -p <ref>] [--name <name>] [--label key=value]... [-o <mode>] [-- <payload>]
 ```
 
 Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `pane-id`, `none`
 
 ### `projmux create pane`
 
-Create a shell Pane; --project splits the resolved Windows detached, without it the current Window
+Create a shell Pane detached on an explicit Pane or the Window's exact shell or Agent anchor
 
 ```
-projmux create pane --project <ref> [--window <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--name <name>] [--label key=value]... [--placement right|down] [-o <mode>] [-- <payload>]
-projmux create pane [--placement right|down] [-o <mode>]
+projmux create pane [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--name <name>] [--label key=value]... [--placement right|down] [-o <mode>] [-- <payload>]
 ```
 
 Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `pane-id`, `none`
 
 ### `projmux create agent`
 
-Create an Agent and its managed Pane; --provider is required, and --project splits the resolved Windows detached
+Create an Agent detached on an explicit Pane or the Window's exact shell or Agent anchor; --provider is required
 
 ```
-projmux create agent --provider <provider> --project <ref> [--cwd <path>] [--add-dir <path>]... [--window <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--name <name>] [--label key=value]... [--placement right|down] [-o <mode>] [-- <payload>]
-projmux create agent --provider <provider> [--placement right|down] [-o pane-id|none] [-- <payload>]
+projmux create agent --provider <provider> [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--name <name>] [--label key=value]... [--placement right|down] [-o <mode>] [-- <payload>]
 ```
 
 Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `pane-id`, `none`
@@ -364,8 +456,7 @@ projmux create snapshot
 Provider shortcut for create agent --provider codex
 
 ```
-projmux create codex --project <ref> [--cwd <path>] [--add-dir <path>]... [--window <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--name <name>] [--label key=value]... [--placement right|down] [-o <mode>] [-- <payload>]
-projmux create codex [--placement right|down] [-o pane-id|none] [-- <payload>]
+projmux create codex [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--name <name>] [--label key=value]... [--placement right|down] [-o <mode>] [-- <payload>]
 ```
 
 Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `pane-id`, `none`
@@ -375,8 +466,7 @@ Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `pane-id`, `none`
 Provider shortcut for create agent --provider claude
 
 ```
-projmux create claude --project <ref> [--cwd <path>] [--add-dir <path>]... [--window <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--name <name>] [--label key=value]... [--placement right|down] [-o <mode>] [-- <payload>]
-projmux create claude [--placement right|down] [-o pane-id|none] [-- <payload>]
+projmux create claude [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--name <name>] [--label key=value]... [--placement right|down] [-o <mode>] [-- <payload>]
 ```
 
 Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `pane-id`, `none`
@@ -386,8 +476,7 @@ Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `pane-id`, `none`
 Provider shortcut for create agent --provider antigravity
 
 ```
-projmux create antigravity --project <ref> [--cwd <path>] [--add-dir <path>]... [--window <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--name <name>] [--label key=value]... [--placement right|down] [-o <mode>] [-- <payload>]
-projmux create antigravity [--placement right|down] [-o pane-id|none] [-- <payload>]
+projmux create antigravity [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--name <name>] [--label key=value]... [--placement right|down] [-o <mode>] [-- <payload>]
 ```
 
 Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `pane-id`, `none`
@@ -397,29 +486,41 @@ Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `pane-id`, `none`
 Delete Projmux resources with an explicit cascade plan
 
 ```
-projmux delete window [<ref>...] [--project <ref>] [--selector key=value]... [--all] [--dry-run] [--yes]
-projmux delete pane [<ref>...] [--project <ref>] [--window <ref>]... [--all] [--dry-run] [--yes]
-projmux delete agent [<ref>...] [--project <ref>] [--window <ref>]... [--all] [--dry-run] [--yes]
+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]
 ```
 
 Subcommands:
 
 | Route | Summary |
 | --- | --- |
-| [`projmux delete window`](#projmux-delete-window) | Delete exact live tmux Windows and every descendant Agent and Pane; no selector inside tmux means the active Window, and --all means every Window in the registry |
+| [`projmux delete project`](#projmux-delete-project) | Explicitly unregister Projects and Registry descendants while preserving roots, Git/worktrees, snapshots, 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 delete window`, `projmux delete pane`, `projmux delete agent`, `projmux delete notification`, `projmux delete snapshot`
+Canonical spelling: `projmux delete project`, `projmux delete window`, `projmux delete pane`, `projmux delete agent`, `projmux delete notification`, `projmux delete snapshot`
+
+### `projmux delete project`
+
+Explicitly unregister Projects and Registry descendants while preserving roots, Git/worktrees, snapshots, and runtime
+
+```
+projmux delete project [<ref>...] [--selector key=value]... [--all] [--dry-run] [--yes]
+```
+
+Aliases: `projects`
 
 ### `projmux delete window`
 
-Delete exact live tmux Windows and every descendant Agent and Pane; no selector inside tmux means the active Window, and --all means every Window in the registry
+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 window [<ref>...] [--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]
 ```
 
 Aliases: `windows`
@@ -429,7 +530,7 @@ Aliases: `windows`
 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 pane [<ref>...] [--project <ref>] [--window <ref>]... [--all] [--dry-run] [--yes]
+projmux delete pane [<ref>...] [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--all] [--socket <name> | --socket-path <absolute>] [--dry-run] [--yes]
 ```
 
 Aliases: `panes`
@@ -439,7 +540,7 @@ Aliases: `panes`
 Delete Agents and their managed Panes; no selector inside tmux means the active Agent, and --all means every Agent in the registry
 
 ```
-projmux delete agent [<ref>...] [--project <ref>] [--window <ref>]... [--all] [--dry-run] [--yes]
+projmux delete agent [<ref>...] [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--all] [--socket <name> | --socket-path <absolute>] [--dry-run] [--yes]
 ```
 
 Aliases: `agents`
@@ -469,10 +570,10 @@ Aliases: `snapshots`
 Describe one Projmux resource
 
 ```
-projmux describe project [<ref>] [-o <mode>]
-projmux describe window [<ref>] [--project <ref>] [-o <mode>]
-projmux describe pane [<ref>] [--project <ref>] [--window <ref>]... [-o <mode>]
-projmux describe agent [<ref>] [--project <ref>] [--window <ref>]... [-o <mode>]
+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>]
 ```
 
 Subcommands:
@@ -480,9 +581,9 @@ Subcommands:
 | Route | Summary |
 | --- | --- |
 | [`projmux describe project`](#projmux-describe-project) | Describe one Project resource; with no selector inside tmux, the active Project |
-| [`projmux describe window`](#projmux-describe-window) | Describe one Window resource; with no selector inside tmux, the active Window |
-| [`projmux describe pane`](#projmux-describe-pane) | Describe one Pane resource; with no selector inside tmux, the active Pane |
-| [`projmux describe agent`](#projmux-describe-agent) | Describe one Agent resource; with no selector inside tmux, the Agent owning the active Pane |
+| [`projmux describe window`](#projmux-describe-window) | Describe one Window resource; inside tmux a reference resolves within the active Project and no selector means the active Window |
+| [`projmux describe pane`](#projmux-describe-pane) | Describe one Pane resource; inside tmux a reference resolves within the active Project and no selector means the active Pane |
+| [`projmux describe agent`](#projmux-describe-agent) | Describe one Agent resource; inside tmux a reference resolves within the active Project and no selector means the Agent owning the active Pane |
 
 Canonical spelling: `projmux describe project`, `projmux describe window`, `projmux describe pane`, `projmux describe agent`
 
@@ -491,7 +592,7 @@ Canonical spelling: `projmux describe project`, `projmux describe window`, `proj
 Describe one Project resource; with no selector inside tmux, the active Project
 
 ```
-projmux describe project
+projmux describe project [<ref>] [--project <ref> | -p <ref>] [-o <mode>]
 ```
 
 Aliases: `projects`
@@ -500,10 +601,10 @@ Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `none`
 
 ### `projmux describe window`
 
-Describe one Window resource; with no selector inside tmux, the active Window
+Describe one Window resource; inside tmux a reference resolves within the active Project and no selector means the active Window
 
 ```
-projmux describe window
+projmux describe window [<ref>] [--project <ref> | -p <ref>] [-o <mode>]
 ```
 
 Aliases: `windows`
@@ -512,10 +613,10 @@ Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `none`
 
 ### `projmux describe pane`
 
-Describe one Pane resource; with no selector inside tmux, the active Pane
+Describe one Pane resource; inside tmux a reference resolves within the active Project and no selector means the active Pane
 
 ```
-projmux describe pane
+projmux describe pane [<ref>] [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [-o <mode>]
 ```
 
 Aliases: `panes`
@@ -524,10 +625,10 @@ Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `none`
 
 ### `projmux describe agent`
 
-Describe one Agent resource; with no selector inside tmux, the Agent owning the active Pane
+Describe one Agent resource; inside tmux a reference resolves within the active Project and no selector means the Agent owning the active Pane
 
 ```
-projmux describe agent
+projmux describe agent [<ref>] [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [-o <mode>]
 ```
 
 Aliases: `agents`
@@ -592,8 +693,8 @@ Move the current client to a live resource
 
 ```
 projmux focus project <ref>
-projmux focus window <ref> --project <ref>
-projmux focus pane <ref> --project <ref> --window <ref>
+projmux focus window <ref> {--project <ref> | -p <ref>}
+projmux focus pane <ref> {--project <ref> | -p <ref>} {--window <ref> | -w <ref>}
 ```
 
 Subcommands:
@@ -601,8 +702,8 @@ Subcommands:
 | Route | Summary |
 | --- | --- |
 | [`projmux focus project`](#projmux-focus-project) | Move the current client to an already-live Project; never materializes |
-| [`projmux focus window`](#projmux-focus-window) | Move the current client to an already-live Window; never materializes |
-| [`projmux focus pane`](#projmux-focus-pane) | Move the current client to an already-live Pane; never materializes |
+| [`projmux focus window`](#projmux-focus-window) | Move the current client to an already-live Window in an exact live root session; never materializes |
+| [`projmux focus pane`](#projmux-focus-pane) | Move the current client to an already-live Pane in an exact live root session; never materializes |
 
 Canonical spelling: `projmux focus project`, `projmux focus window`, `projmux focus pane`
 
@@ -616,18 +717,18 @@ projmux focus project <ref> [--socket <path>] [--client <tty>] [--json]
 
 ### `projmux focus window`
 
-Move the current client to an already-live Window; never materializes
+Move the current client to an already-live Window in an exact live root session; never materializes
 
 ```
-projmux focus window <ref> --project <ref> [--socket <path>] [--client <tty>] [--json]
+projmux focus window <ref> {--project <ref> | -p <ref>} [--socket <path>] [--client <tty>] [--json]
 ```
 
 ### `projmux focus pane`
 
-Move the current client to an already-live Pane; never materializes
+Move the current client to an already-live Pane in an exact live root session; never materializes
 
 ```
-projmux focus pane <ref> --project <ref> --window <ref> [--socket <path>] [--json]
+projmux focus pane <ref> {--project <ref> | -p <ref>} {--window <ref> | -w <ref>} [--socket <path>] [--json]
 ```
 
 ## `projmux get`
@@ -635,12 +736,13 @@ projmux focus pane <ref> --project <ref> --window <ref> [--socket <path>] [--jso
 Read Projmux resources by selector
 
 ```
-projmux get projects [--project <ref>] [--selector key=value]... [-o <mode>]
-projmux get windows [--project <ref>] [--window <ref>]... [--selector key=value]... [--all-projects] [-o <mode>]
-projmux get panes [--project <ref>] [--window <ref>]... [--pane <ref>]... [--selector key=value]... [--all-projects] [-o <mode>]
-projmux get agents [--project <ref>] [--window <ref>]... [--selector key=value]... [--all-projects] [-o <mode>]
+projmux get projects [--project <ref> | -p <ref>] [--selector key=value]... [-o <mode>]
+projmux get windows [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]... [--all-projects | -A] [-o <mode>]
+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>] [--window <ref>]... [--pane <ref>]... [--selector key=value]... [-o <mode>]
+projmux get pane [--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 json|none]
 ```
 
 Subcommands:
@@ -648,21 +750,22 @@ Subcommands:
 | Route | Summary |
 | --- | --- |
 | [`projmux get projects`](#projmux-get-projects) | List Project resources |
-| [`projmux get windows`](#projmux-get-windows) | List Window resources; inside tmux defaults to the active Project, and --all-projects lists every Project |
-| [`projmux get panes`](#projmux-get-panes) | List Pane resources; inside tmux defaults to the active Project, and --all-projects lists every Project |
-| [`projmux get agents`](#projmux-get-agents) | List Agent resources; inside tmux defaults to the active Project, and --all-projects lists every Project |
+| [`projmux get windows`](#projmux-get-windows) | List Window resources; inside tmux defaults to the active managed root, and --all-projects lists the whole Registry |
+| [`projmux get panes`](#projmux-get-panes) | List Pane resources; inside tmux defaults to the active managed root, and --all-projects lists the whole Registry |
+| [`projmux get agents`](#projmux-get-agents) | List Agent resources; 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 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 snapshots`, `projmux get pane`
 
 ### `projmux get projects`
 
 List Project resources
 
 ```
-projmux get projects
+projmux get projects [--project <ref> | -p <ref>] [--selector key=value]... [-o <mode>]
 ```
 
 Aliases: `project`
@@ -671,10 +774,10 @@ Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `none`
 
 ### `projmux get windows`
 
-List Window resources; inside tmux defaults to the active Project, and --all-projects lists every Project
+List Window resources; inside tmux defaults to the active managed root, and --all-projects lists the whole Registry
 
 ```
-projmux get windows [--project <ref>] [--window <ref>]... [--selector key=value]... [--all-projects] [-o <mode>]
+projmux get windows [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]... [--all-projects | -A] [-o <mode>]
 ```
 
 Aliases: `window`
@@ -683,26 +786,76 @@ Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `none`
 
 ### `projmux get panes`
 
-List Pane resources; inside tmux defaults to the active Project, and --all-projects lists every Project
+List Pane resources; inside tmux defaults to the active managed root, and --all-projects lists the whole Registry
 
 ```
-projmux get panes [--project <ref>] [--window <ref>]... [--pane <ref>]... [--selector key=value]... [--all-projects] [-o <mode>]
+projmux get panes [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [--all-projects | -A] [-o <mode>]
 ```
 
 Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `none`
 
 ### `projmux get agents`
 
-List Agent resources; inside tmux defaults to the active Project, and --all-projects lists every Project
+List Agent resources; inside tmux defaults to the active managed root, and --all-projects lists the whole Registry
 
 ```
-projmux get agents [--project <ref>] [--window <ref>]... [--selector key=value]... [--all-projects] [-o <mode>]
+projmux get agents [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--selector key=value]... [--all-projects | -A] [-o <mode>]
 ```
 
 Aliases: `agent`
 
 Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `none`
 
+### `projmux get runtime`
+
+List every tmux Session, Window, and Pane on one exact server with its attribution
+
+```
+projmux get runtime sessions [--socket <name> | --socket-path <absolute>] [-o json|none]
+projmux get runtime windows [--socket <name> | --socket-path <absolute>] [-o json|none]
+projmux get runtime panes [--socket <name> | --socket-path <absolute>] [-o json|none]
+```
+
+Subcommands:
+
+| Route | Summary |
+| --- | --- |
+| [`projmux get runtime sessions`](#projmux-get-runtime-sessions) | List every tmux session on one exact server with its attribution |
+| [`projmux get runtime windows`](#projmux-get-runtime-windows) | List every tmux window on one exact server with its attribution |
+| [`projmux get runtime panes`](#projmux-get-runtime-panes) | List every tmux pane on one exact server with its attribution |
+
+Canonical spelling: `projmux get runtime sessions`, `projmux get runtime windows`, `projmux get runtime panes`
+
+#### `projmux get runtime sessions`
+
+List every tmux session on one exact server with its attribution
+
+```
+projmux get runtime sessions [--socket <name> | --socket-path <absolute>] [-o json|none]
+```
+
+Output modes (`-o`): `json`, `none`
+
+#### `projmux get runtime windows`
+
+List every tmux window on one exact server with its attribution
+
+```
+projmux get runtime windows [--socket <name> | --socket-path <absolute>] [-o json|none]
+```
+
+Output modes (`-o`): `json`, `none`
+
+#### `projmux get runtime panes`
+
+List every tmux pane on one exact server with its attribution
+
+```
+projmux get runtime panes [--socket <name> | --socket-path <absolute>] [-o json|none]
+```
+
+Output modes (`-o`): `json`, `none`
+
 ### `projmux get notifications`
 
 List pending notification rows
@@ -728,7 +881,7 @@ Aliases: `snapshot`
 Read one Pane resource; with no selector inside tmux, the active Pane
 
 ```
-projmux get pane [--current] [--project <ref>] [--window <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>]
 ```
 
 Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `none`
@@ -903,23 +1056,33 @@ projmux quit [--yes|--force]
 Preview or repair Registry and exact tmux resource drift
 
 ```
-projmux reconcile resources [--dry-run] [--socket <name> | --socket-path <absolute>] [-o json]
+projmux reconcile resources [--dry-run] [--materialize-project <name|uid:uid>] [--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]
 ```
 
 Subcommands:
 
 | Route | Summary |
 | --- | --- |
-| [`projmux reconcile resources`](#projmux-reconcile-resources) | Preview or repair safe Registry and tmux UID, owner, and runtime drift on one exact socket |
+| [`projmux reconcile resources`](#projmux-reconcile-resources) | Preview or repair exact anchor-aware Registry and tmux topology on one exact socket |
+| [`projmux reconcile registry`](#projmux-reconcile-registry) | Plan Registry state-loss recovery with zero writes, then restore one explicitly named verified source |
 
-Canonical spelling: `projmux reconcile resources`
+Canonical spelling: `projmux reconcile resources`, `projmux reconcile registry`
 
 ### `projmux reconcile resources`
 
-Preview or repair safe Registry and tmux UID, owner, and runtime drift on one exact socket
+Preview or repair exact anchor-aware Registry and tmux topology on one exact socket
+
+```
+projmux reconcile resources [--dry-run] [--materialize-project <name|uid:uid>] [--socket <name> | --socket-path <absolute>] [-o json]
+```
+
+### `projmux reconcile registry`
+
+Plan Registry state-loss recovery with zero writes, then restore one explicitly named verified source
 
 ```
-projmux reconcile resources [--dry-run] [--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]
 ```
 
 ## `projmux rebind`
@@ -927,7 +1090,7 @@ projmux reconcile resources [--dry-run] [--socket <name> | --socket-path <absolu
 Rebind a Project to a new absolute root without moving files
 
 ```
-projmux rebind project [<ref>] --root <absolute-path>
+projmux rebind project [<ref>] [--project <ref> | -p <ref>] --root <absolute-path>
 ```
 
 Subcommands:
@@ -943,7 +1106,7 @@ Canonical spelling: `projmux rebind project`
 Rewrite one Project spec.root; no filesystem move, no heuristic uid merge
 
 ```
-projmux rebind project [<ref>] --root <absolute-path>
+projmux rebind project [<ref>] [--project <ref> | -p <ref>] --root <absolute-path>
 ```
 
 ## `projmux rename`
@@ -951,10 +1114,10 @@ projmux rebind project [<ref>] --root <absolute-path>
 Rename a Projmux resource metadata.name
 
 ```
-projmux rename project [<ref>] --name <name>
-projmux rename window [<ref>] --name <name> [--project <ref>]
-projmux rename pane [<ref>] --name <name> [--project <ref>] [--window <ref>]...
-projmux rename agent [<ref>] --name <name> [--project <ref>] [--window <ref>]...
+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>]...
 ```
 
 Subcommands:
@@ -962,9 +1125,9 @@ Subcommands:
 | Route | Summary |
 | --- | --- |
 | [`projmux rename project`](#projmux-rename-project) | Rename a Projmux Project resource; with no selector inside tmux, the active Project |
-| [`projmux rename window`](#projmux-rename-window) | Rename a Projmux Window resource; with no selector inside tmux, the active Window |
-| [`projmux rename pane`](#projmux-rename-pane) | Rename a Projmux Pane resource; with no selector inside tmux, the active Pane; does not change tmux pane_title |
-| [`projmux rename agent`](#projmux-rename-agent) | Rename an Agent stable resource name without changing its topic, provider, or managed Pane |
+| [`projmux rename window`](#projmux-rename-window) | Rename a Projmux Window resource; inside tmux a reference resolves within the active Project or ControlSession and no selector means the active Window |
+| [`projmux rename pane`](#projmux-rename-pane) | Rename a Projmux Pane resource; inside tmux a reference resolves within the active Project or ControlSession and no selector means the active Pane; does not change tmux pane_title |
+| [`projmux rename agent`](#projmux-rename-agent) | Rename an Agent stable resource name within the active Project or ControlSession without changing its topic, provider, or managed Pane |
 
 Canonical spelling: `projmux rename project`, `projmux rename window`, `projmux rename pane`, `projmux rename agent`
 
@@ -973,37 +1136,37 @@ Canonical spelling: `projmux rename project`, `projmux rename window`, `projmux
 Rename a Projmux Project resource; with no selector inside tmux, the active Project
 
 ```
-projmux rename project
+projmux rename project [<ref>] [--project <ref> | -p <ref>] --name <name>
 ```
 
 Aliases: `projects`
 
 ### `projmux rename window`
 
-Rename a Projmux Window resource; with no selector inside tmux, the active Window
+Rename a Projmux Window resource; inside tmux a reference resolves within the active Project or ControlSession and no selector means the active Window
 
 ```
-projmux rename window
+projmux rename window [<ref>] --name <name> [--project <ref> | -p <ref>]
 ```
 
 Aliases: `windows`
 
 ### `projmux rename pane`
 
-Rename a Projmux Pane resource; with no selector inside tmux, the active Pane; does not change tmux pane_title
+Rename a Projmux Pane resource; inside tmux a reference resolves within the active Project or ControlSession and no selector means the active Pane; does not change tmux pane_title
 
 ```
-projmux rename pane
+projmux rename pane [<ref>] --name <name> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]...
 ```
 
 Aliases: `panes`
 
 ### `projmux rename agent`
 
-Rename an Agent stable resource name without changing its topic, provider, or managed Pane
+Rename an Agent stable resource name within the active Project or ControlSession without changing its topic, provider, or managed Pane
 
 ```
-projmux rename agent
+projmux rename agent [<ref>] --name <name> [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]...
 ```
 
 Aliases: `agents`
@@ -1018,26 +1181,26 @@ projmux resources
 
 ## `projmux restore`
 
-Preview a saved session snapshot restore (--dry-run only in this release)
+Project a saved snapshot into one exact closed Project desired state
 
 ```
-projmux restore snapshot --dry-run [--session <name>]
+projmux restore snapshot --session <name> [--project <ref> | -p <ref>] [--dry-run | --yes] [--client <tmux-client>]
 ```
 
 Subcommands:
 
 | Route | Summary |
 | --- | --- |
-| [`projmux restore snapshot`](#projmux-restore-snapshot) | Preview a saved session snapshot restore; --dry-run is required |
+| [`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`
 
-Preview a saved session snapshot restore; --dry-run is required
+Project a saved snapshot into one exact closed Project desired state
 
 ```
-projmux restore snapshot --dry-run [--session <name>]
+projmux restore snapshot --session <name> [--project <ref> | -p <ref>] [--dry-run | --yes] [--client <tmux-client>]
 ```
 
 ## `projmux runtime`
@@ -1046,6 +1209,7 @@ Manage the live and ephemeral tmux runtime inventory
 
 ```
 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
@@ -1057,12 +1221,13 @@ Subcommands:
 | Route | Summary |
 | --- | --- |
 | [`projmux runtime sessions`](#projmux-runtime-sessions) | Pick a live or ephemeral tmux session |
+| [`projmux runtime diagnostics`](#projmux-runtime-diagnostics) | Inspect every tmux object on one exact server, with attribution and safe actions |
 | [`projmux runtime attach`](#projmux-runtime-attach) | Attach a live or ephemeral runtime without Project identity |
 | [`projmux runtime stop`](#projmux-runtime-stop) | Terminate live tmux sessions by tagged selection |
 | [`projmux runtime tag`](#projmux-runtime-tag) | Manage the ephemeral tagged session selection |
 | [`projmux runtime prune`](#projmux-runtime-prune) | Trim old ephemeral tmux sessions |
 
-Canonical spelling: `projmux runtime sessions`, `projmux runtime attach`, `projmux runtime stop`, `projmux runtime tag`, `projmux runtime prune`
+Canonical spelling: `projmux runtime sessions`, `projmux runtime diagnostics`, `projmux runtime attach`, `projmux runtime stop`, `projmux runtime tag`, `projmux runtime prune`
 
 ### `projmux runtime sessions`
 
@@ -1072,6 +1237,14 @@ Pick a live or ephemeral tmux session
 projmux runtime sessions
 ```
 
+### `projmux runtime diagnostics`
+
+Inspect every tmux object on one exact server, with attribution and safe actions
+
+```
+projmux runtime diagnostics [--socket <name> | --socket-path <absolute>] [--ui=popup|sidebar]
+```
+
 ### `projmux runtime attach`
 
 Attach a live or ephemeral runtime without Project identity
@@ -1260,4 +1433,3 @@ Print the current version
 projmux version
 projmux --version
 ```
-