projmux 0.5.2 → 0.6.0

package/docs/keybindings.md

@@ -8,10 +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, 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.
+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
@@ -20,23 +20,20 @@ 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.
+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` 으로 어떤 키가 막혔는지 진단하고,
@@ -71,15 +68,6 @@ These open the projmux popups and the sidebar. No prefix needed.
 | `Alt-5` | Settings |
 | `Alt-6` | Project switcher popup |
 
-The same surfaces are also available from the prefix table:
-
-| Shortcut | Action |
-| --- | --- |
-| `Prefix F` | Project sidebar |
-| `Prefix b` | Existing session popup |
-| `Prefix f` | Project switcher popup |
-| `Prefix g` | Jump to the current pane's project session |
-
 ### Windows, panes, AI splits
 
 | Shortcut | Action |
@@ -88,9 +76,6 @@ The same surfaces are also available from the prefix table:
 | `Alt-Shift-Left` / `Alt-Shift-Right` | Previous / next window |
 | `Alt-Left` / `Right` / `Up` / `Down` | Move focus between panes |
 | `Alt-r` | Rename the current window |
-| `Prefix R` | Rename the current window |
-| `Prefix r` | Open an AI split to the right |
-| `Prefix l` | Open an AI split below |
 
 When a pane closes, projmux re-spreads remaining panes so the surviving split
 does not stretch lopsided.
@@ -125,8 +110,8 @@ 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
+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.
 
 | Status | Meaning |
@@ -140,10 +125,8 @@ 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 > 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.
+exact apply command, e.g. `projmux init ghostty --apply`. Settings >
+Keybindings shows the same delivery categories after a capture.
 
 Useful flags:
 

package/docs/notify-os-focus-poc.md

@@ -72,14 +72,14 @@ a different command worked better.
 |---|---|---|---|---|
 | Ghostty | macOS | `osascript -e 'tell application "Ghostty" to activate'` + window-id match | | [ ] |
 | Ghostty | Linux X11 | `wmctrl -ia <wid>` | | [ ] |
-| Ghostty | Linux Wayland | Compositor-specific: gnome `dbus` (`org.gnome.Shell.Eval`), KDE `kdotool`, sway `swaymsg` | | [ ] |
-| Kitty | Any | `kitty @ focus-window --match <expr>` | | [ ] |
-| WezTerm | Any | `wezterm cli activate-pane --pane-id <id>` | | [ ] |
+| Ghostty | Linux Wayland | Compositor-specific: gnome `dbus` (`org.gnome.Shell.Eval`), KDE `kdotool`, sway `swaymsg` | No — Ubuntu GNOME 50 Wayland with Ghostty 1.3.1 exposes `GHOSTTY_*` detection signals, but Ghostty has no raise/focus CLI action and GNOME Shell `Eval` returns `(false, '')` outside unsafe mode. | [x] |
+| Kitty | Any | `kitty @ focus-window --match <expr>` | Partial — Ubuntu GNOME Wayland default kitty 0.45.0 attach exposes `KITTY_WINDOW_ID`/`KITTY_PID`, but no `KITTY_LISTEN_ON`; external `kitty @ ls` fails without a controlling TTY unless kitty is launched with a remote-control socket. | [x] |
+| WezTerm | Any | `wezterm cli activate-pane --pane-id <id>` | Partial — WezTerm 20240203 crashes on native GNOME 50 Wayland in this host, but the X11 fallback (`WAYLAND_DISPLAY` unset) attaches and `wezterm cli activate-pane --pane-id 0` succeeds. | [x] |
 | Windows Terminal | Windows | `wt -w <id> focus-tab -t <n>` (same instance only) | | [ ] |
 | Windows Terminal | WSL → Windows | WSL interop + `wt.exe -w <id> focus-tab` | OK — `wt.exe -w 0 focus-tab -t 0` raises the WT window (verified WSL2 Ubuntu-24.04, WT host) | [x] |
 | iTerm2 | macOS | AppleScript (`tell application "iTerm" ...`) or Python API | | [ ] |
-| Alacritty | Any | No remote IPC. OS-window focus only — fall back to the table below. | | [ ] |
-| Foot | Linux | `footclient` is limited. OS-window focus only — fall back to the table below. | | [ ] |
+| Alacritty | Any | No remote IPC. OS-window focus only — fall back to the table below. | No — Alacritty 0.16.1 IPC socket is reachable and can create windows/read config, but exposes no existing-window focus or raise command. | [x] |
+| Foot | Linux | `footclient` is limited. OS-window focus only — fall back to the table below. | No — foot 1.25.0 server/footclient can create a new terminal window, but exposes no existing-window focus or raise command. | [x] |
 | VS Code embedded | Any | Best-effort via `vscode://` URL handler or `code --command` | | [ ] |
 
 ## OS-level window activation matrix
