diff --git a/README.md b/README.md
index 84cb122f..d26bdad8 100644
--- a/README.md
+++ b/README.md
@@ -28,6 +28,12 @@ more complex codebases.
> Do not install Serena via an MCP or plugin marketplace! They contain outdated and suboptimal installation commands.
> Instead, follow our [Quick Start](#quick-start) instructions.
+## Quick Demo
+
+https://github.com/user-attachments/assets/8d11646e-b80e-4723-b9d7-32d6101b5f58
+
+:tv: Longer video: [Introduction to Serena in 5 Minutes (YouTube)](https://www.youtube.com/watch?v=5QN7gN1KYLA)
+
## What Our "End Users" Say
While it is humans who download and set up Serena, our end users are essentially AI agents.
@@ -72,16 +78,12 @@ Most modern AI chat clients directly support MCP, including
+:tv: See also: [Introduction to Serena in 5 Minutes (YouTube)](https://www.youtube.com/watch?v=5QN7gN1KYLA)
+
To connect the Serena MCP server to your client, you either
* provide the client with a launch command that allows it to start the MCP server, or
* start the Serena MCP server yourself in HTTP mode and provide the client with the URL.
-Serena's tools are powered by two alternative language intelligence backends:
- * With the SolidLSP backend (default), language servers for the selected programming languages will be started
-automatically for your project.
- * With the JetBrains backend, the Serena JetBrains plugin must be installed in your IDE and
-the project you want to work on must open and set up.
-
See the [Quick Start](#quick-start) section below for information on how to get started.
## Programming Language Support & Semantic Analysis Capabilities
@@ -97,7 +99,7 @@ There are two alternative technologies powering these capabilities:
* **Language servers** implementing the language server protocol (LSP) — the free/open-source alternative
which is used by default.
-* The **Serena JetBrains Plugin**, which leverages the powerful code analysis and editing
+* **The Serena JetBrains Plugin**, which leverages the powerful code analysis and editing
capabilities of your JetBrains IDE (paid plugin; free trial available).
You can choose either of these backends depending on your preferences and requirements.
@@ -203,25 +205,6 @@ To achieve this, Serena offers multiple levels of (composable) configuration:
-## Serena in Action
-
-
-Demonstrations
-
-#### Demonstration 1: Efficient Operation in Claude Code
-
-A demonstration of Serena efficiently retrieving and editing code within Claude Code, thereby saving tokens and time. Efficient operations are not only useful for saving costs, but also for generally improving the generated code's quality. This effect may be less pronounced in very small projects, but often becomes of crucial importance in larger ones.
-
-https://github.com/user-attachments/assets/ab78ebe0-f77d-43cc-879a-cc399efefd87
-
-#### Demonstration 2: Serena in Claude Desktop
-
-A demonstration of Serena implementing a small feature for itself (a better log GUI) with Claude Desktop.
-Note how Serena's tools enable Claude to find and edit the right symbols.
-
-https://github.com/user-attachments/assets/6eaa9aa1-610d-4723-a2d6-bf1e487ba753
-
-
## Quick Start
**Prerequisites**. Serena is managed by *uv*, and [installing uv](https://docs.astral.sh/uv/getting-started/installation/) is the only required prerequisite.
diff --git a/docs/02-usage/025_jetbrains_plugin.md b/docs/02-usage/025_jetbrains_plugin.md
index 5a0a16f2..1995ca34 100644
--- a/docs/02-usage/025_jetbrains_plugin.md
+++ b/docs/02-usage/025_jetbrains_plugin.md
@@ -2,7 +2,7 @@
The [JetBrains Plugin](https://plugins.jetbrains.com/plugin/28946-serena/) allows the Serena MCP server to
leverage the powerful code analysis and editing capabilities of your JetBrains IDE.
-This page explains how to install the plugin and how to configure Serena for using it.
+This page explains how to install the plugin and how to configure Serena appropriately.
You will still need to set up the Serena MCP server
itself, so make sure to follow the [installation instructions](020_running.md) and connect the MCP server to your
LLM-based client as described in [client setup](030_clients.md) in addition to following the instructions below.
@@ -18,20 +18,20 @@ LLM-based client as described in [client setup](030_clients.md) in addition to f
We recommend the JetBrains plugin as the preferred way of using Serena,
especially for users of JetBrains IDEs.
-```{admonition} *Note:* The plugin is a language intelligence backend for the Serena MCP server.
-:class: note
-It is *not* a UI extension for direct agent interaction (like Copilot) or anything of the sort.
-You still interact with your regular client – be it external to your IDE (like Claude Code) or internal (like JetBrains AI Assistant) –
-and connect it to the Serena MCP server.
-The plugin simply enables the Serena MCP server to directly leverage capabilities of your JetBrains IDE!
-```
-
**How it works:**
1. Install the plugin in your JetBrains IDE
2. Configure Serena to use the JetBrains language backend (see [below](configure-jetbrains))
3. Open the project you want to work on in your JetBrains IDE and activate it in Serena (see [below](jetbrains-workflow))
4. Start coding via your MCP client as usual
+```{admonition} *Note:* The plugin is a language intelligence backend for the Serena MCP server.
+:class: note
+It is *not* a UI extension for direct agent interaction (like Copilot) or anything of the sort.
+You still interact with your regular client – be it external to your IDE (like Claude Code CLI) or internal (like Copilot or JetBrains AI Assistant) –
+and connect it to the Serena MCP server.
+The plugin simply enables the Serena MCP server to directly leverage capabilities of your JetBrains IDE!
+```
+
**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.
@@ -82,7 +82,7 @@ language_backend: JetBrains
Note that the file might not exist yet if you never executed Serena before.
-**Per-Instance Configuration**.
+**Per-Server 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.
@@ -119,9 +119,10 @@ You will also notice that your client will use the JetBrains-specific tools like
Having installed the plugin in your IDE and having configured Serena to use the JetBrains backend,
the general workflow is simple:
-1. Open the project you want to work on in your JetBrains IDE
-2. Activate the project's root folder as a project in Serena (see [Project Creation](project-creation-indexing) and [Project Activation](project-activation))
-3. Start using Serena tools as usual
+1. Open the project you want to work on in your JetBrains IDE.
+ Note that the project must be appropriately set up in your IDE, i.e. symbol lookups for all relevant programming languages and frameworks should work in the IDE.
+2. Activate the project's root folder as a project in Serena (see [Project Creation](project-creation-indexing) and [Project Activation](project-activation)).
+3. Start using Serena's tools as usual.
Note that the project folder that is open in your IDE and the Serena project root folder must match.