Align project docs with checked-in code

Author: sanbuphy

docs/ar/projects/project-01-baseline-vs-minimal-harness/index.md

@@ -11,7 +11,7 @@
 
 ستنفذها مرتين. المرة الأولى: prompt فقط، دون تحضير. المرة الثانية: مع وضع `AGENTS.md` و `init.sh` و `feature_list.json` مسبقًا في المستودع. ثم قارن.
 
-جوهر هذا المشروع ليس كتابة الكود، بل قياس الفرق بين "قضاء 15 دقيقة في تحضير القواعد أولًا" و"ترك الوكيل يعمل مباشرة".
+يستخدم سيناريو الدورة هذا فترة قصيرة من إعادة الاكتشاف/التحضير كمثال، لا كنتيجة قياس ثابتة.
 
 ## الأدوات
 
@@ -23,3 +23,14 @@
 ## آلية harness
 
 Harness بسيط: `AGENTS.md` + `init.sh` + `feature_list.json`
+
+## استخدم المشروع المضمَّن في المستودع
+
+مسار المشروع في المستودع: `projects/project-01/`
+
+| المجلد | ماذا يحتوي | كيف تستخدمه / ماذا تقارن |
+|------|------|------|
+| `starter/` | تشغيل الـ harness الضعيف. يحتوي فقط على `task-prompt.md` كوصف للمهمة ولا يتضمن `AGENTS.md` أو `feature_list.json`. | قدّم الـ prompt لوكيلك وقِس ما الذي ينجزه بدون أي هيكلة إضافية. |
+| `solution/` | نفس جزء المنتج مع ملفات harness صريحة: `AGENTS.md` و`CLAUDE.md` و`init.sh` و`feature_list.json` و`claude-progress.md`. | قارن كيف تجعل القواعد والتحقق نفس المهمة قابلة للتنفيذ والقياس. |
+
+الميزات الأربع الملموسة هي: تشغيل النافذة، قائمة المستندات، لوحة الأسئلة/الأجوبة، وإنشاء مجلد البيانات المحلي. راجع `solution/feature_list.json` لمعرفة الدليل المتوقع لكل ميزة.

docs/ar/projects/project-02-agent-readable-workspace/index.md

@@ -11,6 +11,15 @@
 
 ستنفذه مرتين: الأولى دون مساعدة، والثانية مع وضع `ARCHITECTURE.md` و `PRODUCT.md` و `session-handoff.md` مسبقًا في المستودع.
 
+## استخدم المشروع الموجود في المستودع
+
+مسار المستودع: `projects/project-02/`
+
+| المجلد | ماذا يحتوي | ماذا تقارن |
+|------|------|------|
+| `starter/` | كود Project 01 مع import المستندات، عرض التفاصيل، و persistence غير مكتملة بعد. توجد وثائق لكنها أخف، ولا يوجد `session-handoff.md`. | مقدار السياق الذي تحتاج الجلسة الثانية من الوكيل إلى اكتشافه من جديد. |
+| `solution/` | نفس جزء المنتج مكتمل، مع وثائق handoff تحت `projects/project-02/solution/`، بالإضافة إلى `feature_list.json` و `session-handoff.md`. | هل تستطيع جلسة جديدة المتابعة اعتمادًا على حالة المستودع فقط. |
+
 ## الأدوات
 
 - Claude Code أو Codex

docs/ar/projects/project-03-multi-session-continuity/index.md

@@ -11,6 +11,15 @@
 
 ستنفذه مرتين: الأولى دون قيود، والثانية مع تطبيق صارم.
 
+## استخدم المشروع الموجود في المستودع
+
+مسار المستودع: `projects/project-03/`
+
+| المجلد | ماذا يحتوي | ماذا تقارن |
+|------|------|------|
+| `starter/` | كود Project 02 وفيه indexing و Q&A مع citations غير مكتملين بعد. يوجد `feature_list.json` أولي، لكن لا توجد ملفات handoff/restart النهائية. | هل ينحرف الوكيل بين عدة ميزات أو يفقد الحالة بعد إعادة التشغيل. |
+| `solution/` | chunking و metadata و index status و citation-based Q&A مكتملة، مع `init.sh` و `session-handoff.md` و `claude-progress.md` و `clean-state-checklist.md`. | هل تملك كل ميزة دليل تحقق قبل وضعها في حالة pass. |
+
 ## الأدوات
 
 - Claude Code أو Codex

docs/ar/projects/project-04-incremental-indexing/index.md

@@ -11,6 +11,17 @@
 
 ستنفذه مرتين: الأولى دون سجلات أو قيود، والثانية بالأدوات والقواعد المناسبة.
 
+## استخدم المشروع الموجود في المستودع
+
+مسار المستودع: `projects/project-04/`
+
+| المجلد | ماذا يحتوي | ماذا تقارن |
+|------|------|------|
+| `starter/` | كود Project 03 مع إشارات تشخيص ضعيفة. عيب indexing المزروع قد يكسر chunking للملفات الكبيرة، ولا يوجد script لفحص المعمارية. | كم يستغرق الوكيل للوصول إلى السبب الجذري بدون إشارات runtime. |
+| `solution/` | structured logger، وثائق/script لحدود المعمارية، منطق chunking مصحح، و `clean-state-checklist.md`. | هل تجعل logs و boundary checks الإصلاح أسرع وأقل تدخلاً. |
+
+ملفات مهمة: `projects/project-04/solution/src/services/logger.ts`, `projects/project-04/solution/scripts/check-architecture.sh`, `projects/project-04/solution/docs/ARCHITECTURE.md`, `projects/project-04/solution/src/services/indexing-service.ts`.
+
 ## الأدوات
 
 - Claude Code أو Codex

docs/ar/projects/project-05-grounded-qa-verification/index.md

@@ -11,6 +11,17 @@
 
 اختر ترقية جوهرية لميزة، مثل محادثة متعددة الأدوار، أو إعادة تصميم لوحة الاستشهادات، أو فلترة المستندات، وحافظ عليها ثابتة في كل التشغيلات.
 
+## استخدم المشروع الموجود في المستودع
+
+مسار المستودع: `projects/project-05/`
+
+| المجلد | ماذا يحتوي | ماذا تقارن |
+|------|------|------|
+| `starter/` | تطبيق مبني على Project 04 قبل ترقية سجل المحادثة. | نقطة البداية إذا أردت إعادة تشغيل المتغيرات الثلاثة. |
+| `solution/single-role/` | وكيل واحد يخطط وينفذ ويقيّم نفسه. | الدرجة والعيوب في `evaluator-rubric.md`. |
+| `solution/gen-eval/` | generator + evaluator مع دليل مراجعة. | الدرجة وملاحظات revision في `evaluator-rubric.md`. |
+| `solution/plan-gen-eval/` | planner + generator + evaluator مع sprint contract. | `sprint-contract.md` ودليل الدرجة الأعلى في `evaluator-rubric.md`. |
+
 ## الأدوات
 
 - Claude Code أو Codex

docs/ar/projects/project-06-runtime-observability-and-debugging/index.md

@@ -11,6 +11,15 @@
 
 استخدم مجموعة مهام ثابتة متعددة الميزات تغطي شريحة منتج كاملة: استيراد المستندات، الفهرسة، Q&A مع الاستشهادات، قابلية ملاحظة runtime، وحالة مستودع قابلة للقراءة والاستئناف. ابدأ بتشغيل baseline مع harness ضعيف، ثم شغّل أقوى harness لديك، ثم نظف وأعد التشغيل. أخيرًا، نفذ تجربة ablation للـ harness: أزل مكونًا واحدًا كل مرة وانظر أيها مهم فعليًا.
 
+## استخدم المشروع الموجود في المستودع
+
+مسار المستودع: `projects/project-06/`
+
+| المجلد | ماذا يحتوي | ماذا تقارن |
+|------|------|------|
+| `starter/` | المنتج شبه مكتمل، لكن سطح harness ضعيف عمدًا: يوجد `AGENTS.md` أساسي فقط، ولا يوجد `feature_list.json` أو `session-handoff.md` أو clean-state checklist أو benchmark/cleanup scripts. | ملاحظات يدوية لخط baseline مع harness ضعيف. |
+| `solution/` | harness كامل: `AGENTS.md`, `CLAUDE.md`, `feature_list.json`, `init.sh`, `session-handoff.md`, `clean-state-checklist.md`, quality/evaluator docs و scripts. | شغّل `projects/project-06/solution/scripts/benchmark.sh` و `projects/project-06/solution/scripts/cleanup-scanner.sh` ثم قارن أدلة الجودة. |
+
 ## الأدوات
 
 - Claude Code أو Codex

docs/de/projects/project-01-baseline-vs-minimal-harness/index.md

@@ -11,7 +11,7 @@ Baue das minimale Gerüst einer Electron-Wissensdatenbank-App: ein Fenster mit D
 
 Du führst sie zweimal aus. Beim ersten Mal: nur ein Prompt, keine Vorbereitung. Beim zweiten Mal: `AGENTS.md`, `init.sh` und `feature_list.json` liegen bereits im Repository. Danach vergleichst du.
 
-Der Kern dieses Projekts ist nicht das Schreiben von Code, sondern herauszufinden, wie groß der Abstand zwischen "15 Minuten Regeln vorbereiten" und "den Agenten einfach loslaufen lassen" ist.
+Dieses Kursbeispiel nutzt eine kurze Wiederentdeckungs-/Vorbereitungsphase als Beispiel, nicht als fest gemessenes Ergebnis.
 
 ## Werkzeuge
 
@@ -23,3 +23,14 @@ Der Kern dieses Projekts ist nicht das Schreiben von Code, sondern herauszufinde
 ## Harness-Mechanismus
 
 Minimaler harness: `AGENTS.md` + `init.sh` + `feature_list.json`
