docs: prefer guides.xml over Settings.cfg for modern PHP-based rendering

- Update intercept-deployment.md with accurate webhook status codes (200, 204, 412)
- Add GitHub CLI automation examples for webhook setup
- Fix validate_docs.sh to accept either guides.xml OR Settings.cfg
- Update templates/AGENTS.md with complete guides.xml example configuration
- Update typo3-extension-architecture.md to document guides.xml as preferred

Based on learnings from setting up docs.typo3.org webhook for nr-saml-auth extension.
guides.xml uses modern PHP-based rendering while Settings.cfg is legacy Sphinx-based.

Author: CybotTM

references/intercept-deployment.md

@@ -14,9 +14,11 @@ Before setting up webhooks, ensure:
 2. **Git Repository Referenced**: The Git repository URL must be listed on your extension's TER detail page
 3. **Documentation Structure**: Your `Documentation/` directory must contain:
    - `Index.rst` (main entry point)
-   - `Settings.cfg` (documentation metadata)
+   - `guides.xml` (modern, preferred) OR `Settings.cfg` (legacy)
    - Valid RST files following TYPO3 documentation standards
 
+> **Note**: `guides.xml` is the modern PHP-based rendering configuration and is preferred over `Settings.cfg` (legacy Sphinx-based). New extensions should use `guides.xml`.
+
 ## Webhook Registration
 
 ### GitHub Setup
@@ -54,6 +56,32 @@ Before setting up webhooks, ensure:
    - Click **Add webhook** to save
    - GitLab will test the connection
 
+### GitHub CLI Automation
+
+For faster setup using `gh` CLI:
+
+```bash
+# Create webhook
+gh api repos/{owner}/{repo}/hooks \
+  --method POST \
+  --field name=web \
+  --field "config[url]=https://docs-hook.typo3.org" \
+  --field "config[content_type]=json" \
+  --field "config[insecure_ssl]=0" \
+  --raw-field "events[]=push" \
+  --field active=true
+
+# Trigger test delivery
+gh api repos/{owner}/{repo}/hooks/{hook_id}/tests --method POST
+
+# Check delivery status
+gh api repos/{owner}/{repo}/hooks/{hook_id}/deliveries \
+  --jq '.[] | {id: .id, status: .status, status_code: .status_code, event: .event}'
+
+# List webhooks to find hook_id
+gh api repos/{owner}/{repo}/hooks --jq '.[] | {id: .id, url: .config.url}'
+```
+
 ## First-Time Approval
 
 The first time you trigger documentation rendering, the TYPO3 Documentation Team must approve your repository:
@@ -76,7 +104,16 @@ The first time you trigger documentation rendering, the TYPO3 Documentation Team
 1. Go to **Settings** → **Webhooks**
 2. Click on the webhook
 3. Scroll to **Recent Deliveries**
-4. Verify delivery shows `200` response code
+4. Verify delivery shows `200` or `204` response code
+
+**Expected Status Codes:**
+| Code | Meaning |
+|------|---------|
+| `200` | Success (ping events) |
+| `204` | Success (push events accepted) |
+| `412` | Precondition Failed - expected on first-time test pushes before approval |
+
+> **Note**: A `412` error on test push delivery is normal for repositories not yet approved. The actual push after commits will trigger the approval workflow.
 
 **GitLab:**
 1. Go to **Settings** → **Webhooks**
@@ -180,10 +217,10 @@ Understanding the rendering pipeline:
    ~/.claude/skills/typo3-docs/scripts/validate_docs.sh
    ```
 
-2. **Missing Settings.cfg**
+2. **Missing Configuration File**
    ```bash
-   # Check file exists
-   ls -la Documentation/Settings.cfg
+   # Check for guides.xml (modern) or Settings.cfg (legacy)
+   ls -la Documentation/guides.xml Documentation/Settings.cfg
    ```
 
 3. **Invalid Cross-References**
@@ -219,7 +256,7 @@ Understanding the rendering pipeline:
 **Fix**:
 1. Trigger manual rebuild from Intercept dashboard
 2. Check build logs for errors
-3. Verify `Settings.cfg` has correct project configuration
+3. Verify `guides.xml` or `Settings.cfg` has correct project configuration
 
 ## Best Practices
 
@@ -276,8 +313,15 @@ For supporting multiple TYPO3 versions:
    git push origin docs-v12
    ```
 
-2. **Configure Settings.cfg** for each branch
+2. **Configure guides.xml** (or Settings.cfg) for each branch
+   ```xml
+   <!-- guides.xml (modern) -->
+   <project title="Extension Name"
+            version="2.1.0"
+            copyright="since 2024 by Your Name"/>
+   ```
    ```ini
+   # Settings.cfg (legacy)
    [general]
    project = Extension Name
    release = 2.1.0

references/typo3-extension-architecture.md

@@ -17,18 +17,24 @@ Official TYPO3 extension file structure for documentation extraction weighting a
 **ext_emconf.php** - Extension metadata
 - **Documentation Priority:** HIGH
 - **Extract:** Title, description, version, author, constraints
-- **Map to RST:** Introduction/Index.rst, Settings.cfg
+- **Map to RST:** Introduction/Index.rst, guides.xml (or Settings.cfg)
 - **Weight:** Essential metadata, version constraints
 
 **Index.rst** (in Documentation/)
 - **Documentation Priority:** CRITICAL
 - **Required:** Main documentation entry point
 - **Must Exist:** For TYPO3 Intercept deployment
 
-**Settings.cfg** (in Documentation/)
+**guides.xml** (in Documentation/) - Modern, Preferred
 - **Documentation Priority:** CRITICAL
-- **Required:** Documentation build configuration
+- **Required:** Documentation build configuration (PHP-based rendering)
 - **Must Exist:** For TYPO3 Intercept deployment
+- **Note:** Modern format, preferred over Settings.cfg
+
+**Settings.cfg** (in Documentation/) - Legacy
+- **Documentation Priority:** CRITICAL (if guides.xml not present)
+- **Required:** Documentation build configuration (Sphinx-based)
+- **Note:** Legacy format, migrate to guides.xml for modern rendering
 
 ### 🟡 Core Structure Files (Medium-High Priority)
 
@@ -205,7 +211,8 @@ Official TYPO3 extension file structure for documentation extraction weighting a
 
 **Required Files:**
 - `Index.rst` - Main entry point
-- `Settings.cfg` - Build configuration
+- `guides.xml` - Build configuration (modern, preferred)
+- `Settings.cfg` - Build configuration (legacy, if guides.xml not present)
 
 **Common Structure:**
 - `Introduction/` - Overview, features, screenshots
@@ -495,12 +502,12 @@ Missing Utility documentation:
 - ✅ `composer.json` with `"type": "typo3-cms-extension"`
 - ✅ PSR-4 autoload configuration
 - ✅ `Documentation/Index.rst`
-- ✅ `Documentation/Settings.cfg`
+- ✅ `Documentation/guides.xml` (modern) OR `Documentation/Settings.cfg` (legacy)
 
 **Classic-Mode Installation:**
 - ✅ `ext_emconf.php`
 - ✅ `Documentation/Index.rst`
-- ✅ `Documentation/Settings.cfg`
+- ✅ `Documentation/guides.xml` (modern) OR `Documentation/Settings.cfg` (legacy)
 
 ### Reserved Prefixes
 

scripts/validate_docs.sh

@@ -30,10 +30,16 @@ fi
 echo "Found $RST_FILES RST files"
 echo ""
 
-# Check for Settings.cfg
-if [ ! -f "$DOC_DIR/Settings.cfg" ]; then
-    echo "⚠️  Warning: Settings.cfg not found"
-    echo "   This file is required for TYPO3 Intercept builds"
+# Check for guides.xml (modern) or Settings.cfg (legacy)
+if [ -f "$DOC_DIR/guides.xml" ]; then
+    echo "✅ guides.xml found (modern PHP-based rendering)"
+elif [ -f "$DOC_DIR/Settings.cfg" ]; then
+    echo "✅ Settings.cfg found (legacy Sphinx-based rendering)"
+    echo "   ℹ️  Consider migrating to guides.xml for modern rendering"
+else
+    echo "⚠️  Warning: Neither guides.xml nor Settings.cfg found"
+    echo "   One of these files is required for TYPO3 Intercept builds"
+    echo "   Recommended: Create guides.xml (modern PHP-based rendering)"
 fi
 
 # Check for Index.rst

templates/AGENTS.md

@@ -31,7 +31,8 @@ This is the official TYPO3 extension documentation directory in reStructuredText
 ### Required Files
 
 - `Index.rst` - Main documentation entry point
-- `Settings.cfg` - Documentation metadata and configuration
+- `guides.xml` - Documentation metadata (modern, preferred)
+- `Settings.cfg` - Documentation metadata (legacy, migrate to guides.xml)
 
 ### Common Sections
 
@@ -236,11 +237,33 @@ scripts/validate_docs.sh
 Documentation is automatically built and deployed when:
 
 1. Changes pushed to `main` branch
-2. Webhook configured in Settings.cfg
+2. Webhook configured (docs-hook.typo3.org)
 3. TYPO3 Intercept receives notification
 4. Documentation rebuilt and published
 
-### Settings.cfg Configuration
+### guides.xml Configuration (Modern - Preferred)
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<guides xmlns="https://www.phpdoc.org/guides"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="https://www.phpdoc.org/guides https://www.phpdoc.org/guides/guides.xsd"
+        default-code-language="php">
+    <project title="Extension Name"
+             version="1.0.0"
+             copyright="since 2024 by Vendor Name"/>
+
+    <extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
+               edit-on-github="vendor/extension"
+               edit-on-github-branch="main"
+               edit-on-github-directory="Documentation"
+               project-home="https://github.com/vendor/extension"
+               project-repository="https://github.com/vendor/extension"
+               project-issues="https://github.com/vendor/extension/issues"/>
+</guides>
+```
+
+### Settings.cfg Configuration (Legacy)
 
 ```ini
 [general]
@@ -253,6 +276,8 @@ copyright = 2024
 project_repository = https://github.com/vendor/extension
 ```
 
+> **Note**: New extensions should use `guides.xml`. Migrate existing `Settings.cfg` to `guides.xml` for modern PHP-based rendering.
+
 ## Documentation Extraction and Analysis
 
 ### Using Extraction Tools
@@ -416,9 +441,10 @@ See `references/extraction-patterns.md` for complete extraction documentation.
 - Validate code block languages are supported
 
 **Webhook not triggering:**
-- Check Settings.cfg has correct repository URL
-- Verify webhook configured in repository settings
+- Check guides.xml or Settings.cfg has correct repository URL
+- Verify webhook configured in repository settings (https://docs-hook.typo3.org)
 - Check TYPO3 Intercept logs for errors
+- First-time webhooks require TYPO3 Documentation Team approval (1-3 days)
 
 ## Resources