---
name: hr-documenter
description: >
  סקיל גנרי לתיעוד entities ב-Notion databases של המשתמש — skills, knowledge, workflows, agents,
  rules, integrations, databases, מחלקות (כל 8 הדאטהבייסים של תבנית המשרד).
  כולל מתודולוגיית אימפרוב מלאה: עצי החלטה, סכמת properties, תבניות body, ומפת DUAL relations.
  בהפעלה ראשונה יוצר קובץ config מקומי עם ה-DB IDs, התבניות, והשדות של המשתמש.
  בכל הפעלה אחרי — קורא את ה-config ומתעד בדיוק לפי המבנה שהוגדר.
  הפעל כשהמשתמש אומר "תתעד", "register", "תוסיף ל-DB", "תרשום בנוטיון",
  "document this", "add to office", "תכניס ל-DB", או כשנוצר entity חדש.
  גם כשסקיל אחר קורא לך (מצב שקט) — עבוד ישירות בלי שאלות מיותרות.
  מצב סריקת-ריפו-מלא (הגירה / גרסה ידנית): כשהמשתמש אומר "מפה את כל הריפו",
  "בנה את המשרד בנושן", "העבר את הכל לנושן", "ירדתי מהמנוי", "גרסה ידנית",
  "map my whole repo", "migrate everything to notion" - סורק את כל הריפו
  (agents / skills / knowledge / workflows / integrations / databases / rules) ובונה את טבלת המשרד המלאה בבת אחת (שלב 5).
version: 2.4.1
---

# HR Documenter — תיעוד entities ב-Notion של המשתמש

> סקיל גנרי — עובד עם כל מבנה Notion. ה-config מותאם למשתמש.
> כולל מתודולוגיית אימפרוב מלאה לסיווג, מילוי שדות, וכתיבת body תקני.

---

## זרימה ראשית

```
הפעלה →
├── מצב סריקת-ריפו-מלא? ("מפה את כל הריפו" / "גרסה ידנית" / "ירידה") → שלב 5
├── חפש .office/notion-config.md
│   ├── לא קיים → שלב 1 (אונבורדינג)
│   └── קיים → קרא config
│       ├── הופעל על-ידי סקיל אחר (מצב שקט)? → שלב 2 ישירות, בלי שאלות
│       └── הופעל על-ידי המשתמש? → שלב 2 עם שאלות כשצריך
└── אחרי תיעוד → שלב 3 (ולידציה)
```

**מצב שקט:** כשסקיל אחר מפעיל את hr-documenter (לא המשתמש ישירות), הסקיל מקבל את כל הנתונים כפרמטרים ומתעד ישירות. לא שואל שאלות. אם חסר מידע קריטי — מחזיר שגיאה לסקיל הקורא.

---

## מתודולוגיית אימפרוב — עצי החלטה

### scope: role-specific vs cross-cutting

```
האם ה-entity שייך ספציפית לסוכן אחד?
├── כן → role-specific (חובה: office_owner_agent relation)
└── לא, כמה סוכנים / כל המשרד → cross-cutting (owner ריק)
```

### form (סקילים בלבד): procedural vs rules vs declarative

```
כיצד ה-skill עובד?
├── שלבים קבועים בסדר מוגדר → procedural
├── הנחיות גמישות שאפשר ליישם בסדר שונה → rules
└── הצהרת מצב רצוי (מה צריך להיות, לא איך) → declarative
```

### kind (ידע בלבד): static vs dynamic

```
כיצד המסמך מתעדכן?
├── ידנית, רק כשאסטרטגיה/מציאות משתנה → static
└── אוטומטית / תכוף (DB, API, feedback) → dynamic
```

### shelf (ידע בלבד)

```
על מה המסמך?
├── זהות, חזון, ערכים, DNA → identity-vision
├── קהל יעד, פרסונות, צרכים → audience
├── מתחרים, שוק → competitors
├── טון, שפה, סגנון → voice-style
├── מוצרים, שירותים, הצעת ערך → products
├── אסטרטגיית תוכן, ערוצים → content-strategy
├── נתוני שיווק, אנליטיקס → marketing-data
├── תבניות, פורמטים → templates
├── למידה, הדרכה, פדגוגיה → pedagogy
└── שום דבר מהנ"ל → other
```

### subdivision (סקילים, workflows, agents בלבד — לא ב-ידע!)

```
לאיזה תחום תוכן?
├── רשתות חברתיות → social
├── פודקאסט → podcast
├── קורסים → courses
├── בלוג → blog
├── ספריית ידע → library
├── כלים טכניים → toolbox
└── לא שייך לתחום ספציפי → (לא למלא)
```

### department

```
8 ערכים: קריאייטיב | שיווק | פדגוגיה | מכירות | שירות לקוחות | צוות אישי | HR / תחזוקה | תשתית
```

### agent_role (סוכנים בלבד): doer vs companion

```
מה התוצר של הסוכן?
├── קובץ / תוצר מוחשי (ריל, מייל, מדריך, פודקאסט, קוד) → doer
└── שיחה / ליווי / ייעוץ / אתגור — השיחה עצמה היא התוצר → companion
```

### kind (סוכנים בלבד) — שדה ישן (legacy)

`kind` עם הערכים `partner` / `process` הוא **ציר הטריגר** בשמות הישנים, לא ציר עצמאי:
- `partner` = `trigger=interactive` (הסוכן מדבר עם אדם)
- `process` = `trigger=automatic` (רץ ברקע בלי אינטראקשן)

**לא ממלאים לפי שאלה נפרדת** — הערך נגזר מ-`trigger` שנקבע בעץ למטה.
ב-DB: לשמור בינתיים לתאימות לאחור. בעתיד ייוחלף לחלוטין ע"י `agent_role` + `trigger`.

### trigger (סוכנים בלבד): interactive vs automatic

```
מי מפעיל את הסוכן?
├── אדם פותח שיחה / מקליד פקודה → interactive
└── תזמון / webhook / אירוע מערכת → automatic
```

### pattern (סוכנים מבצעים בלבד): A vs A-hybrid vs B vs C

```
כמה תוצרים ומה המורכבות?
├── סוכן אוטומטי (trigger=automatic, cron/webhook) → C (תמיד Solo)
├── תוצר אחד ישיר, ללא צוות → C (Solo)
│   דוגמאות: שלמו (כותב), נתן (אסטרטגיה)
├── תוצר אחד מורכב, כמה "כובעים" באותה שיחה → B (מומחה רב-תחומי)
│   דוגמאות: אסף (מגיש / עורך / חוקר)
├── כמה תוצרים שונים, sub-agents עצמאיים עם system-prompt משלהם → A (מחלקה)
│   דוגמאות: בצלאל (ריל / סטורי / מגנט)
└── כמה מודולים/workflows בתוך אותו סוכן, לא עצמאיים לגמרי → A-hybrid
    דוגמאות: סוכן עם מודולים M1/W1 שחולקים context

ההבדל A vs B:
  A = sub-agents עצמאיים, system-prompt משלהם, context נפרד
  B = פרסונות באותה שיחה, החלפת "כובע" באותו context

ההבדל A vs A-hybrid:
  A = sub-agents לגמרי עצמאיים
  A-hybrid = מודולים מובנים בתוך הסוכן, עם workflows, אבל לא עצמאיים לגמרי
```

### runtime (סוכנים, אופציונלי)

```
איפה הסוכן רץ?
├── שרת ענן (KaaS, API) → production-cloud
├── Mac מקומי עם launchd/cron → active-launchd
├── ידנית בלבד (CLI, Cursor) → manual-dev
└── לא רץ עדיין / ב-plan → none
```

---

## סכמת Properties — לפי DB

### DB ידע (Knowledge)

