projmux 0.9.0 → 0.10.1

package/docs/architecture.md

@@ -53,8 +53,8 @@ Responsibilities:
 - selection handoff into core actions
 - picker-agnostic close/dismiss actions
 
-Picker-specific display and search rules are tracked in
-[picker-ui-plan.md](picker-ui-plan.md).
+Picker-specific display, search, input, and popup rules are tracked in
+[native-picker.md](native-picker.md).
 
 This keeps parity with the existing shell workflow while moving state and behavior into Go.
 

package/docs/cli.md

@@ -26,7 +26,6 @@ projmux <command> [args...]
 | `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. |
@@ -47,27 +46,27 @@ 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 usage across fixed windows, context, and named quota buckets. |
+| `usage` | Report AI usage across fixed windows and named account quota buckets. |
 | `version` | Print the current version. |
 
 ## switch
 
 ```
-projmux switch [path]
+projmux switch [--ui=popup|sidebar]
+projmux switch open <path>
 projmux switch toggle-tag | toggle-pin | kill | settings | preview
 projmux switch cycle-pane | cycle-window | sidebar-focus
 ```
 
 Project picker. With no positional argument, opens the configured picker popup
-or sidebar (depending on entry helper). With a path, jumps directly. The
+or sidebar (depending on entry helper). `switch open <path>` jumps directly. The
 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/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.
+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
 
@@ -102,20 +101,16 @@ write through a symlink unless `--allow-symlink` is passed (dotfiles repos).
 than one default location (Ghostty `config` vs `config.ghostty`). If setup
 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 [--json] [--section deps|runtime|integrations|session-state|logs] [--verbose]
 ```
 
 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
+for Codex hooks, Claude Code hooks, Antigravity hooks/statusline, and the tmux bell
 fallback. AI notify integration statuses are `installed`, `missing`, or
 `conflict`; missing or conflicting integrations are informational and do not
 make doctor fail. It also reports read-only Session State resume metadata
@@ -129,24 +124,57 @@ Live `hook`/`session-id` metadata is high confidence; DB-validated Antigravity
 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.
+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
@@ -161,6 +189,7 @@ than a standalone Settings row.
 ```
 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
@@ -181,6 +210,52 @@ channel and never change command output or exit status. See
 [operational-diagnostics.md](operational-diagnostics.md) for the file,
 retention, concurrency, and privacy contracts.
 
+`ai watch-title` emits a bounded common lifecycle: one start, one terminal
+pane-gone/hook-active stop, and at most one copy of each closed watcher failure
+tuple per process. Normal polling iterations emit nothing. AI hook ingest emits
+common events only for malformed/read/oversized payloads, unmatched or invalid
+targets, unsupported event classification, and route failures. Provider event
+names, payloads, prompt/tool/transcript values, notification text, pane
+metadata, paths, UUIDs, and conversation/session IDs are never stored. Normal
+state/notify/quiet/dedupe hook results stay zero-volume in the common AI family;
+the existing notify transition remains the owner when notification behavior
+occurs.
+
+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
 
 ```
@@ -278,10 +353,12 @@ projmux notify reconcile [--json]
   While open, the native
   sidebar refreshes its row list on successful queue-write events without an
   Alt-2 close/reopen toggle, using the same deferred refresh path as `a` and
-  `x`. The sidebar uses two-line cards with notification text first and
-  compact age/project/window/pane metadata below. Hidden queue ids remain
-  action values, but the sidebar has no search input. `--client` is used by
-  tmux popup launchers to keep row-select focus on the clicked client.
+  `x`. The sidebar is a pane/session-grouped inbox whose collapsed rows are
+  fixed three-line cards: project/session, agent/provider, and newest age on
+  line 1; topic/pane-title/task context plus severity/live-state metadata on
+  line 2; and the latest notification preview on line 3. Hidden queue ids
+  remain action values, but the sidebar has no search input. `--client` is used
+  by tmux popup launchers to keep row-select focus on the clicked client.
 - `ack <id>` removes one entry; `--all` flushes the queue.
 - `reconcile` — walks `tmux list-panes -a` and back-fills entries for
   panes whose attention state is `reply` AND whose AI agent option is
