projmux 0.4.9 → 0.4.10

package/README-ko.md

@@ -27,10 +27,8 @@ notification, settings 사이를 오가고 싶을 때 사용합니다.
 
 - [Node.js](https://nodejs.org/)와 npm: 기본 설치 경로에 필요합니다.
 - [tmux](https://github.com/tmux/tmux/wiki/Installing) **3.4 이상**.
-- [fzf](https://github.com/junegunn/fzf#installation) **0.65.0 이상**.
 
-설치 후 `projmux doctor`로 로컬 runtime을 확인하세요. 필요한 `fzf`는
-junegunn/fzf CLI binary입니다. `npm i fzf`는 다른 JavaScript library입니다.
+설치 후 `projmux doctor`로 로컬 runtime을 확인하세요.
 
 ## 설치
 

package/README.md

@@ -27,11 +27,8 @@ keys to move between projects, windows, panes, notifications, and settings.
 
 - [Node.js](https://nodejs.org/) and npm, for the main install path.
 - [tmux](https://github.com/tmux/tmux/wiki/Installing) **3.4 or newer**.
-- [fzf](https://github.com/junegunn/fzf#installation) **0.65.0 or newer**.
 
-Run `projmux doctor` after installing to check the local runtime. The `fzf`
-requirement is the junegunn/fzf CLI binary; `npm i fzf` is a different
-JavaScript library.
+Run `projmux doctor` after installing to check the local runtime.
 
 ## Install
 

package/docs/agent-workflow.md

@@ -29,7 +29,7 @@
 - `make fmt`: repository formatting for Go, shell snippets, and generated docs where applicable.
 - `make fix`: safe automatic fixes such as `go fix` and repository-approved cleanup steps.
 - `make npm-pack`: local npm binary package staging and `npm pack --dry-run` for the root package plus platform packages.
-- `make test`: fast unit coverage for app-layer AI split native agent launch/selective popup-toggle/settings/status/notification parity including AI pane option metadata, watcher metadata bootstrap for existing panes, capture-backed reply detection, missing-pane watcher shutdown, armed focus-only reply badge clearing, busy attention preservation on focus clear, manual AI topic preservation while watcher status still updates, agent-labeled desktop notification message context with pane-title-first body text, global/project-local post-create hook dispatch, and agent-specific notification icons, and scoped even row/column resizing after shell and agent splits, status-bar git/kube segment parity including branch block styling, statusbar pwd click path popup/buffer-copy fallback, isolated `projmux shell` tmux app launch/config generation including home-project default session targeting, app-owned project-name statusbar layout, and distinct project badge color, shell startup update prompt actions for fresh installer-aware cached updates, pane/window keybindings, window rename bindings, pane rename helper/binding, pane-exit rebalance command/hooks, hook-pane and after-select-pane based attention focus hooks, attention badge toggle/clear/list/window rendering, attach/current/kill/pin/preview/prune/sessions/session-popup/settings commands, switch, tag, tmux helper commands, update status/check/apply cache and installer detection including GitHub Release binary asset selection/extraction/replacement, doctor install-missing command selection, and Settings About update status/check action wiring, untitled standalone popup-toggle marker close/config install, direct popup minimum sizing, AI picker minimum width and height, sidebar minimum width and compact badge spacing, preview select writes, popup render output after cycling, switch picker pin action behavior without inline settings rows, nested settings hub sections for AI defaults, project picker filesystem scan/pin actions, Project Root settings source/shadowing/set/current/clear flows, app/keybinding info including Ctrl-M rename forwarding, and About version/source rendering, switch picker focused-session kill, switch picker launcher-key abort bindings, switch explicit project-root, unconfigured-root, and weak managed-root heuristic parity, switch popup hiding new-session candidates while sidebar keeps create-capable rows, switch row project-name display with `~` pinned to the top and live-session-first sorting, pretty-path, preview-context including kube context/namespace, switch settings subcommand flows including add-current-pin, interactive add-pin picker, and settings label/preview polish, fzf preview wiring, fzf baseline surface parity including prompt/footer/header fallback without app-name filler and search-key scoped card matching, sidebar compact action-only key footer, sidebar preview-window/start-position behavior without focus-time session switching, sidebar row/window ANSI styling with pane-aggregated attention badge state and AI topic labels, Alt+2/Alt+3 legacy popup row, preview-window, pane metadata, and pane-snapshot parity, switch read0 card rows with active/inactive title styling, right-side status badges, combined directory/git metadata with muted inactive branch styling, statusbar-matched block window tabs with window attention badges, read0 expect-key action parsing, restored pin/tag card badges, and restrained selected-row marker styling, switch preview metadata without duplicated directory/git rows, preview metadata rendering, popup pane display names for AI agents, AI topics, and shell commands, switch preview cycle bindings, sessions picker preview/cycle/open/kill wiring including attached-session fallback behavior, sessions picker launcher-key abort bindings, popup/switch preview summary formatting, popup sessions tmux entry helpers, switch/popup/session rendering, session identity, candidate discovery, config path derivation, popup preview read-models, and pure state rules including preview, tag, and lifecycle stores.
+- `make test`: fast unit coverage for app-layer AI split native agent launch/selective popup-toggle/settings/status/notification parity including AI pane option metadata, watcher metadata bootstrap for existing panes, capture-backed reply detection, missing-pane watcher shutdown, armed focus-only reply badge clearing, busy attention preservation on focus clear, manual AI topic preservation while watcher status still updates, agent-labeled desktop notification message context with pane-title-first body text, global/project-local lifecycle hook dispatch for post-create/pre-create/pane-startup/post-attach with project hook and .projmux/config.toml trust-store hashing plus env/settings kill-switch gating, declarative startup/hook run precedence, project config env/kube session environment application, pane-startup command capture/send-keys orchestration, pre-create abort behavior, and shared projmux notification icon paths, and scoped even row/column resizing after shell and agent splits, status-bar git/kube segment parity including branch block styling, statusbar pwd display-only native-framed path popup, no clipboard or tmux buffer copy, and simple Enter-close popup command, statusbar usage native HUD popup alignment/threshold/sync-staleness/fallback coverage without raw CLI popup or popup-toggle stacking, statusbar settings click popup fallback, isolated `projmux shell` tmux app launch/config generation including home-project default session targeting, app-owned project-name statusbar layout, and distinct project badge color, first-run/version-bump shell welcome state and inline update handling, shell startup update prompt actions for fresh installer-aware cached updates, pane/window keybindings, keymap.toml tmux override rendering/stale unbinds, Settings Keybindings root/list/detail/typed edit flows including parse-error rows, invalid chord and typed-cancel guards, disable/reset writes, app config regeneration, live tmux source-file reload, and no-live-tmux save behavior, window rename bindings, pane rename helper/binding, pane-exit rebalance command/hooks, hook-pane and after-select-pane based attention focus hooks, attention badge toggle/clear/list/window rendering, attach/current/kill/pin/preview/prune/sessions/session-popup/settings commands, switch, tag, tmux helper commands, update status/check/apply cache and installer detection including GitHub Release binary asset selection/extraction/replacement, doctor install-missing command selection, and Settings About update status/check action wiring, untitled standalone popup-toggle marker close/config install, direct popup minimum sizing, AI picker minimum width and height, sidebar minimum width and compact badge spacing, preview select writes, popup render output after cycling, switch picker pin action behavior without inline settings rows, nested settings hub sections for AI defaults, project picker filesystem scan/pin actions, Project Root settings source/shadowing/set/current/clear flows, app/keybinding info including Ctrl-M rename forwarding, and About version/source rendering, switch picker focused-session kill, switch picker launcher-key abort bindings, switch explicit project-root, unconfigured-root, and weak managed-root heuristic parity, switch popup hiding new-session candidates while sidebar keeps create-capable rows, switch row project-name display with `~` pinned to the top and live-session-first sorting, pretty-path, preview-context including kube context/namespace, switch settings subcommand flows including add-current-pin, interactive add-pin picker, and settings label/preview polish, native preview wiring, baseline picker surface parity including prompt/footer/header fallback without app-name filler and search-key scoped card matching, sidebar compact action-only key footer, sidebar preview-window/start-position behavior without focus-time session switching, sidebar row/window ANSI styling with pane-aggregated attention badge state and AI topic labels, Alt+2/Alt+3 legacy popup row, preview-window, pane metadata, and pane-snapshot parity, switch read0 card rows with active/inactive title styling, right-side status badges, combined directory/git metadata with muted inactive branch styling, statusbar-matched block window tabs with window attention badges, read0 expect-key action parsing, restored pin/tag card badges, and restrained selected-row marker styling, switch preview metadata without duplicated directory/git rows, preview metadata rendering, popup pane display names for AI agents, AI topics, and shell commands, switch preview cycle bindings, sessions picker preview/cycle/open/kill wiring including attached-session fallback behavior, sessions picker launcher-key abort bindings, popup/switch preview summary formatting, popup sessions tmux entry helpers, switch/popup/session rendering, session identity, candidate discovery, config path derivation, popup preview read-models, and pure state rules including preview, tag, and lifecycle stores.
 - Current focused unit coverage also includes strict notify SOT behavior
   (TTL does not remove rows, focus success acks, reconcile reports stale
   rows), `notify list --live` queue/live explanations, notify sidebar
@@ -37,8 +37,8 @@
   actions, and `focus` dispatch diagnostics for session fallback, unresolved
   targets, window fallback, pane fallback, explicit id failures, and
   notify-only fallback.
-- Picker focused unit coverage includes backend-neutral picker item/action mapping, fzf adapter output, native title-focused filtering, numeric selection, shared close actions including raw and CSI-u Ctrl-X native custom actions, saved picker backend config, AI picker title chrome and stable search-key ordering, Settings title chrome and root section order, Settings Labs backend switching, environment override precedence, compact multi-line metadata gutters aligned to the project-name column, proportional native scrollbar thumb rendering, multiline partial next-item row rendering with rendered-row scrollbar units, fixed split-preview and sidebar list viewports with scrollbar tracks, native mouse down/follow-drag/release behavior, preview tab/control normalization before width clipping, optional native frame titlebars without same-line rule fill, titled native Alt-1 sidebar chrome, statusbar-preserving sidebar popup height, native-only compact project sidebar popup sizing, and notify sidebar title/popup sizing that preserves the fzf minimum/ratio baseline.
-- `make test-integration`: Docker-backed Linux integration smoke with real `tmux`, `fzf`, `git`, and `stty`; covers `doctor`, tmux config print/install/apply, and notify queue CRUD against isolated HOME/XDG paths.
+- Picker focused unit coverage includes backend-neutral picker item/action mapping, native title-focused filtering, numeric selection, shared close actions including raw and CSI-u Ctrl-X native custom actions, deprecated picker backend value normalization, AI picker title chrome and stable search-key ordering, Settings title chrome and root section order, Settings Labs shell without backend choices plus keybinding diagnostic list/detail/probe outcome/init delegation coverage, environment override normalization, compact multi-line metadata gutters with one-column-indented metadata, proportional native scrollbar thumb rendering, multiline partial next/previous item row rendering with rendered-row scrollbar units, fixed split-preview and sidebar list viewports with scrollbar tracks, native up/down-family navigation wrap with empty-list safety and PageUp/PageDown/Home/End clamp regression coverage, native mouse down/follow-drag/release behavior, preview tab/control normalization before width clipping, optional native frame titlebars without same-line rule fill, titled native Alt-1 sidebar chrome, statusbar-preserving sidebar popup height, native-only compact project sidebar popup sizing, and notify sidebar title/popup sizing.
+- `make test-integration`: Docker-backed Linux integration smoke with real `tmux`, `git`, and `stty`; covers `doctor`, tmux config print/install/apply, and notify queue CRUD against isolated HOME/XDG paths.
 - `make test-install-smoke`: Docker-backed source install smoke; covers `make install`, atomic binary replacement, `tmux apply` against a live `projmux` socket, and post-install notify queue initialization.
 - `make test-e2e`: Docker-backed real-tmux workflow smoke for session/pane setup, app config sourcing, reply-state notify reconciliation, focus notify fallback, and status notify rendering with contextual project/state/agent badges. Host-only terminal, WSL, macOS, and GUI notification behavior remains outside Docker; see [docs/testing.md](testing.md).
 

package/docs/architecture.md

@@ -41,11 +41,10 @@ Responsibilities:
 - convert failures into typed errors
 
 ### 3. UI orchestration
-Picker data is modeled independently from fzf rows. The app builds
+Picker data is modeled independently from row rendering. The app builds
 backend-neutral `picker.Item` values (`Title`, `Value`, `SearchText`,
-`MetaLines`, `Badges`, `PreviewTarget`) and then adapts them to the selected
-backend. Native is the default backend, while `PROJMUX_PICKER_BACKEND=fzf`
-keeps the external fzf backend available as an explicit fallback.
+`MetaLines`, `Badges`, `PreviewTarget`) and renders them through the native
+picker.
 
 Responsibilities:
 - rows for popup and sidebar views
@@ -180,7 +179,7 @@ single `bind -n MouseDown1Status` covers both lines because tmux fires
 | Range id | Line | Click action                              | Keybinding   |
 |----------|------|-------------------------------------------|--------------|
 | session  | 0    | popup `projmux sessions --ui=popup`       | prefix+s s   |
-| pwd      | 0    | copy pane_current_path and show path popup | prefix+s p   |
+| pwd      | 0    | show pane_current_path in a display-only path popup | prefix+s p   |
 | kube     | 0    | popup `projmux switch --ui=popup`         | prefix+s k   |
 | git      | 0    | popup `projmux switch --ui=popup`         | prefix+s g   |
 | usage    | 1    | popup `projmux usage`                     | prefix+s u   |

package/docs/cli.md

@@ -60,9 +60,8 @@ sub-verbs are entry hooks invoked by tmux keybindings (e.g.
 `sidebar-focus` is wired to the sidebar's focus binding so navigation keeps
 the active session in sync).
 
-Settings > Labs > Picker Engine can switch between the default native picker
-backend and the external fzf fallback. `PROJMUX_PICKER_BACKEND=fzf` is supported
-as an environment override and takes priority over the saved Labs setting.
+Settings > Labs remains available for experimental settings, but picker backend
+selection has been retired. The native picker is always used.
 
 ## setup
 
@@ -102,20 +101,16 @@ projmux doctor [--json]
 projmux doctor --install-missing [--dry-run] [--include-optional]
 ```
 
-Runs a dependency check: `tmux ≥ 3.4`, `fzf ≥ 0.65.0`, `git`, `stty` (POSIX
-only), and `kubectl` (optional). Exit code `0` even when optional deps are
-missing; non-zero only when a required dep is missing or stale. `--json`
-emits a machine-readable array; the default is the human report with
-suggested install commands per platform. `--install-missing` is explicit
-opt-in and runs generated install commands only for missing or stale required
-dependencies. `--dry-run` prints those commands without executing them.
-`--include-optional` also includes optional missing dependencies such as
-`kubectl` when an install command is available. Install flags cannot be
-combined with `--json`. Doctor does not diagnose terminal key delivery; use
-`projmux setup` for that. For fzf, doctor requires the junegunn/fzf CLI
-executable on `PATH` to report at least 0.65.0 from `fzf --version`; the npm
-package `fzf` is a JavaScript library and is not a valid CLI install path for
-projmux.
+Runs a dependency check: `tmux ≥ 3.4`, `git`, `stty` (POSIX only), and
+`kubectl` (optional). Exit code `0` even when optional deps are missing;
+non-zero only when a required dep is missing or stale. `--json` emits a
+machine-readable array; the default is the human report with suggested install
+commands per platform. `--install-missing` is explicit opt-in and runs
+generated install commands only for missing or stale required dependencies.
+`--dry-run` prints those commands without executing them. `--include-optional`
+also includes optional missing dependencies such as `kubectl` when an install
+command is available. Install flags cannot be combined with `--json`. Doctor
+does not diagnose terminal key delivery; use `projmux setup` for that.
 
 ## focus
 
@@ -242,19 +237,20 @@ projmux status notify [--max-width N]
 
 ```
 projmux statusbar click <range-id> [--socket <s>] [--mouse-window <id>]
-                                   [--mouse-x N] [--mouse-y N]
+                                   [--client <tty>] [--mouse-x N] [--mouse-y N]
 ```
 
 Click/keyboard dispatcher for the two-line status bar. Implemented range ids:
-`session pwd kube git usage notify`. The bare `window` /
+`session pwd kube git usage notify settings`. The bare `window` /
 `window|<idx>` token (tmux's built-in window-list range) and the empty
 range fall through to `select-window -t @<mouse_window>` so the native
 click-to-switch tab affordance is preserved on row 0. Unknown range ids are
 non-specialized placeholders and no-op. `session` opens the existing-session
-popup; `pwd` copies the current pane path to the tmux paste buffer and shows
-it in a compact popup; `kube` and `git` open the project switcher popup;
-`usage` opens the detailed `projmux usage` table popup; `notify` focuses and
-acks the newest actionable queue target.
+popup; `pwd` shows the current pane path in a native-framed display-only
+popup; `kube` and `git` open the project switcher popup;
+`settings` toggles the settings popup for the tmux client; `usage` opens the
+detailed `projmux usage` table popup; `notify` focuses and acks the newest
+actionable queue target.
 `MouseDown1Status` errors are
 swallowed and surfaced as `display-message` toasts so a transient
 failure does not raise a tmux error popup. See [statusbar.md](statusbar.md).
@@ -413,10 +409,9 @@ flags with the top-level `switch` UX:
   effective root unless saved. `Workdirs` remains separate: those entries are
   additional search roots, not the primary root. Appearance stores
   `~/.config/projmux/statusbar-decoration` as `off` (default), `symbol`, or
-  `emoji` and updates the live tmux option when available. Labs stores
-  `~/.config/projmux/picker-backend` as `native` (default) or `fzf` and updates
-  the live tmux `PROJMUX_PICKER_BACKEND` environment when available. The About
-  section reads the cached update status without network access;
+  `emoji` and updates the live tmux option when available. Labs remains
+  available for experimental settings. The About section reads the cached
+  update status without network access;
   selecting Check Updates runs `projmux update check`, and Update Now runs
   `projmux update apply`. The same About section also lists the keybinding
   diagnostic path: zero-config first, `setup` for swallowed keys, `init` for

package/docs/configuration.md

@@ -38,6 +38,68 @@ 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.
 
+## 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`,
+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.
+
+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.
+
+`~/.config/projmux/keymap.toml` can also be edited by hand. When the file is
+absent, generated tmux config stays on the built-in defaults.
+
+Supported schema:
+
+```toml
+[bindings.sessionizer-sidebar]
+plain = "M-a"
+prefix = "A"
+
+[bindings.new-window]
+plain = "C-t"
+```
+
+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`. |
+
+Set a value to the empty string to disable that chord for the action:
+
+```toml
+[bindings.sessionizer-sidebar]
+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.
+
+The file currently affects generated tmux config from `projmux tmux
+print-config`, `projmux tmux install`, `projmux tmux print-app-config`,
+`projmux tmux install-app`, and `projmux shell`. Terminal init adapters such as
+Ghostty and Windows Terminal still install the built-in CSI-u fallback map.
+Changing those terminal-layer mappings still requires rerunning `projmux init`
+and restarting the terminal where that terminal requires it.
+
+When a chord is overridden, projmux emits unbinds for both the stale default
+chord and the replacement before binding the merged action. Popup and floating
+UI actions still route through `tmux popup-toggle`, so pressing the same
+configured key opens and closes the popup.
+
 ## Environment Variables
 
 | Variable | Purpose |
@@ -51,7 +113,7 @@ The file is read only when no env root list is set.
 | `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_FOCUS_DEBUG` | When non-empty, `projmux focus` prints one telemetry line to stderr. |
-| `PROJMUX_PICKER_BACKEND` | Override the picker backend. Native is the default; set `fzf` to use the external fzf backend. |
+| `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`. |
 
 Example:
@@ -87,7 +149,8 @@ When the hook is set, projmux invokes it with positional arguments:
 summary body urgency app-name tag group icon-path
 ```
 
-Hook details for new-session lifecycle hooks live in [Hooks](hooks.md).
+Hook details for new-session lifecycle hooks and project-local
+`.projmux/config.toml` live in [Hooks](hooks.md).
 
 ## Usage Tracking
 
@@ -100,6 +163,18 @@ ${PROJMUX_USAGE_STATE_DIR:-${XDG_STATE_HOME:-$HOME/.local/state}/projmux/usage}/
 See [Usage tracking](usage-tracking.md) for adapter behavior, throttling, and
 failure handling.
 
+## Shell Welcome State
+
+`projmux shell` stores its once-per-version welcome marker under:
+
+```text
+${XDG_STATE_HOME:-$HOME/.local/state}/projmux/welcomed-v<version>.json
+```
+
+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.
+
 ## Decoration Mode
 
 Settings > Appearance controls optional status and picker decoration:

package/docs/hooks.md

@@ -1,89 +1,224 @@
 # Hooks
 
-projmux runs an optional user script when it creates a new tmux session. The
-hook is the project-agnostic extension point for things projmux itself stays out of:
-injecting per-session env via `tmux set-environment`, picking a `GH_TOKEN` for
-the repo, exporting a Kubernetes context, kicking off a background sync, etc.
-projmux never ships behavior specific to any of those — that lives in the
-hook.
+projmux runs optional user scripts at selected tmux lifecycle points. Hooks are
+the project-agnostic extension point for behavior projmux itself stays out of:
+injecting per-session env via `tmux set-environment`, selecting repository
+tokens, exporting a Kubernetes context, kicking off a background sync, or
+sending an initial pane command.
 
-## Where it lives
+projmux-owned internal tmux hooks such as `pane-focus-in`, `pane-focus-out`,
+`after-select-pane`, and `after-kill-pane` are not exposed as user hook events.
 
-Global hook:
+## Events
+
+| Event | When it runs | Failure behavior | Stdout behavior |
+| --- | --- | --- | --- |
+| `pre-create` | Before projmux creates a missing persistent or ephemeral session | Non-zero exit, exec error, or timeout aborts creation | Logged with `[pre-create] ` |
+| `post-create` | After projmux creates a brand-new persistent or ephemeral session | Logged and ignored; creation continues | Logged with `[post-create] ` |
+| `pane-startup` | After `post-create`, once the initial pane of a brand-new session reaches a shell prompt | Logged and ignored; empty output is no-op | Captured as the command to send into the pane |
+| `post-attach` | After projmux switches the current tmux client to an existing session/target from inside tmux | Logged and ignored | Logged with `[post-attach] ` |
+
+Deferred Phase A candidates remain future work until their behavior can be
+specified without exposing projmux's internal tmux hook machinery: pane exit,
+window create/rename, and focus-change hook events.
+
+## Where Hooks Live
+
+Global hooks live under the XDG config directory:
+
+```text
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/hooks/<event>
+```
+
+For example:
 
 ```text
 ${XDG_CONFIG_HOME:-$HOME/.config}/projmux/hooks/post-create
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/hooks/pane-startup
 ```
 
-Project-local hooks, discovered from the new session's `PROJMUX_CWD`:
+Project-local hooks are discovered from the lifecycle context's `PROJMUX_CWD`:
 
 ```text
-<repo>/.projmux/post-create
-<repo>/.projmux/hooks/post-create
+<repo>/.projmux/<event>
+<repo>/.projmux/hooks/<event>
+<repo>/.projmux/config.toml
 ```
 
-Each hook file must exist, be a regular file or symlink (not a directory), and
-have the owner-execute bit set. Anything else is silently skipped — no warning,
-no log. There is no enable flag.
+For example, `pane-startup` discovery checks:
 
-```sh
-mkdir -p ~/.config/projmux/hooks
-chmod +x ~/.config/projmux/hooks/post-create
+```text
+<repo>/.projmux/pane-startup
+<repo>/.projmux/hooks/pane-startup
 ```
 
-For project-local hooks, projmux runs at most one file: first
-`.projmux/post-create` if executable, otherwise `.projmux/hooks/post-create` if
+Each hook file must exist, be a regular file or symlink (not a directory), and
+have the owner-execute bit set. Anything else is silently skipped.
+
+For each event, projmux runs at most one project-local file: first
+`.projmux/<event>` if executable, otherwise `.projmux/hooks/<event>` if
 executable. Discovery does not walk parent directories and does not run hooks
 from status, preview, or picker hot paths.
 
-## When it runs
+If both a global hook and a project-local hook exist for an event, projmux runs
+the global hook first, then the project-local hook, then any matching
+declarative config command from `.projmux/config.toml`. For `pane-startup`, the
+last non-empty trimmed stdout wins. Config `pane-startup` commands therefore
+override file hooks deterministically.
+
+## Project Config
+
+Repositories may declare hook behavior in `.projmux/config.toml`. projmux
+supports only this narrow TOML subset in Phase B:
+
+```toml
+[startup]
+run = "git status --short"
+
+[hooks.pre-create]
+run = "echo checking"
+
+[hooks.post-create]
+run = "echo created $PROJMUX_SESSION"
+
+[hooks.pane-startup]
+run = "echo make test"
+
+[hooks.post-attach]
+run = "echo attached"
+
+[env]
+FOO = "bar"
+
+[kube]
+context = "dev-cluster"
+namespace = "tools"
+```
+
+Only quoted string values are supported. Unknown sections or keys make the
+config file invalid for this run. Supported hook events are the public lifecycle
+events listed above: `pre-create`, `post-create`, `pane-startup`, and
+`post-attach`. Internal tmux hook names such as `after-select-pane` are rejected.
+Phase C secret interpolation is not implemented; values are used literally.
+
+`[hooks.<event>] run` executes through `sh -c` with the same timeout, logging,
+environment, and failure model as file hooks. For `pane-startup`, stdout is
+captured as the pane command.
+
+`[startup] run` is a direct shorthand for a startup pane command. It is not
+executed as shell by the hook runner; the string itself is sent to the new pane.
+When both `[hooks.pane-startup] run` and `[startup] run` are present,
+`[startup] run` wins because it is applied last.
+
+`[env]` values are added to hook process environments and to newly-created tmux
+session environments. For new sessions, projmux passes them to
+`tmux new-session` as sorted `-e KEY=VALUE` arguments before the first pane is
+created, so the initial shell and `[startup]` command can see them. projmux also
+refreshes the tmux session environment with `tmux set-environment -t <session>
+KEY VALUE` after creation for later panes. projmux's reserved `PROJMUX_*` hook
+variables are appended after `[env]` in hook process environments, so the hook
+contract cannot be overridden by project config.
+
+`[kube] context` and `namespace` are reflected as hook and session environment:
+`PROJMUX_KUBE_CONTEXT`, `KUBE_CONTEXT`, `PROJMUX_KUBE_NAMESPACE`, and
+`KUBE_NAMESPACE`. projmux does not synthesize kubeconfig files from these two
+values.
+
+## Trust Model
+
+Global hooks under `$XDG_CONFIG_HOME` are prompt-free.
+
+Project-local hooks and `.projmux/config.toml` are gated by trust-on-first-use
+for every user-facing hook event in this file. A repository hook file or config
+file must be approved before projmux runs or applies it. Approving "always"
+records the file content hash in:
+
+```text
+${XDG_STATE_HOME:-$HOME/.local/state}/projmux/trusted-projects.json
+```
+
+The trust key is the absolute repository path and each executable hook or config
+path is stored relative to that repository. Each project entry has a
+`trusted_at` timestamp and a `files` map of relative paths to SHA-256 hashes.
+When file content changes, projmux asks again and shows the old and new SHA-256
+hashes. In non-interactive contexts such as tmux run-shell or CI, untrusted or
+changed project-local files fail closed with a warning.
+
+Set `PROJMUX_PROJECT_HOOKS=off` to disable project-local hook discovery
+entirely. Project-local hooks can also be disabled from `projmux settings`
+under Labs. The global hook still runs either way.
+
+## Pane Startup
+
+`pane-startup` runs only for the initial pane created with a new
+projmux-managed session. It runs after `post-create` so `post-create` can seed
+session-level tmux environment before the startup command is sent. It does not
+run when projmux attaches to an existing session or target.
+
+Before running `pane-startup`, projmux polls tmux `pane_current_command` for the
+new pane and waits until it reports a shell command. This avoids fixed sleeps as
+the primary readiness mechanism.
+
+The hook's trimmed stdout is treated as the command to send into the new pane:
+
+```text
+tmux send-keys -t <pane-id> <command> Enter
+```
+
+Empty stdout is a no-op. Hook stderr is still forwarded to projmux's stderr with
+the `[pane-startup] ` prefix. If both global and project-local hooks emit a
+command, the project-local command wins because project hooks run after global
+hooks.
+
+## Pre Create Abort
+
+`pre-create` runs before `tmux new-session` on creation paths. A non-zero exit,
+exec error, or timeout aborts the session creation. If a global `pre-create`
+hook aborts, the project-local `pre-create` hook does not run.
 
-After projmux creates a brand-new tmux session via `EnsureSession` (the
-persistent path used by `current` and `switch`) or `CreateEphemeralSession`
-(used by `attach`). It does **not** run when projmux attaches to an existing
-session.
+This is the only Phase A hook event that can block creation.
 
-If both a global hook and a project-local hook exist, projmux runs the global
-hook first, then the project-local hook. A failure or timeout in either hook is
-logged once and does not block session creation or the other hook.
+## Post Attach
 
-The hook's exit code is ignored — session creation always succeeds.
-Hook stdout and stderr are forwarded to projmux's stderr line-by-line,
-prefixed with `[post-create] `. The hook is killed after 5 seconds.
+`post-attach` is supported only when projmux is already running inside tmux and
+uses `switch-client` to move the current client to an existing session or
+target. Outside tmux, `tmux attach-session` blocks until the user detaches, so
+projmux does not run `post-attach` for outside-tmux attach paths in this phase.
 
 ## Environment
 
-The hook inherits projmux's environment, plus:
+Hooks inherit projmux's environment, plus:
 
 | Variable | Always set | Description |
 | --- | --- | --- |
 | `PROJMUX_SESSION` | yes | tmux session name |
-| `PROJMUX_CWD` | yes | absolute working directory of the new session |
-| `PROJMUX_SESSION_KIND` | yes | `persistent` or `ephemeral` |
+| `PROJMUX_CWD` | yes | lifecycle working directory; for creation events this is the new session directory |
+| `PROJMUX_SESSION_KIND` | yes | `persistent` or `ephemeral` for creation events; empty for `post-attach` |
 | `PROJMUX_VERSION` | yes | projmux version string |
 | `PROJMUX_SOCKET` | only if projmux used `tmux -L <socket>` | tmux socket name |
+| `PROJMUX_PANE` | only for pane events | tmux pane id such as `%7` |
 
 ## Examples
 
-### Global stub
+### Global Post Create Stub
 
 ```bash
 #!/usr/bin/env bash
 echo "session=$PROJMUX_SESSION cwd=$PROJMUX_CWD kind=$PROJMUX_SESSION_KIND"
 ```
 
-### Project-local stub
+### Project Pane Startup Command
 
 ```bash
 mkdir -p .projmux
-cat > .projmux/post-create <<'EOF'
+cat > .projmux/pane-startup <<'EOF'
 #!/usr/bin/env bash
-echo "project hook for $PROJMUX_CWD"
+echo "git status --short"
 EOF
-chmod +x .projmux/post-create
+chmod +x .projmux/pane-startup
 ```
 
-### Per-session GH_TOKEN by repo
+### Per Session GH_TOKEN By Repo
 
 ```bash
 #!/usr/bin/env bash
@@ -105,14 +240,21 @@ it does not retroactively change the current shell. Open new panes via tmux
 ## Troubleshooting
 
 - **Nothing happens.** Check the execute bit on the global hook
-  (`ls -l ~/.config/projmux/hooks/post-create`) or the project hook
-  (`ls -l .projmux/post-create .projmux/hooks/post-create`). A missing bit
-  makes projmux skip silently by design.
-- **`projmux: post-create hook: ... timed out after 5s`.** Long-running work
+  (`ls -l ~/.config/projmux/hooks/<event>`) or the project hook
+  (`ls -l .projmux/<event> .projmux/hooks/<event>`). A missing bit makes
+  projmux skip hook files silently by design. `.projmux/config.toml` does not
+  need an execute bit.
+- **`project hook ... requires trust; skipping in non-interactive context`** or
+  **`project config ... requires trust; skipping in non-interactive context`.**
+  Run the same projmux command from an interactive terminal to approve the file,
+  or set `PROJMUX_PROJECT_HOOKS=off` if project-local execution should be
+  disabled.
+- **`projmux: <event> hook: ... timed out after 5s`.** Long-running work
   belongs in a backgrounded child (`(slow-thing &) >/dev/null 2>&1`). The hook
   itself must return within 5s or projmux kills it.
-- **`projmux: post-create hook: hook ... exited with status N`.** The script
-  returned non-zero. projmux logs it once and moves on; the session is still
-  created.
-- **Lines appear with `[post-create] ` prefix.** Expected — that is how the
-  hook's stdout/stderr is multiplexed into projmux's stderr stream.
+- **`projmux: <event> hook: hook ... exited with status N`.** The script
+  returned non-zero. For `pre-create`, creation aborts; for other events,
+  projmux logs once and moves on.
+- **Lines appear with `[post-create] `, `[pre-create] `, or `[post-attach] `
+  prefixes.** Expected; hook stdout/stderr are multiplexed into projmux's
+  stderr stream. `pane-startup` stdout is captured as the pane command instead.

package/docs/install.md

@@ -18,8 +18,20 @@ After installing, run:
 projmux doctor
 ```
 
-`doctor` checks that runtime tools such as `tmux` and the junegunn/fzf CLI are
-available and new enough.
+`doctor` checks that runtime tools such as `tmux`, `git`, and `stty` are
+available.
+
+Start the tmux app with:
+
+```sh
+projmux shell
+```
+
+The first launch for each projmux version prints a short welcome with the
+current version, detach/exit keys, core app shortcuts, and cached update status
+when available. If an installer-supported update is available, pressing Enter
+at the inline prompt runs `projmux update apply`; answering `n` prints that
+manual command and continues into the shell.
 
 ## Runtime Tools
 
@@ -27,7 +39,6 @@ Normal use needs:
 
 - Node.js and npm for the npm install channel.
 - tmux 3.4 or newer.
-- fzf 0.65.0 or newer.
 
 Useful optional tools: