projmux 0.4.4 → 0.4.6

package/docs/cli.md

@@ -0,0 +1,429 @@
+# CLI Reference
+
+Every subcommand exposed by the `projmux` binary as of v0.4.0. Run
+`projmux help` for the live top-level list, or `projmux <cmd> --help` /
+`projmux <cmd> help` for the per-command usage string.
+
+Exit codes:
+
+- `0` — success.
+- `1` — runtime failure.
+- `2` — usage error (unknown flag, bad enum, missing required flag) or a
+  deterministic semantic exit (e.g. `focus` cannot resolve the target).
+
+## Top-level
+
+```
+projmux <command> [args...]
+```
+
+| Command | Purpose |
+| --- | --- |
+| `ai` | Manage tmux AI splits (Codex/Claude) and per-pane status. |
+| `attention` | View and manage live tmux pane attention state. |
+| `attach` | Open tmux lifecycle entry helpers. |
+| `current` | Resolve the active tmux pane path. |
+| `doctor` | Diagnose runtime dependencies. |
+| `focus` | Switch the active client to a session/window/pane target. |
+| `init` | Apply supported terminal keybinding fallbacks. |
+| `kill` | Terminate tagged tmux sessions. |
+| `notify` | Manage the pending AI notify queue (push/list/ack/reconcile). |
+| `pin` | Manage pinned project directories. |
+| `preview` | Manage persisted tmux preview selection. |
+| `prune` | Trim stale tmux lifecycle state. |
+| `sessions` | Pick and open an existing tmux session. |
+| `session-popup` | Read tmux popup preview state. |
+| `settings` | Configure projmux. |
+| `setup` | Probe terminal key delivery for projmux bindings. |
+| `shell` | Open the isolated projmux tmux app. |
+| `status` | Render tmux status bar segments. |
+| `statusbar` | Dispatch projmux status bar clicks and shortcuts. |
+| `switch` | Pick and open a project tmux session. |
+| `tag` | Manage tagged tmux sessions. |
+| `tmux` | Open tmux popup entry helpers / install generated config. |
+| `update` | Check installer-aware GitHub release update status. |
+| `upgrade` | Self-update via `go install`. |
+| `usage` | Report AI token usage across 5h and weekly windows. |
+| `version` | Print the current version. |
+
+## switch
+
+```
+projmux switch [path]
+projmux switch toggle-tag | toggle-pin | kill | settings | preview
+projmux switch cycle-pane | cycle-window | sidebar-focus
+```
+
+Project picker. With no positional argument, opens the fzf-driven popup or
+sidebar (depending on entry helper). With a path, jumps directly. The
+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).
+
+`PROJMUX_PICKER_BACKEND=native` opts the switcher into the experimental native
+picker backend. fzf remains the default and the only backend with full preview
+pane, sidebar focus, and key-action parity. Native currently provides
+multiline card rendering, title-focused search, numeric selection, and the
+shared close-action contract.
+
+## setup
+
+```
+projmux setup [--timeout DURATION] [--non-interactive]
+```
+
+Probes which projmux key sequences (`Alt-1..5`, `Ctrl-N`, `Ctrl-Shift-{R,L,M}`,
+`Ctrl-M`, `Alt-Shift-{Left,Right}`) reach this process and which the
+terminal swallows. Reports `plain`, `csi-u`, `unknown`, or `timeout` for
+each. `--non-interactive` skips the TTY probe and prints the expected key
+map. Default `--timeout` is `5s`. Run it outside tmux after trying
+`projmux shell`; keys reported as `plain` or `csi-u` already work with zero
+terminal config.
+
+## init
+
+```
+projmux init [terminal] [--apply | --dry-run] [--config <path>]
+             [--allow-symlink]
+```
+
+Applies a terminal-specific fallback for shortcuts that `projmux setup`
+reports as swallowed. When `terminal` is omitted, autodetects from
+`$TERM_PROGRAM`/`$TERMINAL_EMULATOR`.
+Known terminals: `ghostty`, `windows-terminal`. Default is dry-run; pass
+`--apply` to write (timestamped `.bak.<timestamp>` is created). Refuses to
+write through a symlink unless `--allow-symlink` is passed (dotfiles repos).
+`--config <path>` overrides the candidate list when the adapter has more
+than one default location (Ghostty `config` vs `config.ghostty`). If setup
+shows every key arriving, skip init.
+
+## doctor
+
+```
+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.
+
+## focus
+
+```
+projmux focus --target SESSION[:WINDOW[.PANE]] [--socket <path>]
+              [--source ai|status-bar|external|os-notification]
+              [--kind reply-ready|busy-cleared|segment-click|custom]
+              [--json]
+```
+
+Unified switch-client dispatch. Resolves the session against the live tmux
+inventory (with prefix/fuzzy fallback), then redirects one suitable attached
+client on the selected socket. It never force-detaches other clients. If no
+client is attached on that socket, it emits the configured desktop
+notification instead. `--socket` is explicit; when omitted, the socket is
+derived from `$TMUX`.
+
+Exit codes:
+
+- `0` — focused (or the notify-only fallback fired).
+- `2` — target session could not be resolved (`focusExitNotResolved`).
+
+`--source`/`--kind` are telemetry labels logged when
+`PROJMUX_FOCUS_DEBUG` is set. `--json` prints a single-line JSON payload
+with `{ok, fallback, target, socket, resolved_session, client, dispatch,
+session_state, window_state, pane_state, reason, note}`. Callers can
+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`).
+
+## notify
+
+Pending AI notify queue. `attention` is live tmux pane state; `notify` is
+the explicit-ack pending notification source of truth used by the status-bar
+notify segment and notify sidebar. It is not the source of truth for all live pane attention. See
+[notify-queue.md](notify-queue.md) for the full data model.
+
+```
+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]
+                     [--severity ...] [--source ...]
+projmux notify ack   <id> | --all
+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).
+- `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
+  compares queued entries with live pane attention. It calls out manual
+  reply badges that do not queue because no AI agent is attached, live AI
+  reply panes missing a queue entry, matched AI reply entries, and stale
+  queue entries whose live pane no longer matches. `--ui=sidebar` opens the
+  compact interactive notify list where Enter focuses and acks a target, `a`
+  acks the selected row, and `Ctrl-A` 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, while keeping ids,
+  source, severity, and target details searchable.
+- `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
+  set, reporting stale `ai:` entries that no longer match a live pane without
+  acking them.
+  Soft-fails (no error, populated `errors` field in the summary) when
+  tmux is not running. Use this as the recovery path when the queue and
+  live pane state drift.
+
+## usage
+
+Authoritative AI token usage. See [usage-tracking.md](usage-tracking.md)
+for adapter detail.
+
+```
+projmux usage [--model codex|claude|all] [--window 5h|weekly|all]
+              [--json] [--force|-f]
+```
+
+Renders a tab-aligned `MODEL WINDOW PCT RESETS_AT STALE` table; appends a
+backoff note when an adapter is in 429 cooldown. `--force` clears any
+active backoff and bypasses the per-adapter throttle floor (Claude `5m`,
+Codex shares the global `30s`). `--json` emits the snapshot array; when
+backoff is active the wrapper `{snapshots, backoff}` object is emitted
+instead.
+
+## status
+
+Per-segment status-bar renderers. All four are silent on failure — the
+tmux status interval polls them and must never produce a stack trace.
+
+```
+projmux status git    [path]
+projmux status kube   [session]
+projmux status usage  [--max-width N] [--force|-f]
+projmux status notify [--max-width N]
+```
+
+- `git` — `#[bold,fg=colour16,bg=colour45] <branch> #[default]` for the
+  pane's `pane_current_path` (or the supplied path). Empty when not in a
+  repo.
+- `kube` — `⎈ <context>/<namespace>` segment. Reads
+  `~/.cache/tmux/kube-segment-<session>.txt` first (TTL governed by
+  `TMUX_KUBE_CACHE_TTL`, default `5s`). Picks up a per-session
+  `KUBECONFIG` from `${XDG_RUNTIME_DIR:-~/.cache}/kube-sessions/<session>.yaml`.
+- `usage` — HUD-style `Claude (Nm) 5h [bar] N% · weekly [bar] N%   Codex 5h
+  [bar] N% · weekly [bar] N%`. Degrades through six tiers as `--max-width`
+  shrinks. Triggers an opportunistic, throttled refresh (per-adapter
+  throttle, `30s` floor) so a stale cache self-heals.
+- `notify` — newest-first HUD block with project, state, optional agent, text,
+  age, and `+<extras>`. Window/pane ids remain routable metadata but are not
+  displayed in the compact HUD. Degrades through width tiers; default
+  `--max-width` is `200` runes.
+
+## statusbar
+
+```
+projmux statusbar click <range-id> [--socket <s>] [--mouse-window <id>]
+                                   [--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` /
+`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.
+`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).
+
+## attention
+
+```
+projmux attention toggle [pane]
+projmux attention clear  [pane]
+projmux attention arm    [pane]
+projmux attention list   [--json] [--all]
+projmux attention window [window]
+```
+
+Toggles the `✳` pane title prefix and the `@projmux_attention_state` pane
+option. `toggle` flips between cleared and `reply`; `clear` always
+clears; `arm` sets a pre-reply armed state used by the AI flow. The
+producer side pushes the matching entry into the notify queue when the pane
+has an associated AI agent option; clearing attention does not ack the queue
+row (manual toggles on shell panes do not push). `list` reads `tmux list-panes -a` and shows live pane
+attention state without reading or mutating the notify queue; by default
+it shows panes with an attention option or title marker, and `--all`
+includes every pane. `window` renders the status-bar window badge for the
+supplied window.
+
+## ai
+
+```
+projmux ai split    --inside <right|down> [--agent <name>] ...
+projmux ai picker   --inside <right|down>
+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 topic     ...
+```
+
+Manages the AI split lifecycle and the per-pane state machine that drives
+the `attention` badge, the `notify` queue producer, and the desktop
+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.
+
+## tmux
+
+```
+projmux tmux popup-toggle <mode>
+projmux tmux popup-switch
+projmux tmux popup-sessions
+projmux tmux popup-preview <session>
+projmux tmux rebalance-panes
+projmux tmux rename-pane <pane> <title>
+projmux tmux print-config     [--bin <path>]
+projmux tmux print-app-config [--bin <path>]
+projmux tmux install     [--bin <path>] [--config <path>] [--include <path>]
+projmux tmux install-app [--bin <path>] [--config <path>]
+projmux tmux apply
+```
+
+Helpers tmux's keybindings and the install pipeline call into. Modes
+accepted by `popup-toggle` mirror the historical sessionizer surface:
+`session-popup`, `sessionizer`, `sessionizer-sidebar`,
+`ai-split-picker-right`, `ai-split-picker-down`, `ai-split-settings`.
+`apply` reloads the live `-L projmux` server's config without restarting
+it; `make install` and `projmux upgrade` invoke it after replacing the
+binary.
+
+## update
+
+```
+projmux update status [--json]
+projmux update check  [--json]
+projmux update apply  [--dry-run] [--no-apply]
+```
+
+Installer-aware update status foundation. `status` is read-only: it
+prints the current version, cached latest GitHub Release tag when present,
+cache freshness (`fresh`, `stale`, or `unknown`), update state, detected
+installer source, and cache path. It never reaches the network, so it is
+safe for interactive use and shell startup paths.
+
+`check` fetches the latest GitHub Release metadata for
+`crevissepartners/projmux`, atomically writes
+`${XDG_CACHE_HOME:-~/.cache}/projmux/update.json`, then prints the concise
+latest/update/cache result. `--json` emits the same machine-readable
+status shape for both subcommands.
+
+`projmux shell` reads the same cache before opening the isolated tmux app.
+When the cache is fresh, an update is available, and the installer supports
+`update apply`, shell startup shows a small picker with Update Now, Later,
+and Skip This Version actions. This startup prompt never reaches the network;
+run `projmux update check` first when you want it to see the newest release.
+
+Installer detection honors
+`PROJMUX_INSTALLER=npm|go|github-release|source`. When unset or invalid,
+the source is reported as `unknown` with guidance to set the variable.
+`apply` is installer-aware and only runs after explicit user selection.
+For npm installs, it runs `npm update -g projmux` and then
+`projmux tmux apply` unless `--no-apply` is set. For Go installs, it
+delegates to the existing atomic `projmux upgrade` flow. For
+`github-release` installs, it downloads the latest matching
+`projmux_<version>_<goos>_<goarch>.tar.gz` release asset, extracts the
+binary, atomically replaces the current executable, then applies tmux
+configuration unless `--no-apply` is set. `source` installs report an
+actionable error because they must be updated from the source checkout.
+
+## upgrade
+
+```
+projmux upgrade [--ref @latest|@<tag>|@<branch>]
+                [--target <path>] [--no-apply] [--dry-run]
+```
+
+`go install`s the binary, atomically replaces the on-disk file, then
+runs `projmux tmux apply` (skipped with `--no-apply`). Reads
+`PROJMUX_PROJDIR` from the calling shell and memoizes the primary entry
+to `~/.config/projmux/projdir`. npm-installed binaries reject this
+command; use `projmux update apply` or `npm update -g projmux` for npm
+installs.
+
+## sessions / session-popup / preview / pin / kill / prune / tag
+
+The lifecycle helpers retained from earlier releases. They share their
+flags with the top-level `switch` UX:
+
+- `sessions` — list/pick existing tmux sessions, supports `--ui=popup`.
+- `session-popup` — read/write the popup-marker state used during
+  preview cycling.
+- `preview` — manage the persisted window/pane preview selection.
+- `pin add|remove|toggle|list|clear` — pin set CRUD, persisted under
+  `~/.config/projmux/pins`.
+- `kill <session>` / `kill tagged` — terminate sessions; `tagged`
+  consumes the active tagged-selection set.
+- `prune ephemeral` — drop ephemeral sessions older than the configured
+  retention window.
+- `tag` — manage the tagged-selection set.
+
+## current / shell / attach / settings
+
+- `current` — print `pane_current_path` for the active tmux pane (used
+  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`.
+- `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, Status Bar cwd/git decoration, Project Root management, the
+  switcher's saved workdirs list, and About/Update status. 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. Status Bar stores
+  `~/.config/projmux/statusbar-decoration` as `off` (default), `symbol`, or
+  `emoji` and updates the live tmux option when available. 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
+  supported terminal fallbacks, and `doctor` for dependencies.
+
+## See also
+
+- [npm-distribution.md](npm-distribution.md) — npm binary package layout.
+- [statusbar.md](statusbar.md) — two-line layout and click range catalogue.
+- [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.

package/docs/configuration.md

@@ -0,0 +1,127 @@
+# Configuration
+
+Most users can configure projmux from `projmux settings`. Environment variables
+are available for repeatable shell setup, managed machines, or advanced
+overrides.
+
+## Project Discovery
+
+`projmux switch` combines pinned directories, live tmux sessions, and
+discovered project roots.
+
+When no explicit roots are configured, discovery uses weak probes only when
+those folders exist:
+
+- `~/source`
+- `~/work`
+- `~/projects`
+- `~/src`
+- `~/code`
+
+It does not assume a canonical repo root.
+
+Use Settings > Project Picker for the normal interactive flow:
+
+- `Project Root` sets, changes, or clears the saved primary root.
+- `+ Add Workdir...` appends one directory to the saved workdirs list.
+- `Workdirs` reviews and removes saved workdirs.
+
+`Add Workdir > Type path manually...` skips the filesystem scan and is useful
+for large mounts, WSL paths, NFS paths, or temporary project roots.
+
+The saved workdir file is:
+
+```text
+~/.config/projmux/workdirs
+```
+
+It stores one absolute path per line. Lines beginning with `#` are comments.
+The file is read only when no env root list is set.
+
+## Environment Variables
+
+| Variable | Purpose |
+| --- | --- |
+| `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_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_FOCUS_DEBUG` | When non-empty, `projmux focus` prints one telemetry line to stderr. |
+| `PROJMUX_PICKER_BACKEND` | Set to `native` to opt into the experimental native picker backend. `fzf` remains the default and stable backend. |
+| `PROJMUX_INSTALLER` | Installer source hint used by update flows. npm installs set this automatically; advanced release installs can set `github-release`. |
+
+Example:
+
+```sh
+export PROJMUX_PROJDIR="/main/repos:/srv/work/repos"
+```
+
+On Linux and macOS the separator is `:`. On Windows-style paths the separator
+is `;`.
+
+## tmux Project Root Option
+
+The switch command also reads this tmux option:
+
+```tmux
+set-option -g @projmux_projdir /path/to/repos
+```
+
+An env `PROJMUX_PROJDIR` value takes priority over the tmux option. The tmux
+option takes priority over the saved projdir file.
+
+## Notifications
+
+When `PROJMUX_NOTIFY_HOOK` is unset, projmux uses:
+
+- `notify-send` on Linux.
+- PowerShell toasts on WSL.
+
+When the hook is set, projmux invokes it with positional arguments:
+
+```text
+summary body urgency app-name tag group icon-path
+```
+
+Hook details for new-session lifecycle hooks live in [Hooks](hooks.md).
+
+## Usage Tracking
+
+`projmux usage` and the status-bar usage segment store snapshots under:
+
+```text
+${PROJMUX_USAGE_STATE_DIR:-${XDG_STATE_HOME:-$HOME/.local/state}/projmux/usage}/snapshots.json
+```
+
+See [Usage tracking](usage-tracking.md) for adapter behavior, throttling, and
+failure handling.
+
+## Status Bar Decoration
+
+Settings > Status Bar controls the optional cwd/git leading decoration:
+
+- `off` is the default and avoids icon-font assumptions.
+- `symbol` restores the Nerd Font-style folder/git icons.
+- `emoji` uses emoji decorators.
+
+The saved value lives at:
+
+```text
+~/.config/projmux/statusbar-decoration
+```
+
+## Rare Tunables
+
+These are intended for debugging or local policy, not routine setup:
+
+| Variable | Purpose |
+| --- | --- |
+| `PROJMUX_TMUX_NOTIFY_DEDUPE_SECONDS` | Collapse window for duplicate AI notifications keyed on `(summary, tag)`. |
+| `PROJMUX_CODEX_TITLE_WATCH_INTERVAL` | Title-watch loop pacing for Codex panes. |
+| `PROJMUX_CODEX_REPLY_SETTLE_LOOPS` | Reply-detection settle-loop pacing for Codex panes. |
+| `TMUX_KUBE_CACHE_TTL` | Kubernetes status segment cache TTL. |
+| `TMUX_KUBE_TIMEOUT` | kubectl invocation budget for the Kubernetes status segment. |

package/docs/hooks.md

@@ -0,0 +1,118 @@
+# 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.
+
+## Where it lives
+
+Global hook:
+
+```text
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/hooks/post-create
+```
+
+Project-local hooks, discovered from the new session's `PROJMUX_CWD`:
+
+```text
+<repo>/.projmux/post-create
+<repo>/.projmux/hooks/post-create
+```
+
+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.
+
+```sh
+mkdir -p ~/.config/projmux/hooks
+chmod +x ~/.config/projmux/hooks/post-create
+```
+
+For project-local hooks, projmux runs at most one file: first
+`.projmux/post-create` if executable, otherwise `.projmux/hooks/post-create` if
+executable. Discovery does not walk parent directories and does not run hooks
+from status, preview, or picker hot paths.
+
+## When it runs
+
+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.
+
+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.
+
+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.
+
+## Environment
+
+The hook inherits 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_VERSION` | yes | projmux version string |
+| `PROJMUX_SOCKET` | only if projmux used `tmux -L <socket>` | tmux socket name |
+
+## Examples
+
+### Global stub
+
+```bash
+#!/usr/bin/env bash
+echo "session=$PROJMUX_SESSION cwd=$PROJMUX_CWD kind=$PROJMUX_SESSION_KIND"
+```
+
+### Project-local stub
+
+```bash
+mkdir -p .projmux
+cat > .projmux/post-create <<'EOF'
+#!/usr/bin/env bash
+echo "project hook for $PROJMUX_CWD"
+EOF
+chmod +x .projmux/post-create
+```
+
+### Per-session GH_TOKEN by repo
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+case "$PROJMUX_CWD" in
+  "$HOME"/source/repos/personal/*)  token=$GH_TOKEN_PERSONAL ;;
+  "$HOME"/source/repos/work/*)      token=$GH_TOKEN_WORK ;;
+  *) exit 0 ;;
+esac
+
+tmux set-environment -t "$PROJMUX_SESSION" GH_TOKEN "$token"
+```
+
+`set-environment` only seeds the session env that newly-spawned panes inherit;
+it does not retroactively change the current shell. Open new panes via tmux
+(`Ctrl-b c`, `Ctrl-b "`, etc.) to pick up the value.
+
+## 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
+  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.