labset · viqueen · May 9, 2026 · May 9, 2026 · May 9, 2026 · May 9, 2026
diff --git a/.github/actions/setup-and-build/action.yml b/.github/actions/setup-and-build/action.yml
@@ -17,7 +17,3 @@ runs:
     - name: Run tests
       shell: bash
       run: mise run test
-
-    - name: Verify plugin
-      shell: bash
-      run: mise run verify
diff --git a/README.md b/README.md
@@ -1,117 +1,61 @@
-# IntelliJ Platform Plugin Template
+# jb-plugin
 
-[![Twitter Follow](https://img.shields.io/badge/follow-%40JBPlatform-1DA1F2?logo=twitter)](https://twitter.com/JBPlatform)
-[![Developers Forum](https://img.shields.io/badge/JetBrains%20Platform-Join-blue)][jb:forum]
+A JetBrains IntelliJ Platform plugin built with Kotlin, targeting IntelliJ IDEA 2025.2.4+.
 
-## Plugin template structure
+## Quickstart
 
-A generated project contains the following content structure:
+**Prerequisites:** [mise](https://mise.jdx.dev) (handles JDK 21 automatically via `.mise.toml`).
 
-```
-.
-├── .run/                   Predefined Run/Debug Configurations
-├── build/                  Output build directory
-├── gradle
-│   ├── wrapper/            Gradle Wrapper
-├── src                     Plugin sources
-│   ├── main
-│   │   ├── kotlin/         Kotlin production sources
-│   │   └── resources/      Resources - plugin.xml, icons, messages
-├── .gitignore              Git ignoring rules
-├── build.gradle.kts        Gradle build configuration
-├── gradle.properties       Gradle configuration properties
-├── gradlew                 *nix Gradle Wrapper script
-├── gradlew.bat             Windows Gradle Wrapper script
-├── README.md               README
-└── settings.gradle.kts     Gradle project settings
-```
-
-In addition to the configuration files, the most crucial part is the `src` directory, which contains our implementation
-and the manifest for our plugin – [plugin.xml][file:plugin.xml].
-
-> [!NOTE]
-> To use Java in your plugin, create the `/src/main/java` directory.
-
-## Plugin configuration file
-
-The plugin configuration file is a [plugin.xml][file:plugin.xml] file located in the `src/main/resources/META-INF`
-directory.
-It provides general information about the plugin, its dependencies, extensions, and listeners.
-
-You can read more about this file in the [Plugin Configuration File][docs:plugin.xml] section of our documentation.
-
-If you're still not quite sure what this is all about, read our
-introduction: [What is the IntelliJ Platform?][docs:intro]
-
-$H$H Predefined Run/Debug configurations
-
-Within the default project structure, there is a `.run` directory provided containing predefined *Run/Debug
-configurations* that expose corresponding Gradle tasks:
-
-| Configuration name | Description                                                                                                                                                                         |
-|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Run Plugin         | Runs [`:runIde`][gh:intellij-platform-gradle-plugin-runIde] IntelliJ Platform Gradle Plugin task. Use the *Debug* icon for plugin debugging.                                        |
-| Run Tests          | Runs [`:test`][gradle:lifecycle-tasks] Gradle task.                                                                                                                                 |
-| Run Verifications  | Runs [`:verifyPlugin`][gh:intellij-platform-gradle-plugin-verifyPlugin] IntelliJ Platform Gradle Plugin task to check the plugin compatibility against the specified IntelliJ IDEs. |
-
-> [!NOTE]
-> You can find the logs from the running task in the `idea.log` tab.
-
-## Publishing the plugin
-
-> [!TIP]
-> Make sure to follow all guidelines listed in [Publishing a Plugin][docs:publishing] to follow all recommended and
-> required steps.
+```bash
+# clone and set up toolchain
+git clone <repo-url> && cd jb-plugin
+mise install
 
-Releasing a plugin to [JetBrains Marketplace](https://plugins.jetbrains.com) is a straightforward operation that uses
-the `publishPlugin` Gradle task provided by
-the [intellij-platform-gradle-plugin][gh:intellij-platform-gradle-plugin-docs].
+# build the plugin
+mise run build
 
-You can also upload the plugin to the [JetBrains Plugin Repository](https://plugins.jetbrains.com/plugin/upload)
-manually via UI.
+# run tests
+mise run test
 
-## Useful links
-
-- [IntelliJ Platform SDK Plugin SDK][docs]
-- [IntelliJ Platform Gradle Plugin Documentation][gh:intellij-platform-gradle-plugin-docs]
-- [IntelliJ Platform Explorer][jb:ipe]
-- [JetBrains Marketplace Quality Guidelines][jb:quality-guidelines]
-- [IntelliJ Platform UI Guidelines][jb:ui-guidelines]
-- [JetBrains Marketplace Paid Plugins][jb:paid-plugins]
-- [IntelliJ SDK Code Samples][gh:code-samples]
-
-[docs]: https://plugins.jetbrains.com/docs/intellij
-
-[docs:intro]: https://plugins.jetbrains.com/docs/intellij/intellij-platform.html?from=IJPluginTemplate
-
-[docs:plugin.xml]: https://plugins.jetbrains.com/docs/intellij/plugin-configuration-file.html?from=IJPluginTemplate
-
-[docs:publishing]: https://plugins.jetbrains.com/docs/intellij/publishing-plugin.html?from=IJPluginTemplate
-
-[file:plugin.xml]: ./src/main/resources/META-INF/plugin.xml
-
-[gh:code-samples]: https://github.com/JetBrains/intellij-sdk-code-samples
-
-[gh:intellij-platform-gradle-plugin]: https://github.com/JetBrains/intellij-platform-gradle-plugin
-
-[gh:intellij-platform-gradle-plugin-docs]: https://plugins.jetbrains.com/docs/intellij/tools-intellij-platform-gradle-plugin.html
-
-[gh:intellij-platform-gradle-plugin-runIde]: https://plugins.jetbrains.com/docs/intellij/tools-intellij-platform-gradle-plugin-tasks.html#runIde
+# launch a sandboxed IDE with the plugin installed
+mise run ide
+```
 
-[gh:intellij-platform-gradle-plugin-verifyPlugin]: https://plugins.jetbrains.com/docs/intellij/tools-intellij-platform-gradle-plugin-tasks.html#verifyPlugin
+Run `mise tasks` to see all available tasks.
 
-[gradle:lifecycle-tasks]: https://docs.gradle.org/current/userguide/java_plugin.html#lifecycle_tasks
+If you're using IntelliJ IDEA, open the project and use the predefined **Run IDE with Plugin** run configuration (`.run/Run IDE with Plugin.run.xml`).
 
-[jb:github]: https://github.com/JetBrains/.github/blob/main/profile/README.md
+## Other Commands
 
-[jb:forum]: https://platform.jetbrains.com/
+```bash
+mise run verify              # Check plugin compatibility against the target IDE
+./gradlew publishPlugin      # Publish to JetBrains Marketplace
+```
 
-[jb:quality-guidelines]: https://plugins.jetbrains.com/docs/marketplace/quality-guidelines.html
+See [Publishing a Plugin](https://plugins.jetbrains.com/docs/intellij/publishing-plugin.html) for marketplace setup details.
 
-[jb:paid-plugins]: https://plugins.jetbrains.com/docs/marketplace/paid-plugins-marketplace.html
+## Project Structure
 
-[jb:quality-guidelines]: https://plugins.jetbrains.com/docs/marketplace/quality-guidelines.html
+```
+.
+├── .run/                          Predefined Run/Debug configurations
+├── src/main/
+│   ├── kotlin/org/labset/ide/jbplugin/   Kotlin sources
+│   └── resources/
+│       ├── META-INF/plugin.xml           Plugin manifest
+│       └── messages/                     i18n resource bundles
+├── .mise.toml                     mise toolchain and tasks
+├── build.gradle.kts               Gradle build configuration
+├── gradle.properties              Gradle settings (config cache, build cache)
+└── settings.gradle.kts            Gradle project settings
+```
 
-[jb:ipe]: https://jb.gg/ipe
+## Tech Stack
 
-[jb:ui-guidelines]: https://jetbrains.github.io/ui
+| Component | Version |
+|-----------|---------|
+| Kotlin | 2.1.20 |
+| IntelliJ Platform Gradle Plugin | 2.10.2 |
+| Target IDE | IntelliJ IDEA 2025.2.4 |
+| Minimum IDE build | 252.25557 |
+| JVM target | 21 |
diff --git a/build.gradle.kts b/build.gradle.kts
@@ -36,6 +36,12 @@ intellijPlatform {
             Initial version
         """.trimIndent()
     }
+
+    pluginVerification {
+        ides {
+            recommended()
+        }
+    }
 }
 
 tasks {

diff --git a/docs/01-setup.md b/docs/01-setup.md
@@ -0,0 +1,82 @@
+# 01 · Environment Setup
+
+This guide walks you through setting up your development environment from scratch. No prior IntelliJ plugin development experience required.
+
+## What you need
+
+| Tool | Version | Purpose |
+|------|---------|---------|
+| [mise](https://mise.jdx.dev) | latest | manages Java and project tasks |
+| Java (Temurin) | 21 | compiles Kotlin and runs Gradle |
+| IntelliJ IDEA | 2025.1+ | IDE for development (Community Edition is free) |
+
+---
+
+## 1. Install mise
+
+mise is a tool version manager. It reads `.mise.toml` in the project root and installs exactly the right Java version for you.
+
+**macOS (Homebrew):**
+
+```bash
+brew install mise
+```
+
+**Other platforms:** see https://mise.jdx.dev/getting-started.html
+
+After installing, add mise to your shell so it activates automatically:
+
+```bash
+# bash
+echo 'eval "$(mise activate bash)"' >> ~/.bashrc
+
+# zsh
+echo 'eval "$(mise activate zsh)"' >> ~/.zshrc
+```
+
+Restart your terminal or run `source ~/.zshrc` (or `~/.bashrc`) before continuing.
+
+---
+
+## 2. Clone the repository
+
+```bash
+git clone https://github.com/labset/jb-plugin.git
+cd jb-plugin
+```
+
+---
+
+## 3. Install project tools
+
+Inside the project directory, run:
+
+```bash
+mise install
+```
+
+This reads `.mise.toml` and installs **Temurin Java 21** locally for this project. It will not affect any other Java installations on your machine.
+
+Verify Java is available:
+
+```bash
+java -version
+# openjdk version "21.x.x" ...
+```
+
+---
+
+## 4. Open in IntelliJ IDEA
+
+1. Download [IntelliJ IDEA Community Edition](https://www.jetbrains.com/idea/download/) if you don't have it.
+2. Open the project: **File → Open** → select the `jb-plugin` folder.
+3. IntelliJ will detect the Gradle project and import it automatically. This takes a few minutes the first time as it downloads dependencies.
+4. Wait for the Gradle sync to finish (progress bar in the bottom status bar).
+
+> **Tip:** If IntelliJ asks about the Gradle JVM, point it to the Java 21 installed by mise. You can find the path with `mise which java`.
+
+---
+
+## Next step
+
+→ [02-build.md](02-build.md) — Build the plugin
diff --git a/docs/02-build.md b/docs/02-build.md
@@ -0,0 +1,68 @@
+# 02 · Build
+
+This guide explains how to build the plugin and what the output means.
+
+## Prerequisites
+
+Complete [01-setup.md](01-setup.md) first.
+
+---
+
+## What "build" means for an IntelliJ plugin
+
+Building produces a `.zip` archive — a distributable plugin that can be installed into any compatible IntelliJ-based IDE. The archive is placed in `build/distributions/`.
+
+---
+
+## Run the build
+
+```bash
+mise run build
+```
+
+This runs `./gradlew buildPlugin` under the hood.
+
+**First run** will take several minutes — Gradle downloads the IntelliJ Platform SDK and all dependencies. Subsequent builds are fast due to caching.
+
+### What you should see
+
+```
+BUILD SUCCESSFUL in Xs
+```
+
+The plugin archive will be at:
+
+```
+build/distributions/jb-plugin-<version>.zip
+```
+
+---
+
+## Available mise tasks
+
+```bash
+mise tasks
+```
+
+| Task | What it does |
+|------|-------------|
+| `mise run build` | Compiles and packages the plugin |
+| `mise run ide` | Runs the plugin in a sandbox IDE |
+| `mise run test` | Runs automated tests |
+| `mise run verify` | Verifies plugin compatibility |
+
+---
+
+## Common issues
+
+**`Could not resolve com.jetbrains.intellij...`**
+Gradle cannot reach JetBrains repositories. Check your internet connection and try again.
+
+**`Kotlin compilation error`**
+Run `./gradlew clean buildPlugin` to rule out stale build artifacts.
+
+---
+
+## Next step
+
+→ [03-run.md](03-run.md) — Run the plugin in a sandbox IDE
diff --git a/docs/03-run.md b/docs/03-run.md
@@ -0,0 +1,46 @@
+# 03 · Run in Sandbox IDE
+
+The fastest way to manually test your plugin is to launch a sandboxed IntelliJ instance. This is an isolated copy of the IDE with only your plugin installed — it won't touch your normal IntelliJ installation or settings.
+
+## Prerequisites
+
+Complete [02-build.md](02-build.md) first (a build is not strictly required, but the first run will build anyway).
+
+---
+
+## Launch the sandbox
+
+```bash
+mise run ide
+```
+
+This runs `./gradlew runIde` under the hood.
+
+**First launch** downloads the IntelliJ Platform runtime, which can take a few minutes.
+
+---
+
+## What to expect
+
+A fresh IntelliJ IDEA window will open. It is completely separate from your regular IDE — different settings, no projects, no other plugins.
+
+### Try the plugin
+
+1. Inside the sandbox IDE, open the **MyToolWindow** tool window from the side panel.
+2. Verify it loads and displays correctly.
+
+---
+
+## Making changes and reloading
+
+The sandbox IDE does **not** hot-reload. To pick up code changes:
+
+1. Stop the sandbox (close the window or press `Ctrl+C` in the terminal).
+2. Make your changes.
+3. Run `mise run ide` again.
+
+---
+
+## Next step
+
+→ [04-testing.md](04-testing.md) — Write and run automated tests