Introduce system defaults (vs system overrides) (#6724)

docs/cli/enterprise.md

@@ -6,23 +6,27 @@ This document outlines configuration patterns and best practices for deploying a
 
 ## Centralized Configuration: The System Settings File
 
-The most powerful tool for enterprise administration is the system-wide `settings.json` file. This file allows you to define a baseline configuration that applies to all users on a machine. For a complete overview of configuration options, see the [Configuration documentation](./configuration.md). Settings from system, user, and project-level `settings.json` files are merged together. For most settings, the system-wide configuration takes precedence, overriding any conflicting user or project-level settings. However, some settings, like `customThemes`, `mcpServers`, and `includeDirectories`, are merged from all configuration files, and if there are conflicting values (e.g., both workspace and system settings have a 'github' MCP server defined), the system value will take precedence.
+The most powerful tools for enterprise administration are the system-wide settings files. These files allow you to define a baseline configuration (`system-defaults.json`) and a set of overrides (`settings.json`) that apply to all users on a machine. For a complete overview of configuration options, see the [Configuration documentation](./configuration.md).
+
+Settings are merged from four files. The precedence order for single-value settings (like `theme`) is:
+
+1. System Defaults (`system-defaults.json`)
+2. User Settings (`~/.gemini/settings.json`)
+3. Workspace Settings (`<project>/.gemini/settings.json`)
+4. System Overrides (`settings.json`)
+
+This means the System Overrides file has the final say. For settings that are arrays (`includeDirectories`) or objects (`mcpServers`), the values are merged.
 
 **Example of Merging and Precedence:**
 
 Here is how settings from different levels are combined.
 
-- **System `settings.json`:**
+- **System Defaults `system-defaults.json`:**
 
   ```json
   {
-    "theme": "system-enforced-theme",
-    "mcpServers": {
-      "corp-server": {
-        "command": "/usr/local/bin/corp-server-prod"
-      }
-    },
-    "includeDirectories": ["/etc/gemini-cli/global-context"]
+    "theme": "default-corporate-theme",
+    "includeDirectories": ["/etc/gemini-cli/common-context"]
   }
   ```
 
@@ -44,6 +48,7 @@ Here is how settings from different levels are combined.
   ```
 
 - **Workspace `settings.json` (`<project>/.gemini/settings.json`):**
+
   ```json
   {
     "theme": "project-specific-light-theme",
@@ -56,6 +61,19 @@ Here is how settings from different levels are combined.
   }
   ```
 
+- **System Overrides `settings.json`:**
+  ```json
+  {
+    "theme": "system-enforced-theme",
+    "mcpServers": {
+      "corp-server": {
+        "command": "/usr/local/bin/corp-server-prod"
+      }
+    },
+    "includeDirectories": ["/etc/gemini-cli/global-context"]
+  }
+  ```
+
 This results in the following merged configuration:
 
 - **Final Merged Configuration:**
@@ -74,18 +92,19 @@ This results in the following merged configuration:
       }
     },
     "includeDirectories": [
-      "/etc/gemini-cli/global-context",
+      "/etc/gemini-cli/common-context",
       "~/gemini-context",
-      "./project-context"
+      "./project-context",
+      "/etc/gemini-cli/global-context"
     ]
   }
   ```
 
 **Why:**
 
-- **`theme`**: The value from the system settings is used, overriding both user and workspace settings.
-- **`mcpServers`**: The objects are merged. The `corp-server` definition from the system settings takes precedence over the user's definition. The unique `user-tool` and `project-tool` are included.
-- **`includeDirectories`**: The arrays are concatenated in the order of System, User, and then Workspace.
+- **`theme`**: The value from the system overrides (`system-enforced-theme`) is used, as it has the highest precedence.
+- **`mcpServers`**: The objects are merged. The `corp-server` definition from the system overrides takes precedence over the user's definition. The unique `user-tool` and `project-tool` are included.
+- **`includeDirectories`**: The arrays are concatenated in the order of System Defaults, User, Workspace, and then System Overrides.
 
 - **Location**:
   - **Linux**: `/etc/gemini-cli/settings.json`