lumina-wiki 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -3,6 +3,37 @@
 All notable changes to Lumina-Wiki are documented here.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [1.3.0] - 2026-05-09
+
+### Added — Local text-document ingestion (research pack)
+
+- `prepare_source.py` (research pack tool) now supports `.docx`, `.rtf`, and
+  `.epub` in addition to the existing PDF / TeX / HTML / Markdown formats.
+- Hardened against zip-bomb (raw size cap + decompressed total cap) and XXE
+  / XML billion-laughs (`defusedxml.defuse_stdlib()`) for ZIP-of-XML formats
+  (`.docx`, `.epub`).
+- DRM-protected EPUB detection: explicit error with hint instead of an
+  opaque parse crash. Lumina does not strip DRM.
+
+### Requirements
+
+- The new format support requires the **research pack**:
+  `lumina install --packs core,research`. After install run
+  `pip install -r _lumina/tools/requirements.txt` to fetch
+  `python-docx`, `striprtf`, `ebooklib`, `beautifulsoup4`, and `defusedxml`.
+- Missing libs raise an actionable `ValueError` (CLI exit 2) with the
+  `pip install …` hint — no silent empty-text writes.
+
+### Known Limitations
+
+- `.docx`: shapes, text boxes, headers/footers, table cells not extracted.
+- `.rtf`: table layout and embedded images discarded.
+- `.epub`: images, CSS, footnotes, and cross-references discarded; chapter-
+  level segmentation is **not** emitted in v1 — it will land alongside
+  `/lumi-chapter-ingest` EPUB support in a future release.
+- `.odt`, image (`.png`, `.jpg`) and scanned-PDF ingestion remain out of
+  scope. See the roadmap entry "Vision/OCR ingestion" for the follow-up.
+
 ## [1.2.0] - 2026-05-07
 
 ### Added

package/README.md

@@ -199,7 +199,8 @@ Lumina-Wiki is evolving rapidly. Here is our user-facing roadmap:
 **Near-term (Stability & New Ingestion)**
 - [ ] **`/lumi-help` Skill:** A smart assistant to help you learn and use Lumina-Wiki instantly.
 - [x] **Multilingual setup:** Choose English, Vietnamese, or Chinese as your primary language during install. *(shipped in v1.2)*
-- [ ] **Native DOCX & Image OCR:** Ingest Word files and screenshots directly into your wiki.
+- [x] **Native DOCX, RTF & EPUB ingestion:** Pull Word, Rich Text, and EPUB books straight into your wiki via the research pack. *(shipped in v1.x)*
+- [ ] **Image OCR & Scanned PDFs:** Ingest screenshots and scanned PDFs into your wiki.
 - [ ] **Advanced Paper Ranking:** See influence scores and quality signals for your research papers.
 - [x] **Improved CI/CD:** Native support for Bun and Node 22 environments. *(shipped in v1.2)*
 
@@ -221,6 +222,10 @@ Lumina-Wiki is evolving rapidly. Here is our user-facing roadmap:
 
 ## 7. Contributing & License
 
+### CLI Contract
+
+CI scripts and integrations should reference [`docs/cli-contract.md`](./docs/cli-contract.md) for the v1.x stable flag list and exit code mapping. Anything not listed there is internal and may change without notice.
+
 ### Local Development (for contributors)
 
 If you want to contribute to the `lumina-wiki` installer:

package/README.vi.md

@@ -199,7 +199,8 @@ Lumina-Wiki đang phát triển nhanh chóng. Dưới đây là lộ trình hư
 **Sắp tới (Ổn định & Mở rộng nạp tài liệu)**
 - [ ] **Kỹ năng `/lumi-help`:** Trợ lý thông minh giúp bạn học và sử dụng Lumina-Wiki tức thì.
 - [x] **Cài đặt đa ngôn ngữ:** Chọn Tiếng Anh, Tiếng Việt hoặc Tiếng Trung làm ngôn ngữ chính khi cài đặt. *(đã phát hành trong v1.2)*
