---
name: hebrew-doc-studio
description: >-
  יצירת מסמכים מעוצבים בעברית (PDF ו-Word/DOCX) עם RTL מלא, טיפול נכון בטקסט
  מעורב עברית-אנגלית-מספרים (BiDi) וגופנים מוטמעים. השתמש בכל פעם שהפלט הוא מסמך
  בעברית או מעורב עברית/אנגלית: הצעת מחיר, חוזה, מכתב רשמי, פרוטוקול, חשבונית,
  מסמך לקוח, דף מידע מעוצב, או כל 'מסמך Word בעברית' / 'PDF בעברית' / 'קובץ docx
  בעברית'. מפעיל גם על 'תכין מסמך מעוצב בעברית', 'הצעת מחיר בעברית', 'חוזה
  ב-Word', 'Hebrew Word document', 'create a styled Hebrew PDF'. העדף את הסקיל
  הזה על פני סקילי docx/pdf הכלליים כשהמסמך בעברית או RTL - הם מפיקים עברית
  משובשת בלי RTL/BiDi וגופן מוטמע. לא מיועד לקריאה/OCR.
license: MIT
---

# Hebrew Doc Studio - מסמכים מעוצבים בעברית עם RTL

## ⛔ כלל ברזל - קרא לפני שאתה כותב שורת קוד אחת

הטעות הכי נפוצה בסקיל הזה היא שקלוד **מתעלם מהסקריפטים וכותב python-docx משלו**. זה מייצר מסמך שנראה כמעט נכון אבל הוא לא RTL. ארבעה כללים שאסור להפר:

