projmux 0.10.0 → 0.11.0

package/docs/hooks.md

@@ -3,8 +3,7 @@
 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.
+tokens, kicking off a background sync, or sending an initial pane command.
 
 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.
@@ -16,7 +15,7 @@ projmux-owned internal tmux hooks such as `pane-focus-in`, `pane-focus-out`,
 | `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] ` |
 | `post-attach` | After projmux switches the current tmux client to an existing session/target from inside tmux | Logged and ignored | Logged with `[post-attach] ` |
-| `send-noti` | After `projmux notify push` (or the in-process AI notify producer) successfully writes a queue entry | Fired asynchronously and best-effort; queue write and desktop notifications continue even if the hook fails or times out | Receives JSON on stdin; stdout/stderr are logged with `[send-noti] ` |
+| `send-noti` | After `projmux create notification` (or the in-process AI notify producer) successfully writes a queue entry | Fired asynchronously and best-effort; queue write and desktop notifications continue even if the hook fails or times out | Receives JSON on stdin; stdout/stderr are logged with `[send-noti] ` |
 
 Deferred Phase A candidates remain future work until their behavior can be
 specified without exposing projmux's internal tmux hook machinery: pane exit,
@@ -66,10 +65,6 @@ run = "jq -r '.message' | xargs -I{} send-slack \"{}\""
 
 [env]
 FOO = "bar"
-
-[kube]
-context = "dev-cluster"
-namespace = "tools"
 ```
 
 Only quoted string values are supported. Unknown sections or keys make the
@@ -100,10 +95,22 @@ 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.
+### Removed `[kube]` input
+
+The former `[kube]` section is no longer a product or runtime feature. projmux
+does not project Kube-specific hook/session variables and does not rewrite a
+legacy file. If a config still contains `[kube]`, every config write stops
+before changing the file and reports this exact diagnostic:
+
+```text
+legacy [kube] support was removed; manually move context to [env] KUBE_CONTEXT and namespace to [env] KUBE_NAMESPACE, then remove [kube]; original config was not changed
+```
+
+Migration is deliberately manual: copy the former `context` value to an
+explicit `KUBE_CONTEXT` key under generic `[env]`, and the former `namespace`
+value to `KUBE_NAMESPACE`, then remove `[kube]`. Those names are examples, not
+special fields—`[env]` preserves any valid user-supplied key verbatim and no
+`PROJMUX_KUBE_*` variable is synthesized.
 
 ## Trust Model
 
@@ -165,7 +172,7 @@ the notification or block the normal desktop notification flow.
 
 The hook runs asynchronously with the same default timeout (`5s`) as other
 hooks. projmux does not wait for completion before returning from
-`projmux notify push`.
+`projmux create notification`.
 
 stdin receives one JSON object:
 
@@ -201,15 +208,15 @@ The hook environment also includes:
 | `PROJMUX_NOTIFY_MESSAGE` | Human-readable message text |
 | `PROJMUX_NOTIFY_HOOK_DEPTH` | Recursion guard; values `>= 1` suppress nested `send-noti` dispatch |
 
-If a `send-noti` hook itself calls `projmux notify push`, projmux sees
+If a `send-noti` hook itself calls `projmux create notification`, projmux sees
 `PROJMUX_NOTIFY_HOOK_DEPTH=1` in the child environment and skips another
 `send-noti` hook fire. The queue write itself still succeeds.
 
-`Settings > Notifications > Delivery sources` surfaces the active Codex hooks,
-Claude, and tmux AI notify diagnostics: status, conflicts, config paths, and
-copyable CLI install/remove/dry-run commands. It also shows whether
+`Settings > Notifications > Delivery sources` surfaces the active Codex,
+Claude, Antigravity, and tmux AI notify diagnostics: status, conflicts, config
+paths, and copyable CLI install/remove/dry-run commands. It also shows whether
 `PROJMUX_NOTIFY_HOOK` overrides the built-in desktop sender. It does not install
-or remove external Codex, Claude, or tmux settings.
+or remove external Codex, Claude, Antigravity, or tmux settings.
 
 `PROJMUX_NOTIFY_HOOK` is separate from `[hooks.send-noti]`: it replaces the
 desktop sender and receives positional arguments
@@ -226,9 +233,9 @@ severity, and permission/input status badges do not use red.
 
 `projmux doctor` reports Codex hooks-engine wiring separately from legacy
 notify, including unmanaged hooks/conflict details and the relevant
-`projmux ai integrate codex` commands.
+`projmux agent integrate codex` commands.
 
-`projmux ai ingest codex-hook` is the conservative core ingest path for Codex
+`projmux internal agent-hook ingest codex-hook` is the conservative core ingest path for Codex
 hooks-engine events. It reads a single JSON payload from stdin. The embedded
 default install catalog is based on Codex CLI 0.130.0:
 
@@ -250,7 +257,7 @@ Codex hook payload parsing accepts the common fields
 and falls back to treating `session_id` as the thread identity so existing
 `matchAIPane` matching can reuse cached pane metadata.
 
-`projmux ai integrate codex` manages a separate
+`projmux agent integrate codex` manages a separate
 `~/.codex/config.toml` marker block for the hooks engine. If a `[features]`
 table already exists, projmux merges `hooks = true` into that table instead of
 creating a duplicate table. Older projmux-managed `codex_hooks = true` entries
@@ -264,54 +271,54 @@ hooks = true
 matcher = "*"
 [[hooks.PreToolUse.hooks]]
 type = "command"
-command = "projmux ai ingest codex-hook >/dev/null 2>&1 || true"
+command = "projmux internal agent-hook 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"
+command = "projmux internal agent-hook 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"
+command = "projmux internal agent-hook 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"
+command = "projmux internal agent-hook 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"
+command = "projmux internal agent-hook 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"
+command = "projmux internal agent-hook 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"
+command = "projmux internal agent-hook 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"
+command = "projmux internal agent-hook ingest codex-hook >/dev/null 2>&1 || true"
 ```
 
 Repeated installs are idempotent and preserve unrelated Codex config, including
 unmanaged hook entries for the same events. If projmux sees an unmanaged
