lumina-wiki 0.4.0 → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,139 @@
+# Changelog
+
+All notable changes to Lumina-Wiki are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [Unreleased]
+
+### Added
+- `/lumi-migrate-legacy` core skill — LLM-driven backfill of provenance/confidence
+- `CHANGELOG.md` shipped to `_lumina/CHANGELOG.md` for skill consumption
+- Post-upgrade installer banner with lint summary (errors/warnings) when version bumps
+- Manifest `schemaVersion` bump 1 → 2 with `legacyMigrationNeeded` flag
+
+### Migration
+- Upgrades from <0.6 set `legacyMigrationNeeded: true` in manifest. Run `/lumi-migrate-legacy` or `wiki.mjs migrate --add-defaults` to backfill `provenance` and `confidence` fields on existing sources/concepts.
+
+---
+
+## [0.6.0] - 2026-05-03
+
+### Added
+- Schema: `provenance` field (required enum: `replayable|partial|missing`) on source nodes
+- Schema: `confidence` field (optional float 0–1) on source and concept nodes
+- Lint check L11: warns when `confidence` is missing on sources/concepts
+- Lint `--summary` flag outputs stable JSON shape `{ by_check: { L01..L11 } }` for machine consumption
+- `wiki.mjs`: 8-hex `session_id` segment in log entries; `LUMINA_SESSION_ID` env override for multi-write correlation
+- Installer `migrateManifest` helper for forward-compatible `schemaVersion` upgrades (1→1 no-op today, ready for 1→2)
+- Skills: provenance/confidence rubric added to `/lumi-ingest`, `/lumi-discover`, `/lumi-prefill`
+- ROADMAP: v1.0 `/lumi-verify` pass planned (3 stages: grounding A wiki↔raw, drift B raw↔URL, external C wiki↔web)
+
+### Fixed
+- CI: enumerate test files explicitly; use `fileURLToPath` for CLI path resolution
+- CI: quote test globs for Windows; install `requests` for Python tests
+- CI: spawn `npm.cmd` via shell on Windows
+- Scripts: resolve `reset.mjs` and `wiki.mjs` paths with `fileURLToPath`
+- Tools: strip Windows-illegal characters from discovery source IDs
+- Docs: recommend `qmd` skill for local search across all README language files
+
+### Migration
+- Sources need `provenance` (required) added; concepts and sources may add `confidence` (optional).
+- Run `wiki.mjs migrate --add-defaults` for deterministic backfill (sets `provenance: missing`, omits `confidence`), or `/lumi-migrate-legacy` (v0.7+) for LLM-driven backfill.
+- `log.md` entries now include `session:<8hex>` segment — backward-compatible parser; no migration needed for existing log entries.
+- `lint --summary` JSON shape is stable from this version forward; scripts consuming raw lint output should migrate to `--summary`.
+
+---
+
+## [0.5.0] - 2026-05-03
+
+### Added
+- Foundation aliases in wiki: named aliases for foundation nodes enable cross-skill deduplication
+- `wiki.mjs resolve-alias` command for alias lookup
+- Research: `/lumi-prefill` handles Wikipedia disambiguation pages and title collisions gracefully
+- Research: `/lumi-discover` surfaces entry purpose field and deduplicates ingested papers; logs discovery phases
+
+### Fixed
+- `wiki.mjs resolve-alias` no-match error now unwrapped to correct stderr format
+
+### Changed
+- Policy: cross-model review framed around bundled infra, not bias — second-model review is user choice, not blocked
+
+### Migration
+- No schema changes. No migration needed.
+
+---
+
+## [0.4.0] - 2026-05-02
+
+### Added
+- GEMINI.md agent entry-point stub for Gemini IDE targets
+- README restructured into multi-language files; skill names updated throughout
+- Obsidian vault setup documented across all language READMEs; agent entry-point stubs excluded from vault
+- Contributor guide added (`docs/`)
+
+### Changed
+- Skill `canonicalId` values namespaced with pack prefix (e.g. `research:lumi-discover`)
+- Installer: BMAD-style directory prompt; `project_name` auto-derived from directory
+- Installer: broadened Codex target; added `qwen` and `iflow` CLI targets
+- Installer: yellow LUMINA WIKI banner shown on install
+
+### Migration
+- If referencing skill `canonicalId` values in custom tooling, update to pack-prefixed form (e.g. `lumi-discover` → `research:lumi-discover`). Skill filenames and slash-command names are unchanged.
+
+---
+
+## [0.3.0] - 2026-05-02
+
+### Added
+- `extract_pdf.py` shipped as core PDF extractor for all installs (no opt-in required)
+
+### Migration
+- No schema or API changes. No migration needed.
+
+---
+
+## [0.2.0] - 2026-05-02
+
+### Added
+- Full installer with pack system (`core`, `research`, `reading`)
+- CI matrix and package readiness checks (`ci:idempotency`, `ci:package`)
+- Agent context files: `CLAUDE.md`, `AGENTS.md`, dev guide, sandbox helper
+- `.gitignore` for `node_modules`, `__pycache__`, `.env`, editor files
+- Skills output flattened to `.agents/skills/lumi-*` layout
+- Installer: yellow LUMINA WIKI banner, 5-prompt flow, 3-file manifest
+- README: badges, language links, end-user docs
+- Tagline: "Where Knowledge Starts to Glow"
+- ROADMAP: v1 daily-fetch and v2 source/ranking expansion plans
+
+### Changed
+- `.agents/skills/` output renamed from nested layout to flat `lumi-*` prefix
+
+### Migration
+- Fresh install from v0.1: re-run `npx lumina-wiki install --yes`. Existing `raw/` and `wiki/` content is preserved.
+
+---
+
+## [0.1.0] - 2026-05-01
+
+### Added
+- Initial npm package scaffold
+- Core scripts: `wiki.mjs` (graph/frontmatter engine), `lint.mjs` (9 checks), `reset.mjs`, `schemas.mjs`
+- 14 skills locked: 6 core (`/lumi-init`, `/lumi-ingest`, `/lumi-ask`, `/lumi-edit`, `/lumi-check`, `/lumi-reset`), 4 research, 4 reading
+- Installer entry point `bin/lumina.js` (ESM, lazy imports, <300 ms cold start)
+- Atomic write discipline (`atomicWrite` with `fd.datasync()` + rename) throughout
+- `safePath()` path validation rejecting `..`, absolute paths, Windows drive letters
+- Bidirectional link enforcement; `raw/` read-only except `raw/tmp/` and `raw/discovered/`
+- PRD, architecture docs, and v0.1 quick-spec
+
+### Migration
+- First release. No prior version to migrate from.
+
+---
+
+[Unreleased]: https://github.com/tronghieu/lumina-wiki/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/tronghieu/lumina-wiki/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/tronghieu/lumina-wiki/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/tronghieu/lumina-wiki/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/tronghieu/lumina-wiki/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/tronghieu/lumina-wiki/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/tronghieu/lumina-wiki/releases/tag/v0.1.0

