البدء

تدور هذه الصفحة حول المحادثة الأولى — ما يحدث بين قول أحدهم “أريد إنشاء folio” وموقع منشور يمكنهم فتحه. إذا كان لديك folio بالفعل وتريد إعداد مجموعة الأدوات، فانتقل إلى §4 التثبيت والتحقق.

1. 1. “إنشاء folio” يعني خمسة طلبات مختلفة
2. 2. كيف يقرر الوكيل — ولماذا هو جدول وليس حُكمًا تقديريًا
   1. الحقائق الثلاث
   2. القواعد السبع
   3. لماذا تُرجع قاعدتان “ask”، ولماذا هذا هو المغزى
   4. تعديلها
3. 3. كيف تبدو المحادثة
4. 4. التثبيت والتحقق
5. 5. توصيل إطار LLM الخاص بك
6. 6. تحويل مستودع موجود لديك بالفعل
7. 7. رؤيته منشورًا
8. 8. اجعل الصفحة المقصودة خاصة بك
   1. عقدة markdown التي تعدّلها
   2. خلفيتك الخاصة
   3. ثلاثة أمور لن تفعلها
9. 9. تتبع العمل باستخدام beans
10. الخطوات التالية

---

1. “إنشاء folio” يعني خمسة طلبات مختلفة

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

ما تقصده	ما لديك	تكلفة التخمين الخاطئ
folio جديد في مستودع جديد	لا شيء بعد	—
إضافة folio-assistant إلى مستودع موجود لديك بالفعل	مشروعك الخاص، بملفاته الخاصة	إنشاء هيكل folio فوق عمل لم ينظر فيه أحد أولاً
folio آخر في مستودع يحتوي على واحد بالفعل	نسخة من folio-assistant	مستودع ثانٍ لم تكن تريده، ومجموعة نصوص مجزأة
مستند جديد داخل الـ folio الموجود لديك بالفعل	folio، وفصل يدور في ذهنك	folio كامل فارغ، وفصل ما زال غير مكتوب
شيء تفضل وصفه بكلماتك الخاصة	—	—

السطر الرابع هو السطر الذي يستحق التوقف عنده. إنه ليس خطأً من جانبك — فكلمة “folio” كلمة غير مألوفة، وطلب واحد منها عندما تكون قصدت فصلاً في واحد منها هو أكثر الأخطاء الطبيعية والمحتملة. والوكيل الذي ينشئ هيكلاً بناءً على ذلك يكون قد أنتج مستودعًا فارغًا بدلاً من الفقرة التي طلبتها.

2. كيف يقرر الوكيل — ولماذا هو جدول وليس حُكمًا تقديريًا

إن عملية الفرز هي مصنّف حقيقي وقابل للقراءة وليست مجرد عادة قد يمتلكها الوكيل:

• العملية هي folio-assistant-core/processes/conduct/getting-started.bpmn؛
• القرار في محورها هو decisions/folio-intent.dmn، وهو جدول قرارات DMN يمكنك فتحه في أي أداة DMN وتعديله دون لمس التعليمات البرمجية.

المصدر: folio-assistant-core/processes/conduct/getting-started.bpmn — تم توليد ملف SVG بواسطة bun run cat render:bpmn.

الحقائق الثلاث

تقرأ البوابة ثلاثة أمور بالضبط، واثنان منها يأتيان من المعاينة بدلاً من السؤال:

الحقيقة	كيفية الحصول عليها
isFolio	هل يوجد ملف harness.config.json في هذا الدليل؟
repoHasContent	هل تحتوي شجرة العمل على ملفات تمثل مشروع شخص ما، بدلاً من كونها فارغة؟
statedIntent	ما قلته بالفعل — أحد الخيارات الخمسة، أو unstated

إن statedIntent هي حقيقة تتعلق بـ المحادثة. وتظل unstated حتى تحدد أيّها، واستنتاجها من نبرة الحديث أو مما قد يكون ملائمًا هو على وجه التحديد الفشل الذي وُجد هذا الجدول لمنعه.

إن isFolio تتعلق بالدليل، وليس بك. فالشخص الذي استخدم folio-assistant لسنوات لا يزال في دليل isFolio=false عندما يفتح دليلاً جديدًا. فالخبرة تغير مقدار ما يشرحه الوكيل؛ لكنها لا تغير أي فرع يسلكه.

القواعد السبع

#	ما قيل	هل هو folio	هل يحتوي على محتوى	→
1–4	أي من الأربعة	–	–	ذلك الفرع
5	unstated	نعم	–	ask
6	unstated	لا	نعم	ask
7	unstated	لا	لا	folio جديد هنا

