docs: add VSCode debugger documentation

README.md

@@ -473,7 +473,59 @@ As illustrated in the example above, permissions (wallet / disk read / disk writ
 
 ### Debug your contracts
 
-Inside of the console (`clarinet console`), there is a debugger for stepping through your contracts, including support for:
+#### VS Code Debugger
+
+Clarinet supports the [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/) (DAP) which enables debugging your smart contracts inside of VS Code.
+
+To setup a debug session, you'll first need to create a launch.json file to tell VS Code what you want to debug. The easiest way to do this is to let Code generate the template for you by opening the "Run and Debug" view and clicking "create a launch.json file".
+
+![Run and Debug View](docs/images/run-and-debug.png)
+
+This will create the file .vscode/launch.json with the default template:
+
+```json
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "clarinet",
+      "request": "launch",
+      "name": "Call .foo.bar",
+      "manifest": "${workspaceFolder}/Clarinet.toml",
+      "expression": "(contract-call? .foo bar 42)"
+    }
+  ]
+}
+```
+
+Depending on your needs, you will want to set the `name` field to whatever makes sense for your project, then set the `expression` to the Clarity expression that you would like to debug. In the case of the default example shown in the template above, the debugger would start executing the `bar` function of the `foo` contract, passing the argument `42`. Once this file is configured, the debugger works as expected for any [VS Code debugging](https://code.visualstudio.com/docs/editor/debugging).
+
+Execution begins paused at the first expression. The debug toolbar includes buttons to continue, step over, step into, step out, restart, and stop, in that order.
+
+![debug toolbar](docs/images/debug-toolbar.png)
+
+Breakpoints can be set by clicking in the left gutter next to the code or using the right-click menu at a specific code location.
+
+![breakpoint](docs/images/breakpoint.png)
+
+Data watchpoints may also be set, by clicking the + in the Watch section of the Debug side bar and typing the contract variable to watch in the format `<principal>.<contract>.<name>` or using the shortcut for a local contract, `.<contract>.<name>`. When a watchpoint is set on a contract variable, execution will pause when its value will change.
+
+![watchpoint](docs/images/watchpoint.png)
+
+During execution, the values of the current contract's variables, the current function's arguments, and any local variables (i.e. from a `let` expression) are shown in the side bar. The current watchpoints are also shown with their current values. In both cases, the contents of a map are not shown, but can be queried in the Debug Console. The call stack is also updated to show the call stack of the current execution.
+
+![view of side bar, showing variables, watchpoints, and call stack](docs/images/sidebar.png)
+
+At any point during execution, an expression can be evaluated in the current context via the Debug Console. Just type any valid Clarity expression and hit enter to evaluate it. Upon completion, the events emitted and the return value are printed to the debug console.
+
+![debug console](docs/images/debug-console.png)
+
+#### Command Line Debugger
+
+Inside of the console (`clarinet console`), there is a debugger for stepping through your contracts on the command line, including support for:
 
 - Breakpoints
   - **Source**: Break at a specific line (and optional column) of a contract (`break` or `b` command)