diff --git a/README.md b/README.md
index c340293..4036a5c 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,82 @@
-NB. These helper functions are falling behind the arm-sdk blend helpers.
-currently /space/code_repositories/decode-os/os-build-system/blends/devuan-desktop is the working place.
+# live-metal scripts
 
+:bulb: These helper functions need to be integrated with the arm-sdk blend
+helpers. found here:
 
-Helper scripts and configs for devuan sdk to form a blend to produce minimized docker images and install devuan to multiple harddrives using zfs.
+- `/space/code_repositories/decode-os/os-build-system/blends/devuan-desktop`
 
+## helper functions
 
-Run: tmuxp load . to bring up a two window tmux session with one 
-in the live-sdk blend environment and the other not. (see .tmuxp.yaml
+Helper functions and configs for devuan sdk to form a blend and to produce
+minimized docker images and install devuan to multiple harddrives using zfs.
 
-apt-get install tmuxp or run the /var/tmp/020_tmux.sh
+## Install
+
+The install.sh in the live-metal directory expects to be run on a machine
+booted via a live-sd image.
+
+Once you have run this script it will have created a directory `../live-sdk`
+and copied blend configuration files and helper scripts to that directory.
+
+Once you have `cd ../live-sdk` you must:
+
+- changed the drive names in `blends/devuan-desktop-metal/config`
+- review the package list in `blends/devuan-desktop-metal/daedalus/config`
+
+then:
+
+```bash
+tmuxp load .
+```
+
+This will give you two frames, one in the live-sdk env (created by sourcing console_live-sdk.sh)
+and one not. See dot_tmuxp_metal.yaml for the layout.
+
+Use <kbd>ctrl</kbd> + <kbd>B</kbd> followed by <kbd>↑</kbd> <kbd>↓</kbd> <kbd>→</kbd> <kbd>←</kbd> to switch between them.
+
+This script is intended to be run of an sdcard live image NOT a running system.
+
+It copies /var/tmp/live-sdk from `192.168.1.102` if the ssh key exchange does not
+fix password requests the default:default can be used.
+
+It takes the `blends/devuan-desktop-live` directory as a template and copies the
+configuration files in live-metal to the newly named blend directory.
+
+The sources.list will be updated to a `snapshot.debian.org` date that matches
+the live sdcard release (bookworm) if you change the live sdcard image you
+must change the date of the snapshot in the `install.sh` script.
+
+| Devuan Version | Corresponds to Debian | Release Date       |
+| -------------- | --------------------- | ------------------ |
+| 1.0 Jessie     | 8 Jessie              | 2018-06-23T023722Z |
+| 2.0 ASCII      | 9 Stretch             | 2020-07-17T204551Z |
+| 3.0 Beowulf    | 10.4 Buster           | 2023-06-11T103552Z |
+| 4.0 Chimaera   | 11.1 Bullseye         | 2023-06-11T103552Z |
+| 5.0 Daedalus   | 12 Bookworm           | 2023-10-07T150030Z |
+| 6.0 Excalibur  | 13 Trixie             | testing            |
+| 7.0 Freia      | 14 Forky              |                    |
+| Ceres          | Sid                   | unstable           |
+
+`apt-get install tmuxp` or run the `/var/tmp/020_tmux.sh`
+
+### Configuration
+
+The most important change to make before running the install is to provide
+the /dev/disk/by-id for the disks you wish to install to.
+
+After any changes to configuration files it is important to exit and
+reload the sdk.
+
+### Build
+
+In the live-sdk environment you have access to the functions of the sdk.
+
+The amin function that kicjs off the build sequence and debootstrap is
+
+`blend/helpers:build_metal_dist`
+
+To install to the chosen harddrives in the live-sdk env run:
+
+```bash
+ build_metal_dist
+```