ai agent

README.md

@@ -155,6 +155,49 @@ to an empty string opts out of SDK features permanently.
 * `RA3 Mod XML: Show cache report`
 * `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: Install Agent Skill…`
+* `RA3 Mod XML: Export AI Agent index snapshot`
+
+## AI Agent Access
+
+The extension can expose its semantic asset index to AI Agent clients through
+a local, read-only MCP (Model Context Protocol) server. This is optional and
+does not modify `PATH` or install global commands.
+
+Run:
+
+`RA3 Mod XML: Enable AI Agent access…`
+
+The command:
+
+1. Exports a stable index snapshot for the active project.
+2. Creates a stable launcher under `~/.ra3modxml/`.
+3. Starts a local read-only query server while VS Code is running.
+4. Offers to:
+   * install the `ra3-mod-xml` Agent Skill to `~/.agents/skills/` (and
+     optionally to Claude Code or project-local skill directories),
+   * write the MCP client configuration for Claude Desktop or Cursor,
+   * copy a generic MCP configuration block.
+
+The MCP server prefers the live in-memory index while the extension is
+running and falls back to the last exported snapshot when VS Code is closed.
+The exposed tools include asset lookup, incoming semantic references,
+**outgoing reference edges** (`get_asset_references`: which assets an asset
+uses, through which element/attribute, and where in the XML), active-file
+checks, `$DEFINE` lookup, and Include source resolution.
+
+`get_asset_references` follows `inheritFrom` ancestors and marks the
+ancestor's entries with `definedIn`, so "this unit has no `WeaponSetUpdate`,
+but the base unit it inherits from does" is answerable in a single call. It is
+bounded by `depth` (default 1, max 3), `targetTypes` and `maxEdges`, and
+reports truncation instead of silently dropping results.
+
+Discovery is per project (`~/.ra3modxml/endpoints/<project>.json`), so several
+VS Code windows can enable agent access at the same time without shadowing each
+other, and a client can never be silently answered from a different project.
+
+See `docs/ai-agent-integration-plan.md` for the full design and progress.
 
 ## Requirements
 

README.zh-CN.md

@@ -152,6 +152,35 @@
 * `RA3 Mod XML: Show cache report`（显示缓存报告）
 * `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: Install Agent Skill…`（安装 Agent Skill…）
+* `RA3 Mod XML: Export AI Agent index snapshot`（导出 AI Agent 索引快照）
+
+## AI Agent 访问
+
+扩展可以通过本地只读 MCP（Model Context Protocol）Server，把语义索引提供给 AI Agent 使用。该功能可选，不会修改 `PATH`，也不会注册全局命令。
+
+运行：
+
+`RA3 Mod XML: Enable AI Agent access…`
+
+该命令会：
+
+1. 为当前项目导出稳定的索引快照；
+2. 在 `~/.ra3modxml/` 下创建稳定 launcher；
+3. 在 VS Code 运行期间启动本地只读查询服务；
+4. 让用户选择：
+   * 安装 `ra3-mod-xml` Agent Skill 到 `~/.agents/skills/`（也可选择 Claude Code 或项目级目录）；
+   * 写入 Claude Desktop / Cursor 的 MCP 配置；
+   * 复制通用 MCP 配置。
+
+MCP Server 在扩展运行时优先查询内存中的实时索引；扩展关闭后回退到最近一次导出的快照。暴露的工具包括资产定义查询、语义引用查询、**正向引用边**（`get_asset_references`：该资产用了哪些资产、通过哪个元素/属性、写在 XML 的哪一行）、文件是否有效 include、`$DEFINE` 查询以及 Include source 解析。
+
+`get_asset_references` 会沿 `inheritFrom` 祖先链遍历，并用 `definedIn` 标出条目实际写在哪个祖先的文件里，因此"这个单位自己没有 `WeaponSetUpdate`，但它继承的基础单位有"可以在一次调用里回答。它受 `depth`（默认 1，上限 3）、`targetTypes` 与 `maxEdges` 三重限制，并在截断时显式报告，而不是静默丢弃结果。
+
+Endpoint 按项目存放（`~/.ra3modxml/endpoints/<project>.json`），因此多个 VS Code 窗口可以同时启用 AI Agent 访问而不互相覆盖，客户端也不会被静默地用另一个项目的数据回答。
+
+完整设计与进度见 `docs/ai-agent-integration-plan.md`。
 
 ## 环境要求
 

docs/ai-agent-integration-plan.md