@@ -91,7 +91,7 @@ Independent of the terminal: "raise this app to the foreground." Fill the
 |---|---|---|---|---|
 | macOS | `osascript -e 'tell application "<AppName>" to activate'` | Stable; no special permission. | | [ ] |
 | Linux X11 | `wmctrl -a <window-name>` or `xdotool windowactivate <wid>` | Requires `wmctrl` / `xdotool` installed; standard. | | [ ] |
-| Linux Wayland (GNOME) | `gdbus call --session --dest org.gnome.Shell --object-path /org/gnome/Shell --method org.gnome.Shell.Eval ...` | Depends on shell version; recent GNOME locks `Eval` outside dev mode. | | [ ] |
+| Linux Wayland (GNOME) | `gdbus call --session --dest org.gnome.Shell --object-path /org/gnome/Shell --method org.gnome.Shell.Eval ...` | Depends on shell version; recent GNOME locks `Eval` outside dev mode. | No — GNOME Shell 50 returns `(false, '')` for `Eval`; X11 fallbacks also do not see native Wayland Ghostty windows (`wmctrl -lx` empty, `xdotool` cannot resolve title/pid). | [x] |
 | Linux Wayland (KDE) | `kdotool windowactivate <wid>` | KWin script bridge; requires `kdotool`. | | [ ] |
 | Linux Wayland (sway) | `swaymsg '[con_id=<id>] focus'` | Works for sway / wlroots compositors. | | [ ] |
 | Windows | `SetForegroundWindow` via PowerShell + P/Invoke | Foreground-lock policy: if the target hasn't recently been active, the OS will only flash the taskbar entry. | | [ ] |
@@ -155,6 +155,84 @@ Notes from Test 3 (`wt.exe -w 0` bare, no subcommand):
   (Test 1) to raise without creating a tab. Treat the bare form as
   reserved for the "open new tab" case only.
 