@@ -293,7 +370,7 @@ projmux notify reconcile [--json]
 
 ## usage
 
-Authoritative AI token usage. See [usage-tracking.md](usage-tracking.md)
+Authoritative AI account usage. See [usage-tracking.md](usage-tracking.md)
 for adapter detail.
 
 ```
@@ -308,14 +385,27 @@ Codex shares the global `30s`). `--json` emits the snapshot array; when
 backoff is active the wrapper `{snapshots, backoff}` object is emitted
 instead.
 
-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)`.
+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
-conversation context row.
+private conversation context diagnostic.
 
 ## resources
 
@@ -325,21 +415,33 @@ 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.
+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. 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
+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. `No project match`, `Multiple project matches`, and non-drillable
+`Other / unattributed` remain explicit. The first two are display labels over
+stable internal attribution keys. Warming, partial, unavailable, unknown, and
+overage states also remain explicit. 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.
 
+Only Resource Inspector anomalies (`unavailable`, `partial`, `stale`, closed
+collection-stage errors, and scan-budget exhaustion) enter the private bounded
+operations journal. Identical persistent anomalies are transition-coalesced;
+healthy periodic samples and refreshes emit zero records. These records contain
+no CPU/RSS values, PID/process detail, project/tmux identity, path/title/command,
+or arbitrary error/status text. `diagnostics report` includes only error-level
+closed resource outcomes; local-only partial/stale info rows are omitted.
+
 This is distinct from `projmux status resources`, which remains the short
 host-only statusbar renderer.
 
@@ -365,9 +467,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%   Antigravity
-  ctx [bar] N% · quota/<bucket> [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
@@ -392,16 +499,22 @@ projmux statusbar usage-refresh
 ```
 
 Click/keyboard dispatcher for the two-line status bar. Implemented range ids:
-`session pwd kube git usage notify settings`. The bare `window` /
+`session pwd kube git resources usage notify settings`. The bare `window` /
 `window|<idx>` token (tmux's built-in window-list range) and the empty
 range fall through to `select-window -t @<mouse_window>` so the native
-click-to-switch tab affordance is preserved on row 0. Unknown range ids are
+click-to-switch tab affordance is preserved on row 1. Unknown range ids are
 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
@@ -433,11 +546,11 @@ supplied window.
 
 ```
 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>]
-projmux ai notify   <reset|notify> [--pane <id>]
-projmux ai watch-title [--pane <id>]
+projmux ai picker   [--inside] [--shell] [--resume] [right|down]
+projmux ai settings [--get|--set <mode>]
+projmux ai status   set <thinking|waiting|idle> [pane]
+projmux ai notify   [notify|reset] [pane]
+projmux ai watch-title [pane]
 projmux ai ingest   codex-hook < payload.json
 projmux ai ingest   claude-hook < payload.json
 projmux ai ingest   antigravity-hook [--event <PreInvocation|PostInvocation|PostToolUse|Stop|Statusline>] < payload.json
@@ -640,9 +753,9 @@ 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`. 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
+`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.
@@ -664,6 +777,15 @@ payloads are not stored. The log is capped at 1 MiB and trimmed to the most
 recent roughly 512 KiB when it grows past the cap. Use `--json` for raw JSONL
 and `--path` to print the resolved file path.
 
+This legacy log is retained for compatibility. Its producer, `ingest log`
+consumer, 1 MiB/roughly 512 KiB retention, and support-report count summary are
+unchanged. The common operations journal now carries only the safe anomalous
+classification and watcher lifecycle described above. Both surfaces run in
+parallel during the migration. It is now documented as a deprecation candidate,
+but this release does not deprecate, remove, rename, or change it; a separate
+breaking roadmap must first migrate its detailed local consumer. See
+[legacy-diagnostics-inventory.md](legacy-diagnostics-inventory.md).
+
 For `Stop`, projmux reads `transcript_path` when present and extracts the last
 assistant text from the transcript tail; if that is unavailable, it falls back
 to a generic Claude completion row. `PermissionRequest` rows expose the tool
