Visión generalUn reader para la documentación
Un reader para la documentación
que ya escribiste.
No es una wiki con una integración de git añadida — es al revés. Tu repository es la fuente de verdad, la estructura de carpetas es la navegación y no hay ningún archivo que tengas que escribir antes.
01
Descubrimiento
Ya sabe dónde están tus documentos
La primera pantalla no es un asistente de configuración. Conecta un repository y el árbol está ahí, en un orden que alguien habría elegido, con títulos que alguien habría escrito.
- Dónde busca
- docs/, luego documentation/, luego doc/, luego .github/docs/ — después las carpetas adr/, architecture/, specs/ y rfc/ en la raíz, todas como secciones de primer nivel. Si no existe ninguna, lee en su lugar todos los archivos Markdown del repository. Lo que decida queda registrado, así que las sincronizaciones posteriores son deterministas.
- Qué ignora
- node_modules, .venv, vendor, target, build, dist, .next y una docena más. Una barra lateral llena de README de dependencias es lo primero que hace que una herramienta de documentación parezca abandonada.
- Cómo recibe su nombre una página
- El título del front matter, luego el primer H1, luego el nombre de archivo hecho legible — auth-flow.md pasa a Auth flow, 01-intro.md pasa a Intro. Nunca se muestra un nombre de archivo en bruto con su extensión.
- Cómo se decide el orden
- README o index primero, y se convierte en la portada de la carpeta. Luego los prefijos numéricos en orden numérico. Luego todo lo demás por orden alfabético del título. Las subcarpetas después de los archivos. Ninguna lista que mantener.
- Adónde va el ruido
- CHANGELOG, LICENSE, CONTRIBUTING, SECURITY y sus parientes se pliegan en un grupo Archivos del repo al final — salvo que uno de ellos sea el único Markdown del repository, en cuyo caso ocultarlo te dejaría sin nada.
- La salida de emergencia que nunca deberías necesitar
- Existe un archivo de anulación. Nunca es obligatorio, no se menciona en ningún lugar del producto, y un repository que lo necesite para leerse bien es un bug nuestro y no una tarea tuya.
02
La superficie de lectura
Hecha para una especificación que se lee de principio a fin
La mayoría de las herramientas de documentación están hechas para ojear. Esta está hecha para la lectura de cuarenta minutos: un ancho de línea que no se mueve, un índice que te sigue y código que sigue el tema.
- El camino iluminado
- El riel junto al árbol ilumina la ascendencia del documento en el que estás, en degradado de un nivel a otro. Es el único momento de dramatismo visual del producto, y existe porque saber dónde estás dentro de un corpus es justo lo que suele fallar en un árbol de carpetas.
- Un ancho de línea que no se mueve
- La prosa se limita a 78 caracteres en cada punto de corte. Puedes cambiarlo si quieres una columna más ancha o más estrecha, y esa elección te acompaña.
- Oscuro primero, claro completo
- Ambos temas están diseñados y no invertidos, cada uno con su acento, sus propias sombras y sus seis colores de sintaxis. Se aplica antes del primer pintado, así que no hay destello al cargar.
- Diagramas a juego con la página
- Mermaid lee la paleta en uso en lugar de traer un tema estándar, y la vuelve a leer cuando cambias de tema. Ni él ni el resaltador de sintaxis se cargan para un documento que no los usa.
- Copiar para un LLM
- A menudo se abre una especificación para pegarla en otro sitio. Llévate un documento o una carpeta entera como Markdown limpio — sin front matter ni insignias, con los enlaces relativos reescritos — con el recuento de tokens antes de decidirte.
03
Mantenerse al día
Todo el pipeline, etapa por etapaLeer no tiene paso de publicación. Un push es la actualización.
El repository es la fuente de verdad y lo sigue siendo. Nada se copia, nada se importa, y hacer merge es lo único que haces para actualizar un documento.
- Nunca clonado
- Una sola llamada a la API devuelve toda la estructura de carpetas más un blob SHA por archivo. Sin binario de git, sin copia de trabajo, nada en disco. Solo se descargan blobs Markdown, y nunca nada fuera de la raíz de la documentación.
- Un archivo sin cambios no cuesta nada
- El blob SHA es el detector de cambios. Mismo SHA y el archivo se omite por completo, así que un repository donde se movió un párrafo hace el trabajo de un solo archivo.
- Un movimiento conserva su identidad
- Un archivo renombrado se reconoce como el mismo documento, así que su estado de revisión, sus notas, sus confirmaciones de lectura y sus hallazgos de salud se mueven con él. Es la propia regla de coincidencia exacta de git y no necesita puntuación de similitud.
- Tu pestaña se entera por la base de datos
- El worker hace commit del cambio y lo anuncia por la misma conexión, dentro de la misma transacción. Sin bucle de sondeo — y un documento que tienes abierto ofrece recargarse en lugar de cambiarte los párrafos delante.
04
La capa de flujo de trabajo
Saber si un documento sigue siendo cierto
Un alojamiento de documentación puede decirte que una página existe. No puede decirte si alguien está de acuerdo con ella, si se ha construido, o si ha dejado de describir el sistema en silencio.
- Dos ejes, que se mueven por separado
- Un estado de revisión — borrador, en revisión, validado, rechazado, no aplica — y un estado de implementación, porque una especificación con la que todos están de acuerdo y que nadie ha construido es una situación distinta de una a medio construir y discutida.
- El desfase es contenido, nunca una fecha
- Un estado recuerda la versión exacta sobre la que se fijó. Edita el documento y muestra validado · desfasado en lugar de conservar una etiqueta que ha dejado de ser cierta. Una marca de tiempo señalaría desfase cada vez que un worker tocara una fila.
- Ninguna fila hasta que alguien decida algo
- Un documento sin clasificar no tiene estado y no muestra ninguna etiqueta. Un corpus que nadie ha mirado no cuesta nada y parece lo que es, en lugar de un muro de borradores.
- Notas sobre un encabezado
- Un comentario se ancla a la sección de la que trata. Si ese encabezado desaparece, la nota falla de forma visible en lugar de reubicarse sobre un texto que dice otra cosa.
- Confirmaciones de lectura creíbles
- Se cuentan tras diez segundos de lectura visible, nunca con un clic en el árbol, y solo sobre la versión actual.
- Salud de la documentación
- Enlaces relativos rotos, documentos cuyo contenido no ha cambiado en demasiado tiempo, y documentos que nombran un archivo fuente que cambió después que ellos. Tres señales comprobables, ninguna opinión y nada que llame a un modelo.
05
Agentes
Todos los tools, y los cuatro que no pueden existirUn agente es un lector de pleno derecho
Tu equipo escribe documentación en parte para que un modelo la lea. Esta es la superficie que se lo permite, sin copiar y pegar y sin dejarle reescribir nada.
- Un solo endpoint, herramientas retenidas según el alcance
- Un endpoint MCP sin estado al que tu agente apunta con una clave limitada a un proyecto. A una clave de solo lectura nunca se le muestran las herramientas de escritura — no basta con rechazarla cuando las llama.
- Puede producir, no deshacerse
- Un agente deja artifacts en un espacio propio, versionados, junto a la documentación. No puede tocar un archivo del repository, no puede borrar un artifact y no puede cerrar una nota.
- La asimetría
- Un agente puede afirmar que un comentario está atendido. Solo una persona puede cerrarlo. Relaja eso y la objeción de un revisor desaparece en cuanto el agente afirma haberla atendido — en silencio, a escala, en el mismo sistema que un equipo adoptó para evitarlo.
06
Acceso
Roles, equipos e invitacionesNada es legible por defecto
Unirse a una organización no da acceso a ningún documento. Suena estricto hasta que recuerdas que la alternativa es que invitar a un colaborador externo le dé todo el espacio de trabajo.
- La membresía es la organización; el acceso es el proyecto
- Un Member lee un proyecto mediante un acceso de equipo o uno directo. Alguien sin equipo ni acceso no lee nada en absoluto, y un Guest ni siquiera ve la lista de proyectos.
- Resuelto en el servidor, en cada petición
- Una sola consulta responde si puedes leer algo, y un proyecto al que perdiste el acceso responde exactamente igual que uno que nunca existió. Nunca se compara un rol en el navegador.
- Las claves sobreviven a las personas
- Una clave de API pertenece a la organización y nombra un proyecto, así que un trabajo de CI no se rompe el día en que la persona que la creó cambia de equipo.
- Retirar funciona
- Revocar una clave surte efecto en la siguiente petición. Cerrar sesión en todos los dispositivos es una sola acción. Desconectar GitHub invalida las sesiones que llevaban su token en lugar de dejarlas funcionando hasta que caduquen.
Apúntalo a un repo. Lee el manual que no escribiste.
Conecta en tres minutos. Desconecta con un clic.