Site Audit (Crawler + LLM Citation Readiness)

Site Audit rastrea tu dominio (BFS o vía sitemap.xml), genera para cada URL encontrada un informe de issues (SEO técnico + higiene de contenido) y, justo después, dispara automáticamente un lote de Grounding-Audit sobre hasta 100 páginas. Los findings se incorporan como issues adicionales con el prefijo grounding_* en la misma lista de issues — una única vista de panel para SEO técnico + disposición de citación LLM.

Qué puede hacer

• Modos de rastreo — bfs (descubrimiento de enlaces desde start_url, limitado por profundidad) O sitemap (carga todas las URLs de sitemap.xml, recursivamente incluyendo índice de sitemap, ignora crawl_depth). Límite estricto: 10.000 seeds, max_pages aplicado.
• Clasificación de issues — ordenados por prioridad de arreglo, filtrados por severity (critical|high|medium|low|notice), issue_type y status (open|fixed|dismissed). url precargada por issue.
• Puente de Auto-Grounding — automáticamente tras completar el rastreo: lote de Grounding-Audit sobre hasta 100 páginas → los findings se incorporan como issues grounding_* en el mismo rastreo. Sin créditos adicionales. Idempotente (la reejecución deduplica).
• Close-the-Loop — marca los issues con un clic (interfaz) o vía API como fixed/dismissed — individualmente O en masa por issue_type. Paso obligatorio tras cada corrección para que la métrica de comparación delta ("resuelto desde el último rastreo") funcione correctamente.
• AI-Brief (5 créditos por brief) — explicación narrativa de IA por issue con un solo clic.
• Marcas de tiempo del puente — bridge_dispatched_at (lote despachado) y bridge_completed_at (todos los issues grounding_* finalizados). Condición de polling determinista en lugar de esperar ciegamente 1-3 min.

Cuándo usarlo

• Inventario técnico de SEO a nivel de todo el sitio.
• Comprobar la disposición de citación LLM de todo el dominio sin 340 llamadas de Single-Audit.
• Antes de un relanzamiento: qué hay que quitar / arreglar todavía.
• Chequeo mensual de salud para stakeholders.

Flujo de trabajo en la interfaz

1. Inicio — formulario en /site-audit (start_url, max_pages, crawl_depth, crawl_mode, opcional tracking_project_id).
2. Polling — la página de detalle /site-audit/{crawl} muestra un contador en vivo (pages_crawled, total_issues). Auto-refresh.
3. Close-the-Loop — cada issue tiene 2 botones: ✓ Resuelto y ⊘ Descartar. Encima de la tabla hay una barra de herramientas de acción masiva con menú desplegable "Elegir tipo de issue" + Marcar todos como resueltos / Descartar todos para correcciones masivas tras cambios de layout/plantilla.
4. Re-Crawl — una vez resueltos los critical+high, un nuevo rastreo → el bloque de tendencia muestra "resuelto desde el último rastreo" / "nuevo desde el último rastreo".

Flujo de trabajo vía API (llamador de skill)

Secuencia obligatoria tras la corrección:

# 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"

Patrón de polling (determinista desde 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-patrones

• Aplicar una corrección sin PATCH /issues/{id} con status=fixed → el issue permanece "open" en el panel, la métrica de comparación delta de la siguiente iteración de rastreo queda invalidada.
• Consultar los issues justo después de status='completed' sin comprobar bridge_completed_at → faltan los issues grounding_* (el puente todavía está en ejecución).
• Marcado masivo sin filter.issue_type → marca cientos de issues no relacionados. El servidor devuelve meta.applied_filter; el llamador DEBE verificarlo antes de realizar el siguiente paso.
• AI-Brief en bucle para 100+ issues — 5 créditos por brief. Solo para elementos críticos seleccionados.

Módulos relacionados

• Content Audit (Site-Crawl) — escáner de calidad de contenido (qué dice la página, no qué tiene la página). Complementario.
• Grounding Audit — disposición de citación LLM de una sola URL. Llamada directa sin la sobrecarga del rastreo.
• [[modules/page-audit]] — auditoría de conversión por URL (Lighthouse + Vision + ajuste de persona). Más granular por URL.