hoi4-agent-tools 3.5.1 → 3.7.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## Unreleased
 
+## 3.7.0 - 2026-10-04
+
+- Publish an `npm-shrinkwrap.json` so every install reproduces the reviewed dependency closure, including all platforms' optional Sharp binaries (about 300 MB installed).
+- Navigate exact nested source assignments and page through bounded child structure, including repeated keys and same-line blocks.
+- Limit definition-only event/helper lookups to their source family and reuse semantic reference analysis for unchanged snapshots.
+- Check snippet syntax, native command kinds, and declared scopes against cited installed or explicitly selected generated documentation, with unresolved coverage reported separately.
+- Verify source files in bounded parallel batches, reject changing or replaced paths, and bound optional cache persistence without truncating analysis.
+- Load isolated workers' domain modules after authenticating the job, preserving exact operation admission and recorded write policies.
+- Filter reference scans by authority, reuse citation hints, decode supported reference encodings, and preserve byte-bounded continuations and explicit omission counts.
+- Replace the unpatched globbing dependency chain and update vulnerable transitive pins, preserving relative-path, symlink, literal-filename and pattern-complexity checks.
+
+## 3.6.0 - 2026-09-27
+
+- Preview immediate tooltip text from source localisation with declared position, width and padding, using the source tooltip sprite and font.
+- Keep unknown GUI visibility and enablement separate from confirmed states, branch coverage and click regions.
+- Identify inferred scrollbar gutter geometry as approximate.
+- Provide a shorter setup guide, practical examples with real renders, and a separate tool reference; remove redundant planning and release-history documents.
+
 ## 3.5.1 - 2026-09-27
 
 - Preserve installed-game and offline-wiki citations in compact reference context bundles, select question-relevant sections within required sources, and report sources omitted by the result limit separately from missing files.

package/README.md

@@ -1,137 +1,158 @@
 # HOI4 Agent Tools
 
-HOI4 Agent Tools is an MCP server for coding agents to understand Hearts of Iron IV event chains, decisions, cross-system dependencies, technology systems, AI weights, and MTTH timing and to inspect, create, or clean up focus trees, scripted GUIs, and maps. It produces source-linked structural and visual evidence that agents can use inside a larger modding workflow.
+Give your coding agent one MCP server for Hearts of Iron IV modding.
+It can find local documentation and vanilla examples, inspect a mod, render its trees and interfaces, compare source behavior, and make focused edits to focus trees, GUIs and maps.
+The pictures below use real Chaos Redux or installed HOI4 files; click any image for the full-size version.
 
-## What it does
+## Get started
 
