From b24c9f77179bdd462fe67ec32967355400327f08 Mon Sep 17 00:00:00 2001
From: Dominik Jain <dominik.jain@oraios-ai.de>
Date: Wed, 17 Dec 2025 16:33:01 +0100
Subject: [PATCH] Update JetBrains usage information

---
 docs/02-usage/025_jetbrains_plugin.md | 52 ++++++++++++++++++++-------
 1 file changed, 39 insertions(+), 13 deletions(-)

diff --git a/docs/02-usage/025_jetbrains_plugin.md b/docs/02-usage/025_jetbrains_plugin.md
index 05a1693f..5219c201 100644
--- a/docs/02-usage/025_jetbrains_plugin.md
+++ b/docs/02-usage/025_jetbrains_plugin.md
@@ -1,27 +1,53 @@
 # The Serena JetBrains Plugin
 
 The [JetBrains Plugin](https://plugins.jetbrains.com/plugin/28946-serena/) allows Serena to
-leverage the powerful code analysis capabilities of JetBrains IDEs,
-which offers several advantages over the default language server approach.
+leverage the powerful code analysis and editing capabilities of your JetBrains IDE.
 
-The proceeds from the plugin also allow us to dedicate more resources to further developing and improving Serena.
-We recommend the JetBrains plugin as the preferred way of using Serena, regardless of your choice of code editor.
+```{raw} html
+<p>
+<div id="marketplace-link">
+<script src="https://plugins.jetbrains.com/assets/scripts/mp-widget.js"></script>
+<script>
+  MarketplaceWidget.setupMarketplaceWidget('install', 28946, "#marketplace-link");
+</script>
+</p>
+```
 
-After purchasing and installing the plugin, you need to configure `jetbrains: True` in your `serena_config.yml`.
-Then Serena will automatically connect to an open JetBrains IDE instance.
+We recommend the JetBrains plugin as the preferred way of using Serena,
+especially for users of JetBrains IDEs.
+
+**Purchasing the JetBrains Plugin supports the Serena project.**
+The proceeds from plugin sales allow us to dedicate more resources to further developing and improving Serena.
+
+## Configuring Serena 
+
+After installing the plugin, you need to configure Serena to use it.
+
+**Central Configuration**.
+Edit the global Serena configuration file located at `~/.serena/serena_config.yml` 
+(`%USERPROFILE%\.serena\config.yaml` on Windows).
+Change the `language_backend` setting as follows:
+
+```yaml
+language_backend: JetBrains
+```
+
+**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 
+launching the Serena MCP server.
 
 ## Advantages of the JetBrains Plugin
 
 There are multiple features that are only available when using the JetBrains plugin:
 
-- External libraries are indexed and can be referenced by Serena.
-- No additional runtime resources or downloads are needed for language servers.
-- Faster performance of tools.
-- First-class support for multiple languages and frameworks in a single project.
-
-We are also working on additional features like a `move_symbol` tool and debugging related capabilities that
-will be available exclusively through the JetBrains plugin at first.
+* **External library indexing**: Dependencies and libraries are fully indexed and accessible to Serena
+* **No additional setup**: No need to download or configure separate language servers
+* **Enhanced performance**: Faster tool execution thanks to optimized IDE integration
+* **Multi-language excellence**: First-class support for polyglot projects with multiple languages and frameworks
 
+We are also working on additional features like a `move_symbol` tool and debugging-related capabilities that
+will be available exclusively through the JetBrains plugin.
 
 ## Usage with Other Editors