ai agent

src/agent/skill.ts

@@ -73,6 +73,46 @@ Use this skill when you need any of the following:
 Do not use full-text search over the XML tree when one of the MCP query tools
 can answer the question directly.
 
+## Reaching the index
+
+Work down this list and stop at the first step that works.
+
+1. **The query tools are already in your tool list** (names like
+   \`find_asset\`, \`get_status\`). Use them directly. You do not need to
+   configure anything.
+
+2. **The tools are not available, but you can run commands.** The index is
+   reachable without any MCP setup, because the MCP server speaks JSON-RPC over
+   stdio. Read \`~/.ra3modxml/index.json\` first: it is a small, stable
+   discovery manifest listing the live instances and their project roots.
+
+   - If it does not exist, the extension has never been enabled for this
+     project. Tell the user to open the project in VS Code and run
+     "RA3 Mod XML: Enable AI Agent access…". Do not guess or search further.
+   - If it exists, use the launcher at \`~/.ra3modxml/ra3-mod-xml-mcp.cmd\`
+     (Windows) or \`~/.ra3modxml/ra3-mod-xml-mcp\` (elsewhere), or call the
+     bundled server directly through that instance's runtime. Feed it one
+     JSON-RPC request per line on stdin, for example:
+
+     \`\`\`
+     {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"find_asset","arguments":{"id":"AthenaCannon","type":"GameObject"}}}
+     \`\`\`
+
+     A CLI with the same capabilities is bundled alongside the MCP server
+     (\`cli.js\` next to \`mcpServer.js\` in the extension's \`dist/agent/\`).
+     Run it with the same runtime as the launcher; \`cli.js help\` lists the
+     commands. It answers from the live index when VS Code is running and
+     falls back to the last exported snapshot otherwise. Commands that need
+     element context (\`outgoing\`, \`projects\`) require the live index and will
+     say so explicitly instead of returning an empty result.
+
+3. **You can write configuration, if the user agrees.** You may add the MCP
+   server to the your own harness' configuration.
+   Check what your own client supports (e.g. if a restart is required)
+   before promising otherwise.
+
+If none of the steps work, say the index is unavailable and read the XML files directly.
+
 ## How to use
 
 1. Call \`get_status\` first when you are unsure whether an index is available,
@@ -83,8 +123,7 @@ can answer the question directly.
    - \`get_asset_references(id, type?, depth?, targetTypes?)\` for outgoing
      references (what this asset uses, and where that link is written).
    - \`list_assets_by_type(type, prefix?, limit?)\` for browsing assets.
-   - \`is_file_active(path)\` to determine whether a file is included in an indexed stream.
-   - \`find_define(name)\` for $DEFINE constants.
+   - \`is_file_active(path)\` to determine whether a file is included in an indexed stream.   - \`find_define(name)\` for $DEFINE constants.
    - \`resolve_include(source)\` for Include source candidates.
 3. Asset ids are case-insensitive.
 4. If an id exists for multiple asset types, pass the type filter to avoid mixing definitions.