@pleri/olam-cli 0.1.166 → 0.1.167

package/dist/index.js

@@ -5397,7 +5397,7 @@ var init_client = __esm({
     "use strict";
     init_secret();
     DEFAULT_BASE_URL = "http://127.0.0.1:9999";
-    DEFAULT_TIMEOUT_MS = 3e3;
+    DEFAULT_TIMEOUT_MS = 1e4;
     RETRY_COUNT = 2;
     RETRY_BACKOFF_MS = 250;
     AuthClient = class {
@@ -7884,6 +7884,38 @@ function hasImageRef(present, ref) {
   const variants = [`docker.io/library/${ref}`, `docker.io/${ref}`];
   return variants.some((v) => present.has(v));
 }
+async function probeKubectl(exec = defaultDockerExec) {
+  const r = exec("kubectl", ["version", "--client", "--output=json"]);
+  if (r.status === 0 && r.stdout.length > 0) {
+    let clientVersion = "unknown";
+    try {
+      const parsed = JSON.parse(r.stdout);
+      const clientInfo = parsed.clientVersion;
+      if (typeof clientInfo?.gitVersion === "string") {
+        clientVersion = clientInfo.gitVersion;
+      }
+    } catch {
+    }
+    return { ok: true, message: `kubectl ${clientVersion} on PATH` };
+  }
+  return {
+    ok: false,
+    message: "kubectl not found on PATH",
+    remedy: "Install kubectl: macOS: `brew install kubectl`; Linux: https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/"
+  };
+}
+async function probeK3d(exec = defaultDockerExec) {
+  const r = exec("k3d", ["version"]);
+  if (r.status === 0 && r.stdout.length > 0) {
+    const versionLine = r.stdout.trim().split("\n")[0] ?? "";
+    return { ok: true, message: `k3d ${versionLine} on PATH` };
+  }
+  return {
+    ok: false,
+    message: "k3d not found on PATH",
+    remedy: "Install k3d: `brew install k3d` (macOS) or curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash"
+  };
+}
 var HEALTH_TIMEOUT_MS, COLIMA_010_WARN_TEXT, COLIMA_010_RANGE, defaultDockerExec, defaultFetch;
 var init_health_probes = __esm({
   "src/lib/health-probes.ts"() {
@@ -11067,7 +11099,19 @@ var init_schema3 = __esm({
        * use canonical names; `olam flywheel migrate-overlays --push` enforces
        * this via the reverse validator.
        */
-      prefix: external_exports.string().regex(PREFIX_PATTERN, "skill-source prefix must be ASCII lowercase + digits + dash/underscore (1-39 chars, no leading/trailing dash)").optional()
+      prefix: external_exports.string().regex(PREFIX_PATTERN, "skill-source prefix must be ASCII lowercase + digits + dash/underscore (1-39 chars, no leading/trailing dash)").optional(),
+      /**
+       * Which artifact kinds get renamed when `prefix` is set. Optional; defaults
+       * to `['skill', 'agent']` for back-compat with the original Phase A semantic
+       * (Decision 6 in docs/decisions/019-skill-prefix-rules.md). Operators who
+       * want to rebrand ONLY skills (keeping `@architect` etc. canonical) set
+       * `['skill']`; ones who want only agents set `['agent']`.
+       *
+       * Empty array `[]` = same as omitting `prefix` entirely (no renaming).
+       *
+       * NOT applicable when `prefix` is undefined.
+       */
+      prefixScope: external_exports.array(external_exports.enum(["skill", "agent"])).optional()
     });
   }
 });
@@ -16413,29 +16457,26 @@ function updateSkillSource(id, patch) {
     }
   }
   const existing = config.skillSources[idx];
-  let prefixUpdate = {};
+  let working = { ...existing };
   if (patch.prefix === null) {
-    const { prefix: _dropped, ...rest } = existing;
-    void _dropped;
-    const updated2 = {
-      ...rest,
-      ...patch.name !== void 0 ? { name: patch.name } : {},
-      ...patch.branch !== void 0 ? { branch: patch.branch } : {},
-      ...patch.lastPulledSha !== void 0 ? { lastPulledSha: patch.lastPulledSha } : {}
-    };
-    const next2 = [...config.skillSources];
-    next2[idx] = updated2;
-    writeGlobalConfig({ ...config, skillSources: next2 });
-    return updated2;
+    const { prefix: _p, ...rest } = working;
+    void _p;
+    working = rest;
   } else if (patch.prefix !== void 0) {
-    prefixUpdate = { prefix: patch.prefix };
+    working = { ...working, prefix: patch.prefix };
+  }
+  if (patch.prefixScope === null) {
+    const { prefixScope: _s, ...rest } = working;
+    void _s;
+    working = rest;
+  } else if (patch.prefixScope !== void 0) {
+    working = { ...working, prefixScope: [...patch.prefixScope] };
   }
   const updated = {
-    ...existing,
+    ...working,
     ...patch.name !== void 0 ? { name: patch.name } : {},
     ...patch.branch !== void 0 ? { branch: patch.branch } : {},
-    ...patch.lastPulledSha !== void 0 ? { lastPulledSha: patch.lastPulledSha } : {},
-    ...prefixUpdate
+    ...patch.lastPulledSha !== void 0 ? { lastPulledSha: patch.lastPulledSha } : {}
   };
   const next = [...config.skillSources];
   next[idx] = updated;
@@ -17249,7 +17290,7 @@ function detectCollisions(artifacts) {
   }
   return { winners, collisions };
 }
-function cleanManagedSymlinks(claude, installedOlamVersion, overlayReferences) {
+function cleanManagedSymlinks(claude, installedOlamVersion, overlayReferences, expectedAgentWinnerNames) {
   const shadowBackups = [];
   for (const bucket of BUCKETS) {
     const dir = path59.join(claude, bucket);
@@ -17283,8 +17324,11 @@ function cleanManagedSymlinks(claude, installedOlamVersion, overlayReferences) {
           }
           fs58.unlinkSync(p);
         } else if (bucket === "agents" && stat.isFile() && !name.includes(".shadow-backup-")) {
-          const backup3 = shadowBackup(p);
-          shadowBackups.push(backup3);
+          const hasWinner = expectedAgentWinnerNames !== void 0 ? expectedAgentWinnerNames.has(name) : true;
+          if (hasWinner) {
+            const backup3 = shadowBackup(p);
+            shadowBackups.push(backup3);
+          }
         }
       } catch {
       }
@@ -17324,8 +17368,9 @@ function deployArtifacts(artifacts, opts) {
   for (const bucket of BUCKETS) {
     fs58.mkdirSync(path59.join(claude, bucket), { recursive: true });
   }
-  const sweepShadowBackups = cleanManagedSymlinks(claude, opts?.installedOlamVersion, opts?.overlayReferences);
   const { winners, collisions } = detectCollisions(artifacts);
+  const expectedAgentWinnerNames = new Set(winners.filter((a) => a.kind === "agent").map((a) => a.deployBasename));
+  const sweepShadowBackups = cleanManagedSymlinks(claude, opts?.installedOlamVersion, opts?.overlayReferences, expectedAgentWinnerNames);
   const result = { linked: 0, shadowBackups: [...sweepShadowBackups], collisions };
   for (const artifact of winners) {
     const bucket = bucketFor(artifact.kind);
@@ -18860,15 +18905,18 @@ import * as fs68 from "node:fs";
 import * as path67 from "node:path";
 function buildSourcePrefixMap(sources) {
   const byId = /* @__PURE__ */ new Map();
+  const scopeById = /* @__PURE__ */ new Map();
   const prefixes = /* @__PURE__ */ new Set();
   for (const s of sources) {
     if (s.prefix !== void 0 && s.prefix.length > 0) {
       byId.set(s.id, s.prefix);
+      scopeById.set(s.id, s.prefixScope ?? DEFAULT_SCOPE);
       prefixes.add(s.prefix);
     }
   }
   return {
     get: (sourceId) => byId.get(sourceId),
+    getScope: (sourceId) => scopeById.get(sourceId) ?? DEFAULT_SCOPE,
     registeredPrefixes: Array.from(prefixes)
   };
 }
@@ -18880,6 +18928,9 @@ function applyPrefixRewrites(baseArtifacts, sourceMap, claudeDir2, dryRun) {
     const prefix = sourceMap.get(artifact.sourceId);
     if (prefix === void 0)
       continue;
+    const scope = sourceMap.getScope(artifact.sourceId);
+    if (!scope.includes(artifact.kind))
+      continue;
     const canonical = artifact.deployBasename;
     const otherPrefixes = sourceMap.registeredPrefixes.filter((p) => p !== prefix);
     const renamed = applyPrefix(canonical, prefix, otherPrefixes);
@@ -18946,11 +18997,13 @@ function detectPrefixCollisions(sources) {
   }
   return collisions;
 }
+var DEFAULT_SCOPE;
 var init_prefix_deploy = __esm({
   "../core/dist/skill-sync/prefix-deploy.js"() {
     "use strict";
     init_prefix_rules();
     init_managed_merge();
+    DEFAULT_SCOPE = ["skill", "agent"];
   }
 });
 
@@ -19940,7 +19993,7 @@ __export(project_sweep_exports, {
   walkProjectRoot: () => walkProjectRoot
 });
 import * as path72 from "node:path";
-import { readdirSync as readdirSync24, lstatSync as lstatSync6, statSync as statSync25, existsSync as existsSync81 } from "node:fs";
+import { readdirSync as readdirSync25, lstatSync as lstatSync6, statSync as statSync25, existsSync as existsSync81 } from "node:fs";
 function isSkipped(basename16, extra) {
   if (DEFAULT_SKIP.has(basename16))
     return true;
@@ -20004,7 +20057,7 @@ function walk2(currentPath, depth, maxDepth, extraExclude, fsAdapter, results) {
 }
 function makeRealFsAdapter() {
   return {
-    readdirSync: (p) => readdirSync24(p, { encoding: "utf-8" }),
+    readdirSync: (p) => readdirSync25(p, { encoding: "utf-8" }),
     // lstatSync does NOT follow symlinks — used for descent decisions.
     lstatSync: (p) => {
       const s = lstatSync6(p, { throwIfNoEntry: true });
@@ -20188,6 +20241,7 @@ init_output();
 import * as fs6 from "node:fs";
 import * as path6 from "node:path";
 import { execSync } from "node:child_process";
+import { randomUUID as randomUUID2 } from "node:crypto";
 import pc3 from "picocolors";
 
 // src/commands/workspace.ts
@@ -20442,9 +20496,11 @@ function writeConfig(updates, opts = {}) {
 
 // src/commands/init.ts
 function detectProjectType(root) {
-  if (fs6.existsSync(path6.join(root, "Gemfile")) || fs6.existsSync(path6.join(root, "config", "routes.rb"))) return "rails";
+  if (fs6.existsSync(path6.join(root, "Gemfile")) || fs6.existsSync(path6.join(root, "config", "routes.rb")))
+    return "rails";
   if (fs6.existsSync(path6.join(root, "package.json"))) return "node";
-  if (fs6.existsSync(path6.join(root, "pyproject.toml")) || fs6.existsSync(path6.join(root, "requirements.txt"))) return "python";
+  if (fs6.existsSync(path6.join(root, "pyproject.toml")) || fs6.existsSync(path6.join(root, "requirements.txt")))
+    return "python";
   return "generic";
 }
 function getRepoName(root) {
@@ -20461,7 +20517,9 @@ function getRepoName(root) {
 }
 function detectK3dOlamContexts(execFn = (cmd, opts) => execSync(cmd, opts)) {
   try {
-    const raw = execFn("kubectl config get-contexts -o name", { encoding: "utf-8" });
+    const raw = execFn("kubectl config get-contexts -o name", {
+      encoding: "utf-8"
+    });
     const contexts = raw.split("\n").map((l) => l.trim()).filter((l) => /^k3d-olam-/.test(l));
     return { contexts };
   } catch {
@@ -20472,11 +20530,14 @@ function applyKubectlContextPin(contexts, opts = {}) {
   const configPath = opts.configPath ?? OLAM_CONFIG_PATH;
   const readFn = opts.readFileSyncFn ?? fs6.readFileSync;
   const writeFn = opts.writeFileSyncFn ?? fs6.writeFileSync;
+  const mkdirFn = opts.mkdirSyncFn ?? fs6.mkdirSync;
   if (contexts.length === 0) {
     return { skipped: "no ^k3d-olam- contexts found" };
   }
   if (contexts.length > 1) {
-    return { refused: `multiple ^k3d-olam- contexts found: ${contexts.join(", ")} \u2014 set host.kubectl_context_pinned manually` };
+    return {
+      refused: `multiple ^k3d-olam- contexts found: ${contexts.join(", ")} \u2014 set host.kubectl_context_pinned manually`
+    };
   }
   const context = contexts[0];
   let parsed = {};
@@ -20484,17 +20545,26 @@ function applyKubectlContextPin(contexts, opts = {}) {
     const raw = readFn(configPath, "utf8");
     parsed = JSON.parse(raw);
   } catch {
-    parsed = {};
+    parsed = {
+      "config.schema": 1,
+      host: { substrate: "kubernetes" },
+      install_id: randomUUID2()
+    };
   }
   const host = typeof parsed.host === "object" && parsed.host !== null ? parsed.host : {};
   if (typeof host["kubectl_context_pinned"] === "string" && host["kubectl_context_pinned"].length > 0) {
-    return { skipped: `kubectl_context_pinned already set to ${host["kubectl_context_pinned"]}` };
+    return {
+      skipped: `kubectl_context_pinned already set to ${host["kubectl_context_pinned"]}`
+    };
   }
   const next = {
     ...parsed,
     host: { ...host, kubectl_context_pinned: context }
   };
-  writeFn(configPath, JSON.stringify(next, null, 2) + "\n", { encoding: "utf8" });
+  mkdirFn(path6.dirname(configPath), { recursive: true });
+  writeFn(configPath, JSON.stringify(next, null, 2) + "\n", {
+    encoding: "utf8"
+  });
   return { pinned: context };
 }
 function findProjectRoot(startDir) {
@@ -20570,14 +20640,19 @@ function registerInit(program2) {
       printInfo("Project", `${projectType} (detected)`);
       printInfo("Repo", repoName);
       try {
-        const result = ensureProjectWorkspaceFromConfig(projectRoot, repoName);
+        const result = ensureProjectWorkspaceFromConfig(
+          projectRoot,
+          repoName
+        );
         if (result.created) {
           printInfo("Workspace", `${repoName} \u2192 ${result.file}`);
         } else {
           printInfo("Workspace", `${repoName} (already registered)`);
         }
       } catch (err) {
-        printError(`Workspace auto-register failed: ${err instanceof Error ? err.message : String(err)}`);
+        printError(
+          `Workspace auto-register failed: ${err instanceof Error ? err.message : String(err)}`
+        );
       }
       const { contexts } = detectK3dOlamContexts();
       if (contexts !== null) {
@@ -20585,12 +20660,16 @@ function registerInit(program2) {
         if ("pinned" in pinResult) {
           printInfo("kubectl context", `${pinResult.pinned} (auto-pinned)`);
         } else if ("refused" in pinResult) {
-          process.stderr.write(`${pc3.yellow("warn:")} ${pinResult.refused}
-`);
+          process.stderr.write(
+            `${pc3.yellow("warn:")} ${pinResult.refused}
+`
+          );
         }
       }
-      console.log(`
-${pc3.dim(`Next: olam create --name my-world --workspace ${repoName} --task "..."`)}`);
+      console.log(
+        `
+${pc3.dim(`Next: olam create --name my-world --workspace ${repoName} --task "..."`)}`
+      );
     } catch (err) {
       printError(err instanceof Error ? err.message : String(err));
       process.exitCode = 1;
@@ -20950,7 +21029,13 @@ import pc7 from "picocolors";
 init_output();
 init_install_root();
 import { spawnSync as spawnSync10 } from "node:child_process";
-import { existsSync as existsSync29, mkdirSync as mkdirSync19, writeFileSync as writeFileSync15, chmodSync as chmodSync4 } from "node:fs";
+import {
+  existsSync as existsSync29,
+  mkdirSync as mkdirSync19,
+  readdirSync as readdirSync9,
+  writeFileSync as writeFileSync15,
+  chmodSync as chmodSync4
+} from "node:fs";
 import { join as join34 } from "node:path";
 import { homedir as homedir19, platform } from "node:os";
 import { randomBytes as randomBytes7 } from "node:crypto";
@@ -21394,8 +21479,14 @@ var REQUIRED_TOOLS = [
   { name: "kubectl", brew: "kubectl" },
   { name: "helm", brew: "helm" },
   { name: "jq", brew: "jq" },
-  { name: "curl", hint: "expected on macOS by default; `apt install curl` on linux" },
-  { name: "openssl", hint: "expected on macOS by default; `apt install openssl` on linux" },
+  {
+    name: "curl",
+    hint: "expected on macOS by default; `apt install curl` on linux"
+  },
+  {
+    name: "openssl",
+    hint: "expected on macOS by default; `apt install openssl` on linux"
+  },
   { name: "gh", brew: "gh", hint: "after install: `gh auth login`" },
   { name: "docker", hint: "Docker Desktop, or colima on macOS" }
 ];
@@ -21413,7 +21504,10 @@ var OBSERVABILITY_SCRIPTS = [
   "kyverno-cardinality-mutate.sh"
 ];
 function hasTool(tool) {
-  const result = spawnSync10("command", ["-v", tool], { shell: true, stdio: "pipe" });
+  const result = spawnSync10("command", ["-v", tool], {
+    shell: true,
+    stdio: "pipe"
+  });
   return result.status === 0;
 }
 function detectMissingTools() {
@@ -21445,8 +21539,15 @@ function preflight(opts) {
   } else if (opts.autoInstall && platform() === "darwin") {
     const brewable = missing.filter((t) => t.brew);
     if (brewable.length > 0) {
-      printInfo("auto-install", `${brewable.length} brew formula(s): ${brewable.map((t) => t.brew).join(", ")}`);
-      runOrFail("brew", ["install", ...brewable.map((t) => t.brew)], "brew install");
+      printInfo(
+        "auto-install",
+        `${brewable.length} brew formula(s): ${brewable.map((t) => t.brew).join(", ")}`
+      );
+      runOrFail(
+        "brew",
+        ["install", ...brewable.map((t) => t.brew)],
+        "brew install"
+      );
     }
     const stillMissing = detectMissingTools();
     if (stillMissing.length > 0) {
@@ -21465,7 +21566,9 @@ function preflight(opts) {
       process.stderr.write(`  - ${pc6.bold(t.name)}: ${hint}
 `);
     }
-    process.stderr.write("\nRe-run with --auto-install on macOS to install brew-formulae automatically.\n");
+    process.stderr.write(
+      "\nRe-run with --auto-install on macOS to install brew-formulae automatically.\n"
+    );
     process.exit(1);
   }
   if (!runCapture("gh", ["auth", "status"]).ok) {
@@ -21501,16 +21604,33 @@ function ensureColima() {
     printWarning("colima not running \u2014 starting");
     runOrFail(
       "colima",
-      ["start", "--cpu", "4", "--memory", "8", "--vm-type=vz", "--mount-type=virtiofs"],
+      [
+        "start",
+        "--cpu",
+        "4",
+        "--memory",
+        "8",
+        "--vm-type=vz",
+        "--mount-type=virtiofs"
+      ],
       "colima start"
     );
   }
   printSuccess("colima running");
-  const chmod = runCapture("colima", ["ssh", "--", "sudo", "chmod", "666", "/var/run/docker.sock"]);
+  const chmod = runCapture("colima", [
+    "ssh",
+    "--",
+    "sudo",
+    "chmod",
+    "666",
+    "/var/run/docker.sock"
+  ]);
   if (chmod.ok) {
     printSuccess("docker.sock chmod applied inside colima VM");
   } else {
-    printWarning("colima ssh chmod failed \u2014 k3d cluster create may still succeed");
+    printWarning(
+      "colima ssh chmod failed \u2014 k3d cluster create may still succeed"
+    );
   }
 }
 function ensureCluster(opts) {
@@ -21526,14 +21646,25 @@ function ensureCluster(opts) {
   const ghConfigBind = `${homedir19()}/.config/gh:/host/.config/gh`;
   runOrFail(
     "k3d",
-    ["cluster", "create", opts.cluster, "--volume", ghConfigBind, "--wait", "--timeout", "90s"],
+    [
+      "cluster",
+      "create",
+      opts.cluster,
+      "--volume",
+      ghConfigBind,
+      "--wait",
+      "--timeout",
+      "90s"
+    ],
     `k3d cluster create ${opts.cluster}`
   );
   if (!runCapture("kubectl", ["cluster-info"]).ok) {
     printError("kubectl cannot reach the cluster \u2014 check kubeconfig context");
     process.exit(1);
   }
-  printSuccess(`cluster ready (${runCapture("kubectl", ["config", "current-context"]).stdout.trim()})`);
+  printSuccess(
+    `cluster ready (${runCapture("kubectl", ["config", "current-context"]).stdout.trim()})`
+  );
 }
 function resolveObservabilityScriptsDir() {
   const installed = join34(installRoot(), "host-cp", "observability");
@@ -21570,12 +21701,14 @@ function installObservability(opts) {
     step("4/6 \u2014 observability (skipped via --skip-observability)");
     return;
   }
-  step("4/6 \u2014 observability stack (Loki + Promtail + Grafana + Prometheus + Kyverno)");
+  step(
+    "4/6 \u2014 observability stack (Loki + Promtail + Grafana + Prometheus + Kyverno)"
+  );
   const observabilityDir = resolveObservabilityScriptsDir();
   if (!observabilityDir) {
-    printWarning("bundled observability scripts not found \u2014 skipping");
-    printWarning("  (expected in published CLI installs; missing only in dev tarballs without bundling)");
-    return;
+    throw new Error(
+      `Bundled observability assets missing. This indicates a corrupt or incomplete @pleri/olam-cli installation. Remediation: reinstall with 'npm install -g @pleri/olam-cli@latest', or open an issue at https://github.com/pleri/olam/issues with this error.`
+    );
   }
   const bundleRoot = resolveBundleRoot();
   const scriptEnv = { ...process.env };
@@ -21589,10 +21722,15 @@ function installObservability(opts) {
       continue;
     }
     printInfo("run", script);
-    const result = spawnSync10("bash", [path94], { stdio: "inherit", env: scriptEnv });
+    const result = spawnSync10("bash", [path94], {
+      stdio: "inherit",
+      env: scriptEnv
+    });
     if (result.status !== 0) {
       if (script === "loki-ingest.sh") {
-        printWarning("loki-ingest non-zero \u2014 likely Promtail scrub-wait flake; continuing");
+        printWarning(
+          "loki-ingest non-zero \u2014 likely Promtail scrub-wait flake; continuing"
+        );
       } else {
         printError(`${script} failed \u2014 observability stack not ready`);
         process.exit(1);
@@ -21603,7 +21741,9 @@ function installObservability(opts) {
   }
 }
 function applyPeripheralServicesManifests() {
-  step("5/6 \u2014 peripheral-services manifests (IngressRoutes + ServiceMonitors + recording rules + dashboards + Kyverno)");
+  step(
+    "5/6 \u2014 peripheral-services manifests (IngressRoutes + ServiceMonitors + recording rules + dashboards + Kyverno)"
+  );
   const dir = resolvePeripheralServicesDir();
   if (!dir) {
     printWarning("bundled peripheral-services manifests not found \u2014 skipping");
@@ -21611,21 +21751,38 @@ function applyPeripheralServicesManifests() {
   }
   const manifestsDir = join34(dir, "manifests");
   if (!existsSync29(manifestsDir)) {
-    printWarning(`peripheral-services/manifests not found at ${manifestsDir} \u2014 skipping`);
+    printWarning(
+      `peripheral-services/manifests not found at ${manifestsDir} \u2014 skipping`
+    );
     return;
   }
-  printInfo("apply", manifestsDir);
-  const result = spawnSync10("kubectl", ["apply", "-f", manifestsDir], { stdio: "inherit" });
-  if (result.status !== 0) {
-    printError("kubectl apply failed \u2014 peripheral-services manifests not applied");
-    process.exit(result.status ?? 1);
+  const manifestFiles = readdirSync9(manifestsDir).filter(
+    (f) => (f.endsWith(".yaml") || f.endsWith(".yml")) && !/deploy/i.test(f)
+  ).map((f) => join34(manifestsDir, f));
+  if (manifestFiles.length === 0) {
+    printWarning(
+      "no non-deployment peripheral-services manifests found \u2014 skipping"
+    );
+    return;
+  }
+  for (const manifest of manifestFiles) {
+    printInfo("apply", manifest.replace(manifestsDir + "/", ""));
+    const r = spawnSync10("kubectl", ["apply", "-f", manifest], {
+      stdio: "inherit"
+    });
+    if (r.status !== 0) {
+      printError(`kubectl apply failed for ${manifest}`);
+      process.exit(r.status ?? 1);
+    }
   }
   printSuccess("peripheral-services manifests applied");
 }
 function delegateToUpgrade() {
   step("6/6 \u2014 apply host-cp + peripherals + rollout (olam upgrade)");
   const olamBin = process.argv[1] ?? "olam";
-  const result = spawnSync10(process.execPath, [olamBin, "upgrade", "-y"], { stdio: "inherit" });
+  const result = spawnSync10(process.execPath, [olamBin, "upgrade", "-y"], {
+    stdio: "inherit"
+  });
   if (result.status !== 0) {
     printError("olam upgrade failed \u2014 see output above");
     process.exit(result.status ?? 1);
@@ -21657,7 +21814,10 @@ async function runBootstrapKubernetes(rawOpts) {
     skipClusterCreate: rawOpts.skipClusterCreate ?? false
   };
   printHeader("olam setup \u2014 k3s mode");
-  printInfo("mode", "one-command bring-up of olam peripherals + observability on a local k3d cluster");
+  printInfo(
+    "mode",
+    "one-command bring-up of olam peripherals + observability on a local k3d cluster"
+  );
   preflight(opts);
   ensureSecrets();
   ensureColima();
@@ -21750,6 +21910,9 @@ async function runBootstrap2(opts, deps = {}) {
   if (digests["kg-service"] && !opts.skipKgService) {
     imageRefs.push({ name: "kg-service", ref: `${registry}/olam-kg-service@${digests["kg-service"]}` });
   }
+  if (digests["memory-service"] && !opts.skipMemory) {
+    imageRefs.push({ name: "memory-service", ref: `${registry}/olam-memory-service@${digests["memory-service"]}` });
+  }
   if (digests["devbox-base"]) {
     imageRefs.push({
       name: "devbox-base",
@@ -21827,6 +21990,10 @@ async function runBootstrap2(opts, deps = {}) {
   if (kgServiceRef) {
     tagPlan.push({ name: "kg-service", from: kgServiceRef.ref, to: "olam-kg-service:local" });
   }
+  const memoryServiceRef = imageRefs.find((r) => r.name === "memory-service");
+  if (memoryServiceRef) {
+    tagPlan.push({ name: "memory-service", from: memoryServiceRef.ref, to: "olam-memory-service:local" });
+  }
   const devboxBaseRef = imageRefs.find((r) => r.name === "devbox-base");
   if (devboxBaseRef) {
     tagPlan.push({ name: "devbox-base (bare)", from: devboxBaseRef.ref, to: "olam-devbox:base" });
@@ -22617,6 +22784,7 @@ function writeCloudMemorySecret(value, path94 = CLOUD_MEMORY_SECRET_PATH) {
 }
 
 // src/commands/memory-service-container.ts
+init_output();
 var MEMORY_SERVICE_PORT = 3111;
 var MEMORY_SERVICE_CONTAINER = "olam-memory-service";
 var MEMORY_SERVICE_LOCAL_TAG = "olam-memory-service:local";
@@ -22651,13 +22819,27 @@ var MemoryServiceContainerController = class {
   }
   /**
    * Resolve the first available image tag: local → dev → published.
+   *
+   * The preferred path is :local (populated by `olam bootstrap` pulling the
+   * digest-pinned image and tagging it). The :published fallback is `:latest`
+   * which is NOT digest-pinned — Docker will pull whatever tag-head is on
+   * the registry at pull time. This is the degraded-mode path for operators
+   * whose image-digests.json predates the G1 memory-service digest fix; it
+   * is intentionally loud so they know they are not on the pinned path.
+   *
    * Throws if none exist (operator should run `olam bootstrap` to pull, or
    * `node packages/cli/scripts/build-memory-service-image.mjs` to build locally).
    */
   resolveImage() {
-    for (const tag of [MEMORY_SERVICE_LOCAL_TAG, MEMORY_SERVICE_DEV_TAG, MEMORY_SERVICE_PUBLISHED_TAG]) {
+    for (const tag of [MEMORY_SERVICE_LOCAL_TAG, MEMORY_SERVICE_DEV_TAG]) {
       if (this.imageExists(tag)) return tag;
     }
+    if (this.imageExists(MEMORY_SERVICE_PUBLISHED_TAG)) {
+      printWarning(
+        `memory-service: using tag-pulled fallback image (${MEMORY_SERVICE_PUBLISHED_TAG}). This image was NOT pulled by digest. Run \`olam bootstrap\` to pull the digest-pinned image and eliminate this warning.`
+      );
+      return MEMORY_SERVICE_PUBLISHED_TAG;
+    }
     throw new Error(
       `memory-service image not found. Tried: ${MEMORY_SERVICE_LOCAL_TAG}, ${MEMORY_SERVICE_DEV_TAG}, ${MEMORY_SERVICE_PUBLISHED_TAG}. Run \`olam bootstrap\` to pull the published image, or \`node packages/cli/scripts/build-memory-service-image.mjs\` to build locally.`
     );
@@ -22773,7 +22955,7 @@ var PERIPHERALS = [
   {
     name: "auth-service",
     port: 9999,
-    k8sServiceName: "auth-service",
+    k8sResourceName: "olam-auth-service",
     composeContainerName: "olam-auth-service",
     configMapKeyInHostCp: "OLAM_AUTH_SERVICE_URL",
     healthPath: "/health"
@@ -22781,7 +22963,7 @@ var PERIPHERALS = [
   {
     name: "mcp-auth-service",
     port: 9998,
-    k8sServiceName: "mcp-auth-service",
+    k8sResourceName: "olam-mcp-auth-service",
     composeContainerName: "olam-mcp-auth-service",
     configMapKeyInHostCp: "OLAM_MCP_AUTH_SERVICE_URL",
     healthPath: "/health"
@@ -22789,7 +22971,7 @@ var PERIPHERALS = [
   {
     name: "kg-service",
     port: 9997,
-    k8sServiceName: "kg-service",
+    k8sResourceName: "olam-kg-service",
     composeContainerName: "olam-kg-service",
     configMapKeyInHostCp: "OLAM_KG_SERVICE_URL",
     healthPath: "/health"
@@ -22797,7 +22979,7 @@ var PERIPHERALS = [
   {
     name: "memory-service",
     port: 3111,
-    k8sServiceName: "memory-service",
+    k8sResourceName: "olam-memory-service",
     composeContainerName: "olam-memory-service",
     configMapKeyInHostCp: "OLAM_MEMORY_SERVICE_URL",
     healthPath: "/agentmemory/livez"
@@ -23455,7 +23637,7 @@ async function spawnPeripheralPortForward(peripheral, context, namespace, deps =
         "port-forward",
         "-n",
         namespace,
-        `service/${peripheral.k8sServiceName}`,
+        `service/${peripheral.k8sResourceName}`,
         `${peripheral.port}:${peripheral.port}`
       ],
       {
@@ -23654,8 +23836,8 @@ function appendAuditEntry(entry, auditLogPath, writeFileSyncImpl) {
 }
 async function runManifestRefresh(manifestsDir, acceptRegression, deps = {}, peripheral) {
   const auditLogPath = deps.auditLogPath ?? MANIFEST_REFRESH_AUDIT_LOG;
-  const readdirSync32 = deps.readdirSync ?? fs31.readdirSync;
-  const readFileSync92 = deps.readFileSync ?? fs31.readFileSync;
+  const readdirSync33 = deps.readdirSync ?? fs31.readdirSync;
+  const readFileSync93 = deps.readFileSync ?? fs31.readFileSync;
   const writeFileSyncImpl = deps.writeFileSync ?? fs31.writeFileSync;
   const existsSync112 = deps.existsSync ?? fs31.existsSync;
   const now = deps.now ? deps.now() : /* @__PURE__ */ new Date();
@@ -23668,7 +23850,7 @@ async function runManifestRefresh(manifestsDir, acceptRegression, deps = {}, per
   }
   let files;
   try {
-    const entries = readdirSync32(targetDir, { withFileTypes: true });
+    const entries = readdirSync33(targetDir, { withFileTypes: true });
     files = entries.filter((e) => e.isFile() && (e.name.endsWith(".yaml") || e.name.endsWith(".json"))).map((e) => e.name);
   } catch (err) {
     return {
@@ -23681,7 +23863,7 @@ async function runManifestRefresh(manifestsDir, acceptRegression, deps = {}, per
     const filePath = path32.join(targetDir, file);
     let content;
     try {
-      content = readFileSync92(filePath, "utf8");
+      content = readFileSync93(filePath, "utf8");
     } catch {
       continue;
     }
@@ -23831,9 +24013,8 @@ var PERIPHERAL_SECRETS = [
   { name: "memory-service", secretName: "olam-memory-service-secret", keys: ["OLAM_MEMORY_BEARER_SECRET"] }
 ];
 var K8S_DNS_SUFFIX = "olam.svc.cluster.local";
-function buildK8sDnsUrl(k8sServiceName, port2) {
-  const prefixed = k8sServiceName.startsWith("olam-") ? k8sServiceName : `olam-${k8sServiceName}`;
-  return `http://${prefixed}.${K8S_DNS_SUFFIX}:${port2}`;
+function buildK8sDnsUrl(k8sResourceName, port2) {
+  return `http://${k8sResourceName}.${K8S_DNS_SUFFIX}:${port2}`;
 }
 function appendSubstrateAuditEntry(entry, stderr) {
   try {
@@ -23933,11 +24114,11 @@ async function checkSecretPreCondition(context, deps) {
 }
 async function applyConfigMapSubstitution(context, manifestsDir, deps) {
   const wrap = deps.kubectlWrapImpl ?? kubectlWrap;
-  const readFileSync92 = deps.readFileSyncImpl ?? fs32.readFileSync;
+  const readFileSync93 = deps.readFileSyncImpl ?? fs32.readFileSync;
   const configMapPath = path33.join(manifestsDir, "30-configmap.yaml");
   let rawYaml;
   try {
-    rawYaml = readFileSync92(configMapPath, "utf8");
+    rawYaml = readFileSync93(configMapPath, "utf8");
   } catch (err) {
     return `Failed to read ConfigMap at ${configMapPath}: ${err instanceof Error ? err.message : String(err)}`;
   }
@@ -23949,7 +24130,7 @@ async function applyConfigMapSubstitution(context, manifestsDir, deps) {
   }
   const data = parsed["data"] ?? {};
   for (const peripheral of PERIPHERALS) {
-    data[peripheral.configMapKeyInHostCp] = buildK8sDnsUrl(peripheral.k8sServiceName, peripheral.port);
+    data[peripheral.configMapKeyInHostCp] = buildK8sDnsUrl(peripheral.k8sResourceName, peripheral.port);
   }
   parsed["data"] = data;
   const patchedYaml = yamlStringify(parsed);
@@ -24302,10 +24483,10 @@ async function runUpgradeKubernetes(opts = {}, deps = {}) {
     return { exitCode: 1, summary: "configmap substitution failed" };
   }
   step35Spinner.succeed("ConfigMap patched with K8s DNS URLs (survives bulk apply)");
-  const step4Spinner = ora3("Waiting for rollout (all 5 deployments, 90s each)").start();
+  const step4Spinner = ora3("Waiting for rollout (all 5 deployments, 300s each)").start();
   const deploymentNames = [
     HOST_CP_DEPLOYMENT_NAME,
-    ...PERIPHERALS.map((p) => p.name)
+    ...PERIPHERALS.map((p) => p.k8sResourceName)
   ];
   const rolloutResults = await Promise.all(
     deploymentNames.map(
@@ -24318,18 +24499,28 @@ async function runUpgradeKubernetes(opts = {}, deps = {}) {
           `deployment/${deploymentName}`,
           "-n",
           K8S_NAMESPACE3,
-          "--timeout=90s"
+          "--timeout=300s"
         ],
-        { timeout: 95e3 }
+        { timeout: 305e3 }
       )
     )
   );
   const failedDeployments = deploymentNames.filter((_, i) => !rolloutResults[i]?.ok);
   if (failedDeployments.length > 0) {
     step4Spinner.fail(`Rollout failed for: ${failedDeployments.join(", ")}`);
-    for (const name of failedDeployments) {
+    for (const [i, name] of failedDeployments.entries()) {
+      const result = rolloutResults[deploymentNames.indexOf(name)];
       stderr.write(`${pc10.red("error:")} rollout status failed for deployment/${name}.
 `);
+      if (result && (result.stdout || result.stderr)) {
+        stderr.write(`${pc10.dim("--- kubectl rollout status output ---")}
+`);
+        if (result.stdout) stderr.write(result.stdout + "\n");
+        if (result.stderr) stderr.write(result.stderr + "\n");
+        stderr.write(`${pc10.dim(`exit code: ${result.exitCode ?? "(none)"}, reason: ${"reason" in result ? result.reason : "ok"}`)}
+`);
+      }
+      void i;
       stderr.write(`${pc10.dim(`--- kubectl get pods -n ${K8S_NAMESPACE3} -o wide ---`)}
 `);
       const podsResult = await wrap(
@@ -34550,7 +34741,7 @@ async function runPeripheralProbes(peripheral, startPosition, kubectlContext, wr
       [
         ...ctxArgs,
         "exec",
-        `deploy/${peripheral.name}`,
+        `deploy/${peripheral.k8sResourceName}`,
         "-n",
         K8S_NAMESPACE5,
         "--",
@@ -34567,7 +34758,7 @@ async function runPeripheralProbes(peripheral, startPosition, kubectlContext, wr
     return {
       ok: false,
       message: `${peripheral.name} pod not reachable`,
-      remedy: `Check pod logs: kubectl logs deploy/${peripheral.name} -n ${K8S_NAMESPACE5}. stderr: ${errLine}`
+      remedy: `Check pod logs: kubectl logs deploy/${peripheral.k8sResourceName} -n ${K8S_NAMESPACE5}. stderr: ${errLine}`
     };
   })();
   rows.push({ name: `${peripheral.name} reachable`, result: reachableResult, position: startPosition });
@@ -34612,7 +34803,7 @@ async function runPeripheralProbes(peripheral, startPosition, kubectlContext, wr
         "-n",
         K8S_NAMESPACE5,
         "-l",
-        `app=${peripheral.name}`,
+        `app=${peripheral.k8sResourceName}`,
         "-o",
         `jsonpath={.items[0].status.containerStatuses[0].image}`
       ],
@@ -34626,7 +34817,7 @@ async function runPeripheralProbes(peripheral, startPosition, kubectlContext, wr
       ok: true,
       warn: true,
       message: `${peripheral.name} image not detected`,
-      remedy: `Verify pod is running: kubectl get pods -n ${K8S_NAMESPACE5} -l app=${peripheral.name}`
+      remedy: `Verify pod is running: kubectl get pods -n ${K8S_NAMESPACE5} -l app=${peripheral.k8sResourceName}`
     };
   })();
   rows.push({ name: `${peripheral.name} image`, result: imagePresentResult, position: startPosition + 2 });
@@ -35314,10 +35505,10 @@ function parseTracker(path94) {
 }
 
 // ../cli-plugin-tasks/dist/commands/workers.js
-import { randomUUID as randomUUID2 } from "node:crypto";
+import { randomUUID as randomUUID3 } from "node:crypto";
 var SUBSTRATES = ["mac-mini", "cloudflare-container", "gcp-vm"];
 function generateProvisionPlan(opts) {
-  const workerId = opts.workerId ?? `worker-${randomUUID2().slice(0, 8)}`;
+  const workerId = opts.workerId ?? `worker-${randomUUID3().slice(0, 8)}`;
   const hostCpUrl = opts.hostCpUrl ?? "http://localhost:19000";
   const nodeId = opts.olamNodeId ?? `<OLAM_NODE_ID>`;
   const sessionId = opts.sessionId ?? `<OLAM_SESSION_ID>`;
@@ -35667,8 +35858,8 @@ function registerCompletion(program2) {
 // src/commands/setup.ts
 init_cli_version();
 init_health_probes();
-import { spawn as spawn7 } from "node:child_process";
-import { existsSync as existsSync84 } from "node:fs";
+import { spawn as spawn7, spawnSync as spawnSync26 } from "node:child_process";
+import { existsSync as existsSync84, readFileSync as readFileSync68 } from "node:fs";
 import { homedir as homedir43 } from "node:os";
 import path75 from "node:path";
 import { createInterface as createInterface3 } from "node:readline";
@@ -35996,10 +36187,17 @@ async function runProjectSweepPhase(opts, deps, sweepDeps = {}) {
 
 // src/commands/setup.ts
 var REQUIRED_NODE_MAJOR = 20;
-var NEXT_STEPS_DOCS = [
-  "docs/architecture/devbox-contract.md  \u2014 image contract",
-  "docs/architecture/manifest-spec.md    \u2014 per-repo .adb.yaml schema",
-  "docs/architecture/config-spec.md      \u2014 workspace .olam/config.yaml schema"
+var SETUP_K3D_CLUSTER_NAME = "olam-dev";
+var NEXT_STEPS_DOCS_DOCKER = [
+  "https://github.com/pleri/olam/blob/main/docs/architecture/devbox-contract.md  \u2014 image contract",
+  "https://github.com/pleri/olam/blob/main/docs/architecture/manifest-spec.md    \u2014 per-repo .adb.yaml schema",
+  "https://github.com/pleri/olam/blob/main/docs/architecture/config-spec.md      \u2014 workspace .olam/config.yaml schema"
+];
+var NEXT_STEPS_DOCS_KUBERNETES = [
+  "https://github.com/pleri/olam/blob/main/docs/architecture/devbox-contract.md  \u2014 image contract",
+  "https://github.com/pleri/olam/blob/main/docs/architecture/manifest-spec.md    \u2014 per-repo .adb.yaml schema",
+  "https://github.com/pleri/olam/blob/main/docs/architecture/config-spec.md      \u2014 workspace .olam/config.yaml schema",
+  "https://github.com/pleri/olam/blob/main/docs/k8s/SETUP.md                     \u2014 k3d operator guide"
 ];
 var defaultSpawn = (cmd, args) => new Promise((resolve27) => {
   const child = spawn7(cmd, [...args], { stdio: "inherit" });
@@ -36028,14 +36226,61 @@ var defaultPrompt = (question, defaultYes) => {
     rl.on("close", () => resolve27(defaultYes));
   });
 };
-async function phase1SystemCheck(deps) {
+var DOCKER_MIGRATION_HINT = "olam: detected existing docker stack \u2014 continuing on docker. To migrate to k3d, run: olam upgrade --substrate=kubernetes (available in a future release).";
+function resolveSubstrate(opts, deps) {
+  if (opts.substrate === "kubernetes") return "kubernetes";
+  if (opts.substrate === "docker") return "docker";
+  const configPath = deps.configPath ?? OLAM_CONFIG_PATH;
+  if (existsSync84(configPath)) {
+    try {
+      const raw = readFileSync68(configPath, "utf8");
+      const parsed = JSON.parse(raw);
+      const host = parsed.host;
+      if (host?.substrate === "kubernetes") return "kubernetes";
+      if (host?.substrate === "compose") {
+        process.stderr.write(DOCKER_MIGRATION_HINT + "\n");
+        return "docker";
+      }
+    } catch {
+    }
+  }
+  return "kubernetes";
+}
+async function phase1SystemCheck(substrate, deps) {
+  const nodeVersion = deps.nodeVersion ?? process.version;
+  const nodeMajor = parseNodeMajor(nodeVersion);
+  const nodeOk = nodeMajor !== null && nodeMajor >= REQUIRED_NODE_MAJOR;
+  if (substrate === "kubernetes") {
+    const kubectlProbe = await probeKubectl(deps.dockerExec);
+    if (!kubectlProbe.ok) {
+      return phaseFromProbe(kubectlProbe);
+    }
+    const dockerProbe2 = await probeDockerDaemon(deps.dockerExec);
+    if (!dockerProbe2.ok) {
+      return {
+        ok: false,
+        message: "docker daemon required for k3d: " + dockerProbe2.message,
+        remedy: dockerProbe2.remedy
+      };
+    }
+    if (!nodeOk) {
+      return {
+        ok: false,
+        message: `Node.js ${nodeVersion} is too old (need \u2265${REQUIRED_NODE_MAJOR})`,
+        remedy: `Install Node.js ${REQUIRED_NODE_MAJOR}+ LTS via nvm/fnm/asdf and re-run \`olam setup\`.`
+      };
+    }
+    return { ok: true, message: `kubectl on PATH; docker ready; node ${nodeVersion}` };
+  }
   const dockerProbe = await probeDockerDaemon(deps.dockerExec);
   if (!dockerProbe.ok) {
     return phaseFromProbe(dockerProbe);
   }
-  const nodeVersion = deps.nodeVersion ?? process.version;
-  const nodeMajor = parseNodeMajor(nodeVersion);
-  if (nodeMajor === null || nodeMajor < REQUIRED_NODE_MAJOR) {
+  const composeProbe = await probeComposePlugin(deps.dockerExec);
+  if (!composeProbe.ok) {
+    return phaseFromProbe(composeProbe);
+  }
+  if (!nodeOk) {
     return {
       ok: false,
       message: `Node.js ${nodeVersion} is too old (need \u2265${REQUIRED_NODE_MAJOR})`,
@@ -36044,9 +36289,68 @@ async function phase1SystemCheck(deps) {
   }
   return {
     ok: true,
-    message: `${dockerProbe.message}; node ${nodeVersion}`
+    message: `${dockerProbe.message}; ${composeProbe.message}; node ${nodeVersion}`
   };
 }
+async function phase1_5InstallSubstrate(substrate, opts, deps) {
+  if (substrate === "docker") {
+    return { ok: true, skipped: true, message: "no-op for docker substrate" };
+  }
+  const spawnFn = deps.spawnSubprocess ?? defaultSpawn;
+  const promptFn = deps.prompt ?? defaultPrompt;
+  const k3dProbe = await probeK3d(deps.dockerExec);
+  if (k3dProbe.ok) {
+    return { ok: true, message: `k3d already present: ${k3dProbe.message}` };
+  }
+  const hasBrew = spawnSync26("command", ["-v", "brew"], { shell: true, stdio: "pipe" }).status === 0;
+  const useBrewMsg = hasBrew ? "Homebrew" : "upstream install script";
+  if (!opts.yes) {
+    const confirmed = await promptFn(
+      `k3d is not installed. Install via ${useBrewMsg}?`,
+      true
+    );
+    if (!confirmed) {
+      return {
+        ok: false,
+        message: "k3d install declined; required for kubernetes substrate",
+        remedy: "Install manually: `brew install k3d` or curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash, then re-run `olam setup --substrate=kubernetes`."
+      };
+    }
+  }
+  if (hasBrew) {
+    process.stdout.write("Installing k3d via Homebrew...\n");
+    const r = await spawnFn("brew", ["install", "k3d"]);
+    if (r.status !== 0) {
+      return {
+        ok: false,
+        message: `brew install k3d failed (exit ${r.status ?? "signal"})`,
+        remedy: "Try manually: `brew install k3d` or curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash"
+      };
+    }
+  } else {
+    process.stdout.write("Installing k3d via upstream install script...\n");
+    const r = await spawnFn("bash", [
+      "-c",
+      "curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash"
+    ]);
+    if (r.status !== 0) {
+      return {
+        ok: false,
+        message: `k3d upstream install failed (exit ${r.status ?? "signal"})`,
+        remedy: "Install manually: https://k3d.io/v5.x/installation/"
+      };
+    }
+  }
+  const k3dCheck = await probeK3d(deps.dockerExec);
+  if (!k3dCheck.ok) {
+    return {
+      ok: false,
+      message: "k3d still not on PATH after install \u2014 shell PATH may need updating",
+      remedy: "Close and re-open your terminal, then re-run `olam setup --substrate=kubernetes`."
+    };
+  }
+  return { ok: true, message: `k3d installed: ${k3dCheck.message}` };
+}
 function parseNodeMajor(version) {
   const m = version.match(/^v?(\d+)\./);
   if (!m) return null;
@@ -36057,6 +36361,65 @@ function phaseFromProbe(probe2) {
   if (probe2.ok) return { ok: true, message: probe2.message };
   return { ok: false, message: probe2.message, remedy: probe2.remedy };
 }
+async function phase2_5ProvisionCluster(substrate, opts, deps) {
+  if (substrate === "docker") {
+    return { ok: true, skipped: true, message: "no-op for docker substrate" };
+  }
+  const spawnFn = deps.spawnSubprocess ?? defaultSpawn;
+  const listResult = await captureSpawn("k3d", ["cluster", "list", "--output", "json"], deps.dockerExec);
+  if (listResult.ok) {
+    const exists = clusterExistsInList(listResult.stdout, SETUP_K3D_CLUSTER_NAME);
+    if (exists) {
+      return {
+        ok: true,
+        message: `cluster ${SETUP_K3D_CLUSTER_NAME} already exists; skipping create`
+      };
+    }
+  }
+  process.stdout.write(`Creating k3d cluster ${SETUP_K3D_CLUSTER_NAME}...
+`);
+  const ghConfigBind = `${homedir43()}/.config/gh:/host/.config/gh`;
+  const createResult = await spawnFn("k3d", [
+    "cluster",
+    "create",
+    SETUP_K3D_CLUSTER_NAME,
+    "--volume",
+    ghConfigBind,
+    "--wait",
+    "--timeout",
+    "90s"
+  ]);
+  if (createResult.status !== 0) {
+    return {
+      ok: false,
+      message: `k3d cluster create ${SETUP_K3D_CLUSTER_NAME} failed (exit ${createResult.status ?? "signal"})`,
+      remedy: `Run manually: k3d cluster create ${SETUP_K3D_CLUSTER_NAME} --wait --timeout 90s`
+    };
+  }
+  const ctxResult = captureSpawnSync("kubectl", ["config", "current-context"]);
+  const ctx = ctxResult.ok ? ctxResult.stdout.trim() : "(unknown)";
+  return { ok: true, message: `cluster ${SETUP_K3D_CLUSTER_NAME} created; context: ${ctx}` };
+}
+async function captureSpawn(cmd, args, dockerExec) {
+  const exec = dockerExec ?? ((c, a) => {
+    const r2 = spawnSync26(c, [...a], { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] });
+    return { status: r2.status, stdout: r2.stdout ?? "", stderr: r2.stderr ?? "" };
+  });
+  const r = exec(cmd, args);
+  return { ok: r.status === 0, stdout: r.stdout, stderr: r.stderr };
+}
+function captureSpawnSync(cmd, args) {
+  const r = spawnSync26(cmd, [...args], { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] });
+  return { ok: r.status === 0, stdout: r.stdout ?? "" };
+}
+function clusterExistsInList(json, clusterName) {
+  try {
+    const parsed = JSON.parse(json);
+    return Array.isArray(parsed) && parsed.some((c) => c.name === clusterName);
+  } catch {
+    return false;
+  }
+}
 async function phase2CliSanity(deps) {
   const version = deps.olamCliVersion ?? safeReadCliVersion();
   if (!version || version === "unknown") {
@@ -36075,11 +36438,36 @@ function safeReadCliVersion() {
     return null;
   }
 }
-async function phase3Bootstrap(deps) {
+async function phase2_6PinKubectlContext(substrate, deps) {
+  if (substrate !== "kubernetes") {
+    return { ok: true, skipped: true, message: "no-op for docker substrate" };
+  }
+  const expectedContext = `k3d-${SETUP_K3D_CLUSTER_NAME}`;
+  writeConfig({ host: { substrate: "kubernetes" } }, { configPath: deps.configPath });
+  const result = applyKubectlContextPin([expectedContext], {
+    configPath: deps.configPath
+  });
+  if ("pinned" in result) {
+    return { ok: true, message: `kubectl context pinned: ${result.pinned}` };
+  }
+  if ("skipped" in result) {
+    return { ok: true, message: `kubectl context already pinned (${result.skipped})` };
+  }
+  return {
+    ok: false,
+    message: `kubectl context pin refused: ${result.refused}`,
+    remedy: `Set host.kubectl_context_pinned = ${expectedContext} in ~/.olam/config.json and re-run.`
+  };
+}
+async function phase3Bootstrap(substrate, deps) {
   const spawnFn = deps.spawnSubprocess ?? defaultSpawn;
-  const r = await spawnFn("olam", ["bootstrap", "--skip-auth-login"]);
+  const bootstrapArgs = ["bootstrap", "--skip-auth-login"];
+  if (substrate === "kubernetes") {
+    bootstrapArgs.push("--skip-cluster-create");
+  }
+  const r = await spawnFn("olam", bootstrapArgs);
   if (r.status === 0) {
-    return { ok: true, message: "olam bootstrap succeeded" };
+    return { ok: true, message: `olam bootstrap succeeded (substrate: ${substrate})` };
   }
   return {
     ok: false,
@@ -36191,7 +36579,10 @@ async function phase6Auth(opts, deps) {
     message: `olam auth login exited ${r.status}; re-run \`olam auth login\` after resolving`
   };
 }
-async function phase7Verify(deps) {
+async function phase7Verify(opts, deps) {
+  if (opts.skipDoctor) {
+    return { ok: true, skipped: true, message: "skipped via --skip-doctor" };
+  }
   const spawnFn = deps.spawnSubprocess ?? defaultSpawn;
   const r = await spawnFn("olam", ["doctor"]);
   if (r.status === 0) {
@@ -36203,9 +36594,12 @@ async function phase7Verify(deps) {
     remedy: "Inspect doctor output above; the specific failing probe names its remedy."
   };
 }
-var PHASE_TITLES = [
+var PHASE_TITLES_DOCKER = [
   "Phase 1: System check",
+  "Phase 1.5: Substrate tools install",
   "Phase 2: olam CLI sanity",
+  "Phase 2.5: Cluster provision",
+  "Phase 2.6: Pin kubectl context",
   "Phase 3: Bootstrap",
   "Phase 4: Shell init",
   "Phase 5: Init project",
@@ -36215,22 +36609,29 @@ var PHASE_TITLES = [
   "Phase 7: Final verification"
 ];
 async function runSetup(opts, deps = {}) {
-  printHeader("olam setup");
+  const substrate = resolveSubstrate(opts, deps);
+  const bannerSubstrate = substrate === "kubernetes" ? "Kubernetes (k3d)" : "Docker Compose";
+  printHeader(`olam setup \u2014 Olam local stack on ${bannerSubstrate}`);
+  process.stdout.write(`substrate: ${substrate}
+`);
   const phaseFns = [
-    () => phase1SystemCheck(deps),
+    () => phase1SystemCheck(substrate, deps),
+    () => phase1_5InstallSubstrate(substrate, opts, deps),
     () => phase2CliSanity(deps),
-    () => phase3Bootstrap(deps),
+    () => phase2_5ProvisionCluster(substrate, opts, deps),
+    () => phase2_6PinKubectlContext(substrate, deps),
+    () => phase3Bootstrap(substrate, deps),
     () => phase4ShellInit(opts, deps),
     () => phase5InitProject(opts, deps),
     () => phase5aSkillSource(opts, deps),
     () => phase5bProjectSweep(opts, deps),
     () => phase6Auth(opts, deps),
-    () => phase7Verify(deps)
+    () => phase7Verify(opts, deps)
   ];
   const results = [];
   let failureAt = null;
   for (let i = 0; i < phaseFns.length; i += 1) {
-    const name = PHASE_TITLES[i];
+    const name = PHASE_TITLES_DOCKER[i];
     process.stdout.write(`
 ${name}
 `);
@@ -36254,7 +36655,8 @@ ${name}
   }
   printSuccess("Setup complete.");
   process.stdout.write("\nNext steps \u2014 read these in order for the 3-contract pattern:\n");
-  for (const line of NEXT_STEPS_DOCS) {
+  const nextStepsDocs = substrate === "kubernetes" ? NEXT_STEPS_DOCS_KUBERNETES : NEXT_STEPS_DOCS_DOCKER;
+  for (const line of nextStepsDocs) {
     printInfo("docs", line);
   }
   process.stdout.write("\n");
@@ -36262,9 +36664,31 @@ ${name}
 }
 function registerSetup(program2) {
   program2.command("setup").description(
-    "Fresh-host onboarding wizard. Runs 7 phases (system check \u2192 bootstrap \u2192 shell init \u2192 init project \u2192 auth prompt \u2192 doctor verification). Idempotent; safe to re-run."
-  ).option("--skip-shell-init", "Skip Phase 4 (do not append to ~/.zshrc / ~/.bashrc)").option("--skip-auth", "Skip Phase 6 (do not prompt for `olam auth login`)").option("--skip-skill-source", "Skip Phase 5a (do not pick a skill source; run `olam skills source add` later)").option("--skill-source <id-or-url>", "Non-interactive Phase 5a: curated name (e.g. atlas-toolbox) or git URL").option("--skip-project-sweep", "Skip Phase 5b (do not walk projects directory for repo discovery)").option("--projects <path>", "Phase 5b: project root path to walk (default: ~/Projects)").option("--dry-run", "Phase 5b: print matches without registering or building (no side effects)").option("--exclude <glob...>", "Phase 5b: additional skip patterns for project sweep").option("--skip-kg", "Phase 5b: skip KG eager-build sub-step (sources still registered)").option("-y, --yes", "Auto-affirm every prompt (non-interactive)").action(async (opts) => {
-    const report = await runSetup(opts);
+    "Fresh-host onboarding wizard. Default substrate=kubernetes (k3d on all platforms): installs k3d (no sudo needed \u2014 only requires docker), provisions the olam-dev cluster, then runs bootstrap end-to-end. Existing docker/compose installs are protected \u2014 they continue on docker with a migration hint. Idempotent; safe to re-run."
+  ).option(
+    "--substrate <substrate>",
+    "Target substrate: kubernetes (default, alias: k3s) or docker. Auto-detected from ~/.olam/config.json when not specified."
+  ).option("--skip-shell-init", "Skip Phase 4 (do not append to ~/.zshrc / ~/.bashrc)").option("--skip-auth", "Skip Phase 6 (do not prompt for `olam auth login`)").option("--skip-skill-source", "Skip Phase 5a (do not pick a skill source; run `olam skills source add` later)").option("--skill-source <id-or-url>", "Non-interactive Phase 5a: curated name (e.g. atlas-toolbox) or git URL").option("--skip-project-sweep", "Skip Phase 5b (do not walk projects directory for repo discovery)").option("--projects <path>", "Phase 5b: project root path to walk (default: ~/Projects)").option("--dry-run", "Phase 5b: print matches without registering or building (no side effects)").option("--exclude <glob...>", "Phase 5b: additional skip patterns for project sweep").option("--skip-kg", "Phase 5b: skip KG eager-build sub-step (sources still registered)").option(
+    "--skip-doctor",
+    "Skip Phase 7 final `olam doctor` verification (for CI or minimal setups)"
+  ).option("-y, --yes", "Auto-affirm every prompt (non-interactive)").action(async (rawOpts) => {
+    let substrate;
+    const rawSubstrate = rawOpts.substrate;
+    if (rawSubstrate === "k3s" || rawSubstrate === "kubernetes") {
+      substrate = "kubernetes";
+    } else if (rawSubstrate === "docker") {
+      substrate = "docker";
+    } else if (rawSubstrate !== void 0) {
+      process.stderr.write(
+        `[olam setup] Unknown --substrate value '${rawSubstrate}'. Valid values: docker, kubernetes (alias: k3s).
+`
+      );
+      process.exitCode = 1;
+      return;
+    }
+    const { substrate: _drop, ...restOpts } = rawOpts;
+    void _drop;
+    const report = await runSetup({ ...restOpts, substrate });
     if (report.exitCode !== 0) process.exitCode = report.exitCode;
   });
 }
@@ -37036,7 +37460,7 @@ import * as readline2 from "node:readline";
 import pc32 from "picocolors";
 
 // src/commands/flywheel/install-shims.ts
-import { copyFileSync as copyFileSync9, existsSync as existsSync88, mkdirSync as mkdirSync53, readFileSync as readFileSync71, writeFileSync as writeFileSync44 } from "node:fs";
+import { copyFileSync as copyFileSync9, existsSync as existsSync88, mkdirSync as mkdirSync53, readFileSync as readFileSync72, writeFileSync as writeFileSync44 } from "node:fs";
 import { homedir as homedir46 } from "node:os";
 import { dirname as dirname48, join as join85 } from "node:path";
 
@@ -37140,7 +37564,7 @@ function installOne(spec, targetDir, opts) {
     }
     return { basename: spec.basename, action: "written", targetPath };
   }
-  const existing = readFileSync71(targetPath, "utf8");
+  const existing = readFileSync72(targetPath, "utf8");
   if (existing === newContent) {
     return { basename: spec.basename, action: "unchanged", targetPath };
   }
@@ -37252,6 +37676,15 @@ ${pc32.bold("Sync now?")} ${pc32.dim("[Y/n] ")}`);
     });
   });
 }
+function parsePrefixScope(raw) {
+  const tokens = raw.split(",").map((t) => t.trim()).filter((t) => t.length > 0);
+  if (tokens.length === 0) return [];
+  const valid = /* @__PURE__ */ new Set(["skill", "agent"]);
+  for (const t of tokens) {
+    if (!valid.has(t)) return null;
+  }
+  return [...new Set(tokens)];
+}
 function registerSkillsSource(program2) {
   const skills = program2.command("skills").description("Manage skill sources and synchronization");
   const source = skills.command("source").description("Manage registered skill sources");
@@ -37264,20 +37697,29 @@ function registerSkillsSource(program2) {
       return;
     }
     printHeader(`${all.length} skill source(s)`);
+    const DEFAULT_SCOPE_REPR = "skill,agent";
+    const showScopeCol = all.some(
+      (s) => s.prefixScope !== void 0 && s.prefixScope.slice().sort().join(",") !== "agent,skill"
+    );
     for (let i = 0; i < all.length; i += 1) {
       const s = all[i];
       const when = new Date(s.addedAt).toISOString().slice(0, 10);
       const sha = s.lastPulledSha ? s.lastPulledSha.slice(0, 8) : pc32.dim("(unpulled)");
       const ord = pc32.dim(`[${i + 1}]`);
       const prefixCol = s.prefix ? pc32.cyan(s.prefix.padEnd(12)) : pc32.dim("\u2014".padEnd(12));
+      const scopeDisplay = s.prefixScope !== void 0 ? s.prefixScope.join(",") : DEFAULT_SCOPE_REPR;
+      const scopeCol = showScopeCol ? ` ${pc32.yellow(scopeDisplay.padEnd(12))}` : "";
       console.log(
-        `  ${ord} ${pc32.bold(s.id.padEnd(14))} ${s.name.padEnd(24)} ${s.branch.padEnd(12)} ${sha.padEnd(12)} ${prefixCol} ${pc32.dim(when)} ${pc32.dim(s.gitUrl)}`
+        `  ${ord} ${pc32.bold(s.id.padEnd(14))} ${s.name.padEnd(24)} ${s.branch.padEnd(12)} ${sha.padEnd(12)} ${prefixCol}${scopeCol} ${pc32.dim(when)} ${pc32.dim(s.gitUrl)}`
       );
     }
   });
   source.command("add").description("Register and clone a skill source (T6 capability-class: requires --trust OR interactive ack)").requiredOption("--name <name>", "Display name (lowercase, digits, dash)").requiredOption("--git-url <url>", "git URL (https://, git@, ssh://, file://, or absolute path)").option("--branch <branch>", "Branch to track", "main").option(
     "--prefix <prefix>",
     'Deploy prefix: skills+agents from this source deploy as <prefix>:<canonical-name> (e.g. "atl", "pln"). Must match /^[a-z0-9][a-z0-9_-]{0,38}$/'
+  ).option(
+    "--prefix-scope <scope>",
+    'Comma-separated list of artifact kinds to rename when prefix is set. Valid values: skill, agent. Default: skill,agent. E.g. "--prefix-scope=skill" to rename only skills.'
   ).option("--trust", "Acknowledge that registering grants symlink-into-~/.claude permission (skips interactive picker)").option("--sync-now", "Run `olam skills sync` immediately after add (skips interactive prompt)").option("--no-sync-now", "Skip the post-add sync (skips interactive prompt)").option("--install-hook", "Install the SessionStart hook after add (skips interactive prompt)").option("--no-install-hook", "Skip installing the SessionStart hook (skips interactive prompt)").option(
     "--hook-scope <scope>",
     "When installing the hook (post-add): project (<cwd>/.claude) or user (~/.claude)",
@@ -37291,6 +37733,18 @@ function registerSkillsSource(program2) {
       process.exitCode = 1;
       return;
     }
+    let parsedPrefixScope;
+    if (opts.prefixScope !== void 0) {
+      const parsed = parsePrefixScope(opts.prefixScope);
+      if (parsed === null) {
+        printError(
+          `--prefix-scope must be a comma-separated list of "skill" and/or "agent" \u2014 got "${opts.prefixScope}"`
+        );
+        process.exitCode = 1;
+        return;
+      }
+      parsedPrefixScope = parsed;
+    }
     const isTTY = Boolean(process.stdout.isTTY);
     const testPromptFn = globalThis.__olamTestTrustPrompt;
     let decision;
@@ -37328,8 +37782,11 @@ function registerSkillsSource(program2) {
         branch: opts.branch,
         trustMethod: decision.method
       });
-      if (opts.prefix !== void 0) {
-        updateSkillSource(entry.id, { prefix: opts.prefix });
+      if (opts.prefix !== void 0 || parsedPrefixScope !== void 0) {
+        updateSkillSource(entry.id, {
+          ...opts.prefix !== void 0 ? { prefix: opts.prefix } : {},
+          ...parsedPrefixScope !== void 0 ? { prefixScope: parsedPrefixScope } : {}
+        });
       }
     } catch (err) {
       try {
@@ -37576,6 +38033,53 @@ function registerSkillsSource(program2) {
       process.exitCode = 1;
     }
   });
+  source.command("set-prefix-scope").description(
+    "Set which artifact kinds are renamed by the prefix (comma-separated: skill, agent, or skill,agent)"
+  ).argument("<name>", 'Display name of the skill source (from "olam skills source list")').argument("<scope>", 'Comma-separated artifact kinds: "skill", "agent", or "skill,agent". Empty string = no renaming.').action((name, scopeRaw) => {
+    const entry = getSkillSourceByName(name);
+    if (entry === null) {
+      printError(
+        `skill source "${name}" is not registered. Run "olam skills source list" to see registered sources.`
+      );
+      process.exitCode = 1;
+      return;
+    }
+    const parsed = parsePrefixScope(scopeRaw);
+    if (parsed === null) {
+      printError(
+        `scope must be a comma-separated list of "skill" and/or "agent" \u2014 got "${scopeRaw}"`
+      );
+      process.exitCode = 1;
+      return;
+    }
+    try {
+      updateSkillSource(entry.id, { prefixScope: parsed });
+      const display = parsed.length === 0 ? "(none \u2014 prefix disabled)" : parsed.join(",");
+      printSuccess(`set prefix-scope "${display}" on source "${name}" (${entry.id})`);
+    } catch (err) {
+      printError(asMessage3(err));
+      process.exitCode = 1;
+    }
+  });
+  source.command("unset-prefix-scope").description(
+    "Remove the prefix-scope override from a registered skill source (reverts to default: both skill and agent are renamed)"
+  ).argument("<name>", 'Display name of the skill source (from "olam skills source list")').action((name) => {
+    const entry = getSkillSourceByName(name);
+    if (entry === null) {
+      printError(
+        `skill source "${name}" is not registered. Run "olam skills source list" to see registered sources.`
+      );
+      process.exitCode = 1;
+      return;
+    }
+    try {
+      updateSkillSource(entry.id, { prefixScope: null });
+      printSuccess(`unset prefix-scope on source "${name}" (${entry.id}) \u2014 reverted to default (skill,agent)`);
+    } catch (err) {
+      printError(asMessage3(err));
+      process.exitCode = 1;
+    }
+  });
 }
 
 // src/commands/skills.ts
@@ -37595,8 +38099,8 @@ import {
   existsSync as existsSync89,
   lstatSync as lstatSync8,
   mkdirSync as mkdirSync54,
-  readdirSync as readdirSync26,
-  readFileSync as readFileSync72,
+  readdirSync as readdirSync27,
+  readFileSync as readFileSync73,
   readlinkSync as readlinkSync4,
   rmSync as rmSync9,
   statSync as statSync27,
@@ -37679,7 +38183,7 @@ function ensureRealDir(p) {
     rmSync9(p);
     mkdirSync54(p, { recursive: true });
     if (existsSync89(target) && statSync27(target).isDirectory()) {
-      for (const entry of readdirSync26(target)) {
+      for (const entry of readdirSync27(target)) {
         const src = join86(target, entry);
         const dest = join86(p, entry);
         const srcStat = lstatSync8(src);
@@ -37703,8 +38207,8 @@ function postMergeSanitize(mergedText, label) {
   return { ok: false, reason: `[post-merge-sanitize] ${label} merged output failed sanitizer: ${result.reason}` };
 }
 function mergeOne(upstreamPath, overlayPath, destPath2, label, dryRun, messages) {
-  const upstreamText = readFileSync72(upstreamPath, "utf8");
-  const overlayText = readFileSync72(overlayPath, "utf8");
+  const upstreamText = readFileSync73(upstreamPath, "utf8");
+  const overlayText = readFileSync73(overlayPath, "utf8");
   const result = mergeMarkdown(upstreamText, overlayText, label, upstreamPath, overlayPath);
   if ("error" in result) {
     messages.push(`ERROR ${result.error.reason}`);
@@ -37724,7 +38228,7 @@ function mergeOne(upstreamPath, overlayPath, destPath2, label, dryRun, messages)
 }
 function isNewAgentOverlay(overlayPath) {
   try {
-    const text = readFileSync72(overlayPath, "utf8");
+    const text = readFileSync73(overlayPath, "utf8");
     const { fm } = parseFrontmatter3(text);
     return fm["overlay-intent"] === "new-agent";
   } catch {
@@ -37740,7 +38244,7 @@ function copyNewAgent(overlayPath, destPath2, label, dryRun, messages) {
 }
 function walkSkillsOverlays(skillsOverridesDir, skillsDir, opts, result) {
   if (!existsSync89(skillsOverridesDir)) return;
-  for (const skillName of readdirSync26(skillsOverridesDir)) {
+  for (const skillName of readdirSync27(skillsOverridesDir)) {
     const overlaySkillDir = join86(skillsOverridesDir, skillName);
     if (!statSync27(overlaySkillDir).isDirectory()) continue;
     const upstreamSkillDir = join86(skillsDir, skillName);
@@ -37756,7 +38260,7 @@ function walkOverlayTree(overlayRoot, upstreamRoot, labelPrefix, opts, result, i
   const stack = [overlayRoot];
   while (stack.length > 0) {
     const current = stack.pop();
-    for (const entry of readdirSync26(current)) {
+    for (const entry of readdirSync27(current)) {
       const overlayPath = join86(current, entry);
       const stat = lstatSync8(overlayPath);
       if (stat.isDirectory()) {
@@ -39743,9 +40247,9 @@ function registerMcpServe(cmd) {
 init_output();
 
 // src/commands/mcp/install-shared.ts
-import { spawnSync as spawnSync27 } from "node:child_process";
+import { spawnSync as spawnSync28 } from "node:child_process";
 var DEFAULT_CLAUDE_SHELL_DEPS = {
-  spawn: spawnSync27,
+  spawn: spawnSync28,
   log: (msg) => console.log(msg)
 };
 function isOnPath(deps, bin) {
@@ -40462,8 +40966,8 @@ function registerMcp(program2) {
 init_output();
 
 // src/lib/memory-host-process-migration.ts
-import { existsSync as existsSync100, readFileSync as readFileSync80, unlinkSync as unlinkSync23 } from "node:fs";
-import { spawnSync as spawnSync28 } from "node:child_process";
+import { existsSync as existsSync100, readFileSync as readFileSync81, unlinkSync as unlinkSync23 } from "node:fs";
+import { spawnSync as spawnSync29 } from "node:child_process";
 
 // src/commands/memory/_paths.ts
 import { homedir as homedir51 } from "node:os";
@@ -40531,7 +41035,7 @@ function migrateFromHostProcess(opts = {}) {
 }
 function readPidFromFile(pidPath2) {
   try {
-    const raw = readFileSync80(pidPath2, "utf8").trim();
+    const raw = readFileSync81(pidPath2, "utf8").trim();
     const pid = parseInt(raw, 10);
     if (!Number.isFinite(pid) || pid <= 0) return null;
     return pid;
@@ -40548,7 +41052,7 @@ function isProcessAlive(pid) {
   }
 }
 function processCommName(pid) {
-  const r = spawnSync28("ps", ["-p", String(pid), "-o", "comm="], { encoding: "utf-8" });
+  const r = spawnSync29("ps", ["-p", String(pid), "-o", "comm="], { encoding: "utf-8" });
   if (r.status !== 0) return null;
   const comm = r.stdout.trim();
   return comm.split("/").pop() ?? null;
@@ -40562,7 +41066,7 @@ function terminateProcess(pid) {
   const deadline = Date.now() + KILL_TIMEOUT_MS;
   while (Date.now() < deadline) {
     if (!isProcessAlive(pid)) return true;
-    spawnSync28("sleep", ["0.1"]);
+    spawnSync29("sleep", ["0.1"]);
   }
   try {
     process.kill(pid, "SIGKILL");
@@ -40964,7 +41468,7 @@ function registerMemoryUninstall(cmd) {
 // src/commands/memory/mode.ts
 init_schema2();
 init_output();
-import { existsSync as existsSync103, readFileSync as readFileSync81, writeFileSync as writeFileSync51 } from "node:fs";
+import { existsSync as existsSync103, readFileSync as readFileSync82, writeFileSync as writeFileSync51 } from "node:fs";
 import { join as join94 } from "node:path";
 import * as readline7 from "node:readline/promises";
 import { parse as parseYaml7, stringify as stringifyYaml6 } from "yaml";
@@ -40979,7 +41483,7 @@ function locateConfig(cwd) {
   return { absPath };
 }
 function readConfigYaml(absPath) {
-  const raw = readFileSync81(absPath, "utf-8");
+  const raw = readFileSync82(absPath, "utf-8");
   const parsed = parseYaml7(raw) ?? {};
   if (typeof parsed !== "object" || parsed === null) {
     throw new Error(`${absPath} is not a YAML object`);
@@ -41466,7 +41970,7 @@ function registerMemoryStats(cmd) {
 }
 
 // src/commands/memory/install-hooks.ts
-import { copyFileSync as copyFileSync12, existsSync as existsSync105, mkdirSync as mkdirSync60, readFileSync as readFileSync82, writeFileSync as writeFileSync52 } from "node:fs";
+import { copyFileSync as copyFileSync12, existsSync as existsSync105, mkdirSync as mkdirSync60, readFileSync as readFileSync83, writeFileSync as writeFileSync52 } from "node:fs";
 import { homedir as homedir52 } from "node:os";
 import { dirname as dirname56, join as join96, resolve as resolve25 } from "node:path";
 import { fileURLToPath as fileURLToPath9 } from "node:url";
@@ -41489,7 +41993,7 @@ function installOne2(basename16, sourceDir, targetDir, opts) {
   if (!existsSync105(sourcePath)) {
     throw new Error(`canonical hook source missing at ${sourcePath} \u2014 olam install corrupt or sourceDir is wrong`);
   }
-  const newContent = readFileSync82(sourcePath, "utf8");
+  const newContent = readFileSync83(sourcePath, "utf8");
   if (!existsSync105(targetPath)) {
     if (opts.dryRun !== true) {
       mkdirSync60(dirname56(targetPath), { recursive: true });
@@ -41497,7 +42001,7 @@ function installOne2(basename16, sourceDir, targetDir, opts) {
     }
     return { basename: basename16, action: "written", targetPath };
   }
-  const existing = readFileSync82(targetPath, "utf8");
+  const existing = readFileSync83(targetPath, "utf8");
   if (existing === newContent) {
     return { basename: basename16, action: "unchanged", targetPath };
   }
@@ -42824,14 +43328,14 @@ init_file_lock();
 import { mkdirSync as mkdirSync63, appendFileSync as appendFileSync6 } from "node:fs";
 import { homedir as homedir57 } from "node:os";
 import { dirname as dirname59, join as join100 } from "node:path";
-import { randomUUID as randomUUID3 } from "node:crypto";
+import { randomUUID as randomUUID4 } from "node:crypto";
 var VALID_SEVERITIES = /* @__PURE__ */ new Set(["critical", "high", "medium", "low", "info", "warn"]);
 var PROMPT_FEEDING_FIELDS = ["extracted_pattern", "severity", "affected_persona", "proposed_edit"];
 var BREADCRUMBS_BASE = join100(homedir57(), ".local", "share", "claude", "breadcrumbs");
 var LOCK_FILENAME = ".flywheel-emit.lock";
 function buildRecord(opts) {
   const rec = {
-    breadcrumb_id: randomUUID3().replace(/-/g, ""),
+    breadcrumb_id: randomUUID4().replace(/-/g, ""),
     emitted_at: (/* @__PURE__ */ new Date()).toISOString(),
     emitted_by_skill: opts.skill,
     pass_number: opts.pass !== void 0 ? Number.parseInt(opts.pass, 10) : 0,
@@ -42975,7 +43479,7 @@ function registerFlywheelK5Score(parent) {
 }
 
 // src/commands/flywheel/k5-validate.ts
-import { readFileSync as readFileSync86, statSync as statSync30 } from "node:fs";
+import { readFileSync as readFileSync87, statSync as statSync30 } from "node:fs";
 import { parse as parseYAML } from "yaml";
 var K5_DIMS = ["direction", "approach", "open_questions", "constraints", "reuse"];
 var MAX_PLAN_BYTES = 1048576;
@@ -43045,7 +43549,7 @@ function validatePlan(path94) {
   }
   let text;
   try {
-    text = readFileSync86(path94, "utf8");
+    text = readFileSync87(path94, "utf8");
   } catch (err) {
     return { ok: false, message: `FAIL cannot read ${path94}: ${err instanceof Error ? err.message : "unknown"}` };
   }
@@ -43127,7 +43631,7 @@ function registerFlywheelK5Validate(parent) {
 }
 
 // src/commands/flywheel/k10-measure.ts
-import { readFileSync as readFileSync87 } from "node:fs";
+import { readFileSync as readFileSync88 } from "node:fs";
 
 // ../core/dist/lib/k10-budget.js
 var K10_TOKEN_CAP = 5500;
@@ -43184,7 +43688,7 @@ function registerFlywheelK10Measure(parent) {
   parent.command("k10-measure").description("Measure K10 token budget for upstream + optional overlay; emit PASS/REJECT verdict").requiredOption("--upstream <path>", "path to upstream file (e.g. persona prompt)").option("--overlay <path>", "path to overlay file (omit if none \u2014 PASS without enforcement)").option("--json", "emit verdict as JSON instead of human-readable").action((opts) => {
     let upstreamText;
     try {
-      upstreamText = readFileSync87(opts.upstream, "utf8");
+      upstreamText = readFileSync88(opts.upstream, "utf8");
     } catch (err) {
       process.stderr.write(
         `[k10-measure-error] cannot read upstream ${opts.upstream}: ${err instanceof Error ? err.message : "unknown"}
@@ -43196,7 +43700,7 @@ function registerFlywheelK10Measure(parent) {
     let overlayTokens = null;
     if (opts.overlay !== void 0) {
       try {
-        const overlayText = readFileSync87(opts.overlay, "utf8");
+        const overlayText = readFileSync88(opts.overlay, "utf8");
         overlayTokens = tokensFromText(overlayText);
       } catch (err) {
         process.stderr.write(
@@ -43230,7 +43734,7 @@ function registerFlywheelK10Measure(parent) {
 }
 
 // src/commands/flywheel/check-persona-skeleton.ts
-import { existsSync as existsSync109, readFileSync as readFileSync88, statSync as statSync31 } from "node:fs";
+import { existsSync as existsSync109, readFileSync as readFileSync89, statSync as statSync31 } from "node:fs";
 import { homedir as homedir58 } from "node:os";
 import { basename as basename14, join as join101 } from "node:path";
 import { parse as parseYAML2 } from "yaml";
@@ -43279,7 +43783,7 @@ function checkFile(filepath) {
   if (!existsSync109(filepath) || !statSync31(filepath).isFile()) {
     return { passed: false, failures: [`file not found: ${filepath}`], tokens: 0, mergedSkipped: false };
   }
-  const text = readFileSync88(filepath, "utf8");
+  const text = readFileSync89(filepath, "utf8");
   const { fm, body } = parseFile(text);
   const failures = [];
   for (const key of REQUIRED_FRONTMATTER_KEYS) {
@@ -43345,7 +43849,7 @@ Results: ${passCount} passed, ${failCount} failed
 }
 
 // src/commands/flywheel/diversity-check.ts
-import { readFileSync as readFileSync89 } from "node:fs";
+import { readFileSync as readFileSync90 } from "node:fs";
 import { basename as basename15 } from "node:path";
 import { globSync as globSync2 } from "node:fs";
 
@@ -43454,7 +43958,7 @@ function registerFlywheelDiversityCheck(parent) {
     const personas = /* @__PURE__ */ new Map();
     for (const filepath of files) {
       try {
-        const body = readFileSync89(filepath, "utf8");
+        const body = readFileSync90(filepath, "utf8");
         if (body.trim().length > 0) {
           personas.set(basename15(filepath, ".md"), body);
         }
@@ -43547,12 +44051,12 @@ import {
   copyFileSync as copyFileSync15,
   existsSync as existsSync110,
   mkdirSync as mkdirSync65,
-  readFileSync as readFileSync90,
-  readdirSync as readdirSync31,
+  readFileSync as readFileSync91,
+  readdirSync as readdirSync32,
   statSync as statSync32,
   writeFileSync as writeFileSync57
 } from "node:fs";
-import { spawnSync as spawnSync29 } from "node:child_process";
+import { spawnSync as spawnSync30 } from "node:child_process";
 import { homedir as homedir60 } from "node:os";
 import { dirname as dirname61, join as join103, relative as relative7 } from "node:path";
 function escapeRegex(s) {
@@ -43586,7 +44090,7 @@ function walkOverlayFiles(dir) {
   const found = [];
   let entries;
   try {
-    entries = readdirSync31(dir);
+    entries = readdirSync32(dir);
   } catch {
     return [];
   }
@@ -43633,7 +44137,7 @@ function resolveAtlasUser2(opts) {
   const claudeDir2 = opts._testClaudeDir ?? process.env["OLAM_CLAUDE_DIR"] ?? join103(homedir60(), ".claude");
   const f = join103(claudeDir2, ".atlas-user");
   if (existsSync110(f)) {
-    const v = readFileSync90(f, "utf-8").trim();
+    const v = readFileSync91(f, "utf-8").trim();
     if (v.length === 0) return null;
     assertValidAtlasUser(v);
     return v;
@@ -43641,7 +44145,7 @@ function resolveAtlasUser2(opts) {
   return null;
 }
 function runGit2(args, cwd) {
-  const result = spawnSync29("git", args, {
+  const result = spawnSync30("git", args, {
     cwd,
     encoding: "utf-8",
     stdio: ["ignore", "pipe", "pipe"]
@@ -43775,7 +44279,7 @@ function pushOverlays(opts) {
       const basename16 = relPath.split("/").pop() ?? relPath;
       let content;
       try {
-        content = readFileSync90(srcFile);
+        content = readFileSync91(srcFile);
       } catch {
         continue;
       }
@@ -43823,12 +44327,12 @@ function pushOverlays(opts) {
       const targetFile = join103(targetDir, relPath);
       let srcBuf;
       try {
-        srcBuf = readFileSync90(srcFile);
+        srcBuf = readFileSync91(srcFile);
       } catch {
         continue;
       }
       if (existsSync110(targetFile)) {
-        const dstBuf = readFileSync90(targetFile);
+        const dstBuf = readFileSync91(targetFile);
         if (srcBuf.equals(dstBuf)) {
           wouldUnchange += 1;
           process.stdout.write(`  [skip] ${overlayKind}.overrides/${relPath} (unchanged)
@@ -43879,13 +44383,13 @@ function pushOverlays(opts) {
       const targetFile = join103(membersBase, `${overlayKind}.overrides`, relPath);
       let srcBuf;
       try {
-        srcBuf = readFileSync90(srcFile);
+        srcBuf = readFileSync91(srcFile);
       } catch {
         continue;
       }
       const targetExists = existsSync110(targetFile);
       if (targetExists) {
-        const dstBuf = readFileSync90(targetFile);
+        const dstBuf = readFileSync91(targetFile);
         if (srcBuf.equals(dstBuf)) {
           filesUnchanged += 1;
           continue;
@@ -44094,7 +44598,7 @@ function migrateOverlays(opts = {}) {
   for (const filePath of allFiles) {
     let original;
     try {
-      original = readFileSync90(filePath, "utf8");
+      original = readFileSync91(filePath, "utf8");
     } catch {
       continue;
     }
@@ -44254,7 +44758,7 @@ function registerFlywheel(program2) {
 
 // src/commands/seed.ts
 init_output();
-import { spawnSync as spawnSync30, spawn as spawnAsync2 } from "node:child_process";
+import { spawnSync as spawnSync31, spawn as spawnAsync2 } from "node:child_process";
 var DEFAULT_SINGLETON_CONTAINER = "olam-postgres";
 var DEFAULT_SINGLETON_USER = "development";
 function assertValidSeedName(name) {
@@ -44265,7 +44769,7 @@ function assertValidSeedName(name) {
   }
 }
 function singletonDocker(container, user, args, stdin) {
-  return spawnSync30(
+  return spawnSync31(
     "docker",
     ["exec", "-i", container, "psql", "-U", user, ...args],
     { encoding: "utf-8", input: stdin }
@@ -44320,7 +44824,7 @@ async function handleBake(opts) {
   if (sources.length > 1) {
     throw new Error("multiple sources specified \u2014 pass exactly one of --source-container, --source-url, --source-local");
   }
-  const ping = spawnSync30("docker", ["inspect", "--format", "{{.State.Status}}", singleton], { encoding: "utf-8" });
+  const ping = spawnSync31("docker", ["inspect", "--format", "{{.State.Status}}", singleton], { encoding: "utf-8" });
   if (ping.status !== 0 || (ping.stdout || "").trim() !== "running") {
     throw new Error(`singleton container "${singleton}" not running \u2014 run \`olam bootstrap\` first`);
   }