diff --git a/.vscode/launch.json b/.vscode/launch.json
new file mode 100644
index 0000000..9f3ea55
--- /dev/null
+++ b/.vscode/launch.json
@@ -0,0 +1,39 @@
+{
+    // F5 opens a second VS Code window (the Extension Development Host) with this
+    // extension loaded from source. See docs/developing.md.
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Run Extension",
+            "type": "extensionHost",
+            "request": "launch",
+            "args": [
+                "--extensionDevelopmentPath=${workspaceFolder}",
+                // Open this repo as the test workspace: it builds with Fallout, so it
+                // already has a .fallout/temp/build-graph.json and the views populate
+                // immediately. Point this elsewhere to test against another build.
+                "${workspaceFolder}"
+            ],
+            "outFiles": [
+                "${workspaceFolder}/out/**/*.js"
+            ],
+            "preLaunchTask": "npm: compile"
+        },
+        {
+            // Same, with every other extension disabled. Use when something looks off
+            // and you need to rule out interference from your own installed extensions.
+            "name": "Run Extension (clean profile)",
+            "type": "extensionHost",
+            "request": "launch",
+            "args": [
+                "--extensionDevelopmentPath=${workspaceFolder}",
+                "--disable-extensions",
+                "${workspaceFolder}"
+            ],
+            "outFiles": [
+                "${workspaceFolder}/out/**/*.js"
+            ],
+            "preLaunchTask": "npm: compile"
+        }
+    ]
+}
diff --git a/.vscode/tasks.json b/.vscode/tasks.json
new file mode 100644
index 0000000..9b0863d
--- /dev/null
+++ b/.vscode/tasks.json
@@ -0,0 +1,24 @@
+{
+    "version": "2.0.0",
+    "tasks": [
+        {
+            // preLaunchTask for both launch configurations — F5 compiles before it launches,
+            // so the Extension Development Host never runs stale out/*.js.
+            "type": "npm",
+            "script": "compile",
+            "group": "build",
+            "problemMatcher": "$tsc",
+            "label": "npm: compile"
+        },
+        {
+            // Long-running alternative: leave this going and use "Reload Window" in the
+            // Extension Development Host instead of restarting the debug session.
+            "type": "npm",
+            "script": "watch",
+            "group": "build",
+            "isBackground": true,
+            "problemMatcher": "$tsc-watch",
+            "label": "npm: watch"
+        }
+    ]
+}
diff --git a/README.md b/README.md
index a1b68e0..5df68a9 100644
--- a/README.md
+++ b/README.md
@@ -22,7 +22,7 @@ Versions are computed by [Nerdbank.GitVersioning](https://github.com/dotnet/Nerd
 
 ## Contributing
 
-This repository uses GitFlow: branch from `develop`, PR back into `develop`. See [docs/branching-and-release.md](docs/branching-and-release.md), [docs/ci.md](docs/ci.md) and [docs/releasing.md](docs/releasing.md).
+This repository uses GitFlow: branch from `develop`, PR back into `develop`. Press <kbd>F5</kbd> to run the extension from source — see [docs/developing.md](docs/developing.md), plus [docs/branching-and-release.md](docs/branching-and-release.md), [docs/ci.md](docs/ci.md) and [docs/releasing.md](docs/releasing.md).
 
 ## License
 
diff --git a/docs/ci.md b/docs/ci.md
index 6db7b75..d584fb3 100644
--- a/docs/ci.md
+++ b/docs/ci.md
@@ -100,6 +100,8 @@ dotnet fallout --plan             # what would run, without running it
 dotnet fallout VerifyVsixCredentials   # proves marketplace tokens, publishes nothing
 ```
 
+To run the extension itself rather than the build, see [developing.md](developing.md).
+
 ## Gotchas
 
 - **`PublicRelease: true`** is set on any job that checks out a tag. A detached HEAD matches none of `version.json`'s branch refspecs, so without it Nerdbank.GitVersioning appends a git-height suffix and the marketplace version stops being a clean triple.
diff --git a/docs/developing.md b/docs/developing.md
new file mode 100644
index 0000000..81d382f
--- /dev/null
+++ b/docs/developing.md
@@ -0,0 +1,65 @@
+# Developing
+
+Running the extension from source, on a machine that has never built it.
+
+## Prerequisites
+
+Node 20+ and the .NET SDK pinned in [`global.json`](../global.json). Nothing else — `build.ps1` / `build.sh` provision the Fallout CLI themselves, and `npm ci` installs `vsce`/`ovsx` locally rather than globally.
+
+```bash
+npm ci
+```
+
+## The loop
+
+**Press F5.** That compiles, then opens a second VS Code window — the Extension Development Host — with the extension loaded from `out/`. Two configurations are provided:
+
+| Configuration | Use when |
+|---|---|
+| **Run Extension** | Normal work. |
+| **Run Extension (clean profile)** | Something looks wrong and you need to rule out interference from your own installed extensions (`--disable-extensions`). |
+
+Both open **this repo** as the test workspace, which is the point: the repo builds with Fallout, so it already has a `.fallout/temp/build-graph.json` and the views populate immediately. Change the last entry in `args` to test against a different build.
+
+After editing, either restart the debug session, or run the `npm: watch` task and use **Developer: Reload Window** in the host — faster, and it keeps the workspace state (parameters and secrets you entered) intact.
+
+### Without VS Code's launcher
+
+Equivalent to F5, for a terminal or a machine driving it headlessly:
+
+```bash
+npm run compile
+code --extensionDevelopmentPath="$PWD" --new-window "$PWD"
+```
+
+## If a view is empty
+
+The extension reads a build graph the Fallout build emits. No graph, no targets:
+
+```bash
+./build.ps1 --plan        # writes .fallout/temp/build-graph.json without running anything
+```
+
+Requires Fallout 10.4.0 or later — the emission landed in that release, so older framework versions produce no graph at all.
+
+The **Deployment** view is expected to stay empty. It is a declared placeholder: the continuous-delivery model (channels → environments → targets, ADR-0009) is emitted by the framework, and nothing writes a `deployment-graph.json` yet.
+
+## Packaging
+
+The `.vsix` is built by the Fallout build, not by an npm script — the version is computed, so packaging is a build concern:
+
+```bash
+./build.ps1 PackVsix                    # produces fallout.vsix
+./build.ps1 PackVsix --pre-release      # marks it a marketplace pre-release
+```
+
+`package.json`'s `version` is `0.0.0` on purpose. The real version comes from Nerdbank.GitVersioning at pack time; a number hardcoded beside it would be a second source of truth guaranteed to drift. See [releasing.md](releasing.md).
+
+Install the result with **Extensions: Install from VSIX…** to test it as a user would, rather than as a development host.
+
+## See also
+
+- [ci.md](ci.md) — what runs in CI, and running those same targets locally
+- [branching-and-release.md](branching-and-release.md) — GitFlow, protection, merge rules
+- [releasing.md](releasing.md) — versioning, channels, cutting a release
+- [../plugins/Fallout.Vsce/README.md](../plugins/Fallout.Vsce/README.md) — the vsce/ovsx toolchain plugin the build drives