diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4b06dd8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,117 @@
+# Detecting and resolving dependency vulnerabilities in Gradle projects
+
+This is a simple project demonstrating how to use the `dependency-submission` GitHub action to detect
+vulnerable dependencies in a Gradle project, and various techniques to address these vulnerabilities.
+
+## Setting up the repository to detect vulnerable dependencies
+
+In order to receive alerts about any vulnerable dependencies for this repository:
+
+1. Dependency graph and Dependabot alerts are enabled
+
+
+2. A simple `dependency-submission` workflow is configured to run on any push to the `main` branch.
+
+https://github.com/bigdaz/dependency-submission-demo/blob/4606ae62102b56b47b8376f85fd0dc9a8fcffd74/.github/workflows/dependency-submission.yml#L1-L22
+
+See the [full dependency-submission documentatio](https://github.com/gradle/actions/blob/main/dependency-submission/README.md)n for more details on adding a dependency-submission workflow.
+
+## Vulnerabilities reported for this repository
+
+This repository has 5 current Dependabot alerts for vulnerable dependencies.
+These are not publicly visible, but here is the list:
+
+
+
+In the following section we will step through the process of investigating, isolating and addressing
+these vulnerabilities.
+
+## Updating a direct dependency to non-vulnerable version
+
+In this example repository, a dependency on `org.apache.commons:commons-text:1.9` results in the following
+Dependabot alert:
+
+
+
+In this simple case, the vulnerable dependency is declared directly in the Gradle project,
+and a newer, non-vulnerable version is available. So the fix is as simple as bumping the version in the project.
+Here is an example pull-request that will address this vulnerability.
+
+https://github.com/bigdaz/dependency-submission-demo/pull/1/files
+
+## Updating a transitive dependency by updating a direct dependency
+
+We see 2 vulnerabilities reported for `org.apache.commons:commons-compress:1.24.0`, like this:
+
+
+
+But there isn't anywhere in our Gradle project where we add depend on `commons-compress`: this vulnerability
+must involve a _transitive_ dependency, and the first step is to work out which direct dependency is responsible.
+The easiest way to do this is with a Gradle Build Scan®, which is why our workflow is
+configured to automatically publish a Build Scan for every dependency submission.
+
+https://github.com/bigdaz/dependency-submission-demo/blob/4606ae62102b56b47b8376f85fd0dc9a8fcffd74/.github/workflows/dependency-submission.yml#L20-L22
+
+[Looking at the build scan for the latest submission](https://scans.gradle.com/s/umqci7ktaxfd6/dependencies?dependencies=commons-compress&expandAll&focusedDependency=WzAsMSwyLFswLDAsWzBdXV0&focusedDependencyView=versions), we can see that `commons-compress` is required by `io.minio:minio:8.5.8`, which _is_ a direct dependency of our project.
+
+
+
+Searching for newer versions reveals that there's an updated version of `minio` available (`8.5.9`),
+and when we update our project to this version, the commons-compress library is updated to `1.26.0`.
+
+Here's the pull-request that will update the version of `minio`, resolving the 2 Dependabot alerts
+triggered by `org.apache.commons:commons-compress:1.24.0`.
+
+https://github.com/bigdaz/dependency-submission-demo/pull/5/files
+
+## Updating a transitive dependency using a dependency constraint
+
+There are times when you won't be able to update a direct dependency to resolve a transitive dependency vulnerability.
+Perhaps there isn't a newer version available with the vulnerability resolved, or perhaps your project isn't
+compatible with the newer version.
+
+In this case, you can directly influence the transitive dependency version with a [dependency constraint](https://docs.gradle.org/current/userguide/dependency_constraints.html).
+A dependency contraint allows you to specify a transitive dependency version to use, without adding a direct dependency on that version.
+
+This pull-request adds a dependency constraint that causes the build to use a newer version of `commons-compress`,
+thereby resolving the Dependabot alert.
+
+https://github.com/bigdaz/dependency-submission-demo/pull/6/files
+
+If you inspect [the resulting Build Scan](https://scans.gradle.com/s/iballo7cgijxw/dependencies?dependencies=commons-compress&expandAll&focusedDependency=WzAsMSw1LFswLDAsWzFdXV0&focusedDependencyView=versions),
+you can see that the version of `commons-compress` is updated, but the version of `minio` is not changed.
+
+## Updating a Plugin classpath dependency
+
+As well as the things you declare in a `dependencies` block, the various Gradle plugins that you apply to your build
+will often have library dependencies.
+Vulnerabilities in these dependencies are detected by the `dependency-submission` action.
+
+The final 2 Dependabot alerts in this project are due to `com.squareup.okio:okio-jvm:3.2.0` and `com.squareup.okio:okio:3.2.0`.
+
+
+
+When inspecting the Build Scan for these vulnerable versions, [we note that they are not listed in the
+"Dependencies" section](https://scans.gradle.com/s/csber5edafgy2/dependencies?dependencies=okio&expandAll).
+This is because these vulnerable versions are actually brought in by the `com.github.ben-manes.versions` plugin:
+you can see this by [searching for 'okio' in the "Build Dependencies" section of the Build Scan](https://scans.gradle.com/s/iballo7cgijxw/build-dependencies?dependencies=okio&expandAll&focusedDependency=WzAsMCwyOSxbMCwwLFsyXV1d&focusedDependencyView=versions).
+
+
+
+Although vulnerable plugin dependencies like this can be trickier to identify, they can be addressed in much the same way as
+regular transitive dependencies.
+In this case there is no newer version of the plugin available, so we can't simply update the plugin version.
+Instead, we must add a dependency constraint to force a newer version of `okio` to be used.
+
+By looking closely at the Build Scan and searching for released versions, we find that constraining the
+version of `com.squareup.okhttp3:okhttp:4.12.0`, both the `okio` and `okio-jvm` versions will be transitively
+updated to non-vulnerable versions.
+
+This pull request adds a dependency constraint to the `buildscript` classpath, which fixes the security
+vulnerablitity in `okio` that is introduced by the `com.github.ben-manes.versions` plugin.
+
+https://github.com/bigdaz/dependency-submission-demo/pull/4/files
+
+The [resulting Build Scan demonstrates](https://scans.gradle.com/s/csber5edafgy2/build-dependencies?dependencies=okio&expandAll&focusedDependency=WzAsMCwzNCxbMCwwLFsxXV1d&focusedDependencyView=versions) that the build dependencies no longer include the vulnerable dependency versions.
+
+