@projmux/darwin-arm64 0.4.3 → 0.4.5

package/README.md

@@ -7,6 +7,9 @@ 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.
 
+[![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)
 
 ## Why projmux
@@ -29,26 +32,6 @@ for a daily terminal workspace:
   self-contained tmux app, or install the generated snippet into your normal
   tmux server.
 
-## What's new in 0.4
-
-- **`projmux setup` / `projmux init`** — diagnose terminal key delivery,
-  then auto-merge the right CSI-u bindings into Ghostty or Windows
-  Terminal configs.
-- **`projmux doctor`** — runtime dependency report with minimum-version
-  enforcement (tmux 3.4, fzf 0.55).
-- **`projmux focus`** — unified switch-client dispatch shared by the
-  AI reply-ready flow and the status-bar notify click.
-- **Persistent notify queue** — `projmux notify push|list|ack|reconcile`
-  with TTL, severity, source, and target metadata. See
-  [notify-queue.md](docs/notify-queue.md).
-- **Authoritative usage tracking** — `projmux usage` reads Claude's
-  OAuth usage endpoint and Codex's local rollout `rate_limits`. See
-  [usage-tracking.md](docs/usage-tracking.md).
-- **Two-line clickable status bar** — row 0 keeps the native window
-  list (click a tab to switch), row 1 splits a notify HUD pill (left)
-  and a usage HUD bar (right). Both segments degrade gracefully on
-  narrow status budgets. See [statusbar.md](docs/statusbar.md).
-
 ## What It Does
 
 - Creates or switches to tmux sessions from project directories.
@@ -81,10 +64,14 @@ Open the app once, then use its generated tmux bindings to:
 
 ## Requirements
 
-- [Go 1.24+](https://go.dev/dl/) — required to install or build the binary.
+- [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.
-- [zsh](https://zsh.sourceforge.io/) — default shell of the generated app config (`projmux shell`).
+- 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.
@@ -92,40 +79,49 @@ Open the app once, then use its generated tmux bindings to:
 Desktop notifications: Linux uses `notify-send`; WSL routes Windows toasts via
 `powershell.exe`. Override either with `PROJMUX_NOTIFY_HOOK`.
 
-Run `projmux doctor` any time to verify everything is on `PATH` and that
-tmux/fzf meet the minimum supported versions.
+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`.
 
 ## Install
 
 ```sh
-go install github.com/crevissepartners/projmux/cmd/projmux@latest
+npm install -g projmux
 ```
 
-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`:
+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
-export PATH="$(go env GOPATH)/bin:$PATH"
+projmux version
 ```
 
-Verify:
+If npm is not a fit for your machine, install with Go:
 
 ```sh
-projmux version
+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 default project root projmux uses for picker and
-discovery. It is optional — when unset, projmux falls back to its built-in
-source-root discovery (`~/source`, `~/work`, `~/projects`, `~/src`, `~/code`,
-`~/source/repos`).
+`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="$HOME/source/repos"
+export PROJMUX_PROJDIR="/your/path"
 ```
 
-Add the line to `~/.zshrc` (or your shell's rc file). The resolved value is
+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.
 
@@ -138,20 +134,28 @@ search list, so they participate in discovery just like
 
 ```sh
 # Linux/macOS — primary repo + secondary search root
-export PROJMUX_PROJDIR="$HOME/source/repos:/srv/work/repos"
+export PROJMUX_PROJDIR="/main/repos:/srv/work/repos"
 ```
 
-#### Set the project root at install time
+#### Set the project root during setup
 
 ```sh
-PROJMUX_PROJDIR=/your/path go install github.com/crevissepartners/projmux/cmd/projmux@latest
-PROJMUX_PROJDIR=/your/path projmux tmux apply
+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.
 
+You can also manage the saved value interactively with
+`projmux settings > Project Picker > Project Root`. That screen shows the
+effective primary root and source (`PROJMUX_PROJDIR`, `@projmux_projdir`,
+saved, or not configured), shows when a saved value is shadowed by env/tmux,
+and lets you set a path directly, use the current project context, or clear the
+saved value. When no Project Root is configured, the direct-set prompt starts
+with `$HOME` as an editable fallback; it is not treated as the effective root
+until you save it.
+
 ### From source
 
 ```sh
@@ -173,13 +177,15 @@ projmux shell
 ```
 
 projmux owns this tmux server, its generated config, status bar, and popup
-bindings. 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` to see which sequences your
-terminal swallows, then `projmux init [terminal] --apply` (auto-detects when
-no terminal is given) to merge the right CSI-u bindings into your terminal
-config. Dotfiles users on multi-machine setups should pass
+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).
@@ -190,54 +196,46 @@ for the supported versions.
 
 ## Upgrading
 
-`projmux upgrade` reinstalls the binary via `go install`, atomically replaces
-the active file, and reapplies the live tmux config so a running `-L projmux`
-server picks up new bindings without a restart.
+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 upgrade                                  # @latest, replace + apply
-projmux upgrade --ref @v0.2.0                    # pin a specific tag
-projmux upgrade --ref @main                      # track a branch
-projmux upgrade --target /usr/local/bin/projmux  # replace another path
-projmux upgrade --no-apply                       # skip 'projmux tmux apply'
-projmux upgrade --dry-run                        # print the steps only
+projmux update check
 ```
 
-The upgrade reads `PROJMUX_PROJDIR` from the calling shell and memoizes the
-primary (first) path to `~/.config/projmux/projdir`, so the new binary keeps
-the same project root context as the one it replaces.
-
-Pass a new project root inline to atomically switch the binary and the saved
-projdir in one step:
-
-```sh
-PROJMUX_PROJDIR=/new/path projmux upgrade
-
-# Multi-path also works; only the primary entry is persisted to the saved file.
-PROJMUX_PROJDIR="/main/repos:/secondary/repos" projmux upgrade   # Linux/macOS
-# Windows: PROJMUX_PROJDIR="C:\main\repos;C:\secondary\repos"
-```
+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, `upgrade`, etc.), run `projmux help` or
+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. The default discovery logic favors common source locations such
-as `~/source`, `~/work`, `~/projects`, `~/src`, `~/code`, and `~/source/repos`
-when they exist. `projmux settings` also has `Project Picker > Add Project...`,
-which scans those filesystem roots up to depth 3 so projects outside `~` and
-`~rp` 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.
+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:
 
+- `Project Root` - set, change, or clear the saved primary root. This is the
+  one root used as the primary project context; env `PROJMUX_PROJDIR` and tmux
+  `@projmux_projdir` override the saved value until unset. If no root is
+  configured, the direct-set prompt pre-fills `$HOME` so the picker remains
+  usable without inventing an implicit saved root.
 - `+ 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
@@ -264,8 +262,8 @@ and troubleshooting.
 
 | Variable | Purpose |
 | --- | --- |
-| `PROJMUX_PROJDIR` | Default 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/default list. |
+| `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. |
@@ -316,6 +314,7 @@ More documentation:
 - [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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@projmux/darwin-arm64",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "macOS arm64 binary for projmux",
   "license": "MIT",
   "repository": {