feat(ci): Gitea Actions — dockerized web/docs/rust-ci images, Apple client CI, Mac runner

Three workflows: ci.yml (Rust workspace inside the punktfunk-rust-ci
builder image + web/docs-site build+typecheck), docker.yml (build+push
punktfunk-web, punktfunk-docs, punktfunk-rust-ci to git.unom.io — host
and native clients stay un-dockerized by design), apple.yml (host-mode
macos-arm64 runner: Rust core -> PunktfunkCore.xcframework ->
swift build + swift test).

ci/rust-ci.Dockerfile: Ubuntu 26.04 with the workspace's link deps
(FFmpeg 8, PipeWire, Opus, GL/EGL/GBM, xkbcommon, libcuda via the
580-server userspace as a link stub) + pinned rustup + node for the JS
actions. Verified end to end in-container: build, 141/141 tests, C ABI
harness; all three images seeded to the registry manually.

scripts/ci/setup-macos-runner.sh provisions the Mac (rustup + darwin
targets, Node tarball, gitea-runner 1.0.8 host mode, LaunchAgent with
DEVELOPER_DIR auto-detect for sudo-free Xcode selection). Docs in
docs-site/content/docs/ci.md.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs-site/content/docs/ci.md

@@ -0,0 +1,67 @@
+---
+title: "CI & Docker"
+description: "Gitea Actions setup — workflows, the dockerized pieces, and the runners."
+---
+
+CI runs on **Gitea Actions** (`git.unom.io`, org `unom`). Three workflows in
+`.gitea/workflows/`, two runners, three images in the Gitea container registry.
+
+## Workflows
+
+| Workflow | Trigger | Runner | What it does |
+|---|---|---|---|
+| `ci.yml` | push to `main`, PRs | `ubuntu-latest` | Rust workspace (fmt · clippy `-D warnings` · build · test · C-ABI harness · generated-header drift) inside the `punktfunk-rust-ci` image; `web/` and `docs-site/` build + typecheck in `oven/bun:1` |
+| `docker.yml` | push to `main`, `v*` tags, manual | `ubuntu-latest` | Builds + pushes the three images below (`latest` + `sha-<short>` tags) |
+| `apple.yml` | push to `main`, PRs, manual | `macos-arm64` | Rust core → `PunktfunkCore.xcframework` → `swift build` + `swift test` in `clients/apple` |
+
+## Dockerized pieces
+
+The host and the native clients are intentionally **not** containerized (the host needs
+the GPU/compositor stack of the box it runs on). What is:
+
+| Image | Source | Notes |
+|---|---|---|
+| `git.unom.io/unom/punktfunk-web` | `web/Dockerfile` (repo-root context — orval needs `docs/api/openapi.json`) | Nitro `bun` bundle; `PORT` (3000) and `PUNKTFUNK_MGMT_URL` env at runtime |
+| `git.unom.io/unom/punktfunk-docs` | `docs-site/Dockerfile` | This site; `PORT` (3000) |
+| `git.unom.io/unom/punktfunk-rust-ci` | `ci/rust-ci.Dockerfile` | Ubuntu 26.04 + FFmpeg 8/PipeWire/GL/GBM dev libs + a libcuda **link stub** (driver userspace, no kernel module) + pinned rustup — the container `ci.yml`'s Rust job runs in |
+
+Registry pushes authenticate with the repo Actions secret **`REGISTRY_TOKEN`** (a PAT
+with `write:package`; the login username in `docker.yml` is the token owner, not the
+push actor).
+
+## Runners
+
+- **`ubuntu-latest`** — the pre-existing Linux runner; runs the Rust/web/docs jobs (as
+  docker containers) and the image build+push jobs.
+- **`macos-arm64`** — `home-mac-mini-1` (M-series, macOS 26), a **host-mode**
+  `act_runner` (upstream now ships it as `gitea-runner`) provisioned by
+  [`scripts/ci/setup-macos-runner.sh`](https://git.unom.io/unom/punktfunk/src/branch/main/scripts/ci/setup-macos-runner.sh):
+  rustup (+ both darwin targets for the universal xcframework), Node.js (host-mode runners
+  execute JS actions via `node` from PATH — nothing auto-provisions it), the runner binary
+  in `~/.local/bin`, state in `~/ci/act-runner/` (config, `.runner` registration,
+  `runner.log`), kept alive by the `io.gitea.act_runner` LaunchAgent. Needs full **Xcode**
+  for `xcodebuild -create-xcframework` (CLT alone only covers `swift build/test`); if
+  `xcode-select` still points at CLT, the script auto-detects `/Applications/Xcode*.app`
+  and bakes a `DEVELOPER_DIR` override into the LaunchAgent — no sudo required.
+
+Re-provisioning (idempotent) or first-time registration from a dev box:
+
+```sh
+# token: org unom → Settings → Actions → Runners → Create new runner
+ssh enricobuehler@192.168.1.135 GITEA_RUNNER_TOKEN=<token> bash -s \
+    < scripts/ci/setup-macos-runner.sh
+```
+
+## Troubleshooting
+
+- **Mac runner offline** — `ssh <mac> tail -50 '~/ci/act-runner/runner.log'`; restart with
+  `launchctl kickstart -k gui/$(id -u)/io.gitea.act_runner`. After a reboot with nobody
+  logged in, the LaunchAgent only starts once auto-login is enabled (or promote the plist
+  to a LaunchDaemon).
+- **`apple.yml` fails at the xcframework step** — Xcode missing or unselected:
+  `sudo xcode-select -s /Applications/Xcode.app/Contents/Developer` and accept the license
+  (`sudo xcodebuild -license accept`), then re-run.
+- **Rust job can't pull `punktfunk-rust-ci`** — the runner host's docker daemon needs a
+  `docker login git.unom.io` if the org/registry isn't anonymously readable.
+- **Stale builder image after toolchain/dep changes** — `docker.yml` re-pushes it on every
+  `main` push; a manual `workflow_dispatch` of `docker.yml` forces a rebuild.

docs-site/content/docs/meta.json

@@ -7,12 +7,14 @@
     "implementation-plan",
     "roadmap",
     "m2-plan",
+    "apple-stage2-presenter",
     "---Setup---",
     "linux-setup",
     "headless-box",
     "gnome-box",
     "bazzite",
     "windows-host",
-    "dualsense-haptics"
+    "dualsense-haptics",
+    "ci"
   ]
 }