docs(skills): document Tuner libpeas gotcha, fix exceptions table, runtime-update PRs, empty x-version

- app-gotchas.md: add org.altlinux.Tuner section (-Dgjs=false for libpeas 2.x on
  GNOME Platform 49; mozjs-128 not available); add Tuner row to app table
- pipeline.md: rewrite exceptions table as conditional (screenshots vs no-screenshots);
  add Runtime-update PRs section (CI doesn't trigger with no flatpaks/ diffs)
- versioning.md: document empty x-version string as equivalent to absent x-version;
  add Flathub API curl one-liner for checking current upstream version

Assisted-by: Claude Sonnet 4.6 via OpenCode

Author: castrojo

skills/app-gotchas.md

@@ -12,6 +12,7 @@ Per-app known issues and workarounds. Each app has a dedicated `GOTCHAS.md` in i
 | firefox-nightly | `flatpaks/firefox-nightly/GOTCHAS.md` | app-id is `org.mozilla.firefox.nightly` (renamed from `org.mozilla.firefox` to avoid Flathub clash), rolling aarch64 sha256, BaseApp required pre-install, `.appdata.xml` skips CI validation |
 | thunderbird-nightly | `flatpaks/thunderbird-nightly/GOTCHAS.md` | x86_64 only (no aarch64), comm-central icon pinning — verify each size sha256 independently (swap of 32/64 was a bug), `--persist=.thunderbird-nightly` profile isolation, no BaseApp pre-install needed, extension stubs created in build-commands (not cleanup-commands) |
 | virtualbox | `flatpaks/virtualbox/GOTCHAS.md` | KVM backend (no vboxdrv kernel module), X11 only (VBoxSVGA Wayland bug), hardening disabled, gsoap serial build, shared-modules SDL1+GLU inlined |
+| org.altlinux.Tuner | (inline in `app-gotchas.md`) | `libpeas` 2.x requires `-Dgjs=false` on GNOME Platform 49 (mozjs-128 not available) |
 
 ## Flatpak install scope — always system-wide
 
@@ -105,6 +106,35 @@ x-skip-launch-check: true
 
 Applies to: **goose**, **lmstudio** (any Electron GUI app).
 
+## org.altlinux.Tuner
+
+### libpeas 2.x: `-Dgjs=false` required on GNOME Platform 49
+
+`libpeas` 2.0.x depends on `gjs` (GNOME JavaScript), which requires SpiderMonkey
+(`mozjs-128`). `mozjs-128` is **not included** in `org.gnome.Platform//49`, so the
+`libpeas` build fails on any clean x86_64 build with:
+
+```
+meson: error: Dependency "mozjs-128" not found
+```
+
+**Fix:** add `-Dgjs=false` to the `libpeas` module's `config-opts`:
+
+```yaml
+- name: libpeas
+  buildsystem: meson
+  config-opts:
+    - -Dgjs=false
+    # ... other opts
+```
+
+This disables the GJS plugin loader; Tuner does not use it, so functionality is unaffected.
+
+**Why aarch64 may pass while x86_64 fails:** flatpak-builder caches build artifacts
+by content hash. If a prior aarch64 build of `libpeas` was cached before the mozjs-128
+check was enforced, the cached result is reused and the step appears to pass. A clean
+build (no cache) will reproduce the failure on both arches.
+
 ## bundle-repack apps: no metainfo injection
 
 The `release.yaml` pipeline downloads a pre-built upstream `.flatpak` and repackages it as

skills/pipeline.md

@@ -127,6 +127,16 @@ until CI passes end-to-end:
 Never close a "new app" issue based solely on files being committed. The Flatpak
 must be buildable and installable before the issue is closed.
 
+## Runtime-update PRs
+
+When a runtime-update PR is created (e.g. by raptor[bot] or Copilot), the manifest
+may already reflect the target state — `runtime-version` set on import with no other
+diffs. **CI will not trigger on a branch with no file changes to `flatpaks/`.**
+
+To trigger CI: make a real, correct change to the manifest. The canonical fix is to
+set `x-version` to the current upstream release version (check Flathub or the upstream
+repo). This is always a valid improvement — `x-version` must not be empty.
+
 ## flatpak-builder-lint known errors
 
 `build.yml` runs `flatpak-builder-lint manifest "flatpaks/$app/manifest.yaml"` during CI.
@@ -195,16 +205,23 @@ Both steps use the same `exceptions.json` file as the manifest lint step.
 
 #### Required exceptions for non-Flathub repos
 
-These errors fire on every manifest.yaml app in testhub (not Flathub-specific behavior):
+These errors can fire on manifest.yaml apps in testhub. Which ones apply depends on the
+app's metainfo content:
 
-| Exception | Reason |
-|---|---|
-| `appstream-screenshots-not-mirrored-in-ostree` | No `--mirror-screenshots-url` passed; not required outside Flathub |
-| `appstream-no-flathub-manifest-key` | `flathub::manifest` custom tag only required for Flathub submissions |
-| `appstream-external-screenshot-url` | Same root cause as above — screenshots not mirrored |
-| `metainfo-missing-screenshots` | Personal hosting repo — no screenshots maintained here |
-
-Add these **four** to `exceptions.json` for every manifest.yaml app.
+| Exception | When it fires | Add? |
+|---|---|---|
+| `appstream-no-flathub-manifest-key` | Always — `flathub::manifest` custom tag only required for Flathub submissions | Always |
+| `appstream-screenshots-not-mirrored-in-ostree` | App has screenshots in metainfo but `--mirror-screenshots-url` not passed | If app has screenshots |
+| `appstream-external-screenshot-url` | App has screenshots pointing to external URLs (not dl.flathub.org/media) | If app has screenshots |
+| `metainfo-missing-screenshots` | App has no screenshots in metainfo | If app has no screenshots |
+
+**Practical rule:** Add `appstream-no-flathub-manifest-key` universally. Then:
+- If the app **has** screenshots in metainfo: add `appstream-external-screenshot-url` + `appstream-screenshots-not-mirrored-in-ostree`
+- If the app **has no** screenshots: add `metainfo-missing-screenshots`
+
+Note: `appstream-screenshots-not-mirrored-in-ostree` and `appstream-external-screenshot-url`
+fire at **different** lint stages (builddir vs repo respectively) — both must be in
+`exceptions.json` or the build will fail at one stage even if the other passes.
 
 If CI surfaces additional errors after first run, add them to `exceptions.json` and
 document in the app's `GOTCHAS.md`. Do not add metainfo fields we cannot keep accurate

skills/versioning.md

@@ -14,11 +14,15 @@ Every package must carry an explicit version tag on ghcr.io in addition to `:lat
 - `release.yaml` apps: `version` is a required field — CI errors if missing.
 - `manifest.yaml` apps: add `x-version: "<version>"` as a top-level field.
   flatpak-builder ignores `x-`-prefixed fields — safe to add.
-- If `x-version` is absent, the build warns and pushes `:latest` only.
+- If `x-version` is absent **or set to an empty string (`x-version: ''`)**, the build
+  warns and pushes `:latest` only. Both cases are equivalent failures — always set a
+  real version string.
 - Version strings must reflect the actual upstream app version — not build dates,
   git shas, or repo versions.
 - When upgrading an app, update `x-version` (or `version`) in the same commit that
   updates the source URL and sha256.
+- **Checking the current version:** use the Flathub API:
+  `curl -s https://flathub.org/api/v2/appstream/<app-id> | python3 -c "import json,sys; d=json.load(sys.stdin); print([r['version'] for r in d.get('releases',[])][:3])"`
 
 ## Source URL convention (manifest.yaml apps)