package/README.md

@@ -66,6 +66,37 @@ If you installed the `research` pack, some skills need API keys to search online
 
 The agent will guide you through an interactive setup to save your keys to a local `.env` file.
 
+### **Step 3 (Upgrades): Migrate Legacy Wiki Entries**
+
+If you are **re-installing Lumina-Wiki on a project that already has a `wiki/` from an earlier version**, run the installer the same way:
+
+```bash
+npx lumina-wiki install
+```
+
+The installer detects the version bump and updates scripts, schemas, and skills atomically. **Your wiki content (`wiki/`, `raw/`, `log.md`) is never modified by the installer.** When the installer finds frontmatter fields added by newer versions but missing on older entries, it prints a `[warn]` banner with the count and the next step.
+
+You then have two ways to backfill:
+
+**Option A — LLM-driven (recommended):** Open your AI chat and run:
+
+> **You:**
+> `/lumi-migrate-legacy`
+
+The skill reads `_lumina/CHANGELOG.md` to learn which fields each version added, runs `lint --json` to find affected entries, and infers per-entry values (e.g. `provenance: replayable | partial | missing`, `confidence: high | medium | low | unverified`) from `raw/` snapshots, citation edges, and entry metadata. Idempotent — safe to run multiple times.
+
+**Option B — Quick deterministic backfill:** From your terminal:
+
+```bash
+node _lumina/scripts/wiki.mjs migrate --add-defaults
+```
+
+This applies conservative defaults (`provenance: missing`, `confidence: unverified`) to every entry that lacks them. Lint goes green immediately, but values are placeholders — you can refine later with Option A or by editing entries by hand.
+
+You can combine: run Option B first for a clean lint, then Option A when you want higher-quality values. Both write atomically and leave a trail in `wiki/log.md`.
+
+For the full list of schema changes per version, see [`CHANGELOG.md`](CHANGELOG.md) or the local copy at `_lumina/CHANGELOG.md` after install.
+
 ## 3. Your First Commands (Core Skills)
 
 Interact with your wiki using these commands in your AI chat interface (Gemini CLI, Claude, etc.).
