finalize

2026-09-10 21:39:32 +02:00
parent 5993da4ce6
commit a25adacaee
19 changed files with 1407 additions and 79 deletions
@@ -1,5 +1,42 @@
 # Changelog
 ## 0.1.26 — 2026-09-10
 ### Added
 - **AI Agent access (MCP).** `RA3 Mod XML: Enable AI Agent access…` exposes the
  semantic index to AI agent clients through a local, read-only MCP (Model
  Context Protocol) server. It exports a stable snapshot, writes a launcher
  under `~/.ra3modxml/`, starts a loopback query server while VS Code is
  running, and offers to install the Agent Skill and/or write the MCP client
  configuration (Claude Desktop, Cursor global/project, or a copied generic
  block). `Disable AI Agent access` stops the live server for the workspace;
  `Uninstall AI Agent integration…` removes MCP config entries, the launcher,
  and Skill copies after a confirmation prompt.
 - **Agent Skill (`ra3-mod-xml`).** `RA3 Mod XML: Install Agent Skill…` installs
  `SKILL.md` plus a query-tool reference to `~/.agents/skills/`, and optionally
  to Claude Code or project-local skill directories. It explains when the index
  applies and how to reach it with or without MCP. `Uninstall Agent Skill…` 
  removes only directories that still carry the extension's marker.
 - **`RA3 Mod XML: Export AI Agent index snapshot`** writes the gzipped,
  versioned snapshot that the MCP server and CLI fall back to when VS Code is
  closed.
 - **Agent CLI** (`dist/agent/cli.js`): live-index first, exported-snapshot
  fallback. `outgoing` and `projects` need element context and report that
  explicitly instead of returning an empty result.
 - **First-run / upgrade introduction.** After the first index, the extension
  offers AI Agent access once (per machine). Upgrades from a build that already
  had the feature stay silent, and "Don't show again" is remembered.
 - **Live discovery and multi-window safety.** Per-project endpoint files, one
  `instances/` entry per VS Code window, and a merged `~/.ra3modxml/index.json`.
  Queries are pinned to a project and a mismatched answer is refused. A crashed
  window's instance file is pruned by the next activation.
 - **No Node installation required.** The MCP launcher for AI Agent Access runs
  the bundled server on VS Code's own Electron binary (`ELECTRON_RUN_AS_NODE=1`)
  and falls back to `node` on `PATH` only when that binary is missing.
  Launchers are refreshed on activation, so moving or updating VS Code does not
  break an existing MCP configuration.
 ## 0.1.25 — 2026-08-11
 ### Changed
@@ -156,7 +156,10 @@ to an empty string opts out of SDK features permanently.
 * `RA3 Mod XML: Find unreferenced assets…`
 * `RA3 Mod XML: Find unreferenced assets of this type`
 * `RA3 Mod XML: Enable AI Agent access…`
 * `RA3 Mod XML: Disable AI Agent access`
 * `RA3 Mod XML: Install Agent Skill…`
 * `RA3 Mod XML: Uninstall Agent Skill…`
 * `RA3 Mod XML: Uninstall AI Agent integration…`
 * `RA3 Mod XML: Export AI Agent index snapshot`
 ## AI Agent Access
@@ -213,6 +216,32 @@ the live index when VS Code is running and from the exported snapshot
 otherwise; commands that need element context say so explicitly rather than
 returning an empty result.
 ### Installing and removing the integration
 * `RA3 Mod XML: Install Agent Skill…` works with or without an indexed project.
  The default target is the cross-agent `~/.agents/skills/ra3-mod-xml/`
  convention; Claude Code (`~/.claude/skills/`), project-local `.agents/skills/`
  and `.claude/skills/`, and any custom folder can be selected too.
 * `RA3 Mod XML: Uninstall Agent Skill…` lists the recorded copies and removes
  only directories that still carry the extension's marker. A folder the user
  replaced or created by hand is never deleted.
 * `RA3 Mod XML: Disable AI Agent access` stops the live query server for the
  current workspace (project discovery files for this window are cleaned up).
  Installed skills and MCP client configurations are kept.
 * `RA3 Mod XML: Uninstall AI Agent integration…` is the cleanup wizard. It can
  stop live access, remove installed Agent Skills, delete the MCP entries this
  extension wrote (from the recorded files and the conventional Claude
  Desktop / Cursor paths, leaving other servers untouched), and delete the
  stable launcher. Nothing is removed before a confirmation prompt.
 After an extension upgrade, recorded Skill copies are rewritten automatically
 to the new version; directories without the extension's marker are left alone.
 The first time an AI Agent feature becomes available (fresh install, or an
 upgrade from an older version), the extension offers to enable it after the
 first index. It never asks twice: choosing "Don't show again" — or simply
 ignoring the message — is remembered, and later upgrades stay silent.
 See `docs/ai-agent-integration-plan.md` for the full design and progress.
 ## Requirements
@@ -153,7 +153,10 @@
 * `RA3 Mod XML: Find unreferenced assets…`（查找未引用的资产…）
 * `RA3 Mod XML: Find unreferenced assets of this type`（查找此类型的未引用资产）
 * `RA3 Mod XML: Enable AI Agent access…`（启用 AI Agent 访问…）
 * `RA3 Mod XML: Disable AI Agent access`（禁用 AI Agent 访问）
 * `RA3 Mod XML: Install Agent Skill…`（安装 Agent Skill…）
 * `RA3 Mod XML: Uninstall Agent Skill…`（卸载 Agent Skill…）
 * `RA3 Mod XML: Uninstall AI Agent integration…`（卸载 AI Agent 集成…）
 * `RA3 Mod XML: Export AI Agent index snapshot`（导出 AI Agent 索引快照）
 ## AI Agent 访问
@@ -184,6 +187,17 @@ Endpoint 按项目存放（`~/.ra3modxml/endpoints/<project>.json`），因此
 MCP Server 本质上就是 stdio 上的 JSON-RPC，因此 agent 也可以完全不做 MCP 配置，直接把请求管道给 launcher。另有一个配套 CLI（`cli.js`，与 `mcpServer.js` 同在 `dist/agent/`）：VS Code 运行时走实时索引，否则读导出的快照；需要元素上下文的命令会明确说明，而不是返回空结果。
 ### 安装与移除
 * `RA3 Mod XML: Install Agent Skill…` 不要求项目已建立索引。默认安装到跨 agent 的 `~/.agents/skills/ra3-mod-xml/`，也可选择 Claude Code（`~/.claude/skills/`）、项目级 `.agents/skills/` 与 `.claude/skills/`，或任意自定义文件夹。
 * `RA3 Mod XML: Uninstall Agent Skill…` 列出已记录的安装位置，只删除仍带有本扩展标记的目录；被用户替换或手工创建的目录不会被删除。
 * `RA3 Mod XML: Disable AI Agent access` 停止当前工作区的实时查询服务并清理本窗口的发现文件；已安装的 Skill 与 MCP 客户端配置会保留。
 * `RA3 Mod XML: Uninstall AI Agent integration…` 是清理向导：可停止实时访问、移除已安装的 Agent Skill、删除本扩展写入的 MCP 配置项（来自记录文件与常规的 Claude Desktop / Cursor 路径，不会动其他 server），以及删除稳定 launcher。确认之前不会删除任何内容。
 扩展升级后，记录中的 Skill 副本会自动重写到新版本；不带本扩展标记的目录不会被改写。
 当 AI Agent 功能首次可用时（全新安装，或从旧版本升级），扩展会在第一次索引完成后询问是否启用。它不会反复打扰：选择"不再提示"——或者干脆忽略——都会被记住，之后的升级保持静默。
 完整设计与进度见 `docs/ai-agent-integration-plan.md`。
 ## 环境要求
