diff --git a/Cargo.toml b/Cargo.toml
index f7f5470212..0924d45bbe 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -13,6 +13,8 @@ members = [
     "bridge_types",
 ]
 
+exclude = [ "legacy" ]
+
 [profile.release]
 lto = true
 #codegen-units = 1
diff --git a/README.md b/README.md
index a187a22134..c2259016fa 100644
--- a/README.md
+++ b/README.md
@@ -1,18 +1,80 @@
-# slvm
+<img src="https://sl-sh-dev.github.io/sl-sh/images/sl-sh-ascii-logo.png" alt="sl-sh logo" style="max-width:100%;">
 
-Simple Lisp Compiler And Virtual Machine
+# Simple Lisp Shell (pronounced slosh)
 
-This compiles Lisp to slvm bytecode.  It is intended to eventually
-become part of sl-sh (simple lisp shell).
+![Rust](https://github.com/sl-sh-dev/sl-sh/workflows/Rust/badge.svg?branch=master)
 
-Contains three projects:
-- vm: This is the bytecode VM that is target of the compiler.
+## Note this is a new expermental version, see ./legacy/ for the original version (slush).
+
+Simple Lisp SHell (sl-sh) is a lisp based shell written in Rust. It is not POSIX
+compliant and makes no effort to be. Sl-sh should run on any *nix platform as
+well as macOS (CI currently only tests against ubuntu and macOS).It is a Lisp-1
+that is heavily inspired by Clojure and Common Lisp. It is a shell, it is a
+scripting language, and it is a REPL.
+
+Some of the more prominent features:
+
+* The contains both a shell and a lisp reader so familiar bash-isms like
+    ```bash
+    cat file | tr -s " " | cut -d " " -f 2,4
+    ```
+    "just work"
+* Support for an rc file, ```~/.config/slosh/init.slosh```, to set up environment and fully customize your prompt.
+* Common Lisp style macro system with support for quote and backquote (with clojure style ~ and ~@ expansion).
+* Dynamically Typed
+* Note lacks many features from legacy sl-sh but catching up (std lib is currently tiny).
+
+
+Contains these crates:
+- slosh: a REPL with debugger and extensions that use compiler, includes shell functionality.
 - compiler: the core compiler code
-- slosh: a REPL with debugger and extensions that use compiler
+- compile_state: helper crate with state contained by a VM for use with compiler
+- vm: this is the bytecode VM that is target of the compiler
+- builtins: set of some core builtins
+- shell: contains shell specific code, this includes a shell reader (parser), job control etc
+- bridge_macros: macros for exported Rust functions as slosh functions
+- bridge_types: helper types for code using bridge_macros
+- legacy (excluded): original sl-sh version, more complete but slower and worse core shell support
 
 ## Running
 cargo run -p slosh
 
+## Installation 
+
+### 1. Get sl-sh
+- [Install git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+    ```
+    git clone https://github.com/sl-sh-dev/sl-sh
+    cd slsh
+    ```
+
+### 2. Build sl-sh
+- [Install Rust](https://www.rust-lang.org/tools/install) and build from source:
+    ```
+
+    cargo build -p slosh --release
+    ./target/release/slosh
+    ```
+    OR
+- [Install docker](https://docs.docker.com/get-docker/) and build in a container (FIXME- alpine related error in unix.rs...):
+```
+docker run --rm --net host --user "$(id -u):$(id -g)" -v "$PWD:/usr/src/sl-sh" -w /usr/src/sl-sh rust:alpine cargo build -p slosh --release
+```
+
+Either method will leave you with a binary target/release/slosh that will run the shell. The above docker command will produce a completely static binary while compiling with rust will be linked to you system's libc. You can use the musl target with cargo to produce a static binary with an installed rust.
+
+
+### 3. Use sl-sh as primary shell
+- install binary
+```
+sudo install -D -m 755 target/release/slosh /usr/local/bin/
+```
+- add slosh to /etc/shells and change login shell to slosh
+```
+echo /usr/local/bin/slosh | sudo tee -a /etc/shells
+chsh -s /usr/local/bin/slosh
+```
+
 ## Compiler
 These are a subset of sl-sh forms and most work exactly the same.  See the
 sl-sh docs at:
@@ -24,14 +86,16 @@ https://sl-sh-dev.github.io/sl-sh/mydoc_api.html
 - Nil
 - String Constant
 - Symbol
+- Keyword
 - Character (chars are grapheme clusters)
-- Float
-- Integer
+- Float (32 bits- f32)
+- Integer (56 bit signed integer)
 - Byte
 
 ### Heap allocated objects (complex types)
-- Pair
+- Pair/ConsCell
 - Vector
+- HashMap
 - String
 
 ### Special Forms
@@ -43,12 +107,11 @@ The following special forms are currently in the compiler:
 - macro
 - if
 - quote (')
-- back-quote (` supports , ,@)
+- back-quote (` supports ~ ~@)
 - and
 - or
 - err
 - let
-- let*
 - call/cc
 - defer
 - on-error
@@ -78,10 +141,6 @@ Note: These are all compiled to bytecode and once compiled are not dynamic anymo
 - make-vec
 - vec-push!
 - vec-pop!
-- vec-nth
-- vec-set!
-- vec-len
-- vec-clear!
 - str
 - =
 - /=
@@ -104,7 +163,7 @@ Note: These are all compiled to bytecode and once compiled are not dynamic anymo
 - Macros
 
 ## slosh
-Slosh is the prototype language and REPL using compiler and vm.
+Slosh is the shell and scripting language REPL using the compiler, vm and shell crates.
 
 ### Built-in Forms
 These forms (written in Rust but callable from Lisp) are supported.
@@ -123,4 +182,4 @@ These forms (written in Rust but callable from Lisp) are supported.
 - Debug on error, currently useful for probing VM state only
 
 ## Links
-- sl-sh shell: https://github.com/sl-sh-dev/sl-sh
+- sl-sh legacy shell: https://github.com/sl-sh-dev/sl-sh/legacy
diff --git a/legacy/Cargo.lock b/legacy/Cargo.lock
index c350efbc50..3db2562723 100644
--- a/legacy/Cargo.lock
+++ b/legacy/Cargo.lock
@@ -814,7 +814,7 @@ dependencies = [
 
 [[package]]
 name = "sl-sh"
-version = "0.9.69"
+version = "0.9.70"
 dependencies = [
  "cfg-if",
  "chrono",