From 56310bad4480d479c6eeb1fb2f5fd81f7f4666db Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 8 Jan 2026 01:36:55 +0100
Subject: [PATCH] docs: add gateway self-update prompt guidance

---
 src/agents/system-prompt.test.ts | 11 +++++++++++
 src/agents/system-prompt.ts      | 14 +++++++++++++-
 2 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/src/agents/system-prompt.test.ts b/src/agents/system-prompt.test.ts
index 5c8f853605..ff3a325927 100644
--- a/src/agents/system-prompt.test.ts
+++ b/src/agents/system-prompt.test.ts
@@ -71,4 +71,15 @@ describe("buildAgentSystemPromptAppend", () => {
     expect(prompt).toContain("Prefer aliases when specifying model overrides");
     expect(prompt).toContain("- Opus: anthropic/claude-opus-4-5");
   });
+
+  it("adds gateway self-update guidance when gateway tool is available", () => {
+    const prompt = buildAgentSystemPromptAppend({
+      workspaceDir: "/tmp/clawd",
+      toolNames: ["gateway", "bash"],
+    });
+
+    expect(prompt).toContain("## Gateway Self-Update");
+    expect(prompt).toContain("config.apply");
+    expect(prompt).toContain("update.run");
+  });
 });
diff --git a/src/agents/system-prompt.ts b/src/agents/system-prompt.ts
index 5dd713657e..1543cc0c82 100644
--- a/src/agents/system-prompt.ts
+++ b/src/agents/system-prompt.ts
@@ -41,7 +41,8 @@ export function buildAgentSystemPromptAppend(params: {
     canvas: "Present/eval/snapshot the Canvas",
     nodes: "List/describe/notify/camera/screen on paired nodes",
     cron: "Manage cron jobs and wake events",
-    gateway: "Restart the running Gateway process",
+    gateway:
+      "Restart, apply config, or run updates on the running Gateway process",
     sessions_list: "List sessions with filters and last messages",
     sessions_history: "Fetch message history for a session",
     sessions_send: "Send a message into another session",
@@ -93,6 +94,7 @@ export function buildAgentSystemPromptAppend(params: {
     toolLines.push(`- ${tool}`);
   }
 
+  const hasGateway = availableTools.has("gateway");
   const thinkHint =
     params.defaultThinkLevel && params.defaultThinkLevel !== "off"
       ? `Default thinking level: ${params.defaultThinkLevel}.`
@@ -161,6 +163,16 @@ export function buildAgentSystemPromptAppend(params: {
         ].join("\n"),
     "TOOLS.md does not control tool availability; it is user guidance for how to use external tools.",
     "",
+    hasGateway ? "## Gateway Self-Update" : "",
+    hasGateway
+      ? [
+          "Use the gateway tool to update or reconfigure this instance when asked.",
+          "Actions: config.get, config.schema, config.apply (validate + write full config, then restart), update.run (update deps or git, then restart).",
+          "After restart, Clawdbot pings the last active session automatically.",
+        ].join("\n")
+      : "",
+    hasGateway ? "" : "",
+    "",
     params.modelAliasLines && params.modelAliasLines.length > 0
       ? "## Model Aliases"
       : "",