Saltar a contenido

Operaciones de Guide Library

Este documento es la guia de mantenimiento de la biblioteca y de la web-app Guide Library.

Debe leerse junto con:

  • AGENTS.md
  • GUIA_DESPLIEGUE_GUIDE_LIBRARY.md
  • README.md

1. Idea principal

El repositorio tiene dos capas:

  1. Biblioteca de trabajo en Markdown
  2. Es la fuente de verdad.
  3. Se edita desde Obsidian, Codex o GitHub.

  4. Incluye guiones, manuales, fichas, indices, fuentes brutas y control factual.

  5. Web-app estatica

  6. Se genera automaticamente desde los Markdown.
  7. Se publica en Cloudflare Pages.
  8. Sirve para leer comodo desde movil, tablet o PC.

Nunca editar a mano .mkdocs/ ni site/. Son carpetas generadas.

2. Estado de produccion

  • Repo GitHub: curiositasmundus/guides-library
  • Rama de produccion: main
  • Proyecto Cloudflare Pages: guides-library
  • Dominio previsto: library.curiositasmundus.com
  • URL temporal de Cloudflare: https://guides-library.pages.dev
  • Build command:
pip install -r requirements.txt && python scripts/build_guide_library.py && mkdocs build
  • Build output directory:
site

3. Archivos importantes

  • AGENTS.md: reglas de trabajo para IA y humanos.
  • README.md: entrada rapida y estado de importacion.
  • OPERACIONES_GUIDE_LIBRARY.md: esta guia operativa.
  • GUIA_DESPLIEGUE_GUIDE_LIBRARY.md: despliegue, dominio y acceso.
  • mkdocs.yml: configuracion de la web-app.
  • requirements.txt: dependencias Python para construir la web.
  • scripts/build_guide_library.py: prepara los Markdown para MkDocs.
  • webapp/: icono, PWA, estilos y overrides.
  • .gitignore: excluye carpetas generadas.

4. Flujo normal para anadir documentos

  1. Conservar la fuente bruta.
  2. Guardar el documento completo en la carpeta Fuentes/ adecuada.
  3. No reescribir la fuente para "mejorarla".

  4. Anotar dudas o falsedades dentro de la fuente cuando proceda.

  5. Clasificar el conocimiento.

  6. Global: Conocimiento_General/
  7. Pais: Belgica/Conocimiento_Belgica/ u otro pais futuro.
  8. Ciudad: Pais/Ciudad/Manual_Ciudad.md

  9. Tour: guion, fichas e indice del tour.

  10. Integrar sin sustituir.

  11. Leer antes los archivos existentes.
  12. Anadir o fusionar secciones concretas.

  13. No borrar contenido util anterior.

  14. Actualizar navegacion.

  15. 00_Inicio.md
  16. Pais/00_Pais.md
  17. Pais/Ciudad/00_Ciudad.md

  18. Indices rapidos y fichas cuando haya tour usable.

  19. Actualizar control.

  20. Control_Factual/Cola_importacion_tours_drive.md
  21. Control_Factual/Informaciones_para_confirmar_por_humanos.md
  22. Control_Factual/Inventario_documentos_origen.md

  23. README.md, si cambia el estado de importacion.

  24. Probar la web.

python scripts/build_guide_library.py
mkdocs build

En esta maquina puede ser necesario:

py -3.14 scripts/build_guide_library.py
py -3.14 -m mkdocs build

5. Flujo normal para cambios pequenos

Ejemplos: corregir una errata, anadir un enlace, mejorar un indice, cambiar estilos.

  1. Hacer una rama codex/... si el cambio no es trivial.
  2. Editar solo los archivos necesarios.
  3. Ejecutar build local.
  4. Commit claro.
  5. Push.
  6. Crear PR a main.
  7. Fusionar cuando el build sea correcto.

Cloudflare despliega desde main, asi que cualquier cambio fusionado a main debe ser publicable.

6. Politica de ramas

  • main: produccion. Debe construir correctamente.
  • codex/...: trabajo en curso o integraciones automaticas.
  • backup/...: puntos de vuelta antes de cambios grandes.

Antes de grandes importaciones o reestructuraciones:

git branch backup/nombre-fecha HEAD

No usar git reset --hard ni revertir cambios ajenos sin permiso explicito.

7. Que hace build_guide_library.py

El script:

  • Copia los Markdown a .mkdocs/docs.
  • Convierte enlaces tipo Obsidian Texto a enlaces Markdown.
  • Usa 00_Inicio.md como portada web (index.md).
  • Copia archivos de apoyo necesarios para que el README web no tenga enlaces rotos.
  • Copia assets de webapp/assets.

