diff --git a/bin/README b/bin/README
deleted file mode 100644
index c0ebd75eb..000000000
--- a/bin/README
+++ /dev/null
@@ -1,23 +0,0 @@
-hledger add-on commands, hledger-related scripts, developer builds.
-
-Scripts named hledger-* are hledger add-on commands. The ones in this
-bin/ directory are tested along with hledger, but shipped as add-ons
-rather than built-in commands because they are experimental, or
-for some other reason.
-
-Add this directory to your $PATH and they will show up as commands
-listed by hledger (or, you can run them directly).
-To speed them up (recommended), compile them:
-
-$ bin/compile.sh
-
-When using hledger to run add-on commands, remember to use a --
-before add-on-specific options or hledger will complain. Like so:
-
-$ hledger [HLEDGEROPTS] ADDONCMD [-- ADDONOPTS]
-
-See also http://hledger.org/hledger.html#add-on-commands .
-
-hledger-related bash scripts, example make rules etc. are also kept here.
-And hledger developer binaries may get stored here,
-such as old versions for benchmarking, and platform-specific binaries.
diff --git a/bin/README.md b/bin/README.md
new file mode 100644
index 000000000..9803aaf80
--- /dev/null
+++ b/bin/README.md
@@ -0,0 +1,18 @@
+Miscellaneous hledger add-ons, bash scripts, example make rules, etc. 
+The Makefile may also store hledger developer binaries here.
+
+hledger-*.hs are example/experimental hledger add-on commands, shipped as executable stack scripts. 
+Add this directory to $PATH and they will show up in hledger's commands list.
+You can run them directly and they will install required dependencies and run in interpreted mode. 
+Or you can compile them to run faster (recommended) using `stack ghc` or the `bin/compile.sh` script.
+201907: These scripts are tested infrequently and in need of update.
+They are:
+
+- hledger-check.hs      - check more complex account balance assertions
+- hledger-smooth.hs     - an attempt at automatically splitting infrequent/irregular transactions
+
+A reminder from http://hledger.org/hledger.html#add-on-commands :
+when using the main hledger executable to run add-on commands, remember
+to put a -- before the add-on's options, or hledger will complain. Eg, do:
+
+    $ hledger [HLEDGEROPTS] ADDONCMD [-- ADDONOPTS]