hoi4-agent-tools 4.0.0 → 4.0.3

package/dist/hoi4_agent_tools/gui/native-state.js

@@ -0,0 +1,244 @@
+import { assignments, parseClausewitz } from '../core/source/index.js';
+/** Windows whose branches the engine selects, keyed by the window's root element name. */
+const NATIVE_BRANCHES = {
+    countrypoliticsview: [
+        {
+            elements: ['no_faction'],
+            shown: (state) => state.faction === 'none',
+            describe: 'the country is not in a faction',
+        },
+        {
+            elements: ['original_in_faction'],
+            shown: (state) => state.faction === 'leader',
+            describe: 'the country leads its faction',
+        },
+        {
+            elements: ['in_faction'],
+            shown: (state) => state.faction === 'member',
+            describe: 'the country is a member of a faction it does not lead',
+        },
+        {
+            elements: ['power_balance_button'],
+            shown: (state) => state.balanceOfPower,
+            describe: 'the country has an active balance of power',
+        },
+    ],
+};
+/**
+ * Icons whose frame the game picks from the ruling ideology, as the ideology group at each
+ * one-based frame. `pol_factions_strip` holds fascism, communism, democratic and neutrality.
+ */
+const IDEOLOGY_FRAME_ICONS = {
+    pol_faction_icon: ['fascism', 'communism', 'democratic', 'neutrality'],
+};
+const DEFAULT_SCENARIO_DATE = '1936.1.1';
+function scenarioDate(scenario) {
+    const parts = (scenario.date ?? DEFAULT_SCENARIO_DATE).split('.').map(Number);
+    return dateKey(parts[0] ?? 1936, parts[1] ?? 1, parts[2] ?? 1);
+}
+function dateKey(year, month, day) {
+    return year * 10_000 + month * 100 + day;
+}
+function scenarioCountryTag(scenario) {
+    const candidate = [
+        scenario.country?.tag,
+        scenario.country?.countryTag,
+        scenario.country?.GetTag,
+    ].find((value) => typeof value === 'string' && /^[A-Za-z0-9_]{2,64}$/u.test(value));
+    return candidate?.toUpperCase();
+}
+function scenarioString(scenario, ...keys) {
+    for (const key of keys) {
+        const value = scenario.country?.[key];
+        if (typeof value === 'string' && /^[A-Za-z0-9_]{2,64}$/u.test(value))
+            return value.toLowerCase();
+    }
+    return undefined;
+}
+function scenarioBoolean(scenario, ...keys) {
+    for (const key of keys) {
+        const value = scenario.country?.[key];
+        if (typeof value === 'boolean')
+            return value;
+        if (typeof value === 'string' && /^(?:yes|true)$/iu.test(value))
+            return true;
+        if (typeof value === 'string' && /^(?:no|false)$/iu.test(value))
+            return false;
+    }
+    return undefined;
+}
+function explicitFaction(scenario) {
+    const named = scenarioString(scenario, 'faction', 'factionRole');
+    if (named === 'none' || named === 'member' || named === 'leader')
+        return named;
+    const leader = scenarioBoolean(scenario, 'factionLeader', 'isFactionLeader');
+    if (leader === true)
+        return 'leader';
+    const member = scenarioBoolean(scenario, 'inFaction', 'isInFaction', 'faction');
+    if (member === false)
+        return 'none';
+    if (member === true)
+        return 'member';
+    return undefined;
+}
+const FACTION_CREATION = new Set(['create_faction', 'create_faction_from_template']);
+function visitHistory(entries, cutoff, facts, members, owner) {
+    for (const entry of entries) {
+        if (entry.type !== 'assignment')
+            continue;
+        const key = entry.key.value;
+        const dated = /^(\d{1,4})\.(\d{1,2})\.(\d{1,2})$/u.exec(key);
+        if (dated !== null) {
+            // A dated block applies from its date; later blocks have not happened yet.
+            if (entry.value.type === 'block' && dateKey(+dated[1], +dated[2], +dated[3]) <= cutoff)
+                visitHistory(entry.value.entries, cutoff, facts, members, owner);
+            continue;
+        }
+        if (key === 'set_politics' && entry.value.type === 'block') {
+            const party = assignments(entry.value, 'ruling_party')[0]?.value;
+            if (party?.type === 'scalar')
+                facts.ideology = party.value.toLowerCase();
+        }
+        else if (FACTION_CREATION.has(key)) {
+            facts.createsFaction = true;
+        }
+        else if (key === 'set_power_balance') {
+            facts.powerBalance = true;
+        }
+        else if (key === 'remove_power_balance') {
+            facts.powerBalance = false;
+        }
+        else if (key === 'add_to_faction' &&
+            entry.value.type === 'scalar' &&
+            entry.value.value.toUpperCase() !== owner) {
+            const tag = entry.value.value.toUpperCase();
+            const joined = members.get(tag) ?? new Set();
+            joined.add(owner);
+            members.set(tag, joined);
+        }
+        else if ((key === 'if' || key === 'else' || key === 'else_if') &&
+            entry.value.type === 'block') {
+            // Conditions such as DLC checks cannot be evaluated here; their content is treated as
+            // part of the start, which matches a fully owned game.
+            visitHistory(entry.value.entries, cutoff, facts, members, owner);
+        }
+    }
+}
+function historyTag(file) {
+    const match = /^history\/countries\/([A-Za-z0-9_]{2,64})(?:\s*-[^/]*)?\.txt$/u.exec(file.relativePath.replaceAll('\\', '/'));
+    return match?.[1]?.toUpperCase();
+}
+function historyState(tag, files, cutoff) {
+    const facts = {
+        createsFaction: false,
+        powerBalance: false,
+    };
+    // `add_to_faction = X` in a leader's history adds X to that leader's faction, so a country
+    // is a member when another country's history adds it.
+    const additions = new Map();
+    let found = false;
+    for (const file of files) {
+        if (file.shadowedBy !== undefined)
+            continue;
+        const fileTag = historyTag(file);
+        if (fileTag === undefined)
+            continue;
+        const owned = fileTag === tag;
+        if (owned)
+            found = true;
+        // Only the country's own history carries its other facts; every other file can matter
+        // solely through the members it adds to a faction.
+        else if (!file.bytes.includes('add_to_faction'))
+            continue;
+        const document = parseClausewitz(file.bytes, file.displayPath);
+        const own = {
+            createsFaction: false,
+            powerBalance: false,
+        };
+        visitHistory(document.root.entries, cutoff, owned ? facts : own, additions, fileTag);
+    }
+    const memberOfFaction = (additions.get(tag)?.size ?? 0) > 0;
+    return { facts, found, memberOfFaction };
+}
+/** Resolve the country facts the engine would use, explicit scenario values first. */
+export function resolveNativeCountryState(scenario, files) {
+    const tag = scenarioCountryTag(scenario);
+    const history = tag === undefined
+        ? undefined
+        : historyState(tag, files.filter(({ relativePath }) => relativePath.startsWith('history/countries/')), scenarioDate(scenario));
+    const knownHistory = history?.found === true ? history : undefined;
+    const ideologyFromScenario = scenarioString(scenario, 'ideology', 'rulingIdeology', 'countryIdeology');
+    const factionFromScenario = explicitFaction(scenario);
+    const bopFromScenario = scenarioBoolean(scenario, 'balanceOfPower', 'hasBalanceOfPower', 'powerBalance');
+    const ideology = ideologyFromScenario ?? knownHistory?.facts.ideology;
+    const faction = factionFromScenario ??
+        (knownHistory === undefined
+            ? 'none'
+            : knownHistory.facts.createsFaction
+                ? 'leader'
+                : knownHistory.memberOfFaction
+                    ? 'member'
+                    : 'none');
+    return {
+        tag,
+        ideology,
+        faction,
+        balanceOfPower: bopFromScenario ?? knownHistory?.facts.powerBalance ?? false,
+        sources: {
+            ideology: ideologyFromScenario !== undefined
+                ? 'scenario'
+                : knownHistory?.facts.ideology !== undefined
+                    ? 'history'
+                    : 'unknown',
+            faction: factionFromScenario !== undefined
+                ? 'scenario'
+                : knownHistory !== undefined
+                    ? 'history'
+                    : 'default',
+            balanceOfPower: bopFromScenario !== undefined
+                ? 'scenario'
+                : knownHistory !== undefined
+                    ? 'history'
+                    : 'default',
+        },
+    };
+}
+/** Whether any native decision can apply to this window, so the country state is worth resolving. */
+export function windowHasNativeState(windowName, elementNames) {
+    return (NATIVE_BRANCHES[windowName] !== undefined ||
+        Object.keys(IDEOLOGY_FRAME_ICONS).some((name) => elementNames.has(name)));
+}
+/** The engine-selected branches and frames for a scene, below any explicit scenario input. */
+export function nativeWindowState(windowName, elementNames, scenario, files) {
+    if (!windowHasNativeState(windowName, elementNames))
+        return undefined;
+    const state = resolveNativeCountryState(scenario, files);
+    const visibility = {};
+    const values = {};
+    const notes = [];
+    const subject = state.tag ?? 'the scenario country';
+    for (const rule of NATIVE_BRANCHES[windowName] ?? []) {
+        const shown = rule.shown(state);
+        for (const name of rule.elements)
+            visibility[name] = shown;
+        notes.push(`${rule.elements.join(', ')} ${shown ? 'is shown' : 'is hidden'} for ${subject}; the game shows it only when ${rule.describe}.`);
+    }
+    for (const [name, order] of Object.entries(IDEOLOGY_FRAME_ICONS)) {
+        if (!elementNames.has(name) || state.ideology === undefined)
+            continue;
+        const index = order.indexOf(state.ideology);
+        if (index < 0)
+            continue;
+        values[`${name}.frame`] = index + 1;
+        notes.push(`${name} shows the ${state.ideology} frame for ${subject}.`);
+    }
+    return { visibility, values, notes, state };
+}
+/** Whether the scenario needs history to resolve its native state, and so to be scanned. */
+export function scenarioNeedsCountryHistory(scenario) {
+    if (scenarioCountryTag(scenario) === undefined)
+        return false;
+    return (scenarioString(scenario, 'ideology', 'rulingIdeology', 'countryIdeology') === undefined ||
+        explicitFaction(scenario) === undefined ||
+        scenarioBoolean(scenario, 'balanceOfPower', 'hasBalanceOfPower', 'powerBalance') === undefined);
+}