-`projmux ai ingest codex-hook` command, it refuses to install over it rather
+`projmux internal agent-hook ingest codex-hook` command, it refuses to install over it rather
 than guessing ownership. `--dry-run` previews the TOML update. `--remove`
 removes projmux-managed Codex hooks wiring.
 
@@ -354,9 +361,9 @@ Runtime action overrides are stored separately from the install catalog at:
 ${XDG_CONFIG_HOME:-$HOME/.config}/projmux/ai-hook-actions.json
 ```
 
-`Settings > Notifications > Hook quiet policy` reads and writes that file. The
+`Settings > Notifications > Agent event behavior` reads and writes that file. The
 runtime file only changes ingest behavior (`notify`, `state`, or `quiet`);
-`projmux ai integrate codex` still uses the catalog `install` field to decide
+`projmux agent integrate codex` still uses the catalog `install` field to decide
 which hooks to write. Runtime overrides also apply to known specialized
 events, so `Stop` or `PermissionRequest` can be made state-only or quiet
 without changing which hook commands are installed. When a known Codex event
@@ -379,7 +386,7 @@ to auto-trust hooks.
 projmux-managed bell hook installed. The diagnostic is read-only; it only
 inspects current `alert-bell` hooks and prints the matching integrate commands.
 
-`projmux ai integrate tmux-bell` is the opt-in fallback for AI CLIs that do
+`projmux agent integrate tmux-bell` is the opt-in fallback for AI CLIs that do
 not expose structured hooks but do emit BEL or OSC 9. It mutates the current
 tmux server only; it does not edit tmux config files. Install applies these
 server settings and appends a marked `alert-bell` hook:
@@ -388,10 +395,10 @@ server settings and appends a marked `alert-bell` hook:
 tmux set-option -g allow-passthrough on
 tmux set-option -g monitor-bell on
 tmux set-option -g bell-action other
-tmux set-hook -ag alert-bell run-shell -b 'projmux ai ingest bell --pane "#{pane_id}" >/dev/null 2>&1 || true # projmux-managed:tmux-bell:v1'
+tmux set-hook -ag alert-bell run-shell -b 'projmux internal agent-hook ingest bell --pane "#{pane_id}" >/dev/null 2>&1 || true # projmux-managed:tmux-bell:v1'
 ```
 