Si en el futuro se crea un nuevo pais o una carpeta raiz nueva con contenido real, revisar SOURCE_DIRS dentro de scripts/build_guide_library.py.

8. Reglas para enlaces

Preferir enlaces Obsidian dentro del contenido de trabajo:

[Ayuntamiento](Belgica/Lovaina/Guion_Lovaina_2h.md#03-ayuntamiento)

El script los convierte para la web.

Tambien funcionan enlaces Markdown relativos:

[Ayuntamiento](Guion_Lovaina_2h.md#03-ayuntamiento)

Si se cambia un encabezado de un guion, revisar sus indices rapidos. Muchos avisos de build vienen de anclas antiguas.

9. Warnings habituales del build

Ancla no encontrada

Significa que un indice enlaza a una seccion cuyo titulo ha cambiado.

Accion:

  • Buscar el enlace en el indice rapido.
  • Buscar el encabezado real en el guion/manual.
  • Actualizar el enlace o el titulo.

No bloquea siempre el despliegue, pero afecta a la navegacion durante tours.

Archivo no encontrado

Puede significar:

  • Falta crear el archivo enlazado.
  • El archivo existe, pero no esta incluido en SOURCE_DIRS.
  • El enlace esta mal escrito.

Esto si debe revisarse antes de dar por terminada una ciudad o tour.

requirements.txt no encontrado en Cloudflare

Cloudflare esta desplegando una rama que no tiene la web-app.

Accion:

  • Confirmar que Cloudflare usa main.
  • Confirmar que main contiene requirements.txt, mkdocs.yml y scripts/build_guide_library.py.

10. Cloudflare y dominio

Cloudflare Pages debe desplegar desde main.

No usar la carpeta de cPanel como destino principal de esta web-app. La carpeta de cPanel puede existir, pero el dominio library.curiositasmundus.com debe apuntar al proyecto de Cloudflare Pages.

Si el dominio falla:

  1. Revisar Custom domains en Cloudflare Pages.
  2. Revisar DNS de library.curiositasmundus.com.
  3. Debe apuntar a guides-library.pages.dev mediante CNAME, salvo que Cloudflare lo gestione automaticamente.

11. Acceso privado y futuro pago

Estado recomendado ahora:

  • Cloudflare Access.
  • Login por email con one-time PIN.
  • Permitir emails del dominio curiositasmundus.com o una lista concreta.

Si en el futuro se convierte en app de pago:

  • No rehacer la biblioteca desde cero.
  • Mantener Markdown como fuente de contenido mientras sea posible.
  • Cambiar la capa de acceso: lista de emails de clientes, grupos, Stripe/Auth externo o backend especifico.
  • Solo introducir base de datos o backend cuando haya necesidad real: usuarios, pagos, edicion web, permisos por plan o analitica avanzada.

12. Checklist para futuras IAs

Antes de tocar el repo:

  • Leer AGENTS.md.
  • Leer este documento si la tarea afecta a la web, despliegue o flujo de trabajo.
  • Comprobar rama y estado con git status.
  • No editar .mkdocs/ ni site/.
  • No mezclar cambios de contenido masivos con cambios tecnicos de despliegue salvo que el usuario lo pida.

Antes de cerrar:

  • Ejecutar scripts/build_guide_library.py.
  • Ejecutar mkdocs build.
  • Explicar warnings relevantes.
  • Actualizar README/control factual si se ha importado contenido.
  • Confirmar que los cambios estan en la rama correcta.
  • Si se despliega en Cloudflare, confirmar que main contiene los archivos necesarios.

13. Checklist para humanos

Despues de meter nuevos documentos:

  • Confirmar que la fuente bruta quedo guardada.
  • Confirmar que el contenido esta en el nivel correcto.
  • Confirmar que los indices enlazan el nuevo material.
  • Confirmar que las dudas factuales estan registradas.
  • Esperar al deploy automatico de Cloudflare o lanzar uno manual.
  • Abrir library.curiositasmundus.com y probar busqueda/navegacion.

14. No hacer

  • No copiar grandes bloques a varios niveles si basta con enlazar.
  • No borrar fuentes brutas.
  • No presentar leyendas como hechos.
  • No editar carpetas generadas.
  • No cambiar Cloudflare a una rama temporal salvo para una prueba puntual.
  • No dejar Cloudflare permanentemente apuntando a una rama que no sea main.
  • No meter imagenes pesadas sin decidir antes estrategia de almacenamiento.