hoi4-agent-tools 2.2.0 → 2.3.0

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.0';
 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/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/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 }]
+    }
+  ]
+}

package/examples/probability/adaptive-event-sequence-input.json

@@ -0,0 +1,57 @@
+{
+  "scenarioSet": {
+    "schemaVersion": "1.0",
+    "id": "pool_baseline",
+    "scenarios": [{ "id": "baseline", "state": {} }]
+  },
+  "customPoolManifest": {
+    "schemaVersion": "1.0",
+    "id": "adaptive_event_pool_example",
+    "selection": {
+      "mode": "categorical_weighted",
+      "cadence": "timer",
+      "timerMinDays": 45,
+      "timerMaxDays": 60,
+      "rounding": "nearest"
+    },
+    "state": { "minor_events_since_major": 0, "major_gain": 150 },
+    "candidates": [
+      { "id": "minor_repeatable", "category": "minor", "weight": 1000, "cap": 1000 },
+      { "id": "major_crisis", "category": "major", "weight": 0, "cap": 1000, "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": "candidate.major_crisis.weight",
+            "value": "state.major_gain"
+          },
+          { "operation": "compress_timer", "target": "selection.timer_max_days", "value": 1 }
+        ]
+      },
+      {
+        "when": "selected.category == major",
+        "actions": [
+          { "operation": "reset_category", "target": "category.major", "value": 0 },
+          { "operation": "reset_timer", "target": "selection", "value": null }
+        ]
+      }
+    ]
+  },
+  "horizonDays": 720,
+  "maxSteps": 1000,
+  "samples": 250000,
+  "seed": 3601,
+  "confidenceLevel": 0.95,
+  "outputs": ["json", "ranking", "timing", "sequence", "unresolved"]
+}

package/examples/probability/event-mtth-scenarios.json

@@ -0,0 +1,57 @@
+{
+  "schemaVersion": "1.0",
+  "id": "event_mtth_timeline_examples",
+  "surfaceHint": "event_mean_time_to_happen",
+  "scenarios": [
+    {
+      "id": "contained_outbreak",
+      "label": "Contained outbreak with later containment failure",
+      "actor": "EXM",
+      "date": "1940.1.1",
+      "state": {
+        "variable.outbreak_pressure": 25,
+        "variable.chaos": 350,
+        "has_war": false
+      },
+      "flags": ["outbreak_active", "containment_program_active"],
+      "schedule": [
+        {
+          "atDay": 60,
+          "set": { "variable.outbreak_pressure": 45 }
+        },
+        {
+          "atDay": 120,
+          "set": { "variable.chaos": 650 },
+          "clearFlags": ["containment_program_active"]
+        }
+      ]
+    },
+    {
+      "id": "uncertain_pressure",
+      "label": "Pressure and war state sampled",
+      "actor": "EXM",
+      "date": "1940.1.1",
+      "state": { "variable.chaos": 500 },
+      "flags": ["outbreak_active"],
+      "uncertainInputs": [
+        {
+          "path": "variable.outbreak_pressure",
+          "distribution": {
+            "kind": "triangular",
+            "min": 20,
+            "mode": 50,
+            "max": 90
+          }
+        },
+        {
+          "path": "has_war",
+          "distribution": {
+            "kind": "categorical",
+            "values": [true, false],
+            "probabilities": [0.35, 0.65]
+          }
+        }
+      ]
+    }
+  ]
+}

package/examples/probability/event-mtth-simulate-input.json

