hoi4-agent-tools 3.4.1 → 3.5.1

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## Unreleased
 
+## 3.5.1 - 2026-09-27
+
+- Preserve installed-game and offline-wiki citations in compact reference context bundles, select question-relevant sections within required sources, and report sources omitted by the result limit separately from missing files.
+- Exercise one-, two-, and eight-result context budgets across six real-source work surfaces while retaining the nine-query discovery benchmark.
+- Allow up to five minutes for npm registry processing before publication verification fails.
+
+## 3.5.0 - 2026-09-26
+
+- Search and read bounded, revision-bound local offline-wiki, installed-game, and optional generated-script documentation sections; retrieve task citation bundles and exact indexed source definitions and usages through four read-only MCP tools.
+- Compare hash-bound frozen probability source files at their logical gameplay paths while preserving physical source provenance and leaving current files untouched.
+- Keep candidate eligibility overrides separate from weight-modifier conditions so an eligible scenario does not force every modifier to apply.
+- Evaluate hidden and custom-tooltip trigger wrappers with their enclosed conditions while excluding presentation metadata from eligibility logic.
+- Accept explicit GUI scenario dates and state-controller facts, evaluate their source conditions, render requested native windows at their declared settled show position, and resolve native list templates and scenario-only localisation from the correct source.
+- Honor single-line native labels and preserve the first inferred font line, with explicit fidelity reporting for undersized native text-height conventions.
+- Preserve dotted event namespaces so a namespace query selects its own events rather than unrelated systems sharing the first name segment.
+- Compact selected event diagrams without retaining empty row gaps from the rest of the workspace graph.
+- Resolve supported dated state-history values at the earliest active bookmark for map inspection, and refuse state rewrites that would silently conflict with or discard dated commands.
+- Interpret floating-harbor placements as sea-side markers with land targets, preserving vanilla-compatible anomalies as source-linked review warnings instead of thousands of false map errors.
+- Show alternatives within a national focus prerequisite group with dotted connectors, leaving individually required prerequisites solid.
+- Draw wide technology-folder icons at their decoded sprite dimensions and the source GUI's icon anchor, preserving 131×52 chemical cylinders instead of shrinking them to 70×70.
+- Include user-approved in-game focus and technology captures beside current-source and source-matched historical MCP renders, with source revisions and explicit whole-image comparison limits.
+- Include native-size vanilla and Chaos Redux interface references with declared scenarios, full images, diagnostics, and source hashes; keep game imagery outside the npm package.
+
 ## 3.4.1 - 2026-09-25
 
 - Validate technology renders against the requested view's source placement, node coverage, and sprite resolution without inheriting unrelated graph-wide diagnostics, while reporting deferred whole-workspace helper projection as a separate analysis boundary; resolve subtechnology art from the source GUI slot before using a technology-id fallback and include every referenced slot texture in the asset scan.
@@ -401,4 +424,4 @@
 - Removed runtime workspace registration, manual rollback, legacy write-policy inputs, and package-level library/schema exports.
 - Renamed the HTTP discovery grant to `allowDiscoveredMods`; it grants discovered mod IDs only.
 
