hoi4-agent-tools 2.8.11 → 3.0.0

package/dist/hoi4_agent_tools/gui/studio.js

@@ -241,7 +241,7 @@ function basenameFallbackPatterns(exactPaths, exactFiles) {
         .map(({ relativePath }) => relativePath.replaceAll('\\', '/').toLowerCase()));
     return [
         ...new Set(exactPaths
-            .filter((candidate) => !resolved.has(candidate.toLowerCase()))
+            .filter((candidate) => !/[*?[\]{}!]/u.test(candidate) && !resolved.has(candidate.toLowerCase()))
             .map((candidate) => `**/${path.posix.basename(candidate)}`)),
     ].sort((left, right) => compareCodeUnits(left, right));
 }
@@ -341,6 +341,22 @@ export function referencedAssetPatternsForWindow(graph, windowName, additionalSp
         if (textValues.has(localisation.key))
             textValues.add(localisation.value);
     }
+    const dynamicTextNames = new Set();
+    for (const value of textValues) {
+        for (const match of value.matchAll(/\[(?:\?[^\]]*\.)?([A-Za-z_][A-Za-z0-9_.:-]*)[^\]]*\]/gu)) {
+            const token = match[1];
+            if (token === undefined)
+                continue;
+            dynamicTextNames.add(token);
+            dynamicTextNames.add(token.slice(token.lastIndexOf('.') + 1));
+        }
+    }
+    const dynamicTextLocalisationKeys = new Set(graph.scriptedLocalisation
+        .filter(({ name }) => dynamicTextNames.has(name))
+        .flatMap(({ localisationKeys }) => localisationKeys));
+    for (const localisation of graph.localisation)
+        if (dynamicTextLocalisationKeys.has(localisation.key))
+            textValues.add(localisation.value);
     for (const value of textValues) {
         for (const token of localisationIconTokens(value)) {
             for (const candidate of localisationIconSpriteCandidates(token))
@@ -372,6 +388,12 @@ export function referencedAssetPatternsForWindow(graph, windowName, additionalSp
         const match = /^\[([^\]]+)\]$/u.exec(image);
         return match?.[1] === undefined ? [] : [match[1]];
     }));
+    const usesCountryFlags = graph.scriptedGuis
+        .filter(({ name }) => relatedScriptedGuiNames.has(name))
+        .flatMap(({ propertyDefinitions }) => propertyDefinitions)
+        .some(({ attributes }) => Object.entries(attributes).some(([key, value]) => key.toLocaleLowerCase('en-US') === 'image' &&
+        typeof value === 'string' &&
+        /(?:^|\.)GetFlag\]$/u.test(value)));
     for (const definition of graph.scriptedLocalisation) {
         if (!dynamicImageTokens.has(definition.name))
             continue;
@@ -417,17 +439,41 @@ export function referencedAssetPatternsForWindow(graph, windowName, additionalSp
             ...manifest.sourceFrames.map(({ path: framePath }) => framePath),
         ]),
     ];
-    return [...new Set(references.flatMap(referenceVariants))].sort((left, right) => compareCodeUnits(left, right));
-}
-function scenarioSpriteNames(scenarios) {
     return [
-        ...new Set(scenarios.flatMap(({ values, scriptedGui }) => Object.entries({ ...scriptedGui, ...values })
-            .filter(([key, value]) => typeof value === 'string' &&
-            value.startsWith('GFX_') &&
-            (key.endsWith('.image') || !key.includes('.')))
-            .map(([, value]) => value))),
+        ...new Set([
+            ...references.flatMap(referenceVariants),
+            ...(usesCountryFlags
+                ? [
+                    'gfx/flags/*.{bmp,dds,png,tga}',
+                    'gfx/flags/medium/*.{bmp,dds,png,tga}',
+                    'gfx/flags/small/*.{bmp,dds,png,tga}',
+                ]
+                : []),
+        ]),
     ].sort((left, right) => compareCodeUnits(left, right));
 }