@@ -0,0 +1,37 @@
+{
+  "adapter": "event_mean_time_to_happen",
+  "source": { "identifier": "example_outbreak.42" },
+  "scenarioSet": {
+    "schemaVersion": "1.0",
+    "id": "outbreak_simulation",
+    "surfaceHint": "event_mean_time_to_happen",
+    "scenarios": [
+      {
+        "id": "uncertain_pressure",
+        "actor": "EXM",
+        "date": "1940.1.1",
+        "state": { "variable.chaos": 500 },
+        "flags": ["outbreak_active"],
+        "uncertainInputs": [
+          {
+            "path": "variable.outbreak_pressure",
+            "distribution": { "kind": "triangular", "min": 20, "mode": 50, "max": 90 }
+          },
+          {
+            "path": "has_war",
+            "distribution": {
+              "kind": "categorical",
+              "values": [true, false],
+              "probabilities": [0.35, 0.65]
+            }
+          }
+        ]
+      }
+    ]
+  },
+  "horizonDays": 365,
+  "samples": 100000,
+  "seed": 19400101,
+  "confidenceLevel": 0.95,
+  "outputs": ["json", "timing", "waterfall", "unresolved"]
+}

package/examples/probability/focus-route-scenarios.json

@@ -0,0 +1,61 @@
+{
+  "schemaVersion": "1.0",
+  "id": "focus_route_choice_examples",
+  "surfaceHint": "national_focus_ai_will_do",
+  "description": "Representative country states for evaluating the next focus choice.",
+  "scenarios": [
+    {
+      "id": "peace_low_industry",
+      "label": "Peace with weak industry",
+      "actor": "EXM",
+      "date": "1938.1.1",
+      "state": {
+        "has_war": false,
+        "num_of_military_factories": 8,
+        "stability": 0.62,
+        "world_tension": 0.28,
+        "focus.external_factors_complete": true
+      },
+      "flags": ["route_independent"]
+    },
+    {
+      "id": "defensive_war",
+      "label": "Defensive war under pressure",
+      "actor": "EXM",
+      "date": "1939.9.1",
+      "state": {
+        "has_war": true,
+        "is_in_defensive_war": true,
+        "num_of_military_factories": 12,
+        "stability": 0.45,
+        "world_tension": 0.74,
+        "focus.external_factors_complete": true
+      },
+      "flags": ["route_independent", "border_crisis_active"]
+    },
+    {
+      "id": "uncertain_foreign_support",
+      "label": "Foreign support uncertain",
+      "actor": "EXM",
+      "date": "1939.3.1",
+      "state": {
+        "has_war": false,
+        "num_of_military_factories": 10,
+        "stability": 0.55,
+        "world_tension": 0.52,
+        "focus.external_factors_complete": true
+      },
+      "flags": ["route_independent"],
+      "uncertainInputs": [
+        {
+          "path": "has_flag.foreign_support_secured",
+          "alternatives": [true, false]
+        },
+        {
+          "path": "variable.foreign_influence",
+          "range": { "min": 20, "max": 80 }
+        }
+      ]
+    }
+  ]
+}

package/examples/probability/focus-route-sweep-input.json