-The hook calls `projmux ai ingest bell --pane <pane_id>`. Bell ingest resolves
+The hook calls `projmux internal agent-hook ingest bell --pane <pane_id>`. Bell ingest resolves
 the target pane through tmux and pushes an info notify queue row such as
 `bell · Claude CLI`, with metadata including `agent=bell`, `event=bell`,
 session/window/pane, pane title, command, and socket path when available. The
@@ -413,9 +420,9 @@ the current `alert-bell` hooks and unsets only entries carrying
 
 `projmux doctor` reports Claude Code hook wiring in `~/.claude/settings.json`,
 including unmanaged projmux ingest command conflicts and the relevant
-`projmux ai integrate claude` commands.
+`projmux agent integrate claude` commands.
 
-`projmux ai ingest claude-hook` is the conservative core ingest path for
+`projmux internal agent-hook ingest claude-hook` is the conservative core ingest path for
 Claude Code hooks. It reads a single JSON payload from stdin. The embedded
 default install catalog is based on Claude Code 2.1.140 and represents the
 29 hook events visible in that version:
@@ -456,14 +463,14 @@ Hook-generated queue rows use the same compact body catalog: agent label,
 event category, then the best available summary (Codex assistant text, Claude
 tool/action summary, transcript summary, error, or teammate labels). Structured
 payload details remain in `metadata`, which is passed through the `send-noti`
-JSON payload and `notify list --json`; the sidebar stays compact and does not
+JSON payload and `get notifications --json`; the sidebar stays compact and does not
 expand a separate metadata detail view. `SubagentStop` remains parsed for
 diagnostics but is intentionally excluded from hook notifications because it can
 fire at high volume.
 
 Pane matching follows the shared AI ingest order: inherited `$TMUX_PANE`, then
 payload `cwd`, then cached session id pane options. A matched pane is marked
-with `@projmux_ai_hook_active=1`, so `projmux ai watch-title` skips the pane
+with `@projmux_ai_hook_active=1`, so `projmux internal agent-hook watch-title` skips the pane
 after a minimal hook-active gate instead of polling pane title/capture output;
 hook payloads become the primary signal. The tmux bell fallback does not mark
 panes hook-active, so title/capture fallback remains available for panes that
@@ -481,7 +488,7 @@ upstream schemas settle:
 | `SubagentStop` | `subagent_type`, `subagentType`, `agent_type`, `agentType`; `subagent_id`, `subagentId`, `agent_id`, `agentId`; nested `subagent.type`, `subagent.name`, `subagent.kind`, `subagent.id`, `subagent.subagent_id`, `subagent.agent_id` |
 | `TeammateIdle` | `teammate_name`, `teammateName`, `teammate`; `teammate_id`, `teammateId`; `teammate_context`, `teammateContext`, `context`, `reason`, `message`; nested `teammate.name`, `teammate.type`, `teammate.kind`, `teammate.id`, `teammate.teammate_id`, `teammate.context`, `teammate.status`, `teammate.reason`, `teammate.message` |
 
-`projmux ai integrate claude` manages user-level Claude Code hook settings in
+`projmux agent integrate claude` manages user-level Claude Code hook settings in
 `~/.claude/settings.json`. Claude Code hooks are configured under the top-level
 `hooks` object, with each event containing matcher entries and each matcher
 entry containing a `hooks` array. Projmux omits `matcher`, which Claude Code
