@odla-ai/cli 0.43.1 → 0.45.0

package/dist/index.cjs

@@ -1234,10 +1234,17 @@ function parseArgv(argv) {
 function assertArgs(parsed, allowedOptions2, maxPositionals) {
   const allowed = new Set(allowedOptions2);
   for (const name of Object.keys(parsed.options)) {
-    if (!allowed.has(name)) throw new Error(`unknown option "--${name}"; run "odla-ai help" for supported options`);
+    if (allowed.has(name)) continue;
+    const accepts = [...allowed].sort().map((option) => `--${option}`).join(" ");
+    throw new Error(
+      `unknown option "--${name}"` + (accepts ? ` \u2014 this command accepts: ${accepts}` : " \u2014 this command takes no options")
+    );
   }
   if (parsed.positionals.length > maxPositionals) {
-    throw new Error(`unexpected argument "${parsed.positionals[maxPositionals]}"; run "odla-ai help"`);
+    const taken = parsed.positionals.slice(0, maxPositionals).join(" ");
+    throw new Error(
+      `unexpected argument "${parsed.positionals[maxPositionals]}" \u2014 ` + (maxPositionals ? `"odla-ai ${taken}" takes no further arguments` : "this command takes no arguments")
+    );
   }
 }
 function requiredString(value2, name) {
@@ -1275,6 +1282,198 @@ function addOption(options, name, value2) {
   else options[name] = [String(current), String(value2)];
 }
 
+// src/surface.ts
+var PM_ACTIONS = {
+  list: {},
+  add: {},
+  create: {},
+  get: {},
+  set: {},
+  update: {},
+  status: {},
+  move: {},
+  done: {},
+  comment: {},
+  comments: {},
+  history: {},
+  link: {},
+  ref: {},
+  rm: {},
+  delete: {}
+};
+var PM_TASK_ACTIONS = {
+  ...PM_ACTIONS,
+  ready: {},
+  claim: {},
+  release: {}
+};
+var PM_ENTITIES = {
+  ...Object.fromEntries(
+    ["goal", "conformance", "decision", "bug"].map((entity) => [entity, PM_ACTIONS])
+  ),
+  task: PM_TASK_ACTIONS,
+  kanban: PM_TASK_ACTIONS
+};
+var COMMAND_SURFACE = {
+  agent: { jobs: {}, retry: {} },
+  ai: { models: {} },
+  admin: {
+    ai: {
+      show: {},
+      set: {},
+      credentials: {},
+      models: {},
+      usage: {},
+      audit: {},
+      credential: { set: {} }
+    },
+    spend: { show: {}, reset: {} }
+  },
+  app: {
+    archive: {},
+    restore: {},
+    export: {},
+    import: {},
+    rename: {},
+    "refresh-sandbox": {},
+    "go-live": {},
+    promote: {},
+    owners: { list: {}, add: {}, remove: {} }
+  },
+  auth: { login: {} },
+  brand: { design: { unpack: {} } },
+  bug: { create: {}, list: {}, report: {} },
+  calendar: { status: {}, calendars: {}, connect: {}, disconnect: {} },
+  capabilities: {},
+  code: {
+    connect: {},
+    grant: { request: {}, list: {}, approve: {}, revoke: {} },
+    repository: { show: {}, list: {}, bind: {} }
+  },
+  config: { diff: {}, plan: {}, apply: {} },
+  context: { show: {}, list: {}, save: {}, remove: {} },
+  credentials: { list: {}, revoke: {} },
+  device: { enroll: {}, list: {}, revoke: {} },
+  // `watch`, `read`, `reply`, and `resolve` take a topic id from there on.
+  discuss: {
+    groups: {},
+    list: {},
+    topics: {},
+    read: {},
+    post: {},
+    reply: {},
+    resolve: {},
+    who: {},
+    watch: {}
+  },
+  doctor: {},
+  help: {},
+  init: {},
+  monitor: { plan: {}, apply: {}, run: {}, status: {}, incidents: {}, report: {} },
+  o11y: { status: {} },
+  operations: { get: {}, wait: {} },
+  platform: {
+    status: {}
+  },
+  pm: {
+    ...PM_ENTITIES,
+    project: { list: {}, add: {}, create: {}, use: {} },
+    handoff: {},
+    next: {},
+    start: {},
+    watch: {}
+  },
+  provision: {},
+  runbook: {
+    ask: {},
+    search: {},
+    impact: {},
+    list: {},
+    get: {},
+    cat: {},
+    new: {},
+    edit: {},
+    comment: {},
+    import: {},
+    visibility: {},
+    publish: {},
+    archive: {},
+    history: {},
+    revert: {},
+    rm: {},
+    lint: {}
+  },
+  secrets: { push: {}, status: {}, set: {}, "set-clerk-key": {} },
+  security: {
+    plan: {},
+    sources: {},
+    run: {},
+    status: {},
+    report: {},
+    github: { connect: {}, disconnect: {} }
+  },
+  setup: {},
+  skill: { install: {} },
+  smoke: {},
+  version: {},
+  whoami: {}
+};
+function acceptedAfter(path) {
+  let node = COMMAND_SURFACE;
+  for (const word of path) {
+    node = node?.[word];
+    if (!node) return [];
+  }
+  return Object.keys(node).sort();
+}
+function validateInvocation(words2) {
+  let node = COMMAND_SURFACE;
+  const walked = [];
+  for (const word of words2) {
+    if (Object.keys(node).length === 0) return null;
+    const next = node[word];
+    if (!next) return { validPrefix: walked.join(" "), word, accepted: Object.keys(node).sort() };
+    walked.push(word);
+    node = next;
+  }
+  return null;
+}
+function describeProblem(problem) {
+  const where = problem.validPrefix ? `after "${problem.validPrefix}"` : "as a command";
+  if (!problem.accepted.length) return `"${problem.word}" is not accepted ${where}. Run "odla-ai help"`;
+  if (!problem.word) return `"odla-ai ${problem.validPrefix}" needs one of: ${problem.accepted.join(", ")}`;
+  return `"${problem.word}" is not accepted ${where} \u2014 try: ${problem.accepted.join(", ")}`;
+}
+function rejectWord(path, word, note) {
+  const sentence = describeProblem({
+    validPrefix: path.join(" "),
+    word: word ?? "",
+    accepted: acceptedAfter(path)
+  });
+  throw new Error(note ? `${sentence}. ${note}` : sentence);
+}
+function invocationPath(words2) {
+  let node = COMMAND_SURFACE;
+  const path = [];
+  for (const word of words2) {
+    const next = node[word];
+    if (!next) break;
+    path.push(word);
+    node = next;
+    if (Object.keys(node).length === 0) break;
+  }
+  return path;
+}
+function surfacePaths(node = COMMAND_SURFACE, prefix = []) {
+  const paths2 = [];
+  for (const [word, child] of Object.entries(node)) {
+    const path = [...prefix, word];
+    paths2.push(path);
+    paths2.push(...surfacePaths(child, path));
+  }
+  return paths2;
+}
+
 // src/admin-spend.ts
 async function call(ctx, method, scope) {
   const url = `${ctx.platformUrl.replace(/\/$/, "")}/registry/platform/spend?scope=${encodeURIComponent(scope)}`;
@@ -1324,9 +1523,7 @@ async function spendReset(ctx, scope) {
 async function adminSpend(parsed, ctx) {
   const action2 = parsed.positionals[2];
   const scope = parsed.positionals[3] ?? stringOpt(parsed.options.scope);
-  if (action2 !== "show" && action2 !== "reset") {
-    throw new Error('unknown spend command. Try "odla-ai admin spend show <scope>".');
-  }
+  if (action2 !== "show" && action2 !== "reset") rejectWord(["admin", "spend"], action2);
   if (!scope) {
     throw new Error(
       `"admin spend ${action2}" needs a scope, e.g. odla-ai admin spend ${action2} app:my-app:<incarnation>`
@@ -2125,6 +2322,11 @@ var SET_OPTIONS = [
 async function adminCommand(parsed, deps = {}) {
   const area = parsed.positionals[1];
   const action2 = parsed.positionals[2];
+  if (area !== "ai" && area !== "spend") rejectWord(["admin"], area);
+  if (!acceptedAfter(["admin", area]).includes(action2 ?? "")) rejectWord(["admin", area], action2);
+  if (action2 === "credential" && !acceptedAfter(["admin", "ai", "credential"]).includes(parsed.positionals[3] ?? "")) {
+    rejectWord(["admin", "ai", "credential"], parsed.positionals[3]);
+  }
   if (area === "spend") {
     assertArgs(parsed, JSON_OPTIONS, 4);
     const context2 = await resolveOperatorContext(parsed, { allowMissingConfig: true });
@@ -2150,14 +2352,11 @@ async function adminCommand(parsed, deps = {}) {
       out
     });
   }
-  const credentialSet = action2 === "credential" && parsed.positionals[3] === "set";
+  const credentialSet = action2 === "credential";
   const credentials = action2 === "credentials";
   const models = action2 === "models";
   const usage = action2 === "usage";
   const audit = action2 === "audit";
-  if (area !== "ai" || action2 !== "show" && action2 !== "set" && !credentialSet && !credentials && !models && !usage && !audit) {
-    throw new Error('unknown admin command. Try "odla-ai admin ai show".');
-  }
   const allowed = credentialSet ? [...CONTEXT_OPTIONS, "from-env", "stdin"] : action2 === "set" ? SET_OPTIONS : models ? [...JSON_OPTIONS, "provider"] : usage ? [...JSON_OPTIONS, "app-id", "env", "run-id", "limit"] : audit ? [...JSON_OPTIONS, "limit"] : JSON_OPTIONS;
   assertArgs(parsed, allowed, credentialSet ? 5 : action2 === "set" ? 4 : 3);
   const context = await resolveOperatorContext(parsed, { allowMissingConfig: true });
@@ -2371,9 +2570,7 @@ async function authCommand(parsed, deps = {}) {
     "json"
   ], 2);
   const action2 = parsed.positionals[1] ?? "login";
-  if (action2 !== "login") {
-    throw new Error(`unknown auth action "${action2}". Try "odla-ai auth login --app <id> --email <odla-account>".`);
-  }
+  if (action2 !== "login") rejectWord(["auth"], action2);
   const context = await resolveOperatorContext(parsed, {
     allowMissingConfig: true,
     requireApp: true
@@ -2446,9 +2643,7 @@ function bothTenants(cfg) {
 // src/agent-command.ts
 async function agentCommand(parsed, deps = {}) {
   const action2 = parsed.positionals[1];
-  if (action2 !== "jobs" && action2 !== "retry") {
-    throw new Error(`unknown agent action "${action2 ?? ""}". Try "odla-ai agent jobs --json".`);
-  }
+  if (action2 !== "jobs" && action2 !== "retry") rejectWord(["agent"], action2);
   assertArgs(parsed, ["config", "env", "state", "limit", "json", "token"], action2 === "jobs" ? 2 : 3);
   if (action2 === "retry" && (parsed.options.state !== void 0 || parsed.options.limit !== void 0)) {
     throw new Error('--state and --limit are supported only by "agent jobs"');
@@ -2619,9 +2814,7 @@ async function appOwnersCommand(parsed, dependencies = {}) {
     await (sub === "add" ? ownersAdd(email, options) : ownersRemove(email, options));
     return;
   }
-  throw new Error(
-    `unknown app owners subcommand "${sub}". Try "odla-ai app owners list", "odla-ai app owners add <email>", or "odla-ai app owners remove <email>".`
-  );
+  rejectWord(["app", "owners"], sub);
 }
 
 // src/app-rename.ts
@@ -2727,8 +2920,10 @@ async function appCommand(parsed, dependencies = {}) {
     return;
   }
   if (sub !== "archive" && sub !== "restore") {
-    throw new Error(
-      `unknown app subcommand "${sub ?? ""}". Try "odla-ai app archive --yes", "odla-ai app restore", "odla-ai app export", "odla-ai app import <file>", "odla-ai app refresh-sandbox", "odla-ai app go-live", "odla-ai app promote", "odla-ai app rename <name>", or "odla-ai app owners <list|add|remove>". (Permanent deletion has no CLI: it requires a signed-in owner in Studio.)`
+    rejectWord(
+      ["app"],
+      sub,
+      "Permanent deletion has no CLI: it requires a signed-in owner in Studio."
     );
   }
   assertArgs(parsed, ["config", "token", "email", "yes", "json"], 2);
@@ -2889,7 +3084,8 @@ async function brandCommand(parsed, deps) {
     await designUnpack(parsed, deps);
     return;
   }
-  throw new Error(USAGE);
+  if (subject !== "design") rejectWord(["brand"], subject);
+  rejectWord(["brand", "design"], action2, USAGE);
 }
 
 // src/calendar-errors.ts
@@ -5750,9 +5946,7 @@ async function secretsCommand(parsed, deps) {
     return;
   }
   if (sub !== "push") {
-    throw new Error(
-      `unknown secrets subcommand "${sub ?? ""}". Try "odla-ai secrets push --env dev", "odla-ai secrets status --env dev", "odla-ai secrets set <name> --env dev --stdin", or "odla-ai secrets set-clerk-key --env dev --stdin".`
-    );
+    rejectWord(["secrets"], sub);
   }
   assertArgs(parsed, ["config", "env", "dry-run", "yes"], 2);
   await secretsPush({
@@ -5765,7 +5959,7 @@ async function secretsCommand(parsed, deps) {
 async function projectCommand(command, parsed, deps) {
   if (command === "ai") {
     const sub = parsed.positionals[1];
-    if (sub !== "models") throw new Error(`unknown ai subcommand "${sub ?? ""}". Try "odla-ai ai models --env dev".`);
+    if (sub !== "models") rejectWord(["ai"], sub);
     assertArgs(parsed, ["config", "env", "provider", "json"], 2);
     await aiModels({
       configPath: stringOpt(parsed.options.config) ?? "odla.config.mjs",
@@ -5779,9 +5973,7 @@ async function projectCommand(command, parsed, deps) {
   }
   if (command === "config") {
     const sub = parsed.positionals[1];
-    if (sub !== "diff" && sub !== "plan" && sub !== "apply") {
-      throw new Error(`unknown config subcommand "${sub ?? ""}". Try "odla-ai config diff --json".`);
-    }
+    if (sub !== "diff" && sub !== "plan" && sub !== "apply") rejectWord(["config"], sub);
     assertArgs(
       parsed,
       sub === "apply" ? ["config", "plan", "idempotency-key", "token", "email", "open", "json"] : ["config", "token", "email", "open", "json"],
@@ -5809,7 +6001,7 @@ async function projectCommand(command, parsed, deps) {
   if (command === "operations") {
     const sub = parsed.positionals[1];
     if (sub !== "get" && sub !== "wait") {
-      throw new Error(`unknown operations subcommand "${sub ?? ""}". Try "odla-ai operations get <operation-id> --json".`);
+      rejectWord(["operations"], sub);
     }
     assertArgs(
       parsed,
@@ -5883,7 +6075,7 @@ async function projectCommand(command, parsed, deps) {
   }
   if (command === "skill") {
     const sub = parsed.positionals[1];
-    if (sub !== "install") throw new Error(`unknown skill subcommand "${sub ?? ""}". Try "odla-ai skill install".`);
+    if (sub !== "install") rejectWord(["skill"], sub);
     install(parsed, 2, deps);
     return true;
   }
@@ -10441,9 +10633,7 @@ function grantsUrl(cfg, suffix = "") {
 async function codeGrantCommand(parsed, deps = {}) {
   const action2 = parsed.positionals[2];
   if (!isAction(action2)) {
-    throw new Error(
-      `unknown code grant action "${action2 ?? ""}". Try "odla-ai code grant list --env dev".`
-    );
+    rejectWord(["code", "grant"], action2);
   }
   const decides = action2 === "approve" || action2 === "revoke";
   assertArgs(parsed, ["config", "env", "json", "token", "email", "open"], decides ? 4 : 3);
@@ -10563,9 +10753,7 @@ function repositoryUrl(cfg, suffix = "") {
 async function codeRepositoryCommand(parsed, deps = {}) {
   const action2 = parsed.positionals[2];
   if (!isAction2(action2)) {
-    throw new Error(
-      `unknown code repository action "${action2 ?? ""}". Try "odla-ai code repository show --env dev".`
-    );
+    rejectWord(["code", "repository"], action2);
   }
   assertArgs(parsed, ["config", "env", "repo", "json", "token", "email", "open"], 3);
   const cfg = await loadProjectConfig(stringOpt(parsed.options.config) ?? "odla.config.mjs");
@@ -10640,9 +10828,7 @@ async function codeCommand(parsed, dependencies) {
     });
   }
   if (sub !== "connect") {
-    throw new Error(
-      `unknown code subcommand "${sub ?? ""}". Try "odla-ai code connect --env dev" or "odla-ai code grant list --env dev".`
-    );
+    rejectWord(["code"], sub);
   }
   assertArgs(parsed, [
     "config",
@@ -10779,9 +10965,7 @@ async function contextCommand(parsed, deps = {}) {
     return;
   }
   if (action2 !== "show") {
-    throw new Error(
-      `unknown context action "${action2 ?? ""}". Try show|list|save|remove.`
-    );
+    rejectWord(["context"], action2);
   }
   const context = await resolveOperatorContext(parsed, {
     allowMissingConfig: true,
@@ -10837,9 +11021,7 @@ async function responseError(response2) {
 }
 async function credentialCommand(parsed, deps = {}) {
   const action2 = parsed.positionals[1] ?? "list";
-  if (action2 !== "list" && action2 !== "revoke") {
-    throw new Error(`unknown credentials action "${action2}". Try "odla-ai credentials list".`);
-  }
+  if (action2 !== "list" && action2 !== "revoke") rejectWord(["credentials"], action2);
   assertArgs(parsed, ["config", "env", "all", "json", "token", "email", "open"], action2 === "revoke" ? 3 : 2);
   const cfg = await loadProjectConfig(stringOpt(parsed.options.config) ?? "odla.config.mjs");
   const doFetch = deps.fetch ?? fetch;
@@ -11248,9 +11430,17 @@ Safety:
   grant, run it once with --request-grant. That flag ignores ODLA_DEV_TOKEN and
   the local cache, prints and opens a fresh exact-project owner-review URL, then
   continues provisioning with the approved replacement credential.
-  Before a non-dry-run provision, the executable checks npm's current CLI
-  release. A confirmed stale client stops with a safe npx rerun command; a
-  workspace-linked client also identifies the worktree that must be updated.
+  Every command says so on STDERR when this CLI is older than the one npm
+  serves, naming the repair for how this executable was launched \u2014 rebuild the
+  worktree, npm i the dependency, or npx the scoped package. The answer is read
+  from a cache under ~/.odla refreshed in the background at most every three
+  hours, so no invocation waits on the registry and stdout is never touched.
+  Set ODLA_CLI_UPDATE_CHECK=0 to switch it off.
+  Before a non-dry-run provision, the executable additionally checks npm LIVE
+  rather than trusting that cache: a security-sensitive grant shape must not
+  ride on a three-hour-old answer. A confirmed stale client stops with a safe
+  npx rerun command; a workspace-linked client also identifies the worktree
+  that must be updated.
   Run Code from a GitHub checkout already connected to an app in Studio; an
   odla.config.mjs may select the app explicitly but is not required. With an
   enrolled code.session device, the Studio repository selection authorizes the
@@ -11841,7 +12031,7 @@ async function discussCommand(parsed, deps = {}) {
   assertArgs(parsed, ALLOWED, 3);
   const action2 = parsed.positionals[1];
   const id2 = parsed.positionals[2];
-  if (!action2) throw new Error('"discuss" needs an action. Run "odla-ai help".');
+  if (!acceptedAfter(["discuss"]).includes(action2 ?? "")) rejectWord(["discuss"], action2);
   const ctx = await buildContext(parsed, deps);
   switch (action2) {
     case "groups":
@@ -11865,7 +12055,7 @@ async function discussCommand(parsed, deps = {}) {
       return;
     }
     default:
-      throw new Error(`unknown discuss action "${action2}". Run "odla-ai help".`);
+      rejectWord(["discuss"], action2);
   }
 }
 
@@ -12775,7 +12965,7 @@ async function pmCommand(parsed, deps = {}) {
       assertArgs(parsed, COMMON_OPTIONS, 4);
       return pmProjectUse(await buildContext2(parsed, deps), requireId2(parsed.positionals[3], action3));
     }
-    throw new Error(`unknown pm project action "${action3}". Try list|add|use.`);
+    rejectWord(["pm", "project"], action3);
   }
   if (word === "next") {
     assertArgs(parsed, [...COMMON_OPTIONS, "app", "project", "verbose"], 2);
@@ -12806,10 +12996,10 @@ async function pmCommand(parsed, deps = {}) {
     return pmHandoff(await buildContext2(parsed, deps), parsed);
   }
   const entity = ALIASES[word];
-  if (!entity) throw new Error(`unknown pm entity "${word}". Try "odla-ai pm start" to claim Ready work, or "odla-ai pm bug list" (goal|task|decision|bug).`);
+  if (!entity) rejectWord(["pm"], word);
   const requestedAction = parsed.positionals[2] ?? "list";
   const action2 = canonicalAction(requestedAction);
-  if (!action2) throw new Error(`unknown pm action "${requestedAction}". Try list|add|get|set|done|link|ref|comment|comments|history|rm.`);
+  if (!action2) rejectWord(["pm", word], requestedAction);
   assertArgs(parsed, allowedOptions(entity, action2), 4);
   if ((action2 === "ready" || action2 === "claim" || action2 === "release") && entity !== "task") {
     throw new Error(`pm ${action2} is only valid for tasks`);
@@ -12895,12 +13085,7 @@ async function platformCommand(parsed, deps = {}) {
   if (action2 === "status") {
     return platformStatus(parsed, deps);
   }
-  throw new Error(
-    `unknown platform action "${[
-      action2,
-      parsed.positionals[2]
-    ].filter(Boolean).join(" ")}". Try "odla-ai platform status --json".`
-  );
+  rejectWord(["platform"], action2);
 }
 async function platformStatus(parsed, deps) {
   assertArgs(
@@ -13237,9 +13422,7 @@ async function o11yCommand(parsed, deps = {}) {
   );
   const action2 = parsed.positionals[1];
   if (action2 !== "status") {
-    throw new Error(
-      `unknown o11y action "${action2 ?? ""}". Try "odla-ai o11y status --json".`
-    );
+    rejectWord(["o11y"], action2);
   }
   const minutes = statusMinutes(
     numberOpt(parsed.options.minutes, "--minutes") ?? 60
@@ -13492,9 +13675,7 @@ var OPTIONS = [
 async function monitorCommand(parsed, deps = {}) {
   assertArgs(parsed, OPTIONS, 3);
   const action2 = parsed.positionals[1] ?? "status";
-  if (!["plan", "apply", "run", "status", "incidents", "report"].includes(action2)) {
-    throw new Error(`unknown monitor action "${action2}". Try "odla-ai monitor status --json".`);
-  }
+  if (!acceptedAfter(["monitor"]).includes(action2)) rejectWord(["monitor"], action2);
   const context = await resolveOperatorContext(parsed, {
     allowMissingConfig: action2 !== "plan" && action2 !== "apply",
     requireApp: true
@@ -14124,187 +14305,6 @@ async function provision(options) {
 // src/record.ts
 var import_node_fs18 = require("fs");
 var import_node_process18 = __toESM(require("process"), 1);
-
-// src/surface.ts
-var PM_ACTIONS = {
-  list: {},
-  add: {},
-  create: {},
-  get: {},
-  set: {},
-  update: {},
-  status: {},
-  move: {},
-  done: {},
-  comment: {},
-  comments: {},
-  ref: {},
-  rm: {},
-  delete: {}
-};
-var PM_TASK_ACTIONS = {
-  ...PM_ACTIONS,
-  ready: {},
-  claim: {},
-  release: {}
-};
-var PM_ENTITIES = {
-  ...Object.fromEntries(
-    ["goal", "conformance", "decision", "bug"].map((entity) => [entity, PM_ACTIONS])
-  ),
-  task: PM_TASK_ACTIONS,
-  kanban: PM_TASK_ACTIONS
-};
-var COMMAND_SURFACE = {
-  agent: { jobs: {}, retry: {} },
-  ai: { models: {} },
-  admin: {
-    ai: {
-      show: {},
-      set: {},
-      credentials: {},
-      models: {},
-      usage: {},
-      audit: {},
-      credential: { set: {} }
-    }
-  },
-  app: {
-    archive: {},
-    restore: {},
-    export: {},
-    import: {},
-    rename: {},
-    "refresh-sandbox": {},
-    "go-live": {},
-    promote: {},
-    owners: { list: {}, add: {}, remove: {} }
-  },
-  auth: { login: {} },
-  brand: { design: { unpack: {} } },
-  bug: { create: {}, list: {}, report: {} },
-  calendar: { status: {}, calendars: {}, connect: {}, disconnect: {} },
-  capabilities: {},
-  code: {
-    connect: {},
-    grant: { request: {}, list: {}, approve: {}, revoke: {} },
-    repository: { show: {}, list: {}, bind: {} }
-  },
-  config: { diff: {}, plan: {}, apply: {} },
-  context: { show: {}, list: {}, save: {}, remove: {} },
-  credentials: { list: {}, revoke: {} },
-  device: { enroll: {}, list: {}, revoke: {} },
-  // `watch`, `read`, `reply`, and `resolve` take a topic id from there on.
-  discuss: {
-    groups: {},
-    list: {},
-    topics: {},
-    read: {},
-    post: {},
-    reply: {},
-    resolve: {},
-    who: {},
-    watch: {}
-  },
-  doctor: {},
-  help: {},
-  init: {},
-  monitor: { plan: {}, apply: {}, run: {}, status: {}, incidents: {}, report: {} },
-  o11y: { status: {} },
-  operations: { get: {}, wait: {} },
-  platform: {
-    status: {}
-  },
-  pm: {
-    ...PM_ENTITIES,
-    project: { list: {}, add: {}, create: {}, use: {} },
-    handoff: {},
-    next: {},
-    start: {},
-    watch: {}
-  },
-  provision: {},
-  runbook: {
-    ask: {},
-    search: {},
-    impact: {},
-    list: {},
-    get: {},
-    cat: {},
-    new: {},
-    edit: {},
-    comment: {},
-    import: {},
-    visibility: {},
-    publish: {},
-    archive: {},
-    history: {},
-    revert: {},
-    rm: {},
-    lint: {}
-  },
-  secrets: { push: {}, status: {}, set: {}, "set-clerk-key": {} },
-  security: {
-    plan: {},
-    sources: {},
-    run: {},
-    status: {},
-    report: {},
-    github: { connect: {}, disconnect: {} }
-  },
-  setup: {},
-  skill: { install: {} },
-  smoke: {},
-  version: {},
-  whoami: {}
-};
-function acceptedAfter(path) {
-  let node = COMMAND_SURFACE;
-  for (const word of path) {
-    node = node?.[word];
-    if (!node) return [];
-  }
-  return Object.keys(node).sort();
-}
-function validateInvocation(words2) {
-  let node = COMMAND_SURFACE;
-  const walked = [];
-  for (const word of words2) {
-    if (Object.keys(node).length === 0) return null;
-    const next = node[word];
-    if (!next) return { validPrefix: walked.join(" "), word, accepted: Object.keys(node).sort() };
-    walked.push(word);
-    node = next;
-  }
-  return null;
-}
-function describeProblem(problem) {
-  const where = problem.validPrefix ? `after "${problem.validPrefix}"` : "as a command";
-  return `"${problem.word}" is not accepted ${where} \u2014 try: ${problem.accepted.join(", ")}`;
-}
-function invocationPath(words2) {
-  let node = COMMAND_SURFACE;
-  const path = [];
-  for (const word of words2) {
-    const next = node[word];
-    if (!next) break;
-    path.push(word);
-    node = next;
-    if (Object.keys(node).length === 0) break;
-  }
-  return path;
-}
-function surfacePaths(node = COMMAND_SURFACE, prefix = []) {
-  const paths2 = [];
-  for (const [word, child] of Object.entries(node)) {
-    const path = [...prefix, word];
-    paths2.push(path);
-    paths2.push(...surfacePaths(child, path));
-  }
-  return paths2;
-}
-
-// src/record.ts
 function recordInvocation(parsed) {
   const file = import_node_process18.default.env.ODLA_CLI_RECORD;
   if (!file) return;
@@ -14393,6 +14393,7 @@ async function deviceCommand(parsed, deps) {
     "wait"
   ], 3);
   const action2 = parsed.positionals[1] ?? "";
+  if (!acceptedAfter(["device"]).includes(action2)) rejectWord(["device"], action2);
   const out = deps.stdout ?? console;
   const doFetch = deps.fetch ?? fetch;
   const cfg = await loadProjectConfig(stringOpt(parsed.options.config));
@@ -14400,7 +14401,7 @@ async function deviceCommand(parsed, deps) {
   if (action2 === "enroll") return enroll(parsed, deps, cfg, doFetch, out, json);
   if (action2 === "list") return list2(parsed, deps, cfg, doFetch, out, json);
   if (action2 === "revoke") return revoke(parsed, deps, cfg, doFetch, out, json);
-  throw new Error('odla-ai device expects "enroll", "list", or "revoke"');
+  rejectWord(["device"], action2);
 }
 async function enroll(parsed, deps, cfg, doFetch, out, json) {
   const name = stringOpt(parsed.options.name) ?? defaultDeviceName();
@@ -15347,6 +15348,7 @@ async function buildContext3(parsed, deps, action2) {
 async function runbookCommand(parsed, deps = {}) {
   const action2 = parsed.positionals[1] ?? "list";
   assertArgs(parsed, ALLOWED2, action2 === "ask" || action2 === "search" ? 64 : 4);
+  if (!acceptedAfter(["runbook"]).includes(action2)) rejectWord(["runbook"], action2);
   const ctx = await buildContext3(parsed, deps, action2);
   const slug = parsed.positionals[2];
   switch (action2) {
@@ -15436,7 +15438,7 @@ async function runbookCommand(parsed, deps = {}) {
     case "rm":
       return runbookRemove(ctx, requireSlug(slug, "rm"));
     default:
-      throw new Error(`unknown runbook action "${action2}". Try ${acceptedAfter(["runbook"]).join(", ")}.`);
+      rejectWord(["runbook"], action2);
   }
 }
 
@@ -16050,9 +16052,7 @@ async function securityCommand(parsed, dependencies) {
     else printHostedReport(context.stdout, report5);
     return;
   }
-  if (sub !== "run") {
-    throw new Error('unknown security command. Try "odla-ai security plan", "security sources", or "security run".');
-  }
+  if (sub !== "run") rejectWord(["security"], sub);
   const sourceId = stringOpt(parsed.options.source);
   if (sourceId) await runSourceSecurityCommand(parsed, dependencies, sourceId);
   else await runLocalSecurityCommand(parsed, dependencies);
@@ -16069,9 +16069,7 @@ async function githubSecurityCommand(parsed, dependencies) {
       stringOpt(parsed.options.env)
     );
   }
-  if (action2 !== "connect") {
-    throw new Error('unknown security github command. Try "odla-ai security github connect".');
-  }
+  if (action2 !== "connect") rejectWord(["security", "github"], action2);
   assertArgs(parsed, ["config", "env", "platform", "repo", "email", "open"], 3);
   await requireStudioHuman(
     stringOpt(parsed.options.config) ?? "odla.config.mjs",
@@ -16118,6 +16116,87 @@ async function securityStatus(parsed, dependencies) {
   }
 }
 
+// src/update-notice.ts
+var import_node_child_process8 = require("child_process");
+var import_node_fs24 = require("fs");
+var import_node_path23 = require("path");
+var import_node_process21 = __toESM(require("process"), 1);
+var REGISTRY_URL = "https://registry.npmjs.org/@odla-ai%2fcli/latest";
+var INTERVAL_MS = 3 * 60 * 60 * 1e3;
+var VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+var refreshScheduled = false;
+function updateCacheFile(env) {
+  return odlaHomePath(["cli-update.json"], env);
+}
+function readUpdateCache(path) {
+  try {
+    const parsed = JSON.parse((0, import_node_fs24.readFileSync)(path, "utf8"));
+    if (typeof parsed.latest !== "string" || !VERSION.test(parsed.latest)) return null;
+    if (typeof parsed.checkedAt !== "number") return null;
+    return { latest: parsed.latest, checkedAt: parsed.checkedAt };
+  } catch {
+    return null;
+  }
+}
+function updateNotice(options = {}) {
+  const env = options.env ?? import_node_process21.default.env;
+  if (env.ODLA_CLI_UPDATE_CHECK === "0") return null;
+  const current = options.currentVersion ?? cliVersion();
+  if (!VERSION.test(current)) return null;
+  const path = updateCacheFile(env);
+  const cache2 = readUpdateCache(path);
+  const now = options.now ?? Date.now();
+  if ((!cache2 || now - cache2.checkedAt > INTERVAL_MS) && !refreshScheduled) {
+    refreshScheduled = true;
+    (options.refresh ?? spawnRefresh)(path, env.ODLA_CLI_REGISTRY_URL ?? REGISTRY_URL);
+  }
+  if (!cache2 || compareVersions(current, cache2.latest) >= 0) return null;
+  return renderNotice(current, cache2.latest, options.entryPath ?? import_node_process21.default.argv[1]);
+}
+function renderNotice(current, latest, entryPath) {
+  const resolved = resolvedEntryPath(entryPath);
+  const behindMajor = Number(latest.split(".")[0]) > Number(current.split(".")[0]);
+  const repair = isWorkspaceCli(resolved) ? `this is the workspace build at ${resolved} \u2014 rebase that worktree and rebuild it` : resolved.includes("/_npx/") ? `run npx --yes @odla-ai/cli@${latest} <command>` : `run npm i @odla-ai/cli@${latest}`;
+  const severity = behindMajor ? "a MAJOR version behind, so commands and flags this version has may no longer exist" : "behind";
+  return `odla-ai: ${current} is ${severity}; npm serves ${latest}. To update, ${repair}.`;
+}
+function spawnRefresh(cachePath, registryUrl) {
+  const script = `
+    const {mkdirSync,writeFileSync}=require("node:fs");
+    const {dirname}=require("node:path");
+    const [path,url]=process.argv.slice(1);
+    const done=setTimeout(()=>process.exit(0),5000); done.unref();
+    fetch(url,{headers:{accept:"application/vnd.npm.install-v1+json"}})
+      .then(r=>r.ok?r.json():null)
+      .then(b=>{
+        const v=b&&b.version;
+        if (typeof v!=="string"||!/^\\d+\\.\\d+\\.\\d+/.test(v)) return;
+        mkdirSync(dirname(path),{recursive:true});
+        writeFileSync(path,JSON.stringify({latest:v,checkedAt:Date.now()}));
+      })
+      .catch(()=>{});
+  `;
+  try {
+    (0, import_node_child_process8.spawn)(import_node_process21.default.execPath, ["-e", script, cachePath, registryUrl], {
+      detached: true,
+      stdio: "ignore"
+    }).unref();
+  } catch {
+  }
+}
+function resolvedEntryPath(entryPath) {
+  if (!entryPath) return "unknown executable";
+  try {
+    return (0, import_node_fs24.realpathSync)(entryPath);
+  } catch {
+    return entryPath;
+  }
+}
+function isWorkspaceCli(entryPath) {
+  const normalized = entryPath.replaceAll("\\", "/");
+  return /\/packages\/cli\/(dist|bin)\//.test(normalized) && !normalized.includes("/node_modules/");
+}
+
 // src/exit-code.ts
 function exitCodeFor(err) {
   const code = err?.code;
@@ -16145,6 +16224,11 @@ async function runCli(argv = process.argv.slice(2), dependencies = {}) {
     throw error;
   } finally {
     renderAdvisories(out, advisories);
+    try {
+      const behind = updateNotice();
+      if (behind) out.error(behind);
+    } catch {
+    }
   }
 }
 async function dispatchCli(argv, dependencies) {
@@ -16225,6 +16309,7 @@ async function dispatchCli(argv, dependencies) {
   }
   if (command === "bug") {
     const action2 = parsed.positionals[1] ?? "list";
+    if (!acceptedAfter(["bug"]).includes(action2)) rejectWord(["bug"], action2);
     const canonical2 = action2 === "report" || action2 === "create" ? "add" : action2;
     await pmCommand({
       ...parsed,
@@ -16253,7 +16338,7 @@ async function dispatchCli(argv, dependencies) {
     return;
   }
   if (await projectCommand(command, parsed, runtime)) return;
-  throw new Error(`unknown command "${command}". Run "odla-ai help".`);
+  rejectWord([], command);
 }
 async function provisionCommand(parsed, dependencies) {
   assertArgs(parsed, [
@@ -16297,7 +16382,7 @@ async function provisionCommand(parsed, dependencies) {
 async function calendarCommand(parsed, dependencies) {
   const sub = parsed.positionals[1];
   if (sub !== "status" && sub !== "calendars" && sub !== "connect" && sub !== "disconnect") {
-    throw new Error(`unknown calendar subcommand "${sub ?? ""}". Try "odla-ai calendar status --env dev".`);
+    rejectWord(["calendar"], sub);
   }
   assertArgs(parsed, ["config", "env", "json", "token", "email", "open", "yes"], 2);
   if (sub !== "status" && sub !== "calendars" && parsed.options.json !== void 0) throw new Error(`--json is supported only by calendar status/calendars`);