hoi4-agent-tools 3.10.0 → 4.0.1

package/docs/map.md

@@ -1,10 +1,11 @@
 # Maps
 
-Use `hoi4.map_inspect`, `hoi4.map_render`, and `hoi4.map_rewrite` for provinces, states, strategic regions, adjacency, supply nodes, railways, positions, ownership, cores, claims, resources, buildings, and localisation.
+Generate a new world, split states and reshape provinces. Preview the map and update the scripts that refer to it.
+Use `hoi4.map_inspect` and `hoi4.map_rewrite` for provinces, states, regions, supply, railways, positions, ownership, resources, buildings and localisation.
 
 ## Inspect and navigate the complete map
 
-`hoi4.map_inspect` validates the map and returns a full-map PNG plus a searchable, clickable HTML navigator by default. The navigator supports pan, zoom, fit-to-map, search by numeric ID, localisation key, or localised name, and exact click lookup for province, state, and strategic-region IDs. Hovering reports both top-left bitmap coordinates and bottom-left HOI4 map coordinates.
+`hoi4.map_inspect` finds map problems and returns a full-map PNG plus a searchable, clickable HTML navigator by default. The navigator supports pan, zoom, fit-to-map, search by numeric ID, localisation key, or localised name, and exact click lookup for province, state, and strategic-region IDs. Hovering reports both top-left bitmap coordinates and bottom-left HOI4 map coordinates.
 
 The linked JSON catalog contains every active province definition, state, and strategic region with resolved names, alternate localisation values, source paths and lines, raster bounds and centers, memberships, neighbors, victory points, resources, buildings, ports, supply nodes, railways, normal and special adjacencies, building positions, unit positions, weather positions, and entity locators. Large catalog and render data remain in MCP resources instead of filling the agent prompt.
 
@@ -12,9 +13,25 @@ Use `query` for a compact name or ID result list and `coordinates` for exact pix
 
 Set `lookupOnly: true` for coordinate, query, and selected-ID lookups without full validation, the complete catalog artifact, overview rendering, or province geometry export. The lookup artifact contains only the requested matches and source revision. Use full inspection for allocation previews or province row runs.
 
-`hoi4.map_render` creates the same complete catalog and navigator with a chosen base layer and overlays. Base layers include province, state, strategic region, terrain, continent, owner, controller, cores, claims, and coast. Overlays include coastlines, ports, victory points, resources, state and province buildings, supply nodes, railways, adjacencies, and building, unit, and weather positions.
+`hoi4.map_inspect` accepts these fields:
 
-Pass `tile: { x, y, width, height }` to `hoi4.map_render` for a reusable bounded PNG, JSON, and HTML view of one top-left bitmap area. The tile preserves the selected base layer and overlays, and its JSON records raster dimensions and province IDs in the area. Identical source revisions and render settings produce identical artifact hashes.
+| Field                | Default and limits               | Meaning                                                                                                                                                                                                                 |
+| -------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `provinceIds`        | `[]`, at most 32                 | Province records to return, with exact geometry row runs.                                                                                                                                                               |
+| `stateIds`           | `[]`, at most 1,000              | State records to return.                                                                                                                                                                                                |
+| `regionIds`          | `[]`, at most 1,000              | Strategic-region records to return.                                                                                                                                                                                     |
+| `query`              | optional, at most 256 characters | Name, localisation key, or ID search.                                                                                                                                                                                   |
+| `queryLimit`         | 100, range 1 to 1,000            | Maximum `query` matches.                                                                                                                                                                                                |
+| `coordinates`        | `[]`, at most 100                | `{ "kind": "pixel", "x", "y" }` with top-left bitmap pixels, or `{ "kind": "map", "x", "z" }` with HOI4 map coordinates.                                                                                                |
+| `lookupOnly`         | `false`                          | Return only the requested lookups, as described above.                                                                                                                                                                  |
+| `includeOverview`    | `true`                           | Render the full-map PNG and navigator; set `false` to skip the overview render.                                                                                                                                         |
+| `allocationRequests` | `[]`, at most 100                | Preview the next free identifiers: `{ "kind": "state", "requestedId"? }` or `{ "kind": "province", "requestedId"?, "requestedColor"? }`, where `requestedColor` is `{ "r", "g", "b" }`. Not accepted with `lookupOnly`. |
+
+Give `hoi4.map_inspect` a `layer`, `overlays`, `scale`, `tile` or `area` to render that view instead of validating; the result is the same complete catalog and navigator drawn with the chosen base layer and overlays, and lookups (`query`, `coordinates`, IDs) belong in a separate call. Base layers include province, state, strategic region, terrain, continent, owner, controller, cores, claims, and coast. Overlays include coastlines, ports, victory points, resources, state and province buildings, supply nodes, railways, adjacencies, and building, unit, and weather positions.
+
+A rendered view takes `layer` (default `province`), up to 12 `overlays`, and an integer `scale` from 1 to 16 (default 1).
+
+Pass `tile: { x, y, width, height }` for a reusable bounded PNG, JSON, and HTML view of one top-left bitmap area. The tile preserves the selected base layer and overlays, and its JSON records raster dimensions and province IDs in the area. Identical source revisions and render settings produce identical artifact hashes.
 
 Pass `area: { provinceIds, stateIds, regionIds, padding }` to render the exact bounding area of those map entities with optional pixel padding. The result reports the resolved tile coordinates. An unknown ID or an area larger than 2,048 pixels in either direction is explicit, so a narrower selection can be requested.
 
