Antora migration polish: zero warnings + local mermaid + CI fix (#496)

[michalharakal]

Closes #496. Also unblocks the failing `bundleDokkaIntoSite` CI run on develop (see commit 3 below).

Summary

Clears every warning emitted by the Antora build, fixes a CI permission failure that was hiding behind the first post-merge `workflow_dispatch` of `docs.yml`, and replaces the asciidoctor-kroki dependency with a local mermaid renderer so builds no longer depend on kroki.io at all.

Warning count: 13 → 0. Errors: 0.

Four commits

1. `4a745624` — component attributes for operator-design

Adds `asciidoc.attributes` block to `docs/antora.yml` defining `framework_name`, `ksp_version`, `dokka_version`, `asciidoctorj_version` — the four attribute references in `operator-design.adoc` the original author never declared. Antora component-level attributes flow to every page, so seven `{FRAMEWORK_NAME}` / `{KSP_VERSION}` / `{DOKKA_VERSION}` / `{ASCIIDOCTORJ_VERSION}` placeholders now resolve to real values. 13 → 7 warnings.

2. `7a459bf3` — strip pandoc anchors + cascade-demote headings

The 6 "section title out of sequence" warnings in `skainet-for-ai.adoc` and `arduino-c-codegen.adoc` looked like they were about heading levels but turned out to be about 20 `[[...]]` anchor lines that pandoc generated above every heading. In that position Asciidoctor binds them to the next block as bibliographic markers, which blocks the `==` / `===` from registering as section-opening headings, which drifts the parser's level counter. Stripping the anchors fixes the hierarchy parse; Asciidoctor auto-generates id-from-title anchors anyway so URL fragments stay stable. Also cascade-demoted the two files' headings by one level (`sed -E 's/^=(=+ )/\\1/'`) so they start with the idiomatic `= Page Title`. 7 → 1 warning.

3. `ca06cf51` — CI permission fix on bundleDokkaIntoSite

First CI run of the post-migration `docs.yml` failed with `Failed to create directory docs/build/site/api` during the `bundleDokkaIntoSite` step. Root cause: the Antora container was running as root, so `docs/build/site/` was root-owned, and the subsequent Gradle task (running on the runner host as the `runner` user) couldn't `mkdir` inside it.

Two coupled fixes, both necessary:

• Add `--user "$(id -u):$(id -g)"` to the `docker run` invocation so the container writes as the runner user.
• Set `runtime.cache_dir: ./.cache/antora` in the playbook because running as non-root kills the default `$HOME/.cache/antora` resolution (the container process has no matching passwd entry and `$HOME` falls back to `/`, which an unprivileged user can't write). The `.cache/` path is already gitignored via the pre-staged `## antora` section in the root `.gitignore`.

Verified end-to-end locally with the full CI flow (clean site dir → non-root Antora run → writable cache dir → Gradle bundle succeeds → `docs/build/site/api/` populated with the Dokka aggregate).

4. `724f72bd` — drop kroki, render mermaid locally

The final warning was `asciidoctor-kroki: Skipping mermaid block` in `hlo-getting-started.adoc`. Kroki was returning HTTP 400 for one diagram; switching from GET to POST didn't help (kroki.io rejected the POST for a different reason with an empty response body). The fix is to stop using kroki at all and render mermaid locally via `@mermaid-js/mermaid-cli` which the Docker image already bakes in.

Pipeline change:

[mermaid]      -->  local-mermaid-extension.js
----           -->  writes source to /tmp/skainet-mm-*/in.mmd
source         -->  exec mmdc -i in.mmd -o out.svg
----           -->  emits SVG as a \`pass\` block, inlined into HTML

Changes:

• `docs/.docker/Dockerfile`: drop `asciidoctor-kroki@0.18` from the npm install; `COPY local-mermaid-extension.js` into `/opt/antora/`.
• `docs/.docker/local-mermaid-extension.js` (new, ~90 lines): Asciidoctor.js block processor mirroring the shape used by asciidoctor-kroki (same `onContext`, `process`, `createBlock` pattern) but dispatching to `/opt/antora/node_modules/.bin/mmdc` via `child_process.execSync`. Cleans its temp dir in a `finally`. On failure emits a literal block with the original source + mmdc's stderr so degradation is visible.
• `docs/antora-playbook.yml`: swap `asciidoctor-kroki` extension for `/opt/antora/local-mermaid-extension.js`; drop the two `kroki-*` attributes.
• `docs/modules/ROOT/pages/tutorials/hlo-getting-started.adoc`: first real mermaid-cli render surfaced a previously-hidden authoring bug — a `sequenceDiagram` participant was aliased as `Opt`, and `opt` is a mermaid sequenceDiagram keyword (case-insensitive match, optional blocks). Kroki had been silently dropping this diagram the whole time; local rendering surfaced the actual error. Renamed to `Optimizer`.

Verification

docker build --no-cache -t skainet-antora:local docs/.docker
rm -rf docs/build/site docs/.cache
docker run --rm --user \"\$(id -u):\$(id -g)\" \\
    -v \"\$PWD:/antora\" -w /antora \\
    skainet-antora:local docs/antora-playbook.yml
grep -c \"<svg\" docs/build/site/skainet/tutorials/hlo-getting-started.html
# => 3  (one inline SVG per [mermaid] block, all three diagrams)
./gradlew --no-daemon bundleDokkaIntoSite
ls docs/build/site/api   # full Dokka aggregate

Warning count: 0. Error count: 0. Rendered inline SVG count: 3.

Net effect

• The Antora site builds cleanly with zero noise.
• No network dependency at build time: kroki.io is out of the stack entirely.
• `docs.yml` CI runs green end-to-end from first run. No manual fix needed post-merge.
• Docker image is strictly smaller (one less npm dep, asciidoctor-kroki + transitive deps gone).
• Every mermaid block in every page renders locally and consistently, regardless of size.

🤖 Generated with Claude Code

[github-actions]

📖 Documentation Preview

The documentation has been built successfully for this PR.

Generated Files:

• Operator documentation: docs/modules/operators/_generated_/
• JSON schema output: operators.json

Artifacts:

• Download the documentation-preview-497 artifact to view the complete documentation locally.

This comment will be updated automatically when the PR is updated.