toolfactory 0.1.2 → 0.2.1

package/src/project/gate.ts

@@ -9,6 +9,18 @@
  * A step here is a command and nothing else. GitHub Actions `uses:` steps are runner provisioning
  * (checkout, toolchains, caches) and stay in `src/surfaces/workflows.ts`, which wraps this list.
  */
+
+import {
+  type NativePackageId,
+  nativePackageSteps,
+  nativeRegistryRows,
+  nativeToolchainSteps,
+} from "../distribution/native.js";
+import {
+  type SystemPackageId,
+  systemPackageSteps,
+  systemRegistryRows,
+} from "../distribution/system.js";
 import { githubSlug } from "../hosts/github.js";
 import { githubOwner, projectName } from "../identity/name.js";
 import { isInstructionOnly, type PackageManager, type Project, type SurfaceId } from "../model.js";
@@ -28,6 +40,14 @@ import {
   npmName,
   pypiName,
 } from "../surfaces/shared.js";
+import {
+  extensionName,
+  OVSX_VERSION,
+  publisher,
+  VSCE_VERSION,
+  HOST_DIR as VSCODE_HOST_DIR,
+  vsixName,
+} from "../surfaces/vscode-extension.js";
 
 export interface GateStep {
   /** Step label: the CI step name, and the banner the shell script echoes. */
@@ -140,7 +160,11 @@ export function gateSteps(project: Project): GateStep[] {
       when: "ci",
     });
   }
