@nolto/cli 0.6.0 → 0.7.0

package/README.md

@@ -20,7 +20,7 @@ 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 `.roadmap/roadmap.json` when needed.
+and creates `.nolto/roadmaps/<slug>.json` when needed.
 
 For browser-based authentication without the rest of the repository setup:
 
@@ -52,13 +52,15 @@ project.
 ### Roadmap Sync
 
 ```bash
-nolto sync                         # Push roadmap.json and linked plan Markdown
+nolto sync                         # Push roadmap JSON files and linked plan Markdown
 nolto watch [--debounce <ms>]      # Watch registered repositories and auto-sync
 nolto watch --install-service      # Install the Linux systemd user service
 ```
 
-`sync` reads `.roadmap/roadmap.json`, validates schema v2, follows any linked plan
-Markdown paths, and sends an idempotent full upsert to the bound project.
+`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.
 
 `watch` uses the repository registry maintained by `nolto init`. Missing registered
 repositories are skipped with a warning.
@@ -88,11 +90,13 @@ Repository binding (`nolto.json`):
 
 ```json
 {
-  "projectId": "00000000-0000-0000-0000-000000000001",
-  "roadmapSlug": "my-repository"
+  "projectId": "00000000-0000-0000-0000-000000000001"
 }
 ```
 
+The optional legacy `roadmapSlug` field is read only when naming an automatically
+migrated `.roadmap/roadmap.json`; canonical roadmap slugs come from filenames.
+
 Precedence: CLI flags > environment variables > `nolto.json` > config file > defaults.
 
 ## JSON Output

package/dist/index.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { createRequire as createRequire2 } from "module";
-import { fileURLToPath as fileURLToPath3 } from "url";
-import path12 from "path";
+import { createRequire as createRequire3 } from "module";
+import { fileURLToPath as fileURLToPath4 } from "url";
+import path13 from "path";
 import { CommanderError } from "commander";
 
 // src/config.ts
@@ -26,9 +26,9 @@ var CliError = class extends Error {
   hint;
   status;
 };
-function mapHttpStatusToCliError(status, retryAfter, wwwAuthenticate) {
+function mapHttpStatusToCliError(status, opts = {}) {
   if (status === 401) {
-    const detail = wwwAuthenticate ? ` (${wwwAuthenticate})` : "";
+    const detail = opts.wwwAuthenticate ? ` (${opts.wwwAuthenticate})` : "";
     return new CliError(
       `Unauthorized${detail}`,
       3,
@@ -36,16 +36,25 @@ function mapHttpStatusToCliError(status, retryAfter, wwwAuthenticate) {
       status
     );
   }
+  if (status === 402) {
+    const hint = opts.upgradeUrl != null ? `Upgrade: ${opts.upgradeUrl}` : void 0;
+    return new CliError(
+      opts.serverMessage ?? opts.serverError ?? "Payment Required",
+      4,
+      hint,
+      status
+    );
+  }
   if (status === 403) {
     return new CliError(
-      "Forbidden \u2014 insufficient scope",
+      opts.serverMessage ?? opts.serverError ?? "Forbidden",
       3,
-      "Ensure your API token has mcp:read and mcp:write scopes.",
+      "Check that your token belongs to a member of this project (`nolto whoami`).",
       status
     );
   }
   if (status === 429) {
-    const waitMsg = retryAfter ? ` Retry-After: ${retryAfter}s` : "";
+    const waitMsg = opts.retryAfter ? ` Retry-After: ${opts.retryAfter}s` : "";
     return new CliError(`Rate limit exceeded.${waitMsg}`, 4, void 0, status);
   }
   return new CliError(`Server returned HTTP ${status}`, 5, void 0, status);
@@ -155,9 +164,6 @@ async function mergeJsonFile(filePath, patch) {
 async function writeRepoBinding(root, projectId) {
   await mergeJsonFile(path.join(root, "nolto.json"), { projectId });
 }
-async function writeRoadmapSlug(root, slug) {
-  await mergeJsonFile(path.join(root, "nolto.json"), { roadmapSlug: slug });
-}
 function getConfigDir(env) {
   const xdg = env["XDG_CONFIG_HOME"];
   const base = xdg != null && xdg.length > 0 ? xdg : path.join(os.homedir(), ".config");
@@ -276,11 +282,11 @@ function maskToken(token) {
 function createHttpClient(opts) {
   const { baseUrl, version, token } = opts;
   const base = baseUrl.replace(/\/+$/, "");
-  async function request(method, path13, body) {
-    if (!path13.startsWith("/api/")) {
-      throw new CliError(`HTTP client path must start with /api/, got: ${path13}`, 2);
+  async function request(method, path14, body) {
+    if (!path14.startsWith("/api/")) {
+      throw new CliError(`HTTP client path must start with /api/, got: ${path14}`, 2);
     }
-    const url = `${base}${path13}`;
+    const url = `${base}${path14}`;
     const headers = {
       "Content-Type": "application/json",
       "User-Agent": `${CLI_USER_AGENT_NAME}/${version}`
@@ -307,7 +313,21 @@ function createHttpClient(opts) {
     if (!response.ok) {
       const retryAfter = response.headers.get("retry-after") ?? void 0;
       const wwwAuthenticate = response.headers.get("www-authenticate") ?? void 0;
-      throw mapHttpStatusToCliError(response.status, retryAfter, wwwAuthenticate);
+      let errorBody;
+      try {
+        const parsed = await response.json();
+        if (parsed != null && typeof parsed === "object" && !Array.isArray(parsed)) {
+          errorBody = parsed;
+        }
+      } catch {
+      }
+      throw mapHttpStatusToCliError(response.status, {
+        retryAfter,
+        wwwAuthenticate,
+        serverError: typeof errorBody?.["error"] === "string" ? errorBody["error"] : void 0,
+        serverMessage: typeof errorBody?.["message"] === "string" ? errorBody["message"] : void 0,
+        upgradeUrl: typeof errorBody?.["upgradeUrl"] === "string" ? errorBody["upgradeUrl"] : void 0
+      });
     }
     return response.json();
   }
@@ -418,7 +438,7 @@ async function handleShow(deps, projectBindingPath, mode2) {
     }
     return;
   }
-  const binding = await loadRepoBinding(projectBindingPath).catch((err) => {
+  const binding = deps.repoBinding != null ? deps.repoBinding.binding : await loadRepoBinding(projectBindingPath).catch((err) => {
     if (err instanceof CliError) throw err;
     throw new CliError(`Cannot read binding: ${String(err)}`, 2);
   });
@@ -511,6 +531,12 @@ Proceeding anyway \u2014 verify the ID is correct.
       );
     }
   }
+  if (deps.repoBinding?.error != null) {
+    process.stderr.write(
+      `Warning: existing nolto.json is invalid (${deps.repoBinding.error.message}). Overwriting it to repair.
+`
+    );
+  }
   await writeRepoBinding(root, projectId);
   const writtenPath = path2.join(root, "nolto.json");
   if (mode2 === "json") {
@@ -529,9 +555,13 @@ function register(program, deps) {
   ).option("--show", "Show the current repo binding (path + projectId + source)").option("--unlink", "Remove the projectId key from nolto.json");
   cmd.action(async (projectId) => {
     const { output } = deps;
-    const projectBindingPath = deps.projectBindingPath ?? null;
+    const projectBindingPath = deps.repoBinding?.path ?? deps.projectBindingPath ?? null;
+    const bindingError = deps.repoBinding?.error ?? null;
     const mode2 = output.mode;
     if (cmd.opts()["show"]) {
+      if (bindingError != null) {
+        throw invalidBindingError(projectBindingPath, bindingError);
+      }
       await handleShow(deps, projectBindingPath, mode2);
       return;
     }
@@ -543,6 +573,9 @@ function register(program, deps) {
       return;
     }
     if (projectId == null || projectId.trim().length === 0) {
+      if (bindingError != null) {
+        throw invalidBindingError(projectBindingPath, bindingError);
+      }
       throw new CliError(
         "Usage: nolto link <projectId>  (provide a UUID)\nOr use --show to view the current binding, --unlink to remove it.",
         2
@@ -551,6 +584,12 @@ function register(program, deps) {
     await performLink(deps, projectId, mode2);
   });
 }
+function invalidBindingError(projectBindingPath, error) {
+  return new CliError(
+    `Invalid nolto.json at ${projectBindingPath ?? "unknown path"}: ${error.message}. Repair it with \`nolto link <projectId>\` or \`nolto init\`.`,
+    2
+  );
+}
 
 // src/skill-install.ts
 import { cp, mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2, rm } from "fs/promises";
