lumina-wiki 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -3,6 +3,76 @@
 All notable changes to Lumina-Wiki are documented here.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [1.4.0] - 2026-05-09
+
+### Added — `/lumi-help` orientation skill (PR #9)
+
+- New core skill `/lumi-help` with three modes:
+  - **Mode A — Orientation** (default): reads live workspace state
+    (`manifest.json`, `wiki/index.md`, `wiki/log.md`, `raw/`) and recommends
+    a single next action. Stale-log surfaces as a 30-day idle hint after
+    the primary recommendation, not as the primary action itself.
+  - **Mode B — Catalog** (`/lumi-help skills` or `/lumi-help catalog`): parses
+    `_lumina/schema/lumi-help.csv` and renders the full skill list grouped by
+    pack. Only sections matching installed packs are rendered at install time.
+  - **Mode C — Framework Q&A** (`/lumi-help explain <question>`): answers
+    how-it-works questions by citing shipped schema docs (`README.md` schema
+    block, `page-templates.md`, `cross-reference-packs.md`, `graph-packs.md`,
+    and the relevant `SKILL.md`).
+- `src/templates/_lumina/schema/lumi-help.csv` — pack-conditional skill
+  catalog (CSV, `{{#if pack_*}}` gates rendered at install time). Single
+  source of truth for skill names, menu strings, and prerequisite ordering.
+- `src/templates/_lumina/schema/lumi-help-runbook.md` — procedural detail
+  (bash probes, decision ladder, output formats) separated from the SKILL.md
+  contract; loaded on demand.
+- `cleanupObsoleteCatalog()` in `manifest.js` removes the pre-v1.4
+  `skills-catalog.md` and `_state/skills-manifest.json` on re-install —
+  best-effort, `ENOENT` is not an error.
+- `scripts/verify-lumi-help.test.mjs` — integrity test: validates CSV header
+  contract, column counts, id/menu uniqueness, valid enum values, pack gating,
+  and cross-references for all four pack combinations.
+- `test:catalog` script wired into `package.json` (`node --test scripts/verify-lumi-help.test.mjs`).
+- User guides (EN/VI/ZH) gain a `/lumi-help` section and a "Meet /lumi-help"
+  opener in Quick Start.
+
+### Fixed
+
+- `--cwd` / `--directory` flag propagation regression: dropping the
+  program-level `process.cwd()` default unmasks user-supplied `--cwd` values
+  that were being short-circuited by commander's `??` chain. Pinned by new
+  tests in `bin/lumina.deprecations.test.js`.
+
+## [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
@@ -313,7 +383,11 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ---
 
-[Unreleased]: https://github.com/tronghieu/lumina-wiki/compare/v1.0.0...HEAD
+[Unreleased]: https://github.com/tronghieu/lumina-wiki/compare/v1.4.0...HEAD
+[1.4.0]: https://github.com/tronghieu/lumina-wiki/compare/v1.3.0...v1.4.0
+[1.3.0]: https://github.com/tronghieu/lumina-wiki/compare/v1.2.0...v1.3.0
+[1.2.0]: https://github.com/tronghieu/lumina-wiki/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/tronghieu/lumina-wiki/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/tronghieu/lumina-wiki/compare/v0.9.1...v1.0.0
 [0.9.1]: https://github.com/tronghieu/lumina-wiki/compare/v0.9.0...v0.9.1
 [0.9.0]: https://github.com/tronghieu/lumina-wiki/compare/v0.8.1...v0.9.0

package/README.md

@@ -177,6 +177,7 @@ These are the commands you can use when chatting with your AI agent.
 | | `/lumi-check` | Check the wiki for errors, such as broken links. |
 | | `/lumi-reset` | Safely reset parts of the wiki. |
 | | `/lumi-verify` | Check that wiki notes match the sources they cite. Reports anything suspicious for your review; never edits notes for you. |
+| | `/lumi-help` | Read your workspace state and recommend one next action. Pass `skills` to list every command, or `explain <topic>` to ask how Lumina itself works (e.g., `/lumi-help explain bidirectional links`). |
 | **Research** | `/lumi-research-discover` | Discover and rank relevant research papers. |
 | | `/lumi-research-watchlist` | Choose research topics for scheduled discovery with AI help. |
 | | `/lumi-research-survey` | Create a survey or summary from existing knowledge. |
