@openpalm/lib 0.10.1 → 0.11.0-beta.1

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

@@ -2,20 +2,9 @@ import { describe, test, expect, beforeEach, afterEach } from "bun:test";
 import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { deriveSystemEnvFromSpec, writeCapabilityVars } from "./spec-to-env.js";
-import type { StackSpec } from "./stack-spec.js";
-
-function makeSpec(overrides?: Partial<StackSpec>): StackSpec {
-  return {
-    version: 2,
-    capabilities: {
-      llm: "openai/gpt-4o",
-      embeddings: { provider: "openai", model: "text-embedding-3-small", dims: 1536 },
-      memory: { userId: "default_user" },
-    },
-    ...overrides,
-  };
-}
+import { deriveSystemEnvFromSpec, writeVoiceVars } from "./spec-to-env.js";
+
+const MINIMAL_SPEC = { version: 2 as const };
 
 let tempDir = "";
 
@@ -29,72 +18,84 @@ afterEach(() => {
 
 describe("deriveSystemEnvFromSpec", () => {
   test("produces OP_HOME", () => {
-    const result = deriveSystemEnvFromSpec(makeSpec(), "/home/op");
+    const result = deriveSystemEnvFromSpec(MINIMAL_SPEC, "/home/op");
     expect(result.OP_HOME).toBe("/home/op");
   });
 
   test("produces default port values", () => {
-    const result = deriveSystemEnvFromSpec(makeSpec(), "/home/op");
+    const result = deriveSystemEnvFromSpec(MINIMAL_SPEC, "/home/op");
     expect(result.OP_ASSISTANT_PORT).toBe("3800");
-    expect(result.OP_MEMORY_PORT).toBe("3898");
     expect(result.OP_GUARDIAN_PORT).toBe("3899");
   });
 
-  test("does not include LLM provider in system env (lives in OP_CAP_* vars in stack.env)", () => {
-    const result = deriveSystemEnvFromSpec(makeSpec(), "/home/op");
-    expect(result.SYSTEM_LLM_PROVIDER).toBeUndefined();
-    expect(result.SYSTEM_LLM_MODEL).toBeUndefined();
+  test("does not include the retired memory service port", () => {
+    const result = deriveSystemEnvFromSpec(MINIMAL_SPEC, "/home/op");
+    const retired = "OP_" + "MEMORY_PORT";
+    expect(result[retired]).toBeUndefined();
   });
 
-  test("does not include embedding config in system env (lives in OP_CAP_* vars in stack.env)", () => {
-    const result = deriveSystemEnvFromSpec(makeSpec(), "/home/op");
-    expect(result.EMBEDDING_MODEL).toBeUndefined();
-    expect(result.EMBEDDING_DIMS).toBeUndefined();
+  test("does not include LLM provider in system env", () => {
+    const result = deriveSystemEnvFromSpec(MINIMAL_SPEC, "/home/op");
+    expect(result.SYSTEM_LLM_PROVIDER).toBeUndefined();
+    expect(result.SYSTEM_LLM_MODEL).toBeUndefined();
   });
 
   test("does not include removed feature flags", () => {
-    const spec = makeSpec();
-    const result = deriveSystemEnvFromSpec(spec, "/home/op");
+    const result = deriveSystemEnvFromSpec(MINIMAL_SPEC, "/home/op");
     expect(result.OP_OLLAMA_ENABLED).toBeUndefined();
     expect(result.OP_ADMIN_ENABLED).toBeUndefined();
   });
 });
 
-describe("writeCapabilityVars", () => {
-  test("writes OP_CAP_* vars to stack.env", () => {
-    const spec = makeSpec({
-      capabilities: {
-        llm: "openai/gpt-4o",
-        embeddings: { provider: "openai", model: "text-embedding-3-small", dims: 1536 },
-        memory: { userId: "default_user" },
-      },
-    });
-
-    // Seed stack.env so writeCapabilityVars can read/merge it
-    const vaultDir = join(tempDir, "vault");
-    mkdirSync(join(vaultDir, "stack"), { recursive: true });
-    writeFileSync(join(vaultDir, "stack", "stack.env"), "# stack env\n");
-
-    writeCapabilityVars(spec, vaultDir);
-
-    const stackEnvContent = readFileSync(join(vaultDir, "stack", "stack.env"), "utf-8");
-    expect(stackEnvContent).toContain("OP_CAP_LLM_PROVIDER=openai");
-    expect(stackEnvContent).toContain("OP_CAP_LLM_MODEL=gpt-4o");
-    expect(stackEnvContent).toContain("OP_CAP_EMBEDDINGS_MODEL=text-embedding-3-small");
-    expect(stackEnvContent).toContain("OP_CAP_EMBEDDINGS_DIMS=1536");
-    expect(stackEnvContent).toContain("MEMORY_USER_ID=default_user");
+describe("writeVoiceVars", () => {
+  test("writes TTS vars to stack.env", () => {
+    mkdirSync(tempDir, { recursive: true });
+    writeFileSync(join(tempDir, "stack.env"), "# stack env\n");
+
+    writeVoiceVars({
+      tts: { baseURL: "https://tts.example.com/v1", model: "tts-1", voice: "alloy" },
+    }, tempDir);
+
+    const content = readFileSync(join(tempDir, "stack.env"), "utf-8");
+    expect(content).toContain("TTS_BASE_URL=https://tts.example.com/v1");
+    expect(content).toContain("TTS_MODEL=tts-1");
+    expect(content).toContain("TTS_VOICE=alloy");
   });
 
-  test("does not create managed.env files", () => {
-    const spec = makeSpec();
+  test("writes STT vars to stack.env", () => {
+    mkdirSync(tempDir, { recursive: true });
+    writeFileSync(join(tempDir, "stack.env"), "# stack env\n");
+
+    writeVoiceVars({
+      stt: { baseURL: "https://stt.example.com/v1", model: "whisper-1", language: "en" },
+    }, tempDir);
+
+    const content = readFileSync(join(tempDir, "stack.env"), "utf-8");
+    expect(content).toContain("STT_BASE_URL=https://stt.example.com/v1");
+    expect(content).toContain("STT_MODEL=whisper-1");
+    expect(content).toContain("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);
+
+    const content = readFileSync(join(tempDir, "stack.env"), "utf-8");
+    expect(content).toContain("TTS_BASE_URL=https://tts.example.com/v1");
+  });
 
-    const vaultDir = join(tempDir, "vault");
-    mkdirSync(join(vaultDir, "stack"), { recursive: true });
-    writeFileSync(join(vaultDir, "stack", "stack.env"), "# stack env\n");
+  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");
 
-    writeCapabilityVars(spec, vaultDir);
+    writeVoiceVars({}, tempDir);
 
-    const managedEnvPath = join(vaultDir, "stack", "services", "memory", "managed.env");
-    expect(() => readFileSync(managedEnvPath)).toThrow();
+    // File should be unchanged
+    const content = readFileSync(stackEnvPath, "utf-8");
+    expect(content).toBe("EXISTING=value\n");
   });
 });

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

@@ -1,18 +1,14 @@
 /**
  * Config-to-env derivation pipeline.
  *
- * Reads a StackSpec v2 and deterministically produces:
- * 1. System env vars for stack.env (non-secret infrastructure config)
- * 2. Resolved capability vars (OP_CAP_*) written to stack.env
+ * Produces system env vars for stack.env (non-secret infrastructure config).
+ * Voice channel vars (TTS/STT) are written separately via writeVoiceVars.
  */
 
 import type { StackSpec } from "./stack-spec.js";
-import { SPEC_DEFAULTS, parseCapabilityString } from "./stack-spec.js";
+import { SPEC_DEFAULTS } from "./stack-spec.js";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
-import { mergeEnvContent, parseEnvContent } from "./env.js";
-import { PROVIDER_DEFAULT_URLS, PROVIDER_KEY_MAP, OLLAMA_INSTACK_URL } from "../provider-constants.js";
-import { listEnabledAddonIds } from "./registry.js";
+import { mergeEnvContent } from "./env.js";
 
 /**
  * Derive the system.env key-value pairs from the StackSpec.
@@ -34,8 +30,6 @@ export function deriveSystemEnvFromSpec(
   result["OP_HOME"] = homeDir;
   result["OP_UID"] = String(uid);
   result["OP_GID"] = String(gid);
-  result["OP_DOCKER_SOCK"] = process.env.OP_DOCKER_SOCK ?? "/var/run/docker.sock";
-
   // Image
   result["OP_IMAGE_NAMESPACE"] = image.namespace;
   result["OP_IMAGE_TAG"] = image.tag;
@@ -44,151 +38,56 @@ export function deriveSystemEnvFromSpec(
   result["OP_ASSISTANT_PORT"] = String(ports.assistant);
   result["OP_ADMIN_PORT"] = String(ports.admin);
   result["OP_ADMIN_OPENCODE_PORT"] = String(ports.adminOpencode);
-  result["OP_MEMORY_PORT"] = String(ports.memory);
   result["OP_GUARDIAN_PORT"] = String(ports.guardian);
   result["OP_ASSISTANT_SSH_PORT"] = String(ports.assistantSsh);
 
+  void spec; // spec reserved for future use; ports/image come from SPEC_DEFAULTS
+
   return result;
 }
 
-// ── Capability Resolution ────────────────────────────────────────────────
-
-/**
- * Resolve all capabilities from stack.yml and write OP_CAP_* vars into stack.env.
- *
- * Reads raw API keys from the current stack.env, resolves provider → base URL → API key
- * for each capability, and merges the OP_CAP_* section into stack.env.
- *
- * Services consume these via compose ${VAR} substitution in their environment blocks.
- */
-export function writeCapabilityVars(spec: StackSpec, vaultDir: string): void {
-  const stackEnvPath = `${vaultDir}/stack/stack.env`;
-  const stackEnv = existsSync(stackEnvPath)
-    ? parseEnvContent(readFileSync(stackEnvPath, "utf-8"))
-    : {};
-
-  const resolveKey = (provider: string): string => {
-    const keyVar = PROVIDER_KEY_MAP[provider];
-    return keyVar ? (stackEnv[keyVar] || "") : "";
-  };
-
-  /** Providers that do NOT use an OpenAI-compatible /v1 path prefix. */
-  const NO_V1_SUFFIX = new Set(["ollama", "google"]);
-
-  const ensureV1 = (url: string, provider: string): string => {
-    if (!url || NO_V1_SUFFIX.has(provider)) return url;
-    return url.endsWith("/v1") ? url : `${url.replace(/\/+$/, "")}/v1`;
-  };
-
-  /** Map provider → env var for user-configured base URL overrides. */
-  const BASE_URL_ENV_MAP: 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",
-  };
+// ── Voice Channel Env Vars ────────────────────────────────────────────────
 
-  const resolveUrl = (provider: string): string => {
-    if (provider === "ollama" && listEnabledAddonIds(dirname(vaultDir)).includes("ollama")) return OLLAMA_INSTACK_URL;
-    // Check stack.env for a user-configured base URL override for any provider
-    const urlEnvKey = BASE_URL_ENV_MAP[provider];
-    if (urlEnvKey && stackEnv[urlEnvKey]) {
-      return ensureV1(stackEnv[urlEnvKey], provider);
-    }
-    const defaultUrl = PROVIDER_DEFAULT_URLS[provider] || "";
-    return ensureV1(defaultUrl, provider);
+export type VoiceVarsConfig = {
+  tts?: {
+    enabled?: boolean;
+    baseURL?: string;
+    model?: string;
+    voice?: string;
   };
-
-  const caps: Record<string, string> = {};
-
-  /** Set a list of capability env vars to empty string (disabled capability). */
-  const clearCapVars = (prefix: string, fields: string[]): void => {
-    for (const f of fields) caps[`${prefix}_${f}`] = "";
+  stt?: {
+    enabled?: boolean;
+    baseURL?: string;
+    model?: string;
+    language?: string;
   };
+};
 
-  // ── LLM ──
-  const { provider: llmP, model: llmM } = parseCapabilityString(spec.capabilities.llm);
-  caps.OP_CAP_LLM_PROVIDER = llmP;
-  caps.OP_CAP_LLM_MODEL = llmM;
-  caps.OP_CAP_LLM_BASE_URL = resolveUrl(llmP);
-  caps.OP_CAP_LLM_API_KEY = resolveKey(llmP);
-
-  // ── SLM ──
-  if (spec.capabilities.slm) {
-    const { provider: slmP, model: slmM } = parseCapabilityString(spec.capabilities.slm);
-    caps.OP_CAP_SLM_PROVIDER = slmP;
-    caps.OP_CAP_SLM_MODEL = slmM;
-    caps.OP_CAP_SLM_BASE_URL = resolveUrl(slmP);
-    caps.OP_CAP_SLM_API_KEY = resolveKey(slmP);
-  } else {
-    clearCapVars("OP_CAP_SLM", ["PROVIDER", "MODEL", "BASE_URL", "API_KEY"]);
-  }
-
-  // ── Embeddings ──
-  const emb = spec.capabilities.embeddings;
-  caps.OP_CAP_EMBEDDINGS_PROVIDER = emb.provider;
-  caps.OP_CAP_EMBEDDINGS_MODEL = emb.model;
-  caps.OP_CAP_EMBEDDINGS_BASE_URL = resolveUrl(emb.provider);
-  caps.OP_CAP_EMBEDDINGS_API_KEY = resolveKey(emb.provider);
-  caps.OP_CAP_EMBEDDINGS_DIMS = String(emb.dims);
-
-  // ── TTS ──
-  const tts = spec.capabilities.tts;
-  if (tts?.enabled) {
-    const p = tts.provider || llmP;
-    caps.OP_CAP_TTS_PROVIDER = p;
-    caps.OP_CAP_TTS_MODEL = tts.model || "";
-    caps.OP_CAP_TTS_BASE_URL = resolveUrl(p);
-    caps.OP_CAP_TTS_API_KEY = resolveKey(p);
-    caps.OP_CAP_TTS_VOICE = tts.voice || "";
-    caps.OP_CAP_TTS_FORMAT = tts.format || "";
-  } else {
-    clearCapVars("OP_CAP_TTS", ["PROVIDER", "MODEL", "BASE_URL", "API_KEY", "VOICE", "FORMAT"]);
-  }
+/**
+ * Write TTS/STT env vars to stack.env for the voice channel container.
+ * Only vars with non-empty values are written; missing values are left unchanged.
+ */
+export function writeVoiceVars(config: VoiceVarsConfig, stackDir: string): void {
+  const stackEnvPath = `${stackDir}/stack.env`;
+  const base = existsSync(stackEnvPath) ? readFileSync(stackEnvPath, "utf-8") : "";
+  const vars: Record<string, string> = {};
 
-  // ── STT ──
-  const stt = spec.capabilities.stt;
-  if (stt?.enabled) {
-    const p = stt.provider || llmP;
-    caps.OP_CAP_STT_PROVIDER = p;
-    caps.OP_CAP_STT_MODEL = stt.model || "";
-    caps.OP_CAP_STT_BASE_URL = resolveUrl(p);
-    caps.OP_CAP_STT_API_KEY = resolveKey(p);
-    caps.OP_CAP_STT_LANGUAGE = stt.language || "";
-  } else {
-    clearCapVars("OP_CAP_STT", ["PROVIDER", "MODEL", "BASE_URL", "API_KEY", "LANGUAGE"]);
+  const { tts, stt } = config;
+  if (tts?.enabled !== false) {
+    if (tts?.baseURL) vars["TTS_BASE_URL"] = tts.baseURL;
+    if (tts?.model) vars["TTS_MODEL"] = tts.model;
+    if (tts?.voice) vars["TTS_VOICE"] = tts.voice;
   }
-
-  // ── Reranking ──
-  const rr = spec.capabilities.reranking;
-  if (rr?.enabled) {
-    const p = rr.provider || llmP;
-    caps.OP_CAP_RERANKING_PROVIDER = p;
-    caps.OP_CAP_RERANKING_MODEL = rr.model || "";
-    caps.OP_CAP_RERANKING_BASE_URL = resolveUrl(p);
-    caps.OP_CAP_RERANKING_API_KEY = resolveKey(p);
-    caps.OP_CAP_RERANKING_TOP_K = rr.topK ? String(rr.topK) : "";
-    caps.OP_CAP_RERANKING_TOP_N = rr.topN ? String(rr.topN) : "";
-  } else {
-    clearCapVars("OP_CAP_RERANKING", ["PROVIDER", "MODEL", "BASE_URL", "API_KEY", "TOP_K", "TOP_N"]);
+  if (stt?.enabled !== false) {
+    if (stt?.baseURL) vars["STT_BASE_URL"] = stt.baseURL;
+    if (stt?.model) vars["STT_MODEL"] = stt.model;
+    if (stt?.language) vars["STT_LANGUAGE"] = stt.language;
   }
 
-  // ── Memory ──
-  caps.MEMORY_USER_ID = spec.capabilities.memory.userId || "default_user";
+  if (Object.keys(vars).length === 0) return;
 
-  // Merge into stack.env
-  const base = existsSync(stackEnvPath) ? readFileSync(stackEnvPath, "utf-8") : "";
-  let content = mergeEnvContent(base, caps, {
-    sectionHeader: "# ── Resolved Capabilities (from stack.yml) ─────────────────────────",
+  let content = mergeEnvContent(base, vars, {
+    sectionHeader: "# ── Voice Channel (TTS/STT) ──────────────────────────────────────────",
   });
   if (!content.endsWith("\n")) content += "\n";
   writeFileSync(stackEnvPath, content, { mode: 0o600 });

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

@@ -5,7 +5,7 @@
  * so users can quickly identify and fix configuration issues.
  */
 
-import type { StackSpec, StackSpecCapabilities } from "./stack-spec.js";
+import type { StackSpec } from "./stack-spec.js";
 
 export type ValidationError = {
   code: string;
@@ -41,18 +41,6 @@ export function validateStackSpec(input: unknown): ValidationError[] {
     return errors;
   }
 
-  // Capabilities
-  if (typeof spec.capabilities !== "object" || spec.capabilities === null) {
-    errors.push({
-      code: "OP-CFG-001",
-      message: "No capabilities defined",
-      path: "capabilities",
-      hint: "Add capabilities.llm and capabilities.embeddings sections",
-    });
-  } else {
-    validateCapabilities(spec.capabilities as StackSpecCapabilities, errors);
-  }
-
   // Image
   if (spec.image && typeof spec.image === "object") {
     const img = spec.image as Record<string, unknown>;
@@ -69,91 +57,6 @@ export function validateStackSpec(input: unknown): ValidationError[] {
     }
   }
 
+  void (spec as unknown as StackSpec); // reserved for future validations
   return errors;
 }
-
-function validateCapabilities(
-  capabilities: StackSpecCapabilities,
-  errors: ValidationError[],
-): void {
-  // LLM (required, "provider/model" string)
-  if (!capabilities.llm || typeof capabilities.llm !== "string") {
-    errors.push({
-      code: "OP-CFG-008",
-      message: "capabilities.llm is required (format: provider/model)",
-      path: "capabilities.llm",
-      hint: 'Example: "anthropic/claude-sonnet-4-5" or "ollama/qwen2.5-coder:3b"',
-    });
-  } else if (!capabilities.llm.includes("/")) {
-    errors.push({
-      code: "OP-CFG-008",
-      message: `capabilities.llm "${capabilities.llm}" must be in provider/model format`,
-      path: "capabilities.llm",
-      hint: 'Example: "anthropic/claude-sonnet-4-5"',
-    });
-  }
-
-  // SLM (optional, same format)
-  if (capabilities.slm !== undefined) {
-    if (typeof capabilities.slm !== "string") {
-      errors.push({
-        code: "OP-CFG-008",
-        message: "capabilities.slm must be a string (format: provider/model)",
-        path: "capabilities.slm",
-      });
-    } else if (!capabilities.slm.includes("/")) {
-      errors.push({
-        code: "OP-CFG-008",
-        message: `capabilities.slm "${capabilities.slm}" must be in provider/model format`,
-        path: "capabilities.slm",
-      });
-    }
-  }
-
-  // Embeddings (required object)
-  if (!capabilities.embeddings || typeof capabilities.embeddings !== "object") {
-    errors.push({
-      code: "OP-CFG-002",
-      message: "capabilities.embeddings is required",
-      path: "capabilities.embeddings",
-      hint: "Add provider, model, and dims fields",
-    });
-  } else {
-    const emb = capabilities.embeddings;
-    if (!emb.provider || typeof emb.provider !== "string") {
-      errors.push({
-        code: "OP-CFG-004",
-        message: "capabilities.embeddings.provider is required",
-        path: "capabilities.embeddings.provider",
-      });
-    }
-    if (!emb.model || typeof emb.model !== "string") {
-      errors.push({
-        code: "OP-CFG-008",
-        message: "capabilities.embeddings.model is required",
-        path: "capabilities.embeddings.model",
-      });
-    }
-    if (
-      emb.dims !== undefined &&
-      (typeof emb.dims !== "number" || emb.dims < 1)
-    ) {
-      errors.push({
-        code: "OP-CFG-009",
-        message: "capabilities.embeddings.dims must be a positive integer",
-        path: "capabilities.embeddings.dims",
-        hint: "Common values: nomic-embed-text: 768, text-embedding-3-small: 1536",
-      });
-    }
-  }
-
-  // Memory (required object)
-  if (!capabilities.memory || typeof capabilities.memory !== "object") {
-    errors.push({
-      code: "OP-CFG-002",
-      message: "capabilities.memory is required",
-      path: "capabilities.memory",
-      hint: "Add at minimum a userId field",
-    });
-  }
-}

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

@@ -1,8 +1,7 @@
 /**
  * Stack spec parser tests.
  *
- * Verifies that readStackSpec / writeStackSpec produce consistent results
- * and that all addon resolution goes through the canonical lib functions.
+ * Verifies that readStackSpec / writeStackSpec produce consistent results.
  */
 import { describe, it, expect, beforeEach, afterEach } from "bun:test";
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
@@ -13,9 +12,6 @@ import {
   writeStackSpec,
   STACK_SPEC_FILENAME,
   stackSpecPath,
-  parseCapabilityString,
-  formatCapabilityString,
-  updateCapability,
 } from "./stack-spec.js";
 import type { StackSpec } from "./stack-spec.js";
 
@@ -29,38 +25,35 @@ afterEach(() => {
   rmSync(configDir, { recursive: true, force: true });
 });
 
-// ── Helpers ─────────────────────────────────────────────────────────────
-
-function makeSpec(): StackSpec {
-  return {
-    version: 2,
-    capabilities: {
-      llm: "openai/gpt-4o",
-      embeddings: { provider: "openai", model: "text-embedding-3-small", dims: 1536 },
-      memory: { userId: "test-user" },
-    },
-  };
-}
+const MINIMAL_SPEC: StackSpec = { version: 2 };
 
 // ── readStackSpec / writeStackSpec round-trip ────────────────────────────
 
 describe("readStackSpec / writeStackSpec round-trip", () => {
-  it("round-trips a spec with capabilities only", () => {
-    const spec = makeSpec();
-    writeStackSpec(configDir, spec);
+  it("round-trips a minimal spec", () => {
+    writeStackSpec(configDir, MINIMAL_SPEC);
     const read = readStackSpec(configDir);
     expect(read).not.toBeNull();
     expect(read!.version).toBe(2);
-    expect(read!.capabilities.llm).toBe("openai/gpt-4o");
   });
 
   it("writes to the canonical filename", () => {
-    writeStackSpec(configDir, makeSpec());
+    writeStackSpec(configDir, MINIMAL_SPEC);
     const expectedPath = join(configDir, STACK_SPEC_FILENAME);
     const read = readStackSpec(configDir);
     expect(read).not.toBeNull();
     expect(stackSpecPath(configDir)).toBe(expectedPath);
   });
+
+  it("ignores legacy capabilities fields on read", () => {
+    // On upgraded installs, old stack.yml may have capabilities — should still parse
+    writeFileSync(join(configDir, STACK_SPEC_FILENAME),
+      "version: 2\ncapabilities:\n  llm: openai/gpt-4o\n  embeddings:\n    provider: openai\n    model: text-embedding-3-small\n    dims: 1536\n"
+    );
+    const read = readStackSpec(configDir);
+    expect(read).not.toBeNull();
+    expect(read!.version).toBe(2);
+  });
 });
 
 // ── readStackSpec edge cases ────────────────────────────────────────────
@@ -80,71 +73,22 @@ describe("readStackSpec edge cases", () => {
     expect(readStackSpec(configDir)).toBeNull();
   });
 
-  it("returns null when capabilities is missing", () => {
+  it("returns valid spec for version 2 with no other fields", () => {
     writeFileSync(join(configDir, STACK_SPEC_FILENAME), "version: 2\n");
-    expect(readStackSpec(configDir)).toBeNull();
-  });
-});
-
-// ── Capability helpers ──────────────────────────────────────────────────
-
-describe("parseCapabilityString", () => {
-  it("splits provider/model", () => {
-    expect(parseCapabilityString("openai/gpt-4o")).toEqual({ provider: "openai", model: "gpt-4o" });
-  });
-
-  it("handles model with slashes", () => {
-    expect(parseCapabilityString("ollama/qwen/2.5-coder:3b")).toEqual({ provider: "ollama", model: "qwen/2.5-coder:3b" });
-  });
-
-  it("handles missing slash", () => {
-    expect(parseCapabilityString("openai")).toEqual({ provider: "openai", model: "" });
-  });
-});
-
-describe("formatCapabilityString", () => {
-  it("joins provider and model", () => {
-    expect(formatCapabilityString("openai", "gpt-4o")).toBe("openai/gpt-4o");
-  });
-});
-
-// ── updateCapability ────────────────────────────────────────────────────
-
-describe("updateCapability", () => {
-  it("updates a single capability key", () => {
-    writeStackSpec(configDir, makeSpec());
-    updateCapability(configDir, "llm", "anthropic/claude-sonnet-4");
-    const read = readStackSpec(configDir);
-    expect(read).not.toBeNull();
-    expect(read!.capabilities.llm).toBe("anthropic/claude-sonnet-4");
-  });
-
-  it("throws when spec is missing", () => {
-    expect(() => updateCapability(configDir, "llm", "test")).toThrow("stack.yml not found or invalid");
+    const spec = readStackSpec(configDir);
+    expect(spec).not.toBeNull();
+    expect(spec!.version).toBe(2);
   });
 });
 
 // ── stackSpecPath / STACK_SPEC_FILENAME ──────────────────────────────────
 
 describe("stackSpecPath", () => {
-  it("returns configDir/stack.yml", () => {
-    expect(stackSpecPath("/foo/config")).toBe("/foo/config/stack.yml");
+  it("returns stackDir/stack.yml", () => {
+    expect(stackSpecPath("/foo/config/stack")).toBe("/foo/config/stack/stack.yml");
   });
 
   it("uses STACK_SPEC_FILENAME constant", () => {
     expect(STACK_SPEC_FILENAME).toBe("stack.yml");
-    expect(stackSpecPath(configDir)).toBe(`${configDir}/${STACK_SPEC_FILENAME}`);
-  });
-});
-
-// ── writeStackSpec creates directory ─────────────────────────────────────
-
-describe("writeStackSpec", () => {
-  it("creates configDir if it does not exist", () => {
-    const nestedDir = join(configDir, "nested", "deep");
-    writeStackSpec(nestedDir, makeSpec());
-    const read = readStackSpec(nestedDir);
-    expect(read).not.toBeNull();
-    expect(read!.version).toBe(2);
   });
 });