@uniqbit/mate-core 0.18.1 → 0.18.3-canary.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniqbit/mate-core",
-  "version": "0.18.1",
+  "version": "0.18.3-canary.0",
   "description": "Core framework and plugin APIs for Mate.",
   "license": "MIT",
   "repository": {

package/src/cli/commands/doctor.ts

@@ -9,6 +9,11 @@ import type { GlobalConfigStore } from "../../lib/orchestrator/global-config-sto
 import { pathIsDirectory } from "../../lib/orchestrator/repo-local-registry";
 import { resolveRootContext, type RootContext } from "../../lib/orchestrator/root-context";
 import type { CapabilityConfig, FrameworkConfig, HubMember } from "../../lib/orchestrator/types";
+import {
+  describeUnknownAudience,
+  readAudienceSelection,
+  resolveAudience,
+} from "../../tools/setup/dynamic-plugins/audiences";
 import {
   inspectDeclaredPlugins,
   type PluginInspection,
@@ -26,6 +31,8 @@ interface DoctorDeps {
   /** Returns a member checkout's HEAD commit, or null when unreadable. */
   gitHead?: (memberPath: string) => string | null;
   inspectPlugins?: (companionPath: string) => Promise<PluginInspection>;
+  /** Environment `MATE_AUDIENCE` is read from; defaults to the process environment. */
+  env?: Record<string, string | undefined>;
 }
 
 export type DoctorKind = "core" | "working" | "companion" | "hub";
@@ -59,6 +66,10 @@ export interface DoctorReport {
   toolInstallations?: DoctorToolInstallation[];
   requiredPluginDrift?: Array<{ pluginId: string; kind: string; reason: string }>;
   pluginFailures?: PluginVerificationFailure[];
+  /** Present for a companion that declares audiences or has one selected. */
+  audiences?: { declared: string[]; active: string | null };
+  /** Set when `MATE_AUDIENCE` names an audience the companion does not declare. */
+  audienceError?: string;
   /** IDs of the capabilities the verified plugins provide. */
   pluginCapabilities?: string[];
   engineRequirement?: { range: string; ok: boolean; detail: string };
@@ -215,6 +226,19 @@ function collectConfiguredRootSections(
   report.engineRequirement = collectEngineRequirement(config);
 }
 
+function collectAudiences(
+  report: DoctorReport,
+  config: FrameworkConfig,
+  env: Record<string, string | undefined>,
+): void {
+  const declared = Object.keys(config.audiences ?? {});
+  const requested = readAudienceSelection(env);
+  if (declared.length === 0 && requested === null) return;
+  const resolution = resolveAudience(config, requested);
+  report.audiences = { declared, active: resolution.ok ? resolution.active : null };
+  if (!resolution.ok) report.audienceError = describeUnknownAudience(resolution);
+}
+
 export async function collectDoctorReport(deps: DoctorDeps = {}): Promise<DoctorReport> {
   const cwd = path.resolve(deps.cwd ?? process.cwd());
   const pathValue = deps.pathValue ?? process.env.PATH ?? "";
@@ -248,8 +272,15 @@ export async function collectDoctorReport(deps: DoctorDeps = {}): Promise<Doctor
     report.engineRequirement = collectEngineRequirement(root.config);
   }
 
+  const env = deps.env ?? process.env;
+  if (root.rootPath && root.config && kind !== "hub") {
+    collectAudiences(report, root.config, env);
+  }
+
   if (root.rootPath && root.config) {
-    const inspection = await (deps.inspectPlugins ?? inspectDeclaredPlugins)(root.rootPath);
+    const inspect =
+      deps.inspectPlugins ?? ((companionPath) => inspectDeclaredPlugins(companionPath, { env }));
+    const inspection = await inspect(root.rootPath);
     report.pluginFailures = inspection.failures;
     report.pluginCapabilities = inspection.capabilities;
   }
@@ -334,6 +365,15 @@ function renderHumanReport(report: DoctorReport): void {
   if (report.toolInstallations) {
     printSection("Tool Installations", renderToolInstallations(report.toolInstallations));
   }
+  if (report.audiences) {
+    printSection(
+      "Audiences",
+      renderKeyValueTable([
+        ["Declared", report.audiences.declared.join(", ") || "none"],
+        ["Active", report.audiences.active ?? "none"],
+      ]),
+    );
+  }
   if (report.hub) printSection("Hub Members", renderHubMembers(report.hub.members));
   // Companions with no drift produce no section at all: required plugins are
   // silent when healthy.
@@ -376,8 +416,9 @@ function renderHumanReport(report: DoctorReport): void {
  * working repository), `companion`, `hub`, or `core` (not linked) — with
  * kind-specific diagnostics: policy and capabilities for working repos,
  * capabilities and tool checks for companions, member health for hubs.
- * Declared plugins are verified strictly (allowed by `MATE_ALLOWED_PLUGINS`,
- * installed, loadable); any failure is named on stderr and exits non-zero.
+ * Declared plugins of the effective set (base plus the `MATE_AUDIENCE`
+ * audience) are verified strictly (installed, loadable); any failure is named
+ * on stderr and exits non-zero, as is an undeclared `MATE_AUDIENCE`.
  * `--json` emits the same report as one JSON document.
  */
 export async function runDoctorCommand(argv: string[] = [], deps: DoctorDeps = {}): Promise<void> {
@@ -389,5 +430,9 @@ export async function runDoctorCommand(argv: string[] = [], deps: DoctorDeps = {
   for (const failure of failures) {
     process.stderr.write(`${FRAMEWORK_NAME}: plugin ${failure.package}: ${failure.reason}\n`);
   }
+  if (report.audienceError) {
+    process.stderr.write(`${FRAMEWORK_NAME}: ${report.audienceError}\n`);
+    process.exitCode = 1;
+  }
   if (failures.length > 0) process.exitCode = 1;
 }

package/src/cli/commands/install.ts

@@ -9,6 +9,12 @@ import {
   resolveInstallContext,
 } from "../../lib/install";
 import { renderInstallExecution } from "../install-plan";
+import {
+  describeUnknownAudience,
+  installPluginDeclarations,
+  readAudienceSelection,
+  resolveAudience,
+} from "../../tools/setup/dynamic-plugins/audiences";
 import { hydrateDynamicPlugins } from "../../tools/setup/dynamic-plugins/hydrate";
 import {
   installDeclaredPlugins,
@@ -69,19 +75,31 @@ export async function runInstallCommand(argv: string[], cwd = process.cwd()): Pr
     process.exitCode = 1;
     return false;
   }
+  if (context.kind === "companion") {
+    const audience = resolveAudience(context.config, readAudienceSelection(process.env));
+    if (!audience.ok) {
+      process.stderr.write(`${FRAMEWORK_NAME}: ${describeUnknownAudience(audience)}\n`);
+      process.exitCode = 1;
+      return false;
+    }
+  }
+  const declarations =
+    context.kind === "companion" || context.kind === "hub"
+      ? installPluginDeclarations(context.config)
+      : [];
   // Root-declared plugins (companion or hub) install first and hydrate into
   // the registry before the plan is built, so one run goes install → load →
   // plan and their own install requirements are part of the plan.
   if (
     (context.kind === "companion" || context.kind === "hub") &&
     context.companionPath &&
-    context.config.plugins?.length
+    declarations.length
   ) {
     let results: PluginInstallResult[];
     try {
       results = frozen
-        ? await installDeclaredPluginsFrozen(context.companionPath, context.config.plugins)
-        : await installDeclaredPlugins(context.companionPath, context.config.plugins);
+        ? await installDeclaredPluginsFrozen(context.companionPath, declarations)
+        : await installDeclaredPlugins(context.companionPath, declarations);
     } catch (error) {
       if (!(error instanceof FrozenInstallError)) throw error;
       process.stderr.write(`${FRAMEWORK_NAME}: frozen plugin install refused: ${error.message}\n`);

package/src/cli/commands/studio/terminal-launch.ts

@@ -3,6 +3,10 @@ import path from "node:path";
 
 import { FRAMEWORK_NAME } from "../../../framework";
 import { ConfigStore, mergeWithDefaults } from "../../../lib/orchestrator/config-store";
+import {
+  effectiveStudioAgent,
+  readAudienceSelection,
+} from "../../../tools/setup/dynamic-plugins/audiences";
 import type { StudioInventory, StudioInventoryCompanion } from "./inventory";
 import { findAction, promptArgs, skillInstalledFor, SUBJECT_PATTERN } from "./actions";
 import { collectSkillInventory, type StudioSkillInventory } from "./mate-inventory";
@@ -45,18 +49,24 @@ export interface DefaultAgentOutcome {
 }
 
 /**
- * The companion's `studio.terminal.agent` for one provider. Never throws and
- * never echoes the configured value into the notice.
+ * The companion's effective default agent for one provider: the active
+ * audience's `studio.terminal.agent` (Studio's own `MATE_AUDIENCE`, never the
+ * browser's), else the base one. Never throws and never echoes the configured
+ * value into the notice.
  */
 export async function defaultAgentFor(
   companionPath: string,
   agent: TerminalAgent,
+  env: Record<string, string | undefined> = process.env,
 ): Promise<DefaultAgentOutcome> {
   const configPath = path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "framework.yaml");
   if (!fs.existsSync(configPath)) return {};
   let name: unknown;
   try {
-    name = (await new ConfigStore(configPath).load()).studio?.terminal?.agent;
+    name = effectiveStudioAgent(
+      await new ConfigStore(configPath).load(),
+      readAudienceSelection(env),
+    );
   } catch {
     return {};
   }

package/src/lib/orchestrator/config-store.ts

@@ -141,6 +141,111 @@ function validatePluginDeclarations(config: FrameworkConfig): void {
   }
 }
 
+export const AUDIENCE_NAME_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
+
+const AUDIENCE_KEYS = ["plugins", "studio"] as const;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function validateAudiencePlugins(audience: string, plugins: unknown): Map<string, string> {
+  if (!Array.isArray(plugins)) {
+    throw new ConfigError(`audience "${audience}": plugins must be a list.`);
+  }
+  const versions = new Map<string, string>();
+  for (const entry of plugins) {
+    if (
+      !isRecord(entry) ||
+      typeof entry.package !== "string" ||
+      typeof entry.version !== "string"
+    ) {
+      throw new ConfigError(
+        `audience "${audience}": plugins entry must have string package and version: ${JSON.stringify(entry)}`,
+      );
+    }
+    if (
+      entry.policy !== undefined &&
+      !PLUGIN_DECLARATION_POLICIES.includes(entry.policy as never)
+    ) {
+      throw new ConfigError(
+        `audience "${audience}": plugins entry "${entry.package}": policy "${String(entry.policy)}" is not allowed for declared plugins (allowed: ${PLUGIN_DECLARATION_POLICIES.join(", ")}).`,
+      );
+    }
+    if (versions.has(entry.package)) {
+      throw new ConfigError(
+        `audience "${audience}": package "${entry.package}" is declared more than once.`,
+      );
+    }
+    versions.set(entry.package, entry.version);
+  }
+  return versions;
+}
+
+/**
+ * Validates the optional `audiences` mapping. Only companions may declare
+ * audiences; names are safe identifiers and keys form a closed set so typos
+ * fail instead of silently doing nothing.
+ */
+function validateAudiences(config: FrameworkConfig): void {
+  const audiences = config.audiences as unknown;
+  if (audiences === undefined) return;
+  if (config.type === "hub") {
+    throw new ConfigError('Only companions may declare audiences; a "hub" framework may not.');
+  }
+  if (!isRecord(audiences)) {
+    throw new ConfigError("audiences must be a mapping of audience name to configuration.");
+  }
+
+  const basePackages = new Set((config.plugins ?? []).map((plugin) => plugin.package));
+  const seen = new Map<string, { audience: string; version: string }>();
+
+  for (const [name, audience] of Object.entries(audiences)) {
+    if (!AUDIENCE_NAME_PATTERN.test(name)) {
+      throw new ConfigError(
+        `Invalid audience name "${name}": must match ${AUDIENCE_NAME_PATTERN.source}.`,
+      );
+    }
+    if (!isRecord(audience)) {
+      throw new ConfigError(`audience "${name}" must be a mapping.`);
+    }
+    for (const key of Object.keys(audience)) {
+      if (!AUDIENCE_KEYS.includes(key as never)) {
+        throw new ConfigError(
+          `audience "${name}": unknown key "${key}" (allowed: ${AUDIENCE_KEYS.join(", ")}).`,
+        );
+      }
+    }
+
+    if (audience.plugins !== undefined) {
+      for (const [pkg, version] of validateAudiencePlugins(name, audience.plugins)) {
+        if (basePackages.has(pkg)) {
+          throw new ConfigError(
+            `audience "${name}": package "${pkg}" is also declared in base plugins.`,
+          );
+        }
+        const other = seen.get(pkg);
+        if (other && other.version !== version) {
+          throw new ConfigError(
+            `package "${pkg}" has conflicting versions in audiences "${other.audience}" (${other.version}) and "${name}" (${version}).`,
+          );
+        }
+        seen.set(pkg, other ?? { audience: name, version });
+      }
+    }
+
+    if (audience.studio !== undefined) {
+      const agent =
+        isRecord(audience.studio) && isRecord(audience.studio.terminal)
+          ? audience.studio.terminal.agent
+          : undefined;
+      if (agent !== undefined && typeof agent !== "string") {
+        throw new ConfigError(`audience "${name}": studio.terminal.agent must be a string.`);
+      }
+    }
+  }
+}
+
 export class ConfigStore extends YamlFileStore<FrameworkConfig> {
   constructor(configPath = process.env.MATE_CONFIG ?? defaultConfigPath()) {
     super(path.resolve(configPath));
@@ -150,6 +255,7 @@ export class ConfigStore extends YamlFileStore<FrameworkConfig> {
     const merged = mergeWithDefaults(migrateProfilesToAllowedAgents(await super.load()));
     validateHubConfig(merged);
     validatePluginDeclarations(merged);
+    validateAudiences(merged);
     return merged;
   }
 

package/src/lib/orchestrator/types.ts

@@ -125,6 +125,15 @@ export interface StudioTerminalConfig {
   agent?: string;
 }
 
+/**
+ * A named slice of a companion's configuration, activated by `MATE_AUDIENCE`.
+ * Plugins add to the base list; `studio.terminal.agent` overrides the base.
+ */
+export interface AudienceConfig {
+  plugins?: PluginDeclaration[];
+  studio?: { terminal?: StudioTerminalConfig };
+}
+
 export interface FrameworkConfig {
   type?: FrameworkType;
   git?: GitModeProfile;
@@ -137,6 +146,7 @@ export interface FrameworkConfig {
   packageManagers?: string[];
   engines?: EngineConstraints;
   studio?: { terminal?: StudioTerminalConfig };
+  audiences?: Record<string, AudienceConfig>;
 }
 
 export interface CompanionRegistryConfig {

package/src/tools/setup/dynamic-plugins/audiences.ts

@@ -0,0 +1,128 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { parse } from "yaml";
+
+import { FRAMEWORK_NAME } from "../../../framework";
+import type { PluginDeclaration } from "../../../lib/orchestrator/types";
+
+export const AUDIENCE_ENV = "MATE_AUDIENCE";
+
+export type AudienceResolution =
+  | { ok: true; active: string | null }
+  | { ok: false; requested: string; declared: string[] };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function pluginList(value: unknown): unknown[] {
+  return isRecord(value) && Array.isArray(value.plugins) ? value.plugins : [];
+}
+
+function audienceEntry(raw: unknown, audience: string | null): unknown {
+  if (audience === null || !isRecord(raw) || !isRecord(raw.audiences)) return undefined;
+  return Object.hasOwn(raw.audiences, audience) ? raw.audiences[audience] : undefined;
+}
+
+function studioAgent(value: unknown): unknown {
+  if (!isRecord(value) || !isRecord(value.studio) || !isRecord(value.studio.terminal)) {
+    return undefined;
+  }
+  return value.studio.terminal.agent;
+}
+
+/** `MATE_AUDIENCE` from the environment; unset, empty or blank means none. */
+export function readAudienceSelection(env: Record<string, string | undefined>): string | null {
+  const value = env[AUDIENCE_ENV]?.trim();
+  return value ? value : null;
+}
+
+/** Audience names declared by raw parsed `framework.yaml`, in declared order. */
+export function declaredAudiences(raw: unknown): string[] {
+  return isRecord(raw) && isRecord(raw.audiences) ? Object.keys(raw.audiences) : [];
+}
+
+export function resolveAudience(raw: unknown, audience: string | null): AudienceResolution {
+  if (audience === null) return { ok: true, active: null };
+  const declared = declaredAudiences(raw);
+  if (declared.includes(audience)) return { ok: true, active: audience };
+  return { ok: false, requested: audience, declared };
+}
+
+/**
+ * Base plugins followed by the active audience's, each declaration keeping
+ * its own `policy` and `config`. An unknown audience contributes nothing.
+ */
+export function effectivePluginDeclarations(raw: unknown, audience: string | null): unknown[] {
+  return [...pluginList(raw), ...pluginList(audienceEntry(raw, audience))];
+}
+
+/**
+ * Base plugins followed by every audience's, for installation only: a
+ * package shared by audiences appears once since validation guarantees one
+ * version. Runtime declarations must come from `effectivePluginDeclarations`.
+ */
+export function allPluginDeclarations(raw: unknown): unknown[] {
+  const all = [...pluginList(raw)];
+  for (const name of declaredAudiences(raw)) {
+    all.push(...pluginList(audienceEntry(raw, name)));
+  }
+  const seen = new Set<string>();
+  return all.filter((entry) => {
+    if (!isRecord(entry) || typeof entry.package !== "string") return true;
+    const key = `${entry.package}@${String(entry.version)}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+/** Operator-facing message for a `MATE_AUDIENCE` the companion does not declare. */
+export function describeUnknownAudience(
+  resolution: Extract<AudienceResolution, { ok: false }>,
+): string {
+  const declared = resolution.declared.length > 0 ? resolution.declared.join(", ") : "none";
+  return `unknown audience "${resolution.requested}" (${AUDIENCE_ENV}); declared audiences: ${declared}`;
+}
+
+/** Install-time declarations of an already validated config: base plus every audience. */
+export function installPluginDeclarations(config: unknown): PluginDeclaration[] {
+  return allPluginDeclarations(config) as PluginDeclaration[];
+}
+
+/**
+ * The active audience's Studio default agent, else the base one. Returned
+ * as found: the caller owns rejecting a value that is not a safe name.
+ */
+export function effectiveStudioAgent(raw: unknown, audience: string | null): unknown {
+  return studioAgent(audienceEntry(raw, audience)) ?? studioAgent(raw);
+}
+
+/**
+ * Raw read of the companion's `framework.yaml`. Deliberately avoids
+ * `ConfigStore.load()` — hydration runs on every invocation and must never
+ * create or migrate config files as a side effect.
+ */
+export async function readFrameworkRaw(companionPath: string): Promise<unknown> {
+  try {
+    const text = await fs.readFile(
+      path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"),
+      "utf8",
+    );
+    return (parse(text) as unknown) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export async function readEffectiveDeclarations(
+  companionPath: string,
+  audience: string | null,
+): Promise<unknown[]> {
+  return effectivePluginDeclarations(await readFrameworkRaw(companionPath), audience);
+}
+
+export async function readAllDeclarations(companionPath: string): Promise<unknown[]> {
+  return allPluginDeclarations(await readFrameworkRaw(companionPath));
+}

package/src/tools/setup/dynamic-plugins/hydrate.ts

@@ -7,7 +7,14 @@ import { CompanionResolver } from "../../../lib/orchestrator/companion-resolver"
 import { GlobalConfigStore } from "../../../lib/orchestrator/global-config-store";
 import type { Plugin } from "../plugin";
 import type { PluginRegistry } from "../registry";
-import { readDeclarations, validateDeclaration } from "./declarations";
+import {
+  describeUnknownAudience,
+  effectivePluginDeclarations,
+  readAudienceSelection,
+  readFrameworkRaw,
+  resolveAudience,
+} from "./audiences";
+import { validateDeclaration } from "./declarations";
 import { loadDynamicPlugin, type DynamicPluginLoadDeps } from "./loader";
 
 // Packages already registered in this process; re-hydration (e.g. right after
@@ -62,9 +69,9 @@ function activateDeclaredPlugin(plugin: Plugin): Plugin {
 }
 
 /**
- * Registers the companion's declared plugins into the active registry —
- * compiled-in plugins first (they are already registered), declared order
- * after. Runs before cap-command detection on every invocation. No-op
+ * Registers the companion's effective plugins (base plus the active
+ * `MATE_AUDIENCE`) into the active registry — compiled-in plugins first
+ * (they are already registered), declared order after. Runs before cap-command detection on every invocation. No-op
  * without a companion or `plugins:` entries; all diagnostics go to stderr;
  * never throws.
  */
@@ -77,7 +84,12 @@ export async function hydrateDynamicPlugins(deps: HydrateDynamicPluginsDeps = {}
       deps.companionPath ?? (await resolveCompanionQuietly(deps.cwd ?? process.cwd(), env));
     if (!companionPath) return;
 
-    const entries = await readDeclarations(companionPath);
+    const raw = await readFrameworkRaw(companionPath);
+    const audience = resolveAudience(raw, readAudienceSelection(env));
+    if (!audience.ok) {
+      warn(`${describeUnknownAudience(audience)}; applying the base configuration only`);
+    }
+    const entries = effectivePluginDeclarations(raw, audience.ok ? audience.active : null);
     if (entries.length === 0) return;
 
     const registry = deps.registry ?? getActiveDistribution().registry;

package/src/tools/setup/dynamic-plugins/verify.ts

@@ -2,7 +2,8 @@ import fs from "node:fs/promises";
 
 import { FRAMEWORK_NAME } from "../../../framework";
 import type { PluginDeclaration } from "../../../lib/orchestrator/types";
-import { readDeclarations, validateDeclaration } from "./declarations";
+import { readAudienceSelection, readEffectiveDeclarations } from "./audiences";
+import { validateDeclaration } from "./declarations";
 import { loadDynamicPlugin, type DynamicPluginLoadDeps } from "./loader";
 import { pluginPackageRoot } from "./paths";
 
@@ -18,7 +19,8 @@ export interface PluginInspection {
 }
 
 /**
- * Strict, installation-free check of every declared plugin: installed
+ * Strict, installation-free check of every effective plugin (base plus the
+ * active `MATE_AUDIENCE`; inactive audiences are not checked): installed
  * and loadable with the effective environment. Unlike hydration it fails
  * closed on the first-class problems ordinary commands only warn about.
  */
@@ -37,7 +39,7 @@ export async function inspectDeclaredPlugins(
   const failures: PluginVerificationFailure[] = [];
   const capabilities: string[] = [];
   const declarations: PluginDeclaration[] = [];
-  for (const entry of await readDeclarations(companionPath)) {
+  for (const entry of await readEffectiveDeclarations(companionPath, readAudienceSelection(env))) {
     const { declaration, error } = validateDeclaration(entry);
     if (declaration) declarations.push(declaration);
     else failures.push({ package: "(malformed entry)", reason: error ?? "invalid plugins entry" });

package/src/tools/setup.ts

@@ -28,6 +28,12 @@ import { createUvPlugin } from "./setup/package-managers/uv";
 import type { PackageManagerSetupDeps } from "./setup/package-managers/uv";
 import { applyRequiredSelectionsToConfig } from "./setup/policy";
 import { invalidateInstallState } from "../lib/install";
+import {
+  describeUnknownAudience,
+  installPluginDeclarations,
+  readAudienceSelection,
+  resolveAudience,
+} from "./setup/dynamic-plugins/audiences";
 import { hydrateDynamicPlugins } from "./setup/dynamic-plugins/hydrate";
 import { installDeclaredPlugins } from "./setup/dynamic-plugins/install";
 import {
@@ -139,6 +145,8 @@ export async function executeSetup(
     deps.configStore ??
     new ConfigStore(path.join(cwd, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"));
   const config = mergeWithDefaults(await configStore.load());
+  const audience = resolveAudience(config, readAudienceSelection(process.env));
+  if (!audience.ok) throw new ConfigError(describeUnknownAudience(audience));
   if (input.allowedAgents !== undefined) {
     config.allowedAgents = [...new Set(input.allowedAgents)];
   }
@@ -162,8 +170,9 @@ export async function executeSetup(
   // Declared plugin packages install and hydrate before the setup plan runs,
   // so a fresh clone reaches a fully applied state from one setup run
   // (install → load → plan).
-  if (config.plugins?.length) {
-    for (const result of await installDeclaredPlugins(companionPath, config.plugins)) {
+  const declarations = installPluginDeclarations(config);
+  if (declarations.length) {
+    for (const result of await installDeclaredPlugins(companionPath, declarations)) {
       if (result.status === "failed") {
         process.stderr.write(
           `${FRAMEWORK_NAME}: plugin "${result.package}" failed to install: ${result.error ?? "unknown error"}\n`,