@@ -136,6 +167,27 @@ Lumina creates a workspace with a clear purpose for each directory.
 
 > The `wiki/graph/` folder contains `edges.jsonl` and `citations.jsonl` (machine-readable data files, not markdown). Excluding it keeps the graph view clean.
 
+### **Local Search with qmd (Optional)**
+
+As your wiki grows, you may want faster full-text search than `index.md` plus `grep` can offer. We recommend [qmd](https://github.com/tobi/qmd) — a local, on-device search engine for markdown files with hybrid BM25/vector search and LLM re-ranking. It pairs nicely with Lumina-Wiki and your AI agent.
+
+**How to wire it into your agent:**
+
+1. Install qmd following the instructions in its repo, then index the project root so it sees both `wiki/` and `raw/`.
+2. **CLI route** — your agent can call `qmd <query>` via `Bash`. Just mention in your prompts that the command is available.
+3. **MCP route (handy for Claude Code, Codex, Cursor)** — register qmd's MCP server in your IDE's MCP config. The agent picks it up as a native tool and can call it from `/lumi-ask` or any follow-up.
+4. Re-index after `/lumi-ingest` (manually or via a hook) so new pages become searchable.
+
+qmd sits alongside `index.md` and the wiki graph — a fast retrieval layer that feeds your agent better candidates before it reads pages in full.
+
+**Bonus — tobi's official qmd skill.** tobi also publishes a dedicated skill that teaches your agent how to use qmd effectively (when to pick `lex` vs `vec` vs `hyde`, how to write `intent` to disambiguate, lex syntax for phrases and exclusions). If your IDE supports the skill format, you can install it with:
+
+```bash
+npx skills add https://github.com/tobi/qmd --skill qmd
+```
+
+We recommend reading [the skill page on skills.sh](https://skills.sh/tobi/qmd/qmd) first to see exactly what it adds.
+
 ---
 
 ## 5. Available Skills and Tools (v0.1)

package/README.vi.md

@@ -64,6 +64,37 @@ Nếu bạn đã cài đặt gói `research`, một số kỹ năng sẽ cần A
 
 Agent sẽ hướng dẫn bạn qua một quy trình cài đặt tương tác để lưu các key của bạn vào file `.env` cục bộ.
 
+### **Bước 3 (Khi nâng cấp): Migrate các entry wiki cũ**
+
+Nếu bạn **cài lại Lumina-Wiki trên một dự án đã có sẵn `wiki/` từ phiên bản trước**, chạy installer như bình thường:
+
+```bash
+npx lumina-wiki install
+```
+
+Installer phát hiện version mới và cập nhật scripts, schemas, skills atomically. **Nội dung wiki của bạn (`wiki/`, `raw/`, `log.md`) không bị installer chỉnh sửa.** Khi installer thấy các trường frontmatter mới được thêm bởi version mới nhưng thiếu trên các entry cũ, nó sẽ in banner `[warn]` kèm số lượng và bước tiếp theo.
+
+Bạn có hai cách để backfill:
+
+**Cách A — LLM-driven (khuyến nghị):** Mở chat AI và chạy:
+
+> **Bạn:**
+> `/lumi-migrate-legacy`
+
+Skill đọc `_lumina/CHANGELOG.md` để biết phiên bản nào thêm trường gì, chạy `lint --json` để tìm entry bị ảnh hưởng, và infer giá trị cho từng entry (ví dụ: `provenance: replayable | partial | missing`, `confidence: high | medium | low | unverified`) dựa trên snapshot trong `raw/`, citation edges, và metadata. Idempotent — chạy lại nhiều lần vẫn an toàn.
+
+**Cách B — Backfill nhanh, deterministic:** Từ terminal:
+
+```bash
+node _lumina/scripts/wiki.mjs migrate --add-defaults
+```
+
+Lệnh này gán default bảo thủ (`provenance: missing`, `confidence: unverified`) cho mọi entry còn thiếu. Lint xanh ngay, nhưng giá trị chỉ là placeholder — bạn có thể tinh chỉnh sau bằng Cách A hoặc sửa tay.
+
+Có thể kết hợp: chạy Cách B trước để lint xanh, sau đó Cách A khi muốn giá trị chính xác hơn. Cả hai đều atomic và để lại trail trong `wiki/log.md`.
+
+Xem [`CHANGELOG.md`](CHANGELOG.md) hoặc bản local `_lumina/CHANGELOG.md` sau khi cài để biết toàn bộ thay đổi schema theo version.
+
 ## 3. Các lệnh đầu tiên của bạn (Kỹ năng cốt lõi)
 
 Tương tác với wiki của bạn bằng cách sử dụng các lệnh này trong giao diện trò chuyện với AI Agent (ví dụ: Gemini CLI, Claude, v.v.).
@@ -134,6 +165,27 @@ Lumina tạo ra một không gian làm việc với mục đích rõ ràng cho t
 
 > Thư mục `wiki/graph/` chứa `edges.jsonl` và `citations.jsonl` (dữ liệu máy đọc, không phải markdown). Exclude thư mục này giúp graph view không bị nhiễu.
 
+### **Tìm kiếm cục bộ với qmd (Tùy chọn)**
+
+Khi wiki của bạn lớn dần, bạn có thể muốn tìm kiếm full-text nhanh hơn so với `index.md` + `grep`. Chúng tôi gợi ý [qmd](https://github.com/tobi/qmd) — một search engine chạy hoàn toàn local trên file markdown, kết hợp BM25, vector search và LLM re-ranking. qmd phối hợp rất hợp với Lumina-Wiki và AI Agent của bạn.
+
+**Cách tích hợp với AI Agent:**
+
+1. Cài qmd theo hướng dẫn trong repo của nó, sau đó index thư mục gốc của project để qmd thấy cả `wiki/` lẫn `raw/`.
+2. **Qua CLI** — agent có thể gọi `qmd <query>` bằng `Bash`. Chỉ cần nhắc trong prompt rằng câu lệnh này đã sẵn sàng.
+3. **Qua MCP (rất tiện cho Claude Code, Codex, Cursor)** — đăng ký MCP server của qmd vào file cấu hình MCP của IDE. Agent sẽ nhận nó như một tool gốc và có thể gọi từ `/lumi-ask` hay câu hỏi tiếp theo.
+4. Re-index sau mỗi lần `/lumi-ingest` (thủ công hoặc qua hook) để các trang mới có thể tìm được.
+
+qmd đứng song song với `index.md` và wiki graph — một lớp truy xuất nhanh giúp agent có candidate tốt hơn trước khi đọc đầy đủ từng trang.
+
+**Tuỳ chọn thêm — skill chính thức của tobi cho qmd.** tobi cũng phát hành một skill chuyên dụng, dạy agent cách dùng qmd hiệu quả (khi nào chọn `lex` vs `vec` vs `hyde`, cách viết `intent` để khử nhập nhằng, cú pháp lex cho phrase và exclude). Nếu IDE của bạn hỗ trợ định dạng skill, bạn có thể cài bằng:
+
+```bash
+npx skills add https://github.com/tobi/qmd --skill qmd
+```
+
+Khuyến khích đọc [trang skill trên skills.sh](https://skills.sh/tobi/qmd/qmd) trước để xem chính xác skill này bổ sung những gì.
+
 ---
 
 ## 5. Các Kỹ năng và Công cụ có sẵn (v0.1)

package/README.zh.md

@@ -64,6 +64,37 @@ npx lumina-wiki install
 
 Agent 将引导您通过交互式设置将密钥保存到本地 `.env` 文件中。
 
+### **第三步（升级时）：迁移旧版 Wiki 条目**
+
+如果您**在已经有 `wiki/` 的旧项目上重新安装 Lumina-Wiki**，照常运行安装器：
+
+```bash
+npx lumina-wiki install
+```
+
+安装器检测到版本升级后会原子性地更新 scripts、schemas 和 skills。**您的 wiki 内容（`wiki/`、`raw/`、`log.md`）不会被安装器修改。** 当安装器发现新版本添加的 frontmatter 字段在旧条目中缺失时，会打印 `[warn]` 横幅，显示数量和下一步操作。
+
+您有两种方式进行回填：
+
+**方案 A — LLM 驱动（推荐）：** 打开 AI 聊天并运行：
+
+> **您：**
+> `/lumi-migrate-legacy`
+
+该技能读取 `_lumina/CHANGELOG.md` 了解每个版本添加了哪些字段，运行 `lint --json` 找出受影响的条目，并基于 `raw/` 快照、引用边和条目元数据为每个条目推断合适的值（例如 `provenance: replayable | partial | missing`，`confidence: high | medium | low | unverified`）。幂等 — 多次运行也是安全的。
+
+**方案 B — 快速确定性回填：** 从终端运行：
+
+```bash
+node _lumina/scripts/wiki.mjs migrate --add-defaults
+```
+
+此命令为所有缺失字段的条目设置保守的默认值（`provenance: missing`，`confidence: unverified`）。lint 立即变绿，但值只是占位符 — 您可以稍后通过方案 A 或手动编辑来优化。
+
+您可以组合使用：先运行方案 B 让 lint 变绿，需要更准确的值时再运行方案 A。两种方式都是原子写入并在 `wiki/log.md` 留下记录。
+
+完整的版本 schema 变更列表请见 [`CHANGELOG.md`](CHANGELOG.md) 或安装后的本地副本 `_lumina/CHANGELOG.md`。
+
 ## 3. 常用指令（核心技能 Core Skills）
 
 在您的 AI 聊天界面（Gemini CLI, Claude 等）中使用这些指令与维基进行交互。
@@ -134,6 +165,27 @@ Lumina 创建的工作区为每个目录都设定了明确的用途。
 
 > `wiki/graph/` 文件夹包含 `edges.jsonl` 和 `citations.jsonl`（机器可读数据文件，非 Markdown）。排除该文件夹可保持图谱视图整洁。
 
+### **使用 qmd 进行本地搜索（可选）**
+
+随着您的 Wiki 不断增长，您可能希望获得比 `index.md` + `grep` 更快的全文搜索体验。我们推荐 [qmd](https://github.com/tobi/qmd) —— 一个完全本地、设备上的 Markdown 搜索引擎，结合 BM25、向量搜索和 LLM 重排序。qmd 与 Lumina-Wiki 和您的 AI Agent 配合得非常顺畅。
+
+**如何与 AI Agent 集成：**
+
+1. 按照 qmd 仓库中的说明安装，然后对项目根目录建立索引，使 qmd 能同时看到 `wiki/` 和 `raw/`。
+2. **CLI 方式** — Agent 可以通过 `Bash` 调用 `qmd <query>`。只需在提示中提及该命令已可用。
+3. **MCP 方式（在 Claude Code、Codex、Cursor 中很方便）** — 在 IDE 的 MCP 配置中注册 qmd 的 MCP 服务器。Agent 会将其识别为原生工具，可以从 `/lumi-ask` 或后续提问中调用。
+4. 在每次 `/lumi-ingest` 后重新索引（手动或通过 hook），让新页面可被搜索到。
+
+qmd 与 `index.md` 和 wiki 图谱并行工作 —— 作为一个快速检索层，在 Agent 完整阅读页面之前为它提供更好的候选结果。
+
+**额外推荐 —— tobi 的官方 qmd skill。** tobi 还发布了一个专用 skill，教您的 Agent 如何高效使用 qmd（何时选择 `lex` vs `vec` vs `hyde`、如何编写 `intent` 进行消歧、lex 短语与排除项语法）。如果您的 IDE 支持 skill 格式，可以通过以下命令安装：
+
+```bash
+npx skills add https://github.com/tobi/qmd --skill qmd
+```
+
+建议先阅读 [skills.sh 上的 skill 页面](https://skills.sh/tobi/qmd/qmd)，了解它具体添加了什么。
+
 ---
 
 ## 5. 可用技能与工具 (v0.1)

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "lumina-wiki",
-  "version": "0.4.0",
+  "version": "0.7.0",
   "description": "Domain-agnostic, multi-IDE wiki scaffolder — Karpathy's LLM-Wiki vision, cross-platform and pack-based.",
   "keywords": [
     "llm-wiki",
@@ -55,6 +55,7 @@
     "src/tools/fetch_s2.py",
     "src/tools/fetch_deepxiv.py",
     "src/tools/requirements.txt",
+    "CHANGELOG.md",
     "README.md",
     "LICENSE"
   ],
@@ -71,8 +72,8 @@
   "devDependencies": {},
   "scripts": {
     "test": "npm run test:installer",
-    "test:installer": "node --test src/installer/*.test.js",
-    "test:scripts": "node --test src/scripts/*.test.mjs",
+    "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",
     "test:python": "python3 -m pytest src/tools/tests -q",
     "test:all": "npm run test:installer && npm run test:scripts && npm run test:python",
     "test:fs": "node --test src/installer/fs.test.js",

package/src/installer/commands.js

@@ -17,6 +17,7 @@
 import { readFile, writeFile, rename, unlink, rm, access, copyFile } from 'node:fs/promises';
 import { join, resolve, relative, dirname, basename } from 'node:path';
 import { constants as fsConstants } from 'node:fs';
+import { spawnSync } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 
@@ -31,6 +32,7 @@ import {
 import {
   readManifest,
   writeManifest,
+  migrateManifest,
   readSkillsManifest,
   writeSkillsManifest,
   readFilesManifest,
@@ -223,6 +225,9 @@ export async function installCommand(opts = {}) {
   // 8. Copy scripts
   await copyScripts(projectRoot);
 
+  // 8.5. Copy CHANGELOG.md so /lumi-migrate-legacy can read it offline
+  await copyChangelog(projectRoot);
+
   // 9. Copy skills
   const skillRows = await copySkills(projectRoot, packs);
 
@@ -259,7 +264,13 @@ export async function installCommand(opts = {}) {
 
   // 17. Write three state files atomically
   const now = new Date().toISOString();
+  // Run schema migrations on the existing manifest first so flags like
+  // legacyMigrationNeeded are preserved into the final write.
+  const migrated = existingManifest
+    ? migrateManifest(existingManifest, MANIFEST_SCHEMA_VERSION)
+    : {};
   const manifest = {
+    ...migrated,
     schemaVersion:    MANIFEST_SCHEMA_VERSION,
     packageVersion:   PKG.version,
     installedAt:      existingManifest?.installedAt ?? now,
@@ -280,6 +291,16 @@ export async function installCommand(opts = {}) {
   await writeSkillsManifest(projectRoot, skillRows);
   await writeFilesManifest(projectRoot, fileRows);
 
+  // 17.5. Post-upgrade: spawn lint --summary, print banner if findings exist
+  if (isUpgrade && existingManifest.packageVersion !== PKG.version) {
+    await printPostUpgradeBanner({
+      projectRoot,
+      fromVersion: existingManifest.packageVersion,
+      toVersion: PKG.version,
+      colors,
+    });
+  }
+
   // 18. Print summary
   console.log('');
   console.log(colors.green('[done] Lumina Wiki installed successfully.'));
@@ -395,6 +416,76 @@ export async function versionCommand(opts = {}) {
 // Internal helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * Run lint --summary in the project root and, if findings exist, print a
+ * post-upgrade banner to stderr.
+ *
+ * @param {object} opts
+ * @param {string}  opts.projectRoot
+ * @param {string}  opts.fromVersion
+ * @param {string}  opts.toVersion
+ * @param {object}  opts.colors
+ */
+export async function printPostUpgradeBanner({ projectRoot, fromVersion, toVersion, colors }) {
+  let summary;
+  try {
+    const lintScript = join(projectRoot, '_lumina', 'scripts', 'lint.mjs');
+    const result = spawnSync(
+      process.execPath,
+      [lintScript, '--summary'],
+      { cwd: projectRoot, encoding: 'utf8', timeout: 30000 },
+    );
+
+    // Exit codes: 0 = clean, 1 = findings. Anything else (crash / ENOENT) → skip.
+    if (result.error || (result.status !== 0 && result.status !== 1)) {
+      return;
+    }
+
+    try {
+      summary = JSON.parse(result.stdout.trim());
+    } catch {
+      return;
+    }
+  } catch {
+    return;
+  }
+
+  const { errors = 0, warnings = 0 } = summary;
+  if (errors === 0 && warnings === 0) {
+    return;
+  }
+
+  const banner = [
+    '',
+    colors.yellow(`[warn] Lumina upgraded v${fromVersion} -> v${toVersion} — schema gap detected:`),
+    colors.yellow(`       ${errors} error(s), ${warnings} warning(s) across legacy entries.`),
+    '',
+    '     Quick fix (deterministic):',
+    '       node _lumina/scripts/wiki.mjs migrate --add-defaults',
+    '',
+    '     Smart fix (LLM-driven, recommended):',
+    '       /lumi-migrate-legacy',
+    '',
+    '     Both are idempotent. See _lumina/CHANGELOG.md for details.',
+    '',
+  ].join('\n');
+
+  process.stderr.write(banner + '\n');
+
+  // Spawn-and-forget: append upgrade log entry (ignore failures, e.g., wiki/ missing)
+  try {
+    const wikiScript = join(projectRoot, '_lumina', 'scripts', 'wiki.mjs');
+    const logMsg = `upgrade v${fromVersion}->v${toVersion}: ${errors} errors, ${warnings} warnings — run /lumi-migrate-legacy`;
+    spawnSync(
+      process.execPath,
+      [wikiScript, 'log', 'installer', logMsg],
+      { cwd: projectRoot, encoding: 'utf8', timeout: 10000 },
+    );
+  } catch {
+    // Ignore: wiki/ may not exist for incomplete installs
+  }
+}
+
 async function readAnswersFromConfig(projectRoot, existingManifest) {
   // Try reading lumina.config.yaml for stored answers
   try {
@@ -690,6 +781,16 @@ async function copyScripts(projectRoot) {
   }
 }
 
+async function copyChangelog(projectRoot) {
+  const src = join(PACKAGE_ROOT, 'CHANGELOG.md');
+  const dest = join(projectRoot, '_lumina', 'CHANGELOG.md');
+  try {
+    await copyFile(src, dest);
+  } catch (_) {
+    // CHANGELOG may not exist in older snapshots; skip gracefully
+  }
+}
+
 async function copySkills(projectRoot, packs) {
   const skillRows = [];
   const skillDefs = getSkillDefs(packs);
@@ -735,12 +836,13 @@ function getSkillDefs(packs) {
 
   if (packs.includes('core')) {
     const coreSkills = [
-      { name: 'init',    canonicalId: 'lumi-init',    displayName: '/lumi-init' },
-      { name: 'ingest',  canonicalId: 'lumi-ingest',  displayName: '/lumi-ingest' },
-      { name: 'ask',     canonicalId: 'lumi-ask',     displayName: '/lumi-ask' },
-      { name: 'edit',    canonicalId: 'lumi-edit',    displayName: '/lumi-edit' },
-      { name: 'check',   canonicalId: 'lumi-check',   displayName: '/lumi-check' },
-      { name: 'reset',   canonicalId: 'lumi-reset',   displayName: '/lumi-reset' },
+      { name: 'init',            canonicalId: 'lumi-init',            displayName: '/lumi-init' },
+      { name: 'ingest',          canonicalId: 'lumi-ingest',          displayName: '/lumi-ingest' },
+      { name: 'ask',             canonicalId: 'lumi-ask',             displayName: '/lumi-ask' },
+      { name: 'edit',            canonicalId: 'lumi-edit',            displayName: '/lumi-edit' },
+      { name: 'check',           canonicalId: 'lumi-check',           displayName: '/lumi-check' },
+      { name: 'reset',           canonicalId: 'lumi-reset',           displayName: '/lumi-reset' },
+      { name: 'migrate-legacy',  canonicalId: 'lumi-migrate-legacy',  displayName: '/lumi-migrate-legacy' },
     ];
     for (const s of coreSkills) {
       defs.push({ ...s, pack: 'core', srcPackPath: 'core' });

package/src/installer/manifest.js

@@ -19,7 +19,7 @@ import { atomicWrite, ensureDir } from './fs.js';
 // Constants
 // ---------------------------------------------------------------------------
 
-export const MANIFEST_SCHEMA_VERSION = 1;
+export const MANIFEST_SCHEMA_VERSION = 2;
 
 export const SKILLS_CSV_HEADER = 'canonical_id,display_name,pack,source,relative_path,target_link_path,version';
 export const FILES_CSV_HEADER = 'relative_path,sha256,source_pack,installed_version';
@@ -274,6 +274,78 @@ export async function writeFilesManifest(projectRoot, rows) {
   await atomicWrite(csvPath, serializeCsv(rows, cols));
 }
 
+// ---------------------------------------------------------------------------
+// Manifest migration
+// ---------------------------------------------------------------------------
+
+/**
+ * Migration registry shape (for future entries):
+ *
+ * const MIGRATIONS = {
+ *   '1->2': (m) => ({ ...m, newField: 'default' }),
+ *   '2->3': (m) => { ... return updatedManifest; },
+ * };
+ *
+ * To add a migration from version N to N+1:
+ *   1. Bump MANIFEST_SCHEMA_VERSION to N+1.
+ *   2. Add `'N->N+1': (m) => { ...transform... }` to MIGRATIONS.
+ *   3. The loop below will apply it automatically.
+ */
+const MIGRATIONS = {
+  '1->2': (m) => ({ ...m, legacyMigrationNeeded: true }),
+};
+
+/**
+ * Migrate a manifest object to the target schema version.
+ *
+ * - If `manifest.schemaVersion === targetVersion` — no-op, returns manifest unchanged.
+ * - If `manifest.schemaVersion` is missing (legacy install) — sets it to 1 and returns.
+ * - If `manifest.schemaVersion > targetVersion` — throws (downgrade not supported, code 3).
+ * - If `manifest.schemaVersion < targetVersion` — applies registered migrations in order.
+ *
+ * @param {object} manifest      - Parsed manifest object (may lack schemaVersion).
+ * @param {number} targetVersion - The schema version to migrate to.
+ * @returns {object}             - The migrated manifest (new object if changed).
+ */
+export function migrateManifest(manifest, targetVersion) {
+  // Legacy install: schemaVersion was not recorded before this constant existed.
+  if (manifest.schemaVersion === undefined || manifest.schemaVersion === null) {
+    return { ...manifest, schemaVersion: 1 };
+  }
+
+  const current = manifest.schemaVersion;
+
+  if (current === targetVersion) {
+    return manifest;
+  }
+
+  if (current > targetVersion) {
+    const err = new Error(
+      `Manifest schemaVersion ${current} is newer than installer target ${targetVersion}. ` +
+      'Downgrade is not supported. Update lumina-wiki to the latest version.',
+    );
+    err.code = 3;
+    throw err;
+  }
+
+  // Apply migrations step-by-step (current → current+1 → … → targetVersion).
+  let m = manifest;
+  for (let v = current; v < targetVersion; v++) {
+    const key = `${v}->${v + 1}`;
+    const migrate = MIGRATIONS[key];
+    if (!migrate) {
+      const err = new Error(
+        `No migration found for schemaVersion ${key}. ` +
+        'This is an internal error — please file an issue.',
+      );
+      err.code = 3;
+      throw err;
+    }
+    m = { ...migrate(m), schemaVersion: v + 1 };
+  }
+  return m;
+}
+
 // ---------------------------------------------------------------------------
 // State file paths helper
 // ---------------------------------------------------------------------------

package/src/installer/template-engine.js

@@ -124,6 +124,8 @@ export function renderReadme(template, variables, purpose = '') {
     return [
       titleLine,
       '',
+      '## Project Purpose',
+      '',
       purposeText,
       '',
       '<!-- lumina:schema -->',
@@ -140,7 +142,7 @@ export function renderReadme(template, variables, purpose = '') {
   // Find end of title block (first non-empty, non-H1 line before marker)
   let insertIdx = schemaMarkerIdx;
   // Insert purpose region before schema marker
-  const purposeLines = ['', purposeText, ''];
+  const purposeLines = ['', '## Project Purpose', '', purposeText, ''];
   lines.splice(insertIdx, 0, ...purposeLines);
 
   return lines.join('\n');