docs(mkdocs): API navegable por temas + navegación y UX enriquecidas

docs/ARCHITECTURE.md

@@ -34,6 +34,23 @@ visual library-centric vive en un producto separado; ADR [0040](decisiones/0040-
 
 ## 2. Vista de alto nivel
 
+```mermaid
+flowchart LR
+    EQ["ecuación de búsqueda<br/>o archivo .bib"] --> SRC["Source<br/>OpenAlex · BibTeX"]
+    SRC --> CORPUS[("CORPUS<br/>tabla Arrow<br/>1 fila / paper")]
+    FOR["Forrajeo<br/>back/forward · rank = scent"] <--> CORPUS
+    PRE["Preprocessor<br/>normalize + thesaurus"] --> CORPUS
+    CORPUS --> PROJ["Projectors<br/>acoplamiento · co-citación<br/>co-autoría · keyword · institución"]
+    PROJ --> NET["Networks<br/>networkx"]
+    NET --> ANA["Análisis<br/>métricas · centralidad<br/>comunidades · asortatividad"]
+    NET --> EXP["Exporters<br/>GraphML / CSV"]
+    ANA --> REP["informe de calidad"]
+    CORPUS -. persiste .-> DUCK[("DuckDBBackend<br/>biblioteca viva · stateful")]
+    DUCK -. snapshot sellado .-> SNAP["CorpusSnapshot"]
+```
+
+*Detalle anotado del mismo flujo (con topes, procedencia y estado del ciclo):*
+
 ```
    ecuación de búsqueda
           │  (traducción + reporte de traducción, ADR 0007)

docs/guias/index.md

@@ -72,4 +72,4 @@ trabajas.
 - [Tu primer mapa de investigación](../tutoriales/primer-mapa.md) — aprende desde cero, en 5 minutos
 - [Quickstart](../getting-started/quickstart.md) — ciclo mínimo en 2 minutos
 - [Referencia CLI](../reference/cli.md) — todos los comandos
-- [API Python](../reference/python-api.md) — como librería
+- [API Python](../reference/python-api/index.md) — como librería

docs/reference/python-api/analisis.md

@@ -0,0 +1,17 @@
+---
+title: Análisis de redes
+---
+
+# Análisis de redes
+
+Leer las redes: métricas globales, centralidad por nodo, detección de
+comunidades, asortatividad y composición de comunidades, más el informe de
+calidad específico de la red de co-citación.
+
+::: bib2graph.network_metrics
+::: bib2graph.centrality
+::: bib2graph.detect_communities
+::: bib2graph.assortativity
+::: bib2graph.community_composition
+::: bib2graph.cocitation_quality_report
+::: bib2graph.QualityThresholds

docs/reference/python-api/corpus.md

@@ -0,0 +1,19 @@
+---
+title: Corpus y persistencia
+---
+
+# Corpus y persistencia
+
+El corazón del modelo de datos: el `Corpus` (una tabla canónica Arrow con
+semántica de valor), su `Manifest` de procedencia, los snapshots sellados y los
+backends que lo respaldan —puro en memoria para tests, o DuckDB para la
+biblioteca viva—.
+
+::: bib2graph.Corpus
+::: bib2graph.Manifest
+::: bib2graph.CorpusSnapshot
+::: bib2graph.SchemaError
+::: bib2graph.TabularBackend
+::: bib2graph.InMemoryBackend
+::: bib2graph.stores.duckdb.DuckDBStore
+::: bib2graph.backends.duckdb.DuckDBBackend

docs/reference/python-api/exportadores.md

@@ -0,0 +1,11 @@
+---
+title: Exportadores
+---
+
+# Exportadores
+
+Llevar las redes fuera de bib2graph: `GraphMLExporter` (para Gephi, Cytoscape,
+networkx) y `CsvExporter` (nodos y aristas en tablas planas, versionables).
+
+::: bib2graph.GraphMLExporter
+::: bib2graph.CsvExporter

docs/reference/python-api/forrajeo.md

@@ -0,0 +1,17 @@
+---
+title: Forrajeo y curación
+---
+
+# Forrajeo y curación
+
+Expandir y curar el corpus: el `Forager` rankea candidatos por *information
+scent* (estructura bibliométrica determinista, sin IA), con preview de
+crecimiento antes de comprometer; el `Preprocessor` normaliza, y los filtros
+PRISMA acotan el corpus de forma trazable.
+
+::: bib2graph.Forager
+::: bib2graph.RankedCandidates
+::: bib2graph.GrowthPreview
+::: bib2graph.Preprocessor
+::: bib2graph.apply_filters
+::: bib2graph.FilterCriterion

docs/reference/python-api/fuentes.md

@@ -0,0 +1,14 @@
+---
+title: Fuentes (siembra)
+---
+
+# Fuentes (siembra)
+
+La costura de **ingesta de doble puerta**: `Source` y sus implementaciones
+siembran el corpus inicial desde una ecuación de búsqueda (OpenAlex) o un archivo
+BibTeX. Ambas puertas son primarias.
+
+::: bib2graph.Source
+::: bib2graph.OpenAlexSource
+::: bib2graph.BibtexSource
+::: bib2graph.SeedResult

docs/reference/python-api/index.md

@@ -0,0 +1,53 @@
+---
+title: API de Python
+---
+
+# API de Python
+
+Referencia de la **superficie pública de la librería** `bib2graph`, agrupada por
+tema. Se **autogenera desde los docstrings** del código (mkdocstrings): si cambia
+el código, cambia esta página.
+
+Para usar la herramienta desde la terminal, mira la [referencia del CLI `b2g`](../cli.md).
+
+!!! tip "Cómo leer esta referencia"
+    Cada objeto muestra un **índice de sus miembros** al principio (haz clic para
+    saltar) y un **ícono de tipo** —clase, método o atributo— en la tabla de
+    contenidos de la derecha. Los tipos en las firmas son **enlaces**: haz clic
+    para ir a su definición.
+
+## Mapa de la API
+
+<div class="grid cards" markdown>
+
+-   :material-database: **[Corpus y persistencia](corpus.md)**
+
+    El `Corpus` (tabla canónica en memoria), su `Manifest`, snapshots sellados y
+    los backends (memoria / DuckDB) que lo respaldan.
+
+-   :material-seed: **[Fuentes (siembra)](fuentes.md)**
+
+    `Source` y sus implementaciones (OpenAlex, BibTeX): de una ecuación de
+    búsqueda o un `.bib` al corpus inicial.
+
+-   :material-graph-outline: **[Forrajeo y curación](forrajeo.md)**
+
+    `Forager`, preview de crecimiento, preprocesamiento y filtros PRISMA para
+    expandir y curar el corpus.
+
+-   :material-vector-triangle: **[Redes (proyección)](redes.md)**
+
+    `Networks` y los cinco proyectores: acoplamiento, co-citación, co-autoría,
+    colaboración institucional y co-ocurrencia de keywords.
+
+-   :material-chart-scatter-plot: **[Análisis de redes](analisis.md)**
+
+    Métricas, centralidad, detección de comunidades, asortatividad y el informe
+    de calidad de co-citación.
+
+-   :material-export: **[Exportadores](exportadores.md)**
+
+    `GraphMLExporter` y `CsvExporter` para llevar las redes a Gephi, Cytoscape o
+    networkx.
+
+</div>

docs/reference/python-api/redes.md

@@ -0,0 +1,18 @@
+---
+title: Redes (proyección)
+---
+
+# Redes (proyección)
+
+Proyectar el corpus a **redes bibliométricas**. `Networks` orquesta los cinco
+proyectores —acoplamiento bibliográfico, co-citación, co-autoría, colaboración
+institucional y co-ocurrencia de keywords—, cada uno produciendo un
+`NetworkArtifact` listo para analizar o exportar.
+
+::: bib2graph.Networks
+::: bib2graph.NetworkArtifact
+::: bib2graph.BibliographicCouplingProjector
+::: bib2graph.CoCitationProjector
+::: bib2graph.AuthorCollaborationProjector
+::: bib2graph.InstitutionCollaborationProjector
+::: bib2graph.KeywordCoOccurrenceProjector

docs/tutoriales/primer-mapa.md

@@ -148,4 +148,4 @@ En 5 minutos:
   ecuación de búsqueda, forrajeo, curación PRISMA, lectura de redes y
   redacción del reporte.
 - **Referencia completa:** [Todos los comandos de bib2graph](../reference/cli.md).
-- **Como librería Python:** [API Python](../reference/python-api.md).
+- **Como librería Python:** [API Python](../reference/python-api/index.md).

mkdocs.yml

@@ -23,6 +23,12 @@ edit_uri: edit/dev/docs/
 
 docs_dir: docs
 
+# `mkdocs serve` solo vigila docs_dir y este archivo. La "API de Python" se
+# genera desde los docstrings de src/ (mkdocstrings); sin esto, editar el código
+# NO recarga el sitio en vivo y seguís viendo el build anterior.
+watch:
+  - src
+
 # Validación de enlaces. Muchos .md fuente —los ADRs (inmutables) y los archivos
 # de raíz como CONTRIBUTING/VERSIONING/AGENTS— enlazan entre sí con rutas
 # relativas que son correctas en GitHub (su render principal) pero caen fuera de
@@ -61,12 +67,18 @@ theme:
     - navigation.sections
     - navigation.top
     - navigation.instant
+    - navigation.instant.progress   # barra de progreso al navegar sin recargar
     - navigation.tracking
     - navigation.indexes
+    - navigation.path                # migas de pan (breadcrumbs) por página
+    - navigation.footer              # enlaces anterior/siguiente al pie
+    - navigation.prune               # solo renderiza el nav visible (perf: 38 ADRs)
     - toc.follow
     - search.suggest
     - search.highlight
     - content.code.copy
+    - content.code.annotate          # anotaciones (1) dentro de bloques de código
+    - content.tooltips               # tooltips en abreviaturas y preview de símbolos
     - content.action.edit
 
 plugins:
@@ -82,24 +94,35 @@ plugins:
           paths: [src]
           options:
             docstring_style: google
+            docstring_section_style: table   # Args/Returns como tabla prolija
             show_root_heading: true
             show_root_full_path: false
             show_source: false
             show_signature_annotations: true
             separate_signature: true
+            signature_crossrefs: true        # tipos en la firma → enlaces clicables
             members_order: source
             heading_level: 2
+            show_symbol_type_heading: true   # ícono de tipo (clase/método/attr) en headings
+            show_symbol_type_toc: true       # …y en la tabla de contenidos (escaneable)
+            summary: true                    # índice compacto de miembros por objeto
             filters: ["!^_"]
 
 markdown_extensions:
   - admonition
+  - abbr                    # abreviaturas con tooltip (junto a content.tooltips)
   - attr_list
   - md_in_html
   - tables
   - toc:
       permalink: true
   - pymdownx.details
-  - pymdownx.superfences
+  - pymdownx.superfences:
+      custom_fences:
+        # Diagramas Mermaid: ```mermaid … ``` se renderiza como diagrama vectorial.
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
   - pymdownx.tabbed:
       alternate_style: true
   - pymdownx.highlight:
@@ -147,7 +170,14 @@ nav:
       - Leer las 5 redes: guias/leer-redes.md
       - Del corpus al reporte: guias/reporte.md
   - Referencia:
-      - API de Python: reference/python-api.md
+      - API de Python:
+          - reference/python-api/index.md
+          - Corpus y persistencia: reference/python-api/corpus.md
+          - Fuentes (siembra): reference/python-api/fuentes.md
+          - Forrajeo y curación: reference/python-api/forrajeo.md
+          - Redes (proyección): reference/python-api/redes.md
+          - Análisis de redes: reference/python-api/analisis.md
+          - Exportadores: reference/python-api/exportadores.md
       - CLI b2g: reference/cli.md
       - Glosario: reference/glosario.md
   - Contribuye:

src/bib2graph/backends/duckdb.py

@@ -988,7 +988,7 @@ def persist_filter_steps(
     ) -> None:
         """Persiste los pasos de filtro PRISMA en ``filter_log``.
 
-        #126 — trazabilidad PRISMA: los pasos aplicados en ``b2g filter``
+        Ref #126 — trazabilidad PRISMA: los pasos aplicados en ``b2g filter``
         se guardan para que ``manifest.filters`` sobreviva entre cargas del
         store.
 
@@ -1020,7 +1020,7 @@ def persist_filter_steps(
     def load_filter_steps(self) -> list[dict[str, object]]:
         """Carga los pasos de filtro PRISMA desde ``filter_log``.
 
-        #126 — trazabilidad PRISMA: permite que ``DuckDBStore.load()``
+        Ref #126 — trazabilidad PRISMA: permite que ``DuckDBStore.load()``
         reconstruya ``manifest.filters`` con los pasos persistidos.
 
         Returns:
@@ -1051,7 +1051,7 @@ def persist_enricher_refs(
     ) -> None:
         """Persiste las referencias de enriquecedor en ``enricher_log``.
 
-        #141 — trazabilidad de enriquecimiento: los ``EnricherRef`` aplicados
+        Ref #141 — trazabilidad de enriquecimiento: los ``EnricherRef`` aplicados
         en ``b2g enrich`` / ``b2g chain`` / ``b2g build`` se guardan para que
         ``manifest.enrichers`` sobreviva entre cargas del store.
 
@@ -1078,7 +1078,7 @@ def persist_enricher_refs(
     def load_enricher_refs(self) -> list[dict[str, Any]]:
         """Carga las referencias de enriquecedor desde ``enricher_log``.
 
-        #141 — trazabilidad de enriquecimiento: permite que
+        Ref #141 — trazabilidad de enriquecimiento: permite que
         ``DuckDBStore.load()`` reconstruya ``manifest.enrichers`` con los
         EnricherRef persistidos.
 

src/bib2graph/backends/memory.py

@@ -349,7 +349,7 @@ class InMemoryBackend:
     Semántica de valor: todas las operaciones mutantes devuelven una nueva
     instancia; la original no cambia nunca.
 
-    #54: almacena también los IDs backward observados en ``_referenced_refs``
+    Ref #54: almacena también los IDs backward observados en ``_referenced_refs``
     (lista en memoria, equivalente a la tabla ``referenced_but_not_fetched``
     de ``DuckDBBackend``).
     """

src/bib2graph/cli/commands/networks.py

@@ -21,7 +21,7 @@
 
 DEPRECADO (ADR 0038, #165): usar ``b2g build --spec``.  Se retira en 0.11.0.
 
-#159 — helper compartido:
+Ref #159 — helper compartido:
   ``run_networks`` delega la carga YAML y proyección a ``_build_from_spec_file``
   (definido en ``build.py``).  Esto garantiza que ``build --spec`` y
   ``networks --spec`` nunca diverjan, y que #165 pueda retirar ``networks``