@uniqbit/mate-core 0.18.4 → 1.0.0-canary.0

package/src/tools/setup/engine.ts

@@ -2,28 +2,29 @@
 import { getActiveDistribution } from "../../distribution";
 import { FRAMEWORK_NAME } from "../../framework";
 import type { FrameworkConfig } from "../../lib/orchestrator/types";
-import type { RenderedRuntimeDocument } from "../../runtime/runtime-document-manifest";
+import { getClaudePluginRoot } from "../../lib/package-paths";
+import type { RenderedRuntimeDocuments } from "../../runtime/runtime-document-manifest";
 import { collectHostingProviders, ContextServiceMediator } from "./context-services";
-import {
-  ledgerFromInputs,
-  ledgerTeardownInput,
-  readContributionLedger,
-  writeContributionLedger,
-  type ContributionLedger,
-} from "./contribution-ledger";
 import type {
   CapabilityContributionInput,
   CapabilityPlugin,
   Plugin,
   PluginRegistration,
+  RuntimeContributionsByRuntime,
   SetupContext,
 } from "./plugin";
-import { reconcileClaudeContributions } from "./providers/claude";
-import { reconcileOpenCodeContributions } from "./providers/opencode";
-import { mergeCompanionOpenCodeConfig, renderDocumentsForTarget } from "./runtime-documents";
+import { reconcileClaudeContributions, renderClaudeWorkingDocuments } from "./providers/claude";
+import {
+  inspectClaudePluginFolders,
+  publishClaudePluginFolders,
+  type ClaudePluginFolders,
+} from "./providers/claude-plugin-folders";
+import {
+  reconcileOpenCodeContributions,
+  renderOpenCodeWorkingDocuments,
+} from "./providers/opencode";
 import { normalizeRegistration, type NormalizedRegistration } from "./registry";
