@kitsy/cnos-cli 1.1.1 → 1.2.0

package/dist/index.js

@@ -16,9 +16,11 @@ var COMMAND_OPTION_KEYS_WITH_VALUE = /* @__PURE__ */ new Set([
   "--provider",
   "--passphrase",
   "--vault",
-  "--inherit"
+  "--inherit",
+  "--as",
+  "--set"
 ]);
-var COMMAND_FLAG_KEYS = /* @__PURE__ */ new Set(["--flatten", "--public", "--local", "--remote", "--ref"]);
+var COMMAND_FLAG_KEYS = /* @__PURE__ */ new Set(["--flatten", "--public", "--local", "--remote", "--ref", "--no-passphrase"]);
 function normalizeCommand(argv) {
   const [command = "doctor", ...rest] = argv;
   const resource = rest[0];
@@ -26,12 +28,21 @@ function normalizeCommand(argv) {
   if ((command === "create" || command === "add") && resource === "profile") {
     return ["profile", "create", ...remaining];
   }
+  if ((command === "create" || command === "add") && resource === "vault") {
+    return ["vault", "create", ...remaining];
+  }
   if ((command === "delete" || command === "remove") && resource === "profile") {
     return ["profile", "delete", ...remaining];
   }
+  if ((command === "delete" || command === "remove") && resource === "vault") {
+    return ["vault", "remove", ...remaining];
+  }
   if (command === "list" && resource === "profile") {
     return ["profile", "list", ...remaining];
   }
+  if (command === "list" && resource === "vault") {
+    return ["vault", "list", ...remaining];
+  }
   if ((command === "create" || command === "add") && resource === "secret") {
     return ["secret", "set", ...remaining];
   }
@@ -186,16 +197,16 @@ function printJson(value) {
 }
 
 // src/services/writes.ts
-import { mkdir, readFile, rm, writeFile } from "fs/promises";
-import path from "path";
+import { mkdir, readFile as readFile2, rm as rm2, writeFile as writeFile2 } from "fs/promises";
+import path2 from "path";
 import {
-  createSecretVault,
+  getVaultPassphraseEnvVar,
   parseYaml,
   resolveConfigDocumentPath,
-  resolveSecretPassphrase,
-  resolveSecretStoreRoot,
-  stringifyYaml,
-  writeLocalSecret
+  stringifyYaml as stringifyYaml2,
+  writeLocalSecret,
+  resolveConfiguredVaultPassphrase as resolveConfiguredVaultPassphrase2,
+  resolveSecretStoreRoot as resolveSecretStoreRoot2
 } from "@kitsy/cnos/internal";
 
 // src/services/runtime.ts
@@ -228,6 +239,125 @@ async function createRuntimeService(options = {}) {
   });
 }
 