@@ -644,7 +683,7 @@ async function addRepoToRegistry(filePath, repoRoot) {
 }
 
 // src/roadmap-scaffold.ts
-import { mkdir as mkdir4, writeFile as writeFile4 } from "fs/promises";
+import { mkdir as mkdir4, readdir, writeFile as writeFile4 } from "fs/promises";
 import { existsSync as existsSync2 } from "fs";
 import path5 from "path";
 function slugifyProjectId(name) {
@@ -652,12 +691,23 @@ function slugifyProjectId(name) {
   return slug.length > 0 ? slug : "project";
 }
 async function scaffoldRoadmap(args) {
-  const dir = path5.join(args.repoRoot, ".roadmap");
-  const filePath = path5.join(dir, "roadmap.json");
-  if (existsSync2(filePath)) {
-    return { created: false, path: filePath };
-  }
   const repoBasename = path5.basename(args.repoRoot);
+  const dir = path5.join(args.repoRoot, ".nolto", "roadmaps");
+  const filePath = path5.join(dir, `${slugifyProjectId(repoBasename)}.json`);
+  const legacyPath = path5.join(args.repoRoot, ".roadmap", "roadmap.json");
+  try {
+    const existing = (await readdir(dir)).sort();
+    if (existing.length > 0) {
+      return { created: false, path: path5.join(dir, existing[0]) };
+    }
+  } catch (err) {
+    if (err == null || typeof err !== "object" || !("code" in err) || err.code !== "ENOENT") {
+      throw err;
+    }
+  }
+  if (existsSync2(legacyPath)) {
+    return { created: false, path: legacyPath };
+  }
   const roadmap = {
     schemaVersion: 2,
     project: {
@@ -803,6 +853,12 @@ Saved ${configPath}
           const setup = await rl.question(`
 Set up this repository (${root}) for roadmap sync? [Y/n] `);
           if (setup.trim().toLowerCase() !== "n") {
+            if (deps.repoBinding?.error != null) {
+              process.stderr.write(
+                `Warning: existing nolto.json is invalid (${deps.repoBinding.error.message}). Overwriting it to repair.
+`
+              );
+            }
             await writeRepoBinding(root, defaultProjectId);
             process.stdout.write(`binding:        wrote ${path6.join(root, "nolto.json")}
 `);
@@ -1027,7 +1083,7 @@ function register4(program, deps) {
       } catch {
       }
     }
-    const projectBindingPath = deps.projectBindingPath ?? null;
+    const projectBindingPath = deps.repoBinding?.path ?? deps.projectBindingPath ?? null;
     if (mode2 === "json") {
       printResult(
         {
@@ -1063,7 +1119,7 @@ function register4(program, deps) {
 }
 
 // src/commands/sync.ts
-import { readFile as readFile4 } from "fs/promises";
+import { copyFile, mkdir as mkdir5, readFile as readFile4, readdir as readdir2, rename, rmdir, unlink } from "fs/promises";
 import { existsSync as existsSync3 } from "fs";
 
 // src/sync-repo.ts
@@ -1219,8 +1275,7 @@ function collectPlanRefs(roadmap) {
   }
   return refs;
 }
-async function loadValidRoadmap(repoRoot, readFile7) {
-  const filePath = path7.join(repoRoot, ".roadmap", "roadmap.json");
+async function loadValidRoadmap(filePath, readFile7) {
   let raw;
   try {
     raw = await readFile7(filePath);
@@ -1236,7 +1291,7 @@ async function loadValidRoadmap(repoRoot, readFile7) {
   const { errors } = validateRoadmap(parsed);
   if (errors.length > 0) {
     throw new CliError(
-      `roadmap.json failed validation \u2014 not syncing:
+      `${filePath} failed validation \u2014 not syncing:
   ${errors.join("\n  ")}`,
       2
     );
@@ -1279,6 +1334,36 @@ async function runSync(args, deps) {
 }
 
 // src/sync-repo.ts
+var ROADMAP_SLUG_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+async function listRoadmapFiles(roadmapsDir, io) {
+  try {
+    const entries = await io.listDir(roadmapsDir);
+    return entries.filter((entry) => entry.endsWith(".json")).sort();
+  } catch (err) {
+    if (err != null && typeof err === "object" && "code" in err && err.code === "ENOENT") {
+      return [];
+    }
+    throw err;
+  }
+}
+async function migrateLegacyRoadmap(args) {
+  const targetPath = path8.join(args.roadmapsDir, `${args.slug}.json`);
+  await args.io.mkdir(args.roadmapsDir);
+  try {
+    await args.io.rename(args.legacyPath, targetPath);
+  } catch {
+    await args.io.copyFile(args.legacyPath, targetPath);
+    await args.io.unlink(args.legacyPath);
+  }
+  try {
+    await args.io.rmdir(path8.dirname(args.legacyPath));
+  } catch {
+  }
+  args.io.log(
+    `migrated .roadmap/roadmap.json \u2192 .nolto/roadmaps/${args.slug}.json \u2014 commit this change (ensure .nolto/ is not gitignored)`
+  );
+  return `${args.slug}.json`;
+}
 async function syncRepo(args, io) {
   const bindingPath = path8.join(args.root, "nolto.json");
   const binding = await loadRepoBinding(bindingPath);
@@ -1286,24 +1371,65 @@ async function syncRepo(args, io) {
   if (projectId == null) {
     throw new CliError("No project binding. Run `nolto init` or `nolto link <projectId>`.", 2);
   }
-  let slug = binding?.roadmapSlug;
-  if (slug == null) {
-    slug = slugifyProjectId(path8.basename(args.root));
-    await writeRoadmapSlug(args.root, slug);
-    io.log(`roadmapSlug not set \u2014 derived "${slug}" and saved to nolto.json`);
+  const roadmapsDir = path8.join(args.root, ".nolto", "roadmaps");
+  const legacyPath = path8.join(args.root, ".roadmap", "roadmap.json");
+  let roadmapFiles = await listRoadmapFiles(roadmapsDir, io);
+  if (roadmapFiles.length > 0) {
+    if (io.fileExists(legacyPath)) {
+      io.warn(
+        "legacy .roadmap/roadmap.json is ignored because .nolto/roadmaps/ already contains roadmap files"
+      );
+    }
+  } else if (io.fileExists(legacyPath)) {
+    const migrationSlug = binding?.roadmapSlug ?? slugifyProjectId(path8.basename(args.root));
+    roadmapFiles = [
+      await migrateLegacyRoadmap({
+        slug: migrationSlug,
+        legacyPath,
+        roadmapsDir,
+        io
+      })
+    ];
+  } else {
+    throw new CliError(
+      `No roadmap found in ${roadmapsDir}. Run \`nolto init\` to create one.`,
+      2
+    );
   }
-  const roadmap = await loadValidRoadmap(args.root, io.readFile);
-  const response = await runSync(
-    { repoRoot: args.root, projectId, slug, roadmap },
-    { http: io.http, readFile: io.readFile, fileExists: io.fileExists, log: io.log, warn: io.warn }
+  const roadmaps = await Promise.all(
+    roadmapFiles.map(async (fileName) => {
+      const slug = fileName.slice(0, -".json".length);
+      if (!ROADMAP_SLUG_PATTERN.test(slug)) {
+        throw new CliError(
+          `Invalid roadmap filename "${fileName}": slug must match ^[a-z0-9][a-z0-9._-]*$.`,
+          2
+        );
+      }
+      const filePath = path8.join(roadmapsDir, fileName);
+      return { slug, roadmap: await loadValidRoadmap(filePath, io.readFile) };
+    })
   );
-  const planAbsPaths = collectPlanRefs(roadmap).map((ref) => path8.join(args.root, ref.path));
-  return { ...response, planAbsPaths };
+  const planAbsPaths = /* @__PURE__ */ new Set();
+  for (const { roadmap } of roadmaps) {
+    for (const ref of collectPlanRefs(roadmap)) {
+      planAbsPaths.add(path8.join(args.root, ref.path));
+    }
+  }
+  const results = [];
+  for (const { slug, roadmap } of roadmaps) {
+    results.push(
+      await runSync(
+        { repoRoot: args.root, projectId, slug, roadmap },
+        { http: io.http, readFile: io.readFile, fileExists: io.fileExists, log: io.log, warn: io.warn }
+      )
+    );
+  }
+  return { results, planAbsPaths: [...planAbsPaths] };
 }
 
 // src/commands/sync.ts
 function register5(program, deps) {
-  program.command("sync").description("Push .roadmap/roadmap.json and linked plan documents to Nolto (idempotent full upsert).").action(async () => {
+  program.command("sync").description("Push .nolto/roadmaps/*.json and linked plan documents to Nolto (idempotent full upsert).").action(async () => {
     if (deps.settings.token == null) {
       throw new CliError("Not authenticated. Run `nolto login` or set NOLTO_TOKEN.", 3);
     }
@@ -1322,6 +1448,12 @@ function register5(program, deps) {
       {
         readFile: (p) => readFile4(p, "utf8"),
         fileExists: (p) => existsSync3(p),
+        listDir: (p) => readdir2(p),
+        rename,
+        copyFile,
+        mkdir: (p) => mkdir5(p, { recursive: true }).then(() => void 0),
+        unlink,
+        rmdir,
         http,
         log: (line) => process.stdout.write(line + "\n"),
         warn: (line) => process.stderr.write("Warning: " + line + "\n")
@@ -1335,12 +1467,61 @@ function register5(program, deps) {
 }
 
 // src/commands/watch.ts
-import { readFile as readFile5 } from "fs/promises";
+import { copyFile as copyFile2, mkdir as mkdir6, readFile as readFile5, readdir as readdir3, rename as rename2, rmdir as rmdir2, unlink as unlink2 } from "fs/promises";
 import { existsSync as existsSync4 } from "fs";
 import path10 from "path";
 import chokidar from "chokidar";
 
 // src/watch-core.ts
+var WatchSet = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  deps;
+  handles = /* @__PURE__ */ new Map();
+  async reconcile(roots) {
+    const nextRoots = new Set(roots);
+    for (const [root, handle] of this.handles) {
+      if (nextRoots.has(root)) continue;
+      try {
+        await handle.stop();
+      } catch (err) {
+        this.deps.log(
+          `Failed to stop watching ${root}: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+      this.handles.delete(root);
+      this.deps.log(`Stopped watching ${root}`);
+    }
+    for (const root of nextRoots) {
+      if (this.handles.has(root)) continue;
+      this.handles.set(root, this.deps.start(root));
+      this.deps.log(`Watching ${root}`);
+    }
+  }
+  async stopAll() {
+    await this.reconcile([]);
+  }
+  size() {
+    return this.handles.size;
+  }
+};
+async function reloadRoots(deps) {
+  let registry;
+  try {
+    registry = await deps.load();
+  } catch (err) {
+    deps.warn(
+      `registry reload failed: ${err instanceof Error ? err.message : String(err)} \u2014 keeping current watch set`
+    );
+    return null;
+  }
+  return registry.repos.map((repo) => repo.root).filter((root) => {
+    if (deps.exists(root)) return true;
+    deps.warn(`registered repo no longer exists, skipping: ${root}`);
+    return false;
+  });
+}
 var RepoWatch = class {
   constructor(root, deps) {
     this.root = root;
@@ -1418,6 +1599,13 @@ function getUnitPath(env) {
   return path9.join(base, "systemd", "user", "nolto-watch.service");
 }
 async function installServiceWith(deps) {
+  if (deps.platform !== "linux") {
+    throw new CliError(
+      "--install-service requires systemd and is only supported on Linux.",
+      2,
+      "Run `nolto watch` manually in a terminal instead."
+    );
+  }
   const unitPath = getUnitPath(deps.env);
   await deps.mkdir(path9.dirname(unitPath));
   await deps.writeFile(unitPath, buildUnitFile({ nodePath: deps.nodePath, scriptPath: deps.scriptPath }));
@@ -1433,17 +1621,18 @@ async function installServiceWith(deps) {
   deps.log("Service nolto-watch enabled and started. Logs: journalctl --user -u nolto-watch -f");
 }
 async function installService() {
-  const { writeFile: writeFile6, mkdir: mkdir6 } = await import("fs/promises");
-  const { execFile } = await import("child_process");
-  const { promisify } = await import("util");
-  const execFileAsync = promisify(execFile);
+  const { writeFile: writeFile6, mkdir: mkdir8 } = await import("fs/promises");
+  const { execFile: execFile2 } = await import("child_process");
+  const { promisify: promisify2 } = await import("util");
+  const execFileAsync = promisify2(execFile2);
   await installServiceWith({
+    platform: process.platform,
     env: process.env,
     nodePath: process.execPath,
     scriptPath: path9.resolve(process.argv[1] ?? ""),
     writeFile: (p, content) => writeFile6(p, content, "utf8"),
     mkdir: async (p) => {
-      await mkdir6(p, { recursive: true });
+      await mkdir8(p, { recursive: true });
     },
     exec: async (cmd) => {
       try {
@@ -1458,14 +1647,81 @@ async function installService() {
     warn: (line) => process.stderr.write("Warning: " + line + "\n")
   });
 }
+async function uninstallServiceWith(deps) {
+  if (deps.platform !== "linux") {
+    throw new CliError(
+      "--uninstall-service requires systemd and is only supported on Linux.",
+      2
+    );
+  }
+  const unitPath = getUnitPath(deps.env);
+  const disable = await deps.exec(["systemctl", "--user", "disable", "--now", "nolto-watch"]);
+  let unlinkError;
+  try {
+    await deps.unlink(unitPath);
+    deps.log(`Removed ${unitPath}`);
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      deps.log(`Unit file not found at ${unitPath}; nothing to remove.`);
+    } else {
+      unlinkError = err;
+    }
+  }
+  const reload = await deps.exec(["systemctl", "--user", "daemon-reload"]);
+  const systemctlFailed = disable.code !== 0 || reload.code !== 0;
+  if (systemctlFailed) {
+    deps.warn(
+      `Could not deactivate the service automatically. Run manually:
+  systemctl --user disable --now nolto-watch
+  rm -f "${unitPath}"
+  systemctl --user daemon-reload`
+    );
+  }
+  if (unlinkError != null) {
+    throw unlinkError;
+  }
+  if (systemctlFailed) {
+    return;
+  }
+  deps.log("Service nolto-watch stopped, disabled, and removed.");
+}
+async function uninstallService() {
+  const { unlink: unlink3 } = await import("fs/promises");
+  const { execFile: execFile2 } = await import("child_process");
+  const { promisify: promisify2 } = await import("util");
+  const execFileAsync = promisify2(execFile2);
+  await uninstallServiceWith({
+    platform: process.platform,
+    env: process.env,
+    unlink: unlink3,
+    exec: async (cmd) => {
+      try {
+        await execFileAsync(cmd[0], cmd.slice(1));
+        return { code: 0, stderr: "" };
+      } catch (err) {
+        const e = err;
+        return { code: e.code ?? 1, stderr: e.stderr ?? String(err) };
+      }
+    },
+    log: (line) => process.stdout.write(line + "\n"),
+    warn: (line) => process.stderr.write("Warning: " + line + "\n")
+  });
+}
 
 // src/commands/watch.ts
 function register6(program, deps) {
-  program.command("watch").description("Watch every registered repository's roadmap + plan files and sync on change.").option("--debounce <ms>", "Debounce window in milliseconds", "2000").option("--install-service", "Install and enable a systemd user unit (nolto-watch) instead of watching").action(async (opts) => {
+  program.command("watch").description("Watch every registered repository's roadmap + plan files and sync on change.").option("--debounce <ms>", "Debounce window in milliseconds", "2000").option("--install-service", "Install and enable a systemd user unit (nolto-watch) instead of watching").option("--uninstall-service", "Stop and remove the systemd user unit (nolto-watch) instead of watching").action(async (opts) => {
+    if (opts.installService && opts.uninstallService) {
+      throw new CliError("--install-service and --uninstall-service cannot be used together.", 2);
+    }
     if (opts.installService) {
       await installService();
       return;
     }
+    if (opts.uninstallService) {
+      await uninstallService();
+      return;
+    }
     if (deps.settings.token == null) {
       throw new CliError("Not authenticated. Run `nolto login` or set NOLTO_TOKEN.", 3);
     }
@@ -1473,7 +1729,8 @@ function register6(program, deps) {
     if (Number.isNaN(debounceMs) || debounceMs < 0) {
       throw new CliError("--debounce must be a non-negative integer.", 2);
     }
-    const registry = await loadRegistry(getRegistryPath(process.env));
+    const registryPath = getRegistryPath(process.env);
+    const registry = await loadRegistry(registryPath);
     const roots = registry.repos.map((r) => r.root).filter((root) => {
       if (existsSync4(root)) return true;
       process.stderr.write(`Warning: registered repo no longer exists, skipping: ${root}
@@ -1488,17 +1745,22 @@ function register6(program, deps) {
       version: deps.version,
       token: deps.settings.token
     });
-    const watchers = [];
-    for (const root of roots) {
-      const roadmapPath = path10.join(root, ".roadmap", "roadmap.json");
-      const watcher = chokidar.watch([roadmapPath], { ignoreInitial: true });
-      watchers.push(watcher);
+    const startRepo = (root) => {
+      const roadmapsPath = path10.join(root, ".nolto", "roadmaps");
+      const legacyRoadmapPath = path10.join(root, ".roadmap", "roadmap.json");
+      const watcher = chokidar.watch([roadmapsPath, legacyRoadmapPath], { ignoreInitial: true });
       const repoWatch = new RepoWatch(root, {
         sync: () => syncRepo(
           { root, defaultProjectId: deps.settings.defaultProjectId },
           {
             readFile: (p) => readFile5(p, "utf8"),
             fileExists: (p) => existsSync4(p),
+            listDir: (p) => readdir3(p),
+            rename: rename2,
+            copyFile: copyFile2,
+            mkdir: (p) => mkdir6(p, { recursive: true }).then(() => void 0),
+            unlink: unlink2,
+            rmdir: rmdir2,
             http,
             log: (line) => process.stdout.write(`[${path10.basename(root)}] ${line}
 `),
@@ -1515,12 +1777,41 @@ function register6(program, deps) {
       });
       watcher.on("all", (_event, filePath) => repoWatch.handleEvent(filePath));
       void repoWatch.flush();
-    }
+      return { stop: () => watcher.close() };
+    };
+    const watchSet = new WatchSet({
+      start: startRepo,
+      log: (line) => process.stdout.write(line + "\n")
+    });
+    await watchSet.reconcile(roots);
+    const registryWatcher = chokidar.watch(registryPath, { ignoreInitial: true });
+    let registryReloadTimer = null;
+    registryWatcher.on("all", () => {
+      if (registryReloadTimer != null) clearTimeout(registryReloadTimer);
+      registryReloadTimer = setTimeout(() => {
+        registryReloadTimer = null;
+        void reloadRoots({
+          load: () => loadRegistry(registryPath),
+          exists: (root) => existsSync4(root),
+          warn: (line) => process.stderr.write(`Warning: ${line}
+`)
+        }).then(async (newRoots) => {
+          if (newRoots == null) return;
+          await watchSet.reconcile(newRoots);
+          if (newRoots.length === 0) {
+            process.stderr.write(
+              "Warning: registry is empty \u2014 watching 0 repositories until repos are registered\n"
+            );
+          }
+        });
+      }, 500);
+    });
     process.stdout.write(`Watching ${roots.length} repositories (debounce ${debounceMs}ms). Ctrl-C to stop.
 `);
     await new Promise((resolve) => {
       const stop = () => {
-        void Promise.all(watchers.map((w) => w.close())).then(() => resolve());
+        if (registryReloadTimer != null) clearTimeout(registryReloadTimer);
+        void Promise.all([registryWatcher.close(), watchSet.stopAll()]).then(() => resolve());
       };
       process.once("SIGINT", stop);
       process.once("SIGTERM", stop);
@@ -1528,25 +1819,17 @@ function register6(program, deps) {
   });
 }
 
-// src/program.ts
-function stripCommanderErrorPrefix(msg) {
-  return msg.startsWith("error: ") ? msg.slice("error: ".length) : msg;
-}
-function buildProgram(deps) {
-  const writeErr = (_msg) => {
-  };
-  const program = new Command("nolto").version(deps.version, "-V, --version", "Print version number").exitOverride().configureOutput({ writeErr }).description("Nolto CLI \u2014 sync repository roadmaps with Nolto.").option("--token <value>", "API token (overrides env/file)").option("--base-url <url>", "Nolto base URL (default: https://nolto.app)").option("--project <projectId>", "Default project ID").option("--json", "Output as JSON");
-  register2(program, deps);
-  register3(program, deps);
-  register4(program, deps);
-  register(program, deps);
-  register5(program, deps);
-  register6(program, deps);
-  return program;
-}
+// src/update-cli.ts
+import { execFile } from "child_process";
+import { existsSync as existsSync5 } from "fs";
+import { realpath } from "fs/promises";
+import { createRequire as createRequire2 } from "module";
+import path12 from "path";
+import { fileURLToPath as fileURLToPath3 } from "url";
+import { promisify } from "util";
 
 // src/update-notifier.ts
-import { readFile as readFile6, writeFile as writeFile5, mkdir as mkdir5 } from "fs/promises";
+import { readFile as readFile6, writeFile as writeFile5, mkdir as mkdir7 } from "fs/promises";
 import https from "https";
 import path11 from "path";
 var PACKAGE = "@nolto/cli";
@@ -1566,17 +1849,17 @@ function isNewerVersion(latest, current) {
 }
 function formatUpdateNotice(latest, current) {
   return `
-Update available: ${current} \u2192 ${latest}  \xB7  npm i -g @nolto/cli@latest
+Update available: ${current} \u2192 ${latest}  \xB7  run \`nolto update\`
 `;
 }
 function isDisabled(env) {
   return env["NO_UPDATE_NOTIFIER"] === "1" || env["NODE_ENV"] === "test" || Boolean(env["CI"]);
 }
-function fetchLatestFromRegistry() {
+function fetchLatestFromRegistry(timeoutMs = REQUEST_TIMEOUT_MS) {
   return new Promise((resolve) => {
     const req = https.get(
       `https://registry.npmjs.org/${PACKAGE}/latest`,
-      { timeout: REQUEST_TIMEOUT_MS, headers: { accept: "application/json" } },
+      { timeout: timeoutMs, headers: { accept: "application/json" } },
       (res) => {
         if (res.statusCode !== 200) {
           res.resume();
@@ -1603,12 +1886,15 @@ function fetchLatestFromRegistry() {
     req.on("error", () => resolve(null));
   });
 }
+async function writeUpdateCache(cachePath, now, latest) {
+  await mkdir7(path11.dirname(cachePath), { recursive: true });
+  const payload = { checkedAt: now, latest };
+  await writeFile5(cachePath, JSON.stringify(payload), { mode: 384 });
+}
 async function refreshCache(cachePath, now, fetchLatest) {
   const latest = await fetchLatest();
   if (!latest) return;
-  await mkdir5(path11.dirname(cachePath), { recursive: true }).catch(() => void 0);
-  const payload = { checkedAt: now, latest };
-  await writeFile5(cachePath, JSON.stringify(payload), { mode: 384 }).catch(() => void 0);
+  await writeUpdateCache(cachePath, now, latest).catch(() => void 0);
 }
 async function checkForUpdate(opts) {
   if (isDisabled(opts.env)) return null;
@@ -1642,12 +1928,197 @@ async function notifyUpdate(opts) {
   }
 }
 
+// src/update-cli.ts
+var PACKAGE2 = "@nolto/cli";
+var UPDATE_CACHE_FILE = "update-check.json";
+var UPDATE_REQUEST_TIMEOUT_MS = 1e4;
+function isNpxPath(scriptPath) {
+  return /[\\/]_npx[\\/]/.test(scriptPath);
+}
+function isInsideGlobalPackage(scriptPath, globalRoot, platform) {
+  if (globalRoot.length === 0) return false;
+  const normalize = (value) => value.replaceAll("\\", "/").replace(/\/+$/, "");
+  const normalizedScript = normalize(scriptPath);
+  const packagePrefix = `${normalize(globalRoot)}/${PACKAGE2}/`;
+  if (platform === "win32") {
+    return normalizedScript.toLowerCase().startsWith(packagePrefix.toLowerCase());
+  }
+  return normalizedScript.startsWith(packagePrefix);
+}
+function notGlobalError(scriptPath) {
+  return new CliError(
+    `${PACKAGE2} is not installed as an npm global package (running from ${scriptPath}).`,
+    2,
+    `Update it the same way it was installed, or install globally: npm i -g ${PACKAGE2}`
+  );
+}
+function stderrTail(stderr) {
+  return stderr.trim().slice(-500);
+}
+async function updateCliWith(deps) {
+  if (isNpxPath(deps.scriptPath)) {
+    throw new CliError(
+      `Cannot self-update an npx invocation. Install globally: npm i -g ${PACKAGE2}`,
+      2
+    );
+  }
+  const rootResult = await deps.exec(["npm", "root", "-g"]);
+  const reportedRoot = rootResult.stdout.trim();
+  let globalRoot;
+  try {
+    globalRoot = rootResult.code === 0 && reportedRoot.length > 0 ? await deps.realpath(reportedRoot) : "";
+  } catch {
+    globalRoot = "";
+  }
+  if (!isInsideGlobalPackage(deps.scriptPath, globalRoot, deps.platform)) {
+    throw notGlobalError(deps.scriptPath);
+  }
+  const latest = await deps.fetchLatest();
+  if (latest == null) {
+    throw new CliError(
+      "Could not reach the npm registry to check for the latest @nolto/cli version.",
+      5
+    );
+  }
+  if (!isNewerVersion(latest, deps.currentVersion)) {
+    deps.log(`Already up to date (${PACKAGE2} ${deps.currentVersion}).`);
+    return {
+      status: "up-to-date",
+      from: deps.currentVersion,
+      to: deps.currentVersion,
+      watchService: "not-installed"
+    };
+  }
+  const installResult = await deps.exec([
+    "npm",
+    "install",
+    "-g",
+    `${PACKAGE2}@${latest}`
+  ]);
+  if (installResult.code !== 0) {
+    const detail = stderrTail(installResult.stderr);
+    throw new CliError(
+      `Could not update ${PACKAGE2}${detail.length > 0 ? `: ${detail}` : "."}`,
+      5,
+      /EACCES|permission denied/i.test(installResult.stderr) ? "Permission denied \u2014 check your npm global prefix (npm config get prefix) or re-run with elevated permissions." : void 0
+    );
+  }
+  deps.log(`Updated ${PACKAGE2} ${deps.currentVersion} \u2192 ${latest}.`);
+  await deps.writeCache(
+    path12.join(deps.configDir, UPDATE_CACHE_FILE),
+    deps.now,
+    latest
+  ).catch(() => void 0);
+  let watchService = "not-installed";
+  const unitPath = getUnitPath(deps.env);
+  if (deps.platform === "linux" && deps.unitExists(unitPath)) {
+    const restartResult = await deps.exec([
+      "systemctl",
+      "--user",
+      "restart",
+      "nolto-watch"
+    ]);
+    if (restartResult.code === 0) {
+      watchService = "restarted";
+      deps.log("Restarted nolto-watch service.");
+    } else {
+      watchService = "restart-failed";
+      deps.warn(
+        "Could not restart nolto-watch automatically. Run manually:\n  systemctl --user restart nolto-watch"
+      );
+    }
+  }
+  return {
+    status: "updated",
+    from: deps.currentVersion,
+    to: latest,
+    watchService
+  };
+}
+function getCurrentVersion() {
+  const dirname = path12.dirname(fileURLToPath3(import.meta.url));
+  const require3 = createRequire2(import.meta.url);
+  try {
+    const pkg = require3(path12.resolve(dirname, "../package.json"));
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+async function updateCli(opts = {}) {
+  const execFileAsync = promisify(execFile);
+  const scriptPath = await realpath(process.argv[1] ?? "");
+  return updateCliWith({
+    currentVersion: getCurrentVersion(),
+    scriptPath,
+    platform: process.platform,
+    env: process.env,
+    configDir: getConfigDir(process.env),
+    now: Date.now(),
+    exec: async (cmd) => {
+      try {
+        const result = await execFileAsync(cmd[0], cmd.slice(1), { encoding: "utf8" });
+        return { code: 0, stdout: String(result.stdout), stderr: String(result.stderr) };
+      } catch (err) {
+        const e = err;
+        return {
+          code: typeof e.code === "number" ? e.code : 1,
+          stdout: e.stdout ?? "",
+          stderr: e.stderr ?? String(err)
+        };
+      }
+    },
+    realpath,
+    fetchLatest: () => fetchLatestFromRegistry(UPDATE_REQUEST_TIMEOUT_MS),
+    writeCache: writeUpdateCache,
+    unitExists: existsSync5,
+    log: opts.quiet === true ? () => void 0 : (line) => process.stdout.write(line + "\n"),
+    warn: (line) => process.stderr.write("Warning: " + line + "\n")
+  });
+}
+
+// src/commands/update.ts
+function register7(program, deps) {
+  program.command("update").description("Update @nolto/cli to the latest version and restart the watch service if installed").action(async () => {
+    const mode2 = deps.output.mode;
+    const result = await updateCli({ quiet: mode2 === "json" });
+    if (mode2 === "json") {
+      printResult(result, mode2);
+    }
+  });
+}
+
+// src/program.ts
+function stripCommanderErrorPrefix(msg) {
+  return msg.startsWith("error: ") ? msg.slice("error: ".length) : msg;
+}
+function buildProgram(deps) {
+  const writeErr = (_msg) => {
+  };
+  const program = new Command("nolto").version(deps.version, "-V, --version", "Print version number").exitOverride().configureOutput({ writeErr }).description("Nolto CLI \u2014 sync repository roadmaps with Nolto.").option("--token <value>", "API token (overrides env/file)").option("--base-url <url>", "Nolto base URL (default: https://nolto.app)").option("--project <projectId>", "Default project ID").option("--json", "Output as JSON");
+  register2(program, deps);
+  register3(program, deps);
+  register4(program, deps);
+  register(program, deps);
+  register5(program, deps);
+  register6(program, deps);
+  register7(program, deps);
+  program.hook("preAction", (_thisCommand, actionCommand) => {
+    const bindingError = deps.repoBinding?.error;
+    const bindingExemptCommands = ["init", "link", "update"];
+    if (bindingError != null && !bindingExemptCommands.includes(actionCommand.name())) {
+      throw bindingError;
+    }
+  });
+  return program;
+}
+
 // src/index.ts
-var __dirname3 = path12.dirname(fileURLToPath3(import.meta.url));
-var require2 = createRequire2(import.meta.url);
+var __dirname3 = path13.dirname(fileURLToPath4(import.meta.url));
+var require2 = createRequire3(import.meta.url);
 function getVersion() {
   try {
-    const pkgPath = path12.resolve(__dirname3, "../package.json");
+    const pkgPath = path13.resolve(__dirname3, "../package.json");
     const pkg = require2(pkgPath);
     return pkg.version ?? "0.0.0";
   } catch {
@@ -1681,19 +2152,21 @@ async function main() {
     }
   }
   const projectBindingPath = findRepoBindingFile({ env: process.env, cwd: process.cwd() });
-  const repoBinding = projectBindingPath != null ? await loadRepoBinding(projectBindingPath).catch((err) => {
+  const repoBinding = projectBindingPath != null ? await loadRepoBinding(projectBindingPath).then((binding) => ({
+    binding,
+    path: projectBindingPath,
+    error: null
+  })).catch((err) => {
     if (err instanceof CliError) {
-      printError(err, mode);
-      process.exitCode = err.exitCode;
-      process.exit();
+      return { binding: null, path: projectBindingPath, error: err };
     }
     throw err;
-  }) : null;
+  }) : { binding: null, path: null, error: null };
   const settings = resolveSettings({
     flags: { token: flagToken, baseUrl: flagBaseUrl, project: flagProject },
     env: process.env,
     file: configFile,
-    repoBinding
+    repoBinding: repoBinding.binding
   });
   const version = getVersion();
   const http = createHttpClient({
@@ -1707,7 +2180,7 @@ async function main() {
     output: { mode },
     version,
     configPath,
-    projectBindingPath
+    repoBinding
   });
   await program.parseAsync(process.argv);
   await notifyUpdate({ current: version, env: process.env, isJson: mode === "json", now: Date.now() });

package/dist/skill/roadmap-progress/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: roadmap-progress
-description: Maintain a local project's `.roadmap/roadmap.json` as work starts, completes, becomes blocked, or is replanned. Use when Codex or Claude plans project phases and tasks, begins or finishes an implementation task, reports project progress, records a blocker, or needs to keep the Roadmap Viewer current. Do not mark work done without verification. Attach plan documents to tasks with the plan command.
+description: Maintain a local project's `.nolto/roadmaps/<slug>.json` as work starts, completes, becomes blocked, or is replanned. Use when Codex or Claude plans project phases and tasks, begins or finishes an implementation task, reports project progress, records a blocker, or needs to keep the Roadmap Viewer current. Do not mark work done without verification. Attach plan documents to tasks with the plan command.
 ---
 
 # Roadmap Progress
 
-Keep `.roadmap/roadmap.json` synchronized with verified repository work. Treat the file as the source of truth for progress reporting.
+Keep `.nolto/roadmaps/<slug>.json` synchronized with verified repository work. Treat the file as the source of truth for progress reporting.
 
 ## Resolve the roadmap
 
 1. Use the roadmap named by the user when provided.
-2. Otherwise locate `.roadmap/roadmap.json` from the current directory upward.
+2. Otherwise locate `.nolto/roadmaps/*.json` from the current directory upward. If exactly one exists, use it. If multiple exist, ask the user to choose one and pass it with `--file <path>`.
 3. If no roadmap exists and the user asked to plan or initialize the project, create one using [references/schema.md](references/schema.md). Otherwise report that it is missing; do not invent project scope.
 4. Read [references/schema.md](references/schema.md) before creating phases or tasks, changing IDs, or repairing validation errors.
 
@@ -40,7 +40,7 @@ Edit phases and tasks directly while preserving stable IDs. Add dependencies onl
 
 When an implementation plan exists as a markdown file in the repository,
 link it to its task: `roadmap.mjs plan <task-id> --path docs/plans/feature.md`.
-Paths are repository-relative (the repository root is the parent of `.roadmap/`).
+Paths are repository-relative (the repository root is the parent of `.nolto/`).
 The command warns if the file does not exist yet; create the plan file first
 when possible.
 

package/dist/skill/roadmap-progress/references/schema.md

@@ -1,6 +1,6 @@
 # Roadmap schema
 
-Use this reference when creating or structurally editing `.roadmap/roadmap.json`.
+Use this reference when creating or structurally editing `.nolto/roadmaps/<slug>.json`.
 
 ## Shape
 

package/dist/skill/roadmap-progress/scripts/roadmap.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { access, readFile, rename, writeFile } from "node:fs/promises";
+import { access, readFile, readdir, rename, writeFile } from "node:fs/promises";
 import path from "node:path";
 
 const STATUSES = new Set(["todo", "in-progress", "done", "blocked"]);
@@ -27,19 +27,53 @@ function parseArguments(argv) {
 
 async function findRoadmap(explicitPath) {
   if (explicitPath) return path.resolve(explicitPath);
+
+  const directories = [];
   let directory = process.cwd();
   while (true) {
-    const candidate = path.join(directory, ".roadmap", "roadmap.json");
+    directories.push(directory);
+    const roadmapsDirectory = path.join(directory, ".nolto", "roadmaps");
     try {
-      await access(candidate);
-      return candidate;
+      const candidates = (await readdir(roadmapsDirectory, { withFileTypes: true }))
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+        .map((entry) => path.join(roadmapsDirectory, entry.name))
+        .sort();
+      if (candidates.length === 1) return candidates[0];
+      if (candidates.length > 1) {
+        throw new Error(
+          `Multiple roadmaps found; pass --file <path> to choose one:\n  ${candidates.join("\n  ")}`
+        );
+      }
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) break;
+    directory = parent;
+  }
+
+  for (const candidateRoot of directories) {
+    const legacyCandidate = path.join(candidateRoot, ".roadmap", "roadmap.json");
+    try {
+      await access(legacyCandidate);
+      console.warn(
+        `WARN deprecated roadmap path ${legacyCandidate}; migrate it to .nolto/roadmaps/<slug>.json`
+      );
+      return legacyCandidate;
     } catch {
-      const parent = path.dirname(directory);
-      if (parent === directory) break;
-      directory = parent;
+      // Continue walking upward.
     }
   }
-  throw new Error("No .roadmap/roadmap.json found. Pass --file <path>.");
+  throw new Error("No .nolto/roadmaps/*.json found. Pass --file <path>.");
+}
+
+function repoRootForRoadmap(filePath) {
+  const parent = path.dirname(filePath);
+  if (path.basename(parent) === "roadmaps" && path.basename(path.dirname(parent)) === ".nolto") {
+    return path.dirname(path.dirname(parent));
+  }
+  if (path.basename(parent) === ".roadmap") return path.dirname(parent);
+  return path.dirname(filePath);
 }
 
 function localIsoNow() {
@@ -228,7 +262,7 @@ try {
     task.plan = options.path;
     roadmap.schemaVersion = 2;
     roadmap.updatedAt = localIsoNow();
-    const repoRoot = path.dirname(path.dirname(filePath));
+    const repoRoot = repoRootForRoadmap(filePath);
     try {
       await access(path.join(repoRoot, options.path));
     } catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nolto/cli",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "CLI for syncing repository roadmaps with Nolto.",
   "license": "MIT",
   "type": "module",
@@ -36,12 +36,12 @@
     "prepublishOnly": "npm run typecheck && npm test && npm run build"
   },
   "dependencies": {
-    "@nolto/roadmap-schema": "0.1.0",
     "chokidar": "^4.0.3",
     "commander": "^14.0.0",
     "zod": "^3.24.1"
   },
   "devDependencies": {
+    "@nolto/roadmap-schema": "0.1.0",
     "@types/node": "^22.0.0",
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",