# chamnan — لكي يعرف المستودع نفسه

<sub>[🇬🇧 English](../../README.md) · [🇨🇳 中文](README.zh-CN.md) · [🇹🇼 繁體中文](README.zh-TW.md) · [🇯🇵 日本語](README.ja.md) · [🇰🇷 한국어](README.ko.md) · [🇹🇭 ไทย](README.th.md) · [🇻🇳 Tiếng Việt](README.vi.md) · [🇮🇩 Indonesia](README.id.md) · [🇮🇳 हिन्दी](README.hi.md) · [🇧🇩 বাংলা](README.bn.md) · [🇵🇰 اردو](README.ur.md) · [🇮🇱 עברית](README.he.md) · [🇹🇷 Türkçe](README.tr.md) · [🇷🇺 Русский](README.ru.md) · [🇺🇦 Українська](README.uk.md) · [🇵🇱 Polski](README.pl.md) · [🇨🇿 Čeština](README.cs.md) · [🇩🇪 Deutsch](README.de.md) · [🇳🇱 Nederlands](README.nl.md) · [🇫🇷 Français](README.fr.md) · [🇪🇸 Español](README.es.md) · [🇵🇹 Português](README.pt-PT.md) · [🇧🇷 Português (BR)](README.pt-BR.md) · [🇮🇹 Italiano](README.it.md) · [🇷🇴 Română](README.ro.md) · [🇬🇷 Ελληνικά](README.el.md) · [🇭🇺 Magyar](README.hu.md) · [🇸🇪 Svenska](README.sv.md) · [🇫🇮 Suomi](README.fi.md) · [🇩🇰 Dansk](README.da.md) · [🇳🇴 Norsk](README.no.md) · [🇵🇭 Tagalog](README.tl.md)</sub>

