diff --git a/README.md b/README.md
index 4ae46b9..6e0c5fa 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,42 @@
-Nim lockfile generator
+# Nim lockfile generator
+
+Generates Nix specific lock files for Nim packages.
+
+It puts your dependencies in the Nix store where they belong.
+
+```sh
+cd «Nim project with a Nimble file»
+nim_lk > lock.json
+```
+
+These lock files contain Nix FOD store paths that can be converted to `nim.cfg` files.
+
+```nix
+{ pkgs ? import <nixpkgs> { }, lockPath }:
+let inherit (pkgs) lib;
+in lib.pipe lockPath [
+  builtins.readFile
+  builtins.fromJSON
+  (builtins.getAttr "depends")
+  (map ({ path, srcDir, ... }: ''path:"${path}/${srcDir}"''))
+  lib.strings.concatLines
+  (pkgs.writeText "nim.cfg")
+]
+```
+
+I manage all this with [Tup](https://gittup.org/tup).
+
+```
+# Tuprules.tup above my Nim projects
+!nim_lk = |> nim_lk > %o |> lock.json
+
+NIXEXPRS_DIR = $(TUP_CWD)/nixexprs
+!nim_cfg = |> nix build --file $(NIXEXPRS_DIR)/configure.nix --argstr lockPath `pwd`/%f --out-link %o |> nim.cfg
+```
+
+```
+# Tupfile in a Nim project
+include_rules
+: |> !nim_lk |> | ./<lock>
+: lock.json |> !nim_cfg |> | ./<lock>
+```