mx bin ls: clear PATH setup instructions (2.8.0)

apps/cli/src/commands/bin.ts

@@ -2,7 +2,7 @@ import { readdirSync, statSync } from 'node:fs';
 import * as path from 'node:path';
 import { delimiter } from 'node:path';
 import { requireRuntime, runtimeBinDir, listRuntimeBins, MxError } from '@mx/core';
-import { emit, dim, bold, warn, tildify } from '../output';
+import { emit, dim, bold, check, warn, tildify } from '../output';
 import { templatesDir } from '../paths';
 import type { Flags } from '../args';
 
@@ -61,12 +61,17 @@ export function dispatchBin(positionals: string[], flags: Flags): void {
               console.log(`  ${bold(b.name.padEnd(nameW))}  ${origin}${flag}`);
             }
           }
-          // Nudge the user to wire bin/ onto PATH if it isn't already.
+          // Always close with PATH guidance — confirm when it's wired up, or
+          // spell out exactly how to wire it (mx can't edit your shell config).
           console.log();
           if (onPath(dir)) {
-            console.log(`  ${dim(`${tildify(dir)} is on your PATH`)}`);
+            console.log(`  ${check()} ${dim(`${tildify(dir)} is on your PATH — these run as commands anywhere`)}`);
           } else {
-            console.log(`  ${dim(`not on PATH — add: export PATH="$(mx bin path):$PATH"`)}`);
+            console.log(`  ${warn()} ${dim(`${tildify(dir)} is not on your PATH yet.`)}`);
+            console.log(`  ${dim('To run these as commands, add this line to your shell startup file')}`);
+            console.log(`  ${dim('(~/.zshrc, ~/.bashrc, …) and restart your shell:')}`);
+            console.log();
+            console.log(`      ${bold('export PATH="$(mx bin path):$PATH"')}`);
           }
         },
         // Porcelain: the raw list plus the dir and whether it's on PATH.

docs/commands.md

@@ -388,7 +388,7 @@ With `--force`, prints a loud irreversibility warning to stderr before executing
 
 Manage the runtime-wide `bin/` directory — utility executables shared across every work, meant to be on your `PATH`. mx ships some (currently `dcs` and `lcs` — delete / list Claude Code sessions by name) and you can drop your own in; any executable file is picked up.
 
-- **`mx bin ls`** (or bare `mx bin`) — list the bins, each tagged `mx` (shipped) or `user` (yours), with a warning on any that aren't executable, plus a note on whether `bin/` is currently on your `PATH`. Porcelain returns `{ "dir", "onPath", "bins": [{ "name", "path", "executable", "shipped" }] }`.
+- **`mx bin ls`** (or bare `mx bin`) — list the bins, each tagged `built-in` (shipped) or `user` (yours), with a warning on any that aren't executable. It ends with PATH guidance: a ✓ when `bin/` is already on your `PATH`, otherwise a step-by-step instruction to add `export PATH="$(mx bin path):$PATH"` to your shell startup file (`~/.zshrc`, `~/.bashrc`, …). Porcelain returns `{ "dir", "onPath", "bins": [{ "name", "path", "executable", "shipped" }] }`.
 - **`mx bin path`** — print the absolute `bin/` directory, for wiring it onto `PATH`:
 
   ```

docs/history.md

@@ -2,6 +2,10 @@
 
 What each release brought. Reverse-chronological. Dates reflect when the corresponding tag was pushed.
 
+## 2.8.0 — 2026-06-29
+
+**`mx bin ls` spells out the PATH setup.** When `<runtime>/bin/` isn't on your `PATH`, the listing now ends with a clear, multi-line instruction — add `export PATH="$(mx bin path):$PATH"` to your shell startup file (`~/.zshrc`, `~/.bashrc`, …) and restart — instead of a terse one-liner. When it is on `PATH`, it confirms with a ✓. CLI-only cosmetic change.
+
 ## 2.7.0 — 2026-06-29
 
 Four changes in one release: a runtime-wide `bin/`, `mx update` auto-syncing, removal of the redundant per-work `bin/`, and `-o` opening only the Terminal.

npm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roulabs/mx",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "mx — run several features in parallel across shared repos using git worktrees",
   "type": "module",
   "bin": {