fix(agents): document skipBootstrap runtime scope and add regression for existing workspace files

lonexreb · lonexreb · commit 4dcbde0fa92c · 2026-04-30T15:53:45.000-05:00
Codex review on PR #75217 noted that the runtime resolver guard correctly honors agents.defaults.skipBootstrap, but the public docs at docs/gateway/config-agents.md still described it as workspace-creation-only, and the diff did not include a regression proving `contextFiles` / `injectedWorkspaceFiles` stay empty when existing workspace files are present and skipBootstrap is true. Align the public contract with the new runtime behavior: - docs/gateway/config-agents.md now describes both effects of skipBootstrap (creation + runtime injection) and points users at `contextInjection: 'never'` if they want to keep files on disk but skip injection only. - src/config/types.agent-defaults.ts JSDoc on `skipBootstrap` mirrors the doc wording so editor hover and SDK consumers see the same contract. Add a regression in src/agents/bootstrap-files.test.ts that exercises the exact failure mode the issue described: write AGENTS.md and SOUL.md into the workspace, then call resolveBootstrapFilesForRun and resolveBootstrapContextForRun with skipBootstrap=true and assert both return empty results. A second case sets skipBootstrap=false / unset and asserts AGENTS.md is still resolved, so the guard does not regress the default path. Refs #75184
diff --git a/docs/gateway/config-agents.md b/docs/gateway/config-agents.md
@@ -59,7 +59,12 @@ Optional default skill allowlist for agents that do not set
 
 ### `agents.defaults.skipBootstrap`
 
-Disables automatic creation of workspace bootstrap files (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`).
+Skips workspace bootstrap files for pre-configured deployments. When set to `true`, OpenClaw both:
+
+1. **Disables automatic creation** of workspace bootstrap files (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`) at workspace setup.
+2. **Skips runtime injection** of any existing workspace bootstrap files into the system prompt on every turn (CLI and embedded runtime).
+
+Use this when the deployment supplies its own system prompt, or when you want a workspace-bootstrap-free environment without keeping stray files out of the prompt manually. If you only want to skip injection but keep the files on disk for tooling, use `agents.defaults.contextInjection: "never"` instead.
 
 ```json5
 {
diff --git a/src/agents/bootstrap-files.test.ts b/src/agents/bootstrap-files.test.ts
@@ -141,6 +141,44 @@ describe("resolveBootstrapFilesForRun", () => {
     expect(agentsContextFiles).toHaveLength(1);
     expect(agentsContextFiles[0]?.content).toBe("workspace rules");
   });
+
+  it("returns no bootstrap files when agents.defaults.skipBootstrap is true even if workspace files exist", async () => {
+    // Regression for #75184: workspace creation already honored skipBootstrap
+    // (agent-command.ts:373 passes ensureBootstrapFiles: !skipBootstrap), but
+    // any workspace that already had AGENTS.md / SOUL.md / etc. on disk would
+    // still be picked up by the runtime resolver and injected into the system
+    // prompt. Honor skipBootstrap at the resolver so existing workspace files
+    // also stay out of injection without forcing users onto contextInjection.
+    const workspaceDir = await makeTempWorkspace("openclaw-skip-bootstrap-");
+    await fs.writeFile(path.join(workspaceDir, "AGENTS.md"), "workspace rules", "utf8");
+    await fs.writeFile(path.join(workspaceDir, "SOUL.md"), "soul content", "utf8");
+
+    const files = await resolveBootstrapFilesForRun({
+      workspaceDir,
+      config: { agents: { defaults: { skipBootstrap: true } } } as never,
+    });
+    expect(files).toEqual([]);
+
+    const context = await resolveBootstrapContextForRun({
+      workspaceDir,
+      config: { agents: { defaults: { skipBootstrap: true } } } as never,
+    });
+    expect(context.contextFiles).toEqual([]);
+  });
+
+  it("still resolves workspace bootstrap files when skipBootstrap is false or unset", async () => {
+    const workspaceDir = await makeTempWorkspace("openclaw-skip-bootstrap-off-");
+    await fs.writeFile(path.join(workspaceDir, "AGENTS.md"), "workspace rules", "utf8");
+
+    const filesUnset = await resolveBootstrapFilesForRun({ workspaceDir });
+    expect(filesUnset.some((file) => file.name === "AGENTS.md" && !file.missing)).toBe(true);
+
+    const filesFalse = await resolveBootstrapFilesForRun({
+      workspaceDir,
+      config: { agents: { defaults: { skipBootstrap: false } } } as never,
+    });
+    expect(filesFalse.some((file) => file.name === "AGENTS.md" && !file.missing)).toBe(true);
+  });
 });
 
 describe("resolveBootstrapContextForRun", () => {
diff --git a/src/config/types.agent-defaults.ts b/src/config/types.agent-defaults.ts
@@ -222,7 +222,14 @@ export type AgentDefaultsConfig = {
   systemPromptOverride?: string;
   /** Provider-independent prompt overlays applied by model family. */
   promptOverlays?: PromptOverlaysConfig;
-  /** Skip bootstrap (BOOTSTRAP.md creation, etc.) for pre-configured deployments. */
+  /**
+   * Skip workspace bootstrap files for pre-configured deployments. When true,
+   * disables automatic creation of `BOOTSTRAP.md` / `AGENTS.md` / `SOUL.md` /
+   * etc., AND skips runtime injection of any existing workspace bootstrap
+   * files into the system prompt (CLI + embedded runtime). Use
+   * `contextInjection: "never"` instead if you want to keep the files on disk
+   * but skip prompt injection only.
+   */
   skipBootstrap?: boolean;
   /**
    * Controls when workspace bootstrap files (AGENTS.md, SOUL.md, etc.) are
