docs: add maintenance guide for list maintainers

Author: GeiserX

MAINTENANCE.md

@@ -0,0 +1,97 @@
+# Guía de mantenimiento
+
+> **Este fichero lo mantiene exclusivamente @GeiserX.** No se aceptan PRs que lo modifiquen.
+
+Directrices para los mantenedores de esta lista. Esta guía es común a todas las awesome lists del ecosistema (awesome-spain + listas regionales). Seguirla garantiza que todos los repositorios mantengan la misma calidad, formato y criterios de inclusión, de modo que el conjunto funcione como una colección coherente.
+
+## Filosofía de inclusión
+
+El criterio fundamental es: **se acepta software que da soporte específico a Catalunya, no software hecho por alguien de Catalunya.**
+
+Un repositorio se incluye porque interactúa con instituciones, servicios, infraestructura, normativas o datos propios de Catalunya. No basta con que el autor resida o trabaje aquí. Un framework genérico creado por un developer de Catalunya no pertenece a esta lista. Un cliente para la API de datos abiertos del gobierno de Catalunya o una integración con servicios públicos de Catalunya sí.
+
+- **Sí:** Clientes de APIs de instituciones de Catalunya, integraciones con servicios públicos regionales, scrapers de transporte o datos abiertos de Catalunya.
+- **No:** Librerías genéricas creadas por equipos de Catalunya, software genérico cuyo autor simplemente reside en la comunidad.
+
+Ver `AGENTS.md` (si existe) para criterios detallados adicionales.
+
+## Revisar PRs
+
+1. Comprobar que el proyecto **da soporte específico a Catalunya** (no simplemente que el autor es de Catalunya).
+2. Verificar que la PR incluye la **URL del servicio o institución de Catalunya** que el proyecto soporta.
+3. Comprobar formato: entrada simple, orden alfabético, descripción en español que empieza en mayúscula y termina con punto.
+4. **CI debe estar verde** antes de mergear: awesome-lint-extra (formato y orden) + lychee (enlaces).
+5. Las insignias se generan automáticamente. Los contribuidores solo envían:
+   ```markdown
+   - [Nombre](https://github.com/owner/repo) - Descripción breve que empieza en mayúscula y termina con punto.
+   ```
+6. Tras mergear, ejecutar el pipeline de insignias (si existe) y hacer push:
+   ```bash
+   bash scripts/gather-metadata.sh
+   python3 scripts/transform-readme.py
+   ```
+
+## Añadir entradas como mantenedor
+
+1. Añadir la entrada simple en la sección correcta, en orden alfabético.
+2. Ejecutar el pipeline de insignias (si el repo dispone de los scripts):
+   ```bash
+   bash scripts/gather-metadata.sh
+   python3 scripts/transform-readme.py
+   ```
+3. Commit y push. Verificar que CI queda verde.
+4. Si el propietario del proyecto no ha sido notificado, abrir un issue de cortesía en su repo:
+   - Título: `Incluido en awesome-catalunya`
+   - Cuerpo: mensaje breve en español (tuteo) explicando la inclusión y ofreciendo retirarlo si lo prefiere.
+   - **Un solo issue por propietario** — nunca abrir múltiples issues en repos del mismo usuario/organización.
+
+## Eliminar entradas
+
+Las entradas no se borran sin más. Se mueven a `DELETED.md` en la sección correspondiente:
+
+| Razón | Sección en DELETED.md |
+|-------|-----------------------|
+| Repo archivado/solo lectura | Archivados |
+| Repo eliminado o renombrado | Repos inexistentes o renombrados |
+| Autor confirmó abandono | Abandonados |
+| No cumple criterios de inclusión | Eliminados por no ser específicos de Catalunya |
+| Sustituido por otro proyecto | Reemplazados (enlazar sucesor) |
+
+Esto evita re-adiciones y preserva el historial.
+
+## Mantenimiento periódico
+
+- **Mensual:** Revisar la salida de lychee en GitHub Actions. Corregir o eliminar enlaces rotos.
+- **Trimestral:** Refrescar insignias (`gather-metadata.sh` + `transform-readme.py`). Comprobar si hay repos recién archivados:
+  ```bash
+  grep -oE 'https://github\.com/[^/)]+/[^/)]+' README.md | sort -u | while read url; do
+    repo="${url#https://github.com/}"
+    archived=$(gh api "repos/$repo" --jq '.archived' 2>/dev/null)
+    [ "$archived" = "true" ] && echo "ARCHIVADO: $repo"
+  done
+  ```
+
+## Herramientas
+
+- **awesome-lint-extra** — Linter propio. Valida formato, orden alfabético, insignias y descripciones. Se ejecuta como GitHub Action (`GeiserX/awesome-lint-extra@main`) y como script standalone (`python3 lint.py`). Configuración en `.awesomerc.json`.
+- **transform-readme.py** — Genera insignias de shields.io y etiquetas de institución/servicio a partir de `scripts/metadata.json`.
+- **gather-metadata.sh** — Obtiene metadatos (estrellas, lenguaje, licencia, rama) de la API de GitHub para cada repo listado.
+- **lychee** — Comprobador de enlaces. Se ejecuta en CI como `lycheeverse/lychee-action@v2`. No bloquea merges (`continue-on-error: true`), pero sus resultados deben revisarse periódicamente.
+
+## Reglas de formato
+
+- La descripción **no debe empezar con el nombre** del proyecto.
+- Una línea por entrada, sin saltos de línea.
+- Descripciones en **español**.
+- **Orden alfabético** dentro de cada sección/subsección (sin distinguir mayúsculas/minúsculas).
+- Evitar el anglicismo «curar/curado» — usar «selección» o «recopilación» (según FundéuRAE).
+- Nuevas categorías: preferiblemente con al menos 3 proyectos.
+
+## Contenido prohibido
+
+No se aceptan proyectos relacionados con: pornografía, NSFW, apuestas, loterías, religión, política partidista.
+
+## Difusión
+
+- Abrir issues de notificación en repos de proyectos incluidos (uno por propietario, en español).
+- Publicar en comunidades de desarrollo relevantes tras alcanzar masa crítica.