diff --git a/README.asc b/README.asc
new file mode 100644
index 00000000..e6ef8222
--- /dev/null
+++ b/README.asc
@@ -0,0 +1,10 @@
+environment variables:
+
+DEBUG:: whether to initialise basic debugging features at load time. the value is irrelevant; the test is for whether the variable is defined.
+DEBUG_WAIT:: whether to wait for a debugger to attach before executing `main`.
+
+LOG_LEVEL:: minimum log level that will render to the logging stream. note that a given level may have been compiled out and may not be present, eg. DEBUG tends to only be present for debug builds.
+BREAK_LEVEL:: minimum log level that will trigger a breakpoint
+
+JOB_THREADS:: default number of threads to spin up for job queues.
+JOB_DEPTH:: the default size of the pending work item queue for a job queue.