سياسة المطابقة هي FIRST، لذا فإن القواعد 1–4 تأتي قبل أي استنتاج: الشخص الذي يحدد ما يريده لا يتم تجاوزه أبدًا بواسطة استدلال تجريبي حول نظام ملفاته.

لماذا تُرجع قاعدتان “ask”، ولماذا هذا هو المغزى

القاعدة 7 وحدها هي القابلة للحسم بمجرد المعاينة. فالدليل الذي هو بالفعل folio يتوافق مع ثلاثة طلبات مختلفة، والدليل الذي يحتوي على مشروع لشخص ما يتوافق مع طلبين. والجدول لا يتغاضى عن ذلك — بل يُرجع ask.

هذا الأمر أهم مما يبدو عليه:

إن ask هي نتيجة يُخرجها الجدول، وليست قرارًا يتوصل إليه الوكيل.

لا يمكن للوكيل التوجيه إلى فرع لم يُرجعه الجدول، وبالتالي يصبح السؤال إلزاميًا وليس من باب المجاملة. والوكيل الذي يُترك ليقرر ما إذا كان سيسأل سيقرر، تحت أي ضغط ليبدو مفيدًا، ألا يسأل — والحالات الثلاث الغامضة هي تحديدًا المواضع التي يكون فيها التخمين أكثر تكلفة.

عندما تجيب، تصبح إجابتك هي statedIntent ويتم تقييم الجدول نفسه مرة أخرى. ولهذا السبب يعود المخطط بحلقة تكرارية إلى قراءة حقائق المستودع بدلاً من القفز مباشرة إلى أحد الفروع: فإجابتك هي دليل، يُقرأ مثل أي حقيقة أخرى.

تعديلها

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

3. كيف تبدو المحادثة

شكل السؤال يأتي قبل محتواه. يحدد الوكيل الطريقة التي تفضل أن تُسأل بها — خيارات قابلة للتحديد، دردشة عادية، قراءة صوتية، خط كبير — ويسجل ذلك في interaction/interaction.json حتى لا تسألك أي جلسة مستقبلية مرة أخرى. راجع إمكانية الوصول.

بعد ذلك، عندما تكون الإجابة غامضة بحق:

أنت: أريد إنشاء folio

المساعد: يحتوي هذا الدليل بالفعل على folio بداخله (content/atlas/)، لذا إليك بعض الأمور التي قد تقصدها —

1. إضافة شيء إلى الـ folio الموجود هنا — فصل، أو مستند (يوصى به — فهذا هو المعنى الأغلب لعبارة “إنشاء …” من داخل folio)
2. إضافة folio ثانٍ إلى جانب atlas
3. بدء folio جديد في مستودع جديد
4. أخبرني بالمزيد

(عدم الإجابة لا بأس به — سأختار 1 وأعرضه عليك قبل كتابة أي شيء.)

وبعد ذلك، ما الذي ستبدأ فيه — لأن “الـ folio” ليس شيئًا يريده أي شخص في الواقع:

نوع المحتوى	ماهيته	يتطلب
paper	ورقة علمية أو كتاب، ادعاءات رسمية مدعومة بـ Lean، منضدة عبر LaTeX	مجموعة أدوات Lean، وTeX
document	نثر منظم — إرشادات سياسات، معيار، تقرير	pandoc؛ لا يتطلب Lean، ولا TeX
WHO SMART DAK	حزمة تكيّف رقمي (L2) — شخصيات، عمليات، عناصر بيانات، جداول قرارات	—
WHO SMART IG	دليل تطبيق FHIR (L3)، مبني من L2 DAK	Java، وSUSHI، وIG Publisher

راجع أنواع المحتوى لمعرفة ما توفره لك كل صياغة شكلية.

4. التثبيت والتحقق

اتبع التثبيت، ثم:

bun run cat check-deps

يجب الإفادة بوجود bun. وأي شيء يتطلبه نوع المحتوى الخاص بك ولا يتوفر يتم إدراجه مع تلميح للتثبيت — فلا يتطلب folio المستند أيًا من بنود Lean أو TeX.

5. توصيل إطار LLM الخاص بك

سجّل folio-assistant كخادم MCP — راجع توصيل إطار LLM لـ Claude Code وAntigravity وGemini CLI وعملاء MCP العامين.

الأدوات الأكثر صلة بهذه الصفحة:

الأداة	الغرض
folio_init	إنشاء هيكل folio. مسجلة كأداة عامة، لأنها تعمل قبل أن يكون للـ folio نوع محتوى
workflow_start / workflow_next / workflow_complete	تشغيل getting-started.bpmn كعملية حقيقية؛ يحدد workflow_next ما هو مفعّل الآن وأي مهارة تنفذه
work_plan_prime	إظهار خطة العمل (beans)
check_dependencies	فحص مجموعات الأدوات المثبتة
skill_list / skill_fetch	اكتشاف تعليمات المهارة وتحميلها

