projmux 0.5.2 → 0.6.0

package/docs/configuration.md

@@ -38,20 +38,65 @@ The saved workdir file is:
 It stores one absolute path per line. Lines beginning with `#` are comments.
 The file is read only when no env root list is set.
 
+## Project Named Snapshots
+
+Project open exposes reusable restore choices as named snapshots. Older
+checkouts may already have named snapshots in the legacy storage directory:
+
+```text
+<project>/.projmux/layouts/<name>.toml
+```
+
+The project context comes from `PROJMUX_CWD` when set, otherwise projmux walks
+upward from the current directory to the nearest `.projmux` or `.git` marker.
+Files outside that project tree are not discovered. This storage is treated as
+legacy import data for the `Named snapshot` row in Project open. New primary
+user-facing surfaces describe the restore unit as a snapshot, not as a separate
+layout or preset feature.
+
+The legacy schema is intentionally close to the session-state snapshot shape:
+
+```toml
+schema_version = 1
+description = "Daily dev"
+mode = "inherit-autosave" # default; or "fresh-each-time"
+default_cwd = "${PROJMUX_CWD}"
+
+[[windows]]
+index = 0
+name = "main"
+layout = "..."
+active_pane_index = 0
+
+[[windows.panes]]
+index = 0
+cwd = "${PROJMUX_CWD}"
+command = "make watch"
+```
+
+`command` records a startup recipe, matching the supported session-state replay
+recipe. Panes without `command` may use `recipe = "shell"`. Supported
+interpolation placeholders are limited to `${PROJMUX_CWD}` and
+`${PROJMUX_SESSION}`; other `${...}` values are rejected during load.
+
+Unknown fields and unknown sections are ignored so future schema additions do
+not break older files. The built-in parser only accepts quoted strings and
+integer values for the known fields above; it does not implement the full TOML
+language.
+
 ## Keymap File
 
-Settings > Keybindings is the normal in-app editor for tmux key chords. It
-lists each action, opens a detail screen, and lets you type `plain` or
-`prefix` tmux chord strings. Saving writes `~/.config/projmux/keymap.toml`,
+Settings > Keybindings is the normal in-app editor for action keys. It lists
+each action, opens a detail screen, and uses `Press new key` to capture one
+keypress through the same controlling-TTY probe path as `projmux setup`.
+Saving writes safe tmux plain chords to `~/.config/projmux/keymap.toml`,
 rewrites `~/.config/projmux/tmux.conf`, and, when Settings is running inside
-tmux, sources that app config so non-terminal-layer tmux chords take effect
-immediately.
+tmux, sources that app config so tmux-level chords take effect immediately.
 
-Settings > Labs > Diagnose keybindings is the in-app diagnostic/remediation
-surface for the same catalog. It probes one action key at a time through the
-controlling TTY, reports whether the key arrived as a plain tmux chord, CSI-u
-fallback, unexpected sequence, or timeout, and delegates supported terminal
-fallback preview/apply operations to the `projmux init` engine.
+Settings reports CSI-u/User-key captures as terminal fallback delivery and
+does not write a keymap entry for them. Raw sequences that cannot be safely
+represented as a tmux plain chord are not persisted; configure terminal
+fallback with `projmux init` instead.
 
 `~/.config/projmux/keymap.toml` can also be edited by hand. When the file is
 absent, generated tmux config stays on the built-in defaults.
@@ -61,7 +106,6 @@ Supported schema:
 ```toml
 [bindings.sessionizer-sidebar]
 plain = "M-a"
-prefix = "A"
 
 [bindings.new-window]
 plain = "C-t"
@@ -72,7 +116,10 @@ Each table is `[bindings.<action-id>]`. Supported keys are:
 | Key | Meaning |
 | --- | --- |
 | `plain` | A no-prefix tmux chord such as `M-a`, `C-t`, or `M-S-Left`. |
-| `prefix` | A tmux prefix-table chord such as `A` or `r`. |
+
+Legacy `prefix = ...` entries still parse during migration so existing files
+do not break, but Settings no longer writes prefix keys and generated tmux
+config no longer binds the old action prefix chords.
 
 Set a value to the empty string to disable that chord for the action:
 
@@ -81,12 +128,12 @@ Set a value to the empty string to disable that chord for the action:
 plain = ""
 ```
 