@@ -840,15 +962,21 @@ accepted by `popup-toggle` mirror the historical sessionizer surface:
 `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.
+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
 

package/docs/configuration.md

@@ -183,7 +183,7 @@ shows the keymap error row and refuses to overwrite it until the file is fixed.
 
 The file currently affects generated tmux config from `projmux tmux
 print-config`, `projmux tmux install`, `projmux tmux print-app-config`,
-`projmux tmux install-app`, and `projmux shell`. Terminal init adapters such as
+`projmux tmux install-app`, and `projmux shell`. Terminal remediation 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 setup
@@ -439,7 +439,6 @@ confidence for DB-validated cache sources or low confidence for legacy history.
 | `PROJMUX_SESSIONSTATE_AUTOSAVE` | Session snapshot autosave override for the global fallback. Values such as `off`, `false`, or `0` disable autosave for projects that inherit the global setting; explicit project auto-save `on`/`off` still takes precedence. |
 | `PROJMUX_SESSIONSTATE_DEBUG` | When non-empty, quiet autosave surfaces suppressed session-state errors to stderr. |
 | `PROJMUX_FOCUS_DEBUG` | When non-empty, `projmux focus` prints one telemetry line to stderr. |
-| `PROJMUX_PICKER_BACKEND` | Legacy picker backend override. Any value, including old `fzf` settings, now resolves to the native picker. |
 | `PROJMUX_INSTALLER` | Installer source hint used by update flows. npm installs set this automatically; advanced release installs can set `github-release`. |
 | `PROJMUX_SHELL_UPDATE_CHECK_TIMEOUT_MS` | Timeout in milliseconds for the best-effort release check attempted by `projmux shell` when the update cache is missing or stale. Invalid, zero, or negative values use the default. |
 
@@ -841,7 +840,9 @@ 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.
+values use the bold critical role. Visible severity words are omitted and each
+percent uses a fixed four-column slot, including `%`, so metric transitions do
+not resize the segment. 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`.

package/docs/globalization.md

@@ -34,7 +34,7 @@ Classification:
 
 | Family | Examples | Class | Phase 0 policy |
 | --- | --- | --- | --- |
-| Agent names | `Codex`, `Claude`, `AI` | `literal` | Preserve exactly. |
+| Agent names | `Codex`, `Claude`, `Antigravity`, `AI` | `literal` | Preserve exactly. |
 | Category labels | `Response complete`, `Approval required`, `Input required`, `Error`, `Subagent stopped`, `Teammate waiting` | `translate` | English baseline now; catalog keys later. |
 | Review body prefix | `Review pending:` | `translate` | English baseline now; catalog key later. |
 | Tool names | `Bash`, `Read`, `WebFetch`, `Shell` | `literal` | Preserve provider/source spelling. |
@@ -78,7 +78,7 @@ Classification:
 | Row labels and previews | enabled/disabled state, current source, saved values | `translate` | Inventory only; catalog later. |
 | Disabled reasons and warnings | missing project, env override, conflict text | `translate` | Inventory only; catalog later. |
 | Config keys and env vars | `PROJMUX_PROJDIR`, `config.toml`, `ui.locale` | `literal` | Preserve exactly. |
-| Commands shown for copying | `projmux ai integrate codex --dry-run` | `literal` | Preserve exactly. |
+| Commands shown for copying | `projmux ai integrate codex --dry-run`, `projmux ai integrate antigravity --dry-run` | `literal` | Preserve exactly. |
 | Persisted values | `none`, `notify`, `raise`, `auto` | `literal` | Preserve enum values. |
 
 ### Native Picker And Render Surfaces
@@ -87,7 +87,7 @@ Files:
 
 - `internal/ui/projmuxpicker/*`
 - `internal/ui/render/*`
-- `docs/native-picker-no-fzf-poc.md`
+- `docs/native-picker.md`
 
 Classification:
 
@@ -124,7 +124,7 @@ Classification:
 
 Do not translate these families:
 
