updated docs, added run() helper