projmux 0.6.2 → 0.6.4

package/README.md

@@ -74,11 +74,11 @@ Inside the app:
 - `Alt-3` opens the existing-session picker.
 - `Alt-4` opens the AI split picker.
 - `Alt-5` opens settings.
-- `Alt-6` opens the project switcher popup.
 
-See [Terminal Keybindings](docs/keybindings.md) for the full key map. If a key
+Those five launch keys are the guaranteed zero-config defaults. Add more
+aliases in Settings > Keybindings or `~/.config/projmux/keymap.toml`. If a key
 does not fire, run `projmux setup` outside tmux, then use
-`projmux init [terminal] --apply` for supported terminal fallbacks.
+`projmux init [terminal] --apply` for supported terminal delivery fallbacks.
 
 ## Day-To-Day Use
 

package/docs/agent-workflow.md

@@ -29,33 +29,46 @@
 - `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 branch block styling, statusbar pwd display-only native-framed path popup, no clipboard or tmux buffer copy, and simple Enter-close popup command, statusbar usage native HUD popup alignment/threshold/sync-staleness/fallback coverage without raw CLI popup or popup-toggle stacking, statusbar settings click popup fallback, 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, 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, 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`: 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 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, capture and typed fallback flows, unsafe raw capture, unsafe typed payload, disabled/default 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 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, 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 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, 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), 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, trust approve continuation, and trust deny/cancel no-session behavior.
+- `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 `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.
 - `make test` also covers legacy named-snapshot storage compatibility for `.projmux/layouts/*.toml`, supported interpolation validation, malformed-file list warnings, portable conversion helpers, dry-run conversion to the session-state restore preview with source labels, missing current-session failure, destructive live replay helper behavior with fresh/internal source marking and fresh saved-snapshot cleanup, and the session-state live replay helper that stages windows, moves them by tmux ID, and removes extra live windows.
 - `make test` also covers `projmux ai integrate codex` default hooks install/idempotence/dry-run/removal, compatibility legacy Codex notify mode install/idempotence, dry-run preview, unmanaged `notify = ...` conflict refusal, managed-block removal, catalog-driven Codex hook event installation with local override merging, nested inline Codex hook schema, `[features]` merge/preservation, preservation of unrelated Codex/Claude config and unmanaged hook entries, Settings Codex `/hooks` review notice and tested-version rows, and remove-all behavior for projmux-managed Codex blocks.
 - `make test` also covers `projmux ai ingest codex-hook` event parsing, PermissionRequest critical queue rows with tool/action metadata, Stop info queue rows, UserPromptSubmit busy/no-queue behavior, quiet/no-notify diagnostics for non-firing Codex hook events including override-added catalog events, cataloged hook notification body formatting, hook-active pane marking, topic preservation without hook candidate writes, and mutable resume metadata writes for `@projmux_ai_resume_id`, source, and updated-at.
 - `make test` also covers `projmux ai integrate claude` user-level Claude Code hook settings install/idempotence, dry-run preview, unmanaged projmux ingest command conflict refusal across all settings events, managed-command removal by marker even for stale events outside the current catalog, preservation of unrelated settings/hooks, catalog-driven Claude hook event installation with local override merging, and managed wiring for the 29 Claude Code 2.1.140 events in the embedded default catalog.
 - `make test` also covers `projmux ai ingest claude-hook` core and extra Claude Code hook ingest for event parsing, transcript fallback, cataloged hook notification body formatting, permission summary formatting, UserPromptSubmit busy/no-queue behavior, Notification severity/text mapping, StopFailure/TeammateIdle text/severity/metadata mapping, SubagentStop quiet/no-notify diagnostics, unknown future-event quiet fallback, hook-active pane marking, topic preservation without hook candidate writes, mutable resume metadata writes for `@projmux_ai_resume_id`, source, and updated-at, and Claude transcript path preservation.
+- `make test` also covers the Globalization Phase 0 English baseline for AI desktop notification summaries/bodies and hook-ingest queue text while preserving agent names, tool names, commands, paths, and provider payload values as literals/data.
+- `make test` also covers the Globalization Phase 1 message catalog foundation: locale resolver priority and normalization, `ko-KR` to `en-US` fallback, missing fallback-key errors, `en-US` completeness for foundation keys, and plain-text versus ANSI/tmux-styled fragment API separation.
 - `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 now covers onboarding revisit and welcome wiring (`projmux welcome`, `Settings > About > Welcome`, `pending_attach_welcome`, attach-time `welcome --popup` one-time claim/env suppression/tmux popup payload, and generated `client-attached` app config wiring) via shell welcome tests.
-- `make test` also covers `projmux quit` action-picker rows, cancel/close no-op behavior, explicit quit of only app-owned `tmux -L projmux` runtimes marked by `@projmux_app=1`, 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 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 `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, statusbar git/notify/usage/settings palette regressions, attention/pane-border/popup/switch progress color guards, renderer-only lead-mode topic prefix styling, and settings/trust/destructive row color guards.
 - 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/clear-all
-  actions, including in-place `x` ack that refreshes the sidebar without
-  focusing, preserves selection position where possible, and renders the empty
-  state after the last row is acked, and `focus` dispatch diagnostics for session fallback, unresolved
+  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
   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 and CSI-u Ctrl-X 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 keybinding diagnostic list/detail/probe outcome/init delegation coverage, environment override normalization, compact multi-line metadata gutters with one-column-indented metadata, proportional native scrollbar thumb rendering, 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, preview tab/control normalization before width clipping, optional native frame titlebars without same-line rule fill and with titlebar border reset guards, titled native Alt-1 sidebar chrome, statusbar-preserving sidebar popup height, native-only compact project sidebar popup sizing, 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 keybinding diagnostic list/detail/probe outcome/init delegation coverage, environment override normalization, compact multi-line metadata gutters with one-column-indented metadata, proportional native scrollbar thumb rendering, 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, preview tab/control normalization before width clipping, optional native frame titlebars without same-line rule fill and with titlebar border reset guards, titled native Alt-1 sidebar chrome, statusbar-preserving sidebar popup height, native-only compact project sidebar popup sizing, 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.
+- psmux AI split MVP focused unit coverage includes right/down `psmux -L projmux split-window` command shapes with `-P -F "#{pane_id}"`, PowerShell-rendered plain shell and Codex/Claude command tails, psmux-scoped Windows runner lookup for Codex `.cmd`/`.ps1`/`.exe`/extensionless shims, Claude native-installer PATH guidance, unchanged tmux split behavior, and explicit psmux degradation for tmux-only pane metadata, watch-title, and split-layout follow-up calls.
+- Shell focused unit coverage includes native Windows and explicit `PROJMUX_MUX_BACKEND=psmux` `projmux.exe shell` routing to `psmux -L projmux -f <generated config> new-session -A -s <session> [-c <cwd>]`, separate minimal psmux config generation with PowerShell-rendered callbacks, minimal psmux project-switch keybinding generation with psmux/native-picker env forcing, native line-mode fallback, explicit PowerShell `display-popup -E powershell -NoProfile -Command <script>` command tail, left-anchored sidebar-like popup geometry, explicit tmux override on Windows, and unchanged tmux/POSIX shell routing.
 - `make test-integration`: Docker-backed Linux integration smoke with real `tmux`, `git`, and `stty`; covers `doctor`, tmux config print/install/apply, and notify queue CRUD against isolated HOME/XDG paths.
 - `make test-install-smoke`: Docker-backed source install smoke; covers `make install`, atomic binary replacement, `tmux apply` against a live `projmux` socket, and post-install notify queue initialization.
 - `make test-e2e`: Docker-backed real-tmux workflow smoke for session/pane setup, app config sourcing, reply-state notify reconciliation, focus notify fallback, and status notify rendering with contextual project/state/agent badges. Host-only terminal, WSL, macOS, and GUI notification behavior remains outside Docker; see [docs/testing.md](testing.md).

package/docs/architecture.md

@@ -90,6 +90,30 @@ Ephemeral runtime state:
 - popup marker files
 - current tagged selection set
 
