hoi4-agent-tools 2.2.0 → 2.3.3

package/dist/hoi4_agent_tools/technology/graph.js

@@ -315,9 +315,30 @@ function stronglyConnectedComponents(nodeIds, edges, signal) {
     }
     return components.sort((left, right) => compareCodeUnits(left[0] ?? '', right[0] ?? ''));
 }
-function expandHelperReferences(references, calls, unresolved, signal) {
+function expandHelperReferences(references, calls, unresolved, analysisMode, signal) {
     const direct = references.filter(({ sourceKind }) => sourceKind === 'scripted_effect');
     const publicReferences = references.filter(({ sourceKind }) => sourceKind !== 'scripted_effect');
+    if (analysisMode === 'focused') {
+        if (calls.length > 0) {
+            unresolved.push({
+                id: 'tech-unresolved-helper-expansion-deferred',
+                kind: 'unsupported_construct',
+                expression: 'scripted_effect expansion',
+                confidence: 'unresolved',
+                blockers: [
+                    {
+                        code: 'TECH_HELPER_EXPANSION_DEFERRED',
+                        message: 'Large-workspace technology analysis retains scripted-effect calls and direct references without materialising the full helper projection.',
+                    },
+                ],
+            });
+        }
+        const deduplicated = new Map();
+        for (const reference of [...publicReferences, ...direct])
+            if (!deduplicated.has(reference.id))
+                deduplicated.set(reference.id, reference);
+        return [...deduplicated.values()].sort((left, right) => compareCodeUnits(left.id, right.id));
+    }
     const refsByHelper = new Map();
     for (const reference of direct) {
         const group = refsByHelper.get(reference.sourceId) ?? [];
@@ -1085,7 +1106,7 @@ export function buildTechnologyGraph(snapshot, options) {
     const unlocks = resolveUnlocks(selectOwnedRecords(fragments.flatMap(({ unlocks }) => unlocks), ({ technologyId }) => technologyId, ({ location }) => location, technologyById).sort((left, right) => compareCodeUnits(left.id, right.id)), unlockTargets, snapshot.complete);
     const unresolved = fragments.flatMap(({ unresolved }) => unresolved);
     const helperCalls = fragments.flatMap(({ helperCalls }) => helperCalls);
-    const externalReferences = expandHelperReferences(fragments.flatMap(({ externalReferences }) => externalReferences), helperCalls, unresolved, options.signal);
+    const externalReferences = expandHelperReferences(fragments.flatMap(({ externalReferences }) => externalReferences), helperCalls, unresolved, options.analysisMode ?? 'full', options.signal);
     const issues = diagnose(technologies, folders, placements, gridboxes, edges, categories, doctrineDefinitions, unlocks, externalReferences, selectedTechnologies.duplicates.map((group) => group.map(({ iconSprite, effectSignatureFields, ...technology }) => ({
         ...technology,
         icon: iconStatus(iconSprite, snapshot.index, assets),
@@ -1111,10 +1132,13 @@ export function buildTechnologyGraph(snapshot, options) {
     const graph = {
         schemaVersion: TECHNOLOGY_GRAPH_SCHEMA_VERSION,
         parserVersion: TECHNOLOGY_PARSER_VERSION,
+        analysisMode: options.analysisMode ?? 'full',
         workspaceId: snapshot.workspaceId,
         workspaceIdentity: options.workspaceIdentity,
         revision,
-        complete: snapshot.complete && unresolved.every(({ kind }) => kind !== 'partial_source'),
+        complete: snapshot.complete &&
+            unresolved.every(({ kind }) => kind !== 'partial_source') &&
+            !(options.analysisMode === 'focused' && helperCalls.length > 0),
         analysisBoundary: {
             staticAnalysis: true,
             language: 'l_english',
@@ -1125,6 +1149,9 @@ export function buildTechnologyGraph(snapshot, options) {
                 'meta-generated or variable technology identifiers',
                 'exact AI research choice and runtime research time',
                 'dynamic scripted localisation without supplied runtime values',
+                ...(options.analysisMode === 'focused' && helperCalls.length > 0
+                    ? ['large-workspace scripted-effect helper projections are deferred']
+                    : []),
             ],
             assumptions: [
                 'classic technology paths point from the defining technology to leads_to_tech',

package/dist/hoi4_agent_tools/technology/queries.js

@@ -8,17 +8,42 @@ function requireTechnology(graph, technologyId) {
             technologyId,
         });
 }
-export function technologyScanReport(graph) {
+const TECHNOLOGY_SCAN_FULL_GRAPH_RECORD_LIMIT = 100_000;
+function technologyRecordCount(graph) {
+    return (graph.technologies.length +
+        graph.folders.length +
+        graph.categories.length +
+        graph.placements.length +
+        graph.gridboxes.length +
+        graph.edges.length +
+        graph.unlocks.length +
+        graph.unlockTargets.length +
+        graph.externalReferences.length +
+        graph.helperCalls.length +
+        graph.issues.length +
+        graph.diagnostics.length +
+        graph.unresolved.length +
+        graph.doctrineDefinitions.length);
+}
+function groupedCounts(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)));
+}
+export function technologyScanReport(graph, fullGraphRecordLimit = TECHNOLOGY_SCAN_FULL_GRAPH_RECORD_LIMIT) {
+    const recordCount = technologyRecordCount(graph);
     const classifications = Object.fromEntries(['confirmed_error', 'probable_defect', 'design_warning', 'unresolved_analysis'].map((classification) => [
         classification,
         graph.issues.filter((issue) => issue.classification === classification).length,
     ]));
-    return {
+    const summary = {
         schemaVersion: graph.schemaVersion,
         parserVersion: graph.parserVersion,
         workspaceId: graph.workspaceId,
         workspaceIdentity: graph.workspaceIdentity,
         revision: graph.revision,
+        analysisMode: graph.analysisMode ?? 'full',
         complete: graph.complete,
         statistics: graph.statistics,
         issueClassifications: classifications,
@@ -31,7 +56,49 @@ export function technologyScanReport(graph) {
         analysisBoundary: graph.analysisBoundary,
         issueSamples: graph.issues.slice(0, 100),
         unresolvedSamples: graph.unresolved.slice(0, 100),
-        authoritativeGraphIncluded: true,
+        recordCounts: {
+            technologies: graph.technologies.length,
+            folders: graph.folders.length,
+            categories: graph.categories.length,
+            placements: graph.placements.length,
+            gridboxes: graph.gridboxes.length,
+            edges: graph.edges.length,
+            unlocks: graph.unlocks.length,
+            unlockTargets: graph.unlockTargets.length,
+            externalReferences: graph.externalReferences.length,
+            issues: graph.issues.length,
+            diagnostics: graph.diagnostics.length,
+            unresolved: graph.unresolved.length,
+            doctrineDefinitions: graph.doctrineDefinitions.length,
+        },
+    };
+    if (recordCount <= fullGraphRecordLimit) {
+        return {
+            ...summary,
+            authoritativeGraphIncluded: true,
+            graph,
+        };
+    }
+    return {
+        ...summary,
+        authoritativeGraphIncluded: false,
+        graphSummary: {
+            revision: graph.revision,
+            recordCounts: summary.recordCounts,
+            technologyKinds: groupedCounts(graph.technologies, ({ kind }) => kind),
+            edgeKinds: groupedCounts(graph.edges, ({ kind }) => kind),
+            issueCodes: groupedCounts(graph.issues, ({ code }) => code),
+            issueSeverities: groupedCounts(graph.issues, ({ severity }) => severity),
+            diagnosticCodes: groupedCounts(graph.diagnostics, ({ code }) => code),
+            diagnosticSeverities: groupedCounts(graph.diagnostics, ({ severity }) => severity),
+        },
+        diagnosticSamples: graph.diagnostics.slice(0, 100),
+        artifactProjection: {
+            mode: 'large-scan-summary',
+            fullGraphRecordCount: recordCount,
+            fullGraphRecordLimit,
+            detailQueries: ['folders', 'trace', 'explain', 'unlocks', 'bonus_coverage', 'lint', 'impact'],
+        },
     };
 }
 export function discoverTechnologyFolders(graph, folderId) {

package/dist/hoi4_agent_tools/technology/service.js

@@ -18,6 +18,7 @@ const GRAPH_ARTIFACT_BYTES = 134_217_728;
 const GRAPH_ARTIFACT_CHUNKS = 2_048;
 const HISTORY_ENTRIES = 12;
 const FOCUSED_RENDER_LIMIT = 32;
+const FOCUSED_GRAPH_FILE_THRESHOLD = 1_000;
 class BoundedTechnologyFragmentCache {
     #values = new Map();
     #bytes = 0;
@@ -58,6 +59,36 @@ function sharedState(engine) {
     }
     return state;
 }
+function technologyScanPatterns(workspace) {
+    const roots = workspace.registration.roots;
+    const under = (values, glob) => values.map((root) => `${root.replaceAll('\\', '/').replace(/\/$/u, '')}/${glob}`);
+    return [
+        'common/technologies/**/*.txt',
+        'common/technology_tags/**/*.txt',
+        'common/technology_sharing/**/*.txt',
+        'common/doctrines/**/*.txt',
+        'common/units/**/*.txt',
+        'common/buildings/**/*.txt',
+        'common/abilities/**/*.txt',
+        'common/decisions/**/*.txt',
+        'common/scripted_effects/**/*.txt',
+        'common/on_actions/**/*.txt',
+        'common/ideas/**/*.txt',
+        'common/characters/**/*.txt',
+        'common/combat_tactics.txt',
+        'events/**/*.txt',
+        'history/countries/**/*.txt',
+        ...under(roots.focus, '**/*.txt'),
+        ...under(roots.interface, '**/*.gui'),
+        ...under(roots.localisation, 'english/**/*.{yml,yaml}'),
+        ...under(roots.localisation, '*.{yml,yaml}'),
+    ].sort(compareCodeUnits);
+}
+function technologyAnalysisMode(workspace, snapshot) {
+    return workspace.gameRoot !== undefined || snapshot.files.length > FOCUSED_GRAPH_FILE_THRESHOLD
+        ? 'focused'
+        : 'full';
+}
 function rememberGraph(state, graph) {
     const history = state.history.get(graph.workspaceId) ?? new Map();
     history.delete(graph.revision);
@@ -79,6 +110,7 @@ function safeSlug(value) {
 function graphHash(graph) {
     return hashCanonical({
         schemaVersion: graph.schemaVersion,
+        analysisMode: graph.analysisMode ?? 'full',
         workspaceIdentity: graph.workspaceIdentity,
         revision: graph.revision,
         statistics: graph.statistics,
@@ -322,10 +354,12 @@ export class TechnologyTreeViewer {
         const cached = this.#state.current.get(workspaceId);
         if (options.refresh !== true && cached?.generation === generation)
             return cached.graph;
-        const snapshot = await this.engine.scan(workspaceId, {}, options.principal, options.signal);
+        const snapshot = await this.engine.scan(workspaceId, { patterns: technologyScanPatterns(workspace) }, options.principal, options.signal);
+        const analysisMode = technologyAnalysisMode(workspace, snapshot);
         const preliminary = buildTechnologyGraph(snapshot, {
             workspaceIdentity: workspace.workspaceIdentity,
             cache: this.#state.fragments,
+            analysisMode,
             ...(options.signal === undefined ? {} : { signal: options.signal }),
         });
         const patterns = technologyAssetPatterns(preliminary);
@@ -339,6 +373,7 @@ export class TechnologyTreeViewer {
             workspaceIdentity: workspace.workspaceIdentity,
             cache: this.#state.fragments,
             assetFiles,
+            analysisMode,
             ...(options.signal === undefined ? {} : { signal: options.signal }),
         });
         this.#state.current.set(workspaceId, { generation, snapshot, assetFiles, graph });
@@ -354,7 +389,7 @@ export class TechnologyTreeViewer {
         let report;
         switch (input.mode) {
             case 'scan':
-                report = { ...technologyScanReport(graph), graph };
+                report = technologyScanReport(graph);
                 break;
             case 'folders':
                 report = discoverTechnologyFolders(graph, input.folderId);
@@ -588,6 +623,7 @@ export class TechnologyTreeViewer {
             workspaceIdentity: workspace.workspaceIdentity,
             cache: this.#state.fragments,
             assetFiles: cached.assetFiles,
+            analysisMode: cached.graph.analysisMode ?? 'full',
             ...(signal === undefined ? {} : { signal }),
         });
     }

package/dist/hoi4_agent_tools/version.js

@@ -1,6 +1,6 @@
 import { LATEST_PROTOCOL_VERSION } from '@modelcontextprotocol/sdk/types.js';
 export const PACKAGE_NAME = 'hoi4-agent-tools';
-export const PACKAGE_VERSION = '2.2.0';
+export const PACKAGE_VERSION = '2.3.3';
 export const MCP_PROTOCOL_VERSION = LATEST_PROTOCOL_VERSION;
 export const CONFIG_VERSION = 1;
 export const TRANSACTION_VERSION = 1;

package/docs/README.md

@@ -3,6 +3,7 @@
 - [Setup](setup.md): install the server, configure HOI4 paths, and connect an MCP client.
 - [Event chains](events.md): inspect, trace, lint, render, and compare event chains.
 - [Technology trees](technology.md): inspect, trace, lint, render, and compare technologies and doctrines.
+- [AI and MTTH analysis](probability.md): evaluate weighted logic, timing, uncertainty, sequences, and patches.
 - [Focus trees](focus.md): inspect, create, render, and clean national or continuous focus content.
 - [Scripted GUIs](gui.md): inspect linked UI source, render states, and create or repair GUIs.
 - [Maps](map.md): inspect and edit provinces, states, regions, adjacency, supply, and railways.

package/docs/development.md

@@ -23,6 +23,8 @@ The event-chain acceptance fixture contains more than 300 project-owned event de
 
 The technology acceptance fixture contains 1,040 project-owned technologies across 13 folders and exercises classic and current doctrines, prerequisites, exclusive branches, multiple placements, unlocks, bonuses, grants, assets, unresolved references, rendering, and comparison.
 
+The probability fixture contains more than 150 weighted blocks, 250 scenarios, and a declared stateful pool. Run `npm run benchmark` after analyzer changes. On the July 22, 2026 reference run, cold indexing took 28 ms, a cached block evaluation 29 ms, the 250-row matrix 85 ms, one million draws 9 ms, 3/12/25-candidate sequence cases 20/2,079/356 ms, and retrieval of a 1.84 MB result 3 ms. Review budgets are 250 ms, 150 ms, 750 ms, 100 ms, 200/10,000/3,000 ms, and 100 ms respectively; accuracy, method metadata, and omitted probability must not be weakened to meet them.
+
 Local opt-in tests can also read an installed game and an external mod without copying their sources:
 
 ```bash

package/docs/events.md

@@ -16,9 +16,9 @@ Use the three event tools directly from the target mod.
 - `lint`: find missing targets, unreachable events, suspicious cycles, conflicting definitions, invalid timing, and unresolved dynamic calls.
 - `impact`: identify callers, descendants, state dependencies, and files affected by a proposed event change.
 
-Use narrow identifiers, direction, and depth limits when the task concerns one chain. Broad scans build the structural event graph without expanding every scripted helper into duplicate paths. Focused trace, path, state, impact, and render calls expand helper relationships when needed.
+Use narrow identifiers, direction, and depth limits when the task concerns one chain. Broad scans build the structural event graph without expanding every scripted helper into duplicate paths. Focused trace and path calls traverse helper nodes and collapse only the selected bounded route, while state, impact, and render calls expand helper relationships when their workspace-wide evidence requires it.
 
-The compact response summarizes the result. Small scan resources contain the complete graph; very large scan resources contain exact totals, grouped inventories, representative diagnostics, and the revision needed for focused follow-up queries. This keeps an agent's prompt and artifact storage bounded without reducing the results of those focused queries.
+The compact response summarizes the result. Small scan resources contain the complete graph; very large scan resources contain exact totals, grouped inventories, representative diagnostics, and the revision needed for focused follow-up queries. The viewer retains the complete in-memory graph for those follow-up queries, and the event issue ceiling is high enough for installed-game-scale diagnostic inventories. This keeps an agent's prompt and artifact storage bounded without reducing the results of those focused queries.
 
 Selectors use one of these forms:
 

package/docs/probability.md

@@ -0,0 +1,80 @@
+# AI and MTTH scenario analysis
+
+The probability tools explain weighted HOI4 logic under explicit world-state scenarios. They inspect real mod source or proposed in-memory source, show which conditions and modifiers apply, calculate only probabilities supported by the selected HOI4 surface, and keep every unresolved input visible.
+
+Use them for event timing and option weights, decision and mission scores, focus selection, technology and doctrine selection, direct random chances, `random_list`, supported AI strategy factors, and declared custom weighted pools.
+
+| Tool                        | Use                                                                                                                             |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `hoi4.probability_inspect`  | Discover weighted blocks, adapters, candidates, provenance, capabilities, and unsupported constructs.                           |
+| `hoi4.probability_evaluate` | Evaluate eligibility, modifier traces, raw values, proven probabilities, and MTTH horizon chances across scenarios.             |
+| `hoi4.probability_sweep`    | Sweep declared ranges and locate sensitivity changes, breakpoints, and rank reversals.                                          |
+| `hoi4.probability_simulate` | Sample declared distributions with a deterministic seed and confidence intervals.                                               |
+| `hoi4.probability_sequence` | Analyze only recovery, caps, cooldowns, removal, resets, timers, and terminal states declared by a custom pool manifest.        |
+| `hoi4.probability_compare`  | Attribute changes in eligibility, modifiers, values, probabilities, timing, ranks, and unresolved analysis to a proposed patch. |
+| `hoi4.probability_render`   | Render cached ranking, matrix, waterfall, timing, sensitivity, sequence, comparison, and unresolved views.                      |
+
+All seven tools are read-only. Proposed source is parsed in memory and never written. When an installed game root is configured, evaluation fails closed unless `launcher-settings.json` identifies the supported HOI4 build and checksum. Results otherwise state that they target the adapter version without claiming local-game verification.
+
+## Scenarios
+
+A scenario contains only state the caller is willing to declare. Missing values stay unresolved. Alternatives and ranges produce exact branches or bounds; probability distributions require `hoi4.probability_simulate`.
+
+```json
+{
+  "schemaVersion": "1.0",
+  "id": "route_states",
+  "scenarios": [
+    {
+      "id": "defensive_war",
+      "actor": "EXM",
+      "date": "1939.9.1",
+      "state": {
+        "has_war": true,
+        "variable.foreign_influence": 45,
+        "focus.external_factors_complete": true
+      },
+      "flags": ["route_independent"]
+    }
+  ]
+}
+```
+
+Focus, technology, and doctrine probabilities require a complete candidate pool. Their engine rule is an independent uniform score race, not weight divided by total weight. Focus scenarios use `focus.external_factors_complete: true` only after the caller has supplied every relevant prerequisite and strategy factor. Technology and doctrine scenarios use `technology.external_factors_complete: true` only after cost, date, bonus, strategy, and candidate effects are accounted for.
+
+Decision and mission adapters intentionally return scores and ranks without inventing normalized probabilities. Event-option and `random_list` adapters normalize only their complete local pools. Direct random remains an independent percentage. MTTH horizon chance uses the versioned game timing model and returns a bound when an inactive-to-active polling phase is unknown.
+
+Named acceptance bands and configurable diagnostic thresholds let a test suite state intended probability, timing, starvation, dominance, prevalence, and sensitivity limits. Evaluate, sweep, and simulation requests can name the metrics of interest; that set is retained in result metadata while the authoritative result keeps the eligibility and trace context required to explain them. Sweeps enumerate declared alternatives exactly, add trigger breakpoints and their adjacent values for continuous ranges, and report local elasticities, pairwise interactions, rank reversals, cliffs, and missed target bands. Sweep expansion is bounded and rejected before it can silently truncate the requested analysis.
+
+## Results
+
+Authoritative JSON keeps these fields separate:
+
+- eligibility;
+- raw value or raw interval;
+- conditional selection probability or deterministic probability interval;
+- effective MTTH and cumulative time chance;
+- sampled frequency and statistical confidence interval;
+- scenario prevalence.
+
+Every candidate includes source provenance with a stable AST path, an ordered modifier trace, support level, and unresolved analysis. `external` support means the parsed candidate is valid but its surrounding game factors were not fully declared. The tool response stays compact; complete matrices, traces, simulations, comparisons, and visuals are linked MCP resources.
+
+Nested `random_list` entries report both their conditional share inside the immediate list and their full path probability through every enclosing list. Dynamic parent paths remain explicit unresolved evidence.
+
+Deterministic simulation uses constant-memory Latin hypercube sampling by default, with seeded pseudo-random sampling available when requested. Numeric distributions can use a Gaussian copula correlation matrix. Discrete or categorical correlation requests are sampled independently and reported as unresolved instead of being approximated silently. Simulation reports Wilson intervals, effective sample count, global input importance, and HOI4 daily-hazard MTTH samples. Timing quantiles use a deterministic bounded reservoir and include their confidence basis and retained sample count.
+
+## Proposed patches
+
+Pass `inlineClausewitz` or `virtualPatch` in a source selector to analyze text without writing it. `hoi4.probability_compare` evaluates the before and after source under the same scenarios and attributes each changed rank, score, probability, or uncertainty to its modifier trace.
+
+## Declared sequences
+
+Sequence analysis accepts a `customPoolManifest`. The manifest is the complete model boundary: candidates, selection mode, cadence, state, recovery, caps, cooldowns, removals, resets, timer changes, and terminal states. Small finite systems use exact state distributions, bounded systems expose omitted beam mass, and large systems use deterministic seeded Monte Carlo. Results include per-candidate and per-category next-choice probability, expected selections, ever-selected probability, starvation, and expected first-selection day. The analyzer never executes event effects or infers wider campaign state.
+
+## Visual review
+
+`hoi4.probability_render` produces deterministic ranking, matrix, waterfall, timing-survival, sensitivity, threshold, sequence, comparison, and unresolved views. Filters can select scenarios, candidates, and metrics. Pass the scenario hash returned by evaluation as `expectedScenarioHash` when a caller needs a render bound to that exact analysis; a stale hash returns a structured stale-result diagnostic and no visual artifact.
+
+Adapter evidence and known boundaries are recorded in [probability-adapter-evidence.md](research/probability-adapter-evidence.md).
+
+Callable argument examples are in [`examples/probability`](../examples/probability). Generated JSON Schemas for every operation, scenario sets, custom pools, and authoritative results are in [`schemas`](../schemas).

package/docs/research/probability-adapter-evidence.md

@@ -0,0 +1,64 @@
+# Probability adapter evidence
+
+The AI and MTTH Scenario Analyzer targets Hearts of Iron IV **Operation Postern 1.19.2.0 (checksum d245)**. Adapter behavior is versioned as `hoi4-1.19.2.v1`; results always include that adapter version and game build.
+
+This review used the installed game's documentation, vanilla source examples, and an offline Paradox wiki snapshot. Paths below are relative to a Hearts of Iron IV installation or to the offline snapshot. SHA-256 values identify the exact files reviewed on 2026-07-22.
+
+## Adapter semantics
+
+| Adapter                                           | Proven interpretation                                                                                                                                                                                                                  | Exact probability conditions                                                                                                                                                     | Deliberate boundary                                                                                                              |
+| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `event_mean_time_to_happen`                       | Ordered `base`, `add`, and `factor` operations produce an effective duration. When the trigger is active, `M` days is the median of daily checks, so daily hazard is `1 - 2^(-1/M)`. Inactive event triggers are polled every 20 days. | A time-horizon chance is exact only while trigger state, every modifier input, scheduled change, and any inactive-to-active polling phase are declared.                          | It does not execute events or infer state changes. Missing poll phase produces a 0–20 day activation bound.                      |
+| `event_option_ai_chance`                          | Options form one proportional categorical pool. An omitted block has weight 1. An all-zero pool selects the first option.                                                                                                              | Every option and eligibility result for the event must be present.                                                                                                               | The engine's d100 selection granularity is reported for effective shares below one percent.                                      |
+| `decision_ai_will_do` and `mission_ai_will_do`    | Ordered source modifiers produce a raw desirability score after eligibility.                                                                                                                                                           | No normalized probability is claimed.                                                                                                                                            | Local documentation does not prove a complete categorical denominator or a universal selection formula.                          |
+| `national_focus_ai_will_do`                       | Each eligible focus receives an independent uniform draw from zero to its evaluated score; the maximum wins. A just-completed prerequisite and AI strategy focus factors can change the score.                                         | The complete eligible candidate pool and every external focus factor must be declared. Exact probabilities use the independent-uniform maximum race, not `weight / sum(weight)`. | Ordered AI strategy plans can override weighted choice and are reported rather than simulated.                                   |
+| `technology_ai_will_do` and `doctrine_ai_will_do` | Eligible candidates use the independent-uniform maximum-score race. Research factors, cost, date, bonuses, and forced strategy choices can alter or override ranking.                                                                  | The complete eligible pool and all external research factors must be declared.                                                                                                   | Research duration is not selection probability. Forced research strategies and wider research-slot scheduling are not simulated. |
+| `direct_random`                                   | `chance` is an independent percentage in `[0,100]`.                                                                                                                                                                                    | The chance expression must resolve.                                                                                                                                              | It is never normalized against neighboring blocks.                                                                               |
+| `random_list`                                     | Entries form the complete local proportional weight pool. Nested entries retain their immediate conditional share and multiply through enclosing lists for a full path probability.                                                    | Every entry, enclosing list, and modifier on the selected path must resolve.                                                                                                     | Dynamic entry identifiers, dynamic parent paths, or effect-derived values remain unresolved unless supplied explicitly.          |
+| `ai_strategy_factor`                              | Supported strategy types modify a target score. `research_weight_factor` is a percentage factor; positive `research_tech` forces prioritization.                                                                                       | Raw factor evaluation is exact when the strategy and target are explicit.                                                                                                        | A strategy definition is not itself normalized into a probability pool.                                                          |
+| `custom_weighted_pool`                            | The manifest declares categorical or independent selection plus recovery, caps, cooldowns, removals, resets, timer changes, and terminal states.                                                                                       | Exact finite-state analysis is used while the state space stays bounded; otherwise the result is explicitly beam-bounded or seeded Monte Carlo.                                  | Only declared state transitions run. Gameplay effects and campaign state are never inferred or executed.                         |
+
+## Installed documentation reviewed
+
+| Relative path                                   | SHA-256                                                            | Used for                                                      |
+| ----------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------- |
+| `launcher-settings.json`                        | `f99265973bba12f30906cc98629d8520218ff8cd90a5f9d1d82e7f00fb737b9e` | Installed game version and checksum                           |
+| `common/decisions/_documentation.md`            | `5e7e686b5582f32c38d898d805e17171e88f3bfeee4a030deb1884f9726de019` | Decision scopes, eligibility surfaces, and evaluation cadence |
+| `common/doctrines/_documentation.md`            | `f0d1b7ad1f1dc8afe59942a406784a2d72c0c73dd42963c2502f89961eea85d4` | Current doctrine definitions and AI fields                    |
+| `common/script_constants/documentation.md`      | `e2812efbddc7961038e1f1f2b6dd6b059bdc70704ec87d1fe530835d9141be1c` | `constant:` schema and nested constant paths                  |
+| `documentation/script_concept_documentation.md` | `884bfe9f9207ea4b25b36b5129d0f77d11d4b2f7eb0592587767ec58d24930c7` | Script constants and dynamic script concepts                  |
+| `documentation/effects_documentation.md`        | `2cdc93d26775990468eed167442f7a416b13059fb8fe07d139b54250b79209af` | `random_list` and AI strategy effect syntax                   |
+| `common/ai_strategy/_documentation.md`          | `70f5d755ae7ed4060e49cc64a393d1a0dc5611b3acc8abc6dfb4538781c915a1` | `research_tech` and `research_weight_factor` behavior         |
+
+The offline wiki pages `AI modding`, `Data structures`, `Decision modding`, `Event modding`, `National focus modding`, `Scopes`, and `Technology modding` were reviewed in parallel. Their respective SHA-256 values were `f1fdb9fd…a14f`, `20a03385…a14f`, `500e8161…68c`, `b0186d9b…e00`, `b1c7f624…6faf`, `04866815…fdc`, and `48050261…fdc`.
+
+## Vanilla examples reviewed
+
+| Surface                       | Relative path and line                                         | SHA-256                                                            |
+| ----------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------ |
+| Event MTTH                    | `events/Yugoslavia.txt:49`                                     | `138279b294ef0d567e477efe2f0ebb72c5c0a7f2920ed3fd03d2792749624dbc` |
+| Event option `ai_chance`      | `events/AAT_Generic_Events.txt:44`                             | `e718d19edba2d56c75a5bbf1fa0c51bbb6cda54e0919434c4490fec9dabcea69` |
+| Decision `ai_will_do`         | `common/decisions/_generic_decisions.txt:56`                   | `83cd276f8fd2c0c90470225c996d7afee7b8c08437289dd23d819a4a29edb187` |
+| Focus `ai_will_do`            | `common/national_focus/austria.txt:122`                        | `0f197e321cb9e0c267a11c78bccb570ef42d1fc251e7af05fb4f385de27a1059` |
+| Technology `ai_will_do`       | `common/technologies/industry.txt:30`                          | `06d45f11a0bfdee35ef72b935b2bee3b0083a49eb771e5c6b9391c087ed7d94f` |
+| Current doctrine `ai_will_do` | `common/doctrines/grand_doctrines/land_grand_doctrines.txt:14` | `cd81a877366c582f096422320cd7fcf9fb259afcc8d45d3dbb887b37792b329d` |
+| `random_list`                 | `events/AAT_Sweden.txt:1760`                                   | `8fad5c10d147afab27eb42c78f3261c804cd6149f1c81927418ab0bbe3b8bf29` |
+| Direct `random`               | `events/BBA_Switzerland.txt:1197`                              | `4331bbe2ea7d0844eb357ecd73f915c1ba3e5a0b115ae62ea5b95a8011e1145e` |
+| AI research strategy factor   | `common/ai_strategy/ENG.txt:3206`                              | `f6fed5347c68ab2a3b79e4864dc5d72490c9cabe46a16e865932d2e5a37716d9` |
+
+The installed vanilla inventory contained 71 event files with MTTH, 101 with `ai_chance`, 86 decision files with `ai_will_do`, 76 national-focus files, 13 technology files, 19 doctrine files, 38 event files with `random_list`, and 9 AI strategy files with `research_weight_factor`. These counts were used to select examples and to test discovery breadth; they are not runtime assumptions.
+
+## Unsupported constructs
+
+When a game root is configured, adapter execution verifies `launcher-settings.json` against the supported raw version and checksum and fails closed on a missing, unreadable, or different build. Without a configured game root, results identify the adapter target without claiming that an installed build was verified.
+
+The analyzer reports, but does not guess or execute:
+
+- arbitrary effects used to calculate later weights;
+- unprovided scopes, event targets, game rules, DLC state, dynamic identifiers, meta effects, or scripted-localisation results;
+- parameterized scripted triggers whose arguments cannot be resolved from the selected source;
+- recursive MTTH variables or helper cycles;
+- incomplete focus, technology, doctrine, event-option, or random-list candidate pools;
+- categorical or discrete correlation requests; numeric ranges and numeric distributions are supported by the correlation sampler;
+- invalid or non-positive-semidefinite correlation matrices;
+- full strategic AI planning, research-slot scheduling, event-effect execution, or campaign simulation.

package/docs/setup.md

@@ -12,6 +12,8 @@ Set the MCP process working directory to the mod being edited. The server create
 
 When the MCP server starts with its working directory inside a mod, every focus, GUI, map, event, and technology call uses that mod automatically. Configured multi-mod or remote deployments can use explicit workspace selection.
 
+Local startup accepts normal descriptor-based mods and sparse descriptor-less mods that contain standard HOI4 content folders. Empty roots need a `descriptor.mod` or an explicit configuration so the server does not guess an unrelated directory.
+
 ## Optional persistent configuration
 
 Use `--init` only when you need several mod roots, a fixed game path, or a shared/remote process:

package/docs/technology.md

@@ -8,7 +8,7 @@ Use the three technology tools directly from the target mod.
 
 `hoi4.tech_inspect` provides eight focused modes:
 
-- `scan`: build the complete technology graph and report its inventory, diagnostics, analysis limits, and revision.
+- `scan`: build the technology graph and report its inventory, diagnostics, analysis limits, and revision. Small graphs include the complete graph in the report; large graphs return exact counts, grouped findings, samples, and the revision for focused follow-up queries.
 - `folders`: list folder roots and source placements, or inspect one `folderId`.
 - `trace`: follow prerequisites, descendants, or both from a `technologyId` with bounded depth and node limits.
 - `explain`: collect one technology's definition, placements, paths, exclusivity, metadata, effects, unlocks, grants, bonuses, and unresolved references.
@@ -43,7 +43,9 @@ Impact mode takes a subject with `kind` set to `technology`, `category`, `folder
 }
 ```
 
-Findings are separated into confirmed errors, probable defects, design warnings, and unresolved analysis. Roots, grant-only technologies, early dates, zero AI weights, repeated effects, and routing nodes are evaluated in context instead of being treated as automatic defects.
+Findings are separated into confirmed errors, probable defects, design warnings, and unresolved analysis. Roots, grant-only technologies, early dates, zero AI weights, repeated effects, and routing nodes are evaluated in context instead of being treated as automatic defects. The viewer keeps its authoritative graph in memory while the linked scan artifact remains a bounded summary; use its revision with the focused inspect modes or a render resource to inspect the relevant records.
+
+Game-backed and otherwise large workspaces automatically use focused analysis mode. It keeps direct grants, bonuses, unlocks, definitions, and the source-linked scripted-effect call index while deferring the full helper projection that can otherwise make a vanilla-plus-mod scan take minutes or exhaust the server process. The result is marked partial and names this boundary in `analysisBoundary`; no direct source evidence is discarded.
 
 ## Render
 

package/examples/clients/codex-config.toml

@@ -0,0 +1,3 @@
+[mcp_servers.hoi4_agent_tools]
+command = "npx"
+args = ["-y", "hoi4-agent-tools@latest"]

package/examples/clients/generic.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "hoi4_agent_tools": {
+      "command": "npx",
+      "args": ["-y", "hoi4-agent-tools@latest"]
+    }
+  }
+}

package/examples/probability/adaptive-event-pool.json

@@ -0,0 +1,92 @@
+{
+  "schemaVersion": "1.0",
+  "id": "adaptive_event_pool_example",
+  "description": "Declared pool with recovery, repeat caps, category growth, reset, removal, and timer compression.",
+  "selection": {
+    "mode": "categorical_weighted",
+    "cadence": "timer",
+    "timerMinDays": 45,
+    "timerMaxDays": 60,
+    "rounding": "nearest"
+  },
+  "state": {
+    "minor_events_since_major": 0,
+    "major_gain": 150,
+    "timer_compression": 0
+  },
+  "candidates": [
+    {
+      "id": "minor_fire_once",
+      "category": "fire_once",
+      "weight": 1000,
+      "cap": 1000,
+      "eligibleWhen": "not selected.minor_fire_once",
+      "oneTime": true
+    },
+    {
+      "id": "minor_repeatable",
+      "category": "repeatable",
+      "weight": 1000,
+      "cap": 1000,
+      "eligibleWhen": "true",
+      "cooldownDays": 0
+    },
+    {
+      "id": "major_crisis",
+      "category": "major",
+      "weight": 0,
+      "cap": 1000,
+      "eligibleWhen": "not selected.major_crisis",
+      "oneTime": true
+    }
+  ],
+  "recovery": [
+    {
+      "cadence": "monthly",
+      "target": "candidate.minor_repeatable.weight",
+      "amount": 20,
+      "cap": "candidate.minor_repeatable.cap"
+    }
+  ],
+  "transitions": [
+    {
+      "when": "selected.category != major",
+      "actions": [
+        { "operation": "add", "target": "state.minor_events_since_major", "value": 1 },
+        {
+          "operation": "add",
+          "target": "candidate.major_crisis.weight",
+          "value": "state.major_gain"
+        },
+        {
+          "operation": "compress_timer",
+          "target": "selection.timer_max_days",
+          "value": "floor(state.minor_events_since_major / 3)"
+        }
+      ]
+    },
+    {
+      "when": "selected.id == minor_repeatable",
+      "actions": [
+        { "operation": "multiply", "target": "candidate.minor_repeatable.cap", "value": 0.5 },
+        {
+          "operation": "cap",
+          "target": "candidate.minor_repeatable.weight",
+          "value": "candidate.minor_repeatable.cap"
+        }
+      ]
+    },
+    {
+      "when": "selected.category == major",
+      "actions": [
+        { "operation": "set", "target": "state.minor_events_since_major", "value": 0 },
+        { "operation": "reset_category", "target": "category.major", "value": 0 },
+        { "operation": "reset_timer", "target": "selection", "value": null }
+      ]
+    },
+    {
+      "when": "selected.one_time == true",
+      "actions": [{ "operation": "remove", "target": "selected.candidate", "value": null }]
+    }
+  ]
+}