projmux 0.4.4 → 0.4.6

package/README.md

@@ -1,311 +1,109 @@
 # projmux
 
-Project-aware tmux workspace management for people who live in terminals.
+<p align="center">
+  <img src="docs/assets/projmux-icon.png" alt="projmux icon" width="112">
+</p>
 
-`projmux` turns project directories into durable tmux workspaces with previews,
-sidebar navigation, generated keybindings, status metadata, and AI-pane
-attention signals. It can run as its own tmux app (`projmux shell`) or install
-the same behavior into your existing tmux server.
+Project-aware tmux workspaces with fast switching, previews, status context,
+and AI-pane attention built in.
 
 [![npm version](https://img.shields.io/npm/v/projmux?logo=npm)](https://www.npmjs.com/package/projmux)
 [![CI](https://github.com/crevissepartners/projmux/actions/workflows/ci.yml/badge.svg)](https://github.com/crevissepartners/projmux/actions/workflows/ci.yml)
 
-[한국어 README](README-ko.md)
+[Korean README](README-ko.md)
 
-## Why projmux
+![projmux shell project sidebar demo](docs/assets/projmux-shell-sidebar.gif)
 
-Most tmux project switchers stop at "pick a directory and attach a session".
-`projmux` treats that as the foundation, then adds the app-level pieces needed
-for a daily terminal workspace:
+## What It Is
 
-- **Project identity stays stable.** Directories, pins, live sessions, preview
-  selection, and lifecycle commands all use the same normalized session model.
-- **The UI shows context before you switch.** Popup and sidebar pickers preview
-  sessions, windows, panes, git branch, Kubernetes context, and pane metadata.
-- **The tmux layer is generated, not hand-spliced.** `projmux` writes the tmux
-  config it needs for popup launchers, window/pane rename flows, status
-  segments, pane borders, attention badges, and app mode.
-- **AI panes are first-class.** Codex and Claude panes can be launched,
-  labeled, tracked as thinking or waiting, surfaced in pane/window/session
-  badges, and announced through desktop notifications.
-- **You can choose isolation or integration.** Use `projmux shell` as a
-  self-contained tmux app, or install the generated snippet into your normal
-  tmux server.
+`projmux` turns project directories into durable tmux sessions. It gives you a
+keyboard-first workspace app for switching projects, previewing sessions,
+opening AI splits, and keeping useful context visible in tmux.
 
-## What It Does
-
-- Creates or switches to tmux sessions from project directories.
-- Shows existing sessions with window and pane previews.
-- Provides popup and sidebar navigation surfaces backed by `fzf`.
-- Pins important projects and scans common source roots for new ones.
-- Persists preview selection for fast window and pane cycling.
-- Generates tmux bindings for launchers, rename prompts, pane borders, status
-  segments, and attention hooks.
-- Displays git branch and Kubernetes context/namespace in the status area.
-- Renders a two-line clickable status bar with click-to-switch tabs on
-  row 0 and HUD-style notify (left) and AI usage (right) segments on
-  row 1.
-- Launches AI splits and keeps their agent name, topic, status, and
-  notification state visible in tmux.
-
-## Typical Workflow
-
-```sh
-projmux shell
-```
-
-Open the app once, then use its generated tmux bindings to:
-
-- jump between projects from a sidebar or popup,
-- inspect sessions before attaching,
-- split Codex, Claude, or a plain shell into the current workspace,
-- rename windows and AI pane topics without losing metadata,
-- see which panes need review from badges and desktop notifications.
+Use it when you want one command to open your terminal workspace and one set of
+keys to move between projects, windows, panes, notifications, and settings.
 
 ## Requirements
 
-- [Node.js](https://nodejs.org/) and npm — required for the recommended npm
-  install path.
-- [Go 1.24+](https://go.dev/dl/) — required only when installing with
-  `go install` or building from source.
-- [tmux](https://github.com/tmux/tmux/wiki/Installing) **≥ 3.4** — the workspace runtime. Earlier versions miss `display-popup -T` and other features projmux depends on.
-- [fzf](https://github.com/junegunn/fzf#installation) **≥ 0.55** — interactive popup/sidebar pickers. The multiline picker uses `--marker-multi-line`, `--gap-line`, and `--highlight-line`, which landed by 0.55.
-- A Unix shell such as `bash`, `zsh`, or `sh` — `projmux shell` uses your
-  absolute `$SHELL` for the generated app config, falling back to `/bin/sh`.
-- [git](https://git-scm.com/downloads) — branch/status metadata.
-- `stty` — POSIX terminal control, used by `projmux setup`. Already shipped by every macOS / Linux base system; not applicable on Windows hosts.
-- [kubectl](https://kubernetes.io/docs/tasks/tools/) — optional, only for the Kubernetes status segment.
-
-Desktop notifications: Linux uses `notify-send`; WSL routes Windows toasts via
-`powershell.exe`. Override either with `PROJMUX_NOTIFY_HOOK`.
+- [Node.js](https://nodejs.org/) and npm, for the main install path.
+- [tmux](https://github.com/tmux/tmux/wiki/Installing) **3.4 or newer**.
+- [fzf](https://github.com/junegunn/fzf#installation) **0.65.0 or newer**.
 
-Run `projmux doctor` any time to verify runtime dependencies are on `PATH`
-and that tmux/fzf meet the minimum supported versions. Terminal key delivery
-is diagnosed separately with `projmux setup`.
+Run `projmux doctor` after installing to check the local runtime. The `fzf`
+requirement is the junegunn/fzf CLI binary; `npm i fzf` is a different
+JavaScript library.
 
 ## Install
 
 ```sh
 npm install -g projmux
-```
-
-npm installs a small Node.js shim plus the matching platform binary package
-for Linux and macOS on x64 or arm64. The shim marks the install as npm-managed
-so `projmux update` and the Settings About screen can use the right upgrade
-path.
-
-Verify:
-
-```sh
 projmux version
 ```
 
-If npm is not a fit for your machine, install with Go:
-
-```sh
-go install github.com/crevissepartners/projmux/cmd/projmux@latest
-```
-
-This drops the binary in `$(go env GOBIN)` (when set) or `$(go env GOPATH)/bin`
-(default `~/go/bin`). Make sure that directory is on your `PATH`.
-
-### Optional: `PROJMUX_PROJDIR`
-
-`PROJMUX_PROJDIR` is the primary project root projmux uses for picker and
-discovery when you explicitly configure it. It is optional; when unset,
-projmux does not assume a canonical repo root. Discovery still uses pins, live
-sessions, saved workdirs, and weak common-folder probes (`~/source`, `~/work`,
-`~/projects`, `~/src`, `~/code`) when they exist.
-
-```sh
-export PROJMUX_PROJDIR="/your/path"
-```
-
-Add the line to `~/.bashrc`, `~/.zshrc`, or your shell's rc file. The resolved value is
-memoized to `~/.config/projmux/projdir` after first use, so later shells keep
-the same root even without the env var.
-
-`PROJMUX_PROJDIR` accepts an OS-native PATH-style multi-value (`:` on
-Linux/macOS, `;` on Windows). The first non-empty entry is the primary
-project root; any additional entries are prepended to the managed-roots
-search list, so they participate in discovery just like
-`PROJMUX_MANAGED_ROOTS`. Only the primary path is memoized to
-`~/.config/projmux/projdir`.
-
-```sh
-# Linux/macOS — primary repo + secondary search root
-export PROJMUX_PROJDIR="/main/repos:/srv/work/repos"
-```
-
-#### Set the project root during setup
-
-```sh
-PROJMUX_PROJDIR=/your/path projmux shell
-```
-
-The first invocation that sees the env var writes
-`~/.config/projmux/projdir`, so later shells without the env var still
-resolve the same root.
-
-### From source
-
-```sh
-git clone https://github.com/crevissepartners/projmux.git
-cd projmux
-make install
-```
+The npm package installs a small Node.js shim plus the matching projmux binary
+for Linux and macOS on x64 or arm64. npm is the primary distribution path for
+normal users.
 
-`make install` builds, atomically replaces `$(go env GOPATH)/bin/projmux`, and
-runs `projmux tmux apply` so the live `-L projmux` server picks up new bindings
-without a restart. Override the destination with `INSTALL_DIR=/usr/local/bin`.
+Manual Go, source checkout, GitHub Release, and packaging details live in
+[Install](docs/install.md).
 
 ## Quick Start
 
-Launch the isolated projmux tmux app:
+Open the isolated projmux tmux app:
 
 ```sh
 projmux shell
 ```
 
-projmux owns this tmux server, its generated config, status bar, and popup
-bindings. Cooperative terminals get `Alt-1`..`Alt-5` immediately, with no
-terminal config. The left status badge shows the current project name; the
-right side shows path, kube segment, git segment, and clock.
-
-If a key does not fire, run `projmux setup` outside tmux to see which
-sequences your terminal swallows. For supported terminals, preview the
-fallback with `projmux init [terminal]`, then apply it with
-`projmux init [terminal] --apply` (auto-detects when no terminal is given).
-Dotfiles users on multi-machine setups should pass
-`--allow-symlink` or `--config <path>` to make their intent explicit. Full
-flow and the manual CSI-u fallback are in
-[Terminal Keybindings](docs/keybindings.md).
-
-If anything looks off, `projmux doctor` reports which dependency is
-missing or stale and how to install it. See [Requirements](#requirements)
-for the supported versions.
-
-## Upgrading
-
-The Settings About screen is the normal interactive update surface: it shows
-cached release status, installer source, Check Updates, Update Now, and
-release notes. The startup update prompt uses the same cache and never reaches
-the network.
-To refresh the cached release status manually, run:
-
-```sh
-projmux update check
-```
-
-Use Settings > About > Update or `projmux update apply` to update through the
-detected installer. See [Upgrading](docs/upgrading.md) for npm, Go, GitHub
-Release, and source-checkout details.
-
-## Usage
-
-Day-to-day, projmux is driven by tmux keybindings inside `projmux shell` — see
-[Terminal Keybindings](docs/keybindings.md). For the full CLI surface (pins,
-preview state, status helpers, updates, etc.), run `projmux help` or
-`<command> --help`.
-
-## How It Finds Projects
-
-`projmux switch` combines pinned directories, live tmux sessions, and discovered
-project roots. When no explicit search roots are configured, discovery uses
-weak common-folder probes such as `~/source`, `~/work`, `~/projects`, `~/src`,
-and `~/code` if they exist; it does not assume a canonical `~/source/repos`
-root. `projmux settings` also has `Project Picker > Add Project...`, which
-scans filesystem roots up to depth 3 so projects outside the weak probes can be
-added to the picker. Session names are derived from normalized directory paths,
-so a project keeps the same tmux session name across launches.
-
-For permanent search-root customization, the Project Picker section also
-includes:
-
-- `+ Add Workdir...` - append a single directory to the saved workdirs list.
-- `Workdirs` - review and remove saved workdirs. The same picker also surfaces
-  any active `PROJMUX_MANAGED_ROOTS` / `TMUX_SESSIONIZER_ROOTS` env values as
-  read-only rows so you can see why an env list might be overriding the saved
-  file.
-
-`Add Workdir > Type path manually...` gives you a typed entry that skips the
-filesystem scan. Use it for paths you do not want crawled, e.g. WSL mounts
-(`/mnt/c/Users/...`), large NFS mounts, or per-project temp roots.
-
-The saved file lives at `~/.config/projmux/workdirs` (one absolute path per
-line, `#` comments allowed). It is consulted only when the env vars are unset.
+Inside the app:
 
-## Hooks
+- `Alt-1` opens the project sidebar.
+- `Alt-2` opens the notification list.
+- `Alt-3` opens the existing-session picker.
+- `Alt-4` opens the AI split picker.
+- `Alt-5` opens settings.
+- `Alt-6` opens the project switcher popup.
 
-projmux runs an optional user script at `~/.config/projmux/hooks/post-create`
-whenever it creates a new tmux session. Use it to inject per-session env via
-`tmux set-environment` (e.g. picking a `GH_TOKEN` based on the project path).
-Missing or non-executable hooks are skipped silently; failures never block
-session creation. See [Hooks](docs/hooks.md) for the env contract, examples,
-and troubleshooting.
+See [Terminal Keybindings](docs/keybindings.md) for the full key map. If a key
+does not fire, run `projmux setup` outside tmux, then use
+`projmux init [terminal] --apply` for supported terminal fallbacks.
 
-## Environment Variables
+## Day-To-Day Use
 
-| Variable | Purpose |
-| --- | --- |
-| `PROJMUX_PROJDIR` | Explicit primary project root for the current shell. Accepts an OS-native PATH-style multi-value: the first entry is the primary repo root (memoized to `~/.config/projmux/projdir`), and any additional entries are prepended to the managed-roots search list. |
-| `PROJMUX_MANAGED_ROOTS` | Colon-separated list of search roots. Overrides the saved/heuristic list. |
-| `PROJMUX_NOTIFY_HOOK` | External executable that receives AI desktop notifications instead of the built-in sender. |
-| `PROJMUX_USAGE_STATE_DIR` | Override directory for the AI-usage snapshot cache. Defaults to `<state>/projmux/usage`. Point this at a synced location (Dropbox, iCloud Drive, etc) to share authoritative usage between machines. |
-| `PROJMUX_USAGE_DEBUG` | When non-empty, surfaces adapter errors from `projmux status usage` to stderr instead of swallowing them. |
-| `PROJMUX_USAGE_LIMITS_PATH` | Deprecated. Limits now come from the upstream APIs (Anthropic OAuth usage endpoint, Codex `rate_limits`); this variable is read but ignored. |
+- Pick a project directory and projmux creates or reuses its tmux session.
+- Pin important projects so they stay easy to reach.
+- Preview windows, panes, git branch, Kubernetes context, and AI pane state
+  before switching.
+- Use Settings > Project Picker to add roots and workdirs without editing env
+  vars.
+- Use Settings > About > Update or `projmux update apply` to upgrade.
 
-## AI usage tracking
+For detailed configuration, including `PROJMUX_PROJDIR`, managed roots,
+notifications, and usage tracking, see [Configuration](docs/configuration.md).
+For update behavior by installer type, see [Upgrading](docs/upgrading.md).
 
-`projmux usage` reports authoritative 5-hour and weekly utilisation for both
-Claude Code and the Codex CLI. Both adapters read from the upstream's own
-view of your account so the percentages match what `claude /usage` and
-`codex` show natively:
+## More Docs
 
-- **Claude** — calls `GET https://api.anthropic.com/api/oauth/usage` with the
-  bearer token in `~/.claude/.credentials.json`. The adapter performs a
-  single refresh round-trip on 401 and rewrites the credentials file with
-  the rotated tokens. Tokens are never logged.
-- **Codex** — reads the most recent `rate_limits` payload from the newest
-  `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`. `primary` maps to the 5h
-  window, `secondary` to the weekly window.
-
-Snapshots are persisted under `<state>/projmux/usage/snapshots.json` (or
-`PROJMUX_USAGE_STATE_DIR`) and refreshed at most every 30 seconds when
-`projmux status usage` runs in the tmux status bar.
-
-## Scope
-
-`projmux` owns the portable session-management core: naming, discovery, pins,
-preview state, tmux orchestration, status segments, and generated tmux bindings.
+- [Install](docs/install.md)
+- [Configuration](docs/configuration.md)
+- [Terminal Keybindings](docs/keybindings.md)
+- [CLI Reference](docs/cli.md)
+- [Statusbar](docs/statusbar.md)
+- [Hooks](docs/hooks.md)
+- [Usage tracking](docs/usage-tracking.md)
+- [Agent Workflow](docs/agent-workflow.md)
 
 ## Development
 
-Useful commands:
-
 ```sh
 make build
 make fmt
 make fix
 make test
-make test-integration
-make test-e2e
-make verify
 ```
 
-More documentation:
-
-- [Architecture](docs/architecture.md)
-- [CLI Reference](docs/cli.md)
-- [Statusbar](docs/statusbar.md)
-- [Notify queue](docs/notify-queue.md)
-- [Usage tracking](docs/usage-tracking.md)
-- [Upgrading](docs/upgrading.md)
-- [Hooks](docs/hooks.md)
-- [Migration Plan](docs/migration-plan.md)
-- [Repo Layout](docs/repo-layout.md)
-- [Terminal Keybindings](docs/keybindings.md)
-- [Agent Workflow](docs/agent-workflow.md)
+See [Testing](docs/testing.md), [Architecture](docs/architecture.md), and
+[Repo Layout](docs/repo-layout.md) for contributor details.
 
 ## License
 

package/docs/agent-workflow.md

@@ -0,0 +1,56 @@
+# Agent Workflow
+
+## Parallel Work With `wt`
+- Start with `wt --version` and `wt list`.
+- Create the task path with `wt path --create <branch>`.
+- Work only inside the returned path.
+- Keep file ownership clear. If two agents need the same file, one should finish or hand off before the other edits it.
+- Use `wt cleanup` or `wt prune` only after previewing what will be removed.
+
+## Branch Naming
+- `feat/<topic>` for new behavior.
+- `fix/<topic>` for bug fixes.
+- `docs/<topic>` for documentation-only changes.
+- `refactor/<topic>` for structure changes without intended behavior changes.
+- `chore/<topic>` for maintenance or tooling.
+
+## Standard Development Loop
+1. Sync the branch context and inspect `git status --short`.
+2. Implement the smallest coherent change.
+3. Run `make fmt`.
+4. Run `make fix`.
+5. Run `make test`.
+6. Run `make test-integration`.
+7. Run `make test-e2e`.
+8. Update the maintained test list below if behavior or coverage expectations changed.
+9. Prepare review notes with parity status, commands run, and remaining risks.
+
+## Maintained Test List
+- `make fmt`: repository formatting for Go, shell snippets, and generated docs where applicable.
+- `make fix`: safe automatic fixes such as `go fix` and repository-approved cleanup steps.
+- `make npm-pack`: local npm binary package staging and `npm pack --dry-run` for the root package plus platform packages.
+- `make test`: fast unit coverage for app-layer AI split native agent launch/selective popup-toggle/settings/status/notification parity including AI pane option metadata, watcher metadata bootstrap for existing panes, capture-backed reply detection, missing-pane watcher shutdown, armed focus-only reply badge clearing, busy attention preservation on focus clear, manual AI topic preservation while watcher status still updates, agent-labeled desktop notification message context with pane-title-first body text, global/project-local post-create hook dispatch, and agent-specific notification icons, and scoped even row/column resizing after shell and agent splits, status-bar git/kube segment parity including branch block styling, statusbar pwd click path popup/buffer-copy fallback, isolated `projmux shell` tmux app launch/config generation including home-project default session targeting, app-owned project-name statusbar layout, and distinct project badge color, shell startup update prompt actions for fresh installer-aware cached updates, pane/window keybindings, window rename bindings, pane rename helper/binding, pane-exit rebalance command/hooks, hook-pane and after-select-pane based attention focus hooks, attention badge toggle/clear/list/window rendering, attach/current/kill/pin/preview/prune/sessions/session-popup/settings commands, switch, tag, tmux helper commands, update status/check/apply cache and installer detection including GitHub Release binary asset selection/extraction/replacement, doctor install-missing command selection, and Settings About update status/check action wiring, untitled standalone popup-toggle marker close/config install, direct popup minimum sizing, AI picker minimum width and height, sidebar minimum width and compact badge spacing, preview select writes, popup render output after cycling, switch picker pin action behavior without inline settings rows, nested settings hub sections for AI defaults, project picker filesystem scan/pin actions, Project Root settings source/shadowing/set/current/clear flows, app/keybinding info including Ctrl-M rename forwarding, and About version/source rendering, switch picker focused-session kill, switch picker launcher-key abort bindings, switch explicit project-root, unconfigured-root, and weak managed-root heuristic parity, switch popup hiding new-session candidates while sidebar keeps create-capable rows, switch row project-name display with `~` pinned to the top and live-session-first sorting, pretty-path, preview-context including kube context/namespace, switch settings subcommand flows including add-current-pin, interactive add-pin picker, and settings label/preview polish, fzf preview wiring, fzf baseline surface parity including prompt/footer/header fallback without app-name filler and search-key scoped card matching, sidebar compact action-only key footer, sidebar preview-window/start-position behavior without focus-time session switching, sidebar row/window ANSI styling with pane-aggregated attention badge state and AI topic labels, Alt+2/Alt+3 legacy popup row, preview-window, pane metadata, and pane-snapshot parity, switch read0 card rows with active/inactive title styling, right-side status badges, combined directory/git metadata with muted inactive branch styling, statusbar-matched block window tabs with window attention badges, read0 expect-key action parsing, restored pin/tag card badges, and restrained selected-row marker styling, switch preview metadata without duplicated directory/git rows, preview metadata rendering, popup pane display names for AI agents, AI topics, and shell commands, switch preview cycle bindings, sessions picker preview/cycle/open/kill wiring including attached-session fallback behavior, sessions picker launcher-key abort bindings, popup/switch preview summary formatting, popup sessions tmux entry helpers, switch/popup/session rendering, session identity, candidate discovery, config path derivation, popup preview read-models, and pure state rules including preview, tag, and lifecycle stores.
+- 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
+  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
+  notify-only fallback.
+- Picker focused unit coverage includes backend-neutral picker item/action mapping, fzf adapter output, native title-focused filtering, numeric selection, and shared close actions.
+- `make test-integration`: Docker-backed Linux integration smoke with real `tmux`, `fzf`, `git`, and `stty`; covers `doctor`, tmux config print/install/apply, and notify queue CRUD against isolated HOME/XDG paths.
+- `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).
+
+## When To Update This List
+- A feature moves between unit, integration, and e2e coverage levels.
+- A new subsystem introduces a new validation target or removes one.
+- Behavior changes require new parity assertions or a different e2e scenario.
+- A target stops being authoritative and must be replaced.
+
+## Review Checklist
+- The branch stays within its stated scope.
+- The change preserves boundaries between portable `projmux` behavior and local machine policy.
+- The required `make` targets were run in order.
+- Test inventory updates are included when behavior changed.
+- Known parity gaps are explicit.

package/docs/architecture.md

@@ -0,0 +1,199 @@
+# Architecture
+
+## Core model
+
+`projmux` is built around a small set of domain objects:
+
+- `ProjectRoot`: a directory that may map to a tmux session
+- `SessionIdentity`: the stable session name derived from a directory
+- `SessionTarget`: the current selected session/window/pane target
+- `CandidateSet`: the ordered list of project directories presented to the user
+- `PinSet`: user-curated candidate priority state
+- `PreviewState`: selected window/pane state used by popup and session previews
+
+## Layers
+
+### 1. Core
+Pure rules and state transitions.
+
+Responsibilities:
+- directory normalization
+- session naming
+- candidate ordering
+- pin state changes
+- tagged selection state
+- lifecycle decisions such as reuse, create, kill, fallback
+
+This layer should not shell out directly.
+
+### 2. Integrations
+Adapters for external systems.
+
+Initial adapters:
+- tmux
+- kubeconfig per-session state
+- filesystem
+- git metadata for preview enrichment
+
+Responsibilities:
+- execute commands
+- parse command output
+- convert failures into typed errors
+
+### 3. UI orchestration
+Picker data is modeled independently from fzf rows. The app builds
+backend-neutral `picker.Item` values (`Title`, `Value`, `SearchText`,
+`MetaLines`, `Badges`, `PreviewTarget`) and then adapts them to the selected
+backend. `fzf` remains the default, stable backend; the native backend is
+opt-in through `PROJMUX_PICKER_BACKEND=native` while it reaches full parity.
+
+Responsibilities:
+- rows for popup and sidebar views
+- preview rendering
+- keybind-to-action dispatch
+- selection handoff into core actions
+- picker-agnostic close/dismiss actions
+
+Picker-specific display and search rules are tracked in
+[picker-ui-plan.md](picker-ui-plan.md).
+
+This keeps parity with the existing shell workflow while moving state and behavior into Go.
+
+### 4. Local environment
+This repo owns the portable application behavior and generated tmux config.
+
+Responsibilities that remain outside `projmux`:
+- terminal emulator key dispatch
+- shell startup policy
+- install-time package checks
+- machine-specific path and symlink choices
+
+## Configuration model
+
+Config should be explicit and file-backed.
+
+Candidate areas:
+- managed roots
+- default home-like roots
+- preview preferences
+- session naming exceptions
+- kube session settings
+- ephemeral session retention defaults
+
+## State model
+
+Persistent state:
+- pins
+- lightweight user preferences
+
+Ephemeral runtime state:
+- preview selection
+- popup marker files
+- current tagged selection set
+
+## Notify queue
+
+`projmux` keeps a single JSON-backed queue of pending notifications at
+`<state>/projmux/notify.json` (typically `~/.local/state/projmux/notify.json`,
+following XDG). Writes go through an `O_CREATE|O_EXCL` lock file
+(`notify.json.lock`) with bounded retry + jittered backoff so the queue
+is safe across concurrent producers (the AI flow, the manual `attention
+toggle`, the `notify push` CLI) on a local filesystem.
+
+Attention and notify are intentionally separate surfaces: attention is live
+tmux pane state, while notify is the explicit-ack pending queue derived from
+AI reply panes and explicit pushes. The queue helps clicks route to work; it
+does not own the truth of every live badge.
+
+- **Push** — `projmux notify push` (or the in-process producer in
+  `internal/app/notify_producer.go`) appends an entry. Entries carry a
+  stable id (caller-supplied or `ai:<session>:<pane>` for the producer
+  path), text (capped at 80 runes), severity (`info|warn|critical`),
+  source (`ai|k8s|git|external`), TTL freshness metadata (default 600s), and a
+  `Target{Socket, Session, Window, Pane}`. Re-pushing an existing id
+  refreshes the entry's text and timestamp.
+- **List** — `projmux notify list` returns newest-first until explicit ack.
+  TTL is not a removal condition. `projmux notify list --live` adds a
+  read-only comparison against live pane state, explaining manual reply
+  badges without queue entries, live AI replies with/missing queue entries,
+  and stale `ai:` entries.
+- **Ack** — `projmux notify ack <id>` removes one entry; `--all`
+  flushes everything. Focus/click handlers do not ack rows.
+- **Reconcile** — `projmux notify 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.
+  `make install` and `projmux upgrade` invoke it so the queue
+  recovers from any drift introduced by a lost daemon.
+
+The producer is wired to the attention state machine: a pane
+transitioning to `reply` with an AI agent option set pushes an
+`ai:<session>:<pane>` entry; the matching `clear` (or the AI
+flow's `status set idle`) leaves it pending until explicit ack. Manual `attention toggle` on a
+shell pane does not push because the agent option is empty —
+the queue is intentionally AI-driven only.
+
+See [notify-queue.md](notify-queue.md) for the full reference.
+
+## Usage snapshots
+
+`projmux usage` and `projmux status usage` share a single `Manager`
+that walks two registered adapters (Claude, Codex) and persists the
+result to `<state>/projmux/usage/snapshots.json` (or
+`PROJMUX_USAGE_STATE_DIR`). The cache file is the authoritative source
+for the HUD render path so the tmux status interval never blocks on a
+network call.
+
+- **Per-adapter throttle** — Claude reports a 5-minute hint via the
+  `ThrottleHinter` interface; Codex falls through to the global
+  `30s` floor used by `status usage`. `MaybeCollect` only invokes an
+  adapter when `now - last_collect >= throttle`. `--force` bypasses the
+  gate.
+- **429 backoff** — Claude implements `BackoffStater`. On HTTP 429
+  the adapter persists `BackoffState{Until, Consecutive}`: the
+  default cooldown is 30 minutes, doubling per consecutive 429 up to a
+  60-minute cap. A `Retry-After` header (when present) raises the floor.
+  During backoff `Collect` short-circuits (no network call). A clean
+  200 resets the streak. `--force` clears the persisted state via the
+  `BackoffResetter` interface so the next call attempts the network
+  call regardless of streak.
+- **Failure preservation** — adapter failures do not erase prior
+  rows. The Manager merges new snapshots over the on-disk slice, so a
+  transient 429 keeps the last known good numbers visible.
+
+See [usage-tracking.md](usage-tracking.md) for adapter detail (token
+refresh, rollout schema).
+
+## Two-line clickable status bar
+
+projmux configures tmux with `status 2`. Line 0 is the existing
+session/window/path/git/kube/clock row. Line 1 splits the notification bar
+(left half, capped at 80 cells) and the AI usage HUD (right half, capped at
+120 cells) using tmux `#[align=left]` / `#[align=right]`. Each clickable
+segment is wrapped in a tmux user-defined range (`#[range=user|<id>]...
+#[norange]`) and dispatched through `projmux statusbar click <range-id>`. A
+single `bind -n MouseDown1Status` covers both lines because tmux fires
+`MouseDown1Status` from any line of a multi-line status bar with
+`#{mouse_status_range}` resolving to whichever range the cursor was over.
+
+| Range id | Line | Click action                              | Keybinding   |
+|----------|------|-------------------------------------------|--------------|
+| session  | 0    | popup `projmux sessions --ui=popup`       | prefix+s s   |
+| pwd      | 0    | copy pane_current_path and show path popup | prefix+s p   |
+| kube     | 0    | popup `projmux switch --ui=popup`         | prefix+s k   |
+| git      | 0    | popup `projmux switch --ui=popup`         | prefix+s g   |
+| usage    | 1    | popup `projmux usage`                     | prefix+s u   |
+| notify   | 1    | focus origin pane of newest notification  | prefix+s n   |
+
+The keyboard chord uses `bind-key s switch-client -T projmux-status` so the
+prefix-then-`s`-then-letter shortcut routes through the same dispatcher as
+the mouse click. Empty `#{mouse_status_range}` (clicks on whitespace) is a
+no-op so the binding never flashes a spurious error.
+
+## Non-goals
+
+- replacing tmux
+- owning terminal emulator bindings
+- becoming a generic worktree orchestrator
+- implementing a fully custom TUI before parity is reached