+function scenarioSpriteNames(scenarios, additionalText = []) {
+    const sprites = new Set();
+    const pending = [...scenarios, ...additionalText];
+    while (pending.length > 0) {
+        const value = pending.pop();
+        if (typeof value === 'string') {
+            if (/^GFX_[A-Za-z0-9_.:+-]+$/u.test(value))
+                sprites.add(value);
+            for (const token of localisationIconTokens(value))
+                for (const candidate of localisationIconSpriteCandidates(token))
+                    sprites.add(candidate);
+            continue;
+        }
+        if (value === null || typeof value !== 'object')
+            continue;
+        if (Array.isArray(value))
+            pending.push(...value);
+        else
+            pending.push(...Object.values(value));
+    }
+    return [...sprites].sort((left, right) => compareCodeUnits(left, right));
+}
 function bmFontPagePatterns(files) {
     const references = files.flatMap((file) => {
         if (!file.relativePath.toLowerCase().endsWith('.fnt') || file.shadowedBy !== undefined)
@@ -570,6 +616,14 @@ function fullImage(render) {
         throw new Error('GUI render did not produce an image.');
     return image;
 }
+function visualSceneKey(scene) {
+    const { id: _id, description: _description, ...scenario } = scene.scenario;
+    return hashCanonical({
+        windowName: scene.windowName,
+        sourceRevision: scene.sourceRevision,
+        scenario,
+    });
+}
 export function guiArtifactProvenance(graph, kind, primaryScene, scenarioScenes = [primaryScene], metadata = {}) {
     const { scenario } = primaryScene;
     const sourceEvidence = boundedSourceHashEvidence(graph.sourceHashes);
@@ -657,7 +711,7 @@ export class ScriptedGuiStudio {
             graph: buildGuiSourceGraph(retainedFiles, this.engine.indexFiles(retainedFiles)),
         };
         this.#graphCache.set(key, scanned);
-        while (this.#graphCache.size > 8) {
+        while (this.#graphCache.size > 1) {
             const oldest = this.#graphCache.keys().next().value;
             if (oldest === undefined)
                 break;
@@ -665,6 +719,10 @@ export class ScriptedGuiStudio {
         }
         return scanned;
     }
+    /** Release parsed GUI graphs after a bounded batch job has finished using the studio. */
+    clearCaches() {
+        this.#graphCache.clear();
+    }
     async scan(workspaceId, principal, signal, languages = ['l_english']) {
         signal?.throwIfAborted();
         const workspace = this.resolver.get(workspaceId, principal);
@@ -746,10 +804,10 @@ export class ScriptedGuiStudio {
         input.signal?.throwIfAborted();
         const placeholderScenario = parsePreviewScenario(input.scenario);
         const explicitRelatedScenarios = (input.relatedScenarios ?? []).map(parsePreviewScenario);
-        const scanned = await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [placeholderScenario.language, ...explicitRelatedScenarios.map(({ language }) => language)], scenarioSpriteNames([placeholderScenario, ...explicitRelatedScenarios]));
         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));
         const generatedScenarios = generatedOptions === undefined
             ? []
             : generateGuiPreviewScenarios(scanned.graph, input.windowName, placeholderScenario, generatedOptions);
@@ -817,6 +875,9 @@ export class ScriptedGuiStudio {
         const requestedBaselineScenario = input.comparisonScenario === undefined
             ? undefined
             : parsePreviewScenario(input.comparisonScenario);
+        const generatedOptions = input.generatedScenarios === undefined
+            ? undefined
+            : parseGeneratedScenarioOptions(input.generatedScenarios);
         const scanned = await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [
             placeholderScenario.language,
             ...(requestedBaselineScenario === undefined ? [] : [requestedBaselineScenario.language]),
@@ -825,10 +886,7 @@ export class ScriptedGuiStudio {
             placeholderScenario,
             ...(requestedBaselineScenario === undefined ? [] : [requestedBaselineScenario]),
             ...explicitRelatedScenarios,
-        ]));
-        const generatedOptions = input.generatedScenarios === undefined
-            ? undefined
-            : parseGeneratedScenarioOptions(input.generatedScenarios);
+        ], generatedOptions?.textSamples));
         const generatedScenarios = generatedOptions === undefined
             ? []
             : generateGuiPreviewScenarios(scanned.graph, input.windowName, placeholderScenario, generatedOptions);
@@ -846,6 +904,18 @@ export class ScriptedGuiStudio {
         const catalog = new GuiAssetCatalog(scanned.graph, scanned.files, budget, scenario.language);
         const scene = await buildGuiScene(scanned.graph, scanned.files, input.windowName, scenario, catalog);
         const render = await renderGuiScene(scene, undefined, input.signal, budget);
+        const fullRenderCache = new Map([
+            [visualSceneKey(scene), fullImage(render)],
+        ]);
+        const renderFull = async (target) => {
+            const key = visualSceneKey(target);
+            const cached = fullRenderCache.get(key);
+            if (cached !== undefined)
+                return cached;
+            const image = fullImage(await renderGuiScene(target, ['full'], input.signal, budget));
+            fullRenderCache.set(key, image);
+            return image;
+        };
         const scenarioScenes = [scene];
         const scenarioItems = [];
         for (const variantScenario of [scenario, ...relatedScenarios]) {
@@ -855,10 +925,7 @@ export class ScriptedGuiStudio {
                 : await buildGuiScene(scanned.graph, scanned.files, input.windowName, variantScenario, catalog);
             if (variantScene !== scene)
                 scenarioScenes.push(variantScene);
-            const variantRender = variantScene === scene
-                ? render
-                : await renderGuiScene(variantScene, ['full'], input.signal, new RenderBudget());
-            const image = fullImage(variantRender);
+            const image = variantScene === scene ? fullImage(render) : await renderFull(variantScene);
             scenarioItems.push({
                 label: variantScenario.description ?? variantScenario.id,
                 png: image.png,
@@ -873,8 +940,7 @@ export class ScriptedGuiStudio {
             const stateScenario = scenarioWith(scenario, { id: `${scenario.id}-${state}`, state });
             const stateScene = await buildGuiScene(scanned.graph, scanned.files, input.windowName, stateScenario, catalog);
             stateScenes.push(stateScene);
-            const stateRender = await renderGuiScene(stateScene, ['full'], input.signal, budget);
-            const image = fullImage(stateRender);
+            const image = await renderFull(stateScene);
             stateItems.push({ label: state, png: image.png, width: image.width, height: image.height });
         }
         const resolutionScenes = [];
@@ -895,8 +961,7 @@ export class ScriptedGuiStudio {
             });
             const resolutionScene = await buildGuiScene(scanned.graph, scanned.files, input.windowName, resolutionScenario, catalog);
             resolutionScenes.push(resolutionScene);
-            const resolutionRender = await renderGuiScene(resolutionScene, ['full'], input.signal, budget);
-            const image = fullImage(resolutionRender);
+            const image = await renderFull(resolutionScene);
             resolutionItems.push({
                 label: `${resolution.width}×${resolution.height} · UI ${uiScale}`,
                 png: image.png,
@@ -905,8 +970,8 @@ export class ScriptedGuiStudio {
             });
         }
         const baselineScene = await buildGuiScene(scanned.graph, scanned.files, input.windowName, baselineScenario, catalog);
-        const baselineRender = await renderGuiScene(baselineScene, ['full'], input.signal, budget);
-        const comparison = await compareGuiImages(fullImage(baselineRender).png, fullImage(render).png, budget, input.signal);
+        const baselineImage = await renderFull(baselineScene);
+        const comparison = await compareGuiImages(baselineImage.png, fullImage(render).png, budget, input.signal);
         const renderedSourceIds = [
             ...scenarioScenes,
             ...stateScenes,

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

@@ -391,7 +391,7 @@ export function registerGuiTools(server, engine, context) {
     });
     server.registerTool('hoi4.gui_render', {
         title: 'Render scripted GUI artifacts',
-        description: 'Render GUI states, resolutions, generated or explicit scenarios, hierarchy, comparisons, and diagnostics.',
+        description: 'Render GUI states, resolutions, generated or explicit scenarios, dynamic flags and text icons, hierarchy, comparisons, and diagnostics.',
         inputSchema: renderInput,
         outputSchema: guiRenderOutputSchema,
         annotations: artifactProducing,

package/dist/hoi4_agent_tools/probability/service.js

@@ -2,7 +2,7 @@ import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { canonicalJson, compareCodeUnits, hashCanonical } from '../core/canonical.js';
 import { ClausewitzEvaluationDefinitions } from '../core/clausewitz-evaluation.js';
-import { probabilityDomainScanPatterns } from '../core/domain-scan-patterns.js';
+import { probabilityDomainScanPatterns, probabilitySharedDefinitionPatterns, } from '../core/domain-scan-patterns.js';
 import { publicArtifactLink } from '../core/artifacts.js';
 import { ServiceError } from '../core/result.js';
 import { PACKAGE_VERSION } from '../version.js';
@@ -649,12 +649,19 @@ export class ProbabilityAnalyzer {
         this.engine = engine;
         this.state = analyzerState(engine);
     }
-    async scan(context, sourcePaths = []) {
+    async scan(context, sourcePaths = [], emptyScope = 'domain') {
         if (context.refresh === true)
             this.engine.invalidate(context.workspaceId);
         const workspace = this.engine.resolver.get(context.workspaceId, context.principal);
+        const selectedSourcePaths = sourcePaths.filter((sourcePath) => sourcePath !== undefined);
         return this.engine.scan(context.workspaceId, {
-            patterns: probabilityDomainScanPatterns(workspace, sourcePaths.filter((sourcePath) => sourcePath !== undefined)),
+            patterns: selectedSourcePaths.length > 0
+                ? probabilityDomainScanPatterns(workspace, selectedSourcePaths)
+                : emptyScope === 'domain'
+                    ? probabilityDomainScanPatterns(workspace)
+                    : emptyScope === 'shared'
+                        ? probabilitySharedDefinitionPatterns()
+                        : [],
         }, context.principal, context.signal);
     }
     async verifyGameVersion(context, adapter) {
@@ -714,6 +721,14 @@ export class ProbabilityAnalyzer {
         return {
             workspaceId: context.workspaceId,
             workspaceIdentity: workspace.workspaceIdentity,
+            ...(typeof extra.sourceScope === 'string'
+                ? {
+                    sourceScope: extra.sourceScope,
+                }
+                : {}),
+            ...(Array.isArray(extra.sourcePaths) && extra.sourcePaths.length > 0
+                ? { sourcePaths: extra.sourcePaths }
+                : {}),
             sourceRevision: snapshot.revision,
             sourceHash: surface.sourceHash,
             scenarioHash,
@@ -840,7 +855,7 @@ export class ProbabilityAnalyzer {
             throw new ServiceError('PROBABILITY_INPUT_AMBIGUOUS', 'Provide either source or customPoolManifest for inspection');
         if (customPoolManifest !== undefined && adapter !== 'custom_weighted_pool')
             throw new ServiceError('PROBABILITY_ADAPTER_MISMATCH', 'customPoolManifest inspection requires adapter custom_weighted_pool');
-        const snapshot = await this.scan(context, [source?.path]);
+        const snapshot = await this.scan(context, [source?.path], source === undefined ? 'none' : source.inlineClausewitz === undefined ? 'domain' : 'shared');
         if (customPoolManifest !== undefined) {
             const surface = customSurface(customPoolManifest, snapshot.revision);
             const gameVersionVerification = await this.verifyGameVersion(context, 'custom_weighted_pool');
@@ -1030,7 +1045,7 @@ export class ProbabilityAnalyzer {
         if (!usingManifest && request.adapter === 'custom_weighted_pool')
             throw new ServiceError('PROBABILITY_MANIFEST_REQUIRED', 'custom_weighted_pool requires customPoolManifest');
         const gameVersionVerification = await this.verifyGameVersion(request, request.adapter);
-        const snapshot = await this.scan(request, [request.source?.path]);
+        const snapshot = await this.scan(request, [request.source?.path], usingManifest ? 'none' : request.source?.inlineClausewitz === undefined ? 'domain' : 'shared');
         const surface = usingManifest
             ? customSurface(request.customPoolManifest, snapshot.revision)
             : discoverWeightedSurface(snapshot, request.adapter, request.source, request.candidatePool ?? []);
@@ -1039,6 +1054,14 @@ export class ProbabilityAnalyzer {
             ? request.customPoolManifest.candidates.map(({ id }) => id)
             : (request.candidatePool ?? []), gameVersionVerification, {
             operation,
+            sourceScope: request.source?.path !== undefined
+                ? 'file'
+                : request.source?.inlineClausewitz !== undefined
+                    ? 'shared'
+                    : request.source !== undefined
+                        ? 'domain'
+                        : 'none',
+            sourcePaths: request.source?.path === undefined ? [] : [request.source.path],
             horizonDays: request.horizonDays,
             requestedMetrics: request.metrics,
             acceptanceBands: request.acceptanceBands,
@@ -1167,7 +1190,7 @@ export class ProbabilityAnalyzer {
     }
     async sequence(request) {
         request.signal?.throwIfAborted();
-        const snapshot = await this.scan(request);
+        const snapshot = await this.scan(request, [], 'none');
         const surface = customSurface(request.customPoolManifest, snapshot.revision);
         const gameVersionVerification = await this.verifyGameVersion(request, 'custom_weighted_pool');
         const metadata = this.metadata(request, snapshot, surface, request.scenarioSet, request.customPoolManifest.candidates.map(({ id }) => id), gameVersionVerification, {
@@ -1334,8 +1357,10 @@ export class ProbabilityAnalyzer {
             return this.store(stale, ['json'], false, request.signal, request.principal);
         }
         await this.verifyGameVersion(request, result.adapter.id);
-        const snapshot = await this.scan(request);
-        if (snapshot.revision !== result.metadata.sourceRevision) {
+        const snapshot = result.metadata.sourceScope === undefined || result.metadata.sourceScope === 'none'
+            ? undefined
+            : await this.scan(request, result.metadata.sourcePaths ?? [], result.metadata.sourceScope === 'shared' ? 'shared' : 'domain');
+        if (snapshot !== undefined && snapshot.revision !== result.metadata.sourceRevision) {
             const stale = {
                 ...result,
                 status: 'stale',

package/dist/hoi4_agent_tools/schemas/probability.js

@@ -737,6 +737,8 @@ const probabilityMetadataSchema = z
     .object({
     workspaceId: z.string(),
     workspaceIdentity: z.string(),
+    sourceScope: z.enum(['file', 'shared', 'domain', 'none']).optional(),
+    sourcePaths: z.array(z.string()).max(100_000).optional(),
     sourceRevision: z.string(),
     sourceHash: z.string(),
     scenarioHash: z.string(),

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 = '2.8.11';
+export const PACKAGE_VERSION = '3.0.0';
 export const MCP_PROTOCOL_VERSION = LATEST_PROTOCOL_VERSION;
 export const CONFIG_VERSION = 1;
 export const TRANSACTION_VERSION = 1;

package/docs/development.md

@@ -35,4 +35,6 @@ npm run test:local
 
 Add `HOI4_DEPENDENCY_ROOTS` as the platform path-delimited list when the external mod has dependencies. Local tests remain read-only.
 
+The installed-game qualification also parses every shipped bitmap-font descriptor, resolves every atlas page, shapes native and enlarged glyphs, verifies deterministic raster output, and checks HOI4 localisation colours across base fonts and language overrides.
+
 See the package [Security Policy](../SECURITY.md) for private vulnerability reporting.

package/docs/gui.md

@@ -31,13 +31,13 @@ Rewrite once, then inspect and render the result.
 
 Inspection checks missing assets and localisation, invalid sizes, overlap, clipping, overflow, button-label centering, content crossing a background boundary, conflicting click regions, invisible blockers, broken parents or contexts, list-row cuts, state conflicts, trigger/effect gaps, and resolution drift. `hoi4.gui_render` returns a scripted-scenario gallery and JSON delta report alongside the generic state and resolution galleries.
 
-The renderer resolves sprites and fonts through the complete mod, dependency, and installed-game load order. Mod windows therefore render ordinary vanilla sprites, tiled vanilla panels, progress bars, masked shields, button frames, and localisation icons such as `£command_power` without copying game assets into the mod. Case differences in GFX and font identifiers do not prevent a valid asset from resolving.
+The renderer resolves sprites and fonts through the complete mod, dependency, and installed-game load order. Mod windows therefore render ordinary vanilla sprites, tiled vanilla panels, progress bars, masked shields, button frames, country flags, and localisation icons such as `£command_power` without copying game assets into the mod. Case differences in GFX and font identifiers do not prevent a valid asset from resolving.
 
 Bitmap text uses the language-appropriate HOI4 font definition and its real glyph atlas. Header, serif, compact, typewriter, black, inverted, and other declared faces keep their own glyph shapes, native metrics, face colour, border colour, language override, and font-specific `textcolors` palette. The renderer reads BMFont channel roles, separates face and outline coverage, and recognizes both vanilla black-on-white masks and conventional white-on-transparent custom masks. HOI4 localisation colour runs such as `§Y` and `§R` therefore colour the glyph face while retaining its sharp antialiasing and declared border instead of flattening the glyph into a blurred monochrome mask or switching to the tool font. The default language uses the base font rather than an unrelated language override, and the renderer recognizes installed-game atlases whose filename omits a page suffix declared by the matching `.fnt` file.
 
 Layout follows Clausewitz orientation and element-origin anchors, including `CENTER_LEFT`, `CENTER_RIGHT`, `CENTER_UP`, `CENTER_DOWN`, `origo`, `centerposition`, inherited container coordinate origins, local scale, and both `%` and `%%` relative dimensions. Text boxes use native font metrics together with `maxWidth`, `maxHeight`, alignment, wrapping, and `fixedsize` clipping. Cornered tile sprites use fixed nine-slice borders and optional center tiling; progress bars composite their filled and background textures; masked shields composite their background and mask textures.
 
-Scripted-GUI composition follows `parent_scripted_gui` chains even when the linked child window is a top-level sibling in the `.gui` file. Literal `always = yes` and `always = no` visibility and click-enabled blocks are applied automatically. A scenario's `values` object supplies concrete runtime values in one place: variable names resolve numeric text, scripted-localisation names resolve dynamic labels, a progress-bar element name sets its fill value, and element keys ending in `.image`, `.frame`, `.x`, `.y`, `.visible`, or `.enabled` update that visual property. Scripted-GUI property expressions such as `image = "[GetMeterSprite]"` or `x = meter_fill_width` consume matching scenario values automatically. Dynamic lists instantiate their declared `entry_container` or `country_scope_entry_container`; each scenario row can select the country template with `countryScope`, choose an explicit `entryContainer`, and provide row-scoped text, image, frame, position, visibility, and enabled values.
+Scripted-GUI composition follows `parent_scripted_gui` chains even when the linked child window is a top-level sibling in the `.gui` file. Literal `always = yes` and `always = no` visibility and click-enabled blocks are applied automatically. A scenario's `values` object supplies concrete runtime values in one place: variable names resolve numeric text, scripted-localisation names resolve dynamic labels, a progress-bar element name sets its fill value, and element keys ending in `.image`, `.frame`, `.x`, `.y`, `.visible`, or `.enabled` update that visual property. Scripted-GUI property expressions such as `image = "[GetMeterSprite]"` or `x = meter_fill_width` consume matching scenario values automatically. Dynamic text is parsed after scenario and scripted-localisation substitution, so a runtime string containing `£command_power` or `£[GetResourceIcon]` renders the resolved inline HOI4 text icon instead of literal marker text. Dynamic lists instantiate their declared `entry_container` or `country_scope_entry_container`; each scenario row can select the country template with `countryScope`, choose an explicit `entryContainer`, provide `countryTag` and `ideology` for `GetFlag`, and supply row-scoped text, image, frame, position, visibility, and enabled values. Masked country sprites use the actual mask and overlay dimensions, so custom flag sizes are discovered from GFX assets rather than assumed by the renderer.
 
 `hoi4.gui_inspect` and `hoi4.gui_render` generate a plausible seeded runtime scenario by default. The generator follows the complete `parent_scripted_gui` surface, discovers numeric and text tokens in GUI localisation and scripted-GUI properties, chooses real scripted-localisation text and sprite candidates, applies simple source thresholds, fills meters within their declared ranges, populates dynamic lists with coherent rows, selects one overlapping tab pane, keeps active and idle controls mutually exclusive, and leaves values explicitly supplied by the caller unchanged. Normal controls and animation frames remain stable unless variation is explicitly requested. Every explicit `relatedScenarios` entry is rendered beside the generated view.
 
@@ -66,11 +66,22 @@ Preview scenarios can include exact layout expectations:
   "values": {
     "threat": 73,
     "GetThreatLabel": "High",
+    "GetCostLine": "Cost £command_power 20",
     "threat_meter": 73,
     "confirm_button.enabled": true
   },
   "flags": { "panel_open": true },
-  "lists": { "target_list": [{ "id": 1, "label": "First target" }] },
+  "lists": {
+    "target_list": [
+      {
+        "id": 1,
+        "label": "France",
+        "countryScope": true,
+        "countryTag": "FRA",
+        "ideology": "democratic"
+      }
+    ]
+  },
   "visibility": { "target_list": true, "confirm_button": true },
   "expectations": {
     "visible": ["target_list", "confirm_button"],

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hoi4-agent-tools",
   "mcpName": "io.github.klimPaskov/hoi4-agent-tools",
-  "version": "2.8.11",
+  "version": "3.0.0",
   "description": "Analyze HOI4 events, tech trees, AI weights, and MTTH; build focus trees, GUIs, and maps.",
   "type": "module",
   "license": "Apache-2.0",
@@ -47,6 +47,7 @@
     "docs/map.md",
     "docs/http.md",
     "docs/development.md",
+    "docs/images/readme/",
     "examples/clients/",
     "examples/probability/",
     "schemas/",
@@ -75,6 +76,7 @@
     "test:local": "tsx scripts/run-local-tests.ts",
     "test:coverage": "vitest run --coverage",
     "benchmark": "node --expose-gc --import tsx scripts/benchmark.ts",
+    "docs:examples": "tsx scripts/generate-readme-examples.ts",
     "fixtures:generate": "npm run fixtures:generate:focus && npm run fixtures:generate:gui && npm run fixtures:generate:map && npm run fixtures:generate:event && npm run fixtures:generate:technology && npm run fixtures:generate:probability",
     "fixtures:generate:focus": "tsx scripts/generate-fixtures.ts",
     "fixtures:generate:gui": "tsx scripts/generate-gui-fixture.ts",

package/schemas/configuration.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.11/schemas/configuration.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.0.0/schemas/configuration.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {
@@ -60,13 +60,13 @@
       "minLength": 1
     },
     "__schema2": {
-      "default": 20000,
+      "default": 100000,
       "type": "integer",
       "minimum": 1,
       "maximum": 1000000
     },
     "__schema3": {
-      "default": 134217728,
+      "default": 268435456,
       "type": "integer",
       "minimum": 1048576,
       "maximum": 9007199254740991

package/schemas/continuous-focus-palette.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.11/schemas/continuous-focus-palette.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.0.0/schemas/continuous-focus-palette.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/custom-weighted-pool.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.11/schemas/custom-weighted-pool.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.0.0/schemas/custom-weighted-pool.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/event-feature-manifest.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.11/schemas/event-feature-manifest.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.0.0/schemas/event-feature-manifest.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/focus-plan.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.11/schemas/focus-plan.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.0.0/schemas/focus-plan.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/focus-planning-sidecar.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.11/schemas/focus-planning-sidecar.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.0.0/schemas/focus-planning-sidecar.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/gui-animation-source.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.11/schemas/gui-animation-source.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.0.0/schemas/gui-animation-source.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/gui-helper.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.11/schemas/gui-helper.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.0.0/schemas/gui-helper.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/gui-scenario.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.11/schemas/gui-scenario.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.0.0/schemas/gui-scenario.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/map-operation.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.11/schemas/map-operation.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.0.0/schemas/map-operation.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "oneOf": [
     {

package/schemas/operation-result.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.8.11/schemas/operation-result.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.0.0/schemas/operation-result.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {