hoi4-agent-tools 3.7.0 → 3.8.1

package/dist/hoi4_agent_tools/schemas/reference.js

@@ -54,7 +54,11 @@ export const sourceKeyPathSchema = z
 export const sourceLookupRequestSchema = z
     .object({
     workspaceId: workspaceIdSchema,
-    symbol: z.string().trim().min(1).max(256),
+    symbol: z.string().trim().min(1).max(256).optional(),
+    /** Locate mode: a scanned source path (`mod:events/a.txt`, `events/a.txt`, or absolute). */
+    path: z.string().trim().min(1).max(4096).optional(),
+    line: z.number().int().min(1).optional(),
+    column: z.number().int().min(1).optional(),
     kind: z
         .string()
         .regex(/^[a-z][a-z0-9_]{0,63}$/u)
@@ -74,7 +78,39 @@ export const sourceLookupRequestSchema = z
         .regex(/^[a-f0-9]{64}$/u)
         .optional(),
 })
-    .strict();
+    .strict()
+    .superRefine((value, context) => {
+    const locating = value.path !== undefined || value.line !== undefined;
+    if (locating === (value.symbol !== undefined))
+        context.addIssue({
+            code: 'custom',
+            path: ['symbol'],
+            message: 'Provide either symbol, or path and line to locate a source position',
+        });
+    if (locating && (value.path === undefined || value.line === undefined))
+        context.addIssue({
+            code: 'custom',
+            path: ['line'],
+            message: 'Locating a source position requires both path and line',
+        });
+    if (!locating && value.column !== undefined)
+        context.addIssue({
+            code: 'custom',
+            path: ['column'],
+            message: 'column applies only with path and line',
+        });
+    if (locating &&
+        (value.keyPath !== undefined ||
+            value.view === 'structure' ||
+            value.fromLine !== undefined ||
+            value.fromColumn !== undefined ||
+            value.expectedRevision !== undefined))
+        context.addIssue({
+            code: 'custom',
+            path: ['path'],
+            message: 'Navigation options apply to a symbol lookup; locate first, then pass its keyPath',
+        });
+});
 const hash = z.string().regex(/^[a-f0-9]{64}$/u);
 const line = z.number().int().min(1);
 const count = z.number().int().min(0);
@@ -101,6 +137,8 @@ export const referenceSectionSchema = z
     endLine: line,
     excerpt: z.string().max(300),
     authority: z.string().max(80),
+    /** The cited line that best matches the query; start a bounded read here. */
+    matchLine: line.optional(),
 })
     .strict();
 export const referenceSearchDataSchema = z
@@ -142,6 +180,7 @@ export const sourceLookupDataSchema = z
         'event_definitions',
         'event_consumers',
         'helper_definitions',
+        'source_location',
     ]),
     revision: hash,
     complete: z.boolean(),
@@ -153,6 +192,45 @@ export const sourceLookupDataSchema = z
     referencesTruncated: z.boolean(),
     referencesComplete: z.boolean(),
     unresolvedReferenceCount: count,
