projmux 0.6.2 → 0.6.4

package/docs/keybindings.md

@@ -1,63 +1,33 @@
 # Terminal Keybindings
 
-projmux is keyboard-driven. `projmux shell` writes a tmux config that owns
-every binding listed here, so the keys are live the moment the app starts —
-no extra setup in most terminals.
+projmux is keyboard-driven, but the guaranteed launch contract is small:
+fresh installs bind `Alt-1` through `Alt-5` as plain Meta sequences
+(`M-1`..`M-5`, bytes `\x1b1`..`\x1b5`). Other actions remain discoverable in
+Settings > Keybindings. Transport-dependent actions keep their built-in
+transport default key, and Settings can add separate safe tmux plain aliases to
+the same action. They are not installed as terminal-specific User-key
+fallbacks. `UserN` and `CSI-u` are legacy/removal/unsupported targets, not
+supported fallback guidance.
 
 The recommended path when a key does not fire:
 
-1. Press the key inside `projmux shell` and see what works on your terminal
-   out of the box ([Quick start](#quick-start-no-setup)).
-2. If something is swallowed, open Settings > Keybindings and select the
-   action to capture the key, or run [`projmux setup`](#diagnose-projmux-setup)
-   outside tmux. Both paths tell you exactly which sequences reach the process
-   and which the terminal is eating.
-3. For terminals projmux knows how to configure, run
-   [`projmux init [terminal]`](#auto-config-projmux-init) as the fallback:
-   preview first, then add `--apply` to merge the right bindings into your
-   terminal config with a timestamped backup.
-4. If your terminal is not in the init list (or you prefer to edit configs by
-   hand), use the [Manual fallback / advanced (CSI-u)](#manual-fallback--advanced-csi-u)
-   section.
-
-To change a user-facing key, open Settings > Keybindings, select an action,
-then choose `Press new key`. Settings captures one keypress through the same
-TTY probe path used by `projmux setup`, writes safe tmux plain chords to
-`~/.config/projmux/keymap.toml`, regenerates `~/.config/projmux/tmux.conf`,
-and hot-reloads the live tmux config when Settings is running inside tmux.
-CSI-u/User-key captures are reported as terminal fallback delivery and do not
-need a keymap write. Raw sequences that cannot be represented safely as a tmux
-plain chord are not persisted; configure terminal fallback with `projmux init`
-instead.
-
-The Settings surface no longer exposes plain/prefix tmux chord fields. Legacy
-`prefix = ...` entries in an existing `keymap.toml` still parse during
-migration, but Settings does not write new prefix entries and generated tmux
-config no longer binds the old action prefix chords.
-
-> 한국어 요약: 대부분의 터미널은 `projmux shell` 만으로 아래 키가 바로 동작합니다.
-> 동작하지 않으면 `projmux setup` 으로 어떤 키가 막혔는지 진단하고,
-> `projmux init [terminal]` 으로 자동 설정하세요. 자동 설정이 없는 터미널은
-> 마지막 [Manual fallback / advanced (CSI-u)](#manual-fallback--advanced-csi-u)
-> 섹션의 매핑표를 참고해 직접 설정하면 됩니다.
-
-The tmux **prefix** is the upstream default `Ctrl-b`. Inside the running
-session, `Ctrl-b ?` lists every binding live.
-
-## Quick start (no setup)
-
-These shortcuts are bound by projmux's generated tmux config. On terminals
-that pass `Alt-*` and `Ctrl-*` chords through to the running process
-unchanged (e.g. Linux gnome-terminal, foot, most stock Linux terminals),
-they work the moment you launch `projmux shell` — no terminal config
-required.
-
-If a key does nothing, jump to
-[Diagnose: `projmux setup`](#diagnose-projmux-setup) instead of guessing.
-
-### Pickers
-
-These open the projmux popups and the sidebar. No prefix needed.
+1. Try the key inside `projmux shell`.
+2. Open Settings > Keybindings > Diagnostic, or run `projmux setup` outside
+   tmux, to see which bytes reach the process.
+3. For supported terminals, preview `projmux init [terminal]`; add `--apply`
+   only after reviewing the merge.
+4. For unsupported terminals, configure plain Meta bytes or add a tmux alias in
+   Settings > Keybindings.
+
+Settings writes safe tmux plain chords to
+`~/.config/projmux/keymap.toml`, regenerates
+`~/.config/projmux/tmux.conf`, and hot-reloads the live tmux config when it is
+running inside tmux. Raw escape payloads, Windows Terminal `sendInput` strings,
+and tmux User keys are rejected as aliases.
+
+## Quick Start
+
+These shortcuts are the guaranteed launch defaults. They need no tmux prefix.
 
 | Shortcut | Action |
 | --- | --- |
@@ -66,263 +36,164 @@ These open the projmux popups and the sidebar. No prefix needed.
 | `Alt-3` | Existing session popup |
 | `Alt-4` | AI split picker |
 | `Alt-5` | Settings |
-| `Alt-6` | Project switcher popup |
 
-### Windows, panes, AI splits
+The tmux prefix remains the upstream default `Ctrl-b`. Inside a running
+session, `Ctrl-b ?` lists the live tmux bindings.
 
-| Shortcut | Action |
-| --- | --- |
-| `Ctrl-n` | New tmux window in the current pane's directory |
-| `Alt-Shift-Left` / `Alt-Shift-Right` | Previous / next window |
-| `Alt-Left` / `Right` / `Up` / `Down` | Move focus between panes |
-| `Alt-r` | Rename the current window |
-
-When a pane closes, projmux re-spreads remaining panes so the surviving split
-does not stretch lopsided.
-
-The AI split bindings use the configured default mode. For one-shot launches,
-run `projmux ai split --agent claude|codex|shell|selective right|down`. Extra
-args after `--` are appended to the resolved `claude` or `codex` executable for
-a managed pane. To register user-level skills, slash commands, editor actions,
-or launcher shortcuts that call those one-shot launches, see
-[AI Agent Shortcuts](ai-agent-shortcuts.md).
-
-### Inside the pickers
-
-| Surface | Shortcut | Action |
-| --- | --- | --- |
-| Existing session popup | `Ctrl-X` | Kill the focused session and reopen the popup |
-| Existing session popup | `Left/Right` | Preview previous/next window |
-| Existing session popup | `Alt-Up/Alt-Down` | Preview previous/next pane |
-| Project switcher | `Ctrl-X` | Kill the focused existing session and reopen the picker |
-| Project switcher | `Alt-P` | Pin or unpin the focused directory |
-
-### Conditional rename keys
-
-These two only fire if your terminal forwards CSI-u sequences for `Ctrl-M`
-and `Ctrl-Shift-M`. Without that wiring, plain `Ctrl-M` is just `Enter` and
-`Ctrl-Shift-M` typically does nothing. `projmux init` configures this for
-the terminals it supports; otherwise see
-[Manual fallback / advanced (CSI-u)](#manual-fallback--advanced-csi-u).
+## Discoverable Actions
 
-| Shortcut | Action |
+Settings > Keybindings lists the full action catalogue. In particular, sidebar
+keymap actions, pane switching, window switching, and rename actions remain
+visible. Transport-dependent rows show the default transport key separately
+from editable plain aliases.
+
+Optional direct aliases can be added for actions such as:
+
+| Canonical action | Meaning |
+| --- | --- |
+| `ProjectSwitcherToggle` | Project switcher popup |
+| `new-window` | New tmux window in the current pane directory |
+| `rename-window` | Rename the current tmux window |
+
+Pane switching is catalogued as transport-dependent and the generated app tmux
+config binds `M-Left`, `M-Right`, `M-Up`, and `M-Down` to `select-pane`
+movement. Previous/next window remain transport-dependent and the generated app
+tmux config binds `M-S-Left` / `M-S-Right` to the tmux window navigation
+commands. These default transport keys are always rendered by projmux, because
+delivery still depends on the terminal forwarding the modifier-arrow sequence.
+Settings can add extra safe plain aliases, such as `M-[` for
+`previous-window`; those aliases are saved to `keymap.toml` as `keys = [...]`
+without storing or replacing the transport default. Rename actions no longer
+have a built-in terminal fallback; use tmux's prefix rename flow or configure
+an explicit safe alias where the action is editable.
+
+## Roadmap Requirements
+
+Follow-up Phase 2 keeps Settings > Keybindings as a discovery surface. It must
+continue to expose launch toggles, sidebar keymap actions, picker-local actions,
+pane switching, window switching, and rename actions. Transport-dependent rows
+should explain the default transport key and offer only additive safe plain
+aliases; diagnostic-only rows should explain why they are not editable.
+
+Follow-up Phase 3 removes the `UserN` / `CSI-u` route from the product model.
+Windows Terminal and Ghostty-centered replacements should use plain
+Meta/control chords or xterm modifier sequences where possible. If a key cannot
+be represented that way, leave it as a non-editable unsupported or diagnostic
+row instead of preserving a User-key or CSI-u fallback.
+
+## Picker Actions
+
+Picker-internal commands are surface-scoped. The same physical key can be used
+by different picker surfaces, while conflicts inside one surface are rejected.
+
+| Surface action | Meaning |
 | --- | --- |
-| `Ctrl-M` | Rename the current window (terminal must send `User10`) |
-| `Ctrl-Shift-M` | Rename the current AI pane label / topic (terminal must send `User11`) |
+| `Sidebar:KillSession` | Kill the focused existing session |
+| `Sidebar:PinProject` | Pin or unpin the focused directory |
+| `SessionPopup:KillSession` | Kill the focused session |
+| `SessionPopup:CyclePreviewWindowPrev` / `SessionPopup:CyclePreviewWindowNext` | Preview windows |
+| `SessionPopup:CyclePreviewPanePrev` / `SessionPopup:CyclePreviewPaneNext` | Preview panes |
+| `NotifySidebar:Ack` / `NotifySidebar:ClearNonCritical` / `NotifySidebar:ClearAll` | Manage notifications |
 
-## Diagnose: `projmux setup`
+Runtime picker footers render key guides from the merged keymap, preferring the
+default alias when it is present and otherwise using the first configured alias.
+
+## Keymap File
+
+Settings writes the action-centered multi-alias schema:
+
+```toml
+[bindings.ProjectSidebarToggle]
+keys = ["M-1", "M-a"]
 
-Run `projmux setup` *outside* tmux (in your raw terminal window) to find out
-which projmux keys actually reach the process. The command auto-detects your
-terminal, then asks you to press each shortcut in turn and classifies the
-result:
+[bindings.new-window]
+keys = ["C-t"]
 
-The same diagnostic is available in-app at Settings > Keybindings > Diagnostic.
-The flow reads the controlling TTY directly, so it can probe a
-key while Settings itself is running inside tmux.
+[bindings.previous-window]
+keys = ["M-["] # additive alias; default M-S-Left is not stored here
+
+[bindings."Sidebar:PinProject"]
+keys = ["M-p", "p"]
+```
+
+Legacy files using `plain = "M-a"` still read as a single-primary replacement
+override. New writes use `keys = [...]`. `keys = []` disables the direct plain
+aliases for that action. Legacy `prefix = ...` entries still parse during
+migration and are preserved when Settings rewrites the file, but Settings does
+not create new prefix entries.
+
+Legacy popup IDs such as `sessionizer-sidebar`, `notify-sidebar`,
+`session-popup`, `ai-split-picker-right`, `ai-split-settings`, and
+`sessionizer` still read. Settings and new docs show the canonical toggle
+names: `ProjectSidebarToggle`, `NotifySidebarToggle`, `SessionPopupToggle`,
+`AISplitPickerToggle`, `SettingsToggle`, and `ProjectSwitcherToggle`.
+
+## Diagnose: `projmux setup`
+
+Run `projmux setup` outside tmux to find out which projmux keys reach the raw
+terminal. The same diagnostic is available in-app at Settings > Keybindings >
+Diagnostic.
 
 | Status | Meaning |
 | --- | --- |
-| `OK plain` | The terminal forwarded the bare escape (e.g. `\x1b1` for `Alt-1`); tmux's plain bind handles it. |
-| `OK csi-u` | The terminal already forwards a `ESC [ NNNNu` sequence routed to a tmux `User*` key. You are fully wired. |
-| `MISS timeout` | No bytes arrived — the terminal swallowed the key for its own action. |
-| `MISS unknown` | Something arrived, but it does not match either expected sequence — the terminal bound this combo to a different action. |
-
-The summary at the end lists the failing keys and a remediation hint
-tailored to the detected terminal (Ghostty, WezTerm, kitty, iTerm2,
-Alacritty, Windows Terminal, foot, VS Code, …). When projmux ships an init
-adapter for the terminal, the summary gives both the dry-run preview and the
-exact apply command, e.g. `projmux init ghostty --apply`. Settings >
-Keybindings shows the same delivery categories after a capture.
+| `OK plain` | The terminal forwarded the expected bytes, such as `\x1b1` for `Alt-1`; tmux can bind this directly. |
+| `MISS timeout` | No bytes arrived because the terminal swallowed the key. |
+| `MISS unknown` | Bytes arrived, but they do not match the expected plain sequence. |
 
 Useful flags:
 
 ```sh
-projmux setup                       # interactive probe (default)
-projmux setup --timeout 10s         # wait longer per key
-projmux setup --non-interactive     # just print the expected key map and exit
+projmux setup
+projmux setup --timeout 10s
+projmux setup --non-interactive
 ```
 
-`--non-interactive` is handy when you only want to see, on this machine and
-shell, which `plain` and `csi-u` byte sequences projmux is listening for —
-useful for hand-rolling a config in a terminal projmux does not yet know
-about.
+## Auto-Config: `projmux init`
 
-> 한국어 요약: `projmux setup` 을 tmux *밖에서* 실행하면, 진단 대상 키를 차례로
-> 누르며 어떤 키가 plain/CSI-u 로 도달하는지, 어떤 키가 swallow 되는지 표로
-> 알려줍니다. 끝에서 터미널별 다음 단계를 제안합니다.
-
-## Auto-config: `projmux init`
-
-`projmux init` is the supported fallback when `projmux setup` shows that a
-terminal swallows shortcuts projmux already binds in tmux. It merges the
-projmux CSI-u keybindings into a terminal emulator's config file. Default
-mode is **dry-run** — nothing is written until you pass `--apply`. Applying
-the merge always creates a timestamped backup of the previous file.
+`projmux init` previews and optionally applies supported terminal mappings.
+Default mode is dry-run; pass `--apply` to write changes with a timestamped
+backup.
 
 ```sh
-projmux init                              # auto-detect + dry-run preview
-projmux init ghostty                      # explicit terminal, dry-run preview
-projmux init ghostty --apply              # write changes (with .bak.<ts> backup)
-projmux init --config /path/to/file       # bypass auto-detected paths
-projmux init --allow-symlink              # opt in to merging through a symlink
-projmux init --dry-run                    # force dry-run even with no other flag
+projmux init
+projmux init ghostty
+projmux init ghostty --apply
+projmux init windows-terminal --apply
+projmux init --config /path/to/file
+projmux init --allow-symlink
 ```
 
-The merge is idempotent: bindings already pointing at the desired action are
-no-ops, missing bindings are appended in a managed block, and triggers
-already mapped to a *different* action are left untouched and reported as
-`skip-conflict` warnings — projmux never silently overwrites your custom
-mappings. Re-running `projmux init --apply` after editing the file refreshes
-just the projmux-owned region.
-
-`projmux init` always uses the built-in terminal fallback map. To override the
-tmux chords rendered by `projmux tmux print-config`, `projmux tmux install`,
-or `projmux shell`, use Settings > Keybindings or edit
-`~/.config/projmux/keymap.toml`; see [Configuration](configuration.md#keymap-file).
-
-### Supported terminals
-
-#### Ghostty
-
-- Detection: `TERM_PROGRAM=ghostty` or `GHOSTTY_RESOURCES_DIR` set.
-- Config candidates (resolved in this order):
-  1. `<config-dir>/ghostty/config` — canonical default
-  2. `<config-dir>/ghostty/config.ghostty` — common dotfiles convention
-
-  `<config-dir>` honours `$XDG_CONFIG_HOME` first, then `$HOME/.config`.
-  When both candidates exist, init refuses to guess and asks for
-  `--config <path>` to disambiguate.
-- Idempotency marker: bindings live inside a managed block delimited by
-
-  ```text
-  # >>> projmux managed keybindings (do not edit between markers)
-  ...
-  # <<< projmux managed keybindings
-  ```
-
-  Edit anything *outside* those markers freely; init re-renders the inside
-  on every `--apply`.
-- Symlink guard: if the resolved config path is a symlink (typical when
-  dotfiles users symlink the terminal config into a tracked repo), init
-  refuses by default to avoid silently mutating the symlink target. Pass
-  `--allow-symlink` to opt in, or `--config <path>` to point at a
-  non-symlinked file.
-
-#### Windows Terminal (including WSL)
-
-- Detection: `WT_SESSION` set (native Windows), or `WSL_DISTRO_NAME` /
-  `WSL_INTEROP` set (running from inside WSL where the host terminal is
-  Windows Terminal).
-- Config resolution:
-  - Native Windows: `%LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_*\LocalState\settings.json`.
-  - WSL: resolves `%LOCALAPPDATA%` through `cmd.exe /c echo %LOCALAPPDATA%`
-    interop, then translates `C:\Users\...` into `/mnt/c/Users/...` so the
-    Linux side can read/write the file directly.
-- Merge model: settings.json is JSONC (allows `//` and `/* */` comments,
-  trailing commas). Init parses, locates `actions[]` and `keybindings[]`,
-  and merges entries identified by the `User.projmux*` ID prefix. Anything
-  outside that prefix is preserved verbatim, including comments and
-  formatting where reasonable.
-- Conflicts: a key already mapped to a non-projmux action is skipped with a
-  warning, same as Ghostty.
-
-### Reading dry-run output
-
-Each line of the dry-run plan prefixes the action with one of:
-
-| Prefix | Meaning |
-| --- | --- |
-| `+` | New binding will be added. |
-| `=` | Binding already matches; no change. |
-| `!` | Trigger is already mapped to a *different* action; will be skipped. Resolve manually before applying. |
-
-The trailing `note:` lines flag whether the config file does not yet exist
-(it will be created), and the final line tells you whether you still need
-`--apply` or whether the file is already up to date.
-
-> 한국어 요약: `projmux init` 은 dry-run 이 기본이고 `--apply` 시 timestamped
-> 백업 후 머지합니다. Ghostty 는 managed 블록 마커로 idempotent, 두 표준
-> path 모두 인식하며 symlink 는 default 거절. Windows Terminal 은 WSL interop
-> 으로 `/mnt/c/...` 경로까지 알아서 풀고, JSONC 형식의 `settings.json` 에
-> `User.projmux*` prefix 로 머지합니다. 사용자가 같은 키를 다른 액션에 매핑한
-> 경우 skip + warning.
-
-## Manual fallback / advanced (CSI-u)
-
-Use this section when:
-
-- your terminal is not yet supported by `projmux init`, or
-- you prefer to manage the config by hand, or
-- `projmux setup` shows specific keys still being swallowed and you want to
-  redirect just those.
-
-The fix is to map the swallowed keystroke to a CSI-u sequence the terminal
-forwards to tmux unchanged. projmux binds CSI-u escapes to tmux's
-`User0`–`User11` keys, so once the terminal forwards the sequence the
-action fires.
-
-### CSI-u Map
-
-| CSI-u sequence | tmux key | Action |
-| --- | --- | --- |
-| `ESC [ 9001 u` | `User0` | Open AI split to the right |
-| `ESC [ 9002 u` | `User1` | Open AI split below |
-| `ESC [ 9003 u` | `User2` | Notify sidebar |
-| `ESC [ 9004 u` | `User3` | Existing session popup |
-| `ESC [ 9005 u` | `User4` | Project sidebar |
-| `ESC [ 9006 u` | `User5` | AI split picker |
-| `ESC [ 9007 u` | `User6` | Settings |
-| `ESC [ 9008 u` | `User7` | New tmux window in the current pane directory |
-| `ESC [ 9011 u` | `User10` | Rename the current tmux window |
-| `ESC [ 9012 u` | `User11` | Rename the current tmux pane label |
-| `ESC [ 9013 u` | `User12` | Project switcher popup |
-
-> Previous/Next window (Alt-Shift-Left/Right) intentionally **do not** use a
-> CSI-u detour — both projmux and modern terminals already agree on the
-> xterm-standard modifier sequence (`\x1b[1;4D` / `\x1b[1;4C`), so tmux binds
-> directly to `M-S-Left` / `M-S-Right`. This keeps the popup-side chord
-> handler and the tmux root binding consuming the same sequence.
-
-### Ghostty (manual)
-
-`projmux init ghostty` is the maintained path. The block below is what the
-managed region in `~/.config/ghostty/config` ends up looking like — useful
-if you want to author it by hand or vet what init produces. Ghostty
-keybinds use `keybind = trigger=action`; the `csi:` action sends a CSI
-sequence without the leading `ESC [` bytes.
+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 aliases still
+belong in Settings > Keybindings or the keymap file.
+
+### Ghostty
+
+`projmux init ghostty` emits plain Meta bytes for `Alt-1` through `Alt-5` in
+the managed block:
 
 ```text
-keybind = alt+1=csi:9005u
-keybind = alt+2=csi:9003u
-keybind = alt+3=csi:9004u
-keybind = alt+4=csi:9006u
-keybind = alt+5=csi:9007u
-keybind = alt+6=csi:9013u
-
-keybind = ctrl+shift+r=csi:9001u
-keybind = ctrl+shift+l=csi:9002u
-
-keybind = ctrl+shift+n=csi:9008u
-keybind = ctrl+m=csi:9011u
-keybind = ctrl+shift+m=csi:9012u
+# >>> projmux managed keybindings (do not edit between markers)
+keybind = alt+1=text:\x1b1
+keybind = alt+2=text:\x1b2
+keybind = alt+3=text:\x1b3
+keybind = alt+4=text:\x1b4
+keybind = alt+5=text:\x1b5
+# <<< projmux managed keybindings
 ```
 
-`Alt-Shift-Left` and `Alt-Shift-Right` are intentionally absent: Ghostty
-already emits the xterm-standard `\x1b[1;4D` / `\x1b[1;4C` sequences for
-those chords, which tmux now binds directly. Adding a `csi:9009u` /
-`csi:9010u` override would re-introduce the detour that hid the chord from
-projmux popup handlers.
-
-Reload Ghostty or restart the terminal after changing the config.
+Config candidates are `<config-dir>/ghostty/config` and
+`<config-dir>/ghostty/config.ghostty`, with `$XDG_CONFIG_HOME` preferred over
+`$HOME/.config`. If both exist, pass `--config <path>`. Symlinked configs are
+refused by default; pass `--allow-symlink` to write through the link.
 
-### Windows Terminal (manual)
+### Windows Terminal
 
-`projmux init windows-terminal` (which also covers WSL) is the maintained
-path. Use the snippet below to author `settings.json` by hand. Add
-`sendInput` actions and bind them from `keybindings`. Windows Terminal
-works well with plain tmux escape sequences for the default `Alt`
-shortcuts, while the split actions can send tmux prefix sequences directly. Escape bytes should be written as `\u001b`.
+`projmux init 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:
 
 ```json
 {
@@ -332,35 +203,14 @@ shortcuts, while the split actions can send tmux prefix sequences directly. Esca
     { "command": { "action": "sendInput", "input": "\u001b3" }, "id": "User.projmuxSessions" },
     { "command": { "action": "sendInput", "input": "\u001b4" }, "id": "User.projmuxAIPicker" },
     { "command": { "action": "sendInput", "input": "\u001b5" }, "id": "User.projmuxSettings" },
-    { "command": { "action": "sendInput", "input": "\u001b6" }, "id": "User.projmuxSwitch" },
     { "command": { "action": "sendInput", "input": "\u0002r" }, "id": "User.projmuxAISplitRight" },
     { "command": { "action": "sendInput", "input": "\u0002l" }, "id": "User.projmuxAISplitDown" },
     { "command": { "action": "sendInput", "input": "\u000e" }, "id": "User.projmuxNewWindow" },
     { "command": { "action": "sendInput", "input": "\u001b[1;4D" }, "id": "User.projmuxPrevWindow" },
-    { "command": { "action": "sendInput", "input": "\u001b[1;4C" }, "id": "User.projmuxNextWindow" },
-    { "command": { "action": "sendInput", "input": "\u001b[9011u" }, "id": "User.projmuxRenameWindow" },
-    { "command": { "action": "sendInput", "input": "\u001b[9012u" }, "id": "User.projmuxRenamePane" }
-  ],
-  "keybindings": [
-    { "id": "User.projmuxSidebar", "keys": "alt+1" },
-    { "id": "User.projmuxNotifySidebar", "keys": "alt+2" },
-    { "id": "User.projmuxSessions", "keys": "alt+3" },
-    { "id": "User.projmuxAIPicker", "keys": "alt+4" },
-    { "id": "User.projmuxSettings", "keys": "alt+5" },
-    { "id": "User.projmuxSwitch", "keys": "alt+6" },
-    { "id": "User.projmuxAISplitRight", "keys": "ctrl+shift+r" },
-    { "id": "User.projmuxAISplitDown", "keys": "ctrl+shift+l" },
-    { "id": "User.projmuxNewWindow", "keys": "ctrl+n" },
-    { "id": "User.projmuxPrevWindow", "keys": "alt+shift+left" },
-    { "id": "User.projmuxNextWindow", "keys": "alt+shift+right" },
-    { "id": "User.projmuxRenameWindow", "keys": "ctrl+m" },
-    { "id": "User.projmuxRenamePane", "keys": "ctrl+shift+m" }
+    { "command": { "action": "sendInput", "input": "\u001b[1;4C" }, "id": "User.projmuxNextWindow" }
   ]
 }
 ```
 
-This example matches the default projmux app shortcuts without depending on
-CSI-u support from Windows Terminal for the `Alt` shortcuts. `Ctrl-M` and
-`Ctrl-Shift-M` still use CSI-u so tmux can distinguish rename commands from
-plain Enter. If a key is already bound by Windows Terminal, remove or change
-the conflicting `keybindings` entry before adding the projmux binding.
+Windows Terminal config is JSONC; comments and unrelated user entries are
+preserved where possible. Conflicting user-owned keys are skipped.

package/docs/native-picker-no-fzf-poc.md

@@ -16,6 +16,9 @@ The fzf compatibility surface for the native engine is tracked in
   execution, and result contracts, while moving visual composition into
   `projmuxpicker` so projmux can evolve a native picker design without coupling
   every visual tweak to the compatibility option/result shape.
+  Built-in fallback colors are centralized as semantic tokens in
+  `internal/theme/palette.go`; see [theme-palette.md](theme-palette.md) for the
+  current inventory and truecolor to tmux 256-color mapping policy.
 - `internal/ui/pickercompat` remains an internal compatibility mapper between
   the old option/result shape and the backend-neutral `picker.Options`
   contract. It is not a runtime backend. App code should
@@ -29,7 +32,7 @@ The fzf compatibility surface for the native engine is tracked in
 - The native picker supports ranked fuzzy search/filter, arrow-key selection in
   normal CSI and tmux application-cursor modes, Enter, Esc, Ctrl-C, Backspace,
   Ctrl-U, Ctrl-W, PageUp/PageDown, Home/End, modified CSI keys, custom expect
-  keys such as Ctrl-X/Alt-P, printable expect keys such as notify `x`, control
+  keys such as Ctrl-X/Alt-P, printable expect keys such as notify `a`/`x`, control
   expect keys such as notify `Ctrl-X`, `start:pos(N)` initial focus, preview
   command output, preview cycle command bindings, and sidebar focus command
   bindings.
@@ -40,9 +43,10 @@ The fzf compatibility surface for the native engine is tracked in
 - Typed-query prompts support cursor-aware insertion/deletion with a visible
   prompt cursor, Left/Right, Ctrl-A/E, Delete, Backspace, Ctrl-U, and Ctrl-W
   for settings path entry.
-- The native key parser recognizes the app's CSI-u keybind-probe sequences
-  such as `ESC [ 9005 u` for `Alt-1`, plus generic modified CSI-u forms such as
-  `ESC [ 115 ; 7 u` for `Ctrl-Alt-S`.
+- The native key parser keeps legacy parser-fixture coverage for app-specific
+  modified-key escapes, plus generic modified forms such as `ESC [ 115 ; 7 u`
+  for `Ctrl-Alt-S`. This is backend parser parity, not a product fallback
+  route.
 - Native interactive picker screens use an alternate screen lifecycle to better
   match fzf fullscreen behavior and restore the tmux pane after exit. Frame
   updates and screen exit both return to column 0 before emitting terminal

package/docs/native-picker-parity.md

@@ -27,10 +27,10 @@ native picker engine and is not a public dependency-policy change.
 | selected multi-line marker | selected switch/session/notify cards | Covered for app multiline rows | native uses the same compact pointer-width red `▌` gutter as the first selected project line, and metadata lines align to the project-name column without the old deeper indent; `nativeContinuation`; `TestNativeInteractiveRendersSelectedMultilineContinuationMarker`; `TestInteractiveRowLinesUsesCompactSelectedMetaIndent`; `TestInteractiveRowLinesAlignsUnselectedMetaWithProjectName` |
 | fzf current row colors | simple and multi-line rows | Covered for app rows | `nativeCurrentStart`, `nativePointer`; pointer/continuation gutter tokens carry the current-row background; `TestNativeSelectedContentKeepsCurrentStyleAfterReset`; `TestNativeInteractiveUsesCurrentStyleForSimpleSelection` |
 | `--expect` keys | Enter/Ctrl-X/Alt-P/notify keys | Covered | `pickercompat.PickerOptions`; `TestNativeInteractiveSupportsCustomExpectKeys` |
-| printable expect keys | notify sidebar `x` ack | Covered | `TestNativeInteractiveSupportsPrintableExpectKeys`; Docker no-fzf e2e |
+| printable expect keys | notify sidebar `a` ack and `x` non-critical clear | Covered | `TestNativeInteractiveSupportsPrintableExpectKeys`; Docker no-fzf e2e |
 | control expect keys | notify sidebar `Ctrl-X`, settings `Ctrl-Alt-S` close | Covered | `TestNativeInteractiveSupportsControlExpectKeys`; `TestNativeInteractiveSupportsControlAltCloseKeys` |
 | close `--bind key:abort` | Esc, Ctrl-C, Alt-N, Ctrl-Alt-S variants | Covered | `CloseActions`; `TestNativeRunnerUsesSharedCloseActions` |
-| terminal CSI-u key encoding | app keybind probe sequences, Ghostty/kitty-style modified keys | Covered | native handles app-specific Alt keys, generic modified letters/digits, and non-text keys such as Enter/Esc/Backspace/Tab; `TestNativeInteractiveSupportsCSIuAppKeyBindings` |
+| terminal modified-key encoding | legacy parser fixtures, Ghostty/kitty-style modified keys | Covered | native handles app-specific parser fixtures, generic modified letters/digits, and non-text keys such as Enter/Esc/Backspace/Tab; this is backend parity, not product fallback guidance; `TestNativeInteractiveSupportsCSIuAppKeyBindings` |
 | `execute-silent(...)+refresh-preview` | switch/session preview cycling | Covered for command execution and rerender loop | `pickercompat.PickerOptions`/`pickercompat.OptionsFromPicker`; `TestNativeInteractiveRunsCustomActionCommandAndRefreshes`; `TestPickerOptionsMapsCompatBindingsToContractActions`; Docker no-fzf e2e sends `Right` and `Alt-Down` before selection |
 | `focus:execute-silent(...)` | switch sidebar focus | Covered | native renders the selection frame diff before running sidebar focus commands so movement stays visible before tmux focus side effects; `runNativeFocusAction`; `TestNativeInteractiveRunsFocusActionOnSelectionChange` |
 | `start:pos(N)` | switch sidebar initial row | Covered | `pickercompat.PickerOptions`/`pickercompat.OptionsFromPicker`; `TestPickerOptionsFromCompatPickerMapsStartPosToInitialIndex`; `TestPickerOptionsMapsCompatBindingsToContractActions` |
@@ -43,7 +43,7 @@ native picker engine and is not a public dependency-policy change.
 | query cursor editing | typed settings path prompts | Covered | Left/Right, Ctrl-A/E, Delete, Backspace, Ctrl-U/W query editing plus visible prompt cursor; `TestNativeInteractiveEditsTypedQueryAtCursor`; `TestNativeInteractiveSupportsQueryLineEditingKeys`; `TestNativeInteractiveCtrlUDeletesBeforeCursor`; `TestNativePromptLineRendersQueryCursor` |
 | terminal arrow key variants | interactive selection in tmux/docker | Covered | CSI, SS3/application cursor, modified CSI tests; up/down movement wraps at list boundaries while PageUp/PageDown and Home/End remain clamped or explicit jumps; app TTY `/dev/tty` fallback; raw TTY EOF polling keeps split ESC sequences from leaking into the query; `TestNativeInteractiveWrapsPreviousNavigationKeys`; `TestNativeInteractiveWrapsNextNavigationKeys`; `TestNativeInteractiveJumpNavigationRemainsClamped` |
 | mouse support | optional fzf mouse picker interaction | Partially covered | native enables SGR mouse reporting in interactive alternate-screen mode, primary mouse down focuses the clicked row, primary mouse up applies it, and wheel input moves selection; drag gestures remain outside this POC; `TestNativeInteractiveSelectsOnMouseRelease`; `TestNativeInteractiveMouseDownOnlyFocuses`; `TestNativeInteractiveIgnoresMouseReleaseBeforeDown`; `TestNativeInteractiveSupportsMouseWheelSelection`; Docker no-fzf e2e clicks the AI settings row under a PTY |
-| fzf navigation keys | interactive selection in searchable lists | Covered | native maps CSI-u `Ctrl-J` plus `Ctrl-N` to down and `Ctrl-P`/`Ctrl-K` to up when not claimed by a custom action; up/down-family movement is safe on empty lists; raw LF remains Enter for PTY compatibility; `TestNativeInteractiveSupportsFZFNavigationKeys`; `TestNativeInteractiveNavigationKeysAreNoopForEmptyList` |
+| fzf navigation keys | interactive selection in searchable lists | Covered | native maps modified-key `Ctrl-J` plus `Ctrl-N` to down and `Ctrl-P`/`Ctrl-K` to up when not claimed by a custom action; up/down-family movement is safe on empty lists; raw LF remains Enter for PTY compatibility; `TestNativeInteractiveSupportsFZFNavigationKeys`; `TestNativeInteractiveNavigationKeysAreNoopForEmptyList` |
 | alternate-screen lifecycle | fzf fullscreen picker screen restore | Covered | native frame updates and screen exit return to column 0 before terminal control sequences, screen exit resets styles plus clears the alternate buffer from the home cursor before restore, and real TTY restores get a short settle window before caller handoff; `nativeScreenEnter`; `TestNativeInteractiveUsesAlternateScreen`; `TestRenderFullFrameUpdateAlwaysHomesAndWritesFrame` |
 | frame content width | fzf border inner width | Covered | `ContentLayout` uses the frame inner width so separators and rows reach the right border; `TestRendererContentLayoutUsesFrameInnerWidth` |
 | tmux popup frame interaction | native picker popups launched through `popup-toggle` | Covered for native backend popups | `popup-toggle` passes tmux `display-popup -B` when `PROJMUX_PICKER_BACKEND=native`, so the native picker owns the visible frame instead of double-drawing with the tmux popup border; native Alt-1 uses a compact native-only minimum while fzf keeps the previous project sidebar minimum; Alt-1/Alt-2 sidebar heights reserve two bottom statusbar rows; Alt-2 notify sidebar keeps the fzf-like `24%` / min `64` baseline; `TestAppRunTmuxPopupToggleUsesBorderlessPopupForNativeBackend`; `TestSessionizerSidebarWidthKeepsFZFMinimum`; `TestSidebarPopupHeightLeavesStatusbarRows`; `TestNotifySidebarWidthMatchesFZFBaseline`; `TestAppRunTmuxPopupToggleKeepsNotifySidebarFZFSizingForNative` |
@@ -108,7 +108,7 @@ contract; native popups still rely on the existing borderless tmux popup path.
   preview cursor, selects `bravo-web`, and asserts tmux reports the selected
   session's active target on the expected window with the expected pane path.
 - `notify sidebar`: native routing is unit-covered; Docker no-fzf e2e pushes a
-  notification, presses printable expect key `x`, and verifies the row is acked.
+  notification, presses printable expect key `a`, and verifies the row is acked.
 
 ## Experimental Boundaries
 

package/docs/notify-queue.md

@@ -93,12 +93,14 @@ repeatable filters. Without `--live`, this command reads only the queue and
 preserves the stable JSON array used by scripts.
 
 `--ui=sidebar` opens the notify queue as an interactive right-side list when
-run inside the tmux popup surface. Enter focuses the selected target pane and
-acks the row after focus succeeds. `x` acks the selected row in place, keeps
-the sidebar open, and refreshes the list from the queue while preserving the
-selection position where possible; acking the last remaining row renders the
-empty state until the popup is closed. `Ctrl-X` clears all rows via `notify ack
---all` and exits. Rows are intentionally compact: the visible label keeps
+run inside the tmux popup surface. Selecting a row focuses the selected target
+pane and acks the row after focus succeeds. The surface actions
+`NotifySidebar:Ack`, `NotifySidebar:ClearNonCritical`, and
+`NotifySidebar:ClearAll` are internal picker actions; direct launch aliases
+are edited in Settings, while internal picker aliases are adjusted in
+`keymap.toml` when needed. Runtime footer key guides read the merged keymap
+and show the default alias when present, otherwise the first configured alias,
+so custom aliases do not make the UI stale. Rows are intentionally compact: the visible label keeps
 notification text first, then age, project, window, and pane metadata; hidden
 queue ids remain action values but the sidebar has no search input and
 intentionally does not expose a separate metadata detail view.