projmux 0.6.6 → 0.7.0

package/README-ko.md

@@ -4,8 +4,9 @@
   <img src="docs/assets/projmux-icon.png" alt="projmux icon" width="112">
 </p>
 
-프로젝트별 tmux workspace를 빠르게 전환하고, preview/status context/AI pane
-attention까지 함께 다루는 터미널 workspace 도구입니다.
+프로젝트별 tmux workspace를 빠르게 전환하고, Claude Code, Codex,
+Antigravity pane의 preview/status context/attention까지 함께 다루는 터미널
+workspace 도구입니다.
 
 [![npm version](https://img.shields.io/npm/v/projmux?logo=npm)](https://www.npmjs.com/package/projmux)
 [![CI](https://github.com/crevissepartners/projmux/actions/workflows/ci.yml/badge.svg)](https://github.com/crevissepartners/projmux/actions/workflows/ci.yml)
@@ -15,7 +16,7 @@ attention까지 함께 다루는 터미널 workspace 도구입니다.
 <p align="center">
   <img src="docs/assets/projmux-ai-attention.gif" alt="projmux AI attention demo" width="820">
   <br>
-  <em>다른 프로젝트에서 일하는 동안 agent 작업이 끝나면 notification에서 바로 해당 pane으로 돌아갑니다.</em>
+  <em>project를 오가며 AI permission 대기를 상태줄에서 확인하고, notification list에서 해당 pane으로 돌아갑니다.</em>
 </p>
 
 ## 무엇인가
@@ -23,6 +24,8 @@ attention까지 함께 다루는 터미널 workspace 도구입니다.
 `projmux`는 프로젝트 디렉터리를 오래 유지되는 tmux session으로 연결합니다.
 프로젝트 전환, session preview, AI split 실행, tmux 안의 상태 표시를 한
 키보드 중심 workspace 앱으로 묶습니다.
+Claude Code와 Codex hook event를 직접 수집하고, 수동으로 연결한 Antigravity
+hook/statusline event도 같은 notification 흐름으로 다룹니다.
 
 터미널 workspace를 한 명령으로 열고, 한 세트의 키로 project/window/pane,
 notification, settings 사이를 오가고 싶을 때 사용합니다.
@@ -59,7 +62,7 @@ projmux shell
 
 - `Alt-1`: project sidebar.
 - `Alt-2`: notification list.
-- `Alt-3`: existing-session picker.
+- `Alt-3`: Recent Windows.
 - `Alt-4`: AI split picker.
 - `Alt-5`: settings.
 - `Alt-6`: project switcher popup.
@@ -82,17 +85,45 @@ projmux shell
 설정은 [Configuration](docs/configuration.md)을 참고하세요. installer별 update
 동작은 [Upgrading](docs/upgrading.md)에 있습니다.
 
+## 에이전트 스킬
+
+projmux shortcut은 AI 도구의 user-level skill 또는 slash command로도 등록할
+수 있습니다. 스킬은 같은 CLI contract를 감싸는 얇은 wrapper입니다:
+
+```sh
+projmux ai split --agent codex right
+projmux ai split --agent claude down
+projmux ai split --agent antigravity right
+```
+
+`/projmux:codex-right` 같은 Claude slash command를 등록한 뒤 prompt와 함께
+실행시키면, Claude가 projmux command를 호출하고 현재 project에 붙은 managed
+Codex pane이 새로 열립니다. prompt는 새 pane으로 바로 전달되고,
+permission/completion hook event가 tmux 상태줄과 notification list에
+표시됩니다.
+Antigravity도 같은 managed split 경로로 실행되며, 수동 hook ingest와 session
+resume 지원 범위는 CLI reference에 정리되어 있습니다.
+
+설치 template과 naming convention은
+[AI Agent Shortcuts](docs/ai-agent-shortcuts.md)에 정리되어 있습니다.
+
+<p align="center">
+  <img src="docs/assets/projmux-skill-workflow.gif" alt="projmux skill workflow demo" width="820">
+  <br>
+  <em>Claude가 prompt와 함께 등록된 projmux skill을 호출해 managed Codex pane을 열고, Codex가 그 자리에서 응답합니다.</em>
+</p>
+
 ## 추가 문서
 
 - [Install](docs/install.md)
 - [Configuration](docs/configuration.md)
 - [Terminal Keybindings](docs/keybindings.md)
+- [AI Agent Shortcuts](docs/ai-agent-shortcuts.md)
 - [CLI Reference](docs/cli.md)
 - [Statusbar](docs/statusbar.md)
 - [Hooks](docs/hooks.md)
 - [Usage tracking](docs/usage-tracking.md)
 - [Agent Workflow](docs/agent-workflow.md)
-- [README Hero GIF Recording](docs/readme-hero-gif-recording.md)
 
 ## 개발
 

package/README.md

@@ -7,7 +7,7 @@
 <p align="center">
   <strong>A tmux-native workspace for multi-agent AI development.</strong>
   <br>
-  <em>First-class Claude Code and Codex integration with hook-driven attention and agent-aware session resume.</em>
+  <em>Managed Claude Code, Codex, and Antigravity panes with hook-driven attention and agent-aware session resume.</em>
 </p>
 
 <p align="center">
@@ -25,20 +25,20 @@ projmux shell
 <p align="center">
   <img src="docs/assets/projmux-ai-attention.gif" alt="projmux AI attention demo" width="820">
   <br>
-  <em>An agent finishes in another project. Open notifications, select it, and jump straight back.</em>
+  <em>Switch between projects while an AI pane waits for permission, then jump back from the tmux notification list.</em>
 </p>
 
 ## Why
 
-Six tmux windows. Each one is running Claude Code or Codex on a different
-repo. Three are idle. One is waiting on a permission prompt. One crashed an
-hour ago and you have no idea which.
+Six tmux windows. Each one is running Claude Code, Codex, or Antigravity on a
+different repo. Three are idle. One is waiting on a permission prompt. One
+crashed an hour ago and you have no idea which.
 
-projmux ingests Claude Code and Codex hook events directly, shows live
-per-pane state in the tmux status bar, and lets one keystroke take you to
-the pane that actually needs you. It also remembers each agent's resume id,
-so after a reboot every pane comes back as the *same* conversation — not a
-fresh one.
+projmux ingests Claude Code and Codex hook events directly, accepts manually
+wired Antigravity hook/statusline events, shows live per-pane state in the tmux
+status bar, and lets one keystroke take you to the pane that actually needs
+you. It also remembers each agent's resume id, so after a reboot every pane
+comes back as the *same* conversation — not a fresh one.
 
 ## Requirements
 
@@ -71,7 +71,7 @@ Inside the app:
 
 - `Alt-1` opens the project sidebar.
 - `Alt-2` opens the notification list.
-- `Alt-3` opens the existing-session picker.
+- `Alt-3` opens Recent Windows.
 - `Alt-4` opens the AI split picker.
 - `Alt-5` opens settings.
 
@@ -94,6 +94,35 @@ For detailed configuration, including `PROJMUX_PROJDIR`, managed roots,
 notifications, and usage tracking, see [Configuration](docs/configuration.md).
 For update behavior by installer type, see [Upgrading](docs/upgrading.md).
 
+## Agent Skills
+
+projmux shortcuts can also live in your AI tool as user-level skills or slash
+commands. A skill is just a thin wrapper around the same CLI contract:
+
+```sh
+projmux ai split --agent codex right
+projmux ai split --agent claude down
+projmux ai split --agent antigravity right
+```
+
+After registering a Claude slash command such as `/projmux:codex-right`, ask
+Claude to use it with a prompt. Claude runs the projmux command, Codex opens in
+a managed pane attached to the current project, and the prompt is delivered
+there immediately.
+projmux tracks hook events from the opened pane and shows permission or
+completion notifications in tmux.
+Antigravity uses the same managed split path, with manual hook ingest and
+session resume support documented in the CLI reference.
+
+Install templates and naming conventions are in
+[AI Agent Shortcuts](docs/ai-agent-shortcuts.md).
+
+<p align="center">
+  <img src="docs/assets/projmux-skill-workflow.gif" alt="projmux skill workflow demo" width="820">
+  <br>
+  <em>Claude invokes a registered projmux skill with a prompt, opens a managed Codex pane, and Codex answers there.</em>
+</p>
+
 ## More Docs
 
 - [Install](docs/install.md)
@@ -105,7 +134,6 @@ For update behavior by installer type, see [Upgrading](docs/upgrading.md).
 - [Hooks](docs/hooks.md)
 - [Usage tracking](docs/usage-tracking.md)
 - [Agent Workflow](docs/agent-workflow.md)
-- [README Hero GIF Recording](docs/readme-hero-gif-recording.md)
 
 ## Development
 

package/docs/agent-workflow.md

@@ -29,18 +29,22 @@
 - `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 Notify sidebar pane-grouped read-model rows and interactions: collapsed pane inbox group construction, fixed three-line group cards with stable project/provider, topic/context, aggregate metadata, and latest-preview slots including topic-with-project cases, child-count badges that match expandable child rows without rendering `+0`, childless group headers without strong fold affordance, selected/expanded marker-only row shape changes, duplicate label/preview reduction, worst-severity aggregation, inactive/gone group display and child-count rendering, pane-less fallback grouping, compact newest-first child event rows with warn/critical severity preservation, Right/Left fold mutation plus childless Right no-op refresh, folded and expanded live group Enter focus+ack with mixed-severity critical rows, inactive-but-routable group Enter focus+ack, gone group Enter cleanup without focus including critical rows, target-gone race cleanup, transient focus-failure no-ack refresh, child Enter focus/ack preservation, explicit group acknowledgement including mixed-severity critical rows, and grouped deferred refresh output with expanded-state pruning.
+- `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, compact action-list state copy, flat Keys list/action detail rows, key detail remove/test rows, Add key default press-key flow with Advanced typed entry, collapsed Troubleshooting entry copy, Labs compatibility redirect to the Keybindings root, capture/add-key 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 +63,24 @@
 - `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.
+- `make test` also covers Recent Windows Phase 0 state/model behavior: server-scoped file paths, missing/corrupt state policy with corrupt-file backup, MRU newest-first recording, same-window dedupe and promotion, default queue limiting, current-window exclusion, cross-session candidate retention, gone-window pruning against live window inventory, and label fallback rules that keep win/pane ids as debug fallback instead of the primary row label.
+- `make test` also covers Recent Windows Phase 1 native picker behavior: `projmux window recent` empty-state messaging, cross-session candidate picker rows with descriptive project/session/window/pane command age metadata, window-only switching without pane restoration, switch-failure refresh/prune handling, and gone-window pruning before picker selection.
+- `make test` also covers Recent Windows Phase 2/3/4 keybinding, popup, and runtime recorder integration: `RecentWindows:Open` owns the guaranteed `M-3` launch default, generated tmux config uses client-scoped `tmux popup-toggle recent-windows`, the popup body runs `projmux window recent`, generated tmux config installs background `window record` hooks for window and client-session changes plus first-use population without `session-window-changed`, `window record` snapshots current tmux socket/session/window/active-pane metadata into the socket-scoped store with escaped field parsing, repeated same-window record fires dedupe instead of growing entries, the queue remains bounded by `recentwindows.DefaultLimit`, Settings > Keybindings shows Recent Windows with the `M-3` default, setup probe text names Recent Windows, `SessionPopupToggle` no longer owns the guaranteed `M-3` default, and escaped tmux field separators are parsed for current/list window metadata.
 - 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
+  reconcile reports inactive `queue-stale` rows), `notify list --live` queue/live explanations, notify sidebar
+  three-line grouped card rendering with child-count/fold semantics plus focus/ack/non-critical-clear/clear-all
+  actions, notify/statusbar/sidebar attention-vs-AI palette assertions including muted inactive/gone rows,
+  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/architecture.md

@@ -139,13 +139,14 @@ does not own the truth of every live badge.
   TTL is not a removal condition. `projmux notify list --live` adds a
   read-only comparison against live pane state, explaining manual reply
   badges without queue entries, live AI replies with/missing queue entries,
-  and stale `ai:` entries.
+  and inactive (`queue-stale`) `ai:` entries.
 - **Ack** — `projmux notify ack <id>` removes one entry; `--all`
-  flushes everything. Focus/click handlers do not ack rows.
+  flushes everything. Interactive focus/click handlers ack after successful
+  focus, and gone/unroutable targets clean up without focusing.
 - **Reconcile** — `projmux notify reconcile` walks
   `tmux list-panes -a` and back-fills entries for panes whose
   attention state is `reply` AND whose AI agent option is set,
-  reporting stale `ai:` entries that no longer match a live pane without
+  reporting inactive `ai:` entries that no longer match a live reply+agent pane without
   acking them.
   `make install` and `projmux upgrade` invoke it so the queue
   recovers from any drift introduced by a lost daemon.

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,23 +206,33 @@ 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
   compares queued entries with live pane attention. It calls out manual
   reply badges that do not queue because no AI agent is attached, live AI
-  reply panes missing a queue entry, matched AI reply entries, and stale
-  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.
+  reply panes missing a queue entry, matched AI reply entries, inactive
+  (`queue-stale`) queue entries whose live pane EXISTS but no longer matches
+  reply+agent state, and gone (`queue-gone`) entries whose pane is absent from
+  the real tmux live pane inventory (or which have no routable target).
+  `--ui=sidebar` opens the compact interactive notify list where Enter
+  focuses and acks live or inactive-routable targets, cleans gone/unroutable
+  targets without focusing, `a` acks the selected row, `x` clears non-critical
+  rows, and `Ctrl-X` clears all; 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 +248,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 +259,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 +340,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 +348,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 +371,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 +449,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
@@ -610,8 +656,8 @@ projmux tmux apply
 Helpers tmux's keybindings and the install pipeline call into. Modes
 accepted by `popup-toggle` mirror the historical sessionizer surface:
 `session-popup`, `sessionizer`, `sessionizer-sidebar`,
-`notify-sidebar`, `ai-split-picker-right`, `ai-split-picker-down`,
-`ai-split-settings`.
+`notify-sidebar`, `recent-windows`, `ai-split-picker-right`,
+`ai-split-picker-down`, `ai-split-settings`.
 `apply` reloads the live `-L projmux` server's config without restarting
 it; `make install` and `projmux upgrade` invoke it after replacing the
 binary.
@@ -637,10 +683,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 +724,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 +758,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.