truthmark 2.2.2 → 2.2.5

package/docs/README.md

@@ -0,0 +1,119 @@
+---
+status: active
+doc_type: index
+last_reviewed: 2026-06-20
+source_of_truth:
+  - docs/ai/repo-rules.md
+  - ../.truthmark/config.yml
+---
+
+# Truthmark Docs Index
+
+## Purpose
+
+`docs/` is Truthmark's canonical repository documentation tree. It keeps repository-wide agent rules, reusable standards, current architecture, and current lane-separated truth docs separate from onboarding copy and historical planning notes.
+
+`AGENTS.md` is the agent entry point, but it delegates repository-wide rules to [docs/ai/repo-rules.md](ai/repo-rules.md). [README.md](../README.md) remains the human onboarding and product entry point. [docs/user-guide.md](user-guide.md) owns detailed human-facing command, workflow, and configuration guidance. `.truthmark/config.yml` defines the committed hierarchy contract.
+
+## Scope
+
+This doc defines the current structure, navigation map, and maintenance expectations of Truthmark's canonical `docs/` tree.
+
+## Authority Source
+
+Repository-wide conflict order and completion policy live in [docs/ai/repo-rules.md](ai/repo-rules.md). Use this index for navigation and document-class guidance; it does not restate the full authority hierarchy.
+
+[README.md](../README.md) may help with onboarding and positioning, but it must not override current-state docs or repository-wide agent rules.
+
+## Audience Split
+
+### Agent-centric docs
+
+- `docs/ai/` for repository rules and agent onboarding
+- `docs/truthmark/routes/` for routing metadata
+- `docs/standards/` for reusable constraints and completion rules
+- `docs/truthmark/product/` for product capability promises, boundaries, and acceptance criteria
+- `docs/truthmark/engineering/` for current implementation behavior, architecture, contracts, workflows, and operations
+- `docs/architecture/` for repository-specific architecture guardrails
+- `docs/truthmark/templates/` for editable scaffold templates used to create new docs
+- `docs/truthmark/engineering/contracts/` for stable contracts the CLI exposes
+
+### Human-centric docs
+
+- [README.md](../README.md) for onboarding and positioning
+- [docs/user-guide.md](user-guide.md) for detailed usage, command, workflow, configuration, routing, Portal, and example guidance
+
+## Directory Map
+
+| Path | Type | Primary audience | Purpose |
+| --- | --- | --- | --- |
+| `docs/ai/` | agent rules | agent | Repository-wide rules and fast onboarding |
+| `docs/truthmark/routes/` | routing | both | Truth-routing metadata such as `areas.md` and `areas/**/*.md` |
+| `docs/standards/` | standard | agent | Reusable constraints, verification rules, completion gates |
+| `docs/truthmark/product/` | product truth | agent | Product capability promises, boundaries, decisions, and acceptance criteria |
+| `docs/truthmark/engineering/` | engineering truth | agent | Current implementation behavior for init, check, contracts, workflows, and operations |
+| `docs/architecture/` | architecture | agent | Repository-specific architecture guardrails |
+| `docs/truthmark/templates/` | template | both | Editable templates for scaffolded docs; templates are not Truth Sync targets |
+| `docs/user-guide.md` | guide | human | Detailed usage guide kept out of the root README so onboarding stays concise |
+
+## Frontmatter Policy
+
+Canonical docs should include frontmatter and keep these fields current:
+
+- `status`
+- `doc_type`
+- `last_reviewed`
+- `source_of_truth`
+
+## Update Rules
+
+- When repository-wide agent policy changes, update [docs/ai/repo-rules.md](ai/repo-rules.md).
+- When code-to-doc routing changes, update [docs/truthmark/routes/areas.md](truthmark/routes/areas.md) in the same change.
+- When package versions or release/version policy change, apply [docs/standards/versioning.md](standards/versioning.md) before accepting the version.
+- When PR or release source text is needed, write a `changes/` note using [docs/standards/change-notes.md](standards/change-notes.md).
+- When `truthmark init` or scaffolded files change, update the relevant truth or architecture doc, not only [README.md](../README.md).
+- When `truthmark check` changes what it validates or how it reports diagnostics, update both the current truth doc and the contract doc.
+- When major product, onboarding, install, command, positioning, or workflow behavior changes, review the root [README.md](../README.md) and update it if the human entry point would otherwise be stale.
+- Keep planning or proposal material outside the canonical current-state docs until it becomes implemented truth.
+- When current behavior changes for architecture, contracts, or lane-separated truth docs, update the owning canonical doc's `Product Decisions` and `Rationale` sections in the same change.
+- Do not keep parallel documentation trees for the same subject.
+
+## Important Truthmark-Specific Caveat
+
+New repositories should run `truthmark config` before `truthmark init` so teams can review the committed hierarchy contract before workflow surfaces are installed. The current scaffold writes a root route index plus one child route file under the configured routing root.
+
+## Recommended Reading Order
+
+### For humans
+
+1. [README.md](../README.md)
+2. [docs/user-guide.md](user-guide.md), when command or workflow detail is needed
+3. [.truthmark/config.yml](../.truthmark/config.yml)
+4. [docs/ai/repo-rules.md](ai/repo-rules.md)
+5. [docs/truthmark/engineering/architecture/overview.md](truthmark/engineering/architecture/overview.md)
+6. the relevant product, engineering, or standard doc for the area being changed
+
+### For agents
+
+1. [docs/ai/repo-rules.md](ai/repo-rules.md)
+2. [docs/ai/agent-onboarding.md](ai/agent-onboarding.md), when routing is unclear or cross-area
+3. [docs/truthmark/routes/areas.md](truthmark/routes/areas.md), when mapping code to canonical truth
+4. [docs/truthmark/engineering/architecture/overview.md](truthmark/engineering/architecture/overview.md), when changing module boundaries
+5. the relevant standard, product truth, and engineering truth docs for the task
+
+Use the route files under [docs/truthmark/routes/](truthmark/routes/) when designing areas for larger API, frontend, infrastructure, or monorepo repositories.
+
+## Maintenance Principle
+
+The canonical tree should stay small, explicit, and current. Historical notes are useful for traceability, but current behavior belongs in the nearest maintained document class, not in old plans or chat summaries.
+
+## Product Decisions
+
+- Decision (2026-05-15): The docs index owns navigation and document-class guidance for the canonical tree, while [docs/ai/repo-rules.md](ai/repo-rules.md) owns repository-wide authority order and completion policy.
+- Decision (2026-06-20): The root README is the concise human storefront. Detailed human-facing command, workflow, configuration, routing, Portal, and example material belongs in [docs/user-guide.md](user-guide.md).
+
+## Rationale
+
+Keeping the docs index focused on navigation avoids loading duplicated authority prose while still giving agents and maintainers one stable place to resolve where current truth should live before they edit deeper canonical docs.
+
+Keeping the root README concise reduces evaluator friction while preserving detailed operational guidance in a linked guide.

package/docs/readmes/README.ar.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
+```
+
+فعّل مضيف الذكاء الاصطناعي الذي تستخدمه فعلياً. تكون الإعدادات الجديدة محايدة تجاه المضيف، لذلك أضف قائمة `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
+```
+
+جرّب الآن مسار الاعتماد الأكثر شيوعاً: توثيق سلوك موجود من الكود والاختبارات. في مضيف البرمجة بالذكاء الاصطناعي، اطلب من سير العمل المثبّت:
+
+```text
+/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
+```
+
+بعد ذلك، لا ينبغي للمستخدمين عادةً استدعاء Truth Sync مباشرة. واصل البرمجة عبر مضيف الذكاء الاصطناعي؛ فتعليمات المستودع المثبّتة تطلب من الوكيل تشغيل الاختبارات ذات الصلة وتنفيذ مراجعة Truth Sync قبل التسليم عندما تتغير الشيفرة الوظيفية. أنت تراجع فرق الكود الناتج مع فرق توثيق الحقيقة.
+
+إذا كنت تريد فقط التحقق عبر CLI ولا تريد بعدُ مسارات عمل ذكاء اصطناعي خاصة بمضيف، فاترك `platforms` محذوفة وشغّل `truthmark init && truthmark check`؛ يمكنك إضافة منصة لاحقاً وإعادة تشغيل `truthmark init`.
+
+## 💡 المشكلة: فجوة توثيق الذكاء الاصطناعي
+
+وكلاء البرمجة بالذكاء الاصطناعي مذهلون في كتابة الكود بسرعة. لكن هذه السرعة تخلق نمط فشل جديداً وخطيراً: **قصة المستودع تنحرف عن الواقع.**
+
+* يضيع السلوك داخل سجلات محادثة عابرة.
+* تتأخر وثائق المعمارية بسرعة.
+* تختفي قرارات المنتج بعد التسليم.
+* يُترك مراجعو الكود لفحص فروق كود خام من دون فهم "السبب".
+* تُجبر كل جلسة ذكاء اصطناعي جديدة على إعادة اكتشاف حقيقة مستودعك من الصفر.
+
+## 🎯 الحل: Truthmark
+
+يثبّت **Truthmark** طبقة سير عمل أصلية لـ Git داخل مستودعك. وهو يعالج الجزء الذي يتعطل عادةً في تطوير الذكاء الاصطناعي: مساعدة التوثيق على البقاء متوافقاً مع الكود.
+
+بدلاً من الأمل في أن يتذكر البشر ووكلاء الذكاء الاصطناعي تحديث الوثائق، يجعل Truthmark التوثيق عادةً منهجية قابلة للمراجعة داخل مستودعك مباشرةً.
+
+### ✨ لماذا يتميّز Truthmark
+
+Truthmark ليس مجرد أداة توثيق أخرى. إنه مدمج بعمق في سير عمل الذكاء الاصطناعي:
+
+* **🚫 بلا ارتباط بمورّد واحد:** لا خدمات مستضافة، ولا قواعد بيانات مخفية، ولا خوادم إضافية للتشغيل.
+* **🌳 أصلي 100% لـ Git:** كل شيء يعيش في مستودعك. تنتقل الحقيقة مع فرعك.
+* **🤝 عقد يملكه البشر ويتبعه الوكلاء:** الصائنون يملكون عقد المستودع؛ والوكلاء يتبعون التعليمات المثبّتة أثناء البرمجة.
+* **✅ الثقة عبر التحقق:** يصبح عمل الذكاء الاصطناعي أسهل للثقة لأن العمل الذي يغيّر السلوك يتضمن قراراً أو فرقاً في توثيق الحقيقة يمكن للبشر مراجعته.
+
+## 🔄 كيف يعمل
+
+عندما يعدّل وكيل ذكاء اصطناعي كودك، لا تكون المهمة قد انتهت. يثبّت Truthmark حاجز سير عمل عند وقت الإنهاء يتبعه الوكلاء قبل التسليم:
+
+1. 💻 **الكود:** يغيّر الوكيل الكود الوظيفي.
+2. 🧪 **الاختبار:** تُشغّل الاختبارات ذات الصلة.
+3. 🔍 **التحقق:** يتحقق Truthmark من التوثيق المربوط كجزء من مراجعة وقت الإنهاء المثبّتة.
+4. 📝 **التوثيق:** يحدّث الوكيل الوثائق عندما تتغير حقيقة المستودع.
+5. 👀 **المراجعة:** يراجع إنسان *فرق الكود* + *فرق الحقيقة*.
+
+## 🛠 كيف تتفاعل مع Truthmark
+
+لدى Truthmark عقد واحد محلي داخل المستودع، وطريقتان لاستخدامه.
+
+### البشر يثبّتون العقد ويتحققون منه
+
+يستخدم الصائنون وCI واجهة CLI:
+
+* `truthmark config` - إنشاء الإعدادات الأولية.
+* `truthmark init` - تثبيت أو تحديث التوجيه، وقوالب وثائق الحقيقة، وتعليمات مضيف الذكاء الاصطناعي.
+* `truthmark check` - التحقق من حقيقة المستودع من الطرفية.
+
+### الوكلاء يتبعون العقد أثناء البرمجة
+
+يثبّت Truthmark تعليمات محلية في المستودع لمضيفي البرمجة بالذكاء الاصطناعي المدعومين مثل Codex وClaude Code وGitHub Copilot وOpenCode وAntigravity وCursor.
+
+الحلقة العادية بسيطة:
+
+1. اطلب من الوكيل تغيير كود، أو اطلب منه توثيق سلوك موجود.
+2. تخبر التعليمات المثبّتة الوكيل متى يختبر، ومتى يحدّث وثائق الحقيقة، ومتى يتوقف للمراجعة البشرية.
+3. أنت تراجع فروق Git العادية: الكود وأي تغييرات في وثائق الحقيقة.
+
+طلبات الوكيل التي يبدأها المستخدم قليلة عمداً:
+
+* `/truthmark-document` - توثيق سلوك منفّذ موجود من الكود والاختبارات.
+* `/truthmark-realize` - تنفيذ الكود من وثائق الحقيقة الموجودة.
+* `/truthmark-check` - تدقيق حقيقة المستودع.
+
+Truth Sync ليس الطريقة المعتادة لبدء العمل؛ إنه مراجعة وقت الإنهاء بعد تغييرات الكود الوظيفية.
+Truth Structure ليس أمراً يومياً؛ إنه يصلح التوجيه أو الملكية فقط عندما يعيق ذلك العمل.
+
+## ما الذي تحصل عليه
+
+| القدرة | ما تفعله |
+| --- | --- |
+| حقيقة أصلية لـ Git | تُبقي حقيقة المستودع في Markdown وإعدادات ملتزم بها. |
+| توثيق مرتبط بالفرع | تنتقل الحقيقة مع الفرع بدلاً من العيش في جلسة خاصة. |
+| CLI بشري | يمنح الصائنين أوامر للإعداد والتحديث والتحقق والفحص. |
+| إرشادات الوكيل المثبّتة | تخبر وكلاء البرمجة متى يوثقون، أو يختبرون، أو يزامنون الحقيقة، أو يدققون، أو يتوقفون للمراجعة. |
+| توجيه صريح | يربط مناطق الكود بوثائق الحقيقة المعتمدة. |
+| تسليمات قابلة للمراجعة | ينتج فروق Git عادية لكل من الكود ووثائق الحقيقة. |
+| تشغيل محلي أولاً | لا يتطلب خدمة مستضافة أو daemon أو قاعدة بيانات أو خادم MCP. |
+| حدود كتابة أكثر أماناً | يفصل بين مسارات العمل التي تبدأ بالكود، أو تبدأ بالتوثيق، أو للقراءة فقط، أو للتوثيق فقط. |
+| التحقق | يبلّغ عن مشكلات التوجيه والسلطة وfrontmatter والروابط والأسطح المولّدة ونطاق الفرع والحداثة والتغطية. |
+| Portal اختياري | يولّد موقع عرض HTML ثابتاً وملتزماً به من وثائق حقيقة Markdown عندما يُفعّل ويُطلب ذلك صراحةً. |
+
+## نظرة بصرية عامة
+
+![ميزات Truthmark](../assets/truthmark-features.png)
+
+**الميزات:** ما يثبّته Truthmark وكيف ينقسم سطح سير العمل.
+
+![موضع Truthmark](../assets/truthmark-position.png)
+
+**الموضع:** أين يندرج Truthmark مقارنةً بالمطالبات والذاكرة ومسارات عمل المواصفات.
+
+![تدفق مزامنة Truthmark](../assets/truthmark-syncflow.png)
+
+**تدفق المزامنة:** كيف ينهي Truth Sync تغييرات الكود العادية قبل التسليم.
+
+## لماذا تتبناه الفرق
+
+Truthmark مخصص للفرق التي تعرف بالفعل أن وكلاء الذكاء الاصطناعي يستطيعون توليد الكود.
+
+المشكلة التالية هي الحوكمة.
+
+ليست الحوكمة كطقوس. بل الحوكمة كسؤال بسيط:
+
+> بعد هذا التغيير المدعوم بالذكاء الاصطناعي، هل ما زال المستودع يقول الحقيقة؟
+
+يساعد Truthmark الفرق على الإجابة عن ذلك بملفات ملتزم بها، وتوجيه صريح، وفروق قابلة للمراجعة.
+
+يكون مفيداً عندما تحتاج إلى:
+
+- انحراف أقل في التوثيق
+- تسليمات أفضل
+- حقيقة منتج خاصة بالفرع
+- توثيق معماري وAPI دائم
+- ملكية صريحة بين الوثائق والكود
+- حدود كتابة أكثر أماناً للوكلاء
+- توثيق قابل للمراجعة بدلاً من ذاكرة مخفية
+- مسارات عمل ذكاء اصطناعي تستمر في العمل من ملفات المستودع الملتزم بها
+
+## أين يندرج Truthmark
+
+لا يستبدل Truthmark المطالبات أو الذاكرة أو المواصفات أو الاختبارات أو مراجعة الكود.
+
+إنه يمنح تلك المسارات مكاناً دائماً للرسو في Git.
+
+| الحاجة | الأنسب |
+| --- | --- |
+| مخرجات أفضل من جلسة وكيل واحدة | مطالبة أفضل |
+| استمرارية شخصية أو على مستوى الجلسة | أداة ذاكرة |
+| عمل ميزات يبدأ بالخطة | سير عمل مواصفات |
+| حقيقة مرتبطة بالفرع تنتقل مع الكود | Truthmark |
+| التحقق من صحة السلوك | الاختبارات والمراجعة |
+| مراجعة تغييرات التوثيق المدعومة بالذكاء الاصطناعي | Truthmark مع مراجعة Git |
+
+مجال Truthmark ضيق عمداً بحسب التصميم:
+
+```text
+make repository truth explicit
+route it to code
+تثبيت إرشادات الوكلاء حولها
+keep the result reviewable in Git
+```
+
+## تعمّق أكثر
+
+README هو الواجهة: سياق سريع، وبدء سريع، والنموذج الذهني الأساسي.
+
+للاستخدام أمراً بأمر، ومقارنات الأسطح، وتفاصيل المنصات المدعومة، والإعداد، والتوجيه، وPortal، والأمثلة، اقرأ [دليل مستخدم Truthmark](../user-guide.md).
+
+## حالة المشروع
+
+يوفر الإصدار الحالي:
+
+- أوامر CLI محلية للإعداد والتهيئة والتحقق والفهرسة وتحليل الأثر وحالة سير العمل
+- تعليمات وكلاء محلية مولّدة لـ Codex وClaude Code وGitHub Copilot وOpenCode وAntigravity وCursor
+- تشخيصات للتوجيه والسلطة وfrontmatter والروابط والحداثة والأسطح المولّدة ونطاق الفرع والتغطية
+- وثائق حقيقة مرتبطة بالفرع وعناصر مستمدة لاستخبارات المستودع
+
+## التوثيق
+
+- [دليل المستخدم](../user-guide.md)
+- [فهرس الوثائق](../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 صغير عمداً: محلي، ملتزم به، مرتبط بالفرع، وقابل للمراجعة.
+
+إنه ليس خدمة مستضافة، ولا خادم MCP، ولا قاعدة بيانات متجهات، ولا طبقة ذاكرة مخفية، ولا منتج إنفاذ CI، ولا محركاً مستقلاً لإعادة كتابة الكود. يساعد حقيقة المستودع على البقاء مرئية؛ ولا يستبدل الاختبارات أو مراجعة الكود أو حكم البشر.
+
+## الترخيص
+
+MIT. راجع [LICENSE](../../LICENSE).

package/docs/readmes/README.de.md

@@ -0,0 +1,225 @@
+# Truthmark
+
+**Deine Agenten schreiben Code. Truthmark pflegt menschenorientierte, in Git überprüfbare Dokumentation.**
+
+[🇺🇸 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-Banner](../assets/truthmark-banner.png)
+
+## 🚀 Schnellstart: lokal in fünf Minuten ausführen
+
+Führe dies in dem Git-Repository aus, das Truthmark verwalten soll:
+
+```bash
+cd /path/to/your-repo
+npm install -g truthmark
+truthmark config
+```
+
+Aktiviere den KI-Host, den du tatsächlich nutzt. Neue Konfigurationen sind host-neutral; füge daher vor der Initialisierung eine `platforms`-Liste auf oberster Ebene zu `.truthmark/config.yml` hinzu:
+
+```yaml
+version: 2
+platforms:
+  - codex        # or: claude-code, github-copilot, opencode, antigravity, cursor
+truthmark:
+  workspace: docs/truthmark
+  generated:
+    portal:
+      enabled: false
+```
+
+Installiere anschließend die repo-lokalen Truth-Dokumente, das Routing und die Anweisungen für KI-Hosts:
+
+```bash
+truthmark init
+truthmark check
+git diff
+```
+
+Probiere nun den häufigsten Einstiegspfad: ein bestehendes Verhalten anhand von Code und Tests dokumentieren. Bitte in deinem KI-Coding-Host den installierten Workflow:
+
+```text
+/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
+```
+
+Danach sollten Nutzer Truth Sync normalerweise nicht direkt aufrufen. Programmiere weiter über deinen KI-Host; die installierten Repository-Anweisungen weisen den Agenten an, relevante Tests auszuführen und vor der Übergabe die Truth Sync-Prüfung durchzuführen, wenn funktionaler Code geändert wurde. Du prüfst den daraus entstehenden Code-Diff plus den Truth-Doc-Diff.
+
+Wenn du nur CLI-Validierung möchtest und noch keine host-spezifischen KI-Workflows willst, lasse `platforms` weg und führe `truthmark init && truthmark check` aus; du kannst später eine Plattform hinzufügen und `truthmark init` erneut ausführen.
+
+## 💡 Das Problem: die KI-Dokumentationslücke
+
+KI-Coding-Agenten sind unglaublich gut darin, schnell Code zu schreiben. Doch diese Geschwindigkeit erzeugt einen gefährlichen neuen Fehlermodus: **die Geschichte des Repositories driftet von der Realität ab.**
+
+* Verhalten geht in flüchtigen Chatverläufen verloren.
+* Architekturdokumente geraten schnell in Rückstand.
+* Produktentscheidungen verschwinden nach der Übergabe.
+* Code-Reviewer prüfen rohe Code-Diffs, ohne das „Warum“ zu verstehen.
+* Jede neue KI-Sitzung muss die Wahrheit deines Repositories von Grund auf neu entdecken.
+
+## 🎯 Die Lösung: Truthmark
+
+**Truthmark** installiert eine Git-native Workflow-Schicht in deinem Repository. Es behebt den Teil der KI-Entwicklung, der normalerweise kaputtgeht: die Dokumentation dabei zu unterstützen, mit dem Code synchron zu bleiben.
+
+Statt darauf zu hoffen, dass Menschen und KI-Agenten daran denken, Dokumentation zu aktualisieren, macht Truthmark Dokumentation direkt in deinem Repo zu einer systematischen, überprüfbaren Gewohnheit.
+
+### ✨ Warum Truthmark einzigartig ist
+
+Truthmark ist nicht einfach nur ein weiteres Dokumentationstool. Es ist tief in den KI-Workflow integriert:
+
+* **🚫 Kein Vendor-Lock-in:** keine gehosteten Dienste, keine versteckten Datenbanken, keine zusätzlichen Server im Betrieb.
+* **🌳 100 % Git-nativ:** alles lebt in deinem Repository. Die Wahrheit bewegt sich mit deinem Branch.
+* **🤝 Von Menschen besessener, von Agenten befolgter Vertrag:** Maintainer besitzen den Repository-Vertrag; Agenten folgen beim Coden den installierten Anweisungen.
+* **✅ Vertrauen durch Verifikation:** KI-Arbeit wird leichter vertrauenswürdig, weil verhaltensändernde Arbeit eine für Menschen überprüfbare Truth-Doc-Entscheidung oder einen Diff enthält.
+
+## 🔄 Wie es funktioniert
+
+Wenn ein KI-Agent deinen Code verändert, ist die Arbeit nicht erledigt. Truthmark installiert eine Workflow-Schutzschiene zum Abschluss, der Agenten vor der Übergabe folgen:
+
+1. 💻 **Code:** Der Agent ändert funktionalen Code.
+2. 🧪 **Test:** Relevante Tests werden ausgeführt.
+3. 🔍 **Prüfen:** Truthmark prüft zugeordnete Dokumentation als Teil der installierten Abschlussprüfung.
+4. 📝 **Dokumentation:** Docs werden vom Agenten aktualisiert, wenn sich die Repository-Wahrheit geändert hat.
+5. 👀 **Review:** Ein Mensch prüft den *Code-Diff* + den *Truth-Diff*.
+
+## 🛠 Wie du mit Truthmark interagierst
+
+Truthmark hat einen repo-lokalen Vertrag und zwei Arten, ihn zu nutzen.
+
+### Menschen installieren und validieren den Vertrag
+
+Maintainer und CI nutzen die CLI:
+
+* `truthmark config` - erstellt die Anfangskonfiguration.
+* `truthmark init` - installiert oder aktualisiert Routing, Truth-Doc-Scaffolds und Anweisungen für KI-Hosts.
+* `truthmark check` - validiert die Repository-Truth im Terminal.
+
+### Agenten folgen dem Vertrag beim Coden
+
+Truthmark installiert repo-lokale Anweisungen für unterstützte KI-Coding-Hosts wie Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity und Cursor.
+
+Der normale Ablauf ist einfach:
+
+1. Bitte deinen Agenten um eine Codeänderung oder darum, vorhandenes Verhalten zu dokumentieren.
+2. Die installierten Anweisungen sagen dem Agenten, wann er testen, wann er Truth-Dokumente aktualisieren und wann er für menschliche Prüfung stoppen soll.
+3. Du prüfst normale Git-Diffs: Code plus alle Truth-Doc-Änderungen.
+
+Die vom Nutzer gestarteten Agentenanfragen bleiben bewusst wenige:
+
+* `/truthmark-document` - dokumentiert vorhandenes implementiertes Verhalten aus Code und Tests.
+* `/truthmark-realize` - implementiert Code aus vorhandenen Truth-Dokumenten.
+* `/truthmark-check` - auditiert die Repository-Truth.
+
+Truth Sync ist nicht der übliche Weg, Arbeit zu starten; es ist die Abschlussprüfung nach funktionalen Codeänderungen.
+Truth Structure ist kein Alltagsbefehl; es repariert Routing oder Ownership nur, wenn das die Arbeit blockiert.
+
+## Was du bekommst
+
+| Fähigkeit | Was sie tut |
+| --- | --- |
+| Git-native Wahrheit | Hält Repository-Wahrheit in committetem Markdown und Konfiguration. |
+| Branch-bezogene Dokumentation | Die Wahrheit bewegt sich mit dem Branch, statt in einer privaten Sitzung zu leben. |
+| Menschliche CLI | Gibt Maintainern Befehle für Einrichtung, Aktualisierung, Validierung und Inspektion. |
+| Installierte Agentenanleitung | Sagt Coding-Agenten, wann sie dokumentieren, testen, Truth synchronisieren, auditieren oder für Review stoppen sollen. |
+| Explizites Routing | Ordnet Codebereiche kanonischen Truth-Dokumenten zu. |
+| Überprüfbare Übergaben | Erzeugt normale Git-Diffs sowohl für Code als auch für Truth-Dokumente. |
+| Local-first-Betrieb | Benötigt keinen gehosteten Dienst, Daemon, keine Datenbank und keinen MCP-Server. |
+| Sicherere Schreibgrenzen | Trennt code-first-, doc-first-, read-only- und doc-only-Workflows. |
+| Validierung | Meldet Probleme bei Routing, Autorität, Frontmatter, Links, generierten Oberflächen, Branch-Scope, Aktualität und Abdeckung. |
+| Optionales Portal | Erzeugt bei ausdrücklicher Aktivierung und Anforderung eine committete statische HTML-Präsentationssite aus Markdown-Truth-Dokumenten. |
+
+## Visueller Überblick
+
+![Truthmark-Funktionen](../assets/truthmark-features.png)
+
+**Funktionen:** was Truthmark installiert und wie Agenten repo-lokale Anweisungen nutzen.
+
+![Truthmark-Position](../assets/truthmark-position.png)
+
+**Position:** wo Truthmark im Verhältnis zu Prompts, Memory und Spec-Workflows steht.
+
+![Truthmark-Sync-Ablauf](../assets/truthmark-syncflow.png)
+
+**Sync-Ablauf:** wie Truth Sync normale Codeänderungen vor der Übergabe abschließt.
+
+## Warum Teams es einsetzen
+
+Truthmark ist für Teams, die bereits wissen, dass KI-Agenten Code erzeugen können.
+
+Das nächste Problem ist Governance.
+
+Nicht Governance als Zeremonie. Governance als einfache Frage:
+
+> Sagt das Repository nach dieser KI-gestützten Änderung noch die Wahrheit?
+
+Truthmark hilft Teams, diese Frage mit committeten Dateien, explizitem Routing und überprüfbaren Diffs zu beantworten.
+
+Es ist nützlich, wenn du Folgendes brauchst:
+
+- weniger Dokumentationsdrift
+- bessere Übergaben
+- branch-spezifische Produktwahrheit
+- dauerhafte Architektur- und API-Dokumentation
+- explizite Ownership zwischen Docs und Code
+- sicherere Schreibgrenzen für Agenten
+- überprüfbare Dokumentation statt versteckter Memory
+- Agentenanleitung, die weiterhin aus committeten Repo-Dateien funktioniert
+
+## Wo Truthmark hineinpasst
+
+Truthmark ersetzt keine Prompts, Memory, Specs, Tests oder Code-Reviews.
+
+Es gibt diesen Workflows einen dauerhaften Ort in Git.
+
+| Bedarf | Besser geeignet |
+| --- | --- |
+| Bessere Ausgabe aus einer Agentensitzung | Besserer Prompt |
+| Persönliche oder sitzungsbezogene Kontinuität | Memory-Tool |
+| Plan-first-Feature-Arbeit | Spec-Workflow |
+| Branch-bezogene Wahrheit, die mit Code reist | Truthmark |
+| Verhaltenskorrektheit validieren | Tests und Review |
+| KI-gestützte Dokumentationsänderungen prüfen | Truthmark plus Git-Review |
+
+Truthmarks Spur ist bewusst schmal:
+
+```text
+make repository truth explicit
+route it to code
+Agentenanleitung darum installieren
+keep the result reviewable in Git
+```
+
+## Tiefer einsteigen
+
+Das README ist das Schaufenster: schneller Kontext, Schnellstart und das zentrale Denkmodell.
+
+Für befehlsweise Nutzung, Oberflächenvergleiche, Details zu unterstützten Plattformen, Konfiguration, Routing, Portal und Beispiele lies den [Truthmark-Benutzerleitfaden](../user-guide.md).
+
+## Projektstatus
+
+Die aktuelle Version bietet:
+
+- lokale CLI-Befehle für config, init, check, index, impact und Workflow-Status
+- generierte repo-lokale Agentenanweisungen für Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity und Cursor
+- Diagnosen für Routing, Autorität, Frontmatter, Links, Aktualität, generierte Oberflächen, Branch-Scope und Abdeckung
+- branch-bezogene Truth-Dokumente und abgeleitete Repository-Intelligence-Artefakte
+
+## Dokumentation
+
+- [Benutzerleitfaden](../user-guide.md)
+- [Docs-Index](../README.md)
+- [Architekturüberblick](../truthmark/engineering/architecture/overview.md)
+- [API- und CLI-Verträge](../truthmark/engineering/contracts/config-route-and-check-contracts.md)
+- [Leitfaden zur Pflege der Repository-Wahrheit](../standards/maintaining-repository-truth.md)
+
+Für lokale Entwicklungs- und Beitragsbefehle siehe [CONTRIBUTING.md](../../CONTRIBUTING.md).
+
+## Designgrenzen
+
+Truthmark ist bewusst klein: lokal, committet, branch-bezogen und überprüfbar.
+
+Es ist kein gehosteter Dienst, MCP-Server, keine Vektordatenbank, versteckte Memory-Schicht, kein CI-Enforcement-Produkt und keine autonome Code-Rewrite-Engine. Es hilft, Repository-Wahrheit sichtbar zu halten; es ersetzt keine Tests, Code-Reviews oder menschliches Urteil.
+
+## Lizenz
+
+MIT. Siehe [LICENSE](../../LICENSE).