hoi4-agent-tools 2.5.2 → 2.6.0

package/dist/hoi4_agent_tools/technology/render.js

@@ -47,6 +47,7 @@ function technologyNode(graph, technologyId, placement) {
         sourcePath: technology.source.path,
         sourceLine: technology.source.location.start.line,
         layoutSize: technology.layoutSize,
+        iconSprite: technology.icon.sprite,
         ...(placement === undefined ? {} : { placement }),
     };
 }
@@ -152,6 +153,7 @@ function viewSelection(graph, options) {
                 kind: 'doctrine',
                 sourcePath: definition.source.path,
                 sourceLine: definition.source.location.start.line,
+                ...(definition.icon === undefined ? {} : { iconSprite: definition.icon.sprite }),
             });
         for (const definition of graph.doctrineDefinitions) {
             const from = `doctrine:${definition.kind}:${definition.id}`;
@@ -203,6 +205,7 @@ function viewSelection(graph, options) {
                 kind: 'doctrine',
                 sourcePath: doctrine.source.path,
                 sourceLine: doctrine.source.location.start.line,
+                ...(doctrine.icon === undefined ? {} : { iconSprite: doctrine.icon.sprite }),
             });
             for (const targetId of doctrine.exclusiveIds) {
                 const target = graph.doctrineDefinitions.find(({ id }) => id === targetId);
@@ -215,7 +218,11 @@ function viewSelection(graph, options) {
                         kind: target === undefined ? 'unresolved' : 'doctrine',
                         ...(target === undefined
                             ? {}
-                            : { sourcePath: target.source.path, sourceLine: target.source.location.start.line }),
+                            : {
+                                sourcePath: target.source.path,
+                                sourceLine: target.source.location.start.line,
+                                ...(target.icon === undefined ? {} : { iconSprite: target.icon.sprite }),
+                            }),
                     });
                 edges.push({ id: `${from}:xor:${to}`, from, to, kind: 'exclusive' });
             }
@@ -537,7 +544,7 @@ function colours(kind) {
         removed: { fill: '#4a2828', stroke: '#ef7d7d' },
     }[kind];
 }
-function svgFor(titleText, positioned, edges, sourceAccurate) {
+function svgFor(titleText, positioned, edges, sourceAccurate, iconDataUris) {
     const maximumX = Math.max(PADDING + LARGE_NODE_WIDTH, ...positioned.map(({ x, width }) => x + width));
     const maximumY = Math.max(HEADER_HEIGHT + LARGE_NODE_HEIGHT, ...positioned.map(({ y, height }) => y + height));
     const width = Math.ceil(maximumX + PADDING);
@@ -566,28 +573,45 @@ function svgFor(titleText, positioned, edges, sourceAccurate) {
     const nodeSvg = positioned.map((node) => {
         const colour = colours(node.kind);
         const small = node.layoutSize === 'small';
+        const iconDataUri = node.iconSprite === undefined ? undefined : iconDataUris[node.iconSprite];
+        const compactIcon = iconDataUri !== undefined && small && node.width <= SMALL_NODE_WIDTH;
+        const iconSize = iconDataUri === undefined
+            ? 0
+            : compactIcon
+                ? Math.max(1, Math.min(node.width - 12, node.height - 12))
+                : Math.max(1, Math.min(64, node.height - 16, Math.floor(node.width * 0.36)));
+        const textInset = iconDataUri === undefined ? (small ? 6 : 12) : iconSize + 18;
+        const availableTextWidth = Math.max(1, node.width - textInset - (small ? 6 : 12));
         const labelLimit = small ? 12 : 34;
         const label = node.label.length > labelLimit
             ? `${node.label.slice(0, Math.max(1, labelLimit - 1))}…`
             : node.label;
         const subtitle = node.subtitle.length > 48 ? `${node.subtitle.slice(0, 45)}…` : node.subtitle;
-        const labelSvg = text.render(label, {
-            x: node.x + (small ? 6 : 12),
-            y: node.y + (small ? 27 : 30),
-            fontSize: small ? 9 : 15,
-            fill: '#f1f5f8',
-            weight: 600,
-            targetWidth: Math.min(node.width - (small ? 12 : 24), Math.max(1, text.measure(label, small ? 9 : 15))),
-        });
-        const subtitleSvg = text.render(small ? 'SMALL' : subtitle, {
-            x: node.x + (small ? 6 : 12),
-            y: node.y + (small ? 51 : 58),
-            fontSize: small ? 8 : 11,
-            fill: '#b8c4ce',
-            targetWidth: Math.min(node.width - (small ? 12 : 24), Math.max(1, text.measure(small ? 'SMALL' : subtitle, small ? 8 : 11))),
-        });
+        const labelSvg = compactIcon
+            ? ''
+            : text.render(label, {
+                x: node.x + textInset,
+                y: node.y + (small ? 27 : 30),
+                fontSize: small ? 9 : 15,
+                fill: '#f1f5f8',
+                weight: 600,
+                targetWidth: Math.min(availableTextWidth, Math.max(1, text.measure(label, small ? 9 : 15))),
+            });
+        const subtitleSvg = compactIcon
+            ? ''
+            : text.render(small ? 'SMALL' : subtitle, {
+                x: node.x + textInset,
+                y: node.y + (small ? 51 : 58),
+                fontSize: small ? 8 : 11,
+                fill: '#b8c4ce',
+                targetWidth: Math.min(availableTextWidth, Math.max(1, text.measure(small ? 'SMALL' : subtitle, small ? 8 : 11))),
+            });
+        const iconSvg = iconDataUri === undefined
+            ? ''
+            : `<image href="${escapeXml(iconDataUri)}" x="${node.x + (compactIcon ? 6 : 8)}" y="${node.y + (node.height - iconSize) / 2}" width="${iconSize}" height="${iconSize}" preserveAspectRatio="xMidYMid meet"/>`;
         const layoutAttribute = node.layoutSize === undefined ? '' : ` data-layout-size="${node.layoutSize}"`;
-        return `<g data-node-id="${escapeXml(node.id)}"${layoutAttribute}${node.sourcePath === undefined ? '' : ` data-source-path="${escapeXml(node.sourcePath)}" data-source-line="${node.sourceLine ?? 1}"`}><rect x="${node.x}" y="${node.y}" width="${node.width}" height="${node.height}" rx="8" fill="${colour.fill}" stroke="${colour.stroke}" stroke-width="2"/><title>${escapeXml(`${node.id}${node.layoutSize === undefined ? '' : ` · ${node.layoutSize} layout`}${node.sourcePath === undefined ? '' : ` · ${node.sourcePath}:${node.sourceLine ?? 1}`}`)}</title>${labelSvg}${subtitleSvg}</g>`;
+        const iconAttribute = node.iconSprite === undefined ? '' : ` data-icon-sprite="${escapeXml(node.iconSprite)}"`;
+        return `<g data-node-id="${escapeXml(node.id)}"${layoutAttribute}${iconAttribute}${node.sourcePath === undefined ? '' : ` data-source-path="${escapeXml(node.sourcePath)}" data-source-line="${node.sourceLine ?? 1}"`}><rect x="${node.x}" y="${node.y}" width="${node.width}" height="${node.height}" rx="8" fill="${colour.fill}" stroke="${colour.stroke}" stroke-width="2"/><title>${escapeXml(`${node.id}${node.layoutSize === undefined ? '' : ` · ${node.layoutSize} layout`}${node.sourcePath === undefined ? '' : ` · ${node.sourcePath}:${node.sourceLine ?? 1}`}`)}</title>${iconSvg}${labelSvg}${subtitleSvg}</g>`;
     });
     const title = text.render(titleText, {
         x: PADDING,
@@ -616,7 +640,13 @@ export async function renderTechnologyGraph(graph, options) {
     const positioned = selection.sourceAccurate
         ? layoutFolder(retained)
         : layoutGenerated(retained, edges);
-    const rendered = svgFor(selection.title, positioned, edges, selection.sourceAccurate);
+    const iconDataUris = options.iconDataUris ?? {};
+    const requestedIconSprites = [
+        ...new Set(retained.flatMap(({ iconSprite }) => (iconSprite === undefined ? [] : [iconSprite]))),
+    ].sort(compareCodeUnits);
+    const renderedIconSprites = requestedIconSprites.filter((sprite) => iconDataUris[sprite] !== undefined);
+    const unresolvedIconSprites = requestedIconSprites.filter((sprite) => iconDataUris[sprite] === undefined);
+    const rendered = svgFor(selection.title, positioned, edges, selection.sourceAccurate, iconDataUris);
     const budget = options.budget ?? new RenderBudget();
     budget.reserve(rendered.width, rendered.height, `technology ${options.view} render`);
     budget.reserveRasterOperation(`technology-render:${graph.revision}:${options.view}:${sha256Bytes(rendered.svg)}`, `technology ${options.view} rasterization`);
@@ -631,6 +661,11 @@ export async function renderTechnologyGraph(graph, options) {
         nodes: retained,
         edges,
         omittedNodeCount: Math.max(0, selection.nodes.length - retained.length),
+        iconCoverage: {
+            requested: requestedIconSprites.length,
+            rendered: renderedIconSprites.length,
+            unresolvedSprites: unresolvedIconSprites,
+        },
         render: { width: rendered.width, height: rendered.height },
     })}\n`;
     const html = options.includeHtml === true ? htmlFor(selection.title, rendered.svg, json) : undefined;
@@ -639,6 +674,8 @@ export async function renderTechnologyGraph(graph, options) {
         graphRevision: graph.revision,
         selectedIds: retained.map(({ id }) => id),
         omittedNodeCount: Math.max(0, selection.nodes.length - retained.length),
+        renderedIconCount: renderedIconSprites.length,
+        unresolvedIconSprites,
         sourceAccurate: selection.sourceAccurate,
         generatedAnalysisLayout: !selection.sourceAccurate,
         width: rendered.width,
@@ -655,3 +692,12 @@ export async function renderTechnologyGraph(graph, options) {
         },
     };
 }
+/** Return only the sprite names that the bounded render selection will display. */
+export function technologyRenderIconSprites(graph, options) {
+    const maximum = Math.max(1, Math.min(options.maxNodes ?? 600, MAX_RENDER_NODES));
+    return [
+        ...new Set(viewSelection(graph, options)
+            .nodes.slice(0, maximum)
+            .flatMap(({ iconSprite }) => (iconSprite === undefined ? [] : [iconSprite]))),
+    ].sort(compareCodeUnits);
+}

package/dist/hoi4_agent_tools/technology/service.js

@@ -6,10 +6,12 @@ import { ServiceError } from '../core/result.js';
 import { SOURCE_MAX_BYTES } from '../core/source/index.js';
 import { isPortablePathSegment } from '../core/workspace.js';
 import { PACKAGE_VERSION } from '../version.js';
+import { GuiAssetCatalog } from '../gui/assets.js';
+import { buildGuiSourceGraph } from '../gui/source-graph.js';
 import { compareTechnologyGraphs } from './compare.js';
 import { buildTechnologyGraph, technologyAssetPatterns } from './graph.js';
 import { analyzeTechnologyImpact, discoverTechnologyFolders, explainTechnology, inspectTechnologyUnlocks, lintTechnologyGraph, technologyBonusCoverage, technologyScanReport, traceTechnology, } from './queries.js';
-import { renderTechnologyGraph, } from './render.js';
+import { renderTechnologyGraph, technologyRenderIconSprites, } from './render.js';
 const FRAGMENT_CACHE_ENTRIES = 8_192;
 const FRAGMENT_CACHE_BYTES = 134_217_728;
 const PROPOSED_SOURCE_FILES = 128;
@@ -80,10 +82,54 @@ function technologyScanPatterns(workspace) {
         'history/countries/**/*.txt',
         ...under(roots.focus, '**/*.txt'),
         ...under(roots.interface, '**/*.gui'),
+        ...under(roots.interface, '**/*.gfx'),
+        ...under(roots.gfx, '**/*.gfx'),
         ...under(roots.localisation, 'english/**/*.{yml,yaml}'),
         ...under(roots.localisation, '*.{yml,yaml}'),
     ].sort(compareCodeUnits);
 }
+function activeTechnologySprite(spriteName, spritePath, sprites) {
+    return sprites.find((sprite) => sprite.name === spriteName && (spritePath === undefined || sprite.sourcePath === spritePath));
+}
+async function resolveTechnologyIconDataUris(cached, requestedSprites, budget, signal) {
+    const icons = [
+        ...cached.graph.technologies.map(({ icon }) => icon),
+        ...cached.graph.doctrineDefinitions.flatMap(({ icon }) => icon ?? []),
+    ].filter(({ sprite }) => requestedSprites.has(sprite));
+    const spriteSourcePaths = new Set(icons.flatMap(({ spritePath }) => (spritePath === undefined ? [] : [spritePath])));
+    const spriteFiles = cached.snapshot.files.filter(({ displayPath }) => spriteSourcePaths.has(displayPath));
+    if (spriteFiles.length === 0)
+        return {};
+    const graph = buildGuiSourceGraph(spriteFiles, cached.snapshot.index);
+    const files = new Map();
+    for (const file of [...spriteFiles, ...cached.assetFiles])
+        files.set(file.displayPath, file);
+    const catalog = new GuiAssetCatalog(graph, [...files.values()], budget);
+    const unique = new Map();
+    for (const icon of icons)
+        if (!unique.has(icon.sprite))
+            unique.set(icon.sprite, icon);
+    const entries = [...unique.entries()].sort(([left], [right]) => compareCodeUnits(left, right));
+    const dataUris = {};
+    let cursor = 0;
+    await Promise.all(Array.from({ length: Math.min(8, entries.length) }, async () => {
+        while (cursor < entries.length) {
+            signal?.throwIfAborted();
+            const entry = entries[cursor];
+            cursor += 1;
+            if (entry === undefined)
+                continue;
+            const [spriteName, icon] = entry;
+            const sprite = activeTechnologySprite(spriteName, icon.spritePath, graph.sprites);
+            if (sprite === undefined)
+                continue;
+            const frame = await catalog.loadSpriteFrame(sprite, 0);
+            if (frame?.supported === true && frame.dataUri !== undefined)
+                dataUris[spriteName] = frame.dataUri;
+        }
+    }));
+    return Object.fromEntries(Object.entries(dataUris).sort(([left], [right]) => compareCodeUnits(left, right)));
+}
 function technologyAnalysisMode(workspace, snapshot) {
     return workspace.gameRoot !== undefined || snapshot.files.length > FOCUSED_GRAPH_FILE_THRESHOLD
         ? 'focused'
@@ -462,6 +508,9 @@ export class TechnologyTreeViewer {
             ...(input.signal === undefined ? {} : { signal: input.signal }),
         });
         const budget = new RenderBudget();
+        const cached = this.#state.current.get(input.workspaceId);
+        if (cached?.graph.revision !== graph.revision)
+            throw new ServiceError('TECH_RENDER_SOURCE_MISSING', 'Technology render source inventory is unavailable for the current graph');
         const renderOptions = {
             view: input.view,
             maxNodes: input.maxNodes ?? 1_000,
@@ -473,13 +522,23 @@ export class TechnologyTreeViewer {
             ...(input.targetId === undefined ? {} : { targetId: input.targetId }),
             ...(input.signal === undefined ? {} : { signal: input.signal }),
         };
-        const render = await renderTechnologyGraph(graph, renderOptions);
-        const focused = [];
         const focusedFolders = input.view === 'dependencies' && input.folderId === undefined
             ? graph.folders
                 .filter((folder) => graph.placements.some(({ folderId }) => folderId === folder.id))
                 .slice(0, FOCUSED_RENDER_LIMIT)
             : [];
+        const requestedIconSprites = new Set([
+            ...technologyRenderIconSprites(graph, renderOptions),
+            ...focusedFolders.flatMap(({ id }) => technologyRenderIconSprites(graph, {
+                view: 'folder',
+                folderId: id,
+                maxNodes: 1_000,
+            })),
+        ]);
+        const iconDataUris = await resolveTechnologyIconDataUris(cached, requestedIconSprites, budget, input.signal);
+        renderOptions.iconDataUris = iconDataUris;
+        const render = await renderTechnologyGraph(graph, renderOptions);
+        const focused = [];
         for (const folder of focusedFolders) {
             input.signal?.throwIfAborted();
             focused.push(await renderTechnologyGraph(graph, {
@@ -487,6 +546,7 @@ export class TechnologyTreeViewer {
                 folderId: folder.id,
                 maxNodes: 1_000,
                 includeHtml: false,
+                iconDataUris,
                 budget,
                 ...(input.signal === undefined ? {} : { signal: input.signal }),
             }));
@@ -516,6 +576,8 @@ export class TechnologyTreeViewer {
                 omittedNodeCount: render.omittedNodeCount,
                 sourceAccurate: render.sourceAccurate,
                 generatedAnalysisLayout: render.generatedAnalysisLayout,
+                renderedIconCount: render.renderedIconCount,
+                unresolvedIconSprites: render.unresolvedIconSprites,
                 hashes: render.hashes,
             },
             focusedFolders: focused.map((bundle, index) => ({
@@ -523,6 +585,8 @@ export class TechnologyTreeViewer {
                 folderId: focusedFolders[index]?.id,
                 selectedIds: bundle.selectedIds,
                 omittedNodeCount: bundle.omittedNodeCount,
+                renderedIconCount: bundle.renderedIconCount,
+                unresolvedIconSprites: bundle.unresolvedIconSprites,
                 hashes: bundle.hashes,
             })),
             focusedFolderCoverage: {

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.5.2';
+export const PACKAGE_VERSION = '2.6.0';
 export const MCP_PROTOCOL_VERSION = LATEST_PROTOCOL_VERSION;
 export const CONFIG_VERSION = 1;
 export const TRANSACTION_VERSION = 1;

package/docs/focus.md

@@ -30,7 +30,7 @@ For a layout-only cleanup of an existing national tree, call `hoi4.focus_rewrite
 
 Compact mode imports the tree, resets authored presentation coordinates and lane bounds, and performs a deterministic reflow in the same rewrite call. It keeps prerequisites, mutual exclusions, availability, bypasses, rewards, icons, localisation, AI behavior, and route/lane membership unchanged.
 
-The rewrite measures canvas bounds, same-row spacing, the same curved connector paths used by the renderer, connector lengths, connector-node intersections, branch balance, overall centering, and topology-aware fake-complexity patterns. Compact mode evaluates preservation, row repair, linear-chain repair, sibling balancing, and combined compression strategies, then chooses the cleanest valid result. Sparse direct sibling fan-outs are packed around their parent at the minimum readable spacing, with each exclusive descendant branch moving as a unit and shared convergence focuses staying centered. Dense branches remain wider only when their contents need the room. It refuses invalid geometry such as overlapping or cramped focuses, bad parent order, rendered crossings, connectors through unrelated focuses, or an off-center canvas. Long connectors, fake detours, staircase or zigzag chains, and avoidable sibling imbalance are optimization priorities instead of independent rejection budgets.
+The rewrite measures canvas bounds, same-row spacing, the same curved connector paths used by the renderer, connector lengths, connector-node intersections, branch balance, overall centering, and topology-aware fake-complexity patterns. Compact mode evaluates preservation, occupied-row repair, prerequisite-depth reflow, linear-chain repair, sibling balancing, and combined compression strategies, then chooses the cleanest valid result. Equivalent branches are aligned by dependency depth even when their authored rows differ, and connector shape is prioritized before raw canvas dimensions so a shorter canvas cannot win by introducing unnecessary horizontal detours. Sparse direct sibling fan-outs are packed around their parent at the minimum readable spacing, with each exclusive descendant branch moving as a unit and shared convergence focuses staying centered. Dense branches remain wider only when their contents need the room. It refuses invalid geometry such as overlapping or cramped focuses, bad parent order, rendered crossings, connectors through unrelated focuses, or an off-center canvas. Long connectors, fake detours, staircase or zigzag chains, and avoidable sibling imbalance are optimization priorities instead of independent rejection budgets.
 
 Use the default `layoutMode: "authored"` with a complete plan when deliberately designing coordinates or changing gameplay. Set `layoutMode: "compact"` with a complete plan when creating a large automatically arranged tree. Inspect and render calls remain useful before or after either rewrite mode, but a separate plan is not required for compact cleanup.
 

package/docs/gui.md

@@ -52,6 +52,8 @@ Selectors accept an element name, instance ID, or source ID. Visibility expectat
 
 Broad inspection indexes localisation actually referenced by GUI source and returns a connected workspace projection when the complete source graph is very large. The resource records full and returned node and edge counts, so an agent can identify the relevant window without loading unrelated vanilla UI into its prompt. Rendering remains targeted to the selected root, state, and resolution.
 
+GUI rewrites keep complete validation evidence in a linked JSON resource and retain the highest-priority findings in the transaction result. Large surrounding interface inventories therefore do not turn a small scalar patch into a transaction structure-limit error.
+
 ## Offline preview limits
 
 The renderer does not run the game engine. Each render includes a fidelity report that separates fields it models from fields it approximates, ignores, cannot resolve, or does not support. Treat that report as part of the review.

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/docs/technology.md

@@ -51,7 +51,7 @@ Game-backed and otherwise large workspaces automatically use focused analysis mo
 
 `hoi4.tech_render` returns authoritative JSON with deterministic SVG and PNG resources; set `includeHtml` when a bundled static report is useful. Available views are `summary`, `folder`, `dependencies`, `technology`, `doctrine`, `exclusive`, `memberships`, `bonuses`, `grants`, `unlocks`, `metadata`, `assets`, and `unresolved`.
 
-Folder renders use the actual folder assignments, gridbox geometry, technology coordinates, and HOI4 item size found in source. Technologies with `force_use_small_tech_layout = yes` render as 72×72 small items; normal technologies render as large items. The authoritative JSON and SVG expose `layoutSize` for every technology. Dependency and other semantic views are explicitly labelled as generated analysis layouts. Missing sprites, textures, or localisation remain identifiable from JSON and vector output even when no icon raster is decoded.
+Folder renders use the actual folder assignments, gridbox geometry, technology coordinates, and HOI4 item size found in source. Technologies with `force_use_small_tech_layout = yes` render as compact icon items; normal technologies render as large items with their icon and label. Sprite declarations and texture files resolve through the active load order across the mod, configured dependencies, and the detected or configured game installation, so vanilla icons used by a mod appear in SVG, PNG, and HTML artifacts. The authoritative JSON and SVG expose `layoutSize`, rendered-icon coverage, and unresolved sprite names without embedding image data in JSON. Dependency and other semantic views are explicitly labelled as generated analysis layouts.
 
 Example folder render:
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hoi4-agent-tools",
   "mcpName": "io.github.klimPaskov/hoi4-agent-tools",
-  "version": "2.5.2",
+  "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",
@@ -69,6 +69,7 @@
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "test": "vitest run",
+    "test:all": "vitest run --shard=1/8 && vitest run --shard=2/8 && vitest run --shard=3/8 && vitest run --shard=4/8 && vitest run --shard=5/8 && vitest run --shard=6/8 && vitest run --shard=7/8 && vitest run --shard=8/8",
     "test:unit": "vitest run tests/unit",
     "test:integration": "vitest run tests/integration",
     "test:local": "tsx scripts/run-local-tests.ts",
@@ -91,7 +92,7 @@
     "release:order:verify": "tsx scripts/verify-npm-release-order.ts",
     "pack:check": "tsx scripts/check-package.ts",
     "inspector": "tsx scripts/run-inspector.ts",
-    "check": "npm run format:check && npm run lint && npm run typecheck && npm run test && npm run fixtures:check && npm run schemas:check && npm run build && npm run pack:check && npm run registry:validate",
+    "check": "npm run format:check && npm run lint && npm run typecheck && npm run test:all && npm run fixtures:check && npm run schemas:check && npm run build && npm run pack:check && npm run registry:validate",
     "prepack": "npm run build"
   },
   "dependencies": {

package/schemas/configuration.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v2.5.2/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.2/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.2/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.2/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.2/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.2/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.2/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.2/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.2/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": {