projmux 0.4.5 → 0.4.7

package/docs/npm-distribution.md

@@ -0,0 +1,86 @@
+# npm Distribution
+
+`projmux` remains a Go CLI. npm is a distribution channel that installs a
+small Node.js shim plus one platform-specific Go binary package.
+
+The public npm package `projmux` is the root shim package. Release builds use
+this package layout:
+
+| package | contents |
+| --- | --- |
+| `projmux` | `npm/projmux.js` shim and optional dependencies |
+| `@projmux/linux-x64` | `linux/amd64` `bin/projmux` |
+| `@projmux/linux-arm64` | `linux/arm64` `bin/projmux` |
+| `@projmux/darwin-x64` | `darwin/amd64` `bin/projmux` |
+| `@projmux/darwin-arm64` | `darwin/arm64` `bin/projmux` |
+
+The shim sets `PROJMUX_INSTALLER=npm` before executing the real binary so
+`projmux update status` and the Settings About screen can present
+npm-specific guidance. npm is only an update/install source label here; the
+keybinding flow remains `projmux shell` first, then `projmux setup` and
+`projmux init` only for terminals that swallow shortcuts.
+
+## Local Packaging
+
+Build and dry-run pack all npm packages:
+
+```bash
+make npm-pack
+```
+
+or:
+
+```bash
+scripts/package-npm.sh --version 0.4.0 --out /tmp/projmux-npm --pack
+```
+
+The script stages package directories under `dist/npm` by default. It builds
+the Go binary for each supported platform, copies package metadata and docs,
+updates package versions in the staged copies, then runs `npm pack --dry-run`
+when `--pack` is set.
+
+## Publish Order
+
+The platform packages must be published before the root package:
+
+```text
+@projmux/linux-x64
+@projmux/linux-arm64
+@projmux/darwin-x64
+@projmux/darwin-arm64
+projmux
+```
+
+Publishing the scoped platform packages requires control of the `@projmux`
+npm scope. Configure npm Trusted Publishing for every package before merging a
+release PR:
+
+| npm package | GitHub organization/user | repository | workflow filename |
+| --- | --- | --- | --- |
+| `@projmux/linux-x64` | `crevissepartners` | `projmux` | `release.yml` |
+| `@projmux/linux-arm64` | `crevissepartners` | `projmux` | `release.yml` |
+| `@projmux/darwin-x64` | `crevissepartners` | `projmux` | `release.yml` |
+| `@projmux/darwin-arm64` | `crevissepartners` | `projmux` | `release.yml` |
+| `projmux` | `crevissepartners` | `projmux` | `release.yml` |
+
+Leave the npm trusted publisher environment field empty unless the workflow is
+later moved behind a GitHub deployment environment.
+
+Tag releases publish npm packages from GitHub Actions after release archives
+are uploaded. The workflow runs:
+
+```bash
+scripts/package-npm.sh --version "${GITHUB_REF_NAME#v}" --out dist/npm
+```
+
+then publishes each staged package with `npm publish --access public`.
+The npm publish job uses GitHub Actions OIDC (`id-token: write`) instead of a
+long-lived `NPM_TOKEN` secret. PR CI runs `make npm-pack` so package staging and
+dry-run packing fail before release.
+
+## Non-Goals
+
+The npm installer must not install system dependencies, edit shell startup
+files, or mutate tmux config. Those actions stay behind explicit
+`projmux doctor`, `projmux init`, Settings About update actions, or future
+opt-in install commands.

package/docs/picker-ui-plan.md

