Biblioteca Supercontexto · guía para todo el staff

Para quién es esta guía

Para todo el equipo de CreaRackSL — Edu, Dani, Txell — sin necesidad de ser programador. Si trabajas aquí, esta guía te explica qué es “la Biblioteca” que ves en los dashboards, cómo te sirve a ti y por qué Claude la usa.

Lenguaje llano, sin jerga innecesaria. Ve al sitio que te interese:

• ¿Qué es la Biblioteca?
• ¿Para qué me sirve a mí?
• ¿Cómo la usa Claude?
• Los sensores del dashboard
• Drift & sync — la banda 5 de Pulse
• ¿Cómo se alimenta?
• Glosario mínimo

¿Qué es la Biblioteca?

La Biblioteca CreaRackSL es nuestro cerebro colectivo auto-mantenido. Es tres cosas a la vez:

1. Un índice del código vivo de CreaRack Pro y del workspace. Sabe qué funciones, modelos y endpoints existen, y cómo están conectados entre sí.
2. Una wiki que se escribe sola. Cuando alguien hace un cambio importante en el código, un agente llamado Bibliotecario lo lee, entiende el cambio, y escribe una página de wiki para dejar constancia. Sin que nadie se lo pida.
3. Un buscador semántico que entiende preguntas en lenguaje natural. Puedes preguntar “¿cómo funciona el sistema de multi-tenancy?” y devuelve la respuesta sintetizada con los fuentes.

Todo esto vive en D1 (la base de datos del workspace en Cloudflare), se expone via tools MCP para que Claude pueda consultarlo, y se visualiza en el sensor Bibliotecario del widget “Salud del sistema”.

¿Por qué la llamamos “Supercontexto”?

El término viene del concepto de “dar contexto extendido a una IA”. En lugar de que Claude tenga que leer todo el repo cada vez que arranca una sesión, la Biblioteca le da la foto más relevante al momento. Como un asistente que ha leído todo el código y la documentación, y te lo cuenta en el idioma que necesites.

¿Por qué se construyó?

Originalmente teníamos docs tradicionales (Markdown en el repo) que se quedaban desactualizados cada pocas semanas. Y teníamos código que solo Edu o Dani podían leer fluidamente. El objetivo del proyecto Supercontexto (cerrado en sesión 22, abril 2026) fue construir un sistema donde:

• El código habla por sí mismo — se indexa automáticamente.
• La documentación se auto-mantiene — el Bibliotecario crea/actualiza páginas al ritmo de los commits.
• Cualquiera puede preguntar y obtener respuesta — sin tener que saber dónde buscar.
• Claude arranca con contexto fresco — cada sesión del equipo entra con la foto del proyecto cargada.

¿Para qué me sirve a mí?

Si eres Txell (admin / finanzas / legal)

• Preguntar en lenguaje natural: en el Pulse (workspace.crearack.com/biblioteca/pulse) o via Help Widget puedes preguntar cosas como “¿qué se cobró a CreaRack por licencias en marzo?” o “¿qué es el módulo de signage?” y obtener respuesta con fuentes.
• Consultar decisiones pasadas: cuando un proveedor pregunta “¿por qué usáis X y no Y?”, la Biblioteca tiene las decision_pages (ADRs — Architecture Decision Records) con el razonamiento histórico.
• Contexto para Claude Code: si usas tu Claude Code (CLI) para preparar un contrato o responder un email técnico, puedes decir “pregúntale a la Biblioteca sobre X” y Claude la consulta.

Si eres Edu o Dani (devs)

• Arranque instantáneo de sesión: abres Claude Code y ya sabe en qué fase está el proyecto, qué crons están corriendo, qué hay pendiente. No tienes que recordar nada.
• Impacto de un cambio antes de tocarlo: preguntas “si modifico este archivo, ¿qué docs afectará?” y te lo dice.
• Buscar código por intención: en vez de grep, preguntas “¿dónde está el endpoint que genera el PDF del rack?”.
• Historial estructurado: incidentes, runbooks, decisiones — todo archivado en un sitio consultable.

¿Cómo la usa Claude?

Cada instancia de Claude Code (la que usa Edu, la de Dani, y cualquier otra que se monte) tiene acceso al Supercontexto como fuente de verdad complementaria al código.

