projmux 0.8.4 → 0.10.0

package/docs/configuration.md

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

package/docs/globalization.md

@@ -87,7 +87,7 @@ Files:
 
 - `internal/ui/projmuxpicker/*`
 - `internal/ui/render/*`
-- `docs/native-picker-no-fzf-poc.md`
+- `docs/native-picker.md`
 
 Classification:
 
@@ -124,7 +124,7 @@ Classification:
 
 Do not translate these families:
 
-- Product and agent names: `Codex`, `Claude`, `projmux`, `tmux`, `psmux`,
+- Product and agent names: `Codex`, `Claude`, `projmux`, `tmux`,
   `GitHub`, `npm`.
 - Terminal and app names: `Windows Terminal`, `Ghostty`, `WezTerm`, `Kitty`,
   `iTerm2`, `Alacritty`, `Foot`.

package/docs/hooks.md

@@ -207,8 +207,9 @@ If a `send-noti` hook itself calls `projmux notify push`, projmux sees
 
 `Settings > Notifications > Delivery sources` surfaces the active Codex hooks,
 Claude, and tmux AI notify diagnostics: status, conflicts, config paths, and
-copyable CLI install/remove/dry-run commands. It does not install or remove
-external Codex, Claude, or tmux settings.
+copyable CLI install/remove/dry-run commands. It also shows whether
+`PROJMUX_NOTIFY_HOOK` overrides the built-in desktop sender. It does not install
+or remove external Codex, Claude, or tmux settings.
 
 `PROJMUX_NOTIFY_HOOK` is separate from `[hooks.send-noti]`: it replaces the
 desktop sender and receives positional arguments
@@ -617,37 +618,79 @@ 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`:
+`projmux ai ingest antigravity-hook --event <event> < payload.json` accepts
+Antigravity CLI `agy` hook payloads. Antigravity v1.1.12 stdin does
+not include the event name, so the command's `--event` value is authoritative.
+Payload event aliases remain a compatibility fallback when `--event` is
+omitted. `projmux ai integrate antigravity [--dry-run|--remove]` owns exactly
+the named `projmux` entry in `~/.gemini/config/hooks.json` and separately owns
+only `statusLine` in `~/.gemini/antigravity-cli/settings.json`. Other named hooks,
+their fields, and unknown JSON values remain untouched. The generated commands
+use the stable absolute projmux executable because Antigravity runs handlers
+with the config directory as cwd. The command refuses unmanaged name/command
+conflicts, malformed JSON, symlink paths, and permission failures with an
+actionable diagnostic. Doctor/Settings distinguish installed, missing,
+conflicting, and stale managed entries; stale covers executable, event/schema,
+or stdout-fallback drift and is refreshed by the install command.
+The statusline object uses the official v1.1.12 command shape with
+`enabled=true` and `stack_with_default=true`. Its direct explicit `Statusline`
+ingest command emits empty stdout, preserving the built-in line. Existing
+custom statusline commands are conflicts and are never wrapped or chained.
+
+The default Antigravity catalog records the five official v1.1.12 events and
+installs four non-permission events:
 
 | 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 |
+| `PreToolUse` | known permission-changing event; never installed and no permission decision is synthesized |
+| `PreInvocation` | marks the matched pane hook-active and moves it to thinking/busy; no notify queue entry is pushed |
+| `PostInvocation` | marks the matched pane hook-active and writes a quiet bookkeeping diagnostic; no notify queue entry is pushed |
+| `PostToolUse` | marks the matched pane hook-active, retains tool error metadata in quiet diagnostics, and pushes no notify queue entry |
+| `Stop` | pushes an info completion unless an explicit error signal requires a critical error row |
+| `Statusline` with `tool_confirmation_pending=true` | pushes/replaces a deduped critical approval-required row outside the hook catalog |
+| `Statusline` with `agent_state=thinking|working|tool_use` | moves the matched pane to thinking/busy without notifying, unless a terminal completion/approval state must be preserved from a late refresh; a new `PreInvocation` resets the next generation to busy |
+| `Statusline` with `agent_state=idle` or `tool_confirmation_pending=false` | quiet update; does not clear completion/approval attention and creates no notification |
 | 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 notify rows use `agent=antigravity` metadata. The v1.1.12 parser
+retains common camelCase `conversationId`, `workspacePaths`, `transcriptPath`,
+`artifactDirectoryPath`, and `modelName`; invocation `invocationNum` and
+`initialNumSteps`; post-tool `toolCall`, `stepIdx`, and `error`; and Stop
+`executionNum`, `terminationReason`, `error`, and `fullyIdle`. Existing aliases
+such as `conversation_id`, `cwd`, `workspace.path`, `agent_state`, and nested
+`statusline.tool_confirmation_pending` remain accepted. The first non-empty
+`workspacePaths` value is only a cwd fallback candidate; empty/absent arrays do
+not become the process cwd, and inherited `$TMUX_PANE` still wins attribution.
+`NO_TOOL_CALL`, `MODEL_STOP`, and known normal reasons are info completions.
+Non-empty `error`, explicit `ERROR`, and `MAX_STEPS_EXCEEDED` families are
+critical; unknown reasons retain diagnostic metadata but default to info.
+Explicit non-permission hook ingest writes valid hook stdout: `{}` for
+invocation/post-tool events and `{"decision":"stop"}` for Stop. The latter
+allows the requested stop to complete; projmux does not emit `continue` or a
+`PreToolUse` permission decision.
+Each managed command includes its explicit event selector and a valid stdout
+fallback: `{}` for invocation/post-tool events and `{"decision":"stop"}` for
+Stop. The fallback is non-blocking and never returns `continue`,
+`allow`, `deny`, or `ask`.
+
+The named entry in `hooks.json` remains the install source of truth. Use
+`agy -p '/hooks' --output-format json` only as a read-only runtime diagnosis of
+loaded sources/events; its result is never used to generate or rewrite config.
 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`. The statusline
