@uniqbit/mate-core 0.15.3 → 0.15.4-canary.10

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

@@ -3,15 +3,20 @@ import fs from "node:fs/promises";
 import path from "node:path";
 
 import type { PluginDeclaration } from "../../../lib/orchestrator/types";
-import { pluginInstallDir, pluginPackageRoot } from "./paths";
-import { PluginPinStore, type PluginPin } from "./pin-store";
+import { dynamicPluginsWorkspaceRoot, pluginPackageRoot } from "./paths";
 
-export type BunInstallRunner = (
-  installDir: string,
+export type NpmInstallRunner = (
+  workspaceRoot: string,
+) => Promise<{ ok: boolean; detail?: string }> | { ok: boolean; detail?: string };
+
+export type NpmUpdateRunner = (
+  workspaceRoot: string,
+  packages: string[],
 ) => Promise<{ ok: boolean; detail?: string }> | { ok: boolean; detail?: string };
 
 export interface PluginInstallDeps {
-  runBunInstall?: BunInstallRunner;
+  runNpmInstall?: NpmInstallRunner;
+  runNpmUpdate?: NpmUpdateRunner;
 }
 
 export interface PluginInstallResult {
@@ -21,16 +26,38 @@ export interface PluginInstallResult {
   error?: string;
 }
 
-/** Runs `bun install` in the plugin workspace, honoring the user's ambient registry/auth config. */
-function defaultBunInstall(installDir: string): { ok: boolean; detail?: string } {
-  const result = spawnSync("bun", ["install", "--silent"], { cwd: installDir, encoding: "utf8" });
+/** Runs `npm install` for the shared plugin workspace, honoring the user's ambient registry/auth config. */
+function defaultNpmInstall(workspaceRoot: string): { ok: boolean; detail?: string } {
+  const result = spawnSync("npm", ["install", "--no-audit", "--no-fund", "--silent"], {
+    cwd: workspaceRoot,
+    encoding: "utf8",
+  });
   if (result.error || result.status !== 0) {
     return {
       ok: false,
       detail:
         result.error?.message ??
         result.stderr?.trim() ??
-        `bun install exited with ${result.status}`,
+        `npm install exited with ${result.status}`,
+    };
+  }
+  return { ok: true };
+}
+
+/** Runs `npm update <pkg...>` to force re-resolution of `latest`-declared plugins every run. */
+function defaultNpmUpdate(
+  workspaceRoot: string,
+  packages: string[],
+): { ok: boolean; detail?: string } {
+  const result = spawnSync("npm", ["update", "--no-audit", "--no-fund", "--silent", ...packages], {
+    cwd: workspaceRoot,
+    encoding: "utf8",
+  });
+  if (result.error || result.status !== 0) {
+    return {
+      ok: false,
+      detail:
+        result.error?.message ?? result.stderr?.trim() ?? `npm update exited with ${result.status}`,
     };
   }
   return { ok: true };
@@ -47,125 +74,113 @@ async function readInstalledVersion(packageRoot: string): Promise<string | null>
   }
 }
 
-/**
- * Best-effort integrity extraction from bun's text lockfile. The lockfile is
- * JSONC (trailing commas); package entries are tuples whose last string is
- * the registry integrity hash. Absence is tolerated per spec.
- */
-async function readIntegrityFromBunLock(
-  installDir: string,
-  packageName: string,
-): Promise<string | undefined> {
+async function readWorkspaceDependencies(workspaceRoot: string): Promise<Record<string, string>> {
   try {
-    const raw = await fs.readFile(path.join(installDir, "bun.lock"), "utf8");
-    const parsed = JSON.parse(raw.replace(/,(\s*[}\]])/g, "$1")) as {
-      packages?: Record<string, unknown>;
-    };
-    const entry = parsed.packages?.[packageName];
-    if (!Array.isArray(entry)) return undefined;
-    return entry.find(
-      (element): element is string => typeof element === "string" && element.startsWith("sha"),
-    );
+    const manifest = JSON.parse(
+      await fs.readFile(path.join(workspaceRoot, "package.json"), "utf8"),
+    ) as { dependencies?: Record<string, string> };
+    return manifest.dependencies ?? {};
   } catch {
-    return undefined;
+    return {};
   }
 }
 
+async function writeWorkspaceManifest(
+  workspaceRoot: string,
+  dependencies: Record<string, string>,
+): Promise<void> {
+  await fs.mkdir(workspaceRoot, { recursive: true });
+  await fs.writeFile(
+    path.join(workspaceRoot, "package.json"),
+    JSON.stringify({ private: true, dependencies }, null, 2) + "\n",
+    "utf8",
+  );
+}
+
 /**
- * Installs each declared plugin into `.mate/dependencies/plugins/<sanitized>/`
- * and records `{ package, declaredVersion, resolvedVersion, integrity }` in
- * the committed pin file. Exact/range versions resolve once and stay pinned
- * until the declaration changes; `latest` re-resolves on every run. Matching
- * pinned installs are left untouched.
+ * Installs every declared plugin into one shared workspace at
+ * `.mate/plugins/`. Builds a single `dependencies` map (package
+ * → declared version, sorted by name) and diffs it against the workspace's
+ * current `package.json` plus each package's actual installed presence; an
+ * identical, fully-installed map with no `latest` declaration skips the
+ * install entirely. Otherwise the map is written and `npm install` runs once
+ * for the whole workspace. `latest`-declared plugins additionally get an
+ * `npm update` every run, regardless of whether the map changed, so they
+ * re-resolve on every run. The shared, committed `package-lock.json` is the
+ * sole reproducibility record; nothing else pins versions. Private
+ * registries are never Mate's concern: installs run through the operator's
+ * own ambient npm config, or a project-local, gitignored `.npmrc` dropped
+ * next to the workspace's `package.json`.
  */
 export async function installDeclaredPlugins(
   companionPath: string,
   declarations: PluginDeclaration[],
   deps: PluginInstallDeps = {},
 ): Promise<PluginInstallResult[]> {
-  const runBunInstall = deps.runBunInstall ?? defaultBunInstall;
-  const pinStore = new PluginPinStore(companionPath);
-  const previousPins = (await pinStore.load()).plugins;
-  const nextPins: PluginPin[] = [];
-  const results: PluginInstallResult[] = [];
-
-  for (const declaration of declarations) {
-    const pin = previousPins.find((candidate) => candidate.package === declaration.package);
-    const installDir = pluginInstallDir(companionPath, declaration.package);
-    const packageRoot = pluginPackageRoot(companionPath, declaration.package);
-    // oxlint-disable-next-line no-await-in-loop -- installs mutate a shared pin file sequentially
-    const installedVersion = await readInstalledVersion(packageRoot);
-
-    const pinMatches =
-      declaration.version !== "latest" &&
-      pin !== undefined &&
-      pin.declaredVersion === declaration.version &&
-      installedVersion === pin.resolvedVersion;
-    if (pinMatches) {
-      nextPins.push(pin);
-      results.push({
-        package: declaration.package,
-        status: "unchanged",
-        resolvedVersion: pin.resolvedVersion,
-      });
-      continue;
-    }
+  const runNpmInstall = deps.runNpmInstall ?? defaultNpmInstall;
+  const runNpmUpdate = deps.runNpmUpdate ?? defaultNpmUpdate;
+  const workspaceRoot = dynamicPluginsWorkspaceRoot(companionPath);
 
-    // oxlint-disable-next-line no-await-in-loop
-    const result = await installOne(installDir, packageRoot, declaration, runBunInstall);
-    results.push(result);
-    if (result.status === "installed" && result.resolvedVersion) {
-      nextPins.push({
-        package: declaration.package,
-        declaredVersion: declaration.version,
-        resolvedVersion: result.resolvedVersion,
-        // oxlint-disable-next-line no-await-in-loop
-        integrity: await readIntegrityFromBunLock(installDir, declaration.package),
-      });
-    }
+  const sorted = declarations.toSorted((a, b) => a.package.localeCompare(b.package));
+  const desired: Record<string, string> = {};
+  for (const declaration of sorted) desired[declaration.package] = declaration.version;
+
+  const [current, installedBefore] = await Promise.all([
+    readWorkspaceDependencies(workspaceRoot),
+    Promise.all(
+      sorted.map((declaration) =>
+        readInstalledVersion(pluginPackageRoot(companionPath, declaration.package)),
+      ),
+    ),
+  ]);
+
+  const latestPackages = sorted
+    .filter((declaration) => declaration.version === "latest")
+    .map((declaration) => declaration.package);
+  const manifestMatches = JSON.stringify(desired) === JSON.stringify(current);
+  const allInstalled = installedBefore.every((version) => version !== null);
+  const unchanged = latestPackages.length === 0 && manifestMatches && allInstalled;
+
+  if (unchanged) {
+    return sorted.map((declaration, index) => ({
+      package: declaration.package,
+      status: "unchanged",
+      resolvedVersion: installedBefore[index] ?? undefined,
+    }));
   }
 
-  // Pins mirror the declaration list; undeclared packages drop out.
-  if (JSON.stringify(nextPins) !== JSON.stringify(previousPins)) {
-    await pinStore.save({ plugins: nextPins });
+  await writeWorkspaceManifest(workspaceRoot, desired);
+  const installOutcome = await runNpmInstall(workspaceRoot);
+  const installFailure = installOutcome.ok
+    ? undefined
+    : (installOutcome.detail ?? "npm install failed");
+
+  let updateFailure: string | undefined;
+  if (latestPackages.length > 0) {
+    const updateOutcome = await runNpmUpdate(workspaceRoot, latestPackages);
+    updateFailure = updateOutcome.ok ? undefined : (updateOutcome.detail ?? "npm update failed");
   }
-  return results;
-}
 
-async function installOne(
-  installDir: string,
-  packageRoot: string,
-  declaration: PluginDeclaration,
-  runBunInstall: BunInstallRunner,
-): Promise<PluginInstallResult> {
-  try {
-    // Fresh workspace per (re)install so `latest` and edited declarations
-    // actually re-resolve instead of reusing a stale lockfile.
-    await fs.rm(installDir, { recursive: true, force: true });
-    await fs.mkdir(installDir, { recursive: true });
-    await fs.writeFile(
-      path.join(installDir, "package.json"),
-      JSON.stringify(
-        { private: true, dependencies: { [declaration.package]: declaration.version } },
-        null,
-        2,
-      ) + "\n",
-      "utf8",
-    );
-    const outcome = await runBunInstall(installDir);
-    if (!outcome.ok) {
-      throw new Error(outcome.detail ?? "bun install failed");
+  const resolvedVersions = await Promise.all(
+    sorted.map((declaration) =>
+      readInstalledVersion(pluginPackageRoot(companionPath, declaration.package)),
+    ),
+  );
+
+  return sorted.map((declaration, index) => {
+    const isLatest = declaration.version === "latest";
+    const failure = installFailure ?? (isLatest ? updateFailure : undefined);
+    if (failure) {
+      return { package: declaration.package, status: "failed", error: failure };
     }
-    const resolvedVersion = await readInstalledVersion(packageRoot);
+    const resolvedVersion = resolvedVersions[index];
     if (!resolvedVersion) {
-      throw new Error(`installed tree is missing ${declaration.package}/package.json`);
+      return {
+        package: declaration.package,
+        status: "failed",
+        error: `installed tree is missing ${declaration.package}/package.json`,
+      };
     }
     return { package: declaration.package, status: "installed", resolvedVersion };
-  } catch (error) {
-    return {
-      package: declaration.package,
-      status: "failed",
-      error: error instanceof Error ? error.message : String(error),
-    };
-  }
+  });
 }

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

@@ -1,8 +1,9 @@
 import fs from "node:fs/promises";
+import { createRequire } from "node:module";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 
-import { FRAMEWORK_NAME, frameworkCommandName } from "../../../framework";
+import { FRAMEWORK_NAME } from "../../../framework";
 import type { PluginDeclaration } from "../../../lib/orchestrator/types";
 import type { Plugin } from "../plugin";
 import { resolveEffectivePluginConfig } from "./config-resolution";
@@ -12,14 +13,9 @@ import {
   type CreatePlugin,
   type PluginHost,
 } from "./host";
-import { pluginPackageRoot } from "./paths";
-import type { PluginPin } from "./pin-store";
+import { dynamicPluginsWorkspaceRoot, pluginPackageRoot } from "./paths";
 
 interface PluginManifest {
-  version?: string;
-  main?: string;
-  module?: string;
-  exports?: unknown;
   mate?: { pluginApiVersion?: unknown };
 }
 
@@ -35,38 +31,17 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-function commandName(): string {
-  try {
-    return frameworkCommandName();
-  } catch {
-    return FRAMEWORK_NAME;
-  }
-}
-
-function resolveEntryFromExports(exportsField: unknown): string | undefined {
-  if (typeof exportsField === "string") return exportsField;
-  if (!isRecord(exportsField)) return undefined;
-  const dot = "." in exportsField ? exportsField["."] : exportsField;
-  if (typeof dot === "string") return dot;
-  if (!isRecord(dot)) return undefined;
-  for (const condition of ["bun", "import", "default", "require"]) {
-    const candidate = dot[condition];
-    if (typeof candidate === "string") return candidate;
-    if (isRecord(candidate) && typeof candidate.default === "string") return candidate.default;
-  }
-  return undefined;
-}
-
 /**
- * Loads one declared plugin from its installed tree: pin verification, API
- * version gate before import, dynamic import, factory resolution, effective
- * config, factory invocation. Every failure class returns a single warning
- * instead of throwing, so one broken plugin never takes down the CLI.
+ * Loads one declared plugin from the shared workspace: installed-presence
+ * check, API version gate before import, entry-point resolution via the
+ * shared workspace's own module resolver, dynamic import, factory
+ * resolution, effective config, factory invocation. Every failure class
+ * returns a single warning instead of throwing, so one broken plugin never
+ * takes down the CLI.
  */
 export async function loadDynamicPlugin(
   companionPath: string,
   declaration: PluginDeclaration,
-  pins: PluginPin[],
   deps: DynamicPluginLoadDeps = {},
 ): Promise<DynamicPluginLoadResult> {
   const name = declaration.package;
@@ -80,27 +55,7 @@ export async function loadDynamicPlugin(
   } catch {
     return {
       ok: false,
-      warning: `plugin "${name}" is not installed; run \`${commandName()} install\`.`,
-    };
-  }
-
-  const pin = pins.find((candidate) => candidate.package === name);
-  if (!pin) {
-    return {
-      ok: false,
-      warning: `plugin "${name}" has no recorded pin; run \`${commandName()} install\`.`,
-    };
-  }
-  if (pin.declaredVersion !== declaration.version) {
-    return {
-      ok: false,
-      warning: `plugin "${name}" declares version "${declaration.version}" but was pinned from "${pin.declaredVersion}"; run \`${commandName()} install\`.`,
-    };
-  }
-  if (manifest.version !== pin.resolvedVersion) {
-    return {
-      ok: false,
-      warning: `plugin "${name}" has version ${manifest.version ?? "unknown"} installed but ${pin.resolvedVersion} pinned; run \`${commandName()} install\`.`,
+      warning: `plugin "${name}" is not installed; run \`${FRAMEWORK_NAME} install\`.`,
     };
   }
 
@@ -121,9 +76,19 @@ export async function loadDynamicPlugin(
     };
   }
 
-  const entryRelative =
-    resolveEntryFromExports(manifest.exports) ?? manifest.module ?? manifest.main ?? "index.js";
-  const entryPath = path.resolve(packageRoot, entryRelative);
+  let entryPath: string;
+  try {
+    const workspaceRequire = createRequire(
+      pathToFileURL(path.join(dynamicPluginsWorkspaceRoot(companionPath), "package.json")),
+    );
+    entryPath = workspaceRequire.resolve(name);
+  } catch (error) {
+    return {
+      ok: false,
+      warning: `plugin "${name}" could not be resolved: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+
   const importModule =
     deps.importModule ??
     ((specifier: string) => import(specifier) as Promise<Record<string, unknown>>);

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

@@ -2,34 +2,20 @@ import path from "node:path";
 
 import { FRAMEWORK_NAME } from "../../../framework";
 
-/** Flattens an npm package name into a single directory segment. */
-export function sanitizePluginDirName(packageName: string): string {
-  return packageName.replace(/^@/, "").replace(/\//g, "-");
+/** Shared workspace root: one package.json + node_modules for every declared plugin. */
+export function dynamicPluginsWorkspaceRoot(companionPath: string): string {
+  return path.join(companionPath, `.${FRAMEWORK_NAME}`, "plugins");
 }
 
-export function dynamicPluginsRoot(companionPath: string): string {
-  return path.join(companionPath, `.${FRAMEWORK_NAME}`, "dependencies", "plugins");
-}
-
-/** Per-plugin install workspace holding a private package.json and node_modules. */
-export function pluginInstallDir(companionPath: string, packageName: string): string {
-  return path.join(dynamicPluginsRoot(companionPath), sanitizePluginDirName(packageName));
-}
-
-/** Root of the installed plugin package itself. */
+/** Root of one installed plugin package inside the shared workspace's node_modules. */
 export function pluginPackageRoot(companionPath: string, packageName: string): string {
   return path.join(
-    pluginInstallDir(companionPath, packageName),
+    dynamicPluginsWorkspaceRoot(companionPath),
     "node_modules",
     ...packageName.split("/"),
   );
 }
 
-/** Committed pin file recording resolved plugin versions. */
-export function pluginPinFilePath(companionPath: string): string {
-  return path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "plugins.lock.yaml");
-}
-
 /** Gitignored per-machine override file deep-merged over committed plugin config. */
 export function pluginLocalOverridesPath(companionPath: string): string {
   return path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "plugins.local.yaml");
@@ -37,3 +23,6 @@ export function pluginLocalOverridesPath(companionPath: string): string {
 
 /** Companion-relative gitignore entry for the local override file. */
 export const PLUGIN_LOCAL_OVERRIDES_GITIGNORE_ENTRY = `.${FRAMEWORK_NAME}/config/plugins.local.yaml`;
+
+/** Companion-relative gitignore entry for the shared workspace's local, never-committed registry credentials. */
+export const PLUGIN_WORKSPACE_NPMRC_GITIGNORE_ENTRY = `.${FRAMEWORK_NAME}/plugins/.npmrc`;

package/src/tools/setup/dynamic-plugins/registry-hint.ts

@@ -0,0 +1,14 @@
+/**
+ * A generic, actionable hint printed on install failure — never guesses at
+ * the actual registry URL/host. Private registries stay a plain, standard
+ * npm operation: a one-time `npm config set --global`, or (since the shared
+ * plugin workspace is a real npm project) a project-local, gitignored
+ * `.npmrc` dropped directly in it — either is picked up by `npm install`
+ * with nothing Mate-injected.
+ */
+export function registryConfigHint(packageName: string): string {
+  const scope = packageName.startsWith("@") ? packageName.split("/")[0] : undefined;
+  return scope
+    ? `If "${scope}" lives in a private registry, configure it once with:\n  npm config set "${scope}:registry" "<registry-url>" --global\n  npm config set "//<registry-host>/:_authToken" "<token>" --global`
+    : `If this package lives in a private registry, configure it once via \`npm config set\` (see the npm docs for scoped registries).`;
+}

package/src/tools/setup/engine.ts

@@ -2,7 +2,15 @@ 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";
+import type {
+  CapabilityContributionInput,
+  CapabilityPlugin,
+  Plugin,
+  PluginRegistration,
+  SetupContext,
+} from "./plugin";
+import { reconcileClaudeContributions } from "./providers/claude";
+import { reconcileOpenCodeContributions } from "./providers/opencode";
 import { normalizeRegistration, type NormalizedRegistration } from "./registry";
 
 export interface SetupInstallationPlanAction {
@@ -151,5 +159,61 @@ export async function executeSetupInstallationPlan(
 
   await mediator.finalize();
 
+  await reconcileCapabilityContributions(ctx, plugins, plan);
+
   return { executedActions, skippedActions, warnings };
 }
+
+// The Runtime Surface of each active Agent Runtime, by runtime id.
+const RUNTIME_SURFACE_RECONCILERS: Record<
+  string,
+  (ctx: SetupContext, inputs: CapabilityContributionInput[]) => Promise<void>
+> = {
+  claude: reconcileClaudeContributions,
+  opencode: reconcileOpenCodeContributions,
+};
+
+/**
+ * Reconcile declared Capability contributions through every active runtime's
+ * Runtime Surface (spec: plugin-engine). Runs after all plugin phases, so
+ * providers are always done first. Disabled capabilities participate with
+ * `enabled: false` and drive teardown of their managed entries.
+ */
+async function reconcileCapabilityContributions(
+  ctx: SetupContext,
+  plugins: Plugin[],
+  plan: SetupInstallationPlan,
+): Promise<void> {
+  // The plan already resolved enablement (policy, saved selection, package
+  // manager requirements); mirror it instead of recomputing.
+  const enabledByPluginId = new Map(
+    plan.actions
+      .filter((action) => action.phase === "capability" && action.providerId === undefined)
+      .map((action) => [action.pluginId, action.action === "apply"]),
+  );
+
+  const inputsByRuntime = new Map<string, CapabilityContributionInput[]>();
+  for (const plugin of plugins) {
+    if (plugin.kind !== "capability") continue;
+    const capability = plugin as CapabilityPlugin;
+    if (!capability.getRuntimeContributions) continue;
+    const enabled = enabledByPluginId.get(capability.id) ?? false;
+    const byRuntime = capability.getRuntimeContributions(ctx);
+    for (const [runtimeId, contributions] of Object.entries(byRuntime)) {
+      if (!contributions) continue;
+      // Inactive runtimes still reconcile — with everything disabled — so a
+      // deselected runtime's managed entries (skill trees, guidance blocks)
+      // are torn down. The surfaces never create files for disabled inputs.
+      const runtimeActive = plan.activeProviders.includes(runtimeId);
+      const inputs = inputsByRuntime.get(runtimeId) ?? [];
+      inputs.push({ pluginId: capability.id, enabled: enabled && runtimeActive, contributions });
+      inputsByRuntime.set(runtimeId, inputs);
+    }
+  }
+
+  for (const [runtimeId, inputs] of inputsByRuntime) {
+    const reconcile = RUNTIME_SURFACE_RECONCILERS[runtimeId];
+    if (!reconcile || inputs.length === 0) continue;
+    await reconcile(ctx, inputs);
+  }
+}

package/src/tools/setup/mate.ts

@@ -1,13 +1,11 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
-import { frameworkCommandName } from "../../framework";
 import { pruneEmptyAncestors } from "./utils";
 
 export const MATE_ARTIFACT_SKILLS = ["mate-artifact-finish"] as const;
 export const MATE_SKILLS = ["mate-artifact-finish", "mate-create-report"] as const;
 
-const MATE_COMMAND_PLACEHOLDER = "{{MATE_COMMAND}}";
 const MATE_SKILLS_SOURCE = path.join(
   import.meta.dirname,
   "../../templates/capabilities/openspec-cap/mate-skills",
@@ -16,9 +14,9 @@ const MATE_SKILLS_SOURCE = path.join(
 const MATE_CREATE_REPORT_SKILL = `---
 name: mate-create-report
 description: Create a browser-first Mate report from an explicit structured ReportDocument. Use when a skill needs to present supplied metrics, tables, statuses, metadata, or narrative text.
-allowed-tools: Bash({{MATE_COMMAND}}:*)
+allowed-tools: Bash(mate:*)
 license: MIT
-compatibility: Requires the {{MATE_COMMAND}} CLI and the OpenSpec capability enabled.
+compatibility: Requires the mate CLI and the OpenSpec capability enabled.
 metadata:
   author: mate
   version: "1.0"
@@ -57,22 +55,14 @@ Supported section types are \`metadata\`, \`metrics\`, \`key-value\`, \`table\`,
 ## Invocation
 
 1. Serialize the complete document to a temporary file or pipe it to stdin.
-2. Run \`{{MATE_COMMAND}} report --input <file-or->\`.
+2. Run \`mate report --input <file-or->\`.
 3. Add \`--json\` when the caller needs normalized JSON instead of browser delivery.
 
 The default path writes self-contained HTML to a unique OS temporary directory and opens it in the default browser. The report includes a visible "Print / Save as PDF" control that calls the browser's native print dialog. If HTML delivery fails, the CLI warns on stderr and emits the complete report document as JSON on stdout.
 
-The built-in \`{{MATE_COMMAND}} report\` path collects Mate usage data and adapts it to the same contract and renderer.
+The built-in \`mate report\` path collects Mate usage data and adapts it to the same contract and renderer.
 `;
 
-function currentMateCommand(): string {
-  try {
-    return frameworkCommandName();
-  } catch {
-    return "mate";
-  }
-}
-
 export async function deployMateSkillDir(src: string, dest: string): Promise<void> {
   await fs.mkdir(dest, { recursive: true });
   const entries = await fs.readdir(src, { withFileTypes: true });
@@ -83,31 +73,38 @@ export async function deployMateSkillDir(src: string, dest: string): Promise<voi
       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, currentMateCommand()),
-        "utf8",
-      );
-    } else {
-      await fs.copyFile(srcPath, destPath);
-    }
+    await fs.copyFile(srcPath, destPath);
+  }
+}
+
+const DEFAULT_MATE_SKILLS_BUCKET = "agents";
+
+/**
+ * A skill's source lives under a provider bucket so its folder name always
+ * matches its `name:` frontmatter: `<tool>/<skill>/` when that tool needs its
+ * own behavior (e.g. Claude Code always confirms before `mate artifact
+ * finish` pushes, since a push is a shared-state action), falling back to
+ * `agents/<skill>/` — the shared default every other tool (e.g. opencode,
+ * which pushes automatically) uses.
+ */
+async function resolveMateSkillSource(skill: string, tool: string): Promise<string> {
+  const providerDir = path.join(MATE_SKILLS_SOURCE, tool, skill);
+  try {
+    await fs.access(providerDir);
+    return providerDir;
+  } catch {
+    return path.join(MATE_SKILLS_SOURCE, DEFAULT_MATE_SKILLS_BUCKET, skill);
   }
 }
 
-export async function applyMateSkills(skillsDir: string): Promise<void> {
+export async function applyMateSkills(skillsDir: string, tool: string): Promise<void> {
   for (const skill of MATE_SKILLS) {
     const destination = path.join(skillsDir, skill);
     if (skill === "mate-create-report") {
       await fs.mkdir(destination, { recursive: true });
-      await fs.writeFile(
-        path.join(destination, "SKILL.md"),
-        MATE_CREATE_REPORT_SKILL.replaceAll(MATE_COMMAND_PLACEHOLDER, currentMateCommand()),
-        "utf8",
-      );
+      await fs.writeFile(path.join(destination, "SKILL.md"), MATE_CREATE_REPORT_SKILL, "utf8");
     } else {
-      await deployMateSkillDir(path.join(MATE_SKILLS_SOURCE, skill), destination);
+      await deployMateSkillDir(await resolveMateSkillSource(skill, tool), destination);
     }
   }
 }