diff --git a/README.md b/README.md
index 4412dac..7b6ab08 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,60 @@
-# eip-3074-tools-action
\ No newline at end of file
+# eip-3074-tools-action
+
+Tools built around the patched versions of forge and the solidity compiler that
+support EIP-3074 opcodes from [clabby/eip-3074-foundry].
+
+## Docker image
+
+The Docker image defined in this repo contains both the patched solc and forge
+binaries, compatible with EIP-3074 and ready o be used. The patches are avaiable
+under the `patches` directory, during the image build process the source for
+both binaries is checked out, the patches are applied and the binaries are built
+and put under `/usr/local/bin` in the final image.
+
+The image also includes an entrypoint script that makes it easier to use the
+patched forge with any foundry project using EIP-3074 instructions. It provides
+these arguments:
+* `--foundry-command`: subcommand to use with the patched forge
+* `--foundry-directory`: where to find the foundry project in the container
+* `--foundry-script`: when `--foundry-command` is script, path in the foundry
+project of the script to execute.
+
+There's a github actions workflow in this repo that builds and publishes the
+image on each merge to master, it is availble at: `ghcr.io/fgimenez/eip3074-tools`
+
+### How to use
+Containers created from this image should mount a local directory containing a
+source foundry project and then run a forge command on it. For example, to
+build a project, from the project root you can execute:
+```shell
+$ docker run --rm \
+    -v $(pwd):/app/foundry \
+    -u $(id -u):$(id -g) \
+	ghcr.io/fgimenez/eip3074-tools:latest \
+	--foundry-directory /app/foundry \
+	--foundry-command build
+```
+In this command:
+* `-v $(pwd):/app/foundry` mounts the local directory in `/app/foundry` in the
+container.
+* `-u $(id -u):$(id -g)` makes sure that the files created will belong to the
+same user executing the command.
+* `ghcr.io/fgimenez/eip3074-tools:latest` is the image name
+* `--foundry-directory /app/foundry` tells the entrypoint script to use
+`/app/foundry` in the container as the foundry project directory.
+* `--foundry-command build` tells the entrypoint script to use `build` as the
+forge command.
+
+To run tests in a project, from the projects root:
+```shell
+$ docker run --rm \
+    -v $(pwd):/app/foundry \
+    -u $(id -u):$(id -g) \
+	ghcr.io/fgimenez/eip3074-tools:latest \
+	--foundry-directory /app/foundry \
+	--foundry-command "test -vvv"
+```
+In this case we have signalled forge that we want incresed verbosity in the test
+output passing `test -vvvv` to `--foundry-command`.
+
+[clabby/eip-3074-foundry]: https://github.com/clabby/eip-3074-foundry