@@ -1120,3 +1120,66 @@ test/*.test.mjs                37 个文件 / 302 个用例，299 通过，3 跳
 - **发现降级**：删掉 `endpoints/` 后仍能通过 `instances/` 找到实例。
 - **崩溃剪枝**：插入一个 PID 必死的实例，剪枝后另一个实例仍正常工作；
  清理本窗口实例不影响其他窗口。
 ---
 ## 20. P0 修复（2026-09-10）
 三期测试暴露 / 评审发现的问题，以下四项已修复：
 | # | 问题 | 修复 |
 |---|---|---|
 | 1 | `test/agentSkill.test.mjs` 与 `SKILL.md` 措辞不一致（`new session` / `Never fabricate index results` 在源码中丢失），干净重建后测试失败 | 恢复两条护栏；测试同步断言 |
 | 2 | Skill 里的 `CnC3Types.xsd` 说法错误：它是 RA3 Mod SDK 也携带的 SAGE 基础 schema（`sdk.ts` 的 SDK 根标记就是它），原句会让 agent 误判真实 RA3 项目 | 删除该句，改为通用否定规则（SAGE-looking XML / 复制的 `.xsd` / `Data` 目录本身都不构成证据） |
 | 3 | 关闭一个 VS Code 窗口会无条件 `clearEndpoint()` + `writeManifest([])`，抹掉其他仍在服务窗口的 `endpoint.json` / `index.json` | 新增 `refreshDiscovery()`：从幸存 instance 文件重新推导两者；`stopAgentLocalServer` 改用它；新增回归测试 |
 | 4 | `npm run build` 不清理 `dist/`，0.1.26 VSIX 同时带着旧布局的 `dist/mcpServer.js` / `dist/cli.js` | `esbuild.mjs` 构建前 `rm -rf dist` |
 同时：
 - `SKILL.md` 修正被合并的 `find_define` 列表项与 `the your own harness'` 笔误；
  从 `SKILL.md` 链接 `references/query-guide.md`（skills 客户端只按需加载被引用的
  资源，之前该文件永远不会被读取）；CLI 段落补充“它是 Node 脚本、没有 Node 时用
  launcher 里的 Electron 运行时”的说明。
 - `CHANGELOG.md` 补上 0.1.26 条目。
 - 全量测试：310 通过 / 0 失败 / 3 跳过（跳过项仍是沙箱禁止 spawn 的三条）。
 ## 21. P1 第一批：安装 / 卸载 / 禁用（2026-09-10）
 针对“安装与卸载要简单”“升级后要能自动同步”两项：
 | 内容 | 实现 |
 |---|---|
 | 安装不再依赖索引 | `ra3modxml.installAgentSkill` 改为只读取 `ws.projectRoot`（可为空），无项目时仍可装到用户级目录 |
 | 安装位置更灵活 | 默认 `~/.agents/skills`、Claude Code、项目级 `.agents/skills` / `.claude/skills`、以及自定义文件夹（`<folder>/ra3-mod-xml`） |
 | 安全卸载 | 新增 `readSkillMarker` / `installedSkillStatus` / `uninstallRecordedSkills` / `forgetSkillInstallRecords`：只删除带 marker 且路径匹配的目录，用户替换过的目录跳过并报告 |
 | 禁用实时访问 | 新增 `ra3modxml.disableAgentAccess`：停服务器、清本窗口 instance/endpoint、从幸存实例重建发现文件，保留 skill 与 MCP 配置 |
 | 完整卸载向导 | 新增 `ra3modxml.uninstallAgentIntegration`：可勾选停止实时访问 / 移除 Skill / 移除 MCP 配置 / 删除 launcher，确认后才执行 |
 | MCP 配置可回滚 | 新增 `mcp-install.json` 记录（`installMcpServerConfigToFile`）、`removeMcpServerFromConfigFile`（同时兼容 `mcpServers` 与 VS Code 的 `servers`，空容器自动删除）、`uninstallMcpServerConfigs`（记录 + 常规客户端路径）、`removeLauncher` |
 | 升级自动同步 | 激活时对比 `skill-install.json` 中的版本，有差异才调用 `syncInstalledSkills` 重写；无 marker 的目录不改写 |
 | 本地化 | 新增 55 条 AI Agent 相关字符串到 `l10n/bundle.l10n.json` 与 `zh-cn`（共 210 条/语言），命令标题加入 `package.nls.*` |
 测试：`agentSetup.test.mjs` 6 项、`agentSkill.test.mjs` 7 项（含 marker 防误删、
 MCP 配置保留其他 server、空容器清理、记录回滚）。
 ## 22. P1 第二批：首装 / 升级提示（2026-09-10）
 - 新增纯逻辑模块 `src/agent/onboarding.ts`（可单测）：
  - `AGENT_FEATURE_VERSION = "0.1.26"`；
  - `shouldOfferAgentOnboarding(state, currentVersion)`：
    首次安装提示一次；从早于 0.1.26 的版本升级提示一次；
    已在带此功能的版本提示过则保持静默；`dismissed` 永久抑制；
  - `compareVersions` 处理 `"0.1" < "0.1.26"`、`"0.1.26-beta" == "0.1.26"`。
 - `extension.ts` 在**第一次索引完成后**（`ws.onIndexUpdate`）弹一次信息提示，
  按钮为 `Enable AI Agent access…` / `Learn more` / `Don't show again`；
  无论用户选择还是忽略，都会把 `informedVersion` 写入 `globalState`，不会重复打扰。
 - 新增 4 条本地化字符串（两种语言各 214 条）。
 - `test/onboarding.test.mjs`：5 个用例覆盖上述规则。
 ### 仍未处理（下一批）
 - VS Code 原生 `chatSkills` / `mcpServerDefinitionProviders` 接入（免 launcher /
  免手写配置）。
 - Claude/Cursor 路径收敛为数据驱动预设 + `configure --harness`；
  稳定 CLI launcher（免 Node 路径发现）。
 - `mcpServer.ts` 的 `serverInfo.version` 仍硬编码 `0.1.0`；
  `startAgentLocalServer` 仍有并发启动竞态。
@@ -1,7 +1,14 @@
 import * as esbuild from "esbuild";
 import { rm } from "node:fs/promises";
 const watch = process.argv.includes("--watch");
 // Remove previous outputs first. esbuild only overwrites the files its current
 // entry points produce, so without this a packaged VSIX can ship stale
 // artifacts from an older layout (e.g. the pre-`outbase` dist/mcpServer.js
 // next to the current dist/agent/mcpServer.js).
 await rm("dist", { recursive: true, force: true });
 const ctx = await esbuild.context({
  entryPoints: [
    "./src/extension.ts",
@@ -153,5 +153,64 @@
  "Reference \"{0}\" has no definition of type `{1}` (ids with the same name exist for other types)": "Reference \"{0}\" has no definition of type `{1}` (ids with the same name exist for other types)",
  "Reference \"{0}\" has no definition of the expected declared type (ids with the same name exist for other types)": "Reference \"{0}\" has no definition of the expected declared type (ids with the same name exist for other types)",
  "Reference \"{0}\" has no matching definition (ids with the same name exist for other types)": "Reference \"{0}\" has no matching definition (ids with the same name exist for other types)",
-  "Unresolved reference \"{0}\" (not found in the current index)": "Unresolved reference \"{0}\" (not found in the current index)"
+  "Unresolved reference \"{0}\" (not found in the current index)": "Unresolved reference \"{0}\" (not found in the current index)",
  "RA3 Mod XML: no index available yet. Wait for indexing to finish before exporting an AI Agent snapshot.": "RA3 Mod XML: no index available yet. Wait for indexing to finish before exporting an AI Agent snapshot.",
  "RA3 Mod XML: exported AI Agent index snapshot to {0}": "RA3 Mod XML: exported AI Agent index snapshot to {0}",
  "Reveal in Explorer": "Reveal in Explorer",
  "RA3 Mod XML: failed to export AI Agent index snapshot: {0}": "RA3 Mod XML: failed to export AI Agent index snapshot: {0}",
  "RA3 Mod XML: no index available yet. Wait for indexing to finish before enabling AI Agent access.": "RA3 Mod XML: no index available yet. Wait for indexing to finish before enabling AI Agent access.",
  "RA3 Mod XML: the AI Agent launcher will use Node from PATH. Install Node, or run VS Code from a normal installation so the bundled runtime can be used.": "RA3 Mod XML: the AI Agent launcher will use Node from PATH. Install Node, or run VS Code from a normal installation so the bundled runtime can be used.",
  "Install Agent Skill (recommended)": "Install Agent Skill (recommended)",
  "Write MCP config to Claude Desktop": "Write MCP config to Claude Desktop",
  "Write MCP config to Cursor (global)": "Write MCP config to Cursor (global)",
  "Write MCP config to Cursor (project)": "Write MCP config to Cursor (project)",
  "Copy MCP config": "Copy MCP config",
  "RA3 Mod XML AI Agent access enabled. Choose an optional next step.": "RA3 Mod XML AI Agent access enabled. Choose an optional next step.",
  "RA3 Mod XML Agent Skill installed to {0}": "RA3 Mod XML Agent Skill installed to {0}",
  "RA3 Mod XML: could not write the Agent Skill to {0}": "RA3 Mod XML: could not write the Agent Skill to {0}",
  "RA3 Mod XML MCP config written to {0}": "RA3 Mod XML MCP config written to {0}",
  "RA3 Mod XML MCP config copied to clipboard.": "RA3 Mod XML MCP config copied to clipboard.",
  "RA3 Mod XML: failed to enable AI Agent access: {0}": "RA3 Mod XML: failed to enable AI Agent access: {0}",
  "Default (~/.agents/skills)": "Default (~/.agents/skills)",
  "Claude Code (~/.claude/skills)": "Claude Code (~/.claude/skills)",
  "Current project .agents/skills": "Current project .agents/skills",
  "Current project .claude/skills": "Current project .claude/skills",
  "Choose a custom folder…": "Choose a custom folder…",
  "The skill is installed as <folder>/{0}": "The skill is installed as <folder>/{0}",
  "Select Agent Skill install locations": "Select Agent Skill install locations",
  "Choose a skill folder": "Choose a skill folder",
  "Choose the folder that should contain the {0} skill": "Choose the folder that should contain the {0} skill",
  "RA3 Mod XML: could not write the Agent Skill (0 of {0} locations).": "RA3 Mod XML: could not write the Agent Skill (0 of {0} locations).",
  "RA3 Mod XML Agent Skill installed to {0} location(s); {1} failed.": "RA3 Mod XML Agent Skill installed to {0} location(s); {1} failed.",
  "RA3 Mod XML Agent Skill installed to {0} location(s).": "RA3 Mod XML Agent Skill installed to {0} location(s).",
  "Show installed skills": "Show installed skills",
  "RA3 Mod XML: no recorded Agent Skill installation to remove.": "RA3 Mod XML: no recorded Agent Skill installation to remove.",
  "missing — will be dropped from the record": "missing — will be dropped from the record",
  "installed by this extension (v{0})": "installed by this extension (v{0})",
  "not managed by this extension — will be skipped": "not managed by this extension — will be skipped",
  "No RA3 Mod XML skill marker found; remove it manually if you want it gone.": "No RA3 Mod XML skill marker found; remove it manually if you want it gone.",
  "Select Agent Skill installations to remove": "Select Agent Skill installations to remove",
  "RA3 Mod XML: removed {0} Agent Skill installation(s); {1} skipped (not managed by this extension).": "RA3 Mod XML: removed {0} Agent Skill installation(s); {1} skipped (not managed by this extension).",
  "RA3 Mod XML: removed {0} Agent Skill installation(s).": "RA3 Mod XML: removed {0} Agent Skill installation(s).",
  "RA3 Mod XML: AI Agent access disabled for this workspace. Installed skills and MCP client configurations were kept.": "RA3 Mod XML: AI Agent access disabled for this workspace. Installed skills and MCP client configurations were kept.",
  "Uninstall AI Agent integration…": "Uninstall AI Agent integration…",
  "Stop live AI Agent access in this window": "Stop live AI Agent access in this window",
  "Remove installed Agent Skills": "Remove installed Agent Skills",
  "{0} location(s)": "{0} location(s)",
  "Remove MCP client configuration entries": "Remove MCP client configuration entries",
  "Claude Desktop / Cursor and files recorded by this extension": "Claude Desktop / Cursor and files recorded by this extension",
  "Remove the stable MCP launcher": "Remove the stable MCP launcher",
  "Select what to remove (nothing is removed until you confirm)": "Select what to remove (nothing is removed until you confirm)",
  "Remove the selected AI Agent components?": "Remove the selected AI Agent components?",
  "Remove": "Remove",
  "live access stopped": "live access stopped",
  "{0} skill installation(s) removed": "{0} skill installation(s) removed",
  "{0} unmanaged skill folder(s) skipped": "{0} unmanaged skill folder(s) skipped",
  "MCP config removed from {0} file(s)": "MCP config removed from {0} file(s)",
  "MCP launcher removed": "MCP launcher removed",
  "RA3 Mod XML AI Agent cleanup: {0}.": "RA3 Mod XML AI Agent cleanup: {0}.",
  "RA3 Mod XML: this version can expose the project's asset index to AI agents (MCP + Agent Skill). Enable it?": "RA3 Mod XML: this version can expose the project's asset index to AI agents (MCP + Agent Skill). Enable it?",
  "Enable AI Agent access": "Enable AI Agent access",
  "Learn more": "Learn more",
  "Don't show again": "Don't show again"
 }
@@ -153,5 +153,64 @@
  "Reference \"{0}\" has no definition of type `{1}` (ids with the same name exist for other types)": "引用 \"{0}\" 没有类型为 `{1}` 的定义（其他类型存在同名 id）",
  "Reference \"{0}\" has no definition of the expected declared type (ids with the same name exist for other types)": "引用 \"{0}\" 没有符合声明类型的定义（其他类型存在同名 id）",
  "Reference \"{0}\" has no matching definition (ids with the same name exist for other types)": "引用 \"{0}\" 没有匹配的定义（其他类型存在同名 id）",
-  "Unresolved reference \"{0}\" (not found in the current index)": "无法解析的引用 \"{0}\"（当前索引中未找到）"
+  "Unresolved reference \"{0}\" (not found in the current index)": "无法解析的引用 \"{0}\"（当前索引中未找到）",
  "RA3 Mod XML: no index available yet. Wait for indexing to finish before exporting an AI Agent snapshot.": "RA3 Mod XML：暂无可用索引。请等待索引完成后再导出 AI Agent 快照。",
  "RA3 Mod XML: exported AI Agent index snapshot to {0}": "RA3 Mod XML：已导出 AI Agent 索引快照到 {0}",
  "Reveal in Explorer": "在资源管理器中显示",
  "RA3 Mod XML: failed to export AI Agent index snapshot: {0}": "RA3 Mod XML：导出 AI Agent 索引快照失败：{0}",
  "RA3 Mod XML: no index available yet. Wait for indexing to finish before enabling AI Agent access.": "RA3 Mod XML：暂无可用索引。请等待索引完成后再启用 AI Agent 访问。",
  "RA3 Mod XML: the AI Agent launcher will use Node from PATH. Install Node, or run VS Code from a normal installation so the bundled runtime can be used.": "RA3 Mod XML：AI Agent 启动器将使用 PATH 中的 Node。请安装 Node，或从正常安装的 VS Code 启动，以使用内置运行时。",
  "Install Agent Skill (recommended)": "安装 Agent Skill（推荐）",
  "Write MCP config to Claude Desktop": "将 MCP 配置写入 Claude Desktop",
  "Write MCP config to Cursor (global)": "将 MCP 配置写入 Cursor（全局）",
  "Write MCP config to Cursor (project)": "将 MCP 配置写入 Cursor（项目）",
  "Copy MCP config": "复制 MCP 配置",
  "RA3 Mod XML AI Agent access enabled. Choose an optional next step.": "RA3 Mod XML AI Agent 访问已启用。请选择可选的后续操作。",
  "RA3 Mod XML Agent Skill installed to {0}": "RA3 Mod XML Agent Skill 已安装到 {0}",
  "RA3 Mod XML: could not write the Agent Skill to {0}": "RA3 Mod XML：无法将 Agent Skill 写入 {0}",
  "RA3 Mod XML MCP config written to {0}": "RA3 Mod XML MCP 配置已写入 {0}",
  "RA3 Mod XML MCP config copied to clipboard.": "RA3 Mod XML MCP 配置已复制到剪贴板。",
  "RA3 Mod XML: failed to enable AI Agent access: {0}": "RA3 Mod XML：启用 AI Agent 访问失败：{0}",
  "Default (~/.agents/skills)": "默认（~/.agents/skills）",
  "Claude Code (~/.claude/skills)": "Claude Code（~/.claude/skills）",
  "Current project .agents/skills": "当前项目 .agents/skills",
  "Current project .claude/skills": "当前项目 .claude/skills",
  "Choose a custom folder…": "选择自定义文件夹…",
  "The skill is installed as <folder>/{0}": "Skill 将安装到 <文件夹>/{0}",
  "Select Agent Skill install locations": "选择 Agent Skill 安装位置",
  "Choose a skill folder": "选择 Skill 文件夹",
  "Choose the folder that should contain the {0} skill": "选择用于存放 {0} Skill 的文件夹",
  "RA3 Mod XML: could not write the Agent Skill (0 of {0} locations).": "RA3 Mod XML：无法写入 Agent Skill（{0} 个位置全部失败）。",
  "RA3 Mod XML Agent Skill installed to {0} location(s); {1} failed.": "RA3 Mod XML Agent Skill 已安装到 {0} 个位置；{1} 个失败。",
  "RA3 Mod XML Agent Skill installed to {0} location(s).": "RA3 Mod XML Agent Skill 已安装到 {0} 个位置。",
  "Show installed skills": "查看已安装的 Skill",
  "RA3 Mod XML: no recorded Agent Skill installation to remove.": "RA3 Mod XML：没有可移除的 Agent Skill 安装记录。",
  "missing — will be dropped from the record": "已缺失——将从记录中删除",
  "installed by this extension (v{0})": "由本扩展安装（v{0}）",
  "not managed by this extension — will be skipped": "不由本扩展管理——将跳过",
  "No RA3 Mod XML skill marker found; remove it manually if you want it gone.": "未找到 RA3 Mod XML Skill 标记；如需删除请手动处理。",
  "Select Agent Skill installations to remove": "选择要移除的 Agent Skill 安装",
  "RA3 Mod XML: removed {0} Agent Skill installation(s); {1} skipped (not managed by this extension).": "RA3 Mod XML：已移除 {0} 个 Agent Skill 安装；跳过 {1} 个（不由本扩展管理）。",
  "RA3 Mod XML: removed {0} Agent Skill installation(s).": "RA3 Mod XML：已移除 {0} 个 Agent Skill 安装。",
  "RA3 Mod XML: AI Agent access disabled for this workspace. Installed skills and MCP client configurations were kept.": "RA3 Mod XML：已禁用此工作区的 AI Agent 访问。已安装的 Skill 和 MCP 客户端配置已保留。",
  "Uninstall AI Agent integration…": "卸载 AI Agent 集成…",
  "Stop live AI Agent access in this window": "在此窗口中停止实时 AI Agent 访问",
  "Remove installed Agent Skills": "移除已安装的 Agent Skill",
  "{0} location(s)": "{0} 个位置",
  "Remove MCP client configuration entries": "移除 MCP 客户端配置项",
  "Claude Desktop / Cursor and files recorded by this extension": "Claude Desktop / Cursor 以及本扩展记录过的配置文件",
  "Remove the stable MCP launcher": "移除稳定的 MCP 启动器",
  "Select what to remove (nothing is removed until you confirm)": "选择要移除的内容（确认前不会删除任何内容）",
  "Remove the selected AI Agent components?": "要移除选中的 AI Agent 组件吗？",
  "Remove": "移除",
  "live access stopped": "已停止实时访问",
  "{0} skill installation(s) removed": "已移除 {0} 个 Skill 安装",
  "{0} unmanaged skill folder(s) skipped": "已跳过 {0} 个非本扩展管理的 Skill 目录",
  "MCP config removed from {0} file(s)": "已从 {0} 个配置文件中移除 MCP 配置",
  "MCP launcher removed": "已移除 MCP 启动器",
  "RA3 Mod XML AI Agent cleanup: {0}.": "RA3 Mod XML AI Agent 清理完成：{0}。",
  "RA3 Mod XML: this version can expose the project's asset index to AI agents (MCP + Agent Skill). Enable it?": "RA3 Mod XML：此版本可以把项目资产索引提供给 AI Agent（MCP + Agent Skill）。要启用吗？",
  "Enable AI Agent access": "启用 AI Agent 访问",
  "Learn more": "了解更多",
  "Don't show again": "不再提示"
 }
@@ -130,10 +130,22 @@
        "command": "ra3modxml.enableAgentAccess",
        "title": "%ra3modxml.command.enableAgentAccess.title%"
      },
      {
        "command": "ra3modxml.disableAgentAccess",
        "title": "%ra3modxml.command.disableAgentAccess.title%"
      },
      {
        "command": "ra3modxml.installAgentSkill",
        "title": "%ra3modxml.command.installAgentSkill.title%"
      },
      {
        "command": "ra3modxml.uninstallAgentSkill",
        "title": "%ra3modxml.command.uninstallAgentSkill.title%"
      },
      {
        "command": "ra3modxml.uninstallAgentIntegration",
        "title": "%ra3modxml.command.uninstallAgentIntegration.title%"
      },
      {
        "command": "ra3modxml.exportIndexSnapshot",
        "title": "%ra3modxml.command.exportIndexSnapshot.title%"
@@ -14,7 +14,10 @@
  "ra3modxml.command.configureSdkPath.title": "RA3 Mod XML: Configure SDK path…",
  "ra3modxml.command.showCacheReport.title": "RA3 Mod XML: Show cache report",
  "ra3modxml.command.enableAgentAccess.title": "RA3 Mod XML: Enable AI Agent access…",
  "ra3modxml.command.disableAgentAccess.title": "RA3 Mod XML: Disable AI Agent access",
  "ra3modxml.command.installAgentSkill.title": "RA3 Mod XML: Install Agent Skill…",
  "ra3modxml.command.uninstallAgentSkill.title": "RA3 Mod XML: Uninstall Agent Skill…",
  "ra3modxml.command.uninstallAgentIntegration.title": "RA3 Mod XML: Uninstall AI Agent integration…",
  "ra3modxml.command.exportIndexSnapshot.title": "RA3 Mod XML: Export AI Agent index snapshot",
  "ra3modxml.command.findUnreferencedAssets.title": "RA3 Mod XML: Find unreferenced assets…",
  "ra3modxml.command.findUnreferencedAssetsOfType.title": "RA3 Mod XML: Find unreferenced assets of this type"
@@ -14,7 +14,10 @@
  "ra3modxml.command.configureSdkPath.title": "RA3 Mod XML: 配置 SDK 路径…",
  "ra3modxml.command.showCacheReport.title": "RA3 Mod XML: 显示缓存报告",
  "ra3modxml.command.enableAgentAccess.title": "RA3 Mod XML: 启用 AI Agent 访问…",
  "ra3modxml.command.disableAgentAccess.title": "RA3 Mod XML: 禁用 AI Agent 访问",
  "ra3modxml.command.installAgentSkill.title": "RA3 Mod XML: 安装 Agent Skill…",
  "ra3modxml.command.uninstallAgentSkill.title": "RA3 Mod XML: 卸载 Agent Skill…",
  "ra3modxml.command.uninstallAgentIntegration.title": "RA3 Mod XML: 卸载 AI Agent 集成…",
  "ra3modxml.command.exportIndexSnapshot.title": "RA3 Mod XML: 导出 AI Agent 索引快照",
  "ra3modxml.command.findUnreferencedAssets.title": "RA3 Mod XML: 查找未引用的资产…",
  "ra3modxml.command.findUnreferencedAssetsOfType.title": "RA3 Mod XML: 查找该类型的未引用资产"
@@ -21,7 +21,7 @@
 import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { isProcessAlive, type AgentEndpoint } from "./endpoint";
+import { clearEndpoint, isProcessAlive, writeEndpoint, type AgentEndpoint } from "./endpoint";
 import { defaultAgentHome, snapshotBaseName } from "./snapshot";
 /** One live extension-host instance. */
