hoi4-agent-tools 3.4.0 → 3.5.0

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 ## Unreleased
 
+## 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.
+- Accept focused event inspection and render evidence when every event source was scanned and no blocking diagnostics remain, while retaining deferred workspace-wide helper and lifecycle projections as an explicit boundary.
+- Keep repeated window-local GUI control names additive in the shared index, exclude engine-owned compound-control roles from scripted click-effect requirements, and preserve compact operation summaries when linked evidence exceeds the MCP wire budget.
+- Parse each active scripted-effect source document once when building mechanic helper inventories so bounded real-workspace scenarios do not multiply parser state by the number of helpers in a file.
+- Interpret declared temporary-variable assignment, arithmetic, rounding, clamping, and scope-valued inputs with chain-wide unscoped semantics in bounded mechanic scenarios.
+- Evaluate `has_variable` against declared scenario state so guarded defaults and subsequent temporary-variable arithmetic remain deterministic.
+- Follow a live replacement worker through its terminal publication instead of returning a nonterminal job record during concurrent checkpoint recovery.
+
 ## 3.4.0 - 2026-09-20
 
 - Add branch-local focus cleanup with pinned anchors and symmetry groups, connector measurements, source-linked crops, and scenario-backed structural route diagnostics.

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 {
@@ -278,6 +287,13 @@ function evaluateAssignmentCore(assignment, scenario, candidate, definitions, he
             unresolved: [],
         };
     }
+    if (key === 'has_variable') {
+        const state = scopeContext.expression === 'ROOT' ? scenario.state : scopeContext.binding.state;
+        return {
+            state: Object.hasOwn(state, right) || Object.hasOwn(state, `variable.${right}`) ? 'true' : 'false',
+            unresolved: [],
+        };
+    }
     if (key === 'tag' || key === 'original_tag') {
         const actor = scopeContext.expression === 'ROOT'
             ? scenario.actor
@@ -311,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/index.js

@@ -1369,6 +1369,7 @@ export class SymbolIndex {
             this.#active.set(key, active);
             const additiveCategory = active.kind === 'decision_category' ||
                 active.kind === 'technology_category' ||
+                active.kind === 'gui_element' ||
                 active.kind === 'texture';
             for (const candidate of group) {
                 candidate.overridden = additiveCategory ? candidate.sourceShadowed : candidate !== active;

package/dist/hoi4_agent_tools/core/job-worker-host.js

@@ -73,7 +73,12 @@ export class JobWorkerHost {
         for (;;) {
             try {
                 await this.scheduler.run(this.owner, 1024, signal, () => this.capacity.run(signal, (lease) => this.launch(workspaceId, id, lease, principal)));
-                return await this.jobs.get(workspaceId, id, principal);
+                const current = await this.jobs.get(workspaceId, id, principal);
+                if (['completed', 'cancelled', 'failed'].includes(current.status))
+                    return current;
+                if (current.owner !== undefined && jobOwnerLiveness(current.owner) === 'alive')
+                    return await this.followOwner(workspaceId, id, principal);
+                throw new ServiceError('JOB_WORKER_EXIT', 'The worker stopped without publishing a terminal job outcome');
             }
             catch (error) {
                 const current = await this.jobs.get(workspaceId, id, principal);
@@ -108,6 +113,19 @@ export class JobWorkerHost {
             }
         }
     }
+    async followOwner(workspaceId, id, principal) {
+        for (;;) {
+            const record = await this.jobs.get(workspaceId, id, principal);
+            if (['completed', 'failed', 'cancelled'].includes(record.status))
+                return record;
+            const liveness = record.owner === undefined ? 'dead' : jobOwnerLiveness(record.owner);
+            if (liveness !== 'alive')
+                throw new ServiceError(liveness === 'unknown' ? 'JOB_OWNER_UNRESOLVED' : 'JOB_WORKER_EXIT', liveness === 'unknown'
+                    ? 'The replacement execution owner cannot be verified on this host'
+                    : 'The replacement worker stopped without publishing a terminal job outcome');
+            await delay(100);
+        }
+    }
     async launch(workspaceId, id, lease, principal) {
         // Resolve the same configured workspace and grants again immediately before dispatch.
         await this.jobs.get(workspaceId, id, principal);

package/dist/hoi4_agent_tools/core/operation-result.js

@@ -114,6 +114,9 @@ function boundedResult(result, actualBytes) {
             : 'Tool output exceeded the wire budget; nonessential inline details were omitted',
         details: { actualBytes, maxBytes: MAX_TOOL_RESULT_BYTES },
     };
+    const compactData = result.data !== null && typeof result.data === 'object' && !Array.isArray(result.data)
+        ? result.data
+        : {};
     return {
         status: result.status,
         code: result.code.slice(0, 256),
@@ -141,7 +144,7 @@ function boundedResult(result, actualBytes) {
                     },
                 },
             ],
-        data: {},
+        data: jsonBytesWithin(compactData, 2_048) ? compactData : {},
     };
 }
 function jsonStringBytes(value) {

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/operations.js

@@ -37,21 +37,27 @@ export function eventGraphCounts(graph, artifacts) {
 }
 export function eventGraphValidation(graph) {
     const counts = eventGraphCounts(graph, 0);
+    const analysisBoundaryPassed = graph.complete || (graph.analysisMode === 'focused' && graph.skippedSourceCount === 0);
+    const passed = analysisBoundaryPassed && counts.blockingDiagnostics === 0;
     return {
-        passed: graph.complete && counts.blockingDiagnostics === 0,
+        passed,
         checks: [
             {
                 id: 'event-analysis',
-                passed: graph.complete && counts.blockingDiagnostics === 0,
-                message: graph.analysisMode === 'focused'
-                    ? 'Large workspace analysis deferred workspace-wide helper projections and lifecycle passes; direct evidence is linked'
+                passed,
+                message: counts.blockingDiagnostics > 0
+                    ? `${counts.blockingDiagnostics} blocking event-chain diagnostics; full evidence is linked`
                     : graph.complete
-                        ? `${counts.blockingDiagnostics} blocking event-chain diagnostics; full evidence is linked`
-                        : graph.issues.some(({ code }) => code === 'EVENT_HELPER_DEPTH_LIMIT' ||
-                            code === 'EVENT_HELPER_PROJECTION_LIMIT' ||
-                            code === 'EVENT_HELPER_STATE_PROJECTION_LIMIT')
-                            ? 'Helper expansion reached a depth or materialization boundary; helper_expansion mode provides bounded source-linked continuation'
-                            : `${graph.skippedSourceCount} event-analysis source(s) were skipped; full evidence is linked`,
+                        ? 'The event-chain analysis is complete and has no blocking diagnostics'
+                        : graph.analysisMode === 'focused' && graph.skippedSourceCount === 0
+                            ? 'Whole-workspace helper projections and lifecycle passes were deferred; the requested event analysis retains direct source evidence'
+                            : graph.analysisMode === 'focused'
+                                ? `${graph.skippedSourceCount} event-analysis source(s) were skipped; linked evidence records the partial boundary`
+                                : graph.issues.some(({ code }) => code === 'EVENT_HELPER_DEPTH_LIMIT' ||
+                                    code === 'EVENT_HELPER_PROJECTION_LIMIT' ||
+                                    code === 'EVENT_HELPER_STATE_PROJECTION_LIMIT')
+                                    ? 'Helper expansion reached a depth or materialization boundary; helper_expansion mode provides bounded source-linked continuation'
+                                    : `${graph.skippedSourceCount} event-analysis source(s) were skipped; full evidence is linked`,
             },
         ],
     };

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) {