[doc] TOOLS-594 eng update README.md.

- `rm server.js`: stale worse than nothing.
- Sub-headings markdown.
- Added sections based on what's used in real Joyent repos
  including renaming "Repository/Directory" section to "Code Layout".
Yeah, I considered this, but as:
- we've switched to md
- restdown is described as "authored in Markdown"
- there is an outside chance a project might not have an API

I thought putting markdown here simplified things. Should I revert?