@@ -0,0 +1,36 @@
+{
+  "adapter": "national_focus_ai_will_do",
+  "source": { "identifier": "EXM_prepare_the_border" },
+  "scenarioSet": {
+    "schemaVersion": "1.0",
+    "id": "focus_route_sweep",
+    "surfaceHint": "national_focus_ai_will_do",
+    "scenarios": [
+      {
+        "id": "uncertain_foreign_support",
+        "actor": "EXM",
+        "date": "1939.3.1",
+        "state": {
+          "has_war": false,
+          "stability": 0.55,
+          "world_tension": 0.52,
+          "focus.external_factors_complete": true
+        },
+        "uncertainInputs": [
+          {
+            "path": "variable.foreign_influence",
+            "range": { "min": 20, "max": 80 }
+          }
+        ]
+      }
+    ]
+  },
+  "candidatePool": ["EXM_expand_industry", "EXM_prepare_the_border", "EXM_seek_foreign_support"],
+  "sweep": {
+    "paths": ["variable.foreign_influence"],
+    "steps": 25,
+    "pairwise": false,
+    "findRankReversals": true
+  },
+  "outputs": ["json", "ranking", "matrix", "waterfall", "sensitivity", "unresolved"]
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "hoi4-agent-tools",
   "mcpName": "io.github.klimPaskov/hoi4-agent-tools",
-  "version": "2.2.0",
-  "description": "Analyze HOI4 events and technology trees; create and clean focus trees, GUIs, and maps.",
+  "version": "2.3.0",
+  "description": "Analyze HOI4 events, tech trees, AI weights, and MTTH; build focus trees, GUIs, and maps.",
   "type": "module",
   "license": "Apache-2.0",
   "author": "HOI4 Agent Tools contributors",
@@ -24,6 +24,9 @@
     "event-chains",
     "technology-trees",
     "doctrines",
+    "ai-weights",
+    "mtth",
+    "probability-analysis",
     "hoi4-events",
     "scripted-gui",
     "hoi4-map"
@@ -37,11 +40,16 @@
     "docs/setup.md",
     "docs/events.md",
     "docs/technology.md",
+    "docs/probability.md",
+    "docs/research/probability-adapter-evidence.md",
     "docs/focus.md",
     "docs/gui.md",
     "docs/map.md",
     "docs/http.md",
     "docs/development.md",
+    "examples/clients/",
+    "examples/probability/",
+    "schemas/",
     "server.json",
     "README.md",
     "CHANGELOG.md",
@@ -66,12 +74,13 @@
     "test:local": "tsx scripts/run-local-tests.ts",
     "test:coverage": "vitest run --coverage",
     "benchmark": "node --expose-gc --import tsx scripts/benchmark.ts",
-    "fixtures:generate": "npm run fixtures:generate:focus && npm run fixtures:generate:gui && npm run fixtures:generate:map && npm run fixtures:generate:event && npm run fixtures:generate:technology",
+    "fixtures:generate": "npm run fixtures:generate:focus && npm run fixtures:generate:gui && npm run fixtures:generate:map && npm run fixtures:generate:event && npm run fixtures:generate:technology && npm run fixtures:generate:probability",
     "fixtures:generate:focus": "tsx scripts/generate-fixtures.ts",
     "fixtures:generate:gui": "tsx scripts/generate-gui-fixture.ts",
     "fixtures:generate:map": "tsx scripts/generate-map-fixture.ts",
     "fixtures:generate:event": "tsx scripts/generate-event-fixture.ts",
     "fixtures:generate:technology": "tsx scripts/generate-technology-fixture.ts",
+    "fixtures:generate:probability": "tsx scripts/generate-probability-fixture.ts",
     "fixtures:check": "npm run fixtures:generate && tsx scripts/check-generated.ts fixtures",
     "schemas:generate": "tsx scripts/generate-schemas.ts",
     "schemas:check": "tsx scripts/generate-schemas.ts && tsx scripts/check-generated.ts schemas",
@@ -92,13 +101,13 @@
     "fast-glob": "3.3.3",
     "fontkit": "2.0.4",
     "iconv-lite": "0.7.3",
-    "jose": "6.2.3",
+    "jose": "6.2.4",
     "sharp": "0.35.3",
     "zod": "4.4.3"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
-    "@modelcontextprotocol/inspector": "0.22.0",
+    "@modelcontextprotocol/inspector": "1.0.0",
     "@types/express": "5.0.6",
     "@types/fontkit": "2.0.9",
     "@types/node": "22.20.1",
@@ -109,10 +118,10 @@
     "eslint": "10.7.0",
     "fast-check": "4.9.0",
     "pixelmatch": "7.2.0",
-    "prettier": "3.9.5",
-    "tsx": "4.23.0",
+    "prettier": "3.9.6",
+    "tsx": "4.23.1",
     "typescript": "6.0.3",
-    "typescript-eslint": "8.63.0",
+    "typescript-eslint": "8.65.0",
     "vitest": "4.1.10"
   },
   "overrides": {