@openpalm/lib 0.10.2 → 0.11.0-beta.10

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

@@ -6,67 +6,55 @@
  * 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 { resolveOperatorIds, hasUsableOperatorId } from "./operator-ids.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)) {
@@ -82,45 +70,60 @@ export function writeSystemEnv(state: ControlPlaneState): void {
     OP_SETUP_COMPLETE: alreadyComplete ? "true" : "false"
   };
 
+  // Backfill OP_UID/OP_GID when the existing stack.env was written by an
+  // older code path that hard-coded 1000, or when the file was created
+  // with missing/zero values. We only override when the current value is
+  // 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);
+  }
+
   const content = mergeEnvContent(base, adminManaged, {
     sectionHeader: "# ── Admin-managed ──────────────────────────────────────────────────"
   });
 
-  writeFileSync(systemEnvPath, content);
+  writeFileSync(systemEnvPath, content, { mode: 0o600 });
+  chmodSync(systemEnvPath, 0o600);
 }
 
 function generateFallbackSystemEnv(state: ControlPlaneState): string {
-  const uid = typeof process.getuid === "function" ? (process.getuid() ?? 1000) : 1000;
-  const gid = typeof process.getgid === "function" ? (process.getgid() ?? 1000) : 1000;
+  // 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
+  // meaning on the host process.
+  const ids = resolveOperatorIds(state.homeDir);
+  const idLines: string[] = ids
+    ? [`OP_UID=${ids.uid}`, `OP_GID=${ids.gid}`]
+    : [];
 
   return [
     "# OpenPalm — System Configuration (managed by CLI/admin)",
     "# Auto-generated fallback.",
     "",
     "# ── Authentication ──────────────────────────────────────────────────",
-    `OP_ADMIN_TOKEN=\${OP_ADMIN_TOKEN}`,
-    `OP_ASSISTANT_TOKEN=\${OP_ASSISTANT_TOKEN}`,
+    `OP_UI_LOGIN_PASSWORD=\${OP_UI_LOGIN_PASSWORD}`,
     "",
     "# ── 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"}`,
+    ...idLines,
     "",
     "# ── Images ──────────────────────────────────────────────────────────",
     `OP_IMAGE_NAMESPACE=${process.env.OP_IMAGE_NAMESPACE ?? "openpalm"}`,
     `OP_IMAGE_TAG=${DEFAULT_IMAGE_TAG}`,
     "",
     "# ── Ports (38XX range) ──────────────────────────────────────────────",
+    "# Guardian is network-only (no host port) — channels reach it via",
+    "# http://guardian:8080 over the channel_lan Docker network.",
     `OP_ASSISTANT_PORT=3800`,
     `OP_ADMIN_PORT=3880`,
     `OP_ADMIN_OPENCODE_PORT=3881`,
-    `OP_MEMORY_PORT=3898`,
-    `OP_GUARDIAN_PORT=3899`,
     ""
   ].join("\n");
 }
@@ -143,8 +146,21 @@ export function discoverStackOverlays(stackDir: string): string[] {
       .filter((e) => e.isDirectory())
       .sort((a, b) => a.name.localeCompare(b.name));
     for (const entry of entries) {
-      const addonCompose = `${addonsDir}/${entry.name}/compose.yml`;
-      if (existsSync(addonCompose)) files.push(addonCompose);
+      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}`);
     }
   }
 
@@ -191,19 +207,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 +239,107 @@ 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.stackDir);
+  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/ only on first install —
+  // refreshCoreAssets() is the canonical writer on update.
+  mkdirSync(state.stackDir, { recursive: true });
+  const composePath = `${state.stackDir}/core.compose.yml`;
+  if (!existsSync(composePath)) {
+    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.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,109 @@
  *
  * 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 { fileURLToPath } from "node:url";
+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";
 
+function resolveAssetVersion(): string {
+  if (process.env.OP_ASSET_VERSION) return process.env.OP_ASSET_VERSION;
+  try {
+    const pkgJson = JSON.parse(
+      readFileSync(join(dirname(fileURLToPath(import.meta.url)), "../../package.json"), "utf-8")
+    );
+    return `v${pkgJson.version}`;
+  } catch {
+    return "main";
+  }
+}
+const VERSION = resolveAssetVersion();
+
+// Persona files (openpalm.md, system.md), stash seeds, and user-editable config
+// files are intentionally NOT in this list. They are seeded once (never
+// overwritten) via seedOpenPalmDir (skipExisting) or SEEDED_ASSETS below.
 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" },
+];
+
+// Seeded once — written only when the file does not exist yet.
+// User edits always win; upgrade never touches these files.
+const SEEDED_ASSETS: { relPath: string; githubFilename: string }[] = [
+  { relPath: "config/assistant/opencode.jsonc", githubFilename: ".openpalm/config/assistant/opencode.jsonc" },
 ];
 
 async function downloadAsset(filename: string): Promise<string> {
@@ -140,5 +154,44 @@ export async function refreshCoreAssets(): Promise<{
     updated.push(asset.relPath);
   }
 
+  // Seed user-editable assets only when missing — never overwrite.
+  for (const asset of SEEDED_ASSETS) {
+    const targetPath = join(homeDir, asset.relPath);
+    if (existsSync(targetPath)) continue;
+    const freshContent = await downloadAsset(asset.githubFilename);
+    mkdirSync(dirname(targetPath), { recursive: true });
+    writeFileSync(targetPath, freshContent);
+    updated.push(asset.relPath);
+  }
+
   return { backupDir, updated };
 }
+
+// ── Assistant Persona File Seeding ────────────────────────────────────
+
+/**
+ * Seed assistant persona files (openpalm.md, system.md) into OP_HOME.
+ *
+ * Idempotent: **never overwrites** an existing file — user edits always
+ * win. This preserves the "config/ is user-owned" contract: persona files
+ * are seeded once on first install and never touched again on update.
+ *
+ * `seeds` maps relative path keys (e.g. `"config/assistant/openpalm.md"`)
+ * to file content. Each file is written to `resolveOpenPalmHome()/<relPath>`
+ * only if the file does not already exist.
+ *
+ * Returns the list of relative paths that were actually written (empty on
+ * re-run when every seed already exists on disk).
+ */
+export function seedAssistantPersonaFiles(seeds: Record<string, string>): string[] {
+  const homeDir = resolveOpenPalmHome();
+  const written: string[] = [];
+  for (const [relPath, content] of Object.entries(seeds)) {
+    const targetPath = join(homeDir, relPath);
+    if (existsSync(targetPath)) continue;
+    mkdirSync(dirname(targetPath), { recursive: true });
+    writeFileSync(targetPath, content);
+    written.push(relPath);
+  }
+  return written;
+}