@@ -197,9 +198,10 @@ The scripts behind these skills live in `_lumina/scripts/` and `_lumina/tools/`;
 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] **`/lumi-help` Skill:** A smart assistant that reads your workspace state and tells you the one thing to do next; `skills` shows every command, `explain <topic>` answers how Lumina itself works.
 - [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 +223,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

@@ -177,6 +177,7 @@ Xem [Hướng dẫn Nâng cao](docs/user-guide/advanced-qmd.vi.md) để biết
 | | `/lumi-check` | Kiểm tra lỗi trong wiki (liên kết hỏng, v.v.). |
 | | `/lumi-reset` | Xóa các phần của wiki một cách an toàn. |
 | | `/lumi-verify` | Kiểm tra xem các trang wiki có khớp với nguồn đã trích dẫn không. Báo cáo những điểm đáng ngờ để bạn xem xét; không tự sửa ghi chú giúp bạn. |
+| | `/lumi-help` | Đọc trạng thái workspace và đề xuất một bước tiếp theo. Gõ `/lumi-help skills` để xem toàn bộ danh sách lệnh, hoặc `/lumi-help explain <chủ đề>` để hỏi Lumina hoạt động ra sao (ví dụ `/lumi-help explain bidirectional links`). |
 | **Research**| `/lumi-research-discover` | Khám phá và xếp hạng các bài báo nghiên cứu liên quan. |
 | | `/lumi-research-watchlist` | Giúp bạn chọn các chủ đề nghiên cứu để AI tìm định kỳ. |
 | | `/lumi-research-survey` | Tạo một bài tổng quan/khảo sát từ kiến thức hiện có. |
@@ -197,9 +198,10 @@ Các script chạy nền nằm trong `_lumina/scripts/` và `_lumina/tools/`; th
 Lumina-Wiki đang phát triển nhanh chóng. Dưới đây là lộ trình hướng tới người dùng của chúng tôi:
 
 **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] **Kỹ năng `/lumi-help`:** Trợ lý thông minh đọc trạng thái workspace và mách bạn bước tiếp theo; gõ `/lumi-help skills` để xem toàn bộ lệnh, hoặc `/lumi-help explain <chủ đề>` để hỏi Lumina hoạt động ra sao.
 - [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 +223,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

@@ -178,6 +178,7 @@ npx skills add https://github.com/tobi/qmd --skill qmd
 | | `/lumi-check` | 检查 wiki 中的问题（断链等）。 |
 | | `/lumi-reset` | 安全地删除 wiki 的部分内容。 |
 | | `/lumi-verify` | 核查 wiki 里的笔记是否与引用的来源相符。把可疑之处报告给你审阅；不会替你修改笔记。 |
+| | `/lumi-help` | 读取工作区状态，给出下一步该做的一条建议。加参数 `/lumi-help skills` 可查看全部命令清单，或 `/lumi-help explain <主题>` 询问 Lumina 自己的工作原理（例如 `/lumi-help explain bidirectional links`）。 |
 | **Research**| `/lumi-research-discover` | 发现并排序相关研究论文。 |
 | | `/lumi-research-watchlist` | 帮你选择要定期查找的研究主题。 |
 | | `/lumi-research-survey` | 从现有知识创建综述/调研。 |
@@ -198,9 +199,10 @@ npx skills add https://github.com/tobi/qmd --skill qmd
 Lumina-Wiki 正在快速演进。这是我们的用户路线图：
 
 **近期计划（稳定性与新导入支持）**
-- [ ] **`/lumi-help` 技能：** 智能助手，帮您即时学习和使用 Lumina-Wiki。
+- [x] **`/lumi-help` 技能：** 智能助手读取工作区状态并告诉你下一步该做什么；加参数 `/lumi-help skills` 可查看全部命令清单，或 `/lumi-help explain <主题>` 询问 Lumina 本身的工作原理。
 - [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 +225,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)
@@ -110,13 +145,33 @@ Examples:
 // ---------------------------------------------------------------------------
 // Global options
 // ---------------------------------------------------------------------------
+//
+// IMPORTANT: --directory has NO default here on purpose.
+// If we set `process.cwd()` as the default, commander stores it on
+// `globalOpts.directory` for every invocation — even when the user only
+// passed `--cwd <path>` (which lands on globalOpts.cwd because commander
+// hoists global-shaped flags up regardless of where in argv they appear).
+// The merge expression in each subcommand uses
+//   cmdOpts.directory ?? cmdOpts.cwd ?? globalOpts.directory ?? globalOpts.cwd ?? process.cwd()
+// and `??` short-circuits as soon as one of those is non-nullish — so a
+// program-level default of process.cwd() would *always* win over the user's
+// `--cwd` value. The trailing `?? process.cwd()` in the merge expression is
+// the single source of truth for the no-flag default; do not duplicate it
+// here. Regression: see test "install --cwd <tmp> writes into <tmp>, not cwd".
 program
-  .option('--directory <path>', 'installation directory', process.cwd())
+  .option('--directory <path>', 'installation directory')
   .addOption(new Option('--cwd <path>', 'alias for --directory').hideHelp())
   .option('-y, --yes', 'accept all defaults (non-interactive)')
   .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 +224,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 +253,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 +288,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.4.0",
   "description": "Domain-agnostic, multi-IDE wiki scaffolder — Karpathy's LLM-Wiki vision, cross-platform and pack-based.",
   "keywords": [
     "llm-wiki",
@@ -83,10 +83,11 @@
   "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:catalog": "node --test scripts/verify-lumi-help.test.mjs",
     "test:fs": "node --test src/installer/fs.test.js",
     "test:manifest": "node --test src/installer/manifest.test.js",
     "test:template": "node --test src/installer/template-engine.test.js",

package/src/installer/commands.js

@@ -37,6 +37,7 @@ import {
   writeSkillsManifest,
   readFilesManifest,
   writeFilesManifest,
+  cleanupObsoleteCatalog,
   MANIFEST_SCHEMA_VERSION,
 } from './manifest.js';
 import {
@@ -338,6 +339,10 @@ export async function installCommand(opts = {}) {
   await writeManifest(projectRoot, manifest);
   await writeSkillsManifest(projectRoot, skillRows);
   await writeFilesManifest(projectRoot, fileRows);
+  // Remove pre-v1.4 catalog files (skills-catalog.md, _state/skills-manifest.json)
+  // if they linger from an earlier install. The canonical catalog is
+  // _lumina/schema/lumi-help.csv, rendered by renderSchemaDocs above.
+  await cleanupObsoleteCatalog(projectRoot);
 
   // 17.5. Post-upgrade: spawn lint --summary, print banner if findings exist
   if (isUpgrade && existingManifest.packageVersion !== PKG.version) {
@@ -1025,6 +1030,7 @@ function getSkillDefs(packs) {
       { name: 'reset',           canonicalId: 'lumi-reset',           displayName: '/lumi-reset' },
       { name: 'verify',          canonicalId: 'lumi-verify',          displayName: '/lumi-verify' },
       { name: 'migrate-legacy',  canonicalId: 'lumi-migrate-legacy',  displayName: '/lumi-migrate-legacy' },
+      { name: 'help',            canonicalId: 'lumi-help',            displayName: '/lumi-help' },
     ];
     for (const s of coreSkills) {
       defs.push({ ...s, pack: 'core', srcPackPath: 'core' });
@@ -1086,7 +1092,7 @@ async function copyTools(projectRoot, { research }) {
 
 async function renderSchemaDocs(projectRoot, templateVars) {
   const schemaDir = join(projectRoot, '_lumina', 'schema');
-  const schemaDocs = ['page-templates.md', 'cross-reference-packs.md', 'graph-packs.md'];
+  const schemaDocs = ['page-templates.md', 'cross-reference-packs.md', 'graph-packs.md', 'lumi-help.csv', 'lumi-help-runbook.md'];
 
   for (const doc of schemaDocs) {
     const templatePath = join(TEMPLATES_DIR, '_lumina', 'schema', doc);
@@ -1215,6 +1221,8 @@ async function buildFilesManifest(projectRoot, packs, pkgVersion) {
     '_lumina/schema/page-templates.md',
     '_lumina/schema/cross-reference-packs.md',
     '_lumina/schema/graph-packs.md',
+    '_lumina/schema/lumi-help.csv',
+    '_lumina/schema/lumi-help-runbook.md',
     'CLAUDE.md',
     'AGENTS.md',
     'GEMINI.md',

package/src/installer/manifest.js

@@ -3,10 +3,17 @@
  * @description Reader/writer for the three Lumina installer state files.
  *
  * Three state files (single concern each, atomic write per file):
- *   1. _lumina/manifest.json       — install state
- *   2. _lumina/_state/skills-manifest.csv — skill inventory
+ *   1. _lumina/manifest.json              — install state
+ *   2. _lumina/_state/skills-manifest.csv — skill inventory (paths/sha/version)
  *   3. _lumina/_state/files-manifest.csv  — hash tracking
  *
+ * The workflow catalog is _lumina/schema/lumi-help.csv — it is the
+ * canonical source of truth for /lumi-help (read directly at runtime). No
+ * derived JSON mirror exists; commands.js renders the .csv template at
+ * install time and lumi-help reads it via Bash. Earlier versions of the
+ * installer wrote a derived _state/skills-manifest.json — that file is now
+ * obsolete and is cleaned up on re-install.
+ *
  * All writes go through atomicWrite from fs.js.
  * Reads are defensive: missing file → null; truncated CSV → empty rows + warning.
  */
@@ -355,12 +362,41 @@ export function migrateManifest(manifest, targetVersion) {
   return m;
 }
 
+// ---------------------------------------------------------------------------
+// Obsolete-file cleanup
+// ---------------------------------------------------------------------------
+
+/**
+ * Remove obsolete catalog files left behind by older installs.
+ *
+ * Pre-v1.4 installs wrote two files that are no longer used:
+ *   - _lumina/schema/skills-catalog.md         (replaced by lumi-help.csv)
+ *   - _lumina/_state/skills-manifest.json      (no longer derived)
+ *
+ * This is best-effort — missing files are not an error.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<void>}
+ */
+export async function cleanupObsoleteCatalog(projectRoot) {
+  const { unlink } = await import('node:fs/promises');
+  const candidates = [
+    join(projectRoot, '_lumina', 'schema', 'skills-catalog.md'),
+    join(projectRoot, '_lumina', '_state', 'skills-manifest.json'),
+  ];
+  await Promise.all(candidates.map(async (p) => {
+    try { await unlink(p); } catch (err) {
+      if (err.code !== 'ENOENT') throw err;
+    }
+  }));
+}
+
 // ---------------------------------------------------------------------------
 // State file paths helper
 // ---------------------------------------------------------------------------
 
 /**
- * Return the canonical paths for all three state files.
+ * Return the canonical paths for all installer state files.
  *
  * @param {string} projectRoot
  * @returns {{ manifestJson: string, skillsCsv: string, filesCsv: string }}

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/skills/core/help/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: lumi-help
+description: >
+  Orient the user in their Lumina wiki workspace. Three modes:
+  Orientation (default — recommend ONE next action; offer to run),
+  Catalog (on `skills`/`list` arg or features question — render
+  lumi-help.csv grouped by pack), Framework Q&A (on `explain`
+  arg or how-it-works question — answer from local docs with
+  citations). Use when the user says "help", "what next", "I'm lost",
+  asks for orientation, or asks how Lumina works.
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# /lumi-help
+
+Read `README.md` at the project root before this SKILL.md.
+
+This file is the contract — it has everything you need for normal invocations.
+For precision detail (exact Bash commands, full output templates, multilingual
+keyword lists, fallback codes) consult `_lumina/schema/lumi-help-runbook.md`
+**only when the relevant section explicitly points to it**. Don't load it
+upfront — Mode B never needs it.
+
+## Purpose
+
+Help the user know:
+
+1. **Where they are** — installed packs, what's done, what's pending.
+2. **What to do next** — ONE recommended skill with a cited reason.
+3. **How to invoke it** — name, args, language hint; offer to run for them.
+4. **What's available** — full catalog grouped by pack on demand.
+5. **How Lumina works** — framework questions answered from local docs with citations.
+
+## Step 0 · Read languages, ALWAYS first
+
+Before mode routing, read `_lumina/config/lumina.config.yaml` and bind:
+
+- `COMM_LANG` ← `communication_language` — language of every word back to user.
+- `DOC_LANG` ← `document_output_language` — surfaced when recommending a write-skill.
+
+User never passes a language flag. Match input tone (casual ↔ formal).
+
+## Three modes (router decides AFTER Step 0, BEFORE other reads)
+
+| Trigger | Mode | Job |
+|---|---|---|
+| no arg, or "help / what next / I'm lost" | **A · Orientation** | recommend ONE next action; offer to run |
+| `skills`/`catalog`/`list`, or features question | **B · Catalog** | render `lumi-help.csv` grouped by pack |
+| `explain`/`docs`, or how-it-works question | **C · Q&A** | answer with doc citations |
+
+Keyword detection is multilingual (EN + VI + ZH). Mode B takes precedence over
+C. If the question is about wiki *content* (not the framework), bridge to
+`/lumi-ask` instead of answering in Mode C.
+
+> When the user's input language is not English, or when the trigger is borderline,
+> read the full keyword lists at `_lumina/schema/lumi-help-runbook.md` § Router
+> before deciding. English plain-text triggers can be matched from this table alone.
+
+## Mode A — Orientation (5 steps: locate → detect → compute → ground → cite)
+
+Decision ladder is **load-bearing** — pick first match in this order:
+
+1. Manifest missing → `/lumi-init`.
+2. Required skill with both gates satisfied (`after` AND `before`),
+   completed=false → that skill.
+3. raw/ files not yet ingested → `/lumi-ingest`.
+4. Default → `/lumi-ask`.
+
+Output: skill recommendation + one-sentence reason in `COMM_LANG` + `→ Run`
+line + (write-skill only) `DOC_LANG` note + citation arrow + **"Want me to run
+it now? (yes / show me first / skip)"**. Skip the prompt for case (4). On
+"yes" → invoke; otherwise don't.
+
+> For the exact Bash reads at each step (locate / detect / ground), the full
+> formal-and-casual output templates, the idle-wiki hint format, and fallback
+> codes (`__NO_MANIFEST__`, `__NO_CATALOG__`, `__NO_GRAPH__`, `__NO_DATE__`),
+> read `_lumina/schema/lumi-help-runbook.md` § Mode A before producing output.
+
+## Mode B — Catalog
+
+Parse `_lumina/schema/lumi-help.csv`. Group rows by `pack` in order
+core → research → reading → other (alphabetical). Pack labels are hardcoded:
+
+- `core` → "Core (always installed)"
+- `research` → "Research pack"
+- `reading` → "Reading pack"
+- other → pack name with first letter capitalized
+
+Each entry: `` `[<menu>]` `/<id>` <args if non-empty> — <description> ``. End with
+two footer pointers to `/lumi-help` (orientation) and `/lumi-help explain <topic>`
+(framework Q&A). **Mode B never needs the runbook.**
+
+## Mode C — Framework Q&A (5 steps: same skeleton as A)
+
+Doc paths are stable, all shipped to the workspace at install time:
+
+| Doc | When |
+|---|---|
+| `README.md` (`<!-- lumina:schema -->` block) | core concepts: layout, page types, link syntax, cross-reference rules, constraints, skills overview |
+| `_lumina/schema/page-templates.md` | page-type frontmatter + section structure |
+| `_lumina/schema/cross-reference-packs.md` | bidirectional-link rules and pack extensions |
+| `_lumina/schema/graph-packs.md` | edge type vocabulary for `wiki/graph/edges.jsonl` |
+| `.agents/skills/<skill-id>/SKILL.md` | when the question is specifically about one skill's behavior |
+
+Use the Read tool (not Bash). Read just the slice you need. Build a 1–4
+sentence answer in `COMM_LANG` with a `**Source**:` line. If no doc covers
+the question, say so and point at the closest.
+
+> For the exact output templates (formal, casual, no-doc fallback) and the
+> rules for when to append the optional "→ Try it" line, read
+> `_lumina/schema/lumi-help-runbook.md` § Mode C before producing output.
+
+## Data sources (read-only)
+
+| Source | Read in |
+|---|---|
+| `_lumina/config/lumina.config.yaml` | Step 0 (every invocation) |
+| `_lumina/manifest.json` | Mode A |
+| `_lumina/schema/lumi-help.csv` | Mode A, B |
+| `wiki.mjs list-entities`, `wiki/log.md`, `raw/`, `wiki/index.md` | Mode A |
+| `README.md` schema block, `_lumina/schema/page-templates.md`, `cross-reference-packs.md`, `graph-packs.md`, target skill's `SKILL.md` | Mode C |
+
+## Constraints
+
+- Read only the sources above. Never write a file. Never call mutating
+  `wiki.mjs` subcommands. Read-only ones allowed: `list-entities`,
+  `read-meta`, `read-edges`, `read-citations`, `resolve-alias`.
+- Respond in `COMM_LANG`. Surface `DOC_LANG` next to write-skills.
+- Cite every non-trivial claim in Mode C — if a doc does not say it, don't assert it.
+- Never read `wiki/` page bodies in Mode C, never `raw/`. Reading another skill's `SKILL.md` is allowed only when the user's question is specifically about that skill's behavior.
+- "Want me to run it now?" is a soft prompt — invoke only on affirmative reply.
+- Match the user's tone (casual ↔ formal).
+- All Bash reads happen before reasoning; never infer state from prior conversation.
+- When recommending a verification skill (`/lumi-check`, `/lumi-verify`) right after a write skill (`/lumi-ingest`, `/lumi-edit`, `/lumi-research-*`, `/lumi-reading-*`), suggest the user run it in a fresh context window or via a subagent — the writing context biases the check.

package/src/templates/README.md

@@ -187,6 +187,7 @@ Skills live in `.agents/skills/` and are invoked via slash commands. Active inst
 | `/lumi-check`  | manual/weekly  | Lint: broken links, orphans, missing reverse links    |
 | `/lumi-reset`  | manual         | Scoped destructive cleanup                            |
 | `/lumi-verify` | manual         | Check that wiki pages match the sources they cite; reports suspicious statements for the user to review; never auto-edits                            |
+| `/lumi-help`   | manual         | Read workspace state and recommend the single next action; offer to run it. Argument `skills`/`catalog`/`list` (or a "what's available" question) switches to catalog mode and renders `_lumina/schema/lumi-help.csv` grouped by pack. |
 
 {{#if pack_research}}### Pack: research
 

package/src/templates/_lumina/schema/lumi-help-runbook.md

@@ -0,0 +1,220 @@
+# /lumi-help — runbook
+
+Procedural detail for the `lumi-help` skill: exact Bash commands, output
+templates, multilingual keyword lists, and fallback codes. The skill reads this
+file when it needs precision; `SKILL.md` is the contract.
+
+## Step 0 · Read languages (always first)
+
+```bash
+sed -n 's/^communication_language:[[:space:]]*"\?\([^"]*\)"\?.*/\1/p' \
+  _lumina/config/lumina.config.yaml
+sed -n 's/^document_output_language:[[:space:]]*"\?\([^"]*\)"\?.*/\1/p' \
+  _lumina/config/lumina.config.yaml
+```
+
+Bind two locals:
+
+- `COMM_LANG` — every word back to user. If config missing or empty, fall back
+  to the language detected from the user's most recent message.
+- `DOC_LANG` — surface this whenever recommending a write-skill (`/lumi-init`,
+  `/lumi-ingest`, `/lumi-edit`, `/lumi-research-*`, `/lumi-reading-*`).
+
+Also snap tone from the input: casual → casual response register; formal →
+templated form.
+
+## Router · multilingual keyword lists
+
+**Mode B — Catalog** (priority over C):
+`skills`, `catalog`, `list`, `features`, `available`, `commands`,
+`capabilities`, `tính năng`, `khả năng`, `lệnh`, `liệt kê`, `có gì`,
+`có những gì`, `什么命令`, `有什么`, `命令`.
+
+**Mode C — Framework Q&A** requires BOTH:
+
+- *Question form*: `how does`, `how do`, `what is`, `what's the difference`,
+  `why does`, `why do`, `explain`, `tell me about`, `cách nào`, `như thế nào`,
+  `tại sao`, `giải thích`, `nghĩa là gì`, `怎么`, `如何`, `为什么`, `解释`, `什么是`.
+- *Plus Lumina noun*: `lumi-`, `wiki`, `raw`, `foundations`, `outputs`,
+  `summary`, `concepts`, `sources`, `ingest`, `bidirectional`, `link`, `edge`,
+  `graph`, `frontmatter`, `slug`, `pack`, `lint`, `manifest`, `Lumina`.
+
+If the question is about wiki *content* (not framework), bridge to `/lumi-ask`
+instead of Mode C.
+
+## Mode A · Bash reads
+
+### Step a · Locate
+
+```bash
+cat _lumina/manifest.json 2>/dev/null || echo "__NO_MANIFEST__"
+cat _lumina/schema/lumi-help.csv 2>/dev/null || echo "__NO_CATALOG__"
+date +%Y-%m-%d 2>/dev/null || echo "__NO_DATE__"
+```
+
+`__NO_MANIFEST__` → recommend `/lumi-init`, stop.
+`__NO_CATALOG__` → recommend re-running `npx lumina-wiki install`, stop.
+
+CSV header: `id,menu,pack,phase,after,before,required,args,outputs,description`.
+Multi-value fields (`after`, `before`, `outputs`) are semicolon-separated.
+
+### Step b · Detect state
+
+```bash
+node _lumina/scripts/wiki.mjs list-entities 2>/dev/null || echo "__NO_GRAPH__"
+grep -E "^## \[[0-9]{4}-[0-9]{2}-[0-9]{2}\] " "wiki/log.md" 2>/dev/null | tail -n 30
+find "raw/" -maxdepth 1 -type f ! -name ".*" ! -name ".gitkeep" 2>/dev/null | sort
+sed -n '/^<!-- lumina:index -->/,/^<!-- \/lumina:index -->/p' "wiki/index.md" 2>/dev/null | head -200
+```
+
+Substitute `raw/`, `wiki/log.md`, `wiki/index.md` with paths from
+`manifest.resolvedPaths` if relocated. `__NO_GRAPH__` → entity counts = 0.
+
+The index grep is supplementary context only — `list-entities` is the source
+of truth for ingested-entity coverage. Detect raw/ orphans by diffing the
+`find raw/` output against `list-entities`, not against the index block.
+
+### Step c · Compute next (DAG over CSV)
+
+For every row S:
+
+1. Pack gating — already done by installer (rendered CSV is in-scope).
+2. Completion — true if any `S.outputs` glob matches a live entity OR `S.id`
+   appears in parsed log entries.
+3. Upstream — every id in `S.after` must be completed.
+4. Downstream — for every other row T, if `T.before` contains `S.id`, S depends
+   on T: don't pick S before T has run.
+5. Phase order: `1-bootstrap → 2-ingest → 3-query → anytime`.
+
+Pick (first match wins):
+
+1. Manifest missing → `lumi-init`. *Reason: workspace not initialized.*
+2. Required skill, both gates satisfied, completed=false (phase order) →
+   that skill. *Reason: this required step is the next gate.*
+3. raw/ orphans exist → `lumi-ingest`. *Reason: N file(s) in `raw/` not yet
+   ingested. Include filenames when N ≤ 3.*
+4. Default → `lumi-ask`. *Reason: wiki is healthy — query the knowledge base.*
+
+Idle hint (additive, never replaces primary): if last `## [YYYY-MM-DD]` log
+heading is more than 30 days before today, append:
+
+> Hint: No wiki activity in N days — `/lumi-check` runs a graph-health audit when you're ready.
+
+### Step d · Ground
+
+For S.id `lumi-X`, citation in priority order:
+
+1. `node _lumina/scripts/wiki.mjs resolve-alias "X"` → if returns
+   `foundations/<slug>`, use it.
+2. Else: `.agents/skills/lumi-X/SKILL.md` "<section heading>".
+3. Else: `README.md` "Available Skills".
+
+One `resolve-alias` call. No retry. Omit citation arrow when none found.
+
+### Step e · Output template (formal register)
+
+```
+## Lumina — Next action
+
+**`[<menu>]` /<skill-name>** — <display name>
+[Reason — one sentence in COMM_LANG]
+
+→ Run: `/<skill-name>` [<args>]
+[if write-skill: "Wiki pages will be written in <DOC_LANG>."]
+
+↳ <citation path>     ← only if step d found one
+[Idle-wiki hint, if applicable]
+
+Want me to run it now? (yes / show me first / skip)
+
+To see every available skill: `/lumi-help skills`
+For how Lumina works: `/lumi-help explain <topic>`
+```
+
+Skip the "Want me to run it now?" prompt for case (4) — `/lumi-ask` is the
+default-healthy state, no offer needed.
+
+If user replies "yes" → invoke the recommended skill in this conversation.
+Anything non-affirmative ("show me first", "skip", silence) → don't invoke.
+
+### Step e · Output template (casual register)
+
+When input is casual ("hi bro", "chào", "嗨", emojis, slang), drop the `##`
+heading and the trailing two-line footer. Lead with a one-sentence answer in
+`COMM_LANG`, then the bullet, then "Want me to run it now?". Keep the citation
+arrow `↳` if step d found one.
+
+## Mode B · Catalog rendering
+
+```bash
+cat _lumina/schema/lumi-help.csv 2>/dev/null || echo "__NO_CATALOG__"
+```
+
+Parse with the canonical header. Group rows by `pack` in order:
+core → research → reading → other (alphabetical). Within each group, preserve
+the row order in the CSV.
+
+Pack labels (hardcoded):
+
+- `core` → "Core (always installed)"
+- `research` → "Research pack"
+- `reading` → "Reading pack"
+- other → pack name with first letter capitalized
+
+Output:
+
+```
+## Lumina — Skills catalog
+
+### <Pack label>
+
+- `[<menu>]` `/<id>` <args if non-empty> — <description>
+- `[<menu>]` `/<id>` <args if non-empty> — <description>
+
+### <Pack label>
+
+- ...
+
+→ For a recommendation based on your current state: `/lumi-help`
+→ For a how-it-works question about Lumina: `/lumi-help explain <topic>`
+```
+
+Render `args` directly after the id with a single space, e.g.
+`` `/lumi-ingest` [path/to/file] — read a source ... ``.
+
+`__NO_CATALOG__` → fall back to Mode A with a one-line note that the catalog
+file is missing and re-running `npx lumina-wiki install` is needed. Never
+invent a skill list from memory.
+
+## Mode C · Output templates
+
+### Formal register
+
+```
+## Lumina — <topic phrased as a noun>
+
+<direct answer, 1–4 sentences in COMM_LANG>
+
+**Source**: `<path>` § <section heading>
+[Optional 2nd source line if claim spans multiple docs]
+
+→ Try it: `/<skill-name>` [<args>] — <one-line nudge>
+[if Try-it points at a write-skill: "Wiki pages will be written in <DOC_LANG>."]
+```
+
+The "Try it" line is optional — include only when an obviously-relevant next
+skill exists (e.g. an "explain ingest" answer naturally points at
+`/lumi-ingest`).
+
+### No-doc fallback
+
+```
+## Lumina — <topic>
+
+The local docs don't cover this directly. The closest reference is `<path>`. You can also open an issue at the lumina-wiki repository if this is a real gap.
+```
+
+### Casual register
+
+Same content, but drop the `## Lumina — <topic>` heading and lead with the
+answer directly. Keep the `**Source**:` line — citations are non-negotiable.

package/src/templates/_lumina/schema/lumi-help.csv

@@ -0,0 +1,23 @@
+id,menu,pack,phase,after,before,required,args,outputs,description
+lumi-init,IN,core,1-bootstrap,,lumi-ingest,true,,_lumina/manifest.json;wiki/index.md,bootstrap a wiki from existing raw/ content
+lumi-ingest,IG,core,2-ingest,lumi-init,lumi-ask,true,[path/to/file],wiki/sources/**;wiki/log.md,"read a source and write a wiki page (drafts shown for review, then continues unless judgment is needed)"
+lumi-ask,AS,core,3-query,lumi-ingest,,false,[your question],wiki/outputs/**;wiki/summary/**,"query the wiki, synthesize an answer, optionally file a page"
+lumi-edit,ED,core,anytime,,,false,[path/to/wiki/page],,"add, remove, or revise wiki content"
+lumi-check,CH,core,anytime,,,false,,,"lint — broken links, orphans, missing reverse links"
+lumi-reset,RS,core,anytime,,,false,,,scoped destructive cleanup (never touches raw/)
+lumi-verify,VR,core,anytime,,,false,,,flag wiki claims that diverge from cited sources (never auto-edits)
+lumi-help,HP,core,anytime,,,false,[skills | explain <topic>],,"orient yourself; recommend the next action; answer questions about Lumina itself"
+{{#if pack_research}}
+lumi-research-prefill,RP,research,1-bootstrap,lumi-init,lumi-ingest,false,,wiki/foundations/**,seed foundations/ to prevent concept duplication
+lumi-research-discover,RD,research,2-ingest,,lumi-ingest,false,,raw/discovered/**,ranked candidate shortlist of new sources
+lumi-research-watchlist,RW,research,anytime,,lumi-research-discover,false,,_lumina/config/watchlist.yml,choose topics for scheduled discovery
+lumi-research-survey,RV,research,3-query,lumi-ingest,,false,,wiki/summary/**,narrative synthesis across a topic's sources
+lumi-research-topic,RT,research,3-query,lumi-ingest,,false,,wiki/topics/**,cluster concepts and sources into a thematic topic page
+lumi-research-setup,RSS,research,anytime,,,false,,.env,interactive API key configuration
+{{/if}}
+{{#if pack_reading}}
+lumi-reading-chapter-ingest,RCI,reading,2-ingest,lumi-init,,false,[chapter],wiki/chapters/**;wiki/characters/**;wiki/themes/**;wiki/plot/**,file a chapter; update characters/themes/plot pages
+lumi-reading-character-track,RCT,reading,3-query,lumi-reading-chapter-ingest,,false,,wiki/characters/**,build or refresh a character profile across chapters
+lumi-reading-theme-map,RTM,reading,3-query,lumi-reading-chapter-ingest,,false,,wiki/themes/**,trace a theme across chapters with citations
+lumi-reading-plot-recap,RPR,reading,3-query,lumi-reading-chapter-ingest,,false,,wiki/plot/**,spoiler-bounded plot summary up to a chapter
+{{/if}}

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