hoi4-agent-tools 2.5.3 → 2.6.0

package/docs/map.md

@@ -2,38 +2,75 @@
 
 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.
 
-## Create or reshape map content
+## Inspect and navigate the complete map
 
-Map changes may add, split, merge, remove, or redefine provinces and states; update strategic regions; edit normal or special adjacency; and update supply, railway, building, unit, or weather positions.
+`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.
 
-Geometry must be exact. Use existing province IDs, integer polygon boundaries with the required fill rule, a validated raster mask, or explicit pixels. Natural-language geography can guide an agent, but it is not rewrite geometry.
+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.
 
-Pass up to 32 `provinceIds` to `hoi4.map_inspect` to receive a linked exact-geometry JSON artifact. It records the active map dimensions, unknown IDs, and each known province as maximal `[y, startX, endXExclusive]` runs sorted in top-left raster order. Derive a bounded pixel subset or mask from those runs before calling `hoi4.map_rewrite`; row runs are inspection evidence, not a rewrite geometry kind.
+Use `query` for a compact name or ID result list and `coordinates` for exact pixel or map-coordinate lookup. Use `provinceIds`, `stateIds`, and `regionIds` for focused records. Up to 32 selected provinces can also produce exact geometry as maximal `[y, startX, endXExclusive]` row runs.
 
-For state or province moves, splits, merges, removals, or type changes, explicitly state what happens to applicable data:
+`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.
 
-- state membership and strategic region membership;
-- manpower, resources, buildings, and victory points;
-- owner, controller, cores, and claims;
-- ports, supply nodes, and railways;
-- building, unit, weather, and entity positions;
-- normal and special adjacency;
-- state localisation.
+## Create states
 
-Build one ordered list of exact operations, call `hoi4.map_rewrite`, and review its before, proposed, and changed-area evidence. Then inspect and render the result.
+The compact `create_state` form needs selected provinces and a display name:
 
-## Inspect and clean a map
+```json
+{
+  "id": "create-western-state",
+  "kind": "create_state",
+  "provinceIds": [120, 121, 122],
+  "displayName": "Western Ireland"
+}
+```
 
-1. Inspect the affected map area and read reference diagnostics.
-2. Render a baseline with the relevant province, state, region, terrain, coastline, supply, railway, ownership, or building overlays.
-3. Build one ordered list of exact repair operations.
-4. Supply every required geometry and data-movement choice.
-5. Rewrite, then inspect and render the result.
+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.
 
-Common cleanup work includes duplicate IDs or colors, bitmap/definition mismatches, invalid state or region membership, broken adjacency, missing localisation, disconnected province geometry, invalid ports or victory points, and stale supply or railway references.
+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.
 
-The map tools do not infer a corridor, choose a replacement province, redistribute state data, reconnect a railway, or move a port without an explicit instruction. ID and color allocation checks the configured game, dependencies, and mod before choosing a value.
+## Create provinces
 
-## Review boundary
+The compact `create_province` form needs a source province and exact geometry:
 
-Map renders are offline evidence. Final inspection checks that references remain valid and changes stay within the declared geometry. Unsupported or ambiguous changes stop with a blocker instead of applying a partial substitute.
+```json
+{
+  "id": "create-western-province",
+  "kind": "create_province",
+  "sourceProvinceId": 4812,
+  "geometry": {
+    "kind": "rectangle",
+    "origin": { "x": 2330, "y": 740 },
+    "width": 12,
+    "height": 9
+  }
+}
+```
+
+Geometry may be a rectangle, an even-odd polygon, explicit pixels, or a hash-bound raster mask. The tool allocates an unused contiguous province ID and unused RGB color after scanning game, dependencies, and mod sources. By default it inherits the source definition, state and strategic-region membership, and retains connected data on the source unless the new province itself must receive it.
+
+Pass `provinceId`, `definition`, or the full distribution object when an exact override is needed. All selected pixels must belong to the named source province; this keeps a creation request deterministic.
+
+## Change IDs
+
+Use `renumber_map_entity` for `province`, `state`, or `strategic-region` IDs:
+
+```json
+{
+  "id": "swap-state-ids",
+  "kind": "renumber_map_entity",
+  "entity": "state",
+  "fromId": 12,
+  "toId": 18
+}
+```
+
+If the destination exists, the default behavior swaps the two IDs. Province swaps update definitions, state and region membership, victory points, province buildings, adjacency, supply nodes, railways, unit positions, building sea references, and standard province and victory-point localisation keys. State swaps update state records, standard state localisation keys, and building-position state references. Strategic-region swaps update region records, standard localisation keys, and weather-position references. Province and strategic-region operations preserve their required contiguous ID sets.
+
+Set `collision` to `reject` to require an unused destination. Set `renameLocalisation` to `false` only when custom localisation-key handling is intentional.
+
+## 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.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hoi4-agent-tools",
   "mcpName": "io.github.klimPaskov/hoi4-agent-tools",
-  "version": "2.5.3",
+  "version": "2.6.0",
   "description": "Analyze HOI4 events, tech trees, AI weights, and MTTH; build focus trees, GUIs, and maps.",
   "type": "module",
   "license": "Apache-2.0",

package/schemas/configuration.schema.json

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

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

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.3/schemas/continuous-focus-palette.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.6.0/schemas/continuous-focus-palette.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/custom-weighted-pool.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.3/schemas/custom-weighted-pool.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.6.0/schemas/custom-weighted-pool.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/event-feature-manifest.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.3/schemas/event-feature-manifest.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.6.0/schemas/event-feature-manifest.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/focus-plan.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.3/schemas/focus-plan.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.6.0/schemas/focus-plan.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/focus-planning-sidecar.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.3/schemas/focus-planning-sidecar.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.6.0/schemas/focus-planning-sidecar.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/gui-animation-source.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.3/schemas/gui-animation-source.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.6.0/schemas/gui-animation-source.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/gui-helper.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.3/schemas/gui-helper.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.6.0/schemas/gui-helper.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/gui-scenario.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.3/schemas/gui-scenario.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.6.0/schemas/gui-scenario.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {