claude-nomad 0.53.3 → 0.55.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # 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)
+
+
+### Added
+
+* **doctor:** add preflight hardening checks ([#344](https://github.com/funkadelic/claude-nomad/issues/344)) ([551ab16](https://github.com/funkadelic/claude-nomad/commit/551ab16a6c0c6bdf88a51c5dbf5a76f3cd4a7f22))
+
+
+### Fixed
+
+* **update:** silence npm output on successful self-update ([#342](https://github.com/funkadelic/claude-nomad/issues/342)) ([b7171b9](https://github.com/funkadelic/claude-nomad/commit/b7171b933c6bb9b4578b7e109bb334baa0f147b8))
+
 ## [0.53.3](https://github.com/funkadelic/claude-nomad/compare/v0.53.2...v0.53.3) (2026-06-26)
 
 

package/README.md

@@ -39,19 +39,26 @@ 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.
 - **One command tells you what is wrong.** `nomad doctor` is a read-only health check: wedged sync
   repo, broken hook references, hooks that would crash on session start because of a missing
-  `--preserve-symlinks-main` flag, version drift, oversized backup cache, 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.
+  `--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, 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
@@ -66,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>
@@ -100,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
@@ -166,7 +224,10 @@ but requires nomad `>= 0.35.0` because it calls recent subcommands (`nomad diff`
 - `gh` ([GitHub CLI](https://cli.github.com/)), required by `nomad init`
 
 **Optional:** [curl](https://curl.se/) or [wget](https://www.gnu.org/software/wget/) for the
-version-staleness check and `nomad doctor --check-schema`. The CLI works without them.
+version-staleness check and `nomad doctor --check-schema`. The CLI works without them. The opt-in
+`nomad doctor --check-remote` flag reads the locally-cached `origin/main` remote-tracking ref (no
+curl or wget needed) and verifies that `shared/` and a valid `path-map.json` are present there; it
+skips with a `⚠︎` when the ref is unavailable, and is non-fatal in all cases.
 
 ## Learn more