@openpalm/lib 0.10.2 → 0.11.0-beta.2

package/src/control-plane/setup.ts

@@ -5,35 +5,48 @@
  * This module does NOT include Docker operations (compose up, image pull, etc.)
  * — those happen separately in the caller after setup completes.
  */
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
-import { randomBytes } from "node:crypto";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync } from "node:fs";
+import { join } from "node:path";
 import { createLogger } from "../logger.js";
 import {
   PROVIDER_KEY_MAP,
-  EMBEDDING_DIMS,
-  OLLAMA_INSTACK_URL,
 } from "../provider-constants.js";
 import { mergeEnvContent } from "./env.js";
 import { ensureHomeDirs } from "./home.js";
+import { acquireInstallLock, releaseInstallLock, type InstallLockHandle } from "./install-lock.js";
 import {
   ensureSecrets,
   updateSecretsEnv,
   updateSystemSecretsEnv,
   ensureOpenCodeConfig,
   readStackEnv,
+  writeAuthJsonProviderKeys,
 } from "./secrets.js";
-import { ensureOpenCodeSystemConfig, ensureMemoryDir } from "./core-assets.js";
-import { createState, writeSetupTokenFile } from "./lifecycle.js";
+import { ensureOpenCodeSystemConfig } from "./core-assets.js";
+import { createState } from "./lifecycle.js";
 import { writeStackSpec } from "./stack-spec.js";
-import type { StackSpec, StackSpecCapabilities } from "./stack-spec.js";
-import { writeCapabilityVars } from "./spec-to-env.js";
+import { writeVoiceVars } from "./spec-to-env.js";
 import type { ControlPlaneState } from "./types.js";
 import { validateSetupSpec } from "./setup-validation.js";
-import { listEnabledAddonIds } from "./registry.js";
+import { getRegistryAutomation, setAddonEnabled } from "./registry.js";
 export { validateSetupSpec } from "./setup-validation.js";
 
 const logger = createLogger("setup");
 
