diff --git a/README.md b/README.md
index 408511f..52e16f5 100644
--- a/README.md
+++ b/README.md
@@ -62,7 +62,7 @@ Once installed there are three ways to execute code:
 * By specifying an expression to execute upon the command-line:
   * `yal -e '(print (os))'`
 * By passing the name of a file containing lisp code to read and execute:
-  * `yal test.lisp`
+  * `yal examples/test.lisp`
 * By launching the interpreter with zero arguments, which will start the interactive REPL mode.
   * If present the file `~/.yalrc` is loaded before the REPL starts.
   * Here is a sample [.yalrc](.yalrc) file which shows the kind of thing you might wish to do.
@@ -170,17 +170,19 @@ Here the regular expressions will be matched against the name of the file(s) in
 
 ## Examples
 
-A reasonable amount of sample code can be found in the various included files:
+A reasonable amount of sample code can be found beneath the [examples/](examples/) directory, including:
 
-* [fibonacci.list](fibonacci.lisp)
+* [examples/fibonacci.list](examples/fibonacci.lisp)
   * Calculate the first 25 numbers of the Fibonacci sequence.
-* [fizzbuzz.lisp](fizzbuzz.lisp)
+* [examples/fizzbuzz.lisp](examples/fizzbuzz.lisp)
   * A standalone sample of solving the fizzbuzz problem.
-* [mtest.lisp](mtest.lisp)
-  * Shows simple some macro examples, but see [lisp-tests.lisp](lisp-tests.lisp) for a more useful example.
-* [sorting.lisp](sorting.lisp)
+* [examples/mtest.lisp](examples/mtest.lisp)
+  * Shows simple some macro examples, but see [examples/lisp-tests.lisp](examples/lisp-tests.lisp) for a more useful example.
+    * This uses macros in an interesting way.
+    * It is also used to actually test the various Lisp-methods we've implemented.
+* [examples/sorting.lisp](examples/sorting.lisp)
   * Demonstrates writing & benchmarking sorting-routines.
-* [test.lisp](test.lisp)
+* [examples/test.lisp](examples/test.lisp)
   * A misc. collection of sample code, functions, and notes.
 
 As noted there is a standard-library of functions which are loaded along with any user-supplied script - that library of functions may also provide a useful reference and example of yal-code:
@@ -189,7 +191,7 @@ As noted there is a standard-library of functions which are loaded along with an
 
 The standard-library contains its own series of test-cases written in Lisp:
 
-* [lisp-tests.lisp](lisp-tests.lisp)
+* [examples/lisp-tests.lisp](examples/lisp-tests.lisp)
 
 The lisp-tests.lisp file contains a simple macro for defining test-cases, and uses that to good effect to test a range of our lisp-implemented primitives.
 
diff --git a/examples/Makefile b/examples/Makefile
new file mode 100644
index 0000000..7826ea5
--- /dev/null
+++ b/examples/Makefile
@@ -0,0 +1,5 @@
+#
+# Generate README.md, by running readme.lisp.
+#
+README.md: *.lisp
+	../yal readme.lisp > README.md
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 0000000..b304753
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,27 @@
+# Examples
+
+This directory contains some simple lisp examples, which can be executed via `yal`.
+
+
+* [dynamic.lisp](dynamic.lisp)
+  * Execute code by name, via introspection.
+* [fibonacci.lisp](fibonacci.lisp)
+  * Calculate the first 25 fibonacci numbers.
+* [fizzbuzz.lisp](fizzbuzz.lisp)
+  * Show the fizzbuzz up to 50.
+* [hash.lisp](hash.lisp)
+  * Demonstrate working with hashes.
+* [lisp-tests.lisp](lisp-tests.lisp)
+  * A simple lisp-based testing framework for our primitives.
+* [mtest.lisp](mtest.lisp)
+  * Simple tests of our macro system.
+* [readme.lisp](readme.lisp)
+  * Generate a README.md file, based on directory contents.
+* [sorting.lisp](sorting.lisp)
+  * Demonstrate generating random lists, and sorting them.
+* [test.lisp](test.lisp)
+  * Simple feature-tests/demonstrations of our system.
+* [time.lisp](time.lisp)
+  * Demonstrate our date/time functions.
+* [try.lisp](try.lisp)
+  * Demonstrate our error-handling, with try/catch.
diff --git a/args.lisp b/examples/args.lisp
similarity index 100%
rename from args.lisp
rename to examples/args.lisp
diff --git a/dynamic.lisp b/examples/dynamic.lisp
similarity index 100%
rename from dynamic.lisp
rename to examples/dynamic.lisp
diff --git a/fibonacci.lisp b/examples/fibonacci.lisp
similarity index 100%
rename from fibonacci.lisp
rename to examples/fibonacci.lisp
diff --git a/fizzbuzz.lisp b/examples/fizzbuzz.lisp
similarity index 93%
rename from fizzbuzz.lisp
rename to examples/fizzbuzz.lisp
index d43d02c..f9917c2 100644
--- a/fizzbuzz.lisp
+++ b/examples/fizzbuzz.lisp
@@ -1,4 +1,4 @@
-;;; fizzbuzz2.lisp - A simple fizzbuzz implementation
+;;; fizzbuzz2.lisp - Show the fizzbuzz up to 50.
 
 ;; Taking advantage of our (cond) primitive we can just return the
 ;; string to print for any given number.
diff --git a/hash.lisp b/examples/hash.lisp
similarity index 100%
rename from hash.lisp
rename to examples/hash.lisp
diff --git a/lisp-tests.lisp b/examples/lisp-tests.lisp
similarity index 99%
rename from lisp-tests.lisp
rename to examples/lisp-tests.lisp
index b99147c..c7a73cf 100644
--- a/lisp-tests.lisp
+++ b/examples/lisp-tests.lisp
@@ -1,4 +1,4 @@
-;;; tests.lisp - Some simple tests of our lisp-written primitives
+;;; tests.lisp - A simple lisp-based testing framework for our primitives.
 
 ;;; About
 ;;
diff --git a/mtest.lisp b/examples/mtest.lisp
similarity index 100%
rename from mtest.lisp
rename to examples/mtest.lisp
diff --git a/examples/readme.lisp b/examples/readme.lisp
new file mode 100644
index 0000000..bb311c7
--- /dev/null
+++ b/examples/readme.lisp
@@ -0,0 +1,37 @@
+;;; readme.lisp - Generate a README.md file, based on directory contents.
+
+;;
+;; This directory contains *.lisp, echo of which has a header-line prefixed
+;; with three semi-colons:
+;;
+;;     ;;; foo.lisp - Information
+;;
+;; This script reads those files and outputs a simple index, of the filename
+;; and the information.
+;;
+
+(set! lisp:files (fn* ()
+                      "Return a list of all the lisp files in the current directory"
+                      (sort (glob "*.lisp"))))
+
+
+(set! lisp:info (fn* (file)
+                     "Output a brief overview of the given file"
+                     (let* (
+                            text (file:lines file)
+                            line  (nth text 0)
+                            info (match "^([^-]*)-+[ ]+(.*)$" line))
+                       (when (list? info)
+                         (print "* [%s](%s)" file file)
+                         (print "  * %s" (nth info 2))))))
+
+
+(set! lisp:index (fn* ()
+                      "Generate a README.md snippet"
+                      (let* (files (lisp:files))
+                        (apply files lisp:info()))))
+
+(print "# Examples\n")
+(print "This directory contains some simple lisp examples, which can be executed via `yal`.\n\n")
+
+(lisp:index)
diff --git a/sorting.lisp b/examples/sorting.lisp
similarity index 100%
rename from sorting.lisp
rename to examples/sorting.lisp
diff --git a/test.lisp b/examples/test.lisp
similarity index 100%
rename from test.lisp
rename to examples/test.lisp
diff --git a/time.lisp b/examples/time.lisp
similarity index 92%
rename from time.lisp
rename to examples/time.lisp
index c4426c6..ea928fb 100644
--- a/time.lisp
+++ b/examples/time.lisp
@@ -1,4 +1,4 @@
-;;; time.lisp - Demonstrate the date/time functions
+;;; time.lisp - Demonstrate our date/time functions.
 
 ;;
 ;; This is a sample input file for our minimal lisp interpreter.
diff --git a/try.lisp b/examples/try.lisp
similarity index 90%
rename from try.lisp
rename to examples/try.lisp
index 0ebb485..faa3320 100644
--- a/try.lisp
+++ b/examples/try.lisp
@@ -1,4 +1,4 @@
-;;; try.lisp - Demonstrate our try/catch behaviour
+;;; try.lisp - Demonstrate our error-handling, with try/catch.
 
 ;;
 ;; This file demonstrates our try/catch behaviour, which allows