lumina-wiki 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -3,6 +3,60 @@
 All notable changes to Lumina-Wiki are documented here.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [1.5.0] - 2026-05-10
+
+### Added — Learning Pack: `/lumi-learning-reflect` self-reflection skill (PRs #16, #17)
+
+- New optional **learning** pack installable via `npx lumina-wiki install --packs core,learning`.
+- New skill `/lumi-learning-reflect`: guides metacognitive self-reflection sessions on any concept or source in the wiki.
+  - Creates or updates `wiki/reflections/<slug>.md` — a personal reflection page with a rewritable **"Current understanding"** section and an append-only **"Evolution"** log.
+  - AI acts as a metacognitive mirror: reads past entries, quotes the user's own words, and asks prompting questions — but **never writes reflection content**. The user always authors their own understanding.
+  - Reflection pages are a personal overlay exempt from bidirectional-link requirements (`reflections/**` added to exempt globs in `schemas.mjs`).
+- `schemas.mjs` gains the `reflections` entity type (7 required frontmatter fields: `id`, `title`, `type`, `created`, `updated`, `related_concepts`, `related_sources`, `evolution_count`) scoped to the learning pack.
+- `commands.js` registers the learning pack as a valid selectable option (`VALID_PACKS`), creates `wiki/reflections/` on install, and wires up the `/lumi-learning-reflect` skill symlink.
+- Template READMEs (EN/VI/ZH) and `lumi-help.csv` catalog updated to include the new skill and Learning Pack install option.
+- `cross-reference-packs.md` and `page-templates.md` schema docs extended with reflection page format.
+- PR #17 follow-up: locale strings (EN/VI/ZH) for the new pack prompt, `prompts.js` pack description, and `assert.rejects` CI fix.
+
+## [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)
@@ -344,7 +398,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

