I'm inclined to agree with @jfly here. It's very important for the readme to let users know how to build, but I'm not sure it's so important describe what is happening in the build process. I view readme's as what information a newcomer needs to know in order to use the thing.

My slight preference would be not to merge this. However, I don't have any concerns with merging it either, so do what you want with it.

I'm inclined to agree with @jfly here.

Sounds good, that's also my preference. At least we have a this PR as thorough answer to #196 (review) we can reference in the future if needed.

Actually, what I think I can do is turn this into an ADR (architecture decision record).

Not sure what the best public reference on this is, but https://github.com/joelparkerhenderson/architecture-decision-record roughly covers it.

This has the benefit of being a point-in-time documentation that does not make any promises about future maintenance.