+Notes from Test 4 (Ubuntu GNOME Wayland + Ghostty):
+
+- Environment: Ubuntu GNOME Wayland (`XDG_SESSION_TYPE=wayland`,
+  `XDG_CURRENT_DESKTOP=ubuntu:GNOME`, `WAYLAND_DISPLAY=wayland-0`) with
+  Ghostty 1.3.1 (`GHOSTTY_RESOURCES_DIR`, `GHOSTTY_BIN_DIR` set). Inside tmux,
+  `TERM_PROGRAM=tmux`, so Ghostty detection must use the `GHOSTTY_*` signals.
+- Ghostty 1.3.1 exposes helper actions such as `+new-window`,
+  `+show-config`, and `+list-actions`, but no CLI action that raises an
+  existing window, focuses a tab, or activates a split. Treat Ghostty on
+  native Linux Wayland as OS-window-focus-only unless a future Ghostty IPC
+  surface lands.
+- GNOME Shell `Eval` is not usable as a default adapter path on GNOME 50:
+  `gdbus call --session --dest org.gnome.Shell --object-path /org/gnome/Shell
+  --method org.gnome.Shell.Eval 'global.display.focus_window ?
+  global.display.focus_window.get_title() : ""'` returned `(false, '')`.
+- X11 fallbacks are insufficient for native Wayland windows in this
+  configuration: `wmctrl -lx` returned an empty list, and `xdotool
+  getactivewindow getwindowname getwindowpid` could only see an Xwayland
+  window id with no associated pid/title.
+
+Notes from Test 5 (Ubuntu GNOME Wayland + kitty default attach):
+
+- Environment: Ubuntu GNOME Wayland with kitty 0.45.0 attached to the projmux
+  tmux server (`client_termname=xterm-kitty`).
+- The tmux client process inherited `KITTY_WINDOW_ID=1`, `KITTY_PID=<pid>`,
+  `TERM=xterm-kitty`, and `COLORTERM=truecolor`, but not `KITTY_LISTEN_ON`.
+- From a non-interactive external process, `kitty @ ls` failed with
+  `open /dev/tty: no such device or address`. That confirms the default
+  no-socket launch cannot be driven by an osfocus adapter running outside the
+  kitty window.
+- The candidate command remains viable only when kitty is launched with a
+  remote-control surface (`--listen-on ...` or `listen_on` plus
+  `allow_remote_control`) and the adapter can discover that address.
+
+Notes from Test 6 (Ubuntu GNOME Wayland + kitty socket attach):
+
+- Launching kitty with `--listen-on unix:/tmp/projmux-kitty.sock --override
+  allow_remote_control=yes` passed `KITTY_LISTEN_ON` through to the tmux client
+  and allowed an external process to run `kitty @ --to
+  unix:/tmp/projmux-kitty.sock ls`.
+- `kitty @ --to unix:/tmp/projmux-kitty.sock focus-window --match id:1`
+  exited successfully. The adapter path is viable when the launch/config
+  exposes a discoverable remote-control socket.
+
+Notes from Test 7 (Ubuntu GNOME Wayland + WezTerm):
+
+- Native Wayland launch failed on GNOME 50 with `wl_surface ... Buffer size
+  ... must be an integer multiple of the buffer_scale (2)`.
+- X11 fallback launch (`WAYLAND_DISPLAY` unset) attached to tmux successfully
+  (`client_termname=xterm-256color`).
+- `wezterm cli list` failed while `WAYLAND_DISPLAY` pointed at the stale
+  Wayland socket, but `env -u WAYLAND_DISPLAY wezterm cli list` found the X11
+  GUI socket and reported `PANEID 0`.
+- `env -u WAYLAND_DISPLAY wezterm cli activate-pane --pane-id 0` exited
+  successfully. A WezTerm adapter on GNOME Wayland must avoid stale Wayland
+  socket selection when the GUI is actually running on X11.
+
+Notes from Test 8 (Ubuntu GNOME Wayland + Alacritty):
+
+- Alacritty 0.16.1 daemon mode created an IPC socket at
+  `/run/user/1000/Alacritty-wayland-0-<pid>.sock`; `alacritty msg --socket
+  ... create-window -e tmux -L projmux attach -t repos-projmux` attached a new
+  tmux client (`client_termname=alacritty`).
+- `alacritty msg --socket ... get-config` succeeded, confirming that the
+  socket is externally reachable.
+- `alacritty msg` exposes `create-window`, `config`, and `get-config`; it does
+  not expose an existing-window focus/raise command. Treat Alacritty as
+  OS-window-focus-only for this roadmap item.
+
+Notes from Test 9 (Ubuntu GNOME Wayland + foot):
+
+- Starting `foot-server.socket` and then running `footclient -N ... tmux -L
+  projmux attach -t repos-projmux` attached a new tmux client
+  (`client_termname=foot`).
+- The footclient surface is useful for creating terminals against the server,
+  but does not provide an IPC command to focus or raise an existing window.
+  Treat foot as OS-window-focus-only.
+
 If multiple signals are present (e.g. tmux inside VS Code's embedded
 terminal), the adapter chain picks the innermost match the IPC can actually
 talk to and falls through to the next on detect failure.

package/docs/notify-queue.md