-In Settings, `Disable Plain/Prefix chord` writes the empty string override.
-`Reset Plain/Prefix chord` removes that override and returns to the built-in
-default. The Settings writer is deterministic and rewrites the supported
-subset only: `[bindings.<action-id>]` tables with `plain` and `prefix` string
-keys. If the existing file has parse errors or unknown action IDs, Settings
-shows the keymap error row and refuses to overwrite it until the file is fixed.
+In Settings, `Disable` writes the empty plain override. `Reset default`
+removes that override and returns to the built-in default. The Settings writer
+is deterministic and rewrites the supported saved subset only:
+`[bindings.<action-id>]` tables with `plain` string keys. If the existing file
+has parse errors or unknown action IDs, Settings shows the keymap error row and
+refuses to overwrite it until the file is fixed.
 
 The file currently affects generated tmux config from `projmux tmux
 print-config`, `projmux tmux install`, `projmux tmux print-app-config`,
@@ -107,13 +154,16 @@ configured key opens and closes the popup.
 | `PROJMUX_PROJDIR` | Explicit primary project root. Accepts an OS-native PATH-style multi-value: the first non-empty entry is the primary root and later entries are prepended to managed-root discovery. The primary value is memoized to `~/.config/projmux/projdir`. |
 | `PROJMUX_MANAGED_ROOTS` | Search-root override. Uses the OS-native path-list separator and takes priority over the saved workdirs file and default weak probes. |
 | `TMUX_SESSIONIZER_ROOTS` | Legacy alias still honored at runtime for managed roots. |
-| `PROJMUX_NOTIFY_HOOK` | External executable that receives AI desktop notifications instead of the built-in Linux/WSL sender. |
+| `PROJMUX_NOTIFY_HOOK` | External executable that receives AI desktop notifications instead of the built-in Linux/WSL sender. Separate from declarative `[hooks.send-noti]`. |
+| `PROJMUX_NOTIFY_HOOK_DEPTH` | Internal recursion guard for `send-noti` hooks. Depth `>= 1` suppresses nested hook dispatch while still allowing the queue write itself. |
 | `PROJMUX_DESKTOP_NOTIFY_MODE` | OS desktop notification mode override. `none` / `notify` / `raise` (case insensitive). When set, this takes priority over every other resolution rung. The in-app notify queue is not affected. |
 | `PROJMUX_DESKTOP_NOTIFY` | Legacy on/off override kept for backward compatibility. `on` maps to `notify`, `off` maps to `none`. Honored only when `PROJMUX_DESKTOP_NOTIFY_MODE` is unset. |
 | `PROJMUX_WSL_TOAST_ICON_DIR` | Directory used when copying the WSL toast icon into a Windows-readable path. |
 | `PROJMUX_USAGE_STATE_DIR` | Override directory for AI usage snapshots. Defaults to `<state>/projmux/usage`. Point this at a synced directory to share authoritative usage across machines. |
 | `PROJMUX_USAGE_DEBUG` | When non-empty, prints adapter errors from `projmux status usage` to stderr. |
 | `PROJMUX_USAGE_LIMITS_PATH` | Deprecated. Read but ignored; limits now come from upstream APIs and local Codex rollout state. |
