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/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)