diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9263eb635d..298dbae30f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -95,6 +95,41 @@ switch t := t.(type) {
 
 Then when a new case is added to the sum type, `go-check-sumtype` will detect the missing case statically.
 
+## VSCode extension
+
+The preferred way to develop the FTL VSCode extension is to open a VSCode instance in the `extensions/vscode` directory. This will load the extension in a new VSCode window. From there, the `launch.json` and `tasks.json` files are configured to run the extension in a new window.
+
+## Building the extension
+
+```bash
+just build-extension
+```
+
+## Packaging the extension
+
+To package the extension, run:
+
+```bash
+just package-extension
+```
+
+This will create a `.vsix` file in the `extensions/vscode` directory.
+
+## Publishing the extension
+
+To publish the extension, run:
+
+```bash
+just publish-extension
+```
+
+This will publish the extension to the FTL marketplace. This command will require you to have a Personal Access Token (PAT) with the `Marketplace` scope. You can create a PAT [here](https://dev.azure.com/ftl-org/_usersSettings/tokens).
+
+## Useful links
+
+- [VSCode extension samples](https://github.com/microsoft/vscode-extension-samples)
+- [Extension Guidelines](https://code.visualstudio.com/api/references/extension-guidelines)
+
 ## Communications
 
 ### Issues
diff --git a/extensions/vscode/README.md b/extensions/vscode/README.md
index c8aedf157e..46d4ea4dc7 100644
--- a/extensions/vscode/README.md
+++ b/extensions/vscode/README.md
@@ -1,39 +1,40 @@
-# FTL VSCode extension
+# FTL for Visual Studio Code
 
-## Getting started
+[The VS Code FTL extension](https://marketplace.visualstudio.com/items?itemName=FTL.ftl)
+provides support for
+[FTL](https://github.com/TBD54566975/ftl) within VSCode including LSP integration and useful commands for manageing FTL projects.
 
-Within the FTL.vscode-workspace, select the `VSCode Extensions` workspace. Select "Run and Debug" on the activity bar, then select `Run Extension`. This will open a new VSCode window with the extension running.
+## Requirements
 
-In the extension development host, open an FTL project (with `ftl-project.toml` or `ftl.toml` files).
+- FTL 0.169.0 or newer
 
-If you get any errors, you might need to build the extension first (see below).
+## Quick Start
 
-## Building the extension
+1.  Install [FTL](https://github.com/TBD54566975/ftl) 0.169.0 or newer.
 
-We use `just` for our command line tasks. To build the extension, run:
-```bash
-just build-extension
-```
+2.  Install this extension.
 
-## Packaging the extension
+3.  Open any FTL project with a `ftl-project.toml` or `ftl.toml` file.
 
-To package the extension, run:
-```bash
-just package-extension
-```
+4.  The extension will automatically activate and provide support for FTL projects.
 
-This will create a `.vsix` file in the `extensions/vscode` directory.
+> [!IMPORTANT]
+> If you have installed FTL with hermit (or other dependency management tools), you may need to specify the path to the FTL binary in the extension settings.
 
-## Publishing the extension
+Example:
 
-To publish the extension, run:
-```bash
-just publish-extension
+```json
+{
+  "ftl.executablePath": "bin/ftl"
+}
 ```
 
-This will publish the extension to the FTL marketplace. This command will require you to have a Personal Access Token (PAT) with the `Marketplace` scope. You can create a PAT [here](https://dev.azure.com/ftl-org/_usersSettings/tokens).
+You can also configure additional command line arguments for the FTL binary in the settings.
 
-## Useful links
+Example:
 
-- [VSCode extension samples](https://github.com/microsoft/vscode-extension-samples)
-- [Extension Guidelines](https://code.visualstudio.com/api/references/extension-guidelines)
+```json
+{
+  "ftl.devCommandFlags": ["--recreate", "--parallelism=4"]
+}
+```
diff --git a/extensions/vscode/package.json b/extensions/vscode/package.json
index 3c38fc59a0..5f5792769e 100644
--- a/extensions/vscode/package.json
+++ b/extensions/vscode/package.json
@@ -3,7 +3,7 @@
   "displayName": "FTL",
   "publisher": "ftl",
   "description": "VSCode extension for FTL",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "repository": {
     "type": "git",
     "url": "https://github.com/TBD54566975/ftl-vscode"