+| `PROJMUX_SESSIONSTATE_AUTOSAVE` | Session snapshot autosave override for the global fallback. Values such as `off`, `false`, or `0` disable autosave for projects that inherit the global setting; explicit project auto-save `on`/`off` still takes precedence. |
+| `PROJMUX_SESSIONSTATE_DEBUG` | When non-empty, quiet autosave surfaces suppressed session-state errors to stderr. |
 | `PROJMUX_FOCUS_DEBUG` | When non-empty, `projmux focus` prints one telemetry line to stderr. |
 | `PROJMUX_PICKER_BACKEND` | Legacy picker backend override. Any value, including old `fzf` settings, now resolves to the native picker. |
 | `PROJMUX_INSTALLER` | Installer source hint used by update flows. npm installs set this automatically; advanced release installs can set `github-release`. |
@@ -151,6 +201,20 @@ When the hook is set, projmux invokes it with positional arguments:
 summary body urgency app-name tag group icon-path
 ```
 
+This environment variable remains the imperative "replace desktop notification
+sender" escape hatch. It does not run through the declarative hook trust/config
+system and it does not receive the notify-queue JSON payload. For additive
+forwarding after a successful queue write, prefer `[hooks.send-noti]` in
+`config.toml`.
+
+`[hooks.send-noti]` and `PROJMUX_NOTIFY_HOOK` can coexist:
+
+- `PROJMUX_NOTIFY_HOOK` replaces the built-in Linux/WSL desktop sender.
+- `[hooks.send-noti]` fires after the queue write and does not replace desktop
+  notifications.
+- `PROJMUX_NOTIFY_HOOK_DEPTH` prevents a `send-noti` hook that calls
+  `projmux notify push` from recursively re-triggering itself.
+
 The app-name argument is `com.crevisse.projmux` (reverse-domain id used as
 the Linux `--app-name`, the macOS sender label, and the Windows
 `AppUserModelID`). Earlier releases used `projmux.TmuxCodex`; the new id
@@ -167,12 +231,12 @@ gated here.
 | Mode | On push | On click |
 | --- | --- | --- |
 | `none` | no toast | n/a |
-| `notify` | toast / notify-send fires | toast click invokes `projmux focus --uri` via the `projmux://` handler |
-| `raise` | toast / notify-send fires AND the host terminal is auto-raised via the osfocus chain | same as `notify` — click is always available |
+| `notify` | toast / notify-send fires | no click action |
+| `raise` | toast / notify-send fires AND the host terminal is auto-raised via the osfocus chain | toast click invokes `projmux focus --uri` via the `projmux://` handler |
 
-Click activation is always wired. The `projmux://` URI handler is
-registered on the first Notify of each tmux server (gated by the
-`@projmux_uri_protocol_registered_v2` marker) regardless of mode. The
+Click activation is wired only for `raise`. The `projmux://` URI handler is
+registered on the first `raise` Notify of each tmux server (gated by the
+`@projmux_uri_protocol_registered_v2` marker). The
 mode only controls whether a toast fires at all and whether to follow it
 up with an on-push auto-raise.
 
@@ -194,13 +258,16 @@ toggle set keep their behavior — `@projmux_desktop_notify=0` resolves to
 Settings press through the new row writes the new key and the legacy key
 goes unused. No eager rewrite of tmux state.
 
-Toggle from Settings > AI Settings > `Desktop notifications`. The
+Toggle from Settings > Notifications > `Desktop notifications`. The
 Settings info row labels the effective source as `env`, `env (legacy)`,
 `setting`, `setting (legacy)`, or `default` so users see which rung of
 the cascade pinned the value.
 
 Hook details for new-session lifecycle hooks and project-local
 `.projmux/config.toml` live in [Hooks](hooks.md).
+Settings names that entry point as **Project recipe** (search still matches
+`config.toml` as an alias) to avoid leaking internal file names in the primary
+Settings view.
 
 ### Toast click handler (WSL + Windows Terminal)
 
@@ -287,6 +354,82 @@ If the marker is missing, the next shell launch shows the welcome again. If the
 marker is corrupt or cannot be written, shell startup continues without the
 welcome.
 
