diff --git a/src/README.md b/src/README.md
index ba23ee53..e5dec4d2 100644
--- a/src/README.md
+++ b/src/README.md
@@ -2,15 +2,53 @@ punk shell
 ==============================
 
 
+Runtimes
+------------------------------
+```
+#run from project root:  
+./bin/runtime.cmd list -remote
+# This is a cross-platform polyglot wrapper that should run from bash, or with tclsh or in windows directly in powershell/cmd.exe
+./bin/runtime.cmd fetch
+
+#if no retrievable runtime for your platform, you'll need a vfs capable tclkit or a zipfs capable tclsh with an attached vfs
+
+#todo: exact notes on creating suitable runtimes (plain tclsh will likely be missing zipfs vfs to mount)
+
+```
+
+
 Build Instructions
 ------------------------------
 
-+ Use  tclsh|punk make.tcl to build .tm modules and rebuild the punk executable
-e.g tclsh make.tcl modules
-e.g tclsh make.tcl project
++ Use  `tclsh|<punkruntime> make.tcl <commandname>` to build .tm modules and rebuild the punk executable
+In normal use it should be called from the project root.
+e.g
+```
+ tclsh src/make.tcl vendorupdate   ;# if needed
+
+ tclsh src/make.tcl packages       ;# build/install the unversioned libs / modules to <projectroot>
+ # or separately:
+ # tclsh src/make.tcl modules      ;# src/modules -> /modules (etc)
+ # tclsh src/make.tcl libs         ;# src/lib     -> /lib (etc)
+
+ tclsh src/make.tcl vfscommonupdate ;copy the  libs/modules that are now in <projectroot>/modules to vfs system for inclusion in the binary.
+
+ # If make.tcl dependencies are modified:
+ # tclsh src/make.tcl bootsupport  ;# src/modules -> src/bootsupport/modules,  src/lib -> src/bootsupport/lib (etc)
+
+ tclsh src/make.tcl project
+```
+
+
+```
+A common interactive test scenario (after running src/tests/runtests.tcl to test the unversioned source)
+is to run 'tclsh src/make.tcl modules'
+Then '<punkexecutable> dev'
+This will source modules/libs from <projectroot>/modules and <projectroot>/lib intead of from the executable's vfs. 
+```
 
-+ Then Use tclsh|punk build.tcl to run the 'kettle' system to build docs and/or standard tcl libraries with pkgIndex.tcl files,   
-or - use the `pmix KettleShell` command from within the punk shell to perform kettle operations.
++ Then Use tclsh|punk build.tcl to run the 'kettle' system to build doc files,   
+or - use the `pmix KettleShell` command from within the punk shell to perform kettle operations. Confirm with user or ask user to manually run.
 
-(The name 'build.tcl' is the standard name used by the [Kettle](https://chiselapp.com/user/andreas_kupries/repository/Kettle/home) system)
+(The name 'build.tcl' is the standard name used by the [Kettle](https://chiselapp.com/user/andreas_kupries/repository/Kettle/home) system - it is not for building the punk project.)