@odla-ai/cli 0.43.1 → 0.45.0

package/dist/bin.cjs

@@ -99,17 +99,173 @@ var init_runbook_requires = __esm({
   }
 });
 
+// src/odla-home.ts
+function odlaHome(env = import_node_process.default.env) {
+  if (env.VITEST && !env.ODLA_HOME) {
+    throw new Error(
+      "ODLA_HOME must be set under test \u2014 resolving the real ~/.odla would write to the developer's machine"
+    );
+  }
+  return env.ODLA_HOME ?? (0, import_node_path.join)(env.HOME ?? (0, import_node_os.homedir)(), ".odla");
+}
+function odlaHomePath(segments, env = import_node_process.default.env) {
+  return (0, import_node_path.join)(odlaHome(env), ...segments);
+}
+function identityFile(env) {
+  return odlaHomePath(["identity.json"], env);
+}
+function deviceSessionFile(env) {
+  return odlaHomePath(["session.json"], env);
+}
+function appTokenFile(appId, env) {
+  return odlaHomePath(["apps", safeSegment(appId), "dev-token.json"], env);
+}
+function appCredentialsFile(appId, env) {
+  return odlaHomePath(["apps", safeSegment(appId), "credentials.json"], env);
+}
+function scopedTokenFile(env) {
+  return odlaHomePath(["admin-token.local.json"], env);
+}
+function pmContextFile(env) {
+  return odlaHomePath(["pm-context.json"], env);
+}
+function adoptRepoLocalCache(legacyPath, machinePath, out) {
+  if (!(0, import_node_fs.existsSync)(legacyPath) || legacyPath === machinePath) return false;
+  const superseded2 = (0, import_node_fs.existsSync)(machinePath);
+  if (!superseded2) {
+    (0, import_node_fs.mkdirSync)((0, import_node_path.dirname)(machinePath), { recursive: true });
+    (0, import_node_fs.copyFileSync)(legacyPath, machinePath);
+    (0, import_node_fs.chmodSync)(machinePath, 384);
+  }
+  (0, import_node_fs.rmSync)(legacyPath, { force: true });
+  out?.error(
+    superseded2 ? `auth: removed superseded ${legacyPath}; this machine's credentials live in ${odlaHome()}` : `auth: moved ${legacyPath} into ${machinePath}; credentials are per machine now, not per worktree`
+  );
+  return true;
+}
+function safeSegment(value2) {
+  const clean4 = value2.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/^-+|-+$/g, "");
+  if (!clean4) throw new Error(`"${value2}" is not a usable app id`);
+  return clean4;
+}
+var import_node_fs, import_node_os, import_node_path, import_node_process;
+var init_odla_home = __esm({
+  "src/odla-home.ts"() {
+    "use strict";
+    init_cjs_shims();
+    import_node_fs = require("fs");
+    import_node_os = require("os");
+    import_node_path = require("path");
+    import_node_process = __toESM(require("process"), 1);
+  }
+});
+
 // src/version.ts
 function cliVersion() {
-  const pkg = JSON.parse((0, import_node_fs.readFileSync)(new URL("../package.json", importMetaUrl), "utf8"));
+  const pkg = JSON.parse((0, import_node_fs2.readFileSync)(new URL("../package.json", importMetaUrl), "utf8"));
   return pkg.version ?? "unknown";
 }
-var import_node_fs;
+var import_node_fs2;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
     init_cjs_shims();
