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

package/src/control-plane/setup.ts

@@ -23,11 +23,11 @@ import {
   writeAuthJsonProviderKeys,
 } from "./secrets.js";
 import { createState } from "./lifecycle.js";
-import { writeStackSpec } from "./stack-spec.js";
+import { readStackSpec, writeStackSpec } from "./stack-spec.js";
 import { writeVoiceVars } from "./spec-to-env.js";
 import type { ControlPlaneState } from "./types.js";
 import { validateSetupSpec } from "./setup-validation.js";
-import { getRegistryAutomation, setAddonEnabled } from "./registry.js";
+import { getRegistryAutomation, setAddonEnabled, setAddonProfileSelection } from "./registry.js";
 export { validateSetupSpec } from "./setup-validation.js";
 
 const logger = createLogger("setup");
@@ -69,15 +69,15 @@ export type SetupSpec = {
   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).
+   * Operator-supplied UI login password. Persisted as a file-based secret.
    */
   security: { uiLoginPassword: string };
   owner?: { name?: string; email?: string };
   connections: SetupConnection[];
   channelCredentials?: Record<string, Record<string, string>>;
   addons?: Record<string, boolean>;
+  voiceProfile?: string;
+  ollamaProfile?: string;
   imageTag?: string;
   hostAkm?: boolean;
 };