-- Product and agent names: `Codex`, `Claude`, `projmux`, `tmux`,
+- Product and agent names: `Codex`, `Claude`, `Antigravity`, `projmux`, `tmux`,
   `GitHub`, `npm`.
 - Terminal and app names: `Windows Terminal`, `Ghostty`, `WezTerm`, `Kitty`,
   `iTerm2`, `Alacritty`, `Foot`.
@@ -239,7 +239,8 @@ Contribution convention:
 - Add the `en-US` entry in the same change as the key.
 - Add `ko-KR` when the translation is known; otherwise rely on fallback while
   keeping the missing key intentional in review notes.
-- Do not translate product names (`projmux`, `tmux`, `Codex`, `Claude`),
+- Do not translate product names (`projmux`, `tmux`, `Codex`, `Claude`,
+  `Antigravity`),
   commands, paths, config keys, environment variables, provider payloads, or
   source enum values.
 - Runtime migrations should be narrow by surface. Move a string family behind
@@ -296,7 +297,8 @@ Width-safe rendering:
 
 Runtime surfaces migrated:
 
-- AI desktop notification summaries for Codex and Claude hook payloads.
+- AI desktop notification summaries for Codex, Claude, and Antigravity hook
+  payloads.
 - In-app notify queue table/sidebar/statusbar display text for AI entries.
 - Notify live explanation text for `projmux notify list --live`.
 - Sidebar/table/statusbar age formatting and sidebar stale/gone/target labels.
@@ -317,9 +319,9 @@ Literal preservation and parity rules:
 - Translate only catalog-owned category labels such as `Response complete`,
   `Approval required`, `Input required`, `Error`, `Subagent stopped`, and
   `Teammate waiting`.
-- Preserve provider-owned payloads verbatim: `Codex`, `Claude`, tool names,
-  commands, paths, URLs, query strings, transcript excerpts, teammate IDs, and
-  subagent IDs.
+- Preserve provider-owned payloads verbatim: `Codex`, `Claude`, `Antigravity`,
+  tool names, commands, paths, URLs, query strings, transcript excerpts,
+  teammate IDs, and subagent IDs.
 - Desktop notification summaries and in-app queue display text must use the
   same rendered category labels for the same locale while preserving the same
   literal payload body.

package/docs/hooks.md

@@ -205,11 +205,11 @@ If a `send-noti` hook itself calls `projmux notify push`, projmux sees
 `PROJMUX_NOTIFY_HOOK_DEPTH=1` in the child environment and skips another
 `send-noti` hook fire. The queue write itself still succeeds.
 
-`Settings > Notifications > Delivery sources` surfaces the active Codex hooks,
-Claude, and tmux AI notify diagnostics: status, conflicts, config paths, and
-copyable CLI install/remove/dry-run commands. It also shows whether
+`Settings > Notifications > Delivery sources` surfaces the active Codex,
+Claude, Antigravity, and tmux AI notify diagnostics: status, conflicts, config
+paths, and copyable CLI install/remove/dry-run commands. It also shows whether
 `PROJMUX_NOTIFY_HOOK` overrides the built-in desktop sender. It does not install
-or remove external Codex, Claude, or tmux settings.
+or remove external Codex, Claude, Antigravity, or tmux settings.
 
 `PROJMUX_NOTIFY_HOOK` is separate from `[hooks.send-noti]`: it replaces the
 desktop sender and receives positional arguments
@@ -731,16 +731,28 @@ projmux does not run `post-attach` for outside-tmux attach paths in this phase.
 
 ## Environment
 