@@ -0,0 +1,773 @@
+# RA3 Mod XML AI Agent 接入计划与进度追踪
+
+> 状态：实施中  
+> 创建时间：2026-09-09  
+> 目标：让 AI Agent / 其他工具能够方便、可靠地使用 RA3 Mod XML 扩展构建的语义索引。
+
+---
+
+## 进度追踪
+
+| 阶段 | 内容 | 状态 |
+|---|---|---|
+| Phase 0 | 计划与进度文件 | ✅ 完成 |
+| Phase 1 | 外部快照格式与导出命令 | ✅ 完成 |
+| Phase 2 | 查询核心与 CLI | ✅ 完成 |
+| Phase 3 | MCP Server | ✅ 完成（基础 stdio MCP） |
+| Phase 4 | MCP 配置助手 / 稳定 launcher | ✅ 完成（launcher + 启用命令 + Claude/Cursor 配置写入 + 复制配置） |
+| Phase 5 | Agent Skill 安装器 | ✅ 完成（默认安装 + 多位置选择 + 安装记录 + 卸载/同步函数） |
+| Phase 6 | Live 查询与快照合并策略 | ✅ 完成（本地只读 HTTP live server + endpoint 文件 + MCP 在线优先/离线兜底 + final 索引静默 5 秒自动快照） |
+| Phase 7 | 测试、文档、发布 | 🟡 部分完成（README + 计划文档已更新；全部 31 个 test/*.test.mjs 逐个直接运行通过；已用直接 esbuild CLI 验证 dist 构建与 MCP smoke test；`node --test` 受沙箱限制，尚未 VSIX 打包/发布） |
+
+### 二期进度（2026-09-10）
+
+| 阶段 | 内容 | 状态 |
+|---|---|---|
+| 二期 A1 | live 响应携带 `projectDir`，MCP 侧校验 | ✅ 完成 |
+| 二期 A2 | endpoint 按项目分文件（保留全局兜底） | ✅ 完成 |
+| 二期 A3 | live server 支持 `?project=` 路由（不再只看活动编辑器） | ✅ 完成 |
+| 二期 A4 | 关闭窗口只清理自己写的 endpoint | ✅ 完成 |
+| 二期 A5 | `processId` 存活校验 | ✅ 完成 |
+| 二期 A6 | live 失败负缓存 | ✅ 完成 |
+| 二期 A7 | `snapshotBaseName` 改为 sha1 前缀 + 可读 slug | ✅ 完成 |
+| 二期 B1 | Skill 适用范围段落（正/负信号 + `get_status` 探针） | ✅ 完成 |
+| 二期 C1 | `get_asset_references`：有界、带 provenance 的正向引用查询 | ✅ 完成 |
+| 二期 C2 | 本地 HTTP `/get_asset_references` 与 MCP 工具接入 | ✅ 完成 |
+| 二期 C3 | 二期测试与文档 | ✅ 完成（264/264 测试通过） |
+
+---
+
+## 1. 背景与目标
+
+当前 RA3 Mod XML 扩展已经能构建大型项目的语义索引，包括：
+
+- asset 定义：`type / id / file / line / origin / stream`
+- `$DEFINE`
+- `<Include>` / `xi:include` 关系
+- 语义引用和反向引用
+- manifest 资产
+- `.w3x` art 资产
+
+这些能力目前主要服务于 VS Code 编辑器内部。  
+本计划的目标是：
+
+1. 让 AI Agent、脚本和其他工具能够方便、可靠地使用该索引；
+2. 不需要用户注册全局 CLI / 修改 PATH；
+3. 安装/更新扩展后能通过一次性设置完成接入；
+4. 在用户持续编辑代码时，索引查询仍然足够实时且不会造成磁盘写放大；
+5. 为 AI Agent 提供工具 + 引导 Skill，让它知道何时、如何调用索引。
+
+---
+
+## 2. 核心设计决策
+
+### 2.1 不采用“全局 CLI + PATH”作为主入口
+
+CLI 可以作为高级/调试工具保留，但不是默认路径。
+
+### 2.2 以 MCP Server 作为 AI Agent 主接口
+
+MCP Server 使用本地 stdio 启动，通过绝对路径配置即可，不需要 PATH。
+
+### 2.3 内存索引为主，磁盘快照为辅
+
+- 实时查询尽量走 VS Code 扩展内存中的 `ModIndex`；
+- 磁盘只保存低频、合并后的“当前稳定快照”作为离线兜底；
+- 避免用户连续编辑保存时产生大量磁盘 IO。
+
+### 2.4 Agent Skill 是可选增强层
+
+MCP 注册解决“工具可用”，Skill 解决“Agent 知道怎么用好工具”。  
+Skill 不作为启用 MCP 的强制条件。
+
+### 2.5 所有查询结果都携带索引状态
+
+外部接口必须返回：索引是否存在、是否正在构建、是否完整、是否 stale、数据版本/时间。
+
+---
+
+## 3. 目标架构
+
+```text
+VS Code 扩展
+   │
+   ├── 内存 ModIndex
+   │       │
+   │       ├── 本地只读查询服务（可选，热数据）
+   │       └── 低频快照导出（冷数据）
+   │
+   ├── MCP 配置助手
+   │       └── 写入 AI 客户端配置 + 稳定 launcher
+   │
+   └── Agent Skill 安装器
+           └── 安装到 ~/.agents/skills 等位置
+
+AI Agent / 外部工具
+   │
+   ├── MCP Server（推荐）
+   │       ├── 扩展在线 → 查询内存/本地服务
+   │       └── 扩展离线 → 读取最近稳定快照
+   │
+   ├── CLI（可选）
+   └── HTTP/JSON-RPC（可选）
+```
+
+---
+
+## 4. 组件设计
+
+### 4.1 外部快照格式
+
+定义一份稳定、公开的快照 schema，不直接暴露内部 workspaceStorage 缓存。
+
+```json
+{
+  "schemaVersion": 1,
+  "project": "D:/Mods/CoronaMod/mods/mods/corona",
+  "generatedAt": "...",
+  "buildId": 128,
+  "phase": "art",
+  "complete": true,
+  "stale": false,
+  "stats": {
+    "assetCount": 38304,
+    "referenceCount": 97862,
+    "defineCount": 240,
+    "streamCount": 12
+  },
+  "assets": [
+    {
+      "type": "GameObject",
+      "id": "...",
+      "file": "Data/...",
+      "line": 10,
+      "origin": "project",
+      "stream": "static",
+      "viaInstance": false
+    }
+  ],
+  "defines": [],
+  "references": [],
+  "includeGraph": [],
+  "sourceCandidates": []
+}
+```
+
+生成方式：
+
+- 从 `ModIndex` 导出；
+- 使用数组而不是 JS Map；
+- 原子写入：`temp + rename`；
+- 同一项目只维护 `current` 快照，不保留每次历史版本；
+- 可选维护 `previous` 用于构建期间回退。
+
+### 4.2 MCP Server
+
+MCP Server 不直接持有完整索引，而是作为查询代理：
+
+1. 扩展在线时，转发到 VS Code 扩展的本地只读查询服务；
+2. 扩展离线时，读取最近一次稳定快照；
+3. 所有工具返回结果时附带索引状态。
+
+建议 MCP 工具集：
+
+```text
+get_status()
+list_projects()
+find_asset(id, type?)
+find_references(id, type?)
+list_assets_by_type(type, prefix?, limit?)
+get_definition(type, id)
+resolve_include(source)
+is_file_active(path)
+find_define(name)
+get_usage_guide()
+```
+
+### 4.3 稳定 launcher 与 MCP 配置助手
+
+扩展安装路径会随版本变化，所以不能直接写死在 MCP 配置里。
+
+稳定入口：
+
+```text
+~/.ra3modxml/
+  ra3-mod-xml-mcp.cmd
+  projects.json
+  snapshots/
+    current.json.gz
+    meta.json
+  skill-install.json
+```
+
+MCP 配置示例：
+
+```json
+{
+  "mcpServers": {
+    "ra3-mod-xml": {
+      "command": "C:\\Users\\lanyi\\.ra3modxml\\ra3-mod-xml-mcp.cmd",
+      "args": ["--project", "D:\\Mods\\CoronaMod\\mods\\mods\\corona"]
+    }
+  }
+}
+```
+
+扩展每次激活/升级时刷新 launcher 内容，指向当前扩展安装目录。  
+这样 MCP 配置只需要写一次，升级不断。
+
+### 4.4 Agent Skill
+
+默认安装：
+
+```text
+~/.agents/skills/ra3-mod-xml/
+├── SKILL.md
+└── references/
+    └── query-guide.md
+```
+
+Skill 内容原则：
+
+- 只描述功能本身；
+- 说明“什么情况下该用这个 Skill”以及“怎么用”；
+- 不引用各个工作区里的具体文档，例如 `docs/codebase-navigation-guide.md`，避免注意力噪音；
+- 保持通用，不绑定某个 mod。
+
+Skill 内容建议包括：
+
+- 索引覆盖范围和状态含义；
+- MCP 工具用途；
+- 推荐查询工作流：
+  - 从 ID 找定义 → `find_asset`
+  - 找所有引用 → `find_references`
+  - 确认文件是否 active → `is_file_active`
+  - 追继承链 → `find_references` + `find_asset`
+  - 找未引用资产 → `unreferenced`
+- 使用规则：
+  - 优先查询索引，而不是全项目 `rg`；
+  - 查询尽量带 type，避免同名不同类型混淆；
+  - 不要把整个索引快照读进上下文；
+  - 如果索引状态不是 ready/stale，应查询状态或重试。
+
+### 4.5 索引状态与一致性
+
+定义索引状态：
+
+| 状态 | 含义 |
+|---|---|
+| `no_index` | 从未构建 |
+| `building` | 正在构建/重建 |
+| `ready_xml` | XML phase 已发布，art 未完成 |
+| `ready` | 完整 final 索引 |
+| `stale` | 构建期间有文件变化 |
+| `error` | 构建失败但保留 last good |
+
+查询接口支持两种模式：
+
+- 默认 / eventual：有可用快照就返回，同时附带 `stale/incomplete` 标记；
+- 严格 / consistent：调用方传 `wait_for_index=true` / `allow_stale=false`，等待新 final 索引或超时。
+
+### 4.6 持久化策略
+
+- 热数据：内存 `ModIndex`；
+- 实时查询：本地查询服务 / MCP 转发；
+- 冷数据：低频快照，例如：
+  - 用户手动导出；
+  - 索引稳定一段时间后自动写一次；
+  - 扩展退出前写一次（尽力而为）；
+- 不每次 rebuild 都写全量快照。
+
+### 4.7 用户交互流程
+
+安装/更新扩展后：
+
+1. 首次索引完成；
+2. 如果尚未启用且未被用户忽略，弹出提示：
+
+```text
+RA3 Mod XML 索引已就绪。
+是否让 AI Agent 使用索引查询能力？
+```
+
+3. 用户点击“启用”；
+4. 扩展默认注册 MCP Server；
+5. 同时询问/默认勾选：
+
+```text
+[✓] 同时安装 RA3 Mod XML Agent Skill（推荐）
+```
+
+6. 写入 MCP 配置；
+7. 安装 Skill 到 `~/.agents/skills/ra3-mod-xml/`；
+8. 提供“安装到其他位置”或“手动操作指南”。
+
+### 4.8 安全设计
+
+- 本地查询服务只监听 `127.0.0.1`；
+- 使用随机 token；
+- MCP Server 默认只读，不提供文件修改/命令执行工具；
+- 写 MCP 配置前必须用户同意；
+- Skill 安装目录记录 managed marker，避免覆盖用户自定义内容。
+
+---
+
+## 5. 实施阶段
+
+### Phase 1：外部快照格式与导出命令
+
+- 新增 `src/agent/snapshot.ts`
+- 新增命令：`ra3modxml.exportIndexSnapshot`
+- 定义 `schemaVersion`
+- 从 `ModIndex` 生成可序列化快照
+- 原子写入 `~/.ra3modxml/snapshots/current.json.gz`
+- 输出状态元数据
+
+### Phase 2：查询核心与 CLI
+
+- 复用纯 TS `indexer` 模块；
+- 新增 `src/agent/query.ts`：
+  - `findAsset`
+  - `findReferences`
+  - `isFileActive`
+  - `listAssetsByType`
+  - `getStatus`
+- 新增 CLI 入口（可选）：
+  - 不注册 PATH；
+  - 通过绝对路径调用；
+  - 供脚本/调试使用。
+
+### Phase 3：MCP Server
+
+- 新增 `src/agent/mcpServer.ts`
+- 支持 stdio 协议；
+- 启动时读取连接信息/快照；
+- 提供前述 MCP 工具；
+- 每个响应带索引状态。
+
+### Phase 4：MCP 配置助手
+
+- 新增 `src/agent/setup.ts`
+- 创建稳定 launcher；
+- 检测/写入常见客户端配置：
+  - Claude Desktop
+  - Cursor
+  - Codex
+  - 通用 JSON
+- 提供“复制 MCP 配置”；
+- 提供手动操作指南。
+
+### Phase 5：Agent Skill 安装器
+
+- 新增 `src/agent/skill.ts`
+- 生成 `SKILL.md` + `references/query-guide.md`
+- 默认安装到 `~/.agents/skills/ra3-mod-xml/`
+- 可选安装到：
+  - `~/.claude/skills/ra3-mod-xml/`
+  - 项目 `.agents/skills/`
+  - 项目 `.claude/skills/`
+  - 自定义位置
+- 记录已安装位置，扩展升级时自动同步；
+- 不覆盖用户自定义内容。
+
+### Phase 6：Live 查询与快照合并
+
+- 在扩展内启动本地只读查询服务；
+- MCP Server 在线时优先转发到扩展；
+- 离线时读取 `current.json.gz`；
+- 实现快照 quiet-period 合并写入，避免频繁全量落盘；
+- 实现状态机：`no_index / building / ready_xml / ready / stale / error`。
+
+### Phase 7：测试、文档、发布
+
+- 测试快照导出/导入一致性；
+- 测试 MCP 工具查询；
+- 测试 Skill 安装/更新/卸载；
+- 测试持续编辑场景下的状态与 stale 行为；
+- 更新 README / docs；
+- 发布新版本。
+
+---
+
+## 6. 预估文件改动
+
+### 新增文件
+
+```text
+src/agent/
+  types.ts
+  snapshot.ts
+  query.ts
+  mcpServer.ts
+  setup.ts
+  skill.ts
+  localServer.ts
+  launcher.ts
+
+docs/
+  ai-agent-integration-plan.md
+```
+
+### 修改文件
+
+```text
+package.json                 # commands / configuration
+src/extension.ts             # 注册命令、设置、初始化
+src/workspace.ts             # 暴露 index status / snapshot 发布钩子
+src/features/agentSetup.ts   # 用户引导 UI（或并入 agent/setup.ts）
+```
+
+---
+
+## 7. 验收标准
+
+1. 用户安装/更新扩展并完成一次索引后，可以看到“启用 AI Agent 访问”的引导。
+2. 用户点击启用后，不需要手动配置 PATH，不需要手动查找 workspaceStorage。
+3. 常见 AI 客户端能通过 MCP 调用索引工具。
+4. Agent 能正确回答：
+   - “某 asset 定义在哪个文件？”
+   - “谁引用了这个 asset？”
+   - “这个 XML 文件是否真的被 Include？”
+5. 查询接口在无索引/索引更新中不会返回误导性空结果。
+6. 用户连续编辑保存时，不会因为频繁快照写入而产生明显卡顿或磁盘膨胀。
+7. Skill 安装后，Agent 知道优先使用 MCP 查询，而不是全文 grep。
+8. 扩展升级后，MCP 配置仍然有效，Skill 能自动同步到已安装位置。
+
+---
+---
+
+# 第二部分：二期计划（讨论结论 + 实施）
+
+> 讨论时间：2026-09-10
+> 主题：Skill 的项目识别边界、正向/间接引用查询的取舍、MCP 与 localhost 架构现状
+
+---
+
+## 8. 讨论结论一：谁来判定"这是不是一个红警 3 模组项目"
+
+### 问题
+
+Skill 需要说明"何时应该被使用"和"适用范围"。这要求 Agent 能理解什么是
+"红警 3 模组项目里的 XML"，同时避免把无关项目误判为 RA3 模组。
+
+问题在于：这个判断应该由扩展/Skill 自己解释（甚至给出推断规则），还是应该
+由项目开发者在自己的项目文档 / `AGENTS.md` 里声明？
+
+### 结论：分层，且 Skill 不做复杂推断
+
+| 层 | 职责 | 理由 |
+|---|---|---|
+| **Skill** | 说明能力覆盖范围 + 少量正/负信号 + 便宜的探测方式 | Skill 是用户全局的，会在**所有**对话里加载，必须简短且能自我限制 |
+| **项目开发者**（`AGENTS.md` / README / 项目标记） | 声明"这个仓库是什么项目、要不要用这些工具" | 只有项目自己知道自己是什么，这是每个仓库的局部事实 |
+| **MCP 工具自身** | 用响应证明自己是否可用 | `get_status` 是最便宜的判定，不应靠读文档猜 |
+
+### 为什么不把判断规则写进 Skill
+
+- Skill 在 `~/.agents/skills/` 下全局生效；如果写一堆判定规则，会在与 RA3
+  无关的项目里制造"要不要用这个工具"的注意力噪音。
+- 规则永远不完备。真实反例：
+  - 目录里有 `Schemas/xsd/CnC3Types.xsd` → 可能只是 SDK 本身，不是 mod；
+  - 只有一堆从 SDK 抄来的 `.xsd` → 是"RA3 相关"，但没有 mod 数据；
+  - `CnC3Types.xsd` 里的 `CnC3` 指 **C&C3**（命令与征服 3 / 凯恩之怒），
+    所以"存在 CnC3Types.xsd" **不等于** "是 RA3 模组"；
+  - 有 `Data/Mod.xml` / `*.babproj` / `Data/additionalmaps/mapmetadata_*.xml`
+    → 基本可确认是 **SAGE / BinaryAssetBuilder** 系项目（RA3 只是其中之一）。
+- 一旦误判，Agent 会拿 RA3 的索引数据去回答另一个项目的问题，比不使用更糟。
+
+### 落地方案
+
+**Skill 侧**（`src/agent/skill.ts` 的 `SKILL_MD`）新增 applicability 段落：
+
+- 正向信号（任一命中即可尝试）：
+  `Data/Mod.xml`；`Data/additionalmaps/mapmetadata_*.xml`；`*.babproj`；
+  XML 根为 `<AssetDeclaration>`；使用 `<Includes><Include source="DATA:…"/></Includes>`。
+- 明确否定：无关仓库、仅含拷贝 `.xsd` 的项目、通用 XML 配置、构建脚本、
+  非 SAGE 游戏项目。
+- 便宜的探针：不确定时先调 `get_status`；它返回索引归属的 `projectDir`。
+  如果与当前工作区根不一致，或状态是 `no_index`，就**停止使用索引工具**，
+  改为直接读文件。
+
+这样即使误触发，成本也只是一次 `get_status`，不会污染后续推理。
+
+**项目开发者侧**：在项目根 `AGENTS.md` 写一句即可，例如：
+
+```markdown
+## RA3 Mod tooling
+This repository is a Red Alert 3 mod (SAGE XML). When locating asset
+definitions or references, prefer the `ra3-mod-xml` MCP tools
+(`find_asset`, `find_references`, `is_file_active`) over full-text search.
+```
+
+扩展**不自动**往用户仓库写标记文件（如 `.agents/ra3-mod-xml-project.json`）
+作为二期内容；若将来提供，必须显式确认。
+
+---
+
+## 9. 讨论结论二：要不要提供"某个 Asset 直接/间接引用的所有 Asset"
+
+### 场景
+
+用户要求 Agent"查阅或修改雅典娜炮的武器"。Agent 需要：
+
+1. 找到雅典娜炮的 GameObject；
+2. 读源码，发现 `<FireWeaponUpdate />` / `<WeaponSetUpdate />` 等子元素，
+   在这些子元素里找到武器引用；
+3. 若 `<CreateObjectDie />` 引用了临时物体，还要去读临时物体的 GameObject，
+   在它的 `FireWeaponUpdate` 里找武器；
+4. 若雅典娜炮只有 `FireWeaponUpdate`、`WeaponSetUpdate` 在
+   `inheritFrom` 的 `BaseCannon` 上，还要读 `BaseCannon` 并综合判断。
+
+评估问题：
+
+- 是否有必要提供"某个 Asset 直接或间接引用的所有 Asset"？
+- 只给精炼 asset 列表，Agent 不知道是哪个子元素导致的引用，有用吗？
+- 若同时提供上下文，磁盘/内存/性能允许吗？内容长度会不会反而比直接读源码更贵？
+- 相对直接读源码未必有显著提升，反而增加注意力噪音？
+- 间接引用会不会多项式/指数爆炸？
+
+### 先指出当前实现的真实缺口
+
+现在的索引只有**反向**引用（谁引用了我），没有**正向**查询（我引用了谁）。
+`find_references(AthenaCannon)` 返回的是"谁引用了雅典娜炮"，而不是"雅典娜炮
+用了哪些武器"。所以上述 Agent 工作流**目前完全无法用工具完成**，只能读源码。
+
+因此问题不是"要不要锦上添花"，而是这里确实缺一个基础能力。
+
+### 结论：不提供"所有可达 Asset 的扁平闭包"，改提供"有界 + 带 provenance 的边列表"
+
+**不采用扁平静态闭包的理由：**
+
+1. **丢失 provenance，Agent 仍然要读源码。** 到底是 `FireWeaponUpdate` 的武器、
+   `WeaponSetUpdate` 的武器、`CreateObjectDie` 临时物体的武器，还是
+   `inheritFrom` 继承来的武器？这决定了 Agent 改哪个文件、加不加
+   `xai:joinAction`。丢掉上下文，列表基本没用。
+2. **尺寸会失控。** 一个 GameObject 的可达闭包可能是
+   `Weapon → Projectile → Warhead → DamageNugget → FX → Particle → Texture`、
+   `Model → Mesh → Material → Texture`、`AttributeModifier`、`Upgrade`、`Command`、
+   `Button`……Corona 规模下单个单位几百到上千节点完全可能。200 条边就是几万
+   token，**比直接读 3 个小 XML 文件贵得多**。
+3. **注意力噪音。** 列表里 80% 是与当前问题无关的 Texture / FX 时，推理质量下降。
+4. **"间接"的诱惑会持续膨胀。** 一旦提供无界闭包，Agent 会习惯性调用它，
+   然后被淹没。
+
+**但以下特性确实值得工具化：**
+
+- 多跳遍历是**纯机械**的，正是工具该做的事；
+- `inheritFrom` 链 + `xai:joinAction` 语义很微妙，Agent 手推容易错；
+- 每跳都 read 一个文件，Corona 下成本和 token 都很高；
+- 工具可以做到**确定性、不遗漏**（按 XSD 判定"哪些属性是引用"，
+  而不是靠 Agent 逐个注意）。
+
+**设计要点（二期实现遵循）：**
+
+- 返回**边列表**而不是节点集合。每条边携带：
+  - `from`（effective asset）、`to`（解析出的定义位置）、
+  - `via.kind`（`attribute` / `content` / `inheritFrom`）、
+  - `via.element`、`via.parent`、`via.attribute`，
+  - `source.file` / `source.line`（XML 实际所在位置），
+  - `definedIn`（当该边来自 `inheritFrom` 祖先的 XML 时，标明真正写它的资产）。
+- **默认 `depth: 1`，硬上限 3。** Agent 拿到直接引用后自己决定是否对某个具体
+  节点递归，比一次性 dump 闭包更省 token、更有针对性。
+- **`targetTypes` 过滤**是抑制噪音最有效的手段。雅典娜炮场景就是
+  `targetTypes: ["WeaponTemplate"]`（可选再带 `GameObject` 给 `CreateObjectDie`），
+  返回可能只有 3–10 条边。
+- **`inheritFrom` 不消耗 depth**：继承是资产自身定义的一部分，不是运行时引用。
+  因此在同一 depth 内递归遍历继承链（链长上限 8），并把 `definedIn` 标出来。
+- **截断时返回 `omittedByTargetType` 摘要**，让 Agent 知道被砍掉了什么形状的数据，
+  可以精确下钻，而不是无脑重试或放弃。
+- **不提供"合并后的有效值"**：`joinAction` 的 Replace/Remove/merge 语义算错的风险
+  太高，一期不做。
+
+**关于爆炸和成本：**
+
+- 算法上不是指数：带 visited-set 的 BFS 是 `O(V+E)`。真正的风险是**语义宽度**，
+  不是复杂度，因此用 `depth` + `targetTypes` + `maxEdges` 三重限制。
+- **只做 live 查询**（VS Code 打开时可用）。要拿元素上下文，最干净的做法是按需
+  解析定义所在文件的 DOM，而不是往 records 缓存里塞元素名/属性名 —— Corona 有
+  ~98k 条引用记录，再塞 5 个字符串字段会让常驻内存明显膨胀，为一个默认 `depth=1`
+  的功能付出这个成本不划算。
+- 离线快照路径明确返回"需要 live index"，而不是静默返回空结果。
+
+---
+
+## 10. 讨论结论三：MCP / localhost 的实际架构与多窗口缺陷
+
+### 当前架构（事实）
+
+```text
+AI 客户端
+   │  stdio (JSON-RPC, MCP)
+   ▼
+dist/agent/mcpServer.js          ← 由 AI 客户端启动，参数 --project <dir>
+   │  HTTP (127.0.0.1:临时端口, Bearer token)
+   ▼
+VS Code 扩展进程内的 localServer  ← 仅在"启用 AI Agent 访问"后启动
+   │
+   ├─ 在线 → ws.activeIndex() 实时内存索引
+   └─ 离线 → ~/.ra3modxml/snapshots/project-<hash>.json.gz
+```
+
+- **AI 客户端不需要知道端口。** MCP Server 自己读
+  `~/.ra3modxml/endpoint.json` 拿 `url` + `token` 再 `fetch`。localhost 层是
+  纯实现细节。
+- **端口**：`server.listen(port ?? 0, "127.0.0.1")`，即由操作系统分配临时端口，
+  不会冲突；当前未传 `port`，所以永远是临时端口。
+- **鉴权**：`Authorization: Bearer <token>`，token 为启动时随机生成；绑定
+  `127.0.0.1`，局域网访问不到。
+- **降级**：live 查询失败（endpoint 不存在 / 连接被拒 / 超时 1.5s）时回退到快照。
+
+### 多项目 / 多 VSCode 窗口的真实缺陷
+
+`endpoint.json` 是**全局唯一**的一个文件，所有 VSCode 窗口都往它写入：
+
+1. **最后启用的窗口覆盖前面所有窗口。** 两个窗口都启用了 Agent 访问时，
+   只有后启动的那个能被 MCP Server 找到。
+2. **可能串项目（严重）。** 假设窗口 B 覆盖了 endpoint，而某个 MCP Server 是用
+   `--project 窗口A` 启动的，它的 `tryLiveQuery` 会打到**窗口 B** 的 server，
+   拿到窗口 B 的索引数据，而返回值里没有任何东西能暴露这个不一致。
+   这比 `no_index` 危险得多 —— 会静默给出错误答案。
+3. **关闭任意窗口都会 `clearEndpoint()`**，把还开着的其他窗口的 live 通道一起断掉。
+4. **同一窗口内多项目也不稳。** live server 用
+   `getIndex: () => ws.activeIndex()`，而 `activeIndex()` 跟着**当前活动编辑器**走。
+   用户切到另一个项目的文件，live 查询就会静默换项目；而 `endpoint.json` 里的
+   `projectDir` 只在启动时写一次，之后不更新。
+5. `processId` 虽然写进了 endpoint，但**从未被校验**；VSCode 崩溃后残留的 endpoint
+   只能靠连接失败兜底。
+6. 离线快照路径是**正确**的 —— `snapshotPathForProject()` 按项目路径做 hash，
+   多项目互不干扰。问题只在 live 层。
+
+### 修复方案（二期 A，按性价比排序）
+
+1. **live 响应必须带 `projectDir`，MCP 侧必须校验它和 `--project` 一致**，
+   不一致就直接走快照。这是最小的正确性补丁，最先做。
+2. **endpoint 按项目存**：`~/.ra3modxml/endpoints/<project-hash>.json`，
+   MCP Server 按 `--project` 找对应的那个；同时保留 `endpoint.json` 作为
+   "最近"的兼容入口。
+3. **live server 支持 `?project=` 路由**，而不是只认 `activeIndex()`。
+   扩展侧加 `indexForProject(projectDir)`，一个窗口的一个 server 就能服务它
+   所有已索引项目，也就不怕用户切编辑器。
+4. **关闭时只清自己的那一条**，不无条件删全局 endpoint。
+5. **校验 `processId` 是否存活**，不存活就当 endpoint 失效。
+6. `tryLiveQuery` 失败后做几秒的"live 不可用"负缓存，避免每次调用都试一次。
+7. `snapshotBaseName` 换成 sha1 前缀 + 可读 slug（与 `diskCacheKey` 一致的做法），
+   降低碰撞概率。
+
+---
+
+## 11. 二期实施清单
+
+### 二期 A：多窗口 / 多项目正确性
+
+- `src/agent/snapshot.ts`：新增 `projectHash()`；`snapshotBaseName()` 改为
+  `<slug>-<sha1-12>`。
+- `src/agent/endpoint.ts`：新增
+  `endpointPathForProject()` / `writeEndpointForProject()` /
+  `readEndpointForProject()` / `clearEndpointForProject()` / `isProcessAlive()`。
+- `src/workspace.ts`：新增 `indexForProject(projectDir)`。
+- `src/agent/liveQuery.ts`：`liveStatus()` 在没有索引时回落到请求的 `projectDir`。
+- `src/agent/localServer.ts`：`getIndex(projectDir?)` 路由、异步 handler、
+  `/projects` 端点、所有响应携带 `index.projectDir`。
+- `src/agent/mcpServer.ts`：按项目读 endpoint、校验 `projectDir` 与 `processId`、
+  `?project=` 透传、live 失败负缓存、响应 `projectDir` 二次校验。
+- `src/extension.ts`：启动时按项目写 endpoint、关闭时只清自己写过的那些。
+
+### 二期 B：Skill 适用范围
+
+- `src/agent/skill.ts`：`SKILL_MD` 增加 applicability 段落（正向信号、明确否定、
+  `get_status` 探针）；保持"不引用工作区文档"的原则。
+
+### 二期 C：`get_asset_references`
+
+- `src/agent/forwardRefs.ts`（新增）：DOM-based、有界、带 provenance 的正向引用遍历。
+- `src/agent/localServer.ts`：新增 `GET /get_asset_references`。
+- `src/agent/mcpServer.ts`：新增 `get_asset_references` 工具（live-only，
+  离线时返回明确的"需要 live index"说明）。
+- `src/extension.ts`：为 live server 提供 `loadFile()`（读文本 + 解析 + LineMap）。
+
+### 二期 D：测试
+
+- `test/agentEndpoint.test.mjs`：按项目 endpoint、进程存活、清理隔离。
+- `test/agentLocalServer.test.mjs`：`?project=` 路由、`projectDir` 校验、
+  `/get_asset_references`。
+- `test/agentForwardRefs.test.mjs`：直接引用、继承链、`CreateObjectDie` 内容引用、
+  `targetTypes` 过滤、`maxEdges` 截断、`depth` 上限。
+- `test/agentSkill.test.mjs`：Skill 文本包含 applicability 段落且不含工作区文档引用。
+- `test/agentMcpRouting.test.mjs`：live URL 固定 `project`、跨项目响应拒绝。
+
+---
+
+## 12. 二期实施结果
+
+全部完成，`npx tsc --noEmit` 通过，`test/*.test.mjs` 共 **264/264** 通过。
+
+### 新增 / 修改文件
+
+```text
+新增：
+  src/agent/forwardRefs.ts          有界、带 provenance 的正向引用遍历
+  test/agentForwardRefs.test.mjs
+  test/agentMcpRouting.test.mjs
+
+修改：
+  src/agent/endpoint.ts             按项目 endpoint + isProcessAlive()
+  src/agent/snapshot.ts             projectHash() / projectSlug() / snapshotBaseName()
+  src/agent/liveQuery.ts            liveStatus() 回落请求的 projectDir
+  src/agent/localServer.ts          异步 handler、?project= 路由、/projects、/get_asset_references
+  src/agent/mcpServer.ts            按项目 endpoint、projectDir 校验、负缓存、get_asset_references
+  src/agent/skill.ts                applicability 段落 + get_asset_references 用法
+  src/workspace.ts                  新增 indexForProject()
+  src/extension.ts                  按项目写/清 endpoint、loadFile、endpoint 刷新
+  test/agentEndpoint.test.mjs
+  test/agentLocalServer.test.mjs
+  test/agentSkill.test.mjs
+```
+
+### 关键行为
+
+**多窗口 / 多项目**
+
+- `~/.ra3modxml/endpoints/<slug>-<sha1-12>.json` 一项目一文件；MCP Server 先读自己项目的
+  文件，读不到才退回全局 `endpoint.json`，且仅在 `projectDir` 匹配时使用。
+- 每个 live 请求带 `?project=`；server 用 `ModWorkspace.indexForProject()` 路由，
+  不再依赖"当前活动编辑器"。
+- MCP 侧对响应里的 `index.projectDir` 做二次校验，不匹配就拒答并提示重新启用，
+  而不是给一个看起来合理但属于别的项目的答案。
+- 关闭窗口只删除本窗口写过的 endpoint 文件。
+- `processId` 不存活时 endpoint 视为失效。
+- live 连接失败后有 5 秒负缓存，避免每次工具调用都探一次。
+
+**Skill**
+
+- 新增 `When this skill applies` 段落：正向信号（`Data/Mod.xml`、
+  `mapmetadata_*.xml`、`*.babproj`、`<AssetDeclaration>`、
+  `uri:ea.com:eala:asset`）、明确否定规则（无关仓库、仅含拷贝 `.xsd` 的项目）、
+  以及 `CnC3Types.xsd` 属于 C&C3 而非 RA3 的反例。
+- 规定用 `get_status` 做便宜探针：状态为 `no_index` 或 `projectDir` 不匹配时
+  停止使用索引工具，改为直接读文件。
+- 仍然不引用任何工作区文档（有测试断言）。
+
+**`get_asset_references`（正向引用）**
+
+- 返回**边**：`from` / `to` / `via{kind,element,parent,attribute}` /
+  `source{file,line,character}` / `definedIn` / `value`。
+- `depth` 默认 1、上限 3；`inheritFrom` 不消耗 depth，祖先 XML 在同层遍历，
+  用 `definedIn` 标出真正写这条边的资产（解决"雅典娜炮自己没有 WeaponSetUpdate，
+  但 BaseCannon 有"的场景）。
+- `targetTypes` 按 XSD 可赋值性过滤，但 `inheritFrom` 边始终保留，因为
+  它解释了其余边写在哪里。
+- `maxEdges` 截断时返回 `truncated` + `omittedByTargetType`（只统计因上限被丢弃的边，
+  已被 `targetTypes` 过滤的不计入）。
+- 只走 live 路径；不可用时返回明确的错误说明，而不是空结果。
+
+### 已知限制
+
+- `get_asset_references` 不计算 `xai:joinAction`（`Replace`/`Remove`）合并后的
+  有效值，需要调用方自行确认。
+- 只有 live 路径支持正向引用；离线快照路径明确返回"需要 live index"。
+- `snapshotBaseName` 改为 `<slug>-<sha1-12>`，旧的 `project-<hash>.json.gz`
+  快照文件不会被自动清理（该功能尚未发布，无兼容负担）。
+- 本沙箱禁止 spawn 子进程，因此 `node --test` 与 `npm run build` 无法直接运行；
+  验证方式为：逐个 `node test/*.test.mjs`、直接调用 esbuild CLI 构建 dist、
+  用管道驱动 `dist/agent/mcpServer.js` 做端到端 smoke test。
+
+

esbuild.mjs

@@ -3,9 +3,14 @@ import * as esbuild from "esbuild";
 const watch = process.argv.includes("--watch");
 
 const ctx = await esbuild.context({
-  entryPoints: ["./src/extension.ts"],
+  entryPoints: [
+    "./src/extension.ts",
+    "./src/agent/mcpServer.ts",
+    "./src/agent/cli.ts",
+  ],
   bundle: true,
-  outfile: "dist/extension.js",
+  outdir: "dist",
+  outbase: "src",
   external: ["vscode"],
   format: "cjs",
   platform: "node",

package.json

@@ -126,6 +126,18 @@
         "command": "ra3modxml.showCacheReport",
         "title": "%ra3modxml.command.showCacheReport.title%"
       },
+      {
+        "command": "ra3modxml.enableAgentAccess",
+        "title": "%ra3modxml.command.enableAgentAccess.title%"
+      },
+      {
+        "command": "ra3modxml.installAgentSkill",
+        "title": "%ra3modxml.command.installAgentSkill.title%"
+      },
+      {
+        "command": "ra3modxml.exportIndexSnapshot",
+        "title": "%ra3modxml.command.exportIndexSnapshot.title%"
+      },
       {
         "command": "ra3modxml.findUnreferencedAssets",
         "title": "%ra3modxml.command.findUnreferencedAssets.title%"

package.nls.json

@@ -13,6 +13,9 @@
   "ra3modxml.command.clearCache.title": "RA3 Mod XML: Clear caches and rebuild",
   "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.installAgentSkill.title": "RA3 Mod XML: Install Agent Skill…",
+  "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"
 }

package.nls.zh-cn.json

@@ -13,6 +13,9 @@
   "ra3modxml.command.clearCache.title": "RA3 Mod XML: 清空缓存并重建",
   "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.installAgentSkill.title": "RA3 Mod XML: 安装 Agent Skill…",
+  "ra3modxml.command.exportIndexSnapshot.title": "RA3 Mod XML: 导出 AI Agent 索引快照",
   "ra3modxml.command.findUnreferencedAssets.title": "RA3 Mod XML: 查找未引用的资产…",
   "ra3modxml.command.findUnreferencedAssetsOfType.title": "RA3 Mod XML: 查找该类型的未引用资产"
 }

src/agent/cli.ts

@@ -0,0 +1,159 @@
+/**
+ * Minimal CLI for querying an exported RA3 Mod XML agent snapshot.
+ *
+ * This is intentionally not installed into PATH. It is meant for scripts,
+ * debugging, and as a reference for MCP tool implementations.
+ *
+ * Usage examples:
+ *   node out/agent/cli.js --project D:/Mods/Example status
+ *   node out/agent/cli.js --snapshot /path/to/snapshot.json.gz find ExampleUnit
+ *   node out/agent/cli.js --project D:/Mods/Example refs ExampleUnit GameObject
+ */
+
+import { readSnapshotFile, snapshotPathForProject } from "./snapshot";
+import {
+  findAssets,
+  findDefine,
+  findReferenceGroups,
+  isFileActive,
+  listAssetsByType,
+  resolveIncludeSource,
+  statusFromSnapshot,
+} from "./query";
+
+interface CliOptions {
+  snapshotPath: string | null;
+  projectDir: string | null;
+  command: string;
+  args: string[];
+}
+
+function parseArgs(argv: string[]): CliOptions {
+  const options: CliOptions = {
+    snapshotPath: null,
+    projectDir: null,
+    command: "status",
+    args: [],
+  };
+  const positional: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--snapshot" || arg === "-s") {
+      options.snapshotPath = argv[++i] ?? null;
+    } else if (arg === "--project" || arg === "-p") {
+      options.projectDir = argv[++i] ?? null;
+    } else if (arg === "--help" || arg === "-h") {
+      options.command = "help";
+    } else if (arg.startsWith("-")) {
+      // ignore unknown flags
+    } else {
+      positional.push(arg);
+    }
+  }
+  if (positional.length > 0) {
+    options.command = positional[0];
+    options.args = positional.slice(1);
+  }
+  return options;
+}
+
+function printHelp(): void {
+  console.log(`RA3 Mod XML agent snapshot CLI
+
+Usage:
+  node out/agent/cli.js --project <dir> <command> [args...]
+  node out/agent/cli.js --snapshot <file> <command> [args...]
+
+Commands:
+  status
+  find <id> [type]
+  refs <id> [type]
+  list <type> [prefix]
+  active <file>
+  define <name>
+  resolve <source>
+  help
+`);
+}
+
+async function main(): Promise<void> {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.command === "help") {
+    printHelp();
+    return;
+  }
+  const snapshotPath =
+    options.snapshotPath ??
+    (options.projectDir ? snapshotPathForProject(options.projectDir) : null);
+  if (!snapshotPath) {
+    console.error("No --project or --snapshot provided.");
+    process.exitCode = 2;
+    return;
+  }
+  const snapshot = await readSnapshotFile(snapshotPath);
+  if (!snapshot) {
+    console.error(`Snapshot not found or unreadable: ${snapshotPath}`);
+    process.exitCode = 3;
+    return;
+  }
+
+  const [a, b] = options.args;
+  switch (options.command) {
+    case "status":
+      console.log(JSON.stringify(statusFromSnapshot(snapshot), null, 2));
+      break;
+    case "find":
+      if (!a) {
+        console.error("find requires an id.");
+        process.exitCode = 2;
+        return;
+      }
+      console.log(JSON.stringify(findAssets(snapshot, a, b), null, 2));
+      break;
+    case "refs":
+      if (!a) {
+        console.error("refs requires an id.");
+        process.exitCode = 2;
+        return;
+      }
+      console.log(JSON.stringify(findReferenceGroups(snapshot, a, b), null, 2));
+      break;
+    case "list":
+      if (!a) {
+        console.error("list requires a type.");
+        process.exitCode = 2;
+        return;
+      }
+      console.log(JSON.stringify(listAssetsByType(snapshot, a, b ?? ""), null, 2));
+      break;
+    case "active":
+      if (!a) {
+        console.error("active requires a file path.");
+        process.exitCode = 2;
+        return;
+      }
+      console.log(JSON.stringify({ active: isFileActive(snapshot, a) }, null, 2));
+      break;
+    case "define":
+      if (!a) {
+        console.error("define requires a name.");
+        process.exitCode = 2;
+        return;
+      }
+      console.log(JSON.stringify(findDefine(snapshot, a), null, 2));
+      break;
+    case "resolve":
+      if (!a) {
+        console.error("resolve requires a source.");
+        process.exitCode = 2;
+        return;
+      }
+      console.log(JSON.stringify(resolveIncludeSource(snapshot, a), null, 2));
+      break;
+    default:
+      console.error(`Unknown command: ${options.command}`);
+      process.exitCode = 2;
+  }
+}
+
+void main();