@@ -497,7 +504,7 @@ an observability hook:
         "hooks": [
           {
             "type": "command",
-            "command": "projmux ai ingest claude-hook >/dev/null 2>&1 || true # projmux-managed:claude-hook:v1"
+            "command": "projmux internal agent-hook ingest claude-hook >/dev/null 2>&1 || true # projmux-managed:claude-hook:v1"
           }
         ]
       }
@@ -507,7 +514,7 @@ an observability hook:
         "hooks": [
           {
             "type": "command",
-            "command": "projmux ai ingest claude-hook >/dev/null 2>&1 || true # projmux-managed:claude-hook:v1"
+            "command": "projmux internal agent-hook ingest claude-hook >/dev/null 2>&1 || true # projmux-managed:claude-hook:v1"
           }
         ]
       }
@@ -517,7 +524,7 @@ an observability hook:
         "hooks": [
           {
             "type": "command",
-            "command": "projmux ai ingest claude-hook >/dev/null 2>&1 || true # projmux-managed:claude-hook:v1"
+            "command": "projmux internal agent-hook ingest claude-hook >/dev/null 2>&1 || true # projmux-managed:claude-hook:v1"
           }
         ]
       }
@@ -527,7 +534,7 @@ an observability hook:
         "hooks": [
           {
             "type": "command",
-            "command": "projmux ai ingest claude-hook >/dev/null 2>&1 || true # projmux-managed:claude-hook:v1"
+            "command": "projmux internal agent-hook ingest claude-hook >/dev/null 2>&1 || true # projmux-managed:claude-hook:v1"
           }
         ]
       }
@@ -537,7 +544,7 @@ an observability hook:
         "hooks": [
           {
             "type": "command",
-            "command": "projmux ai ingest claude-hook >/dev/null 2>&1 || true # projmux-managed:claude-hook:v1"
+            "command": "projmux internal agent-hook ingest claude-hook >/dev/null 2>&1 || true # projmux-managed:claude-hook:v1"
           }
         ]
       }
@@ -547,7 +554,7 @@ an observability hook:
         "hooks": [
           {
             "type": "command",
-            "command": "projmux ai ingest claude-hook >/dev/null 2>&1 || true # projmux-managed:claude-hook:v1"
+            "command": "projmux internal agent-hook ingest claude-hook >/dev/null 2>&1 || true # projmux-managed:claude-hook:v1"
           }
         ]
       }
@@ -557,7 +564,7 @@ an observability hook:
         "hooks": [
           {
             "type": "command",
-            "command": "projmux ai ingest claude-hook >/dev/null 2>&1 || true # projmux-managed:claude-hook:v1"
+            "command": "projmux internal agent-hook ingest claude-hook >/dev/null 2>&1 || true # projmux-managed:claude-hook:v1"
           }
         ]
       }
@@ -572,7 +579,7 @@ and re-adds the current managed command while preserving unrelated settings and
 hooks. `--remove` deletes only marked commands, and `--dry-run` previews the
 JSON without writing. Removal and unmanaged conflict detection scan every event
 under the settings `hooks` object, not just the current catalog. If any event
-already has an unmanaged command that invokes `projmux ai ingest claude-hook`,
+already has an unmanaged command that invokes `projmux internal agent-hook ingest claude-hook`,
 projmux refuses to install over it because it cannot tell whether the command
 is user-owned or stale projmux wiring.
 
@@ -612,17 +619,17 @@ that fallback; catalog `"notify"` and `"state"` entries still need built-in
 handler code for event-specific queue rows or state transitions. Runtime action
 overrides live in the same
 `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/ai-hook-actions.json` file used by
