@nolto/cli 0.8.0 → 0.9.0

package/README.md

@@ -21,6 +21,8 @@ nolto init
 `nolto init` configures authentication, selects or creates a project, writes the
 repo-local `nolto.json` binding, installs the bundled `roadmap-progress` skill,
 and creates `.nolto/roadmaps/<slug>.json` when needed.
+Re-running it inside a repository keeps the saved token and only sets up that
+repository; use `--force` to reconfigure the global settings.
 
 For browser-based authentication without the rest of the repository setup:
 
@@ -61,6 +63,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
 ```
@@ -68,10 +73,42 @@ nolto watch --install-service      # Install the Linux systemd user service
 `sync` reads every `.nolto/roadmaps/*.json` file in filename order, uses each
 filename stem as its slug, validates schema v2, follows any linked plan Markdown
 paths, and sends an idempotent full upsert to the bound project. A legacy
-`.roadmap/roadmap.json` is migrated automatically when no canonical roadmap exists.
+`.roadmap/roadmap.json` is migrated by `nolto sync` when no canonical roadmap
+exists; `nolto watch` only warns and never migrates.
 
 `watch` uses the repository registry maintained by `nolto init`. Missing registered
 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
 
@@ -134,7 +171,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 |