@nolto/cli 0.8.1 → 0.10.0

package/README.md

@@ -45,7 +45,7 @@ nolto whoami               # Show resolved auth/config state and project count
 ```bash
 nolto link <projectId>     # Write or update nolto.json at the repository root
 nolto link --show          # Show the current binding, source, and repository identity
-nolto link --rebind        # Rebind the project to this repository (owner only)
+nolto link --rebind [--yes] # Rebind the project to this repository (owner only)
 nolto link --unlink        # Remove projectId from nolto.json
 ```
 
@@ -53,8 +53,11 @@ Commit `nolto.json` so everyone working in the repository targets the same Nolto
 project. A Nolto project is bound to the first repository identity it syncs from.
 The identity is the normalized `origin` remote, or a machine ID plus path when no
 remote is available. Syncing from a different repository fails with
-`409 repo_mismatch`. An owner can run `nolto link --rebind` in the correct
-repository to change the binding, at most once every seven days.
+`409 repo_mismatch`. Before rebinding, run `nolto link --show` and confirm that
+the project ID is intended for this repository. An owner can then run
+`nolto link --rebind` in the correct repository to change the binding, at most
+once every seven days. The command shows the project name and asks for
+confirmation; pass `--yes` (`-y`) to skip the prompt.
 
 CLI versions older than 0.8.0 do not send a repository identity and receive
 `426`; run `nolto update` before syncing.
@@ -63,6 +66,9 @@ CLI versions older than 0.8.0 do not send a repository identity and receive
 
 ```bash
 nolto sync                         # Push roadmap JSON files and linked plan Markdown
+nolto diff [slug]                  # Compare local and server roadmaps without changing them
+nolto pull [slug]                  # Overwrite local roadmap files from the server
+nolto pull --merge [slug]          # Structurally merge server and local roadmaps
 nolto watch [--debounce <ms>]      # Watch registered repositories and auto-sync
 nolto watch --install-service      # Install the Linux systemd user service
 ```
@@ -78,6 +84,35 @@ repositories are skipped with a warning.
 The CLI warns when an installed `roadmap-progress` skill version differs from the
 CLI version; run `nolto init` in that repository to refresh it.
 
+Use `nolto diff [slug]` before pushing to review structural task, phase, and
+metadata differences. It exits with code 1 when differences are found and does
+not change either side. `nolto pull [slug]` downloads all server roadmaps, or one
+named roadmap, and intentionally overwrites the corresponding local files after
+validation. It never deletes local-only roadmaps. Add `--merge` to preserve valid
+local changes using a deterministic structural merge, and review the result with
+`git diff` before committing.
+
+## Merging roadmap conflicts
+
+Roadmap files use Nolto's structural Git merge driver. The repository attribute
+and local Git configuration are:
+
+```text
+.nolto/roadmaps/*.json merge=nolto-roadmap
+git config --local merge.nolto-roadmap.driver "nolto merge-file %A %B --base %O"
+```
+
+`nolto init` sets up both entries for the current repository and is safe to run
+again for an existing repository. Git invokes the underlying command as:
+
+```bash
+nolto merge-file <ours> <theirs> --base <ancestor>
+```
+
+The result is written to `<ours>` as required by Git. Use
+`nolto pull --merge [slug]` when the server has changes that should be combined
+with a valid local roadmap before syncing.
+
 ## Configuration
 
 The config file is `~/.config/nolto/config.json` (or
@@ -139,7 +174,7 @@ Errors are written to stderr:
 | Code | Meaning |
 |---|---|
 | 0 | Success |
-| 1 | Unexpected command failure |
+| 1 | Roadmap differences found (`nolto diff`) or unexpected command failure |
 | 2 | Local input or file validation error |
 | 3 | Authentication or authorization error |
 | 4 | Rate limit response |