* Remove makefile, add mdbook-mermaid

* Add design doc section about backwards compatibility

* fix footnotes