diff --git a/README.md b/README.md
index 42abb87e..343394b5 100644
--- a/README.md
+++ b/README.md
@@ -67,7 +67,7 @@ Under Linux, it is sometimes useful to install this tool as global, BUT best pra
 
 #### MacOS
 
-- Under macOS, be careful with installation as global. This is not recommended so better to install it as a dev-dependency
+Under macOS, be careful with installation as global. This is not recommended so better to install it as a dev-dependency
 
 #### Windows
 
@@ -84,7 +84,8 @@ npm install --global @iobroker/dev-server
 
 #### Installation as a development dependency
 
-Some more explanation, especially when a **global installation** is problematic **because of permission** issues (e.g., on **macOS**), you can install the dev-server as a local development dependency.
+> [!NOTE]
+> Some more explanation, especially when a **global installation** is problematic **because of permission** issues (e.g. on **MacOS**), you can add the dev-server to your adapter's `devDependencies` and add it e.g. as a script to your package.json.
 
 **Option 1: Using npm install command (recommended)**
 
@@ -167,7 +168,8 @@ For additional command line arguments, see below.
 
 By default, dev-server creates a temporary directory called `.dev-server` in your adapter directory where all data is stored. This directory must be excluded from NPM and Git.
 
-Your `.gitignore` file must be extended with a single additional line:
+> [!IMPORTANT]
+> Your `.gitignore` file must be extended with a single additional line:
 
 ```text
 .dev-server/
@@ -224,7 +226,8 @@ The following options are available:
 
 Run dev-server, the adapter will not run, but you may test the Admin UI with hot-reload.
 
-If you start the adapter from Admin, be aware that it will use the code uploaded during setup (or when `dev-server upload` was called explicitly).
+> [!NOTE]
+> If you start the adapter from Admin, be aware that it will use the code uploaded during setup (or when `dev-server upload` was called explicitly).
 
 The following options are available:
 
@@ -241,7 +244,8 @@ The adapter will automatically restart when its source code changes (with a 2-se
 
 You may attach a debugger to the running adapter. Keep in mind that the debugger will be detached when you change your source code, you need to manually attach again to the new process. Watch the console output for the correct process id to attach to.
 
-If you are using TypeScript, make sure you have the `watch:ts` script defined the same way it is done by [Adapter Creator](https://github.com/ioBroker/create-adapter). There is no need to run `npm run watch:ts` separately, this is automatically done by dev-server.
+> [!IMPORTANT]
+> If you are using TypeScript, make sure you have the `watch:ts` script defined the same way it is done by [Adapter Creator](https://github.com/ioBroker/create-adapter). There is no need to run `npm run watch:ts` separately, this is automatically done by dev-server.
 
 The following options are available:
 
@@ -277,7 +281,8 @@ Upload the current version of your adapter to the dev-server.
 
 This is only required if you changed something relevant in your io-package.json.
 
-You should only do this when dev-server is not running.
+> [!WARNING]
+> You should only do this when dev-server is not running.
 
 This is a shortcut for `npm pack` and `npm install <package>.tgz`.
 
@@ -465,4 +470,17 @@ Take note of the paths and set up a launch configuration like in the screenshot
 
 ![Run or debug adapter](docs/images/webstorm-debug.jpg)
 
-Now you can run / debug and restart the process from WebStorm, and changes will automatically be synced.
+> [!WARNING]
+> If the option "symlinks" has been used during dev-server setup, you must add the following "Node parameters"
+
+```
+--preserve-symlinks --preserve-symlinks-main
+```
+
+> [!NOTE]
+> If your adapter has been created with adapter creator >= 2.5.1  
+> this configuration is created automatically and stored in ".idea/workspace.xml"
+
+Now you can run / debug and restart the process from Webstorm, and changes will automatically be synced. 
+
+![Start adapter process](docs/images/webstorm-debugger-selection.png)
diff --git a/docs/images/webstorm-debugger-selection.png b/docs/images/webstorm-debugger-selection.png
new file mode 100644
index 00000000..30edcefa
Binary files /dev/null and b/docs/images/webstorm-debugger-selection.png differ