@nolto/cli 0.5.0 → 0.6.0

package/README.md

@@ -1,6 +1,7 @@
 # @nolto/cli
 
-A thin MCP client CLI for [Nolto](https://nolto.app) — register plans and update progress from your terminal. The installed command is `nolto`.
+The Nolto CLI keeps a repository's roadmap in sync with [Nolto](https://nolto.app).
+The installed command is `nolto`.
 
 ## Quick Start
 
@@ -10,82 +11,62 @@ Run once without installing:
 npx @nolto/cli init
 ```
 
-Or install it (globally or as a devDependency) to get the `nolto` command:
+Or install the CLI globally:
 
 ```bash
 npm install -g @nolto/cli
 nolto init
 ```
 
-Follow the prompts to configure your API token and default project. Then verify:
+`nolto init` configures authentication, selects or creates a project, writes the
+repo-local `nolto.json` binding, installs the bundled `roadmap-progress` skill,
+and creates `.roadmap/roadmap.json` when needed.
+
+For browser-based authentication without the rest of the repository setup:
 
 ```bash
-nolto whoami
+nolto login
 ```
 
 ## Commands
 
-### Setup
+### Setup and Authentication
 
 ```bash
-nolto init                    # Interactive setup
-nolto whoami                  # Show current auth/config state
+nolto init [--force]       # Interactive project and repository setup
+nolto login [--force]      # Authenticate in the browser and save the API token
+nolto whoami               # Show resolved auth/config state and project count
 ```
 
-### Repo Binding
-
-Bind the current repository to a Nolto project by writing a `nolto.json` at the repo root:
+### Repository Binding
 
 ```bash
-nolto link <projectId>   # Write nolto.json and commit it to share with your team
-nolto link --show        # Show the current binding (path, projectId, source)
-nolto link --unlink      # Remove the projectId key from nolto.json
+nolto link <projectId>     # Write or update nolto.json at the repository root
+nolto link --show          # Show the current binding and its source
+nolto link --unlink        # Remove projectId from nolto.json
 ```
 
-Once `nolto.json` is committed, every command in this repo automatically targets the correct project without needing `--project` or `NOLTO_PROJECT`.
-
-### Project Management
-
-```bash
-nolto project list
-nolto project register <name> [--description <text>] [--repository-url <url>]
-nolto project set-default <projectId>
-nolto project set-default <projectId> --local   # Config file only, no MCP call
-```
+Commit `nolto.json` so everyone working in the repository targets the same Nolto
+project.
 
-### Plan Management
+### Roadmap Sync
 
 ```bash
-nolto plan list [--status not_started|in_progress|done|discarded]
-nolto plan get <planId>
-nolto plan register --file PLAN.md [--title <text>] [--status <status>] \
-  [--planned-start <ISO>] [--planned-end <ISO>] \
-  [--phases <json>] [--doc kind=path ...] \
-  [--source-url <url>] [--source-hash <hex>] [--no-git]
-nolto plan status <planId> <status> [--message <text>]
-nolto plan review <planId> go|no_go [--summary <text>]
+nolto sync                         # Push roadmap.json and linked plan Markdown
+nolto watch [--debounce <ms>]      # Watch registered repositories and auto-sync
+nolto watch --install-service      # Install the Linux systemd user service
 ```
 
-### Phase Management
+`sync` reads `.roadmap/roadmap.json`, validates schema v2, follows any linked plan
+Markdown paths, and sends an idempotent full upsert to the bound project.
 
-```bash
-nolto phase status <planId> <phaseId> <status> [--message <text>]
-nolto phase test <planId> <phaseId> passed|failed|skipped \
-  [--round <n>] [--summary <text>]
-```
-
-### Document Upload
-
-```bash
-nolto doc upload <planId> --file <path> --kind plan|final_report|review_report|test_report|other \
-  [--phase <phaseId>] [--filename <name>]
-```
+`watch` uses the repository registry maintained by `nolto init`. Missing registered
+repositories are skipped with a warning.
 
 ## Configuration
 
-### Config File
-
-Location: `~/.config/nolto/config.json` (or `$XDG_CONFIG_HOME/nolto/config.json`), mode 0600.
+The config file is `~/.config/nolto/config.json` (or
+`$XDG_CONFIG_HOME/nolto/config.json`) and is written with mode 0600.
 
 ```json
 {
@@ -95,44 +76,35 @@ Location: `~/.config/nolto/config.json` (or `$XDG_CONFIG_HOME/nolto/config.json`
 }
 ```
 
-### Environment Variables
+Environment variables:
 
 | Variable | Description |
 |---|---|
 | `NOLTO_TOKEN` | API token |
 | `NOLTO_BASE_URL` | Base URL (default: `https://nolto.app`) |
-| `NOLTO_PROJECT` | Default project ID |
-
-### Repo Binding File
+| `NOLTO_PROJECT` | Default project ID fallback |
 
-`nolto.json` at the repository root pins the project for everyone who clones the repo:
+Repository binding (`nolto.json`):
 
 ```json
-{ "projectId": "00000000-0000-0000-0000-000000000001" }
+{
+  "projectId": "00000000-0000-0000-0000-000000000001",
+  "roadmapSlug": "my-repository"
+}
 ```
 
-**Precedence**: CLI flags > environment variables > `nolto.json` (repo binding) > config file > defaults
-
-## Exit Codes
-
-| Code | Meaning |
-|---|---|
-| 0 | Success |
-| 1 | MCP tool error (`result.isError: true` or JSON-RPC error) |
-| 2 | Local input validation error (bad args, file errors, etc.) |
-| 3 | Auth error (no token / 401 / 403) |
-| 4 | Rate limit (429) — message includes Retry-After seconds |
-| 5 | Network / DNS / connection error |
+Precedence: CLI flags > environment variables > `nolto.json` > config file > defaults.
 
 ## JSON Output
 
-Add `--json` for machine-readable output (results to stdout, errors to stderr):
+Use the global `--json` option for machine-readable command output:
 
 ```bash
-nolto plan list --json | jq '.[].id'
+nolto --json whoami
+nolto --json sync
 ```
 
-Errors are written to stderr as a structured envelope:
+Errors are written to stderr:
 
 ```json
 {
@@ -145,15 +117,16 @@ Errors are written to stderr as a structured envelope:
 }
 ```
 
-Fields: `message` (string), `exitCode` (number), `status` (HTTP status when known, optional), `hint` (optional guidance).
-
-## Rate Limits
-
-The MCP server enforces **60 requests/minute per user**. Each CLI command uses approximately 3 HTTP round-trips (initialize + initialized + tools/call), giving an effective throughput of **~20 commands/minute**.
-
-## SDK Note
+## Exit Codes
 
-This CLI uses `@modelcontextprotocol/sdk ^1.29.0` for Streamable HTTP transport. Keep in lockstep with the server SDK version for protocol compatibility.
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | Unexpected command failure |
+| 2 | Local input or file validation error |
+| 3 | Authentication or authorization error |
+| 4 | Rate limit response |
+| 5 | Network, DNS, or server error |
 
 ## License