feedback(skill): fricción de agente en sandbox sin acceso a OpenAlex + workflow --from-bib incompleto

[Luisehica]

Contexto

• Perspectiva: agente (Claude) operando en un sandbox con red restringida por allowlist de dominios (sin api.openalex.org habilitado)
• Estrategia: one-shot con --from-bib (sin red)
• Versión: bib2graph 0.11.0

Qué funcionó

• La CLI es agente-friendly en el sentido correcto: --help en cada verbo es autoritativo, status da "próximo mejor paso" explícito, y los mensajes de error en general dicen qué comando correr después.
• seed --from-bib funcionó bien para poblar el corpus offline una vez instalado el extra correcto.
• El SKILL.md es limpio y legible: nada de instrucciones ocultas, buena separación entre lo que la herramienta automatiza y lo que es "irreductiblemente humano".

Fricción / qué costó

1. Extra bibtex no viene por defecto. pip install bib2graph seguido de seed --from-bib falla con "bibtexparser no está instalado". Para un agente que recién descubre la herramienta y va directo a lo local/sin-red (probablemente el camino más común quando no hay red saliente disponible), este debería ser el camino que "sí o sí" funciona out of the box.

2. El workflow --from-bib es engañoso sobre "sin red". Sembrar desde .bib no pide red, pero build después da 4 redes con 0 nodos/0 aristas porque los papers no tienen references_id/authors_id/keywords_id/cited_by_id, que solo llegan vía seed --resolve o enrich (ambos SÍ necesitan red a OpenAlex). El mensaje de build avisa esto, pero recién ahí, después de correr todo el pipeline. Sería valioso que seed --from-bib (sin --resolve) advirtiera desde el inicio: "este corpus no tendrá redes útiles hasta resolver contra OpenAlex".

3. Errores de red no distinguen "sin internet" de "dominio bloqueado por firewall/allowlist". El 403 de seed --equation contra api.openalex.org se reportó como "Verificá tu conexión a internet y reintentá", lo cual es engañoso en un sandbox con salida a internet real pero restringida por dominio. Un agente pierde tiempo diagnosticando esto. Sugerencia: si el status code es 403 (vs. timeout/DNS fail), sugerir explícitamente revisar allowlist/proxy corporativo en vez de "conexión a internet".

4. resolve/seed --resolve no explica el motivo del 0. Corrí resolve sobre un corpus sembrado desde .bib sin DOIs y devolvió "Papers con DOI: 0 / Resueltos: 0" sin sugerir la causa raíz (el .bib no traía campo doi). Un mensaje tipo "0 papers con DOI en el corpus — agregá el campo doi a las entradas .bib o usá seed --equation" ahorraría una vuelta de diagnóstico.

5. El subcomando skill genera fricción de confianza en el agente por diseño, no por contenido. Que un paquete de PyPI tenga un verbo literal "Instala la skill de bib2graph en el directorio de Claude" es, correctamente, una señal de alerta para un agente cauteloso — tuve que auditar el SKILL.md completo antes de confiar en él (resultó limpio). No es necesariamente algo a "arreglar", pero documentar explícitamente en el --help o el README que el archivo es solo texto/markdown sin código ejecutable ayudaría a que agentes lo adopten con menos fricción de auditoría.

Qué faltó / ideas

• Un modo b2g doctor o similar que chequee de una: extras instalados, conectividad a OpenAlex, DOIs faltantes en el corpus — antes de que el usuario/agente llegue a build y se encuentre con redes vacías.
• Aclarar en seed --help que --from-bib sin --resolve produce un corpus "solo lectura de metadata", no forrajeable ni graficable.

(opcional) Pasos corridos

seed --equation "..." (403, sin acceso a api.openalex.org)
seed --from-bib semillas.bib (falló por bibtexparser faltante, luego OK tras pip install bib2graph[bibtex])
resolve --email ... (0/0/0, sin causa explicada)
build (4 redes, 0 nodos cada una)