diff --git a/README.md b/README.md
new file mode 100644
index 00000000..11c6bd54
--- /dev/null
+++ b/README.md
@@ -0,0 +1,27 @@
+##  punkshell - an alternative Tcl Shell
+
+BSD license
+
+2023-08  Note: this is **alpha** level software and still highly experimental.
+
+
+### Features
+- default ansi color output - toggle with 'colour on' and 'colour off'
+- experimental functional language features. (will not be performant until more work is done on script compilation)
+    e.g  var_pipe_output.=  var_list.= list a b c |> string toupper  
+- easy execution of externals commands with return of stdout, stderr and the exitcode of the process
+   - run <comand> ...
+       (return exitcode of process - and allows process writes to stderr/stdout to appear in console as they occur)
+   - runout <command> ... 
+       (return stdout of process - no output until completion) 
+   - runerr <command> ...
+       (return stderr of process - no output until completion)
+   - runx  
+       (return a dict of stdout stderr exitcode - no output until completion)
+
+
+
+#### very unripe parts:
+- commandline options - in need of urgent work to document and lock down specifics - in particular: punkshell somescript.tcl needs a fix to emit errors.
+- shellfilter - api is clumsy
+- scriptlib - will likely be reorganised/pruned significantly