projmux 0.8.4 → 0.10.0

package/docs/cli.md

@@ -23,15 +23,16 @@ projmux <command> [args...]
 | `attention` | View and manage live tmux pane attention state. |
 | `attach` | Open tmux lifecycle entry helpers. |
 | `current` | Resolve the active tmux pane path. |
-| `doctor` | Diagnose runtime dependencies. |
+| `doctor` | Run read-only runtime and integration diagnostics. |
+| `diagnostics` | Read the private bounded operational event log. |
 | `focus` | Switch the active client to a session/window/pane target. |
-| `init` | Preview or apply supported terminal key delivery mappings. |
 | `kill` | Terminate tagged tmux sessions. |
 | `notify` | Manage the pending AI notify queue (push/list/ack/reconcile). |
 | `pin` | Manage pinned project directories. |
 | `preview` | Manage persisted tmux preview selection. |
 | `prune` | Trim stale tmux lifecycle state and inspect preserved session snapshots. |
 | `quit` | Quit the app-owned projmux tmux runtime. |
+| `resources` | Inspect live Linux/tmux Project → Window → Pane CPU/RSS attribution. |
 | `sessions` | Pick and open an existing tmux session. |
 | `session-popup` | Read tmux popup preview state. |
 | `settings` | Configure projmux. |
@@ -45,7 +46,7 @@ projmux <command> [args...]
 | `update` | Check installer-aware GitHub release update status. |
 | `upgrade` | Self-update via `go install`. |
 | `welcome` | Print the shell onboarding guide again. |
-| `usage` | Report AI token usage across 5h and weekly windows. |
+| `usage` | Report AI usage across fixed windows, context, and named quota buckets. |
 | `version` | Print the current version. |
 
 ## switch
@@ -62,8 +63,9 @@ sub-verbs are entry hooks invoked by tmux keybindings (e.g.
 `sidebar-focus` is wired to the sidebar's focus binding so navigation keeps
 the active session in sync).
 
-Settings > Labs remains available for experimental settings, but picker backend
-selection has been retired. The native picker is always used.
+Settings > Labs remains available for experimental settings, but picker
+selection/source rows have been retired. The native picker is always used, and
+there is no picker selection configuration or migration behavior.
 
 ## setup
 
@@ -81,31 +83,31 @@ key map. Default `--timeout` is `5s`. Run it outside tmux after trying
 Settings > Keybindings edits in-app action aliases; terminal delivery
 diagnostics stay in this CLI flow.
 
-## init
+## setup terminal
 
 ```
-projmux init [terminal] [--apply | --dry-run] [--config <path>]
-             [--allow-symlink]
+projmux setup terminal [terminal] [--apply] [--config <path>]
+                              [--allow-symlink]
 ```
 
 Previews or applies terminal-specific key delivery mappings for supported
 terminals when `projmux setup` reports swallowed shortcuts. When `terminal` is
 omitted, autodetects from `$TERM_PROGRAM`/`$TERMINAL_EMULATOR`.
-Known terminals: `ghostty`, `windows-terminal`. Default is dry-run; pass
-`--apply` to write (timestamped `.bak.<timestamp>` is created). Refuses to
+Known terminals: `ghostty`, `windows-terminal`. Default is a read-only
+preview; pass `--apply` to write (timestamped `.bak.<timestamp>` is created). Refuses to
 write through a symlink unless `--allow-symlink` is passed (dotfiles repos).
 `--config <path>` overrides the candidate list when the adapter has more
 than one default location (Ghostty `config` vs `config.ghostty`). If setup
-shows every key arriving, skip init.
+shows every key arriving, skip terminal remediation.
 
 ## doctor
 
 ```
-projmux doctor [--json]
-projmux doctor --install-missing [--dry-run] [--include-optional]
+projmux doctor [--json] [--section deps|runtime|integrations|session-state|logs] [--verbose]
 ```
 
-Runs a dependency check: `tmux ≥ 3.4`, `git`, `stty` (POSIX only), and
+Runs read-only diagnostics, including a dependency check for `tmux ≥ 3.4`,
+`git`, `stty` (POSIX only), and
 `kubectl` (optional), then reports read-only AI notify integration diagnostics
 for Codex hooks, Claude Code hooks, and the tmux bell
 fallback. AI notify integration statuses are `installed`, `missing`, or
@@ -115,23 +117,132 @@ diagnostics for saved agent panes, including `available`, `stale`, or
 `unavailable` status plus confidence, source, updated-at, and the affected
 snapshot/window/pane.
 
-Exit code `0` even when optional deps or AI notify integrations are missing;
-non-zero only when a required dep is missing or stale. `--json` emits a
-machine-readable object with `dependencies`, `ai_notify_integrations`, and
-`session_state_resume`; the default is the human report with suggested install
-commands per platform, AI integration install/remove/dry-run commands, and
-Session State resume metadata health. `--install-missing` is explicit opt-in
-and runs generated install commands only for missing or stale required
-dependencies. `--dry-run` prints those commands without executing them.
-`--include-optional` also includes optional missing dependencies such as
-`kubectl` when an install command is available. Install flags cannot be combined
-with `--json`. Doctor does not diagnose terminal key delivery; use `projmux
-setup` for that.
-
-`Settings > Notifications > Delivery sources` shows active Codex hooks, Claude,
-Antigravity manual hook ingest, and tmux statuses, conflicts, config paths, and
-copyable AI integration commands where available. Settings does not install or
-remove external Codex, Claude, Antigravity, or tmux notify wiring.
+Session State preview and doctor report the resume source captured on the pane.
+Live `hook`/`session-id` metadata is high confidence; DB-validated Antigravity
+`antigravity-last-conversation` and `antigravity-conversation-metadata` picker
+sources are medium confidence; legacy `antigravity-history` is low confidence.
+Disk discovery never lowers or overwrites an already captured live source.
+
+The default text report shows per-section summaries plus failing or warning
+items. `--verbose` adds successful checks and complete typed detail, including
+versions, paths, confidence/source metadata, and displayed remediation.
+`--section` projects the same inventory used by text and JSON: `deps` selects
+dependencies, `integrations` selects AI notify integrations, and
+`session-state` selects resume metadata plus retention guidance. `runtime`
+selects the fixed `tmux` backend, an actual one-second read-only probe of the
+app socket, and generated-versus-live config digest state. `logs` selects the
+state/log/journal presence, private permissions and metadata-only writability
+checks plus a bounded aggregate of recent safe operational error codes. These
+sections expose only closed status codes and counts: no path, socket name,
+routing identity, message, config content, or argv is rendered.
+The recent-error count is the size of the newest 20-record window, not a
+lifetime total; `logs.recent-errors.bounded` means older errors were omitted.
+The probe captures at most 4 KiB, generated config inspection reads at most
+1 MiB, and the journal seam reads at most 5 MiB.
+Symlinks and non-regular inputs are rejected without following or blocking on
+them. On Windows, POSIX mode bits cannot establish ACL privacy, so otherwise
+valid paths report the closed `privacy-unverified` warning rather than a false
+private/insecure classification, followed by a separate metadata-only `ready`
+or `not-writable` finding; Doctor never changes ACLs.
+
+JSON reports have integer `schema_version: 2`. An unfiltered report retains the
+existing typed `dependencies`, `ai_notify_integrations`,
+`session_state_resume`, and `session_state_prune` detail and adds ordered
+`runtime` and `logs` finding arrays. Every finding has closed `severity`,
+stable `code`, and closed `remediation`; bounded aggregates may add `count`
+and `safe_codes`. A filtered report contains only the selected typed field(s).
+`--verbose` is accepted with `--json` but does not change JSON fields or values.
+
+Default and verbose text exit non-zero only when their projected dependency
+inventory contains a required missing or stale dependency. A non-`deps`
+section exits `0`. JSON preserves its successful exit after emitting a report,
+even when required dependencies are missing or stale.
+
+Doctor is read-only for every flag combination. It never creates or repairs
+state/log paths, installs packages, runs displayed remediation, changes
+terminal or tmux state, generates/applies config, migrates files, or writes
+operational-log outcomes. Missing, malformed, or permission-denied journals
+degrade to typed log findings without failing the command. The removed `--install-missing`,
+`--include-optional`, and Doctor `--dry-run` mutation flags fail as unknown
+usage with an exact instruction to remove the flag and run displayed
+remediation explicitly outside Doctor; they are never ignored. Doctor does not
+diagnose terminal key delivery; use `projmux setup` for that.
+
+JSON migration: consumers must switch on `schema_version` before decoding.
+Version 2 changes the previously empty/reserved `runtime` and `logs` arrays to
+the typed finding shape above; field meanings inside the version 1 dependency,
+integration, and Session State inventories are unchanged. Consumers that only
+understand version 1 must reject version 2 rather than decoding the new arrays
+as the old empty placeholder shape.
+
+`Settings > Notifications > Delivery sources` shows active Codex, Claude, and
+Antigravity hooks plus tmux statuses, conflicts, config paths, and
+copyable AI integration commands where available. Its summary/detail also shows
+whether `PROJMUX_NOTIFY_HOOK` overrides the built-in desktop sender. Settings
+does not install or remove external Codex, Claude, Antigravity, or tmux notify
+wiring. Pending in-app queue rows remain owned by the statusbar/sidebar rather
+than a standalone Settings row.
+
+## diagnostics
+
+```
+projmux diagnostics log [--tail N] [--json]
+                        [--level info|error] [--component NAME] [--path]
+projmux diagnostics report [--output <path>]
+```
+
+Reads the local operational event journal through the same tolerant JSONL
+reader used by every output mode. The default text view shows the newest 50
+valid records. `--tail N` changes that bound, `--json` emits the selected
+records as JSONL, and `--level` / `--component` filter before tailing. `--path`
+prints the resolved path without creating or reading the log.
+
+Successful state-changing top-level commands produce one `info` outcome, and
+every top-level command error produces one `error` outcome. Successful
+high-frequency/read-only commands such as `status`, `ai ingest`, `attention
+arm`/`clear`/`window`, `tmux autosave-session-state`, `window record`, and
+successful `diagnostics log` views do not produce an event. Errors from those
+automatic hook/poll paths still produce one safe `error` outcome. Successful
+direct command help and explicit `--dry-run` preview modes also remain
+read-only and do not produce an event. Journal failures are a best-effort side
+channel and never change command output or exit status. See
+[operational-diagnostics.md](operational-diagnostics.md) for the file,
+retention, concurrency, and privacy contracts.
+
+Session create/attach/switch/kill and `tmux apply` use correlated
+`lifecycle.start`/`lifecycle.outcome` records instead of a duplicate generic
+top-level outcome. The text and JSONL views expose only the closed safe
+`operation` and optional `code` enums; session names, socket paths, tmux
+targets, subprocess argv, and generated configuration are never recorded.
+
+`diagnostics report` is the explicit consent boundary for creating one local
+private `tar.gz` support archive. The invocation first prints a redacted
+destination label, the complete included/omitted entry list, stable omission reasons, report
+schema, and redaction mode; the first parent/temp/archive write happens only
+after that preview is successfully written. `--output` selects the local
+destination. Without it, the command uses a timestamped archive in the current
+directory. Existing destinations are never replaced.
+
+The archive contains `manifest.json`, safe projmux version/platform/backend
+metadata, a redacted projection of Doctor JSON schema version 2,
+config presence states (never values), up to 50 recent errors from the existing
+bounded operations reader, and count-only AI ingest diagnostics. Paths,
+session/window/pane/thread/routing identifiers, run IDs, tool/version output,
+commands, guidance, reasons, and other free text are field-scoped hashes unless they
+match a closed diagnostic enum/static-name allowlist. Raw config/environment
+values, argv/stdin, prompts, notification text, pane output, transcripts, and
+hook payloads are never collected. Missing, corrupt, or unreadable sources are
+recorded as stable manifest omissions. Report collection does not repair source
+permissions, migrate hooks, append an operational outcome, contact a network,
+upload, create an issue, or run in the background; only the explicitly selected
+output parent/temp/archive can be written.
+
+The redacted Doctor projection keeps `schema_version`, closed runtime/log
+finding enums, and structural/count
+numbers as numbers. Numeric routing fields such as `window_index` and
+`pane_index` become field-scoped hash strings under `default-hash-v1`; consumers
+must treat this support projection as redacted evidence rather than decoding it
+back into the unredacted Doctor Go types.
 
 ## focus
 
@@ -249,23 +360,67 @@ Authoritative AI token usage. See [usage-tracking.md](usage-tracking.md)
 for adapter detail.
 
 ```
-projmux usage [--model codex|claude|antigravity|all] [--window 5h|weekly|all]
+projmux usage [--model codex|claude|antigravity|all] [--window 5h|weekly|context|quota|all]
               [--json] [--force|-f]
 ```
 
-Renders a tab-aligned `MODEL WINDOW PCT RESETS_AT STALE` table; appends a
+Renders a tab-aligned `MODEL WINDOW PCT RESETS_AT RESET_IN STALE` table; appends a
 backoff note when an adapter is in 429 cooldown. `--force` clears any
 active backoff and bypasses the per-adapter throttle floor (Claude `5m`,
 Codex shares the global `30s`). `--json` emits the snapshot array; when
 backoff is active the wrapper `{snapshots, backoff}` object is emitted
 instead.
 
-Antigravity has no 5-hour/weekly quota contract, so it is surfaced
-`context-window-only`: the adapter emits a single `context` window row
-(context-window fullness, no `RESETS_AT`) sourced from the latest
-statusline `context_window` seen via hook ingest. `--model antigravity`
-renders that row; in the HUD it shows as `Antigravity ctx [bar] N%`
-alongside the Claude/Codex quota bars.
+Claude keeps the canonical aggregate `5h` and `weekly` rows and projects each
+valid typed upstream `limits[]` entry as a named `quota/<exact group>` row.
+Model-scoped rows append the exact upstream model display identity in text
+output; terminal controls are escaped and the visible label is bounded without
+normalizing the stored identity. JSON preserves the typed named-quota metadata,
+including nullable scope/model ID/surface, reset, `updated_at`, and `stale`.
+These percent-only rows never synthesize token counts. A malformed limits block
+fails that adapter refresh so the prior complete Claude slice remains visible;
+a valid aggregate-only response replaces and removes obsolete named rows.
+
+Antigravity emits official account rows labelled
+`quota/<upstream bucket ID>`. Conversation-local context remains private
+hook/notify diagnostic metadata and legacy cached context rows are suppressed
+from text and JSON output. `--window quota` selects named account rows; opaque
+IDs such as `weekly` are not aliases for the fixed `weekly` window. Used
+percent is `100 * (1 - remaining_fraction)`. `--window context` remains
+accepted for compatibility and returns no Usage rows.
+`reset_time` and optional `reset_in_seconds` are preserved independently,
+including the distinction between absent and explicit zero. Invalid,
+disabled, missing, or empty quota data degrades without reinterpreting the
+private conversation context diagnostic.
+
+## resources
+
+```
+projmux resources
+```
+
+Opens the native, read-only Resource Inspector. It samples only while this
+interactive process is alive, paints `warming` immediately, then refreshes at
+a non-overlapping two-second cadence. Right or Enter drills Project → Window →
+Pane → Pane detail; Left returns (and is a no-op at the root), while Esc closes
+the popup at every depth. Search matches the current scope's display name and
+stable tmux id. Tab cycles CPU, Memory, and Name sorting; Ctrl-R requests an
+immediate refresh. A plain `r` remains search input.
+
+CPU list values are host-capacity share; pane detail also shows
+core-equivalent CPU. Project and window rows count panes, while pane rows count
+the attributed processes. Pane rows and detail share the resolved pane identity
+and label the tmux current command, PID/SID, pane id, and TTY separately. Memory
+is explicitly an RSS sum (shared pages can be counted more than once) plus its
+host ratio. `Unassigned`,
+`Shared / ambiguous`, and non-drillable `Other / unattributed` remain explicit,
+as do warming, partial, unavailable, unknown, and overage states. No process
+command list, mutation, history, graph, daemon, persistence, or Session State
+telemetry is created. Linux/tmux provides attribution; unsupported platforms
+show an unavailable reason rather than zero metrics.
+
+This is distinct from `projmux status resources`, which remains the short
+host-only statusbar renderer.
 
 ## status
 