1. **אסור** לייצר מסמך Word/DOCX עברי עם `python-docx` גולמי שאתה כותב בעצמך, ואסור להשתמש בסקיל `docx` הכללי. **חובה** לייבא ולהשתמש ב-`HebrewDoc` מ-`scripts/hebrew_docx.py`. ל-PDF - חובה `html_to_pdf` מ-`scripts/hebrew_pdf.py`.
2. **יישור לימין הוא לא RTL.** `alignment = WD_ALIGN_PARAGRAPH.RIGHT` לבדו משאיר את הטקסט זורם שמאל-לימין, רק צמוד לימין. זו הסיבה מספר 1 ל"מסמך שנוצר אבל לא RTL". RTL אמיתי דורש `w:bidi` על הפסקה + `w:rtl` רק על ה-runs העבריים + `w:bidiVisual` על טבלאות. רק `HebrewDoc` עושה את כל זה נכון. אם אתה מוצא את עצמך כותב `alignment=RIGHT` ידנית - עצור, אתה בנתיב השגוי.
3. **אם אין הרצת קוד (Python) בסביבה - אי אפשר לייצר מסמך עברי תקין בסקיל הזה.** הסקיל כולו נשען על הרצת הסקריפטים. בסביבה בלי כלי קוד (למשל פרפלקסיטי, או צ'אט בלי הרצת קוד), אמור זאת למשתמש במפורש - אל תייצר מסמך שבור כתחליף.
4. לפני מסירת כל מסמך עברי - **חובה** להריץ את שער האימות הוויזואלי (ראה "בדיקה לפני מסירה"). בדיקת קוד לבדה לא מספיקה לעברית.

## שלב 0 (חובה): שער-שאלה לפני יצירה

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

**1. צבעים.** הצג את ערכת הפלטות (פתח/הראה `assets/palettes-preview.pdf`) ובקש לבחור פלטה או למסור צבע hex של מותג:

| שם | `palette=` | accent | מתאים ל- |
|----|-----------|--------|----------|
| כחול עסקי | `navy` | `#1F4E79` | ברירת מחדל, כל מסמך עסקי |
| טורקיז טכנולוגי | `teal` | `#0E7C86` | תחושת AI/טק, מסמכי מוצר והטמעה |
| סגול פרימיום | `indigo` | `#4B3F9E` | שיווקי, מיתוג בולט |
| ירוק כספי | `emerald` | `#1E6F5C` | כספים, צמיחה, קיימוּת |
| בורדו פורמלי | `burgundy` | `#8C2F39` | חוזים, מסמכים משפטיים/רשמיים |
| גרפיט מינימליסטי | `charcoal` | `#333333` | דוחות, מינימליזם ניטרלי |
| **צבע מותג** | (hex חופשי) | מה שהמשתמש ייתן | מיתוג אישי |

**2. מבנה / flow.** שאל אם יש מבנה מועדף (סדר מקטעים, מה חובה לכלול, אורך), **או** שהמשתמש מעדיף שתחליט לפי התוכן. אם בחר "תחליט" - בנה את ה-flow לפי סוג המסמך (שלדים ב-`references/israeli-templates.md`) ולפי התוכן שסופק, ותכריז בקצרה על המבנה שבחרת לפני היצירה.

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

### מבני ברירת מחדל לפי סוג מסמך (כש"תחליט")

- **הצעת מחיר:** פס-כותרת (שם+תאריך) → לכבוד → פתיח קצר → פירוט שירותים (רשימה) → טבלת תמחור → סיכום מע"מ → תוקף ותנאי תשלום → חתימות.
- **חוזה:** כותרת → מבוא/הואיל → הגדרות → היקף → תנאי תשלום → תקופה → סודיות/קניין → אחריות → יישוב סכסוכים → חתימות.
- **מכתב רשמי:** כותרת/לוגו → תאריך ונמען → גוף (פתיח, עיקר, סיום) → חתימה.
- **דוח / סיכום:** כותרת → תקציר מנהלים → מקטעי תוכן עם כותרות → טבלאות/נתונים → מסקנות והמלצות.
- **דף מידע (one-pager):** פס-כותרת → 2-3 מקטעים קצרים → CTA/פרטי קשר.

## מתי להשתמש ומה הנתיב הנכון

שני נתיבים, והבחירה ביניהם היא ההחלטה הראשונה והחשובה ביותר:

| הפלט שהמשתמש צריך | נתיב | למה |
|---|---|---|
| **PDF מעוצב** (הצעת מחיר, מסמך שיווקי, מסמך לקוח, דף עם צבעים/לוגו/טבלאות) | `scripts/hebrew_pdf.py` (HTML/CSS → WeasyPrint) | רינדור HTML אמיתי + **גופנים מוטמעים** → נראה זהה בכל מחשב. הנתיב הכי "מעוצב". |
| **Word שניתן לעריכה** (חוזה, פרוטוקול, מסמך שהלקוח ימשיך לערוך) | `scripts/hebrew_docx.py` (python-docx) | קובץ Word אמיתי ובר-עריכה, עם RTL ו-BiDi נכונים. |

ברירת מחדל כשלא ברור: אם המשתמש אמר "מעוצב", "PDF", "הצעת מחיר", "מסמך שיווקי" → PDF. אם אמר "Word", "docx", "שאוכל לערוך", "חוזה" → DOCX. בספק, שאל שאלה אחת קצרה.

> **קריטי:** בסביבת ההרצה אין גופן עברי מעוצב מותקן. אל תסתמך על גופני מערכת - הם יפיקו ריבועים או עברית מכוערת. נתיב ה-PDF פותר זאת בהטמעת הגופנים המצורפים. ראה `references/rtl-bidi-cheatsheet.md`.

## נתיב 1: PDF מעוצב (מומלץ למסמכים מעוצבים)

הסקיל מצרף גופנים עבריים סטטיים ב-`assets/fonts/` ומטמיע אותם אוטומטית. אתה רק כותב HTML/CSS עברי - ה-BiDi מטופל נייטיב על ידי `dir="rtl"`, ללא `get_display` וללא סידור תווים.

```python
import sys; sys.path.insert(0, "scripts")
from hebrew_pdf import html_to_pdf

body = '''
<div class="header-band"><h1>הצעת מחיר</h1>
  <div class="muted">בינה מלאכותית בגובה העיניים | 22/06/2026</div></div>
<p>הפרויקט כולל אפיון, פיתוח MVP והדרכה. ליווי בערוץ WhatsApp ייעודי.</p>
<table>
  <thead><tr><th>תיאור</th><th>כמות</th><th>סה"כ</th></tr></thead>
  <tbody><tr><td>אפיון</td><td class="num">1</td><td class="num">5,000.00</td></tr></tbody>
</table>
<p class="total">סה"כ לתשלום: 31,388.00 ש"ח</p>
'''
html_to_pdf(body, "/mnt/user-data/outputs/proposal.pdf",
            title="הצעת מחיר", font="Heebo", palette="navy")
# palette אחת מ-navy/teal/indigo/emerald/burgundy/charcoal, או accent="#RRGGBB" לצבע מותג
```

- גופנים: `'Heebo'` (סאנס מודרני, ברירת מחדל), `'Assistant'` (סאנס נקי), `'Frank Ruhl Libre'` (סריף פורמלי/משפטי).
- מחלקות CSS מובנות (ב-`BASE_CSS`): `.header-band` (פס כותרת צבוע), `.muted`, `.num` (ספרות טבלאיות), `.total` ו-`.totals` (בלוק סיכומים מיושר לימין), `.align-left` (יישור שמאל כשבאמת צריך).
- מונחים לועזיים (AI, SaaS, WhatsApp) נשארים LTR במקומם אוטומטית.
- לשליטה מלאה במסמך: העבר `full_html=<מחרוזת HTML שלמה>`. תבנית מוכנה: `assets/templates/document-base.html`.

## נתיב 2: Word/DOCX בר-עריכה

`scripts/hebrew_docx.py` מספק את המחלקה `HebrewDoc` שמטפלת בתקלות שמשבשות מסמכי Word עבריים (בסיס פסקה RTL, run יחיד שנותן ל-Word להריץ bidi לבד, גופן/גודל לכתב מורכב - ראה cheatsheet).

```python
import sys; sys.path.insert(0, "scripts")
from hebrew_docx import HebrewDoc

doc = HebrewDoc(font="Assistant", size=12, palette="navy").page(margin_mm=22)
# palette מגדיר accent + גוון פסי-טבלה. לחלופין accent="1F4E79" (hex ללא #) לצבע מותג.
doc.heading("חוזה שירותים", level=0)
doc.paragraph('ההסכם נחתם בין חברת Acme בע"מ לבין הלקוח (גרסה 2).')
doc.heading("היקף העבודה", level=2)
doc.bullets(["אפיון תהליכים", "פיתוח MVP תוך 30 יום", "הדרכת צוות"])
doc.table(
    headers=["תיאור", "כמות", 'מחיר (ש"ח)'],
    rows=[["אפיון", "1", "5,000.00"], ["פיתוח", "1", "12,000.00"]],
    col_widths_mm=[90, 25, 40])
doc.footer_page_numbers()
doc.save("/mnt/user-data/outputs/contract.docx")
```

מתודות: `heading(text, level)` (level=0 לראשית), `paragraph(text, bold/italic/size/color/align)`, `bullets(list)`, `numbered(list)`, `table(headers, rows, col_widths_mm, header_fill, zebra)`, `page(margin_mm, size)`, `footer_page_numbers()`, `spacer()`, `page_break()`, `save(path)`.

- בחירת גופן ל-Word משנה את המראה אצל הקורא. `David` בטוח כמעט בכל Windows. `Assistant`/`Heebo` מודרני אך דורש שיהיה מותקן. אם נדרשת זהות חזותית מובטחת → ייצא PDF.
- כל מתודה כבר עושה את הפיצול לפי כתב; פשוט העבר טקסט מעורב כמחרוזת רגילה.

## התקנת תלויות

```bash
pip install --break-system-packages python-docx weasyprint python-bidi
```

`python-docx` מספיק לנתיב Word. `weasyprint` (דורש pango/cairo, קיימים בסביבה) לנתיב PDF. `python-bidi` רק אם משתמשים ב-reportlab לטפסים בקואורדינטות קבועות (לא הנתיב המומלץ).

## תבניות עסקיות ישראליות

`references/israeli-templates.md` מפרט שדות חובה לפי סוג מסמך (חשבונית מס, חוזה, הצעת מחיר, קבלה, פרוטוקול), כללי מע"מ, וניסוחים משפטיים סטנדרטיים.

**חשבונית מס - שים לב למספר הקצאה:** במודל "חשבוניות ישראל", חשבונית מס בסכום שמעל הסף מחייבת מספר הקצאה מרשות המסים, אחרת הקונה לא יכול לקזז מס תשומות. הסף יורד בהדרגה: 20,000 ש"ח ב-2025, 10,000 ש"ח מינואר 2026, **5,000 ש"ח מ-1 ביוני 2026** (לפני מע"מ). **ודא את הסף העדכני מול רשות המסים לפני הפקת חשבונית.**

