If we're going to split the documentation across files, that's probably good - I've had grumblings in the past that GitHub's generated table of contents doesn't actually scroll so folks can't scroll through all the headers - but we should consider what this means for the docs in pkg.go.dev, which I believe only pull from README.md - do we need to make sure there's a subset of docs available for pkg.go.dev? Does docs/... work there?

I think if we're going to use Markdown-committed table of contents, we need a way to keep them up-to-date (via automation).

I guess you've generated them one-time using Claude, but to make it consistent, this needs to be automatable + validated in CI

Also, the reason for using an HTML table over Markdown is that it's easier to add new entries without worrying about formatting (should we be introducing whitespace to make sure all the Markdown table columns line up?) etc

(Haven't yet fully reviewed the different pages - will do shortly)