truthmark/docs/readmes/README.el.md

Truthmark

Οι πράκτορές σας γράφουν κώδικα. Το Truthmark διατηρεί τεκμηρίωση προσανατολισμένη στον άνθρωπο και ελέγξιμη μέσω Git.

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

🚀 Γρήγορη εκκίνηση: τοπική εκτέλεση σε πέντε λεπτά

Εκτελέστε το μέσα στο αποθετήριο Git που θέλετε να διαχειρίζεται το Truthmark:

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

Ενεργοποιήστε τον AI host που πραγματικά χρησιμοποιείτε. Οι νέες ρυθμίσεις είναι ουδέτερες ως προς τον host, οπότε προσθέστε μια λίστα platforms στο ανώτερο επίπεδο του .truthmark/config.yml πριν από την αρχικοποίηση:

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

Έπειτα εγκαταστήστε τοπικά τα έγγραφα αλήθειας του αποθετηρίου, τη δρομολόγηση και τις επιφάνειες ροής εργασίας πρακτόρων:

truthmark init
truthmark check
git diff

Τώρα δοκιμάστε την πιο συνηθισμένη διαδρομή υιοθέτησης: τεκμηριώστε μια υπάρχουσα συμπεριφορά από κώδικα και tests. Στον AI coding host σας, ζητήστε από την εγκατεστημένη ροή εργασίας:

/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 σας.
• 🤝 Αρχιτεκτονική δύο επιφανειών: Διαχωρίζει καθαρά τα εργαλεία που χρησιμοποιούν οι άνθρωποι για τη διαχείριση του repo από τις ροές εργασίας που χρησιμοποιούν οι AI agents για να γράφουν κώδικα.
• ✅ Εμπιστοσύνη μέσω επαλήθευσης: Η εργασία AI γίνεται ευκολότερο να εμπιστευτεί, επειδή η εργασία που αλλάζει συμπεριφορά περιλαμβάνει μια απόφαση ή ένα diff εγγράφου αλήθειας που μπορεί να ελεγχθεί από άνθρωπο.

🔄 Πώς λειτουργεί

Όταν ένας AI agent τροποποιεί τον κώδικά σας, η δουλειά δεν έχει τελειώσει. Το Truthmark εγκαθιστά έναν φραγμό ροής εργασίας στο τέλος, τον οποίο ακολουθούν οι πράκτορες πριν από την παράδοση:

1. 💻 Κώδικας: Ο πράκτορας τροποποιεί λειτουργικό κώδικα.
2. 🧪 Test: Εκτελούνται τα σχετικά tests.
3. 🔍 Έλεγχος: Το Truth Sync ελέγχει την αντιστοιχισμένη τεκμηρίωση όταν εκτελείται η εγκατεστημένη ροή εργασίας.
4. 📝 Τεκμηρίωση: Τα docs ενημερώνονται από τον πράκτορα όταν αλλάζει η αλήθεια του αποθετηρίου.
5. 👀 Ανασκόπηση: Ένας άνθρωπος ανασκοπεί το code diff + το diff αλήθειας.

🛠 Δύο επιφάνειες, ένα σύστημα αλήθειας

Το Truthmark χωρίζεται σκόπιμα σε δύο ξεχωριστές επιφάνειες για να εξυπηρετεί τόσο τους ανθρώπους συντηρητές όσο και τους AI agents.

1. 🧑‍💻 Το ανθρώπινο CLI (συντηρητές & CI)

Χρησιμοποιείται από developers για τη ρύθμιση, τη διαμόρφωση και την επικύρωση του αποθετηρίου.

• truthmark config - Δημιουργεί την αρχική σας διαμόρφωση.
• truthmark init - Εγκαθιστά την απαραίτητη δρομολόγηση, τα scaffolds και τις οδηγίες.
• truthmark check - Επικυρώνει τα τεχνουργήματα αλήθειας από το terminal.

2. 🤖 Οι ροές εργασίας που απευθύνονται στην AI (πράκτορες)

Το Truthmark εγκαθιστά native skills, prompts και εντολές που καταλαβαίνουν οι υποστηριζόμενοι AI hosts (όπως Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity και Cursor). Αυτά δεν είναι shell commands· είναι σημεία εισόδου ροών εργασίας για την AI.

• /truthmark-sync - Η ροή εργασίας στο τέλος που ακολουθούν οι πράκτορες μετά από αλλαγές λειτουργικού κώδικα· δεν είναι κανονική εντολή εκκίνησης χρήστη.
• /truthmark-document - Δημιουργεί docs για υπάρχον μη τεκμηριωμένο κώδικα.
• /truthmark-structure - Οργανώνει ευρείες περιοχές αποθετηρίου σε συγκεκριμένους τομείς.
• /truthmark-realize - Ανάπτυξη με τεκμηρίωση πρώτα: Διαβάζει αρχιτεκτονικά docs και δημιουργεί κώδικα που ταιριάζει.
• /truthmark-check - Έλεγχος της αλήθειας του αποθετηρίου που καθοδηγείται από πράκτορα.