قائمة الأدوات الكاملة موجودة في صفحة المهارات والأدوار؛ ولا تظهر أدوات أنواع المحتوى إلا عندما يكون المحوّل المطابق نشطًا.

6. تحويل مستودع موجود لديك بالفعل

في فرع overlay، يعاين الوكيل قبل أن يلمس أي شيء:

bun run cat scan:repo            # read-only report
bun run cat scan:repo -- --json  # the same, as facts

ويصنف ما يجده في ثلاث فئات — library (مواد مصدرية كتبها شخص آخر)، وcontent (نثر تم تأليفه هنا)، وunclassified (غير مصنف).

والفئة الثالثة وُضعت عن قصد. فالمصنّف الذي يجبر كل ملف على الدخول في واحدة من فئتين تكون له دقة لا يستطيع أحد تقييمها، ويقدّم أخطاءه في صورة ملفات منقولة. أما هذا المصنف فيخبرك بما لم يتمكن من تصنيفه ويترك لك القرار.

ثم يطرح ثلاثة أسئلة، جميعها قابلة للإجابة بالاختيار، وكلها تُطرح لكل دليل بدلاً من كل ملف:

1. هل تريد الاستيراد أصلاً؟ — كل شيء، أو المصادر فقط، أو لا شيء، أو الاختيار حسب الفئة.
2. إلى أين تذهب كل مجموعة؟ — إلى library/ أو content/، بالنسبة للمجموعات التي لم يكن متأكدًا بشأنها.
3. الإبقاء في المكان نفسه، أم إعادة التنظيم؟ — الإبقاء في المكان هو التوصية المقصودة تمامًا. فالترتيب مجرد تفضيل؛ أما الرابط النسبي المعطل في ملف README فهو عيب برمجي.

لا شيء ينتقل حتى تتم الإجابة عن السؤال 3. وتلك الخطوة مميزة بالعلامة relaxable="false" في مخطط BPMN، فلا يمكن لأي حزمة محتوى إسقاطها.

الانضباط الكامل: مهارة repo-conversion.

7. رؤيته منشورًا

يجب أن ينتهي إنشاء الـ folio برابط. فور إنشاء الهيكل مباشرة:

bun run cat pages:bootstrap            # derive the address, report, no probe
bun run cat pages:bootstrap -- --wait  # probe until the site answers (bounded)

يقوم باستخلاص العنوان من harness.config.json أو المستودع البعيد origin، ويعثر على مهام سير عمل النشر بناءً على ما تفعله وليس بناءً على أسمائها، ويُبلغ عن واحدة من ثلاث حالات:

	المعنى
live	الموقع استجاب. ها هو الرابط
not yet	خطأ 404 تم قياسه — العنوان صحيح ولم يستقر البناء الأول هناك بعد
could not check	تعذر استخلاص العنوان، أو لم يتم فحص أي شيء، أو فشل الطلب

الحالة الثالثة ليست نسخة مخففة من الثانية، ولن يخبرك الوكيل “من المفترض أن يظهر قريبًا” بالاستناد إليها. فالخطأ 404 المقاس هو دليل؛ أما الطلب الفاشل فهو غياب للدليل، والمؤلف الذي يُبلغ بالحالة الخاطئة يذهب للبحث عن موقع لم يكن ليظهر أبدًا.

الحالات الثلاث نفسها تمثل جدول قرارات — decisions/pages-live-gate.dmn — وتم اختبار scripts/pages-bootstrap.ts ليتطابق معه تمامًا، بحيث لا يمكن للبرمجية النصية والجدول أن يتباعدا.

8. اجعل الصفحة المقصودة خاصة بك

تفتح الصفحة الرئيسية لموقعك بالوصف الخاص بنسختك، مرسومًا داخل الخلفية الخاصة بك. وكلاهما يأتي من ملف واحد — <name>.json في جذر المستودع — ولا يوجد أي شيء يخص قط المنصة العابس مكتوبًا في القالب. غيّر الملف؛ وستتبعه الصفحة.

عقدة markdown التي تعدّلها

// <name>.json -- the DECLARATION. Every key below is one of its top-level
// fields, which is what settles this label: it is not the folio config.
{
  "title": "My Folio",              // the left sidebar's heading
  "description": "One line.\nAnother line.",   // ← the landing markdown
  "icon": "mark-small",             // which image is the browser tab's
  "images": [ /* … */ ]
}

