Docs: document per-project language_backend override; move field to SharedConfig

- Add "Per-Project Configuration" section to JetBrains plugin docs
  with cross-reference anchor for linking from other pages
- Add language_backend to project configuration feature list in workflow docs
- Add cross-reference from global config docs to per-project override
- Move language_backend field from ProjectConfig to SharedConfig,
  following the same pattern as symbol_info_budget (review feedback)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/02-usage/025_jetbrains_plugin.md

@@ -48,10 +48,31 @@ language_backend: JetBrains
 *Note*: you can also use the button `Edit Global Serena Config` in the Serena MCP dashboard to open the config file in your default editor.
 
 **Per-Instance Configuration**.
-The configuration setting in the global config file can be overridden on a 
-per-instance basis by providing the arguments `--language-backend JetBrains` when 
+The configuration setting in the global config file can be overridden on a
+per-instance basis by providing the arguments `--language-backend JetBrains` when
 launching the Serena MCP server.
 
+(per-project-language-backend)=
+**Per-Project Configuration**.
+You can also set the language backend on a per-project basis in the project's
+`.serena/project.yml` file:
+
+```yaml
+language_backend: JetBrains
+```
+
+If set, this overrides the global `language_backend` setting for the session when the project is
+activated at startup (via the `--project` flag).
+
+:::{important}
+The language backend is determined once at startup and cannot be changed during a running session.
+If a project with a different backend is activated after startup, Serena will return an error.
+
+If you need to work with projects that use different backends, you can either:
+1. Use the `--project` flag to activate the project at startup, which will use its configured backend.
+2. Configure separate MCP server instances (one per backend) in your client.
+:::
+
 **Verifying the Setup**.
 You can verify that Serena is using the JetBrains plugin by either checking the dashboard, where
 you will see `Languages:

docs/02-usage/040_workflow.md

@@ -46,12 +46,13 @@ After creation, you can adjust the project settings in the generated `.serena/pr
 within the project directory.
 
 The file allows you to configure ...
-  * the set of programming languages for which language servers are spawned (not relevant when using the JetBrains plugin)  
+  * the set of programming languages for which language servers are spawned (not relevant when using the JetBrains plugin)
     Note that you can dynamically add/remove language servers while Serena is running via the [Dashboard](060_dashboard).
+  * the [language backend](per-project-language-backend) to use for this project (overriding the global setting)
   * the encoding used in source files
   * ignore rules
   * write access
-  * an initial prompt that shall be passed to the LLM whenever the project is activated 
+  * an initial prompt that shall be passed to the LLM whenever the project is activated
   * the name by which you want to refer to the project (relevant when telling the LLM to dynamically activate the project)
   * the set of tools and modes to use by default
 

docs/02-usage/050_configuration.md

@@ -23,7 +23,8 @@ The global configuration file allows you to change general settings and defaults
 ### Settings
 
 Some of the configurable settings include:
-  * the language backend to use by default (i.e., the JetBrains plugin or language servers)
+  * the language backend to use by default (i.e., the JetBrains plugin or language servers);
+    this can also be [overridden per project](per-project-language-backend)
   * UI settings affecting the [Serena Dashboard and GUI tool](060_dashboard.md)
   * the set of tools to enable/disable by default
   * the set of modes to use by default

src/serena/config/serena_config.py

@@ -134,24 +134,6 @@ class ModeSelectionDefinition:
     default_modes: Sequence[str] | None = None
 
 
-@dataclass
-class SharedConfig(ModeSelectionDefinition, ToolInclusionDefinition, ToStringMixin):
-    """Shared between SerenaConfig and ProjectConfig, the latter used to override values in the form
-    (same as in ModeSelectionDefinition).
-    The defaults here shall be none and should be set to the global default values in SerenaConfig.
-    """
-
-    symbol_info_budget: float | None = None
-
-
-class SerenaConfigError(Exception):
-    pass
-
-
-def get_serena_managed_in_project_dir(project_root: str | Path) -> str:
-    return os.path.join(project_root, SERENA_MANAGED_DIR_NAME)
-
-
 class LanguageBackend(Enum):
     LSP = "LSP"
     """
@@ -172,6 +154,25 @@ class LanguageBackend(Enum):
         raise ValueError(f"Unknown language backend '{backend_str}': valid values are {[b.value for b in LanguageBackend]}")
 
 
+@dataclass
+class SharedConfig(ModeSelectionDefinition, ToolInclusionDefinition, ToStringMixin):
+    """Shared between SerenaConfig and ProjectConfig, the latter used to override values in the form
+    (same as in ModeSelectionDefinition).
+    The defaults here shall be none and should be set to the global default values in SerenaConfig.
+    """
+
+    symbol_info_budget: float | None = None
+    language_backend: LanguageBackend | None = None
+
+
+class SerenaConfigError(Exception):
+    pass
+
+
+def get_serena_managed_in_project_dir(project_root: str | Path) -> str:
+    return os.path.join(project_root, SERENA_MANAGED_DIR_NAME)
+
+
 @dataclass(kw_only=True)
 class ProjectConfig(SharedConfig):
     project_name: str
@@ -181,11 +182,6 @@ class ProjectConfig(SharedConfig):
     ignore_all_files_in_gitignore: bool = True
     initial_prompt: str = ""
     encoding: str = DEFAULT_SOURCE_FILE_ENCODING
-    language_backend: LanguageBackend | None = None
-    """
-    The language backend to use for this project.
-    If None, the global setting from SerenaConfig is used.
-    """
 
     SERENA_DEFAULT_PROJECT_FILE = "project.yml"
     FIELDS_WITHOUT_DEFAULTS = {"project_name", "languages"}