projmux 0.6.6 → 0.6.7

package/docs/agent-workflow.md

@@ -29,18 +29,21 @@
 - `make fmt`: repository formatting for Go, shell snippets, and generated docs where applicable.
 - `make fix`: safe automatic fixes such as `go fix` and repository-approved cleanup steps.
 - `make npm-pack`: local npm binary package staging and `npm pack --dry-run` for the root package plus platform packages.
-- `make test`: fast unit coverage for app-layer AI split native agent launch/selective popup-toggle/settings/status/notification parity including AI pane option metadata, watcher metadata bootstrap for existing panes, capture-backed reply detection, missing-pane watcher shutdown, armed focus-only reply badge clearing, busy attention preservation on focus clear, manual AI topic preservation while watcher status still updates, agent-labeled desktop notification message context with pane-title-first body text, global/project-local lifecycle hook dispatch for post-create/pre-create/post-attach/send-noti with project hook and `.projmux/config.toml` trust-store hashing plus env/settings kill-switch gating, declarative startup command and hook run coverage, `send-noti` stdin JSON delivery plus `PROJMUX_NOTIFY_*` env payload, notify queue write success/failure/depth-guard dispatch rules, notify/statusbar/sidebar origin-client focus routing, project config env/kube session environment application, Settings project config env/kube/startup form writes with trust-store refresh and preserved hook commands, startup command send-keys orchestration plus startup pane replay markers, pre-create abort behavior, and shared projmux notification icon paths, and scoped even row/column resizing after shell and agent splits, status-bar git/kube segment parity including muted git branch block styling and compact dirty/staged/ahead/behind state colors, statusbar pwd display-only native-framed path popup with shared popup-wait-key/no-extra-payload-line command coverage, no clipboard or tmux buffer copy, and popup-wait-key cursor/raw-mode restore coverage, statusbar usage native HUD popup alignment/height-budget/threshold palette/muted sync-staleness/fallback coverage without raw CLI popup or popup-toggle stacking, statusbar settings click popup fallback and settings chip right-edge rendering without default trailing space, popup-toggle stale marker recovery, isolated `projmux shell` tmux app launch/config generation including home fallback plus project-context default session targeting from `PROJMUX_CWD` or nearest project marker, app-owned project-name statusbar layout, distinct project badge color, and quiet debounced session-state autosave command/app-config trigger, first-run/version-bump shell welcome state and inline update handling, shell startup update prompt actions for fresh installer-aware cached updates, pane/window keybindings, keymap.toml tmux override rendering/stale unbinds including retired direct/UserKey cleanup, Settings Keybindings root/list/detail capture flows including parse-error rows, unsafe raw capture and timeout guards, disable/reset writes, app config regeneration, live tmux source-file reload, and no-live-tmux save behavior, window rename bindings, pane rename helper/binding, pane-exit rebalance command/hooks, hook-pane and after-select-pane based attention focus hooks, attention badge toggle/clear/list/window rendering, attach/current/kill/pin/preview/prune/sessions/session-popup/settings commands, switch, tag, tmux helper commands, update status/check/apply cache and installer detection including GitHub Release binary asset selection/extraction/replacement, doctor install-missing command selection, AI notify integration diagnostics, and Session State resume metadata diagnostics, Settings AI notify integration diagnostics read-only status/conflict/CLI guidance, and Settings About update status/check action wiring, untitled standalone popup-toggle marker close/config install, direct popup minimum sizing, AI picker minimum width and height, sidebar minimum width and compact badge spacing, preview select writes, popup render output after cycling, switch picker pin action behavior without inline settings rows, nested settings hub sections for AI defaults, project picker filesystem scan/pin actions, Project Root settings source/shadowing/set/current/clear flows, app/keybinding info including Ctrl-M rename forwarding, and About version/source rendering, switch picker focused-session kill, switch picker launcher-key abort bindings, switch explicit project-root, unconfigured-root, and weak managed-root heuristic parity, switch popup hiding new-session candidates while sidebar keeps create-capable rows, switch row project-name display with `~` pinned to the top and live-session-first sorting, pretty-path, preview-context including kube context/namespace, switch settings subcommand flows including add-current-pin, interactive add-pin picker, and settings label/preview polish including Phase 2 Settings/hookmaker/project-startup/trust/quit destructive row color regression strings, native preview wiring, baseline picker surface parity including prompt/footer/header fallback without app-name filler and search-key scoped card matching, sidebar compact action-only key footer, sidebar preview-window/start-position behavior without focus-time session switching, sidebar row/window ANSI styling with pane-aggregated attention badge state and AI topic labels, Alt+2/Alt+3 legacy popup row, preview-window, pane metadata, and pane-snapshot parity, switch read0 card rows with active/inactive title styling, right-side status badges, combined directory/git metadata with muted inactive branch styling, statusbar-matched block window tabs with window attention badges, read0 expect-key action parsing, restored pin/tag card badges, and restrained selected-row marker styling, switch preview metadata without duplicated directory/git rows, preview metadata rendering, popup pane display names for AI agents, AI topics, and shell commands, switch preview cycle bindings, sessions picker preview/cycle/open/kill wiring including attached-session fallback behavior, sessions picker launcher-key abort bindings, popup/switch preview summary formatting, popup sessions tmux entry helpers, switch/popup/session rendering, session identity, session-state Claude/Codex resume and declarative startup replay, session snapshot capture/autosave recipe classification including save/autosave pre-capture resume metadata refresh from live AI session ids, Claude transcript paths, and Codex rollout log cwd matching/ambiguity skips, candidate discovery, config path derivation, popup preview read-models, and pure state rules including preview, tag, and lifecycle stores.
-- `make test` also covers Settings > AI Settings > Enabled agents Phase 0 config behavior: missing config enables Claude and Codex, unknown saved provider names are ignored without disabling known providers, Settings toggles persist Claude/Codex only, shell/selective are absent from enabled-agent rows, and a saved default split mode warns when its provider is disabled.
-- `make test` also covers AI semantic badge renderer aggregation for window-list, sidebar rows, switch window tabs, popup pane summaries, and pane-border topic badges using prompt-required > response-complete > in-progress priority while preserving blank no-state lanes, plus Settings > Appearance AI badge style selection for dot/emoji/off pane-border compatibility with dot as the persisted/config fallback.
+- `make test`: fast unit coverage for app-layer AI split native agent launch/selective popup-toggle/settings/status/notification parity including AI pane option metadata, watcher metadata bootstrap for existing panes, capture-backed reply detection, missing-pane watcher shutdown, armed focus-only reply badge clearing, busy attention preservation on focus clear, manual AI topic preservation while watcher status still updates, agent-labeled desktop notification message context with pane-title-first body text, global/project-local lifecycle hook dispatch for post-create/pre-create/post-attach/send-noti with project hook and `.projmux/config.toml` trust-store hashing plus env/settings kill-switch gating, declarative startup command and hook run coverage, `send-noti` stdin JSON delivery plus `PROJMUX_NOTIFY_*` env payload, notify queue write success/failure/depth-guard dispatch rules, notify/statusbar/sidebar origin-client focus routing, project config env/kube session environment application, Settings project config env/kube/startup form writes with trust-store refresh and preserved hook commands, startup command send-keys orchestration plus startup pane replay markers, pre-create abort behavior, and shared projmux notification icon paths, and scoped even row/column resizing after shell and agent splits, status-bar git/kube segment parity including muted git branch block styling and compact dirty/staged/ahead/behind state colors, statusbar pwd display-only native-framed path popup with shared popup-wait-key/no-extra-payload-line command coverage, no clipboard or tmux buffer copy, and popup-wait-key cursor/raw-mode restore coverage, statusbar usage native HUD popup alignment/height-budget/threshold palette/muted sync-staleness/fallback coverage without raw CLI popup or popup-toggle stacking, statusbar settings click popup fallback and settings chip right-edge rendering without default trailing space, popup-toggle stale marker recovery, isolated `projmux shell` tmux app launch/config generation including home fallback plus project-context default session targeting from `PROJMUX_CWD` or nearest project marker, app-owned project-name statusbar layout, distinct project badge color, and quiet debounced session-state autosave command/app-config trigger, shell-entry welcome release prompt and inline update handling, shell update skip-by-latest-tag behavior plus best-effort stale-cache refresh, pane/window keybindings, keymap.toml tmux override rendering/stale unbinds including retired direct/UserKey cleanup, Settings Keybindings root/list/detail capture flows including parse-error rows, unsafe raw capture and timeout guards, disable/reset writes, app config regeneration, live tmux source-file reload, and no-live-tmux save behavior, window rename bindings, pane rename helper/binding, pane-exit rebalance command/hooks, hook-pane and after-select-pane based attention focus hooks, attention badge toggle/clear/list/window rendering, attach/current/kill/pin/preview/prune/sessions/session-popup/settings commands, switch, tag, tmux helper commands, update status/check/apply cache and installer detection including GitHub Release binary asset selection/extraction/replacement, doctor install-missing command selection, AI notify integration diagnostics, and Session State resume metadata diagnostics, Settings AI notify integration diagnostics read-only status/conflict/CLI guidance, and Settings About update status/check action wiring, untitled standalone popup-toggle marker close/config install, direct popup minimum sizing, AI picker minimum width and height, sidebar minimum width and compact badge spacing, preview select writes, popup render output after cycling, switch picker pin action behavior without inline settings rows, nested settings hub sections for AI defaults, project picker filesystem scan/pin actions, Project Root settings source/shadowing/set/current/clear flows, app/keybinding info including Ctrl-M rename forwarding, and About version/source rendering, switch picker focused-session kill, switch picker launcher-key abort bindings, switch explicit project-root, unconfigured-root, and weak managed-root heuristic parity, switch popup hiding new-session candidates while sidebar keeps create-capable rows, switch row project-name display with `~` pinned to the top and live-session-first sorting, pretty-path, preview-context including kube context/namespace, switch settings subcommand flows including add-current-pin, interactive add-pin picker, and settings label/preview polish including Phase 2 Settings/hookmaker/project-startup/trust/quit destructive row color regression strings, native preview wiring, baseline picker surface parity including prompt/footer/header fallback without app-name filler and search-key scoped card matching, sidebar compact action-only key footer, sidebar preview-window/start-position behavior without focus-time session switching, sidebar row/window ANSI styling with pane-aggregated attention badge state and AI topic labels, Alt+2/Alt+3 legacy popup row, preview-window, pane metadata, and pane-snapshot parity, switch read0 card rows with active/inactive title styling, right-side status badges, combined directory/git metadata with muted inactive branch styling, statusbar-matched block window tabs with window attention badges, read0 expect-key action parsing, restored pin/tag card badges, and restrained selected-row marker styling, switch preview metadata without duplicated directory/git rows, preview metadata rendering, popup pane display names for AI agents, AI topics, and shell commands, switch preview cycle bindings, sessions picker preview/cycle/open/kill wiring including attached-session fallback behavior, sessions picker launcher-key abort bindings, popup/switch preview summary formatting, popup sessions tmux entry helpers, switch/popup/session rendering, session identity, session-state Claude/Codex/Antigravity resume and declarative startup replay, session snapshot capture/autosave recipe classification including save/autosave pre-capture resume metadata refresh from live AI session ids including Antigravity conversation ids, Claude transcript paths, and Codex rollout log cwd matching/ambiguity skips, candidate discovery, config path derivation, popup preview read-models, and pure state rules including preview, tag, and lifecycle stores.
+- `make test` also covers Settings > AI Settings > Enabled agents Phase 0 config behavior: missing config enables Claude, Codex, and Antigravity, unknown saved provider names are ignored without disabling known providers, Settings toggles persist Claude/Codex/Antigravity only, shell/selective are absent from enabled-agent rows, and a saved default split mode warns when its provider is disabled.
+- `make test` also covers native Alt-1 sidebar `Sidebar:KillSession` mutable refresh: the action kills through the focused-session safety path, keeps the native picker session open, refreshes rows and preview with `picker.Action.Mutate`/`DeferredUpdate`, and preserves the previous-live-session guard.
+- `make test` also covers the AI provider metadata registry for Claude/Codex/Antigravity launch providers: registry-derived enabled-agent defaults and ordering, Settings enabled-agent rows, AI picker visibility for disabled providers, ambient usage model scope derivation for quota-supported providers, hook diagnostic provider metadata, Antigravity session-state support metadata, and explicit diagnostics for disabled providers without adding unsupported quota adapters.
+- `make test` also covers usage HUD/all-model filtering from Settings > AI Settings > Enabled agents: ambient `status usage` and `usage --model all` scope collection/rendering to enabled Claude/Codex providers, all-disabled all-model output shows a Settings fallback without refreshing adapters, disabled cached rows/backoff do not leak into ambient output, and explicit `usage --model claude|codex` still collects/renders the requested provider even when disabled.
+- `make test` also covers AI semantic badge renderer aggregation for window-list, sidebar rows, switch window tabs, popup pane summaries, and pane-border topic badges using prompt-required > response-complete > in-progress priority while preserving blank no-state lanes, response-complete live badge consume on attention clear without idling action-required/progress badges, plus Settings > Appearance AI badge style selection for dot/emoji/off pane-border, Alt-1 sidebar window/preview tabs, and tmux window-status compatibility with dot as the persisted/config fallback.
 - `make test` also covers AI semantic badge Phase 3 theme-role hardening: `@projmux_ai_badge_kind` storage values and aggregate priority stay unchanged, `minimal` remains a read-time alias for the `off` badge style, progress/success/action-required badge roles stay distinct, permission/input status badges do not use critical red, and critical notify queue severity does not drive live AI status badge colors or desktop notification urgency.
-- `make test` also covers keybinding surface tier catalog rules, action-centered `keymap.toml` `keys = [...]` multi-alias parsing/writing, quoted internal `Surface:Action` tables, legacy popup action ID aliases, canonical popup toggle names, generated tmux config multi-alias rendering, global/direct conflict detection, surface-scoped native picker command conflict detection, Settings Keybindings list/search/detail surface-aware picker-local labels, simplified action detail rows, Labs compatibility redirect to the Keybindings root, capture/add-alias flows, unsafe raw capture, reset behavior, stale guide docs guards, and welcome/runtime footer copy that avoids hardcoded launch-key guides.
-- `make test` also covers welcome revisit policy: shell welcome is suppressed only by `skip_version` matching the current version, legacy `last_welcomed_version` state does not count as skipped, `s` stores current-version welcome skip, Enter continues without storing skip, Settings > About > Welcome opens a Settings-native viewer without pending state, and shell prompt display does not schedule a redundant attach popup.
+- `make test` also covers keybinding surface tier catalog rules, action-centered `keymap.toml` `keys = [...]` multi-alias parsing/writing, quoted internal `Surface:Action` tables, legacy popup action ID aliases, canonical popup toggle names, AI split popup-vs-direct action labels, generated tmux config multi-alias rendering, global/direct conflict detection, surface-scoped native picker command conflict detection, Settings Keybindings list/search/detail surface-aware picker-local labels, simplified action detail rows, Labs compatibility redirect to the Keybindings root, capture/add-alias flows, unsafe raw capture, reset behavior, stale guide docs guards, and welcome/runtime footer copy that avoids hardcoded launch-key guides.
+- `make test` also covers welcome revisit policy: legacy welcome state remains readable without suppressing shell entry, Enter continues without storing release skip, `s` stores an update skip for the current latest tag when an update is available, source installs show disabled Upgrade guidance, stale update cache refresh is best-effort, Settings > About > Welcome opens a Settings-native viewer without pending state, and shell prompt display does not schedule a redundant attach popup.
 - `make test` also covers transport-dependent app tmux defaults for pane/window navigation (`M-Left`/`M-Right`/`M-Up`/`M-Down` and `M-S-Left`/`M-S-Right`) while keeping visible default chords, allowing additive safe plain aliases that do not store or remove the transport defaults, and no UserKey/CSI-u generated fallback.
-- `make test` also covers direct `projmux ai split --agent <claude|codex|shell|selective>` launches, enabled-agent gating for disabled direct launches and disabled saved defaults, `--force-agent` as an explicit direct CLI-only override, selective picker filtering with all-disabled shell fallback guidance, config-default preservation, extra args appended to resolved agent executables, managed pane metadata, title watcher startup, layout application, plain shell split behavior, selective picker delegation, and invalid direct-agent usage errors.
+- `make test` also covers direct `projmux ai split --agent <claude|codex|antigravity|shell|selective>` launches, enabled-agent gating for disabled direct launches and disabled saved defaults, `--force-agent` as an explicit direct CLI-only override, selective picker filtering with all-disabled shell fallback guidance, config-default preservation, extra args appended to resolved agent executables, managed pane metadata, title watcher startup, layout application, plain shell split behavior, selective picker delegation, invalid direct-agent usage errors, and regressions that direct concrete-agent and saved-default splits create a new pane without probing existing AI pane metadata or selecting an existing pane, including when launched from the current AI pane.
 - `make test` also covers Settings IA regression guards for `send-noti` visibility in Hooks, no nested Project recipe inside Hooks, Project recipe/AI/Labs view-first detail rows, Appearance Path/Git/Notify icon direct off/symbol/emoji preview selection with no Change page, Notifications root/Desktop notifications/Delivery sources relocation, localized Korean Desktop notifications root/detail chrome without visible English residue, Delivery sources command-row clipboard copy, and Labs Project Hooks overview-first rows.
 - `make test` also covers AI desktop notification dedupe precedence (env override > Settings saved value > default), Desktop notifications mode persistence through `desktop-notify-mode`, saved-config precedence over live tmux options, `projmux tmux apply` regeneration of `@projmux_desktop_notify_mode`, configured dedupe-window collapse/send behavior, Settings > Notifications AI dedupe preset/custom rows, explicit notify focus consume rules for selected critical rows and older same-pane non-critical AI cleanup, preservation of critical/permission/stop-failure/external/git/k8s rows during bulk cleanup, OS Toast click-to-focus queue consume, WSL Toast protocol handler hidden-launcher registration with `wsl.exe --exec` URI forwarding, and attention clear paths that do not ack the queue.
 - `make test` also covers AI hook runtime action precedence over catalog defaults, runtime quiet for known Codex notify events, runtime notify for known Claude quiet events, generic in-app-only notify rows for known Codex hook events without specialized handlers, suppression of desktop notification and `send-noti` dispatch on that generic path, separation of runtime hook action from catalog install events, Settings > Notifications hook quiet policy display/write behavior without external install/remove execution, hook desktop notification payload parity with the in-app queue text across the shared OS notification payload, normal/transient OS urgency and expiration for critical AI queue rows, and dormant title/capture fallback gating once a pane is hook-active.
