hoi4-agent-tools 3.5.0 → 3.6.0

package/docs/setup.md

@@ -1,50 +1,74 @@
 # Setup
 
-For Codex, the supplied registration allows 120 seconds for startup and 600 seconds per tool call.
-Large source scans and GUI renders can take several minutes; keep selectors and scenario matrices bounded and use negotiated task support when available.
-`tool_timeout_sec` is the per-server tool deadline described in the [official configuration reference](https://developers.openai.com/ja-JP/docs/config-file/config-reference).
+You need a coding agent that supports MCP and Node.js 22.19+ in the Node 22 line, or Node.js 24.
+Keep an installed copy of Hearts of Iron IV available for vanilla references, artwork and fonts.
 
-HOI4 Agent Tools requires Node.js 22.19 or later in the Node 22 line, or Node.js 24.
-
-## Install
+## 1. Install
 
 ```bash
 npm install --global hoi4-agent-tools
 ```
 
-Set the MCP process working directory to the mod being edited. The server creates its local workspace in memory, keeps generated artifacts in the per-user data directory, and starts without a config file. The installed game is detected when available for vanilla references; it is not required for source inspection or offline rendering.
+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.
+
+## 2. Connect your agent
+
+```bash
+hoi4-agent-tools-setup --print-client-config
+```
+
+Copy the printed `globalInstall` configuration into your MCP client, or use `codexTomlGlobal` for a TOML-based Codex configuration.
+The printed command is correct for your platform.
+
+Open the mod as your agent's workspace.
+If your client does not supply workspace roots, set the MCP process working directory to that mod folder.
+The server can then select the active mod without a separate configuration file.
+It keeps indexes and generated images in your user data directory.
 
-When the MCP server starts with its working directory inside a mod, every focus, GUI, map, event, and technology call uses that mod automatically. Configured multi-mod or remote deployments can use explicit workspace selection.
+## 3. Try a small task
 
-Local startup accepts normal descriptor-based mods and sparse descriptor-less mods that contain standard HOI4 content folders. Empty roots need a `descriptor.mod` or an explicit configuration so the server does not guess an unrelated directory.
+> Find the focus trees in this mod and render one of them.
 
-## Optional persistent configuration
+> Find the installed documentation for `save_event_target_as` and read only the relevant section.
 
-Use `--init` only when you need several mod roots, a fixed game path, or a shared/remote process:
+Continue with the [examples guide](examples.md).
+A mod normally has `descriptor.mod` or standard HOI4 content folders; an empty folder needs a descriptor or explicit configuration.
 
-### Configure explicit paths
+## Choose game and mod paths
 
-Use explicit paths when discovery is incomplete or when you want to expose more than one mod root:
+Use explicit paths if automatic discovery cannot find the game, or if you want to configure several mods:
 
 ```bash
-hoi4-agent-tools-setup --init --mod-root /projects/hoi4-mods --mod-root /workshop/hoi4-mods --game-root "/games/Hearts of Iron IV" --workspace-storage-root /var/lib/hoi4-agent-tools
+hoi4-agent-tools-setup --init --mod-root "/projects/hoi4-mods" --game-root "/games/Hearts of Iron IV"
+hoi4-agent-tools-setup --print-client-config
 ```
 
-- `--mod-root PATH` adds a parent folder containing mods. Repeat it for additional locations.
-- `--game-root PATH` selects the installed game folder used for vanilla references.
-- `--workspace-storage-root PATH` selects where indexes, renders, and other generated workspace files are stored.
-- `--config PATH` writes or reads a config at a custom path instead of the default per-user location.
+`--mod-root` is a parent folder containing mod directories, not the game installation.
+It can be repeated for several locations.
+`--game-root` points to the installed game.
+Use quoted Windows paths on Windows, for example `"C:/Program Files (x86)/Steam/steamapps/common/Hearts of Iron IV"`.
 
-The corresponding config fields are `modRoots`, `gameRoot`, and `workspaceStorageRoot`.
+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.
 
-For a configured workspace, `wikiRoot` can select an absolute path to an offline Paradox Wiki snapshot and `scriptDocsRoot` can select an absolute path to a user-supplied generated documentation dump. Without these fields, the reference tools look for `paradox_wiki/` and `script_docs/` inside the mod. See [Local references](reference.md).
+## Add local reference material
 
-Linked directory entries are not followed. If a mod folder is a symlink or junction, configure the real parent directory as another `--mod-root`.
+Place an offline wiki snapshot in `paradox_wiki/` inside the mod.
+An optional generated documentation dump can go in `script_docs/`.
+For a configured workspace, `wikiRoot` and `scriptDocsRoot` can point to other absolute directories.
+The server reads these local files; it does not download the wiki.
+See [Local references](reference.md) for source selection and missing-source reports.
 
-## MCP client registration
+## Common problems
 
-```bash
-hoi4-agent-tools-setup --print-client-config
-```
+| Problem                             | Check                                                                                                                       |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| The agent cannot find a mod         | Open the mod workspace, set the server working directory, or configure its real parent with `--mod-root`.                   |
+| A render lacks icons or fonts       | Confirm `--game-root` and the mod's asset paths. Read the missing-file findings.                                            |
+| A control's state is unresolved     | Supply the scenario's required country, state, controller or variable inputs; do not assume a visible control is available. |
+| A large query takes several minutes | Start with the specific tree, window or source area you need. Use [background jobs](jobs.md) when supported by your client. |
 
-Use the printed `globalInstall` or `codexTomlGlobal` entry. It is platform-correct and uses the default config without an environment variable. For a custom config, add `--config PATH` when printing the registration.
+The supplied Codex registration allows 120 seconds for startup and 600 seconds per tool call.
+For remote or shared deployments, use the [HTTP guide](http.md).

package/docs/tools.md

@@ -0,0 +1,64 @@
+# Tool reference
+
+Most users can ask their agent in ordinary language; the [examples guide](examples.md) is the best starting point.
+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.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
+
+Inspect findings and missing inputs along with the image or result.
+A rendered control does not by itself prove native availability, and a source simulation is not a game-engine receipt.
+For reference searches, retain the cited file, lines and revision so you can reopen the same section.
+
+Large results are returned as linked `hoi4-agent://` resources.
+Follow `continuationUri` until it is `null`; clients can also request byte ranges with `?offset=<bytes>&length=<bytes>`.
+Archive images you need to keep rather than relying on temporary server storage.
+
+## Longer operations
+
+Clients that negotiate MCP tasks can retrieve a long operation after reconnecting.
+Other clients receive the ordinary synchronous result.
+Use `hoi4.job_inspect` to inspect an authorized job or retrieve its result, and `hoi4.job_cancel` to request cancellation.
+See [Background jobs](jobs.md) for request keys, cancellation and recovery.
+
+## Optional ChaosX tools
+
+Setting `HOI4_AGENT_TOOLS_CHAOSX=1` on the server process exposes `chaosx.focus_country_assets` and `chaosx.visual_revision`.
+These workflow-specific tools are absent from the default public list.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "hoi4-agent-tools",
   "mcpName": "io.github.klimPaskov/hoi4-agent-tools",
-  "version": "3.5.0",
-  "description": "Analyze HOI4 events, decisions, impact, tech, AI, and MTTH; build focus trees, GUIs, and maps.",
+  "version": "3.6.0",
+  "description": "HOI4 modding tools for agents: local references, visual previews, focus trees, interfaces and maps.",
   "type": "module",
   "license": "Apache-2.0",
   "author": "HOI4 Agent Tools contributors",
@@ -40,6 +40,8 @@
     "dist/",
     "docs/README.md",
     "docs/setup.md",
+    "docs/examples.md",
+    "docs/tools.md",
     "docs/events.md",
     "docs/analysis.md",
     "docs/mechanics.md",

package/schemas/configuration.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.5.0/schemas/configuration.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.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/v3.5.0/schemas/continuous-focus-palette.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.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/v3.5.0/schemas/custom-weighted-pool.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.6.0/schemas/custom-weighted-pool.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/decision-inspect-input.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.5.0/schemas/decision-inspect-input.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.6.0/schemas/decision-inspect-input.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/v3.5.0/schemas/event-feature-manifest.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.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/v3.5.0/schemas/focus-plan.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.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/v3.5.0/schemas/focus-planning-sidecar.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.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/v3.5.0/schemas/gui-animation-source.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.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/v3.5.0/schemas/gui-helper.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v3.6.0/schemas/gui-helper.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {