The development setup has rapidly changed and README.md hasn't really kept up. So far we seem to have been following a "bag of information" approach, just putting new information in vaguely appropriate sections without much thought. It doesn't really make sense if you read it from top to bottom.

We can probably get rid of the whole "this is what every file is" section, which dates back to the early days of the project.

A screenshot and better, more enticing description of the project at the top would be nice.

The main task is to document the development setup/workflow, but in such a way that the most important information is succinct and upfront, and other details are delegated to READMEs in other places. This is the model we sort of employ for database migrations for example. For instance, every Dockerfile should have a corresponding README for what that image is for and when it is used, though that's probably a follow up task. Another example: the information on how to use the pre-commit hooks could be moved as comments in the .pre-commit config YAML file.

I know I keep telling people that we don't assign issues, but I, Travis, will personally handle this. If anyone tries to fix this with an LLM, we will laugh you off of GitHub.