projmux 0.5.3 → 0.6.1

package/docs/agent-workflow.md

@@ -29,15 +29,27 @@
 - `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 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, Settings project config env/kube/startup form writes with trust-store refresh and preserved hook commands, 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, session-state Claude resume replay, 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/post-attach/send-noti with project hook and `.projmux/config.toml` trust-store hashing plus env/settings kill-switch gating, declarative startup command and hook run coverage, `send-noti` stdin JSON delivery plus `PROJMUX_NOTIFY_*` env payload, notify queue write success/failure/depth-guard dispatch rules, notify/statusbar/sidebar origin-client focus routing, project config env/kube session environment application, Settings project config env/kube/startup form writes with trust-store refresh and preserved hook commands, startup command send-keys orchestration plus startup pane replay markers, 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 fallback plus project-context default session targeting from `PROJMUX_CWD` or nearest project marker, app-owned project-name statusbar layout, distinct project badge color, and quiet debounced session-state autosave command/app-config trigger, 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 capture flows including parse-error rows, unsafe raw capture and timeout 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, AI notify integration diagnostics, and Session State resume metadata diagnostics, Settings AI notify integration diagnostics read-only status/conflict/CLI guidance, 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, session-state Claude/Codex resume and declarative startup replay, session snapshot capture/autosave recipe classification including save/autosave pre-capture resume metadata refresh from live AI session ids, Claude transcript paths, and Codex rollout log cwd matching/ambiguity skips, candidate discovery, config path derivation, popup preview read-models, and pure state rules including preview, tag, and lifecycle stores.
+- `make test` also covers Settings IA regression guards for `send-noti` visibility in Hooks, no nested Project recipe inside Hooks, Project recipe/AI/Labs view-first detail rows, Notifications root/Desktop notifications/Delivery sources relocation, Delivery sources command-row clipboard copy, and Labs Project Hooks overview-first rows.
+- `make test` also covers Settings > Session State as global settings-only UI with default-off auto-save and no window/pane tree, Settings > Project > Session State project-derived identity plus project auto-save override/effective source rows and distinct Save latest snapshot / Save named snapshot labels, closed-project save disabled reasons, named snapshot portable path conversion, project/global auto-save precedence, Projects > Sessions > State read-only latest/named snapshot overview with window/pane cwd/recipe/agent-resume health, user-facing `projmux session-state` status/save/delete/restore dry-run actions including explicit manual save bypass of disabled autosave and agent resume status/confidence preview, and Project open sidebar startup coverage for Labs opt-in `Start project`, default-off empty creation, Latest snapshot, Named snapshot, Empty session, Back, saved-at row metadata, existing-session skip, startup-before-trust ordering, trust approve continuation, and trust deny/cancel no-session behavior.
+- `make test` also covers `projmux shell` usage without startup selector flags, project-context default target lookup from `PROJMUX_CWD` or nearest project marker, explicit `--session` separation from project-derived defaults, and direct empty attach behavior without shell startup picker/replay.
+- `make test` also covers manual Session State Save snapshot and restore dry-run preview actions, title-first pane preview labels with legacy snapshot fallback, missing-snapshot messaging, and the absence of the removed statusbar State shortcut.
+- `make test` also covers legacy named-snapshot storage compatibility for `.projmux/layouts/*.toml`, supported interpolation validation, malformed-file list warnings, portable conversion helpers, dry-run conversion to the session-state restore preview with source labels, missing current-session failure, destructive live replay helper behavior with fresh/internal source marking and fresh saved-snapshot cleanup, and the session-state live replay helper that stages windows, moves them by tmux ID, and removes extra live windows.
+- `make test` also covers `projmux ai integrate codex` default hooks install/idempotence/dry-run/removal, compatibility legacy Codex notify mode install/idempotence, dry-run preview, unmanaged `notify = ...` conflict refusal, managed-block removal, catalog-driven Codex hook event installation with local override merging, nested inline Codex hook schema, `[features]` merge/preservation, preservation of unrelated Codex/Claude config and unmanaged hook entries, Settings Codex `/hooks` review notice and tested-version rows, and remove-all behavior for projmux-managed Codex blocks.
+- `make test` also covers `projmux ai ingest codex-hook` event parsing, PermissionRequest critical queue rows with tool/action metadata, Stop info queue rows, UserPromptSubmit busy/no-queue behavior, quiet/no-notify diagnostics for non-firing Codex hook events including override-added catalog events, cataloged hook notification body formatting, hook-active pane marking, topic preservation without hook candidate writes, and mutable resume metadata writes for `@projmux_ai_resume_id`, source, and updated-at.
+- `make test` also covers `projmux ai integrate claude` user-level Claude Code hook settings install/idempotence, dry-run preview, unmanaged projmux ingest command conflict refusal across all settings events, managed-command removal by marker even for stale events outside the current catalog, preservation of unrelated settings/hooks, catalog-driven Claude hook event installation with local override merging, and managed wiring for the 29 Claude Code 2.1.140 events in the embedded default catalog.
+- `make test` also covers `projmux ai ingest claude-hook` core and extra Claude Code hook ingest for event parsing, transcript fallback, cataloged hook notification body formatting, permission summary formatting, UserPromptSubmit busy/no-queue behavior, Notification severity/text mapping, StopFailure/TeammateIdle text/severity/metadata mapping, SubagentStop quiet/no-notify diagnostics, unknown future-event quiet fallback, hook-active pane marking, topic preservation without hook candidate writes, mutable resume metadata writes for `@projmux_ai_resume_id`, source, and updated-at, and Claude transcript path preservation.
+- `make test` also covers `projmux ai integrate tmux-bell` dry-run/install/remove tmux command planning, managed `alert-bell` hook append/idempotence/removal, preservation of unmanaged bell hooks, and `projmux ai ingest bell --pane` queue push/metadata/dedupe behavior for non-AI-managed panes.
+- `make test` also covers `projmux ai ingest log` tail/path rendering and bounded JSONL log trimming for ingest diagnostics.
+- `make test` also now covers onboarding revisit and welcome wiring (`projmux welcome`, `Settings > About > Welcome`, `pending_attach_welcome`, attach-time `welcome --popup` one-time claim/env suppression/tmux popup payload, and generated `client-attached` app config wiring) via shell welcome tests.
 - 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
+  (TTL does not remove rows, focus success and target-gone clicks ack,
+  reconcile reports stale rows), `notify list --live` queue/live explanations, notify sidebar
   two-line card rendering with age/project/window/pane metadata plus focus/ack/clear-all
   actions, and `focus` dispatch diagnostics for session fallback, unresolved
-  targets, window fallback, pane fallback, explicit id failures, and
+  targets, window fallback, pane fallback, explicit id failures as unresolved exits, and
   notify-only fallback.
-- 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.
+- 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 and with titlebar border reset guards, 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/cli.md

@@ -43,6 +43,7 @@ projmux <command> [args...]
 | `tmux` | Open tmux popup entry helpers / install generated config. |
 | `update` | Check installer-aware GitHub release update status. |
 | `upgrade` | Self-update via `go install`. |
+| `welcome` | Print the shell onboarding guide again. |
 | `usage` | Report AI token usage across 5h and weekly windows. |
 | `version` | Print the current version. |
 
@@ -102,20 +103,38 @@ projmux doctor --install-missing [--dry-run] [--include-optional]
 ```
 
 Runs a dependency check: `tmux ≥ 3.4`, `git`, `stty` (POSIX only), and
-`kubectl` (optional). Exit code `0` even when optional deps are missing;
+`kubectl` (optional), then reports read-only AI notify integration diagnostics
+for Codex hooks, Claude Code hooks, and the tmux bell
+fallback. AI notify integration statuses are `installed`, `missing`, or
+`conflict`; missing or conflicting integrations are informational and do not
+make doctor fail. It also reports read-only Session State resume metadata
+diagnostics for saved agent panes, including `available`, `stale`, or
+`unavailable` status plus confidence, source, updated-at, and the affected
+snapshot/window/pane.
+
+Exit code `0` even when optional deps or AI notify integrations 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.
+machine-readable object with `dependencies`, `ai_notify_integrations`, and
+`session_state_resume`; the default is the human report with suggested install
+commands per platform, AI integration install/remove/dry-run commands, and
+Session State resume metadata health. `--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.
+
+`Settings > Notifications > Delivery sources` shows active Codex hooks, Claude,
+and tmux statuses, conflicts, config paths, and copyable AI integration
+install/remove/dry-run commands. Settings does not install or remove external
+Codex, Claude, or tmux notify wiring.
 
 ## focus
 
 ```
 projmux focus --target SESSION[:WINDOW[.PANE]] [--socket <path>]
+              [--client <tty>]
               [--source ai|status-bar|external|os-notification|toast]
               [--kind reply-ready|busy-cleared|segment-click|toast-click|custom]
               [--json]
@@ -130,6 +149,12 @@ client is attached on that socket, it emits the configured desktop
 notification instead. `--socket` is explicit; when omitted, the socket is
 derived from `$TMUX`.
 
+`--client` is a preferred origin tmux client. In-app consumers such as the
+status bar and notify sidebar pass the clicked client so focus redirects that
+display first. If that client is gone, focus falls back to an attached client
+already viewing the target session, then the stable first attached client.
+Toast clicks do not pass `--client`.
+
 `--uri` is the entry point used by the WSL Toast click handler (see
 [configuration.md](configuration.md#toast-click-handler-wsl--windows-terminal)).
 The pane id from the URI is resolved to a `SESSION:WINDOW.%paneID` target
@@ -140,7 +165,8 @@ via `tmux display-message`, and the URI's `socket` overrides any
 Exit codes:
 
 - `0` — focused (or the notify-only fallback fired).
-- `2` — target session could not be resolved (`focusExitNotResolved`).
+- `2` — target session/window/pane could not be resolved
+  (`focusExitNotResolved`).
 
 `--source`/`--kind` are telemetry labels logged when
 `PROJMUX_FOCUS_DEBUG` is set. `--json` prints a single-line JSON payload
@@ -150,7 +176,7 @@ distinguish unresolved sessions (`reason=session-unresolved`, exit 2),
 session rename/prefix fallback (`session_state=fallback`), window index
 fallback (`window_state=index-fallback-session`), pane index fallback
 (`pane_state=index-fallback-window`), and explicit id failures
-(`window-id-unresolved` / `pane-id-unresolved`).
+(`window-id-unresolved` / `pane-id-unresolved`, exit 2).
 
 ## notify
 
@@ -164,7 +190,7 @@ projmux notify push  --text <s> --target <SESSION[:WINDOW[.PANE]]>
                      [--socket <s>] [--severity info|warn|critical]
                      [--source ai|k8s|git|external] [--ttl <seconds>]
                      [--id <s>] [--json]
-projmux notify list  [--live] [--json] [--limit N] [--ui table|sidebar]
+projmux notify list  [--live] [--json] [--limit N] [--ui table|sidebar] [--client <tty>]
                      [--severity ...] [--source ...]
 projmux notify ack   <id> | --all
 projmux notify reconcile [--json]
@@ -173,7 +199,10 @@ projmux notify reconcile [--json]
 - `push` — append (or refresh, with `--id`) one entry. `--ttl` defaults to
   `600` seconds as freshness metadata; it does not remove rows from
   `notify list`. `--text` is hard-capped to 80 runes (longer text is
-  truncated server-side).
+  truncated server-side). After a successful queue write, projmux fires
+  declarative `[hooks.send-noti]` asynchronously if configured. That hook gets
+  a JSON payload on stdin plus `PROJMUX_NOTIFY_*` env vars, and it does not
+  replace the normal desktop notification path.
 - `list` — newest-first pending queue table `ID AGE SEV SRC TARGET TEXT`
   (or JSON). `--severity` and `--source` are repeatable filters.
   `--live` adds a non-mutating explanation table (or JSON report) that
@@ -185,7 +214,8 @@ projmux notify reconcile [--json]
   acks the selected row, and `Ctrl-X` clears all; opening or navigating the
   sidebar does not ack. The sidebar uses two-line cards with notification text
   first and compact age/project/window/pane metadata below. Hidden queue ids
-  remain action values, but the sidebar has no search input.
+  remain action values, but the sidebar has no search input. `--client` is
+  used by tmux popup launchers to keep row-select focus on the clicked client.
 - `ack <id>` removes one entry; `--all` flushes the queue.
 - `reconcile` — walks `tmux list-panes -a` and back-fills entries for
   panes whose attention state is `reply` AND whose AI agent option is
@@ -294,6 +324,13 @@ projmux ai settings
 projmux ai status   set <thinking|waiting|idle> [--pane <id>]
 projmux ai notify   <reset|notify> [--pane <id>]
 projmux ai watch-title [--pane <id>]
+projmux ai ingest   codex-hook < payload.json
+projmux ai ingest   claude-hook < payload.json
+projmux ai ingest   bell --pane <pane_id>
+projmux ai ingest   log [--tail N] [--json] [--path]
+projmux ai integrate codex [--dry-run] [--remove]
+projmux ai integrate claude [--dry-run] [--remove]
+projmux ai integrate tmux-bell [--dry-run] [--remove]
 projmux ai topic     ...
 ```
 
@@ -303,6 +340,211 @@ notifier. `status set waiting` is the trigger that flips a pane to the
 reply-ready state — that transition pushes an `ai:<session>:<pane>`
 entry into the notify queue.
 
+`ingest codex-hook` is the hook-facing entrypoint for Codex hooks-engine JSON.
+It reads one JSON payload from stdin and handles the default Codex hook catalog
+`PreToolUse`, `PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`,
+`SessionStart`, `UserPromptSubmit`, and `Stop` as exposed by Codex CLI 0.130.0.
+It accepts the common Codex hook fields `hook_event_name`/`event_name`,
+`thread_id`, `session_id`, `turn_id`, `cwd`, `transcript_path`, `model`,
+`tool_name`, nested `tool.name`, `tool_input`, and `input`. `UserPromptSubmit`
+marks the matched pane hook-active and moves it to thinking/busy without
+pushing a queue entry. `Stop` pushes an info completion row. `PermissionRequest`
+pushes a critical approval row with the tool name and concise action summary.
+The other Codex events are quiet: they mark the pane hook-active and write
+ingest diagnostics, but do not push notify queue entries.
+For event names without a specialized notify/state handler, ingest falls back
+to quiet/log-only handling. A local catalog entry with `"action": "quiet"`
+therefore lets newly discovered events be installed and observed without
+creating notification noise; `"notify"` and `"state"` still require a built-in
+handler before they can change pane state or push queue rows.
+
+`ingest claude-hook` is the hook-facing entrypoint for Claude Code hooks. It
+reads one JSON payload from stdin and handles the default Claude Code 2.1.140
+hook catalog: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`,
+`PostToolBatch`, `PermissionDenied`, `Notification`, `UserPromptSubmit`,
+`UserPromptExpansion`, `SessionStart`, `Stop`, `StopFailure`,
+`SubagentStart`, `SubagentStop`, `PreCompact`, `PostCompact`, `SessionEnd`,
+`PermissionRequest`, `Setup`, `TeammateIdle`, `TaskCreated`,
+`TaskCompleted`, `Elicitation`, `ElicitationResult`, `ConfigChange`,
+`InstructionsLoaded`, `WorktreeCreate`, `WorktreeRemove`, `CwdChanged`, and
+`FileChanged`. It uses the same pane matching order as Codex ingest
+(`$TMUX_PANE`, payload `cwd`, then cached session id), marks matched panes
+hook-active, and writes metadata-bearing notify queue entries only for
+reply-ready, input-ready, approval-required, error, and teammate-idle events.
+`SubagentStop` and the other lifecycle/tool events are quiet: they mark the
+pane hook-active and write ingest diagnostics, but do not push notify queue
+entries. `UserPromptSubmit` only moves the pane to thinking/busy and does not
+push a queue entry.
+Unknown Claude events also fall back to quiet/log-only handling after pane
+matching. Catalog `action` is honored for quiet fallback events; notify/state
+actions need built-in handlers for event-specific body text and state changes.
+
+`ingest bell --pane <pane_id>` is the narrow tmux-bell fallback ingest path.
+It does not require the pane to be AI-managed. Projmux resolves session,
+window, pane, title, command, and socket metadata from tmux, pushes an info
+queue row such as `bell · <pane title>`, and suppresses repeat bell rows from
+the same pane for 5 seconds.
+
+`ingest log` prints recent ingest diagnostics from
+`$XDG_STATE_HOME/projmux/ai-ingest.log`, or `~/.local/state/projmux/ai-ingest.log`
+when `XDG_STATE_HOME` is unset. Ingest paths append compact JSONL records for
+parse errors, unsupported events, missing pane matches, deduped bells,
+state-only transitions, quiet high-volume events, and notify pushes. Raw hook
+payloads are not stored. The log is capped at 1 MiB and trimmed to the most
+recent roughly 512 KiB when it grows past the cap. Use `--json` for raw JSONL
+and `--path` to print the resolved file path.
+
+For `Stop`, projmux reads `transcript_path` when present and extracts the last
+assistant text from the transcript tail; if that is unavailable, it falls back
+to a generic Claude completion row. `PermissionRequest` rows expose the tool
+name plus a concise input summary, preferring Bash commands, file paths, and
+URLs when those fields exist.
+
+Hook row text is intentionally compact: agent label, event category, then the
+best available summary. Structured details remain in queue metadata and are
+available from `notify list --json`; the sidebar does not add a separate
+metadata detail view.
+
+The extra Claude events accept conservative field aliases while Claude's event
+schemas settle. `StopFailure` reads `error_type`/`errorType`/`failure_type` and
+`error_message`/`errorMessage`/`message`/`reason`, plus nested
+`error.type|name|code` and `error.message|text|reason`. `SubagentStop` reads
+`subagent_type`/`subagentType`/`agent_type`, `subagent_id`/`subagentId`, and
+nested `subagent.type|name|kind|id`. `TeammateIdle` reads
+`teammate_name`/`teammateName`, `teammate_id`/`teammateId`,
+`teammate_context`/`teammateContext`/`context`/`reason`/`message`, and nested
+`teammate.name|id|context|status|reason|message`.
+
+Claude Code hook ingest is available through `ingest claude-hook`, but
+`integrate claude` is the opt-in user-level wiring command for
+`~/.claude/settings.json`. It installs command hooks for every event whose
+effective Claude hook catalog entry has `"install": true`. The embedded default
+catalog is based on Claude Code 2.1.140 and lives at
+`internal/app/ai_hook_catalogs/claude.json`; a local override may be placed at
+`${XDG_CONFIG_HOME:-$HOME/.config}/projmux/ai-hooks.d/claude.json` to disable
+or add events before projmux itself is released:
+
+```json
+{
+  "provider": "claude",
+  "events": [
+    { "name": "Stop", "install": false, "action": "notify" },
+    { "name": "FutureEvent", "install": true, "action": "quiet" }
+  ]
+}
+```
+
+The embedded Claude catalog contains all 29 Claude Code 2.1.140 events:
+`PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PostToolBatch`,
+`PermissionDenied`, `Notification`, `UserPromptSubmit`,
+`UserPromptExpansion`, `SessionStart`, `Stop`, `StopFailure`,
+`SubagentStart`, `SubagentStop`, `PreCompact`, `PostCompact`, `SessionEnd`,
+`PermissionRequest`, `Setup`, `TeammateIdle`, `TaskCreated`,
+`TaskCompleted`, `Elicitation`, `ElicitationResult`, `ConfigChange`,
+`InstructionsLoaded`, `WorktreeCreate`, `WorktreeRemove`, `CwdChanged`, and
+`FileChanged`. `SubagentStop` remains quiet/log-only.
+
+The managed command receives Claude's hook JSON on stdin, keeps stdout/stderr
+quiet, and exits successfully even if ingest fails so it does not block Claude
+Code behavior. `--dry-run` previews the JSON update, and `--remove` deletes
+only commands carrying the projmux marker. Removal and unmanaged conflict
+detection scan every `hooks` event in the settings file rather than trusting the
+current catalog, so stale managed events from older catalogs are still removed.
+Existing unrelated Claude settings and hooks are preserved. If any event already
+contains an unmanaged `projmux ai ingest claude-hook` command, projmux refuses
+to install over it and leaves the settings file untouched.
+
+`projmux ai integrate codex` manages a hooks-engine
+block in `~/.codex/config.toml`. It enables `[features] hooks = true`,
+merging into an existing `[features]` table when present, and installs broad
+command hooks for every event whose effective Codex hook catalog entry has
+`"install": true`. The embedded default catalog is based on Codex CLI 0.130.0
+and lives at `internal/app/ai_hook_catalogs/codex.json`; a local override may
+be placed at `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/ai-hooks.d/codex.json`:
+
+```json
+{
+  "provider": "codex",
+  "events": [
+    { "name": "Stop", "install": false, "action": "notify" },
+    { "name": "FutureEvent", "install": true, "action": "quiet" }
+  ]
+}
+```
+
+The embedded Codex catalog contains the 8 Codex CLI 0.130.0 events
+`PreToolUse`, `PermissionRequest`, `PostToolUse`, `PreCompact`,
+`PostCompact`, `SessionStart`, `UserPromptSubmit`, and `Stop`.
+
+```toml
+[features]
+hooks = true
+
+[[hooks.PreToolUse]]
+matcher = "*"
+[[hooks.PreToolUse.hooks]]
+type = "command"
+command = "projmux ai ingest codex-hook >/dev/null 2>&1 || true"
+
+[[hooks.PermissionRequest]]
+matcher = "*"
+[[hooks.PermissionRequest.hooks]]
+type = "command"
+command = "projmux ai ingest codex-hook >/dev/null 2>&1 || true"
+
+[[hooks.PostToolUse]]
+matcher = "*"
+[[hooks.PostToolUse.hooks]]
+type = "command"
+command = "projmux ai ingest codex-hook >/dev/null 2>&1 || true"
+
+[[hooks.PreCompact]]
+matcher = "*"
+[[hooks.PreCompact.hooks]]
+type = "command"
+command = "projmux ai ingest codex-hook >/dev/null 2>&1 || true"
+
+[[hooks.PostCompact]]
+matcher = "*"
+[[hooks.PostCompact.hooks]]
+type = "command"
+command = "projmux ai ingest codex-hook >/dev/null 2>&1 || true"
+
+[[hooks.SessionStart]]
+matcher = "*"
+[[hooks.SessionStart.hooks]]
+type = "command"
+command = "projmux ai ingest codex-hook >/dev/null 2>&1 || true"
+
+[[hooks.UserPromptSubmit]]
+matcher = "*"
+[[hooks.UserPromptSubmit.hooks]]
+type = "command"
+command = "projmux ai ingest codex-hook >/dev/null 2>&1 || true"
+
+[[hooks.Stop]]
+matcher = "*"
+[[hooks.Stop.hooks]]
+type = "command"
+command = "projmux ai ingest codex-hook >/dev/null 2>&1 || true"
+```
+
+Codex hooks are the default integration mode. The hooks install is idempotent,
+preserves unrelated Codex config and unmanaged hook entries, and refuses to
+install over unmanaged projmux Codex hook commands it cannot safely own.
+`--remove` removes projmux-managed Codex hooks wiring. `--dry-run` prints the
+planned change without writing. Codex may still require reviewing or trusting
+the hook through its `/hooks` flow before commands run.
+
+`integrate tmux-bell` is opt-in server-level tmux wiring for arbitrary tools
+that emit BEL or OSC 9. It applies `allow-passthrough on`, `monitor-bell on`,
+`bell-action other`, and appends a marked `alert-bell` hook that invokes
+`projmux ai ingest bell --pane "#{pane_id}"`. `--dry-run` prints the tmux
+commands. tmux `alert-bell` is a window alert and does not expose
+`#{hook_pane}` on tmux 3.4, so `#{pane_id}` is the best available pane context.
+`--remove` unsets only hook entries carrying the projmux marker and leaves
+user-owned `alert-bell` hooks alone.
+
 ## tmux
 
 ```
@@ -381,6 +623,19 @@ to `~/.config/projmux/projdir`. npm-installed binaries reject this
 command; use `projmux update apply` or `npm update -g projmux` for npm
 installs.
 
+## welcome
+
+```
+projmux welcome
+```
+
+Prints the onboarding shell guide (`projmux shell` welcome view) without
+starting tmux. This is useful when you want to revisit the key/shortcut/update
+walkthrough at any time.
+
+Usage is argument-free. Passing positional arguments prints usage and returns a
+usage error.
+
 ## sessions / session-popup / preview / pin / kill / prune / tag
 
 The lifecycle helpers retained from earlier releases. They share their
@@ -404,21 +659,30 @@ flags with the top-level `switch` UX:
   by the shell jump binding).
 - `shell` — boot the isolated `-L projmux` tmux server with the
   generated config. The generated app config uses absolute `$SHELL` as the
-  tmux default shell when set, otherwise `/bin/sh`.
+  tmux default shell when set, otherwise `/bin/sh`. `shell` starts or attaches
+  the app session directly after resolving the target app session name and
+  startup directory. Alt-1 sidebar project open defaults to `Empty session`; the
+  Labs `Sidebar startup picker` opt-in shows `Latest snapshot`, `Named
+  snapshot`, and `Empty session` before creating a closed project session.
+  `Latest snapshot` is auto-saved; named snapshots are fixed until the user
+  saves or replaces them.
 - `attach auto [--keep=N] [--fallback=home|ephemeral]` — auto-attach to
   the most recent session, with bounded retention and a fallback policy.
 - `settings` — interactive configuration UI for the project picker, AI
-  splits, Appearance mode, Project Root management, the
-  switcher's saved workdirs list, Labs, and About/Update status. In Project
+  splits, Notifications, Appearance mode, Project Root management, the
+  switcher's saved workdirs list, Labs (experimental), Settings > Keybindings,
+  and About/Update status. The keybinding flow now lives under
+  `Settings > Keybindings` with `Bindings`, `Diagnostic`, `Probe`, and `Init`
+  chips, and includes the `Welcome` entry in About. In Project
   Picker, `Project Root` manages the saved
   primary root (`~/.config/projmux/projdir`) and displays whether the effective
   value comes from `PROJMUX_PROJDIR`, tmux `@projmux_projdir`, saved config, or
   no configured source. When no source is configured, the direct-set prompt
   starts with `$HOME` as an editable fallback, but `$HOME` is not used as the
   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 remains
+  additional search roots, not the primary root. Appearance stores per-surface
+  path/git/notify icon decoration as `off` (default), `symbol`, or `emoji` and
+  updates the matching 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
@@ -433,4 +697,4 @@ flags with the top-level `switch` UX:
 - [notify-queue.md](notify-queue.md) — queue file format and lifecycle.
 - [usage-tracking.md](usage-tracking.md) — adapter HTTP/file behaviour.
 - [keybindings.md](keybindings.md) — terminal key delivery and CSI-u.
-- [hooks.md](hooks.md) — `post-create` hook contract.
+- [hooks.md](hooks.md) — lifecycle hooks, startup commands, and `send-noti` payload contract.