cwtools-shared 0.2.3 → 0.2.5

package/dist/generated/mcpTools.d.ts

@@ -203,18 +203,21 @@ export declare const GENERATED_MCP_TOOLS: readonly [{
             readonly properties: {
                 readonly file: {
                     readonly type: "string";
-                    readonly description: "Absolute file path";
+                    readonly description: "Absolute path inside the workspace or a configured game installation.";
                 };
                 readonly line: {
-                    readonly type: "number";
+                    readonly type: "integer";
+                    readonly minimum: 0;
                     readonly description: "Line number (0-based)";
                 };
                 readonly column: {
-                    readonly type: "number";
+                    readonly type: "integer";
+                    readonly minimum: 0;
                     readonly description: "Column number (0-based)";
                 };
             };
             readonly required: readonly ["file", "line", "column"];
+            readonly additionalProperties: false;
         };
     };
     readonly registry: {
@@ -292,10 +295,6 @@ export declare const GENERATED_MCP_TOOLS: readonly [{
                     readonly type: "object";
                     readonly description: "Optional raw failed tool result to classify without querying diagnostics again.";
                 };
-                readonly reflection: {
-                    readonly type: "string";
-                    readonly description: "Optional legacy free-form analysis from the model. Kept for backward compatibility; the host still returns deterministic routing advice.";
-                };
             };
             readonly required: readonly [];
         };
@@ -311,19 +310,19 @@ export declare const GENERATED_MCP_TOOLS: readonly [{
 }, {
     readonly tool: {
         readonly name: "query_project_profile";
-        readonly description: "Read the /init-generated Agent project profile from .cwtools/project/profile.json. Use this before broad scans to get workspace type, key directories, localisation languages/encoding, namespaces, workflow routing, validation hints, and mode-specific prompt cards.";
+        readonly description: "Read the /init-generated Agent project profile from .cwtools/project/profile.json. Use this before broad scans to get workspace type, key directories, localisation languages/encoding, namespaces, workflow routing, validation hints, and targeted guidance cards.";
         readonly inputSchema: {
             readonly type: "object";
             readonly properties: {
                 readonly section: {
                     readonly type: "string";
-                    readonly enum: readonly ["summary", "routing", "directories", "localisation", "identifiers", "validation", "compatibility", "promptCards", "all"];
+                    readonly enum: readonly ["summary", "routing", "directories", "localisation", "identifiers", "validation", "compatibility", "guidanceCards", "all"];
                     readonly description: "Targeted profile section to return. Default summary. Use all only when you need the whole profile.";
                 };
-                readonly mode: {
+                readonly guidance: {
                     readonly type: "string";
-                    readonly enum: readonly ["build", "plan", "explore", "general", "utility", "review", "gui_expert", "script_reviewer", "loc_translator", "loc_writer", "orchestrator", "script", "asset"];
-                    readonly description: "Optional mode card to return, e.g. build, plan, loc_writer, asset, orchestrator, script.";
+                    readonly enum: readonly ["implementation", "planning", "exploration", "review", "utility", "localisation", "assets", "coordination", "paradox_coordination"];
+                    readonly description: "Optional guidance card to return for the current task concern.";
                 };
             };
             readonly required: readonly [];
@@ -485,7 +484,7 @@ export declare const GENERATED_MCP_TOOLS: readonly [{
                 };
                 readonly file: {
                     readonly type: "string";
-                    readonly description: "Optional workspace-relative or absolute file path used to restrict entry points.";
+                    readonly description: "Optional workspace-relative path or absolute path inside the workspace/configured game installation used to restrict entry points.";
                 };
                 readonly typeName: {
                     readonly type: "string";
@@ -550,7 +549,7 @@ export declare const GENERATED_MCP_TOOLS: readonly [{
                 };
                 readonly file: {
                     readonly type: "string";
-                    readonly description: "Caller file; narrows to one invocation.";
+                    readonly description: "Caller file inside the workspace or a configured game installation; narrows to one invocation.";
                 };
                 readonly line: {
                     readonly type: "number";
@@ -581,7 +580,7 @@ export declare const GENERATED_MCP_TOOLS: readonly [{
             readonly properties: {
                 readonly file: {
                     readonly type: "string";
-                    readonly description: "Optional file path to analyze; when omitted a definitionId must be given.";
+                    readonly description: "Optional path inside the workspace or a configured game installation; when omitted a definitionId must be given.";
                 };
                 readonly definitionId: {
                     readonly type: "string";
@@ -700,13 +699,13 @@ export declare const GENERATED_MCP_TOOLS: readonly [{
 }, {
     readonly tool: {
         readonly name: "get_pdx_block";
-        readonly description: "Extract exactly one complete AST block by symbol name. Works with .txt (events, common), .gui (containerWindowType by name), and .gfx (pdxmesh by name). Returns 1-based startLine/endLine that can be passed directly to replace_lines. If the symbol is not found, the error response includes a full list of available symbols with line ranges so you can retry with the correct name.";
+        readonly description: "Extract exactly one complete AST block by symbol name from the workspace or a configured game installation. Works with .txt (events, common), .gui (containerWindowType by name), and .gfx (pdxmesh by name). Returns 1-based startLine/endLine that can be passed directly to replace_lines. If the symbol is not found, the error response includes a full list of available symbols with line ranges so you can retry with the correct name.";
         readonly inputSchema: {
             readonly type: "object";
             readonly properties: {
                 readonly file: {
                     readonly type: "string";
-                    readonly description: "Absolute file path";
+                    readonly description: "Absolute path inside the workspace or a configured game installation.";
                 };
                 readonly symbol: {
                     readonly type: "string";
@@ -733,7 +732,7 @@ export declare const GENERATED_MCP_TOOLS: readonly [{
             readonly properties: {
                 readonly file: {
                     readonly type: "string";
-                    readonly description: "Absolute file path (must be in the workspace)";
+                    readonly description: "Absolute file path inside the workspace or a configured game installation.";
                 };
                 readonly line: {
                     readonly type: "number";
@@ -768,7 +767,7 @@ export declare const GENERATED_MCP_TOOLS: readonly [{
             readonly properties: {
                 readonly file: {
                     readonly type: "string";
-                    readonly description: "Absolute file path";
+                    readonly description: "Absolute path inside the workspace or a configured game installation.";
                 };
             };
             readonly required: readonly ["file"];
@@ -811,29 +810,34 @@ export declare const GENERATED_MCP_TOOLS: readonly [{
     };
 }, {
     readonly tool: {
-        readonly name: "query_definition";
-        readonly description: "GoToDefinition at a position, or FindAllRefs if no definition exists. Uses CWTools AST - faster than grep. If you know the symbol name, prefer query_definition_by_name instead.";
+        readonly name: "go_to_definition";
+        readonly description: "Find a definition by exact symbol name or by a 0-based file position. Uses CWTools semantic lookup when available and falls back to the active VS Code language provider.";
         readonly inputSchema: {
             readonly type: "object";
             readonly properties: {
+                readonly symbolName: {
+                    readonly type: "string";
+                    readonly description: "Exact symbol name. Use this instead of file/line/column when the identifier is known.";
+                };
                 readonly file: {
                     readonly type: "string";
-                    readonly description: "Absolute file path";
+                    readonly description: "Absolute file path inside the workspace or a configured game installation.";
                 };
                 readonly line: {
                     readonly type: "number";
-                    readonly description: "Line number (0-based)";
+                    readonly description: "Line number (0-based).";
                 };
                 readonly column: {
                     readonly type: "number";
-                    readonly description: "Column number (0-based)";
+                    readonly description: "Column number (0-based).";
                 };
             };
-            readonly required: readonly ["file", "line", "column"];
+            readonly required: readonly [];
+            readonly additionalProperties: false;
         };
     };
     readonly registry: {
-        readonly name: "query_definition";
+        readonly name: "go_to_definition";
         readonly isWrite: false;
         readonly isReadOnly: true;
         readonly effect: "workspace_read";
@@ -842,48 +846,38 @@ export declare const GENERATED_MCP_TOOLS: readonly [{
     };
 }, {
     readonly tool: {
-        readonly name: "query_definition_by_name";
-        readonly description: "Find where a named symbol is defined - no file/position needed. Returns file path and line number. Works for any top-level PDXScript key (events, triggers, effects, etc.).";
-        readonly inputSchema: {
-            readonly type: "object";
-            readonly properties: {
-                readonly symbolName: {
-                    readonly type: "string";
-                    readonly description: "The exact name of the symbol to find (e.g. \"samplemod_has_psionic_research\", \"distar.001\")";
-                };
-            };
-            readonly required: readonly ["symbolName"];
-        };
-    };
-    readonly registry: {
-        readonly name: "query_definition_by_name";
-        readonly isWrite: false;
-        readonly isReadOnly: true;
-        readonly effect: "workspace_read";
-        readonly riskLevel: 0;
-        readonly concurrencyClass: "parallel";
-    };
-}, {
-    readonly tool: {
-        readonly name: "query_references";
-        readonly description: "Find references to an identifier through the active language provider, with a bounded workspace text-search fallback.";
+        readonly name: "find_references";
+        readonly description: "Find references by exact identifier or by a 0-based file position. Identifier lookup uses workspace symbols plus a bounded text fallback; position lookup uses the active VS Code language provider.";
         readonly inputSchema: {
             readonly type: "object";
             readonly properties: {
                 readonly identifier: {
                     readonly type: "string";
-                    readonly description: "The identifier to search for";
+                    readonly description: "Exact identifier. Use this instead of file/line/column when the name is known.";
                 };
                 readonly file: {
                     readonly type: "string";
-                    readonly description: "Optional file to limit search to";
+                    readonly description: "Absolute file path inside the workspace or a configured game installation.";
+                };
+                readonly line: {
+                    readonly type: "number";
+                    readonly description: "Line number (0-based).";
+                };
+                readonly column: {
+                    readonly type: "number";
+                    readonly description: "Column number (0-based).";
+                };
+                readonly limit: {
+                    readonly type: "number";
+                    readonly description: "Maximum references to return (default 100, max 500).";
                 };
             };
-            readonly required: readonly ["identifier"];
+            readonly required: readonly [];
+            readonly additionalProperties: false;
         };
     };
     readonly registry: {
-        readonly name: "query_references";
+        readonly name: "find_references";
         readonly isWrite: false;
         readonly isReadOnly: true;
         readonly effect: "workspace_read";
@@ -1030,7 +1024,7 @@ export declare const GENERATED_MCP_TOOLS: readonly [{
             readonly properties: {
                 readonly file: {
                     readonly type: "string";
-                    readonly description: "Absolute file path (must be a parsed mod file)";
+                    readonly description: "Absolute path to a parsed file inside the workspace or a configured game installation.";
                 };
             };
             readonly required: readonly ["file"];
@@ -1089,7 +1083,7 @@ export declare const GENERATED_MCP_TOOLS: readonly [{
             readonly properties: {
                 readonly file: {
                     readonly type: "string";
-                    readonly description: "Absolute or workspace-relative path of the .shader/.fxh file.";
+                    readonly description: "Workspace-relative path or absolute path inside the workspace/configured game installation.";
                 };
             };
             readonly required: readonly ["file"];
@@ -1112,7 +1106,7 @@ export declare const GENERATED_MCP_TOOLS: readonly [{
             readonly properties: {
                 readonly file: {
                     readonly type: "string";
-                    readonly description: "Absolute or workspace-relative path of the .shader/.fxh file.";
+                    readonly description: "Workspace-relative path or absolute path inside the workspace/configured game installation.";
                 };
             };
             readonly required: readonly ["file"];
@@ -1166,7 +1160,7 @@ export declare const GENERATED_MCP_TOOLS: readonly [{
                 };
                 readonly file: {
                     readonly type: "string";
-                    readonly description: "Absolute or workspace-relative path of a .shader/.fxh file; lists its Effects with cursor pagination.";
+                    readonly description: "Workspace-relative path or absolute path inside the workspace/configured game installation; lists its Effects with cursor pagination.";
                 };
                 readonly limit: {
                     readonly type: "number";
@@ -1197,7 +1191,7 @@ export declare const GENERATED_MCP_TOOLS: readonly [{
             readonly properties: {
                 readonly file: {
                     readonly type: "string";
-                    readonly description: "Absolute or workspace-relative path of the .shader/.fxh file.";
+                    readonly description: "Workspace-relative path or absolute path inside the workspace/configured game installation.";
                 };
             };
             readonly required: readonly ["file"];
@@ -1224,7 +1218,7 @@ export declare const GENERATED_MCP_TOOLS: readonly [{
                 };
                 readonly file: {
                     readonly type: "string";
-                    readonly description: "Absolute or workspace-relative path of a .shader/.fxh file.";
+                    readonly description: "Workspace-relative path or absolute path inside the workspace/configured game installation.";
                 };
             };
             readonly required: readonly [];

package/dist/generated/mcpTools.js

@@ -234,14 +234,16 @@ exports.GENERATED_MCP_TOOLS = [
                 "properties": {
                     "file": {
                         "type": "string",
-                        "description": "Absolute file path"
+                        "description": "Absolute path inside the workspace or a configured game installation."
                     },
                     "line": {
-                        "type": "number",
+                        "type": "integer",
+                        "minimum": 0,
                         "description": "Line number (0-based)"
                     },
                     "column": {
-                        "type": "number",
+                        "type": "integer",
+                        "minimum": 0,
                         "description": "Column number (0-based)"
                     }
                 },
@@ -249,7 +251,8 @@ exports.GENERATED_MCP_TOOLS = [
                     "file",
                     "line",
                     "column"
-                ]
+                ],
+                "additionalProperties": false
             }
         },
         "registry": {
@@ -334,10 +337,6 @@ exports.GENERATED_MCP_TOOLS = [
                     "toolResult": {
                         "type": "object",
                         "description": "Optional raw failed tool result to classify without querying diagnostics again."
-                    },
-                    "reflection": {
-                        "type": "string",
-                        "description": "Optional legacy free-form analysis from the model. Kept for backward compatibility; the host still returns deterministic routing advice."
                     }
                 },
                 "required": []
@@ -355,7 +354,7 @@ exports.GENERATED_MCP_TOOLS = [
     {
         "tool": {
             "name": "query_project_profile",
-            "description": "Read the /init-generated Agent project profile from .cwtools/project/profile.json. Use this before broad scans to get workspace type, key directories, localisation languages/encoding, namespaces, workflow routing, validation hints, and mode-specific prompt cards.",
+            "description": "Read the /init-generated Agent project profile from .cwtools/project/profile.json. Use this before broad scans to get workspace type, key directories, localisation languages/encoding, namespaces, workflow routing, validation hints, and targeted guidance cards.",
             "inputSchema": {
                 "type": "object",
                 "properties": {
@@ -369,29 +368,25 @@ exports.GENERATED_MCP_TOOLS = [
                             "identifiers",
                             "validation",
                             "compatibility",
-                            "promptCards",
+                            "guidanceCards",
                             "all"
                         ],
                         "description": "Targeted profile section to return. Default summary. Use all only when you need the whole profile."
                     },
-                    "mode": {
+                    "guidance": {
                         "type": "string",
                         "enum": [
-                            "build",
-                            "plan",
-                            "explore",
-                            "general",
-                            "utility",
+                            "implementation",
+                            "planning",
+                            "exploration",
                             "review",
-                            "gui_expert",
-                            "script_reviewer",
-                            "loc_translator",
-                            "loc_writer",
-                            "orchestrator",
-                            "script",
-                            "asset"
+                            "utility",
+                            "localisation",
+                            "assets",
+                            "coordination",
+                            "paradox_coordination"
                         ],
-                        "description": "Optional mode card to return, e.g. build, plan, loc_writer, asset, orchestrator, script."
+                        "description": "Optional guidance card to return for the current task concern."
                     }
                 },
                 "required": []
@@ -564,7 +559,7 @@ exports.GENERATED_MCP_TOOLS = [
                     },
                     "file": {
                         "type": "string",
-                        "description": "Optional workspace-relative or absolute file path used to restrict entry points."
+                        "description": "Optional workspace-relative path or absolute path inside the workspace/configured game installation used to restrict entry points."
                     },
                     "typeName": {
                         "type": "string",
@@ -633,7 +628,7 @@ exports.GENERATED_MCP_TOOLS = [
                     },
                     "file": {
                         "type": "string",
-                        "description": "Caller file; narrows to one invocation."
+                        "description": "Caller file inside the workspace or a configured game installation; narrows to one invocation."
                     },
                     "line": {
                         "type": "number",
@@ -665,7 +660,7 @@ exports.GENERATED_MCP_TOOLS = [
                 "properties": {
                     "file": {
                         "type": "string",
-                        "description": "Optional file path to analyze; when omitted a definitionId must be given."
+                        "description": "Optional path inside the workspace or a configured game installation; when omitted a definitionId must be given."
                     },
                     "definitionId": {
                         "type": "string",
@@ -790,13 +785,13 @@ exports.GENERATED_MCP_TOOLS = [
     {
         "tool": {
             "name": "get_pdx_block",
-            "description": "Extract exactly one complete AST block by symbol name. Works with .txt (events, common), .gui (containerWindowType by name), and .gfx (pdxmesh by name). Returns 1-based startLine/endLine that can be passed directly to replace_lines. If the symbol is not found, the error response includes a full list of available symbols with line ranges so you can retry with the correct name.",
+            "description": "Extract exactly one complete AST block by symbol name from the workspace or a configured game installation. Works with .txt (events, common), .gui (containerWindowType by name), and .gfx (pdxmesh by name). Returns 1-based startLine/endLine that can be passed directly to replace_lines. If the symbol is not found, the error response includes a full list of available symbols with line ranges so you can retry with the correct name.",
             "inputSchema": {
                 "type": "object",
                 "properties": {
                     "file": {
                         "type": "string",
-                        "description": "Absolute file path"
+                        "description": "Absolute path inside the workspace or a configured game installation."
                     },
                     "symbol": {
                         "type": "string",
@@ -827,7 +822,7 @@ exports.GENERATED_MCP_TOOLS = [
                 "properties": {
                     "file": {
                         "type": "string",
-                        "description": "Absolute file path (must be in the workspace)"
+                        "description": "Absolute file path inside the workspace or a configured game installation."
                     },
                     "line": {
                         "type": "number",
@@ -867,7 +862,7 @@ exports.GENERATED_MCP_TOOLS = [
                 "properties": {
                     "file": {
                         "type": "string",
-                        "description": "Absolute file path"
+                        "description": "Absolute path inside the workspace or a configured game installation."
                     }
                 },
                 "required": [
@@ -916,33 +911,34 @@ exports.GENERATED_MCP_TOOLS = [
     },
     {
         "tool": {
-            "name": "query_definition",
-            "description": "GoToDefinition at a position, or FindAllRefs if no definition exists. Uses CWTools AST - faster than grep. If you know the symbol name, prefer query_definition_by_name instead.",
+            "name": "go_to_definition",
+            "description": "Find a definition by exact symbol name or by a 0-based file position. Uses CWTools semantic lookup when available and falls back to the active VS Code language provider.",
             "inputSchema": {
                 "type": "object",
                 "properties": {
+                    "symbolName": {
+                        "type": "string",
+                        "description": "Exact symbol name. Use this instead of file/line/column when the identifier is known."
+                    },
                     "file": {
                         "type": "string",
-                        "description": "Absolute file path"
+                        "description": "Absolute file path inside the workspace or a configured game installation."
                     },
                     "line": {
                         "type": "number",
-                        "description": "Line number (0-based)"
+                        "description": "Line number (0-based)."
                     },
                     "column": {
                         "type": "number",
-                        "description": "Column number (0-based)"
+                        "description": "Column number (0-based)."
                     }
                 },
-                "required": [
-                    "file",
-                    "line",
-                    "column"
-                ]
+                "required": [],
+                "additionalProperties": false
             }
         },
         "registry": {
-            "name": "query_definition",
+            "name": "go_to_definition",
             "isWrite": false,
             "isReadOnly": true,
             "effect": "workspace_read",
@@ -952,53 +948,38 @@ exports.GENERATED_MCP_TOOLS = [
     },
     {
         "tool": {
-            "name": "query_definition_by_name",
-            "description": "Find where a named symbol is defined - no file/position needed. Returns file path and line number. Works for any top-level PDXScript key (events, triggers, effects, etc.).",
-            "inputSchema": {
-                "type": "object",
-                "properties": {
-                    "symbolName": {
-                        "type": "string",
-                        "description": "The exact name of the symbol to find (e.g. \"samplemod_has_psionic_research\", \"distar.001\")"
-                    }
-                },
-                "required": [
-                    "symbolName"
-                ]
-            }
-        },
-        "registry": {
-            "name": "query_definition_by_name",
-            "isWrite": false,
-            "isReadOnly": true,
-            "effect": "workspace_read",
-            "riskLevel": 0,
-            "concurrencyClass": "parallel"
-        }
-    },
-    {
-        "tool": {
-            "name": "query_references",
-            "description": "Find references to an identifier through the active language provider, with a bounded workspace text-search fallback.",
+            "name": "find_references",
+            "description": "Find references by exact identifier or by a 0-based file position. Identifier lookup uses workspace symbols plus a bounded text fallback; position lookup uses the active VS Code language provider.",
             "inputSchema": {
                 "type": "object",
                 "properties": {
                     "identifier": {
                         "type": "string",
-                        "description": "The identifier to search for"
+                        "description": "Exact identifier. Use this instead of file/line/column when the name is known."
                     },
                     "file": {
                         "type": "string",
-                        "description": "Optional file to limit search to"
+                        "description": "Absolute file path inside the workspace or a configured game installation."
+                    },
+                    "line": {
+                        "type": "number",
+                        "description": "Line number (0-based)."
+                    },
+                    "column": {
+                        "type": "number",
+                        "description": "Column number (0-based)."
+                    },
+                    "limit": {
+                        "type": "number",
+                        "description": "Maximum references to return (default 100, max 500)."
                     }
                 },
-                "required": [
-                    "identifier"
-                ]
+                "required": [],
+                "additionalProperties": false
             }
         },
         "registry": {
-            "name": "query_references",
+            "name": "find_references",
             "isWrite": false,
             "isReadOnly": true,
             "effect": "workspace_read",
@@ -1151,7 +1132,7 @@ exports.GENERATED_MCP_TOOLS = [
                 "properties": {
                     "file": {
                         "type": "string",
-                        "description": "Absolute file path (must be a parsed mod file)"
+                        "description": "Absolute path to a parsed file inside the workspace or a configured game installation."
                     }
                 },
                 "required": [
@@ -1220,7 +1201,7 @@ exports.GENERATED_MCP_TOOLS = [
                 "properties": {
                     "file": {
                         "type": "string",
-                        "description": "Absolute or workspace-relative path of the .shader/.fxh file."
+                        "description": "Workspace-relative path or absolute path inside the workspace/configured game installation."
                     }
                 },
                 "required": [
@@ -1246,7 +1227,7 @@ exports.GENERATED_MCP_TOOLS = [
                 "properties": {
                     "file": {
                         "type": "string",
-                        "description": "Absolute or workspace-relative path of the .shader/.fxh file."
+                        "description": "Workspace-relative path or absolute path inside the workspace/configured game installation."
                     }
                 },
                 "required": [
@@ -1306,7 +1287,7 @@ exports.GENERATED_MCP_TOOLS = [
                     },
                     "file": {
                         "type": "string",
-                        "description": "Absolute or workspace-relative path of a .shader/.fxh file; lists its Effects with cursor pagination."
+                        "description": "Workspace-relative path or absolute path inside the workspace/configured game installation; lists its Effects with cursor pagination."
                     },
                     "limit": {
                         "type": "number",
@@ -1338,7 +1319,7 @@ exports.GENERATED_MCP_TOOLS = [
                 "properties": {
                     "file": {
                         "type": "string",
-                        "description": "Absolute or workspace-relative path of the .shader/.fxh file."
+                        "description": "Workspace-relative path or absolute path inside the workspace/configured game installation."
                     }
                 },
                 "required": [
@@ -1368,7 +1349,7 @@ exports.GENERATED_MCP_TOOLS = [
                     },
                     "file": {
                         "type": "string",
-                        "description": "Absolute or workspace-relative path of a .shader/.fxh file."
+                        "description": "Workspace-relative path or absolute path inside the workspace/configured game installation."
                     }
                 },
                 "required": []

package/dist/host/readiness.js

@@ -14,10 +14,9 @@ exports.LOAD_DEPENDENT_TOOLS = new Set([
     'parse_pdx_fragment',
     'query_scope',
     'get_completion_at',
-    'query_definition',
-    'query_definition_by_name',
+    'go_to_definition',
     'explore_pdx_project',
-    'query_references',
+    'find_references',
     'get_diagnostics',
     'query_scripted_effects',
     'query_scripted_triggers',

package/dist/host/vanillaCache.js

@@ -26,11 +26,10 @@ exports.VANILLA_DEPENDENT_TOOLS = new Set([
     'query_types',
     'get_completion_at',
     'query_scope',
-    'query_definition',
-    'query_definition_by_name',
+    'go_to_definition',
     'explore_pdx_project',
     'query_project_knowledge',
-    'query_references',
+    'find_references',
     'get_diagnostics',
     'query_scripted_effects',
     'query_scripted_triggers',

package/dist/knowledge/diagnosticRouting.js

@@ -48,7 +48,7 @@ function analyzeDiagnosticKnowledge(query) {
         code,
         category: 'general',
         explanation: 'No specialized diagnostic route matched; use LSP and indexed evidence before editing.',
-        suggestedTools: ['get_diagnostics', 'explore_pdx_project', 'query_cwt_schema', 'query_definition_by_name', 'query_workspace_index'],
+        suggestedTools: ['get_diagnostics', 'explore_pdx_project', 'query_cwt_schema', 'go_to_definition', 'query_workspace_index'],
         nextSteps: [
             'Group similar diagnostics and inspect a representative block.',
             'Verify identifiers through indexed tools before making changes.',

package/dist/knowledge/rules.js

@@ -940,12 +940,8 @@ async function readProjectGameId(host) {
     return normalizeGameId(game.id);
 }
 async function readProjectProfileFile(host) {
-    let profilePath = path.join(host.workspaceRoot, '.cwtools', 'project', 'profile.json');
-    let read = await host.filesystem.readTextFile(profilePath).catch(() => ({ exists: false, content: '', hasBom: false }));
-    if (!read.exists) {
-        const legacyPath = path.join(host.workspaceRoot, '.cwtools-ai', 'project', 'profile.json');
-        read = await host.filesystem.readTextFile(legacyPath).catch(() => ({ exists: false, content: '', hasBom: false }));
-    }
+    const profilePath = path.join(host.workspaceRoot, '.cwtools', 'project', 'profile.json');
+    const read = await host.filesystem.readTextFile(profilePath).catch(() => ({ exists: false, content: '', hasBom: false }));
     if (!read.exists)
         return null;
     try {

package/dist/knowledge/workflowHints.js

@@ -23,7 +23,7 @@ function queryWorkflowHints() {
                 id: 'entity-lookup',
                 title: 'Verify game identifiers',
                 triggers: ['identifier', 'reference', 'definition', 'entity'],
-                recommendedTools: ['query_project_knowledge', 'explore_pdx_project', 'query_cwt_schema', 'search_rule_capabilities', 'query_rules', 'query_types', 'query_workspace_index', 'query_definition_by_name'],
+                recommendedTools: ['query_project_knowledge', 'explore_pdx_project', 'query_cwt_schema', 'search_rule_capabilities', 'query_rules', 'query_types', 'query_workspace_index', 'go_to_definition'],
                 guardrails: ['Treat empty text search results as inconclusive without indexed verification.', 'Treat semanticHints as retrieval hints, not legality proof.'],
             },
         ],

package/dist/project/profile.d.ts

@@ -1,18 +1,16 @@
 import type { HostServices } from '../host/hostServices';
 import type { SharedToolResult } from '../tools/schema';
-export type AgentMode = 'build' | 'plan' | 'explore' | 'general' | 'utility' | 'review' | 'gui_expert' | 'script_reviewer' | 'loc_translator' | 'loc_writer' | 'orchestrator' | 'script';
+export type ProjectGuidanceCard = 'implementation' | 'planning' | 'exploration' | 'review' | 'utility' | 'localisation' | 'assets' | 'coordination' | 'paradox_coordination';
 export interface QueryProjectProfileArgs {
-    section?: 'summary' | 'routing' | 'directories' | 'localisation' | 'identifiers' | 'validation' | 'compatibility' | 'promptCards' | 'all';
-    mode?: AgentMode | 'asset';
+    section?: 'summary' | 'routing' | 'directories' | 'localisation' | 'identifiers' | 'validation' | 'compatibility' | 'guidanceCards' | 'all';
+    guidance?: ProjectGuidanceCard;
 }
 export interface ProjectProfile {
-    schemaVersion: 2;
+    schemaVersion: 4;
     generatedAt: string;
     workspaceRoot: string;
     workspaceKind: string;
     projectName: string;
-    /** True when a schemaVersion 1 profile was read and normalized. */
-    legacyProfile?: boolean;
     game: {
         id: string;
         displayName: string;
@@ -46,7 +44,7 @@ export interface ProjectProfile {
     validation: Record<string, unknown>;
     freshness?: Record<string, unknown>;
     warnings?: string[];
-    promptCards: Partial<Record<AgentMode | 'asset', string>>;
+    guidanceCards: Partial<Record<ProjectGuidanceCard, string>>;
     efficiencyHints: string[];
     [key: string]: unknown;
 }
@@ -54,6 +52,6 @@ export declare const PROJECT_PROFILE_RELATIVE_PATH: string;
 export declare function getProjectProfilePath(workspaceRoot: string): string;
 export declare function isProjectProfile(value: unknown): value is ProjectProfile;
 export declare function buildProfileSummary(profile: ProjectProfile): string;
-export declare function getPromptCardForMode(profile: ProjectProfile, mode?: AgentMode | 'asset'): string | undefined;
+export declare function getGuidanceCard(profile: ProjectProfile, guidance?: ProjectGuidanceCard): string | undefined;
 export declare function selectProfileSection(profile: ProjectProfile, section: NonNullable<QueryProjectProfileArgs['section']>): unknown;
 export declare function queryProjectProfileWithHost(host: HostServices, args?: QueryProjectProfileArgs): Promise<SharedToolResult>;

package/dist/project/profile.js

@@ -37,30 +37,18 @@ exports.PROJECT_PROFILE_RELATIVE_PATH = void 0;
 exports.getProjectProfilePath = getProjectProfilePath;
 exports.isProjectProfile = isProjectProfile;
 exports.buildProfileSummary = buildProfileSummary;
-exports.getPromptCardForMode = getPromptCardForMode;
+exports.getGuidanceCard = getGuidanceCard;
 exports.selectProfileSection = selectProfileSection;
 exports.queryProjectProfileWithHost = queryProjectProfileWithHost;
 const path = __importStar(require("path"));
 exports.PROJECT_PROFILE_RELATIVE_PATH = path.join('.cwtools', 'project', 'profile.json');
 function getProjectProfilePath(workspaceRoot) {
-    try {
-        const fs = require('fs');
-        const primary = path.join(workspaceRoot, '.cwtools', 'project', 'profile.json');
-        if (fs.existsSync(primary))
-            return primary;
-        const legacy = path.join(workspaceRoot, '.cwtools-ai', 'project', 'profile.json');
-        if (fs.existsSync(legacy))
-            return legacy;
-        return primary;
-    }
-    catch {
-        return path.join(workspaceRoot, exports.PROJECT_PROFILE_RELATIVE_PATH);
-    }
+    return path.join(workspaceRoot, exports.PROJECT_PROFILE_RELATIVE_PATH);
 }
 function isProjectProfile(value) {
     return !!value
         && typeof value === 'object'
-        && (value.schemaVersion === 1 || value.schemaVersion === 2)
+        && value.schemaVersion === 4
         && typeof value.projectName === 'string';
 }
 function buildProfileSummary(profile) {
@@ -79,16 +67,10 @@ function buildProfileSummary(profile) {
         `Localisation: ${languages} (${profile.localisation.encoding})`,
     ].join('\n');
 }
-function getPromptCardForMode(profile, mode) {
-    if (!mode)
+function getGuidanceCard(profile, guidance) {
+    if (!guidance)
         return undefined;
-    if (mode === 'loc_translator' || mode === 'loc_writer')
-        return profile.promptCards.loc_writer ?? profile.promptCards.build;
-    if (mode === 'gui_expert')
-        return profile.promptCards.asset ?? profile.promptCards.build;
-    if (mode === 'script_reviewer')
-        return profile.promptCards.review;
-    return profile.promptCards[mode] ?? profile.promptCards.build;
+    return profile.guidanceCards[guidance] ?? profile.guidanceCards.implementation;
 }
 function selectProfileSection(profile, section) {
     switch (section) {
@@ -104,7 +86,7 @@ function selectProfileSection(profile, section) {
             vanillaCache: profile.validation?.vanillaCache,
             game: profile.game,
         };
-        case 'promptCards': return profile.promptCards;
+        case 'guidanceCards': return profile.guidanceCards;
         case 'all': return profile;
         case 'summary':
         default:
@@ -148,7 +130,7 @@ async function queryProjectProfileWithHost(host, args = {}) {
                 source: 'cwtools-shared',
                 error: {
                     code: 'invalid_profile',
-                    message: 'Project profile exists but is not a valid schemaVersion 1 or 2 profile.',
+                    message: 'Project profile exists but is not a valid schemaVersion 4 profile.',
                 },
             };
         }
@@ -165,8 +147,8 @@ async function queryProjectProfileWithHost(host, args = {}) {
                 profile: section === 'all' ? parsed : undefined,
                 summary: buildProfileSummary(parsed),
                 data: selectProfileSection(parsed, section),
-                promptCard: getPromptCardForMode(parsed, args.mode),
-                _hint: 'Use section="routing", "localisation", "identifiers", or a mode-specific promptCard for targeted context.',
+                guidanceCard: getGuidanceCard(parsed, args.guidance),
+                _hint: 'Use section="routing", "localisation", "identifiers", or a targeted guidance card for focused context.',
             },
         };
     }

package/dist/safety/paths.js

@@ -76,7 +76,7 @@ function isScratchRelativePath(relativePath) {
         .replace(/\\/g, '/')
         .toLowerCase()
         .split('/');
-    return parts.includes('.cwtools') || parts.includes('.cwtools-ai');
+    return parts.includes('.cwtools');
 }
 function validateLocalisationPath(workspaceRoot, inputPath) {
     const resolution = resolveWorkspacePath(workspaceRoot, inputPath);

package/dist/tools/names.d.ts

@@ -1,6 +1,6 @@
-export declare const MCP_TOOL_NAMES: readonly ["query_types", "query_rules", "query_cwt_schema", "search_rule_capabilities", "explain_scope", "parse_pdx_fragment", "query_scope", "get_diagnostics", "analyze_diagnostic_error", "query_project_profile", "query_project_knowledge", "query_workspace_index", "explore_pdx_project", "query_inline_instantiation", "analyze_pdx_flow", "compare_definition_with_vanilla", "query_localisation_index", "get_pdx_block", "get_completion_at", "document_symbols", "workspace_symbols", "query_definition", "query_definition_by_name", "query_references", "query_scripted_effects", "query_scripted_triggers", "query_enums", "query_static_modifiers", "query_variables", "get_entity_info", "query_shader_symbol", "query_shader_compile_unit", "query_shader_platform_variants", "query_shader_callers", "explain_shader_reachability", "validate_shader", "compare_shader_with_vanilla"];
+export declare const MCP_TOOL_NAMES: readonly ["query_types", "query_rules", "query_cwt_schema", "search_rule_capabilities", "explain_scope", "parse_pdx_fragment", "query_scope", "get_diagnostics", "analyze_diagnostic_error", "query_project_profile", "query_project_knowledge", "query_workspace_index", "explore_pdx_project", "query_inline_instantiation", "analyze_pdx_flow", "compare_definition_with_vanilla", "query_localisation_index", "get_pdx_block", "get_completion_at", "document_symbols", "workspace_symbols", "go_to_definition", "find_references", "query_scripted_effects", "query_scripted_triggers", "query_enums", "query_static_modifiers", "query_variables", "get_entity_info", "query_shader_symbol", "query_shader_compile_unit", "query_shader_platform_variants", "query_shader_callers", "explain_shader_reachability", "validate_shader", "compare_shader_with_vanilla"];
 export type McpToolName = typeof MCP_TOOL_NAMES[number];
 export declare const MCP_WRITE_TOOL_NAMES: readonly [];
-export declare const MCP_READONLY_TOOL_NAMES: readonly ["query_types", "query_rules", "query_cwt_schema", "search_rule_capabilities", "explain_scope", "parse_pdx_fragment", "query_scope", "get_diagnostics", "analyze_diagnostic_error", "query_project_profile", "query_project_knowledge", "query_workspace_index", "explore_pdx_project", "query_inline_instantiation", "analyze_pdx_flow", "compare_definition_with_vanilla", "query_localisation_index", "get_pdx_block", "get_completion_at", "document_symbols", "workspace_symbols", "query_definition", "query_definition_by_name", "query_references", "query_scripted_effects", "query_scripted_triggers", "query_enums", "query_static_modifiers", "query_variables", "get_entity_info", "query_shader_symbol", "query_shader_compile_unit", "query_shader_platform_variants", "query_shader_callers", "explain_shader_reachability", "validate_shader", "compare_shader_with_vanilla"];
+export declare const MCP_READONLY_TOOL_NAMES: readonly ["query_types", "query_rules", "query_cwt_schema", "search_rule_capabilities", "explain_scope", "parse_pdx_fragment", "query_scope", "get_diagnostics", "analyze_diagnostic_error", "query_project_profile", "query_project_knowledge", "query_workspace_index", "explore_pdx_project", "query_inline_instantiation", "analyze_pdx_flow", "compare_definition_with_vanilla", "query_localisation_index", "get_pdx_block", "get_completion_at", "document_symbols", "workspace_symbols", "go_to_definition", "find_references", "query_scripted_effects", "query_scripted_triggers", "query_enums", "query_static_modifiers", "query_variables", "get_entity_info", "query_shader_symbol", "query_shader_compile_unit", "query_shader_platform_variants", "query_shader_callers", "explain_shader_reachability", "validate_shader", "compare_shader_with_vanilla"];
 export declare function isMcpToolName(value: string): value is McpToolName;
 export declare function isMcpWriteToolName(value: string): value is typeof MCP_WRITE_TOOL_NAMES[number];

package/dist/tools/names.js

@@ -25,9 +25,8 @@ exports.MCP_TOOL_NAMES = [
     'get_completion_at',
     'document_symbols',
     'workspace_symbols',
-    'query_definition',
-    'query_definition_by_name',
-    'query_references',
+    'go_to_definition',
+    'find_references',
     'query_scripted_effects',
     'query_scripted_triggers',
     'query_enums',

package/dist/tools/symbols.d.ts

@@ -53,8 +53,10 @@ export declare function queryDefinitionByNameWithHost(host: HostServices, args:
     symbolName: string;
 }): Promise<SharedToolResult>;
 export declare function queryReferencesWithHost(host: HostServices, args: {
-    identifier: string;
+    identifier?: string;
     file?: string;
+    line?: number;
+    column?: number;
     limit?: number;
 }): Promise<SharedToolResult>;
 export declare function inferDocumentSymbolsFromText(content: string): DocumentSymbolInfo[];

package/dist/tools/symbols.js

@@ -205,7 +205,12 @@ async function workspaceSymbolsWithHost(host, args) {
     };
 }
 async function queryDefinitionWithHost(host, args) {
-    const resolution = resolveReadableFile(host, args.file);
+    const file = String(args.file ?? '').trim();
+    if (!file || !Number.isInteger(args.line) || args.line < 0
+        || !Number.isInteger(args.column) || args.column < 0) {
+        return (0, schema_1.toolDenied)('invalid_arguments', 'go_to_definition requires symbolName or a non-negative file position.');
+    }
+    const resolution = resolveReadableFile(host, file);
     if ('error' in resolution)
         return resolution.error;
     const fileUri = toFileUri(resolution.resolvedPath);
@@ -236,7 +241,7 @@ async function queryDefinitionWithHost(host, args) {
 async function queryDefinitionByNameWithHost(host, args) {
     const symbolName = String(args.symbolName ?? '').trim();
     if (!symbolName)
-        return (0, schema_1.toolDenied)('invalid_arguments', 'query_definition_by_name requires symbolName.');
+        return (0, schema_1.toolDenied)('invalid_arguments', 'go_to_definition requires symbolName or a file position.');
     const commandResult = await host.lsp.executeCommand('cwtools.ai.queryDefinitionByName', [symbolName], { timeoutMs: 10000 });
     if (!isUnavailable(commandResult)) {
         return {
@@ -264,9 +269,31 @@ async function queryDefinitionByNameWithHost(host, args) {
 }
 async function queryReferencesWithHost(host, args) {
     const identifier = String(args.identifier ?? '').trim();
-    if (!identifier)
-        return (0, schema_1.toolDenied)('invalid_arguments', 'query_references requires identifier.');
     const limit = clampNumber(args.limit, 50, 1, 200);
+    if (!identifier) {
+        if (!args.file || !Number.isInteger(args.line) || (args.line ?? -1) < 0
+            || !Number.isInteger(args.column) || (args.column ?? -1) < 0) {
+            return (0, schema_1.toolDenied)('invalid_arguments', 'find_references requires identifier or file, line, and column.');
+        }
+        const resolution = resolveReadableFile(host, args.file);
+        if ('error' in resolution)
+            return resolution.error;
+        const requested = await requestLsp(host, 'textDocument/references', {
+            textDocument: { uri: toFileUri(resolution.resolvedPath) },
+            position: { line: args.line, character: args.column },
+            context: { includeDeclaration: true },
+        }, 10000);
+        const references = normalizeLocations(requested.data, host.workspaceRoot).slice(0, limit);
+        return {
+            ok: !requested.unavailable,
+            status: requested.unavailable ? 'unavailable' : 'ready',
+            source: 'cwtools-lsp-references',
+            data: { references, total: references.length },
+            error: requested.unavailable
+                ? { code: 'lsp_unavailable', message: requested.message ?? 'Reference provider is unavailable.' }
+                : undefined,
+        };
+    }
     const definition = await queryDefinitionByNameWithHost(host, { symbolName: identifier });
     const firstMatch = definition.data && typeof definition.data === 'object'
         ? getFirstDefinitionMatch(definition.data)
@@ -502,14 +529,14 @@ function classifyOrigin(filePath, workspaceRoot) {
         return 'external';
     const normalized = filePath.replace(/\\/g, '/').toLowerCase();
     if ((0, paths_1.isPathInsideOrEqual)(workspaceRoot, filePath)) {
-        return normalized.includes('/generated/') || normalized.includes('/.cwtools/') || normalized.includes('/.cwtools-ai/')
+        return normalized.includes('/generated/') || normalized.includes('/.cwtools/')
             ? 'generated'
             : 'workspace';
     }
     if (normalized.includes('/vanilla/') || normalized.includes('/cache/') || normalized.includes('/steamapps/common/')) {
         return 'vanilla';
     }
-    if (normalized.includes('/generated/') || normalized.includes('/.cwtools/') || normalized.includes('/.cwtools-ai/'))
+    if (normalized.includes('/generated/') || normalized.includes('/.cwtools/'))
         return 'generated';
     return 'external';
 }

package/dist/tools/toolHandlers.js

@@ -230,20 +230,20 @@ const defaultSharedToolDispatcher = async (host, name, rawArgs) => {
                 query: String(args.query ?? ''),
                 limit: typeof args.limit === 'number' ? args.limit : undefined,
             });
-        case 'query_definition':
-            return (0, symbols_1.queryDefinitionWithHost)(host, {
-                file: String(args.file ?? ''),
-                line: Number(args.line ?? 0),
-                column: Number(args.column ?? 0),
-            });
-        case 'query_definition_by_name':
-            return (0, symbols_1.queryDefinitionByNameWithHost)(host, {
-                symbolName: String(args.symbolName ?? ''),
-            });
-        case 'query_references':
+        case 'go_to_definition':
+            return typeof args.symbolName === 'string' && args.symbolName.trim()
+                ? (0, symbols_1.queryDefinitionByNameWithHost)(host, { symbolName: args.symbolName })
+                : (0, symbols_1.queryDefinitionWithHost)(host, {
+                    file: String(args.file ?? ''),
+                    line: Number(args.line ?? 0),
+                    column: Number(args.column ?? 0),
+                });
+        case 'find_references':
             return (0, symbols_1.queryReferencesWithHost)(host, {
-                identifier: String(args.identifier ?? ''),
+                identifier: typeof args.identifier === 'string' ? args.identifier : undefined,
                 file: typeof args.file === 'string' ? args.file : undefined,
+                line: typeof args.line === 'number' ? args.line : undefined,
+                column: typeof args.column === 'number' ? args.column : undefined,
                 limit: typeof args.limit === 'number' ? args.limit : undefined,
             });
         case 'query_scope':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cwtools-shared",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Shared protocol and tool contracts for the CWTools MCP server",
   "license": "MIT",
   "repository": {