hoi4-agent-tools 4.1.0 → 4.3.0

package/dist/hoi4_agent_tools/event/summary.js

@@ -0,0 +1,130 @@
+import { compareCodeUnits } from '../core/canonical.js';
+/** Findings returned inline, before an agent opens the linked report. */
+export const EVENT_INLINE_FINDINGS = 10;
+const EVENT_INLINE_CODES = 10;
+const EVENT_INLINE_EVENT_IDS = 20;
+const EVENT_INLINE_MESSAGE_LENGTH = 300;
+const CLASSIFICATION_ORDER = {
+    confirmed_error: 0,
+    probable_defect: 1,
+    design_warning: 2,
+    unresolved_analysis: 3,
+};
+const CONFIDENCE_ORDER = {
+    confirmed: 0,
+    high: 1,
+    medium: 2,
+    low: 3,
+    unresolved: 4,
+};
+function countBy(values, key) {
+    const counts = new Map();
+    for (const value of values)
+        counts.set(key(value), (counts.get(key(value)) ?? 0) + 1);
+    return Object.fromEntries([...counts].sort(([left], [right]) => compareCodeUnits(left, right)));
+}
+function layer(issue) {
+    const path = issue.location?.path;
+    return path === undefined ? 'unknown' : (/^([a-z]+):/u.exec(path)?.[1] ?? 'unknown');
+}
+/** The mod's own files first, then most severe: classification, confidence, source order. */
+function issueOrder(left, right) {
+    const leftMod = layer(left) === 'mod' ? 0 : 1;
+    const rightMod = layer(right) === 'mod' ? 0 : 1;
+    return (leftMod - rightMod ||
+        CLASSIFICATION_ORDER[left.classification] - CLASSIFICATION_ORDER[right.classification] ||
+        CONFIDENCE_ORDER[left.confidence] - CONFIDENCE_ORDER[right.confidence] ||
+        compareCodeUnits(left.location?.path ?? '', right.location?.path ?? '') ||
+        (left.location?.start.line ?? 0) - (right.location?.start.line ?? 0) ||
+        compareCodeUnits(left.code, right.code) ||
+        compareCodeUnits(left.message, right.message));
+}
+/** Counts and the most severe findings of a selection, small enough to return inline. */
+export function summarizeEventIssues(issues) {
+    const byCode = Object.entries(countBy(issues, ({ code }) => code))
+        .sort(([leftCode, left], [rightCode, right]) => right - left || compareCodeUnits(leftCode, rightCode))
+        .slice(0, EVENT_INLINE_CODES);
+    return {
+        issues: issues.length,
+        byClassification: countBy(issues, ({ classification }) => classification),
+        // `mod` findings are the workspace's own; `game` and `dependency` ones are context.
+        byLayer: countBy(issues, layer),
+        topCodes: Object.fromEntries(byCode),
+        findings: [...issues]
+            .sort(issueOrder)
+            .slice(0, EVENT_INLINE_FINDINGS)
+            .map((issue) => ({
+            code: issue.code,
+            classification: issue.classification,
+            confidence: issue.confidence,
+            message: issue.message.length > EVENT_INLINE_MESSAGE_LENGTH
+                ? `${issue.message.slice(0, EVENT_INLINE_MESSAGE_LENGTH - 1)}…`
+                : issue.message,
+            ...(issue.location === undefined
+                ? {}
+                : { path: issue.location.path, line: issue.location.start.line }),
+            ...(typeof issue.details.name === 'string' ? { subject: issue.details.name } : {}),
+        })),
+    };
+}
+/** Size of a traced chain and the events it reaches. */
+export function summarizeEventTrace(trace) {
+    const events = trace.nodes
+        .flatMap(({ kind, eventId }) => (kind === 'event' && eventId !== undefined ? [eventId] : []))
+        .sort(compareCodeUnits);
+    return {
+        nodes: trace.nodes.length,
+        edges: trace.edges.length,
+        events: events.length,
+        eventIds: events.slice(0, EVENT_INLINE_EVENT_IDS),
+        boundaryNodes: trace.boundaryNodeIds.length,
+        truncated: trace.truncated,
+    };
+}
+/** How many chains start where, in a form an agent can read without the report. */
+export function summarizeEventRoots(roots) {
+    const nodeLayer = ({ sourcePath }) => sourcePath === undefined ? 'unknown' : (/^([a-z]+):/u.exec(sourcePath)?.[1] ?? 'unknown');
+    // The mod's own events first: vanilla callerless events are context, not the mod's defects.
+    const ids = (nodes) => [...nodes]
+        .sort((left, right) => (nodeLayer(left) === 'mod' ? 0 : 1) - (nodeLayer(right) === 'mod' ? 0 : 1) ||
+        compareCodeUnits(left.eventId ?? '', right.eventId ?? ''))
+        .flatMap(({ eventId }) => (eventId === undefined ? [] : [eventId]))
+        .slice(0, EVENT_INLINE_EVENT_IDS);
+    return {
+        entryPoints: roots.entryPoints.length,
+        entryKinds: countBy(roots.entryPoints, ({ metadata }) => typeof metadata.entryKind === 'string' ? metadata.entryKind : 'unknown'),
+        automaticEvents: roots.automaticEvents.length,
+        callerlessTriggeredEvents: roots.callerlessTriggeredEvents.length,
+        callerlessTriggeredByLayer: countBy(roots.callerlessTriggeredEvents, nodeLayer),
+        callerlessTriggeredEventIds: ids(roots.callerlessTriggeredEvents),
+        cycles: roots.stronglyConnectedComponents.filter(({ cyclic }) => cyclic).length,
+    };
+}
+/** Whether a route exists and, if so, the events it passes through in order. */
+export function summarizeEventPath(path) {
+    return {
+        found: path.found,
+        steps: path.steps.length,
+        eventIds: path.steps
+            .flatMap(({ node }) => node.kind === 'event' && node.eventId !== undefined ? [node.eventId] : [])
+            .slice(0, EVENT_INLINE_EVENT_IDS),
+        ...(path.failureReason === undefined ? {} : { failureReason: path.failureReason }),
+        ...(path.failureMessage === undefined ? {} : { failureMessage: path.failureMessage }),
+        unresolvedAssumptions: path.unresolvedAssumptions.length,
+    };
+}
+/** How far a change to the subject reaches, by count. */
+export function summarizeEventImpact(impact) {
+    return {
+        direct: impact.directNodeIds.length,
+        upstream: impact.upstreamNodeIds.length,
+        downstream: impact.downstreamNodeIds.length,
+        stateAccesses: impact.stateAccessIds.length,
+        affectedRoots: impact.affectedRootIds.length,
+        affectedTerminals: impact.affectedTerminalIds.length,
+        wouldDisconnect: impact.wouldDisconnectNodeIds.length,
+        wouldDisconnectTerminals: impact.wouldDisconnectTerminalIds.length,
+        unresolved: impact.unresolvedNodeIds.length,
+        sampleDownstream: impact.downstreamNodeIds.slice(0, EVENT_INLINE_EVENT_IDS),
+    };
+}