-- Focus trees: inspect structure and references, render layouts, create trees, and reorganize existing branches.
-- Scripted GUIs: trace GUI, GFX, scripted-GUI, and localisation links; render value-driven variants, dynamic country flags, inline text icons, states, resolutions, hierarchy, and click regions; diagnose alignment, visibility, clipping, panel containment, and button-label centering; create or repair interface source.
-- Maps: navigate the complete rendered map by ID or localised name; inspect provinces, states, regions, adjacency, supply, railways, and positions; create states and provinces; change IDs; and repair connected map data.
-- Event chains: scan definitions and call sites, trace routes and state flow, lint references, render graphs, and compare revisions without editing event source.
-- Cross-system impact and decisions: trace definitions and consumers across source systems, evaluate declared actor and target scenarios, inspect costs and mission paths, and compare in-memory proposals.
-- Technology trees: reconstruct technology and doctrine paths, folder layouts, unlocks, bonuses, grants, metadata, assets, and structural changes.
-- AI and MTTH: evaluate weighted choices and timing across explicit scenarios, bind special scope chains, enumerate dynamic target pools, sweep uncertain inputs, simulate distributions, compare patches, and analyze declared stateful pools.
-- Local references: search and read cited offline wiki pages, installed game documentation, optional script documentation, and exact source symbols without loading whole manuals into the conversation.
+Install [Node.js](https://nodejs.org/) 22.19+ in the Node 22 line, or Node.js 24, then run:
 
-## Real results
+```bash
+npm install --global hoi4-agent-tools
+hoi4-agent-tools-setup --print-client-config
+```
 
-The examples use real installed vanilla and Chaos Redux source, supplied game captures, and explicit reproducible display scenarios. They demonstrate source-backed review, not a claim of 99.9% whole-image accuracy. Images, source revisions, hashes, and known differences are in [Visual comparisons](docs/visual-comparisons.md) and [Interface examples](docs/gui-comparisons.md).
+Add the printed configuration to your MCP client and open your mod as its workspace.
+Keep an installed copy of HOI4 available for vanilla examples, artwork and fonts.
+The [setup guide](docs/setup.md) covers connecting your agent and choosing game or mod paths.
 
-| Options Video in game                                                          | Options Video from the MCP renderer                                                                |
-| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
-| ![Options Video in game](docs/images/comparisons/gui/options-video-ingame.png) | ![Options Video rendered from installed source](docs/images/comparisons/gui/options-video-mcp.png) |
+Ask your agent to find a focus tree and render it, locate the installed documentation for a script command, or preview a scripted GUI at different UI scales.
+The examples below show the results.
 
-| Škoda Priority in game                                                           | Škoda Priority from the MCP renderer                                                                 |
-| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| ![Škoda Priority in game](docs/images/comparisons/gui/skoda-priority-ingame.png) | ![Škoda Priority rendered from installed source](docs/images/comparisons/gui/skoda-priority-mcp.png) |
+## Examples
 
-The interface gallery also includes Chaos Redux Settings, Event Log, and Chaos Meter, plus populated vanilla decision and occupation templates. Their manifests separate source-defined layout from declared native runtime fields.
+[Focus trees](#focus-trees-and-alternative-prerequisites) · [Technology folders](#technology-folders-and-card-artwork) · [Interfaces](#scripted-interfaces) · [Maps and events](#maps-and-event-chains) · [Local rules and AI](#local-rules-and-ai-weights) · [All tools](#complete-tool-list)
 
-The other workbenches return complete source-linked layouts and catalogs rather than prose-only summaries.
+### Focus trees and alternative prerequisites
 
-For the supplied focus and technology game captures beside current-source MCP renders, see [Visual examples and comparison limits](https://github.com/klimPaskov/hoi4-agent-tools/blob/main/docs/visual-comparisons.md). These comparisons do not establish 99.9% whole-image accuracy.
+| Tree or branch   | Supplied in-game capture                                                                                              | MCP source preview                                                                                                 |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| Fury             | [![Fury in game](docs/images/comparisons/fury-ingame.png)](docs/images/comparisons/fury-ingame.png)                   | [![Fury focus tree](docs/images/comparisons/fury-mcp.png)](docs/images/comparisons/fury-mcp.png)                   |
+| Holy Realm       | [![Holy Realm in game](docs/images/comparisons/holy-realm-ingame.png)](docs/images/comparisons/holy-realm-ingame.png) | [![Holy Realm focus tree](docs/images/comparisons/holy-realm-mcp.png)](docs/images/comparisons/holy-realm-mcp.png) |
+| Utopia Manifesto | [![Utopia in game](docs/images/comparisons/utopia-ingame.png)](docs/images/comparisons/utopia-ingame.png)             | [![Utopia focus tree](docs/images/comparisons/utopia-mcp.png)](docs/images/comparisons/utopia-mcp.png)             |
 
-| Fury focus tree from Chaos Redux                                                          | Infantry technology folder from Chaos Redux and vanilla                                                |
-| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| ![Fury focus tree rendered from Chaos Redux source](docs/images/comparisons/fury-mcp.png) | ![Infantry technology folder rendered from installed source](docs/images/comparisons/infantry-mcp.png) |
+Dotted connectors in the MCP preview mark focuses where either preceding focus satisfies one prerequisite group.
+The tree previews show route structure; the game's focus screen has different framing, labels and icons.
+The [focus guide](docs/focus.md) explains inspection, rendering and edits, and the [comparison details](docs/visual-comparisons.md#focus-trees) retain source revisions.
+
+### Technology folders and card artwork
+
+> Render a technology folder. Check card sizes, artwork, links and missing placements.
+
+| Folder           | Supplied in-game capture                                                                                                             | MCP source preview                                                                                                                     |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
+| Infantry         | [![Infantry in game](docs/images/comparisons/infantry-ingame.png)](docs/images/comparisons/infantry-ingame.png)                      | [![Infantry technology folder](docs/images/comparisons/infantry-mcp.png)](docs/images/comparisons/infantry-mcp.png)                    |
+| Chemical warfare | [![Chemical folder in game](docs/images/comparisons/chemical-recent-ingame.png)](docs/images/comparisons/chemical-recent-ingame.png) | [![Chemical folder preview](docs/images/comparisons/chemical-historical-mcp.png)](docs/images/comparisons/chemical-historical-mcp.png) |
 
-| Map                                                                              | Event options                                                                                      |
-| -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
-| ![Installed map rendered by the MCP](docs/images/comparisons/source/map-mcp.png) | ![Chaos Redux event chain rendered by the MCP](docs/images/comparisons/source/event-chain-mcp.png) |
+The chemical comparison uses the source revision recorded with the screenshot and includes wide equipment cards.
+The [technology comparison](docs/visual-comparisons.md#technology-folders) records its source revision, and the [technology guide](docs/technology.md) covers inspection and doctrine paths.
 
-These two views retain native output resolution. Their [source manifest](docs/images/comparisons/source/manifest.json) records the map revision and the exact Fury event used for the option view. The event renderer's omitted-node count includes the rest of the workspace graph outside that selection.
+### Scripted interfaces
 
-## Use from a coding agent
+> Preview an interface with its game assets and fonts. Check states, text clipping and clickable areas at 100% and 125% UI scale.
 
-Requires Node.js 22.19 or later in the Node 22 line, or Node.js 24.
+| Interface               | Supplied in-game capture                                                                                                                  | MCP source preview                                                                                                                  |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| Video options           | [![Options in game](docs/images/comparisons/gui/options-video-ingame.png)](docs/images/comparisons/gui/options-video-ingame.png)          | [![Options preview](docs/images/comparisons/gui/options-video-mcp.png)](docs/images/comparisons/gui/options-video-mcp.png)          |
+| Škoda Priority          | [![Škoda Priority in game](docs/images/comparisons/gui/skoda-priority-ingame.png)](docs/images/comparisons/gui/skoda-priority-ingame.png) | [![Škoda Priority preview](docs/images/comparisons/gui/skoda-priority-mcp.png)](docs/images/comparisons/gui/skoda-priority-mcp.png) |
+| Chaos Redux Tag Manager | [![Tag Manager in game](docs/images/comparisons/gui/tag-manager-ingame.png)](docs/images/comparisons/gui/tag-manager-ingame.png)          | [![Tag Manager preview](docs/images/comparisons/gui/tag-manager-mcp.png)](docs/images/comparisons/gui/tag-manager-mcp.png)          |
 
-```bash
-npm install --global hoi4-agent-tools@latest
-```
+The Tag Manager screenshot comes from an older layout.
+The Options preview has no observed gamma value, and Škoda's game capture frames its background differently.
 
-```toml
-[mcp_servers.hoi4_agent_tools]
-command = "hoi4-agent-tools.cmd"
-startup_timeout_sec = 120
-tool_timeout_sec = 600
-```
+| Event Log                                                                                                            | Chaos Meter: status                                                                                                                     | Chaos Meter: deaths                                                                                                                     |
+| -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| [![Event Log preview](docs/images/comparisons/gui/event-log-mcp.png)](docs/images/comparisons/gui/event-log-mcp.png) | [![Chaos Meter status](docs/images/comparisons/gui/chaos-meter-status-mcp.png)](docs/images/comparisons/gui/chaos-meter-status-mcp.png) | [![Chaos Meter deaths](docs/images/comparisons/gui/chaos-meter-deaths-mcp.png)](docs/images/comparisons/gui/chaos-meter-deaths-mcp.png) |
 
-On non-Windows systems, use `hoi4-agent-tools` as the command. Agentic HOI4 repositories can include these steps in their agent template so the coding agent installs and registers the server itself; manual installation is not required in that workflow. Once connected, the server follows the active mod supplied by the client and the agent can call its HOI4 tools directly.
-
-## Tools
-
-| 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 high-fidelity PNG review 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.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 exact values, probabilities, timing, bounds, and unresolved 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.         |
-
-Set `HOI4_AGENT_TOOLS_CHAOSX=1` on the server process to expose the optional `chaosx.focus_country_assets` and `chaosx.visual_revision` tools used by ChaosX workflows. They remain absent from the default public tool list.
-
-Large outputs are linked `hoi4-agent://` resources. For resources over 1 MiB, follow the `continuationUri` returned in `_meta` until it is `null`; clients may also request byte ranges with `?offset=<bytes>&length=<bytes>`.
-
-Long-running domain calls advertise optional MCP task support. A task survives client disconnects and can be retrieved after reconnect; clients without task support keep the ordinary synchronous result contract. Native background rewrites require a stable caller-supplied `requestKey` so retries resolve to one durable mutation receipt. See [Persistent jobs and MCP tasks](docs/jobs.md).
-
-## Coexistence with agent workflows
-
-HOI4 Agent Tools provides HOI4 domain operations without replacing repository instructions such as `AGENTS.md`, skills, plans, or subagents. Its optional weighted-logic prompt helps an agent scope one probability analysis and then returns control to the normal workflow.
-
-Connecting and listing tools does not scan mod source. Compact tool schemas and linked resources keep large diagnostics, renders, and diffs out of the agent's working context until needed. Event, impact, decision, technology, and probability tools analyze source without editing it; only `hoi4.*_rewrite` calls edit mod source.
-
-## Create or clean content
-
-Ask your agent in normal task language. A typical workflow is inspect, render, rewrite, then inspect the result. The agent can call a raster tool when a pixel review is useful without paying that cost during every structural operation.
-
-- Focus trees: "Create a complete national focus tree for this route specification," or "Compact this existing tree into a balanced, readable layout." Existing trees can use a plan-free compact reflow; new trees use a complete plan. See [Focus trees](docs/focus.md).
-- Scripted GUIs: "Create a scripted GUI for this mechanic," or "Render every value-driven version of this window and fix hidden controls, off-center button text, background alignment, clipping, and click-region conflicts." See [Scripted GUIs](docs/gui.md).
-- Maps: "Render the whole map and find this state by name," "Create a state from these provinces," "Create a province inside this exact rectangle," or "Swap these state IDs and update connected references." See [Maps](docs/map.md).
-- Event chains: "Trace every route from this event and explain where its flags and variables change," or "Compare the workspace event graph with its previous revision and render the affected routes." See [Event chains](docs/events.md).
-- Cross-system impact and decisions: "Find every direct and transitive consumer of this idea," or "Compare who can take this decision, what they pay, and its mission end paths for these actor and target scenarios." See [Cross-system impact and decisions](docs/analysis.md).
-- Mechanics and packages: "Test this transfer's conservation and payment," or "Check every declared package link and resume its named scenario suite." See [Mechanic tests and scenario suites](docs/mechanics.md).
-- Technology trees: "Explain everything this technology requires and unlocks," or "Compare this technology patch and render every affected folder and doctrine branch." See [Technology trees](docs/technology.md).
-- AI and MTTH: "Compare these focus weights across peace, defensive-war, and low-stability scenarios," or "Show when this MTTH event becomes likely and which unknown inputs control the result." See [AI and MTTH analysis](docs/probability.md).
-- References: "Find the installed effect signature and an exact vanilla example," or "Show the pertinent wiki and installed documentation for this GUI task." See [Local references](docs/reference.md).
-
-## HTTP
-
-Use stdio for local MCP clients. For shared or remote deployments, see [HTTP](docs/http.md).
-
-## Development
+| Vanilla decisions                                                                                                                                        | Vanilla occupation                                                                                                                                             |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [![Decision window](docs/images/comparisons/native-ui/countrydecisionview-window.png)](docs/images/comparisons/native-ui/countrydecisionview-window.png) | [![Occupation window](docs/images/comparisons/native-ui/countryoccupationview-window.png)](docs/images/comparisons/native-ui/countryoccupationview-window.png) |
 
-```bash
-npm ci
-npm run check
-```
+The Event Log, Chaos Meter, decision and occupation previews use declared states or positions for layout review.
+They are source previews, not observations of a running campaign.
+See the [interface gallery](docs/gui-comparisons.md) for full images and fidelity notes, and the [GUI guide](docs/gui.md) for scenario inputs.
+
+### Maps and event chains
+
+> Find Brandenburg on the map, inspect its provinces and neighbours, and show the affected source files before a change.
+
+> Trace an event's options and follow-up events. Point out unresolved calls and link each route to its source.
+
+| Source map                                                                                                                      | Chaos Redux event chain                                                                                                                |
+| ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| [![Map rendered from installed source](docs/images/comparisons/source/map-mcp.png)](docs/images/comparisons/source/map-mcp.png) | [![Chaos Redux event options](docs/images/comparisons/source/event-chain-mcp.png)](docs/images/comparisons/source/event-chain-mcp.png) |
+
+The [map guide](docs/map.md) covers connected province, state, supply and railway data.
+The [event guide](docs/events.md) covers routes, scope, timing and unresolved references.
+
+### Local rules and AI weights
+
+> Find the installed documentation for `save_event_target_as`, read the relevant section, and show a vanilla usage with file and line references.
+
+> Compare this decision's `ai_will_do` score before and after a change in peace and war. List missing conditions separately from known results.
+
+The [reference example](docs/research/reference-benchmark.md) found the installed effect documentation first and read its relevant 12-line section instead of loading whole wiki pages.
+The [AI guide](docs/probability.md) covers supported weights, chance and timing models; a source score alone does not establish an AI click probability.
+The [examples guide](docs/examples.md) has more prompt details.
+
+## Complete tool list
+
+The default server exposes 35 tools.
+Your agent can select them from ordinary language; use the live tool schema for call parameters.
 
-See [Development](docs/development.md). Apache-2.0 licensed. Hearts of Iron IV and Paradox Interactive are trademarks of their respective owners; this project is unaffiliated.
+| 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.            |
+
+Set `HOI4_AGENT_TOOLS_CHAOSX=1` to expose two optional Chaos Redux workflow tools: `chaosx.focus_country_assets` and `chaosx.visual_revision`.
+The [tool guide](docs/tools.md) explains results, linked artifacts and long operations.
+
+## How it fits your workflow
+
+The server works through your coding agent and follows the mod workspace you provide.
+It keeps large renders and reports in linked files, and retrieves relevant documentation sections instead of whole manuals.
+Your repository instructions and review process still apply.
+
+Inspection and rendering do not edit the mod.
+The focus, GUI and map rewrite tools can change source files after checking the proposed edit.
+The server does not launch or control the game; previews and source tests cannot prove live clicks, AI choices or engine timing.
+
+[Documentation](docs/README.md) · [Tool reference](docs/tools.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md)
+
+Apache-2.0 licensed.
+Hearts of Iron IV artwork belongs to its respective owners; this project is unaffiliated with Paradox Interactive.

package/dist/hoi4_agent_tools/core/engine.js

@@ -182,13 +182,6 @@ export class CoreEngine {
                         signal: controller.signal,
                     });
                     controller.signal.throwIfAborted();
-                    const persistentAnalysisCache = await this.persistentAnalysisCache;
-                    const analysisScope = {
-                        workspaceIdentity: workspace.workspaceIdentity,
-                        rootFingerprint: transactionRootFingerprint(workspace),
-                        principal: principal ?? null,
-                    };
-                    await persistentAnalysisCache?.hydrate(analysisScope, files, sourceDocuments, this.indexSegments, controller.signal);
                     const revision = hashCanonical(files.map(({ absolutePath, displayPath, relativePath, rootKind, loadOrder, shadowedBy, sha256, }) => ({
                         absolutePath,
                         displayPath,
@@ -202,6 +195,13 @@ export class CoreEngine {
                     const cached = this.#scanCache.get(cacheKey);
                     if (cached !== undefined)
                         return cached;
+                    const persistentAnalysisCache = await this.persistentAnalysisCache;
+                    const analysisScope = {
+                        workspaceIdentity: workspace.workspaceIdentity,
+                        rootFingerprint: transactionRootFingerprint(workspace),
+                        principal: principal ?? null,
+                    };
+                    await persistentAnalysisCache?.hydrate(analysisScope, files, sourceDocuments, this.indexSegments, controller.signal);
                     const index = await SymbolIndex.buildAsync(files, controller.signal, this.indexSegments);
                     await persistentAnalysisCache?.persist(analysisScope, files, sourceDocuments, this.indexSegments, controller.signal);
                     const snapshot = {

package/dist/hoi4_agent_tools/core/file-glob.js

@@ -0,0 +1,164 @@
+import path from 'node:path';
+import { escape, globIterate, hasMagic, Ignore, unescape } from 'glob';
+import { lstat, readdir } from 'node:fs/promises';
+import { ServiceError } from './result.js';
+function validatePatterns(patterns) {
+    if (patterns.length > 8192)
+        throw new ServiceError('SCAN_PATTERN_LIMIT', 'Too many source glob patterns');
+    let wildcardCount = 0;
+    for (const pattern of patterns) {
+        if (Buffer.byteLength(pattern, 'utf8') > 4096)
+            throw new ServiceError('SCAN_PATTERN_LIMIT', 'Source glob pattern exceeds its byte limit');
+        if (pattern.startsWith('/') ||
+            /^[A-Za-z]:/u.test(pattern) ||
+            pattern.split('/').includes('..') ||
+            pattern.includes('\0'))
+            throw new ServiceError('SCAN_PATTERN_ESCAPE', 'Source glob patterns must stay relative to the authorized root');
+        let depth = 0;
+        const groups = [];
+        let expansions = 1;
+        for (let index = 0; index < pattern.length; index++) {
+            const character = pattern[index];
+            if (character === '\\') {
+                index++;
+                continue;
+            }
+            if (character === '{') {
+                if (++depth > 8)
+                    throw new ServiceError('SCAN_PATTERN_LIMIT', 'Source glob brace nesting exceeds its limit');
+                groups.push({ start: index + 1, choices: 1 });
+            }
+            if (character === ',' && groups.length > 0)
+                groups.at(-1).choices++;
+            if (character === '}') {
+                depth = Math.max(0, depth - 1);
+                const group = groups.pop();
+                if (group === undefined)
+                    continue;
+                const range = /^(-?\d+|[A-Za-z])\.\.(-?\d+|[A-Za-z])(?:\.\.(-?\d+))?$/u.exec(pattern.slice(group.start, index));
+                if (range !== null) {
+                    const first = /^-?\d+$/u.test(range[1]) ? Number(range[1]) : range[1].charCodeAt(0);
+                    const last = /^-?\d+$/u.test(range[2]) ? Number(range[2]) : range[2].charCodeAt(0);
+                    const step = Math.abs(Number(range[3] ?? 1));
+                    group.choices = Math.floor(Math.abs(last - first) / step) + 1;
+                }
+                expansions *= group.choices;
+                if (!Number.isSafeInteger(expansions) || expansions > 128)
+                    throw new ServiceError('SCAN_PATTERN_LIMIT', 'Source glob expansion exceeds its limit');
+            }
+        }
+        // Validate brace complexity before invoking the glob parser, which can expand braces.
+        if (hasMagic(pattern, { magicalBraces: true }) && ++wildcardCount > 512)
+            throw new ServiceError('SCAN_PATTERN_LIMIT', 'Too many wildcard source glob patterns');
+    }
+}
+/** Relative, cancellable enumeration without traversing symbolic-link directories. */
+export async function* iterateFiles(patterns, options) {
+    validatePatterns(patterns);
+    validatePatterns(options.ignore ?? []);
+    options.signal?.throwIfAborted();
+    const nocase = options.caseSensitive === false;
+    const excluded = new Ignore([...(options.ignore ?? [])], { nocase });
+    const seen = new Set();
+    const allowedPatterns = [];
+    for (const pattern of new Set(patterns)) {
+        let current = options.cwd;
+        let allowed = true;
+        let literal = true;
+        let finalIsFile = false;
+        for (const part of pattern.split('/')) {
+            if (hasMagic(part, { magicalBraces: true })) {
+                literal = false;
+                break;
+            }
+            let name = unescape(part);
+            let candidate = path.resolve(current, name);
+            const relative = path.relative(options.cwd, candidate).replaceAll('\\', '/');
+            if (relative === '..' || relative.startsWith('../') || path.isAbsolute(relative))
+                throw new ServiceError('SCAN_PATTERN_ESCAPE', 'Literal glob prefix escaped its authorized root');
+            let metadata;
+            try {
+                metadata = await lstat(candidate);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT' &&
+                    error.code !== 'ENOTDIR')
+                    throw error;
+                if (!nocase) {
+                    allowed = false;
+                    break;
+                }
+                try {
+                    name =
+                        (await readdir(current)).find((entry) => entry.toLowerCase() === name.toLowerCase()) ??
+                            name;
+                    candidate = path.resolve(current, name);
+                    metadata = await lstat(candidate);
+                }
+                catch {
+                    allowed = false;
+                    break;
+                }
+            }
+            if (metadata.isSymbolicLink()) {
+                allowed = false;
+                break;
+            }
+            finalIsFile = metadata.isFile();
+            current = candidate;
+        }
+        if (!allowed)
+            continue;
+        if (literal) {
+            if (!finalIsFile)
+                continue;
+            const relative = path.relative(options.cwd, current).replaceAll('\\', '/');
+            if (excluded.relative.some((rule) => rule.match(relative)) ||
+                excluded.absolute.some((rule) => rule.match(current)))
+                continue;
+            options.signal?.throwIfAborted();
+            if (!seen.has(relative)) {
+                seen.add(relative);
+                yield relative;
+            }
+        }
+        else
+            allowedPatterns.push(pattern);
+    }
+    if (allowedPatterns.length === 0)
+        return;
+    const matches = globIterate(allowedPatterns, {
+        cwd: options.cwd,
+        withFileTypes: true,
+        nodir: true,
+        dot: false,
+        follow: false,
+        nocase,
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+        ignore: {
+            ignored: (entry) => entry.isSymbolicLink() || excluded.ignored(entry),
+            childrenIgnored: (entry) => entry.isSymbolicLink() || excluded.childrenIgnored(entry),
+        },
+    });
+    for await (const entry of matches) {
+        options.signal?.throwIfAborted();
+        if (!entry.isFile() || entry.isSymbolicLink())
+            continue;
+        const relative = path.relative(options.cwd, entry.fullpath()).replaceAll('\\', '/');
+        if (relative === '..' || relative.startsWith('../') || path.isAbsolute(relative))
+            throw new ServiceError('SCAN_PATTERN_ESCAPE', 'Glob result escaped its authorized root');
+        if (!seen.has(relative)) {
+            seen.add(relative);
+            yield relative;
+        }
+    }
+}
+export async function globFiles(patterns, options) {
+    const files = [];
+    for await (const file of iterateFiles(patterns, options))
+        files.push(file);
+    return files;
+}
+export function escapeFileGlob(relativePath) {
+    return escape(relativePath, { magicalBraces: true });
+}

package/dist/hoi4_agent_tools/core/index-segments.js

@@ -38,6 +38,10 @@ export class IndexSegmentCache {
         this.#entries.set(address, entry);
         return JSON.parse(entry.encoded);
     }
+    /** Availability check without decoding or cache-hit accounting. */
+    has(address) {
+        return this.#entries.has(address);
+    }
     /** Import one authenticated canonical entry without counting it as a process-local hit. */
     importEncoded(address, encoded) {
         const segment = JSON.parse(encoded);

package/dist/hoi4_agent_tools/core/job-operation-registration.js

@@ -0,0 +1,31 @@
+import { JobOperations } from './job-executor.js';
+import { ServiceError } from './result.js';
+/** Load one trusted domain after the authenticated job identifies its operation. */
+export async function registerWorkerOperations(engine, toolName) {
+    const operations = new JobOperations();
+    if (toolName.startsWith('hoi4.event_'))
+        (await import('../event/job-operations.js')).registerEventJobs(operations, engine);
+    else if (toolName.startsWith('hoi4.focus_'))
+        (await import('../focus/job-operations.js')).registerFocusJobs(operations, engine);
+    else if (toolName.startsWith('hoi4.gui_'))
+        (await import('../gui/job-operations.js')).registerGuiJobs(operations, engine);
+    else if (toolName.startsWith('hoi4.map_'))
+        (await import('../map/job-operations.js')).registerMapJobs(operations, engine);
+    else if (toolName.startsWith('hoi4.probability_'))
+        (await import('../probability/job-operations.js')).registerProbabilityJobs(operations, engine);
+    else if (toolName.startsWith('hoi4.tech_'))
+        (await import('../technology/job-operations.js')).registerTechnologyJobs(operations, engine);
+    else if ([
+        'hoi4.impact_inspect',
+        'hoi4.decision_inspect',
+        'hoi4.mechanic_test',
+        'hoi4.package_check',
+        'hoi4.scenario_test',
+    ].includes(toolName))
+        (await import('./analysis-job-operations.js')).registerAnalysisJobs(operations, engine);
+    else
+        throw new ServiceError('JOB_OPERATION_UNAVAILABLE', 'No trusted worker domain matches this job');
+    // A matching prefix never authorizes an unknown suffix or a client-selected module.
+    operations.get(toolName);
+    return operations;
+}

package/dist/hoi4_agent_tools/core/job-worker-host.js

@@ -149,9 +149,11 @@ export class JobWorkerHost {
             stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
             windowsHide: true,
         });
+        let phase = 'waiting_for_ready';
+        let acknowledgmentTimer;
         const initialized = new Promise((resolve, reject) => {
             child.once('error', reject);
-            child.once('exit', () => reject(new ServiceError('JOB_WORKER_STARTUP_EXIT', 'The worker exited before completing its readiness handshake')));
+            child.once('exit', (code, signal) => reject(new ServiceError('JOB_WORKER_STARTUP_EXIT', `The worker exited before completing its startup handshake (phase ${phase}, exit ${code ?? 'none'}, signal ${signal ?? 'none'})`)));
             child.once('message', (value) => {
                 void (async () => {
                     if (typeof value !== 'object' ||
@@ -162,7 +164,23 @@ export class JobWorkerHost {
                         throw new ServiceError('JOB_WORKER_PROTOCOL', 'The worker did not provide its readiness handshake');
                     await lease.handoffToProcess(child.pid);
                     await new Promise((resolve, reject) => {
-                        child.once('disconnect', resolve);
+                        phase = 'waiting_for_acceptance';
+                        acknowledgmentTimer = setTimeout(() => reject(new ServiceError('JOB_WORKER_ACCEPT_TIMEOUT', 'The worker did not acknowledge receipt within its startup window')), 30_000);
+                        child.once('message', (accepted) => {
+                            if (typeof accepted !== 'object' ||
+                                accepted === null ||
+                                !('type' in accepted) ||
+                                accepted.type !== 'accepted') {
+                                reject(new ServiceError('JOB_WORKER_PROTOCOL', 'The worker did not acknowledge the dispatched job'));
+                                return;
+                            }
+                            phase = 'accepted';
+                            // Only close IPC after the child confirms receipt. The persistent job,
+                            // rather than the launcher's lifetime, owns execution after this point.
+                            if (child.connected)
+                                child.disconnect();
+                            resolve();
+                        });
                         child.send({
                             configuration: {
                                 ...configuration,
@@ -178,14 +196,7 @@ export class JobWorkerHost {
                             jobId: id,
                             ...(principal === undefined ? {} : { principal }),
                         }, (error) => {
-                            if (error === null) {
-                                // IPC is startup-only. Closing it after dispatch prevents launcher
-                                // lifetime from becoming an implicit cancellation channel.
-                                if (child.connected)
-                                    child.disconnect();
-                                resolve();
-                            }
-                            else
+                            if (error !== null)
                                 reject(error);
                         });
                     });
@@ -199,7 +210,12 @@ export class JobWorkerHost {
                 });
             });
         });
-        await initialized;
+        try {
+            await initialized;
+        }
+        finally {
+            clearTimeout(acknowledgmentTimer);
+        }
         for (;;) {
             const record = await this.jobs.get(workspaceId, id, principal);
             if (['completed', 'failed', 'cancelled'].includes(record.status))