projmux 0.5.3 → 0.6.1

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,72 @@
+# 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 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 old statusbar Session State shortcut has
+been removed; use `Projects > Sessions > State` or the `projmux session-state`
+CLI for inspection/actions.
+
+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,66 @@
+# Settings Information Architecture
+
+This branch finishes the current Settings/onboarding roadmap slice with a
+view-first layout:
+
+- Every Settings surface keeps the Global/Project tab strip visible so nested
+  pages still show their scope. Detail pages may render the strip as passive
+  context when changing tabs from that nested page would skip an explicit Back
+  boundary.
+- Settings uses a view-first rule: overview rows open details; details show the
+  current state, source, and expected rendered result before offering mutation
+  rows. If a detail opens a dedicated `Change` page, that page is mutation-only
+  and does not repeat the same read-only view rows.
+- `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.
+- `Settings > Appearance` is view-first. The root opens `Path icon`, `Git icon`,
+  and `Notify icon` details. Each detail shows the current mode and off/symbol/
+  emoji rendered previews first, and its `Change` page contains only the
+  off/symbol/emoji mutation choices.
+
+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

@@ -8,13 +8,17 @@ segment only requires one wiring point.
 ## Layout
 
 ```
-row 0  [#S] #{pane_current_path}  ⎈ <ctx>/<ns>  <git>               %H:%M
+row 0  #[range=user|notify] <notify HUD pill> #[norange]
+                                      #[range=user|usage] <usage HUD bar> #[norange]
+row 1  [#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]
-                                           #[range=user|usage] <usage HUD bar> #[norange]
 ```
 
-- Row 0 keeps tmux's native `window-status-format` so clicking a tab
+- Row 0 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 explicit-ack pending queue; live pane attention
+  badges are a separate state surface.
+- Row 1 keeps tmux's native `window-status-format` so clicking a tab
   selects the window. The bind uses `if-shell -F
   "#{==:#{mouse_status_range},window}"` to run `select-window -t =`
   natively when the click lands on the window list, so the
@@ -29,18 +33,15 @@ row 1  #[range=user|notify] <notify HUD pill> #[norange]
   in `#[range=user|<id>]` ranges and dispatched through the projmux
   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
+  `` 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
-  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
-  explicit-ack pending queue; live pane attention badges are a separate
-  state surface. Both
-  segments degrade gracefully when the cell budget is tight; see
+  existing branch block background. Window tab indexes stay left of each tab,
+  and tab titles are centered in a fixed-width trim so long active pane names
+  do not resize the status row.
+- Both HUD segments degrade gracefully when the cell budget is tight; see
   [notify-queue.md](notify-queue.md) and [usage-tracking.md](usage-tracking.md)
   for the per-segment tier ladder.
 
@@ -65,7 +66,7 @@ bind-key -n MouseDown1Status if-shell -F "#{==:#{mouse_status_range},window}" \
 | `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` |
 | `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,9 @@ 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%.
+Session State inspection lives under `Projects > Sessions > State`; global
+Settings > Session State is settings-only and the statusbar no longer exposes a
+duplicate State button.
 
 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
@@ -89,12 +93,10 @@ 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
-that notification.
+The notification HUD detail surface (`Alt-2` / `User2`) opens the right-side
+notification popup with newest-first rows and an amber title. When notification
+icon decoration is `symbol` or `emoji`, the bell appears before the title text.
+Selecting a row still focuses and acknowledges that notification.
 
 Empty `#{mouse_status_range}` (a click on whitespace) falls through to
 `select-window -t @<mouse_window>` when `--mouse-window` is non-empty,
@@ -126,7 +128,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
@@ -151,12 +153,16 @@ emits a deterministic block per segment), regenerate, and re-apply:
 projmux tmux apply
 ```
 
-Settings > Appearance controls the optional decoration mode used by
-the path, git branch, and notification sidebar header. The persisted enum lives at
-`~/.config/projmux/statusbar-decoration`; valid values are `off` (default,
-font-safe), `symbol` (Nerd Font-style folder/GitHub/bell icons), and `emoji`.
-Settings also updates tmux `@projmux_statusbar_decoration` for the live
-server when run inside tmux.
+Settings > Appearance controls optional icon decoration separately for the
+path/cwd marker, git branch marker, and notification sidebar header. Each row
+can be `off` (default, font-safe), `symbol` (Nerd Font-style folder,
+git-provider, or bell icon), or `emoji`. Git branch decoration follows
+`remote.origin.url`: GitHub remotes use a cat-style mark, GitLab remotes use a
+fox-style mark, and other remotes use a generic git branch mark. Settings also
+updates the matching live tmux option
+(`@projmux_statusbar_decoration_cwd`, `_git`, or `_notify`) when run inside
+tmux. The legacy `~/.config/projmux/statusbar-decoration` and
+`@projmux_statusbar_decoration` remain fallback defaults for older configs.
 
 To add a new clickable segment:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projmux",
-  "version": "0.5.3",
+  "version": "0.6.1",
   "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.3",
-    "@projmux/darwin-x64": "0.5.3",
-    "@projmux/linux-arm64": "0.5.3",
-    "@projmux/linux-x64": "0.5.3"
+    "@projmux/darwin-arm64": "0.6.1",
+    "@projmux/darwin-x64": "0.6.1",
+    "@projmux/linux-arm64": "0.6.1",
+    "@projmux/linux-x64": "0.6.1"
   },
   "scripts": {
     "package:npm": "scripts/package-npm.sh",