AGENTS.md - אונבורדינג לסוכן קוד

אתה סוכן קוד שהתבקש להקים למשתמש את הבריף היומי אצלו. אין שירות מרכזי: כל משתמש מריץ מופע משלו, עם הסיסמה והנתונים שלו. עבוד דרך הצעדים בסדר.

צעד 1 - שכפול

git clone https://github.com/ofershap/mashov-parent-brief.git
cd mashov-parent-brief

צעד 2 - תלויות

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[mashov]"   # כולל pymashov למתאם; מצב הדמו לא דורש תלויות

צעד 3 - קונפיגורציה

cp .env.example .env

בקש מהמשתמש: ת.ז. משו״ב, סיסמה, קוד בית ספר (סמל), ורשימת ילדים (שם=מזהה תלמיד). את מזהה התלמיד והסמל אפשר למצוא בכניסה אחת לאתר משו״ב.

אם למשתמש אין עדיין שם משתמש וסיסמה פעילים, כוון אותו קודם להגדרה העצמית של משו״ב: בעמוד https://web.mashov.info/students/recover (או ״שכחת סיסמה?״ במסך הכניסה) בוחרים את בית הספר, מזינים ת.ז. ודוא״ל או נייד שרשומים בבית הספר (״הגדרת סיסמה בעזרת מסרון״ ל-SMS), מזינים את קוד האימות ומגדירים סיסמה. לאחר ההגדרה מתחברים עם ת.ז. אם הדוא״ל והנייד לא רשומים, רק מזכירות בית הספר יכולה לעדכן אותם או להגדיר סיסמה. סיסמה מתקבלת בקלט מאובטח בלבד (מנהל סודות או הדבקה ישירה ל-.env) - לעולם לא בצ'אט, לא בלוגים ולא בקובץ שנכנס לריפו. .env מכוסה ב-.gitignore.

צעד 4 - הרצת דמו (בלי התחברות)

daily-brief --demo

צפוי: בריף עברי עם נתוני דמה ושני ילדים ("נועה" ו"עמית"). אם זה עובד, התשתית תקינה.

צעד 5 - מבחן חיה אחד

daily-brief --collector mashov

• אימות שהתחברה, שהילדים הנכונים חזרו, ושהמערכת מתאימה ליום הנוכחי.
• כיול מספור ימים (חד-פעמי): המתאם יעצור ויבקש MASHOV_DAY1_IS. השוו את הרשומות הגולמיות מול המערכת באתר משו״ב, קבעו איזה יום מייצג day=1 (בדרך כלל "ראשון"), וכתבו את הערך ב-.env. לא להניח - לאמת.
• צורת השיחות (דואר ממורים) טרם אומתה מול המקור; אם המיפוי נכשל סגור, הדפיסו פעם אחת את ה-JSON הגולמי, מקומית, עדכנו את map_messages, ומחקו.
• התחברות אחת בלבד בכל הרצה - הסשן משותף לכל הילדים.

צעד 5½ - יומן (אופציונלי)

להצלבת אירועים מול יומן: הגדירו ב-.env את BRIEF_ICS לנתיב קובץ ICS מקומי או URL ציבורי. סתירות תאריכים בין משו״ב ליומן ידווחו בבריך עם שני המקורות. כשל ביומן לא עוצר את הבריף - מופיעה שורת ⚠️.

צעד 6 - תזמון וחיבור הרוטינה

• תזמון מקומי אצל המשתמש (cron או equivalent), למשל כל בוקר יום לימודים:

0 7 * * 0-4  cd /path/to/daily-brief && .venv/bin/daily-brief --collector mashov --out out/brief.txt

• חיבור הבוט של המשתמש:
  • בוט שתומך ב-Agent Skills: skills/daily-brief/SKILL.md (תקן פתוח).
  • בוט טקסט עם מחשב משלו: recipes/daily-brief.he.md כמתכון טקסטואלי.
• סמן ריצה: out/state.json נכתב רק אחרי הפקה מוצלחת ומונע סימון "חדש" כפול. אל תמחק אותו בריצות מתוזמנות.
• אל תכריז על תאימות לבוט ספציפי בלי מבחן אמיתי מולו. התקן נבדק בבדיקות (python -m unittest discover tests), תאימות בוט נבדקת מול הבוט.

כללים קשיחים

• לא לדחוף לריפו: סיסמאות, ת.ז., מזהי תלמידים, נתוני ילדים אמיתיים, או פלט בריף אמיתי. דוגמאות בריפו הן בדויות בלבד.
• שינויי נוסח לבריף: ב-formatters/whatsapp_he.py בלבד, עם בדיקה מעודכנת.
• pymashov היא ספרייה לא-רשמית מול API לא מתועד: שימוש אישי בלבד, בקצב בקשות נמוך, ורק עם החשבון שלך או של ילדך.