-Codex and are managed from `Settings > Notifications > Hook quiet policy`.
-They only affect ingest delivery; `projmux ai integrate claude` still uses the
+Codex and are managed from `Settings > Notifications > Agent event behavior`.
+They only affect ingest delivery; `projmux agent integrate claude` still uses the
 catalog `install` field for installed hook events.
 
 ## Antigravity Hook Ingest
 
-`projmux ai ingest antigravity-hook --event <event> < payload.json` accepts
+`projmux internal agent-hook ingest antigravity-hook --event <event> < payload.json` accepts
 Antigravity CLI `agy` hook payloads. Antigravity v1.1.12 stdin does
 not include the event name, so the command's `--event` value is authoritative.
 Payload event aliases remain a compatibility fallback when `--event` is
-omitted. `projmux ai integrate antigravity [--dry-run|--remove]` owns exactly
+omitted. `projmux agent integrate antigravity [--dry-run|--remove]` owns exactly
 the named `projmux` entry in `~/.gemini/config/hooks.json` and separately owns
 only `statusLine` in `~/.gemini/antigravity-cli/settings.json`. Other named hooks,
 their fields, and unknown JSON values remain untouched. The generated commands
@@ -694,7 +701,7 @@ reinterpreting context. Raw payloads or transcript contents are not stored.
 
 ## Ingest Debug Log
 
-Every `projmux ai ingest ...` path appends compact JSONL diagnostics to
+Every `projmux internal agent-hook ingest ...` path appends compact JSONL diagnostics to
 `$XDG_STATE_HOME/projmux/ai-ingest.log`, or
 `~/.local/state/projmux/ai-ingest.log` when `XDG_STATE_HOME` is unset. The log
 records source, event, result, pane, match identifiers, and a short reason for
@@ -702,14 +709,17 @@ 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.
 
-Use `projmux ai ingest log` to inspect recent entries:
+Use `projmux diagnostics agent-hook` to inspect recent entries:
 
 ```text
-projmux ai ingest log --tail 20
-projmux ai ingest log --json --tail 20
-projmux ai ingest log --path
+projmux diagnostics agent-hook --tail 20
+projmux diagnostics agent-hook --json --tail 20
+projmux diagnostics agent-hook --path
 ```
 
+The human legacy ingest-log reader has been removed. Use
+`projmux diagnostics agent-hook`; it reads the same bytes.
+
 The file is capped at 1 MiB. When an append grows it past the cap, projmux
 keeps the most recent roughly 512 KiB and trims from the next JSONL boundary so
 the remaining file still starts at a whole entry.
@@ -731,16 +741,28 @@ projmux does not run `post-attach` for outside-tmux attach paths in this phase.
 
 ## Environment
 
-Hooks inherit projmux's environment, plus:
-
-| Variable | Always set | Description |
-| --- | --- | --- |
-| `PROJMUX_SESSION` | yes | tmux session name |
-| `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` |
+Hooks inherit projmux's environment. The lifecycle variables below are added by
+event; “omitted” means the variable is not added when its context value is
+empty.
+
+| Variable | `pre-create` | `post-create` | `post-attach` | `send-noti` |
+| --- | --- | --- | --- | --- |
+| `PROJMUX_SESSION` | new session name | new session name | target session name | target session when known; otherwise empty |
+| `PROJMUX_CWD` | requested session directory | created session directory | resolved target directory; may be empty if lookup fails | dispatcher working directory |
+| `PROJMUX_SESSION_KIND` | `persistent` or `ephemeral` | `persistent` or `ephemeral` | empty | empty |
+| `PROJMUX_VERSION` | projmux version | projmux version | projmux version | projmux version |
+| `PROJMUX_SOCKET` | app socket metadata (`projmux`) | app socket metadata (`projmux`) | app socket metadata (`projmux`) | queue-entry socket when known; otherwise omitted |
+| `PROJMUX_PANE` | omitted: no pane exists yet | exact id returned by standard persistent/ephemeral `tmux new-session`, such as `%7`; omitted for snapshot replay | omitted | target pane when known; otherwise omitted |
+
+`pre-create` intentionally has no `PROJMUX_PANE`: it runs before
+`tmux new-session` creates the first pane. Standard persistent and ephemeral
+`post-create` paths run after creation and therefore receive that exact pane
+id. Snapshot replay can restore multiple panes and does not expose a single
+returned pane at its lifecycle boundary, so it omits `PROJMUX_PANE`.
+`PROJMUX_SOCKET` is routing metadata for hook commands; it does not imply that
+the tmux client itself adds `-L` to its commands. The `post-attach` and
+`send-noti` cells describe their existing contexts; this contract adds no pane
+context to either event.
 
 ## Examples
 