@@ -28,9 +45,45 @@ When no terrain category file is available, seas and lakes are checked against t
 The engine stops reading `adjacencies.csv` at its first `-1` row.
 Rows after it are not read and report `MAP_ADJACENCY_AFTER_TERMINATOR`; a file without that row reports `MAP_ADJACENCY_TERMINATOR_MISSING` as a warning, because the offline wiki describes it as required although at least one published mod omits it.
 
+## Rewrite requests
+
+`hoi4.map_rewrite` takes an ordered list of 1 to 100 operations in `operations`, an optional integer `diffScale` from 1 to 16 for the comparison render (default 1), and an optional `requestKey` for background retries:
+
+```json
+{
+  "operations": [
+    {
+      "id": "create-western-state",
+      "kind": "create_state",
+      "provinceIds": [120, 121, 122],
+      "displayName": "Western State"
+    }
+  ],
+  "diffScale": 2
+}
+```
+
+An operation list may hold up to 100 operations and is applied in order.
+Every operation has a unique `id` (1 to 256 characters), an optional `summary`, and a `kind`.
+The supported kinds are:
+
+- whole maps: `create_world`;
+- states: `create_state`, `split_state`, `merge_states`, `move_state_provinces`, `update_state`;
+- provinces: `create_province`, `split_province`, `merge_provinces`, `remove_province`, `update_province_definition`;
+- strategic regions: `move_region_provinces`;
+- identifiers and script references: `renumber_map_entity`, `remap_map_references`;
+- derived data: `regenerate_map_positions`, `rebuild_supply`;
+- adjacency: `add_normal_adjacency`, `remove_normal_adjacency`, `add_adjacency`, `remove_adjacency`;
+- supply and railways: `add_supply_node`, `remove_supply_node`, `add_railway`, `remove_railway`;
+- positions: `upsert_building_position`, `remove_building_position`, `upsert_unit_position`, `remove_unit_position`, `upsert_weather_position`, `remove_weather_position`;
+- entity locators: `update_entity_locator`.
+
+The complete operation schema is [map-operation.schema.json](../schemas/map-operation.schema.json).
+The examples below show single operations; each goes inside the `operations` array.
+
 ## Create states
 
-The compact `create_state` form needs selected provinces and a display name:
+The compact `create_state` form needs selected provinces and a `displayName` or `name`:
 
 ```json
 {
@@ -41,7 +94,7 @@ The compact `create_state` form needs selected provinces and a display name:
 }
 ```
 
-When all selected provinces belong to one state, the tool infers that source state, allocates the state ID, creates `STATE_<id>` localisation, divides manpower, resources, and state buildings by land-pixel share, copies owner, controller, cores, and claims, and moves province-bound records with their provinces. Supply, railway, port, victory-point, building-position, and strategic-region references remain connected.
+When all selected provinces belong to one state, the tool infers that source state, allocates the state ID, creates `STATE_<id>` localisation, divides manpower, resources, and slot buildings (factories, dockyards, refineries and other buildings that share state slots) by land-pixel share in whole units, keeps level buildings such as infrastructure, air bases, anti-air and radar at their level in both parts, carries dated history to both parts, copies owner, controller, cores, and claims, and moves province-bound records with their provinces. Supply, railway, port, victory-point, building-position, and strategic-region references remain connected.
 
 Pass `sourceStateId`, `stateId`, `name`, `fileName`, `localisation`, or the complete distribution object when the defaults are not the intended design. `split_state` retains the explicit contract for callers that want every policy written out.
 
@@ -87,16 +140,155 @@ Renumbering also inspects active event, focus, decision, scripted helper, on-act
 
 Set `collision` to `reject` to require an unused destination. Set `renameLocalisation` to `false` only when custom localisation-key handling is intentional.
 
