feat: update general skills/rules to adapt example course styles

.agents/rules/quera-styleguide.md

@@ -19,14 +19,22 @@
 هر درس‌نامه متنی باید ساختار زیر را رعایت کند:
 
 1. **مقدمه و قلاب (Hook):** یک موقعیت واقعی، مسئله یا چالش روزمره که ضرورت این موضوع را نشان می‌دهد.
-2. **شرح مفهوم به زبان ساده (Core Concept):** توضیح اصل موضوع بدون پرداختن به جزییات زائد. استفاده از استعاره‌ها و نمودارهای بصری (Mermaid).
+2. **شرح مفهوم به زبان ساده (Core Concept):** توضیح اصل موضوع بدون پرداختن به جزییات زائد، همراه با نمودارها و دیاگرام‌های باکیفیت برداری (SVG / پکیج diagrams).
-3. **جعبه‌های راهنما و هشدار (Admonitions):**
+3. **نمایش تصاویر و دیاگرام‌ها (Centered Image Tables):**
-   - `> [!NOTE]` برای نکات تکمیلی و پس‌زمینه
+   * قرارگیری تصویر در جدول تک‌خانه‌ای وسط‌چین مارک‌داون:
-   - `> [!TIP]` برای ترفندها و پرامپت‌های طلایی
+     ```markdown
-   - `> [!IMPORTANT]` برای ملزومات کلیدی
+     | ![عنوان تصویر](./images/diagram.png) |
-   - `> [!WARNING]` برای اشتباهات رایج و توهم‌های هوش مصنوعی (AI Hallucinations)
+     | :-: |
-4. **جعبه پرامپت نمونه (Ready-to-Use Prompt):** پرامپت‌های کپی-پیست آماده برای ادیتورهایی مثل Cursor/Claude Code.
+     | توضیح تفصیلی و آموزنده زیر تصویر. |
-5. **جمع‌بندی و گام بعدی (Summary & Action Item):** خلاصه در ۳-۴ بالت پوینت کوتاه به همراه پیش‌نمایش درس بعدی.
+     ```
+4. **جعبه‌های راهنما و هشدار (Quera Collapsible Details):**
+   * `<details class="red">` با `<summary>**هشدار: ...**</summary>` برای تله‌ها و خطاهای رایج هوش مصنوعی
+   * `<details class="green">` با `<summary>**نکته: ...**</summary>` برای نکات کلیدی و Best Practiceها
+   * `<details class="violet">` با `<summary>**بیشتر بدانید: ...**</summary>` برای مباحث عمیق‌تر
+5. **بلوک‌های کد و هایلایت خطوط (`<mark>`):**
+   * استفاده از `<mark class="green|blue|violet|yellow|red" title="...">` روی خطوط کلیدی
+   * درج بلافاصلهٔ پاراگراف نقل‌قول (`> ...`) زیر هر بلوک کد برای تشریح خط‌به‌خط
+6. **جمع‌بندی و گام بعدی (Summary & Bridge):** خلاصه در ۳-۴ بالت پوینت کوتاه به همراه پیش‌نمایش و پل ارتباطی به درس بعدی.
 
 ---
 

.agents/rules/sdd-workflow.md

@@ -31,7 +31,7 @@
    هر درس‌نامه یا تمرین در پوشهٔ اختصاصی خود در ساختار زیر قرار می‌گیرد:
    - **درس‌نامه:** `chapters/ch<XX>-<name>/<YY>-<lesson-slug>/`
      - `spec.md` (مشخصات و اهداف یادگیری)
-     - `lesson.md` (متن نهایی درس‌نامه کوئرا)
+     - `README.md` (متن نهایی درس‌نامه کوئرا کالج)
    - **تمرین داوری:** `chapters/ch<XX>-<name>/<YY>-<exercise-slug>/`
      - `spec.md` (مشخصات ورودی/خروجی، سناریو، سنجه‌های داوری)
      - `problem.md` (صورت مسئله برای دانشجو)

.agents/skills/course-sdd-planner/SKILL.md

@@ -49,9 +49,11 @@ description: >-
 
 ---
 