@@ -0,0 +1,111 @@
+# Picker UI Plan
+
+## Goal
+
+The project switcher needs a richer picker surface than a single-line fzf row.
+The target interaction is a card-like list where each item can show a title plus
+small contextual lines such as session state, window/pane summary, branch, or
+path. Search should stay focused on stable identity text, especially the project
+or session title, instead of matching every contextual preview line.
+
+## Current Contract
+
+The picker contract is split in two layers:
+
+- `internal/ui/picker` owns backend-neutral items, actions, preview metadata,
+  backend selection, title-focused filtering, and the default native runner.
+- `internal/ui/fzf` adapts that model into the historical fzf command line.
+
+The fzf fallback backend sends one logical row per item:
+
+```text
+<visible label>\t<selection value>
+```
+
+fzf is configured with:
+
+- `--delimiter "\t"`
+- `--with-nth 1`
+- `--exit-0`
+- optional `--preview` and `--preview-window`
+
+The app depends on fzf returning the selected row and then extracts the hidden
+value after the first tab. This contract is simple and stable, but it limits each
+row to one visible line.
+
+## fzf Capability Check
+
+The installed fzf version supports multi-line items with `--read0`. That means a
+single item can contain newline characters when input records are NUL-delimited.
+This can render card-like rows.
+
+The simple fzf option path is not enough for the desired search behavior:
+
+- `--read0` can display multi-line items.
+- `--nth` can restrict search to selected fields.
+- `--with-nth` can transform the displayed fields.
+- In practice, once `--with-nth` is used to show a card field, fzf searches the
+  transformed visible text. Context lines become searchable.
+
+So fzf can support "multi-line cards", but not "multi-line cards with title-only
+search" through a small option-only extension while preserving the current
+selection contract.
+
+## Viable Paths
+
+### 1. fzf card approximation
+
+Use `--read0` and NUL-delimited multi-line entries. This is the smallest change,
+but contextual card text will participate in search unless the visible card is
+kept title-only. This does not meet the intended search model.
+
+This path is acceptable only as a temporary visual experiment.
+
+### 2. fzf custom filtering
+
+Run fzf in a more controlled mode where query changes reload a filtered list
+from `projmux`, and `projmux` performs title-focused matching. This keeps fzf as
+the renderer but moves filtering into the app.
+
+Tradeoffs:
+
+- More shell quoting and reload complexity.
+- More edge cases around selection identity and tracking.
+- Still constrained by fzf's list layout and event model.
+
+This is viable, but it is a bridge rather than a clean long-term model.
+
+### 3. Native picker TUI
+
+Introduce a picker abstraction and implement a native terminal UI for card rows,
+title-focused search, stable selection identity, and app-owned key handling. fzf
+remains the default backend until parity is reached.
+
+This best matches the desired product direction:
+
+- card rows are first-class data, not encoded fzf strings
+- search fields are explicit
+- preview/context fields can be visible but non-searchable
+- future key behavior can be tested without relying on fzf internals
+
+## Implemented Direction
+
+Do not extend the current fzf row format again as the main implementation. The
+previous hidden-field attempt showed that small fzf encoding changes can break
+selection and navigation in subtle ways.
+
+Current implementation:
+
+- Picker-domain model exists as `picker.Item` with `Title`, `Value`,
+  `SearchText`, `MetaLines`, `Badges`, and `PreviewTarget`.
+- `picker.Options` carries backend-neutral actions, preview metadata, prompt,
+  footer, initial query, and multiline intent.
+- Native is the default backend and renders the popup/sidebar surfaces.
+- `PROJMUX_PICKER_BACKEND=fzf` opts into the external fzf runner. Native supports
+  multiline item rendering, title-focused search via `SearchText`, numeric
+  selection, and shared close actions.
+- Switcher popup/sidebar use the selected backend for preview and key action
+  parity, including native preview panes, raw-key navigation, and sidebar focus
+  tracking.
+
+fzf can stay as the stable fallback while the native picker continues to mature.

package/docs/pr-guideline.md