+// src/services/vaults.ts
+import { readFile, rm, writeFile } from "fs/promises";
+import path from "path";
+import {
+  createSecretVault,
+  loadManifest,
+  listSecretVaults,
+  resolveConfiguredVaultPassphrase,
+  resolveSecretStoreRoot,
+  resolveSecretVaultFile,
+  resolveVaultDefinition,
+  stringifyYaml
+} from "@kitsy/cnos/internal";
+function sortVaults(vaults) {
+  return Object.fromEntries(Object.entries(vaults).sort(([left], [right]) => left.localeCompare(right)));
+}
+async function createVaultDefinition(name, options = {}) {
+  const vault = name.trim() || "default";
+  const provider = options.provider?.trim() || "local";
+  const noPassphrase = options.noPassphrase ?? false;
+  if (provider === "local" && noPassphrase) {
+    throw new Error("Local vaults require a passphrase");
+  }
+  const loadedManifest = await loadManifest(options.root ? { root: options.root } : {});
+  const processEnv = options.processEnv ?? process.env;
+  const passphraseEnvVar = "CNOS_SECRET_PASSPHRASE";
+  const rawManifest = {
+    ...loadedManifest.rawManifest,
+    vaults: {
+      ...loadedManifest.rawManifest.vaults ?? {},
+      [vault]: provider === "local" ? {
+        provider: "local",
+        passphrase: `env:${passphraseEnvVar}`
+      } : {
+        provider
+      }
+    }
+  };
+  let storePath;
+  if (provider === "local") {
+    const passphrase = options.passphrase ?? resolveConfiguredVaultPassphrase(
+      {
+        provider: "local",
+        passphrase: `env:${passphraseEnvVar}`
+      },
+      vault,
+      processEnv
+    );
+    if (!passphrase) {
+      throw new Error(`Vault "${vault}" requires --passphrase or ${passphraseEnvVar}`);
+    }
+    storePath = await createSecretVault(resolveSecretStoreRoot(processEnv), vault, passphrase);
+  }
+  await writeFile(loadedManifest.manifestPath, stringifyYaml(rawManifest), "utf8");
+  return {
+    ...resolveVaultDefinition(
+      {
+        [vault]: rawManifest.vaults[vault]
+      },
+      vault
+    ),
+    passphrasePolicy: provider === "local" ? "required" : "none",
+    manifestPath: loadedManifest.manifestPath,
+    ...storePath ? { storePath } : {}
+  };
+}
+async function listVaultDefinitions(options = {}) {
+  const loadedManifest = await loadManifest(options.root ? { root: options.root } : {});
+  return Object.keys(loadedManifest.manifest.vaults).sort((left, right) => left.localeCompare(right)).map((name) => {
+    const definition = resolveVaultDefinition(loadedManifest.manifest.vaults, name);
+    return {
+      ...definition,
+      passphrasePolicy: definition.requiresPassphrase ? "required" : "none"
+    };
+  });
+}
+async function removeVaultDefinition(name, options = {}) {
+  const vault = name.trim() || "default";
+  const loadedManifest = await loadManifest(options.root ? { root: options.root } : {});
+  if (!loadedManifest.rawManifest.vaults?.[vault]) {
+    return {
+      name: vault,
+      deleted: false,
+      manifestPath: loadedManifest.manifestPath
+    };
+  }
+  const nextVaults = { ...loadedManifest.rawManifest.vaults ?? {} };
+  delete nextVaults[vault];
+  const rawManifest = {
+    ...loadedManifest.rawManifest,
+    ...Object.keys(nextVaults).length > 0 ? { vaults: sortVaults(nextVaults) } : {}
+  };
+  if (Object.keys(nextVaults).length === 0) {
+    delete rawManifest.vaults;
+  }
+  await writeFile(loadedManifest.manifestPath, stringifyYaml(rawManifest), "utf8");
+  const storeRoot = resolveSecretStoreRoot(options.processEnv);
+  const vaultFile = resolveSecretVaultFile(storeRoot, vault);
+  const vaultStoreRoot = path.join(storeRoot, "vaults", vault);
+  let removedStore;
+  try {
+    await readFile(vaultFile, "utf8");
+    await rm(vaultFile, { force: true });
+    await rm(vaultStoreRoot, { recursive: true, force: true });
+    removedStore = vaultStoreRoot;
+  } catch {
+    removedStore = void 0;
+  }
+  return {
+    name: vault,
+    deleted: true,
+    manifestPath: loadedManifest.manifestPath,
+    ...removedStore ? { removedStore } : {}
+  };
+}
+async function listLocalStoreVaults(options = {}) {
+  return listSecretVaults(resolveSecretStoreRoot(options.processEnv));
+}
+
 // src/services/writes.ts
 function setNestedValue(target, pathSegments, value) {
   const [head, ...tail] = pathSegments;
@@ -275,7 +405,7 @@ function isSecretReference(value) {
 }
 async function readYamlDocument(filePath) {
   try {
-    return parseYaml(await readFile(filePath, "utf8")) ?? {};
+    return parseYaml(await readFile2(filePath, "utf8")) ?? {};
   } catch {
     return {};
   }
@@ -314,46 +444,45 @@ async function defineValue(namespace, configPath, rawValue, options = {}) {
   const document = await readYamlDocument(filePath);
   const parsedValue = parseScalarValue(rawValue);
   setNestedValue(document, configPath.split("."), parsedValue);
-  await mkdir(path.dirname(filePath), { recursive: true });
-  await writeFile(filePath, stringifyYaml(document), "utf8");
+  await mkdir(path2.dirname(filePath), { recursive: true });
+  await writeFile2(filePath, stringifyYaml2(document), "utf8");
   return {
     filePath,
     value: parsedValue
   };
 }
-async function createVault(vault, options = {}) {
-  const passphrase = options.passphrase ?? resolveSecretPassphrase(vault, options.processEnv ?? process.env);
-  if (!passphrase) {
-    throw new Error("Vault creation requires --passphrase or CNOS_SECRET_PASSPHRASE");
-  }
-  const normalizedVault = vault.trim() || "default";
-  const filePath = await createSecretVault(
-    resolveSecretStoreRoot(options.processEnv),
-    normalizedVault,
-    passphrase
-  );
-  return {
-    vault: normalizedVault,
-    filePath
-  };
-}
 async function setSecret(configPath, rawValue, options = {}) {
   const runtime = await createRuntimeService(options);
   const workspaceRoot = getSelectedWorkspaceRoot(options, runtime);
   const profile = options.profile ?? runtime.graph.profile;
   const filePath = resolveConfigDocumentPath(workspaceRoot, "secret", configPath, profile);
   const document = await readYamlDocument(filePath);
-  const mode = options.mode ?? "local";
   const vault = options.vault?.trim() || "default";
+  const vaultDefinition = runtime.manifest.vaults[vault];
+  const inferredProvider = vaultDefinition?.provider ?? options.provider;
+  const mode = options.mode ?? (inferredProvider === "local" ? "local" : inferredProvider === "github-secrets" ? "ref" : "local");
   let reference;
   let storePath;
   if (mode === "local") {
-    const passphrase = options.passphrase ?? resolveSecretPassphrase(vault, options.processEnv ?? process.env);
+    const provider = inferredProvider ?? "local";
+    if (provider !== "local") {
+      throw new Error(`Vault "${vault}" uses provider "${provider}" and cannot store local secret material`);
+    }
+    const passphrase = resolveConfiguredVaultPassphrase2(
+      vaultDefinition ? { provider: "local", ...vaultDefinition.passphrase ? { passphrase: vaultDefinition.passphrase } : {} } : { provider: "local" },
+      vault,
+      {
+        ...options.processEnv ?? process.env,
+        ...options.passphrase ? {
+          [getVaultPassphraseEnvVar(vault)]: options.passphrase
+        } : {}
+      }
+    ) ?? options.passphrase;
     if (!passphrase) {
-      throw new Error(`Vault "${vault}" requires --passphrase or CNOS_SECRET_PASSPHRASE`);
+      throw new Error(`Vault "${vault}" requires --passphrase or its configured passphrase env var`);
     }
     const ref = configPath;
-    storePath = await writeLocalSecret(resolveSecretStoreRoot(options.processEnv), ref, rawValue, passphrase, vault);
+    storePath = await writeLocalSecret(resolveSecretStoreRoot2(options.processEnv), ref, rawValue, passphrase, vault);
     reference = {
       provider: "local",
       ref,
@@ -361,13 +490,16 @@ async function setSecret(configPath, rawValue, options = {}) {
     };
   } else {
     reference = {
-      provider: options.provider ?? (mode === "ref" ? "ref" : "remote"),
-      ref: rawValue
+      provider: inferredProvider ?? (mode === "ref" ? "ref" : "remote"),
+      ref: rawValue || configPath.replace(/[^A-Za-z0-9]+/g, "_").toUpperCase(),
+      ...vaultDefinition || vault !== "default" ? {
+        vault
+      } : {}
     };
   }
   setNestedValue(document, configPath.split("."), reference);
-  await mkdir(path.dirname(filePath), { recursive: true });
-  await writeFile(filePath, stringifyYaml(document), "utf8");
+  await mkdir(path2.dirname(filePath), { recursive: true });
+  await writeFile2(filePath, stringifyYaml2(document), "utf8");
   return {
     filePath,
     provider: reference.provider,
@@ -390,18 +522,18 @@ async function deleteSecret(configPath, options = {}) {
       deleted: false
     };
   }
-  await writeFile(filePath, stringifyYaml(document), "utf8");
+  await writeFile2(filePath, stringifyYaml2(document), "utf8");
   let removedStore;
   const secretRef = metadata?.secretRef;
   if (isSecretReference(secretRef) && secretRef.provider === "local") {
-    const storePath = path.join(
-      resolveSecretStoreRoot(options.processEnv),
+    const storePath = path2.join(
+      resolveSecretStoreRoot2(options.processEnv),
       "vaults",
       secretRef.vault ?? "default",
       "store",
       ...secretRef.ref.split("/")
     ).concat(".json");
-    await rm(storePath, { force: true });
+    await rm2(storePath, { force: true });
     removedStore = storePath;
   }
   return {
@@ -426,7 +558,7 @@ async function deleteValue(namespace, configPath, options = {}) {
       deleted: false
     };
   }
-  await writeFile(filePath, stringifyYaml(document), "utf8");
+  await writeFile2(filePath, stringifyYaml2(document), "utf8");
   return {
     filePath,
     deleted: true
@@ -502,8 +634,8 @@ async function runDiff(leftProfile, rightProfile, options = {}) {
 }
 
 // src/services/doctor.ts
-import { readFile as readFile2 } from "fs/promises";
-import path2 from "path";
+import { readFile as readFile3 } from "fs/promises";
+import path3 from "path";
 
 // src/services/validation.ts
 import { validateRuntime } from "@kitsy/cnos/internal";
@@ -518,7 +650,7 @@ async function createValidationSummary(options = {}) {
 
 // src/services/doctor.ts
 async function checkGitignore(root) {
-  const gitignorePath = path2.join(root, ".gitignore");
+  const gitignorePath = path3.join(root, ".gitignore");
   const expected = [
     ".cnos/env/.env",
     ".cnos/env/.env.*",
@@ -530,7 +662,7 @@ async function checkGitignore(root) {
     "!.cnos/workspaces/*/env/.env.*.example"
   ];
   try {
-    const content = await readFile2(gitignorePath, "utf8");
+    const content = await readFile3(gitignorePath, "utf8");
     const missing = expected.filter((entry) => !content.includes(entry));
     return {
       name: "gitignore",
@@ -549,7 +681,7 @@ function issueSummary(issues) {
   return issues.length === 0 ? "no issues" : issues.map((issue) => issue.message).join("; ");
 }
 async function evaluateDoctor(options = {}) {
-  const root = path2.resolve(options.root ?? process.cwd());
+  const root = path3.resolve(options.root ?? process.cwd());
   const { runtime, summary } = await createValidationSummary(options);
   const localRoot = runtime.graph.workspace.workspaceRoots.find((entry) => entry.scope === "local");
   const globalRoot = runtime.graph.workspace.workspaceRoots.find((entry) => entry.scope === "global");
@@ -620,11 +752,17 @@ async function runDump(options = {}) {
 }
 
 // src/commands/exportEnv.ts
+import { mkdir as mkdir2, writeFile as writeFile3 } from "fs/promises";
+import path4 from "path";
+function formatEnvOutput(env) {
+  return Object.entries(env).sort(([left], [right]) => left.localeCompare(right)).map(([key, value]) => `${key}=${value}`).join("\n");
+}
 async function runExportEnv(options = {}) {
   const cliArgs = [...options.cliArgs ?? []];
   const isPublic = consumeFlag(cliArgs, "--public");
   const framework = consumeOption(cliArgs, "--framework");
   const prefix = consumeOption(cliArgs, "--prefix");
+  const to = consumeOption(cliArgs, "--to");
   const runtime = await createRuntimeService({
     ...options,
     cliArgs
@@ -632,16 +770,26 @@ async function runExportEnv(options = {}) {
   const env = isPublic ? runtime.toPublicEnv({
     ...framework ? { framework } : {},
     ...prefix ? { prefix } : {}
-  }) : Object.fromEntries(
-    Object.entries(runtime.manifest.envMapping.explicit).map(([envVar, logicalKey]) => [envVar, runtime.read(logicalKey)]).filter((entry) => entry[1] !== void 0).map(([envVar, value]) => [
-      envVar,
-      typeof value === "string" ? value : typeof value === "number" || typeof value === "boolean" || typeof value === "bigint" ? String(value) : JSON.stringify(value)
-    ])
-  );
+  }) : runtime.toEnv();
+  const output = formatEnvOutput(env);
+  if (to) {
+    const targetPath = path4.resolve(options.root ?? process.cwd(), to);
+    await mkdir2(path4.dirname(targetPath), { recursive: true });
+    await writeFile3(targetPath, output, "utf8");
+    if (options.json) {
+      return printJson({
+        to: targetPath,
+        count: Object.keys(env).length,
+        public: isPublic,
+        ...framework ? { framework } : {}
+      });
+    }
+    return `Wrote ${Object.keys(env).length} env vars to ${targetPath}`;
+  }
   if (options.json) {
     return printJson(env);
   }
-  return Object.entries(env).sort(([left], [right]) => left.localeCompare(right)).map(([key, value]) => `${key}=${value}`).join("\n");
+  return output;
 }
 
 // src/commands/export.ts
@@ -798,15 +946,70 @@ var COMMANDS = [
       {
         flag: "--passphrase <value>",
         description: "Passphrase used to encrypt local secret material when --local is selected."
+      },
+      {
+        flag: "--vault <name>",
+        description: "Use a manifest-defined vault. Provider behavior is inferred from the vault definition."
       }
     ],
     examples: [
       "cnos secret app.token",
-      "cnos secret set app.token super-secret --local --passphrase dev-pass",
-      "cnos add secret app.token APP_TOKEN --ref --provider env",
-      "cnos secret list --workspace agents"
+      "cnos vault create local-dev --passphrase dev-pass",
+      "cnos secret set app.token super-secret --vault local-dev",
+      "cnos vault create github-ci --provider github-secrets --no-passphrase",
+      "cnos secret set app.token APP_TOKEN --vault github-ci"
     ]
   },
+  {
+    id: "vault",
+    summary: "Manage manifest-defined secret vaults.",
+    usage: "cnos vault [create <name> | list | remove <name>] [options] [global-options]",
+    description: "Creates, lists, and removes vault definitions in .cnos/cnos.yml. Local vaults use encrypted material under ~/.cnos/secrets, while github-secrets vaults resolve from process.env in CI.",
+    options: [
+      {
+        flag: "--provider <local|github-secrets>",
+        description: "Vault provider. Defaults to local."
+      },
+      {
+        flag: "--passphrase <value>",
+        description: "Required for local vault creation unless already available in the configured passphrase env var."
+      },
+      {
+        flag: "--no-passphrase",
+        description: "Allowed for passwordless providers such as github-secrets."
+      }
+    ],
+    examples: [
+      "cnos vault create local-dev --passphrase dev-pass",
+      "cnos vault create github-ci --provider github-secrets --no-passphrase",
+      "cnos vault list",
+      "cnos vault remove local-dev"
+    ]
+  },
+  {
+    id: "vault create",
+    summary: "Create a manifest-defined vault.",
+    usage: "cnos vault create <name> [--provider <local|github-secrets>] [--passphrase <value>] [--no-passphrase] [global-options]",
+    description: "Creates a vault definition in .cnos/cnos.yml and, for local vaults, initializes the encrypted store under ~/.cnos/secrets.",
+    examples: [
+      "cnos vault create local-dev --passphrase dev-pass",
+      "cnos vault create github-ci --provider github-secrets --no-passphrase"
+    ]
+  },
+  {
+    id: "vault list",
+    summary: "List manifest-defined vaults.",
+    usage: "cnos vault list [global-options]",
+    description: "Lists vault definitions together with provider and passphrase policy.",
+    examples: ["cnos vault list"]
+  },
+  {
+    id: "vault remove",
+    summary: "Remove a vault definition.",
+    usage: "cnos vault remove <name> [global-options]",
+    description: "Removes the vault from .cnos/cnos.yml and deletes local vault store metadata when present.",
+    examples: ["cnos vault remove local-dev"]
+  },
   {
     id: "define",
     summary: "Write a value or secret into the selected workspace.",
@@ -850,7 +1053,7 @@ var COMMANDS = [
   {
     id: "list",
     summary: "List resolved config entries.",
-    usage: "cnos list [value|secret|meta|env|public|all] [--prefix <path>] [global-options]",
+    usage: "cnos list [value|secret|meta|env|public|all] [--prefix <path>] [--framework <name>] [global-options]",
     description: "Lists stored config or derived projections across one namespace or the full effective graph, with optional prefix filtering.",
     options: [
       {
@@ -860,9 +1063,13 @@ var COMMANDS = [
       {
         flag: "--prefix <path>",
         description: "Filter list output to entries whose logical keys begin with this prefix."
+      },
+      {
+        flag: "--framework <name>",
+        description: "When listing public output, apply framework-specific prefixes such as vite or next."
       }
     ],
-    examples: ["cnos list", "cnos list value --prefix app.", "cnos list env", "cnos list --namespace secret"]
+    examples: ["cnos list", "cnos list value --prefix app.", "cnos list env", "cnos list public --framework vite"]
   },
   {
     id: "profile",
@@ -909,29 +1116,51 @@ var COMMANDS = [
     description: "Deletes .cnos/profiles/<name>.yml.",
     examples: ["cnos profile delete stage"]
   },
+  {
+    id: "promote",
+    summary: "Promote shareable config into public or env projection surfaces.",
+    usage: "cnos promote <key...> --to <public|env> [--as <ENV_VAR>] [global-options]",
+    description: "Adds keys to public.promote or envMapping.explicit in .cnos/cnos.yml. Sensitive or non-shareable namespaces are rejected.",
+    options: [
+      {
+        flag: "--to <public|env>",
+        description: "Choose whether the keys are promoted to the public surface or env export surface."
+      },
+      {
+        flag: "--as <ENV_VAR>",
+        description: "Required for --to env. Sets the exported env var name for the promoted key."
+      }
+    ],
+    examples: [
+      "cnos promote value.flag.auth.upi_enabled --to public",
+      "cnos promote value.server.port --to env --as PORT"
+    ]
+  },
   {
     id: "secret set",
     summary: "Write a secret securely.",
     usage: "cnos secret set <path> <value> [--local|--remote|--ref] [--vault <name>] [--provider <name>] [--passphrase <value>] [global-options]",
-    description: "Writes a secret reference into the repo and, when --local is used, stores encrypted secret material outside the repo under ~/.cnos/secrets/vaults/<vault>.",
+    description: "Writes a secret reference into the repo. When a local vault is selected, CNOS stores encrypted secret material outside the repo under ~/.cnos/secrets/vaults/<vault>; when a github-secrets vault is selected, CNOS writes a CI env-backed ref.",
     examples: [
-      "cnos secret create vault db --passphrase dev-pass",
-      "cnos secret set app.token super-secret --local --vault db --passphrase dev-pass"
+      "cnos vault create db --passphrase dev-pass",
+      "cnos secret set app.token super-secret --vault db",
+      "cnos vault create github-ci --provider github-secrets --no-passphrase",
+      "cnos secret set app.token APP_TOKEN --vault github-ci"
     ]
   },
   {
     id: "secret create vault",
     summary: "Create a local secret vault.",
     usage: "cnos secret create vault <name> --passphrase <value> [global-options]",
-    description: "Creates a named local secret vault under ~/.cnos/secrets/vaults.",
+    description: "Alias for cnos vault create <name>.",
     examples: ["cnos secret create vault db --passphrase dev-pass"]
   },
   {
     id: "secret list",
     summary: "List resolved secrets.",
-    usage: "cnos secret list [global-options]",
-    description: "Lists resolved secret keys for the selected workspace and profile.",
-    examples: ["cnos secret list --workspace api"]
+    usage: "cnos secret list [--vault <name>] [--provider <name>] [global-options]",
+    description: "Lists stored secret entries for the selected workspace and profile, optionally filtered by vault or provider.",
+    examples: ["cnos secret list --workspace api", "cnos secret list --vault github-ci"]
   },
   {
     id: "secret delete",
@@ -982,7 +1211,7 @@ var COMMANDS = [
   {
     id: "export env",
     summary: "Render environment variables for the selected workspace.",
-    usage: "cnos export env [--public] [--framework <name>] [--prefix <prefix>] [global-options]",
+    usage: "cnos export env [--public] [--framework <name>] [--prefix <prefix>] [--to <path>] [global-options]",
     description: "Exports the effective environment as KEY=VALUE lines, or only promoted public values when --public is set.",
     options: [
       {
@@ -996,9 +1225,17 @@ var COMMANDS = [
       {
         flag: "--prefix <prefix>",
         description: "Override the generated public env prefix."
+      },
+      {
+        flag: "--to <path>",
+        description: "Write the rendered KEY=VALUE output to a file instead of stdout."
       }
     ],
-    examples: ["cnos export env", "cnos export env --public --framework vite --workspace api"]
+    examples: [
+      "cnos export env",
+      "cnos export env --to .env.local",
+      "cnos export env --public --framework vite --to .env.local --workspace api"
+    ]
   },
   {
     id: "dump",
@@ -1020,9 +1257,32 @@ var COMMANDS = [
   {
     id: "run",
     summary: "Run a child process with CNOS env injected.",
-    usage: "cnos run [global-options] -- <command...>",
-    description: "Resolves the active workspace and profile, injects runtime env variables, and executes the command after --.",
-    examples: ["cnos run -- node server.js", "cnos run --workspace api -- pnpm dev"]
+    usage: "cnos run [--public] [--framework <name>] [--set <logical-key=value>] [global-options] -- <command...>",
+    description: "Resolves the active workspace and profile, injects runtime env variables, bootstraps __CNOS_GRAPH__ for singleton runtime reads, and executes the command after --.",
+    options: [
+      {
+        flag: "--set <logical-key=value>",
+        description: "Apply inline logical-key overrides for this run without touching repo config files."
+      },
+      {
+        flag: "--public",
+        description: "Inject only promoted public env variables into the child process."
+      },
+      {
+        flag: "--framework <name>",
+        description: "When used with --public, apply framework-specific prefixes such as vite or next."
+      },
+      {
+        flag: "--prefix <prefix>",
+        description: "Override the generated public env prefix for --public runs."
+      }
+    ],
+    examples: [
+      "cnos run -- node server.js",
+      "cnos run --profile stage -- node server.js",
+      "cnos run --set value.server.port=9999 -- node server.js",
+      "cnos run --public --framework vite -- pnpm build"
+    ]
   },
   {
     id: "diff",
@@ -1095,17 +1355,25 @@ var INTEGRATIONS = [
     id: "vite",
     packageName: "@kitsy/cnos-vite",
     entrypoint: "@kitsy/cnos-vite",
-    summary: "Inject CNOS public env into Vite define replacements and import.meta.env.",
+    summary: "Inject CNOS public env into Vite and embed browser-readable CNOS public data.",
     usage: 'import { createCnosVitePlugin } from "@kitsy/cnos-vite"',
-    examples: ["cnos export env --public --framework vite", "vite.config.ts -> plugins: [createCnosVitePlugin()]"]
+    examples: [
+      "cnos export env --public --framework vite",
+      "vite.config.ts -> plugins: [createCnosVitePlugin()]",
+      'browser code -> import cnos from "@kitsy/cnos/browser"'
+    ]
   },
   {
     id: "next",
     packageName: "@kitsy/cnos-next",
     entrypoint: "@kitsy/cnos-next",
-    summary: "Merge CNOS public env into next.config.* using the NEXT_PUBLIC_ convention.",
+    summary: "Merge CNOS public env into Next and embed browser-readable CNOS public data.",
     usage: 'import { withCnosNext } from "@kitsy/cnos-next"',
-    examples: ["cnos export env --public --framework next", "next.config.mjs -> export default withCnosNext({})"]
+    examples: [
+      "cnos export env --public --framework next",
+      "next.config.mjs -> export default withCnosNext({})",
+      'browser code -> import cnos from "@kitsy/cnos/browser"'
+    ]
   }
 ];
 var HELP_DOCUMENT = {
@@ -1232,11 +1500,11 @@ function runHelpAi(topic, cliArgs = []) {
 }
 
 // src/commands/init.ts
-import path4 from "path";
+import path6 from "path";
 
 // src/services/scaffold.ts
-import { mkdir as mkdir2, readFile as readFile3, writeFile as writeFile2 } from "fs/promises";
-import path3 from "path";
+import { mkdir as mkdir3, readFile as readFile4, writeFile as writeFile4 } from "fs/promises";
+import path5 from "path";
 function scaffoldManifest(projectName, workspace) {
   const lines = [
     "version: 1",
@@ -1267,15 +1535,15 @@ function scaffoldManifest(projectName, workspace) {
 }
 async function ensureFile(filePath, content) {
   try {
-    await readFile3(filePath, "utf8");
+    await readFile4(filePath, "utf8");
     return false;
   } catch {
-    await writeFile2(filePath, content, "utf8");
+    await writeFile4(filePath, content, "utf8");
     return true;
   }
 }
 async function ensureGitignore(root) {
-  const gitignorePath = path3.join(root, ".gitignore");
+  const gitignorePath = path5.join(root, ".gitignore");
   const requiredEntries = [
     ".cnos/env/.env",
     ".cnos/env/.env.*",
@@ -1288,7 +1556,7 @@ async function ensureGitignore(root) {
   ];
   let current = "";
   try {
-    current = await readFile3(gitignorePath, "utf8");
+    current = await readFile4(gitignorePath, "utf8");
   } catch {
     current = "";
   }
@@ -1298,18 +1566,18 @@ async function ensureGitignore(root) {
   }
   const prefix = current.trim().length > 0 ? `${current.trimEnd()}
 ` : "";
-  await writeFile2(gitignorePath, `${prefix}${missingEntries.join("\n")}
+  await writeFile4(gitignorePath, `${prefix}${missingEntries.join("\n")}
 `, "utf8");
   return true;
 }
 async function scaffoldWorkspace(root, workspace) {
-  const cnosRoot = path3.join(root, ".cnos");
-  const workspaceRoot = workspace ? path3.join(cnosRoot, "workspaces", workspace) : cnosRoot;
+  const cnosRoot = path5.join(root, ".cnos");
+  const workspaceRoot = workspace ? path5.join(cnosRoot, "workspaces", workspace) : cnosRoot;
   const createdPaths = [];
-  await mkdir2(path3.join(workspaceRoot, "profiles"), { recursive: true });
-  await mkdir2(path3.join(workspaceRoot, "values"), { recursive: true });
-  await mkdir2(path3.join(workspaceRoot, "secrets"), { recursive: true });
-  await mkdir2(path3.join(workspaceRoot, "env"), { recursive: true });
+  await mkdir3(path5.join(workspaceRoot, "profiles"), { recursive: true });
+  await mkdir3(path5.join(workspaceRoot, "values"), { recursive: true });
+  await mkdir3(path5.join(workspaceRoot, "secrets"), { recursive: true });
+  await mkdir3(path5.join(workspaceRoot, "env"), { recursive: true });
   const relativePaths = workspace ? [
     ["workspaces", workspace, "profiles", ".gitkeep"],
     ["workspaces", workspace, "values", ".gitkeep"],
@@ -1322,15 +1590,15 @@ async function scaffoldWorkspace(root, workspace) {
     ["env", ".gitkeep"]
   ];
   for (const relativePath of relativePaths) {
-    const filePath = path3.join(cnosRoot, ...relativePath);
+    const filePath = path5.join(cnosRoot, ...relativePath);
     if (await ensureFile(filePath, "")) {
-      createdPaths.push(path3.relative(root, filePath).replace(/\\/g, "/"));
+      createdPaths.push(path5.relative(root, filePath).replace(/\\/g, "/"));
     }
   }
-  if (await ensureFile(path3.join(cnosRoot, "cnos.yml"), scaffoldManifest(path3.basename(root), workspace))) {
+  if (await ensureFile(path5.join(cnosRoot, "cnos.yml"), scaffoldManifest(path5.basename(root), workspace))) {
     createdPaths.push(".cnos/cnos.yml");
   }
-  if (workspace && await ensureFile(path3.join(root, ".cnos-workspace.yml"), `workspace: ${workspace}
+  if (workspace && await ensureFile(path5.join(root, ".cnos-workspace.yml"), `workspace: ${workspace}
 globalRoot: ~/.cnos
 `)) {
     createdPaths.push(".cnos-workspace.yml");
@@ -1347,7 +1615,7 @@ globalRoot: ~/.cnos
 
 // src/commands/init.ts
 async function runInit(options = {}) {
-  const root = path4.resolve(options.root ?? process.cwd());
+  const root = path6.resolve(options.root ?? process.cwd());
   const result = await scaffoldWorkspace(root, options.workspace);
   if (options.json) {
     return printJson(result);
@@ -1406,34 +1674,52 @@ function printValue(value, json = false) {
 
 // src/services/listing.ts
 import { flattenObject as flattenObject2 } from "@kitsy/cnos/internal";
+function matchesSecretFilter(candidate, filter) {
+  const secretRef = candidate.metadata?.secretRef;
+  if (filter.vault && secretRef?.vault !== filter.vault) {
+    return false;
+  }
+  if (filter.provider && secretRef?.provider !== filter.provider) {
+    return false;
+  }
+  return true;
+}
 function matchesPrefix(key, prefix) {
   if (!prefix) {
     return true;
   }
   return key.startsWith(prefix) || key.split(".").slice(1).join(".").startsWith(prefix);
 }
-function toStoredEntry(namespace, entry) {
+function toStoredEntry(namespace, entry, filter = {}) {
   const sourceId = namespace === "value" ? "filesystem-values" : "filesystem-secrets";
   const candidates = [entry.winner, ...entry.overridden].filter((candidate) => candidate.sourceId === sourceId);
   if (candidates.length === 0) {
     return void 0;
   }
+  const selectedCandidate = namespace === "secret" ? candidates.find((candidate) => matchesSecretFilter(candidate, filter)) : candidates[0];
+  if (!selectedCandidate) {
+    return void 0;
+  }
   return {
     key: entry.key,
-    value: candidates[0]?.value
+    value: selectedCandidate.value
   };
 }
 function listStoredNamespace(namespace, options) {
   return createRuntimeService(options).then(
-    (runtime) => Array.from(runtime.graph.entries.values()).filter((entry) => entry.namespace === namespace).map((entry) => toStoredEntry(namespace, entry)).filter((entry) => Boolean(entry)).filter((entry) => matchesPrefix(entry.key, options.prefix)).sort((left, right) => left.key.localeCompare(right.key))
+    (runtime) => Array.from(runtime.graph.entries.values()).filter((entry) => entry.namespace === namespace).map((entry) => toStoredEntry(namespace, entry, options)).filter((entry) => Boolean(entry)).filter((entry) => matchesPrefix(entry.key, options.prefix)).sort((left, right) => left.key.localeCompare(right.key))
   );
 }
 function listProjectedNamespace(namespace, options) {
   return createRuntimeService(options).then((runtime) => {
-    const projected = namespace === "meta" ? flattenObject2(runtime.toNamespace("meta")) : namespace === "env" ? runtime.manifest.envMapping.explicit : runtime.toPublicEnv();
-    const entries = namespace === "env" ? Object.entries(projected).map(([envVar, logicalKey]) => ({
+    const projected = namespace === "meta" ? flattenObject2(runtime.toNamespace("meta")) : namespace === "env" ? runtime.toEnv() : runtime.toPublicEnv({
+      ...options.framework ? {
+        framework: options.framework
+      } : {}
+    });
+    const entries = namespace === "env" ? Object.entries(projected).map(([envVar, value]) => ({
       key: envVar,
-      value: runtime.read(logicalKey)
+      value
     })) : Object.entries(projected).map(([key, value]) => ({
       key: namespace === "meta" ? `meta.${key}` : key,
       value
@@ -1482,10 +1768,12 @@ async function runList(args = [], options = {}) {
   const cliArgs = [...options.cliArgs ?? []];
   const namespace = normalizeNamespace(args[0] ?? consumeOption(cliArgs, "--namespace"));
   const prefix = consumeOption(cliArgs, "--prefix");
+  const framework = consumeOption(cliArgs, "--framework");
   const entries = await listConfigEntries(namespace, {
     ...options,
     cliArgs,
-    ...prefix ? { prefix } : {}
+    ...prefix ? { prefix } : {},
+    ...framework ? { framework } : {}
   });
   if (options.json) {
     return printJson(entries);
@@ -1497,34 +1785,34 @@ async function runList(args = [], options = {}) {
 }
 
 // src/commands/onboard.ts
-import { copyFile, readdir, rm as rm2 } from "fs/promises";
-import path5 from "path";
+import { copyFile, readdir, rm as rm3 } from "fs/promises";
+import path7 from "path";
 var ROOT_ENV_FILE_PATTERN = /^\.env(?:\.[A-Za-z0-9_-]+)*(?:\.example)?$/;
 async function listRootEnvFiles(root) {
   const entries = await readdir(root, { withFileTypes: true });
   return entries.filter((entry) => entry.isFile() && ROOT_ENV_FILE_PATTERN.test(entry.name)).map((entry) => entry.name).sort((left, right) => left.localeCompare(right));
 }
 async function runOnboard(options = {}) {
-  const root = path5.resolve(options.root ?? process.cwd());
-  const workspace = options.workspace ?? path5.basename(root);
+  const root = path7.resolve(options.root ?? process.cwd());
+  const workspace = options.workspace ?? path7.basename(root);
   const cliArgs = [...options.cliArgs ?? []];
   const move = consumeFlag(cliArgs, "--move");
   if (cliArgs.length > 0) {
     throw new Error(`Unsupported onboard arguments: ${cliArgs.join(" ")}`);
   }
   const scaffold = await scaffoldWorkspace(root, workspace);
-  const envRoot = path5.join(root, ".cnos", "workspaces", workspace, "env");
+  const envRoot = path7.join(root, ".cnos", "workspaces", workspace, "env");
   const rootFiles = await listRootEnvFiles(root);
   const imported = [];
   const skipped = [];
   for (const fileName of rootFiles) {
-    const sourcePath = path5.join(root, fileName);
-    const targetPath = path5.join(envRoot, fileName);
+    const sourcePath = path7.join(root, fileName);
+    const targetPath = path7.join(envRoot, fileName);
     try {
       await copyFile(sourcePath, targetPath);
-      imported.push(path5.relative(root, targetPath).replace(/\\/g, "/"));
+      imported.push(path7.relative(root, targetPath).replace(/\\/g, "/"));
       if (move) {
-        await rm2(sourcePath);
+        await rm3(sourcePath);
       }
     } catch {
       skipped.push(fileName);
@@ -1547,16 +1835,16 @@ async function runOnboard(options = {}) {
 }
 
 // src/commands/profile.ts
-import path8 from "path";
+import path10 from "path";
 
 // src/services/context.ts
-import { readFile as readFile4, writeFile as writeFile3 } from "fs/promises";
-import path6 from "path";
-import { parseYaml as parseYaml2, stringifyYaml as stringifyYaml2 } from "@kitsy/cnos/internal";
+import { readFile as readFile5, writeFile as writeFile5 } from "fs/promises";
+import path8 from "path";
+import { parseYaml as parseYaml2, stringifyYaml as stringifyYaml3 } from "@kitsy/cnos/internal";
 async function loadCliContext(root = process.cwd()) {
-  const filePath = path6.join(path6.resolve(root), ".cnos-workspace.yml");
+  const filePath = path8.join(path8.resolve(root), ".cnos-workspace.yml");
   try {
-    const source = await readFile4(filePath, "utf8");
+    const source = await readFile5(filePath, "utf8");
     const parsed = parseYaml2(source);
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
       return {};
@@ -1567,8 +1855,8 @@ async function loadCliContext(root = process.cwd()) {
   }
 }
 async function saveCliContext(options = {}) {
-  const root = path6.resolve(options.root ?? process.cwd());
-  const filePath = path6.join(root, ".cnos-workspace.yml");
+  const root = path8.resolve(options.root ?? process.cwd());
+  const filePath = path8.join(root, ".cnos-workspace.yml");
   const current = await loadCliContext(root);
   const next = {
     ...current.workspace ? { workspace: current.workspace } : {},
@@ -1578,7 +1866,7 @@ async function saveCliContext(options = {}) {
     ...options.profile ? { profile: options.profile } : {},
     ...options.globalRoot ? { globalRoot: options.globalRoot } : {}
   };
-  await writeFile3(filePath, stringifyYaml2(next), "utf8");
+  await writeFile5(filePath, stringifyYaml3(next), "utf8");
   return {
     filePath,
     context: next
@@ -1586,19 +1874,19 @@ async function saveCliContext(options = {}) {
 }
 
 // src/services/profiles.ts
-import { mkdir as mkdir3, readdir as readdir2, readFile as readFile5, rm as rm3, writeFile as writeFile4 } from "fs/promises";
-import path7 from "path";
-import { parseYaml as parseYaml3, stringifyYaml as stringifyYaml3 } from "@kitsy/cnos/internal";
+import { mkdir as mkdir4, readdir as readdir2, readFile as readFile6, rm as rm4, writeFile as writeFile6 } from "fs/promises";
+import path9 from "path";
+import { parseYaml as parseYaml3, stringifyYaml as stringifyYaml4 } from "@kitsy/cnos/internal";
 async function createProfileDefinition(root = process.cwd(), profile, inherit) {
-  const filePath = path7.join(path7.resolve(root), ".cnos", "profiles", `${profile}.yml`);
-  await mkdir3(path7.dirname(filePath), { recursive: true });
+  const filePath = path9.join(path9.resolve(root), ".cnos", "profiles", `${profile}.yml`);
+  await mkdir4(path9.dirname(filePath), { recursive: true });
   const document = inherit && inherit !== "base" ? {
     name: profile,
     extends: [inherit]
   } : {
     name: profile
   };
-  await writeFile4(filePath, stringifyYaml3(document), "utf8");
+  await writeFile6(filePath, stringifyYaml4(document), "utf8");
   return {
     filePath,
     profile,
@@ -1606,7 +1894,7 @@ async function createProfileDefinition(root = process.cwd(), profile, inherit) {
   };
 }
 async function listProfiles(root = process.cwd()) {
-  const profilesRoot = path7.join(path7.resolve(root), ".cnos", "profiles");
+  const profilesRoot = path9.join(path9.resolve(root), ".cnos", "profiles");
   try {
     const entries = await readdir2(profilesRoot, { withFileTypes: true });
     const discovered = /* @__PURE__ */ new Set(["base"]);
@@ -1621,9 +1909,9 @@ async function listProfiles(root = process.cwd()) {
   }
 }
 async function deleteProfileDefinition(root = process.cwd(), profile) {
-  const filePath = path7.join(path7.resolve(root), ".cnos", "profiles", `${profile}.yml`);
+  const filePath = path9.join(path9.resolve(root), ".cnos", "profiles", `${profile}.yml`);
   try {
-    await rm3(filePath);
+    await rm4(filePath);
     return {
       filePath,
       deleted: true
@@ -1641,9 +1929,9 @@ async function readProfileDefinition(root = process.cwd(), profile = "base") {
       name: "base"
     };
   }
-  const filePath = path7.join(path7.resolve(root), ".cnos", "profiles", `${profile}.yml`);
+  const filePath = path9.join(path9.resolve(root), ".cnos", "profiles", `${profile}.yml`);
   try {
-    return parseYaml3(await readFile5(filePath, "utf8")) ?? void 0;
+    return parseYaml3(await readFile6(filePath, "utf8")) ?? void 0;
   } catch {
     return void 0;
   }
@@ -1665,7 +1953,7 @@ function normalizeProfileAction(args) {
 }
 async function runProfile(args, options = {}) {
   const { action, tail } = normalizeProfileAction(args);
-  const root = path8.resolve(options.root ?? process.cwd());
+  const root = path10.resolve(options.root ?? process.cwd());
   const cliArgs = [...options.cliArgs ?? []];
   if (action === "create") {
     const profile = tail[0] ?? "stage";
@@ -1708,6 +1996,73 @@ async function runProfile(args, options = {}) {
   return profiles.join("\n");
 }
 
+// src/commands/promote.ts
+import { writeFile as writeFile7 } from "fs/promises";
+import {
+  ensureProjectionAllowed,
+  loadManifest as loadManifest2,
+  stringifyYaml as stringifyYaml5
+} from "@kitsy/cnos/internal";
+function normalizeTarget(value) {
+  if (value === "public" || value === "env") {
+    return value;
+  }
+  throw new Error("promote requires --to public|env");
+}
+function sortRecord(record) {
+  return Object.fromEntries(Object.entries(record).sort(([left], [right]) => left.localeCompare(right)));
+}
+async function runPromote(args = [], options = {}) {
+  const cliArgs = [...options.cliArgs ?? []];
+  const target = normalizeTarget(consumeOption(cliArgs, "--to"));
+  const alias = consumeOption(cliArgs, "--as");
+  const keys = args.filter(Boolean);
+  if (keys.length === 0) {
+    throw new Error("promote requires at least one logical key");
+  }
+  if (target === "env") {
+    if (keys.length !== 1) {
+      throw new Error("promote --to env requires exactly one logical key");
+    }
+    if (!alias) {
+      throw new Error("promote --to env requires --as <ENV_VAR>");
+    }
+  }
+  const loadedManifest = await loadManifest2(options.root ? { root: options.root } : {});
+  for (const key of keys) {
+    ensureProjectionAllowed(loadedManifest.manifest, key, target);
+  }
+  const rawManifest = {
+    ...loadedManifest.rawManifest
+  };
+  if (target === "public") {
+    rawManifest.public = {
+      ...rawManifest.public ?? {},
+      promote: Array.from(/* @__PURE__ */ new Set([...rawManifest.public?.promote ?? [], ...keys])).sort(
+        (left, right) => left.localeCompare(right)
+      )
+    };
+  } else {
+    rawManifest.envMapping = {
+      ...rawManifest.envMapping ?? {},
+      explicit: sortRecord({
+        ...rawManifest.envMapping?.explicit ?? {},
+        [alias]: keys[0]
+      })
+    };
+  }
+  await writeFile7(loadedManifest.manifestPath, stringifyYaml5(rawManifest), "utf8");
+  if (options.json) {
+    return printJson({
+      target,
+      keys,
+      ...target === "env" ? { envVar: alias } : {},
+      manifestPath: loadedManifest.manifestPath
+    });
+  }
+  return target === "public" ? `promoted ${keys.join(", ")} to public in ${loadedManifest.manifestPath}` : `promoted ${keys[0]} to env as ${alias} in ${loadedManifest.manifestPath}`;
+}
+
 // src/commands/read.ts
 async function runRead(key, options = {}) {
   const runtime = await createRuntimeService(options);
@@ -1723,14 +2078,60 @@ async function runRead(key, options = {}) {
 
 // src/commands/run.ts
 import { spawn } from "child_process";
+import {
+  CNOS_GRAPH_ENV_VAR,
+  serializeRuntimeGraph
+} from "@kitsy/cnos/internal";
+function consumeOptions(args, flag) {
+  const values = [];
+  for (let index = 0; index < args.length; ) {
+    const token = args[index];
+    if (token === flag) {
+      const value = args[index + 1];
+      if (!value) {
+        throw new Error(`Missing value for ${flag}`);
+      }
+      values.push(value);
+      args.splice(index, 2);
+      continue;
+    }
+    if (token?.startsWith(`${flag}=`)) {
+      values.push(token.slice(flag.length + 1));
+      args.splice(index, 1);
+      continue;
+    }
+    index += 1;
+  }
+  return values;
+}
+function normalizeSetOverrides(values) {
+  return values.map((value) => {
+    if (!value.includes("=")) {
+      throw new Error("--set requires <logical-key>=<value>");
+    }
+    return value.startsWith("--") ? value : `--${value}`;
+  });
+}
 async function runCommand(command, options = {}) {
   if (command.length === 0) {
     throw new Error("run requires a command after --");
   }
-  const runtime = await createRuntimeService(options);
+  const cliArgs = [...options.cliArgs ?? []];
+  const isPublic = consumeFlag(cliArgs, "--public");
+  const framework = consumeOption(cliArgs, "--framework");
+  const prefix = consumeOption(cliArgs, "--prefix");
+  const setOverrides = normalizeSetOverrides(consumeOptions(cliArgs, "--set"));
+  const runtime = await createRuntimeService({
+    ...options,
+    cliArgs: [...cliArgs, ...setOverrides]
+  });
   const env = {
     ...process.env,
-    ...runtime.toEnv()
+    ...isPublic ? runtime.toPublicEnv({
+      ...framework ? { framework } : {},
+      ...prefix ? { prefix } : {}
+    }) : runtime.toEnv(),
+    [CNOS_GRAPH_ENV_VAR]: serializeRuntimeGraph(runtime.graph)
   };
   return new Promise((resolve, reject) => {
     const executable = command[0];
@@ -1765,6 +2166,68 @@ async function runCommand(command, options = {}) {
   });
 }
 
+// src/commands/vault.ts
+function normalizeVaultAction(args) {
+  const [action = "list", ...tail] = args;
+  if (["create", "add", "list", "delete", "remove"].includes(action)) {
+    return {
+      action: action === "add" || action === "create" ? "create" : action === "delete" || action === "remove" ? "remove" : "list",
+      tail
+    };
+  }
+  return {
+    action: "list",
+    tail: args
+  };
+}
+async function runVault(args = [], options = {}) {
+  const { action, tail } = normalizeVaultAction(args);
+  const cliArgs = [...options.cliArgs ?? []];
+  if (action === "create") {
+    const name = tail[0] ?? "default";
+    const provider = consumeOption(cliArgs, "--provider") ?? "local";
+    const passphrase = consumeOption(cliArgs, "--passphrase");
+    const noPassphrase = consumeFlag(cliArgs, "--no-passphrase");
+    const result = await createVaultDefinition(name, {
+      ...options,
+      cliArgs,
+      provider,
+      ...passphrase ? { passphrase } : {},
+      ...noPassphrase ? { noPassphrase: true } : {}
+    });
+    if (options.json) {
+      return printJson(result);
+    }
+    return `created vault "${result.name}" with provider "${result.provider}" in ${result.manifestPath}`;
+  }
+  if (action === "remove") {
+    const name = tail[0] ?? "default";
+    const result = await removeVaultDefinition(name, options);
+    if (options.json) {
+      return printJson(result);
+    }
+    return result.deleted ? `removed vault "${result.name}"` : `vault "${result.name}" was not found`;
+  }
+  const [manifestVaults, localStoreVaults] = await Promise.all([
+    listVaultDefinitions(options),
+    listLocalStoreVaults(options)
+  ]);
+  if (options.json) {
+    return printJson(
+      manifestVaults.map((vault) => ({
+        ...vault,
+        localStore: localStoreVaults.includes(vault.name)
+      }))
+    );
+  }
+  if (manifestVaults.length === 0) {
+    return "";
+  }
+  return manifestVaults.map(
+    (vault) => `${vault.name} provider=${vault.provider} passphrase=${vault.passphrasePolicy}${localStoreVaults.includes(vault.name) ? " local-store=true" : ""}`
+  ).join("\n");
+}
+
 // src/commands/secret.ts
 function isSecretRef(value) {
   return Boolean(
@@ -1801,32 +2264,26 @@ async function runSecret(argsOrPath, options = {}) {
   const { action, tail } = normalizeSecretCommand(args);
   const cliArgs = [...options.cliArgs ?? []];
   if (action === "create-vault") {
-    const vault = tail[0] ?? "default";
-    const passphrase = consumeOption(cliArgs, "--passphrase");
-    const result = await createVault(vault, {
-      ...options,
-      cliArgs,
-      ...passphrase ? { passphrase } : {}
-    });
-    if (options.json) {
-      return printJson(result);
-    }
-    return `created secret vault "${result.vault}" in ${result.filePath}`;
+    return runVault(["create", tail[0] ?? "default"], options);
   }
   if (action === "list") {
     const prefix = consumeOption(cliArgs, "--prefix");
+    const vault = consumeOption(cliArgs, "--vault");
+    const provider = consumeOption(cliArgs, "--provider");
     const entries = await listConfigEntries("secret", {
       ...options,
       cliArgs,
-      ...prefix ? { prefix } : {}
+      ...prefix ? { prefix } : {},
+      ...vault ? { vault } : {},
+      ...provider ? { provider } : {}
     });
     if (options.json) {
       return printJson(entries);
     }
-    return entries.map((entry) => `${entry.key}=${printValue(entry.value)}`).join("\n");
+    return entries.map((entry2) => `${entry2.key}=${printValue(entry2.value)}`).join("\n");
   }
   if (action === "set") {
-    const secretPath = tail[0];
+    const secretPath2 = tail[0];
     const rawValue = tail[1] ?? "";
     const local = consumeFlag(cliArgs, "--local");
     const remote = consumeFlag(cliArgs, "--remote");
@@ -1835,25 +2292,25 @@ async function runSecret(argsOrPath, options = {}) {
     const provider = consumeOption(cliArgs, "--provider");
     const passphrase = consumeOption(cliArgs, "--passphrase");
     const vault = consumeOption(cliArgs, "--vault") ?? "default";
-    const mode = local ? "local" : remote ? "remote" : ref ? "ref" : "local";
-    const result = await setSecret(secretPath ?? "app.token", rawValue, {
+    const mode = local ? "local" : remote ? "remote" : ref ? "ref" : void 0;
+    const result = await setSecret(secretPath2 ?? "app.token", rawValue, {
       ...options,
       cliArgs,
       target,
-      mode,
       vault,
+      ...mode ? { mode } : {},
       ...provider ? { provider } : {},
       ...passphrase ? { passphrase } : {}
     });
     if (options.json) {
       return printJson(result);
     }
-    return result.provider === "local" ? `set secret.${secretPath} in vault "${result.vault ?? "default"}" with ref "${result.ref}" and repo pointer ${result.filePath}` : `set secret.${secretPath} via ${result.provider} in ${result.filePath}`;
+    return result.provider === "local" ? `set secret.${secretPath2} in vault "${result.vault ?? "default"}" with ref "${result.ref}" and repo pointer ${result.filePath}` : `set secret.${secretPath2} via ${result.provider} in ${result.filePath}`;
   }
   if (action === "delete") {
-    const secretPath = tail[0];
+    const secretPath2 = tail[0];
     const target = consumeOption(cliArgs, "--target") ?? "local";
-    const result = await deleteSecret(secretPath ?? "app.token", {
+    const result = await deleteSecret(secretPath2 ?? "app.token", {
       ...options,
       cliArgs,
       target
@@ -1861,22 +2318,37 @@ async function runSecret(argsOrPath, options = {}) {
     if (options.json) {
       return printJson(result);
     }
-    return result.deleted ? `deleted secret.${secretPath} from ${result.filePath}` : `no secret.${secretPath} found in ${result.filePath}`;
+    return result.deleted ? `deleted secret.${secretPath2} from ${result.filePath}` : `no secret.${secretPath2} found in ${result.filePath}`;
   }
   const runtime = await createRuntimeService(options);
-  const value = runtime.secret(tail[0] ?? "app.token");
+  const secretPath = tail[0] ?? "app.token";
+  const expectedVault = consumeOption(cliArgs, "--vault");
+  const entry = runtime.graph.entries.get(`secret.${secretPath}`);
+  const secretRef = entry?.winner.metadata?.secretRef;
+  const value = runtime.secret(secretPath);
   if (value === void 0) {
-    throw new Error(`Missing CNOS secret path: ${tail[0] ?? "app.token"}`);
+    throw new Error(`Missing CNOS secret path: ${secretPath}`);
+  }
+  if (expectedVault && secretRef?.vault && secretRef.vault !== expectedVault) {
+    throw new Error(`Secret ${secretPath} belongs to vault "${secretRef.vault}", not "${expectedVault}"`);
   }
   if (isSecretRef(value)) {
-    const vault = value.vault ?? "default";
-    throw new Error(
-      `Secret ${tail[0] ?? "app.token"} is stored in vault "${vault}" as ref "${value.ref}". Provide the correct vault passphrase to resolve it.`
-    );
+    if (value.provider === "local") {
+      const vault = value.vault ?? "default";
+      throw new Error(
+        `Secret ${secretPath} is stored in vault "${vault}" as ref "${value.ref}". Provide the correct vault passphrase to resolve it.`
+      );
+    }
+    if (value.provider === "github-secrets") {
+      throw new Error(
+        `Secret ${secretPath} is backed by GitHub secrets via ref "${value.ref}". Set that env var in the current process or CI job to resolve it.`
+      );
+    }
+    throw new Error(`Secret ${secretPath} is stored as a ${value.provider} reference "${value.ref}" and is not resolved.`);
   }
   if (options.json) {
     return printJson({
-      key: `secret.${tail[0] ?? "app.token"}`,
+      key: `secret.${secretPath}`,
       value
     });
   }
@@ -1884,9 +2356,9 @@ async function runSecret(argsOrPath, options = {}) {
 }
 
 // src/commands/use.ts
-import path9 from "path";
+import path11 from "path";
 async function runUse(args = [], options = {}) {
-  const root = path9.resolve(options.root ?? process.cwd());
+  const root = path11.resolve(options.root ?? process.cwd());
   const action = args[0] ?? "show";
   const hasUpdates = Boolean(options.workspace || options.profile || options.globalRoot);
   if (action === "show" || !hasUpdates) {
@@ -1923,7 +2395,7 @@ async function runValidate(options = {}) {
 // package.json
 var package_default = {
   name: "@kitsy/cnos-cli",
-  version: "1.1.1",
+  version: "1.2.0",
   description: "CLI entry point and developer tooling for CNOS.",
   type: "module",
   main: "./dist/index.js",
@@ -2068,6 +2540,9 @@ function resolveHelpTopic(command, args) {
   if (command === "export" && args[0] === "env") {
     return normalizeHelpTopic([command, args[0]]);
   }
+  if (command === "vault" && args[0] && ["create", "add", "list", "delete", "remove"].includes(args[0])) {
+    return normalizeHelpTopic([command, args[0] === "delete" ? "remove" : args[0] === "add" ? "create" : args[0]]);
+  }
   if (command === "secret" && args[0] && ["set", "create", "add", "list", "delete", "remove"].includes(args[0])) {
     if ((args[0] === "create" || args[0] === "add") && args[1] === "vault") {
       return normalizeHelpTopic(["secret", "create", "vault"]);
@@ -2149,6 +2624,10 @@ async function main(argv) {
       return;
     case "secret":
       process.stdout.write(`${await runSecret(args.length > 0 ? args : ["app.token"], runtimeOptions)}
+`);
+      return;
+    case "vault":
+      process.stdout.write(`${await runVault(args, runtimeOptions)}
 `);
       return;
     case "use":
@@ -2157,6 +2636,10 @@ async function main(argv) {
       return;
     case "profile":
       process.stdout.write(`${await runProfile(args, runtimeOptions)}
+`);
+      return;
+    case "promote":
+      process.stdout.write(`${await runPromote(args, runtimeOptions)}
 `);
       return;
     case "list":