@@ -216,6 +216,52 @@ export async function readManifest(
  }
 }
 /**
 * Re-derives the legacy global endpoint pointer and the merged discovery
 * manifest from the instance files that still exist and whose recorded
 * process is alive.
 *
 * Called after an instance file is removed (window closed, or pruned as
 * crashed). Closing one window must never make another still-running window
 * undiscoverable: whichever writer changed the instance set has to rebuild
 * both derived files from the survivors instead of clearing them.
 *
 * Best-effort: the pointer/manifest are discovery conveniences, and readers
 * can always scan `instances/`, so failures never propagate to the caller.
 */
 export async function refreshDiscovery(
  agentHome = defaultAgentHome(),
 ): Promise<AgentIndexManifest> {
  const { kept } = await pruneInstances(agentHome);
  const first = kept[0];
  try {
    if (first) {
      await writeEndpoint(endpointOf(first), agentHome);
    } else {
      await clearEndpoint(agentHome);
    }
  } catch {
    // Discovery pointer only; the manifest below is still worth writing.
  }
  return writeManifest(kept, agentHome);
 }
 /**
 * The endpoint fields of an instance file, without the registry-only
 * `instanceId` (endpoint.json predates the instance registry and readers do
 * not expect that field).
 */
 function endpointOf(instance: AgentInstance): AgentEndpoint {
  return {
    url: instance.url,
    token: instance.token,
    projectDir: instance.projectDir,
    projects: instance.projects,
    processId: instance.processId,
    updatedAt: instance.updatedAt,
  };
 }
 /** Snapshot path for a project, re-exported for discovery convenience. */
 export function projectKey(projectDir: string): string {
  return snapshotBaseName(projectDir);
@@ -0,0 +1,61 @@
 /**
 * One-time "this version can expose the index to AI agents" notification.
 *
 * Pure decision logic (no VS Code dependency) so the anti-nag rules can be
 * unit tested:
 *
 * - a fresh install is informed once;
 * - an upgrade from a build that predates the feature is informed once;
 * - an upgrade from a build that already had the feature stays silent;
 * - "Don't show again" (and simply ignoring the message) is remembered, so
 *   the prompt never becomes a recurring nag.
 */
 /** Extension version that introduced AI Agent access. */
 export const AGENT_FEATURE_VERSION = "0.1.26";
 export interface AgentOnboardingState {
  /** Extension version whose notification was already shown. */
  informedVersion?: string;
  /** The user explicitly chose "Don't show again". */
  dismissed?: boolean;
 }
 /**
 * True when the AI Agent introduction should be shown for this version.
 */
 export function shouldOfferAgentOnboarding(
  state: AgentOnboardingState | undefined,
  currentVersion: string,
 ): boolean {
  if (state?.dismissed) return false;
  if (!state?.informedVersion) return true; // First run with this feature.
  if (state.informedVersion === currentVersion) return false;
  // Already informed by a build that had the feature: never repeat.
  // Only upgrades from before the feature introduce it once.
  return compareVersions(state.informedVersion, AGENT_FEATURE_VERSION) < 0;
 }
 /**
 * Compares dotted numeric versions ("1.2.3" > "1.2"). Non-numeric segments
 * count as 0, and a missing segment is smaller than a present one, so
 * "0.1.26" > "0.1" and "0.1.26" > "0.1.26-beta".
 */
 export function compareVersions(a: string, b: string): number {
  const parse = (value: string): number[] =>
    String(value)
      .split(".")
      .map((part) => {
        const match = /^(\d+)/.exec(part.trim());
        return match ? Number(match[1]) : 0;
      });
  const left = parse(a);
  const right = parse(b);
  const length = Math.max(left.length, right.length);
  for (let i = 0; i < length; i++) {
    const l = left[i] ?? 0;
    const r = right[i] ?? 0;
    if (l !== r) return l < r ? -1 : 1;
  }
  return 0;
 }
@@ -9,9 +9,9 @@
 * Pure TypeScript: no VS Code dependency.
 */
-import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { defaultAgentHome } from "./snapshot";
 import {
  launcherScript,
@@ -19,6 +19,9 @@ import {
  type AgentRuntime,
 } from "./runtime";
 /** Key this extension uses for its MCP server entry in every client config. */
 export const MCP_SERVER_KEY = "ra3-mod-xml";
 export interface McpConfigTarget {
  id: string;
  label: string;
@@ -152,12 +155,13 @@ export function commonMcpConfigTargets(projectDir: string): McpConfigTarget[] {
 /**
 * Adds the RA3 Mod XML MCP server entry to a JSON config file, preserving any
- * existing keys and mcpServers. Creates the file when it does not exist.
+ * existing keys and `mcpServers`. Creates the file when it does not exist.
 */
 export async function addMcpServerToConfigFile(
  filePath: string,
  launcher: string,
  projectDir: string,
  serverKey = MCP_SERVER_KEY,
 ): Promise<void> {
  let config: Record<string, unknown> = {};
  try {
@@ -166,7 +170,7 @@ export async function addMcpServerToConfigFile(
    // File absent or malformed: start fresh.
  }
  const servers = (config.mcpServers as Record<string, unknown> | undefined) ?? {};
-  servers["ra3-mod-xml"] = {
+  servers[serverKey] = {
    command: launcher,
    args: ["--project", projectDir],
  };
@@ -175,6 +179,180 @@ export async function addMcpServerToConfigFile(
  await writeFile(filePath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
 }
 /**
 * Removes this extension's server entry from a JSON config file, preserving
 * every other server and top-level key. Handles both the widely used
 * `mcpServers` container and VS Code's `servers` container, and deletes a
 * container that becomes empty.
 *
 * Returns true only when an entry was actually removed; a missing, malformed
 * or already-clean file is left untouched.
 */
 export async function removeMcpServerFromConfigFile(
  filePath: string,
  serverKey = MCP_SERVER_KEY,
 ): Promise<boolean> {
  let config: Record<string, unknown>;
  try {
    config = JSON.parse(await readFile(filePath, "utf8")) as Record<string, unknown>;
  } catch {
    return false;
  }
  let removed = false;
  for (const containerKey of ["mcpServers", "servers"] as const) {
    const container = config[containerKey];
    if (!container || typeof container !== "object" || Array.isArray(container)) {
      continue;
    }
    const servers = container as Record<string, unknown>;
    if (!(serverKey in servers)) continue;
    delete servers[serverKey];
    removed = true;
    if (Object.keys(servers).length === 0) delete config[containerKey];
  }
  if (!removed) return false;
  await writeFile(filePath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
  return true;
 }
 /** One MCP config file this extension wrote, so uninstall can undo exactly that. */
 export interface McpInstallRecord {
  path: string;
  serverKey: string;
  /** Top-level JSON container the entry was written under. */
  format: "mcpServers" | "servers";
  /** Human label (Claude Desktop / Cursor global / ...). */
  label?: string;
  sourceVersion?: string;
 }
 /** Path to the managed MCP config install record under the agent home. */
 export function mcpInstallRecordPath(agentHome = defaultAgentHome()): string {
  return join(agentHome, "mcp-install.json");
 }
 /** Reads the managed MCP config install record, or returns an empty list. */
 export async function readMcpInstallRecord(
  agentHome = defaultAgentHome(),
 ): Promise<McpInstallRecord[]> {
  try {
    const parsed = JSON.parse(
      await readFile(mcpInstallRecordPath(agentHome), "utf8"),
    ) as { installed?: McpInstallRecord[] };
    return Array.isArray(parsed.installed) ? parsed.installed : [];
  } catch {
    return [];
  }
 }
 /** Writes the managed MCP config install record. */
 export async function writeMcpInstallRecord(
  installed: McpInstallRecord[],
  agentHome = defaultAgentHome(),
 ): Promise<void> {
  const file = mcpInstallRecordPath(agentHome);
  await mkdir(dirname(file), { recursive: true });
  await writeFile(file, JSON.stringify({ installed }, null, 2), "utf8");
 }
 export interface InstallMcpConfigOptions {
  filePath: string;
  launcher: string;
  projectDir: string;
  label?: string;
  sourceVersion?: string;
  serverKey?: string;
  agentHome?: string;
 }
 /**
 * Writes the server entry into a config file and remembers that we did, so
 * "uninstall AI Agent integration" can remove exactly what this extension
 * created without touching the user's other MCP servers.
 */
 export async function installMcpServerConfigToFile(
  options: InstallMcpConfigOptions,
 ): Promise<void> {
  const serverKey = options.serverKey ?? MCP_SERVER_KEY;
  await addMcpServerToConfigFile(
    options.filePath,
    options.launcher,
    options.projectDir,
    serverKey,
  );
  const agentHome = options.agentHome ?? defaultAgentHome();
  const path = resolve(options.filePath);
  const installed = (await readMcpInstallRecord(agentHome)).filter(
    (r) => resolve(r.path).toLowerCase() !== path.toLowerCase(),
  );
  installed.push({
    path,
    serverKey,
    format: "mcpServers",
    label: options.label,
    sourceVersion: options.sourceVersion,
  });
  await writeMcpInstallRecord(installed, agentHome);
 }
 export interface UninstallMcpConfigOptions {
  /** Also scan the conventional client paths for this project. */
  projectDir?: string | null;
  agentHome?: string;
  serverKey?: string;
 }
 /**
 * Removes the server entry from every config file this extension recorded,
 * plus the conventional client config paths for `projectDir` (which covers
 * configs written before the install record existed).
 *
 * Returns the paths that actually changed. Missing/malformed files count as
 * "nothing to remove" and are not reported.
 */
 export async function uninstallMcpServerConfigs(
  options: UninstallMcpConfigOptions = {},
 ): Promise<string[]> {
  const serverKey = options.serverKey ?? MCP_SERVER_KEY;
  const agentHome = options.agentHome ?? defaultAgentHome();
  const record = await readMcpInstallRecord(agentHome);
  const candidates = new Map<string, string>();
  for (const entry of record) {
    if (entry.serverKey && entry.serverKey !== serverKey) continue;
    candidates.set(resolve(entry.path).toLowerCase(), entry.path);
  }
  if (options.projectDir) {
    for (const target of commonMcpConfigTargets(options.projectDir)) {
      candidates.set(resolve(target.path).toLowerCase(), target.path);
    }
  }
  const changed: string[] = [];
  for (const path of candidates.values()) {
    try {
      if (await removeMcpServerFromConfigFile(path, serverKey)) changed.push(path);
    } catch {
      // Best effort; keep going through the remaining files.
    }
  }
  const changedKeys = new Set(changed.map((p) => resolve(p).toLowerCase()));
  await writeMcpInstallRecord(
    record.filter((r) => !changedKeys.has(resolve(r.path).toLowerCase())),
    agentHome,
  );
  return changed;
 }
 /** Deletes the stable MCP launcher. Returns false when nothing was removable. */
 export async function removeLauncher(agentHome = defaultAgentHome()): Promise<boolean> {
  try {
    await rm(launcherPath(agentHome), { force: true });
    return true;
  } catch {
    return false;
  }
 }
 /** Default path used for the agent home. */
 export function defaultAgentHomeForSetup(): string {
  return join(homedir(), ".ra3modxml");
@@ -9,9 +9,9 @@
 * Pure TypeScript: no VS Code dependency.
 */
-import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { defaultAgentHome } from "./snapshot";
 export const SKILL_NAME = "ra3-mod-xml";
@@ -40,19 +40,18 @@ Positive signals (any single one is enough to try the tools):
 - XML that uses \`<Includes><Include source="DATA:…" /></Includes>\` or declares
  \`xmlns="uri:ea.com:eala:asset"\`.
-Do **not** use these tools for unrelated repositories. In particular, do not
+Do **not** use these tools for unrelated repositories. SAGE-looking XML, a
-use them merely because a project contains XML, a build script, copied \`.xsd\`
+build script, copied \`.xsd\` schema files, or a folder named \`Data\` are not
-files, or a folder named \`Data\`. A file named \`CnC3Types.xsd\` refers to
+by themselves evidence of a Red Alert 3 mod project: require at least one of
-C&C3 (Tiberium Wars / Kane's Wrath) and is **not** by itself evidence of a
+the positive signals above. When the repository is not a SAGE / RA3 mod
-Red Alert 3 mod. When the repository is not a SAGE / RA3 mod project, ignore
+project, ignore this skill entirely.
 this skill entirely.
 If you are unsure whether the current project is in scope, call \`get_status\`
 first: it is cheap and reports the \`projectDir\` the index belongs to. Stop
 using the index tools when:
 - the state is \`no_index\`, or
- the reported \`projectDir\` does not match the workspace root you are working in.
+- the reported \`projectDir\` does not match the workspace you are working in.
 In those cases read the files directly instead. Never present index results
 from one project as if they belonged to another.
@@ -86,8 +85,9 @@ Work down this list and stop at the first step that works.
   stdio. Read \`~/.ra3modxml/index.json\` first: it is a small, stable
   discovery manifest listing the live instances and their project roots.
-   - If it does not exist, the extension has never been enabled for this
+   - If it does not exist, live discovery has not been enabled on this
-     project. Tell the user to open the project in VS Code and run
+     machine yet (or no VS Code window is running). Tell the user to open the
     project in VS Code and run
     "RA3 Mod XML: Enable AI Agent access…". Do not guess or search further.
   - If it exists, use the launcher at \`~/.ra3modxml/ra3-mod-xml-mcp.cmd\`
     (Windows) or \`~/.ra3modxml/ra3-mod-xml-mcp\` (elsewhere), or call the
@@ -100,18 +100,24 @@ Work down this list and stop at the first step that works.
     A CLI with the same capabilities is bundled alongside the MCP server
     (\`cli.js\` next to \`mcpServer.js\` in the extension's \`dist/agent/\`).
-     Run it with the same runtime as the launcher; \`cli.js help\` lists the
+     It is a plain Node script: run it with
-     commands. It answers from the live index when VS Code is running and
+     \`node <path-to-cli.js> <command>\`. If Node is not installed, do not
-     falls back to the last exported snapshot otherwise. Commands that need
+     install anything — run the same file with the VS Code runtime recorded in
-     element context (\`outgoing\`, \`projects\`) require the live index and will
+     the launcher instead:
-     say so explicitly instead of returning an empty result.
+     \`ELECTRON_RUN_AS_NODE=1 <runtime executable from the launcher> <path-to-cli.js> <command>\`.
     \`cli.js help\` lists the commands. The CLI answers from the live index
     when VS Code is running and falls back to the last exported snapshot
     otherwise. Commands that need element context (\`outgoing\`, \`projects\`)
     require the live index and will say so explicitly instead of returning an
     empty result.
 3. **You can write configuration, if the user agrees.** You may add the MCP
-   server to the your own harness' configuration.
+   server to your own client's configuration. Most clients only load MCP
-   Check what your own client supports (e.g. if a restart is required)
+   servers at startup, so tell the user the change takes effect in a new session;
-   before promising otherwise.
+   check what your own client supports before promising otherwise.
-If none of the steps work, say the index is unavailable and read the XML files directly.
+Never fabricate index results. If none of the steps work, say the index is
 unavailable and read the XML files directly.
 ## How to use
@@ -123,7 +129,8 @@ If none of the steps work, say the index is unavailable and read the XML files d
   - \`get_asset_references(id, type?, depth?, targetTypes?)\` for outgoing
     references (what this asset uses, and where that link is written).
   - \`list_assets_by_type(type, prefix?, limit?)\` for browsing assets.
-   - \`is_file_active(path)\` to determine whether a file is included in an indexed stream.   - \`find_define(name)\` for $DEFINE constants.
+   - \`is_file_active(path)\` to determine whether a file is included in an indexed stream.
   - \`find_define(name)\` for $DEFINE constants.
   - \`resolve_include(source)\` for Include source candidates.
 3. Asset ids are case-insensitive.
 4. If an id exists for multiple asset types, pass the type filter to avoid mixing definitions.
@@ -131,6 +138,9 @@ If none of the steps work, say the index is unavailable and read the XML files d
   results as provisional.
 6. Never read or dump the whole index snapshot; query narrowly.
 See [query-guide.md](./references/query-guide.md) for the full tool reference,
 parameter defaults and result shapes.
 ## Following references with get_asset_references
 Use \`get_asset_references\` to answer "which weapon / model / upgrade / die-object
@@ -174,8 +184,13 @@ The MCP server exposes these tools:
 - is_file_active(path)
 - find_define(name)
 - resolve_include(source)
 - list_projects()
 - get_usage_guide()
 \`get_asset_references\` and \`list_projects\` require a live index (VS Code
 running with the project indexed). All other tools also answer from the last
 exported snapshot when VS Code is closed.
 ## Result metadata
 Every query result includes an \`index\` object:
@@ -352,7 +367,105 @@ export async function uninstallSkillFromDirectory(
  await writeSkillInstallRecord(installed, agentHome);
 }
-/** Re-writes every recorded Skill copy with the current extension version. */
+/**
 * Reads the managed marker of a Skill directory.
 *
 * Returns null when the directory has no `.ra3modxml-skill.json`, or when the
 * marker does not describe that exact directory. A hand-copied or
 * third-party skill is therefore never treated as ours, which is what makes
 * uninstall/update safe.
 */
 export async function readSkillMarker(
  directory: string,
 ): Promise<SkillInstallRecord | null> {
  try {
    const parsed = JSON.parse(
      await readFile(join(directory, SKILL_MARKER_FILE), "utf8"),
    ) as SkillInstallRecord;
    if (!parsed?.path) return null;
    if (resolve(parsed.path) !== resolve(directory)) return null;
    return parsed;
  } catch {
    return null;
  }
 }
 export interface InstalledSkillStatus extends SkillInstallRecord {
  /** The recorded directory currently exists. */
  exists: boolean;
  /** The directory still carries our marker (safe to update/remove). */
  managed: boolean;
 }
 /** Status of every recorded Skill copy (drives the manage/uninstall UI). */
 export async function installedSkillStatus(
  agentHome = defaultAgentHome(),
 ): Promise<InstalledSkillStatus[]> {
  const installed = await readSkillInstallRecord(agentHome);
  const out: InstalledSkillStatus[] = [];
  for (const record of installed) {
    let exists = false;
    try {
      exists = (await stat(record.path)).isDirectory();
    } catch {
      exists = false;
    }
    const managed = exists ? (await readSkillMarker(record.path)) != null : false;
    out.push({ ...record, exists, managed });
  }
  return out;
 }
 /**
 * Removes recorded Skill copies that still carry our marker. Directories that
 * are missing, replaced by the user, or lack the marker are skipped and
 * reported instead of being deleted.
 */
 export async function uninstallRecordedSkills(
  directories: readonly string[],
  agentHome = defaultAgentHome(),
 ): Promise<{ removed: string[]; skipped: string[] }> {
  const removed: string[] = [];
  const skipped: string[] = [];
  for (const dir of directories) {
    const marker = await readSkillMarker(dir);
    if (!marker) {
      skipped.push(dir);
      continue;
    }
    try {
      await uninstallSkillFromDirectory(dir, agentHome);
      removed.push(dir);
    } catch {
      skipped.push(dir);
    }
  }
  return { removed, skipped };
 }
 /**
 * Drops record entries for directories that are already gone, without
 * touching the filesystem. Used by the uninstall UI when a recorded copy no
 * longer exists.
 */
 export async function forgetSkillInstallRecords(
  directories: readonly string[],
  agentHome = defaultAgentHome(),
 ): Promise<void> {
  const wanted = new Set(directories.map((d) => resolve(d)));
  const installed = (await readSkillInstallRecord(agentHome)).filter(
    (r) => !wanted.has(resolve(r.path)),
  );
  await writeSkillInstallRecord(installed, agentHome);
 }
 /**
 * Re-writes every recorded Skill copy with the current extension version.
 *
 * Copies that no longer carry our marker are never overwritten (that would
 * clobber user content), but stay in the record so the uninstall UI can still
 * show them. Records whose directory disappeared are dropped.
 */
 export async function syncInstalledSkills(
  sourceVersion: string,
  agentHome = defaultAgentHome(),
@@ -360,11 +473,22 @@ export async function syncInstalledSkills(
  const installed = await readSkillInstallRecord(agentHome);
  const synced: SkillInstallRecord[] = [];
  for (const record of installed) {
    let exists = false;
    try {
      exists = (await stat(record.path)).isDirectory();
    } catch {
      exists = false;
    }
    if (!exists) continue; // Nothing left to manage.
    if (!(await readSkillMarker(record.path))) {
      synced.push(record); // User-owned now: keep the record, never rewrite.
      continue;
    }
    try {
      await writeSkillTo(record.path, sourceVersion);
      synced.push({ path: record.path, sourceVersion });
    } catch {
-      // Skip unreadable/missing targets; the record will be cleaned below.
+      synced.push(record); // Keep so a later run can retry.
    }
  }
  await writeSkillInstallRecord(synced, agentHome);
@@ -30,26 +30,34 @@ import {
  writeSnapshotFile,
 } from "./agent/snapshot";
 import {
  addMcpServerToConfigFile,
  claudeDesktopConfigPath,
  cursorGlobalConfigPath,
  cursorProjectConfigPath,
  installMcpServerConfigToFile,
  launcherPath,
  mcpConfigJson,
  removeLauncher,
  uninstallMcpServerConfigs,
  writeLauncher,
 } from "./agent/setup";
 import {
  SKILL_NAME,
  agentsSkillsDirForUser,
  claudeSkillsDirForUser,
  forgetSkillInstallRecords,
  installSkillToDirectories,
  installedSkillStatus,
  readSkillInstallRecord,
-  writeSkillInstallRecord,
+  syncInstalledSkills,
-  writeSkillTo,
+  uninstallRecordedSkills,
 } from "./agent/skill";
 import {
  shouldOfferAgentOnboarding,
  type AgentOnboardingState,
 } from "./agent/onboarding";
 import { startLocalServer, type LocalServerHandle } from "./agent/localServer";
 import { parseLoadedXml } from "./agent/forwardRefs";
 import {
  clearEndpoint,
  clearEndpointForProject,
  writeEndpoint,
  writeEndpointForProject,
@@ -58,6 +66,7 @@ import {
  clearInstance,
  makeInstanceId,
  pruneInstances,
  refreshDiscovery,
  writeInstance,
  writeManifest,
 } from "./agent/instances";
@@ -136,6 +145,10 @@ export function activate(context: vscode.ExtensionContext): void {
    ws.log("[codelens] retry started");
  };
  ws.onBuildStart = startCodeLensRetry;
  /** Running extension version (used by the agent onboarding / upgrade sync). */
  const extensionVersion = String(
    (context.extension.packageJSON as { version?: string }).version ?? "dev",
  );
  // Coalesced agent snapshot refresh: after AI Agent access is enabled, keep
  // the external snapshot current without writing on every intermediate
  // rebuild. The timer only fires after a quiet period following a complete,
@@ -144,6 +157,52 @@ export function activate(context: vscode.ExtensionContext): void {
    "ra3modxml.agentAccessEnabled",
    false,
  );
  const AGENT_ONBOARDING_KEY = "ra3modxml.agentOnboarding";
  /** Session guard: one notification at most per activation. */
  let agentOnboardingChecked = false;
  /**
   * One-time introduction of the AI Agent feature. Shown after the first
   * index for this workspace, once per machine (see agent/onboarding.ts for
   * the anti-nag rules). Choosing an action is optional and silent.
   */
  const maybeOfferAgentOnboarding = async (): Promise<void> => {
    if (agentOnboardingChecked) return;
    if (!ws.activeIndex()) return;
    const state = context.globalState.get<AgentOnboardingState>(
      AGENT_ONBOARDING_KEY,
    );
    if (!shouldOfferAgentOnboarding(state, extensionVersion)) {
      agentOnboardingChecked = true;
      return;
    }
    agentOnboardingChecked = true;
    const enable = t("Enable AI Agent access…");
    const learnMore = t("Learn more");
    const never = t("Don't show again");
    const pick = await vscode.window.showInformationMessage(
      t(
        "RA3 Mod XML: this version can expose the project's asset index to AI agents (MCP + Agent Skill). Enable it?",
      ),
      enable,
      learnMore,
      never,
    );
    // Whatever the user chose (including ignoring the message), remember that
    // this version already informed them so it never becomes a recurring nag.
    await context.globalState.update(AGENT_ONBOARDING_KEY, {
      informedVersion: extensionVersion,
      dismissed: pick === never,
    } satisfies AgentOnboardingState);
    if (pick === enable) {
      void vscode.commands.executeCommand("ra3modxml.enableAgentAccess");
    } else if (pick === learnMore) {
      void vscode.env.openExternal(
        vscode.Uri.parse(
          "https://github.com/RA3CoronaDevelopers/Ra3ModXmlExt#ai-agent-access",
        ),
      );
    }
  };
  const AGENT_SNAPSHOT_QUIET_MS = 5000;
  let agentSnapshotTimer: ReturnType<typeof setTimeout> | null = null;
  const scheduleAgentSnapshot = (): void => {
@@ -270,8 +329,11 @@ export function activate(context: vscode.ExtensionContext): void {
    }
    agentEndpointProjects.clear();
    await clearInstance(agentInstanceId).catch(() => undefined);
-    await clearEndpoint().catch(() => undefined);
+    // Other VS Code windows may still be serving an index. Re-derive the
-    await writeManifest([]).catch(() => undefined);
+    // legacy global pointer and the merged manifest from the surviving
    // instance files instead of clearing them, so closing this window never
    // hides a still-running window from agents reading ~/.ra3modxml/index.json.
    await refreshDiscovery().catch(() => undefined);
  };
  /**
   * Republishes this window's endpoint/instance files for every project it now
@@ -335,6 +397,7 @@ export function activate(context: vscode.ExtensionContext): void {
    }
    scheduleAgentSnapshot();
    void refreshAgentEndpoints();
    void maybeOfferAgentOnboarding();
    for (const doc of vscode.workspace.textDocuments) {
      if (doc.languageId === "xml") void diagnostics.update(doc);
    }
@@ -600,25 +663,46 @@ export function activate(context: vscode.ExtensionContext): void {
        );
        if (pick?.id === "skill") {
          const target = agentsSkillsDirForUser();
-          await writeSkillTo(target, version);
+          const installed = await installSkillToDirectories([target], version);
-          const installed = await readSkillInstallRecord();
+          if (installed.length) {
          if (!installed.some((r) => r.path === target)) installed.push({ path: target, sourceVersion: version });
          await writeSkillInstallRecord(installed);
            void vscode.window.showInformationMessage(
              t("RA3 Mod XML Agent Skill installed to {0}", target),
            );
          } else {
            void vscode.window.showErrorMessage(
              t("RA3 Mod XML: could not write the Agent Skill to {0}", target),
            );
          }
        } else if (pick?.id === "claude") {
-          await addMcpServerToConfigFile(claudeDesktopConfigPath(), launcher.path, projectDir);
+          await installMcpServerConfigToFile({
            filePath: claudeDesktopConfigPath(),
            launcher: launcher.path,
            projectDir,
            label: "Claude Desktop",
            sourceVersion: version,
          });
          void vscode.window.showInformationMessage(
            t("RA3 Mod XML MCP config written to {0}", claudeDesktopConfigPath()),
          );
        } else if (pick?.id === "cursor-global") {
-          await addMcpServerToConfigFile(cursorGlobalConfigPath(), launcher.path, projectDir);
+          await installMcpServerConfigToFile({
            filePath: cursorGlobalConfigPath(),
            launcher: launcher.path,
            projectDir,
            label: "Cursor (global)",
            sourceVersion: version,
          });
          void vscode.window.showInformationMessage(
            t("RA3 Mod XML MCP config written to {0}", cursorGlobalConfigPath()),
          );
        } else if (pick?.id === "cursor-project") {
-          await addMcpServerToConfigFile(cursorProjectConfigPath(projectDir), launcher.path, projectDir);
+          await installMcpServerConfigToFile({
            filePath: cursorProjectConfigPath(projectDir),
            launcher: launcher.path,
            projectDir,
            label: "Cursor (project)",
            sourceVersion: version,
          });
          void vscode.window.showInformationMessage(
            t("RA3 Mod XML MCP config written to {0}", cursorProjectConfigPath(projectDir)),
          );
@@ -640,51 +724,238 @@ export function activate(context: vscode.ExtensionContext): void {
  );
  context.subscriptions.push(
    vscode.commands.registerCommand("ra3modxml.installAgentSkill", async () => {
-      const idx = ws.activeIndex();
+      // Installing the Skill only writes text files; it does not need an
-      if (!idx) {
+      // index, so users can prepare their agent tooling before the first build.
-        void vscode.window.showInformationMessage(
+      const projectDir = ws.projectRoot;
          t(
            "RA3 Mod XML: no index available yet. Open and index a project before installing the Agent Skill.",
          ),
        );
        return;
      }
      const projectDir = idx.projectDir;
      const version = String((context.extension.packageJSON as { version?: string }).version ?? "dev");
-      const choices = [
+      const choices: Array<{
        label: string;
        description: string;
        target: string | null;
        picked?: boolean;
      }> = [
        {
          label: t("Default (~/.agents/skills)"),
          description: agentsSkillsDirForUser(),
-          path: agentsSkillsDirForUser(),
+          target: agentsSkillsDirForUser(),
          picked: true,
        },
        {
          label: t("Claude Code (~/.claude/skills)"),
          description: claudeSkillsDirForUser(),
-          path: claudeSkillsDirForUser(),
+          target: claudeSkillsDirForUser(),
        },
      ];
      if (projectDir) {
        choices.push(
          {
            label: t("Current project .agents/skills"),
            description: join(projectDir, ".agents", "skills", SKILL_NAME),
-          path: join(projectDir, ".agents", "skills", SKILL_NAME),
+            target: join(projectDir, ".agents", "skills", SKILL_NAME),
          },
          {
            label: t("Current project .claude/skills"),
            description: join(projectDir, ".claude", "skills", SKILL_NAME),
-          path: join(projectDir, ".claude", "skills", SKILL_NAME),
+            target: join(projectDir, ".claude", "skills", SKILL_NAME),
          },
-      ];
+        );
      }
      choices.push({
        label: t("Choose a custom folder…"),
        description: t("The skill is installed as <folder>/{0}", SKILL_NAME),
        target: null,
      });
      const picked = await vscode.window.showQuickPick(choices, {
        canPickMany: true,
        placeHolder: t("Select Agent Skill install locations"),
      });
      if (!picked?.length) return;
-      const succeeded = await installSkillToDirectories(
+
-        picked.map((p) => p.path),
+      const targets = picked
-        version,
+        .map((p) => p.target)
        .filter((p): p is string => p != null);
      if (picked.some((p) => p.target == null)) {
        const folder = await vscode.window.showOpenDialog({
          canSelectFiles: false,
          canSelectFolders: true,
          canSelectMany: false,
          openLabel: t("Choose a skill folder"),
          title: t("Choose the folder that should contain the {0} skill", SKILL_NAME),
        });
        const dir = folder?.[0]?.fsPath;
        if (dir) targets.push(join(dir, SKILL_NAME));
      }
      if (!targets.length) return;
      const succeeded = await installSkillToDirectories(targets, version);
      const failed = targets.length - succeeded.length;
      if (!succeeded.length) {
        void vscode.window.showErrorMessage(
          t("RA3 Mod XML: could not write the Agent Skill (0 of {0} locations).", targets.length),
        );
        return;
      }
      void vscode.window.showInformationMessage(
-        t("RA3 Mod XML Agent Skill installed to {0} location(s).", succeeded.length),
+        failed > 0
          ? t(
              "RA3 Mod XML Agent Skill installed to {0} location(s); {1} failed.",
              succeeded.length,
              failed,
            )
          : t("RA3 Mod XML Agent Skill installed to {0} location(s).", succeeded.length),
        t("Show installed skills"),
      ).then((pick) => {
        if (pick) void vscode.commands.executeCommand("ra3modxml.uninstallAgentSkill");
      });
    }),
  );
  context.subscriptions.push(
    vscode.commands.registerCommand("ra3modxml.uninstallAgentSkill", async () => {
      const installed = await installedSkillStatus();
      if (!installed.length) {
        void vscode.window.showInformationMessage(
          t("RA3 Mod XML: no recorded Agent Skill installation to remove."),
        );
        return;
      }
      const picks = await vscode.window.showQuickPick(
        installed.map((entry) => ({
          label: entry.path,
          description: !entry.exists
            ? t("missing — will be dropped from the record")
            : entry.managed
              ? t("installed by this extension (v{0})", entry.sourceVersion)
              : t("not managed by this extension — will be skipped"),
          detail: entry.managed || !entry.exists ? undefined : t("No RA3 Mod XML skill marker found; remove it manually if you want it gone."),
          path: entry.path,
          picked: entry.exists && entry.managed,
        })),
        {
          canPickMany: true,
          placeHolder: t("Select Agent Skill installations to remove"),
        },
      );
      if (!picks?.length) return;
      const selected = picks.map((p) => p.path);
      // A record whose directory is already gone only needs its record entry
      // dropped; a managed directory is deleted by uninstallRecordedSkills.
      const missing = installed
        .filter((e) => selected.includes(e.path) && !e.exists)
        .map((e) => e.path);
      const { removed, skipped } = await uninstallRecordedSkills(
        selected.filter((p) => !missing.includes(p)),
      );
      if (missing.length) {
        await forgetSkillInstallRecords(missing);
      }
      void vscode.window.showInformationMessage(
        skipped.length
          ? t(
              "RA3 Mod XML: removed {0} Agent Skill installation(s); {1} skipped (not managed by this extension).",
              removed.length,
              skipped.length,
            )
          : t("RA3 Mod XML: removed {0} Agent Skill installation(s).", removed.length),
      );
    }),
  );
  context.subscriptions.push(
    vscode.commands.registerCommand("ra3modxml.disableAgentAccess", async () => {
      agentAccessEnabled = false;
      await context.workspaceState.update("ra3modxml.agentAccessEnabled", false);
      // Stops the loopback server and removes this window's instance /
      // endpoint files; discovery files are re-derived from other windows.
      await stopAgentLocalServer();
      ws.log("[agent] AI Agent access disabled for this workspace");
      void vscode.window.showInformationMessage(
        t(
          "RA3 Mod XML: AI Agent access disabled for this workspace. Installed skills and MCP client configurations were kept.",
        ),
        t("Uninstall AI Agent integration…"),
      ).then((pick) => {
        if (pick) void vscode.commands.executeCommand("ra3modxml.uninstallAgentIntegration");
      });
    }),
  );
  context.subscriptions.push(
    vscode.commands.registerCommand("ra3modxml.uninstallAgentIntegration", async () => {
      const projectDir = ws.projectRoot;
      const skills = await installedSkillStatus();
      const removableSkills = skills.filter((s) => s.exists);
      const live = agentAccessEnabled || agentLocalServer != null;
      const choices: Array<{
        label: string;
        description?: string;
        id: "disable" | "skills" | "mcp" | "launcher";
        picked?: boolean;
      }> = [];
      if (live) {
        choices.push({
          label: t("Stop live AI Agent access in this window"),
          id: "disable",
          picked: true,
        });
      }
      if (removableSkills.length) {
        choices.push({
          label: t("Remove installed Agent Skills"),
          description: t("{0} location(s)", removableSkills.length),
          id: "skills",
          picked: true,
        });
      }
      choices.push(
        {
          label: t("Remove MCP client configuration entries"),
          description: t("Claude Desktop / Cursor and files recorded by this extension"),
          id: "mcp",
          picked: true,
        },
        {
          label: t("Remove the stable MCP launcher"),
          description: launcherPath(),
          id: "launcher",
        },
      );
      const picked = await vscode.window.showQuickPick(choices, {
        canPickMany: true,
        placeHolder: t("Select what to remove (nothing is removed until you confirm)"),
      });
      if (!picked?.length) return;
      const confirm = await vscode.window.showWarningMessage(
        t("Remove the selected AI Agent components?"),
        { modal: true },
        t("Remove"),
      );
      if (confirm !== t("Remove")) return;
      const summary: string[] = [];
      if (picked.some((p) => p.id === "disable")) {
        agentAccessEnabled = false;
        await context.workspaceState.update("ra3modxml.agentAccessEnabled", false);
        await stopAgentLocalServer();
        summary.push(t("live access stopped"));
      }
      if (picked.some((p) => p.id === "skills")) {
        const { removed, skipped } = await uninstallRecordedSkills(
          removableSkills.filter((s) => s.managed).map((s) => s.path),
        );
        summary.push(t("{0} skill installation(s) removed", removed.length));
        if (skipped.length) {
          summary.push(t("{0} unmanaged skill folder(s) skipped", skipped.length));
        }
      }
      if (picked.some((p) => p.id === "mcp")) {
        const changed = await uninstallMcpServerConfigs({ projectDir });
        summary.push(t("MCP config removed from {0} file(s)", changed.length));
      }
      if (picked.some((p) => p.id === "launcher")) {
        await removeLauncher();
        summary.push(t("MCP launcher removed"));
      }
      void vscode.window.showInformationMessage(
        t("RA3 Mod XML AI Agent cleanup: {0}.", summary.join("; ")),
      );
    }),
  );
@@ -738,6 +1009,25 @@ export function activate(context: vscode.ExtensionContext): void {
    void startAgentLocalServer();
    void refreshLaunchers();
  }
  /**
   * Keeps recorded Skill copies in sync after an extension upgrade. Only runs
   * when a recorded copy is at a different version, and never rewrites a
   * directory that no longer carries our marker.
   */
  void (async () => {
    try {
      const installed = await readSkillInstallRecord();
      if (!installed.some((r) => r.sourceVersion !== extensionVersion)) return;
      const synced = await syncInstalledSkills(extensionVersion);
      ws.log(
        `[agent] synced ${synced.length} installed skill(s) to v${extensionVersion}`,
      );
    } catch {
      // Best effort: the install/uninstall commands can always repair this.
    }
  })();
  void sdkSetup.evaluate(ws);
  void ws.initialize().then(() => {
    void sdkSetup.evaluate(ws);
@@ -14,9 +14,11 @@ import {
  pruneInstances,
  readInstances,
  readManifest,
  refreshDiscovery,
  writeInstance,
  writeManifest,
 } from "../out/agent/instances.js";
 import { endpointPath, readEndpoint } from "../out/agent/endpoint.js";
 function instanceHome() {
  return mkdtempSync(join(tmpdir(), "ra3-instances-"));
@@ -166,3 +168,52 @@ test("makeInstanceId is unique across rapid calls", () => {
  assert.equal(ids.size, 200);
  for (const id of ids) assert.ok(id.startsWith("1234-"), id);
 });
 test("refreshDiscovery keeps surviving windows discoverable", async () => {
  const home = instanceHome();
  try {
    const mine = makeInstance("mine");
    const other = {
      ...makeInstance("other"),
      url: "http://127.0.0.1:19999",
      token: "tok-other",
      projectDir: "D:/Mods/Beta",
      projects: ["D:/Mods/Beta"],
    };
    await writeInstance(mine, home);
    await writeInstance(other, home);
    // This window closes: only its own instance file goes away.
    await clearInstance(mine.instanceId, home);
    const manifest = await refreshDiscovery(home);
    assert.deepEqual(manifest.projects, ["D:/Mods/Beta"]);
    assert.deepEqual(manifest.instances.map((i) => i.instanceId), ["other"]);
    // The legacy global pointer must follow the survivor, not be deleted.
    const endpoint = await readEndpoint(home);
    assert.equal(endpoint?.url, other.url);
    assert.equal(endpoint?.token, other.token);
    assert.equal(existsSync(endpointPath(home)), true);
    // The merged manifest on disk must agree with the returned value.
    const reread = await readManifest(home);
    assert.deepEqual(reread?.instances.map((i) => i.instanceId), ["other"]);
  } finally {
    rmSync(home, { recursive: true, force: true });
  }
 });
 test("refreshDiscovery clears the global pointer when the last window closes", async () => {
  const home = instanceHome();
  try {
    await writeInstance(makeInstance("only"), home);
    await clearInstance("only", home);
    const manifest = await refreshDiscovery(home);
    assert.deepEqual(manifest.instances, []);
    assert.deepEqual(manifest.projects, []);
    assert.equal(existsSync(endpointPath(home)), false);
  } finally {
    rmSync(home, { recursive: true, force: true });
  }
 });
@@ -1,12 +1,18 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
  addMcpServerToConfigFile,
  installMcpServerConfigToFile,
  launcherPath,
  mcpConfigJson,
  mcpServerConfig,
  readMcpInstallRecord,
  removeLauncher,
  removeMcpServerFromConfigFile,
  uninstallMcpServerConfigs,
 } from "../out/agent/setup.js";
 test("mcpServerConfig and mcpConfigJson use the stable launcher", () => {
@@ -34,3 +40,99 @@ test("addMcpServerToConfigFile creates and merges config", async () => {
    rmSync(dir, { recursive: true, force: true });
  }
 });
 test("removeMcpServerFromConfigFile removes only our entry and preserves the rest", async () => {
  const dir = mkdtempSync(join(tmpdir(), "ra3-setup-remove-"));
  try {
    const file = join(dir, "mcp.json");
    writeFileSync(
      file,
      JSON.stringify(
        {
          mcpServers: {
            other: { command: "x" },
            "ra3-mod-xml": { command: "launcher", args: ["--project", "D:/Mods/A"] },
          },
          someOtherKey: 1,
        },
        null,
        2,
      ),
    );
    assert.equal(await removeMcpServerFromConfigFile(file), true);
    const parsed = JSON.parse(readFileSync(file, "utf8"));
    assert.ok(parsed.mcpServers.other);
    assert.equal(parsed.mcpServers["ra3-mod-xml"], undefined);
    assert.equal(parsed.someOtherKey, 1);
    // Nothing left to remove: second call is a no-op.
    assert.equal(await removeMcpServerFromConfigFile(file), false);
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
 });
 test("removeMcpServerFromConfigFile handles VS Code's servers key and drops empty containers", async () => {
  const dir = mkdtempSync(join(tmpdir(), "ra3-setup-vscode-"));
  try {
    const file = join(dir, "mcp.json");
    writeFileSync(
      file,
      JSON.stringify({ servers: { "ra3-mod-xml": { command: "x" } }, inputs: [] }, null, 2),
    );
    assert.equal(await removeMcpServerFromConfigFile(file), true);
    const parsed = JSON.parse(readFileSync(file, "utf8"));
    assert.equal(parsed.servers, undefined);
    assert.deepEqual(parsed.inputs, []);
    // A missing file is "nothing to remove", not an error.
    assert.equal(await removeMcpServerFromConfigFile(join(dir, "nope.json")), false);
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
 });
 test("installed MCP configs can be uninstalled through the install record", async () => {
  const home = mkdtempSync(join(tmpdir(), "ra3-setup-home-"));
  const dir = mkdtempSync(join(tmpdir(), "ra3-setup-record-"));
  try {
    const file = join(dir, "mcp.json");
    await installMcpServerConfigToFile({
      filePath: file,
      launcher: "C:/launcher.cmd",
      projectDir: "D:/Mods/A",
      label: "Test client",
      sourceVersion: "1.2.3",
      agentHome: home,
    });
    const record = await readMcpInstallRecord(home);
    assert.equal(record.length, 1);
    assert.equal(record[0].label, "Test client");
    assert.equal(record[0].serverKey, "ra3-mod-xml");
    assert.equal(record[0].sourceVersion, "1.2.3");
    const removed = await uninstallMcpServerConfigs({ agentHome: home });
    assert.deepEqual(removed, [file]);
    assert.equal((await readMcpInstallRecord(home)).length, 0);
    // Our entry was the only server: the empty container is dropped.
    assert.deepEqual(JSON.parse(readFileSync(file, "utf8")), {});
  } finally {
    rmSync(home, { recursive: true, force: true });
    rmSync(dir, { recursive: true, force: true });
  }
 });
 test("removeLauncher deletes the stable launcher and tolerates its absence", async () => {
  const home = mkdtempSync(join(tmpdir(), "ra3-setup-launcher-"));
  try {
    writeFileSync(launcherPath(home), "dummy", "utf8");
    assert.equal(existsSync(launcherPath(home)), true);
    assert.equal(await removeLauncher(home), true);
    assert.equal(existsSync(launcherPath(home)), false);
    // force: true, so removing it again is still a success.
    assert.equal(await removeLauncher(home), true);
  } finally {
    rmSync(home, { recursive: true, force: true });
  }
 });
@@ -1,13 +1,18 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
  SKILL_MARKER_FILE,
  forgetSkillInstallRecords,
  installSkillToDirectories,
  installedSkillStatus,
  readSkillInstallRecord,
  readSkillMarker,
  uninstallRecordedSkills,
  uninstallSkillFromDirectory,
  writeSkillInstallRecord,
  writeSkillTo,
 } from "../out/agent/skill.js";
@@ -22,6 +27,27 @@ test("writeSkillTo creates SKILL.md and avoids project-doc noise", async () => {
    const content = readFileSync(join(skillDir, "SKILL.md"), "utf8");
    assert.ok(content.includes("find_asset"));
    assert.ok(!content.includes("codebase-navigation-guide"));
    // The bundled reference must list every tool the MCP server exposes.
    const guide = readFileSync(
      join(skillDir, "references", "query-guide.md"),
      "utf8",
    );
    for (const tool of [
      "get_status",
      "find_asset",
      "find_references",
      "get_asset_references",
      "list_assets_by_type",
      "is_file_active",
      "find_define",
      "resolve_include",
      "list_projects",
      "get_usage_guide",
    ]) {
      assert.ok(guide.includes(tool), `query-guide.md must mention ${tool}`);
    }
    assert.equal(guide.includes("CnC3Types.xsd"), false);
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
@@ -44,9 +70,10 @@ test("SKILL.md scopes itself to SAGE/RA3 projects and warns off others", async (
    assert.match(content, /Do \*\*not\*\* use these tools for unrelated repositories/);
    assert.ok(content.includes("get_status"));
    assert.ok(content.includes("projectDir"));
-    // The CnC3 red herring is called out explicitly.
+    // `CnC3Types.xsd` is the shared SAGE base schema (the RA3 Mod SDK ships it
-    assert.ok(content.includes("CnC3Types.xsd"));
+    // too), so it must not be presented as evidence in either direction.
-    assert.ok(content.includes("C&C3"));
+    assert.equal(content.includes("CnC3Types.xsd"), false);
    assert.equal(content.includes("Tiberium Wars"), false);
    // Second-phase capability must be documented.
    assert.ok(content.includes("get_asset_references"));
@@ -69,12 +96,20 @@ test("SKILL.md explains how to reach the index without MCP", async () => {
    // The launcher and the bundled CLI are both mentioned.
    assert.ok(content.includes("ra3-mod-xml-mcp"));
    assert.ok(content.includes("cli.js"));
    // The CLI is a Node script, and the skill must say how to run it when Node
    // is not installed (VS Code's Electron binary as Node).
    assert.ok(content.includes("ELECTRON_RUN_AS_NODE=1"));
    // The stdio escape hatch must be shown, since it needs no setup at all.
    assert.ok(content.includes("tools/call"));
    // It must not pretend configuring a client takes effect immediately.
    assert.ok(content.includes("new session"));
    // And it must refuse to invent results.
    assert.match(content, /Never fabricate index results/);
    // The bundled tool reference must be linked from SKILL.md, otherwise
    // skills-compatible clients never load it (resources load on demand).
    assert.ok(content.includes("./references/query-guide.md"));
    // The tool list must stay a real list; a merged bullet hides an item.
    assert.match(content, /indexed stream\.\n\s+- `find_define\(name\)`/);
    // Instructions must not send it looking for project-specific docs.
    assert.equal(content.includes("codebase-navigation-guide"), false);
  } finally {
@@ -101,3 +136,94 @@ test("installSkillToDirectories records managed copies and uninstall removes the
    rmSync(dir, { recursive: true, force: true });
  }
 });
 test("readSkillMarker requires our marker to describe the same directory", async () => {
  const dir = mkdtempSync(join(tmpdir(), "ra3-skill-marker-"));
  try {
    const managed = join(dir, "managed");
    await writeSkillTo(managed, "1.0.0");
    const marker = await readSkillMarker(managed);
    assert.equal(marker?.sourceVersion, "1.0.0");
    // A hand-copied skill without a marker is never treated as ours.
    const foreign = join(dir, "foreign");
    mkdirSync(foreign, { recursive: true });
    writeFileSync(join(foreign, "SKILL.md"), "user content", "utf8");
    assert.equal(await readSkillMarker(foreign), null);
    // A marker pointing at another directory must not make this one managed.
    const spoofed = join(dir, "spoofed");
    mkdirSync(spoofed, { recursive: true });
    writeFileSync(
      join(spoofed, SKILL_MARKER_FILE),
      JSON.stringify({ path: managed, sourceVersion: "1.0.0" }),
      "utf8",
    );
    assert.equal(await readSkillMarker(spoofed), null);
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
 });
 test("uninstallRecordedSkills removes managed copies and skips user-owned ones", async () => {
  const home = mkdtempSync(join(tmpdir(), "ra3-skill-uninstall-home-"));
  const dir = mkdtempSync(join(tmpdir(), "ra3-skill-uninstall-"));
  try {
    const managed = join(dir, "managed");
    await installSkillToDirectories([managed], "1.0.0", home);
    // A directory the user owns: recorded, but with no marker of ours.
    const foreign = join(dir, "foreign");
    mkdirSync(foreign, { recursive: true });
    writeFileSync(join(foreign, "SKILL.md"), "user content", "utf8");
    const record = await readSkillInstallRecord(home);
    record.push({ path: foreign, sourceVersion: "0.0.0" });
    await writeSkillInstallRecord(record, home);
    const status = await installedSkillStatus(home);
    assert.equal(status.length, 2);
    assert.deepEqual(
      status.map((s) => ({ path: s.path, managed: s.managed })),
      [
        { path: managed, managed: true },
        { path: foreign, managed: false },
      ],
    );
    const { removed, skipped } = await uninstallRecordedSkills(
      [managed, foreign],
      home,
    );
    assert.deepEqual(removed, [managed]);
    assert.deepEqual(skipped, [foreign]);
    assert.equal(existsSync(managed), false);
    assert.equal(readFileSync(join(foreign, "SKILL.md"), "utf8"), "user content");
    // The unmanaged entry stays in the record so it can still be reviewed.
    const after = await readSkillInstallRecord(home);
    assert.deepEqual(after.map((r) => r.path), [foreign]);
  } finally {
    rmSync(home, { recursive: true, force: true });
    rmSync(dir, { recursive: true, force: true });
  }
 });
 test("installedSkillStatus and forgetSkillInstallRecords handle a missing directory", async () => {
  const home = mkdtempSync(join(tmpdir(), "ra3-skill-missing-home-"));
  const dir = mkdtempSync(join(tmpdir(), "ra3-skill-missing-"));
  try {
    const gone = join(dir, "gone");
    await writeSkillInstallRecord([{ path: gone, sourceVersion: "1.0.0" }], home);
    const status = await installedSkillStatus(home);
    assert.equal(status.length, 1);
    assert.equal(status[0].exists, false);
    assert.equal(status[0].managed, false);
    await forgetSkillInstallRecords([gone], home);
    assert.equal((await readSkillInstallRecord(home)).length, 0);
  } finally {
    rmSync(home, { recursive: true, force: true });
    rmSync(dir, { recursive: true, force: true });
  }
 });
@@ -0,0 +1,64 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import {
  AGENT_FEATURE_VERSION,
  compareVersions,
  shouldOfferAgentOnboarding,
 } from "../out/agent/onboarding.js";
 test("compareVersions orders dotted numeric versions", () => {
  assert.equal(compareVersions("0.1.26", "0.1.26"), 0);
  assert.equal(compareVersions("0.1.26", "0.1.25"), 1);
  assert.equal(compareVersions("0.1.25", "0.1.26"), -1);
  assert.equal(compareVersions("0.1.26", "0.1"), 1);
  assert.equal(compareVersions("0.2", "0.1.99"), 1);
  assert.equal(compareVersions("1.0.0", "2.0.0"), -1);
  assert.equal(compareVersions("0.1.26-beta", "0.1.26"), 0);
  assert.equal(compareVersions("dev", "0.1.25"), -1);
 });
 test("a fresh install is offered the AI Agent introduction once", () => {
  assert.equal(shouldOfferAgentOnboarding(undefined, "0.1.26"), true);
  assert.equal(shouldOfferAgentOnboarding({}, "0.1.26"), true);
 });
 test("upgrading from before the feature informs once", () => {
  assert.equal(
    shouldOfferAgentOnboarding({ informedVersion: "0.1.25" }, "0.1.26"),
    true,
  );
  // ...but not again on the same version or later ones.
  assert.equal(
    shouldOfferAgentOnboarding({ informedVersion: "0.1.26" }, "0.1.26"),
    false,
  );
  assert.equal(
    shouldOfferAgentOnboarding({ informedVersion: "0.1.26" }, "0.1.27"),
    false,
  );
 });
 test("upgrading from a build that already had the feature stays silent", () => {
  // 0.1.26 introduced it; someone informed on 0.1.26 must not be re-prompted.
  assert.equal(
    shouldOfferAgentOnboarding({ informedVersion: "0.1.26" }, "0.1.30"),
    false,
  );
 });
 test("dismissed state suppresses the prompt forever", () => {
  assert.equal(
    shouldOfferAgentOnboarding(
      { informedVersion: "0.1.20", dismissed: true },
      "0.1.26",
    ),
    false,
  );
  assert.equal(
    shouldOfferAgentOnboarding(
      { informedVersion: AGENT_FEATURE_VERSION, dismissed: true },
      "0.1.30",
    ),
    false,
  );
 });