@@ -0,0 +1,106 @@
+# PR Guideline
+
+Audience: every contributor — humans and agents alike. Agents working in this
+repo (`claude` / `codex` panes, the team-lead session, etc.) MUST follow these
+rules; the conventions here are what `release-please` parses for the next
+release notes, so a sloppy PR title silently breaks the changelog.
+
+For the surrounding workflow (worktree, validation gates, post-merge install)
+see [AGENTS.md](../AGENTS.md). This document covers only the PR itself.
+
+## PR title — Conventional Commits
+
+Default merge method is **squash**, so the PR title becomes the only commit
+subject that lands on `main`. Format:
+
+```
+<type>(<optional scope>): <imperative summary>
+```
+
+Examples:
+
+```
+feat(ai): add codex split picker keybinding
+fix(ai): prepend agent bin dir to PATH so node-managed CLIs find node
+docs(readme): drop Releases and Configuration sections
+chore: bump release-please manifest to 0.3.0
+refactor(picker): collapse duplicate fzf bootstrap code
+```
+
+Rules:
+
+- Subject is in the imperative ("add", "fix", "drop"), no trailing period.
+- Keep the title under ~70 characters when possible. Long detail goes in the
+  body.
+- The scope is optional but recommended for non-trivial diffs (`ai`, `picker`,
+  `tmux`, `readme`, `ci`, etc.).
+- A `!` after the type or scope marks a breaking change:
+  `feat(ai)!: rename PROJMUX_NOTIFY_HOOK to PROJMUX_NOTIFY_BIN`.
+- Or include a `BREAKING CHANGE: <description>` footer in the body. Either form
+  bumps the major version on the next release-please run.
+
+### Allowed types
+
+| type | use for | release impact |
+| --- | --- | --- |
+| `feat` | user-visible new behavior or capability | minor bump |
+| `fix` | bug fix that ships to users | patch bump |
+| `perf` | measurable runtime/memory improvement | patch bump |
+| `refactor` | code restructure with no user-visible change | none |
+| `docs` | docs-only change | none |
+| `test` | adding or restructuring tests | none |
+| `build` | build system, Makefile, dependencies | none |
+| `ci` | CI workflow / GitHub Actions | none |
+| `chore` | release plumbing, tooling, repo housekeeping | none |
+| `style` | formatting only, no logic change | none |
+
+If the change includes both a feat and a fix, split it into two PRs. release-please
+classifies the whole PR by its title type, not by content.
+
+## PR body
+
+Use this template:
+
+```markdown
+## Summary
+- 1–3 bullets describing what changed and why.
+
+## Test plan
+- [ ] make fmt-check
+- [ ] make test
+- [ ] manual verification step (if relevant)
+```
+
+Notes:
+
+- **Why** matters more than **what**. Diff already shows the what.
+- Reference issues with `Closes #<n>` so they auto-close on merge.
+- Mention follow-ups explicitly when scope was deliberately deferred.
+
+## Branch protection in effect
+
+`main` is governed by ruleset `main-protect`:
+
+- Direct push to `main` is blocked. Even repository admin must use a PR.
+- Required status check: the CI `Test` job. The PR cannot merge until it is
+  green.
+- Admin bypass is `pull_request` mode — admin can self-merge without
+  approvals, but the PR itself is mandatory.
+- Linear history is enforced. The merge methods exposed are
+  `merge` / `squash` / `rebase`; **default is squash** and that is what the
+  team-lead session uses unless the change explicitly needs preserved history.
+- Force pushes and branch deletions on `main` are blocked.
+
+`gh pr merge <num> --squash --delete-branch` is the canonical merge command.
+Use `--auto` if you want the merge queued automatically once CI passes.
+
+## Release-please coupling
+
+Every PR title that lands on `main` is parsed by `release-please-action`.
+A `feat:` or `fix:` PR adds an entry to the next release notes; `chore:` /
+`docs:` / `refactor:` etc. do not. To force a release of accumulated non-user
+changes, open a `chore` PR titled `chore: release X.Y.Z` (or wait for any
+real change). The `internal/version/version.go` constant carries the
+`x-release-please-version` marker so release-please bumps it automatically.
+
+Do not hand-author CHANGELOG.md or version bumps. release-please owns both.

package/docs/repo-layout.md

@@ -0,0 +1,50 @@
+# Repository Layout
+
+## Planned layout
+
+```text
+projmux/
+  cmd/
+    projmux/
+  internal/
+    app/
+    config/
+    core/
+      candidates/
+      pins/
+      preview/
+      sessions/
+    integrations/
+      filesystem/
+      git/
+      kube/
+      tmux/
+    state/
+    ui/
+      fzf/
+      render/
+    version/
+  docs/
+  scripts/
+  test/
+    integration/
+    e2e/
+```
+
+## Notes
+
+- `cmd/projmux` contains only CLI wiring.
+- `internal/core` contains product behavior that should be testable without tmux.
+- `internal/integrations/tmux` should be the only place that knows tmux command strings and output formats.
+- `internal/ui/fzf` may depend on shelling out to `fzf`, but should call typed core services.
+- `scripts/` is for development tooling only, not product logic.
+
+## Early implementation order
+
+1. `internal/core/sessions`
+2. `internal/core/candidates`
+3. `internal/core/pins`
+4. `internal/state`
+5. `internal/integrations/tmux`
+6. `internal/ui/fzf`
+7. CLI command wiring

package/docs/roadmap.md