+## Naming metadata model
+
+Projmux keeps visible naming separate from source metadata:
+
+- **Pane border label** is the primary visible pane name. In the app tmux
+  config it resolves to AI topic first, known interactive shell command
+  (`zsh`, `bash`, `fish`, `sh`, `nu`, `xonsh`) second, and raw pane title last.
+- **Window tab name** follows the active pane's visible pane label through the
+  same tmux format expression used by the pane border. Historically the app
+  config used raw `#{pane_title}` for `automatic-rename-format`, which let shell
+  OSC titles such as branch names diverge from the pane border; generated app
+  config now keeps the two aligned.
+- **Terminal / pane title** remains raw title metadata owned by the running app
+  or shell. It is still available to tmux and to Projmux features that need
+  title evidence, but it is not the canonical Projmux window naming source.
+- **AI topic** is the user-facing AI pane name. AI panes may set the pane title,
+  pane border label, window tab name, and `@projmux_ai_topic` from the topic.
+- **Git branch** belongs in the statusbar git segment. Branch-based terminal
+  title overwrites are not promoted to the primary Projmux pane or window name.
+- **Session snapshots** store source metadata such as `window_name`,
+  `pane_title`, `@projmux_ai_topic`, and agent resume metadata. They do not store
+  a resolved `display_label`; visible labels are recomputed by tmux policy at
+  display time.
+
 ## Notify queue
 
 `projmux` keeps a single JSON-backed queue of pending notifications at

package/docs/cli.md

@@ -71,13 +71,13 @@ selection has been retired. The native picker is always used.
 projmux setup [--timeout DURATION] [--non-interactive]
 ```
 
-Probes which projmux key sequences (`Alt-1..5`, `Ctrl-N`, `Ctrl-Shift-{R,L,M}`,
-`Ctrl-M`, `Alt-Shift-{Left,Right}`) reach this process and which the
-terminal swallows. Reports `plain`, `csi-u`, `unknown`, or `timeout` for
-each. `--non-interactive` skips the TTY probe and prints the expected key
+Probes the guaranteed launch defaults (`Alt-1..5`) plus advanced fallback and
+transport candidates such as `Ctrl-N`, `Ctrl-Shift-{R,L,M}`, `Ctrl-M`, and
+`Alt-Shift-{Left,Right}`. Reports `plain`, `csi-u`, `unknown`, or `timeout`
+for each. `--non-interactive` skips the TTY probe and prints the expected key
 map. Default `--timeout` is `5s`. Run it outside tmux after trying
-`projmux shell`; keys reported as `plain` or `csi-u` already work with zero
-terminal config.
+`projmux shell`; `Alt-1..5` are the only guaranteed zero-config defaults, while
+other probed keys are diagnostic or optional binding candidates.
 
 ## init
 
@@ -211,9 +211,9 @@ projmux notify reconcile [--json]
   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, `x`
-  acks the selected row, and `Ctrl-X` clears all; opening or navigating the
-  sidebar does not ack. The sidebar uses two-line cards with notification text
+  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.
@@ -376,7 +376,8 @@ precedence over catalog `action` during ingest, including known events such as
 `install` field used by `projmux ai integrate codex`. A runtime `notify`
 override for a known Codex event without a specialized handler, such as
 `PreToolUse` or `PostToolUse`, pushes a short generic in-app row like
-`Codex · PreToolUse · Bash`. Generic rows are queue/sidebar/statusbar only and
+`PreToolUse · Bash` with agent/category metadata. Generic rows are
+queue/sidebar/statusbar only and
 do not dispatch OS desktop notifications, `PROJMUX_NOTIFY_HOOK`, or
 `[hooks.send-noti]`.
 
@@ -653,15 +654,17 @@ installs.
 ## welcome
 
 ```
-projmux welcome
+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.
 
