@swmansion/argent 0.18.1-next.2 → 0.18.1-next.21

package/dist/cli-cmds.mjs

@@ -5,7 +5,13 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __commonJS = (cb, mod) => function __require() {
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a2, b) => (typeof require !== "undefined" ? require : a2)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __commonJS = (cb, mod) => function __require2() {
   try {
     return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
   } catch (e) {
@@ -33,6 +39,325 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 
+// ../../node_modules/dotenv/lib/main.js
+var require_main = __commonJS({
+  "../../node_modules/dotenv/lib/main.js"(exports, module) {
+    var fs12 = __require("fs");
+    var path17 = __require("path");
+    var os3 = __require("os");
+    var crypto3 = __require("crypto");
+    var TIPS = [
+      "\u25C8 encrypted .env [www.dotenvx.com]",
+      "\u25C8 secrets for agents [www.dotenvx.com]",
+      "\u2301 auth for agents [www.vestauth.com]",
+      "\u2318 custom filepath { path: '/custom/path/.env' }",
+      "\u2318 enable debugging { debug: true }",
+      "\u2318 override existing { override: true }",
+      "\u2318 suppress logs { quiet: true }",
+      "\u2318 multiple files { path: ['.env.local', '.env'] }"
+    ];
+    function _getRandomTip() {
+      return TIPS[Math.floor(Math.random() * TIPS.length)];
+    }
+    function parseBoolean(value) {
+      if (typeof value === "string") {
+        return !["false", "0", "no", "off", ""].includes(value.toLowerCase());
+      }
+      return Boolean(value);
+    }
+    function supportsAnsi() {
+      return process.stdout.isTTY;
+    }
+    function dim(text2) {
+      return supportsAnsi() ? `\x1B[2m${text2}\x1B[0m` : text2;
+    }
+    var LINE = /(?:^|^)\s*(?:export\s+)?([\w.-]+)(?:\s*=\s*?|:\s+?)(\s*'(?:\\'|[^'])*'|\s*"(?:\\"|[^"])*"|\s*`(?:\\`|[^`])*`|[^#\r\n]+)?\s*(?:#.*)?(?:$|$)/mg;
+    function parse(src) {
+      const obj = {};
+      let lines = src.toString();
+      lines = lines.replace(/\r\n?/mg, "\n");
+      let match;
+      while ((match = LINE.exec(lines)) != null) {
+        const key = match[1];
+        let value = match[2] || "";
+        value = value.trim();
+        const maybeQuote = value[0];
+        value = value.replace(/^(['"`])([\s\S]*)\1$/mg, "$2");
+        if (maybeQuote === '"') {
+          value = value.replace(/\\n/g, "\n");
+          value = value.replace(/\\r/g, "\r");
+        }
+        obj[key] = value;
+      }
+      return obj;
+    }
+    function _parseVault(options) {
+      options = options || {};
+      const vaultPath = _vaultPath(options);
+      options.path = vaultPath;
+      const result = DotenvModule.configDotenv(options);
+      if (!result.parsed) {
+        const err = new Error(`MISSING_DATA: Cannot parse ${vaultPath} for an unknown reason`);
+        err.code = "MISSING_DATA";
+        throw err;
+      }
+      const keys = _dotenvKey(options).split(",");
+      const length = keys.length;
+      let decrypted;
+      for (let i2 = 0; i2 < length; i2++) {
+        try {
+          const key = keys[i2].trim();
+          const attrs = _instructions(result, key);
+          decrypted = DotenvModule.decrypt(attrs.ciphertext, attrs.key);
+          break;
+        } catch (error) {
+          if (i2 + 1 >= length) {
+            throw error;
+          }
+        }
+      }
+      return DotenvModule.parse(decrypted);
+    }
+    function _warn(message) {
+      console.error(`\u26A0 ${message}`);
+    }
+    function _debug(message) {
+      console.log(`\u2506 ${message}`);
+    }
+    function _log(message) {
+      console.log(`\u25C7 ${message}`);
+    }
+    function _dotenvKey(options) {
+      if (options && options.DOTENV_KEY && options.DOTENV_KEY.length > 0) {
+        return options.DOTENV_KEY;
+      }
+      if (process.env.DOTENV_KEY && process.env.DOTENV_KEY.length > 0) {
+        return process.env.DOTENV_KEY;
+      }
+      return "";
+    }
+    function _instructions(result, dotenvKey) {
+      let uri;
+      try {
+        uri = new URL(dotenvKey);
+      } catch (error) {
+        if (error.code === "ERR_INVALID_URL") {
+          const err = new Error("INVALID_DOTENV_KEY: Wrong format. Must be in valid uri format like dotenv://:key_1234@dotenvx.com/vault/.env.vault?environment=development");
+          err.code = "INVALID_DOTENV_KEY";
+          throw err;
+        }
+        throw error;
+      }
+      const key = uri.password;
+      if (!key) {
+        const err = new Error("INVALID_DOTENV_KEY: Missing key part");
+        err.code = "INVALID_DOTENV_KEY";
+        throw err;
+      }
+      const environment = uri.searchParams.get("environment");
+      if (!environment) {
+        const err = new Error("INVALID_DOTENV_KEY: Missing environment part");
+        err.code = "INVALID_DOTENV_KEY";
+        throw err;
+      }
+      const environmentKey = `DOTENV_VAULT_${environment.toUpperCase()}`;
+      const ciphertext = result.parsed[environmentKey];
+      if (!ciphertext) {
+        const err = new Error(`NOT_FOUND_DOTENV_ENVIRONMENT: Cannot locate environment ${environmentKey} in your .env.vault file.`);
+        err.code = "NOT_FOUND_DOTENV_ENVIRONMENT";
+        throw err;
+      }
+      return { ciphertext, key };
+    }
+    function _vaultPath(options) {
+      let possibleVaultPath = null;
+      if (options && options.path && options.path.length > 0) {
+        if (Array.isArray(options.path)) {
+          for (const filepath of options.path) {
+            if (fs12.existsSync(filepath)) {
+              possibleVaultPath = filepath.endsWith(".vault") ? filepath : `${filepath}.vault`;
+            }
+          }
+        } else {
+          possibleVaultPath = options.path.endsWith(".vault") ? options.path : `${options.path}.vault`;
+        }
+      } else {
+        possibleVaultPath = path17.resolve(process.cwd(), ".env.vault");
+      }
+      if (fs12.existsSync(possibleVaultPath)) {
+        return possibleVaultPath;
+      }
+      return null;
+    }
+    function _resolveHome(envPath) {
+      return envPath[0] === "~" ? path17.join(os3.homedir(), envPath.slice(1)) : envPath;
+    }
+    function _configVault(options) {
+      const debug = parseBoolean(process.env.DOTENV_CONFIG_DEBUG || options && options.debug);
+      const quiet = parseBoolean(process.env.DOTENV_CONFIG_QUIET || options && options.quiet);
+      if (debug || !quiet) {
+        _log("loading env from encrypted .env.vault");
+      }
+      const parsed = DotenvModule._parseVault(options);
+      let processEnv = process.env;
+      if (options && options.processEnv != null) {
+        processEnv = options.processEnv;
+      }
+      DotenvModule.populate(processEnv, parsed, options);
+      return { parsed };
+    }
+    function configDotenv(options) {
+      const dotenvPath = path17.resolve(process.cwd(), ".env");
+      let encoding = "utf8";
+      let processEnv = process.env;
+      if (options && options.processEnv != null) {
+        processEnv = options.processEnv;
+      }
+      let debug = parseBoolean(processEnv.DOTENV_CONFIG_DEBUG || options && options.debug);
+      let quiet = parseBoolean(processEnv.DOTENV_CONFIG_QUIET || options && options.quiet);
+      if (options && options.encoding) {
+        encoding = options.encoding;
+      } else {
+        if (debug) {
+          _debug("no encoding is specified (UTF-8 is used by default)");
+        }
+      }
+      let optionPaths = [dotenvPath];
+      if (options && options.path) {
+        if (!Array.isArray(options.path)) {
+          optionPaths = [_resolveHome(options.path)];
+        } else {
+          optionPaths = [];
+          for (const filepath of options.path) {
+            optionPaths.push(_resolveHome(filepath));
+          }
+        }
+      }
+      let lastError;
+      const parsedAll = {};
+      for (const path18 of optionPaths) {
+        try {
+          const parsed = DotenvModule.parse(fs12.readFileSync(path18, { encoding }));
+          DotenvModule.populate(parsedAll, parsed, options);
+        } catch (e) {
+          if (debug) {
+            _debug(`failed to load ${path18} ${e.message}`);
+          }
+          lastError = e;
+        }
+      }
+      const populated = DotenvModule.populate(processEnv, parsedAll, options);
+      debug = parseBoolean(processEnv.DOTENV_CONFIG_DEBUG || debug);
+      quiet = parseBoolean(processEnv.DOTENV_CONFIG_QUIET || quiet);
+      if (debug || !quiet) {
+        const keysCount = Object.keys(populated).length;
+        const shortPaths = [];
+        for (const filePath of optionPaths) {
+          try {
+            const relative4 = path17.relative(process.cwd(), filePath);
+            shortPaths.push(relative4);
+          } catch (e) {
+            if (debug) {
+              _debug(`failed to load ${filePath} ${e.message}`);
+            }
+            lastError = e;
+          }
+        }
+        _log(`injected env (${keysCount}) from ${shortPaths.join(",")} ${dim(`// tip: ${_getRandomTip()}`)}`);
+      }
+      if (lastError) {
+        return { parsed: parsedAll, error: lastError };
+      } else {
+        return { parsed: parsedAll };
+      }
+    }
+    function config2(options) {
+      if (_dotenvKey(options).length === 0) {
+        return DotenvModule.configDotenv(options);
+      }
+      const vaultPath = _vaultPath(options);
+      if (!vaultPath) {
+        _warn(`you set DOTENV_KEY but you are missing a .env.vault file at ${vaultPath}`);
+        return DotenvModule.configDotenv(options);
+      }
+      return DotenvModule._configVault(options);
+    }
+    function decrypt(encrypted, keyStr) {
+      const key = Buffer.from(keyStr.slice(-64), "hex");
+      let ciphertext = Buffer.from(encrypted, "base64");
+      const nonce = ciphertext.subarray(0, 12);
+      const authTag = ciphertext.subarray(-16);
+      ciphertext = ciphertext.subarray(12, -16);
+      try {
+        const aesgcm = crypto3.createDecipheriv("aes-256-gcm", key, nonce);
+        aesgcm.setAuthTag(authTag);
+        return `${aesgcm.update(ciphertext)}${aesgcm.final()}`;
+      } catch (error) {
+        const isRange = error instanceof RangeError;
+        const invalidKeyLength = error.message === "Invalid key length";
+        const decryptionFailed = error.message === "Unsupported state or unable to authenticate data";
+        if (isRange || invalidKeyLength) {
+          const err = new Error("INVALID_DOTENV_KEY: It must be 64 characters long (or more)");
+          err.code = "INVALID_DOTENV_KEY";
+          throw err;
+        } else if (decryptionFailed) {
+          const err = new Error("DECRYPTION_FAILED: Please check your DOTENV_KEY");
+          err.code = "DECRYPTION_FAILED";
+          throw err;
+        } else {
+          throw error;
+        }
+      }
+    }
+    function populate(processEnv, parsed, options = {}) {
+      const debug = Boolean(options && options.debug);
+      const override = Boolean(options && options.override);
+      const populated = {};
+      if (typeof parsed !== "object") {
+        const err = new Error("OBJECT_REQUIRED: Please check the processEnv argument being passed to populate");
+        err.code = "OBJECT_REQUIRED";
+        throw err;
+      }
+      for (const key of Object.keys(parsed)) {
+        if (Object.prototype.hasOwnProperty.call(processEnv, key)) {
+          if (override === true) {
+            processEnv[key] = parsed[key];
+            populated[key] = parsed[key];
+          }
+          if (debug) {
+            if (override === true) {
+              _debug(`"${key}" is already defined and WAS overwritten`);
+            } else {
+              _debug(`"${key}" is already defined and was NOT overwritten`);
+            }
+          }
+        } else {
+          processEnv[key] = parsed[key];
+          populated[key] = parsed[key];
+        }
+      }
+      return populated;
+    }
+    var DotenvModule = {
+      configDotenv,
+      _configVault,
+      _parseVault,
+      config: config2,
+      decrypt,
+      parse,
+      populate
+    };
+    module.exports.configDotenv = DotenvModule.configDotenv;
+    module.exports._configVault = DotenvModule._configVault;
+    module.exports._parseVault = DotenvModule._parseVault;
+    module.exports.config = DotenvModule.config;
+    module.exports.decrypt = DotenvModule.decrypt;
+    module.exports.parse = DotenvModule.parse;
+    module.exports.populate = DotenvModule.populate;
+    module.exports = DotenvModule;
+  }
+});
+
 // ../../node_modules/picocolors/picocolors.js
 var require_picocolors = __commonJS({
   "../../node_modules/picocolors/picocolors.js"(exports, module) {
@@ -162,8 +487,8 @@ var require_src = __commonJS({
 });
 
 // ../argent-cli/src/run.ts
-import * as fs8 from "node:fs";
-import * as path11 from "node:path";
+import * as fs9 from "node:fs";
+import * as path12 from "node:path";
 
 // ../argent-tools-client/src/launcher.ts
 import * as net from "node:net";
@@ -204,7 +529,7 @@ function generateAuthToken() {
   return generateToken();
 }
 function findFreePort() {
-  return new Promise((resolve9, reject) => {
+  return new Promise((resolve10, reject) => {
     const srv = net.createServer();
     srv.listen(0, "127.0.0.1", () => {
       const addr = srv.address();
@@ -215,7 +540,7 @@ function findFreePort() {
       const port = addr.port;
       srv.close((err) => {
         if (err) reject(err);
-        else resolve9(port);
+        else resolve10(port);
       });
     });
     srv.on("error", reject);
@@ -316,7 +641,7 @@ function killSpawnedChild(child, pid) {
   }
 }
 function spawnToolsServer(paths, port, options = {}) {
-  return new Promise((resolve9, reject) => {
+  return new Promise((resolve10, reject) => {
     let logFd;
     try {
       fs.mkdirSync(STATE_DIR, { recursive: true });
@@ -353,7 +678,7 @@ function spawnToolsServer(paths, port, options = {}) {
         rl.close();
         child.stdout?.resume();
         child.stdout?.unref?.();
-        settle(() => resolve9({ port: actualPort, pid }));
+        settle(() => resolve10({ port: actualPort, pid }));
       }
     });
     child.on("error", (err) => {
@@ -742,8 +1067,8 @@ function parseLinkTarget(input) {
   const host = u3.hostname.startsWith("[") ? u3.hostname.slice(1, -1) : u3.hostname;
   if (!host) throw new Error(`URL "${input}" is missing a host.`);
   const port = u3.port ? Number(u3.port) : u3.protocol === "https:" ? 443 : 80;
-  const path16 = u3.pathname === "/" ? "" : u3.pathname.replace(/\/+$/, "");
-  const url = `${u3.protocol}//${u3.host}${path16}`;
+  const path17 = u3.pathname === "/" ? "" : u3.pathname.replace(/\/+$/, "");
+  const url = `${u3.protocol}//${u3.host}${path17}`;
   const token = u3.username ? decodeURIComponent(u3.username) : void 0;
   return { url, host, port, ...token ? { token } : {} };
 }
@@ -879,9 +1204,9 @@ async function tarball(sourcePath) {
   return tarPath;
 }
 function sha256File(filePath) {
-  return new Promise((resolve9, reject) => {
+  return new Promise((resolve10, reject) => {
     const hash = createHash2("sha256");
-    createReadStream(filePath).on("data", (chunk) => hash.update(chunk)).on("end", () => resolve9(hash.digest("hex"))).on("error", reject);
+    createReadStream(filePath).on("data", (chunk) => hash.update(chunk)).on("end", () => resolve10(hash.digest("hex"))).on("error", reject);
   });
 }
 async function uploadTar(tarPath, endpoint) {
@@ -1103,7 +1428,7 @@ function createToolsClient(options = {}) {
 import { copyFile, mkdir as mkdir4, readFile as readFile4, realpath, rm as rm3, stat as stat2, writeFile as writeFile4 } from "node:fs/promises";
 import { constants as fsConstants } from "node:fs";
 import { tmpdir as tmpdir2 } from "node:os";
-import { basename as basename3, dirname as dirname5, extname, isAbsolute as isAbsolute3, join as join8, normalize, resolve as resolve5, sep as sep2 } from "node:path";
+import { basename as basename3, dirname as dirname5, extname, isAbsolute as isAbsolute3, join as join9, normalize, resolve as resolve6, sep as sep2 } from "node:path";
 import { createHash as createHash3 } from "node:crypto";
 
 // ../configuration-core/src/flags.ts
@@ -1304,15 +1629,20 @@ function setAtPath(obj, dottedKey, value) {
 }
 function deleteAtPath(obj, dottedKey) {
   const parts = splitKey(dottedKey);
-  let cur = obj;
+  const chain = [obj];
   for (let i2 = 0; i2 < parts.length - 1; i2++) {
-    const next = cur[parts[i2]];
+    const next = chain[i2][parts[i2]];
     if (!isPlainObject(next)) return false;
-    cur = next;
+    chain.push(next);
   }
+  const parent = chain[parts.length - 1];
   const leaf = parts[parts.length - 1];
-  if (!Object.hasOwn(cur, leaf)) return false;
-  delete cur[leaf];
+  if (!Object.hasOwn(parent, leaf)) return false;
+  delete parent[leaf];
+  for (let i2 = chain.length - 1; i2 >= 1; i2--) {
+    if (Object.keys(chain[i2]).length > 0) break;
+    delete chain[i2 - 1][parts[i2 - 1]];
+  }
   return true;
 }
 var LOCK_STALE_MS2 = 1e4;
@@ -1387,6 +1717,97 @@ function updateConfig(mutate, scope = "global", options = {}) {
   }
 }
 
+// ../configuration-core/src/secrets.ts
+var import_dotenv = __toESM(require_main(), 1);
+import * as fs4 from "node:fs";
+import * as path7 from "node:path";
+var SECRET_ENV_PREFIX = "ARGENT_SECRET_";
+var SECRETS_FILE_NAME = "secrets.env";
+var SHARED_ENV_FILES = [".env.local", ".env"];
+var SECRET_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function envSource(env) {
+  const values = /* @__PURE__ */ new Map();
+  for (const [key, value] of Object.entries(env)) {
+    if (value === void 0 || !key.startsWith(SECRET_ENV_PREFIX)) continue;
+    const name = key.slice(SECRET_ENV_PREFIX.length);
+    if (SECRET_NAME_RE.test(name)) values.set(name, value);
+  }
+  return {
+    label: `environment (${SECRET_ENV_PREFIX}*)`,
+    kind: "env",
+    present: true,
+    names: [...values.keys()].sort(),
+    values
+  };
+}
+function fileSource(filePath, exposure) {
+  const label = filePath;
+  const absent = {
+    label,
+    kind: "file",
+    present: false,
+    names: [],
+    values: /* @__PURE__ */ new Map()
+  };
+  if (!fs4.statSync(filePath, { throwIfNoEntry: false })) return absent;
+  let content;
+  try {
+    content = fs4.readFileSync(filePath, "utf8");
+  } catch {
+    return absent;
+  }
+  const values = /* @__PURE__ */ new Map();
+  let skippedUnprefixed = false;
+  for (const [key, value] of Object.entries((0, import_dotenv.parse)(content))) {
+    const prefixed = key.startsWith(SECRET_ENV_PREFIX);
+    if (exposure === "shared" && !prefixed) {
+      skippedUnprefixed = true;
+      continue;
+    }
+    const name = prefixed ? key.slice(SECRET_ENV_PREFIX.length) : key;
+    if (SECRET_NAME_RE.test(name)) values.set(name, value);
+  }
+  return {
+    label,
+    kind: "file",
+    present: true,
+    names: [...values.keys()].sort(),
+    values,
+    ...values.size === 0 && skippedUnprefixed ? { needsPrefix: true } : {}
+  };
+}
+function secretSources(options = {}) {
+  const sources = [envSource(options.env ?? process.env)];
+  const projectRoot = findProjectRoot(options.cwd ?? process.cwd());
+  const filePaths = [];
+  if (projectRoot) {
+    filePaths.push({
+      path: path7.join(projectRoot, ".argent", SECRETS_FILE_NAME),
+      exposure: "dedicated"
+    });
+    for (const name of SHARED_ENV_FILES) {
+      filePaths.push({ path: path7.join(projectRoot, name), exposure: "shared" });
+    }
+  }
+  filePaths.push({
+    path: path7.join(resolveHomeDir(options), ".argent", SECRETS_FILE_NAME),
+    exposure: "dedicated"
+  });
+  const seen = /* @__PURE__ */ new Set();
+  for (const entry of filePaths) {
+    const resolved = path7.resolve(entry.path);
+    if (seen.has(resolved)) continue;
+    seen.add(resolved);
+    sources.push(fileSource(resolved, entry.exposure));
+  }
+  return sources;
+}
+function secretNames(sources) {
+  const names = /* @__PURE__ */ new Set();
+  for (const source of sources) for (const name of source.names) names.add(name);
+  return [...names].sort();
+}
+
 // ../configuration-core/src/merge.ts
 function mergeRestrictive(local, global2) {
   if (local === void 0) return global2;
@@ -1447,6 +1868,9 @@ function asString(raw) {
   const trimmed = raw.trim();
   return trimmed === "" ? void 0 : trimmed;
 }
+function asNumber(raw) {
+  return typeof raw === "number" && Number.isFinite(raw) ? raw : void 0;
+}
 function asStringArray(raw) {
   if (!Array.isArray(raw)) return void 0;
   const out = [];
@@ -1455,6 +1879,15 @@ function asStringArray(raw) {
   }
   return out;
 }
+var PARSER_EXPECTATIONS = /* @__PURE__ */ new Map([
+  [asBoolean, "a boolean (true or false)"],
+  [asString, "a non-empty string"],
+  [asNumber, "a number"],
+  [asStringArray, "an array of strings"]
+]);
+function describeExpectedValue(def) {
+  return def.expected ?? PARSER_EXPECTATIONS.get(def.parse);
+}
 var CONFIG_SCHEMA = [
   {
     key: "telemetry.enabled",
@@ -1512,7 +1945,7 @@ function getConfigDefinition(key, registry = CONFIG_SCHEMA) {
 }
 
 // ../configuration-core/src/config-access.ts
-import * as path7 from "node:path";
+import * as path8 from "node:path";
 function readScopeValue(def, scope, options) {
   if (!def.scopes.includes(scope)) return void 0;
   const raw = getAtPath(readConfigObject(scope, options), def.key);
@@ -1560,12 +1993,18 @@ var ConfigScopeError = class extends Error {
   allowed;
 };
 var ConfigValidationError = class extends Error {
-  constructor(key) {
-    super(`Invalid value for config key "${key}".`);
+  constructor(key, expected, example) {
+    super(
+      expected ? `Invalid value for config key "${key}": expected ${expected}.` : `Invalid value for config key "${key}".`
+    );
     this.key = key;
+    this.expected = expected;
+    this.example = example;
     this.name = "ConfigValidationError";
   }
   key;
+  expected;
+  example;
 };
 var ConfigManagedElsewhereError = class extends Error {
   constructor(key, command) {
@@ -1582,7 +2021,8 @@ function setConfigValue(key, rawValue, scope = "global", options = {}, registry
   if (def.manageCommand) throw new ConfigManagedElsewhereError(key, def.manageCommand);
   if (!def.scopes.includes(scope)) throw new ConfigScopeError(key, scope, def.scopes);
   const parsed = def.parse(rawValue);
-  if (parsed === void 0) throw new ConfigValidationError(key);
+  if (parsed === void 0)
+    throw new ConfigValidationError(def.key, describeExpectedValue(def), def.example);
   updateConfig((config2) => setAtPath(config2, key, parsed), scope, options);
   return parsed;
 }
@@ -1607,6 +2047,8 @@ function listConfig(options = {}, registry = CONFIG_SCHEMA) {
     description: def.description,
     scopes: def.scopes,
     ...def.manageCommand ? { manageCommand: def.manageCommand } : {},
+    ...describeExpectedValue(def) ? { expected: describeExpectedValue(def) } : {},
+    ...def.example ? { example: def.example } : {},
     effective: getConfigValue(def, options),
     project: readScopeValue(def, "project", options),
     global: readScopeValue(def, "global", options)
@@ -1654,12 +2096,12 @@ function projectSlug() {
   return `${name}-${hash}`;
 }
 function artifactsRoot() {
-  return process.env.ARGENT_ARTIFACTS_DIR ?? join8(tmpdir2(), "argent-artifacts");
+  return process.env.ARGENT_ARTIFACTS_DIR ?? join9(tmpdir2(), "argent-artifacts");
 }
 function artifactDir(deviceId) {
   const parts = [artifactsRoot(), projectSlug(), sessionId()];
   if (deviceId) parts.push(sanitizeSegment(deviceId));
-  return join8(...parts);
+  return join9(...parts);
 }
 function durableBaseDir() {
   const projectRoot = findProjectRoot(process.cwd());
@@ -1678,8 +2120,8 @@ function configuredRecordingsDir() {
   const trimmed = value.trim();
   if (trimmed === "") return null;
   const home = dirname5(argentHomeDir());
-  const expanded = trimmed === "~" ? home : trimmed.startsWith("~/") || trimmed.startsWith(`~${sep2}`) ? join8(home, trimmed.slice(2)) : trimmed;
-  return resolve5(durableBaseDir(), expanded);
+  const expanded = trimmed === "~" ? home : trimmed.startsWith("~/") || trimmed.startsWith(`~${sep2}`) ? join9(home, trimmed.slice(2)) : trimmed;
+  return resolve6(durableBaseDir(), expanded);
 }
 var MAX_DURABLE_BYTES = 2 * 1024 * 1024 * 1024;
 async function readCapped(res, cap) {
@@ -1712,10 +2154,10 @@ async function writeDurableUnique(dir, filename, write) {
   const stem = filename.slice(0, filename.length - ext.length);
   for (let i2 = 1; i2 <= 1e3; i2++) {
     const candidate = i2 === 1 ? filename : `${stem} (${i2})${ext}`;
-    const path16 = join8(dir, candidate);
+    const path17 = join9(dir, candidate);
     try {
-      await write(path16);
-      return path16;
+      await write(path17);
+      return path17;
     } catch (err) {
       if (err?.code === "EEXIST") continue;
       throw err;
@@ -1735,21 +2177,21 @@ function durableSaveTarget(handle) {
     if (configured) {
       return {
         dir: configured,
-        path: join8(configured, sanitizeSegment(handle.filename)),
+        path: join9(configured, sanitizeSegment(handle.filename)),
         base: configured,
         rel: ""
       };
     }
   }
   const base = durableBaseDir();
-  const dir = join8(base, rel);
-  return { dir, path: join8(dir, sanitizeSegment(handle.filename)), base, rel };
+  const dir = join9(base, rel);
+  return { dir, path: join9(dir, sanitizeSegment(handle.filename)), base, rel };
 }
 async function confineToRealBase(dir, base, rel) {
   try {
     const realDir = await realpath(dir);
     const realBase = await realpath(base);
-    return realDir === join8(realBase, rel);
+    return realDir === join9(realBase, rel);
   } catch {
     return false;
   }
@@ -1772,7 +2214,7 @@ async function resolveLocalFile(handle) {
   }
 }
 async function downloadAndExtractArchive(handle, data, dir) {
-  const tarball2 = join8(dir, `${sanitizeSegment(handle.filename)}.tar.gz`);
+  const tarball2 = join9(dir, `${sanitizeSegment(handle.filename)}.tar.gz`);
   try {
     await writeFile4(tarball2, data);
     return await safeExtractTarGz(tarball2, dir, handle.filename);
@@ -1862,7 +2304,7 @@ async function materializeArtifacts(result, ctx) {
           return await downloadAndExtractArchive(value, data, dir);
         }
         if (value.size > 0 && data.length !== value.size) return null;
-        const downloadedPath = join8(dir, sanitizeSegment(value.filename));
+        const downloadedPath = join9(dir, sanitizeSegment(value.filename));
         await writeFile4(downloadedPath, data);
         if (value.mimeType.startsWith("image/")) {
           images.push({ localPath: downloadedPath, data, mimeType: value.mimeType });
@@ -1922,8 +2364,8 @@ function createGetModuleFromFilename(basePath = process.argv[1] ? dirname6(proce
     return decodedFile;
   };
 }
-function normalizeWindowsPath(path16) {
-  return path16.replace(/^[A-Z]:/, "").replace(/\\/g, "/");
+function normalizeWindowsPath(path17) {
+  return path17.replace(/^[A-Z]:/, "").replace(/\\/g, "/");
 }
 
 // ../../node_modules/@posthog/core/dist/featureFlagUtils.mjs
@@ -4475,15 +4917,15 @@ async function addSourceContext(frames) {
   LRU_FILE_CONTENTS_CACHE.reduce();
   return frames;
 }
-function getContextLinesFromFile(path16, ranges, output) {
-  return new Promise((resolve9) => {
-    const stream = createReadStream2(path16);
+function getContextLinesFromFile(path17, ranges, output) {
+  return new Promise((resolve10) => {
+    const stream = createReadStream2(path17);
     const lineReaded = createInterface2({
       input: stream
     });
     function destroyStreamAndResolve() {
       stream.destroy();
-      resolve9();
+      resolve10();
     }
     let lineNumber = 0;
     let currentRangeIndex = 0;
@@ -4492,7 +4934,7 @@ function getContextLinesFromFile(path16, ranges, output) {
     let rangeStart = range[0];
     let rangeEnd = range[1];
     function onStreamError() {
-      LRU_FILE_CONTENTS_FS_READ_FAILED.set(path16, 1);
+      LRU_FILE_CONTENTS_FS_READ_FAILED.set(path17, 1);
       lineReaded.close();
       lineReaded.removeAllListeners();
       destroyStreamAndResolve();
@@ -4553,8 +4995,8 @@ function clearLineContext(frame) {
   delete frame.context_line;
   delete frame.post_context;
 }
-function shouldSkipContextLinesForFile(path16) {
-  return path16.startsWith("node:") || path16.endsWith(".min.js") || path16.endsWith(".min.cjs") || path16.endsWith(".min.mjs") || path16.startsWith("data:");
+function shouldSkipContextLinesForFile(path17) {
+  return path17.startsWith("node:") || path17.endsWith(".min.js") || path17.endsWith(".min.cjs") || path17.endsWith(".min.mjs") || path17.startsWith("data:");
 }
 function shouldSkipContextLinesForFrame(frame) {
   if (void 0 !== frame.lineno && frame.lineno > MAX_CONTEXTLINES_LINENO) return true;
@@ -5780,9 +6222,9 @@ var PostHogBackendClient = class extends PostHogCoreStateless {
     if (!waitUntil) return;
     if (this.disabled || this.optedOut) return;
     if (!this._waitUntilCycle) {
-      let resolve9;
+      let resolve10;
       const promise = new Promise((r2) => {
-        resolve9 = r2;
+        resolve10 = r2;
       });
       try {
         waitUntil(promise);
@@ -5790,7 +6232,7 @@ var PostHogBackendClient = class extends PostHogCoreStateless {
         return;
       }
       this._waitUntilCycle = {
-        resolve: resolve9,
+        resolve: resolve10,
         startedAt: Date.now(),
         timer: void 0
       };
@@ -5814,12 +6256,12 @@ var PostHogBackendClient = class extends PostHogCoreStateless {
     return cycle?.resolve;
   }
   async resolveWaitUntilFlush() {
-    const resolve9 = this._consumeWaitUntilCycle();
+    const resolve10 = this._consumeWaitUntilCycle();
     try {
       await super.flush();
     } catch {
     } finally {
-      resolve9?.();
+      resolve10?.();
     }
   }
   getPersistedProperty(key) {
@@ -5940,15 +6382,15 @@ var PostHogBackendClient = class extends PostHogCoreStateless {
   async waitForLocalEvaluationReady(timeoutMs = THIRTY_SECONDS) {
     if (this.isLocalEvaluationReady()) return true;
     if (void 0 === this.featureFlagsPoller) return false;
-    return new Promise((resolve9) => {
+    return new Promise((resolve10) => {
       const timeout = setTimeout(() => {
         cleanup();
-        resolve9(false);
+        resolve10(false);
       }, timeoutMs);
       const cleanup = this._events.on("localEvaluationFlagsLoaded", (count) => {
         clearTimeout(timeout);
         cleanup();
-        resolve9(count > 0);
+        resolve10(count > 0);
       });
     });
   }
@@ -6403,14 +6845,14 @@ var PostHogBackendClient = class extends PostHogCoreStateless {
     this.context?.enter(data, options);
   }
   async _shutdown(shutdownTimeoutMs) {
-    const resolve9 = this._consumeWaitUntilCycle();
+    const resolve10 = this._consumeWaitUntilCycle();
     await this.featureFlagsPoller?.stopPoller(shutdownTimeoutMs);
     this.errorTracking.shutdown();
     try {
       return await super._shutdown(shutdownTimeoutMs);
     } finally {
       this.distinctIdHasSentFlagCalls = {};
-      resolve9?.();
+      resolve10?.();
     }
   }
   async _requestRemoteConfigPayload(flagKey) {
@@ -6808,6 +7250,7 @@ var FAILURE_CODES = {
   CLI_RUN_FLAG_PARSE_FAILED: "CLI_RUN_FLAG_PARSE_FAILED",
   CLI_RUN_ARGS_NOT_OBJECT: "CLI_RUN_ARGS_NOT_OBJECT",
   CLI_RUN_ARGS_JSON_INVALID: "CLI_RUN_ARGS_JSON_INVALID",
+  CLI_RUN_INPUT_VALIDATION_FAILED: "CLI_RUN_INPUT_VALIDATION_FAILED",
   CLI_RUN_TOOL_CALL_FAILED: "CLI_RUN_TOOL_CALL_FAILED",
   CLI_RUN_SAVE_IMAGE_FAILED: "CLI_RUN_SAVE_IMAGE_FAILED",
   TOOL_CAPABILITY_UNSUPPORTED_OPERATION: "TOOL_CAPABILITY_UNSUPPORTED_OPERATION",
@@ -7009,6 +7452,7 @@ var FAILURE_CODES = {
   CHROMIUM_DEVICE_ID_INVALID: "CHROMIUM_DEVICE_ID_INVALID",
   CHROMIUM_PARAM_INVALID: "CHROMIUM_PARAM_INVALID",
   CHROMIUM_INPUT_INVALID: "CHROMIUM_INPUT_INVALID",
+  CHROMIUM_WINDOW_HIDDEN: "CHROMIUM_WINDOW_HIDDEN",
   CHROMIUM_VIEWPORT_READ_FAILED: "CHROMIUM_VIEWPORT_READ_FAILED",
   CHROMIUM_SCREENSHOT_FAILED: "CHROMIUM_SCREENSHOT_FAILED",
   CHROMIUM_STORAGE_EVAL_FAILED: "CHROMIUM_STORAGE_EVAL_FAILED",
@@ -7395,9 +7839,9 @@ function isReplitAgent(env) {
 }
 var DEVIN_MARKER_PATH = "/opt/.devin";
 var JULES_MARKER_PATH = "/opt/environment_summary.sh";
-function safeExists(fileExists, path16) {
+function safeExists(fileExists, path17) {
   try {
-    return fileExists(path16);
+    return fileExists(path17);
   } catch {
     return false;
   }
@@ -7818,7 +8262,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID2 = randomUUID5();
 function readCliVersion() {
   if (true) {
-    return "0.18.0";
+    return "0.18.1";
   }
   return "0.0.0";
 }
@@ -7852,16 +8296,16 @@ function getBaseProps(runtime) {
 
 // ../telemetry/src/identity.ts
 import * as crypto2 from "node:crypto";
-import * as fs4 from "node:fs";
-import * as path9 from "node:path";
+import * as fs5 from "node:fs";
+import * as path10 from "node:path";
 
 // ../telemetry/src/paths.ts
-import * as path8 from "node:path";
+import * as path9 from "node:path";
 function identityFilePath() {
-  return path8.join(argentHomeDir(), "telemetry-id");
+  return path9.join(argentHomeDir(), "telemetry-id");
 }
 function debugLogPath() {
-  return path8.join(argentHomeDir(), "telemetry-debug.log");
+  return path9.join(argentHomeDir(), "telemetry-debug.log");
 }
 
 // ../telemetry/src/identity.ts
@@ -7960,66 +8404,66 @@ function resolveFingerprintOnce(resolveFingerprint) {
 function isCorruptIdFile(filePath) {
   let isRegularFile;
   try {
-    isRegularFile = fs4.lstatSync(filePath).isFile();
+    isRegularFile = fs5.lstatSync(filePath).isFile();
   } catch {
     return false;
   }
   return isRegularFile && tryReadId(filePath) === null;
 }
 function writeIdFileAtomic(finalPath, id) {
-  fs4.mkdirSync(argentHomeDir(), { recursive: true });
+  fs5.mkdirSync(argentHomeDir(), { recursive: true });
   let occupant;
   try {
-    occupant = fs4.lstatSync(finalPath);
+    occupant = fs5.lstatSync(finalPath);
   } catch (err) {
     if (err.code !== "ENOENT") throw err;
   }
   if (occupant && !occupant.isFile()) {
     throw new Error("telemetry: refusing to replace a non-regular file at the identity path");
   }
-  const tmpPath = path9.join(
+  const tmpPath = path10.join(
     argentHomeDir(),
     `.telemetry-id.tmp.${process.pid}.${crypto2.randomUUID()}`
   );
-  const fd = fs4.openSync(tmpPath, "wx", 384);
+  const fd = fs5.openSync(tmpPath, "wx", 384);
   try {
     try {
-      fs4.writeSync(fd, id);
-      fs4.fsyncSync(fd);
+      fs5.writeSync(fd, id);
+      fs5.fsyncSync(fd);
     } finally {
-      fs4.closeSync(fd);
+      fs5.closeSync(fd);
     }
-    fs4.renameSync(tmpPath, finalPath);
+    fs5.renameSync(tmpPath, finalPath);
   } finally {
     try {
-      fs4.unlinkSync(tmpPath);
+      fs5.unlinkSync(tmpPath);
     } catch {
     }
   }
 }
 function mintRandomId(finalPath) {
-  fs4.mkdirSync(argentHomeDir(), { recursive: true });
+  fs5.mkdirSync(argentHomeDir(), { recursive: true });
   let value = crypto2.randomUUID();
   for (let attempt = 0; attempt < 3; attempt++) {
-    const tmpPath = path9.join(
+    const tmpPath = path10.join(
       argentHomeDir(),
       `.telemetry-id.tmp.${process.pid}.${crypto2.randomUUID()}`
     );
     let fd;
     try {
-      fd = fs4.openSync(tmpPath, "wx", 384);
+      fd = fs5.openSync(tmpPath, "wx", 384);
     } catch (err) {
       if (err.code === "EEXIST") continue;
       throw err;
     }
     try {
       try {
-        fs4.writeSync(fd, value);
-        fs4.fsyncSync(fd);
+        fs5.writeSync(fd, value);
+        fs5.fsyncSync(fd);
       } finally {
-        fs4.closeSync(fd);
+        fs5.closeSync(fd);
       }
-      fs4.linkSync(tmpPath, finalPath);
+      fs5.linkSync(tmpPath, finalPath);
       cached = { path: finalPath, id: value };
       return value;
     } catch (err) {
@@ -8038,7 +8482,7 @@ function mintRandomId(finalPath) {
       throw err;
     } finally {
       try {
-        fs4.unlinkSync(tmpPath);
+        fs5.unlinkSync(tmpPath);
       } catch {
       }
     }
@@ -8046,12 +8490,12 @@ function mintRandomId(finalPath) {
   throw new Error("telemetry: failed to create identity after retries");
 }
 function claimCorruptOccupant(finalPath) {
-  const claimed = path9.join(
+  const claimed = path10.join(
     argentHomeDir(),
     `.telemetry-id.corrupt.${process.pid}.${crypto2.randomUUID()}`
   );
   try {
-    fs4.renameSync(finalPath, claimed);
+    fs5.renameSync(finalPath, claimed);
   } catch {
     return null;
   }
@@ -8060,7 +8504,7 @@ function claimCorruptOccupant(finalPath) {
     grabbed = tryReadId(claimed);
   } finally {
     try {
-      fs4.unlinkSync(claimed);
+      fs5.unlinkSync(claimed);
     } catch {
     }
   }
@@ -8072,9 +8516,9 @@ function peekAnonId() {
 function tryReadId(filePath) {
   let raw;
   try {
-    const stats = fs4.lstatSync(filePath);
+    const stats = fs5.lstatSync(filePath);
     if (!stats.isFile()) return null;
-    raw = fs4.readFileSync(filePath, "utf8");
+    raw = fs5.readFileSync(filePath, "utf8");
   } catch (err) {
     if (err.code === "ENOENT") return null;
     return null;
@@ -8088,12 +8532,12 @@ function tryReadId(filePath) {
 import { execFileSync as execFileSync2, spawn as spawn2 } from "node:child_process";
 
 // ../native-devtools-ios/src/index.ts
-import * as path10 from "node:path";
-import * as fs5 from "node:fs";
-var DYLIB_DIR = process.env.ARGENT_NATIVE_DEVTOOLS_DIR ?? path10.join(__dirname, "..", "dylibs");
-var BIN_DIR = process.env.ARGENT_SIMULATOR_SERVER_DIR ?? path10.join(__dirname, "..", "bin");
-var DYLIB_TCP_DIR = process.env.ARGENT_NATIVE_DEVTOOLS_TCP_DIR ?? path10.join(DYLIB_DIR, "tcp");
-var DYLIB_TVOS_DIR = path10.join(DYLIB_DIR, "tvos");
+import * as path11 from "node:path";
+import * as fs6 from "node:fs";
+var DYLIB_DIR = process.env.ARGENT_NATIVE_DEVTOOLS_DIR ?? path11.join(__dirname, "..", "dylibs");
+var BIN_DIR = process.env.ARGENT_SIMULATOR_SERVER_DIR ?? path11.join(__dirname, "..", "bin");
+var DYLIB_TCP_DIR = process.env.ARGENT_NATIVE_DEVTOOLS_TCP_DIR ?? path11.join(DYLIB_DIR, "tcp");
+var DYLIB_TVOS_DIR = path11.join(DYLIB_DIR, "tvos");
 function hostPlatformKey() {
   if (process.platform === "linux" && process.arch === "arm64") {
     return "linux-arm64";
@@ -8104,14 +8548,14 @@ function simulatorServerBinaryName() {
   return process.platform === "win32" ? "simulator-server.exe" : "simulator-server";
 }
 function platformBinDir() {
-  return path10.join(BIN_DIR, hostPlatformKey());
+  return path11.join(BIN_DIR, hostPlatformKey());
 }
 function simulatorServerBinaryPath() {
   const binaryName = simulatorServerBinaryName();
-  const p = path10.join(platformBinDir(), binaryName);
-  if (!fs5.existsSync(p)) {
-    const flat = path10.join(BIN_DIR, binaryName);
-    const migrationHint = fs5.existsSync(flat) ? ` Found a binary at the old flat path ${flat}; move it to ${p} or update ARGENT_SIMULATOR_SERVER_DIR to point at the parent of the platform subdirectory.` : "";
+  const p = path11.join(platformBinDir(), binaryName);
+  if (!fs6.existsSync(p)) {
+    const flat = path11.join(BIN_DIR, binaryName);
+    const migrationHint = fs6.existsSync(flat) ? ` Found a binary at the old flat path ${flat}; move it to ${p} or update ARGENT_SIMULATOR_SERVER_DIR to point at the parent of the platform subdirectory.` : "";
     throw new Error(
       `simulator-server binary not found for platform "${hostPlatformKey()}" at ${p}. Supported hosts today: darwin, linux (x86_64 and arm64), win32.${migrationHint}`
     );
@@ -8144,12 +8588,12 @@ function resolveHostFingerprint() {
   }
 }
 function resolveHostFingerprintAsync() {
-  return new Promise((resolve9) => {
+  return new Promise((resolve10) => {
     let binary;
     try {
       binary = simulatorServerBinaryPath();
     } catch {
-      resolve9(null);
+      resolve10(null);
       return;
     }
     let settled = false;
@@ -8162,7 +8606,7 @@ function resolveHostFingerprintAsync() {
         child?.kill("SIGKILL");
       } catch {
       }
-      resolve9(value);
+      resolve10(value);
     };
     const watchdog = setTimeout(() => finish(null), FINGERPRINT_TIMEOUT_MS);
     watchdog.unref?.();
@@ -8195,13 +8639,13 @@ function resolveHostFingerprintAsync() {
 }
 
 // ../telemetry/src/consent.ts
-import * as fs6 from "node:fs";
+import * as fs7 from "node:fs";
 var cache = { current: null };
 var sessionOverride = null;
 function readConfigOverride() {
   let stats;
   try {
-    stats = fs6.lstatSync(configFilePath());
+    stats = fs7.lstatSync(configFilePath());
   } catch (err) {
     if (err.code === "ENOENT") {
       cache.current = { mtimeMs: null, fingerprint: null, enabledOverride: null };
@@ -8221,7 +8665,7 @@ function readConfigOverride() {
   }
   let parsedEnabled = null;
   try {
-    const raw = fs6.readFileSync(configFilePath(), "utf8");
+    const raw = fs7.readFileSync(configFilePath(), "utf8");
     const json = JSON.parse(raw);
     if (json && typeof json === "object") {
       const t2 = json.telemetry;
@@ -8282,7 +8726,7 @@ function writeConsentFlag(enabled) {
 }
 
 // ../telemetry/src/debug.ts
-import * as fs7 from "node:fs";
+import * as fs8 from "node:fs";
 function isDebugEnabled(env = process.env) {
   const v = env.ARGENT_TELEMETRY_DEBUG;
   if (!v) return false;
@@ -8309,8 +8753,8 @@ function emitDebugPayload(payload) {
   } catch {
   }
   try {
-    fs7.mkdirSync(argentHomeDir(), { recursive: true });
-    fs7.appendFileSync(debugLogPath(), line + "\n");
+    fs8.mkdirSync(argentHomeDir(), { recursive: true });
+    fs8.appendFileSync(debugLogPath(), line + "\n");
   } catch {
   }
 }
@@ -8404,7 +8848,7 @@ async function shutdown(timeoutMs = SHORT_FLUSH_TIMEOUT_MS) {
   try {
     await Promise.race([
       client2.shutdown(timeoutMs),
-      new Promise((resolve9) => setTimeout(resolve9, timeoutMs + 250).unref())
+      new Promise((resolve10) => setTimeout(resolve10, timeoutMs + 250).unref())
     ]);
   } catch (err) {
     emitDebugError("shutdown failed", err);
@@ -8424,7 +8868,7 @@ async function markDisabled() {
       try {
         await Promise.race([
           client2.shutdown(SHORT_FLUSH_TIMEOUT_MS),
-          new Promise((resolve9) => setTimeout(resolve9, SHORT_FLUSH_TIMEOUT_MS).unref())
+          new Promise((resolve10) => setTimeout(resolve10, SHORT_FLUSH_TIMEOUT_MS).unref())
         ]);
       } catch {
       }
@@ -8457,6 +8901,18 @@ var FlagParseException = class extends Error {
 function isScalarType(type) {
   return type === "string" || type === "number" || type === "integer" || type === "boolean";
 }
+function isJsonField(prop) {
+  return prop?.type === "object" || prop?.type === "array" && !isScalarType(prop.items?.type);
+}
+function flagNameFor(name, prop) {
+  return isJsonField(prop) ? `--${name}-json` : `--${name}`;
+}
+function booleanLiteral(raw) {
+  const value = raw.trim().toLowerCase();
+  if (value === "true" || value === "1") return true;
+  if (value === "false" || value === "0") return false;
+  return void 0;
+}
 function coerceScalar(raw, type, field) {
   if (type === "number") {
     if (raw.trim() === "")
@@ -8474,9 +8930,9 @@ function coerceScalar(raw, type, field) {
     return n2;
   }
   if (type === "boolean") {
-    if (raw === "true" || raw === "1") return true;
-    if (raw === "false" || raw === "0") return false;
-    throw new FlagParseException(`--${field} expected true/false, got "${raw}"`);
+    const value = booleanLiteral(raw);
+    if (value !== void 0) return value;
+    throw new FlagParseException(`--${field} expected true/false (or 1/0), got "${raw}"`);
   }
   return raw;
 }
@@ -8553,6 +9009,12 @@ function parseFlags(argv, schema) {
         if (inlineValue !== void 0) {
           throw new FlagParseException(`--no-${fieldName} does not take a value`);
         }
+        const following = i2 + 1 < argv.length ? booleanLiteral(argv[i2 + 1]) : void 0;
+        if (following !== void 0) {
+          throw new FlagParseException(
+            `--no-${fieldName} does not take a value; use --${fieldName} ${following}`
+          );
+        }
         args[fieldName] = false;
         continue;
       }
@@ -8561,6 +9023,12 @@ function parseFlags(argv, schema) {
     if (propSchema?.type === "boolean") {
       if (inlineValue !== void 0) {
         args[flag] = coerceScalar(inlineValue, "boolean", flag);
+        continue;
+      }
+      const next = i2 + 1 < argv.length ? booleanLiteral(argv[i2 + 1]) : void 0;
+      if (next !== void 0) {
+        args[flag] = next;
+        i2 += 1;
       } else {
         args[flag] = true;
       }
@@ -8618,14 +9086,19 @@ function formatSchemaUsage(schema) {
     const desc = prop.description ? `  ${prop.description}` : "";
     lines.push(`  ${flag}  ${typeLabel}${req}${desc}`);
   }
+  if (entries.some(([, prop]) => prop.type === "boolean")) {
+    lines.push(
+      "",
+      "  Booleans: --flag, --flag true, or --flag 1 sets true; --flag false, --flag 0, --flag=false, or --no-flag sets false."
+    );
+  }
   return lines.join("\n");
 }
 function renderFlagName(name, prop) {
-  if (prop.type === "object" || prop.type === "array" && !isScalarType(prop.items?.type)) {
-    return `--${name}-json <json>`;
-  }
-  if (prop.type === "boolean") return `--${name}`;
-  return `--${name} <value>`;
+  const flag = flagNameFor(name, prop);
+  if (isJsonField(prop)) return `${flag} <json>`;
+  if (prop.type === "boolean") return flag;
+  return `${flag} <value>`;
 }
 function renderType(prop) {
   if (prop.enum && Array.isArray(prop.enum)) {
@@ -8639,6 +9112,93 @@ function renderType(prop) {
   return prop.type ?? "any";
 }
 
+// ../argent-cli/src/run-validation.ts
+function findMissingRequired(payload, schema) {
+  const required = new Set(schema?.required ?? []);
+  if (required.size === 0) return [];
+  const declared = Object.keys(schema?.properties ?? {});
+  const names = [...declared.filter((n2) => required.has(n2))];
+  for (const name of required) {
+    if (!names.includes(name)) names.push(name);
+  }
+  return names.filter((name) => !Object.hasOwn(payload, name));
+}
+function describeServerValidationFailure(err, payload, schema) {
+  const message = err instanceof Error ? err.message : typeof err === "string" ? err : null;
+  if (message === null) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(message);
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(parsed) || parsed.length === 0) return null;
+  if (!parsed.every(isValidationIssue)) return null;
+  const properties = schema?.properties ?? {};
+  const addressesThisTool = (issue) => issue.path.length === 0 || typeof issue.path[0] === "string" && Object.hasOwn(properties, issue.path[0]);
+  if (!parsed.every(addressesThisTool)) return null;
+  const required = new Set(schema?.required ?? []);
+  const missing = [];
+  const invalid = [];
+  for (const issue of parsed) {
+    const head = issue.path[0];
+    if (issue.path.length === 1 && typeof head === "string" && required.has(head) && !Object.hasOwn(payload, head)) {
+      missing.push(head);
+    } else {
+      invalid.push({ path: issue.path, message: issue.message });
+    }
+  }
+  return { missing: sortBySchemaOrder(missing, schema), invalid, rawIssues: parsed };
+}
+function formatValidationError(report, schema) {
+  const properties = schema?.properties ?? {};
+  const lines = [];
+  if (report.missing.length > 0) {
+    const flags2 = sortBySchemaOrder(report.missing, schema).map(
+      (name) => flagNameFor(name, properties[name])
+    );
+    const noun = flags2.length === 1 ? "flag" : "flags";
+    lines.push(`missing required ${noun} ${flags2.join(", ")}`);
+  }
+  for (const field of report.invalid) {
+    lines.push(describeInvalidField(field, properties));
+  }
+  return lines.join("\n       ");
+}
+function missingFlagNames(report, schema) {
+  const properties = schema?.properties ?? {};
+  return sortBySchemaOrder(report.missing, schema).map(
+    (name) => flagNameFor(name, properties[name])
+  );
+}
+function describeInvalidField(field, properties) {
+  if (field.path.length === 0) return field.message;
+  const [head, ...rest] = field.path;
+  if (typeof head !== "string") return field.message;
+  const flag = flagNameFor(head, properties[head]);
+  const nested = rest.length > 0 ? ` ${head}${renderPathTail(rest)}` : "";
+  return `${flag}${nested} ${field.message}`;
+}
+function renderPathTail(rest) {
+  return rest.map((part) => typeof part === "number" ? `[${part}]` : `.${part}`).join("");
+}
+function sortBySchemaOrder(names, schema) {
+  const order = Object.keys(schema?.properties ?? {});
+  return [...names].sort((a2, b) => {
+    const ia = order.indexOf(a2);
+    const ib = order.indexOf(b);
+    if (ia === -1 && ib === -1) return a2.localeCompare(b);
+    if (ia === -1) return 1;
+    if (ib === -1) return -1;
+    return ia - ib;
+  });
+}
+function isValidationIssue(value) {
+  if (value === null || typeof value !== "object") return false;
+  const issue = value;
+  return typeof issue.code === "string" && Array.isArray(issue.path) && typeof issue.message === "string";
+}
+
 // ../argent-cli/src/run.ts
 function splitOptions(argv) {
   let json = false;
@@ -8666,13 +9226,13 @@ function splitOptions(argv) {
   return { json, outPath, argvForFlags: rest };
 }
 async function readStdin() {
-  return new Promise((resolve9, reject) => {
+  return new Promise((resolve10, reject) => {
     let data = "";
     process.stdin.setEncoding("utf8");
     process.stdin.on("data", (chunk) => {
       data += chunk;
     });
-    process.stdin.on("end", () => resolve9(data));
+    process.stdin.on("end", () => resolve10(data));
     process.stdin.on("error", reject);
   });
 }
@@ -8704,8 +9264,8 @@ async function fetchImageToFile(result, outPath) {
   const res = await fetch(url);
   if (!res.ok) throw new Error(`Failed to download image: ${res.status} ${res.statusText}`);
   const buf = Buffer.from(await res.arrayBuffer());
-  fs8.mkdirSync(path11.dirname(path11.resolve(outPath)), { recursive: true });
-  fs8.writeFileSync(outPath, buf);
+  fs9.mkdirSync(path12.dirname(path12.resolve(outPath)), { recursive: true });
+  fs9.writeFileSync(outPath, buf);
 }
 function renderResult(result, outputHint, images, json) {
   if (json) return JSON.stringify(result, null, 2);
@@ -8750,7 +9310,25 @@ Examples:
 `);
     return;
   }
-  const { json, outPath, argvForFlags } = splitOptions(rest);
+  let cliOptions;
+  try {
+    cliOptions = splitOptions(rest);
+  } catch (err) {
+    if (err instanceof FlagParseException) {
+      console.error(`Error: ${err.message}
+`);
+      console.error(`Run \`argent run ${toolName} --help\` to see this tool's flags.`);
+      await trackRunFailure(toolName, startedAt, {
+        error_code: FAILURE_CODES.CLI_RUN_FLAG_PARSE_FAILED,
+        failure_stage: "cli_run_split_options",
+        failure_area: "cli",
+        error_kind: "validation"
+      });
+      process.exit(2);
+    }
+    throw err;
+  }
+  const { json, outPath, argvForFlags } = cliOptions;
   const meta = await fetchTool(toolName);
   if (!meta) {
     console.error(`Tool "${toolName}" not found. Run \`argent tools\` to list available tools.`);
@@ -8762,9 +9340,37 @@ Examples:
     });
     process.exit(1);
   }
+  const schema = meta.inputSchema;
+  const failValidation = async (report, stage) => {
+    const summary = formatValidationError(report, schema);
+    if (json) {
+      console.error(
+        JSON.stringify(
+          {
+            error: summary,
+            missing: missingFlagNames(report, schema),
+            issues: report.rawIssues ?? []
+          },
+          null,
+          2
+        )
+      );
+    } else {
+      console.error(`Error: ${summary}
+`);
+      printToolHelp(meta);
+    }
+    await trackRunFailure(toolName, startedAt, {
+      error_code: FAILURE_CODES.CLI_RUN_INPUT_VALIDATION_FAILED,
+      failure_stage: stage,
+      failure_area: "cli",
+      error_kind: "validation"
+    });
+    process.exit(2);
+  };
   let parsed;
   try {
-    parsed = parseFlags(argvForFlags, meta.inputSchema);
+    parsed = parseFlags(argvForFlags, schema);
   } catch (err) {
     if (err instanceof FlagParseException) {
       console.error(`Error: ${err.message}
@@ -8784,6 +9390,11 @@ Examples:
     printToolHelp(meta);
     return;
   }
+  if (parsed.positional.length > 0) {
+    console.error(
+      `Note: ignoring unused argument(s): ${parsed.positional.join(", ")}. Pass values as --flag <value> or --flag=<value>.`
+    );
+  }
   let payload = {};
   if (parsed.rawArgs !== null) {
     let rawJson = parsed.rawArgs;
@@ -8817,6 +9428,10 @@ Examples:
   for (const [k, v] of Object.entries(parsed.args)) {
     payload[k] = v;
   }
+  const missing = findMissingRequired(payload, schema);
+  if (missing.length > 0) {
+    await failValidation({ missing, invalid: [], rawIssues: null }, "cli_run_required_flags");
+  }
   let result;
   let note;
   let images = [];
@@ -8832,6 +9447,10 @@ Examples:
     images = materialized.images;
     note = resp.note;
   } catch (err) {
+    const report = describeServerValidationFailure(err, payload, schema);
+    if (report) {
+      await failValidation(report, "cli_run_server_validation");
+    }
     console.error(err instanceof Error ? err.message : String(err));
     await trackRunFailure(toolName, startedAt, {
       error_code: FAILURE_CODES.CLI_RUN_TOOL_CALL_FAILED,
@@ -8844,8 +9463,8 @@ Examples:
   if (outPath && meta.outputHint === "image") {
     try {
       if (images.length > 0) {
-        fs8.mkdirSync(path11.dirname(path11.resolve(outPath)), { recursive: true });
-        fs8.writeFileSync(outPath, images[0].data);
+        fs9.mkdirSync(path12.dirname(path12.resolve(outPath)), { recursive: true });
+        fs9.writeFileSync(outPath, images[0].data);
       } else if (result && typeof result === "object") {
         await fetchImageToFile(result, outPath);
       }
@@ -8869,7 +9488,7 @@ Examples:
 
 // ../argent-cli/src/flow.ts
 import * as fsp from "node:fs/promises";
-import * as path12 from "node:path";
+import * as path13 from "node:path";
 var STATUS_GLYPH = {
   pass: "\u2713",
   fail: "\u2717",
@@ -8933,6 +9552,12 @@ function parseRunArgs(argv) {
     };
     const noValue = (name) => {
       if (inline !== void 0) throw new FlagParseException(`${name} does not take a value`);
+      const next = argv[i2 + 1]?.trim().toLowerCase();
+      if (next === "true" || next === "false") {
+        throw new FlagParseException(
+          `${name} does not take a value \u2014 it is a switch; omit it to leave the option off`
+        );
+      }
     };
     if (flag === "--update-baselines") {
       noValue("--update-baselines");
@@ -8970,8 +9595,10 @@ function renderUnderStepLine(s, n2, text2) {
 function renderSummary(report, opts = {}) {
   const warnings = report.steps.filter((s) => s.warning).length;
   const warningsNote = warnings ? `, ${warnings} warning${warnings === 1 ? "" : "s"}` : "";
-  const where = opts.withDevice ? ` on ${report.device}` : "";
-  return `${report.ok ? "PASS" : "FAIL"}${where} \u2014 ${report.passed} passed, ${report.failed} failed, ${report.errored} errored, ${report.skipped} skipped${warningsNote}`;
+  const where = opts.withDevice && report.device ? ` on ${report.device}` : "";
+  const nothingCounted = report.ok && report.passed + report.failed + report.errored + report.skipped === 0;
+  const note = nothingCounted ? " (no test steps)" : "";
+  return `${report.ok ? "PASS" : "FAIL"}${where} \u2014 ${report.passed} passed, ${report.failed} failed, ${report.errored} errored, ${report.skipped} skipped${warningsNote}${note}`;
 }
 function renderArtifactLines(report) {
   const lines = [];
@@ -9001,12 +9628,12 @@ async function exportFailureArtifacts(report, outputDir, ctx) {
     if (!key || !SAFE_ARTIFACT_NAME.test(key)) continue;
     const { result } = await materializeArtifacts(s.artifacts, ctx);
     s.artifacts = result;
-    const dir = path12.join(outputDir, report.flow);
+    const dir = path13.join(outputDir, report.flow);
     for (const [role, value] of Object.entries(s.artifacts)) {
       if (typeof value !== "string") continue;
-      const dest = path12.join(dir, `${key}-${role}.png`);
-      const rel = path12.relative(outputDir, dest);
-      if (rel.startsWith("..") || path12.isAbsolute(rel)) continue;
+      const dest = path13.join(dir, `${key}-${role}.png`);
+      const rel = path13.relative(outputDir, dest);
+      if (rel.startsWith("..") || path13.isAbsolute(rel)) continue;
       try {
         await fsp.mkdir(dir, { recursive: true });
         await fsp.copyFile(value, dest);
@@ -9022,7 +9649,7 @@ async function exportFailureArtifacts(report, outputDir, ctx) {
 function keyFromBaselinePath(artifacts) {
   const baseline = artifacts.baseline;
   if (typeof baseline !== "string") return null;
-  return path12.basename(baseline).replace(/\.png$/, "");
+  return path13.basename(baseline).replace(/\.png$/, "");
 }
 function resolveArtifactDisplayPaths(report) {
   for (const s of report.steps) {
@@ -9034,12 +9661,12 @@ function resolveArtifactDisplayPaths(report) {
 }
 function exitAfterFlush(code, streams = [process.stdout, process.stderr]) {
   return Promise.all(
-    streams.map((s) => new Promise((resolve9) => s.write("", () => resolve9())))
+    streams.map((s) => new Promise((resolve10) => s.write("", () => resolve10())))
   ).then(() => process.exit(code));
 }
 function renderReport(report) {
   const lines = [];
-  lines.push(`Flow "${report.flow}" on ${report.device}`);
+  lines.push(`Flow "${report.flow}"${report.device ? ` on ${report.device}` : ""}`);
   if (report.executionPrerequisite) {
     lines.push(`  assumes: ${report.executionPrerequisite}`);
   }
@@ -9071,7 +9698,7 @@ async function flow(argv, options) {
   }
   const { callTool, baseUrl } = createToolsClient({ paths: options.paths });
   if (sub === "list") {
-    const dir = path12.join(process.cwd(), ".argent", "flows");
+    const dir = path13.join(process.cwd(), ".argent", "flows");
     try {
       const entries = await fsp.readdir(dir);
       const names = entries.filter((f) => f.endsWith(".yaml")).map((f) => f.replace(/\.yaml$/, ""));
@@ -9150,7 +9777,7 @@ async function flow(argv, options) {
   }
   if (args.output) {
     const { url, token } = await baseUrl();
-    await exportFailureArtifacts(report, path12.resolve(args.output), {
+    await exportFailureArtifacts(report, path13.resolve(args.output), {
       toolsUrl: url,
       authToken: token
     });
@@ -9215,10 +9842,27 @@ ${sorted.length} tools. Run \`argent tools describe <name>\` for details.`);
     console.log(formatSchemaUsage(meta.inputSchema));
     if (meta.outputHint) console.log(`
 Output hint: ${meta.outputHint}`);
+  }
+  function printUsage4() {
+    console.log(`Usage:
+  argent tools                       List available tools
+  argent tools describe <name>       Show one tool's flags and description
+
+Options:
+  --json                             Print machine-readable JSON
+  --help, -h                         Show this help
+
+Listing tools contacts the argent tool-server, starting one if none is running.
+`);
   }
   const json = argv.includes("--json");
-  const positional = argv.filter((a2) => !a2.startsWith("--"));
+  const isHelpFlag = (a2) => a2 === "--help" || a2 === "-h";
+  const positional = argv.filter((a2) => !a2.startsWith("--") || isHelpFlag(a2));
   const sub = positional[0];
+  if (sub !== void 0 && isHelpFlag(sub)) {
+    printUsage4();
+    return;
+  }
   if (!sub) {
     await listTools(json);
     return;
@@ -9232,27 +9876,17 @@ Output hint: ${meta.outputHint}`);
     await describeTool(name, json);
     return;
   }
-  if (sub === "--help" || sub === "-h") {
-    console.log(`Usage:
-  argent tools                       List available tools
-  argent tools describe <name>       Show one tool's flags and description
-
-Options:
-  --json                             Print machine-readable JSON
-`);
-    return;
-  }
   console.error(`Unknown subcommand: tools ${sub}`);
   process.exit(1);
 }
 
 // ../argent-cli/src/server.ts
-import * as fs9 from "node:fs";
-import * as path13 from "node:path";
+import * as fs10 from "node:fs";
+import * as path14 from "node:path";
 import { homedir as homedir5, networkInterfaces } from "node:os";
 import { spawn as spawn3 } from "node:child_process";
-var STATE_DIR2 = path13.join(homedir5(), ".argent");
-var LOG_FILE2 = path13.join(STATE_DIR2, "tool-server.log");
+var STATE_DIR2 = path14.join(homedir5(), ".argent");
+var LOG_FILE2 = path14.join(STATE_DIR2, "tool-server.log");
 async function describeForeignServers(ownBundlePath) {
   const others = (await readAllToolsServerStates()).filter(
     ({ state: state2 }) => state2.bundlePath !== ownBundlePath && isToolsServerProcessAlive(state2.pid)
@@ -9311,12 +9945,12 @@ Stop one with: kill <pid>`);
   console.log(`tool-server stopped (pid ${state2.pid}).`);
 }
 function logsCmd(follow) {
-  if (!fs9.existsSync(LOG_FILE2)) {
+  if (!fs10.existsSync(LOG_FILE2)) {
     console.log(`No log file at ${LOG_FILE2}`);
     return;
   }
   if (!follow) {
-    process.stdout.write(fs9.readFileSync(LOG_FILE2, "utf8"));
+    process.stdout.write(fs10.readFileSync(LOG_FILE2, "utf8"));
     return;
   }
   const child = spawn3("tail", ["-f", LOG_FILE2], { stdio: "inherit" });
@@ -9659,9 +10293,9 @@ async function server(argv, options) {
 }
 
 // ../argent-cli/src/lens.ts
-import * as fs10 from "node:fs";
+import * as fs11 from "node:fs";
 import * as os2 from "node:os";
-import * as path14 from "node:path";
+import * as path15 from "node:path";
 
 // ../argent-cli/src/lens-terminal.ts
 import { execFileSync as execFileSync3 } from "node:child_process";
@@ -9879,15 +10513,15 @@ function isSessionAlive(session) {
 // ../argent-cli/src/lens-pty.ts
 import { chmodSync as chmodSync2, readdirSync as readdirSync2 } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname as dirname8, join as join14 } from "node:path";
+import { dirname as dirname8, join as join15 } from "node:path";
 var nodeRequire = createRequire(import.meta.url);
 function ensureSpawnHelperExecutable(req = nodeRequire) {
   if (process.platform !== "darwin") return;
   try {
-    const prebuilds = join14(dirname8(req.resolve("node-pty/package.json")), "prebuilds");
+    const prebuilds = join15(dirname8(req.resolve("node-pty/package.json")), "prebuilds");
     for (const entry of readdirSync2(prebuilds)) {
       try {
-        chmodSync2(join14(prebuilds, entry, "spawn-helper"), 493);
+        chmodSync2(join15(prebuilds, entry, "spawn-helper"), 493);
       } catch {
       }
     }
@@ -9919,7 +10553,7 @@ function ptyInjectBeats(text2) {
   ];
 }
 function sleep(ms) {
-  return new Promise((resolve9) => setTimeout(resolve9, ms));
+  return new Promise((resolve10) => setTimeout(resolve10, ms));
 }
 var DEFAULT_COLS = 80;
 var DEFAULT_ROWS = 24;
@@ -10140,7 +10774,7 @@ var SPAWN_GRACE_MS = 8e3;
 var DEATH_CONFIRMATIONS = 3;
 var SSE_RECONNECT_MS = 1e3;
 function sleep2(ms) {
-  return new Promise((resolve9) => setTimeout(resolve9, ms));
+  return new Promise((resolve10) => setTimeout(resolve10, ms));
 }
 var TRUST_PROMPT_RE = /trust this folder|do you trust|yes,? i trust|trust the files in this/i;
 async function dismissTrustPrompt(session) {
@@ -10296,8 +10930,15 @@ function parseArgs(argv) {
   for (let i2 = 0; i2 < argv.length; i2++) {
     const tok = argv[i2];
     if (tok === "--help" || tok === "-h") help = true;
-    else if (tok === "--forget") forget = true;
-    else if (tok === "--terminal" || tok === "-t") {
+    else if (tok === "--forget") {
+      forget = true;
+      const next = argv[i2 + 1]?.trim().toLowerCase();
+      if (next === "true" || next === "false") {
+        process.stderr.write(`lens: --forget does not take a value; omit it to keep the state
+`);
+        process.exit(2);
+      }
+    } else if (tok === "--terminal" || tok === "-t") {
       const v = argv[++i2];
       if (v === "iterm" || v === "terminal") terminal = v;
       else {
@@ -10413,12 +11054,12 @@ async function lens(argv, options) {
     await endSession(baseUrl);
     process.exit(1);
   }
-  const seedFile = path14.join(os2.tmpdir(), `argent-lens-seed-${process.pid}-${Date.now()}.txt`);
-  fs10.writeFileSync(seedFile, buildSeedPrompt(), "utf8");
+  const seedFile = path15.join(os2.tmpdir(), `argent-lens-seed-${process.pid}-${Date.now()}.txt`);
+  fs11.writeFileSync(seedFile, buildSeedPrompt(), "utf8");
   const launchCmd = agent.launch(shellQuote(process.cwd()), shellQuote(seedFile));
   const removeSeedFile = () => {
     try {
-      fs10.rmSync(seedFile, { force: true });
+      fs11.rmSync(seedFile, { force: true });
     } catch {
     }
   };
@@ -10808,7 +11449,7 @@ Options:
 
 // ../argent-cli/src/config.ts
 var import_picocolors2 = __toESM(require_picocolors(), 1);
-import * as path15 from "node:path";
+import * as path16 from "node:path";
 function config(argv) {
   if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
     printUsage();
@@ -10858,6 +11499,7 @@ the raw value stored at each scope.`);
 }
 function scopeDetail(e) {
   const parts = [`scopes: ${e.scopes.join(", ")}`];
+  if (e.expected) parts.push(`value: ${e.expected}${e.example ? `, e.g. ${e.example}` : ""}`);
   if (e.project !== void 0) parts.push(`project=${formatValuePlain(e.project)}`);
   if (e.global !== void 0) parts.push(`global=${formatValuePlain(e.global)}`);
   return parts.join("  \xB7  ");
@@ -10922,7 +11564,7 @@ parsed (e.g. \`true\`, \`42\`, \`["a","b"]\`); anything else is stored as a stri
     if (warning) console.error(import_picocolors2.default.yellow(warning));
     console.log(`Set ${import_picocolors2.default.bold(key)} = ${formatValuePlain(stored)} (${scopeLabel(targetScope)}).`);
   } catch (err) {
-    reportError(err);
+    reportError(err, () => suggestCorrectedSet(err, key, rawValue, scope));
   }
 }
 function cmdUnset(argv) {
@@ -10991,16 +11633,16 @@ function wantsHelp(argv) {
 }
 function scopeLabel(scope) {
   if (scope === "global") return "global";
-  return `project: ${path15.dirname(configDir("project"))}`;
+  return `project: ${path16.dirname(configDir("project"))}`;
 }
 function degenerateProjectScopeWarning(scope) {
   if (scope !== "project") return null;
   const projDir = configDir("project");
-  if (path15.resolve(projDir) === path15.resolve(configDir("global"))) {
-    return `WARNING: no project found between ${process.cwd()} and your home directory \u2014 "project" scope resolved to the home directory, so this writes the GLOBAL config file (${path15.join(projDir, "config.json")}).`;
+  if (path16.resolve(projDir) === path16.resolve(configDir("global"))) {
+    return `WARNING: no project found between ${process.cwd()} and your home directory \u2014 "project" scope resolved to the home directory, so this writes the GLOBAL config file (${path16.join(projDir, "config.json")}).`;
   }
   if (findProjectRoot(process.cwd()) === null) {
-    return `WARNING: no project markers (.argent, .git, package.json) found above ${process.cwd()} \u2014 treating it as the project root and creating ${path15.join(projDir, "config.json")}.`;
+    return `WARNING: no project markers (.argent, .git, package.json) found above ${process.cwd()} \u2014 treating it as the project root and creating ${path16.join(projDir, "config.json")}.`;
   }
   return null;
 }
@@ -11015,7 +11657,20 @@ function formatValue(value) {
   }
   return formatValuePlain(value);
 }
-function reportError(err) {
+function quoteForShell(value) {
+  if (/^[A-Za-z0-9._/@:+-]+$/.test(value)) return value;
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function suggestCorrectedSet(err, key, rawValue, scope) {
+  if (!(err instanceof ConfigValidationError)) return null;
+  const def = getConfigDefinition(key);
+  if (!def) return null;
+  const wrapped = def.parse([rawValue]);
+  if (wrapped === void 0) return null;
+  const scopeFlag = scope ? ` --scope ${scope}` : "";
+  return `argent config set ${key} ${quoteForShell(JSON.stringify([rawValue]))}${scopeFlag}`;
+}
+function reportError(err, suggest) {
   if (err instanceof ConfigManagedElsewhereError) {
     console.error(`Error: ${err.message} Use \`${err.command}\` instead.`);
   } else if (err instanceof UnknownConfigKeyError || err instanceof ConfigScopeError || err instanceof ConfigValidationError) {
@@ -11023,6 +11678,15 @@ function reportError(err) {
     if (err instanceof UnknownConfigKeyError) {
       console.error(`Run \`argent config list\` to see available keys.`);
     }
+    if (err instanceof ConfigValidationError) {
+      const corrected = suggest?.() ?? null;
+      if (corrected) {
+        console.error(`Did you mean: ${corrected}`);
+      } else if (err.example) {
+        console.error(`Example: argent config set ${err.key} ${quoteForShell(err.example)}`);
+      }
+      console.error(`Run \`argent config list\` to see each key's expected value.`);
+    }
   } else {
     console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
   }
@@ -11054,6 +11718,99 @@ ${keyLines.join("\n")}
 Run \`argent config <command> --help\` for command-specific help.`);
 }
 
+// ../argent-cli/src/secrets.ts
+var import_picocolors3 = __toESM(require_picocolors(), 1);
+async function secrets(argv) {
+  const [sub, ...rest] = argv;
+  if (sub === void 0 || sub === "list") return cmdList2(rest);
+  if (sub === "--help" || sub === "-h") return printUsage2();
+  if (sub === "--json") return cmdList2([sub, ...rest]);
+  console.error(`Error: unknown subcommand "secrets ${sub}". Try \`argent secrets --help\`.`);
+  process.exit(2);
+}
+function printUsage2() {
+  console.log(`Usage: argent secrets [list] [--json]
+
+List the secrets a \`{{secret:<NAME>}}\` placeholder can resolve, and the sources
+they come from. Names only \u2014 a value is never printed.
+
+A name is resolved by the machine running the tool-server, taking the first
+source that defines it:
+
+  1. ${SECRET_ENV_PREFIX}<NAME> in the environment    prefixed variables only
+  2. <project>/.argent/secrets.env             every key (gitignore this file)
+  3. <project>/.env.local, then <project>/.env  only ${SECRET_ENV_PREFIX}-prefixed keys
+  4. ~/.argent/secrets.env                     every key, any project
+
+A secrets file applies to the next tool call \u2014 no restart. An environment
+variable only reaches a tool-server started after it was exported.
+
+Examples:
+  echo 'APP_PASSWORD=\u2026' >> ~/.argent/secrets.env   # available in every project
+  argent secrets                                   # check it is picked up`);
+}
+async function cmdList2(argv) {
+  if (argv.includes("--help") || argv.includes("-h")) return printUsage2();
+  const json = argv.includes("--json");
+  const sources = secretSources();
+  const all = secretNames(sources);
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          secrets: all,
+          sources: sources.map((s) => ({
+            source: s.label,
+            present: s.present,
+            names: s.names,
+            ...s.needsPrefix ? { needsPrefix: true } : {}
+          }))
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+  console.log(`Secrets available to \`{{secret:<NAME>}}\` on this machine:
+`);
+  const claimed = /* @__PURE__ */ new Set();
+  for (const source of sources) {
+    console.log(`  ${source.label}`);
+    if (!source.present) {
+      console.log(`    ${import_picocolors3.default.dim("not found")}`);
+    } else if (source.needsPrefix) {
+      console.log(
+        `    ${import_picocolors3.default.dim(`no ${SECRET_ENV_PREFIX}* keys \u2014 only prefixed keys are exposed from a file the app shares`)}`
+      );
+    } else if (source.names.length === 0) {
+      console.log(`    ${import_picocolors3.default.dim("no secrets")}`);
+    } else {
+      const rendered = source.names.map(
+        (name) => claimed.has(name) ? import_picocolors3.default.dim(`${name} (shadowed above)`) : name
+      );
+      for (const name of source.names) claimed.add(name);
+      console.log(`    ${rendered.join(", ")}`);
+    }
+  }
+  console.log(
+    `
+${all.length === 0 ? "No secrets are defined." : `${all.length} name${all.length === 1 ? "" : "s"} in effect: ${all.join(", ")}`}`
+  );
+  console.log(
+    import_picocolors3.default.dim("Values are never printed. Run `argent secrets --help` to see where to add one.")
+  );
+  const routed = await getResolvedToolsUrl().catch(() => ({ url: null }));
+  if (routed.url) {
+    console.log(
+      import_picocolors3.default.yellow(
+        `
+Note: a remote tool-server is linked (${routed.url}). Placeholders resolve there, against that machine's environment and secrets files \u2014 not the ones listed above.`
+      )
+    );
+  }
+}
+
 // ../../node_modules/@clack/core/dist/index.mjs
 import { styleText } from "node:util";
 import { stdout, stdin } from "node:process";
@@ -11774,7 +12531,7 @@ import { styleText as styleText2, stripVTControlCharacters } from "node:util";
 import process$1 from "node:process";
 var import_sisteransi2 = __toESM(require_src(), 1);
 import { existsSync as existsSync7, lstatSync as lstatSync3, readdirSync as readdirSync3 } from "node:fs";
-import { dirname as dirname10, join as join17 } from "node:path";
+import { dirname as dirname10, join as join18 } from "node:path";
 function isUnicodeSupported() {
   if (process$1.platform !== "win32") {
     return process$1.env.TERM !== "linux";
@@ -12211,7 +12968,7 @@ ${r2}
 }).prompt();
 
 // ../argent-cli/src/link.ts
-var import_picocolors3 = __toESM(require_picocolors(), 1);
+var import_picocolors4 = __toESM(require_picocolors(), 1);
 var WILDCARD_HOSTS = /* @__PURE__ */ new Set(["0.0.0.0", "::", "::0", ""]);
 function isLoopback2(host) {
   return host === "127.0.0.1" || host === "localhost" || host === "::1";
@@ -12469,7 +13226,7 @@ async function preflightHealth(url, token) {
 }
 function printRestartHint() {
   console.log(
-    import_picocolors3.default.dim("Restart your editor to apply the change to any running `argent mcp` session.")
+    import_picocolors4.default.dim("Restart your editor to apply the change to any running `argent mcp` session.")
   );
 }
 function printSecurityCaveat(host, token, url) {
@@ -12478,7 +13235,7 @@ function printSecurityCaveat(host, token, url) {
   if (tls) {
     if (!token) {
       process.stderr.write(
-        import_picocolors3.default.yellow(
+        import_picocolors4.default.yellow(
           `WARNING: ${host} is reached over HTTPS but with NO token \u2014 anyone who can reach the URL can drive the server. Pair with a token.
 `
         )
@@ -12488,7 +13245,7 @@ function printSecurityCaveat(host, token, url) {
   }
   if (token) {
     process.stderr.write(
-      import_picocolors3.default.dim(
+      import_picocolors4.default.dim(
         `Note: ${host} is reached over plain HTTP (bearer-token auth, no TLS). Keep this link to a trusted network or VPN, or front it with an https:// tunnel.
 `
       )
@@ -12496,7 +13253,7 @@ function printSecurityCaveat(host, token, url) {
     return;
   }
   process.stderr.write(
-    import_picocolors3.default.yellow(
+    import_picocolors4.default.yellow(
       `WARNING: linked target ${host} is non-loopback and has NO token \u2014 tool calls travel over plain HTTP with no auth. Treat this link as trusted-network-only, or pair with a token (start the server without --no-auth).
 `
     )
@@ -12529,9 +13286,9 @@ async function link(argv) {
   if (flags2.host !== null) {
     host = flags2.host;
   } else {
-    intro(import_picocolors3.default.bgCyan(import_picocolors3.default.black(" argent link ")));
+    intro(import_picocolors4.default.bgCyan(import_picocolors4.default.black(" argent link ")));
     if (existing) {
-      log.info(`Current link: ${import_picocolors3.default.cyan(existing.url)} (${existing.createdAt})`);
+      log.info(`Current link: ${import_picocolors4.default.cyan(existing.url)} (${existing.createdAt})`);
     }
     host = await promptHost(existing);
   }
@@ -12547,12 +13304,12 @@ async function link(argv) {
   let url = flags2.url ?? formatUrl(host, port);
   if (!flags2.yes && existing) {
     if (existing.url === url) {
-      log.info(`Already linked to ${import_picocolors3.default.cyan(url)}.`);
+      log.info(`Already linked to ${import_picocolors4.default.cyan(url)}.`);
       outro("No changes.");
       return;
     }
     const overwrite = await confirm({
-      message: `Replace existing link ${import_picocolors3.default.dim(existing.url)} with ${import_picocolors3.default.cyan(url)}?`,
+      message: `Replace existing link ${import_picocolors4.default.dim(existing.url)} with ${import_picocolors4.default.cyan(url)}?`,
       initialValue: true
     });
     if (isCancel(overwrite) || !overwrite) {
@@ -12570,10 +13327,10 @@ async function link(argv) {
       }
       const result = await preflightHealth(url, token);
       if (result.ok) {
-        if (spinner2) spinner2.stop(import_picocolors3.default.green("Tool-server reachable."));
+        if (spinner2) spinner2.stop(import_picocolors4.default.green("Tool-server reachable."));
         break;
       }
-      if (spinner2) spinner2.stop(import_picocolors3.default.red("Verification failed."));
+      if (spinner2) spinner2.stop(import_picocolors4.default.red("Verification failed."));
       const detail = result.error ? ` (${result.error})` : "";
       if (flags2.yes) {
         console.error(
@@ -12613,15 +13370,15 @@ async function link(argv) {
   };
   await writeLinkConfig(cfg);
   if (existing && existing.url !== url) {
-    console.log(`${import_picocolors3.default.green("\u2713")} Link updated: ${import_picocolors3.default.dim(existing.url)} \u2192 ${import_picocolors3.default.cyan(url)}`);
+    console.log(`${import_picocolors4.default.green("\u2713")} Link updated: ${import_picocolors4.default.dim(existing.url)} \u2192 ${import_picocolors4.default.cyan(url)}`);
   } else {
-    console.log(`${import_picocolors3.default.green("\u2713")} Linked: ${import_picocolors3.default.cyan(url)}`);
+    console.log(`${import_picocolors4.default.green("\u2713")} Linked: ${import_picocolors4.default.cyan(url)}`);
   }
-  if (token) console.log(import_picocolors3.default.dim("  auth: token stored in ~/.argent/link.json (0600)"));
+  if (token) console.log(import_picocolors4.default.dim("  auth: token stored in ~/.argent/link.json (0600)"));
   printSecurityCaveat(host, token, url);
   if (process.env.ARGENT_TOOLS_URL) {
     console.log(
-      import_picocolors3.default.yellow(
+      import_picocolors4.default.yellow(
         `Note: ARGENT_TOOLS_URL=${process.env.ARGENT_TOOLS_URL} is set in your environment and takes precedence over the link.`
       )
     );
@@ -12652,7 +13409,7 @@ async function unlink3(argv) {
   }
   if (!flags2.yes) {
     const confirmed = await confirm({
-      message: `Remove link to ${import_picocolors3.default.cyan(existing.url)}?`,
+      message: `Remove link to ${import_picocolors4.default.cyan(existing.url)}?`,
       initialValue: true
     });
     if (isCancel(confirmed) || !confirmed) {
@@ -12661,10 +13418,10 @@ async function unlink3(argv) {
     }
   }
   await clearLinkConfig();
-  console.log(`${import_picocolors3.default.green("\u2713")} Unlinked from ${import_picocolors3.default.dim(existing.url)}.`);
+  console.log(`${import_picocolors4.default.green("\u2713")} Unlinked from ${import_picocolors4.default.dim(existing.url)}.`);
   if (process.env.ARGENT_TOOLS_URL) {
     console.log(
-      import_picocolors3.default.yellow(
+      import_picocolors4.default.yellow(
         `The env var ARGENT_TOOLS_URL is also set in your shell (=${process.env.ARGENT_TOOLS_URL}) and takes precedence \u2014 unset it manually if you want fully local behaviour.`
       )
     );
@@ -12673,13 +13430,13 @@ async function unlink3(argv) {
 }
 
 // ../argent-cli/src/telemetry.ts
-var import_picocolors4 = __toESM(require_picocolors(), 1);
+var import_picocolors5 = __toESM(require_picocolors(), 1);
 async function telemetry(args) {
   const sub = args[0];
   init("cli");
   switch (sub) {
     case void 0:
-      printUsage2();
+      printUsage3();
       await shutdown();
       return;
     case "status":
@@ -12694,7 +13451,7 @@ async function telemetry(args) {
       return;
     case "--help":
     case "-h":
-      printUsage2();
+      printUsage3();
       await shutdown();
       return;
     default:
@@ -12703,7 +13460,7 @@ async function telemetry(args) {
       process.exit(1);
   }
 }
-function printUsage2() {
+function printUsage3() {
   console.log(`Usage:
   argent telemetry status    Show telemetry state and device id
   argent telemetry enable    Enable telemetry
@@ -12721,21 +13478,21 @@ async function cmdEnable() {
   const wasEnabled = isEnabled();
   markEnabled();
   if (wasEnabled) {
-    console.log(import_picocolors4.default.dim("Telemetry was already enabled."));
+    console.log(import_picocolors5.default.dim("Telemetry was already enabled."));
   } else {
-    console.log(import_picocolors4.default.green("Telemetry enabled."));
+    console.log(import_picocolors5.default.green("Telemetry enabled."));
   }
   await shutdown();
 }
 async function cmdDisable() {
   const wasEnabled = isEnabled();
   if (!wasEnabled) {
-    console.log(import_picocolors4.default.dim("Telemetry was already disabled."));
+    console.log(import_picocolors5.default.dim("Telemetry was already disabled."));
     await shutdown();
     return;
   }
   await markDisabled();
-  console.log(import_picocolors4.default.red("Telemetry disabled."));
+  console.log(import_picocolors5.default.red("Telemetry disabled."));
   await shutdown();
 }
 export {
@@ -12750,6 +13507,7 @@ export {
   lens,
   link,
   run,
+  secrets,
   server,
   telemetry,
   tools,