Auto-generated API doc: doxygen → custom Python emitter → doc/api/.

`cmake --build build --target doc` runs Doxygen to produce XML, then
`doc/gen_api_md.py` (~330 lines, stdlib-only) emits a Markdown tree
under `doc/api/` that gitea renders directly in its file browser.

- 24 class/struct pages + 51 source-file pages + indices, with source
  links of the form `../../../../src/...#L42` that gitea turns into
  clickable line-anchored links.
- Doxyfile.in templated by CMake (XML-only output to build/doc/xml/).
- Pure Python emitter, zero external deps — no doxybook2 (not packaged
  on Arch) and no moxygen (avoids Node).
- Target gracefully disabled if Doxygen or Python 3 is missing at
  configure time; regular build target unaffected.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

doc/README.md

@@ -0,0 +1,73 @@
+# essim documentation
+
+Auto-generated API reference and high-level design notes for the
+[essim](../README.md) system digital twin.
+
+## Layout
+
+- [`api/`](api/) — auto-generated API reference (Doxygen XML → custom
+  Markdown emitter). Browse classes and files directly in gitea's
+  Markdown renderer. Top page: [`api/index.md`](api/index.md).
+- [`../DESIGN.md`](../DESIGN.md) — implementation notes: domain
+  conventions, TUI flow, gotchas. Hand-maintained.
+- [`classes.puml`](classes.puml) — PlantUML class diagram for the
+  domain model. Render with `plantuml classes.puml` for a PNG/SVG.
+- [`Doxyfile.in`](Doxyfile.in) / [`gen_api_md.py`](gen_api_md.py) —
+  the toolchain (templated Doxygen config + custom XML→Markdown emitter).
+
+## Regenerating the API reference
+
+The Markdown tree under `doc/api/` is committed so it's readable directly
+on gitea. After substantive code changes, regenerate it:
+
+```sh
+# 1. Tooling (once): Doxygen, plus a Python 3 interpreter (already on Arch).
+pacman -S doxygen
+
+# 2. Configure once (or after editing doc/Doxyfile.in):
+cmake -S . -B build
+
+# 3. Regenerate:
+cmake --build build --target doc
+
+# 4. Review and commit the updated doc/api/ tree:
+git add doc/api/
+git status doc/api/
+```
+
+Pipeline:
+
+```
+src/**/*.{hpp,cpp}  ──┐
+README.md            ─┼─► doxygen ─► build/doc/xml/  ─► gen_api_md.py ─► doc/api/
+DESIGN.md            ─┘            (Doxyfile.in)
+```
+
+If either Doxygen or Python 3 is missing at CMake-configure time the
+`doc` target is silently disabled (the regular build still works) and a
+status line is emitted in the CMake log telling you which one to install.
+
+## Why a custom emitter rather than `doxybook2` / `moxygen`
+
+- **`doxybook2`** is not packaged in Arch / AUR and gets stale upstream.
+- **`moxygen`** drags Node into a pure-C++ project.
+- The emitter is one Python file (`gen_api_md.py`, ~330 lines) with
+  zero external dependencies — easy to read, easy to tweak, robust to
+  Doxygen version changes (the XML schema is stable).
+
+Tailor the output by editing `gen_api_md.py` directly: add columns to
+the class table, change the source-link format, group sections
+differently, etc.
+
+## Comment style
+
+The codebase uses standard Doxygen markers:
+
+- `///` for single-line briefs.
+- `/** … */` for multi-line blocks.
+- `@param`, `@return`, `@brief` (or `@short`) tags inside blocks.
+- `@throws` for exceptions a function may raise.
+
+`JAVADOC_AUTOBRIEF = YES` is set so the first sentence of a multi-line
+comment counts as the brief description without needing an explicit
+`@brief` tag.