diff --git a/Nuvolari/README.md b/Nuvolari/README.md
index fb99baf..3a1376c 100644
--- a/Nuvolari/README.md
+++ b/Nuvolari/README.md
@@ -62,6 +62,27 @@ flutter run --dart-define-from-file=../env.json
 With no `env.json` the app starts in demo mode: mock radar frames from assets, offline
 base map style, test ad units. No network and no credentials required.
 
+## Debugging in VS Code
+
+Open the **`Nuvolari` folder** as the workspace root — the configurations in
+`.vscode/` are relative to it. Then pick one in Run and Debug and press **F5**:
+
+| Configuration | Use it for |
+|---|---|
+| **Nuvolari — debug (emulatore)** | Everyday work. Demo mode, no `env.json` needed, hot reload on save. |
+| **Nuvolari — profile** | Judging animation smoothness. Debug builds run the Dart VM unoptimised, so the radar timeline always looks worse than it is — never assess it in debug. |
+| **Nuvolari — debug con env.json** | Real endpoints and keys. |
+| **Nuvolari — debug su Windows** | Fast UI iteration with no emulator. The native map does not render here. |
+| **Test — tutti** / **Test — file corrente** | Debugging tests with breakpoints. |
+
+Every emulator configuration runs `tool/start_emulator.ps1` first, so F5 works from a
+cold machine. The script exits immediately when a device is already attached, so
+pressing F5 twice does not start two emulators.
+
+`Ctrl+Shift+B` runs the full verification. Other tasks live under
+**Terminal → Run Task**: quick verification, regenerating the demo radar frames, and
+shutting the emulator down.
+
 ## Verifying
 
 ```powershell