Flujo típico en una sesión del agente

1. Al arrancar: Claude lee automáticamente el STATE.md del Supercontexto para saber en qué estado está el sistema. Sin intervención tuya.
2. Antes de hacer algo no trivial: llama a bib_ask (“¿cómo funciona X?”) o bib_search_semantic para consultar sin reinventar la rueda.
3. Al tocar código: llama a bib_impact_query para saber qué docs se ven afectados y avisarte.
4. Al cerrar: reporta los cambios con bib_report_change para que el Bibliotecario los indexe.

Por qué cada miembro del staff tiene su Claude

Cada persona del equipo tiene su instancia independiente de Claude Code con memorias propias (tus preferencias, tus vicios, tus contextos específicos). Pero todas comparten el Supercontexto — es conocimiento del proyecto, no de ti.

Es como una biblioteca de barrio: cada lector tiene su carnet y sus anotaciones privadas, pero los libros son de todos.

Los sensores del dashboard

En el widget “Salud del sistema” (dashboard principal workspace.crearack.com) verás tres sensores relacionados con la Biblioteca. Los tres miran el mismo sistema desde ángulos distintos.

Biblioteca

Qué mira: si el índice del código está al día. Cada noche a las 08:00 UTC un cron cuenta cuántos “nodos” (piezas de código y documentación) llevan más de 7 días sin verificarse, y publica el porcentaje “sano”.

Qué leer primero: el porcentaje grande. Si está por encima de 90% y en verde, no hay nada que hacer.

Si está en amber/rojo: el reindex ha fallado o lleva demasiado tiempo sin correr. Avisar a Edu/Dani.

¿Por qué no llega al 100%?

Es esperable que se estabilice en torno al 95-97%, no al 100%. Razones:

• Renombres y eliminaciones dejan huérfanos: cuando se borra una función o un modelo del código, su nodo en la Biblioteca se queda como huérfano hasta que un script de limpieza lo archive. Mientras, suma al “stale”.
• Apps Django no cubiertas por el cron: el cron AST refresca solo las apps principales (core, racks, blueprints, terminal, network, monitoring, signage). Apps secundarias quedan con last_indexed_at antiguo aunque su código exista.
• Docs del workspace: las páginas de wiki tienen su propio circuito (Bibliotecario-Ingest) que no siempre actualiza el timestamp aunque la página esté viva.

Si ves un salto brusco (de 90% a 17% como pasó el 06-05-2026), suele ser una de tres cosas:

1. Cron caído: el script cron-bib-reindex.sh perdió permisos o el repo en STAGE tiene drift. Mirar /opt/bib-reindex/cron-bib-reindex.log.
2. Handler MCP fallando silenciosamente: el reindex se ejecuta pero el handler en CF Workers excede el límite de 1000 subrequests con specs grandes. El log dice [OK] endpoints=0 engañoso. Solución: chunking en el script.
3. Nuevos tipos de nodo no contemplados: si se añade un tipo nuevo (ej. js_module) sin actualizar los crones, queda stale al 100%.

Grafo

Qué mira: si la arquitectura del código es sana (cohesión alta, pocas “funciones dios” que lo controlan todo).

Qué leer primero: el porcentaje de cohesión. >70% es sano, >80% es excelente.

Si está en amber/rojo: la arquitectura se está degradando. No urgente — pero conviene refactorizar cuando se pueda.

¿Qué es exactamente la “cohesión”?

cohesión = edges_internas_de_la_comunidad / edges_totales_de_sus_miembros

Traducido: de todas las conexiones que tiene un módulo, ¿cuántas son consigo mismo y cuántas se van a otros módulos? Cuanto más alto el %, más auto-contenido es ese módulo.

¿Por qué se queda anclada en ~84% y no sube?

Es el techo natural del grafo actual, no un bug. Razones:

• 100% sería un grafo desconectado: significaría que core no se usa desde racks, signage no llama a core, etc. Ningún proyecto real funciona así.
• El algoritmo (Label Propagation) es determinista: con el mismo grafo da el mismo resultado, y el grafo apenas cambia entre runs (±20 nodos al día sobre 4000). Por eso devuelve siempre el mismo 0.8393203124999999.
• Los 10 god nodes son útiles: utilities transversales (helpers de HTMX, tareas de monitoring) que cruzan comunidades por diseño. Eliminarlos haría peor el código, no mejor.