src/agent/endpoint.ts

@@ -0,0 +1,153 @@
+/**
+ * Read/write helpers for the local endpoint files used by MCP/CLI tools to
+ * find a live RA3 Mod XML query server.
+ *
+ * Discovery is **per project** (`endpoints/<slug>-<hash>.json`) because a
+ * single global `endpoint.json` breaks as soon as more than one VS Code
+ * window (or more than one project) has AI Agent access enabled: the last
+ * window to start would overwrite the file, and a client started for project
+ * A could silently receive project B's index.
+ *
+ * A global `endpoint.json` is still written as a legacy/"most recent" pointer
+ * so tooling that does not know the project can find something, but readers
+ * that do know the project must prefer the per-project file.
+ *
+ * Pure TypeScript: no VS Code dependency.
+ */
+
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { defaultAgentHome, snapshotBaseName } from "./snapshot";
+
+export interface AgentEndpoint {
+  /** Base URL of the local server, e.g. http://127.0.0.1:54321 */
+  url: string;
+  token: string;
+  /** Absolute project root this endpoint serves (may serve several). */
+  projectDir?: string;
+  /** Every project root the server can answer for. */
+  projects?: string[];
+  /** PID of the VS Code extension host, used to detect stale files. */
+  processId?: number;
+  /** ISO timestamp of the last write, useful for diagnostics. */
+  updatedAt?: string;
+}
+
+/** Path to the legacy global endpoint file. */
+export function endpointPath(agentHome = defaultAgentHome()): string {
+  return join(agentHome, "endpoint.json");
+}
+
+/** Directory holding one endpoint file per project. */
+export function endpointDir(agentHome = defaultAgentHome()): string {
+  return join(agentHome, "endpoints");
+}
+
+/** Path to the per-project endpoint file. */
+export function endpointPathForProject(
+  projectDir: string,
+  agentHome = defaultAgentHome(),
+): string {
+  return join(endpointDir(agentHome), `${snapshotBaseName(projectDir)}.json`);
+}
+
+async function writeJson(file: string, value: unknown): Promise<void> {
+  await mkdir(dirname(file), { recursive: true });
+  await writeFile(file, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+async function readJson<T>(file: string): Promise<T | null> {
+  try {
+    return JSON.parse(await readFile(file, "utf8")) as T;
+  } catch {
+    return null;
+  }
+}
+
+/** Writes the legacy global endpoint file. */
+export async function writeEndpoint(
+  endpoint: AgentEndpoint,
+  agentHome = defaultAgentHome(),
+): Promise<string> {
+  const file = endpointPath(agentHome);
+  await writeJson(file, endpoint);
+  return file;
+}
+
+/** Writes one project's endpoint file (does not touch the global pointer). */
+export async function writeEndpointForProject(
+  projectDir: string,
+  endpoint: AgentEndpoint,
+  agentHome = defaultAgentHome(),
+): Promise<string> {
+  const file = endpointPathForProject(projectDir, agentHome);
+  await writeJson(file, { ...endpoint, projectDir: resolve(projectDir) });
+  return file;
+}
+
+/** Reads the legacy global endpoint file. */
+export async function readEndpoint(
+  agentHome = defaultAgentHome(),
+): Promise<AgentEndpoint | null> {
+  const parsed = await readJson<AgentEndpoint>(endpointPath(agentHome));
+  if (!parsed?.url || !parsed.token) return null;
+  return parsed;
+}
+
+/**
+ * Reads one project's endpoint. Returns null when the file is missing or the
+ * recorded project does not match the requested one (defence in depth: the
+ * file name already encodes the project, but a stale/hand-edited file must
+ * never be able to redirect a client to another project).
+ */
+export async function readEndpointForProject(
+  projectDir: string,
+  agentHome = defaultAgentHome(),
+): Promise<AgentEndpoint | null> {
+  const parsed = await readJson<AgentEndpoint>(
+    endpointPathForProject(projectDir, agentHome),
+  );
+  if (!parsed?.url || !parsed.token) return null;
+  if (parsed.projectDir && !sameProject(parsed.projectDir, projectDir)) {
+    return null;
+  }
+  return parsed;
+}
+
+/** Removes the legacy global endpoint file. */
+export async function clearEndpoint(
+  agentHome = defaultAgentHome(),
+): Promise<void> {
+  await rm(endpointPath(agentHome), { force: true });
+}
+
+/** Removes one project's endpoint file. */
+export async function clearEndpointForProject(
+  projectDir: string,
+  agentHome = defaultAgentHome(),
+): Promise<void> {
+  await rm(endpointPathForProject(projectDir, agentHome), { force: true });
+}
+
+/** True when both paths resolve to the same project root. */
+export function sameProject(a: string, b: string): boolean {
+  return resolve(a).toLowerCase() === resolve(b).toLowerCase();
+}
+
+/**
+ * True when a recorded extension-host PID is still running.
+ *
+ * `process.kill(pid, 0)` only probes existence: EPERM means the process
+ * exists but we may not signal it, which still counts as alive. Unknown PIDs
+ * are treated as alive so that a missing/older endpoint file does not disable
+ * the live path.
+ */
+export function isProcessAlive(pid: number | undefined | null): boolean {
+  if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0) return true;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code === "EPERM";
+  }
+}

src/agent/forwardRefs.ts

@@ -0,0 +1,503 @@
+/**
+ * Bounded, provenance-carrying forward-reference (outgoing edge) queries.
+ *
+ * The reverse index answers "who references this asset". This module answers
+ * the opposite, which the index does not store: "which assets does this asset
+ * reference, and through which XML element/attribute?".
+ *
+ * Design decisions (see docs/ai-agent-integration-plan.md §9):
+ *
+ * - It returns **edges**, not a flat node set. Each edge carries the element
+ *   name, parent element name and attribute that produced it, plus the exact
+ *   file/line of the XML text. A node list without that context forces the
+ *   agent back into reading source, which is exactly what this should avoid.
+ * - It is **bounded three ways**: `depth` (1 default, 3 max), `targetTypes`
+ *   (assignability filter) and `maxEdges`. Truncation is reported together
+ *   with a per-type summary of what was dropped, so the caller can narrow the
+ *   query instead of silently receiving a partial answer.
+ * - `inheritFrom` does **not** consume depth. Inheritance is part of an
+ *   asset's own effective definition, so the ancestor's XML is walked at the
+ *   same level and tagged with `definedIn`. This is what makes "AthenaCannon
+ *   has no WeaponSetUpdate, but BaseCannon does" answerable in one call.
+ * - It is DOM-based and therefore **live-only**: resolving element context
+ *   needs the parse tree, and storing element names on all ~98k reference
+ *   records would measurably inflate the persistent cache.
+ * - It deliberately does **not** compute merged/inherited effective values:
+ *   `xai:joinAction` Replace/Remove semantics are too easy to get wrong.
+ *
+ * Pure TypeScript: no VS Code dependency.
+ */
+
+import type { AssetDef, ModIndex } from "../indexer/types";
+import { localName } from "../indexer/xpointer";
+import {
+  isReferenceAttributeOfType,
+  isReferenceContentType,
+  resolveContentReferenceTargets,
+  resolveReferenceTargetsForType,
+} from "../indexer/refs";
+import {
+  LineMap,
+  parseXml,
+  type XmlDocument,
+  type XmlElement,
+} from "../language/xmlParser";
+import { resolveElementType } from "../language/typeContext";
+import { isAssignableTo } from "../model/schemaModel";
+
+export interface ForwardRefVia {
+  kind: "attribute" | "content" | "inheritFrom";
+  /** Element carrying the reference (e.g. `Weapon`). */
+  element: string;
+  /** Parent element giving the element its context (e.g. `WeaponSlotHardpoint`). */
+  parent: string | null;
+  /** Attribute name for `attribute` kind; null for `content`/`inheritFrom`. */
+  attribute: string | null;
+}
+
+/** A resolved definition location. */
+export interface ForwardRefTarget {
+  type: string;
+  id: string;
+  file: string;
+  line: number;
+}
+
+export interface ForwardRefEdge {
+  /** 1-based hop number from the queried asset. */
+  depth: number;
+  /** The asset the edge is attributed to (the queried asset for inherited XML). */
+  from: { type: string; id: string };
+  /** Resolved definition, or null for an unresolved reference. */
+  to: ForwardRefTarget | null;
+  via: ForwardRefVia;
+  /**
+   * Present only when the XML text lives in an `inheritFrom` ancestor rather
+   * than in `from` itself.
+   */
+  definedIn?: { type: string; id: string };
+  /** Exact source position of the reference value. */
+  source: { file: string; line: number; character: number };
+  /** Raw value, present for unresolved references and `inheritFrom` edges. */
+  value?: string;
+}
+
+export interface ForwardRefNode extends ForwardRefTarget {
+  /** Shallowest depth at which this node was reached. */
+  depth: number;
+}
+
+export interface ForwardRefOptions {
+  /** Levels of assets to expand. 1 = only the queried asset (default). Max 3. */
+  depth?: number;
+  /** Only keep edges/nodes whose target is assignable to one of these types. */
+  targetTypes?: string[];
+  /** Hard cap on returned edges (default 200). */
+  maxEdges?: number;
+  /** Include edges whose reference value could not be resolved. */
+  includeUnresolved?: boolean;
+  /** Walk `inheritFrom` ancestors (default true). */
+  includeInheritance?: boolean;
+}
+
+export interface ForwardRefResult {
+  roots: AssetDef[];
+  edges: ForwardRefEdge[];
+  nodes: ForwardRefNode[];
+  truncated: boolean;
+  /** Target types dropped because `maxEdges` was reached. */
+  omittedByTargetType: Record<string, number>;
+  /** Non-fatal warnings (missing files, missing definitions, capped chains). */
+  warnings: string[];
+}
+
+/** A parsed XML file plus the raw text, as needed by the DOM walk. */
+export interface LoadedXmlFile {
+  parse: XmlDocument;
+  lineMap: LineMap;
+  text: string;
+}
+
+export type XmlFileLoader = (file: string) => Promise<LoadedXmlFile | null>;
+
+const DEFAULT_MAX_EDGES = 200;
+const MAX_DEPTH_LIMIT = 3;
+/**
+ * Inheritance is walked at the same depth, so the chain length is capped
+ * separately to keep pathological hierarchies from expanding without bound.
+ */
+const MAX_INHERIT_CHAIN = 8;
+
+/** Parses a file's text into the shape this module needs. */
+export function parseLoadedXml(text: string): LoadedXmlFile {
+  return { parse: parseXml(text), lineMap: new LineMap(text), text };
+}
+
+/**
+ * Resolves the definitions to start from, then walks their outgoing
+ * references. Returns an empty result (with a warning) when nothing matches.
+ */
+export async function collectAssetReferences(
+  index: ModIndex,
+  id: string,
+  type: string | null,
+  loadFile: XmlFileLoader,
+  options: ForwardRefOptions = {},
+): Promise<ForwardRefResult> {
+  const wanted = id.toLowerCase();
+  const wantedType = type?.toLowerCase() ?? null;
+  const roots = (index.assetsById.get(wanted) ?? []).filter(
+    (d) => !wantedType || d.type.toLowerCase() === wantedType,
+  );
+  if (!roots.length) {
+    return {
+      roots: [],
+      edges: [],
+      nodes: [],
+      truncated: false,
+      omittedByTargetType: {},
+      warnings: [
+        `No definition found for id "${id}"${type ? ` of type "${type}"` : ""}.`,
+      ],
+    };
+  }
+  const result = await collectForwardReferences(index, roots, loadFile, options);
+  return { ...result, roots };
+}
+
+/**
+ * Walks the outgoing references of `roots` and returns bounded edges.
+ */
+export async function collectForwardReferences(
+  index: ModIndex,
+  roots: readonly AssetDef[],
+  loadFile: XmlFileLoader,
+  options: ForwardRefOptions = {},
+): Promise<ForwardRefResult> {
+  const depthLimit = clampDepth(options.depth);
+  const maxEdges = Math.max(1, Math.floor(options.maxEdges ?? DEFAULT_MAX_EDGES));
+  const targetTypes = (options.targetTypes ?? []).filter(Boolean);
+  const includeUnresolved = options.includeUnresolved ?? false;
+  const includeInheritance = options.includeInheritance ?? true;
+
+  const edges: ForwardRefEdge[] = [];
+  const nodes = new Map<string, ForwardRefNode>();
+  const omitted = new Map<string, number>();
+  const warnings: string[] = [];
+  let truncated = false;
+  let edgeCount = 0;
+
+  const fileCache = new Map<string, LoadedXmlFile | null>();
+  const load = async (file: string): Promise<LoadedXmlFile | null> => {
+    const key = file.toLowerCase();
+    if (!fileCache.has(key)) {
+      try {
+        fileCache.set(key, await loadFile(file));
+      } catch {
+        fileCache.set(key, null);
+      }
+    }
+    return fileCache.get(key) ?? null;
+  };
+
+  interface WorkItem {
+    /** Asset whose XML is walked. */
+    def: AssetDef;
+    /** 0-based expansion level. */
+    level: number;
+    /** Asset the edges are attributed to (the queried asset). */
+    effective: { type: string; id: string };
+    /** Chain from `effective` (exclusive) down to `def` (inclusive). */
+    trail: { type: string; id: string }[];
+  }
+
+  const queue: WorkItem[] = roots.map((def) => ({
+    def,
+    level: 0,
+    effective: { type: def.type, id: def.id },
+    trail: [],
+  }));
+  const visited = new Set<string>();
+
+  const matchesTargetType = (typeName: string): boolean =>
+    targetTypes.length === 0 ||
+    targetTypes.some((wanted) => isAssignableTo(typeName, wanted));
+
+  const addEdge = (
+    level: number,
+    effective: WorkItem["effective"],
+    trail: WorkItem["trail"],
+    via: ForwardRefVia,
+    target: ForwardRefTarget | null,
+    source: ForwardRefEdge["source"],
+    value?: string,
+  ): void => {
+    // `targetTypes` drops edges the caller did not ask for. `inheritFrom`
+    // edges always survive: they explain where the remaining edges came from
+    // (an inherited weapon lives in the ancestor's file, and editing the
+    // derived asset would be wrong). This filter is applied before the edge
+    // cap so `omittedByTargetType` only reports cap-driven truncation.
+    if (target && via.kind !== "inheritFrom" && !matchesTargetType(target.type)) {
+      return;
+    }
+    if (edgeCount >= maxEdges) {
+      truncated = true;
+      const bucket = target?.type ?? "#unresolved";
+      omitted.set(bucket, (omitted.get(bucket) ?? 0) + 1);
+      return;
+    }
+    edgeCount++;
+    const edge: ForwardRefEdge = {
+      depth: level + 1,
+      from: { type: effective.type, id: effective.id },
+      to: target,
+      via,
+      source,
+    };
+    if (trail.length) {
+      const owner = trail[trail.length - 1];
+      edge.definedIn = { type: owner.type, id: owner.id };
+    }
+    if (value !== undefined) edge.value = value;
+    edges.push(edge);
+
+    if (target) {
+      const key = nodeKey(target);
+      const existing = nodes.get(key);
+      if (!existing || level + 1 < existing.depth) {
+        nodes.set(key, { ...target, depth: level + 1 });
+      }
+    }
+  };
+
+  while (queue.length) {
+    const item = queue.shift()!;
+    const { def, level, effective, trail } = item;
+    const visitKey = [
+      effective.type,
+      effective.id.toLowerCase(),
+      def.type,
+      def.id.toLowerCase(),
+      def.file.toLowerCase(),
+      def.line,
+    ].join("\u0000");
+    if (visited.has(visitKey)) continue;
+    visited.add(visitKey);
+
+    const loaded = await load(def.file);
+    if (!loaded) {
+      warnings.push(`Could not read ${def.file} (definition of ${def.type}:${def.id}).`);
+      continue;
+    }
+    const ownerEl = findDefinitionElement(loaded, def);
+    if (!ownerEl) {
+      warnings.push(
+        `Could not locate <${def.type} id="${def.id}"> inside ${def.file}; the index line may be stale.`,
+      );
+      continue;
+    }
+
+    const sourceAt = (offset: number): ForwardRefEdge["source"] => {
+      const pos = loaded.lineMap.positionAt(offset);
+      return { file: def.file, line: pos.line + 1, character: pos.character };
+    };
+
+    for (const el of subtreeInDocumentOrder(ownerEl)) {
+      const elType = resolveElementType(el);
+      const elLocal = localName(el.name);
+      const parentLocal = el.parent ? localName(el.parent.name) : null;
+
+      for (const attr of el.attrs) {
+        if (!attr.hasValue) continue;
+        const nameLower = attr.name.toLowerCase();
+        // inheritFrom belongs to the asset element itself and is handled
+        // separately below so it can also expand the ancestor chain.
+        if (nameLower === "inheritfrom") continue;
+        const value = attr.value;
+        if (!value || value.startsWith("$") || value.startsWith("=")) continue;
+        if (!isReferenceAttributeOfType(elType, attr.name)) continue;
+
+        const via: ForwardRefVia = {
+          kind: "attribute",
+          element: elLocal,
+          parent: parentLocal,
+          attribute: attr.name,
+        };
+        const source = sourceAt(attr.valueStart);
+        const targets = resolveReferenceTargetsForType(index, elType, attr.name, value);
+        if (!targets.length) {
+          if (includeUnresolved) addEdge(level, effective, trail, via, null, source, value);
+          continue;
+        }
+        for (const target of targets) {
+          const to = targetOf(target.def);
+          addEdge(level, effective, trail, via, to, source);
+          if (level + 1 < depthLimit) {
+            queue.push({
+              def: target.def,
+              level: level + 1,
+              effective: { type: target.def.type, id: target.def.id },
+              trail: [],
+            });
+          }
+        }
+      }
+
+      // Simple-content references (e.g. <CreateObject>temp_id</CreateObject>).
+      if (elType && isReferenceContentType(elType) && !el.selfClosing && el.closeTagStart >= 0) {
+        const raw = loaded.text.slice(el.startTagEnd, el.closeTagStart);
+        const value = raw.trim();
+        if (
+          !value ||
+          value.startsWith("$") ||
+          value.startsWith("=") ||
+          value.includes("<")
+        ) {
+          continue;
+        }
+        const start = el.startTagEnd + raw.indexOf(value);
+        const via: ForwardRefVia = {
+          kind: "content",
+          element: elLocal,
+          parent: parentLocal,
+          attribute: null,
+        };
+        const source = sourceAt(start);
+        const targets = resolveContentReferenceTargets(index, elType, value);
+        if (!targets.length) {
+          if (includeUnresolved) addEdge(level, effective, trail, via, null, source, value);
+          continue;
+        }
+        for (const target of targets) {
+          const to = targetOf(target.def);
+          addEdge(level, effective, trail, via, to, source);
+          if (level + 1 < depthLimit) {
+            queue.push({
+              def: target.def,
+              level: level + 1,
+              effective: { type: target.def.type, id: target.def.id },
+              trail: [],
+            });
+          }
+        }
+      }
+    }
+
+    // inheritFrom on the definition element: walk the ancestor at the SAME
+    // level so its XML contributes to the queried asset's effective definition.
+    if (includeInheritance) {
+      const inheritAttr = ownerEl.attrs.find(
+        (a) => a.name.toLowerCase() === "inheritfrom",
+      );
+      const value = inheritAttr?.value;
+      if (inheritAttr?.hasValue && value && !value.startsWith("$") && !value.startsWith("=")) {
+        const via: ForwardRefVia = {
+          kind: "inheritFrom",
+          element: localName(ownerEl.name),
+          parent: ownerEl.parent ? localName(ownerEl.parent.name) : null,
+          attribute: inheritAttr.name,
+        };
+        const source = sourceAt(inheritAttr.valueStart);
+        const targets = resolveReferenceTargetsForType(
+          index,
+          def.type,
+          "inheritFrom",
+          value,
+        );
+        if (!targets.length) {
+          if (includeUnresolved) addEdge(level, effective, trail, via, null, source, value);
+        } else {
+          for (const target of targets) {
+            const to = targetOf(target.def);
+            addEdge(level, effective, trail, via, to, source, value);
+            // The trail records the asset whose XML we are about to walk, so
+            // edges found there report the correct `definedIn`.
+            const nextTrail = [
+              ...trail,
+              { type: target.def.type, id: target.def.id },
+            ];
+            if (nextTrail.length < MAX_INHERIT_CHAIN) {
+              queue.push({ def: target.def, level, effective, trail: nextTrail });
+            } else {
+              warnings.push(
+                `Inheritance chain for ${effective.type}:${effective.id} exceeded ${MAX_INHERIT_CHAIN} levels; deeper ancestors were not walked.`,
+              );
+            }
+          }
+        }
+      }
+    }
+  }
+
+  return {
+    roots: [...roots],
+    edges,
+    nodes: [...nodes.values()].sort(
+      (a, b) => a.depth - b.depth || a.type.localeCompare(b.type) || a.id.localeCompare(b.id),
+    ),
+    truncated,
+    omittedByTargetType: Object.fromEntries(omitted),
+    warnings,
+  };
+}
+
+function clampDepth(depth: number | undefined): number {
+  if (depth == null || !Number.isFinite(depth)) return 1;
+  return Math.max(1, Math.min(MAX_DEPTH_LIMIT, Math.floor(depth)));
+}
+
+function targetOf(def: AssetDef): ForwardRefTarget {
+  return { type: def.type, id: def.id, file: def.file, line: def.line };
+}
+
+function nodeKey(target: ForwardRefTarget): string {
+  return `${target.type}\u0000${target.id.toLowerCase()}\u0000${target.file.toLowerCase()}\u0000${target.line}`;
+}
+
+/**
+ * Finds the element defining `def` inside a parsed file.
+ *
+ * The index stores a line number for the `id` attribute, so an exact line
+ * match is the strongest signal; top-level placement is the next best. This
+ * matters when a nested element reuses the same id.
+ */
+export function findDefinitionElement(
+  loaded: LoadedXmlFile,
+  def: Pick<AssetDef, "id" | "line">,
+): XmlElement | null {
+  const wanted = def.id.toLowerCase();
+  const root = loaded.parse.root;
+  let best: XmlElement | null = null;
+  let bestScore = -1;
+  for (const el of loaded.parse.elements) {
+    const idAttr = el.attrs.find((a) => a.name.toLowerCase() === "id");
+    if (!idAttr?.hasValue) continue;
+    if (idAttr.value.toLowerCase() !== wanted) continue;
+    let score = 0;
+    const isTopLevel = el.parent === root || (root == null && el.parent == null);
+    if (isTopLevel) score += 2;
+    if (def.line > 0) {
+      const line = loaded.lineMap.positionAt(idAttr.valueStart).line + 1;
+      if (line === def.line) score += 4;
+    }
+    if (score > bestScore) {
+      bestScore = score;
+      best = el;
+    }
+  }
+  return best;
+}
+
+/** Depth-first, document-order element list for a subtree (no recursion). */
+export function subtreeInDocumentOrder(root: XmlElement): XmlElement[] {
+  const out: XmlElement[] = [];
+  const stack: XmlElement[] = [root];
+  while (stack.length) {
+    const el = stack.pop()!;
+    out.push(el);
+    for (let i = el.children.length - 1; i >= 0; i--) {
+      stack.push(el.children[i]);
+    }
+  }
+  return out;
+}