@@ -749,6 +771,7 @@ Hooks inherit projmux's environment, plus:
 ```bash
 #!/usr/bin/env bash
 echo "session=$PROJMUX_SESSION cwd=$PROJMUX_CWD kind=$PROJMUX_SESSION_KIND"
+tmux -L "$PROJMUX_SOCKET" set-option -p -t "$PROJMUX_PANE" @projmux_initialized 1
 ```
 
 ### Project Startup Command
@@ -770,7 +793,7 @@ case "$PROJMUX_CWD" in
   *) exit 0 ;;
 esac
 
-tmux set-environment -t "$PROJMUX_SESSION" GH_TOKEN "$token"
+tmux -L "$PROJMUX_SOCKET" set-environment -t "$PROJMUX_SESSION" GH_TOKEN "$token"
 ```
 
 `set-environment` only seeds the session env that newly-spawned panes inherit;

package/docs/install.md

@@ -21,6 +21,19 @@ projmux doctor
 `doctor` performs read-only diagnostics for runtime tools such as `tmux`,
 `git`, and `stty`.
 
+Provider integrations are opt-in and use the canonical installer spelling:
+
+```sh
+projmux agent integrate codex
+projmux agent integrate claude
+projmux agent integrate antigravity
+projmux agent integrate tmux-bell
+```
+
+These installers write managed producers that call
+`projmux internal agent-hook ingest ...`. Existing markerless hooks remain
+user-owned and are never rewritten.
+
 Start the tmux app with:
 
 ```sh
@@ -52,7 +65,6 @@ Normal use needs:
 Useful optional tools:
 
 - `git` for branch/status metadata.
-- `kubectl` for the Kubernetes status segment.
 - `notify-send` on Linux, or `powershell.exe` under WSL, for built-in desktop
   notifications.
 
@@ -71,7 +83,7 @@ directory is on `PATH`.
 Go-managed installs can update through:
 
 ```sh
-projmux upgrade
+projmux update apply
 ```
 
 See [Upgrading](upgrading.md) for version pinning and installer-specific
@@ -89,8 +101,9 @@ make install
 ```
 
 `make install` builds the binary, atomically replaces
-`$(go env GOPATH)/bin/projmux`, runs `projmux tmux apply`, and reconciles the
-notify queue. Override the destination with `INSTALL_DIR=/usr/local/bin`.
+`$(go env GOPATH)/bin/projmux`, runs `projmux config apply`, and reconciles the
+notify queue through `projmux notification reconcile`. Override the destination
+with `INSTALL_DIR=/usr/local/bin`.
 
 Update source checkouts with the repository workflow:
 
@@ -109,8 +122,11 @@ export PROJMUX_INSTALLER=github-release
 ```
 
 With that set, `projmux update apply` downloads the latest matching release
-asset, replaces the current executable, and reapplies the live tmux config
-unless `--no-apply` is used.
+asset, replaces the current executable, and reapplies the live tmux config.
+`--no-apply` skips the live reload only — the new binary still migrates the
+keymap schema and marker-owned provider files, then writes the generated
+config. It does not touch a live tmux bell hook. See
+[Upgrading](upgrading.md#managed-agent-hook-producer-migration).
 
 ## npm Packaging Details