-## ۴. استعاره‌ها، سناریوهای ملموس و دیاگرام‌ها (Pedagogy & Visuals)
+## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
-- **داستان/استعاره ملموس:** [تشبیه موضوع به یک کار روزمره برای درک بدون پیش‌نیاز فنی]
+> **نکته:** در تدوین مشخصات، نیازی به طراحی پرامپت تصویر یا کد دیاگرام نیست. صرفاً مکان، نام فایل پیشنهادی و شرح کوتاهی از آنچه باید به تصویر کشیده شود مشخص می‌گردد تا ایجنت نویسنده با ابزارهای خود (پکیج diagrams یا قالب SVG) آن را بسازد.
-- **دیاگرام پیشنهادی (Mermaid):** [شرح فلوچارت یا نمودار مورد نیاز]
+- **تصویر کاور:** `images/cover.png` — [شرح مختصر ایده بصری کاور درس‌نامه]
+- **نمودار ۱:** `images/[diagram-slug-1].png` — **موضوع:** [شرح مختصر از مفهوم، چرخه، معماری یا فرآیندی که باید ترسیم شود]
+- **نمودار ۲:** `images/[diagram-slug-2].png` — **موضوع:** [شرح مختصر از مفهوم یا مقایسه بصری]
 
 ---
 

.agents/skills/quera-lesson-author/SKILL.md

@@ -1,66 +1,133 @@
 ---
 name: quera-lesson-author
 description: >-
-  Use this skill when drafting or refining full document-based lessons (lesson.md)
+  Use this skill when drafting or refining full document-based lessons (README.md)
-  from an approved spec.md file, following Quera College pedagogical and formatting rules.
+  from an approved spec.md file, following Quera College pedagogical, visual, and formatting standards (FastAPI College reference).
 ---
 
 # Quera Lesson Author (نگارش درس‌نامه‌های متنی کوئرا کالج)
 
-این مهارت راهنمای تبدیل یک سند مشخصات تایید شده (`spec.md`) به متن نهایی و جذاب درس‌نامه (`lesson.md`) است.
+این مهارت راهنمای جامع و استاندارد برای ایجنت‌های نویسنده است تا بتوانند یک سند مشخصات تایید شده (`spec.md`) را به یک درس‌نامهٔ کامل، جذاب، استاندارد و آمادهٔ انتشار در کوئرا کالج (`README.md`) تبدیل کنند.
+
+الگو، ساختار و لحن این راهنما دقیقاً بر اساس استانداردهای پیاده‌سازی‌شده در **دورهٔ FastAPI کوئرا کالج** تدوین شده است.
 
 ---
 
-## چک‌لیست قبل از نگارش
+## ۱. ساختار پوشه‌بندی هر درس‌نامه
-1. آیا فایل `spec.md` در پوشهٔ درس وجود دارد و اهداف آن مشخص است؟
-2. آیا شیوه‌نامه نگارش فارسی کوئرا (`.agents/rules/quera-styleguide.md`) بررسی شده است؟
 
----
+هر درس‌نامه در پوشهٔ اختصاصی خود درون فصل مربوطه قرار دارد و باید شامل فایل متن درس‌نامه و پوشهٔ تصاویر اختصاصی باشد:
 
-## ساختار نگارشی درس‌نامه (`lesson.md`)
+```text
-
+chapters/ch<XX>-<name>/<YY>-<lesson-slug>/
-```markdown
+├── spec.md           # سند مشخصات و قرارداد یادگیری درس (ورودی ایجنت)
-# [عنوان درس‌نامه]
+├── README.md         # متن کامل درس‌نامه کوئرا کالج (خروجی نهایی ایجنت)
-
+└── images/           # پوشهٔ اختصاصی تصاویر، نمودارها و دیاگرام‌های درس
-[مقدمه جذاب و قلاب داستانی: چرا این موضوع برای کسی که می‌خواهد با هوش مصنوعی محصول بسازد حیاتی است؟]
+    ├── cover.png     # تصویر کاور استاندارد درس‌نامه (یا cover.svg)
-
+    ├── [diagram-1].png / .svg
----
+    └── [diagram-2].png / .svg
-
-## [عنوان بخش اول: مفهوم اصلی به زبان ساده]
-
-[توضیح شفاف همراه با استعاره‌های روزمره و مقایسه‌های ملموس]
-
-```mermaid
-flowchart LR
-    A[ایده اولیه] --> B[پرامپت ساختاریافته]
-    B --> C[کد تولید شده با AI]
-    C --> D[بررسی و تست خروجی]
 ```
 