| Property | Type | חובה | ערכים |
|---|---|---|---|
| `Title` | title | ✅ | — |
| `type` | select | ✅ | `knowledge` |
| `scope` | select | ✅ | `role-specific` / `cross-cutting` |
| `kind` | select | ✅ | `static` / `dynamic` |
| `shelf` | select | ✅ | 10 ערכים (ראה עץ למעלה) |
| `status` | select | ✅ | `ready` / `in-progress` / `archived` |
| `description` | text | ✅ | 1-2 משפטים |
| `github_path` | text | ⬜ | — |
| `office_owner_agent` | relation | 🟡 role-specific בלבד | → DB סוכנים |
| `derived_skills` | relation | ⬜ | DUAL reverse |
| `workflows_using` | relation | ⬜ | DUAL reverse |
| `derived_rules` | relation | ⬜ | DUAL reverse |

**⚠️ אסור:** `subdivision` לא קיים ב-DB ידע.

### DB סקילים (Skills)

| Property | Type | חובה | ערכים |
|---|---|---|---|
| `Title` | title | ✅ | — |
| `name` | text | ✅ | slug באנגלית |
| `display_name` | text | ⬜ | שם תצוגה |
| `type` | select | ✅ | `skill` |
| `scope` | select | ✅ | `role-specific` / `cross-cutting` |
| `form` | select | ✅ | `procedural` / `rules` / `declarative` |
| `department` | select | ✅ | 8 ערכים |
| `subdivision` | select | ⬜ | 6 ערכים |
| `status` | select | ✅ | `ready` / `in-progress` / `archived` |
| `description` | text | ✅ | 1-2 משפטים |
| `github_path` | text | ⬜ | — |
| `office_owner_agent` | relation | 🟡 role-specific | → DB סוכנים |
| `derived_from_knowledge` | relation | ⬜ | → DB ידע (DUAL: derived_skills) |
| `references` | relation (self) | ⬜ | → skills אחרים |

### DB Workflows

| Property | Type | חובה | ערכים |
|---|---|---|---|
| `Title` | title | ✅ | — |
| `name` | text | ✅ | slug באנגלית |
| `type` | select | ✅ | `workflow` |
| `department` | select | ✅ | 8 ערכים |
| `subdivision` | select | ⬜ | 6 ערכים |
| `status` | select | ✅ | `ready` / `in-progress` / `archived` |
| `description` | text | ✅ | — |
| `steps` | text | ⬜ | סיכום טקסטואלי |
| `github_path` | text | ⬜ | — |
| `office_owner_agent` | relation | ✅ | → DB סוכנים |
| `uses_skills` | relation | ⬜ | → DB סקילים (DUAL: used_by_workflows) |
| `uses_knowledge` | relation | ⬜ | → DB ידע (DUAL: workflows_using) |

### DB סוכנים (Agents)

| Property | Type | חובה | ערכים |
|---|---|---|---|
| `שם` | title | ✅ | — |
| `name` | text | ✅ | slug |
| `type` | select | ✅ | `agent` |
| `kind` | select | ⚠️ legacy | `partner` / `process` — נגזר מ-trigger (interactive→partner, automatic→process) |
| `pattern` | select | ✅ | `A` / `A-hybrid` / `B` / `C` |
| `trigger` | select | ✅ | `interactive` / `automatic` |
| `agent_role` | select | ✅ | `doer` / `companion` |
| `runtime` | select | ⬜ | `production-cloud` / `active-launchd` / `manual-dev` / `none` |
| `subdivision` | select | ⬜ | 6 ערכים |
| `status` | select | ✅ | `ready` / `in-progress` / `archived` |
| `description` | text | ✅ | — |
| `persona` | text | ⬜ | — |
| `voice` | text | ⬜ | — |
| `personas_list` | text | 🟡 Pattern B | — |
| `github_path` | text | ⬜ | — |
| `department` | relation (multi) | ✅ | → DB מחלקות (page IDs מה-config) |
| `skills` | relation | ⬜ | → DB סקילים (DUAL: office_owner_agent) |
| `workflows` | relation | ⬜ | → DB Workflows (DUAL: office_owner_agent) |
| `knowledge` | relation | ⬜ | → DB ידע (DUAL: office_owner_agent) |

### DB Rules

| Property | Type | חובה | ערכים |
|---|---|---|---|
| `שם` | title | ✅ | — |
| `name` | text | ✅ | slug (e.g. `hebrew-arrows`) |
| `type` | select | ✅ | `rule` |
| `always_apply` | checkbox | ✅ | `"__YES__"` / `"__NO__"` |
| `scope` | select | ✅ | `infrastructure` / `behavior` / `format` / `process` / `documentation` |
| `affects_all_agents` | checkbox | ⬜ | `"__YES__"` / `"__NO__"` |
| `status` | select | ✅ | `ready` / `in-progress` / `archived` |
| `description` | text | ✅ | — |
| `github_path` | text | ✅ | `.cursor/rules/...` |
| `activates_skills` | relation | ⬜ | → DB סקילים |
| `affects_agents` | relation | ⬜ | → DB סוכנים |
| `derived_from_knowledge` | relation | ⬜ | → DB ידע |

> ⚠️ שלוש הסכמות הבאות אומתו מול תבנית-המשרד החיה בנושן (09-08-2026). הן
> **שונות** מהדפוס של חמש הראשונות - אין בהן `type`, אין `github_path`,
> וה-scope מוחלף לרוב ב-`home_department`. לא להשלים שדות "לפי ההיגיון של
> הסכמות האחרות" - שדה שלא קיים בטבלה יזרוק שגיאה.

### DB Integrations (🔌)

**מה זה:** שירות חיצוני שהמשרד מתחבר אליו (OpenAI, Notion, Gmail). ה-*חיבור*, לא הנתונים.

| Property | Type | חובה | ערכים |
|---|---|---|---|
| `שם` | title | ✅ | שם השירות כפי שמכירים אותו (OpenAI, Gmail) |
| `name` | text | ✅ | slug באנגלית - `openai`, `gmail`, `notion-api` |
| `provider` | text | ⬜ | שם הספק - OpenAI, Google, Notion Inc. |
| `category` | select | ⬜ | `llm` / `email` / `storage` / `video` / `automation` / `payment` / `analytics` / `crm` / `infrastructure` / `other` |
| `auth_type` | select | ⬜ | `api_key` / `oauth2` / `bearer_token` / `cookie` / `none` |
| `env_key_name` | text | ⬜ | **שם משתנה הסביבה בלבד** - `OPENAI_API_KEY`. לעולם לא הערך |
| `home_department` | select | ⬜ | 8 המחלקות (קריאייטיב / שיווק / פדגוגיה / מכירות / שירות לקוחות / צוות אישי / HR / תחזוקה / תשתית) |
| `status` | select | ✅ | `active` / `inactive` / `evaluating` / `deprecated` |
| `description` | text | ✅ | מה השירות נותן למשרד, 1-2 משפטים |
| `cost_model` | select | ⬜ | `free` / `freemium` / `subscription` / `usage_based` |
| `homepage_url` · `docs_url` · `logo_url` | url | ⬜ | — |
| `notes` | text | ⬜ | — |
| `added_date` | date | ⬜ | — |
| `hosts_databases` | relation | ⬜ | → DB Databases (DUAL: hosted_by_integration) |
| `used_by_agents` | relation | ⬜ | → DB סוכנים (DUAL: uses_integrations) |
| `used_by_workflows` | relation | ⬜ | → DB Workflows (DUAL: uses_integrations) |
| `used_by_skills` | relation | ⬜ | → DB סקילים (DUAL: uses_integrations) |

**⚠️ אין בטבלה:** `type`, `scope`, `github_path`. אל תנסה לכתוב אותם.
**⚠️ אסור:** לעולם לא לכתוב ערך של מפתח/סוד. `env_key_name` = שם המשתנה בלבד.

