release: dev → main — publicar sitio de docs (sin bump de versión)

.github/workflows/docs.yml

@@ -0,0 +1,59 @@
+name: docs
+
+# Construye el sitio MkDocs Material y lo publica en GitHub Pages.
+# Publica desde `main` (docs estables, alineadas con el último release). Se puede
+# disparar a mano con "Run workflow" (workflow_dispatch) para previsualizar antes
+# de un release. Requiere: Settings → Pages → Source = "GitHub Actions" (una vez).
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "*.md"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+# Permisos mínimos para el deploy a Pages vía OIDC.
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Un solo deploy a la vez; no cancela uno en curso.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          python-version: "3.11"
+      - name: Sync (grupo docs)
+        run: uv sync --group docs
+      - name: Build (mkdocs)
+        run: uv run mkdocs build --clean
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    name: deploy
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -61,6 +61,13 @@ valoraciones_*
 examples/**/*.duckdb
 
 
+# Docs (MkDocs) — output de build local; el sitio se publica vía CI (docs.yml),
+# nunca se commitea.
+site/
+
+# Borradores y exploración local (no va al repo)
+scratch/
+
 # Logs
 logs
 *.log

docs/Notas/22-frontera-y-alcance-de-bib2graph.md

@@ -0,0 +1,60 @@
+# 22 — Frontera y alcance de bib2graph (nota de separación)
+
+> Qué es bib2graph y dónde se detiene **a propósito**. Esta nota existe para ser transparentes con
+> quien la usa: dejar la frontera escrita, sin letra chica. Es la versión que habla al usuario; la
+> decisión, una vez asentada, se gradúa a un ADR que habla a quien decide el código. Fecha: 2026-06-28.
+
+---
+
+> **bib2graph convierte una búsqueda en un corpus, redes de citación y un orden de lectura priorizado —deterministas, reproducibles y con procedencia—. Te lleva hasta la lectura y se detiene ahí: no interpreta, no gestiona tu investigación ni usa IA; el juicio queda tuyo.**
+
+---
+
+## Qué es
+
+bib2graph hace **una** cosa, y la hace bien: toma una búsqueda —una ecuación sobre OpenAlex o un archivo `.bib`— y la transforma en material estructurado para empezar a leer con criterio. Concretamente, te entrega:
+
+- **Un corpus** que crece siguiendo las citaciones (forward y backward chaining) y que **curás vos** —aceptar, rechazar, filtrar—.
+- **Redes de citación** (acoplamiento, co-citación, co-autoría, instituciones, co-keywords), listas para Gephi, Cytoscape o networkx.
+- **Un orden de lectura priorizado**: qué leer primero, según cuánto se acopla, co-cita o es central cada pieza dentro de tu corpus.
+- **Procedencia** de todo: la cadena de búsqueda exacta, la fecha, los topes, la versión — para reconstruir y reportar cómo llegaste a lo que llegaste.
+
+Tres propiedades lo definen, y ninguna es decorativa:
+
+- **Determinista** — mismo input, mismo output. No hay azar ni modelo opaco en el medio.
+- **Reproducible** — cualquiera puede correr lo mismo y obtener lo mismo. Eso lo vuelve defendible ante un revisor.
+- **Con procedencia** — cómo lo hallaste viaja pegado al resultado. No hay magia que no puedas auditar.
+
+## Qué no es (y por qué, a propósito)
+
+Tan importante como lo que hace es lo que **elige no hacer**:
+
+- **No interpreta.** No te dice qué significan los clusters, no decide qué deberías citar, no escribe tu estado del arte. Te muestra la estructura; el sentido lo construís vos leyendo.
+- **No gestiona tu investigación.** No tiene usuarios, ni proyectos, ni colecciones, ni anotaciones. No es un Zotero ni un Mendeley. Administra **un** corpus reproducible, no tu biblioteca a través de toda tu carrera.
+- **No usa IA.** El descubrimiento es **estructura bibliométrica determinista** —acoplamiento, co-citación, centralidad—, no un modelo de lenguaje. Por eso es reproducible y reportable, y por eso no puede "alucinar" un paper que no existe.
+
+Esto no son carencias: son **la frontera**. Una herramienta que se limita a propósito es una herramienta en la que podés confiar y que podés reportar con honestidad. El día que bib2graph empezara a decidir por vos —qué es relevante, qué significa, qué citar— dejaría de ser auditable y se volvería justo lo que la buena investigación debe evitar: una caja que disfraza una elección de autoridad.
+
+## Por qué esta frontera
+
+- **Una cosa bien hecha.** Es más útil un motor afilado y predecible que una suite que hace de todo a medias. Si querés encadenarlo con otras herramientas —tuyas, de terceros, o las que vengan— podés, porque su salida es limpia, abierta y versionada.
+- **El juicio es tuyo, y eso es deliberado.** bib2graph asiste el trabajo *mecánico* —seguir citas a mano agota y se hace mal justo cuando estás cansado—. El trabajo *de criterio* —formular la pregunta, dejar que mute al leer, interpretar las tensiones, decidir qué entra— sigue siendo humano. La herramienta te lleva hasta la lectura; el trabajo de verdad, el de pensar, empieza ahí y es tuyo.
+- **Honestidad reportable.** Una corrida de bib2graph **no es** una revisión sistemática PRISMA, y no pretende serlo. Es un barrido exploratorio, reproducible y documentado, que reduce el sesgo de empezar tu lectura solo por lo que ya recordabas. Reportarlo así —con modestia y con la procedencia a la vista— es más fuerte, no más débil.
+
+## El principio de diseño: la frontera se sostiene sola
+
+Esta nota no enumera una lista cerrada de exclusiones; declara un **principio**.
+
+> Si una funcionalidad es muy distinta de *"convertir una búsqueda en estructura navegable"* —aunque sea una parte legítima del ciclo de investigación— **no entra en bib2graph: se construye al lado, como otra herramienta**.
+
+La frontera no se ensancha para acomodar lo nuevo. Lo nuevo se construye afuera y, si hace falta, se conecta consumiendo la salida limpia y versionada de bib2graph. Gestionar una biblioteca a través de proyectos, interpretar las tensiones de un campo, asistir la escritura: son trabajo real y parte del ciclo, pero son **otras** cosas, y mezclarlas adentro degradaría lo único que bib2graph promete ser —un motor determinista y confiable—.
+
+El principio es **fractal**: la misma disciplina que separa bib2graph de lo demás separa después módulo de módulo dentro del código, y esta nota (que habla al usuario) del ADR (que habla a quien decide el código). Trazar la línea con claridad, en cada nivel, es lo que mantiene cada pieza comprensible y confiable.
+
+## Dónde encaja en tu ciclo
+
+El ciclo de exploración bibliográfica es iterativo: sembrás, seguís citas, la pregunta muta, volvés a sembrar; después organizás, interpretás, escribís. bib2graph vive en el tramo del **forrajeo** —de la semilla a un corpus navegable con su orden de lectura— y se retira antes de la interpretación y la escritura. No te acompaña en todo el ciclo a propósito: hace bien su tramo y te entrega el material limpio para el tuyo. Lo que sigue —pensar, enmarcar, escribir— es tuyo, con tu juicio y con las herramientas que elijas.
+
+---
+
+*bib2graph es software libre (GPL-3.0). El código es la fuente de verdad; esta nota fija la intención.*