@@ -0,0 +1,95 @@
+# Roadmap
+
+## Done (0.4.x)
+
+The 0.4 line filled in the operational surface around the session-management
+core that 0.3 had landed.
+
+### Setup and install
+
+- `projmux setup` — TTY raw-mode probe that reports which projmux key
+  sequences (`Alt-1..5`, `Ctrl-N`, `Ctrl-Shift-{R,L,M}`, `Ctrl-M`,
+  `Alt-Shift-{Left,Right}`) reach the process and which the terminal
+  swallows.
+- `projmux init [terminal]` — auto-merges projmux's CSI-u + chord
+  bindings into a terminal config. Adapters: Ghostty (with the
+  `config` / `config.ghostty` candidate split and symlink guard) and
+  Windows Terminal (WSL + native).
+
+### Diagnostics
+
+- `projmux doctor` — runtime dependency report. Enforces minimum tmux
+  3.4 and fzf 0.65.0 (`stale` status when present but below the floor).
+
+### Focus
+
+- `projmux focus` — unified switch-client dispatch. Resolves a target
+  session against the live tmux inventory, redirects an existing client
+  if one is attached, otherwise emits a desktop notification. Used by
+  the status-bar notify click and by the AI reply-ready handler.
+
+### Notify queue
+
+- `projmux notify push|list|ack` — persistent JSON-backed queue at
+  `<state>/projmux/notify.json` with TTL, severity, source, and target
+  metadata.
+- `projmux notify reconcile` — back-fills the queue from live pane
+  state by walking `tmux list-panes -a`.
+- Producer 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` acks it.
+
+### Usage tracking
+
+- `projmux usage` (and `status usage`) — authoritative 5h + weekly
+  utilisation for both Claude (OAuth `api/oauth/usage` endpoint with
+  401 token refresh) and Codex (latest rollout `rate_limits` JSONL).
+- Per-adapter throttle (Claude `5m`, default `30s`), 429 backoff
+  (`30m`–`60m` exponential), `--force` to bypass both. Snapshots
+  preserved on failure so a 429 does not erase prior rows.
+
+### Statusbar and HUD
+
+- Two-line clickable status bar: row 0 is the existing
+  session/window/path/git/kube row, row 1 splits notify (left) and
+  usage (right).
+- `projmux statusbar click` — single dispatcher for both mouse clicks
+  and the `prefix s {u,n,g,k,p,s}` keyboard chord. Window-list clicks
+  on tabs short-circuit to native `select-window`.
+- `pwd` status click copies the current pane path into the tmux paste
+  buffer and shows a compact path popup instead of a transient
+  warning-coloured toast.
+- HUD-style notify segment with severity+agent badge, midpoint dot
+  separators, and an age field.
+- HUD-style usage segment with bars, last-sync age indicator (Claude),
+  and graceful degradation through six tiers as `--max-width` shrinks.
+
+## Next (0.5+)
+
+Carried forward from earlier milestones — items still outstanding when
+v0.4 shipped.
+
+### Picker UI
+
+- Picker-domain model separate from fzf row encoding (kept fzf as the
+  stable fallback backend). Done in the 0.5 picker contract slice.
+- Native picker backend for multi-line card rows and title-focused search.
+  Done in the 0.5 picker contract slice, later promoted to the default picker
+  backend with `PROJMUX_PICKER_BACKEND=fzf` kept as the explicit fallback.
+- Port switcher popup/sidebar surfaces after parity tests cover
+  selection, preview, and key actions.
+
+### Picker dismissal
+
+- Picker-agnostic popup close/toggle handling so AI picker dismissal
+  does not depend on fzf-specific key bindings. Done in the 0.5 picker
+  contract slice; fzf maps close actions to `abort`, and the native runner
+  consumes the same close action keys.
+
+### Docker install and E2E harness
+
+- Initial Docker-backed Linux smoke suites are available through
+  `make test-integration`, `make test-install-smoke`, and `make test-e2e`.
+  They cover install/runtime substrate checks against real `tmux`; host-only
+  terminal, WSL, macOS, and GUI checks remain separate in
+  [docs/testing.md](testing.md).

package/docs/shell-autostart.md

@@ -0,0 +1,33 @@
+# Shell Auto-Start
+
+If you want every new interactive bash or zsh shell to drop you straight into
+the projmux app, add a guarded hook to `~/.bashrc`, `~/.zshrc`, or the
+equivalent interactive rc file for your shell:
+
+```sh
+if [[ $- == *i* && -z "${TMUX:-}" ]] && command -v projmux >/dev/null 2>&1; then
+  exec projmux shell
+fi
+```
+
+The three guards each prevent a common breakage:
+
+- `$- == *i*` — only fire for interactive shells. Without this you would
+  break `scp`, `ssh host cmd`, `git` over SSH, and any `bash -c '...'` or
+  `zsh -c '...'` invocation.
+- `-z "${TMUX:-}"` — skip when already inside tmux. Without this the hook
+  recurses every time projmux opens a new pane.
+- `command -v projmux >/dev/null 2>&1` — skip on machines where projmux is not
+  installed yet. Without this a fresh login on a new box hangs at a missing
+  binary.
+
+To bypass the hook for one shell, set `TMUX` before launching:
+
+```sh
+TMUX=1 bash
+TMUX=1 zsh
+```
+
+This is **opt-in** behavior. projmux does not assume you want every shell to
+auto-start the app; the snippet above is here only as a known-safe starting
+point for users who do.

package/docs/statusbar.md

@@ -0,0 +1,157 @@
+# Statusbar
+
+`projmux shell` configures tmux with `status 2` and renders a two-line
+clickable status bar. The same dispatcher (`projmux statusbar click`)
+handles both mouse clicks and the keyboard chord, so adding a new
+segment only requires one wiring point.
+
+## Layout
+
+```
+row 0  [#S] #{pane_current_path}  ⎈ <ctx>/<ns>  <git>               %H:%M
+       └────────── native tmux window list (one entry per window) ──────────┘
+row 1  #[range=user|notify] <notify HUD pill> #[norange]
+                                           #[range=user|usage] <usage HUD bar> #[norange]
+```
+
+- Row 0 keeps tmux's native `window-status-format` so clicking a tab
+  selects the window. The bind uses `if-shell -F
+  "#{==:#{mouse_status_range},window}"` to run `select-window -t =`
+  natively when the click lands on the window list, so the
+  mouse-target context resolves the clicked window directly. All
+  other ranges fall through to `run-shell projmux statusbar click
+  ...`, which dispatches by range id. The in-config short-circuit
+  is required because `#{mouse_window}` is empty for window-list
+  clicks on tmux 3.4+, so a `run-shell` handler can't recover the
+  target after the fact — the Go dispatcher's
+  `isWindowListRangeToken` fallback is now defense-in-depth only.
+  The session, pwd, kube, and git segments on this row are wrapped
+  in `#[range=user|<id>]` ranges and dispatched through the projmux
+  handler. The git segment shows the current branch or detached commit,
+  then compact state indicators when available: `*` for local changes,
+  `+N` for staged entries, and `↑N`/`↓N` for ahead/behind counts. Each
+  state token gets its own compact foreground color while preserving the
+  existing branch block background.
+- Row 1 splits the line with `#[align=left]` (the pending AI notify
+  queue, capped at 80
+  cells) and `#[align=right]` (usage, capped at 120 cells). `notify` is the
+  explicit-ack pending queue; live pane attention badges are a separate
+  state surface. Both
+  segments degrade gracefully when the cell budget is tight; see
+  [notify-queue.md](notify-queue.md) and [usage-tracking.md](usage-tracking.md)
+  for the per-segment tier ladder.
+
+A single tmux bind handles both lines:
+
+```tmux
+bind-key -n MouseDown1Status if-shell -F "#{==:#{mouse_status_range},window}" \
+  { select-window -t = } \
+  { run-shell "'<projmux>' statusbar click \"#{mouse_status_range}\" --mouse-window \"#{mouse_window}\"" }
+```
+
+`MouseDown1Status` fires from any line of a multi-line status bar with
+`#{mouse_status_range}` resolving to the range under the cursor.
+
+## Range catalogue
+
+| Range id | Row | Click action                              | Keyboard      |
+| -------- | --- | ----------------------------------------- | ------------- |
+| `session` | 0 | `projmux tmux popup-toggle sessionizer-sidebar` | `prefix s s` |
+| `pwd`     | 0 | copy `#{pane_current_path}` to tmux buffer and show a compact `Path copied` popup | `prefix s p`  |
+| `kube`    | 0 | `projmux tmux popup-toggle sessionizer`   | `prefix s k`  |
+| `git`     | 0 | `projmux tmux popup-toggle sessionizer`   | `prefix s g`  |
+| `usage`   | 1 | `display-popup -E -h 60% -w 80% -- projmux usage`, then wait for Enter | `prefix s u`  |
+| `notify`  | 1 | `projmux focus --target <newest> --source status-bar --kind segment-click`, then ack on focus success | `prefix s n`  |
+
+`notify` reads the pending queue only. For a live pane-state view that is
+independent of queued reminders, use `projmux attention list`. To explain why
+a live reply badge and the queue disagree, use `projmux notify list --live`.
+The notify segment renders the newest queued item as a single notification
+block: project, state (`NEED`/`INFO`/`WARN`/`CRIT`), optional agent, text,
+age, and `+N` for older pending entries. Window/pane ids are not shown in the
+compact status segment.
+`usage` deliberately opens the detailed `projmux usage` table popup; it is the
+clear action surface for the compact HUD bar.
+
+The path popup uses a short title, one-line copy status, the current path, and
+an `Enter closes this popup` prompt. If the tmux buffer write fails, it keeps
+the same compact surface with `Current path` as the title and a copy-unavailable
+message. The notification HUD detail surface (`Alt-2` / `User2`) opens the
+right-side notification popup with newest-first rows. The popup itself is
+untitled; when decoration mode is `symbol` or `emoji`, the bell appears before
+the fzf header text instead. Selecting a row still focuses and acknowledges
+that notification.
+
+Empty `#{mouse_status_range}` (a click on whitespace) falls through to
+`select-window -t @<mouse_window>` when `--mouse-window` is non-empty,
+otherwise it is a no-op. Unknown user range ids are non-specialized
+placeholder surfaces and no-op until a handler is wired into the dispatcher.
+
+## Keyboard chord
+
+```tmux
+bind-key s switch-client -T projmux-status
+bind-key -T projmux-status u run-shell '#{q:projmux} statusbar click usage'
+bind-key -T projmux-status n run-shell '#{q:projmux} statusbar click notify'
+bind-key -T projmux-status g run-shell '#{q:projmux} statusbar click git'
+bind-key -T projmux-status k run-shell '#{q:projmux} statusbar click kube'
+bind-key -T projmux-status p run-shell '#{q:projmux} statusbar click pwd'
+bind-key -T projmux-status s run-shell '#{q:projmux} statusbar click session'
+```
+
+The chord routes through the same dispatcher as the mouse click, so
+keyboard and mouse paths are functionally identical.
+
+## Click failure handling
+
+Every status-bar click runs from tmux's `run-shell`. A non-zero exit
+there triggers a tmux error popup, which is hostile UX for a casual
+click. Each handler therefore swallows runtime failures and surfaces
+them as `display-message` toasts:
+
+- `notify` click whose focus dispatch exits 2 (target unresolved):
+  keep the entry pending, toast `notify target gone; ack to clear`.
+- Any other focus failure: keep the entry, toast `focus failed:
+  <reason>`.
+- `session`, `kube`, or `git` popup launch failure: toast
+  `statusbar <range>: popup failed`.
+- `pwd` path popup failure: keep the copied path in the tmux paste
+  buffer when possible and fall back to a short `display-message`.
+- `usage` popup failure: fall back to inlining the rendered table
+  into a single `display-message`.
+
+`MouseX` / `MouseY` are accepted but not consumed today; the fields
+are wired through so click telemetry can land without changing the
+bind.
+
+## Customizing
+
+The status bar is generated by `projmux tmux print-config` /
+`print-app-config`. To change a segment, edit the generator (it
+emits a deterministic block per segment), regenerate, and re-apply:
+
+```sh
+projmux tmux apply
+```
+
+Settings > Icons & Decorations controls the optional decoration mode used by
+the path, git branch, and notification sidebar header. The persisted enum lives at
+`~/.config/projmux/statusbar-decoration`; valid values are `off` (default,
+font-safe), `symbol` (Nerd Font-style folder/GitHub/bell icons), and `emoji`.
+Settings also updates tmux `@projmux_statusbar_decoration` for the live
+server when run inside tmux.
+
+To add a new clickable segment:
+
+1. Add a `statusbarRangeID` constant in
+   `internal/app/statusbar.go`.
+2. Wire its handler into `dispatchTable`.
+3. Update the generator so the segment is wrapped in
+   `#[range=user|<id>]...#[norange]` on the chosen row.
+4. Add a chord key under `projmux-status` if a keyboard binding is
+   wanted.
+
+Custom user ranges can coexist with the built-in window-list range:
+the dispatcher detects the `window` / `window|<idx>` token before
+the user-range table, so a hostile range named `window` cannot
+shadow the built-in.