claude-nomad 0.54.0 → 0.55.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [0.55.0](https://github.com/funkadelic/claude-nomad/compare/v0.54.0...v0.55.0) (2026-06-28)
+
+
+### Added
+
+* **doctor:** warn on misaligned host key when NOMAD_HOST is unset ([#356](https://github.com/funkadelic/claude-nomad/issues/356)) ([a13e833](https://github.com/funkadelic/claude-nomad/commit/a13e833a09636f98f1e9c51e9c41f01a4323dea2))
+* **init:** offer to snapshot an existing ~/.claude on init ([#357](https://github.com/funkadelic/claude-nomad/issues/357)) ([92e90b1](https://github.com/funkadelic/claude-nomad/commit/92e90b1977fff51d565fa5d11b3c640790ee1b57))
+
+
+### Fixed
+
+* make sync warning messages user-friendly ([#345](https://github.com/funkadelic/claude-nomad/issues/345)) ([002f57d](https://github.com/funkadelic/claude-nomad/commit/002f57de240dfb1349742fa4c2b4ac5e51b5f7ba))
+
+
+### Documentation
+
+* clarify onboarding (two-dir model, session sync, push order) ([#355](https://github.com/funkadelic/claude-nomad/issues/355)) ([396fbb8](https://github.com/funkadelic/claude-nomad/commit/396fbb875b4331800ee74834944da17decbcad92))
+
 ## [0.54.0](https://github.com/funkadelic/claude-nomad/compare/v0.53.3...v0.54.0) (2026-06-27)
 
 

package/README.md

@@ -39,7 +39,9 @@ survives different file paths and your secrets never ride along.
   live settings syncs normally via `nomad capture-settings`.
 - **Every push is secret-scanned.** Only an explicit allow-list of paths ever leaves the machine,
   credentials never sync, and gitleaks scans the exact files about to be published. The push aborts
-  on any hit, with an interactive menu to redact, allow, or drop the finding.
+  on any hit, with an interactive menu to redact, allow, or drop the finding. Always publish through
+  `nomad push`: the sync repo is an ordinary Git repo, so a manual `git push` from it skips the scan
+  entirely and can leak a secret that `nomad push` would have caught.
 - **Preview before you trust it.** `nomad diff` shows offline what a pull would change (gsd-owned
   hook churn is filtered the same as on pull, so the preview matches what a real pull writes), and
   `--dry-run` on pull and push prints the plan without writing anything.
@@ -47,13 +49,16 @@ survives different file paths and your secrets never ride along.
   repo, broken hook references, hooks that would crash on session start because of a missing
   `--preserve-symlinks-main` flag, version drift, oversized backup cache, missing git committer
   identity in the sync repo (a push fails at commit time without one), path-map entries whose local
-  project folder no longer exists on this machine, synced skills with local edits that differ from
-  the shared copy, and settings drift in both directions: keys present in the repo merge but absent
-  from your live `settings.json` (behind; the next `nomad pull` will restore them, fix:
-  `nomad pull`) and keys present locally but not yet in the repo (ahead; local-only additions, fix:
-  `nomad capture-settings`). Each issue includes a fix hint. By default the report is compact: it
-  shows only checks that need action plus a one-line verdict. Add `--verbose` (or `--all` / `-v`) to
-  see the full per-check tree, including everything that passed.
+  project folder no longer exists on this machine, a multi-host repo where this machine's
+  hostname-derived key matches no `hosts/<HOST>.json` or path-map entry (a sign `NOMAD_HOST` is
+  unset here, so per-host settings and session sync will not line up with the other hosts), synced
+  skills with local edits that differ from the shared copy, and settings drift in both directions:
+  keys present in the repo merge but absent from your live `settings.json` (behind; the next
+  `nomad pull` will restore them, fix: `nomad pull`) and keys present locally but not yet in the
+  repo (ahead; local-only additions, fix: `nomad capture-settings`). Each issue includes a fix hint.
+  By default the report is compact: it shows only checks that need action plus a one-line verdict.
+  Add `--verbose` (or `--all` / `-v`) to see the full per-check tree, including everything that
+  passed.
 - **Self-healing sync.** Every overwrite is backed up first, and `nomad pull --force-remote`
   recovers two kinds of stuck sync repo: a repo stuck mid-rebase or mid-merge (aborts the operation,
   parks stranded work on a branch, refuses if shared config is at risk), and a repo where the rebase
@@ -68,15 +73,27 @@ opt-in per-project sync, transcript redaction, backup pruning, and more.
 
 ## Quickstart
 
+nomad works with two directories, and the difference is the one thing worth learning up front:
+
+- **`~/claude-nomad/`** is your private sync repo. This is the one you edit.
+- **`~/.claude/`** is Claude Code's live config. nomad regenerates it on every `pull`.
+
+Edit the repo, never the live config. In particular, never hand-edit `~/.claude/settings.json`: it
+is rebuilt from the repo on every pull and your changes are lost. Change `shared/settings.base.json`
+(or `hosts/<HOST>.json`) in the repo instead, or run `nomad capture-settings` to pull local changes
+back into the repo (see [Changing settings](#changing-settings)).
+
 **First host** (once, ever):
 
 ```bash
 # 1. Install the CLI.
 $ npm i -g claude-nomad
 
-# 2. Create your private sync repo and scaffold it.
+# 2. Create your private sync repo and scaffold it. If you already have a
+#    ~/.claude/ worth keeping, init offers to seed the repo from it.
 $ nomad init                   # prompts for a repo name (default: claude-nomad-config)
-$ nomad init --repo my-config  # non-interactive
+$ nomad init --repo my-config  # set the repo name without the prompt
+$ nomad init --snapshot        # seed from existing ~/.claude/ without being asked
 
 # 3. Add a stable host label to ~/.zshrc or ~/.bashrc, then reload.
 export NOMAD_HOST=<your-host-label>
@@ -102,6 +119,45 @@ $ nomad pull     # apply config to ~/.claude/
 $ nomad push     # publish local changes (sessions, settings)
 ```
 
+Pull before you push whenever both machines may have changed. Sync is last-write-wins, so pushing
+stale local state over newer remote state silently overwrites it. The
+[FAQ](https://funkadelic.github.io/claude-nomad/faq/) covers the full push/pull order when both
+sides have changed.
+
+### Make your sessions follow you
+
+Session history only syncs for projects you list in `path-map.json`, and a fresh `init` starts with
+none, so no sessions sync until you add a mapping. Each entry maps a logical project name to the
+absolute path it lives at on each host:
+
+```json
+{
+  "projects": {
+    "my-app": {
+      "laptop": "/Users/you/code/my-app",
+      "desktop": "/home/you/projects/my-app"
+    }
+  }
+}
+```
+
+The host keys (`laptop`, `desktop`) are the same labels you set in `NOMAD_HOST` on each machine.
+After editing `path-map.json`, `nomad push` publishes the matching sessions and `nomad pull` on
+another host copies them into place, rewriting the embedded file paths so `claude --resume` finds
+them at that host's path.
+
+### Changing settings
+
+There are two ways a settings change reaches the repo, and the right one depends on where you made
+it:
+
+- **You are deciding the change:** edit `shared/settings.base.json` (shared by every host) or
+  `hosts/<HOST>.json` (one machine only) in the repo, then `nomad push`.
+- **Something else already wrote it** (Claude Code or a tool added keys to your live
+  `~/.claude/settings.json`): run `nomad capture-settings` to promote those keys into the repo
+  before the next `nomad pull` overwrites them. Add `--host` to land machine-specific values (such
+  as absolute paths) in `hosts/<HOST>.json` instead of the shared base.
+
 During `nomad push` and `nomad pull`, long-running steps (rebase, secret scan, git push, session
 sync) show an animated progress indicator on an interactive terminal so the CLI does not look hung.
 In CI and when output is piped, only plain text lines are printed, with no ANSI control codes, so

package/dist/nomad.mjs

@@ -780,7 +780,7 @@ var init_push_gitleaks_config = __esm({
 
 // src/push-checks.ts
 import { execFileSync as execFileSync4 } from "node:child_process";
-import { readdirSync as readdirSync4, rmSync as rmSync5 } from "node:fs";
+import { readdirSync as readdirSync5, rmSync as rmSync5 } from "node:fs";
 import { homedir as homedir2, platform } from "node:os";
 import { join as join17 } from "node:path";
 function gitleaksInstallHint() {
@@ -820,7 +820,7 @@ function findGitlinks(dir) {
   function walk(current) {
     let entries;
     try {
-      entries = readdirSync4(current, { withFileTypes: true });
+      entries = readdirSync5(current, { withFileTypes: true });
     } catch {
       return;
     }
@@ -1505,6 +1505,14 @@ function partitionByCaptureExclusion(keys) {
   }
   return { promotable, excluded };
 }
+function describeSettings(keys) {
+  const one = keys.length === 1;
+  return {
+    phrase: `${keys.length} ${one ? "setting" : "settings"} (${keys.join(", ")})`,
+    pronoun: one ? "it" : "them",
+    verb: one ? "is" : "are"
+  };
+}
 var BIN_NODE_RE = /^"?(?:[A-Za-z]:)?[\\/](?:.*[\\/])?bin[\\/]node"?$/;
 var LEADING_BIN_NODE_RE = /^"?(?:[A-Za-z]:)?[\\/](?:[^"\s]*[\\/])?bin[\\/]node"?(?=\s)/;
 function normalizeNodePathsDeep(value) {
@@ -1614,14 +1622,16 @@ function regenerateSettings(ts, opts = {}) {
       const existing = readJson(settingsPath);
       const drift = classifySettingsDrift(merged, existing);
       if (drift.behind.length > 0) {
+        const { phrase, pronoun } = describeSettings(drift.behind);
         warn(
-          `existing settings.json is missing merged keys ${JSON.stringify(drift.behind)}. Run 'nomad pull' to restore them.`
+          `your settings.json is missing ${phrase} that the synced copy has; run 'nomad pull' to restore ${pronoun}.`
         );
       }
       const { promotable } = partitionByCaptureExclusion(drift.ahead);
       if (promotable.length > 0) {
+        const { phrase, pronoun, verb } = describeSettings(promotable);
         warn(
-          `existing settings.json has local-only keys ${JSON.stringify(promotable)}. Run 'nomad capture-settings' to promote them into the repo before they are overwritten.`
+          `your settings.json has ${phrase} that ${verb} not yet synced; run 'nomad capture-settings' to save ${pronoun} to the repo before the next pull overwrites ${pronoun}.`
         );
       }
     } catch {
@@ -2069,7 +2079,7 @@ import { join as join36 } from "node:path";
 // src/commands.doctor.checks.repo.ts
 init_color();
 init_config();
-import { existsSync as existsSync9, lstatSync as lstatSync6, statSync as statSync3 } from "node:fs";
+import { existsSync as existsSync9, lstatSync as lstatSync6, readdirSync as readdirSync2, statSync as statSync3 } from "node:fs";
 import { join as join11 } from "node:path";
 
 // src/commands.doctor.format.ts
@@ -2189,6 +2199,7 @@ function reasonForPartial(repoHome2, host) {
 }
 
 // src/commands.doctor.checks.repo.ts
+init_utils_json();
 function isOverrideActive() {
   return Boolean(process.env.NOMAD_REPO);
 }
@@ -2206,6 +2217,46 @@ function reportHostAndPaths(section2) {
     `${existsSync9(claude) ? green(okGlyph) : yellow(warnGlyph)} claude home: ${blue(claude)}`
   );
 }
+function pathMapHostKeys() {
+  const mapPath = join11(repoHome(), "path-map.json");
+  if (!existsSync9(mapPath)) return /* @__PURE__ */ new Set();
+  let raw;
+  try {
+    raw = readJson(mapPath);
+  } catch {
+    return /* @__PURE__ */ new Set();
+  }
+  if (validatePathMapShape(raw) !== null) return /* @__PURE__ */ new Set();
+  const keys = /* @__PURE__ */ new Set();
+  for (const hosts of Object.values(raw.projects)) {
+    for (const key of Object.keys(hosts)) keys.add(key);
+  }
+  return keys;
+}
+function hostOverrideLabels() {
+  let entries;
+  try {
+    entries = readdirSync2(join11(repoHome(), "hosts"));
+  } catch {
+    return /* @__PURE__ */ new Set();
+  }
+  const labels = /* @__PURE__ */ new Set();
+  for (const entry of entries) {
+    if (entry.endsWith(".json")) labels.add(entry.slice(0, -".json".length));
+  }
+  return labels;
+}
+function reportHostKeyAlignment(section2) {
+  if (process.env.NOMAD_HOST) return;
+  const overrideLabels = hostOverrideLabels();
+  const mapKeys = pathMapHostKeys();
+  if (overrideLabels.has(HOST) || mapKeys.has(HOST)) return;
+  if (overrideLabels.size === 0 && mapKeys.size === 0) return;
+  addItem(
+    section2,
+    `${yellow(warnGlyph)} NOMAD_HOST unset: this repo configures other hosts, but the hostname key ${cyan(HOST)} matches no hosts/${HOST}.json or path-map entry; set NOMAD_HOST to the label this host should use so per-host settings and session sync line up`
+  );
+}
 function reportRepoState(section2) {
   const repo = repoHome();
   const state = classifyRepoState(repo, HOST);
@@ -2301,7 +2352,7 @@ function reportDroppedNamesMigration(section2) {
 // src/commands.doctor.checks.settings.ts
 init_color();
 init_config();
-import { existsSync as existsSync10, readdirSync as readdirSync2 } from "node:fs";
+import { existsSync as existsSync10, readdirSync as readdirSync3 } from "node:fs";
 import { join as join12 } from "node:path";
 function loadBaseSettings(section2) {
   const basePath = join12(repoHome(), "shared", "settings.base.json");
@@ -2347,7 +2398,7 @@ function reportHostOverrides(section2, base, settings) {
     );
     const hostsDir = join12(repo, "hosts");
     if (existsSync10(hostsDir)) {
-      const cands = readdirSync2(hostsDir).filter((f) => f.endsWith(".json"));
+      const cands = readdirSync3(hostsDir).filter((f) => f.endsWith(".json"));
       if (cands.length > 0) addItem(section2, `${dim(infoGlyph)} candidates: ${cands.join(", ")}`);
     }
     process.exitCode = 1;
@@ -2362,7 +2413,7 @@ function reportHostOverrides(section2, base, settings) {
 // src/commands.doctor.checks.pathmap.ts
 init_color();
 init_config();
-import { existsSync as existsSync11, readdirSync as readdirSync3 } from "node:fs";
+import { existsSync as existsSync11, readdirSync as readdirSync4 } from "node:fs";
 import { join as join13 } from "node:path";
 init_utils_json();
 function reportMappedProjects(section2, map) {
@@ -2377,7 +2428,7 @@ function reportUnmappedProjects(section2, map) {
   if (!existsSync11(localProjects)) return;
   let localDirs;
   try {
-    localDirs = readdirSync3(localProjects);
+    localDirs = readdirSync4(localProjects);
   } catch {
     return;
   }
@@ -2666,13 +2717,13 @@ function reportGitIdentity(section2) {
 
 // src/commands.doctor.checks.backups.ts
 init_color();
-import { existsSync as existsSync16, lstatSync as lstatSync7, readdirSync as readdirSync5 } from "node:fs";
+import { existsSync as existsSync16, lstatSync as lstatSync7, readdirSync as readdirSync6 } from "node:fs";
 import { join as join19 } from "node:path";
 init_config();
 var TS_SHAPE2 = /^\d{8}-\d{6}(-\d+)?$/;
 function safeReaddir(dir) {
   try {
-    return readdirSync5(dir);
+    return readdirSync6(dir);
   } catch {
     return [];
   }
@@ -2848,7 +2899,7 @@ function reportCheckSchema(section2) {
 init_color();
 import { randomBytes } from "node:crypto";
 import { execFileSync as execFileSync9 } from "node:child_process";
-import { existsSync as existsSync19, mkdirSync as mkdirSync5, readdirSync as readdirSync7, rmSync as rmSync8 } from "node:fs";
+import { existsSync as existsSync19, mkdirSync as mkdirSync5, readdirSync as readdirSync8, rmSync as rmSync8 } from "node:fs";
 import { homedir as homedir4 } from "node:os";
 import { join as join24 } from "node:path";
 
@@ -2947,7 +2998,7 @@ init_config();
 
 // src/remap.ts
 init_config_sharedDirs_guard();
-import { cpSync as cpSync4, existsSync as existsSync18, mkdirSync as mkdirSync4, readdirSync as readdirSync6, renameSync as renameSync3, rmSync as rmSync7, statSync as statSync4 } from "node:fs";
+import { cpSync as cpSync4, existsSync as existsSync18, mkdirSync as mkdirSync4, readdirSync as readdirSync7, renameSync as renameSync3, rmSync as rmSync7, statSync as statSync4 } from "node:fs";
 import { join as join23, relative as relative3, sep as sep3 } from "node:path";
 
 // src/extras-sync.guards.ts
@@ -3087,7 +3138,7 @@ function remapPush(ts, opts = {}) {
   const reverse = buildReverseMap(map);
   if (!existsSync18(localProjects)) return { unmapped, collisions: 0, pushed, wouldPush };
   if (!dryRun) mkdirSync4(repoProjects, { recursive: true });
-  for (const dir of readdirSync6(localProjects)) {
+  for (const dir of readdirSync7(localProjects)) {
     if (dir.endsWith(TMP_SUFFIX)) continue;
     const logical = reverse.get(dir);
     if (!logical) {
@@ -3133,7 +3184,7 @@ function buildScanTree(tmpRoot) {
   }
   const localProjects = join24(claudeHome(), "projects");
   if (!existsSync19(localProjects)) return { logicalToEncoded, staged, malformed: false };
-  for (const dir of readdirSync7(localProjects)) {
+  for (const dir of readdirSync8(localProjects)) {
     const logical = reverse.get(dir);
     if (!logical) continue;
     copyDirJsonlOnly(join24(localProjects, dir), join24(tmpRoot, "shared", "projects", logical));
@@ -3192,7 +3243,7 @@ function reportCheckShared(section2, gitleaksReady) {
 
 // src/commands.doctor.checks.hooks.scope.ts
 init_color();
-import { existsSync as existsSync20, readFileSync as readFileSync6, readdirSync as readdirSync8, realpathSync as realpathSync2 } from "node:fs";
+import { existsSync as existsSync20, readFileSync as readFileSync6, readdirSync as readdirSync9, realpathSync as realpathSync2 } from "node:fs";
 import { dirname as dirname3, extname, join as join25 } from "node:path";
 init_config();
 function typeFromPackageJson(pkgPath) {
@@ -3245,7 +3296,7 @@ function remedy(family) {
 }
 function safeReaddir2(dir) {
   try {
-    return readdirSync8(dir);
+    return readdirSync9(dir);
   } catch {
     return [];
   }
@@ -3811,7 +3862,7 @@ import { existsSync as existsSync26, statSync as statSync6 } from "node:fs";
 import { dirname as dirname5, join as join31 } from "node:path";
 
 // src/commands.redact.subtree.ts
-import { existsSync as existsSync25, lstatSync as lstatSync8, readFileSync as readFileSync11, readdirSync as readdirSync9, statSync as statSync5, writeFileSync as writeFileSync4 } from "node:fs";
+import { existsSync as existsSync25, lstatSync as lstatSync8, readFileSync as readFileSync11, readdirSync as readdirSync10, statSync as statSync5, writeFileSync as writeFileSync4 } from "node:fs";
 import { join as join30 } from "node:path";
 init_utils_fs();
 init_utils();
@@ -3819,7 +3870,7 @@ function collectFiles(dir, out) {
   if (!existsSync25(dir)) return;
   const st = lstatSync8(dir);
   if (!st.isDirectory()) return;
-  for (const entry of readdirSync9(dir)) {
+  for (const entry of readdirSync10(dir)) {
     const abs = join30(dir, entry);
     const lst = lstatSync8(abs);
     if (lst.isSymbolicLink()) continue;
@@ -4580,7 +4631,7 @@ function reportOptionalDeps(section2, run = execFileSync12) {
   } else {
     addItem(
       section2,
-      `${yellow(warnGlyph)} gh: not installed (optional; needed for nomad init Actions auto-disable + the Actions-drift check)`
+      `${yellow(warnGlyph)} gh: not installed (optional; nomad init needs it to create the sync repo and auto-disable Actions, and the Actions-drift check uses it)`
     );
   }
   reportFetcherRow(section2, run);
@@ -4736,6 +4787,7 @@ function compactSections(sections) {
 function gatherDoctorSections(opts) {
   const host = section("Environment");
   reportHostAndPaths(host);
+  reportHostKeyAlignment(host);
   reportRepoState(host);
   const links = section("Shared links");
   const mapPath = join36(repoHome(), "path-map.json");
@@ -4836,7 +4888,7 @@ function parseDoctorArgs(args) {
 // src/commands.drop-session.ts
 init_config();
 import { execFileSync as execFileSync16 } from "node:child_process";
-import { existsSync as existsSync32, readdirSync as readdirSync10, statSync as statSync8 } from "node:fs";
+import { existsSync as existsSync32, readdirSync as readdirSync11, statSync as statSync8 } from "node:fs";
 import { join as join38, relative as relative4 } from "node:path";
 
 // src/commands.drop-session.git.ts
@@ -4949,7 +5001,7 @@ function cmdDropSession(id) {
 }
 function collectMatches(repoProjects, id, repo) {
   const matches = [];
-  for (const logical of readdirSync10(repoProjects)) {
+  for (const logical of readdirSync11(repoProjects)) {
     const candidate = join38(repoProjects, logical, `${id}.jsonl`);
     if (existsSync32(candidate)) {
       matches.push(relative4(repo, candidate));
@@ -5086,12 +5138,12 @@ init_config();
 
 // src/extras-sync.ts
 init_config();
-import { existsSync as existsSync35 } from "node:fs";
+import { existsSync as existsSync35, statSync as statSync9 } from "node:fs";
 import { join as join42 } from "node:path";
 
 // src/extras-sync.core.ts
 init_config();
-import { cpSync as cpSync6, existsSync as existsSync33, lstatSync as lstatSync9, readdirSync as readdirSync11, rmSync as rmSync11 } from "node:fs";
+import { cpSync as cpSync6, existsSync as existsSync33, lstatSync as lstatSync9, readdirSync as readdirSync12, rmSync as rmSync11 } from "node:fs";
 import { basename, join as join39 } from "node:path";
 init_utils();
 init_utils_json();
@@ -5132,7 +5184,7 @@ function* eachExtrasTarget(v, counts) {
 }
 function stripCollidingDstSymlinks(src, dst, isExcluded) {
   if (!existsSync33(dst)) return;
-  for (const name of readdirSync11(src)) {
+  for (const name of readdirSync12(src)) {
     if (isExcluded(name)) continue;
     const dstPath = join39(dst, name);
     const dstStat = lstatSync9(dstPath, { throwIfNoEntry: false });
@@ -5180,7 +5232,7 @@ function copyExtrasFiltered(src, dst, blockSet) {
   });
 }
 function prunePreservingDenied(src, dst, blockSet) {
-  for (const name of readdirSync11(dst)) {
+  for (const name of readdirSync12(dst)) {
     if (isDeniedName(blockSet, name)) continue;
     const dstPath = join39(dst, name);
     const srcStat = lstatSync9(join39(src, name), { throwIfNoEntry: false });
@@ -5211,7 +5263,7 @@ function copyExtrasFilteredPreserving(src, dst, blockSet) {
   });
 }
 function prunePreservingBy(src, dst, isPreserved) {
-  for (const name of readdirSync11(dst)) {
+  for (const name of readdirSync12(dst)) {
     if (isPreserved(name)) continue;
     const dstPath = join39(dst, name);
     const srcStat = lstatSync9(join39(src, name), { throwIfNoEntry: false });
@@ -5248,7 +5300,7 @@ init_utils_json();
 
 // src/extras-sync.remap.ts
 init_config();
-import { existsSync as existsSync34, mkdirSync as mkdirSync7, readdirSync as readdirSync12, realpathSync as realpathSync4, rmSync as rmSync12 } from "node:fs";
+import { existsSync as existsSync34, mkdirSync as mkdirSync7, readdirSync as readdirSync13, realpathSync as realpathSync4, rmSync as rmSync12 } from "node:fs";
 import { dirname as dirname7, join as join41, sep as sep7 } from "node:path";
 
 // src/extras-sync.planning-diff.ts
@@ -5349,7 +5401,7 @@ function pruneEmptyAncestors(target, planningRoot) {
   let dir = dirname7(target);
   while (dir !== planningRoot && dir.startsWith(planningRoot + sep7)) {
     try {
-      if (readdirSync12(dir).length > 0) break;
+      if (readdirSync13(dir).length > 0) break;
       rmSync12(dir, { recursive: true, force: true });
     } catch {
       break;
@@ -5482,6 +5534,15 @@ function remapExtrasPull(ts, opts = {}) {
 }
 
 // src/extras-sync.ts
+function divergenceWarnLine(o) {
+  const kind = o.isDir ? "folder" : "file";
+  const name = o.isDir ? `${o.dirname}/` : o.dirname;
+  const one = o.count === 1;
+  const fileCount = one ? "1 file" : `${o.count} files`;
+  const them = one ? "it" : "them";
+  const yours = one ? "your current file is" : "your current files are";
+  return `local ${kind} ${name} in repo ${o.logical} differs from the synced copy in ${fileCount}; the next pull step will overwrite ${them} with the synced version (${yours} backed up to ${o.projectBackupRoot}/)`;
+}
 function divergenceCheckExtras(ts) {
   const v = loadValidatedExtras({});
   if (v === null) return;
@@ -5496,7 +5557,13 @@ function divergenceCheckExtras(ts) {
     if (diff.length === 0) continue;
     const projectBackupRoot = join42(backupRoot, encodePath(localRoot));
     warn(
-      `local ${dirname8} for ${logical} diverges from origin in ${diff.length} file(s); next remapExtrasPull will merge changes (.planning overlays, .claude/.CLAUDE.md mirror; backups at ${projectBackupRoot}/)`
+      divergenceWarnLine({
+        dirname: dirname8,
+        logical,
+        isDir: statSync9(local).isDirectory(),
+        count: diff.length,
+        projectBackupRoot
+      })
     );
     for (const f of diff) warn(`  ${f}`);
   }
@@ -5504,7 +5571,7 @@ function divergenceCheckExtras(ts) {
 
 // src/skills-sync.ts
 init_config();
-import { existsSync as existsSync36, lstatSync as lstatSync10, mkdirSync as mkdirSync8, readdirSync as readdirSync13, rmSync as rmSync13 } from "node:fs";
+import { existsSync as existsSync36, lstatSync as lstatSync10, mkdirSync as mkdirSync8, readdirSync as readdirSync14, rmSync as rmSync13 } from "node:fs";
 import { join as join43 } from "node:path";
 init_utils_fs();
 function isGsdOwned(name) {
@@ -5514,7 +5581,7 @@ function isSkillExcluded(name) {
   return isGsdOwned(name) || isDeniedName(ALWAYS_NEVER_SYNC, name);
 }
 function copySkillsPush(src, dst) {
-  const srcNames = readdirSync13(src, { encoding: "utf8" });
+  const srcNames = readdirSync14(src, { encoding: "utf8" });
   const blockSet = /* @__PURE__ */ new Set([
     ...srcNames.filter((n) => isGsdOwned(n)),
     ...ALWAYS_NEVER_SYNC
@@ -6316,7 +6383,7 @@ init_color();
 init_config();
 init_config_sharedDirs_guard();
 import { randomBytes as randomBytes2 } from "node:crypto";
-import { copyFileSync, existsSync as existsSync39, mkdirSync as mkdirSync10, readdirSync as readdirSync14, rmSync as rmSync14 } from "node:fs";
+import { copyFileSync, existsSync as existsSync39, mkdirSync as mkdirSync10, readdirSync as readdirSync15, rmSync as rmSync14 } from "node:fs";
 import { homedir as homedir5 } from "node:os";
 import { join as join46 } from "node:path";
 init_push_leak_verdict();
@@ -6336,7 +6403,7 @@ function stageSessions(tmpRoot, map) {
   const localProjects = join46(claudeHome(), "projects");
   if (!existsSync39(localProjects)) return 0;
   let staged = 0;
-  for (const dir of readdirSync14(localProjects)) {
+  for (const dir of readdirSync15(localProjects)) {
     const logical = reverse.get(dir);
     if (!logical) continue;
     copyDirJsonlOnly(join46(localProjects, dir), join46(tmpRoot, "shared", "projects", logical));
@@ -6427,9 +6494,9 @@ function reportSettingsAheadDrift(repo) {
     const { ahead } = classifySettingsDrift(merged, settings);
     const { promotable } = partitionByCaptureExclusion(ahead);
     if (promotable.length === 0) return;
-    const keys = JSON.stringify(promotable);
+    const { phrase, pronoun, verb } = describeSettings(promotable);
     warn(
-      `settings.json has local-only keys ${keys} not in the repo. Run 'nomad capture-settings' to promote them (or 'nomad capture-settings --host' for host-specific values).`
+      `your settings.json has ${phrase} that ${verb} not yet in the repo; run 'nomad capture-settings' to save ${pronoun} (or 'nomad capture-settings --host' for host-specific values).`
     );
   } catch {
   }
@@ -6697,7 +6764,7 @@ init_config();
 init_utils();
 init_utils_fs();
 init_utils_json();
-import { copyFileSync as copyFileSync2, cpSync as cpSync7, existsSync as existsSync42, rmSync as rmSync15, statSync as statSync9 } from "node:fs";
+import { copyFileSync as copyFileSync2, cpSync as cpSync7, existsSync as existsSync42, rmSync as rmSync15, statSync as statSync10 } from "node:fs";
 import { join as join49 } from "node:path";
 function snapshotIntoShared(map) {
   const repo = repoHome();
@@ -6706,7 +6773,7 @@ function snapshotIntoShared(map) {
     const src = join49(claude, name);
     if (!existsSync42(src)) continue;
     const dst = join49(repo, "shared", name);
-    if (statSync9(src).isDirectory()) {
+    if (statSync10(src).isDirectory()) {
       const gk = join49(dst, ".gitkeep");
       if (existsSync42(gk)) rmSync15(gk);
       cpSync7(src, dst, { recursive: true, force: false, errorOnExist: true });
@@ -6747,6 +6814,9 @@ function preflightConflict(repoHome2) {
   }
   return null;
 }
+function isAlreadyInitialized(repoHome2) {
+  return preflightConflict(repoHome2) !== null;
+}
 function cmdInit(opts = {}) {
   const snapshot = opts.snapshot === true;
   const keepActions = opts.keepActions === true;
@@ -6839,6 +6909,47 @@ function maybeDisableRepoActions(repoHome2, run) {
   }
 }
 
+// src/init.prompt.ts
+init_config();
+init_utils();
+import { existsSync as existsSync44, readdirSync as readdirSync16, statSync as statSync11 } from "node:fs";
+import { join as join51 } from "node:path";
+import { createInterface as createInterface3 } from "node:readline/promises";
+function nonEmptyExists(path) {
+  if (!existsSync44(path)) return false;
+  try {
+    if (statSync11(path).isDirectory()) return readdirSync16(path).length > 0;
+    return true;
+  } catch {
+    return false;
+  }
+}
+function hasExistingClaudeConfig(claudeHome2) {
+  if (existsSync44(join51(claudeHome2, "settings.json"))) return true;
+  return SHARED_LINKS.some((name) => nonEmptyExists(join51(claudeHome2, name)));
+}
+async function confirmSnapshotDefault(claudeHome2) {
+  if (process.stdin.isTTY !== true || process.stdout.isTTY !== true) {
+    log(
+      `tip: ${claudeHome2} already has config; re-run 'nomad init --snapshot' to seed the repo from it.`
+    );
+    return false;
+  }
+  log(`Found existing config in ${claudeHome2}.`);
+  const rl = createInterface3({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await rl.question("Seed the new repo from it? [Y/n] ");
+    return !/^n(o)?$/i.test(answer.trim());
+  } finally {
+    rl.close();
+  }
+}
+async function resolveSnapshotChoice(flagSnapshot, claudeHome2, confirm = confirmSnapshotDefault) {
+  if (flagSnapshot) return true;
+  if (!hasExistingClaudeConfig(claudeHome2)) return false;
+  return confirm(claudeHome2);
+}
+
 // src/nomad.dispatch.helpers.ts
 var REJECT = { ok: false, advance: 0 };
 function applyBool(seen, set) {
@@ -7098,7 +7209,7 @@ function parsePushArgs(argv) {
 // package.json
 var package_default = {
   name: "claude-nomad",
-  version: "0.54.0",
+  version: "0.55.0",
   type: "module",
   description: "Sync Claude Code config (~/.claude/) across machines via a private Git repo, with path remapping and per-host settings overrides.",
   keywords: [
@@ -7230,7 +7341,8 @@ var DEFAULT_HELP = [
     "  init",
     "Create a private GitHub repo via gh (if none exists), scaffold shared/, hosts/, path-map."
   ),
-  row("       --snapshot", "Overlay the current ~/.claude/ into shared/ as the initial seed."),
+  row("       --snapshot", "Seed shared/ from the current ~/.claude/. Without this flag, init"),
+  cont("offers the same seed interactively when it detects existing config."),
   row("       --keep-actions", "Skip auto-disabling GitHub Actions on the private repo."),
   row(
     "       --repo <name>",
@@ -7308,7 +7420,8 @@ var DEFAULT_HELP = [
   "",
   row("  --version", "Print the installed CLI version as bare semver to stdout; exits 0."),
   "",
-  "Run `nomad doctor` to validate your setup. Edit shared/ or hosts/<HOST>.json",
+  "You edit the sync repo (~/claude-nomad/); nomad regenerates ~/.claude/ on every",
+  "pull. Run `nomad doctor` to validate your setup. Edit shared/ or hosts/<HOST>.json",
   "in the repo, never ~/.claude/settings.json directly (it is regenerated on",
   "every pull)."
 ].join("\n");
@@ -7317,15 +7430,15 @@ var DEFAULT_HELP = [
 init_config();
 init_utils();
 init_utils_json();
-import { existsSync as existsSync44, readFileSync as readFileSync14, readdirSync as readdirSync15 } from "node:fs";
-import { join as join51 } from "node:path";
+import { existsSync as existsSync45, readFileSync as readFileSync14, readdirSync as readdirSync17 } from "node:fs";
+import { join as join52 } from "node:path";
 function resumeCmd(sessionId) {
   if (!/^[A-Za-z0-9_-]+$/.test(sessionId) || sessionId.length > 128) {
     fail(`invalid session id: ${sessionId}`);
     process.exit(1);
   }
-  const projectsRoot = join51(claudeHome(), "projects");
-  if (!existsSync44(projectsRoot)) {
+  const projectsRoot = join52(claudeHome(), "projects");
+  if (!existsSync45(projectsRoot)) {
     fail(`${projectsRoot} does not exist`);
     process.exit(1);
   }
@@ -7339,8 +7452,8 @@ function resumeCmd(sessionId) {
     fail(`no cwd field found in ${jsonlPath}`);
     process.exit(1);
   }
-  const mapPath = join51(repoHome(), "path-map.json");
-  if (!existsSync44(mapPath)) {
+  const mapPath = join52(repoHome(), "path-map.json");
+  if (!existsSync45(mapPath)) {
     fail("path-map.json missing");
     process.exit(1);
   }
@@ -7362,9 +7475,9 @@ function resumeCmd(sessionId) {
   console.log(`cd ${shQuote(hit.localPath)} && claude --resume ${shQuote(sessionId)}`);
 }
 function findTranscriptPath(projectsRoot, sessionId) {
-  for (const dir of readdirSync15(projectsRoot)) {
-    const candidate = join51(projectsRoot, dir, `${sessionId}.jsonl`);
-    if (existsSync44(candidate)) return candidate;
+  for (const dir of readdirSync17(projectsRoot)) {
+    const candidate = join52(projectsRoot, dir, `${sessionId}.jsonl`);
+    if (existsSync45(candidate)) return candidate;
   }
   return null;
 }
@@ -7447,8 +7560,9 @@ try {
         console.error("usage: nomad init [--snapshot] [--keep-actions] [--repo <name>]");
         process.exit(1);
       }
+      const snapshot = isAlreadyInitialized(repoHome()) ? initArgs.snapshot : await resolveSnapshotChoice(initArgs.snapshot, claudeHome());
       cmdInit({
-        snapshot: initArgs.snapshot,
+        snapshot,
         keepActions: initArgs.keepActions,
         repoName: initArgs.repoName
       });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-nomad",
-  "version": "0.54.0",
+  "version": "0.55.0",
   "type": "module",
   "description": "Sync Claude Code config (~/.claude/) across machines via a private Git repo, with path remapping and per-host settings overrides.",
   "keywords": [