@kitsy/cnos-cli 1.7.0 → 1.8.1

package/dist/index.js

@@ -12,6 +12,7 @@ var COMMAND_OPTION_KEYS_WITH_VALUE = /* @__PURE__ */ new Set([
   "--format",
   "--framework",
   "--prefix",
+  "--mode",
   "--scan",
   "--target",
   "--to",
@@ -23,7 +24,13 @@ var COMMAND_OPTION_KEYS_WITH_VALUE = /* @__PURE__ */ new Set([
   "--as",
   "--set",
   "--debounce",
-  "--expr"
+  "--expr",
+  "--extends",
+  "--workspaces",
+  "--env",
+  "--yaml",
+  "--toml",
+  "--config"
 ]);
 var COMMAND_FLAG_KEYS = /* @__PURE__ */ new Set([
   "--flatten",
@@ -42,7 +49,9 @@ var COMMAND_FLAG_KEYS = /* @__PURE__ */ new Set([
   "--apply",
   "--rewrite",
   "--signal",
-  "--derive"
+  "--derive",
+  "--materialize",
+  "--source-only"
 ]);
 function normalizeCommand(argv) {
   const [command = "doctor", ...rest] = argv;
@@ -158,6 +167,14 @@ function parseArgs(argv) {
       passthrough.push(token);
       continue;
     }
+    if (command === "onboard" && token === "--json") {
+      const nextValue = rest[index + 1];
+      if (nextValue && !nextValue.startsWith("--")) {
+        cliArgs.push(token, nextValue);
+        index += 1;
+        continue;
+      }
+    }
     if (token === "--json") {
       options.json = true;
       continue;
@@ -771,6 +788,8 @@ async function defineValue(namespace, configPath, rawValue, options = {}) {
     const derivedValue = normalizeDerivedValue(options.deriveExpression, options.deriveExprMode ?? false);
     validateParsedDerivation(runtime.manifest, parseDerivation(derivedValue));
     parsedValue = derivedValue;
+  } else if (Object.hasOwn(options, "parsedValue")) {
+    parsedValue = options.parsedValue;
   } else {
     parsedValue = parseScalarValue(rawValue);
   }
@@ -1576,23 +1595,65 @@ var COMMANDS = [
   },
   {
     id: "init",
-    summary: "Scaffold a workspace-aware CNOS tree in the current project.",
-    usage: "cnos init [--workspace <id>] [--root <path>] [--json]",
-    description: "Creates .cnos/cnos.yml, .cnosrc.yml, optional .cnos-workspace.yml, config folders, and .gitignore entries without overwriting existing files.",
-    examples: ["cnos init", "cnos init --workspace api", "cnos init --root ./apps/api --workspace api --json"]
+    summary: "Scaffold a CNOS project in regular mode or workspace mode.",
+    usage: "cnos init [--mode <regular|workspace>] [--workspaces <csv>] [--root <path>] [--json]",
+    description: "Creates .cnos/cnos.yml, .cnosrc.yml, config folders, and .gitignore entries without overwriting existing files. Regular mode is the default; workspace mode creates base plus optional child workspaces.",
+    examples: [
+      "cnos init",
+      "cnos init --mode workspace",
+      "cnos init --mode workspace --workspaces api,web,agents",
+      "cnos init --root ./apps/api --json"
+    ]
   },
   {
     id: "onboard",
-    summary: "Onboard an existing repo into CNOS and import root dotenv files.",
-    usage: "cnos onboard [--workspace <id>] [--root <path>] [--move] [--json]",
-    description: "Scaffolds the CNOS workspace tree and imports root-level .env, .env.<profile>, and .env.*.example files into .cnos/workspaces/<workspace>/env.",
+    summary: "Import existing env or config sources into CNOS and propose value.* mappings.",
+    usage: "cnos onboard [--workspace <id>] [--env <path>|--yaml <path>|--json <path>|--toml <path>|--config <path>] [--materialize|--source-only] [--prefix <path>] [--move] [--root <path>] [--json]",
+    description: "Auto-discovers root .env* files by default, copies them into CNOS source storage, prints proposed value.* mappings, and can materialize those mappings into CNOS values. In workspace mode, imports land in the selected workspace; otherwise they land in the implicit base layer.",
     options: [
+      {
+        flag: "--env <path>",
+        description: "Import one dotenv file instead of auto-discovering root .env* files."
+      },
+      {
+        flag: "--yaml <path>",
+        description: "Import one YAML config file and flatten it into value.* keys."
+      },
+      {
+        flag: "--json <path>",
+        description: "Import one JSON config file and flatten it into value.* keys."
+      },
+      {
+        flag: "--toml <path>",
+        description: "Import one TOML config file and flatten it into value.* keys."
+      },
+      {
+        flag: "--config <path>",
+        description: "Import one config file using extension-based format detection."
+      },
+      {
+        flag: "--materialize",
+        description: "Write the proposed value.* mappings without prompting."
+      },
+      {
+        flag: "--source-only",
+        description: "Copy the source file(s) into CNOS storage but skip value materialization."
+      },
+      {
+        flag: "--prefix <path>",
+        description: "Scope imported keys under value.<prefix>.*."
+      },
       {
         flag: "--move",
-        description: "Move the root env files into CNOS instead of leaving the originals in place."
+        description: "Move the source files into CNOS instead of leaving the originals in place."
       }
     ],
-    examples: ["cnos onboard", "cnos onboard --workspace webapp", "cnos onboard --root ../my-app --workspace app --move"]
+    examples: [
+      "cnos onboard",
+      "cnos onboard --env .env.production --materialize",
+      "cnos onboard --yaml config/app.yml --prefix app",
+      "cnos onboard --workspace api --config config/api.toml"
+    ]
   },
   {
     id: "codegen",
@@ -2214,10 +2275,55 @@ var COMMANDS = [
   },
   {
     id: "workspace",
-    summary: "Attach or detach package-local workspace config from a parent CNOS root.",
-    usage: "cnos workspace <attach|detach> [options] [global-options]",
-    description: "Detaches a child package into a standalone .cnos root or reattaches a detached package back into a parent workspace.",
-    examples: ["cnos workspace detach", "cnos workspace attach --package-root apps/travel"]
+    summary: "Manage workspace creation, listing, migration, and attach/detach flows.",
+    usage: "cnos workspace <enable|add|list|remove|scaffold|attach|detach> [options] [global-options]",
+    description: "Enables workspace mode for flat CNOS projects, adds and removes manifest workspaces, scaffolds package anchors, and handles detach/attach flows for independent child packages.",
+    examples: [
+      "cnos workspace list",
+      "cnos workspace enable",
+      "cnos workspace add travel --package-root apps/travel --extends base",
+      "cnos workspace remove gallery",
+      "cnos workspace detach --package-root apps/travel"
+    ]
+  },
+  {
+    id: "workspace enable",
+    summary: "Convert a flat regular-mode CNOS root into workspace mode with base.",
+    usage: "cnos workspace enable [global-options]",
+    description: "Moves .cnos/values, .cnos/secrets, .cnos/env, and .cnos/profiles into .cnos/workspaces/base, adds a workspaces block to cnos.yml, and updates the root anchor to workspace: base.",
+    examples: ["cnos workspace enable"]
+  },
+  {
+    id: "workspace add",
+    summary: "Add a child workspace to the manifest and scaffold its on-disk layout.",
+    usage: "cnos workspace add <id> [--package-root <path>] [--extends <workspace|none>] [--force] [global-options]",
+    description: "Creates .cnos/workspaces/<id>, updates cnos.yml, and writes a .cnosrc.yml anchor at the selected package root. When a base workspace exists, CNOS defaults new child workspaces to extends: [base] unless --extends or --extends none is provided.",
+    examples: [
+      "cnos workspace add travel --package-root apps/travel --extends base",
+      "cnos workspace add insights --package-root apps/insights",
+      "cnos workspace add api --extends none"
+    ]
+  },
+  {
+    id: "workspace scaffold",
+    summary: "Scaffold a workspace and anchor without changing other runtime flows.",
+    usage: "cnos workspace scaffold <id> [--package-root <path>] [--extends <workspace>] [--force] [global-options]",
+    description: "Creates the workspace manifest entry, workspace folders, and package anchor for a new app or package. This is an alias-oriented workflow for teams that prefer scaffold wording over add.",
+    examples: ["cnos workspace scaffold gallery --package-root apps/gallery --extends base"]
+  },
+  {
+    id: "workspace list",
+    summary: "List declared workspaces and their inheritance.",
+    usage: "cnos workspace list [global-options]",
+    description: "Shows the declared workspace ids, default workspace, and extends relationships from cnos.yml.",
+    examples: ["cnos workspace list", "cnos workspace list --json"]
+  },
+  {
+    id: "workspace remove",
+    summary: "Remove a workspace from the manifest and delete its local workspace tree.",
+    usage: "cnos workspace remove <id> [global-options]",
+    description: "Deletes .cnos/workspaces/<id> and removes the workspace entry from cnos.yml. CNOS refuses to remove the current default workspace until you change workspaces.default.",
+    examples: ["cnos workspace remove gallery", "cnos workspace remove insights --json"]
   },
   {
     id: "workspace detach",
@@ -2511,32 +2617,41 @@ import path10 from "path";
 // src/services/scaffold.ts
 import { mkdir as mkdir4, readFile as readFile3, writeFile as writeFile4 } from "fs/promises";
 import path9 from "path";
-function scaffoldManifest(projectName, workspace) {
+function scaffoldManifest(projectName, options = {}) {
+  const mode = options.mode ?? "regular";
+  const baseWorkspace = options.workspace ?? "base";
+  const workspaceIds = mode === "workspace" ? [baseWorkspace, ...(options.workspaces ?? []).filter((id) => id !== baseWorkspace)] : [];
   const lines = [
     "version: 1",
     "project:",
-    `  name: ${projectName}`,
-    "profiles:",
-    "  default: base",
-    "envMapping:",
-    "  convention: SCREAMING_SNAKE",
-    "public:",
-    "  promote: []",
-    ""
+    `  name: ${projectName}`
   ];
-  if (workspace) {
-    lines.splice(
-      4,
-      0,
+  if (mode === "workspace") {
+    lines.push(
       "workspaces:",
-      `  default: ${workspace}`,
+      `  default: ${baseWorkspace}`,
       "  global:",
       "    enabled: false",
       "    allowWrite: false",
       "  items:",
-      `    ${workspace}: {}`
+      `    ${baseWorkspace}: {}`
     );
+    for (const workspaceId of workspaceIds) {
+      if (workspaceId === baseWorkspace) {
+        continue;
+      }
+      lines.push(`    ${workspaceId}:`, "      extends: [base]");
+    }
   }
+  lines.push(
+    "profiles:",
+    "  default: local",
+    "envMapping:",
+    "  convention: SCREAMING_SNAKE",
+    "public:",
+    "  promote: []",
+    ""
+  );
   return lines.join("\n");
 }
 async function ensureFile(filePath, content) {
@@ -2576,8 +2691,7 @@ async function ensureGitignore(root) {
 `, "utf8");
   return true;
 }
-async function scaffoldWorkspace(root, workspace) {
-  const cnosRoot = path9.join(root, ".cnos");
+async function ensureWorkspaceLayout(cnosRoot, workspace) {
   const workspaceRoot = workspace ? path9.join(cnosRoot, "workspaces", workspace) : cnosRoot;
   const createdPaths = [];
   await mkdir4(path9.join(workspaceRoot, "profiles"), { recursive: true });
@@ -2598,21 +2712,44 @@ async function scaffoldWorkspace(root, workspace) {
   for (const relativePath of relativePaths) {
     const filePath = path9.join(cnosRoot, ...relativePath);
     if (await ensureFile(filePath, "")) {
-      createdPaths.push(path9.relative(root, filePath).replace(/\\/g, "/"));
+      createdPaths.push(path9.relative(path9.dirname(cnosRoot), filePath).replace(/\\/g, "/"));
     }
   }
-  if (await ensureFile(path9.join(cnosRoot, "cnos.yml"), scaffoldManifest(path9.basename(root), workspace))) {
-    createdPaths.push(".cnos/cnos.yml");
-  }
-  if (await ensureFile(
+  return createdPaths;
+}
+async function ensureCnosrc(root, workspace) {
+  return ensureFile(
     path9.join(root, ".cnosrc.yml"),
     workspace ? `root: ./.cnos
 workspace: ${workspace}
 ` : "root: ./.cnos\n"
-  )) {
+  );
+}
+async function scaffoldProject(root, options = {}) {
+  const mode = options.mode ?? "regular";
+  const baseWorkspace = options.workspace ?? "base";
+  const childWorkspaces = mode === "workspace" ? (options.workspaces ?? []).filter((workspaceId) => workspaceId !== baseWorkspace) : [];
+  const cnosRoot = path9.join(root, ".cnos");
+  const createdPaths = [];
+  if (mode === "workspace") {
+    createdPaths.push(
+      ...(await ensureWorkspaceLayout(cnosRoot, baseWorkspace)).map((entry) => entry.replace(/^\.cnos\//, ".cnos/"))
+    );
+    for (const workspaceId of childWorkspaces) {
+      createdPaths.push(
+        ...(await ensureWorkspaceLayout(cnosRoot, workspaceId)).map((entry) => entry.replace(/^\.cnos\//, ".cnos/"))
+      );
+    }
+  } else {
+    createdPaths.push(...(await ensureWorkspaceLayout(cnosRoot)).map((entry) => entry.replace(/^\.cnos\//, ".cnos/")));
+  }
+  if (await ensureFile(path9.join(cnosRoot, "cnos.yml"), scaffoldManifest(path9.basename(root), options))) {
+    createdPaths.push(".cnos/cnos.yml");
+  }
+  if (await ensureCnosrc(root, mode === "workspace" ? baseWorkspace : void 0)) {
     createdPaths.push(".cnosrc.yml");
   }
-  if (workspace && await ensureFile(path9.join(root, ".cnos-workspace.yml"), `workspace: ${workspace}
+  if (mode === "workspace" && await ensureFile(path9.join(root, ".cnos-workspace.yml"), `workspace: ${baseWorkspace}
 globalRoot: ~/.cnos
 `)) {
     createdPaths.push(".cnos-workspace.yml");
@@ -2622,20 +2759,42 @@ globalRoot: ~/.cnos
   }
   return {
     root,
-    ...workspace ? { workspace } : {},
+    mode,
+    ...mode === "workspace" ? { workspace: baseWorkspace, workspaces: [baseWorkspace, ...childWorkspaces] } : {},
     created: createdPaths
   };
 }
 
 // src/commands/init.ts
+function parseWorkspaceList(value) {
+  if (!value) {
+    return [];
+  }
+  return value.split(",").map((entry) => entry.trim()).filter(Boolean);
+}
 async function runInit(options = {}) {
   const root = path10.resolve(options.root ?? process.cwd());
-  const result = await scaffoldWorkspace(root, options.workspace);
+  const cliArgs = [...options.cliArgs ?? []];
+  const modeOption = consumeOption(cliArgs, "--mode");
+  const workspacesOption = consumeOption(cliArgs, "--workspaces");
+  if (cliArgs.length > 0) {
+    throw new Error(`Unsupported init arguments: ${cliArgs.join(" ")}`);
+  }
+  const mode = modeOption === void 0 ? options.workspace ? "workspace" : "regular" : modeOption === "workspace" || modeOption === "regular" ? modeOption : void 0;
+  if (!mode) {
+    throw new Error(`Invalid value for --mode: ${modeOption}. Use "regular" or "workspace".`);
+  }
+  const workspaces = parseWorkspaceList(workspacesOption);
+  const result = await scaffoldProject(root, {
+    mode,
+    ...mode === "workspace" ? { workspace: options.workspace ?? "base", workspaces } : {}
+  });
   if (options.json) {
     return printJson(result);
   }
-  if (result.workspace) {
-    return `initialized CNOS workspace ${result.workspace} at ${root}`;
+  if (result.mode === "workspace" && result.workspace) {
+    const suffix = result.workspaces && result.workspaces.length > 1 ? ` (${result.workspaces.slice(1).join(", ")} extends ${result.workspace})` : "";
+    return `initialized CNOS workspace project at ${root} with base workspace ${result.workspace}${suffix}`;
   }
   return `initialized CNOS project at ${root}`;
 }
@@ -3034,67 +3193,289 @@ async function runNamespace(namespace, args = [], options = {}) {
 }
 
 // src/commands/onboard.ts
-import { copyFile, readdir as readdir3, rm as rm2 } from "fs/promises";
+import { copyFile, mkdir as mkdir5, readdir as readdir3, rm as rm2, stat as stat2, readFile as readFile4 } from "fs/promises";
 import path13 from "path";
+import readline from "readline/promises";
+import { loadManifest as loadManifest5, 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;
+async function exists(targetPath) {
+  try {
+    await stat2(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
 async function listRootEnvFiles(root) {
   const entries = await readdir3(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));
 }
+function normalizePathSegment(value) {
+  return value.trim().replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[^A-Za-z0-9_-]+/g, "_").replace(/^_+|_+$/g, "").toLowerCase();
+}
+function toLogicalPath(sourceKey, prefixSegments) {
+  const derivedSegments = sourceKey.split(/[._-]+/).map((segment) => normalizePathSegment(segment)).filter(Boolean);
+  return [...prefixSegments, ...derivedSegments].join(".");
+}
+function toWarning(sourceKey) {
+  return SECRET_LIKE_PATTERN.test(sourceKey) ? "looks like a secret" : void 0;
+}
+function createProposedMapping(source, pathKey, value, warning) {
+  return {
+    source,
+    key: `value.${pathKey}`,
+    path: pathKey,
+    value,
+    ...warning ? { warning } : {}
+  };
+}
+function parseEnv(content) {
+  const values = {};
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) {
+      continue;
+    }
+    const separator = line.indexOf("=");
+    if (separator <= 0) {
+      continue;
+    }
+    const key = line.slice(0, separator).trim();
+    let value = line.slice(separator + 1).trim();
+    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1);
+    }
+    values[key] = value;
+  }
+  return values;
+}
+function flattenStructured(value, prefixSegments, currentKey = []) {
+  if (Array.isArray(value) || value === null || typeof value !== "object") {
+    const pathKey = [...prefixSegments, ...currentKey.map((segment) => normalizePathSegment(segment)).filter(Boolean)].join(".");
+    const sourceKey = currentKey.join(".");
+    return pathKey ? [
+      createProposedMapping(sourceKey, pathKey, value, sourceKey ? toWarning(sourceKey) : void 0)
+    ] : [];
+  }
+  return Object.entries(value).flatMap(
+    ([key, nested]) => flattenStructured(nested, prefixSegments, [...currentKey, key])
+  );
+}
+async function parseSource(input, prefixSegments) {
+  const content = await readFile4(input.filePath, "utf8");
+  switch (input.kind) {
+    case "env":
+      return Object.entries(parseEnv(content)).map(([sourceKey, value]) => {
+        const logicalPath = toLogicalPath(sourceKey, prefixSegments);
+        return createProposedMapping(sourceKey, logicalPath, value, toWarning(sourceKey));
+      });
+    case "yaml":
+      return flattenStructured(parseYaml3(content), prefixSegments);
+    case "json":
+      return flattenStructured(JSON.parse(content), prefixSegments);
+    case "toml":
+      return flattenStructured(parseToml(content), prefixSegments);
+  }
+}
+function detectKindFromPath(filePath) {
+  const ext = path13.extname(filePath).toLowerCase();
+  switch (ext) {
+    case ".env":
+      return "env";
+    case ".yaml":
+    case ".yml":
+      return "yaml";
+    case ".json":
+      return "json";
+    case ".toml":
+      return "toml";
+    default:
+      throw new Error(`Unsupported config format for ${filePath}. Use --env, --yaml, --json, --toml, or --config with a supported extension.`);
+  }
+}
+function buildPrefixSegments(prefix) {
+  if (!prefix) {
+    return [];
+  }
+  return prefix.split(".").map((segment) => normalizePathSegment(segment)).filter(Boolean);
+}
+function formatProposals(proposed) {
+  if (proposed.length === 0) {
+    return ["No value mappings were discovered."];
+  }
+  return proposed.map((entry) => {
+    const renderedValue = typeof entry.value === "string" ? JSON.stringify(entry.value) : JSON.stringify(entry.value);
+    return `  ${entry.source || entry.path} -> ${entry.key} = ${renderedValue}${entry.warning ? `  [${entry.warning}]` : ""}`;
+  });
+}
+async function promptForMaterialize() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  try {
+    const answer = (await rl.question("Materialize these values into value.*? [Y/n] ")).trim().toLowerCase();
+    return answer === "" || answer === "y" || answer === "yes";
+  } finally {
+    rl.close();
+  }
+}
+function isInteractive(options) {
+  const processEnv = options.processEnv ?? process.env;
+  return !processEnv.CI && process.stdin.isTTY && process.stdout.isTTY;
+}
+function resolveSourceInputs(root, cliArgs) {
+  const envFile = consumeOption(cliArgs, "--env");
+  const yamlFile = consumeOption(cliArgs, "--yaml");
+  const jsonFile = consumeOption(cliArgs, "--json");
+  const tomlFile = consumeOption(cliArgs, "--toml");
+  const configFile = consumeOption(cliArgs, "--config");
+  const explicit = [
+    envFile ? { kind: "env", filePath: envFile } : void 0,
+    yamlFile ? { kind: "yaml", filePath: yamlFile } : void 0,
+    jsonFile ? { kind: "json", filePath: jsonFile } : void 0,
+    tomlFile ? { kind: "toml", filePath: tomlFile } : void 0,
+    configFile ? { kind: detectKindFromPath(configFile), filePath: configFile } : void 0
+  ].filter(Boolean);
+  if (explicit.length > 1) {
+    throw new Error("Use only one explicit source flag per onboard invocation.");
+  }
+  if (explicit.length === 1) {
+    const source = explicit[0];
+    if (!source) {
+      return [];
+    }
+    const resolvedPath = path13.resolve(root, source.filePath);
+    return [
+      {
+        kind: source.kind,
+        filePath: resolvedPath,
+        displayName: path13.basename(resolvedPath)
+      }
+    ];
+  }
+  return [];
+}
 async function runOnboard(options = {}) {
   const root = path13.resolve(options.root ?? process.cwd());
-  const workspace = options.workspace ?? path13.basename(root);
   const cliArgs = [...options.cliArgs ?? []];
   const move = consumeFlag(cliArgs, "--move");
+  const materialize = consumeFlag(cliArgs, "--materialize");
+  const sourceOnly = consumeFlag(cliArgs, "--source-only");
+  const prefix = consumeOption(cliArgs, "--prefix");
+  if (materialize && sourceOnly) {
+    throw new Error("Use either --materialize or --source-only, not both.");
+  }
+  const explicitSources = resolveSourceInputs(root, cliArgs);
   if (cliArgs.length > 0) {
     throw new Error(`Unsupported onboard arguments: ${cliArgs.join(" ")}`);
   }
-  const scaffold = await scaffoldWorkspace(root, workspace);
-  const envRoot = path13.join(root, ".cnos", "workspaces", workspace, "env");
-  const rootFiles = await listRootEnvFiles(root);
+  let scaffolded = [];
+  const manifestPath = path13.join(root, ".cnos", "cnos.yml");
+  if (!await exists(manifestPath)) {
+    const scaffold = await scaffoldProject(root, {
+      mode: options.workspace && options.workspace !== "base" ? "workspace" : "regular",
+      ...options.workspace && options.workspace !== "base" ? { workspaces: [options.workspace] } : {}
+    });
+    scaffolded = scaffold.created;
+  }
+  const loaded = await loadManifest5({
+    root,
+    ...options.processEnv ? { processEnv: options.processEnv } : {}
+  });
+  const isWorkspaceMode = Object.keys(loaded.manifest.workspaces.items).length > 0;
+  const selectedWorkspace = isWorkspaceMode ? options.workspace ?? (loaded.manifest.workspaces.items.base ? "base" : loaded.manifest.workspaces.default ?? "base") : "base";
+  if (isWorkspaceMode && !loaded.manifest.workspaces.items[selectedWorkspace]) {
+    throw new Error(`Workspace "${selectedWorkspace}" does not exist in this CNOS root.`);
+  }
+  if (!isWorkspaceMode && options.workspace && options.workspace !== "base") {
+    throw new Error("This repo is still in regular mode. Run `cnos workspace enable` before onboarding into a child workspace.");
+  }
+  const envRoot = isWorkspaceMode ? path13.join(root, ".cnos", "workspaces", selectedWorkspace, "env") : path13.join(root, ".cnos", "env");
+  await mkdir5(envRoot, { recursive: true });
+  const rootFiles = explicitSources.length > 0 ? explicitSources : (await listRootEnvFiles(root)).map((fileName) => ({
+    kind: "env",
+    filePath: path13.join(root, fileName),
+    displayName: fileName
+  }));
   const imported = [];
   const skipped = [];
-  for (const fileName of rootFiles) {
-    const sourcePath = path13.join(root, fileName);
-    const targetPath = path13.join(envRoot, fileName);
+  const prefixSegments = buildPrefixSegments(prefix);
+  const proposed = [];
+  for (const source of rootFiles) {
+    const targetPath = path13.join(envRoot, source.displayName);
     try {
-      await copyFile(sourcePath, targetPath);
+      await copyFile(source.filePath, targetPath);
       imported.push(path13.relative(root, targetPath).replace(/\\/g, "/"));
       if (move) {
-        await rm2(sourcePath);
+        await rm2(source.filePath);
       }
     } catch {
-      skipped.push(fileName);
+      skipped.push(source.displayName);
+      continue;
+    }
+    proposed.push(...await parseSource(source, prefixSegments));
+  }
+  const shouldMaterialize = materialize || (!sourceOnly && isInteractive(options) && proposed.length > 0 ? await promptForMaterialize() : false);
+  const materialized = [];
+  if (shouldMaterialize) {
+    for (const entry of proposed) {
+      await defineValue("value", entry.path, String(entry.value ?? ""), {
+        root,
+        ...isWorkspaceMode ? { workspace: selectedWorkspace } : {},
+        parsedValue: entry.value
+      });
+      materialized.push(entry.key);
     }
   }
   const result = {
     root,
-    workspace,
-    scaffolded: scaffold.created,
+    workspace: selectedWorkspace,
+    mode: move ? "move" : "copy",
+    storageMode: isWorkspaceMode ? "workspace" : "regular",
+    scaffolded,
     imported,
     skipped,
-    mode: move ? "move" : "copy"
+    proposed,
+    materialized
   };
   if (options.json) {
     return printJson(result);
   }
-  const importedCount = imported.length;
-  const skippedSuffix = skipped.length > 0 ? ` (${skipped.length} skipped)` : "";
-  return `onboarded ${workspace} at ${root}; imported ${importedCount} root env files into .cnos/workspaces/${workspace}/env using ${result.mode}${skippedSuffix}`;
+  const lines = [
+    `onboarded ${selectedWorkspace} at ${root}`,
+    `Imported ${imported.length} source file(s) into ${path13.relative(root, envRoot).replace(/\\/g, "/") || ".cnos/env"} using ${result.mode}.`,
+    "",
+    `Discovered ${proposed.length} proposed value mapping(s):`,
+    ...formatProposals(proposed)
+  ];
+  if (!shouldMaterialize && !sourceOnly && !isInteractive(options) && proposed.length > 0) {
+    lines.push("", "Non-interactive mode detected; defaulted to source-only. Re-run with --materialize to write value.* keys.");
+  } else if (shouldMaterialize) {
+    lines.push("", `Materialized ${materialized.length} value key(s).`);
+  } else if (sourceOnly) {
+    lines.push("", "Skipped value materialization because --source-only was set.");
+  }
+  if (skipped.length > 0) {
+    lines.push("", `Skipped ${skipped.length} source file(s): ${skipped.join(", ")}`);
+  }
+  return lines.join("\n");
 }
 
 // src/commands/profile.ts
 import path16 from "path";
 
 // src/services/context.ts
-import { readFile as readFile4, writeFile as writeFile5 } from "fs/promises";
+import { readFile as readFile5, writeFile as writeFile5 } from "fs/promises";
 import path14 from "path";
-import { parseYaml as parseYaml3, stringifyYaml as stringifyYaml3 } from "@kitsy/cnos/internal";
+import { parseYaml as parseYaml4, stringifyYaml as stringifyYaml3 } from "@kitsy/cnos/internal";
 async function loadCliContext(root = process.cwd()) {
   const filePath = path14.join(path14.resolve(root), ".cnos-workspace.yml");
   try {
-    const source = await readFile4(filePath, "utf8");
-    const parsed = parseYaml3(source);
+    const source = await readFile5(filePath, "utf8");
+    const parsed = parseYaml4(source);
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
       return {};
     }
@@ -3123,21 +3504,21 @@ async function saveCliContext(options = {}) {
 }
 
 // src/services/profiles.ts
-import { mkdir as mkdir5, readdir as readdir4, readFile as readFile5, rm as rm3, writeFile as writeFile6 } from "fs/promises";
+import { mkdir as mkdir6, readdir as readdir4, readFile as readFile6, rm as rm3, writeFile as writeFile6 } from "fs/promises";
 import path15 from "path";
-import { loadManifest as loadManifest5, parseYaml as parseYaml4, stringifyYaml as stringifyYaml4 } from "@kitsy/cnos/internal";
+import { loadManifest as loadManifest6, parseYaml as parseYaml5, stringifyYaml as stringifyYaml4 } from "@kitsy/cnos/internal";
 async function resolveProfilesRoot(root = process.cwd()) {
   try {
-    const loadedManifest = await loadManifest5({ root });
+    const loadedManifest = await loadManifest6({ root });
     return path15.join(loadedManifest.manifestRoot, "profiles");
   } catch {
-    const loadedManifest = await loadManifest5({ cwd: root });
+    const loadedManifest = await loadManifest6({ cwd: root });
     return path15.join(loadedManifest.manifestRoot, "profiles");
   }
 }
 async function createProfileDefinition(root = process.cwd(), profile, inherit, options = {}) {
   const filePath = path15.join(await resolveProfilesRoot(root), `${profile}.yml`);
-  await mkdir5(path15.dirname(filePath), { recursive: true });
+  await mkdir6(path15.dirname(filePath), { recursive: true });
   const document = options.noInherit ? {
     name: profile,
     activate: {
@@ -3197,7 +3578,7 @@ async function readProfileDefinition(root = process.cwd(), profile = "base") {
   }
   const filePath = path15.join(await resolveProfilesRoot(root), `${profile}.yml`);
   try {
-    return parseYaml4(await readFile5(filePath, "utf8")) ?? void 0;
+    return parseYaml5(await readFile6(filePath, "utf8")) ?? void 0;
   } catch {
     return void 0;
   }
@@ -3277,7 +3658,7 @@ import path17 from "path";
 import { writeFile as writeFile7 } from "fs/promises";
 import {
   ensureProjectionAllowed,
-  loadManifest as loadManifest6,
+  loadManifest as loadManifest7,
   stringifyYaml as stringifyYaml5
 } from "@kitsy/cnos/internal";
 function normalizeTarget(value) {
@@ -3306,7 +3687,7 @@ async function runPromote(args = [], options = {}) {
       throw new Error("promote --to env requires --as <ENV_VAR>");
     }
   }
-  const loadedManifest = await loadManifest6({
+  const loadedManifest = await loadManifest7({
     ...options.root ? { root: options.root } : {},
     ...options.cwd ? { cwd: options.cwd } : {},
     ...options.processEnv ? { processEnv: options.processEnv } : {},
@@ -3473,7 +3854,7 @@ import {
   createSecretVault,
   deriveVaultKey,
   listLocalSecrets,
-  loadManifest as loadManifest7,
+  loadManifest as loadManifest8,
   listSecretVaults,
   readVaultMetadata,
   resolveSecretStoreRoot as resolveSecretStoreRoot2,
@@ -3512,7 +3893,7 @@ async function createVaultDefinition(name, options = {}) {
   if (provider === "local" && (options.noPassphrase ?? false)) {
     throw new Error("Local vaults cannot be passwordless.");
   }
-  const loadedManifest = await loadManifest7({
+  const loadedManifest = await loadManifest8({
     ...options.root ? { root: options.root } : {},
     ...options.cwd ? { cwd: options.cwd } : {},
     ...options.processEnv ? { processEnv: options.processEnv } : {},
@@ -3549,7 +3930,7 @@ async function createVaultDefinition(name, options = {}) {
   };
 }
 async function listVaultDefinitions(options = {}) {
-  const loadedManifest = await loadManifest7({
+  const loadedManifest = await loadManifest8({
     ...options.root ? { root: options.root } : {},
     ...options.cwd ? { cwd: options.cwd } : {},
     ...options.processEnv ? { processEnv: options.processEnv } : {},
@@ -3570,7 +3951,7 @@ async function listVaultDefinitions(options = {}) {
 async function removeVaultDefinition(name, options = {}) {
   await assertWritableConfigRoot(`remove vault ${name}`, options);
   const vault = name.trim() || "default";
-  const loadedManifest = await loadManifest7({
+  const loadedManifest = await loadManifest8({
     ...options.root ? { root: options.root } : {},
     ...options.cwd ? { cwd: options.cwd } : {},
     ...options.processEnv ? { processEnv: options.processEnv } : {},
@@ -3616,7 +3997,7 @@ async function listLocalStoreVaults(options = {}) {
 }
 async function authenticateVault(name, options = {}) {
   const vault = name.trim() || "default";
-  const loadedManifest = await loadManifest7({
+  const loadedManifest = await loadManifest8({
     ...options.root ? { root: options.root } : {},
     ...options.cwd ? { cwd: options.cwd } : {},
     ...options.processEnv ? { processEnv: options.processEnv } : {},
@@ -3937,7 +4318,7 @@ async function runValidate(options = {}) {
 // package.json
 var package_default = {
   name: "@kitsy/cnos-cli",
-  version: "1.7.0",
+  version: "1.8.1",
   description: "CLI entry point and developer tooling for CNOS.",
   type: "module",
   main: "./dist/index.js",
@@ -3973,7 +4354,8 @@ var package_default = {
     access: "public"
   },
   dependencies: {
-    "@kitsy/cnos": "workspace:*"
+    "@kitsy/cnos": "workspace:*",
+    "smol-toml": "^1.4.2"
   },
   scripts: {
     build: "tsup src/index.ts --format esm --dts",
@@ -4212,40 +4594,52 @@ async function runWatch(command, options = {}) {
 }
 
 // src/commands/workspace.ts
-import { cp, mkdir as mkdir6, rename, rm as rm5, stat as stat2, writeFile as writeFile9, readFile as readFile6 } from "fs/promises";
+import { cp, mkdir as mkdir7, readdir as readdir5, readFile as readFile7, rename, rm as rm5, stat as stat3, writeFile as writeFile9 } from "fs/promises";
 import path23 from "path";
-import { loadManifest as loadManifest8, parseYaml as parseYaml5, stringifyYaml as stringifyYaml7 } from "@kitsy/cnos/internal";
-async function exists(targetPath) {
+import { loadManifest as loadManifest9, parseYaml as parseYaml6, stringifyYaml as stringifyYaml7 } from "@kitsy/cnos/internal";
+async function exists2(targetPath) {
   try {
-    await stat2(targetPath);
+    await stat3(targetPath);
     return true;
   } catch {
     return false;
   }
 }
 async function copyIfExists(source, target) {
-  if (!await exists(source)) {
+  if (!await exists2(source)) {
     return;
   }
-  await mkdir6(path23.dirname(target), { recursive: true });
+  await mkdir7(path23.dirname(target), { recursive: true });
   await cp(source, target, { recursive: true, force: true });
 }
+async function moveIfExists(source, target, force = false) {
+  if (!await exists2(source)) {
+    return false;
+  }
+  if (force) {
+    await rm5(target, { recursive: true, force: true });
+  } else if (await exists2(target)) {
+    throw new Error(`Refusing to overwrite existing path ${target}. Use --force to replace it.`);
+  }
+  await mkdir7(path23.dirname(target), { recursive: true });
+  await rename(source, target);
+  return true;
+}
 async function mergeWorkspaceRootsIntoStandalone(targetCnosRoot, sourceRoots) {
   for (const sourceRoot of sourceRoots) {
     for (const folderName of ["values", "secrets", "env", "profiles"]) {
-      await copyIfExists(
-        path23.join(sourceRoot, folderName),
-        path23.join(targetCnosRoot, folderName)
-      );
+      await copyIfExists(path23.join(sourceRoot, folderName), path23.join(targetCnosRoot, folderName));
     }
   }
 }
-async function writeCnosrc(packageRoot, config) {
+async function writeAnchor(packageRoot, manifestRoot, workspace) {
+  const relativeRoot = path23.relative(packageRoot, manifestRoot).replace(/\\/g, "/");
+  const rootValue = relativeRoot.length === 0 ? "./.cnos" : relativeRoot.startsWith(".") ? relativeRoot : `./${relativeRoot}`;
   await writeFile9(
     path23.join(packageRoot, ".cnosrc.yml"),
     stringifyYaml7({
-      root: config.root,
-      ...config.workspace ? { workspace: config.workspace } : {}
+      root: rootValue,
+      ...workspace ? { workspace } : {}
     }),
     "utf8"
   );
@@ -4257,14 +4651,72 @@ function createDetachedManifest(rawManifest) {
   }
   return next;
 }
+function normalizeWorkspaceId(value) {
+  const workspaceId = value?.trim();
+  if (!workspaceId) {
+    throw new Error("Workspace id is required");
+  }
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(workspaceId)) {
+    throw new Error(`Invalid workspace id "${workspaceId}". Use letters, numbers, dot, underscore, or dash.`);
+  }
+  return workspaceId;
+}
+function splitExtends(value) {
+  if (!value) {
+    return void 0;
+  }
+  if (value.trim() === "none") {
+    return [];
+  }
+  const items = value.split(",").map((entry) => entry.trim()).filter(Boolean);
+  return items.length > 0 ? items : void 0;
+}
+async function hasDirectConfigData(cnosRoot) {
+  for (const folderName of ["values", "secrets", "env", "profiles"]) {
+    const folder = path23.join(cnosRoot, folderName);
+    if (!await exists2(folder)) {
+      continue;
+    }
+    const entries = await readdir5(folder, { withFileTypes: true });
+    if (entries.some((entry) => entry.name !== ".gitkeep")) {
+      return true;
+    }
+  }
+  return false;
+}
+async function updateRootAnchorToWorkspace(packageRoot, workspaceId) {
+  const anchorPath = path23.join(packageRoot, ".cnosrc.yml");
+  const current = await exists2(anchorPath) ? parseYaml6(await readFile7(anchorPath, "utf8")) : void 0;
+  await writeFile9(
+    anchorPath,
+    stringifyYaml7({
+      root: typeof current?.root === "string" ? current.root : "./.cnos",
+      workspace: workspaceId
+    }),
+    "utf8"
+  );
+}
+async function updateWorkspaceContext(packageRoot, workspaceId) {
+  const workspacePath = path23.join(packageRoot, ".cnos-workspace.yml");
+  const current = await exists2(workspacePath) ? parseYaml6(await readFile7(workspacePath, "utf8")) : void 0;
+  await writeFile9(
+    workspacePath,
+    stringifyYaml7({
+      workspace: workspaceId,
+      ...typeof current?.profile === "string" ? { profile: current.profile } : {},
+      ...typeof current?.globalRoot === "string" ? { globalRoot: current.globalRoot } : { globalRoot: "~/.cnos" }
+    }),
+    "utf8"
+  );
+}
 async function runDetach(packageRoot, options = {}) {
-  const loaded = await loadManifest8({ cwd: packageRoot });
+  const loaded = await loadManifest9({ cwd: packageRoot });
   if (!loaded.anchorPath || !loaded.anchoredWorkspace) {
     throw new Error("workspace detach requires a package-local .cnosrc.yml with a workspace binding");
   }
   const targetCnosRoot = path23.join(packageRoot, ".cnos");
   const force = consumeFlag([...options.cliArgs ?? []], "--force");
-  if (await exists(targetCnosRoot) && !force) {
+  if (await exists2(targetCnosRoot) && !force) {
     throw new Error(`Refusing to detach because ${displayPath(targetCnosRoot, packageRoot)} already exists. Use --force to overwrite.`);
   }
   if (force) {
@@ -4276,7 +4728,7 @@ async function runDetach(packageRoot, options = {}) {
     workspace: loaded.anchoredWorkspace
   });
   const localRoots = runtime.graph.workspace.workspaceRoots.filter((root) => root.scope === "local").map((root) => root.path);
-  await mkdir6(targetCnosRoot, { recursive: true });
+  await mkdir7(targetCnosRoot, { recursive: true });
   await mergeWorkspaceRootsIntoStandalone(targetCnosRoot, localRoots);
   await writeFile9(
     path23.join(targetCnosRoot, "cnos.yml"),
@@ -4294,7 +4746,7 @@ async function runDetach(packageRoot, options = {}) {
     }
   };
   await writeFile9(path23.join(targetCnosRoot, ".detached"), stringifyYaml7(marker), "utf8");
-  await writeCnosrc(packageRoot, { root: "./.cnos" });
+  await writeFile9(path23.join(packageRoot, ".cnosrc.yml"), stringifyYaml7({ root: "./.cnos" }), "utf8");
   if (options.json) {
     return printJson({
       packageRoot,
@@ -4309,15 +4761,15 @@ async function runAttach(packageRoot, options = {}) {
   const force = consumeFlag(cliArgs, "--force");
   const childCnosRoot = path23.join(packageRoot, ".cnos");
   const markerPath = path23.join(childCnosRoot, ".detached");
-  if (!await exists(markerPath)) {
+  if (!await exists2(markerPath)) {
     throw new Error("workspace attach requires a detached package with .cnos/.detached");
   }
-  const marker = parseYaml5(await readFile6(markerPath, "utf8"));
+  const marker = parseYaml6(await readFile7(markerPath, "utf8"));
   if (!marker?.originalCnosrc?.root || !marker.detachedWorkspace) {
     throw new Error("Invalid .detached marker");
   }
   const parentManifestRoot = path23.resolve(packageRoot, marker.originalCnosrc.root);
-  const parentLoaded = await loadManifest8({ root: parentManifestRoot });
+  const parentLoaded = await loadManifest9({ 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}).`
@@ -4325,17 +4777,17 @@ async function runAttach(packageRoot, options = {}) {
   }
   const workspaceId = marker.originalCnosrc.workspace ?? marker.detachedWorkspace;
   const parentWorkspaceRoot = path23.join(parentLoaded.manifestRoot, "workspaces", workspaceId);
-  if (await exists(parentWorkspaceRoot) && !force) {
+  if (await exists2(parentWorkspaceRoot) && !force) {
     throw new Error(`workspace "${workspaceId}" already exists in parent root. Use --force to overwrite.`);
   }
   if (force) {
     await rm5(parentWorkspaceRoot, { recursive: true, force: true });
   }
-  await mkdir6(parentWorkspaceRoot, { recursive: true });
+  await mkdir7(parentWorkspaceRoot, { recursive: true });
   for (const folderName of ["values", "secrets", "env", "profiles"]) {
     await copyIfExists(path23.join(childCnosRoot, folderName), path23.join(parentWorkspaceRoot, folderName));
   }
-  const rawManifest = parentLoaded.rawManifest;
+  const rawManifest = structuredClone(parentLoaded.rawManifest);
   const workspaces = rawManifest.workspaces ?? {};
   const items = workspaces.items ?? {};
   items[workspaceId] = items[workspaceId] ?? {};
@@ -4345,10 +4797,7 @@ async function runAttach(packageRoot, options = {}) {
   const archivePath = path23.join(packageRoot, ".cnos.detached.bak");
   await rm5(archivePath, { recursive: true, force: true });
   await rename(childCnosRoot, archivePath);
-  await writeCnosrc(packageRoot, {
-    root: marker.originalCnosrc.root,
-    ...workspaceId ? { workspace: workspaceId } : {}
-  });
+  await writeAnchor(packageRoot, parentLoaded.manifestRoot, workspaceId);
   if (options.json) {
     return printJson({
       packageRoot,
@@ -4359,15 +4808,210 @@ async function runAttach(packageRoot, options = {}) {
   }
   return `attached workspace ${workspaceId} to ${displayPath(parentLoaded.manifestRoot, packageRoot)}`;
 }
-async function runWorkspace(args = [], options = {}) {
-  const [action] = args;
+async function runList2(manifestCwd, options = {}) {
+  const loaded = await loadManifest9({
+    ...options.root ? { root: options.root } : {},
+    cwd: manifestCwd,
+    ...options.processEnv ? { processEnv: options.processEnv } : {}
+  });
+  const entries = Object.entries(loaded.manifest.workspaces.items).map(([id, config]) => ({
+    id,
+    extends: config.extends,
+    default: loaded.manifest.workspaces.default === id,
+    path: path23.join(loaded.manifestRoot, "workspaces", id)
+  })).sort((left, right) => left.id.localeCompare(right.id));
+  if (options.json) {
+    return printJson({
+      default: loaded.manifest.workspaces.default,
+      workspaces: entries
+    });
+  }
+  if (entries.length === 0) {
+    return "no workspaces declared";
+  }
+  return entries.map((entry) => {
+    const tags = [
+      entry.default ? "default" : void 0,
+      entry.extends.length > 0 ? `extends=${entry.extends.join(",")}` : void 0
+    ].filter(Boolean);
+    return `${entry.id}${tags.length > 0 ? ` (${tags.join(", ")})` : ""}`;
+  }).join("\n");
+}
+async function runEnable(manifestCwd, packageRoot, options = {}) {
+  const cliArgs = [...options.cliArgs ?? []];
+  if (cliArgs.length > 0) {
+    throw new Error(`Unsupported workspace arguments: ${cliArgs.join(" ")}`);
+  }
+  const loaded = await loadManifest9({
+    ...options.root ? { root: options.root } : {},
+    cwd: manifestCwd,
+    ...options.processEnv ? { processEnv: options.processEnv } : {}
+  });
+  if (loaded.rootResolution.readOnly) {
+    throw new Error(
+      `Cannot enable workspace mode because the active CNOS root is remote and read-only (${loaded.rootResolution.rootUri}). Clone the config repo and edit it directly.`
+    );
+  }
+  const rawManifest = structuredClone(loaded.rawManifest);
+  const rawWorkspaces = rawManifest.workspaces ?? {};
+  const rawItems = rawWorkspaces.items ?? {};
+  if (Object.keys(rawItems).length > 0) {
+    throw new Error("This CNOS root is already in workspace mode.");
+  }
+  const cnosRoot = loaded.manifestRoot;
+  const baseWorkspaceRoot = path23.join(cnosRoot, "workspaces", "base");
+  if (await exists2(baseWorkspaceRoot)) {
+    throw new Error("Cannot enable workspace mode because .cnos/workspaces/base already exists.");
+  }
+  const moved = [];
+  for (const folderName of ["values", "secrets", "env", "profiles"]) {
+    if (await moveIfExists(path23.join(cnosRoot, folderName), path23.join(baseWorkspaceRoot, folderName))) {
+      moved.push(folderName);
+    }
+  }
+  await ensureWorkspaceLayout(cnosRoot, "base");
+  rawWorkspaces.default = "base";
+  rawWorkspaces.items = {
+    base: {}
+  };
+  rawManifest.workspaces = rawWorkspaces;
+  await writeFile9(path23.join(cnosRoot, "cnos.yml"), stringifyYaml7(rawManifest), "utf8");
+  await updateRootAnchorToWorkspace(packageRoot, "base");
+  await updateWorkspaceContext(packageRoot, "base");
+  await ensureGitignore(path23.dirname(cnosRoot));
+  if (options.json) {
+    return printJson({
+      root: path23.dirname(cnosRoot),
+      workspace: "base",
+      moved
+    });
+  }
+  const movedSummary = moved.length > 0 ? `; moved ${moved.join(", ")} into .cnos/workspaces/base` : "";
+  return `enabled workspace mode at ${displayPath(path23.dirname(cnosRoot), packageRoot)} with base workspace${movedSummary}`;
+}
+async function runAddOrScaffold(action, workspaceId, manifestCwd, packageRoot, options = {}) {
+  const cliArgs = [...options.cliArgs ?? []];
+  const extendsOption = splitExtends(consumeOption(cliArgs, "--extends"));
+  const force = consumeFlag(cliArgs, "--force");
+  if (cliArgs.length > 0) {
+    throw new Error(`Unsupported workspace arguments: ${cliArgs.join(" ")}`);
+  }
+  const loaded = await loadManifest9({
+    ...options.root ? { root: options.root } : {},
+    cwd: manifestCwd,
+    ...options.processEnv ? { processEnv: options.processEnv } : {}
+  });
+  if (loaded.rootResolution.readOnly) {
+    throw new Error(
+      `Cannot ${action} workspace because the active CNOS root is remote and read-only (${loaded.rootResolution.rootUri}). Clone the config repo and edit it directly.`
+    );
+  }
+  const manifestRoot = loaded.manifestRoot;
+  const cnosRoot = manifestRoot;
+  const rawManifest = structuredClone(loaded.rawManifest);
+  const rawWorkspaces = rawManifest.workspaces ?? {};
+  const rawItems = rawWorkspaces.items ?? {};
+  const isWorkspaceMode = Object.keys(rawItems).length > 0;
+  const directConfigPresent = await hasDirectConfigData(cnosRoot);
+  if (!isWorkspaceMode || directConfigPresent) {
+    throw new Error(
+      "This CNOS root is not ready for child workspaces yet. Run `cnos workspace enable` first to convert the flat project into workspace mode."
+    );
+  }
+  if (rawItems[workspaceId] && !force) {
+    throw new Error(`workspace "${workspaceId}" already exists. Use --force to update its manifest entry and anchor.`);
+  }
+  const defaultExtends = extendsOption ?? (!["base", "root"].includes(workspaceId) && rawItems.base ? ["base"] : void 0);
+  rawItems[workspaceId] = defaultExtends && defaultExtends.length > 0 ? { extends: defaultExtends } : {};
+  rawWorkspaces.items = rawItems;
+  rawWorkspaces.default = rawWorkspaces.default ?? workspaceId;
+  rawManifest.workspaces = rawWorkspaces;
+  const workspaceRoot = path23.join(cnosRoot, "workspaces", workspaceId);
+  const created = await ensureWorkspaceLayout(cnosRoot, workspaceId);
+  await writeFile9(path23.join(cnosRoot, "cnos.yml"), stringifyYaml7(rawManifest), "utf8");
+  await ensureGitignore(path23.dirname(cnosRoot));
+  await writeAnchor(packageRoot, cnosRoot, workspaceId);
+  await updateWorkspaceContext(packageRoot, workspaceId);
+  const result = {
+    workspace: workspaceId,
+    root: path23.dirname(cnosRoot),
+    packageRoot,
+    created
+  };
+  if (options.json) {
+    return printJson(result);
+  }
+  const verb = action === "add" ? "added" : "scaffolded";
+  return `${verb} workspace ${workspaceId} at ${displayPath(workspaceRoot, packageRoot)}`;
+}
+async function runRemove(workspaceId, manifestCwd, options = {}) {
   const cliArgs = [...options.cliArgs ?? []];
-  const packageRoot = path23.resolve(consumeOption(cliArgs, "--package-root") ?? options.root ?? process.cwd());
+  consumeFlag(cliArgs, "--force");
+  if (cliArgs.length > 0) {
+    throw new Error(`Unsupported workspace arguments: ${cliArgs.join(" ")}`);
+  }
+  const loaded = await loadManifest9({
+    ...options.root ? { root: options.root } : {},
+    cwd: manifestCwd,
+    ...options.processEnv ? { processEnv: options.processEnv } : {}
+  });
+  if (loaded.rootResolution.readOnly) {
+    throw new Error(
+      `Cannot remove workspace because the active CNOS root is remote and read-only (${loaded.rootResolution.rootUri}). Clone the config repo and edit it directly.`
+    );
+  }
+  const rawManifest = structuredClone(loaded.rawManifest);
+  const rawWorkspaces = rawManifest.workspaces ?? {};
+  const rawItems = rawWorkspaces.items ?? {};
+  if (!rawItems[workspaceId]) {
+    throw new Error(`workspace "${workspaceId}" does not exist`);
+  }
+  if (rawWorkspaces.default === workspaceId) {
+    throw new Error(`Cannot remove workspace "${workspaceId}" because it is the default workspace. Change workspaces.default first.`);
+  }
+  delete rawItems[workspaceId];
+  rawWorkspaces.items = rawItems;
+  rawManifest.workspaces = rawWorkspaces;
+  await writeFile9(path23.join(loaded.manifestRoot, "cnos.yml"), stringifyYaml7(rawManifest), "utf8");
+  await rm5(path23.join(loaded.manifestRoot, "workspaces", workspaceId), { recursive: true, force: true });
+  if (options.json) {
+    return printJson({
+      workspace: workspaceId,
+      removedFrom: loaded.manifestRoot
+    });
+  }
+  return `removed workspace ${workspaceId}`;
+}
+async function runWorkspace(args = [], options = {}) {
+  const [action, workspaceArg] = args;
+  const baseCliArgs = [...options.cliArgs ?? []];
+  const manifestCwd = path23.resolve(options.root ?? process.cwd());
+  const packageRoot = path23.resolve(consumeOption(baseCliArgs, "--package-root") ?? options.root ?? process.cwd());
   switch (action) {
-    case "detach":
-      return runDetach(packageRoot, { ...options, cliArgs });
     case "attach":
-      return runAttach(packageRoot, { ...options, cliArgs });
+      return runAttach(packageRoot, { ...options, cliArgs: baseCliArgs });
+    case "detach":
+      return runDetach(packageRoot, { ...options, cliArgs: baseCliArgs });
+    case "enable":
+      return runEnable(manifestCwd, packageRoot, { ...options, cliArgs: baseCliArgs });
+    case "list":
+      return runList2(manifestCwd, options);
+    case "add":
+      return runAddOrScaffold("add", normalizeWorkspaceId(workspaceArg), manifestCwd, packageRoot, {
+        ...options,
+        cliArgs: baseCliArgs
+      });
+    case "scaffold":
+      return runAddOrScaffold("scaffold", normalizeWorkspaceId(workspaceArg), manifestCwd, packageRoot, {
+        ...options,
+        cliArgs: baseCliArgs
+      });
+    case "remove":
+    case "delete":
+      return runRemove(normalizeWorkspaceId(workspaceArg), manifestCwd, {
+        ...options,
+        cliArgs: baseCliArgs
+      });
     default:
       throw new Error(`Unsupported workspace action: ${action ?? "(missing)"}`);
   }
@@ -4393,8 +5037,8 @@ function resolveHelpTopic(command, args) {
   if (command === "dev" && args[0] === "env") {
     return normalizeHelpTopic([command, args[0]]);
   }
-  if (command === "workspace" && args[0] && ["attach", "detach"].includes(args[0])) {
-    return normalizeHelpTopic([command, args[0]]);
+  if (command === "workspace" && args[0] && ["attach", "detach", "add", "list", "remove", "delete", "scaffold", "enable"].includes(args[0])) {
+    return normalizeHelpTopic([command, args[0] === "delete" ? "remove" : 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]]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitsy/cnos-cli",
-  "version": "1.7.0",
+  "version": "1.8.1",
   "description": "CLI entry point and developer tooling for CNOS.",
   "type": "module",
   "main": "./dist/index.js",
@@ -36,7 +36,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@kitsy/cnos": "1.7.0"
+    "smol-toml": "^1.4.2",
+    "@kitsy/cnos": "1.8.1"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts",