amirbiron · Aug 20, 2026 · Aug 18, 2026 · Aug 18, 2026 · Aug 18, 2026 · Aug 19, 2026
diff --git a/AI-MAP.md b/AI-MAP.md
diff --git a/backup_menu_handler.py b/backup_menu_handler.py
@@ -270,6 +270,7 @@ async def show_backup_menu(self, update: Update, context: ContextTypes.DEFAULT_T
             pass
         await message("בחר פעולה מתפריט הגיבוי/שחזור:", reply_markup=reply_markup)
 
+    # docs:backup-callback-dispatch:start — הקטע מוטמע בתיעוד (docs/conversation-handlers.rst); אל תסיר את הסימון
     async def handle_callback_query(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
         query = update.callback_query
         user_id = query.from_user.id
@@ -301,6 +302,7 @@ async def handle_callback_query(self, update: Update, context: ContextTypes.DEFA
         elif data.startswith("backup_details:"):
             backup_id = data.split(":", 1)[1]
             await self._show_backup_details(update, context, backup_id)
+    # docs:backup-callback-dispatch:end
         elif data.startswith("backup_rate_menu:"):
             # פתיחת מסך תיוג עם 3 כפתורים (🏆 / 👍 / 🤷)
             backup_id = data.split(":", 1)[1]

diff --git a/docs/ARCHITECTURE_LAYER_RULES.md b/docs/ARCHITECTURE_LAYER_RULES.md
@@ -1,6 +1,8 @@
-# כללי שכבות – CodeBot
+---
+summary: 'מטרה: לשמור גבולות שכבות ברורים ולמנוע תלות מעגלית/דליפת תשתית.'
+---
 
-מטרה: לשמור גבולות שכבות ברורים ולמנוע תלות מעגלית/דליפת תשתית.
+# כללי שכבות – CodeBot
 
 ## שכבות
 - **domain**: ישויות, שירותים טהורים (ללא IO). אין תלות ב־handlers/infra/services/database.

diff --git a/docs/BOT_TEST_PLAN_CONTAINER.md b/docs/BOT_TEST_PLAN_CONTAINER.md
@@ -1,6 +1,8 @@
-# תכנית בדיקות לבוט – Composition Root (Container) לשירות Snippet
+---
+summary: 'מסמך זה מתאר בדיקות ידניות מהירות לבוט לאחר העברת יצירת התלויות ל־Container דומייני/אפליקטיבי. המטרה: לוודא שה־handlers צורכים את השירות מאותה נקודת אמת, בלי לשנות לוגיקה.'
+---
 
-מסמך זה מתאר בדיקות ידניות מהירות לבוט לאחר העברת יצירת התלויות ל־Container דומייני/אפליקטיבי. המטרה: לוודא שה־handlers צורכים את השירות מאותה נקודת אמת, בלי לשנות לוגיקה.
+# תכנית בדיקות לבוט – Composition Root (Container) לשירות Snippet
 
 ## איך לבדוק
 - **מטרה**: שמירה עובדת, השפה מזוהה נכון, ותצוגה/עריכה ממשיכות כרגיל.

diff --git a/docs/DEV_WEB_PUSH.md b/docs/DEV_WEB_PUSH.md
@@ -1,6 +1,8 @@
-# Web Push – Sticky Notes Reminders
+---
+summary: מסמך זה מסביר כיצד להפעיל ולבדוק התראות Web Push עבור תזכורות של Sticky Notes.
+---
 
-מסמך זה מסביר כיצד להפעיל ולבדוק התראות Web Push עבור תזכורות של Sticky Notes.
+# Web Push – Sticky Notes Reminders
 
 קישור למסמך המקורי עם דוגמאות והסברים מפורטים:
 - https://code-keeper-webapp.onrender.com/share/k8yuEWIeQ1ZqdlGP

diff --git a/docs/agents/rate-limiting.md b/docs/agents/rate-limiting.md
@@ -1,8 +1,8 @@
-# 🚦 מערכת Rate Limiting לסוכני AI ולווב
-
-מטרה: להסביר איך מפעילים ומנטרים Rate Limiting בבוט ובווב, עם דגש על Shadow Mode, ניטור וקונפיג.
-
 ---
+summary: 'מטרה: להסביר איך מפעילים ומנטרים Rate Limiting בבוט ובווב, עם דגש על Shadow Mode, ניטור וקונפיג.'
+---
+
+# 🚦 מערכת Rate Limiting לסוכני AI ולווב
 
 ## אסטרטגיה – Shadow Mode תחילה
 - הפעילו תחילה ב־Shadow Mode: סופרים פגיעות בלימיט אך לא חוסמים.

diff --git a/docs/ai-agents/guide.md b/docs/ai-agents/guide.md
@@ -1,8 +1,8 @@
-# 🤖 מדריך לסוכני AI
-
-מטרה: לקצר זמן חיבור של סוכנים לפרויקט, לשמור על איכות ועמידה במדיניות.
-
 ---
+summary: 'מטרה: לקצר זמן חיבור של סוכנים לפרויקט, לשמור על איכות ועמידה במדיניות.'
+---
+
+# 🤖 מדריך לסוכני AI
 
 ## נקודת פתיחה מהירה
 - קראו את הקובץ `.cursorrules` – הוא מגדיר כללי עבודה, פורמט תשובות וחוקי בטיחות.

diff --git a/docs/ai-guidelines.rst b/docs/ai-guidelines.rst
@@ -1,5 +1,6 @@
 הנחיות מלאות לסוכני AI
 ========================
+:summary: ההנחיות המלאות לסוכני AI שעובדים בריפו: המגבלות הקריטיות, איך מריצים פקודות, אילו כלי קבצים מאושרים, עקרונות עריכת קוד, ומדיניות הקומיטים וה-Pull Requests.
 
 מגבלות קריטיות
 --------------

diff --git a/docs/alerts.rst b/docs/alerts.rst
@@ -1,5 +1,6 @@
 התראות (Alerts)
 ================
+:summary: מערכת ההתראות: חוקי ברירת המחדל, איך מתאימים אותם, מדדי Health ו-Startup ל-Prometheus, קונפיגורציית alert_manager, ובדיקת הזרימה מקצה לקצה.
 
 סקירה מהירה
 -----------

diff --git a/docs/api/ai_explain.md b/docs/api/ai_explain.md
@@ -1,3 +1,7 @@
+---
+summary: 'שירות ה-AI שמתרגם הקשר של התראה להסבר קצר בשפה טבעית: הבקשה והתגובה של POST /api/ai/explain, האימות והבקרות, וקודי השגיאה.'
+---
+
 # 🧠 Observability AI Explain API
 
 שירות זה מספק שכבת AI רשמית שמתרגמת הקשרי התראות (Context) להסבר קצר בשפה טבעית, כולל שורש הבעיה, פעולות מומלצות ואותות תומכים. השירות נפרס כחלק מה־`webserver` (AioHTTP) תחת הנתיב `POST /api/ai/explain` ומשמש את לוח ה-Observability דרך המשתנה `OBS_AI_EXPLAIN_URL`.

diff --git a/docs/api/handlers.documents.rst b/docs/api/handlers.documents.rst
@@ -1,5 +1,6 @@
 handlers.documents module
 =========================
+:summary: מנתב קבצים שנשלחים לבוט לפי ``upload_mode``: שחזור ZIP לריפו GitHub, ייבוא ZIP, וקבצי טקסט שנשמרים דרך שכבת הקבצים. כולל ולידציה והגנות מפני 'פצצת ZIP'.
 
 תיאור כללי
 -----------

diff --git a/docs/api/index.rst b/docs/api/index.rst
@@ -1,7 +1,6 @@
 API Reference
 =============
-
-תיעוד מלא של ה-API של Code Keeper Bot.
+:summary: תיעוד מלא של ה-API של Code Keeper Bot.
 
 .. toctree::
    :maxdepth: 2

diff --git a/docs/api/modules.rst b/docs/api/modules.rst
@@ -1,5 +1,6 @@
 workspace
 =========
+:summary: אינדקס המודולים של התיעוד האוטומטי — נקודת הכניסה לעמודי ה-API שנוצרים מ-autodoc בזמן הבנייה.
 
 .. toctree::
    :maxdepth: 4

diff --git a/docs/api/refactoring_engine.rst b/docs/api/refactoring_engine.rst
@@ -1,5 +1,6 @@
 refactoring\_engine module
 ==========================
+:summary: מנוע הרפקטורינג: המדיניות והקונפיגורציה, קיבוץ לפי קוהזיה שמונע Oversplitting ו-God Class, והמקרה המיוחד של פירוק בטוח ל-models.py.
 
 מדיניות וקונפיגורציה
 ---------------------

diff --git a/docs/architecture.rst b/docs/architecture.rst
@@ -1,11 +1,6 @@
 ארכיטקטורה
 ===========
-
-סקירה כללית
-------------
-
-המערכת מורכבת מבוט Telegram, שכבת שירותים (services), שכבת נתונים (MongoDB) ואפליקציית Web.
-הזרימה העיקרית: Handlers → Services → Database.
+:summary: המערכת מורכבת מבוט Telegram, שכבת שירותים (services), שכבת נתונים (MongoDB) ואפליקציית Web. הזרימה העיקרית: Handlers → Services → Database.
 
 תרשים רכיבים (תמציתי)
 ----------------------

diff --git a/docs/architecture/clean-architecture.rst b/docs/architecture/clean-architecture.rst
@@ -1,9 +1,6 @@
 Clean Architecture ב-src
 ========================
-
-למה Clean Architecture
-----------------------
-ארכיטקטורה זו מפרידה בין לוגיקה עסקית, תזמור יישומי ותשתיות כך שניתן לבדוק יחידות קוד בנפרד, להחליף מקורות נתונים בלי לשבור את שאר המערכת ולרוץ גם בסביבות ללא MongoDB.
+:summary: ארכיטקטורה זו מפרידה בין לוגיקה עסקית, תזמור יישומי ותשתיות כך שניתן לבדוק יחידות קוד בנפרד, להחליף מקורות נתונים בלי לשבור את שאר המערכת ולרוץ גם בסביבות ללא MongoDB.
 
 תרשים שכבות
 ------------

diff --git a/docs/branch-protection-and-pr-rules.rst b/docs/branch-protection-and-pr-rules.rst
@@ -1,9 +1,6 @@
 Branch Protection & PR Rules
 ============================
-
-מטרה
------
-לרכז נהלים ברורים להגנה על ענפים (Branch Protection) ולחוקי PR בפרויקט.
+:summary: לרכז נהלים ברורים להגנה על ענפים (Branch Protection) ולחוקי PR בפרויקט.
 
 כללי ענפים
 -----------

diff --git a/docs/chatops/commands.md b/docs/chatops/commands.md
@@ -1,6 +1,8 @@
-# פקודות ChatOps
+---
+summary: 'להלן מבנה אחיד לכל פקודה: מתי להשתמש, פרמטרים, הרשאות, מה לחפש בפלט, ודוגמה קצרה אם יש ערך מוסף.'
+---
 
-להלן מבנה אחיד לכל פקודה: מתי להשתמש, פרמטרים, הרשאות, מה לחפש בפלט, ודוגמה קצרה אם יש ערך מוסף.
+# פקודות ChatOps
 
 ## כרטיסיות חיפוש (Ctrl/Cmd+K)
 - ניתן לפתוח את החיפוש הגלובלי (`Ctrl/Cmd+K`) ולמצוא כל פקודת ChatOps במהירות. הכרטיסים מוזנים מקובץ `webapp/static/data/commands.json` ולכן חובה לעדכן אותו בכל פעם שמוסיפים פקודה חדשה.

diff --git a/docs/chatops/faq.md b/docs/chatops/faq.md
@@ -1,3 +1,7 @@
+---
+summary: איך נמנעים מדליפת סודות?
+---
+
 # שאלות נפוצות
 
 **למה ChatOps?**

diff --git a/docs/chatops/observe.md b/docs/chatops/observe.md
@@ -1,6 +1,8 @@
-# ChatOps – /observe: הרחבות -v ו- -vv
+---
+summary: מסמך זה מפרט את מצב ההרחבה של הפקודה `/observe` לצורכי תחקור ומהירות תגובה בזמן אמת.
+---
 
-מסמך זה מפרט את מצב ההרחבה של הפקודה `/observe` לצורכי תחקור ומהירות תגובה בזמן אמת.
+# ChatOps – /observe: הרחבות -v ו- -vv
 
 - **מתי להשתמש**: כשצריך תמונת Observability עמוקה (ברמת מערכת) בזמן אמת, כולל הצלבת מקורות נתונים וזיהוי מגמות/חריגות.
 - **הרשאות**: מנהלים בלבד.

diff --git a/docs/chatops/overview.md b/docs/chatops/overview.md
@@ -1,3 +1,7 @@
+---
+summary: העקרונות שמאחורי ChatOps — פלט הבוט כמקור אמת, פקודה אחת לכל החלטה, ואיסור על סודות בפלטים — עם קישורים לעמודי Monitoring, Observability, Git LFS ו-Backup/Restore.
+---
+
 # ChatOps – סקירה כללית
 
 - מקור אמת בזמן אמת: נתונים מהבוט קודמים להשערות מבוססות קוד.

diff --git a/docs/chatops/permissions.md b/docs/chatops/permissions.md
@@ -1,3 +1,7 @@
+---
+summary: מי מורשה להריץ אילו פקודות ChatOps, ומהן מגבלות הקצב עליהן.
+---
+
 # הרשאות ו-Rate Limit
 
 - פקודות רגישות (מנהלים בלבד): `/errors`, `/triage`, `/rate_limit`, `/enable_backoff`, `/disable_backoff`, `/ban`, `/unban`, `/blocked`.

diff --git a/docs/chatops/playbooks.md b/docs/chatops/playbooks.md
@@ -1,3 +1,7 @@
+---
+summary: 'פלייבוקים לתרחישים נפוצים: עלייה ב-p95, שיעור שגיאות מעל אחוז, זיכרון שמטפס, שירות חיצוני איטי, ותקלה חוזרת בתוך רבע שעה.'
+---
+
 # Playbooks – תרחישים נפוצים
 
 ## p95 Latency עלה מעל הסף

diff --git a/docs/chatops/ratelimit.rst b/docs/chatops/ratelimit.rst
@@ -1,5 +1,6 @@
 הגבלת קצב לפקודות רגישות
 =========================
+:summary: העקרונות מאחורי הגבלת הקצב לפקודות רגישות, הדקורטור שמפעיל אותה, הקונפיגורציה, והשילוב בבוט.
 
 ``chatops.ratelimit`` מרכז את שכבת ההגנה הקלה נגד ספאם לפקודות רגישות
 במערכת ה-ChatOps (למשל `/deploy`, `/restart`, `/secrets`). במקום

diff --git a/docs/chatops/troubleshooting.md b/docs/chatops/troubleshooting.md
@@ -1,3 +1,7 @@
+---
+summary: שאלות נפוצות ופתרון תקלות בהפעלת פקודות ChatOps.
+---
+
 # פתרון תקלות (FAQ)
 
 - אין פלט מהבוט: ודאו הרשאות וצ'אט מותר.

diff --git a/docs/ci-cd.rst b/docs/ci-cd.rst
@@ -1,5 +1,6 @@
 CI/CD Guide
 ===========
+:summary: מדריך ה-CI/CD: החוקים הקשיחים, הסטטוסים הנדרשים ב-PR, ריכוז ה-workflows, הבדיקות המומלצות ובניית התיעוד.
 
 חוקים קשיחים
 -------------

diff --git a/docs/configuration.rst b/docs/configuration.rst
@@ -1,5 +1,6 @@
 Rate Limiting
 =============
+:summary: רפרנס הקונפיגורציה של המערכת: Rate Limiting, משתני סביבה, Pooling ו-Timeouts למסדי הנתונים ול-Redis, לקוחות ה-HTTP הסינכרוני והאסינכרוני, Flask, הבוט והמדדים.
 
 Environment variables
 ---------------------

diff --git a/docs/contributing.rst b/docs/contributing.rst
@@ -1,9 +1,6 @@
 מדריך תרומה
 ============
-
-מטרה
------
-לתת מסלול ברור לתרומות קוד, עם דגש על סוכני AI ו-CI.
+:summary: לתת מסלול ברור לתרומות קוד, עם דגש על סוכני AI ו-CI.
 
 כללים כלליים
 -------------

diff --git a/docs/conversation-handlers.rst b/docs/conversation-handlers.rst
@@ -1,9 +1,6 @@
 Conversation Handlers & States
 ==============================
-
-סקירה
------
-מסמך זה מרכז את הזרימות העיקריות של ה‑ConversationHandlers וה‑states.
+:summary: מסמך זה מרכז את הזרימות העיקריות של ה‑ConversationHandlers וה‑states.
 
 רשימת States (מבחר בפועל)
 --------------------------
@@ -161,27 +158,27 @@ Save – שלבים עיקריים
 
 .. literalinclude:: ../handlers/save_flow.py
    :language: python
-   :lines: 123-137
+   :pyobject: start_save_flow
    :caption: handlers/save_flow.py – start_save_flow
 
 .. literalinclude:: ../handlers/save_flow.py
    :language: python
-   :lines: 279-304
+   :pyobject: get_code
    :caption: handlers/save_flow.py – get_code
 
 .. literalinclude:: ../handlers/save_flow.py
    :language: python
-   :lines: 307-338
+   :pyobject: get_filename
    :caption: handlers/save_flow.py – get_filename
 
 .. literalinclude:: ../handlers/save_flow.py
    :language: python
-   :lines: 341-349
+   :pyobject: get_note
    :caption: handlers/save_flow.py – get_note
 
 .. literalinclude:: ../handlers/save_flow.py
    :language: python
-   :lines: 352-401
+   :pyobject: save_file_final
    :caption: handlers/save_flow.py – save_file_final
 
 GitHub – תפריט ושיחת העלאה
@@ -194,33 +191,36 @@ GitHub – תפריט ושיחת העלאה
 
 .. literalinclude:: ../main.py
    :language: python
-   :lines: 739-759
-   :caption: main.py – הגדרת upload_conv_handler (FILE_UPLOAD/REPO_SELECT/FOLDER_SELECT)
+   :start-after: docs:upload-conv:start
+   :end-before: docs:upload-conv:end
+   :caption: main.py – הגדרת upload_conv_handler
 
 Backup – תפריט
 ~~~~~~~~~~~~~~~
 
 .. literalinclude:: ../backup_menu_handler.py
    :language: python
-   :lines: 146-160
+   :pyobject: BackupMenuHandler.show_backup_menu
    :caption: backup_menu_handler.py – show_backup_menu
 
 .. literalinclude:: ../backup_menu_handler.py
    :language: python
-   :lines: 162-210
+   :start-after: docs:backup-callback-dispatch:start
+   :end-before: docs:backup-callback-dispatch:end
    :caption: backup_menu_handler.py – handle_callback_query (קטע ראשון)
 
 Drive – תפריט
 ~~~~~~~~~~~~~~
 
 .. literalinclude:: ../handlers/drive/menu.py
    :language: python
-   :lines: 142-187
+   :pyobject: GoogleDriveMenuHandler.menu
    :caption: handlers/drive/menu.py – GoogleDriveMenuHandler.menu
 
 .. literalinclude:: ../handlers/drive/menu.py
    :language: python
-   :lines: 188-210
+   :start-after: docs:drive-callback-open:start
+   :end-before: docs:drive-callback-open:end
    :caption: handlers/drive/menu.py – GoogleDriveMenuHandler.handle_callback (קטע ראשון)
 
 מוקשים נפוצים ופתרונות

diff --git a/docs/database-schema.rst b/docs/database-schema.rst
@@ -1,5 +1,6 @@
 Database Schema
 ===============
+:summary: סכמת מסד הנתונים: האוספים code_snippets, users, bookmarks ו-sessions, השדות בכל אחד, והאינדקסים.
 
 Collections
 -----------

diff --git a/docs/database/bookmarks-manager.rst b/docs/database/bookmarks-manager.rst
@@ -1,5 +1,6 @@
 מנהל סימניות – BookmarksManager
 ===============================
+:summary: database.bookmarks_manager.BookmarksManager הוא שכבת ה-DB הראשית שמאחורי פיצ'ר הסימניות. הוא דואג לולידציה, לאכיפת מגבלות, ליצירת אינדקסים ולסנכרון הסימניות מול שינויים בקבצי הקוד.
 
 ``database.bookmarks_manager.BookmarksManager`` הוא שכבת ה-DB הראשית
 שמאחורי פיצ'ר הסימניות. הוא דואג לולידציה, לאכיפת מגבלות, ליצירת

diff --git a/docs/database/collections-manager.rst b/docs/database/collections-manager.rst
@@ -1,5 +1,6 @@
 מנהל אוספים – CollectionsManager
 ================================
+:summary: פיצ'ר "הקולקציות שלי" נשען על database.collections_manager.CollectionsManager – שכבת שירות שמספקת CRUD מלא, חוקים חכמים, שיתוף ציבורי, ניהול פריטים ופעילות שיתופים. העמוד מסכם את המבנה כדי שיהיה קל לחבר פיצ'רים חדשים.
 
 פיצ'ר "הקולקציות שלי" נשען על ``database.collections_manager.CollectionsManager`` –
 שכבת שירות שמספקת CRUD מלא, חוקים חכמים, שיתוף ציבורי, ניהול פריטים

diff --git a/docs/database/cursor-pagination.rst b/docs/database/cursor-pagination.rst
@@ -2,6 +2,7 @@
 
 Cursor-based Pagination (created_at / _id)
 ==========================================
+:summary: דפדוף מבוסס קורסור על created_at ו-_id: עקרונות מיון יציב, קידוד ופענוח הקורסור, תבניות שאילתה לשני הכיוונים, ודוגמת PyMongo מלאה.
 
 למה?
 -----

diff --git a/docs/database/detailed-schema.rst b/docs/database/detailed-schema.rst
@@ -1,10 +1,6 @@
 מבנה נתונים מפורט (Detailed Database Schema)
 ==============================================
-
-סקירה כללית
-------------
-
-מסמך זה מתאר בפירוט את כל האוספים, השדות, האילוצים והאינדקסים במסד הנתונים.
+:summary: מסמך זה מתאר בפירוט את כל האוספים, השדות, האילוצים והאינדקסים במסד הנתונים.
 
 אוסף: code_snippets
 --------------------

diff --git a/docs/database/index.rst b/docs/database/index.rst
@@ -1,7 +1,6 @@
 Database
 ========
-
-תיעוד של מערכת מסד הנתונים והמודלים.
+:summary: תיעוד של מערכת מסד הנתונים והמודלים.
 
 Database Manager
 ----------------
-Original file line number
+Diff line change
@@ Expand Up / @@ -2,6 +2,7 @@ @@
     Cursor-based Pagination (created_at / _id)
     ==========================================
+    :summary: דפדוף מבוסס קורסור על created_at ו-_id: עקרונות מיון יציב, קידוד ופענוח הקורסור, תבניות שאילתה לשני הכיוונים, ודוגמת PyMongo מלאה.
     למה?
     -----
@@ Expand Down @@