@kitsy/cnos-cli 1.5.1 → 1.6.1

package/dist/index.js

@@ -17,6 +17,7 @@ var COMMAND_OPTION_KEYS_WITH_VALUE = /* @__PURE__ */ new Set([
   "--provider",
   "--passphrase",
   "--vault",
+  "--package-root",
   "--inherit",
   "--as",
   "--set",
@@ -250,94 +251,169 @@ function printJson(value) {
   return JSON.stringify(value, null, 2);
 }
 
-// src/services/envMaterialization.ts
+// src/services/projections.ts
 import { mkdir, writeFile } from "fs/promises";
 import path2 from "path";
+import { resolveBrowserData, resolveFrameworkEnv, resolveServerProjection } from "@kitsy/cnos/build";
+import { stringifyYaml } from "@kitsy/cnos/internal";
 
 // src/services/runtime.ts
 import { createCnos } from "@kitsy/cnos/configure";
 async function createRuntimeService(options = {}) {
   return createCnos({
+    ...options.cwd ? { cwd: options.cwd } : {},
     ...options.root ? { root: options.root } : {},
     ...options.workspace ? { workspace: options.workspace } : {},
     ...options.profile ? { profile: options.profile } : {},
     ...options.globalRoot ? { globalRoot: options.globalRoot } : {},
     ...options.cliArgs && options.cliArgs.length > 0 ? { cliArgs: options.cliArgs } : {},
     ...options.secretResolution ? { secretResolution: options.secretResolution } : {},
+    ...typeof options.secretRefreshTtl === "number" ? { secretRefreshTtl: options.secretRefreshTtl } : {},
     processEnv: options.processEnv ?? process.env
   });
 }
 
-// src/services/envMaterialization.ts
-function resolveEnvFromRuntime(runtime, cliArgs = []) {
-  const args = [...cliArgs];
-  const isPublic = consumeFlag(args, "--public");
-  const framework = consumeOption(args, "--framework");
-  const prefix = consumeOption(args, "--prefix");
-  return isPublic ? runtime.toPublicEnv({
-    ...framework ? { framework } : {},
-    ...prefix ? { prefix } : {}
-  }) : runtime.toEnv();
+// 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 formatEnvOutput(env) {
-  return Object.entries(env).sort(([left], [right]) => left.localeCompare(right)).map(([key, value]) => `${key}=${value}`).join("\n");
+function escapeShell(value) {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
 }
-async function resolveMaterializedEnv(options = {}) {
-  const runtime = await createRuntimeService({
-    ...options,
-    cliArgs: [...options.cliArgs ?? []]
-  });
-  const env = resolveEnvFromRuntime(runtime, options.cliArgs ?? []);
-  return {
-    runtime,
-    env,
-    output: formatEnvOutput(env)
-  };
+function quoteToml(value) {
+  return `"${escapeShell(value)}"`;
 }
-function resolveMaterializedEnvTarget(to, root = process.cwd()) {
-  return path2.resolve(root, to);
+function formatKeyValueMap(values, format) {
+  const entries = Object.entries(values).sort(([left], [right]) => left.localeCompare(right));
+  switch (format) {
+    case "json":
+      return `${JSON.stringify(Object.fromEntries(entries), null, 2)}
+`;
+    case "yaml":
+      return stringifyYaml(Object.fromEntries(entries));
+    case "shell":
+      return entries.map(([key, value]) => `export ${key}="${escapeShell(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}=${stringifyScalar(value)}`).join("\n");
+  }
 }
-async function writeMaterializedEnvFile(to, output, root = process.cwd()) {
-  const targetPath = resolveMaterializedEnvTarget(to, root);
+async function writeProjectionFile(to, output, root = process.cwd()) {
+  const targetPath = path2.resolve(root, to);
   await mkdir(path2.dirname(targetPath), { recursive: true });
   await writeFile(targetPath, output, "utf8");
   return targetPath;
 }
-async function materializeEnvToFile(to, options = {}) {
-  const result = await resolveMaterializedEnv(options);
-  const targetPath = await writeMaterializedEnvFile(to, result.output, options.root ?? process.cwd());
-  return {
-    ...result,
-    targetPath
-  };
+async function buildServerProjectionArtifact(to, options = {}, format = "json") {
+  const projection = await resolveServerProjection(options);
+  const output = format === "yaml" ? stringifyYaml(projection) : `${JSON.stringify(projection, null, 2)}
+`;
+  const targetPath = await writeProjectionFile(to, output, options.root ?? process.cwd());
+  return { targetPath, output };
+}
+async function buildBrowserProjectionArtifact(to, options = {}, format = "json") {
+  const projection = await resolveBrowserData(options);
+  const output = format === "yaml" ? stringifyYaml(projection) : `${JSON.stringify(projection, null, 2)}
+`;
+  const targetPath = await writeProjectionFile(to, output, options.root ?? process.cwd());
+  return { targetPath, output };
+}
+async function buildPublicProjectionArtifact(to, options = {}, format = "dotenv") {
+  const cliArgs = [...options.cliArgs ?? []];
+  const frameworkIndex = cliArgs.indexOf("--framework");
+  const framework = frameworkIndex >= 0 && cliArgs[frameworkIndex + 1] ? cliArgs[frameworkIndex + 1] : "generic";
+  const env = await resolveFrameworkEnv(options, framework);
+  const output = formatKeyValueMap(env, format);
+  const targetPath = await writeProjectionFile(to, output, options.root ?? process.cwd());
+  return { targetPath, output, env };
+}
+async function buildEnvProjectionArtifact(to, options = {}, format = "dotenv") {
+  const runtime = await createRuntimeService({
+    ...options,
+    cliArgs: [...options.cliArgs ?? []]
+  });
+  const env = runtime.toEnv();
+  for (const [envVar, logicalKey] of Object.entries(runtime.manifest.envMapping.explicit)) {
+    const entry = runtime.graph.entries.get(logicalKey);
+    if (entry?.namespace === "secret" && !(envVar in env)) {
+      env[envVar] = "****";
+    }
+  }
+  const output = formatKeyValueMap(env, format);
+  const targetPath = await writeProjectionFile(to, output, options.root ?? process.cwd());
+  return { targetPath, output, env };
 }
 
 // src/commands/build.ts
 async function runBuild(subcommand, options = {}) {
-  if (subcommand !== "env") {
-    throw new Error(`Unsupported build target: ${subcommand ?? "(missing)"}`);
-  }
   const infoArgs = [...options.cliArgs ?? []];
+  const format = consumeOption(infoArgs, "--format") ?? void 0;
   const isPublic = consumeFlag(infoArgs, "--public");
   const framework = consumeOption(infoArgs, "--framework");
   consumeOption(infoArgs, "--prefix");
   const to = consumeOption(infoArgs, "--to");
+  const provenanceTarget = consumeOption(infoArgs, "--with-provenance");
   if (!to) {
-    throw new Error("build env requires --to <path>");
+    throw new Error(`build ${subcommand ?? "(missing)"} requires --to <path>`);
+  }
+  let targetPath;
+  let count = 0;
+  switch (subcommand) {
+    case "env": {
+      const result = await buildEnvProjectionArtifact(to, {
+        ...options,
+        cliArgs: [...options.cliArgs ?? []]
+      }, format ?? "dotenv");
+      targetPath = result.targetPath;
+      count = Object.keys(result.env).length;
+      break;
+    }
+    case "public": {
+      const result = await buildPublicProjectionArtifact(to, {
+        ...options,
+        cliArgs: [...options.cliArgs ?? []]
+      }, format ?? "dotenv");
+      targetPath = result.targetPath;
+      count = Object.keys(result.env).length;
+      break;
+    }
+    case "server": {
+      const result = await buildServerProjectionArtifact(to, options, format ?? "json");
+      targetPath = result.targetPath;
+      count = 1;
+      break;
+    }
+    case "browser": {
+      const result = await buildBrowserProjectionArtifact(to, options, format ?? "json");
+      targetPath = result.targetPath;
+      count = 1;
+      break;
+    }
+    default:
+      throw new Error(`Unsupported build target: ${subcommand ?? "(missing)"}`);
   }
-  const result = await materializeEnvToFile(to, {
-    ...options,
-    cliArgs: [...options.cliArgs ?? []]
-  });
   if (options.json) {
     return printJson({
-      to: result.targetPath,
-      count: Object.keys(result.env).length,
+      to: targetPath,
+      count,
       public: isPublic,
-      ...framework ? { framework } : {}
+      ...framework ? { framework } : {},
+      ...provenanceTarget ? { provenance: provenanceTarget } : {}
     });
   }
-  return `built env artifact at ${displayPath(result.targetPath, options.root ?? process.cwd())}`;
+  return `built ${subcommand} artifact at ${displayPath(targetPath, options.root ?? process.cwd())}`;
 }
 
 // src/commands/define.ts
@@ -352,7 +428,7 @@ import {
   parseYaml,
   resolveConfigDocumentPath,
   resolveVaultAuth,
-  stringifyYaml
+  stringifyYaml as stringifyYaml2
 } from "@kitsy/cnos/internal";
 function setNestedValue(target, pathSegments, value) {
   const [head, ...tail] = pathSegments;
@@ -454,7 +530,7 @@ async function defineValue(namespace, configPath, rawValue, options = {}) {
   const parsedValue = parseScalarValue(rawValue);
   setNestedValue(document, configPath.split("."), parsedValue);
   await mkdir2(path3.dirname(filePath), { recursive: true });
-  await writeFile2(filePath, stringifyYaml(document), "utf8");
+  await writeFile2(filePath, stringifyYaml2(document), "utf8");
   return {
     filePath,
     value: parsedValue
@@ -492,7 +568,7 @@ async function setSecret(configPath, rawValue, options = {}) {
   }
   setNestedValue(document, configPath.split("."), reference);
   await mkdir2(path3.dirname(filePath), { recursive: true });
-  await writeFile2(filePath, stringifyYaml(document), "utf8");
+  await writeFile2(filePath, stringifyYaml2(document), "utf8");
   return {
     filePath,
     provider: reference.provider,
@@ -514,7 +590,7 @@ async function deleteSecret(configPath, options = {}) {
       deleted: false
     };
   }
-  await writeFile2(filePath, stringifyYaml(document), "utf8");
+  await writeFile2(filePath, stringifyYaml2(document), "utf8");
   const secretRef = metadata?.secretRef;
   if (isSecretReference(secretRef) && secretRef.provider === "local") {
     const definition = runtime.manifest.vaults[secretRef.vault ?? "default"];
@@ -559,7 +635,7 @@ async function deleteValue(namespace, configPath, options = {}) {
       deleted: false
     };
   }
-  await writeFile2(filePath, stringifyYaml(document), "utf8");
+  await writeFile2(filePath, stringifyYaml2(document), "utf8");
   return {
     filePath,
     deleted: true
@@ -598,6 +674,52 @@ async function runDefine(namespace, configPath, rawValue, options = {}) {
   return `defined ${namespace}.${configPath} in ${displayPath(result.filePath, root)}`;
 }
 
+// src/services/envMaterialization.ts
+import { mkdir as mkdir3, writeFile as writeFile3 } from "fs/promises";
+import path5 from "path";
+function resolveEnvFromRuntime(runtime, cliArgs = []) {
+  const args = [...cliArgs];
+  const isPublic = consumeFlag(args, "--public");
+  const framework = consumeOption(args, "--framework");
+  const prefix = consumeOption(args, "--prefix");
+  return isPublic ? runtime.toPublicEnv({
+    ...framework ? { framework } : {},
+    ...prefix ? { prefix } : {}
+  }) : runtime.toEnv();
+}
+function formatEnvOutput(env) {
+  return Object.entries(env).sort(([left], [right]) => left.localeCompare(right)).map(([key, value]) => `${key}=${value}`).join("\n");
+}
+async function resolveMaterializedEnv(options = {}) {
+  const runtime = await createRuntimeService({
+    ...options,
+    cliArgs: [...options.cliArgs ?? []]
+  });
+  const env = resolveEnvFromRuntime(runtime, options.cliArgs ?? []);
+  return {
+    runtime,
+    env,
+    output: formatEnvOutput(env)
+  };
+}
+function resolveMaterializedEnvTarget(to, root = process.cwd()) {
+  return path5.resolve(root, to);
+}
+async function writeMaterializedEnvFile(to, output, root = process.cwd()) {
+  const targetPath = resolveMaterializedEnvTarget(to, root);
+  await mkdir3(path5.dirname(targetPath), { recursive: true });
+  await writeFile3(targetPath, output, "utf8");
+  return targetPath;
+}
+async function materializeEnvToFile(to, options = {}) {
+  const result = await resolveMaterializedEnv(options);
+  const targetPath = await writeMaterializedEnvFile(to, result.output, options.root ?? process.cwd());
+  return {
+    ...result,
+    targetPath
+  };
+}
+
 // src/services/spawn.ts
 import { spawn } from "child_process";
 function shouldUseShellForCommand(command) {
@@ -835,7 +957,7 @@ async function runDiff(leftProfile, rightProfile, options = {}) {
 
 // src/services/doctor.ts
 import { readdir, readFile as readFile2 } from "fs/promises";
-import path5 from "path";
+import path6 from "path";
 import {
   detectLegacyVaultFormat,
   isSecretReference as isSecretReference2,
@@ -857,7 +979,7 @@ async function createValidationSummary(options = {}) {
 
 // src/services/doctor.ts
 async function checkGitignore(root) {
-  const gitignorePath = path5.join(root, ".gitignore");
+  const gitignorePath = path6.join(root, ".gitignore");
   const expected = [
     ".cnos/env/.env",
     ".cnos/env/.env.*",
@@ -892,12 +1014,12 @@ async function collectYamlFiles(root) {
     const entries = await readdir(root, { withFileTypes: true });
     const results = [];
     for (const entry of entries) {
-      const target = path5.join(root, entry.name);
+      const target = path6.join(root, entry.name);
       if (entry.isDirectory()) {
         results.push(...await collectYamlFiles(target));
         continue;
       }
-      if (entry.isFile() && [".yml", ".yaml"].includes(path5.extname(entry.name).toLowerCase())) {
+      if (entry.isFile() && [".yml", ".yaml"].includes(path6.extname(entry.name).toLowerCase())) {
         results.push(target);
       }
     }
@@ -922,7 +1044,7 @@ async function checkSecretSecurity(options, runtime) {
   );
   const legacyDetected = legacyPaths.filter((entry) => Boolean(entry.path));
   const secretFiles = await Promise.all(
-    runtime.graph.workspace.workspaceRoots.filter((root) => root.scope === "local").map((root) => collectYamlFiles(path5.join(root.path, "secrets")))
+    runtime.graph.workspace.workspaceRoots.filter((root) => root.scope === "local").map((root) => collectYamlFiles(path6.join(root.path, "secrets")))
   );
   const plaintextFiles = [];
   for (const file of secretFiles.flat()) {
@@ -952,7 +1074,7 @@ async function checkSecretSecurity(options, runtime) {
   };
 }
 async function evaluateDoctor(options = {}) {
-  const root = path5.resolve(options.root ?? process.cwd());
+  const root = path6.resolve(options.root ?? process.cwd());
   const { runtime, summary } = await createValidationSummary(options);
   const localRoot = runtime.graph.workspace.workspaceRoots.find((entry) => entry.scope === "local");
   const globalRoot = runtime.graph.workspace.workspaceRoots.find((entry) => entry.scope === "global");
@@ -1145,7 +1267,7 @@ 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, optional .cnos-workspace.yml, config folders, and .gitignore entries without overwriting existing files.",
+    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"]
   },
   {
@@ -1563,23 +1685,39 @@ var COMMANDS = [
     id: "build",
     summary: "Build derived configuration artifacts from CNOS.",
     usage: "cnos build <subcommand> [options] [global-options]",
-    description: "Builds deterministic derived outputs from the selected workspace. Currently supports env artifact generation.",
+    description: "Builds deterministic derived outputs from the selected workspace, including server projections, browser projections, env files, and framework-prefixed public env.",
     arguments: [
       {
         name: "subcommand",
-        description: "Supported value: env.",
+        description: "Supported values: server, browser, env, public.",
         required: true
       }
     ],
     examples: [
+      "cnos build server --to .cnos-server.json",
+      "cnos build browser --to .cnos-browser.json",
       "cnos build env --profile local --to .env.local",
-      "cnos build env --public --framework vite --profile prod --to .env.production"
+      "cnos build public --framework vite --profile prod --to .env.production"
     ]
   },
+  {
+    id: "build server",
+    summary: "Build a server runtime projection artifact.",
+    usage: "cnos build server --to <path> [--format <json|yaml>] [global-options]",
+    description: "Builds a flat server projection for runtime auto-loading. Non-secret values are embedded, while secret refs remain refs and hydrate at runtime.",
+    examples: ["cnos build server --to .cnos-server.json", "cnos build server --profile prod --to dist/.cnos-server.json"]
+  },
+  {
+    id: "build browser",
+    summary: "Build a browser projection artifact.",
+    usage: "cnos build browser --to <path> [--format <json|yaml>] [global-options]",
+    description: "Builds a public-only browser projection for tooling and offline packaging flows. secret.* keys are excluded entirely.",
+    examples: ["cnos build browser --to .cnos-browser.json"]
+  },
   {
     id: "build env",
     summary: "Build a flat env-file artifact from CNOS.",
-    usage: "cnos build env --to <path> [--public] [--framework <name>] [--prefix <prefix>] [global-options]",
+    usage: "cnos build env --to <path> [--format <dotenv|docker-env|json|shell|toml|yaml>] [global-options]",
     description: "Builds a deterministic KEY=VALUE artifact for legacy build and runtime workflows. The target file is derived output, not the CNOS source of truth.",
     options: [
       {
@@ -1587,24 +1725,23 @@ var COMMANDS = [
         description: "Write the rendered KEY=VALUE output to a file. Required."
       },
       {
-        flag: "--public",
-        description: "Build only public values based on manifest promotion rules."
-      },
-      {
-        flag: "--framework <name>",
-        description: "Apply framework-specific public env conventions such as vite or next."
-      },
-      {
-        flag: "--prefix <prefix>",
-        description: "Override the generated public env prefix."
+        flag: "--format <dotenv|docker-env|json|shell|toml|yaml>",
+        description: "Select the output format. Defaults to dotenv."
       }
     ],
     examples: [
       "cnos build env --profile local --to .env.local",
       "cnos build env --profile stage --to .env.stage",
-      "cnos build env --public --framework vite --to .env.local"
+      "cnos build env --profile prod --format yaml --to env.yaml"
     ]
   },
+  {
+    id: "build public",
+    summary: "Build a public env artifact with optional framework prefixing.",
+    usage: "cnos build public --to <path> [--framework <name>] [--format <dotenv|docker-env|json|shell|toml|yaml>] [global-options]",
+    description: "Builds env-style public artifacts from promoted keys only, with framework-specific prefixes such as vite or next when requested.",
+    examples: ["cnos build public --framework vite --to .env.vite", "cnos build public --framework next --format json --to public.json"]
+  },
   {
     id: "export env",
     summary: "Render environment variables for the selected workspace.",
@@ -1735,6 +1872,27 @@ var COMMANDS = [
       "cnos run --public --framework vite -- pnpm build"
     ]
   },
+  {
+    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"]
+  },
+  {
+    id: "workspace detach",
+    summary: "Detach a package workspace into a standalone .cnos root.",
+    usage: "cnos workspace detach [--package-root <path>] [--force] [global-options]",
+    description: "Materializes the effective local workspace chain into a package-local .cnos directory, rewrites .cnosrc.yml to root: ./.cnos, and records the original parent binding in .cnos/.detached.",
+    examples: ["cnos workspace detach", "cnos workspace detach --package-root apps/travel --force"]
+  },
+  {
+    id: "workspace attach",
+    summary: "Attach a detached package back to its original parent CNOS root.",
+    usage: "cnos workspace attach [--package-root <path>] [--force] [global-options]",
+    description: "Imports a detached package-local .cnos directory back into the original parent workspace, archives the detached snapshot, and restores .cnosrc.yml to the parent root/workspace binding.",
+    examples: ["cnos workspace attach", "cnos workspace attach --package-root apps/travel --force"]
+  },
   {
     id: "diff",
     summary: "Diff two profiles for the same workspace.",
@@ -2007,11 +2165,11 @@ function runHelpAi(topic, cliArgs = []) {
 }
 
 // src/commands/init.ts
-import path7 from "path";
+import path8 from "path";
 
 // src/services/scaffold.ts
-import { mkdir as mkdir3, readFile as readFile3, writeFile as writeFile3 } from "fs/promises";
-import path6 from "path";
+import { mkdir as mkdir4, readFile as readFile3, writeFile as writeFile4 } from "fs/promises";
+import path7 from "path";
 function scaffoldManifest(projectName, workspace) {
   const lines = [
     "version: 1",
@@ -2045,12 +2203,12 @@ async function ensureFile(filePath, content) {
     await readFile3(filePath, "utf8");
     return false;
   } catch {
-    await writeFile3(filePath, content, "utf8");
+    await writeFile4(filePath, content, "utf8");
     return true;
   }
 }
 async function ensureGitignore(root) {
-  const gitignorePath = path6.join(root, ".gitignore");
+  const gitignorePath = path7.join(root, ".gitignore");
   const requiredEntries = [
     ".cnos/env/.env",
     ".cnos/env/.env.*",
@@ -2073,18 +2231,18 @@ async function ensureGitignore(root) {
   }
   const prefix = current.trim().length > 0 ? `${current.trimEnd()}
 ` : "";
-  await writeFile3(gitignorePath, `${prefix}${missingEntries.join("\n")}
+  await writeFile4(gitignorePath, `${prefix}${missingEntries.join("\n")}
 `, "utf8");
   return true;
 }
 async function scaffoldWorkspace(root, workspace) {
-  const cnosRoot = path6.join(root, ".cnos");
-  const workspaceRoot = workspace ? path6.join(cnosRoot, "workspaces", workspace) : cnosRoot;
+  const cnosRoot = path7.join(root, ".cnos");
+  const workspaceRoot = workspace ? path7.join(cnosRoot, "workspaces", workspace) : cnosRoot;
   const createdPaths = [];
-  await mkdir3(path6.join(workspaceRoot, "profiles"), { recursive: true });
-  await mkdir3(path6.join(workspaceRoot, "values"), { recursive: true });
-  await mkdir3(path6.join(workspaceRoot, "secrets"), { recursive: true });
-  await mkdir3(path6.join(workspaceRoot, "env"), { recursive: true });
+  await mkdir4(path7.join(workspaceRoot, "profiles"), { recursive: true });
+  await mkdir4(path7.join(workspaceRoot, "values"), { recursive: true });
+  await mkdir4(path7.join(workspaceRoot, "secrets"), { recursive: true });
+  await mkdir4(path7.join(workspaceRoot, "env"), { recursive: true });
   const relativePaths = workspace ? [
     ["workspaces", workspace, "profiles", ".gitkeep"],
     ["workspaces", workspace, "values", ".gitkeep"],
@@ -2097,15 +2255,23 @@ async function scaffoldWorkspace(root, workspace) {
     ["env", ".gitkeep"]
   ];
   for (const relativePath of relativePaths) {
-    const filePath = path6.join(cnosRoot, ...relativePath);
+    const filePath = path7.join(cnosRoot, ...relativePath);
     if (await ensureFile(filePath, "")) {
-      createdPaths.push(path6.relative(root, filePath).replace(/\\/g, "/"));
+      createdPaths.push(path7.relative(root, filePath).replace(/\\/g, "/"));
     }
   }
-  if (await ensureFile(path6.join(cnosRoot, "cnos.yml"), scaffoldManifest(path6.basename(root), workspace))) {
+  if (await ensureFile(path7.join(cnosRoot, "cnos.yml"), scaffoldManifest(path7.basename(root), workspace))) {
     createdPaths.push(".cnos/cnos.yml");
   }
-  if (workspace && await ensureFile(path6.join(root, ".cnos-workspace.yml"), `workspace: ${workspace}
+  if (await ensureFile(
+    path7.join(root, ".cnosrc.yml"),
+    workspace ? `root: ./.cnos
+workspace: ${workspace}
+` : "root: ./.cnos\n"
+  )) {
+    createdPaths.push(".cnosrc.yml");
+  }
+  if (workspace && await ensureFile(path7.join(root, ".cnos-workspace.yml"), `workspace: ${workspace}
 globalRoot: ~/.cnos
 `)) {
     createdPaths.push(".cnos-workspace.yml");
@@ -2122,7 +2288,7 @@ globalRoot: ~/.cnos
 
 // src/commands/init.ts
 async function runInit(options = {}) {
-  const root = path7.resolve(options.root ?? process.cwd());
+  const root = path8.resolve(options.root ?? process.cwd());
   const result = await scaffoldWorkspace(root, options.workspace);
   if (options.json) {
     return printJson(result);
@@ -2317,7 +2483,7 @@ async function runList(args = [], options = {}) {
 }
 
 // src/commands/migrate.ts
-import path8 from "path";
+import path9 from "path";
 import {
   applyManifestMappings,
   loadManifest,
@@ -2335,7 +2501,7 @@ async function runMigrate(options = {}) {
     throw new Error(`Unknown migrate options: ${cliArgs.join(" ")}`);
   }
   const manifest = await loadManifest(options.root ? { root: options.root } : {});
-  const scanRoot = path8.resolve(manifest.repoRoot, scan ?? "src");
+  const scanRoot = path9.resolve(manifest.repoRoot, scan ?? "src");
   const usages = await scanEnvUsage(scanRoot);
   const uniqueProposals = new Map(usages.map((usage) => [usage.envVar, proposeMapping(usage.envVar)]));
   const proposals = Array.from(uniqueProposals.values()).sort((left, right) => left.envVar.localeCompare(right.envVar));
@@ -2397,7 +2563,7 @@ async function runMigrate(options = {}) {
 }
 
 // src/commands/namespace.ts
-import path9 from "path";
+import path10 from "path";
 function normalizeCommand2(args) {
   const [actionOrPath, ...tail] = args;
   if (!actionOrPath) {
@@ -2420,7 +2586,7 @@ function normalizeCommand2(args) {
 async function runNamespace(namespace, args = [], options = {}) {
   const { action, tail } = normalizeCommand2(args);
   const cliArgs = [...options.cliArgs ?? []];
-  const root = path9.resolve(options.root ?? process.cwd());
+  const root = path10.resolve(options.root ?? process.cwd());
   if (action === "list") {
     const prefix = consumeOption(cliArgs, "--prefix");
     const entries = await listConfigEntries(namespace, {
@@ -2483,31 +2649,31 @@ async function runNamespace(namespace, args = [], options = {}) {
 
 // src/commands/onboard.ts
 import { copyFile, readdir as readdir2, rm } from "fs/promises";
-import path10 from "path";
+import path11 from "path";
 var ROOT_ENV_FILE_PATTERN = /^\.env(?:\.[A-Za-z0-9_-]+)*(?:\.example)?$/;
 async function listRootEnvFiles(root) {
   const entries = await readdir2(root, { withFileTypes: true });
   return entries.filter((entry) => entry.isFile() && ROOT_ENV_FILE_PATTERN.test(entry.name)).map((entry) => entry.name).sort((left, right) => left.localeCompare(right));
 }
 async function runOnboard(options = {}) {
-  const root = path10.resolve(options.root ?? process.cwd());
-  const workspace = options.workspace ?? path10.basename(root);
+  const root = path11.resolve(options.root ?? process.cwd());
+  const workspace = options.workspace ?? path11.basename(root);
   const cliArgs = [...options.cliArgs ?? []];
   const move = consumeFlag(cliArgs, "--move");
   if (cliArgs.length > 0) {
     throw new Error(`Unsupported onboard arguments: ${cliArgs.join(" ")}`);
   }
   const scaffold = await scaffoldWorkspace(root, workspace);
-  const envRoot = path10.join(root, ".cnos", "workspaces", workspace, "env");
+  const envRoot = path11.join(root, ".cnos", "workspaces", workspace, "env");
   const rootFiles = await listRootEnvFiles(root);
   const imported = [];
   const skipped = [];
   for (const fileName of rootFiles) {
-    const sourcePath = path10.join(root, fileName);
-    const targetPath = path10.join(envRoot, fileName);
+    const sourcePath = path11.join(root, fileName);
+    const targetPath = path11.join(envRoot, fileName);
     try {
       await copyFile(sourcePath, targetPath);
-      imported.push(path10.relative(root, targetPath).replace(/\\/g, "/"));
+      imported.push(path11.relative(root, targetPath).replace(/\\/g, "/"));
       if (move) {
         await rm(sourcePath);
       }
@@ -2532,14 +2698,14 @@ async function runOnboard(options = {}) {
 }
 
 // src/commands/profile.ts
-import path13 from "path";
+import path14 from "path";
 
 // src/services/context.ts
-import { readFile as readFile4, writeFile as writeFile4 } from "fs/promises";
-import path11 from "path";
-import { parseYaml as parseYaml3, stringifyYaml as stringifyYaml2 } from "@kitsy/cnos/internal";
+import { readFile as readFile4, writeFile as writeFile5 } from "fs/promises";
+import path12 from "path";
+import { parseYaml as parseYaml3, stringifyYaml as stringifyYaml3 } from "@kitsy/cnos/internal";
 async function loadCliContext(root = process.cwd()) {
-  const filePath = path11.join(path11.resolve(root), ".cnos-workspace.yml");
+  const filePath = path12.join(path12.resolve(root), ".cnos-workspace.yml");
   try {
     const source = await readFile4(filePath, "utf8");
     const parsed = parseYaml3(source);
@@ -2552,8 +2718,8 @@ async function loadCliContext(root = process.cwd()) {
   }
 }
 async function saveCliContext(options = {}) {
-  const root = path11.resolve(options.root ?? process.cwd());
-  const filePath = path11.join(root, ".cnos-workspace.yml");
+  const root = path12.resolve(options.root ?? process.cwd());
+  const filePath = path12.join(root, ".cnos-workspace.yml");
   const current = await loadCliContext(root);
   const next = {
     ...current.workspace ? { workspace: current.workspace } : {},
@@ -2563,7 +2729,7 @@ async function saveCliContext(options = {}) {
     ...options.profile ? { profile: options.profile } : {},
     ...options.globalRoot ? { globalRoot: options.globalRoot } : {}
   };
-  await writeFile4(filePath, stringifyYaml2(next), "utf8");
+  await writeFile5(filePath, stringifyYaml3(next), "utf8");
   return {
     filePath,
     context: next
@@ -2571,12 +2737,12 @@ async function saveCliContext(options = {}) {
 }
 
 // src/services/profiles.ts
-import { mkdir as mkdir4, readdir as readdir3, readFile as readFile5, rm as rm2, writeFile as writeFile5 } from "fs/promises";
-import path12 from "path";
-import { parseYaml as parseYaml4, stringifyYaml as stringifyYaml3 } from "@kitsy/cnos/internal";
+import { mkdir as mkdir5, readdir as readdir3, readFile as readFile5, rm as rm2, writeFile as writeFile6 } from "fs/promises";
+import path13 from "path";
+import { parseYaml as parseYaml4, stringifyYaml as stringifyYaml4 } from "@kitsy/cnos/internal";
 async function createProfileDefinition(root = process.cwd(), profile, inherit, options = {}) {
-  const filePath = path12.join(path12.resolve(root), ".cnos", "profiles", `${profile}.yml`);
-  await mkdir4(path12.dirname(filePath), { recursive: true });
+  const filePath = path13.join(path13.resolve(root), ".cnos", "profiles", `${profile}.yml`);
+  await mkdir5(path13.dirname(filePath), { recursive: true });
   const document = options.noInherit ? {
     name: profile,
     activate: {
@@ -2590,7 +2756,7 @@ async function createProfileDefinition(root = process.cwd(), profile, inherit, o
   } : {
     name: profile
   };
-  await writeFile5(filePath, stringifyYaml3(document), "utf8");
+  await writeFile6(filePath, stringifyYaml4(document), "utf8");
   return {
     filePath,
     profile,
@@ -2599,7 +2765,7 @@ async function createProfileDefinition(root = process.cwd(), profile, inherit, o
   };
 }
 async function listProfiles(root = process.cwd()) {
-  const profilesRoot = path12.join(path12.resolve(root), ".cnos", "profiles");
+  const profilesRoot = path13.join(path13.resolve(root), ".cnos", "profiles");
   try {
     const entries = await readdir3(profilesRoot, { withFileTypes: true });
     const discovered = /* @__PURE__ */ new Set(["base"]);
@@ -2614,7 +2780,7 @@ async function listProfiles(root = process.cwd()) {
   }
 }
 async function deleteProfileDefinition(root = process.cwd(), profile) {
-  const filePath = path12.join(path12.resolve(root), ".cnos", "profiles", `${profile}.yml`);
+  const filePath = path13.join(path13.resolve(root), ".cnos", "profiles", `${profile}.yml`);
   try {
     await rm2(filePath);
     return {
@@ -2634,7 +2800,7 @@ async function readProfileDefinition(root = process.cwd(), profile = "base") {
       name: "base"
     };
   }
-  const filePath = path12.join(path12.resolve(root), ".cnos", "profiles", `${profile}.yml`);
+  const filePath = path13.join(path13.resolve(root), ".cnos", "profiles", `${profile}.yml`);
   try {
     return parseYaml4(await readFile5(filePath, "utf8")) ?? void 0;
   } catch {
@@ -2658,7 +2824,7 @@ function normalizeProfileAction(args) {
 }
 async function runProfile(args, options = {}) {
   const { action, tail } = normalizeProfileAction(args);
-  const root = path13.resolve(options.root ?? process.cwd());
+  const root = path14.resolve(options.root ?? process.cwd());
   const cliArgs = [...options.cliArgs ?? []];
   if (action === "create") {
     const profile = tail[0] ?? "stage";
@@ -2709,12 +2875,12 @@ async function runProfile(args, options = {}) {
 }
 
 // src/commands/promote.ts
-import path14 from "path";
-import { writeFile as writeFile6 } from "fs/promises";
+import path15 from "path";
+import { writeFile as writeFile7 } from "fs/promises";
 import {
   ensureProjectionAllowed,
   loadManifest as loadManifest2,
-  stringifyYaml as stringifyYaml4
+  stringifyYaml as stringifyYaml5
 } from "@kitsy/cnos/internal";
 function normalizeTarget(value) {
   if (value === "public" || value === "env") {
@@ -2726,7 +2892,7 @@ function sortRecord(record) {
   return Object.fromEntries(Object.entries(record).sort(([left], [right]) => left.localeCompare(right)));
 }
 async function runPromote(args = [], options = {}) {
-  const root = path14.resolve(options.root ?? process.cwd());
+  const root = path15.resolve(options.root ?? process.cwd());
   const cliArgs = [...options.cliArgs ?? []];
   const target = normalizeTarget(consumeOption(cliArgs, "--to"));
   const alias = consumeOption(cliArgs, "--as");
@@ -2765,7 +2931,7 @@ async function runPromote(args = [], options = {}) {
       })
     };
   }
-  await writeFile6(loadedManifest.manifestPath, stringifyYaml4(rawManifest), "utf8");
+  await writeFile7(loadedManifest.manifestPath, stringifyYaml5(rawManifest), "utf8");
   if (options.json) {
     return printJson({
       target,
@@ -2797,9 +2963,8 @@ async function runRead(key, options = {}) {
 // src/commands/run.ts
 import {
   CNOS_GRAPH_ENV_VAR,
-  CNOS_SECRET_PAYLOAD_ENV_VAR,
-  CNOS_SESSION_KEY_ENV_VAR,
-  serializeSecretPayload,
+  CNOS_PROJECTION_ENV_VAR,
+  serializeServerProjection,
   serializeRuntimeGraph
 } from "@kitsy/cnos/internal";
 function consumeOptions(args, flag) {
@@ -2838,7 +3003,7 @@ async function runCommand(command, options = {}) {
   }
   const cliArgs = [...options.cliArgs ?? []];
   const isPublic = consumeFlag(cliArgs, "--public");
-  const isAuthenticated = consumeFlag(cliArgs, "--auth");
+  consumeFlag(cliArgs, "--auth");
   const framework = consumeOption(cliArgs, "--framework");
   const prefix = consumeOption(cliArgs, "--prefix");
   const setOverrides = normalizeSetOverrides(consumeOptions(cliArgs, "--set"));
@@ -2846,21 +3011,14 @@ async function runCommand(command, options = {}) {
     ...options,
     cliArgs: [...cliArgs, ...setOverrides]
   });
-  const authenticatedSecrets = isAuthenticated ? Object.fromEntries(
-    Array.from(runtime.graph.entries.values()).filter((entry) => entry.namespace === "secret").map((entry) => [entry.key, runtime.read(entry.key)])
-  ) : void 0;
-  const secretPayload = authenticatedSecrets ? serializeSecretPayload(authenticatedSecrets) : void 0;
   const env = {
     ...process.env,
     ...isPublic ? runtime.toPublicEnv({
       ...framework ? { framework } : {},
       ...prefix ? { prefix } : {}
     }) : runtime.toEnv(),
-    [CNOS_GRAPH_ENV_VAR]: serializeRuntimeGraph(runtime.graph),
-    ...secretPayload ? {
-      [CNOS_SECRET_PAYLOAD_ENV_VAR]: secretPayload.payload,
-      [CNOS_SESSION_KEY_ENV_VAR]: secretPayload.sessionKey
-    } : {}
+    [CNOS_PROJECTION_ENV_VAR]: serializeServerProjection(runtime.toServerProjection()),
+    [CNOS_GRAPH_ENV_VAR]: serializeRuntimeGraph(runtime.graph)
   };
   return new Promise((resolve, reject) => {
     const executable = command[0];
@@ -2895,14 +3053,14 @@ async function runCommand(command, options = {}) {
 }
 
 // src/commands/secret.ts
-import path17 from "path";
+import path18 from "path";
 
 // src/commands/vault.ts
-import path16 from "path";
+import path17 from "path";
 
 // src/services/vaults.ts
-import { rm as rm3, writeFile as writeFile7 } from "fs/promises";
-import path15 from "path";
+import { rm as rm3, writeFile as writeFile8 } from "fs/promises";
+import path16 from "path";
 import {
   clearAllVaultSessionKeys,
   clearVaultSessionKey,
@@ -2915,7 +3073,7 @@ import {
   resolveSecretStoreRoot as resolveSecretStoreRoot2,
   resolveVaultAuth as resolveVaultAuth2,
   resolveVaultDefinition,
-  stringifyYaml as stringifyYaml5,
+  stringifyYaml as stringifyYaml6,
   writeKeychain,
   writeVaultSessionKey
 } from "@kitsy/cnos/internal";
@@ -2956,7 +3114,7 @@ async function createVaultDefinition(name, options = {}) {
       [vault]: vaultDefinition
     }
   };
-  await writeFile7(loadedManifest.manifestPath, stringifyYaml5(rawManifest), "utf8");
+  await writeFile8(loadedManifest.manifestPath, stringifyYaml6(rawManifest), "utf8");
   const definition = resolveVaultDefinition({ [vault]: vaultDefinition }, vault);
   if (provider === "local") {
     const auth = await resolveVaultAuth2(vault, vaultDefinition, options.processEnv ?? process.env);
@@ -3007,8 +3165,8 @@ async function removeVaultDefinition(name, options = {}) {
   if (Object.keys(nextVaults).length === 0) {
     delete rawManifest.vaults;
   }
-  await writeFile7(loadedManifest.manifestPath, stringifyYaml5(rawManifest), "utf8");
-  const vaultRoot = path15.join(resolveSecretStoreRoot2(options.processEnv), "vaults", vault);
+  await writeFile8(loadedManifest.manifestPath, stringifyYaml6(rawManifest), "utf8");
+  const vaultRoot = path16.join(resolveSecretStoreRoot2(options.processEnv), "vaults", vault);
   let removedStore;
   try {
     await rm3(vaultRoot, { recursive: true, force: true });
@@ -3102,7 +3260,7 @@ function normalizeVaultAction(args) {
 async function runVault(args = [], options = {}) {
   const { action, tail } = normalizeVaultAction(args);
   const cliArgs = [...options.cliArgs ?? []];
-  const root = path16.resolve(options.root ?? process.cwd());
+  const root = path17.resolve(options.root ?? process.cwd());
   if (consumeOption(cliArgs, "--passphrase")) {
     throw new Error("The --passphrase option is not supported in CNOS 1.4. Use env, keychain, or prompt-based auth.");
   }
@@ -3208,7 +3366,7 @@ async function runSecret(argsOrPath, options = {}) {
   const args = Array.isArray(argsOrPath) ? argsOrPath : [argsOrPath];
   const { action, tail } = normalizeSecretCommand(args);
   const cliArgs = [...options.cliArgs ?? []];
-  const root = path17.resolve(options.root ?? process.cwd());
+  const root = path18.resolve(options.root ?? process.cwd());
   if (consumeOption(cliArgs, "--passphrase")) {
     throw new Error("The --passphrase option is not supported in CNOS 1.4. Use env, keychain, or prompt-based auth.");
   }
@@ -3304,9 +3462,9 @@ async function runSecret(argsOrPath, options = {}) {
 }
 
 // src/commands/use.ts
-import path18 from "path";
+import path19 from "path";
 async function runUse(args = [], options = {}) {
-  const root = path18.resolve(options.root ?? process.cwd());
+  const root = path19.resolve(options.root ?? process.cwd());
   const action = args[0];
   const hasUpdates = Boolean(options.workspace || options.profile || options.globalRoot);
   if (action === "show" || !action && !hasUpdates) {
@@ -3343,7 +3501,7 @@ async function runValidate(options = {}) {
 // package.json
 var package_default = {
   name: "@kitsy/cnos-cli",
-  version: "1.5.1",
+  version: "1.6.1",
   description: "CLI entry point and developer tooling for CNOS.",
   type: "module",
   main: "./dist/index.js",
@@ -3398,7 +3556,7 @@ function runVersion() {
 }
 
 // src/commands/value.ts
-import path19 from "path";
+import path20 from "path";
 function normalizeValueCommand(args) {
   const [actionOrPath, ...tail] = args;
   if (!actionOrPath) {
@@ -3422,7 +3580,7 @@ async function runValue(argsOrPath, options = {}) {
   const args = Array.isArray(argsOrPath) ? argsOrPath : [argsOrPath];
   const { action, tail } = normalizeValueCommand(args);
   const cliArgs = [...options.cliArgs ?? []];
-  const root = path19.resolve(options.root ?? process.cwd());
+  const root = path20.resolve(options.root ?? process.cwd());
   if (action === "list") {
     const prefix = consumeOption(cliArgs, "--prefix");
     const entries = await listConfigEntries("value", {
@@ -3485,10 +3643,10 @@ async function runValue(argsOrPath, options = {}) {
 // src/commands/watch.ts
 import {
   CNOS_GRAPH_ENV_VAR as CNOS_GRAPH_ENV_VAR2,
-  CNOS_SECRET_PAYLOAD_ENV_VAR as CNOS_SECRET_PAYLOAD_ENV_VAR2,
-  CNOS_SESSION_KEY_ENV_VAR as CNOS_SESSION_KEY_ENV_VAR2,
+  CNOS_SECRET_PAYLOAD_ENV_VAR,
+  CNOS_SESSION_KEY_ENV_VAR,
   serializeRuntimeGraph as serializeRuntimeGraph2,
-  serializeSecretPayload as serializeSecretPayload2
+  serializeSecretPayload
 } from "@kitsy/cnos/internal";
 async function buildRunEnvironment(options) {
   const cliArgs = [...options.cliArgs ?? []];
@@ -3503,7 +3661,7 @@ async function buildRunEnvironment(options) {
   const authenticatedSecrets = isAuthenticated ? Object.fromEntries(
     Array.from(runtime.graph.entries.values()).filter((entry) => entry.namespace === "secret").map((entry) => [entry.key, runtime.read(entry.key)])
   ) : void 0;
-  const secretPayload = authenticatedSecrets ? serializeSecretPayload2(authenticatedSecrets) : void 0;
+  const secretPayload = authenticatedSecrets ? serializeSecretPayload(authenticatedSecrets) : void 0;
   return {
     runtime,
     env: {
@@ -3514,8 +3672,8 @@ async function buildRunEnvironment(options) {
       }) : runtime.toEnv(),
       [CNOS_GRAPH_ENV_VAR2]: serializeRuntimeGraph2(runtime.graph),
       ...secretPayload ? {
-        [CNOS_SECRET_PAYLOAD_ENV_VAR2]: secretPayload.payload,
-        [CNOS_SESSION_KEY_ENV_VAR2]: secretPayload.sessionKey
+        [CNOS_SECRET_PAYLOAD_ENV_VAR]: secretPayload.payload,
+        [CNOS_SESSION_KEY_ENV_VAR]: secretPayload.sessionKey
       } : {}
     }
   };
@@ -3605,6 +3763,163 @@ async function runWatch(command, options = {}) {
   return isSignal ? "watching config changes in signal mode" : "watching config changes in restart mode";
 }
 
+// src/commands/workspace.ts
+import { cp, mkdir as mkdir6, rename, rm as rm4, stat, writeFile as writeFile9, readFile as readFile6 } from "fs/promises";
+import path21 from "path";
+import { loadManifest as loadManifest4, parseYaml as parseYaml5, stringifyYaml as stringifyYaml7 } from "@kitsy/cnos/internal";
+async function exists(targetPath) {
+  try {
+    await stat(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function copyIfExists(source, target) {
+  if (!await exists(source)) {
+    return;
+  }
+  await mkdir6(path21.dirname(target), { recursive: true });
+  await cp(source, target, { recursive: true, force: true });
+}
+async function mergeWorkspaceRootsIntoStandalone(targetCnosRoot, sourceRoots) {
+  for (const sourceRoot of sourceRoots) {
+    for (const folderName of ["values", "secrets", "env", "profiles"]) {
+      await copyIfExists(
+        path21.join(sourceRoot, folderName),
+        path21.join(targetCnosRoot, folderName)
+      );
+    }
+  }
+}
+async function writeCnosrc(packageRoot, config) {
+  await writeFile9(
+    path21.join(packageRoot, ".cnosrc.yml"),
+    stringifyYaml7({
+      root: config.root,
+      ...config.workspace ? { workspace: config.workspace } : {}
+    }),
+    "utf8"
+  );
+}
+function createDetachedManifest(rawManifest) {
+  const next = structuredClone(rawManifest);
+  if ("workspaces" in next) {
+    delete next.workspaces;
+  }
+  return next;
+}
+async function runDetach(packageRoot, options = {}) {
+  const loaded = await loadManifest4({ cwd: packageRoot });
+  if (!loaded.anchorPath || !loaded.anchoredWorkspace) {
+    throw new Error("workspace detach requires a package-local .cnosrc.yml with a workspace binding");
+  }
+  const targetCnosRoot = path21.join(packageRoot, ".cnos");
+  const force = consumeFlag([...options.cliArgs ?? []], "--force");
+  if (await exists(targetCnosRoot) && !force) {
+    throw new Error(`Refusing to detach because ${displayPath(targetCnosRoot, packageRoot)} already exists. Use --force to overwrite.`);
+  }
+  if (force) {
+    await rm4(targetCnosRoot, { recursive: true, force: true });
+  }
+  const runtime = await createRuntimeService({
+    ...options,
+    root: loaded.manifestRoot,
+    workspace: loaded.anchoredWorkspace
+  });
+  const localRoots = runtime.graph.workspace.workspaceRoots.filter((root) => root.scope === "local").map((root) => root.path);
+  await mkdir6(targetCnosRoot, { recursive: true });
+  await mergeWorkspaceRootsIntoStandalone(targetCnosRoot, localRoots);
+  await writeFile9(
+    path21.join(targetCnosRoot, "cnos.yml"),
+    stringifyYaml7(createDetachedManifest(loaded.rawManifest)),
+    "utf8"
+  );
+  const relativeRoot = path21.relative(packageRoot, loaded.manifestRoot).replace(/\\/g, "/");
+  const marker = {
+    detachedFrom: relativeRoot || ".",
+    detachedWorkspace: loaded.anchoredWorkspace,
+    detachedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    originalCnosrc: {
+      root: relativeRoot || ".",
+      workspace: loaded.anchoredWorkspace
+    }
+  };
+  await writeFile9(path21.join(targetCnosRoot, ".detached"), stringifyYaml7(marker), "utf8");
+  await writeCnosrc(packageRoot, { root: "./.cnos" });
+  if (options.json) {
+    return printJson({
+      packageRoot,
+      detachedWorkspace: loaded.anchoredWorkspace,
+      cnosRoot: targetCnosRoot
+    });
+  }
+  return `detached workspace ${loaded.anchoredWorkspace} into ${displayPath(targetCnosRoot, packageRoot)}`;
+}
+async function runAttach(packageRoot, options = {}) {
+  const cliArgs = [...options.cliArgs ?? []];
+  const force = consumeFlag(cliArgs, "--force");
+  const childCnosRoot = path21.join(packageRoot, ".cnos");
+  const markerPath = path21.join(childCnosRoot, ".detached");
+  if (!await exists(markerPath)) {
+    throw new Error("workspace attach requires a detached package with .cnos/.detached");
+  }
+  const marker = parseYaml5(await readFile6(markerPath, "utf8"));
+  if (!marker?.originalCnosrc?.root || !marker.detachedWorkspace) {
+    throw new Error("Invalid .detached marker");
+  }
+  const parentManifestRoot = path21.resolve(packageRoot, marker.originalCnosrc.root);
+  const parentLoaded = await loadManifest4({ root: parentManifestRoot });
+  const workspaceId = marker.originalCnosrc.workspace ?? marker.detachedWorkspace;
+  const parentWorkspaceRoot = path21.join(parentLoaded.manifestRoot, "workspaces", workspaceId);
+  if (await exists(parentWorkspaceRoot) && !force) {
+    throw new Error(`workspace "${workspaceId}" already exists in parent root. Use --force to overwrite.`);
+  }
+  if (force) {
+    await rm4(parentWorkspaceRoot, { recursive: true, force: true });
+  }
+  await mkdir6(parentWorkspaceRoot, { recursive: true });
+  for (const folderName of ["values", "secrets", "env", "profiles"]) {
+    await copyIfExists(path21.join(childCnosRoot, folderName), path21.join(parentWorkspaceRoot, folderName));
+  }
+  const rawManifest = parentLoaded.rawManifest;
+  const workspaces = rawManifest.workspaces ?? {};
+  const items = workspaces.items ?? {};
+  items[workspaceId] = items[workspaceId] ?? {};
+  workspaces.items = items;
+  rawManifest.workspaces = workspaces;
+  await writeFile9(path21.join(parentLoaded.manifestRoot, "cnos.yml"), stringifyYaml7(rawManifest), "utf8");
+  const archivePath = path21.join(packageRoot, ".cnos.detached.bak");
+  await rm4(archivePath, { recursive: true, force: true });
+  await rename(childCnosRoot, archivePath);
+  await writeCnosrc(packageRoot, {
+    root: marker.originalCnosrc.root,
+    ...workspaceId ? { workspace: workspaceId } : {}
+  });
+  if (options.json) {
+    return printJson({
+      packageRoot,
+      workspace: workspaceId,
+      parentRoot: parentLoaded.manifestRoot,
+      archivedTo: archivePath
+    });
+  }
+  return `attached workspace ${workspaceId} to ${displayPath(parentLoaded.manifestRoot, packageRoot)}`;
+}
+async function runWorkspace(args = [], options = {}) {
+  const [action] = args;
+  const cliArgs = [...options.cliArgs ?? []];
+  const packageRoot = path21.resolve(consumeOption(cliArgs, "--package-root") ?? options.root ?? process.cwd());
+  switch (action) {
+    case "detach":
+      return runDetach(packageRoot, { ...options, cliArgs });
+    case "attach":
+      return runAttach(packageRoot, { ...options, cliArgs });
+    default:
+      throw new Error(`Unsupported workspace action: ${action ?? "(missing)"}`);
+  }
+}
+
 // src/index.ts
 function resolveHelpTopic(command, args) {
   if (command === "help" || command === "help-ai") {
@@ -3616,9 +3931,15 @@ function resolveHelpTopic(command, args) {
   if (command === "build" && args[0] === "env") {
     return normalizeHelpTopic([command, args[0]]);
   }
+  if (command === "build" && args[0] && ["env", "server", "browser", "public"].includes(args[0])) {
+    return normalizeHelpTopic([command, args[0]]);
+  }
   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 === "vault" && args[0] && ["create", "add", "list", "delete", "remove"].includes(args[0])) {
     return normalizeHelpTopic([command, args[0] === "delete" ? "remove" : args[0] === "add" ? "create" : args[0]]);
   }
@@ -3773,6 +4094,10 @@ async function main(argv) {
     }
     case "watch":
       process.stdout.write(`${await runWatch(passthrough.length > 0 ? passthrough : args, runtimeOptions)}
+`);
+      return;
+    case "workspace":
+      process.stdout.write(`${await runWorkspace(args, runtimeOptions)}
 `);
       return;
     case "diff":

package/package.json

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