@openpalm/lib 0.10.1 → 0.11.0-beta.1

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

@@ -15,16 +15,17 @@ import type { ControlPlaneState } from "./types.js";
 let tempDir: string;
 
 function makeState(overrides: Partial<ControlPlaneState> = {}): ControlPlaneState {
+  const configDir = join(tempDir, "config");
   return {
     adminToken: "test",
     assistantToken: "test",
-    setupToken: "test",
     homeDir: tempDir,
-    configDir: join(tempDir, "config"),
-    vaultDir: join(tempDir, "vault"),
-    dataDir: join(tempDir, "data"),
-    logsDir: join(tempDir, "logs"),
+    configDir,
+    stashDir: join(tempDir, "stash"),
+    workspaceDir: join(tempDir, "workspace"),
     cacheDir: join(tempDir, "cache"),
+    stateDir: join(tempDir, "state"),
+    stackDir: join(configDir, "stack"),
     services: {},
     artifacts: { compose: "" },
     artifactMeta: [],
@@ -34,28 +35,25 @@ function makeState(overrides: Partial<ControlPlaneState> = {}): ControlPlaneStat
 }
 
 function seedCoreCompose(): void {
-  const stackDir = join(tempDir, "stack");
+  const stackDir = join(tempDir, "config", "stack");
   mkdirSync(stackDir, { recursive: true });
   writeFileSync(join(stackDir, "core.compose.yml"), "services: {}");
 }
 
-function seedEnvFiles(files: { stack?: boolean; user?: boolean; guardian?: boolean } = {}): void {
+function seedEnvFiles(files: { stack?: boolean; guardian?: boolean } = {}): void {
+  const stackDir = join(tempDir, "config", "stack");
   if (files.stack) {
-    mkdirSync(join(tempDir, "vault", "stack"), { recursive: true });
-    writeFileSync(join(tempDir, "vault", "stack", "stack.env"), "KEY=val");
-  }
-  if (files.user) {
-    mkdirSync(join(tempDir, "vault", "user"), { recursive: true });
-    writeFileSync(join(tempDir, "vault", "user", "user.env"), "SECRET=val");
+    mkdirSync(stackDir, { recursive: true });
+    writeFileSync(join(stackDir, "stack.env"), "KEY=val");
   }
   if (files.guardian) {
-    mkdirSync(join(tempDir, "vault", "stack"), { recursive: true });
-    writeFileSync(join(tempDir, "vault", "stack", "guardian.env"), "CHANNEL_CHAT_SECRET=abc");
+    mkdirSync(stackDir, { recursive: true });
+    writeFileSync(join(stackDir, "guardian.env"), "CHANNEL_CHAT_SECRET=abc");
   }
 }
 
 function seedAddon(name: string): void {
-  const addonDir = join(tempDir, "stack", "addons", name);
+  const addonDir = join(tempDir, "config", "stack", "addons", name);
   mkdirSync(addonDir, { recursive: true });
   writeFileSync(join(addonDir, "compose.yml"), "services: {}");
 }
@@ -98,13 +96,16 @@ describe("buildComposeOptions", () => {
   });
 
   it("returns env files in correct order", () => {
-    seedEnvFiles({ stack: true, user: true, guardian: true });
+    // Note: vault/user/user.env is no longer a
+    // compose env_file. The runtime env file list is: stack.env, guardian.env.
+    // Even when a legacy user.env is present on disk, it is intentionally
+    // excluded from the compose args.
+    seedEnvFiles({ stack: true, guardian: true });
     const state = makeState();
     const opts = buildComposeOptions(state);
-    expect(opts.envFiles).toHaveLength(3);
+    expect(opts.envFiles).toHaveLength(2);
     expect(opts.envFiles[0]).toContain("stack.env");
-    expect(opts.envFiles[1]).toContain("user.env");
-    expect(opts.envFiles[2]).toContain("guardian.env");
+    expect(opts.envFiles[1]).toContain("guardian.env");
   });
 
   it("excludes missing env files", () => {
@@ -136,8 +137,11 @@ describe("buildComposeCliArgs", () => {
   });
 
   it("includes --env-file flags for env files that exist", () => {
+    // Note: vault/user/user.env is no longer
+    // listed in the compose env_file set. Only stack.env and guardian.env
+    // (when present) are passed via --env-file.
     seedCoreCompose();
-    seedEnvFiles({ stack: true, user: true });
+    seedEnvFiles({ stack: true, guardian: true });
     const state = makeState();
     const args = buildComposeCliArgs(state);
     const envFileIndices = args.reduce<number[]>((acc, arg, i) => {

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

@@ -6,67 +6,54 @@
  * the rollback module (snapshot to ~/.cache/openpalm/rollback/).
  */
 import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, chmodSync } from "node:fs";
-import { parseEnvFile, mergeEnvContent } from './env.js';
+import { dirname } from "node:path";
+import { parse as yamlParse } from "yaml";
+import { parseEnvFile, mergeEnvContent, expandEnvVars } from './env.js';
 import type { ControlPlaneState, ArtifactMeta } from "./types.js";
 import { isChannelAddon } from "./channels.js";
-import { readStackSpec } from "./stack-spec.js";
-import { writeCapabilityVars } from "./spec-to-env.js";
 import { listEnabledAddonIds } from "./registry.js";
 
-import { generateRedactSchema } from "./redact-schema.js";
-import { readStackEnv } from "./secrets.js";
 import {
   readCoreCompose,
-  ensureUserEnvSchema,
-  ensureSystemEnvSchema,
 } 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";
 
-// ── Stack Config (stack.yml) ─────────────────────────────────────
-
-/**
- * Check whether Ollama is enabled via active stack/addons/ overlay.
- */
-export function isOllamaEnabled(state: ControlPlaneState): boolean {
-  return listEnabledAddonIds(state.homeDir).includes("ollama");
-}
-
-/**
- * Check whether admin is enabled via active stack/addons/ overlay.
- */
-export function isAdminEnabled(state: ControlPlaneState): boolean {
-  return listEnabledAddonIds(state.homeDir).includes("admin");
-}
-
 // ── Env File Management ──────────────────────────────────────────────
 
 /**
  * Return the env files used for docker compose --env-file args.
  * These are the live vault env files.
  *
- * Order: stack.env -> user.env -> guardian.env
+ * 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).
  */
 export function buildEnvFiles(state: ControlPlaneState): string[] {
   return [
-    `${state.vaultDir}/stack/stack.env`,
-    `${state.vaultDir}/user/user.env`,
-    `${state.vaultDir}/stack/guardian.env`,
+    `${state.stackDir}/stack.env`,
+    `${state.stackDir}/guardian.env`,
   ].filter(existsSync);
 }
 
 /**
- * Write system-managed values to vault/stack/stack.env.
+ * Write system-managed values to config/stack/stack.env.
  *
  * Channel HMAC secrets are NOT written here — they belong in guardian.env.
  * Use writeChannelSecrets() for channel secrets.
  */
 export function writeSystemEnv(state: ControlPlaneState): void {
-  mkdirSync(`${state.vaultDir}/stack`, { recursive: true });
+  mkdirSync(state.stackDir, { recursive: true });
 
-  const systemEnvPath = `${state.vaultDir}/stack/stack.env`;
+  const systemEnvPath = `${state.stackDir}/stack.env`;
 
   let base = "";
   if (existsSync(systemEnvPath)) {
@@ -98,18 +85,16 @@ function generateFallbackSystemEnv(state: ControlPlaneState): string {
     "# Auto-generated fallback.",
     "",
     "# ── Authentication ──────────────────────────────────────────────────",
-    `OP_ADMIN_TOKEN=\${OP_ADMIN_TOKEN}`,
+    `OP_UI_TOKEN=\${OP_UI_TOKEN}`,
     `OP_ASSISTANT_TOKEN=\${OP_ASSISTANT_TOKEN}`,
     "",
     "# ── Service Auth ─────────────────────────────────────────────────────",
-    `OP_MEMORY_TOKEN=${process.env.OP_MEMORY_TOKEN ?? ""}`,
     "OP_OPENCODE_PASSWORD=",
     "",
     "# ── Paths ──────────────────────────────────────────────────────────",
     `OP_HOME=${state.homeDir}`,
     `OP_UID=${uid}`,
     `OP_GID=${gid}`,
-    `OP_DOCKER_SOCK=${process.env.OP_DOCKER_SOCK ?? "/var/run/docker.sock"}`,
     "",
     "# ── Images ──────────────────────────────────────────────────────────",
     `OP_IMAGE_NAMESPACE=${process.env.OP_IMAGE_NAMESPACE ?? "openpalm"}`,
@@ -119,7 +104,6 @@ function generateFallbackSystemEnv(state: ControlPlaneState): string {
     `OP_ASSISTANT_PORT=3800`,
     `OP_ADMIN_PORT=3880`,
     `OP_ADMIN_OPENCODE_PORT=3881`,
-    `OP_MEMORY_PORT=3898`,
     `OP_GUARDIAN_PORT=3899`,
     ""
   ].join("\n");
@@ -191,19 +175,19 @@ function extractChannelSecrets(parsed: Record<string, string>): Record<string, s
 }
 
 /**
- * Read channel HMAC secrets from vault/stack/guardian.env.
+ * Read channel HMAC secrets from config/stack/guardian.env.
  */
-export function readChannelSecrets(vaultDir: string): Record<string, string> {
-  return extractChannelSecrets(parseEnvFile(`${vaultDir}/stack/guardian.env`));
+export function readChannelSecrets(stackDir: string): Record<string, string> {
+  return extractChannelSecrets(parseEnvFile(`${stackDir}/guardian.env`));
 }
 
 /**
- * Write channel HMAC secrets to vault/stack/guardian.env.
+ * Write channel HMAC secrets to state/guardian.env.
  * Merges with existing content; does not overwrite unrelated entries.
  */
-export function writeChannelSecrets(vaultDir: string, secrets: Record<string, string>): void {
-  const guardianPath = `${vaultDir}/stack/guardian.env`;
-  mkdirSync(`${vaultDir}/stack`, { recursive: true });
+export function writeChannelSecrets(stackDir: string, secrets: Record<string, string>): void {
+  const guardianPath = `${stackDir}/guardian.env`;
+  mkdirSync(stackDir, { recursive: true });
 
   let base = "";
   if (existsSync(guardianPath)) {
@@ -223,48 +207,103 @@ export function writeChannelSecrets(vaultDir: string, secrets: Record<string, st
   chmodSync(guardianPath, 0o600);
 }
 
+// ── 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.
+ *
+ * Only mount sources under `state.homeDir` are touched; external paths
+ * (e.g. `/var/run/docker.sock`) are left alone.
+ */
+export function ensureComposeVolumeTargets(state: ControlPlaneState): void {
+  const composeFiles = discoverStackOverlays(`${state.homeDir}/stack`);
+  if (composeFiles.length === 0) return;
+
+  const envVars: Record<string, string> = {
+    ...(process.env as Record<string, string>),
+    ...parseEnvFile(`${state.stackDir}/stack.env`),
+  };
+
+  for (const file of composeFiles) {
+    let doc: Record<string, unknown>;
+    try {
+      doc = yamlParse(readFileSync(file, 'utf-8')) as Record<string, unknown>;
+    } catch {
+      continue;
+    }
+    const services = doc?.services;
+    if (!services || typeof services !== 'object') continue;
+
+    for (const svc of Object.values(services as Record<string, unknown>)) {
+      if (!svc || typeof svc !== 'object') continue;
+      const svcRecord = svc as Record<string, unknown>;
+      if (!Array.isArray(svcRecord.volumes)) continue;
+      for (const vol of svcRecord.volumes as unknown[]) {
+        const volRecord = typeof vol === 'object' && vol !== null
+          ? (vol as Record<string, unknown>)
+          : null;
+        const rawSource = typeof vol === 'string'
+          ? vol.split(':')[0]
+          : String(volRecord?.source ?? '');
+        if (!rawSource) continue;
+
+        const hostPath = expandEnvVars(rawSource, envVars);
+        if (!hostPath || !hostPath.startsWith('/')) continue;
+        if (existsSync(hostPath)) continue;
+
+        // A basename containing a `.` (anywhere, including leading) is a file.
+        // Bare names like `stack` or `data` are directories.
+        const basename = hostPath.split('/').pop() ?? '';
+        const isFile = basename.includes('.');
+
+        if (isFile) {
+          mkdirSync(dirname(hostPath), { recursive: true });
+          writeFileSync(hostPath, '');
+        } else {
+          mkdirSync(hostPath, { recursive: true });
+        }
+      }
+    }
+  }
+}
+
 // ── Persistence (direct-write to live paths) ────────────────────────
 
 export function writeRuntimeFiles(
   state: ControlPlaneState
 ): void {
-  // Write core compose to stack/
-  const stackDir = `${state.homeDir}/stack`;
-  mkdirSync(stackDir, { recursive: true });
-  writeFileSync(`${stackDir}/core.compose.yml`, state.artifacts.compose);
+  // Write core compose to config/stack/
+  mkdirSync(state.stackDir, { recursive: true });
+  writeFileSync(`${state.stackDir}/core.compose.yml`, state.artifacts.compose);
 
   // Load persisted channel HMAC secrets from guardian.env,
   // then generate new ones for new channel addons.
-  const channelSecrets = readChannelSecrets(state.vaultDir);
-  const addonStackDir = `${state.homeDir}/stack`;
+  const channelSecrets = readChannelSecrets(state.stackDir);
   for (const addon of listEnabledAddonIds(state.homeDir)) {
-    const composePath = `${addonStackDir}/addons/${addon}/compose.yml`;
+    const composePath = `${state.stackDir}/addons/${addon}/compose.yml`;
     if (isChannelAddon(composePath) && !channelSecrets[addon]) {
       channelSecrets[addon] = randomHex(16);
     }
   }
 
   // Write channel secrets to guardian.env (the canonical source)
-  writeChannelSecrets(state.vaultDir, channelSecrets);
+  writeChannelSecrets(state.stackDir, channelSecrets);
 
   // Write system.env (no channel secrets — those live in guardian.env)
   writeSystemEnv(state);
 
-  // Ensure env schema directories exist
-  ensureUserEnvSchema();
-  ensureSystemEnvSchema();
-
-  const spec = readStackSpec(state.configDir);
-  // Write OP_CAP_* capability vars to stack.env from stack spec
-  if (spec) {
-    writeCapabilityVars(spec, state.vaultDir);
-  }
-
-  // Generate redact.env.schema from canonical mappings
-  const systemEnv = readStackEnv(state.vaultDir);
-  const redactDir = `${state.dataDir}/secrets`;
-  mkdirSync(redactDir, { recursive: true });
-  writeFileSync(`${redactDir}/redact.env.schema`, generateRedactSchema(systemEnv));
+  // Ensure state directory exists
+  mkdirSync(state.stateDir, { recursive: true });
 
   state.artifactMeta = buildRuntimeFileMeta(state.artifacts);
 }

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

@@ -0,0 +1,104 @@
+import { describe, expect, it, beforeEach, afterEach } from "bun:test";
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { seedStashAssets } from "./core-assets.js";
+
+describe("seedStashAssets", () => {
+  let homeDir: string;
+  const originalHome = process.env.OP_HOME;
+
+  beforeEach(() => {
+    homeDir = mkdtempSync(join(tmpdir(), "stash-seed-test-"));
+    process.env.OP_HOME = homeDir;
+    mkdirSync(join(homeDir, "stash"), { 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);
+    } catch {
+      // ignore — dir may not exist
+    }
+    rmSync(homeDir, { recursive: true, force: true });
+  });
+
+  it("writes every seed under stash/ 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",
+    };
+    const written = seedStashAssets(seeds);
+
+    expect(written.sort()).toEqual(Object.keys(seeds).sort());
+    for (const [rel, content] of Object.entries(seeds)) {
+      const target = join(homeDir, "stash", rel);
+      expect(existsSync(target)).toBe(true);
+      expect(readFileSync(target, "utf-8")).toBe(content);
+    }
+  });
+
+  it("does not overwrite existing files (user edits win)", () => {
+    const seeds = { "skills/keep-mine/SKILL.md": "ORIGINAL SEED\n" };
+    const userEdit = "USER EDIT — must not be overwritten\n";
+
+    // Simulate a previous install: seed first.
+    seedStashAssets(seeds);
+    const target = join(homeDir, "stash/skills/keep-mine/SKILL.md");
+    expect(readFileSync(target, "utf-8")).toBe("ORIGINAL SEED\n");
+
+    // User edits the file.
+    writeFileSync(target, userEdit);
+
+    // Re-run: must return [] and leave the user's content intact.
+    const written = seedStashAssets(seeds);
+    expect(written).toEqual([]);
+    expect(readFileSync(target, "utf-8")).toBe(userEdit);
+  });
+
+  it("creates nested directories under stash/ 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);
+  });
+
+  it("returns an empty list when called with no seeds", () => {
+    expect(seedStashAssets({})).toEqual([]);
+  });
+
+  it("rejects seed keys that escape the stash directory", () => {
+    // Path-traversal guard: ../ sequences in keys must throw rather than
+    // silently writing outside stash/.
+    expect(() =>
+      seedStashAssets({ "../../etc/cron.d/evil": "owned\n" }),
+    ).toThrow(/escapes stash dir/);
+
+    // Confirm the malicious payload was NOT written anywhere relative to
+    // the temp home.
+    expect(existsSync(join(homeDir, "..", "..", "etc", "cron.d", "evil"))).toBe(false);
+  });
+
+  it("rejects seed keys that traverse through the stash dir back out", () => {
+    expect(() =>
+      seedStashAssets({ "skills/../../../escape.md": "x" }),
+    ).toThrow(/escapes stash dir/);
+  });
+
+  it("surfaces errors when the stash directory is read-only", () => {
+    // Skip when running as root (chmod is a no-op for the superuser).
+    const uid = process.getuid?.();
+    if (uid === 0) return;
+
+    const stashDir = join(homeDir, "stash");
+    chmodSync(stashDir, 0o555);
+    try {
+      expect(() =>
+        seedStashAssets({ "skills/readonly/SKILL.md": "nope\n" }),
+      ).toThrow();
+    } finally {
+      chmodSync(stashDir, 0o755);
+    }
+  });
+});

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

@@ -3,95 +3,92 @@
  *
  * Manages source-of-truth files for the ~/.openpalm/ layout:
  *   stack/              — compose runtime assets (core.compose.yml)
- *   vault/              — env schemas
  *
  * This module manages runtime-owned core files only.
  * Registry catalog refresh is handled separately in registry.ts.
- * All ensure* functions verify that the expected files exist at OP_HOME.
- * They create directories as needed but do NOT write file content — that
- * is the responsibility of `refreshCoreAssets()` (GitHub download) or
- * the CLI install command (which downloads assets before calling setup).
+ * Env validation has moved to `akm vault` + the in-house redactor — the
+ * historical `.env.schema` files (varlock format) were retired in #391.
  */
 import { mkdirSync, writeFileSync, readFileSync, existsSync, copyFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { resolveDataDir, resolveVaultDir, resolveOpenPalmHome, resolveBackupsDir } from "./home.js";
+import { dirname, join, resolve, sep } from "node:path";
+import { resolveStateDir, resolveOpenPalmHome, resolveBackupsDir, resolveStashDir } from "./home.js";
 import { createLogger } from "../logger.js";
 import { sha256 } from "./crypto.js";
 
 const logger = createLogger("core-assets");
 
-// ── Env Schema Files (vault/) ────────────────────────────────────────
-
-/**
- * Ensure the user env schema directory exists and return the expected
- * schema file path. The file itself may not exist yet — it is written
- * by refreshCoreAssets() or the CLI install command.
- */
-export function ensureUserEnvSchema(): string {
-  const vaultDir = resolveVaultDir();
-  const dir = `${vaultDir}/user`;
-  mkdirSync(dir, { recursive: true });
-  const path = `${dir}/user.env.schema`;
-  return path;
-}
-
-/**
- * Ensure the system env schema directory exists and return the expected
- * schema file path. The file itself may not exist yet — it is written
- * by refreshCoreAssets() or the CLI install command.
- */
-export function ensureSystemEnvSchema(): string {
-  const vaultDir = resolveVaultDir();
-  const dir = `${vaultDir}/stack`;
-  mkdirSync(dir, { recursive: true });
-  const path = `${dir}/stack.env.schema`;
-  return path;
-}
-
-// ── Memory data directory ────────────────────────────────────────────
-
-export function ensureMemoryDir(dataDir?: string): string {
-  const resolved = dataDir ?? resolveDataDir();
-  const dir = `${resolved}/memory`;
-  mkdirSync(dir, { recursive: true });
-  return dir;
-}
-
 // ── Core Compose (stack/) ─────────────────────────────────────────────
 
-function coreComposePath(): string {
-  return `${resolveOpenPalmHome()}/stack/core.compose.yml`;
-}
-
 export function ensureCoreCompose(): string {
-  const path = coreComposePath();
+  const path = `${resolveOpenPalmHome()}/config/stack/core.compose.yml`;
   mkdirSync(dirname(path), { recursive: true });
   return path;
 }
 
 export function readCoreCompose(): string {
-  const path = coreComposePath();
-  return readFileSync(path, "utf-8");
+  return readFileSync(`${resolveOpenPalmHome()}/config/stack/core.compose.yml`, "utf-8");
 }
 
 // ── OpenCode System Config ──────────────────────────────────────────
 
 export function ensureOpenCodeSystemConfig(): void {
-  const dir = `${resolveDataDir()}/assistant`;
+  const dir = `${resolveStateDir()}/assistant`;
   mkdirSync(dir, { recursive: true });
 }
 
+// ── Shared akm stash (skills / commands / agents) ────────────────────
+
+/**
+ * Seed the shared akm stash with built-in skills / commands / agents.
+ *
+ * Idempotent: **never overwrites** an existing file — user edits to a
+ * seeded asset always win, which preserves the same "config doesn't
+ * overwrite user edits" contract that governs the rest of OP_HOME.
+ *
+ * Returns the list of stash-relative paths that were actually written
+ * (empty on re-run when every seed already exists on disk).
+ *
+ * `seeds` is a map of stash-relative path → file content. Keys MUST be
+ * forward-slash relative paths that stay inside `data/stash/`; any key
+ * that escapes the stash directory after canonicalization throws,
+ * preventing a malicious caller from writing arbitrary files. Source of
+ * truth for the seeded files lives at `.openpalm/stash/` in the
+ * repo; the CLI embeds them at build time and passes the embedded
+ * record directly.
+ */
+export function seedStashAssets(seeds: Record<string, string>): string[] {
+  const stashDir = resolveStashDir();
+  const normalizedStash = resolve(stashDir);
+  const written: string[] = [];
+  for (const [relPath, content] of Object.entries(seeds)) {
+    const targetPath = join(stashDir, relPath);
+    const normalizedTarget = resolve(targetPath);
+    if (
+      normalizedTarget !== normalizedStash &&
+      !normalizedTarget.startsWith(normalizedStash + sep)
+    ) {
+      throw new Error(`Seed path escapes stash dir: ${relPath}`);
+    }
+    if (existsSync(targetPath)) continue;
+    mkdirSync(dirname(targetPath), { recursive: true });
+    writeFileSync(targetPath, content);
+    written.push(relPath);
+  }
+  return written;
+}
+
 // ── Asset Refresh (GitHub download) ──────────────────────────────────
 
 const REPO = "itlackey/openpalm";
 const VERSION = process.env.OP_ASSET_VERSION ?? "main";
 
+// Stash seeds are intentionally NOT in this list — they use seedStashAssets()
+// which never overwrites existing files (user edits win on re-install).
 const MANAGED_ASSETS: { relPath: string; githubFilename: string }[] = [
-  { relPath: "stack/core.compose.yml", githubFilename: ".openpalm/stack/core.compose.yml" },
-  { relPath: "data/assistant/opencode.jsonc", githubFilename: "core/assistant/opencode/opencode.jsonc" },
-  { relPath: "data/assistant/AGENTS.md", githubFilename: "core/assistant/opencode/AGENTS.md" },
-  { relPath: "vault/user/user.env.schema", githubFilename: ".openpalm/vault/user/user.env.schema" },
-  { relPath: "vault/stack/stack.env.schema", githubFilename: ".openpalm/vault/stack/stack.env.schema" },
+  { relPath: "config/stack/core.compose.yml",        githubFilename: ".openpalm/config/stack/core.compose.yml" },
+  { relPath: "config/assistant/opencode.jsonc",      githubFilename: ".openpalm/config/assistant/opencode.jsonc" },
+  { relPath: "config/assistant/openpalm.md",         githubFilename: ".openpalm/config/assistant/openpalm.md" },
+  { relPath: "config/assistant/system.md",           githubFilename: ".openpalm/config/assistant/system.md" },
 ];
 
 async function downloadAsset(filename: string): Promise<string> {