diff --git a/README.md b/README.md
index 62e197c..2a23d42 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,82 @@
 <p align="center">
 
-<img src="assets/logo.png" alt="sprout logo" width="200" height="200" />
-<h1 align="center">sprout</h1>
+<img src="assets/logo.png" alt="sprout logo" width="258" height="200" />
+<h1 align="center">Sprout</h1>
 
-</p>
+---
 
-Sprout is an *EXPERIMENTAL* programmable UEFI bootloader written in Rust.
+Sprout is an **EXPERIMENTAL** programmable UEFI bootloader written in Rust.
 
-Sprout is in use at Edera now in development environments and is intended to ship to production soon.
+Sprout is in use at Edera today in development environments and is intended to ship to production soon.
 
-The name "sprout" is derived from our company name "Edera" which means "ivy".
-Given that Sprout is the first thing that is inteded to start on an Edera system, the name was apt.
+The name "sprout" is derived from our company name "Edera" which means "ivy."
+Given that Sprout is the first thing intended to start on an Edera system, the name was apt.
+
+It supports x86_64 and ARM64 EFI-capable systems. It is designed to require UEFI and can be chainloaded from an
+existing UEFI bootloader or booted by the hardware directly.
+
+## Usage
+
+Sprout is provided as a single EFI binary called `sprout.efi`.
+It can be chainloaded from GRUB or other UEFI bootloaders or booted into directly.
+Sprout will look for \sprout.toml in the root of the EFI partition it was loaded from.
+See [Configuration](#configuration) for how to configure sprout.
+
+## Configuration
+
+Sprout is configured using a TOML file at `\sprout.toml` on the root of the EFI partition sprout was booted from.
+
+### Boot Linux from ESP
+
+```toml
+# sprout configuration: version 1
+version = 1
+
+# add a boot entry for booting linux
+# which will run the boot-linux action.
+[entries.boot-linux]
+title = "Boot Linux"
+actions = ["boot-linux"]
+
+# use the chainload action to boot linux via the efi stub.
+# the options below are passed to the efi stub as the
+# kernel command line. the initrd is loaded using the efi stub
+# initrd loader mechanism.
+[actions.boot-linux]
+chainload.path = "\\vmlinuz"
+chainload.options = ["root=/dev/sda1"]
+chainload.linux-initrd = "\\initrd"
+```
+
+### Bootloader Specification (BLS) Support
+
+```toml
+# sprout configuration: version 1
+version = 1
+
+# load an EFI driver for ext4.
+[drivers.ext4]
+path = "\\sprout\\drivers\\ext4.efi"
+
+# extract the full path of the first filesystem
+# that contains \loader\entries as a directory
+# into the value called "boot"
+[extractors.boot.filesystem-device-match]
+has-item = "\\loader\\entries"
+
+# use the sprout bls module to scan a bls
+# directory for entries and load them as boot
+# entries in sprout, using the entry template
+# as specified here. the bls action below will
+# be passed the extracted values from bls.
+[generators.boot.bls]
+path = "$boot\\loader\\entries"
+entry.title = "$title"
+entry.actions = ["bls"]
+
+# the action that is used for each bls entry above.
+[actions.bls]
+chainload.path = "$boot\\$chainload"
+chainload.options = ["$options"]
+chainload.linux-initrd = "$boot\\$initrd"
+```