feat(build): optional xvfb-run for Linux GUI builds

Add an --xvfb switch to 'build run' and 'job' that wraps the Linux build
command in 'xvfb-run -a sh -c ...', giving GUI toolkits (GTK4/PyGObject)
a headless $DISPLAY. Exported env vars precede xvfb-run so they
propagate into the virtual-display session. No-op (with a notice) for
Windows guests.

The local-ci-build composite action exposes it as the 'xvfb' input
(default false), forwarded as INPUT_XVFB -> --xvfb, mirroring the
use-shared-cache/skip-artifact wiring.

Docs: WORKFLOW-AUTHORING.md parameter table + Linux example note;
LINUX-TEMPLATE-SETUP.md Step 4a (the template ships python3-gi
gir1.2-gtk-4.0 xvfb). Adds build-run unit tests (wrap, plain, Windows
no-op).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/LINUX-TEMPLATE-SETUP.md

@@ -229,11 +229,13 @@ Eseguito da Prepare via SSH come `ci_build` con sudo.
 Header: `#!/usr/bin/env bash` + `set -euo pipefail`
 Helper `assert_step()`: stampa `[OK] [Step N] desc` su successo, `exit 1` su fallimento.
 
-- [x] **Step 1  apt update + upgrade** (saltabile con `--skip-update`)
+- [x] **Step 1  apt update (+ upgrade)**
   ```bash
-  sudo DEBIAN_FRONTEND=noninteractive apt-get update -qq
-  sudo DEBIAN_FRONTEND=noninteractive apt-get upgrade -y -qq
+  sudo DEBIAN_FRONTEND=noninteractive apt-get update -qq        # sempre
+  sudo DEBIAN_FRONTEND=noninteractive apt-get upgrade -y -qq    # saltato da --skip-update
   ```
+  > `apt-get update` gira **sempre** (l'indice deve essere fresco per trovare i
+  > pacchetti). `--skip-update` salta solo l'`upgrade` (lento).
 
 - [x] **Step 2  Toolchain build essentials**
   ```bash
@@ -257,6 +259,15 @@ Helper `assert_step()`: stampa `[OK] [Step N] desc` su successo, `exit 1` su fal
   ```
   - assert: `command -v git`, `command -v 7z`
 
+- [x] **Step 4a  GTK4 / GObject + Xvfb** (test GUI headless, es. PyGObject)
+  ```bash
+  sudo apt-get install -y -qq python3-gi gir1.2-gtk-4.0 xvfb
+  ```
+  - assert: `python3 -c "import gi"`, `command -v Xvfb`
+  - Usato a runtime dai build con il flag `--xvfb` / `-Xvfb` (vedi
+    [WORKFLOW-AUTHORING.md](WORKFLOW-AUTHORING.md) §5): il comando di build gira
+    sotto `xvfb-run` con un `$DISPLAY` virtuale.
+
 - [x] **Step 4b  .NET SDK** (opzionale, flag `--dotnet`)
   ```bash
   curl -fsSL https://dotnet.microsoft.com/download/dotnet/scripts/v1/dotnet-install.sh \

docs/WORKFLOW-AUTHORING.md

@@ -134,6 +134,7 @@ Script location (fixed on host): `N:\Code\Workspace\Local-CI-CD-System\scripts\I
 | `-GuestOS`               | string | `Auto`                         | `Windows`, `Linux`, or `Auto` (detected from VMX guestOS field). |
 | `-BuildCommand`          | string | `''`                           | Shell command to run inside VM. Empty = `dotnet build`.          |
 | `-GuestArtifactSource`   | string | `dist`                         | Path inside VM guest from which artifacts are collected.         |
+| `-Xvfb`                  | switch | off                            | Linux only: run the build under `xvfb-run` (headless X for GUI toolkits, e.g. GTK4/PyGObject). Needs `xvfb` in the template (installed by the toolchain). Ignored for Windows. |
 | `-Submodules`            | switch | off                            | Pass to clone with `--recurse-submodules`.                       |
 | `-UseGitClone`           | switch | off                            | Skip host-side clone; let the guest VM clone directly via HTTPS. |
 | `-GiteaCredentialTarget` | string | `GiteaPAT`                     | Credential Manager target for Gitea PAT (UseGitClone only).      |
@@ -321,6 +322,15 @@ Notes:
 - `-SshKeyPath $env:GITEA_CI_SSH_KEY_PATH` uses the injected key path.
 - The default snapshot name for Linux templates is `BaseClean-Linux`. If you rely on
   `Auto`, add `-SnapshotName 'BaseClean-Linux'` explicitly.
+- For builds or tests that need a display (GUI toolkits such as GTK4/PyGObject),
+  add the `-Xvfb` switch — the build command then runs under `xvfb-run` with a
+  headless X server providing `$DISPLAY`. Example:
+  ```powershell
+            -BuildCommand        'xvfb-aware-tests.sh' `
+            -Xvfb `
+  ```
+  The Ubuntu template ships `python3-gi`, `gir1.2-gtk-4.0` and `xvfb`
+  (installed by the toolchain). `-Xvfb` is ignored for Windows guests.
 
 ### 8.3 Windows build (UseGitClone mode)