@uniqbit/mate-core 0.15.1-canary.1 → 0.15.1-canary.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniqbit/mate-core",
-  "version": "0.15.1-canary.1",
+  "version": "0.15.1-canary.3",
   "description": "Core framework and plugin APIs for Mate.",
   "license": "MIT",
   "files": [

package/src/cli/commands/companion/link.ts

@@ -3,7 +3,7 @@ import path from "node:path";
 import { spawnSync } from "node:child_process";
 import fs from "node:fs/promises";
 
-import { frameworkConfig } from "../../../framework";
+import { FRAMEWORK_NAME } from "../../../framework";
 import {
   selectCompanionLinkInputs,
   type CompanionLinkInputs,
@@ -48,7 +48,7 @@ interface CompanionLinkCommandDeps {
 
 /** All companions surfaced by the "existing companion" picker live under this directory. */
 function companionsHomeDir(): string {
-  return path.join(os.homedir(), `.${frameworkConfig.name}`, "companions");
+  return path.join(os.homedir(), `.${FRAMEWORK_NAME}`, "companions");
 }
 
 function isInsideDir(parentDir: string, candidatePath: string): boolean {

package/src/cli/commands/config.ts

@@ -1,9 +1,9 @@
 import os from "node:os";
 import path from "node:path";
 import { execSync } from "node:child_process";
-import { frameworkConfig } from "../../framework";
+import { FRAMEWORK_NAME } from "../../framework";
 
-const getGlobalConfigDir = () => path.join(os.homedir(), `.${frameworkConfig.name}`);
+const getGlobalConfigDir = () => path.join(os.homedir(), `.${FRAMEWORK_NAME}`);
 
 /**
  * @command mate config

package/src/cli/commands/doctor.ts

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
-import { frameworkConfig } from "../../framework";
+import { FRAMEWORK_NAME, frameworkConfig } from "../../framework";
 import { getActiveDistribution } from "../../distribution";
 import { CompanionResolver } from "../../lib/orchestrator/companion-resolver";
 import { CompanionStore, resolvePolicyFromConfig } from "../../lib/orchestrator/companion-store";
@@ -34,7 +34,7 @@ interface ToolCheck {
 }
 
 function storesForCompanion(companionPath: string): CompanionStores {
-  const configDir = path.join(companionPath, `.${frameworkConfig.name}`, "config");
+  const configDir = path.join(companionPath, `.${FRAMEWORK_NAME}`, "config");
   return {
     configStore: new ConfigStore(path.join(configDir, "framework.yaml")),
     workingRepoStore: new WorkingRepoStore(path.join(configDir, "registry.yaml")),
@@ -42,7 +42,7 @@ function storesForCompanion(companionPath: string): CompanionStores {
 }
 
 async function hasLocalCompanionConfig(cwd: string): Promise<boolean> {
-  const localDir = path.join(cwd, `.${frameworkConfig.name}`);
+  const localDir = path.join(cwd, `.${FRAMEWORK_NAME}`);
   const localLegacyDirs = frameworkConfig.legacyNames.map((name) => path.join(cwd, `.${name}`));
   await migrateConfigDir(localDir, localLegacyDirs);
 

package/src/cli/commands/install.ts

@@ -1,4 +1,5 @@
 import { confirm } from "../confirm";
+import { frameworkCommandName } from "../../framework";
 import {
   buildInstallPlan,
   inspectInstallPlan,
@@ -8,6 +9,23 @@ import {
   resolveInstallContext,
 } from "../../lib/install";
 import { renderInstallExecution } from "../install-plan";
+import { hydrateDynamicPlugins } from "../../tools/setup/dynamic-plugins/hydrate";
+import {
+  installDeclaredPlugins,
+  type PluginInstallResult,
+} from "../../tools/setup/dynamic-plugins/install";
+
+export function reportPluginInstallResults(results: PluginInstallResult[]): void {
+  for (const result of results) {
+    if (result.status === "failed") {
+      process.stderr.write(
+        `${frameworkCommandName()}: plugin "${result.package}" failed to install: ${result.error ?? "unknown error"}\n`,
+      );
+    } else if (result.status === "installed") {
+      console.log(`  installed plugin ${result.package}@${result.resolvedVersion}`);
+    }
+  }
+}
 
 function printPlanText(plan: Awaited<ReturnType<typeof inspectInstallPlan>>): void {
   if (plan.context.message) process.stderr.write(`${plan.context.message}\n\n`);
@@ -36,6 +54,15 @@ export async function runInstallCommand(argv: string[], cwd = process.cwd()): Pr
     process.exitCode = 1;
     return false;
   }
+  // Companion-declared plugins 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.companionPath && context.config.plugins?.length) {
+    reportPluginInstallResults(
+      await installDeclaredPlugins(context.companionPath, context.config.plugins),
+    );
+    await hydrateDynamicPlugins({ companionPath: context.companionPath });
+  }
   const plan = await inspectInstallPlan(buildInstallPlan(context));
   const missing = plan.requirements.filter((item) => !item.satisfied);
   let execution: Awaited<ReturnType<typeof renderInstallExecution>>;
@@ -44,7 +71,9 @@ export async function runInstallCommand(argv: string[], cwd = process.cwd()): Pr
     if (missing.length > 0 && !skipConfirm) {
       const ok = await confirm("Install the missing requirements? [y/N] ");
       if (!ok) {
-        process.stderr.write("Installation declined. Run `mate install --yes` to continue.\n");
+        process.stderr.write(
+          `Installation declined. Run \`${frameworkCommandName()} install --yes\` to continue.\n`,
+        );
         process.exitCode = 1;
         return false;
       }
@@ -54,7 +83,7 @@ export async function runInstallCommand(argv: string[], cwd = process.cwd()): Pr
     printPlanText(plan);
     if (!skipConfirm) {
       process.stderr.write(
-        "mate: installation requires confirmation in a TTY. Re-run with `mate install --yes`.\n",
+        `${frameworkCommandName()}: installation requires confirmation in a TTY. Re-run with \`${frameworkCommandName()} install --yes\`.\n`,
       );
       process.exitCode = 1;
       return false;
@@ -73,9 +102,13 @@ export async function runInstallCommand(argv: string[], cwd = process.cwd()): Pr
   }
   if (!execution.ok) {
     for (const result of execution.results.filter((item) => item.status === "failed")) {
-      process.stderr.write(`mate: ${result.id} failed: ${result.error ?? "unknown error"}\n`);
+      process.stderr.write(
+        `${frameworkCommandName()}: ${result.id} failed: ${result.error ?? "unknown error"}\n`,
+      );
     }
-    process.stderr.write("Installation is incomplete. Re-run `mate install` after remediation.\n");
+    process.stderr.write(
+      `Installation is incomplete. Re-run \`${frameworkCommandName()} install\` after remediation.\n`,
+    );
     process.exitCode = 1;
     return false;
   }
@@ -85,9 +118,11 @@ export async function runInstallCommand(argv: string[], cwd = process.cwd()): Pr
     await saveCompleteInstallState(plan, execution.results);
   } catch (error) {
     process.stderr.write(
-      `mate: installation completed but companion reconciliation failed: ${error instanceof Error ? error.message : String(error)}\n`,
+      `${frameworkCommandName()}: installation completed but companion reconciliation failed: ${error instanceof Error ? error.message : String(error)}\n`,
+    );
+    process.stderr.write(
+      `Installation is incomplete. Re-run \`${frameworkCommandName()} install\`.\n`,
     );
-    process.stderr.write("Installation is incomplete. Re-run `mate install`.\n");
     process.exitCode = 1;
     return false;
   }

package/src/cli/commands/launch/shared.ts

@@ -1,3 +1,4 @@
+import { frameworkCommandName } from "../../../framework";
 import { FrameworkLauncher } from "../../../lib/orchestrator/launcher";
 import {
   LaunchPreflightError,
@@ -42,7 +43,7 @@ export function parseLaunchArgs(argv: string[]): ParsedLaunchArgs | null {
   const agentArgs = separatorIndex >= 0 ? argv.slice(separatorIndex + 1) : [];
 
   for (const arg of optionArgs) {
-    process.stderr.write(`mate: unknown launch option: ${arg}\n`);
+    process.stderr.write(`${frameworkCommandName()}: unknown launch option: ${arg}\n`);
     process.exitCode = 1;
     return null;
   }
@@ -107,14 +108,16 @@ export async function runLaunchToolCommand(
     progress?.stop();
 
     if (error instanceof ToolNotAllowedError) {
-      process.stderr.write(`mate: \`${tool}\` is disallowed by active repository policy.\n`);
+      process.stderr.write(
+        `${frameworkCommandName()}: \`${tool}\` is disallowed by active repository policy.\n`,
+      );
       process.exitCode = 1;
       return;
     }
 
     if (error instanceof RepositoryNotSelectedError) {
       process.stderr.write(`${error.message}\n`);
-      process.stderr.write("Run `mate companion link` first.\n");
+      process.stderr.write(`Run \`${frameworkCommandName()} companion link\` first.\n`);
       process.exitCode = 1;
       return;
     }

package/src/cli/commands/setup.ts

@@ -1,6 +1,6 @@
 import path from "node:path";
 
-import { frameworkConfig } from "../../framework";
+import { FRAMEWORK_NAME, frameworkCommandName } from "../../framework";
 import { ConfigStore, defaultConfig } from "../../lib/orchestrator/config-store";
 import { executeSetup } from "../../tools/setup";
 import {
@@ -98,7 +98,7 @@ async function runSetupFlow(
     if (await checkWorkingRepo(cwd)) {
       process.stderr.write(
         `Warning: this directory looks like a working repository (project files detected).\n` +
-          `Initializing it as a ${frameworkConfig.name} companion here may not be what you want.\n`,
+          `Initializing it as a ${frameworkCommandName()} companion here may not be what you want.\n`,
       );
     }
     const ok = await askConfirm("Initialize this directory as a Mate companion repository? [y/N] ");
@@ -156,7 +156,7 @@ async function runSetupFlow(
       ? getSetupSelectionsFromConfig(defaultConfig())
       : getSetupSelectionsFromConfig(
           await new ConfigStore(
-            path.join(targetCwd, `.${frameworkConfig.name}`, "config", "framework.yaml"),
+            path.join(targetCwd, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"),
           ).load(),
         );
 

package/src/cli/commands/update.ts

@@ -1,7 +1,7 @@
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 
-import { frameworkConfig } from "../../framework";
+import { frameworkCommandName } from "../../framework";
 import {
   OPENCODE_PLUGIN_PACKAGE_NAME,
   warmOpenCodePluginCache,
@@ -20,7 +20,7 @@ type InstallResult = ReturnType<typeof installPublicPackageSync>;
 function writeNpmOnlyRecoveryMessage(): void {
   const { packageName, registry } = getUpdateConfig();
   process.stderr.write(
-    `${frameworkConfig.name}: self-update is only supported for npm-installed Mate.\n`,
+    `${frameworkCommandName()}: self-update is only supported for npm-installed Mate.\n`,
   );
   if (packageName.startsWith("@uniqbit/")) {
     process.stderr.write(
@@ -88,7 +88,7 @@ export async function runUpdateCommand(argv: string[]): Promise<void> {
     latest = await updateCommandDeps.fetchLatestVersion();
   } catch {
     process.stderr.write(
-      `${frameworkConfig.name}: could not reach registry to check for updates\n`,
+      `${frameworkCommandName()}: could not reach registry to check for updates\n`,
     );
     process.exitCode = 1;
     return;
@@ -96,7 +96,7 @@ export async function runUpdateCommand(argv: string[]): Promise<void> {
 
   if (checkOnly) {
     if (updateCommandDeps.isNewer(latest, current)) {
-      console.log(`${frameworkConfig.name}: update available (${current} → ${latest})`);
+      console.log(`${frameworkCommandName()}: update available (${current} → ${latest})`);
       process.exitCode = 1;
     } else {
       console.log("Up to date.");
@@ -127,11 +127,11 @@ export async function runUpdateCommand(argv: string[]): Promise<void> {
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") {
       process.stderr.write(
-        `${frameworkConfig.name}: npm is required for self-update but was not found on PATH\n`,
+        `${frameworkCommandName()}: npm is required for self-update but was not found on PATH\n`,
       );
     } else {
       process.stderr.write(
-        `${frameworkConfig.name}: could not verify the npm installation used for self-update\n`,
+        `${frameworkCommandName()}: could not verify the npm installation used for self-update\n`,
       );
     }
     writeNpmOnlyRecoveryMessage();
@@ -148,7 +148,7 @@ export async function runUpdateCommand(argv: string[]): Promise<void> {
   const result = updateCommandDeps.installLatest(latest);
   if (result.status !== 0 || result.error) {
     process.stderr.write(
-      `${frameworkConfig.name}: upgrade command exited with status ${result.status ?? 1}\n`,
+      `${frameworkCommandName()}: upgrade command exited with status ${result.status ?? 1}\n`,
     );
     process.exitCode = 1;
     return;
@@ -163,7 +163,7 @@ export async function runUpdateCommand(argv: string[]): Promise<void> {
   if (!warmed.ok) {
     process.stderr.write(
       [
-        `${frameworkConfig.name}: could not pre-fetch ${OPENCODE_PLUGIN_PACKAGE_NAME}@${latest} for OpenCode.`,
+        `${frameworkCommandName()}: could not pre-fetch ${OPENCODE_PLUGIN_PACKAGE_NAME}@${latest} for OpenCode.`,
         "The next managed OpenCode launch will download it (requires registry access).",
         ...(warmed.detail ? [`Details: ${warmed.detail}`] : []),
       ].join("\n") + "\n",
@@ -173,7 +173,7 @@ export async function runUpdateCommand(argv: string[]): Promise<void> {
   const postInstall = updateCommandDeps.runPostInstall(skipConfirm);
   if (postInstall.status !== 0 || postInstall.error) {
     process.stderr.write(
-      `\nUpgraded to ${latest}, but installation is incomplete. Run \`mate install\`.\n`,
+      `\nUpgraded to ${latest}, but installation is incomplete. Run \`${frameworkCommandName()} install\`.\n`,
     );
     process.exitCode = 1;
     return;

package/src/cli/main.ts

@@ -1,4 +1,5 @@
 import { getActiveDistribution } from "../distribution";
+import { frameworkCommandName } from "../framework";
 import {
   enforceUpdateIfRequired,
   scheduleBackgroundCheck,
@@ -17,6 +18,7 @@ import { runUpdateCommand } from "./commands/update";
 import { runInstallCommand } from "./commands/install";
 import { inspectInstallPreflight } from "../lib/install";
 import { ensureUnambiguousCompanion } from "./commands/shared/companion-selection";
+import { hydrateDynamicPlugins } from "../tools/setup/dynamic-plugins/hydrate";
 import { findPluginCliCommand } from "./plugin-commands";
 import { usage } from "./usage";
 
@@ -35,11 +37,13 @@ export function isInstallRecoveryCommand(command?: string, subcommand?: string):
 export interface MainDeps {
   ensureUnambiguousCompanion: typeof ensureUnambiguousCompanion;
   inspectInstallPreflight: typeof inspectInstallPreflight;
+  hydrateDynamicPlugins: typeof hydrateDynamicPlugins;
 }
 
 const mainDeps: MainDeps = {
   ensureUnambiguousCompanion,
   inspectInstallPreflight,
+  hydrateDynamicPlugins,
 };
 
 export async function main(argv = process.argv, deps: MainDeps = mainDeps): Promise<void> {
@@ -50,6 +54,12 @@ export async function main(argv = process.argv, deps: MainDeps = mainDeps): Prom
     return;
   }
 
+  // Companion-declared plugins register before cap-command detection so
+  // their commands route like compiled-in ones (including MCP servers whose
+  // command is their own cap subcommand). Diagnostics stay on stderr; a
+  // missing or ambiguous companion makes this a no-op.
+  await deps.hydrateDynamicPlugins();
+
   // Plugin commands (`mate cap <namespace> <command>`) own their stdout (an
   // MCP server speaks JSON-RPC over it), so banners and background chatter
   // are suppressed for them.
@@ -81,8 +91,10 @@ export async function main(argv = process.argv, deps: MainDeps = mainDeps): Prom
   if (!isInstallRecoveryCommand(command, subcommand)) {
     const preflight = await deps.inspectInstallPreflight();
     if (!preflight.ok) {
-      console.error(`mate: ${preflight.reason ?? "installation is incomplete"}`);
-      console.error("Run `mate install` before continuing.");
+      console.error(
+        `${frameworkCommandName()}: ${preflight.reason ?? "installation is incomplete"}`,
+      );
+      console.error(`Run \`${frameworkCommandName()} install\` before continuing.`);
       process.exitCode = 1;
       return;
     }

package/src/cli/plugin-commands.ts

@@ -1,4 +1,5 @@
 import { getActiveDistribution } from "../distribution";
+import { frameworkCommandName } from "../framework";
 import { resolveInstallContext } from "../lib/install";
 import type { FrameworkConfig } from "../lib/orchestrator/types";
 import type { Plugin, PluginCliCommand } from "../tools/setup/plugin";
@@ -85,7 +86,7 @@ export async function ensureCapabilityEnabled(
   const loadConfig = deps.loadConfig ?? (async () => (await resolveInstallContext()).config);
   if (plugin?.isEnabled(await loadConfig())) return true;
 
-  const name = distribution.config.name;
+  const name = frameworkCommandName();
   console.error(
     `${name}: the "${pluginId}" capability is not enabled for this companion. ` +
       `Enable it via \`${name} companion setup\`.`,
@@ -95,7 +96,7 @@ export async function ensureCapabilityEnabled(
 }
 
 function usageFor(plugin: Plugin): string {
-  const distributionName = getActiveDistribution().config.name;
+  const distributionName = frameworkCommandName();
   const namespace = namespaceOf(plugin);
   const lines = (plugin.cliCommands ?? []).map(
     (command) => `  ${distributionName} cap ${namespace} ${command.name}  ${command.description}`,

package/src/cli/usage.ts

@@ -1,9 +1,12 @@
-import { frameworkConfig } from "../framework";
+import { getActiveDistribution } from "../distribution";
+import { FRAMEWORK_NAME, frameworkCommandName } from "../framework";
 
 export function usage(): string {
-  const n = frameworkConfig.name;
+  const n = frameworkCommandName();
+  const packageName =
+    getActiveDistribution().config.update?.packageName ?? `@uniqbit/${FRAMEWORK_NAME}`;
   return [
-    `${n.charAt(0).toUpperCase() + n.slice(1)} CLI (@uniqbit/${n})`,
+    `${n.charAt(0).toUpperCase() + n.slice(1)} CLI (${packageName})`,
     "",
     "Commands:",
     ` ${n} install [--yes]`,

package/src/create-mate.ts

@@ -1,5 +1,6 @@
 import { main } from "./cli/main";
 import { setActiveDistribution, type DistributionConfig } from "./distribution";
+import { FRAMEWORK_NAME } from "./framework";
 import { createBunPlugin } from "./tools/setup/package-managers/bun";
 import { createUvPlugin } from "./tools/setup/package-managers/uv";
 import type { PluginRegistration } from "./tools/setup/plugin";
@@ -23,15 +24,15 @@ export interface MateCli {
  * Assemble a distribution from an identity config and plugin registration
  * entries. Distributions choose their plugin set; the framework always adds
  * bun and uv as required runtime substrate, plus gitignore management named
- * after `config.name` (built last since it reads the full plugin set).
- * Returns the runnable CLI.
+ * after the framework identity (built last since it reads the full plugin
+ * set). Returns the runnable CLI.
  */
 export function createMate({ config, plugins, main: runMain = main }: CreateMateOptions): MateCli {
   const registry = new PluginRegistry([
     ...plugins,
     { plugin: createBunPlugin(), policy: "required" },
     { plugin: createUvPlugin(), policy: "required" },
-    createGitignorePlugin(config.name),
+    createGitignorePlugin(FRAMEWORK_NAME),
   ]);
   setActiveDistribution({ config, registry });
   return {

package/src/framework.ts

@@ -1,5 +1,25 @@
 import { getActiveDistribution } from "./distribution";
 
+/**
+ * Framework identity: names everything identity-shaped regardless of how the
+ * CLI is invoked — state directories (`~/.mate`, `.mate/`), managed-block
+ * markers, `MATE_*` env values, and the `companion-policy framework`
+ * attribute. A whitelabel distribution changes the invocation name only;
+ * identity stays `mate`. Use `frameworkCommandName()` for anything the user
+ * or an agent types.
+ */
+export const FRAMEWORK_NAME = "mate";
+
+/**
+ * Invocation name: how this distribution's CLI is invoked, derived from the
+ * package's `bin` key (`config.name`). Drives usage output, command hints,
+ * error prefixes, agent guidance, and permission entries — never paths,
+ * markers, or env values (use `FRAMEWORK_NAME` for those).
+ */
+export function frameworkCommandName(): string {
+  return getActiveDistribution().config.name;
+}
+
 /**
  * Live view of the active distribution's identity. Framework modules read
  * identity through this object; the values always come from the config the

package/src/index.ts

@@ -21,6 +21,16 @@ export {
   type NormalizedRegistration,
 } from "./tools/setup/registry";
 export { ensureCapabilityEnabled, type EnsureCapabilityEnabledDeps } from "./cli/plugin-commands";
+// Dynamic plugin authors: import from this package as TYPES ONLY. Runtime
+// imports resolve a second, uninitialized copy of mate-core inside the
+// plugin's own node_modules; all runtime behavior flows through PluginHost.
+export {
+  createPluginHost,
+  PLUGIN_API_VERSION,
+  SUPPORTED_PLUGIN_API_VERSIONS,
+  type CreatePlugin,
+  type PluginHost,
+} from "./tools/setup/dynamic-plugins/host";
 export type {
   CapabilityPlugin,
   InstructionsService,
@@ -36,4 +46,8 @@ export type {
   SetupContext,
   TemplatesService,
 } from "./tools/setup/plugin";
-export type { FrameworkConfig } from "./lib/orchestrator/types";
+export type {
+  FrameworkConfig,
+  PluginDeclaration,
+  PluginDeclarationPolicy,
+} from "./lib/orchestrator/types";

package/src/lib/install.ts

@@ -8,7 +8,7 @@ import { CompanionResolver } from "./orchestrator/companion-resolver";
 import { checkEngineRequirement } from "./orchestrator/engine-guard";
 import { GlobalConfigStore } from "./orchestrator/global-config-store";
 import { YamlFileStore } from "./orchestrator/yaml-file-store";
-import { frameworkConfig } from "../framework";
+import { FRAMEWORK_NAME } from "../framework";
 import type { FrameworkConfig } from "./orchestrator/types";
 import { getActiveDistribution } from "../distribution";
 import { createBunPlugin } from "../tools/setup/package-managers/bun";
@@ -55,7 +55,7 @@ export interface InstallState {
 }
 
 function defaultInstallStateRoot(): string {
-  return path.join(os.homedir(), `.${frameworkConfig.name}`, "install-state");
+  return path.join(os.homedir(), `.${FRAMEWORK_NAME}`, "install-state");
 }
 
 export function getInstallStatePath(
@@ -107,12 +107,7 @@ function coreContext(): InstallContext {
 }
 
 async function contextForCompanion(companionPath: string): Promise<InstallContext> {
-  const configPath = path.join(
-    companionPath,
-    `.${frameworkConfig.name}`,
-    "config",
-    "framework.yaml",
-  );
+  const configPath = path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "framework.yaml");
   const config = mergeWithDefaults(await new ConfigStore(configPath).load());
   return {
     kind: "companion",
@@ -124,7 +119,7 @@ async function contextForCompanion(companionPath: string): Promise<InstallContex
 
 async function hasLocalConfig(cwd: string): Promise<boolean> {
   try {
-    await fs.access(path.join(cwd, `.${frameworkConfig.name}`, "config", "framework.yaml"));
+    await fs.access(path.join(cwd, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"));
     return true;
   } catch {
     return false;

package/src/lib/orchestrator/adapters/base.ts

@@ -3,7 +3,7 @@ import path from "node:path";
 
 import { version } from "../../../../package.json";
 import { isCommandOnPath } from "../../fs-utils";
-import { frameworkConfig } from "../../../framework";
+import { FRAMEWORK_NAME, frameworkCommandName } from "../../../framework";
 import { getReactDoctorBinPath, getWrapperBinPath } from "../../package-paths";
 import {
   GRAPHIFY_OUTPUT_SUBDIR,
@@ -77,7 +77,8 @@ export abstract class LaunchAdapter {
     const wrapperBinPath = getWrapperBinPath();
     const env: NodeJS.ProcessEnv = {
       ...process.env,
-      MATE_NAME: frameworkConfig.name,
+      MATE_NAME: FRAMEWORK_NAME,
+      MATE_COMMAND: frameworkCommandName(),
       MATE_VERSION: version,
       MATE_ARTIFACT_PATH: context.companionPath,
       MATE_WRAPPER_BIN_PATH: wrapperBinPath,
@@ -148,7 +149,7 @@ export abstract class LaunchAdapter {
         command: this.toolName,
         args: builtArgs,
         env,
-        warning: `${frameworkConfig.name}: headroom capability enabled but \`headroom\` was not found on PATH; install with \`uv tool install "headroom-ai[all]"\`; launching ${this.toolName} directly\n`,
+        warning: `${frameworkCommandName()}: headroom capability enabled but \`headroom\` was not found on PATH; install with \`uv tool install "headroom-ai[all]"\`; launching ${this.toolName} directly\n`,
       };
     }
 
@@ -182,7 +183,7 @@ export abstract class LaunchAdapter {
           command: this.toolName,
           args: builtArgs,
           env,
-          warning: `${frameworkConfig.name}: headroom proxy failed to become ready on port ${port} after ${maxProxyStartAttempts} attempts; launching ${this.toolName} directly${errorDetail}\n`,
+          warning: `${frameworkCommandName()}: headroom proxy failed to become ready on port ${port} after ${maxProxyStartAttempts} attempts; launching ${this.toolName} directly${errorDetail}\n`,
         };
       }
     }

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

@@ -1,14 +1,14 @@
 import path from "node:path";
 
-import { frameworkConfig } from "../../framework";
+import { FRAMEWORK_NAME } from "../../framework";
 import { getDefaultSetupSelections } from "./setup-compatibilities";
 import { YamlFileStore } from "./yaml-file-store";
-import { type FrameworkConfig } from "./types";
+import { ConfigError, type FrameworkConfig } from "./types";
 
 export const RTK_CAPABILITY_SPLIT_MIGRATION = "rtk-capability-split-v1";
 
 function defaultConfigPath(): string {
-  return `.${frameworkConfig.name}/config/framework.yaml`;
+  return `.${FRAMEWORK_NAME}/config/framework.yaml`;
 }
 
 export function defaultConfig(): FrameworkConfig {
@@ -54,6 +54,23 @@ export function migrateRtkCapabilitySplit(config: FrameworkConfig): FrameworkCon
   };
 }
 
+export const PLUGIN_DECLARATION_POLICIES = ["default", "optional"] as const;
+
+/**
+ * Validates the `plugins` list of a loaded config. Declared plugins may not
+ * claim `required` — required-ness is a distribution prerogative.
+ */
+export function validatePluginDeclarations(config: FrameworkConfig): void {
+  for (const declaration of config.plugins ?? []) {
+    const policy = declaration.policy as string | undefined;
+    if (policy !== undefined && !PLUGIN_DECLARATION_POLICIES.includes(policy as never)) {
+      throw new ConfigError(
+        `plugins entry "${declaration.package}": policy "${policy}" is not allowed for declared plugins (allowed: ${PLUGIN_DECLARATION_POLICIES.join(", ")}).`,
+      );
+    }
+  }
+}
+
 export class ConfigStore extends YamlFileStore<FrameworkConfig> {
   constructor(configPath = process.env.MATE_CONFIG ?? defaultConfigPath()) {
     super(path.resolve(configPath));
@@ -61,6 +78,7 @@ export class ConfigStore extends YamlFileStore<FrameworkConfig> {
 
   override async load(): Promise<FrameworkConfig> {
     const merged = mergeWithDefaults(await super.load());
+    validatePluginDeclarations(merged);
     const needsMigration = !(merged.migrations ?? []).includes(RTK_CAPABILITY_SPLIT_MIGRATION);
     const config = migrateRtkCapabilitySplit(merged);
     if (needsMigration) await this.save(config);

package/src/lib/orchestrator/framework-context.ts

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
-import { frameworkConfig } from "../../framework";
+import { FRAMEWORK_NAME, frameworkConfig } from "../../framework";
 import { CompanionResolver } from "./companion-resolver";
 import { ConfigStore } from "./config-store";
 import { GlobalConfigStore } from "./global-config-store";
@@ -45,7 +45,7 @@ function makeContext(
   contextKind: FrameworkContext["contextKind"],
   repository?: LinkedRepository,
 ): FrameworkContext {
-  const configDir = path.join(companionPath, `.${frameworkConfig.name}`, "config");
+  const configDir = path.join(companionPath, `.${FRAMEWORK_NAME}`, "config");
   return {
     configStore: new ConfigStore(path.join(configDir, "framework.yaml")),
     workingRepoStore: new WorkingRepoStore(path.join(configDir, "registry.yaml")),
@@ -79,7 +79,7 @@ export async function resolveFrameworkContext(
     );
   }
 
-  const localDir = path.join(cwd, `.${frameworkConfig.name}`);
+  const localDir = path.join(cwd, `.${FRAMEWORK_NAME}`);
   const localLegacyDirs = frameworkConfig.legacyNames.map((n) => path.join(cwd, `.${n}`));
   await migrateConfigDir(localDir, localLegacyDirs);
 
@@ -170,7 +170,7 @@ export async function resolveForCapability(
 
   // Fallback: cwd is the companion directory — resolve from its local config.
   // This is specific to mate cap; resolveForLaunch does NOT get this fallback.
-  const localDir = path.join(cwd, `.${frameworkConfig.name}`);
+  const localDir = path.join(cwd, `.${FRAMEWORK_NAME}`);
   const localLegacyDirs = frameworkConfig.legacyNames.map((n) => path.join(cwd, `.${n}`));
   await migrateConfigDir(localDir, localLegacyDirs);
 

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

@@ -1,7 +1,7 @@
 import os from "node:os";
 import path from "node:path";
 
-import { frameworkConfig } from "../../framework";
+import { FRAMEWORK_NAME, frameworkConfig } from "../../framework";
 import { YamlFileStore } from "./yaml-file-store";
 import { migrateConfigDir } from "./migration";
 
@@ -21,9 +21,8 @@ function normalizeGlobalConfig(config: GlobalConfig | null): GlobalConfig {
   };
 }
 
-// Lazy: the distribution name is only known once createMate has run.
 function defaultGlobalConfigPath(): string {
-  return path.join(os.homedir(), `.${frameworkConfig.name}`, "config.yaml");
+  return path.join(os.homedir(), `.${FRAMEWORK_NAME}`, "config.yaml");
 }
 
 export class GlobalConfigStore extends YamlFileStore<GlobalConfig> {