+## Move provinces between states
+
+`move_state_provinces` hands provinces from one state to another.
+Without a `distribution` (or with `"distribution": "proportional"`) the values follow the land: the target receives the moved provinces' share of the source's land pixels of its manpower (the state's population), resources and slot buildings (factories, dockyards, refineries and the like), in whole units.
+Level buildings (infrastructure, air bases, anti-air, radar) stay at their level in the source, and the target takes the higher level of the two.
+Victory points and province buildings follow their province, and the moved provinces take the target's owner, controller, cores and claims because they are now part of the target.
+The provinces must share the target's strategic region, or the operation stops; set `strategicRegion: "move-to-target-region"` in a full `distribution` to move them to the target's region.
+Pass a full `distribution` with `stateValues: "retain-in-current-states"` to leave manpower, resources and buildings where they are, or `"proportional-by-land-pixels"` to write the automatic choice out.
+
+```json
+{
+  "id": "give-province-to-neighbour",
+  "kind": "move_state_provinces",
+  "sourceStateId": 64,
+  "targetStateId": 65,
+  "provinceIds": [3314]
+}
+```
+
+Nothing is lost or duplicated: for any split, merge or move, the sums of manpower, each resource and each slot building over all states are the same before and after.
+
 ## Other map changes
 
 `hoi4.map_rewrite` also moves and merges states, moves provinces between strategic regions, merges or removes provinces, changes province definitions and types, adds or removes normal and special adjacency, and updates supply, railway, building, unit, weather, and entity-locator records. Send one ordered operation list when several connected changes belong together.
 
 Every rewrite returns changed-area, changed-ID, semantic, affected-file, diagnostic, and rendered comparison evidence. A failed operation does not leave a partial multi-file result.
 
+## Check script references
+
+Set `references: true` on `hoi4.map_inspect` to also read events, focuses, decisions, scripted effects and triggers, on-actions, ideas, characters, AI strategies and areas, and country and unit history.
+It reports:
+
+- `MAP_SCRIPT_REFERENCE_MISSING`: a state, province or strategic region named by number that the map does not define, as `owns_state = 64`, `has_full_control_of_state = 64`, `transfer_state = 64`, `set_state_controller = 64`, `capital = 64`, a state scope `64 = { ... }`, a `prioritize = { 64 65 }` list, a `state`, `to_state` or `start_state` argument, a province argument such as `set_province_controller` or `province = { id = 3314 }`, a strategic region in `region = 12` or `ships_in_area`, a unit `location`, or an AI area's `strategic_regions`; an error in the mod's own files and a warning in game or dependency files;
+- `MAP_STATE_TAG_UNKNOWN`: a state owner, controller, core or claim whose tag no `common/country_tags` file declares;
+- `MAP_COUNTRY_CAPITAL_NOT_OWNED`: a country that owns states but has its capital in another country's state.
+
+The data's `scriptReferences` counts the references checked and the missing ones. Numeric keys inside `random_list` and other weighted blocks are weights and are not read as states.
+
+## Keep scripts in step with geography
+
+`remap_map_references` rewrites the script references of one entity kind after a split, merge, removal or renumbering:
+
+```json
+{
+  "id": "brandenburg-split",
+  "kind": "remap_map_references",
+  "entity": "state",
+  "mapping": [
+    { "from": 64, "to": [64, 1082] },
+    { "from": 917, "to": null }
+  ],
+  "readOnlySources": "override"
+}
+```
+
+One target replaces the number. Several targets keep the first and copy the whole referencing assignment for each further target, so `64 = { add_core_of = ROOT }` becomes one block per successor and `owns_state = 64` becomes one condition per successor. In a list such as `prioritize = { 64 65 }` the extra targets join the list.
+Keys that take exactly one value (`capital`, `state`, `to_state`, `start_state`, `province`, `region` and the like) are never copied or deleted: they change to the first target, and when their state has no successor they stay as they are and are reported as `MAP_REFERENCE_NEEDS_REVIEW` with the file and line, so that you choose the new target. They also remain visible to `references: true`. `null` removes the referencing assignment. Game and dependency files are never edited: with `readOnlySources: override` the files that need the change are copied into the mod with it, and otherwise the operation refuses and lists them. `pathPrefixes` limits the rewrite to some folders. Run it in the same request as the split so the review shows both.
+
+`merge_states`, `create_state` and `split_state` can do this themselves: add `"remapReferences": "refuse"` (or `"override"`, which copies the game files that need it into the mod) and the merged-away states are renamed to the survivor, or the source state's references are extended to the new part, in the same plan.
+
+## Positions and supply
+
+`regenerate_map_positions` places building, unit-stack and weather positions from province geometry. By default (`mode: missing`) it only adds what is absent: positions for each building model a state or province lacks (from `show_on_map` and the spawn points in `common/buildings`), a full unit-stack set for provinces without one, and a small and a big weather object for strategic regions without one. `mode: replace` rewrites the positions of the selected `stateIds`, `provinceIds` and `regionIds`. Interior points keep away from province borders, naval bases face the sea province they open onto, and floating harbours sit on the water and name their land province. `positions` limits it to `buildings`, `units` or `weather`; heights come from the heightmap.
+
+`rebuild_supply` places a supply node in a state's capital province (its `capital`, else its highest victory point, else its largest land province) and joins nodes to their country's hub, the state with the most victory points, by the cheapest railway through land that belongs to a state, preferring the country's own provinces and avoiding impassable borders. `mode: connect` (the default) handles named `stateIds`, or without them only states with a supply gap: no node within three land provinces. `mode: replace` rebuilds the whole network. `railwayLevel` (default 1) and `capitalRailwayLevel` (default 3, for lines through the hub) set railway levels.
+
+## Create a new world
+
+`create_world` writes a complete map for a total-conversion mod:
+
+```json
+{
+  "id": "world",
+  "kind": "create_world",
+  "width": 2048,
+  "height": 1024,
+  "seed": 7,
+  "landCoverage": 0.35,
+  "continents": 3,
+  "countries": [
+    { "tag": "AUR", "name": "Aurelia" },
+    { "tag": "BOR", "name": "Borea", "share": 2, "ideology": "democratic" },
+    { "tag": "CAL", "name": "Calder", "color": { "r": 160, "g": 40, "b": 40 } }
+  ],
+  "continentNames": ["Aster", "Brum", "Corvel"]
+}
+```
+
+Width and height are multiples of 256 with at most 13,238,272 pixels. Land comes from noise around `continents` centres to the requested `landCoverage`, or from `landPolygons` in pixel coordinates; the map's east-west seam and polar rows stay sea. Provinces grow evenly from spread seeds (`landProvincePixels`, default 400, and `seaProvincePixels`, default 2,500, both capped so no province exceeds an eighth of the map), stay connected, avoid four-province corners and are at least 20 pixels. Enclosed water becomes land or, when large, a lake.
+
+The operation writes `provinces.bmp`, `definition.csv`, `default.map`, `continent.txt`, `heightmap.bmp`, `terrain.bmp`, `rivers.bmp` (rivers run downhill to the coast), `trees.bmp`, `cities.bmp`, `world_normal.bmp`, the land and water colour maps, `adjacencies.csv`, strategic regions (`landProvincesPerRegion`, `seaProvincesPerRegion`) with weather by latitude, states (`provincesPerState`) with population, category, buildings, resources, victory points and ports, country tags, country files, history and three-band flags, a bookmark, localisation, and every position, supply node and railway. Countries grow from spread-out capitals in proportion to `share`; each state lies within one country and one strategic region.
+
+With `replaceBaseGame` (default `true`) it adds `replace_path` lines for `history/states`, `history/countries`, `history/units`, `map/strategicregions`, `map/supplyareas` and `common/bookmarks` to `descriptor.mod`, and its info diagnostic reminds you that the launcher's `.mod` file beside the mod folder needs the same lines. Base-game events, focuses and decisions still name base-game states; `map_inspect` with `references: true` lists them for replacement or remapping. The same seed always gives the same world. Refine it with the other operations.
+
+## Worked example: build a world, then reshape it
+
+1. Create the world. The same seed always gives the same world.
+
+   ```json
+   {
+     "operations": [
+       {
+         "id": "world",
+         "kind": "create_world",
+         "width": 1024,
+         "height": 512,
+         "seed": 11,
+         "countries": [
+           { "tag": "AUR", "name": "Aurelia" },
+           { "tag": "BOR", "name": "Borea", "share": 2 }
+         ]
+       }
+     ]
+   }
+   ```
+
+2. Inspect it. `hoi4.map_inspect` with `references: true` lists scripts that still name base-game states. Fix those with `remap_map_references` (to a new state) or by replacing the script.
+
+3. Reorganise in one request. The merge folds state 12 into state 11 and rewrites every script that named 12; the move gives one province to a neighbour with its share of population, resources and factories.
+
+   ```json
+   {
+     "operations": [
+       {
+         "id": "merge",
+         "kind": "merge_states",
+         "targetStateId": 11,
+         "sourceStateIds": [12],
+         "remapReferences": "override"
+       },
+       {
+         "id": "move",
+         "kind": "move_state_provinces",
+         "sourceStateId": 11,
+         "targetStateId": 13,
+         "provinceIds": [402]
+       }
+     ]
+   }
+   ```
+
+4. Repair what a change leaves behind. `rebuild_supply` joins new or changed states to their country's supply network, `regenerate_map_positions` adds missing building, unit and weather positions, and `hoi4.map_inspect` with `references: true` must report no `MAP_SCRIPT_REFERENCE_MISSING` and no `MAP_REFERENCE_NEEDS_REVIEW` follow-ups before the mod is released.
+
+`tests/unit/map-reorganise.test.ts` runs this sequence on a generated world and checks that totals of manpower, resources and factories are unchanged.
+
 ## Dated state history
 
 Map inspection reads active `common/bookmarks/*.txt` sources and uses the earliest valid bookmark date as the state-history basis. Supported owner, controller, core, claim, victory-point, and building commands in earlier dated blocks contribute to the inspected state and its rendered owner or controller layer. If no bookmark date is available, dated state fields retain their direct values and inspection reports `MAP_STATE_DATED_HISTORY_UNRESOLVED`.
 
-Map rewrites preserve dated source blocks byte-for-byte. An update to a field overridden by an applicable dated block returns `MAP_DATED_STATE_HISTORY_CONFLICT`. Province membership changes also block when a dated victory point or building entry would need remapping. Splitting or merging a source state with dated history returns `MAP_DATED_STATE_DISTRIBUTION_UNSUPPORTED`, because copying or deleting that history would change its later meaning. A direct edit with only later dated changes may proceed; those later commands remain and can supersede the direct value at later bookmarks. Edit the dated source deliberately when that later behavior is the intended change.
+Map rewrites preserve dated source blocks byte-for-byte. An update to a field overridden by an applicable dated block returns `MAP_DATED_STATE_HISTORY_CONFLICT`. Province membership changes also block when a dated victory point or building entry would need remapping. A split divides dated blocks like the undated values: dated ownership, cores and other effects apply to both parts, dated victory points and province buildings follow their provinces, level buildings keep their level and slot buildings divide by the same land share. A merge carries the source states' dated blocks into the target, but refuses a source whose dated history sets building levels (`MAP_DATED_STATE_DISTRIBUTION_UNSUPPORTED`), because each part's later value replaces its own and the two cannot be combined; move those provinces with `move_state_provinces` or edit the block first. A merge keeps the highest level building and sums slot buildings, and its distribution policy may be omitted. A direct edit with only later dated changes may proceed; those later commands remain and can supersede the direct value at later bookmarks. Edit the dated source deliberately when that later behavior is the intended change.
 
 `floating_harbor` placement rows differ from fixed `naval_base_spawn` ports. Their XYZ coordinates normally identify a sea placement, while the final numeric field names a land target. The map catalog does not count floating-harbor placements as starting naval-base locators. A missing or non-land target is an error. An off-sea position or an unusual state/coastal association is a review warning because those patterns also occur in installed vanilla map data; the warning retains the exact source line.

package/docs/mechanics.md

@@ -1,7 +1,7 @@
 # Mechanic tests, package checks, and scenario suites
 
-`hoi4.mechanic_test`, `hoi4.package_check`, and `hoi4.scenario_test` read authorized HOI4 source and return linked, revision-bound evidence.
-They do not launch the game or change source files.
+Test scripted effects, find missing pieces of a feature and run repeatable scenarios.
+`hoi4.mechanic_test`, `hoi4.package_check` and `hoi4.scenario_test` evaluate mod source and return reports tied to that source revision.
 Supply `expectedRevision` when continuing analysis against a reviewed scan.
 
 ## Test an effect
@@ -39,6 +39,8 @@ An `advance_days` step only expires modeled timed flags; it never runs on action
 }
 ```
 
+The complete input schema is [mechanic-test-input.schema.json](../schemas/mechanic-test-input.schema.json).
+
 The linked trace records applied, skipped, and unresolved source operations with before and after values.
 The `single_payment` assertion checks the named balance's final change and the number and size of its traced deductions, so a compensating grant cannot hide a second charge.
 Supported operations include documented persistent and unscoped temporary-variable arithmetic, exact `has_variable` presence checks, flags, event targets, arrays, conditionals, finite declared scope iteration, scripted helpers, safe meta substitutions, and selected balance effects.
@@ -55,6 +57,7 @@ Add expected `definitions` and `calls` as `{ "kind": "scripted_effect", "id": "t
 The report separates present, absent, shadowed, and unresolved links and includes source hashes and locations.
 Required cases are checked for declaration; run `hoi4.scenario_test` to evaluate them.
 The manifest accepts no source patches or executable commands.
+The input and manifest schemas are [package-check-input.schema.json](../schemas/package-check-input.schema.json) and [package-manifest.schema.json](../schemas/package-manifest.schema.json).
 
 ## Run a suite
 
@@ -63,6 +66,7 @@ The suite has `schemaVersion: "1.0"`, an `id`, and named `cases` in the `mechani
 A mechanic case supplies the same `test` as `hoi4.mechanic_test`; a package case supplies a `manifest`.
 A tool case names one allowed inspect, render, or evaluate operation and supplies its typed `arguments`.
 Cases may declare `sourceSelectors`, output path assertions, and `views` (`summary`, `artifacts`, `diagnostics`).
+The input and suite schemas are [scenario-test-input.schema.json](../schemas/scenario-test-input.schema.json) and [scenario-suite.schema.json](../schemas/scenario-suite.schema.json).
 
 Set `maxCases` to bound a batch.
 Each case receives a content-addressed result artifact; the batch returns its counts and, while cases remain, a `continuation`.

package/docs/probability.md

@@ -1,33 +1,58 @@
 # 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.
+Find out why the AI favours one choice and ignores another. Compare weights, conditions and timing to help your agent balance events, decisions, focuses and research.
+The tools evaluate existing or proposed source under declared game conditions and list any missing facts.
 
 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, compatible 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.                      |
+| Tool                       | Use                                                                                                                                                                                                      |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `hoi4.probability_inspect` | Find weighted logic by file, identifier or candidate IDs and evaluate it: each candidate's weight and probability per scenario, the strongest first, and the facts still missing.                        |
+| `hoi4.probability_analyze` | Deeper analysis selected by `analysis`: `compare` a proposed or frozen source, `sweep` declared ranges, `simulate` uncertain inputs, `sequence` a declared pool over time, `render` a retained analysis. |
 
-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.
+## Game version
 
-Pass a source without an adapter when the surface type is not yet known. Inspection returns every compatible adapter, candidate counts, and example candidate IDs; its discovery artifact includes every candidate ID and source location. If a requested adapter, identifier, or candidate pool does not match the source, inspection returns the same discovery result with an explanation and suggested adapter instead of `PROBABILITY_SURFACE_EMPTY`.
+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.
+
+## One call for current weights
+
+`hoi4.probability_inspect` finds the weighted surface and evaluates it in the same call.
+Name what to inspect in whichever way is at hand:
+
+- `source.path` (and `source.line`) for a file or one block in it;
+- `source.identifier` for a decision, mission, focus, technology, event or `random_list` ID;
+- `candidatePool` alone: its first ID finds the defining file, an event ID stands for all of its options, and a `random_list` ID for all of its entries.
+
+Without `scenarioSet` the evaluation uses one scenario with no declared facts.
+Conditions that need facts stay unresolved, and `missingInputs` lists the facts to declare in a `scenarioSet` for the next call.
+The inline `ranking` shows, for up to four scenarios, the twelve strongest candidates with eligibility, weight, probability and MTTH; the linked resource holds every candidate's trace.
+
+```json
+{ "candidatePool": ["my_mod.12"] }
+```
+
+```json
+{
+  "source": { "path": "common/decisions/my_decisions.txt" },
+  "candidatePool": ["my_decision_a", "my_decision_b"],
+  "scenarioSet": [{ "actor": "GER", "state": { "has_war": true } }]
+}
+```
+
+When a named adapter does not match the source, such as `decision_ai_will_do` for a mission, inspection switches to the matching adapter.
+Set `evaluate: false` for the inventory alone: compatible adapters, candidate counts, example IDs, and the required inputs of the selected source.
 
 Source request paths are exact workspace-relative files, such as `common/decisions/example.txt`.
 The `mod:`, `game:`, and `dependency-N:` labels in returned source citations identify origins; they are not part of a probability request's `source.path`.
 
 For a selected source, `hoi4.probability_inspect` includes missing source-condition fields in compact `requiredInputPaths`, adapter-wide completeness flags in `adapterRequiredInputPaths`, and the full candidate catalog, source provenance, and per-candidate requirements in its JSON resource. Unsupported source constructs remain unresolved evidence rather than being presented as scenario inputs. Evaluation reports eligible, excluded, and unresolved candidate counts inline; the resource preserves each candidate's exact eligibility and unresolved reasons for every scenario.
 
-Evaluation, sweep, simulation, and source comparison also accept an omitted adapter. When a source selector identifies one unambiguous weighted surface, the analyzer selects that source-backed adapter automatically. If a caller supplies a mismatched adapter or `custom_weighted_pool` for a source-backed request, the analyzer corrects it when the source has exactly one match. `customPoolManifest`, `beforeManifest`, and `afterManifest` use the custom-pool adapter automatically; `PROBABILITY_SURFACE_EMPTY` is reserved for sources with no weighted surface, while genuinely multi-adapter sources ask the caller to narrow by identifier or line.
+Inspection, sweeps, simulation and source comparison also accept an omitted adapter. When a source selector identifies one unambiguous weighted surface, the analyzer selects that source-backed adapter automatically. If a caller supplies a mismatched adapter or `custom_weighted_pool` for a source-backed request, the analyzer corrects it when the source has exactly one match. `customPoolManifest`, `beforeManifest`, and `afterManifest` use the custom-pool adapter automatically; `PROBABILITY_SURFACE_EMPTY` is reserved for sources with no weighted surface, while genuinely multi-adapter sources ask the caller to narrow by identifier or line.
 
 ## 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`.
+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_analyze` with `analysis: simulate`.
+A scenario set may be sent as a bare list of scenarios, and scenarios without `id` or `state` get `scenario-1`, `scenario-2` and an empty state.
 
 ```json
 {
@@ -99,6 +124,8 @@ Decision and mission adapters intentionally return scores and ranks without inve
 
 `candidateOverrides` declares candidate eligibility for a scenario. It does not force weight-modifier conditions to be true or false; those conditions still use the scenario's actual declared variables, flags, scopes, and controller facts. An overridden eligibility claim is an explicit scenario assumption, not evidence that the engine makes that candidate available.
 
+`analysis: sweep` takes a `sweep` object with 1 to 32 input `paths`, `steps` from 2 to 10,000 (default 25), `pairwise` (default `false`), and `findRankReversals` (default `true`).
+
 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
@@ -118,11 +145,14 @@ Every evaluated scope pool is stored with the scenario in authoritative JSON. Po
 
 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.
 
+`analysis: simulate` defaults to `samples: 100000` (range 100 to 10,000,000), `seed: 1` (any 32-bit signed integer), `confidenceLevel: 0.95` (range 0.5 to 0.9999), and `samplingMethod: "latin_hypercube"`; the other sampling method is `pseudo_random`.
+`analysis: sequence` uses the same `samples`, `seed`, and `confidenceLevel` defaults, requires `horizonDays`, and defaults `maxSteps` to 1,000 (range 1 to 100,000).
+
 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.
+Pass `inlineClausewitz` or `virtualPatch` in a source selector to analyze text without writing it. `hoi4.probability_analyze` with `analysis: compare` evaluates the before and after source under the same scenarios and attributes each changed rank, score, probability, or uncertainty to its modifier trace.
 
 For a frozen file stored outside its gameplay folder, set the source selector's `path` to its logical gameplay path, `snapshotPath` to the preserved workspace-relative file, and `expectedSourceHash` to the SHA-256 of that file's exact bytes. For example, a decision copy in `docs/evidence/decisions-before.txt` can be analyzed as `common/decisions/policy.txt`. The server verifies the frozen bytes and retains their physical source provenance while using the logical path for domain recognition. It never replaces the current file. Both paths must identify exact files inside authorized roots; traversal and wildcard selectors are rejected. Shared helpers and constants still come from the current configured workspace, so one frozen file is not a complete historical workspace snapshot.
 
@@ -132,7 +162,7 @@ Sequence analysis accepts a `customPoolManifest`. The manifest is the complete m
 
 ## 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.
+`analysis: render` with the `analysisId` of a retained analysis 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).
 

package/docs/reference.md

@@ -1,6 +1,7 @@
 # Local references and source lookup
 
-The reference tools read only local, authorized sources. They do not fetch the Paradox Wiki or start Hearts of Iron IV. The installed game's documentation has the highest authority for current syntax; the offline wiki supplies broader modding guidance. A result identifies its source, path, exact lines, and SHA-256 revision so an agent can inspect only the relevant section.
+Find the right modding rule and see how vanilla uses it. The tools search local game documentation, an offline wiki and your mod source.
+The installed game docs define current syntax; the wiki supplies broader guidance. Each result includes its file, lines and source revision.
 
 The server discovers these directories for a workspace:
 
@@ -14,13 +15,13 @@ Markdown headings and recognizable standalone names in generated `.log` files fo
 
 ## Tools
 
-- `hoi4.reference_context`: request a surface such as `event`, `focus`, `technology`, `gui`, or `map`. It reserves citations for available installed documentation and offline wiki sources before adding further question matches. Supply `question` to select the best matching section within each required source. At a limit of two or more, both source kinds are represented when available; a one-result limit prioritizes installed documentation. `omittedSources` names required sources excluded by the result limit, while `missing` names sources absent from the configured roots. Increase the limit or search an omitted source directly before treating the bundle as sufficient. Citations are pointers and excerpts; read the pertinent sections before changing code.
+- `hoi4.reference_context`: request one surface: `general`, `event`, `decision`, `idea`, `focus`, `technology`, `gui`, `map`, `localisation`, or `ai`. The default limit is 16 citations and the maximum is 24. It reserves citations for available installed documentation and offline wiki sources before adding further question matches. Supply `question` to select the best matching section within each required source. At a limit of two or more, both source kinds are represented when available; a one-result limit prioritizes installed documentation. `omittedSources` names required sources excluded by the result limit, while `missing` names sources absent from the configured roots. Increase the limit or search an omitted source directly before treating the bundle as sufficient. Citations are pointers and excerpts; read the pertinent sections before changing code.
 - `hoi4.reference_search`: search with plain words or exact script tokens. Ranking weighs headings above body text and rare words above common ones, and it matches identifiers both whole and by their words, so "check if a state is controlled by a country" can find `is_controlled_by`. A query that names an identifier only matches sections containing it, an exact heading ranks first, and installed documentation precedes the wiki when they rank equally. Each result's `matchLine` is the cited line that best matches the query; pass it as `startLine` to `hoi4.reference_read` to land on the answer inside a long section. When several sources document the same name, the first copy keeps its place and later copies follow other distinct answers. The default limit is six results and the maximum is twelve. Filter `sources` to `game_doc`, `wiki`, or `script_doc` when appropriate. Only selected authorities are scanned; `coverage.included = false` means that an authority was excluded from this query, not that it is missing.
-- `hoi4.reference_read`: provide a search/context result's `id` and `revision`. Optionally pass its `source` for a focused authority read; resident citations provide this hint automatically. Read up to 80 lines and 8,000 UTF-8 bytes, with JSON escaping also bounded. Continue with the returned `nextLine`, `nextColumn` as `startColumn`, and the same revision. Long source lines continue without losing characters. A changed source returns `REFERENCE_REVISION_STALE`.
+- `hoi4.reference_read`: provide a search/context result's `id` and `revision`. Optionally pass its `source` for a focused authority read; resident citations provide this hint automatically. Read 40 lines by default, set `maxLines` up to 80, and at most 8,000 UTF-8 bytes, with JSON escaping also bounded. Continue with the returned `nextLine`, `nextColumn` as `startColumn`, and the same revision. Long source lines continue without losing characters. A changed source returns `REFERENCE_REVISION_STALE`.
 - `hoi4.source_lookup`: find exact definitions and indexed usages in the installed game and configured mod source. The response includes load order, override status, up to three source blocks bounded to 2,000 bytes each, a scan revision, and explicit reference counts and truncation. Follow `nextLine` and `nextColumn` as `fromLine` and `fromColumn`, with `expectedRevision`, to read more of the active definition.
 - When `hoi4.source_lookup` finds no definition, `suggestions` lists up to five indexed identifiers within three edits of the requested symbol, nearest first, which catches typos and near-miss names.
 - `hoi4.source_lookup` with `path` and `line` instead of `symbol` locates a source position, such as a diagnostic or a changed line in a diff. `path` may be a result path such as `mod:events/example.txt`, a path relative to a source root, or an absolute path inside one. The result names the file's layer and whether a later layer shadows it, the indexed definitions that contain the line, innermost first, and the chain of enclosing assignments with zero-based occurrences for repeated keys. Its `keyPath` starts inside the innermost definition: pass that definition's `id` as `symbol`, its `kind`, and the `keyPath` to read or list that exact block. Without `column`, the first non-blank character of the line is used. A file with parse errors returns its definitions but no structural chain. Only the requested file's folder is scanned, in every layer.
-- `hoi4.script_validate`: check a bounded effect or trigger body against installed native-command documentation. Supply the body in `source`, its `kind`, and its current `scope`. Results cover syntax, command kind, and declared scope, with exact documentation citations. They do not validate command parameters or prove game execution.
+- `hoi4.script_validate`: check a bounded effect or trigger body against installed native-command documentation. Supply the body in `source`, its `kind`, and its current `scope` (`country`, `state`, `character`, `combatant`, `ace`, `strategic_region`, `operation`, `industrial_org`, `purchase_contract`, `raid_instance`, `special_project`, or `faction`). `limit` (1–32, default 12) bounds the returned findings. Results cover syntax, command kind, and declared scope, with exact documentation citations. They do not validate command parameters or prove game execution.
 - `hoi4.script_validate` with `path` instead of `source` checks a whole mod file: every effect and trigger body of an event, decision, national focus, scripted effect, scripted trigger, or on-action file, with the scope the file's structure fixes. It is meant to catch the game's own load errors before launch.
 
 ## Navigate a definition
@@ -96,11 +97,78 @@ File mode reports `SCRIPT_EVENT_POPUP_REPEATED` warnings for any family and adds
 A visible event fired inside an `every_*` loop reaches one player once per loop member when it is sent to a fixed recipient (`ROOT`, `FROM`, `PREV`, `global`, a tag, an `event_target:` or a `var:` scope), or when it is `major = yes` without `fire_only_once`, because a major event is shown to every country.
 An event sent to each loop member in turn, a hidden event, and an event the scanned sources do not define are not reported.
 Scripted effects called inside a loop are checked in their own file, not followed from the caller.
+
+### Known mistakes
+
+File mode also applies a short, reviewed list of mistakes that the game accepts silently or reports with an unhelpful message, and adds `known_mistakes` to `checksPerformed`.
+Each finding is `KNOWN_MISTAKE_<RULE>` with the symptom and the fix in its message.
+A finding that makes a definition not work (`error`) sets `valid` to `false`; the others are warnings.
+
+| Rule                             | Status  | Flags                                                                                                       |
+| -------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
+| `event_namespace_missing`        | error   | An event id whose namespace no events file declares with `add_namespace` (the game logs "Malformed token"). |
+| `event_numeric_id_invalid`       | error   | An event number that is not a whole number from 0 to 99999, so events share an internal id.                 |
+| `event_triggered_only_with_mtth` | warning | `mean_time_to_happen` on an `is_triggered_only = yes` event, which never runs the timer.                    |
+| `event_fires_every_day`          | warning | An automatic, repeatable event with no `mean_time_to_happen` or one of a day or less.                       |
+| `news_event_not_major`           | warning | A `news_event` without `major = yes`, or one that also sets `fire_only_once = yes`.                         |
+| `event_date_window_too_tight`    | warning | An automatic event whose `date` bounds are less than the 20-day trigger check apart.                        |
+| `temp_variable_scope_prefix`     | warning | A scope prefix such as `ROOT.amount` on a variable the file only sets as a temporary variable.              |
+
+The rules come from the offline wiki's Event modding "Common mistakes" and Data structures pages; each rule in `src/hoi4_agent_tools/reference/known-mistakes.json` names its source page, heading and item, and has a detector that reads the parsed file.
+`hoi4.reference_context` lists the rules of the requested surface as `knownMistakes` (id, title and fix) so an author can read them before editing, and `hoi4.error_log` adds `knownMistake` to a logged message that a rule explains.
+The list is shipped with the server and changes only through a reviewed commit; see [Development](development.md#adding-a-known-mistake) for how a rule is added, and how one that no longer applies is resolved.
+
 Search and context replies also report `limitedByBytes` when metadata exceeds their reply budget.
 Read omitted required sources with targeted calls rather than repeatedly requesting the same oversized bundle.
 Reference text supports UTF-8, Windows-1252, and explicitly BOM-marked UTF-16; native engine source encoding rules remain separate.
 
-Example:
+## Read the game's error log
+
+`hoi4.error_log` reads `logs/error.log` from the game's user folder, the folder that also holds `mod/` and `save games/`.
+The server finds it from the configured `gameUserRoot`, then the user folder that contains the mod when the mod sits in its `mod/` folder, then the operating system's default user folder locations.
+It reads the last 16 MiB of the log, joins continuation lines, and groups identical messages with a count.
+
+Each entry has a `category`: `syntax`, `duplicate`, `localisation`, `effect`, `trigger`, `scope`, `graphics`, `interface`, `map`, `missing_reference`, or `other`.
+When the message names a file, the entry gives the file, the line when known, and its layer (`mod`, `dependency`, `game`, or `unknown`).
+`changedSinceLog` is `true` when that file was modified after the log was written, so the error may already be fixed; relaunch the game to confirm.
+Mod entries are listed first.
+
+Each category in `categories` carries a `hint` that says what usually fixes it and which tool narrows it down.
+`patterns` groups messages that differ only in names, numbers, quoted values and paths, such as a run of missing localisation keys, so a flood of one mistake reads as one line with its count.
+An entry whose message is one of the game's wording for a [known mistake](#known-mistakes) carries `knownMistake` with the rule id and the documented fix.
+
+The server remembers the entries of each log it reads in its own cache, keyed by the log's write time.
+When the game has been relaunched since, `sinceLastLaunch` says how many entries are new, how many persist and how many the last fixes removed, with examples of the removed ones, and every entry carries `new`.
+
+Filter with `scope` (`all`, `mod` for entries in the mod's own files, or `unlocated` for entries naming no file), `category`, or a text `query`, and page with `limit` (1–50, default 20) and `offset`.
+
+```json
+{ "scope": "mod", "category": "scope", "limit": 10 }
+```
+
+The tool reads the log the game wrote at its last launch; it never starts the game.
+Run `hoi4.script_validate` with `path` on the reported file to check the same body before the next launch.
+
+## Index the mod and pick free IDs
+
+`hoi4.mod_index` with `mode: "overview"` summarizes the mod without reading every file:
+
+- `descriptor`: the `descriptor.mod` name, version, supported game version, tags, dependencies, `replace_path` entries and Workshop ID;
+- `kinds`: how many definitions of each kind the mod contains, such as events, focuses, decisions and scripted effects;
+- `folders`: file counts and sizes per top-level folder, and per `common/` subfolder;
+- `namespaces`: each event namespace with its number of events, lowest and highest number, and file count.
+
+Set `layer: "all"` to count active definitions across the game, DLC, dependencies and the mod instead of the mod alone.
+
+`mode: "next_id"` finds the next free numbered identifier for an event `namespace` or any `prefix` of one `kind` (`event`, `focus`, `decision`, `idea`, `leader` or `technology`).
+It checks every source layer, so a new ID never collides with a game or dependency definition.
+The result gives `nextId` after the highest used number, and `firstGapId` when a lower number is unused.
+
+```json
+{ "mode": "next_id", "kind": "event", "namespace": "my_mod" }
+```
+
+## Example
 
 ```json
 { "workspaceId": "current", "surface": "event", "question": "save_event_target_as" }