-`context_window` percentage is persisted to the usage state dir on ingest so
-the usage HUD can surface it as a `context-window-only` row — Antigravity has
-no 5-hour/weekly quota contract, so no quota bars are emitted. Raw payloads or
-transcript contents are not stored.
+otherwise preview and doctor render `resume unavailable`. Official snake_case
+`cwd`, `conversation_id`, `transcript_path`, `agent_state`,
+`tool_confirmation_pending`, and structured `context_window.used_percentage`
+plus token fields are parsed directly. The structured percentage is persisted
+with conversation identity to the usage state dir; the legacy string percentage
+remains a fallback so the usage HUD can surface it as the conversation-local
+`context` row. The official top-level `quota` map is persisted independently:
+valid `remaining_fraction` values become used percent, exact upstream bucket
+IDs render as separate `quota/<bucket>` account rows, and `reset_time` plus
+optional `reset_in_seconds` retain their independent meanings. Invalid,
+disabled, missing, or empty quota shapes degrade without inventing a cadence or
+reinterpreting context. Raw payloads or transcript contents are not stored.
 
 ## Ingest Debug Log
 

package/docs/install.md

@@ -18,8 +18,8 @@ After installing, run:
 projmux doctor
 ```
 
-`doctor` checks that runtime tools such as `tmux`, `git`, and `stty` are
-available.
+`doctor` performs read-only diagnostics for runtime tools such as `tmux`,
+`git`, and `stty`.
 
 Start the tmux app with:
 

package/docs/keybindings.md

@@ -17,7 +17,7 @@ The recommended path when a key does not fire:
    `projmux shell` key adapter, then retry the physical key.
 3. Run `projmux setup` outside tmux to see which bytes reach the process.
 4. For supported terminals outside the native macOS app socket, preview
-   `projmux init [terminal]`; add `--apply`
+   `projmux setup terminal [terminal]`; add `--apply`
    only after reviewing the merge.
 5. For unsupported terminals, configure plain Meta bytes or add a custom key in
    Settings > Keybindings.
@@ -56,6 +56,13 @@ These shortcuts are the guaranteed launch defaults. They need no tmux prefix.
 to the selected live tmux window using that window's current active pane; it is
 separate from `last-pane` and from the existing-session popup.
 
+`Resources:Open` is listed in Settings > Keybindings without a default key.
+Adding a safe direct chord opens the Linux/tmux Resource Inspector through the
+canonical client-scoped popup-toggle path; pressing the same custom chord again
+closes it without touching another client's popup. The action remains usable
+when Settings > Labs > Live system resources is off—the Lab controls only
+statusbar visibility.
+
 The tmux prefix remains the upstream default `Ctrl-b`. Inside a running
 session, `Ctrl-b ?` lists the live tmux bindings.
 
@@ -142,11 +149,11 @@ Advanced typed entry remains available from Action detail for literal
 risky/reserved key copy, and raw diagnostics. Advanced delivery is still owned
 by the selected Projmux action. The native macOS app-socket adapter reads the
 same safe chords directly; supported Ghostty and Windows Terminal mappings for
-other paths are previewed/applied through `projmux init`, not by storing raw
+other paths are previewed/applied through `projmux setup terminal`, not by storing raw
 sequences in the primary keymap. Options covers unbinding the action and
 reset/use-default flows. Diagnostic/probe/init workflows are not first-class
 Settings tabs; use `projmux setup` and, where the native adapter does not apply,
-`projmux init` from the terminal when key delivery needs remediation.
+`projmux setup terminal` from the terminal when key delivery needs remediation.
 
 Optional direct keys can be added for actions such as:
 
@@ -187,7 +194,7 @@ Settings > Keybindings stays a discovery surface. It must continue to expose
 launch toggles, sidebar keymap actions, picker-local actions, pane switching,
 window switching, and rename actions. The basic Settings flow is not the
 terminal remediation surface: key-role replacement, disable-default, typed
-fallback, terminal mapping preview/apply, and init execution rows stay out of
+fallback and terminal mapping preview/apply rows stay out of
 the action detail.
 
 The product model does not support `UserN` or `CSI-u` as fallback guidance.
@@ -235,7 +242,10 @@ Settings is the default apply path for key edits: it writes the key list,
 refreshes the generated config, and reloads the running tmux session when
 possible. Use `projmux tmux apply` as a CLI recovery/sync command after editing
 the keymap file by hand, after an outside-tmux Settings save, or after resolving
-a reported generated-config or live-reload failure.
+a reported generated-config or live-reload failure. Generated config first
+unbinds the known retired `C-t` pane-label chord, then installs the current
+keymap; an explicit current `C-t` assignment therefore wins without retaining
+the retired command body. Apply does not rewrite `keymap.toml`.
 
 ## Keymap File
 
@@ -299,29 +309,29 @@ projmux setup --timeout 10s
 projmux setup --non-interactive
 ```
 
