diff --git a/programs/debug_node/README.md b/programs/debug_node/README.md
new file mode 100644
index 00000000..53d56733
--- /dev/null
+++ b/programs/debug_node/README.md
@@ -0,0 +1,104 @@
+
+Introduction
+------------
+
+The `debug_node` is a tool to allow developers to run many interesting sorts of "what-if" tests using state from a production blockchain.
+Like "what happens if I produce enough blocks for the next hardfork time to arrive?" or "what would happen if this account (which I don't have a private key for) did this transaction?"
+
+Setup
+-----
+
+Be sure you've built the right build targets:
+
+    $ make get_dev_key debug_node cli_wallet witness_node
+
+Use the `get_dev_key` utility to generate a keypair:
+
+    $ programs/genesis_util/get_dev_key "" nathan
+    [{"private_key":"5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3","public_key":"BTS6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV","address":"BTSFAbAx7yuxt725qSZvfwWqkdCwp9ZnUama"}]
+
+Obtain a copy of the blockchain in `block_db` directory:
+    $ programs/witness_node/witness_node --data-dir data/mydatadir
+    # ... wait for chain to sync
+    ^C
+    $ cp -Rp data/mydatadir/blockchain/database/block_num_to_block ./block_db
+
+Set up a new datadir with the following `config.ini` settings:
+
+    # setup API endpoint
+    rpc-endpoint = 127.0.0.1:8090
+    # setting this to empty effectively disables the p2p network
+    seed-nodes = []
+    # set apiaccess.json so we can set up
+    api-access = "data/debug_datadir/api-access.json"
+
+Then set up `data/debug_datadir/api-access.json` to allow access to the debug API like this:
+
+    {
+       "permission_map" :
+       [
+          [
+             "bytemaster",
+             {
+                "password_hash_b64" : "9e9GF7ooXVb9k4BoSfNIPTelXeGOZ5DrgOYMj94elaY=",
+                "password_salt_b64" : "INDdM6iCi/8=",
+                "allowed_apis" : ["database_api", "network_broadcast_api", "history_api", "network_node_api", "debug_api"]
+             }
+          ],
+          [
+             "*",
+             {
+                "password_hash_b64" : "*",
+                "password_salt_b64" : "*",
+                "allowed_apis" : ["database_api", "network_broadcast_api", "history_api"]
+             }
+          ]
+       ]
+    }
+
+See [here](https://github.com/cryptonomex/graphene#accessing-restricted-apis) for more detail on the `api-access.json` format.
+
+Once that is set up, run `debug_node` against your newly prepared datadir:
+
+    programs/debug_node/debug_node --data-dir data/debug_datadir
+
+Run `cli_wallet` to connect to the `debug_node` port, using the username and password to access the new `debug_api` (and also a different wallet file):
+
+    programs/cli_wallet/cli_wallet -s 127.0.0.1:8090 -w debug.wallet -u bytemaster -p supersecret
+
+Example usage
+-------------
+
+Load some blocks from the datadir:
+
+    dbg_push_blocks block_db 20000
+
+Note, when pushing a very large number of blocks sometimes `cli_wallet` hangs and you must Ctrl+C and restart it (leaving the `debug_node` running).
+
+Generate (fake) blocks with our own private key:
+
+    dbg_generate_blocks 5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3 1000
+
+Update `angel` account to be controlled by our own private key and generate a (fake) transfer:
+
+    dbg_update_object {"_action":"update", "id":"1.2.1090", "active":{"weight_threshold":1,"key_auths":[["BTS6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV",1]]}}
+    import_key angel 5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3
+    transfer angel init0 999999 BTS "" true
+
+How it works
+------------
+
+The commands work by creating diff(s) from the main chain that are applied to the local chain at specified block height(s).  It lets you easily check out "what-if"
+scenarios in a fantasy debug toy world forked from the real chain, e.g. "if we take all of the blocks until today, then generate a bunch more until a hardfork time
+in the future arrives, does the chain stay up?  Can I do transactions X, Y, and Z in the wallet after the hardfork?"  Anyone connecting to this node sees the same
+fantasy world, so you can e.g. make changes with the `cli_wallet` and see them exist in other `cli_wallet` instances (or GUI wallets or API scripts).
+
+Limitations
+-----------
+
+The main limitations are:
+
+- No export format for the diffs, so you can't really [1] connect multiple `debug_node` to each other.
+- Once faked block(s) or tx(s) have been produced on your chain, you can't really [1] stream blocks or tx's from the main network to your chain.
+
+[1] It should theoretically be possible, but it's non-trivial and totally untested.