-- `make test` also covers Settings > Session State as global settings-only UI with default-off auto-save and no window/pane tree, Settings > Project > Session State project-derived identity plus project auto-save override/effective source rows and distinct Save latest snapshot / Save named snapshot labels, closed-project save disabled reasons, named snapshot portable path conversion, project/global auto-save precedence, Projects > Sessions > State read-only latest/named snapshot overview with window/pane cwd/recipe/agent-resume health, user-facing `projmux session-state` status/save/delete/restore dry-run actions including explicit manual save bypass of disabled autosave and agent resume status/confidence preview, and Project open sidebar startup coverage for Labs opt-in `Start project`, default-off empty creation, Latest snapshot, Named snapshot, Empty session, Back, saved-at row metadata, existing-session skip, startup-before-trust ordering, detached sidebar open continuation before client-scoped separate trust popup handoff without sidebar inline trust UI, trust approve continuation, and trust deny/cancel no-session sidebar refresh behavior.
+- `make test` also covers Settings > Session State as global settings-only UI with default-off auto-save, Sidebar startup picker relocation/compatibility, and no window/pane tree, Settings > Project > Session State project-derived identity plus project auto-save override/effective source rows and distinct Save latest snapshot / Save named snapshot labels, closed-project save disabled reasons, named snapshot portable path conversion, project/global auto-save precedence, Projects > Sessions > State read-only latest/named snapshot overview with window/pane cwd/recipe/agent-resume health, user-facing `projmux session-state` status/save/delete/restore dry-run actions including explicit manual save bypass of disabled autosave and agent resume status/confidence preview, and Project open sidebar startup coverage for Session State opt-in `Start project`, default-off empty creation, Latest snapshot, Named snapshot, Empty session, Back, saved-at row metadata, existing-session skip, startup-before-trust ordering, detached sidebar open continuation before client-scoped separate trust popup handoff without sidebar inline trust UI, trust approve continuation, and trust deny/cancel no-session sidebar refresh behavior.
 - `make test` also covers `projmux shell` usage without startup selector flags, project-context default target lookup from `PROJMUX_CWD` or nearest project marker, explicit `--session` separation from project-derived defaults, and direct empty attach behavior without shell startup picker/replay.
 - `make test` also covers app tmux naming metadata policy: pane border and automatic window rename share the visible pane label expression, AI topic panes feed window tab labels through `@projmux_ai_topic`, shell panes prefer the visible shell command label such as `zsh`, and `projmux shell` disables program-driven window renames while keeping automatic rename enabled.
 - `make test` also covers manual Session State Save snapshot and restore dry-run preview actions, title-first pane preview labels with legacy snapshot fallback, missing-snapshot messaging, and the absence of the removed statusbar State shortcut.
@@ -59,20 +62,21 @@
 - `make test` also covers the Globalization Phase 6 governance guard: Go string-literal audit classification for hardcoded Korean candidates, English user-facing candidates, and ignored literal/data/debug examples; no unapproved runtime Korean literals outside catalog/formatter/test fixtures; `en-US` coverage for every embedded default catalog key; and required `ko-KR` coverage for migrated notify, Settings, picker, welcome, update, and help surfaces.
 - `make test` also covers `projmux ai integrate tmux-bell` dry-run/install/remove tmux command planning, managed `alert-bell` hook append/idempotence/removal, preservation of unmanaged bell hooks, and `projmux ai ingest bell --pane` queue push/metadata/dedupe behavior for non-AI-managed panes.
 - `make test` also covers `projmux ai ingest log` tail/path rendering and bounded JSONL log trimming for ingest diagnostics.
-- `make test` also covers welcome revisit policy: shell `skip_version` gating, `s` skip vs Enter one-run continue, Settings > About > Welcome native viewer, and attach-popup no-duplicate/no-op behavior.
+- `make test` also covers welcome revisit policy: legacy `skip_version` readability without shell suppression, `s` Skip until next vs Enter continue, Settings > About > Welcome native viewer, best-effort shell update cache refresh, and attach-popup no-duplicate/no-op behavior.
 - `make test` also covers `projmux quit` action-picker rows, cancel/close no-op behavior, explicit quit of only app-owned mux runtimes marked by `@projmux_app=1` on the selected `tmux`/`psmux -L projmux` backend, missing/default runtime no-ops, dispatcher wiring, and `Settings > About > Quit projmux` routing through the same picker before any shutdown side effect.
-- `make test` also covers the built-in semantic palette foundation: non-empty fallback truecolor/tmux tokens, distinct action/attention/AI/progress/danger roles, native picker chip/current/titlebar render strings including titlebar frame background/foreground inheritance without separate overlay ANSI, statusbar git/notify/usage/settings palette regressions, attention/pane-border/popup/switch progress color guards, renderer-only lead-mode topic prefix styling, settings/trust/destructive row color guards, Theme settings Phase 0/1 resolver behavior for project/global/fallback source labels, preset fill, explicit token override, invalid-layer warnings, and truecolor-to-tmux mapping, Phase 2 fallback render parity and project/global color isolation for native picker and tmux status/window background adapters, Phase 3 desired font config save/resolve plus unsupported `not applied` status without breaking no-adapter fallback rendering, and Phase 4 Settings theme editing boundaries for project/global resets, project inherit-vs-override labels, effective source labels, and project config theme values feeding the native project popup render path.
+- `make test` also covers the built-in semantic palette foundation: non-empty fallback truecolor/tmux tokens, distinct action/attention/AI/progress/danger roles, native picker chip/current/titlebar render strings including titlebar frame background/foreground inheritance without separate overlay ANSI, statusbar git/notify/usage/settings palette regressions, attention/pane-border/popup/switch progress color guards, renderer-only lead-mode topic prefix styling, settings/trust/destructive row color guards, Theme settings Phase 0/1 resolver behavior for project/global/fallback source labels, preset fill, explicit token override, invalid-layer warnings, and truecolor-to-tmux mapping, Phase 2 fallback render parity and project/global color isolation for native picker and tmux status/window background adapters, native popup-toggle `display-popup -s` body style propagation from the effective theme without touching global popup/shell/status styles, Phase 3 desired font config save/resolve plus unsupported `not applied` status without breaking no-adapter fallback rendering, and Phase 4 Settings theme editing boundaries for project/global resets, project inherit-vs-override labels, effective source labels, and project config theme values feeding the native project popup render path.
 - Current focused unit coverage also includes strict notify SOT behavior
   (TTL does not remove rows, focus success and target-gone clicks ack,
   reconcile reports stale rows), `notify list --live` queue/live explanations, notify sidebar
   two-line card rendering with age/project/window/pane metadata plus focus/ack/non-critical-clear/clear-all
   actions, notify/statusbar/sidebar attention-vs-AI palette assertions including muted stale/gone rows,
-  in-place `a` ack that refreshes the sidebar without
-  focusing, non-critical `x` bulk clear that preserves critical rows, and empty
-  state rendering after all visible non-critical rows are cleared, and `focus` dispatch diagnostics for session fallback, unresolved
+  native picker-session-local `a` ack that refreshes the sidebar without
+  focusing or restarting the picker, non-critical `x` bulk clear that preserves critical rows, empty
+  state rendering after all visible non-critical rows are cleared, and notify queue-write refresh events
+  that update an open native sidebar best-effort without failing queue pushes, and `focus` dispatch diagnostics for session fallback, unresolved
   targets, window fallback, pane fallback, explicit id failures as unresolved exits, and
   notify-only fallback.
-- Picker focused unit coverage includes backend-neutral picker item/action mapping, native title-focused filtering, numeric selection, shared close actions including raw native custom actions, deprecated picker backend value normalization, AI picker title chrome and stable search-key ordering, Settings title chrome and root section order, Settings Labs shell without backend choices plus keybindings compatibility redirect, environment override normalization, compact multi-line metadata gutters with one-column-indented metadata, proportional native scrollbar thumb rendering, native row width clamps that preserve ANSI resets and Korean/wide-cell frame geometry with matched scrollbar/no-scrollbar row budgets including Settings > Appearance AI badge preview rows and parent long emoji preview rows, native app-background coverage for fallback/effective themes across content padding, empty no-footer rows, footer rows, scrollbars, split-preview gaps, reset-to-padding continuation, and Korean Settings > Appearance AI badge style chips/prompt/emoji rows, multiline partial next/previous item row rendering with rendered-row scrollbar units, fixed split-preview and sidebar list viewports with scrollbar tracks, native up/down-family navigation wrap with empty-list safety and PageUp/PageDown/Home/End clamp regression coverage, native mouse down/follow-drag/release behavior, deferred native row updates that preserve filter/selection state, preview tab/control normalization before width clipping, optional native frame titlebars without same-line rule fill and with title/chip gap inheritance guards, titled native Alt-1 sidebar chrome, statusbar-preserving sidebar popup height, native-only compact project sidebar popup sizing, cheap Alt-1 first-paint rows with deferred git/window/attention/preview enrichment, fixed three-line Alt-1 sidebar row geometry across cheap/enriched paints, bulk switch existing-session classification with per-candidate fallback, and notify sidebar title/popup sizing.
+- Picker focused unit coverage includes backend-neutral picker item/action mapping, native title-focused filtering, numeric selection, shared close actions including raw native custom actions, deprecated picker backend value normalization, AI picker title chrome and stable search-key ordering, Settings title chrome and root section order, Settings Labs shell without backend choices plus keybindings compatibility redirect, environment override normalization, compact multi-line metadata gutters with one-column-indented metadata, proportional native scrollbar thumb rendering, native row width clamps that preserve ANSI resets and Korean/wide-cell frame geometry with matched scrollbar/no-scrollbar row budgets including Settings > Appearance AI badge preview rows and parent long emoji preview rows, native app-background and semantic selected/muted/accent/warning/critical role coverage for fallback/effective themes across content padding, empty no-footer rows, footer rows, scrollbars, split-preview gaps, reset-to-padding continuation, and Korean Settings > Appearance AI badge style chips/prompt/emoji rows, multiline partial next/previous item row rendering with rendered-row scrollbar units, fixed split-preview and sidebar list viewports with scrollbar tracks, native up/down-family navigation wrap with empty-list safety and PageUp/PageDown/Home/End clamp regression coverage, native mouse down/follow-drag/release behavior, deferred native row updates that preserve filter/selection state and can repeat from event triggers, preview tab/control normalization before width clipping, optional native frame titlebars without same-line rule fill and with title/chip gap inheritance guards, titled native Alt-1 sidebar chrome, statusbar-preserving sidebar popup height, native-only compact project sidebar popup sizing, cheap Alt-1 first-paint rows with deferred git/window/attention/preview enrichment, fixed three-line Alt-1 sidebar row geometry across cheap/enriched paints, bulk switch existing-session classification with per-candidate fallback, and notify sidebar title/popup sizing.
 - Doctor focused unit coverage includes native Windows psmux dependency policy, Windows `stty` skip behavior, Linux tmux required/stale behavior, and native Windows tmux bell fallback skip diagnostics.
 - psmux focused unit coverage includes Windows native command rendering policy: PowerShell-generated config callbacks quote `projmux.exe` and argv without POSIX shell quoting, direct CreateProcess/C-runtime command-line rendering remains separate from PowerShell and `cmd.exe /c`, and paths/args containing spaces, quotes, backtick, dollar, ampersand, pipe, redirect characters, semicolon, parentheses, braces, caret, percent, and exclamation are pinned as data.
 - psmux app/session foundation focused unit coverage includes `PROJMUX_MUX_BACKEND` and platform-default backend selection, psmux `-L projmux` session create/attach/switch/ephemeral marker command args, list-sessions/list-windows/list-panes minimal inventory parsing, selected-backend app command wiring, and the explicit absence of pane-scoped metadata in psmux inventory rows.