-    import_node_fs = require("fs");
+    import_node_fs2 = require("fs");
+  }
+});
+
+// src/update-notice.ts
+function updateCacheFile(env) {
+  return odlaHomePath(["cli-update.json"], env);
+}
+function readUpdateCache(path) {
+  try {
+    const parsed = JSON.parse((0, import_node_fs3.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 writeUpdateCache(path, cache2) {
+  (0, import_node_fs3.mkdirSync)((0, import_node_path2.dirname)(path), { recursive: true });
+  (0, import_node_fs3.writeFileSync)(path, JSON.stringify(cache2));
+}
+function updateNotice(options = {}) {
+  const env = options.env ?? import_node_process2.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_process2.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_process.spawn)(import_node_process2.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_fs3.realpathSync)(entryPath);
+  } catch {
+    return entryPath;
+  }
+}
+function isWorkspaceCli(entryPath) {
+  const normalized = entryPath.replaceAll("\\", "/");
+  return /\/packages\/cli\/(dist|bin)\//.test(normalized) && !normalized.includes("/node_modules/");
+}
+var import_node_child_process, import_node_fs3, import_node_path2, import_node_process2, REGISTRY_URL, INTERVAL_MS, VERSION, refreshScheduled;
+var init_update_notice = __esm({
+  "src/update-notice.ts"() {
+    "use strict";
+    init_cjs_shims();
+    import_node_child_process = require("child_process");
+    import_node_fs3 = require("fs");
+    import_node_path2 = require("path");
+    import_node_process2 = __toESM(require("process"), 1);
+    init_odla_home();
+    init_runbook_requires();
+    init_version();
+    REGISTRY_URL = "https://registry.npmjs.org/@odla-ai%2fcli/latest";
+    INTERVAL_MS = 3 * 60 * 60 * 1e3;
+    VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+    refreshScheduled = false;
   }
 });
 
@@ -232,8 +388,8 @@ var init_approval_prompt = __esm({
 
 // src/open.ts
 async function openUrl(url, options = {}) {
-  const command = openerFor(options.platform ?? import_node_process.default.platform);
-  const doSpawn = options.spawnImpl ?? import_node_child_process.spawn;
+  const command = openerFor(options.platform ?? import_node_process3.default.platform);
+  const doSpawn = options.spawnImpl ?? import_node_child_process2.spawn;
   await new Promise((resolve15, reject) => {
     const child = doSpawn(command.cmd, [...command.args, url], {
       stdio: "ignore",
@@ -251,13 +407,13 @@ function openerFor(platform) {
   if (platform === "win32") return { cmd: "cmd", args: ["/c", "start", ""] };
   return { cmd: "xdg-open", args: [] };
 }
-var import_node_child_process, import_node_process;
+var import_node_child_process2, import_node_process3;
 var init_open = __esm({
   "src/open.ts"() {
     "use strict";
     init_cjs_shims();
-    import_node_child_process = require("child_process");
-    import_node_process = __toESM(require("process"), 1);
+    import_node_child_process2 = require("child_process");
+    import_node_process3 = __toESM(require("process"), 1);
   }
 });
 
@@ -265,7 +421,7 @@ var init_open = __esm({
 function approvalBrowser(options, host = {}) {
   if (options.open === false) return { open: false, reason: "disabled by --no-open" };
   if (options.open === true) return { open: true, mode: "forced" };
-  const env = host.env ?? import_node_process2.default.env;
+  const env = host.env ?? import_node_process4.default.env;
   if (env.VITEST || env.NODE_ENV === "test") {
     return { open: false, reason: "test environment" };
   }
@@ -295,12 +451,12 @@ function handshakeUrl(platformUrl, userCode) {
   url.searchParams.set("code", userCode);
   return url.toString();
 }
-var import_node_process2;
+var import_node_process4;
 var init_handshake_approval = __esm({
   "src/handshake-approval.ts"() {
     "use strict";
     init_cjs_shims();
-    import_node_process2 = __toESM(require("process"), 1);
+    import_node_process4 = __toESM(require("process"), 1);
     init_approval_prompt();
     init_open();
   }
@@ -308,10 +464,10 @@ var init_handshake_approval = __esm({
 
 // src/handshake-state.ts
 function handshakeFile(cfg) {
-  return (0, import_node_path2.join)((0, import_node_path2.dirname)(cfg.local.tokenFile), "handshake.local.json");
+  return (0, import_node_path4.join)((0, import_node_path4.dirname)(cfg.local.tokenFile), "handshake.local.json");
 }
 function clearPendingHandshake(path) {
-  (0, import_node_fs4.rmSync)(path, { force: true });
+  (0, import_node_fs5.rmSync)(path, { force: true });
 }
 function minutesLeft(expiresAt) {
   return Math.max(1, Math.round((expiresAt - Date.now()) / 6e4));
@@ -331,31 +487,31 @@ function approvalReminder(out, pending, periodMs = 3e4) {
   timer.unref?.();
   return () => clearInterval(timer);
 }
-function handshakeWaitMs(waitSeconds, interactive = import_node_process3.default.stdout.isTTY === true) {
+function handshakeWaitMs(waitSeconds, interactive = import_node_process5.default.stdout.isTTY === true) {
   if (waitSeconds !== void 0) return waitSeconds * 1e3;
   return interactive ? void 0 : 9e4;
 }
-var import_node_fs4, import_node_path2, import_node_process3;
+var import_node_fs5, import_node_path4, import_node_process5;
 var init_handshake_state = __esm({
   "src/handshake-state.ts"() {
     "use strict";
     init_cjs_shims();
-    import_node_fs4 = require("fs");
-    import_node_path2 = require("path");
-    import_node_process3 = __toESM(require("process"), 1);
+    import_node_fs5 = require("fs");
+    import_node_path4 = require("path");
+    import_node_process5 = __toESM(require("process"), 1);
     init_approval_prompt();
   }
 });
 
 // src/device-session.ts
-function deviceCredentialPath(env = import_node_process4.default.env) {
-  return env.ODLA_DEVICE_CREDENTIAL ?? (0, import_node_path3.join)(env.HOME ?? (0, import_node_os.homedir)(), ".odla", "device.json");
+function deviceCredentialPath(env = import_node_process6.default.env) {
+  return env.ODLA_DEVICE_CREDENTIAL ?? (0, import_node_path5.join)(env.HOME ?? (0, import_node_os2.homedir)(), ".odla", "device.json");
 }
-function readDeviceCredential(platform, env = import_node_process4.default.env) {
+function readDeviceCredential(platform, env = import_node_process6.default.env) {
   const path = deviceCredentialPath(env);
-  if (!(0, import_node_fs5.existsSync)(path)) return null;
+  if (!(0, import_node_fs6.existsSync)(path)) return null;
   try {
-    const parsed = JSON.parse((0, import_node_fs5.readFileSync)(path, "utf8"));
+    const parsed = JSON.parse((0, import_node_fs6.readFileSync)(path, "utf8"));
     if (typeof parsed.token !== "string" || !parsed.token.startsWith("odla_device_")) return null;
     if (parsed.platform !== platform) return null;
     return { ...parsed, token: parsed.token, platform: parsed.platform };
@@ -389,76 +545,15 @@ async function mintDeviceSession(platformUrl, credential2, doFetch) {
     ...Array.isArray(body.scopes) ? { scopes: body.scopes } : {}
   };
 }
-var import_node_fs5, import_node_os, import_node_path3, import_node_process4;
+var import_node_fs6, import_node_os2, import_node_path5, import_node_process6;
 var init_device_session = __esm({
   "src/device-session.ts"() {
-    "use strict";
-    init_cjs_shims();
-    import_node_fs5 = require("fs");
-    import_node_os = require("os");
-    import_node_path3 = require("path");
-    import_node_process4 = __toESM(require("process"), 1);
-  }
-});
-
-// src/odla-home.ts
-function odlaHome(env = import_node_process5.default.env) {
-  if (env.VITEST && !env.ODLA_HOME) {
-    throw new Error(
-      "ODLA_HOME must be set under test \u2014 resolving the real ~/.odla would write to the developer's machine"
-    );
-  }
-  return env.ODLA_HOME ?? (0, import_node_path4.join)(env.HOME ?? (0, import_node_os2.homedir)(), ".odla");
-}
-function odlaHomePath(segments, env = import_node_process5.default.env) {
-  return (0, import_node_path4.join)(odlaHome(env), ...segments);
-}
-function identityFile(env) {
-  return odlaHomePath(["identity.json"], env);
-}
-function deviceSessionFile(env) {
-  return odlaHomePath(["session.json"], env);
-}
-function appTokenFile(appId, env) {
-  return odlaHomePath(["apps", safeSegment(appId), "dev-token.json"], env);
-}
-function appCredentialsFile(appId, env) {
-  return odlaHomePath(["apps", safeSegment(appId), "credentials.json"], env);
-}
-function scopedTokenFile(env) {
-  return odlaHomePath(["admin-token.local.json"], env);
-}
-function pmContextFile(env) {
-  return odlaHomePath(["pm-context.json"], env);
-}
-function adoptRepoLocalCache(legacyPath, machinePath, out) {
-  if (!(0, import_node_fs6.existsSync)(legacyPath) || legacyPath === machinePath) return false;
-  const superseded2 = (0, import_node_fs6.existsSync)(machinePath);
-  if (!superseded2) {
-    (0, import_node_fs6.mkdirSync)((0, import_node_path4.dirname)(machinePath), { recursive: true });
-    (0, import_node_fs6.copyFileSync)(legacyPath, machinePath);
-    (0, import_node_fs6.chmodSync)(machinePath, 384);
-  }
-  (0, import_node_fs6.rmSync)(legacyPath, { force: true });
-  out?.error(
-    superseded2 ? `auth: removed superseded ${legacyPath}; this machine's credentials live in ${odlaHome()}` : `auth: moved ${legacyPath} into ${machinePath}; credentials are per machine now, not per worktree`
-  );
-  return true;
-}
-function safeSegment(value2) {
-  const clean4 = value2.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/^-+|-+$/g, "");
-  if (!clean4) throw new Error(`"${value2}" is not a usable app id`);
-  return clean4;
-}
-var import_node_fs6, import_node_os2, import_node_path4, import_node_process5;
-var init_odla_home = __esm({
-  "src/odla-home.ts"() {
     "use strict";
     init_cjs_shims();
     import_node_fs6 = require("fs");
     import_node_os2 = require("os");
-    import_node_path4 = require("path");
-    import_node_process5 = __toESM(require("process"), 1);
+    import_node_path5 = require("path");
+    import_node_process6 = __toESM(require("process"), 1);
   }
 });
 
@@ -508,7 +603,7 @@ function mergeCredential(current, update) {
   return next;
 }
 function ensureGitignore(rootDir, localPaths = []) {
-  const path = (0, import_node_path5.resolve)(rootDir, ".gitignore");
+  const path = (0, import_node_path6.resolve)(rootDir, ".gitignore");
   const existing = (0, import_node_fs7.existsSync)(path) ? (0, import_node_fs7.readFileSync)(path, "utf8") : "";
   const configured = localPaths.map((localPath) => gitignoreEntry(rootDir, localPath)).filter((line2) => !!line2);
   const wanted = [.../* @__PURE__ */ new Set([...GITIGNORE_LINES, ...configured])];
@@ -529,7 +624,7 @@ function o11yDevVars(cfg) {
 function resolveWriteDevVarsTarget(cfg, requested) {
   if (!requested) return null;
   if (requested === true) return cfg.local.devVarsFile;
-  return (0, import_node_path5.resolve)((0, import_node_path5.dirname)(cfg.configPath), requested);
+  return (0, import_node_path6.resolve)((0, import_node_path6.dirname)(cfg.configPath), requested);
 }
 function writeDevVars(path, credentials, env, o11y) {
   const entry = credentials.envs[env];
@@ -557,28 +652,28 @@ function isManagedDevVar(line2) {
   return !!match?.[1] && MANAGED_DEV_VARS.has(match[1]);
 }
 function writePrivateText(path, text4) {
-  (0, import_node_fs7.mkdirSync)((0, import_node_path5.dirname)(path), { recursive: true });
+  (0, import_node_fs7.mkdirSync)((0, import_node_path6.dirname)(path), { recursive: true });
   const temporary = `${path}.tmp-${process.pid}-${Date.now()}`;
   (0, import_node_fs7.writeFileSync)(temporary, text4, { mode: 384 });
   (0, import_node_fs7.chmodSync)(temporary, 384);
   (0, import_node_fs7.renameSync)(temporary, path);
 }
 function gitignoreEntry(rootDir, path) {
-  const rel = (0, import_node_path5.relative)((0, import_node_path5.resolve)(rootDir), (0, import_node_path5.resolve)(path));
-  if (!rel || rel === ".." || rel.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) || (0, import_node_path5.isAbsolute)(rel)) return null;
+  const rel = (0, import_node_path6.relative)((0, import_node_path6.resolve)(rootDir), (0, import_node_path6.resolve)(path));
+  if (!rel || rel === ".." || rel.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) || (0, import_node_path6.isAbsolute)(rel)) return null;
   return rel.replaceAll("\\", "/");
 }
 function displayPath(path, rootDir = process.cwd()) {
-  const rel = (0, import_node_path5.relative)(rootDir, path);
+  const rel = (0, import_node_path6.relative)(rootDir, path);
   return rel && !rel.startsWith("..") ? rel : path;
 }
-var import_node_fs7, import_node_path5, GITIGNORE_LINES, MANAGED_DEV_VARS;
+var import_node_fs7, import_node_path6, GITIGNORE_LINES, MANAGED_DEV_VARS;
 var init_local = __esm({
   "src/local.ts"() {
     "use strict";
     init_cjs_shims();
     import_node_fs7 = require("fs");
-    import_node_path5 = require("path");
+    import_node_path6 = require("path");
     GITIGNORE_LINES = [".odla/*.local.json", ".odla/dev-token.json", ".dev.vars"];
     MANAGED_DEV_VARS = /* @__PURE__ */ new Set([
       "ODLA_PLATFORM",
@@ -596,7 +691,7 @@ var init_local = __esm({
 });
 
 // src/auth-guidance.ts
-function machineAuthState(audience, env = import_node_process6.default.env) {
+function machineAuthState(audience, env = import_node_process7.default.env) {
   const device = readDeviceCredential(audience, env);
   if (!device) return { enrolled: false };
   const session = readJsonFile(deviceSessionFile(env));
@@ -640,12 +735,12 @@ function lapseNotice(state2, now = Date.now()) {
   if (days < 0) return "this machine's enrollment has lapsed; the next command will ask for approval";
   return `idle for ${days} more day${days === 1 ? "" : "s"} before this machine needs approving again (using it resets the clock)`;
 }
-var import_node_process6, ENROL_EVERYTHING, ENROL_PLATFORM_WIDE;
+var import_node_process7, ENROL_EVERYTHING, ENROL_PLATFORM_WIDE;
 var init_auth_guidance = __esm({
   "src/auth-guidance.ts"() {
     "use strict";
     init_cjs_shims();
-    import_node_process6 = __toESM(require("process"), 1);
+    import_node_process7 = __toESM(require("process"), 1);
     init_device_session();
     init_odla_home();
     init_local();
@@ -687,7 +782,7 @@ var init_cached_credential = __esm({
 });
 
 // src/device-session-cache.ts
-async function deviceSessionToken(platformUrl, audience, credential2, doFetch, env = import_node_process7.default.env) {
+async function deviceSessionToken(platformUrl, audience, credential2, doFetch, env = import_node_process8.default.env) {
   const path = deviceSessionFile(env);
   const cached = readJsonFile(path);
   if (cached?.token && cached.platform === audience && cached.deviceId === credential2.deviceId && (cached.expiresAt ?? 0) > Date.now() + SKEW_MS) return cached;
@@ -700,12 +795,12 @@ async function deviceSessionToken(platformUrl, audience, credential2, doFetch, e
   writePrivateJson(path, session);
   return session;
 }
-var import_node_process7, SKEW_MS;
+var import_node_process8, SKEW_MS;
 var init_device_session_cache = __esm({
   "src/device-session-cache.ts"() {
     "use strict";
     init_cjs_shims();
-    import_node_process7 = __toESM(require("process"), 1);
+    import_node_process8 = __toESM(require("process"), 1);
     init_odla_home();
     init_local();
     init_device_session();
@@ -714,23 +809,23 @@ var init_device_session_cache = __esm({
 });
 
 // src/machine-identity.ts
-function readMachineIdentity(audience, env = import_node_process8.default.env) {
+function readMachineIdentity(audience, env = import_node_process9.default.env) {
   const stored = readJsonFile(identityFile(env));
   if (!stored || typeof stored.email !== "string" || !stored.email) return null;
   return stored.platform === audience ? { platform: audience, email: stored.email } : null;
 }
-function rememberMachineIdentity(audience, email, env = import_node_process8.default.env) {
+function rememberMachineIdentity(audience, email, env = import_node_process9.default.env) {
   if (!email) return;
   const existing = readMachineIdentity(audience, env);
   if (existing?.email === email) return;
   writePrivateJson(identityFile(env), { platform: audience, email });
 }
-var import_node_process8;
+var import_node_process9;
 var init_machine_identity = __esm({
   "src/machine-identity.ts"() {
     "use strict";
     init_cjs_shims();
-    import_node_process8 = __toESM(require("process"), 1);
+    import_node_process9 = __toESM(require("process"), 1);
     init_odla_home();
     init_local();
   }
@@ -744,14 +839,14 @@ async function getDeveloperToken(cfg, options, doFetch, out, grantRequest = {})
   const cached = readJsonFile(cfg.local.tokenFile);
   if (!grantRequest.forceReview && !grantRequest.freshLogin) {
     if (options.token) return options.token;
-    if (import_node_process9.default.env.ODLA_DEV_TOKEN) {
-      const declared = import_node_process9.default.env.ODLA_DEV_TOKEN_AUDIENCE;
+    if (import_node_process10.default.env.ODLA_DEV_TOKEN) {
+      const declared = import_node_process10.default.env.ODLA_DEV_TOKEN_AUDIENCE;
       if (declared) {
         if (platformAudience(declared) !== audience) throw new Error("ODLA_DEV_TOKEN_AUDIENCE does not match the configured platform");
       } else if (audience !== "https://odla.ai") {
         throw new Error("ODLA_DEV_TOKEN_AUDIENCE is required for a non-default platform");
       }
-      return import_node_process9.default.env.ODLA_DEV_TOKEN;
+      return import_node_process10.default.env.ODLA_DEV_TOKEN;
     }
     const device = readDeviceCredential(audience);
     if (device) {
@@ -866,7 +961,7 @@ function stillPending(pending, email) {
   );
 }
 function handshakeEmail(value2, cached) {
-  const email = (value2 ?? import_node_process9.default.env.ODLA_USER_EMAIL ?? cached ?? "").trim().toLowerCase();
+  const email = (value2 ?? import_node_process10.default.env.ODLA_USER_EMAIL ?? cached ?? "").trim().toLowerCase();
   if (/@users\.noreply\.github\.com$/i.test(email)) {
     throw new Error(
       `"${email}" is a GitHub commit identity, not an odla account email; use --email <signed-in-odla-account> or ODLA_USER_EMAIL`
@@ -895,14 +990,14 @@ function platformAudience(value2) {
   }
   return url.origin;
 }
-var import_db, import_node_crypto, import_node_process9;
+var import_db, import_node_crypto, import_node_process10;
 var init_token = __esm({
   "src/token.ts"() {
     "use strict";
     init_cjs_shims();
     import_db = require("@odla-ai/db");
     import_node_crypto = require("crypto");
-    import_node_process9 = __toESM(require("process"), 1);
+    import_node_process10 = __toESM(require("process"), 1);
     init_handshake_approval();
     init_handshake_state();
     init_cached_credential();
@@ -917,7 +1012,7 @@ var init_token = __esm({
 async function secretInputValue(options, kind = "credential") {
   if (options.fromEnv && options.stdin) throw new Error("choose exactly one of --from-env or --stdin");
   let value2;
-  if (options.fromEnv) value2 = import_node_process10.default.env[options.fromEnv];
+  if (options.fromEnv) value2 = import_node_process11.default.env[options.fromEnv];
   else if (options.stdin) value2 = await (options.readStdin ?? (() => readSecretStream(kind)))();
   else throw new Error(`${kind} input required: use --from-env <NAME> or --stdin; values are never accepted as arguments`);
   value2 = value2?.replace(/[\r\n]+$/, "");
@@ -925,7 +1020,7 @@ async function secretInputValue(options, kind = "credential") {
   if (new TextEncoder().encode(value2).byteLength > MAX_BYTES) throw new Error(`${kind} exceeds 64 KiB`);
   return value2;
 }
-async function readSecretStream(kind, stream = import_node_process10.default.stdin) {
+async function readSecretStream(kind, stream = import_node_process11.default.stdin) {
   let value2 = "";
   for await (const chunk of stream) {
     value2 += String(chunk);
@@ -933,12 +1028,12 @@ async function readSecretStream(kind, stream = import_node_process10.default.std
   }
   return value2;
 }
-var import_node_process10, MAX_BYTES;
+var import_node_process11, MAX_BYTES;
 var init_secret_input = __esm({
   "src/secret-input.ts"() {
     "use strict";
     init_cjs_shims();
-    import_node_process10 = __toESM(require("process"), 1);
+    import_node_process11 = __toESM(require("process"), 1);
     MAX_BYTES = 64 * 1024;
   }
 });
@@ -950,7 +1045,7 @@ async function getScopedPlatformToken(options) {
 async function resolveAdminPlatformToken(options) {
   const audience = platformAudience(options.platform);
   if (options.token) return options.token;
-  const fromEnv = import_node_process11.default.env.ODLA_ADMIN_TOKEN;
+  const fromEnv = import_node_process12.default.env.ODLA_ADMIN_TOKEN;
   if (fromEnv) return audienceBoundEnvToken(fromEnv, audience);
   return scopedToken(
     audience,
@@ -962,7 +1057,7 @@ async function resolveAdminPlatformToken(options) {
 }
 function audienceBoundEnvToken(token, platform) {
   const audience = platformAudience(platform);
-  const declared = import_node_process11.default.env.ODLA_ADMIN_TOKEN_AUDIENCE;
+  const declared = import_node_process12.default.env.ODLA_ADMIN_TOKEN_AUDIENCE;
   if (declared) {
     if (platformAudience(declared) !== audience) throw new Error("ODLA_ADMIN_TOKEN_AUDIENCE does not match the configured platform");
   } else if (audience !== "https://odla.ai") {
@@ -972,9 +1067,9 @@ function audienceBoundEnvToken(token, platform) {
 }
 async function scopedToken(platform, scope, options, doFetch, out) {
   const audience = platformAudience(platform);
-  const rootDir = options.rootDir ?? import_node_process11.default.cwd();
+  const rootDir = options.rootDir ?? import_node_process12.default.cwd();
   const tokenFile = options.tokenFile ?? scopedTokenFile();
-  adoptRepoLocalCache((0, import_node_path6.join)(rootDir, ".odla/admin-token.local.json"), tokenFile, out);
+  adoptRepoLocalCache((0, import_node_path7.join)(rootDir, ".odla/admin-token.local.json"), tokenFile, out);
   const device = readDeviceCredential(audience);
   if (device && options.cache !== false) {
     const session = await deviceSessionToken(platform, audience, device, doFetch);
@@ -1021,13 +1116,13 @@ async function scopedToken(platform, scope, options, doFetch, out) {
   }
   return token;
 }
-var import_node_path6, import_node_process11, import_db2, SCOPE_PURPOSE;
+var import_node_path7, import_node_process12, import_db2, SCOPE_PURPOSE;
 var init_admin_ai_auth = __esm({
   "src/admin-ai-auth.ts"() {
     "use strict";
     init_cjs_shims();
-    import_node_path6 = require("path");
-    import_node_process11 = __toESM(require("process"), 1);
+    import_node_path7 = require("path");
+    import_node_process12 = __toESM(require("process"), 1);
     import_db2 = require("@odla-ai/db");
     init_local();
     init_handshake_approval();
@@ -1252,7 +1347,7 @@ var init_admin_ai_usage = __esm({
 
 // src/admin-ai.ts
 async function adminAi(options) {
-  const platform = platformAudience(options.platform ?? import_node_process12.default.env.ODLA_PLATFORM ?? "https://odla.ai");
+  const platform = platformAudience(options.platform ?? import_node_process13.default.env.ODLA_PLATFORM ?? "https://odla.ai");
   const doFetch = options.fetch ?? fetch;
   const out = options.stdout ?? console;
   const usageQuery = options.action === "usage" ? adminAiUsageQuery(options) : void 0;
@@ -1430,12 +1525,12 @@ function apiError3(action2, status, body) {
 function isRecord3(value2) {
   return Boolean(value2) && typeof value2 === "object" && !Array.isArray(value2);
 }
-var import_node_process12;
+var import_node_process13;
 var init_admin_ai = __esm({
   "src/admin-ai.ts"() {
     "use strict";
     init_cjs_shims();
-    import_node_process12 = __toESM(require("process"), 1);
+    import_node_process13 = __toESM(require("process"), 1);
     init_token();
     init_secret_input();
     init_admin_ai_auth();
@@ -1480,10 +1575,17 @@ function parseArgv(argv2) {
 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) {
@@ -1527,6 +1629,196 @@ var init_argv = __esm({
   }
 });
 
+// src/surface.ts
+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;
+}
+var PM_ACTIONS, PM_TASK_ACTIONS, PM_ENTITIES, COMMAND_SURFACE;
+var init_surface = __esm({
+  "src/surface.ts"() {
+    "use strict";
+    init_cjs_shims();
+    PM_ACTIONS = {
+      list: {},
+      add: {},
+      create: {},
+      get: {},
+      set: {},
+      update: {},
+      status: {},
+      move: {},
+      done: {},
+      comment: {},
+      comments: {},
+      history: {},
+      link: {},
+      ref: {},
+      rm: {},
+      delete: {}
+    };
+    PM_TASK_ACTIONS = {
+      ...PM_ACTIONS,
+      ready: {},
+      claim: {},
+      release: {}
+    };
+    PM_ENTITIES = {
+      ...Object.fromEntries(
+        ["goal", "conformance", "decision", "bug"].map((entity) => [entity, PM_ACTIONS])
+      ),
+      task: PM_TASK_ACTIONS,
+      kanban: PM_TASK_ACTIONS
+    };
+    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: {}
+    };
+  }
+});
+
 // src/admin-spend.ts
 async function call(ctx, method, scope) {
   const url = `${ctx.platformUrl.replace(/\/$/, "")}/registry/platform/spend?scope=${encodeURIComponent(scope)}`;
@@ -1575,9 +1867,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>`
@@ -1591,6 +1881,7 @@ var init_admin_spend = __esm({
     "use strict";
     init_cjs_shims();
     init_argv();
+    init_surface();
     money = (value2) => `$${value2.toFixed(2)}`;
   }
 });
@@ -2017,12 +2308,12 @@ var init_monitoring_validation = __esm({
 
 // src/config.ts
 async function loadProjectConfig(configPath = "odla.config.mjs", options = {}) {
-  const resolved = (0, import_node_path7.resolve)(configPath);
+  const resolved = (0, import_node_path8.resolve)(configPath);
   if (!(0, import_node_fs9.existsSync)(resolved)) {
     throw new Error(`config not found: ${configPath}. Run "odla-ai init" first or pass --config.`);
   }
   const raw = await loadConfigModule(resolved);
-  const rootDir = (0, import_node_path7.dirname)(resolved);
+  const rootDir = (0, import_node_path8.dirname)(resolved);
   validateRawConfig(raw, resolved);
   const platformUrl = trimSlash(process.env.ODLA_PLATFORM_URL || raw.platformUrl || DEFAULT_PLATFORM);
   const dbEndpoint = trimSlash(process.env.ODLA_DB_ENDPOINT || raw.dbEndpoint || platformUrl);
@@ -2032,14 +2323,14 @@ async function loadProjectConfig(configPath = "odla.config.mjs", options = {}) {
   validateCalendarConfig(raw, unique3([...envs, ...options.additionalEnvs ?? []]), services, resolved);
   validateMonitoringConfig(raw, unique3([...envs, ...options.additionalEnvs ?? []]), services, resolved);
   const local = {
-    tokenFile: raw.local?.tokenFile ? (0, import_node_path7.resolve)(rootDir, raw.local.tokenFile) : appTokenFile(raw.app.id),
-    credentialsFile: raw.local?.credentialsFile ? (0, import_node_path7.resolve)(rootDir, raw.local.credentialsFile) : appCredentialsFile(raw.app.id),
-    devVarsFile: (0, import_node_path7.resolve)(rootDir, raw.local?.devVarsFile ?? ".dev.vars"),
+    tokenFile: raw.local?.tokenFile ? (0, import_node_path8.resolve)(rootDir, raw.local.tokenFile) : appTokenFile(raw.app.id),
+    credentialsFile: raw.local?.credentialsFile ? (0, import_node_path8.resolve)(rootDir, raw.local.credentialsFile) : appCredentialsFile(raw.app.id),
+    devVarsFile: (0, import_node_path8.resolve)(rootDir, raw.local?.devVarsFile ?? ".dev.vars"),
     gitignore: raw.local?.gitignore ?? true
   };
-  adoptRepoLocalCache((0, import_node_path7.resolve)(rootDir, ".odla/dev-token.json"), local.tokenFile, stderr);
-  adoptRepoLocalCache((0, import_node_path7.resolve)(rootDir, ".odla/credentials.local.json"), local.credentialsFile, stderr);
-  (0, import_node_fs9.rmSync)((0, import_node_path7.resolve)(rootDir, ".odla/handshake.local.json"), { force: true });
+  adoptRepoLocalCache((0, import_node_path8.resolve)(rootDir, ".odla/dev-token.json"), local.tokenFile, stderr);
+  adoptRepoLocalCache((0, import_node_path8.resolve)(rootDir, ".odla/credentials.local.json"), local.credentialsFile, stderr);
+  (0, import_node_fs9.rmSync)((0, import_node_path8.resolve)(rootDir, ".odla/handshake.local.json"), { force: true });
   return {
     ...raw,
     configPath: resolved,
@@ -2054,7 +2345,7 @@ async function loadProjectConfig(configPath = "odla.config.mjs", options = {}) {
 async function resolveDataExport(cfg, value2, names) {
   if (value2 === void 0 || value2 === null || value2 === false) return void 0;
   if (typeof value2 !== "string") return value2;
-  const target = (0, import_node_path7.isAbsolute)(value2) ? value2 : (0, import_node_path7.resolve)(cfg.rootDir, value2);
+  const target = (0, import_node_path8.isAbsolute)(value2) ? value2 : (0, import_node_path8.resolve)(cfg.rootDir, value2);
   if (target.endsWith(".json")) {
     return JSON.parse((0, import_node_fs9.readFileSync)(target, "utf8"));
   }
@@ -2145,13 +2436,13 @@ function trimSlash(value2) {
 function unique3(values) {
   return [...new Set(values.filter(Boolean))];
 }
-var import_node_fs9, import_node_path7, import_node_url, import_apps, DEFAULT_PLATFORM, DEFAULT_ENVS, DEFAULT_SERVICES, configImportSerial, GOOGLE_CALENDAR_EVENTS_SCOPE, stderr;
+var import_node_fs9, import_node_path8, import_node_url, import_apps, DEFAULT_PLATFORM, DEFAULT_ENVS, DEFAULT_SERVICES, configImportSerial, GOOGLE_CALENDAR_EVENTS_SCOPE, stderr;
 var init_config = __esm({
   "src/config.ts"() {
     "use strict";
     init_cjs_shims();
     import_node_fs9 = require("fs");
-    import_node_path7 = require("path");
+    import_node_path8 = require("path");
     import_node_url = require("url");
     import_apps = require("@odla-ai/apps");
     init_ai_config_validation();
@@ -2174,13 +2465,13 @@ var init_config = __esm({
 
 // src/operator-profiles.ts
 function operatorProfileFile() {
-  return (0, import_node_path8.resolve)(
-    clean(import_node_process13.default.env.ODLA_CONTEXT_FILE) ?? (0, import_node_path8.join)((0, import_node_os3.homedir)(), ".odla", "contexts.json")
+  return (0, import_node_path9.resolve)(
+    clean(import_node_process14.default.env.ODLA_CONTEXT_FILE) ?? (0, import_node_path9.join)((0, import_node_os3.homedir)(), ".odla", "contexts.json")
   );
 }
 function resolveOperatorProfile(parsed) {
   const fromFlag = clean(stringOpt(parsed.options.context));
-  const fromEnvironment = clean(import_node_process13.default.env.ODLA_CONTEXT);
+  const fromEnvironment = clean(import_node_process14.default.env.ODLA_CONTEXT);
   const name = fromFlag ?? fromEnvironment ?? null;
   const file = operatorProfileFile();
   if (!name) {
@@ -2220,10 +2511,10 @@ function removeOperatorProfile(name, file = operatorProfileFile()) {
   return true;
 }
 function operatorCredentialFiles(selection) {
-  const base = selection.name ? (0, import_node_path8.join)((0, import_node_path8.dirname)(selection.file), "profiles", selection.name) : (0, import_node_path8.join)((0, import_node_os3.homedir)(), ".odla");
+  const base = selection.name ? (0, import_node_path9.join)((0, import_node_path9.dirname)(selection.file), "profiles", selection.name) : (0, import_node_path9.join)((0, import_node_os3.homedir)(), ".odla");
   return {
-    developer: (0, import_node_path8.join)(base, "dev-token.json"),
-    scoped: (0, import_node_path8.join)(base, "admin-token.local.json")
+    developer: (0, import_node_path9.join)(base, "dev-token.json"),
+    scoped: (0, import_node_path9.join)(base, "admin-token.local.json")
   };
 }
 function assertOperatorName(value2, label) {
@@ -2295,15 +2586,15 @@ function clean(value2) {
   const normalized = value2?.trim();
   return normalized || void 0;
 }
-var import_node_fs10, import_node_os3, import_node_path8, import_node_process13;
+var import_node_fs10, import_node_os3, import_node_path9, import_node_process14;
 var init_operator_profiles = __esm({
   "src/operator-profiles.ts"() {
     "use strict";
     init_cjs_shims();
     import_node_fs10 = require("fs");
     import_node_os3 = require("os");
-    import_node_path8 = require("path");
-    import_node_process13 = __toESM(require("process"), 1);
+    import_node_path9 = require("path");
+    import_node_process14 = __toESM(require("process"), 1);
     init_argv();
     init_local();
     init_token();
@@ -2314,7 +2605,7 @@ var init_operator_profiles = __esm({
 async function resolveOperatorContext(parsed, options = {}) {
   const profile = resolveOperatorProfile(parsed);
   const configArgument = stringOpt(parsed.options.config) ?? "odla.config.mjs";
-  const configPath = (0, import_node_path9.resolve)(configArgument);
+  const configPath = (0, import_node_path10.resolve)(configArgument);
   const explicitConfig = parsed.options.config !== void 0;
   const hasConfig = (0, import_node_fs11.existsSync)(configPath);
   if (!hasConfig && (!options.allowMissingConfig || explicitConfig)) {
@@ -2322,13 +2613,13 @@ async function resolveOperatorContext(parsed, options = {}) {
   }
   const loaded = hasConfig ? await loadProjectConfig(configArgument) : void 0;
   const platformFlag = clean2(stringOpt(parsed.options.platform));
-  const platformEnvironment = clean2(import_node_process14.default.env.ODLA_PLATFORM_URL);
+  const platformEnvironment = clean2(import_node_process15.default.env.ODLA_PLATFORM_URL);
   const platformValue = platformAudience(
     platformFlag ?? platformEnvironment ?? profile.value?.platform ?? loaded?.platformUrl ?? DEFAULT_PLATFORM2
   );
   const platformSource = platformFlag ? "flag" : platformEnvironment ? "environment" : profile.value ? "profile" : loaded ? "config" : "default";
   const appFlag = clean2(stringOpt(parsed.options.app));
-  const appEnvironment = clean2(import_node_process14.default.env.ODLA_APP_ID);
+  const appEnvironment = clean2(import_node_process15.default.env.ODLA_APP_ID);
   const appValue = appFlag ?? appEnvironment ?? profile.value?.app ?? loaded?.app.id ?? null;
   const appSource = appFlag ? "flag" : appEnvironment ? "environment" : profile.value?.app ? "profile" : loaded ? "config" : "unresolved";
   if (appValue) {
@@ -2342,16 +2633,16 @@ async function resolveOperatorContext(parsed, options = {}) {
     );
   }
   const envFlag = clean2(stringOpt(parsed.options.env));
-  const envEnvironment = clean2(import_node_process14.default.env.ODLA_ENV);
+  const envEnvironment = clean2(import_node_process15.default.env.ODLA_ENV);
   const environmentValue = envFlag ?? envEnvironment ?? profile.value?.environment ?? options.defaultEnvironment ?? null;
   const environmentSource = envFlag ? "flag" : envEnvironment ? "environment" : profile.value?.environment ? "profile" : options.defaultEnvironment ? "default" : "unresolved";
   if (environmentValue) {
     assertOperatorName(environmentValue, "environment");
   }
-  const rootDir = loaded?.rootDir ?? import_node_process14.default.cwd();
+  const rootDir = loaded?.rootDir ?? import_node_process15.default.cwd();
   const profileCredentials = operatorCredentialFiles(profile);
-  const tokenFile = clean2(import_node_process14.default.env.ODLA_DEV_TOKEN_FILE) ? (0, import_node_path9.resolve)(import_node_process14.default.env.ODLA_DEV_TOKEN_FILE) : profile.name ? profileCredentials.developer : loaded?.local.tokenFile ?? profileCredentials.developer;
-  const scopedTokenFile2 = clean2(import_node_process14.default.env.ODLA_ADMIN_TOKEN_FILE) ? (0, import_node_path9.resolve)(import_node_process14.default.env.ODLA_ADMIN_TOKEN_FILE) : profile.name ? profileCredentials.scoped : loaded ? (0, import_node_path9.join)(loaded.rootDir, ".odla", "admin-token.local.json") : profileCredentials.scoped;
+  const tokenFile = clean2(import_node_process15.default.env.ODLA_DEV_TOKEN_FILE) ? (0, import_node_path10.resolve)(import_node_process15.default.env.ODLA_DEV_TOKEN_FILE) : profile.name ? profileCredentials.developer : loaded?.local.tokenFile ?? profileCredentials.developer;
+  const scopedTokenFile2 = clean2(import_node_process15.default.env.ODLA_ADMIN_TOKEN_FILE) ? (0, import_node_path10.resolve)(import_node_process15.default.env.ODLA_ADMIN_TOKEN_FILE) : profile.name ? profileCredentials.scoped : loaded ? (0, import_node_path10.join)(loaded.rootDir, ".odla", "admin-token.local.json") : profileCredentials.scoped;
   const cfg = loaded ? {
     ...loaded,
     platformUrl: platformValue,
@@ -2373,8 +2664,8 @@ async function resolveOperatorContext(parsed, options = {}) {
     services: [],
     local: {
       tokenFile,
-      credentialsFile: (0, import_node_path9.join)(rootDir, ".odla", "credentials.local.json"),
-      devVarsFile: (0, import_node_path9.join)(rootDir, ".dev.vars"),
+      credentialsFile: (0, import_node_path10.join)(rootDir, ".odla", "credentials.local.json"),
+      devVarsFile: (0, import_node_path10.join)(rootDir, ".dev.vars"),
       gitignore: true
     }
   };
@@ -2406,14 +2697,14 @@ function clean2(value2) {
   const normalized = value2?.trim();
   return normalized || void 0;
 }
-var import_node_fs11, import_node_path9, import_node_process14, DEFAULT_PLATFORM2;
+var import_node_fs11, import_node_path10, import_node_process15, DEFAULT_PLATFORM2;
 var init_operator_context = __esm({
   "src/operator-context.ts"() {
     "use strict";
     init_cjs_shims();
     import_node_fs11 = require("fs");
-    import_node_path9 = require("path");
-    import_node_process14 = __toESM(require("process"), 1);
+    import_node_path10 = require("path");
+    import_node_process15 = __toESM(require("process"), 1);
     init_argv();
     init_config();
     init_operator_profiles();
@@ -2426,6 +2717,11 @@ var init_operator_context = __esm({
 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 });
@@ -2451,14 +2747,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 });
@@ -2504,6 +2797,7 @@ var init_admin_command = __esm({
     init_token();
     init_argv();
     init_operator_context();
+    init_surface();
     CONTEXT_OPTIONS = ["platform", "config", "context", "token", "open", "email"];
     JSON_OPTIONS = [...CONTEXT_OPTIONS, "json"];
     SET_OPTIONS = [
@@ -2708,9 +3002,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
@@ -2718,7 +3010,7 @@ async function authCommand(parsed, deps = {}) {
   const { cfg } = context;
   const out = deps.stdout ?? console;
   const doFetch = deps.fetch ?? fetch;
-  const email = stringOpt(parsed.options.email) ?? import_node_process15.default.env.ODLA_USER_EMAIL?.trim();
+  const email = stringOpt(parsed.options.email) ?? import_node_process16.default.env.ODLA_USER_EMAIL?.trim();
   if (!email) {
     throw new Error(
       "auth login requires --email <odla-account> or ODLA_USER_EMAIL; confirm the signed-in odla email instead of using git or GitHub identity"
@@ -2757,17 +3049,18 @@ async function authCommand(parsed, deps = {}) {
   out.log(`Authorized ${identity.displayName}${handle} for ${cfg.app.id}.`);
   out.log(`odla account: ${identity.email ?? "not returned"}`);
 }
-var import_node_process15;
+var import_node_process16;
 var init_auth_command = __esm({
   "src/auth-command.ts"() {
     "use strict";
     init_cjs_shims();
-    import_node_process15 = __toESM(require("process"), 1);
+    import_node_process16 = __toESM(require("process"), 1);
     init_argv();
     init_operator_context();
     init_token();
     init_auth_guidance();
     init_whoami_command();
+    init_surface();
   }
 });
 
@@ -2803,9 +3096,7 @@ var init_tenant = __esm({
 // 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"');
@@ -2887,6 +3178,7 @@ var init_agent_command = __esm({
     init_config();
     init_tenant();
     init_local();
+    init_surface();
   }
 });
 
@@ -3010,9 +3302,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);
 }
 var init_app_owners = __esm({
   "src/app-owners.ts"() {
@@ -3020,6 +3310,7 @@ var init_app_owners = __esm({
     init_cjs_shims();
     init_argv();
     init_human_session();
+    init_surface();
   }
 });
 
@@ -3143,8 +3434,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);
@@ -3171,6 +3464,7 @@ var init_app_lifecycle = __esm({
     init_app_transfer();
     init_argv();
     init_human_session();
+    init_surface();
   }
 });
 
@@ -3280,15 +3574,15 @@ var init_brand_design_unpack = __esm({
 
 // src/brand-command.ts
 async function readBundle(source, deps) {
-  if (source !== "-") return (0, import_promises.readFile)((0, import_node_path10.resolve)(source), "utf8");
+  if (source !== "-") return (0, import_promises.readFile)((0, import_node_path11.resolve)(source), "utf8");
   const readStdin = deps.readStdin;
   if (!readStdin) throw new Error("reading a bundle from stdin is not supported here");
   return readStdin();
 }
 async function writeAll(result, outDir) {
   for (const file of result.files) {
-    const target = (0, import_node_path10.resolve)(outDir, file.path);
-    await (0, import_promises.mkdir)((0, import_node_path10.dirname)(target), { recursive: true });
+    const target = (0, import_node_path11.resolve)(outDir, file.path);
+    await (0, import_promises.mkdir)((0, import_node_path11.dirname)(target), { recursive: true });
     await (0, import_promises.writeFile)(target, file.bytes);
   }
 }
@@ -3296,7 +3590,7 @@ async function designUnpack(parsed, deps) {
   assertArgs(parsed, ["out", "json"], 4);
   const source = parsed.positionals[3];
   if (!source) throw new Error(USAGE);
-  const outDir = (0, import_node_path10.resolve)(stringOpt(parsed.options.out) ?? "design");
+  const outDir = (0, import_node_path11.resolve)(stringOpt(parsed.options.out) ?? "design");
   const result = unpackDesign(await readBundle(source, deps));
   await writeAll(result, outDir);
   const out = deps.stdout ?? console;
@@ -3320,17 +3614,19 @@ 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);
 }
-var import_promises, import_node_path10, USAGE;
+var import_promises, import_node_path11, USAGE;
 var init_brand_command = __esm({
   "src/brand-command.ts"() {
     "use strict";
     init_cjs_shims();
     import_promises = require("fs/promises");
-    import_node_path10 = require("path");
+    import_node_path11 = require("path");
     init_argv();
     init_brand_design_unpack();
+    init_surface();
     USAGE = "usage: odla-ai brand design unpack <bundle.html|-> [--out <dir>] [--json]";
   }
 });
@@ -4376,7 +4672,7 @@ async function operationClient(cfg, options, purpose) {
     platform: cfg.platformUrl,
     scope: "app:config:write",
     token: options.token,
-    tokenFile: (0, import_node_path11.join)(cfg.rootDir, ".odla", "admin-token.local.json"),
+    tokenFile: (0, import_node_path12.join)(cfg.rootDir, ".odla", "admin-token.local.json"),
     rootDir: cfg.rootDir,
     email: options.email,
     open: options.open,
@@ -4428,13 +4724,13 @@ function normalizeRequestError(error) {
 function record4(value2) {
   return !!value2 && typeof value2 === "object" && !Array.isArray(value2);
 }
-var import_apps6, import_node_path11, IDEMPOTENCY_KEY, DEFAULT_WAIT_SECONDS, DEFAULT_INTERVAL_SECONDS;
+var import_apps6, import_node_path12, IDEMPOTENCY_KEY, DEFAULT_WAIT_SECONDS, DEFAULT_INTERVAL_SECONDS;
 var init_config_operation_command = __esm({
   "src/config-operation-command.ts"() {
     "use strict";
     init_cjs_shims();
     import_apps6 = require("@odla-ai/apps");
-    import_node_path11 = require("path");
+    import_node_path12 = require("path");
     init_admin_ai_auth();
     init_version();
     init_config();
@@ -4757,7 +5053,7 @@ async function inspectConfig(options) {
     platform: cfg.platformUrl,
     scope: "app:config:read",
     token: options.token,
-    tokenFile: (0, import_node_path12.join)(cfg.rootDir, ".odla", "admin-token.local.json"),
+    tokenFile: (0, import_node_path13.join)(cfg.rootDir, ".odla", "admin-token.local.json"),
     rootDir: cfg.rootDir,
     email: options.email,
     open: options.open,
@@ -4886,13 +5182,13 @@ function studioSettingsUrl(reconciliation) {
 function quoteArg2(value2) {
   return `'${value2.replace(/'/g, `'\\''`)}'`;
 }
-var import_apps8, import_node_path12;
+var import_apps8, import_node_path13;
 var init_config_reconcile_command = __esm({
   "src/config-reconcile-command.ts"() {
     "use strict";
     init_cjs_shims();
     import_apps8 = require("@odla-ai/apps");
-    import_node_path12 = require("path");
+    import_node_path13 = require("path");
     init_admin_ai_auth();
     init_config();
     init_config_reconcile_digest();
@@ -4905,7 +5201,7 @@ var init_config_reconcile_command = __esm({
 // src/wrangler.ts
 function findWranglerConfig(rootDir) {
   for (const name of WRANGLER_CONFIG_FILES) {
-    const path = (0, import_node_path13.join)(rootDir, name);
+    const path = (0, import_node_path14.join)(rootDir, name);
     if ((0, import_node_fs14.existsSync)(path)) return path;
   }
   return null;
@@ -5017,16 +5313,16 @@ function wranglerBulkSecrets(run, opts) {
   ];
   return run("npx", args, { input: JSON.stringify(opts.secrets), cwd: opts.cwd });
 }
-var import_node_child_process2, import_node_fs14, import_node_path13, defaultRunner, WRANGLER_CONFIG_FILES;
+var import_node_child_process3, import_node_fs14, import_node_path14, defaultRunner, WRANGLER_CONFIG_FILES;
 var init_wrangler = __esm({
   "src/wrangler.ts"() {
     "use strict";
     init_cjs_shims();
-    import_node_child_process2 = require("child_process");
+    import_node_child_process3 = require("child_process");
     import_node_fs14 = require("fs");
-    import_node_path13 = require("path");
+    import_node_path14 = require("path");
     defaultRunner = (cmd, args, opts) => new Promise((resolvePromise, reject) => {
-      const child = (0, import_node_child_process2.spawn)(cmd, args, { cwd: opts?.cwd, stdio: ["pipe", "pipe", "pipe"] });
+      const child = (0, import_node_child_process3.spawn)(cmd, args, { cwd: opts?.cwd, stdio: ["pipe", "pipe", "pipe"] });
       let stdout = "";
       let stderr2 = "";
       child.stdout.on("data", (chunk) => stdout += chunk.toString());
@@ -5083,10 +5379,10 @@ function wranglerWarnings(rootDir) {
   for (const { label, block: block2 } of blocks) {
     const assets = block2.assets;
     if (assets?.directory) {
-      const dir = (0, import_node_path14.resolve)(rootDir, assets.directory);
-      if (dir === (0, import_node_path14.resolve)(rootDir)) {
+      const dir = (0, import_node_path15.resolve)(rootDir, assets.directory);
+      if (dir === (0, import_node_path15.resolve)(rootDir)) {
         warnings.push(`${label}assets.directory is the project root \u2014 point it at a dedicated build dir (wrangler dev fails with "spawn EBADF")`);
-      } else if ((0, import_node_fs15.existsSync)((0, import_node_path14.join)(dir, "node_modules"))) {
+      } else if ((0, import_node_fs15.existsSync)((0, import_node_path15.join)(dir, "node_modules"))) {
         warnings.push(`${label}assets.directory contains node_modules \u2014 wrangler dev's watcher will exhaust file descriptors`);
       }
     }
@@ -5121,7 +5417,7 @@ function o11yProjectWarnings(rootDir) {
     warnings.push("cannot verify o11y Worker instrumentation \u2014 add a parseable wrangler.jsonc/json config");
     return warnings;
   }
-  const main = typeof config.main === "string" ? (0, import_node_path14.resolve)(rootDir, config.main) : null;
+  const main = typeof config.main === "string" ? (0, import_node_path15.resolve)(rootDir, config.main) : null;
   if (!main || !(0, import_node_fs15.existsSync)(main)) {
     warnings.push("cannot verify o11y Worker instrumentation \u2014 wrangler main is missing or unreadable");
   } else {
@@ -5151,23 +5447,23 @@ function calendarProjectWarnings(rootDir) {
 }
 function readPackageJson(rootDir) {
   try {
-    return JSON.parse((0, import_node_fs15.readFileSync)((0, import_node_path14.join)(rootDir, "package.json"), "utf8"));
+    return JSON.parse((0, import_node_fs15.readFileSync)((0, import_node_path15.join)(rootDir, "package.json"), "utf8"));
   } catch {
     return null;
   }
 }
-var import_node_child_process3, import_node_fs15, import_node_path14, defaultExec;
+var import_node_child_process4, import_node_fs15, import_node_path15, defaultExec;
 var init_doctor_checks = __esm({
   "src/doctor-checks.ts"() {
     "use strict";
     init_cjs_shims();
-    import_node_child_process3 = require("child_process");
+    import_node_child_process4 = require("child_process");
     import_node_fs15 = require("fs");
-    import_node_path14 = require("path");
+    import_node_path15 = require("path");
     init_redact();
     init_local();
     init_wrangler();
-    defaultExec = (cmd, args, cwd) => (0, import_node_child_process3.execFileSync)(cmd, args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    defaultExec = (cmd, args, cwd) => (0, import_node_child_process4.execFileSync)(cmd, args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
   }
 });
 
@@ -5500,8 +5796,8 @@ var init_harness_options = __esm({
 // src/init.ts
 function initProject(options) {
   const out = options.stdout ?? console;
-  const rootDir = (0, import_node_path15.resolve)(options.rootDir ?? process.cwd());
-  const configPath = (0, import_node_path15.resolve)(rootDir, options.configPath ?? "odla.config.mjs");
+  const rootDir = (0, import_node_path16.resolve)(options.rootDir ?? process.cwd());
+  const configPath = (0, import_node_path16.resolve)(rootDir, options.configPath ?? "odla.config.mjs");
   if ((0, import_node_fs16.existsSync)(configPath) && !options.force) {
     throw new Error(`${configPath} already exists. Pass --force to overwrite.`);
   }
@@ -5518,12 +5814,12 @@ function initProject(options) {
     }
   }
   const aiProvider = options.aiProvider;
-  (0, import_node_fs16.mkdirSync)((0, import_node_path15.dirname)(configPath), { recursive: true });
-  (0, import_node_fs16.mkdirSync)((0, import_node_path15.resolve)(rootDir, "src/odla"), { recursive: true });
-  (0, import_node_fs16.mkdirSync)((0, import_node_path15.resolve)(rootDir, ".odla"), { recursive: true });
+  (0, import_node_fs16.mkdirSync)((0, import_node_path16.dirname)(configPath), { recursive: true });
+  (0, import_node_fs16.mkdirSync)((0, import_node_path16.resolve)(rootDir, "src/odla"), { recursive: true });
+  (0, import_node_fs16.mkdirSync)((0, import_node_path16.resolve)(rootDir, ".odla"), { recursive: true });
   (0, import_node_fs16.writeFileSync)(configPath, configTemplate({ appId: options.appId, name: options.name, envs, services, aiProvider }));
-  writeIfMissing((0, import_node_path15.resolve)(rootDir, "src/odla/schema.mjs"), schemaTemplate());
-  writeIfMissing((0, import_node_path15.resolve)(rootDir, "src/odla/rules.mjs"), rulesTemplate());
+  writeIfMissing((0, import_node_path16.resolve)(rootDir, "src/odla/schema.mjs"), schemaTemplate());
+  writeIfMissing((0, import_node_path16.resolve)(rootDir, "src/odla/rules.mjs"), rulesTemplate());
   ensureGitignore(rootDir);
   out.log(`created ${relativeDisplay(configPath, rootDir)}`);
   out.log("created src/odla/schema.mjs and src/odla/rules.mjs");
@@ -5636,13 +5932,13 @@ function defaultKeyEnv(provider) {
 function relativeDisplay(path, rootDir) {
   return path.startsWith(rootDir) ? path.slice(rootDir.length + 1) : path;
 }
-var import_node_fs16, import_node_path15, import_apps9;
+var import_node_fs16, import_node_path16, import_apps9;
 var init_init = __esm({
   "src/init.ts"() {
     "use strict";
     init_cjs_shims();
     import_node_fs16 = require("fs");
-    import_node_path15 = require("path");
+    import_node_path16 = require("path");
     import_apps9 = require("@odla-ai/apps");
     init_local();
   }
@@ -5975,8 +6271,8 @@ function installSkill(options = {}) {
   const files = listFiles(sourceDir);
   if (files.length === 0) throw new Error(`no bundled skills found at ${sourceDir}`);
   const harnesses = normalizeHarnesses(options.harnesses, options.global === true);
-  const root = (0, import_node_path16.resolve)(options.dir ?? process.cwd());
-  const home = (0, import_node_path16.resolve)(options.homeDir ?? (0, import_node_os4.homedir)());
+  const root = (0, import_node_path17.resolve)(options.dir ?? process.cwd());
+  const home = (0, import_node_path17.resolve)(options.homeDir ?? (0, import_node_os4.homedir)());
   const plans = /* @__PURE__ */ new Map();
   const targets = /* @__PURE__ */ new Map();
   const rememberTarget = (harness, target) => {
@@ -5990,48 +6286,48 @@ function installSkill(options = {}) {
     plans.set(target, { target, content: content2, boundary, managedMerge });
   };
   const planSkillTree = (targetDir2, boundary = root) => {
-    for (const rel of files) plan((0, import_node_path16.join)(targetDir2, rel), (0, import_node_fs17.readFileSync)((0, import_node_path16.join)(sourceDir, rel), "utf8"), false, boundary);
+    for (const rel of files) plan((0, import_node_path17.join)(targetDir2, rel), (0, import_node_fs17.readFileSync)((0, import_node_path17.join)(sourceDir, rel), "utf8"), false, boundary);
   };
   let targetDir;
   if (options.global) {
-    const claudeRoot = (0, import_node_path16.join)(home, ".claude", "skills");
-    const codexRoot = (0, import_node_path16.resolve)(options.codexHomeDir ?? process.env.CODEX_HOME ?? (0, import_node_path16.join)(home, ".codex"), "skills");
+    const claudeRoot = (0, import_node_path17.join)(home, ".claude", "skills");
+    const codexRoot = (0, import_node_path17.resolve)(options.codexHomeDir ?? process.env.CODEX_HOME ?? (0, import_node_path17.join)(home, ".codex"), "skills");
     targetDir = harnesses[0] === "codex" ? codexRoot : claudeRoot;
     for (const harness of harnesses) {
       const skillRoot = harness === "claude" ? claudeRoot : codexRoot;
-      planSkillTree(skillRoot, harness === "claude" ? home : (0, import_node_path16.dirname)((0, import_node_path16.dirname)(codexRoot)));
+      planSkillTree(skillRoot, harness === "claude" ? home : (0, import_node_path17.dirname)((0, import_node_path17.dirname)(codexRoot)));
       rememberTarget(harness, skillRoot);
     }
   } else {
-    const sharedRoot = (0, import_node_path16.join)(root, ".agents", "skills");
+    const sharedRoot = (0, import_node_path17.join)(root, ".agents", "skills");
     planSkillTree(sharedRoot);
-    const claudeRoot = (0, import_node_path16.join)(root, ".claude", "skills");
+    const claudeRoot = (0, import_node_path17.join)(root, ".claude", "skills");
     targetDir = harnesses.includes("claude") ? claudeRoot : sharedRoot;
     for (const harness of harnesses) rememberTarget(harness, sharedRoot);
     if (harnesses.includes("claude")) {
       for (const skill of skillNames(files)) {
-        const canonical2 = (0, import_node_fs17.readFileSync)((0, import_node_path16.join)(sourceDir, skill, "SKILL.md"), "utf8");
-        plan((0, import_node_path16.join)(claudeRoot, skill, "SKILL.md"), claudeAdapter(skill, canonical2));
+        const canonical2 = (0, import_node_fs17.readFileSync)((0, import_node_path17.join)(sourceDir, skill, "SKILL.md"), "utf8");
+        plan((0, import_node_path17.join)(claudeRoot, skill, "SKILL.md"), claudeAdapter(skill, canonical2));
       }
       rememberTarget("claude", claudeRoot);
     }
     if (harnesses.includes("cursor")) {
-      const cursorRule = (0, import_node_path16.join)(root, ".cursor", "rules", "odla.mdc");
+      const cursorRule = (0, import_node_path17.join)(root, ".cursor", "rules", "odla.mdc");
       plan(cursorRule, CURSOR_RULE);
       rememberTarget("cursor", cursorRule);
     }
     if (harnesses.includes("agents")) {
-      const agentsFile = (0, import_node_path16.join)(root, "AGENTS.md");
+      const agentsFile = (0, import_node_path17.join)(root, "AGENTS.md");
       plan(agentsFile, managedFileContent(agentsFile, PROJECT_INSTRUCTIONS, options.force === true, root), true);
       rememberTarget("agents", agentsFile);
     }
     if (harnesses.includes("copilot")) {
-      const copilotFile = (0, import_node_path16.join)(root, ".github", "copilot-instructions.md");
+      const copilotFile = (0, import_node_path17.join)(root, ".github", "copilot-instructions.md");
       plan(copilotFile, managedFileContent(copilotFile, PROJECT_INSTRUCTIONS, options.force === true, root), true);
       rememberTarget("copilot", copilotFile);
     }
     if (harnesses.includes("gemini")) {
-      const geminiFile = (0, import_node_path16.join)(root, "GEMINI.md");
+      const geminiFile = (0, import_node_path17.join)(root, "GEMINI.md");
       plan(geminiFile, managedFileContent(geminiFile, PROJECT_INSTRUCTIONS, options.force === true, root), true);
       rememberTarget("gemini", geminiFile);
     }
@@ -6067,7 +6363,7 @@ ${conflicts.map((f) => `  - ${f}`).join("\n")}`
   }
   for (const file of plans.values()) {
     if (!(0, import_node_fs17.existsSync)(file.target) || (0, import_node_fs17.readFileSync)(file.target, "utf8") !== file.content) {
-      (0, import_node_fs17.mkdirSync)((0, import_node_path16.dirname)(file.target), { recursive: true });
+      (0, import_node_fs17.mkdirSync)((0, import_node_path17.dirname)(file.target), { recursive: true });
       (0, import_node_fs17.writeFileSync)(file.target, file.content);
     }
   }
@@ -6087,7 +6383,7 @@ ${conflicts.map((f) => `  - ${f}`).join("\n")}`
   };
 }
 function pathsUnder(root, paths2) {
-  return [...paths2].map((path) => (0, import_node_path16.relative)(root, path)).filter((path) => path !== ".." && !path.startsWith(`..${import_node_path16.sep}`) && !(0, import_node_path16.isAbsolute)(path)).sort();
+  return [...paths2].map((path) => (0, import_node_path17.relative)(root, path)).filter((path) => path !== ".." && !path.startsWith(`..${import_node_path17.sep}`) && !(0, import_node_path17.isAbsolute)(path)).sort();
 }
 function normalizeHarnesses(values, global) {
   const requested = values?.length ? values : ["claude"];
@@ -6132,13 +6428,13 @@ function managedFileContent(path, block2, force, boundary) {
   return `${current.slice(0, startAt)}${block2}${current.slice(afterEnd)}`;
 }
 function symlinkedComponent(boundary, target) {
-  const rel = (0, import_node_path16.relative)(boundary, target);
-  if (rel === ".." || rel.startsWith(`..${import_node_path16.sep}`) || (0, import_node_path16.isAbsolute)(rel)) {
+  const rel = (0, import_node_path17.relative)(boundary, target);
+  if (rel === ".." || rel.startsWith(`..${import_node_path17.sep}`) || (0, import_node_path17.isAbsolute)(rel)) {
     throw new Error(`agent setup target escapes its install root: ${target}`);
   }
   let current = boundary;
-  for (const part of rel.split(import_node_path16.sep).filter(Boolean)) {
-    current = (0, import_node_path16.join)(current, part);
+  for (const part of rel.split(import_node_path17.sep).filter(Boolean)) {
+    current = (0, import_node_path17.join)(current, part);
     try {
       if ((0, import_node_fs17.lstatSync)(current).isSymbolicLink()) return current;
     } catch (error) {
@@ -6155,22 +6451,22 @@ function listFiles(dir) {
   const results = [];
   const walk = (current) => {
     for (const entry of (0, import_node_fs17.readdirSync)(current, { withFileTypes: true })) {
-      const path = (0, import_node_path16.join)(current, entry.name);
+      const path = (0, import_node_path17.join)(current, entry.name);
       if (entry.isDirectory()) walk(path);
-      else results.push((0, import_node_path16.relative)(dir, path));
+      else results.push((0, import_node_path17.relative)(dir, path));
     }
   };
   walk(dir);
   return results.sort();
 }
-var import_node_fs17, import_node_os4, import_node_path16, import_node_url2, AGENT_HARNESSES;
+var import_node_fs17, import_node_os4, import_node_path17, import_node_url2, AGENT_HARNESSES;
 var init_skill = __esm({
   "src/skill.ts"() {
     "use strict";
     init_cjs_shims();
     import_node_fs17 = require("fs");
     import_node_os4 = require("os");
-    import_node_path16 = require("path");
+    import_node_path17 = require("path");
     import_node_url2 = require("url");
     init_skill_adapters();
     AGENT_HARNESSES = ["claude", "codex", "cursor", "copilot", "gemini", "agents"];
@@ -6392,9 +6688,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({
@@ -6407,7 +6701,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",
@@ -6421,9 +6715,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"],
@@ -6451,7 +6743,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,
@@ -6525,7 +6817,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;
   }
@@ -6553,6 +6845,7 @@ var init_cli_project = __esm({
     init_secrets_status();
     init_skill();
     init_smoke();
+    init_surface();
     SKILL_OPTS = ["dir", "global", "force", "agent", "harness"];
   }
 });
@@ -7743,7 +8036,7 @@ var init_dist2 = __esm({
 });
 
 // ../graph/dist/code/index.js
-function dirname10(path) {
+function dirname11(path) {
   const at = path.lastIndexOf("/");
   return at <= 0 ? "." : path.slice(0, at);
 }
@@ -7759,7 +8052,7 @@ function join14(base, specifier) {
 }
 function resolveImport(fromPath, specifier, known) {
   if (!specifier.startsWith(".")) return null;
-  const base = join14(dirname10(fromPath), specifier);
+  const base = join14(dirname11(fromPath), specifier);
   const candidates = [
     base,
     base.replace(/\.js$/, ".ts"),
@@ -10870,19 +11163,19 @@ async function inferGitHubRepository(cwd = process.cwd(), readOrigin = defaultRe
   return repositoryFromGitRemote(remote);
 }
 async function defaultReadOrigin(cwd) {
-  const result = await (0, import_node_util2.promisify)(import_node_child_process4.execFile)(
+  const result = await (0, import_node_util2.promisify)(import_node_child_process5.execFile)(
     "git",
     ["remote", "get-url", "origin"],
     { cwd, encoding: "utf8" }
   );
   return result.stdout;
 }
-var import_node_child_process4, import_node_util2;
+var import_node_child_process5, import_node_util2;
 var init_security_hosted_github = __esm({
   "src/security-hosted-github.ts"() {
     "use strict";
     init_cjs_shims();
-    import_node_child_process4 = require("child_process");
+    import_node_child_process5 = require("child_process");
     import_node_util2 = require("util");
     init_security_hosted_request();
   }
@@ -10929,7 +11222,7 @@ async function prepareCodeLocalSource(cwd, repository, readHead = readGitHead) {
 }
 async function readGitHead(cwd) {
   const value2 = await new Promise((accept, reject) => {
-    (0, import_node_child_process5.execFile)("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf8", maxBuffer: 16384 }, (error, stdout) => {
+    (0, import_node_child_process6.execFile)("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf8", maxBuffer: 16384 }, (error, stdout) => {
       if (error) reject(new Error("code connect requires a Git checkout with an initial commit"));
       else accept(stdout.trim());
     });
@@ -10940,12 +11233,12 @@ async function readGitHead(cwd) {
 function digestText(value2) {
   return `sha256:${(0, import_node_crypto3.createHash)("sha256").update(value2).digest("hex")}`;
 }
-var import_node_child_process5, import_node_crypto3, SOURCE_LIMITS2;
+var import_node_child_process6, import_node_crypto3, SOURCE_LIMITS2;
 var init_code_local_source = __esm({
   "src/code-local-source.ts"() {
     "use strict";
     init_cjs_shims();
-    import_node_child_process5 = require("child_process");
+    import_node_child_process6 = require("child_process");
     import_node_crypto3 = require("crypto");
     init_node();
     SOURCE_LIMITS2 = { maxFiles: 2e4, maxBytes: 512 * 1024 * 1024 };
@@ -10986,7 +11279,7 @@ var init_code_runtime_config = __esm({
 // src/code-connect.ts
 async function codeConnect(options) {
   const cwd = options.cwd ?? process.cwd();
-  const configPath = (0, import_node_path17.resolve)(cwd, options.configPath);
+  const configPath = (0, import_node_path18.resolve)(cwd, options.configPath);
   const cfg = (0, import_node_fs18.existsSync)(configPath) ? await loadProjectConfig(configPath) : null;
   const requestedAppId = options.appId?.trim();
   if (requestedAppId && !/^[a-z0-9][a-z0-9-]{1,62}$/.test(requestedAppId)) {
@@ -11152,14 +11445,14 @@ function apiFailure(action2, status, value2) {
 function record6(value2) {
   return value2 && typeof value2 === "object" && !Array.isArray(value2) ? value2 : null;
 }
-var import_node_fs18, import_node_os5, import_node_path17;
+var import_node_fs18, import_node_os5, import_node_path18;
 var init_code_connect = __esm({
   "src/code-connect.ts"() {
     "use strict";
     init_cjs_shims();
     import_node_fs18 = require("fs");
     import_node_os5 = require("os");
-    import_node_path17 = require("path");
+    import_node_path18 = require("path");
     init_node();
     init_admin_ai_auth();
     init_config();
@@ -11198,9 +11491,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);
@@ -11267,6 +11558,7 @@ var init_code_grant_command = __esm({
     init_config();
     init_redact();
     init_token();
+    init_surface();
     ACTIONS = ["request", "list", "approve", "revoke"];
     isAction = (value2) => ACTIONS.includes(value2 ?? "");
   }
@@ -11331,9 +11623,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");
@@ -11398,6 +11688,7 @@ var init_code_repository_command = __esm({
     init_config();
     init_redact();
     init_token();
+    init_surface();
     ACTIONS2 = ["show", "list", "bind"];
     isAction2 = (value2) => ACTIONS2.includes(value2 ?? "");
   }
@@ -11421,9 +11712,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",
@@ -11468,6 +11757,7 @@ var init_code_command = __esm({
     init_code_connect();
     init_code_grant_command();
     init_code_repository_command();
+    init_surface();
   }
 });
 
@@ -11477,7 +11767,7 @@ function developerTokenStatus(context, parsed, now = Date.now()) {
   const cacheStatus = !cached?.token ? "missing" : cached.platform !== context.platform.value ? "other-platform" : (cached.expiresAt ?? 0) <= now + 6e4 ? "expired" : "valid";
   const source = clean3(
     stringOpt(parsed.options.token)
-  ) ? "flag" : clean3(import_node_process16.default.env.ODLA_DEV_TOKEN) ? "environment" : cacheStatus === "valid" ? "cache" : "missing";
+  ) ? "flag" : clean3(import_node_process17.default.env.ODLA_DEV_TOKEN) ? "environment" : cacheStatus === "valid" ? "cache" : "missing";
   return {
     source,
     cacheFile: context.cfg.local.tokenFile,
@@ -11488,12 +11778,12 @@ function clean3(value2) {
   const normalized = value2?.trim();
   return normalized || void 0;
 }
-var import_node_process16;
+var import_node_process17;
 var init_operator_credentials = __esm({
   "src/operator-credentials.ts"() {
     "use strict";
     init_cjs_shims();
-    import_node_process16 = __toESM(require("process"), 1);
+    import_node_process17 = __toESM(require("process"), 1);
     init_argv();
     init_local();
   }
@@ -11579,9 +11869,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,
@@ -11638,6 +11926,7 @@ var init_context_command = __esm({
     init_operator_credentials();
     init_operator_context();
     init_operator_profiles();
+    init_surface();
   }
 });
 
@@ -11647,9 +11936,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;
@@ -11697,6 +11984,7 @@ var init_credential_command = __esm({
     init_config();
     init_redact();
     init_token();
+    init_surface();
   }
 });
 
@@ -12075,9 +12363,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
@@ -12697,7 +12993,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":
@@ -12721,7 +13017,7 @@ async function discussCommand(parsed, deps = {}) {
       return;
     }
     default:
-      throw new Error(`unknown discuss action "${action2}". Run "odla-ai help".`);
+      rejectWord(["discuss"], action2);
   }
 }
 var ALLOWED;
@@ -12734,6 +13030,7 @@ var init_discuss_command = __esm({
     init_discuss_actions();
     init_discuss_watch();
     init_token();
+    init_surface();
     ALLOWED = [
       "config",
       "token",
@@ -13578,7 +13875,7 @@ function writePmProjectContext(rootDir, value2) {
   });
 }
 function adoptLegacySelection(rootDir) {
-  const legacy = (0, import_node_path18.resolve)(rootDir, ".odla", "pm-project.local.json");
+  const legacy = (0, import_node_path19.resolve)(rootDir, ".odla", "pm-project.local.json");
   if (!(0, import_node_fs19.existsSync)(legacy)) return;
   const previous = readJsonFile(legacy);
   (0, import_node_fs19.rmSync)(legacy, { force: true });
@@ -13593,13 +13890,13 @@ function readSelections() {
 function isSelection(value2) {
   return !!value2 && typeof value2.appId === "string" && typeof value2.projectId === "string" && typeof value2.selectedAt === "string";
 }
-var import_node_fs19, import_node_path18, pmProjectContextFile;
+var import_node_fs19, import_node_path19, pmProjectContextFile;
 var init_pm_project_context = __esm({
   "src/pm-project-context.ts"() {
     "use strict";
     init_cjs_shims();
     import_node_fs19 = require("fs");
-    import_node_path18 = require("path");
+    import_node_path19 = require("path");
     init_local();
     init_odla_home();
     pmProjectContextFile = () => pmContextFile();
@@ -13722,7 +14019,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);
@@ -13753,10 +14050,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`);
@@ -13809,6 +14106,7 @@ var init_pm_command = __esm({
     init_pm_watch();
     init_pm_project_actions();
     init_pm_project_context();
+    init_surface();
     ALIASES = {
       goal: "goal",
       conformance: "goal",
@@ -13918,12 +14216,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(
@@ -13989,6 +14282,7 @@ var init_platform_command = __esm({
     init_argv();
     init_operator_context();
     init_platform_output();
+    init_surface();
   }
 });
 
@@ -14282,9 +14576,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
@@ -14420,6 +14712,7 @@ var init_o11y_command = __esm({
     init_o11y_verdict();
     init_o11y_output();
     init_token();
+    init_surface();
   }
 });
 
@@ -14540,9 +14833,7 @@ var init_monitoring_config = __esm({
 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
@@ -14696,6 +14987,7 @@ var init_monitor_command = __esm({
     init_monitoring_config();
     init_operator_context();
     init_token();
+    init_surface();
     OPTIONS = [
       "config",
       "context",
@@ -15182,7 +15474,7 @@ async function provision(options) {
       await provisionIntegrationSeeds(doFetch, cfg.dbEndpoint, tenantId, dbKey, database.integrations, env, out);
     }
     if (cfg.services.includes("ai") && cfg.ai?.provider && cfg.ai.keyEnv) {
-      const key = import_node_process17.default.env[cfg.ai.keyEnv];
+      const key = import_node_process18.default.env[cfg.ai.keyEnv];
       if (key) {
         const secretName = cfg.ai.secretName ?? defaultSecretName(cfg.ai.provider);
         await (0, import_ai6.putSecret)({ endpoint: cfg.dbEndpoint, token, fetch: doFetch }, tenantId, secretName, key);
@@ -15221,14 +15513,14 @@ async function provision(options) {
     }
   }
 }
-var import_apps13, import_ai6, import_node_process17;
+var import_apps13, import_ai6, import_node_process18;
 var init_provision = __esm({
   "src/provision.ts"() {
     "use strict";
     init_cjs_shims();
     import_apps13 = require("@odla-ai/apps");
     import_ai6 = require("@odla-ai/ai");
-    import_node_process17 = __toESM(require("process"), 1);
+    import_node_process18 = __toESM(require("process"), 1);
     init_config();
     init_calendar();
     init_calendar_errors();
@@ -15245,186 +15537,9 @@ var init_provision = __esm({
   }
 });
 
-// src/surface.ts
-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;
-}
-var PM_ACTIONS, PM_TASK_ACTIONS, PM_ENTITIES, COMMAND_SURFACE;
-var init_surface = __esm({
-  "src/surface.ts"() {
-    "use strict";
-    init_cjs_shims();
-    PM_ACTIONS = {
-      list: {},
-      add: {},
-      create: {},
-      get: {},
-      set: {},
-      update: {},
-      status: {},
-      move: {},
-      done: {},
-      comment: {},
-      comments: {},
-      ref: {},
-      rm: {},
-      delete: {}
-    };
-    PM_TASK_ACTIONS = {
-      ...PM_ACTIONS,
-      ready: {},
-      claim: {},
-      release: {}
-    };
-    PM_ENTITIES = {
-      ...Object.fromEntries(
-        ["goal", "conformance", "decision", "bug"].map((entity) => [entity, PM_ACTIONS])
-      ),
-      task: PM_TASK_ACTIONS,
-      kanban: PM_TASK_ACTIONS
-    };
-    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: {}
-    };
-  }
-});
-
 // src/record.ts
 function recordInvocation(parsed) {
-  const file = import_node_process18.default.env.ODLA_CLI_RECORD;
+  const file = import_node_process19.default.env.ODLA_CLI_RECORD;
   if (!file) return;
   try {
     const entry = {
@@ -15437,13 +15552,13 @@ function recordInvocation(parsed) {
   } catch {
   }
 }
-var import_node_fs20, import_node_process18;
+var import_node_fs20, import_node_process19;
 var init_record = __esm({
   "src/record.ts"() {
     "use strict";
     init_cjs_shims();
     import_node_fs20 = require("fs");
-    import_node_process18 = __toESM(require("process"), 1);
+    import_node_process19 = __toESM(require("process"), 1);
     init_surface();
   }
 });
@@ -15529,6 +15644,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));
@@ -15536,7 +15652,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();
@@ -15567,7 +15683,7 @@ async function enroll(parsed, deps, cfg, doFetch, out, json) {
     headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
     body: JSON.stringify({
       name,
-      platform: import_node_process19.default.platform,
+      platform: import_node_process20.default.platform,
       appIds: apps,
       ...capabilities ? { capabilities } : {},
       ...scopes ? { scopes } : {},
@@ -15579,7 +15695,7 @@ async function enroll(parsed, deps, cfg, doFetch, out, json) {
     throw new Error(`device enroll failed: ${body.error?.message ?? `registry returned ${response2.status}`} (${response2.status})`);
   }
   const path = deviceCredentialPath();
-  (0, import_node_fs21.mkdirSync)((0, import_node_path19.dirname)(path), { recursive: true });
+  (0, import_node_fs21.mkdirSync)((0, import_node_path20.dirname)(path), { recursive: true });
   (0, import_node_fs21.writeFileSync)(path, JSON.stringify({
     token: body.token,
     platform: cfg.platformUrl.replace(/\/$/, ""),
@@ -15686,9 +15802,9 @@ async function scopedToken2(parsed, deps, cfg, doFetch, out, label, scope = "app
   });
 }
 function defaultDeviceName() {
-  return `${import_node_process19.default.env.HOSTNAME ?? import_node_process19.default.env.HOST ?? "machine"}-${import_node_process19.default.platform}`;
+  return `${import_node_process20.default.env.HOSTNAME ?? import_node_process20.default.env.HOST ?? "machine"}-${import_node_process20.default.platform}`;
 }
-var import_db4, import_node_fs21, import_node_path19, import_node_process19;
+var import_db4, import_node_fs21, import_node_path20, import_node_process20;
 var init_device_command = __esm({
   "src/device-command.ts"() {
     "use strict";
@@ -15699,13 +15815,14 @@ var init_device_command = __esm({
     init_auth_guidance();
     init_advisory_output();
     import_node_fs21 = require("fs");
-    import_node_path19 = require("path");
-    import_node_process19 = __toESM(require("process"), 1);
+    import_node_path20 = require("path");
+    import_node_process20 = __toESM(require("process"), 1);
     init_argv();
     init_admin_ai_auth();
     init_device_session();
     init_config();
     init_operator_context();
+    init_surface();
   }
 });
 
@@ -15886,8 +16003,8 @@ function readRunbookDir(dir) {
   const files = (0, import_node_fs23.readdirSync)(dir).filter((f) => f.endsWith(".md")).sort();
   if (!files.length) throw new Error(`no .md files in ${dir}`);
   return files.map((file) => {
-    const slug = (0, import_node_path20.basename)(file, ".md");
-    const parsed = parseRunbook((0, import_node_fs23.readFileSync)((0, import_node_path20.join)(dir, file), "utf8"), slug);
+    const slug = (0, import_node_path21.basename)(file, ".md");
+    const parsed = parseRunbook((0, import_node_fs23.readFileSync)((0, import_node_path21.join)(dir, file), "utf8"), slug);
     return { file, slug, ...parsed, words: parsed.body.split(/\s+/).filter(Boolean).length };
   });
 }
@@ -15952,13 +16069,13 @@ async function upsert(ctx, r, visibility) {
   );
   return "updated";
 }
-var import_node_fs23, import_node_path20;
+var import_node_fs23, import_node_path21;
 var init_runbook_import = __esm({
   "src/runbook-import.ts"() {
     "use strict";
     init_cjs_shims();
     import_node_fs23 = require("fs");
-    import_node_path20 = require("path");
+    import_node_path21 = require("path");
     init_runbook_actions();
   }
 });
@@ -16091,7 +16208,7 @@ var init_runbook_impact_scan = __esm({
 
 // src/runbook-impact.ts
 function gitRunner(cwd) {
-  return (args) => (0, import_node_child_process6.execFileSync)("git", args, { cwd, encoding: "utf8", maxBuffer: 64 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
+  return (args) => (0, import_node_child_process7.execFileSync)("git", args, { cwd, encoding: "utf8", maxBuffer: 64 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
 }
 function collectDiff(runGit, base, read3) {
   let merged = "";
@@ -16136,7 +16253,7 @@ ${body.split("\n").map((line2) => `+${line2}`).join("\n")}
 }
 function manifestLabeller(root) {
   return (workspace) => {
-    const manifest = (0, import_node_path21.join)(root, workspace, "package.json");
+    const manifest = (0, import_node_path22.join)(root, workspace, "package.json");
     if (!(0, import_node_fs24.existsSync)(manifest)) return void 0;
     try {
       const name = JSON.parse((0, import_node_fs24.readFileSync)(manifest, "utf8")).name;
@@ -16205,7 +16322,7 @@ function report4(ctx, impacts) {
 async function runbookImpact(ctx, options, deps = {}) {
   const cwd = deps.cwd ?? process.cwd();
   const runGit = deps.runGit ?? gitRunner(cwd);
-  const read3 = deps.readRepoFile ?? ((path) => (0, import_node_fs24.readFileSync)((0, import_node_path21.join)(cwd, path), "utf8"));
+  const read3 = deps.readRepoFile ?? ((path) => (0, import_node_fs24.readFileSync)((0, import_node_path22.join)(cwd, path), "utf8"));
   const surfaces = changedSurfaces(collectDiff(runGit, options.base, read3), manifestLabeller(cwd));
   if (!surfaces.length) {
     return ctx.out.log(
@@ -16216,14 +16333,14 @@ async function runbookImpact(ctx, options, deps = {}) {
   if (ctx.json) return ctx.out.log(JSON.stringify({ base: options.base, impacts }, null, 2));
   report4(ctx, impacts);
 }
-var import_node_child_process6, import_node_fs24, import_node_path21, SOURCE3, editHint;
+var import_node_child_process7, import_node_fs24, import_node_path22, SOURCE3, editHint;
 var init_runbook_impact = __esm({
   "src/runbook-impact.ts"() {
     "use strict";
     init_cjs_shims();
-    import_node_child_process6 = require("child_process");
+    import_node_child_process7 = require("child_process");
     import_node_fs24 = require("fs");
-    import_node_path21 = require("path");
+    import_node_path22 = require("path");
     init_runbook_impact_scan();
     init_runbook_actions();
     SOURCE3 = /\.(ts|tsx|js|jsx|mts|cts)$/;
@@ -16363,7 +16480,7 @@ var init_runbook_search_command = __esm({
 });
 
 // src/runbook-editor.ts
-function resolveEditor(env = import_node_process20.default.env) {
+function resolveEditor(env = import_node_process21.default.env) {
   for (const name of EDITOR_ENV) {
     const value2 = env[name];
     if (value2 && value2.trim()) return value2.trim();
@@ -16372,13 +16489,13 @@ function resolveEditor(env = import_node_process20.default.env) {
 }
 function defaultRun(command, path) {
   const [bin, ...args] = command.split(/\s+/);
-  const result = (0, import_node_child_process7.spawnSync)(bin, [...args, path], { stdio: "inherit" });
+  const result = (0, import_node_child_process8.spawnSync)(bin, [...args, path], { stdio: "inherit" });
   if (result.error) throw new Error(`could not start editor "${command}": ${result.error.message}`);
   return result.status ?? 0;
 }
 function editText(initial, slug, deps = {}) {
-  const env = deps.env ?? import_node_process20.default.env;
-  const interactive = deps.interactive ?? (() => Boolean(import_node_process20.default.stdin.isTTY));
+  const env = deps.env ?? import_node_process21.default.env;
+  const interactive = deps.interactive ?? (() => Boolean(import_node_process21.default.stdin.isTTY));
   const editor = resolveEditor(env);
   if (!editor)
     throw new Error(
@@ -16386,8 +16503,8 @@ function editText(initial, slug, deps = {}) {
     );
   if (!interactive())
     throw new Error(`cannot open an editor without a terminal \u2014 pass --file <path> or --body "\u2026" instead`);
-  const dir = (0, import_node_fs25.mkdtempSync)((0, import_node_path22.join)((0, import_node_os6.tmpdir)(), "odla-runbook-"));
-  const file = (0, import_node_path22.join)(dir, `${slug}.md`);
+  const dir = (0, import_node_fs25.mkdtempSync)((0, import_node_path23.join)((0, import_node_os6.tmpdir)(), "odla-runbook-"));
+  const file = (0, import_node_path23.join)(dir, `${slug}.md`);
   try {
     (0, import_node_fs25.writeFileSync)(file, initial, { mode: 384 });
     const code = defaultRunOrInjected(deps)(editor, file);
@@ -16398,16 +16515,16 @@ function editText(initial, slug, deps = {}) {
     (0, import_node_fs25.rmSync)(dir, { recursive: true, force: true });
   }
 }
-var import_node_child_process7, import_node_fs25, import_node_os6, import_node_path22, import_node_process20, EDITOR_ENV, defaultRunOrInjected;
+var import_node_child_process8, import_node_fs25, import_node_os6, import_node_path23, import_node_process21, EDITOR_ENV, defaultRunOrInjected;
 var init_runbook_editor = __esm({
   "src/runbook-editor.ts"() {
     "use strict";
     init_cjs_shims();
-    import_node_child_process7 = require("child_process");
+    import_node_child_process8 = require("child_process");
     import_node_fs25 = require("fs");
     import_node_os6 = require("os");
-    import_node_path22 = require("path");
-    import_node_process20 = __toESM(require("process"), 1);
+    import_node_path23 = require("path");
+    import_node_process21 = __toESM(require("process"), 1);
     EDITOR_ENV = ["ODLA_EDITOR", "VISUAL", "EDITOR"];
     defaultRunOrInjected = (deps) => deps.run ?? defaultRun;
   }
@@ -16494,6 +16611,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) {
@@ -16583,7 +16701,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);
   }
 }
 var ALLOWED2, WRITES2;
@@ -16796,9 +16914,9 @@ async function runHostedSecurity(options) {
   const appId = selfAudit ? "odla-ai" : cfg.app.id;
   const env = selfAudit ? "prod" : selectEnv(options.env, cfg.envs, cfg.configPath, cfg.rootDir);
   const platform = options.platform ?? cfg?.platformUrl ?? "https://odla.ai";
-  const target = (0, import_node_path23.resolve)(options.target ?? cfg?.rootDir ?? ".");
-  const output = (0, import_node_path23.resolve)(options.out ?? (0, import_node_path23.resolve)(target, ".odla/security/hosted"));
-  const outputRelative = (0, import_node_path23.relative)(target, output).split(import_node_path23.sep).join("/");
+  const target = (0, import_node_path24.resolve)(options.target ?? cfg?.rootDir ?? ".");
+  const output = (0, import_node_path24.resolve)(options.out ?? (0, import_node_path24.resolve)(target, ".odla/security/hosted"));
+  const outputRelative = (0, import_node_path24.relative)(target, output).split(import_node_path24.sep).join("/");
   if (!outputRelative) throw new Error("Hosted security output cannot be the repository root");
   const profile = profileFor(options.profile ?? "odla", options.maxHuntTasks ?? 12);
   const tokenRequest = {
@@ -16810,7 +16928,7 @@ async function runHostedSecurity(options) {
   };
   const token = await injectedToken(options, tokenRequest);
   const snapshot = await (0, import_node3.snapshotDirectory)(target, {
-    exclude: !outputRelative.startsWith("../") && !(0, import_node_path23.isAbsolute)(outputRelative) ? [outputRelative] : []
+    exclude: !outputRelative.startsWith("../") && !(0, import_node_path24.isAbsolute)(outputRelative) ? [outputRelative] : []
   });
   const hosted = await (0, import_security.createPlatformSecurityReasoners)({
     platform,
@@ -16828,7 +16946,7 @@ async function runHostedSecurity(options) {
   });
   const harness = (0, import_security.createSecurityHarness)({
     profile,
-    store: new import_node3.FileRunStore((0, import_node_path23.resolve)(output, "state")),
+    store: new import_node3.FileRunStore((0, import_node_path24.resolve)(output, "state")),
     discoveryReasoner: hosted.discoveryReasoner,
     validationReasoner: hosted.validationReasoner,
     policy: {
@@ -16852,7 +16970,7 @@ async function runHostedSecurity(options) {
 function selectEnv(requested, declared, configPath, rootDir) {
   const env = requested ?? (declared.includes("dev") ? "dev" : declared[0]);
   if (!env || !declared.includes(env)) {
-    const shown = (0, import_node_path23.relative)(rootDir, configPath) || configPath;
+    const shown = (0, import_node_path24.relative)(rootDir, configPath) || configPath;
     throw new Error(`env "${env ?? ""}" is not declared in ${shown}`);
   }
   return env;
@@ -16881,17 +16999,17 @@ function printSummary(out, appId, env, run, report5, output) {
   out.log(`  coverage: ${report5.coverageStatus} ${complete}/${report5.coverage.length} blocked=${report5.metrics.blockedCells} shallow=${report5.metrics.shallowCells} unscheduled=${report5.metrics.unscheduledCells} budget_exhausted=${report5.metrics.budgetExhaustedCells}`);
   if (report5.callBudget) out.log(`  calls: discovery=${formatBudget(report5.callBudget.discovery)} validation=${formatBudget(report5.callBudget.validation)}`);
   out.log(`  findings: confirmed=${report5.metrics.confirmed} needs_reproduction=${report5.metrics.needsReproduction} candidates=${report5.metrics.candidates}`);
-  out.log(`  report: ${(0, import_node_path23.resolve)(output, "REPORT.md")}`);
+  out.log(`  report: ${(0, import_node_path24.resolve)(output, "REPORT.md")}`);
 }
 function formatBudget(usage) {
   return usage ? `${usage.usedCalls}/${usage.maxCalls} skipped=${usage.skippedCalls}` : "caller-managed";
 }
-var import_node_path23, import_security, import_node3;
+var import_node_path24, import_security, import_node3;
 var init_security = __esm({
   "src/security.ts"() {
     "use strict";
     init_cjs_shims();
-    import_node_path23 = require("path");
+    import_node_path24 = require("path");
     import_security = require("@odla-ai/security");
     import_node3 = require("@odla-ai/security/node");
     init_config();
@@ -17292,9 +17410,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);
@@ -17311,9 +17427,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",
@@ -17369,6 +17483,7 @@ var init_security_command = __esm({
     init_security_run_command();
     init_security_hosted();
     init_human_session();
+    init_surface();
   }
 });
 
@@ -17393,6 +17508,11 @@ async function runCli(argv2 = process.argv.slice(2), dependencies = {}) {
     throw error;
   } finally {
     renderAdvisories(out, advisories);
+    try {
+      const behind = updateNotice();
+      if (behind) out.error(behind);
+    } catch {
+    }
   }
 }
 async function dispatchCli(argv2, dependencies) {
@@ -17473,6 +17593,7 @@ async function dispatchCli(argv2, 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,
@@ -17501,7 +17622,7 @@ async function dispatchCli(argv2, 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, [
@@ -17545,7 +17666,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`);
@@ -17599,6 +17720,8 @@ var init_cli = __esm({
     init_runbook_command();
     init_security_command();
     init_whoami_command();
+    init_surface();
+    init_update_notice();
     init_exit_code();
   }
 });
@@ -17608,16 +17731,17 @@ init_cjs_shims();
 
 // src/cli-update.ts
 init_cjs_shims();
-var import_node_fs2 = require("fs");
 init_runbook_requires();
+init_update_notice();
 init_version();
 var DEFAULT_REGISTRY_URL = "https://registry.npmjs.org/@odla-ai%2fcli/latest";
-var VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+var VERSION2 = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
 async function requireCurrentCliForProvision(argv2, options = {}) {
   if (argv2[0] !== "provision" || argv2.includes("--dry-run")) return;
   const current = options.currentVersion ?? cliVersion();
-  if (!VERSION.test(current)) return;
+  if (!VERSION2.test(current)) return;
   const latest = await fetchLatestCliVersion(options);
+  if (latest) rememberLatest(latest);
   if (!latest || compareVersions(current, latest) >= 0) return;
   const entryPath = resolvedEntryPath(options.entryPath ?? process.argv[1]);
   const workspace = isWorkspaceCli(entryPath);
@@ -17646,25 +17770,19 @@ async function fetchLatestCliVersion(options) {
     );
     if (!response2.ok) return null;
     const body = await response2.json();
-    return typeof body.version === "string" && VERSION.test(body.version) ? body.version : null;
+    return typeof body.version === "string" && VERSION2.test(body.version) ? body.version : null;
   } catch {
     return null;
   } finally {
     clearTimeout(timeout);
   }
 }
-function resolvedEntryPath(entryPath) {
-  if (!entryPath) return "unknown executable";
+function rememberLatest(latest) {
   try {
-    return (0, import_node_fs2.realpathSync)(entryPath);
+    writeUpdateCache(updateCacheFile(), { latest, checkedAt: Date.now() });
   } catch {
-    return entryPath;
   }
 }
-function isWorkspaceCli(entryPath) {
-  const normalized = entryPath.replaceAll("\\", "/");
-  return normalized.includes("/packages/cli/dist/bin.") && !normalized.includes("/node_modules/");
-}
 function renderReleasedProvisionCommand(latest, argv2) {
   const safeArgs = [];
   for (let index = 0; index < argv2.length; index++) {
@@ -17692,8 +17810,9 @@ function shellQuote(value2) {
 // src/cli-runtime.ts
 init_cjs_shims();
 var import_node_module = require("module");
-var import_node_fs3 = require("fs");
-var import_node_path = require("path");
+var import_node_fs4 = require("fs");
+var import_node_path3 = require("path");
+init_update_notice();
 init_version();
 var EXACT_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
 var RUNTIME_MODULES = [
@@ -17752,26 +17871,26 @@ function installedRuntimeModules(entryPath) {
   }));
 }
 function findPackageManifest(fromPath, expectedName) {
-  let directory = (0, import_node_path.dirname)(resolvedEntryPath(fromPath));
-  const root = (0, import_node_path.parse)(directory).root;
+  let directory = (0, import_node_path3.dirname)(resolvedEntryPath(fromPath));
+  const root = (0, import_node_path3.parse)(directory).root;
   while (true) {
-    const path = (0, import_node_path.join)(directory, "package.json");
-    if ((0, import_node_fs3.existsSync)(path)) {
+    const path = (0, import_node_path3.join)(directory, "package.json");
+    if ((0, import_node_fs4.existsSync)(path)) {
       try {
-        const json = JSON.parse((0, import_node_fs3.readFileSync)(path, "utf8"));
+        const json = JSON.parse((0, import_node_fs4.readFileSync)(path, "utf8"));
         if (json?.name === expectedName && typeof json.version === "string") return { path, json };
       } catch {
       }
     }
     if (directory === root) return void 0;
-    directory = (0, import_node_path.dirname)(directory);
+    directory = (0, import_node_path3.dirname)(directory);
   }
 }
 function absoluteEntryPath(entryPath) {
-  const candidate = entryPath || (0, import_node_path.join)(process.cwd(), "odla-ai-cli.js");
-  const absolute = (0, import_node_path.isAbsolute)(candidate) ? candidate : (0, import_node_path.resolve)(candidate);
+  const candidate = entryPath || (0, import_node_path3.join)(process.cwd(), "odla-ai-cli.js");
+  const absolute = (0, import_node_path3.isAbsolute)(candidate) ? candidate : (0, import_node_path3.resolve)(candidate);
   try {
-    return (0, import_node_fs3.realpathSync)(absolute);
+    return (0, import_node_fs4.realpathSync)(absolute);
   } catch {
     return absolute;
   }