+// ── Atomic write helper ──────────────────────────────────────────────────
+
+/**
+ * Write `content` to `path` atomically: write to `path.tmp` first, then
+ * rename over the target. On POSIX this rename is atomic — a reader always
+ * sees either the old file or the new file, never a partially-written one.
+ * If the tmp write fails the original file is untouched.
+ */
+function writeFileAtomic(path: string, content: string | Uint8Array, mode?: number): void {
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, content, mode !== undefined ? { mode } : {});
+  renameSync(tmp, path);
+}
+
 // ── Types ────────────────────────────────────────────────────────────────
 
 export type SetupConnection = {
@@ -52,35 +65,32 @@ export type SetupResult = {
 
 export type SetupSpec = {
   version: 2;
-  capabilities: StackSpecCapabilities;
-  security: { adminToken: string };
+  llm?: { provider: string; model: string; baseUrl?: string };
+  embedding?: { provider: string; model: string; dims: number; baseUrl?: string };
+  tts?: { enabled?: boolean; engine?: string; provider?: string; baseURL?: string; model?: string; voice?: string };
+  stt?: { enabled?: boolean; engine?: string; provider?: string; baseURL?: string; model?: string; language?: string };
+  /**
+   * Operator-supplied UI login password. Persisted to stack.env as
+   * `OP_UI_LOGIN_PASSWORD`. Replaces the legacy `adminToken` field
+   * (Phase 4 of docs/technical/auth-and-proxy-refactor-plan.md).
+   */
+  security: { uiLoginPassword: string };
   owner?: { name?: string; email?: string };
   connections: SetupConnection[];
   channelCredentials?: Record<string, Record<string, string>>;
+  addons?: Record<string, boolean>;
+  imageTag?: string;
+  hostAkm?: boolean;
 };
 
 // ── Secrets Builder ──────────────────────────────────────────────────────
 
 /**
- * Map provider id → env var for a custom base URL override.
- * Allows writeCapabilityVars to resolve non-default endpoints.
+ * Build the stack.env update payload from a setup spec. Provider API
+ * keys are NOT included here — credentials live in OpenCode's auth.json
+ * (see buildAuthJsonFromSetup), not stack.env. This function returns
+ * only non-credential vars: owner identity and similar.
  */
-const PROVIDER_BASE_URL_ENV: Record<string, string> = {
-  openai: "OPENAI_BASE_URL",
-  anthropic: "ANTHROPIC_BASE_URL",
-  groq: "GROQ_BASE_URL",
-  mistral: "MISTRAL_BASE_URL",
-  together: "TOGETHER_BASE_URL",
-  deepseek: "DEEPSEEK_BASE_URL",
-  xai: "XAI_BASE_URL",
-  google: "GOOGLE_BASE_URL",
-  huggingface: "HF_BASE_URL",
-  ollama: "OLLAMA_BASE_URL",
-  lmstudio: "LMSTUDIO_BASE_URL",
-  "model-runner": "MODEL_RUNNER_BASE_URL",
-  "openai-compatible": "OPENAI_COMPATIBLE_BASE_URL",
-};
-
 export function buildSecretsFromSetup(
   connections: SetupConnection[],
   owner?: { name?: string; email?: string },
@@ -90,60 +100,51 @@ export function buildSecretsFromSetup(
   const ownerEmail = (owner?.email?.trim() ?? "").replace(/[\r\n\0]/g, "").slice(0, 200);
   if (ownerName) updates.OWNER_NAME = ownerName;
   if (ownerEmail) updates.OWNER_EMAIL = ownerEmail;
-
-  for (const cap of connections) {
-    // API key: spec value takes precedence, then fall back to environment
-    const envVar = PROVIDER_KEY_MAP[cap.provider];
-    if (envVar) {
-      const key = cap.apiKey || process.env[envVar] || "";
-      if (key) updates[envVar] = key;
-    }
-    // Persist user-configured base URL for any provider so writeCapabilityVars can resolve it
-    if (cap.baseUrl) {
-      const urlEnv = PROVIDER_BASE_URL_ENV[cap.provider];
-      if (urlEnv) updates[urlEnv] = cap.baseUrl;
-    }
-  }
+  void connections;
   return updates;
 }
 
 /**
- * Read auth.json and extract API keys for OAuth-authenticated providers.
- * This fills the gap where OAuth auth writes tokens to auth.json but
- * not to stack.env — the memory service needs them as env vars.
+ * Build the auth.json payload from a setup spec. Returns a record of
+ * `{ providerId: apiKey }` ready to feed into writeAuthJsonProviderKeys.
+ * Pulls keys from the spec first, falling back to the host process
+ * environment for the canonical env var name (e.g. OPENAI_API_KEY for
+ * provider "openai") so operators can preload keys via env before
+ * running the wizard.
  */
-export function extractAuthJsonKeys(vaultDir: string): Record<string, string> {
-  const authJsonPath = `${vaultDir}/stack/auth.json`;
-  if (!existsSync(authJsonPath)) return {};
-  try {
-    const raw = readFileSync(authJsonPath, "utf-8").trim();
-    if (!raw || raw === "{}") return {};
-    const auth = JSON.parse(raw) as Record<string, unknown>;
-    const updates: Record<string, string> = {};
-    for (const [provider, entry] of Object.entries(auth)) {
-      if (!entry || typeof entry !== "object") continue;
-      const record = entry as Record<string, unknown>;
-      // OpenCode stores API keys as { token: "..." } or { apiKey: "..." }
-      const token = (record.token ?? record.apiKey ?? record.api_key ?? record.key) as string | undefined;
-      if (token && typeof token === "string") {
-        const envVar = PROVIDER_KEY_MAP[provider];
-        if (envVar) updates[envVar] = token;
-      }
-    }
-    return updates;
-  } catch {
-    return {};
+export function buildAuthJsonFromSetup(
+  connections: SetupConnection[],
+): Record<string, string> {
+  const keys: Record<string, string> = {};
+  for (const cap of connections) {
+    const envVar = PROVIDER_KEY_MAP[cap.provider];
+    const key = cap.apiKey || (envVar ? process.env[envVar] : undefined) || "";
+    if (key) keys[cap.provider] = key;
   }
+  return keys;
 }
 
+/**
+ * Build the system-secret env update for the wizard / CLI install path.
+ *
+ * Phase 4 of the auth/proxy refactor collapsed the legacy
+ * `OP_UI_TOKEN` / `OP_ASSISTANT_TOKEN` pair into a single operator login
+ * secret (`OP_UI_LOGIN_PASSWORD`). The browser stores the cookie value =
+ * password; `requireAdmin()` compares the cookie against
+ * `process.env.OP_UI_LOGIN_PASSWORD` via the existing `safeTokenCompare`.
+ *
+ * `OP_OPENCODE_PASSWORD` is generated by `ensureSystemSecrets()` on first
+ * run and persists across reruns — it is not regenerated here.
+ *
+ * `existingSystemEnv` is unused now but the parameter is kept so callers
+ * compile unchanged. It can be removed in a follow-up cleanup.
+ */
 export function buildSystemSecretsFromSetup(
-  adminToken: string,
-  existingSystemEnv: Record<string, string> = {}
+  uiLoginPassword: string,
+  _existingSystemEnv: Record<string, string> = {}
 ): Record<string, string> {
   return {
-    OP_ADMIN_TOKEN: adminToken,
-    OP_ASSISTANT_TOKEN: existingSystemEnv.OP_ASSISTANT_TOKEN || randomBytes(32).toString("hex"),
-    OP_MEMORY_TOKEN: existingSystemEnv.OP_MEMORY_TOKEN || randomBytes(32).toString("hex"),
+    OP_UI_LOGIN_PASSWORD: uiLoginPassword,
   };
 }
 
@@ -192,75 +193,159 @@ export async function performSetup(
   const validation = validateSetupSpec(input);
   if (!validation.valid) return { ok: false, error: validation.errors.join("; ") };
 
-  const { capabilities, security, owner, connections, channelCredentials } = input;
-  const state = opts?.state ?? createState(security.adminToken);
-  const ollamaEnabled = listEnabledAddonIds(state.homeDir).includes("ollama");
-
-  logger.info("performing setup", { capabilityCount: connections.length, ollamaEnabled });
+  const { llm, embedding, tts, stt, security, owner, connections, channelCredentials, addons, imageTag, hostAkm } = input;
+  const state = opts?.state ?? createState();
 
-  // Apply Ollama in-stack URL override when addon is enabled
-  const effectiveConnections = ollamaEnabled
-    ? connections.map((c) => c.provider === "ollama" ? { ...c, baseUrl: OLLAMA_INSTACK_URL } : c)
-    : connections;
-  const updates = buildSecretsFromSetup(effectiveConnections, owner);
-
-  // Merge OAuth-authenticated provider keys from auth.json
-  // (OAuth flows store tokens in auth.json, not in the setup payload)
-  const oauthKeys = extractAuthJsonKeys(state.vaultDir);
-  for (const [key, value] of Object.entries(oauthKeys)) {
-    // Only fill in keys that weren't already provided via API key entry
-    if (!updates[key]) updates[key] = value;
+  // Acquire install lock to prevent two concurrent setup runs from racing on
+  // the same config directory. The lock lives in stateDir so it is co-located
+  // with runtime state and the same path startDeploy uses.
+  const lockHandle: InstallLockHandle | null = acquireInstallLock(state.stateDir);
+  if (lockHandle === null) {
+    return {
+      ok: false,
+      error:
+        "install_in_progress: Another install is in progress. Wait for it to finish, or remove state/.install.lock if you're sure no install is running.",
+    };
   }
 
-  // Persist vault env files
+  logger.info("performing setup", { connectionCount: connections.length });
+  const updates = buildSecretsFromSetup(connections, owner);
+  const providerKeys = buildAuthJsonFromSetup(connections);
+
+  // Wrap all persistence work in try/finally so the lock is ALWAYS released.
   try {
-    ensureHomeDirs();
-    ensureSecrets(state);
-    const existingSystemEnv = readStackEnv(state.vaultDir);
-    if (channelCredentials) Object.assign(updates, buildChannelCredentialEnvVars(channelCredentials));
-    // Pick up channel credential env vars not already provided in the spec
-    for (const mapping of Object.values(CHANNEL_CREDENTIAL_ENV_MAP)) {
-      for (const envKey of Object.values(mapping)) {
-        if (!updates[envKey] && process.env[envKey]) updates[envKey] = process.env[envKey];
+    // Persist vault env files + OpenCode auth.json
+    try {
+      ensureHomeDirs();
+      ensureSecrets(state);
+      const existingSystemEnv = readStackEnv(state.stackDir);
+      if (channelCredentials) Object.assign(updates, buildChannelCredentialEnvVars(channelCredentials));
+      // Pick up channel credential env vars not already provided in the spec
+      for (const mapping of Object.values(CHANNEL_CREDENTIAL_ENV_MAP)) {
+        for (const envKey of Object.values(mapping)) {
+          if (!updates[envKey] && process.env[envKey]) updates[envKey] = process.env[envKey];
+        }
       }
+      updateSecretsEnv(state, updates);
+      updateSystemSecretsEnv(state, buildSystemSecretsFromSetup(security.uiLoginPassword, existingSystemEnv));
+      // Provider API keys land in OpenCode's auth.json (bind-mounted into
+      // the assistant container) — never in stack.env.
+      writeAuthJsonProviderKeys(state, providerKeys);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      logger.error("failed to persist setup outputs", { error: message });
+      return { ok: false, error: `Failed to persist setup outputs: ${message}` };
     }
-    updateSecretsEnv(state, updates);
-    updateSystemSecretsEnv(state, buildSystemSecretsFromSetup(security.adminToken, existingSystemEnv));
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    logger.error("failed to update vault env files", { error: message });
-    return { ok: false, error: `Failed to update vault env files: ${message}` };
-  }
 
-  state.adminToken = security.adminToken;
-  state.assistantToken = readStackEnv(state.vaultDir).OP_ASSISTANT_TOKEN ?? state.assistantToken;
-  writeSetupTokenFile(state);
+    // Everything from here through the OP_SETUP_COMPLETE write is wrapped in a
+    // single try/catch so that a disk-full or permission-denied mid-way returns a
+    // clean error rather than leaving a broken half-installed ~/.openpalm/.
+    try {
+      // Write stack.yml (version marker only)
+      writeStackSpec(state.stackDir, { version: 2 });
+
+      // Write image tag and AKM mount paths to stack.env — atomic to avoid
+      // partial writes if the process is interrupted mid-write.
+      const systemEnvForAkm = existsSync(`${state.stackDir}/stack.env`)
+        ? readFileSync(`${state.stackDir}/stack.env`, "utf-8")
+        : "";
+      const akmUpdates: Record<string, string> = {};
+      if (imageTag) akmUpdates.OP_IMAGE_TAG = imageTag;
+      if (hostAkm) {
+        const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+        if (home) {
+          akmUpdates.OP_AKM_STASH = `${home}/akm`;
+          akmUpdates.OP_AKM_DATA = `${home}/.local/share/akm`;
+          akmUpdates.OP_AKM_STATE = `${home}/.local/state/akm`;
+          akmUpdates.OP_AKM_CACHE = `${home}/.cache/akm`;
+          akmUpdates.OP_AKM_CONFIG = `${home}/.config/akm`;
+        }
+      }
+      if (Object.keys(akmUpdates).length > 0) {
+        writeFileAtomic(`${state.stackDir}/stack.env`, mergeEnvContent(systemEnvForAkm, akmUpdates), 0o600);
+      }
+
+      // Write akm config with LLM and embedding settings from setup — atomic.
+      if (llm || embedding) {
+        const akmConfigDir = join(state.configDir, "akm");
+        mkdirSync(akmConfigDir, { recursive: true });
+        const akmConfigPath = join(akmConfigDir, "config.json");
+        let existing: Record<string, unknown> = {};
+        if (existsSync(akmConfigPath)) {
+          try { existing = JSON.parse(readFileSync(akmConfigPath, "utf-8")); } catch { /* ignore corrupt */ }
+        }
+        const updated = { ...existing };
+        if (llm) {
+          const base = llm.baseUrl ? llm.baseUrl.replace(/\/+$/, "") : "";
+          updated.llm = {
+            ...((existing.llm as Record<string, unknown>) ?? {}),
+            endpoint: base ? `${base}/chat/completions` : "",
+            model: llm.model,
+            provider: llm.provider,
+          };
+        }
+        if (embedding) {
+          const base = embedding.baseUrl ? embedding.baseUrl.replace(/\/+$/, "") : "";
+          updated.embedding = {
+            ...((existing.embedding as Record<string, unknown>) ?? {}),
+            endpoint: base ? `${base}/embeddings` : "",
+            model: embedding.model,
+            provider: embedding.provider,
+            dimension: embedding.dims,
+          };
+        }
+        writeFileAtomic(akmConfigPath, JSON.stringify(updated, null, 2), 0o600);
+      }
 
-  // Write stack.yml and OP_CAP_* capability vars to stack.env
-  writeMemoryAndStackConfigs({ version: 2, capabilities }, state);
+      // Write TTS/STT vars to stack.env for the voice channel
+      if (tts || stt) {
+        writeVoiceVars({ tts, stt }, state.stackDir);
+      }
 
-  ensureOpenCodeConfig();
-  ensureOpenCodeSystemConfig();
-  ensureMemoryDir();
+      // Enable requested addons (channels like discord, slack, etc.)
+      // setAddonEnabled copies the compose overlay AND generates CHANNEL_<NAME>_SECRET in guardian.env
+      if (addons) {
+        for (const [name, enabled] of Object.entries(addons)) {
+          if (enabled) setAddonEnabled(state.homeDir, state.stackDir, name, true);
+        }
+      }
 
-  // Mark setup complete in vault/stack/stack.env (where isSetupComplete reads it)
-  const systemEnvPath = `${state.vaultDir}/stack/stack.env`;
-  const systemBase = existsSync(systemEnvPath) ? readFileSync(systemEnvPath, "utf-8") : "";
-  writeFileSync(systemEnvPath, mergeEnvContent(systemBase, { OP_SETUP_COMPLETE: "true" }), { mode: 0o600 });
+      ensureOpenCodeConfig();
+      ensureOpenCodeSystemConfig();
 
-  logger.info("setup complete", { capabilityCount: connections.length });
-  return { ok: true };
-}
+      // Seed default automation into the AKM stash. Idempotent — existing files
+      // are left alone so user edits survive re-install and upgrade.
+      const tasksDir = join(state.stashDir, "tasks");
+      mkdirSync(tasksDir, { recursive: true });
+      const akmImproveDest = join(tasksDir, "akm-improve.md");
+      if (!existsSync(akmImproveDest)) {
+        const akmImproveMd = getRegistryAutomation("akm-improve");
+        if (akmImproveMd) {
+          writeFileSync(akmImproveDest, akmImproveMd);
+          logger.info("seeded default automation", { name: "akm-improve" });
+        } else {
+          logger.warn("default automation missing from registry; skipping seed", {
+            name: "akm-improve",
+          });
+        }
+      }
 
-/** Write stack.yml and OP_CAP_* capability vars to stack.env from the spec's capabilities. */
-function writeMemoryAndStackConfigs(spec: StackSpec, state: ControlPlaneState): void {
-  const { provider: embProvider, model: embModel } = spec.capabilities.embeddings;
-  const resolvedDims = spec.capabilities.embeddings.dims || EMBEDDING_DIMS[`${embProvider}/${embModel}`] || 1536;
+      // NOTE: OP_SETUP_COMPLETE is intentionally NOT written here. Writing it
+      // before the Docker deploy succeeds would mark setup "complete" even
+      // when containers fail to start, sending the user to a broken admin UI
+      // with no path back to the wizard. The flag is now written by
+      // setup-deploy.ts:startDeploy AFTER pollContainerHealth confirms every
+      // container is healthy.
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      logger.error("failed to complete setup persistence", { error: message });
+      return { ok: false, error: `Setup persistence failed: ${message}` };
+    }
 
-  const specToWrite: StackSpec = {
-    ...spec,
-    capabilities: { ...spec.capabilities, embeddings: { ...spec.capabilities.embeddings, dims: resolvedDims } },
-  };
-  writeStackSpec(state.configDir, specToWrite);
-  writeCapabilityVars(specToWrite, state.vaultDir);
+    logger.info("setup complete", { connectionCount: connections.length });
+    return { ok: true };
+  } finally {
+    // Always release the install lock, whether setup succeeded or failed.
+    releaseInstallLock(lockHandle);
+  }
 }

package/src/control-plane/skeleton-guardrail.test.ts

@@ -0,0 +1,151 @@
+/**
+ * Skeleton guardrail tests — validate .openpalm/ directory structure matches v0.11.0.
+ *
+ * The .openpalm/ directory is the repo-shipped OP_HOME skeleton. These tests
+ * prevent reintroduction of pre-v0.11.0 directories (stack/, registry/,
+ * stash-seeds/) and ensure the v0.11.0 structure stays intact.
+ */
+import { describe, test, expect } from "bun:test";
+import { readdirSync, statSync, existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const REPO_ROOT = resolve(import.meta.dir, "../../../..");
+const SKELETON_DIR = join(REPO_ROOT, ".openpalm");
+
+// Allowed top-level dirs in .openpalm/ — mirrors the OP_HOME runtime layout
+const ALLOWED_SOURCE_DIRS = new Set([
+  "config",     // seed files for config/ (assistant, guardian, stack/, akm/)
+  "stash",      // stash source assets: skills/ and vaults/
+  "state",      // state/registry/ + empty service dirs (.gitkeep)
+  "cache",      // empty cache dirs (.gitkeep — regenerable at runtime)
+  "workspace",  // empty workspace dir (.gitkeep)
+]);
+
+// ── Top-level structure ───────────────────────────────────────────────
+
+describe("skeleton: .openpalm/ top-level directories", () => {
+  test("only allowed directories exist", () => {
+    const entries = readdirSync(SKELETON_DIR);
+    const dirs = entries.filter(e => {
+      try { return statSync(join(SKELETON_DIR, e)).isDirectory(); } catch { return false; }
+    });
+    const unexpected = dirs.filter(d => !ALLOWED_SOURCE_DIRS.has(d));
+    expect(unexpected).toEqual([]);
+  });
+
+  test("stack/ no longer exists (moved to config/stack/)", () => {
+    expect(existsSync(join(SKELETON_DIR, "stack"))).toBe(false);
+  });
+
+  test("registry/ no longer exists (moved to state/registry/)", () => {
+    expect(existsSync(join(SKELETON_DIR, "registry"))).toBe(false);
+  });
+
+  test("stash-seeds/ no longer exists (moved to stash/)", () => {
+    expect(existsSync(join(SKELETON_DIR, "stash-seeds"))).toBe(false);
+  });
+});
+
+// ── config/ subdirectory ──────────────────────────────────────────────
+
+describe("skeleton: .openpalm/config/ structure", () => {
+  test("config/stack/ exists with core.compose.yml and stack.yml", () => {
+    expect(existsSync(join(SKELETON_DIR, "config", "stack", "core.compose.yml"))).toBe(true);
+    expect(existsSync(join(SKELETON_DIR, "config", "stack", "stack.yml"))).toBe(true);
+  });
+
+  test("config/stack/addons/ exists", () => {
+    expect(existsSync(join(SKELETON_DIR, "config", "stack", "addons"))).toBe(true);
+  });
+
+  test("config/akm/ exists", () => {
+    expect(existsSync(join(SKELETON_DIR, "config", "akm"))).toBe(true);
+  });
+
+  test("config/assistant/ has seed files", () => {
+    expect(existsSync(join(SKELETON_DIR, "config", "assistant", "opencode.json"))).toBe(true);
+  });
+});
+
+// ── state/registry/ subdirectory ─────────────────────────────────────
+
+describe("skeleton: .openpalm/state/registry/ structure", () => {
+  test("state/registry/addons/ exists with addon subdirectories", () => {
+    const addonsDir = join(SKELETON_DIR, "state", "registry", "addons");
+    expect(existsSync(addonsDir)).toBe(true);
+    const addons = readdirSync(addonsDir);
+    expect(addons).toContain("chat");
+    expect(addons).toContain("api");
+    expect(addons).toContain("discord");
+  });
+
+  test("state/registry/automations/ exists", () => {
+    expect(existsSync(join(SKELETON_DIR, "state", "registry", "automations"))).toBe(true);
+  });
+
+  test("each addon has compose.yml", () => {
+    const addonsDir = join(SKELETON_DIR, "state", "registry", "addons");
+    const addons = readdirSync(addonsDir).filter(e => {
+      try { return statSync(join(addonsDir, e)).isDirectory(); } catch { return false; }
+    });
+    for (const addon of addons) {
+      expect(existsSync(join(addonsDir, addon, "compose.yml"))).toBe(true);
+    }
+  });
+});
+
+// ── stash/ subdirectory ───────────────────────────────────────────────
+
+describe("skeleton: .openpalm/stash/ structure", () => {
+  test("stash/skills/ exists with config-diagnostics skill", () => {
+    expect(existsSync(join(SKELETON_DIR, "stash", "skills", "config-diagnostics", "SKILL.md"))).toBe(true);
+  });
+
+  test("stash/vaults/ exists", () => {
+    expect(existsSync(join(SKELETON_DIR, "stash", "vaults"))).toBe(true);
+  });
+
+  test("stash/tasks/ exists", () => {
+    expect(existsSync(join(SKELETON_DIR, "stash", "tasks"))).toBe(true);
+  });
+});
+
+// ── state/ service dirs ───────────────────────────────────────────────
+
+describe("skeleton: .openpalm/state/ service directories", () => {
+  const serviceDirs = ["assistant", "admin", "guardian", "logs", "backups"];
+
+  for (const dir of serviceDirs) {
+    test(`state/${dir}/ exists`, () => {
+      expect(existsSync(join(SKELETON_DIR, "state", dir))).toBe(true);
+    });
+  }
+
+  test("state/akm/data/ exists", () => {
+    expect(existsSync(join(SKELETON_DIR, "state", "akm", "data"))).toBe(true);
+  });
+
+  test("state/akm/state/ exists", () => {
+    expect(existsSync(join(SKELETON_DIR, "state", "akm", "state"))).toBe(true);
+  });
+
+  test("state/logs/opencode/ exists", () => {
+    expect(existsSync(join(SKELETON_DIR, "state", "logs", "opencode"))).toBe(true);
+  });
+});
+
+// ── cache/ and workspace/ ─────────────────────────────────────────────
+
+describe("skeleton: .openpalm/cache/ and workspace/", () => {
+  test("cache/akm/ exists", () => {
+    expect(existsSync(join(SKELETON_DIR, "cache", "akm"))).toBe(true);
+  });
+
+  test("cache/rollback/ exists", () => {
+    expect(existsSync(join(SKELETON_DIR, "cache", "rollback"))).toBe(true);
+  });
+
+  test("workspace/ exists", () => {
+    expect(existsSync(join(SKELETON_DIR, "workspace"))).toBe(true);
+  });
+});