package/docs/ai-agent-shortcuts.md

@@ -22,6 +22,11 @@ projmux ai split --agent codex right
 projmux ai split --agent claude down
 ```
 
+Every direct AI split invocation creates a new managed AI pane for the selected
+agent. Existing Codex, Claude, or Antigravity panes in the same project/session
+are left in place and are not selected by the shortcut. `right` and `down`
+choose where the new pane is created.
+
 Add the separator only when you have extra arguments for the selected agent:
 
 ```sh
@@ -42,18 +47,18 @@ project defaults or current recommendations. If there are no private extra
 arguments, omit the separator entirely; do not leave a trailing bare `--`.
 
 Settings > AI Settings > Enabled agents is the source of truth for whether
-Claude and Codex may be launched. Disabled agents do not appear in the
+Claude, Codex, and Antigravity may be launched. Disabled agents do not appear in the
 selective picker, and direct shortcut commands such as
 `projmux ai split --agent codex right` fail clearly instead of launching. This
 is intentional: shortcuts are thin direct CLI wrappers and must respect the
 same disabled state as hand-written commands.
 
 `--force-agent` is the only override, and it is explicit CLI policy for direct
-`--agent claude|codex` launches. Do not put it in shared picker, default-mode,
-or general shortcut registrations. Use it only in a private one-shot command
-when you deliberately want to launch a disabled agent without changing
-Settings. If every AI agent is disabled, `--agent selective` still offers a
-plain `shell` split and guidance to re-enable Claude/Codex.
+`--agent claude|codex|antigravity` launches. Do not put it in shared picker,
+default-mode, or general shortcut registrations. Use it only in a private
+one-shot command when you deliberately want to launch a disabled agent without
+changing Settings. If every AI agent is disabled, `--agent selective` still
+offers a plain `shell` split and guidance to re-enable Claude/Codex/Antigravity.
 
 `shell` and `selective` are not targets for extra agent arguments. Use them
 without a tail:

package/docs/cli.md

@@ -19,7 +19,7 @@ projmux <command> [args...]
 
 | Command | Purpose |
 | --- | --- |
-| `ai` | Manage tmux AI splits (Codex/Claude) and per-pane status. |
+| `ai` | Manage tmux AI splits (Codex/Claude/Antigravity) and per-pane status. |
 | `attention` | View and manage live tmux pane attention state. |
 | `attach` | Open tmux lifecycle entry helpers. |
 | `current` | Resolve the active tmux pane path. |
@@ -129,9 +129,9 @@ with `--json`. Doctor does not diagnose terminal key delivery; use `projmux
 setup` for that.
 
 `Settings > Notifications > Delivery sources` shows active Codex hooks, Claude,
-and tmux statuses, conflicts, config paths, and copyable AI integration
-install/remove/dry-run commands. Settings does not install or remove external
-Codex, Claude, or tmux notify wiring.
+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.
 
 ## focus
 
@@ -152,6 +152,10 @@ client is attached on that socket, it emits the configured desktop
 notification instead. `--socket` is explicit; when omitted, the socket is
 derived from `$TMUX`.
 
+After a successful tmux focus, `projmux focus` dispatches host-terminal
+osfocus only when Desktop notification mode is `raise`. Modes `off` /
+`none` and `notify` keep focus in tmux without a host-window raise.
+
 `--client` is a preferred origin tmux client. In-app consumers such as the
 status bar and notify sidebar pass the clicked client so focus redirects that
 display first. If that client is gone, focus falls back to an attached client
@@ -202,10 +206,13 @@ projmux notify reconcile [--json]
 - `push` — append (or refresh, with `--id`) one entry. `--ttl` defaults to
   `600` seconds as freshness metadata; it does not remove rows from
   `notify list`. `--text` is hard-capped to 80 runes (longer text is
-  truncated server-side). After a successful queue write, projmux fires
-  declarative `[hooks.send-noti]` asynchronously if configured. That hook gets
-  a JSON payload on stdin plus `PROJMUX_NOTIFY_*` env vars, and it does not
-  replace the normal desktop notification path.
+  truncated server-side). After a successful queue write, projmux sends a
+  best-effort refresh event to open native notify sidebars and fires
+  declarative `[hooks.send-noti]` asynchronously if configured. Event delivery
+  failure does not fail the queue write; reopening the sidebar still shows the
+  latest queue. The hook gets a JSON payload on stdin plus
+  `PROJMUX_NOTIFY_*` env vars, and it does not replace the normal desktop
+  notification path.
 - `list` — newest-first pending queue table `ID AGE SEV SRC TARGET TEXT`
   (or JSON). `--severity` and `--source` are repeatable filters.
   `--live` adds a non-mutating explanation table (or JSON report) that
@@ -215,10 +222,13 @@ projmux notify reconcile [--json]
   queue entries whose live pane no longer matches. `--ui=sidebar` opens the
   compact interactive notify list where Enter focuses and acks a target, `a`
   acks the selected row, `x` clears non-critical rows, and `Ctrl-X` clears all;
-  opening or navigating the sidebar does not ack. 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.
+  opening or navigating the sidebar does not ack. 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.
 - `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
@@ -234,7 +244,7 @@ Authoritative AI token usage. See [usage-tracking.md](usage-tracking.md)
 for adapter detail.
 
 ```
-projmux usage [--model codex|claude|all] [--window 5h|weekly|all]
+projmux usage [--model codex|claude|antigravity|all] [--window 5h|weekly|all]
               [--json] [--force|-f]
 ```
 
@@ -245,6 +255,11 @@ 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 supported 5-hour/weekly quota adapter. `--model
+antigravity` renders an explicit unsupported note: the stable Antigravity
+signal is `context-window-only` statusline data, which is not mixed into the
+Claude/Codex quota HUD.
+
 ## status
 
 Per-segment status-bar renderers. All four are silent on failure — the
@@ -321,7 +336,7 @@ supplied window.
 ## ai
 
 ```
-projmux ai split    [--agent <claude|codex|shell|selective>] [--force-agent] [right|down] [-- <extra-arg>...]
+projmux ai split    [--agent <claude|codex|antigravity|shell|selective>] [--force-agent] [right|down] [-- <extra-arg>...]
 projmux ai picker   --inside <right|down>
 projmux ai settings
 projmux ai status   set <thinking|waiting|idle> [--pane <id>]
@@ -329,6 +344,7 @@ 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   bell --pane <pane_id>
 projmux ai ingest   log [--tail N] [--json] [--path]
 projmux ai integrate codex [--dry-run] [--remove]
@@ -351,21 +367,25 @@ yellow respectively. That palette is independent from notify queue
 can still render a non-red action-required status badge.
 
 `ai split right|down` uses the configured default split mode. Add
-`--agent claude`, `--agent codex`, `--agent shell`, or `--agent selective` for
-a one-shot launch without changing that default. `--agent selective` opens the
-existing picker flow; `--agent shell` opens the existing plain shell split.
-Arguments after `--` are extra arguments appended to the resolved `claude` or
-`codex` executable inside the managed wrapper; projmux still sets the context
-directory, tmux title, AI pane metadata, title watcher, and split layout.
-Settings > AI Settings > Enabled agents controls Claude/Codex launch
+`--agent claude`, `--agent codex`, `--agent antigravity`, `--agent shell`, or
+`--agent selective` for a one-shot launch without changing that default.
+Concrete `--agent claude|codex|antigravity` invocations create a new managed
+agent pane every time; existing managed AI panes in the same project/session are
+not selected or reused.
+`--agent selective` opens the existing picker flow; `--agent shell` opens the
+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.
+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
-instead of falling back to another agent. Direct `--agent claude|codex` launches
-also fail when disabled, including shortcuts that call the same command. For a
-deliberate one-shot direct CLI launch, pass `--force-agent`; picker and saved
-default paths do not use this override. If all AI agents are disabled, the
-selective picker still offers the plain `shell` split and shows guidance to
-re-enable Claude/Codex.
+instead of falling back to another agent. Direct
+`--agent claude|codex|antigravity` launches also fail when disabled, including
+shortcuts that call the same command. For a deliberate one-shot direct CLI
+launch, pass `--force-agent`; picker and saved default paths do not use this
+override. If all AI agents are disabled, the selective picker still offers the
+plain `shell` split and shows guidance to re-enable Claude/Codex/Antigravity.
 For user-level skill, slash-command, editor, or launcher registrations that
 call this contract, see [AI Agent Shortcuts](ai-agent-shortcuts.md).
 
@@ -425,6 +445,28 @@ 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`.
+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`. Usage quota HUD
+support remains unsupported because the only stable usage signal is
+`context-window-only` statusline data. Transcript contents are not read.
+
 `ingest bell --pane <pane_id>` is the narrow tmux-bell fallback ingest path.
 It does not require the pane to be AI-managed. Projmux resolves session,
 window, pane, title, command, and socket metadata from tmux, pushes an info
@@ -637,10 +679,13 @@ latest/update/cache result. `--json` emits the same machine-readable
 status shape for both subcommands.
 
 `projmux shell` reads the same cache before opening the isolated tmux app.