-## Auto-Config: `projmux init`
+## Terminal remediation: `projmux setup terminal`
 
-`projmux init` previews and optionally applies supported terminal mappings.
-Default mode is dry-run; pass `--apply` to write changes with a timestamped
+`projmux setup terminal` previews and optionally applies supported terminal
+mappings. Default mode is a read-only preview; pass `--apply` to write changes with a timestamped
 backup.
 
 ```sh
-projmux init
-projmux init ghostty
-projmux init ghostty --apply
-projmux init windows-terminal --apply
-projmux init --config /path/to/file
-projmux init --allow-symlink
+projmux setup terminal
+projmux setup terminal ghostty
+projmux setup terminal ghostty --apply
+projmux setup terminal windows-terminal --apply
+projmux setup terminal --config /path/to/file
+projmux setup terminal --allow-symlink
 ```
 
 The merge is idempotent: matching bindings are no-ops, missing bindings are
 added, and keys already mapped to a different user action are skipped with a
-warning. `projmux init` does not read `keymap.toml`; direct tmux keys still
+warning. `projmux setup terminal` does not read `keymap.toml`; direct tmux keys still
 belong in Settings > Keybindings or the keymap file.
 
 ### Ghostty
 
-`projmux init ghostty` emits plain Meta bytes for `Alt-1` through `Alt-5` in
+`projmux setup terminal ghostty` emits plain Meta bytes for `Alt-1` through `Alt-5` in
 the managed block:
 
 ```text
@@ -341,7 +351,7 @@ refused by default; pass `--allow-symlink` to write through the link.
 
 ### Windows Terminal
 
-`projmux init windows-terminal` merges `sendInput` actions identified by the
+`projmux setup terminal windows-terminal` merges `sendInput` actions identified by the
 `User.projmux*` ID prefix. The generated inputs use plain Meta bytes, tmux
 prefix sequences for split actions, and xterm modifier-arrow sequences for
 previous/next window:

package/docs/native-picker.md

@@ -0,0 +1,103 @@
+# Native Picker
+
+The native picker is the product picker for every interactive selection flow.
+There is no runtime backend selection, saved picker selector, or external
+picker process. `internal/ui/picker` owns the interaction contract and
+`internal/ui/projmuxpicker` owns its visual composition.
+
+## Product Contract
+
+| Area | Behavior | Primary evidence |
+| --- | --- | --- |
+| Items and results | Structured items keep display labels, stable values, optional search text, multi-line metadata, and action results separate. `internal/ui/pickercompat` maps older internal option/result shapes into this contract; it is not a runtime backend. | `TestPickerOptionsFromCompatPickerMapsCandidatesWhenEntriesAreEmpty`; `TestPickerOptionsFromCompatPickerPreservesTheme` |
+| Search | Lower-case queries are case-insensitive, uppercase queries are case-sensitive, hidden values remain searchable when no explicit search key exists, explicit search-key lists preserve caller order, and simple rows receive fuzzy ranking and match highlighting. | `TestFilterItemsUsesSmartCase`; `TestFilterItemsSearchesHiddenValueWhenNoSearchKey`; `TestFilterItemsPreservesSearchKeyOrder`; `TestFilterItemsRanksBetterMatchesFirst` |
+| Navigation | Up/Down, Ctrl-J/Ctrl-N, and Ctrl-K/Ctrl-P wrap selection; PageUp/PageDown and Home/End clamp or jump; empty lists remain safe. Ctrl-N and Ctrl-P remain real navigation keys unless a caller claims the key as a custom action. | `TestNativeInteractiveSupportsControlNavigationKeys`; `TestNativeInteractiveWrapsPreviousNavigationKeys`; `TestNativeInteractiveWrapsNextNavigationKeys`; `TestNativeInteractiveNavigationKeysAreNoopForEmptyList`; `TestNativeInteractiveJumpNavigationRemainsClamped` |
+| Editing | Left/Right, Ctrl-A/E, Delete, Backspace, Ctrl-U/W, printable input, accept-query mode, and a visible query cursor are supported. | `TestNativeInteractiveEditsTypedQueryAtCursor`; `TestNativeInteractiveSupportsQueryLineEditingKeys`; `TestNativeInteractiveCtrlUDeletesBeforeCursor`; `TestNativeRunnerAcceptsTypedQuery` |
+| Actions | Enter accepts, shared close actions abort, printable/control expect keys return stable action keys, command actions can refresh previews, and mutable actions can update items without restarting the picker. | `TestNativeRunnerUsesSharedCloseActions`; `TestNativeInteractiveSupportsPrintableExpectKeys`; `TestNativeInteractiveRunsCustomActionCommandAndRefreshes`; `TestNativeInteractiveCustomActionMutatesItemsAndRefreshes` |
+| Deferred state | Deferred and event-triggered updates preserve query and selection by value, can repeat, and may explicitly choose a new focus value. | `TestNativeInteractiveDeferredUpdateTriggerRefreshesRepeatedly`; switch and notify sidebar mutable-refresh app tests |
+| Preview | Popup previews use a right split, sidebar previews use a bottom split, control bytes and tabs are normalized before clipping, and preview scrolling/cycling rerenders in place. | `TestNativeInteractiveRendersWidePreviewBesideList`; `TestNativeInteractiveRendersDownPreviewBelowList`; `TestRenderSplitPreviewRowsNormalizesPreviewTabsBeforeTruncating`; `TestNativeInteractiveRendersPreviewOffset` |
+| Mouse | SGR mouse input focuses on primary down, follows drag, accepts on matching release, and scrolls with the wheel. | `TestNativeInteractiveSelectsOnMouseRelease`; `TestNativeInteractiveMouseDragFollowsSelection`; `TestNativeInteractiveSupportsMouseWheelSelection` |
+| Lifecycle | Interactive runs use the alternate screen, synchronized/coalesced frame updates, controlling-TTY fallback, and deterministic reader cleanup. | `TestNativeInteractiveUsesAlternateScreen`; `TestNativeInteractiveWrapsRedrawsInSynchronizedUpdates`; picker/setup lifecycle tests in `docs/agent-workflow.md` |
+
+## Rendering And Popup Chrome
+
+The renderer owns rounded frames, optional titlebars and chips, search/header
+separators, footer placement, selected-row styling, proportional scrollbars,
+multi-line gaps, preview geometry, ANSI restoration, and terminal-cell width for
+CJK text, emoji, and combining marks. Frame-owned cells inherit the effective
+theme's `surface` and `chrome_foreground` values, including padding after
+embedded resets.
+
+Picker popups are always borderless tmux popups (`display-popup -B`) so the
+native renderer owns the visible frame. The popup body receives a per-command
+style derived from the effective theme; no global popup, pane, window, shell,
+or status style is mutated. Project sidebars use a `20%` width with a `40`
+column minimum, notification sidebars use `24%` with a `64` column minimum,
+and both reserve the two statusbar rows when client height is known.
+
+Primary evidence includes `TestAppRunTmuxPopupToggleUsesBorderlessNativePopup`,
+`TestAppRunTmuxPopupToggleUsesNativePopupBodyStyleFromGlobalTheme`,
+`TestBuildPopupToggleAppliesNativeBodyStyle`,
+`TestSessionizerSidebarWidthUsesCompactMinimum`,
+`TestNotifySidebarWidthUsesProductContract`, and
+`TestSidebarPopupHeightLeavesStatusbarRows`.
+
+## Fuzzy Scoring Provenance
+
+The native fuzzy scorer intentionally follows the fzf V2 dynamic-scoring
+algorithm for the maintained reference cases in `internal/ui/picker/backend_test.go`.
+`TestFuzzyScoreMatchesFZFV2ReferenceScores` and
+`TestFuzzyScoreRejectsFZFV2ReferenceNonMatches` are provenance fixtures; keep
+their expected scores stable when changing filtering internals.
+
+## Retired Artifact Contract
+
+The retired picker selector environment variable and saved selector filename
+are not runtime inputs. Their presence must not cause lookup, file reads,
+warnings, deletion, rewriting, propagation to child popups, or any change to
+the native path. There is deliberately no alias, migration, or stale-value
+cleanup behavior.
+
+Coverage is split by boundary:
+
+- `TestRunNativePickerOptionDoesNotObserveRetiredBackendArtifacts` guards the
+  direct picker path, fails if the retired env name is queried, and verifies a
+  stale file is neither deleted nor replaced.
+- `TestAppRunSwitchUsesNativePickerWithoutBackendLookup` guards the ordinary
+  switch flow.
+- `TestAppRunTmuxPopupToggleIgnoresRetiredBackendArtifacts` and
+  `TestBuildPopupTogglePropagatesNativePickerEnvironmentWithoutRetiredBackend`
+  guard popup chrome and child-environment construction.
+- `test/e2e/linux-smoke.sh` launches the ordinary attached-client Settings
+  popup with stale env/file values, completes the recorder flow, verifies the
+  file inode/content are unchanged, and rejects visible compatibility output.
+
+## Removed PoC Coverage Mapping
+
+The retired standalone dependency sandbox and focused smoke duplicated product
+coverage or tested a dependency policy that no longer exists. Its valid
+behavior assertions remain covered as follows:
+
+| Removed focused assertion | Maintained coverage |
+| --- | --- |
+| Settings and Labs render through the native picker | `TestSettingsUsesNativePicker`; `TestSettingsHubKeepsLabsSectionWithoutRetiredPickerChoices`; ordinary attached-client Settings recorder in `test/e2e/linux-smoke.sh` |
+| Search chrome, smart-case filtering, native frame ownership, and full-height rendering | `TestNativeInteractiveSeparatesSearchHeaderFromList`; `TestFilterItemsUsesSmartCase`; `TestNativeInteractiveRendersBorderFrame`; `TestNativeInteractiveUsesAvailableHeightForSimpleLists` |
+| AI Settings maps a typed selection to the saved mode | `TestAISettingsPickerSetsSelectedMode`; native picker option/result mapping tests |
+| Switch popup/sidebar filtering, selection, preview cycling, and initial focus | `TestAppRunSwitchDefaultsToPopupAndOpensSelectedSession`; `TestSwitchCommandSupportsSidebarUI`; preview cycle and initial-position tests in `internal/app/switch_test.go` |
+| Sessions popup filtering, selection, and preview cycling | `TestAppRunSessionsDefaultsToPopupAndOpensSelectedSession`; session popup preview/cycle tests in `internal/app/session_popup_test.go` |
+| Notification sidebar navigation and mutable actions | `TestNotifySidebarUsesNativePicker`; notify sidebar ack/clear/deferred-refresh app tests |
+| Launch-key close behavior and Ctrl-N/Ctrl-P navigation | `TestNativeInteractiveClosesOnMatchingLaunchCloseKey`; `TestNativeInteractiveSupportsControlNavigationKeys`; empty-list and wrap tests |
+| Mouse selection and alternate-screen restoration | native mouse and lifecycle tests listed above |
+| Generated shell config and the Alt-1 project-sidebar popup path | `TestShellWritesAppConfigAndRunsIsolatedTmux`; `TestAppRunTmuxPopupToggleOpensStandaloneSidebar`; popup frame/body-style tests listed above |
+| Stale selector values do not affect the product | retained and strengthened in the unit/app/e2e negative coverage listed in the previous section |
+
+The dependency-absence assertion is now a source-residue property rather than
+a separate container scenario: production code contains no selector, resolver,
+saved-selector access, propagation, or external picker launch path.
+
+## Maintenance
+
+Update this document and the maintained list in
+[`docs/agent-workflow.md`](agent-workflow.md) whenever picker behavior changes
+coverage level, gains a new product flow, or changes input/render/action
+semantics.

package/docs/notify-queue.md

@@ -70,12 +70,13 @@ 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`. Antigravity manual hook rows carry `agent=antigravity`,
+`teammate_name`. Antigravity 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.
+`agy --conversation <uuid>` when it is UUID-shaped. Antigravity
+account quota remains outside notify attention semantics: `context_window` is a
+separate conversation-local gauge and is never treated as 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

package/docs/npm-distribution.md

@@ -18,7 +18,7 @@ The shim sets `PROJMUX_INSTALLER=npm` before executing the real binary so
 `projmux update status` and the Settings About screen can present
 npm-specific guidance. npm is only an update/install source label here; the
 keybinding flow remains `projmux shell` first, then `projmux setup` and
-`projmux init` only for terminals that swallow shortcuts.
+`projmux setup terminal` only for terminals that swallow shortcuts.
 
 ## Local Packaging
 
@@ -116,5 +116,5 @@ completed update never leaves stale-path `run-shell` commands failing with
 
 The npm installer must not install system dependencies, edit shell startup
 files, or mutate tmux config. Those actions stay behind explicit
-`projmux doctor`, `projmux init`, Settings About update actions, or future
+`projmux doctor`, `projmux setup terminal`, Settings About update actions, or future
 opt-in install commands.