> لا تحتوي هذه الصفحة على أي أرقام، عن قصد. كل القياسات موجودة في ملف README الإنجليزي وتتغيّر مع كل إصدار؛ أما هذه الصفحة فلا. ← [Evidence](../../README.md#evidence)

## ما هذا

إضافة لـ Claude Code. تبني فهرسًا للمستودع يقرأه الوكيل بدلًا من مسح الملفات ملفًا ملفًا، وتحتفظ بالسياق الهندسي الذي يتراكم أثناء عملك — حالة العمل، وسجلات الجلسات، وأسباب القرارات، والإجراءات التي تعيد استنتاجها في كل مرة.

كل ما تكتبه هو markdown عادي يُحفظ بجانب الشيفرة. لا اتصال بالشبكة أثناء التشغيل، ولا قاعدة بيانات، ولا خدمة تعمل في الخلفية، ولا نموذج embedding — مكتبة بايثون القياسية فقط.

## ما المشكلة التي يحلّها

مع كل جلسة جديدة، أو كلما ضُغط السياق، يضيع كل ما فهمه الوكيل عن شيفرتك ويعود إلى البحث من البداية.

يمنع chamnan هذا الاكتشاف المتكرر: يُسلَّم الفهرس عند بداية الجلسة، وتكون التكلفة رقمًا معروفًا ومحدودًا بدلًا من قراءات ملفات بلا حد.

## التثبيت

```bash
claude plugin marketplace add ArcticFox2029/chamnan
claude plugin install chamnan@chamnan
```

افتح جلسة جديدة، ثم شغّل `/chamnan:bootstrap` مرة واحدة لكل مستودع.

<!-- generated: build_sections.py -->

## كل الميزات

أربع قدرات. كل ما في الجداول أدناه يعمل فعلاً في الإصدار الحالي. يمكن إطفاء كل جزء على حدة في `.chamnan/config.json`، ولا يعتمد جزء على آخر.

### الفهم — ما الموجود، وما المتصل بما

| | |
|---|---|
| **الفهرس** | `MAP.md` — سطر واحد لكل ملف، مولَّد من الشيفرة نفسها. يقرأ الوكيل الفهرس ثم يبحث بـ grep عن التفصيل المطلوب، بدل أن يمشي في الشجرة كلها. |
| **الأثر** | من يعتمد على هذا الملف، وأي اختبارات تغطّيه. استيرادات الملف نفسه مكتوبة في أعلاه أصلاً؛ الجهة المكلفة هي الاتجاه المعاكس — ابحث عن المسار بـ grep قبل التعديل. |
| **نموذج البيانات** | أسماء الجداول والنماذج مع سطر تعريفي واحد، مستخرجة من DDL والهجرات ونماذج ORM — لا تفريغاً كاملاً للمخطط. لا يظهر إلا إذا كان المستودع يعرّف واحداً. |
| **سطح الـ API** | الطريقة والمسار والمعالج، من مزخرفات المسارات ووثائق OpenAPI وتعريفات الخدمة في `.proto` — لا المواصفة كاملة. |
| **الإعدادات** | أسماء متغيرات البيئة التي يقرأها المستودع. **الأسماء فقط، ولا تُسجَّل القيم أبداً** — ويحذّر إذا لم يكن `.env` ضمن gitignore. |
| **النشر** | ما يعمل فعلاً، مقروءاً من بيانات Kubernetes وAnsible وCompose وHelm وCI: الأنواع والأسماء، الصور، الأدوار، خطوط الإنتاج. أما Secret فلا يُؤخذ منه إلا اسمه، ولا شيء تحته. |
| **المواد غير المصدرية** | الأوراق الممسوحة والتصديرات والأرشيفات — أعداداً وأحجاماً وأكثر الامتدادات شيوعاً فحسب. وجوده يمنع الوكيل من الذهاب لينظر بنفسه، وذلك أغلى بكثير. **لا يُفتح أبداً، ولا يُقرأ أبداً.** |

### التذكّر — ماذا كان يُعمَل، ولماذا

| | |
|---|---|
| **حالة العمل** | `STATE.md` — ما يجري العمل عليه الآن، يُحقن عند بدء الجلسة كي يتوقف ضغط السياق عن محوه. |
| **سجل الجلسة** | سجل واحد لكل جلسة في `.chamnan/sessions/`. **ما لم يكتمل فقط** يصل إلى الجلسة التالية؛ أما جلسة انتهت بنظافة فلا تحقن شيئاً. |
| **الذاكرة** | `decisions/` و`lessons/` و`rules/`. القواعد قيود دائمة، فتوضع أمام الوكيل كل جلسة؛ أما القرارات والدروس فتُسهم بعنوانها فقط، وتُقرأ حين يبدو العنوان ذا صلة. |
| **الخيوط المفتوحة** | خطوط عمل لم تُغلق بعد، مع تاريخ الملفات التي مسّها الخيط — ويظل يتتبعها بعد إعادة تسمية الملف. |

### إعادة الاستعمال — ما حُلّ مرة

| | |
|---|---|
| **الإجراءات** | مهارات يكتبها الوكيل **بنفسه** حين يصطدم بشيء معقّد أو متكرر. ليست مكتبة جاهزة مرفقة، بل آلية. |
| **الأدوات** | يلاحظ أن النص المؤقت نفسه كُتب مرة أخرى، فيعرض الاحتفاظ به — ويذكّرك به قبل أن تكتب نصاً جديداً. |
| **مسارات العمل** | يلاحظ أن الأوامر نفسها جرت بالترتيب نفسه في أيام منفصلة، فيعرض تدوين ذلك التسلسل. |

### التراكم — ما تعلّمه المستودع عن نفسه

| | |
|---|---|
| **المحطات** | التغييرات القليلة التي أعادت تشكيل المستودع: ما الذي انتقل، ولماذا استحق ذلك، وأي مناطق مسّها. |
| **المرشحات** | تسلسلات الأوامر المتكررة المكتشفة تُحجز **دائماً بانتظار تأكيد إنسان**. لا شيء يُرقّى تلقائياً. |
| **البيئات** | أعلن ما هي production أو staging وما المحظور فيها، ثم ينبّهك حين يشيخ ذلك الإعلان. |
| **التقرير** | ماذا تحوي مساحة العمل، وهل هو في المتناول فعلاً، وكيف تغيّر السياق لكل دور في مستودعك. رقمك أنت، لا رقمنا. |

عملٌ هندسي متكرر يتحول إلى معرفة مستودع قابلة لإعادة الاستعمال — **لا تدريب نموذج، ولا أتمتة للمطوّر.** إنها آلية لحفظ عمل لولاها لظل في رأس من قام به وحده.

## الأوامر

كلها تُستدعى من الطرفية، والوكيل يستدعيها بنفسه أيضاً.

| | |
|---|---|
| `chamnan-map` | بناء الفهرس وتحديثه |
| `chamnan-report` | ماذا تحوي مساحة العمل، وكيف تغيّر السياق لكل دور |
| `chamnan-impact` | من يعتمد على هذا الملف، وأي اختبارات تغطّيه |
| `chamnan-timeline` | ماذا جرى لهذا الملف حتى الآن |
| `chamnan-peek` | يقول ما داخل ملف كبير دون قراءته إلى السياق |
| `chamnan-promote` | الاحتفاظ بنص برمجي كأداة دائمة لهذا المستودع |
| `chamnan-candidates` | عرض التكرارات المكتشفة وتأكيدها أو رفضها |
| `chamnan-env` | إعلان البيئة ومحظوراتها، والتحقق من أن الإعلان ما زال حديثاً |
| `chamnan-age` | من أين بدأت المعرفة المخزّنة تشيخ |

ومهارات تُستدعى من داخل الجلسة: `/chamnan:bootstrap` `/chamnan:remap` `/chamnan:resume` `/chamnan:remember` `/chamnan:milestone` `/chamnan:capture` `/chamnan:promote` `/chamnan:report`

## ماذا يكتب، وأين

كل شيء داخل `.chamnan/`، وهو markdown وJSON عاديان. يمكن قراءته وتحريره يدوياً وحذفه في أي وقت دون أن ينكسر شيء.

| | |
|---|---|
| `MAP.md` | ما الموجود، وما يعتمد على ما |
| `STATE.md` | ما يجري العمل عليه الآن |
| `sessions/` | أين توقف العمل السابق |
| `memory/` | القرارات والدروس والقواعد الدائمة |
| `threads/` | خطوط العمل التي لم تُغلق |
| `skills/` · `tools/` | الإجراءات والنصوص التي تستحق الحفظ |
| `milestones.md` | التغييرات التي أعادت تشكيل المستودع |
| `config.json` | تشغيل كل جزء وإطفاؤه، وسقف حجم الكتلة المحقونة في الجلسة |

**الكتابة الوحيدة خارج `.chamnan/`** هي خطاف Git اختياري قبل الإيداع، يبقي الفهرس مواكباً للشيفرة — لا يُثبَّت إلا إذا وافقت، ويمكن نزعه.

**الوكيل لا يتعلم.** لا شيء يُدرَّب، ولا يبقى شيء خارج هذا المجلد، والجلسة التالية تبدأ من الصفر كما كانت — لكنها تبدأ من الصفر *داخل مستودع يشرح نفسه*. الاستمرارية في المخرجات لا في النموذج.

## الأمان

| | |
|---|---|
| **لا اتصال بالشبكة أثناء التشغيل** | ولا مرة واحدة. لا يحتاج مفتاح API، ولا يُرسل شيء إلى أي مكان. |
| **لا يعيد كتابة شيفرتك** | يبلّغ ولا يحرّر. الفهرس ينسخ تعليقاتك التي كتبتها أصلاً، ولا يخترعها؛ والملفات بلا تعليق تُذكر بأسمائها لتملأها أنت. |
| **لا خدمة خلفية ولا عمل في الخلفية** | لا عملية مقيمة، ولا قاعدة بيانات، ولا نموذج تضمين — مكتبة Python القياسية وحدها. |
| **الأسرار تُرشَّح أولاً** | كل ما سيُكتب أو يُحقن في الجلسة يمر أولاً بمرشّح الأسرار: تبقى *أسماء* المتغيرات ولا تبقى قيمها. أما السقف الذي لا يبلغه هذا المرشّح فمكتوب بجانب رقمه في README الإنجليزي. |
| **ما الذي تستطيعه إضافة مثبّتة تجاهك** | مشروح كاملاً في README الإنجليزي، بما في ذلك عند أي حلقة يقطع chamnan سلسلة التسريب. |

## المتطلبات

Claude Code · Python · Git · macOS أو Linux أو Windows

لا شيء غير ذلك، ولا اعتماديات تُثبَّت. أدنى إصدار من Python مذكور في [README › Requirements](../../README.md#requirements) — وهذه الصفحة لا تحمل أرقاماً، لأن الأرقام هي ما يتغير.

## الإيقاف أو الإزالة

أطفئه جزءاً جزءاً في `.chamnan/config.json` · أوقفه في مستودع واحد · انزع الإضافة من الجهاز كله · احذف `.chamnan/` متى شئت دون أن ينكسر شيء — الخطوات التفصيلية في [README › Update, disable, uninstall](../../README.md#update-disable-uninstall)

<!-- /generated -->

## اقرأ هذا قبل التثبيت

**chamnan مناسب لمجلد رئيسي واحد تعود إليه مرارًا.** كل ما يفعله يُدفع مقدّمًا ويُسترد في الجلسات اللاحقة — أما مستودع تفتحه مرة واحدة، فقد دفعت كل شيء ولم تسترد شيئًا.

**يبلّغ ولا يعيد كتابة شيفرتك.** الفهرس ينسخ التعليقات التي كتبتها أنت، ولا يختلق شيئًا. والملفات بلا تعليق تُذكر بأسمائها لتضيفها بنفسك.

**حدوده مقيسة ومكتوبة**، بما في ذلك القياسات التي تعمل ضد ميزته الأساسية نفسها.

## أين التفاصيل

| | |
|---|---|
| كل رقم، وكيف قيس | [README › Evidence](../../README.md#evidence) |
| مجموعة اختبارات الانحدار — يمكنك تشغيلها بنفسك | [`tests/run_tests.py`](../../tests/run_tests.py) |
| ما الذي تغيّر في كل إصدار، ولماذا | [CHANGELOG.md](../../CHANGELOG.md) |
| كل شيء | [README.md](../../README.md) |

---

<sub>MIT · [github.com/ArcticFox2029/chamnan](https://github.com/ArcticFox2029/chamnan)</sub>