-When the cache is fresh, an update is available, and the installer supports
-`update apply`, shell startup shows a small picker with Update Now, Later,
-and Skip This Version actions. This startup prompt never reaches the network;
-run `projmux update check` first when you want it to see the newest release.
+When the cache is missing or stale, shell startup attempts a bounded
+best-effort refresh, then continues even if the network check fails. When a
+fresh cached update is available, the shell welcome uses Enter=Continue,
+`u`=Upgrade, and `s`=Skip until next. Upgrade invokes only
+`projmux update apply`; Skip until next writes the latest release tag to
+`${XDG_CACHE_HOME:-~/.cache}/projmux/update-skip.json` and suppresses that tag
+until a newer latest release appears.
 
 Installer detection honors
 `PROJMUX_INSTALLER=npm|go|github-release|source`. When unset or invalid,
@@ -675,9 +720,8 @@ installs.
 projmux welcome [--popup [--force]]
 ```
 
-Prints the onboarding shell guide (`projmux shell` welcome view) without
-starting tmux. This is useful when you want to revisit the key/shortcut/update
-walkthrough at any time.
+Prints the shell-entry release prompt and bootstrap reminder without starting
+tmux. This is useful when you want to revisit the welcome view at any time.
 
 `--popup` is the tmux attach-helper form. It shows the popup only when a
 pending attach welcome marker exists. `--popup --force` opens the popup without
@@ -710,7 +754,7 @@ flags with the top-level `switch` UX:
   tmux default shell when set, otherwise `/bin/sh`. `shell` starts or attaches
   the app session directly after resolving the target app session name and
   startup directory. Alt-1 sidebar project open defaults to `Empty session`; the
-  Labs `Sidebar startup picker` opt-in shows `Latest snapshot`, `Named
+  Session State `Sidebar startup picker` opt-in shows `Latest snapshot`, `Named
   snapshot`, and `Empty session` before creating a closed project session.
   `Latest snapshot` is auto-saved; named snapshots are fixed until the user
   saves or replaces them.

package/docs/configuration.md

@@ -127,6 +127,12 @@ do not break. Settings preserves existing prefix entries when rewriting the
 file, but does not create new prefix keys, and generated tmux config no longer
 binds the old action prefix chords.
 
+Settings > Keybindings names `AISplitPickerToggle` as the AI split popup
+picker toggle. That action opens or closes the picker UI and is separate from
+the direct AI pane actions, `ai-split-right` and `ai-split-down`. The direct
+actions create a new managed AI pane each time they run, leaving existing AI
+panes in place. `right` and `down` choose where the new pane is created.
+
 Use an empty `keys` list to disable direct plain aliases for the action when
 editing the file by hand:
 
@@ -183,6 +189,14 @@ picker frames also apply the built-in fallback `background`/`foreground` tokens
 so picker-owned padding, empty rows, footer rows, and preview gaps do not
 inherit the terminal default background.
 
+Native picker popups launched through `projmux tmux popup-toggle` also pass a
+per-popup tmux 3.4 `display-popup -s` body style using the effective theme
+`background`/`foreground` tmux tokens. This styles only the tmux popup body
+before the native renderer draws. It does not set global `popup-style` or
+`popup-border-style`, and it does not change shell pane backgrounds,
+`default-style`, `window-style`, OSC terminal backgrounds, or the general
+status/window palette.
+
 Resolver schema shape:
 
 ```toml
@@ -273,11 +287,12 @@ user/global preference in this release.
 | `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. |
 
 ## Welcome State
 
-`projmux shell` stores per-version welcome state under the projmux state
-directory, normally:
+`projmux shell` still reads and rewrites legacy per-version welcome state under
+the projmux state directory for attach-popup compatibility, normally:
 
 ```text
 ${XDG_STATE_HOME:-$HOME/.local/state}/projmux/welcomed-v<version>.json
@@ -295,11 +310,21 @@ The current schema is:
 }
 ```
 
-`skip_version` is the only field that suppresses the shell welcome. When it
-matches the current projmux version, `projmux shell` skips the welcome. When it
-is absent or names a different version, the welcome is shown again. Older state
-files that contain only `last_welcomed_version` remain readable, but that field
-does not count as a skip.
+This file no longer suppresses the shell-entry welcome. `skip_version` and
+`last_welcomed_version` remain readable for legacy state and pending attach
+popup compatibility, but the automatic shell prompt now uses release skip state
+instead.
+
+Update prompt skips are stored by latest release tag under the update cache
+directory:
+
+```text
+${XDG_CACHE_HOME:-$HOME/.cache}/projmux/update-skip.json
+```
+
+When `tag_name` matches the fresh cached latest release tag, `projmux shell`
+continues without offering the update actions. A newer latest tag makes the
+prompt eligible again.
 
 Example:
 
@@ -401,7 +426,9 @@ only a generic in-app queue/sidebar/statusbar row; it does not fire OS toast,
 The OS-level dispatch carries three modes. The in-app notify queue, the
 statusbar segment, and the attention badge stay live regardless of which
 mode is active — only the toast / notify-send / auto-raise fan-out is
-gated here.
+gated here. The same mode also gates `projmux focus` post-switch osfocus
+dispatch: only `raise` asks the host terminal to come forward after a
+successful tmux focus.
 
 | Mode | On push | On click |
 | --- | --- | --- |
@@ -413,7 +440,8 @@ Click activation is wired only for `raise`. The `projmux://` URI handler is
 registered on the first `raise` Notify of each tmux server (gated by the
 `@projmux_uri_protocol_registered_v6` marker). The
 mode only controls whether a toast fires at all and whether to follow it
-up with an on-push auto-raise.
+up with an on-push auto-raise. `off` / `none` and `notify` also suppress
+the focus-triggered osfocus raise after `projmux focus`.
 
 Resolution order (highest priority first):
 
@@ -551,8 +579,8 @@ while `on` and `off` take precedence. Auto-save only updates the latest
 snapshot. Named snapshots are manual and are never updated by auto-save.
 
 Project open from the Alt-1 sidebar defaults to opening a closed project as an
-`Empty session`. The optional `Settings > Labs > Sidebar startup picker` toggle
-enables the native sidebar `Start project` step. Rows appear as `Latest
+`Empty session`. The optional `Settings > Session State > Sidebar startup
+picker` toggle enables the native sidebar `Start project` step. Rows appear as `Latest
 snapshot`, named snapshot rows, `Empty session`, and `Back`. `Latest snapshot`
 is the snapshot auto-save that changes as auto-save runs; named snapshots are
 fixed snapshots. Rows include saved-at date/time metadata when projmux can
@@ -571,7 +599,7 @@ Default `projmux shell` no longer opens a startup picker or replays session-stat
 snapshots before attach. It still derives the default app session identity and
 startup directory from the current project context when available; otherwise it
 uses the `home` target and home directory. Session-state restore selection is
-limited to the Labs sidebar startup picker.
+limited to the Session State sidebar startup picker.
 
 Settings > Session State is global settings only: global auto-save, auto-save
 interval, and storage/retention policy. Settings > Project > Session State

package/docs/hooks.md

@@ -606,6 +606,39 @@ Codex and are managed from `Settings > Notifications > Hook quiet policy`.
 They only affect ingest delivery; `projmux ai integrate claude` still uses the
 catalog `install` field for installed hook events.
 
+## Antigravity Hook Ingest
+
+`projmux ai ingest antigravity-hook < payload.json` is available for manual
+Antigravity CLI `agy` hook/statusline payloads. Projmux does not provide
+`projmux ai integrate antigravity`, does not install Antigravity hooks, and
+does not mutate Antigravity user config. The Delivery sources diagnostic
+therefore reports Antigravity as a read-only unsupported/manual row. If users
+wire it by hand, use an absolute `projmux` command path or a known cwd because
+relative command paths failed the Phase 0b smoke.
+
+The default known Antigravity catalog records only observed Phase 0b signals
+and marks them `install: false`:
+
+| Event/signal | Behavior |
+| --- | --- |
+| `PostInvocation` | marks the matched pane hook-active and writes a quiet ingest diagnostic; no notify queue entry is pushed |
+| `Stop` | pushes a completion row, or a critical error row when `error` is present or `terminationReason` is non-normal |
+| `Statusline` with `tool_confirmation_pending=true` | pushes a critical approval row; this is only active when a statusline/manual status payload is wired to ingest |
+| `Statusline` without `tool_confirmation_pending=true` | marks the matched pane hook-active and writes a quiet ingest diagnostic |
+| unknown events | mark the matched pane hook-active and write quiet ingest diagnostics only |
+
+Antigravity notify rows use `agent=antigravity` metadata. Accepted fields
+include `conversationId`/`conversation_id`, `cwd`, `workspace.path`,
+`transcriptPath`, `terminationReason`, `error`, `fullyIdle`, `agent_state`,
+`context_window`, and nested `statusline.tool_confirmation_pending`.
+Antigravity ingest uses `conversationId` as pane thread metadata for matching
+and as session-state resume metadata. Session restore uses
+`agy --conversation <uuid>` only when that id is present and UUID-shaped;
+otherwise preview and doctor render `resume unavailable`. Antigravity usage
+quota HUD support remains unsupported because the stable usage signal is
+`context-window-only` statusline data, not 5-hour/weekly quota data. Raw
+payloads or transcript contents are not stored.
+
 ## Ingest Debug Log
 
 Every `projmux ai ingest ...` path appends compact JSONL diagnostics to

package/docs/install.md

@@ -28,14 +28,14 @@ projmux shell
 ```
 
 Each `projmux shell` launch prints a short welcome with the current version,
-detach/exit keys, core app shortcuts, and cached update status when available.
-Press Enter to continue for this run, or press `s` to skip the welcome for the
-current projmux version. The next projmux version shows the welcome again.
-
-If an installer-supported update is available, the same prompt keeps update
-actions separate from welcome skip: press `u` to run `projmux update apply`,
-`n` to print the manual update command, or `d` to skip daily update prompts for
-that release.
+detach/exit keys, a bootstrap reminder, and cached release status when
+available. Press Enter to continue into the shell.
+
+If an update is available, the same shell-entry prompt uses one action
+vocabulary: Enter continues, `u` upgrades by invoking `projmux update apply`,
+and `s` skips that latest release tag until a newer tag appears. For `source`
+or unknown installer sources, `u` prints installer guidance and then continues
+shell entry.
 
 To revisit the guide later, run `projmux welcome`, or use Settings > About >
 Welcome inside the app to open it in a visible viewer. Set `PROJMUX_WELCOME=off` before

