@uniqbit/mate-core 0.15.4-canary.8 → 0.15.4

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

@@ -0,0 +1,146 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import type { McpEntryDescriptor } from "./claude-format";
+
+// OpenCode runtime config format primitives: parse/serialize for
+// `opencode.json`/`tui.json`, plugin-reference array handling, and MCP entry
+// shapes. This module owns the file formats only — which entries are
+// Mate-managed is the callers' (Runtime Surface) knowledge.
+
+export type OpenCodeConfig = Record<string, unknown>;
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Tolerant read; `present` distinguishes absent/malformed from empty. */
+export async function readOpenCodeConfig(
+  configPath: string,
+): Promise<{ present: boolean; config: OpenCodeConfig }> {
+  try {
+    const parsed = JSON.parse(await fs.readFile(configPath, "utf8")) as unknown;
+    if (isRecord(parsed)) {
+      return { present: true, config: parsed };
+    }
+  } catch {
+    // Absent or unparseable — start from an empty object.
+  }
+  return { present: false, config: {} };
+}
+
+export async function writeOpenCodeConfig(
+  configPath: string,
+  config: OpenCodeConfig,
+): Promise<void> {
+  await fs.mkdir(path.dirname(configPath), { recursive: true });
+  await fs.writeFile(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+}
+
+export function getOpenCodePluginReferences(config: OpenCodeConfig): unknown[] {
+  return Array.isArray(config.plugin) ? config.plugin : [];
+}
+
+/** Replace the plugin array in place; an empty list removes the key. */
+export function setOpenCodePluginReferences(config: OpenCodeConfig, references: unknown[]): void {
+  if (references.length === 0) {
+    delete config.plugin;
+    return;
+  }
+  config.plugin = references;
+}
+
+function mergeConfig(target: Record<string, unknown>, source: Record<string, unknown>): void {
+  for (const [key, sourceValue] of Object.entries(source)) {
+    const targetValue = target[key];
+    if (isRecord(targetValue) && isRecord(sourceValue)) {
+      mergeConfig(targetValue, sourceValue);
+      continue;
+    }
+
+    target[key] = sourceValue;
+  }
+}
+
+/**
+ * Merge an overlay into the launch-time `OPENCODE_CONFIG_CONTENT` env value
+ * (overlay wins on scalar conflicts) and return the serialized result. Invalid
+ * inherited content is ignored rather than breaking the launch.
+ */
+export function mergeOpenCodeConfigContent(
+  overlay: Record<string, unknown>,
+  env: NodeJS.ProcessEnv = process.env,
+  options: { appendSkillPaths?: string[] } = {},
+): string {
+  let config: Record<string, unknown> = {};
+  const existing = env.OPENCODE_CONFIG_CONTENT;
+
+  if (existing) {
+    try {
+      const parsed = JSON.parse(existing) as unknown;
+      if (isRecord(parsed)) {
+        config = parsed;
+      }
+    } catch {
+      // Ignore invalid inherited config content rather than breaking launch.
+    }
+  }
+
+  mergeConfig(config, overlay);
+
+  if (options.appendSkillPaths && options.appendSkillPaths.length > 0) {
+    const skills = isRecord(config.skills) ? config.skills : {};
+    const paths = Array.isArray(skills.paths) ? skills.paths : [];
+    const existingPaths = new Set(paths);
+    skills.paths = [
+      ...paths,
+      ...options.appendSkillPaths.filter((skillPath) => !existingPaths.has(skillPath)),
+    ];
+    config.skills = skills;
+  }
+
+  return JSON.stringify(config);
+}
+
+/** Map a provider-agnostic MCP descriptor to OpenCode's `mcp` entry shape. */
+export function toOpenCodeMcpEntry(descriptor: McpEntryDescriptor): Record<string, unknown> {
+  if (descriptor.url) {
+    return { type: "remote", url: descriptor.url, enabled: true };
+  }
+  return {
+    type: "local",
+    command: [descriptor.command ?? "", ...(descriptor.args ?? [])].filter(Boolean),
+    ...(descriptor.env ? { environment: descriptor.env } : {}),
+    enabled: true,
+  };
+}
+
+/**
+ * Reconcile a single server entry in the `mcp` map while preserving every
+ * unrelated key. `entry: null` removes the server; removal never creates the
+ * file, and an emptied `mcp` map is dropped entirely.
+ */
+export async function updateOpenCodeMcpServer(
+  configPath: string,
+  name: string,
+  entry: Record<string, unknown> | null,
+): Promise<void> {
+  const { present, config } = await readOpenCodeConfig(configPath);
+  if (entry === null && !present) return;
+
+  const mcp: Record<string, unknown> = isRecord(config.mcp) ? { ...config.mcp } : {};
+  if (entry === null) {
+    if (!(name in mcp)) return;
+    delete mcp[name];
+  } else {
+    mcp[name] = entry;
+  }
+
+  const next = { ...config };
+  if (Object.keys(mcp).length > 0) {
+    next.mcp = mcp;
+  } else {
+    delete next.mcp;
+  }
+  await writeOpenCodeConfig(configPath, next);
+}

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

@@ -10,8 +10,25 @@ import {
   warmOpenCodePluginCache,
 } from "../../../lib/opencode-plugin-package";
 import { refreshFromTemplate, stripGuidanceBlock } from "../plugins/guidance";
-import type { McpServerDescriptor, ProviderPlugin, SetupContext } from "../plugin";
-import { pruneEmptyAncestors } from "../utils";
+import { stripSectionFromFile, type RemoveHeadingSectionOptions } from "./agent-file-sections";
+import { patchSkillTreeMarkdownFiles } from "./skill-tree";
+import {
+  instructionBlockKey,
+  removeManagedBlocksForPlugin,
+  upsertManagedBlock,
+} from "../context-services";
+import type { CapabilityContributionInput, ProviderPlugin, SetupContext } from "../plugin";
+import { mergeDir, pruneEmptyAncestors } from "../utils";
+import {
+  getOpenCodePluginReferences,
+  isRecord,
+  readOpenCodeConfig,
+  setOpenCodePluginReferences,
+  toOpenCodeMcpEntry,
+  updateOpenCodeMcpServer,
+  writeOpenCodeConfig,
+  type OpenCodeConfig,
+} from "./opencode-format";
 import { getSetupProvidersRoot, getSetupRootTemplates } from "./utils";
 
 // Copied Mate plugin source files from earlier releases. Plugin code is
@@ -46,10 +63,6 @@ const LEGACY_TUI_DEPENDENCIES = {
   "@opentui/solid": "^0.3.4",
 };
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 function mergeConfigDefaults(
   target: Record<string, unknown>,
   defaults: Record<string, unknown>,
@@ -100,25 +113,20 @@ function isLegacyMatePluginConfigEntry(entry: unknown): boolean {
  * references) with the current pinned package reference while preserving
  * every unrelated plugin entry.
  */
-function ensureMatePluginReference(config: Record<string, unknown>, pluginReference: string): void {
-  const existing = Array.isArray(config.plugin) ? config.plugin : [];
-  const preserved = existing.filter(
+function ensureMatePluginReference(config: OpenCodeConfig, pluginReference: string): void {
+  const preserved = getOpenCodePluginReferences(config).filter(
     (entry) => !isMateOpenCodePluginReference(entry) && !isLegacyMatePluginConfigEntry(entry),
   );
-  config.plugin = [...preserved, pluginReference];
+  setOpenCodePluginReferences(config, [...preserved, pluginReference]);
 }
 
-function stripMatePluginReference(config: Record<string, unknown>): void {
+function stripMatePluginReference(config: OpenCodeConfig): void {
   if (!Array.isArray(config.plugin)) return;
 
-  const preserved = config.plugin.filter(
+  const preserved = getOpenCodePluginReferences(config).filter(
     (entry) => !isMateOpenCodePluginReference(entry) && !isLegacyMatePluginConfigEntry(entry),
   );
-  if (preserved.length === 0) {
-    delete config.plugin;
-    return;
-  }
-  config.plugin = preserved;
+  setOpenCodePluginReferences(config, preserved);
 }
 
 async function syncOpenCodeConfigFile(
@@ -140,7 +148,7 @@ async function syncOpenCodeConfigFile(
 
   mergeConfigDefaults(existing, defaults);
   ensureMatePluginReference(existing, pluginReference);
-  await fs.writeFile(destPath, JSON.stringify(existing, null, 2) + "\n", "utf8");
+  await writeOpenCodeConfig(destPath, existing);
 }
 
 function normalizeForComparison(value: unknown): unknown {
@@ -187,7 +195,7 @@ async function teardownOpenCodeConfigFile(srcPath: string, destPath: string): Pr
     return;
   }
 
-  await fs.writeFile(destPath, JSON.stringify(existing, null, 2) + "\n", "utf8");
+  await writeOpenCodeConfig(destPath, existing);
 }
 
 async function removeLegacyTuiDependencies(dest: string): Promise<void> {
@@ -326,55 +334,191 @@ function getCompanionOpenCodeConfigPath(companionPath: string): string {
   return path.join(companionPath, ".opencode", "opencode.json");
 }
 
-function opencodeMcpEntry(descriptor: McpServerDescriptor): Record<string, unknown> {
-  if (descriptor.url) {
-    return { type: "remote", url: descriptor.url, enabled: true };
+// ---------------------------------------------------------------------------
+// Runtime Surface escape hatch (spec: runtime-surface). Imperative operations
+// for effects a declaration cannot express. Format knowledge stays here;
+// capabilities pass only predicates.
+// ---------------------------------------------------------------------------
+
+/** Patch markdown files of an externally written `.opencode/skills/<name>` tree. */
+export async function patchOpenCodeSkillTree(
+  companionPath: string,
+  name: string,
+  transform: (content: string) => string,
+  options: { excludeFiles?: readonly string[] } = {},
+): Promise<void> {
+  await patchSkillTreeMarkdownFiles(
+    path.join(companionPath, ".opencode", "skills", name),
+    transform,
+    new Set(options.excludeFiles ?? []),
+  );
+}
+
+/**
+ * Strip a foreign heading section from the OpenCode guidance surfaces: the
+ * shared root AGENTS.md, the per-provider `.opencode/AGENTS.md`, and — when
+ * syncing from a linked repo — the repo-level AGENTS.md. With
+ * `guardSharedFile`, the shared root file is left alone while another active
+ * runtime (Claude) still uses it.
+ */
+export async function stripOpenCodeForeignSections(
+  companionPath: string,
+  options: RemoveHeadingSectionOptions & {
+    repoPath?: string;
+    guardSharedFile?: { activeProviders: string[] };
+  },
+): Promise<void> {
+  const sharedWithActive = options.guardSharedFile?.activeProviders.includes("claude") ?? false;
+  if (!sharedWithActive) {
+    await stripSectionFromFile(path.join(companionPath, "AGENTS.md"), options);
+  }
+  await stripSectionFromFile(path.join(companionPath, ".opencode", "AGENTS.md"), options);
+  if (options.repoPath) {
+    await stripSectionFromFile(path.join(options.repoPath, "AGENTS.md"), options);
   }
-  return {
-    type: "local",
-    command: [descriptor.command ?? "", ...(descriptor.args ?? [])].filter(Boolean),
-    ...(descriptor.env ? { environment: descriptor.env } : {}),
-    enabled: true,
-  };
 }
 
-// Reconcile a single Mate-managed MCP server in `.opencode/opencode.json`
-// while preserving every unrelated key. `entry: null` removes the server.
-async function updateCompanionOpenCodeMcpServer(
+/**
+ * Remove plugin entries matching `isForeign` from `opencode.json`. A config
+ * left empty is deleted; malformed configs are left untouched.
+ */
+export async function removeOpenCodeForeignPluginReferences(
   companionPath: string,
-  name: string,
-  entry: Record<string, unknown> | null,
+  isForeign: (entry: unknown) => boolean,
 ): Promise<void> {
   const configPath = getCompanionOpenCodeConfigPath(companionPath);
-  let existing: Record<string, unknown> = {};
-  let present = false;
+  let raw: string;
   try {
-    const parsed = JSON.parse(await fs.readFile(configPath, "utf8")) as unknown;
-    if (isRecord(parsed)) {
-      existing = parsed;
-      present = true;
+    raw = await fs.readFile(configPath, "utf8");
+  } catch {
+    return;
+  }
+  try {
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    if (Array.isArray(parsed.plugin)) {
+      setOpenCodePluginReferences(
+        parsed,
+        parsed.plugin.filter((entry) => !isForeign(entry)),
+      );
+    }
+    if (Object.keys(parsed).length === 0) {
+      await fs.unlink(configPath);
+    } else {
+      await writeOpenCodeConfig(configPath, parsed);
     }
   } catch {
-    // Absent or unparseable — start from an empty object.
+    // JSON parse error — leave file untouched
   }
-  if (entry === null && !present) return;
-
-  const mcp: Record<string, unknown> = isRecord(existing.mcp) ? { ...existing.mcp } : {};
-  if (entry === null) {
-    if (!(name in mcp)) return;
-    delete mcp[name];
-  } else {
-    mcp[name] = entry;
+}
+
+// ---------------------------------------------------------------------------
+// Runtime Surface reconciliation: apply/remove declared Capability
+// contributions (spec: runtime-surface). Managed identity: named MCP servers,
+// `isManagedReference` for plugin entries, managed guidance blocks, and named
+// skill trees.
+// ---------------------------------------------------------------------------
+
+const OPENCODE_CONTRIBUTION_CONFIG_FILES = ["opencode.json", "tui.json"];
+
+export async function reconcileOpenCodeContributions(
+  ctx: SetupContext,
+  inputs: CapabilityContributionInput[],
+): Promise<void> {
+  const { companionPath } = ctx;
+
+  if (ctx.scope === "hub") {
+    await reconcileOpenCodeMcpContributions(ctx, inputs);
+    await reconcileOpenCodeAgentDefinitionContributions(ctx, inputs);
+    return;
+  }
+
+  await reconcileOpenCodeMcpContributions(ctx, inputs);
+  await reconcileOpenCodeAgentDefinitionContributions(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) {
+        const configPath = path.join(companionPath, ".opencode", name);
+        const { present, config } = await readOpenCodeConfig(configPath);
+        if (!input.enabled && !present) continue;
+        const preserved = getOpenCodePluginReferences(config).filter(
+          (entry) => !pluginReference.isManagedReference(entry),
+        );
+        setOpenCodePluginReferences(
+          config,
+          input.enabled ? [...preserved, pluginReference.reference] : preserved,
+        );
+        await writeOpenCodeConfig(configPath, config);
+      }
+    }
+
+    // Guidance sections are managed blocks in AGENTS.md. Capability disable
+    // strips them here; runtime teardown of the shared AGENTS.md is guarded in
+    // the provider teardown paths (kept while another active runtime uses it).
+    const guidancePath = path.join(companionPath, "AGENTS.md");
+    const sections = input.enabled ? (input.contributions.guidanceSections ?? []) : [];
+    const keepKeys = new Set<string>();
+    for (const section of sections) {
+      const blockKey = instructionBlockKey(input.pluginId, section.content);
+      keepKeys.add(blockKey);
+      await upsertManagedBlock(guidancePath, FRAMEWORK_NAME, blockKey, section.content);
+    }
+    if ((input.contributions.guidanceSections ?? []).length > 0) {
+      await removeManagedBlocksForPlugin(guidancePath, FRAMEWORK_NAME, input.pluginId, keepKeys);
+    }
+
+    for (const skillTree of input.contributions.skillTrees ?? []) {
+      const skillDir = path.join(companionPath, ".opencode", "skills", skillTree.name);
+      if (input.enabled) {
+        await mergeDir(skillTree.sourceDir, skillDir);
+      } else {
+        await fs.rm(skillDir, { recursive: true, force: true });
+        await pruneEmptyAncestors(path.join(companionPath, ".opencode", "skills"), companionPath);
+      }
+    }
   }
+}
 
-  const next = { ...existing };
-  if (Object.keys(mcp).length > 0) {
-    next.mcp = mcp;
-  } else {
-    delete next.mcp;
+/** 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,
+      );
+    }
+  }
+}
+
+/**
+ * Reconcile declared agent definition files under `.opencode/agents/`. Runs
+ * in both companion and hub scope — an agent definition is fully
+ * self-contained (no shared-file merge), so it needs no companion-only
+ * surface.
+ */
+async function reconcileOpenCodeAgentDefinitionContributions(
+  ctx: SetupContext,
+  inputs: CapabilityContributionInput[],
+): Promise<void> {
+  const agentsDir = path.join(ctx.companionPath, ".opencode", "agents");
+  for (const input of inputs) {
+    for (const agent of input.contributions.agentDefinitions ?? []) {
+      const agentPath = path.join(agentsDir, `${agent.name}.md`);
+      if (input.enabled) {
+        await fs.mkdir(agentsDir, { recursive: true });
+        await fs.writeFile(agentPath, agent.content, "utf8");
+      } else {
+        await fs.rm(agentPath, { force: true });
+        await pruneEmptyAncestors(agentsDir, ctx.companionPath);
+      }
+    }
   }
-  await fs.mkdir(path.dirname(configPath), { recursive: true });
-  await fs.writeFile(configPath, JSON.stringify(next, null, 2) + "\n", "utf8");
 }
 
 export function createOpenCodePlugin(): ProviderPlugin {
@@ -387,15 +531,19 @@ export function createOpenCodePlugin(): ProviderPlugin {
     isEnabled: (config) => (config.allowedAgents ?? []).includes("opencode"),
     hosting: {
       mcp: {
-        async register(ctx: SetupContext, descriptor: McpServerDescriptor) {
-          await updateCompanionOpenCodeMcpServer(
-            ctx.companionPath,
+        async register(ctx: SetupContext, descriptor) {
+          await updateOpenCodeMcpServer(
+            getCompanionOpenCodeConfigPath(ctx.companionPath),
             descriptor.name,
-            opencodeMcpEntry(descriptor),
+            toOpenCodeMcpEntry(descriptor),
           );
         },
         async unregister(ctx: SetupContext, name: string) {
-          await updateCompanionOpenCodeMcpServer(ctx.companionPath, name, null);
+          await updateOpenCodeMcpServer(
+            getCompanionOpenCodeConfigPath(ctx.companionPath),
+            name,
+            null,
+          );
         },
       },
       instructions: {
@@ -403,6 +551,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/providers/skill-tree.ts

@@ -0,0 +1,38 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+// Escape-hatch support: patch markdown files of a skill tree that an external
+// CLI wrote into a runtime directory (SKILL.md plus references/*.md).
+// Directory-driven so reference files added by future releases are covered.
+
+async function patchMarkdownFile(
+  filePath: string,
+  transform: (content: string) => string,
+): Promise<void> {
+  let content: string;
+  try {
+    content = await fs.readFile(filePath, "utf8");
+  } catch {
+    return; // file absent — nothing to patch
+  }
+  const rewritten = transform(content);
+  if (rewritten !== content) await fs.writeFile(filePath, rewritten, "utf8");
+}
+
+export async function patchSkillTreeMarkdownFiles(
+  skillDir: string,
+  transform: (content: string) => string,
+  excludeFiles: ReadonlySet<string> = new Set(),
+): Promise<void> {
+  await patchMarkdownFile(path.join(skillDir, "SKILL.md"), transform);
+
+  const refsDir = path.join(skillDir, "references");
+  let entries: string[];
+  try {
+    entries = await fs.readdir(refsDir);
+  } catch {
+    return; // no references/ dir
+  }
+  const targets = entries.filter((name) => name.endsWith(".md") && !excludeFiles.has(name));
+  await Promise.all(targets.map((name) => patchMarkdownFile(path.join(refsDir, name), transform)));
+}

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.