feat: Flatpak packaging for the HeiniRemote agent

Bundles the agent as de.pc_heini.HeiniRemoteAgent on the freedesktop 24.08
runtime, mirroring the o3de-flatpak CI approach (bwrap-free build, OSTree
repo force-pushed to pages, single-file bundle attached to a Gitea release).
Compiles the agent from upstream source (newest v* tag, else main).

Sandbox notes: screen capture/input via portals need no special permission;
the PTY console uses flatpak-spawn --host for a real host shell, and a native
install's agent.toml is adopted read-only.

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

README.md

@@ -0,0 +1,95 @@
+# heiniremote-flatpak
+
+Flatpak packaging for the [HeiniRemote](https://git.pc-heini.de/pc-heini/HeiniRemote)
+customer agent (`de.pc_heini.HeiniRemoteAgent`) — an additional distribution
+channel next to the plain release binary, with all dependencies (GStreamer,
+libnice, wl-clipboard, …) pinned inside the freedesktop 24.08 runtime.
+
+Same setup as [o3de-flatpak](https://git.pc-heini.de/pc-heini/o3de-flatpak):
+a Gitea Action builds the Flatpak **without** `flatpak-builder` (no bubblewrap
+needed in CI), exports it into an OSTree repo and force-pushes that to the
+`pages` branch. The difference: the agent is compiled from upstream source
+(newest `v*` tag, falling back to `main` while no release exists) instead of
+repackaging a prebuilt archive.
+
+## Install
+
+From the Flatpak remote (gets updates via `flatpak update`):
+
+```sh
+flatpak remote-add --if-not-exists heiniremote \
+  https://git.pc-heini.de/pc-heini/heiniremote-flatpak/raw/branch/pages/heiniremote.flatpakrepo
+flatpak install heiniremote de.pc_heini.HeiniRemoteAgent
+```
+
+Or as a single-file bundle (attached to each release of this repo, no remote
+needed, but no auto-updates either):
+
+```sh
+flatpak install ./heiniremote-agent-<version>.flatpak
+```
+
+## Configure
+
+The agent needs a server URL and device token. Inside the sandbox the config
+path is:
+
+```
+~/.var/app/de.pc_heini.HeiniRemoteAgent/config/heiniremote/agent.toml
+```
+
+If a native install already left a config at `~/.config/heiniremote/agent.toml`,
+the wrapper picks it up automatically (read-only). `HEINIREMOTE_SERVER_URL` /
+`HEINIREMOTE_TOKEN` env overrides work as usual:
+
+```sh
+flatpak run --env=HEINIREMOTE_SERVER_URL=wss://… de.pc_heini.HeiniRemoteAgent
+```
+
+## Autostart
+
+The native install runs as a systemd user service; the Flatpak equivalent is a
+user unit wrapping `flatpak run`:
+
+```ini
+# ~/.config/systemd/user/heiniremote-agent.service
+[Unit]
+Description=HeiniRemote agent (Flatpak)
+After=graphical-session.target
+
+[Service]
+ExecStart=flatpak run de.pc_heini.HeiniRemoteAgent
+Restart=on-failure
+
+[Install]
+WantedBy=graphical-session.target
+```
+
+## How the sandbox is punched
+
+Screen capture and input injection go through xdg-desktop-portal
+(ScreenCast + RemoteDesktop) — that is the normal, fully sandboxed path and
+needs no special permission. Two things do:
+
+- **`--talk-name=org.freedesktop.Flatpak`** — the PTY rescue console must show
+  the *host*, not the sandbox. The wrapper sets `SHELL=/app/bin/host-shell`,
+  which execs the user's real login shell via `flatpak-spawn --host`. This is
+  a deliberate sandbox escape; for a remote maintenance tool the sandbox is
+  packaging, not a security boundary.
+- **`--filesystem=xdg-config/heiniremote:ro`** — adopt a native install's
+  `agent.toml` (see above).
+
+Everything else is standard: `network` (signaling + WebRTC/TURN), `wayland`
+(bundled wl-copy/wl-paste), `dri` (dmabuf screencast buffers), and the
+StatusNotifier names for the tray icon.
+
+## Repo layout
+
+| File | Role |
+|---|---|
+| `.gitea/workflows/build-flatpak.yml` | CI: resolve upstream version → cargo build → assemble → publish `pages` + release bundle. Daily schedule picks up new upstream versions. |
+| `scripts/get-latest-version.sh` | Newest upstream `v*` tag, else `main` HEAD (`0.0.0-git.<date>.<sha>`). |
+| `scripts/make-flatpak.sh` | bwrap-free assembly: `build-init` → copy files → `build-finish` → `build-export`. |
+| `heiniremote-wrapper.sh` | Entry point: host-shell `$SHELL` override + config adoption. |
+| `host-shell.sh` | `flatpak-spawn --host` bridge for the PTY console. |
+| `de.pc_heini.HeiniRemoteAgent.*` | Desktop file, AppStream metainfo (version stamped by CI), icon. |