-import { surfaceRoot } from "./surface-target";
-import { removeForeignGuidanceBlocks, sweepAudienceDeclarations } from "./upgrade-sweep";
+import { projectionRepoRoot } from "./surface-target";
 
 export interface SetupInstallationPlanAction {
   phase: Plugin["kind"];
@@ -42,25 +43,18 @@ export interface SetupInstallationOutcome {
   executedActions: SetupInstallationPlanAction[];
   skippedActions: SetupInstallationPlanAction[];
   warnings: string[];
-}
-
-/**
- * The registrations a pass that writes a persisted surface may reconcile:
- * base only. An audience registration takes part in no such pass — neither
- * its lifecycle hooks nor its declared contributions — whatever audience is
- * active; its contributions reach sessions only through the launch layer.
- */
-export function persistedRegistrations(
-  registrations: PluginRegistration[],
-): NormalizedRegistration[] {
-  return registrations.map(normalizeRegistration).filter((entry) => entry.audience === null);
+  /**
+   * Enabled Capabilities' Claude plugin folders, published outside a hub (a hub
+   * has no wrap for plain sessions to load them through); never printed here.
+   */
+  claudePluginFolders: ClaudePluginFolders;
 }
 
 export function buildSetupInstallationPlan(
   config: FrameworkConfig,
   registrations: PluginRegistration[],
 ): SetupInstallationPlan {
-  const entries = persistedRegistrations(registrations);
+  const entries = registrations.map(normalizeRegistration);
   // Required plugins are always treated as enabled: saved selections cannot
   // deselect them and deselection never produces a teardown action.
   const isEntryEnabled = (entry: NormalizedRegistration) =>
@@ -130,7 +124,7 @@ export async function executeSetupInstallationPlan(
   registrations: PluginRegistration[],
   plan: SetupInstallationPlan,
 ): Promise<SetupInstallationOutcome> {
-  const plugins = persistedRegistrations(registrations).map((entry) => entry.plugin);
+  const plugins = registrations.map((entry) => normalizeRegistration(entry).plugin);
   const pluginById = new Map(plugins.map((plugin) => [plugin.id, plugin]));
   const executedActions: SetupInstallationPlanAction[] = [];
   const skippedActions: SetupInstallationPlanAction[] = [];
@@ -197,22 +191,19 @@ export async function executeSetupInstallationPlan(
 
   await mediator.finalize();
 
-  const reconcileWarnings = await reconcileCapabilityContributions(
-    ctx,
-    plugins,
-    plan,
-    registrations.map(normalizeRegistration),
-  );
-  for (const warning of reconcileWarnings) {
-    warnings.push(warning);
-    process.stderr.write(`${warning}\n`);
-  }
+  const inputsByRuntime = await reconcileCapabilityContributions(ctx, plugins, plan);
+  const claudeInputs = inputsByRuntime.get("claude") ?? [];
+  const folderOptions = { bundledPluginRoot: getClaudePluginRoot() };
+  const claudePluginFolders =
+    ctx.scope === "hub"
+      ? await inspectClaudePluginFolders(claudeInputs, folderOptions)
+      : await publishClaudePluginFolders(claudeInputs, folderOptions);
 
-  return { executedActions, skippedActions, warnings };
+  return { executedActions, skippedActions, warnings, claudePluginFolders };
 }
 
 // The Runtime Surface of each active Agent Runtime, by runtime id.
-export const RUNTIME_SURFACE_RECONCILERS: Record<
+const RUNTIME_SURFACE_RECONCILERS: Record<
   string,
   (ctx: SetupContext, inputs: CapabilityContributionInput[]) => Promise<void>
 > = {
@@ -220,6 +211,18 @@ export const RUNTIME_SURFACE_RECONCILERS: Record<
   opencode: reconcileOpenCodeContributions,
 };
 
+/**
+ * The working-target render of each Runtime Surface, by runtime id, in the
+ * order its documents are rendered.
+ */
+const RUNTIME_SURFACE_WORKING_RENDERERS: Record<
+  string,
+  (ctx: SetupContext, inputs: CapabilityContributionInput[]) => Promise<RenderedRuntimeDocuments>
+> = {
+  claude: renderClaudeWorkingDocuments,
+  opencode: renderOpenCodeWorkingDocuments,
+};
+
 /**
  * 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.
@@ -228,6 +231,7 @@ async function collectContributionInputs(
   ctx: SetupContext,
   plugins: Plugin[],
   plan: SetupInstallationPlan,
+  onContributionError?: ContributionErrorHandler,
 ): Promise<Map<string, CapabilityContributionInput[]>> {
   // The plan already resolved enablement (policy, saved selection, package
   // manager requirements); mirror it instead of recomputing.
@@ -243,7 +247,14 @@ async function collectContributionInputs(
     const capability = plugin as CapabilityPlugin;
     if (!capability.getRuntimeContributions) continue;
     const enabled = enabledByPluginId.get(capability.id) ?? false;
-    const byRuntime = await capability.getRuntimeContributions(ctx);
+    let byRuntime: RuntimeContributionsByRuntime;
+    try {
+      byRuntime = await capability.getRuntimeContributions(ctx);
+    } catch (error) {
+      if (!onContributionError) throw error;
+      onContributionError(capability.id, error);
+      continue;
+    }
     for (const [runtimeId, contributions] of Object.entries(byRuntime)) {
       if (!contributions) continue;
       // Inactive runtimes still reconcile — with everything disabled — so a
@@ -267,143 +278,77 @@ async function collectContributionInputs(
  * 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.
+ * `enabled: false` and drive teardown of their managed entries. Returns the
+ * inputs it reconciled, so the pass derives launch-only data from the same ones.
  */
 async function reconcileCapabilityContributions(
   ctx: SetupContext,
   plugins: Plugin[],
   plan: SetupInstallationPlan,
-  registrations: NormalizedRegistration[],
-): Promise<string[]> {
+): Promise<Map<string, CapabilityContributionInput[]>> {
   const inputsByRuntime = await collectContributionInputs(ctx, plugins, plan);
-  const ledgerRoot = surfaceRoot(ctx);
-  const ledger = await readContributionLedger(ledgerRoot);
-  const warnings: string[] = [];
-  let unswept = ledger?.unswept ?? [];
-  if (!ledger || unswept.length > 0) {
-    if (!ledger) {
-      await removeForeignGuidanceBlocks(ledgerRoot, new Set(plugins.map((plugin) => plugin.id)));
-    }
-    const sweep = await sweepAudienceDeclarations(ctx, {
-      registrations,
-      ...(ledger ? { packages: new Set(unswept) } : {}),
-    });
-    prependTeardown(inputsByRuntime, sweep.teardown);
-    unswept = sweep.unswept;
-    warnings.push(...sweep.warnings);
-  }
-  prependLedgerTeardown(inputsByRuntime, ledger);
   for (const [runtimeId, inputs] of inputsByRuntime) {
     const reconcile = RUNTIME_SURFACE_RECONCILERS[runtimeId];
     if (!reconcile || inputs.length === 0) continue;
     await reconcile(ctx, inputs);
   }
-  await writeContributionLedger(ledgerRoot, ledgerFromInputs(inputsByRuntime, unswept));
-  return warnings;
-}
-
-/**
- * Disabled inputs placed first, skipping any owner that is an enabled input
- * of the pass on that runtime: removal runs before enabled inputs apply.
- */
-function prependTeardown(
-  inputsByRuntime: Map<string, CapabilityContributionInput[]>,
-  teardownByRuntime: ReadonlyMap<string, readonly CapabilityContributionInput[]>,
-): void {
-  for (const [runtimeId, teardown] of teardownByRuntime) {
-    const inputs = inputsByRuntime.get(runtimeId) ?? [];
-    const enabled = new Set(inputs.filter((input) => input.enabled).map((input) => input.pluginId));
-    const kept = teardown.filter((input) => !enabled.has(input.pluginId));
-    if (kept.length > 0) inputsByRuntime.set(runtimeId, [...kept, ...inputs]);
-  }
+  return inputsByRuntime;
 }
 
-/**
- * Every recorded owner that is not an enabled input of this pass, as a
- * disabled input placed first: its entries are removed before enabled inputs
- * apply, so an identity another plugin still declares is re-applied after.
- * Entries the ledger does not record are never named, so they survive.
- */
-function prependLedgerTeardown(
-  inputsByRuntime: Map<string, CapabilityContributionInput[]>,
-  ledger: ContributionLedger | null,
-): void {
-  prependTeardown(
-    inputsByRuntime,
-    new Map(
-      Object.entries(ledger?.runtimes ?? {}).map(([runtimeId, owners]) => [
-        runtimeId,
-        Object.entries(owners).map(([owner, identities]) => ledgerTeardownInput(owner, identities)),
-      ]),
-    ),
-  );
-}
+/** Receives one Capability's rejected contributions; that Capability then contributes nothing. */
+export type ContributionErrorHandler = (capabilityId: string, error: unknown) => void;
 
 /**
- * The declared contributions of one audience's plugins, as enabled inputs per
- * active runtime. No plugin phase and no lifecycle hook runs: an audience
- * plugin contributes declaratively only. OpenCode plugin references are
- * dropped — the Mate plugin has no way to load another plugin.
+ * One pass's declared Capability contributions by runtime, collected without a
+ * reconcile. A rejecting Capability fails the collection unless
+ * `onContributionError` takes its error; only diagnostics should pass one.
  */
-export async function collectAudienceInputs(
+export async function collectRuntimeContributionInputs(
   ctx: SetupContext,
   registrations: PluginRegistration[],
-  audience: string,
+  plan: SetupInstallationPlan,
+  onContributionError?: ContributionErrorHandler,
 ): Promise<Map<string, CapabilityContributionInput[]>> {
-  const inputsByRuntime = new Map<string, CapabilityContributionInput[]>();
-  for (const entry of registrations.map(normalizeRegistration)) {
-    if (entry.audience !== audience || entry.plugin.kind !== "capability") continue;
-    const capability = entry.plugin as CapabilityPlugin;
-    if (!capability.getRuntimeContributions) continue;
-    if (entry.policy !== "required" && !capability.isEnabled(ctx.config)) continue;
-    const byRuntime = await capability.getRuntimeContributions(ctx);
-    for (const [runtimeId, contributions] of Object.entries(byRuntime)) {
-      if (!contributions || !ctx.activeProviders.includes(runtimeId)) continue;
-      const { pluginReferences: _dropped, ...declarative } = contributions;
-      const inputs = inputsByRuntime.get(runtimeId) ?? [];
-      inputs.push({
-        pluginId: capability.id,
-        enabled: true,
-        capabilityEnabled: true,
-        contributions: declarative,
-      });
-      inputsByRuntime.set(runtimeId, inputs);
-    }
-  }
-  return inputsByRuntime;
-}
-
-/** What a render returns: its warnings are data for the caller, never printed here. */
-export interface RenderedRuntimeDocuments {
-  documents: RenderedRuntimeDocument[];
-  warnings: string[];
+  const plugins = registrations.map((entry) => normalizeRegistration(entry).plugin);
+  return collectContributionInputs(ctx, plugins, plan, onContributionError);
 }
 
 /**
  * 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.
+ * Surface reaches inside a Working Repository. Refuses before anything renders
+ * when the context has no Working Repository: every document is addressed by it.
+ * Its warnings are data for the caller, never printed here.
  */
 export async function renderRuntimeDocuments(
   ctx: SetupContext,
   registrations: PluginRegistration[],
   plan: SetupInstallationPlan,
-  wrapped?: { audience: string; registrations: PluginRegistration[] },
 ): Promise<RenderedRuntimeDocuments> {
-  const plugins = persistedRegistrations(registrations).map((entry) => entry.plugin);
-  const inputsByRuntime = await collectContributionInputs(ctx, plugins, plan);
-  /** A checkout wrapped for an audience carries it beside base; no other audience ever. */
-  if (wrapped) {
-    const audienceInputs = await collectAudienceInputs(
-      ctx,
-      wrapped.registrations,
-      wrapped.audience,
-    );
-    for (const [runtimeId, inputs] of audienceInputs) {
-      inputsByRuntime.set(runtimeId, [...(inputsByRuntime.get(runtimeId) ?? []), ...inputs]);
-    }
+  projectionRepoRoot(ctx);
+  const inputsByRuntime = await collectRuntimeContributionInputs(ctx, registrations, plan);
+  const rendered: RenderedRuntimeDocuments = { documents: [], warnings: [] };
+  for (const [runtimeId, render] of Object.entries(RUNTIME_SURFACE_WORKING_RENDERERS)) {
+    if (!ctx.activeProviders.includes(runtimeId)) continue;
+    const { documents, warnings } = await render(ctx, inputsByRuntime.get(runtimeId) ?? []);
+    rendered.documents.push(...documents);
+    rendered.warnings.push(...warnings);
   }
-  const documents = renderDocumentsForTarget(ctx, inputsByRuntime);
-  if (ctx.target !== "working") return { documents, warnings: [] };
-  return mergeCompanionOpenCodeConfig(ctx.companionPath, documents);
+  return rendered;
+}
+
+/**
+ * Publishes the enabled Claude plugin folders for a wrap pass, before it
+ * renders: writes Mate's marketplace files and removes those of disabled
+ * Capabilities. Runs no plugin phase.
+ */
+export async function publishRuntimeClaudePluginMarketplaces(
+  ctx: SetupContext,
+  registrations: PluginRegistration[],
+  plan: SetupInstallationPlan,
+): Promise<ClaudePluginFolders> {
+  const inputsByRuntime = await collectRuntimeContributionInputs(ctx, registrations, plan);
+  return publishClaudePluginFolders(inputsByRuntime.get("claude") ?? [], {
+    bundledPluginRoot: getClaudePluginRoot(),
+  });
 }

package/src/tools/setup/managed-output.ts

@@ -0,0 +1,51 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import type {
+  ManagedOutputEntry,
+  ManagedOutputOwner,
+  ManagedOutputRecorder,
+  ManagedOutputReport,
+} from "./plugin";
+
+export interface ManagedOutputCollector {
+  recorder: ManagedOutputRecorder;
+  /** Entries inside the companion, deduplicated, as companion-relative POSIX paths. */
+  report(): ManagedOutputReport;
+}
+
+export function createManagedOutputCollector(companionPath: string): ManagedOutputCollector {
+  const entries: ManagedOutputEntry[] = [];
+  return {
+    recorder: { record: (entry) => entries.push(entry) },
+    report() {
+      const seen = new Set<string>();
+      const report: ManagedOutputEntry[] = [];
+      for (const entry of entries) {
+        const relative = path.relative(companionPath, entry.path);
+        if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) continue;
+        const posix = relative.split(path.sep).join("/");
+        const key = `${entry.change}\0${entry.owner}\0${posix}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        report.push({ ...entry, path: posix });
+      }
+      return report;
+    },
+  };
+}
+
+/** Removes `target` and records it, only when it existed: a no-op removal claims nothing. */
+export async function removeRecorded(
+  target: string,
+  owner: ManagedOutputOwner,
+  recorder?: ManagedOutputRecorder,
+): Promise<void> {
+  const existed = await fs.lstat(target).then(
+    () => true,
+    () => false,
+  );
+  if (!existed) return;
+  await fs.rm(target, { recursive: true, force: true });
+  recorder?.record({ path: target, change: "removed", owner });
+}

package/src/tools/setup/mate.ts

@@ -1,13 +1,20 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
+import { removeRecorded } from "./managed-output";
+import type { ManagedOutputRecorder } from "./plugin";
 import { pruneEmptyAncestors } from "./utils";
+import { readFrontmatter } from "../../lib/frontmatter";
 
-export const MATE_ARTIFACT_SKILLS = ["mate-artifact-publish"] as const;
 export const MATE_SKILLS = [
-  "mate-artifact-publish",
+  "mate-clarify-intent",
+  "mate-explore-change",
+  "mate-propose-change",
+  "mate-apply-change",
+  "mate-archive-change",
+  "mate-publish-artifact",
+  "mate-backfill-spec",
   "mate-create-report",
-  "mate-openspec-backfill",
   "mate-interview-me",
   "mate-grill-me",
   "mate-grilling",
@@ -17,8 +24,11 @@ export const MATE_SKILLS = [
   "mate-simplify-code",
 ] as const;
 const LEGACY_MATE_SKILLS = ["mate-artifact-finish", "mate-openspec-artifact-finish"] as const;
-/** Every Mate-owned skill name a skill root may hold, current or retired. */
-export const MANAGED_MATE_SKILL_NAMES = [...MATE_SKILLS, ...LEGACY_MATE_SKILLS] as const;
+/**
+ * Renamed without aliases: removed only when Mate wrote them (`metadata.author: mate`),
+ * so a user-authored skill that happens to share a retired name is left alone.
+ */
+const RETIRED_MATE_SKILLS = ["mate-artifact-publish", "mate-openspec-backfill"] as const;
 
 const MATE_SKILLS_SOURCE = path.join(import.meta.dirname, "../../templates/mate-skills");
 
@@ -83,13 +93,41 @@ A \`diff\` section carries a unified diff patch as produced by \`git diff\`. The
 
 A report carrying a mermaid payload loads the pinned, integrity-checked diagram runtime from a CDN; a report without one does not. Offline, each diagram stays readable as its source. Otherwise the page stays a single self-contained file.
 
+## Presentation Fields
+
+These fields are optional. A document without them stays valid and renders with the defaults.
+
+- \`tone\` on a status item: \`ok\`, \`warn\`, \`error\`, \`info\`, or \`neutral\`. It sets the marker's colour and shape. When absent, the tone is inferred from well-known status words such as \`passed\`, \`stale\`, or \`failed\`, and any other text is \`neutral\`.
+
+  \`\`\`json
+  { "label": "Build", "status": "flaky", "tone": "warn" }
+  \`\`\`
+
+- \`format\` on a \`text\` section: \`plain\` (default, shown verbatim with its line breaks) or \`markdown\`.
+
+  \`\`\`json
+  { "id": "notes", "title": "Notes", "type": "text", "format": "markdown", "content": "- **Renderer** owns layout\\n- See \`highlight.ts\`" }
+  \`\`\`
+
+- \`caption\` on a \`diagram\` or \`diff\` section: a non-empty Markdown note shown beneath the visual, in the same section and without a heading of its own.
+
+  \`\`\`json
+  { "id": "changes", "title": "Changes", "type": "diff", "patch": "...", "caption": "Moves validation into \`contract.ts\`." }
+  \`\`\`
+
+Markdown supports paragraphs, \`#\` headings, one-level \`-\`, \`*\`, or \`1.\` lists, \`**strong**\`, \`*emphasis*\`, \`\` \`code\` \`\`, fenced code blocks with syntax highlighting, and \`[text](https://…)\` links. Raw HTML is shown as text, links other than \`http\` or \`https\` are shown as plain text, and any other syntax stays literal.
+
+The page follows the reader's colour scheme: Mate brand colours on white in light mode, and on a dark background in dark mode, with highlighted code and mermaid diagrams following the same scheme. It always prints as dark text on white.
+
+To mark mermaid nodes, apply the theme classes \`added\`, \`changed\`, and \`removed\` with \`class\` or \`:::\`; they follow the colour scheme. Lines that fix a colour with \`classDef\`, \`style\`, or \`linkStyle\` are dropped from the dark copy, because a fill chosen for a white page hides the labels there.
+
 ## Invocation
 
 1. Serialize the complete document to a temporary file or pipe it to stdin.
 2. Run \`mate report --input <file-or->\`.
 3. Add \`--json\` when the caller needs normalized JSON instead of browser delivery.
 
-The CLI chooses the delivery surface; deliver only through \`mate report\`, never a hand-written file, server, or browser launch. Inside a Studio terminal it hosts the report in Studio and prints a full link only when Studio has a public address, otherwise it tells the operator to open Studio → Reports; relay that output. Elsewhere, or when Studio is unreachable, it writes self-contained HTML to a unique OS temporary directory and opens it in the default browser. The report includes a visible "Print / Save as PDF" control that calls the browser's native print dialog. If HTML delivery fails, the CLI warns on stderr and emits the complete report document as JSON on stdout.
+The CLI chooses the delivery surface; deliver only through \`mate report\`, never a hand-written file, server, or browser launch. Inside a Studio terminal it hosts the report in Studio and prints a full link only when Studio has a public address, otherwise it tells the operator to open Studio → Reports; relay that output. Elsewhere, or when Studio is unreachable, it writes self-contained HTML to a unique OS temporary directory and opens it in the default browser. The report header carries an icon-only print control, named "Print / Save as PDF", that calls the browser's native print dialog. If HTML delivery fails, the CLI warns on stderr and emits the complete report document as JSON on stdout.
 
 The built-in \`mate report\` path collects Mate usage data and adapts it to the same contract and renderer.
 `;
@@ -133,10 +171,41 @@ async function resolveMateSkillSource(skill: string, tool: string): Promise<stri
   throw new Error(`Mate skill source not found: ${skill}`);
 }
 
-export async function applyMateSkills(skillsDir: string, tool: string): Promise<void> {
+/** The `metadata.author` a skill directory's SKILL.md declares, if any. */
+export async function readSkillAuthor(skillDir: string): Promise<unknown> {
+  let source: string;
+  try {
+    source = await fs.readFile(path.join(skillDir, "SKILL.md"), "utf8");
+  } catch {
+    return undefined;
+  }
+  const metadata = readFrontmatter(source)?.metadata as { author?: unknown } | null | undefined;
+  return metadata?.author;
+}
+
+async function isMateAuthored(skillDir: string): Promise<boolean> {
+  return (await readSkillAuthor(skillDir)) === "mate";
+}
+
+export async function removeRetiredMateSkills(
+  skillsDir: string,
+  recorder?: ManagedOutputRecorder,
+): Promise<void> {
+  for (const skill of RETIRED_MATE_SKILLS) {
+    const dir = path.join(skillsDir, skill);
+    if (await isMateAuthored(dir)) await removeRecorded(dir, "mate", recorder);
+  }
+}
+
+export async function applyMateSkills(
+  skillsDir: string,
+  tool: string,
+  recorder?: ManagedOutputRecorder,
+): Promise<void> {
   for (const skill of LEGACY_MATE_SKILLS) {
-    await fs.rm(path.join(skillsDir, skill), { recursive: true, force: true });
+    await removeRecorded(path.join(skillsDir, skill), "mate", recorder);
   }
+  await removeRetiredMateSkills(skillsDir, recorder);
   for (const skill of MATE_SKILLS) {
     const destination = path.join(skillsDir, skill);
     if (skill === "mate-create-report") {
@@ -145,13 +214,19 @@ export async function applyMateSkills(skillsDir: string, tool: string): Promise<
     } else {
       await deployMateSkillDir(await resolveMateSkillSource(skill, tool), destination);
     }
+    recorder?.record({ path: destination, change: "written", owner: "mate" });
   }
 }
 
-export async function teardownMateSkills(skillsDir: string, companionPath: string): Promise<void> {
-  for (const skill of MANAGED_MATE_SKILL_NAMES) {
+export async function teardownMateSkills(
+  skillsDir: string,
+  companionPath: string,
+  recorder?: ManagedOutputRecorder,
+): Promise<void> {
+  await removeRetiredMateSkills(skillsDir, recorder);
+  for (const skill of [...MATE_SKILLS, ...LEGACY_MATE_SKILLS]) {
     try {
-      await fs.rm(path.join(skillsDir, skill), { recursive: true, force: true });
+      await removeRecorded(path.join(skillsDir, skill), "mate", recorder);
     } catch {
       /* not present */
     }

package/src/tools/setup/plugin.ts

@@ -1,4 +1,5 @@
 import type { FrameworkConfig, LinkedRepository } from "../../lib/orchestrator/types";
+import type { SessionKind } from "../../runtime/session-kind";
 import type { InstallRequirement, InstallRequirementContext } from "./install-contract";
 import type { ClaudeHookGroup } from "./providers/claude-format";
 
@@ -7,10 +8,9 @@ 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;
- * `audience-layer` writes one audience's launch layer, outside every repository.
+ * its own upward walk and leaves the placing to the Projection Root.
  */
-export type ProjectionTarget = "companion" | "working" | "audience-layer";
+export type ProjectionTarget = "companion" | "working";
 
 export interface SetupContext {
   companionPath: string;
@@ -23,14 +23,11 @@ export interface SetupContext {
   repoPath?: string;
   /** Defaults to `companion`, so a caller that names no target is unchanged. */
   target?: ProjectionTarget;
-  /** The audience an `audience-layer` pass renders; required by that target only. */
-  audience?: string;
   /**
-   * Where an `audience-layer` pass writes: the staging directory a render is
-   * built in before it is renamed into place. The audience's layer directory
-   * when absent.
+   * Asks the OpenSpec capability to regenerate its CLI output in `sync` mode.
+   * Only `mate companion update` sets it; launches leave committed output alone.
    */
-  layerRoot?: string;
+  regenerateOpenSpec?: boolean;
   /**
    * Provider-mediated context services. Always populated when the engine
    * executes a plugin; optional so hand-built contexts (tests, direct calls)
@@ -39,13 +36,34 @@ export interface SetupContext {
   mcp?: McpService;
   instructions?: InstructionsService;
   templates?: TemplatesService;
+  /** Collects the managed output a sync pass touched; absent outside one. */
+  managedOutput?: ManagedOutputRecorder;
 }
 
+export type ManagedOutputOwner = "mate" | "openspec";
+
+/** One path a pass wrote or removed, with the side that owns it. */
+export interface ManagedOutputEntry {
+  /** Absolute when recorded; companion-relative POSIX in a {@link ManagedOutputReport}. */
+  path: string;
+  change: "written" | "removed";
+  owner: ManagedOutputOwner;
+}
+
+export interface ManagedOutputRecorder {
+  record(entry: ManagedOutputEntry): void;
+}
+
+/** What a sync pass reports it touched, as companion-relative POSIX paths. */
+export type ManagedOutputReport = readonly ManagedOutputEntry[];
+
 export interface LaunchPreflightContext {
   companionPath: string;
   config: FrameworkConfig;
   repository?: LinkedRepository;
   providerId: string;
+  /** The session the prepare answers for, so a check can skip what that session does not load. */
+  sessionKind: SessionKind;
 }
 
 /** Provider-agnostic description of an MCP server to register. */
@@ -131,15 +149,9 @@ export type PluginPolicy = "required" | "default" | "optional";
 
 /**
  * A plugin registration entry. Bare plugins derive their policy from
- * `defaultSelected` (`true` → "default", `false` → "optional"). `audience` is
- * the source of a declared plugin: `null` (or absent) for compiled-in plugins
- * and top-level `plugins` declarations, the audience name for a declaration
- * under `audiences.<name>.plugins`. `packageName` names the declared package a
- * dynamic plugin was loaded from.
+ * `defaultSelected` (`true` → "default", `false` → "optional").
  */
-export type PluginRegistration =
-  | Plugin
-  | { plugin: Plugin; policy: PluginPolicy; audience?: string | null; packageName?: string };
+export type PluginRegistration = Plugin | { plugin: Plugin; policy: PluginPolicy };
 
 /**
  * A hook group a Capability contributes to a runtime's settings. `marker` is
@@ -203,10 +215,17 @@ export interface AgentDefinitionContribution {
   content: string;
 }
 
+/** A Claude Code plugin folder, declared under the `claude` key. Launch-only: never written to a file. */
+export interface PluginDirectoryContribution {
+  /** Absolute path of the folder holding `.claude-plugin/plugin.json`. */
+  path: string;
+}
+
 /**
  * Declarative Agent Runtime contributions of one Capability for one runtime.
  * The runtime's Runtime Surface reconciles these symmetrically: applied while
  * the Capability is enabled, removed when it is not, idempotent across runs.
+ * `pluginDirectories` is the exception: gathered for the launch, written nowhere.
  */
 export interface RuntimeContributions {
   mcpServers?: McpServerDescriptor[];
@@ -216,6 +235,7 @@ export interface RuntimeContributions {
   skillTrees?: SkillTreeContribution[];
   pluginReferences?: PluginReferenceContribution[];
   agentDefinitions?: AgentDefinitionContribution[];
+  pluginDirectories?: PluginDirectoryContribution[];
 }
 
 /**