The reasoning gets written down

A guide of about sixty-five kilobytes now sits beside the engine: seven chapters covering installation, configuration, routing, views, CSS and the frontend, each closing on its own best practices.

Until now the intent lives in the code. That works for one person and stops working the moment anyone else, or any tool, needs to know why something is the way it is. Syntax can be inferred by reading; reasoning cannot.

The opening chapter states four principles the rest of the design follows from:

Short code, high expressiveness Freedom without condescension Balance in height and width, logical coherence instead of fragmentation across folders One coherent system

The third is the most particular of the four and the hardest to argue for in the abstract. It says a feature should live in one file at the height it belongs, rather than being scattered across a controllers directory, a views directory, a styles directory and an assets directory that each hold one fragment of it. It is why a .phlo file carries its own routes, views, styles and scripts.

The best-practices sections are the part that will age best, because they carry what went wrong and which assumption caused it. A rule without its reason is a rule someone will reasonably break.