feat(ci): add lychee broken link checker and stage-and-check job

Signed-off-by: skjnldsv <skjnldsv@protonmail.com>

Co-authored-by: skjnldsv <14975046+skjnldsv@users.noreply.github.com>

Author: skjnldsv

.github/workflows/sphinxbuild.yml

@@ -304,6 +304,50 @@ jobs:
           echo "Staged artifacts for ${branch}:"
           find stage -type f | head -20
 
+      # ========================================================================
+      # VALIDATION: CHECK FOR BROKEN LINKS (NEW CONTENT IN FULL CONTEXT)
+      # ========================================================================
+      # For link validation, we need the full context (existing versions) so
+      # lychee can resolve cross-version references. So we:
+      # 1. Build a temporary validation structure with both old and new content
+      # 2. Run lychee only against the NEW content
+      # 3. Clean up the temporary structure
+      # ========================================================================
+      - name: Build full validation context
+        run: |
+          branch="${{ steps.branch.outputs.branch_name }}"
+
+          # Build validation structure: start with existing versions
+          mkdir -p full-context/server
+          cp -r validation-context/server/* full-context/server/ || true
+
+          # Merge in the new artifacts
+          mkdir -p "full-context/server/${branch}"
+          cp -r "stage/${branch}/"* "full-context/server/${branch}/" || true
+
+          echo "Validation structure ready:"
+          find full-context -type d -maxdepth 2
+
+      - name: Check for broken links with lychee
+        uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411 # v2.8.0
+        with:
+          fail: true
+          token: ${{ secrets.GITHUB_TOKEN }}
+          jobSummary: true
+          args: |
+            --root-dir $(pwd)/full-context
+            --offline
+            --no-progress
+            --remap 'https://docs.nextcloud.com/server/ file://$(pwd)/full-context/server/'
+            --exclude 'mailto:'
+            --exclude '(https?:/?/?)?$'
+            --exclude-path '.*/404\.html'
+            'full-context/server/${{ steps.branch.outputs.branch_name }}/**/*.html'
+
+      - name: Clean up validation context
+        if: always()
+        run: rm -rf full-context
+
       # ========================================================================
       # UPLOAD STAGING ARTIFACTS
       # ========================================================================