@kitsy/cnos-cli 1.9.1 → 1.10.0

package/dist/index.js

@@ -33,7 +33,16 @@ var COMMAND_OPTION_KEYS_WITH_VALUE = /* @__PURE__ */ new Set([
   "--env",
   "--yaml",
   "--toml",
-  "--config"
+  "--config",
+  "--type",
+  "--default",
+  "--enum",
+  "--pattern",
+  "--summary",
+  "--description",
+  "--example",
+  "--used-by",
+  "--deprecation-message"
 ]);
 var COMMAND_FLAG_KEYS = /* @__PURE__ */ new Set([
   "--flatten",
@@ -56,7 +65,21 @@ var COMMAND_FLAG_KEYS = /* @__PURE__ */ new Set([
   "--materialize",
   "--source-only",
   "--allow-secret",
-  "--fix-secret-env-mappings"
+  "--fix-secret-env-mappings",
+  "--required",
+  "--optional",
+  "--deprecated",
+  "--clear-default",
+  "--clear-enum",
+  "--clear-pattern",
+  "--clear-summary",
+  "--clear-description",
+  "--clear-examples",
+  "--clear-used-by",
+  "--clear-deprecated",
+  "--clear-deprecation-message",
+  "--fill-missing",
+  "--review-all"
 ]);
 function normalizeCommand(argv) {
   const [command = "doctor", ...rest] = argv;
@@ -263,9 +286,37 @@ function consumeOption(args, flag) {
   }
   return void 0;
 }
+function consumeOptions(args, flag) {
+  const values = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+    if (!token) {
+      continue;
+    }
+    if (token.startsWith(`${flag}=`)) {
+      values.push(token.slice(flag.length + 1));
+      args.splice(index, 1);
+      index -= 1;
+      continue;
+    }
+    if (token === flag) {
+      const value = args[index + 1];
+      if (!value) {
+        throw new Error(`Missing value for ${flag}`);
+      }
+      values.push(value);
+      args.splice(index, 2);
+      index -= 1;
+    }
+  }
+  return values;
+}
 
 // src/format/displayPath.ts
 import path from "path";
+function toPortablePath(filePath) {
+  return filePath.replace(/\\/g, "/");
+}
 function displayPath(filePath, root = process.cwd()) {
   const absoluteRoot = path.resolve(root);
   const absoluteFile = path.resolve(filePath);
@@ -274,9 +325,9 @@ function displayPath(filePath, root = process.cwd()) {
     return ".";
   }
   if (relative.startsWith("..") || path.isAbsolute(relative)) {
-    return absoluteFile;
+    return toPortablePath(absoluteFile);
   }
-  return relative;
+  return toPortablePath(relative);
 }
 
 // src/format/printJson.ts
@@ -290,6 +341,52 @@ import path4 from "path";
 import { resolveBrowserData, resolveFrameworkEnv, resolveServerProjection } from "@kitsy/cnos/build";
 import { stringifyYaml } from "@kitsy/cnos/internal";
 
+// src/services/envSerialization.ts
+var DOTENV_SAFE_UNQUOTED = /^[A-Za-z0-9_./:@%+*-]+$/;
+function escapeDoubleQuoted(value) {
+  return value.replace(/\\/g, "\\\\").replace(/\r/g, "\\r").replace(/\n/g, "\\n").replace(/\t/g, "\\t").replace(/"/g, '\\"');
+}
+function requiresDotenvQuoting(value) {
+  return value.length === 0 || !DOTENV_SAFE_UNQUOTED.test(value) || value.includes(" ") || value.includes("#") || value.includes("$");
+}
+function quoteDotenv(value) {
+  if (!requiresDotenvQuoting(value)) {
+    return value;
+  }
+  return `"${escapeDoubleQuoted(value)}"`;
+}
+function quoteToml(value) {
+  return `"${escapeDoubleQuoted(value)}"`;
+}
+function quoteShell(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function stringifyScalar(value) {
+  if (value === void 0 || value === null) {
+    return "";
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return String(value);
+  }
+  return JSON.stringify(value);
+}
+function formatEnvEntries(values, format = "dotenv") {
+  const entries = Object.entries(values).sort(([left], [right]) => left.localeCompare(right));
+  switch (format) {
+    case "shell":
+      return entries.map(([key, value]) => `export ${key}=${quoteShell(stringifyScalar(value))}`).join("\n");
+    case "toml":
+      return entries.map(([key, value]) => `${key} = ${quoteToml(stringifyScalar(value))}`).join("\n");
+    case "docker-env":
+    case "dotenv":
+    default:
+      return entries.map(([key, value]) => `${key}=${quoteDotenv(stringifyScalar(value))}`).join("\n");
+  }
+}
+
 // src/services/runtime.ts
 import { createCnos } from "@kitsy/cnos/configure";
 async function createRuntimeService(options = {}) {
@@ -319,7 +416,7 @@ function resolveFilesystemBasePath(root, cwd = process.cwd()) {
 }
 
 // src/services/secretEnvBuild.ts
-import { readFile } from "fs/promises";
+import { readFile, realpath } from "fs/promises";
 import path3 from "path";
 import readline from "readline/promises";
 import { spawnSync } from "child_process";
@@ -375,8 +472,28 @@ function isGitIgnored(repoRoot, targetPath) {
   });
   return result.status === 0;
 }
-async function assertSecretEnvTargetIsGitIgnored(targetPath, cwd) {
+async function resolveCanonicalRepoRoot(cwd) {
   const repoRoot = resolveGitRoot(cwd);
+  if (!repoRoot) {
+    return void 0;
+  }
+  try {
+    return await realpath(repoRoot);
+  } catch {
+    return path3.resolve(repoRoot);
+  }
+}
+async function resolveCanonicalTargetPath(targetPath) {
+  const resolvedPath = path3.resolve(targetPath);
+  try {
+    const resolvedDir = await realpath(path3.dirname(resolvedPath));
+    return path3.join(resolvedDir, path3.basename(resolvedPath));
+  } catch {
+    return resolvedPath;
+  }
+}
+async function assertSecretEnvTargetIsGitIgnored(targetPath, cwd) {
+  const repoRoot = await resolveCanonicalRepoRoot(cwd);
   if (!repoRoot) {
     throw new Error(
       `Cannot write revealed secrets to ${targetPath} because CNOS could not verify gitignore protection. Run inside a git repo or omit --reveal.`
@@ -390,8 +507,9 @@ async function assertSecretEnvTargetIsGitIgnored(targetPath, cwd) {
       `Cannot write revealed secrets to ${targetPath} because ${gitignorePath} is missing. Add a gitignored env target or omit --reveal.`
     );
   }
-  if (!isGitIgnored(repoRoot, targetPath)) {
-    const relativeTarget = path3.relative(repoRoot, targetPath).replace(/\\/g, "/");
+  const canonicalTargetPath = await resolveCanonicalTargetPath(targetPath);
+  if (!isGitIgnored(repoRoot, canonicalTargetPath)) {
+    const relativeTarget = path3.relative(repoRoot, canonicalTargetPath).replace(/\\/g, "/");
     throw new Error(
       `Cannot write revealed secrets to ${targetPath} because ${relativeTarget} is not gitignored. Add an ignore rule first, then re-run cnos build env --reveal.`
     );
@@ -417,24 +535,6 @@ async function confirmSecretEnvBuild(targetPath, mappings) {
 }
 
 // src/services/projections.ts
-function stringifyScalar(value) {
-  if (value === void 0 || value === null) {
-    return "";
-  }
-  if (typeof value === "string") {
-    return value;
-  }
-  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
-    return String(value);
-  }
-  return JSON.stringify(value);
-}
-function escapeShell(value) {
-  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
-}
-function quoteToml(value) {
-  return `"${escapeShell(value)}"`;
-}
 function formatKeyValueMap(values, format) {
   const entries = Object.entries(values).sort(([left], [right]) => left.localeCompare(right));
   switch (format) {
@@ -444,13 +544,13 @@ function formatKeyValueMap(values, format) {
     case "yaml":
       return stringifyYaml(Object.fromEntries(entries));
     case "shell":
-      return entries.map(([key, value]) => `export ${key}="${escapeShell(stringifyScalar(value))}"`).join("\n");
+      return formatEnvEntries(Object.fromEntries(entries), "shell");
     case "toml":
-      return entries.map(([key, value]) => `${key} = ${quoteToml(stringifyScalar(value))}`).join("\n");
+      return formatEnvEntries(Object.fromEntries(entries), "toml");
     case "docker-env":
     case "dotenv":
     default:
-      return entries.map(([key, value]) => `${key}=${stringifyScalar(value)}`).join("\n");
+      return formatEnvEntries(Object.fromEntries(entries), format);
   }
 }
 async function writeProjectionFile(to, output, root = process.cwd()) {
@@ -1070,7 +1170,7 @@ function resolveEnvFromRuntime(runtime, cliArgs = []) {
   }) : runtime.toEnv();
 }
 function formatEnvOutput(env) {
-  return Object.entries(env).sort(([left], [right]) => left.localeCompare(right)).map(([key, value]) => `${key}=${value}`).join("\n");
+  return formatEnvEntries(env, "dotenv");
 }
 async function resolveMaterializedEnv(options = {}) {
   const runtime = await createRuntimeService({
@@ -1158,6 +1258,17 @@ async function startGraphWatchLoop(options) {
           }, debounceMs);
         }
       );
+      watcher.on("error", (error) => {
+        if (closed) {
+          return;
+        }
+        if (recursive && (error.code === "EMFILE" || error.code === "ENOSPC")) {
+          watcherMap.delete(targetPath);
+          watcher.close();
+          attachWatcher(targetPath, false);
+          return;
+        }
+      });
       watcherMap.set(targetPath, watcher);
     } catch {
       if (recursive) {
@@ -1349,6 +1460,9 @@ async function runDiff(leftProfile, rightProfile, options = {}) {
   return rows.map((row) => `${row.key}: ${JSON.stringify(row.left)} -> ${JSON.stringify(row.right)}`).join("\n");
 }
 
+// src/commands/doctor.ts
+import { loadManifest as loadManifest4 } from "@kitsy/cnos/internal";
+
 // src/services/doctor.ts
 import { readdir as readdir2, readFile as readFile3, writeFile as writeFile4 } from "fs/promises";
 import path9 from "path";
@@ -1563,6 +1677,16 @@ async function runDoctor(options = {}) {
   const cliArgs = [...options.cliArgs ?? []];
   const shouldFixSecretEnvMappings = cliArgs.includes("--fix-secret-env-mappings");
   const repairResult = shouldFixSecretEnvMappings ? await repairSecretEnvMappings(options) : void 0;
+  const loadedManifest = await loadManifest4({
+    ...options.root ? { root: options.root } : {},
+    ...options.cwd ? { cwd: options.cwd } : {},
+    ...options.processEnv ? { processEnv: options.processEnv } : {},
+    ...options.cacheMode ? { cacheMode: options.cacheMode } : {},
+    ...typeof options.cacheTtlSeconds === "number" ? { cacheTtlSeconds: options.cacheTtlSeconds } : {},
+    ...options.forceRefresh ? { forceRefresh: true } : {}
+  });
+  const hasSchema = Object.keys(loadedManifest.manifest.schema).length > 0;
+  const specPointer = hasSchema ? "Run cnos spec doctor to review config spec coverage." : void 0;
   const checks = await evaluateDoctor(options);
   const hasFailures = checks.some((check) => !check.ok);
   if (hasFailures) {
@@ -1571,11 +1695,12 @@ async function runDoctor(options = {}) {
   if (options.json) {
     return printJson({
       ...repairResult ? { repair: repairResult } : {},
-      checks
+      checks,
+      ...specPointer ? { guidance: [specPointer] } : {}
     });
   }
   const repairLine = repairResult ? repairResult.removed.length > 0 ? `REPAIRED secret-env-mappings: removed ${repairResult.removed.map((entry) => `${entry.envVar} -> ${entry.logicalKey}`).join(", ")}` : "REPAIRED secret-env-mappings: no secret env mappings found" : void 0;
-  return [repairLine, ...checks.map((check) => `${check.ok ? "OK" : "FAIL"} ${check.name}: ${check.details}`)].filter((value) => Boolean(value)).join("\n");
+  return [repairLine, ...checks.map((check) => `${check.ok ? "OK" : "FAIL"} ${check.name}: ${check.details}`), specPointer].filter((value) => Boolean(value)).join("\n");
 }
 
 // src/commands/dump.ts
@@ -1603,6 +1728,9 @@ async function runDump(options = {}) {
 
 // src/commands/codegen.ts
 import { watchSchema, writeCodegenOutput } from "@kitsy/cnos/internal";
+function formatPortablePath(filePath) {
+  return filePath.replace(/\\/g, "/");
+}
 async function runCodegen(options = {}) {
   const cliArgs = [...options.cliArgs ?? []];
   const out = consumeOption(cliArgs, "--out");
@@ -1629,7 +1757,7 @@ async function runCodegen(options = {}) {
     };
     process.once("SIGINT", closeWatcher);
     process.once("SIGTERM", closeWatcher);
-    return `watching schema changes -> ${out ?? ".cnos/types/cnos.d.ts"}`;
+    return `watching schema changes -> ${formatPortablePath(out ?? ".cnos/types/cnos.d.ts")}`;
   }
   const result = await writeCodegenOutput({
     ...options.root ? {
@@ -1640,7 +1768,7 @@ async function runCodegen(options = {}) {
     } : {}
   });
   const summary = result.hasSchema ? `generated types from ${result.schemaEntryCount} schema entr${result.schemaEntryCount === 1 ? "y" : "ies"}` : "generated empty types (no schema section found)";
-  return `${summary} -> ${result.typesPath} and ${result.runtimePath}`;
+  return `${summary} -> ${formatPortablePath(result.typesPath)} and ${formatPortablePath(result.runtimePath)}`;
 }
 
 // src/commands/exportEnv.ts
@@ -2070,6 +2198,150 @@ var COMMANDS = [
       "cnos define secret app.token super-secret --workspace api"
     ]
   },
+  {
+    id: "spec",
+    summary: "Author and inspect manifest-global config specs stored under schema.",
+    usage: "cnos spec [list | show <logicalKey> | set <logicalKey> | delete <logicalKey> | doctor] [options] [global-options]",
+    description: 'Manages CNOS config specs (user-facing "spec") stored in the manifest schema: block. Use cnos define/value/secret for concrete value authoring.',
+    examples: [
+      "cnos spec list",
+      "cnos spec show value.server.port",
+      'cnos spec set value.server.port --type number --required --summary "HTTP server port"',
+      "cnos spec delete value.legacy.flag",
+      "cnos spec doctor"
+    ]
+  },
+  {
+    id: "spec list",
+    summary: "List declared spec entries.",
+    usage: "cnos spec list [--prefix <path>] [global-options]",
+    description: "Lists manifest schema entries. In v1, spec entries are manifest-global rather than workspace-scoped.",
+    options: [
+      {
+        flag: "--prefix <path>",
+        description: "Filter listed spec keys by logical-key prefix."
+      }
+    ],
+    examples: ["cnos spec list", "cnos spec list --prefix value.server."]
+  },
+  {
+    id: "spec show",
+    summary: "Show one spec entry.",
+    usage: "cnos spec show <logicalKey> [global-options]",
+    description: "Shows one manifest schema entry by namespace-qualified logical key.",
+    arguments: [
+      {
+        name: "logicalKey",
+        description: "Namespace-qualified key such as value.server.port.",
+        required: true
+      }
+    ],
+    examples: ["cnos spec show value.server.port", "cnos spec show secret.db.password --json"]
+  },
+  {
+    id: "spec set",
+    summary: "Create or update one spec entry.",
+    usage: "cnos spec set <logicalKey> [field-flags] [global-options]",
+    description: "Writes one manifest schema entry. With no field flags in a TTY, CNOS enters interactive authoring mode. With field flags, CNOS uses non-interactive mode.",
+    arguments: [
+      {
+        name: "logicalKey",
+        description: "Namespace-qualified key such as value.server.port.",
+        required: true
+      }
+    ],
+    options: [
+      {
+        flag: "--type <string|number|boolean|object|array>",
+        description: "Set expected value type."
+      },
+      {
+        flag: "--required | --optional",
+        description: "Mark key required or optional."
+      },
+      {
+        flag: "--default <jsonOrScalar>",
+        description: "Set default using JSON-first parsing; fallback is literal string."
+      },
+      {
+        flag: "--enum <jsonArray>",
+        description: "Set allowed values from a non-empty JSON array."
+      },
+      {
+        flag: "--pattern <regex>",
+        description: "Set regex pattern for string values."
+      },
+      {
+        flag: "--summary <text>",
+        description: "Set short description."
+      },
+      {
+        flag: "--description <text>",
+        description: "Set long description."
+      },
+      {
+        flag: "--example <value>",
+        description: "Add example value. Repeatable. JSON-first parsing."
+      },
+      {
+        flag: "--used-by <text>",
+        description: "Add usage context text. Repeatable."
+      },
+      {
+        flag: "--deprecated",
+        description: "Mark as deprecated."
+      },
+      {
+        flag: "--deprecation-message <text>",
+        description: "Set deprecation message and auto-mark deprecated."
+      },
+      {
+        flag: "--clear-default | --clear-enum | --clear-pattern | --clear-summary | --clear-description | --clear-examples | --clear-used-by | --clear-deprecated | --clear-deprecation-message",
+        description: "Explicitly clear stored fields."
+      }
+    ],
+    examples: [
+      'cnos spec set value.server.port --type number --required --summary "HTTP server port"',
+      `cnos spec set value.app.stage --enum '["local","stage","prod"]'`,
+      "cnos spec set value.legacy.flag --clear-deprecated"
+    ]
+  },
+  {
+    id: "spec delete",
+    summary: "Delete one spec entry.",
+    usage: "cnos spec delete <logicalKey> [global-options]",
+    description: "Removes one manifest schema entry by namespace-qualified logical key.",
+    arguments: [
+      {
+        name: "logicalKey",
+        description: "Namespace-qualified key such as value.server.port.",
+        required: true
+      }
+    ],
+    examples: ["cnos spec delete value.legacy.flag", "cnos spec remove value.legacy.flag --json"]
+  },
+  {
+    id: "spec doctor",
+    summary: "Compare declared spec against current config and guide remediation.",
+    usage: "cnos spec doctor [--fill-missing|--review-all] [global-options]",
+    description: "Report mode shows missing required keys, undeclared keys, type/enum/pattern mismatches, defaults in use, and deprecated keys in use. Write modes run interactive remediation flows.",
+    options: [
+      {
+        flag: "--fill-missing",
+        description: "Interactively fill only missing required keys. Requires TTY and writable root."
+      },
+      {
+        flag: "--review-all",
+        description: "Interactively review all declared spec keys one by one. Requires TTY and writable root."
+      }
+    ],
+    examples: [
+      "cnos spec doctor",
+      "cnos spec doctor --json",
+      "cnos spec doctor --fill-missing",
+      "cnos spec doctor --review-all --workspace api --profile stage"
+    ]
+  },
   {
     id: "use",
     summary: "Persist repo-local CLI defaults such as workspace and profile.",
@@ -2177,12 +2449,14 @@ var COMMANDS = [
   {
     id: "secret set",
     summary: "Write a secret securely.",
-    usage: "cnos secret set <path> <value> [--local|--remote|--ref] [--vault <name>] [--provider <name>] [global-options]",
-    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 an environment-backed vault is selected, CNOS writes an env-backed ref for CI or cloud runtimes.",
+    usage: "cnos secret set <path> [value] [--local|--remote|--ref] [--vault <name>] [--provider <name>] [--stdin] [global-options]",
+    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 an environment-backed vault is selected, CNOS writes an env-backed ref for CI or cloud runtimes. If [value] is omitted, CNOS prompts for a masked value interactively; use --stdin for pipelines.",
     examples: [
       "cnos vault create db",
       "cnos vault auth db",
       "cnos secret set app.token super-secret --vault db",
+      "cnos secret set app.token --vault db",
+      'printf "super-secret" | cnos secret set app.token --vault db --stdin',
       "cnos vault create github-ci --provider environment --no-passphrase",
       "cnos secret set app.token APP_TOKEN --vault github-ci"
     ]
@@ -2541,7 +2815,7 @@ var COMMANDS = [
     id: "doctor",
     summary: "Run repository and workspace diagnostics.",
     usage: "cnos doctor [--fix-secret-env-mappings] [global-options]",
-    description: "Checks manifest/workspace setup, gitignore coverage, and related diagnostics for the selected workspace. Secret env mappings are reported as a security risk; use --fix-secret-env-mappings to remove them from envMapping.explicit in one shot.",
+    description: "Checks manifest/workspace setup, gitignore coverage, and related diagnostics for the selected workspace. Secret env mappings are reported as a security risk; use --fix-secret-env-mappings to remove them from envMapping.explicit in one shot. When schema entries exist, doctor points to cnos spec doctor for spec coverage and remediation.",
     examples: ["cnos doctor", "cnos doctor --workspace api --json", "cnos doctor --fix-secret-env-mappings"]
   },
   {
@@ -3094,9 +3368,15 @@ function printTable(rows) {
       ...rows.map((row) => stringifyCell(row[column]).length)
     )
   );
-  const renderRow = (row) => columns.map((column, index) => stringifyCell(row[column]).padEnd(widths[index], " ")).join("  ").trimEnd();
+  const renderRow = (row) => columns.map((column, index) => {
+    const width = widths[index] ?? column.length;
+    return stringifyCell(row[column]).padEnd(width, " ");
+  }).join("  ").trimEnd();
   return [
-    columns.map((column, index) => column.padEnd(widths[index], " ")).join("  ").trimEnd(),
+    columns.map((column, index) => {
+      const width = widths[index] ?? column.length;
+      return column.padEnd(width, " ");
+    }).join("  ").trimEnd(),
     widths.map((width) => "-".repeat(width)).join("  "),
     ...rows.map(renderRow)
   ].join("\n");
@@ -3288,7 +3568,7 @@ async function runList(args = [], options = {}) {
 import path12 from "path";
 import {
   applyManifestMappings,
-  loadManifest as loadManifest4,
+  loadManifest as loadManifest5,
   proposeMapping,
   rewriteSourceFiles,
   scanEnvUsage
@@ -3305,7 +3585,7 @@ async function runMigrate(options = {}) {
   if (apply) {
     await assertWritableConfigRoot("apply migration mappings", options);
   }
-  const manifest = await loadManifest4({
+  const manifest = await loadManifest5({
     ...options.root ? { root: options.root } : {},
     ...options.cwd ? { cwd: options.cwd } : {},
     ...options.processEnv ? { processEnv: options.processEnv } : {},
@@ -3471,7 +3751,7 @@ async function runNamespace(namespace, args = [], options = {}) {
 import { copyFile, mkdir as mkdir5, readdir as readdir3, rm as rm2, stat as stat2, readFile as readFile5 } from "fs/promises";
 import path14 from "path";
 import readline2 from "readline/promises";
-import { loadManifest as loadManifest5, parseYaml as parseYaml3 } from "@kitsy/cnos/internal";
+import { loadManifest as loadManifest6, parseYaml as parseYaml3 } from "@kitsy/cnos/internal";
 import { parse as parseToml } from "smol-toml";
 var ROOT_ENV_FILE_PATTERN = /^\.env(?:\.[A-Za-z0-9_-]+)*(?:\.example)?$/;
 var SECRET_LIKE_PATTERN = /(secret|token|password|passwd|private|api[_-]?key|client[_-]?secret|dsn)/i;
@@ -3656,7 +3936,7 @@ async function runOnboard(options = {}) {
     });
     scaffolded = scaffold.created;
   }
-  const loaded = await loadManifest5({
+  const loaded = await loadManifest6({
     root,
     ...options.processEnv ? { processEnv: options.processEnv } : {}
   });
@@ -3781,13 +4061,13 @@ async function saveCliContext(options = {}) {
 // src/services/profiles.ts
 import { mkdir as mkdir6, readdir as readdir4, readFile as readFile7, rm as rm3, writeFile as writeFile7 } from "fs/promises";
 import path16 from "path";
-import { loadManifest as loadManifest6, parseYaml as parseYaml5, stringifyYaml as stringifyYaml5 } from "@kitsy/cnos/internal";
+import { loadManifest as loadManifest7, parseYaml as parseYaml5, stringifyYaml as stringifyYaml5 } from "@kitsy/cnos/internal";
 async function resolveProfilesRoot(root = process.cwd()) {
   try {
-    const loadedManifest = await loadManifest6({ root });
+    const loadedManifest = await loadManifest7({ root });
     return path16.join(loadedManifest.manifestRoot, "profiles");
   } catch {
-    const loadedManifest = await loadManifest6({ cwd: root });
+    const loadedManifest = await loadManifest7({ cwd: root });
     return path16.join(loadedManifest.manifestRoot, "profiles");
   }
 }
@@ -3933,7 +4213,7 @@ import path18 from "path";
 import { writeFile as writeFile8 } from "fs/promises";
 import {
   ensureProjectionAllowed,
-  loadManifest as loadManifest7,
+  loadManifest as loadManifest8,
   stringifyYaml as stringifyYaml6
 } from "@kitsy/cnos/internal";
 function normalizeTarget(value) {
@@ -3965,7 +4245,7 @@ async function runPromote(args = [], options = {}) {
   } else if (allowSecret) {
     throw new Error("--allow-secret is only supported with promote --to env");
   }
-  const loadedManifest = await loadManifest7({
+  const loadedManifest = await loadManifest8({
     ...options.root ? { root: options.root } : {},
     ...options.cwd ? { cwd: options.cwd } : {},
     ...options.processEnv ? { processEnv: options.processEnv } : {},
@@ -4037,7 +4317,7 @@ import {
   serializeRuntimeGraph,
   serializeSecretPayload
 } from "@kitsy/cnos/internal";
-function consumeOptions(args, flag) {
+function consumeOptions2(args, flag) {
   const values = [];
   for (let index = 0; index < args.length; ) {
     const token = args[index];
@@ -4076,7 +4356,7 @@ async function runCommand(command, options = {}) {
   const isAuthenticated = consumeFlag(cliArgs, "--auth");
   const framework = consumeOption(cliArgs, "--framework");
   const prefix = consumeOption(cliArgs, "--prefix");
-  const setOverrides = normalizeSetOverrides(consumeOptions(cliArgs, "--set"));
+  const setOverrides = normalizeSetOverrides(consumeOptions2(cliArgs, "--set"));
   const runtime = await createRuntimeService({
     ...options,
     cliArgs: [...cliArgs, ...setOverrides]
@@ -4132,6 +4412,8 @@ async function runCommand(command, options = {}) {
 
 // src/commands/secret.ts
 import path21 from "path";
+import readline3 from "readline";
+import { Writable } from "stream";
 
 // src/commands/vault.ts
 import path20 from "path";
@@ -4145,7 +4427,7 @@ import {
   createSecretVault,
   deriveVaultKey,
   listLocalSecrets,
-  loadManifest as loadManifest8,
+  loadManifest as loadManifest9,
   listSecretVaults,
   readVaultMetadata,
   resolveSecretStoreRoot as resolveSecretStoreRoot2,
@@ -4184,7 +4466,7 @@ async function createVaultDefinition(name, options = {}) {
   if (provider === "local" && (options.noPassphrase ?? false)) {
     throw new Error("Local vaults cannot be passwordless.");
   }
-  const loadedManifest = await loadManifest8({
+  const loadedManifest = await loadManifest9({
     ...options.root ? { root: options.root } : {},
     ...options.cwd ? { cwd: options.cwd } : {},
     ...options.processEnv ? { processEnv: options.processEnv } : {},
@@ -4221,7 +4503,7 @@ async function createVaultDefinition(name, options = {}) {
   };
 }
 async function listVaultDefinitions(options = {}) {
-  const loadedManifest = await loadManifest8({
+  const loadedManifest = await loadManifest9({
     ...options.root ? { root: options.root } : {},
     ...options.cwd ? { cwd: options.cwd } : {},
     ...options.processEnv ? { processEnv: options.processEnv } : {},
@@ -4242,7 +4524,7 @@ async function listVaultDefinitions(options = {}) {
 async function removeVaultDefinition(name, options = {}) {
   await assertWritableConfigRoot(`remove vault ${name}`, options);
   const vault = name.trim() || "default";
-  const loadedManifest = await loadManifest8({
+  const loadedManifest = await loadManifest9({
     ...options.root ? { root: options.root } : {},
     ...options.cwd ? { cwd: options.cwd } : {},
     ...options.processEnv ? { processEnv: options.processEnv } : {},
@@ -4288,7 +4570,7 @@ async function listLocalStoreVaults(options = {}) {
 }
 async function authenticateVault(name, options = {}) {
   const vault = name.trim() || "default";
-  const loadedManifest = await loadManifest8({
+  const loadedManifest = await loadManifest9({
     ...options.root ? { root: options.root } : {},
     ...options.cwd ? { cwd: options.cwd } : {},
     ...options.processEnv ? { processEnv: options.processEnv } : {},
@@ -4470,6 +4752,45 @@ async function readStdinValue() {
   }
   return Buffer.concat(chunks).toString("utf8").trimEnd();
 }
+async function promptHiddenValue(message) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error("Cannot prompt for a secret value in non-interactive mode. Pass <value> explicitly or use --stdin.");
+  }
+  const mutableStdout = new WritableMask();
+  const rl = readline3.createInterface({
+    input: process.stdin,
+    output: mutableStdout,
+    terminal: true
+  });
+  try {
+    mutableStdout.muted = true;
+    const value = await new Promise((resolve) => {
+      rl.question(message, resolve);
+    });
+    process.stdout.write("\n");
+    return value;
+  } finally {
+    rl.close();
+  }
+}
+async function resolveSecretSetValue(secretPath, providedValue, stdin) {
+  if (stdin) {
+    return readStdinValue();
+  }
+  if (providedValue !== void 0) {
+    return providedValue;
+  }
+  return promptHiddenValue(`Enter value for secret "${secretPath}": `);
+}
+var WritableMask = class extends Writable {
+  muted = false;
+  _write(chunk, _encoding, callback) {
+    if (!this.muted) {
+      process.stdout.write(chunk);
+    }
+    callback();
+  }
+};
 async function runSecret(argsOrPath, options = {}) {
   const args = Array.isArray(argsOrPath) ? argsOrPath : [argsOrPath];
   const { action, tail } = normalizeSecretCommand(args);
@@ -4514,8 +4835,9 @@ async function runSecret(argsOrPath, options = {}) {
     const provider = consumeOption(cliArgs, "--provider");
     const vault = consumeOption(cliArgs, "--vault") ?? "default";
     const mode = local ? "local" : remote ? "remote" : ref ? "ref" : void 0;
-    const rawValue = stdin ? await readStdinValue() : tail[1] ?? "";
-    const result = await setSecret(secretPath2 ?? "app.token", rawValue, {
+    const resolvedSecretPath = secretPath2 ?? "app.token";
+    const rawValue = await resolveSecretSetValue(resolvedSecretPath, tail[1], stdin);
+    const result = await setSecret(resolvedSecretPath, rawValue, {
       ...options,
       cliArgs,
       target,
@@ -4569,64 +4891,970 @@ async function runSecret(argsOrPath, options = {}) {
   return printValue(valueForOutput);
 }
 
-// src/commands/use.ts
-import path22 from "path";
-async function runUse(args = [], options = {}) {
-  const root = path22.resolve(options.root ?? process.cwd());
-  const action = args[0];
-  const hasUpdates = Boolean(options.workspace || options.profile || options.globalRoot);
-  if (action === "show" || !action && !hasUpdates) {
-    const context = await loadCliContext(root);
-    if (options.json) {
-      return printJson(context);
+// src/services/spec/specDoctor.ts
+import { compareSpecToGraph } from "@kitsy/cnos/internal";
+
+// src/services/maskedPrompt.ts
+import readline4 from "readline";
+import { Writable as Writable2 } from "stream";
+var WritableMask2 = class extends Writable2 {
+  muted = false;
+  _write(chunk, _encoding, callback) {
+    if (!this.muted) {
+      process.stdout.write(chunk);
     }
-    return Object.keys(context).length === 0 ? "no CLI context configured" : printJson(context);
+    callback();
   }
-  const result = await saveCliContext({
-    root,
-    ...options.workspace ? { workspace: options.workspace } : {},
-    ...options.profile ? { profile: options.profile } : {},
-    ...options.globalRoot ? { globalRoot: options.globalRoot } : {}
-  });
-  if (options.json) {
-    return printJson(result);
+};
+function assertInteractiveInput(mode) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error(`Cannot prompt for ${mode} input in non-interactive mode.`);
   }
-  return `updated CLI context in ${displayPath(result.filePath, root)}`;
 }
-
-// src/commands/ui.ts
-import { createServer } from "http";
-import path23 from "path";
-import { createRequire } from "module";
-import { loadManifest as loadManifest9 } from "@kitsy/cnos/internal";
-function parsePort(value, fallback, flag) {
-  if (!value) {
-    return fallback;
-  }
-  const parsed = Number(value);
-  if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65535) {
-    throw new Error(`Invalid value for ${flag}: ${value}`);
+async function promptMaskedInput(message) {
+  assertInteractiveInput("masked");
+  const mutableStdout = new WritableMask2();
+  const rl = readline4.createInterface({
+    input: process.stdin,
+    output: mutableStdout,
+    terminal: true
+  });
+  try {
+    process.stdout.write(message);
+    mutableStdout.muted = true;
+    const value = await new Promise((resolve) => {
+      rl.question("", resolve);
+    });
+    process.stdout.write("\n");
+    return value;
+  } finally {
+    rl.close();
   }
-  return parsed;
 }
-function resolveUiPackageRoot() {
-  const require2 = createRequire(import.meta.url);
+async function promptInput(message) {
+  assertInteractiveInput("plain");
+  const rl = readline4.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: true
+  });
   try {
-    const packageJsonPath = require2.resolve("@kitsy/cnos-ui/package.json");
-    return path23.dirname(packageJsonPath);
-  } catch {
-    throw new Error("Unable to resolve @kitsy/cnos-ui. Install workspace dependencies before running `cnos ui`.");
+    return await new Promise((resolve) => {
+      rl.question(message, (answer) => resolve(answer));
+    });
+  } finally {
+    rl.close();
   }
 }
-function writeJson(response, statusCode, payload) {
-  response.statusCode = statusCode;
-  response.setHeader("Content-Type", "application/json; charset=utf-8");
-  response.end(`${printJson(payload)}
-`);
+
+// src/services/spec/specDoctor.ts
+var BLOCKING_STATUSES = /* @__PURE__ */ new Set([
+  "missing_required",
+  "undeclared",
+  "type_mismatch",
+  "enum_mismatch",
+  "pattern_mismatch"
+]);
+function statusLabel(status) {
+  return status.replace(/_/g, " ");
 }
-async function readJsonBody(request) {
-  const chunks = [];
-  for await (const chunk of request) {
+function isBlockingStatus(status) {
+  return BLOCKING_STATUSES.has(status);
+}
+function isBlockingIssue(issue) {
+  return isBlockingStatus(issue.status);
+}
+function isInteractiveMode() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+function toPath(key) {
+  const separatorIndex = key.indexOf(".");
+  if (separatorIndex <= 0 || separatorIndex >= key.length - 1) {
+    throw new Error(`Spec key must be namespace-qualified: ${key}`);
+  }
+  return {
+    namespace: key.slice(0, separatorIndex),
+    configPath: key.slice(separatorIndex + 1)
+  };
+}
+function toDoctorIssue(issue) {
+  return {
+    key: issue.key,
+    status: issue.status,
+    ...issue.expectedType ? {
+      expectedType: issue.expectedType
+    } : {},
+    ...issue.actualType ? {
+      actualType: issue.actualType
+    } : {},
+    ...issue.value !== void 0 ? {
+      value: issue.value
+    } : {},
+    ...issue.sourceFile ? {
+      sourceFile: issue.sourceFile
+    } : {},
+    ...issue.summary ? {
+      summary: issue.summary
+    } : {}
+  };
+}
+function renderIssueLine(issue) {
+  const context = [
+    issue.expectedType ? `expected=${issue.expectedType}` : void 0,
+    issue.actualType ? `actual=${issue.actualType}` : void 0,
+    issue.sourceFile ? `source=${issue.sourceFile}` : void 0
+  ].filter((value) => Boolean(value)).join(", ");
+  return context.length > 0 ? `- ${issue.key} [${statusLabel(issue.status)}] (${context})` : `- ${issue.key} [${statusLabel(issue.status)}]`;
+}
+function makeReportResult(runtime, mode, actions) {
+  const report = compareSpecToGraph(runtime);
+  return {
+    workspace: report.workspace,
+    profile: report.profile,
+    summary: report.summary,
+    issues: report.issues.map((issue) => toDoctorIssue(issue)),
+    mode,
+    ...actions ? {
+      actions
+    } : {}
+  };
+}
+function getRuleForKey(runtime, logicalKey) {
+  return runtime.manifest.schema[logicalKey];
+}
+async function promptForKeyValue(key, rule) {
+  const lines = [
+    "",
+    `Key: ${key}`,
+    ...rule?.summary ? [`Summary: ${rule.summary}`] : [],
+    ...rule?.description ? [`Description: ${rule.description}`] : [],
+    ...rule?.enum ? [`Allowed values: ${rule.enum.map((entry) => JSON.stringify(entry)).join(", ")}`] : [],
+    ...rule?.pattern ? [`Pattern: ${rule.pattern}`] : []
+  ];
+  process.stdout.write(`${lines.join("\n")}
+`);
+  if (key.startsWith("secret.")) {
+    return (await promptMaskedInput(`Enter value for ${key}: `)).trimEnd();
+  }
+  if (rule?.enum && rule.enum.length > 0) {
+    process.stdout.write(
+      `${rule.enum.map((entry, index2) => `${index2 + 1}. ${JSON.stringify(entry)}`).join("\n")}
+`
+    );
+    const choice = (await promptInput(`Choose [1-${rule.enum.length}] or enter a custom value: `)).trim();
+    const index = Number(choice);
+    if (Number.isFinite(index) && index >= 1 && index <= rule.enum.length) {
+      return JSON.stringify(rule.enum[index - 1]);
+    }
+    return choice;
+  }
+  return (await promptInput(`Enter value for ${key}: `)).trim();
+}
+async function applyWriteForKey(key, rawValue, options) {
+  const { namespace, configPath } = toPath(key);
+  if (namespace === "secret") {
+    await setSecret(configPath, rawValue, options);
+    return;
+  }
+  await defineValue(namespace, configPath, rawValue, options);
+}
+function hasBlockingIssues(result) {
+  return result.issues.some((issue) => isBlockingIssue(issue));
+}
+function hasFailedActions(actions) {
+  return actions.some((action) => action.result === "failed");
+}
+async function runSpecDoctor(mode, options = {}) {
+  const runtime = await createRuntimeService({
+    ...options,
+    secretResolution: "lazy"
+  });
+  if (mode === "report") {
+    const result2 = makeReportResult(runtime, mode);
+    return {
+      result: result2,
+      blocking: hasBlockingIssues(result2)
+    };
+  }
+  if (!isInteractiveMode()) {
+    throw new Error(`spec doctor --${mode} requires an interactive TTY.`);
+  }
+  const report = compareSpecToGraph(runtime);
+  const actions = [];
+  let unresolvedBlocking = false;
+  if (mode === "fill-missing") {
+    const missing = report.issues.filter((issue) => issue.status === "missing_required").sort((left, right) => left.key.localeCompare(right.key));
+    for (const issue of missing) {
+      const rule = getRuleForKey(runtime, issue.key);
+      try {
+        const value = await promptForKeyValue(issue.key, rule);
+        await applyWriteForKey(issue.key, value, options);
+        actions.push({
+          key: issue.key,
+          result: "applied"
+        });
+      } catch (error) {
+        actions.push({
+          key: issue.key,
+          result: "failed",
+          reason: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }
+  } else {
+    const schemaKeys = Object.keys(runtime.manifest.schema).sort((left, right) => left.localeCompare(right));
+    const issuesByKey = /* @__PURE__ */ new Map();
+    for (const issue of report.issues) {
+      const existing = issuesByKey.get(issue.key) ?? [];
+      existing.push(issue.status);
+      issuesByKey.set(issue.key, existing);
+    }
+    for (const key of schemaKeys) {
+      const keyStatuses = issuesByKey.get(key) ?? [];
+      const rule = getRuleForKey(runtime, key);
+      const statusText = keyStatuses.length > 0 ? keyStatuses.map(statusLabel).join(", ") : "ok";
+      process.stdout.write(`
+Key: ${key}
+Current status: ${statusText}
+`);
+      const actionChoice = (await promptInput("Action [k=keep, u=update, s=skip]: ")).trim().toLowerCase();
+      if (actionChoice === "k" || actionChoice === "keep") {
+        actions.push({
+          key,
+          result: "skipped",
+          reason: "keep"
+        });
+        continue;
+      }
+      if (actionChoice === "s" || actionChoice === "skip") {
+        if (keyStatuses.includes("missing_required")) {
+          unresolvedBlocking = true;
+        }
+        actions.push({
+          key,
+          result: "skipped",
+          reason: "skip"
+        });
+        continue;
+      }
+      try {
+        const value = await promptForKeyValue(key, rule);
+        await applyWriteForKey(key, value, options);
+        actions.push({
+          key,
+          result: "applied"
+        });
+      } catch (error) {
+        actions.push({
+          key,
+          result: "failed",
+          reason: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }
+  }
+  const refreshed = await createRuntimeService({
+    ...options,
+    secretResolution: "lazy"
+  });
+  const result = makeReportResult(refreshed, mode, actions);
+  const blocking = hasBlockingIssues(result) || hasFailedActions(actions) || unresolvedBlocking;
+  return {
+    result,
+    blocking
+  };
+}
+function formatSpecDoctorResult(result) {
+  const lines = [
+    `Spec doctor (${result.workspace} / ${result.profile}) [mode=${result.mode}]`,
+    "",
+    `missingRequired=${result.summary.missingRequired}`,
+    `undeclared=${result.summary.undeclared}`,
+    `typeMismatch=${result.summary.typeMismatch}`,
+    `enumMismatch=${result.summary.enumMismatch}`,
+    `patternMismatch=${result.summary.patternMismatch}`,
+    `defaultApplied=${result.summary.defaultApplied}`,
+    `deprecatedInUse=${result.summary.deprecatedInUse}`,
+    ""
+  ];
+  if (result.issues.length === 0) {
+    lines.push("No spec issues detected.");
+  } else {
+    lines.push("Issues:");
+    lines.push(...result.issues.map(renderIssueLine));
+  }
+  if (result.actions && result.actions.length > 0) {
+    lines.push("");
+    lines.push("Actions:");
+    lines.push(
+      ...result.actions.map(
+        (action) => action.reason ? `- ${action.key}: ${action.result} (${action.reason})` : `- ${action.key}: ${action.result}`
+      )
+    );
+  }
+  return lines.join("\n");
+}
+
+// src/services/spec/manifestSpecStore.ts
+import { writeFile as writeFile10 } from "fs/promises";
+import { loadManifest as loadManifest10, stringifyYaml as stringifyYaml8 } from "@kitsy/cnos/internal";
+function hasOwn(target, key) {
+  return Object.prototype.hasOwnProperty.call(target, key);
+}
+function sortSchema(schema) {
+  return Object.fromEntries(Object.entries(schema).sort(([left], [right]) => left.localeCompare(right)));
+}
+async function loadSpecManifest(options = {}) {
+  const loadedManifest = await loadManifest10({
+    ...options.root ? { root: options.root } : {},
+    ...options.cwd ? { cwd: options.cwd } : {},
+    ...options.processEnv ? { processEnv: options.processEnv } : {},
+    ...options.cacheMode ? { cacheMode: options.cacheMode } : {},
+    ...typeof options.cacheTtlSeconds === "number" ? { cacheTtlSeconds: options.cacheTtlSeconds } : {},
+    ...options.forceRefresh ? { forceRefresh: true } : {}
+  });
+  return {
+    manifestPath: loadedManifest.manifestPath,
+    rawManifest: loadedManifest.rawManifest,
+    schema: loadedManifest.manifest.schema
+  };
+}
+async function listSpecEntries(options = {}) {
+  const loaded = await loadSpecManifest(options);
+  const prefix = options.prefix?.trim();
+  const entries = Object.entries(loaded.schema).filter(([key]) => prefix ? key.startsWith(prefix) : true).sort(([left], [right]) => left.localeCompare(right)).map(([key, rule]) => ({
+    key,
+    rule
+  }));
+  return {
+    manifestPath: loaded.manifestPath,
+    entries
+  };
+}
+async function showSpecEntry(logicalKey, options = {}) {
+  const loaded = await loadSpecManifest(options);
+  const key = logicalKey.trim();
+  return {
+    manifestPath: loaded.manifestPath,
+    key,
+    ...loaded.schema[key] ? {
+      rule: loaded.schema[key]
+    } : {}
+  };
+}
+async function setSpecEntry(logicalKey, options = {}) {
+  const loaded = await loadSpecManifest(options);
+  const key = logicalKey.trim();
+  const hasSetFields = Object.keys(options.set ?? {}).length > 0;
+  if (!loaded.schema[key] && !hasSetFields) {
+    throw new Error(`Cannot clear fields for undeclared spec key ${key}.`);
+  }
+  const current = loaded.schema[key] ?? {};
+  const next = {
+    ...current,
+    ...options.set ?? {}
+  };
+  for (const field of options.clear ?? []) {
+    if (hasOwn(next, field)) {
+      delete next[field];
+    }
+  }
+  if (Object.keys(next).length === 0) {
+    throw new Error(`Spec entry ${key} cannot be empty. Set at least one field or delete the entry.`);
+  }
+  const nextSchema = sortSchema({
+    ...loaded.schema,
+    [key]: next
+  });
+  const nextRawManifest = {
+    ...loaded.rawManifest,
+    schema: nextSchema
+  };
+  await writeFile10(loaded.manifestPath, stringifyYaml8(nextRawManifest), "utf8");
+  return {
+    manifestPath: loaded.manifestPath,
+    key,
+    action: loaded.schema[key] ? "updated" : "created",
+    rule: next
+  };
+}
+async function deleteSpecEntry(logicalKey, options = {}) {
+  const loaded = await loadSpecManifest(options);
+  const key = logicalKey.trim();
+  if (!loaded.schema[key]) {
+    return {
+      manifestPath: loaded.manifestPath,
+      key,
+      deleted: false
+    };
+  }
+  const nextSchema = { ...loaded.schema };
+  delete nextSchema[key];
+  const sorted = sortSchema(nextSchema);
+  const nextRawManifest = {
+    ...loaded.rawManifest,
+    ...Object.keys(sorted).length > 0 ? { schema: sorted } : {}
+  };
+  if (Object.keys(sorted).length === 0) {
+    delete nextRawManifest.schema;
+  }
+  await writeFile10(loaded.manifestPath, stringifyYaml8(nextRawManifest), "utf8");
+  return {
+    manifestPath: loaded.manifestPath,
+    key,
+    deleted: true
+  };
+}
+
+// src/services/spec/specPrompts.ts
+import readline5 from "readline";
+
+// src/services/spec/patternValidation.ts
+function assertValidSpecPattern(pattern) {
+  try {
+    void new RegExp(pattern);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(`Invalid --pattern regex: ${reason}`);
+  }
+}
+
+// src/services/spec/specPrompts.ts
+var SPEC_TYPES = ["string", "number", "boolean", "object", "array"];
+function parseJsonOrString(rawValue) {
+  try {
+    return JSON.parse(rawValue);
+  } catch {
+    return rawValue;
+  }
+}
+function createPrompt() {
+  const rl = readline5.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  return {
+    ask(question) {
+      return new Promise((resolve) => {
+        rl.question(question, (answer) => resolve(answer.trim()));
+      });
+    },
+    close() {
+      rl.close();
+    }
+  };
+}
+function isInteractiveSpecPromptMode() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+async function promptSpecSetInput(logicalKey) {
+  const prompt = createPrompt();
+  try {
+    process.stdout.write(`Config spec for ${logicalKey}
+`);
+    const set = {};
+    const type = (await prompt.ask(`Type (${SPEC_TYPES.join("|")}) [skip]: `)).toLowerCase();
+    if (type) {
+      if (!SPEC_TYPES.includes(type)) {
+        throw new Error(`Unsupported type: ${type}`);
+      }
+      set.type = type;
+    }
+    const required = (await prompt.ask("Required? (y/n) [skip]: ")).toLowerCase();
+    if (required === "y" || required === "yes") {
+      set.required = true;
+    } else if (required === "n" || required === "no") {
+      set.required = false;
+    }
+    const defaultValue = await prompt.ask("Default value (JSON or string) [skip]: ");
+    if (defaultValue) {
+      set.default = parseJsonOrString(defaultValue);
+    }
+    const enumValue = await prompt.ask("Enum values as JSON array [skip]: ");
+    if (enumValue) {
+      const parsed = parseJsonOrString(enumValue);
+      if (!Array.isArray(parsed)) {
+        throw new Error("Enum must be a JSON array");
+      }
+      if (parsed.length === 0) {
+        throw new Error("Enum must not be empty");
+      }
+      set.enum = parsed;
+    }
+    const pattern = await prompt.ask("Pattern (regex string) [skip]: ");
+    if (pattern) {
+      assertValidSpecPattern(pattern);
+      set.pattern = pattern;
+    }
+    const summary = await prompt.ask("Summary [skip]: ");
+    if (summary) {
+      set.summary = summary;
+    }
+    const description = await prompt.ask("Description [skip]: ");
+    if (description) {
+      set.description = description;
+    }
+    const examples = await prompt.ask("Examples as JSON array [skip]: ");
+    if (examples) {
+      const parsed = parseJsonOrString(examples);
+      if (!Array.isArray(parsed)) {
+        throw new Error("Examples must be a JSON array");
+      }
+      set.examples = parsed;
+    }
+    const usedBy = await prompt.ask("Used by (comma separated) [skip]: ");
+    if (usedBy) {
+      const values = usedBy.split(",").map((entry) => entry.trim()).filter(Boolean);
+      if (values.length > 0) {
+        set.usedBy = values;
+      }
+    }
+    const deprecated = (await prompt.ask("Deprecated? (y/n) [skip]: ")).toLowerCase();
+    if (deprecated === "y" || deprecated === "yes") {
+      set.deprecated = true;
+    } else if (deprecated === "n" || deprecated === "no") {
+      set.deprecated = false;
+    }
+    const deprecationMessage = await prompt.ask("Deprecation message [skip]: ");
+    if (deprecationMessage) {
+      set.deprecationMessage = deprecationMessage;
+      set.deprecated = true;
+    }
+    return {
+      set,
+      clear: [],
+      hasFieldFlags: Object.keys(set).length > 0,
+      cliArgs: []
+    };
+  } finally {
+    prompt.close();
+  }
+}
+
+// src/services/spec/specSetInput.ts
+var SPEC_TYPES2 = /* @__PURE__ */ new Set(["string", "number", "boolean", "object", "array"]);
+var SECRET_FORBIDDEN_FIELDS = ["default", "enum", "examples"];
+function parseJsonOrString2(rawValue) {
+  try {
+    return JSON.parse(rawValue);
+  } catch {
+    return rawValue;
+  }
+}
+function validateNamespaceQualifiedKey(logicalKey) {
+  const trimmed = logicalKey.trim();
+  if (!trimmed.includes(".")) {
+    throw new Error(`Spec key must be namespace-qualified: ${logicalKey}`);
+  }
+  const namespace = trimmed.slice(0, trimmed.indexOf("."));
+  const keyPath = trimmed.slice(trimmed.indexOf(".") + 1);
+  if (!namespace || !keyPath) {
+    throw new Error(`Spec key must be namespace-qualified: ${logicalKey}`);
+  }
+}
+function parseSetOptionToField(option) {
+  switch (option) {
+    case "--clear-default":
+      return "default";
+    case "--clear-enum":
+      return "enum";
+    case "--clear-pattern":
+      return "pattern";
+    case "--clear-summary":
+      return "summary";
+    case "--clear-description":
+      return "description";
+    case "--clear-examples":
+      return "examples";
+    case "--clear-used-by":
+      return "usedBy";
+    case "--clear-deprecated":
+      return "deprecated";
+    case "--clear-deprecation-message":
+      return "deprecationMessage";
+    default:
+      throw new Error(`Unknown clear option: ${option}`);
+  }
+}
+function assertNoClearConflict(set, clear) {
+  if (clear.has("default") && Object.prototype.hasOwnProperty.call(set, "default")) {
+    throw new Error("Cannot combine --default with --clear-default");
+  }
+  if (clear.has("enum") && Object.prototype.hasOwnProperty.call(set, "enum")) {
+    throw new Error("Cannot combine --enum with --clear-enum");
+  }
+  if (clear.has("pattern") && Object.prototype.hasOwnProperty.call(set, "pattern")) {
+    throw new Error("Cannot combine --pattern with --clear-pattern");
+  }
+  if (clear.has("summary") && Object.prototype.hasOwnProperty.call(set, "summary")) {
+    throw new Error("Cannot combine --summary with --clear-summary");
+  }
+  if (clear.has("description") && Object.prototype.hasOwnProperty.call(set, "description")) {
+    throw new Error("Cannot combine --description with --clear-description");
+  }
+  if (clear.has("examples") && Object.prototype.hasOwnProperty.call(set, "examples")) {
+    throw new Error("Cannot combine --example with --clear-examples");
+  }
+  if (clear.has("usedBy") && Object.prototype.hasOwnProperty.call(set, "usedBy")) {
+    throw new Error("Cannot combine --used-by with --clear-used-by");
+  }
+  if (clear.has("deprecated") && Object.prototype.hasOwnProperty.call(set, "deprecated")) {
+    throw new Error("Cannot combine --deprecated with --clear-deprecated");
+  }
+  if (clear.has("deprecated") && Object.prototype.hasOwnProperty.call(set, "deprecationMessage")) {
+    throw new Error("Cannot combine --clear-deprecated with --deprecation-message");
+  }
+}
+function assertSecretSafeSpecSet(logicalKey, set) {
+  if (!logicalKey.startsWith("secret.")) {
+    return;
+  }
+  const offending = SECRET_FORBIDDEN_FIELDS.filter((field) => Object.prototype.hasOwnProperty.call(set, field));
+  if (offending.length > 0) {
+    throw new Error(
+      `Cannot set ${offending.join(", ")} for secret spec key ${logicalKey}. Store secret values in the vault, not schema metadata.`
+    );
+  }
+}
+function parseSpecSetInput(logicalKey, rawCliArgs = []) {
+  validateNamespaceQualifiedKey(logicalKey);
+  const cliArgs = [...rawCliArgs];
+  const clearOptions = [
+    "--clear-default",
+    "--clear-enum",
+    "--clear-pattern",
+    "--clear-summary",
+    "--clear-description",
+    "--clear-examples",
+    "--clear-used-by",
+    "--clear-deprecated",
+    "--clear-deprecation-message"
+  ];
+  const clear = /* @__PURE__ */ new Set();
+  for (const option of clearOptions) {
+    if (consumeFlag(cliArgs, option)) {
+      clear.add(parseSetOptionToField(option));
+    }
+  }
+  if (clear.has("deprecated")) {
+    clear.add("deprecationMessage");
+  }
+  const set = {};
+  const type = consumeOption(cliArgs, "--type");
+  if (type) {
+    if (!SPEC_TYPES2.has(type)) {
+      throw new Error(`Unsupported --type value: ${type}`);
+    }
+    set.type = type;
+  }
+  const required = consumeFlag(cliArgs, "--required");
+  const optional = consumeFlag(cliArgs, "--optional");
+  if (required && optional) {
+    throw new Error("Cannot combine --required and --optional");
+  }
+  if (required) {
+    set.required = true;
+  }
+  if (optional) {
+    set.required = false;
+  }
+  const defaultValue = consumeOption(cliArgs, "--default");
+  if (defaultValue !== void 0) {
+    set.default = parseJsonOrString2(defaultValue);
+  }
+  const enumValue = consumeOption(cliArgs, "--enum");
+  if (enumValue !== void 0) {
+    const parsed = parseJsonOrString2(enumValue);
+    if (!Array.isArray(parsed)) {
+      throw new Error("--enum must be a JSON array");
+    }
+    if (parsed.length === 0) {
+      throw new Error("--enum must not be empty");
+    }
+    set.enum = parsed;
+  }
+  const pattern = consumeOption(cliArgs, "--pattern");
+  if (pattern !== void 0) {
+    assertValidSpecPattern(pattern);
+    set.pattern = pattern;
+  }
+  const summary = consumeOption(cliArgs, "--summary");
+  if (summary !== void 0) {
+    set.summary = summary;
+  }
+  const description = consumeOption(cliArgs, "--description");
+  if (description !== void 0) {
+    set.description = description;
+  }
+  const examples = consumeOptions(cliArgs, "--example").map(parseJsonOrString2);
+  if (examples.length > 0) {
+    set.examples = examples;
+  }
+  const usedBy = consumeOptions(cliArgs, "--used-by");
+  if (usedBy.length > 0) {
+    set.usedBy = usedBy;
+  }
+  const deprecated = consumeFlag(cliArgs, "--deprecated");
+  if (deprecated) {
+    set.deprecated = true;
+  }
+  const deprecationMessage = consumeOption(cliArgs, "--deprecation-message");
+  if (deprecationMessage !== void 0) {
+    set.deprecationMessage = deprecationMessage;
+    set.deprecated = true;
+  }
+  if (clear.has("deprecationMessage") && Object.prototype.hasOwnProperty.call(set, "deprecationMessage")) {
+    throw new Error("Cannot combine --clear-deprecated with --deprecation-message");
+  }
+  if (clear.has("deprecationMessage") && Object.prototype.hasOwnProperty.call(set, "deprecated") && set.deprecated) {
+  }
+  assertNoClearConflict(set, clear);
+  assertSecretSafeSpecSet(logicalKey, set);
+  return {
+    set,
+    clear: Array.from(clear),
+    hasFieldFlags: Object.keys(set).length > 0 || clear.size > 0,
+    cliArgs
+  };
+}
+
+// src/commands/spec.ts
+function normalizeSpecAction(args) {
+  const [action = "list", ...tail] = args;
+  if (["list", "show", "set", "delete", "remove", "doctor"].includes(action)) {
+    return {
+      action: action === "remove" ? "delete" : action,
+      tail
+    };
+  }
+  return {
+    action: "show",
+    tail: args
+  };
+}
+function validateNamespaceQualifiedKey2(logicalKey) {
+  const key = logicalKey.trim();
+  if (!key.includes(".")) {
+    throw new Error(`Spec key must be namespace-qualified: ${logicalKey}`);
+  }
+  const namespace = key.slice(0, key.indexOf("."));
+  const keyPath = key.slice(key.indexOf(".") + 1);
+  if (!namespace || !keyPath) {
+    throw new Error(`Spec key must be namespace-qualified: ${logicalKey}`);
+  }
+  return key;
+}
+function hasFieldFlag(cliArgs) {
+  const clearFlags = /* @__PURE__ */ new Set([
+    "--clear-default",
+    "--clear-enum",
+    "--clear-pattern",
+    "--clear-summary",
+    "--clear-description",
+    "--clear-examples",
+    "--clear-used-by",
+    "--clear-deprecated",
+    "--clear-deprecation-message"
+  ]);
+  const optionFlags = /* @__PURE__ */ new Set([
+    "--type",
+    "--default",
+    "--enum",
+    "--pattern",
+    "--summary",
+    "--description",
+    "--example",
+    "--used-by",
+    "--deprecation-message"
+  ]);
+  const toggleFlags = /* @__PURE__ */ new Set(["--required", "--optional", "--deprecated"]);
+  return cliArgs.some((arg) => {
+    const raw = arg.includes("=") ? arg.slice(0, arg.indexOf("=")) : arg;
+    return clearFlags.has(raw) || optionFlags.has(raw) || toggleFlags.has(raw);
+  });
+}
+function assertSecretSafeSpecSet2(logicalKey, set) {
+  if (!logicalKey.startsWith("secret.")) {
+    return;
+  }
+  const forbidden = ["default", "enum", "examples"].filter((field) => Object.prototype.hasOwnProperty.call(set, field));
+  if (forbidden.length > 0) {
+    throw new Error(
+      `Cannot set ${forbidden.join(", ")} for secret spec key ${logicalKey}. Store secret values in the vault, not schema metadata.`
+    );
+  }
+}
+async function runSpec(args = [], options = {}) {
+  const { action, tail } = normalizeSpecAction(args);
+  const cliArgs = [...options.cliArgs ?? []];
+  if (action === "list") {
+    const prefix = consumeOption(cliArgs, "--prefix");
+    if (cliArgs.length > 0) {
+      throw new Error(`Unsupported spec list options: ${cliArgs.join(" ")}`);
+    }
+    const result2 = await listSpecEntries({
+      ...options,
+      ...prefix ? {
+        prefix
+      } : {}
+    });
+    if (options.json) {
+      return printJson(result2);
+    }
+    return result2.entries.map((entry) => entry.key).join("\n");
+  }
+  if (action === "show") {
+    const logicalKey2 = validateNamespaceQualifiedKey2(tail[0] ?? "");
+    if (tail.length > 1) {
+      throw new Error("spec show accepts exactly one <logicalKey>");
+    }
+    if (cliArgs.length > 0) {
+      throw new Error(`Unsupported spec show options: ${cliArgs.join(" ")}`);
+    }
+    const result2 = await showSpecEntry(logicalKey2, options);
+    if (!result2.rule) {
+      throw new Error(`No spec entry found for ${logicalKey2}`);
+    }
+    if (options.json) {
+      return printJson(result2);
+    }
+    return [
+      `${result2.key}:`,
+      ...Object.entries(result2.rule).map(([key, value]) => `  ${key}: ${JSON.stringify(value)}`)
+    ].join("\n");
+  }
+  if (action === "set") {
+    const logicalKey2 = validateNamespaceQualifiedKey2(tail[0] ?? "");
+    if (tail.length > 1) {
+      throw new Error("spec set accepts exactly one <logicalKey>");
+    }
+    const fieldFlagPresent = hasFieldFlag(cliArgs);
+    if (!fieldFlagPresent && options.json) {
+      throw new Error("spec set --json requires field flags; interactive JSON mode is not supported.");
+    }
+    let input = parseSpecSetInput(logicalKey2, cliArgs);
+    if (!input.hasFieldFlags) {
+      if (!isInteractiveSpecPromptMode()) {
+        throw new Error("spec set without field flags requires an interactive TTY.");
+      }
+      input = await promptSpecSetInput(logicalKey2);
+    }
+    if (Object.keys(input.set).length === 0 && input.clear.length === 0) {
+      throw new Error("spec set requires at least one field to set or clear.");
+    }
+    assertSecretSafeSpecSet2(logicalKey2, input.set);
+    if (input.cliArgs.length > 0) {
+      throw new Error(`Unsupported spec set options: ${input.cliArgs.join(" ")}`);
+    }
+    await assertWritableConfigRoot(`update spec ${logicalKey2}`, options);
+    const result2 = await setSpecEntry(logicalKey2, {
+      ...options,
+      set: input.set,
+      clear: input.clear
+    });
+    if (options.json) {
+      return printJson(result2);
+    }
+    return `${result2.action} spec ${result2.key}`;
+  }
+  if (action === "doctor") {
+    const fillMissing = cliArgs.includes("--fill-missing");
+    const reviewAll = cliArgs.includes("--review-all");
+    if (fillMissing && reviewAll) {
+      throw new Error("spec doctor accepts only one write mode: --fill-missing or --review-all");
+    }
+    const mode = fillMissing ? "fill-missing" : reviewAll ? "review-all" : "report";
+    if (mode !== "report" && options.json) {
+      throw new Error(`spec doctor --${mode} does not support --json in Phases 1-3.`);
+    }
+    if (cliArgs.some((value) => !["--fill-missing", "--review-all"].includes(value))) {
+      throw new Error(`Unsupported spec doctor options: ${cliArgs.join(" ")}`);
+    }
+    if (mode !== "report") {
+      await assertWritableConfigRoot(`run spec doctor --${mode}`, options);
+    }
+    const outcome = await runSpecDoctor(mode, options);
+    if (outcome.blocking) {
+      process.exitCode = 1;
+    }
+    if (options.json) {
+      return printJson(outcome.result);
+    }
+    return formatSpecDoctorResult(outcome.result);
+  }
+  const logicalKey = validateNamespaceQualifiedKey2(tail[0] ?? "");
+  if (tail.length > 1) {
+    throw new Error("spec delete accepts exactly one <logicalKey>");
+  }
+  if (cliArgs.length > 0) {
+    throw new Error(`Unsupported spec delete options: ${cliArgs.join(" ")}`);
+  }
+  await assertWritableConfigRoot(`delete spec ${logicalKey}`, options);
+  const result = await deleteSpecEntry(logicalKey, options);
+  if (options.json) {
+    return printJson(result);
+  }
+  return result.deleted ? `deleted spec ${result.key}` : `no spec entry found for ${result.key}`;
+}
+
+// src/commands/use.ts
+import path22 from "path";
+async function runUse(args = [], options = {}) {
+  const root = path22.resolve(options.root ?? process.cwd());
+  const action = args[0];
+  const hasUpdates = Boolean(options.workspace || options.profile || options.globalRoot);
+  if (action === "show" || !action && !hasUpdates) {
+    const context = await loadCliContext(root);
+    if (options.json) {
+      return printJson(context);
+    }
+    return Object.keys(context).length === 0 ? "no CLI context configured" : printJson(context);
+  }
+  const result = await saveCliContext({
+    root,
+    ...options.workspace ? { workspace: options.workspace } : {},
+    ...options.profile ? { profile: options.profile } : {},
+    ...options.globalRoot ? { globalRoot: options.globalRoot } : {}
+  });
+  if (options.json) {
+    return printJson(result);
+  }
+  return `updated CLI context in ${displayPath(result.filePath, root)}`;
+}
+
+// src/commands/ui.ts
+import { createServer } from "http";
+import path23 from "path";
+import { createRequire } from "module";
+import { loadManifest as loadManifest11 } from "@kitsy/cnos/internal";
+function parsePort(value, fallback, flag) {
+  if (!value) {
+    return fallback;
+  }
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65535) {
+    throw new Error(`Invalid value for ${flag}: ${value}`);
+  }
+  return parsed;
+}
+function resolveUiPackageRoot() {
+  const require2 = createRequire(import.meta.url);
+  try {
+    const packageJsonPath = require2.resolve("@kitsy/cnos-ui/package.json");
+    return path23.dirname(packageJsonPath);
+  } catch {
+    throw new Error("Unable to resolve @kitsy/cnos-ui. Install workspace dependencies before running `cnos ui`.");
+  }
+}
+function writeJson(response, statusCode, payload) {
+  response.statusCode = statusCode;
+  response.setHeader("Content-Type", "application/json; charset=utf-8");
+  response.end(`${printJson(payload)}
+`);
+}
+async function readJsonBody(request) {
+  const chunks = [];
+  for await (const chunk of request) {
     chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
   }
   if (chunks.length === 0) {
@@ -4689,7 +5917,7 @@ async function handleSummary(options, searchParams) {
     ...runtimeOptions,
     secretResolution: "lazy"
   });
-  const loadedManifest = await loadManifest9({
+  const loadedManifest = await loadManifest11({
     ...options.root ? { root: options.root } : {},
     ...options.cwd ? { cwd: options.cwd } : {},
     ...options.processEnv ? { processEnv: options.processEnv } : {}
@@ -4700,7 +5928,7 @@ async function handleSummary(options, searchParams) {
   const envEntries = runtime.toEnv();
   const publicEntries = runtime.toPublicEnv();
   const counts = Array.from(runtime.graph.entries.values()).reduce((acc, entry) => {
-    acc.all += 1;
+    acc.all = (acc.all ?? 0) + 1;
     acc[entry.namespace] = (acc[entry.namespace] ?? 0) + 1;
     return acc;
   }, { all: 0 });
@@ -4732,9 +5960,12 @@ async function handleRevealList(body, options) {
   const prefix = typeof body.prefix === "string" ? body.prefix.trim() : "";
   const passphrase = typeof body.passphrase === "string" ? body.passphrase : void 0;
   const runtimeOptions = toRuntimeOptionsFromBody(options, body);
+  const processEnv = withUiPassphrase(options.processEnv, passphrase);
   const runtime = await createRuntimeService({
     ...runtimeOptions,
-    processEnv: withUiPassphrase(options.processEnv, passphrase),
+    ...processEnv ? {
+      processEnv
+    } : {},
     secretResolution: "lazy"
   });
   const entries = [];
@@ -4763,9 +5994,12 @@ async function handleRevealInspect(body, options) {
   }
   const passphrase = typeof body.passphrase === "string" ? body.passphrase : void 0;
   const runtimeOptions = toRuntimeOptionsFromBody(options, body);
+  const processEnv = withUiPassphrase(options.processEnv, passphrase);
   const runtime = await createRuntimeService({
     ...runtimeOptions,
-    processEnv: withUiPassphrase(options.processEnv, passphrase),
+    ...processEnv ? {
+      processEnv
+    } : {},
     ...key.startsWith("secret.") ? { secretResolution: "lazy" } : {}
   });
   if (key.startsWith("secret.")) {
@@ -4905,7 +6139,7 @@ async function runValidate(options = {}) {
 // package.json
 var package_default = {
   name: "@kitsy/cnos-cli",
-  version: "1.9.1",
+  version: "1.10.0",
   description: "CLI entry point and developer tooling for CNOS.",
   type: "module",
   main: "./dist/index.js",
@@ -5182,9 +6416,9 @@ async function runWatch(command, options = {}) {
 }
 
 // src/commands/workspace.ts
-import { cp, mkdir as mkdir7, readdir as readdir5, readFile as readFile8, rename, rm as rm5, stat as stat3, writeFile as writeFile10 } from "fs/promises";
+import { cp, mkdir as mkdir7, readdir as readdir5, readFile as readFile8, rename, rm as rm5, stat as stat3, writeFile as writeFile11 } from "fs/promises";
 import path25 from "path";
-import { loadManifest as loadManifest10, parseYaml as parseYaml6, stringifyYaml as stringifyYaml8 } from "@kitsy/cnos/internal";
+import { loadManifest as loadManifest12, parseYaml as parseYaml6, stringifyYaml as stringifyYaml9 } from "@kitsy/cnos/internal";
 async function exists2(targetPath) {
   try {
     await stat3(targetPath);
@@ -5223,9 +6457,9 @@ async function mergeWorkspaceRootsIntoStandalone(targetCnosRoot, sourceRoots) {
 async function writeAnchor(packageRoot, manifestRoot, workspace) {
   const relativeRoot = path25.relative(packageRoot, manifestRoot).replace(/\\/g, "/");
   const rootValue = relativeRoot.length === 0 ? "./.cnos" : relativeRoot.startsWith(".") ? relativeRoot : `./${relativeRoot}`;
-  await writeFile10(
+  await writeFile11(
     path25.join(packageRoot, ".cnosrc.yml"),
-    stringifyYaml8({
+    stringifyYaml9({
       root: rootValue,
       ...workspace ? { workspace } : {}
     }),
@@ -5275,9 +6509,9 @@ async function hasDirectConfigData(cnosRoot) {
 async function updateRootAnchorToWorkspace(packageRoot, workspaceId) {
   const anchorPath = path25.join(packageRoot, ".cnosrc.yml");
   const current = await exists2(anchorPath) ? parseYaml6(await readFile8(anchorPath, "utf8")) : void 0;
-  await writeFile10(
+  await writeFile11(
     anchorPath,
-    stringifyYaml8({
+    stringifyYaml9({
       root: typeof current?.root === "string" ? current.root : "./.cnos",
       workspace: workspaceId
     }),
@@ -5287,9 +6521,9 @@ async function updateRootAnchorToWorkspace(packageRoot, workspaceId) {
 async function updateWorkspaceContext(packageRoot, workspaceId) {
   const workspacePath = path25.join(packageRoot, ".cnos-workspace.yml");
   const current = await exists2(workspacePath) ? parseYaml6(await readFile8(workspacePath, "utf8")) : void 0;
-  await writeFile10(
+  await writeFile11(
     workspacePath,
-    stringifyYaml8({
+    stringifyYaml9({
       workspace: workspaceId,
       ...typeof current?.profile === "string" ? { profile: current.profile } : {},
       ...typeof current?.globalRoot === "string" ? { globalRoot: current.globalRoot } : { globalRoot: "~/.cnos" }
@@ -5298,7 +6532,7 @@ async function updateWorkspaceContext(packageRoot, workspaceId) {
   );
 }
 async function runDetach(packageRoot, options = {}) {
-  const loaded = await loadManifest10({ cwd: packageRoot });
+  const loaded = await loadManifest12({ cwd: packageRoot });
   if (!loaded.anchorPath || !loaded.anchoredWorkspace) {
     throw new Error("workspace detach requires a package-local .cnosrc.yml with a workspace binding");
   }
@@ -5318,9 +6552,9 @@ async function runDetach(packageRoot, options = {}) {
   const localRoots = runtime.graph.workspace.workspaceRoots.filter((root) => root.scope === "local").map((root) => root.path);
   await mkdir7(targetCnosRoot, { recursive: true });
   await mergeWorkspaceRootsIntoStandalone(targetCnosRoot, localRoots);
-  await writeFile10(
+  await writeFile11(
     path25.join(targetCnosRoot, "cnos.yml"),
-    stringifyYaml8(createDetachedManifest(loaded.rawManifest)),
+    stringifyYaml9(createDetachedManifest(loaded.rawManifest)),
     "utf8"
   );
   const relativeRoot = path25.relative(packageRoot, loaded.manifestRoot).replace(/\\/g, "/");
@@ -5333,8 +6567,8 @@ async function runDetach(packageRoot, options = {}) {
       workspace: loaded.anchoredWorkspace
     }
   };
-  await writeFile10(path25.join(targetCnosRoot, ".detached"), stringifyYaml8(marker), "utf8");
-  await writeFile10(path25.join(packageRoot, ".cnosrc.yml"), stringifyYaml8({ root: "./.cnos" }), "utf8");
+  await writeFile11(path25.join(targetCnosRoot, ".detached"), stringifyYaml9(marker), "utf8");
+  await writeFile11(path25.join(packageRoot, ".cnosrc.yml"), stringifyYaml9({ root: "./.cnos" }), "utf8");
   if (options.json) {
     return printJson({
       packageRoot,
@@ -5357,7 +6591,7 @@ async function runAttach(packageRoot, options = {}) {
     throw new Error("Invalid .detached marker");
   }
   const parentManifestRoot = path25.resolve(packageRoot, marker.originalCnosrc.root);
-  const parentLoaded = await loadManifest10({ root: parentManifestRoot });
+  const parentLoaded = await loadManifest12({ root: parentManifestRoot });
   if (parentLoaded.rootResolution.readOnly) {
     throw new Error(
       `Cannot attach workspace because the parent CNOS root is remote and read-only (${parentLoaded.rootResolution.rootUri}).`
@@ -5381,7 +6615,7 @@ async function runAttach(packageRoot, options = {}) {
   items[workspaceId] = items[workspaceId] ?? {};
   workspaces.items = items;
   rawManifest.workspaces = workspaces;
-  await writeFile10(path25.join(parentLoaded.manifestRoot, "cnos.yml"), stringifyYaml8(rawManifest), "utf8");
+  await writeFile11(path25.join(parentLoaded.manifestRoot, "cnos.yml"), stringifyYaml9(rawManifest), "utf8");
   const archivePath = path25.join(packageRoot, ".cnos.detached.bak");
   await rm5(archivePath, { recursive: true, force: true });
   await rename(childCnosRoot, archivePath);
@@ -5397,7 +6631,7 @@ async function runAttach(packageRoot, options = {}) {
   return `attached workspace ${workspaceId} to ${displayPath(parentLoaded.manifestRoot, packageRoot)}`;
 }
 async function runList2(manifestCwd, options = {}) {
-  const loaded = await loadManifest10({
+  const loaded = await loadManifest12({
     ...options.root ? { root: options.root } : {},
     cwd: manifestCwd,
     ...options.processEnv ? { processEnv: options.processEnv } : {}
@@ -5430,7 +6664,7 @@ async function runEnable(manifestCwd, packageRoot, options = {}) {
   if (cliArgs.length > 0) {
     throw new Error(`Unsupported workspace arguments: ${cliArgs.join(" ")}`);
   }
-  const loaded = await loadManifest10({
+  const loaded = await loadManifest12({
     ...options.root ? { root: options.root } : {},
     cwd: manifestCwd,
     ...options.processEnv ? { processEnv: options.processEnv } : {}
@@ -5463,7 +6697,7 @@ async function runEnable(manifestCwd, packageRoot, options = {}) {
     base: {}
   };
   rawManifest.workspaces = rawWorkspaces;
-  await writeFile10(path25.join(cnosRoot, "cnos.yml"), stringifyYaml8(rawManifest), "utf8");
+  await writeFile11(path25.join(cnosRoot, "cnos.yml"), stringifyYaml9(rawManifest), "utf8");
   await updateRootAnchorToWorkspace(packageRoot, "base");
   await updateWorkspaceContext(packageRoot, "base");
   await ensureGitignore(path25.dirname(cnosRoot));
@@ -5484,7 +6718,7 @@ async function runAddOrScaffold(action, workspaceId, manifestCwd, packageRoot, o
   if (cliArgs.length > 0) {
     throw new Error(`Unsupported workspace arguments: ${cliArgs.join(" ")}`);
   }
-  const loaded = await loadManifest10({
+  const loaded = await loadManifest12({
     ...options.root ? { root: options.root } : {},
     cwd: manifestCwd,
     ...options.processEnv ? { processEnv: options.processEnv } : {}
@@ -5516,7 +6750,7 @@ async function runAddOrScaffold(action, workspaceId, manifestCwd, packageRoot, o
   rawManifest.workspaces = rawWorkspaces;
   const workspaceRoot = path25.join(cnosRoot, "workspaces", workspaceId);
   const created = await ensureWorkspaceLayout(cnosRoot, workspaceId);
-  await writeFile10(path25.join(cnosRoot, "cnos.yml"), stringifyYaml8(rawManifest), "utf8");
+  await writeFile11(path25.join(cnosRoot, "cnos.yml"), stringifyYaml9(rawManifest), "utf8");
   await ensureGitignore(path25.dirname(cnosRoot));
   await writeAnchor(packageRoot, cnosRoot, workspaceId);
   await updateWorkspaceContext(packageRoot, workspaceId);
@@ -5538,7 +6772,7 @@ async function runRemove(workspaceId, manifestCwd, options = {}) {
   if (cliArgs.length > 0) {
     throw new Error(`Unsupported workspace arguments: ${cliArgs.join(" ")}`);
   }
-  const loaded = await loadManifest10({
+  const loaded = await loadManifest12({
     ...options.root ? { root: options.root } : {},
     cwd: manifestCwd,
     ...options.processEnv ? { processEnv: options.processEnv } : {}
@@ -5560,7 +6794,7 @@ async function runRemove(workspaceId, manifestCwd, options = {}) {
   delete rawItems[workspaceId];
   rawWorkspaces.items = rawItems;
   rawManifest.workspaces = rawWorkspaces;
-  await writeFile10(path25.join(loaded.manifestRoot, "cnos.yml"), stringifyYaml8(rawManifest), "utf8");
+  await writeFile11(path25.join(loaded.manifestRoot, "cnos.yml"), stringifyYaml9(rawManifest), "utf8");
   await rm5(path25.join(loaded.manifestRoot, "workspaces", workspaceId), { recursive: true, force: true });
   if (options.json) {
     return printJson({
@@ -5649,6 +6883,9 @@ function resolveHelpTopic(command, args) {
   if (command === "profile" && args[0] && ["create", "list", "use", "delete", "remove"].includes(args[0])) {
     return normalizeHelpTopic([command, args[0] === "remove" ? "delete" : args[0]]);
   }
+  if (command === "spec" && args[0] && ["list", "show", "set", "delete", "remove", "doctor"].includes(args[0])) {
+    return normalizeHelpTopic([command, args[0] === "remove" ? "delete" : args[0]]);
+  }
   return normalizeHelpTopic([command]);
 }
 async function main(argv) {
@@ -5726,6 +6963,10 @@ async function main(argv) {
       return;
     case "secret":
       process.stdout.write(`${await runSecret(args.length > 0 ? args : ["app.token"], runtimeOptions)}
+`);
+      return;
+    case "spec":
+      process.stdout.write(`${await runSpec(args, runtimeOptions)}
 `);
       return;
     case "vault":