+    /** Indexed identifiers within three edits of a symbol that has no definition. */
+    suggestions: z.array(z.string().max(1024)).max(5).optional(),
+    location: z
+        .object({
+        path: z.string().max(4096),
+        rootKind: z.string().max(32),
+        loadOrder: count,
+        shadowed: z.boolean(),
+        line,
+        column: line,
+        text: z.string().max(300),
+        owners: z
+            .array(z
+            .object({
+            kind: z.string().max(64),
+            id: z.string().max(1024),
+            startLine: line,
+            endLine: line,
+            overridden: z.boolean(),
+        })
+            .strict())
+            .max(8),
+        chain: z
+            .array(z
+            .object({
+            key: z.string().max(128).nullable(),
+            occurrence: count,
+            index: count,
+            startLine: line,
+            endLine: line,
+        })
+            .strict())
+            .max(24),
+        chainTruncated: z.boolean(),
+        keyPath: sourceKeyPathSchema.nullable(),
+        structureAvailable: z.boolean(),
+    })
+        .strict()
+        .optional(),
     definitions: z
         .array(z
         .object({

package/dist/hoi4_agent_tools/schemas/transaction.js

@@ -34,7 +34,7 @@ const transactionOperationSchema = z
     .strict();
 const transactionReadDependencySchema = z
     .object({
-    rootKind: z.enum(['mod', 'game', 'dependency', 'artifact', 'cache', 'fixture']),
+    rootKind: z.enum(['mod', 'game', 'dlc', 'dependency', 'artifact', 'cache', 'fixture']),
     loadOrder: z.number().int().min(0),
     relativePath: workspaceRelativePathSchema,
     sha256: sha256Schema,

package/dist/hoi4_agent_tools/technology/service.js

@@ -117,7 +117,7 @@ async function scanTechnologySources(engine, workspaceId, workspace, principal,
     const scans = await Promise.all([
         engine.scan(workspaceId, { patterns, rootKinds: ['mod', 'dependency', 'fixture'] }, principal, signal),
         ...(workspace.roots.some(({ kind }) => kind === 'game')
-            ? [engine.scan(workspaceId, { patterns, rootKinds: ['game'] }, principal, signal)]
+            ? [engine.scan(workspaceId, { patterns, rootKinds: ['game', 'dlc'] }, principal, signal)]
             : []),
     ]);
     const files = scans.flatMap(({ files }) => files.map((file) => ({ ...file })));

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

package/docs/development.md

@@ -42,3 +42,9 @@ Add `HOI4_DEPENDENCY_ROOTS` as the platform path-delimited list when the externa
 The installed-game qualification also parses every shipped bitmap-font descriptor, resolves every atlas page, shapes native and enlarged glyphs, verifies deterministic raster output, and checks HOI4 localisation colours across base fonts and language overrides.
 
 See the package [Security Policy](../SECURITY.md) for private vulnerability reporting.
+
+## Dependencies
+
+`npm-shrinkwrap.json` is published and fixes the complete production dependency tree for every consumer, who no longer receive newer transitive releases on their own.
+Run `npm audit --omit=dev` and `npm audit signatures` before each release, and publish a new version with a refreshed shrinkwrap when a production advisory is fixed upstream.
+Keep `overrides` inside every dependent's declared range; consumers do not apply this package's overrides, and `tests/package/metadata.test.ts` checks each production dependency edge in the shrinkwrap against its range.

package/docs/examples.md

@@ -16,9 +16,9 @@ Use [Local references](reference.md) to configure an offline wiki snapshot or na
 
 ## Review a large tree
 
-> Render the Utopia Manifesto focus tree. Check its branch connections, alternative prerequisites, missing references and crowded areas before suggesting edits.
+> Render the mod's largest branching focus tree. Check its branch connections, alternative prerequisites, missing references and crowded areas before suggesting edits.
 
-[![Utopia Manifesto focus tree](images/comparisons/utopia-mcp.png)](images/comparisons/utopia-mcp.png)
+[![Branching focus tree preview](images/comparisons/utopia-mcp.png)](images/comparisons/utopia-mcp.png)
 
 Open the image at full size for the complete layout.
 This example contains 124 focuses in the recorded source version.
@@ -31,7 +31,7 @@ The [focus guide](focus.md) covers inspecting, rendering and reorganizing trees.
 [![Infantry technology folder](images/comparisons/infantry-mcp.png)](images/comparisons/infantry-mcp.png)
 
 The preview follows the loaded technology and GUI definitions, including wide equipment cards.
-The [technology comparisons](visual-comparisons.md#technology-folders) also show a chemical folder rendered from a matching recorded source revision.
+The [technology comparisons](visual-comparisons.md#technology-folders) also show a mod folder with wide equipment cards rendered from a matching recorded source revision.
 See the [technology guide](technology.md) for grants, bonuses and doctrine paths.
 
 ## Inspect an interface before editing it

package/docs/map.md

@@ -18,6 +18,16 @@ Pass `tile: { x, y, width, height }` to `hoi4.map_render` for a reusable bounded
 
 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.
 
+## Catalog consistency
+
+Validation reads the active `common/terrain/*.txt` categories and `map/continent.txt` (or the continent file `default.map` names) along with the map files.
+A province whose terrain no category defines reports `MAP_TERRAIN_UNKNOWN`, and a land province with a continent number beyond the continents listed reports `MAP_CONTINENT_UNKNOWN`; continent IDs follow their order in the file.
+Seas and lakes must use a category with `is_water = yes` (`MAP_SEA_TERRAIN_INVALID`, `MAP_LAKE_TERRAIN_INVALID`), land provinces must not (`MAP_LAND_TERRAIN_WATER`), and a strategic region's `naval_terrain` must name a category with `naval_terrain = yes` (`MAP_REGION_NAVAL_TERRAIN_INVALID`).
+When no terrain category file is available, seas and lakes are checked against the base game's `ocean` and `lakes` names instead, and unknown terrain is not reported.
+
+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.
+
 ## Create states
 
 The compact `create_state` form needs selected provinces and a display name:

package/docs/reference.md

@@ -10,14 +10,16 @@ The server discovers these directories for a workspace:
 | Offline wiki                   | `modRoot/paradox_wiki/**/*.md`                                              | Set absolute `wikiRoot`.                               |
 | Generated script documentation | `modRoot/script_docs/**/*.md` and `**/*.log`                                | Set absolute `scriptDocsRoot` to a user-supplied dump. |
 
-Only Markdown headings and recognizable standalone names in generated `.log` files form sections. A dump that yields one section should be treated as insufficiently parsed; inspect its source format before relying on it. Source bytes are hashed on each request, while unchanged section indexes are reused. Missing roots are reported as unavailable. The public package contains none of these local source files.
+Markdown headings and recognizable standalone names in generated `.log` files form sections. A Markdown table row whose first cell is an identifier, such as a wiki effect, trigger, modifier, define, or on action, is also its own one-line section, so a citation can name the exact entry inside a long table. A dump that yields one section should be treated as insufficiently parsed; inspect its source format before relying on it. Source bytes are hashed on each request, while unchanged section indexes are reused. Missing roots are reported as unavailable. The public package contains none of these local source files.
 
 ## 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_search`: search page names, headings, exact script tokens, and matching body lines. 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_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.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.
 
 ## Navigate a definition
@@ -70,4 +72,4 @@ Call `hoi4.reference_context` with that input, then search `save_event_target_as
 
 The local index admits at most 512 files per source kind, 2 MB per file, 32 MB in total, and 20,000 sections. Search and read responses are bounded by the MCP result budget. `skipped` and per-source coverage expose incomplete ingestion instead of implying that an omitted source was checked. Registered external reference roots are operator configuration and remain private to the authorized workspace.
 
-See [the measured Chaos Redux reference retrieval](research/reference-benchmark.md) for actual source coverage and response sizes.
+See [the measured Chaos Redux reference retrieval](research/reference-benchmark.md) for actual source coverage, held-out discovery results, and response sizes. Plain-word questions still miss when the documentation uses different vocabulary, for example "national spirit" for `ideas`; search the script name directly when it is known.

package/docs/research/reference-benchmark.md

@@ -27,6 +27,45 @@ The retrieval benchmark used the local service directly. A separate real-workspa
 
 The four additional public tool definitions add approximately 6.5 KB to the one-time MCP tool discovery response. The complete list is about 72 KB in the discovery fixture and is tested against a 72 KiB ceiling. The context reduction above applies to reference retrieval after discovery.
 
+## Held-out discovery questions
+
+Measured on 2026-10-04 against the same local Chaos Redux wiki snapshot and installed documentation.
+The nine questions above were assembled alongside the previous ranking, so they cannot show whether a ranking change generalizes.
+Two further sets in `scripts/reference-discovery-cases.ts` phrase tasks the way an agent asks them, mostly without the script name.
+Every expected answer was checked by hand in the local files, and a case may list several acceptable sections.
+A result answers a question when its cited section contains an expected answer line; it lands when its cited line is within eight lines of that answer.
+
+The discovery set has 32 plain-word questions, five exact identifiers, and two unrelated negative queries.
+The validation set has 24 plain-word questions written before any ranking adjustment and was never used to tune it.
+
+| Set and ranking                | Answer first | Within three | Within five | Lands within three | Mean reciprocal rank |
+| ------------------------------ | -----------: | -----------: | ----------: | -----------------: | -------------------: |
+| Discovery, previous ranking    |         7/37 |        19/37 |       22/37 |              18/37 |                0.342 |
+| Discovery, field-weighted BM25 |        19/37 |        28/37 |       29/37 |              26/37 |                0.628 |
+| Validation, previous ranking   |         4/24 |         7/24 |       12/24 |               7/24 |                0.272 |
+| Validation, field-weighted     |        11/24 |        16/24 |       20/24 |              16/24 |                0.588 |
+
+The previous ranking placed four of the five exact identifiers first and did not return the `on_startup` wiki entry at all; the current one places each first, with installed documentation ahead of the wiki.
+Both returned no results for the two negative queries.
+On the original nine questions, all nine stay within five results, three rank first rather than five, and one moves from fourth to fifth.
+
+In three repeated runs, the first query after a source change took 370–386 ms to index about twelve thousand sections, compared with 147–159 ms with the previous ranking.
+Later queries took a median of 37 ms, compared with 49–63 ms, and the median ranked reply was about 3.7 KB in both.
+
+Twelve plain-word questions across both sets still miss the top five.
+Most use vocabulary the documentation does not: "national spirit" where script says `ideas`, "give a state" for `transfer_state`, "repeat effects" for `for_loop_effect`, and "build a factory" for `add_building_construction`.
+Search the script name when it is known; the ranking does not add synonyms for individual questions.
+These are 61 task questions over one documentation snapshot, not a general precision guarantee.
+
+Run both sets with:
+
+```bash
+npx tsx scripts/evaluate-reference-discovery.ts MOD_ROOT GAME_ROOT
+npx tsx scripts/evaluate-reference-discovery.ts MOD_ROOT GAME_ROOT --validation
+```
+
+The script exits with a failure when a case has no expected answer in the supplied sources.
+
 ## Compact context budgets
 
 A 2026-09-27 check of the installed 3.5.0 server found that eight GUI results could contain only wiki sections even though the installed GUI documentation was available. The 3.5.1 source qualifies limits of one, two, and eight citations across the same six work surfaces. All eighteen cases retained installed documentation; limits of two or more also retained wiki citations. Required sources excluded by the limit appeared in `omittedSources`, separately from files absent under `missing`. The nine search queries still found all expected answer-bearing sections.

package/docs/setup.md

@@ -9,6 +9,9 @@ Keep an installed copy of Hearts of Iron IV available for vanilla references, ar
 npm install --global hoi4-agent-tools
 ```
 
+The package publishes an `npm-shrinkwrap.json`, so every registry or `npx` install receives the same reviewed dependency versions.
+npm installs the image library's prebuilt binaries for every supported platform from it, about 280 MiB in total; the server loads only the one for your system.
+
 Source inspection can work without an installed game.
 Previews need the assets and fonts referenced by the mod; missing files are reported in the result.
 
@@ -53,6 +56,18 @@ For a custom configuration location, add `--config PATH` to both setup commands.
 `--workspace-storage-root PATH` chooses where generated indexes and images are saved.
 Linked mod directories are not followed; configure their real parent directory instead.
 
+### How sources are layered
+
+Sources load in the engine's order: the base game, then each installed folder under `dlc/` and `integrated_dlc/` in order of its internal DLC ID, then dependencies, then the mod.
+A later layer replaces a file with the same path from an earlier one, so a DLC's version of an interface file is the active one and the base game's copy is reported as shadowed.
+Results name a DLC layer by its folder, for example `dlc023_man_the_guns:interface/mtg_leaders.gfx`.
+Only folders that contain a `dlcNNN.dlc` descriptor and resolve inside the game root are layers; archives inside a DLC folder are not unpacked.
+An installed DLC folder is not proof that the DLC is enabled in a particular playset; check `has_dlc` where content depends on it.
+Set `"includeGameDlc": false` on a configured workspace to analyze the base game alone.
+
+`replace_path` entries in a mod's or dependency's `descriptor.mod` unload earlier-loaded files under that folder, as the engine does, and join any `replacePaths` configured for the workspace.
+Entries that are not plain relative folders, such as `../outside` or wildcard paths, are ignored.
+
 ## Add local reference material
 
 Place an offline wiki snapshot in `paradox_wiki/` inside the mod.

package/docs/tools.md

@@ -4,43 +4,43 @@ Most users can ask their agent in ordinary language; the [examples guide](exampl
 This page lists exact tool names for agents and integrations.
 Use the connected server's live schema for the fields accepted by each call.
 
-| Tool                        | Purpose                                                                                      |
-| --------------------------- | -------------------------------------------------------------------------------------------- |
-| `hoi4.focus_inspect`        | Read focus trees, continuous-focus placement, and structural or reference problems.          |
-| `hoi4.focus_render`         | Produce fast HTML, SVG, JSON, and source-linked layout artifacts.                            |
-| `hoi4.focus_raster`         | Produce a PNG preview with decoded source icons.                                             |
-| `hoi4.focus_rewrite`        | Create or update a focus tree.                                                               |
-| `hoi4.gui_inspect`          | Read a scripted GUI and its linked assets and logic.                                         |
-| `hoi4.gui_render`           | Render generated and explicit GUI scenarios, states, resolutions, and layout diagnostics.    |
-| `hoi4.gui_rewrite`          | Create or update a GUI source package.                                                       |
-| `hoi4.map_inspect`          | Search, click, navigate, and inspect the complete rendered map and its linked data.          |
-| `hoi4.map_render`           | Render full-map layers, overlays, names, IDs, coordinates, and source-linked catalogs.       |
-| `hoi4.map_rewrite`          | Create or update states, provinces, IDs, networks, positions, and connected map data.        |
-| `hoi4.reference_context`    | Get compact, cited wiki and installed documentation pointers for a modding surface.          |
-| `hoi4.reference_search`     | Search bounded local documentation sections.                                                 |
-| `hoi4.reference_read`       | Read one revision-bound section, with line continuation.                                     |
-| `hoi4.source_lookup`        | Find exact definitions, overrides, usages, and narrow source blocks.                         |
-| `hoi4.script_validate`      | Check snippet syntax, native command kinds, and declared scopes against local documentation. |
-| `hoi4.event_inspect`        | Scan, trace, explain, lint, or assess event chains and their state flow.                     |
-| `hoi4.event_render`         | Render source-linked event routes, options, timing, state, scope, and unresolved edges.      |
-| `hoi4.event_compare`        | Compare event-chain topology and diagnostics between revisions.                              |
-| `hoi4.impact_inspect`       | Trace symbol and changed-file consumers across source systems and compare proposals.         |
-| `hoi4.decision_inspect`     | Inventory and evaluate decisions or missions under declared scenarios and source changes.    |
-| `hoi4.mechanic_test`        | Execute bounded source effects on a copied declared scenario and check assertions.           |
-| `hoi4.package_check`        | Check declarative package definitions, calls, registrations, assets, and case links.         |
-| `hoi4.scenario_test`        | Run named source and domain cases in resumable, revision-bound batches.                      |
-| `hoi4.job_inspect`          | Inspect durable background work or retrieve its completed tool result.                       |
-| `hoi4.job_cancel`           | Durably request cancellation of authorized background work.                                  |
-| `hoi4.tech_inspect`         | Scan, trace, explain, lint, and assess technology and doctrine systems.                      |
-| `hoi4.tech_render`          | Render source layouts with real item sizes and year guides, plus dependencies and assets.    |
-| `hoi4.tech_compare`         | Compare technology graphs, placements, references, diagnostics, and source overlays.         |
-| `hoi4.probability_inspect`  | Locate weighted logic and discover compatible adapters, candidates, and required inputs.     |
-| `hoi4.probability_evaluate` | Evaluate supported weights, probability and timing models, and missing inputs.               |
-| `hoi4.probability_sweep`    | Find sensitivity, breakpoints, cliffs, and rank reversals across declared ranges.            |
-| `hoi4.probability_simulate` | Run deterministic sampled analysis with confidence and convergence data.                     |
-| `hoi4.probability_sequence` | Analyze declared recovery, caps, cooldowns, resets, timers, and terminal states.             |
-| `hoi4.probability_compare`  | Attribute AI-weight and MTTH changes between real or proposed source.                        |
-| `hoi4.probability_render`   | Render cached rankings, matrices, timing, sensitivity, sequence, and comparisons.            |
+| Tool                        | Purpose                                                                                                          |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `hoi4.focus_inspect`        | Read focus trees, continuous-focus placement, and structural or reference problems.                              |
+| `hoi4.focus_render`         | Produce fast HTML, SVG, JSON, and source-linked layout artifacts.                                                |
+| `hoi4.focus_raster`         | Produce a PNG preview with decoded source icons.                                                                 |
+| `hoi4.focus_rewrite`        | Create or update a focus tree.                                                                                   |
+| `hoi4.gui_inspect`          | Read a scripted GUI and its linked assets and logic.                                                             |
+| `hoi4.gui_render`           | Render generated and explicit GUI scenarios, states, resolutions, and layout diagnostics.                        |
+| `hoi4.gui_rewrite`          | Create or update a GUI source package.                                                                           |
+| `hoi4.map_inspect`          | Search, click, navigate, and inspect the complete rendered map and its linked data.                              |
+| `hoi4.map_render`           | Render full-map layers, overlays, names, IDs, coordinates, and source-linked catalogs.                           |
+| `hoi4.map_rewrite`          | Create or update states, provinces, IDs, networks, positions, and connected map data.                            |
+| `hoi4.reference_context`    | Get compact, cited wiki and installed documentation pointers for a modding surface.                              |
+| `hoi4.reference_search`     | Search local documentation in plain words or script names; each result names its answering line.                 |
+| `hoi4.reference_read`       | Read one revision-bound section, with line continuation.                                                         |
+| `hoi4.source_lookup`        | Find exact definitions, overrides and usages across game, DLC and mod, or the definition containing a file line. |
+| `hoi4.script_validate`      | Check snippet syntax, native command kinds, and declared scopes against local documentation.                     |
+| `hoi4.event_inspect`        | Scan, trace, explain, lint, or assess event chains and their state flow.                                         |
+| `hoi4.event_render`         | Render source-linked event routes, options, timing, state, scope, and unresolved edges.                          |
+| `hoi4.event_compare`        | Compare event-chain topology and diagnostics between revisions.                                                  |
+| `hoi4.impact_inspect`       | Trace symbol and changed-file consumers across source systems and compare proposals.                             |
+| `hoi4.decision_inspect`     | Inventory and evaluate decisions or missions under declared scenarios and source changes.                        |
+| `hoi4.mechanic_test`        | Execute bounded source effects on a copied declared scenario and check assertions.                               |
+| `hoi4.package_check`        | Check declarative package definitions, calls, registrations, assets, and case links.                             |
+| `hoi4.scenario_test`        | Run named source and domain cases in resumable, revision-bound batches.                                          |
+| `hoi4.job_inspect`          | Inspect durable background work or retrieve its completed tool result.                                           |
+| `hoi4.job_cancel`           | Durably request cancellation of authorized background work.                                                      |
+| `hoi4.tech_inspect`         | Scan, trace, explain, lint, and assess technology and doctrine systems.                                          |
+| `hoi4.tech_render`          | Render source layouts with real item sizes and year guides, plus dependencies and assets.                        |
+| `hoi4.tech_compare`         | Compare technology graphs, placements, references, diagnostics, and source overlays.                             |
+| `hoi4.probability_inspect`  | Locate weighted logic and discover compatible adapters, candidates, and required inputs.                         |
+| `hoi4.probability_evaluate` | Evaluate supported weights, probability and timing models, and missing inputs.                                   |
+| `hoi4.probability_sweep`    | Find sensitivity, breakpoints, cliffs, and rank reversals across declared ranges.                                |
+| `hoi4.probability_simulate` | Run deterministic sampled analysis with confidence and convergence data.                                         |
+| `hoi4.probability_sequence` | Analyze declared recovery, caps, cooldowns, resets, timers, and terminal states.                                 |
+| `hoi4.probability_compare`  | Attribute AI-weight and MTTH changes between real or proposed source.                                            |
+| `hoi4.probability_render`   | Render cached rankings, matrices, timing, sensitivity, sequence, and comparisons.                                |
 
 ## Reading results
 

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "hoi4-agent-tools",
-  "version": "3.7.0",
+  "version": "3.8.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "hoi4-agent-tools",
-      "version": "3.7.0",
+      "version": "3.8.1",
       "license": "Apache-2.0",
       "dependencies": {
         "@fontsource-variable/roboto": "5.3.0",
@@ -42,6 +42,7 @@
         "fast-check": "4.9.0",
         "pixelmatch": "7.2.0",
         "prettier": "3.9.6",
+        "semver": "7.8.5",
         "tsx": "4.23.11",
         "typescript": "6.0.3",
         "typescript-eslint": "8.66.0",
@@ -715,9 +716,9 @@
       }
     },
     "node_modules/@hono/node-server": {
-      "version": "2.1.0",
-      "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-2.1.0.tgz",
-      "integrity": "sha512-XovyyCCnBzW+zKu+z/zq8hwNs4KOR5rEMAOxo2f40Q5xoOI37IMm6MIg2COOUtUApo0i6850MTBKH2u4QLGIqg==",
+      "version": "2.1.3",
+      "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-2.1.3.tgz",
+      "integrity": "sha512-TA//nWMqPhbfdfneACk6t5a9eqbS9lABEPyKn0/xZTah3H3U2XaVg85rJFl0/Fyit0I552YDHgXGVSf3GwqbUw==",
       "license": "MIT",
       "engines": {
         "node": ">=20"
@@ -1755,6 +1756,18 @@
         }
       }
     },
+    "node_modules/@modelcontextprotocol/node/node_modules/@hono/node-server": {
+      "version": "1.19.17",
+      "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-1.19.17.tgz",
+      "integrity": "sha512-dSneS5qhiauZWGDCeK4o695Xd9nUNjviSZCMQrj10eetr8Uln1ucn6bbphOM6UynAMMtNIzZNSpL9vnASJwrPQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18.14.1"
+      },
+      "peerDependencies": {
+        "hono": "^4"
+      }
+    },
     "node_modules/@modelcontextprotocol/sdk": {
       "version": "1.30.0",
       "resolved": "https://registry.npmjs.org/@modelcontextprotocol/sdk/-/sdk-1.30.0.tgz",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hoi4-agent-tools",
   "mcpName": "io.github.klimPaskov/hoi4-agent-tools",
-  "version": "3.7.0",
+  "version": "3.8.1",
   "description": "HOI4 modding tools for agents: local references, visual previews, focus trees, interfaces and maps.",
   "type": "module",
   "license": "Apache-2.0",
@@ -137,13 +137,13 @@
     "fast-check": "4.9.0",
     "pixelmatch": "7.2.0",
     "prettier": "3.9.6",
+    "semver": "7.8.5",
     "tsx": "4.23.11",
     "typescript": "6.0.3",
     "typescript-eslint": "8.66.0",
     "vitest": "4.1.11"
   },
   "overrides": {
-    "@hono/node-server": "2.1.0",
     "brace-expansion": "5.0.12",
     "fast-uri": "3.1.8",
     "qs": "6.16.0",