מוסיפים ספר חדש? קראו קודם את ADDING_BOOKS.md — רשימת המלכודות שנשברות בשקט (ספר הערות נלווה, פורמט שלושת המרשמים, הוולידטורים שקוראים git ולא את עץ העבודה).
מאגר זה מכיל הרבה יותר קבצים ממה שמגיע למשתמשים. לפני כל בדיקה או תיקון של מיקום ספר, שם ספר או קישורים — ודאו קודם שהקובץ שאתם נוגעים בו הוא זה שנארז. עותקים מקבילים באותו שם קיימים כמעט תמיד, ורובם לא נארזים.
הכל נבנה ב־.github/workflows/update-library.yml (job package, מצב
links_sync_mode):
| נכס | נבנה על ידי | מה בפנים |
|---|---|---|
otzaria_latest.zip |
create_release_archives.sh → manual_links_packaging.py package |
הספרייה עצמה: מיזוג BOOK_ROOTS לעץ אחד בשם אוצריא/, links/, files_manifest.json, metadata.json, manual_links_sync.json, manual_links_lineage.json, packaging_toolchain.json |
otzaria_dicta_latest.zip |
create_auxiliary_archives.sh |
DictaToOtzaria/לא ערוך/ספרים בלבד (חומר גלם, לא הספרייה) |
talmud_bavli_latest.tar.zst |
create_auxiliary_archives.sh |
קובצי ה־PDF שתחת MoreBooks/ספרים/אוצריא/תלמוד בבלי, משוטחים |
fordb_latest.zip |
.github/workflows/update-fordb.yml |
תיקיית ForDB/ (ה־CSV־ים) |
מוגדר ב־manual_links_packaging.py:34-50. כל שורש
מועתק אל תוך אותו עץ יעד אוצריא/, לפי הסדר, עם overwrite=True — שורש מאוחר יותר
דורס קובץ באותו נתיב יחסי:
Ben-YehudaToOtzaria/ספרים/אוצריא
DictaToOtzaria/ערוך/ספרים/אוצריא
OnYourWayToOtzaria/ספרים/אוצריא
OraytaToOtzaria/ספרים/אוצריא
tashmaToOtzaria/ספרים/אוצריא
sefariaToOtzaria/sefaria_export/ספרים/אוצריא
sefariaToOtzaria/sefaria_api/ספרים/אוצריא
MoreBooks/ספרים/אוצריא
KSK/ספרים/אוצריא
wikiJewishBooksToOtzaria/ספרים/אוצריא
wikisourceToOtzaria/ספרים/אוצריא
ToratEmetToOtzaria/ספרים/אוצריא
pninimToOtzaria/ספרים/אוצריא
National-LibraryToOtzaria/ספרים/אוצריא
yam-HaHachmaToOtzaria/ספרים/אוצריא
BeitAharonVeYisraelToOtzaria/ספרים/אוצריא
אותה רשימה משוכפלת כ־PACKAGED_PREFIXES ב־validate_fordb_book_names.py:186
(שם היא כוללת גם את DictaToOtzaria/לא ערוך/, שנכנס רק ל־zip הדיקטה). אם משנים
אחת — צריך לעדכן את השנייה.
יש עוד עותק בשלב ה־prepare: folders + mapping ב־sync_and_merge_folders.py (SourcesBooks.csv).
מקור שחסר שם נארז כרגיל, אבל ספריו לא מופיעים ב־SourcesBooks.csv.
test_source_lists_contract.py אוכף שהרשימה שווה ל־BOOK_ROOTS, חוץ משני שורשי ספריא הריקים.
MoreBooks/ספרים/שאינו תחתאוצריא/- תבנית Word וכלי תיקון שכבת הטקסט של PDF עברו ל־book-sources; קובצי הספרים נשארים כאן
- כל
<source>/ספרים/<משהו שאינו אוצריא>/— למשלOraytaToOtzaria/ספרים/לא רלוונטי/ DictaToOtzaria/לא ערוך/— נכנס רק ל־otzaria_dicta_latest.zip, לא לספרייהBeitAharonVeYisraelToOtzaria/ספרים/בהמתנה/— ספרים ממתינים של מכון בית אהרן וישראל (לא רשומים במטא־דאטה)- כלי עבודה:
linker/,linker-eval/,metadata/. הסקריפטים שלסקריפטים שונות/עברו ל־book-sources; נשארו בה רק הודעות העברה
מוגדר ב־manual_links_sync.json (links_roots), עם
expected_state של present/absent לכל שורש — סטייה מהמצב המוצהר מפילה את
האריזה. קבצים שטוחים בלבד: תת־תיקייה מתחת לשורש links היא שגיאה קשה.
כל הקבצים ממוזגים לתיקייה links/ אחת ב־zip, וללא דריסה (התנגשות = שגיאה).
תלוי במקור הספר (עמודת source ב־seforim.db):
- ספר של המאגר הזה (Dicta / MoreBooks / OnYourWay / Orayta / ToratEmet /
pninim / Ben-Yehuda / wikisource / tashma / wikiJewishBooks / National-Library /
yam-HaHachma / KSK / BeitAharonVeYisrael):
הקטגוריה נגזרת מנתיב התיקייה הפיזי בתוך
BOOK_ROOTS. מזיזים את הקובץ ב־git.ForDB/book_moves.csvלא מיועד לספרים אלה. - ספר של ספריא (
source.name='Sefaria'): אין קובץ מקומי, הוא נוצר בזמן הבנייה מה־API. מזיזים רק דרךForDB/book_moves.csv. הצרכן הואSeforimLibrary/generator/sefariasqlite/.../RenameCategoriesPostProcess.kt; ההתאמה מדויקת בבתים (שימו לב לגרשיים״U+05F4 מול").
עץ ספריא שצריך להתמזג עם תיקיית אוצריא בשם אחר (למשל «מילונים וספרי יעץ» של ספריא עם
«ספרות עזר» של אוצריא, שהפכו לשתי תיקיות «דקדוק», «אנציקלופדיות» ו«מילונים» נפרדות): מספיק כלל
שינוי שם אחד על הקטגוריה העליונה ב־ForDB/category_renames.csv (מילונים וספרי יעץ,ספרות עזר).
renameCategories רץ לפני שלב אוצריא, ושלב אוצריא מכניס תיקייה לקטגוריה קיימת באותו שם
(Generator.findExistingCategory), ולכן גם תתי־הקטגוריות מתמזגות לבדן. לא מוסיפים כלל לכל
תת־קטגוריה: category_moves.csv אינו ממזג, וכלל שינוי שם מתאים לפי כותרת בכל העץ. שורות
sefaria_category_changes.csv עוברות לנתיב החדש, שורה אחת לכל נתיב (SeedAllMetadata נכשל על
נתיב שנעלם ועל נתיב כפול), ו־validate_fordb_book_names.py נכשל על נתיב בשם הישן.
author.name הוא המפתח הייחודי — שתי צורות כתיב של אותו אדם הן שני מחברים, ומאז
שנוסף חיפוש לפי מחבר זה אומר שחצי מספריו לא נמצאים. התיקון תלוי במקור:
- ספר של המאגר הזה: השם מגיע משדה
author(אוauthors[]) ב־metadata.json שבשורש המאגר — לא מ־heAuthorsב־ForDB/all_metadata.json, שאינו נצרך בבניית טבלת המחברים. עורכים אתmetadata.json; אתall_metadata.jsonמעדכנים במקביל רק לשם עקביות — אבל לא רק לשם עקביות: קיים נוהג של סנכרון ידניheAuthors→metadata.json(ר'a5a627d6, יולי 2026), שמסיר תארי כבוד בדרך. סנכרון כזה בעתיד יוריד את ה־"רבי" מ־רבי יעקב בן יעקב משה לורברבוים מליסאויפצל אותו שוב מצד ספריא, ששם ה־CSV כן שומר אותו. לפני סנכרון כזה — לבדוק מולForDB/sefaria_author_changes.csv. - ספר של ספריא: השם מגיע מה־schema של ספריא, ואי אפשר לערוך אותו כאן. מוסיפים
שורה ל־ForDB/sefaria_author_changes.csv
(
שם בספריא,שם קנוני), שנצרך ב־SefariaDirectImporterבזמן הייבוא — לפני ש־upsertAuthorמקצה מזהה, כדי שלא ייווצרו שתי שורות שצריך למזג אחר כך.
ניקוד, טעמים, תווי BIDI בלתי־נראים ורווחים כפולים אינם צריכים שורה ב־CSV:
normalizeAuthorName ב־SeforimLibrary מסיר אותם משני הצדדים. גרשיים וגרש נשמרים.
ה־CSV שמור למקרים שרק אדם יכול להכריע בהם — ושם צריך זהירות: אברהם שמואל בנימין סופר ו־סופר, שמעון בן אברהם שמואל בנימין דומים הרבה יותר זה לזה מאשר שתי
הצורות של יעקב מליסא, והם אב ובן.
חלק מהערכים תוקנו ונבדקו ביד; הם רשומים ב־.github/data/locked_metadata.tsv:
author ב־metadata.json, שורה 2 בקובץ הספר, שם קנוני ב־ForDB/sefaria_author_changes.csv,
heShortDesc ו־heDescNew ב־ForDB/sefaria_metadata_changes.csv. ערך נעול קודם לכל סנכרון
גורף — heAuthors → metadata.json, הרצה ידנית של sefaria-export, המרה חוזרת או שינוי מפתח
בספריא. .github/scripts/check_locked_metadata.py רץ ב־validate-fordb-book-names.yml ונכשל כשערך
נעול השתנה או כשהמפתח שלו נעלם (ספר שנמחק, שורת CSV שנמחקה), ו־update-fordb.yml לא מפרסם ForDB
שערך נעול בו נדרס. שינוי מכוון: מעדכנים את
השורה באותו קומיט — python3 .github/scripts/update_locked_metadata.py --key KIND:KEY, או
--all-changed-vs origin/main --add-new לכל מה שהענף שינה (מול נקודת הפיצול, לא מול קצה main) — או עורכים אותה ביד. PR של עורך הקטלוג
(Bshlomecha) נושא את עדכון הנעילה בקומיט משלו, «עדכון קובץ הנעילה לערכים החדשים». שינוי שם של ספר
שה־CI מיישר (fordb_book_renames.py) והעברה/שינוי שם של קובץ בלי שינוי תוכן (git R100) — שורות הנעילה
עוברות לבד ב־push ל־main (follow_lock_renames.py). ב־CI שורה 2 נקראת מ־git: כל נתיב נעול חייב
להתקיים, והתוכן מושווה בספרים שהשתנו מאז הריצה המוצלחת האחרונה; בדיקה מלאה של כל הספרים — הרצה
מקומית בלי --git-rev. בספרי ממירים שורה 2 נשמרת גם ב־post_convert_fixes.tsv של המקור.
שני קבצי חובה ב־ForDB/, שהמחולל ב־SeforimLibrary הופך לטבלאות banner, book_banner
ו־book_protection ב־seforim.db. קובץ חסר מפיל את הבנייה (ואת שער ה־ForDB): הגנה שנעלמת בשקט
גרועה מבנייה שנכשלת. אין שורות = כותרת בלבד.
CSV לפי RFC-4180 ב־UTF-8, עם שורת כותרת:
| קובץ | כותרת | ערך |
|---|---|---|
book_banners.csv |
id,sourceName,bookName,text |
טקסט הבאנר שמעל תחילת הספר. ירידת שורה = שורה חדשה בתוך שדה במירכאות. הסימון היחיד: קישור [תווית](url), ו־{title} מוחלף בשם הספר (באפליקציה) |
book_protection.csv |
sourceName,bookName,level |
1 = בלי ייצוא לעריכה והגבלת העתקה; 2 = גם בלי ייצוא PDF והגבלת הדפסה |
sourceName הוא שם תיקיית המקור העליונה (KSK, National-LibraryToOtzaria), כמו source.name
ב־DB. bookName ריק = ברירת מחדל לכל ספרי המקור; שורה עם bookName גוברת עליה. bookName הוא
שם הספר הסופי ב־DB: איות book.title של שם קובץ ה־.txt, אחרי book_renames.csv.
id בבאנר הוא מספר קבוע (1 ומעלה) שהטקסט נשמר תחתיו ב־DB פעם אחת: ספרים עם אותו נוסח חולקים
id, ושורות עם אותו id חייבות לשאת אותו טקסט בדיוק (אחרת המחולל והבדיקה נכשלים). שינוי נוסח
נשאר באותו id — בכל השורות שלו — ונוסח חדש מקבל מספר שלא היה בשימוש. לא ממספרים מחדש ולא
ממחזרים מספר של נוסח שנמחק.
זכויות יוצרים וקרדיט נכתבים כאן ולא בקובץ הספר (.claude/skills/otzaria-book-format/references/book-file.md,
"זכויות יוצרים וקרדיט"). בספר קיים מוחקים את שורת הזכויות ומורידים באחת את מספרי השורות שאחריה
בכל הקישורים (של הספר ואליו).
validate_fordb_book_names.py בודק כל שורה מול ספרי אותו מקור: בהגנה שורה שלא נמצאה מפילה את
הבדיקה (וגם המחולל נכשל), בבאנר היא רק אזהרה. sourceName שאינו מקור במאגר הזה הוא רק אזהרה,
כי מקור ממאגר פרטי מצטרף רק בזמן הבנייה (והמחולל נכשל על מקור שלא נמצא). שינוי שם של קובץ ספר
מתעדכן בשני הקבצים אוטומטית, רק בשורות של אותו מקור.
הערות על X עשוי להישאר ספר עצמאי ב־DB: המחולל ממזג קובץ הערות (גם הערות על חברותא…) רק
כשהקישורים מלאים והתוכן בטוח למיזוג. בדיקת השמות המוקדמת אינה מסיקה
מיזוג מהכותרת. seedBookNotices מתאים את השורות לספרים ב־DB הסופי, אחרי המיזוג ושינויי
השמות: שורת הגנה ללא ספר מפילה את הבנייה, ושורת באנר ללא ספר היא אזהרה. אם קובץ ההערות
מוזג, יש להפנות את השורה לספר הבסיס בפועל; ההגנה עליו חלה גם על ההערות שבתוכו.
ספרים ממאגר פרטי: saga-continue.yml מעביר ל־manual-generate-release את משתני המאגר
PRIVATE_BOOKS_REPO, PRIVATE_BOOKS_TAG ו־PRIVATE_BOOKS_ASSET_SHA256 (כולם או אף אחד). הם נקראים
בזמן שלב S1 ואינם מקובעים ב־saga-state, כך שהרצה חוזרת של S1 לוקחת את ערכיהם העדכניים.
ForDB/divine_name_overrides.csv (חובה; קובץ חסר מפיל את הבנייה ואת שער ה־ForDB) הוא רשימת פסוקים שהמחולל ב־SeforimLibrary
(buildLineDivineNameIndex) משתמש בה לטבלה line_divine_name. היא חלה רק על שורות ספרי הבסיס
של התנ"ך. CSV לפי RFC-4180 ב־UTF-8, עם הכותרת ref,kind,decision,source,note:
| עמודה | ערך |
|---|---|
ref |
<שם ספר בתנ"ך> פרק:פסוק, טווח פרק:פסוק-פסוק או פרק:פסוק-פרק:פסוק (שופטים 17:1-18:31). שם הספר כמו ב־DB (שמואל א, דברי הימים ב) |
kind |
ADNUT, EL, ELOAH, ELOHIM, EHYEH, SHADDAI, TZEVAOT, או * = כל הסוגים. HVYH ו־YAH לא נקבעים ברשימה |
decision |
profane = חול, גובר על כל כלל. sacred = קודש, לפסוק אחד ולסוג אחד, וגובר על טווח profane (בראשית 19:18 בתוך פרשת לוט) |
source |
המקור ההלכתי; מותר ריק |
note |
חובה. כל שורה ממתינה לאישור רבני, וההערה אומרת זאת |
שורה אחת שהמחולל אינו מבין גורמת לו להתעלם מהרשימה כולה, ואז בתנ"ך מסומן כקודש רק
שם הוי"ה. לכן validate_fordb_book_names.py בודק כל שורה כמו המחולל ונכשל על כל בעיה.
פסוק שאינו קיים ב־DB נבדק רק במחולל, כאזהרה. שמות ספרי התנ"ך אינם שמות קבצים, ולכן
הקובץ אינו משתתף במעקב שינויי השם.
שם ספר אוצריא ב־DB הוא שם הקובץ, ולכן שינוי שם מנתק אותו מכל שורה שמזהה אותו לפי
שם. ב־push ל־main ה־CI (validate-fordb-book-names.yml, fordb_book_renames.py)
עוקב אחרי זה בעצמו: לכל קובץ .txt נארז ששונה בשמו מאז הריצה המוצלחת האחרונה, הוא
מחליף את השם הישן בחדש ב־book_info.csv (כל השורות של הספר), book_moves.csv, commentator_collective_titles.csv,
sefaria_metadata_changes.csv, book_banners.csv ו־book_protection.csv (רק באותו מקור),
ForDB/all_metadata.json, metadata.json, all_metadata_with_file_paths.json, ובשורשי ה־links הנארזים (שם קובץ ה־_links.json,
path_2, ו־heRef_2 כשהוא מתחיל בשם). שינוי שמשנה רק גרשיים (הבח → הב”ח) מתוקן
באיות ה־DB.
מה הוא לא עושה: פיצול ספר לכמה קבצים, או הוצאה מהספרייה (לריפו הפרטי extra_books), אינם שינוי שם, ולכן
השורות נמחקות כיתומות כמו קודם. שם ישן שהוביל לשני יעדים, שמופיע ב־book_renames.csv,
או שקובץ הקישורים החדש שלו כבר קיים, אינו מיושר וגם אינו נמחק, והריצה נכשלת.
הקישורים האוטומטיים אינם שמורים במאגר: הם נוצרים מחדש ב־LinkerToOtzaria בכל בנייה
(תיקיות linker_links/ הישנות נמחקו בספטמבר 2026, ואין לבדוק או לשחזר אותן).
שגיאת הקלדה או סריקה שנמצאת במקור חוזרת בכל המרה מחדש. מלבד התיקון בספר, מוסיפים
שורה ל־<מקור>/post_convert_fixes.tsv (ספר, טקסט שגוי עם הקשר ייחודי, טקסט מתוקן,
הערה). הממירים של המקורות במאגר מחילים את הקובץ דרך post_convert_fixes.py
על כל ספר שהם כותבים, ונעצרים כשעוגן חסר או כפול. בדיקה מול הספרים שבמאגר:
python post_convert_fixes.py --check <מקור>.
הקטגוריה שמופיעה באפליקציה נקבעת ב־SeforimLibrary, לא כאן. כשמדווחים על ספר "במקום הלא נכון", בדקו את שניהם — הנתיב במאגר יכול להיות תקין וה־DB עדיין שגוי:
python3 - <<'PY'
import sqlite3, os
db = os.path.expanduser('~/Downloads/seforim.db') # DB בנוי כלשהו
c = sqlite3.connect(db)
cats = {r[0]: (r[1], r[2]) for r in c.execute("select id,parentId,title from category")}
def path(cid):
p = []
while cid:
par, t = cats[cid]; p.append(t); cid = par
return "/".join(reversed(p))
for t, cid, s in c.execute(
"select b.title,b.categoryId,s.name from book b left join source s on s.id=b.sourceId "
"where b.title like ? order by b.title", ('%אור הישר%',)):
print(f"{t}\t| {path(cid)}\t| {s}")
PYב־db_version=19 (אוגוסט 2026) 26 ספרים נחתו בתיקיות לא קשורות — למשל
אור הישר על נדה תחת מחשבת ישראל/אחרונים/רמחל, אור הישר/סדר נזיקין תחת
מורה נבוכים, אור הישר/מסכתות קטנות תחת תנא דבי אליהו, ושני ספרי
אודות התוכנה תחת שות מהרשם. קובצי המקור כאן היו תקינים.
הסיבה: התיקיות שנוצרות אוטומטית עבור יעדי book_moves.csv נכתבות עם rowid
משתמע, בעוד שלב אוצריא מקצה מזהי קטגוריה מ־InMemoryIdAllocator מתמיד. מאחר ש־
renameCategories רץ כעת לפני appendOtzaria, התיקיות החדשות חטפו את המזהים
השמורים, וה־INSERT OR IGNORE של שלב אוצריא נבלע בשקט — בעוד הספרים עדיין נכתבו
עם אותו categoryId. תוקן ב־SeforimLibrary (ensureCounterAtLeast(CATEGORY, …)
ב־GenerateLines.kt + אימות־אחרי־הכנסה ב־IdAllocatorBindings.upsertCategory).
הסימן המזהה: הקטגוריה ה"נכונה" פשוט לא קיימת ב־DB, והמזהה שלה תפוס בידי
תיקייה שנוצרה מ־book_moves.csv.