@openpalm/lib 0.11.0-beta.9 → 0.11.0-rc.2

package/src/control-plane/lifecycle.ts

@@ -8,25 +8,23 @@ import {
   resolveConfigDir,
   resolveStashDir,
   resolveWorkspaceDir,
-  resolveCacheDir,
-  resolveStateDir,
+  resolveDataDir,
   resolveStackDir,
 } from "./home.js";
-import { ensureSecrets } from "./secrets.js";
+import { ensureSecrets, readStackSecretEnv } from "./secrets.js";
 import {
   resolveRuntimeFiles,
   writeRuntimeFiles,
-  buildEnvFiles,
   discoverStackOverlays,
   ensureComposeVolumeTargets,
 } from "./config-persistence.js";
-import { readStackSpec } from "./stack-spec.js";
 import { refreshCoreAssets } from "./core-assets.js";
 import { isSetupComplete } from "./setup-status.js";
 import { snapshotCurrentState } from "./rollback.js";
 import { checkDocker, composePreflight, composePull, composeUp, composeConfigServices, resolveComposeProjectName } from "./docker.js";
+import { buildComposeOptions } from "./compose-args.js";
 import { acquireInstallLock, releaseInstallLock } from "./install-lock.js";
-import { listEnabledAddonIds } from "./registry.js";
+import { getAddonServiceNames, listEnabledAddonIds } from "./registry.js";
 
 const IMAGE_NAMESPACE_RE = /^[a-z0-9]+(?:[._-][a-z0-9]+)*$/;
 const SEMVER_TAG_RE = /^v\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