package/dist/hoi4_agent_tools/focus/importer.js

@@ -135,9 +135,9 @@ function isFormableDecision(target, options) {
         return false;
     return /(?:^form_|formable|form_country)/iu.test(target);
 }
-function isEffectContainer(key) {
+function isEffectContainer(key, nativeEffects) {
     return (effectContainerKeys.has(key) ||
-        (nativeFocusEffectKeys.has(key) &&
+        ((nativeFocusEffectKeys.has(key) || nativeEffects?.has(key) === true) &&
             /^(?:(?:global_)?every|ordered|random)_[a-z0-9_]+$/u.test(key)));
 }
 function isScopeKey(key, knownLeaders) {
@@ -342,6 +342,7 @@ function referenceLinks(document, block, options) {
     const links = [];
     const knownHelpers = catalogValues(options, 'helper');
     const knownLeaders = catalogValues(options, 'leader');
+    const isNative = (key) => nativeFocusEffectKeys.has(key) || options.nativeEffects?.has(key) === true;
     function recordReference(assignment, specification) {
         for (const target of referenceTargets(assignment, specification)) {
             const kind = specification.kind === 'decision' && isFormableDecision(target, options)
@@ -364,7 +365,8 @@ function referenceLinks(document, block, options) {
             recordReference(assignment, reference);
             if (assignment.value.type === 'block') {
                 for (const nested of assignments(assignment.value)) {
-                    if (nested.value.type === 'block' && isEffectContainer(nested.key.value.toLowerCase())) {
+                    if (nested.value.type === 'block' &&
+                        isEffectContainer(nested.key.value.toLowerCase(), options.nativeEffects)) {
                         effectAssignment(nested, new Set());
                     }
                 }
@@ -373,7 +375,7 @@ function referenceLinks(document, block, options) {
         }
         if (knownHelpers.has(key) &&
             !effectContainerKeys.has(normalizedKey) &&
-            !nativeFocusEffectKeys.has(normalizedKey)) {
+            !isNative(normalizedKey)) {
             links.push({
                 kind: 'helper',
                 target: key,
@@ -381,7 +383,7 @@ function referenceLinks(document, block, options) {
             });
             return;
         }
-        if (isEffectContainer(normalizedKey)) {
+        if (isEffectContainer(normalizedKey, options.nativeEffects)) {
             if (assignment.value.type !== 'block')
                 return;
             if (normalizedKey === 'random_list') {
@@ -397,7 +399,7 @@ function referenceLinks(document, block, options) {
             }
             return;
         }
-        if (nativeFocusEffectKeys.has(normalizedKey))
+        if (isNative(normalizedKey))
             return;
         if (assignment.value.type === 'block' && isScopeKey(key, knownLeaders)) {
             effectWalk(assignment.value, new Set());

package/dist/hoi4_agent_tools/focus/native-effects.js

@@ -2,7 +2,9 @@
  * Native effect identifiers used to distinguish direct scripted-effect calls
  * from engine effects while importing focus completion rewards.
  *
- * Source: the official HOI4 1.19.2 effects documentation reviewed 2026-07-10.
+ * Source: the official HOI4 1.19.2 effects documentation reviewed 2026-07-10. This is the
+ * fallback list; analysis also accepts every effect the installed game documents in
+ * documentation/effects_documentation.md, so effects added by later patches are recognized.
  * Keep this list synchronized during compatibility reviews.
  */
 export const nativeEffectKeys = new Set([

package/dist/hoi4_agent_tools/focus/tool-support.js

@@ -40,7 +40,7 @@ export function activeSidecar(snapshot, focusFile) {
 }
 export function importFocusFile(snapshot, file, palettes) {
     const document = parseClausewitz(file.bytes, file.displayPath);
-    const imported = importFocusTrees(document, { references: referenceCatalog(snapshot) });
+    const imported = importFocusTrees(document, focusImportOptions(snapshot));
     const sidecar = activeSidecar(snapshot, file);
     imported.plans = imported.plans.map((plan) => {
         const enriched = sidecar === undefined
@@ -89,6 +89,15 @@ export function selectContinuousPlan(result, paletteId) {
         throw new ServiceError('CONTINUOUS_FOCUS_PALETTE_NOT_FOUND', `Continuous focus palette was not found: ${paletteId}`);
     return plan;
 }
+/** Import options from a scan: its reference catalog and the installed game's documented effects. */
+export function focusImportOptions(snapshot) {
+    return {
+        references: referenceCatalog(snapshot),
+        ...(snapshot.documentedEffects === undefined
+            ? {}
+            : { nativeEffects: snapshot.documentedEffects.names }),
+    };
+}
 export function referenceCatalog(snapshot) {
     const identifiers = (kind) => [
         ...new Set(snapshot.index

package/dist/hoi4_agent_tools/impact/service.js

@@ -94,6 +94,8 @@ export class ImpactAnalyzer {
             directConsumers: graph.directConsumers.length,
             transitiveConsumers: graph.transitiveConsumers.length,
             affectedFiles: graph.affectedFiles.length,
+            // Affected files are evidence, not writes: this read-only analysis never changes a file.
+            affectedFilePaths: graph.affectedFiles.slice(0, 64),
             cycles: graph.cycles.length,
             scenarioSuites: scenarioSuites.scannedSuites,
             affectedCases: scenarioSuites.matches.length,
@@ -108,7 +110,6 @@ export class ImpactAnalyzer {
         result.code = complete ? 'IMPACT_ANALYZED' : 'IMPACT_ANALYZED_PARTIAL';
         result.artifacts = [publicArtifactLink(artifact)];
         result.proposedFiles = overlay?.changes.map(({ path }) => path).slice(0, 64) ?? [];
-        result.changedFiles = graph.affectedFiles.slice(0, 64);
         setInlineFilesScanned(result, before.files.map(({ displayPath }) => displayPath));
         result.validation = {
             passed: complete,

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

@@ -16,6 +16,7 @@ const impactOutputSchema = strictOperationResultSchema(z
     directConsumers: nonNegativeIntegerSchema,
     transitiveConsumers: nonNegativeIntegerSchema,
     affectedFiles: nonNegativeIntegerSchema,
+    affectedFilePaths: z.array(z.string().max(1024)).max(64).optional(),
     cycles: nonNegativeIntegerSchema,
     scenarioSuites: nonNegativeIntegerSchema,
     affectedCases: nonNegativeIntegerSchema,

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

@@ -70,6 +70,70 @@ const renderHashSchema = z
     html: sha256Schema.optional(),
 })
     .strict();
+const countMapSchema = z.record(z.string().max(256), nonNegativeIntegerSchema);
+const inlineIdsSchema = z.array(z.string().max(256)).max(20);
+/** Bounded inline answer of an inspection; see docs/events.md. */
+const eventInspectSummarySchema = z
+    .object({
+    issues: nonNegativeIntegerSchema.optional(),
+    byClassification: countMapSchema.optional(),
+    byLayer: countMapSchema.optional(),
+    topCodes: countMapSchema.optional(),
+    findings: z
+        .array(z
+        .object({
+        code: z.string().max(256),
+        classification: z.enum([
+            'confirmed_error',
+            'probable_defect',
+            'design_warning',
+            'unresolved_analysis',
+        ]),
+        confidence: z.enum(['confirmed', 'high', 'medium', 'low', 'unresolved']),
+        message: z.string().max(300),
+        path: z.string().max(1024).optional(),
+        line: nonNegativeIntegerSchema.optional(),
+        subject: z.string().max(1024).optional(),
+    })
+        .strict())
+        .max(10)
+        .optional(),
+    trace: z
+        .object({
+        nodes: nonNegativeIntegerSchema,
+        edges: nonNegativeIntegerSchema,
+        events: nonNegativeIntegerSchema,
+        eventIds: inlineIdsSchema,
+        boundaryNodes: nonNegativeIntegerSchema,
+        truncated: z.boolean(),
+    })
+        .strict()
+        .optional(),
+    entryPoints: nonNegativeIntegerSchema.optional(),
+    entryKinds: countMapSchema.optional(),
+    automaticEvents: nonNegativeIntegerSchema.optional(),
+    callerlessTriggeredEvents: nonNegativeIntegerSchema.optional(),
+    callerlessTriggeredByLayer: countMapSchema.optional(),
+    callerlessTriggeredEventIds: inlineIdsSchema.optional(),
+    cycles: nonNegativeIntegerSchema.optional(),
+    found: z.boolean().optional(),
+    steps: nonNegativeIntegerSchema.optional(),
+    eventIds: inlineIdsSchema.optional(),
+    failureReason: z.string().max(64).optional(),
+    failureMessage: z.string().max(1024).optional(),
+    unresolvedAssumptions: nonNegativeIntegerSchema.optional(),
+    direct: nonNegativeIntegerSchema.optional(),
+    upstream: nonNegativeIntegerSchema.optional(),
+    downstream: nonNegativeIntegerSchema.optional(),
+    stateAccesses: nonNegativeIntegerSchema.optional(),
+    affectedRoots: nonNegativeIntegerSchema.optional(),
+    affectedTerminals: nonNegativeIntegerSchema.optional(),
+    wouldDisconnect: nonNegativeIntegerSchema.optional(),
+    wouldDisconnectTerminals: nonNegativeIntegerSchema.optional(),
+    unresolved: nonNegativeIntegerSchema.optional(),
+    sampleDownstream: z.array(z.string().max(1024)).max(20).optional(),
+})
+    .strict();
 const eventInspectDataSchema = z
     .object({
     mode: eventInspectModeSchema,
@@ -78,6 +142,7 @@ const eventInspectDataSchema = z
     graphHash: sha256Schema,
     counts: eventGraphCountsSchema,
     helperExpansion: helperExpansionSummarySchema.optional(),
+    summary: eventInspectSummarySchema.optional(),
     boundary: inspectBoundarySchema,
 })
     .strict();
@@ -93,6 +158,7 @@ const eventRenderOutputSchema = strictOperationResultSchema(z
         selectedNodes: nonNegativeIntegerSchema,
         omittedNodes: nonNegativeIntegerSchema,
         branchRenders: nonNegativeIntegerSchema,
+        omittedBranchRenders: nonNegativeIntegerSchema,
     }),
     boundary: z
         .object({

package/dist/hoi4_agent_tools/probability/service.js

@@ -775,39 +775,39 @@ export class ProbabilityAnalyzer {
         if (adapter === 'custom_weighted_pool' || workspace.gameRoot === undefined)
             return { status: 'adapter_target_only', adapterTarget: VERIFIED_GAME_VERSION };
         const sourcePath = path.join(workspace.gameRoot, 'launcher-settings.json');
+        const unknown = (reason) => ({
+            status: 'version_unknown',
+            adapterTarget: VERIFIED_GAME_VERSION,
+            sourcePath,
+            reason,
+        });
         let parsed;
         try {
             parsed = JSON.parse(await readFile(sourcePath, 'utf8'));
         }
         catch (error) {
-            throw new ServiceError('PROBABILITY_GAME_VERSION_UNVERIFIED', 'The configured game version could not be verified from launcher-settings.json', { sourcePath, reason: error instanceof Error ? error.message : String(error) });
+            return unknown(error instanceof Error ? error.message : String(error));
         }
         if (typeof parsed !== 'object' || parsed === null)
-            throw new ServiceError('PROBABILITY_GAME_VERSION_UNVERIFIED', 'The configured launcher-settings.json does not contain a version object', { sourcePath });
+            return unknown('launcher-settings.json does not contain a version object');
         const settings = parsed;
         const observedVersion = typeof settings.version === 'string' ? settings.version : undefined;
         const observedRawVersion = typeof settings.rawVersion === 'string' ? settings.rawVersion : undefined;
-        const observedChecksum = observedVersion?.match(/\(([a-z0-9]+)\)\s*$/iu)?.[1];
-        if (observedVersion === undefined ||
-            observedRawVersion === undefined ||
-            observedChecksum === undefined)
-            throw new ServiceError('PROBABILITY_GAME_VERSION_UNVERIFIED', 'The configured launcher-settings.json is missing version, rawVersion, or checksum data', { sourcePath, observedVersion, observedRawVersion, observedChecksum });
-        if (observedRawVersion !== VERIFIED_GAME_RAW_VERSION ||
-            observedChecksum.toLowerCase() !== VERIFIED_GAME_CHECKSUM)
-            throw new ServiceError('PROBABILITY_GAME_VERSION_UNSUPPORTED', `Probability adapters are verified for ${VERIFIED_GAME_VERSION}, not the configured game version`, {
-                sourcePath,
-                observedVersion,
-                observedRawVersion,
-                observedChecksum,
-                adapterTarget: VERIFIED_GAME_VERSION,
-            });
+        const observedChecksum = observedVersion?.match(/\(([a-z0-9]+)\)\s*$/iu)?.[1]?.toLowerCase();
+        if (observedVersion === undefined || observedRawVersion === undefined)
+            return unknown('launcher-settings.json is missing version or rawVersion');
+        // Any installed version is analyzed with the documented rules; the observed identity is
+        // recorded so a result can be traced to the game it describes.
         return {
-            status: 'workspace_verified',
+            status: observedRawVersion === VERIFIED_GAME_RAW_VERSION &&
+                observedChecksum === VERIFIED_GAME_CHECKSUM
+                ? 'workspace_verified'
+                : 'workspace_observed',
             adapterTarget: VERIFIED_GAME_VERSION,
             sourcePath,
             observedVersion,
             observedRawVersion,
-            observedChecksum: observedChecksum.toLowerCase(),
+            ...(observedChecksum === undefined ? {} : { observedChecksum }),
         };
     }
     metadata(context, snapshot, surface, scenarioSet, candidatePool, gameVersionVerification, extra = {}) {

package/dist/hoi4_agent_tools/reference/source-lookup.js

@@ -1,7 +1,7 @@
 import { ServiceError } from '../core/result.js';
 import { decodeSource } from '../core/source/encoding.js';
 import { readBoundedJsonLines } from './lines.js';
-import { scanImpactSemanticReferences } from '../core/impact-semantic.js';
+import { IMPACT_SEMANTIC_MAX_REFERENCES, scanImpactSemanticReferences, } from '../core/impact-semantic.js';
 import { parseClausewitz } from '../core/source/parser.js';
 import { navigateSource } from './source-navigation.js';
 import { locatePatterns, locateSource } from './source-locate.js';
@@ -126,7 +126,9 @@ export async function sourceLookup(engine, workspaceId, input, principal, signal
     });
     let semantic = input.includeReferences ? semanticCache.get(snapshot) : undefined;
     if (input.includeReferences && semantic === undefined) {
-        semantic = scanImpactSemanticReferences(snapshot, 200_000, { includeOnActions: true });
+        semantic = scanImpactSemanticReferences(snapshot, IMPACT_SEMANTIC_MAX_REFERENCES, {
+            includeOnActions: true,
+        });
         semanticCache.set(snapshot, semantic);
     }
     const referenceIdentities = new Set();

package/dist/hoi4_agent_tools/schemas/probability.js

@@ -770,7 +770,13 @@ const probabilityMetadataSchema = z
     gameVersion: z.string(),
     gameVersionVerification: z
         .object({
-        status: z.enum(['workspace_verified', 'adapter_target_only']),
+        status: z.enum([
+            'workspace_verified',
+            'workspace_observed',
+            'version_unknown',
+            'adapter_target_only',
+        ]),
+        reason: z.string().max(1024).optional(),
         adapterTarget: z.string(),
         sourcePath: z.string().optional(),
         observedVersion: z.string().optional(),

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

package/docs/analysis.md

@@ -58,6 +58,8 @@ Malformed, missing, or oversized suite files produce explicit partial coverage.
 The graph includes active and overridden definitions, direct and transitive consumers, source locations, state-key reads and writes, and coverage limits.
 It connects source-backed event, focus, decision, idea, technology, scripted-helper, localisation, GUI, sprite, and texture references where a typed static edge can be established.
 Unresolved dynamic names, missing definitions, skipped sources, cycles, and traversal limits remain explicit in the report.
+A dynamic reference counts against completeness only when it names a symbol kind the traversal reaches, so `activate_decision = event_target:choice` affects the impact of a decision but not of an idea that no decision consumes.
+`data.affectedFilePaths` lists up to 64 affected files; the result's `changedFiles` stays empty because the analysis never writes.
 An affected file is a source dependency lead, not a claim that the game executed that path.
 
 ## Decisions and missions
@@ -99,6 +101,8 @@ The inventory lists active decisions, category fragments, overridden source defi
 Category and decision `allowed`, `visible`, and `available` results remain separate; mission visibility is reported as ignored where documented.
 Target selection covers explicit lists and arrays plus supported state ownership, control, and continent filters.
 When a target, flag, variable, or helper input is unknown, the corresponding gate remains unresolved.
+This includes `has_variable` and `has_event_target`: an undeclared variable or event target is unknown, not absent, unless the scenario sets `closedFlags: true`.
+AI weights use the probability adapters, which run on any installed game version and record the observed build in their evidence.
 
 Costs distinguish automatic engine political-power payment from a custom affordability trigger and its separate `complete_effect` payment.
 The report identifies direct deductions, possible double payment, missing direct payment, conditional or helper-dependent paths, repeatability, cooldowns, removal, activation, cancellation, and mission timeout paths.

package/docs/events.md

@@ -26,6 +26,18 @@ For a large helper closure, use [bounded helper expansion](helper-expansion.md)
 
 The compact response summarizes the result. Small scan resources contain the complete graph; large scan resources contain exact totals, grouped inventories, representative diagnostics, and the revision needed for focused follow-up queries. Large focused scans keep direct event and on-action evidence, call sites, state accesses, and source locations while leaving helper expansion and workspace-wide lifecycle analysis explicit as deferred boundaries. This keeps an agent's prompt and artifact storage bounded without allowing a broad scan to exhaust the MCP process.
 
+`data.summary` answers the request inline before the linked report is opened. `scan`, `lint` and `state_flow` return the number of findings in the selection, counts by classification, the ten most frequent codes and the ten most severe findings with their path, line and subject. `trace` adds the traced node, edge and event counts with up to twenty event IDs. `roots` returns entry-point counts by kind, automatic and callerless triggered events, and cycle counts. `data.counts` still describes the whole analyzed graph, including vanilla events.
+
+`explain_path` adds whether a route was found, its step count, event IDs and failure reason; `impact` adds direct, upstream, downstream, affected-root and disconnection counts.
+
+Workspace-wide modes expand scripted helpers up to a fixed work ceiling. On a very large mod the expansion stops there with an `EVENT_HELPER_PROJECTION_LIMIT` finding that names the completed and total roots; calls from the remaining roots stay structural, and a namespace, event or file selector or `helper_expansion` mode covers them. An unselected overview render returns the overview and as many branch renders as the request's raster budget allows, reporting the rest in `omittedBranchRenders`.
+
+A `scan` retains the complete graph as a snapshot artifact only up to 128 MiB of canonical JSON. A larger graph, such as a mod with thousands of events and hundreds of thousands of state accesses, returns the scan report with the info diagnostic `EVENT_GRAPH_SNAPSHOT_OMITTED`; comparisons then use the revisions this server holds in memory.
+
+An assignment such as `custom_effect = yes` is reported as a missing helper only where it can execute: in effect blocks of events, decisions, focuses and on-actions, inside scope and loop effects, and in conventionally named effect blocks (`on_*`, `*_effect`, `*_effects`) of other definition files. Arguments of native effects such as `add_building_construction = { instant_build = yes }`, condition blocks such as `visible`, `available`, `allowed`, `ai_will_do`, `NOT` or `any_*`, and data fields of ideas, raids, special projects and scripted GUIs are not calls.
+
+A read is linked to a writer of the same name when the writer is a temporary variable, a write inside a scripted helper (whose scope is decided by its caller), a scope-prefixed name such as `GER.value`, or the array behind `entries^num`. `event_target:name` reads targets saved by `save_event_target_as` and `save_global_event_target_as`; `global_event_target:name` reads only global targets. A finding is kept per owner and subject, so different flags or targets read in one event remain separate findings.
+
 Selectors use one of these forms:
 
 ```json

package/docs/probability.md

@@ -12,7 +12,7 @@ Use them for event timing and option weights, decision and mission scores, focus
 
 ## Game version
 
-When `gameRoot` is configured, `launcher-settings.json` must identify the supported HOI4 build and checksum for evaluation to run. Without a game root, results identify the adapter version. Proposed source is evaluated in memory.
+The adapters apply the documented weighting rules of `ai_will_do`, `ai_chance`, mean time to happen, `random_list` and AI strategies, which are the same in every game version, so evaluation runs on whatever HOI4 version is installed. When `gameRoot` is configured, `metadata.gameVersionVerification` records the build read from `launcher-settings.json`: `workspace_verified` for the build the adapters were last reviewed against, `workspace_observed` for any other build, and `version_unknown` with a `reason` when the file cannot be read. Without a game root, results identify the adapter version (`adapter_target_only`). Proposed source is evaluated in memory.
 
 ## One call for current weights
 

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "hoi4-agent-tools",
-  "version": "4.1.0",
+  "version": "4.3.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "hoi4-agent-tools",
-      "version": "4.1.0",
+      "version": "4.3.0",
       "license": "Apache-2.0",
       "dependencies": {
         "@fontsource-variable/roboto": "5.3.0",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hoi4-agent-tools",
   "mcpName": "io.github.klimPaskov/hoi4-agent-tools",
-  "version": "4.1.0",
+  "version": "4.3.0",
   "description": "Build HOI4 mods: focus trees, events, decisions, worlds, GUI previews, docs and AI balance.",
   "type": "module",
   "license": "Apache-2.0",

package/schemas/configuration.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.1.0/schemas/configuration.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.3.0/schemas/configuration.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

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

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.1.0/schemas/continuous-focus-palette.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.3.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/v4.1.0/schemas/custom-weighted-pool.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.3.0/schemas/custom-weighted-pool.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/decision-inspect-input.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.1.0/schemas/decision-inspect-input.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.3.0/schemas/decision-inspect-input.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/error-log-input.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.1.0/schemas/error-log-input.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.3.0/schemas/error-log-input.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/v4.1.0/schemas/event-feature-manifest.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.3.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/v4.1.0/schemas/focus-plan.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.3.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/v4.1.0/schemas/focus-planning-sidecar.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.3.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/v4.1.0/schemas/gui-animation-source.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.3.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/v4.1.0/schemas/gui-helper.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.3.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/v4.1.0/schemas/gui-scenario.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.3.0/schemas/gui-scenario.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/helper-expansion-request.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.1.0/schemas/helper-expansion-request.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.3.0/schemas/helper-expansion-request.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/helper-expansion-summary.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.1.0/schemas/helper-expansion-summary.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.3.0/schemas/helper-expansion-summary.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {