--- /dev/null
+# Overview #
+
+Welcome to the VVhitespace language. This repository provides two main tools.
+
+A compiler, `vvc`, accepts human-readable VVhitespace source code and translates
+it to true VVhitespace code. VVhitespace code is represented with the *whitespace
+characters* `[tTvVsSnN]` corresponding to `[Tab]`, `[Vtab]`, `[Space]`,
+`[Newline]`, respectively. The first character on a line which is not from this
+set begins a comment which ends with the line. See the standard library for
+examples in this style.
+
+An interpreter, `vvi`, accepts true VVhitespace files as generated by `vvc` and
+executes them according to the rules in `reference.md`.
+
+
+# Instructions #
+
+To build the VVhitespace software, simply run `make` in the top level directory.
+This will produce two binaries, `vvc` for compiling human-readable
+pseudo-vvhitespace into true vvhitespace, and `vvi` for interpreting/executing
+vvhitespace programs.
+
+Use these two programs to build and run your VVS programs:
+
+ vvc -i your_code.pvvs -o output_file.vvs
+ vvi -i output_file.vvs
+
+
+# Examples #
+
+The `examples/` folder contains examples with Makefiles. Simply `cd` into an
+example and `make run` to build and execute it. Don't forget to build `vvc`
+and `vvi` first! More details can be found in `examples/README.md`.
+
+
+# Standard Library #
+
+A standard library provides a few convenience functions. More details can be found
+in `stdlib/README.md`. A working example can be found in `examples/hello-stdlib`.
--- /dev/null
+# Overview #
+
+This folder contains example VVhitespace programs.
+
+Each program can be built and run by executing `make run` in the example
+sub-directory.
+
+Running `make clean` in a specific example sub-directory will clean up all
+build-related files for that example. Executing the same command in the
+top-level `examples/` directory will clean up every example.
+
+Before running any examples, first run `make` in the top-level VVhitespace
+folder to build `vvc` and `vvi`.
+# Overview #
+
+This folder contains a library of useful functions written in VVhitespace.
+Standard include guards are used with `cpp` to include the stdlib in user
+programs. For an example, see `examples/hello-stdlib`.
+
# Reservations #
+Since all labels share a global namespace, the standard library makes the
+following reservations:
+
## Label ##
00000000 0xxxxxxx - reserved for stdlib function entry points
00001000 xxxxxxxx - for use by 1000
00001001 xxxxxxxx - for use by 1001
+ ...etc