lumina-wiki 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -3,6 +3,45 @@
 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)
@@ -344,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,7 +198,7 @@ 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)*
 - [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.

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,7 +198,7 @@ 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)*
 - [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.

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,7 +199,7 @@ 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 已发布）*
 - [x] **原生 DOCX、RTF 与 EPUB 导入：** 通过 research pack 将 Word、Rich Text 与 EPUB 电子书直接导入维基。*（v1.x 已发布）*
 - [ ] **图片 OCR 与扫描 PDF：** 将截图与扫描版 PDF 导入维基。

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.4.0",
   "description": "Domain-agnostic, multi-IDE wiki scaffolder — Karpathy's LLM-Wiki vision, cross-platform and pack-based.",
   "keywords": [
     "llm-wiki",
@@ -87,6 +87,7 @@
     "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: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/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}}