The changes look good, I'd tentatively convert the .PUML files to mermaid diagrams, which do have a textual representation

The files are mostly moved from what I can see, do you intend to do a verification pass, them being still valid/correct?

The changes look good, I'd tentatively convert the .PUML files to mermaid diagrams, which do have a textual representation

Agree, an LLM can probably do this for us.

The files are mostly moved from what I can see, do you intend to do a verification pass, them being still valid/correct?

Definitely not correct -- we need to do a content pass. My initial focus was to contribute a skeleton that consolidated docs assets from all over the repo, and established a good outline/structure for the site. There's a lot of work to do here to get things cleaned up (championed by @LePremierHomme). We have:

• incorrect/outdated content
• poorly communicated content
• missing content

I would, however, discourage a big-bang approach here. Would prefer to merge the skeleton with placeholders and dirty annotations (and even let that go live on the site), then systematically go through each item and improve through smaller, atomic PRs.

Looks good, few suggestions:

• move site/98-reference/faq.md into site/06-faq (and break sections into files)
• simlink site/98-reference, similarly to specs.
• add placeholder for dev section (not to be published)