projmux 0.4.3 → 0.4.5

package/README-ko.md

@@ -82,7 +82,8 @@ projmux shell
 - [Go 1.24+](https://go.dev/dl/) — binary 설치/빌드에 필요.
 - [tmux](https://github.com/tmux/tmux/wiki/Installing) **≥ 3.4** — workspace 런타임. 이전 버전은 `display-popup -T` 등 projmux 가 사용하는 기능이 없습니다.
 - [fzf](https://github.com/junegunn/fzf#installation) **≥ 0.55** — popup/sidebar picker. 멀티라인 피커가 `--marker-multi-line`, `--gap-line`, `--highlight-line` 을 사용하며 모두 0.55 까지 도입됐습니다.
-- [zsh](https://zsh.sourceforge.io/) — `projmux shell` 이 만드는 앱 tmux 설정의 기본 shell.
+- `bash`, `zsh`, `sh` 같은 Unix shell — `projmux shell` 이 만드는 앱 tmux
+  설정은 절대 경로 `$SHELL` 을 사용하고, 없으면 `/bin/sh` 로 fallback 합니다.
 - [git](https://git-scm.com/downloads) — branch/status segment.
 - `stty` — POSIX 터미널 제어, `projmux setup` 에서 사용. macOS/Linux 기본 시스템에 이미 포함, Windows 호스트에선 해당 없음.
 - [kubectl](https://kubernetes.io/docs/tasks/tools/) — 선택, Kubernetes status segment 사용 시에만.
@@ -114,16 +115,17 @@ projmux version
 
 ### 선택: `PROJMUX_PROJDIR`
 
-`PROJMUX_PROJDIR` 은 projmux 가 picker/탐색에서 기본으로 사용할 프로젝트
-루트입니다. 설정하지 않으면 projmux 가 내장된 source-root 탐색(`~/source`,
-`~/work`, `~/projects`, `~/src`, `~/code`, `~/source/repos`) 으로 자동
-fallback 합니다.
+`PROJMUX_PROJDIR` 은 명시적으로 설정했을 때 projmux 가 picker/탐색에서 사용할
+primary 프로젝트 루트입니다. 설정하지 않으면 projmux 는 canonical repo root 를
+가정하지 않습니다. 탐색은 pin, 살아 있는 session, saved workdirs, 그리고 존재할
+때만 참고하는 약한 common-folder probe(`~/source`, `~/work`, `~/projects`,
+`~/src`, `~/code`) 를 사용합니다.
 
 ```sh
-export PROJMUX_PROJDIR="$HOME/source/repos"
+export PROJMUX_PROJDIR="/your/path"
 ```
 
-`~/.zshrc` (또는 사용 중인 shell rc 파일) 에 한 줄 추가하면 됩니다. 첫 실행
+`~/.bashrc`, `~/.zshrc` 또는 사용 중인 shell rc 파일에 한 줄 추가하면 됩니다. 첫 실행
 이후에는 `~/.config/projmux/projdir` 에 memoize 되므로, 이후 env 가 없어도 같은
 루트가 유지됩니다.
 
@@ -134,7 +136,7 @@ prepend 됩니다. saved 파일에는 primary 만 memoize 됩니다.
 
 ```sh
 # Linux/macOS — primary repo + 보조 검색 root
-export PROJMUX_PROJDIR="$HOME/source/repos:/srv/work/repos"
+export PROJMUX_PROJDIR="/main/repos:/srv/work/repos"
 ```
 
 #### 최초 설치 시 projdir 지정
@@ -147,6 +149,14 @@ PROJMUX_PROJDIR=/your/path projmux tmux apply
 env 가 살아있는 첫 실행이 `~/.config/projmux/projdir` 에 값을 기록하므로,
 이후 새 shell 에서 env 없이도 같은 루트가 유지됩니다.
 
+저장된 값은 `projmux settings > Project Picker > Project Root` 에서도 관리할
+수 있습니다. 이 화면은 현재 effective primary root 와 source
+(`PROJMUX_PROJDIR`, `@projmux_projdir`, saved, not configured)를 보여주고,
+saved 값이 env/tmux 값에 shadow 되는 상황을 따로 표시합니다. 경로를 직접
+입력하거나 현재 project context 를 저장하거나 saved 값을 지울 수 있습니다.
+Project Root 가 설정되지 않은 경우 직접 입력 prompt 는 `$HOME` 을 수정 가능한
+fallback 으로 채웁니다. 저장하기 전까지는 effective root 로 간주하지 않습니다.
+
 ### 소스에서 빌드
 
 ```sh
@@ -217,16 +227,22 @@ PROJMUX_PROJDIR="/main/repos:/secondary/repos" projmux upgrade   # Linux/macOS
 ## 프로젝트 탐색 방식
 
 `projmux switch`는 pinned directory, 현재 살아 있는 tmux session, 발견된
-project root를 합쳐 후보를 만듭니다. 기본 탐색은 존재하는 경우 `~/source`,
-`~/work`, `~/projects`, `~/src`, `~/code`, `~/source/repos` 같은 일반적인
-소스 디렉터리를 우선합니다. `projmux settings`의 `Project Picker > Add
-Project...`는 이 filesystem root를 depth 3까지 스캔하므로 `~`나 `~rp` 밖의
-프로젝트도 picker 후보로 추가할 수 있습니다. 세션 이름은 정규화된 디렉터리
-경로에서 만들어지므로 같은 프로젝트는 다시 실행해도 같은 tmux 세션으로 연결됩니다.
+project root를 합쳐 후보를 만듭니다. 명시적인 검색 root 가 없으면 기본 탐색은
+존재하는 경우 `~/source`, `~/work`, `~/projects`, `~/src`, `~/code` 같은 약한
+common-folder probe 를 참고합니다. canonical `~/source/repos` root 는 가정하지
+않습니다. `projmux settings`의 `Project Picker > Add Project...`는 filesystem
+root를 depth 3까지 스캔하므로 약한 probe 밖의 프로젝트도 picker 후보로 추가할
+수 있습니다. 세션 이름은 정규화된 디렉터리 경로에서 만들어지므로 같은 프로젝트는
+다시 실행해도 같은 tmux 세션으로 연결됩니다.
 
 탐색 root를 영구적으로 커스터마이즈하려면 Project Picker 섹션의 다음 항목을
 사용하세요:
 
+- `Project Root` - saved primary root 를 설정/변경/해제합니다. Project Root 는
+  primary project context 로 쓰는 한 개의 루트이며, `PROJMUX_PROJDIR` env 와
+  tmux `@projmux_projdir` 값이 있으면 saved 값보다 우선됩니다. root 가
+  설정되지 않았을 때 직접 입력 prompt 는 `$HOME` 을 미리 채워 picker 를 열 수
+  있게 하지만, 저장 전에는 암묵적인 saved root 로 쓰지 않습니다.
 - `+ Add Workdir...` - 디렉터리 하나를 saved workdirs 목록에 누적 추가.
 - `Workdirs` - 저장된 workdir 검토/삭제. 환경변수 `PROJMUX_MANAGED_ROOTS` /
   `TMUX_SESSIONIZER_ROOTS`가 설정되어 있으면 read-only 행으로 함께 표시되어
@@ -253,8 +269,8 @@ projmux는 새 tmux 세션을 만들 때마다 선택적 사용자 스크립트
 
 | 변수 | 용도 |
 | --- | --- |
-| `PROJMUX_PROJDIR` | 현재 shell 의 기본 프로젝트 루트. OS-native PATH 형식 multi-value 지원: 첫 항목이 primary repo root (saved 파일에 memoize), 이후 항목은 managed-roots 검색 목록 앞에 prepend. |
-| `PROJMUX_MANAGED_ROOTS` | 콜론 구분 검색 root 목록. saved/default 보다 우선. |
+| `PROJMUX_PROJDIR` | 현재 shell 의 명시적 primary 프로젝트 루트. OS-native PATH 형식 multi-value 지원: 첫 항목이 primary repo root (saved 파일에 memoize), 이후 항목은 managed-roots 검색 목록 앞에 prepend. |
+| `PROJMUX_MANAGED_ROOTS` | 콜론 구분 검색 root 목록. saved/heuristic 목록보다 우선. |
 | `PROJMUX_NOTIFY_HOOK` | AI desktop notification 을 내장 sender 대신 받는 외부 실행 파일. |
 | `PROJMUX_USAGE_STATE_DIR` | AI 사용량 snapshot 캐시 디렉터리. 기본값은 `<state>/projmux/usage`. Dropbox/iCloud 같은 동기화 위치를 가리키게 하면 여러 머신 사이에서 authoritative 사용량을 공유할 수 있다. |
 | `PROJMUX_USAGE_DEBUG` | 비어 있지 않으면 `projmux status usage` 의 adapter 오류를 swallow 하지 않고 stderr 로 surface 한다. |

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",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "tmux project session manager",
   "license": "MIT",
   "homepage": "https://github.com/crevissepartners/projmux#readme",
@@ -22,10 +22,10 @@
     "LICENSE"
   ],
   "optionalDependencies": {
-    "@projmux/darwin-arm64": "0.4.3",
-    "@projmux/darwin-x64": "0.4.3",
-    "@projmux/linux-arm64": "0.4.3",
-    "@projmux/linux-x64": "0.4.3"
+    "@projmux/darwin-arm64": "0.4.5",
+    "@projmux/darwin-x64": "0.4.5",
+    "@projmux/linux-arm64": "0.4.5",
+    "@projmux/linux-x64": "0.4.5"
   },
   "scripts": {
     "package:npm": "scripts/package-npm.sh",