From e4d80a330f2ab36d1852267436f24a8d5739377e Mon Sep 17 00:00:00 2001
From: Michael Panchenko <michael.panchenko@oraios-ai.de>
Date: Tue, 16 Dec 2025 22:45:35 +0700
Subject: [PATCH] Documentation on the jetbrains plugin

---
 README.md                                     |  2 ++
 docs/02-usage/020_running.md                  |  7 ++++
 docs/02-usage/025_jetbrains_plugin.md         | 32 +++++++++++++++++++
 .../resources/serena_config.template.yml      |  4 +--
 4 files changed, 43 insertions(+), 2 deletions(-)
 create mode 100644 docs/02-usage/025_jetbrains_plugin.md

diff --git a/README.md b/README.md
index 49c715be..028be352 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,8 @@ Instead, it can use code-centric tools like `find_symbol`, `find_referencing_sym
   <a href="lessons_learned.md"><img src="https://img.shields.io/badge/Lessons-Learned-7c4700?style=flat&logo=readthedocs&logoColor=white&labelColor=7c4700" alt="Lessons Learned" /></a>
 </p>
 
+> NEWS: Serena 1.0.0 and Serena JetBrains plugin have been released! Check out [the documentation](https://oraios.github.io/serena/02-usage/025_jetbrains_plugin.html).
+
 ## LLM Integration
 
 Serena provides the necessary [tools](https://oraios.github.io/serena/01-about/035_tools.html) for coding workflows, but an LLM is required to do the actual work,
diff --git a/docs/02-usage/020_running.md b/docs/02-usage/020_running.md
index 231dd70c..e6126b32 100644
--- a/docs/02-usage/020_running.md
+++ b/docs/02-usage/020_running.md
@@ -11,6 +11,13 @@ This section describes
 In the following, we will refer to the command used to run Serena as `<serena>`,
 which you should replace with the appropriate command based on your chosen method.
 
+:::{note}
+By default, Serena will use language servers for code understanding and analysis.
+We provide a powerful alternative to that through the [Serena JetBrains Plugin](025_jetbrains_plugin),
+which has several advantages over the language server approach.
+Note that you don't have to use a JetBrains IDE as your editor to take advantage of this solution.
+:::
+
 ### Using uvx
 
 `uvx` is part of `uv`. It can be used to run the latest version of Serena directly from the repository, without an explicit local installation.
diff --git a/docs/02-usage/025_jetbrains_plugin.md b/docs/02-usage/025_jetbrains_plugin.md
new file mode 100644
index 00000000..05a1693f
--- /dev/null
+++ b/docs/02-usage/025_jetbrains_plugin.md
@@ -0,0 +1,32 @@
+# 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.
+
+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.
+
+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.
+
+## 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.
+
+
+## Usage with Other Editors
+
+We realize that not everyone uses a JetBrains IDE as their main code editor.
+You can still take advantage of the JetBrains plugin by running a JetBrains IDE instance alongside your
+preferred editor. Most JetBrains IDEs have a free community edition that you can use for this purpose.
+You just need to make sure that the project you are working on is open and indexed in the JetBrains IDE, 
+so that Serena can connect to it.
diff --git a/src/serena/resources/serena_config.template.yml b/src/serena/resources/serena_config.template.yml
index 974fe7e5..5a5d587e 100644
--- a/src/serena/resources/serena_config.template.yml
+++ b/src/serena/resources/serena_config.template.yml
@@ -55,8 +55,8 @@ included_optional_tools: []
 
 jetbrains: False
 # whether to enable JetBrains mode and use tools based on the Serena JetBrains IDE plugin
-# instead of language server-based tools
-# NOTE: The plugin is yet unreleased. This is for Serena developers only.
+# instead of language-server-based tools. Requires the Serena JetBrains plugin to be installed and
+# a JetBrains IDE instance to be running with an open project.
 
 
 default_max_tool_answer_chars: 150000