package/docs/keybindings.md

@@ -33,7 +33,7 @@ These shortcuts are the guaranteed launch defaults. They need no tmux prefix.
 | `Alt-1` | Project sidebar |
 | `Alt-2` | Notify sidebar |
 | `Alt-3` | Existing session popup |
-| `Alt-4` | AI split picker |
+| `Alt-4` | AI split popup picker |
 | `Alt-5` | Settings |
 
 The tmux prefix remains the upstream default `Ctrl-b`. Inside a running
@@ -57,9 +57,20 @@ Optional direct aliases can be added for actions such as:
 | Canonical action | Meaning |
 | --- | --- |
 | `ProjectSwitcherToggle` | Project switcher popup |
+| `AISplitPickerToggle` | AI split popup picker; pressing again closes the picker popup |
+| `ai-split-right` | Open a new direct AI split to the right |
+| `ai-split-down` | Open a new direct AI split below |
 | `new-window` | New tmux window in the current pane directory |
 | `rename-window` | Rename the current tmux window |
 
+`AISplitPickerToggle` is the `Alt-4` popup picker toggle. It opens or closes
+the picker UI where the user chooses the AI split mode. It is separate from
+the direct `ai-split-right` and `ai-split-down` actions.
+
+The direct AI split actions create a new managed AI pane each time they run.
+Existing AI panes are left in place; the requested direction controls where the
+new pane is created.
+
 Pane switching is catalogued as transport-dependent and the generated app tmux
 config binds `M-Left`, `M-Right`, `M-Up`, and `M-Down` to `select-pane`
 movement. Previous/next window remain transport-dependent and the generated app
@@ -132,7 +143,9 @@ Legacy popup IDs such as `sessionizer-sidebar`, `notify-sidebar`,
 `session-popup`, `ai-split-picker-right`, `ai-split-settings`, and
 `sessionizer` still read. Settings and new docs show the canonical toggle
 names: `ProjectSidebarToggle`, `NotifySidebarToggle`, `SessionPopupToggle`,
-`AISplitPickerToggle`, `SettingsToggle`, and `ProjectSwitcherToggle`.
+`AISplitPickerToggle`, `SettingsToggle`, and `ProjectSwitcherToggle`. Direct
+AI split actions keep their command IDs, `ai-split-right` and `ai-split-down`,
+so Settings can distinguish them from the `Alt-4` popup picker toggle.
 
 ## Diagnose: `projmux setup`
 

package/docs/native-picker-parity.md

@@ -32,6 +32,7 @@ native picker engine and is not a public dependency-policy change.
 | close `--bind key:abort` | Esc, Ctrl-C, Alt-N, Ctrl-Alt-S variants | Covered | `CloseActions`; `TestNativeRunnerUsesSharedCloseActions` |
 | terminal modified-key encoding | legacy parser fixtures, Ghostty/kitty-style modified keys | Covered | native handles app-specific parser fixtures, generic modified letters/digits, and non-text keys such as Enter/Esc/Backspace/Tab; this is backend parity, not product fallback guidance; `TestNativeInteractiveSupportsCSIuAppKeyBindings` |
 | `execute-silent(...)+refresh-preview` | switch/session preview cycling | Covered for command execution and rerender loop | `pickercompat.PickerOptions`/`pickercompat.OptionsFromPicker`; `TestNativeInteractiveRunsCustomActionCommandAndRefreshes`; `TestPickerOptionsMapsCompatBindingsToContractActions`; Docker no-fzf e2e sends `Right` and `Alt-Down` before selection |
+| action-local/event-backed mutable refresh | notify sidebar `a` ack and `x` non-critical clear; notify sidebar queue-write event refresh; switch sidebar `Ctrl-X` kill | Covered for in-session row/live-state refresh without picker restart | `picker.Action.Mutate` returns a `DeferredUpdate`, notify queue-write events trigger the same `DeferredUpdate` path after an event arrives, and both reuse the native frame diff renderer plus value-then-clamp selection preservation; `TestNativeInteractiveCustomActionMutatesItemsAndRefreshes`; `TestNativeInteractiveCustomActionRefreshPreservesSelectedValue`; `TestNativeInteractiveDeferredUpdateTriggerRefreshesRepeatedly`; notify sidebar app tests assert one picker invocation with refreshed rows/live state and event subscription; switch sidebar kill app tests assert one native picker invocation with refreshed rows/preview and previous-live-session guard preservation |
 | `focus:execute-silent(...)` | switch sidebar focus | Covered | native renders the selection frame diff before running sidebar focus commands so movement stays visible before tmux focus side effects; `runNativeFocusAction`; `TestNativeInteractiveRunsFocusActionOnSelectionChange` |
 | `start:pos(N)` | switch sidebar initial row | Covered | `pickercompat.PickerOptions`/`pickercompat.OptionsFromPicker`; `TestPickerOptionsFromCompatPickerMapsStartPosToInitialIndex`; `TestPickerOptionsMapsCompatBindingsToContractActions` |
 | `--preview` | switch, sessions | Covered by command output | `nativePreviewLines`; `TestNativeInteractiveRendersSelectedPreview` |
@@ -47,7 +48,7 @@ native picker engine and is not a public dependency-policy change.
 | alternate-screen lifecycle | fzf fullscreen picker screen restore | Covered | native frame updates and screen exit return to column 0 before terminal control sequences, screen exit resets styles plus clears the alternate buffer from the home cursor before restore, and real TTY restores get a short settle window before caller handoff; `nativeScreenEnter`; `TestNativeInteractiveUsesAlternateScreen`; `TestRenderFullFrameUpdateAlwaysHomesAndWritesFrame` |
 | frame content width | fzf border inner width | Covered | `ContentLayout` uses the frame inner width so separators and rows reach the right border; `TestRendererContentLayoutUsesFrameInnerWidth` |
 | picker-owned app background | native picker frame interior | Covered for renderer-owned cells | `ThemeFromEffective` applies built-in fallback and explicit effective background/foreground SGR to the native frame, and frame rows resume the app style after embedded resets so content padding, empty no-footer rows, footer rows, scrollbars, and preview gaps do not leak terminal default background; `TestThemeFromEffectiveFallbackPaintsFrameBackground`; `TestRendererFrameBackgroundResumesAfterContentResetBeforePadding`; `TestNativeInteractiveNoFooterBlankRowsUseThemeBackground`; `TestNativeInteractiveSplitPreviewGapsUseThemeBackground`; `TestNativeInteractiveSettingsAIBadgeStyleLongPreviewClampsFrameRows` |
-| tmux popup frame interaction | native picker popups launched through `popup-toggle` | Covered for native backend popups | `popup-toggle` passes tmux `display-popup -B` when `PROJMUX_PICKER_BACKEND=native`, so the native picker owns the visible frame instead of double-drawing with the tmux popup border; native Alt-1 uses a compact native-only minimum while fzf keeps the previous project sidebar minimum; Alt-1/Alt-2 sidebar heights reserve two bottom statusbar rows; Alt-2 notify sidebar keeps the fzf-like `24%` / min `64` baseline; `TestAppRunTmuxPopupToggleUsesBorderlessPopupForNativeBackend`; `TestSessionizerSidebarWidthKeepsFZFMinimum`; `TestSidebarPopupHeightLeavesStatusbarRows`; `TestNotifySidebarWidthMatchesFZFBaseline`; `TestAppRunTmuxPopupToggleKeepsNotifySidebarFZFSizingForNative` |
+| tmux popup frame interaction | native picker popups launched through `popup-toggle` | Covered for native backend popups | `popup-toggle` passes tmux `display-popup -B` when `PROJMUX_PICKER_BACKEND=native`, so the native picker owns the visible frame instead of double-drawing with the tmux popup border; tmux 3.4 per-command `display-popup -s` is used for the popup body style, setting `bg`/`fg` from the same effective theme tmux background/foreground tokens so tmux's blank/pre-draw popup body matches the native picker surface before the app renderer paints; no global `popup-style`, `popup-border-style`, shell pane background, `default-style`, `window-style`, OSC background, or status/window palette options are changed; native Alt-1 uses a compact native-only minimum while fzf keeps the previous project sidebar minimum; Alt-1/Alt-2 sidebar heights reserve two bottom statusbar rows; Alt-2 notify sidebar keeps the fzf-like `24%` / min `64` baseline; `TestAppRunTmuxPopupToggleUsesBorderlessPopupForNativeBackend`; `TestAppRunTmuxPopupToggleUsesNativePopupBodyStyleFromEffectiveTheme`; `TestBuildPopupToggleWithPickerBackendStylesNativeOnly`; `TestBuildDisplayPopupArgsAddsBodyStyle`; `TestSessionizerSidebarWidthKeepsFZFMinimum`; `TestSidebarPopupHeightLeavesStatusbarRows`; `TestNotifySidebarWidthMatchesFZFBaseline`; `TestAppRunTmuxPopupToggleKeepsNotifySidebarFZFSizingForNative` |
 | optional native titlebar | native picker popup frame | Covered for empty-title compatibility and opt-in titles | `picker.Options.Title`; `RenderFrameWithTitle`; `ContentLayoutWithTitle`; empty titles keep the prior frame unchanged, non-empty titles render in a picker-owned section below the top border, titlebar text/divider/chip gaps inherit the frame background/foreground instead of a separate titlebar overlay ANSI layer, and the native Alt-1 project sidebar opts into `Projects`; `TestRendererRenderFrameWithTitleKeepsDefaultWhenTitleEmpty`; `TestRendererRenderFrameWithTitleUsesTitlebarRow`; `TestRendererContentLayoutWithTitleReservesTitlebarRow`; `TestNativeInteractiveRendersOptionalTitlebar`; `TestSwitchCommandNativeSidebarSetsTitle` |
 | redraw flicker/top clipping | keyboard navigation in exact-height tmux popup | Partially covered | native redraws use synchronized updates plus coalesced row diffs after the first frame, skip unchanged frames, render frame diffs before sidebar focus commands, frame rendering avoids trailing bottom-border CRLF, and screen exit clears the alternate buffer before restore; `TestNativeInteractiveWrapsRedrawsInSynchronizedUpdates`; `TestFrameUpdateRendererSkipsUnchangedFrame`; `TestFrameUpdateRendererCoalescesEachFrameUpdate`; `TestRendererRenderFrameUsesCRLFRowsForRawTTY`; `TestNativeInteractiveUsesAlternateScreen` |
 
