diff --git a/NEW-FORMATTERS.md b/NEW-FORMATTERS.md
new file mode 100644
index 0000000..19d6d12
--- /dev/null
+++ b/NEW-FORMATTERS.md
@@ -0,0 +1,89 @@
+## available environment variables
+
+- `PROJECT_ROOT` is the root directory of your project, the one
+  with files that need to be reformatted.  Currently (as of 2023-09) this is
+  just the output of `git rev-parse --show-toplevel` but it may be improved.
+- `WF_ROOT` is the root directory of the `would-format` checkout
+
+file checking and sniffing
+
+## file type sniffing
+
+You can override a file type by creating an executable in
+`$WOULD_FORMAT_PROJECT_ROOT/.would-format/sniffer`.  This is typically a shell
+script, but it doesn't have to be.  It takes one argument, the full path of
+the file to be checked.
+
+This file should print the type of file it should be treated as.  If the
+script has no opinion on the matter, it should print nothing and exit.  Here
+is an example:
+
+```shell-script
+#!/usr/bin/env bash
+
+file="$1"
+
+if [[ $file == *.pl ]] ; then
+    # the default is that .pl corresponds to perl, but not here!
+    echo -n "prolog"
+fi
+
+if [[ $file == *.ts ]] ; then
+    # qt translations, who knew
+    echo -n "qt-translation"
+fi
+
+# We're fine with the defaults for other types of files so we don't
+# print anything else.
+
+exit 0
+```
+
+Return values:
+
+- 0: success
+- 254: file can't be read due to permissions, etc ("etc" is as of
+  2023-Q3 broad in scope; it could include trying and failing to read a file
+  on a NFS mount)
+- 255: some sort of internal error
+
+
+
+
+## return value normalization for formatters
+
+In general, low-numbered codes are related to the code to be analyzed
+or reformatted and high-numbered codes have to do with problems with these
+scripts themselves.
+
+### In `would_format` mode
+
+`would-format.sh` interprets return values to mean the following:
+
+FIXME: Unsurprisingly, `gofmt` gets this right, even if none of the other
+tools does.  Drop `1`.
+
+- 0: file wouldn't be reformatted
+- 1: file would be reformatted
+- 2: file has at least one syntax error
+- 252: Unexpected return value from the tool; that is, the value of `$?` is
+  unexpected and thus unhandled
+- 253: Unexpected output from the tool; that is, the output emitted by the
+  tool is unexpected and thus unhandled
+- 254: file can't be read due to permissions, etc ("etc" is as of
+  2023-Q3 broad in scope; it could include trying and failing to read a file
+  on a NFS mount)
+- 255: error internal to the script in question
+
+
+# in `do_format` mode
+
+`do-format.sh` interprets return values to mean the following:
+
+- 0: file was successfully reformatted
+- 1: file was not successfully reformatted, presumably due to a syntax error
+- 254: file can't be rewritten due to permissions, etc ("etc" is as of
+  2023-Q3 broad in scope; it could include trying and failing to read a file
+  on a NFS mount)
+- 255: error internal to the script in question
+