-> [!NOTE]
+> **نکتهٔ نام‌گذاری فایل:** فایل اصلی درس‌نامه در کوئرا کالج نامش `README.md` است (نه `lesson.md`).
-> [نکته تکمیلی درباره عملکرد هوش مصنوعی یا پیش‌زمینه مورد نیاز]
 
 ---
 
-## [عنوان بخش دوم: پیاده‌سازی عملی و کار با ابزار]
+## ۲. گردش‌کار نگارش درس‌نامه (Author Agent Workflow)
 
-[گام‌های عملی استفاده از ادیتور/ابزار به همراه تصویرسازی ذهنی]
+ایجنت نویسنده باید این ۵ گام را به ترتیب طی کند:
 
-> [!TIP]
+1. **بررسی قرارداد `spec.md`:**
-> **پرامپت پیشنهادی برای ادیتور:**
+   * اهداف یادگیری بلوم (Understand, Apply, Evaluate) را به دقت بخوانید.
-> ```text
+   * مرزهای محتوا را رعایت کنید: موارد **In-Scope** باید کامل پوشش داده شوند و به هیچ‌وجه نباید وارد موضوعات **Out-of-Scope** شوید.
-> [متن دقیق و تمیز پرامپت آماده استفاده]
+   * جدول واژگان تخصصی و اصطلاحات انگلیسی/فارسی را بررسی کنید.
-> ```
+   * لیست **جایگاه‌های تصاویر و نمودارها (Visual Placeholders)** را استخراج کنید.
+
+2. **تولید تصاویر و نمودارهای بصری (Visuals & Diagrams):**
+   * برای هر Placeholder مشخص‌شده در `spec.md`، تصویر یا دیاگرام متناظر را تولید و در پوشهٔ `images/` ذخیره کنید.
+   * از نمودارهای مدرن و تمیز با ابزارهایی مثل پکیج پایتونی `diagrams` (`https://github.com/mingrammer/diagrams`) یا کدهای برداری SVG با تم تیرهٔ کوئرا کالج (مشخصات تم در بخش ۵) استفاده کنید.
+   * هر درس‌نامه باید حتماً دارای یک تصویر کاور (`cover.png` یا `cover.svg`) و حداقل ۱ تا ۴ نمودار مفهومی باشد.
+
+3. **نگارش متن درس بر اساس کالبدشکافی کوئرا:**
+   * ساختار استاندارد بخش‌ها (قلاب داستانی، نقشه درس، مفاهیم اصلی، جعبه‌های کال‌اوت، کدهای هایلایت‌شده و جمع‌بندی) را پیاده کنید.
+
+4. **اعمال استانداردهای فرانت‌اند کوئرا (HTML & CSS Components):**
+   * جعبه‌های هشدار، نکته و بیشتر بدانید را با تگ‌های `<details class="...">` پیاده کنید.
+   * خطوط مهم کد را با تگ‌های `<mark class="...">` هایلایت نمایید.
+   * تصاویر را در جدول‌های تک‌خانه‌ای وسط‌چین همراه با کپشن تفصیلی درج کنید.
+
+5. **بازبینی نهایی و انطباق با معیارهای پذیرش (Acceptance Checklist).**
 
 ---
 
-## [عنوان بخش سوم: خطرات و توهم‌های رایج هوش مصنوعی]
+## ۳. ساختار و کالبدشکافی استاندارد درس‌نامه (`README.md`)
 
