toolfactory 0.1.2 → 0.2.1

package/dist/project/lock.d.ts

@@ -16,6 +16,11 @@ export declare const LockSchema: z.ZodObject<{
             manual: "manual";
         }>;
         keys: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        keyedArrays: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            id: z.ZodString;
+            values: z.ZodArray<z.ZodString>;
+            entries: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        }, z.core.$strip>>>;
         regions: z.ZodOptional<z.ZodArray<z.ZodObject<{
             begin: z.ZodString;
             end: z.ZodString;

package/dist/project/lock.js

@@ -17,6 +17,15 @@ 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/dist/surfaces/agent-plugins.js

@@ -1,4 +1,4 @@
-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";
 export function assertBundleIdentity(project) {
@@ -13,12 +13,13 @@ export const 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/dist/surfaces/agents.js

@@ -160,7 +160,8 @@ function layoutSection(project) {
     if (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.");
     }
     if (has(project, "web"))
@@ -216,6 +217,9 @@ function installSection(project) {
     if (has(project, "dsh")) {
         lines.push(`- **DSH** (experimental): \`dsh plugin --profile ${DSH_PROFILE} add ./${DSH_HOST_DIR}\` installs the`, "  bundle (`dsh plugin` forwards to pnpm, so pnpm must be on `PATH`); the operations reach the", `  model as \`${dshToolName(project, "<operation>")}\`, and \`dsh --profile ${DSH_PROFILE} --dump-config\` shows`, `  the composed \`id: ${dshRowId(project)}\` row. Bundle patches are read once per boot and never watched,`, `  so restart DSH after editing \`${DSH_HOST_DIR}/${PATCH_FILE}\` or reinstalling. Boot with`, `  \`--patch ${DSH_HOST_DIR}/${LOCAL_PATCH_FILE}\` and no bundle installed to drive this checkout`, "  instead. Every config variable is restated in the row's `env:` because DSH scrubs", "  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(`- **Browser extension**: \`npm --prefix ${BROWSER_HOST_DIR} install && npm --prefix ${BROWSER_HOST_DIR} exec --no -- wxt build\`,`, `  then \`chrome://extensions\` → developer mode → Load unpacked → \`${BROWSER_HOST_DIR}/.output/chrome-mv3\`;`, `  \`npm --prefix ${BROWSER_HOST_DIR} exec --no -- web-ext run\` does the same for Firefox. Pair it with this`, `  checkout's kernel: \`${[command, ...args].join(" ")} mcp --http --pair\` mints a token under the data`, `  directory and prints the \`<url>#<token>\` the extension's options page accepts (with no token minted`, `  and no \`${envName(project.identity.name)}_MCP_TOKEN\` in the environment the endpoint stays open on loopback). The content`, "  script's selectors are yours to maintain: it is authored escape-hatch code against a page that", "  changes on its own schedule, and nothing here can version-proof it.");
@@ -224,7 +228,8 @@ function installSection(project) {
         !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", "`gemini` extension is selected; nothing installs into a running host._");
     }
     lines.push("", "Codex and Cursor read this file as is; Claude Code and Gemini read `CLAUDE.md` / `GEMINI.md`,", "each of which `.agents/sync.py` renders as the one line `@AGENTS.md`.", "");
@@ -570,6 +575,19 @@ function devcontainer(project) {
         : document.features;
     return `${JSON.stringify({ ...document, features }, null, 2)}\n`;
 }
+/** The vendor-owned workflow gains the Python prerequisite it cannot know. */
+function agentConfigWorkflow(project) {
+    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) {
     const skip = new Set([SETUP_PATH, IGNORE_PATH, ".devcontainer/devcontainer.json"]);
@@ -579,7 +597,7 @@ function vendored(project) {
             .map(([path, content]) => ({
             kind: "file",
             path,
-            content,
+            content: path === ".github/workflows/agent-config.yml" ? agentConfigWorkflow(project) : content,
             ...(path.endsWith("sync.py") ? { mode: 0o755 } : {}),
         })),
         { kind: "file", path: ".devcontainer/devcontainer.json", content: devcontainer(project) },

package/dist/surfaces/agents.test.js

@@ -108,6 +108,18 @@ describe("agents", () => {
         expect(setup).toContain("npx toolfactory check >/dev/null");
         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/dist/surfaces/claude.js

@@ -5,7 +5,7 @@
  * `claude plugin marketplace add <owner>/<repo>` (and Copilot CLI's identical command) installs.
  */
 import { githubSlug } from "../hosts/github.js";
-import { compact, configProperties, envName, has, isSensitive, json, kernelLaunch, mcpVerdict, requiredConfig, } from "./shared.js";
+import { compact, configProperties, envName, has, isSensitive, kernelLaunch, mcpVerdict, requiredConfig, } from "./shared.js";
 export const surface = {
     id: "claude",
     plan(project) {
@@ -61,8 +61,13 @@ export const 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/dist/surfaces/codex.js

@@ -8,7 +8,7 @@
  * this surface does not reach.
  */
 import { projectName } from "../identity/name.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";
 export const surface = {
@@ -60,8 +60,13 @@ export const 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/dist/surfaces/codex.test.js

@@ -29,9 +29,9 @@ 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: [
@@ -59,18 +59,18 @@ 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")
+        if (manifest?.kind !== "merge")
             throw new Error("expected a manifest");
-        expect(JSON.parse(manifest.content)).toMatchObject({ skills: "./skills/" });
-        expect(JSON.parse(manifest.content)).not.toHaveProperty("mcpServers");
+        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")
+        if (manifest?.kind !== "merge")
             throw new Error("expected a manifest");
-        const parsed = JSON.parse(manifest.content);
+        const parsed = manifest.patch;
         expect(parsed.skills).toBe("./skills/");
         expect(parsed).not.toHaveProperty("mcpServers");
     });

package/dist/surfaces/cursor.js

@@ -3,7 +3,7 @@
  * and the bundle's `mcp.json` is shared. Loader unverified, like Codex.
  */
 import { projectName } from "../identity/name.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 = {
     id: "cursor",
     plan(project) {
@@ -39,7 +39,7 @@ export const 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/dist/surfaces/distribution.test.js

@@ -165,9 +165,9 @@ 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/dist/surfaces/dsh.js

@@ -21,7 +21,7 @@
 import { Scalar, stringify as yamlStringify } from "yaml";
 import { getBinding } from "../bindings/index.js";
 import { projectName } from "../identity/name.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
  * lags the alpha line by weeks, so an unpinned install is neither current nor reproducible.
@@ -37,6 +37,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";
 /** `headless` is one-shot and ships an app bundle; a profile without one blocks forever. */
@@ -80,7 +82,11 @@ function patch(project, launch) {
             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() {
+    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. */
 export function toolName(project, operation) {
@@ -108,20 +114,34 @@ export const 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/dist/surfaces/dsh.test.js

@@ -1,5 +1,9 @@
+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 { apply, replaceRegions } from "../project/apply.js";
 import { DSH_PIN, surface as dsh } from "./dsh.js";
 const echo = { name: "echo", inputSchema: { type: "object" }, requires: [] };
 const browse = {
@@ -31,11 +35,41 @@ const project = {
     packageManager: "npm",
 };
 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/dist/surfaces/gemini.js

@@ -19,7 +19,7 @@
  */
 import { projectName } from "../identity/name.js";
 import { AGENTS_PATH } from "./agents.js";
-import { compact, configProperties, envName, isSensitive, json, kernelLaunch, mcpVerdict, } from "./shared.js";
+import { compact, configProperties, envName, isSensitive, kernelLaunch, mcpVerdict, } from "./shared.js";
 export const MANIFEST_PATH = "gemini-extension.json";
 /**
  * The `@google/gemini-cli` release `validate()` runs. Pinned so the gate is reproducible;
@@ -48,7 +48,7 @@ export const 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

package/dist/surfaces/gemini.test.js

@@ -30,9 +30,9 @@ const project = {
     packageManager: "npm",
 };
 const [manifestFile, ...rest] = gemini.plan(project);
-if (manifestFile?.kind !== "file")
-    throw new Error("expected one whole file");
-const manifest = JSON.parse(manifestFile.content);
+if (manifestFile?.kind !== "merge")
+    throw new Error("expected one merge file");
+const manifest = manifestFile.patch;
 describe("gemini", () => {
     it("is one root manifest: a dashed name, the kernel launch, AGENTS.md as the context file", () => {
         expect(rest).toEqual([]);
@@ -54,7 +54,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", () => {
         expect(gemini.validate?.(project)).toEqual([

package/dist/surfaces/hermes-native.js

@@ -25,8 +25,6 @@
  * support. The fake-ctx test gets the same behavioural coverage with no Hermes import at all.
  */
 import { join } from "node:path";
-import { stringify as toml } from "smol-toml";
-import { stringify as yaml } from "yaml";
 import { KERNEL_DIR } from "../bindings/typescript.js";
 import { projectName } from "../identity/name.js";
 import { isPortable } from "../model.js";
@@ -57,6 +55,8 @@ export function hermesInstall() {
     return `curl -fsSL ${HERMES_PIN.installer} | bash -s -- --commit ${HERMES_PIN.commit} --skip-setup --skip-browser --skip-computer-use --non-interactive --no-skills`;
 }
 const HEADER = "# Generated by toolfactory. Do not edit; run `toolfactory build` to regenerate.\n";
+const INIT_BEGIN = "# tf:init";
+const INIT_END = "# /tf:init";
 /**
  * The plugin package. It is a sibling of the author's own package rather than part of it: a
  * Hermes directory plugin *is* a Python package, and the two must be importable side by side.
@@ -243,7 +243,7 @@ function manifest(project, operations) {
         optional_env: optional.length ? optional : undefined,
         python_dependencies: core ? [core] : undefined,
     });
-    return `${HEADER}${yaml(document)}`;
+    return document;
 }
 function pyproject(project) {
     const core = pinnedCore(project) ?? pypiName(project);
@@ -270,7 +270,7 @@ function pyproject(project) {
                 : undefined,
         }),
     });
-    return `${toml(document)}\n`;
+    return document;
 }
 /** isort order: plain `import` before `from`, alphabetical within each. */
 function sortImports(lines) {
@@ -357,7 +357,7 @@ def _handler(name: str) -> Callable[..., str]:
     return call`,
     };
 }
-function initPy(project, operations) {
+function initRegion(project, operations) {
     const core = project.tool.binding === "python" ? pythonCore(project) : typescriptCore(project);
     const names = envDeclarations(project).required.map((entry) => entry.name);
     return `${HEADER}"""Hermes plugin for ${project.identity.name}, registered through PluginContext.
@@ -385,7 +385,7 @@ def _ready() -> bool:
 ${core.body}
 
 
-def register(ctx: Any) -> None:
+def _register_generated(ctx: Any) -> None:
     # Hermes' own per-plugin data directory, through the variable every host uses.
     os.environ.setdefault(${JSON.stringify(dataDirEnvName(project))}, str(ctx.state.data_dir))
     for schema in TOOLS:
@@ -398,6 +398,20 @@ def register(ctx: Any) -> None:
             requires_env=list(REQUIRES_ENV),
             description=schema["description"],
         )
+
+
+def register(ctx: Any) -> None:
+    _register_generated(ctx)
+    register_native(ctx)
+`;
+}
+function initTemplate() {
+    return `${INIT_BEGIN}${INIT_END}
+
+
+# Yours: use the full PluginContext here. This hook runs after Toolfactory's generated tools.
+def register_native(ctx: Any) -> None:
+    pass
 `;
 }
 function readme(project, operations) {
@@ -474,9 +488,24 @@ export const surface = {
         const operations = includedOperations(project, surface);
         const dir = pluginDir(project);
         return [
-            { kind: "file", path: `${dir}/plugin.yaml`, content: manifest(project, operations) },
-            { kind: "file", path: `${dir}/__init__.py`, content: initPy(project, operations) },
-            { kind: "file", path: `${HOST_DIR}/pyproject.toml`, content: pyproject(project) },
+            {
+                kind: "merge",
+                path: `${dir}/plugin.yaml`,
+                format: "yaml",
+                patch: manifest(project, operations),
+            },
+            {
+                kind: "region",
+                path: `${dir}/__init__.py`,
+                regions: [{ begin: INIT_BEGIN, end: INIT_END, content: initRegion(project, operations) }],
+                template: initTemplate(),
+            },
+            {
+                kind: "merge",
+                path: `${HOST_DIR}/pyproject.toml`,
+                format: "toml",
+                patch: pyproject(project),
+            },
             { kind: "file", path: `${HOST_DIR}/README.md`, content: readme(project, operations) },
             {
                 kind: "file",

package/dist/surfaces/hermes-native.test.js

@@ -1,10 +1,11 @@
 import { execFileSync } from "node:child_process";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
-import { parse as parseToml } from "smol-toml";
+import { join } from "node:path";
+import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
 import { describe, expect, it } from "vitest";
-import { parse as parseYaml } from "yaml";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { apply } from "../project/apply.js";
 import { HOST_DIR, pluginDir, surface } from "./hermes-native.js";
 const echo = {
     name: "echo",
@@ -56,10 +57,35 @@ function project(overrides = {}) {
     };
 }
 function emitted(target) {
-    return Object.fromEntries(surface.plan(target).map((file) => [file.path, file.kind === "file" ? file.content : ""]));
+    return Object.fromEntries(surface
+        .plan(target)
+        .map((file) => [
+        file.path,
+        file.kind === "file"
+            ? file.content
+            : file.kind === "merge"
+                ? file.format === "yaml"
+                    ? stringifyYaml(file.patch)
+                    : file.format === "toml"
+                        ? stringifyToml(file.patch)
+                        : JSON.stringify(file.patch)
+                : file.regions.map((region) => region.content).join(""),
+    ]));
 }
 const python = project({ tool: { ...project().tool, binding: "python" } });
 describe("hermes-native", () => {
+    it("keeps native registrations in the author hook while refreshing generated registrations", () => {
+        const root = mkdtempSync(join(tmpdir(), "toolfactory-hermes-region-"));
+        const target = { ...project(), root };
+        apply(root, surface.plan(target), "0.1.0");
+        const path = join(root, pluginDir(target), "__init__.py");
+        writeFileSync(path, readFileSync(path, "utf8").replace("    pass\n", '    ctx.register_tool(name="native", toolset="native", schema={}, handler=lambda _: "{}")\n'));
+        apply(root, surface.plan({ ...target, operations: [echo] }), "0.1.0");
+        const text = readFileSync(path, "utf8");
+        expect(text).toContain('name="native"');
+        expect(text).toContain("def _register_generated(ctx: Any)");
+        expect(text).toContain("_register_generated(ctx)\n    register_native(ctx)");
+    });
     it("projects the manifest Hermes parses and the credentials it prompts for", () => {
         const files = emitted(project());
         const manifest = parseYaml(files[`${pluginDir(project())}/plugin.yaml`] ?? "");
@@ -157,12 +183,7 @@ describe.skipIf(!hasHermes())("hermes plugins doctor", () => {
     it("loads and registers the generated plugin", () => {
         const root = mkdtempSync(join(tmpdir(), "toolfactory-hermes-"));
         try {
-            for (const file of surface.plan(project())) {
-                if (file.kind !== "file")
-                    continue;
-                mkdirSync(dirname(join(root, file.path)), { recursive: true });
-                writeFileSync(join(root, file.path), file.content);
-            }
+            apply(root, surface.plan(project()), "0.1.0");
             const commands = surface.validate?.({ ...project(), root }) ?? [];
             const command = commands.find((c) => c.label === "hermes plugins doctor");
             if (!command)