diff --git a/README.md b/README.md
index f395538a..6e4bf0dd 100644
--- a/README.md
+++ b/README.md
@@ -7,17 +7,26 @@ pipeline that's more comprehensible, reproducible, and extendable.
 
 The build process for an image is described by a pipeline. Each
 [*stage*](/stages) in a pipeline is a program that, given some configuration,
-modifies a file system tree. Pipelines are defined as JSON files like this one:
+modifies a file system tree. Finally, an assembler takes a filesystem tree, and
+assembles it into an image. Pipelines are defined as JSON files like this one:
 
 ```json
 {
   "name": "Example Image",
-  "pipeline": [
+  "stages": [
     {
       "name": "io.weldr.dnf",
       "options": {
-        "packages": [ "@core", "httpd" ]
-      }
+        "releasever": "30",
+        "repos": {
+          "fedora": {
+            "name": "Fedora",
+            "metalink": "https://mirrors.fedoraproject.org/metalink?repo=fedora-$releasever&arch=$basearch",
+            "gpgkey": "file:///etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-$releasever-$basearch"
+          }
+        },
+        "packages": [ "@Core", "grub2-pc", "httpd" ]
+        }
     },
     {
       "name": "io.weldr.systemd",
@@ -26,30 +35,55 @@ modifies a file system tree. Pipelines are defined as JSON files like this one:
       }
     },
     {
-      "name": "io.weldr.qcow2",
+      "name": "io.weldr.grub2",
       "options": {
-        "target": "output.qcow2"
+        "root_fs_uuid": "76a22bf4-f153-4541-b6c7-0332c0dfaeac"
       }
     }
-  ]
+  ],
+  "assembler": {
+    "name": "io.weldr.qcow2",
+    "options": {
+      "filename": "example.qcow2",
+      "root_fs_uuid": "76a22bf4-f153-4541-b6c7-0332c0dfaeac"
+    }
+  }
 }
 ```
 
 `osbuild` runs each of the stages in turn, isolating them from the host and
-from each other, with the exception that the first stage may be given an input
-directory, the last stage an output directory and all stages of a given
-pipeline are given the same filesystem tree to operate on.
+from each other, with the exception that they all operate on the same
+filesystem-tree. The assembler is similarly isolated, and given the same
+tree, in read-only mode and assembles it into an image without altering
+its contents.
+
+The filesystem tree produced by the final stage of a pipeline, is named
+and optionally saved to be reused as the base for future pipelines.
 
 Each stage is passed the (appended) `options` object as JSON over stdin.
 
-The above pipeline has no input and produces a qcow2 image.
+The above pipeline has no base and produces a qcow2 image.
 
 ## Running
 
 ```
-osbuild [--input DIRECTORY] [--output DIRECTORY] PIPELINE
-```
+usage: python3 -m osbuild [-h] [--objects DIRECTORY] [-l DIRECTORY] -o DIRECTORY
+                   PIPELINE
 
-Runs `PIPELINE`. If `--input` is given, the directory is available
-read-only in the first stage. If `--output` is given it, it must be empty
-and is avialble read-write in the final stage.
+Build operating system images
+
+positional arguments:
+  PIPELINE              json file containing the pipeline that should be built
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --objects DIRECTORY   the directory where intermediary os trees are stored
+  -l DIRECTORY, --libdir DIRECTORY
+                        the directory containing stages, assemblers, and the
+                        osbuild library
+
+required named arguments:
+  -o DIRECTORY, --output DIRECTORY
+                        provide the empty DIRECTORY as output argument to the
+                        last stage
+```