حقل description هو عبارة عن markdown، ويتم تصييره كما هو. وهو العقدة التي تعرضها الصفحة المقصودة؛ ولا توجد صفحة منفصلة لتظل متوافقة معها، وهذا هو المغزى — فالوصف الذي يظهر في مكانين هو وصف سينتهي به الأمر إلى الاختلاف مع نفسه.

خلفيتك الخاصة

تصبح الصورة خلفية للصفحة المقصودة بالإعلان عن role: "landing" وتحديد منفذ العرض الذي تم اقتصاصها لأجله:

{
  "id": "landing-laptop",
  "src": "docs/assets/img/my-backdrop.webp",
  "role": "landing",
  "layout": "laptop",               // also: "mobile", "card"
  "width": 1671, "height": 941,
  "textRegion": { "x": 0.205, "y": 0.285, "w": 0.625, "h": 0.235 }
}

textRegion هي المنطقة التي يمكن أن توضع فيها الكلمات بأمان، كنسب كسرية من أبعاد الصورة. وهي تُحدَّد يدويًا وليست محسوبة آليًا، لأنها تحدد أين تكون الصورة هادئة — وهو تقدير تركيبي لا يغني عنه أي تحليل للبكسلات. فخلفية الحواسيب المحمولة الخاصة بالمنصة تحتوي على سحابة أفكار ذات جزء سفلي داخلي واضح، وعلامة تشغل الثلث العلوي، وأذن قط ترتفع في أسفل يسارها؛ وقد تم تحديد المربع الذي يتجنب الثلاثة معًا من خلال تصيير خيارات مرشحة ومعاينتها بالعين. افعل الشيء نفسه مع خلفيتك.

أعلن عن متغير واحد لكل منفذ عرض. ويحمل كل منها منطقته الخاصة، لأن التركيب نفسه يتوضع بشكل مختلف في الاقتصاص الرأسي (portrait).

ثم:

bun run cat docs:harness         # push the declaration into docs/_data/
bun run cat docs:harness -- --check   # ...and fail if stale (for CI)

ثلاثة أمور لن تفعلها

ما تعلنه	ما تفعله الصفحة
خلفية مع منطقة محددة	تعرض وصفك بداخلها
خلفية بدون منطقة محددة	تعرض الصورة، وتضع الكلمات أسفلها
بدون خلفية	تعرض الكلمات وحدها

السطر الأوسط مقصود. فالنص الذي يُوضع عبر التخمين يستقر فوق القط، لذا فإن المنطقة غير المعلنة تعني “لا تقم بالتراكب فوق الصورة”، ولا تعني أبدًا “أي مكان مناسب”. ووجود folio بدون رسوم أمر عادي وليس عطلاً.

وإذا أعلنت عن متغير mobile وفتح زائر الموقع من هاتف، فسيحصل على ذلك الملف — وإذا لم تكن قد أعلنت عنه، فسيحصل على أوسع ملف متاح لديك. وهذا التراجع التنازلي هو انخفاض فعلي في الجودة، لأن منطقة الاقتصاص العريض لا تناسب الشاشة الضيقة؛ ويتم الإبلاغ عنه بدلاً من إخفائه، حتى تتمكن أداة التصيير من رفض التراكب بدلاً من وضع النص في مكان لم يختره أحد.

9. تتبع العمل باستخدام beans

يستخدم folio-assistant أداة beans كآلية وحيدة لخطة العمل — مستدامة عبر الجلسات، ومشتركة بين الوكلاء، ومودعة في المستودع.

scripts/install-beans.sh          # install the CLI if missing
beans prime                       # emit work-plan priming for agents
beans list                        # current open items
beans create "draft chapter 1"    # open an item
beans <id> --status in-progress   # claim an item

تحقق قبل أن تنشئ. يُصدر الأمر beans create معرفًا جديدًا في كل استدعاء ولا يزيل التكرار أبدًا. وإعادة تنفيذ خطوة برمجية دون التحقق من الوجود المسبق أنتج 14,688 عنصر bean مكرر في folio واحد خلال ظهيرة يوم واحد. ويوجد التحقق في مهارة todo-manager.

يُظهر خطاف SessionStart الخطة في بداية كل جلسة، وتُتيح أداة work_plan_prime في MCP الواجهة نفسها لأي وكيل متصل.

الخطوات التالية

• إمكانية الوصول — كيف يسأل الوكيل، وأداة التحكم في الإعدادات على هذا الموقع
• درس تعليمي — كتابة ورقة علمية
• كتابة مستند
• أنواع المحتوى — الصياغة الشكلية لكل مجال
• مسار عمل النشر — كل عملية في المستودع
• البنية الهندسية — المحولات، والمهارات، ونموذج الكتل البرمجية