-- [ ] **Ingest DOCX & OCR Ảnh:** Nạp trực tiếp file Word và ảnh chụp màn hình vào wiki.
+- [x] **Nạp DOCX, RTF & EPUB native:** Đưa thẳng file Word, Rich Text và sách EPUB vào wiki qua research pack. *(đã phát hành trong v1.x)*
+- [ ] **OCR ảnh & PDF scan:** Nạp ảnh chụp màn hình và PDF dạng scan vào wiki.
 - [ ] **Xếp hạng bài báo nâng cao:** Xem điểm số ảnh hưởng và tín hiệu chất lượng cho các nghiên cứu của bạn.
 - [x] **Cải thiện CI/CD:** Hỗ trợ chính thức cho môi trường Bun và Node 22. *(đã phát hành trong v1.2)*
 
@@ -221,6 +222,10 @@ Lumina-Wiki đang phát triển nhanh chóng. Dưới đây là lộ trình hư
 
 ## 7. Đóng góp & Giấy phép
 
+### Hợp đồng CLI
+
+Script CI và tích hợp nên tham chiếu [`docs/cli-contract.md`](./docs/cli-contract.md) để biết danh sách cờ ổn định và mapping exit code cho v1.x. Bất cứ thứ gì không liệt kê trong đó đều là nội bộ và có thể đổi mà không báo trước.
+
 ### Phát triển cục bộ (dành cho người đóng góp)
 
 Nếu bạn muốn đóng góp cho trình cài đặt `lumina-wiki`:

package/README.zh.md

@@ -200,7 +200,8 @@ Lumina-Wiki 正在快速演进。这是我们的用户路线图：
 **近期计划（稳定性与新导入支持）**
 - [ ] **`/lumi-help` 技能：** 智能助手，帮您即时学习和使用 Lumina-Wiki。
 - [x] **多语言安装：** 安装时可选英文、越南文或中文作为主语言。*（v1.2 已发布）*
-- [ ] **原生 DOCX 与图片 OCR：** 直接将 Word 文件和截图导入您的维基。
+- [x] **原生 DOCX、RTF 与 EPUB 导入：** 通过 research pack 将 Word、Rich Text 与 EPUB 电子书直接导入维基。*（v1.x 已发布）*
+- [ ] **图片 OCR 与扫描 PDF：** 将截图与扫描版 PDF 导入维基。
 - [ ] **高级论文排名：** 查看研究论文的影响力评分和质量信号。
 - [x] **改进的 CI/CD：** 正式支持 Bun 和 Node 22 环境。*（v1.2 已发布）*
 
@@ -223,6 +224,10 @@ Lumina-Wiki 正在快速演进。这是我们的用户路线图：
 
 ## 7. 贡献与许可
 
+### CLI 契约
+
+CI 脚本和集成应参考 [`docs/cli-contract.md`](./docs/cli-contract.md) 了解 v1.x 稳定标志列表和退出码映射。未在其中列出的任何内容均为内部，可能在不另行通知的情况下更改。
+
 ### 本地开发（贡献者）
 
 如果您想为 `lumina-wiki` 安装器做贡献：

package/bin/lumina.js

@@ -12,14 +12,15 @@
  *
  * Flags (all commands):
  *   --directory <path>  — installation directory (defaults to current directory)
- *   --cwd <path>        — backward-compat alias for --directory
+ *   --cwd <path>        — [deprecated] alias for --directory; removed in v2.0
  *   --yes, -y           — accept all defaults (non-interactive / CI)
  *   --no-update         — skip npm registry version check
  *   --re-link           — recompute symlink/junction/copy strategy
  *   --packs <list>      — comma-separated pack list for non-interactive install
  *   --ide-targets <list> — comma-separated IDE target list for non-interactive install
  *
- * Exit codes: 0 success, 1 user error, 2 filesystem error, 3 upgrade incompatibility
+ * Exit codes: 0 success, 1 user error, 2 filesystem/safety, 3 internal/network,
+ *             4 user cancelled (Ctrl-C in interactive prompt or declined confirm)
  */
 
 import { createRequire } from 'node:module';
@@ -76,6 +77,39 @@ if (handledVersion) process.exit(0);
 const { Command, Option } = await import('commander');
 const program = new Command();
 