package/dist/hoi4_agent_tools/gui/renderer.js

@@ -658,15 +658,20 @@ export async function renderGuiScene(scene, variants = defaultVariants, signal,
         const basePng = await sharp(Buffer.from(full.svg), { limitInputPixels: RENDER_MAX_PIXELS })
             .png({ compressionLevel: 9, adaptiveFiltering: false, palette: false })
             .toBuffer();
-        const rendered = await Promise.all(prepared.map(async (item) => {
-            if (item.variant === 'full')
-                return {
+        // Derived variants are rasterized one at a time: each decodes the full-size base raster, so
+        // running them together multiplies the peak native memory of one render.
+        const rendered = [];
+        for (const item of prepared) {
+            if (item.variant === 'full') {
+                rendered.push({
                     variant: item.variant,
                     svg: item.svg,
                     png: basePng,
                     width: item.view.width,
                     height: item.view.height,
-                };
+                });
+                continue;
+            }
             signal?.throwIfAborted();
             budget.reserveRasterOperation(`gui-derived-variant:${sha256Bytes(item.svg)}`, `GUI ${item.variant} derived rasterization`);
             const png = item.variant === 'cropped'
@@ -684,14 +689,14 @@ export async function renderGuiScene(scene, variants = defaultVariants, signal,
                     .png({ compressionLevel: 9, adaptiveFiltering: false, palette: false })
                     .toBuffer();
             signal?.throwIfAborted();
-            return {
+            rendered.push({
                 variant: item.variant,
                 svg: item.svg,
                 png,
                 width: item.view.width,
                 height: item.view.height,
-            };
-        }));
+            });
+        }
         images = rendered;
     }
     return {

package/dist/hoi4_agent_tools/gui/source-graph.js

@@ -76,6 +76,7 @@ const modelledElementAttributes = new Set([
     'hide',
     'hidden',
     'visible',
+    'show',
     'enabled',
     'context_aware_text',
 ]);
@@ -1063,9 +1064,13 @@ function linkGraph(nodes, edges, elements, sprites, fonts, scriptedGuis, scripte
     for (const font of fonts) {
         const key = font.name.toLocaleLowerCase('en-US');
         const existing = fontByName.get(key);
+        const declared = font.kind === 'bitmapfont';
+        const existingDeclared = existing?.kind === 'bitmapfont';
         if (existing === undefined ||
-            (existing.override && !font.override) ||
-            (existing.languages.length > 0 && font.languages.length === 0))
+            (!existingDeclared && declared) ||
+            (existingDeclared === declared &&
+                ((existing.override && !font.override) ||
+                    (existing.languages.length > 0 && font.languages.length === 0))))
             fontByName.set(key, font);
     }
     const elementByName = new Map();
@@ -1126,7 +1131,7 @@ function linkGraph(nodes, edges, elements, sprites, fonts, scriptedGuis, scripte
             addEdge(edges, 'uses_font', element.id, font?.id ?? `font:${fontName}`, font !== undefined, { fontName }, element.location);
         }
         for (const key of localisationAttributeNames) {
-            const value = element.attributes[key];
+            const value = localisationAttributeValue(element.attributes, key);
             if (typeof value !== 'string' ||
                 value.trim().length === 0 ||
                 !isStaticGuiLocalisationReference(value))
@@ -1206,6 +1211,14 @@ const localisationAttributeNames = [
     'pdx_tooltip_delayed',
     'hint_tag',
 ];
+/** Clausewitz keys are case-insensitive: vanilla spells the button label `buttontext`. */
+function localisationAttributeValue(attributes, name) {
+    const lowered = name.toLowerCase();
+    for (const [key, value] of Object.entries(attributes))
+        if (key.toLowerCase() === lowered)
+            return value;
+    return undefined;
+}
 function isStaticGuiLocalisationReference(value) {
     const trimmed = value.trim();
     return !(trimmed.startsWith('[') && trimmed.endsWith(']'));
@@ -1214,7 +1227,7 @@ function referencedGuiLocalisationKeys(elements, scriptedLocalisation) {
     const keys = new Set(scriptedLocalisation.flatMap(({ localisationKeys }) => localisationKeys));
     for (const element of elements) {
         for (const attribute of localisationAttributeNames) {
-            const value = element.attributes[attribute];
+            const value = localisationAttributeValue(element.attributes, attribute);
             if (typeof value === 'string' &&
                 value.trim().length > 0 &&
                 isStaticGuiLocalisationReference(value))

package/dist/hoi4_agent_tools/gui/studio.js

@@ -17,6 +17,7 @@ import { TRANSACTION_MAX_DIAGNOSTICS } from '../core/transaction-limits.js';
 import { PACKAGE_VERSION } from '../version.js';
 import { isSafeAnimationSourcePath } from './animation-manifest.js';
 import { GuiAssetCatalog, parseBmFont } from './assets.js';
+import { scenarioNeedsCountryHistory } from './native-state.js';
 import { projectGuiGraphForArtifact } from './inspection-artifact.js';
 import { buildGuiScene } from './layout.js';
 import { GUI_VALIDATION_MAX_DIAGNOSTICS } from './limits.js';
@@ -333,7 +334,13 @@ function assertTargetWindowAvailable(graph, windowName) {
         })),
     });
 }
+const lowerCaseKeySets = new WeakMap();
 function collectNamedAttributes(value, keys, output) {
+    let lowered = lowerCaseKeySets.get(keys);
+    if (lowered === undefined) {
+        lowered = new Set([...keys].map((key) => key.toLowerCase()));
+        lowerCaseKeySets.set(keys, lowered);
+    }
     if (Array.isArray(value)) {
         for (const entry of value)
             collectNamedAttributes(entry, keys, output);
@@ -342,7 +349,7 @@ function collectNamedAttributes(value, keys, output) {
     if (typeof value !== 'object' || value === null)
         return;
     for (const [key, entry] of Object.entries(value)) {
-        if (keys.has(key) && typeof entry === 'string')
+        if (lowered.has(key.toLowerCase()) && typeof entry === 'string')
             output.add(entry);
         collectNamedAttributes(entry, keys, output);
     }
@@ -559,6 +566,16 @@ export function scenarioCountryFlagPatterns(scenarios) {
         `gfx/flags/${directory}${tag}_*.{bmp,dds,png,tga}`,
     ]));
 }
+/**
+ * Engine-controlled windows read the scenario country's faction, balance of power and ruling
+ * party from country history; the faction facts also live in other countries' histories.
+ */
+function scenarioCountryHistoryPatterns(scenarios) {
+    return scenarios.some(scenarioNeedsCountryHistory) ? ['history/countries/*.txt'] : [];
+}
+function scenarioCountryAssetPatterns(scenarios) {
+    return [...scenarioCountryFlagPatterns(scenarios), ...scenarioCountryHistoryPatterns(scenarios)];
+}
 function bmFontPagePatterns(files) {
     const references = files.flatMap((file) => {
         if (!file.relativePath.toLowerCase().endsWith('.fnt') || file.shadowedBy !== undefined)
@@ -1072,7 +1089,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]), [placeholderScenario, ...explicitRelatedScenarios].some(({ tooltip }) => tooltip !== undefined));
+        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]), scenarioCountryAssetPatterns([placeholderScenario, ...explicitRelatedScenarios]), scenarioLocalisationKeys([placeholderScenario, ...explicitRelatedScenarios]), [placeholderScenario, ...explicitRelatedScenarios].some(({ tooltip }) => tooltip !== undefined));
         let builtDefinitions;
         const evaluationDefinitions = () => (builtDefinitions ??= ClausewitzEvaluationDefinitions.build(scanned));
         const resolveLocalisation = (target) => resolveScenarioScriptedLocalisation(scanned.graph, input.windowName, target, evaluationDefinitions);