-Usage is argument-free. Passing positional arguments prints usage and returns a
-usage error.
+`--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
+consulting pending or skip state. Passing positional arguments prints usage and
+returns a usage error.
 
 ## sessions / session-popup / preview / pin / kill / prune / tag
 
@@ -718,11 +721,12 @@ flags with the top-level `switch` UX:
   updates the matching live tmux option when available. Labs remains
   available for experimental settings. The About section reads the cached
   update status without network access;
-  selecting Check Updates runs `projmux update check`, and Update Now runs
-  `projmux update apply`. `Settings > About > Quit projmux` routes through the
-  same `projmux quit` action picker. The same About section also lists the
-  keybinding diagnostic path: zero-config first, `setup` for swallowed keys,
-  `init` for supported terminal fallbacks, and `doctor` for dependencies.
+  selecting Check Updates runs `projmux update check`, Update Now runs
+  `projmux update apply`, and Welcome opens a Settings-native viewer
+  independent of shell skip state. `Settings > About > Quit projmux` routes
+  through the same `projmux quit` action picker. The same About section also
+  lists the keybinding diagnostic path: zero-config first, `setup` for swallowed keys,
+  `init` for supported terminal mappings, and `doctor` for dependencies.
 
 ## See also
 
@@ -730,5 +734,5 @@ flags with the top-level `switch` UX:
 - [statusbar.md](statusbar.md) — two-line layout and click range catalogue.
 - [notify-queue.md](notify-queue.md) — queue file format and lifecycle.
 - [usage-tracking.md](usage-tracking.md) — adapter HTTP/file behaviour.
-- [keybindings.md](keybindings.md) — terminal key delivery and CSI-u.
+- [keybindings.md](keybindings.md) — terminal key delivery and aliases.
 - [hooks.md](hooks.md) — lifecycle hooks, startup commands, and `send-noti` payload contract.

package/docs/configuration.md

@@ -87,16 +87,16 @@ language.
 ## Keymap File
 
 Settings > Keybindings is the normal in-app editor for action keys. It lists
-each action, opens a detail screen, and uses `Press new key` to capture one
-keypress through the same controlling-TTY probe path as `projmux setup`.
-Saving writes safe tmux plain chords to `~/.config/projmux/keymap.toml`,
-rewrites `~/.config/projmux/tmux.conf`, and, when Settings is running inside
-tmux, sources that app config so tmux-level chords take effect immediately.
+user-configurable direct bindings, opens a detail screen, and offers `Add
+alias`, `Replace primary`, `Disable default`, `Reset`, `Press new key`, and
+`Type key chord`. Saving writes safe tmux plain chords to
+`~/.config/projmux/keymap.toml`, rewrites `~/.config/projmux/tmux.conf`, and,
+when Settings is running inside tmux, sources that app config so tmux-level
+chords take effect immediately.
 
-Settings reports CSI-u/User-key captures as terminal fallback delivery and
-does not write a keymap entry for them. Raw sequences that cannot be safely
-represented as a tmux plain chord are not persisted; configure terminal
-fallback with `projmux init` instead.
+Raw sequences that cannot be safely represented as a tmux plain chord are not
+persisted. Use Settings to save a safe direct alias, or use `projmux init` for
+the supported terminal mappings.
 
 `~/.config/projmux/keymap.toml` can also be edited by hand. When the file is
 absent, generated tmux config stays on the built-in defaults.
@@ -104,43 +104,54 @@ absent, generated tmux config stays on the built-in defaults.
 Supported schema:
 
 ```toml
-[bindings.sessionizer-sidebar]
-plain = "M-a"
+[bindings.ProjectSidebarToggle]
+keys = ["M-1", "M-a"]
 
 [bindings.new-window]
-plain = "C-t"
+keys = ["C-t"]
+
+[bindings."Sidebar:PinProject"]
+keys = ["M-p", "p"]
 ```
 
 Each table is `[bindings.<action-id>]`. Supported keys are:
 
 | Key | Meaning |
 | --- | --- |
-| `plain` | A no-prefix tmux chord such as `M-a`, `C-t`, or `M-S-Left`. |
+| `keys` | A list of no-prefix tmux plain chords such as `M-a`, `C-t`, or `M-S-Left`. |
+| `plain` | Legacy single-primary replacement. Still read, but not written by Settings. |
 
 Legacy `prefix = ...` entries still parse during migration so existing files
-do not break, but Settings no longer writes prefix keys and generated tmux
-config no longer binds the old action prefix chords.
+do not break. Settings preserves existing prefix entries when rewriting the
+file, but does not create new prefix keys, and generated tmux config no longer
+binds the old action prefix chords.
 
-Set a value to the empty string to disable that chord for the action:
+Use an empty `keys` list to disable direct plain aliases for the action:
 
 ```toml