+// Exit code contract (see docs/planning-artifacts/audits/cli-contract-audit.md
+// and `--help` text below). Caught errors map as follows:
+//   - RangeError (from safePath)        → 2 (path safety)
+//   - err.code in {EACCES, EPERM}        → 2 (filesystem perms)
+//   - err.code === 2 / err.code === 3    → preserved
+//   - other string fs codes (E*)         → 3 (internal/io: ENOENT, EBUSY, EIO,
+//                                            EROFS, ENOSPC, ENOTDIR, …)
+//   - everything else                    → 1 (user error)
+// ---------------------------------------------------------------------------
+function exitCodeFor(err, defaultCode = 1) {
+  if (err instanceof RangeError) return 2;
+  if (err.code === 'EACCES' || err.code === 'EPERM') return 2;
+  if (err.code === 2) return 2;
+  if (err.code === 3) return 3;
+  if (typeof err.code === 'string' && err.code.startsWith('E')) return 3;
+  return defaultCode;
+}
+
+// ---------------------------------------------------------------------------
+// Deprecation warnings — emitted to stderr once per invocation.
+// Source of truth: docs/cli-contract.md.
+// ---------------------------------------------------------------------------
+let _cwdWarned = false;
+function warnDeprecatedCwdIfUsed(cmdOpts, globalOpts) {
+  if (_cwdWarned) return;
+  if (cmdOpts.cwd != null || globalOpts.cwd != null) {
+    process.stderr.write(
+      '[deprecated] --cwd is deprecated and will be removed in v2.0. Use --directory instead.\n'
+    );
+    _cwdWarned = true;
+  }
+}
+
 program
   .name('lumina')
   .description('Lumina Wiki — domain-agnostic, multi-IDE wiki scaffolder')
@@ -84,8 +118,9 @@ program
 Exit codes:
   0  success
   1  user error (bad flag, missing prereq)
-  2  filesystem error (permission denied, path outside cwd)
-  3  upgrade incompatibility (manifest references unknown pack)
+  2  filesystem / safety (permission denied, path outside cwd, unknown pack slug)
+  3  internal / network (atomicWrite failure, 5xx, upgrade incompatibility, lint catastrophic)
+  4  user cancelled (Ctrl-C in interactive prompt or declined confirm)
 
 Flags applicable to all commands:
   --directory <path>  installation directory (defaults to current directory)
@@ -117,6 +152,13 @@ program
   .option('--no-update', 'skip npm registry version check')
   .option('--re-link', 'recompute symlink strategy from current platform capabilities');
 
+// Single source of truth for --cwd deprecation: fires once before any
+// subcommand action regardless of whether --cwd was passed globally or
+// per-command. New subcommands inherit this for free.
+program.hook('preAction', (_thisCommand, actionCommand) => {
+  warnDeprecatedCwdIfUsed(actionCommand.opts(), program.opts());
+});
+
 // ---------------------------------------------------------------------------
 // --version / -v — print immediately then do async update check
 // ---------------------------------------------------------------------------
@@ -169,11 +211,9 @@ program
     } catch (err) {
       // Top-level catch: locale may not be resolved yet (pre-loadLocale path).
       // Error strings kept as EN literals — machine-readable, intentionally exempt.
-      const isPermError  = err.code === 'EACCES' || err.code === 'EPERM';
-      const isRangeError = err instanceof RangeError;
       console.error(`[error] ${err.message}`);
       if (process.env.DEBUG) console.error(err.stack);
-      process.exit(isPermError || isRangeError || err.code === 2 ? 2 : 1);
+      process.exit(exitCodeFor(err));
     }
   });
 
@@ -200,7 +240,7 @@ program
     } catch (err) {
       console.error(`[error] ${err.message}`);
       if (process.env.DEBUG) console.error(err.stack);
-      process.exit(2);
+      process.exit(exitCodeFor(err));
     }
   });
 
