Site Audit (Crawler + LLM Citation Readiness)

Site Audit crawlt deine Domain (BFS oder via sitemap.xml), erzeugt für jede gefundene URL einen Issue-Report (technische SEO + Content-Hygiene) und feuert direkt im Anschluss automatisch einen Grounding-Audit-Batch über bis zu 100 Pages. Die Findings werden als zusätzliche Issues mit Prefix grounding_* in dieselbe Issues-Liste eingespeist — ein einziger Dashboard-View für technische SEO + LLM-Citation-Readiness.

Was es kann

• Crawl-Modi — bfs (Link-Discovery ab start_url, depth-limited) ODER sitemap (lädt alle URLs aus sitemap.xml, rekursiv inkl. Sitemap-Index, ignoriert crawl_depth). Hartes Cap: 10 000 Seeds, max_pages enforced.
• Issue-Klassifikation — fix-priority-sortiert, gefiltert nach severity (critical|high|medium|low|notice), issue_type und status (open|fixed|dismissed). Eager-loaded url pro Issue.
• Auto-Grounding-Bridge — automatisch nach Crawl-Completion: Grounding-Audit-Batch über bis zu 100 Pages → Findings landen als grounding_*-Issues im selben Crawl. Keine Zusatz-Credits. Idempotent (Re-Run dedupt).
• Close-the-Loop — Issues per Klick (UI) oder per API als fixed/dismissed markieren — einzeln ODER bulk pro issue_type. Pflicht-Schritt nach jedem Fix damit die Delta-Vergleichsmetrik („seit letztem Crawl behoben") sinnvoll funktioniert.
• AI-Brief (5 Credits pro Brief) — narrative LLM-Erklärung pro Issue auf Knopfdruck.
• Bridge-Timestamps — bridge_dispatched_at (Batch dispatched) und bridge_completed_at (alle grounding_*-Issues final). Deterministische Polling-Condition statt blind 1-3 min zu warten.

Wann nutzen

• Site-weite technische SEO-Bestandsaufnahme.
• LLM-Citation-Readiness der ganzen Domain prüfen ohne 340× Single-Audit-Calls.
• Vor einem Relaunch: was muss noch raus / gefixt werden.
• Monatlicher Health-Check für Stakeholder.

Workflow im UI

1. Start — Form unter /site-audit (start_url, max_pages, crawl_depth, crawl_mode, optional tracking_project_id). Die Startadresse ist mit der Domain des aktiven Projekts vorbelegt. Eine nackte Domain wie beispiel.de genügt: das https:// kommt dazu, sobald du das Feld verlässt.
2. Polling — Detail-Page /site-audit/{crawl} zeigt Live-Counter (pages_crawled, total_issues). Auto-Refresh.
3. Close-the-Loop — Pro Issue gibt es 2 Buttons: ✓ Behoben und ⊘ Verwerfen. Oberhalb der Tabelle eine Bulk-Action-Toolbar mit Dropdown „Issue-Typ wählen" + Alle als behoben markieren / Alle verwerfen für mass-fixes nach Layout-/Template-Changes.
4. Re-Crawl — Nachdem critical+high gelöst sind, neuer Crawl → Trend-Block zeigt „seit letztem Crawl behoben" / „seit letztem Crawl neu".

Von der Kachel »Fehler (4xx/5xx)« zur Problemliste

Die Kachel Crawl-Efficiency auf der Detailseite zählt, wie viele gecrawlte Seiten mit einem Fehlerstatus geantwortet haben. Der Wert Fehler (4xx/5xx) ist eine Schaltfläche:

1. Klick auf den Wert — der Reiter Probleme öffnet sich, gefiltert auf die Statusfehler; darüber steht „Problemliste gefiltert auf die Fehlerseiten der Crawl-Efficiency-Kachel." Schweregrad und „Nur offene" sind dabei zurückgesetzt, denn die Kachel zählt Seiten unabhängig davon, ob die Meldung schon behoben ist. Die Fehlergruppen stehen aufgeklappt ganz oben.
2. Die Meldungen heißen nach dem, was die Seite tut: Seite antwortet mit Fehlerstatus (4xx) und Seite antwortet mit Serverfehler (5xx) — die Seite selbst antwortet so; es geht nicht um einen Link auf einer anderen Seite. Zum selben Zähler gehören „Seite nicht erreichbar (Timeout)" und „Rate-Limit (429)".
3. Zwei getrennte Filter. Nur offene im Reiter Probleme blendet behobene und verworfene Meldungen aus; Status-Code im Reiter Seiten filtert die gecrawlten Seiten nach ihrer HTTP-Antwort (200, Weiterleitung, 404, 5xx). Beide stehen einzeln in der Adresse — ?issue_status=open bzw. ?http_status=404 — und beeinflussen sich nicht: ein 404-Filter im Reiter Seiten hebt „Nur offene" in der Problemliste nicht auf. Eine so gefilterte Adresse lässt sich als Lesezeichen oder Link weitergeben.

Workflow per API (Skill-Caller)

Pflicht-Sequenz nach Fix:

# 1. Issues holen
ISSUES=$(curl -sH "Authorization: Bearer $TOKEN" \
    "$BASE/v1/site-audit/$CRAWL/issues?status=open&per_page=100" | jq '.data')

# 2. Pro Issue: Fix anwenden (Layout-Edit / Content-Update / Migration)

# 3. PFLICHT: Issue als fixed markieren — sonst weiß die Plattform nicht
#    dass die Arbeit done ist und die Delta-Metrik wird wertlos:
curl -X PATCH \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"status":"fixed"}' \
    "$BASE/v1/site-audit/issues/$ISSUE_ID"

# 4. Bei Layout-/Template-Fixes: Bulk-Mark statt 50× Single-PATCH:
curl -X PATCH \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"filter":{"issue_type":"missing_alt_text","status":"open"},"new_status":"fixed"}' \
    "$BASE/v1/site-audit/$CRAWL/issues/bulk"

Polling-Pattern (deterministisch ab 2026-05-14):

while true; do
    R=$(curl -sH "Authorization: Bearer $TOKEN" "$BASE/v1/site-audit/$CRAWL" | jq '.data')
    STATUS=$(echo "$R" | jq -r .status)
    BRIDGE=$(echo "$R" | jq -r .bridge_completed_at)
    [ "$STATUS" = "completed" ] && [ "$BRIDGE" != "null" ] && break
    sleep 30
done
# → JETZT sind alle Issues final, auch die grounding_*

Anti-Patterns

• Fix anwenden ohne PATCH /issues/{id} mit status=fixed → Issue bleibt „open" im Dashboard, Delta-Vergleichsmetrik der nächsten Crawl-Iteration wird wertlos.
• Issues direkt nach status='completed' abrufen ohne bridge_completed_at zu prüfen → grounding_*-Issues fehlen (Bridge läuft noch).
• Bulk-Mark ohne filter.issue_type → markiert hunderte unrelated Issues. Server gibt meta.applied_filter zurück; Caller MUSS das verifizieren bevor er den nächsten Schritt macht.
• AI-Brief in Schleife für 100+ Issues — 5 Credits pro Brief. Nur für ausgewählte critical-Items.

Verwandte Module

• Content Audit (Site-Crawl) — content-quality scanner (was Page sagen, nicht Page hat). Komplementär.
• Grounding Audit — Single-URL LLM-Citation-Readiness. Direct-Call ohne Crawl-Overhead.
• Page-Deep-Audit — Conversion Audit pro URL (Lighthouse + Vision + Persona-Fit). Granularer pro URL.