truthmark 2.2.3 → 2.2.5

package/docs/readmes/README.el.md

@@ -0,0 +1,225 @@
+# Truthmark
+
+**Οι πράκτορές σας γράφουν κώδικα. Το Truthmark διατηρεί τεκμηρίωση προσανατολισμένη στον άνθρωπο και ελέγξιμη μέσω Git.**
+
+[🇺🇸 English](../../README.md) | [🇨🇳 简体中文](README.zh.md) | [🇯🇵 日本語](README.ja.md) | [🇰🇷 한국어](README.ko.md) | [🇩🇪 Deutsch](README.de.md) | [🇫🇷 Français](README.fr.md) | [🇪🇸 Español](README.es.md) | [🇧🇷 Português](README.pt.md) | [🇷🇺 Русский](README.ru.md) | [🇸🇦 العربية](README.ar.md) | [🇮🇹 Italiano](README.it.md) | [🇵🇱 Polski](README.pl.md) | [🇹🇷 Türkçe](README.tr.md) | [🇻🇳 Tiếng Việt](README.vi.md) | [🇮🇩 Bahasa Indonesia](README.id.md) | [🇬🇷 Ελληνικά](README.el.md)
+
+![Πανό Truthmark](../assets/truthmark-banner.png)
+
+## 🚀 Γρήγορη εκκίνηση: τοπική εκτέλεση σε πέντε λεπτά
+
+Εκτελέστε το μέσα στο αποθετήριο Git που θέλετε να διαχειρίζεται το Truthmark:
+
+```bash
+cd /path/to/your-repo
+npm install -g truthmark
+truthmark config
+```
+
+Ενεργοποιήστε τον AI host που πραγματικά χρησιμοποιείτε. Οι νέες ρυθμίσεις είναι ουδέτερες ως προς τον host, οπότε προσθέστε μια λίστα `platforms` στο ανώτερο επίπεδο του `.truthmark/config.yml` πριν από την αρχικοποίηση:
+
+```yaml
+version: 2
+platforms:
+  - codex        # or: claude-code, github-copilot, opencode, antigravity, cursor
+truthmark:
+  workspace: docs/truthmark
+  generated:
+    portal:
+      enabled: false
+```
+
+Έπειτα εγκαταστήστε τοπικά τα έγγραφα αλήθειας του αποθετηρίου, τη δρομολόγηση και τις επιφάνειες ροής εργασίας πρακτόρων:
+
+```bash
+truthmark init
+truthmark check
+git diff
+```
+
+Τώρα δοκιμάστε την πιο συνηθισμένη διαδρομή υιοθέτησης: τεκμηριώστε μια υπάρχουσα συμπεριφορά από κώδικα και tests. Στον AI coding host σας, ζητήστε από την εγκατεστημένη ροή εργασίας:
+
+```text
+/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
+```
+
+Μετά από αυτό, οι χρήστες συνήθως δεν πρέπει να καλούν απευθείας το Truth Sync. Συνεχίστε να γράφετε κώδικα μέσω του AI host σας· οι εγκατεστημένες οδηγίες του αποθετηρίου λένε στον πράκτορα να εκτελεί τα σχετικά tests και να πραγματοποιεί την ανασκόπηση Truth Sync πριν από την παράδοση όταν αλλάζει λειτουργικός κώδικας. Εσείς ανασκοπείτε το προκύπτον code diff μαζί με το truth-doc diff.
+
+Αν θέλετε μόνο επικύρωση CLI και δεν θέλετε ακόμη host-specific AI workflows, αφήστε το `platforms` εκτός και εκτελέστε `truthmark init && truthmark check`· μπορείτε να προσθέσετε πλατφόρμα αργότερα και να εκτελέσετε ξανά `truthmark init`.
+
+## 💡 Το πρόβλημα: το κενό τεκμηρίωσης της AI
+
+Οι AI coding agents είναι απίστευτοι στο να γράφουν κώδικα γρήγορα. Όμως αυτή η ταχύτητα δημιουργεί έναν επικίνδυνο νέο τρόπο αποτυχίας: **η ιστορία του αποθετηρίου απομακρύνεται από την πραγματικότητα.**
+
+* Η συμπεριφορά χάνεται σε εφήμερα ιστορικά συνομιλιών.
+* Τα έγγραφα αρχιτεκτονικής μένουν γρήγορα πίσω.
+* Οι αποφάσεις προϊόντος εξαφανίζονται μετά την παράδοση.
+* Οι reviewers κώδικα μένουν να εξετάζουν ωμά code diffs χωρίς να καταλαβαίνουν το «γιατί».
+* Κάθε νέα AI session αναγκάζεται να ανακαλύψει ξανά την αλήθεια του αποθετηρίου σας από την αρχή.
+
+## 🎯 Η λύση: Truthmark
+
+Το **Truthmark** εγκαθιστά ένα Git-native επίπεδο ροής εργασίας μέσα στο αποθετήριό σας. Διορθώνει το μέρος της ανάπτυξης με AI που συνήθως σπάει: βοηθά την τεκμηρίωση να παραμένει ευθυγραμμισμένη με τον κώδικα.
+
+Αντί να ελπίζετε ότι οι άνθρωποι και οι AI agents θα θυμηθούν να ενημερώσουν τα docs, το Truthmark κάνει την τεκμηρίωση μια συστηματική, ελέγξιμη συνήθεια ακριβώς μέσα στο repo σας.
+
+### ✨ Γιατί το Truthmark είναι μοναδικό
+
+Το Truthmark δεν είναι απλώς άλλο ένα εργαλείο τεκμηρίωσης. Είναι βαθιά ενσωματωμένο στη ροή εργασίας AI:
+
+* **🚫 Μηδενικό κλείδωμα σε προμηθευτή:** Καμία hosted υπηρεσία, καμία κρυφή βάση δεδομένων, κανένας επιπλέον server προς λειτουργία.
+* **🌳 100% Git-native:** Όλα ζουν στο αποθετήριό σας. Η αλήθεια κινείται μαζί με το branch σας.
+* **🤝 Συμβόλαιο που ανήκει σε ανθρώπους και ακολουθείται από agents:** Οι συντηρητές κατέχουν το συμβόλαιο του αποθετηρίου· οι agents ακολουθούν τις εγκατεστημένες οδηγίες ενώ γράφουν κώδικα.
+* **✅ Εμπιστοσύνη μέσω επαλήθευσης:** Η εργασία AI γίνεται ευκολότερο να εμπιστευτεί, επειδή η εργασία που αλλάζει συμπεριφορά περιλαμβάνει μια απόφαση ή ένα diff εγγράφου αλήθειας που μπορεί να ελεγχθεί από άνθρωπο.
+
+## 🔄 Πώς λειτουργεί
+
+Όταν ένας AI agent τροποποιεί τον κώδικά σας, η δουλειά δεν έχει τελειώσει. Το Truthmark εγκαθιστά έναν φραγμό ροής εργασίας στο τέλος, τον οποίο ακολουθούν οι πράκτορες πριν από την παράδοση:
+
+1. 💻 **Κώδικας:** Ο πράκτορας τροποποιεί λειτουργικό κώδικα.
+2. 🧪 **Test:** Εκτελούνται τα σχετικά tests.
+3. 🔍 **Έλεγχος:** Το Truthmark ελέγχει τη χαρτογραφημένη τεκμηρίωση ως μέρος της εγκατεστημένης τελικής ανασκόπησης.
+4. 📝 **Τεκμηρίωση:** Τα docs ενημερώνονται από τον πράκτορα όταν αλλάζει η αλήθεια του αποθετηρίου.
+5. 👀 **Ανασκόπηση:** Ένας άνθρωπος ανασκοπεί το *code diff* + το *diff αλήθειας*.
+
+## 🛠 Πώς αλληλεπιδράτε με το Truthmark
+
+Το Truthmark έχει ένα repo-local συμβόλαιο και δύο τρόπους χρήσης του.
+
+### Οι άνθρωποι εγκαθιστούν και επικυρώνουν το συμβόλαιο
+
+Οι συντηρητές και το CI χρησιμοποιούν το CLI:
+
+* `truthmark config` - δημιουργεί την αρχική διαμόρφωση.
+* `truthmark init` - εγκαθιστά ή ανανεώνει routing, truth-doc scaffolds και οδηγίες για AI hosts.
+* `truthmark check` - επικυρώνει την αλήθεια του αποθετηρίου από το τερματικό.
+
+### Οι agents ακολουθούν το συμβόλαιο ενώ γράφουν κώδικα
+
+Το Truthmark εγκαθιστά repo-local οδηγίες για υποστηριζόμενους AI coding hosts όπως Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity και Cursor.
+
+Ο κανονικός κύκλος είναι απλός:
+
+1. Ζητήστε από τον agent αλλαγή κώδικα ή τεκμηρίωση υπάρχουσας συμπεριφοράς.
+2. Οι εγκατεστημένες οδηγίες λένε στον agent πότε να δοκιμάσει, πότε να ενημερώσει truth docs και πότε να σταματήσει για ανθρώπινη ανασκόπηση.
+3. Εσείς ελέγχετε κανονικά Git diffs: κώδικα και τυχόν αλλαγές σε truth docs.
+
+Τα user-started αιτήματα προς agents είναι σκόπιμα λίγα:
+
+* `/truthmark-document` - τεκμηριώνει υπάρχουσα υλοποιημένη συμπεριφορά από κώδικα και tests.
+* `/truthmark-realize` - υλοποιεί κώδικα από υπάρχοντα truth docs.
+* `/truthmark-check` - ελέγχει την αλήθεια του αποθετηρίου.
+
+Το Truth Sync δεν είναι ο συνηθισμένος τρόπος έναρξης εργασίας· είναι η τελική ανασκόπηση μετά από λειτουργικές αλλαγές κώδικα.
+Το Truth Structure δεν είναι καθημερινή εντολή· επισκευάζει routing ή ownership μόνο όταν αυτό μπλοκάρει την εργασία.
+
+## Τι παίρνετε
+
+| Δυνατότητα | Τι κάνει |
+| --- | --- |
+| Git-native αλήθεια | Διατηρεί την αλήθεια του αποθετηρίου σε committed Markdown και config. |
+| Τεκμηρίωση με scope branch | Η αλήθεια κινείται με το branch αντί να ζει σε ιδιωτική session. |
+| Ανθρώπινο CLI | Δίνει στους συντηρητές εντολές setup, refresh, validation και inspection. |
+| Εγκατεστημένη καθοδήγηση agent | Λέει στους coding agents πότε να τεκμηριώσουν, να δοκιμάσουν, να συγχρονίσουν truth, να κάνουν audit ή να σταματήσουν για review. |
+| Ρητή δρομολόγηση | Αντιστοιχίζει περιοχές κώδικα σε κανονικά έγγραφα αλήθειας. |
+| Ελέγξιμες παραδόσεις | Παράγει συνηθισμένα Git diffs τόσο για κώδικα όσο και για έγγραφα αλήθειας. |
+| Local-first λειτουργία | Δεν απαιτεί hosted service, daemon, βάση δεδομένων ή MCP server. |
+| Ασφαλέστερα όρια εγγραφής | Διαχωρίζει code-first, doc-first, read-only και doc-only workflows. |
+| Επικύρωση | Αναφέρει ζητήματα routing, authority, frontmatter, links, generated surfaces, branch scope, freshness και coverage. |
+| Προαιρετικό Portal | Δημιουργεί ένα committed στατικό HTML presentation site από έγγραφα αλήθειας Markdown όταν ενεργοποιηθεί και ζητηθεί ρητά. |
+
+## Οπτική επισκόπηση
+
+![Χαρακτηριστικά Truthmark](../assets/truthmark-features.png)
+
+**Χαρακτηριστικά:** τι εγκαθιστά το Truthmark και πώς χωρίζεται η επιφάνεια ροής εργασίας.
+
+![Θέση Truthmark](../assets/truthmark-position.png)
+
+**Θέση:** πού εντάσσεται το Truthmark σε σχέση με prompts, memory και spec workflows.
+
+![Ροή συγχρονισμού Truthmark](../assets/truthmark-syncflow.png)
+
+**Ροή συγχρονισμού:** πώς το Truth Sync κλείνει τις κανονικές αλλαγές κώδικα πριν από την παράδοση.
+
+## Γιατί το υιοθετούν οι ομάδες
+
+Το Truthmark είναι για ομάδες που ήδη γνωρίζουν ότι οι AI agents μπορούν να παράγουν κώδικα.
+
+Το επόμενο πρόβλημα είναι η διακυβέρνηση.
+
+Όχι διακυβέρνηση ως τελετουργία. Διακυβέρνηση ως μια απλή ερώτηση:
+
+> Μετά από αυτή την AI-assisted αλλαγή, λέει ακόμη το αποθετήριο την αλήθεια;
+
+Το Truthmark βοηθά τις ομάδες να απαντήσουν σε αυτό με committed files, ρητή δρομολόγηση και ελέγξιμα diffs.
+
+Είναι χρήσιμο όταν χρειάζεστε:
+
+- λιγότερη απόκλιση τεκμηρίωσης
+- καλύτερες παραδόσεις
+- αλήθεια προϊόντος ειδική ανά branch
+- ανθεκτική τεκμηρίωση αρχιτεκτονικής και API
+- ρητή ιδιοκτησία μεταξύ docs και code
+- ασφαλέστερα όρια εγγραφής πρακτόρων
+- ελέγξιμη τεκμηρίωση αντί για κρυφή μνήμη
+- καθοδήγηση για agents που εξακολουθεί να λειτουργεί από committed αρχεία του repo
+
+## Πού ταιριάζει το Truthmark
+
+Το Truthmark δεν αντικαθιστά prompts, memory, specs, tests ή code review.
+
+Δίνει σε αυτές τις ροές εργασίας ένα ανθεκτικό μέρος για να προσγειωθούν στο Git.
+
+| Ανάγκη | Καλύτερη επιλογή |
+| --- | --- |
+| Καλύτερη έξοδος από μία session πράκτορα | Καλύτερο prompt |
+| Προσωπική ή session-level συνέχεια | Εργαλείο μνήμης |
+| Feature work με σχέδιο πρώτα | Spec workflow |
+| Αλήθεια με scope branch που ταξιδεύει με τον κώδικα | Truthmark |
+| Επικύρωση ορθότητας συμπεριφοράς | Tests και review |
+| Ανασκόπηση AI-assisted αλλαγών τεκμηρίωσης | Truthmark μαζί με Git review |
+
+Η λωρίδα του Truthmark είναι σκόπιμα στενή:
+
+```text
+make repository truth explicit
+route it to code
+εγκατάσταση καθοδήγησης για agents γύρω από αυτή
+keep the result reviewable in Git
+```
+
+## Πηγαίνετε βαθύτερα
+
+Το README είναι η βιτρίνα: γρήγορο πλαίσιο, γρήγορη εκκίνηση και το βασικό νοητικό μοντέλο.
+
+Για χρήση ανά εντολή, συγκρίσεις επιφανειών, λεπτομέρειες υποστηριζόμενων πλατφορμών, διαμόρφωση, δρομολόγηση, Portal και παραδείγματα, διαβάστε τον [Οδηγό χρήστη Truthmark](../user-guide.md).
+
+## Κατάσταση έργου
+
+Η τρέχουσα έκδοση παρέχει:
+
+- τοπικές CLI commands για config, init, check, index, impact και workflow status
+- παραγόμενες repo-local οδηγίες για agents για Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity και Cursor
+- diagnostics για route, authority, frontmatter, link, freshness, generated-surface, branch-scope και coverage
+- έγγραφα αλήθειας με scope branch και παράγωγα τεχνουργήματα ευφυΐας αποθετηρίου
+
+## Τεκμηρίωση
+
+- [Οδηγός χρήστη](../user-guide.md)
+- [Ευρετήριο docs](../README.md)
+- [Επισκόπηση αρχιτεκτονικής](../truthmark/engineering/architecture/overview.md)
+- [Συμβάσεις API και CLI](../truthmark/engineering/contracts/config-route-and-check-contracts.md)
+- [Οδηγός συντήρησης αλήθειας αποθετηρίου](../standards/maintaining-repository-truth.md)
+
+Για εντολές τοπικής ανάπτυξης και συνεισφοράς, δείτε το [CONTRIBUTING.md](../../CONTRIBUTING.md).
+
+## Όρια σχεδιασμού
+
+Το Truthmark είναι σκόπιμα μικρό: τοπικό, committed, με scope branch και ελέγξιμο.
+
+Δεν είναι hosted service, MCP server, vector database, κρυφό memory layer, προϊόν επιβολής CI ή αυτόνομη μηχανή επανεγγραφής κώδικα. Βοηθά την αλήθεια του αποθετηρίου να παραμένει ορατή· δεν αντικαθιστά tests, code review ή ανθρώπινη κρίση.
+
+## Άδεια
+
+MIT. Δείτε [LICENSE](../../LICENSE).

