projmux 0.4.9 → 0.5.0

package/docs/keybindings.md

@@ -8,9 +8,10 @@ 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, run [`projmux setup`](#diagnose-projmux-setup)
-   outside tmux — it tells you exactly which sequences reach the process and
-   which the terminal is eating.
+2. If something is swallowed, open Settings > Labs > Diagnose keybindings, 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
@@ -19,6 +20,24 @@ The recommended path when a key does not fire:
    hand), use the [Manual fallback / advanced (CSI-u)](#manual-fallback--advanced-csi-u)
    section.
 
+To change projmux's tmux-level chords, open Settings > Keybindings. The
+in-app editor writes `~/.config/projmux/keymap.toml`, regenerates
+`~/.config/projmux/tmux.conf`, and hot-reloads the live tmux config when
+Settings is running inside tmux. Terminal fallback mappings are separate:
+after changing fallback keys, rerun `projmux init` and restart the terminal
+where applicable.
+
+Settings > Labs > Diagnose keybindings reuses the same probe and terminal
+fallback engines from `projmux setup` and `projmux init`. It lists the
+keybinding catalog, lets you press one action key at a time from inside the
+app, distinguishes plain / CSI-u / unexpected / timeout outcomes, and exposes
+preview/apply rows for supported terminal fallbacks. When an unexpected
+sequence can be safely read as a tmux plain chord, the Lab shows an explicit
+`Save as plain override` row with the suggested chord; it never overwrites
+`keymap.toml` from an unexpected sequence unless you select that confirmation
+row. The Lab also shows whether the detected terminal can reload config after
+fallback apply or needs a restart/manual reload.
+
 > 한국어 요약: 대부분의 터미널은 `projmux shell` 만으로 아래 키가 바로 동작합니다.
 > 동작하지 않으면 `projmux setup` 으로 어떤 키가 막혔는지 진단하고,
 > `projmux init [terminal]` 으로 자동 설정하세요. 자동 설정이 없는 터미널은
@@ -106,6 +125,10 @@ 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:
 
+The same diagnostic is available in-app at Settings > Labs > Diagnose
+keybindings. The Lab flow reads the controlling TTY directly, so it can probe a
+key while Settings itself is running inside tmux.
+
 | Status | Meaning |
 | --- | --- |
 | `OK plain` | The terminal forwarded the bare escape (e.g. `\x1b1` for `Alt-1`); tmux's plain bind handles it. |
@@ -118,6 +141,9 @@ 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 > Labs also includes a concise after-apply hint: Ghostty/WezTerm/kitty
+can reload config, Windows Terminal and iTerm2 generally need a restarted tab
+or session, and unknown terminals are marked manual.
 
 Useful flags:
 
@@ -160,6 +186,11 @@ already mapped to a *different* action are left untouched and reported as
 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
@@ -253,12 +284,16 @@ action fires.
 | `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 [ 9009 u` | `User8` | Previous tmux window |
-| `ESC [ 9010 u` | `User9` | Next tmux window |
 | `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
@@ -281,10 +316,14 @@ keybind = ctrl+shift+l=csi:9002u
 keybind = ctrl+shift+n=csi:9008u
 keybind = ctrl+m=csi:9011u
 keybind = ctrl+shift+m=csi:9012u
-keybind = alt+shift+left=csi:9009u
-keybind = alt+shift+right=csi:9010u
 ```
 
+`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.
 
 ### Windows Terminal (manual)

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

@@ -1,7 +1,6 @@
 # Native Picker Engine
 
-This note tracks the native picker engine. Native is the default picker backend,
-while the `internal/ui/fzf` backend remains available as an explicit fallback.
+This note tracks the native picker engine. Native is the only picker backend.
 
 The fzf compatibility surface for the native engine is tracked in
 [native-picker-parity.md](native-picker-parity.md).
@@ -16,21 +15,14 @@ The fzf compatibility surface for the native engine is tracked in
   responsible for backend routing, keyboard input, filtering, preview command
   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 fzf adapter.
-- `internal/ui/fzf` now owns the adapter between fzf's legacy option/result
-  shape and the backend-neutral `picker.Options` contract. App code should
-  describe picker intent as rows, actions, preview commands, and initial focus;
-  the fzf adapter is responsible for translating that into `--expect`,
-  `--bind execute-silent(...)`, `+refresh-preview`, and `start:pos(N)`.
-- `intfzf.NewPickerRunner()` wraps fzf behind the same `picker.Runner`
-  interface as the native runner. This is the current DI boundary for swapping
-  picker engines while keeping fzf available.
-- Settings > Labs > Picker Engine stores the backend selection in
-  `~/.config/projmux/picker-backend` and updates the live tmux environment so
-  new picker popups can switch between `fzf` and `native` without restarting
-  the app server.
-- Native is the default backend. `PROJMUX_PICKER_BACKEND=fzf` remains an
-  explicit environment override and takes priority over the saved Labs setting.
+  every visual tweak to the compatibility option/result shape.
+- `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
+  describe picker intent as rows, actions, preview commands, and initial focus,
+  then route through the native picker.
+- Settings > Labs remains available for experimental settings, but picker
+  backend selection has been retired.
 - Picker flows covered by the native path include AI picker/settings, shell
   update prompt, settings hub sections, switch settings/add-pin, the main
   project switcher list, recent sessions, and notify sidebar.
@@ -41,9 +33,10 @@ The fzf compatibility surface for the native engine is tracked in
   expect keys such as notify `Ctrl-X`, `start:pos(N)` initial focus, preview
   command output, preview cycle command bindings, and sidebar focus command
   bindings.
-- FZF-style movement keys are supported for native selection: `Ctrl-N` moves
-  down, while `Ctrl-P` and `Ctrl-K` move up unless the app claims the key as a
-  custom action.
+- FZF-style movement keys are supported for native selection: `Ctrl-N` and
+  `Ctrl-J` move down, while `Ctrl-P` and `Ctrl-K` move up unless the app claims
+  the key as a custom action. Up/down-family movement wraps at list boundaries;
+  PageUp/PageDown and Home/End remain clamped or explicit jumps.
 - 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.
@@ -135,7 +128,8 @@ The fzf compatibility surface for the native engine is tracked in
 ## Experimental Boundaries
 
 - The `projmuxpicker` package is intended as a foundation that can be carried
-  forward, along with the fzf-to-picker adapter boundary in `internal/ui/fzf`.
+  forward, along with the compatibility option/result mapping in
+  `internal/ui/pickercompat`.
   Its frame, row, preview, theme, ANSI, and redraw modules are foundation code;
   Docker sandbox scripts and dependency-policy notes remain support
   scaffolding.
@@ -151,9 +145,7 @@ The fzf compatibility surface for the native engine is tracked in
   switch and sessions popup flows type a filtered query, send `Right` and
   `Alt-Down`, and assert the stored preview window/pane cursor for the selected
   session.
-- Public doctor dependency policy remains separate from picker backend
-  selection. Native is the default picker backend, and fzf remains available as
-  an explicit fallback.
+- Public doctor dependency policy no longer includes an external picker binary.
 
 ## Interactive No-fzf Sandbox
 

package/docs/native-picker-parity.md

@@ -14,8 +14,8 @@ native picker engine and is not a public dependency-policy change.
 | `--header` | AI, settings, shell update, notify | Covered | `renderNativeInteractive`, `renderNative`; settings native tests |
 | `--footer` / `--footer-border line` | AI, settings, shell update, switch, sessions, notify | Covered for interactive native screens | `renderNativeInteractive` reserves bottom footer space and renders a separator line; `TestNativeInteractiveRendersFooterAtBottom` |
 | `--ansi` | colored row labels from render package | Covered | native writes row labels directly, strips ANSI escapes from default search text, restores selected-row styling after embedded ANSI resets, and measures rendered cell width for Korean/CJK text, emoji, and combining marks; `TestFilterItemsIgnoresANSIEscapeSequences`; `TestNativeInteractiveUsesCurrentStyleForSimpleSelection`; `TestVisibleLenUsesTerminalCellWidth`; Docker e2e shows ANSI rows |
-| hidden value after tab delimiter | all picker selections and default fzf matching | Covered by `picker.Item.Value` and default search text | `fzf.PickerOptions`; `TestNativeRunnerFiltersAndSelectsByNumber`; `TestFilterItemsSearchesHiddenValueWhenNoSearchKey` |
-| plain fzf candidates without structured entries | legacy runner call shape | Covered | `fzf.PickerOptions`; `TestPickerOptionsFromFZFMapsCandidatesWhenEntriesAreEmpty` |
+| hidden value after tab delimiter | all picker selections and default fzf matching | Covered by `picker.Item.Value` and default search text | `pickercompat.PickerOptions`; `TestNativeRunnerFiltersAndSelectsByNumber`; `TestFilterItemsSearchesHiddenValueWhenNoSearchKey` |
+| plain fzf candidates without structured entries | compat option call shape | Covered | `pickercompat.PickerOptions`; `TestPickerOptionsFromCompatPickerMapsCandidatesWhenEntriesAreEmpty` |
 | search key filtering (`--nth`/reload filter file) | switch/sessions/notify entries | Covered by `Item.SearchText` with fzf reload order preservation | `FilterItems`; `TestFilterItemsUsesSearchTextNotMetadata`; `TestFilterItemsPreservesSearchKeyOrder` |
 | default `--smart-case` matching | all searchable picker rows | Covered | native filter keeps lower-case queries case-insensitive and uppercase queries case-sensitive; `TestFilterItemsUsesFZFSmartCase` |
 | fzf match highlighting | searchable simple picker rows | Covered for non-search-key simple rows | native highlights matched visible label runes while preserving embedded ANSI style; search-key reload lists intentionally keep fzf disabled-filter rendering without match highlights; `TestNativeInteractiveHighlightsSimpleQueryMatches`; `TestNativeInteractiveDoesNotHighlightSearchKeyReloadLists` |
@@ -26,14 +26,14 @@ native picker engine and is not a public dependency-policy change.
 | `--gap --gap-line ─` | switch, sessions, notify multi-line rows | Covered for app multiline rows | `nativeGapLine`, row-budgeted range; `TestNativeInteractiveRendersMultilineGapLine`, `TestNativeVisibleRangeCountsMultilineRenderedRows` |
 | 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 | `fzf.PickerOptions`; `TestNativeInteractiveSupportsCustomExpectKeys` |
+| `--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 |
 | 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` |
-| `execute-silent(...)+refresh-preview` | switch/session preview cycling | Covered for command execution and rerender loop | `fzf.PickerOptions`/`fzf.OptionsFromPicker`; `TestNativeInteractiveRunsCustomActionCommandAndRefreshes`; `TestPickerOptionsMapsFZFBindingsToContractActions`; Docker no-fzf e2e sends `Right` and `Alt-Down` before selection |
+| `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 | `fzf.PickerOptions`/`fzf.OptionsFromPicker`; `TestPickerOptionsFromFZFMapsStartPosToInitialIndex`; `TestPickerOptionsMapsFZFBindingsToContractActions` |
+| `start:pos(N)` | switch sidebar initial row | Covered | `pickercompat.PickerOptions`/`pickercompat.OptionsFromPicker`; `TestPickerOptionsFromCompatPickerMapsStartPosToInitialIndex`; `TestPickerOptionsMapsCompatBindingsToContractActions` |
 | `--preview` | switch, sessions | Covered by command output | `nativePreviewLines`; `TestNativeInteractiveRendersSelectedPreview` |
 | `--preview-window right,60%,border-left` | switch popup, sessions popup | Covered for projmux option shape | `renderNativeSplitPreview` renders a single-column left border without a synthetic title row, uses fzf-measured percent sizing, normalizes preview tabs/control bytes before clipping, and pads both panes to fixed row widths so long preview rows do not wrap into extra vertical rows; `TestNativeInteractiveRendersWidePreviewBesideList`; `TestNativePreviewWidthUsesPreviewWindowPercent`; `TestRenderSplitPreviewRowsPadsBothPanes`; `TestRenderSplitPreviewRowsNormalizesPreviewTabsBeforeTruncating` |
 | `--preview-window down,25%,border-top` | switch sidebar | Covered for projmux option shape | `renderNativeDownPreview` renders an immediate top border without a synthetic title row, uses fzf-measured percent sizing, and pads preview rows to the surface width; `TestNativeInteractiveRendersDownPreviewBelowList`; `TestNativePreviewHeightUsesPreviewWindowPercent`; `TestRenderDownPreviewPadsPreviewRows` |
@@ -41,9 +41,9 @@ native picker engine and is not a public dependency-policy change.
 | `--query` | typed settings path defaults | Covered | `Options.InitialQuery`; settings tests |
 | `--print-query` accept-query mode | typed settings path prompts | Covered | `Options.AcceptQuery`; `TestNativeRunnerAcceptsTypedQuery` |
 | 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; app TTY `/dev/tty` fallback; raw TTY EOF polling keeps split ESC sequences from leaking into the query |
+| 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; raw LF remains Enter for PTY compatibility; `TestNativeInteractiveSupportsFZFNavigationKeys` |
+| 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` |
 | 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` |
@@ -52,36 +52,39 @@ native picker engine and is not a public dependency-policy change.
 
 ## Native Surface Architecture
 
-- `internal/ui/picker` remains the backend-neutral contract and owns fzf/native
+- `internal/ui/picker` remains the backend-neutral contract and owns native
   routing, keyboard input, fuzzy filtering, action dispatch, preview command
   execution, and result handling.
 - `internal/ui/projmuxpicker` owns projmux-native visual composition: frame,
   redraw updates, ANSI width/truncation, theme tokens, prompt/footer/list
   rendering, selected row styling, scrollbars/gap rows, and preview pane
   geometry/rendering.
-- `internal/ui/fzf` owns the compatibility adapter in both directions:
-  `picker.Options` becomes fzf flags/bindings for fallback, and legacy
-  `fzf.Options` becomes `picker.Options` for the native backend. This keeps app
-  code closer to a DI-style picker contract instead of embedding fzf binding
-  strings at each call site.
-- `intfzf.NewPickerRunner()` adapts fzf to the same `picker.Runner` interface
-  as `picker.NativeRunner`, so follow-up branches can inject either backend at
-  a narrower boundary without deleting the existing fzf runner.
-- Settings > Labs > Picker Engine persists the selected backend in
-  `~/.config/projmux/picker-backend` and updates the live tmux server
-  environment through `PROJMUX_PICKER_BACKEND`, while direct environment
-  overrides still win over saved config. Native is the default when no saved
-  backend or override exists; `fzf` remains available as an explicit fallback.
+- `internal/ui/pickercompat` remains as the internal compatibility option/result
+  mapper from older app option shapes to `picker.Options` for the native
+  backend. It is not a runtime backend. This keeps app code closer to a
+  DI-style picker contract instead of embedding binding strings at each call
+  site.
+- Settings > Labs remains available, but picker backend selection has been
+  retired. Deprecated saved/env backend values normalize to native.
 - The split lets projmux grow a first-party picker design independently from
-  the fzf compatibility adapter.
+  the compatibility option/result mapper.
+
+## Frame Chrome ANSI
+
+Native picker frame chrome is normalized in `internal/ui/projmuxpicker`.
+Titlebars restore the titlebar style after embedded ANSI resets, search prompt
+and footer separators fill the available frame width, and header, row, footer,
+and preview lines close any active SGR style before padding or frame borders can
+inherit it. This phase does not add popup modes or change the `popup-toggle`
+contract; native popups still rely on the existing borderless tmux popup path.
 
 ## Verified Flows
 
 - `ai` picker/settings: native backend routing covered by app tests. Docker
   no-fzf e2e also types `Codex` into `projmux ai settings` and verifies the
   native simple picker writes the `codex` mode without fzf.
-- `shell` update prompt: native backend routing covered by shared fzf-to-native
-  adapter and settings-style typed prompt tests.
+- `shell` update prompt: native backend routing covered by shared compat-to-native
+  bridge and settings-style typed prompt tests.
 - `settings`: native backend exercised in unit tests and Docker no-fzf e2e
   using Enter plus arrow-key navigation under a PTY. The Docker e2e also fails
   if the Settings flows write tmux no-server noise to stderr while running
@@ -121,9 +124,8 @@ native picker engine and is not a public dependency-policy change.
 - Mouse support is intentionally narrow in this POC: primary mouse down focuses
   the clicked row, primary mouse up applies it, and wheel input moves selection.
   Drag gestures and the full fzf mouse grammar are follow-up work.
-- The public doctor/docs dependency policy is tracked separately from picker
-  backend selection. Native is the default picker backend, while fzf remains an
-  explicit fallback.
+- The public doctor/docs dependency policy no longer includes an external
+  picker binary.
 - Draft PR: https://github.com/crevissepartners/projmux/pull/98.
 
 ## Commands

package/docs/picker-ui-plan.md

@@ -2,42 +2,27 @@
 
 ## Goal
 
-The project switcher needs a richer picker surface than a single-line fzf row.
-The target interaction is a card-like list where each item can show a title plus
-small contextual lines such as session state, window/pane summary, branch, or
-path. Search should stay focused on stable identity text, especially the project
-or session title, instead of matching every contextual preview line.
+The project switcher needs a rich native picker surface. The target interaction
+is a card-like list where each item can show a title plus small contextual lines
+such as session state, window/pane summary, branch, or path. Search should stay
+focused on stable identity text, especially the project or session title,
+instead of matching every contextual preview line.
 
 ## Current Contract
 
 The picker contract is split in two layers:
 
 - `internal/ui/picker` owns backend-neutral items, actions, preview metadata,
-  backend selection, title-focused filtering, and the default native runner.
-- `internal/ui/fzf` adapts that model into the historical fzf command line.
-
-The fzf fallback backend sends one logical row per item:
-
-```text
-<visible label>\t<selection value>
-```
-
-fzf is configured with:
-
-- `--delimiter "\t"`
-- `--with-nth 1`
-- `--exit-0`
-- optional `--preview` and `--preview-window`
-
-The app depends on fzf returning the selected row and then extracts the hidden
-value after the first tab. This contract is simple and stable, but it limits each
-row to one visible line.
+  title-focused filtering, and the native runner.
+- `internal/ui/pickercompat` is an internal compatibility option/result shape
+  for older app call sites. It is not a runtime backend, and product flows do
+  not execute the external fzf binary.
 
 ## fzf Capability Check
 
-The installed fzf version supports multi-line items with `--read0`. That means a
-single item can contain newline characters when input records are NUL-delimited.
-This can render card-like rows.
+This section is historical context. Earlier design work evaluated fzf because it
+supported multi-line items with `--read0`, where a single item can contain
+newline characters when input records are NUL-delimited.
 
 The simple fzf option path is not enough for the desired search behavior:
 
@@ -59,7 +44,7 @@ Use `--read0` and NUL-delimited multi-line entries. This is the smallest change,
 but contextual card text will participate in search unless the visible card is
 kept title-only. This does not meet the intended search model.
 
-This path is acceptable only as a temporary visual experiment.
+This path is retired and is not supported.
 
 ### 2. fzf custom filtering
 
@@ -73,13 +58,12 @@ Tradeoffs:
 - More edge cases around selection identity and tracking.
 - Still constrained by fzf's list layout and event model.
 
-This is viable, but it is a bridge rather than a clean long-term model.
+This bridge path is retired and is not supported.
 
 ### 3. Native picker TUI
 
 Introduce a picker abstraction and implement a native terminal UI for card rows,
-title-focused search, stable selection identity, and app-owned key handling. fzf
-remains the default backend until parity is reached.
+title-focused search, stable selection identity, and app-owned key handling.
 
 This best matches the desired product direction:
 
@@ -90,9 +74,9 @@ This best matches the desired product direction:
 
 ## Implemented Direction
 
-Do not extend the current fzf row format again as the main implementation. The
-previous hidden-field attempt showed that small fzf encoding changes can break
-selection and navigation in subtle ways.
+Do not extend the retired fzf row format again. The previous hidden-field attempt
+showed that small fzf encoding changes can break selection and navigation in
+subtle ways.
 
 Current implementation:
 
@@ -100,12 +84,8 @@ Current implementation:
   `SearchText`, `MetaLines`, `Badges`, and `PreviewTarget`.
 - `picker.Options` carries backend-neutral actions, preview metadata, prompt,
   footer, initial query, and multiline intent.
-- Native is the default backend and renders the popup/sidebar surfaces.
-- `PROJMUX_PICKER_BACKEND=fzf` opts into the external fzf runner. Native supports
-  multiline item rendering, title-focused search via `SearchText`, numeric
-  selection, and shared close actions.
-- Switcher popup/sidebar use the selected backend for preview and key action
-  parity, including native preview panes, raw-key navigation, and sidebar focus
-  tracking.
-
-fzf can stay as the stable fallback while the native picker continues to mature.
+- Native is the picker backend and renders the popup/sidebar surfaces.
+- Native supports multiline item rendering, title-focused search via
+  `SearchText`, numeric selection, and shared close actions.
+- Switcher popup/sidebar use native preview panes, raw-key navigation, and
+  sidebar focus tracking.

package/docs/repo-layout.md

@@ -21,7 +21,9 @@ projmux/
       tmux/
     state/
     ui/
-      fzf/
+      picker/
+      pickercompat/
+      projmuxpicker/
       render/
     version/
   docs/
@@ -36,7 +38,8 @@ projmux/
 - `cmd/projmux` contains only CLI wiring.
 - `internal/core` contains product behavior that should be testable without tmux.
 - `internal/integrations/tmux` should be the only place that knows tmux command strings and output formats.
-- `internal/ui/fzf` may depend on shelling out to `fzf`, but should call typed core services.
+- `internal/ui/picker` and `internal/ui/projmuxpicker` own native picker behavior.
+- `internal/ui/pickercompat` is an internal compatibility option/result shape for older app call sites. It is not a runtime backend; product code should route through the native picker.
 - `scripts/` is for development tooling only, not product logic.
 
 ## Early implementation order
@@ -46,5 +49,5 @@ projmux/
 3. `internal/core/pins`
 4. `internal/state`
 5. `internal/integrations/tmux`
-6. `internal/ui/fzf`
+6. `internal/ui/picker`
 7. CLI command wiring

package/docs/roadmap.md

@@ -19,7 +19,7 @@ core that 0.3 had landed.
 ### Diagnostics
 
 - `projmux doctor` — runtime dependency report. Enforces minimum tmux
-  3.4 and fzf 0.65.0 (`stale` status when present but below the floor).
+  3.4 and checks workflow dependencies such as `git` and `stty`.
 
 ### Focus
 
@@ -52,7 +52,7 @@ core that 0.3 had landed.
 
 - Two-line clickable status bar: row 0 is the existing
   session/window/path/git/kube row, row 1 splits notify (left) and
-  usage (right).
+  usage (right), with a row-0 settings click fallback.
 - `projmux statusbar click` — single dispatcher for both mouse clicks
   and the `prefix s {u,n,g,k,p,s}` keyboard chord. Window-list clicks
   on tabs short-circuit to native `select-window`.
@@ -71,20 +71,34 @@ v0.4 shipped.
 
 ### Picker UI
 
-- Picker-domain model separate from fzf row encoding (kept fzf as the
-  stable fallback backend). Done in the 0.5 picker contract slice.
+- Picker-domain model separate from row rendering. Done in the 0.5 picker
+  contract slice.
 - Native picker backend for multi-line card rows and title-focused search.
-  Done in the 0.5 picker contract slice, later promoted to the default picker
-  backend with `PROJMUX_PICKER_BACKEND=fzf` kept as the explicit fallback.
+  Done in the 0.5 picker contract slice, later promoted to the only picker
+  backend.
 - Port switcher popup/sidebar surfaces after parity tests cover
   selection, preview, and key actions.
 
 ### Picker dismissal
 
 - Picker-agnostic popup close/toggle handling so AI picker dismissal
-  does not depend on fzf-specific key bindings. Done in the 0.5 picker
-  contract slice; fzf maps close actions to `abort`, and the native runner
-  consumes the same close action keys.
+  does not depend on backend-specific key bindings. Done in the 0.5 picker
+  contract slice; the native runner consumes shared close action keys.
+
+### Keybindings
+
+- In-app Settings editor for tmux keymap entries. Done in the 0.5 keybinding
+  M4 slice: Settings > Keybindings lists actions, opens action detail rows,
+  accepts typed `plain`/`prefix` tmux chord strings, supports disable/reset,
+  writes `~/.config/projmux/keymap.toml`, regenerates the app tmux config, and
+  hot-reloads the live tmux config when Settings is running inside tmux.
+- M6 progress: Settings > Labs now exposes a Keybinding Lab that reuses the
+  setup probe and init merge engines for per-action diagnostics, single-key
+  plain/CSI-u/unknown/timeout outcomes, and supported terminal fallback
+  preview/apply actions.
+- Still outstanding for later milestones: broader terminal-specific fallback
+  remediation for changed/custom fallback mappings beyond the supported init
+  adapters.
 
 ### Docker install and E2E harness
 

package/docs/statusbar.md

@@ -27,7 +27,10 @@ row 1  #[range=user|notify] <notify HUD pill> #[norange]
   `isWindowListRangeToken` fallback is now defense-in-depth only.
   The session, pwd, kube, and git segments on this row are wrapped
   in `#[range=user|<id>]` ranges and dispatched through the projmux
-  handler. The git segment shows the current branch or detached commit,
+  handler. The standalone config also wraps the right-side `projmux`
+  badge as the `settings` range; the app config renders a compact
+  `⚙` settings chip after the clock. The git segment shows the current
+  branch or detached commit,
   then compact state indicators when available: `*` for local changes,
   `+N` for staged entries, and `↑N`/`↓N` for ahead/behind counts. Each
   state token gets its own compact foreground color while preserving the
@@ -46,7 +49,7 @@ A single tmux bind handles both lines:
 ```tmux
 bind-key -n MouseDown1Status if-shell -F "#{==:#{mouse_status_range},window}" \
   { select-window -t = } \
-  { run-shell "'<projmux>' statusbar click \"#{mouse_status_range}\" --mouse-window \"#{mouse_window}\"" }
+  { run-shell "'<projmux>' statusbar click \"#{mouse_status_range}\" --client \"#{client_tty}\" --mouse-window \"#{mouse_window}\"" }
 ```
 
 `MouseDown1Status` fires from any line of a multi-line status bar with
@@ -57,10 +60,11 @@ bind-key -n MouseDown1Status if-shell -F "#{==:#{mouse_status_range},window}" \
 | Range id | Row | Click action                              | Keyboard      |
 | -------- | --- | ----------------------------------------- | ------------- |
 | `session` | 0 | `projmux tmux popup-toggle sessionizer-sidebar` | `prefix s s` |
-| `pwd`     | 0 | copy `#{pane_current_path}` to tmux buffer and show a compact `Path copied` popup | `prefix s p`  |
+| `pwd`     | 0 | show a native-framed current-path popup; no clipboard or tmux buffer copy | `prefix s p`  |
 | `kube`    | 0 | `projmux tmux popup-toggle sessionizer`   | `prefix s k`  |
 | `git`     | 0 | `projmux tmux popup-toggle sessionizer`   | `prefix s g`  |
-| `usage`   | 1 | `display-popup -E -h 60% -w 80% -- projmux usage`, then wait for Enter | `prefix s u`  |
+| `settings` | 0 | `projmux tmux popup-toggle --client <tty> ai-split-settings` | mouse only; `prefix s s` remains `session` |
+| `usage`   | 1 | show a native-framed usage HUD popup from cached usage state | `prefix s u`  |
 | `notify`  | 1 | `projmux focus --target <newest> --source status-bar --kind segment-click`, then ack on focus success | `prefix s n`  |
 
 `notify` reads the pending queue only. For a live pane-state view that is
@@ -70,13 +74,23 @@ The notify segment renders the newest queued item as a single notification
 block: project, state (`NEED`/`INFO`/`WARN`/`CRIT`), optional agent, text,
 age, and `+N` for older pending entries. Window/pane ids are not shown in the
 compact status segment.
-`usage` deliberately opens the detailed `projmux usage` table popup; it is the
-clear action surface for the compact HUD bar.
-
-The path popup uses a short title, one-line copy status, the current path, and
-an `Enter closes this popup` prompt. If the tmux buffer write fails, it keeps
-the same compact surface with `Current path` as the title and a copy-unavailable
-message. The notification HUD detail surface (`Alt-2` / `User2`) opens the
+`usage` opens a native-framed detail HUD for the compact usage bar. It reads
+the cached usage state in-process, keeps the existing `projmux usage` CLI
+output shape unchanged for external consumers, aligns model/window rows with
+right-aligned numeric values, dims unavailable values, and colors rows at the
+same alert thresholds as the popup: amber at 80% and red at 95%.
+
+The path popup uses the native picker frame chrome, a one-line title,
+the full wrapped current path, cheap project/git metadata when available, and
+an `Enter closes this popup` prompt. The click is display-only: it does not
+invoke system clipboard tools and does not write a tmux paste buffer. The
+popup command prints one quoted payload and waits for a plain Enter read so it
+does not leave terminal key state behind. The usage popup uses the same
+single-payload print and plain Enter-close pattern. It shows the authoritative
+last collect timestamp when present, falls back to the cache file mtime when
+needed, and colors that sync line amber once it is more than 60 seconds old.
+The notification HUD detail surface
+(`Alt-2` / `User2`) opens the
 right-side notification popup with newest-first rows. The popup itself is
 untitled; when decoration mode is `symbol` or `emoji`, the bell appears before
 the fzf header text instead. Selecting a row still focuses and acknowledges
@@ -100,7 +114,9 @@ bind-key -T projmux-status s run-shell '#{q:projmux} statusbar click session'
 ```
 
 The chord routes through the same dispatcher as the mouse click, so
-keyboard and mouse paths are functionally identical.
+keyboard and mouse paths are functionally identical for keyed ranges.
+There is intentionally no `prefix s s` settings fallback because that chord
+already opens the session/sidebar range.
 
 ## Click failure handling
 
@@ -115,10 +131,11 @@ them as `display-message` toasts:
   <reason>`.
 - `session`, `kube`, or `git` popup launch failure: toast
   `statusbar <range>: popup failed`.
-- `pwd` path popup failure: keep the copied path in the tmux paste
-  buffer when possible and fall back to a short `display-message`.
-- `usage` popup failure: fall back to inlining the rendered table
-  into a single `display-message`.
+- `settings` popup launch failure: toast `statusbar settings: popup failed`.
+- `pwd` path popup failure: fall back to a short `display-message`
+  containing the current path.
+- `usage` popup failure: fall back to a compact usage summary
+  `display-message`.
 
 `MouseX` / `MouseY` are accepted but not consumed today; the fields
 are wired through so click telemetry can land without changing the

package/docs/testing.md

@@ -7,9 +7,8 @@ and humans run the same entrypoints.
 
 - `make test` runs the fast Go unit suite. These tests avoid tmux, TTY, GUI,
   and host shell dependencies.
-- Picker unit coverage includes the backend-neutral item/action contract, fzf
-  adapter mapping, native title-focused filtering, numeric selection, and
-  shared close actions.
+- Picker unit coverage includes the backend-neutral item/action contract,
+  native title-focused filtering, numeric selection, and shared close actions.
 - `make test-integration` builds `test/docker/Dockerfile` and runs
   `test/integration/linux-smoke.sh` in Docker. It validates Linux dependency
   discovery, tmux config generation/install, app config reload against a real
@@ -29,7 +28,7 @@ The Docker suites are intended to cover portable Linux behavior that can be
 made deterministic in a container:
 
 - binary build and source install into an isolated prefix
-- `doctor` dependency checks for `tmux`, `fzf`, `git`, and `stty`
+- `doctor` dependency checks for `tmux`, `git`, and `stty`
 - tmux config print/install/apply paths
 - notify queue push/list/ack/reconcile state transitions
 - focus fallback behavior when a tmux server has sessions but no attached
@@ -37,9 +36,8 @@ made deterministic in a container:
 - status rendering that only depends on tmux state and local files
 
 The test container disables networking during `docker run`. The image build may
-use the network to fetch the pinned base image, apt packages, and pinned fzf
-version, but suite execution should not need network access after the image is
-built.
+use the network to fetch the pinned base image and apt packages, but suite
+execution should not need network access after the image is built.
 
 ## Host-Only Checks