¿Cómo subiría el % en la práctica?

En literatura de modularidad, >80% de cohesión se considera “alta”. El 84% del grafo CreaRack ya es objetivamente bueno — el widget está dando una señal correcta, no está estancado por un problema técnico.

Más útil que perseguir el % es mirar las 2-3 comunidades con cohesión más baja — esas sí señalan acoplamiento mal estructurado y son candidatos reales a refactor. Disponible en el Pulse (/biblioteca/pulse) con detalle por comunidad.

Bibliotecario

Qué mira: la wiki auto-mantenida. Cuántas páginas hay, cuántas están pendientes de revisión, qué agentes han trabajado en las últimas 24h, cuánto ha costado en API.

Qué leer primero: el número de páginas y el insight en verde (“Sistema sano”). Si dice eso, todo OK.

Si está en rojo: puede ser una contradicción detectada entre páginas, o un cron que lleva >36h sin correr. Skill /wiki-lint-review o mirar gh run list.

Cómo leer la línea de métricas

Cada sensor muestra una línea de números bajo el título. Aquí está la traducción al cristiano:

Biblioteca — 215 stale de 3841 nodos · hace 1h

• 3841 nodos: cuántas piezas de código tiene indexadas (funciones, modelos, endpoints, archivos…). Cuanto más alto, más completa es la foto.
• 215 stale: piezas que llevan tiempo sin reverificarse. Mientras sea menos del 10%, es normal.
• hace 1h: cuándo corrió la última actualización del índice. Si pasa de 24h, algo va mal.

Grafo — 3841 nodos · 371 comunidades · 10 god nodes

• 3841 nodos: las mismas piezas de código del sensor anterior.
• 371 comunidades: grupos de piezas que trabajan juntas (un módulo, una feature, una zona de la app). Más comunidades = más modular.
• 10 god nodes: piezas demasiado grandes que tocan a casi todo. Cuanto menos, más sano. Por encima de 20 conviene refactorizar.

Bibliotecario — 99 pág · 94 active · 5 draft · 42 acc/24h · 460.2k toks/7d

• 99 pág: páginas de wiki existentes.
• 94 active · 5 draft: cuántas están publicadas y cuántas pendientes de revisar.
• 42 acc/24h: accesos a la wiki en las últimas 24 horas (lo que el equipo y los agentes consultan).
• 460.2k toks/7d: tokens de IA consumidos por los crons del Bibliotecario en los últimos 7 días — la factura de mantener todo esto vivo (≈$1/semana).

Regla general para los 3 sensores

Si los 3 están en verde, no hay nada que hacer. Solo mirar de reojo una vez al día.

Drift & sync — la banda 5 de Pulse

Pulse tiene una banda llamada “Drift & sync” con tres tarjetas. Vigila cuándo la documentación deja de coincidir con el código (o con sus páginas espejo). Tres ángulos del mismo problema:

1. Docs desactualizados (Escriba)

Páginas de wiki que apuntan a archivos de código que han cambiado desde la última vez que la doc se revisó.

Es comparación por timestamps: si el código se modificó hoy pero la doc no se ha tocado desde hace 8 días, sale aquí marcada con +8 d. No lee el contenido, solo mira las fechas — barato y rápido.

🟢 Verde: nada que hacer. · 🟡 Amber: revisar cuando puedas. · 🔴 Rojo: la doc ya está engañando.

→ Detalle: [[feature—biblioteca—escriba-drift]]

2. Drift checks · 7 d (Haiku)

Un paso más sofisticado: en vez de mirar fechas, un cron usa Claude Haiku para LEER la página y compararla con el código actual, y devuelve un porcentaje de drift + un nivel de confianza. Si encuentra una desviación clara, abre automáticamente un draft con la propuesta de corrección.

Cifras típicas: ~$0.02/semana, 10-15 páginas revisadas/día. Si el % sube por encima de 15 o el coste se dispara, mirar el endpoint.