@@ -289,9 +444,14 @@ projmux status resources
   `~/.cache/tmux/kube-segment-<session>.txt` first (TTL governed by
   `TMUX_KUBE_CACHE_TTL`, default `5s`). Picks up a per-session
   `KUBECONFIG` from `${XDG_RUNTIME_DIR:-~/.cache}/kube-sessions/<session>.yaml`.
-- `usage` — HUD-style `Claude (Nm) 5h [bar] N% · weekly [bar] N%   Codex 5h
-  [bar] N% · weekly [bar] N%`. Degrades through six tiers as `--max-width`
-  shrinks. Triggers an opportunistic, throttled refresh (per-adapter
+- `usage` — HUD-style provider blocks containing only official `5h` and
+  `weekly` windows. Antigravity's exact `quota/gemini-weekly` snapshot is
+  projected as `weekly` without changing its cached identity; other named
+  quotas and context never consume status width. Claude typed `limits[]`
+  named/model rows are likewise excluded, so only its aggregate `5h` and
+  `weekly` rows reach the status line. Narrow tiers keep one primary window per
+  provider (`5h`, otherwise `weekly`) before hard truncation.
+  Triggers an opportunistic, throttled refresh (per-adapter
   throttle, `30s` floor) so a stale cache self-heals.
 - `notify` — newest-first HUD block with project, state, optional agent, text,
   age, and `+<extras>`. Window/pane ids remain routable metadata but are not
@@ -300,7 +460,11 @@ projmux status resources
 - `resources` — macOS/Linux/WSL aggregate `CPU N%  MEM N%`. Linux uses
   `/proc/stat` and `/proc/meminfo`; macOS uses native Mach host statistics.
   CPU needs two invocations to establish a delta and renders `--` for the first
-  sample. WSL reports the Linux guest/VM view. Unsupported platforms and
+  sample. CPU independently warns at 70–89% and becomes bold critical at 90% or
+  above; memory independently warns at 75–89% and becomes bold critical at 90%
+  or above. Normal and unavailable values use the secondary status-text role.
+  These values are host-scoped rather than pane/window/project/session
+  attribution. WSL reports the Linux guest/VM view. Unsupported platforms and
   unreadable system metrics produce no error output.
 
 ## statusbar
@@ -320,8 +484,14 @@ non-specialized placeholders and no-op. `session` opens the existing-session
 popup; `pwd` shows the current pane path in a native-framed display-only
 popup; `kube` and `git` open the project switcher popup;
 `settings` toggles the settings popup for the tmux client; `usage` opens the
-detailed `projmux usage` table popup; `notify` focuses and acks the newest
-actionable queue target. The internal `usage-refresh` shortcut entry point
+detailed cached account-usage popup. Legacy context rows are suppressed and
+named quotas retain exact identity/reset/freshness values. Claude model-scoped
+rows distinguish the exact group and model display identity with bounded,
+terminal-safe labels; JSON retains their full typed metadata. `USED`, `LIMIT`,
+and `LEFT` appear together only when at least one displayed row has real
+absolute counts; percent-only datasets omit those columns rather than
+synthesizing counts.
+`notify` focuses and acks the newest actionable queue target. The internal `usage-refresh` shortcut entry point
 runs the same throttled, per-adapter collection policy as `status usage` and
 then reopens the display-only usage popup from cache.
 `MouseDown1Status` errors are
@@ -352,7 +522,7 @@ supplied window.
 ## ai
 
 ```
-projmux ai split    [--agent <claude|codex|antigravity|shell|selective|resume>] [--force-agent] [right|down] [-- <extra-arg>...]
+projmux ai split    [--agent <claude|codex|antigravity|shell|selective|resume>] [--force-agent] [--print-pane-id] [right|down] [-- <extra-arg>...]
 projmux ai picker   [--inside] [--shell] [--resume] <right|down>
 projmux ai settings
 projmux ai status   set <thinking|waiting|idle> [--pane <id>]
@@ -360,11 +530,12 @@ projmux ai notify   <reset|notify> [--pane <id>]
 projmux ai watch-title [--pane <id>]
 projmux ai ingest   codex-hook < payload.json
 projmux ai ingest   claude-hook < payload.json
-projmux ai ingest   antigravity-hook < payload.json
+projmux ai ingest   antigravity-hook [--event <PreInvocation|PostInvocation|PostToolUse|Stop|Statusline>] < payload.json
 projmux ai ingest   bell --pane <pane_id>
 projmux ai ingest   log [--tail N] [--json] [--path]
 projmux ai integrate codex [--dry-run] [--remove]
 projmux ai integrate claude [--dry-run] [--remove]
+projmux ai integrate antigravity [--dry-run] [--remove]
 projmux ai integrate tmux-bell [--dry-run] [--remove]
 projmux ai topic     ...
 ```
@@ -394,11 +565,41 @@ existing plain shell split. Arguments after `--` are extra arguments appended to
 the resolved `claude`, `codex`, or `agy` executable inside the managed wrapper;
 projmux still sets the context directory, tmux title, AI pane metadata, title
 watcher, and split layout.
-The resume picker lists the newest deduplicated Claude/Codex resume sessions
-for the current project, with `[+ New Session]` pinned first. If there are no
-resume sessions it goes straight to the existing selective picker. Phase 1
-captures the selected `(agent, resume id)` contract but still launches a fresh
-split; actual `claude --resume` / `codex resume` wiring is reserved for Phase 2.
+
+Automation callers can add `--print-pane-id` to an explicit direct
+`--agent claude|codex|antigravity|shell` launch. On success, stdout contains
+exactly the new `%N` pane id followed by one newline. The value comes directly
+from tmux's existing
+`split-window -P -F '#{pane_id}'` result. If tmux returns no valid pane id, the
+command fails non-zero with tmux-specific guidance and writes no
+success value. Without `--print-pane-id`, successful split invocations keep the
+existing empty-stdout behavior.
+
+`--print-pane-id` is not available for the saved default mode or for
+`--agent selective|resume`, because those paths may open a picker and launch
+only after a later user selection. Those combinations fail before opening a
+picker or creating a pane. Arguments after `--` keep their existing argv-tail
+meaning when the flag is used with a concrete AI agent.
+The resume picker lists the newest deduplicated Claude, Codex, and Antigravity
+resume sessions for the current project, with `[+ New Session]` pinned first.
+If there are no resume sessions it goes straight to the existing selective
+picker. Selecting a row directly starts `claude --resume <id>`,
+`codex resume <id>`, or `agy --conversation <uuid>`.
+
+Live Antigravity hook/session-state resume metadata remains a separate,
+high-confidence lane; it is not enumerated from disk by the picker. Within the
+picker's disk discovery, source order is the workspace-to-latest-UUID mapping
+in `cache/last_conversations.json`, workspace-bearing summarized rows in
+`cache/conversation_metadata.json`, then legacy `history.jsonl`. The two cache
+sources require a normalized UUID and an exact regular
+`conversations/<uuid>.db`; only DB existence and mtime are read. SQLite content,
+prompt/transcript text, sidecars, symlinks, and arbitrary paths are never used.
+The cache is only the history floor exposed by upstream v1.1.12, not a complete
+conversation history. Cache rows have medium confidence and blank turns;
+`last_conversations` uses a short UUID title, while metadata uses only a safe
+summary. Legacy history is low confidence. Missing/malformed cache, stale
+missing-DB mappings, workspace-less metadata, and unknown fields degrade
+without failing Claude/Codex or legacy discovery.
 Settings > AI Settings > Enabled agents controls Claude/Codex/Antigravity launch
 visibility. Disabled agents are hidden from the selective picker and from the
 default-mode picker. A saved default that later becomes disabled fails clearly
@@ -467,27 +668,75 @@ precedence over catalog `action` for known Claude events too; for example a
 noisy notify event can be made state-only or quiet without changing installed
 Claude hook commands.
 
-`ingest antigravity-hook` is the manual hook/statusline entrypoint for
-Antigravity CLI `agy` payloads observed in the Phase 0b smoke. Projmux does not
-provide `projmux ai integrate antigravity`, does not install Antigravity hooks,
-and does not mutate Antigravity user config. If users wire Antigravity manually,
-the hook/statusline command should call an absolute `projmux` path or run from a
-known cwd because relative command paths failed smoke.
-
-The default known Antigravity catalog is intentionally narrow:
-`PostInvocation` is quiet/log-only, `Stop` is notify, and `Statusline` is notify
-only when manually wired and `tool_confirmation_pending=true`. `Stop` with
-`error` or a non-normal `terminationReason` pushes a critical error row; `Stop`
-without those error signals pushes an info completion row. Accepted identity
-fields include `conversationId`/`conversation_id`, `cwd` or `workspace.path`,
-`transcriptPath`, `fullyIdle`, `agent_state`, and `context_window`.
+`ingest antigravity-hook` is the hook/statusline entrypoint for
+Antigravity CLI `agy` payloads. Official v1.1.12 hook commands must pass their
+event identity explicitly, for example
+`projmux ai ingest antigravity-hook --event Stop`; the official stdin payload
+does not carry an event field. The explicit selector is authoritative, while
+payload `eventName` and its legacy aliases remain fallback inputs for existing
+manual wiring. `projmux ai integrate antigravity` manages exactly the named
+`projmux` entry in `~/.gemini/config/hooks.json` and, separately, exactly the
+`statusLine` member in `~/.gemini/antigravity-cli/settings.json`. The managed
+statusline uses the official v1.1.12 `{type:"command", enabled:true,
+stack_with_default:true}` shape and an absolute direct ingest command whose
+stdout is empty, so the built-in statusline remains visible. It preserves every
+other named entry and unknown JSON value, resolves the running projmux
+executable to a stable absolute path, and supports `--dry-run` and `--remove`.
+An existing unmanaged custom `statusLine` is an actionable conflict and is
+never chained, wrapped, or rewritten. An existing
+unmanaged `projmux` entry, another Antigravity projmux ingest command, malformed
+JSON, symlinks, and read/write permission failures are reported without
+rewriting the file. Doctor and Settings also report a managed entry as `stale`
+when its absolute executable, event/schema wiring, or stdout fallback differs
+from the current plan; the displayed install command refreshes it.
+
+The embedded v1.1.12 catalog contains the five official events `PreToolUse`,
+`PostToolUse`, `PreInvocation`, `PostInvocation`, and `Stop`. The managed entry
+installs `PreInvocation`, `PostInvocation`, `PostToolUse`, and `Stop`, each with
+an explicit `--event`; `PreToolUse` remains disabled because its response can
+change permission policy. `Statusline` remains an explicit statusline selector
+outside that official hook catalog.
+
+`PreInvocation` moves the matched pane to thinking/busy without notifying.
+`PostInvocation` and `PostToolUse` remain quiet bookkeeping paths, with tool
+errors retained in ingest diagnostics. `Stop` keeps the completion/error notify
+classification. Hook stdout is `{}` for the three non-Stop managed events and
+`{"decision":"stop"}` for Stop, including a shell fallback if ingest fails, so
+the hook cannot force continuation or synthesize a permission decision.
+Official statusline `agent_state` values `thinking`, `working`, and `tool_use`
+map to thinking/busy unless the pane already holds a terminal completion or
+approval state; this prevents a late statusline refresh from regressing `Stop`.
+A new `PreInvocation` resets the pane to thinking for the next generation.
+`idle` is quiet and does not clear an existing completion or approval state.
+`tool_confirmation_pending=true` produces a stable-ID,
+deduped approval-required row; false never produces a notification.
+
+The managed JSON is the install source of truth. The command
+`agy -p '/hooks' --output-format json` is a read-only runtime diagnostic for
+confirming loaded event names and sources; projmux never uses `/hooks` output
+to rewrite `hooks.json`.
+
+`workspacePaths` uses the first non-empty path as a cwd matching candidate;
+an absent or empty array does not invent a cwd. Inherited `$TMUX_PANE` remains
+the first pane attribution source. A Stop with non-empty `error`, explicit
+`ERROR`, or a `MAX_STEPS_EXCEEDED` family reason pushes a critical error row.
+`NO_TOOL_CALL`, `MODEL_STOP`, and known normal reasons push an info completion;
+unknown reasons remain info completions with diagnostic metadata rather than
+being promoted to critical. Official camelCase fields retained by the parser
+also include `artifactDirectoryPath`, `modelName`, `invocationNum`,
+`initialNumSteps`, `toolCall`, `stepIdx`, `executionNum`, and `fullyIdle`.
 Antigravity notify metadata uses `agent=antigravity`. Phase 3 session-state
 restore is included: Antigravity ingest stores `conversationId` as pane thread
 metadata for matching and as session-state resume metadata. Restore uses
 `agy --conversation <uuid>` when that id is present and UUID-shaped; otherwise
-session-state preview/doctor render `resume unavailable`. The statusline
-`context_window` value is persisted on ingest and surfaced by the usage HUD
-as a `context-window-only` row (Antigravity has no 5h/weekly quota contract).
+session-state preview/doctor render `resume unavailable`. Structured statusline
+`context_window.used_percentage` is persisted with its conversation id as
+private hook/notify diagnostic metadata and is not surfaced as account usage.
+The official `quota` map is persisted independently and surfaces each valid entry as
+`quota/<exact bucket ID>` with independently retained absolute and relative
+reset values. Bucket IDs are never mapped to `5h`/`weekly`, and account quota
+is never inferred from the conversation-local gauge.
+The earlier string percentage form remains a compatibility fallback.
 Transcript contents are not read.
 
 `ingest bell --pane <pane_id>` is the narrow tmux-bell fallback ingest path.
@@ -664,7 +913,7 @@ projmux tmux popup-switch
 projmux tmux popup-sessions
 projmux tmux popup-preview <session>
 projmux tmux rebalance-panes
-projmux tmux rename-pane <pane> <title>
+projmux tmux rename-pane <pane> <label>
 projmux tmux print-config     [--bin <path>]
 projmux tmux print-app-config [--bin <path>]
 projmux tmux install     [--bin <path>] [--config <path>] [--include <path>]
@@ -675,16 +924,27 @@ projmux tmux apply
 Helpers tmux's keybindings and the install pipeline call into. Modes
 accepted by `popup-toggle` mirror the historical sessionizer surface:
 `session-popup`, `sessionizer`, `sessionizer-sidebar`,
-`notify-sidebar`, `recent-windows`, `ai-split-picker-right`,
+`notify-sidebar`, `recent-windows`, `resource-inspector`, `ai-split-picker-right`,
 `ai-split-picker-down`, `ai-split-resume-right`, `ai-split-resume-down`,
 `ai-split-settings`.
+`rename-pane` sets only the pane-scoped user label
+`@projmux_pane_label`; an empty label clears the option. It does not change the
+raw tmux pane title, AI topic, or AI topic manual-ownership flag. The canonical
+keybinding action id is `rename-pane-label`. The retired `rename-pane-topic`
+keymap action is no longer accepted: replace a stale
+`[bindings.rename-pane-topic]` table with `[bindings.rename-pane-label]`.
+The advanced `projmux ai topic set/clear` commands remain available and keep
+AI topic ownership separate from the user pane label and raw pane title.
 `apply` regenerates the app tmux config and reloads the live `-L projmux`
 server without restarting it. `make install` and `projmux upgrade` invoke it
 after replacing the binary. Settings > Keybindings normally runs the same
 save/config/reload flow automatically; use `projmux tmux apply` as the CLI
 recovery or sync path after hand-editing `keymap.toml`, after saving Settings
 outside tmux, or after resolving a reported config-generation or live-reload
-failure.
+failure. Reload also removes the known retired no-prefix `C-t` pane-label
+binding from older live servers before installing current bindings. If the
+current keymap assigns `C-t` to another action, that current action is bound
+after cleanup and remains the owner.
 
 ## update
 
@@ -818,8 +1078,13 @@ flags with the top-level `switch` UX:
   regenerates the app config, and reloads the running tmux session when
   possible; skipped or failed stages show `projmux tmux apply` as the recovery
   or sync command. Terminal diagnostics and terminal mapping application stay
-  in the `projmux shell` -> `projmux setup` -> `projmux init` remediation path.
-  The About section includes the `Welcome` entry. In Project
+  in the `projmux shell` -> `projmux setup` -> `projmux setup terminal`
+  remediation path.
+  The compact About section contains Version, Source, real update
+  status/actions, Welcome, and Quit. It does not duplicate static setup or
+  diagnostics guides: use `projmux setup` for key-delivery diagnosis,
+  `projmux setup terminal` for supported terminal remediation, and the
+  read-only `projmux doctor` report for dependency/runtime diagnostics. In Project
   Picker, `Project Root` manages the saved
   primary root (`~/.config/projmux/projdir`) and displays whether the effective
   value comes from `PROJMUX_PROJDIR`, tmux `@projmux_projdir`, saved config, or
@@ -834,10 +1099,9 @@ flags with the top-level `switch` UX:
   selecting Check Updates runs `projmux update check`, Update Now runs
   `projmux update apply`, and Welcome opens a Settings-native viewer
   independent of shell skip state. `Settings > About > Quit projmux` routes
-  through the same `projmux quit` action picker. The same About section also
-  lists the keybinding diagnostic path: try `projmux shell` first, use `setup`
-  for swallowed keys, use `init` for supported terminal mappings, and use
-  `doctor` for dependencies.
+  through the same `projmux quit` action picker. Settings mutations surface
+  their handled success/failure as a transient passive row inside the native
+  popup; selecting the next action clears or replaces that row.
 
 ## See also