@@ -78,7 +78,7 @@ npx lumina-wiki install
 
 > **Note for Windows users:** For the best experience, enable [Developer Mode](https://learn.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development) so the installer can use symlinks correctly. If Developer Mode is off, the installer falls back to copying skill files; everything still works, but updates are less ideal.
 
-The installer will guide you through a quick setup, including optional **Packs** such as `research` and `reading`.
+The installer will guide you through a quick setup, including optional **Packs** such as `research`, `reading`, and `learning`.
 
 ### **Step 2 (Optional): Configure the Research Pack**
 
@@ -117,7 +117,7 @@ Interact with your wiki using these commands in your AI chat interface, such as
 -   `/lumi-edit [path/to/wiki/page]`: Request a change or correction to a specific wiki page.
 -   `/lumi-check`: Check the whole wiki for errors, such as broken links or orphan pages.
 
-*Additional skills may be available if you installed optional packs such as `research` or `reading`.*
+*Additional skills may be available if you installed optional packs such as `research`, `reading`, or `learning`.*
 
 ---
 
@@ -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. |
@@ -187,6 +188,7 @@ These are the commands you can use when chatting with your AI agent.
 | | `/lumi-reading-character-track` | Track characters and their relationships in a story. |
 | | `/lumi-reading-theme-map` | Identify and map themes in a narrative. |
 | | `/lumi-reading-plot-recap` | Provide a progressive plot recap. |
+| **Learning** | `/lumi-learning-reflect` | Guide a self-reflection session on a concept or source you have studied. Creates a personal reflection page in `wiki/reflections/` with a rewritable "Current understanding" section and an append-only "Evolution" log. The AI acts as a metacognitive mirror — it quotes your past words and asks questions — but never writes the reflection for you. |
 
 The scripts behind these skills live in `_lumina/scripts/` and `_lumina/tools/`; you usually do not need to call them directly.
 
@@ -197,16 +199,18 @@ 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. *(shipped in v1.4)*
+- [x] **Learning Pack:** Self-reflection sessions that track how your understanding of a concept evolves over time. *(shipped in v1.4)*
 - [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)*
+- [ ] **Global Source Expansion:** Direct integration with OpenAlex, CORE, and Unpaywall for reliable DOI-to-PDF resolution.
+- [ ] **RSS & Blog Monitoring:** Automatically surface new papers from your favorite lab blogs and journals.
+- [ ] **Advanced Paper Ranking:** See influence scores and quality signals for your research papers.
 
 **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.
+- [ ] **Image OCR & Scanned PDFs:** Ingest screenshots and scanned PDFs into your wiki.
+- [ ] **Paper Version Tracking:** Get notified when an already-ingested paper has a new revision or published version.
 - [ ] **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.

package/README.vi.md

@@ -78,7 +78,7 @@ npx lumina-wiki install
 
 > **Lưu ý cho người dùng Windows:** Để có trải nghiệm tốt nhất, bạn nên [bật Chế độ nhà phát triển (Developer Mode)](https://learn.microsoft.com/vi-vn/windows/apps/get-started/enable-your-device-for-development) để trình cài đặt có thể sử dụng symlink một cách chính xác. Nếu Developer Mode bị tắt, trình cài đặt sẽ chuyển sang sao chép các file skill; chức năng vẫn hoạt động nhưng sẽ không lý tưởng bằng cho việc cập nhật.
 
-Trình cài đặt sẽ hướng dẫn bạn qua một vài bước thiết lập nhanh, bao gồm cả việc lựa chọn các **Gói (Packs)** tùy chọn như `research` (nghiên cứu) và `reading` (đọc hiểu).
+Trình cài đặt sẽ hướng dẫn bạn qua một vài bước thiết lập nhanh, bao gồm cả việc lựa chọn các **Gói (Packs)** tùy chọn như `research` (nghiên cứu), `reading` (đọc hiểu) và `learning` (học tập).
 
 ### **Bước 2 (Tùy chọn): Cấu hình Gói Research**
 
@@ -117,7 +117,7 @@ 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
 -   `/lumi-edit [đường/dẫn/tới/trang/wiki]`: Yêu cầu thay đổi hoặc sửa lỗi cho một trang wiki cụ thể.
 -   `/lumi-check`: Kiểm tra toàn bộ wiki để tìm lỗi (liên kết hỏng, trang mồ côi, v.v.).
 
-*Các kỹ năng bổ sung có thể có sẵn nếu bạn đã cài đặt các gói tùy chọn như `research` hoặc `reading`.*
+*Các kỹ năng bổ sung có thể có sẵn nếu bạn đã cài đặt các gói tùy chọn như `research`, `reading` hoặc `learning`.*
 
 ---
 
@@ -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ó. |
@@ -187,6 +188,7 @@ Xem [Hướng dẫn Nâng cao](docs/user-guide/advanced-qmd.vi.md) để biết
 | | `/lumi-reading-character-track`| Theo dõi các nhân vật và mối quan hệ của họ trong truyện. |
 | | `/lumi-reading-theme-map` | Xác định và lập bản đồ các chủ đề trong một câu chuyện. |
 | | `/lumi-reading-plot-recap` | Cung cấp một bản tóm tắt tuần tự của cốt truyện. |
+| **Learning** | `/lumi-learning-reflect` | Hướng dẫn một buổi phản tư (self-reflection) về một khái niệm hoặc tài liệu bạn đã học. Tạo trang phản tư cá nhân trong `wiki/reflections/` với phần "Hiểu biết hiện tại" có thể chỉnh sửa và nhật ký "Quá trình phát triển" chỉ được ghi thêm (không xóa). AI đóng vai trò gương nhận thức — trích dẫn lại lời bạn và đặt câu hỏi — nhưng không bao giờ viết nội dung phản tư thay bạn. |
 
 Các script chạy nền nằm trong `_lumina/scripts/` và `_lumina/tools/`; thông thường bạn không cần gọi trực tiếp.
 
@@ -197,16 +199,18 @@ 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. *(đã phát hành trong v1.4)*
+- [x] **Gói Learning:** Các buổi phản tư cá nhân giúp bạn theo dõi sự tiến triển trong hiểu biết về một khái niệm theo thời gian. *(đã phát hành trong v1.4)*
 - [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)*
+- [ ] **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 để tra cứu DOI-to-PDF đáng tin cậy.
+- [ ] **Theo dõi RSS & Blog:** Tự động phát hiện bài báo mới từ các blog phòng thí nghiệm và tạp chí yêu thích.
+- [ ] **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.
 
 **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.
+- [ ] **OCR ảnh & PDF scan:** Nạp ảnh chụp màn hình và PDF dạng scan vào wiki.
+- [ ] **Theo dõi phiên bản bài báo:** Nhận thông báo khi một bài báo đã nạp có bản sửa đổi hoặc phiên bản xuất bản chính thức mới.
 - [ ] **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.

package/README.zh.md

@@ -78,7 +78,7 @@ npx lumina-wiki install
 
 > **Windows 用户注意：** 为了获得最佳体验，建议[启用开发者模式](https://learn.microsoft.com/zh-cn/windows/apps/get-started/enable-your-device-for-development)，以便安装程序正确使用符号链接。如果开发者模式关闭，安装程序会退回到复制 skill 文件；功能仍然可用，但对后续更新不如符号链接理想。
 
-安装程序会引导您完成几个快速设置步骤，包括选择可选的 **Packs**，例如 `research`（研究）和 `reading`（阅读）。
+安装程序会引导您完成几个快速设置步骤，包括选择可选的 **Packs**，例如 `research`（研究）、`reading`（阅读）和 `learning`（学习）。
 
 ### **第二步（可选）：配置 Research Pack**
 
@@ -117,7 +117,7 @@ node _lumina/scripts/wiki.mjs migrate --add-defaults
 -   `/lumi-edit [path/to/wiki/page]`: 要求修改或修正某个具体 wiki 页面。
 -   `/lumi-check`: 检查整个 wiki 的问题（断链、孤立页面等）。
 
-*如果您安装了 `research` 或 `reading` 等可选包，还会有额外技能可用。*
+*如果您安装了 `research`、`reading` 或 `learning` 等可选包，还会有额外技能可用。*
 
 ---
 
@@ -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` | 从现有知识创建综述/调研。 |
@@ -188,6 +189,7 @@ npx skills add https://github.com/tobi/qmd --skill qmd
 | | `/lumi-reading-character-track`| 追踪故事中的角色及其关系。 |
 | | `/lumi-reading-theme-map` | 识别并映射故事主题。 |
 | | `/lumi-reading-plot-recap` | 提供情节的顺序回顾。 |
+| **Learning** | `/lumi-learning-reflect` | 引导一次针对某个概念或资料的自我反思（self-reflection）。在 `wiki/reflections/` 中创建个人反思页，包含可改写的"当前理解"部分和只能追加的"演变日志"。AI 充当认知镜——引用你过去说的话并提问——但从不替你撰写反思内容。 |
 
 后台脚本位于 `_lumina/scripts/` 和 `_lumina/tools/`；通常您不需要直接调用它们。
 
@@ -198,16 +200,18 @@ 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 本身的工作原理。*（v1.4 已发布）*
+- [x] **学习包（Learning Pack）：** 自我反思功能，帮助您追踪对某个概念的理解随时间的演变。*（v1.4 已发布）*
 - [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，实现可靠的 DOI-to-PDF 解析。
+- [ ] **RSS 与博客监控：** 自动从您喜爱的实验室博客和期刊中发现新论文。
+- [ ] **高级论文排名：** 查看研究论文的影响力评分和质量信号。
 
 **长期计划（深度研究与集成）**
-- [ ] **全球数据源扩展：** 直接集成 OpenAlex、CORE 和 Unpaywall。
-- [ ] **RSS 与博客监控：** 自动从您喜爱的实验室博客中发现新论文。
+- [ ] **图片 OCR 与扫描 PDF：** 将截图与扫描版 PDF 导入维基。
+- [ ] **论文版本追踪：** 当已导入的论文出现新修订版或正式发表版本时发出通知。
 - [ ] **Google Workspace：** 直接将 Google Docs 和 Sheets 导入知识图谱。
 - [ ] **多媒体支持：** 通过转录处理 YouTube 视频和音频录音。
 - [ ] **知识图谱审计：** 自动检测矛盾和结构偏移。

package/bin/lumina.js

@@ -145,8 +145,21 @@ 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')

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "lumina-wiki",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Domain-agnostic, multi-IDE wiki scaffolder — Karpathy's LLM-Wiki vision, cross-platform and pack-based.",
   "keywords": [
     "llm-wiki",
@@ -84,9 +84,10 @@
   "scripts": {
     "test": "npm run test:installer",
     "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: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 src/scripts/schemas.test.mjs",
     "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 {
@@ -111,6 +112,7 @@ const CORE_WIKI_DIRS = [
 
 const RESEARCH_WIKI_DIRS = ['wiki/foundations', 'wiki/topics'];
 const READING_WIKI_DIRS  = ['wiki/chapters', 'wiki/characters', 'wiki/themes', 'wiki/plot'];
+const LEARNING_WIKI_DIRS = ['wiki/reflections'];
 
 const CORE_RAW_DIRS = ['raw/sources', 'raw/notes', 'raw/assets', 'raw/tmp', 'raw/download'];
 const RESEARCH_RAW_DIRS = ['raw/discovered'];
@@ -123,7 +125,7 @@ const LUMINA_DIRS = [
   '_lumina/_state',
 ];
 
-const VALID_PACKS = new Set(['core', 'research', 'reading']);
+const VALID_PACKS = new Set(['core', 'research', 'reading', 'learning']);
 const VALID_IDE_TARGETS = new Set(['claude_code', 'codex', 'cursor', 'gemini_cli', 'qwen', 'iflow', 'generic']);
 
 // ---------------------------------------------------------------------------
@@ -220,6 +222,7 @@ export async function installCommand(opts = {}) {
   const { projectName, researchPurpose, ideTargets, packs, communicationLang, documentOutputLang, locale } = answers;
   const hasResearch = packs.includes('research');
   const hasReading  = packs.includes('reading');
+  const hasLearning = packs.includes('learning');
 
   console.log('');
   if (isUpgrade) {
@@ -241,6 +244,9 @@ export async function installCommand(opts = {}) {
   if (hasReading) {
     dirsToCreate.push(...READING_WIKI_DIRS);
   }
+  if (hasLearning) {
+    dirsToCreate.push(...LEARNING_WIKI_DIRS);
+  }
 
   for (const dir of dirsToCreate) {
     await ensureDir(join(projectRoot, dir));
@@ -255,6 +261,7 @@ export async function installCommand(opts = {}) {
     pack_core:     true,
     pack_research: hasResearch,
     pack_reading:  hasReading,
+    pack_learning: hasLearning,
     created_at:    new Date().toISOString().slice(0, 10),
     schema_version: String(MANIFEST_SCHEMA_VERSION),
   };
@@ -338,6 +345,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) {
@@ -759,6 +770,7 @@ async function renderAndWriteConfig(projectRoot, templateVars, answers) {
       core:     true,
       research: answers.packs.includes('research'),
       reading:  answers.packs.includes('reading'),
+      learning: answers.packs.includes('learning'),
     },
     paths: {
       raw:     'raw',
@@ -774,7 +786,7 @@ async function renderAndWriteConfig(projectRoot, templateVars, answers) {
       log_prefix:   '## [{{date}}] {{skill}} | {{details}}',
       bidirectional_links: {
         mode: 'exempt-only',
-        exemptions: ['foundations/**', 'outputs/**', '*://*'],
+        exemptions: ['foundations/**', 'outputs/**', '*://*', ...(answers.packs.includes('learning') ? ['reflections/**'] : [])],
       },
       graph: {
         enabled: true,
@@ -1025,6 +1037,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' });
@@ -1057,6 +1070,15 @@ function getSkillDefs(packs) {
     }
   }
 
+  if (packs.includes('learning')) {
+    const learningSkills = [
+      { name: 'reflect', canonicalId: 'lumi-learning-reflect', displayName: '/lumi-learning-reflect' },
+    ];
+    for (const s of learningSkills) {
+      defs.push({ ...s, pack: 'learning', srcPackPath: 'packs/learning' });
+    }
+  }
+
   return defs;
 }
 
@@ -1086,7 +1108,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 +1237,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/locales/en.mjs

@@ -37,6 +37,8 @@ export default {
   'prompt.packs.option.research.hint':         'discover/survey/prefill/setup skills + source-fetcher tools',
   'prompt.packs.option.reading.label':         'Reading',
   'prompt.packs.option.reading.hint':          'chapter-ingest/character-track/theme-map/plot-recap skills',
+  'prompt.packs.option.learning.label':        'Learning',
+  'prompt.packs.option.learning.hint':         'self-reflection skills (reflect skill + wiki/reflections/)',
 
   // ── Language pair ──────────────────────────────────────────────────────────
   'prompt.communication_language.message':     'Communication language (how the LLM talks to you)',

package/src/installer/locales/vi.mjs

@@ -36,6 +36,8 @@ export default {
   'prompt.packs.option.research.hint':         'kỹ năng discover/survey/prefill/setup + công cụ lấy nguồn',
   'prompt.packs.option.reading.label':         'Reading',
   'prompt.packs.option.reading.hint':          'kỹ năng chapter-ingest/character-track/theme-map/plot-recap',
+  'prompt.packs.option.learning.label':        'Learning',
+  'prompt.packs.option.learning.hint':         'kỹ năng tự phản tư (reflect + wiki/reflections/)',
 
   // ── Language pair ──────────────────────────────────────────────────────────
   'prompt.communication_language.message':     'Ngôn ngữ giao tiếp (LLM trò chuyện với bạn)',

package/src/installer/locales/zh.mjs

@@ -42,6 +42,8 @@ export default {
   'prompt.packs.option.research.hint':         'discover/survey/prefill/setup 技能 + 来源抓取工具',
   'prompt.packs.option.reading.label':         'Reading',
   'prompt.packs.option.reading.hint':          'chapter-ingest/character-track/theme-map/plot-recap 技能',
+  'prompt.packs.option.learning.label':        'Learning',
+  'prompt.packs.option.learning.hint':         '自我反思技能 (reflect 技能 + wiki/reflections/)',
 
   // ── Language pair ──────────────────────────────────────────────────────────
   'prompt.communication_language.message':     '交流语言(LLM 与你对话使用的语言)',

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

@@ -241,6 +241,7 @@ export async function runInstallPrompts({ acceptDefaults = false, cwd = process.
     options: [
       { value: 'research', label: t ? t('prompt.packs.option.research.label') : 'Research', hint: t ? t('prompt.packs.option.research.hint') : 'discover/survey/prefill/setup skills + source-fetcher tools' },
       { value: 'reading',  label: t ? t('prompt.packs.option.reading.label') : 'Reading',   hint: t ? t('prompt.packs.option.reading.hint') : 'chapter-ingest/character-track/theme-map/plot-recap skills' },
+      { value: 'learning', label: t ? t('prompt.packs.option.learning.label') : 'Learning', hint: t ? t('prompt.packs.option.learning.hint') : 'self-reflection skills (reflect skill + wiki/reflections/)' },
     ],
     required: false,
   });

package/src/scripts/lint.mjs

@@ -1178,7 +1178,8 @@ async function runLint(projectRoot, opts) {
   allFindings.push(...checkL08(edges));
 
   if (indexContent !== undefined) {
-    allFindings.push(...checkL09(indexPath, indexContent, entityFiles));
+    const indexEntityFiles = entityFiles.filter(f => !f.startsWith('reflections/'));
+    allFindings.push(...checkL09(indexPath, indexContent, indexEntityFiles));
   }
 
   // L10: collect all foundation frontmatters in one pass, then check for alias conflicts.
@@ -1284,7 +1285,7 @@ async function applyFixes(findings, wikiRoot, edgesPath, indexPath, indexContent
   // Fix L09.
   const l09findings = findings.filter(f => f.id === 'L09-index-stale');
   if (l09findings.length > 0) {
-    const { newContent, preview } = fixL09(indexContent, entityFiles);
+    const { newContent, preview } = fixL09(indexContent, entityFiles.filter(f => !f.startsWith('reflections/')));
     if (newContent !== indexContent) {
       if (opts.dryRun) {
         for (const f of l09findings) { f.proposed_fix = preview; }

package/src/scripts/schemas.mjs

@@ -35,6 +35,7 @@ export const SCHEMA_VERSION = '0.1.0';
 export const EXEMPTION_GLOBS = [
   'foundations/**',
   'outputs/**',
+  'reflections/**',
   '*://*',
 ];
 
@@ -86,7 +87,7 @@ export const ENUMS = {
 // ---------------------------------------------------------------------------
 
 /**
- * @typedef {'core'|'research'|'reading'} Pack
+ * @typedef {'core'|'research'|'reading'|'learning'} Pack
  */
 
 /**
@@ -114,6 +115,9 @@ export const ENTITY_DIRS = {
   characters:  { dir: 'characters/',  pack: 'reading' },
   themes:      { dir: 'themes/',      pack: 'reading' },
   plot:        { dir: 'plot/',        pack: 'reading' },
+
+  // learning pack
+  reflections: { dir: 'reflections/', pack: 'learning' },
 };
 
 // ---------------------------------------------------------------------------
@@ -374,6 +378,18 @@ export const REQUIRED_FRONTMATTER = {
     { key: 'book',      type: 'string',   required: true,  pack: 'reading' },
     { key: 'up_to_chapter', type: 'number', required: true, pack: 'reading' },
   ],
+
+  // Learning pack: reflection page (personal overlay — exempt from bidi links)
+  reflections: [
+    { key: 'id',               type: 'string',   required: true,  pack: 'learning' },
+    { key: 'title',            type: 'string',   required: true,  pack: 'learning' },
+    { key: 'type',             type: 'string',   required: true,  pack: 'learning' },
+    { key: 'created',          type: 'iso-date', required: true,  pack: 'learning' },
+    { key: 'updated',          type: 'iso-date', required: true,  pack: 'learning' },
+    { key: 'related_concepts', type: 'array',    required: true,  pack: 'learning' },
+    { key: 'related_sources',  type: 'array',    required: true,  pack: 'learning' },
+    { key: 'evolution_count',  type: 'number',   required: true,  pack: 'learning' },
+  ],
 };
 
 // ---------------------------------------------------------------------------