truthmark/docs/readmes/README.es.md

Truthmark

Tus agentes escriben código. Truthmark mantiene documentación orientada a humanos y revisable en Git.

🇺🇸 English | 🇨🇳 简体中文 | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇩🇪 Deutsch | 🇫🇷 Français | 🇪🇸 Español | 🇧🇷 Português | 🇷🇺 Русский | 🇸🇦 العربية | 🇮🇹 Italiano | 🇵🇱 Polski | 🇹🇷 Türkçe | 🇻🇳 Tiếng Việt | 🇮🇩 Bahasa Indonesia | 🇬🇷 Ελληνικά

🚀 Inicio rápido: ejecutarlo localmente en cinco minutos

Ejecuta esto dentro del repositorio Git que quieres que Truthmark gestione:

cd /path/to/your-repo
npm install -g truthmark
truthmark config

Activa el host de IA que realmente usas. Las configuraciones nuevas son neutrales respecto al host, así que añade una lista platforms de nivel superior a .truthmark/config.yml antes de la inicialización:

version: 2
platforms:
  - codex        # or: claude-code, github-copilot, opencode, antigravity, cursor
truthmark:
  workspace: docs/truthmark
  generated:
    portal:
      enabled: false

Después instala los documentos de verdad locales del repositorio, el enrutamiento y las instrucciones para hosts de IA:

truthmark init
truthmark check
git diff

Ahora prueba la ruta de adopción más común: documentar un comportamiento existente a partir del código y las pruebas. En tu host de codificación con IA, pídele al workflow instalado:

/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts

Después de eso, normalmente los usuarios no deberían invocar Truth Sync directamente. Sigue programando mediante tu host de IA; las instrucciones instaladas en el repositorio le dicen al agente que ejecute las pruebas pertinentes y realice la revisión de Truth Sync antes de la entrega cuando haya cambios de código funcional. Tú revisas el diff de código resultante junto con el diff de los documentos de verdad.

Si solo quieres validación por CLI y todavía no quieres workflows de IA específicos de un host, deja platforms omitido y ejecuta truthmark init && truthmark check; puedes añadir una plataforma más tarde y volver a ejecutar truthmark init.

💡 El problema: la brecha de documentación de la IA

Los agentes de codificación con IA son increíbles escribiendo código rápidamente. Pero esa velocidad crea un nuevo modo de fallo peligroso: la historia del repositorio se desvía de la realidad.

• El comportamiento se pierde en historiales de chat efímeros.
• Los documentos de arquitectura se quedan atrás rápidamente.
• Las decisiones de producto desaparecen después de la entrega.
• Los revisores de código acaban examinando diffs de código sin procesar, sin entender el «por qué».
• Cada nueva sesión de IA se ve obligada a redescubrir desde cero la verdad de tu repositorio.

🎯 La solución: Truthmark

Truthmark instala en tu repositorio una capa de workflow nativa de Git. Arregla la parte del desarrollo con IA que normalmente se rompe: ayudar a que la documentación permanezca alineada con el código.

En lugar de esperar que humanos y agentes de IA recuerden actualizar la documentación, Truthmark convierte la documentación en un hábito sistemático y revisable dentro de tu propio repositorio.

✨ Por qué Truthmark es único

Truthmark no es simplemente otra herramienta de documentación. Está profundamente integrado en el workflow de IA:

• 🚫 Sin dependencia de proveedor: no hay servicios alojados, bases de datos ocultas ni servidores adicionales que operar.
• 🌳 100 % nativo de Git: todo vive en tu repositorio. La verdad se mueve con tu rama.
• 🤝 Contrato propiedad de humanos y seguido por agentes: Los mantenedores poseen el contrato del repositorio; los agentes siguen las instrucciones instaladas mientras programan.
• ✅ Confianza mediante verificación: el trabajo de la IA resulta más fácil de confiar porque el trabajo que cambia comportamiento incluye una decisión o un diff de documento de verdad revisable por humanos.

🔄 Cómo funciona

Cuando un agente de IA modifica tu código, el trabajo no ha terminado. Truthmark instala una protección de workflow al final de la tarea que los agentes siguen antes de la entrega:

1. 💻 Código: el agente modifica código funcional.
2. 🧪 Prueba: se ejecutan las pruebas pertinentes.
3. 🔍 Comprobación: Truthmark revisa la documentación mapeada como parte de la revisión de cierre instalada.
4. 📝 Documentación: el agente actualiza los docs cuando la verdad del repositorio ha cambiado.
5. 👀 Revisión: una persona revisa el diff de código + el diff de verdad.

🛠 Cómo interactúas con Truthmark

Truthmark tiene un contrato local del repositorio y dos formas de usarlo.

Las personas instalan y validan el contrato

Los mantenedores y CI usan la CLI:

• truthmark config - crea la configuración inicial.
• truthmark init - instala o actualiza el enrutamiento, los andamios de documentos de verdad y las instrucciones para hosts de IA.
• truthmark check - valida la verdad del repositorio desde la terminal.

Los agentes siguen el contrato mientras programan

Truthmark instala instrucciones locales del repositorio para hosts de codificación con IA compatibles, como Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity y Cursor.

El ciclo normal es simple:

1. Pide a tu agente un cambio de código o que documente un comportamiento existente.
2. Las instrucciones instaladas le dicen al agente cuándo probar, cuándo actualizar documentos de verdad y cuándo detenerse para revisión humana.
3. Revisas diffs Git normales: código más cualquier cambio en documentos de verdad.