@@ -110,8 +111,10 @@ contract; native popups still rely on the existing borderless tmux popup path.
   the right-side preview layout instead of inline preview, asserts the stored
   preview cursor, selects `bravo-web`, and asserts tmux reports the selected
   session's active target on the expected window with the expected pane path.
-- `notify sidebar`: native routing is unit-covered; Docker no-fzf e2e pushes a
-  notification, presses printable expect key `a`, and verifies the row is acked.
+- `notify sidebar`: native routing is unit-covered; app tests cover
+  queue-write event subscription and picker tests cover repeated
+  event-triggered deferred refresh. Docker no-fzf e2e pushes a notification,
+  presses printable expect key `a`, and verifies the row is acked.
 
 ## Experimental Boundaries
 

package/docs/notify-queue.md

@@ -13,6 +13,7 @@ via `projmux focus`, and feeds the HUD pill rendered by
 ```
 ${XDG_STATE_HOME:-$HOME/.local/state}/projmux/notify.json
 ${XDG_STATE_HOME:-$HOME/.local/state}/projmux/notify.json.lock
+${XDG_STATE_HOME:-$HOME/.local/state}/projmux/notify-queue-events/refresh-*.sock
 ```
 
 The lock file is acquired via `O_CREATE|O_EXCL` with bounded retry
@@ -24,6 +25,13 @@ The queue file is a pretty-printed JSON array of `Notification`
 objects, sorted newest-first on read. `expires_at` is freshness metadata;
 expired entries are not filtered or deleted by `list`.
 
+Open native notify sidebars also create per-process Unix datagram sockets for
+queue-write refresh events. If the state-dir socket path would exceed Unix
+socket path limits, projmux uses a short per-state-dir temp runtime path for
+the socket directory. These sockets are transient UI delivery endpoints only:
+they are not queue state, do not change the JSON schema, and are removed when
+the sidebar exits.
+
 ## Data model
 
 `internal/core/notify`:
@@ -58,11 +66,17 @@ exit code 2.
 routing/debug context such as `agent`, `thread_id`, `turn_id`, `cwd`,
 `model`, and `client`; Claude hook rows also carry event-specific keys such as
 `tool_name`, `tool_input.command`, `error_type`, `subagent_type`, and
-`teammate_name`. Tmux bell fallback rows carry `agent=bell`, `event=bell`,
-and tmux target context such as pane title, command, session, window, pane, and
-socket. `notify list --json` includes this metadata as the structured data
-channel while human table/sidebar output keeps the compact text body. Existing
-entries without metadata remain valid.
+`teammate_name`. Antigravity manual hook rows carry `agent=antigravity`,
+`conversation_id`, `termination_reason`, `fully_idle`,
+`tool_confirmation_pending`, `agent_state`, and `context_window` when present.
+The same `conversation_id` can seed session-state restore via
+`agy --conversation <uuid>` when it is UUID-shaped; Antigravity quota usage
+remains unsupported because `context_window` is not 5-hour/weekly quota data.
+Tmux bell fallback rows carry `agent=bell`, `event=bell`, and tmux target
+context such as pane title, command, session, window, pane, and socket.
+`notify list --json` includes this metadata as the structured data channel
+while human table/sidebar output keeps the compact text body. Existing entries
+without metadata remain valid.
 
 ## CLI surface
 
@@ -100,11 +114,22 @@ pane and acks the row after focus succeeds. The surface actions
 are edited in Settings, while internal picker aliases are adjusted in
 `keymap.toml` when needed. Runtime footer key guides read the merged keymap
 and show the default alias when present, otherwise the first configured alias,
-so custom aliases do not make the UI stale. Rows are intentionally compact: the visible label keeps
+so custom aliases do not make the UI stale. `NotifySidebar:Ack` and
+`NotifySidebar:ClearNonCritical` refresh rows, live state, and selection inside
+the same native picker session; `NotifySidebar:ClearAll` still closes the
+popup and prints a summary. Rows are intentionally compact: the visible label keeps
 notification text first, then age, project, window, and pane metadata; hidden
 queue ids remain action values but the sidebar has no search input and
 intentionally does not expose a separate metadata detail view.
 
+When a new pending notification is successfully pushed by any app producer
+(`notify push`, reply-ready, reconcile backfill, or bell fallback), open native
+notify sidebars receive a best-effort queue-write event and rerun the same
+`DeferredUpdate` row/live-state refresh path used by `a` ack and `x`
+non-critical clear. Event delivery errors are ignored after the queue write:
+the push still succeeds, and reopening the sidebar remains the recovery path
+for seeing the latest queue.
+
 `--live` adds a non-mutating explanation view that reads
 `tmux list-panes -a` and compares the queue with live reply-state panes. It
 does not push, ack, or otherwise repair anything. Human output keeps the
@@ -153,6 +178,9 @@ path), then:
 - reports every existing queue entry whose id starts with `ai:` and whose
   pane no longer matches that condition as stale, without acking it.
 
+Successful backfill pushes publish the same best-effort open-sidebar refresh
+event as other pending queue additions.
+
 Soft-fails when tmux is not running (returns a populated `errors`
 field rather than a non-zero exit) so the post-install hook does not
 break. Run this as the recovery path when the on-disk queue has drifted
@@ -180,7 +208,10 @@ an entry with:
 When the pane leaves the reply state (manual `attention clear`,
 `status set idle`, or a window close), `AckReplyReady` intentionally does not
 remove the entry. The user consumes it through explicit ack. Store errors are
-swallowed so the live tmux UI never blocks on disk IO.
+swallowed so the live tmux UI never blocks on disk IO. After a successful
+queue write and same-pane non-critical compaction, the producer publishes the
+same best-effort notify-sidebar queue-write refresh event used by
+`projmux notify push`.
 
 Manual `projmux attention toggle` on a pane without an agent option
 does NOT push — the queue is intentionally AI-driven; reconcile honours
@@ -200,7 +231,9 @@ tmux and writes an info/source-ai row with:
 Unlike reply-ready reconcile, bell ingest does not require AI pane metadata.
 It is intentionally available for arbitrary CLIs that only signal attention
 through BEL or OSC 9. Repeated bells from the same pane are suppressed for 5
-seconds before a later bell refreshes the stable queue id.
+seconds before a later bell refreshes the stable queue id. Successful
+non-deduped bell queue writes publish the same best-effort open-sidebar
+refresh event as other pending queue additions.
 
 ## Consumer (status-bar click)
 
@@ -230,8 +263,11 @@ Outcomes:
 
 The same consume policy is shared by notify-sidebar Enter and OS
 click-to-focus Toast callbacks after a real tmux focus dispatch succeeds.
+OS Toast click-to-focus is only registered when Desktop notification mode is
+`raise`; the in-app sidebar/statusbar consume path works in every mode.
 Pane focus hooks and attention clear paths remain live-attention-only and do
-not ack the notify queue. Non-critical AI completion producers also compact
+not ack the notify queue; their response-complete badge consume is limited to
+live tmux pane badge/state options. Non-critical AI completion producers also compact
 older same-pane non-critical AI rows after replacing/pushing their latest row,
 so reply-ready/stop/bell-style completion rows stay latest-state centered
 without changing the queue schema or TTL contract.

package/docs/session-restore.md

@@ -51,8 +51,12 @@ CLI for inspection/actions.
 Agent restore direct-starts supported resume commands when creating fresh tmux
 panes, matching the `projmux ai split` wrapper shape: the wrapper prepends the
 agent binary directory to `PATH`, changes to the saved cwd, sets the terminal
-and tmux pane title from the saved agent topic, then execs `codex resume <id>`
-or `claude --resume <id>`. This avoids typing agent resumes with
+and tmux pane title from the saved agent topic, then execs `codex resume <id>`,
+`claude --resume <id>`, or `agy --conversation <uuid>`. Antigravity restore
+uses only the stable statusline `conversation_id` or hook `conversationId`
+metadata captured as the pane resume id; missing or non-UUID Antigravity ids
+render as `resume unavailable` rather than falling back silently to a shell
+recipe. This avoids typing agent resumes with
 `tmux send-keys`. The restore wrapper is still a non-interactive shell command
 tail, so it does not replay the original pane's interactive shell startup,
 environment, shell functions, aliases, or live process state. Startup recipes
@@ -74,7 +78,7 @@ when building `Named snapshot` candidates; new primary surfaces should describe
 the restore unit as a snapshot, not as a separate layout or preset feature.
 
 Project open from the Alt-1 sidebar defaults to opening a closed project as an
-`Empty session`. `Settings > Labs > Sidebar startup picker` is an opt-in toggle;
+`Empty session`. `Settings > Session State > Sidebar startup picker` is an opt-in toggle;
 when it is on, closed project open advances inside the sidebar to the native
 `Start project` step. Rows are ordered `Latest snapshot`, named snapshot rows,
 `Empty session`, then `Back`. `Latest snapshot` is the auto-saved snapshot that
@@ -98,5 +102,5 @@ directly without a startup picker or trust gate.
 Default `projmux shell` no longer opens a compatibility startup picker and no
 longer accepts startup selector flags for session-state restore. It always
 follows the normal empty attach path after resolving the target app session name
-and startup directory. Use `Settings > Labs > Sidebar startup picker` for
+and startup directory. Use `Settings > Session State > Sidebar startup picker` for
 interactive Latest snapshot / Named snapshot / Empty session selection.

package/docs/settings-ia.md

@@ -62,6 +62,10 @@ view-first layout:
   runtime action values and writes only
   `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/ai-hook-actions.json`. It does not
   edit catalog `install` values or run agent install/remove commands.
+- `Settings > Session State > Sidebar startup picker` controls the Alt-1
+  project-open startup selector. The saved file remains
+  `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/sidebar-startup-picker`, and the
+  stale `labs:sidebar-startup-picker` action opens this Session State detail.
 - `Settings > Labs` keeps experimental toggles, but keybindings no longer have a
   visible Labs row. The hidden compatibility action redirects to the
   `Settings > Keybindings` action list, not to a diagnostic default.
@@ -107,5 +111,6 @@ Shell bootstrap UX is phase-split:
 - `projmux welcome` remains the stdout revisit command.
 - `Settings > About > Welcome` opens a visible native viewer independent of
   shell skip state.
-- Shell `skip_version` state applies only to the automatic `projmux shell`
-  prompt; it does not hide manual revisit surfaces.
+- Legacy shell `skip_version` state remains readable for compatibility but no
+  longer suppresses the automatic `projmux shell` prompt; release skips live in
+  `update-skip.json` and do not hide manual revisit surfaces.

package/docs/statusbar.md

@@ -46,6 +46,9 @@ row 1  [#S]  #{pane_current_path}  ⎈ <ctx>/<ns>  <git>   %H:%M
   notify queue segment and from notify queue severity or desktop notification
   urgency. For example, an approval request may remain a critical queued
   notification while its live status badge renders action-required amber-orange.
+  Pane focus hooks and `projmux attention clear` consume only the
+  response-complete live badge, including stale `@projmux_ai_state=waiting`
+  fallback state; action-required and in-progress live badges remain visible.
   Window-list badges and app pane-border badges use the same semantic priority,
   with display style controlled by Settings > Appearance > AI badge style and persisted in
   `~/.config/projmux/ai-badge-style`. The default is `dot`; `emoji` renders

package/docs/testing.md

@@ -117,12 +117,15 @@ Observe:
   `"reason":"no-attached-client"`.
 - Windows shows a short projmux toast with `session ready:
   projmux-host-smoke`.
+- In `notify` mode, the toast has no click-to-focus action and should not
+  auto-raise the host terminal.
 - No visible PowerShell or console window remains open after the toast.
 
 If the PR changes click-to-focus behavior, repeat with
 `PROJMUX_DESKTOP_NOTIFY_MODE=raise`, click the toast, and record whether the
-host terminal returns to the target. Otherwise leave click callbacks marked as
-manual/not run.
+host terminal returns to the target. `raise` should also be the only mode where
+`projmux focus` performs post-switch osfocus. Otherwise leave click callbacks
+marked as manual/not run.
 
 ### macOS GUI Notification
 

package/docs/upgrading.md

@@ -3,13 +3,14 @@
 projmux has two update surfaces:
 
 - `projmux shell` reads the cached release status before opening the app. When
-  the cache is fresh and a newer release is available, startup shows a picker
-  with Update Now, Later, and Skip This Version actions.
+  the cache is missing or stale, startup attempts a short best-effort refresh
+  and continues if it fails. When a newer release is available, the shell
+  welcome offers Continue, Upgrade, and Skip until next actions.
 - Settings > About > Update shows the current version, detected installer,
   cached latest version, Check Updates, and Update Now actions.
 
-Startup never reaches the network. Refresh the cache explicitly when you want
-projmux to check GitHub Releases:
+Refresh the cache explicitly when you want a full foreground GitHub Releases
+check:
 
 ```sh
 projmux update check
@@ -24,6 +25,11 @@ projmux update apply
 Use `--dry-run` to see the planned action and `--no-apply` to skip reloading
 the live tmux config after the binary changes.
 
+Shell Upgrade invokes only `projmux update apply`. Shell Skip until next stores
+the current latest release tag in `update-skip.json`; the prompt appears again
+when the cached latest tag changes. For `source` and unknown installer sources,
+Upgrade prints guidance and continues shell entry without applying anything.
+
 ## npm Installs
 
 The recommended install path is:

package/docs/usage-tracking.md

@@ -1,10 +1,26 @@
 # Usage tracking
 
 `projmux usage` and `projmux status usage` report authoritative 5-hour
-and weekly utilisation for both Claude Code and the Codex CLI. Both
-adapters read from the upstream's own view of the account so the
+and weekly utilisation for enabled AI agents. `--model all`, the tmux
+HUD, and the statusbar usage popup use Settings > AI Settings > Enabled
+agents as the source of truth, so disabled Claude/Codex providers are
+not refreshed or rendered on ambient/all surfaces. Explicit read-only
+requests such as `projmux usage --model claude` or `--model codex`
+still collect and render that provider even when it is disabled.
+
+Both adapters read from the upstream's own view of the account so the
 percentages match what `claude /usage` and `codex` show natively.
 
+Antigravity is intentionally not registered as a 5-hour/weekly quota adapter.
+The only stable Phase 0b usage signal is statusline `context_window`, which is
+conversation context-window usage, not account quota usage. `projmux usage
+--model antigravity` and ambient all-model table output therefore render an
+explicit unsupported note when Antigravity is enabled. The statusbar usage
+popup shows an `Antigravity ctx ... unsupported` row, while the compact tmux
+status segment stays silent unless Claude/Codex quota rows exist. Projmux does
+not infer quota, reset timestamps, or account limits from screen scraping,
+tokens, history, OAuth/cache files, or binary strings.
+
 ## Adapters
 
 ### Claude (`internal/core/usage/adapters/claude`)
@@ -79,12 +95,13 @@ across machines (Dropbox, iCloud Drive).
 ### `projmux usage`
 
 ```
-projmux usage [--model codex|claude|all] [--window 5h|weekly|all]
+projmux usage [--model codex|claude|antigravity|all] [--window 5h|weekly|all]
               [--json] [--force|-f]
 ```
 
-Calls `Manager.Collect` (or `ForceCollect` with `--force`), filters by
-model/window, and renders the tab-aligned table:
+For `--model all`, calls `Manager.Collect` (or `ForceCollect` with
+`--force`) only for providers enabled in Settings > AI Settings >
+Enabled agents, filters by window, and renders the tab-aligned table:
 
 ```
 MODEL   WINDOW  PCT   RESETS_AT                STALE
@@ -103,16 +120,27 @@ instead. A backoff note is appended to the human table:
 claude is in backoff, try again in 30m (use --force to bypass)
 ```
 
+When no AI agents are enabled, all-model table output contains no
+provider rows and prints a short Settings hint. `--json` returns an
+empty array. Explicit `--model claude` and `--model codex` bypass the
+enabled-agent filter for read-only inspection and collect/render only
+the requested adapter. Explicit `--model antigravity` renders the same
+unsupported/context-window-only note even when Antigravity is disabled, because
+there is no supported Antigravity quota adapter to collect.
+
 ### `projmux status usage`
 
 ```
 projmux status usage [--max-width N] [--force|-f]
 ```
 
-The HUD bar wired to the tmux status interval. Triggers an
-opportunistic refresh: `MaybeCollect(throttle=30s)` (subject to
-per-adapter throttle and active backoff). Errors are swallowed unless
-`PROJMUX_USAGE_DEBUG` is set. Then loads the cache and renders.
+The HUD bar wired to the tmux status interval. It scopes the registry to
+enabled AI agents, then triggers an opportunistic refresh:
+`MaybeCollect(throttle=30s)` (subject to per-adapter throttle and active
+backoff). Disabled providers are not refreshed just to be hidden. Errors
+are swallowed unless `PROJMUX_USAGE_DEBUG` is set. Then it loads the
+cache, filters to the same enabled-agent scope, and renders. If no AI
+agents are enabled, the status segment emits nothing.
 
 Output degrades through six tiers as `--max-width` shrinks:
 
@@ -132,10 +160,11 @@ because the rollout file is always near-current (no throttle gap to report).
 ### Statusbar usage popup
 
 `projmux statusbar click usage` renders a native-framed popup from the same
-cache instead of shelling out to `projmux usage`. This keeps `projmux usage
---json` backwards-compatible for CLI consumers while giving the tmux click path
-a structured table with aligned rows, right-aligned numeric values, dim
-unavailable cells, amber usage at 80%, and red usage at 95%.
+cache instead of shelling out to `projmux usage`. The popup filters rows and
+sync metadata to the same enabled-agent scope as the ambient HUD. This keeps
+`projmux usage --json` backwards-compatible for CLI consumers while giving the
+tmux click path a structured table with aligned rows, right-aligned numeric
+values, dim unavailable cells, amber usage at 80%, and red usage at 95%.
 
 The popup sync line uses the maximum authoritative `LastCollect` timestamp from
 the cache. If that field is unavailable, it falls back to the snapshots file

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projmux",
-  "version": "0.6.6",
+  "version": "0.6.7",
   "description": "tmux project session manager",
   "license": "MIT",
   "homepage": "https://github.com/crevissepartners/projmux#readme",
@@ -28,9 +28,9 @@
     "package:npm:pack": "scripts/package-npm.sh --pack"
   },
   "optionalDependencies": {
-    "@projmux/linux-x64": "0.6.6",
-    "@projmux/linux-arm64": "0.6.6",
-    "@projmux/darwin-x64": "0.6.6",
-    "@projmux/darwin-arm64": "0.6.6"
+    "@projmux/linux-x64": "0.6.7",
+    "@projmux/linux-arm64": "0.6.7",
+    "@projmux/darwin-x64": "0.6.7",
+    "@projmux/darwin-arm64": "0.6.7"
   }
 }