@@ -235,7 +275,9 @@ discover
     } catch (err) {
       console.error(`[error] ${err.message}`);
       if (process.env.DEBUG) console.error(err.stack);
-      process.exit(err.code === 2 ? 2 : 3);
+      // Unhandled exceptions from discover-runner are by definition not user
+      // errors (main() handles those), so default unknown → 3 (internal).
+      process.exit(exitCodeFor(err, 3));
     }
   });
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "lumina-wiki",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Domain-agnostic, multi-IDE wiki scaffolder — Karpathy's LLM-Wiki vision, cross-platform and pack-based.",
   "keywords": [
     "llm-wiki",
@@ -83,9 +83,9 @@
   "devDependencies": {},
   "scripts": {
     "test": "npm run test:installer",
-    "test:installer": "node --test src/installer/commands.test.js src/installer/fs.test.js src/installer/locales.test.js src/installer/manifest.test.js src/installer/prompts.test.js src/installer/readme-templates.test.js src/installer/template-engine.test.js src/installer/update-check.test.js",
+    "test:installer": "node --test bin/lumina.flags.test.js bin/lumina.deprecations.test.js bin/lumina.cancel.test.js src/installer/commands.test.js src/installer/fs.test.js src/installer/locales.test.js src/installer/manifest.test.js src/installer/prompts.test.js src/installer/readme-templates.test.js src/installer/template-engine.test.js src/installer/update-check.test.js",
     "test:scripts": "node --test src/scripts/lint.test.mjs src/scripts/reset.test.mjs src/scripts/wiki.test.mjs src/scripts/discover-runner.test.mjs src/scripts/external-ids.test.mjs src/scripts/parse-ids.test.mjs src/scripts/merge-ids.test.mjs src/scripts/build-source.test.mjs src/scripts/wiki-yaml-object.test.mjs",
-    "test:python": "python3 -m pytest src/tools/tests -q",
+    "test:python": "node scripts/run-pytest.mjs",
     "test:all": "npm run test:installer && npm run test:scripts && npm run test:python",
     "test:fs": "node --test src/installer/fs.test.js",
     "test:manifest": "node --test src/installer/manifest.test.js",

package/src/installer/prompts.js

@@ -143,7 +143,7 @@ export function buildPromptList(existingManifest, defaultLocale = 'en') {
 /**
  * Run the five interactive install prompts.
  * Returns default answers immediately when `acceptDefaults` is true (--yes mode).
- * Calls process.exit(0) if the user cancels (Ctrl-C).
+ * Calls process.exit(4) if the user cancels (Ctrl-C) or declines a confirm prompt.
  *
  * @param {object}  [opts]
  * @param {boolean} [opts.acceptDefaults=false] - Skip prompts; return defaults.
@@ -174,7 +174,7 @@ export async function runInstallPrompts({ acceptDefaults = false, cwd = process.
   if (isCancel(localeRaw)) {
     // t may be EN or may not be loaded yet — use cancel string from t if available
     cancel(t ? t('prompt.cancelled') : 'Installation cancelled.');
-    process.exit(0);
+    process.exit(4);
   }
   const locale = localeRaw;
   const langDefault = LOCALE_LANGUAGE_NAME[locale] ?? 'English';
@@ -192,7 +192,7 @@ export async function runInstallPrompts({ acceptDefaults = false, cwd = process.
     });
     if (isCancel(proceed) || !proceed) {
       cancel(t ? t('prompt.cancelled') : 'Installation cancelled.');
-      process.exit(0);
+      process.exit(4);
     }
   }
 
@@ -203,7 +203,7 @@ export async function runInstallPrompts({ acceptDefaults = false, cwd = process.
     placeholder: cwdAbs,
     defaultValue: cwdAbs,
   });
-  if (isCancel(directoryRaw)) { cancel(t ? t('prompt.cancelled') : 'Installation cancelled.'); process.exit(0); }
+  if (isCancel(directoryRaw)) { cancel(t ? t('prompt.cancelled') : 'Installation cancelled.'); process.exit(4); }
   const directory = expandUserPath(directoryRaw, cwdAbs);
   const projectName = defaultProjectName(directory);
 
@@ -212,7 +212,7 @@ export async function runInstallPrompts({ acceptDefaults = false, cwd = process.
     message: t ? t('prompt.purpose.message') : 'Research purpose (optional — describe what this wiki is for)',
     placeholder: t ? t('prompt.purpose.placeholder') : 'e.g. Track flash-attention variants for a survey',
   });
-  if (isCancel(researchPurposeRaw)) { cancel(t ? t('prompt.cancelled') : 'Installation cancelled.'); process.exit(0); }
+  if (isCancel(researchPurposeRaw)) { cancel(t ? t('prompt.cancelled') : 'Installation cancelled.'); process.exit(4); }
   const researchPurpose = researchPurposeRaw || '';
 
   // ── Prompt 3: IDE targets ────────────────────────────────────────────────
@@ -230,7 +230,7 @@ export async function runInstallPrompts({ acceptDefaults = false, cwd = process.
     initialValues: ['claude_code'],
     required: false,
   });
-  if (isCancel(ideTargetsRaw)) { cancel(t ? t('prompt.cancelled') : 'Installation cancelled.'); process.exit(0); }
+  if (isCancel(ideTargetsRaw)) { cancel(t ? t('prompt.cancelled') : 'Installation cancelled.'); process.exit(4); }
   const ideTargets = Array.isArray(ideTargetsRaw) && ideTargetsRaw.length > 0
     ? ideTargetsRaw
     : ['claude_code'];
@@ -244,7 +244,7 @@ export async function runInstallPrompts({ acceptDefaults = false, cwd = process.
     ],
     required: false,
   });
-  if (isCancel(packsRaw)) { cancel(t ? t('prompt.cancelled') : 'Installation cancelled.'); process.exit(0); }
+  if (isCancel(packsRaw)) { cancel(t ? t('prompt.cancelled') : 'Installation cancelled.'); process.exit(4); }
   const selectedPacks = Array.isArray(packsRaw) ? packsRaw : [];
   const packs = ['core', ...selectedPacks.filter(p => p !== 'core')];
 
@@ -254,7 +254,7 @@ export async function runInstallPrompts({ acceptDefaults = false, cwd = process.
     placeholder: langDefault,
     defaultValue: langDefault,
   });
-  if (isCancel(communicationLangRaw)) { cancel(t ? t('prompt.cancelled') : 'Installation cancelled.'); process.exit(0); }
+  if (isCancel(communicationLangRaw)) { cancel(t ? t('prompt.cancelled') : 'Installation cancelled.'); process.exit(4); }
   const communicationLang = communicationLangRaw || langDefault;
 
   const documentOutputLangRaw = await text({
@@ -262,7 +262,7 @@ export async function runInstallPrompts({ acceptDefaults = false, cwd = process.
     placeholder: langDefault,
     defaultValue: langDefault,
   });
-  if (isCancel(documentOutputLangRaw)) { cancel(t ? t('prompt.cancelled') : 'Installation cancelled.'); process.exit(0); }
+  if (isCancel(documentOutputLangRaw)) { cancel(t ? t('prompt.cancelled') : 'Installation cancelled.'); process.exit(4); }
   const documentOutputLang = documentOutputLangRaw || langDefault;
 
   return {

package/src/tools/prepare_source.py

@@ -1,8 +1,8 @@
 """
 prepare_source.py — Normalize a local file into an ingest-ready package.
 
-Accepts one local file (PDF, .tex, .html, .md) and produces a deterministic
-output package at raw/tmp/<slug>/ containing:
+Accepts one local file (PDF, .tex, .html, .md, .txt, .docx, .rtf, .epub)
+and produces a deterministic output package at raw/tmp/<slug>/ containing:
     source.<ext>   — original file (hard-link or copy)
     meta.json      — extracted metadata (title, type, sha256, ext, slug, size)
     text.txt       — extracted plain text
@@ -61,10 +61,19 @@ from typing import Any
 # Constants
 # ---------------------------------------------------------------------------
 
-SUPPORTED_EXTENSIONS = {".pdf", ".tex", ".html", ".htm", ".md", ".txt"}
+SUPPORTED_EXTENSIONS = {".pdf", ".tex", ".html", ".htm", ".md", ".txt", ".docx", ".rtf", ".epub"}
 # Slug is the first 16 hex chars of the file's SHA256 — enough uniqueness.
 SLUG_LENGTH = 16
 
+# Zip-bomb defense thresholds for ZIP-of-XML formats (.docx, .epub).
+# Raw caps reject oversized files outright; decompressed caps reject ratio
+# attacks. Pre-flight only — does not stream the archive.
+MAX_DOCX_BYTES = 50_000_000              # 50 MB raw .docx
+MAX_DOCX_EXTRACTED_BYTES = 200_000_000   # 200 MB total uncompressed
+MAX_EPUB_BYTES = 100_000_000             # 100 MB raw .epub (long novels + images)
+MAX_EPUB_EXTRACTED_BYTES = 500_000_000   # 500 MB total uncompressed
+EPUB_SIZE_HINT_BYTES = 1_000_000         # extracted-text threshold for stderr note
+
 
 # ---------------------------------------------------------------------------
 # Helpers
@@ -243,6 +252,136 @@ def _extract_html_text(path: Path) -> str:
     return extractor.get_text()
 
 
+def _check_zip_safety(path: Path, max_bytes: int, max_extracted: int) -> None:
+    """Pre-flight zip-bomb defense: cap raw size + sum of uncompressed sizes."""
+    import zipfile
+
+    raw_size = path.stat().st_size
+    if raw_size > max_bytes:
+        raise ValueError(
+            f"File too large for safe extraction: {raw_size} bytes "
+            f"> {max_bytes}. Refusing to ingest."
+        )
+    try:
+        with zipfile.ZipFile(path) as zf:
+            total = sum(info.file_size for info in zf.infolist())
+            if total > max_extracted:
+                raise ValueError(
+                    f"Decompressed size {total} bytes > {max_extracted}. "
+                    f"Suspected zip-bomb; refusing to ingest."
+                )
+    except zipfile.BadZipFile as exc:
+        raise ValueError(f"Not a valid zip-based document: {exc}") from exc
+
+
+def _extract_docx_text(path: Path) -> str:
+    """Extract text from .docx. Body paragraphs only; shapes/textboxes excluded."""
+    try:
+        import defusedxml  # type: ignore[import-untyped]
+        defusedxml.defuse_stdlib()
+        from docx import Document  # type: ignore[import-untyped]
+    except ImportError as exc:
+        raise ValueError(
+            "python-docx and defusedxml required for .docx ingestion. "
+            "Install: pip install python-docx defusedxml. "
+            f"(Underlying: {exc})"
+        ) from exc
+
+    _check_zip_safety(path, MAX_DOCX_BYTES, MAX_DOCX_EXTRACTED_BYTES)
+
+    try:
+        doc = Document(str(path))
+    except Exception as exc:  # noqa: BLE001 — python-docx raises wide; surface as ValueError
+        raise ValueError(f"Cannot parse .docx (corrupt or DRM): {exc}") from exc
+
+    return "\n".join(p.text for p in doc.paragraphs)
+
+
+def _extract_rtf_text(path: Path) -> str:
+    """Extract plain text from .rtf using striprtf."""
+    try:
+        from striprtf.striprtf import rtf_to_text  # type: ignore[import-untyped]
+    except ImportError as exc:
+        raise ValueError(
+            "striprtf required for .rtf ingestion. "
+            "Install: pip install striprtf. "
+            f"(Underlying: {exc})"
+        ) from exc
+    try:
+        src = path.read_text(encoding="utf-8", errors="replace")
+    except OSError as exc:
+        raise ValueError(f"Cannot read .rtf file: {exc}") from exc
+    try:
+        return rtf_to_text(src)
+    except Exception as exc:  # noqa: BLE001 — match docx/epub: surface as ValueError exit 2
+        raise ValueError(f"Cannot parse .rtf: {exc}") from exc
+
+
+def _epub_is_drm_protected(path: Path) -> bool:
+    """Detect DRM by presence of META-INF/encryption.xml in the archive."""
+    import zipfile
+
+    try:
+        with zipfile.ZipFile(path) as zf:
+            return "META-INF/encryption.xml" in zf.namelist()
+    except zipfile.BadZipFile:
+        return False
+
+
+def _extract_epub_text(path: Path) -> str:
+    """Extract flat text from .epub by walking the spine. v1 = flat text only."""
+    try:
+        import warnings
+        import defusedxml  # type: ignore[import-untyped]
+        defusedxml.defuse_stdlib()
+        import ebooklib  # type: ignore[import-untyped]
+        from ebooklib import epub  # type: ignore[import-untyped]
+        from bs4 import BeautifulSoup  # type: ignore[import-untyped]
+    except ImportError as exc:
+        raise ValueError(
+            "ebooklib, beautifulsoup4, and defusedxml required for .epub ingestion. "
+            "Install: pip install ebooklib beautifulsoup4 defusedxml. "
+            f"(Underlying: {exc})"
+        ) from exc
+
+    _check_zip_safety(path, MAX_EPUB_BYTES, MAX_EPUB_EXTRACTED_BYTES)
+
+    if _epub_is_drm_protected(path):
+        raise ValueError(
+            "EPUB is DRM-protected (META-INF/encryption.xml present). "
+            "DRM removal is the user's responsibility; Lumina does not strip DRM."
+        )
+
+    try:
+        book = epub.read_epub(str(path))
+    except Exception as exc:  # noqa: BLE001 — ebooklib raises wide on bad XML
+        raise ValueError(f"Cannot parse .epub (corrupt or unsupported): {exc}") from exc
+
+    parts: list[str] = []
+    with warnings.catch_warnings():
+        warnings.filterwarnings("ignore", module="bs4")
+        for spine_entry in book.spine:
+            try:
+                doc = book.get_item_with_id(spine_entry[0])
+            except Exception:  # noqa: BLE001
+                continue
+            if doc is None or doc.get_type() != ebooklib.ITEM_DOCUMENT:
+                continue
+            soup = BeautifulSoup(doc.get_content(), "html.parser")
+            text = soup.get_text(separator="\n").strip()
+            if text:
+                parts.append(text)
+
+    full = "\n\n".join(parts)
+    size_bytes = len(full.encode("utf-8"))
+    if size_bytes > EPUB_SIZE_HINT_BYTES:
+        _err(
+            f"Note: extracted EPUB text {size_bytes:,} bytes (> 1 MB). "
+            "Future: /lumi-chapter-ingest may help once EPUB support lands."
+        )
+    return full
+
+
 def _extract_text(path: Path) -> str:
     """Dispatch text extraction by file extension."""
     ext = path.suffix.lower()
@@ -252,6 +391,12 @@ def _extract_text(path: Path) -> str:
         return _extract_tex_text(path)
     if ext in (".html", ".htm"):
         return _extract_html_text(path)
+    if ext == ".docx":
+        return _extract_docx_text(path)
+    if ext == ".rtf":
+        return _extract_rtf_text(path)
+    if ext == ".epub":
+        return _extract_epub_text(path)
     # .md, .txt, and other text files — read as UTF-8
     try:
         return path.read_text(encoding="utf-8", errors="replace")
@@ -366,6 +511,9 @@ def _guess_type(ext: str) -> str:
         ".htm": "webpage",
         ".md": "markdown",
         ".txt": "text",
+        ".docx": "docx",
+        ".rtf": "rtf",
+        ".epub": "epub",
     }.get(ext, "unknown")
 
 
@@ -377,8 +525,9 @@ def main(argv: list[str] | None = None) -> None:
     parser = argparse.ArgumentParser(
         prog="prepare_source.py",
         description=(
-            "Normalize a local file (PDF, .tex, .html, .md) into an ingest-ready "
-            "package under raw/tmp/<slug>/. Deterministic: same input -> same output."
+            "Normalize a local file (PDF, .tex, .html, .md, .txt, .docx, .rtf, "
+            ".epub) into an ingest-ready package under raw/tmp/<slug>/. "
+            "Deterministic: same input -> same output."
         ),
     )
     parser.add_argument("file", help="Path to the source file to prepare.")

package/src/tools/requirements.txt

@@ -13,6 +13,14 @@ pypdf>=4.0.0
 # fetch_arxiv.py, fetch_s2.py, fetch_wikipedia.py, fetch_deepxiv.py, discover.py
 requests>=2.31.0
 
+# ─── Local text-document ingestion (research pack) ──────────────────────────
+# prepare_source.py extractors for .docx/.rtf/.epub
+python-docx>=1.1.0
+striprtf>=0.0.26
+ebooklib>=0.18
+beautifulsoup4>=4.12.0
+defusedxml>=0.7.1
+
 # ─── Development ─────────────────────────────────────────────────────────────
 pytest>=7.0.0
 pytest-cov>=4.0.0