I see, you are more focused on providing the core functionality in the simplest way possible from purely technical perspective, and less so on what kind of "language" or interface it provides the end user — assuming someone who wants an interface can make a wrapper. I can see that your points make sense from this perspective, the solution with FDs is indeed simpler from this viewpoint.

I, on the other hand, criticized it as a complete interface made with some workflow in mind that would need no wrappers, would help the user discover itself and avoid footguns. Your interpretation sounds like what the authors may have had in mind when they made it.

> who’s trying to audit use of these tools without the manual?

I'd try to work on different levels when understanding some system. Before getting into details, I'd try to understand the high-level components/steps and their dataflows, and then gradually keep refining the level of detail. If a tool has 2-3 descriptively named arguments and you have a high-level idea of what the tool is for, you can usually track the dataflows of its call quite well without manual. Say, understanding a command like

  make -B -C ./somewhere -k

  make --always-make --directory=./somewhere --keep-going