@@ -37,8 +35,7 @@ export function createState(): ControlPlaneState {
   const configDir = resolveConfigDir();
   const stashDir = resolveStashDir();
   const workspaceDir = resolveWorkspaceDir();
-  const cacheDir = resolveCacheDir();
-  const stateDir = resolveStateDir();
+  const dataDir = resolveDataDir();
   const stackDir = resolveStackDir();
 
   const services: Record<string, "running" | "stopped"> = {};
@@ -51,8 +48,7 @@ export function createState(): ControlPlaneState {
     configDir,
     stashDir,
     workspaceDir,
-    cacheDir,
-    stateDir,
+    dataDir,
     stackDir,
     services,
     artifacts: { compose: "" },
@@ -60,6 +56,7 @@ export function createState(): ControlPlaneState {
   };
 
   ensureSecrets(bootstrapState);
+  Object.assign(process.env, readStackSecretEnv(stackDir));
 
   return bootstrapState;
 }
@@ -74,7 +71,7 @@ async function reconcileCore(
   }
 
   for (const addonName of listEnabledAddonIds(state.homeDir)) {
-    mkdirSync(`${state.stateDir}/${addonName}`, { recursive: true });
+    mkdirSync(`${state.dataDir}/${addonName}`, { recursive: true });
   }
 
   const active: string[] = [];
@@ -89,8 +86,7 @@ async function reconcileCore(
   // Preflight: validate compose merge before mutation.
   // Mandatory when compose files exist and OP_SKIP_COMPOSE_PREFLIGHT is not set.
   // Fails if Docker is unavailable (Docker is required for any compose operation).
-  const files = buildComposeFileList(state);
-  const envFiles = buildEnvFiles(state);
+  const { files, envFiles, profiles } = buildComposeOptions(state);
   if (files.length > 0 && !process.env.OP_SKIP_COMPOSE_PREFLIGHT) {
     const dockerCheck = await checkDocker();
     if (!dockerCheck.ok) {
@@ -99,12 +95,13 @@ async function reconcileCore(
         "Docker must be running before install/update/apply operations."
       );
     }
-    const preflight = await composePreflight({ files, envFiles });
+    const preflight = await composePreflight({ files, envFiles, profiles });
     if (!preflight.ok) {
-      const projectName = resolveComposeProjectName();
+      const projectName = resolveComposeProjectName(Object.assign({}, ...envFiles.map((f) => parseEnvFile(f))));
       const fileArgs = files.flatMap((f) => ["-f", f]).join(" ");
       const envArgs = envFiles.filter(existsSync).flatMap((f) => ["--env-file", f]).join(" ");
-      const resolvedCmd = `docker compose ${fileArgs} --project-name ${projectName} ${envArgs} config --quiet`;
+      const profileArgs = profiles.flatMap((p) => ["--profile", p]).join(" ");
+      const resolvedCmd = `docker compose ${fileArgs} --project-name ${projectName} ${envArgs} ${profileArgs} config --quiet`;
       throw new Error(
         `Compose preflight failed: ${preflight.stderr}\n` +
         `Resolved command: ${resolvedCmd}\n` +
@@ -125,7 +122,7 @@ async function reconcileCore(
 }
 
 export async function applyInstall(state: ControlPlaneState): Promise<void> {
-  const lock = acquireInstallLock(state.stateDir);
+  const lock = acquireInstallLock(state.dataDir);
   if (!lock) throw new Error("Another install is already in progress");
   try {
     await reconcileCore(state, { activateServices: true });
@@ -139,7 +136,7 @@ export async function applyInstall(state: ControlPlaneState): Promise<void> {
 }
 
 export async function applyUpdate(state: ControlPlaneState): Promise<{ restarted: string[] }> {
-  const lock = acquireInstallLock(state.stateDir);
+  const lock = acquireInstallLock(state.dataDir);
   if (!lock) throw new Error("Another install is already in progress");
   try {
     return { restarted: await reconcileCore(state, {}) };
@@ -149,7 +146,7 @@ export async function applyUpdate(state: ControlPlaneState): Promise<{ restarted
 }
 
 export async function applyUninstall(state: ControlPlaneState): Promise<{ stopped: string[] }> {
-  const lock = acquireInstallLock(state.stateDir);
+  const lock = acquireInstallLock(state.dataDir);
   if (!lock) throw new Error("Another install is already in progress");
   try {
     return { stopped: await reconcileCore(state, { deactivateServices: true }) };
@@ -179,7 +176,7 @@ export async function updateStackEnvToLatestImageTag(state: ControlPlaneState):
   namespace: string;
   tag: string;
 }> {
-  const systemEnvPath = `${state.stackDir}/stack.env`;
+  const systemEnvPath = `${state.stashDir}/env/stack.env`;
   const parsed = parseEnvFile(systemEnvPath);
   const namespace = (parsed.OP_IMAGE_NAMESPACE ?? process.env.OP_IMAGE_NAMESPACE ?? "openpalm").trim().toLowerCase();
 
@@ -187,10 +184,14 @@ export async function updateStackEnvToLatestImageTag(state: ControlPlaneState):
     throw new Error(`Invalid image namespace in system.env: ${namespace}`);
   }
 
+  // `assistant` is the version-of-record image: all platform images
+  // (assistant, guardian, channel, voice) are published in lockstep under the
+  // same OP_IMAGE_TAG, so its newest tag is the canonical platform version.
+
   let response: Response;
   try {
     response = await fetch(
-      `https://registry.hub.docker.com/v2/repositories/${namespace}/admin/tags?page_size=25&ordering=last_updated`,
+      `https://registry.hub.docker.com/v2/repositories/${namespace}/assistant/tags?page_size=25&ordering=last_updated`,
       { headers: { Accept: "application/json" } }
     );
   } catch (e) {
@@ -221,7 +222,7 @@ export async function applyUpgrade(
   updated: string[];
   restarted: string[];
 }> {
-  const lock = acquireInstallLock(state.stateDir);
+  const lock = acquireInstallLock(state.dataDir);
   if (!lock) throw new Error("Another install is already in progress");
   try {
     const { backupDir, updated } = await refreshCoreAssets();
@@ -247,15 +248,14 @@ export type UpgradeResult = {
  * Callers handle their own audit logging and admin self-recreation.
  */
 export async function performUpgrade(state: ControlPlaneState): Promise<UpgradeResult> {
-  const files = buildComposeFileList(state);
-  const envFiles = buildEnvFiles(state);
+  const composeOpts = buildComposeOptions(state);
 
   // Compose preflight runs inside `applyUpgrade` -> `reconcileCore`, so we
   // skip the redundant top-level call. Any merge failure aborts before
   // mutation just the same.
 
   // 1. Snapshot stack.env for rollback on failure
-  const stackEnvPath = `${state.stackDir}/stack.env`;
+  const stackEnvPath = `${state.stashDir}/env/stack.env`;
   let originalStackEnv: string | null = null;
   try {
     originalStackEnv = readFileSync(stackEnvPath, "utf-8");
@@ -278,15 +278,15 @@ export async function performUpgrade(state: ControlPlaneState): Promise<UpgradeR
     throw e;
   }
 
-  // 3. Pull images
-  const pullResult = await composePull({ files, envFiles });
+  // 3. Pull all images (core + addons, including profile-gated voice)
+  const pullResult = await composePull(composeOpts);
   if (!pullResult.ok) {
     throw new Error(`Failed to pull images: ${pullResult.stderr}`);
   }
 
-  // 4. Recreate containers
+  // 4. Recreate containers (includes profiles for voice addon)
   const services = await buildManagedServices(state);
-  const upResult = await composeUp({ files, envFiles, services, removeOrphans: true });
+  const upResult = await composeUp({ ...composeOpts, services, removeOrphans: true });
   if (!upResult.ok) {
     throw new Error(`Images pulled but failed to recreate containers: ${upResult.stderr}`);
   }
@@ -305,7 +305,7 @@ export async function performUpgrade(state: ControlPlaneState): Promise<UpgradeR
  * Used by the admin "set version" action — skips the auto-detect step in performUpgrade.
  */
 export async function applyTagChange(state: ControlPlaneState, tag: string): Promise<UpgradeResult> {
-  const stackEnvPath = `${state.stackDir}/stack.env`;
+  const stackEnvPath = `${state.stashDir}/env/stack.env`;
   const currentContent = existsSync(stackEnvPath) ? readFileSync(stackEnvPath, "utf-8") : "";
   writeFileSync(stackEnvPath, mergeEnvContent(currentContent, { OP_IMAGE_TAG: tag }, { uncomment: true }));
   const upgradeResult = await applyUpgrade(state);
@@ -319,16 +319,15 @@ export async function applyTagChange(state: ControlPlaneState, tag: string): Pro
 }
 
 export function buildComposeFileList(state: ControlPlaneState): string[] {
-  return discoverStackOverlays(state.stackDir);
+  return discoverStackOverlays(state.stackDir, state.homeDir);
 }
 
 export async function buildManagedServices(state: ControlPlaneState): Promise<string[]> {
-  const files = buildComposeFileList(state);
-  const envFiles = buildEnvFiles(state);
+  const composeOpts = buildComposeOptions(state);
 
   // Prefer compose-derived service list when Docker is available
-  if (files.length > 0 && !process.env.OP_SKIP_COMPOSE_PREFLIGHT) {
-    const result = await composeConfigServices({ files, envFiles });
+  if (composeOpts.files.length > 0 && !process.env.OP_SKIP_COMPOSE_PREFLIGHT) {
+    const result = await composeConfigServices(composeOpts);
     if (result.ok && result.services.length > 0) {
       return result.services;
     }
@@ -336,7 +335,9 @@ export async function buildManagedServices(state: ControlPlaneState): Promise<st
 
   // Fallback: static inference from CORE_SERVICES + active addon overlays
   const services: string[] = [...CORE_SERVICES];
-  services.push(...listEnabledAddonIds(state.homeDir));
+  for (const addon of listEnabledAddonIds(state.homeDir)) {
+    services.push(...getAddonServiceNames(state.homeDir, addon));
+  }
   return services;
 }
 

package/src/control-plane/markdown-task.ts

@@ -1,21 +1,18 @@
 /**
- * AKM markdown task parser.
+ * AKM task parser.
  *
- * Task files are markdown with YAML frontmatter. The frontmatter defines the
- * schedule and target; for inline-prompt tasks the markdown body is the prompt.
- *
- * Supported target types:
- *   command  — `command: [...]` YAML array (argv), run via Bun.spawn / akm tasks run
- *   prompt   — `prompt: inline` + markdown body as the prompt text
+ * Task files are YAML documents in knowledge/tasks/. Supported target types:
+ *   command  — `command: [...]` YAML array (argv)
+ *   prompt   — `prompt: <text>` inline prompt text
  *   workflow — `workflow: workflow:<ref>` + optional `params` map
  */
 import { parse as parseYaml } from "yaml";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import type { AutomationConfig } from "./scheduler.js";
 import { createLogger } from "../logger.js";
 
-const logger = createLogger("markdown-task");
+const logger = createLogger("task-file");
 
 // ── Types ─────────────────────────────────────────────────────────────────
 
@@ -35,29 +32,11 @@ export type MarkdownTaskTarget =
   | { kind: "prompt"; profile?: string; body: string }
   | { kind: "workflow"; ref: string; params: Record<string, unknown> };
 
-// ── Frontmatter splitter ──────────────────────────────────────────────────
-
-interface ParsedFile {
-  frontmatter: string;
-  body: string;
-}
-
-function splitFrontmatter(content: string): ParsedFile | null {
-  // Must start with ---
-  if (!content.startsWith("---")) return null;
-  const after = content.slice(3);
-  const end = after.indexOf("\n---");
-  if (end === -1) return null;
-  return {
-    frontmatter: after.slice(0, end).trim(),
-    body: after.slice(end + 4).trim(),
-  };
-}
-
 // ── Parser ────────────────────────────────────────────────────────────────
 
 export function parseMarkdownTask(filePath: string): MarkdownTask | null {
-  const id = filePath.replace(/.*[\\/]/, "").replace(/\.md$/, "");
+  const fileName = basename(filePath);
+  const id = fileName.replace(/\.(?:ya?ml|md)$/, "");
   let raw: string;
   try {
     raw = readFileSync(filePath, "utf-8");
@@ -66,22 +45,17 @@ export function parseMarkdownTask(filePath: string): MarkdownTask | null {
     return null;
   }
 
-  const parts = splitFrontmatter(raw);
-  if (!parts) {
-    logger.warn("task file missing frontmatter delimiters", { filePath });
-    return null;
-  }
-
+  const { frontmatter, body } = splitTaskSource(raw);
   let fm: Record<string, unknown>;
   try {
-    fm = parseYaml(parts.frontmatter) as Record<string, unknown>;
+    const parsed = parseYaml(frontmatter);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      logger.warn("task YAML is not an object", { filePath });
+      return null;
+    }
+    fm = parsed as Record<string, unknown>;
   } catch (err) {
-    logger.warn("failed to parse task frontmatter", { filePath, error: String(err) });
-    return null;
-  }
-
-  if (!fm || typeof fm !== "object") {
-    logger.warn("task frontmatter is not an object", { filePath });
+    logger.warn("failed to parse task YAML", { filePath, error: String(err) });
     return null;
   }
 
@@ -106,19 +80,19 @@ export function parseMarkdownTask(filePath: string): MarkdownTask | null {
     }
     target = { kind: "command", cmd };
   } else if (fm.prompt !== undefined) {
-    if (fm.prompt !== "inline") {
-      // Future: handle asset-ref and file-path prompt sources
-      logger.warn("task 'prompt' supports only 'inline' currently", { filePath });
+    if (typeof fm.prompt !== "string" || !fm.prompt.trim()) {
+      logger.warn("task 'prompt' must be a non-empty string", { filePath });
       return null;
     }
-    if (!parts.body) {
-      logger.warn("prompt:inline task has no markdown body", { filePath });
+    const promptBody = fm.prompt.trim() === "inline" ? body.trim() : fm.prompt.trim();
+    if (!promptBody) {
+      logger.warn("task prompt body is empty", { filePath });
       return null;
     }
     target = {
       kind: "prompt",
       profile: typeof fm.profile === "string" ? fm.profile : undefined,
-      body: parts.body,
+      body: promptBody,
     };
   } else if (fm.workflow !== undefined) {
     if (typeof fm.workflow !== "string") {
@@ -149,13 +123,19 @@ export function parseMarkdownTask(filePath: string): MarkdownTask | null {
   };
 }
 
+function splitTaskSource(raw: string): { frontmatter: string; body: string } {
+  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!match) return { frontmatter: raw, body: "" };
+  return { frontmatter: match[1] ?? "", body: match[2] ?? "" };
+}
+
 export function loadMarkdownTasks(stashDir: string): MarkdownTask[] {
   const dir = join(stashDir, "tasks");
   if (!existsSync(dir)) return [];
 
   const tasks: MarkdownTask[] = [];
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+    if (!entry.isFile() || (!entry.name.endsWith(".md") && !entry.name.endsWith(".yml") && !entry.name.endsWith(".yaml"))) continue;
     const task = parseMarkdownTask(join(dir, entry.name));
     if (task) tasks.push(task);
   }
@@ -195,6 +175,6 @@ export function taskToAutomationConfig(task: MarkdownTask): AutomationConfig {
       agent,
     },
     on_failure: "log",
-    fileName: `${task.id}.md`,
+    fileName: basename(task.source.path),
   };
 }

package/src/control-plane/opencode-client.ts

@@ -2,7 +2,7 @@
  * Shared OpenCode REST API client.
  *
  * Factory function that returns typed accessors for an OpenCode server
- * at a configurable base URL. Used by both the admin (container) and
+ * at a configurable base URL. Used by both the admin UI (host process) and
  * CLI (host subprocess) to talk to OpenCode.
  */
 

package/src/control-plane/paths.ts

@@ -5,78 +5,93 @@
  * When the directory layout changes, update this file only.
  *
  * Layout:
- *   config/        — user-editable config + system config files (auth.json, akm/)
- *   config/stack/  — compose runtime + stack config (stack.env, guardian.env, stack.yml, addons/)
- *   cache/         — regenerable/semi-persistent data (akm cache, guardian cache, rollback)
- *   state/         — persistent service data (assistant, admin, guardian, logs, backups, registry)
- *   stash/         — akm knowledge (skills, vaults, agents)
+ *   config/        — user-editable config + system config files (akm/)
+ *   config/stack/  — compose runtime + stack config (stack.env, stack.yml, auth.json, fixed compose files)
+ *   data/          — persistent service data, logs, backups, rollback
+ *   knowledge/     — akm knowledge (skills, env, secrets, agents)
  *   workspace/     — shared work area
  */
+import { dirname, basename } from "node:path";
 import type { ControlPlaneState } from "./types.js";
 
 // ── Config directory — user + system config ─────────────────────────────────
 
-/** OpenCode auth token store */
-export const authJsonPath          = (s: ControlPlaneState): string => `${s.configDir}/auth.json`;
-/** akm setup config directory (AKM_CONFIG_DIR) */
+/**
+ * OpenCode auth token store. Provider credentials are sensitive, so they live
+ * under knowledge/secrets/ (out of config/stack/) and are bind-mounted into
+ * every OpenCode-based container (assistant + guardian).
+ */
+export const authJsonPath          = (s: ControlPlaneState): string => `${s.stashDir}/secrets/auth.json`;
+/** akm config directory mounted at /etc/akm */
 export const akmConfigDir          = (s: ControlPlaneState): string => `${s.configDir}/akm`;
-/** akm setup config file (written by admin on capability save) */
+/** akm setup config file (written by the admin UI AKM action and CLI install) */
 export const akmConfigPath         = (s: ControlPlaneState): string => `${s.configDir}/akm/config.json`;
 export const tasksDir              = (s: ControlPlaneState): string => `${s.stashDir}/tasks`;
 export const assistantConfigDir    = (s: ControlPlaneState): string => `${s.configDir}/assistant`;
+/** Guardian OpenCode global config dir — bind-mounted at /etc/opencode */
+export const guardianConfigDir     = (s: ControlPlaneState): string => `${s.configDir}/guardian`;
 
 // ── Config/stack directory — compose runtime + stack config ─────────────────
 
-/** System env: capabilities, secrets, tokens */
-export const stackEnvPath          = (s: ControlPlaneState): string => `${s.stackDir}/stack.env`;
-/** Guardian HMAC channel secrets */
-export const guardianEnvPath       = (s: ControlPlaneState): string => `${s.stackDir}/guardian.env`;
-/** Stack spec: capability assignments */
-export const stackSpecFilePath     = (s: ControlPlaneState): string => `${s.stackDir}/stack.yml`;
-
-// ── Cache directory — regenerable/semi-persistent ───────────────────────────
+/**
+ * System env: non-secret runtime configuration (the Compose `--env-file`).
+ * Lives under knowledge/env/ alongside the user env file (akm `env:stack`).
+ */
+export const stackEnvPath          = (s: ControlPlaneState): string => `${s.stashDir}/env/stack.env`;
+/**
+ * Resolve the OP_HOME root from a stackDir. Normally `<home>/config/stack`;
+ * falls back to the stackDir itself for callers/tests that pass a home-shaped
+ * dir. Mirrors `resolveHomeDirFromStackDir` in secrets-files.ts so the env and
+ * secret dirs resolve consistently from the same input.
+ */
+const homeFromStackDir = (stackDir: string): string =>
+  basename(stackDir) === "stack" && basename(dirname(stackDir)) === "config"
+    ? dirname(dirname(stackDir))
+    : stackDir;
 
-export const akmCacheDir           = (s: ControlPlaneState): string => `${s.cacheDir}/akm`;
-export const guardianCacheDir      = (s: ControlPlaneState): string => `${s.cacheDir}/guardian`;
-export const rollbackDir           = (s: ControlPlaneState): string => `${s.cacheDir}/rollback`;
+/**
+ * Same as `stackEnvPath` but resolved from a `stackDir` for the few callers
+ * that only have the stack dir, not full state.
+ */
+export const stackEnvPathFromStackDir = (stackDir: string): string => `${homeFromStackDir(stackDir)}/knowledge/env/stack.env`;
 
-// ── State directory — persistent service data ───────────────────────────────
+// ── Operational state directories ───────────────────────────────────────────
 
-export const assistantServiceDir   = (s: ControlPlaneState): string => `${s.stateDir}/assistant`;
-export const adminServiceDir       = (s: ControlPlaneState): string => `${s.stateDir}/admin`;
-export const guardianServiceDir    = (s: ControlPlaneState): string => `${s.stateDir}/guardian`;
-export const guardianStashDir      = (s: ControlPlaneState): string => `${s.stateDir}/guardian/stash`;
-export const guardianAkmDir        = (s: ControlPlaneState): string => `${s.stateDir}/guardian/akm`;
-/** Shared akm operational data (data/, state/ — NOT config, which lives in config/akm/) */
-export const akmStateDir           = (s: ControlPlaneState): string => `${s.stateDir}/akm`;
-export const taskLogDir            = (s: ControlPlaneState, id: string): string => `${s.cacheDir}/akm/tasks/logs/${id}`;
-export const taskLogsRootDir       = (s: ControlPlaneState): string => `${s.cacheDir}/akm/tasks/logs`;
-export const logsDir               = (s: ControlPlaneState): string => `${s.stateDir}/logs`;
+export const akmCacheDir           = (s: ControlPlaneState): string => `${s.dataDir}/akm/cache`;
+export const rollbackDir           = (s: ControlPlaneState): string => `${s.dataDir}/rollback`;
+export const logsDir               = (s: ControlPlaneState): string => `${s.dataDir}/logs`;
 /**
  * Guardian's own audit log of channel ingress (HMAC verify, replay, rate
  * limit). Phase 6 of the auth/proxy refactor removed the OpenPalm-side
  * `admin-audit.jsonl` — OpenCode session logs are the audit trail for
  * chat + tool activity.
  */
-export const guardianAuditPath     = (s: ControlPlaneState): string => `${s.stateDir}/logs/guardian-audit.log`;
-/** One-shot 0.11.0 migration log (OP_UI_TOKEN → OPENCODE_SERVER_PASSWORD, endpoints.json move) */
-export const migration0110LogPath  = (s: ControlPlaneState): string => `${s.stateDir}/logs/migration-0.11.0.log`;
-export const backupsDir            = (s: ControlPlaneState): string => `${s.stateDir}/backups`;
-export const registryDir           = (s: ControlPlaneState): string => `${s.stateDir}/registry`;
-export const registryAddonsDir     = (s: ControlPlaneState): string => `${s.stateDir}/registry/addons`;
-export const registryAutomationsDir = (s: ControlPlaneState): string => `${s.stateDir}/registry/automations`;
-export const secretsDir            = (s: ControlPlaneState): string => `${s.stateDir}/secrets`;
-export const secretProviderPath    = (s: ControlPlaneState): string => `${s.stateDir}/secrets/provider.json`;
-export const secretsIndexPath      = (s: ControlPlaneState): string => `${s.stateDir}/secrets/plaintext-index.json`;
-export const passStoreDir          = (s: ControlPlaneState): string => `${s.stateDir}/secrets/pass-store`;
+export const guardianAuditPath     = (s: ControlPlaneState): string => `${s.dataDir}/logs/guardian-audit.log`;
+export const backupsDir            = (s: ControlPlaneState): string => `${s.dataDir}/backups`;
+
+// ── State directory — persistent service data ───────────────────────────────
 
-// ── Stash directory ─────────────────────────────────────────────────────────
+export const assistantServiceDir   = (s: ControlPlaneState): string => `${s.dataDir}/assistant`;
+export const guardianServiceDir    = (s: ControlPlaneState): string => `${s.dataDir}/guardian`;
+export const guardianAkmDir        = (s: ControlPlaneState): string => `${s.dataDir}/guardian/akm`;
+/** akm durable data — NOT config, which lives in config/akm/ */
+export const akmDataDir            = (s: ControlPlaneState): string => `${s.dataDir}/akm/data`;
+export const taskLogDir            = (s: ControlPlaneState, id: string): string => `${s.dataDir}/akm/cache/tasks/logs/${id}`;
+export const taskLogsRootDir       = (s: ControlPlaneState): string => `${s.dataDir}/akm/cache/tasks/logs`;
+export const secretsDir            = (s: ControlPlaneState): string => `${s.dataDir}/secrets`;
+export const secretProviderPath    = (s: ControlPlaneState): string => `${s.dataDir}/secrets/provider.json`;
+export const secretsIndexPath      = (s: ControlPlaneState): string => `${s.dataDir}/secrets/plaintext-index.json`;
+export const passStoreDir          = (s: ControlPlaneState): string => `${s.dataDir}/secrets/pass-store`;
 
-/** akm vault:user file — lives in the stash */
-export const akmUserVaultPath      = (s: ControlPlaneState): string => `${s.stashDir}/vaults/user.env`;
+// ── Knowledge directory ─────────────────────────────────────────────────────
+// The akm env:user file path (`knowledge/env/user.env`) is owned by
+// `akm-user-env.ts` (`userEnvPathSync`), which also handles its read/write and
+// legacy migration — kept there rather than duplicated as a bare path here.
 
 // ── Stack directory ─────────────────────────────────────────────────────────
 
 export const coreComposePath       = (s: ControlPlaneState): string => `${s.stackDir}/core.compose.yml`;
-export const addonsStackDir        = (s: ControlPlaneState): string => `${s.stackDir}/addons`;
+export const servicesComposePath   = (s: ControlPlaneState): string => `${s.stackDir}/services.compose.yml`;
+export const channelsComposePath   = (s: ControlPlaneState): string => `${s.stackDir}/channels.compose.yml`;
+export const customComposePath     = (s: ControlPlaneState): string => `${s.stackDir}/custom.compose.yml`;
 export const addonComposePath      = (s: ControlPlaneState, name: string): string => `${s.stackDir}/addons/${name}/compose.yml`;

package/src/control-plane/profile-ids.ts

@@ -0,0 +1,21 @@
+export type HardwareProfileVariant = 'cpu' | 'cuda' | 'rocm';
+
+const PROFILE_ID_RE = /^addon\.([a-z0-9-]+)(?:\.(cpu|cuda|rocm))?$/;
+
+export function addonProfileId(addon: string, variant: HardwareProfileVariant): string {
+  return `addon.${addon}.${variant}`;
+}
+
+export function resolveHardwareProfileVariant(profileId: string): HardwareProfileVariant | null {
+  return (profileId.match(PROFILE_ID_RE)?.[2] as HardwareProfileVariant | undefined) ?? null;
+}
+
+export function canonicalAddonProfileSelection(addon: string, profile: string): string {
+  const trimmed = profile.trim();
+  if (!trimmed) return '';
+
+  const match = trimmed.match(PROFILE_ID_RE);
+  if (!match || match[1] !== addon) return '';
+
+  return trimmed;
+}

package/src/control-plane/provider-models.ts

@@ -4,7 +4,7 @@
  * Used by the admin capabilities test endpoint and the CLI setup wizard
  * to enumerate the models a configured provider exposes.
  */
-import { readStackEnv } from "./secrets.js";
+import { readStackRuntimeEnv } from "./secrets.js";
 import { PROVIDER_DEFAULT_URLS } from "../provider-constants.js";
 
 /** Static model list for Anthropic (no listing API available). */
@@ -24,7 +24,7 @@ const ANTHROPIC_MODELS = [
  *
  * - Empty input → empty string.
  * - `env:NAME` form → looks up `NAME` in `process.env` first, then falls back
- *   to `config/stack/stack.env` resolved against `stackDir`.
+   *   to `knowledge/secrets/<NAME>` resolved against `stackDir`.
  * - Anything else → returned verbatim (treated as a literal key value).
  */
 function resolveApiKey(apiKeyRef: string, stackDir: string): string {
@@ -34,7 +34,7 @@ function resolveApiKey(apiKeyRef: string, stackDir: string): string {
   const varName = apiKeyRef.slice(4);
   if (process.env[varName]) return process.env[varName]!;
 
-  const secrets = readStackEnv(stackDir);
+  const secrets = readStackRuntimeEnv(stackDir);
   return secrets[varName] ?? "";
 }