Τι παίρνετε

Δυνατότητα	Τι κάνει
Git-native αλήθεια	Διατηρεί την αλήθεια του αποθετηρίου σε committed Markdown και config.
Τεκμηρίωση με scope branch	Η αλήθεια κινείται με το branch αντί να ζει σε ιδιωτική session.
Ανθρώπινο CLI	Δίνει στους συντηρητές εντολές setup, refresh, validation και inspection.
Ροές εργασίας για AI	Δίνει στους πράκτορες host-native ροές εργασίας για sync, documentation, structure, realization και audit.
Ρητή δρομολόγηση	Αντιστοιχίζει περιοχές κώδικα σε κανονικά έγγραφα αλήθειας.
Ελέγξιμες παραδόσεις	Παράγει συνηθισμένα 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 και πώς χωρίζεται η επιφάνεια ροής εργασίας.

Θέση: πού εντάσσεται το Truthmark σε σχέση με prompts, memory και spec workflows.

Ροή συγχρονισμού: πώς το Truth Sync κλείνει τις κανονικές αλλαγές κώδικα πριν από την παράδοση.

Γιατί το υιοθετούν οι ομάδες

Το Truthmark είναι για ομάδες που ήδη γνωρίζουν ότι οι AI agents μπορούν να παράγουν κώδικα.

Το επόμενο πρόβλημα είναι η διακυβέρνηση.

Όχι διακυβέρνηση ως τελετουργία. Διακυβέρνηση ως μια απλή ερώτηση:

Μετά από αυτή την AI-assisted αλλαγή, λέει ακόμη το αποθετήριο την αλήθεια;

Το Truthmark βοηθά τις ομάδες να απαντήσουν σε αυτό με committed files, ρητή δρομολόγηση και ελέγξιμα diffs.

Είναι χρήσιμο όταν χρειάζεστε:

• λιγότερη απόκλιση τεκμηρίωσης
• καλύτερες παραδόσεις
• αλήθεια προϊόντος ειδική ανά branch
• ανθεκτική τεκμηρίωση αρχιτεκτονικής και API
• ρητή ιδιοκτησία μεταξύ docs και code
• ασφαλέστερα όρια εγγραφής πρακτόρων
• ελέγξιμη τεκμηρίωση αντί για κρυφή μνήμη
• AI workflows που συνεχίζουν να λειτουργούν από committed repo files

Πού ταιριάζει το 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 είναι σκόπιμα στενή:

make repository truth explicit
route it to code
install agent workflows around it
keep the result reviewable in Git

Πηγαίνετε βαθύτερα

Το README είναι η βιτρίνα: γρήγορο πλαίσιο, γρήγορη εκκίνηση και το βασικό νοητικό μοντέλο.

Για χρήση ανά εντολή, συγκρίσεις επιφανειών, λεπτομέρειες υποστηριζόμενων πλατφορμών, διαμόρφωση, δρομολόγηση, Portal και παραδείγματα, διαβάστε τον Οδηγό χρήστη Truthmark.

Κατάσταση έργου

Η τρέχουσα έκδοση παρέχει:

• τοπικές CLI commands για config, init, check, index, impact και workflow status
• generated AI workflow surfaces για Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity και Cursor
• diagnostics για route, authority, frontmatter, link, freshness, generated-surface, branch-scope και coverage
• έγγραφα αλήθειας με scope branch και παράγωγα τεχνουργήματα ευφυΐας αποθετηρίου

Τεκμηρίωση

• Οδηγός χρήστη
• Ευρετήριο docs
• Επισκόπηση αρχιτεκτονικής
• Συμβάσεις API και CLI
• Οδηγός συντήρησης αλήθειας αποθετηρίου

Για εντολές τοπικής ανάπτυξης και συνεισφοράς, δείτε το CONTRIBUTING.md.

Όρια σχεδιασμού

Το Truthmark είναι σκόπιμα μικρό: τοπικό, committed, με scope branch και ελέγξιμο.

Δεν είναι hosted service, MCP server, vector database, κρυφό memory layer, προϊόν επιβολής CI ή αυτόνομη μηχανή επανεγγραφής κώδικα. Βοηθά την αλήθεια του αποθετηρίου να παραμένει ορατή· δεν αντικαθιστά tests, code review ή ανθρώπινη κρίση.

Άδεια

MIT. Δείτε LICENSE.