-Earlier release history is available in the [Git tags](https://github.com/klimPaskov/hoi4-agent-tools/tags).
+Earlier release history is preserved in the [commit history](https://github.com/klimPaskov/hoi4-agent-tools/commits/main).

package/README.md

@@ -11,34 +11,35 @@ HOI4 Agent Tools is an MCP server for coding agents to understand Hearts of Iron
 - Cross-system impact and decisions: trace definitions and consumers across source systems, evaluate declared actor and target scenarios, inspect costs and mission paths, and compare in-memory proposals.
 - Technology trees: reconstruct technology and doctrine paths, folder layouts, unlocks, bonuses, grants, metadata, assets, and structural changes.
 - AI and MTTH: evaluate weighted choices and timing across explicit scenarios, bind special scope chains, enumerate dynamic target pools, sweep uncertain inputs, simulate distributions, compare patches, and analyze declared stateful pools.
+- Local references: search and read cited offline wiki pages, installed game documentation, optional script documentation, and exact source symbols without loading whole manuals into the conversation.
 
 ## Real results
 
-The GUI renderer resolves the mod and installed-game sources, fonts, localisation colours, sprites, scripted visibility, dynamic values, lists, controls, and panel composition. These pairs show the in-game surface beside the MCP result.
+The examples use real installed vanilla and Chaos Redux source, supplied game captures, and explicit reproducible display scenarios. They demonstrate source-backed review, not a claim of 99.9% whole-image accuracy. Images, source revisions, hashes, and known differences are in [Visual comparisons](docs/visual-comparisons.md) and [Interface examples](docs/gui-comparisons.md).
 
-| Communist Insurgency in game                                                        | Communist Insurgency from MCP                                                                |
-| ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| ![Communist Insurgency in game](docs/images/readme/communist-insurgency-ingame.png) | ![Communist Insurgency rendered by the MCP](docs/images/readme/communist-insurgency-mcp.png) |
+| Options Video in game                                                          | Options Video from the MCP renderer                                                                |
+| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
+| ![Options Video in game](docs/images/comparisons/gui/options-video-ingame.png) | ![Options Video rendered from installed source](docs/images/comparisons/gui/options-video-mcp.png) |
 
-| Chaos Meter in game                                               | Chaos Meter from MCP                                                       |
-| ----------------------------------------------------------------- | -------------------------------------------------------------------------- |
-| ![Chaos Meter in game](docs/images/readme/chaos-meter-ingame.png) | ![Chaos Meter rendered by the MCP](docs/images/readme/chaos-meter-mcp.png) |
+| Škoda Priority in game                                                           | Škoda Priority from the MCP renderer                                                                 |
+| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| ![Škoda Priority in game](docs/images/comparisons/gui/skoda-priority-ingame.png) | ![Škoda Priority rendered from installed source](docs/images/comparisons/gui/skoda-priority-mcp.png) |
 
-The same scenario-aware renderer can select mutually exclusive settings panes and populate plausible runtime values.
-
-| Trigger Events settings                                                                    | Advanced settings                                                                      |
-| ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
-| ![Trigger Events settings rendered by the MCP](docs/images/readme/settings-events-mcp.png) | ![Advanced settings rendered by the MCP](docs/images/readme/settings-advanced-mcp.png) |
+The interface gallery also includes Chaos Redux Settings, Event Log, and Chaos Meter, plus populated vanilla decision and occupation templates. Their manifests separate source-defined layout from declared native runtime fields.
 
 The other workbenches return complete source-linked layouts and catalogs rather than prose-only summaries.
 
-| Focus tree                                                                     | Technology tree                                                                    |
-| ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
-| ![Large focus tree rendered by the MCP](docs/images/readme/focus-tree-mcp.png) | ![Technology tree rendered by the MCP](docs/images/readme/technology-tree-mcp.png) |
+For the supplied focus and technology game captures beside current-source MCP renders, see [Visual examples and comparison limits](https://github.com/klimPaskov/hoi4-agent-tools/blob/main/docs/visual-comparisons.md). These comparisons do not establish 99.9% whole-image accuracy.
+
+| Fury focus tree from Chaos Redux                                                          | Infantry technology folder from Chaos Redux and vanilla                                                |
+| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| ![Fury focus tree rendered from Chaos Redux source](docs/images/comparisons/fury-mcp.png) | ![Infantry technology folder rendered from installed source](docs/images/comparisons/infantry-mcp.png) |
+
+| Map                                                                              | Event options                                                                                      |
+| -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| ![Installed map rendered by the MCP](docs/images/comparisons/source/map-mcp.png) | ![Chaos Redux event chain rendered by the MCP](docs/images/comparisons/source/event-chain-mcp.png) |
 
-| Map                                                             | Event chain                                                                | Probability ranking                                                                |
-| --------------------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
-| ![Full map rendered by the MCP](docs/images/readme/map-mcp.png) | ![Event chain rendered by the MCP](docs/images/readme/event-chain-mcp.png) | ![Probability ranking rendered by the MCP](docs/images/readme/probability-mcp.png) |
+These two views retain native output resolution. Their [source manifest](docs/images/comparisons/source/manifest.json) records the map revision and the exact Fury event used for the option view. The event renderer's omitted-node count includes the rest of the workspace graph outside that selection.
 
 ## Use from a coding agent
 
@@ -51,6 +52,8 @@ npm install --global hoi4-agent-tools@latest
 ```toml
 [mcp_servers.hoi4_agent_tools]
 command = "hoi4-agent-tools.cmd"
+startup_timeout_sec = 120
+tool_timeout_sec = 600
 ```
 
 On non-Windows systems, use `hoi4-agent-tools` as the command. Agentic HOI4 repositories can include these steps in their agent template so the coding agent installs and registers the server itself; manual installation is not required in that workflow. Once connected, the server follows the active mod supplied by the client and the agent can call its HOI4 tools directly.
@@ -69,6 +72,10 @@ On non-Windows systems, use `hoi4-agent-tools` as the command. Agentic HOI4 repo
 | `hoi4.map_inspect`          | Search, click, navigate, and inspect the complete rendered map and its linked data.       |
 | `hoi4.map_render`           | Render full-map layers, overlays, names, IDs, coordinates, and source-linked catalogs.    |
 | `hoi4.map_rewrite`          | Create or update states, provinces, IDs, networks, positions, and connected map data.     |
+| `hoi4.reference_context`    | Get compact, cited wiki and installed documentation pointers for a modding surface.       |
+| `hoi4.reference_search`     | Search bounded local documentation sections.                                              |
+| `hoi4.reference_read`       | Read one revision-bound section, with line continuation.                                  |
+| `hoi4.source_lookup`        | Find exact definitions, overrides, usages, and narrow source blocks.                      |
 | `hoi4.event_inspect`        | Scan, trace, explain, lint, or assess event chains and their state flow.                  |
 | `hoi4.event_render`         | Render source-linked event routes, options, timing, state, scope, and unresolved edges.   |
 | `hoi4.event_compare`        | Compare event-chain topology and diagnostics between revisions.                           |
@@ -114,6 +121,7 @@ Ask your agent in normal task language. A typical workflow is inspect, render, r
 - Mechanics and packages: "Test this transfer's conservation and payment," or "Check every declared package link and resume its named scenario suite." See [Mechanic tests and scenario suites](docs/mechanics.md).
 - Technology trees: "Explain everything this technology requires and unlocks," or "Compare this technology patch and render every affected folder and doctrine branch." See [Technology trees](docs/technology.md).
 - AI and MTTH: "Compare these focus weights across peace, defensive-war, and low-stability scenarios," or "Show when this MTTH event becomes likely and which unknown inputs control the result." See [AI and MTTH analysis](docs/probability.md).
+- References: "Find the installed effect signature and an exact vanilla example," or "Show the pertinent wiki and installed documentation for this GUI task." See [Local references](docs/reference.md).
 
 ## HTTP
 

package/dist/hoi4_agent_tools/core/condition-evaluator.js

@@ -176,8 +176,17 @@ function evaluateAssignmentCore(assignment, scenario, candidate, definitions, he
         const malformed = malformedBlock(assignment.value, candidate);
         if (malformed !== undefined)
             return malformed;
-        if (key === 'AND')
-            return evaluateTriggerBlock(assignment.value, scenario, candidate, definitions, helperStack, scopeContext);
+        if (key === 'AND' ||
+            key === 'hidden_trigger' ||
+            key === 'custom_trigger_tooltip' ||
+            key === 'custom_override_tooltip')
+            return evaluateTriggerBlock(key === 'custom_trigger_tooltip' || key === 'custom_override_tooltip'
+                ? {
+                    ...assignment.value,
+                    entries: assignment.value.entries.filter((entry) => entry.type !== 'assignment' ||
+                        !['tooltip', 'not_tooltip'].includes(entry.key.value)),
+                }
+                : assignment.value, scenario, candidate, definitions, helperStack, scopeContext);
         if (key === 'OR') {
             const children = assignments(assignment.value).map((child) => evaluateAssignment(child, scenario, candidate, definitions, helperStack, scopeContext));
             return {
@@ -318,6 +327,36 @@ function evaluateAssignmentCore(assignment, scenario, candidate, definitions, he
             unresolved: [],
         };
     }
+    if ((key === 'controls_state' || key === 'is_controlled_by') && scenario.controls !== undefined) {
+        const targetScope = resolveScopeContext(scenario, right, scopeContext);
+        const stateId = key === 'controls_state'
+            ? /^[1-9][0-9]*$/u.test(right)
+                ? right
+                : targetScope?.binding.id
+            : scopeContext.binding.id;
+        const country = key === 'controls_state'
+            ? scopeContext.expression === 'ROOT'
+                ? scenario.actor
+                : scopeIdentity(scopeContext)
+            : targetScope === undefined
+                ? /^[A-Z0-9]{3}$/u.test(right)
+                    ? right
+                    : undefined
+                : targetScope.expression === 'ROOT' && scenario.actor === undefined
+                    ? undefined
+                    : scopeIdentity(targetScope);
+        if (stateId === undefined || !/^[1-9][0-9]*$/u.test(stateId) || country === undefined)
+            return unresolved(assignment, candidate, `Scenario does not bind the state and country for ${key}`, 'controls');
+        const controller = scenario.controls[stateId];
+        if (controller === undefined)
+            return unresolved(assignment, candidate, `Scenario does not declare the controller of state ${stateId}`, `controls.${stateId}`);
+        if (!['=', '!='].includes(assignment.operator.text))
+            return unresolved(assignment, candidate, `Unsupported controller comparison ${assignment.operator.text}`);
+        return {
+            state: compare(controller, country, assignment.operator.text) ? 'true' : 'false',
+            unresolved: [],
+        };
+    }
     const helper = definitions.scriptedTriggers.get(key);
     if (helper !== undefined && bool(right) !== undefined) {
         if (helperStack.includes(key))

package/dist/hoi4_agent_tools/core/condition-schema.js

@@ -1,4 +1,22 @@
 import { z } from 'zod';
+export const ConditionControlMapSchema = z
+    .record(z.string().regex(/^[1-9][0-9]{0,8}$/u), z.string().regex(/^[A-Z0-9]{3}$/u))
+    .refine((value) => Object.keys(value).length <= 2_048, 'Too many declared state controllers');
+export const GuiScenarioDateSchema = z
+    .string()
+    .max(16)
+    .refine((value) => {
+    const match = /^(\d{1,4})[.-](\d{1,2})[.-](\d{1,2})$/u.exec(value);
+    if (match === null)
+        return false;
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+    const days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+    return year >= 1 && month >= 1 && month <= 12 && day >= 1 && day <= days[month - 1];
+}, 'Use a valid YYYY.M.D or YYYY-MM-DD date')
+    .transform((value) => value.split(/[.-]/u).map(Number).join('.'));
 export const ScenarioScalarSchema = z.union([
     z.string().max(16_384),
     z.number(),

package/dist/hoi4_agent_tools/core/configuration.js

@@ -96,6 +96,16 @@ export const workspaceRegistrationSchema = z
     artifactRoot: z.string().min(1).optional(),
     cacheRoot: z.string().min(1).optional(),
     fixtureRoot: z.string().min(1).optional(),
+    wikiRoot: z
+        .string()
+        .min(1)
+        .refine((value) => path.isAbsolute(value), 'Wiki root must be absolute')
+        .optional(),
+    scriptDocsRoot: z
+        .string()
+        .min(1)
+        .refine((value) => path.isAbsolute(value), 'Script documentation root must be absolute')
+        .optional(),
 })
     .strict()
     .superRefine((value, context) => {

package/dist/hoi4_agent_tools/core/domain-scan-patterns.js

@@ -1,4 +1,5 @@
 import { compareCodeUnits } from './canonical.js';
+import { ServiceError } from './result.js';
 function under(roots, glob) {
     return roots.map((root) => `${root.replaceAll('\\', '/').replace(/\/$/u, '')}/${glob}`);
 }
@@ -39,7 +40,14 @@ export function focusDomainScanPatterns(workspace) {
 /** Weighted source surfaces and shared definitions used by probability analysis. */
 export function probabilityDomainScanPatterns(workspace, sourcePaths = []) {
     const roots = workspace.registration.roots;
-    const normalizedSourcePaths = sourcePaths.map((sourcePath) => sourcePath.replace(/^.*?:/u, '').replaceAll('\\', '/').replace(/^\.\//u, ''));
+    const normalizedSourcePaths = sourcePaths.map((sourcePath) => {
+        const normalized = sourcePath.replaceAll('\\', '/').replace(/^\.\//u, '');
+        if (normalized.startsWith('/') ||
+            normalized.split('/').includes('..') ||
+            /[:*?[\]{}!\0]/u.test(normalized))
+            throw new ServiceError('PROBABILITY_SOURCE_PATH_INVALID', 'Probability source paths must be exact workspace-relative files');
+        return normalized;
+    });
     if (normalizedSourcePaths.length > 0)
         return uniquePatterns([...normalizedSourcePaths, ...probabilitySharedDefinitionPatterns()]);
     return uniquePatterns([

package/dist/hoi4_agent_tools/core/impact-semantic.js

@@ -56,12 +56,18 @@ function stateKeyTarget(assignment, kind) {
 function normalized(file) {
     return file.relativePath.replaceAll('\\', '/').toLowerCase();
 }
-function ownerFor(snapshot, file, assignment, ancestors) {
+function ownerFor(snapshot, file, assignment, ancestors, includeOnActions) {
     if (assignment.value.type !== 'block')
         return undefined;
     const key = assignment.key.value;
     const sourcePath = normalized(file);
     let owner;
+    if (includeOnActions &&
+        sourcePath.startsWith('common/on_actions/') &&
+        ancestors.length === 1 &&
+        ancestors[0] === 'on_actions') {
+        return { kind: 'on_action', id: key };
+    }
     if (sourcePath.startsWith('events/') && ancestors.length === 0 && eventKeys.has(key)) {
         const id = firstScalar(assignment.value, 'id')?.value;
         if (id !== undefined)
@@ -114,7 +120,7 @@ function staticTarget(value) {
         !/^(?:ROOT|FROM|PREV|THIS)$/iu.test(value));
 }
 /** Extracts typed script edges while preserving unknown dynamic references. */
-export function scanImpactSemanticReferences(snapshot, maxReferences = 200_000) {
+export function scanImpactSemanticReferences(snapshot, maxReferences = 200_000, options = {}) {
     if (!Number.isSafeInteger(maxReferences) || maxReferences < 1 || maxReferences > 1_000_000)
         throw new RangeError('Semantic reference limit is outside the supported range');
     const references = [];
@@ -148,7 +154,7 @@ export function scanImpactSemanticReferences(snapshot, maxReferences = 200_000)
     };
     const walk = (file, document, block, ancestors, owner) => {
         for (const assignment of assignments(block)) {
-            const identified = ownerFor(snapshot, file, assignment, ancestors);
+            const identified = ownerFor(snapshot, file, assignment, ancestors, options.includeOnActions === true);
             const current = identified ?? owner;
             if (identified?.kind === 'decision' && ancestors.length === 1)
                 emit(file, document, assignment, identified, 'decision_category', ancestors[0], 'decision_category_membership');
@@ -237,7 +243,8 @@ export function scanImpactSemanticReferences(snapshot, maxReferences = 200_000)
                 path.startsWith('common/technologies/') ||
                 path.startsWith('common/scripted_effects/') ||
                 path.startsWith('common/scripted_triggers/') ||
-                path.startsWith('common/scripted_guis/')))
+                path.startsWith('common/scripted_guis/') ||
+                (options.includeOnActions === true && path.startsWith('common/on_actions/'))))
             continue;
         if (snapshot.index.isSourceSkipped(file.displayPath)) {
             complete = false;

package/dist/hoi4_agent_tools/core/scanner.js

@@ -180,7 +180,7 @@ export class WorkspaceScanner {
         return result;
     }
 }
-async function readBoundedFile(handle, remainingBytes, signal) {
+export async function readBoundedFile(handle, remainingBytes, signal) {
     const chunks = [];
     let total = 0;
     for (;;) {

package/dist/hoi4_agent_tools/core/scenario-model.js

@@ -34,6 +34,9 @@ export function scenarioFromGui(base, values = base.values) {
     for (const [key, value] of Object.entries(base.flags))
         state[`flag.${key}`] = value;
     const scopes = structuredClone(base.scopes ?? {});
+    for (const stateId of Object.keys(base.controls ?? {})) {
+        scopes[stateId] ??= { id: stateId, type: 'state', state: {} };
+    }
     for (const [key, value] of Object.entries(state)) {
         const match = /^(ROOT|THIS|FROM(?:\.FROM)*|PREV)\.(.+)$/u.exec(key);
         if (match === null)
@@ -49,6 +52,8 @@ export function scenarioFromGui(base, values = base.values) {
     return {
         schemaVersion: '1.0',
         id: base.id,
+        ...(base.date === undefined ? {} : { date: base.date }),
+        ...(base.controls === undefined ? {} : { controls: { ...base.controls } }),
         state,
         scopes,
         closedFlags: false,
@@ -62,6 +67,7 @@ export function scenarioFromProbability(base) {
         id: base.id,
         ...(base.actor === undefined ? {} : { actor: base.actor }),
         ...(base.date === undefined ? {} : { date: base.date }),
+        ...(base.controls === undefined ? {} : { controls: { ...base.controls } }),
         state: structuredClone(base.state),
         ...(base.flags === undefined ? {} : { flags: [...base.flags] }),
         ...(base.eventTargets === undefined ? {} : { eventTargets: { ...base.eventTargets } }),

package/dist/hoi4_agent_tools/core/scenario-state.js

@@ -42,6 +42,9 @@ export function resolveScopeContext(scenario, expression, current) {
     const direct = explicitScope(scenario, expression, current);
     if (direct !== undefined)
         return direct;
+    if (/^[1-9][0-9]*$/u.test(expression) && Object.hasOwn(scenario.controls ?? {}, expression)) {
+        return { expression, binding: { id: expression, type: 'state', state: {} }, parent: current };
+    }
     const targetMatch = /^(?:event_target|scope):(.+)$/iu.exec(expression);
     const targetId = targetMatch === null
         ? undefined

package/dist/hoi4_agent_tools/core/workspace.js

@@ -488,6 +488,10 @@ export class WorkspaceResolver {
         const fixtureRoot = registration.fixtureRoot === undefined
             ? undefined
             : await canonicalPath(registration.fixtureRoot);
+        const wikiRoot = registration.wikiRoot === undefined ? undefined : await canonicalPath(registration.wikiRoot);
+        const scriptDocsRoot = registration.scriptDocsRoot === undefined
+            ? undefined
+            : await canonicalPath(registration.scriptDocsRoot);
         const generatedAllowed = (candidate, generatedKind) => (registration.kind === 'mod' &&
             isWithin(path.join(modRoot, '.hoi4-agent', generatedKind), candidate)) ||
             this.#storageRoots.some((root) => isWithin(root, candidate));
@@ -524,7 +528,13 @@ export class WorkspaceResolver {
             }
         }
         if (this.#serverStateRoot !== undefined &&
-            [modRoot, ...sourceRoots, artifactRoot, cacheRoot].some((root) => pathsOverlap(this.#serverStateRoot, root))) {
+            [
+                modRoot,
+                ...sourceRoots,
+                artifactRoot,
+                cacheRoot,
+                ...[wikiRoot, scriptDocsRoot].filter((root) => root !== undefined),
+            ].some((root) => pathsOverlap(this.#serverStateRoot, root))) {
             throw new ServiceError('SERVER_STATE_ROOT_OVERLAP', 'Server state root must not overlap a workspace source or generated-storage root', { workspaceId: registration.id });
         }
         await mkdir(artifactRoot, { recursive: true });
@@ -595,6 +605,8 @@ export class WorkspaceResolver {
             artifactRoot,
             cacheRoot,
             ...(fixtureRoot === undefined ? {} : { fixtureRoot }),
+            ...(wikiRoot === undefined ? {} : { wikiRoot }),
+            ...(scriptDocsRoot === undefined ? {} : { scriptDocsRoot }),
             writeEnabled: registration.kind === 'mod',
         };
         const workspaceIdentity = resolvedWorkspaceIdentity(workspaceBase);

package/dist/hoi4_agent_tools/event/graph.js

@@ -848,7 +848,14 @@ function ensureReferencedNodes(graph) {
             id: edge.to,
             kind: 'unresolved',
             label: `Missing ${isEvent ? 'event' : 'helper'}: ${expression}`,
-            ...(isEvent ? { eventId: expression, namespace: expression.split('.')[0] } : {}),
+            ...(isEvent
+                ? {
+                    eventId: expression,
+                    namespace: expression.includes('.')
+                        ? expression.slice(0, expression.lastIndexOf('.'))
+                        : expression,
+                }
+                : {}),
             sourcePath: edge.location.path,
             location: edge.location,
             metadata: { expression, unresolvedKind },

package/dist/hoi4_agent_tools/event/service.js

@@ -984,6 +984,7 @@ export class EventChainViewer {
         const renderOptions = {
             view: input.view,
             budget,
+            compactLayout: input.compactLayout ?? input.selector !== undefined,
             ...(input.selector === undefined ? {} : { selector: input.selector }),
             ...(input.direction === undefined ? {} : { direction: input.direction }),
             ...(input.maxDepth === undefined ? {} : { maxDepth: input.maxDepth }),

package/dist/hoi4_agent_tools/event/source-analysis.js

@@ -450,7 +450,7 @@ class FragmentAnalyzer {
                 kind: 'event',
                 label: id,
                 eventId: id,
-                namespace: id.includes('.') ? id.slice(0, id.indexOf('.')) : id,
+                namespace: id.includes('.') ? id.slice(0, id.lastIndexOf('.')) : id,
                 sourcePath: this.file.displayPath,
                 location: this.location(assignment, id),
                 metadata: {

package/dist/hoi4_agent_tools/focus/render.js

@@ -204,7 +204,12 @@ function svgDocument(plan, layout, diagnostics, options) {
         diagnosticMap.set(focusId, group);
     }
     const prerequisiteEdges = plan.focuses
-        .flatMap((focus) => focus.prerequisites.groups.flatMap((group, groupIndex) => group.focusIds.map((parentId) => ({ parentId, childId: focus.id, groupIndex }))))
+        .flatMap((focus) => focus.prerequisites.groups.flatMap((group, groupIndex) => group.focusIds.map((parentId) => ({
+        parentId,
+        childId: focus.id,
+        groupIndex,
+        alternative: group.focusIds.length > 1,
+    }))))
         .filter(({ parentId, childId }) => pixel.has(parentId) && pixel.has(childId))
         .sort((left, right) => compareCodeUnits(left.parentId, right.parentId) ||
         compareCodeUnits(left.childId, right.childId) ||
@@ -239,7 +244,10 @@ function svgDocument(plan, layout, diagnostics, options) {
             originX: padding - minimumX * horizontal,
             originY: padding - minimumY * vertical,
         });
-        parts.push(`<path d="${focusConnectorSvgPath(curve)}" fill="none" stroke="#8da2bc" stroke-width="2" marker-end="url(#arrow)" data-parent="${escapeXml(edge.parentId)}" data-child="${escapeXml(edge.childId)}" data-prerequisite-group="${edge.groupIndex}"/>`);
+        const stroke = edge.alternative
+            ? 'stroke-width="2.5" stroke-dasharray="2 4" stroke-linecap="round"'
+            : 'stroke-width="2"';
+        parts.push(`<path d="${focusConnectorSvgPath(curve)}" fill="none" stroke="#8da2bc" ${stroke} marker-end="url(#arrow)" data-parent="${escapeXml(edge.parentId)}" data-child="${escapeXml(edge.childId)}" data-prerequisite-group="${edge.groupIndex}" data-prerequisite-kind="${edge.alternative ? 'or' : 'required'}"/>`);
     }
     parts.push('</g>', '<g id="mutual-exclusions">');
     for (const [leftId, rightId] of exclusionEdges) {

package/dist/hoi4_agent_tools/gui/layout.js

@@ -1172,7 +1172,11 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
     const clipChain = inheritedClipChain ?? (inheritedClip === undefined ? [] : [inheritedClip]);
     const localScale = scalarNumber(property(definition.attributes, 'scale'), 1) ?? 1;
     const scale = parentScale * localScale;
-    const position = objectProperty(property(definition.attributes, 'position'));
+    const shownPosition = depth === 0 ? objectProperty(property(definition.attributes, 'show_position')) : undefined;
+    const position = shownPosition ?? objectProperty(property(definition.attributes, 'position'));
+    if (shownPosition !== undefined) {
+        addFidelity(fidelity, 'modelled', 'window_show_position', 'The requested root window uses its declared settled show position.', definition);
+    }
     const size = objectProperty(property(definition.attributes, 'size'));
     const scriptedX = rowValues?.[`${definition.name}.x`] ??
         scenario.values[`${definition.name}.x`] ??
@@ -1196,8 +1200,22 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
     const orientationAxes = anchorAxes(orientation);
     const anchorX = anchoredCoordinate(parentRect.x, parentRect.width, localX, orientationAxes.horizontal);
     const anchorY = anchoredCoordinate(parentRect.y, parentRect.height, localY, orientationAxes.vertical);
-    const widthValue = size === undefined ? undefined : property(size, 'width', 'x');
-    const heightValue = size === undefined ? undefined : property(size, 'height', 'y');
+    const scriptedWidth = rowValues?.[`${definition.name}.width`] ??
+        scenario.values[`${definition.name}.width`] ??
+        scenario.scriptedGui[`${definition.name}.width`];
+    const scriptedHeight = rowValues?.[`${definition.name}.height`] ??
+        scenario.values[`${definition.name}.height`] ??
+        scenario.scriptedGui[`${definition.name}.height`];
+    const widthValue = typeof scriptedWidth === 'number' && Number.isFinite(scriptedWidth)
+        ? scriptedWidth
+        : size === undefined
+            ? undefined
+            : property(size, 'width', 'x');
+    const heightValue = typeof scriptedHeight === 'number' && Number.isFinite(scriptedHeight)
+        ? scriptedHeight
+        : size === undefined
+            ? undefined
+            : property(size, 'height', 'y');
     let width = scaledNumber(widthValue, parentRect.width, scale) ?? 0;
     let height = scaledNumber(heightValue, parentRect.height, scale) ?? 0;
     // A doubled percent names a far-edge coordinate in the parent, whereas a single
@@ -1455,10 +1473,17 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
             width = declaredMaxWidth;
         if (width === 0 && inferWidth && /textbox/iu.test(definition.elementType))
             width = nativeTextBoxWidth * scale;
-        if (height === 0 && inferHeight && declaredMaxHeight !== undefined)
+        const inferredTextHeight = height === 0 && inferHeight;
+        if (inferredTextHeight && declaredMaxHeight !== undefined)
             height = declaredMaxHeight;
         const maxWidth = declaredMaxWidth ?? width;
-        const wrapped = wrapText(catalog, fontName, displayText, visibleText.colours, fontSize * scale, maxWidth, context.work, resolvedInlineIcons);
+        const wrapped = wrapText(catalog, fontName, displayText, visibleText.colours, fontSize * scale, scalarBoolean(property(definition.attributes, 'multiline')) === false ? 0 : maxWidth, context.work, resolvedInlineIcons);
+        // Native maxHeight text boxes retain at least one font line. Explicit size
+        // rectangles and inherited parent clipping still constrain their pixels.
+        if (inferredTextHeight && declaredMaxHeight !== undefined && height < wrapped.lineHeight) {
+            height = wrapped.lineHeight;
+            addFidelity(fidelity, 'approximated', 'text_minimum_line_height', 'An inferred maxHeight smaller than one font line retains the first line; this native layout convention has no engine capture in this scenario.', definition);
+        }
         const glyphLines = [];
         const inlineIcons = [];
         for (const [lineIndex, line] of wrapped.lines.entries()) {
@@ -1747,7 +1772,7 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
     if (state === 'full-list' && rows === undefined)
         rows = Array.from({ length: 12 }, (_unused, index) => ({ index }));
     const dynamicList = context.dynamicListsByName.get(definition.name);
-    const listElement = /(?:grid|listbox|overlappingelements)/iu.test(definition.elementType);
+    const listElement = /(?:grid|listbox|overlappingelements|positiontype)/iu.test(definition.elementType);
     const slotSize = objectProperty(property(definition.attributes, 'slotsize'));
     const slotHeight = scaledNumber(slotSize === undefined ? undefined : property(slotSize, 'height', 'y'), height, scale);
     const slotWidth = scaledNumber(slotSize === undefined ? undefined : property(slotSize, 'width', 'x'), width, scale);
@@ -1761,8 +1786,13 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
     const maxHorizontal = scalarNumber(property(definition.attributes, 'max_slots_horizontal'), 1);
     const maxVertical = scalarNumber(property(definition.attributes, 'max_slots_vertical'), 1);
     const grid = /grid/iu.test(definition.elementType);
+    const singleColumnFlow = grid &&
+        maxHorizontal === 1 &&
+        slotHeight !== undefined &&
+        slotHeight <= scale &&
+        (maxVertical === undefined || maxVertical <= 0);
     const rowPosition = (index, fallbackY) => {
-        if (!grid || slotWidth === undefined || slotHeight === undefined)
+        if (!grid || singleColumnFlow || slotWidth === undefined || slotHeight === undefined)
             return { x: 0, y: fallbackY };
         if (maxVertical !== undefined && maxVertical > 0) {
             const rowsPerColumn = Math.max(1, Math.trunc(maxVertical));
@@ -1822,11 +1852,22 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
                 (row.countryScope === true
                     ? (dynamicList?.countryScopeEntryContainer ?? dynamicList?.entryContainer)
                     : (dynamicList?.entryContainer ?? dynamicList?.countryScopeEntryContainer));
-            const template = templateName === undefined ? undefined : context.elementsByName.get(templateName);
+            const candidates = templateName === undefined
+                ? []
+                : (context.elementsByNameCandidates.get(templateName) ?? []);
+            const localCandidates = candidates.filter(({ sourcePath }) => sourcePath === definition.sourcePath);
+            const localRoots = localCandidates.filter(({ parentId }) => parentId === undefined);
+            const template = localRoots.length === 1
+                ? localRoots[0]
+                : localCandidates.length === 1
+                    ? localCandidates[0]
+                    : candidates.length === 1
+                        ? candidates[0]
+                        : undefined;
             if (template === undefined) {
                 diagnostics.push(diagnostic('GUI_DYNAMIC_LIST_TEMPLATE_MISSING', 'error', templateName === undefined
                     ? `Dynamic list ${definition.name} has no entry container for scenario row ${index}.`
-                    : `Dynamic list ${definition.name} cannot resolve entry container ${templateName}.`, definition));
+                    : `Dynamic list ${definition.name} cannot unambiguously resolve entry container ${templateName}.`, definition));
                 continue;
             }
             const templatePosition = objectProperty(property(template.attributes, 'position'));
@@ -1842,7 +1883,7 @@ async function layoutElement(definition, parentRect, inheritedClip, parentScale,
             };
             await layoutElement(template, shiftedParent, childClip, scale, depth + 1, context, rowSuffix(index), index, row, instanceId, origo, resolveVisibleAppearance, childClipChain);
             const rendered = context.instancesById.get(`${template.id}${rowSuffix(index)}`);
-            rowY += (slotHeight ?? rendered?.unclippedRect.height ?? 0) + spacingY;
+            rowY += Math.max(slotHeight ?? 0, rendered?.unclippedRect.height ?? 0) + spacingY;
             renderedRows += 1;
         }
         addFidelity(fidelity, renderedRows === rows.length ? 'modelled' : 'missing', dynamicList === undefined ? 'native_dynamic_list' : 'scripted_gui_dynamic_list', `Expanded ${renderedRows}/${rows.length} scenario rows for ${definition.name} through ${dynamicList === undefined ? 'explicit native' : 'scripted-GUI'} entry containers.`, definition);
@@ -2055,10 +2096,15 @@ export async function buildGuiScene(graph, scannedFiles, windowName, scenario, c
     };
     const output = [];
     const elementsByName = new Map();
+    const elementsByNameCandidates = new Map();
     for (const element of [...graph.elements].sort((left, right) => compareCodeUnits(right.sourcePath, left.sourcePath) ||
-        right.definitionOrder - left.definitionOrder))
+        right.definitionOrder - left.definitionOrder)) {
         if (!elementsByName.has(element.name))
             elementsByName.set(element.name, element);
+        const candidates = elementsByNameCandidates.get(element.name) ?? [];
+        candidates.push(element);
+        elementsByNameCandidates.set(element.name, candidates);
+    }
     const context = {
         graph,
         scenario: layoutScenario,
@@ -2067,6 +2113,7 @@ export async function buildGuiScene(graph, scannedFiles, windowName, scenario, c
         diagnostics,
         elementsById,
         elementsByName,
+        elementsByNameCandidates,
         dynamicListsByName,
         countryFlagProperties,
         constantElementEnabled,

package/dist/hoi4_agent_tools/gui/scenario.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { ConditionScopeBindingSchema, ConditionResultSchema } from '../core/condition-schema.js';
+import { ConditionScopeBindingSchema, ConditionResultSchema, ConditionControlMapSchema, GuiScenarioDateSchema, } from '../core/condition-schema.js';
 import { renderDimensionViolation, RENDER_MAX_DIMENSION } from '../core/render-budget.js';
 import { ServiceError } from '../core/result.js';
 import { GUI_SCENARIO_MAX_KEYS, GUI_SCENARIO_MAX_LIST_KEYS, GUI_SCENARIO_MAX_ROWS, GUI_SCENARIO_MAX_STRING_CHARACTERS, } from './limits.js';
@@ -104,6 +104,8 @@ const GuiPreviewScenarioBodySchema = z
         .max(128)
         .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/u),
     description: z.string().max(500).optional(),
+    date: GuiScenarioDateSchema.optional(),
+    controls: ConditionControlMapSchema.optional(),
     resolution: GuiPreviewResolutionSchema.default({ width: 1920, height: 1080 }),
     uiScale: z
         .number()