→ Detalle: [[feature—biblioteca—drift-check-semantic]] · [[decision—20260514—kb-vs-graph-drift-detection]] · [[entity—biblioteca—endpoint—drift-checks]]

3. Mirror cascades (Sync Cascade)

Algunas páginas son espejos entre sí: cuando se actualiza el onboarding de Edu, los onboardings de Dani y Txell deberían recibir el mismo cambio. El runbook de credenciales del workspace es espejo del de la plataforma. Etc.

Sync Cascade detecta esos vínculos vía un campo mirrors: en el front-matter y, cuando una página fuente cambia, propone PRs draft con la propagación a sus espejos. La verificación humana siempre queda al final — el sistema no mergea solo.

Si la tarjeta marca “X pendientes”, hay espejos esperando que alguien revise el PR draft. Click en “Ver PR drafts” lleva al listado en GitHub.

→ Detalle: [[feature—supercontext—sync-cascade]] · [[entity—biblioteca—endpoint—mirror-cascades]] · [[runbook—workspace—pausar-sync-cascade]] (cómo apagarlo si se vuelve loco)

Qué hacer cuando algo sale en amber/rojo

Verde en las tres no significa que la doc esté perfecta — solo que el sistema no ha detectado desincronización. Si tú ves algo raro al leer una página, edita y guarda. El sistema te ayuda, no te sustituye.

¿Cómo se alimenta?

El sistema tiene 6 crons automáticos que lo mantienen vivo sin intervención humana. Cada uno hace una cosa específica:

Todo vive en GitHub Actions del repo CreaRackSL-workspace. Si alguno falla, el sensor Bibliotecario pasa a amber/rojo y avisa.

Coste

El sistema consume aproximadamente $10/mes de API Anthropic (Haiku + Sonnet con caching). Este coste se ve reflejado en el sensor (355k toks/7d ≈ $1/semana).

¿Cómo contribuir?

Si eres staff no-dev (Txell)

Tu mejor contribución es preguntar en el Pulse cuando no sepas algo. Cada pregunta que haces:

1. Genera una respuesta sintetizada.
2. Si la respuesta es sólida, se archiva automáticamente como borrador de página.
3. Al día siguiente, el Curator decide si promoverla a página definitiva.
4. La siguiente persona que pregunte lo mismo obtiene la respuesta instantánea.

Es decir: preguntando, construyes la wiki para todos.

Si eres dev (Edu / Dani)

• Commitea con mensajes claros. El Bibliotecario-Ingest lee el mensaje del commit para decidir si crear página.
• Confía en los skills CLI: /wiki-review-drafts, /wiki-promote, /wiki-delete, /wiki-lint-review. Los tienes en .claude/skills/ tanto en CreaRack-Pro como en el workspace.
• Respeta la Regla 19: cualquier sesión de Claude que toque el Supercontexto lee STATE.md + briefings/NEXT.md al arrancar.

Glosario mínimo

Dónde ampliar

• workspace.crearack.com/biblioteca/pulse — estado completo en vivo (8 paneles + nueva sección Bibliotecario · 7d).
• src/content/wiki/catalog.md — catálogo de todas las páginas (250+).
• src/content/wiki/index.md — mapa curado de arranque rápido con los enlaces más útiles.
• public/supercontext/STATE.md — estado del sistema operativo para las sesiones del agente.
• public/supercontext/reports/ — informes semanales archivados (domingo 08:00 UTC).

Véase también

• [[concept—biblioteca—supercontexto]]
• [[feature—biblioteca—graphify]]
• [[feature—supercontext—fase-6-metricas-utility]]
• [[crearack-tech—guides—biblioteca-guide]]
• [[workspace—onboarding—onboarding-edu]]
• [[workspace—onboarding—onboarding-dani]]
• [[feature—biblioteca—escriba-drift]] — Drift por timestamps (tarjeta 1 de Drift & sync)
• [[feature—biblioteca—drift-check-semantic]] — Drift por contenido con Haiku (tarjeta 2)
• [[feature—supercontext—sync-cascade]] — Espejos entre páginas (tarjeta 3)
• [[runbook—workspace—pausar-sync-cascade]] — Apagar Sync Cascade si genera ruido