@@ -34,6 +34,7 @@ type Notification struct {
     Text      string    // capped at 80 runes
     Severity  string    // info | warn | critical
     Source    string    // ai | k8s | git | external
+    Metadata  map[string]string // optional producer metadata
     CreatedAt time.Time
     ExpiresAt time.Time
     Target            // session, window, pane, socket
@@ -53,6 +54,16 @@ freshness/display field, not a removal condition. `Severity` and
 returns `ErrInvalidSeverity` / `ErrInvalidSource` which the CLI maps to
 exit code 2.
 
+`Metadata` is optional and is omitted when empty. Hook producers use it for
+routing/debug context such as `agent`, `thread_id`, `turn_id`, `cwd`,
+`model`, and `client`; Claude hook rows also carry event-specific keys such as
+`tool_name`, `tool_input.command`, `error_type`, `subagent_type`, and
+`teammate_name`. Tmux bell fallback rows carry `agent=bell`, `event=bell`,
+and tmux target context such as pane title, command, session, window, pane, and
+socket. `notify list --json` includes this metadata as the structured data
+channel while human table/sidebar output keeps the compact text body. Existing
+entries without metadata remain valid.
+
 ## CLI surface
 
 ### push
@@ -72,7 +83,7 @@ number of seconds. `--json` prints `{id, queued}` for scripting.
 ### list
 
 ```
-projmux notify list [--live] [--json] [--limit N] [--ui table|sidebar]
+projmux notify list [--live] [--json] [--limit N] [--ui table|sidebar] [--client <tty>]
                     [--severity ...] [--source ...]
 ```
 
@@ -87,7 +98,7 @@ acks the row after focus succeeds. `x` acks the selected row. `Ctrl-X` clears
 all rows via `notify ack --all`. 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.
+input and intentionally does not expose a separate metadata detail view.
 
 `--live` adds a non-mutating explanation view that reads
 `tmux list-panes -a` and compares the queue with live reply-state panes. It
@@ -170,21 +181,42 @@ Manual `projmux attention toggle` on a pane without an agent option
 does NOT push — the queue is intentionally AI-driven; reconcile honours
 the same contract.
 
+## Producer (tmux bell fallback)
+
+`projmux ai ingest bell --pane <pane_id>` is the opt-in fallback producer
+installed by `projmux ai integrate tmux-bell`. It reads the target pane from
+tmux and writes an info/source-ai row with:
+
+- id: `ai:bell:<session>:<pane>`
+- text: `bell · <pane title>` with command/window fallback context
+- metadata: `agent=bell`, `event=bell`, pane/session/window/socket fields
+- freshness TTL: 10 minutes
+
+Unlike reply-ready reconcile, bell ingest does not require AI pane metadata.
+It is intentionally available for arbitrary CLIs that only signal attention
+through BEL or OSC 9. Repeated bells from the same pane are suppressed for 5
+seconds before a later bell refreshes the stable queue id.
+
 ## Consumer (status-bar click)
 
 `internal/app/statusbar.go::handleNotify`. A click on the notify range
 or the `prefix s n` chord reads the newest queue entry and dispatches:
 
 ```
-projmux focus --target <target> --source status-bar --kind segment-click [--socket <s>]
+projmux focus --target <target> --source status-bar --kind segment-click [--socket <s>] [--client <tty>]
 ```
 
+The status bar passes the clicked tmux client as `--client` when tmux provides
+it. The notify sidebar does the same for row selection. If that origin client
+is no longer attached, `projmux focus` falls back to the existing target-session
+client selection policy.
+
 Outcomes:
 
 - **Focus succeeded** — ack the entry. Focus is the single consume path for
   routed notification clicks.
-- **Focus exited 2 (target unresolved)** — keep the entry pending and toast
-  `notify target gone; ack to clear`.
+- **Focus exited 2 (target unresolved)** — ack the entry and toast
+  `notify target gone; cleared`.
 - **Other failure** — keep the entry, toast `focus failed: <reason>`
   so the user can retry without losing the row.
 

package/docs/session-restore.md

@@ -0,0 +1,78 @@
+# Session Restore
+
+Session snapshots store tmux layout metadata and replay recipes for shell,
+startup, and supported agent panes. Manual CLI actions remain available through:
+
+```sh
+projmux session-state status [--session <name>]
+projmux session-state save
+projmux session-state preview [--session <name>]
+projmux session-state restore --dry-run [--session <name>]
+projmux session-state delete [--session <name>]
+```
+
+The primary inspection surface is `Projects > Sessions > State`. It shows a
+read-only overview first: latest snapshot status, named snapshots, window ->
+pane structure, cwd, recipe, and agent resume health. Mutation belongs one
+level deeper in explicit actions; the overview does not immediately save,
+delete, preview, or restore.
+
+Project Session State actions are scoped to the project-derived session
+identity, not the currently attached tmux session. `Save latest snapshot`
+captures the live project session when that session exists. `Save named
+snapshot` captures the same live project session into a project-local named
+snapshot and stores cwd values with portable project-root placeholders. Closed
+project sessions disable save actions with the live-session reason. `Preview
+restore` prints the read-only dry-run restore plan for the project snapshot, and
+`Delete snapshot` requires a confirmation picker before removing the project
+snapshot. Destructive restore execution remains outside Settings in this slice.
+
+Agent panes in Settings, the statusbar popup, and restore dry-run previews show
+resume metadata health next to the pane recipe. `available` means a resume id is
+present and recent enough for replay, `stale` means the stored id exists but the
+metadata is missing or older than the snapshot policy, and `unavailable`
+means projmux cannot safely resume that agent pane from the snapshot. Confidence
+is derived from the metadata source: direct session ids and hook ingest are high
+confidence, transcript/log fallbacks are medium confidence, and missing or
+unknown sources are low or none.
+
+The statusbar Session State popup remains a secondary shortcut backed by the
+same read model and CLI behavior:
+
+- `Save snapshot` captures the current tmux session, bypassing the autosave debounce
+  just like `projmux session-state save`.
+- `Preview restore` prints the dry-run restore plan and does not execute tmux
+  replay commands.
+
+Settings > Session State is global settings only: global auto-save, auto-save
+interval, and storage/retention policy. It does not show the current
+snapshot tree. Delete for current-session snapshots and destructive restore
+execution stay deferred until those actions have a dedicated safe policy for
+existing or non-empty live sessions.
+
+Named snapshots may currently be backed by legacy project files in
+`<project>/.projmux/layouts/*.toml`. They reuse the same window, pane, cwd, and
+startup recipe concepts as session snapshots, but the user-facing restore model
+is still `Latest snapshot`, `Named snapshot`, or `Empty session`. The legacy
+files are imported read-only by Project open
+when building `Named snapshot` candidates; new primary surfaces should describe
+the restore unit as a snapshot, not as a separate layout or preset feature.
+
+Project open from the Alt-1 sidebar defaults to opening a closed project as an
+`Empty session`. `Settings > Labs > Sidebar startup picker` is an opt-in toggle;
+when it is on, closed project open advances inside the sidebar to the native
+`Start project` step. Rows are ordered `Latest snapshot`, named snapshot rows,
+`Empty session`, then `Back`. `Latest snapshot` is the auto-saved snapshot that
+keeps changing as auto-save runs. `Named snapshot` is a fixed, user-named
+snapshot and is not updated by auto-save. Rows include saved-at date/time
+metadata when available. `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 before session create, snapshot replay, or startup
+command. Existing sessions switch directly without a startup picker.
+
+Default `projmux shell` no longer opens a compatibility startup picker and no
+longer accepts startup selector flags for session-state restore. It always
+follows the normal empty attach path after resolving the target app session name
+and startup directory. Use `Settings > Labs > Sidebar startup picker` for
+interactive Latest snapshot / Named snapshot / Empty session selection.

package/docs/settings-ia.md

@@ -0,0 +1,54 @@
+# Settings Information Architecture
+
+This branch finishes the current Settings/onboarding roadmap slice with a
+view-first layout:
+
+- `Settings > Project Picker > Workdirs` is the list/overview entry. Add/remove
+  actions live inside that view.
+- `Settings > Project Picker > Project Root` shows effective and saved values
+  first, then the edit actions, then the explanatory hints.
+- `Settings > Keybindings` is the single entry point for keybinding work. The
+  page is split into four chips: `Bindings`, `Diagnostic`, `Probe`, and `Init`.
+- `Settings > Notifications` owns notification delivery IA. Desktop notification
+  mode, delivery source diagnostics, in-app queue status, and
+  `PROJMUX_NOTIFY_HOOK` visibility live together without mixing mutation
+  boundaries.
+- `Settings > Notifications > Desktop notifications` owns the desktop
+  notification mode. The detail choices are `none`, `notify`, and `raise`.
+- `Settings > Notifications > Delivery sources` shows Codex hooks, Claude, and
+  tmux producer diagnostics plus copyable install/remove/dry-run commands.
+  Settings copies command text only; it does not install or remove external
+  notify wiring. The legacy Codex notify source is intentionally omitted from
+  Settings.
+- `Settings > Labs` keeps experimental toggles, but keybindings no longer have a
+  visible Labs row. The hidden compatibility action still redirects to the
+  unified Keybindings page.
+- `Settings > Labs > Project Hooks` is overview-first. The Labs root opens the
+  overview, and the on/off mutation rows live one level deeper.
+- `Settings > AI Settings` is view-first. The root contains `Default split
+  mode`; the detail contains the `Claude`, `Codex`, and `Shell` choices.
+- `Settings > Project > Project recipe` is the functional label for
+  `.projmux/config.toml`. Search still matches `config.toml` as an alias.
+- `Settings > Project > Project recipe` is view-first. The root contains section
+  rows such as `Startup command`, `Kube`, and `Environment`; mutation actions
+  such as `Set startup command...`, `Clear startup command`, kube edits, and env
+  add/remove rows live inside those details.
+
+Hooks remain the reference pattern for this IA:
+
+- project-scoped rows stay editable in-app
+- global/system rows are read-only in-app
+- project overrides are created intentionally from the project surface or
+  `projmux hook edit <event> --project`
+- `Settings > Project > Hooks` lists hook events only. It does not nest the
+  Project recipe row; Project recipe belongs under the Project tab.
+- The Settings hook event list includes `send-noti` for both global and project
+  hook views.
+
+Shell bootstrap UX is phase-split:
+
+- Phase 1 is complete in this branch: `projmux welcome`, the About-screen
+  Welcome entry, and `pending_attach_welcome` state make the guide revisit-able.
+- Phase 2 is complete in this branch: the generated projmux shell tmux config
+  runs the low-noise `projmux welcome --popup` attach hook, which claims the
+  pending marker once and displays the welcome guide after attach.

package/docs/statusbar.md

@@ -10,7 +10,7 @@ segment only requires one wiring point.
 ```
 row 0  [#S] #{pane_current_path}  ⎈ <ctx>/<ns>  <git>               %H:%M
        └────────── native tmux window list (one entry per window) ──────────┘
-row 1  #[range=user|notify] <notify HUD pill> #[norange]
+row 1  #[range=user|notify] <notify HUD pill> #[norange] #[range=user|sessionstate]state#[norange]
                                            #[range=user|usage] <usage HUD bar> #[norange]
 ```
 
@@ -37,7 +37,7 @@ row 1  #[range=user|notify] <notify HUD pill> #[norange]
   existing branch block background.
 - Row 1 splits the line with `#[align=left]` (the pending AI notify
   queue, capped at 80
-  cells) and `#[align=right]` (usage, capped at 120 cells). `notify` is the
+  cells, plus the compact `state` entrypoint) and `#[align=right]` (usage, capped at 120 cells). `notify` is the
   explicit-ack pending queue; live pane attention badges are a separate
   state surface. Both
   segments degrade gracefully when the cell budget is tight; see