### DB Databases (🗄️)

**מה זה:** מאגר נתונים שהמשרד קורא ממנו או כותב אליו (בסיס Airtable, פרויקט Supabase, קובץ SQLite). ה-*נתונים*, להבדיל מהחיבור.

| Property | Type | חובה | ערכים |
|---|---|---|---|
| `שם` | title | ✅ | שם המאגר |
| `name` | text | ✅ | slug באנגלית - `transcripts`, `sales-calls` |
| `platform` | select | ⬜ | `notion` / `airtable` / `postgresql` / `sqlite` / `csv` / `other` |
| `category` | select | ⬜ | `transcripts` / `crm` / `content` / `analytics` / `meta` / `config` / `other` |
| `scope` | select | ⬜ | `role-specific` / `cross-cutting` |
| `status` | select | ✅ | `active` / `inactive` / `archived` |
| `description` | text | ✅ | **מה נשמר בו** + מי קורא/כותב, 1-2 משפטים |
| `home_department` | select | ⬜ | 8 המחלקות |
| `schema_summary` | text | ⬜ | תיאור הטבלאות / השדות העיקריים |
| `internal_db_id` | text | ⬜ | אם ב-Notion - ה-data_source_id |
| `external_url` | url | ⬜ | — |
| `record_count_approx` | number | ⬜ | — |
| `notes` | text | ⬜ | — |
| `added_date` | date | ⬜ | — |
| `hosted_by_integration` | relation | ⬜ | → DB Integrations (DUAL: hosts_databases) |
| `written_by_agents` | relation | ⬜ | → DB סוכנים (DUAL: databases_written) |
| `read_by_agents` | relation | ⬜ | → DB סוכנים (DUAL: databases_read) |
| `used_by_skills` | relation | ⬜ | → DB סקילים (DUAL: uses_databases) |
| `used_by_workflows` | relation | ⬜ | → DB Workflows (DUAL: uses_databases) |

**⚠️ אין בטבלה:** `type`, `github_path`. **⚠️ אסור:** מזהי-בסיס סודיים, connection strings או סיסמאות.

### DB מחלקות (🏛️)

**מה זה:** חדרי המשרד. נוצרות באונבורדינג (שלב 1) ומזהי הדפים נשמרים ב-`department_page_ids`. **לא נסרקות מהריפו** - סוכן משויך אליהן דרך `department`.

| Property | Type | חובה | ערכים |
|---|---|---|---|
| `Title` | title | ✅ | **שים לב: `Title`, לא `שם`** - היחיד מבין ה-4 האלה |
| `name` | text | ✅ | slug באנגלית |
| `type` | select | ✅ | `department` (הערך היחיד) |
| `kind` | select | ⬜ | `regular` / `infrastructure` |
| `color` | text | ⬜ | — |
| `status` | select | ✅ | `ready` / `in-progress` / `archived` |
| `office_agents` | relation | ⬜ | → DB סוכנים (DUAL: department) |
| `parent_department` · `sub_departments` | relation (self) | ⬜ | היררכיית מחלקות |

**⚠️ אין בטבלה:** `description`. **⚠️ אסור:** ליצור מחלקה חדשה במהלך סריקה (שלב 5). סוכן שלא משתייך לאף מחלקה קיימת - שייך לכללית ביותר שמתאימה ורשום בדו"ח, אל תמציא מחלקה.

---

## DUAL Relations Map

| מקור | יעד | property | reverse |
|---|---|---|---|
| Skills | Knowledge | `derived_from_knowledge` | `derived_skills` |
| Skills | Skills (self) | `references` | `referenced_by` |
| Workflows | Skills | `uses_skills` | `used_by_workflows` |
| Workflows | Knowledge | `uses_knowledge` | `workflows_using` |
| Agents | Skills | `skills` | `office_owner_agent` |
| Agents | Workflows | `workflows` | `office_owner_agent` |
| Agents | Knowledge | `knowledge` | `office_owner_agent` |
| Agents | Agents (self) | `parent_agent` | `sub_agents` |
| Rules | Skills | `activates_skills` | `activated_by_rules` |
| Rules | Agents | `affects_agents` | `affected_by_rules` |
| Rules | Knowledge | `derived_from_knowledge` | `derived_rules` |
| Integrations | Agents | `used_by_agents` | `uses_integrations` |
| Integrations | Workflows | `used_by_workflows` | `uses_integrations` |
| Integrations | Skills | `used_by_skills` | `uses_integrations` |
| Databases | Agents | `written_by_agents` | `databases_written` |
| Databases | Agents | `read_by_agents` | `databases_read` |
| Databases | Skills | `used_by_skills` | `uses_databases` |
| Databases | Workflows | `used_by_workflows` | `uses_databases` |
| Integrations | Databases | `hosts_databases` | `hosted_by_integration` |
| מחלקות | Agents | `office_agents` | `department` |

---

## תבניות Body

### תבנית Body — DB סקילים

```notion-blocks
[paragraph, bold]
scope: [role-specific/cross-cutting] | form: [procedural/rules/declarative] | עודכן: DD בMM YYYY | owner: [סוכן, אם role-specific]

[heading_2] 📋 סקירה
[paragraph] מה ה-skill עושה ב-1–2 משפטים — פעולה ספציפית, לא תיאור עמום.

[heading_2] 🎯 מה ה-skill מבצע
--- אם form=procedural: ---
[numbered_list]
1. צעד 1: ...
2. צעד 2: ...
3. צעד 3: ...
--- אם form=rules: ---
[bulleted_list]
• כלל 1: ...
• כלל 2: ...

[heading_2] 📥 קלט / 📤 פלט
[bulleted_list]
• קלט: [טקסט / תמלול / רשימה / שאלה]
• פלט: [מסמך / רשימה / החלטה / קוד]

[heading_2] 🗣️ מתי מפעילים אותו
[bulleted_list]
• תרחיש 1: ...
• תרחיש 2: ...

[heading_2] ❌ מתי לא להשתמש
[callout, icon=❌, color=red_background]
• ❌ לא בשביל [תרחיש שגוי] → [skill אחר]
• ❌ לא בשביל [תרחיש שגוי 2] → [skill אחר]

[heading_2] 🔗 קשרים ב-DB
[table: 2 columns — Property | ערך]
| scope | role-specific / cross-cutting |
| form | procedural / rules |
| owner_agent (relation) | [שם — חובה ב-role] |
| department | [ערך] |
| references (self-relation) | [skills אחרים שמופעלים] |
| derived_from_knowledge (relation) | [knowledge מקור] |

[heading_2] 📝 לוג עדכונים
[callout, icon=🔍, color=blue_background]
🔍 שיפור 1 — [כותרת תמציתית] (DD בMM YYYY)
[תיאור + קבצים שעודכנו]

[heading_2] 🗣️ הוראות לקלוד — מאיפה להתחיל
[callout, icon=🗣️, color=purple_background]
כשמבקשים ממך עזרה עם ה-skill הזה — התחל בסדר:
1. קרא את 📝 לוג עדכונים — שינוי אחרון? אולי שם הבעיה.
2. בדוק ❌ מתי לא להשתמש — וודא שזה ה-skill הנכון.
3. קרא את 🎯 מה ה-skill מבצע — הצעדים/הכללים.
4. בדוק 📥 קלט / 📤 פלט — האם הקלט שניתן מתאים?
5. אם נכשל: הקובץ ב-github_path. knowledge מקור: derived_from_knowledge.
```

### תבנית Body — DB ידע

```notion-blocks
[paragraph, bold]
scope: [role-specific/cross-cutting] | kind: [static/dynamic] | shelf: [מדף] | עודכן: DD בMM YYYY

[heading_2] 📋 סקירה
[paragraph] מה המסמך מכיל ב-1–2 משפטים.

[heading_2] 🎯 מה יש בפנים (TOC)
[bulleted_list]
• חלק 1 — [נושא] — תיאור קצר
• חלק 2 — [נושא] — תיאור קצר
• חלק 3 — [נושא] — תיאור קצר

[heading_2] 🔗 איפה זה משמש
[table: 2 columns — מי צורך | למה]
| [סוכן 1] | [שימוש 1] |
| [סוכן 2] | [שימוש 2] |

[heading_2] 📝 מתי מעדכנים
[bulleted_list]
• kind=static: עדכון רק כשהאסטרטגיה משתנה
• kind=dynamic: עדכון תכוף — [קצב צפוי]

[heading_2] ❌ מה זה לא
[callout, icon=❌, color=red_background]
• ❌ לא [מסמך אחר שאפשר להתבלבל] — ההבדל: [...]
• ❌ לא [תרחיש שגוי] → [knowledge נכון]

[heading_2] 🔗 קשרים ב-DB
[table: 2 columns — Property | ערך]
| scope | cross-cutting / role-specific |
| kind | static / dynamic |
| shelf | [ערך] |
| owner_agent (relation) | [רק ב-role-specific] |
| derived_skills (relation) | [skills שמתבססים על זה] |

[heading_2] 📝 לוג עדכונים
[callout, icon=📊, color=blue_background]
📊 עדכון 1 — [כותרת] (DD בMM YYYY)
[מה נוסף / שונה]

[heading_2] 🗣️ הוראות לקלוד — מאיפה להתחיל
[callout, icon=🗣️, color=purple_background]
כשצריך עזרה עם המסמך הזה:
1. קרא את 📋 סקירה + 🎯 TOC — האם זה המסמך הנכון?
2. בדוק ❌ מה זה לא — אולי המסמך הנכון הוא אחר.
3. קרא 📝 מתי מעדכנים — אם dynamic, אולי לא עדכני.
4. בדוק 📝 לוג עדכונים — מתי נערך לאחרונה?
5. אם המידע לא מספיק: skills גזורים ב-derived_skills. knowledge קשור באותו shelf.
```

### תבנית Body — DB Workflows

```notion-blocks
[paragraph, bold]
owner: [סוכן] | גרסה: X.Y | עודכן: DD בMM YYYY | סטטוס: [תיאור קצר]

[heading_2] 📋 סקירה
[paragraph] מה ה-workflow עושה ומתי מפעילים אותו.

[heading_2] 🎬 טריגר
[bulleted_list]
• מתי מופעל: [תנאי]
• תנאים מקדימים: [מה צריך להיות מוכן]

[heading_2] 🔄 צעדים
[toggle/numbered_list per step]
שלב 1 — [שם]:
• מה עושים: ...
• skill שמופעל: [skill] (אם רלוונטי)
• 🚦 gate: [מה צריך לעבור]

שלב 2 — [שם]:
...

[heading_2] 📥 קלט / 📤 פלט
[bulleted_list]
• קלט: [מה ה-workflow מקבל]
• פלט: [מה הוא מספק]

[heading_2] 🔍 פתרון בעיות
[callout, icon=🔧, color=blue_background]
• תסמין: [שלב X תקוע] → פעולה: [בדיקה / תיקון]
• תסמין: [פלט לא תקין] → פעולה: ...

[heading_2] ❌ מה ה-workflow לא עושה
[callout, icon=❌, color=red_background]
• ❌ לא [פעולה X] → workflow אחר: [שם]
• ❌ לא [פעולה Y] → skill: [שם]

[heading_2] 🔗 קשרים ב-DB
[table: 2 columns — Property | ערך]
| owner_agent (relation, חובה) | [סוכן] |
| department | [ערך] |
| subdivision | [אם רלוונטי] |
| uses_skills (relation) | [skills שמופעלים] |
| uses_knowledge (relation) | [knowledge רלוונטי] |

[heading_2] 📝 לוג עדכונים
[callout, icon=🔧, color=blue_background]
🔧 תיקון 1 — [כותרת] (DD בMM YYYY)
[תיאור + קבצים]

[heading_2] 🗣️ הוראות לקלוד — מאיפה להתחיל
[callout, icon=🗣️, color=purple_background]
כשצריך עזרה עם ה-workflow:
1. קרא 📝 לוג עדכונים — תיקון אחרון?
2. בדוק 🎬 טריגר — הופעל מהמקום הנכון?
3. בדוק ❌ מה לא עושה — בתחום?
4. קרא 🔄 צעדים — באיזה שלב נתקע?
5. אם נכשל: skills בשלבים (uses_skills), owner agent system-prompt.
```

### תבנית Body — DB סוכנים

```notion-blocks
[paragraph, bold]
גרסה: X.Y | עודכן: DD בMM YYYY | סטטוס: [תיאור קצר]

[heading_2] 📋 סקירה
[paragraph] מה הסוכן עושה ותפקידו ב-1–2 פסקאות.

[heading_2] 🎛️ Submenu — מסלולים / מודולים / אייג'נטים
[table: 3 columns — Submenu item | תיאור קצר | קישור פנימי]
דפוס A-hybrid → מודולים: M1/W1...
דפוס B → sub-agents/פרסונות
דפוס C → workflow שטוח ← skills ממוספרים

[heading_2] 🔄 איך הסוכן עובד
[numbered_list]
1. המשתמשת פותחת שיחה → תפריט
2. בחירה במסלול → שאלות
3. ביצוע → פלט
4. (gate / אישור / עדכון knowledge)

[heading_2] 📚 מסמכי ידע שהסוכן צורך
[bulleted_list]
• [knowledge-1] — למה מצורף
• [knowledge-2] — למה מצורף

[heading_2] ❌ מה לא בתחום הסוכן
[callout, icon=❌, color=red_background]
[שם] הוא [תפקיד מובחן] — לא [פעולה שלילית].
• ❌ לא [פעולה X] → [סוכן אחר]
• ❌ לא [פעולה Y] → [סוכן אחר]

[heading_2] 🔗 קשרים ב-DB
[table: 2 columns — Property | ערך]
| department | [ערך] |
| subdivision | [אם רלוונטי] |
| kind | [נגזר: partner=interactive / process=automatic] |
| pattern | A-hybrid / B / C |
| trigger | interactive / automatic |
| agent_role | doer / companion |
| skills (relation) | [skills role-specific] |
| workflows (relation) | [workflows] |
| knowledge (relation) | [knowledge role-specific] |

[heading_2] 📝 לוג עדכונים
[callout, icon=🔍, color=blue_background]
🔍 שיפור 1 — [כותרת] (DD בMM YYYY)
[תיאור: מה השתנה ולמה]
קבצים שעודכנו: [רשימה]

[heading_2] 🗣️ הוראות לקלוד — מאיפה להתחיל
[callout, icon=🗣️, color=purple_background]
כשצריך עזרה עם [שם הסוכן]:
1. קרא 📝 לוג עדכונים — שיפור אחרון?
2. בדוק ❌ מה לא בתחום — בקשה בכלל בתחום?
3. קרא 🎛️ Submenu — איזה מסלול אמור לטפל?
4. בדוק 🔄 איך עובד — שלבי אינטראקציה.
5. אם נכשל: system-prompt + workflows + knowledge ב-relations.
```

---

## עיקרון אוטונומיה — החלט, אל תשאל

הסקיל הזה משרת משתמשים שלא מבינים את מבנה ה-Notion ולא צריכים להבין אותו. **ההנחיה המרכזית:**

1. **החלט לבד** — אם אתה יכול להסיק את הערך מההקשר (מה ה-entity עושה, לאיזה סוכן הוא שייך, איך הוא עובד) → בחר בלי לשאול
2. **לא לחשוף צנרת** — לעולם אל תזכיר בפני המשתמש שמות קבצים פנימיים (notion-config.md, master-library/), שמות שדות טכניים, או מבנה DB
3. **שאל רק מה שאי-אפשר להסיק** — ואם שואל, שאל בשפה פשוטה: "הסוכן מייצר תוצר (קובץ, מייל) או מנהל שיחה?" — לא "doer or companion?"
4. **אם באמת תקוע** — אל תשאל את המשתמש שאלות שהוא לא יכול לענות עליהן. בחר ברירת מחדל סבירה, או אמור "צריך לבדוק עם מנהלת המערכת"

---

## כללי ברזל

1. **כל קשר = relation אמיתי** — לעולם לא רק טקסט ב-content
2. **סדר DAG ליצירה:** knowledge → skills → workflows → agents → rules
3. **DUAL relations** מתעדכנות אוטומטית בשני הכיוונים (יצירת relation בצד אחד = מספיק)
4. **Title property:**
   - ידע / סקילים / Workflows / **מחלקות** → `Title`
   - סוכני המשרד / Rules / Integrations / Databases → `שם`
5. **subdivision** קיים ב: סוכני המשרד, סקילים, Workflows — **לא ב-ידע, לא ב-Rules** (ישליך שגיאה)
6. **Checkbox values:** `"__YES__"` / `"__NO__"` (לא true/false)
7. **תאריכים:** DD בחודש YYYY (לדוגמה: "18 במאי 2026")
8. **אִימפּרוּב** ו-**בְּנָיָה** — תמיד עם ניקוד מלא
9. **שורת מטא** — חובה כ-paragraph ראשון בכל דף, לפני ה-H2 הראשון
10. **כותרות H2** — חובה emoji בהתחלה. לא `## זהות` אלא `## 📋 סקירה`
11. **סעיף `🗣️ הוראות לקלוד — מאיפה להתחיל`** — חובה בכל 4 סוגי entities
12. **סעיף `📝 לוג עדכונים`** — חובה, גם אם זה "יצירה ראשונה"
13. **לא להמציא ערכים** — אם שדה select לא מכיל את הערך שרוצים, לא ליצור ערך חדש בלי לשאול
14. **שאלה אחת בכל פעם** — לא להציף. במצב שקט — אפס שאלות
15. **דיווח עם קישור** — תמיד אחרי כל פעולה
16. **ולידציה** — תמיד אחרי כתיבה (שלב 3)

---

## פלטת צבעים ל-callouts

| צבע | שימוש |
|---|---|
| `blue_background` | מטא, פקודות, הקשר, לוג עדכונים, פתרון בעיות |
| `gray_background` | תיאורים נייטרליים |
| `green_background` | "✅ הושלם", תהליכים |
| `yellow_background` | תובנות, "🔜 מה נשאר" |
| `purple_background` | "הוראות לקלוד", רפרנס |
| `orange_background` | אזהרה בינונית |
| `red_background` | "❌ אסור", "מה לא עושה" |

---

## שלב 0 — בדיקת תשתית

**בכל הפעלה**, לפני הכל:

1. **בדוק חיבור Notion MCP** — קרא ל-`API-post-search` עם query ריק (או כל קריאה). אם נכשל:
   > "אין לי גישה ל-Notion. צריך לחבר Notion MCP. מדריך מהיר:
   > 1. Settings → Connectors → Add Connector
   > 2. בחר Notion
   > 3. אשר הרשאות לדאטהבייסים הרלוונטיים"
   → **עצור.**

2. **חפש `.office/notion-config.md`** ב-root של ה-repo
   - קיים → קרא → שלב 2
   - לא קיים → שלב 1

---

## שלב 1 — אונבורדינג

### מסלול א — Auto-Discovery (מועדף)

שאל שאלה אחת:
> "יש לך Notion databases לתיעוד? תן לי את ה-IDs שלהם ואני אסרוק אותם אוטומטית.
> (ה-ID נמצא ב-URL של ה-database: `notion.so/[workspace]/[DATABASE_ID]?v=...` — 32 תווים אחרי הסלאש האחרון, לפני ה-`?`)"

**כשמקבלים ID, לכל DB:**

1. קרא ל-Notion MCP → `API-retrieve-a-database` עם `database_id`:
   ```
   CallMcpTool: server="user-Notion", toolName="API-retrieve-a-database", arguments={"database_id": "<ID>"}
   ```
   התגובה מכילה: title, properties (כל השדות — שם, type, options ל-select, relation targets).

2. מ-properties חלץ:
   - `title` property (שם השדה שהוא title type)
   - כל select property → שמור שם + אופציות
   - כל relation property → שמור שם + target database
   - כל text/rich_text/number/date/checkbox property

3. **למד מרשומות קיימות (reverse engineering):**
   קרא ל-`API-post-search` עם filter על ה-database:
   ```
   CallMcpTool: server="user-Notion", toolName="API-post-search", arguments={"query": "", "filter": {"property": "object", "value": "page"}, "page_size": 3}
   ```
   ואז לכל page → קרא blocks:
   ```
   CallMcpTool: server="user-Notion", toolName="API-get-block-children", arguments={"block_id": "<page_id>"}
   ```
   מתוך ה-blocks, חלץ את הדפוס:
   - סדר ה-headings (H2)
   - טקסט השורה הראשונה (שורת מטא?)
   - שימוש ב-callouts (צבעים, icons)
   - שימוש בטבלאות
   - bullets vs numbered lists

4. **הצג למשתמש את מה שלמדת:**
   > "סרקתי את [שם DB]. מצאתי:
   > - [N] שדות: [רשימה]
   > - תבנית body (למדתי מ-[N] רשומות קיימות): [תיאור]
   > - Relations ל: [DBs]
   > זה נכון? משהו לשנות?"

### מסלול ב — ידני (fallback)

אם המשתמש לא יודע IDs או מעדיף למלא ידנית:

1. "כמה databases יש לך? ומה השמות שלהם?"
2. לכל DB: "מה ה-database ID?" + הסבר איפה למצוא
3. "יש שדות חובה? כללים מיוחדים?"

### בניית Config

אחרי שיש את כל המידע, בנה `.office/notion-config.md`:

```markdown
# Notion Office Config

> נוצר אוטומטית על-ידי hr-documenter | עודכן: [DD בMM YYYY]
> לעריכה ידנית — שנה ושמור. לאונבורדינג מחדש — "reset config".

---

## databases

### [שם DB]
database_id: [32 chars]
title_property: [שם]
entity_type: [skill/knowledge/workflow/agent/rule/custom]

**properties:**
- [שם] (select): [val1, val2, val3] [REQUIRED]
- [שם] (text): — [REQUIRED]
- [שם] (relation → [target DB name]): — [OPTIONAL]
- [שם] (select): [val1, val2] [OPTIONAL]

**body_template:**
- META: [scope]: {scope} | [form]: {form} | עודכן: {date}
- H2: 📋 סקירה → paragraph
- H2: 🎯 [כותרת] → list
- H2: 📥 קלט / 📤 פלט → bullets
- H2: ❌ [כותרת שלילית] → callout(red_background)
- H2: 🔗 קשרים → table
- H2: 📝 לוג עדכונים → callout(blue_background)
- H2: 🗣️ הוראות → callout(purple_background)

**routing_keywords:** [מילים שמסייעות לזהות שה-entity שייך ל-DB הזה]

---

### [שם DB 2]
...

---

## routing_rules

מילות מפתח לזיהוי DB יעד:
- "skill" / "סקיל" / "יכולת" → [DB Skills]
- "knowledge" / "ידע" / "מסמך" → [DB Knowledge]
- "workflow" / "תהליך" / "זרימה" → [DB Workflows]
- "agent" / "סוכן" → [DB Agents]
- "rule" / "כלל" / "חוק" / "הנחיה" → [DB Rules]
- "integration" / "אינטגרציה" / "חיבור" / "שירות חיצוני" / "API" → [DB Integrations]
- "database" / "דאטהבייס" / "מאגר" / "בסיס נתונים" / "טבלה" → [DB Databases]
- "department" / "מחלקה" / "חדר" → [DB מחלקות]

**אינטגרציה מול דאטהבייס - ההבחנה:** השירות שמתחברים אליו = integration (Airtable, Supabase). המאגר עצמו שבתוכו יושבים הנתונים = database (בסיס Airtable מסוים, פרויקט Supabase מסוים). שירות אחד יכול להחזיק כמה מאגרים.

## department_page_ids

[department_name]: [page_id]
...

## iron_rules
- [כלל 1]
- [כלל 2]

## callout_colors
- blue_background: מטא, לוג, הקשר
- red_background: שלילה, אסור
- purple_background: הוראות לקלוד
- green_background: הושלם
- yellow_background: תובנות, מה נשאר
```