Las solicitudes de agente iniciadas por el usuario son deliberadamente pocas:

• /truthmark-document - documenta comportamiento implementado existente a partir de código y tests.
• /truthmark-realize - implementa código a partir de documentos de verdad existentes.
• /truthmark-check - audita la verdad del repositorio.

Truth Sync no es la forma habitual de iniciar trabajo; es la revisión de cierre después de cambios funcionales de código. Truth Structure no es un comando cotidiano; repara enrutamiento o propiedad solo cuando eso bloquea el trabajo.

Lo que obtienes

Capacidad	Qué hace
Verdad nativa de Git	Mantiene la verdad del repositorio en Markdown y configuración versionados.
Documentación con alcance de rama	La verdad se mueve con la rama en lugar de vivir en una sesión privada.
CLI humana	Da a los mantenedores comandos de configuración, actualización, validación e inspección.
Guía de agente instalada	Indica a los agentes de codificación cuándo documentar, probar, sincronizar verdad, auditar o detenerse para revisión.
Enrutamiento explícito	Mapea áreas de código a documentos de verdad canónicos.
Entregas revisables	Produce diffs Git ordinarios tanto para el código como para los documentos de verdad.
Operación local-first	No requiere servicio alojado, demonio, base de datos ni servidor MCP.
Límites de escritura más seguros	Separa workflows code-first, doc-first, read-only y doc-only.
Validación	Informa problemas de enrutamiento, autoridad, frontmatter, enlaces, superficies generadas, alcance de rama, frescura y cobertura.
Portal opcional	Genera, cuando se activa y solicita explícitamente, un sitio estático HTML versionado a partir de documentos de verdad Markdown.

Panorama visual

Funciones: lo que instala Truthmark y cómo se divide la superficie de workflow.

Posición: dónde encaja Truthmark en relación con prompts, memoria y workflows de especificación.

Flujo de sincronización: cómo Truth Sync cierra los cambios de código normales antes de la entrega.

Por qué los equipos lo adoptan

Truthmark es para equipos que ya saben que los agentes de IA pueden generar código.

El siguiente problema es la gobernanza.

No la gobernanza como ceremonia. Gobernanza como una pregunta sencilla:

Después de este cambio asistido por IA, ¿el repositorio sigue diciendo la verdad?

Truthmark ayuda a los equipos a responder con archivos versionados, enrutamiento explícito y diffs revisables.

Es útil cuando necesitas:

• menos deriva de documentación
• mejores entregas
• verdad de producto específica de la rama
• documentación duradera de arquitectura y API
• propiedad explícita entre docs y código
• límites de escritura de agentes más seguros
• documentación revisable en lugar de memoria oculta
• guía de agente que sigue funcionando desde archivos versionados del repositorio

Dónde encaja Truthmark

Truthmark no reemplaza prompts, memoria, especificaciones, pruebas ni revisión de código.

Les da a esos workflows un lugar duradero donde aterrizar en Git.

Necesidad	Mejor opción
Mejor salida de una sesión de agente	Mejor prompt
Continuidad personal o a nivel de sesión	Herramienta de memoria
Trabajo de funcionalidad con plan primero	Workflow de especificación
Verdad con alcance de rama que viaja con el código	Truthmark
Validar la corrección del comportamiento	Pruebas y revisión
Revisar cambios de documentación asistidos por IA	Truthmark más revisión Git

El carril de Truthmark es estrecho por diseño:

make repository truth explicit
route it to code
instalar guía de agente alrededor de ella
keep the result reviewable in Git

Profundizar

El README es el escaparate: contexto rápido, inicio rápido y el modelo mental central.

Para uso comando por comando, comparaciones de superficies, detalles de plataformas compatibles, configuración, enrutamiento, Portal y ejemplos, lee la guía de usuario de Truthmark.

Estado del proyecto

La versión actual proporciona:

• comandos CLI locales para config, init, check, index, impact y estado de workflows
• instrucciones de agente locales del repositorio generadas para Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity y Cursor
• diagnósticos de enrutamiento, autoridad, frontmatter, enlaces, frescura, superficies generadas, alcance de rama y cobertura
• documentos de verdad con alcance de rama y artefactos derivados de inteligencia del repositorio

Documentación

• Guía de usuario
• Índice de docs
• Vista general de arquitectura
• Contratos de API y CLI
• Guía de mantenimiento de la verdad del repositorio

Para comandos de desarrollo local y contribución, consulta CONTRIBUTING.md.

Límites de diseño

Truthmark es intencionadamente pequeño: local, versionado, con alcance de rama y revisable.

No es un servicio alojado, servidor MCP, base de datos vectorial, capa de memoria oculta, producto de aplicación de CI ni motor autónomo de reescritura de código. Ayuda a que la verdad del repositorio permanezca visible; no reemplaza pruebas, revisión de código ni juicio humano.

Licencia

MIT. Consulta LICENSE.

Eliminación segura

Use truthmark uninstall --dry-run para revisar las superficies de host generadas exactas, luego truthmark uninstall --apply para eliminarlas. Los truth creados, la configuración, las plantillas, la salida de Portal, los archivos de Gemini y los archivos de usuario no relacionados se conservan; quite una instalación global de npm por separado con su gestor de paquetes.