docs(embedded-mpv): clarify Linux system runtime baseline

AGENTS.md

@@ -227,6 +227,9 @@ Key files:
       dependencies `libmpv2`/`mpv-libs`/`mpv`
     - `portable`: AppImage/Snap with the pinned LGPL-compatible closure
     - `flatpak`: Flatpak with the same pinned closure
+- The DEB system-runtime contract is Ubuntu 24.04+ (`libmpv2`). Ubuntu 22.04
+  provides `libmpv1`, so use the x64 AppImage on Jammy instead of weakening the
+  package dependency or advertising frame-copy without a compatible runtime.
 - Only `iptvnator_mpv_helper` may link libmpv. The Electron executable,
   Electron libraries, `embedded_mpv.node`, and
   `embedded_mpv_frame_reader.node` must not load or link it. Preserve this

CLAUDE.md

@@ -629,7 +629,9 @@ engine` (restart required) or
   `iptvnator_mpv_helper` may link libmpv; Electron, its shipped libraries, the
   addon, and frame reader must not. Official x64 packages use three separate
   profiles: DEB/RPM/Pacman depend on system libmpv, AppImage/Snap bundle the
-  pinned LGPL closure, and Flatpak bundles the same closure. ARM packages are
+  pinned LGPL closure, and Flatpak bundles the same closure. The DEB contract
+  requires `libmpv2` and is verified on Ubuntu 24.04+; Ubuntu 22.04 users need
+  the x64 AppImage because Jammy provides `libmpv1`. ARM packages are
   marker-only. Stored or explicit opt-ins cannot bypass the fail-closed
   packaged manifest/file/hash gate and bounded `--runtime-probe`; any failure
   keeps the sandbox enabled, records a stable reason, and falls back to

docs/architecture/embedded-mpv-native.md

@@ -83,6 +83,11 @@ one unpacked application layout per pass:
 | `portable` | AppImage, Snap   | Bundled pinned LGPL-compatible runtime under `native/lib`                                     |
 | `flatpak`  | Flatpak          | The same bundled pinned LGPL-compatible runtime under `native/lib`                            |
 
+The DEB contract deliberately names `libmpv2`, not a loose `libmpv`
+alternative. Release CI verifies that contract on Ubuntu 24.04 (Noble).
+Ubuntu 22.04 (Jammy) provides `libmpv1`, so its DEB cannot enable this
+system-runtime frame-copy path; use the x64 AppImage there instead.
+
 Every x64 layout contains the addon, frame reader, helper, and a normalized
 `embedded-mpv-runtime.json`. The Electron executable, Electron libraries,
 `embedded_mpv.node`, and the frame reader must not link libmpv; only the helper
@@ -549,7 +554,9 @@ Linux release profiles:
 - `IPTVNATOR_LINUX_FRAME_COPY_PROFILE=system` builds DEB, RPM, and Pacman.
   `afterPack` removes the private `lib` directory, writes a
   `system-libmpv-frame-copy` manifest, and package metadata requires
-  `libmpv2`, `mpv-libs`, or `mpv`.
+  `libmpv2`, `mpv-libs`, or `mpv`. The DEB path is verified on Ubuntu 24.04+;
+  Ubuntu 22.04 users need the x64 AppImage because Jammy only provides
+  `libmpv1`.
 - `IPTVNATOR_LINUX_FRAME_COPY_PROFILE=portable` builds AppImage and Snap with
   the pinned source-built closure and a `bundled-lgpl-frame-copy` manifest.
 - `IPTVNATOR_LINUX_FRAME_COPY_PROFILE=flatpak` builds Flatpak with the same

tools/embedded-mpv/README.md

@@ -110,6 +110,10 @@ Set one exact `IPTVNATOR_LINUX_FRAME_COPY_PROFILE` per packaging pass:
 | `portable` | AppImage, Snap   | Retain the pinned LGPL closure under `native/lib`            |
 | `flatpak`  | Flatpak          | Retain the same pinned LGPL closure under `native/lib`       |
 
+The DEB metadata requires `libmpv2` and is release-tested on Ubuntu 24.04
+(Noble). Ubuntu 22.04 (Jammy) only provides `libmpv1`; use the x64 AppImage on
+that distribution rather than relaxing the runtime contract.
+
 Profiles cannot share one Electron Builder pass because its targets reuse the
 same unpacked application directory. A missing or unsupported profile, or a
 target from another profile, fails packaging.

vendor/embedded-mpv/README.md

@@ -26,6 +26,9 @@ Linux package profiles consume that one staged x64 source runtime differently:
 - Non-x64 Linux packages retain no native artifacts and ship only the
   unavailable marker.
 
+The DEB dependency is specifically `libmpv2` (verified on Ubuntu 24.04+).
+Ubuntu 22.04 provides `libmpv1`; use the x64 AppImage there.
+
 Only `iptvnator_mpv_helper` may link libmpv. Electron,
 `embedded_mpv.node`, and `embedded_mpv_frame_reader.node` must remain free of
 direct libmpv dependencies. See `tools/embedded-mpv/README.md` and