**הערה על פורמט:** ה-body template משתמש בפורמט DSL פשוט (לא markdown מקונן) כדי למנוע בעיות parsing:
- `META:` = שורת מטא ראשונה (bold paragraph)
- `H2:` = heading_2 + emoji
- `→ paragraph/list/bullets/callout(color)/table` = סוג ה-block שאחרי

### סיום אונבורדינג:

1. שמור `.office/notion-config.md`
2. הצג סיכום: `✅ Config נוצר — [N] databases, [M] properties, [K] relations. מוכן לתעד.`
3. שאל: "רוצה לתעד משהו עכשיו?"

---

## שלב 2 — תיעוד entity

### 2a. Routing — לאיזה DB?

1. קרא את `routing_rules` מה-config
2. חפש מילות מפתח בהקשר (מה המשתמש אמר / מה הסקיל הקורא העביר)
3. אם ברור → המשך
4. אם לא ברור → שאל: "מה אתה רוצה לתעד? [רשימת DBs מה-config]"

### 2b. מילוי Properties

**סדר עבודה:**

1. **מלא אוטומטית** מה שאפשר להסיק:
   - `type` → תמיד ערך קבוע (מ-config: entity_type)
   - `status` → `ready` (ברירת מחדל) או `in-progress`
   - title → מה שהמשתמש נתן
   - date fields → היום

2. **השתמש בעצי ההחלטה** (מסעיף "מתודולוגיית אימפרוב") כדי להכריע בשדות:
   - scope → עץ role-specific vs cross-cutting
   - form → עץ procedural vs rules vs declarative (skills בלבד)
   - kind → עץ static vs dynamic (ידע בלבד) / legacy ב-סוכנים — נגזר מ-trigger
   - shelf → עץ 10 ערכים (ידע בלבד)
   - subdivision → עץ 6 ערכים (skills, workflows, agents)
   - department → 8 ערכים
   - agent_role → עץ doer vs companion (סוכנים)
   - trigger → עץ interactive vs automatic (סוכנים)
   - pattern → עץ A/A-hybrid/B/C (סוכנים מבצעים)
   - runtime → עץ 4 ערכים (סוכנים, אופציונלי)

3. **עקרון אוטונומיה:** החלט לבד מה שאפשר להסיק. שאל רק מה שבאמת אי-אפשר.

4. **Relations:**
   - אם scope=role-specific → owner_agent חובה. חפש page ID:
     ```
     CallMcpTool: server="user-Notion", toolName="API-post-search",
       arguments={"query": "[שם הסוכן]", "filter": {"property": "object", "value": "page"}}
     ```
   - מה-results → מצא page שנמצא ב-database של agents → קח page.id
   - אם department relation (סוכנים) → השתמש ב-`department_page_ids` מה-config

### 2c. בניית Body (Blocks)

קרא את `body_template` מה-config עבור ה-DB הנבחר, **או השתמש בתבניות Body מסעיף "תבניות Body"** אם ה-config לא מגדיר תבנית מותאמת.

לכל שורה ב-template:

**META:** → block paragraph עם bold:
```json
{
  "object": "block",
  "type": "paragraph",
  "paragraph": {
    "rich_text": [{
      "type": "text",
      "text": { "content": "scope: cross-cutting | form: procedural | עודכן: 20 במאי 2026" },
      "annotations": { "bold": true }
    }]
  }
}
```

**H2:** → block heading_2:
```json
{
  "object": "block",
  "type": "heading_2",
  "heading_2": {
    "rich_text": [{ "type": "text", "text": { "content": "📋 סקירה" } }]
  }
}
```

**→ paragraph:**
```json
{
  "object": "block",
  "type": "paragraph",
  "paragraph": {
    "rich_text": [{ "type": "text", "text": { "content": "[תוכן]" } }]
  }
}
```

**→ bullets:**
```json
{
  "object": "block",
  "type": "bulleted_list_item",
  "bulleted_list_item": {
    "rich_text": [{ "type": "text", "text": { "content": "[פריט]" } }]
  }
}
```

**→ list (numbered):**
```json
{
  "object": "block",
  "type": "numbered_list_item",
  "numbered_list_item": {
    "rich_text": [{ "type": "text", "text": { "content": "[פריט]" } }]
  }
}
```

**→ callout(color):**
```json
{
  "object": "block",
  "type": "callout",
  "callout": {
    "icon": { "type": "emoji", "emoji": "[emoji from H2]" },
    "color": "[color]_background",
    "rich_text": [{ "type": "text", "text": { "content": "[תוכן]" } }],
    "children": [
      {
        "object": "block",
        "type": "bulleted_list_item",
        "bulleted_list_item": {
          "rich_text": [{ "type": "text", "text": { "content": "[פריט]" } }]
        }
      }
    ]
  }
}
```

**→ table:**
```json
{
  "object": "block",
  "type": "table",
  "table": {
    "table_width": 2,
    "has_column_header": true,
    "has_row_header": false,
    "children": [
      {
        "type": "table_row",
        "table_row": {
          "cells": [
            [{ "type": "text", "text": { "content": "Property" } }],
            [{ "type": "text", "text": { "content": "ערך" } }]
          ]
        }
      },
      {
        "type": "table_row",
        "table_row": {
          "cells": [
            [{ "type": "text", "text": { "content": "scope" } }],
            [{ "type": "text", "text": { "content": "cross-cutting" } }]
          ]
        }
      }
    ]
  }
}
```

### 2d. יצירת Page

```
CallMcpTool: server="user-Notion", toolName="API-post-page",
  arguments={
    "parent": { "database_id": "<מ-config>" },
    "properties": {
      "<title_property>": { "title": [{ "text": { "content": "<שם>" } }] },
      "<select_field>": { "select": { "name": "<value>" } },
      "<text_field>": { "rich_text": [{ "text": { "content": "<value>" } }] },
      "<relation_field>": { "relation": [{ "id": "<page_id>" }] },
      "<checkbox_field>": { "checkbox": true }
    },
    "children": [ <blocks array from 2c> ]
  }
```

### 2e. דיווח

```
✅ [entity_type]: "[שם]" נוצר ב-[DB name] → https://notion.so/[page_id_with_dashes]
```

---

## שלב 3 — ולידציה (אחרי כתיבה)

אחרי יצירת page, בצע בדיקה:

1. **קרא חזרה את ה-page:**
   ```
   CallMcpTool: server="user-Notion", toolName="API-get-block-children",
     arguments={"block_id": "<page_id>"}
   ```

