diff --git a/README.md b/README.md
index ec880dc5..0cd5dfec 100644
--- a/README.md
+++ b/README.md
@@ -2,8 +2,35 @@
 
 BSD license
 
-2023-08  Note: this is **alpha** level software and still highly experimental.
+Version 0.11.0 (2026-07) — this is **alpha** level software and still highly experimental. See `CHANGELOG.md` for recent changes.
 
+### Supported Platforms
+
+- Tcl 8.6+ required; Tcl 9.0 and 9.1 supported.
+- Primary target: Windows (win32-x86_64). Linux, macOS, and FreeBSD are secondary targets.
+
+### Getting Started
+
+The project uses a Tcl-based build system (`src/make.tcl`). From the project root:
+
+```
+# Fetch a suitable Tcl runtime (cross-platform polyglot wrapper — runs from bash, powershell, or cmd.exe)
+./bin/runtime.cmd fetch
+
+# Build modules and libraries into the project root
+tclsh src/make.tcl packages
+
+# Full build (modules + libraries + VFS + binaries)
+tclsh src/make.tcl project
+```
+
+See `src/README.md` for detailed build instructions and `bin/AGENTS.md` for the runtime manager.
+
+For evaluating uncommitted source without a full build, a built executable can run directly against the source tree:
+
+```
+<punkexe> src shell
+```
 
 ### Features
 - default ansi color output - toggle with 'colour on' and 'colour off' (or set NO_COLOR environment variable)
@@ -70,32 +97,49 @@ BSD license
         with colourised indication of type such as proc,alias,ensemble,oo object,oo class,imported,exported where possible.   
         (renamed aliases and builtins and commands loaded from binaries will appear unmarked)
     -  `nn/` - move up one namespace towards root namespace '::'  analogous to `cd ..`   (alias `::/`)
-    -  `n/new <somename>` - create a child namespace called 'somename' and switch to it in one operation.  (alias `:/new`)
+    -  `newns <somename>` - create a child namespace called 'somename' and switch to it in one operation.  (alias `:/new`)
 - cross-platform alternative to cd & ls/dir without invoking child processes. Display colourised listing of dirs and folders - with vfs indication.
     -  `d/` - list current directory (alias `./`)   
         also `d/ <globpattern>` to restrict output
     -  `d/ <subdir>` - switch to subdir and list contents in one operation 
     -  `dd/` - move up one directory and output listing. Roughly equivalent to `cd ..` followed by dir or ls  (alias `../`)
-    -  `d/new <folder>` - create a child directory and switch to it in one operation. (alias `./new <folder>`)
+    -  `newdir <folder>` - create a child directory and switch to it in one operation.
+- `<punkexe> script` subcommand for reliable non-interactive script execution:
+    -  `punkexe script <file.tcl> ?args?` — runs a script file with conventional `::argv0`/`::argv`
+    -  `commands | punkexe script` — runs piped stdin commands and exits at EOF (no trailing `exit` needed)
+    -  Honest exit codes (0 success, 1 error with errorInfo on stderr); no shellfilter transforms or logging side effects.
+    -  `lib:<name>` resolution for scriptlib scripts: `punkexe script lib:hello` or bare `punkexe lib:hello`
+- pluggable console backends: the REPL can run against non-detectable terminal-like devices via `::opunk::Console` subclasses (ssh-channel, tk-widget, test-double), with size, eof, and capability answered by subclass overrides.
+- cross-platform runtime manager (`bin/runtime.cmd`): fetch, list, use, and run Tcl runtimes — works from bash, powershell, or cmd.exe. `list -remote` compares local vs server runtimes with sha1 verification.
 - Ability to create zipfs wrapped applications with all required libraries built in.
 - Additional libraries
     - improved fork of tcllib's imap4  (punk::imap4)
     - netbox client library (punk::netbox)
     - telnet client with support for cp437
       e.g can render mapscii.me with mouse support, and can view the ANSI max-headroom movie at 1984.ws
-    - A feature-rich argument processor that can be used purely to generate function documentation, or
+    - A feature-rich argument processor (punk::args) that can be used purely to generate function documentation, or
       also to process and validate flags and values (punk::args)
       The argument processor/documentor can display command synopses, grids of applicable argument choices,
       and indications of when short-forms (prefixes for flags/arguments/values) are applicable.
+      Commands documented with punk::args carry inline usage tables accessible via `i <command>` at the repl.
+    - In-shell help system: `i <command>` shows documented usage tables; `i help` lists registered help topics
+      (tcl, env, console, etc.) with per-topic documented usage.
 
 #### missing
 - raw mode REPL (read-eval-print-loop) to allow commandline completion etc (undergoing development).
-- documentation is incomplete.
-- tests coverage is low. 
+- documentation is incomplete, though the punk::args (PUNKARGS) system now provides inline usage tables and command documentation for many commands via `i <command>` at the repl.
+- tests coverage is growing but not yet comprehensive — characterization suites exist for punk::args, punk::ns, punk::lib, punk::libunknown, punk::mix, shellthread, shellfilter, and console, among others.
 - signal handling on unix-like platforms (ctrl-c implemented on windows only).
 
 
 #### very unripe parts:
-- commandline options - in need of 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
+- theming
+
+### Documentation
+
+- `src/README.md` — detailed build instructions
+- `CHANGELOG.md` — version history and recent changes
+- `AGENTS.md` (root) + child AGENTS.md files — contributor guidance and project structure (DOX hierarchy)
+- `GOALS.md` — technical goal index with per-goal detail files under `goals/`