package/docs/readmes/README.es.md

@@ -0,0 +1,225 @@
+# Truthmark
+
+**Tus agentes escriben código. Truthmark mantiene documentación orientada a humanos y revisable en Git.**
+
+[🇺🇸 English](../../README.md) | [🇨🇳 简体中文](README.zh.md) | [🇯🇵 日本語](README.ja.md) | [🇰🇷 한국어](README.ko.md) | [🇩🇪 Deutsch](README.de.md) | [🇫🇷 Français](README.fr.md) | [🇪🇸 Español](README.es.md) | [🇧🇷 Português](README.pt.md) | [🇷🇺 Русский](README.ru.md) | [🇸🇦 العربية](README.ar.md) | [🇮🇹 Italiano](README.it.md) | [🇵🇱 Polski](README.pl.md) | [🇹🇷 Türkçe](README.tr.md) | [🇻🇳 Tiếng Việt](README.vi.md) | [🇮🇩 Bahasa Indonesia](README.id.md) | [🇬🇷 Ελληνικά](README.el.md)
+
+![Banner de Truthmark](../assets/truthmark-banner.png)
+
+## 🚀 Inicio rápido: ejecutarlo localmente en cinco minutos
+
+Ejecuta esto dentro del repositorio Git que quieres que Truthmark gestione:
+
+```bash
+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:
+
+```yaml
+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:
+
+```bash
+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:
+
+```text
+/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 de Truthmark](../assets/truthmark-features.png)
+
+**Funciones:** lo que instala Truthmark y cómo se divide la superficie de workflow.
+
+![Posición de Truthmark](../assets/truthmark-position.png)
+
+**Posición:** dónde encaja Truthmark en relación con prompts, memoria y workflows de especificación.
+
+![Flujo de sincronización de Truthmark](../assets/truthmark-syncflow.png)
+
+**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:
+
+```text
+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](../user-guide.md).
+
+## 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](../user-guide.md)
+- [Índice de docs](../README.md)
+- [Vista general de arquitectura](../truthmark/engineering/architecture/overview.md)
+- [Contratos de API y CLI](../truthmark/engineering/contracts/config-route-and-check-contracts.md)
+- [Guía de mantenimiento de la verdad del repositorio](../standards/maintaining-repository-truth.md)
+
+Para comandos de desarrollo local y contribución, consulta [CONTRIBUTING.md](../../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](../../LICENSE).