@@ -64,8 +64,9 @@ bind-key -n MouseDown1Status if-shell -F "#{==:#{mouse_status_range},window}" \
 | `kube`    | 0 | `projmux tmux popup-toggle sessionizer`   | `prefix s k`  |
 | `git`     | 0 | `projmux tmux popup-toggle sessionizer`   | `prefix s g`  |
 | `settings` | 0 | `projmux tmux popup-toggle --client <tty> ai-split-settings` | mouse only; `prefix s s` remains `session` |
+| `sessionstate` | 1 | show a secondary Session State snapshot status and restore preview popup; primary inspection lives under Projects > Sessions > State | `prefix s r` |
 | `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`  | 1 | `projmux focus --target <newest> --source status-bar --kind segment-click [--client <tty>]`, then ack on focus success | `prefix s n`  |
 
 `notify` reads the pending queue only. For a live pane-state view that is
 independent of queued reminders, use `projmux attention list`. To explain why
@@ -79,6 +80,11 @@ 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%.
+`sessionstate` opens a secondary Session State popup for the current tmux
+session. Its action label is `Save snapshot`, which captures the current tmux
+session as the latest snapshot and bypasses the autosave debounce. Primary
+state inspection lives under `Projects > Sessions > State`; global Settings >
+Session State is settings-only.
 
 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
@@ -110,6 +116,7 @@ bind-key -T projmux-status n run-shell '#{q:projmux} statusbar click notify'
 bind-key -T projmux-status g run-shell '#{q:projmux} statusbar click git'
 bind-key -T projmux-status k run-shell '#{q:projmux} statusbar click kube'
 bind-key -T projmux-status p run-shell '#{q:projmux} statusbar click pwd'
+bind-key -T projmux-status r run-shell '#{q:projmux} statusbar click sessionstate'
 bind-key -T projmux-status s run-shell '#{q:projmux} statusbar click session'
 ```
 
@@ -126,7 +133,7 @@ click. Each handler therefore swallows runtime failures and surfaces
 them as `display-message` toasts:
 
 - `notify` click whose focus dispatch exits 2 (target unresolved):
-  keep the entry pending, toast `notify target gone; ack to clear`.
+  ack the entry, toast `notify target gone; cleared`.
 - Any other focus failure: keep the entry, toast `focus failed:
   <reason>`.
 - `session`, `kube`, or `git` popup launch failure: toast
@@ -134,6 +141,8 @@ them as `display-message` toasts:
 - `settings` popup launch failure: toast `statusbar settings: popup failed`.
 - `pwd` path popup failure: fall back to a short `display-message`
   containing the current path.
+- `sessionstate` popup failure: fall back to a compact snapshot status
+  `display-message`.
 - `usage` popup failure: fall back to a compact usage summary
   `display-message`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projmux",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "tmux project session manager",
   "license": "MIT",
   "homepage": "https://github.com/crevissepartners/projmux#readme",
@@ -24,10 +24,10 @@
     "LICENSE"
   ],
   "optionalDependencies": {
-    "@projmux/darwin-arm64": "0.5.2",
-    "@projmux/darwin-x64": "0.5.2",
-    "@projmux/linux-arm64": "0.5.2",
-    "@projmux/linux-x64": "0.5.2"
+    "@projmux/darwin-arm64": "0.6.0",
+    "@projmux/darwin-x64": "0.6.0",
+    "@projmux/linux-arm64": "0.6.0",
+    "@projmux/linux-x64": "0.6.0"
   },
   "scripts": {
     "package:npm": "scripts/package-npm.sh",

package/docs/roadmap.md

@@ -1,109 +0,0 @@
-# Roadmap
-
-## Done (0.4.x)
-
-The 0.4 line filled in the operational surface around the session-management
-core that 0.3 had landed.
-
-### Setup and install
-
-- `projmux setup` — TTY raw-mode probe that reports which projmux key
-  sequences (`Alt-1..5`, `Ctrl-N`, `Ctrl-Shift-{R,L,M}`, `Ctrl-M`,
-  `Alt-Shift-{Left,Right}`) reach the process and which the terminal
-  swallows.
-- `projmux init [terminal]` — auto-merges projmux's CSI-u + chord
-  bindings into a terminal config. Adapters: Ghostty (with the
-  `config` / `config.ghostty` candidate split and symlink guard) and
-  Windows Terminal (WSL + native).
-
-### Diagnostics
-
-- `projmux doctor` — runtime dependency report. Enforces minimum tmux
-  3.4 and checks workflow dependencies such as `git` and `stty`.
-
-### Focus
-
-- `projmux focus` — unified switch-client dispatch. Resolves a target
-  session against the live tmux inventory, redirects an existing client
-  if one is attached, otherwise emits a desktop notification. Used by
-  the status-bar notify click and by the AI reply-ready handler.
-
-### Notify queue
-
-- `projmux notify push|list|ack` — persistent JSON-backed queue at
-  `<state>/projmux/notify.json` with TTL, severity, source, and target
-  metadata.
-- `projmux notify reconcile` — back-fills the queue from live pane
-  state by walking `tmux list-panes -a`.
-- Producer wired to the attention state machine: a pane transitioning
-  to `reply` with an AI agent option set pushes an `ai:<session>:<pane>`
-  entry; the matching `clear` acks it.
-
-### Usage tracking
-
-- `projmux usage` (and `status usage`) — authoritative 5h + weekly
-  utilisation for both Claude (OAuth `api/oauth/usage` endpoint with
-  401 token refresh) and Codex (latest rollout `rate_limits` JSONL).
-- Per-adapter throttle (Claude `5m`, default `30s`), 429 backoff
-  (`30m`–`60m` exponential), `--force` to bypass both. Snapshots
-  preserved on failure so a 429 does not erase prior rows.
-
-### Statusbar and HUD
-
-- Two-line clickable status bar: row 0 is the existing
-  session/window/path/git/kube row, row 1 splits notify (left) and
-  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`.
-- `pwd` status click copies the current pane path into the tmux paste
-  buffer and shows a compact path popup instead of a transient
-  warning-coloured toast.
-- HUD-style notify segment with severity+agent badge, midpoint dot
-  separators, and an age field.
-- HUD-style usage segment with bars, last-sync age indicator (Claude),
-  and graceful degradation through six tiers as `--max-width` shrinks.
-
-## Next (0.5+)
-
-Carried forward from earlier milestones — items still outstanding when
-v0.4 shipped.
-
-### Picker UI
-
-- 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 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 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
-
-- Initial Docker-backed Linux smoke suites are available through
-  `make test-integration`, `make test-install-smoke`, and `make test-e2e`.
-  They cover install/runtime substrate checks against real `tmux`; host-only
-  terminal, WSL, macOS, and GUI checks remain separate in
-  [docs/testing.md](testing.md).