lumina-wiki 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -3,6 +3,113 @@
 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
+
+- **Multilingual installer (PR #7).** Interactive installer prompts and
+  rendered banners now ship in English, Vietnamese, and Simplified Chinese.
+  Language is selected at install time and persisted; upgrades read the
+  prior choice from manifest config. Localization covers prompts, summary
+  output, and post-install banner — workspace template content is unchanged.
+- **Persistent HTTP GET cache for fetchers (PR #5).** New
+  `_lumina/tools/http_cache.py` provides a content-addressed, file-backed
+  cache layer for arxiv / DOI / Semantic Scholar / web GET requests, shared
+  across `discover` and `ingest` runs. TTL is configurable via env
+  (validated at load time) and a cache schema version pins the on-disk
+  format so future shape changes self-invalidate. List-of-tuples query
+  params bypass caching by design.
+- **Bun smoke job in CI (PR #3).** GitHub Actions now runs a Bun
+  compatibility job alongside Node, catching runtime divergences early
+  (path resolution, module loading, child-process spawn) without making
+  Bun a supported runtime contract.
+- **Claude Code GitHub Actions workflows (PR #8).** Two opt-in workflows —
+  Claude PR Assistant (mention-triggered) and Claude Code Review (auto on
+  PR open/sync) — are shipped under `.github/workflows/`. Both are
+  restricted to repository maintainers on this public repo to prevent
+  unsolicited token usage from forks.
+- Source pages gain an optional `external_ids` frontmatter object holding
+  validated cross-source identifiers across four namespaces: `doi`, `arxiv`,
+  `s2`, and `url` (canonical form). The namespace registry is locked to
+  these four — `openalex`, `isbn`, and `s2_corpus` are reserved but not yet
+  implemented.
+- New module `_lumina/scripts/external-ids.mjs` and its Python mirror
+  `_lumina/tools/id_utils.py` provide pure helpers (`normalizeExternalId`,
+  `parseUrlToExternalIds`, `canonicalizeUrl`, `externalIdMatchKey`,
+  `expandExternalIds`, `safeIdToken`, `sanitizeExternalIdsObject`). Parity is
+  gated by a shared JSON fixture.
+- New CLI wrapper `_lumina/scripts/parse-ids.mjs` reads a URL from `argv` and
+  emits a validated `external_ids` JSON map. Skill prompts call this instead
+  of inline `node -e` interpolation, eliminating shell-injection risk.
+- Producers (`/lumi-ingest`, `/lumi-discover`, all fetchers) populate
+  `external_ids` automatically. `init_discovery.py --exclude-keys` filters
+  candidates by expanded external_ids set so a DOI excludes its arxiv form.
+- Three new lint checks on source pages: **L13** (warn — namespace coverage
+  derivable from `urls[]`), **L14** (error — invalid identifier value),
+  **L16** (warn — `urls[]` ↔ `external_ids` mismatch). L13's remediation
+  message points users at `/lumi-migrate-legacy --backfill-ids`.
+- Opt-in `/lumi-migrate-legacy --backfill-ids` flag populates `external_ids`
+  on legacy source pages from existing `urls[]`. Non-destructive (existing
+  keys win) and idempotent. No `--dry-run` — review with `git diff`.
+- Source pages gain an optional `sources` frontmatter array recording fetch
+  provenance: `[{provider, fetched_at, url?}]`. Each ingest run appends one
+  entry — multi-fetch keeps history rather than replacing.
+- New CLI wrapper `_lumina/scripts/build-source.mjs` (and the underlying
+  `buildSourceEntry` / `build_source_entry` helpers in `external-ids.mjs` /
+  `id_utils.py`) constructs one validated entry per fetcher run. Provider
+  must be a kebab/snake slug (max 32 chars). `/lumi-ingest` Phase 3 calls
+  it after writing `external_ids`.
+
+### Changed
+
+- `init_discovery.py` flag renamed in place: `--exclude-ids` →
+  `--exclude-keys`. No deprecation alias (LLM-driven, no human contract).
+- `wiki.mjs` `parseFrontmatter` / `stringifyFrontmatter` now round-trip
+  top-level YAML object values (block-mapping form). `set-meta external_ids`
+  runs `sanitizeExternalIdsObject` automatically — `__proto__` and unknown
+  namespaces are stripped before persisting.
+- `EXTERNAL_ID_NAMESPACES` source of truth moved from `external-ids.mjs` to
+  `schemas.mjs` (where pure-data lives). `external-ids.mjs` now imports and
+  re-exports it for back-compat with downstream consumers.
+
+### Migration
+
+- Legacy wikis with no `external_ids` populated will see L13 warnings on
+  source pages whose `urls[]` contain an arxiv/doi/s2 URL. Run
+  `/lumi-migrate-legacy --backfill-ids` to populate them. The standard
+  migration flow (`/lumi-migrate-legacy` without the flag) is unchanged.
+
 ## [1.1.0] - 2026-05-06
 
 ### Added

package/README.md

@@ -56,6 +56,10 @@ Lumina-Wiki works from one simple principle: keep your raw materials separate fr
 +-------------------------+                        +---------------------------+
 ```
 
+<p align="center">
+  <img src="assets/lumina-architecture-en.png" alt="Lumina-Wiki Architecture" width="720">
+</p>
+
 1.  **You Provide:** Place your documents (PDFs, notes) in the `raw/` directory.
 2.  **The Agent Builds:** Use commands in your AI chat, such as `/lumi-ingest`, to make the agent read from `raw/` and build a structured, interlinked wiki in `wiki/`.
 3.  **You Query:** Ask questions with `/lumi-ask` against the agent's "brain" in `wiki/` for faster, more context-aware answers.
@@ -121,6 +125,10 @@ Interact with your wiki using these commands in your AI chat interface, such as
 
 Lumina creates a workspace where each folder has a clear purpose.
 
+<p align="center">
+  <img src="assets/lumina-env-en.png" alt="Lumina-Wiki Workspace Environment" width="720">
+</p>
+
 | Path | Purpose | Managed By |
 | :--- | :--- | :--- |
 | **`raw/`** | **Your immutable input library.** The agent **only reads** from here. | **You** |
@@ -152,6 +160,8 @@ As your wiki grows, you can use [qmd](https://github.com/tobi/qmd) for faster lo
 npx skills add https://github.com/tobi/qmd --skill qmd
 ```
 
+See the [Advanced Guide](docs/user-guide/advanced-qmd.en.md) for detailed installation and configuration.
+
 ---
 
 ## 5. Available Skills
@@ -184,24 +194,38 @@ The scripts behind these skills live in `_lumina/scripts/` and `_lumina/tools/`;
 
 ## 6. What's Coming Next
 
-The current release is **v0.2** (preview). The full plan is in [`ROADMAP.md`](./ROADMAP.md). Headline items:
+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)*
+- [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)*
 
-**v1.0.0 - First Stable**
-- **Scheduled discovery** - saved research topics can be checked on a schedule you choose.
-- New `/lumi-research-watchlist` skill to help you choose and update the topics to follow.
-- Stability lock for the v0.1 surface: CLI flags, exit codes, and schema field names.
-- Cross-platform CI matrix: macOS, Linux, and Windows on Node 20 and 22.
+**Long-term (Deep Research & Integration)**
+- [ ] **Global Source Expansion:** Direct integration with OpenAlex, CORE, and Unpaywall.
+- [ ] **RSS & Blog Monitoring:** Automatically identify new papers from your favorite lab blogs.
+- [ ] **Google Workspace:** Ingest Google Docs and Sheets directly into your graph.
+- [ ] **Multimedia Support:** Process YouTube videos and Audio recordings via transcripts.
+- [ ] **Knowledge Graph Auditing:** Automated checks for contradictions and structural drift.
 
-**v2.0.0 - Research Pack Source Expansion**
-- **New paper sources:** OpenAlex, Unpaywall, CORE (Priority 1) -> OpenReview, Hugging Face Papers, Papers With Code (Priority 2) -> Crossref, DOAJ, research lab RSS feeds (Priority 3).
-- **Paper ranking:** new `/lumi-rank` skill adding influential-citation count, field-normalized citation rank, Scite support/contrast signals, and Altmetric attention to a `ranking:` frontmatter block.
+**Proposed**
+- [ ] **Desktop Application:** A dedicated visual environment for easier wiki management.
+- [ ] **Specialized Science Packs:** Deep integration for bio-medical and physics researchers.
 
-**Want to contribute?** Pick any unchecked item in `ROADMAP.md`, open an issue to claim it, then send a PR. Source fetchers follow the same pattern in `src/tools/` (CLI + JSON, no async, exit codes `0/2/3`), so they are a good first contribution. See the local development steps below.
+---
+*Full technical details are available in [`ROADMAP.md`](./ROADMAP.md). Want to contribute? Join us on GitHub!*
 
 ---
 
 ## 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

@@ -56,6 +56,10 @@ Lumina-Wiki hoạt động dựa trên một nguyên tắc đơn giản: tách b
 +-------------------------+                        +---------------------------+
 ```
 
+<p align="center">
+  <img src="assets/lumina-architecture-vi.png" alt="Kiến trúc Lumina-Wiki" width="720">
+</p>
+
 1.  **Bạn Cung cấp:** Đặt các tài liệu (PDF, ghi chú) của bạn vào thư mục `raw/`.
 2.  **Agent Xây dựng:** Sử dụng các lệnh trong cuộc hội thoại với AI (như `/lumi-ingest`) để yêu cầu agent đọc từ `raw/` và xây dựng một wiki có cấu trúc, liên kết chặt chẽ trong thư mục `wiki/`.
 3.  **Bạn Khai thác:** Đặt câu hỏi (sử dụng `/lumi-ask`) trực tiếp vào "bộ não" của agent trong `wiki/` để nhận được câu trả lời nhanh và phù hợp với ngữ cảnh hơn.
@@ -121,6 +125,10 @@ Tương tác với wiki của bạn bằng cách sử dụng các lệnh này tr
 
 Lumina tạo ra một không gian làm việc với mục đích rõ ràng cho từng thư mục.
 
+<p align="center">
+  <img src="assets/lumina-env-vi.png" alt="Môi trường làm việc Lumina-Wiki" width="720">
+</p>
+
 | Đường dẫn | Mục đích | Quản lý bởi |
 | :--- | :--- | :--- |
 | **`raw/`** | **Thư viện đầu vào bất biến của bạn.** Agent **chỉ đọc** từ đây. | **Bạn** |
@@ -152,6 +160,8 @@ Khi wiki lớn dần, bạn có thể dùng [qmd](https://github.com/tobi/qmd)
 npx skills add https://github.com/tobi/qmd --skill qmd
 ```
 
+Xem [Hướng dẫn Nâng cao](docs/user-guide/advanced-qmd.vi.md) để biết chi tiết cài đặt và cấu hình.
+
 ---
 
 ## 5. Các kỹ năng có sẵn
@@ -184,24 +194,38 @@ Các script chạy nền nằm trong `_lumina/scripts/` và `_lumina/tools/`; th
 
 ## 6. Lộ trình sắp tới
 
-Phiên bản hiện tại là **v0.2** (preview). Kế hoạch đầy đủ ở [`ROADMAP.md`](./ROADMAP.md). Những hạng mục chính:
+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] **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)*
+- [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)*
 
-**v1.0.0 — Bản ổn định đầu tiên**
-- **Tìm tài liệu định kỳ** — các chủ đề nghiên cứu đã lưu có thể được kiểm tra lại theo lịch bạn chọn.
-- Skill mới `/lumi-research-watchlist` để giúp bạn chọn và cập nhật các chủ đề muốn theo dõi.
-- Khoá ổn định bề mặt v0.1 (CLI flags, exit codes, tên trường schema).
-- CI matrix đa nền tảng (macOS + Linux + Windows, Node 20 + 22).
+**Dài hạn (Nghiên cứu sâu & Tích hợp)**
+- [ ] **Mở rộng nguồn dữ liệu toàn cầu:** Tích hợp trực tiếp với OpenAlex, CORE và Unpaywall.
+- [ ] **Theo dõi RSS & Blog:** Tự động tìm bài báo mới từ các blog phòng thí nghiệm yêu thích.
+- [ ] **Google Workspace:** Nạp trực tiếp Google Docs và Sheets vào đồ thị tri thức.
+- [ ] **Hỗ trợ đa phương tiện:** Xử lý video YouTube và ghi âm Audio thông qua transcript.
+- [ ] **Kiểm định đồ thị tri thức:** Tự động phát hiện mâu thuẫn và sai lệch cấu trúc.
 
-**v2.0.0 — Mở rộng nguồn bài báo nghiên cứu cho Research Pack**
-- **Nguồn bài báo mới:** OpenAlex, Unpaywall, CORE (Ưu tiên 1) → OpenReview, Hugging Face Papers, Papers With Code (Ưu tiên 2) → Crossref, DOAJ, RSS từ các blog research lab (Ưu tiên 3).
-- **Đánh giá bài báo:** skill mới `/lumi-rank` đưa các chỉ số influential-citation count, xếp hạng theo lĩnh vực, Scite support/contrast, và Altmetric vào block `ranking:` trong frontmatter.
+**Dự kiến**
+- [ ] **Ứng dụng Desktop:** Môi trường giao diện chuyên dụng để quản lý wiki dễ dàng hơn.
+- [ ] **Gói Khoa học Chuyên dụng:** Tích hợp sâu cho các nhà nghiên cứu sinh học, y tế và vật lý.
 
-**Muốn đóng góp?** Chọn bất kỳ hạng mục chưa tick trong `ROADMAP.md`, mở issue để nhận, rồi gửi PR. Các fetcher nguồn bài báo đều tuân theo cùng pattern trong `src/tools/` (CLI + JSON, no async, exit codes `0/2/3`) nên rất phù hợp cho lần contribute đầu tiên. Xem hướng dẫn dev cục bộ bên dưới.
+---
+*Chi tiết kỹ thuật đầy đủ có tại [`ROADMAP.md`](./ROADMAP.md). Bạn muốn đóng góp? Hãy tham gia cùng chúng tôi trên GitHub!*
 
 ---
 
 ## 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

@@ -56,6 +56,10 @@ Lumina-Wiki 遵循一个简单原则：将您的原始资料与 AI 的结构化
 +-------------------------+                        +---------------------------+
 ```
 
+<p align="center">
+  <img src="assets/lumina-architecture-en.png" alt="Lumina-Wiki 架构" width="720">
+</p>
+
 1.  **您提供：** 将文档（PDF、笔记）放入 `raw/` 目录。
 2.  **Agent 构建：** 在 AI 对话中使用指令（如 `/lumi-ingest`），让 Agent 从 `raw/` 读取内容，并在 `wiki/` 中构建结构化、互相关联的维基。
 3.  **您使用：** 通过 `/lumi-ask` 直接向 `wiki/` 中的 Agent“大脑”提问，获得更快、更贴合上下文的回答。
@@ -121,6 +125,10 @@ node _lumina/scripts/wiki.mjs migrate --add-defaults
 
 Lumina 会创建一个工作区，每个目录都有明确用途。
 
+<p align="center">
+  <img src="assets/lumina-env-en.png" alt="Lumina-Wiki 工作区环境" width="720">
+</p>
+
 | 路径 | 用途 | 管理方 |
 | :--- | :--- | :--- |
 | **`raw/`** | **您的不可变输入库。** Agent **只从这里读取**。 | **您** |
@@ -146,12 +154,15 @@ Lumina 会创建一个工作区，每个目录都有明确用途。
 
 ### **使用 qmd 进行本地搜索（高级，可选）**
 
-当 wiki 逐渐变大时，您可以使用 [qmd](https://github.com/tobi/qmd) 获得更快的本地 Markdown 搜索。如果您的 IDE 支持 skill 格式，可以通过以下命令安装官方 qmd skill：
+随着 Wiki 的增长，您可以使用 [qmd](https://github.com/tobi/qmd) 实现更快的本地 Markdown 搜索。如果您的 IDE 支持 Skill 格式，请安装官方 qmd skill：
 
 ```bash
 npx skills add https://github.com/tobi/qmd --skill qmd
 ```
 
+有关详细的安装和配置，请参阅[高级指南](docs/user-guide/advanced-qmd.zh.md)。
+
+
 ---
 
 ## 5. 可用技能
@@ -184,24 +195,39 @@ npx skills add https://github.com/tobi/qmd --skill qmd
 
 ## 6. 未来规划
 
-当前版本是 **v0.2**（预览版）。完整计划见 [`ROADMAP.md`](./ROADMAP.md)。主要项目：
+Lumina-Wiki 正在快速演进。这是我们的用户路线图：
+
+**近期计划（稳定性与新导入支持）**
+- [ ] **`/lumi-help` 技能：** 智能助手，帮您即时学习和使用 Lumina-Wiki。
+- [x] **多语言安装：** 安装时可选英文、越南文或中文作为主语言。*（v1.2 已发布）*
+- [x] **原生 DOCX、RTF 与 EPUB 导入：** 通过 research pack 将 Word、Rich Text 与 EPUB 电子书直接导入维基。*（v1.x 已发布）*
+- [ ] **图片 OCR 与扫描 PDF：** 将截图与扫描版 PDF 导入维基。
+- [ ] **高级论文排名：** 查看研究论文的影响力评分和质量信号。
+- [x] **改进的 CI/CD：** 正式支持 Bun 和 Node 22 环境。*（v1.2 已发布）*
+
+**长期计划（深度研究与集成）**
+- [ ] **全球数据源扩展：** 直接集成 OpenAlex、CORE 和 Unpaywall。
+- [ ] **RSS 与博客监控：** 自动从您喜爱的实验室博客中发现新论文。
+- [ ] **Google Workspace：** 直接将 Google Docs 和 Sheets 导入知识图谱。
+- [ ] **多媒体支持：** 通过转录处理 YouTube 视频和音频录音。
+- [ ] **知识图谱审计：** 自动检测矛盾和结构偏移。
 
-**v1.0.0 — 首个稳定版**
-- **定期查找新资料** — 已保存的研究主题可以按你选择的频率再次检查。
-- 新技能 `/lumi-research-watchlist`，帮助你选择和更新要跟踪的研究主题。
-- 锁定 v0.1 的稳定接口（CLI flags、退出码、schema 字段名）。
-- 跨平台 CI 矩阵（macOS + Linux + Windows，Node 20 + 22）。
+**计划中**
+- [ ] **桌面端应用：** 专用的图形界面环境，方便管理维基。
+- [ ] **专业科学包：** 为生物医学和物理研究人员提供深度集成。
 
-**v2.0.0 — 扩展 Research Pack 的论文来源**
-- **新论文来源：** OpenAlex、Unpaywall、CORE（优先级 1）→ OpenReview、Hugging Face Papers、Papers With Code（优先级 2）→ Crossref、DOAJ、研究实验室博客 RSS（优先级 3）。
-- **论文评估：** 新技能 `/lumi-rank`，将 influential-citation count、领域归一化排名、Scite support/contrast 和 Altmetric 添加到 frontmatter 的 `ranking:` 区块。
+---
+*完整的技术细节请见 [`ROADMAP.md`](./ROADMAP.md)。想要贡献？欢迎在 GitHub 上加入我们！*
 
-**想贡献？** 选择 `ROADMAP.md` 中任何未勾选的项目，开 issue 认领，然后提交 PR。所有论文来源 fetcher 都遵循 `src/tools/` 中相同模式（CLI + JSON、no async、退出码 `0/2/3`），很适合作为第一次贡献。请参考下面的本地开发步骤。
 
 ---
 
 ## 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)
@@ -95,7 +130,7 @@ Flags applicable to all commands:
   --packs <list>      install packs: core,research,reading
   --ide-targets <list>  target CLIs: claude_code,codex,gemini_cli,qwen,iflow,cursor,generic
                           codex covers all AGENTS.md-compatible CLIs
-                          (Codex, Amp, Crush, Goose, Auggie, OpenCode, etc.)
+                          (OpenAI CodexApp (ChatGPT), Amp, Crush, Goose, Auggie, OpenCode, etc.)
 
 Examples:
   npx lumina-wiki install
@@ -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
 // ---------------------------------------------------------------------------
@@ -140,6 +182,8 @@ program
   .addOption(new Option('--project-name <name>', 'override auto-derived project name').hideHelp())
   .option('--communication-language <language>', 'language agents use when talking to the user')
   .option('--document-output-language <language>', 'language used for wiki documents')
+  .option('--lang <code>', 'installer UI locale: en, vi, zh')
+  .option('--force-locale-switch', 'allow switching installer locale during upgrade')
   .action(async (cmdOpts) => {
     const globalOpts = program.opts();
     const mergedDir      = cmdOpts.directory ?? cmdOpts.cwd ?? globalOpts.directory ?? globalOpts.cwd ?? process.cwd();
@@ -161,13 +205,15 @@ program
         projectName: cmdOpts.projectName,
         communicationLang: cmdOpts.communicationLanguage,
         documentOutputLang: cmdOpts.documentOutputLanguage,
+        lang: cmdOpts.lang,
+        forceLocaleSwitch: Boolean(cmdOpts.forceLocaleSwitch),
       });
     } catch (err) {
-      const isPermError  = err.code === 'EACCES' || err.code === 'EPERM';
-      const isRangeError = err instanceof RangeError;
+      // Top-level catch: locale may not be resolved yet (pre-loadLocale path).
+      // Error strings kept as EN literals — machine-readable, intentionally exempt.
       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));
     }
   });
 
@@ -194,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));
     }
   });
 
@@ -229,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.1.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",
@@ -35,6 +35,8 @@
     "src/installer/banner.js",
     "src/installer/commands.js",
     "src/installer/fs.js",
+    "src/installer/locales.js",
+    "src/installer/locales/*.mjs",
     "src/installer/manifest.js",
     "src/installer/prompts.js",
     "src/installer/template-engine.js",
@@ -45,8 +47,13 @@
     "src/scripts/reset.mjs",
     "src/scripts/schemas.mjs",
     "src/scripts/discover-runner.mjs",
+    "src/scripts/external-ids.mjs",
+    "src/scripts/parse-ids.mjs",
+    "src/scripts/merge-ids.mjs",
+    "src/scripts/build-source.mjs",
     "src/scripts/lib/*.mjs",
     "src/skills/**/*.md",
+    "src/tools/_cache.py",
     "src/tools/_env.py",
     "src/tools/extract_pdf.py",
     "src/tools/discover.py",
@@ -57,6 +64,7 @@
     "src/tools/fetch_wikipedia.py",
     "src/tools/fetch_s2.py",
     "src/tools/fetch_deepxiv.py",
+    "src/tools/id_utils.py",
     "src/tools/requirements.txt",
     "CHANGELOG.md",
     "README.md",
@@ -75,15 +83,16 @@
   "devDependencies": {},
   "scripts": {
     "test": "npm run test:installer",
-    "test:installer": "node --test src/installer/commands.test.js src/installer/fs.test.js src/installer/manifest.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",
-    "test:python": "python3 -m pytest src/tools/tests -q",
+    "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": "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",
     "test:template": "node --test src/installer/template-engine.test.js",
     "test:update": "node --test src/installer/update-check.test.js",
     "ci:idempotency": "node scripts/ci-idempotency.mjs",
+    "ci:cold-start": "node scripts/measure-cold-start.mjs",
     "ci:package": "node scripts/ci-package.mjs",
     "pack:check": "npm run ci:package",
     "dev:install": "node bin/lumina.js install",

package/src/installer/banner.js

@@ -7,6 +7,9 @@
  * subshells. Respects NO_COLOR by emitting plain text.
  *
  * Narrow terminals (<80 cols) get a compact fallback so lines do not wrap.
+ *
+ * Banner runs before locale selection; literal EN by design.
+ * ASCII art is locale-agnostic; only tagline+footer use hardcoded EN strings.
  */
 
 const NO_COLOR = Boolean(process.env.NO_COLOR);