@kitsy/cnos-cli 1.6.1 → 1.8.0

package/dist/index.js

@@ -5,7 +5,8 @@ var OPTION_KEYS = {
   "--root": "root",
   "--workspace": "workspace",
   "--profile": "profile",
-  "--global-root": "globalRoot"
+  "--global-root": "globalRoot",
+  "--cache-ttl": "cacheTtlSeconds"
 };
 var COMMAND_OPTION_KEYS_WITH_VALUE = /* @__PURE__ */ new Set([
   "--format",
@@ -21,7 +22,9 @@ var COMMAND_OPTION_KEYS_WITH_VALUE = /* @__PURE__ */ new Set([
   "--inherit",
   "--as",
   "--set",
-  "--debounce"
+  "--debounce",
+  "--expr",
+  "--extends"
 ]);
 var COMMAND_FLAG_KEYS = /* @__PURE__ */ new Set([
   "--flatten",
@@ -39,7 +42,9 @@ var COMMAND_FLAG_KEYS = /* @__PURE__ */ new Set([
   "--dry-run",
   "--apply",
   "--rewrite",
-  "--signal"
+  "--signal",
+  "--derive",
+  "--onboard-current"
 ]);
 function normalizeCommand(argv) {
   const [command = "doctor", ...rest] = argv;
@@ -104,6 +109,14 @@ function normalizeCommand(argv) {
   return [command, ...rest];
 }
 function setOption(options, key, value) {
+  if (key === "cacheTtlSeconds") {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+      throw new Error(`Invalid value for --cache-ttl: ${value}`);
+    }
+    options.cacheTtlSeconds = parsed;
+    return;
+  }
   options[key] = value;
 }
 function parseArgs(argv) {
@@ -253,7 +266,7 @@ function printJson(value) {
 
 // src/services/projections.ts
 import { mkdir, writeFile } from "fs/promises";
-import path2 from "path";
+import path3 from "path";
 import { resolveBrowserData, resolveFrameworkEnv, resolveServerProjection } from "@kitsy/cnos/build";
 import { stringifyYaml } from "@kitsy/cnos/internal";
 
@@ -266,6 +279,9 @@ async function createRuntimeService(options = {}) {
     ...options.workspace ? { workspace: options.workspace } : {},
     ...options.profile ? { profile: options.profile } : {},
     ...options.globalRoot ? { globalRoot: options.globalRoot } : {},
+    cacheMode: options.cacheMode ?? "runtime",
+    ...typeof options.cacheTtlSeconds === "number" ? { cacheTtlSeconds: options.cacheTtlSeconds } : {},
+    ...options.forceRefresh ? { forceRefresh: true } : {},
     ...options.cliArgs && options.cliArgs.length > 0 ? { cliArgs: options.cliArgs } : {},
     ...options.secretResolution ? { secretResolution: options.secretResolution } : {},
     ...typeof options.secretRefreshTtl === "number" ? { secretRefreshTtl: options.secretRefreshTtl } : {},
@@ -273,6 +289,15 @@ async function createRuntimeService(options = {}) {
   });
 }
 
+// src/services/paths.ts
+import path2 from "path";
+function resolveFilesystemBasePath(root, cwd = process.cwd()) {
+  if (!root || root.startsWith("git+") || root.startsWith("cnos://")) {
+    return path2.resolve(cwd);
+  }
+  return path2.resolve(root);
+}
+
 // src/services/projections.ts
 function stringifyScalar(value) {
   if (value === void 0 || value === null) {
@@ -311,37 +336,62 @@ function formatKeyValueMap(values, format) {
   }
 }
 async function writeProjectionFile(to, output, root = process.cwd()) {
-  const targetPath = path2.resolve(root, to);
-  await mkdir(path2.dirname(targetPath), { recursive: true });
+  const targetPath = path3.resolve(root, to);
+  await mkdir(path3.dirname(targetPath), { recursive: true });
   await writeFile(targetPath, output, "utf8");
   return targetPath;
 }
 async function buildServerProjectionArtifact(to, options = {}, format = "json") {
-  const projection = await resolveServerProjection(options);
+  const projection = await resolveServerProjection({
+    ...options,
+    cacheMode: "build"
+  });
   const output = format === "yaml" ? stringifyYaml(projection) : `${JSON.stringify(projection, null, 2)}
 `;
-  const targetPath = await writeProjectionFile(to, output, options.root ?? process.cwd());
+  const targetPath = await writeProjectionFile(
+    to,
+    output,
+    resolveFilesystemBasePath(options.root, options.cwd ?? process.cwd())
+  );
   return { targetPath, output };
 }
 async function buildBrowserProjectionArtifact(to, options = {}, format = "json") {
-  const projection = await resolveBrowserData(options);
+  const projection = await resolveBrowserData({
+    ...options,
+    cacheMode: "build"
+  });
   const output = format === "yaml" ? stringifyYaml(projection) : `${JSON.stringify(projection, null, 2)}
 `;
-  const targetPath = await writeProjectionFile(to, output, options.root ?? process.cwd());
+  const targetPath = await writeProjectionFile(
+    to,
+    output,
+    resolveFilesystemBasePath(options.root, options.cwd ?? 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 env = await resolveFrameworkEnv(
+    {
+      ...options,
+      cacheMode: "build"
+    },
+    framework
+  );
   const output = formatKeyValueMap(env, format);
-  const targetPath = await writeProjectionFile(to, output, options.root ?? process.cwd());
+  const targetPath = await writeProjectionFile(
+    to,
+    output,
+    resolveFilesystemBasePath(options.root, options.cwd ?? process.cwd())
+  );
   return { targetPath, output, env };
 }
 async function buildEnvProjectionArtifact(to, options = {}, format = "dotenv") {
   const runtime = await createRuntimeService({
     ...options,
+    cacheMode: "build",
     cliArgs: [...options.cliArgs ?? []]
   });
   const env = runtime.toEnv();
@@ -352,7 +402,11 @@ async function buildEnvProjectionArtifact(to, options = {}, format = "dotenv") {
     }
   }
   const output = formatKeyValueMap(env, format);
-  const targetPath = await writeProjectionFile(to, output, options.root ?? process.cwd());
+  const targetPath = await writeProjectionFile(
+    to,
+    output,
+    resolveFilesystemBasePath(options.root, options.cwd ?? process.cwd())
+  );
   return { targetPath, output, env };
 }
 
@@ -413,23 +467,208 @@ async function runBuild(subcommand, options = {}) {
       ...provenanceTarget ? { provenance: provenanceTarget } : {}
     });
   }
-  return `built ${subcommand} artifact at ${displayPath(targetPath, options.root ?? process.cwd())}`;
+  return `built ${subcommand} artifact at ${displayPath(
+    targetPath,
+    resolveFilesystemBasePath(options.root, options.cwd ?? process.cwd())
+  )}`;
 }
 
-// src/commands/define.ts
+// src/services/cache.ts
+import { readdir, rm, stat } from "fs/promises";
 import path4 from "path";
+import {
+  loadManifest,
+  parseGitUri,
+  readRemoteRootCacheMetadata,
+  resolveCnosCacheRoot,
+  resolveRemoteRootCachePaths,
+  resolveRootUri
+} from "@kitsy/cnos/internal";
+async function computeDirectorySize(targetPath) {
+  try {
+    const info = await stat(targetPath);
+    if (!info.isDirectory()) {
+      return info.size;
+    }
+    const entries = await readdir(targetPath, { withFileTypes: true });
+    const sizes = await Promise.all(
+      entries.map((entry) => computeDirectorySize(path4.join(targetPath, entry.name)))
+    );
+    return sizes.reduce((sum, value) => sum + value, 0);
+  } catch {
+    return 0;
+  }
+}
+async function listCachedRoots(processEnv = process.env) {
+  const rootsDir = path4.join(resolveCnosCacheRoot(processEnv), "roots");
+  try {
+    const entries = await readdir(rootsDir, { withFileTypes: true });
+    const records = await Promise.all(
+      entries.filter((entry) => entry.isDirectory()).map(async (entry) => {
+        const cacheDir = path4.join(rootsDir, entry.name);
+        const metadata = await readRemoteRootCacheMetadata(path4.join(cacheDir, ".cnos-cache-meta.json"));
+        if (!metadata) {
+          return void 0;
+        }
+        return {
+          uri: metadata.uri,
+          cacheDir,
+          cachedAt: metadata.cachedAt,
+          resolvedCommit: metadata.resolvedCommit,
+          immutable: metadata.isImmutable,
+          ref: metadata.ref,
+          subpath: metadata.subpath,
+          sizeBytes: await computeDirectorySize(cacheDir)
+        };
+      })
+    );
+    return records.filter((record) => Boolean(record)).sort((left, right) => left.uri.localeCompare(right.uri));
+  } catch {
+    return [];
+  }
+}
+async function clearCachedRoots(uri, processEnv = process.env) {
+  if (uri) {
+    const paths = resolveRemoteRootCachePaths(uri, processEnv);
+    await rm(paths.cacheDir, { recursive: true, force: true });
+    return { cleared: [uri] };
+  }
+  const records = await listCachedRoots(processEnv);
+  await Promise.all(records.map((record) => rm(record.cacheDir, { recursive: true, force: true })));
+  return {
+    cleared: records.map((record) => record.uri)
+  };
+}
+async function refreshCachedRoots(uri, options = {}) {
+  const processEnv = options.processEnv ?? process.env;
+  if (uri) {
+    const parsed = parseGitUri(uri);
+    await resolveRootUri(uri, process.cwd(), {
+      processEnv,
+      cacheMode: "build",
+      forceRefresh: true
+    });
+    return { refreshed: [parsed.uri] };
+  }
+  const loadedManifest = await loadManifest({
+    ...options.root ? { root: options.root } : {},
+    ...options.cwd ? { cwd: options.cwd } : {},
+    processEnv
+  }).catch(() => void 0);
+  if (loadedManifest?.rootResolution.remote && loadedManifest.rootResolution.protocol === "git") {
+    await resolveRootUri(loadedManifest.rootResolution.rootUri, loadedManifest.consumerRoot, {
+      processEnv,
+      cacheMode: "build",
+      forceRefresh: true
+    });
+    return {
+      refreshed: [loadedManifest.rootResolution.rootUri]
+    };
+  }
+  const records = await listCachedRoots(processEnv);
+  const mutable = records.filter((record) => !record.immutable);
+  for (const record of mutable) {
+    await resolveRootUri(record.uri, process.cwd(), {
+      processEnv,
+      cacheMode: "build",
+      forceRefresh: true
+    });
+  }
+  return {
+    refreshed: mutable.map((record) => record.uri)
+  };
+}
+
+// src/commands/cache.ts
+function normalizeAction(args) {
+  const [action = "list", target] = args;
+  if (action === "list" || action === "clear" || action === "refresh") {
+    return {
+      action,
+      ...typeof target === "string" ? { target } : {}
+    };
+  }
+  return {
+    action: "list",
+    ...typeof args[0] === "string" ? { target: args[0] } : {}
+  };
+}
+function formatBytes(sizeBytes) {
+  if (sizeBytes < 1024) {
+    return `${sizeBytes} B`;
+  }
+  if (sizeBytes < 1024 * 1024) {
+    return `${Math.round(sizeBytes / 1024 * 10) / 10} KB`;
+  }
+  return `${Math.round(sizeBytes / (1024 * 1024) * 10) / 10} MB`;
+}
+async function runCache(args = [], options = {}) {
+  const { action, target } = normalizeAction(args);
+  if (action === "clear") {
+    const result = await clearCachedRoots(target, options.processEnv ?? process.env);
+    return options.json ? printJson(result) : `cleared ${result.cleared.length} cached root(s)`;
+  }
+  if (action === "refresh") {
+    const result = await refreshCachedRoots(target, options);
+    return options.json ? printJson(result) : `refreshed ${result.refreshed.length} cached root(s)`;
+  }
+  const records = await listCachedRoots(options.processEnv ?? process.env);
+  if (options.json) {
+    return printJson(records);
+  }
+  if (records.length === 0) {
+    return "no cached remote roots";
+  }
+  return records.map(
+    (record) => [
+      record.uri,
+      `  cached: ${record.cachedAt}`,
+      `  commit: ${record.resolvedCommit}`,
+      `  immutable: ${record.immutable ? "yes" : "no"}`,
+      `  size: ${formatBytes(record.sizeBytes)}`
+    ].join("\n")
+  ).join("\n\n");
+}
+
+// src/commands/define.ts
+import path6 from "path";
 
 // src/services/writes.ts
 import { mkdir as mkdir2, readFile, writeFile as writeFile2 } from "fs/promises";
-import path3 from "path";
+import path5 from "path";
 import {
   getNamespaceDefinition,
+  normalizeDerivedValue,
+  parseDerivation,
   createSecretVaultProvider,
+  validateDerivedTargetNamespace,
+  validateParsedDerivation,
   parseYaml,
   resolveConfigDocumentPath,
   resolveVaultAuth,
   stringifyYaml as stringifyYaml2
 } from "@kitsy/cnos/internal";
+
+// src/services/rootAccess.ts
+import { loadManifest as loadManifest2 } from "@kitsy/cnos/internal";
+async function assertWritableConfigRoot(action, options = {}) {
+  const loadedManifest = await loadManifest2({
+    ...options.root ? { root: options.root } : {},
+    ...options.cwd ? { cwd: options.cwd } : {},
+    ...options.processEnv ? { processEnv: options.processEnv } : {},
+    ...options.cacheMode ? { cacheMode: options.cacheMode } : {},
+    ...typeof options.cacheTtlSeconds === "number" ? { cacheTtlSeconds: options.cacheTtlSeconds } : {},
+    ...options.forceRefresh ? { forceRefresh: true } : {}
+  });
+  if (!loadedManifest.rootResolution.readOnly) {
+    return;
+  }
+  throw new Error(
+    `Cannot ${action} because the active CNOS root is remote and read-only (${loadedManifest.rootResolution.rootUri}). Clone the config repo and edit it directly.`
+  );
+}
+
+// src/services/writes.ts
 function setNestedValue(target, pathSegments, value) {
   const [head, ...tail] = pathSegments;
   if (!head) {
@@ -495,6 +734,7 @@ function getSelectedWorkspaceRoot(options, runtime) {
   return workspaceRoot.path;
 }
 async function defineValue(namespace, configPath, rawValue, options = {}) {
+  await assertWritableConfigRoot(`write ${namespace}.${configPath}`, options);
   if (namespace === "secret") {
     const secret = await setSecret(configPath, rawValue, {
       ...options,
@@ -527,9 +767,17 @@ async function defineValue(namespace, configPath, rawValue, options = {}) {
   const profile = options.profile ?? runtime.graph.profile;
   const filePath = resolveConfigDocumentPath(workspaceRoot, namespace, configPath, profile);
   const document = await readYamlDocument(filePath);
-  const parsedValue = parseScalarValue(rawValue);
+  let parsedValue;
+  if (options.deriveExpression !== void 0) {
+    validateDerivedTargetNamespace(runtime.manifest, namespace);
+    const derivedValue = normalizeDerivedValue(options.deriveExpression, options.deriveExprMode ?? false);
+    validateParsedDerivation(runtime.manifest, parseDerivation(derivedValue));
+    parsedValue = derivedValue;
+  } else {
+    parsedValue = parseScalarValue(rawValue);
+  }
   setNestedValue(document, configPath.split("."), parsedValue);
-  await mkdir2(path3.dirname(filePath), { recursive: true });
+  await mkdir2(path5.dirname(filePath), { recursive: true });
   await writeFile2(filePath, stringifyYaml2(document), "utf8");
   return {
     filePath,
@@ -567,7 +815,7 @@ async function setSecret(configPath, rawValue, options = {}) {
     };
   }
   setNestedValue(document, configPath.split("."), reference);
-  await mkdir2(path3.dirname(filePath), { recursive: true });
+  await mkdir2(path5.dirname(filePath), { recursive: true });
   await writeFile2(filePath, stringifyYaml2(document), "utf8");
   return {
     filePath,
@@ -577,6 +825,7 @@ async function setSecret(configPath, rawValue, options = {}) {
   };
 }
 async function deleteSecret(configPath, options = {}) {
+  await assertWritableConfigRoot(`delete secret.${configPath}`, options);
   const runtime = await createRuntimeService(options);
   const workspaceRoot = getSelectedWorkspaceRoot(options, runtime);
   const profile = options.profile ?? runtime.graph.profile;
@@ -607,6 +856,7 @@ async function deleteSecret(configPath, options = {}) {
   };
 }
 async function deleteValue(namespace, configPath, options = {}) {
+  await assertWritableConfigRoot(`delete ${namespace}.${configPath}`, options);
   if (namespace === "secret") {
     return deleteSecret(configPath, options);
   }
@@ -645,7 +895,7 @@ async function deleteValue(namespace, configPath, options = {}) {
 // src/commands/define.ts
 async function runDefine(namespace, configPath, rawValue, options = {}) {
   const cliArgs = [...options.cliArgs ?? []];
-  const root = path4.resolve(options.root ?? process.cwd());
+  const root = path6.resolve(options.root ?? process.cwd());
   const target = consumeOption(cliArgs, "--target") ?? "local";
   const local = consumeFlag(cliArgs, "--local");
   const remote = consumeFlag(cliArgs, "--remote");
@@ -676,7 +926,7 @@ async function runDefine(namespace, configPath, rawValue, options = {}) {
 
 // src/services/envMaterialization.ts
 import { mkdir as mkdir3, writeFile as writeFile3 } from "fs/promises";
-import path5 from "path";
+import path7 from "path";
 function resolveEnvFromRuntime(runtime, cliArgs = []) {
   const args = [...cliArgs];
   const isPublic = consumeFlag(args, "--public");
@@ -703,17 +953,21 @@ async function resolveMaterializedEnv(options = {}) {
   };
 }
 function resolveMaterializedEnvTarget(to, root = process.cwd()) {
-  return path5.resolve(root, to);
+  return path7.resolve(root, to);
 }
 async function writeMaterializedEnvFile(to, output, root = process.cwd()) {
   const targetPath = resolveMaterializedEnvTarget(to, root);
-  await mkdir3(path5.dirname(targetPath), { recursive: true });
+  await mkdir3(path7.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());
+  const targetPath = await writeMaterializedEnvFile(
+    to,
+    result.output,
+    resolveFilesystemBasePath(options.root, options.cwd ?? process.cwd())
+  );
   return {
     ...result,
     targetPath
@@ -834,6 +1088,7 @@ async function startDevEnvLoop(command, options = {}) {
   const writeCurrent = async () => {
     await materializeEnvToFile(to, {
       ...options,
+      cacheMode: "dev",
       cliArgs: [...cliArgs]
     });
   };
@@ -847,6 +1102,7 @@ async function startDevEnvLoop(command, options = {}) {
   }
   const watcher = await startGraphWatchLoop({
     ...options,
+    cacheMode: "dev",
     cliArgs,
     debounceMs,
     async onChange(payload) {
@@ -903,7 +1159,10 @@ async function runDev(subcommand, command, options = {}) {
   };
   process.once("SIGINT", closeLoop);
   process.once("SIGTERM", closeLoop);
-  const targetPath = displayPath(to, options.root ?? process.cwd());
+  const targetPath = displayPath(
+    to,
+    resolveFilesystemBasePath(options.root, options.cwd ?? process.cwd())
+  );
   return isSignal ? `watching config changes and rewriting ${targetPath} in signal mode` : `watching config changes, rewriting ${targetPath}, and restarting the child process`;
 }
 
@@ -956,11 +1215,12 @@ async function runDiff(leftProfile, rightProfile, options = {}) {
 }
 
 // src/services/doctor.ts
-import { readdir, readFile as readFile2 } from "fs/promises";
-import path6 from "path";
+import { readdir as readdir2, readFile as readFile2 } from "fs/promises";
+import path8 from "path";
 import {
   detectLegacyVaultFormat,
   isSecretReference as isSecretReference2,
+  loadManifest as loadManifest3,
   parseYaml as parseYaml2,
   readKeychain,
   resolveSecretStoreRoot
@@ -979,7 +1239,7 @@ async function createValidationSummary(options = {}) {
 
 // src/services/doctor.ts
 async function checkGitignore(root) {
-  const gitignorePath = path6.join(root, ".gitignore");
+  const gitignorePath = path8.join(root, ".gitignore");
   const expected = [
     ".cnos/env/.env",
     ".cnos/env/.env.*",
@@ -1011,15 +1271,15 @@ function issueSummary(issues) {
 }
 async function collectYamlFiles(root) {
   try {
-    const entries = await readdir(root, { withFileTypes: true });
+    const entries = await readdir2(root, { withFileTypes: true });
     const results = [];
     for (const entry of entries) {
-      const target = path6.join(root, entry.name);
+      const target = path8.join(root, entry.name);
       if (entry.isDirectory()) {
         results.push(...await collectYamlFiles(target));
         continue;
       }
-      if (entry.isFile() && [".yml", ".yaml"].includes(path6.extname(entry.name).toLowerCase())) {
+      if (entry.isFile() && [".yml", ".yaml"].includes(path8.extname(entry.name).toLowerCase())) {
         results.push(target);
       }
     }
@@ -1044,7 +1304,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(path6.join(root.path, "secrets")))
+    runtime.graph.workspace.workspaceRoots.filter((root) => root.scope === "local").map((root) => collectYamlFiles(path8.join(root.path, "secrets")))
   );
   const plaintextFiles = [];
   for (const file of secretFiles.flat()) {
@@ -1074,7 +1334,15 @@ async function checkSecretSecurity(options, runtime) {
   };
 }
 async function evaluateDoctor(options = {}) {
-  const root = path6.resolve(options.root ?? process.cwd());
+  const root = resolveFilesystemBasePath(options.root, options.cwd ?? process.cwd());
+  const loadedManifest = await loadManifest3({
+    ...options.root ? { root: options.root } : {},
+    ...options.cwd ? { cwd: options.cwd } : {},
+    ...options.processEnv ? { processEnv: options.processEnv } : {},
+    ...options.cacheMode ? { cacheMode: options.cacheMode } : {},
+    ...typeof options.cacheTtlSeconds === "number" ? { cacheTtlSeconds: options.cacheTtlSeconds } : {},
+    ...options.forceRefresh ? { forceRefresh: true } : {}
+  });
   const { 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");
@@ -1090,6 +1358,11 @@ async function evaluateDoctor(options = {}) {
       ok: true,
       details: `${runtime.graph.workspace.workspaceId} via ${runtime.graph.workspace.workspaceSource}`
     },
+    {
+      name: "root",
+      ok: true,
+      details: loadedManifest.rootResolution.remote ? `${loadedManifest.rootResolution.rootUri} -> ${loadedManifest.manifestRoot}${loadedManifest.rootResolution.immutable ? " | immutable" : " | mutable ref"}${loadedManifest.rootResolution.resolvedCommit ? ` | commit ${loadedManifest.rootResolution.resolvedCommit}` : ""}` : loadedManifest.manifestRoot
+    },
     {
       name: "namespaces",
       ok: true,
@@ -1214,7 +1487,10 @@ async function runExportEnv(options = {}) {
         ...framework ? { framework } : {}
       });
     }
-    return `Wrote ${Object.keys(result2.env).length} env vars to ${displayPath(result2.targetPath, options.root ?? process.cwd())}`;
+    return `Wrote ${Object.keys(result2.env).length} env vars to ${displayPath(
+      result2.targetPath,
+      resolveFilesystemBasePath(options.root, options.cwd ?? process.cwd())
+    )}`;
   }
   const result = await resolveMaterializedEnv(baseOptions);
   if (options.json) {
@@ -1235,7 +1511,7 @@ async function runExport(subcommand, options = {}) {
 var GLOBAL_OPTIONS = [
   {
     flag: "--root <path>",
-    description: "Resolve the CNOS project from a specific filesystem root."
+    description: "Resolve the CNOS project from a specific filesystem root or remote root URI."
   },
   {
     flag: "--workspace <id>",
@@ -1249,6 +1525,10 @@ var GLOBAL_OPTIONS = [
     flag: "--global-root <path>",
     description: "Override the configured global CNOS root used for workspace layering."
   },
+  {
+    flag: "--cache-ttl <seconds>",
+    description: "Override the remote-root cache TTL for mutable refs during this invocation."
+  },
   {
     flag: "--json",
     description: "Emit JSON output for commands that support structured responses."
@@ -1263,6 +1543,39 @@ var GLOBAL_OPTIONS = [
   }
 ];
 var COMMANDS = [
+  {
+    id: "cache",
+    summary: "Inspect and manage cached remote roots.",
+    usage: "cnos cache [list|clear|refresh] [root-uri] [global-options]",
+    description: "Lists cached git-backed remote roots, clears cache entries, or forces a refresh for mutable refs.",
+    examples: [
+      "cnos cache list",
+      "cnos cache clear",
+      "cnos cache clear git+https://github.com/org/config.git#v2.1.0",
+      "cnos cache refresh"
+    ]
+  },
+  {
+    id: "cache list",
+    summary: "List cached remote roots.",
+    usage: "cnos cache list [global-options]",
+    description: "Lists git-backed remote roots cached under ~/.cnos/cache together with cache time, resolved commit, immutability, and size.",
+    examples: ["cnos cache list"]
+  },
+  {
+    id: "cache clear",
+    summary: "Clear cached remote roots.",
+    usage: "cnos cache clear [root-uri] [global-options]",
+    description: "Removes all cached remote roots by default, or clears one specific cached root when a full remote URI is provided.",
+    examples: ["cnos cache clear", "cnos cache clear git+https://github.com/org/config.git#main"]
+  },
+  {
+    id: "cache refresh",
+    summary: "Force refresh mutable cached remote roots.",
+    usage: "cnos cache refresh [root-uri] [global-options]",
+    description: "Re-fetches a specific git-backed remote root, or refreshes the active remote root / all mutable cached roots when no URI is provided.",
+    examples: ["cnos cache refresh", "cnos cache refresh git+ssh://git@github.com/org/config.git#main"]
+  },
   {
     id: "init",
     summary: "Scaffold a workspace-aware CNOS tree in the current project.",
@@ -1330,6 +1643,14 @@ var COMMANDS = [
         flag: "--target <local|global>",
         description: "Choose whether writes land in the local project workspace or the configured global root."
       },
+      {
+        flag: "--derive",
+        description: "Write a derived value instead of a literal. Use the second positional value as a template, or combine with --expr."
+      },
+      {
+        flag: "--expr <expression>",
+        description: "With --derive, write an expression-form derived value instead of template shorthand."
+      },
       {
         flag: "--prefix <path>",
         description: "Filter value list output to keys that begin with this logical path or key prefix."
@@ -1338,6 +1659,8 @@ var COMMANDS = [
     examples: [
       "cnos value app.name",
       "cnos value set server.port 3000",
+      "cnos value set app.origin --derive '${value.app.protocol}://${value.app.host}'",
+      `cnos value set app.display_name --derive --expr "coalesce(value.app.custom_name, value.app.name, 'Unnamed')"`,
       "cnos add value app.name demo",
       "cnos value list --prefix app."
     ]
@@ -1345,9 +1668,28 @@ var COMMANDS = [
   {
     id: "value set",
     summary: "Write a value.",
-    usage: "cnos value set <path> <value> [--target <local|global>] [global-options]",
-    description: "Writes a deterministic value document into the selected workspace or explicit global target.",
-    examples: ["cnos value set app.name demo", "cnos add value server.port 3000 --target global"]
+    usage: "cnos value set <path> <value> [--target <local|global>] [--derive] [--expr <expression>] [global-options]",
+    description: "Writes either a literal value or a first-class derived value into the selected workspace or explicit global target.",
+    options: [
+      {
+        flag: "--target <local|global>",
+        description: "Choose whether writes land in the local project workspace or the configured global root."
+      },
+      {
+        flag: "--derive",
+        description: "Interpret the provided value as a derived template, or combine with --expr for expression syntax."
+      },
+      {
+        flag: "--expr <expression>",
+        description: "With --derive, store the value as an expression-form derivation instead of template shorthand."
+      }
+    ],
+    examples: [
+      "cnos value set app.name demo",
+      "cnos value set app.origin --derive '${value.app.protocol}://${value.app.host}'",
+      `cnos value set app.display_name --derive --expr "coalesce(value.app.custom_name, value.app.name, 'Unnamed')"`,
+      "cnos add value server.port 3000 --target global"
+    ]
   },
   {
     id: "value list",
@@ -1520,7 +1862,7 @@ var COMMANDS = [
     id: "list",
     summary: "List resolved config entries.",
     usage: "cnos list [<namespace>|all] [--prefix <path>] [--framework <name>] [global-options]",
-    description: "Lists stored config or derived projections across one namespace or the full effective graph, with optional prefix filtering. Custom data namespaces such as flags are supported, and process exposes server-only ambient runtime state.",
+    description: "Lists stored config or derived projections across one namespace or the full effective graph, with optional prefix filtering. Derived values are annotated with `(derived)`. Custom data namespaces such as flags are supported, and process exposes server-only ambient runtime state.",
     options: [
       {
         flag: "--namespace <name>",
@@ -1646,7 +1988,7 @@ var COMMANDS = [
     id: "inspect",
     summary: "Inspect the winning value and provenance for a key.",
     usage: "cnos inspect <key> [global-options]",
-    description: "Shows the resolved value, namespace, active profile, workspace context, and the loader/origin that won precedence.",
+    description: "Shows the resolved value, namespace, active profile, workspace context, loader/origin, and derived-expression metadata when the key is computed from other CNOS keys or runtime namespaces.",
     arguments: [
       {
         name: "key",
@@ -1874,10 +2216,48 @@ 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 <add|list|remove|scaffold|attach|detach> [options] [global-options]",
+    description: "Adds and removes manifest workspaces, scaffolds package anchors, migrates single-root projects into workspace mode, and handles detach/attach flows for independent child packages.",
+    examples: [
+      "cnos workspace list",
+      "cnos workspace add travel --package-root apps/travel --extends base",
+      "cnos workspace add main --onboard-current",
+      "cnos workspace remove gallery",
+      "cnos workspace detach --package-root apps/travel"
+    ]
+  },
+  {
+    id: "workspace add",
+    summary: "Add a workspace to the manifest and scaffold its on-disk layout.",
+    usage: "cnos workspace add <id> [--package-root <path>] [--extends <workspace>] [--onboard-current] [--force] [global-options]",
+    description: "Creates .cnos/workspaces/<id>, updates cnos.yml, writes a .cnosrc.yml anchor at the selected package root, and optionally migrates an existing single-root .cnos tree into workspace mode with --onboard-current.",
+    examples: [
+      "cnos workspace add travel --package-root apps/travel --extends base",
+      "cnos workspace add insights --package-root apps/insights",
+      "cnos workspace add main --onboard-current"
+    ]
+  },
+  {
+    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",
@@ -2050,6 +2430,7 @@ var HELP_DOCUMENT = {
   examples: [
     "cnos use --profile stage",
     "cnos doctor --workspace api",
+    "cnos cache list",
     "cnos build env --profile stage --to .env.stage",
     "cnos dev env --profile local --to .env.local -- pnpm dev",
     "cnos export env --public --framework vite",
@@ -2165,11 +2546,11 @@ function runHelpAi(topic, cliArgs = []) {
 }
 
 // src/commands/init.ts
-import path8 from "path";
+import path10 from "path";
 
 // src/services/scaffold.ts
 import { mkdir as mkdir4, readFile as readFile3, writeFile as writeFile4 } from "fs/promises";
-import path7 from "path";
+import path9 from "path";
 function scaffoldManifest(projectName, workspace) {
   const lines = [
     "version: 1",
@@ -2208,7 +2589,7 @@ async function ensureFile(filePath, content) {
   }
 }
 async function ensureGitignore(root) {
-  const gitignorePath = path7.join(root, ".gitignore");
+  const gitignorePath = path9.join(root, ".gitignore");
   const requiredEntries = [
     ".cnos/env/.env",
     ".cnos/env/.env.*",
@@ -2235,14 +2616,13 @@ async function ensureGitignore(root) {
 `, "utf8");
   return true;
 }
-async function scaffoldWorkspace(root, workspace) {
-  const cnosRoot = path7.join(root, ".cnos");
-  const workspaceRoot = workspace ? path7.join(cnosRoot, "workspaces", workspace) : cnosRoot;
+async function ensureWorkspaceLayout(cnosRoot, workspace) {
+  const workspaceRoot = workspace ? path9.join(cnosRoot, "workspaces", workspace) : cnosRoot;
   const createdPaths = [];
-  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 });
+  await mkdir4(path9.join(workspaceRoot, "profiles"), { recursive: true });
+  await mkdir4(path9.join(workspaceRoot, "values"), { recursive: true });
+  await mkdir4(path9.join(workspaceRoot, "secrets"), { recursive: true });
+  await mkdir4(path9.join(workspaceRoot, "env"), { recursive: true });
   const relativePaths = workspace ? [
     ["workspaces", workspace, "profiles", ".gitkeep"],
     ["workspaces", workspace, "values", ".gitkeep"],
@@ -2255,23 +2635,33 @@ async function scaffoldWorkspace(root, workspace) {
     ["env", ".gitkeep"]
   ];
   for (const relativePath of relativePaths) {
-    const filePath = path7.join(cnosRoot, ...relativePath);
+    const filePath = path9.join(cnosRoot, ...relativePath);
     if (await ensureFile(filePath, "")) {
-      createdPaths.push(path7.relative(root, filePath).replace(/\\/g, "/"));
+      createdPaths.push(path9.relative(path9.dirname(cnosRoot), filePath).replace(/\\/g, "/"));
     }
   }
-  if (await ensureFile(path7.join(cnosRoot, "cnos.yml"), scaffoldManifest(path7.basename(root), workspace))) {
-    createdPaths.push(".cnos/cnos.yml");
-  }
-  if (await ensureFile(
-    path7.join(root, ".cnosrc.yml"),
+  return createdPaths;
+}
+async function ensureCnosrc(root, workspace) {
+  return ensureFile(
+    path9.join(root, ".cnosrc.yml"),
     workspace ? `root: ./.cnos
 workspace: ${workspace}
 ` : "root: ./.cnos\n"
-  )) {
+  );
+}
+async function scaffoldWorkspace(root, workspace) {
+  const cnosRoot = path9.join(root, ".cnos");
+  const createdPaths = (await ensureWorkspaceLayout(cnosRoot, workspace)).map(
+    (entry) => entry.replace(/^\.cnos\//, ".cnos/")
+  );
+  if (await ensureFile(path9.join(cnosRoot, "cnos.yml"), scaffoldManifest(path9.basename(root), workspace))) {
+    createdPaths.push(".cnos/cnos.yml");
+  }
+  if (await ensureCnosrc(root, workspace)) {
     createdPaths.push(".cnosrc.yml");
   }
-  if (workspace && await ensureFile(path7.join(root, ".cnos-workspace.yml"), `workspace: ${workspace}
+  if (workspace && await ensureFile(path9.join(root, ".cnos-workspace.yml"), `workspace: ${workspace}
 globalRoot: ~/.cnos
 `)) {
     createdPaths.push(".cnos-workspace.yml");
@@ -2288,7 +2678,7 @@ globalRoot: ~/.cnos
 
 // src/commands/init.ts
 async function runInit(options = {}) {
-  const root = path8.resolve(options.root ?? process.cwd());
+  const root = path10.resolve(options.root ?? process.cwd());
   const result = await scaffoldWorkspace(root, options.workspace);
   if (options.json) {
     return printJson(result);
@@ -2324,6 +2714,22 @@ function printInspect(record) {
       `overridden: ${record.overridden.map((entry) => `${entry.sourceId}@${entry.workspaceId}=${String(entry.value)}`).join(", ")}`
     );
   }
+  if (record.derived) {
+    lines.push(`derivedType: ${record.derived.type}`);
+    lines.push(`derivedExpression: ${record.derived.expression}`);
+    lines.push(`runtimeDependent: ${record.derived.runtimeDependent ? "yes" : "no"}`);
+    if (record.derived.runtimeNamespaces.length > 0) {
+      lines.push(`runtimeNamespaces: ${record.derived.runtimeNamespaces.join(", ")}`);
+    }
+    if (record.derived.dependencies.length > 0) {
+      lines.push(
+        `dependencies: ${record.derived.dependencies.map((entry) => `${entry.key}=${String(entry.value)}${entry.runtimeNamespace ? ` (${entry.runtimeNamespace})` : ""}`).join(", ")}`
+      );
+    }
+    if (record.derived.promotionWarning) {
+      lines.push(`warning: ${record.derived.promotionWarning}`);
+    }
+  }
   return lines.join("\n");
 }
 
@@ -2391,13 +2797,24 @@ function toStoredEntry(namespace, entry, filter = {}) {
   }
   return {
     key: entry.key,
-    value: selectedCandidate.value
+    value: selectedCandidate.value,
+    ...typeof selectedCandidate.value === "object" && selectedCandidate.value !== null && !Array.isArray(selectedCandidate.value) && "$derive" in selectedCandidate.value ? {
+      derived: true
+    } : {}
   };
 }
-function listStoredNamespace(namespace, options) {
-  return createRuntimeService(options).then(
-    (runtime) => Array.from(runtime.graph.entries.values()).filter((entry) => entry.namespace === namespace).map((entry) => toStoredEntry(namespace, entry, options)).filter((entry) => Boolean(entry)).filter((entry) => matchesPrefix(entry.key, options.prefix)).sort((left, right) => left.key.localeCompare(right.key))
-  );
+async function listStoredNamespace(namespace, options) {
+  const runtime = await createRuntimeService(options);
+  return Array.from(runtime.graph.entries.values()).filter((entry) => entry.namespace === namespace).map((entry) => {
+    const stored = toStoredEntry(namespace, entry, options);
+    if (!stored) {
+      return void 0;
+    }
+    return {
+      ...stored,
+      value: stored.derived ? runtime.read(entry.key) : stored.value
+    };
+  }).filter((entry) => Boolean(entry)).filter((entry) => entry.value !== void 0).filter((entry) => matchesPrefix(entry.key, options.prefix)).sort((left, right) => left.key.localeCompare(right.key));
 }
 function listProjectedNamespace(namespace, options) {
   return createRuntimeService(options).then((runtime) => {
@@ -2479,14 +2896,14 @@ async function runList(args = [], options = {}) {
   if (entries.length === 0) {
     return "";
   }
-  return entries.map((entry) => `${entry.key}=${printValue(entry.value)}`).join("\n");
+  return entries.map((entry) => `${entry.key}=${printValue(entry.value)}${entry.derived ? "  (derived)" : ""}`).join("\n");
 }
 
 // src/commands/migrate.ts
-import path9 from "path";
+import path11 from "path";
 import {
   applyManifestMappings,
-  loadManifest,
+  loadManifest as loadManifest4,
   proposeMapping,
   rewriteSourceFiles,
   scanEnvUsage
@@ -2500,8 +2917,18 @@ async function runMigrate(options = {}) {
   if (cliArgs.length > 0) {
     throw new Error(`Unknown migrate options: ${cliArgs.join(" ")}`);
   }
-  const manifest = await loadManifest(options.root ? { root: options.root } : {});
-  const scanRoot = path9.resolve(manifest.repoRoot, scan ?? "src");
+  if (apply) {
+    await assertWritableConfigRoot("apply migration mappings", options);
+  }
+  const manifest = await loadManifest4({
+    ...options.root ? { root: options.root } : {},
+    ...options.cwd ? { cwd: options.cwd } : {},
+    ...options.processEnv ? { processEnv: options.processEnv } : {},
+    ...options.cacheMode ? { cacheMode: options.cacheMode } : {},
+    ...typeof options.cacheTtlSeconds === "number" ? { cacheTtlSeconds: options.cacheTtlSeconds } : {},
+    ...options.forceRefresh ? { forceRefresh: true } : {}
+  });
+  const scanRoot = path11.resolve(manifest.consumerRoot, 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));
@@ -2563,7 +2990,7 @@ async function runMigrate(options = {}) {
 }
 
 // src/commands/namespace.ts
-import path10 from "path";
+import path12 from "path";
 function normalizeCommand2(args) {
   const [actionOrPath, ...tail] = args;
   if (!actionOrPath) {
@@ -2586,7 +3013,7 @@ function normalizeCommand2(args) {
 async function runNamespace(namespace, args = [], options = {}) {
   const { action, tail } = normalizeCommand2(args);
   const cliArgs = [...options.cliArgs ?? []];
-  const root = path10.resolve(options.root ?? process.cwd());
+  const root = path12.resolve(options.root ?? process.cwd());
   if (action === "list") {
     const prefix = consumeOption(cliArgs, "--prefix");
     const entries = await listConfigEntries(namespace, {
@@ -2597,16 +3024,24 @@ async function runNamespace(namespace, args = [], options = {}) {
     if (options.json) {
       return printJson(entries);
     }
-    return entries.map((entry) => `${entry.key}=${printValue(entry.value)}`).join("\n");
+    return entries.map((entry) => `${entry.key}=${printValue(entry.value)}${entry.derived ? "  (derived)" : ""}`).join("\n");
   }
   if (action === "set") {
     const configPath2 = tail[0] ?? "app.name";
-    const rawValue = tail[1] ?? "";
+    const derive = consumeFlag(cliArgs, "--derive");
+    const expr = consumeOption(cliArgs, "--expr");
+    const deriveArg = derive && !expr && cliArgs[0] && !cliArgs[0].startsWith("--") ? cliArgs.shift() : void 0;
+    const rawValue = derive ? "" : tail[1] ?? "";
+    const deriveExpression = derive ? expr ?? tail[1] ?? deriveArg ?? "" : void 0;
     const target = consumeOption(cliArgs, "--target") ?? "local";
     const result = await defineValue(namespace, configPath2, rawValue, {
       ...options,
       cliArgs,
-      target
+      target,
+      ...deriveExpression !== void 0 ? {
+        deriveExpression,
+        deriveExprMode: Boolean(expr)
+      } : {}
     });
     if (options.json) {
       return printJson({
@@ -2648,34 +3083,34 @@ async function runNamespace(namespace, args = [], options = {}) {
 }
 
 // src/commands/onboard.ts
-import { copyFile, readdir as readdir2, rm } from "fs/promises";
-import path11 from "path";
+import { copyFile, readdir as readdir3, rm as rm2 } from "fs/promises";
+import path13 from "path";
 var ROOT_ENV_FILE_PATTERN = /^\.env(?:\.[A-Za-z0-9_-]+)*(?:\.example)?$/;
 async function listRootEnvFiles(root) {
-  const entries = await readdir2(root, { withFileTypes: true });
+  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));
 }
 async function runOnboard(options = {}) {
-  const root = path11.resolve(options.root ?? process.cwd());
-  const workspace = options.workspace ?? path11.basename(root);
+  const root = path13.resolve(options.root ?? process.cwd());
+  const workspace = options.workspace ?? path13.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 = path11.join(root, ".cnos", "workspaces", workspace, "env");
+  const envRoot = path13.join(root, ".cnos", "workspaces", workspace, "env");
   const rootFiles = await listRootEnvFiles(root);
   const imported = [];
   const skipped = [];
   for (const fileName of rootFiles) {
-    const sourcePath = path11.join(root, fileName);
-    const targetPath = path11.join(envRoot, fileName);
+    const sourcePath = path13.join(root, fileName);
+    const targetPath = path13.join(envRoot, fileName);
     try {
       await copyFile(sourcePath, targetPath);
-      imported.push(path11.relative(root, targetPath).replace(/\\/g, "/"));
+      imported.push(path13.relative(root, targetPath).replace(/\\/g, "/"));
       if (move) {
-        await rm(sourcePath);
+        await rm2(sourcePath);
       }
     } catch {
       skipped.push(fileName);
@@ -2698,14 +3133,14 @@ async function runOnboard(options = {}) {
 }
 
 // src/commands/profile.ts
-import path14 from "path";
+import path16 from "path";
 
 // src/services/context.ts
 import { readFile as readFile4, writeFile as writeFile5 } from "fs/promises";
-import path12 from "path";
+import path14 from "path";
 import { parseYaml as parseYaml3, stringifyYaml as stringifyYaml3 } from "@kitsy/cnos/internal";
 async function loadCliContext(root = process.cwd()) {
-  const filePath = path12.join(path12.resolve(root), ".cnos-workspace.yml");
+  const filePath = path14.join(path14.resolve(root), ".cnos-workspace.yml");
   try {
     const source = await readFile4(filePath, "utf8");
     const parsed = parseYaml3(source);
@@ -2718,8 +3153,8 @@ async function loadCliContext(root = process.cwd()) {
   }
 }
 async function saveCliContext(options = {}) {
-  const root = path12.resolve(options.root ?? process.cwd());
-  const filePath = path12.join(root, ".cnos-workspace.yml");
+  const root = path14.resolve(options.root ?? process.cwd());
+  const filePath = path14.join(root, ".cnos-workspace.yml");
   const current = await loadCliContext(root);
   const next = {
     ...current.workspace ? { workspace: current.workspace } : {},
@@ -2737,12 +3172,21 @@ async function saveCliContext(options = {}) {
 }
 
 // src/services/profiles.ts
-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";
+import { mkdir as mkdir5, readdir as readdir4, readFile as readFile5, 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";
+async function resolveProfilesRoot(root = process.cwd()) {
+  try {
+    const loadedManifest = await loadManifest5({ root });
+    return path15.join(loadedManifest.manifestRoot, "profiles");
+  } catch {
+    const loadedManifest = await loadManifest5({ cwd: root });
+    return path15.join(loadedManifest.manifestRoot, "profiles");
+  }
+}
 async function createProfileDefinition(root = process.cwd(), profile, inherit, options = {}) {
-  const filePath = path13.join(path13.resolve(root), ".cnos", "profiles", `${profile}.yml`);
-  await mkdir5(path13.dirname(filePath), { recursive: true });
+  const filePath = path15.join(await resolveProfilesRoot(root), `${profile}.yml`);
+  await mkdir5(path15.dirname(filePath), { recursive: true });
   const document = options.noInherit ? {
     name: profile,
     activate: {
@@ -2765,9 +3209,9 @@ async function createProfileDefinition(root = process.cwd(), profile, inherit, o
   };
 }
 async function listProfiles(root = process.cwd()) {
-  const profilesRoot = path13.join(path13.resolve(root), ".cnos", "profiles");
+  const profilesRoot = await resolveProfilesRoot(root);
   try {
-    const entries = await readdir3(profilesRoot, { withFileTypes: true });
+    const entries = await readdir4(profilesRoot, { withFileTypes: true });
     const discovered = /* @__PURE__ */ new Set(["base"]);
     for (const entry of entries) {
       if (entry.isFile() && entry.name.endsWith(".yml")) {
@@ -2780,9 +3224,9 @@ async function listProfiles(root = process.cwd()) {
   }
 }
 async function deleteProfileDefinition(root = process.cwd(), profile) {
-  const filePath = path13.join(path13.resolve(root), ".cnos", "profiles", `${profile}.yml`);
+  const filePath = path15.join(await resolveProfilesRoot(root), `${profile}.yml`);
   try {
-    await rm2(filePath);
+    await rm3(filePath);
     return {
       filePath,
       deleted: true
@@ -2800,7 +3244,7 @@ async function readProfileDefinition(root = process.cwd(), profile = "base") {
       name: "base"
     };
   }
-  const filePath = path13.join(path13.resolve(root), ".cnos", "profiles", `${profile}.yml`);
+  const filePath = path15.join(await resolveProfilesRoot(root), `${profile}.yml`);
   try {
     return parseYaml4(await readFile5(filePath, "utf8")) ?? void 0;
   } catch {
@@ -2824,9 +3268,11 @@ function normalizeProfileAction(args) {
 }
 async function runProfile(args, options = {}) {
   const { action, tail } = normalizeProfileAction(args);
-  const root = path14.resolve(options.root ?? process.cwd());
+  const root = options.root ?? process.cwd();
+  const displayRoot = resolveFilesystemBasePath(options.root, options.cwd ?? process.cwd());
   const cliArgs = [...options.cliArgs ?? []];
   if (action === "create") {
+    await assertWritableConfigRoot(`create profile ${tail[0] ?? "stage"}`, options);
     const profile = tail[0] ?? "stage";
     const inherit = consumeOption(cliArgs, "--inherit");
     const noInherit = consumeFlag(cliArgs, "--no-inherit");
@@ -2838,22 +3284,23 @@ async function runProfile(args, options = {}) {
       return printJson(result);
     }
     if (noInherit) {
-      return `created profile ${profile} at ${displayPath(result.filePath, root)} without inheriting base`;
+      return `created profile ${profile} at ${displayPath(result.filePath, displayRoot)} without inheriting base`;
     }
-    return `created profile ${profile} at ${displayPath(result.filePath, root)}; inherits values from base by default`;
+    return `created profile ${profile} at ${displayPath(result.filePath, displayRoot)}; inherits values from base by default`;
   }
   if (action === "use") {
     const profile = tail[0] ?? "base";
     const result = await saveCliContext({
-      root,
+      root: path16.resolve(root),
       profile
     });
     if (options.json) {
       return printJson(result);
     }
-    return `active profile set to ${profile} in ${displayPath(result.filePath, root)}`;
+    return `active profile set to ${profile} in ${displayPath(result.filePath, displayRoot)}`;
   }
   if (action === "delete") {
+    await assertWritableConfigRoot(`delete profile ${tail[0] ?? "base"}`, options);
     const profile = tail[0] ?? "base";
     const result = await deleteProfileDefinition(root, profile);
     if (options.json) {
@@ -2875,11 +3322,11 @@ async function runProfile(args, options = {}) {
 }
 
 // src/commands/promote.ts
-import path15 from "path";
+import path17 from "path";
 import { writeFile as writeFile7 } from "fs/promises";
 import {
   ensureProjectionAllowed,
-  loadManifest as loadManifest2,
+  loadManifest as loadManifest6,
   stringifyYaml as stringifyYaml5
 } from "@kitsy/cnos/internal";
 function normalizeTarget(value) {
@@ -2892,7 +3339,7 @@ function sortRecord(record) {
   return Object.fromEntries(Object.entries(record).sort(([left], [right]) => left.localeCompare(right)));
 }
 async function runPromote(args = [], options = {}) {
-  const root = path15.resolve(options.root ?? process.cwd());
+  const root = path17.resolve(options.root ?? process.cwd());
   const cliArgs = [...options.cliArgs ?? []];
   const target = normalizeTarget(consumeOption(cliArgs, "--to"));
   const alias = consumeOption(cliArgs, "--as");
@@ -2908,7 +3355,15 @@ async function runPromote(args = [], options = {}) {
       throw new Error("promote --to env requires --as <ENV_VAR>");
     }
   }
-  const loadedManifest = await loadManifest2(options.root ? { root: options.root } : {});
+  const loadedManifest = await loadManifest6({
+    ...options.root ? { root: options.root } : {},
+    ...options.cwd ? { cwd: options.cwd } : {},
+    ...options.processEnv ? { processEnv: options.processEnv } : {},
+    ...options.cacheMode ? { cacheMode: options.cacheMode } : {},
+    ...typeof options.cacheTtlSeconds === "number" ? { cacheTtlSeconds: options.cacheTtlSeconds } : {},
+    ...options.forceRefresh ? { forceRefresh: true } : {}
+  });
+  await assertWritableConfigRoot(`promote ${keys.join(", ")}`, options);
   for (const key of keys) {
     ensureProjectionAllowed(loadedManifest.manifest, key, target);
   }
@@ -3053,21 +3508,21 @@ async function runCommand(command, options = {}) {
 }
 
 // src/commands/secret.ts
-import path18 from "path";
+import path20 from "path";
 
 // src/commands/vault.ts
-import path17 from "path";
+import path19 from "path";
 
 // src/services/vaults.ts
-import { rm as rm3, writeFile as writeFile8 } from "fs/promises";
-import path16 from "path";
+import { rm as rm4, writeFile as writeFile8 } from "fs/promises";
+import path18 from "path";
 import {
   clearAllVaultSessionKeys,
   clearVaultSessionKey,
   createSecretVault,
   deriveVaultKey,
   listLocalSecrets,
-  loadManifest as loadManifest3,
+  loadManifest as loadManifest7,
   listSecretVaults,
   readVaultMetadata,
   resolveSecretStoreRoot as resolveSecretStoreRoot2,
@@ -3100,12 +3555,20 @@ function defaultLocalAuthSources(vault) {
   return [`env:CNOS_SECRET_PASSPHRASE_${token}`, "env:CNOS_SECRET_PASSPHRASE", `keychain:cnos/${vault}`, "prompt"];
 }
 async function createVaultDefinition(name, options = {}) {
+  await assertWritableConfigRoot(`create vault ${name}`, options);
   const vault = name.trim() || "default";
   const provider = options.provider?.trim() || "local";
   if (provider === "local" && (options.noPassphrase ?? false)) {
     throw new Error("Local vaults cannot be passwordless.");
   }
-  const loadedManifest = await loadManifest3(options.root ? { root: options.root } : {});
+  const loadedManifest = await loadManifest7({
+    ...options.root ? { root: options.root } : {},
+    ...options.cwd ? { cwd: options.cwd } : {},
+    ...options.processEnv ? { processEnv: options.processEnv } : {},
+    ...options.cacheMode ? { cacheMode: options.cacheMode } : {},
+    ...typeof options.cacheTtlSeconds === "number" ? { cacheTtlSeconds: options.cacheTtlSeconds } : {},
+    ...options.forceRefresh ? { forceRefresh: true } : {}
+  });
   const vaultDefinition = buildVaultDefinition(vault, provider);
   const rawManifest = {
     ...loadedManifest.rawManifest,
@@ -3135,7 +3598,14 @@ async function createVaultDefinition(name, options = {}) {
   };
 }
 async function listVaultDefinitions(options = {}) {
-  const loadedManifest = await loadManifest3(options.root ? { root: options.root } : {});
+  const loadedManifest = await loadManifest7({
+    ...options.root ? { root: options.root } : {},
+    ...options.cwd ? { cwd: options.cwd } : {},
+    ...options.processEnv ? { processEnv: options.processEnv } : {},
+    ...options.cacheMode ? { cacheMode: options.cacheMode } : {},
+    ...typeof options.cacheTtlSeconds === "number" ? { cacheTtlSeconds: options.cacheTtlSeconds } : {},
+    ...options.forceRefresh ? { forceRefresh: true } : {}
+  });
   const localStoreVaults = await listSecretVaults(resolveSecretStoreRoot2(options.processEnv));
   return Object.keys(loadedManifest.manifest.vaults).sort((left, right) => left.localeCompare(right)).map((name) => {
     const definition = resolveVaultDefinition(loadedManifest.manifest.vaults, name);
@@ -3147,8 +3617,16 @@ async function listVaultDefinitions(options = {}) {
   });
 }
 async function removeVaultDefinition(name, options = {}) {
+  await assertWritableConfigRoot(`remove vault ${name}`, options);
   const vault = name.trim() || "default";
-  const loadedManifest = await loadManifest3(options.root ? { root: options.root } : {});
+  const loadedManifest = await loadManifest7({
+    ...options.root ? { root: options.root } : {},
+    ...options.cwd ? { cwd: options.cwd } : {},
+    ...options.processEnv ? { processEnv: options.processEnv } : {},
+    ...options.cacheMode ? { cacheMode: options.cacheMode } : {},
+    ...typeof options.cacheTtlSeconds === "number" ? { cacheTtlSeconds: options.cacheTtlSeconds } : {},
+    ...options.forceRefresh ? { forceRefresh: true } : {}
+  });
   if (!loadedManifest.rawManifest.vaults?.[vault]) {
     return {
       name: vault,
@@ -3166,10 +3644,10 @@ async function removeVaultDefinition(name, options = {}) {
     delete rawManifest.vaults;
   }
   await writeFile8(loadedManifest.manifestPath, stringifyYaml6(rawManifest), "utf8");
-  const vaultRoot = path16.join(resolveSecretStoreRoot2(options.processEnv), "vaults", vault);
+  const vaultRoot = path18.join(resolveSecretStoreRoot2(options.processEnv), "vaults", vault);
   let removedStore;
   try {
-    await rm3(vaultRoot, { recursive: true, force: true });
+    await rm4(vaultRoot, { recursive: true, force: true });
     removedStore = vaultRoot;
   } catch {
     removedStore = void 0;
@@ -3187,7 +3665,14 @@ async function listLocalStoreVaults(options = {}) {
 }
 async function authenticateVault(name, options = {}) {
   const vault = name.trim() || "default";
-  const loadedManifest = await loadManifest3(options.root ? { root: options.root } : {});
+  const loadedManifest = await loadManifest7({
+    ...options.root ? { root: options.root } : {},
+    ...options.cwd ? { cwd: options.cwd } : {},
+    ...options.processEnv ? { processEnv: options.processEnv } : {},
+    ...options.cacheMode ? { cacheMode: options.cacheMode } : {},
+    ...typeof options.cacheTtlSeconds === "number" ? { cacheTtlSeconds: options.cacheTtlSeconds } : {},
+    ...options.forceRefresh ? { forceRefresh: true } : {}
+  });
   const definition = loadedManifest.manifest.vaults[vault];
   if (!definition) {
     throw new Error(`Unknown vault "${vault}"`);
@@ -3260,7 +3745,7 @@ function normalizeVaultAction(args) {
 async function runVault(args = [], options = {}) {
   const { action, tail } = normalizeVaultAction(args);
   const cliArgs = [...options.cliArgs ?? []];
-  const root = path17.resolve(options.root ?? process.cwd());
+  const root = path19.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.");
   }
@@ -3366,7 +3851,7 @@ async function runSecret(argsOrPath, options = {}) {
   const args = Array.isArray(argsOrPath) ? argsOrPath : [argsOrPath];
   const { action, tail } = normalizeSecretCommand(args);
   const cliArgs = [...options.cliArgs ?? []];
-  const root = path18.resolve(options.root ?? process.cwd());
+  const root = path20.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.");
   }
@@ -3462,9 +3947,9 @@ async function runSecret(argsOrPath, options = {}) {
 }
 
 // src/commands/use.ts
-import path19 from "path";
+import path21 from "path";
 async function runUse(args = [], options = {}) {
-  const root = path19.resolve(options.root ?? process.cwd());
+  const root = path21.resolve(options.root ?? process.cwd());
   const action = args[0];
   const hasUpdates = Boolean(options.workspace || options.profile || options.globalRoot);
   if (action === "show" || !action && !hasUpdates) {
@@ -3501,7 +3986,7 @@ async function runValidate(options = {}) {
 // package.json
 var package_default = {
   name: "@kitsy/cnos-cli",
-  version: "1.6.1",
+  version: "1.8.0",
   description: "CLI entry point and developer tooling for CNOS.",
   type: "module",
   main: "./dist/index.js",
@@ -3556,7 +4041,7 @@ function runVersion() {
 }
 
 // src/commands/value.ts
-import path20 from "path";
+import path22 from "path";
 function normalizeValueCommand(args) {
   const [actionOrPath, ...tail] = args;
   if (!actionOrPath) {
@@ -3580,7 +4065,7 @@ async function runValue(argsOrPath, options = {}) {
   const args = Array.isArray(argsOrPath) ? argsOrPath : [argsOrPath];
   const { action, tail } = normalizeValueCommand(args);
   const cliArgs = [...options.cliArgs ?? []];
-  const root = path20.resolve(options.root ?? process.cwd());
+  const root = path22.resolve(options.root ?? process.cwd());
   if (action === "list") {
     const prefix = consumeOption(cliArgs, "--prefix");
     const entries = await listConfigEntries("value", {
@@ -3591,16 +4076,24 @@ async function runValue(argsOrPath, options = {}) {
     if (options.json) {
       return printJson(entries);
     }
-    return entries.map((entry) => `${entry.key}=${printValue(entry.value)}`).join("\n");
+    return entries.map((entry) => `${entry.key}=${printValue(entry.value)}${entry.derived ? "  (derived)" : ""}`).join("\n");
   }
   if (action === "set") {
     const valuePath = tail[0] ?? "app.name";
-    const rawValue = tail[1] ?? "";
+    const derive = consumeFlag(cliArgs, "--derive");
+    const expr = consumeOption(cliArgs, "--expr");
+    const deriveArg = derive && !expr && cliArgs[0] && !cliArgs[0].startsWith("--") ? cliArgs.shift() : void 0;
+    const rawValue = derive ? "" : tail[1] ?? "";
+    const deriveExpression = derive ? expr ?? tail[1] ?? deriveArg ?? "" : void 0;
     const target = consumeOption(cliArgs, "--target") ?? "local";
     const result = await defineValue("value", valuePath, rawValue, {
       ...options,
       cliArgs,
-      target
+      target,
+      ...deriveExpression !== void 0 ? {
+        deriveExpression,
+        deriveExprMode: Boolean(expr)
+      } : {}
     });
     if (options.json) {
       return printJson({
@@ -3656,6 +4149,7 @@ async function buildRunEnvironment(options) {
   const prefix = consumeOption(cliArgs, "--prefix");
   const runtime = await createRuntimeService({
     ...options,
+    cacheMode: "dev",
     cliArgs
   });
   const authenticatedSecrets = isAuthenticated ? Object.fromEntries(
@@ -3697,12 +4191,14 @@ async function startWatchLoop(options) {
   const root = options.root ?? process.cwd();
   let current = await buildRunEnvironment({
     ...options,
+    cacheMode: "dev",
     cliArgs
   });
   let child = !isSignal ? spawnWatchedChild(command, root, current.env) : void 0;
   let closed = false;
   const watcher = await startGraphWatchLoop({
     ...options,
+    cacheMode: "dev",
     cliArgs,
     debounceMs,
     async onChange(payload) {
@@ -3711,6 +4207,7 @@ async function startWatchLoop(options) {
       }
       current = await buildRunEnvironment({
         ...options,
+        cacheMode: "dev",
         cliArgs
       });
       if (isSignal) {
@@ -3764,12 +4261,12 @@ async function runWatch(command, options = {}) {
 }
 
 // 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";
+import { cp, mkdir as mkdir6, readdir as readdir5, readFile as readFile6, rename, rm as rm5, stat as stat2, 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) {
   try {
-    await stat(targetPath);
+    await stat2(targetPath);
     return true;
   } catch {
     return false;
@@ -3779,25 +4276,37 @@ async function copyIfExists(source, target) {
   if (!await exists(source)) {
     return;
   }
-  await mkdir6(path21.dirname(target), { recursive: true });
+  await mkdir6(path23.dirname(target), { recursive: true });
   await cp(source, target, { recursive: true, force: true });
 }
+async function moveIfExists(source, target, force = false) {
+  if (!await exists(source)) {
+    return false;
+  }
+  if (force) {
+    await rm5(target, { recursive: true, force: true });
+  } else if (await exists(target)) {
+    throw new Error(`Refusing to overwrite existing path ${target}. Use --force to replace it.`);
+  }
+  await mkdir6(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(
-        path21.join(sourceRoot, folderName),
-        path21.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(
-    path21.join(packageRoot, ".cnosrc.yml"),
+    path23.join(packageRoot, ".cnosrc.yml"),
     stringifyYaml7({
-      root: config.root,
-      ...config.workspace ? { workspace: config.workspace } : {}
+      root: rootValue,
+      ...workspace ? { workspace } : {}
     }),
     "utf8"
   );
@@ -3809,18 +4318,48 @@ 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;
+  }
+  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 exists(folder)) {
+      continue;
+    }
+    const entries = await readdir5(folder, { withFileTypes: true });
+    if (entries.some((entry) => entry.name !== ".gitkeep")) {
+      return true;
+    }
+  }
+  return false;
+}
 async function runDetach(packageRoot, options = {}) {
-  const loaded = await loadManifest4({ cwd: packageRoot });
+  const loaded = await loadManifest8({ 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 targetCnosRoot = path23.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 });
+    await rm5(targetCnosRoot, { recursive: true, force: true });
   }
   const runtime = await createRuntimeService({
     ...options,
@@ -3831,11 +4370,11 @@ async function runDetach(packageRoot, options = {}) {
   await mkdir6(targetCnosRoot, { recursive: true });
   await mergeWorkspaceRootsIntoStandalone(targetCnosRoot, localRoots);
   await writeFile9(
-    path21.join(targetCnosRoot, "cnos.yml"),
+    path23.join(targetCnosRoot, "cnos.yml"),
     stringifyYaml7(createDetachedManifest(loaded.rawManifest)),
     "utf8"
   );
-  const relativeRoot = path21.relative(packageRoot, loaded.manifestRoot).replace(/\\/g, "/");
+  const relativeRoot = path23.relative(packageRoot, loaded.manifestRoot).replace(/\\/g, "/");
   const marker = {
     detachedFrom: relativeRoot || ".",
     detachedWorkspace: loaded.anchoredWorkspace,
@@ -3845,8 +4384,8 @@ async function runDetach(packageRoot, options = {}) {
       workspace: loaded.anchoredWorkspace
     }
   };
-  await writeFile9(path21.join(targetCnosRoot, ".detached"), stringifyYaml7(marker), "utf8");
-  await writeCnosrc(packageRoot, { root: "./.cnos" });
+  await writeFile9(path23.join(targetCnosRoot, ".detached"), stringifyYaml7(marker), "utf8");
+  await writeFile9(path23.join(packageRoot, ".cnosrc.yml"), stringifyYaml7({ root: "./.cnos" }), "utf8");
   if (options.json) {
     return printJson({
       packageRoot,
@@ -3859,8 +4398,8 @@ async function runDetach(packageRoot, options = {}) {
 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");
+  const childCnosRoot = path23.join(packageRoot, ".cnos");
+  const markerPath = path23.join(childCnosRoot, ".detached");
   if (!await exists(markerPath)) {
     throw new Error("workspace attach requires a detached package with .cnos/.detached");
   }
@@ -3868,34 +4407,36 @@ async function runAttach(packageRoot, options = {}) {
   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 parentManifestRoot = path23.resolve(packageRoot, marker.originalCnosrc.root);
+  const parentLoaded = await loadManifest8({ 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}).`
+    );
+  }
   const workspaceId = marker.originalCnosrc.workspace ?? marker.detachedWorkspace;
-  const parentWorkspaceRoot = path21.join(parentLoaded.manifestRoot, "workspaces", workspaceId);
+  const parentWorkspaceRoot = path23.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 rm5(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));
+    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] ?? {};
   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 writeFile9(path23.join(parentLoaded.manifestRoot, "cnos.yml"), stringifyYaml7(rawManifest), "utf8");
+  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,
@@ -3906,15 +4447,168 @@ 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 loadManifest8({
+    ...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 runAddOrScaffold(action, workspaceId, manifestCwd, packageRoot, options = {}) {
   const cliArgs = [...options.cliArgs ?? []];
-  const packageRoot = path21.resolve(consumeOption(cliArgs, "--package-root") ?? options.root ?? process.cwd());
+  const extendsOption = splitExtends(consumeOption(cliArgs, "--extends"));
+  const onboardCurrent = consumeFlag(cliArgs, "--onboard-current");
+  const force = consumeFlag(cliArgs, "--force");
+  if (cliArgs.length > 0) {
+    throw new Error(`Unsupported workspace arguments: ${cliArgs.join(" ")}`);
+  }
+  const loaded = await loadManifest8({
+    ...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 && !onboardCurrent) {
+    throw new Error(
+      "This CNOS root is in single-root mode and already has direct values/secrets/env/profiles data. Re-run with --onboard-current to migrate it 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);
+  if (onboardCurrent) {
+    if (isWorkspaceMode) {
+      throw new Error("--onboard-current can only be used when the manifest is not already in workspace mode.");
+    }
+    for (const folderName of ["values", "secrets", "env", "profiles"]) {
+      await moveIfExists(path23.join(cnosRoot, folderName), path23.join(workspaceRoot, folderName), force);
+    }
+  }
+  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 ensureFile(path23.join(packageRoot, ".cnos-workspace.yml"), `workspace: ${workspaceId}
+globalRoot: ~/.cnos
+`);
+  const result = {
+    workspace: workspaceId,
+    root: path23.dirname(cnosRoot),
+    packageRoot,
+    onboarded: onboardCurrent,
+    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 ?? []];
+  consumeFlag(cliArgs, "--force");
+  if (cliArgs.length > 0) {
+    throw new Error(`Unsupported workspace arguments: ${cliArgs.join(" ")}`);
+  }
+  const loaded = await loadManifest8({
+    ...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 "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)"}`);
   }
@@ -3934,12 +4628,15 @@ function resolveHelpTopic(command, args) {
   if (command === "build" && args[0] && ["env", "server", "browser", "public"].includes(args[0])) {
     return normalizeHelpTopic([command, args[0]]);
   }
-  if (command === "dev" && args[0] === "env") {
+  if (command === "cache" && args[0] && ["list", "clear", "refresh"].includes(args[0])) {
     return normalizeHelpTopic([command, args[0]]);
   }
-  if (command === "workspace" && args[0] && ["attach", "detach"].includes(args[0])) {
+  if (command === "dev" && args[0] === "env") {
     return normalizeHelpTopic([command, args[0]]);
   }
+  if (command === "workspace" && args[0] && ["attach", "detach", "add", "list", "remove", "delete", "scaffold"].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]]);
   }
@@ -3983,6 +4680,9 @@ async function main(argv) {
     ...options.globalRoot ? {
       globalRoot: options.globalRoot
     } : {},
+    ...typeof options.cacheTtlSeconds === "number" ? {
+      cacheTtlSeconds: options.cacheTtlSeconds
+    } : {},
     ...options.json ? {
       json: true
     } : {},
@@ -4074,6 +4774,10 @@ async function main(argv) {
       return;
     case "build":
       process.stdout.write(`${await runBuild(args[0], runtimeOptions)}
+`);
+      return;
+    case "cache":
+      process.stdout.write(`${await runCache(args, runtimeOptions)}
 `);
       return;
     case "dev":