diff --git a/deploy-static-site/README.md b/deploy-static-site/README.md
new file mode 100644
index 0000000..9f8f44d
--- /dev/null
+++ b/deploy-static-site/README.md
@@ -0,0 +1,75 @@
+# deploy-static-site
+
+Builds a Nix flake site, uploads a tarball to S3, and deploys it via Nomad using a shared `static-server` container image. Content is fetched from S3 at container startup — nothing is baked into the image.
+
+## Usage
+
+```yaml
+- uses: https://git.toph.so/toph/ci-actions/deploy-static-site@main
+  with:
+    domain: example.com
+  env:
+    NOMAD_TOKEN: ${{ secrets.NOMAD_TOKEN }}
+    AWS_ACCESS_KEY_ID: ${{ secrets.S3_ACCESS_KEY }}
+    AWS_SECRET_ACCESS_KEY: ${{ secrets.S3_SECRET_KEY }}
+```
+
+## Inputs
+
+| Input | Required | Default | Description |
+|---|---|---|---|
+| `domain` | yes | — | Domain the site is served at (e.g. `toph.so`) |
+| `flake-output` | no | `default` | Flake output to build (e.g. `docs`) |
+| `nomad-addr` | no | `http://172.17.0.1:4646` | Nomad API address |
+| `server-image` | no | `registry.toph.so/static-server:latest` | OCI image for the static server |
+| `datacenter` | no | `contabo` | Nomad datacenter |
+| `s3-endpoint` | no | `https://s3.toph.so` | S3 endpoint URL |
+| `s3-bucket` | no | `nix-cache` | S3 bucket for site tarballs |
+| `smoke-test` | no | `true` | Run a smoke test after deploy |
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `NOMAD_TOKEN` | yes | Nomad ACL token with deploy access to `static-sites` namespace |
+| `AWS_ACCESS_KEY_ID` | yes | S3 access key |
+| `AWS_SECRET_ACCESS_KEY` | yes | S3 secret key |
+| `NIX_SIGNING_KEY` | no | If set, signs and pushes the Nix closure to the S3 binary cache (speeds up future builds) |
+
+## Infrastructure Requirements
+
+- Nomad namespace `static-sites` must exist
+- `registry.toph.so/static-server:latest` must be pushed (see `images/flake.nix` and the `build-static-server` workflow)
+- S3 bucket (`nix-cache` by default) must exist and be writable with the supplied credentials
+
+## Site Flake Requirements
+
+The site repo's flake must expose a package output that produces a directory of static files:
+
+```nix
+packages.x86_64-linux.default = # derivation whose $out contains static files
+```
+
+Use `site-lib` from this repo to set this up with minimal boilerplate:
+
+```nix
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    site-lib = {
+      url = "git+https://git.toph.so/toph/ci-actions?dir=site-lib";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+  };
+
+  outputs = { self, nixpkgs, site-lib }:
+    site-lib.lib.mkSite {
+      inherit self nixpkgs;
+      src = ./.;
+      installPhase = ''
+        mkdir -p $out
+        cp -r dist/. $out/
+      '';
+    };
+}
+```