hardening and bugfixing prior to stable release

packages/nopy/docs/VAGRANT.md

@@ -1,7 +1,9 @@
 # Vagrant
 
-`vagrant ssh-config` to find the SSH port of the machine
-`vagrant status --machine-readable` will be executed by pyinfra to get information about available VMs
+A Vagrant box is the cheapest way to run a cube against a real machine you can
+throw away afterwards.
+
+## The Vagrantfile
 
 ```ruby
 
@@ -19,3 +21,34 @@ Vagrant.configure("2") do |config|
   end
 
 ```
+
+## Naming the machine to nopy
+
+The host string is `@vagrant/<name>`, where `<name>` is what `config.vm.define`
+declared — `nopytestvm` above. It is pyinfra's connector syntax, not nopy's, and
+it is the same shape as `@docker/<container-or-image>`.
+
+Two ways to get there. Either pick `vagrant` in the host prompt and answer the
+follow-up with the machine name, which is what builds the string for you, or put
+it in `.nopyrc.json` so it appears in the list directly:
+
+```json
+{
+  "hosts": ["@vagrant/nopytestvm"],
+  "cubePackages": ["@bitsquare/nopy-cubes-core"]
+}
+```
+
+pyinfra runs `vagrant status --machine-readable` to find the available machines
+and `vagrant ssh-config` for the SSH port, so `vagrant` has to be on `PATH` and
+the box has to be `up` before a deploy.
+
+## Cleaning up
+
+```sh
+vagrant halt        # stop it, keep the disk
+vagrant destroy -f  # delete it — the next `vagrant up` is a fresh box
+```
+
+`destroy` is the one to use between test runs of a cube that is not idempotent:
+re-running against a half-configured box tests something other than the cube.