lumina-wiki 1.6.0 → 1.6.2

package/CHANGELOG.md

@@ -5,6 +5,60 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
 
+## [1.6.2] - 2026-06-15
+
+### Fixed
+
+- Repaired stale Claude skill links during upgrades by validating their real
+  targets instead of trusting the previously recorded link strategy.
+- Made POSIX skill links relative so copied, moved, or renamed workspaces can
+  be upgraded without retaining links to their old absolute location.
+- Reconciled removed packs and IDE targets by deleting obsolete
+  installer-managed skills, tools, links, and unchanged generated stubs while
+  preserving modified or user-owned files.
+- Made `npx lumina-wiki install` detect and upgrade an enclosing workspace when
+  invoked from a nested directory, while explicit `--directory` and `--cwd`
+  targets remain exact.
+- Fixed interactive locale switching for existing and legacy workspaces,
+  including default-language cascading and confirmation binding to the final
+  resolved locale.
+- Made installation fail clearly when required Claude skill links cannot be
+  created instead of writing successful state for a partial install.
+
+## [1.6.1] - 2026-05-18
+
+### Fixed
+
+- Restored v1.6 research tool scripts to the npm package allowlist so
+  upgrades include OpenAlex, Unpaywall, CORE, RSS, and PDF resolution tools
+  (fixes #20).
+- Expanded the package-readiness check (`scripts/ci-package.mjs`) to require
+  every Python tool copied by the installer, preventing future research-pack
+  tarball omissions.
+
+### Changed
+
+- OpenAlex research tooling now authenticates via `OPENALEX_API_KEY` /
+  `api_key` query parameter instead of the deprecated `OPENALEX_MAILTO`
+  polite-pool flow. The new key enables OpenAlex's free daily API budget and
+  usage tracking. Existing users should rename `OPENALEX_MAILTO` to
+  `OPENALEX_API_KEY` in their local `.env` — the old variable is ignored.
+- `fetch_openalex.py` search `per_page` is now clamped to 100 (the OpenAlex
+  documented maximum) and explicit 401/403 handling surfaces a clear error
+  message when the key is rejected.
+
+### CI
+
+- Dropped Node 22 from the test matrix across all OSes due to an upstream
+  `node:test` IPC bug (`ERR_TEST_FAILURE` / structured-clone deserialization)
+  that surfaced intermittently on Windows, macOS, and Linux runners.
+- Cold-start budget gate now runs only on `ubuntu-latest`; Windows and macOS
+  hosted runners have filesystem latency that makes the 350 ms threshold
+  infeasible regardless of code changes.
+- `Node 20 / windows-latest` marked `continue-on-error: true` to surface a
+  remaining Windows-only `node:test` flake as a warning instead of blocking
+  the build (tracked in #23).
+
 ## [1.6.0] - 2026-05-15
 
 ### Added — Multi-provider PDF resolution + RSS / Atom feeds (research pack)

package/README.md

@@ -93,6 +93,8 @@ The agent will help you check the research tools and save keys to a local `.env`
 
 If you reinstall Lumina-Wiki on a project that already has a `wiki/` from an earlier version, just run `npx lumina-wiki install` again. The installer updates scripts, schemas, and skills; **your content in `wiki/`, `raw/`, and `log.md` is not modified**.
 
+You can run the command from the project root or one of its subfolders. If you remove a pack or AI tool from the setup, Lumina removes its old managed commands and unchanged setup files. Files you edited are kept with a warning. If the whole project was copied, moved, or renamed, Lumina repairs its managed links during the upgrade.
+
 If the installer warns that older entries are missing newer frontmatter fields, you have two ways to backfill them:
 
 - **Recommended:** open your AI chat and run `/lumi-migrate-legacy`.

package/README.vi.md

@@ -93,6 +93,8 @@ Agent sẽ hướng dẫn bạn kiểm tra công cụ nghiên cứu và lưu key
 
 Nếu bạn cài lại Lumina-Wiki trên một dự án đã có `wiki/` từ phiên bản trước, cứ chạy lại `npx lumina-wiki install`. Installer cập nhật scripts, schemas và skills; **nội dung của bạn trong `wiki/`, `raw/`, `log.md` không bị chỉnh sửa**.
 
+Bạn có thể chạy lệnh tại thư mục gốc hoặc một thư mục con của dự án. Nếu bỏ một gói hoặc công cụ AI khỏi thiết lập, Lumina sẽ dọn các lệnh cũ và những tệp thiết lập chưa được bạn sửa. Tệp đã chỉnh sửa được giữ lại kèm cảnh báo. Nếu toàn bộ dự án được sao chép, di chuyển hoặc đổi tên, Lumina sẽ sửa lại các liên kết do hệ thống quản lý khi nâng cấp.
+
 Nếu installer cảnh báo entry cũ thiếu frontmatter mới, có hai cách backfill:
 
 - **Khuyến nghị:** mở chat AI và chạy `/lumi-migrate-legacy`.

package/README.zh.md

@@ -93,6 +93,8 @@ Agent 会引导您检查研究工具，并在需要时把 key 保存到本地 `.
 
 如果您在已经有旧版 `wiki/` 的项目上重新安装 Lumina-Wiki，直接再次运行 `npx lumina-wiki install` 即可。安装器会更新 scripts、schemas 和 skills；**您在 `wiki/`、`raw/`、`log.md` 中的内容不会被修改**。
 
+您可以在项目根目录或其子目录中运行该命令。如果从设置中移除某个包或 AI 工具，Lumina 会清理旧命令和未经您修改的设置文件。您修改过的文件会保留，并显示警告。如果整个项目被复制、移动或重命名，Lumina 会在升级时修复由系统管理的链接。
+
 如果安装器提示旧条目缺少新的 frontmatter 字段，可以用两种方式回填：
 
 - **推荐：** 打开 AI 对话并运行 `/lumi-migrate-legacy`。

package/bin/lumina.js

@@ -199,6 +199,12 @@ program
   .option('--force-locale-switch', 'allow switching installer locale during upgrade')
   .action(async (cmdOpts) => {
     const globalOpts = program.opts();
+    const hasExplicitDirectory = (
+      cmdOpts.directory != null
+      || cmdOpts.cwd != null
+      || globalOpts.directory != null
+      || globalOpts.cwd != null
+    );
     const mergedDir      = cmdOpts.directory ?? cmdOpts.cwd ?? globalOpts.directory ?? globalOpts.cwd ?? process.cwd();
     const mergedYes      = cmdOpts.yes      ?? globalOpts.yes      ?? false;
     const mergedReLink   = cmdOpts.reLink   ?? globalOpts.reLink   ?? false;
@@ -220,6 +226,7 @@ program
         documentOutputLang: cmdOpts.documentOutputLanguage,
         lang: cmdOpts.lang,
         forceLocaleSwitch: Boolean(cmdOpts.forceLocaleSwitch),
+        searchParents: !hasExplicitDirectory,
       });
     } catch (err) {
       // Top-level catch: locale may not be resolved yet (pre-loadLocale path).

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "lumina-wiki",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "description": "Domain-agnostic, multi-IDE wiki scaffolder — Karpathy's LLM-Wiki vision, cross-platform and pack-based.",
   "keywords": [
     "llm-wiki",
@@ -64,6 +64,11 @@
     "src/tools/fetch_wikipedia.py",
     "src/tools/fetch_s2.py",
     "src/tools/fetch_deepxiv.py",
+    "src/tools/fetch_openalex.py",
+    "src/tools/fetch_unpaywall.py",
+    "src/tools/fetch_core.py",
+    "src/tools/resolve_pdf.py",
+    "src/tools/fetch_rss.py",
     "src/tools/id_utils.py",
     "src/tools/requirements.txt",
     "CHANGELOG.md",
@@ -83,7 +88,8 @@
   "devDependencies": {},
   "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:installer": "npm run test:installer:commands && node --test bin/lumina.flags.test.js bin/lumina.deprecations.test.js bin/lumina.cancel.test.js src/installer/fs.test.js src/installer/locales.test.js src/installer/manifest.test.js src/installer/prompts.test.js src/installer/readme-templates.test.js src/installer/template-engine.test.js src/installer/update-check.test.js",
+    "test:installer:commands": "node src/installer/commands.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 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",

package/src/installer/commands.js

@@ -127,6 +127,37 @@ const LUMINA_DIRS = [
 
 const VALID_PACKS = new Set(['core', 'research', 'reading', 'learning']);
 const VALID_IDE_TARGETS = new Set(['claude_code', 'codex', 'cursor', 'gemini_cli', 'qwen', 'iflow', 'generic']);
+const RESEARCH_TOOL_FILES = [
+  '_env.py', '_cache.py', 'discover.py', 'init_discovery.py', 'prepare_source.py',
+  'fetch_arxiv.py', 'fetch_wikipedia.py', 'fetch_s2.py', 'fetch_deepxiv.py',
+  'fetch_openalex.py', 'fetch_unpaywall.py', 'fetch_core.py', 'resolve_pdf.py',
+  'fetch_rss.py',
+];
+
+async function findEnclosingWorkspace(startDir) {
+  let current = resolve(startDir);
+  while (true) {
+    try {
+      await access(join(current, '_lumina', 'manifest.json'), fsConstants.F_OK);
+      return current;
+    } catch (err) {
+      if (err.code !== 'ENOENT' && err.code !== 'ENOTDIR') throw err;
+    }
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+async function readManifestForInstall(projectRoot) {
+  try {
+    return await readManifest(projectRoot);
+  } catch (err) {
+    const e = new Error(`MANIFEST_READ_FAILED: ${err.message} (path: ${projectRoot}/_lumina/manifest.json)`);
+    e.code = 2;
+    throw e;
+  }
+}
 
 // ---------------------------------------------------------------------------
 // install command
@@ -144,32 +175,24 @@ const VALID_IDE_TARGETS = new Set(['claude_code', 'codex', 'cursor', 'gemini_cli
  * @param {string} [opts.projectName]  - Hidden escape hatch; default = basename(directory)
  * @param {string} [opts.communicationLang]
  * @param {string} [opts.documentOutputLang]
+ * @param {boolean} [opts.searchParents] - Find an enclosing Lumina workspace when no directory flag was used
  */
 export async function installCommand(opts = {}) {
   const { yes = false, reLink = false } = opts;
   const initialDir = opts.directory ?? opts.cwd ?? process.cwd();
-  let projectRoot = resolve(initialDir);
+  const requestedRoot = resolve(initialDir);
+  let projectRoot = opts.searchParents
+    ? (await findEnclosingWorkspace(requestedRoot) ?? requestedRoot)
+    : requestedRoot;
   const colors = await getColorFns();
 
   // 1. Read existing manifest at the initial path (upgrade detection)
   // Distinguish ENOENT (fresh install) from real I/O errors. Real errors must
   // bail loud — silently treating them as "fresh install" would let a transient
   // permission failure quietly nuke an existing install.
-  let existingManifest = null;
-  try {
-    existingManifest = await readManifest(projectRoot);
-  } catch (err) {
-    if (err.code === 'ENOENT') {
-      existingManifest = null;
-    } else {
-      // Pre-loadLocale path — intentionally EN-only and machine-readable.
-      const e = new Error(`MANIFEST_READ_FAILED: ${err.message} (path: ${projectRoot}/_lumina/manifest.json)`);
-      e.code = 2;
-      throw e;
-    }
-  }
+  let existingManifest = await readManifestForInstall(projectRoot);
 
-  const isUpgrade = existingManifest !== null;
+  let isUpgrade = existingManifest !== null;
 
   // 2. Collect answers (locale not yet loaded; prompts use EN fallback literals)
   let answers;
@@ -182,13 +205,27 @@ export async function installCommand(opts = {}) {
       cwd: projectRoot,
       existingManifest,
       defaultLocale: opts.lang ?? 'en',
+      resolveDestination: async (directory) => {
+        const manifest = await readManifestForInstall(directory);
+        if (!manifest) return null;
+        return {
+          existingManifest: manifest,
+          answers: await readAnswersFromConfig(directory, manifest),
+        };
+      },
     });
     // Re-resolve projectRoot from the directory the user typed.
     if (answers.directory) {
       projectRoot = resolve(answers.directory);
     }
+    existingManifest = await readManifestForInstall(projectRoot);
+    isUpgrade = existingManifest !== null;
   }
   answers = applyInstallOverrides(answers, opts);
+  const previousSkillRows = isUpgrade
+    ? previousManagedSkillRows(await readSkillsManifest(projectRoot), existingManifest)
+    : [];
+  const previousFileRows = isUpgrade ? await readFilesManifest(projectRoot) : [];
 
   // 2b. Load locale module ONCE after applyInstallOverrides resolves locale.
   const localeMod = await loadLocale(answers.locale ?? 'en');
@@ -209,7 +246,11 @@ export async function installCommand(opts = {}) {
         ?? migrateManifest(existingManifest, MANIFEST_SCHEMA_VERSION).locale
         ?? 'en'
     );
-    if (installedLocale !== answers.locale && !opts.forceLocaleSwitch) {
+    if (
+      installedLocale !== answers.locale
+      && !opts.forceLocaleSwitch
+      && answers.localeSwitchConfirmedFor !== answers.locale
+    ) {
       const e = new Error(
         `LOCALE_SWITCH_REFUSED: installed locale '${installedLocale}' differs from resolved locale '${answers.locale}'. ` +
         `Pass --force-locale-switch to confirm (this will rewrite README.md and IDE stubs in the new locale).`,
@@ -223,6 +264,9 @@ export async function installCommand(opts = {}) {
   const hasResearch = packs.includes('research');
   const hasReading  = packs.includes('reading');
   const hasLearning = packs.includes('learning');
+  const previousProjectRoot = existingManifest?.resolvedPaths?.projectRoot;
+  const relocated = Boolean(previousProjectRoot && resolve(previousProjectRoot) !== projectRoot);
+  const effectiveReLink = reLink || relocated;
 
   console.log('');
   if (isUpgrade) {
@@ -230,6 +274,9 @@ export async function installCommand(opts = {}) {
   } else {
     console.log(colors.bold(t('progress.installing', { dir: projectRoot })));
   }
+  if (relocated) {
+    console.log(colors.yellow(t('warn.relocated', { from: previousProjectRoot, to: projectRoot })));
+  }
 
   // 3. Scaffold directories
   const dirsToCreate = [
@@ -252,6 +299,20 @@ export async function installCommand(opts = {}) {
     await ensureDir(join(projectRoot, dir));
   }
 
+  await reconcileRemovedIdeTargets({
+    projectRoot,
+    previousIdeTargets: existingManifest?.ideTargets ?? [],
+    currentIdeTargets: ideTargets,
+    previousFileRows,
+    previousSkillRows,
+    colors,
+    t,
+  });
+
+  if (isUpgrade && existingManifest?.packs?.research && !hasResearch) {
+    await cleanupRemovedResearchPack(projectRoot, previousFileRows, colors, t);
+  }
+
   // 4. Template variables
   const templateVars = {
     project_name:             projectName,
@@ -282,7 +343,10 @@ export async function installCommand(opts = {}) {
   await copyChangelog(projectRoot);
 
   // 9. Copy skills
-  const skillRows = await copySkills(projectRoot, packs);
+  const skillRows = await copySkills(projectRoot, packs, {
+    claudeCode: ideTargets.includes('claude_code'),
+  });
+  await reconcileRemovedSkills(projectRoot, previousSkillRows, skillRows);
 
   // 10. Copy Python tools (core: extract_pdf; research pack: discovery/fetchers)
   await copyTools(projectRoot, { research: hasResearch });
@@ -307,10 +371,18 @@ export async function installCommand(opts = {}) {
   // 15. Create per-skill symlinks (.claude/skills/lumi-*) for Claude Code
   const symlinkStrategies = {};
   if (ideTargets.includes('claude_code')) {
-    const { strategies } = await createSkillSymlinks(
-      projectRoot, skillRows, existingManifest, reLink, colors, t
+    const { strategies, errors } = await createSkillSymlinks(
+      projectRoot, skillRows, existingManifest, effectiveReLink, colors, t
     );
     Object.assign(symlinkStrategies, strategies);
+    if (errors.length > 0) {
+      const e = new Error(
+        `SKILL_LINKS_INCOMPLETE: ${errors.length} of ${skillRows.length} Claude skill links failed: ` +
+        errors.map(item => `${item.skill}: ${item.error.message}`).join('; '),
+      );
+      e.code = 2;
+      throw e;
+    }
   }
 
   // 16. Build files-manifest rows
@@ -677,7 +749,9 @@ function applyInstallOverrides(answers, opts) {
   const next = { ...answers };
   const priorLocale = answers.locale ?? null;
 
-  // Locale: --lang flag overrides; case-insensitive normalize.
+  // Locale: --lang overrides the interactive selector. Keep the installed
+  // locale in answers.locale until this point so default language values can
+  // cascade correctly when an existing destination is selected.
   // Pre-loadLocale error → EN-only string (chicken-and-egg, machine-readable).
   if (opts.lang !== undefined && opts.lang !== null && opts.lang !== '') {
     const normalized = String(opts.lang).toLowerCase().trim();
@@ -687,9 +761,12 @@ function applyInstallOverrides(answers, opts) {
       throw e;
     }
     next.locale = normalized;
+  } else if (next.selectedLocale) {
+    next.locale = next.selectedLocale;
   } else if (!next.locale) {
     next.locale = 'en';
   }
+  delete next.selectedLocale;
 
   // Cascade: if --lang changed locale and user didn't explicitly pass language
   // overrides, refresh the language defaults to match the new locale.
@@ -929,6 +1006,113 @@ function ideTargetStubFiles(ideTargets) {
     .filter(Boolean);
 }
 
+async function removeManagedFileIfUnchanged(projectRoot, relPath, previousFileRows, colors, t) {
+  const absPath = safePath(projectRoot, relPath);
+  try {
+    await access(absPath, fsConstants.F_OK);
+  } catch (err) {
+    if (err.code === 'ENOENT') return;
+    throw err;
+  }
+
+  const previous = previousFileRows.find(row => row.relative_path === relPath);
+  if (previous?.sha256) {
+    try {
+      if (await fileHash(absPath) === previous.sha256) {
+        await unlink(absPath);
+        return;
+      }
+    } catch (_) {}
+  }
+
+  console.log(colors.yellow(t('warn.preserved_modified_file', { path: relPath })));
+}
+
+function previousManagedSkillRows(previousSkillRows, existingManifest) {
+  const rowsById = new Map(previousSkillRows.map(row => [row.canonical_id, row]));
+  const previousStrategies = existingManifest?.symlinkStrategies ?? {};
+  const claudeWasSelected = existingManifest?.ideTargets?.includes('claude_code') ?? false;
+  const previousPacks = Object.keys(existingManifest?.packs ?? {});
+  for (const skill of getSkillDefs(previousPacks)) {
+    if (!rowsById.has(skill.canonicalId)) {
+      rowsById.set(skill.canonicalId, {
+        canonical_id: skill.canonicalId,
+        relative_path: join('.agents', 'skills', skill.canonicalId),
+        target_link_path: existingManifest?.ideTargets?.includes('claude_code')
+          ? join('.claude', 'skills', skill.canonicalId)
+          : '',
+      });
+    }
+  }
+  for (const canonicalId of Object.keys(previousStrategies)) {
+    if (!rowsById.has(canonicalId)) {
+      rowsById.set(canonicalId, {
+        canonical_id: canonicalId,
+        relative_path: join('.agents', 'skills', canonicalId),
+        target_link_path: join('.claude', 'skills', canonicalId),
+      });
+    }
+  }
+  return [...rowsById.values()].map(row => ({
+    ...row,
+    managed_link: claudeWasSelected
+      || Object.prototype.hasOwnProperty.call(previousStrategies, row.canonical_id),
+  }));
+}
+
+async function removeManagedSkillLink(projectRoot, skill) {
+  if (skill.managed_link === false) return;
+  const relPath = skill.target_link_path || join('.claude', 'skills', skill.canonical_id);
+  await rm(safePath(projectRoot, relPath), { recursive: true, force: true });
+}
+
+async function reconcileRemovedIdeTargets({
+  projectRoot,
+  previousIdeTargets,
+  currentIdeTargets,
+  previousFileRows,
+  previousSkillRows,
+  colors,
+  t,
+}) {
+  const removedTargets = previousIdeTargets.filter(target => !currentIdeTargets.includes(target));
+  for (const target of removedTargets) {
+    if (target === 'claude_code') {
+      await Promise.all(previousSkillRows.map(skill => removeManagedSkillLink(projectRoot, skill)));
+    }
+
+    const relPath = ideTargetStubFiles([target])[0];
+    if (relPath) {
+      await removeManagedFileIfUnchanged(projectRoot, relPath, previousFileRows, colors, t);
+    }
+  }
+}
+
+async function reconcileRemovedSkills(projectRoot, previousSkillRows, currentSkillRows) {
+  const currentIds = new Set(currentSkillRows.map(row => row.canonical_id));
+  const obsolete = previousSkillRows.filter(row => !currentIds.has(row.canonical_id));
+
+  for (const skill of obsolete) {
+    if (skill.relative_path) {
+      await rm(safePath(projectRoot, skill.relative_path), { recursive: true, force: true });
+    }
+    await removeManagedSkillLink(projectRoot, skill);
+  }
+}
+
+async function cleanupRemovedResearchPack(projectRoot, previousFileRows, colors, t) {
+  await Promise.all(RESEARCH_TOOL_FILES.map(file => (
+    rm(safePath(projectRoot, join('_lumina', 'tools', file)), { force: true })
+  )));
+  await removeManagedFileIfUnchanged(
+    projectRoot,
+    '.env.example',
+    previousFileRows,
+    colors,
+    t,
+  );
+}
+
 function buildIdeStub(target, vars) {
   const name = vars.project_name || 'this wiki';
   switch (target) {
@@ -983,7 +1167,7 @@ async function copyChangelog(projectRoot) {
   }
 }
 
-async function copySkills(projectRoot, packs) {
+async function copySkills(projectRoot, packs, { claudeCode = false } = {}) {
   const skillRows = [];
   const skillDefs = getSkillDefs(packs);
 
@@ -1003,7 +1187,7 @@ async function copySkills(projectRoot, packs) {
       pack:            skill.pack,
       source:          'built-in',
       relative_path:   `.agents/skills/${skill.canonicalId}`,
-      target_link_path: join('.claude', 'skills', skill.canonicalId),
+      target_link_path: claudeCode ? join('.claude', 'skills', skill.canonicalId) : '',
       version:         PKG.version,
     });
   }
@@ -1085,13 +1269,7 @@ function getSkillDefs(packs) {
 async function copyTools(projectRoot, { research }) {
   const destDir = join(projectRoot, '_lumina', 'tools');
   const coreTools = ['extract_pdf.py', 'fetch_pdf.py', 'id_utils.py'];
-  const researchTools = [
-    '_env.py', '_cache.py', 'discover.py', 'init_discovery.py', 'prepare_source.py',
-    'fetch_arxiv.py', 'fetch_wikipedia.py', 'fetch_s2.py', 'fetch_deepxiv.py',
-    'fetch_openalex.py', 'fetch_unpaywall.py', 'fetch_core.py', 'resolve_pdf.py',
-    'fetch_rss.py',
-  ];
-  const toolFiles = research ? [...coreTools, ...researchTools] : coreTools;
+  const toolFiles = research ? [...coreTools, ...RESEARCH_TOOL_FILES] : coreTools;
   // Parallelize: each copy is independent and destDir already exists.
   // Sequential awaits were the main Windows cold-start regression in v1.4
   // (~30 ms per file × 14 files dominates on NTFS + Defender).
@@ -1140,6 +1318,8 @@ async function renderEnvExample(projectRoot) {
       `# Copy to .env and fill in your values. Never commit .env.\n\n` +
       `# Semantic Scholar API key (optional; improves rate limits)\n` +
       `SEMANTIC_SCHOLAR_API_KEY=\n\n` +
+      `# OpenAlex API key (optional; enables free daily API budget and usage tracking)\n` +
+      `OPENALEX_API_KEY=\n\n` +
       `# DeepXiv token (optional; enables full-text PDF access)\n` +
       `DEEPXIV_TOKEN=\n\n` +
       `# arXiv does not require an API key in v0.1\n`;
@@ -1211,6 +1391,7 @@ async function seedWikiFiles(projectRoot) {
 
 async function createSkillSymlinks(projectRoot, skillRows, existingManifest, reLink, colors, t = null) {
   const strategies = {};
+  const errors = [];
 
   for (const skill of skillRows) {
     const target   = resolve(projectRoot, skill.relative_path);
@@ -1225,6 +1406,7 @@ async function createSkillSymlinks(projectRoot, skillRows, existingManifest, reL
         console.log(colors.yellow(`  [warn] ${result.message}`));
       }
     } catch (err) {
+      errors.push({ skill: skill.canonical_id, error: err });
       const msg = t
         ? t('error.symlink', { skill: skill.canonical_id, message: err.message })
         : `  [error] Failed to link ${skill.canonical_id}: ${err.message}`;
@@ -1232,7 +1414,7 @@ async function createSkillSymlinks(projectRoot, skillRows, existingManifest, reL
     }
   }
 
-  return { strategies };
+  return { strategies, errors };
 }
 
 async function buildFilesManifest(projectRoot, packs, pkgVersion) {

package/src/installer/fs.js

@@ -29,6 +29,7 @@ import {
   stat,
   readdir,
   symlink,
+  realpath,
   lstat,
   rm,
   copyFile,
@@ -186,6 +187,18 @@ export function fileHash(filePath) {
 // linkDirectory — symlink ladder
 // ---------------------------------------------------------------------------
 
+async function linkPointsToTarget(linkPath, target) {
+  try {
+    const [currentTarget, expectedTarget] = await Promise.all([
+      realpath(linkPath),
+      realpath(target),
+    ]);
+    return currentTarget === expectedTarget;
+  } catch (_) {
+    return false;
+  }
+}
+
 /**
  * @typedef {'symlink'|'junction'|'copy'} LinkStrategy
  */
@@ -206,9 +219,10 @@ export function fileHash(filePath) {
  *   2. fs.symlink(target, linkPath, 'junction')    — Windows directory junctions
  *   3. copyDir(target, linkPath) + warn            — final fallback
  *
- * When `linkPath` already exists and matches the same strategy recorded in
- * `existingStrategy` (from manifest), the function returns early (idempotent).
- * When `linkPath` already exists with a different strategy, it is removed first.
+ * When `linkPath` already exists and points to `target` with the same link
+ * strategy recorded in `existingStrategy`, the function returns early.
+ * Stale links are removed and recreated. Copy fallbacks are refreshed because
+ * their source target cannot be verified from filesystem metadata.
  *
  * @param {string}          target           - Real directory the link should point to.
  * @param {string}          linkPath         - Where the link/copy will be created.
@@ -220,20 +234,28 @@ export async function linkDirectory(target, linkPath, existingStrategy = null) {
   let existingStat = null;
   try {
     existingStat = await lstat(linkPath);
-  } catch (_) {
-    // Does not exist — proceed with creation
+  } catch (err) {
+    if (err.code !== 'ENOENT' && err.code !== 'ENOTDIR') throw err;
   }
 
   if (existingStat) {
     // If it is a symlink or junction pointing to the right target, keep it
-    if (existingStat.isSymbolicLink() && existingStrategy === 'symlink') {
-      return { strategy: 'symlink', message: `symlink already exists: ${linkPath}`, warning: false };
-    }
-    if (existingStat.isSymbolicLink() && existingStrategy === 'junction') {
-      return { strategy: 'junction', message: `junction already exists: ${linkPath}`, warning: false };
+    if (
+      existingStat.isSymbolicLink()
+      && (existingStrategy === 'symlink' || existingStrategy === 'junction')
+    ) {
+      if (await linkPointsToTarget(linkPath, target)) {
+        return {
+          strategy: existingStrategy,
+          message: `${existingStrategy} already exists: ${linkPath}`,
+          warning: false,
+        };
+      }
     }
     if (existingStat.isDirectory() && existingStrategy === 'copy') {
-      return { strategy: 'copy', message: `copy already exists: ${linkPath}`, warning: false };
+      await rm(linkPath, { recursive: true, force: true });
+      await copyDir(target, linkPath);
+      return { strategy: 'copy', message: `copy refreshed: ${linkPath}`, warning: false };
     }
     // Stale or mismatched — remove and recreate
     if (existingStat.isSymbolicLink()) {
@@ -249,8 +271,11 @@ export async function linkDirectory(target, linkPath, existingStrategy = null) {
 
   // Attempt 1: native symlink (macOS / Linux / Windows with Developer Mode)
   try {
-    await symlink(target, linkPath);
-    return { strategy: 'symlink', message: `symlink created: ${linkPath} -> ${target}`, warning: false };
+    const symlinkTarget = process.platform === 'win32'
+      ? resolve(target)
+      : (relative(dirname(linkPath), target) || '.');
+    await symlink(symlinkTarget, linkPath);
+    return { strategy: 'symlink', message: `symlink created: ${linkPath} -> ${symlinkTarget}`, warning: false };
   } catch (err1) {
     // EPERM on Windows without Developer Mode, or other platform restriction
     const isPermError = err1.code === 'EPERM' || err1.code === 'EACCES';
@@ -259,7 +284,7 @@ export async function linkDirectory(target, linkPath, existingStrategy = null) {
 
   // Attempt 2: Windows directory junction
   try {
-    await symlink(target, linkPath, 'junction');
+    await symlink(resolve(target), linkPath, 'junction');
     return { strategy: 'junction', message: `junction created: ${linkPath} -> ${target}`, warning: false };
   } catch (err2) {
     // Junction also failed — fall through to copy

package/src/installer/locales/en.mjs

@@ -75,6 +75,8 @@ export default {
   // ── Warnings ───────────────────────────────────────────────────────────────
   'warn.manifest_read':                        '[warn] Could not read existing manifest: {message}. Treating as fresh install.',
   'warn.copied_skills':                        '  [warn] Some skills were copied instead of symlinked. Run "lumina install --re-link" after enabling Windows Developer Mode.',
+  'warn.relocated':                            '  [warn] Workspace moved from {from} to {to}; managed links will be refreshed.',
+  'warn.preserved_modified_file':               '  [warn] Kept modified file that is no longer selected: {path}',
   'warn.upgrade_header':                       '[warn] Lumina upgraded v{from} -> v{to} — schema gap detected:',
   'warn.upgrade_errors':                       '       {errors} error(s), {warnings} warning(s) across legacy entries.',
   'warn.upgrade_fix_quick':                    '     Quick fix (deterministic):',

package/src/installer/locales/vi.mjs

@@ -74,6 +74,8 @@ export default {
   // ── Warnings ───────────────────────────────────────────────────────────────
   'warn.manifest_read':                        '[cảnh báo] Không đọc được manifest hiện tại: {message}. Coi như cài đặt mới.',
   'warn.copied_skills':                        '  [cảnh báo] Một số kỹ năng được sao chép thay vì symlink. Chạy "lumina install --re-link" sau khi bật Windows Developer Mode.',
+  'warn.relocated':                            '  [cảnh báo] Workspace đã chuyển từ {from} sang {to}; các liên kết do Lumina quản lý sẽ được làm mới.',
+  'warn.preserved_modified_file':               '  [cảnh báo] Giữ lại tệp đã được chỉnh sửa dù không còn được chọn: {path}',
   'warn.upgrade_header':                       '[cảnh báo] Lumina đã nâng cấp v{from} -> v{to} — phát hiện chênh lệch schema:',
   'warn.upgrade_errors':                       '       {errors} lỗi, {warnings} cảnh báo trên các mục cũ.',
   'warn.upgrade_fix_quick':                    '     Sửa nhanh (xác định):',