docs/ai-disclosure.md

@@ -0,0 +1,5 @@
+---
+title: IA en el desarrollo
+---
+
+{% include-markdown "../AI_DISCLOSURE.md" %}

docs/changelog.md

@@ -0,0 +1,5 @@
+---
+title: Changelog
+---
+
+{% include-markdown "../CHANGELOG.md" %}

docs/contributing.md

@@ -0,0 +1,5 @@
+---
+title: Contribuir
+---
+
+{% include-markdown "../CONTRIBUTING.md" %}

docs/getting-started/installation.md

@@ -0,0 +1,39 @@
+---
+title: Instalación
+---
+
+# Instalación
+
+bib2graph necesita **Python ≥ 3.11**.
+
+## Con uv (recomendado)
+
+Recomendamos [**uv**](https://docs.astral.sh/uv/) para gestionar el entorno:
+
+```bash
+uv add bib2graph
+```
+
+## Con pip
+
+```bash
+pip install bib2graph
+```
+
+## Extras opcionales
+
+Algunas capacidades viven en extras opt-in para mantener el núcleo liviano:
+
+| Extra | Habilita | Instalar |
+|-------|----------|----------|
+| `bibtex` | Sembrar el corpus desde archivos `.bib` | `uv add "bib2graph[bibtex]"` |
+| `gui` | Interfaz local (FastAPI + SPA), aún en construcción | `uv add "bib2graph[gui]"` |
+
+## Verificá la instalación
+
+```bash
+b2g --help
+```
+
+Deberías ver el grupo de comandos del CLI `b2g`. Si es así, seguí con el
+[Quickstart](quickstart.md).

docs/getting-started/quickstart.md

@@ -0,0 +1,57 @@
+---
+title: Quickstart
+---
+
+# Quickstart
+
+De una ecuación de búsqueda a un GraphML, sin escribir código.
+
+## Desde el CLI
+
+<!-- termynal -->
+
+```
+$ b2g init mi-investigacion
+Workspace creado en ./mi-investigacion
+$ cd mi-investigacion
+$ b2g seed --equation '"unequal ecological exchange"' --max-results 50
+Sembrando desde OpenAlex...
+---> 100%
+52 papers en el corpus
+$ b2g build
+Construyendo las redes...
+---> 100%
+Listas: acoplamiento · co-citación · co-autoría · instituciones · co-keywords
+$ b2g export --format graphml
+Exportadas a ./redes/*.graphml
+```
+
+En tres pasos pasaste de una ecuación a redes en GraphML, sin escribir código.
+
+Cada comando acepta `--json` para orquestarlo desde scripts o agentes. Para la
+lista completa de comandos y opciones, corré `b2g --help` o mirá la
+[referencia del CLI `b2g`](../reference/cli.md).
+
+!!! tip "Workspace por investigación"
+    `b2g init` crea una carpeta autocontenida (`workspace.json` + base de datos +
+    redes/snapshots/exports). Todos los comandos resuelven el workspace desde el
+    directorio actual — por eso el `cd` después de `init`.
+
+## Desde Python
+
+```python
+from pathlib import Path
+from bib2graph import OpenAlexSource, DuckDBStore, Networks, GraphMLExporter
+
+corpus = OpenAlexSource().seed('"unequal ecological exchange"').corpus
+store = DuckDBStore(Path("biblioteca.duckdb"))
+store.persist(corpus)
+
+for red in Networks.quick(store.load()):
+    GraphMLExporter().export(red.graph, red.metrics, out_dir=Path(f"redes/{red.spec.kind}"))
+```
+
+## Siguiente paso
+
+- Profundizá en flujos concretos en las [Guías](../guias/index.md).
+- Entendé el modelo por dentro en [Arquitectura](../ARCHITECTURE.md).

docs/guias/index.md

@@ -0,0 +1,28 @@
+---
+title: Guías (how-to)
+---
+
+# Guías (how-to)
+
+Las **guías** son recetas orientadas a una tarea concreta: ya sabés qué querés
+hacer y buscás los pasos para lograrlo. Si en cambio querés *aprender* desde
+cero, empezá por los [Tutoriales](../tutoriales/index.md).
+
+!!! note "En construcción"
+    Estamos escribiendo las guías. Seguimiento en el
+    [issue #208](https://github.com/complexluise/bib2graph/issues/208).
+    Planificado:
+
+    - Cómo elaborar y refinar una ecuación de búsqueda.
+    - Cómo expandir el corpus por citaciones (forrajeo) sin perder el foco.
+    - Cómo aplicar filtros PRISMA y curar (aceptar/rechazar) de forma versionable.
+    - Cómo interpretar las 5 redes y exportarlas a Gephi / Cytoscape.
+    - Cómo hacer reproducible un análisis (snapshots e historia del corpus).
+
+## Mientras tanto
+
+- [Quickstart](../getting-started/quickstart.md) — el camino más corto a un
+  GraphML.
+- [Referencia del CLI `b2g`](../reference/cli.md) — todos los comandos y opciones.
+- [API de Python](../reference/python-api.md) — para uso como librería.
+- [Arquitectura](../ARCHITECTURE.md) — el modelo mental del ciclo y las redes.

docs/index.md

@@ -0,0 +1,74 @@
+---
+title: Inicio
+---
+
+# bib2graph
+
+> De una búsqueda bibliográfica a **redes de citación reproducibles** — una
+> biblioteca de literatura que curás vos, sin servidores ni planillas.
+
+**bib2graph** toma una ecuación de búsqueda (o un archivo `.bib`), arma un corpus
+de papers desde [OpenAlex](https://openalex.org), te deja **curarlo** y lo
+proyecta a **redes bibliométricas** listas para analizar en Gephi, Cytoscape,
+networkx o donde quieras: acoplamiento bibliográfico, co-citación, co-autoría,
+colaboración institucional y co-ocurrencia de keywords.
+
+El corpus **persiste y crece** entre sesiones, y el resultado es **reproducible**:
+mismo input, mismas redes.
+
+!!! warning "Alpha"
+    Mientras la versión sea `0.x`, la API puede cambiar entre releases menores.
+    Úsalo para explorar y validar, no como dependencia estable de producción
+    todavía.
+
+## Empezá acá
+
+<div class="grid cards" markdown>
+
+-   :material-download: **[Instalación](getting-started/installation.md)**
+
+    Instalá `bib2graph` con `uv` o `pip` en un minuto.
+
+-   :material-rocket-launch: **[Quickstart](getting-started/quickstart.md)**
+
+    De una ecuación a un GraphML, sin escribir código.
+
+-   :material-book-open-variant: **[Guías](guias/index.md)**
+
+    Tutoriales y recetas para tareas concretas de investigación.
+
+-   :material-api: **[Referencia](reference/cli.md)**
+
+    El CLI `b2g` y la API de Python, autogeneradas desde el código.
+
+</div>
+
+## Qué hace
+
+- **Siembra** desde una ecuación de búsqueda (OpenAlex) o un archivo BibTeX.
+- **Expande** el corpus siguiendo citaciones, rankeando candidatos por
+  estructura — sin IA.
+- **Curás vos:** aceptar/rechazar papers, filtros PRISMA, todo versionable en CSV.
+- **5 redes bibliométricas:** acoplamiento, co-citación, co-autoría,
+  instituciones, co-keywords.
+- **Sub-redes temáticas** filtrando por keyword.
+- **Biblioteca persistente** (DuckDB) que crece entre sesiones.
+- **Reproducible:** mismo corpus → mismas redes y comunidades (hash de contenido).
+- **Dos interfaces:** CLI scriptable (`b2g`, salida `--json`) y librería de Python.
+- **Exporta** a GraphML/CSV para Gephi, Cytoscape, networkx, etc.
+
+## Cómo se construye (y la IA)
+
+bib2graph se desarrolla **con la IA en el lazo**: una persona plantea el problema,
+decide y **aprueba cada cambio**; modelos de IA implementan el código, los tests y
+la documentación bajo esa dirección. **El producto en sí no usa IA generativa** —
+el ranking del forrajeo es estructura bibliométrica determinista (acoplamiento,
+co-citación, centralidad), sin LLM ni embeddings, y la curación es 100% humana. El
+detalle está en [IA en el desarrollo](ai-disclosure.md).
+
+## Licencia
+
+[GPL-3.0-or-later](https://github.com/complexluise/bib2graph/blob/main/LICENSE) —
+software libre con copyleft fuerte: cualquier derivado que se distribuya debe
+seguir siendo libre y de código abierto. Es deliberado: esta herramienta queda
+para la comunidad y no puede cerrarse en un producto propietario.

docs/reference/cli.md

@@ -0,0 +1,22 @@
+---
+title: CLI b2g
+---
+
+# CLI `b2g`
+
+Referencia completa del CLI agente-native `b2g`: el grupo principal y todos sus
+subcomandos, con sus opciones y textos de ayuda. Se **autogenera desde el grupo
+Click** (mkdocs-click): es la misma información que `b2g --help`, siempre en
+sincronía con el código.
+
+!!! info "Salida JSON"
+    Cada subcomando acepta `--json` (envelope versionado) y respeta los exit
+    codes 0–5. Los detalles del contrato (envelope, exit codes, FSM) están en
+    [Contratos detallados](../API.md).
+
+::: mkdocs-click
+    :module: bib2graph.cli
+    :command: b2g
+    :prog_name: b2g
+    :depth: 1
+    :style: table