Jalankan ini di dalam repositori Git yang ingin Anda kelola dengan Truthmark:
```bash
cd /path/to/your-repo
npm install -g truthmark
truthmark config
```
Aktifkan host AI yang benar-benar Anda gunakan. Konfigurasi baru bersifat netral terhadap host, jadi tambahkan daftar `platforms` tingkat atas ke `.truthmark/config.yml` sebelum inisialisasi:
Kemudian pasang dokumen kebenaran lokal repositori, perutean, dan permukaan alur kerja agen:
```bash
truthmark init
truthmark check
git diff
```
Sekarang coba jalur adopsi yang paling umum: dokumentasikan satu perilaku yang sudah ada dari kode dan pengujian. Di host pengodean AI Anda, minta alur kerja yang terpasang:
```text
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
```
Setelah itu, pengguna biasanya tidak perlu memanggil Truth Sync secara langsung. Teruslah membuat kode melalui host AI Anda; instruksi repositori yang terpasang memberi tahu agen untuk menjalankan pengujian yang relevan dan melakukan tinjauan Truth Sync sebelum serah terima ketika kode fungsional berubah. Anda meninjau diff kode yang dihasilkan beserta diff dokumen truth.
Jika Anda hanya menginginkan validasi CLI dan belum menginginkan alur kerja AI khusus host, biarkan `platforms` tidak dicantumkan dan jalankan `truthmark init && truthmark check`; Anda dapat menambahkan platform nanti dan menjalankan ulang `truthmark init`.
## 💡 Masalah: kesenjangan dokumentasi AI
Agen pengodean AI luar biasa dalam menulis kode dengan cepat. Namun kecepatan ini menciptakan mode kegagalan baru yang berbahaya: **cerita repositori menyimpang dari kenyataan.**
* Perilaku hilang dalam riwayat chat yang sementara.
* Dokumen arsitektur cepat tertinggal.
* Keputusan produk lenyap setelah serah terima.
* Peninjau kode dibiarkan memeriksa diff kode mentah tanpa memahami "mengapa".
* Setiap sesi AI baru dipaksa menemukan ulang kebenaran repositori Anda dari awal.
## 🎯 Solusi: Truthmark
**Truthmark** memasang lapisan alur kerja native Git ke dalam repositori Anda. Ini memperbaiki bagian pengembangan AI yang biasanya rusak: membantu dokumentasi tetap selaras dengan kode.
Alih-alih berharap manusia dan agen AI ingat memperbarui dokumen, Truthmark menjadikan dokumentasi sebagai kebiasaan sistematis dan dapat ditinjau langsung di dalam repositori Anda.
### ✨ Mengapa Truthmark unik
Truthmark bukan sekadar alat dokumentasi lain. Ia terintegrasi mendalam ke dalam alur kerja AI:
* **🚫 Tanpa ketergantungan vendor:** Tidak ada layanan ter-host, tidak ada basis data tersembunyi, tidak ada server tambahan untuk dioperasikan.
* **🌳 100% native Git:** Semuanya hidup di repositori Anda. Kebenaran bergerak bersama branch Anda.
* **🤝 Kontrak yang dimiliki manusia dan diikuti agen:** Pemelihara memiliki kontrak repositori; agen mengikuti instruksi yang terpasang saat membuat kode.
* **✅ Kepercayaan melalui verifikasi:** Pekerjaan AI menjadi lebih mudah dipercaya karena pekerjaan yang mengubah perilaku menyertakan keputusan atau diff dokumen kebenaran yang dapat ditinjau manusia.
## 🔄 Cara kerjanya
Ketika agen AI memodifikasi kode Anda, pekerjaannya belum selesai. Truthmark memasang penjaga alur kerja saat penyelesaian yang diikuti agen sebelum serah terima:
Truthmark memasang instruksi lokal repositori untuk host pengodean AI yang didukung seperti Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, dan Cursor.
Alur normalnya sederhana:
1. Minta agen Anda melakukan perubahan kode, atau minta ia mendokumentasikan perilaku yang sudah ada.
2. Instruksi yang terpasang memberi tahu agen kapan harus menguji, kapan memperbarui dokumen kebenaran, dan kapan berhenti untuk tinjauan manusia.
3. Anda meninjau diff Git biasa: kode plus perubahan dokumen kebenaran apa pun.
Permintaan agen yang dimulai pengguna sengaja dibuat sedikit:
*`/truthmark-document` - mendokumentasikan perilaku terimplementasi yang sudah ada dari kode dan pengujian.
*`/truthmark-realize` - mengimplementasikan kode dari dokumen kebenaran yang sudah ada.
| Perutean eksplisit | Memetakan area kode ke dokumen kebenaran kanonis. |
| Serah terima yang dapat ditinjau | Menghasilkan diff Git biasa untuk kode maupun dokumen kebenaran. |
| Operasi lokal terlebih dahulu | Tidak membutuhkan layanan ter-host, daemon, basis data, atau server MCP. |
| Batas tulis yang lebih aman | Memisahkan alur kerja code-first, doc-first, read-only, dan doc-only. |
| Validasi | Melaporkan masalah perutean, otoritas, frontmatter, tautan, permukaan yang dihasilkan, cakupan branch, kesegaran, dan coverage. |
| Portal opsional | Menghasilkan situs presentasi HTML statis yang di-commit dari dokumen kebenaran Markdown ketika diaktifkan dan diminta secara eksplisit. |
README adalah etalase: konteks cepat, mulai cepat, dan model mental inti.
Untuk penggunaan per perintah, perbandingan permukaan, detail platform yang didukung, konfigurasi, perutean, Portal, dan contoh, baca [Panduan Pengguna Truthmark](../user-guide.md).
## Status proyek
Rilis saat ini menyediakan:
- perintah CLI lokal untuk config, init, check, index, impact, dan status alur kerja
Untuk perintah pengembangan lokal dan kontribusi, lihat [CONTRIBUTING.md](../../CONTRIBUTING.md).
## Batas desain
Truthmark sengaja kecil: lokal, di-commit, berlingkup branch, dan dapat ditinjau.
Ini bukan layanan ter-host, server MCP, basis data vektor, lapisan memori tersembunyi, produk penegakan CI, atau mesin penulisan ulang kode otonom. Ini membantu kebenaran repositori tetap terlihat; tidak menggantikan pengujian, tinjauan kode, atau penilaian manusia.