-> [!WARNING]
+متن نهایی درس‌نامه باید از این قالب دقیق پیروی کند:
-> **مراقب این تله باشید:**
-> [توضیح خطایی که ایجنت‌ها ممکن است در این مرحله مرتکب شوند و نحوه هدایت مجدد آن‌ها]
 
----
+````markdown
+# [عنوان درس‌نامه به فارسی روان]
+
+[مقدمه و قلاب داستانی (Hook): یک موقعیت ملموس، سناریوی واقعی محصولی یا پرسش کلیدی که انگیزهٔ مطالعه را در دانشجو ایجاد می‌کند. مثلاً: «فرض کنید تغییر کوچکی روی یک اندپوینت پرداخت اعمال کرده‌ایم و می‌خواهیم همان امروز آن را دیپلوی کنیم...»]
+
+| ![کاور درس‌نامهٔ [عنوان]](./images/cover.png) |
+| :-: |
+
+[نقشهٔ راه درس‌نامه (Overview): توضیح کوتاه ۲ تا ۳ جمله‌ای از اینکه در این درس قرار است چه مراحلی طی شود، چه ابزارهایی بررسی می‌شوند و در پایان دانشجو به چه خروجی ملموسی می‌رسد.]
+
+## [عنوان بخش اول: مفهوم پایه یا چرایی موضوع]
+
+[توضیح عمیق و شفاف مفهوم همراه با استعاره‌های ملموس و مقایسه‌های روزمره]
+
+| ![عنوان یا توضیح کوتاه نمودار](./images/concept-diagram.png) |
+| :-: |
+| [توضیح تفصیلی، آموزنده و چندخطی زیر نمودار که پیام کلیدی و ارتباط اجزا را بیان می‌کند.] |
+
+[ادامهٔ شرح درس...]
+
+<details class="red">
+<summary>**هشدار: [عنوان هشدار درباره خطای رایج، تله یا توهم هوش مصنوعی]**</summary>
+
+[شرح خطای رایج یا توهم ایجنت و نحوهٔ پیشگیری و مهار آن. توضیح اینکه چرا این خطا رخ می‌دهد و چطور باید رفتار صحیح را ارزیابی کرد.]
+
+</details>
+
+## [عنوان بخش دوم: پیاده‌سازی عملی، ابزارها یا کُد]
+
+[توضیح شیوهٔ استفاده از ابزار یا پیاده‌سازی گام‌به‌گام]
+
+```python app.py python
+from fastapi import FastAPI
+
+app = FastAPI()
+
+@app.get("/")
+def read_root():
+    <mark class="green" title="پاسخ ساده برای بررسی سلامت سرویس">return {"service": "online", "status": "ok"}</mark>
+```
+
+> [باکس نقل‌قول بلافاصله پس از بلوک کد: تشریح خط‌به‌خط و دقیق کدهای بالا، کارکرد هر تابع، متغیرها و رفتاری که خروجی تولید می‌کند. هرگز کد بدون توضیح رها نمی‌شود.]
+
+<details class="green">
+<summary>**نکته: [قانون طلایی یا بهترین الگو (Best Practice)]**</summary>
+
+[توضیح ترفند یا الگوی حرفه‌ای که کارایی را بالا می‌برد یا از اتلاف وقت دانشجو جلوگیری می‌کند.]
+
+</details>
+
+## [عنوان بخش سوم: مقایسه، سناریوهای خطا یا حالت‌های پیشرفته]
+
+[بررسی حالت‌های خطا، تست یا مقایسهٔ گزینه‌های مختلف]
+
+| معیار | روش الف | روش ب |
+| :-: | :-: | :-: |
+| سرعت اجرا | سریع | کند |
+| انعطاف‌پذیری | بالا | محدود |
+| هزینه | کم | بالا |
+
+<details class="violet">
+<summary>**بیشتر بدانید: [مبحث تکمیلی و معماری عمیق‌تر]**</summary>
+
+[مطالعهٔ عمیق‌تر برای دانشجویانی که می‌خواهند از پشت‌صحنه یا تاریخچه و معماری مطلع شوند.]
+
+</details>
 
 ## جمع‌بندی و گام بعدی
 