@@ -85,10 +85,8 @@ export type SetupSpec = {
 // ── Secrets Builder ──────────────────────────────────────────────────────
 
 /**
- * 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.
+ * Build the non-secret stack.env update payload from a setup spec.
+ * Provider API keys and channel credentials are written as file-based secrets.
  */
 export function buildSecretsFromSetup(
   connections: SetupConnection[],
@@ -124,7 +122,7 @@ export function buildAuthJsonFromSetup(
 }
 
 /**
- * Build the system-secret env update for the wizard / CLI install path.
+ * Build the system-secret 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
@@ -132,8 +130,8 @@ export function buildAuthJsonFromSetup(
  * 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.
+  * `OP_OPENCODE_PASSWORD` may be supplied explicitly as a file-based secret in
+  * `knowledge/secrets/op_opencode_password` when OpenCode auth is enabled.
  *
  * `existingSystemEnv` is unused now but the parameter is kept so callers
  * compile unchanged. It can be removed in a follow-up cleanup.
@@ -192,13 +190,13 @@ export async function performSetup(
   const validation = validateSetupSpec(input);
   if (!validation.valid) return { ok: false, error: validation.errors.join("; ") };
 
-  const { llm, embedding, tts, stt, security, owner, connections, channelCredentials, addons, imageTag, hostAkm } = input;
+  const { llm, embedding, tts, stt, security, owner, connections, channelCredentials, addons, voiceProfile, ollamaProfile, imageTag, hostAkm } = input;
   const state = opts?.state ?? createState();
 
   // 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
+  // the same config directory. The lock lives in dataDir so it is co-located
   // with runtime state and the same path startDeploy uses.
-  const lockHandle: InstallLockHandle | null = acquireInstallLock(state.stateDir);
+  const lockHandle: InstallLockHandle | null = acquireInstallLock(state.dataDir);
   if (lockHandle === null) {
     return {
       ok: false,
@@ -218,14 +216,15 @@ export async function performSetup(
       ensureHomeDirs();
       ensureSecrets(state);
       const existingSystemEnv = readStackEnv(state.stackDir);
-      if (channelCredentials) Object.assign(updates, buildChannelCredentialEnvVars(channelCredentials));
+      const channelSecretUpdates = channelCredentials ? 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];
+          if (!channelSecretUpdates[envKey] && process.env[envKey]) channelSecretUpdates[envKey] = process.env[envKey];
         }
       }
       updateSecretsEnv(state, updates);
+      updateSecretsEnv(state, channelSecretUpdates);
       patchSecretsEnvFile(state.stackDir, buildSystemSecretsFromSetup(security.uiLoginPassword, existingSystemEnv));
       // Provider API keys land in OpenCode's auth.json (bind-mounted into
       // the assistant container) — never in stack.env.
@@ -240,13 +239,13 @@ export async function performSetup(
     // 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 });
+      // Preserve addon enablement while refreshing the stack schema marker.
+      writeStackSpec(state.stackDir, readStackSpec(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 systemEnvForAkm = existsSync(`${state.stashDir}/env/stack.env`)
+        ? readFileSync(`${state.stashDir}/env/stack.env`, "utf-8")
         : "";
       const akmUpdates: Record<string, string> = {};
       if (imageTag) akmUpdates.OP_IMAGE_TAG = imageTag;
@@ -254,14 +253,11 @@ export async function performSetup(
         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);
+        writeFileAtomic(`${state.stashDir}/env/stack.env`, mergeEnvContent(systemEnvForAkm, akmUpdates), 0o600);
       }
 
       // Write akm config with LLM and embedding settings from setup — atomic.
@@ -302,24 +298,33 @@ export async function performSetup(
       }
 
       // Enable requested addons (channels like discord, slack, etc.)
-      // setAddonEnabled copies the compose overlay AND generates CHANNEL_<NAME>_SECRET in guardian.env
+      // setAddonEnabled records explicit activation state and ensures channel secret files.
       if (addons) {
         for (const [name, enabled] of Object.entries(addons)) {
-          if (enabled) setAddonEnabled(state.homeDir, state.stackDir, name, true);
+          if (enabled) setAddonEnabled(state.homeDir, state.stackDir, name, true, state);
         }
       }
 
+
+      if (voiceProfile?.trim()) {
+        setAddonProfileSelection(state.stackDir, 'voice', voiceProfile.trim(), state);
+      }
+
+      if (ollamaProfile?.trim()) {
+        setAddonProfileSelection(state.stackDir, 'ollama', ollamaProfile.trim(), state);
+      }
+
       ensureOpenCodeConfig();
 
       // 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");
+      const akmImproveDest = join(tasksDir, "akm-improve.yml");
       if (!existsSync(akmImproveDest)) {
-        const akmImproveMd = getRegistryAutomation("akm-improve");
-        if (akmImproveMd) {
-          writeFileSync(akmImproveDest, akmImproveMd);
+        const akmImproveTask = getRegistryAutomation("akm-improve");
+        if (akmImproveTask) {
+          writeFileSync(akmImproveDest, akmImproveTask);
           logger.info("seeded default automation", { name: "akm-improve" });
         } else {
           logger.warn("default automation missing from registry; skipping seed", {

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

@@ -15,9 +15,8 @@ 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)
+  "knowledge",      // knowledge source assets: skills/, env/, secrets/, tasks/
+  "data",       // empty service dirs (.gitkeep)
   "workspace",  // empty workspace dir (.gitkeep)
 ]);
 
@@ -37,25 +36,37 @@ describe("skeleton: .openpalm/ top-level directories", () => {
     expect(existsSync(join(SKELETON_DIR, "stack"))).toBe(false);
   });
 
-  test("registry/ no longer exists (moved to state/registry/)", () => {
+  test("registry/ no longer exists", () => {
     expect(existsSync(join(SKELETON_DIR, "registry"))).toBe(false);
   });
 
-  test("stash-seeds/ no longer exists (moved to stash/)", () => {
+  test("stash-seeds/ no longer exists (moved to knowledge/)", () => {
     expect(existsSync(join(SKELETON_DIR, "stash-seeds"))).toBe(false);
   });
 });
 
+// ── power-user helper scripts ─────────────────────────────────────────
+
+describe("skeleton: helper scripts", () => {
+  test("openpalm.sh and openpalm.ps1 ship at the skeleton root", () => {
+    expect(existsSync(join(SKELETON_DIR, "openpalm.sh"))).toBe(true);
+    expect(existsSync(join(SKELETON_DIR, "openpalm.ps1"))).toBe(true);
+  });
+});
+
 // ── config/ subdirectory ──────────────────────────────────────────────
 
 describe("skeleton: .openpalm/config/ structure", () => {
-  test("config/stack/ exists with core.compose.yml and stack.yml", () => {
+  test("config/stack/ exists with fixed compose files and stack.yml", () => {
     expect(existsSync(join(SKELETON_DIR, "config", "stack", "core.compose.yml"))).toBe(true);
+    expect(existsSync(join(SKELETON_DIR, "config", "stack", "services.compose.yml"))).toBe(true);
+    expect(existsSync(join(SKELETON_DIR, "config", "stack", "channels.compose.yml"))).toBe(true);
+    expect(existsSync(join(SKELETON_DIR, "config", "stack", "custom.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/stack/addons/ does not exist", () => {
+    expect(existsSync(join(SKELETON_DIR, "config", "stack", "addons"))).toBe(false);
   });
 
   test("config/akm/ exists", () => {
@@ -63,86 +74,84 @@ describe("skeleton: .openpalm/config/ structure", () => {
   });
 
   test("config/assistant/ has seed files", () => {
-    expect(existsSync(join(SKELETON_DIR, "config", "assistant", "opencode.json"))).toBe(true);
+    expect(existsSync(join(SKELETON_DIR, "config", "assistant", "opencode.jsonc"))).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("config/guardian/ has the OpenCode global config (mounted at /etc/opencode)", () => {
+    expect(existsSync(join(SKELETON_DIR, "config", "guardian", "opencode.jsonc"))).toBe(true);
   });
 
-  test("state/registry/automations/ exists", () => {
-    expect(existsSync(join(SKELETON_DIR, "state", "registry", "automations"))).toBe(true);
+  test("config/guardian/ ships the message-moderation instructions", () => {
+    expect(existsSync(join(SKELETON_DIR, "config", "guardian", "instructions", "moderation.md"))).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);
-    }
+// ── no runtime registry ───────────────────────────────────────────────
+
+describe("skeleton: no runtime registry", () => {
+  test("data/registry/ does not exist", () => {
+    expect(existsSync(join(SKELETON_DIR, "data", "registry"))).toBe(false);
   });
 });
 
-// ── stash/ subdirectory ───────────────────────────────────────────────
+// ── knowledge/ subdirectory ───────────────────────────────────────────────
+
+describe("skeleton: .openpalm/knowledge/ structure", () => {
+  test("knowledge/skills/ exists with config-diagnostics skill", () => {
+    expect(existsSync(join(SKELETON_DIR, "knowledge", "skills", "config-diagnostics", "SKILL.md"))).toBe(true);
+  });
 
-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("knowledge/env/ exists with user.env seed", () => {
+    expect(existsSync(join(SKELETON_DIR, "knowledge", "env", "user.env"))).toBe(true);
   });
 
-  test("stash/vaults/ exists", () => {
-    expect(existsSync(join(SKELETON_DIR, "stash", "vaults"))).toBe(true);
+  test("knowledge/secrets/ exists", () => {
+    expect(existsSync(join(SKELETON_DIR, "knowledge", "secrets"))).toBe(true);
   });
 
-  test("stash/tasks/ exists", () => {
-    expect(existsSync(join(SKELETON_DIR, "stash", "tasks"))).toBe(true);
+  test("knowledge/tasks/ exists", () => {
+    expect(existsSync(join(SKELETON_DIR, "knowledge", "tasks"))).toBe(true);
   });
 });
 
-// ── state/ service dirs ───────────────────────────────────────────────
+// ── data/ service dirs ────────────────────────────────────────────────
 
-describe("skeleton: .openpalm/state/ service directories", () => {
-  const serviceDirs = ["assistant", "admin", "guardian", "logs", "backups"];
+describe("skeleton: .openpalm/data/ service directories", () => {
+  const serviceDirs = ["assistant", "admin", "guardian"];
 
   for (const dir of serviceDirs) {
-    test(`state/${dir}/ exists`, () => {
-      expect(existsSync(join(SKELETON_DIR, "state", dir))).toBe(true);
+    test(`data/${dir}/ exists`, () => {
+      expect(existsSync(join(SKELETON_DIR, "data", dir))).toBe(true);
     });
   }
 
-  test("state/akm/data/ exists", () => {
-    expect(existsSync(join(SKELETON_DIR, "state", "akm", "data"))).toBe(true);
+  test("data/akm/ exists", () => {
+    expect(existsSync(join(SKELETON_DIR, "data", "akm"))).toBe(true);
   });
 
-  test("state/akm/state/ exists", () => {
-    expect(existsSync(join(SKELETON_DIR, "state", "akm", "state"))).toBe(true);
+  test("data/akm/cache and data/akm/data exist", () => {
+    expect(existsSync(join(SKELETON_DIR, "data", "akm", "cache"))).toBe(true);
+    expect(existsSync(join(SKELETON_DIR, "data", "akm", "data"))).toBe(true);
   });
 
-  test("state/logs/opencode/ exists", () => {
-    expect(existsSync(join(SKELETON_DIR, "state", "logs", "opencode"))).toBe(true);
+  test("data/logs/ exists", () => {
+    expect(existsSync(join(SKELETON_DIR, "data", "logs"))).toBe(true);
   });
 });
 
-// ── cache/ and workspace/ ─────────────────────────────────────────────
+// ── data/rollback and workspace/ ──────────────────────────────────────
+
+describe("skeleton: .openpalm/data/rollback and workspace/", () => {
+  test("cache/ does not exist in the skeleton", () => {
+    expect(existsSync(join(SKELETON_DIR, "cache"))).toBe(false);
+  });
 
-describe("skeleton: .openpalm/cache/ and workspace/", () => {
-  test("cache/akm/ exists", () => {
-    expect(existsSync(join(SKELETON_DIR, "cache", "akm"))).toBe(true);
+  test("data/backups/ exists", () => {
+    expect(existsSync(join(SKELETON_DIR, "data", "backups"))).toBe(true);
   });
 
-  test("cache/rollback/ exists", () => {
-    expect(existsSync(join(SKELETON_DIR, "cache", "rollback"))).toBe(true);
+  test("data/rollback/ exists", () => {
+    expect(existsSync(join(SKELETON_DIR, "data", "rollback"))).toBe(true);
   });
 
   test("workspace/ exists", () => {

package/src/control-plane/spec-to-env.test.ts

@@ -62,54 +62,59 @@ describe("deriveSystemEnvFromSpec", () => {
 });
 
 describe("writeVoiceVars", () => {
+  // writeVoiceVars takes a stackDir (<home>/config/stack) and writes the env
+  // to <home>/knowledge/env/stack.env. Build that layout per test.
+  let stackDir = "";
+  let stackEnv = "";
+  beforeEach(() => {
+    stackDir = join(tempDir, "config", "stack");
+    stackEnv = join(tempDir, "knowledge", "env", "stack.env");
+    mkdirSync(stackDir, { recursive: true });
+    mkdirSync(join(tempDir, "knowledge", "env"), { recursive: true });
+  });
+
   test("writes TTS vars to stack.env", () => {
-    mkdirSync(tempDir, { recursive: true });
-    writeFileSync(join(tempDir, "stack.env"), "# stack env\n");
+    writeFileSync(stackEnv, "# stack env\n");
 
     writeVoiceVars({
       tts: { baseURL: "https://tts.example.com/v1", model: "tts-1", voice: "alloy" },
-    }, tempDir);
+    }, stackDir);
 
-    const content = readFileSync(join(tempDir, "stack.env"), "utf-8");
+    const content = readFileSync(stackEnv, "utf-8");
     expect(content).toContain("OP_TTS_BASE_URL=https://tts.example.com/v1");
     expect(content).toContain("OP_TTS_MODEL=tts-1");
     expect(content).toContain("OP_TTS_VOICE=alloy");
   });
 
   test("writes STT vars to stack.env", () => {
-    mkdirSync(tempDir, { recursive: true });
-    writeFileSync(join(tempDir, "stack.env"), "# stack env\n");
+    writeFileSync(stackEnv, "# stack env\n");
 
     writeVoiceVars({
       stt: { baseURL: "https://stt.example.com/v1", model: "whisper-1", language: "en" },
-    }, tempDir);
+    }, stackDir);
 
-    const content = readFileSync(join(tempDir, "stack.env"), "utf-8");
+    const content = readFileSync(stackEnv, "utf-8");
     expect(content).toContain("OP_STT_BASE_URL=https://stt.example.com/v1");
     expect(content).toContain("OP_STT_MODEL=whisper-1");
     expect(content).toContain("OP_STT_LANGUAGE=en");
   });
 
   test("creates stack.env if it does not exist", () => {
-    mkdirSync(tempDir, { recursive: true });
-
     writeVoiceVars({
       tts: { baseURL: "https://tts.example.com/v1", model: "tts-1" },
-    }, tempDir);
+    }, stackDir);
 
-    const content = readFileSync(join(tempDir, "stack.env"), "utf-8");
+    const content = readFileSync(stackEnv, "utf-8");
     expect(content).toContain("OP_TTS_BASE_URL=https://tts.example.com/v1");
   });
 
   test("is a no-op when no vars are provided", () => {
-    mkdirSync(tempDir, { recursive: true });
-    const stackEnvPath = join(tempDir, "stack.env");
-    writeFileSync(stackEnvPath, "EXISTING=value\n");
+    writeFileSync(stackEnv, "EXISTING=value\n");
 
-    writeVoiceVars({}, tempDir);
+    writeVoiceVars({}, stackDir);
 
     // File should be unchanged
-    const content = readFileSync(stackEnvPath, "utf-8");
+    const content = readFileSync(stackEnv, "utf-8");
     expect(content).toBe("EXISTING=value\n");
   });
 });

package/src/control-plane/spec-to-env.ts

@@ -6,9 +6,12 @@
  */
 
 import { SPEC_DEFAULTS } from "./stack-spec.js";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
 import { mergeEnvContent } from "./env.js";
 import { resolveOperatorIds } from "./operator-ids.js";
+import { assertNoSecretLikeStackEnvKeys } from './secrets.js';
+import { stackEnvPathFromStackDir } from './paths.js';
 
 /**
  * Derive the system.env key-value pairs from the StackSpec.
@@ -75,7 +78,7 @@ export type VoiceVarsConfig = {
  * engine without filling in URL/model still persists.
  */
 export function writeVoiceVars(config: VoiceVarsConfig, stackDir: string): void {
-  const stackEnvPath = `${stackDir}/stack.env`;
+  const stackEnvPath = stackEnvPathFromStackDir(stackDir);
   const base = existsSync(stackEnvPath) ? readFileSync(stackEnvPath, "utf-8") : "";
   const vars: Record<string, string> = {};
 
@@ -101,10 +104,12 @@ export function writeVoiceVars(config: VoiceVarsConfig, stackDir: string): void
   }
 
   if (Object.keys(vars).length === 0) return;
+  assertNoSecretLikeStackEnvKeys(vars);
 
   let content = mergeEnvContent(base, vars, {
     sectionHeader: "# ── Voice Channel (TTS/STT) ──────────────────────────────────────────",
   });
   if (!content.endsWith("\n")) content += "\n";
+  mkdirSync(dirname(stackEnvPath), { recursive: true, mode: 0o700 });
   writeFileSync(stackEnvPath, content, { mode: 0o600 });
 }

package/src/control-plane/stack-spec.test.ts

@@ -36,6 +36,11 @@ describe("readStackSpec / writeStackSpec round-trip", () => {
     expect(read!.version).toBe(2);
   });
 
+  it("round-trips enabled addons", () => {
+    writeStackSpec(configDir, { version: 2, addons: ['chat', 'api'] });
+    expect(readStackSpec(configDir)).toEqual({ version: 2, addons: ['api', 'chat'] });
+  });
+
   it("writes to the canonical filename", () => {
     writeStackSpec(configDir, MINIMAL_SPEC);
     const expectedPath = join(configDir, STACK_SPEC_FILENAME);
@@ -77,6 +82,11 @@ describe("readStackSpec edge cases", () => {
     expect(spec).not.toBeNull();
     expect(spec!.version).toBe(2);
   });
+
+  it("ignores malformed addon names", () => {
+    writeFileSync(join(configDir, STACK_SPEC_FILENAME), "version: 2\naddons:\n  - chat\n  - ../bad\n  - API\n");
+    expect(readStackSpec(configDir)).toEqual({ version: 2, addons: ['chat'] });
+  });
 });
 
 // ── STACK_SPEC_FILENAME ───────────────────────────────────────────────────

package/src/control-plane/stack-spec.ts

@@ -14,8 +14,11 @@ import { stringify as yamlStringify, parse as yamlParse } from "yaml";
 
 export type StackSpec = {
   version: 2;
+  addons?: string[];
 };
 
+const ADDON_NAME_RE = /^[a-z0-9][a-z0-9-]{0,62}$/;
+
 // ── Constants ───────────────────────────────────────────────────────────
 
 export const STACK_SPEC_FILENAME = "stack.yml";
@@ -59,5 +62,29 @@ export function readStackSpec(configDir: string): StackSpec | null {
   if (typeof raw !== "object" || raw === null) return null;
   const obj = raw as Record<string, unknown>;
   if (obj.version !== 2) return null;
-  return { version: 2 };
+  const spec: StackSpec = { version: 2 };
+  if (Array.isArray(obj.addons)) {
+    const addons = obj.addons
+      .filter((value): value is string => typeof value === 'string' && ADDON_NAME_RE.test(value))
+      .filter((value, index, all) => all.indexOf(value) === index)
+      .sort();
+    if (addons.length > 0) spec.addons = addons;
+  }
+  return spec;
+}
+
+export function listStackSpecAddons(configDir: string): string[] {
+  return readStackSpec(configDir)?.addons ?? [];
+}
+
+export function setStackSpecAddon(configDir: string, name: string, enabled: boolean): void {
+  if (!ADDON_NAME_RE.test(name)) throw new Error(`Invalid addon name: ${name}`);
+  const current = readStackSpec(configDir) ?? { version: 2 };
+  const addons = new Set(current.addons ?? []);
+  if (enabled) addons.add(name);
+  else addons.delete(name);
+  const next: StackSpec = { version: 2 };
+  const sorted = [...addons].sort();
+  if (sorted.length > 0) next.addons = sorted;
+  writeStackSpec(configDir, next);
 }

package/src/control-plane/types.ts

@@ -27,10 +27,9 @@ export type ArtifactMeta = {
 export type ControlPlaneState = {
   homeDir: string;
   configDir: string;
-  stashDir: string;      // homeDir/stash
+  stashDir: string;      // homeDir/knowledge
   workspaceDir: string;  // homeDir/workspace
-  cacheDir: string;      // homeDir/cache (regenerable/semi-persistent data)
-  stateDir: string;      // homeDir/state (service data + system state)
+  dataDir: string;       // homeDir/data (service data + operational files)
   stackDir: string;      // configDir/stack (compose runtime + stack config)
   services: Record<string, "running" | "stopped">;
   artifacts: {
@@ -48,4 +47,3 @@ export const CORE_SERVICES: CoreServiceName[] = [
   "assistant",
   "guardian",
 ];
-