hoi4-agent-tools 2.8.10 → 3.0.0

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';
@@ -11,8 +11,9 @@ import { compareProbabilityResults } from './compare.js';
 import { evaluateExactCandidates, evaluateSurfaceScenarios } from './evaluation.js';
 import { VERIFIED_GAME_CHECKSUM, VERIFIED_GAME_RAW_VERSION, VERIFIED_GAME_VERSION, } from './model.js';
 import { renderProbabilityResult } from './render.js';
-import { analyzeSequence } from './sequence.js';
+import { analyzeSequence, evaluateCustomPoolPoint } from './sequence.js';
 import { simulateSurface } from './simulation.js';
+import { Rational } from './rational.js';
 import { discoverWeightedSurface, inventoryWeightedSurfaces, } from './source-analysis.js';
 import { sweepSurface } from './sweep.js';
 const states = new WeakMap();
@@ -584,6 +585,63 @@ function customSurface(manifest, sourceRevision) {
         unsupported: [],
     };
 }
+function customPoolScenarios(surface, manifest, scenarioSet) {
+    return scenarioSet.scenarios.map((scenario) => {
+        const point = evaluateCustomPoolPoint(manifest, scenario);
+        const ordered = [...point.candidates].sort((left, right) => right.probability - left.probability || compareCodeUnits(left.id, right.id));
+        const rank = new Map(ordered.map((candidate, index) => [candidate.id, index + 1]));
+        const candidates = point.candidates.map((candidate) => {
+            const exactWeight = Rational.parse(candidate.weight);
+            const exactPoolTotal = Rational.parse(point.poolTotal);
+            const exactProbability = !candidate.eligible
+                ? Rational.zero
+                : manifest.selection.mode === 'categorical_weighted'
+                    ? exactWeight !== undefined && exactPoolTotal !== undefined && !exactPoolTotal.isZero()
+                        ? exactWeight.divide(exactPoolTotal)
+                        : undefined
+                    : exactWeight?.divide(new Rational(100n)).max(Rational.zero).min(Rational.one);
+            const unresolved = point.unresolved.filter(({ candidateId }) => candidateId === undefined || candidateId === candidate.id);
+            return {
+                id: candidate.id,
+                eligibility: candidate.eligible ? 'true' : 'false',
+                supportLevel: unresolved.length === 0 ? 'exact' : 'unsupported',
+                rawValue: exactWeight?.toJSON() ?? null,
+                conditionalProbability: candidate.probability,
+                ...(exactProbability === undefined
+                    ? {}
+                    : { exactConditionalProbability: exactProbability.toJSON() }),
+                rank: candidate.eligible ? (rank.get(candidate.id) ?? null) : null,
+                trace: [],
+                provenance: surface.candidates.find(({ id }) => id === candidate.id)?.provenance ?? [],
+                unresolved,
+            };
+        });
+        const eligible = ordered.filter(({ eligible }) => eligible);
+        return {
+            id: scenario.id,
+            ...(scenario.label === undefined ? {} : { label: scenario.label }),
+            ...(scenario.prevalence === undefined ? {} : { prevalence: scenario.prevalence }),
+            poolComplete: true,
+            supportLevel: point.unresolved.length === 0 ? 'exact' : 'unsupported',
+            candidates,
+            ...(Rational.parse(point.poolTotal) === undefined
+                ? {}
+                : { poolTotal: Rational.parse(point.poolTotal).toJSON() }),
+            summary: {
+                topOutcomes: eligible.slice(0, 3).map(({ id }) => id),
+                bottomEligibleOutcomes: eligible.slice(-3).map(({ id }) => id),
+                impossibleOutcomes: ordered
+                    .filter(({ probability }) => probability === 0)
+                    .map(({ id }) => id),
+                unresolvedOutcomes: candidates
+                    .filter(({ unresolved }) => unresolved.length > 0)
+                    .map(({ id }) => id),
+                dominantFactors: [],
+            },
+            unresolved: point.unresolved,
+        };
+    });
+}
 export class ProbabilityAnalyzer {
     engine;
     state;
@@ -591,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) {
@@ -656,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,
@@ -775,13 +848,61 @@ export class ProbabilityAnalyzer {
         }
         return complete;
     }
