diff --git a/.vscode/settings.json b/.vscode/settings.json
index 8a290211..3f32d63a 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -3,6 +3,7 @@
         "agno",
         "asyncio",
         "genai",
+        "getpid",
         "Gopls",
         "langsrv",
         "multilspy",
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e56d6ad1..5f4be5ce 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,13 +4,16 @@ Changes prior to the next official version change will appear here.
 
 # 2025-04-07
 
+> **Breaking Config Changes**: make sure to set `ignore_all_files_in_gitignore`, remove `ignore_dirs`
+>  and (optionally) set `ignore_paths` in your project configs. See [updated config template](myproject.template.yml)
+
 * Serena core:
     * New tool: FindReferencingCodeSnippets
     * Adjusted prompt in CreateTextFileTool to prevent writing partial content (see [here](https://www.reddit.com/r/ClaudeAI/comments/1jpavtm/comment/mloek1x/?utm_source=share&utm_medium=web3x&utm_name=web3xcss&utm_term=1&utm_content=share_button)).
     * FindSymbolTool: allow passing a file for restricting search, not just a directory (Gemini was too dumb to pass directories)
     * Native support for gitignore files for configuring files to be ignored by serena. See also
       in *Language Servers* section below.
-    * Allow Serena to switch between projects (project activation)
+    * **Major Feature**: Allow Serena to switch between projects (project activation)
         * Add central Serena configuration in `serena_config.yml`, which 
             * contains the list of available projects
             * allows to configure whether project activation is enabled
diff --git a/README.md b/README.md
index 8c8770ac..01724720 100644
--- a/README.md
+++ b/README.md
@@ -65,6 +65,14 @@ implementation.
 
 Coming soon: Kotlin and Dart.
 
+
+> ⚠️ **Note:** Serena is under active development, we are continuously adding features, improving stability and UX.
+> As a result, configuration might change in a breaking way. If you have an invalid configuration,
+> the MCP server (or the Serena Agent) may not start properly (investigate the MCP logs in the former case). 
+> Check the [changelog](CHANGELOG.md)
+> and the configuration templates when updating Serena and update your configs accordingly.
+
+
 ## Table of Contents
 
 <!-- Created with  markdown-toc -i README.md -->
diff --git a/myproject.template.yml b/myproject.template.yml
index 5aca9627..51191a45 100644
--- a/myproject.template.yml
+++ b/myproject.template.yml
@@ -8,10 +8,13 @@ project_root: /path/to/project
 language: python
 
 # whether to use the project's gitignore file to ignore files
+# Added on 2025-04-07
 ignore_all_files_in_gitignore: true
 
 # list of additional paths to ignore
 # same syntax as gitignore, so you can use * and **
+# Was previously called `ignored_dirs`, please update your config if you are using that.
+# Added (renamed)on 2025-04-07
 ignored_paths: []
 
 
diff --git a/src/serena/agent.py b/src/serena/agent.py
index 3f45abb0..a8dca604 100644
--- a/src/serena/agent.py
+++ b/src/serena/agent.py
@@ -37,6 +37,10 @@ TTool = TypeVar("TTool", bound="Tool")
 SUCCESS_RESULT = "OK"
 
 
+class SerenaConfigError(Exception):
+    pass
+
+
 class ProjectConfig(ToStringMixin):
     SERENA_MANAGED_DIR = ".serena"
     SERENA_DEFAULT_PROJECT_FILE = "project.yml"
@@ -49,10 +53,20 @@ class ProjectConfig(ToStringMixin):
         self.project_root: str = str(project_root.resolve())
         self.ignored_paths: list[str] = config_dict.get("ignored_paths", [])
         self.excluded_tools: set[str] = set(config_dict.get("excluded_tools", []))
-        self.ignore_all_files_in_gitignore = config_dict.get("ignore_all_files_in_gitignore", True)
 
-        # backwards compatibility
-        self.ignored_paths.extend(config_dict.get("ignored_dirs", []))
+        if "ignore_all_files_in_gitignore" not in config_dict:
+            raise SerenaConfigError(
+                "`ignore_all_files_in_gitignore` key not found in project configuration. Please update your `project.yml` file."
+                "It is recommended to set this to `True`."
+            )
+        self.ignore_all_files_in_gitignore = config_dict["ignore_all_files_in_gitignore"]
+
+        # Raise errors for deprecated keys
+        if "ignored_dirs" in config_dict:
+            raise SerenaConfigError(
+                "`ignored_dirs` key is deprecated. Please use `ignored_paths` instead."
+                "Note that you can also set `ignore_all_files_in_gitignore` to `True`, which will be enough for most cases."
+            )
 
     @classmethod
     def from_yml(cls, yml_path: Path) -> Self:
@@ -95,7 +109,9 @@ class SerenaConfig:
 
         # read projects
         self.projects: dict[str, ProjectConfig] = {}
-        for project_config_path in config_yaml.get("projects", []):
+        if "projects" not in config_yaml:
+            raise SerenaConfigError("`projects` key not found in Serena configuration. Please update your `serena_config.yml` file.")
+        for project_config_path in config_yaml["projects"]:
             project_config_path = Path(project_config_path)
             if not project_config_path.is_absolute():
                 project_config_path = Path(serena_root_path()) / project_config_path