## בדיקה לפני מסירה (חובה - שער חוסם)

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

```bash
# DOCX → PDF → PNG  (LibreOffice קיים בסביבה)
soffice --headless --convert-to pdf --outdir /tmp file.docx
pdftoppm -png -r 110 -f 1 -l 1 /tmp/file.pdf /tmp/preview
# ואז view על /tmp/preview-1.png ובדוק: כיוון RTL, מונחים לועזיים במקומם, מספרים תקינים, גופן עברי אמיתי (לא ריבועים)
```

ל-PDF מ-WeasyPrint: המר ישירות עם `pdftoppm` ובדוק את אותם דברים.

## משאבים מצורפים

- `scripts/hebrew_pdf.py` - HTML/CSS → PDF עברי מעוצב עם גופנים מוטמעים. הרץ `python scripts/hebrew_pdf.py` להדגמה.
- `scripts/hebrew_docx.py` - בונה Word עברי RTL (`HebrewDoc`). הרץ `python scripts/hebrew_docx.py` להדגמה.
- `scripts/palettes.py` - ערכת פלטות צבע בשמות (navy/teal/indigo/emerald/burgundy/charcoal). שני הסקריפטים מקבלים `palette=`.
- `assets/fonts/` - Heebo, Assistant, Frank Ruhl Libre (Regular+Bold/SemiBold, סטטי).
- `assets/templates/document-base.html` - תבנית HTML מוכנה למסמך מעוצב.
- `assets/palettes-preview.pdf` - גיליון תצוגה ויזואלי של כל הפלטות. **הצג אותו למשתמש בשער-השאלה.**
- `references/rtl-bidi-cheatsheet.md` - הכלל המרכזי של RTL/BiDi לכל נתיב, והטעויות שמשבשות מסמכים.
- `references/palettes.md` - קטלוג הפלטות, שימוש, ועקרונות בחירת צבע.
- `references/fonts.md` - קטלוג הגופנים, הוספת גופן, בחירת גופן ל-Word.
- `references/israeli-templates.md` - שדות חובה ותבניות למסמכים עסקיים ישראליים.