src/agent/liveQuery.ts

@@ -0,0 +1,147 @@
+/**
+ * Query helpers that operate directly on the live in-memory ModIndex.
+ *
+ * These are useful for local HTTP/live services where converting the full
+ * index to an external snapshot on every query would be wasteful.
+ *
+ * Pure TypeScript: no VS Code dependency.
+ */
+
+import { resolve } from "node:path";
+import type { AssetDef, DefineDef, ModIndex, ReferenceSite } from "../indexer/types";
+import { statusFromIndex } from "./snapshot";
+import type { AgentIndexStatus, AgentReferenceGroup } from "./types";
+
+function normalizePath(p: string): string {
+  return resolve(p).replace(/\\/g, "/").toLowerCase();
+}
+
+/** Finds asset definitions by id in the live index. */
+export function findAssetsLive(
+  index: ModIndex,
+  id: string,
+  type?: string | null,
+): AssetDef[] {
+  const wanted = id.toLowerCase();
+  const wantedType = type?.toLowerCase();
+  const candidates = index.assetsById.get(wanted) ?? [];
+  if (!wantedType) return candidates;
+  return candidates.filter((a) => a.type.toLowerCase() === wantedType);
+}
+
+/** Lists assets of one type in the live index. */
+export function listAssetsByTypeLive(
+  index: ModIndex,
+  type: string,
+  idPrefix = "",
+  limit?: number,
+): AssetDef[] {
+  const wantedType = type.toLowerCase();
+  const wantedPrefix = idPrefix.toLowerCase();
+  const byType = index.assets.get(type);
+  if (!byType) return [];
+  const out: AssetDef[] = [];
+  for (const [id, defs] of byType) {
+    if (!id.startsWith(wantedPrefix)) continue;
+    for (const def of defs) {
+      if (def.type.toLowerCase() !== wantedType) continue;
+      out.push(def);
+      if (limit != null && out.length >= limit) return out;
+    }
+  }
+  return out;
+}
+
+/**
+ * Converts the reverse reference map into groups for one asset id.
+ * Reference map keys are `type\0id\0file\0line`.
+ */
+export function findReferenceGroupsLive(
+  index: ModIndex,
+  id: string,
+  type?: string | null,
+): AgentReferenceGroup[] {
+  const wanted = id.toLowerCase();
+  const wantedType = type?.toLowerCase();
+  const groups: AgentReferenceGroup[] = [];
+  for (const [key, sites] of index.references) {
+    const parts = key.split("\u0000");
+    if (parts.length !== 4) continue;
+    const [typeName, defId, file, lineText] = parts;
+    if (defId.toLowerCase() !== wanted) continue;
+    if (wantedType && typeName.toLowerCase() !== wantedType) continue;
+    groups.push({
+      type: typeName,
+      id: defId,
+      file,
+      line: Number(lineText) || 0,
+      sites,
+    });
+  }
+  return groups;
+}
+
+/** Flattens live reference groups into sites. */
+export function findReferenceSitesLive(
+  index: ModIndex,
+  id: string,
+  type?: string | null,
+): ReferenceSite[] {
+  return findReferenceGroupsLive(index, id, type).flatMap((g) => g.sites);
+}
+
+/** Returns streams containing a file in the live index. */
+export function streamsForFileLive(
+  index: ModIndex,
+  file: string,
+): ModIndex["streams"] {
+  const key = normalizePath(file);
+  return index.streams.filter((s) =>
+    [...s.files].some((candidate) => normalizePath(candidate) === key),
+  );
+}
+
+/** True when a file belongs to a live stream. */
+export function isFileActiveLive(index: ModIndex, file: string): boolean {
+  return streamsForFileLive(index, file).length > 0;
+}
+
+/** Finds defines by name in the live index. */
+export function findDefineLive(
+  index: ModIndex,
+  name: string,
+): DefineDef[] {
+  const wanted = name.toLowerCase();
+  return index.defines.get(wanted) ?? [];
+}
+
+/** Resolves Include source using the live source-candidate list. */
+export function resolveIncludeLive(
+  index: ModIndex,
+  source: string,
+): { source: string; path: string } | null {
+  const wanted = source.toLowerCase();
+  const hit = index.sourceCandidates.find(
+    (c) => c.source.toLowerCase() === wanted,
+  );
+  return hit ? { source: hit.source, path: hit.path } : null;
+}
+
+/**
+ * Returns a status object for the live index.
+ *
+ * `requestedProjectDir` is only echoed when no index is available, so callers
+ * can still verify which server they reached. It is never used to fake a
+ * `projectDir` when an index exists — the index is the source of truth.
+ */
+export function liveStatus(
+  index: ModIndex | null | undefined,
+  requestedProjectDir?: string,
+): AgentIndexStatus {
+  return statusFromIndex(index, requestedProjectDir);
+}
+
+/** Every project root this index belongs to (for `/projects` listing). */
+export function knownProjectDirs(index: ModIndex | null | undefined): string[] {
+  return index ? [index.projectDir] : [];
+}

src/agent/localServer.ts

@@ -0,0 +1,268 @@
+/**
+ * Local read-only HTTP server for live RA3 Mod XML index queries.
+ *
+ * The server runs inside the VS Code extension host when the user has enabled
+ * AI Agent access. It listens only on 127.0.0.1 and requires a bearer token so
+ * unrelated local processes cannot query it by accident.
+ *
+ * Requests may carry `?project=<dir>` to select which project's index answers
+ * the query. When omitted, the server falls back to the active project. Every
+ * response echoes `index.projectDir` so the caller can verify it reached the
+ * server/project it asked for — see docs/ai-agent-integration-plan.md §10 for
+ * why that check is required in multi-window setups.
+ *
+ * Pure TypeScript: no VS Code dependency.
+ */
+
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import type { AddressInfo } from "node:net";
+import type { ModIndex } from "../indexer/types";
+import {
+  collectAssetReferences,
+  type ForwardRefOptions,
+  type XmlFileLoader,
+} from "./forwardRefs";
+import {
+  findAssetsLive,
+  findDefineLive,
+  findReferenceGroupsLive,
+  isFileActiveLive,
+  listAssetsByTypeLive,
+  liveStatus,
+  resolveIncludeLive,
+} from "./liveQuery";
+
+const USAGE_GUIDE = `RA3 Mod XML live index query API
+
+Endpoints (all require Authorization: Bearer <token>):
+  GET /status
+  GET /projects
+  GET /find_asset?id=...&type=...
+  GET /find_references?id=...&type=...
+  GET /get_asset_references?id=...&type=...&depth=1&targetTypes=A,B&maxEdges=200
+  GET /list_assets?type=...&prefix=...&limit=...
+  GET /is_file_active?path=...
+  GET /find_define?name=...
+  GET /resolve_include?source=...
+  GET /get_usage_guide
+
+All endpoints accept an optional ?project=<absolute dir> selector. Responses
+echo index.projectDir; treat the result as belonging to a different project
+when it does not match what you asked for.
+`;
+
+export interface LocalServerHandle {
+  port: number;
+  token: string;
+  close(): Promise<void>;
+}
+
+export interface LocalServerOptions {
+  /** Returns the current in-memory index for a project (null when unknown). */
+  getIndex: (projectDir?: string) => ModIndex | null;
+  /** Every project root the live workspace currently knows about. */
+  listProjects?: () => string[];
+  /**
+   * Reads + parses one XML file. Required by /get_asset_references, which
+   * needs element context that the index does not store.
+   */
+  loadFile?: XmlFileLoader;
+  token?: string;
+  /** Defaults to an OS-assigned port on 127.0.0.1. */
+  port?: number;
+}
+
+function sendJson(res: ServerResponse, status: number, value: unknown): void {
+  const body = JSON.stringify(value);
+  res.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "content-length": Buffer.byteLength(body),
+  });
+  res.end(body);
+}
+
+function sendText(res: ServerResponse, status: number, text: string): void {
+  res.writeHead(status, {
+    "content-type": "text/plain; charset=utf-8",
+    "content-length": Buffer.byteLength(text),
+  });
+  res.end(text);
+}
+
+function isAuthorized(req: IncomingMessage, token: string): boolean {
+  const header = req.headers.authorization ?? "";
+  return header === `Bearer ${token}`;
+}
+
+/** Parses a comma-separated `targetTypes` parameter. */
+function parseList(raw: string | null): string[] {
+  if (!raw) return [];
+  return raw
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+function parseNumber(raw: string | null): number | undefined {
+  if (raw == null || raw === "") return undefined;
+  const value = Number(raw);
+  return Number.isFinite(value) ? value : undefined;
+}
+
+function forwardRefOptionsFrom(q: URLSearchParams): ForwardRefOptions {
+  return {
+    depth: parseNumber(q.get("depth")),
+    targetTypes: parseList(q.get("targetTypes")),
+    maxEdges: parseNumber(q.get("maxEdges")),
+    includeUnresolved: q.get("includeUnresolved") === "true",
+  };
+}
+
+async function handle(
+  options: LocalServerOptions,
+  token: string,
+  req: IncomingMessage,
+  res: ServerResponse,
+): Promise<void> {
+  if (!isAuthorized(req, token)) {
+    sendJson(res, 401, { error: "Unauthorized" });
+    return;
+  }
+  const url = new URL(req.url ?? "/", "http://127.0.0.1");
+  const q = url.searchParams;
+  const projectDir = q.get("project") ?? undefined;
+  const index = options.getIndex(projectDir);
+  // When an index exists its own projectDir is authoritative; the selector is
+  // only echoed for no-index responses so callers can still verify the server.
+  const status = liveStatus(index, projectDir);
+
+  switch (url.pathname) {
+    case "/status":
+      sendJson(res, 200, status);
+      return;
+
+    case "/projects":
+      sendJson(res, 200, {
+        index: status,
+        data: options.listProjects?.() ?? [],
+      });
+      return;
+
+    case "/find_asset":
+      sendJson(res, 200, {
+        index: status,
+        data: index ? findAssetsLive(index, q.get("id") ?? "", q.get("type")) : [],
+      });
+      return;
+
+    case "/find_references":
+      sendJson(res, 200, {
+        index: status,
+        data: index
+          ? findReferenceGroupsLive(index, q.get("id") ?? "", q.get("type"))
+          : [],
+      });
+      return;
+
+    case "/list_assets": {
+      const limit = parseNumber(q.get("limit"));
+      sendJson(res, 200, {
+        index: status,
+        data: index
+          ? listAssetsByTypeLive(index, q.get("type") ?? "", q.get("prefix") ?? "", limit)
+          : [],
+      });
+      return;
+    }
+
+    case "/is_file_active":
+      sendJson(res, 200, {
+        index: status,
+        data: { active: index ? isFileActiveLive(index, q.get("path") ?? "") : false },
+      });
+      return;
+
+    case "/find_define":
+      sendJson(res, 200, {
+        index: status,
+        data: index
+          ? findDefineLive(index, (q.get("name") ?? "").replace(/^\$/, ""))
+          : [],
+      });
+      return;
+
+    case "/resolve_include":
+      sendJson(res, 200, {
+        index: status,
+        data: index ? resolveIncludeLive(index, q.get("source") ?? "") : null,
+      });
+      return;
+
+    case "/get_asset_references": {
+      if (!index) {
+        sendJson(res, 200, {
+          index: status,
+          data: null,
+          error:
+            "get_asset_references requires a live index (VS Code must be open with the project indexed).",
+        });
+        return;
+      }
+      if (!options.loadFile) {
+        sendJson(res, 200, {
+          index: status,
+          data: null,
+          error: "The live server was started without XML file access.",
+        });
+        return;
+      }
+      const result = await collectAssetReferences(
+        index,
+        q.get("id") ?? "",
+        q.get("type"),
+        options.loadFile,
+        forwardRefOptionsFrom(q),
+      );
+      sendJson(res, 200, { index: status, data: result });
+      return;
+    }
+
+    case "/get_usage_guide":
+      sendText(res, 200, USAGE_GUIDE);
+      return;
+
+    default:
+      sendJson(res, 404, { error: `Not found: ${url.pathname}` });
+  }
+}
+
+/** Starts a local HTTP server; resolves once it is listening. */
+export async function startLocalServer(
+  options: LocalServerOptions,
+): Promise<LocalServerHandle> {
+  const token = options.token ?? randomToken();
+  const server = createServer((req, res) => {
+    void handle(options, token, req, res).catch((err) => {
+      sendJson(res, 500, {
+        error: err instanceof Error ? err.message : String(err),
+      });
+    });
+  });
+  await new Promise<void>((resolveListen, reject) => {
+    server.once("error", reject);
+    server.listen(options.port ?? 0, "127.0.0.1", () => resolveListen());
+  });
+  const address = server.address() as AddressInfo;
+  return {
+    port: address.port,
+    token,
+    close: () =>
+      new Promise<void>((resolveClose, rejectClose) => {
+        server.close((err) => (err ? rejectClose(err) : resolveClose()));
+      }),
+  };
+}
+
+function randomToken(): string {
+  return `ra3-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}

src/agent/mcpServer.ts

@@ -0,0 +1,499 @@
+/**
+ * Minimal MCP (Model Context Protocol) stdio server exposing the RA3 Mod XML
+ * agent snapshot query API.
+ *
+ * This is intentionally dependency-free. It speaks the JSON-RPC-over-stdio
+ * subset used by MCP clients:
+ *
+ *   initialize
+ *   notifications/initialized
+ *   ping
+ *   tools/list
+ *   tools/call
+ *
+ * Usage:
+ *   node out/agent/mcpServer.js --project D:/Mods/Example
+ *   node out/agent/mcpServer.js --snapshot /path/to/snapshot.json.gz
+ */
+
+import { createInterface } from "node:readline";
+import {
+  isProcessAlive,
+  readEndpoint,
+  readEndpointForProject,
+} from "./endpoint";
+import { readSnapshotFile, snapshotPathForProject } from "./snapshot";
+import {
+  findAssets,
+  findDefine,
+  findReferenceGroups,
+  isFileActive,
+  listAssetsByType,
+  resolveIncludeSource,
+  statusFromSnapshot,
+} from "./query";
+import type { AgentIndexSnapshot } from "./types";
+
+interface McpTool {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  handler: (args: Record<string, unknown>, snapshot: AgentIndexSnapshot | null) => unknown;
+}
+
+const USAGE_GUIDE = `RA3 Mod XML index query tools
+
+This MCP server exposes the semantic index built by the RA3 Mod XML VS Code extension.
+
+Use these tools instead of full-text grepping the XML tree when you need exact facts:
+- find_asset(id, type?) -> definition sites (file/line/origin/stream)
+- find_references(id, type?) -> semantic reference sites
+- get_asset_references(id, type?, depth?, targetTypes?) -> outgoing reference EDGES with element context
+- list_assets_by_type(type, prefix?, limit?) -> assets of a type
+- is_file_active(path) -> whether a file is part of an indexed include stream
+- find_define(name) -> $DEFINE definitions
+- resolve_include(source) -> candidate source file
+- get_status() -> current index state
+
+Tips:
+- Asset ids are case-insensitive.
+- Prefer passing type when the same id exists for multiple asset types.
+- Always check the returned index state; if it is stale/incomplete, treat results as provisional.
+- Use get_asset_references to follow "which weapon/model/upgrade does this asset use" chains.
+  It returns edges annotated with the element name, parent element and attribute that produced
+  them, plus the exact XML file/line, so you do not have to read source to find the link.
+  Start with depth 1 (the default) and pass targetTypes (e.g. ["WeaponTemplate"]) to cut noise.
+  Edges with a "definedIn" field come from an inheritFrom ancestor's XML.
+  When "truncated" is true, read "omittedByTargetType" and narrow the query instead of retrying.
+- Do not attempt to read the entire snapshot file; query narrowly.`;
+
+const TOOLS: McpTool[] = [
+  {
+    name: "get_status",
+    description: "Returns the current index state and basic statistics.",
+    inputSchema: { type: "object", properties: {} },
+    handler: (_args, snapshot) => statusFromSnapshot(snapshot),
+  },
+  {
+    name: "find_asset",
+    description: "Finds asset definitions by id, optionally filtered by asset type.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Asset id to find" },
+        type: { type: "string", description: "Optional asset type filter" },
+      },
+      required: ["id"],
+    },
+    handler: (args, snapshot) => {
+      const id = String(args.id ?? "");
+      if (!snapshot) return statusFromSnapshot(snapshot);
+      return {
+        index: statusFromSnapshot(snapshot),
+        data: findAssets(snapshot, id, args.type ? String(args.type) : null),
+      };
+    },
+  },
+  {
+    name: "find_references",
+    description: "Finds semantic reference sites pointing to an asset id, optionally filtered by type.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Asset id whose references to find" },
+        type: { type: "string", description: "Optional asset type filter" },
+      },
+      required: ["id"],
+    },
+    handler: (args, snapshot) => {
+      const id = String(args.id ?? "");
+      if (!snapshot) return statusFromSnapshot(snapshot);
+      return {
+        index: statusFromSnapshot(snapshot),
+        data: findReferenceGroups(snapshot, id, args.type ? String(args.type) : null),
+      };
+    },
+  },
+  {
+    name: "list_assets_by_type",
+    description: "Lists asset definitions of one type, optionally filtered by id prefix.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        type: { type: "string", description: "Asset type" },
+        prefix: { type: "string", description: "Optional id prefix" },
+        limit: { type: "number", description: "Maximum number of results" },
+      },
+      required: ["type"],
+    },
+    handler: (args, snapshot) => {
+      const type = String(args.type ?? "");
+      if (!snapshot) return statusFromSnapshot(snapshot);
+      const limit = typeof args.limit === "number" ? args.limit : undefined;
+      return {
+        index: statusFromSnapshot(snapshot),
+        data: listAssetsByType(snapshot, type, args.prefix ? String(args.prefix) : "", limit),
+      };
+    },
+  },
+  {
+    name: "is_file_active",
+    description: "Returns whether a file belongs to an indexed include stream (i.e. is not a dead file).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Absolute file path" },
+      },
+      required: ["path"],
+    },
+    handler: (args, snapshot) => {
+      const path = String(args.path ?? "");
+      if (!snapshot) return statusFromSnapshot(snapshot);
+      return {
+        index: statusFromSnapshot(snapshot),
+        data: { active: isFileActive(snapshot, path) },
+      };
+    },
+  },
+  {
+    name: "find_define",
+    description: "Finds $DEFINE constants by name.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Define name (with or without leading $)" },
+      },
+      required: ["name"],
+    },
+    handler: (args, snapshot) => {
+      const name = String(args.name ?? "").replace(/^\$/, "");
+      if (!snapshot) return statusFromSnapshot(snapshot);
+      return {
+        index: statusFromSnapshot(snapshot),
+        data: findDefine(snapshot, name),
+      };
+    },
+  },
+  {
+    name: "resolve_include",
+    description: "Resolves an Include source string from the snapshot's candidate list.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        source: { type: "string", description: "Include source, e.g. DATA:Units/Example.xml" },
+      },
+      required: ["source"],
+    },
+    handler: (args, snapshot) => {
+      const source = String(args.source ?? "");
+      if (!snapshot) return statusFromSnapshot(snapshot);
+      return {
+        index: statusFromSnapshot(snapshot),
+        data: resolveIncludeSource(snapshot, source),
+      };
+    },
+  },
+  {
+    name: "get_asset_references",
+    description:
+      "Returns the outgoing references (edges) of an asset: which assets it references, through which element/attribute, and at which file/line. Also follows inheritFrom ancestors (marked with definedIn). Live index required.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Asset id whose outgoing references to return" },
+        type: { type: "string", description: "Optional asset type filter" },
+        depth: {
+          type: "number",
+          description:
+            "Levels of assets to expand: 1 (default) = the asset itself, including inherited XML; max 3.",
+        },
+        targetTypes: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Only keep edges whose target is assignable to one of these types, e.g. [\"WeaponTemplate\"].",
+        },
+        maxEdges: { type: "number", description: "Hard cap on returned edges (default 200)." },
+        includeUnresolved: {
+          type: "boolean",
+          description: "Also return edges whose reference value could not be resolved.",
+        },
+      },
+      required: ["id"],
+    },
+    // Live-only: element context is not stored in the on-disk snapshot.
+    handler: () => ({
+      index: { state: "no_index" },
+      error:
+        "get_asset_references requires a live index. Open the project in VS Code (with AI Agent access enabled) and retry.",
+    }),
+  },
+  {
+    name: "get_usage_guide",
+    description: "Returns guidance for using the RA3 Mod XML index tools.",
+    inputSchema: { type: "object", properties: {} },
+    handler: () => ({ text: USAGE_GUIDE }),
+  },
+];
+
+/** Tools that can only be answered by the live extension server. */
+const LIVE_ONLY_TOOLS = new Set(["get_asset_references"]);
+
+export function liveUrlForTool(
+  endpointUrl: string,
+  projectDir: string | null,
+  toolName: string,
+  args: Record<string, unknown>,
+): string | null {
+  const base = endpointUrl.replace(/\/$/, "");
+  const q = new URLSearchParams();
+  // Always pin the requested project. Without this the server would silently
+  // answer from whatever project its active editor points at.
+  if (projectDir) q.set("project", projectDir);
+  switch (toolName) {    case "get_status":
+      return q.toString() ? `${base}/status?${q}` : `${base}/status`;
+    case "find_asset":
+      q.set("id", String(args.id ?? ""));
+      if (args.type != null) q.set("type", String(args.type));
+      return `${base}/find_asset?${q}`;
+    case "find_references":
+      q.set("id", String(args.id ?? ""));
+      if (args.type != null) q.set("type", String(args.type));
+      return `${base}/find_references?${q}`;
+    case "get_asset_references":
+      q.set("id", String(args.id ?? ""));
+      if (args.type != null) q.set("type", String(args.type));
+      if (args.depth != null) q.set("depth", String(args.depth));
+      if (Array.isArray(args.targetTypes)) {
+        q.set("targetTypes", (args.targetTypes as unknown[]).map(String).join(","));
+      }
+      if (args.maxEdges != null) q.set("maxEdges", String(args.maxEdges));
+      if (args.includeUnresolved != null) {
+        q.set("includeUnresolved", String(args.includeUnresolved));
+      }
+      return `${base}/get_asset_references?${q}`;
+    case "list_assets_by_type":
+      q.set("type", String(args.type ?? ""));
+      if (args.prefix != null) q.set("prefix", String(args.prefix));
+      if (args.limit != null) q.set("limit", String(args.limit));
+      return `${base}/list_assets?${q}`;
+    case "is_file_active":
+      q.set("path", String(args.path ?? ""));
+      return `${base}/is_file_active?${q}`;
+    case "find_define":
+      q.set("name", String(args.name ?? ""));
+      return `${base}/find_define?${q}`;
+    case "resolve_include":
+      q.set("source", String(args.source ?? ""));
+      return `${base}/resolve_include?${q}`;
+    default:
+      return null;
+  }
+}
+
+export function normalizePath(p: string): string {
+  return p.replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase();
+}
+
+/**
+ * Rejects a live response that belongs to a different project than the one
+ * this MCP client was started for. This is the guard against the
+ * multi-window cross-talk described in docs/ai-agent-integration-plan.md §10:
+ * returning another project's data silently would be worse than returning
+ * nothing, because the agent cannot tell the difference.
+ */
+export function responseProjectMismatch(
+  payload: unknown,
+  projectDir: string | null,
+): boolean {
+  if (!projectDir) return false;
+  const index = (payload as { index?: { projectDir?: string } } | null)?.index;
+  const reported = index?.projectDir;
+  if (!reported) return false;
+  return normalizePath(reported) !== normalizePath(projectDir);
+}
+
+/** Cooldown after a failed live attempt, to avoid a probe per tool call. */
+const LIVE_RETRY_COOLDOWN_MS = 5000;
+let liveUnavailableUntil = 0;
+
+interface LiveResult {
+  payload: unknown;
+  /** True when the live server answered but for a different project. */
+  mismatched: boolean;
+}
+
+/** Tries the live extension server; returns null when unavailable. */
+async function tryLiveQuery(
+  toolName: string,
+  args: Record<string, unknown>,
+  projectDir: string | null,
+  agentHome?: string,
+): Promise<LiveResult | null> {
+  if (Date.now() < liveUnavailableUntil) return null;
+  // Prefer the per-project endpoint so two open windows cannot shadow each
+  // other; fall back to the legacy global file only when it matches.
+  let endpoint = projectDir
+    ? await readEndpointForProject(projectDir, agentHome)
+    : null;
+  if (!endpoint) {
+    const fallback = await readEndpoint(agentHome);
+    if (
+      fallback &&
+      (!projectDir ||
+        !fallback.projectDir ||
+        normalizePath(fallback.projectDir) === normalizePath(projectDir))
+    ) {
+      endpoint = fallback;
+    }
+  }
+  if (!endpoint) return null;
+  // A crashed VS Code can leave the file behind; a dead PID means stale.
+  if (!isProcessAlive(endpoint.processId)) return null;
+
+  const url = liveUrlForTool(endpoint.url, projectDir, toolName, args);
+  if (!url) return null;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 1500);
+  try {
+    const res = await fetch(url, {
+      headers: { authorization: `Bearer ${endpoint.token}` },
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      if (res.status === 401 || res.status === 404) return null;
+      return null;
+    }
+    const payload: unknown = await res.json();
+    return { payload, mismatched: responseProjectMismatch(payload, projectDir) };
+  } catch {
+    liveUnavailableUntil = Date.now() + LIVE_RETRY_COOLDOWN_MS;
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function sendMessage(message: unknown): void {
+  process.stdout.write(`${JSON.stringify(message)}\n`);
+}
+
+function resultFor(id: unknown, result: unknown): unknown {
+  return { jsonrpc: "2.0", id, result };
+}
+
+function errorFor(id: unknown, code: number, message: string): unknown {
+  return { jsonrpc: "2.0", id, error: { code, message } };
+}
+
+async function handleRequest(
+  message: Record<string, unknown>,
+  snapshot: AgentIndexSnapshot | null,
+  projectDir: string | null,
+  agentHome?: string,
+): Promise<unknown | null> {
+  const method = String(message.method ?? "");
+  const id = message.id;
+  const params = (message.params ?? {}) as Record<string, unknown>;
+
+  switch (method) {
+    case "initialize":
+      return resultFor(id, {
+        protocolVersion: params.protocolVersion ?? "2024-11-05",
+        capabilities: { tools: {} },
+        serverInfo: { name: "ra3-mod-xml", version: "0.1.0" },
+      });
+    case "ping":
+      return resultFor(id, {});
+    case "tools/list":
+      return resultFor(id, {
+        tools: TOOLS.map((tool) => ({
+          name: tool.name,
+          description: tool.description,
+          inputSchema: tool.inputSchema,
+        })),
+      });
+    case "tools/call": {
+      const toolName = String(params.name ?? "");
+      const tool = TOOLS.find((t) => t.name === toolName);
+      if (!tool) return errorFor(id, -32602, `Unknown tool: ${toolName}`);
+      const args = (params.arguments ?? {}) as Record<string, unknown>;
+      const live = await tryLiveQuery(toolName, args, projectDir, agentHome);
+
+      if (live?.mismatched) {
+        // The server answered for another project. Refuse it: a plausible
+        // wrong answer is worse than an explicit failure.
+        liveUnavailableUntil = Date.now() + LIVE_RETRY_COOLDOWN_MS;
+        return textResult(id, {
+          index: { state: "error", projectDir: projectDir ?? undefined },
+          error: `The live server answered for a different project than "${projectDir}"; refusing the result. Re-run "RA3 Mod XML: Enable AI Agent access…" for this project.`,
+        });
+      }
+
+      if (LIVE_ONLY_TOOLS.has(toolName)) {
+        // Report a clear reason instead of an empty result, so the agent does
+        // not conclude "this asset has no references".
+        return textResult(
+          id,
+          live?.payload ?? {
+            index: { state: "no_index", projectDir: projectDir ?? undefined },
+            error: `"${toolName}" requires a live index. Open the project in VS Code with AI Agent access enabled, then retry.`,
+          },
+        );
+      }
+
+      const output = live?.payload ?? tool.handler(args, snapshot);
+      return textResult(id, output);
+    }
+    default:
+      // Notifications have no id; ignore them.
+      if (id === undefined) return null;
+      return errorFor(id, -32601, `Method not found: ${method}`);
+  }
+}
+
+/** Wraps any tool payload into an MCP text content result. */
+function textResult(id: unknown, payload: unknown): unknown {
+  const text = typeof payload === "string" ? payload : JSON.stringify(payload, null, 2);
+  return resultFor(id, { content: [{ type: "text", text }] });
+}
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+  let projectDir: string | null = null;
+  let snapshotPath: string | null = null;
+  let agentHome: string | undefined;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--project" || args[i] === "-p") projectDir = args[++i] ?? null;
+    else if (args[i] === "--snapshot" || args[i] === "-s") snapshotPath = args[++i] ?? null;
+    else if (args[i] === "--agent-home") agentHome = args[++i] ?? undefined;
+  }
+  const resolvedSnapshotPath =
+    snapshotPath ??
+    (projectDir ? snapshotPathForProject(projectDir, agentHome) : null);
+  let snapshot: AgentIndexSnapshot | null = null;
+  if (resolvedSnapshotPath) snapshot = await readSnapshotFile(resolvedSnapshotPath);
+
+  const rl = createInterface({
+    input: process.stdin,
+    crlfDelay: Infinity,
+  });
+  rl.on("line", (line) => {
+    if (!line.trim()) return;
+    let message: Record<string, unknown>;
+    try {
+      message = JSON.parse(line) as Record<string, unknown>;
+    } catch {
+      return;
+    }
+    void handleRequest(message, snapshot, projectDir, agentHome).then((response) => {
+      if (response != null) sendMessage(response);
+    });
+  });
+}
+
+// Only run the stdio loop when executed directly, so the module stays
+// importable by tests.
+if (typeof require !== "undefined" && require.main === module) {
+  void main();
+}

src/agent/query.ts

@@ -0,0 +1,158 @@
+/**
+ * Query helpers over the stable AgentIndexSnapshot.
+ *
+ * Pure TypeScript and dependency-free, so the same functions can back a CLI,
+ * MCP tools, or a local HTTP API.
+ */
+
+import { resolve } from "node:path";
+import type { AssetDef, ReferenceSite } from "../indexer/types";
+import type {
+  AgentDefine,
+  AgentIndexSnapshot,
+  AgentIndexStatus,
+  AgentReferenceGroup,
+  AgentStream,
+} from "./types";
+
+function normalizePath(p: string): string {
+  return resolve(p).replace(/\\/g, "/").toLowerCase();
+}
+
+/** Returns all asset definitions whose id equals `id`, optionally filtered by type. */
+export function findAssets(
+  snapshot: AgentIndexSnapshot,
+  id: string,
+  type?: string | null,
+): AssetDef[] {
+  const wanted = id.toLowerCase();
+  const wantedType = type?.toLowerCase();
+  const out: AssetDef[] = [];
+  for (const asset of snapshot.assets) {
+    if (asset.id.toLowerCase() !== wanted) continue;
+    if (wantedType && asset.type.toLowerCase() !== wantedType) continue;
+    out.push(asset);
+  }
+  return out;
+}
+
+/** Returns asset definitions whose type and id prefix match. */
+export function listAssetsByType(
+  snapshot: AgentIndexSnapshot,
+  type: string,
+  idPrefix = "",
+  limit?: number,
+): AssetDef[] {
+  const wantedType = type.toLowerCase();
+  const wantedPrefix = idPrefix.toLowerCase();
+  const out: AssetDef[] = [];
+  for (const asset of snapshot.assets) {
+    if (asset.type.toLowerCase() !== wantedType) continue;
+    if (!asset.id.toLowerCase().startsWith(wantedPrefix)) continue;
+    out.push(asset);
+    if (limit != null && out.length >= limit) break;
+  }
+  return out;
+}
+
+/** Returns reference groups pointing to definitions matching `id` and optional `type`. */
+export function findReferenceGroups(
+  snapshot: AgentIndexSnapshot,
+  id: string,
+  type?: string | null,
+): AgentReferenceGroup[] {
+  const wanted = id.toLowerCase();
+  const wantedType = type?.toLowerCase();
+  return snapshot.references.filter((r) => {
+    if (r.id.toLowerCase() !== wanted) return false;
+    if (wantedType && r.type.toLowerCase() !== wantedType) return false;
+    return true;
+  });
+}
+
+/** Flattens reference groups into plain reference sites. */
+export function findReferenceSites(
+  snapshot: AgentIndexSnapshot,
+  id: string,
+  type?: string | null,
+): ReferenceSite[] {
+  return findReferenceGroups(snapshot, id, type).flatMap((g) => g.sites);
+}
+
+/** True when a file belongs to at least one indexed stream. */
+export function isFileActive(snapshot: AgentIndexSnapshot, file: string): boolean {
+  const key = normalizePath(file);
+  return snapshot.streams.some((s) =>
+    s.files.some((candidate) => normalizePath(candidate) === key),
+  );
+}
+
+/** Returns the streams that contain a file. */
+export function streamsForFile(
+  snapshot: AgentIndexSnapshot,
+  file: string,
+): AgentStream[] {
+  const key = normalizePath(file);
+  return snapshot.streams.filter((s) =>
+    s.files.some((candidate) => normalizePath(candidate) === key),
+  );
+}
+
+/** Finds a define by case-insensitive name. */
+export function findDefine(
+  snapshot: AgentIndexSnapshot,
+  name: string,
+): AgentDefine[] {
+  const wanted = name.toLowerCase();
+  return snapshot.defines.filter((d) => d.name.toLowerCase() === wanted);
+}
+
+/** Resolves an Include source using the snapshot's candidate list. */
+export function resolveIncludeSource(
+  snapshot: AgentIndexSnapshot,
+  source: string,
+): { source: string; path: string } | null {
+  const wanted = source.toLowerCase();
+  const hit = snapshot.sourceCandidates.find(
+    (c) => c.source.toLowerCase() === wanted,
+  );
+  return hit ? { source: hit.source, path: hit.path } : null;
+}
+
+/** Returns the snapshot's status (ready_xml/ready/stale). */
+export function statusFromSnapshot(
+  snapshot: AgentIndexSnapshot | null | undefined,
+): AgentIndexStatus {
+  if (!snapshot) {
+    return { state: "no_index", detail: "No index snapshot is available." };
+  }
+  const state: AgentIndexStatus["state"] = snapshot.stale
+    ? "stale"
+    : !snapshot.complete
+      ? "ready_xml"
+      : "ready";
+  return {
+    state,
+    projectDir: snapshot.projectDir,
+    phase: snapshot.phase,
+    complete: snapshot.complete,
+    stale: snapshot.stale,
+    generatedAt: snapshot.generatedAt,
+    buildId: snapshot.buildId,
+    stats: snapshot.stats,
+  };
+}
+
+/** Convenience aggregate returned by MCP/CLI query tools. */
+export interface QueryResult<T> {
+  index: AgentIndexStatus;
+  data: T;
+}
+
+/** Wraps any query data with current index status. */
+export function withStatus<T>(snapshot: AgentIndexSnapshot | null, data: T): QueryResult<T> {
+  return {
+    index: statusFromSnapshot(snapshot),
+    data,
+  };
+}

src/agent/setup.ts

@@ -0,0 +1,160 @@
+/**
+ * Helpers for creating the stable MCP launcher and MCP client configuration.
+ *
+ * The launcher lives outside the VS Code extension install directory (under
+ * ~/.ra3modxml) so AI client configs do not break when the extension is
+ * updated to a new version. The extension refreshes the launcher on every
+ * activation/update.
+ *
+ * Pure TypeScript: no VS Code dependency.
+ */
+
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { defaultAgentHome } from "./snapshot";
+
+export interface McpConfigTarget {
+  id: string;
+  label: string;
+  path: string;
+}
+
+/** File name of the stable launcher on the current platform. */
+export function launcherFileName(): string {
+  return process.platform === "win32" ? "ra3-mod-xml-mcp.cmd" : "ra3-mod-xml-mcp";
+}
+
+/** Absolute path to the stable launcher under the agent home. */
+export function launcherPath(agentHome = defaultAgentHome()): string {
+  return join(agentHome, launcherFileName());
+}
+
+/**
+ * Path to the bundled MCP server inside an extension install/dev directory.
+ * The packaged extension ships this file under dist/agent/mcpServer.js.
+ */
+export function bundledMcpServerPath(extensionRoot: string): string {
+  return join(extensionRoot, "dist", "agent", "mcpServer.js");
+}
+
+/**
+ * Creates the stable launcher script. It points to the current extension's
+ * bundled MCP server and passes the project directory.
+ */
+export async function writeLauncher(
+  extensionRoot: string,
+  projectDir: string,
+  agentHome = defaultAgentHome(),
+): Promise<string> {
+  const server = bundledMcpServerPath(extensionRoot);
+  const launcher = launcherPath(agentHome);
+  await mkdir(dirname(launcher), { recursive: true });
+  if (process.platform === "win32") {
+    const content = [
+      "@echo off",
+      `node "${server}" --project "${projectDir}"`,
+      "",
+    ].join("\r\n");
+    await writeFile(launcher, content, "utf8");
+  } else {
+    const content = [
+      "#!/usr/bin/env sh",
+      `exec node "${server}" --project "${projectDir}"`,
+      "",
+    ].join("\n");
+    await writeFile(launcher, content, "utf8");
+    await chmod(launcher, 0o755);
+  }
+  return launcher;
+}
+
+/** MCP client config entry for one project. */
+export function mcpServerConfig(
+  launcher: string,
+  projectDir: string,
+): Record<string, unknown> {
+  return {
+    mcpServers: {
+      "ra3-mod-xml": {
+        command: launcher,
+        args: ["--project", projectDir],
+      },
+    },
+  };
+}
+
+/** Human-readable JSON config block users can paste into AI clients. */
+export function mcpConfigJson(
+  launcher: string,
+  projectDir: string,
+): string {
+  return JSON.stringify(mcpServerConfig(launcher, projectDir), null, 2);
+}
+
+/** Claude Desktop config path (Windows/macOS/Linux common locations). */
+export function claudeDesktopConfigPath(): string {
+  if (process.env.APPDATA) return join(process.env.APPDATA, "Claude", "claude_desktop_config.json");
+  return join(homedir(), ".config", "Claude", "claude_desktop_config.json");
+}
+
+/** Cursor's global MCP config path. */
+export function cursorGlobalConfigPath(): string {
+  return join(homedir(), ".cursor", "mcp.json");
+}
+
+/** Cursor's project-scoped MCP config path. */
+export function cursorProjectConfigPath(projectDir: string): string {
+  return join(projectDir, ".cursor", "mcp.json");
+}
+
+/** Common local MCP config files this extension can offer to update. */
+export function commonMcpConfigTargets(projectDir: string): McpConfigTarget[] {
+  return [
+    {
+      id: "claude-desktop",
+      label: "Claude Desktop",
+      path: claudeDesktopConfigPath(),
+    },
+    {
+      id: "cursor-global",
+      label: "Cursor (global)",
+      path: cursorGlobalConfigPath(),
+    },
+    {
+      id: "cursor-project",
+      label: "Cursor (current project)",
+      path: cursorProjectConfigPath(projectDir),
+    },
+  ];
+}
+
+/**
+ * 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.
+ */
+export async function addMcpServerToConfigFile(
+  filePath: string,
+  launcher: string,
+  projectDir: string,
+): Promise<void> {
+  let config: Record<string, unknown> = {};
+  try {
+    config = JSON.parse(await readFile(filePath, "utf8")) as Record<string, unknown>;
+  } catch {
+    // File absent or malformed: start fresh.
+  }
+  const servers = (config.mcpServers as Record<string, unknown> | undefined) ?? {};
+  servers["ra3-mod-xml"] = {
+    command: launcher,
+    args: ["--project", projectDir],
+  };
+  config.mcpServers = servers;
+  await mkdir(dirname(filePath), { recursive: true });
+  await writeFile(filePath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+
+/** Default path used for the agent home. */
+export function defaultAgentHomeForSetup(): string {
+  return join(homedir(), ".ra3modxml");
+}

src/agent/skill.ts

@@ -0,0 +1,333 @@
+/**
+ * Agent Skill generator/installer for the RA3 Mod XML MCP tools.
+ *
+ * The Skill focuses on the functionality itself: when to use it and how to
+ * use the RA3 Mod XML MCP query tools. It intentionally avoids referencing
+ * any project-specific docs (e.g. docs/codebase-navigation-guide.md) so the
+ * agent is not distracted by unrelated workspace guidance.
+ *
+ * Pure TypeScript: no VS Code dependency.
+ */
+
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { defaultAgentHome } from "./snapshot";
+
+export const SKILL_NAME = "ra3-mod-xml";
+export const SKILL_MARKER_FILE = ".ra3modxml-skill.json";
+
+const SKILL_MD = `---
+name: ra3-mod-xml
+description: Use the RA3 Mod XML semantic index to find asset definitions, references, outgoing references, active files, defines, and include sources in SAGE / BinaryAssetBuilder XML projects such as Command & Conquer: Red Alert 3 mods. Use this when you need exact facts about mod assets instead of guessing or full-text searching the XML tree.
+---
+
+# RA3 Mod XML Index
+
+This skill provides access to the semantic index built by the RA3 Mod XML VS Code extension.
+
+## When this skill applies
+
+Use these tools only for SAGE / BinaryAssetBuilder mod XML projects — the kind
+used by Command & Conquer: Red Alert 3 mods.
+
+Positive signals (any single one is enough to try the tools):
+
+- \`Data/Mod.xml\` exists.
+- \`Data/additionalmaps/mapmetadata_*.xml\` exists.
+- A \`*.babproj\` file exists.
+- XML whose root element is \`<AssetDeclaration>\`.
+- 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
+use them merely because a project contains XML, a build script, copied \`.xsd\`
+files, or a folder named \`Data\`. A file named \`CnC3Types.xsd\` refers to
+C&C3 (Tiberium Wars / Kane's Wrath) and is **not** by itself evidence of a
+Red Alert 3 mod. When the repository is not a SAGE / RA3 mod project, ignore
+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.
+
+In those cases read the files directly instead. Never present index results
+from one project as if they belonged to another.
+
+## When to use
+
+Use this skill when you need any of the following:
+
+- Find where an asset id is defined (GameObject, WeaponTemplate, Texture, etc.).
+- Find which files/positions reference an asset id.
+- Find which assets an asset references, and through which element/attribute.
+- List assets of a particular type.
+- Check whether a file is actually part of the active include graph (i.e. not a dead file).
+- Resolve an Include source string.
+- Look up a $DEFINE constant.
+- Get the current index status and statistics.
+
+Do not use full-text search over the XML tree when one of the MCP query tools
+can answer the question directly.
+
+## How to use
+
+1. Call \`get_status\` first when you are unsure whether an index is available,
+   current, or belongs to the project you are working in.
+2. Use narrow queries:
+   - \`find_asset(id, type?)\` for definition locations.
+   - \`find_references(id, type?)\` for incoming semantic references.
+   - \`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.
+   - \`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.
+5. If the returned index state is \`stale\`, \`ready_xml\`, or \`building\`, treat
+   results as provisional.
+6. Never read or dump the whole index snapshot; query narrowly.
+
+## Following references with get_asset_references
+
+Use \`get_asset_references\` to answer "which weapon / model / upgrade / die-object
+does this asset actually use" without reading source first. It returns **edges**,
+not a flat list, so provenance is preserved:
+
+- \`from\` is the asset you asked about.
+- \`to\` is the resolved definition (file + line), or null when unresolved.
+- \`via.element\` / \`via.parent\` / \`via.attribute\` say exactly which XML
+  element and attribute created the link.
+- \`source\` is the file/line where that link is written.
+- \`definedIn\` is present when the link comes from an \`inheritFrom\` ancestor's
+  XML rather than from the asset's own file. Inheritance is walked at the same
+  depth, so a base asset's weapon slot configuration is reported together with
+  the derived asset's own modules.
+
+Practical rules:
+
+- Start with the default \`depth: 1\` (the queried asset only). Raise it to 2 or 3
+  only for a specific node you already decided to follow. The maximum is 3.
+- Pass \`targetTypes\` to cut noise, e.g. \`["WeaponTemplate"]\`, or
+  \`["GameObject"]\` for \`CreateObjectDie\`-style die-object links.
+- If \`truncated\` is true, read \`omittedByTargetType\` and narrow the query
+  (smaller \`targetTypes\`, lower \`depth\`) instead of blindly retrying.
+- Call \`find_references\` in the opposite direction: it tells you who else would
+  be affected by a change.
+- Merged/inherited *effective values* are not computed. When \`xai:joinAction\`
+  (\`Replace\` / \`Remove\`) appears in the merge path, open the file and confirm
+  the real result yourself.
+`;
+
+const QUERY_GUIDE_MD = `# RA3 Mod XML query tool reference
+
+The MCP server exposes these tools:
+
+- get_status()
+- find_asset(id, type?)
+- find_references(id, type?)
+- get_asset_references(id, type?, depth?, targetTypes?, maxEdges?, includeUnresolved?)
+- list_assets_by_type(type, prefix?, limit?)
+- is_file_active(path)
+- find_define(name)
+- resolve_include(source)
+- get_usage_guide()
+
+## Result metadata
+
+Every query result includes an \`index\` object:
+
+\`\`\`json
+{
+  "state": "ready",
+  "projectDir": "D:/Mods/Example",
+  "complete": true,
+  "stale": false
+}
+\`\`\`
+
+Possible states:
+
+- no_index: no index snapshot exists.
+- building: a rebuild is in progress.
+- ready_xml: XML assets are available but art assets may be incomplete.
+- ready: complete index.
+- stale: index may be outdated.
+- error: last build failed.
+
+Always check \`index.projectDir\`. If it does not match the project you are
+working on, discard the result and read files directly instead.
+
+## get_asset_references
+
+Returns outgoing reference edges with full provenance:
+
+\`\`\`json
+{
+  "index": { "state": "ready", "projectDir": "D:/Mods/Example" },
+  "data": {
+    "roots": [{ "type": "GameObject", "id": "AthenaCannon", "file": "...", "line": 12 }],
+    "edges": [
+      {
+        "depth": 1,
+        "from": { "type": "GameObject", "id": "AthenaCannon" },
+        "to": { "type": "WeaponTemplate", "id": "AthenaCannonWeapon", "file": "...", "line": 88 },
+        "via": { "kind": "attribute", "element": "Weapon", "parent": "WeaponSlotHardpoint", "attribute": "Template" },
+        "source": { "file": "D:/Mods/Example/Data/Allied/Units/AthenaCannon.xml", "line": 40, "character": 24 }
+      }
+    ],
+    "nodes": [],
+    "truncated": false,
+    "omittedByTargetType": {},
+    "warnings": []
+  }
+}
+\`\`\`
+
+\`via.kind\` is one of \`attribute\`, \`content\` or \`inheritFrom\`. Edges carrying
+\`definedIn\` come from an \`inheritFrom\` ancestor's XML.
+
+This tool requires a **live** index (VS Code open with the project indexed).
+It is not available from the on-disk snapshot because element context is not
+stored there. When live is unavailable the tool returns an explicit error
+instead of an empty result.
+`;
+
+export interface SkillInstallRecord {
+  /** Skill directory (the directory containing SKILL.md). */
+  path: string;
+  /** Extension version that installed/updated this copy. */
+  sourceVersion: string;
+}
+
+/**
+ * Writes a managed copy of the Skill into `targetDir` (the directory that
+ * should contain SKILL.md).
+ */
+export async function writeSkillTo(
+  targetDir: string,
+  sourceVersion: string,
+): Promise<void> {
+  await mkdir(join(targetDir, "references"), { recursive: true });
+  await writeFile(join(targetDir, "SKILL.md"), SKILL_MD, "utf8");
+  await writeFile(
+    join(targetDir, "references", "query-guide.md"),
+    QUERY_GUIDE_MD,
+    "utf8",
+  );
+  const marker: SkillInstallRecord = {
+    path: targetDir,
+    sourceVersion,
+  };
+  await writeFile(
+    join(targetDir, SKILL_MARKER_FILE),
+    JSON.stringify(marker, null, 2),
+    "utf8",
+  );
+}
+
+/** Conventional ~/.agents/skills/<skill-name> path. */
+export function agentsSkillsDirForUser(home = homedir()): string {
+  return join(home, ".agents", "skills", SKILL_NAME);
+}
+
+/** Conventional ~/.claude/skills/<skill-name> path (Claude Code). */
+export function claudeSkillsDirForUser(home = homedir()): string {
+  return join(home, ".claude", "skills", SKILL_NAME);
+}
+
+/** Path to the managed-install record under the agent home. */
+export function skillInstallRecordPath(agentHome = defaultAgentHome()): string {
+  return join(agentHome, "skill-install.json");
+}
+
+/** Reads the managed skill install record, or returns an empty list. */
+export async function readSkillInstallRecord(
+  agentHome = defaultAgentHome(),
+): Promise<SkillInstallRecord[]> {
+  try {
+    const text = await readFile(skillInstallRecordPath(agentHome), "utf8");
+    const parsed = JSON.parse(text) as { installed?: SkillInstallRecord[] };
+    return Array.isArray(parsed.installed) ? parsed.installed : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Writes the managed skill install record. */
+export async function writeSkillInstallRecord(
+  installed: SkillInstallRecord[],
+  agentHome = defaultAgentHome(),
+): Promise<void> {
+  const file = skillInstallRecordPath(agentHome);
+  await mkdir(dirname(file), { recursive: true });
+  await writeFile(
+    file,
+    JSON.stringify({ installed }, null, 2),
+    "utf8",
+  );
+}
+
+/**
+ * Installs the Skill into several directories and records each managed copy.
+ * Returns the directories successfully written.
+ */
+export async function installSkillToDirectories(
+  directories: string[],
+  sourceVersion: string,
+  agentHome = defaultAgentHome(),
+): Promise<string[]> {
+  const installed = await readSkillInstallRecord(agentHome);
+  const succeeded: string[] = [];
+  for (const dir of directories) {
+    try {
+      await writeSkillTo(dir, sourceVersion);
+      if (!installed.some((r) => r.path === dir)) {
+        installed.push({ path: dir, sourceVersion });
+      } else {
+        const record = installed.find((r) => r.path === dir);
+        if (record) record.sourceVersion = sourceVersion;
+      }
+      succeeded.push(dir);
+    } catch {
+      // Keep going; caller can surface per-directory failures.
+    }
+  }
+  await writeSkillInstallRecord(installed, agentHome);
+  return succeeded;
+}
+
+/** Removes one managed Skill directory and its install record entry. */
+export async function uninstallSkillFromDirectory(
+  directory: string,
+  agentHome = defaultAgentHome(),
+): Promise<void> {
+  await rm(directory, { recursive: true, force: true });
+  const installed = (await readSkillInstallRecord(agentHome)).filter(
+    (r) => r.path !== directory,
+  );
+  await writeSkillInstallRecord(installed, agentHome);
+}
+
+/** Re-writes every recorded Skill copy with the current extension version. */
+export async function syncInstalledSkills(
+  sourceVersion: string,
+  agentHome = defaultAgentHome(),
+): Promise<SkillInstallRecord[]> {
+  const installed = await readSkillInstallRecord(agentHome);
+  const synced: SkillInstallRecord[] = [];
+  for (const record of installed) {
+    try {
+      await writeSkillTo(record.path, sourceVersion);
+      synced.push({ path: record.path, sourceVersion });
+    } catch {
+      // Skip unreadable/missing targets; the record will be cleaned below.
+    }
+  }
+  await writeSkillInstallRecord(synced, agentHome);
+  return synced;
+}

src/agent/snapshot.ts

@@ -0,0 +1,204 @@
+/**
+ * Convert an internal ModIndex into a stable, external agent snapshot and
+ * read/write those snapshots on disk.
+ *
+ * Pure TypeScript: no VS Code dependency, so CLI/MCP/tools can reuse this
+ * module outside the extension.
+ */
+
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { gunzip, gzip } from "node:zlib";
+import { promisify } from "node:util";
+import type { ModIndex } from "../indexer/types";
+import {
+  AGENT_SNAPSHOT_SCHEMA_VERSION,
+  type AgentIndexSnapshot,
+  type AgentIndexStatus,
+} from "./types";
+
+const gzipAsync = promisify(gzip);
+const gunzipAsync = promisify(gunzip);
+
+/** Default directory used for launcher/snapshots/skill installation state. */
+export function defaultAgentHome(): string {
+  return join(homedir(), ".ra3modxml");
+}
+
+/** Directory where current external snapshots are stored. */
+export function defaultSnapshotDir(agentHome = defaultAgentHome()): string {
+  return join(agentHome, "snapshots");
+}
+
+/**
+ * Stable, collision-resistant identity for one project directory.
+ * Case-insensitive (Windows paths) and independent of the current drive
+ * mapping case, so the same project always maps to the same key.
+ */
+export function projectHash(projectDir: string): string {
+  return createHash("sha1")
+    .update(resolve(projectDir).toLowerCase(), "utf8")
+    .digest("hex")
+    .slice(0, 12);
+}
+
+/**
+ * Short, filesystem-safe, human-readable prefix for a project (directory
+ * basename, sanitized). Falls back to "project" when the basename has no
+ * usable characters.
+ */
+export function projectSlug(projectDir: string): string {
+  const raw = basename(resolve(projectDir));
+  const slug = raw
+    .replace(/[^A-Za-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .toLowerCase();
+  return slug || "project";
+}
+
+/**
+ * A stable, readable file name for one project:
+ * `<slug>-<sha1-12>` (e.g. `corona-9f3a1c2b4d5e`).
+ */
+export function snapshotBaseName(projectDir: string): string {
+  return `${projectSlug(projectDir)}-${projectHash(projectDir)}`;
+}
+
+/** Converts the internal ModIndex to the stable external snapshot shape. */
+export function snapshotFromIndex(index: ModIndex, buildId?: number): AgentIndexSnapshot {
+  const assets: AgentIndexSnapshot["assets"] = [];
+  for (const byId of index.assets.values()) {
+    for (const defs of byId.values()) {
+      assets.push(...defs);
+    }
+  }
+
+  const defines: AgentIndexSnapshot["defines"] = [];
+  for (const defs of index.defines.values()) {
+    defines.push(...defs);
+  }
+
+  const references: AgentIndexSnapshot["references"] = [];
+  for (const [key, sites] of index.references) {
+    const parts = key.split("\u0000");
+    if (parts.length !== 4) continue;
+    references.push({
+      type: parts[0],
+      id: parts[1],
+      file: parts[2],
+      line: Number(parts[3]) || 0,
+      sites,
+    });
+  }
+
+  const streams: AgentIndexSnapshot["streams"] = index.streams.map((s) => ({
+    name: s.name,
+    entry: s.entry,
+    files: [...s.files],
+  }));
+
+  return {
+    schemaVersion: AGENT_SNAPSHOT_SCHEMA_VERSION,
+    projectDir: index.projectDir,
+    sdkDir: index.sdkDir,
+    phase: index.phase,
+    complete: index.complete,
+    stale: index.stale,
+    generatedAt: new Date().toISOString(),
+    buildId,
+    stats: {
+      assetCount: assets.length,
+      referenceCount: index.references.size,
+      defineCount: defines.length,
+      fileCount: index.files.size,
+      streamCount: streams.length,
+      sourceCandidateCount: index.sourceCandidates.length,
+      manifestFileCount: index.manifests.size,
+      manifestAssetCount: index.stats.manifestAssetCount,
+    },
+    assets,
+    defines,
+    references,
+    streams,
+    sourceCandidates: index.sourceCandidates,
+    diagnostics: index.diagnostics,
+  };
+}
+
+/** Returns a status object for a missing/not-yet-built index. */
+export function noIndexStatus(projectDir?: string, detail?: string): AgentIndexStatus {
+  return {
+    state: "no_index",
+    projectDir,
+    detail: detail ?? "No index has been built yet.",
+  };
+}
+
+/** Returns a status object for the current index state. */
+export function statusFromIndex(index: ModIndex | null | undefined, projectDir?: string): AgentIndexStatus {
+  if (!index) return noIndexStatus(projectDir);
+  const state: AgentIndexStatus["state"] = index.stale
+    ? "stale"
+    : !index.complete
+      ? "ready_xml"
+      : "ready";
+  return {
+    state,
+    projectDir: index.projectDir,
+    phase: index.phase,
+    complete: index.complete,
+    stale: index.stale,
+    generatedAt: new Date().toISOString(),
+    stats: {
+      assetCount: index.stats.assetCount,
+      referenceCount: index.stats.referenceCount,
+      defineCount: index.stats.defineCount,
+      fileCount: index.stats.indexedFiles,
+      streamCount: index.stats.streams,
+      sourceCandidateCount: index.stats.sourceCandidates,
+      manifestFileCount: index.stats.manifestFiles,
+      manifestAssetCount: index.stats.manifestAssetCount,
+    },
+  };
+}
+
+/** Serializes a snapshot to a JSON string (not compressed). */
+export function snapshotToJson(snapshot: AgentIndexSnapshot): string {
+  return JSON.stringify(snapshot);
+}
+
+/** Writes a snapshot as gzip-compressed JSON using atomic temp+rename. */
+export async function writeSnapshotFile(
+  filePath: string,
+  snapshot: AgentIndexSnapshot,
+): Promise<string> {
+  const payload = Buffer.from(snapshotToJson(snapshot), "utf8");
+  const buf = await gzipAsync(payload);
+  const target = resolve(filePath);
+  await mkdir(dirname(target), { recursive: true });
+  const tmp = `${target}.tmp`;
+  await writeFile(tmp, buf);
+  await rename(tmp, target);
+  return target;
+}
+
+/** Reads a gzip-compressed JSON snapshot written by writeSnapshotFile. */
+export async function readSnapshotFile(filePath: string): Promise<AgentIndexSnapshot | null> {
+  try {
+    const buf = await readFile(filePath);
+    const text = (await gunzipAsync(buf)).toString("utf8");
+    return JSON.parse(text) as AgentIndexSnapshot;
+  } catch {
+    return null;
+  }
+}
+
+/** Builds the conventional snapshot path for a project under the agent home. */
+export function snapshotPathForProject(
+  projectDir: string,
+  agentHome = defaultAgentHome(),
+): string {
+  return join(defaultSnapshotDir(agentHome), `${snapshotBaseName(projectDir)}.json.gz`);
+}

src/agent/types.ts

@@ -0,0 +1,103 @@
+/**
+ * Public, stable data types for exposing RA3 Mod XML indexes to AI Agents
+ * and external tools.
+ *
+ * These types intentionally mirror the internal index model but use plain
+ * serializable arrays instead of Maps/Sets. They are independent of the VS
+ * Code API and of the extension's internal workspaceStorage layout.
+ */
+
+import type {
+  AssetDef,
+  DefineDef,
+  IndexerDiagnostic,
+  ReferenceSite,
+  SourceCandidate,
+} from "../indexer/types";
+
+/** Current external snapshot schema version. */
+export const AGENT_SNAPSHOT_SCHEMA_VERSION = 1;
+
+export type AgentIndexState =
+  | "no_index"
+  | "building"
+  | "ready_xml"
+  | "ready"
+  | "stale"
+  | "error";
+
+export interface AgentIndexStats {
+  assetCount: number;
+  referenceCount: number;
+  defineCount: number;
+  fileCount: number;
+  streamCount: number;
+  sourceCandidateCount: number;
+  manifestFileCount: number;
+  manifestAssetCount: number;
+}
+
+export interface AgentAsset extends AssetDef {
+  // AssetDef is already plain/serializable.
+}
+
+export interface AgentDefine extends DefineDef {
+  // DefineDef is already plain/serializable.
+}
+
+/** A stream (static or global:<name>) with the normalized file paths in it. */
+export interface AgentStream {
+  name: string;
+  entry: string;
+  files: string[];
+}
+
+/** Reference sites grouped by the definition they point to. */
+export interface AgentReferenceGroup {
+  type: string;
+  id: string;
+  file: string;
+  line: number;
+  sites: ReferenceSite[];
+}
+
+/**
+ * Immutable, tool-facing snapshot of one project index.
+ */
+export interface AgentIndexSnapshot {
+  schemaVersion: number;
+  projectDir: string;
+  sdkDir: string;
+  /** Last finished phase: "xml" or "art". */
+  phase: "xml" | "art";
+  complete: boolean;
+  stale?: boolean;
+  generatedAt: string;
+  /** Build counter from the workspace; useful for change detection. */
+  buildId?: number;
+  stats: AgentIndexStats;
+  assets: AgentAsset[];
+  defines: AgentDefine[];
+  /**
+   * Reverse references grouped by target definition key.
+   * Consumers normally filter by `type` + `id`, then aggregate groups.
+   */
+  references: AgentReferenceGroup[];
+  streams: AgentStream[];
+  sourceCandidates: SourceCandidate[];
+  diagnostics: IndexerDiagnostic[];
+}
+
+/** Status returned by query interfaces when an index may not be ready. */
+export interface AgentIndexStatus {
+  state: AgentIndexState;
+  projectDir?: string;
+  phase?: "xml" | "art";
+  complete?: boolean;
+  stale?: boolean;
+  generatedAt?: string;
+  buildId?: number;
+  stats?: AgentIndexStats;
+  /** Human-readable explanation for no_index/error states. */
+  detail?: string;
+}

src/extension.ts

@@ -1,4 +1,7 @@
 import * as vscode from "vscode";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { stripBom } from "./language/xmlParser";
 import { ModWorkspace } from "./workspace";
 import { SdkSetup } from "./sdkSetup";
 import { Ra3CompletionProvider } from "./features/completion";
@@ -21,6 +24,36 @@ import {
   RA3_SEMANTIC_TOKENS_LEGEND,
 } from "./features/semanticTokens";
 import { t } from "./localize";
+import {
+  snapshotFromIndex,
+  snapshotPathForProject,
+  writeSnapshotFile,
+} from "./agent/snapshot";
+import {
+  addMcpServerToConfigFile,
+  claudeDesktopConfigPath,
+  cursorGlobalConfigPath,
+  cursorProjectConfigPath,
+  mcpConfigJson,
+  writeLauncher,
+} from "./agent/setup";
+import {
+  SKILL_NAME,
+  agentsSkillsDirForUser,
+  claudeSkillsDirForUser,
+  installSkillToDirectories,
+  readSkillInstallRecord,
+  writeSkillInstallRecord,
+  writeSkillTo,
+} from "./agent/skill";
+import { startLocalServer, type LocalServerHandle } from "./agent/localServer";
+import { parseLoadedXml } from "./agent/forwardRefs";
+import {
+  clearEndpoint,
+  clearEndpointForProject,
+  writeEndpoint,
+  writeEndpointForProject,
+} from "./agent/endpoint";
 
 const XML_SELECTOR: vscode.DocumentSelector = [{ language: "xml" }];
 /** Safety-net refresh interval while a rebuild is running. */
@@ -96,9 +129,126 @@ export function activate(context: vscode.ExtensionContext): void {
     ws.log("[codelens] retry started");
   };
   ws.onBuildStart = startCodeLensRetry;
+  // 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,
+  // non-stale final index.
+  let agentAccessEnabled = context.workspaceState.get<boolean>(
+    "ra3modxml.agentAccessEnabled",
+    false,
+  );
+  const AGENT_SNAPSHOT_QUIET_MS = 5000;
+  let agentSnapshotTimer: ReturnType<typeof setTimeout> | null = null;
+  const scheduleAgentSnapshot = (): void => {
+    if (!agentAccessEnabled) return;
+    if (agentSnapshotTimer) clearTimeout(agentSnapshotTimer);
+    agentSnapshotTimer = setTimeout(() => {
+      agentSnapshotTimer = null;
+      const current = ws.activeIndex();
+      if (!current?.complete || current.stale === true) return;
+      void writeSnapshotFile(
+        snapshotPathForProject(current.projectDir),
+        snapshotFromIndex(current, ws.buildCount),
+      ).catch((err) => {
+        ws.log(
+          `[agent-snapshot] export failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      });
+    }, AGENT_SNAPSHOT_QUIET_MS);
+  };
+  let agentLocalServer: LocalServerHandle | null = null;
+  /** Project roots whose per-project endpoint file this window wrote. */
+  const agentEndpointProjects = new Set<string>();
+  const startAgentLocalServer = async (): Promise<void> => {
+    if (agentLocalServer) return;
+    try {
+      const handle = await startLocalServer({
+        // Route by explicit project so a query can never be answered by
+        // whichever project the active editor happens to point at.
+        getIndex: (projectDir) =>
+          projectDir ? ws.indexForProject(projectDir) : ws.activeIndex(),
+        listProjects: () => ws.getProjectRoots(),
+        loadFile: async (file) => {
+          const text = stripBom(await readFile(file, "utf8"));
+          return parseLoadedXml(text);
+        },
+      });
+      agentLocalServer = handle;
+      const url = `http://127.0.0.1:${handle.port}`;
+      const projects = ws.getProjectRoots();
+      const endpoint = {
+        url,
+        token: handle.token,
+        projectDir: ws.projectRoot ?? undefined,
+        projects,
+        processId: process.pid,
+        updatedAt: new Date().toISOString(),
+      };
+      // One file per project, so two open windows cannot shadow each other.
+      for (const project of projects) {
+        const file = await writeEndpointForProject(project, {
+          ...endpoint,
+          projectDir: project,
+        });
+        agentEndpointProjects.add(project);
+        ws.log(`[agent-local-server] endpoint for ${project} -> ${file}`);
+      }
+      // Legacy/global pointer for tooling that does not know the project.
+      await writeEndpoint(endpoint);
+      ws.log(`[agent-local-server] listening on ${url}`);
+    } catch (err) {
+      ws.log(
+        `[agent-local-server] failed to start: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  };
+  const stopAgentLocalServer = async (): Promise<void> => {
+    if (agentLocalServer) {
+      const server = agentLocalServer;
+      agentLocalServer = null;
+      await server.close().catch(() => undefined);
+    }
+    // Only remove the endpoint files this window wrote: another VS Code
+    // window may still be serving its own projects.
+    for (const project of agentEndpointProjects) {
+      await clearEndpointForProject(project).catch(() => undefined);
+    }
+    agentEndpointProjects.clear();
+    await clearEndpoint().catch(() => undefined);
+  };
+  /**
+   * Publishes per-project endpoint files for every project this window now
+   * knows about. Called on each index update so projects discovered later get
+   * an endpoint without restarting the server.
+   */
+  const refreshAgentEndpoints = async (): Promise<void> => {
+    if (!agentLocalServer) return;
+    const url = `http://127.0.0.1:${agentLocalServer.port}`;
+    const token = agentLocalServer.token;
+    const projects = ws.getProjectRoots();
+    const base = {
+      url,
+      token,
+      projects,
+      processId: process.pid,
+      updatedAt: new Date().toISOString(),
+    };
+    for (const project of projects) {
+      try {
+        await writeEndpointForProject(project, { ...base, projectDir: project });
+        agentEndpointProjects.add(project);
+      } catch (err) {
+        ws.log(
+          `[agent-local-server] could not write endpoint for ${project}: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+  };
   context.subscriptions.push({
     dispose: () => {
       if (codeLensRetryTimer) clearInterval(codeLensRetryTimer);
+      if (agentSnapshotTimer) clearTimeout(agentSnapshotTimer);
+      void stopAgentLocalServer();
     },
   });
   context.subscriptions.push(
@@ -123,6 +273,8 @@ export function activate(context: vscode.ExtensionContext): void {
         `[codelens] refresh (project=${idx.stats.projectDir}, phase=${idx.phase}, assets=${idx.stats.assetCount}, complete=${idx.complete}, stale=${idx.stale === true})`,
       );
     }
+    scheduleAgentSnapshot();
+    void refreshAgentEndpoints();
     for (const doc of vscode.workspace.textDocuments) {
       if (doc.languageId === "xml") void diagnostics.update(doc);
     }
@@ -282,6 +434,190 @@ export function activate(context: vscode.ExtensionContext): void {
       );
     }),
   );
+  context.subscriptions.push(
+    vscode.commands.registerCommand("ra3modxml.exportIndexSnapshot", async () => {
+      const idx = ws.activeIndex();
+      if (!idx) {
+        void vscode.window.showInformationMessage(
+          t(
+            "RA3 Mod XML: no index available yet. Wait for indexing to finish before exporting an AI Agent snapshot.",
+          ),
+        );
+        return;
+      }
+      const path = snapshotPathForProject(idx.projectDir);
+      try {
+        const snapshot = snapshotFromIndex(idx, ws.buildCount);
+        await writeSnapshotFile(path, snapshot);
+        void vscode.window.showInformationMessage(
+          t(
+            "RA3 Mod XML: exported AI Agent index snapshot to {0}",
+            path,
+          ),
+          t("Reveal in Explorer"),
+        ).then((pick) => {
+          if (pick) void vscode.commands.executeCommand("revealInExplorer", vscode.Uri.file(path));
+        });
+      } catch (err) {
+        void vscode.window.showErrorMessage(
+          t(
+            "RA3 Mod XML: failed to export AI Agent index snapshot: {0}",
+            err instanceof Error ? err.message : String(err),
+          ),
+        );
+      }
+    }),
+  );
+  context.subscriptions.push(
+    vscode.commands.registerCommand("ra3modxml.enableAgentAccess", async () => {
+      const idx = ws.activeIndex();
+      if (!idx) {
+        void vscode.window.showInformationMessage(
+          t(
+            "RA3 Mod XML: no index available yet. Wait for indexing to finish before enabling AI Agent access.",
+          ),
+        );
+        return;
+      }
+      const projectDir = idx.projectDir;
+      try {
+        const snapshot = snapshotFromIndex(idx, ws.buildCount);
+        await writeSnapshotFile(snapshotPathForProject(projectDir), snapshot);
+        const launcher = await writeLauncher(
+          context.extensionUri.fsPath,
+          projectDir,
+        );
+        const configJson = mcpConfigJson(launcher, projectDir);
+        agentAccessEnabled = true;
+        await context.workspaceState.update("ra3modxml.agentAccessEnabled", true);
+        void startAgentLocalServer();
+        const version = String((context.extension.packageJSON as { version?: string }).version ?? "dev");
+        const installSkill = t("Install Agent Skill (recommended)");
+        const writeClaude = t("Write MCP config to Claude Desktop");
+        const writeCursorGlobal = t("Write MCP config to Cursor (global)");
+        const writeCursorProject = t("Write MCP config to Cursor (project)");
+        const copyConfig = t("Copy MCP config");
+        const pick = await vscode.window.showQuickPick(
+          [
+            {
+              label: installSkill,
+              description: agentsSkillsDirForUser(),
+              id: "skill",
+            },
+            {
+              label: writeClaude,
+              description: claudeDesktopConfigPath(),
+              id: "claude",
+            },
+            {
+              label: writeCursorGlobal,
+              description: cursorGlobalConfigPath(),
+              id: "cursor-global",
+            },
+            {
+              label: writeCursorProject,
+              description: cursorProjectConfigPath(projectDir),
+              id: "cursor-project",
+            },
+            {
+              label: copyConfig,
+              id: "copy",
+            },
+          ],
+          {
+            placeHolder: t("RA3 Mod XML AI Agent access enabled. Choose an optional next step."),
+          },
+        );
+        if (pick?.id === "skill") {
+          const target = agentsSkillsDirForUser();
+          await writeSkillTo(target, version);
+          const installed = await readSkillInstallRecord();
+          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 if (pick?.id === "claude") {
+          await addMcpServerToConfigFile(claudeDesktopConfigPath(), launcher, projectDir);
+          void vscode.window.showInformationMessage(
+            t("RA3 Mod XML MCP config written to {0}", claudeDesktopConfigPath()),
+          );
+        } else if (pick?.id === "cursor-global") {
+          await addMcpServerToConfigFile(cursorGlobalConfigPath(), launcher, projectDir);
+          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, projectDir);
+          void vscode.window.showInformationMessage(
+            t("RA3 Mod XML MCP config written to {0}", cursorProjectConfigPath(projectDir)),
+          );
+        } else if (pick?.id === "copy") {
+          await vscode.env.clipboard.writeText(configJson);
+          void vscode.window.showInformationMessage(
+            t("RA3 Mod XML MCP config copied to clipboard."),
+          );
+        }
+      } catch (err) {
+        void vscode.window.showErrorMessage(
+          t(
+            "RA3 Mod XML: failed to enable AI Agent access: {0}",
+            err instanceof Error ? err.message : String(err),
+          ),
+        );
+      }
+    }),
+  );
+  context.subscriptions.push(
+    vscode.commands.registerCommand("ra3modxml.installAgentSkill", async () => {
+      const idx = ws.activeIndex();
+      if (!idx) {
+        void vscode.window.showInformationMessage(
+          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 = [
+        {
+          label: t("Default (~/.agents/skills)"),
+          description: agentsSkillsDirForUser(),
+          path: agentsSkillsDirForUser(),
+          picked: true,
+        },
+        {
+          label: t("Claude Code (~/.claude/skills)"),
+          description: claudeSkillsDirForUser(),
+          path: claudeSkillsDirForUser(),
+        },
+        {
+          label: t("Current project .agents/skills"),
+          description: join(projectDir, ".agents", "skills", SKILL_NAME),
+          path: 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),
+        },
+      ];
+      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),
+        version,
+      );
+      void vscode.window.showInformationMessage(
+        t("RA3 Mod XML Agent Skill installed to {0} location(s).", succeeded.length),
+      );
+    }),
+  );
   context.subscriptions.push(
     vscode.commands.registerCommand(
       "ra3modxml.showReferences",
@@ -302,8 +638,12 @@ export function activate(context: vscode.ExtensionContext): void {
     ),
   );
 
+  if (agentAccessEnabled) void startAgentLocalServer();
   void sdkSetup.evaluate(ws);
-  void ws.initialize().then(() => void sdkSetup.evaluate(ws));
+  void ws.initialize().then(() => {
+    void sdkSetup.evaluate(ws);
+    if (agentAccessEnabled) void startAgentLocalServer();
+  });
 }
 
 export function deactivate(): void {

src/workspace.ts

@@ -229,6 +229,18 @@ export class ModWorkspace {
     return this.activeState()?.indexer ?? null;
   }
 
+  /**
+   * Index of one specific project (normalized absolute root), or null.
+   *
+   * The live agent server routes queries through this instead of
+   * `activeIndex()`, so a query for project A can never be answered from
+   * whatever project the user happens to be editing right now.
+   */
+  indexForProject(projectDir: string): ModIndex | null {
+    if (!projectDir) return null;
+    return this.states.get(normKey(projectDir))?.index ?? null;
+  }
+
   /**
    * Discovers project roots from the current workspace folders and open
    * documents, registers per-project state and starts the initial build(s):

test/agentEndpoint.test.mjs

@@ -0,0 +1,102 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import {
+  clearEndpoint,
+  clearEndpointForProject,
+  endpointPathForProject,
+  isProcessAlive,
+  readEndpoint,
+  readEndpointForProject,
+  sameProject,
+  writeEndpoint,
+  writeEndpointForProject,
+} from "../out/agent/endpoint.js";
+
+const PROJECT_A = "D:/Mods/ExampleA";
+const PROJECT_B = "D:/Mods/ExampleB";
+
+test("endpoint file round-trips and clears", async () => {
+  const home = mkdtempSync(join(tmpdir(), "ra3-endpoint-test-"));
+  try {
+    await writeEndpoint(
+      { url: "http://127.0.0.1:12345", token: "abc", projectDir: PROJECT_A },
+      home,
+    );
+    const loaded = await readEndpoint(home);
+    assert.equal(loaded?.url, "http://127.0.0.1:12345");
+    assert.equal(loaded?.token, "abc");
+
+    await clearEndpoint(home);
+    assert.equal(await readEndpoint(home), null);
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("per-project endpoints do not shadow each other", async () => {
+  const home = mkdtempSync(join(tmpdir(), "ra3-endpoint-multi-"));
+  try {
+    // Two "windows" enable agent access for different projects.
+    await writeEndpointForProject(
+      PROJECT_A,
+      { url: "http://127.0.0.1:1111", token: "token-a", processId: process.pid },
+      home,
+    );
+    await writeEndpointForProject(
+      PROJECT_B,
+      { url: "http://127.0.0.1:2222", token: "token-b", processId: process.pid },
+      home,
+    );
+
+    const a = await readEndpointForProject(PROJECT_A, home);
+    const b = await readEndpointForProject(PROJECT_B, home);
+    assert.equal(a?.url, "http://127.0.0.1:1111");
+    assert.ok(sameProject(a.projectDir, PROJECT_A));
+    assert.equal(b?.url, "http://127.0.0.1:2222");
+    assert.ok(sameProject(b.projectDir, PROJECT_B));
+
+    // Clearing one project must not disturb the other.
+    await clearEndpointForProject(PROJECT_A, home);
+    assert.equal(await readEndpointForProject(PROJECT_A, home), null);
+    assert.equal((await readEndpointForProject(PROJECT_B, home))?.token, "token-b");
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("a per-project endpoint recording another project is rejected", async () => {
+  const home = mkdtempSync(join(tmpdir(), "ra3-endpoint-mismatch-"));
+  try {
+    const file = endpointPathForProject(PROJECT_A, home);
+    // Simulate a stale/edited file that claims to serve a different project.
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(
+      file,
+      JSON.stringify({
+        url: "http://127.0.0.1:3333",
+        token: "t",
+        projectDir: PROJECT_B,
+      }),
+    );
+    assert.equal(await readEndpointForProject(PROJECT_A, home), null);
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("isProcessAlive detects dead pids and trusts unknown ones", () => {
+  assert.equal(isProcessAlive(process.pid), true);
+  assert.equal(isProcessAlive(undefined), true);
+  assert.equal(isProcessAlive(0), true);
+  assert.equal(isProcessAlive(NaN), true);
+  // Not a valid Windows PID, so it cannot correspond to a running process.
+  assert.equal(isProcessAlive(0x7fffffff), false);
+});
+
+test("sameProject is case-insensitive", () => {
+  assert.equal(sameProject("D:/Mods/Example", "d:/mods/example"), true);
+  assert.equal(sameProject("D:/Mods/Example", "D:/Mods/Other"), false);
+});

test/agentForwardRefs.test.mjs

@@ -0,0 +1,308 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  collectAssetReferences,
+  parseLoadedXml,
+} from "../out/agent/forwardRefs.js";
+
+// ── Fixture files ────────────────────────────────────────────────────
+// AthenaCannon has no WeaponSetUpdate of its own: it inherits BaseCannon,
+// which owns the weapon slot, and has its own die-object content reference.
+const ATHENA = `<?xml version="1.0" encoding="utf-8"?>
+<AssetDeclaration xmlns="uri:ea.com:eala:asset">
+  <GameObject id="AthenaCannon" inheritFrom="BaseCannon">
+    <CreateObjectDie>
+      <CreateObject>AthenaCannon_Die</CreateObject>
+    </CreateObjectDie>
+  </GameObject>
+</AssetDeclaration>`;
+
+const BASE = `<?xml version="1.0" encoding="utf-8"?>
+<AssetDeclaration xmlns="uri:ea.com:eala:asset">
+  <GameObject id="BaseCannon">
+    <WeaponSetUpdate>
+      <WeaponSlotHardpoint>
+        <Weapon Template="AthenaCannonWeapon" />
+      </WeaponSlotHardpoint>
+    </WeaponSetUpdate>
+  </GameObject>
+</AssetDeclaration>`;
+
+const DIE = `<?xml version="1.0" encoding="utf-8"?>
+<AssetDeclaration xmlns="uri:ea.com:eala:asset">
+  <GameObject id="AthenaCannon_Die">
+    <WeaponSetUpdate>
+      <WeaponSlotHardpoint>
+        <Weapon Template="DieExplosionWeapon" />
+      </WeaponSlotHardpoint>
+    </WeaponSetUpdate>
+  </GameObject>
+</AssetDeclaration>`;
+
+const FILES = {
+  "D:/Mods/Example/Data/AthenaCannon.xml": ATHENA,
+  "D:/Mods/Example/Data/BaseCannon.xml": BASE,
+  "D:/Mods/Example/Data/AthenaCannon_Die.xml": DIE,
+};
+
+function def(type, id, file, line) {
+  return { type, id, file, line, origin: "project", stream: "static" };
+}
+
+const ATHENA_DEF = def("GameObject", "AthenaCannon", "D:/Mods/Example/Data/AthenaCannon.xml", 3);
+const BASE_DEF = def("GameObject", "BaseCannon", "D:/Mods/Example/Data/BaseCannon.xml", 3);
+const DIE_DEF = def("GameObject", "AthenaCannon_Die", "D:/Mods/Example/Data/AthenaCannon_Die.xml", 3);
+const WEAPON_DEF = def(
+  "WeaponTemplate",
+  "AthenaCannonWeapon",
+  "D:/Mods/Example/Data/Weapon.xml",
+  88,
+);
+const DIE_WEAPON_DEF = def(
+  "WeaponTemplate",
+  "DieExplosionWeapon",
+  "D:/Mods/Example/Data/Weapon.xml",
+  120,
+);
+
+function makeIndex() {
+  const all = [ATHENA_DEF, BASE_DEF, DIE_DEF, WEAPON_DEF, DIE_WEAPON_DEF];
+  const assetsById = new Map();
+  for (const d of all) {
+    const key = d.id.toLowerCase();
+    if (!assetsById.has(key)) assetsById.set(key, []);
+    assetsById.get(key).push(d);
+  }
+  const assets = new Map([
+    ["GameObject", new Map([["athenacannon", [ATHENA_DEF]], ["basecannon", [BASE_DEF]], ["athenacannon_die", [DIE_DEF]]])],
+    ["WeaponTemplate", new Map([["athenacannonweapon", [WEAPON_DEF]], ["dieexplosionweapon", [DIE_WEAPON_DEF]]])],
+  ]);
+  return {
+    projectDir: "D:/Mods/Example",
+    sdkDir: "",
+    complete: true,
+    phase: "art",
+    assets,
+    assetsById,
+    defines: new Map(),
+    files: new Map(),
+    streams: [],
+    manifests: new Map(),
+    sourceCandidates: [],
+    diagnostics: [],
+    references: new Map(),
+    recordsHashes: new Map(),
+    stats: {},
+  };
+}
+
+function loader(map = FILES) {
+  return async (file) => {
+    const text = map[file];
+    return text ? parseLoadedXml(text) : null;
+  };
+}
+
+function findEdge(edges, predicate) {
+  return edges.find(predicate);
+}
+
+test("depth 1 returns only the queried asset's own edges", async () => {
+  const result = await collectAssetReferences(
+    makeIndex(),
+    "AthenaCannon",
+    "GameObject",
+    loader(),
+    {},
+  );
+  assert.equal(result.roots.length, 1);
+  // Own content ref + inherited weapon ref + the inheritFrom edge itself.
+  assert.ok(result.edges.length >= 3);
+  assert.deepEqual(
+    [...new Set(result.edges.map((e) => e.depth))],
+    [1],
+    "all edges must be at depth 1",
+  );
+  assert.equal(result.truncated, false);
+});
+
+test("attribute references carry element, parent and attribute provenance", async () => {
+  const result = await collectAssetReferences(
+    makeIndex(),
+    "AthenaCannon",
+    "GameObject",
+    loader(),
+  );
+  const weapon = findEdge(
+    result.edges,
+    (e) => e.via.kind === "attribute" && e.to?.id === "AthenaCannonWeapon",
+  );
+  assert.ok(weapon, "weapon edge should exist");
+  assert.equal(weapon.via.element, "Weapon");
+  assert.equal(weapon.via.parent, "WeaponSlotHardpoint");
+  assert.equal(weapon.via.attribute, "Template");
+  assert.equal(weapon.to.type, "WeaponTemplate");
+  assert.equal(weapon.to.line, 88);
+  assert.ok(weapon.source.file.endsWith("BaseCannon.xml"));
+  assert.ok(weapon.source.line > 0);
+});
+
+test("content references (CreateObjectDie) are reported with kind=content", async () => {
+  const result = await collectAssetReferences(
+    makeIndex(),
+    "AthenaCannon",
+    "GameObject",
+    loader(),
+  );
+  const die = findEdge(result.edges, (e) => e.via.kind === "content");
+  assert.ok(die, "die-object content edge should exist");
+  assert.equal(die.via.element, "CreateObject");
+  assert.equal(die.via.parent, "CreateObjectDie");
+  assert.equal(die.via.attribute, null);
+  assert.equal(die.to.type, "GameObject");
+  assert.equal(die.to.id, "AthenaCannon_Die");
+  assert.ok(die.source.file.endsWith("AthenaCannon.xml"));
+});
+
+test("inheritFrom is walked and marked with definedIn", async () => {
+  const result = await collectAssetReferences(
+    makeIndex(),
+    "AthenaCannon",
+    "GameObject",
+    loader(),
+  );
+  const inherit = findEdge(result.edges, (e) => e.via.kind === "inheritFrom");
+  assert.ok(inherit, "inheritFrom edge should exist");
+  assert.equal(inherit.to.id, "BaseCannon");
+  assert.equal(inherit.value, "BaseCannon");
+  assert.equal(inherit.definedIn, undefined, "the inheritFrom edge itself is on AthenaCannon");
+
+  const inheritedWeapon = findEdge(
+    result.edges,
+    (e) => e.to?.id === "AthenaCannonWeapon",
+  );
+  assert.ok(inheritedWeapon, "weapon from the ancestor must still be reported");
+  assert.deepEqual(inheritedWeapon.definedIn, { type: "GameObject", id: "BaseCannon" });
+  assert.equal(inheritedWeapon.from.id, "AthenaCannon", "edge is attributed to the queried asset");
+});
+
+test("targetTypes filters edges, but inheritFrom edges always survive", async () => {
+  const result = await collectAssetReferences(
+    makeIndex(),
+    "AthenaCannon",
+    "GameObject",
+    loader(),
+    { targetTypes: ["WeaponTemplate"] },
+  );
+  assert.ok(result.edges.length > 0);
+  assert.ok(
+    result.edges.some((e) => e.to.type === "WeaponTemplate"),
+    "expected at least one WeaponTemplate edge",
+  );
+  for (const edge of result.edges) {
+    // inheritFrom is kept so the caller can see where the weapon is written.
+    if (edge.via.kind === "inheritFrom") continue;
+    assert.equal(edge.to.type, "WeaponTemplate", `${edge.via.element} should be filtered out`);
+  }
+  // Nodes mirror the kept edges, so the inheritFrom target may appear too.
+  const inheritIds = new Set(
+    result.edges
+      .filter((e) => e.via.kind === "inheritFrom")
+      .map((e) => e.to.id.toLowerCase()),
+  );
+  for (const node of result.nodes) {
+    assert.ok(
+      node.type === "WeaponTemplate" || inheritIds.has(node.id.toLowerCase()),
+      `unexpected node ${node.type}:${node.id}`,
+    );
+  }
+});
+
+test("depth 2 expands into referenced assets", async () => {
+  const result = await collectAssetReferences(
+    makeIndex(),
+    "AthenaCannon",
+    "GameObject",
+    loader(),
+    { depth: 2 },
+  );
+  const depths = new Set(result.edges.map((e) => e.depth));
+  assert.ok(depths.has(2), "expected depth-2 edges from the die-object GameObject");
+  const dieWeapon = findEdge(result.edges, (e) => e.to?.id === "DieExplosionWeapon");
+  assert.ok(dieWeapon, "the die object's weapon should appear at depth 2");
+  assert.equal(dieWeapon.depth, 2);
+  assert.equal(dieWeapon.from.id, "AthenaCannon_Die");
+});
+
+test("depth is clamped to the max of 3", async () => {
+  const result = await collectAssetReferences(
+    makeIndex(),
+    "AthenaCannon",
+    "GameObject",
+    loader(),
+    { depth: 99 },
+  );
+  for (const edge of result.edges) {
+    assert.ok(edge.depth <= 3, `depth ${edge.depth} exceeded the clamp`);
+  }
+});
+
+test("maxEdges truncates and reports what was dropped", async () => {
+  const result = await collectAssetReferences(
+    makeIndex(),
+    "AthenaCannon",
+    "GameObject",
+    loader(),
+    { maxEdges: 1 },
+  );
+  assert.equal(result.edges.length, 1);
+  assert.equal(result.truncated, true);
+  const omitted = Object.values(result.omittedByTargetType).reduce((a, b) => a + b, 0);
+  assert.ok(omitted >= 1, "expected the dropped edges to be summarised");
+});
+
+test("unresolved references are opt-in", async () => {
+  const text = `<AssetDeclaration xmlns="uri:ea.com:eala:asset">
+  <GameObject id="Ghost">
+    <WeaponSetUpdate><WeaponSlotHardpoint><Weapon Template="DoesNotExist" /></WeaponSlotHardpoint></WeaponSetUpdate>
+  </GameObject>
+</AssetDeclaration>`;
+  const ghost = def("GameObject", "Ghost", "D:/Mods/Example/Data/Ghost.xml", 2);
+  const index = makeIndex();
+  index.assetsById.set("ghost", [ghost]);
+  const ghostLoader = loader({ "D:/Mods/Example/Data/Ghost.xml": text });
+
+  const without = await collectAssetReferences(index, "Ghost", "GameObject", ghostLoader);
+  assert.equal(without.edges.length, 0);
+
+  const withUnresolved = await collectAssetReferences(index, "Ghost", "GameObject", ghostLoader, {
+    includeUnresolved: true,
+  });
+  assert.equal(withUnresolved.edges.length, 1);
+  assert.equal(withUnresolved.edges[0].to, null);
+  assert.equal(withUnresolved.edges[0].value, "DoesNotExist");
+});
+
+test("unknown ids produce a warning instead of throwing", async () => {
+  const result = await collectAssetReferences(
+    makeIndex(),
+    "NoSuchAsset",
+    "GameObject",
+    loader(),
+  );
+  assert.equal(result.edges.length, 0);
+  assert.equal(result.roots.length, 0);
+  assert.equal(result.warnings.length, 1);
+  assert.match(result.warnings[0], /No definition found/);
+});
+
+test("unreadable files produce a warning and no edges", async () => {
+  const result = await collectAssetReferences(
+    makeIndex(),
+    "AthenaCannon",
+    "GameObject",
+    async () => null,
+  );
+  assert.equal(result.edges.length, 0);
+  assert.ok(result.warnings.some((w) => w.includes("Could not read")));
+});

test/agentLocalServer.test.mjs

@@ -0,0 +1,283 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { startLocalServer } from "../out/agent/localServer.js";
+import { parseLoadedXml } from "../out/agent/forwardRefs.js";
+
+const PROJECT_A = "D:/Mods/Example";
+const PROJECT_B = "D:/Mods/Other";
+
+function makeStats() {
+  return {
+    projectDir: "P",
+    sdkDir: "",
+    phase: "art",
+    complete: true,
+    indexedFiles: 1,
+    parsedFiles: 1,
+    shallowScannedFiles: 0,
+    deferredArtFiles: 0,
+    shallowCacheHits: 0,
+    recordsCacheHits: 0,
+    resolveCacheHits: 0,
+    resolveCalls: 0,
+    snapshotHits: 0,
+    snapshotFallbacks: 0,
+    candidatesMs: 0,
+    walkMs: 0,
+    artScanMs: 0,
+    assetCount: 1,
+    referenceCount: 1,
+    defineCount: 1,
+    manifestFiles: 0,
+    manifestAssetCount: 0,
+    streams: 1,
+    sourceCandidates: 1,
+    elapsedMs: 1,
+  };
+}
+
+const CANNON_XML = `<AssetDeclaration xmlns="uri:ea.com:eala:asset">
+  <GameObject id="AthenaCannon" inheritFrom="BaseCannon">
+    <CreateObjectDie><CreateObject>AthenaCannon_Die</CreateObject></CreateObjectDie>
+  </GameObject>
+</AssetDeclaration>`;
+
+const BASE_XML = `<AssetDeclaration xmlns="uri:ea.com:eala:asset">
+  <GameObject id="BaseCannon">
+    <WeaponSetUpdate><WeaponSlotHardpoint><Weapon Template="AthenaCannonWeapon" /></WeaponSlotHardpoint></WeaponSetUpdate>
+  </GameObject>
+</AssetDeclaration>`;
+
+const FILES = {
+  "D:/Mods/Example/Data/AthenaCannon.xml": CANNON_XML,
+  "D:/Mods/Example/Data/BaseCannon.xml": BASE_XML,
+};
+
+function makeIndex(projectDir, unitId, extraDefs = []) {
+  const file = `${projectDir}/Data/${unitId}.xml`;
+  const unit = { type: "GameObject", id: unitId, file, line: 2, origin: "project", stream: "static" };
+  const all = [unit, ...extraDefs];
+  const assets = new Map();
+  const assetsById = new Map();
+  for (const d of all) {
+    if (!assets.has(d.type)) assets.set(d.type, new Map());
+    const byId = assets.get(d.type);
+    if (!byId.has(d.id.toLowerCase())) byId.set(d.id.toLowerCase(), []);
+    byId.get(d.id.toLowerCase()).push(d);
+    const key = d.id.toLowerCase();
+    if (!assetsById.has(key)) assetsById.set(key, []);
+    assetsById.get(key).push(d);
+  }
+  return {
+    projectDir,
+    sdkDir: "",
+    complete: true,
+    phase: "art",
+    stale: false,
+    assets,
+    assetsById,
+    defines: new Map([
+      ["exampledefine", [{ name: "ExampleDefine", value: "1", file, line: 2, origin: "project" }]],
+    ]),
+    files: new Map(),
+    streams: [
+      {
+        name: "static",
+        entry: `${projectDir}/Data/Mod.xml`,
+        files: new Set([file.toLowerCase().replace(/\\/g, "/")]),
+      },
+    ],
+    manifests: new Map(),
+    sourceCandidates: [],
+    diagnostics: [],
+    references: new Map([
+      [
+        `GameObject\u0000${unitId.toLowerCase()}\u0000${file}\u00002`,
+        [{ file: `${projectDir}/Data/Other.xml`, line: 3, start: 1, end: 2, kind: "attr" }],
+      ],
+    ]),
+    recordsHashes: new Map(),
+    stats: makeStats(),
+  };
+}
+
+const PROJECT_A_RELATED = [
+  {
+    type: "GameObject",
+    id: "BaseCannon",
+    file: "D:/Mods/Example/Data/BaseCannon.xml",
+    line: 2,
+    origin: "project",
+    stream: "static",
+  },
+  {
+    type: "GameObject",
+    id: "AthenaCannon_Die",
+    file: "D:/Mods/Example/Data/AthenaCannon_Die.xml",
+    line: 2,
+    origin: "project",
+    stream: "static",
+  },
+  {
+    type: "WeaponTemplate",
+    id: "AthenaCannonWeapon",
+    file: "D:/Mods/Example/Data/Weapon.xml",
+    line: 88,
+    origin: "project",
+    stream: "static",
+  },
+];
+
+/** Routes to a distinct index per requested project, like the extension does. */
+function routedServerOptions() {
+  const indexes = new Map([
+    [PROJECT_A, makeIndex(PROJECT_A, "AthenaCannon", PROJECT_A_RELATED)],
+    [PROJECT_B, makeIndex(PROJECT_B, "OtherUnit")],
+  ]);
+  return {
+    getIndex: (projectDir) => (projectDir ? indexes.get(projectDir) ?? null : indexes.get(PROJECT_A)),
+    listProjects: () => [...indexes.keys()],
+    loadFile: async (file) => {
+      const text = FILES[file];
+      return text ? parseLoadedXml(text) : null;
+    },
+  };
+}
+
+async function withServer(fn) {
+  const handle = await startLocalServer({ ...routedServerOptions(), token: "test-token" });
+  const base = `http://127.0.0.1:${handle.port}`;
+  const headers = { authorization: "Bearer test-token" };
+  const get = async (path) => (await fetch(`${base}${path}`, { headers })).json();
+  try {
+    await fn({ base, headers, get });
+  } finally {
+    await handle.close();
+  }
+}
+
+test("local server requires the bearer token", async () => {
+  await withServer(async ({ base }) => {
+    const unauthorized = await fetch(`${base}/status`);
+    assert.equal(unauthorized.status, 401);
+    const forbidden = await fetch(`${base}/status`, {
+      headers: { authorization: "Bearer wrong" },
+    });
+    assert.equal(forbidden.status, 401);
+  });
+});
+
+test("local server exposes read-only queries", async () => {
+  await withServer(async ({ get }) => {
+    const status = await get(`/status?project=${encodeURIComponent(PROJECT_A)}`);
+    assert.equal(status.state, "ready");
+    assert.equal(status.projectDir, PROJECT_A);
+
+    const asset = await get(
+      `/find_asset?project=${encodeURIComponent(PROJECT_A)}&id=AthenaCannon&type=GameObject`,
+    );
+    assert.equal(asset.data.length, 1);
+
+    const refs = await get(
+      `/find_references?project=${encodeURIComponent(PROJECT_A)}&id=AthenaCannon`,
+    );
+    assert.equal(refs.data.length, 1);
+
+    const active = await get(
+      `/is_file_active?project=${encodeURIComponent(PROJECT_A)}&path=D:/Mods/Example/Data/AthenaCannon.xml`,
+    );
+    assert.equal(active.data.active, true);
+  });
+});
+
+test("?project= selects the index instead of the active editor's project", async () => {
+  await withServer(async ({ get }) => {
+    const a = await get(`/find_asset?project=${encodeURIComponent(PROJECT_A)}&id=AthenaCannon`);
+    assert.equal(a.index.projectDir, PROJECT_A);
+    assert.equal(a.data.length, 1);
+
+    const b = await get(`/find_asset?project=${encodeURIComponent(PROJECT_B)}&id=OtherUnit`);
+    assert.equal(b.index.projectDir, PROJECT_B);
+    assert.equal(b.data.length, 1);
+
+    // The same id must not resolve when asked about the other project.
+    const cross = await get(
+      `/find_asset?project=${encodeURIComponent(PROJECT_B)}&id=AthenaCannon`,
+    );
+    assert.equal(cross.data.length, 0);
+    assert.equal(cross.index.projectDir, PROJECT_B);
+  });
+});
+
+test("an unknown project reports no_index without faking a projectDir", async () => {
+  await withServer(async ({ get }) => {
+    const unknown = "D:/Mods/Unknown";
+    const result = await get(`/status?project=${encodeURIComponent(unknown)}`);
+    assert.equal(result.state, "no_index");
+    assert.equal(result.projectDir, unknown);
+  });
+});
+
+test("/projects lists the known roots", async () => {
+  await withServer(async ({ get }) => {
+    const result = await get("/projects");
+    assert.deepEqual(new Set(result.data), new Set([PROJECT_A, PROJECT_B]));
+  });
+});
+
+test("/get_asset_references returns provenance-carrying edges", async () => {
+  await withServer(async ({ get }) => {
+    const result = await get(
+      `/get_asset_references?project=${encodeURIComponent(PROJECT_A)}&id=AthenaCannon&type=GameObject`,
+    );
+    assert.equal(result.index.state, "ready");
+    const data = result.data;
+    assert.ok(data, "expected a data payload");
+    assert.equal(data.edges.length >= 3, true);
+
+    const weapon = data.edges.find((e) => e.to?.id === "AthenaCannonWeapon");
+    assert.ok(weapon, "expected the inherited weapon edge");
+    assert.equal(weapon.via.element, "Weapon");
+    assert.equal(weapon.via.parent, "WeaponSlotHardpoint");
+    assert.equal(weapon.definedIn.id, "BaseCannon");
+    assert.equal(weapon.source.file, "D:/Mods/Example/Data/BaseCannon.xml");
+
+    const die = data.edges.find((e) => e.via.kind === "content");
+    assert.ok(die, "expected the CreateObjectDie content edge");
+    assert.equal(die.to.id, "AthenaCannon_Die");
+  });
+});
+
+test("/get_asset_references honours targetTypes and depth parameters", async () => {
+  await withServer(async ({ get }) => {
+    const filtered = await get(
+      `/get_asset_references?project=${encodeURIComponent(PROJECT_A)}&id=AthenaCannon&targetTypes=WeaponTemplate`,
+    );
+    for (const edge of filtered.data.edges) {
+      if (edge.via.kind === "inheritFrom") continue;
+      assert.equal(edge.to.type, "WeaponTemplate");
+    }
+
+    const shallow = await get(
+      `/get_asset_references?project=${encodeURIComponent(PROJECT_A)}&id=AthenaCannon&depth=1`,
+    );
+    for (const edge of shallow.data.edges) {
+      assert.equal(edge.depth, 1);
+    }
+
+    const deep = await get(
+      `/get_asset_references?project=${encodeURIComponent(PROJECT_A)}&id=AthenaCannon&depth=2`,
+    );
+    for (const edge of deep.data.edges) {
+      assert.ok(edge.depth <= 2);
+    }
+  });
+});
+
+test("/get_asset_references explains itself when live data is unavailable", async () => {
+  await withServer(async ({ get }) => {
+    const missing = await get(`/get_asset_references?project=${encodeURIComponent(PROJECT_A)}&id=Nope`);
+    assert.equal(missing.data.roots.length, 0);
+    assert.ok(missing.data.warnings.length > 0);
+  });
+});

test/agentMcpRouting.test.mjs

@@ -0,0 +1,73 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  liveUrlForTool,
+  normalizePath,
+  responseProjectMismatch,
+} from "../out/agent/mcpServer.js";
+
+const PROJECT_A = "D:/Mods/Example";
+
+test("live URLs always pin the requested project", () => {
+  const url = liveUrlForTool("http://127.0.0.1:1234", PROJECT_A, "find_asset", {
+    id: "AthenaCannon",
+    type: "GameObject",
+  });
+  assert.ok(url);
+  const parsed = new URL(url);
+  assert.equal(parsed.pathname, "/find_asset");
+  assert.equal(parsed.searchParams.get("project"), PROJECT_A);
+  assert.equal(parsed.searchParams.get("id"), "AthenaCannon");
+  assert.equal(parsed.searchParams.get("type"), "GameObject");
+});
+
+test("get_asset_references serialises its list and scalar options", () => {
+  const url = liveUrlForTool("http://127.0.0.1:1234/", PROJECT_A, "get_asset_references", {
+    id: "AthenaCannon",
+    depth: 2,
+    targetTypes: ["WeaponTemplate", "GameObject"],
+    maxEdges: 25,
+    includeUnresolved: true,
+  });
+  assert.ok(url);
+  const parsed = new URL(url);
+  assert.equal(parsed.pathname, "/get_asset_references");
+  assert.equal(parsed.searchParams.get("depth"), "2");
+  assert.equal(parsed.searchParams.get("targetTypes"), "WeaponTemplate,GameObject");
+  assert.equal(parsed.searchParams.get("maxEdges"), "25");
+  assert.equal(parsed.searchParams.get("includeUnresolved"), "true");
+  assert.equal(parsed.searchParams.get("project"), PROJECT_A);
+});
+
+test("live URLs omit the project selector when none is configured", () => {
+  const url = liveUrlForTool("http://127.0.0.1:1234", null, "get_status", {});
+  assert.equal(url, "http://127.0.0.1:1234/status");
+});
+
+test("unknown tools have no live URL", () => {
+  assert.equal(liveUrlForTool("http://127.0.0.1:1", PROJECT_A, "nope", {}), null);
+});
+
+test("responseProjectMismatch flags answers from another project", () => {
+  // Matching project (case/separator-insensitive) is accepted.
+  assert.equal(
+    responseProjectMismatch({ index: { projectDir: "d:/mods/example" } }, PROJECT_A),
+    false,
+  );
+  // A different project must be rejected: this is the multi-window cross-talk guard.
+  assert.equal(
+    responseProjectMismatch({ index: { projectDir: "D:/Mods/Other" } }, PROJECT_A),
+    true,
+  );
+  // No project configured, or no projectDir in the payload: nothing to check.
+  assert.equal(responseProjectMismatch({ index: { state: "ready" } }, PROJECT_A), false);
+  assert.equal(
+    responseProjectMismatch({ index: { projectDir: "D:/Mods/Other" } }, null),
+    false,
+  );
+  assert.equal(responseProjectMismatch(null, PROJECT_A), false);
+});
+
+test("normalizePath is case- and separator-insensitive", () => {
+  assert.equal(normalizePath("D:\\Mods\\Example\\"), normalizePath("d:/mods/example"));
+});

test/agentSetup.test.mjs

@@ -0,0 +1,36 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  addMcpServerToConfigFile,
+  mcpConfigJson,
+  mcpServerConfig,
+} from "../out/agent/setup.js";
+
+test("mcpServerConfig and mcpConfigJson use the stable launcher", () => {
+  const config = mcpServerConfig("C:/Users/me/.ra3modxml/ra3-mod-xml-mcp.cmd", "D:/Mods/Example");
+  assert.deepEqual(config.mcpServers["ra3-mod-xml"].args, ["--project", "D:/Mods/Example"]);
+  const json = mcpConfigJson("C:/launcher.cmd", "D:/Proj");
+  assert.ok(json.includes("C:/launcher.cmd"));
+  assert.ok(json.includes("D:/Proj"));
+});
+
+test("addMcpServerToConfigFile creates and merges config", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "ra3-setup-test-"));
+  try {
+    const file = join(dir, "mcp.json");
+    await addMcpServerToConfigFile(file, "C:/launcher.cmd", "D:/Proj");
+    const first = JSON.parse(readFileSync(file, "utf8"));
+    assert.ok(first.mcpServers["ra3-mod-xml"]);
+
+    writeFileSync(file, JSON.stringify({ mcpServers: { other: { command: "x" } } }, null, 2));
+    await addMcpServerToConfigFile(file, "C:/launcher.cmd", "D:/Proj");
+    const merged = JSON.parse(readFileSync(file, "utf8"));
+    assert.ok(merged.mcpServers.other);
+    assert.ok(merged.mcpServers["ra3-mod-xml"]);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

test/agentSkill.test.mjs

@@ -0,0 +1,77 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  SKILL_MARKER_FILE,
+  installSkillToDirectories,
+  readSkillInstallRecord,
+  uninstallSkillFromDirectory,
+  writeSkillTo,
+} from "../out/agent/skill.js";
+
+test("writeSkillTo creates SKILL.md and avoids project-doc noise", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "ra3-skill-test-"));
+  try {
+    const skillDir = join(dir, "ra3-mod-xml");
+    await writeSkillTo(skillDir, "0.1.25");
+    assert.ok(existsSync(join(skillDir, "SKILL.md")));
+    assert.ok(existsSync(join(skillDir, "references", "query-guide.md")));
+    assert.ok(existsSync(join(skillDir, SKILL_MARKER_FILE)));
+    const content = readFileSync(join(skillDir, "SKILL.md"), "utf8");
+    assert.ok(content.includes("find_asset"));
+    assert.ok(!content.includes("codebase-navigation-guide"));
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("SKILL.md scopes itself to SAGE/RA3 projects and warns off others", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "ra3-skill-scope-"));
+  try {
+    const skillDir = join(dir, "ra3-mod-xml");
+    await writeSkillTo(skillDir, "0.1.25");
+    const content = readFileSync(join(skillDir, "SKILL.md"), "utf8");
+
+    // Must state its applicability and list concrete positive signals.
+    assert.match(content, /When this skill applies/);
+    assert.ok(content.includes("Data/Mod.xml"));
+    assert.ok(content.includes("babproj"));
+    assert.ok(content.includes("AssetDeclaration"));
+
+    // Must give an explicit negative rule and a cheap probe.
+    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.
+    assert.ok(content.includes("CnC3Types.xsd"));
+    assert.ok(content.includes("C&C3"));
+
+    // Second-phase capability must be documented.
+    assert.ok(content.includes("get_asset_references"));
+    assert.ok(content.includes("definedIn"));
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("installSkillToDirectories records managed copies and uninstall removes them", async () => {
+  const home = mkdtempSync(join(tmpdir(), "ra3-skill-home-"));
+  const dir = mkdtempSync(join(tmpdir(), "ra3-skill-target-"));
+  try {
+    const target = join(dir, "ra3-mod-xml");
+    const succeeded = await installSkillToDirectories([target], "0.1.25", home);
+    assert.deepEqual(succeeded, [target]);
+    const record = await readSkillInstallRecord(home);
+    assert.equal(record.length, 1);
+    assert.equal(record[0].path, target);
+
+    await uninstallSkillFromDirectory(target, home);
+    assert.equal(existsSync(target), false);
+    assert.equal((await readSkillInstallRecord(home)).length, 0);
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

test/agentSnapshot.test.mjs

@@ -0,0 +1,184 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { snapshotFromIndex, writeSnapshotFile, readSnapshotFile } from "../out/agent/snapshot.js";
+import {
+  findAssets,
+  findReferenceGroups,
+  isFileActive,
+  listAssetsByType,
+  resolveIncludeSource,
+  statusFromSnapshot,
+} from "../out/agent/query.js";
+
+function makeStats() {
+  return {
+    projectDir: "P",
+    sdkDir: "",
+    phase: "art",
+    complete: true,
+    indexedFiles: 3,
+    parsedFiles: 2,
+    shallowScannedFiles: 1,
+    deferredArtFiles: 0,
+    shallowCacheHits: 0,
+    recordsCacheHits: 0,
+    resolveCacheHits: 0,
+    resolveCalls: 0,
+    snapshotHits: 0,
+    snapshotFallbacks: 0,
+    candidatesMs: 0,
+    walkMs: 0,
+    artScanMs: 0,
+    assetCount: 2,
+    referenceCount: 1,
+    defineCount: 1,
+    manifestFiles: 0,
+    manifestAssetCount: 0,
+    streams: 1,
+    sourceCandidates: 1,
+    elapsedMs: 1,
+  };
+}
+
+function makeIndex() {
+  const file = "D:/Mods/Example/Data/Units/Example.xml";
+  const assets = new Map([
+    [
+      "GameObject",
+      new Map([
+        [
+          "exampleunit",
+          [
+            {
+              type: "GameObject",
+              id: "ExampleUnit",
+              file,
+              line: 5,
+              origin: "project",
+              stream: "static",
+            },
+          ],
+        ],
+      ]),
+    ],
+  ]);
+  const references = new Map([
+    [
+      "GameObject\u0000exampleunit\u0000D:/Mods/Example/Data/Units/Example.xml\u00005",
+      [
+        {
+          file: "D:/Mods/Example/Data/Other.xml",
+          line: 3,
+          start: 10,
+          end: 21,
+          kind: "attr",
+        },
+      ],
+    ],
+  ]);
+  return {
+    projectDir: "D:/Mods/Example",
+    sdkDir: "",
+    complete: true,
+    phase: "art",
+    stale: false,
+    assets,
+    assetsById: new Map([
+      [
+        "exampleunit",
+        [
+          {
+            type: "GameObject",
+            id: "ExampleUnit",
+            file,
+            line: 5,
+            origin: "project",
+            stream: "static",
+          },
+        ],
+      ],
+    ]),
+    defines: new Map([
+      [
+        "exampledefine",
+        [
+          {
+            name: "ExampleDefine",
+            value: "1",
+            file,
+            line: 2,
+            origin: "project",
+          },
+        ],
+      ],
+    ]),
+    files: new Map(),
+    streams: [
+      {
+        name: "static",
+        entry: "D:/Mods/Example/Data/Mod.xml",
+        files: new Set(["d:/mods/example/data/units/example.xml"]),
+      },
+    ],
+    manifests: new Map(),
+    sourceCandidates: [
+      {
+        source: "DATA:Units/Example.xml",
+        path: "D:/Mods/Example/Data/Units/Example.xml",
+        prefix: "DATA",
+        baseDir: "D:/Mods/Example/Data",
+      },
+    ],
+    diagnostics: [],
+    references,
+    recordsHashes: new Map(),
+    stats: makeStats(),
+  };
+}
+
+test("snapshotFromIndex flattens assets, defines, streams and references", () => {
+  const snapshot = snapshotFromIndex(makeIndex(), 42);
+  assert.equal(snapshot.schemaVersion, 1);
+  assert.equal(snapshot.assets.length, 1);
+  assert.equal(snapshot.assets[0].id, "ExampleUnit");
+  assert.equal(snapshot.defines.length, 1);
+  assert.equal(snapshot.streams.length, 1);
+  assert.deepEqual(snapshot.streams[0].files, [
+    "d:/mods/example/data/units/example.xml",
+  ]);
+  assert.equal(snapshot.references.length, 1);
+  assert.equal(snapshot.references[0].sites.length, 1);
+  assert.equal(snapshot.buildId, 42);
+});
+
+test("query helpers operate on snapshots", () => {
+  const snapshot = snapshotFromIndex(makeIndex(), 1);
+  assert.equal(findAssets(snapshot, "ExampleUnit").length, 1);
+  assert.equal(findAssets(snapshot, "exampleunit", "GameObject").length, 1);
+  assert.equal(findAssets(snapshot, "exampleunit", "WeaponTemplate").length, 0);
+  assert.equal(listAssetsByType(snapshot, "gameobject", "exa").length, 1);
+  assert.equal(findReferenceGroups(snapshot, "ExampleUnit").length, 1);
+  assert.equal(isFileActive(snapshot, "D:/Mods/Example/Data/Units/Example.xml"), true);
+  assert.equal(isFileActive(snapshot, "D:/Mods/Example/Data/Dead.xml"), false);
+  assert.equal(resolveIncludeSource(snapshot, "data:units/example.xml")?.path, "D:/Mods/Example/Data/Units/Example.xml");
+  assert.equal(statusFromSnapshot(snapshot).state, "ready");
+});
+
+test("snapshot file write/read round-trips", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "ra3-agent-test-"));
+  try {
+    const file = join(dir, "snapshot.json.gz");
+    const snapshot = snapshotFromIndex(makeIndex(), 7);
+    await writeSnapshotFile(file, snapshot);
+    const loaded = await readSnapshotFile(file);
+    assert.ok(loaded);
+    assert.equal(loaded.assets.length, snapshot.assets.length);
+    assert.equal(loaded.references[0].sites[0].file, "D:/Mods/Example/Data/Other.xml");
+    assert.equal(loaded.buildId, 7);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});