-    async inspect(context, adapter, source, candidatePool = []) {
-        if (source === undefined)
+    async inspect(context, adapter, source, candidatePool = [], customPoolManifest) {
+        if (source === undefined && customPoolManifest === undefined)
             return { adapters: probabilityAdapters(), artifacts: [], filesScanned: [] };
-        const snapshot = await this.scan(context, [source.path]);
+        if (customPoolManifest !== undefined && source !== undefined)
+            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], 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');
+            const report = {
+                schemaVersion: 'probability-inspection.v2',
+                workspaceId: context.workspaceId,
+                surface: {
+                    id: surface.id,
+                    adapter: surface.adapter,
+                    poolComplete: true,
+                    sourceRevision: surface.sourceRevision,
+                    sourceHash: surface.sourceHash,
+                    gameVersionVerification,
+                    candidateCount: surface.candidates.length,
+                    candidates: surface.candidates.map((candidate) => ({
+                        id: candidate.id,
+                        sourceKind: candidate.sourceKind,
+                        provenance: candidate.provenance,
+                        hasEligibility: customPoolManifest.candidates.find(({ id }) => id === candidate.id)?.eligibleWhen !==
+                            undefined,
+                        hasWeightBlock: true,
+                        requiredInputs: [],
+                        referencedProvenance: [],
+                        analysisSupport: 'exact',
+                    })),
+                    requiredInputs: [],
+                    unsupported: [],
+                },
+            };
+            const workspace = this.engine.resolver.get(context.workspaceId, context.principal);
+            const artifact = await this.engine.artifacts.putChunked(workspace, `probability-inspect-${surface.sourceHash.slice(0, 12)}.json`, 'application/json', `${canonicalJson(report)}\n`, {
+                kind: 'probability-inspection',
+                toolVersion: PACKAGE_VERSION,
+                schemaVersion: 'probability-inspection.v2',
+                sourceHashes: { aggregate: surface.sourceHash },
+            }, 'Declared custom weighted-pool inventory', context.signal);
+            return {
+                adapters: probabilityAdapters(),
+                surface: report.surface,
+                artifacts: [publicArtifactLink(artifact)],
+                filesScanned: [],
+            };
+        }
+        const selectedSource = source;
         const storeDiscovery = async (inventory, reason) => {
             const availableAdapters = inventory.adapters.filter(({ candidateCount }) => candidateCount > 0);
-            const matchingIdentifier = availableAdapters.filter(({ identifierMatchCount }) => source.identifier !== undefined && identifierMatchCount > 0);
+            const matchingIdentifier = availableAdapters.filter(({ identifierMatchCount }) => selectedSource.identifier !== undefined && identifierMatchCount > 0);
             const matchingPool = availableAdapters.filter(({ candidatePoolMatchCount }) => candidatePool.length > 0 && candidatePoolMatchCount > 0);
             const requested = availableAdapters.find(({ adapterId }) => adapterId === adapter);
             const ranked = [
@@ -826,7 +947,7 @@ export class ProbabilityAnalyzer {
             };
         };
         if (adapter === undefined) {
-            const inventory = inventoryWeightedSurfaces(snapshot, source, candidatePool);
+            const inventory = inventoryWeightedSurfaces(snapshot, selectedSource, candidatePool);
             return storeDiscovery(inventory, inventory.adapters.some(({ candidateCount }) => candidateCount > 0)
                 ? 'source_inventory'
                 : 'no_weighted_surfaces');
@@ -834,14 +955,14 @@ export class ProbabilityAnalyzer {
         const gameVersionVerification = await this.verifyGameVersion(context, adapter);
         let surface;
         try {
-            surface = discoverWeightedSurface(snapshot, adapter, source, candidatePool);
+            surface = discoverWeightedSurface(snapshot, adapter, selectedSource, candidatePool);
         }
         catch (error) {
             if (!(error instanceof ServiceError) ||
                 (error.code !== 'PROBABILITY_SURFACE_EMPTY' &&
                     error.code !== 'PROBABILITY_IDENTIFIER_NOT_FOUND'))
                 throw error;
-            const inventory = inventoryWeightedSurfaces(snapshot, source, candidatePool);
+            const inventory = inventoryWeightedSurfaces(snapshot, selectedSource, candidatePool);
             const requested = inventory.adapters.find(({ adapterId }) => adapterId === adapter);
             const reason = error.code === 'PROBABILITY_IDENTIFIER_NOT_FOUND'
                 ? 'identifier_not_found'
@@ -916,12 +1037,31 @@ export class ProbabilityAnalyzer {
         if (request.scenarioSet.workspaceId !== undefined &&
             request.scenarioSet.workspaceId !== request.workspaceId)
             throw new ServiceError('PROBABILITY_SCENARIO_WORKSPACE_MISMATCH', 'Scenario set belongs to a different workspace');
+        const usingManifest = request.customPoolManifest !== undefined;
+        if (usingManifest !== (request.source === undefined))
+            throw new ServiceError('PROBABILITY_INPUT_AMBIGUOUS', 'Provide exactly one source or customPoolManifest');
+        if (usingManifest && request.adapter !== 'custom_weighted_pool')
+            throw new ServiceError('PROBABILITY_ADAPTER_MISMATCH', 'customPoolManifest requires the custom_weighted_pool adapter');
+        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 surface = discoverWeightedSurface(snapshot, request.adapter, request.source, request.candidatePool ?? []);
+        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 ?? []);
         const definitions = ClausewitzEvaluationDefinitions.build(snapshot);
-        const metadata = this.metadata(request, snapshot, surface, request.scenarioSet, request.candidatePool ?? [], gameVersionVerification, {
+        const metadata = this.metadata(request, snapshot, surface, request.scenarioSet, usingManifest
+            ? 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,
@@ -931,7 +1071,9 @@ export class ProbabilityAnalyzer {
         const cached = this.state.byCacheKey.get(metadata.cacheKey);
         if (cached !== undefined)
             return { result: cached, surface, definitions, snapshot };
-        const scenarios = evaluateSurfaceScenarios(surface, request.scenarioSet.scenarios, definitions, request.horizonDays);
+        const scenarios = usingManifest
+            ? customPoolScenarios(surface, request.customPoolManifest, request.scenarioSet)
+            : evaluateSurfaceScenarios(surface, request.scenarioSet.scenarios, definitions, request.horizonDays);
         return {
             result: this.buildResult(operation, metadata, surface, scenarios, {
                 ...(request.acceptanceBands === undefined
@@ -1048,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, {
@@ -1137,12 +1279,31 @@ export class ProbabilityAnalyzer {
         return this.store(result, request.outputs ?? ['json', 'sequence'], false, request.signal, request.principal);
     }
     async compare(request) {
-        const before = await this.analyzeUnstored('evaluate', { ...request, source: request.before });
-        const after = await this.analyzeUnstored('evaluate', {
-            ...request,
-            source: request.after,
-            refresh: false,
-        });
+        const manifestMode = request.beforeManifest !== undefined || request.afterManifest !== undefined;
+        if (manifestMode !== (request.before === undefined && request.after === undefined))
+            throw new ServiceError('PROBABILITY_COMPARE_INPUT_AMBIGUOUS', 'Compare either before/after sources or beforeManifest/afterManifest');
+        if (manifestMode &&
+            (request.beforeManifest === undefined || request.afterManifest === undefined))
+            throw new ServiceError('PROBABILITY_COMPARE_MANIFEST_REQUIRED', 'Custom-pool comparison requires both beforeManifest and afterManifest');
+        if (!manifestMode && (request.before === undefined || request.after === undefined))
+            throw new ServiceError('PROBABILITY_COMPARE_SOURCE_REQUIRED', 'Source comparison requires both before and after');
+        const before = manifestMode
+            ? await this.analyzeUnstored('evaluate', {
+                ...request,
+                customPoolManifest: request.beforeManifest,
+            })
+            : await this.analyzeUnstored('evaluate', { ...request, source: request.before });
+        const after = manifestMode
+            ? await this.analyzeUnstored('evaluate', {
+                ...request,
+                customPoolManifest: request.afterManifest,
+                refresh: false,
+            })
+            : await this.analyzeUnstored('evaluate', {
+                ...request,
+                source: request.after,
+                refresh: false,
+            });
         const metadata = {
             ...after.result.metadata,
             cacheKey: hashCanonical({
@@ -1196,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/technology/service.js

@@ -20,7 +20,6 @@ const GRAPH_ARTIFACT_BYTES = 134_217_728;
 const GRAPH_ARTIFACT_CHUNKS = 2_048;
 const HISTORY_ENTRIES = 12;
 const FOCUSED_RENDER_LIMIT = 32;
-const FOCUSED_GRAPH_FILE_THRESHOLD = 1_000;
 class BoundedTechnologyFragmentCache {
     #values = new Map();
     #bytes = 0;
@@ -88,6 +87,45 @@ function technologyScanPatterns(workspace) {
         ...under(roots.localisation, '*.{yml,yaml}'),
     ].sort(compareCodeUnits);
 }
+function recomputeTechnologyShadowing(files) {
+    const groups = new Map();
+    for (const file of files) {
+        delete file.shadowedBy;
+        const key = file.relativePath.replaceAll('\\', '/').toLowerCase();
+        const group = groups.get(key) ?? [];
+        group.push(file);
+        groups.set(key, group);
+    }
+    for (const group of groups.values()) {
+        group.sort((left, right) => right.loadOrder - left.loadOrder || compareCodeUnits(left.displayPath, right.displayPath));
+        const active = group[0];
+        for (const shadowed of group.slice(1))
+            shadowed.shadowedBy = active.displayPath;
+    }
+}
+async function scanTechnologySources(engine, workspaceId, workspace, principal, signal) {
+    const patterns = technologyScanPatterns(workspace);
+    const scans = await Promise.all([
+        engine.scan(workspaceId, { patterns, rootKinds: ['mod', 'dependency', 'fixture'] }, principal, signal),
+        ...(workspace.roots.some(({ kind }) => kind === 'game')
+            ? [engine.scan(workspaceId, { patterns, rootKinds: ['game'] }, principal, signal)]
+            : []),
+    ]);
+    const files = scans.flatMap(({ files }) => files.map((file) => ({ ...file })));
+    recomputeTechnologyShadowing(files);
+    files.sort((left, right) => left.loadOrder - right.loadOrder || compareCodeUnits(left.displayPath, right.displayPath));
+    const index = engine.indexFiles(files);
+    return {
+        workspaceId,
+        revision: hashCanonical(files.map(({ displayPath, loadOrder, sha256 }) => ({ displayPath, loadOrder, sha256 }))),
+        files,
+        index,
+        complete: scans.every(({ complete }) => complete) && index.complete,
+        skippedSourceCount: index.skippedSourceCount,
+        skippedSources: index.skippedSources,
+        diagnostics: [...scans.flatMap(({ diagnostics }) => diagnostics), ...index.diagnostics],
+    };
+}
 function activeTechnologySprite(spriteName, spritePath, sprites) {
     return sprites.find((sprite) => sprite.name === spriteName && (spritePath === undefined || sprite.sourcePath === spritePath));
 }
@@ -130,11 +168,6 @@ async function resolveTechnologyIconDataUris(cached, requestedSprites, budget, s
     }));
     return Object.fromEntries(Object.entries(dataUris).sort(([left], [right]) => compareCodeUnits(left, right)));
 }
-function technologyAnalysisMode(workspace, snapshot) {
-    return workspace.gameRoot !== undefined || snapshot.files.length > FOCUSED_GRAPH_FILE_THRESHOLD
-        ? 'focused'
-        : 'full';
-}
 function rememberGraph(state, graph) {
     const history = state.history.get(graph.workspaceId) ?? new Map();
     history.delete(graph.revision);
@@ -400,8 +433,8 @@ export class TechnologyTreeViewer {
         const cached = this.#state.current.get(workspaceId);
         if (options.refresh !== true && cached?.generation === generation)
             return cached.graph;
-        const snapshot = await this.engine.scan(workspaceId, { patterns: technologyScanPatterns(workspace) }, options.principal, options.signal);
-        const analysisMode = technologyAnalysisMode(workspace, snapshot);
+        const snapshot = await scanTechnologySources(this.engine, workspaceId, workspace, options.principal, options.signal);
+        const analysisMode = 'full';
         const preliminary = buildTechnologyGraph(snapshot, {
             workspaceIdentity: workspace.workspaceIdentity,
             cache: this.#state.fragments,

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.10';
+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.10",
+  "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.10/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.10/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.10/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.10/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.10/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.10/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.10/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.10/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.10/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.10/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.10/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": {