@openpalm/lib 0.11.0-beta.11 → 0.11.0-beta.13

package/src/control-plane/compose-args.ts

@@ -5,49 +5,159 @@
  * construction into a single shared module. Both CLI and admin
  * routes use these functions instead of assembling args inline.
  */
-import { existsSync } from "node:fs";
+import { existsSync, writeFileSync, chmodSync, mkdirSync } from "node:fs";
 import type { ControlPlaneState } from "./types.js";
 import { buildComposeFileList } from "./lifecycle.js";
 import { buildEnvFiles } from "./config-persistence.js";
 import { resolveComposeProjectName } from "./docker.js";
+import { parseEnvFile } from "./env.js";
+import { canonicalAddonProfileSelection } from "./profile-ids.js";
+import { listStackSpecAddons } from "./stack-spec.js";
 
 // ── Types ────────────────────────────────────────────────────────────────
 
 export type ComposeOptions = {
   files: string[];
   envFiles: string[];
+  profiles: string[];
 };
 
+// ── Profile Resolution ───────────────────────────────────────────────────
+
+/**
+ * Resolve active Docker Compose profiles from the stack env.
+ * Reads OP_VOICE_PROFILE and OP_OLLAMA_PROFILE (addon hardware profiles).
+ * Returns deduplicated, non-empty profile strings.
+ */
+export function resolveActiveProfiles(state: ControlPlaneState): string[] {
+  const profiles: string[] = [];
+  const stackEnvPath = `${state.stashDir}/env/stack.env`;
+  let env: Record<string, string> = {};
+  if (existsSync(stackEnvPath)) {
+    env = parseEnvFile(stackEnvPath);
+    for (const profile of (env.COMPOSE_PROFILES ?? '').split(',')) {
+      const trimmed = profile.trim();
+      if (trimmed) profiles.push(trimmed);
+    }
+    const voiceProfile = canonicalAddonProfileSelection('voice', env.OP_VOICE_PROFILE ?? '');
+    if (voiceProfile) profiles.push(voiceProfile);
+    const ollamaProfile = canonicalAddonProfileSelection('ollama', env.OP_OLLAMA_PROFILE ?? '');
+    if (ollamaProfile) profiles.push(ollamaProfile);
+  }
+
+  for (const addon of listStackSpecAddons(state.stackDir)) {
+    if (addon === 'voice') {
+      profiles.push(canonicalAddonProfileSelection('voice', env.OP_VOICE_PROFILE ?? '') || 'addon.voice.cpu');
+    } else if (addon === 'ollama') {
+      profiles.push(canonicalAddonProfileSelection('ollama', env.OP_OLLAMA_PROFILE ?? '') || 'addon.ollama.cpu');
+    } else {
+      profiles.push(`addon.${addon}`);
+    }
+  }
+
+  return [...new Set(profiles)];
+}
+
 // ── Builders ─────────────────────────────────────────────────────────────
 
 /**
- * Build the compose file and env file lists for a given state.
- * Returns the resolved files and env files for use with docker.ts functions.
- *
- * Note: env files are already filtered to only existing paths by
- * `buildEnvFiles()` in config-persistence.ts.
+ * Build the compose file, env file, and profile lists for a given state.
+ * Returns the resolved values for use with docker.ts functions.
  */
 export function buildComposeOptions(state: ControlPlaneState): ComposeOptions {
   return {
     files: buildComposeFileList(state),
     envFiles: buildEnvFiles(state),
+    profiles: resolveActiveProfiles(state),
   };
 }
 
 /**
  * Build the full docker compose CLI argument array for a given state.
  *
- * Returns: ['--project-name', 'openpalm', '-f', file1, '-f', file2, '--env-file', env1, ...]
+ * Returns: ['--project-name', 'openpalm', '-f', file1, '-f', file2, '--env-file', env1, '--profile', addon.voice.cpu, ...]
  *
  * Only includes env files that exist on disk.
  */
 export function buildComposeCliArgs(state: ControlPlaneState): string[] {
-  const { files, envFiles } = buildComposeOptions(state);
+  const { files, envFiles, profiles } = buildComposeOptions(state);
 
   return [
     "--project-name",
-    resolveComposeProjectName(),
+    resolveComposeProjectName(collectEnvOverrides(envFiles)),
     ...files.flatMap((f) => ["-f", f]),
     ...envFiles.filter((f) => existsSync(f)).flatMap((f) => ["--env-file", f]),
+    ...profiles.flatMap((p) => ["--profile", p]),
+  ];
+}
+
+// ── Run Script ───────────────────────────────────────────────────────────
+
+/**
+ * Convert an absolute path to a ${OP_HOME}-relative shell expression.
+ * E.g. "/home/user/.openpalm/config/stack/core.compose.yml"
+ *   → "${OP_HOME}/config/stack/core.compose.yml"
+ */
+function toOpHomeRelative(absPath: string, homeDir: string): string {
+  if (absPath.startsWith(homeDir)) {
+    return absPath.replace(homeDir, "${OP_HOME}");
+  }
+  return absPath;
+}
+
+function shellArg(value: string): string {
+  if (value.includes("${")) return `"${value}"`;
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+function collectEnvOverrides(envFiles: string[]): Record<string, string> {
+  const overrides: Record<string, string> = {};
+  for (const envFile of envFiles) {
+    Object.assign(overrides, parseEnvFile(envFile));
+  }
+  return overrides;
+}
+
+/**
+ * Write the effective docker compose command to OP_HOME/run.sh.
+ * Uses environment variable references (${OP_HOME}, ${OP_PROJECT_NAME}) so
+ * the script is portable and self-documenting.
+ *
+ * Wraps `source stack.env` in `set -a` / `set +a` so variables without
+ * explicit `export` are still available to child processes (docker compose).
+ *
+ * Called after any stack modification: setup, addon enable/disable,
+ * profile change, or upgrade.
+ */
+export function writeRunScript(state: ControlPlaneState): void {
+  const { files, envFiles, profiles } = buildComposeOptions(state);
+  const stackEnvRef = toOpHomeRelative(`${state.stashDir}/env/stack.env`, state.homeDir);
+
+  const lines: string[] = [
+    "#!/usr/bin/env bash",
+    "# Auto-generated by OpenPalm - DO NOT EDIT",
+    "# This file reproduces the exact docker compose invocation",
+    "# used by the control plane. Run it to start/restart the stack.",
+    "",
+    `set -euo pipefail`,
+    `SCRIPT_DIR="$(cd -- "$(dirname -- "${"${BASH_SOURCE[0]}"}")" && pwd)"`,
+    `OP_HOME="${"${OP_HOME:-$SCRIPT_DIR}"}"`,
+    `export OP_HOME`,
+    `set -a`,
+    `source ${shellArg(stackEnvRef)}`,
+    `set +a`,
+    `profile_args=(${profiles.map(shellArg).join(' ')})`,
+    `docker compose --project-name "${"${OP_PROJECT_NAME:-${COMPOSE_PROJECT_NAME:-openpalm}}"}" \\`,
+    `    "${"${profile_args[@]}"}" \\`,
+    ...files.flatMap((f) => [`    -f ${shellArg(toOpHomeRelative(f, state.homeDir))} \\`]),
+    ...envFiles.filter((f) => existsSync(f)).flatMap((f) => [`    --env-file ${shellArg(toOpHomeRelative(f, state.homeDir))} \\`]),
+    `    up -d`,
+    "",
   ];
+
+  const content = lines.join("\n");
+  const runScriptPath = `${state.homeDir}/run.sh`;
+  mkdirSync(state.homeDir, { recursive: true });
+  writeFileSync(runScriptPath, content, { mode: 0o755 });
+  chmodSync(runScriptPath, 0o755);
 }

package/src/control-plane/config-persistence.ts

@@ -3,58 +3,52 @@
  *
  * Writes and derives live runtime files (compose, env, schemas).
  * Files are validated in-place before writing; rollback is handled by
- * the rollback module (snapshot to ~/.cache/openpalm/rollback/).
+ * the rollback module (snapshot to OP_HOME/data/rollback/).
  */
-import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, chmodSync } from "node:fs";
-import { dirname } from "node:path";
+import { mkdirSync, writeFileSync, readFileSync, existsSync, chmodSync } from "node:fs";
+import { dirname, resolve as resolvePath } from "node:path";
 import { parse as yamlParse } from "yaml";
-import { parseEnvFile, mergeEnvContent, expandEnvVars } from './env.js';
+import { parseEnvContent, parseEnvFile, mergeEnvContent, expandEnvVars } from './env.js';
+import { assertNoSecretLikeStackEnvKeys, isSecretLikeStackEnvKey } from './secrets.js';
+import { ensureSecret } from './secrets-files.js';
 import type { ControlPlaneState, ArtifactMeta } from "./types.js";
-import { isChannelAddon } from "./channels.js";
 import { listEnabledAddonIds } from "./registry.js";
 import { resolveOperatorIds, hasUsableOperatorId } from "./operator-ids.js";
 
 import {
   readCoreCompose,
+  readBundledStackAsset,
 } from "./core-assets.js";
 export { sha256, randomHex } from "./crypto.js";
 import { sha256, randomHex } from "./crypto.js";
 
-const DEFAULT_IMAGE_TAG = process.env.OP_IMAGE_TAG ?? "latest";
+const DEFAULT_IMAGE_TAG = "latest";
 
 // ── Env File Management ──────────────────────────────────────────────
 
 /**
  * Return the env files used for docker compose --env-file args.
- * These are the live vault env files.
  *
- * Order: stack.env -> guardian.env
- *
- * Note: `vault/user/user.env` is no longer a
- * compose env_file. User-managed env secrets live in the akm
- * `vault:user` store and are sourced by the assistant entrypoint at
- * container startup. The legacy file is migrated into akm and deleted
- * on upgrade; subsequent `docker compose` invocations must not reference
- * it (compose interpolates `${VAR}` against the merged --env-file
- * contents, and a stale user.env would shadow the akm-sourced values).
+ * Only `knowledge/env/stack.env` (non-secret system config). Secret values
+ * live in `knowledge/secrets/<ENV_KEY>` and are granted to services as Compose
+ * file secrets. The user env (`knowledge/env/user.env`) is NOT a compose
+ * env_file — it is sourced by the assistant entrypoint at container startup.
  */
 export function buildEnvFiles(state: ControlPlaneState): string[] {
   return [
-    `${state.stackDir}/stack.env`,
-    `${state.stackDir}/guardian.env`,
+    `${state.stashDir}/env/stack.env`,
   ].filter(existsSync);
 }
 
 /**
- * Write system-managed values to config/stack/stack.env.
+ * Write system-managed values to knowledge/env/stack.env.
  *
- * Channel HMAC secrets are NOT written here — they belong in guardian.env.
- * Use writeChannelSecrets() for channel secrets.
+ * Secret-like keys are NOT written here — they belong in knowledge/secrets/.
+ * Use ensureChannelSecret() for channel secrets.
  */
 export function writeSystemEnv(state: ControlPlaneState): void {
-  mkdirSync(state.stackDir, { recursive: true });
-
-  const systemEnvPath = `${state.stackDir}/stack.env`;
+  const systemEnvPath = `${state.stashDir}/env/stack.env`;
+  mkdirSync(`${state.stashDir}/env`, { recursive: true, mode: 0o700 });
 
   let base = "";
   if (existsSync(systemEnvPath)) {
@@ -63,11 +57,12 @@ export function writeSystemEnv(state: ControlPlaneState): void {
     base = generateFallbackSystemEnv(state);
   }
 
-  // Preserve existing OP_SETUP_COMPLETE=true
-  const alreadyComplete = /^OP_SETUP_COMPLETE=true$/mi.test(base);
-
+  // Preserve the existing OP_SETUP_COMPLETE flag as-is.
+  // Only the wizard completion path (buildSystemSecretsFromSetup) writes "true".
+  // Defaulting to "false" here ensures a fresh install always shows the wizard.
+  const parsed = parseEnvFile(systemEnvPath);
   const adminManaged: Record<string, string> = {
-    OP_SETUP_COMPLETE: alreadyComplete ? "true" : "false"
+    OP_SETUP_COMPLETE: parsed.OP_SETUP_COMPLETE === "true" ? "true" : "false",
   };
 
   // Backfill OP_UID/OP_GID when the existing stack.env was written by an
@@ -76,13 +71,20 @@ export function writeSystemEnv(state: ControlPlaneState): void {
   // missing or zero — an operator who manually set OP_UID=2000 (e.g.
   // because they're running on a host with a non-1000 service account)
   // must not be silently changed.
-  const parsed = parseEnvFile(systemEnvPath);
   const ids = resolveOperatorIds(state.homeDir);
   if (ids) {
     if (!hasUsableOperatorId(parsed, "OP_UID")) adminManaged.OP_UID = String(ids.uid);
     if (!hasUsableOperatorId(parsed, "OP_GID")) adminManaged.OP_GID = String(ids.gid);
   }
 
+  // Backfill OP_HOME when missing — compose files reference ${OP_HOME}
+  // for all volume mounts. Without this, Docker Compose defaults to blank.
+  if (!parsed.OP_HOME) adminManaged.OP_HOME = state.homeDir;
+
+  base = stripSecretLikeEnvKeys(base);
+  assertNoSecretLikeStackEnvKeys(parseEnvContent(base));
+  assertNoSecretLikeStackEnvKeys(adminManaged);
+
   const content = mergeEnvContent(base, adminManaged, {
     sectionHeader: "# ── Admin-managed ──────────────────────────────────────────────────"
   });
@@ -91,6 +93,19 @@ export function writeSystemEnv(state: ControlPlaneState): void {
   chmodSync(systemEnvPath, 0o600);
 }
 
+function stripSecretLikeEnvKeys(content: string): string {
+  return content
+    .split('\n')
+    .filter((line) => {
+      let trimmed = line.trim();
+      if (trimmed.startsWith('export ')) trimmed = trimmed.slice(7).trimStart();
+      const eq = trimmed.indexOf('=');
+      if (eq <= 0) return true;
+      return !isSecretLikeStackEnvKey(trimmed.slice(0, eq).trim());
+    })
+    .join('\n');
+}
+
 function generateFallbackSystemEnv(state: ControlPlaneState): string {
   // Operator UID/GID — auto-detect from OP_HOME owner (or process UID).
   // Skipped on Windows where containers run in WSL2 and OP_UID has no
@@ -104,12 +119,6 @@ function generateFallbackSystemEnv(state: ControlPlaneState): string {
     "# OpenPalm — System Configuration (managed by CLI/admin)",
     "# Auto-generated fallback.",
     "",
-    "# ── Authentication ──────────────────────────────────────────────────",
-    `OP_UI_LOGIN_PASSWORD=\${OP_UI_LOGIN_PASSWORD}`,
-    "",
-    "# ── Service Auth ─────────────────────────────────────────────────────",
-    "OP_OPENCODE_PASSWORD=",
-    "",
     "# ── Paths ──────────────────────────────────────────────────────────",
     `OP_HOME=${state.homeDir}`,
     ...idLines,
@@ -131,37 +140,20 @@ function generateFallbackSystemEnv(state: ControlPlaneState): string {
 // ── Stack Overlay Discovery ────────────────────────────────────────────
 
 /**
- * Discover compose overlays from the stack directory.
- * Returns full paths: [stack/core.compose.yml, stack/addons/{name}/compose.yml].
+ * Discover active compose overlays.
+ * Returns the fixed compose stack: core, services, channels, and custom.
+ * First-party services are profile-gated inside services.compose.yml and
+ * channels.compose.yml.
  */
-export function discoverStackOverlays(stackDir: string): string[] {
+export function discoverStackOverlays(stackDir: string, _homeDir?: string): string[] {
   const files: string[] = [];
 
   const coreYml = `${stackDir}/core.compose.yml`;
   if (existsSync(coreYml)) files.push(coreYml);
 
-  const addonsDir = `${stackDir}/addons`;
-  if (existsSync(addonsDir)) {
-    const entries = readdirSync(addonsDir, { withFileTypes: true })
-      .filter((e) => e.isDirectory())
-      .sort((a, b) => a.name.localeCompare(b.name));
-    for (const entry of entries) {
-      const dir = `${addonsDir}/${entry.name}`;
-      // Pick up compose.yml plus any compose.<variant>.yml sibling
-      // overlays (e.g. compose.cdi.yml generated by /admin/voice on
-      // CDI hosts). Stable sort: compose.yml first, then siblings
-      // alphabetically, so the base file's keys are the defaults and
-      // overlays merge on top in deterministic order.
-      const overlays = readdirSync(dir, { withFileTypes: true })
-        .filter((e) => e.isFile() && /^compose(\.[A-Za-z0-9_-]+)?\.ya?ml$/.test(e.name))
-        .map((e) => e.name)
-        .sort((a, b) => {
-          if (a === "compose.yml" || a === "compose.yaml") return -1;
-          if (b === "compose.yml" || b === "compose.yaml") return 1;
-          return a.localeCompare(b);
-        });
-      for (const name of overlays) files.push(`${dir}/${name}`);
-    }
+  for (const name of ['services.compose.yml', 'channels.compose.yml', 'custom.compose.yml']) {
+    const composePath = `${stackDir}/${name}`;
+    if (existsSync(composePath)) files.push(composePath);
   }
 
   return files;
@@ -192,79 +184,38 @@ export function buildRuntimeFileMeta(artifacts: {
 }
 
 // ── Channel Secrets ────────────────────────────────────────────────────
-// Channel HMAC secrets live exclusively in vault/stack/guardian.env.
-
-const CHANNEL_SECRET_RE = /^CHANNEL_([A-Z0-9_]+)_SECRET$/;
 
-/** Extract channel secrets from parsed env entries. */
-function extractChannelSecrets(parsed: Record<string, string>): Record<string, string> {
-  const result: Record<string, string> = {};
-  for (const [key, value] of Object.entries(parsed)) {
-    const match = key.match(CHANNEL_SECRET_RE);
-    if (match?.[1] && value) result[match[1].toLowerCase()] = value;
-  }
-  return result;
+export function channelSecretName(addon: string): string {
+  return `channel_${addon.replace(/-/g, '_')}_secret`;
 }
 
-/**
- * Read channel HMAC secrets from config/stack/guardian.env.
- */
-export function readChannelSecrets(stackDir: string): Record<string, string> {
-  return extractChannelSecrets(parseEnvFile(`${stackDir}/guardian.env`));
-}
-
-/**
- * Write channel HMAC secrets to state/guardian.env.
- * Merges with existing content; does not overwrite unrelated entries.
- */
-export function writeChannelSecrets(stackDir: string, secrets: Record<string, string>): void {
-  const guardianPath = `${stackDir}/guardian.env`;
-  mkdirSync(stackDir, { recursive: true });
-
-  let base = "";
-  if (existsSync(guardianPath)) {
-    base = readFileSync(guardianPath, "utf-8");
-  } else {
-    base = "# Guardian channel HMAC secrets — managed by openpalm\n";
-  }
-
-  const updates: Record<string, string> = {};
-  for (const [ch, secret] of Object.entries(secrets)) {
-    updates[`CHANNEL_${ch.toUpperCase()}_SECRET`] = secret;
-  }
-
-  const content = mergeEnvContent(base, updates);
-  writeFileSync(guardianPath, content, { mode: 0o600 });
-  // Ensure correct permissions even if file already existed with wrong mode
-  chmodSync(guardianPath, 0o600);
+export function ensureChannelSecret(stackDir: string, addon: string): string {
+  return ensureSecret(stackDir, channelSecretName(addon), () => randomHex(16));
 }
 
 // ── Volume Mount Targets ───────────────────────────────────────────────
 
 /**
- * Parse all enabled compose files and pre-create every host-side volume
- * mount target as the current user. This prevents Docker from creating
- * them as root-owned, which causes EACCES inside non-root containers.
- *
- * For file mounts (basename contains a `.`), creates an empty file.
- * For directory mounts (basename has no `.`), creates the directory.
- *
- * Heuristic: a basename containing a `.` is treated as a file. This
- * intentionally includes leading-dot files (e.g. `.env`) because Docker
- * bind mounts to them must be regular files. Bare directory names like
- * `stack` or `addons` lack extensions and are created as directories.
+ * Parse enabled compose files and pre-create host-side volume mount
+ * targets under OP_HOME as the current user. This prevents Docker from
+ * creating them as root-owned, which causes EACCES inside non-root
+ * containers.
  *
  * Only mount sources under `state.homeDir` are touched; external paths
  * (e.g. `/var/run/docker.sock`) are left alone.
+ *
+ * The file-vs-directory distinction is best-effort and only applies to
+ * explicit OP_HOME paths.
  */
 export function ensureComposeVolumeTargets(state: ControlPlaneState): void {
-  const composeFiles = discoverStackOverlays(state.stackDir);
+  const composeFiles = discoverStackOverlays(state.stackDir, state.homeDir);
   if (composeFiles.length === 0) return;
 
   const envVars: Record<string, string> = {
     ...(process.env as Record<string, string>),
-    ...parseEnvFile(`${state.stackDir}/stack.env`),
+    ...parseEnvFile(`${state.stashDir}/env/stack.env`),
   };
+  const homeRoot = resolvePath(state.homeDir);
 
   for (const file of composeFiles) {
     let doc: Record<string, unknown>;
@@ -291,18 +242,20 @@ export function ensureComposeVolumeTargets(state: ControlPlaneState): void {
 
         const hostPath = expandEnvVars(rawSource, envVars);
         if (!hostPath || !hostPath.startsWith('/')) continue;
-        if (existsSync(hostPath)) continue;
+        const resolvedHostPath = resolvePath(hostPath);
+        if (!resolvedHostPath.startsWith(`${homeRoot}/`) && resolvedHostPath !== homeRoot) continue;
+        if (existsSync(resolvedHostPath)) continue;
 
-        // A basename containing a `.` (anywhere, including leading) is a file.
-        // Bare names like `stack` or `data` are directories.
-        const basename = hostPath.split('/').pop() ?? '';
+        // Only create mounts under OP_HOME. For now, treat existing explicit
+        // file paths as files and directory paths as directories.
+        const basename = resolvedHostPath.split('/').pop() ?? '';
         const isFile = basename.includes('.');
 
         if (isFile) {
-          mkdirSync(dirname(hostPath), { recursive: true });
-          writeFileSync(hostPath, '');
+          mkdirSync(dirname(resolvedHostPath), { recursive: true });
+          writeFileSync(resolvedHostPath, '');
         } else {
-          mkdirSync(hostPath, { recursive: true });
+          mkdirSync(resolvedHostPath, { recursive: true });
         }
       }
     }
@@ -322,24 +275,25 @@ export function writeRuntimeFiles(
     writeFileSync(composePath, state.artifacts.compose);
   }
 
-  // Load persisted channel HMAC secrets from guardian.env,
-  // then generate new ones for new channel addons.
-  const channelSecrets = readChannelSecrets(state.stackDir);
+  for (const name of ['services.compose.yml', 'channels.compose.yml', 'custom.compose.yml']) {
+    const path = `${state.stackDir}/${name}`;
+    if (!existsSync(path)) writeFileSync(path, readBundledStackAsset(name));
+  }
+
   for (const addon of listEnabledAddonIds(state.homeDir)) {
-    const composePath = `${state.stackDir}/addons/${addon}/compose.yml`;
-    if (isChannelAddon(composePath) && !channelSecrets[addon]) {
-      channelSecrets[addon] = randomHex(16);
+    if (['api', 'chat', 'discord', 'slack'].includes(addon)) {
+      for (const channel of ['api', 'chat', 'discord', 'slack']) {
+        ensureChannelSecret(state.stackDir, channel);
+      }
+      break;
     }
   }
 
-  // Write channel secrets to guardian.env (the canonical source)
-  writeChannelSecrets(state.stackDir, channelSecrets);
-
-  // Write system.env (no channel secrets — those live in guardian.env)
+  // Write stack.env (no secrets — those live in knowledge/secrets/)
   writeSystemEnv(state);
 
   // Ensure state directory exists
-  mkdirSync(state.stateDir, { recursive: true });
+  mkdirSync(state.dataDir, { recursive: true });
 
   state.artifactMeta = buildRuntimeFileMeta(state.artifacts);
 }

package/src/control-plane/core-assets.test.ts

@@ -11,21 +11,21 @@ describe("seedStashAssets", () => {
   beforeEach(() => {
     homeDir = mkdtempSync(join(tmpdir(), "stash-seed-test-"));
     process.env.OP_HOME = homeDir;
-    mkdirSync(join(homeDir, "stash"), { recursive: true });
+    mkdirSync(join(homeDir, "knowledge"), { recursive: true });
   });
 
   afterEach(() => {
     process.env.OP_HOME = originalHome;
     // Restore writable mode in case a test chmod'd the stash dir.
     try {
-      chmodSync(join(homeDir, "stash"), 0o755);
+      chmodSync(join(homeDir, "knowledge"), 0o755);
     } catch {
       // ignore — dir may not exist
     }
     rmSync(homeDir, { recursive: true, force: true });
   });
 
-  it("writes every seed under stash/ on first run", () => {
+  it("writes every seed under knowledge/ on first run", () => {
     const seeds = {
       "skills/test-skill/SKILL.md": "---\nname: test-skill\ntype: skill\n---\nhello\n",
       "commands/test-cmd.md": "---\nname: test-cmd\ntype: command\n---\nrun me\n",
@@ -34,7 +34,7 @@ describe("seedStashAssets", () => {
 
     expect(written.sort()).toEqual(Object.keys(seeds).sort());
     for (const [rel, content] of Object.entries(seeds)) {
-      const target = join(homeDir, "stash", rel);
+      const target = join(homeDir, "knowledge", rel);
       expect(existsSync(target)).toBe(true);
       expect(readFileSync(target, "utf-8")).toBe(content);
     }
@@ -46,7 +46,7 @@ describe("seedStashAssets", () => {
 
     // Simulate a previous install: seed first.
     seedStashAssets(seeds);
-    const target = join(homeDir, "stash/skills/keep-mine/SKILL.md");
+    const target = join(homeDir, "knowledge/skills/keep-mine/SKILL.md");
     expect(readFileSync(target, "utf-8")).toBe("ORIGINAL SEED\n");
 
     // User edits the file.
@@ -58,10 +58,10 @@ describe("seedStashAssets", () => {
     expect(readFileSync(target, "utf-8")).toBe(userEdit);
   });
 
-  it("creates nested directories under stash/ as needed", () => {
+  it("creates nested directories under knowledge/ as needed", () => {
     const seeds = { "skills/deep/nested/asset/SKILL.md": "x" };
     seedStashAssets(seeds);
-    expect(existsSync(join(homeDir, "stash/skills/deep/nested/asset/SKILL.md"))).toBe(true);
+    expect(existsSync(join(homeDir, "knowledge/skills/deep/nested/asset/SKILL.md"))).toBe(true);
   });
 
   it("returns an empty list when called with no seeds", () => {
@@ -70,7 +70,7 @@ describe("seedStashAssets", () => {
 
   it("rejects seed keys that escape the stash directory", () => {
     // Path-traversal guard: ../ sequences in keys must throw rather than
-    // silently writing outside stash/.
+    // silently writing outside knowledge/.
     expect(() =>
       seedStashAssets({ "../../etc/cron.d/evil": "owned\n" }),
     ).toThrow(/escapes stash dir/);
@@ -91,7 +91,7 @@ describe("seedStashAssets", () => {
     const uid = process.getuid?.();
     if (uid === 0) return;
 
-    const stashDir = join(homeDir, "stash");
+    const stashDir = join(homeDir, "knowledge");
     chmodSync(stashDir, 0o555);
     try {
       expect(() =>