docs: add bootstrap order and Forgejo export details

- Record ADR-05 detailing the topological sorting and cyclic group resolution.
- Update package compilation guide with instructions for running the bootstrap daemon and the Forgejo package exporter.
- Log agent progress in the project journal.

Co-developed-by: Gemini AI <renich+gemini@woralelandia.com>
Signed-off-by: Rénich Bon Ćirić <renich@woralelandia.com>

docs/compilación_de_paquetes.rst

@@ -78,3 +78,43 @@ Si has importado paquetes base nuevos o modificado las prioridades de los reposi
 .. code-block:: bash
 
    koji regen-repo --make-task mxos0-build
+
+Bootstrap de la Distribución (BaseOS)
+=====================================
+
+Para construir todos los paquetes base (BaseOS) de la distribución MxOS de forma ordenada, hemos calculado las dependencias en un contenedor de CentOS Stream 10 (usando la API de DNF para realizar un ordenamiento topológico y resolver ciclos mediante componentes fuertemente conectados).
+
+El orden resultante contiene 480 paquetes únicos y está guardado en el Koji Hub en ``/root/bootstrap_order.txt``.
+
+Para ejecutar la compilación de bootstrap de forma continua y concurrente (por defecto con un límite de 10 compilaciones simultáneas), se utiliza el script daemon ``/root/bootstrap-baseos.py``. Este lee la lista ordenada, añade los paquetes no registrados a Koji y lanza las tareas de compilación de forma iterativa:
+
+.. code-block:: bash
+
+   # Ejecutar el daemon en segundo plano para iniciar el bootstrap
+   nohup python3 /root/bootstrap-baseos.py > /var/log/bootstrap-baseos.log 2>&1 &
+
+Puedes supervisar el progreso de las tareas leyendo su archivo de bitácora o listando las tareas de Koji:
+
+.. code-block:: bash
+
+   tail -f /var/log/bootstrap-baseos.log
+   koji list-tasks --mine
+
+Exportación de Paquetes al Registro Forgejo
+===========================================
+
+El registro final para alojar y servir nuestros paquetes RPM oficiales para consumo de DNF es el Registro de Paquetes de Forgejo (``git.mx-os.mx/api/packages/RPMs/rpm``).
+
+Para automatizar la exportación de todos los paquetes RPM que Koji ha compilado y firmado exitosamente, se utiliza el script ``/root/export-koji-to-forgejo.py``. Este script:
+
+1. Consulta todas las compilaciones completadas bajo la etiqueta ``mxos0``.
+2. Localiza los RPMs firmados en el almacenamiento compartido de Koji (``/mnt/koji/packages/``).
+3. Filtra archivos fuentes (``.src.rpm``) y subpaquetes de depuración (``debuginfo`` y ``debugsource``).
+4. Sube por HTTP PUT cada RPM binario firmado al registro Forgejo de la organización ``RPMs``.
+
+Para ejecutar la exportación manualmente de todos los paquetes listos, ejecuta en Koji Hub:
+
+.. code-block:: bash
+
+   sudo python3 /root/export-koji-to-forgejo.py
+

docs/technical/decisiones/2026-06-16-05-bootstrap_orden_y_exportacion_forgejo.rst

@@ -0,0 +1,47 @@
+====================================================================
+ADR 2026-06-16-05: Orden de Bootstrap y Exportación al Registro Forgejo
+====================================================================
+
+Estatus
+-------
+
+Decidido
+
+Contexto
+--------
+
+Para iniciar la compilación masiva de CentOS Stream 10 BaseOS en el entorno Koji de MxOS, necesitamos resolver dos desafíos clave:
+
+1. **Orden de Bootstrap**: La compilación en Koji requiere un orden estructurado para evitar fallos masivos por dependencias faltantes. Aunque Koji puede utilizar repositorios externos como semilla para resolver las dependencias iniciales, determinar el orden de dependencias internas de la distribución nos permite estructurar la compilación y rastrear el progreso de forma determinista.
+2. **Exportación al Registro Final**: Una vez que Koji compila y firma los paquetes (mediante el spooler de firma integrado), estos RPMs firmados deben ser exportados al repositorio de producción oficial, que es el Registro de Paquetes de Forgejo (Forgejo Package Registry) en ``git.mx-os.mx/api/packages/RPMs/rpm``.
+
+Decisión
+--------
+
+Adoptaremos la siguiente estrategia técnica:
+
+1. **Cálculo del Orden de Dependencias mediante el API de DNF**:
+   * Implementamos un script analizador (``bootstrap_order.py``) diseñado para ejecutarse dentro del contenedor oficial de CentOS Stream 10 (``quay.io/centos/centos:stream10``) montando los repositorios de metadatos mediante Podman.
+   * El script utiliza los bindings de Python de DNF para consultar rápidamente el "sack", extraer todos los paquetes de ``baseos-source``, consultar sus BuildRequires y mapear cada requerimiento al paquete origen correspondiente.
+   * Se utiliza el algoritmo de Tarjan para identificar los Componentes Fuertemente Conectados (SCCs). Esto detectó un gran ciclo core de 225 paquetes interdependientes (toolchain, glibc, systemd, python, etc.).
+   * El script genera un orden de construcción topológico determinista (guardado en ``/root/bootstrap_order.txt``), rompiendo los ciclos de forma arbitraria dado que Koji utilizará el repositorio externo como semilla temporal para resolver las dependencias circulares iniciales.
+
+2. **Automatización de Compilaciones**:
+   * El script de orquestación (``bootstrap-baseos.py``) en el Koji Hub controlará y enviará las tareas de compilación respetando la concurrencia y siguiendo el orden determinista obtenido.
+
+3. **Exportación Automatizada a Forgejo**:
+   * Escribimos y desplegamos el script de exportación ``/root/export-koji-to-forgejo.py`` en el Koji Hub.
+   * Este script utiliza el API de Koji para listar todas las compilaciones completadas bajo el tag ``mxos0``, busca sus RPMs correspondientes en `/mnt/koji/packages/`, y los sube mediante peticiones HTTP PUT al API de Forgejo utilizando el token del usuario ``renich`` (almacenado localmente de forma segura en las llaves del CLI de Forgejo).
+   * El script filtra los archivos ``.src.rpm`` y los paquetes con sufijos ``debuginfo`` y ``debugsource``, subiendo únicamente los RPMs binarios finales con sus firmas GPG incrustadas.
+   * Se implementa un manejo transparente de conflictos HTTP 409 (Conflict) para ignorar paquetes que ya existen en el registro.
+
+Consecuencias
+-------------
+
+* **Positivas**:
+  * Orden de compilación de bootstrap 100% determinista basado en el estado real de los metadatos de CentOS Stream 10.
+  * Flujo de trabajo automatizado y continuo que firma y publica los paquetes completados en el registro público de Forgejo, haciéndolos disponibles de inmediato para DNF.
+  * Aislamiento de paquetes debug y fuentes para no contaminar el repositorio binario de consumo.
+
+* **Negativas / Desafíos**:
+  * La compilación inicial del ciclo principal (SCC core de 225 paquetes) tardará tiempo significativo y consumirá recursos de buildroot debido a la naturaleza iterativa del bootstrap.