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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniqbit/mate-core",
-  "version": "0.15.1-canary.1",
+  "version": "0.15.1-canary.2",
   "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,
@@ -44,7 +45,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 +57,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 +76,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 +92,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,
@@ -81,8 +82,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/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,6 +1,6 @@
 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";
@@ -8,7 +8,7 @@ import { 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 {

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> {

package/src/lib/orchestrator/repo-local-registry.ts

@@ -3,7 +3,7 @@ import path from "node:path";
 
 import { parse, stringify } from "yaml";
 
-import { frameworkConfig } from "../../framework";
+import { FRAMEWORK_NAME } from "../../framework";
 import { resolveGitInfoExcludePath } from "../../tools/setup/git-utils";
 import { YamlFileStore } from "./yaml-file-store";
 import type { CompanionSource, LinkedRepository } from "./types";
@@ -19,8 +19,7 @@ export interface RepoLocalRegistry {
   companions: RepoLocalCompanionPointer[];
 }
 
-// Lazy: the distribution name is only known once createMate has run.
-const repoLocalDirName = () => `.${frameworkConfig.name}`;
+const repoLocalDirName = () => `.${FRAMEWORK_NAME}`;
 const repoLocalExcludeEntry = () => `${repoLocalDirName()}/`;
 const repoLocalScanSkipDirNames = () =>
   new Set([

package/src/lib/orchestrator/setup-preflight.ts

@@ -3,7 +3,7 @@ import path from "node:path";
 
 import { parse } from "yaml";
 
-import { frameworkConfig } from "../../framework";
+import { FRAMEWORK_NAME, frameworkCommandName, frameworkConfig } from "../../framework";
 import { fileExists } from "../fs-utils";
 import { GlobalConfigStore } from "./global-config-store";
 import { CompanionResolver, type CompanionMatch } from "./companion-resolver";
@@ -127,7 +127,7 @@ export async function looksLikeWorkingRepo(cwd: string): Promise<boolean> {
 export async function hasLocalCompanionConfig(cwd: string): Promise<boolean> {
   const resolvedCwd = path.resolve(cwd);
   const candidatePaths = [
-    path.join(resolvedCwd, `.${frameworkConfig.name}`, "config", "framework.yaml"),
+    path.join(resolvedCwd, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"),
     ...frameworkConfig.legacyNames.map((name) =>
       path.join(resolvedCwd, `.${name}`, "config", "framework.yaml"),
     ),
@@ -145,7 +145,7 @@ export async function hasLocalCompanionConfig(cwd: string): Promise<boolean> {
 async function hasWorkingRepoConfig(cwd: string): Promise<boolean> {
   try {
     const raw = await fs.readFile(
-      path.join(path.resolve(cwd), `.${frameworkConfig.name}`, "config", "framework.yaml"),
+      path.join(path.resolve(cwd), `.${FRAMEWORK_NAME}`, "config", "framework.yaml"),
       "utf8",
     );
     const config = parse(raw) as { type?: unknown } | null;
@@ -190,7 +190,7 @@ export async function inspectSetupPreflight(
 
 export function formatSetupGuardrailError(cwd: string, match: CompanionMatch): string {
   return [
-    `\`${frameworkConfig.name} setup\` cannot run here: ${path.resolve(cwd)} is inside linked working repo \`${match.repositoryId}\`.`,
-    `Run \`${frameworkConfig.name} setup\` from the companion repo instead: ${match.companionPath}`,
+    `\`${frameworkCommandName()} setup\` cannot run here: ${path.resolve(cwd)} is inside linked working repo \`${match.repositoryId}\`.`,
+    `Run \`${frameworkCommandName()} setup\` from the companion repo instead: ${match.companionPath}`,
   ].join("\n");
 }

package/src/lib/orchestrator/working-repo-store.ts

@@ -1,12 +1,12 @@
 import path from "node:path";
 
-import { frameworkConfig } from "../../framework";
+import { FRAMEWORK_NAME, frameworkCommandName } from "../../framework";
 import { migrateRegistryData } from "./migration";
 import { YamlFileStore } from "./yaml-file-store";
 import { ConfigError, type WorkingRepoConfig } from "./types";
 
 export function getDefaultWorkingRepoPath(): string {
-  return `.${frameworkConfig.name}/config/registry.yaml`;
+  return `.${FRAMEWORK_NAME}/config/registry.yaml`;
 }
 
 export class WorkingRepoStore extends YamlFileStore<WorkingRepoConfig> {
@@ -21,7 +21,7 @@ export class WorkingRepoStore extends YamlFileStore<WorkingRepoConfig> {
 
   protected async onMissing(): Promise<WorkingRepoConfig> {
     throw new ConfigError(
-      `Working repo config not found. Please run \`${frameworkConfig.name} companion setup\` to initialize the framework.`,
+      `Working repo config not found. Please run \`${frameworkCommandName()} companion setup\` to initialize the framework.`,
     );
   }
 

package/src/lib/update-checker.ts

@@ -2,7 +2,7 @@ import os from "node:os";
 import path from "node:path";
 
 import { getActiveDistribution, type DistributionUpdateConfig } from "../distribution";
-import { frameworkConfig } from "../framework";
+import { FRAMEWORK_NAME, frameworkCommandName } from "../framework";
 import { fetchPublicPackageVersion, PUBLIC_NPM_REGISTRY } from "./public-npm";
 import { YamlFileStore } from "./orchestrator/yaml-file-store";
 
@@ -22,7 +22,7 @@ export const updateCheckerDeps = {
 
 export class UpdateStateStore extends YamlFileStore<UpdateState> {
   constructor() {
-    super(path.join(os.homedir(), `.${frameworkConfig.name}`, "update-state.yaml"));
+    super(path.join(os.homedir(), `.${FRAMEWORK_NAME}`, "update-state.yaml"));
   }
 
   protected onMissing(): Promise<UpdateState> {
@@ -35,9 +35,9 @@ export function getCurrentVersion(): string {
 }
 
 export function getUpdateConfig(): Required<DistributionUpdateConfig> {
-  const { name, update } = getActiveDistribution().config;
+  const { update } = getActiveDistribution().config;
   return {
-    packageName: update?.packageName ?? `@uniqbit/${name}`,
+    packageName: update?.packageName ?? `@uniqbit/${FRAMEWORK_NAME}`,
     registry: update?.registry ?? PUBLIC_NPM_REGISTRY,
     enforce: update?.enforce ?? false,
   };
@@ -62,9 +62,9 @@ export async function showUpdateBannerIfAvailable(store: UpdateStateStore): Prom
     const current = getCurrentVersion();
     if (!isNewer(state.latestVersion, current)) return;
     process.stderr.write(
-      `\n${frameworkConfig.name}: update available (${current} → ${state.latestVersion})\n`,
+      `\n${frameworkCommandName()}: update available (${current} → ${state.latestVersion})\n`,
     );
-    process.stderr.write(`  Run \`${frameworkConfig.name} update\` to upgrade.\n\n`);
+    process.stderr.write(`  Run \`${frameworkCommandName()} update\` to upgrade.\n\n`);
   } catch {
     // never block the main command
   }
@@ -83,9 +83,9 @@ export async function enforceUpdateIfRequired(store: UpdateStateStore): Promise<
     const current = getCurrentVersion();
     if (!isNewer(state.latestVersion, current)) return false;
     process.stderr.write(
-      `\n${frameworkConfig.name}: update required (${current} → ${state.latestVersion})\n`,
+      `\n${frameworkCommandName()}: update required (${current} → ${state.latestVersion})\n`,
     );
-    process.stderr.write(`  Run \`${frameworkConfig.name} update\` before continuing.\n\n`);
+    process.stderr.write(`  Run \`${frameworkCommandName()} update\` before continuing.\n\n`);
     return true;
   } catch {
     return false;

package/src/playbooks/companion-guidance.ts

@@ -1,6 +1,6 @@
 import path from "node:path";
 
-import { frameworkConfig } from "../framework";
+import { FRAMEWORK_NAME, frameworkCommandName } from "../framework";
 import type { AdapterContext } from "../lib/orchestrator/adapters/base";
 import {
   hasGraphifyCapability,
@@ -35,7 +35,7 @@ export function buildCodebaseExplorationGuidanceSection(
 2. If tokensave is empty/file-only/irrelevant, run graphify query "<question>"; use graphify path/explain to deepen.
 3. Use grep/glob/read only after tokensave and graphify were tried.</order>
 <notes>Dirty graph files are expected. Use wiki/index.md for broad navigation; GRAPH_REPORT.md only if query/path/explain fall short.</notes>
-<post-edit>After code changes, run mate cap index.</post-edit>
+<post-edit>After code changes, run ${frameworkCommandName()} cap index.</post-edit>
 </codebase-exploration-rules>`;
   }
 
@@ -48,7 +48,7 @@ export function buildCodebaseExplorationGuidanceSection(
 2. Use graphify path "<A>" "<B>" or graphify explain "<concept>" to deepen.
 3. Use grep/glob/read only after graphify was tried.</order>
 <notes>Dirty graph files are expected. Use wiki/index.md for broad navigation; GRAPH_REPORT.md only if query/path/explain fall short.</notes>
-<post-edit>After code changes, run mate cap index --graphify.</post-edit>
+<post-edit>After code changes, run ${frameworkCommandName()} cap index --graphify.</post-edit>
 </codebase-exploration-rules>`;
   }
 
@@ -57,7 +57,7 @@ export function buildCodebaseExplorationGuidanceSection(
 <order>tokensave -> grep/glob/read. MUST try tokensave before raw source.
 1. tokensave_context first.
 2. Use grep/glob/read only after tokensave is empty or irrelevant.</order>
-<post-edit>After code changes, run mate cap index --tokensave.</post-edit>
+<post-edit>After code changes, run ${frameworkCommandName()} cap index --tokensave.</post-edit>
 </codebase-exploration-rules>`;
 }
 
@@ -73,13 +73,12 @@ export function buildCompanionPolicyXml(
   context: AdapterContext,
   options: { wrapperBinPath?: string } = {},
 ): string {
-  const name = frameworkConfig.name;
   const wrapperBinPath = options.wrapperBinPath ?? getWrapperBinPath();
   const lines = [
     "## MANDATORY RULES - NON-NEGOTIABLE",
     "",
-    `<companion-policy framework="${name}" priority="mandatory">`,
-    `  <overview>You are operating inside the ${name} companion repository.</overview>`,
+    `<companion-policy framework="${FRAMEWORK_NAME}" priority="mandatory">`,
+    `  <overview>You are operating inside the ${FRAMEWORK_NAME} companion repository.</overview>`,
     "  <context>",
     "    <paths>",
     `      <path role="working-repository" env="MATE_REPO_PATH">${context.repository.path}</path>`,
@@ -89,7 +88,7 @@ export function buildCompanionPolicyXml(
     "    <cli-tools>",
     `      <cli name="openspec" type="wrapper" invokeAs="${path.join(wrapperBinPath, "openspec")}" />`,
     `      <cli name="graphify" type="wrapper" invokeAs="${path.join(wrapperBinPath, "graphify")}" />`,
-    '      <cli name="mate" type="global" invokeAs="mate" />',
+    `      <cli name="${FRAMEWORK_NAME}" type="global" invokeAs="${frameworkCommandName()}" />`,
     "    </cli-tools>",
     `    <linked-repository id="${context.repository.id}" profile="${context.repository.profile}" />`,
     "  </context>",
@@ -104,7 +103,7 @@ export function buildCompanionPolicyXml(
 
   if (hasOpenspecCapability(context.capabilities)) {
     lines.push(
-      '    <rule id="openspec-finish" severity="critical">Finish OpenSpec changes ONLY with: mate artifact finish "<name>" --json — never hand-commit or hand-tag a finish. Finishing a still-active change applies its delta specs itself, so do not pre-apply them to openspec/specs right before finishing. Finishing an already-archived change resumes without re-applying delta specs, so an archive flow that already synced specs (e.g. openspec-sync-specs) composes fine with a finish afterwards.</rule>',
+      `    <rule id="openspec-finish" severity="critical">Finish OpenSpec changes ONLY with: ${frameworkCommandName()} artifact finish "<name>" --json — never hand-commit or hand-tag a finish. Finishing a still-active change applies its delta specs itself, so do not pre-apply them to openspec/specs right before finishing. Finishing an already-archived change resumes without re-applying delta specs, so an archive flow that already synced specs (e.g. openspec-sync-specs) composes fine with a finish afterwards.</rule>`,
     );
   }
 

package/src/runtime/env.ts

@@ -6,6 +6,7 @@
  */
 export const MATE_ENV = {
   frameworkName: "MATE_NAME",
+  commandName: "MATE_COMMAND",
   version: "MATE_VERSION",
   companionPath: "MATE_ARTIFACT_PATH",
   wrapperBinPath: "MATE_WRAPPER_BIN_PATH",

package/src/templates/capabilities/openspec-cap/claude/hooks/mate-artifact-finish.sh

@@ -146,9 +146,10 @@ const change = extractArchiveCommand(command) || extractMoveCommand(command);
 if (!change) process.exit(0);
 if (isClearFailure(input.tool_response)) process.exit(0);
 
+const mateCommand = process.env.MATE_COMMAND || "mate";
 const context =
   "OpenSpec change " + change + " was just archived. Invoke the mate-artifact-finish " +
-  "skill, then run `mate artifact finish \"" + change + "\" --json` to complete the " +
+  "skill, then run `" + mateCommand + " artifact finish \"" + change + "\" --json` to complete the " +
   "finish workflow (commit, tag, and push).";
 process.stdout.write(JSON.stringify({
   hookSpecificOutput: {

package/src/templates/capabilities/openspec-cap/mate-skills/mate-artifact-finish/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: mate-artifact-finish
-description: Finish a completed artifact in one step via `mate artifact finish`. Use when the user wants to finish, ship, or archive-and-push a completed artifact and anchor it with a dated revert tag.
-allowed-tools: Bash(mate:*), Bash(git:*), Bash(openspec:*)
+description: Finish a completed artifact in one step via `{{MATE_COMMAND}} artifact finish`. Use when the user wants to finish, ship, or archive-and-push a completed artifact and anchor it with a dated revert tag.
+allowed-tools: Bash({{MATE_COMMAND}}:*), Bash(git:*), Bash(openspec:*)
 license: MIT
-compatibility: Requires the mate CLI and the openspec capability enabled.
+compatibility: Requires the {{MATE_COMMAND}} CLI and the openspec capability enabled.
 metadata:
   author: mate
   version: "1.2"
@@ -13,7 +13,7 @@ Finish a completed artifact as one deterministic mate workflow and leave a dated
 
 ## Workflow
 
-`mate artifact finish` is the deterministic, non-interactive finish pipeline.
+`{{MATE_COMMAND}} artifact finish` is the deterministic, non-interactive finish pipeline.
 
 The CLI performs normal work; only conflict recovery requires agent judgment.
 
@@ -24,10 +24,10 @@ The CLI performs normal work; only conflict recovery requires agent judgment.
 2. **Run the CLI.**
 
    ```bash
-   mate artifact finish "<artifact-name>" --json
+   {{MATE_COMMAND}} artifact finish "<artifact-name>" --json
    ```
 
-   Run it from the companion repository. Finish mutates only that repository; the linked working repository is capability-indexing context. Do not manually invoke `mate cap index`.
+   Run it from the companion repository. Finish mutates only that repository; the linked working repository is capability-indexing context. Do not manually invoke `{{MATE_COMMAND}} cap index`.
 
    Add `--force` only if the user explicitly wants to override the not-complete guard (validation is never bypassable). Unrelated companion changes are preserved and do not require `--force`. Add `--no-push` for a local-only finish.
 
@@ -44,8 +44,8 @@ The CLI performs normal work; only conflict recovery requires agent judgment.
 
 - **CRITICAL — no manual finishing**: Never hand-commit or hand-tag instead of this skill. For a still-active change the finish pipeline applies delta specs itself (via `openspec archive`) — do not pre-apply them, or produce fails with "already exists". A change whose specs were already synced (e.g. via `openspec-sync-specs`) must be archived first; finish then resumes from the archive without re-applying delta specs.
 - Always pass `--json` and parse the result; do not scrape human-readable output.
-- Never re-run `mate artifact finish` blindly after a `conflict`.
+- Never re-run `{{MATE_COMMAND}} artifact finish` blindly after a `conflict`.
 - Never auto-resolve a provider-specific conflict you do not understand — ask the user.
 - Use the JSON fields the CLI returns; do not recompute names, dates, or tags by hand.
-- Invoke the CLI as `mate`, never through a companion-local wrapper.
+- Invoke the CLI as `{{MATE_COMMAND}}`, never through a companion-local wrapper.
 - Only the companion repository is a finish Git target; the working repository is an index input.

package/src/templates/capabilities/openspec-cap/mate-skills/mate-artifact-finish/references/openspec.md

@@ -13,7 +13,7 @@ Use this reference when you need the OpenSpec-specific parts of `mate-artifact-f
 
 The CLI is **resumable**.
 
-If the change is already archived — because the developer ran `openspec archive` by hand, or because a prior finish partially completed — `mate artifact finish` detects the existing:
+If the change is already archived — because the developer ran `openspec archive` by hand, or because a prior finish partially completed — `{{MATE_COMMAND}} artifact finish` detects the existing:
 
 ```text
 openspec/changes/archive/<date>-<name>/
@@ -21,7 +21,7 @@ openspec/changes/archive/<date>-<name>/
 
 It then skips the archive step and continues from commit → tag → push. In that case the result includes `resumed: true`.
 
-This means a developer can archive manually first and still rely on `mate artifact finish` for the commit/tag/push tail.
+This means a developer can archive manually first and still rely on `{{MATE_COMMAND}} artifact finish` for the commit/tag/push tail.
 
 ## JSON Contract
 
@@ -80,7 +80,7 @@ Failure behavior matters:
 
 ## OpenSpec Conflict Workflow
 
-If `status` is `conflict`, do **not** rerun `mate artifact finish`.
+If `status` is `conflict`, do **not** rerun `{{MATE_COMMAND}} artifact finish`.
 
 At that point:
 

package/src/templates/providers/claude/.claude/hooks/validate-artifact-path

@@ -4,6 +4,10 @@
 Artifact-like files may be written in the working repository only when the
 target path is already ignored by git. That keeps local-only scratch files
 possible without weakening the default repo split.
+
+Editing a file that already exists is always allowed: the guard exists to
+stop new agent artifacts from landing in the working repo, not to freeze
+files that are already part of it.
 """
 
 from __future__ import annotations
@@ -74,6 +78,15 @@ def companion_root() -> str | None:
     return os.path.normpath(companion) if companion else None
 
 
+def claude_config_root() -> str:
+    """Claude Code's own config/state directory (plan files, settings, todos).
+    Writes there are agent-runtime state, never Mate artifacts."""
+    configured = os.environ.get("CLAUDE_CONFIG_DIR")
+    if configured:
+        return os.path.normpath(configured)
+    return os.path.normpath(os.path.join(os.path.expanduser("~"), ".claude"))
+
+
 def normalize_path(file_path: str) -> str:
     if os.path.isabs(file_path):
         return os.path.normpath(file_path)
@@ -161,7 +174,7 @@ def block_write(target: str, companion: str) -> None:
     raise SystemExit(2)
 
 
-def check_file_path(file_path: str, companion: str | None) -> None:
+def check_file_path(file_path: str, companion: str | None, allow_existing: bool = False) -> None:
     if not file_path or not companion:
         return
 
@@ -169,6 +182,12 @@ def check_file_path(file_path: str, companion: str | None) -> None:
     if normalized.startswith(companion):
         return
 
+    if is_under(normalized, claude_config_root()):
+        return
+
+    if allow_existing and os.path.isfile(normalized):
+        return
+
     if is_product_documentation_path(normalized):
         return
 
@@ -203,7 +222,11 @@ def main() -> int:
     tool_input = payload.get("tool_input", {})
 
     if tool_name in {"Write", "Edit", "MultiEdit"}:
-        check_file_path(str(tool_input.get("file_path", "")), companion)
+        check_file_path(
+            str(tool_input.get("file_path", "")),
+            companion,
+            allow_existing=tool_name in {"Edit", "MultiEdit"},
+        )
         return 0
 
     if tool_name == "Bash":

package/src/tools/setup/capabilities/graphify.ts

@@ -10,7 +10,7 @@ import {
   runShellCommand,
 } from "../utils";
 import { confirm } from "../../../cli/confirm";
-import { frameworkConfig } from "../../../framework";
+import { FRAMEWORK_NAME } from "../../../framework";
 import { isInstalledViaUvTool } from "../package-managers/uv";
 
 // Storage contract: <companionPath>/.graphify/<repositoryId>/graphify-out/
@@ -43,9 +43,9 @@ const GRAPHIFY_PROVIDER_DIRS: Record<string, string> = {
 export const GRAPHIFY_COMPANION_OUT_PREFIX =
   "$MATE_ARTIFACT_PATH/.graphify/$MATE_REPO_ID/graphify-out/";
 
-// Lazy: marker names derive from the active distribution's identity.
-const GRAPHIFY_START = () => `<!-- ${frameworkConfig.name.toUpperCase()}:GRAPHIFY:START -->`;
-const GRAPHIFY_END = () => `<!-- ${frameworkConfig.name.toUpperCase()}:GRAPHIFY:END -->`;
+// Marker names derive from the framework identity, never the invocation name.
+const GRAPHIFY_START = () => `<!-- ${FRAMEWORK_NAME.toUpperCase()}:GRAPHIFY:START -->`;
+const GRAPHIFY_END = () => `<!-- ${FRAMEWORK_NAME.toUpperCase()}:GRAPHIFY:END -->`;
 
 // Per-provider root agent instruction files used for graphify cleanup on teardown.
 const GRAPHIFY_AGENT_FILES: Record<string, string> = {

package/src/tools/setup/capabilities/openspec.ts

@@ -3,6 +3,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { promisify } from "node:util";
 
+import { frameworkCommandName } from "../../../framework";
 import { getOpenSpecSchemaSelection } from "../../../lib/orchestrator/setup-compatibilities";
 import { fetchPublicPackageVersion } from "../../../lib/public-npm";
 import { isNewer } from "../../../lib/update-checker";
@@ -134,6 +135,33 @@ async function teardownToolRuntime(companionPath: string, tool: OpenSpecTool): P
   await teardownOpenspecSkills(getSkillsDir(companionPath, tool), companionPath);
 }
 
+const MATE_COMMAND_PLACEHOLDER = "{{MATE_COMMAND}}";
+
+// Like mergeDir, but renders the invocation-name placeholder at deploy time.
+// Files without the placeholder are copied byte-identical.
+export async function deployMateSkillDir(src: string, dest: string): Promise<void> {
+  await fs.mkdir(dest, { recursive: true });
+  const entries = await fs.readdir(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      await deployMateSkillDir(srcPath, destPath);
+      continue;
+    }
+    const content = await fs.readFile(srcPath, "utf8");
+    if (content.includes(MATE_COMMAND_PLACEHOLDER)) {
+      await fs.writeFile(
+        destPath,
+        content.replaceAll(MATE_COMMAND_PLACEHOLDER, frameworkCommandName()),
+        "utf8",
+      );
+    } else {
+      await fs.copyFile(srcPath, destPath);
+    }
+  }
+}
+
 async function applyMateOpenspecSkills(
   companionPath: string,
   tools: OpenSpecTool[],
@@ -141,7 +169,7 @@ async function applyMateOpenspecSkills(
   for (const tool of tools) {
     const skillsDir = getSkillsDir(companionPath, tool);
     for (const skill of MATE_ARTIFACT_SKILLS) {
-      await mergeDir(path.join(MATE_SKILLS_SOURCE, skill), path.join(skillsDir, skill));
+      await deployMateSkillDir(path.join(MATE_SKILLS_SOURCE, skill), path.join(skillsDir, skill));
     }
   }
 }

package/src/tools/setup/engine.ts

@@ -1,4 +1,5 @@
 import { getActiveDistribution } from "../../distribution";
+import { FRAMEWORK_NAME } from "../../framework";
 import type { FrameworkConfig } from "../../lib/orchestrator/types";
 import { collectHostingProviders, ContextServiceMediator } from "./context-services";
 import type { CapabilityPlugin, Plugin, PluginRegistration, SetupContext } from "./plugin";
@@ -106,7 +107,7 @@ export async function executeSetupInstallationPlan(
   const distribution = getActiveDistribution();
   const mediator = new ContextServiceMediator({
     ctx,
-    frameworkName: distribution.config.name,
+    frameworkName: FRAMEWORK_NAME,
     hostingProviders: collectHostingProviders(plugins, plan.activeProviders),
     assetOverrideRoots: distribution.config.assetRoots,
     warn: (message) => {

package/src/tools/setup/plugins/guidance.ts

@@ -1,11 +1,11 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
-import { frameworkConfig } from "../../../framework";
+import { FRAMEWORK_NAME, frameworkConfig } from "../../../framework";
 import { removeGraphifySection } from "../capabilities/graphify";
 
-// Lazy: marker names derive from the active distribution's identity.
-const upperName = () => frameworkConfig.name.toUpperCase();
+// Marker names derive from the framework identity, never the invocation name.
+const upperName = () => FRAMEWORK_NAME.toUpperCase();
 
 function allMateStarts(): string[] {
   return [

package/src/tools/setup/providers/claude.ts

@@ -2,6 +2,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
+import { frameworkCommandName } from "../../../framework";
 import { GlobalConfigStore } from "../../../lib/orchestrator/global-config-store";
 import { getWrapperBinPath } from "../../../lib/package-paths";
 import type { FrameworkConfig } from "../../../lib/orchestrator/types";
@@ -51,10 +52,16 @@ const MANAGED_HOOK_MARKERS = [
 ];
 
 // Base `permissions.allow` entries that Claude gets for Mate-managed workflows.
-// Read/Glob are scoped to the companion path so routine reads of skills,
-// specs, and change artifacts don't prompt for approval on every file.
+// Read/Edit are scoped to the companion path so routine reads and artifact
+// writes of skills, specs, and change artifacts don't prompt for approval on
+// every file. Claude Code ignores `Glob()` rules for file-permission checks
+// (only Read/Edit rules gate file tools), so no Glob entry is emitted.
 function getBaseManagedPermissionEntries(companionPath: string): string[] {
-  return ["Bash(mate:*)", `Read(${companionPath}/**)`, `Glob(${companionPath}/**)`];
+  return [
+    `Bash(${frameworkCommandName()}:*)`,
+    `Read(${companionPath}/**)`,
+    `Edit(${companionPath}/**)`,
+  ];
 }
 
 const LEGACY_MANAGED_PERMISSION_ENTRIES = [
@@ -73,14 +80,14 @@ function getCapabilityPermissionEntries(): Record<string, string[]> {
       "Skill(openspec-archive-change)",
       "Skill(mate-artifact-finish)",
       "Bash(openspec:*)",
-      "Bash(mate cap graphify:*)",
+      `Bash(${frameworkCommandName()} cap graphify:*)`,
       `Bash(${path.join(wrapperBinPath, "openspec")}:*)`,
     ],
     rtk: ["Bash(rtk:*)"],
     graphify: [
       "Skill(graphify)",
       "Bash(graphify:*)",
-      "Bash(mate cap graphify:*)",
+      `Bash(${frameworkCommandName()} cap graphify:*)`,
       `Bash(${path.join(wrapperBinPath, "graphify")}:*)`,
     ],
     "react-doctor": [
@@ -89,6 +96,12 @@ function getCapabilityPermissionEntries(): Record<string, string[]> {
       "Bash(npx react-doctor@latest *)",
     ],
     tokensave: ["mcp__tokensave__*"],
+    // The context-mode Claude plugin exposes its skill and MCP tools under the
+    // plugin namespace; pre-seed both so routine routing doesn't prompt.
+    "context-mode": [
+      "Skill(context-mode:context-mode)",
+      "mcp__plugin_context-mode_context-mode__*",
+    ],
   };
 }
 
@@ -97,6 +110,10 @@ function getAllManagedPermissionEntries(companionPath: string): Set<string> {
     ...getBaseManagedPermissionEntries(companionPath),
     ...Object.values(getCapabilityPermissionEntries()).flat(),
     ...LEGACY_MANAGED_PERMISSION_ENTRIES,
+    // Legacy base entry: Claude Code never matched Glob() rules for file
+    // permission checks and warns about them, so setup no longer emits it.
+    // Keep it managed so re-running setup strips it from existing installs.
+    `Glob(${companionPath}/**)`,
   ]);
 }
 

package/src/tools/setup/providers/opencode.ts

@@ -2,6 +2,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
+import { frameworkCommandName } from "../../../framework";
 import {
   OPENCODE_PLUGIN_PACKAGE_NAME,
   getOpenCodePluginPackageReference,
@@ -243,9 +244,9 @@ async function warmPluginCacheForSetup(pluginReference: string): Promise<void> {
 
   process.stderr.write(
     [
-      `mate: could not pre-fetch ${pluginReference} into OpenCode's plugin environment.`,
+      `${frameworkCommandName()}: could not pre-fetch ${pluginReference} into OpenCode's plugin environment.`,
       "The first managed OpenCode launch will download it, which requires registry access.",
-      "Re-run `mate companion setup` with network access to warm the cache ahead of time.",
+      `Re-run \`${frameworkCommandName()} companion setup\` with network access to warm the cache ahead of time.`,
       ...(warmed.detail ? [`Details: ${warmed.detail}`] : []),
     ].join("\n") + "\n",
   );

package/src/tools/setup.ts

@@ -2,7 +2,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
-import { frameworkConfig } from "../framework";
+import { FRAMEWORK_NAME, frameworkCommandName } from "../framework";
 import { ConfigStore, mergeWithDefaults } from "../lib/orchestrator/config-store";
 import { GlobalConfigStore } from "../lib/orchestrator/global-config-store";
 import {
@@ -72,11 +72,7 @@ export async function updateProjectGitignore(
   const ctx: SetupContext = { companionPath, config, mode: "sync", activeProviders: [] };
   const plugins = getActiveDistribution().registry.getAll();
   const entries = collectManagedGitignoreEntries(ctx, plugins);
-  await writeManagedGitignoreBlock(
-    path.join(companionPath, ".gitignore"),
-    frameworkConfig.name,
-    entries,
-  );
+  await writeManagedGitignoreBlock(path.join(companionPath, ".gitignore"), FRAMEWORK_NAME, entries);
 }
 
 export async function syncCompanionFiles(
@@ -93,14 +89,17 @@ export async function syncCompanionFiles(
   );
 }
 
-function mateFolderReadme(): string {
-  const n = frameworkConfig.name;
+// Exported for the distribution-identity tests.
+export function mateFolderReadme(): string {
+  const n = frameworkCommandName();
+  const packageName =
+    getActiveDistribution().config.update?.packageName ?? `@uniqbit/${FRAMEWORK_NAME}`;
   return [
-    `# .${n}`,
+    `# .${FRAMEWORK_NAME}`,
     ``,
-    `This directory is managed by the **${n}** companion framework (\`@uniqbit/${n}\`).`,
+    `This directory is managed by the **${FRAMEWORK_NAME}** companion framework (\`${packageName}\`).`,
     ``,
-    `The ${n} framework keeps your AI agent's companion artifacts separate from the code it works on.`,
+    `The ${FRAMEWORK_NAME} framework keeps your AI agent's companion artifacts separate from the code it works on.`,
     `Specs, notes, and agent config live here; code stays in the linked working repository.`,
     ``,
     `## Common commands`,
@@ -118,7 +117,7 @@ function mateFolderReadme(): string {
     ``,
     `## Configuration`,
     ``,
-    `Edit \`.${n}/config/framework.yaml\` to configure:`,
+    `Edit \`.${FRAMEWORK_NAME}/config/framework.yaml\` to configure:`,
     ``,
     `- **profiles** — per-profile allowed agents list`,
     `- **capabilities** — skill and CLI tool capabilities (e.g. react-doctor, openspec, tokensave, headroom, rtk)`,
@@ -128,7 +127,7 @@ function mateFolderReadme(): string {
 }
 
 async function writeMateReadme(companionPath: string): Promise<void> {
-  const readmePath = path.join(companionPath, `.${frameworkConfig.name}`, "README.md");
+  const readmePath = path.join(companionPath, `.${FRAMEWORK_NAME}`, "README.md");
   await fs.mkdir(path.dirname(readmePath), { recursive: true });
   await fs.writeFile(readmePath, mateFolderReadme(), "utf8");
 }
@@ -158,7 +157,7 @@ export async function executeSetup(
 
   const configStore =
     deps.configStore ??
-    new ConfigStore(path.join(cwd, `.${frameworkConfig.name}`, "config", "framework.yaml"));
+    new ConfigStore(path.join(cwd, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"));
   const config = mergeWithDefaults(await configStore.load());
   const defaultProfile = config.profiles.default;