@@ -69,5 +136,110 @@ flowchart LR
 - **نکته ۲:** [خلاصه نکته کلیدی]
 - **نکته ۳:** [خلاصه نکته کلیدی]
 
-> در درس بعدی به سراغ **[عنوان درس بعد]** می‌رویم تا یاد بگیریم چگونه ...
+[پل ارتباطی به درس بعد]: در درس‌نامهٔ بعدی به سراغ **«[عنوان درس بعد]»** می‌رویم تا یاد بگیریم چطور ...
+````
+
+---
+
+## ۴. اجزای خاص رابط کاربری و فرمت‌بندی کوئرا کالج (Quera Custom UI)
+
+### ۱.۴. جدول نمایش تصاویر و دیاگرام‌ها (Centered Image Tables)
+در کوئرا کالج، تصاویر مستقیماً رها نمی‌شوند؛ بلکه همیشه درون یک جدول مارک‌داون تک‌خانه‌ای وسط‌چین با کپشن توضیحی قرار می‌گیرند:
+
+```markdown
+| ![متن جایگزین کوتاه](./images/filename.png) |
+| :-: |
+| متن توضیح تفصیلی و آموزنده زیر تصویر که پیام نمودار را تشریح می‌کند. |
 ```
+
+### ۲.۴. جعبه‌های پیام و آکاردئون‌های رنگی (`<details class="...">`)
+به جای الرت‌های مرسوم گیت‌هاب، از تگ‌های `<details>` با کلاس‌های رنگی کوئرا استفاده می‌شود:
+
+* **کلاس قرمز (`class="red"`) — هشدارها، تله‌ها و توهم‌های هوش مصنوعی:**
+  ```html
+  <details class="red">
+  <summary>**هشدار: [عنوان هشدار]**</summary>
+
+  متن هشدار و راه‌های پیشگیری از خطا...
+
+  </details>
+  ```
+
+* **کلاس سبز (`class="green"`) — نکات طلایی و شیوه‌های بهینه (Best Practices):**
+  ```html
+  <details class="green">
+  <summary>**نکته: [عنوان نکته]**</summary>
+
+  متن نکته و توصیهٔ کلیدی...
+
+  </details>
+  ```
+
+* **کلاس بنفش (`class="violet"`) — مباحث عمیق‌تر و بیشتر بدانید:**
+  ```html
+  <details class="violet">
+  <summary>**بیشتر بدانید: [مبحث تکمیلی]**</summary>
+
+  توضیحات پیشرفته و لینک به مستندات رسمی...
+
+  </details>
+  ```
+
+* **کلاس آبی (`class="blue"`) — یادداشت‌ها و پس‌زمینه‌ها.**
+
+### ۳.۴. بلوک‌های کد و هایلایت خطوط (`<mark>`)
+بلوک‌های کد به صورت سه‌تکه تعریف می‌شوند:
+````markdown
+```<زبان> <نام_فایل> <زبان>
+def example():
+    <mark class="green" title="توضیح هايلايت">کد مورد نظر برای جلب توجه</mark>
+```
+````
+* رنگ‌های مجاز برای `class`: `blue`، `green`، `violet`، `yellow`، `red`.
+* ویژگی `title`: توضیحی کوتاه که هنگام قرار گرفتن ماوس روی خط هایلایت‌شده ظاهر می‌شود.
+* **الزام حتمی:** بلافاصله زیر هر بلوک کد، یک پاراگراف نقل‌قول (`> ...`) قرار می‌گیرد که کدها را به زبان ساده تشریح می‌کند.
+
+---
+
+## ۵. راهنمای تولید و استایل دیاگرام‌ها (Visuals & SVG Styleguide)
+
+نمودارها و دیاگرام‌های درس‌نامه باید از نظر بصری فوق‌العاده باکیفیت و حرفه‌ای باشند (مانند خروجی پکیج `diagrams` یا فایل‌های SVG اختصاصی دوره FastAPI):
+
+1. **ابعاد و ساختار پایه SVG:**
+   * عرض ثابت: `width="1100"` و `viewBox="0 0 1100 <height>"` (ارتفاع معمولاً بین `360` تا `690` بسته به محتوا).
+   * پس‌زمینهٔ گرادیان تیرهٔ مدرن: از `#0B1220` به `#111B2E` با گوشه‌های گرد (`rx="20"`).
+   * فونت متن‌ها: `Segoe UI, Vazirmatn, system-ui, -apple-system, sans-serif`.
+2. **پالت رنگی المان‌ها:**
+   * رنگ‌های برجسته: آبی فیروزه‌ای (`#00BDF0`)، بنفش (`#8B5CF6`)، سبز زمردی (`#10B981`)، زرد/نارنجی (`#F59E0B`)، قرمز هشداری (`#EF4444`).
+   * رنگ متون: سفید خالص (`#FFFFFF`) برای تیترها، خاکستری روشن (`#C7D2E1` یا `#E2E8F0`) برای برچسب‌ها، خاکستری خنثی (`#8CA0B8`) برای توضیحات فرعی.
+3. **واترمارک لوگوی کوئرا:**
+   * در گوشهٔ پایین سمت راست تمام نمودارها، لوگوی وکتور کوئرا قرار می‌گیرد:
+   ```xml
+   <g transform="translate(880 378) scale(0.14)" opacity="0.92" fill="#FFFFFF">
+     <!-- مسیر وکتور لوگوی کوئرا -->
+   </g>
+   ```
+
+---
+
+## ۶. نگارش فارسی و قواعد زبانی (Persian Typography)
+
+* **اصطلاحات فنی دو زبانه:** در اولین مواجهه، واژهٔ فارسی پررنگ و انگلیسی ایتالیک داخل پرانتز می‌آید:  
+  `**تست خودکار (*Automated Testing*)**` | `**مهندسی پرامپت (*Prompt Engineering*)**`
+* **رعایت دقیق نیم‌فاصله‌ها:** در تمام افعال استمراری («می‌شود»، «می‌دانیم»)، جمع‌ها («درس‌نامه‌ها»، «ایجنت‌ها»)، پسوندهای تفضیلی («سریع‌تر»، «مهم‌ترین») و کلمات ترکیبی («تست‌کیس»، «دست‌نخورده»، «کلمه‌به‌کلمه»).
+* **گیومه‌های فارسی:** استفاده از « » برای نقل‌قول‌ها و مفاهیم خاص به جای " ".
+* **لحن:** دوستانه، اول‌شخص جمع («می‌بینیم»، «می‌سازیم»)، آموزنده و گام‌به‌گام؛ متناسب با کسی که کدنویس حرفه‌ای نیست اما قصد ساخت یک محصول کامل را دارد.
+
+---
+
+## ۷. چک‌لیست نهایی ایجنت نویسنده (Quality Gate)
+
+قبل از پایان نگارش درس‌نامه، بررسی کنید:
+- [ ] آیا تمام موارد **In-Scope** از `spec.md` پوشش داده شده و هیچ مبحث **Out-of-Scope** مطرح نشده است؟
+- [ ] آیا کاور (`images/cover.png`) و تمام دیاگرام‌های Placeholder در پوشهٔ `images/` قرار گرفته‌اند؟
+- [ ] آیا تصاویر در جدول‌های مارک‌داون تک‌خانه‌ای وسط‌چین همراه با کپشن تفصیلی درج شده‌اند؟
+- [ ] آیا حداقل دو باکس `<details class="...">` (یکی هشدار `red` و یکی نکته `green`) در متن وجود دارد؟
+- [ ] آیا بلوک‌های کد دارای `<mark>` و توضیح تحلیلی در باکس نقل‌قول (`> ...`) هستند؟
+- [ ] آیا اصطلاحات انگلیسی به همراه معادل فارسی مصوب آورده شده‌اند؟
+- [ ] آیا نیم‌فاصله‌ها و گیومه‌های فارسی به طور کامل رعایت شده‌اند؟
+- [ ] آیا در پایان درس، خلاصهٔ نکات و پیش‌نمایش درس بعدی درج شده است؟