-Hooks inherit projmux's environment, plus:
-
-| Variable | Always set | Description |
-| --- | --- | --- |
-| `PROJMUX_SESSION` | yes | tmux session name |
-| `PROJMUX_CWD` | yes | lifecycle working directory; for creation events this is the new session directory |
-| `PROJMUX_SESSION_KIND` | yes | `persistent` or `ephemeral` for creation events; empty for `post-attach` |
-| `PROJMUX_VERSION` | yes | projmux version string |
-| `PROJMUX_SOCKET` | only if projmux used `tmux -L <socket>` | tmux socket name |
-| `PROJMUX_PANE` | only for pane events | tmux pane id such as `%7` |
+Hooks inherit projmux's environment. The lifecycle variables below are added by
+event; “omitted” means the variable is not added when its context value is
+empty.
+
+| Variable | `pre-create` | `post-create` | `post-attach` | `send-noti` |
+| --- | --- | --- | --- | --- |
+| `PROJMUX_SESSION` | new session name | new session name | target session name | target session when known; otherwise empty |
+| `PROJMUX_CWD` | requested session directory | created session directory | resolved target directory; may be empty if lookup fails | dispatcher working directory |
+| `PROJMUX_SESSION_KIND` | `persistent` or `ephemeral` | `persistent` or `ephemeral` | empty | empty |
+| `PROJMUX_VERSION` | projmux version | projmux version | projmux version | projmux version |
+| `PROJMUX_SOCKET` | app socket metadata (`projmux`) | app socket metadata (`projmux`) | app socket metadata (`projmux`) | queue-entry socket when known; otherwise omitted |
+| `PROJMUX_PANE` | omitted: no pane exists yet | exact id returned by standard persistent/ephemeral `tmux new-session`, such as `%7`; omitted for snapshot replay | omitted | target pane when known; otherwise omitted |
+
+`pre-create` intentionally has no `PROJMUX_PANE`: it runs before
+`tmux new-session` creates the first pane. Standard persistent and ephemeral
+`post-create` paths run after creation and therefore receive that exact pane
+id. Snapshot replay can restore multiple panes and does not expose a single
+returned pane at its lifecycle boundary, so it omits `PROJMUX_PANE`.
+`PROJMUX_SOCKET` is routing metadata for hook commands; it does not imply that
+the tmux client itself adds `-L` to its commands. The `post-attach` and
+`send-noti` cells describe their existing contexts; this contract adds no pane
+context to either event.
 
 ## Examples
 
@@ -749,6 +761,7 @@ Hooks inherit projmux's environment, plus:
 ```bash
 #!/usr/bin/env bash
 echo "session=$PROJMUX_SESSION cwd=$PROJMUX_CWD kind=$PROJMUX_SESSION_KIND"
+tmux -L "$PROJMUX_SOCKET" set-option -p -t "$PROJMUX_PANE" @projmux_initialized 1
 ```
 
 ### Project Startup Command
@@ -770,7 +783,7 @@ case "$PROJMUX_CWD" in
   *) exit 0 ;;
 esac
 
-tmux set-environment -t "$PROJMUX_SESSION" GH_TOKEN "$token"
+tmux -L "$PROJMUX_SOCKET" set-environment -t "$PROJMUX_SESSION" GH_TOKEN "$token"
 ```
 
 `set-environment` only seeds the session env that newly-spawned panes inherit;

package/docs/keybindings.md

@@ -194,7 +194,7 @@ Settings > Keybindings stays a discovery surface. It must continue to expose
 launch toggles, sidebar keymap actions, picker-local actions, pane switching,
 window switching, and rename actions. The basic Settings flow is not the
 terminal remediation surface: key-role replacement, disable-default, typed
-fallback, terminal mapping preview/apply, and init execution rows stay out of
+fallback and terminal mapping preview/apply rows stay out of
 the action detail.
 
 The product model does not support `UserN` or `CSI-u` as fallback guidance.
@@ -242,7 +242,10 @@ Settings is the default apply path for key edits: it writes the key list,
 refreshes the generated config, and reloads the running tmux session when
 possible. Use `projmux tmux apply` as a CLI recovery/sync command after editing
 the keymap file by hand, after an outside-tmux Settings save, or after resolving
-a reported generated-config or live-reload failure.
+a reported generated-config or live-reload failure. Generated config first
+unbinds the known retired `C-t` pane-label chord, then installs the current
+keymap; an explicit current `C-t` assignment therefore wins without retaining
+the retired command body. Apply does not rewrite `keymap.toml`.
 
 ## Keymap File