@@ -1106,15 +1123,14 @@ 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]), [beforeScenario, afterScenario].some(({ tooltip }) => tooltip !== undefined));
+        const scanned = await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [beforeScenario.language, afterScenario.language], scenarioSpriteNames([beforeScenario, afterScenario]), scenarioTemplateNames([beforeScenario, afterScenario]), scenarioCountryAssetPatterns([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);
         const after = await buildGuiScene(scanned.graph, scanned.files, input.windowName, afterScenario, afterCatalog);
-        const [beforeRender, afterRender] = await Promise.all([
-            renderGuiScene(before, ['full'], input.signal, budget),
-            renderGuiScene(after, ['full'], input.signal, budget),
-        ]);
+        // One full raster at a time keeps the peak native memory of a comparison to a single render.
+        const beforeRender = await renderGuiScene(before, ['full'], input.signal, budget);
+        const afterRender = await renderGuiScene(after, ['full'], input.signal, budget);
         const comparison = await compareGuiImages(fullImage(beforeRender).png, fullImage(afterRender).png, budget, input.signal);
         const evidenceJson = `${canonicalJson({
             offline: true,
@@ -1159,7 +1175,7 @@ export class ScriptedGuiStudio {
             placeholderScenario,
             ...(requestedBaselineScenario === undefined ? [] : [requestedBaselineScenario]),
             ...explicitRelatedScenarios,
-        ]), scenarioCountryFlagPatterns([
+        ]), scenarioCountryAssetPatterns([
             placeholderScenario,
             ...(requestedBaselineScenario === undefined ? [] : [requestedBaselineScenario]),
             ...explicitRelatedScenarios,
@@ -1316,17 +1332,13 @@ export class ScriptedGuiStudio {
         galleryBudget.reserveRasterOperation(`gui-gallery:${sha256Bytes(scenarioGallerySvg)}`, 'GUI scripted scenario gallery SVG rasterization');
         galleryBudget.reserveRasterOperation(`gui-gallery:${sha256Bytes(stateGallerySvg)}`, 'GUI state gallery SVG rasterization');
         galleryBudget.reserveRasterOperation(`gui-gallery:${sha256Bytes(resolutionGallerySvg)}`, 'GUI resolution gallery SVG rasterization');
-        const [scenarioGalleryPng, stateGalleryPng, resolutionGalleryPng] = await Promise.all([
-            sharp(Buffer.from(scenarioGallerySvg), { limitInputPixels: RENDER_MAX_PIXELS })
-                .png({ compressionLevel: 9, adaptiveFiltering: false, palette: false })
-                .toBuffer(),
-            sharp(Buffer.from(stateGallerySvg), { limitInputPixels: RENDER_MAX_PIXELS })
-                .png({ compressionLevel: 9, adaptiveFiltering: false, palette: false })
-                .toBuffer(),
-            sharp(Buffer.from(resolutionGallerySvg), { limitInputPixels: RENDER_MAX_PIXELS })
-                .png({ compressionLevel: 9, adaptiveFiltering: false, palette: false })
-                .toBuffer(),
-        ]);
+        const rasterizeGallery = (svg) => sharp(Buffer.from(svg), { limitInputPixels: RENDER_MAX_PIXELS })
+            .png({ compressionLevel: 9, adaptiveFiltering: false, palette: false })
+            .toBuffer();
+        // Gallery canvases are large and independent; rasterize them one at a time.
+        const scenarioGalleryPng = await rasterizeGallery(scenarioGallerySvg);
+        const stateGalleryPng = await rasterizeGallery(stateGallerySvg);
+        const resolutionGalleryPng = await rasterizeGallery(resolutionGallerySvg);
         const slug = safeSlug(input.windowName);
         const projectedArtifactGraph = projectGuiGraphForArtifact(scanned.graph, [
             ...new Set([...scenarioScenes, ...stateScenes, ...resolutionScenes, baselineScene].flatMap(({ elements }) => elements.map(({ sourceId }) => sourceId))),
@@ -1522,7 +1534,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]), previewScenario.tooltip !== undefined);
+            : await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [previewScenario.language], scenarioSpriteNames([previewScenario]), scenarioTemplateNames([previewScenario]), scenarioCountryAssetPatterns([previewScenario]), scenarioLocalisationKeys([previewScenario]), previewScenario.tooltip !== undefined);
         const exactTargets = await this.scanner.scan(workspace, {
             patterns: prepared.map(({ relativePath }) => relativePath),
             ...(input.signal === undefined ? {} : { signal: input.signal }),
@@ -1544,7 +1556,7 @@ export class ScriptedGuiStudio {
             let proposedGraph = buildGuiSourceGraph(proposedFiles, this.engine.indexFiles(proposedFiles));
             const proposedAssetPatterns = [
                 ...referencedAssetPatternsForWindow(proposedGraph, input.windowName, [], [scenario.language], scenarioTemplateNames([scenario])),
-                ...scenarioCountryFlagPatterns([scenario]),
+                ...scenarioCountryAssetPatterns([scenario]),
             ];
             const exactProposedAssets = proposedAssetPatterns.length === 0
                 ? []

package/dist/hoi4_agent_tools/mcp/prompts/probability.js

@@ -5,8 +5,8 @@ export const probabilityPromptArguments = z.object({
 });
 export const probabilityPromptDefinition = {
     name: 'hoi4.probability_analysis',
-    title: 'Analyze HOI4 weighted logic',
-    description: 'Plan one source-linked AI, MTTH, random, or declared-pool analysis and return to the owning modding workflow.',
+    title: 'Analyze AI choices and event timing',
+    description: 'Outline an analysis of AI choices, event timing, random chances or a custom weighted pool.',
 };
 /** One prompt body for both protocol generations; it does not run an analysis. */
 export function probabilityPrompt(input) {

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 = '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.';
+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. 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/analysis.js

@@ -112,7 +112,7 @@ const packageInputSchema = z
 const scenarioInputSchema = z
     .object({
     ...scenarioTestRequestSchema.shape,
-    suite: compactValidatedInputSchema(scenarioSuiteSchema, 'Named mechanic, package, or fixed read-only tool cases. See docs/mechanics.md.').optional(),
+    suite: compactValidatedInputSchema(scenarioSuiteSchema, 'Named mechanic, package or inspection cases. See docs/mechanics.md.').optional(),
 })
     .strict()
     .superRefine((input, context) => {
@@ -131,8 +131,8 @@ const readOnlyAnalysisTool = {
 export const analysisTaskTools = [
     {
         name: 'hoi4.impact_inspect',
-        title: 'Inspect cross-system impact',
-        description: 'Trace where symbols are defined and consumed across focuses, events, decisions, ideas, GUI and helpers, or what a changed file affects; proposed sources are analyzed in memory. Example: {"symbols":[{"kind":"scripted_effect","id":"my_effect"}]}. Returns consumer counts inline; the revision-bound graph is a linked resource.',
+        title: 'Find what a script change affects',
+        description: 'Find what a script change affects across focuses, events, decisions, ideas, windows and helpers. Trace definitions and their uses, including proposed source. Example: {"symbols":[{"kind":"scripted_effect","id":"my_effect"}]}. Returns consumer counts inline; the revision-bound graph is a linked resource.',
         inputSchema: impactInspectRequestSchema,
         outputSchema: impactOutputSchema,
         annotations: readOnlyAnalysisTool,
@@ -140,15 +140,15 @@ export const analysisTaskTools = [
     {
         name: 'hoi4.decision_inspect',
         title: 'Inspect decisions and missions',
-        description: 'Inventory decisions and missions, or evaluate one under declared actor and target scenarios: visibility, availability, payment, lifecycle and proposed-source differences. Example: {"mode":"inspect","id":"my_decision","scenarios":[{"id":"base","actor":"GER","state":{}}]}. Returns each scenario outcome inline; full evidence is linked.',
+        description: 'Explain why a decision or mission is hidden, unavailable or unaffordable. Inspect conditions, costs and lifecycle for declared actors and targets, or compare proposed source. Example: {"mode":"inspect","id":"my_decision","scenarios":[{"id":"base","actor":"GER","state":{}}]}. Returns each scenario outcome inline; full evidence is linked.',
         inputSchema: decisionInspectRequestSchema,
         outputSchema: decisionOutputSchema,
         annotations: readOnlyAnalysisTool,
     },
     {
         name: 'hoi4.mechanic_test',
-        title: 'Test declared mechanic steps',
-        description: 'Interpret source-backed effect steps (scripted effect, event option, decision, focus reward) on a declared state and check typed assertions; unsupported effects stay unresolved and no source changes. Example: {"test":{"id":"t","scenario":{"schemaVersion":"1.0","id":"t","state":{"treasury":10}},"steps":[...],"assertions":[...]}}. See docs/mechanics.md.',
+        title: 'Test scripted effects',
+        description: 'Test what an effect, event option, decision or focus reward does to a declared state. Run steps and check assertions; unsupported effects stay unresolved. See docs/mechanics.md. Example: {"test":{"id":"t","scenario":{"schemaVersion":"1.0","id":"t","state":{"treasury":10}},"steps":[...],"assertions":[...]}}.',
         inputSchema: mechanicInputSchema,
         outputSchema: mechanicOutputSchema,
         annotations: readOnlyAnalysisTool,
@@ -156,7 +156,7 @@ export const analysisTaskTools = [
     {
         name: 'hoi4.package_check',
         title: 'Check package connections',
-        description: 'Check a declarative package manifest against active definitions, calls, registrations, localisation, assets and required suite cases. Example: {"manifest":{"schemaVersion":"1.0","id":"my_package","definitions":[{"kind":"scripted_effect","id":"my_effect"}]}}. Returns present, absent, shadowed and unresolved counts inline.',
+        description: 'Find missing pieces of a feature by checking its package manifest against definitions, calls, registrations, localisation, assets and required test cases. Example: {"manifest":{"schemaVersion":"1.0","id":"my_package","definitions":[{"kind":"scripted_effect","id":"my_effect"}]}}. Returns present, absent, shadowed and unresolved counts inline.',
         inputSchema: packageInputSchema,
         outputSchema: packageOutputSchema,
         annotations: readOnlyAnalysisTool,
@@ -164,7 +164,7 @@ export const analysisTaskTools = [
     {
         name: 'hoi4.scenario_test',
         title: 'Run scenario suite',
-        description: 'Run a suite of named mechanic, package or read-only tool cases, inline or from a workspace file, in resumable revision-bound batches. Example: {"suitePath":"tests/my_suite.json","maxCases":20}. Returns completed, failed, unresolved and pending counts, and a continuation while cases remain.',
+        description: 'Run named mechanic, package or inspection cases from a suite or workspace file. Continue unfinished batches and report failures and unresolved cases. Example: {"suitePath":"tests/my_suite.json","maxCases":20}. Returns completed, failed, unresolved and pending counts, and a continuation while cases remain.',
         inputSchema: scenarioInputSchema,
         outputSchema: scenarioOutputSchema,
         annotations: readOnlyAnalysisTool,

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

@@ -169,15 +169,15 @@ export const eventTaskTools = [
     {
         name: 'hoi4.event_inspect',
         title: 'Inspect event chains',
-        description: 'Scan, find roots, trace, explain paths, inspect state flow, lint, assess impact or compare (mode compare) event graphs. Example: {"mode":"trace","selector":"my_mod.1","direction":"downstream"}; a selector is an event ID, a namespace, my_mod.* or a file. Returns counts and the main findings inline; the full source-linked report is a resource.',
+        description: 'Follow event chains and explain their options, conditions, timing and state changes. Find broken calls, inspect affected events or compare revisions with mode compare. Example: {"mode":"trace","selector":"my_mod.1","direction":"downstream"}; a selector is an event ID, a namespace, my_mod.* or a file. Returns counts and the main findings inline; the full source-linked report is a resource.',
         inputSchema: eventInspectInputSchema,
         outputSchema: eventInspectOutputSchema,
         annotations: readOnlyEventTool,
     },
     {
         name: 'hoi4.event_render',
-        title: 'Render event chains',
-        description: 'Render a source-linked event view (overview, neighborhood, options, timing, state, scope, unresolved and more) as JSON, SVG and PNG. Example: {"view":"overview","selector":"my_mod"}. Images are linked artifacts; calls that cannot be resolved statically stay explicit unresolved edges.',
+        title: 'Preview event chains',
+        description: 'Preview event routes, options, timing, state and scope as JSON, SVG and PNG. Example: {"view":"overview","selector":"my_mod"}. Images are linked artifacts; calls that cannot be resolved statically stay explicit unresolved edges.',
         inputSchema: eventRenderInputSchema,
         outputSchema: eventRenderOutputSchema,
         annotations: readOnlyEventTool,

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

@@ -135,23 +135,23 @@ export const focusTaskTools = [
     {
         name: 'hoi4.focus_inspect',
         title: 'Inspect focus trees',
-        description: 'Read national focus trees and continuous-focus palettes: structure, layout, source references and diagnostics. Example: {"treeId":"my_focus_tree"}. Returns counts and the main diagnostics inline; the full report is a linked resource.',
+        description: 'Find focus branches, prerequisites, layout problems and missing references in national trees and continuous-focus palettes. Example: {"treeId":"my_focus_tree"}. Returns counts and the main diagnostics inline; the full report is a linked resource.',
         inputSchema: focusInspectRequestSchema,
         outputSchema: focusInspectOutputSchema,
         annotations: artifactProducing,
     },
     {
         name: 'hoi4.focus_render',
-        title: 'Render a focus tree or continuous palette',
-        description: 'Render a focus tree or palette as a PNG with decoded icons plus HTML, SVG and JSON source maps (png:false for vector only; cropFocusIds adds close-ups). Example: {"relativePath":"common/national_focus/my_tree.txt","treeId":"my_focus_tree"}. Images are linked artifacts, not inline.',
+        title: 'Preview a focus tree or continuous palette',
+        description: 'Preview a focus tree or palette with its icons. Export PNG, HTML, SVG and JSON source maps; png:false skips the PNG and cropFocusIds adds close-ups. Example: {"relativePath":"common/national_focus/my_tree.txt","treeId":"my_focus_tree"}. Images are linked artifacts, not inline.',
         inputSchema: focusRenderRequestSchema,
         outputSchema: focusRenderOutputSchema,
         annotations: artifactProducing,
     },
     {
         name: 'hoi4.focus_rewrite',
-        title: 'Create or clean up focus content',
-        description: 'Create a focus tree or palette from a complete plan (createIfMissing), or re-lay out an existing tree without a plan. Example: {"relativePath":"common/national_focus/my_tree.txt","treeId":"my_focus_tree","layoutMode":"compact"}. Validates, writes atomically and returns the changed files with a rollback-able transaction.',
+        title: 'Build or arrange a focus tree',
+        description: 'Create focus trees and continuous-focus palettes, or rearrange existing branches. Use createIfMissing with a complete plan to create content, or layoutMode to arrange an existing tree. Example: {"relativePath":"common/national_focus/my_tree.txt","treeId":"my_focus_tree","layoutMode":"compact"}. Returns the changed files.',
         inputSchema: focusRewriteRequestSchema,
         outputSchema: focusPlanOutputSchema,
         annotations: {