-[bindings.sessionizer-sidebar]
-plain = ""
+[bindings.ProjectSidebarToggle]
+keys = []
 ```
 
-In Settings, `Disable` writes the empty plain override. `Reset default`
-removes that override and returns to the built-in default. The Settings writer
-is deterministic and rewrites the supported saved subset only:
-`[bindings.<action-id>]` tables with `plain` string keys. 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.
+In Settings, `Disable default` writes `keys = []`. `Reset` removes the saved
+override and returns to the built-in default. Legacy popup IDs such as
+`sessionizer-sidebar` still read, but new writes use canonical toggle names
+such as `ProjectSidebarToggle`, `NotifySidebarToggle`, `SessionPopupToggle`,
+`AISplitPickerToggle`, `SettingsToggle`, and `ProjectSwitcherToggle`. Internal
+popup commands use `Surface:Action` IDs and have surface-local conflict
+domains; those are manual `keymap.toml` entries, not Settings list/edit
+targets.
+
+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
-Ghostty and Windows Terminal still install the built-in CSI-u fallback map.
-Changing those terminal-layer mappings still requires rerunning `projmux init`
-and restarting the terminal where that terminal requires it.
+Ghostty and Windows Terminal install built-in plain-byte mappings where needed.
+Changing terminal-layer mappings still requires rerunning `projmux init` 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
@@ -169,6 +180,33 @@ configured key opens and closes the popup.
 | `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`. |
 
+## Welcome State
+
+`projmux shell` stores per-version welcome state under the projmux state
+directory, normally:
+
+```text
+${XDG_STATE_HOME:-$HOME/.local/state}/projmux/welcomed-v<version>.json
+```
+
+The current schema is:
+
+```json
+{
+  "version": 1,
+  "last_welcomed_version": "0.6.3",
+  "welcomed_at": "2026-05-21T00:00:00Z",
+  "skip_version": "0.6.3",
+  "skipped_at": "2026-05-21T00:00:00Z"
+}
+```
+
+`skip_version` is the only field that suppresses the shell welcome. When it
+matches the current projmux version, `projmux shell` skips the welcome. When it
+is absent or names a different version, the welcome is shown again. Older state
+files that contain only `last_welcomed_version` remain readable, but that field
+does not count as a skip.
+
 Example:
 
 ```sh
@@ -401,31 +439,6 @@ ${PROJMUX_USAGE_STATE_DIR:-${XDG_STATE_HOME:-$HOME/.local/state}/projmux/usage}/
 See [Usage tracking](usage-tracking.md) for adapter behavior, throttling, and
 failure handling.
 
-## Shell Welcome State
-
-`projmux shell` stores its once-per-version welcome marker under:
-
-```text
-${XDG_STATE_HOME:-$HOME/.local/state}/projmux/welcomed-v<version>.json
-```
-
-If the marker is missing, the next shell launch shows the welcome again. If the
-marker is corrupt or cannot be written, shell startup continues without the
-welcome.
-
-The same guide is also available on demand through `projmux welcome`, and it is
-linked from Settings > About as `Welcome`.
-
-When `pending_attach_welcome` is true, the generated projmux shell tmux config
-runs `projmux welcome --popup` asynchronously from the `client-attached` hook.
-That helper atomically claims the pending marker, flips it off, and shows the
-welcome guide in a tmux popup once for that version. Missing, corrupt, or
-already-consumed state is a quiet no-op.
-
-Set `PROJMUX_WELCOME=off` before launching or attaching to `projmux shell` to
-suppress the automatic attach popup. The manual `projmux welcome` command still
-prints the guide.
-
 ## Session State
 
 `projmux shell` autosaves session snapshots from the app tmux status tick. The
@@ -446,7 +459,12 @@ fixed snapshots. Rows include saved-at date/time metadata when projmux can
 determine it. `Back` returns to the project list without creating, replaying, or
 opening a session. After the startup mode is selected, project hook/config trust
 is evaluated if needed; approval continues the selected path and deny/cancel
-aborts without session create, snapshot replay, or startup command. Existing
+aborts without session create, snapshot replay, or startup command. The Alt-1
+sidebar opens trust as the shared client-scoped `Trust project hooks` popup
+instead of inline sidebar rows. The selected open continuation runs in a
+detached tmux job that can close the sidebar before trust without depending on
+the self-closing sidebar process to keep running. Deny/cancel refreshes the
+original sidebar query/selection context with a visible status message. Existing
 sessions switch directly without a startup picker.
 
 Default `projmux shell` no longer opens a startup picker or replays session-state