hoi4-agent-tools 3.5.1 → 3.7.0

package/dist/hoi4_agent_tools/gui/studio.js

@@ -343,14 +343,20 @@ function localisationIconSpriteCandidates(token) {
     const normalized = token.startsWith('GFX_') ? token : `GFX_${token}`;
     return [...new Set([normalized, `${normalized}_texticon`, `${normalized}_text_icon`])];
 }
-export function referencedAssetPatternsForWindow(graph, windowName, additionalSpriteNames = [], languages = ['l_english'], additionalTemplateNames = []) {
+export function referencedAssetPatternsForWindow(graph, windowName, additionalSpriteNames = [], languages = ['l_english'], additionalTemplateNames = [], includeImmediateTooltip = false) {
     const spriteNames = new Set(additionalSpriteNames);
     const fontNames = new Set();
     const textValues = new Set();
+    if (includeImmediateTooltip) {
+        spriteNames.add('ToolTip');
+        fontNames.add('cg_16b');
+    }
     for (const element of selectedElements(graph, windowName, additionalTemplateNames)) {
         collectNamedAttributes(element.attributes, new Set(['spriteType', 'quadTextureSprite']), spriteNames);
         collectNamedAttributes(element.attributes, new Set(['font', 'buttonFont']), fontNames);
         collectNamedAttributes(element.attributes, new Set(['text', 'buttonText', 'context_aware_text']), textValues);
+        if (includeImmediateTooltip)
+            collectNamedAttributes(element.attributes, new Set(['pdx_tooltip']), textValues);
     }
     for (const localisation of graph.localisation) {
         if (textValues.has(localisation.key))
@@ -619,7 +625,7 @@ function assertUniqueScenarioIds(scenarios) {
         seen.add(scenario.id);
     }
 }
-function scenarioMatrixEvidence(graph, scenes) {
+export function scenarioMatrixEvidence(graph, scenes) {
     const primary = scenes[0];
     if (primary === undefined)
         return { offline: true, scenarios: [], changes: [] };
@@ -664,16 +670,23 @@ function scenarioMatrixEvidence(graph, scenes) {
         if (matches.length === 0)
             return [];
         const shown = matches
-            .filter(({ elements }) => elements.some(({ visible }) => visible))
+            .filter(({ elements }) => elements.every(({ visibilityStatus }) => visibilityStatus !== 'unresolved') &&
+            elements.some(({ visibilityStatus }) => visibilityStatus === 'shown'))
             .map(({ scene }) => scene.scenario.id);
         const hidden = matches
-            .filter(({ elements }) => elements.every(({ visible }) => !visible))
+            .filter(({ elements }) => elements.every(({ visibilityStatus }) => visibilityStatus === 'hidden'))
+            .map(({ scene }) => scene.scenario.id);
+        const unresolvedVisibility = matches
+            .filter(({ elements }) => elements.some(({ visibilityStatus }) => visibilityStatus === 'unresolved'))
             .map(({ scene }) => scene.scenario.id);
         const enabled = matches
-            .filter(({ elements }) => elements.some(({ clickable }) => clickable))
+            .filter(({ elements }) => elements.some(({ enablement }) => enablement === 'enabled'))
             .map(({ scene }) => scene.scenario.id);
         const disabled = matches
-            .filter(({ elements }) => elements.every(({ clickable }) => !clickable))
+            .filter(({ elements }) => elements.every(({ enablement }) => enablement === 'disabled'))
+            .map(({ scene }) => scene.scenario.id);
+        const unresolved = matches
+            .filter(({ elements }) => elements.some(({ enablement }) => enablement === 'unresolved'))
             .map(({ scene }) => scene.scenario.id);
         return [
             {
@@ -682,10 +695,24 @@ function scenarioMatrixEvidence(graph, scenes) {
                     ...new Set(matches.flatMap(({ elements }) => elements.map(({ sourcePath }) => sourcePath))),
                 ].sort(compareCodeUnits),
                 ...(visibilityNames.has(name)
-                    ? { visibility: { shown, hidden, covered: shown.length > 0 && hidden.length > 0 } }
+                    ? {
+                        visibility: {
+                            shown,
+                            hidden,
+                            unresolved: unresolvedVisibility,
+                            covered: shown.length > 0 && hidden.length > 0,
+                        },
+                    }
                     : {}),
                 ...(enabledNames.has(name)
-                    ? { enabled: { enabled, disabled, covered: enabled.length > 0 && disabled.length > 0 } }
+                    ? {
+                        enabled: {
+                            enabled,
+                            disabled,
+                            unresolved,
+                            covered: enabled.length > 0 && disabled.length > 0,
+                        },
+                    }
                     : {}),
             },
         ];
@@ -736,13 +763,34 @@ function scenarioMatrixEvidence(graph, scenes) {
             })),
             visibleElements: scene.elements
                 .filter(({ visible }) => visible)
-                .map(({ id, name }) => ({ id, name })),
+                .map(({ id, name, visibilityStatus }) => ({ id, name, visibilityStatus })),
             hiddenElements: scene.elements
                 .filter(({ visible }) => !visible)
-                .map(({ id, name, visibilityReason }) => ({ id, name, reason: visibilityReason })),
+                .map(({ id, name, visibilityReason, visibilityStatus }) => ({
+                id,
+                name,
+                reason: visibilityReason,
+                visibilityStatus,
+            })),
+            unresolvedVisibility: scene.elements
+                .filter(({ visibilityStatus }) => visibilityStatus === 'unresolved')
+                .map(({ id, name, visible, visibilityStatusReason }) => ({
+                id,
+                name,
+                previewVisible: visible,
+                reason: visibilityStatusReason,
+            })),
             disabledElements: scene.elements
-                .filter(({ disabledReason }) => disabledReason !== undefined)
+                .filter(({ disabledReason, enablement }) => disabledReason !== undefined && enablement === 'disabled')
                 .map(({ id, name, disabledReason }) => ({ id, name, reason: disabledReason })),
+            unresolvedClickRegions: scene.elements
+                .filter(({ visible, enablement }) => visible && enablement === 'unresolved')
+                .map(({ id, name, rect, enablementReason }) => ({
+                id,
+                name,
+                rect,
+                reason: enablementReason,
+            })),
         })),
         changes: scenes.slice(1).map((scene) => {
             const currentByKey = new Map(scene.elements.map((element) => [elementKey(element), element]));
@@ -758,13 +806,13 @@ function scenarioMatrixEvidence(graph, scenes) {
             for (const key of keys) {
                 const before = primaryByKey.get(key);
                 const after = currentByKey.get(key);
-                if (before?.visible !== true && after?.visible === true)
+                if (before?.visibilityStatus === 'hidden' && after?.visibilityStatus === 'shown')
                     shown.push(after.name);
-                if (before?.visible === true && after?.visible !== true)
+                if (before?.visibilityStatus === 'shown' && after?.visibilityStatus === 'hidden')
                     hidden.push(before.name);
-                if (before?.clickable === true && after?.clickable === false)
+                if (before?.enablement === 'enabled' && after?.enablement === 'disabled')
                     disabled.push(after.name);
-                if (before?.clickable === false && after?.clickable === true)
+                if (before?.enablement === 'disabled' && after?.enablement === 'enabled')
                     enabled.push(after.name);
                 if (before === undefined || after === undefined)
                     continue;
@@ -924,7 +972,7 @@ export class ScriptedGuiStudio {
         const files = mergeScannedFiles(snapshot.files, localisationFiles);
         return this.graphForFiles(files, `workspace:${workspaceId}`);
     }
-    async scanWindow(workspaceId, windowName, principal, signal, languages = ['l_english'], additionalSpriteNames = [], additionalTemplateNames = [], additionalAssetPatterns = [], additionalLocalisationKeys = []) {
+    async scanWindow(workspaceId, windowName, principal, signal, languages = ['l_english'], additionalSpriteNames = [], additionalTemplateNames = [], additionalAssetPatterns = [], additionalLocalisationKeys = [], includeImmediateTooltip = false) {
         const workspace = this.resolver.get(workspaceId, principal);
         const layoutPatterns = guiLayoutPatterns(workspace);
         const overlayLayouts = await this.engine.scan(workspaceId, {
@@ -955,7 +1003,7 @@ export class ScriptedGuiStudio {
         const definitions = this.graphForFiles(definitionFiles, `definitions:${workspaceId}`, additionalLocalisationKeys);
         assertTargetWindowAvailable(definitions.graph, windowName);
         const referencedPatterns = [
-            ...referencedAssetPatternsForWindow(definitions.graph, windowName, additionalSpriteNames, languages, additionalTemplateNames),
+            ...referencedAssetPatternsForWindow(definitions.graph, windowName, additionalSpriteNames, languages, additionalTemplateNames, includeImmediateTooltip),
             ...additionalAssetPatterns,
         ];
         const exactReferenced = referencedPatterns.length === 0
@@ -1000,7 +1048,7 @@ export class ScriptedGuiStudio {
         const generatedOptions = input.generatedScenarios === undefined
             ? undefined
             : parseGeneratedScenarioOptions(input.generatedScenarios);
-        const scanned = await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [placeholderScenario.language, ...explicitRelatedScenarios.map(({ language }) => language)], scenarioSpriteNames([placeholderScenario, ...explicitRelatedScenarios], generatedOptions?.textSamples), scenarioTemplateNames([placeholderScenario, ...explicitRelatedScenarios]), scenarioCountryFlagPatterns([placeholderScenario, ...explicitRelatedScenarios]), scenarioLocalisationKeys([placeholderScenario, ...explicitRelatedScenarios]));
+        const scanned = await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [placeholderScenario.language, ...explicitRelatedScenarios.map(({ language }) => language)], scenarioSpriteNames([placeholderScenario, ...explicitRelatedScenarios], generatedOptions?.textSamples), scenarioTemplateNames([placeholderScenario, ...explicitRelatedScenarios]), scenarioCountryFlagPatterns([placeholderScenario, ...explicitRelatedScenarios]), scenarioLocalisationKeys([placeholderScenario, ...explicitRelatedScenarios]), [placeholderScenario, ...explicitRelatedScenarios].some(({ tooltip }) => tooltip !== undefined));
         const generatedScenarios = generatedOptions === undefined
             ? []
             : generateGuiPreviewScenarios(scanned.graph, input.windowName, placeholderScenario, generatedOptions, ClausewitzEvaluationDefinitions.build(scanned));
@@ -1030,7 +1078,7 @@ export class ScriptedGuiStudio {
         const budget = new RenderBudget();
         const beforeScenario = parsePreviewScenario(input.before);
         const afterScenario = parsePreviewScenario(input.after);
-        const scanned = await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [beforeScenario.language, afterScenario.language], scenarioSpriteNames([beforeScenario, afterScenario]), scenarioTemplateNames([beforeScenario, afterScenario]), scenarioCountryFlagPatterns([beforeScenario, afterScenario]), scenarioLocalisationKeys([beforeScenario, afterScenario]));
+        const scanned = await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [beforeScenario.language, afterScenario.language], scenarioSpriteNames([beforeScenario, afterScenario]), scenarioTemplateNames([beforeScenario, afterScenario]), scenarioCountryFlagPatterns([beforeScenario, afterScenario]), scenarioLocalisationKeys([beforeScenario, afterScenario]), [beforeScenario, afterScenario].some(({ tooltip }) => tooltip !== undefined));
         const beforeCatalog = new GuiAssetCatalog(scanned.graph, scanned.files, budget, beforeScenario.language);
         const afterCatalog = new GuiAssetCatalog(scanned.graph, scanned.files, budget, afterScenario.language);
         const before = await buildGuiScene(scanned.graph, scanned.files, input.windowName, beforeScenario, beforeCatalog);
@@ -1091,7 +1139,11 @@ export class ScriptedGuiStudio {
             placeholderScenario,
             ...(requestedBaselineScenario === undefined ? [] : [requestedBaselineScenario]),
             ...explicitRelatedScenarios,
-        ]));
+        ]), [
+            placeholderScenario,
+            ...(requestedBaselineScenario === undefined ? [] : [requestedBaselineScenario]),
+            ...explicitRelatedScenarios,
+        ].some(({ tooltip }) => tooltip !== undefined));
         const generatedScenarios = generatedOptions === undefined
             ? []
             : generateGuiPreviewScenarios(scanned.graph, input.windowName, placeholderScenario, generatedOptions, ClausewitzEvaluationDefinitions.build(scanned));
@@ -1438,7 +1490,7 @@ export class ScriptedGuiStudio {
         const previewScenario = input.scenario === undefined ? undefined : parsePreviewScenario(input.scenario);
         const initiallyScanned = input.windowName === undefined
             ? await this.scan(input.workspaceId, input.principal, input.signal)
-            : await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [previewScenario.language], scenarioSpriteNames([previewScenario]), scenarioTemplateNames([previewScenario]), scenarioCountryFlagPatterns([previewScenario]), scenarioLocalisationKeys([previewScenario]));
+            : await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [previewScenario.language], scenarioSpriteNames([previewScenario]), scenarioTemplateNames([previewScenario]), scenarioCountryFlagPatterns([previewScenario]), scenarioLocalisationKeys([previewScenario]), previewScenario.tooltip !== undefined);
         const exactTargets = await this.scanner.scan(workspace, {
             patterns: prepared.map(({ relativePath }) => relativePath),
             ...(input.signal === undefined ? {} : { signal: input.signal }),

package/dist/hoi4_agent_tools/map/service.js

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import fg from 'fast-glob';
+import { escapeFileGlob } from '../core/file-glob.js';
 import { ArtifactStore, boundedSourceHashEvidence, publicArtifactLink, } from '../core/artifacts.js';
 import { canonicalJson, compareCodeUnits, hashCanonical, sha256Bytes } from '../core/canonical.js';
 import { sortDiagnostics } from '../core/diagnostics.js';
@@ -426,7 +426,7 @@ function provinceBitmapPatterns(defaultMaps, mapRoots) {
             const selectedPath = path.posix.normalize(path.posix.join(normalizedRoot, normalizedName));
             if (selectedPath !== normalizedRoot && !selectedPath.startsWith(`${normalizedRoot}/`))
                 continue;
-            patterns.add(fg.posix.escapePath(selectedPath));
+            patterns.add(escapeFileGlob(selectedPath));
         }
     }
     return [...patterns].sort((left, right) => compareCodeUnits(left, right));

package/dist/hoi4_agent_tools/mcp/server/instructions.js

@@ -1,2 +1,2 @@
 /** Shared agent-facing guidance for both MCP protocol generations. */
-export const SERVER_INSTRUCTIONS = 'Use hoi4.reference_context for local wiki and installed documentation citations, hoi4.reference_search and hoi4.reference_read for exact sections, and hoi4.source_lookup for indexed source examples. Use focus tools for focus trees, GUI tools for interfaces, and map tools for map data. Start unfamiliar event chains with hoi4.event_inspect. Event tools are read-only. Start cross-system source review with hoi4.impact_inspect and decision or mission scenarios with hoi4.decision_inspect. Test declared mechanic steps with hoi4.mechanic_test, package connections with hoi4.package_check, and named suites with hoi4.scenario_test. These analysis tools are read-only. Start technology and doctrine work with hoi4.tech_inspect. Technology tools are read-only. Start weighted AI, MTTH, random, and declared-pool analysis with hoi4.probability_inspect. Probability tools are read-only. Concurrent calls queue automatically and emit periodic progress when the client requests it. Long operations support negotiated MCP tasks; native background rewrites require a stable requestKey. Large evidence is linked as resources.';
+export const SERVER_INSTRUCTIONS = 'Start with the matching inspect tool; use hoi4.probability_inspect for weights and timing. Find local documentation with hoi4.reference_context, hoi4.reference_search and hoi4.reference_read, and source definitions with hoi4.source_lookup. Inspection and rendering are read-only; rewrite tools edit mod source. Results describe offline source and scenario models, not observed game behavior. Unresolved states are not confirmed coverage. Read linked artifacts when summaries omit detail. Long operations support negotiated MCP tasks and hoi4.job_inspect/hoi4.job_cancel; background rewrites need a stable requestKey.';

package/dist/hoi4_agent_tools/mcp/tools/reference.js

@@ -1,6 +1,7 @@
 import { errorResult, strictOperationResultSchema } from '../../core/operation-result.js';
 import { ReferenceToolService } from '../../reference/operations.js';
 import { referenceContextRequestSchema, referenceReadRequestSchema, referenceSearchRequestSchema, sourceLookupRequestSchema, referenceContextDataSchema, referenceReadDataSchema, referenceSearchDataSchema, sourceLookupDataSchema, } from '../../schemas/reference.js';
+import { scriptValidateDataSchema, scriptValidateRequestSchema, } from '../../schemas/script-validation.js';
 const readOnly = {
     readOnlyHint: true,
     destructiveHint: false,
@@ -35,11 +36,19 @@ export const referenceTools = [
     {
         name: 'hoi4.source_lookup',
         title: 'Look up HOI4 source symbol',
-        description: 'Find exact Clausewitz definitions, override status, a bounded source block, and indexed usages in the configured game and mod.',
+        description: 'Find exact Clausewitz definitions and usages; navigate nested keyPath blocks or list bounded child structure with view=structure.',
         inputSchema: sourceLookupRequestSchema,
         outputSchema: strictOperationResultSchema(sourceLookupDataSchema),
         annotations: readOnly,
     },
+    {
+        name: 'hoi4.script_validate',
+        title: 'Check HOI4 script commands and scopes',
+        description: 'Check effect or trigger snippet syntax, native command kinds and declared scopes against cited installed documentation. Unknown helpers and native argument blocks remain explicit.',
+        inputSchema: scriptValidateRequestSchema,
+        outputSchema: strictOperationResultSchema(scriptValidateDataSchema),
+        annotations: readOnly,
+    },
 ];
 export function registerReferenceTools(server, engine, context) {
     const service = new ReferenceToolService(engine);

package/dist/hoi4_agent_tools/reference/lines.js

@@ -50,3 +50,15 @@ export function readBoundedLines(lines, firstLine, startLine, startColumn, maxLi
         nextColumn: lineIndex < lines.length ? columnIndex + 1 : null,
     };
 }
+/** Preserve continuation while bounding JSON escaping as well as raw UTF-8 text. */
+export function readBoundedJsonLines(lines, firstLine, startLine, startColumn, maxLines, maxBytes, maxJsonBytes) {
+    let budget = maxBytes;
+    for (;;) {
+        const result = readBoundedLines(lines, firstLine, startLine, startColumn, maxLines, budget);
+        if (Buffer.byteLength(JSON.stringify(result.text), 'utf8') <= maxJsonBytes)
+            return result;
+        budget = Math.max(4, Math.floor(budget / 2));
+        if (budget === 4 && maxJsonBytes < 26)
+            throw new RangeError('JSON text budget cannot retain a source character');
+    }
+}

package/dist/hoi4_agent_tools/reference/operations.js

@@ -4,11 +4,14 @@ import { toolResult } from '../core/operation-result.js';
 import { referenceContextRequestSchema, referenceReadRequestSchema, referenceSearchRequestSchema, sourceLookupRequestSchema, } from '../schemas/reference.js';
 import { ReferenceService } from './service.js';
 import { sourceLookup } from './source-lookup.js';
+import { scriptValidateDataSchema, scriptValidateRequestSchema, } from '../schemas/script-validation.js';
+import { validateScript } from './script-validation.js';
 const schemas = {
     'hoi4.reference_search': referenceSearchRequestSchema,
     'hoi4.reference_read': referenceReadRequestSchema,
     'hoi4.reference_context': referenceContextRequestSchema,
     'hoi4.source_lookup': sourceLookupRequestSchema,
+    'hoi4.script_validate': scriptValidateRequestSchema,
 };
 export function isReferenceTool(name) {
     return Object.hasOwn(schemas, name);
@@ -35,7 +38,47 @@ export class ReferenceToolService {
                 ? await this.references.read(workspace, referenceReadRequestSchema.parse(parsed), signal)
                 : name === 'hoi4.reference_context'
                     ? await this.references.context(workspace, referenceContextRequestSchema.parse(parsed), signal)
-                    : await sourceLookup(this.engine, workspaceId, sourceLookupRequestSchema.parse(parsed), context.principal, signal);
-        return toolResult(emptyServiceResult(workspaceId, data));
+                    : name === 'hoi4.script_validate'
+                        ? await validateScript(this.references, workspace, scriptValidateRequestSchema.parse(parsed), signal)
+                        : await sourceLookup(this.engine, workspaceId, sourceLookupRequestSchema.parse(parsed), context.principal, signal);
+        const result = emptyServiceResult(workspaceId, data);
+        if (name === 'hoi4.script_validate') {
+            const checked = scriptValidateDataSchema.parse(data);
+            result.code = checked.valid === null ? 'SCRIPT_CHECK_PARTIAL' : 'SCRIPT_CHECKED';
+            result.validation = {
+                passed: checked.valid === true,
+                checks: [
+                    {
+                        id: 'script-command-checks',
+                        passed: checked.valid === true,
+                        message: checked.valid === true
+                            ? 'Syntax, native command kinds and declared scopes match the selected documentation'
+                            : checked.valid === false
+                                ? 'Script checks found an error'
+                                : 'Script checks have unresolved coverage',
+                    },
+                ],
+            };
+            result.diagnostics = checked.findings
+                .filter(({ status }) => status !== 'supported')
+                .slice(0, 20)
+                .map((finding) => ({
+                code: finding.code,
+                severity: finding.status === 'error' ? 'error' : 'warning',
+                category: 'validation',
+                message: finding.message,
+                details: {
+                    command: finding.command,
+                    kind: finding.kind,
+                    scope: finding.scope,
+                    line: finding.line,
+                    column: finding.column,
+                },
+            }));
+            while (Buffer.byteLength(JSON.stringify(result.diagnostics), 'utf8') > 4096 &&
+                result.diagnostics.length > 1)
+                result.diagnostics.pop();
+        }
+        return toolResult(result);
     }
 }

package/dist/hoi4_agent_tools/reference/script-validation.js

@@ -0,0 +1,277 @@
+import path from 'node:path';
+import { hashCanonical } from '../core/canonical.js';
+import { ServiceError } from '../core/result.js';
+import { locationFor, parseClausewitz, } from '../core/source/index.js';
+const MAX_COMMANDS = 256;
+const booleanCommands = new Set(['AND', 'OR', 'NOT', 'XOR', 'NAND', 'NOR']);
+const containers = new Set([
+    'and',
+    'or',
+    'not',
+    'xor',
+    'nand',
+    'nor',
+    'hidden_trigger',
+    'hidden_effect',
+]);
+const conditionals = new Set(['if', 'else_if', 'else']);
+const iteratorParameters = new Set([
+    'tooltip',
+    'random_select_amount',
+    'display_individual_scopes',
+    'count',
+]);
+function editDistance(a, b) {
+    let row = Array.from({ length: b.length + 1 }, (_, index) => index);
+    for (let i = 0; i < a.length; i++) {
+        const next = [i + 1];
+        for (let j = 0; j < b.length; j++)
+            next.push(Math.min(next[j] + 1, row[j + 1] + 1, row[j] + Number(a[i] !== b[j])));
+        if (Math.min(...next) > 3)
+            return 4;
+        row = next;
+    }
+    return row[b.length];
+}
+/** Check only rules explicitly available from one selected documentation authority. */
+export async function validateScript(references, workspace, input, signal) {
+    if (Buffer.byteLength(input.source, 'utf8') > 64_000)
+        throw new ServiceError('SCRIPT_SOURCE_TOO_LARGE', 'Snippet exceeds 64000 UTF-8 bytes');
+    const inventory = await references.inventory(workspace, signal, [input.documentation]);
+    const catalogs = { effect: new Map(), trigger: new Map() };
+    const sources = new Map();
+    for (const section of inventory.sections) {
+        const filename = path.basename(section.path).toLowerCase();
+        const match = /^(effects?|triggers?)_(?:documentation|docs)\.(?:md|log)$/u.exec(filename);
+        if (match === null)
+            continue;
+        sources.set(section.path, section.revision);
+        if (!/^[a-z_][a-z0-9_]{0,255}$/u.test(section.heading))
+            continue;
+        const scopeLine = /^\s*(?:\*\s*)?Supported Scopes:\s*(.+?)\s*$/imu.exec(section.lines.join('\n'));
+        if (scopeLine === null || !/^[a-z_,\s]+$/iu.test(scopeLine[1]))
+            continue;
+        const scopes = [
+            ...new Set(scopeLine[1]
+                .toLowerCase()
+                .split(/[,\s]+/u)
+                .filter(Boolean)),
+        ].sort();
+        const kind = match[1].startsWith('effect') ? 'effect' : 'trigger';
+        const previous = catalogs[kind].get(section.heading);
+        const { lines: _lines, ...reference } = section;
+        if (previous !== undefined) {
+            previous.conflict ||= previous.scopes.join(',') !== scopes.join(',');
+        }
+        else
+            catalogs[kind].set(section.heading, { reference, scopes, conflict: false });
+    }
+    const document = parseClausewitz(Buffer.from(input.source, 'utf8'), 'snippet');
+    const findings = [];
+    let visited = 0;
+    let checkedCommands = 0;
+    let argumentBlocksUnchecked = 0;
+    let suggestionBudget = 4000;
+    const bindings = new Map();
+    for (const binding of input.bindings) {
+        if (bindings.has(binding.name))
+            throw new ServiceError('SCRIPT_BINDING_DUPLICATE', 'Scope bindings must have unique names');
+        if (binding.name === 'ROOT' || binding.name === 'THIS' || binding.name === 'PREV')
+            throw new ServiceError('SCRIPT_BINDING_RESERVED', 'ROOT, THIS and PREV follow the supplied scope and traversal stack');
+        bindings.set(binding.name, binding.scope);
+    }
+    const report = (entry, kind, scope, details) => {
+        const position = locationFor('snippet', document.lineIndex, entry.start, entry.end).start;
+        findings.push({
+            ...details,
+            command: entry.key.value.slice(0, 256),
+            kind,
+            scope,
+            line: position.line,
+            column: position.column,
+        });
+    };
+    for (const diagnostic of document.diagnostics)
+        findings.push({
+            code: diagnostic.code,
+            status: 'error',
+            command: '',
+            kind: input.kind,
+            scope: input.scope,
+            line: diagnostic.location?.start.line ?? 1,
+            column: diagnostic.location?.start.column ?? 1,
+            message: diagnostic.message.slice(0, 500),
+            suggestions: [],
+        });
+    const walk = (block, kind, scope, previous) => {
+        for (const entry of block.entries) {
+            signal?.throwIfAborted();
+            if (++visited > MAX_COMMANDS) {
+                return;
+            }
+            if (entry.type !== 'assignment') {
+                const position = locationFor('snippet', document.lineIndex, entry.start, entry.end).start;
+                findings.push({
+                    code: 'SCRIPT_EXPECTED_COMMAND',
+                    status: 'error',
+                    command: '',
+                    kind,
+                    scope,
+                    line: position.line,
+                    column: position.column,
+                    message: 'Expected a command assignment in this effect or trigger body',
+                    suggestions: [],
+                });
+                continue;
+            }
+            const raw = entry.key.value;
+            if (raw.startsWith('@'))
+                continue;
+            const name = booleanCommands.has(raw) ? raw.toLowerCase() : raw;
+            const explicitScope = raw === 'ROOT'
+                ? input.scope
+                : raw === 'THIS'
+                    ? scope
+                    : raw === 'PREV'
+                        ? previous
+                        : bindings.get(raw);
+            const fixedScope = /^[A-Z][A-Z0-9]{2}$/u.test(raw) &&
+                !['ROOT', 'THIS', 'PREV', 'FROM', 'AND', 'NOT', 'XOR', 'NOR'].includes(raw)
+                ? 'country'
+                : /^\d+$/u.test(raw)
+                    ? 'state'
+                    : undefined;
+            if (entry.value.type === 'block' &&
+                (explicitScope !== undefined || fixedScope !== undefined)) {
+                walk(entry.value, kind, explicitScope ?? fixedScope, scope);
+                continue;
+            }
+            const signature = catalogs[kind].get(name);
+            if (signature === undefined) {
+                const other = catalogs[kind === 'effect' ? 'trigger' : 'effect'].get(name);
+                const suggestions = name.length > 128
+                    ? []
+                    : [...catalogs[kind].keys()]
+                        .filter((candidate) => Math.abs(candidate.length - name.length) <= 3)
+                        .filter(() => suggestionBudget-- > 0)
+                        .map((candidate) => ({ candidate, distance: editDistance(name, candidate) }))
+                        .filter(({ distance }) => distance <= 3)
+                        .sort((a, b) => a.distance - b.distance || a.candidate.localeCompare(b.candidate, 'en'))
+                        .slice(0, 3)
+                        .map(({ candidate }) => candidate);
+                report(entry, kind, scope, {
+                    code: other === undefined ? 'SCRIPT_COMMAND_UNRESOLVED' : 'SCRIPT_COMMAND_WRONG_KIND',
+                    status: other === undefined ? 'unresolved' : 'error',
+                    message: other === undefined
+                        ? 'Not documented as a native command in the selected source; inspect scripted helpers or declare the scope binding'
+                        : `Documented as a ${kind === 'effect' ? 'trigger' : 'effect'}, not a ${kind}`,
+                    suggestions,
+                    ...(other === undefined ? {} : { reference: other.reference }),
+                });
+                continue;
+            }
+            checkedCommands++;
+            const wrongScope = !signature.scopes.includes('any') && !signature.scopes.includes(scope);
+            report(entry, kind, scope, {
+                code: signature.conflict
+                    ? 'SCRIPT_DOCUMENTATION_CONFLICT'
+                    : wrongScope
+                        ? 'SCRIPT_COMMAND_WRONG_SCOPE'
+                        : 'SCRIPT_COMMAND_SUPPORTED',
+                status: signature.conflict ? 'unresolved' : wrongScope ? 'error' : 'supported',
+                suggestions: [],
+                reference: signature.reference,
+                message: signature.conflict
+                    ? 'Conflicting supported scopes in the selected documentation'
+                    : wrongScope
+                        ? `Supported scopes: ${signature.scopes.join(', ')}`
+                        : 'Command kind and declared scope match the selected documentation',
+            });
+            const iterator = /^(?:every|random|any|all)_(?:(?:owned|controlled|neighbor)_)?(state|country)$/u.exec(name);
+            if (entry.value.type !== 'block') {
+                if (containers.has(name) || conditionals.has(name) || iterator !== null)
+                    report(entry, kind, scope, {
+                        code: 'SCRIPT_EXPECTED_BLOCK',
+                        status: 'error',
+                        message: 'This control command requires a block',
+                        suggestions: [],
+                        reference: signature.reference,
+                    });
+                continue;
+            }
+            if (containers.has(name)) {
+                walk(entry.value, kind, scope, previous);
+                continue;
+            }
+            if (conditionals.has(name) || iterator !== null) {
+                const childScope = iterator?.[1] ?? scope;
+                for (const child of entry.value.entries) {
+                    if (child.type === 'assignment' && child.key.value === 'limit') {
+                        if (child.value.type === 'block')
+                            walk(child.value, 'trigger', childScope, iterator === null ? previous : scope);
+                        else
+                            report(child, 'trigger', childScope, {
+                                code: 'SCRIPT_EXPECTED_BLOCK',
+                                status: 'error',
+                                message: 'limit requires a trigger block',
+                                suggestions: [],
+                            });
+                    }
+                    else if (iterator !== null &&
+                        child.type === 'assignment' &&
+                        iteratorParameters.has(child.key.value)) {
+                        argumentBlocksUnchecked++;
+                    }
+                    else
+                        walk({ type: 'block', entries: [child], start: child.start, end: child.end }, kind, childScope, iterator === null ? previous : scope);
+                }
+            }
+            else {
+                argumentBlocksUnchecked++;
+                report(entry, kind, scope, {
+                    code: 'SCRIPT_ARGUMENT_BLOCK_UNCHECKED',
+                    status: 'unresolved',
+                    message: 'Native argument block is not validated from prose documentation; read the cited syntax before use',
+                    suggestions: [],
+                    reference: signature.reference,
+                });
+            }
+        }
+    };
+    if (document.diagnostics.every(({ severity }) => severity !== 'error' && severity !== 'blocker'))
+        walk(document.root, input.kind, input.scope);
+    const unresolvedCount = findings.filter(({ status }) => status === 'unresolved').length;
+    const invalid = findings.some(({ status }) => status === 'error');
+    const truncated = visited > MAX_COMMANDS;
+    const incomplete = unresolvedCount > 0 || truncated || inventory.skipped > 0 || catalogs[input.kind].size === 0;
+    const order = { error: 0, unresolved: 1, supported: 2 };
+    findings.sort((a, b) => order[a.status] - order[b.status] ||
+        a.line - b.line ||
+        a.column - b.column ||
+        a.code.localeCompare(b.code, 'en'));
+    const result = {
+        valid: invalid ? false : incomplete ? null : true,
+        checksPerformed: ['syntax', 'command_kind', 'declared_scope'],
+        parametersChecked: false,
+        documentation: {
+            source: input.documentation,
+            revision: hashCanonical([...sources].sort()),
+            effectCount: catalogs.effect.size,
+            triggerCount: catalogs.trigger.size,
+            skippedSources: inventory.skipped,
+        },
+        findings: findings.slice(0, input.limit),
+        totalFindings: findings.length,
+        omittedFindings: Math.max(0, findings.length - input.limit),
+        checkedCommands,
+        unresolvedCount,
+        truncated,
+        argumentBlocksUnchecked,
+    };
+    while (Buffer.byteLength(JSON.stringify(result), 'utf8') > 16_000 && result.findings.length > 1)
+        result.findings.pop();
+    result.omittedFindings = result.totalFindings - result.findings.length;
+    if (Buffer.byteLength(JSON.stringify(result), 'utf8') > 16_000)
+        throw new ServiceError('REFERENCE_RESPONSE_TOO_LARGE', 'Command documentation metadata exceeds the bounded reply');
+    return result;
+}