## טעויות נפוצות (Gotchas)

- **אל תריץ `get_display` על טקסט ל-Word/HTML.** Word ומנוע ה-HTML מריצים bidi בעצמם; הרצה כפולה משבשת. `get_display` שייך רק לנתיב reportlab.
- **אל תפצל שורה ל-runs לפי כתב ואל תסדר תווים ידנית.** שים את כל השורה ב-run אחד, סמן את הפסקה `w:bidi` ואת ה-run `w:rtl`, ותן ל-Word להריץ bidi בעצמו (כמו טקסט עברי שמקלידים ידנית). פיצול לפי כתב שובר רווחים, פיסוק, סוגריים ותאריכים ב-Word/Google Docs - וב-LibreOffice זה נראה תקין, אז אל תיפול בפח. `HebrewDoc` כבר עושה זאת נכון.
- **אל תסתמך על גופני מערכת לעברית ב-PDF.** הטמע מ-`assets/fonts/` (נתיב ה-PDF עושה זאת).
- **אל תגדיר `w:jc="right"` על פסקה עברית.** תחת `w:bidi`, הערך "right" מתפרש כקצה הלוגי ומרונדר **שמאלה** ב-LibreOffice/Google Docs/תצוגות מקדימה. ליישור-ימין (ברירת מחדל ב-RTL) פשוט משמיטים את jc - קצה ההובלה של פסקת bidi הוא ימין. `HebrewDoc` כבר עושה זאת. (זו היתה תקלת היישור-שמאל שחזרה שוב ושוב.)
- **אל תאמת יישור לפי העין על שורה ארוכה.** שורה ארוכה ממלאת את כל הרוחב ונראית מיושרת-ימין גם כשהפסקה שמאלה. בדוק שורה קצרה (כותרת): אם הקצה הימני שלה לא נוגע בשול הימני, הפסקה מיושרת-שמאל. אימות אמיתי: ב-Word/Google Docs, או מדידת מיקום טקסט ב-PDF מרונדר.
- **אל תאמת RTL ב-LibreOffice בלבד.** הוא מרנדר RTL גם כשה-XML פגום. לאימות אמיתי פתח ב-Word/Google Docs, או בדוק שב-`word/document.xml` ה-`w:bidi` קודם ל-`w:jc` בכל `w:pPr`.
- **בלי ניקוד** במסמכים עסקיים/משפטיים. תאריך עסקי DD/MM/YYYY.