projmux 0.8.3 → 0.9.0

package/docs/cli.md

@@ -23,7 +23,8 @@ 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. |
@@ -32,6 +33,7 @@ projmux <command> [args...]
 | `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 +47,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
@@ -63,7 +65,9 @@ sub-verbs are entry hooks invoked by tmux keybindings (e.g.
 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.
+selection/source rows have been retired. The native picker is always used;
+legacy `PROJMUX_PICKER_BACKEND` and `picker-backend` values remain read-compatible
+and normalize to native.
 
 ## setup
 
@@ -81,31 +85,35 @@ 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.
+
+The top-level `projmux init` command remains a deprecated compatibility alias
+during the migration period. It prints the exact `projmux setup terminal`
+replacement to stderr and still accepts the legacy `--dry-run` flag.
 
 ## doctor
 
 ```
 projmux doctor [--json]
-projmux doctor --install-missing [--dry-run] [--include-optional]
 ```
 
-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 +123,63 @@ 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 plain report exits non-zero when a required dependency is missing
+or stale, and exits `0` when only optional dependencies or AI notify
+integrations are missing. `--json` preserves its current successful exit after
+emitting the report even when a required dependency is missing or stale. It
+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.
+Users explicitly run any displayed install guidance or command outside doctor.
+Doctor does not diagnose terminal key delivery; use `projmux setup` for that.
+
+Compatibility notice: `--install-missing`, `--dry-run`, and
+`--include-optional` are deprecated install flags. During the compatibility
+period their install, preview, optional-dependency, output, and exit behavior
+remain unchanged, and each invocation using one or more of them emits one
+stderr warning. They cannot be combined with `--json`; `--dry-run` and
+`--include-optional` still require `--install-missing`. These mutation paths
+will be removed when doctor becomes read-only diagnostics only.
+
+`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]
+```
+
+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.
 
 ## focus
 
@@ -249,23 +297,51 @@ 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.
+Antigravity emits a conversation-local `context` row and separate official
+account rows labelled `quota/<upstream bucket ID>`. `--window quota` selects
+the latter; opaque IDs such as `weekly` are not aliases for the fixed
+`weekly` window. Used percent is `100 * (1 - remaining_fraction)`.
+`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
+conversation context row.
+
+## 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. Enter drills Project → Window → Pane →
+Pane detail; Esc or Alt-Left returns, and root Esc closes. 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. 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,18 +365,23 @@ 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`
+- `usage` — HUD-style `Claude (Nm) 5h [bar] N% · weekly [bar] N%   Antigravity
+  ctx [bar] N% · quota/<bucket> [bar] N%`. Degrades through six tiers as `--max-width`
   shrinks. 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
   displayed in the compact HUD. Degrades through width tiers; default
   `--max-width` is `200` runes.
-- `resources` — Linux/WSL aggregate `CPU N%  MEM N%` from `/proc/stat` and
-  `/proc/meminfo`. CPU needs two invocations to establish a delta and renders
-  `--` for the first sample. WSL reports the Linux guest/VM view. Unsupported
-  platforms and unreadable procfs data produce no error output.
+- `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. 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
 
@@ -351,7 +432,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>]
@@ -359,11 +440,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     ...
 ```
@@ -393,11 +475,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
@@ -466,27 +578,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 and
+surfaced by the usage HUD as the separate `context` row. 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.
@@ -663,7 +823,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>]
@@ -674,9 +834,14 @@ 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`; `rename-pane-topic` remains a
+deprecated label-only keymap alias for one compatibility period.
 `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
@@ -817,8 +982,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
@@ -833,10 +1003,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
 

package/docs/configuration.md

@@ -4,6 +4,24 @@ Most users can configure projmux from `projmux settings`. Environment variables
 are available for repeatable shell setup, managed machines, or advanced
 overrides.
 
+## Operational diagnostics state
+
+Projmux keeps a private bounded operational journal at:
+
+```text
+${XDG_STATE_HOME:-$HOME/.local/state}/projmux/logs/operations.jsonl
+```
+
+There is no configuration switch for arbitrary fields or remote delivery. The
+`projmux` state and `logs` directories are created/repaired to mode `0700`, and
+the JSONL file is created/repaired to `0600` on POSIX systems. At more than
+5 MiB, the writer atomically retains about the newest 2 MiB of complete valid
+records. Lock ownership is maintained by the OS and acquisition waits no more
+than 200 ms before the best-effort write is abandoned. See
+[operational-diagnostics.md](operational-diagnostics.md) for safe field and
+best-effort behavior. Existing `ai-ingest.log` and
+`PROJMUX_*_DEBUG` settings remain separate and unchanged.
+
 ## Project Discovery
 
 `projmux switch` combines pinned directories, live tmux sessions, and
@@ -97,8 +115,8 @@ keybinding as saved; failures identify the stage that failed.
 Raw sequences that cannot be safely represented as a direct keybinding are not
 persisted. Use Settings to save a custom key. When key delivery needs
 terminal-layer remediation, first try the key in `projmux shell`, then run
-`projmux setup` from the raw terminal, then use `projmux init` for supported
-terminal adapters.
+`projmux setup` from the raw terminal, then use `projmux setup terminal` for
+supported terminal adapters.
 
 `~/.config/projmux/keymap.toml` can also be edited by hand. When the file is
 absent, generated tmux config stays on the built-in defaults.
@@ -114,6 +132,9 @@ keys = ["C-t"]
 
 [bindings."Sidebar:PinProject"]
 keys = ["M-p", "p"]
+
+[bindings."Resources:Open"]
+keys = ["M-u"]
 ```
 
 Each table is `[bindings.<action-id>]`. Supported keys are:
