Taking the best from the two: what about assuming a default @link /book/group/best-document-ever-about-link - but still allowing custom @link to allow easy migrations?

There's no easy way to do that...
The diviner flow loads code from a repository, creates "cache" files, and then loads them directly to DB. I'm not sure it's even reasonable to try to run it on a different workspace copy.

Are there mechanisms to re-gen the doc after we land changes? If not that might be something we should be able to do with harnormaster, and we can bring the docs back after something like that is set up to ensure they’re always updated

Agree with last comment

I never use them, because there is no real method search. I think, we should be considering generating a documentation with a real php documention tool. But whatever we do: I think we can remove them in their current form.