@uniqbit/mate-core 0.15.5 → 0.16.0-canary.1

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

@@ -31,6 +31,9 @@ import {
 
 // Storage contract: <companionPath>/.graphify/<repositoryId>/graphify-out/
 export const GRAPHIFY_STORE_SEGMENT = ".graphify";
+
+/** Skill tree the external `graphify install` CLI writes into a runtime directory. */
+export const GRAPHIFY_SKILL_NAME = "graphify";
 export const GRAPHIFY_OUTPUT_SUBDIR = "graphify-out";
 
 const GRAPHIFY_INSTALL_CMD = `uv tool install graphifyy`;
@@ -271,9 +274,12 @@ export function createGraphifyPlugin(deps: GraphifyPluginDeps = {}): CapabilityP
             // every setup/sync so it survives graphifyy regenerating the skill.
             const patchSkillTree =
               providerId === "claude" ? patchClaudeSkillTree : patchOpenCodeSkillTree;
-            await patchSkillTree(ctx.companionPath, "graphify", rewriteGraphifySkillOutputPaths, {
-              excludeFiles: GRAPHIFY_SKILL_REWRITE_EXCLUDE,
-            });
+            await patchSkillTree(
+              ctx.companionPath,
+              GRAPHIFY_SKILL_NAME,
+              rewriteGraphifySkillOutputPaths,
+              { excludeFiles: GRAPHIFY_SKILL_REWRITE_EXCLUDE },
+            );
           },
 
           async teardown(ctx: SetupContext) {
@@ -282,10 +288,13 @@ export function createGraphifyPlugin(deps: GraphifyPluginDeps = {}): CapabilityP
             // Remove the Graphify-managed skills directory (written by the
             // external CLI, so removed here rather than via a declaration).
             try {
-              await fs.rm(path.join(ctx.companionPath, providerDir, "skills", "graphify"), {
-                recursive: true,
-                force: true,
-              });
+              await fs.rm(
+                path.join(ctx.companionPath, providerDir, "skills", GRAPHIFY_SKILL_NAME),
+                {
+                  recursive: true,
+                  force: true,
+                },
+              );
             } catch {
               /* not present */
             }

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

@@ -32,14 +32,17 @@ export const OPENSPEC_SKILLS = [
   "openspec-archive-change",
 ] as const;
 
-// Mate-authored skills (not generated by the openspec CLI) that ship alongside the
-// openspec workflow skills and are installed per active provider.
-const LEGACY_CLAUDE_STATE_PATTERN = /^mate-artifact-finish\..+\.json$/;
+// Mate-authored skills (not generated by the openspec CLI) are sourced from the
+// shared Mate skill tree and installed per active provider while OpenSpec is enabled.
 
-const MATE_V1_SCHEMA_SOURCE = path.join(
+/** Every Mate-owned schema is installed for availability; only one is ever activated as the companion default. */
+const MATE_SCHEMA_NAMES = ["mate-v1", "mate-minimal"] as const;
+
+const MATE_SCHEMA_SOURCE_ROOT = path.join(
   import.meta.dirname,
-  "../../../templates/capabilities/openspec-cap/mate-v1",
+  "../../../templates/capabilities/openspec-cap",
 );
+const MATE_CONVENTIONS_SOURCE = path.join(MATE_SCHEMA_SOURCE_ROOT, "openspec-conventions.yaml");
 
 const OPENSPEC_TOOL_DIRS = {
   claude: ".claude",
@@ -57,6 +60,7 @@ export interface OpenSpecPluginDeps {
   isCommandOnPath?: typeof isCommandOnPath;
   confirm?: typeof confirm;
   pathValue?: () => string;
+  wrapperBinPath?: () => string;
   getInstalledVersion?: (pathValue: string) => Promise<string | undefined>;
   fetchLatestVersion?: () => Promise<string | undefined>;
 }
@@ -95,8 +99,12 @@ function getOpenSpecConfigPath(companionPath: string): string {
   return path.join(companionPath, "openspec", "config.yaml");
 }
 
-function getMateV1SchemaDir(companionPath: string): string {
-  return path.join(companionPath, "openspec", "schemas", "mate-v1");
+function getMateSchemaDir(companionPath: string, schemaName: string): string {
+  return path.join(companionPath, "openspec", "schemas", schemaName);
+}
+
+function getMateConventionsPath(companionPath: string): string {
+  return path.join(companionPath, "openspec", "mate-conventions.yaml");
 }
 
 export async function teardownOpenspecSkills(
@@ -154,21 +162,15 @@ async function reconcileOpenSpecTools(
 
   // The openspec CLI generates its own workflow skills above; layer the
   // mate-authored skills on top for the same active providers.
-  if (ctx.config.git === "auto") {
-    await applyMateOpenspecSkills(ctx.companionPath, tools);
-  } else {
-    for (const tool of tools) {
-      await teardownMateSkills(getSkillsDir(ctx.companionPath, tool), ctx.companionPath);
-    }
-  }
+  await applyMateOpenspecSkills(ctx.companionPath, tools);
 }
 
-async function warnIfOpenSpecOutdated(
+async function updateOpenSpecIfOutdated(
   ctx: SetupContext,
   deps: Required<
     Pick<
       OpenSpecPluginDeps,
-      "installCommand" | "confirm" | "pathValue" | "getInstalledVersion" | "fetchLatestVersion"
+      "installCommand" | "pathValue" | "getInstalledVersion" | "fetchLatestVersion"
     >
   >,
 ): Promise<void> {
@@ -178,21 +180,9 @@ async function warnIfOpenSpecOutdated(
   const latest = await deps.fetchLatestVersion();
   if (!latest || !isNewer(latest, installed)) return;
 
-  if (ctx.mode !== "setup") {
-    process.stderr.write(
-      `openspec: installed version ${installed} is outdated (latest ${latest}). Run \`${OPENSPEC_INSTALL_COMMAND}\` to upgrade.\n`,
-    );
-    return;
-  }
-
   process.stdout.write(
-    `openspec: installed version ${installed} is outdated (latest ${latest}).\n  ${OPENSPEC_INSTALL_COMMAND}\n`,
+    `openspec: installed version ${installed} is outdated (latest ${latest}). Updating now:\n  ${OPENSPEC_INSTALL_COMMAND}\n`,
   );
-  const ok = await deps.confirm("Upgrade openspec now?");
-  if (!ok) {
-    process.stderr.write("openspec: upgrade skipped - continuing with the installed version\n");
-    return;
-  }
 
   try {
     await deps.installCommand("npm", ["install", "-g", "@fission-ai/openspec@latest"], {
@@ -218,7 +208,7 @@ async function ensureOpenSpecInstalled(
   >,
 ): Promise<boolean> {
   if (deps.isCommandOnPath("openspec", deps.pathValue())) {
-    await warnIfOpenSpecOutdated(ctx, deps);
+    await updateOpenSpecIfOutdated(ctx, deps);
     return true;
   }
 
@@ -266,11 +256,8 @@ async function ensureOpenSpecInstalled(
   return true;
 }
 
-async function teardownOpenSpecSchema(companionPath: string): Promise<void> {
-  const schemaDir = getMateV1SchemaDir(companionPath);
-  await fs.rm(schemaDir, { recursive: true, force: true });
-  await pruneEmptyAncestors(schemaDir, companionPath);
-
+/** Only the config Mate itself wrote is removed; a user-edited config.yaml is left alone. */
+async function removeManagedOpenSpecConfig(companionPath: string): Promise<void> {
   const configPath = getOpenSpecConfigPath(companionPath);
   try {
     const content = await fs.readFile(configPath, "utf8");
@@ -283,13 +270,39 @@ async function teardownOpenSpecSchema(companionPath: string): Promise<void> {
   }
 }
 
+async function teardownOpenSpecSchema(companionPath: string): Promise<void> {
+  for (const schemaName of MATE_SCHEMA_NAMES) {
+    const schemaDir = getMateSchemaDir(companionPath, schemaName);
+    await fs.rm(schemaDir, { recursive: true, force: true });
+    await pruneEmptyAncestors(schemaDir, companionPath);
+  }
+
+  await fs.rm(getMateConventionsPath(companionPath), { force: true });
+  await removeManagedOpenSpecConfig(companionPath);
+}
+
 async function reconcileOpenSpecSchema(ctx: SetupContext): Promise<void> {
+  await Promise.all(
+    MATE_SCHEMA_NAMES.map((schemaName) =>
+      mergeDir(
+        path.join(MATE_SCHEMA_SOURCE_ROOT, schemaName),
+        getMateSchemaDir(ctx.companionPath, schemaName),
+      ),
+    ),
+  );
+  await fs.rm(
+    path.join(getMateSchemaDir(ctx.companionPath, "mate-v1"), "templates", "explore-brief.md"),
+    { force: true },
+  );
+  await fs.copyFile(MATE_CONVENTIONS_SOURCE, getMateConventionsPath(ctx.companionPath));
+
+  // Availability is unconditional so any change may select a Mate schema;
+  // activation stays opt-in through the companion-level setup selection.
   if (getOpenSpecSchemaSelection(ctx.config.capabilities ?? []) !== "mate-v1") {
-    await teardownOpenSpecSchema(ctx.companionPath);
+    await removeManagedOpenSpecConfig(ctx.companionPath);
     return;
   }
 
-  await mergeDir(MATE_V1_SCHEMA_SOURCE, getMateV1SchemaDir(ctx.companionPath));
   const configPath = getOpenSpecConfigPath(ctx.companionPath);
   await fs.mkdir(path.dirname(configPath), { recursive: true });
 
@@ -310,6 +323,7 @@ export function createOpenspecPlugin(deps: OpenSpecPluginDeps = {}): CapabilityP
     isCommandOnPath: deps.isCommandOnPath ?? isCommandOnPath,
     confirm: deps.confirm ?? confirm,
     pathValue: deps.pathValue ?? (() => process.env.PATH ?? ""),
+    wrapperBinPath: deps.wrapperBinPath ?? getWrapperBinPath,
     getInstalledVersion: deps.getInstalledVersion ?? defaultGetInstalledVersion,
     fetchLatestVersion: deps.fetchLatestVersion ?? defaultFetchLatestVersion,
   };
@@ -333,11 +347,18 @@ export function createOpenspecPlugin(deps: OpenSpecPluginDeps = {}): CapabilityP
             "Skill(openspec-propose)",
             "Skill(openspec-apply-change)",
             "Skill(openspec-archive-change)",
-            "Skill(mate-artifact-finish)",
+            "Skill(mate-artifact-publish)",
             "Skill(mate-openspec-backfill)",
+            "Skill(mate-interview-me)",
+            "Skill(mate-grill-me)",
+            "Skill(mate-grilling)",
+            "Skill(mate-grill-with-docs)",
+            "Skill(mate-domain-modeling)",
+            "Skill(mate-show-me)",
+            "Skill(mate-simplify-code)",
             "Bash(openspec:*)",
             `Bash(${FRAMEWORK_NAME} cap graphify:*)`,
-            `Bash(${path.join(getWrapperBinPath(), "openspec")}:*)`,
+            `Bash(${path.join(depsWithDefaults.wrapperBinPath(), "openspec")}:*)`,
           ],
         },
       };
@@ -375,23 +396,9 @@ export function createOpenspecPlugin(deps: OpenSpecPluginDeps = {}): CapabilityP
     },
     forProvider: {
       claude: {
-        // The archive-finish nudge hook ships in the bundled mate Claude
-        // plugin and self-gates at runtime; openspec no longer contributes a
-        // Claude hook file. Only legacy per-session nudge state is migrated.
-        async apply(ctx: SetupContext) {
-          const stateDir = path.join(ctx.companionPath, ".claude", "state");
-          try {
-            const entries = await fs.readdir(stateDir);
-            await Promise.all(
-              entries
-                .filter((entry) => LEGACY_CLAUDE_STATE_PATTERN.test(entry))
-                .map((entry) => fs.unlink(path.join(stateDir, entry))),
-            );
-            await pruneEmptyAncestors(stateDir, ctx.companionPath);
-          } catch {
-            /* no legacy state */
-          }
-        },
+        // Publication is explicit (`mate-artifact-publish`), so openspec
+        // contributes no archive-triggered Claude hook and no hook state.
+        async apply() {},
         async teardown(ctx: SetupContext) {
           await teardownToolRuntime(ctx.companionPath, "claude");
         },

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

@@ -1,4 +1,5 @@
 import { spawnSync } from "node:child_process";
+import { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 
@@ -10,7 +11,12 @@ export { TOKENSAVE_WORKING_REPO_EXCLUDE_ENTRIES } from "./tokensave-shared";
 
 export const TOKENSAVE_SUPPORTED_AGENTS = new Set(["claude", "opencode"]);
 export const TOKENSAVE_STORE_DIR = ".tokensave";
+export const TOKENSAVE_STORE_CONFIG_FILE = "config.json";
 export const TOKENSAVE_MIN_RUST_VERSION = "1.91.0";
+/** Single-graph posture Mate owns in the per-project store config; every other key is left as found. */
+const TOKENSAVE_OWNED_POSTURE = { auto_track: false, suppress_scope_warning: true } as const;
+const TOKENSAVE_BRANCH_META_FILE = "branch-meta.json";
+const TOKENSAVE_DISABLED_BRANCH_META_FILE = "branch-meta.json.mate-disabled";
 const TOKENSAVE_STORE_EXCLUDE_ENTRY = `${TOKENSAVE_STORE_DIR}/`;
 const TOKENSAVE_BREW_INSTALL_CMD = "brew install aovestdipaperino/tap/tokensave";
 const TOKENSAVE_CARGO_INSTALL_CMD = "cargo install --locked tokensave";
@@ -101,6 +107,21 @@ async function tokensaveInstalled(repoPath: string): Promise<boolean> {
   return result.ok;
 }
 
+/**
+ * Upgrades the installed binary without making setup depend on network
+ * availability. `--kill` keeps the non-interactive setup path from hanging on
+ * a running Tokensave MCP process.
+ */
+async function upgradeTokensave(repoPath: string): Promise<void> {
+  const result = tokensaveDeps.run(["upgrade", "--kill"], repoPath);
+  if (result.ok) return;
+
+  const detail = result.stderr.trim();
+  process.stderr.write(
+    `tokensave: automatic upgrade failed${detail ? `: ${detail}` : ""} - continuing with the installed version\n`,
+  );
+}
+
 // Global agent integration (MCP entry, session hooks, wildcard permission grant, and
 // tokensave's own config bookkeeping) is owned by tokensave's installer — Mate never
 // hand-edits ~/.tokensave/config.toml. Runs in setup mode only; the installer is
@@ -169,8 +190,12 @@ function getTokensaveInstallPlan(): { command: string; run: () => Promise<void>
   return undefined;
 }
 
-export async function ensureTokensaveInstalled(repoPath: string): Promise<boolean> {
+export async function ensureTokensaveInstalled(
+  repoPath: string,
+  options: { upgrade?: boolean } = {},
+): Promise<boolean> {
   if (await tokensaveInstalled(repoPath)) {
+    if (options.upgrade) await upgradeTokensave(repoPath);
     return true;
   }
 
@@ -230,6 +255,90 @@ export async function ensureTokensaveStoreExcluded(repoPath: string): Promise<vo
   await fs.writeFile(excludePath, lines.join("\n") + "\n", "utf8");
 }
 
+/**
+ * Deactivates Tokensave's multi-branch mode without deleting branch databases.
+ * The metadata is preserved in a Mate-owned backup so the migration is reversible.
+ */
+async function deactivateTokensaveBranchMetadata(repoPath: string): Promise<void> {
+  const storePath = path.join(repoPath, TOKENSAVE_STORE_DIR);
+  const branchMetaPath = path.join(storePath, TOKENSAVE_BRANCH_META_FILE);
+  const disabledBranchMetaPath = path.join(storePath, TOKENSAVE_DISABLED_BRANCH_META_FILE);
+
+  let branchMeta: string;
+  try {
+    branchMeta = await fs.readFile(branchMetaPath, "utf8");
+  } catch {
+    return;
+  }
+
+  let removeActiveMetadata = false;
+  try {
+    await fs.copyFile(branchMetaPath, disabledBranchMetaPath, fsConstants.COPYFILE_EXCL);
+    removeActiveMetadata = true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+      return;
+    }
+
+    try {
+      removeActiveMetadata = (await fs.readFile(disabledBranchMetaPath, "utf8")) === branchMeta;
+    } catch {
+      return;
+    }
+  }
+
+  if (removeActiveMetadata) {
+    await fs.unlink(branchMetaPath).catch(() => {});
+  }
+}
+
+/**
+ * Reconciles Mate's single-graph branching posture into the working repo's
+ * git-excluded `.tokensave/config.json` and deactivates existing branch
+ * metadata. Best-effort by design: the file is created by `tokensave init`,
+ * so an absent, unreadable, or unparseable config is left untouched rather
+ * than treated as an error. Existing branch databases are never removed.
+ */
+export async function ensureTokensaveBranchingPosture(repoPath: string): Promise<void> {
+  const configPath = path.join(repoPath, TOKENSAVE_STORE_DIR, TOKENSAVE_STORE_CONFIG_FILE);
+
+  let raw: string;
+  try {
+    raw = await fs.readFile(configPath, "utf8");
+  } catch {
+    return;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return;
+  }
+
+  const next = JSON.stringify(
+    { ...(parsed as Record<string, unknown>), ...TOKENSAVE_OWNED_POSTURE },
+    null,
+    2,
+  );
+  const serialized = `${next}\n`;
+  if (serialized === raw) {
+    await deactivateTokensaveBranchMetadata(repoPath);
+    return;
+  }
+
+  try {
+    await fs.writeFile(configPath, serialized, "utf8");
+  } catch {
+    /** Best-effort: the store config is not Mate's to guarantee. */
+  }
+
+  await deactivateTokensaveBranchMetadata(repoPath);
+}
+
 async function teardownDriver(repoPath: string, providers: string[]) {
   const agents = providers.filter((p) => TOKENSAVE_SUPPORTED_AGENTS.has(p));
   if (agents.length === 0) return;
@@ -325,9 +434,14 @@ export function createTokensavePlugin(): CapabilityPlugin {
       if (ctx.activeProviders.filter((p) => TOKENSAVE_SUPPORTED_AGENTS.has(p)).length === 0) return;
 
       const targetPath = ctx.repoPath ?? ctx.companionPath;
-      if (!(await ensureTokensaveInstalled(targetPath))) {
+      if (
+        !(await ensureTokensaveInstalled(targetPath, {
+          upgrade: ctx.mode === "setup",
+        }))
+      ) {
         return;
       }
+      await ensureTokensaveBranchingPosture(targetPath);
       if (ctx.mode === "setup") {
         installTokensaveAgentIntegrations(ctx.activeProviders, targetPath);
       }

package/src/tools/setup/engine.ts

@@ -1,6 +1,7 @@
 // oxlint-disable no-await-in-loop
 import { getActiveDistribution } from "../../distribution";
 import { FRAMEWORK_NAME } from "../../framework";
+import type { RenderedRuntimeDocument } from "../../lib/orchestrator/projection-types";
 import type { FrameworkConfig } from "../../lib/orchestrator/types";
 import { collectHostingProviders, ContextServiceMediator } from "./context-services";
 import type {
@@ -12,6 +13,7 @@ import type {
 } from "./plugin";
 import { reconcileClaudeContributions } from "./providers/claude";
 import { reconcileOpenCodeContributions } from "./providers/opencode";
+import { renderDocumentsForTarget } from "./runtime-documents";
 import { normalizeRegistration, type NormalizedRegistration } from "./registry";
 
 export interface SetupInstallationPlanAction {
@@ -189,16 +191,14 @@ const RUNTIME_SURFACE_RECONCILERS: Record<
 };
 
 /**
- * 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.
+ * The declared Capability contributions of one pass, keyed by runtime. Shared
+ * by both targets: what a companion pass writes is what a working pass renders.
  */
-async function reconcileCapabilityContributions(
+async function collectContributionInputs(
   ctx: SetupContext,
   plugins: Plugin[],
   plan: SetupInstallationPlan,
-): Promise<void> {
+): Promise<Map<string, CapabilityContributionInput[]>> {
   // The plan already resolved enablement (policy, saved selection, package
   // manager requirements); mirror it instead of recomputing.
   const enabledByPluginId = new Map(
@@ -225,10 +225,38 @@ async function reconcileCapabilityContributions(
       inputsByRuntime.set(runtimeId, inputs);
     }
   }
+  return inputsByRuntime;
+}
 
+/**
+ * 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> {
+  const inputsByRuntime = await collectContributionInputs(ctx, plugins, plan);
   for (const [runtimeId, inputs] of inputsByRuntime) {
     const reconcile = RUNTIME_SURFACE_RECONCILERS[runtimeId];
     if (!reconcile || inputs.length === 0) continue;
     await reconcile(ctx, inputs);
   }
 }
+
+/**
+ * The same declarations, rendered rather than written: a working-target pass
+ * produces the documents and the Projection Root places them, so no Runtime
+ * Surface reaches inside a Working Repository.
+ */
+export async function renderRuntimeDocuments(
+  ctx: SetupContext,
+  registrations: PluginRegistration[],
+  plan: SetupInstallationPlan,
+): Promise<RenderedRuntimeDocument[]> {
+  const plugins = registrations.map((entry) => normalizeRegistration(entry).plugin);
+  return renderDocumentsForTarget(ctx, await collectContributionInputs(ctx, plugins, plan));
+}

package/src/tools/setup/mate.ts

@@ -3,18 +3,22 @@ import path from "node:path";
 
 import { pruneEmptyAncestors } from "./utils";
 
-export const MATE_ARTIFACT_SKILLS = ["mate-artifact-finish"] as const;
+export const MATE_ARTIFACT_SKILLS = ["mate-artifact-publish"] as const;
 export const MATE_SKILLS = [
-  "mate-artifact-finish",
+  "mate-artifact-publish",
   "mate-create-report",
   "mate-openspec-backfill",
+  "mate-interview-me",
+  "mate-grill-me",
+  "mate-grilling",
+  "mate-grill-with-docs",
+  "mate-domain-modeling",
+  "mate-show-me",
+  "mate-simplify-code",
 ] as const;
-const LEGACY_MATE_SKILLS = ["mate-openspec-artifact-finish"] as const;
+const LEGACY_MATE_SKILLS = ["mate-artifact-finish", "mate-openspec-artifact-finish"] as const;
 
-const MATE_SKILLS_SOURCE = path.join(
-  import.meta.dirname,
-  "../../templates/capabilities/openspec-cap/mate-skills",
-);
+const MATE_SKILLS_SOURCE = path.join(import.meta.dirname, "../../templates/mate-skills");
 
 const MATE_CREATE_REPORT_SKILL = `---
 name: mate-create-report
@@ -55,7 +59,27 @@ Write a JSON document with this shape:
 }
 \`\`\`
 
-Supported section types are \`metadata\`, \`metrics\`, \`key-value\`, \`table\`, \`statuses\`, and \`text\`. Use only strings, numbers, booleans, and null values. Section IDs must be unique. Validate required fields before invoking the CLI.
+Supported section types are \`metadata\`, \`metrics\`, \`key-value\`, \`table\`, \`statuses\`, \`text\`, \`diagram\`, and \`diff\`. Use only strings, numbers, booleans, and null values. Section IDs must be unique. Validate required fields before invoking the CLI.
+
+## Visual Sections
+
+A \`diagram\` section carries exactly one payload. \`mermaid\` holds diagram source the report draws as a picture; \`text\` holds a monospace ASCII sketch or pseudocode block, kept with its line breaks and indentation. Supplying both payloads or neither fails validation.
+
+\`\`\`json
+{ "id": "structure", "title": "Structure", "type": "diagram", "mermaid": "classDiagram\\n  Report --> Renderer" }
+\`\`\`
+
+\`\`\`json
+{ "id": "sketch", "title": "Sketch", "type": "diagram", "text": "root\\n  child" }
+\`\`\`
+
+A \`diff\` section carries a unified diff patch as produced by \`git diff\`. The report groups it by file, marks added, removed, and context lines, and keeps those markings legible in print. An empty patch renders an explicit no-data message.
+
+\`\`\`json
+{ "id": "changes", "title": "Changes", "type": "diff", "patch": "diff --git a/src/acme.ts b/src/acme.ts\\n..." }
+\`\`\`
+
+A report carrying a mermaid payload inlines the diagram runtime; a report without one does not. Either way the page stays a single self-contained file that makes no network request.
 
 ## Invocation
 
@@ -87,10 +111,8 @@ 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.
+ * own behavior, falling back to `agents/<skill>/` — the shared default every
+ * other tool uses.
  */
 async function resolveMateSkillSource(skill: string, tool: string): Promise<string> {
   const providerDir = path.join(MATE_SKILLS_SOURCE, tool, skill);
@@ -98,8 +120,15 @@ async function resolveMateSkillSource(skill: string, tool: string): Promise<stri
     await fs.access(providerDir);
     return providerDir;
   } catch {
-    return path.join(MATE_SKILLS_SOURCE, DEFAULT_MATE_SKILLS_BUCKET, skill);
+    const sharedDir = path.join(MATE_SKILLS_SOURCE, DEFAULT_MATE_SKILLS_BUCKET, skill);
+    try {
+      await fs.access(sharedDir);
+      return sharedDir;
+    } catch {
+      /* source is missing */
+    }
   }
+  throw new Error(`Mate skill source not found: ${skill}`);
 }
 
 export async function applyMateSkills(skillsDir: string, tool: string): Promise<void> {

package/src/tools/setup/plugin.ts

@@ -4,6 +4,13 @@ import type { ClaudeHookGroup } from "./providers/claude-format";
 
 export type SetupScope = "companion" | "hub";
 
+/**
+ * Where a reconcile pass lands its documents. `companion` writes the material's
+ * own repository; `working` renders the documents an Agent Runtime discovers by
+ * its own upward walk and leaves the placing to the Projection Root.
+ */
+export type ProjectionTarget = "companion" | "working";
+
 export interface SetupContext {
   companionPath: string;
   config: FrameworkConfig;
@@ -13,6 +20,8 @@ export interface SetupContext {
   scope?: SetupScope;
   /** Working repository path when syncing from a linked repo (e.g. during launch). */
   repoPath?: string;
+  /** Defaults to `companion`, so a caller that names no target is unchanged. */
+  target?: ProjectionTarget;
   /**
    * Provider-mediated context services. Always populated when the engine
    * executes a plugin; optional so hand-built contexts (tests, direct calls)

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

@@ -104,8 +104,18 @@ export async function refreshFromTemplate(
 
   remaining = removeGraphifySection(remaining).trimEnd();
 
+  const template = templateContent.trimEnd();
+  /**
+   * A template carrying no managed markers cannot be stripped by marker above,
+   * so without this it would be prepended again on every refresh. Consuming
+   * every leading copy also heals a file an earlier refresh already grew.
+   */
+  while (template && remaining.startsWith(template)) {
+    remaining = remaining.slice(template.length).trimStart();
+  }
+
   const sections = [
-    templateContent.trimEnd(),
+    template,
     ...(normalizedOptions.appendSections ?? []).map((section) => section.trim()).filter(Boolean),
   ];
   if (remaining) {