2. **בדוק:**
   - [ ] יש שורת מטא ראשונה?
   - [ ] כל H2 עם emoji?
   - [ ] יש callout לוג עדכונים?
   - [ ] Properties נכתבו (לא ריקים)?

3. **אם נכשל** → תקן אוטומטית (update blocks) → דווח: "✅ תוקן: [מה]"

---

## שלב 4 — עדכון entity קיים

כשהמשתמש אומר "עדכן" / "שנה" / "תוסיף ל-X":

1. **מצא את ה-page:**
   ```
   CallMcpTool: server="user-Notion", toolName="API-post-search",
     arguments={"query": "<שם ה-entity>"}
   ```
   סנן results → רק pages מתוך ה-DBs שב-config.

2. **קרא blocks קיימים:**
   ```
   CallMcpTool: server="user-Notion", toolName="API-get-block-children",
     arguments={"block_id": "<page_id>"}
   ```

3. **הצג מצב נוכחי** → שאל מה לשנות

4. **עדכן:**
   - Properties: `API-patch-page` עם `page_id` + properties חדשים
   - Blocks: `API-update-a-block` / `API-patch-block-children` לפי הצורך

5. **הוסף ללוג עדכונים:**
   מצא את block ה-callout של "📝 לוג עדכונים" → הוסף child bullet עם:
   `[emoji] [כותרת] — [DD בMM YYYY]`

---

## שלב 5 - סריקת ריפו מלא (מצב הגירה / גרסה ידנית)

**מתי:** המשתמש יורד מהמנוי לגרסה הידנית, או מבקש למפות את **כל** הריפו לנושן בבת אחת (לא ישות-ישות). טריגרים: "מפה את כל הריפו", "בנה את המשרד בנושן", "העבר את הכל לנושן", "ירדתי מהמנוי", "גרסה ידנית", "map my whole repo", "migrate everything".

**העיקרון:** הריפו הוא מקור-האמת. הסריקה קוראת את כל הסוכנים / סקילים / ידע / workflows מהריפו ובונה מהם את טבלת המשרד המלאה בנושן - כך שהעבודה נגישה ושמורה גם בלי חיבור VO חי. לא ממציאים כלום; ממפים אך ורק את מה שקיים בריפו. הריפו מוביל, נושן עוקב.

**לפני שמתחילים - הצג את הדרכת המעבר.** אם זו הפעלה בהקשר של ירידה / גרסה ידנית (ולא רק תחזוקה שוטפת), קרא את `references/manual-version-onboarding.md` והצג את עיקריו למשתמש (לא איבדת כלום; מה נשאר; מה השתנה). ואז המשך.

### 5a. תנאי מקדים - config

- `.office/notion-config.md` לא קיים? ← הרץ קודם **שלב 1 (אונבורדינג)** ליצירת ה-config. בלי DB IDs אין לאן לכתוב. (בירידה זה המצב הרגיל - לרוב עדיין אין config.)
- קיים? ← קרא אותו והמשך.

### 5b. גילוי - מיפוי מבנה הריפו לישויות

סרוק את שורש הריפו (git root, או ה-cwd אם אין git). זהה את התיקיות הבאות. **דלג על מה שלא קיים** - ריפו של תלמיד עשוי להכיל רק חלק מהמבנה:

| מיקום בריפו | סוג ישות | scope | איך לחלץ |
|---|---|---|---|
| `master-library/*.md`, `knowledge/*.md` | knowledge | cross-cutting | כותרת H1 = שם; blockquote / משפט ראשון = description; shelf + kind מעצי ההחלטה |
| `skills/<name>/SKILL.md` | skill | cross-cutting | frontmatter `name` + `description`; form + department מהתוכן |
| `agents/ready/<name>/` | agent | - | README (כותרת = שם, "מה X עושה" = description); system-prompt.md = persona; status=`ready` |
| `agents/in-progress/<name>/` | agent | - | כנ"ל; status=`in-progress` |
| `pipeline-agents/<name>/`, `agents/*/pipeline/` | agent | - | trigger=`automatic`, runtime=`active-launchd`/`production-cloud`; README = שם + description |
| `pipeline-agents/<name>/pipeline/`, `pipeline-agents/<name>/scripts/`, `pipeline-agents/<name>/src/` (תיקייה עם כמה קבצי-שלב רציפים בתוך pipeline-agent) | workflow | **role-specific** | owner = הסוכן שבתיקייתו (`pipeline-agents/<name>/`); שם = "<name> - תהליך" (או כותרת מפורשת ל-workflow ב-README אם יש); שלבים = קבצי התיקייה לפי סדר (כל קובץ = שלב אחד); description = "מה זה עושה" מ-README של הסוכן |
| `.env.example` (עדיפות ראשונה) או `.env` בתוך `agents/<name>/` או `pipeline-agents/<name>/` | integration (ישות אחת לכל שירות שזוהה) | role-specific (ברירת מחדל); cross-cutting אם אותו שירות חוזר במפתחות של כמה סוכנים | owner = הסוכן שבתיקייתו. קרא רק את **שם המשתנה** (צד שמאל של `=`) - לעולם לא את הערך, גם אם זה `.env` אמיתי עם מפתח אמיתי. זהה שירות ממפתח מוכר בלבד: `OPENAI_API_KEY`→OpenAI, `ANTHROPIC_API_KEY`→Claude/Anthropic, `NOTION_API_KEY`/`NOTION_TOKEN`→Notion, `GOOGLE_*`/`GMAIL_*`→Gmail, `ZOOM_*`→Zoom, `RUNPOD_*`→RunPod, `WHATSAPP_*`→WhatsApp, `STRIPE_*`→Stripe, `AIRTABLE_*`→Airtable. מפתח לא מזוהה ← דלג ורשום ב-5f, אל תנחש שם שירות |
| `agents/<name>/skills/<s>/` | skill | **role-specific** | owner = הסוכן שמכיל; frontmatter כרגיל |
| קבצי ידע בתוך `agents/<name>/` או `pipeline-agents/<name>/knowledge/` | knowledge | **role-specific** | owner = הסוכן שמכיל |
| `.env.example`/`.env` (מפתחות שמצביעים על **מאגר**, לא על שירות): `AIRTABLE_BASE_ID` · `SUPABASE_URL`/`SUPABASE_PROJECT_REF` · `DATABASE_URL`/`POSTGRES_*` · `MONGODB_URI` · `NOTION_DATABASE_ID`. וכן קבצי מאגר בריפו: `*.sqlite`/`*.db`, תיקיית `migrations/`/`schema.sql`, קובץ state קבוע כמו `data/*.json` | database (ישות לכל מאגר) | role-specific (ברירת מחדל); cross-cutting אם כמה סוכנים ניגשים לאותו מאגר | owner = הסוכן שבתיקייתו. **שם המשתנה בלבד, לעולם לא הערך.** `platform` לפי המקור, ורק מהערכים הקיימים: Airtable = `airtable` · Supabase/Postgres = `postgresql` · נושן = `notion` · `*.sqlite`/`*.db` = `sqlite` · `*.csv` = `csv` · כל השאר (Mongo, קובץ JSON) = `other`. `description` = מה נשמר בו לפי ההקשר בריפו (README / שם התיקייה). מפתח שלא ברור אם הוא מאגר ← דלג ורשום ב-5f, אל תנחש |
| `.cursor/rules/*.md(c)`, `CLAUDE.md` (כללי עבודה מפורשים), `AGENTS.md` | rule | cross-cutting (או role-specific אם הכלל יושב בתיקיית סוכן) | `שם` = כותרת הכלל; `github_path` = הנתיב; `always_apply` לפי frontmatter `alwaysApply` אם קיים, אחרת `__NO__`; `scope` מהתוכן (infrastructure/behavior/format/process/documentation). קובץ ארוך עם כמה כללים ← ישות אחת לכל כלל **רק אם** יש כותרות ברורות; אחרת ישות אחת לקובץ |

**לדלג תמיד:** `agents/completed/` ו-`agents/*/completed/` (ארכיון פיתוח - meeting-decisions, progress; לא ישויות פעילות), `assets/` ותמונות, `.git/`, `node_modules/`, `output/`, קבצי `.zip`, `.claude-plugin/`. מבנה לא ברור? ← דלג ורשום אותו בדו"ח (5f) במקום לנחש.

### 5c. סדר יצירה (DAG)

לפי כלל ברזל 2, עם integrations ו-databases בתחילת השרשרת (סקילים/workflows/סוכנים עשויים להתייחס אליהם): **integrations ← databases ← knowledge ← skills ← workflows ← agents ← rules**. צור בסדר הזה, כי ישות מאוחרת מקשרת לישות מוקדמת (סוכן מקשר לסקילים ולידע שלו; workflow/סוכן מקשרים לאינטגרציות ולמאגרים שהם משתמשים בהם). סדר הפוך = relations שבורים.

1. integrations (אם התגלו - מ-`.env.example`/`.env`)
2. databases (אם התגלו - מפתחות-מאגר ב-`.env.example`, קבצי `*.sqlite`/`migrations/`)
3. knowledge (master-library cross-cutting, ואז role-specific פר-סוכן)
4. skills (cross-cutting בשורש, ואז role-specific פר-סוכן)
5. workflows (אם התגלו - כולל תיקיות `pipeline/`/`scripts/`/`src/` בתוך pipeline-agents)
6. agents (כולל ה-relations לסקילים / ידע / אינטגרציות / מאגרים שלהם)
7. rules (אם קיימים - `.cursor/rules/`, כללי עבודה ב-CLAUDE.md/AGENTS.md)

### 5d. תיעוד כל ישות (bulk, במצב שקט)

לכל ישות שהתגלתה, הפעל את הלוגיקה של **שלב 2** (routing ← מילוי properties מעצי ההחלטה ← בניית body ← יצירת page ← ולידציה שלב 3). זה **מצב שקט** - אל תשאל על כל ישות בנפרד; החלט לבד לפי עצי ההחלטה (עיקרון אוטונומיה). דווח התקדמות כל כמה ישויות ("תיעדתי 8 מתוך 23...") כדי שהמשתמש יראה שזה זז.

**Dedup (חובה):** לפני יצירה, חפש page קיים באותו שם ב-DB היעד (`API-post-search`). כבר קיים? ← **עדכן** (שלב 4), אל תיצור כפול. כך הסריקה idempotent - אפשר להריץ אותה שוב ושוב בבטחה.

### 5e. Relations (DUAL) - אחרי שכל הישויות קיימות

עבור שוב על הסוכנים, וקשר כל אחד למה שבתיקייתו (לפי מפת DUAL Relations):

- סוכן ← הסקילים שבתיקייתו (`agents/<name>/skills/`): relation `skills` (reverse: `office_owner_agent`).
- סוכן ← קבצי הידע שבתיקייתו: relation `knowledge`.
- skill role-specific ← owner agent: `office_owner_agent`.
- workflow ← סוכן: `office_owner_agent`; workflow ← סקילים: `uses_skills`.
- סוכן/workflow ← האינטגרציות שזוהו מ-`.env.example` שבתיקייתו: relation `uses_integrations` (reverse: `used_by_agents`/`used_by_workflows`).
- סוכן ← המאגרים שזוהו בתיקייתו: `databases_written` אם הוא כותב אליהם, `databases_read` אם רק קורא (reverse: `written_by_agents`/`read_by_agents`). לא ברור מהריפו אם כותב או קורא? ← `databases_read` (ההנחה השמרנית) ורשום ב-5f.
- rule ← מה שהוא משפיע עליו, אם ברור מהתוכן: `affects_agents` / `activates_skills`. לא ברור ← השאר ריק, אל תנחש.

יצירת relation בצד אחד מספיקה (DUAL מתעדכן אוטומטית בשני הכיוונים - כלל ברזל 3).

### 5f. דו"ח סיכום

```
✅ מיפוי הריפו הושלם - טבלת המשרד שלך בנושן מוכנה:
   • [N] סוכנים  • [M] סקילים  • [K] מסמכי ידע  • [W] workflows
   • [I] integrations  • [D] מאגרי נתונים  • [R] כללים
   נוצרו/עודכנו ב: [קישורי ה-DB]
   דילגתי על: [תיקיות/קבצים שלא זוהו, אם היו]
   [אם סוג ישות לא נמצא בריפו - כתוב "לא נמצאו X בריפו", אל תשמיט את השורה בשקט]

מעכשיו העבודה שלך חיה בשני מקומות שלמים ונגישים:
   • הריפו (מקור-האמת) - כל הסוכנים, הסקילים והידע, אצלך לתמיד.
   • טבלת המשרד בנושן - התצוגה המלאה, בלי תלות במנוי.
```

### 5g. עדכון שוטף אחרי הירידה

כל שינוי בריפו (סוכן / סקיל / ידע חדש או עודכן) - הרץ שוב:

- ישות בודדת שהשתנתה ← שלב 2 (או שלב 4 לעדכון).
- שינוי רחב / ריפרוש מלא ← שלב 5 שוב (ה-dedup מונע כפילויות).

**הריפו מוביל, נושן עוקב** - תמיד עורכים בריפו ואז מסנכרנים לנושן, לא הפוך.

---

## טיפול בשגיאות

| מצב | תגובה |
|---|---|
| Notion MCP לא מחובר | הצג מדריך חיבור → עצור |
| database_id לא תקין (404) | "ה-ID [X] לא נמצא. בדוק שהוא נכון (32 תווים, בלי מקפים) ושנתת הרשאות ל-connector." |
| select value לא קיים | "הערך '[X]' לא קיים ב-[field]. ערכים מותרים: [Y, Z]. מה לבחור?" |
| relation target לא נמצא | "לא מצאתי את '[X]' ב-DB [target]. בדוק את השם או תן page ID ישירות." |
| config חלקי | "ה-config מגדיר [X] databases אבל אתה מנסה לתעד [Y] שאין לו DB. רוצה להוסיף?" |
| page כבר קיים (duplicate) | "כבר קיים page בשם '[X]' ב-[DB]. לעדכן אותו? או ליצור חדש?" |
| blocks write failed | "היצירה הצליחה אבל body חלקי. אנסה להוסיף את ה-blocks החסרים." → retry |
| ריפו ריק / אין תיקיות מוכרות (שלב 5) | "לא מצאתי agents/ · skills/ · master-library/ בריפו. הפעל אותי מתוך שורש הריפו של הסוכנים שלך." |
| מבנה תיקייה לא מזוהה (שלב 5) | דלג עליו, המשך עם השאר, ורשום בדו"ח הסיכום (5f). אל תנחש סוג ישות. |

---

## עדכון config

| פקודה | מה קורה |
|---|---|
| "עדכן config" / "הוסף DB" | מוסיף DB חדש ל-config הקיים |
| "שנה תבנית של [DB]" | מעדכן body_template של DB ספציפי |
| "reset config" / "אונבורדינג מחדש" | מוחק config ומתחיל מאפס |
| "סרוק מחדש [DB]" | קורא API-retrieve-a-database ומעדכן properties |

---

## מיקום

- **Config:** `.office/notion-config.md` ב-root של ה-repo של המשתמש
- **Skill source:** `skills/hr-documenter/SKILL.md` (בתוך הפלאגין)
- **הדרכת המעבר לגרסה הידנית:** `references/manual-version-onboarding.md` (מוצג בתחילת שלב 5)