-  if (has(project, "web") || has(project, "browser-extension")) {
+  if (
+    has(project, "web") ||
+    has(project, "browser-extension") ||
+    has(project, "vscode-extension")
+  ) {
     // The web smoke and the browser extension's own Playwright smoke both drive Chromium;
     // their own npm installs fetch the browser, the runner needs its system libraries.
     steps.push({
@@ -149,6 +173,7 @@ export function gateSteps(project: Project): GateStep[] {
       when: "ci",
     });
   }
+  steps.push(...nativeToolchainSteps(project));
   steps.push({
     name: "toolfactory validate",
     run: `${cli} validate`,
@@ -160,6 +185,7 @@ export function gateSteps(project: Project): GateStep[] {
     name: "author tests",
     run: typescript ? pm.test : "uv run --with pytest pytest -q",
   });
+  if (typescript) steps.push({ name: "author integration tests", run: pm.run("test:integration") });
   if (openclaw) {
     // T3, credential-free: one real OpenClaw agent turn against a scripted model. The suite only
     // exists when `tool.json` `tests.examples` names an operation the plugin carries, which is
@@ -220,13 +246,16 @@ const LEGAL_BUNDLE_PATHS = [
  * the release workflow's `package` job, which uploads the directory as one artifact. Publishing
  * to a registry stays a CI concern; producing the artifacts never is.
  */
-export function packageSteps(project: Project): GateStep[] {
+export function packageSteps(project: Project, options: { system?: boolean } = {}): GateStep[] {
   const cli = toolfactoryCli(project);
   const name = project.identity.name;
   const steps: GateStep[] = [
     { name: "release directory", run: `rm -rf ${RELEASE_DIR} && mkdir -p ${RELEASE_DIR}` },
     ...bootstrapSteps(project),
     outputsStep(project),
+    ...nativeToolchainSteps(project),
+    ...nativePackageSteps(project),
+    ...systemPackageSteps(project, { include: options.system !== false }),
   ];
   if (has(project, "web")) {
     steps.push({
@@ -329,6 +358,12 @@ export function packageSteps(project: Project): GateStep[] {
     });
   }
   // COVERAGE.md is tracked; coverage.json is a build output that need not be, so recompute it.
+  if (has(project, "vscode-extension")) {
+    steps.push({
+      name: "VS Code extension VSIX",
+      run: `npm --prefix ${VSCODE_HOST_DIR} install && npm --prefix ${VSCODE_HOST_DIR} run vsix && cp ${VSCODE_HOST_DIR}/extension.vsix ${RELEASE_DIR}/${vsixName(project)}`,
+    });
+  }
   steps.push({
     name: "coverage report",
     run: `cp COVERAGE.md ${RELEASE_DIR}/ && ${cli} coverage > ${RELEASE_DIR}/coverage.json`,
@@ -355,6 +390,8 @@ export function openclawTarball(project: Project): string {
 export interface Registry {
   /** Stable id: the release job suffix, the `secrets status` row, the unpublish step name. */
   id:
+    | NativePackageId
+    | SystemPackageId
     | "npm"
     | "pypi"
     | "mcp-registry"
@@ -365,7 +402,9 @@ export interface Registry {
     | "chrome"
     | "firefox"
     | "edge"
-    | "safari";
+    | "safari"
+    | "vscode-marketplace"
+    | "open-vsx";
   /** The surfaces whose selection publishes here; all must be selected. */
   surfaces: SurfaceId[];
   /** Environment names the publish leg consumes (repository scope); [] for OIDC/GITHUB_TOKEN legs. */
@@ -447,6 +486,22 @@ const ASC_SECRETS = ["ASC_KEY_ID", "ASC_ISSUER_ID", "ASC_PRIVATE_KEY"];
 export const RELEASE_SECRET_NAMES = [
   "NPM_TOKEN",
   "CLAWHUB_TOKEN",
+  "VSCE_PAT",
+  "OVSX_PAT",
+  "CARGO_REGISTRY_TOKEN",
+  "NUGET_API_KEY",
+  "MAVEN_CENTRAL_USERNAME",
+  "MAVEN_CENTRAL_PASSWORD",
+  "MAVEN_GPG_PRIVATE_KEY",
+  "MAVEN_GPG_PASSPHRASE",
+  "RUBYGEMS_API_KEY",
+  "HOMEBREW_TAP_TOKEN",
+  "SCOOP_BUCKET_TOKEN",
+  "CHOCOLATEY_API_KEY",
+  "APT_GPG_PRIVATE_KEY",
+  "APT_GPG_KEY_ID",
+  "COPR_LOGIN",
+  "COPR_TOKEN",
   ...CHROME_SECRETS,
   ...FIREFOX_SECRETS,
   ...EDGE_SECRETS,
@@ -474,6 +529,29 @@ export function registries(project: Project): Registry[] {
   const wxtSubmit = `npm --prefix ${BROWSER_HOST_DIR} exec --no -- wxt submit --dry-run`;
 
   const rows: Registry[] = [
+    ...nativeRegistryRows(project),
+    ...systemRegistryRows(project),
+    {
+      id: "vscode-marketplace",
+      surfaces: ["vscode-extension"],
+      secrets: ["VSCE_PAT"],
+      url: "https://marketplace.visualstudio.com/manage",
+      probe: `npx --yes @vscode/vsce@${VSCE_VERSION} verify-pat ${publisher(project)}`,
+      exists: `npx --yes @vscode/vsce@${VSCE_VERSION} show ${publisher(project)}.${extensionName(project)} --json | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>process.exit(JSON.parse(s).versions.some(v=>v.version==="${version}")?0:1))'`,
+      gate: allSet(["VSCE_PAT"]),
+      retractUrl: "https://marketplace.visualstudio.com/manage",
+      retractHard: `npx --yes @vscode/vsce@${VSCE_VERSION} unpublish ${publisher(project)}.${extensionName(project)} --force`,
+    },
+    {
+      id: "open-vsx",
+      surfaces: ["vscode-extension"],
+      secrets: ["OVSX_PAT"],
+      url: "https://open-vsx.org/user-settings/tokens",
+      probe: `npx --yes ovsx@${OVSX_VERSION} verify-pat ${publisher(project)}`,
+      exists: `curl -fsS -o /dev/null https://open-vsx.org/api/${publisher(project)}/${extensionName(project)}/${version}`,
+      gate: allSet(["OVSX_PAT"]),
+      retractUrl: "https://open-vsx.org/user-settings/extensions",
+    },
     {
       id: "npm",
       surfaces: ["npm"],
@@ -627,7 +705,9 @@ export function registries(project: Project): Registry[] {
   const selected = rows.filter(
     (row) =>
       row.surfaces.every((surface) => has(project, surface)) &&
-      (row.id !== "safari" || project.tool.browserExtension?.safari === true),
+      (row.id !== "safari" || project.tool.browserExtension?.safari === true) &&
+      (row.id !== "vscode-marketplace" || project.tool.vscode?.marketplace !== false) &&
+      (row.id !== "open-vsx" || project.tool.vscode?.openvsx !== false),
   );
   const mcpRegistry = selected.find((row) => row.id === "mcp-registry");
   if (mcpRegistry) {
@@ -638,6 +718,14 @@ export function registries(project: Project): Registry[] {
       ? packages.map((row) => `[ "$${gateVariable(row)}" = true ]`).join(" && ")
       : "true";
   }
+  const runtime = selected.find(
+    (row) => row.id === (project.tool.binding === "python" ? "pypi" : "npm"),
+  );
+  for (const row of selected.filter(
+    (row) => row.id === "vscode-marketplace" || row.id === "open-vsx",
+  )) {
+    if (runtime) row.gate = `(${row.gate}) && { ${runtime.exists} || { ${runtime.gate}; }; }`;
+  }
   return selected;
 }
 
@@ -664,6 +752,10 @@ export function manualSteps(project: Project): string[] {
   const has_ = (id: Registry["id"]) => rows.some((row) => row.id === id);
   const slug = githubSlug(project.identity.repository);
   const steps: string[] = [];
+  if (has_("vscode-marketplace") || has_("open-vsx"))
+    steps.push(
+      "VS Code: register the publisher in Visual Studio Marketplace; create the Open VSX namespace and accept its publisher agreement before setting VSCE_PAT / OVSX_PAT. tool.vscode.publisher selects that identity.",
+    );
   if (has_("oci")) {
     steps.push(
       `ghcr.io: the first push publishes a private image whatever the repository's visibility, and GitHub has no visibility API — flip it once at ${rows.find((row) => row.id === "oci")?.url}.`,

package/src/project/lock.ts

@@ -23,6 +23,18 @@ export const LockSchema = z.object({
        * patch — or deselecting the surface that added it — uninstalls it instead of stranding it.
        */
       keys: z.array(z.string()).optional(),
+      /** A keyed array's inverse: the entries Toolfactory owns at each dotted path. */
+      keyedArrays: z
+        .record(
+          z.string(),
+          z.object({
+            id: z.string(),
+            values: z.array(z.string()),
+            /** The last projected entry shape lets a later plan remove only stale generated leaves. */
+            entries: z.record(z.string(), z.record(z.string(), z.unknown())).optional(),
+          }),
+        )
+        .optional(),
       /**
        * A region file's inverse, exactly as `keys` is a merge file's: the marker pairs its
        * projector wrote. Regions the current plan no longer writes are emptied before the current

package/src/surfaces/agent-plugins.ts

@@ -4,7 +4,7 @@
  * Validation is Ajv against the cached official schemas; the spec forbids fetching at load.
  */
 import type { Project, Surface } from "../model.js";
-import { json, kernelLaunch, mcpVerdict } from "./shared.js";
+import { kernelLaunch, mcpVerdict } from "./shared.js";
 
 export const MCP_SCHEMA_ID = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
 export const PLUGIN_SCHEMA_ID = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
@@ -24,12 +24,13 @@ export const surface: Surface = {
     const launch = kernelLaunch(project, "${PLUGIN_ROOT}");
     return [
       {
-        kind: "file",
+        kind: "merge",
         path: "mcp.json",
-        content: json({
+        format: "json",
+        patch: {
           $schema: MCP_SCHEMA_ID,
           mcpServers: { [project.identity.name]: { type: "stdio", ...launch } },
-        }),
+        },
       },
     ];
   },

package/src/surfaces/agents.test.ts

@@ -129,6 +129,22 @@ describe("agents", () => {
     expect(setup).toContain("npm install --no-audit --no-fund");
   });
 
+  it("installs uv before Python projects run the vendored setup workflow", () => {
+    const workflow = planned(
+      project(["cli"], { binding: "python" }),
+      ".github/workflows/agent-config.yml",
+    );
+    if (workflow.kind !== "file") throw new Error("expected an agent-config workflow file");
+    const install = "uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0";
+    expect(workflow.content).toContain(install);
+    expect(workflow.content.indexOf(install)).toBeLessThan(
+      workflow.content.indexOf("run: bash .agents/setup --all"),
+    );
+    const typescript = planned(project(["cli"]), ".github/workflows/agent-config.yml");
+    if (typescript.kind !== "file") throw new Error("expected an agent-config workflow file");
+    expect(typescript.content).toBe(TEMPLATE_FILES[".github/workflows/agent-config.yml"]);
+  });
+
   it("owns the agent adapters, the binding's ignores and the build outputs in .gitignore", () => {
     const bare = region(project(["cli"]), IGNORE_PATH);
     const agentBlocks = (TEMPLATE_FILES[IGNORE_PATH] ?? "").split("# ─── Secrets")[0] ?? "";

package/src/surfaces/agents.ts

@@ -198,7 +198,8 @@ function layoutSection(project: Project): string[] {
     has(project, "openclaw-native") ||
     has(project, "hermes-native") ||
     has(project, "dsh") ||
-    has(project, "browser-extension")
+    has(project, "browser-extension") ||
+    has(project, "vscode-extension")
   ) {
     lines.push(
       "- `hosts/<id>/` — the host-native escape hatch for a selected host; nothing else creates it.",
@@ -281,6 +282,15 @@ function installSection(project: Project): string[] {
       "  KEY/PASSWORD/SECRET/TOKEN names before spawning an MCP server.",
     );
   }
+  if (has(project, "vscode-extension")) {
+    lines.push(
+      "- **VS Code extension**: `npm --prefix hosts/vscode install`, then open `hosts/vscode` in VS Code",
+      "  and press F5. Development and `npm --prefix hosts/vscode test` use the checkout's kernel.",
+      "  `npm --prefix hosts/vscode run vsix` packages it; install with `code --install-extension hosts/vscode/extension.vsix`.",
+      "  Use Developer: Reload Window after rebuilding an installed extension. Native activation, contributions",
+      "  and every VS Code API are available in your own files; include your license in the extension directory.",
+    );
+  }
   if (has(project, "browser-extension")) {
     const { command, args } = getBinding(project.tool.binding).cliCommand(project);
     lines.push(
@@ -299,7 +309,8 @@ function installSection(project: Project): string[] {
     !openclaw &&
     !hermes &&
     !has(project, "dsh") &&
-    !has(project, "browser-extension")
+    !has(project, "browser-extension") &&
+    !has(project, "vscode-extension")
   ) {
     lines.push(
       "_No host-native surface (`openclaw-native`, `hermes-native`, `dsh`, `browser-extension`) or",
@@ -688,6 +699,22 @@ function devcontainer(project: Project): string {
   return `${JSON.stringify({ ...document, features }, null, 2)}\n`;
 }
 
+/** The vendor-owned workflow gains the Python prerequisite it cannot know. */
+function agentConfigWorkflow(project: Project): string {
+  const path = ".github/workflows/agent-config.yml";
+  const workflow = TEMPLATE_FILES[path] ?? "";
+  if (isInstructionOnly(project.tool) || project.tool.binding !== "python") return workflow;
+  const setup = "      - name: Run the shared setup entry point\n";
+  if (!workflow.includes(setup))
+    throw new Error(`${path} no longer has the setup step; re-vendor before adding uv.`);
+  return workflow.replace(
+    setup,
+    "      - name: Install uv\n" +
+      "        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0\n\n" +
+      setup,
+  );
+}
+
 /** Whole-file carriers: no per-project content, `adopt` is the escape hatch. */
 function vendored(project: Project): PlannedFile[] {
   const skip = new Set([SETUP_PATH, IGNORE_PATH, ".devcontainer/devcontainer.json"]);
@@ -698,7 +725,8 @@ function vendored(project: Project): PlannedFile[] {
         ([path, content]): PlannedFile => ({
           kind: "file",
           path,
-          content,
+          content:
+            path === ".github/workflows/agent-config.yml" ? agentConfigWorkflow(project) : content,
           ...(path.endsWith("sync.py") ? { mode: 0o755 } : {}),
         }),
       ),

package/src/surfaces/claude.ts

@@ -12,7 +12,6 @@ import {
   envName,
   has,
   isSensitive,
-  json,
   kernelLaunch,
   mcpVerdict,
   requiredConfig,
@@ -79,8 +78,13 @@ export const surface: Surface = {
       plugins: [compact({ name: identity.name, source: "./", description: identity.description })],
     });
     return [
-      { kind: "file", path: ".claude-plugin/plugin.json", content: json(manifest) },
-      { kind: "file", path: ".claude-plugin/marketplace.json", content: json(marketplace) },
+      { kind: "merge", path: ".claude-plugin/plugin.json", format: "json", patch: manifest },
+      {
+        kind: "merge",
+        path: ".claude-plugin/marketplace.json",
+        format: "json",
+        patch: marketplace,
+      },
     ];
   },
   validate(project) {

package/src/surfaces/codex.test.ts

@@ -33,8 +33,8 @@ describe("codex", () => {
   it("makes the repository its own single-plugin marketplace, and validates with the real codex CLI", () => {
     const files = codex.plan(project(["codex", "mcp"]));
     const marketplace = files.find((entry) => entry.path === ".agents/plugins/marketplace.json");
-    if (marketplace?.kind !== "file") throw new Error("expected a whole file");
-    expect(JSON.parse(marketplace.content)).toMatchObject({
+    if (marketplace?.kind !== "merge") throw new Error("expected a merge manifest");
+    expect(marketplace.patch).toMatchObject({
       name: "hello",
       interface: { displayName: "Hello" },
       plugins: [
@@ -64,17 +64,17 @@ describe("codex", () => {
     const target = project(["skill", "codex"]);
     target.tool.runtime = "none";
     const manifest = codex.plan(target).find((entry) => entry.path === ".codex-plugin/plugin.json");
-    if (manifest?.kind !== "file") throw new Error("expected a manifest");
-    expect(JSON.parse(manifest.content)).toMatchObject({ skills: "./skills/" });
-    expect(JSON.parse(manifest.content)).not.toHaveProperty("mcpServers");
+    if (manifest?.kind !== "merge") throw new Error("expected a manifest");
+    expect(manifest.patch).toMatchObject({ skills: "./skills/" });
+    expect(manifest.patch).not.toHaveProperty("mcpServers");
   });
 
   it("can omit the eager MCP server while retaining the plugin skill", () => {
     const target = project(["skill", "codex", "mcp"]);
     target.tool.codex = { mcp: false };
     const manifest = codex.plan(target).find((entry) => entry.path === ".codex-plugin/plugin.json");
-    if (manifest?.kind !== "file") throw new Error("expected a manifest");
-    const parsed = JSON.parse(manifest.content);
+    if (manifest?.kind !== "merge") throw new Error("expected a manifest");
+    const parsed = manifest.patch;
     expect(parsed.skills).toBe("./skills/");
     expect(parsed).not.toHaveProperty("mcpServers");
   });

package/src/surfaces/codex.ts

@@ -10,7 +10,7 @@
 
 import { projectName } from "../identity/name.js";
 import type { Surface } from "../model.js";
-import { compact, has, json, kernelLaunch, mcpVerdict } from "./shared.js";
+import { compact, has, kernelLaunch, mcpVerdict } from "./shared.js";
 
 /** The Codex CLI (`@openai/codex`) `validate()` is proven against — pin for a deterministic gate. */
 export const CODEX_PIN = "0.152.1";
@@ -65,8 +65,13 @@ export const surface: Surface = {
       ],
     });
     return [
-      { kind: "file", path: ".codex-plugin/plugin.json", content: json(manifest) },
-      { kind: "file", path: ".agents/plugins/marketplace.json", content: json(marketplace) },
+      { kind: "merge", path: ".codex-plugin/plugin.json", format: "json", patch: manifest },
+      {
+        kind: "merge",
+        path: ".agents/plugins/marketplace.json",
+        format: "json",
+        patch: marketplace,
+      },
     ];
   },
   validate(project) {

package/src/surfaces/cursor.ts

@@ -4,15 +4,7 @@
  */
 import { projectName } from "../identity/name.js";
 import type { Surface } from "../model.js";
-import {
-  compact,
-  configProperties,
-  envName,
-  has,
-  json,
-  mcpVerdict,
-  requiredConfig,
-} from "./shared.js";
+import { compact, configProperties, envName, has, mcpVerdict, requiredConfig } from "./shared.js";
 
 export const surface: Surface = {
   id: "cursor",
@@ -51,7 +43,7 @@ export const surface: Surface = {
       mcpServers: has(project, "agent-plugins") ? "./mcp.json" : undefined,
       variables,
     });
-    return [{ kind: "file", path: ".cursor-plugin/plugin.json", content: json(manifest) }];
+    return [{ kind: "merge", path: ".cursor-plugin/plugin.json", format: "json", patch: manifest }];
   },
   verdict: (operation) => {
     const verdict = mcpVerdict(operation);

package/src/surfaces/distribution.test.ts

@@ -190,8 +190,8 @@ describe("claude", () => {
   it("makes the repository its own single-plugin marketplace", () => {
     const files = claude.plan(project(["claude", "mcp"]));
     const file = files.find((entry) => entry.path === ".claude-plugin/marketplace.json");
-    if (file?.kind !== "file") throw new Error("expected a whole file");
-    expect(JSON.parse(file.content)).toMatchObject({
+    if (file?.kind !== "merge") throw new Error("expected a merge file");
+    expect(file.patch).toMatchObject({
       name: "hello",
       owner: { name: "GoatInAHat" },
       plugins: [{ name: "hello", source: "./", description: "Say hello" }],

package/src/surfaces/dsh.test.ts

@@ -1,6 +1,10 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { describe, expect, it } from "vitest";
 import { parse as parseYaml } from "yaml";
 import type { Operation, Project } from "../model.js";
+import { apply, replaceRegions } from "../project/apply.js";
 import { DSH_PIN, surface as dsh } from "./dsh.js";
 
 const echo: Operation = { name: "echo", inputSchema: { type: "object" }, requires: [] };
@@ -36,12 +40,44 @@ const project: Project = {
 
 const files = Object.fromEntries(
   dsh.plan(project).map((file) => {
-    if (file.kind !== "file") throw new Error("expected whole files only");
-    return [file.path, file.content];
+    return [
+      file.path,
+      file.kind === "file"
+        ? file.content
+        : file.kind === "merge"
+          ? JSON.stringify(file.patch)
+          : (replaceRegions(file.template, file) ?? file.template),
+    ];
   }),
 );
 
 describe("dsh", () => {
+  it("rebuilds legacy patch regions without commenting out insert or losing authored rows", () => {
+    const root = mkdtempSync(join(tmpdir(), "toolfactory-dsh-"));
+    try {
+      const plan = dsh.plan({ ...project, root });
+      const patches = plan.filter((file) => file.kind === "region");
+      apply(root, plan, project.toolfactoryVersion);
+      for (const file of patches) {
+        const path = join(root, file.path);
+        const legacy = readFileSync(path, "utf8").replace("# tf:mcp\n", "# tf:mcp");
+        writeFileSync(path, `${legacy}\n- insert:\n    - id: authored\n`);
+      }
+
+      apply(root, plan, project.toolfactoryVersion);
+      for (const file of patches) {
+        const rendered = readFileSync(join(root, file.path), "utf8");
+        expect(rendered).toMatch(/^# tf:mcp\n- insert:/);
+        expect(parseYaml(rendered, { logLevel: "silent" })).toMatchObject([
+          { insert: [{ id: "mcp-hello-tool" }] },
+          { insert: [{ id: "authored" }] },
+        ]);
+      }
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
   it("is two shipped files and no code: the bundle manifest and one mcp-client insert row", () => {
     // `dsh.bundle.patch` is DSH's whole acceptance test for a bundle; a dependency would be wrong,
     // because @deepseek-ai/dsh-mcp-client is @deepseek-ai/dsh's own.

package/src/surfaces/dsh.ts

@@ -22,7 +22,7 @@ import { Scalar, stringify as yamlStringify } from "yaml";
 import { getBinding } from "../bindings/index.js";
 import { projectName } from "../identity/name.js";
 import type { Project, Surface } from "../model.js";
-import { compact, configProperties, envName, json, kernelLaunch, mcpVerdict } from "./shared.js";
+import { compact, configProperties, envName, kernelLaunch, mcpVerdict } from "./shared.js";
 
 /**
  * The `@deepseek-ai/dsh` release `validate()` boots. Pinned, not `@alpha`: npm's `latest` tag
@@ -40,6 +40,8 @@ export const PATCH_FILE = "cordis.patch.yml";
  * passes to `dsh --patch` to drive the working tree.
  */
 export const LOCAL_PATCH_FILE = "cordis.local.patch.yml";
+const PATCH_BEGIN = "# tf:mcp";
+const PATCH_END = "# /tf:mcp";
 
 /** DSH's first-party MCP bridge; the only plugin the bundle names. */
 const MCP_CLIENT = "@deepseek-ai/dsh-mcp-client";
@@ -88,7 +90,12 @@ function patch(project: Project, launch: { command: string; args: string[] }): s
       failOnStartupError: true,
     }),
   };
-  return yamlStringify([{ insert: [row] }], { lineWidth: 0 });
+  // Region replacement starts immediately after the comment marker.
+  return `\n${yamlStringify([{ insert: [row] }], { lineWidth: 0 })}`;
+}
+
+function patchTemplate(): string {
+  return `${PATCH_BEGIN}\n${PATCH_END}\n\n# Yours: add Cordis rows or local code configuration below this marker.\n`;
 }
 
 /** The public name a bridged MCP tool takes in DSH; `mcp__<serverName>__<rawName>` is its contract. */
@@ -120,20 +127,34 @@ export const surface: Surface = {
       dsh: { bundle: { patch: `./${PATCH_FILE}` } },
     });
     return [
-      { kind: "file", path: `${HOST_DIR}/package.json`, content: json(manifest) },
+      { kind: "merge", path: `${HOST_DIR}/package.json`, format: "json", patch: manifest },
       {
-        kind: "file",
+        kind: "region",
         path: `${HOST_DIR}/${PATCH_FILE}`,
         // `cwd` is deliberately absent: an installed bundle has no path to point at, and the
         // published launch resolves through the registry from wherever DSH is running.
-        content: patch(project, kernelLaunch(project, ".")),
+        regions: [
+          {
+            begin: PATCH_BEGIN,
+            end: PATCH_END,
+            content: patch(project, kernelLaunch(project, ".")),
+          },
+        ],
+        template: patchTemplate(),
       },
       {
-        kind: "file",
+        kind: "region",
         path: `${HOST_DIR}/${LOCAL_PATCH_FILE}`,
         // The kernel as `introspect` and `inspector.json` spawn it: repo-relative, so it resolves
         // against the directory DSH itself was started in.
-        content: patch(project, getBinding(project.tool.binding).kernelCommand(project)),
+        regions: [
+          {
+            begin: PATCH_BEGIN,
+            end: PATCH_END,
+            content: patch(project, getBinding(project.tool.binding).kernelCommand(project)),
+          },
+        ],
+        template: patchTemplate(),
       },
     ];
   },

package/src/surfaces/gemini.test.ts

@@ -34,8 +34,8 @@ const project: Project = {
 };
 
 const [manifestFile, ...rest] = gemini.plan(project);
-if (manifestFile?.kind !== "file") throw new Error("expected one whole file");
-const manifest = JSON.parse(manifestFile.content) as Record<string, unknown>;
+if (manifestFile?.kind !== "merge") throw new Error("expected one merge file");
+const manifest = manifestFile.patch as Record<string, unknown>;
 
 describe("gemini", () => {
   it("is one root manifest: a dashed name, the kernel launch, AGENTS.md as the context file", () => {
@@ -58,7 +58,7 @@ describe("gemini", () => {
       ],
     });
     // `skills/` and `commands/` are auto-discovered from the extension root; no key names them.
-    expect(manifestFile.content).not.toContain('"skills"');
+    expect(JSON.stringify(manifestFile.patch)).not.toContain('"skills"');
   });
 
   it("validates through Gemini's own manifest validator, and carries only MCP tool calls", () => {

package/src/surfaces/gemini.ts

@@ -26,7 +26,6 @@ import {
   configProperties,
   envName,
   isSensitive,
-  json,
   kernelLaunch,
   mcpVerdict,
 } from "./shared.js";
@@ -64,7 +63,7 @@ export const surface: Surface = {
       contextFileName: AGENTS_PATH,
       settings: settings.length ? settings : undefined,
     });
-    return [{ kind: "file", path: MANIFEST_PATH, content: json(manifest) }];
+    return [{ kind: "merge", path: MANIFEST_PATH, format: "json", patch: manifest }];
   },
   validate(project) {
     // Gemini's own manifest validator: it parses the manifest, enforces the name and version