docs: generate docs/README.md instead of listing filenames

[sethbergman]

make docs was a placeholder that ran ls docs/, which is what GitHub
already shows when you open the directory: sixteen filenames, and no way
to tell that audit.md is the file explaining why two audit devices are
the dangerous configuration.

It now builds docs/README.md from each document's own H1 and H2
headings. Deriving the index rather than writing one alongside the docs
is the point: a hand-maintained index stops covering each new document
silently, and the omission is invisible to everyone except the reader
who needed that document.

CI runs the generator with --check, so a new document, a renamed section
or a hand-edit to the index fails as a diff with make docs as the fix.
That alone would be circular — a generator that misread a heading would
produce a wrong description CI then defends, since both halves of the
diff come from it — so tests/docs-index covers the reading: headings
inside fenced code blocks are not sections (several docs open with a
shell block containing a ## comment), a document with no title is an
error rather than an empty link, a pipe in a heading is escaped rather
than ending the table cell, --check reports staleness without quietly
fixing it, and regeneration is idempotent because the index does not
index itself.

Each of those was verified by breaking the generator in a way the
assertion does not name.