@@ -150,6 +171,12 @@ such as `ProjectSidebarToggle`, `NotifySidebarToggle`, `SessionPopupToggle`,
 popup commands use `Surface:Action` IDs and have surface-local conflict
 domains and remain visible in Settings when catalogued.
 
+`Resources:Open` is a user-configurable direct popup action with no built-in
+shortcut. Every configured alias renders the canonical client-scoped body
+`projmux tmux popup-toggle --client #{client_tty} resource-inspector`; pressing
+the same alias again closes only that client's popup. It remains available on
+Linux/tmux even when the Labs live-resource status segment is off.
+
 The Settings writer is deterministic and rewrites the supported saved subset
 only. If the existing file has parse errors or unknown action IDs, Settings
 shows the keymap error row and refuses to overwrite it until the file is fixed.
@@ -159,8 +186,8 @@ print-config`, `projmux tmux install`, `projmux tmux print-app-config`,
 `projmux tmux install-app`, and `projmux shell`. Terminal init adapters such as
 Ghostty and Windows Terminal install built-in plain-byte mappings where needed;
 they do not read `keymap.toml` or copy saved keys into terminal configs.
-Changing terminal-layer mappings still requires rerunning `projmux init` and
-restarting the terminal where that terminal requires it.
+Changing terminal-layer mappings still requires rerunning `projmux setup
+terminal` and restarting the terminal where that terminal requires it.
 
 When a chord is overridden, projmux emits unbinds for both the stale default
 chord and the replacement before binding the merged action. Popup and floating
@@ -334,9 +361,9 @@ user/global preference in this release.
 ## AI Resume Picker
 
 The AI resume picker (`projmux ai split --agent resume`) lists the most recent
-deduplicated Claude/Codex resume sessions. The number of rows it shows and how
-far below the current directory it scans are both configurable; the defaults are
-30 rows and depth 0 (the current directory only).
+deduplicated Claude/Codex/Antigravity resume sessions. The number of rows it
+shows and how far below the current directory it scans are both configurable;
+the defaults are 30 rows and depth 0 (the current directory only).
 
 Preferred interactive path:
 
@@ -375,6 +402,21 @@ column (`./`, `./web`, `./api`) so child-directory sessions are easy to tell
 apart. A missing or zero depth is identical to the historical behavior. Settings
 edits write the global config.
 
+Antigravity uses the upstream v1.1.12 current-storage boundary before its
+legacy history fallback. `cache/last_conversations.json` contributes the latest
+UUID mapped to a matching workspace; `cache/conversation_metadata.json`
+contributes only rows that carry a valid UUID, workspace URI/path, and summary.
+Both require an exact regular `conversations/<uuid>.db` and use only its
+existence/mtime. They do not open SQLite content and do not treat `.db-wal`,
+`.db-shm`, symlinks, or arbitrary paths as conversations. The cache provides a
+latest-session floor rather than complete history. Missing/malformed cache,
+workspace-less metadata, and stale mappings degrade to legacy `history.jsonl`
+without changing the shared exact/depth/sort/cap behavior.
+Live hook/session-state resume metadata is a separate high-confidence lane and
+is not a disk-picker candidate. When a disk picker selection creates a pane,
+its source is persisted so Session State preview and doctor can report medium
+confidence for DB-validated cache sources or low confidence for legacy history.
+
 ## Environment Variables
 
 | Variable | Purpose |
@@ -780,10 +822,28 @@ CPU/memory segment on the lower status row. The saved global value is:
 ```
 
 Accepted values are `off` (default) and `on`. The feature is available on
-native Linux and WSL. It reads Linux procfs directly without launching `top`,
-`free`, PowerShell, or another metrics process. In WSL the values describe the
-Linux guest/VM view, not total Windows host utilization. The CPU delta cache is
-internal state at
+macOS, native Linux, and WSL. Linux reads procfs directly; macOS reads Mach host
+statistics and `hw.memsize`. Neither path launches `top`, `vm_stat`, `free`,
+PowerShell, or another metrics process. On macOS, available memory is free plus
+inactive pages, matching the reclaimable-memory intent of Linux
+`MemAvailable`. In WSL the values describe the Linux guest/VM view, not total
+Windows host utilization. These are host-scoped values and do not attribute
+usage to a pane, window, project, or session.
+
+When enabled, the compact segment is also the clickable `resources` statusbar
+range and opens the Resource Inspector. Turning the Lab off hides only this
+segment; it does not disable `projmux resources` or a custom-bound
+`Resources:Open` action. Inspector samples are memory-only for the popup
+lifetime and are unrelated to the status segment's host CPU reference cache.
+
+The display policy is fixed rather than configurable: CPU is normal below 70%,
+warning at 70–89%, and critical at 90% or above; memory is normal below 75%,
+warning at 75–89%, and critical at 90% or above. The two values are classified
+and styled independently. Normal and unavailable (`--`) values use the
+secondary status-text theme role, warnings use the warning role, and critical
+values use the bold critical role. No threshold values are stored in config.
+
+The CPU delta cache is internal state at
 `${XDG_STATE_HOME:-~/.local/state}/projmux/live-resources-sample.json`.
 CPU reference samples older than 30 seconds are ignored and replaced on the
 next refresh.

package/docs/globalization.md

@@ -124,7 +124,7 @@ Classification:
 
 Do not translate these families:
 
-- Product and agent names: `Codex`, `Claude`, `projmux`, `tmux`, `psmux`,
+- Product and agent names: `Codex`, `Claude`, `projmux`, `tmux`,
   `GitHub`, `npm`.
 - Terminal and app names: `Windows Terminal`, `Ghostty`, `WezTerm`, `Kitty`,
   `iTerm2`, `Alacritty`, `Foot`.