From b828b4754b6b2f6d593a995a0af7bfd5cb3d9f33 Mon Sep 17 00:00:00 2001
From: Shehab <127568346+ashmod@users.noreply.github.com>
Date: Fri, 19 Dec 2025 22:11:37 +0200
Subject: [PATCH] docs(cli): add System Prompt Override (GEMINI_SYSTEM_MD)
 (#9515)

---
 docs/cli/index.md                 |  2 +
 docs/cli/system-prompt.md         | 93 +++++++++++++++++++++++++++++++
 docs/get-started/configuration.md | 12 ++++
 docs/index.md                     |  3 +
 docs/sidebar.json                 |  4 ++
 5 files changed, 114 insertions(+)
 create mode 100644 docs/cli/system-prompt.md

diff --git a/docs/cli/index.md b/docs/cli/index.md
index 3c3421801b..069c802411 100644
--- a/docs/cli/index.md
+++ b/docs/cli/index.md
@@ -38,6 +38,8 @@ overview of Gemini CLI, see the [main documentation page](../index.md).
   files and directories from being accessed by tools.
 - **[Context files (GEMINI.md)](./gemini-md.md):** Provide persistent,
   hierarchical context to the model.
+- **[System prompt override](./system-prompt.md):** Replace the built‑in system
+  instructions using `GEMINI_SYSTEM_MD`.
 
 ## Non-interactive mode
 
diff --git a/docs/cli/system-prompt.md b/docs/cli/system-prompt.md
new file mode 100644
index 0000000000..c7fe5fc4ba
--- /dev/null
+++ b/docs/cli/system-prompt.md
@@ -0,0 +1,93 @@
+# System Prompt Override (GEMINI_SYSTEM_MD)
+
+The core system instructions that guide Gemini CLI can be completely replaced
+with your own Markdown file. This feature is controlled via the
+`GEMINI_SYSTEM_MD` environment variable.
+
+## Overview
+
+The `GEMINI_SYSTEM_MD` variable instructs the CLI to use an external Markdown
+file for its system prompt, completely overriding the built-in default. This is
+a full replacement, not a merge. If you use a custom file, none of the original
+core instructions will apply unless you include them yourself.
+
+This feature is intended for advanced users who need to enforce strict,
+project-specific behavior or create a customized persona.
+
+> Tip: You can export the current default system prompt to a file first, review
+> it, and then selectively modify or replace it (see
+> [“Export the default prompt”](#export-the-default-prompt-recommended)).
+
+## How to enable
+
+You can set the environment variable temporarily in your shell, or persist it
+via a `.gemini/.env` file. See
+[Persisting Environment Variables](../get-started/authentication.md#persisting-environment-variables).
+
+- Use the project default path (`.gemini/system.md`):
+  - `GEMINI_SYSTEM_MD=true` or `GEMINI_SYSTEM_MD=1`
+  - The CLI reads `./.gemini/system.md` (relative to your current project
+    directory).
+
+- Use a custom file path:
+  - `GEMINI_SYSTEM_MD=/absolute/path/to/my-system.md`
+  - Relative paths are supported and resolved from the current working
+    directory.
+  - Tilde expansion is supported (e.g., `~/my-system.md`).
+
+- Disable the override (use built‑in prompt):
+  - `GEMINI_SYSTEM_MD=false` or `GEMINI_SYSTEM_MD=0` or unset the variable.
+
+If the override is enabled but the target file does not exist, the CLI will
+error with: `missing system prompt file '<path>'`.
+
+## Quick examples
+
+- One‑off session using a project file:
+  - `GEMINI_SYSTEM_MD=1 gemini`
+- Persist for a project using `.gemini/.env`:
+  - Create `.gemini/system.md`, then add to `.gemini/.env`:
+    - `GEMINI_SYSTEM_MD=1`
+- Use a custom file under your home directory:
+  - `GEMINI_SYSTEM_MD=~/prompts/SYSTEM.md gemini`
+
+## UI indicator
+
+When `GEMINI_SYSTEM_MD` is active, the CLI shows a `|⌐■_■|` indicator in the UI
+to signal custom system‑prompt mode.
+
+## Export the default prompt (recommended)
+
+Before overriding, export the current default prompt so you can review required
+safety and workflow rules.
+
+- Write the built‑in prompt to the project default path:
+  - `GEMINI_WRITE_SYSTEM_MD=1 gemini`
+- Or write to a custom path:
+  - `GEMINI_WRITE_SYSTEM_MD=~/prompts/DEFAULT_SYSTEM.md gemini`
+
+This creates the file and writes the current built‑in system prompt to it.
+
+## Best practices: SYSTEM.md vs GEMINI.md
+
+- SYSTEM.md (firmware):
+  - Non‑negotiable operational rules: safety, tool‑use protocols, approvals, and
+    mechanics that keep the CLI reliable.
+  - Stable across tasks and projects (or per project when needed).
+- GEMINI.md (strategy):
+  - Persona, goals, methodologies, and project/domain context.
+  - Evolves per task; relies on SYSTEM.md for safe execution.
+
+Keep SYSTEM.md minimal but complete for safety and tool operation. Keep
+GEMINI.md focused on high‑level guidance and project specifics.
+
+## Troubleshooting
+
+- Error: `missing system prompt file '…'`
+  - Ensure the referenced path exists and is readable.
+  - For `GEMINI_SYSTEM_MD=1|true`, create `./.gemini/system.md` in your project.
+- Override not taking effect
+  - Confirm the variable is loaded (use `.gemini/.env` or export in your shell).
+  - Paths are resolved from the current working directory; try an absolute path.
+- Restore defaults
+  - Unset `GEMINI_SYSTEM_MD` or set it to `0`/`false`.
diff --git a/docs/get-started/configuration.md b/docs/get-started/configuration.md
index de675456a6..223f142e97 100644
--- a/docs/get-started/configuration.md
+++ b/docs/get-started/configuration.md
@@ -1129,6 +1129,18 @@ the `advanced.excludedEnvVars` setting in your `settings.json` file.
 - **`GEMINI_SANDBOX`**:
   - Alternative to the `sandbox` setting in `settings.json`.
   - Accepts `true`, `false`, `docker`, `podman`, or a custom command string.
+- **`GEMINI_SYSTEM_MD`**:
+  - Replaces the built‑in system prompt with content from a Markdown file.
+  - `true`/`1`: Use project default path `./.gemini/system.md`.
+  - Any other string: Treat as a path (relative/absolute supported, `~`
+    expands).
+  - `false`/`0` or unset: Use the built‑in prompt. See
+    [System Prompt Override](../cli/system-prompt.md).
+- **`GEMINI_WRITE_SYSTEM_MD`**:
+  - Writes the current built‑in system prompt to a file for review.
+  - `true`/`1`: Write to `./.gemini/system.md`. Otherwise treat the value as a
+    path.
+  - Run the CLI once with this set to generate the file.
 - **`SEATBELT_PROFILE`** (macOS specific):
   - Switches the Seatbelt (`sandbox-exec`) profile on macOS.
   - `permissive-open`: (Default) Restricts writes to the project folder (and a
diff --git a/docs/index.md b/docs/index.md
index 0c6e5b78d8..83e834818e 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -73,6 +73,9 @@ This documentation is organized into the following sections:
 - **[Memport](./core/memport.md):** Using the Memory Import Processor.
 - **[Tools API](./core/tools-api.md):** Information on how the core manages and
   exposes tools.
+- **[System Prompt Override](./cli/system-prompt.md):** Replace built-in system
+  instructions using `GEMINI_SYSTEM_MD`.
+
 - **[Policy Engine](./core/policy-engine.md):** Use the Policy Engine for
   fine-grained control over tool execution.
 
diff --git a/docs/sidebar.json b/docs/sidebar.json
index 9802125258..147bbe106b 100644
--- a/docs/sidebar.json
+++ b/docs/sidebar.json
@@ -115,6 +115,10 @@
       {
         "label": "Uninstall",
         "slug": "docs/cli/uninstall"
+      },
+      {
+        "label": "System prompt override",
+        "slug": "docs/cli/system-prompt"
       }
     ]
   },