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

package/package.json

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

package/src/cli/commands/cap/openspec.ts

@@ -79,7 +79,26 @@ export async function runOpenspecCapCommand(
     readOpenSpecProjectSchema(companionPath),
   );
 
-  const result = spawnSync("openspec", forwardedArgs, { cwd, stdio: "inherit" });
+  if (forwardedArgs[0] === "init" || forwardedArgs[0] === "update") {
+    const reset = spawnSync("openspec", ["config", "reset", "--all", "-y"], {
+      cwd,
+      stdio: "inherit",
+    });
+    if (reset.error) {
+      process.stderr.write(`Failed to reset openspec config: ${reset.error.message}\n`);
+      process.exitCode = 1;
+      return;
+    }
+    if (reset.status !== 0) {
+      process.exitCode = reset.status ?? 1;
+      return;
+    }
+  }
+
+  const result = spawnSync("openspec", forwardedArgs, {
+    cwd,
+    stdio: "inherit",
+  });
   if (result.error) {
     process.stderr.write(`Failed to run openspec: ${result.error.message}\n`);
     process.exitCode = 1;

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

@@ -50,6 +50,7 @@ async function selectRegisteredCompanion(): Promise<string> {
 async function runHubInit(argv: string[]): Promise<void> {
   const folder = positionalArgs(argv)[0] ?? process.cwd();
   const hubPath = await initializeCompanionHub(folder);
+  await updateHubPlugins(hubPath);
   console.log(`Initialized companion hub: ${hubPath}`);
 }
 

package/src/cli/commands/plugin/install.ts

@@ -2,8 +2,10 @@ import path from "node:path";
 
 import { FRAMEWORK_NAME } from "../../../framework";
 import { resolveInstallContext } from "../../../lib/install";
+import { backfillHubAllowedAgents } from "../../../lib/orchestrator/companion-hub";
 import { ConfigStore } from "../../../lib/orchestrator/config-store";
-import type { PluginDeclaration } from "../../../lib/orchestrator/types";
+import type { FrameworkConfig, PluginDeclaration } from "../../../lib/orchestrator/types";
+import { applySetupCompatibilities } from "../../../tools/setup";
 import { hydrateDynamicPlugins } from "../../../tools/setup/dynamic-plugins/hydrate";
 import {
   installDeclaredPlugins,
@@ -33,6 +35,7 @@ function withDeclaration(
 export interface PluginInstallCommandDeps {
   cwd?: string;
   installDeps?: PluginInstallDeps;
+  setupHub?: (companionPath: string, config: FrameworkConfig) => Promise<void>;
 }
 
 /**
@@ -78,8 +81,10 @@ export async function runPluginInstallCommand(
   );
   const store = new ConfigStore(configPath);
   const nextPlugins = withDeclaration(context.config.plugins ?? [], packageName, version);
-  if (nextPlugins !== context.config.plugins) {
-    await store.save({ ...context.config, plugins: nextPlugins });
+  const nextConfig = { ...context.config, plugins: nextPlugins };
+  const agentsBackfilled = context.kind === "hub" && backfillHubAllowedAgents(nextConfig);
+  if (nextPlugins !== context.config.plugins || agentsBackfilled) {
+    await store.save(nextConfig);
   }
 
   const results = await installDeclaredPlugins(
@@ -89,6 +94,13 @@ export async function runPluginInstallCommand(
   );
   reportPluginInstallResults(results);
   await hydrateDynamicPlugins({ companionPath: context.companionPath });
+  if (context.kind === "hub") {
+    await (
+      deps.setupHub ??
+      ((companionPath, config) =>
+        applySetupCompatibilities(companionPath, config, "sync", undefined, undefined, "hub"))
+    )(context.companionPath, nextConfig);
+  }
 
   return results.find((result) => result.package === packageName)?.status !== "failed";
 }

package/src/lib/orchestrator/companion-hub.ts

@@ -8,12 +8,14 @@ import { FRAMEWORK_NAME } from "../../framework";
 import { ConfigStore, validateHubConfig } from "./config-store";
 import { GlobalConfigStore } from "./global-config-store";
 import type { FrameworkConfig, HubMember, HubMemberSource } from "./types";
+import { listSetupProviderCompatibilities } from "./setup-compatibilities";
 import {
   installDeclaredPlugins,
   type PluginInstallDeps,
   type PluginInstallResult,
 } from "../../tools/setup/dynamic-plugins/install";
 import { hydrateDynamicPlugins } from "../../tools/setup/dynamic-plugins/hydrate";
+import { applySetupCompatibilities } from "../../tools/setup";
 import { findRepoLocalRegistryFile } from "./repo-local-registry";
 
 export interface GitCommandResult {
@@ -41,6 +43,7 @@ export interface HubSyncResult {
 export interface HubPluginSyncDeps {
   installDeps?: PluginInstallDeps;
   hydrate?: (options: { companionPath: string }) => Promise<void>;
+  setup?: (companionPath: string, config: FrameworkConfig, mode: "setup" | "sync") => Promise<void>;
 }
 
 export function defaultGitCommand(cwd: string, args: string[]): GitCommandResult {
@@ -123,7 +126,7 @@ export async function initializeCompanionHub(
   } else {
     const config: FrameworkConfig = {
       type: "hub",
-      allowedAgents: [],
+      allowedAgents: listSetupProviderCompatibilities().map((entry) => entry.agent),
       packageManagers: [],
       capabilities: [],
       hub: { companions: [] },
@@ -365,16 +368,35 @@ export async function syncHub(
   return results;
 }
 
+/**
+ * Hubs persisted before provider bootstrapping carry `allowedAgents: []`;
+ * an empty list on a hub means "all built-in agents", not "none".
+ */
+export function backfillHubAllowedAgents(config: FrameworkConfig): boolean {
+  if (config.type !== "hub" || config.allowedAgents.length > 0) return false;
+  config.allowedAgents = listSetupProviderCompatibilities().map((entry) => entry.agent);
+  return true;
+}
+
 export async function updateHubPlugins(
   hubPath: string,
   deps: HubPluginSyncDeps = {},
 ): Promise<PluginInstallResult[]> {
-  const { config } = await assertHubRoot(hubPath);
+  const { config, store } = await assertHubRoot(hubPath);
+  if (backfillHubAllowedAgents(config)) await store.save(config);
   const declarations = config.plugins ?? [];
-  if (declarations.length === 0) return [];
-
   const resolvedHubPath = path.resolve(hubPath);
-  const results = await installDeclaredPlugins(resolvedHubPath, declarations, deps.installDeps);
-  await (deps.hydrate ?? hydrateDynamicPlugins)({ companionPath: resolvedHubPath });
+  const results =
+    declarations.length > 0
+      ? await installDeclaredPlugins(resolvedHubPath, declarations, deps.installDeps)
+      : [];
+  if (declarations.length > 0) {
+    await (deps.hydrate ?? hydrateDynamicPlugins)({ companionPath: resolvedHubPath });
+  }
+  await (
+    deps.setup ??
+    ((companionPath, setupConfig, mode) =>
+      applySetupCompatibilities(companionPath, setupConfig, mode, undefined, undefined, "hub"))
+  )(resolvedHubPath, config, "sync");
   return results;
 }

package/src/lib/orchestrator/types.ts

@@ -96,8 +96,8 @@ export type PluginDeclarationPolicy = "default" | "optional";
 /**
  * A companion-declared npm plugin: installed by setup/install into the
  * companion's own shared plugin workspace (`.mate/plugins/`) and loaded
- * from there on every invocation. Declaration registers the plugin;
- * enablement stays in the `capabilities` list.
+ * from there on every invocation. Declaration both registers and activates
+ * the plugin; dynamic plugins do not need a separate `capabilities` entry.
  */
 export interface PluginDeclaration {
   /** npm package name (e.g. `@acme/custom-plugin`). */

package/src/templates/root/TEMPLATE_AGENTS.md

@@ -12,6 +12,6 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
 - Code comments: JSDoc format only (`/** ... */`), never `//`. Sparse — only non-obvious invariants or constraints, never restated artifact rationale.
 - Never add a `Co-Authored-By: <model>` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (`$MATE_REPO_PATH`) unless the user explicitly asks for it.
-- Never run database queries or other destructive/irreversible operations (writes, deletes, migrations, force-push, `rm -rf`, deploys) without asking the user first.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->

package/src/templates/root/TEMPLATE_CLAUDE.md

@@ -14,6 +14,6 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
 - The root `CLAUDE.md` in the companion repo is intentional and loaded by Mate. Do not create another project-level `CLAUDE.md` in the working repo unless the user explicitly asks for one.
 - Never add a `Co-Authored-By: <model>` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (`$MATE_REPO_PATH`) unless the user explicitly asks for it.
-- Never run database queries or other destructive/irreversible operations (writes, deletes, migrations, force-push, `rm -rf`, deploys) without asking the user first.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->

package/src/tools/setup/__snapshots__/runtime-surface-golden.test.ts.snap

@@ -17,6 +17,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
 - Code comments: JSDoc format only (\`/** ... */\`), never \`//\`. Sparse — only non-obvious invariants or constraints, never restated artifact rationale.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -42,6 +43,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
 - The root \`CLAUDE.md\` in the companion repo is intentional and loaded by Mate. Do not create another project-level \`CLAUDE.md\` in the working repo unless the user explicitly asks for one.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -174,6 +176,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
 - Code comments: JSDoc format only (\`/** ... */\`), never \`//\`. Sparse — only non-obvious invariants or constraints, never restated artifact rationale.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -191,7 +194,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.9",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
     ],
     "references": {
       "mate": "..",
@@ -227,7 +230,7 @@ Write chunks to $GRAPHIFY_OUT and read $GRAPHIFY_OUT later.
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.9",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
     ],
   },
 }
@@ -321,6 +324,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
 - Code comments: JSDoc format only (\`/** ... */\`), never \`//\`. Sparse — only non-obvious invariants or constraints, never restated artifact rationale.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -346,6 +350,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
 - The root \`CLAUDE.md\` in the companion repo is intentional and loaded by Mate. Do not create another project-level \`CLAUDE.md\` in the working repo unless the user explicitly asks for one.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -402,7 +407,7 @@ Write chunks to $GRAPHIFY_OUT and read $GRAPHIFY_OUT later.
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.9",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
     ],
     "references": {
       "mate": "..",
@@ -438,7 +443,7 @@ Write chunks to $GRAPHIFY_OUT and read $GRAPHIFY_OUT later.
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.9",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
     ],
   },
 }
@@ -587,6 +592,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
 - Code comments: JSDoc format only (\`/** ... */\`), never \`//\`. Sparse — only non-obvious invariants or constraints, never restated artifact rationale.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -619,6 +625,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
 - The root \`CLAUDE.md\` in the companion repo is intentional and loaded by Mate. Do not create another project-level \`CLAUDE.md\` in the working repo unless the user explicitly asks for one.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -758,6 +765,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
 - Code comments: JSDoc format only (\`/** ... */\`), never \`//\`. Sparse — only non-obvious invariants or constraints, never restated artifact rationale.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -785,7 +793,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
       },
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.9",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
     ],
     "references": {
       "mate": "..",
@@ -800,7 +808,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.9",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
     ],
   },
 }
@@ -891,6 +899,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
 - Code comments: JSDoc format only (\`/** ... */\`), never \`//\`. Sparse — only non-obvious invariants or constraints, never restated artifact rationale.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -923,6 +932,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
 - The root \`CLAUDE.md\` in the companion repo is intentional and loaded by Mate. Do not create another project-level \`CLAUDE.md\` in the working repo unless the user explicitly asks for one.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -999,7 +1009,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
       },
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.9",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
     ],
     "references": {
       "mate": "..",
@@ -1014,7 +1024,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.9",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
     ],
   },
 }
@@ -1157,6 +1167,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
 - Code comments: JSDoc format only (\`/** ... */\`), never \`//\`. Sparse — only non-obvious invariants or constraints, never restated artifact rationale.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -1182,6 +1193,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
 - The root \`CLAUDE.md\` in the companion repo is intentional and loaded by Mate. Do not create another project-level \`CLAUDE.md\` in the working repo unless the user explicitly asks for one.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -1274,6 +1286,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
 - Code comments: JSDoc format only (\`/** ... */\`), never \`//\`. Sparse — only non-obvious invariants or constraints, never restated artifact rationale.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 
@@ -1299,7 +1312,7 @@ Canonical Mate policy and any more specific tool-routing instructions remain aut
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.9",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
       "context-mode@1.0.169",
     ],
     "references": {
@@ -1315,7 +1328,7 @@ Canonical Mate policy and any more specific tool-routing instructions remain aut
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.9",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
       "context-mode@1.0.169",
     ],
   },
@@ -1399,6 +1412,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
 - Code comments: JSDoc format only (\`/** ... */\`), never \`//\`. Sparse — only non-obvious invariants or constraints, never restated artifact rationale.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 
@@ -1432,6 +1446,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
 - The root \`CLAUDE.md\` in the companion repo is intentional and loaded by Mate. Do not create another project-level \`CLAUDE.md\` in the working repo unless the user explicitly asks for one.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -1457,7 +1472,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.9",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
       "context-mode@1.0.169",
     ],
     "references": {
@@ -1473,7 +1488,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.9",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
       "context-mode@1.0.169",
     ],
   },
@@ -1603,6 +1618,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
 - Code comments: JSDoc format only (\`/** ... */\`), never \`//\`. Sparse — only non-obvious invariants or constraints, never restated artifact rationale.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -1630,6 +1646,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
 - The root \`CLAUDE.md\` in the companion repo is intentional and loaded by Mate. Do not create another project-level \`CLAUDE.md\` in the working repo unless the user explicitly asks for one.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -1749,6 +1766,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
 - Code comments: JSDoc format only (\`/** ... */\`), never \`//\`. Sparse — only non-obvious invariants or constraints, never restated artifact rationale.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -1766,7 +1784,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.9",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
     ],
     "references": {
       "mate": "..",
@@ -1784,7 +1802,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.9",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
     ],
   },
 }
@@ -1867,6 +1885,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
 - Code comments: JSDoc format only (\`/** ... */\`), never \`//\`. Sparse — only non-obvious invariants or constraints, never restated artifact rationale.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -1894,6 +1913,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
 - The root \`CLAUDE.md\` in the companion repo is intentional and loaded by Mate. Do not create another project-level \`CLAUDE.md\` in the working repo unless the user explicitly asks for one.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -1948,7 +1968,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.9",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
     ],
     "references": {
       "mate": "..",
@@ -1966,7 +1986,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.9",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
     ],
   },
 }
@@ -2093,6 +2113,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
 - Code comments: JSDoc format only (\`/** ... */\`), never \`//\`. Sparse — only non-obvious invariants or constraints, never restated artifact rationale.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -2118,6 +2139,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
 - The root \`CLAUDE.md\` in the companion repo is intentional and loaded by Mate. Do not create another project-level \`CLAUDE.md\` in the working repo unless the user explicitly asks for one.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -2220,6 +2242,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
 - Code comments: JSDoc format only (\`/** ... */\`), never \`//\`. Sparse — only non-obvious invariants or constraints, never restated artifact rationale.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -2237,7 +2260,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.9",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
     ],
     "references": {
       "mate": "..",
@@ -2257,7 +2280,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.9",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
     ],
   },
 }
@@ -2341,6 +2364,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
 - Code comments: JSDoc format only (\`/** ... */\`), never \`//\`. Sparse — only non-obvious invariants or constraints, never restated artifact rationale.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -2366,6 +2390,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
 - The root \`CLAUDE.md\` in the companion repo is intentional and loaded by Mate. Do not create another project-level \`CLAUDE.md\` in the working repo unless the user explicitly asks for one.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -2402,7 +2427,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.9",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
     ],
     "references": {
       "mate": "..",
@@ -2422,7 +2447,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.9",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
     ],
   },
 }
@@ -2551,6 +2576,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
 - Code comments: JSDoc format only (\`/** ... */\`), never \`//\`. Sparse — only non-obvious invariants or constraints, never restated artifact rationale.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 
@@ -2593,6 +2619,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
 - The root \`CLAUDE.md\` in the companion repo is intentional and loaded by Mate. Do not create another project-level \`CLAUDE.md\` in the working repo unless the user explicitly asks for one.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -2738,7 +2765,7 @@ Write chunks to $GRAPHIFY_OUT and read $GRAPHIFY_OUT later.
       },
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.9",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
       "context-mode@1.0.169",
     ],
     "references": {
@@ -2781,7 +2808,7 @@ Write chunks to $GRAPHIFY_OUT and read $GRAPHIFY_OUT later.
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.9",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
       "context-mode@1.0.169",
     ],
   },
@@ -2935,6 +2962,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
 - Code comments: JSDoc format only (\`/** ... */\`), never \`//\`. Sparse — only non-obvious invariants or constraints, never restated artifact rationale.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -2960,6 +2988,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
 - The root \`CLAUDE.md\` in the companion repo is intentional and loaded by Mate. Do not create another project-level \`CLAUDE.md\` in the working repo unless the user explicitly asks for one.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -2983,7 +3012,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.9",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
     ],
     "references": {
       "mate": "..",
@@ -2998,7 +3027,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.9",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
     ],
   },
 }
@@ -3021,6 +3050,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
 - Code comments: JSDoc format only (\`/** ... */\`), never \`//\`. Sparse — only non-obvious invariants or constraints, never restated artifact rationale.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -3046,6 +3076,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
 - The root \`CLAUDE.md\` in the companion repo is intentional and loaded by Mate. Do not create another project-level \`CLAUDE.md\` in the working repo unless the user explicitly asks for one.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -3069,7 +3100,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.9",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
     ],
     "references": {
       "mate": "..",
@@ -3084,7 +3115,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.9",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
     ],
   },
 }
@@ -3107,6 +3138,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
 - Code comments: JSDoc format only (\`/** ... */\`), never \`//\`. Sparse — only non-obvious invariants or constraints, never restated artifact rationale.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 
@@ -3133,6 +3165,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
 - The root \`CLAUDE.md\` in the companion repo is intentional and loaded by Mate. Do not create another project-level \`CLAUDE.md\` in the working repo unless the user explicitly asks for one.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -3156,7 +3189,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.9",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
     ],
     "references": {
       "mate": "..",
@@ -3171,7 +3204,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.9",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
     ],
   },
 }
@@ -3194,6 +3227,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
 - Code comments: JSDoc format only (\`/** ... */\`), never \`//\`. Sparse — only non-obvious invariants or constraints, never restated artifact rationale.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -3219,6 +3253,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
 - The root \`CLAUDE.md\` in the companion repo is intentional and loaded by Mate. Do not create another project-level \`CLAUDE.md\` in the working repo unless the user explicitly asks for one.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -3242,7 +3277,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.9",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
     ],
     "references": {
       "mate": "..",
@@ -3257,7 +3292,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.9",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
     ],
   },
 }
@@ -3280,6 +3315,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
 - Code comments: JSDoc format only (\`/** ... */\`), never \`//\`. Sparse — only non-obvious invariants or constraints, never restated artifact rationale.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -3305,6 +3341,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
 - The root \`CLAUDE.md\` in the companion repo is intentional and loaded by Mate. Do not create another project-level \`CLAUDE.md\` in the working repo unless the user explicitly asks for one.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -3328,7 +3365,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.9",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
     ],
     "references": {
       "mate": "..",
@@ -3343,7 +3380,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.9",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
     ],
   },
 }
@@ -3366,6 +3403,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
 - Code comments: JSDoc format only (\`/** ... */\`), never \`//\`. Sparse — only non-obvious invariants or constraints, never restated artifact rationale.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -3391,6 +3429,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
 - The root \`CLAUDE.md\` in the companion repo is intentional and loaded by Mate. Do not create another project-level \`CLAUDE.md\` in the working repo unless the user explicitly asks for one.
 - Never add a \`Co-Authored-By: <model>\` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (\`$MATE_REPO_PATH\`) unless the user explicitly asks for it.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->
 "
@@ -3525,15 +3564,44 @@ User notes.
 }
 `;
 
-exports[`working repo golden fixtures hub roots are refused before any runtime file is written 1`] = `
+exports[`working repo golden fixtures hub roots set up providers only without companion surfaces 1`] = `
 {
   "agentsMd": null,
   "claudeHooks": {},
-  "claudeMcpConfig": null,
+  "claudeMcpConfig": {
+    "mcpServers": {
+      "tokensave": {
+        "args": [
+          "serve",
+        ],
+        "command": "tokensave",
+      },
+    },
+  },
   "claudeMd": null,
-  "claudeSettingsLocal": null,
+  "claudeSettingsLocal": {
+    "autoMemoryEnabled": false,
+    "permissions": {
+      "allow": [
+        "Bash(mate:*)",
+        "Edit(<root>/companion/**)",
+        "Read(<root>/companion/**)",
+      ],
+    },
+  },
   "claudeSkills": {},
-  "opencodeConfig": null,
+  "opencodeConfig": {
+    "mcp": {
+      "tokensave": {
+        "command": [
+          "tokensave",
+          "serve",
+        ],
+        "enabled": true,
+        "type": "local",
+      },
+    },
+  },
   "opencodePlugins": {},
   "opencodeSkills": {},
   "opencodeTui": null,

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

@@ -134,6 +134,16 @@ async function reconcileOpenSpecTools(
 ): Promise<void> {
   const tools = deriveOpenSpecTools(ctx.activeProviders);
   if (tools.length === 0) return;
+  /** Best-effort: `config reset` is missing on older openspec releases. */
+  try {
+    await runCommand("openspec", ["config", "reset", "--all", "-y"], {
+      cwd: ctx.companionPath,
+    });
+  } catch (error) {
+    process.stderr.write(
+      `openspec config reset skipped: ${error instanceof Error ? error.message : String(error)}\n`,
+    );
+  }
 
   await runCommand("openspec", ["init", "--tools", tools.join(","), "--force", ctx.companionPath], {
     cwd: ctx.companionPath,

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

@@ -9,6 +9,7 @@ import { CompanionResolver } from "../../../lib/orchestrator/companion-resolver"
 import { GlobalConfigStore } from "../../../lib/orchestrator/global-config-store";
 import { PLUGIN_DECLARATION_POLICIES } from "../../../lib/orchestrator/config-store";
 import type { PluginDeclaration } from "../../../lib/orchestrator/types";
+import type { Plugin } from "../plugin";
 import type { PluginRegistry } from "../registry";
 import { loadDynamicPlugin, type DynamicPluginLoadDeps } from "./loader";
 
@@ -89,6 +90,16 @@ function validateDeclaration(entry: unknown): { declaration?: PluginDeclaration;
   return { declaration: entry as unknown as PluginDeclaration };
 }
 
+/**
+ * A framework declaration is the activation switch for a dynamic plugin.
+ * Own-property override rather than a spread: class-instance plugins keep
+ * their prototype members.
+ */
+function activateDeclaredPlugin(plugin: Plugin): Plugin {
+  plugin.isEnabled = () => true;
+  return plugin;
+}
+
 /**
  * Registers the companion's declared plugins into the active registry —
  * compiled-in plugins first (they are already registered), declared order
@@ -135,7 +146,10 @@ export async function hydrateDynamicPlugins(deps: HydrateDynamicPluginsDeps = {}
         );
       }
 
-      registry.register({ plugin: result.plugin, policy: declaration.policy ?? "optional" });
+      registry.register({
+        plugin: activateDeclaredPlugin(result.plugin),
+        policy: declaration.policy ?? "optional",
+      });
       hydratedPackages.add(declaration.package);
     }
   } catch (error) {

package/src/tools/setup/engine.ts

@@ -125,6 +125,8 @@ export async function executeSetupInstallationPlan(
   });
 
   for (const action of plan.actions) {
+    if (ctx.scope === "hub" && action.phase !== "provider") continue;
+
     const plugin = pluginById.get(action.pluginId);
     if (!plugin) {
       continue;

package/src/tools/setup/plugin.ts

@@ -2,11 +2,15 @@ import type { FrameworkConfig, LinkedRepository } from "../../lib/orchestrator/t
 import type { InstallRequirement, InstallRequirementContext } from "./install-contract";
 import type { ClaudeHookGroup } from "./providers/claude-format";
 
+export type SetupScope = "companion" | "hub";
+
 export interface SetupContext {
   companionPath: string;
   config: FrameworkConfig;
   mode: "setup" | "sync";
   activeProviders: string[];
+  /** Hub setup runs providers but excludes companion-only surfaces. */
+  scope?: SetupScope;
   /** Working repository path when syncing from a linked repo (e.g. during launch). */
   repoPath?: string;
   /**

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

@@ -346,6 +346,11 @@ export async function reconcileClaudeContributions(
 ): Promise<void> {
   const { companionPath, config } = ctx;
 
+  if (ctx.scope === "hub") {
+    await reconcileClaudeMcpContributions(ctx, inputs);
+    return;
+  }
+
   // The settings sync (re)creates the managed settings document, so it only
   // runs while the Claude runtime is active; a deactivated runtime's pass is
   // teardown-only and must not resurrect files the provider teardown removed.
@@ -353,15 +358,9 @@ export async function reconcileClaudeContributions(
     await syncCompanionClaudeSettings(companionPath, config, inputs);
   }
 
-  for (const input of inputs) {
-    for (const descriptor of input.contributions.mcpServers ?? []) {
-      await updateClaudeMcpServer(
-        getCompanionClaudeMcpConfigPath(companionPath),
-        descriptor.name,
-        input.enabled ? toClaudeMcpEntry(descriptor) : null,
-      );
-    }
+  await reconcileClaudeMcpContributions(ctx, inputs);
 
+  for (const input of inputs) {
     // Guidance sections are managed blocks in CLAUDE.md. Current sections are
     // upserted, then stale keys (content changes, disabled capability) are
     // swept. CLAUDE.md is Claude-exclusive, so no shared-file guard applies.
@@ -389,6 +388,22 @@ export async function reconcileClaudeContributions(
   }
 }
 
+/** Reconcile only MCP entries without touching Claude settings or guidance. */
+async function reconcileClaudeMcpContributions(
+  ctx: SetupContext,
+  inputs: CapabilityContributionInput[],
+): Promise<void> {
+  for (const input of inputs) {
+    for (const descriptor of input.contributions.mcpServers ?? []) {
+      await updateClaudeMcpServer(
+        getCompanionClaudeMcpConfigPath(ctx.companionPath),
+        descriptor.name,
+        input.enabled ? toClaudeMcpEntry(descriptor) : null,
+      );
+    }
+  }
+}
+
 // Maintain the companion `.mcp.json` shell. Managed MCP servers are reconciled
 // from declared Capability contributions (and legacy `ctx.mcp` hosting); this
 // only guarantees the file exists with an `mcpServers` map. Loaded at launch
@@ -688,6 +703,10 @@ export function createClaudePlugin(): ProviderPlugin {
       },
     },
     async apply(ctx) {
+      if (ctx.scope === "hub") {
+        await syncCompanionClaudeSettings(ctx.companionPath, ctx.config);
+        return;
+      }
       await configureClaude(ctx.companionPath);
       await configureClaudeGuidance(ctx.companionPath);
       await teardownLegacyClaudeBin(ctx.companionPath);

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

@@ -426,15 +426,14 @@ export async function reconcileOpenCodeContributions(
 ): Promise<void> {
   const { companionPath } = ctx;
 
-  for (const input of inputs) {
-    for (const descriptor of input.contributions.mcpServers ?? []) {
-      await updateOpenCodeMcpServer(
-        getCompanionOpenCodeConfigPath(companionPath),
-        descriptor.name,
-        input.enabled ? toOpenCodeMcpEntry(descriptor) : null,
-      );
-    }
+  if (ctx.scope === "hub") {
+    await reconcileOpenCodeMcpContributions(ctx, inputs);
+    return;
+  }
 
+  await reconcileOpenCodeMcpContributions(ctx, inputs);
+
+  for (const input of inputs) {
     for (const pluginReference of input.contributions.pluginReferences ?? []) {
       const configFiles = pluginReference.configFiles ?? OPENCODE_CONTRIBUTION_CONFIG_FILES;
       for (const name of configFiles) {
@@ -479,6 +478,22 @@ export async function reconcileOpenCodeContributions(
   }
 }
 
+/** Reconcile only MCP entries without touching OpenCode plugins or guidance. */
+async function reconcileOpenCodeMcpContributions(
+  ctx: SetupContext,
+  inputs: CapabilityContributionInput[],
+): Promise<void> {
+  for (const input of inputs) {
+    for (const descriptor of input.contributions.mcpServers ?? []) {
+      await updateOpenCodeMcpServer(
+        getCompanionOpenCodeConfigPath(ctx.companionPath),
+        descriptor.name,
+        input.enabled ? toOpenCodeMcpEntry(descriptor) : null,
+      );
+    }
+  }
+}
+
 export function createOpenCodePlugin(): ProviderPlugin {
   return {
     id: "opencode",
@@ -509,6 +524,7 @@ export function createOpenCodePlugin(): ProviderPlugin {
       },
     },
     async apply(ctx: SetupContext) {
+      if (ctx.scope === "hub") return;
       await syncOpenCodeRuntimeFiles(
         path.join(getSetupProvidersRoot(), "opencode"),
         ctx.companionPath,

package/src/tools/setup.ts

@@ -1,5 +1,4 @@
 // oxlint-disable no-await-in-loop
-import fs from "node:fs/promises";
 import path from "node:path";
 
 import { FRAMEWORK_NAME } from "../framework";
@@ -25,7 +24,7 @@ import {
   collectManagedGitignoreEntries,
   writeManagedGitignoreBlock,
 } from "./setup/plugins/gitignore";
-import type { PluginRegistration, SetupContext } from "./setup/plugin";
+import type { PluginRegistration, SetupContext, SetupScope } from "./setup/plugin";
 import { getActiveDistribution } from "../distribution";
 import { createUvPlugin } from "./setup/package-managers/uv";
 import type { PackageManagerSetupDeps } from "./setup/package-managers/uv";
@@ -60,10 +59,11 @@ export async function applySetupCompatibilities(
   mode: "setup" | "sync",
   plugins: PluginRegistration[] = getActiveDistribution().registry.getEntries(),
   repoPath?: string,
+  scope: SetupScope = config.type === "hub" ? "hub" : "companion",
 ): Promise<SetupInstallationOutcome> {
   const plan = buildSetupInstallationPlan(config, plugins);
   const activeProviders = plan.activeProviders;
-  const ctx: SetupContext = { companionPath, config, mode, activeProviders, repoPath };
+  const ctx: SetupContext = { companionPath, config, mode, activeProviders, repoPath, scope };
   return executeSetupInstallationPlan(ctx, plugins, plan);
 }
 
@@ -91,48 +91,6 @@ export async function syncCompanionFiles(
   );
 }
 
-export function mateFolderReadme(): string {
-  const n = FRAMEWORK_NAME;
-  const packageName =
-    getActiveDistribution().config.update?.packageName ?? `@uniqbit/${FRAMEWORK_NAME}`;
-  return [
-    `# .${FRAMEWORK_NAME}`,
-    ``,
-    `This directory is managed by the **${FRAMEWORK_NAME}** companion framework (\`${packageName}\`).`,
-    ``,
-    `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`,
-    ``,
-    `| Command | Description |`,
-    `|---|---|`,
-    `| \`${n} companion setup\` | Initialize or re-configure this companion |`,
-    `| \`${n} companion link\` | Link a working repository to a companion |`,
-    `| \`${n} companion list\` | List linked repositories for the active working repo context |`,
-    `| \`${n} companion open\` | Inject the resolved companion into the current editor window |`,
-    `| \`${n} claude\` / \`${n} opencode\` | Launch an allowed agent from a linked working repository |`,
-    `| \`${n} doctor\` | Check current link state, installed tools, and active capabilities |`,
-    ``,
-    `Run \`${n} claude\` or \`${n} opencode\` from any linked working repository directory.`,
-    ``,
-    `## Configuration`,
-    ``,
-    `Edit \`.${FRAMEWORK_NAME}/config/framework.yaml\` to configure:`,
-    ``,
-    `- **allowedAgents** — agents permitted to launch from linked repositories`,
-    `- **capabilities** — skill and CLI tool capabilities (e.g. react-doctor, openspec, tokensave, headroom, rtk)`,
-    `- **git** — set to \`auto\` to synchronize the companion before agent launches`,
-    ``,
-  ].join("\n");
-}
-
-async function writeMateReadme(companionPath: string): Promise<void> {
-  const readmePath = path.join(companionPath, `.${FRAMEWORK_NAME}`, "README.md");
-  await fs.mkdir(path.dirname(readmePath), { recursive: true });
-  await fs.writeFile(readmePath, mateFolderReadme(), "utf8");
-}
-
 export const setupToolDeps = {
   executeSetup: (input: SetupInput) => executeSetup(input),
 };
@@ -160,14 +118,6 @@ export async function executeSetup(
     deps.configStore ??
     new ConfigStore(path.join(cwd, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"));
   const config = mergeWithDefaults(await configStore.load());
-  // Hubs are never companions: no setup entry path (CLI, wizard, or the
-  // setup framework tool) may write agent guidance into a hub root.
-  if (config.type === "hub") {
-    throw new ConfigError(
-      `A companion hub cannot be set up as a companion: ${cwd}. Use \`${FRAMEWORK_NAME} hub\` commands to manage the hub.`,
-    );
-  }
-
   if (input.allowedAgents !== undefined) {
     config.allowedAgents = [...new Set(input.allowedAgents)];
   }
@@ -202,12 +152,13 @@ export async function executeSetup(
     await hydrateDynamicPlugins({ companionPath });
   }
   await applySetupCompatibilities(companionPath, config, "setup");
-  await invalidateInstallState({ kind: "companion", companionPath });
+  await invalidateInstallState({
+    kind: config.type === "hub" ? "hub" : "companion",
+    companionPath,
+  });
 
   await globalConfigStore.register(companionPath);
 
-  await writeMateReadme(companionPath);
-
   // Setup no longer fans out to linked repos: capabilities that touch a working repo
   // (companion files on launch, the tokensave/graphify graph via `mate cap index`)
   // are applied in that repo's own context, not eagerly from here.