claude-nomad 0.25.5 → 0.26.1

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [0.26.1](https://github.com/funkadelic/claude-nomad/compare/v0.26.0...v0.26.1) (2026-05-27)
+
+
+### Fixed
+
+* **preview:** replace diffJsonStrings parallel walk with jsdiff LCS line diff ([#159](https://github.com/funkadelic/claude-nomad/issues/159)) ([d9c0dca](https://github.com/funkadelic/claude-nomad/commit/d9c0dcae7b417d069e826ce3b825e9f23115ba2d))
+* **remap:** fail closed on path-map collisions in remapPush before any write ([#156](https://github.com/funkadelic/claude-nomad/issues/156)) ([db33157](https://github.com/funkadelic/claude-nomad/commit/db33157faa02b5439278ae4e92a02bd671faee72))
+
+
+### Changed
+
+* **codeql:** skip analysis on release-please PR branches ([#160](https://github.com/funkadelic/claude-nomad/issues/160)) ([2bfed46](https://github.com/funkadelic/claude-nomad/commit/2bfed463ccd76f6331e5ab775bbd5d19df2898e9))
+* **tests:** skip PR-time test matrix on release-please PR branches ([#158](https://github.com/funkadelic/claude-nomad/issues/158)) ([222e27b](https://github.com/funkadelic/claude-nomad/commit/222e27b2643382136505f72e148c17c7ecb7a08f))
+
+## [0.26.0](https://github.com/funkadelic/claude-nomad/compare/v0.25.5...v0.26.0) (2026-05-27)
+
+
+### Added
+
+* **doctor:** readability pass on doctor output ([#154](https://github.com/funkadelic/claude-nomad/issues/154)) ([d4bb912](https://github.com/funkadelic/claude-nomad/commit/d4bb912180dbae8e12dfafb4ddd71abb54d0d441))
+
 ## [0.25.5](https://github.com/funkadelic/claude-nomad/compare/v0.25.4...v0.25.5) (2026-05-27)
 
 

package/README.md

@@ -12,15 +12,16 @@
 **Your entire Claude Code setup, on every machine. History included, every push secret-scanned.**
 
 Open Claude Code on a second machine and it is a blank slate: none of your custom agents, slash
-commands, tuned settings, or past conversations. claude-nomad keeps all of it in sync through a
+commands, tuned settings, or past conversations. **claude-nomad** keeps all of it in sync through a
 private Git repo you control. `nomad push` on one machine, `nomad pull` on the next, and everything
 is there, conversations included.
 
-- **Resume your sessions on any machine.** Start a conversation on your desktop and pick it up on
-  your laptop. claude-nomad remaps the file paths Claude Code embeds in every transcript, so your
-  history follows you instead of getting stranded on the box where it started.
+- **Resume your Claude Code [sessions](https://code.claude.com/docs/en/agent-sdk/sessions) on any
+  machine.** Start a conversation on your desktop and pick it up on your laptop. **claude-nomad**
+  remaps the file paths Claude Code embeds in every transcript, so your history follows you instead
+  of getting stranded on the box where it started.
 - **Secret-scanned, private by default.** Your `~/.claude/` also holds OAuth tokens, MCP
-  credentials, and the full text of every conversation, so claude-nomad is deliberate about what
+  credentials, and the full text of every conversation, so **claude-nomad** is deliberate about what
   leaves your machine: credentials and ephemeral state never sync, only an explicit allow-list of
   paths is pushed, and everything that does go up is scanned by
   [gitleaks](https://github.com/gitleaks/gitleaks) before it leaves your machine; the push aborts on
@@ -30,7 +31,7 @@ is there, conversations included.
   and follow you everywhere. Per-machine tweaks like model choice, MCP URLs, and env vars merge on
   top instead of clobbering your shared defaults.
 
-Not dotfiles, not rsync. claude-nomad understands Claude Code's state, so your session history
+Not dotfiles, not rsync. **claude-nomad** understands Claude Code's state, so your session history
 survives different file paths and your secrets never ride along.
 
 For anyone running Claude Code on more than one machine: a laptop and a desktop, a Mac and a WSL
@@ -65,8 +66,8 @@ box, a personal rig and a work machine. [Get started in three steps.](#quickstar
 
 ## Quickstart
 
-If you already have a private claude-nomad mirror (see [Setup](#setup) for the one-time bootstrap),
-adding a new host is three steps:
+If you already have a private **claude-nomad** mirror (see [Setup](#setup) for the one-time
+bootstrap), adding a new host is three steps:
 
 ```bash
 $ npm i -g claude-nomad
@@ -97,8 +98,8 @@ First-host bootstrap and the safe-migration sequence for a populated `~/.claude/
 
 ## How it works (two-repo model)
 
-claude-nomad is a **tool**, not a config store. You maintain a separate **private** repo that holds
-your actual config (`CLAUDE.md`, agents, skills, settings overrides, session transcripts). The
+**claude-nomad** is a **tool**, not a config store. You maintain a separate **private** repo that
+holds your actual config (`CLAUDE.md`, agents, skills, settings overrides, session transcripts). The
 tool's source and your config end up coexisting in one working tree on each host.
 
 ```text
@@ -205,8 +206,8 @@ cleanly instead of creating an orphan `~/.claude/projects/TBD/`. Replace each `"
 path when you bring up that host.
 
 On `push`, sessions in `~/.claude/projects/-Users-you-code-my-example-repo/` get copied to
-`shared/projects/my-example-repo/`. On `pull` on another machine, they get copied to that host's
-encoded path. `claude --resume` then finds them (see
+`shared/projects/my-example-repo/`. On `nomad pull` on another machine, they get copied to that
+host's encoded path. `claude --resume` then finds them (see
 [What does NOT sync (deliberate trade-offs)](#what-does-not-sync-deliberate-trade-offs) for the
 cross-OS cwd-binding gotcha).
 
@@ -215,10 +216,10 @@ working unchanged. Each value is an array of directory or root-file names (e.g.
 `CLAUDE.md`) checked against `SUPPORTED_EXTRAS` in `src/config.ts`; anything outside that whitelist
 is skipped with a log line, so an unrecognized name cannot widen the sync surface.
 
-On `push`, opted-in content at `<localRoot>/<name>` (a directory subtree or a single file) is copied
-to `shared/extras/<logical>/<name>` and goes through the same staged-tree gitleaks scan as
-everything else. On `pull`, the reverse copy runs after `git pull --rebase`, and just before it
-overwrites your working tree a divergence check compares the incoming content against your local
+On `nomad push`, opted-in content at `<localRoot>/<name>` (a directory subtree or a single file) is
+copied to `shared/extras/<logical>/<name>` and goes through the same staged-tree gitleaks scan as
+everything else. On `nomad pull`, the reverse copy runs after `git pull --rebase`, and just before
+it overwrites your working tree a divergence check compares the incoming content against your local
 copy and prints a per-file WARN naming anything that differs.
 
 Your existing local content is backed up under `~/.cache/claude-nomad/backup/<ts>/extras/` before
@@ -229,10 +230,11 @@ the pull copy lands, so an unexpected overwrite is always recoverable.
 `settings.base.json` holds portable defaults (model, permissions, plugins).
 `hosts/<NOMAD_HOST>.json` holds machine-specific patches. They're deep-merged on every pull (scalars
 override, objects merge recursively, arrays replace). Keys that used to be force-marked per-host
-because they embedded absolute paths (`statusLine.command`, `hooks`) can live in base if you write
-the commands with `$HOME` (e.g. `"command": "node \"$HOME/.claude/my-statusline.cjs\""`); Claude
-Code runs them through a shell so shell expansion applies. Reserve per-host files for truly
-machine-specific values (env, MCP URLs, host-only model overrides).
+because they embedded absolute paths (`statusLine.command`, `hooks`) can live in
+`settings.base.json` if you write the commands with `$HOME` (e.g.
+`"command": "node \"$HOME/.claude/my-statusline.cjs\""`); Claude Code runs them through a shell so
+shell expansion applies. Reserve per-host files for truly machine-specific values (env, MCP URLs,
+host-only model overrides).
 
 `shared/settings.base.json`:
 
@@ -243,7 +245,7 @@ machine-specific values (env, MCP URLs, host-only model overrides).
 }
 ```
 
-`hosts/<your-wsl-host>.json`:
+`hosts/<your-other-host>.json`:
 
 ```json
 {
@@ -252,7 +254,7 @@ machine-specific values (env, MCP URLs, host-only model overrides).
 }
 ```
 
-Result on that host: opus model, the local Ollama env var, plus the shared permissions array.
+Results on `your-other-host`: opus 4.7, the local Ollama env var, plus the shared permissions array.
 
 > [!CAUTION] Never hand-edit `~/.claude/settings.json` on a synced host. It's regenerated on every
 > `nomad pull` from base + host, so your edits will be clobbered. Edit the base or host file in the
@@ -273,8 +275,8 @@ Read these before adopting so you opt in with eyes open.
   surface. Unsafe path-map values (path-traversal in `logical` keys, non-absolute or unnormalized
   `localRoot` values) abort the run before any file is touched, so a malformed entry fails loudly
   instead of corrupting state.
-- **Cross-OS `claude --resume` cwd binding.** Sessions embed the cwd where they were created, so the
-  picker's `cd ... && claude --resume <id>` line fails on a different host. Use
+- **Cross-OS `claude --resume` cwd binding.** Sessions embed the cwd where they were created, so
+  Claude Code's picker's `cd ... && claude --resume <id>` line fails on a different host. Use
   `nomad doctor --resume-cmd <id>` for a host-local equivalent (see
   [Cross-OS resume](#cross-os-resume)). The sidecar approach preserves transcript byte-equality.
 - **Empty directories don't survive sync.** Git doesn't track empty dirs; `nomad doctor` reports
@@ -293,13 +295,14 @@ Read these before adopting so you opt in with eyes open.
   it is absent or mismatched)
 - A **private** GitHub repo (or any Git remote you control)
 
-**Optional:**
+**Optional, but recommended:**
 
-- `gh` (GitHub CLI), used only by `nomad init` to auto-disable Actions on the private repo; if it is
-  missing or unauthenticated, init prints a manual fallback tip and continues
-- `curl`, used only by the version/update check (the `nomad doctor` latest-release line and the
-  post-`nomad update` check); it degrades silently when curl is absent or offline, so the rest of
-  the CLI works without it
+- `gh` ([GitHub CLI](https://cli.github.com/)), used only by `nomad init` to auto-disable Actions on
+  the private repo; if it is missing or unauthenticated, init prints a manual fallback tip and
+  continues
+- [curl](https://curl.se/), used only by the version/update check (the `nomad doctor` latest-release
+  line and the post-`nomad update` check); it degrades silently when curl is absent or offline, so
+  the rest of the CLI works without it
 
 ## Setup
 
@@ -329,7 +332,7 @@ enforces an Actions policy upstream).
 
 > [!WARNING] If you ever flip the mirror to public, both protections evaporate: CI starts firing on
 > every `nomad push` against `main`, and your session transcripts (which include conversation
-> content) become world-readable. Keep it private.
+> content) become world-readable. **Keep it private.**
 
 ### Bootstrap
 
@@ -342,10 +345,10 @@ $ gh repo create <your-username>/claude-nomad --private
 # 2. Copy the public tool into your private repo. A bare clone followed by a
 #    mirror push makes a complete, independent copy (every branch and tag) with
 #    no fork link back to upstream, which is what lets you keep it private. Once, ever.
-$ git clone --bare git@github.com:funkadelic/claude-nomad.git /tmp/cn.git # download a full copy
-$ cd /tmp/cn.git
+$ git clone --bare git@github.com:funkadelic/claude-nomad.git /tmp/claude-nomad.git # download a full copy
+$ cd /tmp/claude-nomad.git
 $ git push --mirror git@github.com:<your-username>/claude-nomad.git # upload it to your private repo
-$ cd .. && rm -rf /tmp/cn.git
+$ cd .. && rm -rf /tmp/claude-nomad.git
 
 # 3. Install the CLI globally and clone your private copy. Repeat on every host.
 $ npm i -g claude-nomad
@@ -380,9 +383,6 @@ $ nomad init
 # starting point. Stages shared/ and writes hosts/<NOMAD_HOST>.json from
 # your current ~/.claude/settings.json. Does NOT touch the originals.
 $ nomad init --snapshot
-
-# Either form accepts --keep-actions to skip the auto-disable.
-$ nomad init --keep-actions
 ```
 
 `nomad init` refuses to clobber existing scaffold artifacts, so re-running on a populated repo is a
@@ -533,9 +533,9 @@ point under your npm prefix's `bin/`), then delete the alias line from your shel
 | `nomad doctor --check-shared`    | Read-only gitleaks preflight: stages the session transcripts a `push` would publish into a temp tree and scans them, failing (`✗`, exit 1) per affected session with rotate-and-scrub guidance. Skips with a `⚠︎` when gitleaks is not on PATH. See [Recovery flow: gitleaks FATAL on a session JSONL](#recovery-flow-gitleaks-fatal-on-a-session-jsonl). |
 | `nomad --version`                | Print the installed CLI version as bare semver to stdout; exits 0. Used by the npm-publish smoke test and useful for ad-hoc upgrade checks.                                                                                                                                                                                                              |
 
-The version-check emits ``⚠︎ version: <local> -> <latest> (run `nomad update`)`` when the local
-install is behind the latest upstream release, and `✓ version: <local> (latest)` when current. It
-silently skips on network failures.
+The version-check emits ``⚠︎ claude-nomad: <local> -> <latest> (run `nomad update`)`` when the local
+install is behind the latest upstream release, and `✓ claude-nomad: <local> (latest)` when current.
+It silently skips on network failures.
 
 Two further `⚠︎`-only drift checks run in `nomad doctor`. The gitleaks version-drift line
 `⚠︎ gitleaks: <local> -> <pinned> (...)` fires when the local gitleaks major.minor differs from the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-nomad",
-  "version": "0.25.5",
+  "version": "0.26.1",
   "type": "module",
   "description": "Sync Claude Code config (~/.claude/) across machines via a private Git repo, with path remapping and per-host settings overrides.",
   "keywords": [
@@ -80,6 +80,7 @@
     "vitest": "^4.1.6"
   },
   "dependencies": {
+    "diff": "^9.0.0",
     "picocolors": "^1.1.1",
     "tsx": "^4.22.2"
   }

package/src/commands.doctor.check-shared.scan.ts

@@ -14,7 +14,7 @@
 
 import { join } from 'node:path';
 
-import { green, red, okGlyph, failGlyph } from './color.ts';
+import { green, red, dim, okGlyph, failGlyph } from './color.ts';
 import { addItem, type DoctorSection } from './commands.doctor.format.ts';
 import { CLAUDE_HOME } from './config.ts';
 import { type Finding, partitionFindings, scanStagedTree } from './push-gitleaks.ts';
@@ -47,16 +47,16 @@ function reportSessionFindings(
 ): void {
   for (const [sid, counts] of bySession) {
     const summary = [...counts.entries()].map(([rule, n]) => `${rule} (${n})`).join(', ');
-    addItem(section, `${red(failGlyph)} session ${sid}: ${summary}`);
+    addItem(section, `${red(failGlyph)} ${red(summary)} in session ${sid}`);
     const logical = logicalBySession.get(sid);
     /* c8 ignore next -- false branch is defensive; every bySession sid is keyed in logicalBySession */
     if (logical !== undefined) {
       addItem(
         section,
-        `  rotate the credential, then scrub ${scrubPath(logical, sid, logicalToEncoded)}`,
+        `  ${dim(`rotate the credential, then scrub ${scrubPath(logical, sid, logicalToEncoded)}`)}`,
       );
     }
-    addItem(section, `  false positive? add a pattern to .gitleaks.toml`);
+    addItem(section, `  ${dim('false positive? add a pattern to .gitleaks.toml')}`);
   }
   process.exitCode = 1;
 }
@@ -70,7 +70,7 @@ function reportSessionFindings(
  */
 function reportOtherFindings(section: DoctorSection, other: Finding[]): void {
   for (const f of other) {
-    addItem(section, `${red(failGlyph)} leak in ${f.File}: ${f.RuleID}`);
+    addItem(section, `${red(failGlyph)} ${red(f.RuleID)} leak in ${f.File}`);
   }
   process.exitCode = 1;
 }
@@ -111,6 +111,29 @@ function buildLogicalBySession(findings: Finding[]): Map<string, string> {
   return logicalBySession;
 }
 
+/**
+ * Emit a deduplicated description legend in the footer: one `[rule-id]:
+ * description` row per distinct RuleID across all findings, set off by a blank
+ * line before and after. Sourced from the `Description` gitleaks bakes into
+ * each finding, so it needs no network; rules whose description is absent
+ * (older gitleaks, custom rules) are skipped, and the whole block (including
+ * the surrounding blanks) is omitted when no descriptions are available. The
+ * legend lives in the footer so a rule hit across many files or sessions
+ * (e.g. `sonar-api-token`) is explained once, not per occurrence.
+ */
+function emitDescriptionLegend(section: DoctorSection, findings: Finding[]): void {
+  const descByRule = new Map<string, string>();
+  for (const f of findings) {
+    if (f.Description && !descByRule.has(f.RuleID)) descByRule.set(f.RuleID, f.Description);
+  }
+  if (descByRule.size === 0) return;
+  addItem(section, '');
+  for (const [rule, desc] of descByRule) {
+    addItem(section, `  ${red(`[${rule}]`)}: ${dim(desc)}`);
+  }
+  addItem(section, '');
+}
+
 /**
  * Scan the staged temp tree through the shared `scanStagedTree` and emit the
  * result rows. Isolates the deepest nesting from `reportCheckShared`: the scan
@@ -155,4 +178,5 @@ export function scanAndReport(
   if (bySession.size > 0) {
     reportSessionFindings(section, bySession, buildLogicalBySession(findings), logicalToEncoded);
   }
+  emitDescriptionLegend(section, findings);
 }

package/src/commands.doctor.checks.pathmap.ts

@@ -13,7 +13,7 @@ import { encodePath } from './utils.json.ts';
  * `process.exitCode = 1`. Read-only: FAIL lines stay on stdout.
  */
 
-/** Emits the mapped-projects header for the current host and one line per mapped project. */
+/** Emits the mapped-projects header for the current host and one indented child line per mapped project. */
 function reportMappedProjects(section: DoctorSection, map: PathMap): void {
   const mapped = Object.entries(map.projects).filter(([, hosts]) => hosts[HOST]);
   addItem(
@@ -21,7 +21,7 @@ function reportMappedProjects(section: DoctorSection, map: PathMap): void {
     `${dim(infoGlyph)} mapped projects for ${cyan(HOST)}: ${dim(String(mapped.length))}`,
   );
   for (const [name, hosts] of mapped) {
-    addItem(section, `${dim(infoGlyph)} ${name} -> ${blue(hosts[HOST])}`);
+    addItem(section, `      ${name} -> ${blue(hosts[HOST])}`);
   }
 }
 

package/src/commands.doctor.checks.repo.ts

@@ -43,7 +43,7 @@ export function isOverrideActive(): boolean {
  * Pushes the host identity (info) and the two key path lines (repo and
  * claude-home) with gutter glyphs. Path presence is reported via warnGlyph
  * (not failGlyph) so an absent CLAUDE_HOME does not flip sectionFailed to
- * decorate the Host header with `✘`. The authoritative empty-repo FAIL is
+ * decorate the Host header with a fail glyph. The authoritative empty-repo FAIL is
  * owned by reportRepoState; these two lines remain informational and do
  * NOT mutate process.exitCode.
  */
@@ -83,6 +83,16 @@ export function reportRepoState(section: DoctorSection): void {
   }
 }
 
+/**
+ * True when the repo has a `shared/<name>` source for this link. `applySharedLinks`
+ * only creates a symlink when this source exists, so when it does NOT, an absent
+ * or dangling link in `~/.claude/` is expected (nothing to sync), not a problem to
+ * fix. Doctor uses this to downgrade those rows from a warn to an info note.
+ */
+function repoHasSharedSource(name: string): boolean {
+  return existsSync(join(REPO_HOME, 'shared', name));
+}
+
 /**
  * Resolve the display item and optional exit-code side-effect for a single
  * shared-link path. Returns `{ line, fail }` where `fail` true means the
@@ -99,7 +109,12 @@ function classifySharedLink(name: string, p: string): { line: string; fail: bool
   } catch (err) {
     const code = (err as NodeJS.ErrnoException).code;
     if (code === 'ENOENT') {
-      return { line: `${yellow(warnGlyph)} ${name}: missing`, fail: false };
+      return repoHasSharedSource(name)
+        ? {
+            line: `${yellow(warnGlyph)} ${name}: missing (run \`nomad pull\` to restore)`,
+            fail: false,
+          }
+        : { line: `${dim(infoGlyph)} ${name}: not synced (nothing in shared/)`, fail: false };
     }
     return { line: `${red(failGlyph)} ${name}: could not stat (${String(code)})`, fail: true };
   }
@@ -112,7 +127,10 @@ function classifySharedLink(name: string, p: string): { line: string; fail: bool
 /**
  * Resolve the display item for a path already confirmed to be a symlink.
  * Follows the link via statSync; a throw means the target is missing or
- * unreadable. Returns `{ line, fail: false }` (symlink issues are WARN, not FAIL).
+ * unreadable. Never FAILs (`fail: false`): a dangling link whose source still
+ * lives in the repo is a WARN with a `nomad pull` hint, a dangling link whose
+ * source is gone from the repo is an info note (stale, safe to remove), and a
+ * non-ENOENT stat error is a WARN naming the code.
  */
 function classifySymlinkTarget(name: string, p: string): { line: string; fail: boolean } {
   try {
@@ -121,10 +139,15 @@ function classifySymlinkTarget(name: string, p: string): { line: string; fail: b
   } catch (err) {
     const code = (err as NodeJS.ErrnoException).code;
     if (code === 'ENOENT') {
-      return {
-        line: `${yellow(warnGlyph)} ${name}: broken symlink (target missing)`,
-        fail: false,
-      };
+      return repoHasSharedSource(name)
+        ? {
+            line: `${yellow(warnGlyph)} ${name}: broken symlink (target missing, run \`nomad pull\`)`,
+            fail: false,
+          }
+        : {
+            line: `${dim(infoGlyph)} ${name}: stale symlink (no longer in shared/, safe to remove)`,
+            fail: false,
+          };
     }
     return {
       line: `${yellow(warnGlyph)} ${name}: symlink target unreadable (${String(code)})`,
@@ -135,13 +158,15 @@ function classifySymlinkTarget(name: string, p: string): { line: string; fail: b
 
 /**
  * Emits a per-entry status line for each name in SHARED_LINKS
- * (okGlyph/warnGlyph/failGlyph). A non-symlink blocks sync and FAILs via
- * process.exitCode. TOCTOU-safe: lstatSync is wrapped in try/catch so a path
+ * (okGlyph/warnGlyph/infoGlyph/failGlyph). A non-symlink blocks sync and FAILs
+ * via process.exitCode. TOCTOU-safe: lstatSync is wrapped in try/catch so a path
  * that vanishes or becomes unreadable between the probe and the stat yields a
- * row instead of an unhandled throw that aborts the whole doctor run. A symlink
- * whose target cannot be resolved is a WARN (broken-symlink for a missing
- * target, target-unreadable otherwise), never a healthy OK, so a dangling or
- * unreadable link is not masked.
+ * row instead of an unhandled throw that aborts the whole doctor run. Severity
+ * keys off whether the repo still has a `shared/<name>` source: an absent or
+ * dangling link is a WARN with a `nomad pull` hint when the source exists (a
+ * real out-of-sync state), and a calm info note when it does not (nothing to
+ * sync). A symlink whose target cannot be resolved is never a healthy OK, so a
+ * dangling or unreadable link is not masked.
  */
 export function reportSharedLinks(section: DoctorSection): void {
   for (const name of SHARED_LINKS) {

package/src/commands.doctor.format.ts

@@ -70,17 +70,32 @@ function sectionFailed(s: DoctorSection): boolean {
  * headers with a red `✗ ` glyph (U+2717, same as the per-item FAIL glyph so
  * `grep -F '✗'` catches both row and header failures), and writes one blank
  * line between rendered sections (no leading or trailing blank).
+ *
+ * An empty-string item renders as a true blank line (no tree connector), which
+ * lets a reporter set off a footer block (e.g. the `--check-shared` description
+ * legend) with vertical whitespace. The `└` connector attaches to the last
+ * non-empty item rather than the last array slot so a trailing blank does not
+ * strand the elbow on an empty line.
+ */
+/**
+ * Render one section: a (possibly fail-glyph-prefixed) header followed by its
+ * items as a tree. Empty-string items print as true blank lines; the `└` elbow
+ * attaches to the last non-empty item so a trailing blank cannot strand it.
  */
+function renderSection(s: DoctorSection): void {
+  const header = sectionFailed(s) ? `${red(FAIL_GLYPH_BARE)} ${s.header}` : s.header;
+  console.log(header);
+  const lastContent = s.items.reduce((acc, item, j) => (item !== '' ? j : acc), -1);
+  for (let j = 0; j < s.items.length; j++) {
+    if (s.items[j] === '') console.log('');
+    else console.log(`${j === lastContent ? '  └ ' : '  ├ '}${s.items[j]}`);
+  }
+}
+
 export function renderDoctor(sections: DoctorSection[]): void {
   const visible = sections.filter((s) => s.items.length > 0);
   for (let i = 0; i < visible.length; i++) {
     if (i > 0) console.log('');
-    const s = visible[i];
-    const header = sectionFailed(s) ? `${red(FAIL_GLYPH_BARE)} ${s.header}` : s.header;
-    console.log(header);
-    for (let j = 0; j < s.items.length; j++) {
-      const isLast = j === s.items.length - 1;
-      console.log(`${isLast ? '  └ ' : '  ├ '}${s.items[j]}`);
-    }
+    renderSection(visible[i]);
   }
 }

package/src/commands.doctor.ts

@@ -62,7 +62,7 @@ export function cmdDoctor(opts: { checkShared?: boolean } = {}): void {
   reportRebaseClean(repository);
   reportMirrorActions(repository);
 
-  const version = section('Version');
+  const version = section('Version Checks');
   reportVersionCheck(version);
   reportNodeEngineCheck(version);
   reportGitleaksVersionCheck(version);

package/src/commands.doctor.version.ts

@@ -11,9 +11,9 @@ import { HOME, UPSTREAM_REPO_SLUG } from './config.ts';
  * Soft, offline-tolerant release-version check appended to `cmdDoctor`. Reads
  * the local `package.json.version`, compares it to the latest release tag on
  * the upstream GitHub repo (cached 1h, 3s curl timeout), and emits one of:
- *   - `✓ version: <local> (latest)` when local == latest
- *   - `⚠︎ version: <local> -> <latest>` when local < latest
- *   - `ℹ︎ version: <local> (ahead of latest release <latest>)` when local > latest
+ *   - `✓ claude-nomad: <local> (latest)` when local == latest
+ *   - `⚠︎ claude-nomad: <local> -> <latest>` when local < latest
+ *   - `ℹ︎ claude-nomad: <local> (ahead of latest release <latest>)` when local > latest
  * Every failure path (offline, curl missing, non-2xx, malformed JSON, missing
  * `tag_name`, missing/unreadable package.json) is a SILENT skip; this module
  * never sets `process.exitCode` and never writes to stderr.
@@ -153,9 +153,9 @@ function fetchLatestTag(): string | null {
  * Emit a single, non-fatal version diagnostic for `nomad doctor` by comparing the local package.json version to the latest upstream release.
  *
  * Logs one of:
- * - `✓ version: <local> (latest)` when the versions match
- * - `⚠︎ version: <local> -> <latest> (run \`nomad update\`)` when the local version is behind
- * - `ℹ︎ version: <local> (ahead of latest release <latest>)` when the local version is ahead
+ * - `✓ claude-nomad: <local> (latest)` when the versions match
+ * - `⚠︎ claude-nomad: <local> -> <latest> (run \`nomad update\`)` when the local version is behind
+ * - `ℹ︎ claude-nomad: <local> (ahead of latest release <latest>)` when the local version is ahead
  *
  * Any failure to read the local version, retrieve or parse the latest release, or use the cache results in no output and does not change `process.exitCode`.
  */
@@ -181,10 +181,16 @@ export function reportVersionCheck(section: DoctorSection): void {
 
   const cmp = compareSemver(localPure, latest);
   if (cmp === 0) {
-    addItem(section, `${green(okGlyph)} version: ${local} (latest)`);
+    addItem(section, `${green(okGlyph)} claude-nomad: ${local} (latest)`);
   } else if (cmp === -1) {
-    addItem(section, `${yellow(warnGlyph)} version: ${local} -> ${latest} (run \`nomad update\`)`);
+    addItem(
+      section,
+      `${yellow(warnGlyph)} claude-nomad: ${local} -> ${latest} (run \`nomad update\`)`,
+    );
   } else {
-    addItem(section, `${dim(infoGlyph)} version: ${local} (ahead of latest release ${latest})`);
+    addItem(
+      section,
+      `${dim(infoGlyph)} claude-nomad: ${local} (ahead of latest release ${latest})`,
+    );
   }
 }

package/src/diff-lines.ts

@@ -0,0 +1,43 @@
+import { diffLines } from 'diff';
+
+import { green, red } from './color.ts';
+
+/**
+ * Map a jsdiff `diffLines` result for two pre-stringified JSON strings into
+ * an array of unified-diff body lines (the two-line header is the caller's
+ * responsibility).
+ *
+ * Each jsdiff part has a `value` that may span multiple lines and may carry a
+ * trailing `\n`. The value is split on `\n` and any trailing empty element
+ * (produced by the trailing newline) is dropped so that it does not become a
+ * spurious blank output line.
+ *
+ * Line prefix mapping per part type:
+ *   - context (neither added nor removed): a single leading space then the line
+ *   - removed (`part.removed === true`): `red('-' + line)`
+ *   - added (`part.added === true`): `green('+' + line)`
+ *
+ * Coloring routes through `color.ts` `red`/`green` helpers, so `NO_COLOR` /
+ * non-TTY environments degrade to literal `-` / `+` prefixed lines with no
+ * ANSI escape sequences. Picocolors owns the detection logic.
+ */
+export function diffLinesToUnified(oldStr: string, newStr: string): string[] {
+  const parts = diffLines(oldStr, newStr);
+  const lines: string[] = [];
+  for (const part of parts) {
+    const partLines = part.value.split('\n');
+    // A part value ending in '\n' yields a trailing '' after split; drop it.
+    if (partLines[partLines.length - 1] === '') {
+      partLines.pop();
+    }
+    const prefix = part.removed
+      ? (line: string) => red(`-${line}`)
+      : part.added
+        ? (line: string) => green(`+${line}`)
+        : (line: string) => ` ${line}`;
+    for (const line of partLines) {
+      lines.push(prefix(line));
+    }
+  }
+  return lines;
+}

package/src/preview.ts

@@ -1,53 +1,34 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 
-import { green, red } from './color.ts';
 import { CLAUDE_HOME, HOST, REPO_HOME } from './config.ts';
+import { diffLinesToUnified } from './diff-lines.ts';
 import { applySharedLinks } from './links.ts';
 import { remapPull } from './remap.ts';
 import { log } from './utils.ts';
 import { deepMerge, readJson } from './utils.json.ts';
 
 /**
- * Minimal in-tree unified-diff helper for two pre-stringified JSON
- * documents. Walks the line arrays in parallel and emits a unified-diff
- * style output: unchanged lines prefixed with a space, removed lines with
- * `-` (red), added lines with `+` (green), plus at most three lines of
- * surrounding context per changed block. The implementation is intentionally
- * naive (no LCS); for two ~50-line settings JSON inputs the result is
- * acceptable even if not optimal.
+ * LCS line diff for two pre-stringified JSON documents via jsdiff. Returns a
+ * unified-diff style string: the two literal header lines
+ * `--- ~/.claude/settings.json` and `+++ would write`, followed by body lines
+ * where unchanged lines are prefixed with a space, removed lines with `-`
+ * (red), and added lines with `+` (green). Coloring routes through `color.ts`
+ * so `NO_COLOR` / non-TTY environments degrade to literal prefixes with no
+ * ANSI escape sequences.
  *
- * Returns the empty string when the inputs are byte-identical so the caller
- * can suppress the section. Picocolors handles `NO_COLOR` / `FORCE_COLOR`
- * detection, so the `red`/`green` wrappers degrade to identity in non-TTY
- * environments and the output stays literal `-` / `+` prefixed.
- *
- * The header line `--- ~/.claude/settings.json` / `+++ would write` is
- * literal; callers that want a different header can prepend their own.
+ * Returns the empty string when inputs are byte-identical so the caller can
+ * suppress the section. jsdiff `diffLines` aligns on the longest common
+ * subsequence, so a mid-document insertion does not cascade false `-`/`+`
+ * pairs for the unchanged tail.
  */
 export function diffJsonStrings(currentJsonText: string, newJsonText: string): string {
   if (currentJsonText === newJsonText) return '';
-  const a = currentJsonText.split('\n');
-  const b = newJsonText.split('\n');
-  const lines: string[] = [];
-  lines.push('--- ~/.claude/settings.json');
-  lines.push('+++ would write');
-
-  // Walk both arrays in parallel. Lines that match index-wise are context;
-  // others are emitted as -a / +b. A real unified-diff would compute the
-  // longest common subsequence; this naive walk is good enough for two JSON
-  // documents pretty-printed at the same indentation level.
-  const maxLen = Math.max(a.length, b.length);
-  for (let i = 0; i < maxLen; i++) {
-    const av = a[i];
-    const bv = b[i];
-    if (av === bv) {
-      if (av !== undefined) lines.push(` ${av}`);
-      continue;
-    }
-    if (av !== undefined) lines.push(red(`-${av}`));
-    if (bv !== undefined) lines.push(green(`+${bv}`));
-  }
+  const lines: string[] = [
+    '--- ~/.claude/settings.json',
+    '+++ would write',
+    ...diffLinesToUnified(currentJsonText, newJsonText),
+  ];
   return lines.join('\n');
 }
 

package/src/push-gitleaks.scan.ts

@@ -31,6 +31,13 @@ export type Finding = {
   StartLine: number;
   Match: string;
   Fingerprint: string;
+  /**
+   * Human-readable rule description gitleaks bakes into every finding (the
+   * matched rule's `description` from its toml). Optional: absent on older
+   * gitleaks reports or custom rules with no description, in which case the
+   * doctor legend silently omits the entry (graceful degradation, no network).
+   */
+  Description?: string;
 };
 
 /**

package/src/remap.ts

@@ -2,7 +2,7 @@ import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, statSync } from 'no
 import { join, relative, sep } from 'node:path';
 
 import { CLAUDE_HOME, HOST, REPO_HOME, type PathMap } from './config.ts';
-import { log } from './utils.ts';
+import { die, log } from './utils.ts';
 import { backupBeforeWrite, backupRepoWrite } from './utils.fs.ts';
 import { encodePath, readJson } from './utils.json.ts';
 
@@ -98,17 +98,67 @@ export function remapPull(ts: string, opts: { dryRun?: boolean } = {}): { unmapp
   return { unmapped };
 }
 
+/**
+ * Build the encoded-key to logical-name reverse map for the current host,
+ * failing closed on any `path-map.json` shape that would silently lose session
+ * data on push. Both failure modes `die()` (throw `NomadFatal`) before the
+ * caller writes anything:
+ *
+ * - Encoded-path collision: two distinct host paths that `encodePath` maps to
+ *   the same key (every `/` becomes `-`), which would clobber each other under
+ *   one repo directory.
+ * - Duplicate path: two logical names mapping to the same host path, where only
+ *   one logical could be pushed and the other's `shared/projects/` copy would
+ *   be orphaned.
+ *
+ * @param map - the parsed `path-map.json`
+ * @returns reverse lookup from encoded local dir name to logical project name
+ */
+function buildReverseMap(map: PathMap): Map<string, string> {
+  const reverse = new Map<string, string>();
+  const encodedPaths = new Map<string, string>();
+  for (const [logical, hosts] of Object.entries(map.projects)) {
+    const p = hosts[HOST];
+    if (!p || p === 'TBD') continue;
+    const encoded = encodePath(p);
+    const prior = encodedPaths.get(encoded);
+    if (prior !== undefined) {
+      if (prior !== p) {
+        die(
+          `encoded-path collision in path-map.json: "${prior}" and "${p}" both encode to` +
+            ` "${encoded}" (encodePath replaces every / with -).` +
+            ` Edit path-map.json so the two paths do not encode identically.` +
+            ` Run nomad doctor for the full list of collisions.`,
+        );
+      }
+      die(
+        `duplicate path in path-map.json: logical names "${reverse.get(encoded)}" and "${logical}"` +
+          ` both map to "${p}" for ${HOST}, so only one could be pushed and the other's` +
+          ` shared/projects/ copy would be orphaned.` +
+          ` Edit path-map.json so each host path maps to a single logical name.`,
+      );
+    }
+    encodedPaths.set(encoded, p);
+    reverse.set(encoded, logical);
+  }
+  return reverse;
+}
+
 /**
  * Push: copy local path-encoded dirs back to repo under logical names.
  *
  * Returns `{ unmapped: N, collisions: M }` where `unmapped` is the count of
  * `~/.claude/projects/<dir>/` entries that have no path-map reverse-lookup
- * for this host. `collisions` is reserved for a future slice's path-encoding
- * collision detection and is always `0` here.
+ * for this host. `collisions` is always `0` on the success path: any
+ * `path-map.json` shape that would silently lose data (an encoded-path
+ * collision between two distinct host paths, or two logical names mapping to
+ * the same host path) makes `buildReverseMap` `die()` (throw `NomadFatal`) to
+ * refuse the push before any `shared/projects/` content is written. Detection
+ * runs during the reverse-map build, so it fires under `dryRun` too.
  *
  * `opts.dryRun` (default `false`): when `true`, log `would push:` lines
- * instead of calling `backupRepoWrite` + `copyDir`. Counts are computed
- * identically in both modes.
+ * instead of calling `backupRepoWrite` + `copyDir`. Collision detection
+ * runs identically in both modes.
  */
 export function remapPush(
   ts: string,
@@ -116,7 +166,6 @@ export function remapPush(
 ): { unmapped: number; collisions: number } {
   const dryRun = opts.dryRun === true;
   let unmapped = 0;
-  const collisions = 0;
   const mapPath = join(REPO_HOME, 'path-map.json');
   if (!existsSync(mapPath)) {
     log('no path-map.json; skipping session export');
@@ -126,16 +175,14 @@ export function remapPush(
   const map = readJson<PathMap>(mapPath);
   const localProjects = join(CLAUDE_HOME, 'projects');
   const repoProjects = join(REPO_HOME, 'shared', 'projects');
-  if (!dryRun) mkdirSync(repoProjects, { recursive: true });
 
-  const reverse = new Map<string, string>();
-  for (const [logical, hosts] of Object.entries(map.projects)) {
-    const p = hosts[HOST];
-    if (!p || p === 'TBD') continue;
-    reverse.set(encodePath(p), logical);
-  }
+  const reverse = buildReverseMap(map);
+  if (!existsSync(localProjects)) return { unmapped, collisions: 0 };
+  // Create the repo destination only after collision detection passes and we
+  // know there is something to push, so a failing or no-op push is fully
+  // side-effect-free (no empty shared/projects/ left behind).
+  if (!dryRun) mkdirSync(repoProjects, { recursive: true });
 
-  if (!existsSync(localProjects)) return { unmapped, collisions };
   for (const dir of readdirSync(localProjects)) {
     const logical = reverse.get(dir);
     if (!logical) {
@@ -156,5 +203,5 @@ export function remapPush(
     copyDirJsonlOnly(join(localProjects, dir), repoDst);
     log(`pushed ${dir} -> ${logical}`);
   }
-  return { unmapped, collisions };
+  return { unmapped, collisions: 0 };
 }