+
+## Nutze das eingecheckte Projekt
+
+Repository-Pfad: `projects/project-01/`
+
+| Verzeichnis | Inhalt | Nutzung/Vergleich |
+|------|------|------|
+| `starter/` | Weak-Harness-Lauf. Enthält nur `task-prompt.md` als Aufgabenbeschreibung und keine `AGENTS.md` oder `feature_list.json`. | Gib den Prompt an deinen Agenten und miss, was ohne zusätzliche Struktur fertig wird. |
+| `solution/` | Gleicher Produktslice mit expliziten Harness-Artefakten: `AGENTS.md`, `CLAUDE.md`, `init.sh`, `feature_list.json` und `claude-progress.md`. | Vergleiche, wie Regeln und Verifikation die gleiche Aufgabe konkret und überprüfbar machen. |
+
+Die vier konkreten Features sind Fensterstart, Dokumentliste, Frage-Panel und das lokale Datenverzeichnis. Schau in `solution/feature_list.json` für die erwartete Evidence pro Feature.

docs/de/projects/project-02-agent-readable-workspace/index.md

@@ -11,6 +11,17 @@ Füge dem Repository "Lesbarkeit" hinzu, damit ein neuer Agent die Projektstrukt
 
 Du führst es zweimal aus: zuerst ohne Hilfe, dann mit bereits abgelegten `ARCHITECTURE.md`, `PRODUCT.md` und `session-handoff.md`.
 
+## Nutze das eingecheckte Projekt
+
+Repository-Pfad: `projects/project-02/`
+
+| Verzeichnis | Inhalt | Vergleichspunkt |
+|------|------|------|
+| `starter/` | Code aus Project 01 mit noch unvollständigem Import, Detailansicht und Persistenz. Die Dokumentation ist vorhanden, aber dünner, und `session-handoff.md` fehlt. | Wie viel Kontext eine zweite Agent-Sitzung erneut herausfinden muss. |
+| `solution/` | Derselbe Produktschnitt ist fertig, mit Übergabedokumentation unter `projects/project-02/solution/` sowie `feature_list.json` und `session-handoff.md`. | Ob eine neue Sitzung nur aus dem Repository-Zustand weiterarbeiten kann. |
+
+Die Produktfunktionen sind Dokumentimport, vollständiges Laden von Details/Inhalt und Persistenz nach Neustart. Die Harness-Funktion ist ein gut übergebbarer Workspace.
+
 ## Werkzeuge
 
 - Claude Code oder Codex

docs/de/projects/project-03-multi-session-continuity/index.md

@@ -11,6 +11,15 @@ Füge dem Agenten Scope-Kontrolle und Verifikationsgates hinzu. Implementiere Do
 
 Du führst es zweimal aus: zuerst ohne Einschränkungen, dann mit strikter Durchsetzung.
 
+## Nutze das eingecheckte Projekt
+
+Repository-Pfad: `projects/project-03/`
+
+| Verzeichnis | Inhalt | Vergleichspunkt |
+|------|------|------|
+| `starter/` | Project-02-Code, bei dem Indexierung und zitierfähiges Q&A noch unvollständig sind. Es gibt ein erstes `feature_list.json`, aber keine finalen Neustart- und Übergabeartefakte. | Ob der Agent über mehrere Funktionen driftet oder nach einem Neustart Zustand verliert. |
+| `solution/` | Chunking, Metadaten, Indexierungsstatus und Q&A mit Zitaten sind fertig, plus `init.sh`, `session-handoff.md`, `claude-progress.md` und `clean-state-checklist.md`. | Ob jede Funktion konkrete Evidenz hat, bevor sie als bestanden markiert wird. |
+
 ## Werkzeuge
 
 - Claude Code oder Codex

docs/de/projects/project-04-incremental-indexing/index.md

@@ -11,6 +11,17 @@ Füge Runtime-Beobachtbarkeit hinzu, etwa Startlogs, Import-/Indexierungslogs un
 
 Du führst es zweimal aus: zuerst ohne Logs oder Regeln, dann mit passenden Werkzeugen und Regeln.
 
+## Nutze das eingecheckte Projekt
+
+Repository-Pfad: `projects/project-04/`
+
+| Verzeichnis | Inhalt | Vergleichspunkt |
+|------|------|------|
+| `starter/` | Project-03-Code mit schwachen Diagnosesignalen. Der eingebaute Indexierungsfehler kann Chunking bei großen Dateien brechen, und es gibt kein Architekturprüfskript. | Wie lange der Agent ohne Runtime-Signale bis zur Ursache braucht. |
+| `solution/` | Strukturierter Logger, Architekturgrenzendokumentation und Prüfsktipt, korrigierte Chunking-Logik und `clean-state-checklist.md`. | Ob Logs und Grenzprüfungen die Korrektur schneller und weniger invasiv machen. |
+
+Wichtige Dateien: `projects/project-04/solution/src/services/logger.ts`, `projects/project-04/solution/scripts/check-architecture.sh`, `projects/project-04/solution/docs/ARCHITECTURE.md`, `projects/project-04/solution/src/services/indexing-service.ts`.
+
 ## Werkzeuge
 
 - Claude Code oder Codex