@projmux/darwin-x64 0.4.2 → 0.4.4

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,14 +134,13 @@ 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
@@ -173,13 +168,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,50 +187,37 @@ 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:
@@ -264,8 +248,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 +300,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-x64",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "macOS x64 binary for projmux",
   "license": "MIT",
   "repository": {