docs: clarify inheritance of global defaults

Fixes #1155

Co-Authored-By: Dominik Jain <dominik.jain@oraios-ai.de>
Co-Authored-By: Claude <noreply@anthropic.com>

docs/02-usage/040_workflow.md

@@ -57,7 +57,12 @@ The file allows you to configure ...
   * the set of tools and modes to use by default
 
 For detailed information on the parameters and possible settings, see the 
-[template file](https://github.com/oraios/serena/blob/main/src/serena/resources/project.template.yml). 
+[template file](https://github.com/oraios/serena/blob/main/src/serena/resources/project.template.yml).
+
+:::{note}
+Many settings in project.yml *extend* or *override* settings in the global configuration file `serena_config.yml`.
+So use the project configuration specifically for aspects that apply only to the particular project.
+:::
 
 **Local Overrides**. The project.yml file is intended to be versioned together with the project.
 You can specify local overrides for the settings in a `project.local.yml` file in the same directory

docs/02-usage/050_configuration.md

@@ -33,6 +33,9 @@ Some of the configurable settings include:
   * logging settings
   * advanced settings specific to individual language servers (see [below](ls-specific-settings))
 
+The global configuration settings apply to all projects.
+Some of the settings it contains can, however, be *extended* or *overridden* in project-specific settings, contexts and modes.
+
 For detailed information on the parameters and possible settings, see the
 [template file](https://github.com/oraios/serena/blob/main/src/serena/resources/serena_config.template.yml).
 

src/serena/resources/project.template.yml

@@ -56,7 +56,9 @@ ignored_paths: []
 # Added on 2025-04-18
 read_only: false
 
-# list of tool names to exclude. We recommend not excluding any tools, see the readme for more details.
+# list of tool names to exclude.
+# This extends the existing exclusions (e.g. from the global configuration)
+#
 # Below is the complete list of tools for convenience.
 # To make sure you have the latest list of tools, and to view their descriptions, 
 # execute `uv run scripts/print_tool_overview.py`.
@@ -97,7 +99,8 @@ read_only: false
 #  * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
 excluded_tools: []
 
-# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default)
+# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default).
+# This extends the existing inclusions (e.g. from the global configuration).
 included_optional_tools: []
 
 # fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools.