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). La dirección de inicio viene rellenada con el dominio del proyecto activo. Basta con un dominio sin esquema como ejemplo.es: el https:// se añade en cuanto sales del campo.
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".

De la tarjeta «Errores (4xx/5xx)» a la lista de problemas

La tarjeta Crawl-Efficiency de la página de detalle cuenta cuántas páginas rastreadas respondieron con un estado de error. El valor Errores (4xx/5xx) es un botón:

1. Clic en el valor — se abre la pestaña Problemas, filtrada a los errores de estado; encima aparece «Lista de problemas filtrada a las páginas con error que cuenta la tarjeta de eficiencia de rastreo.» La severidad y «Solo abiertos» se restablecen, porque la tarjeta cuenta páginas sin importar si el problema ya está resuelto. Los grupos de error aparecen desplegados arriba del todo.
2. Los problemas se llaman según lo que hace la página: La página responde con un estado de error (4xx) y La página responde con un error del servidor (5xx) — es la propia página la que responde así; no se trata de un enlace en otra página. Al mismo contador pertenecen «Página inaccesible (timeout)» y «Rate limit (429)».
3. Dos filtros separados. Solo abiertos en la pestaña Problemas oculta los problemas resueltos y descartados; Código de estado en la pestaña Páginas filtra las páginas rastreadas por su respuesta HTTP (200, redirección, 404, 5xx). Ambos aparecen por separado en la dirección — ?issue_status=open y ?http_status=404 — y no se afectan entre sí: un filtro 404 en la pestaña Páginas ya no anula «Solo abiertos» en la lista de problemas. Una dirección así filtrada se puede guardar como marcador o compartir como enlace.

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.
• Page-Deep-Audit — auditoría de conversión por URL (Lighthouse + Vision + ajuste de persona). Más granular por URL.