hoi4-agent-tools 3.5.0 → 3.6.0

package/dist/hoi4_agent_tools/gui/renderer.js

@@ -39,7 +39,10 @@ function bitmapDefinitionId(key, layer = 'face') {
 function sceneGlyphDefinitions(scene) {
     const outlines = new Map();
     const bitmaps = new Map();
-    for (const element of scene.elements) {
+    for (const element of [
+        ...scene.elements,
+        ...(scene.tooltipPreview === undefined ? [] : [scene.tooltipPreview.textElement]),
+    ]) {
         for (const line of element.text?.glyphLines ?? []) {
             for (const glyph of line.glyphs) {
                 if (glyph.kind === 'outline')
@@ -400,6 +403,8 @@ function renderOverlay(element, variant, toolText) {
     if (rect.width <= 0 || rect.height <= 0)
         return '';
     if (variant === 'click-regions') {
+        if (element.enablement === 'unresolved')
+            return `<g><rect ${rectAttributes(rect)} fill="#ffb84d" fill-opacity="0.12" stroke="#ffb84d" stroke-width="2" stroke-dasharray="5 3"/><title>${escapeXml(`Potential click region: ${element.enablementReason ?? element.visibilityStatusReason ?? element.name}`)}</title>${toolText.render(`${element.name} (?)`, { x: rect.x + 3, y: rect.y + 13, fontSize: 11, fill: '#ffb84d' })}</g>`;
         if (!element.clickable)
             return '';
         return `<g><rect ${rectAttributes(rect)} fill="#00d4ff" fill-opacity="0.2" stroke="#00d4ff" stroke-width="2"/>${toolText.render(element.name, { x: rect.x + 3, y: rect.y + 13, fontSize: 11, fill: '#00d4ff' })}</g>`;
@@ -418,6 +423,13 @@ function renderOverlay(element, variant, toolText) {
     }
     return '';
 }
+function renderTooltipPreview(scene, toolText) {
+    const tooltip = scene.tooltipPreview;
+    if (tooltip === undefined)
+        return '';
+    return (renderBaseElement(tooltip.element, undefined, toolText) +
+        renderBaseElement(tooltip.textElement, undefined, toolText));
+}
 function viewFor(scene, variant) {
     if (variant !== 'cropped' || scene.bounds.width <= 0 || scene.bounds.height <= 0) {
         return {
@@ -453,7 +465,7 @@ export function sceneToSvg(scene, variant) {
         : [`<clipPath id="clip-${index}"><rect ${rectAttributes(element.clipRect)}/></clipPath>`]);
     const body = scene.elements
         .map((element, index) => renderBaseElement(element, element.clipRect === undefined ? undefined : `clip-${index}`, toolText))
-        .join('');
+        .join('') + renderTooltipPreview(scene, toolText);
     const overlays = scene.elements
         .map((element) => renderOverlay(element, variant, toolText))
         .join('');
@@ -479,7 +491,7 @@ async function sceneToSvgCooperative(scene, variant, signal) {
     const clipDefinitions = await cooperativeParts(scene.elements, (element, index) => element.clipRect === undefined
         ? ''
         : `<clipPath id="clip-${index}"><rect ${rectAttributes(element.clipRect)}/></clipPath>`, signal);
-    const body = await cooperativeParts(scene.elements, (element, index) => renderBaseElement(element, element.clipRect === undefined ? undefined : `clip-${index}`, toolText), signal);
+    const body = (await cooperativeParts(scene.elements, (element, index) => renderBaseElement(element, element.clipRect === undefined ? undefined : `clip-${index}`, toolText), signal)) + renderTooltipPreview(scene, toolText);
     const overlays = await cooperativeParts(scene.elements, (element) => renderOverlay(element, variant, toolText), signal);
     const fidelity = escapeXml(canonicalJson(scene.fidelity));
     return `<svg xmlns="http://www.w3.org/2000/svg" width="${view.width}" height="${view.height}" viewBox="${finite(view.viewBox.x)} ${finite(view.viewBox.y)} ${finite(view.viewBox.width)} ${finite(view.viewBox.height)}"><metadata data-renderer="hoi4-agent-tools" data-mode="offline">${fidelity}</metadata><defs>${clipDefinitions}${sceneGlyphDefinitions(scene)}${toolText.definitions()}</defs><rect ${rectAttributes(view.viewBox)} fill="#17202a"/>${body}${overlays}</svg>`;
@@ -526,6 +538,27 @@ export function hierarchyToSvg(scene) {
 function sceneLayoutEvidence(scene) {
     return {
         ...scene,
+        ...(scene.tooltipPreview === undefined
+            ? {}
+            : {
+                tooltipPreview: {
+                    targetId: scene.tooltipPreview.targetId,
+                    localisationKey: scene.tooltipPreview.localisationKey,
+                    placement: scene.tooltipPreview.placement,
+                    element: {
+                        id: scene.tooltipPreview.element.id,
+                        rect: scene.tooltipPreview.element.rect,
+                        sprite: scene.tooltipPreview.element.sprite?.spriteName,
+                    },
+                    textElement: {
+                        id: scene.tooltipPreview.textElement.id,
+                        rect: scene.tooltipPreview.textElement.rect,
+                        text: scene.tooltipPreview.textElement.text?.text,
+                        lines: scene.tooltipPreview.textElement.text?.lines,
+                        fontName: scene.tooltipPreview.textElement.text?.fontName,
+                    },
+                },
+            }),
         elements: scene.elements.map((element) => ({
             ...element,
             ...(element.sprite === undefined

package/dist/hoi4_agent_tools/gui/scenario.js

@@ -103,6 +103,24 @@ const GuiPreviewScenarioBodySchema = z
         .min(1)
         .max(128)
         .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/u),
+    tooltip: z
+        .object({
+        target: elementNameSchema,
+        x: z.number().nonnegative(),
+        y: z.number().nonnegative(),
+        width: z.number().positive().max(RENDER_MAX_DIMENSION),
+        padding: z
+            .number()
+            .nonnegative()
+            .max(RENDER_MAX_DIMENSION / 2)
+            .describe('Caller-declared inset on each side, in viewport pixels; no native padding is inferred.'),
+    })
+        .strict()
+        .refine(({ padding, width }) => padding * 2 < width, {
+        path: ['padding'],
+        message: 'Tooltip padding must leave a positive text width.',
+    })
+        .optional(),
     description: z.string().max(500).optional(),
     date: GuiScenarioDateSchema.optional(),
     controls: ConditionControlMapSchema.optional(),

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/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/reference/service.js

@@ -386,35 +386,52 @@ export class ReferenceService {
     async context(workspace, input, signal) {
         const inventory = await this.inventory(workspace, signal);
         const wanted = surfaceNames[input.surface];
-        const selected = [];
+        const ranked = input.question === undefined ? [] : this.rank(inventory.sections, input.question);
+        const required = [];
         const missing = [];
+        const includeRequired = (name, section) => {
+            if (section === undefined) {
+                missing.push(name);
+                return;
+            }
+            const matching = ranked.find((entry) => entry.section.path === section.path && entry.section.source === section.source);
+            required.push({ name, section: matching?.section ?? section });
+        };
         for (const name of [...new Set(wanted)]) {
             const section = inventory.sections.find((entry) => entry.source === 'wiki' && entry.title.toLowerCase() === name.toLowerCase());
-            if (section === undefined)
-                missing.push(name);
-            else
-                selected.push(section);
+            includeRequired(name, section);
         }
         for (const name of gameDocNames[input.surface]) {
             const section = inventory.sections.find((entry) => entry.source === 'game_doc' &&
                 entry.path.replaceAll('\\', '/').toLowerCase().endsWith(`${name}.md`));
-            if (section !== undefined)
-                selected.push(section);
-            else
-                missing.push(name);
+            includeRequired(name, section);
         }
-        const ranked = input.question === undefined ? [] : this.rank(inventory.sections, input.question).slice(0, 5);
+        const questionOrder = new Map(ranked.map(({ section }, index) => [section.id, index]));
+        const byQuestion = (left, right) => (questionOrder.get(left.section.id) ?? Number.MAX_SAFE_INTEGER) -
+            (questionOrder.get(right.section.id) ?? Number.MAX_SAFE_INTEGER);
+        const game = required.filter(({ section }) => section.source === 'game_doc').sort(byQuestion);
+        const wiki = required.filter(({ section }) => section.source === 'wiki').sort(byQuestion);
+        const seen = new Set();
         const prioritized = [
-            ...ranked.map(({ section }) => section),
-            ...selected.filter((section) => !ranked.some((entry) => entry.section.id === section.id)),
-        ];
+            ...[...game.slice(0, 1), ...wiki.slice(0, 1), ...game.slice(1), ...wiki.slice(1)].map(({ section }) => section),
+            ...ranked.slice(0, 5).map(({ section }) => section),
+        ].filter((section) => {
+            if (seen.has(section.id))
+                return false;
+            seen.add(section.id);
+            return true;
+        });
+        const selected = prioritized.slice(0, input.limit);
         return {
             surface: input.surface,
-            sections: prioritized.slice(0, input.limit).map((section) => ({
+            sections: selected.map((section) => ({
                 ...this.publicSection(section),
                 excerpt: ranked.find((entry) => entry.section.id === section.id)?.excerpt ?? section.excerpt,
             })),
             omitted: Math.max(0, prioritized.length - input.limit),
+            omittedSources: required
+                .filter(({ section }) => !selected.some((entry) => entry.path === section.path && entry.source === section.source))
+                .map(({ name }) => name),
             missing,
             coverage: inventory.coverage,
             skipped: inventory.skipped,

package/dist/hoi4_agent_tools/schemas/reference.js

@@ -109,6 +109,7 @@ export const referenceContextDataSchema = z
     surface: referenceSurfaceSchema,
     sections: z.array(referenceSectionSchema).max(24),
     omitted: count,
+    omittedSources: z.array(z.string().max(256)).max(32),
     missing: z.array(z.string().max(256)).max(32),
     coverage: coverageBySource,
     skipped: count,

package/dist/hoi4_agent_tools/version.js

@@ -1,6 +1,6 @@
 import { LATEST_PROTOCOL_VERSION } from '@modelcontextprotocol/sdk/types.js';
 export const PACKAGE_NAME = 'hoi4-agent-tools';
-export const PACKAGE_VERSION = '3.5.0';
+export const PACKAGE_VERSION = '3.6.0';
 export const MCP_PROTOCOL_VERSION = LATEST_PROTOCOL_VERSION;
 export const CONFIG_VERSION = 1;
 export const TRANSACTION_VERSION = 1;

package/docs/README.md

@@ -1,20 +1,35 @@
 # Documentation
 
-- [Setup](setup.md): install the server, configure HOI4 paths, and connect an MCP client.
-- [Local references](reference.md): retrieve cited offline wiki and installed documentation sections and exact source definitions.
-- [Event chains](events.md): inspect, trace, lint, render, and compare event chains.
-- [Cross-system impact and decisions](analysis.md): trace source consumers and evaluate decision or mission scenarios.
-- [Mechanic tests and scenario suites](mechanics.md): interpret declared effect steps, check package links, and run resumable cases.
-- [Technology trees](technology.md): inspect, trace, lint, render, and compare technologies and doctrines.
-- [Visual examples and comparison limits](visual-comparisons.md): real game captures beside MCP renders, with measured findings and limits.
-- [Interface examples and comparison limits](https://github.com/klimPaskov/hoi4-agent-tools/blob/main/docs/gui-comparisons.md): native-size vanilla and Chaos Redux windows, populated templates, scenarios, and provenance.
-- [Bounded helper expansion](helper-expansion.md): resume source-linked event and technology helper paths with exact coverage boundaries.
-- [Persistent jobs](jobs.md): run, inspect, cancel, and recover long operations.
-- [AI and MTTH analysis](probability.md): evaluate weighted logic, timing, uncertainty, sequences, and patches.
-- [Focus trees](focus.md): inspect, create, render, and clean national or continuous focus content.
-- [Scripted GUIs](gui.md): inspect linked UI source, render states, and create or repair GUIs.
-- [Maps](map.md): inspect and edit provinces, states, regions, adjacency, supply, and railways.
-- [HTTP](http.md): run the MCP server for shared or remote access.
-- [Development](development.md): build, test, and contribute.
-
-For vulnerability reporting, see the repository [Security Policy](../SECURITY.md).
+Start with [Setup](setup.md), then try the [Examples](examples.md).
+You can ask your coding agent for these tasks in ordinary language; you do not need to memorize tool names.
+
+## Choose a task
+
+| I want to…                                           | Read                                      |
+| ---------------------------------------------------- | ----------------------------------------- |
+| Find a modding rule or a vanilla example             | [Local references](reference.md)          |
+| Work on a focus tree                                 | [Focus trees](focus.md)                   |
+| Understand an event chain                            | [Events](events.md)                       |
+| Trace dependencies or inspect decisions and missions | [Decisions and dependencies](analysis.md) |
+| Preview a technology or doctrine tree                | [Technology trees](technology.md)         |
+| Build or review an interface                         | [Scripted GUIs](gui.md)                   |
+| Inspect or edit the map                              | [Maps](map.md)                            |
+| Compare weights, chances or timing                   | [AI and probability](probability.md)      |
+| Test a mechanic or check a content package           | [Mechanic tests](mechanics.md)            |
+
+## See the results
+
+- [Examples](examples.md): practical prompts with real renders.
+- [Focus and technology comparisons](visual-comparisons.md): supplied game captures beside source renders.
+- [Interface comparisons](gui-comparisons.md): vanilla and Chaos Redux windows.
+
+## Detailed reference
+
+- [Tool reference](tools.md): tool names and what each one does.
+- [Background jobs](jobs.md): inspect, cancel or retrieve long operations.
+- [Large event and technology queries](helper-expansion.md): follow bounded results without losing coverage.
+- [Remote hosting](http.md): share the server over HTTP.
+- [Development](development.md): build, test and contribute.
+- [Architecture decisions](adr/README.md): implementation rationale for contributors.
+
+For vulnerability reporting, use the [security policy](../SECURITY.md).

package/docs/examples.md

@@ -0,0 +1,85 @@
+# Examples
+
+Start with a task you would normally give your coding agent.
+The agent chooses the MCP tools and opens the resulting images or source references.
+The renders below use actual Chaos Redux and installed HOI4 files; use names from your own mod when trying the prompts.
+
+## Find a rule without reading a whole wiki
+
+> Find the installed documentation for `save_event_target_as`, read the relevant section, and show a vanilla usage. Keep the file and line references.
+
+The reference tools find the section, read a small excerpt, and retain its source revision so the agent can return to it later.
+In the [measured reference example](research/reference-benchmark.md), the search found the installed effect documentation first and a 12-line read supplied the command and supported scopes.
+No wiki download or game launch was needed.
+
+Use [Local references](reference.md) to configure an offline wiki snapshot or narrow a search.
+
+## Check alternative focus prerequisites
+
+> Find Fury's focus tree. Render the branch leading to “The Last Neighbor Has Fallen” and show whether both preceding focuses are required or either one is enough.
+
+![Fury branch with dotted alternative prerequisites](images/comparisons/fury-or-mcp.png)
+
+Dotted connectors mark alternatives within one prerequisite group; solid connectors mark separate required prerequisites.
+The agent can link each finding to the source block before you change the route.
+The [in-game comparison](visual-comparisons.md#focus-trees) shows the same branch and explains the presentation differences.
+
+## Review a large tree
+
+> Render the Utopia Manifesto focus tree. Check its branch connections, alternative prerequisites, missing references and crowded areas before suggesting edits.
+
+[![Utopia Manifesto focus tree](images/comparisons/utopia-mcp.png)](images/comparisons/utopia-mcp.png)
+
+Open the image at full size for the complete layout.
+This example contains 124 focuses in the recorded source version.
+The [focus guide](focus.md) covers inspecting, rendering and reorganizing trees.
+
+## Preview technology layouts and artwork
+
+> Render the infantry technology folder using this mod and its installed game assets. Check card sizes, icons, prerequisite links and missing placements.
+
+[![Infantry technology folder](images/comparisons/infantry-mcp.png)](images/comparisons/infantry-mcp.png)
+
+The preview follows the loaded technology and GUI definitions, including wide equipment cards.
+The [technology comparisons](visual-comparisons.md#technology-folders) also show chemical and biological folders and explain why different source versions can produce different layouts.
+See the [technology guide](technology.md) for grants, bonuses and doctrine paths.
+
+## Inspect an interface before editing it
+
+> Find the Video options window in the installed interface files. Render it with labelled control regions, then check its text, spacing and clipping.
+
+| Supplied in-game capture                                                  | MCP source preview                                                     |
+| ------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| ![Video options in game](images/comparisons/gui/options-video-ingame.png) | ![Video options preview](images/comparisons/gui/options-video-mcp.png) |
+
+For a mod window, ask for the same view at 100% and 125% UI scale and supply the state values needed by its controls.
+Unknown state values must stay unresolved; a visible button alone does not establish that it is enabled in the game.
+The [interface gallery](gui-comparisons.md) includes Škoda Priority, Chaos Redux Settings, Event Log, Chaos Meter, decisions and occupation views.
+
+## Locate map data and plan an edit
+
+> Find Brandenburg by name, show it on the map, and inspect its provinces, neighbours and railway connections. Show the affected files before changing anything.
+
+[![Map rendered from installed source](images/comparisons/source/map-mcp.png)](images/comparisons/source/map-mcp.png)
+
+After reviewing the selection, you can ask for a specific change such as moving named provinces into a state or updating a railway path.
+The map tools check connected records and preserve dated state history when the operation can be represented safely.
+See [Maps](map.md) for supported edits.
+
+## Trace an event or compare AI weights
+
+> Trace this event's options and follow-up events. Point out unresolved calls and link each route to its source.
+
+[![Chaos Redux event options](images/comparisons/source/event-chain-mcp.png)](images/comparisons/source/event-chain-mcp.png)
+
+> Compare this decision's `ai_will_do` score before and after my change in peace and war. List missing conditions separately from known results.
+
+Use [Events](events.md) for route graphs and [AI analysis](probability.md) for supported weights, chances and timing models.
+A decision score is not automatically a percentage chance of an AI click.
+
+## About these examples
+
+The images are source previews, not recordings of the server running the game.
+Supplied game screenshots are identified separately and published with permission.
+The [comparison pages](visual-comparisons.md) and [interface gallery](gui-comparisons.md) keep source details, reproducible inputs and known differences alongside the images.
+The package does not include HOI4 or Chaos Redux source files or artwork.

package/docs/gui.md

@@ -2,6 +2,43 @@
 
 Use `hoi4.gui_inspect`, `hoi4.gui_render`, and `hoi4.gui_rewrite` for `.gui`, `.gfx`, `common/scripted_guis`, localisation, sprites, fonts, and linked decision entry points.
 
+## Start with a preview
+
+> Render this window at 100% and 125% UI scale. Show its control regions and list the state inputs needed to establish visibility and availability.
+
+The [interface examples](gui-comparisons.md) show real vanilla and Chaos Redux windows.
+Cyan click regions have confirmed availability under the supplied scenario.
+Dashed amber regions are potential controls with unresolved visibility or enabling conditions; they do not count as confirmed branch coverage.
+The scene retains the reason so the agent can supply the missing facts instead of guessing.
+These are source-model results, not proof of native click execution.
+
+## Preview immediate tooltip text
+
+An explicit tooltip request uses a visible element's `pdx_tooltip` localisation key:
+
+```json
+{
+  "id": "close-tooltip",
+  "tooltip": {
+    "target": "close_button",
+    "x": 980,
+    "y": 100,
+    "width": 160,
+    "padding": 16
+  }
+}
+```
+
+The target can be an instance ID from inspection or a unique element name.
+Position, width and padding are declared viewport pixels; height follows the measured text.
+The preview uses the loaded `ToolTip` sprite and `cg_16b` font.
+Missing or ambiguous targets, hidden or unresolved visibility, missing text/assets, and bounds errors produce diagnostics without a guessed popup.
+A visibly disabled control can still have tooltip text.
+
+Engine-generated `[!element_action]` and `[!element_action_enabled]` descriptions are not invented.
+If their exact text is known, supply the exact bracketed token as a string key in `scenario.values` or `scenario.scriptedGui`; otherwise the tooltip remains unresolved.
+The preview does not establish native automatic positioning, frame composition, delayed timing or `click_to_front` behavior.
+
 ## Create a GUI
 
 `hoi4.gui_rewrite` can work from supported source, targeted patches, or structured helpers. Source and helper rewrites may include one bounded text package: the main `.gui` plus additional interface `.gui`/`.gfx`, configured GFX `.gfx`, `common/scripted_guis/*.txt`, and localisation `.yml` files. The package is path-checked, parsed, linked, rendered, validated, and applied together in one rewrite. Existing text encodings are retained, while localisation is always written as UTF-8 with BOM.

package/docs/reference.md

@@ -14,7 +14,7 @@ Only Markdown headings and recognizable standalone names in generated `.log` fil
 
 ## Tools
 
-- `hoi4.reference_context`: request a surface such as `event`, `focus`, `technology`, `gui`, or `map`. It returns only the relevant offline wiki and installed documentation citations for that surface. Supply `question` to put the five best matching sections first. `missing` names a selected source absent from the configured roots. Citations are pointers and excerpts; read the pertinent sections before changing code.
+- `hoi4.reference_context`: request a surface such as `event`, `focus`, `technology`, `gui`, or `map`. It reserves citations for available installed documentation and offline wiki sources before adding further question matches. Supply `question` to select the best matching section within each required source. At a limit of two or more, both source kinds are represented when available; a one-result limit prioritizes installed documentation. `omittedSources` names required sources excluded by the result limit, while `missing` names sources absent from the configured roots. Increase the limit or search an omitted source directly before treating the bundle as sufficient. Citations are pointers and excerpts; read the pertinent sections before changing code.
 - `hoi4.reference_search`: search page names, headings, exact script tokens, and matching body lines. The default limit is six results and the maximum is twelve. Filter `sources` to `game_doc`, `wiki`, or `script_doc` when appropriate.
 - `hoi4.reference_read`: provide a search/context result's `id` and `revision`. Read up to 80 lines and 8,000 UTF-8 bytes. Continue with the returned `nextLine`, `nextColumn` as `startColumn`, and the same revision. Long source lines continue without losing characters. A changed source returns `REFERENCE_REVISION_STALE`.
 - `hoi4.source_lookup`: find exact definitions and indexed usages in the installed game and configured mod source. The response includes load order, override status, up to three source blocks bounded to 2,000 bytes each, a scan revision, and explicit reference counts and truncation. Follow `nextLine` and `nextColumn` as `fromLine` and `fromColumn`, with `expectedRevision`, to read more of the active definition.

package/docs/research/reference-benchmark.md

@@ -26,3 +26,17 @@ Revision-bound section IDs stayed stable across unrelated retrieval calls in the
 The retrieval benchmark used the local service directly. A separate real-workspace stdio run identified the built server as 3.5.0 and completed documentation context in 306 ms, a cited section read in 162 ms, and a first exact source lookup in 58,851 ms. That lookup builds the broader game/mod symbol inventory; it should not be confused with the much narrower documentation lookup. MCP transport fixtures cover both protocol adapters, workspace authorization, read-scope denial, and source usage discovery. Individual task adequacy and actual engine behavior remain separate checks.
 
 The four additional public tool definitions add approximately 6.5 KB to the one-time MCP tool discovery response. The complete list is about 72 KB in the discovery fixture and is tested against a 72 KiB ceiling. The context reduction above applies to reference retrieval after discovery.
+
+## Compact context budgets
+
+A 2026-09-27 check of the installed 3.5.0 server found that eight GUI results could contain only wiki sections even though the installed GUI documentation was available. The 3.5.1 source qualifies limits of one, two, and eight citations across the same six work surfaces. All eighteen cases retained installed documentation; limits of two or more also retained wiki citations. Required sources excluded by the limit appeared in `omittedSources`, separately from files absent under `missing`. The nine search queries still found all expected answer-bearing sections.
+
+For the GUI question “Where are scripted GUI click effects and triggers defined?”, the measured results were:
+
+| Citation limit | Returned source kinds            | Required sources omitted | JSON bytes | Milliseconds |
+| -------------- | -------------------------------- | -----------------------: | ---------: | -----------: |
+| 1              | Installed documentation          |                        5 |        877 |          348 |
+| 2              | Installed documentation and wiki |                        4 |      1,480 |          396 |
+| 8              | Installed documentation and wiki |                        0 |      5,926 |          339 |
+
+The default six-surface context bundles used 3,545–5,556 bytes including omission metadata. A smaller response is not sufficient evidence when `omittedSources` is nonempty: increase the limit or search and read those sources directly. The evaluation script fails when a compact budget drops a required source kind or silently omits its required-source pointers.