+The same guide is also available on demand through `projmux welcome`, and it is
+linked from Settings > About as `Welcome`.
+
+When `pending_attach_welcome` is true, the generated projmux shell tmux config
+runs `projmux welcome --popup` asynchronously from the `client-attached` hook.
+That helper atomically claims the pending marker, flips it off, and shows the
+welcome guide in a tmux popup once for that version. Missing, corrupt, or
+already-consumed state is a quiet no-op.
+
+Set `PROJMUX_WELCOME=off` before launching or attaching to `projmux shell` to
+suppress the automatic attach popup. The manual `projmux welcome` command still
+prints the guide.
+
+## Session State
+
+`projmux shell` autosaves session snapshots from the app tmux status tick. The
+autosave command is quiet and debounced per session, and stores snapshots under
+`${XDG_STATE_HOME:-$HOME/.local/state}/projmux/sessions`.
+
+Global auto-save defaults to `off` on a fresh install. Project auto-save is an
+override with `inherit`, `on`, and `off`; `inherit` follows the global value,
+while `on` and `off` take precedence. Auto-save only updates the latest
+snapshot. Named snapshots are manual and are never updated by auto-save.
+
+Project open from the Alt-1 sidebar defaults to opening a closed project as an
+`Empty session`. The optional `Settings > Labs > Sidebar startup picker` toggle
+enables the native sidebar `Start project` step. Rows appear as `Latest
+snapshot`, named snapshot rows, `Empty session`, and `Back`. `Latest snapshot`
+is the snapshot auto-save that changes as auto-save runs; named snapshots are
+fixed snapshots. Rows include saved-at date/time metadata when projmux can
+determine it. `Back` returns to the project list without creating, replaying, or
+opening a session. After the startup mode is selected, project hook/config trust
+is evaluated if needed; approval continues the selected path and deny/cancel
+aborts without session create, snapshot replay, or startup command. Existing
+sessions switch directly without a startup picker.
+
+Default `projmux shell` no longer opens a startup picker or replays session-state
+snapshots before attach. It still derives the default app session identity and
+startup directory from the current project context when available; otherwise it
+uses the `home` target and home directory. Session-state restore selection is
+limited to the Labs sidebar startup picker.
+
+Settings > Session State is global settings only: global auto-save, auto-save
+interval, and storage/retention policy. Settings > Project > Session State
+is override/effective-focused: project identity, project auto-save
+`inherit`/`on`/`off`, effective auto-save value/source, and snapshot save
+actions. Snapshot inspection lives under `Projects > Sessions > State`, whose
+overview shows latest/named snapshot status and the window -> pane read model
+without immediate mutation.
+
+The saved global toggles live under
+`${XDG_CONFIG_HOME:-$HOME/.config}/projmux/sessionstate-autosave`,
+`${XDG_CONFIG_HOME:-$HOME/.config}/projmux/sessionstate-autosave-interval`, and
+`${XDG_CONFIG_HOME:-$HOME/.config}/projmux/sidebar-startup-picker`. Project
+auto-save overrides live under
+`${XDG_CONFIG_HOME:-$HOME/.config}/projmux/sessionstate-projects/<session>/autosave`.
+The environment variables above override the global files.
+
+Manual snapshot actions are available from the CLI:
+
+```sh
+projmux session-state status [--session <name>]
+projmux session-state save
+projmux session-state delete [--session <name>]
+projmux session-state restore --dry-run [--session <name>]
+```
+
+`status` prints the source label (`autosave`, `layout(<name>)`, or `fresh`), the
+effective auto-save state, and a compact snapshot preview for the
+target session. Older snapshots without a source field display as `autosave`.
+`save` captures the current tmux session immediately and intentionally bypasses
+the autosave debounce and disabled-autosave gate; it still requires a current
+tmux session. `delete` removes the target snapshot without an interactive
+confirmation. `restore --dry-run` is preview-only in this release and does not
+create sessions or send tmux commands.
+
 ## Decoration Mode
 
 Settings > Appearance controls optional status and picker decoration: