hoi4-agent-tools 3.10.0 → 4.0.0

package/docs/setup.md

@@ -1,6 +1,6 @@
 # Setup
 
-You need a coding agent that supports MCP and Node.js 22.19+ in the Node 22 line, or Node.js 24.
+You need a coding agent that supports MCP and Node.js 22 (22.19 or later) or Node.js 24.
 Keep an installed copy of Hearts of Iron IV available for vanilla references, artwork and fonts.
 
 ## 1. Install
@@ -21,13 +21,28 @@ Previews need the assets and fonts referenced by the mod; missing files are repo
 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.
+The command prints four alternatives:
+
+| Key               | Use it for                                                                    |
+| ----------------- | ----------------------------------------------------------------------------- |
+| `globalInstall`   | JSON clients (Claude Code, Claude Desktop, Cursor and others), global install |
+| `codexTomlGlobal` | Codex `config.toml`, global install                                           |
+| `generic`         | JSON clients that should start a pinned version through `npx`                 |
+| `codexToml`       | Codex `config.toml` through `npx`                                             |
+
+Copy one of them into your MCP client; the printed command is correct for your platform.
+The Codex entries also set `startup_timeout_sec = 120`, `tool_timeout_sec = 600` and an idle limit, because the first scan of a large mod and long renders exceed Codex's default timeouts.
+The [client examples](../examples/clients) show the same entries without your paths.
 
 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.
+
+### How the server picks your mod
+
+Every tool takes an optional `workspaceId`; the default, `"current"`, means the mod that contains the client's workspace root or, when the client sends no roots, the server's working directory.
+With no configuration file, the server configures itself from that folder, so set the MCP process working directory to the mod if your client does not supply roots.
+After `--init` writes a configuration file, every folder under its mod roots is a workspace, and the current mod is the one that contains the client root or working directory; when that matches no mod and several are configured, pass the mod's `workspaceId`.
+The [configuration reference](configuration.md#how-the-server-picks-your-mod) gives the exact rules, the default file location, every key and the environment variables.
+Indexes are kept in the server's state folder and generated images in workspace storage, both in your user data directory by default.
 
 ## 3. Try a small task
 
@@ -36,7 +51,7 @@ It keeps indexes and generated images in your user data directory.
 > Find the installed documentation for `save_event_target_as` and read only the relevant section.
 
 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.
+Without a configuration file, the folder must look like a mod: it needs `descriptor.mod` or standard HOI4 content folders.
 
 ## Choose game and mod paths
 
@@ -53,7 +68,7 @@ It can be repeated for several locations.
 Use quoted Windows paths on Windows, for example `"C:/Program Files (x86)/Steam/steamapps/common/Hearts of Iron IV"`.
 
 For a custom configuration location, add `--config PATH` to both setup commands.
-`--workspace-storage-root PATH` chooses where generated indexes and images are saved.
+`--workspace-storage-root PATH` chooses where generated images and rewrite transactions are saved.
 Linked mod directories are not followed; configure their real parent directory instead.
 
 ### How sources are layered
@@ -85,16 +100,34 @@ See [Local references](reference.md) for source selection and missing-source rep
 | 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. |
 | Idle server processes accumulate    | Set an idle limit as described in [Server lifetime](#server-lifetime).                                                      |
+| The game reported errors at startup | Ask the agent to read them with `hoi4.error_log`; set `gameUserRoot` if the game's user folder is not found automatically.  |
+| Startup or a tool call times out    | Raise the client's timeouts; the printed Codex entries allow 120 seconds for startup and 600 seconds per call.              |
+
+Two setup commands help with path problems:
 
-The supplied Codex registration allows 120 seconds for startup and 600 seconds per tool call.
+```bash
+hoi4-agent-tools-setup --discover
+hoi4-agent-tools-setup --diagnose
+```
+
+`--discover` prints the mod and game folders the server can detect, without writing anything.
+`--diagnose` checks the configured paths and their permissions, the Node.js version and the image library, and accepts `--config PATH`.
+`--help` lists every option.
 
 For remote or shared deployments, use the [HTTP guide](http.md).
 
+### A running game
+
+This server reads source and never launches, controls or watches the game.
+Pair it with a live-game MCP server, such as the separate HOI4 Live Tools project, for anything that needs the running game: launching and loading saves, the console, firing events, reading popups and the screen, playing time forward, and log deltas during a session.
+Use this server to find and fix the source (`hoi4.error_log` maps last launch's errors to files and says which ones a relaunch removed), and the live server to reproduce and confirm in game.
+
 ### Server lifetime
 
-A stdio server exits when its client closes stdin, and when the process that launched it, such as a `cmd.exe` shim, has exited.
+A stdio server exits when its client closes stdin, and when the process that launched it, such as a `cmd.exe` shim, has exited and no request is still open.
 Some clients start a server for every subagent and keep each connection open after the subagent finishes, so idle servers accumulate and each holds its own index in memory.
-A server with no client traffic and no open request for `stdioIdleExitMinutes` minutes exits.
+A server with no client traffic and no open request for `stdioIdleExitMinutes` minutes (0–10,080) exits.
 That setting applies to every client sharing the server configuration, so prefer the `HOI4_AGENT_STDIO_IDLE_EXIT_MINUTES` environment variable in the affected client's registration; the Codex registrations printed by `hoi4-agent-tools-setup --print-client-config` set it to 30.
+The variable takes a whole number from 0 to 10,080; an empty value uses the configuration, and any other value stops the server at startup with an error.
 A client that later calls an exited server reports it as disconnected, so leave the limit at `0` (never) for a single long-lived session.
 Over stdio, read the `hoi4-agent://server/status` resource to see every server process that shares the server state root, with its transport, memory, last client activity and the execution limits in effect. Records of exited processes are removed on read; a server that has not updated its record for five minutes is listed as stale.

package/docs/technology.md

@@ -18,6 +18,24 @@ Use the three technology tools directly from the target mod.
 - `impact`: find the definitions, placements, edges, grants, bonuses, unlocks, localisation, sprites, and files affected by a proposed removal or rename.
 - `helper_expansion`: stream source-linked scripted-effect call paths and helper-owned technology references with bounded pages and revision-bound continuation.
 
+Request fields select the records each mode reads:
+
+| Field                    | Used by                                                            | Meaning                                                                                                       |
+| ------------------------ | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
+| `technologyId`           | `trace`, `explain` (required); `unlocks`, `bonus_coverage`, `lint` | Technology to trace or explain, or a filter for the other modes.                                              |
+| `folderId`               | `folders`, `lint`                                                  | Folder to inspect, or a lint filter.                                                                          |
+| `categoryId`             | `bonus_coverage`                                                   | Technology category whose research-bonus coverage is reported.                                                |
+| `targetKind`             | `unlocks`                                                          | Unlock target kind: `equipment`, `equipment_module`, `sub_unit`, `building`, `ability`, `tactic`, or `other`. |
+| `targetId`               | `unlocks`                                                          | Unlock target ID.                                                                                             |
+| `direction`              | `trace`                                                            | `prerequisites`, `descendants`, or `both` (default).                                                          |
+| `maxDepth`               | `trace`                                                            | Traversal depth, 1 to 256, default 32.                                                                        |
+| `maxNodes`               | `trace`                                                            | Traversed nodes, 1 to 25,000, default 2,000.                                                                  |
+| `includeSubTechnologies` | `trace`                                                            | Follow sub-technology edges as well as prerequisites; default `true`.                                         |
+| `classifications`        | `lint`                                                             | Up to 4 of `confirmed_error`, `probable_defect`, `design_warning`, and `unresolved_analysis`.                 |
+| `codes`                  | `lint`                                                             | Up to 100 diagnostic codes.                                                                                   |
+| `impact`                 | `impact` (required)                                                | Removal or rename subject, described below.                                                                   |
+| `helperExpansion`        | `helper_expansion`                                                 | Bounded helper-expansion request; see [bounded helper expansion](helper-expansion.md).                        |
+
 Example trace:
 
 ```json
@@ -64,6 +82,11 @@ Render validation is scoped to the requested view: folder source placement, omit
 
 Subtechnology cards use the sprite declared by their source GUI slot before any technology-id fallback. Slot-declared textures are included in the bounded asset scan even when no ordinary technology icon references the same file.
 
+`hoi4.tech_render` accepts `folderId` (required for the `folder` view), `technologyId`, `categoryId`, and `targetId`.
+`technologyId` selects the traced neighbourhood in the `dependencies` and `technology` views and filters the `bonuses`, `grants`, and `unlocks` views.
+`categoryId` filters the `memberships`, `bonuses`, and `grants` views, and `targetId` filters the `unlocks` view.
+`maxNodes` ranges from 1 to 2,000 and defaults to 1,000.
+
 Example folder render:
 
 ```json
@@ -81,9 +104,11 @@ Large dependency requests return a bounded overview plus focused folder resource
 
 ## Compare
 
-`hoi4.tech_compare` compares cached revisions, graph resources, current source, or proposed in-memory source overlays. It reports added, removed, renamed, or moved technologies; graph and placement changes; metadata, category, tag, unlock, grant, bonus, localisation, and icon changes; introduced and resolved findings; and newly reachable or disconnected content.
+`hoi4.tech_inspect` with `mode: compare` compares cached revisions, graph resources, current source, or proposed in-memory source overlays. It reports added, removed, renamed, or moved technologies; graph and placement changes; metadata, category, tag, unlock, grant, bonus, localisation, and icon changes; introduced and resolved findings; and newly reachable or disconnected content.
 
 `before` and `after` each accept `{ "revision": "<sha256>" }` or `{ "artifactUri": "hoi4-agent://..." }`. Proposed overlays take `{ relativePath, source, expectedSourceHash? }`; use `source: null` to model deletion. Overlays are analyzed without writing them.
+A request takes between 1 and 128 overlays, and `after` and `proposedSources` are mutually exclusive.
+The comparison render is produced unless `render` is `false`; `maxRenderNodes` ranges from 1 to 2,000 and defaults to 500.
 
 ```json
 {

package/docs/third-party-notices.md

@@ -0,0 +1,11 @@
+# Third-party notices
+
+## Roboto
+
+HOI4 Agent Tools depends on `@fontsource-variable/roboto` version 5.3.0 for deterministic, host-independent artifact labels and the project-owned synthetic BMFont fixture.
+
+Copyright 2011 The Roboto Project Authors (<https://github.com/googlefonts/roboto-classic>). Roboto-Italic[wdth,wght].ttf: Copyright 2011 The Roboto Project Authors (<https://github.com/googlefonts/roboto-classic>).
+
+Roboto is licensed under the SIL Open Font License, Version 1.1 (`OFL-1.1`). The complete license text is distributed as `LICENSE` in the installed `@fontsource-variable/roboto` package. The font package is pinned in `package.json` and the published `npm-shrinkwrap.json`; generated SVG/PNG documents may contain derived glyph outlines or pixels as permitted by the OFL.
+
+The application source remains licensed under Apache-2.0 as stated in the repository [LICENSE](../LICENSE). Third-party components retain their respective licenses.

package/docs/tools.md

@@ -4,43 +4,152 @@ 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 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 a snippet or a whole mod file for syntax, command kinds, and 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.                                |
+The default server exposes 28 tools in nine areas.
+The **Writes** column says what a call can change:
+
+- **—** reads source and returns a result.
+- **review files** writes images and reports to the server's own workspace storage, never to the mod.
+- **mod files** changes mod source after validating the edit, with a recorded transaction that can be rolled back.
+
+MCP clients see the review-file tools as not read-only, because they store artifacts, and may ask for approval before running them.
+`hoi4.job_cancel` is marked destructive because it stops work in progress; it never edits source.
+
+## References and source
+
+| Tool                     | Purpose                                                                                                                                   | Writes |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | ------ |
+| `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: up to 80 lines (40 by default) and 8,000 bytes, 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 a snippet or a whole mod file for syntax, command kinds, and scopes against local documentation.                                    | —      |
+| `hoi4.error_log`         | Group the game's `error.log` from its last launch by category, with the source file, line and layer, and whether that file changed since. | —      |
+| `hoi4.mod_index`         | Summarize the mod's descriptor and definitions, or find the next free numbered ID for an event namespace or prefix across every layer.    | —      |
+
+## Focus trees
+
+| Tool                 | Purpose                                                                                                                    | Writes       |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------ |
+| `hoi4.focus_inspect` | Read focus trees, continuous-focus placement, and structural or reference problems.                                        | review files |
+| `hoi4.focus_render`  | Render a tree or palette as a PNG with decoded icons plus HTML, SVG, JSON and source maps; `png: false` for vector only.   | review files |
+| `hoi4.focus_rewrite` | Create a focus tree or continuous-focus palette from a complete plan, or compact an existing tree's layout without a plan. | mod files    |
+
+## Scripted GUIs
+
+| Tool               | Purpose                                                                                                     | Writes       |
+| ------------------ | ----------------------------------------------------------------------------------------------------------- | ------------ |
+| `hoi4.gui_inspect` | Read a scripted GUI and its linked assets and logic.                                                        | review files |
+| `hoi4.gui_render`  | Render generated and explicit GUI scenarios, states, resolutions, and layout diagnostics.                   | review files |
+| `hoi4.gui_rewrite` | Apply one validated GUI change as full source, structured helpers, or exact patches, with extra text files. | mod files    |
+
+## Maps
+
+| Tool               | Purpose                                                                                                                                      | Writes       |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
+| `hoi4.map_inspect` | Validate, search and look up the map; render a layer, overlays, tile or area; check script references to map entities.                       | review files |
+| `hoi4.map_rewrite` | Create a new world, or create, split, merge and renumber states and provinces, regenerate positions and supply, and remap script references. | mod files    |
+
+## Events
+
+| Tool                 | Purpose                                                                                                                             | Writes |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------ |
+| `hoi4.event_inspect` | Scan, trace, explain, lint, or assess event chains and their state flow; `mode: compare` diffs cached, artifact or proposed graphs. | —      |
+| `hoi4.event_render`  | Render source-linked event routes, options, timing, state, scope, and unresolved edges.                                             | —      |
+
+## Technology and doctrines
+
+| Tool                | Purpose                                                                                                                   | Writes |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------ |
+| `hoi4.tech_inspect` | Scan, trace, explain, lint, and assess technology and doctrine systems; `mode: compare` diffs graphs and source overlays. | —      |
+| `hoi4.tech_render`  | Render source layouts with real item sizes and year guides, plus dependencies and assets.                                 | —      |
+
+## AI weights and timing
+
+| Tool                       | Purpose                                                                                                                  | Writes |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------ |
+| `hoi4.probability_inspect` | Find weighted logic by path, ID or candidate IDs and evaluate it: weights, probabilities and the facts still missing.    | —      |
+| `hoi4.probability_analyze` | Compare a proposed source, sweep ranges, simulate uncertainty, analyze a declared pool over time, or render an analysis. | —      |
+
+## Decisions, impact and tests
+
+| Tool                    | Purpose                                                                                   | Writes |
+| ----------------------- | ----------------------------------------------------------------------------------------- | ------ |
+| `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`    | Interpret declared effect steps on a copied scenario state 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.                   | —      |
+
+## Background jobs
+
+| Tool               | Purpose                                                                | Writes    |
+| ------------------ | ---------------------------------------------------------------------- | --------- |
+| `hoi4.job_inspect` | Inspect durable background work or retrieve its completed tool result. | —         |
+| `hoi4.job_cancel`  | Durably request cancellation of authorized background work.            | job state |
+
+## Prompts and resources
+
+The server offers one MCP prompt, `hoi4.probability_analysis`.
+It takes an `objective` and an optional `sourceHint` and returns a plan for one source-linked AI-weight, MTTH, random or declared-pool analysis; it does not run the analysis itself.
+
+Large results are returned as links to the resource template `hoi4-agent://workspace/{workspaceId}/artifact/{sha256}/{provenanceHash}/{name}`.
+Clients can read a byte range with `?offset=<bytes>&length=<bytes>`.
+
+Local stdio clients also see the fixed resource `hoi4-agent://server/status`, which lists the server processes sharing this server state, with memory use, last client activity and execution limits; see [server lifetime](setup.md#server-lifetime).
+Authenticated HTTP sessions never see it.
+
+## Arguments
+
+Tools accept the shorthands agents most often send and read them as the canonical form: an event selector as a plain string, a namespace wildcard such as `chaosx.nr14.*`, or an object without `kind` or with `id` for its own field; a trace's event as `from`, `eventId` or `namespace`; a GUI scenario without `id`, or none for a window inspection; a decision inspection by `id` or `decisionId` without a scenario; a probability scenario set as a bare list or without ids and `state`; a script file check that also names a kind and scope, which the file already fixes, and a snippet check without a `kind`, which is read as the effect or trigger with fewer errors. A `limit`, `maxDepth`, `maxNodes` or `maxEdges` above its maximum is lowered to the maximum.
+Anything still invalid comes back as a tool error, code `INVALID_ARGUMENTS`, that names each failing field with what it expected and shows a working call.
+It is a tool error rather than a protocol error because clients show a tool error's text to the model, while some reduce a protocol error to a generic message.
+Every error and blocked result also carries its blockers in the text content, so a client that shows only text still explains the failure.
+
+## Example calls
+
+Every tool description in `tools/list` ends with a call like these, and an invalid call returns the same example for its tool.
+Fields not shown take their defaults; `workspaceId` is `"current"` unless you pass one.
+The CI stdio smoke suite sends each of these shapes to a real server process.
+
+| Tool                       | Example arguments                                                                                                                                                                                                       |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `hoi4.reference_context`   | `{"surface":"event","question":"fire an event after a delay"}`                                                                                                                                                          |
+| `hoi4.reference_search`    | `{"query":"add_timed_idea"}`                                                                                                                                                                                            |
+| `hoi4.reference_read`      | `{"id":"<hit id>","revision":"<hit revision>"}` from a search or context hit                                                                                                                                            |
+| `hoi4.source_lookup`       | `{"symbol":"my_scripted_effect"}` or `{"path":"events/my_events.txt","line":42}`                                                                                                                                        |
+| `hoi4.script_validate`     | `{"source":"add_political_power = 10","kind":"effect","scope":"country"}` or `{"path":"events/my_events.txt"}`                                                                                                          |
+| `hoi4.error_log`           | `{"scope":"mod","category":"effect"}`                                                                                                                                                                                   |
+| `hoi4.mod_index`           | `{"mode":"overview"}` or `{"mode":"next_id","kind":"event","namespace":"my_mod"}`                                                                                                                                       |
+| `hoi4.focus_inspect`       | `{"treeId":"my_focus_tree"}`                                                                                                                                                                                            |
+| `hoi4.focus_render`        | `{"relativePath":"common/national_focus/my_tree.txt","treeId":"my_focus_tree"}`                                                                                                                                         |
+| `hoi4.focus_rewrite`       | `{"relativePath":"common/national_focus/my_tree.txt","treeId":"my_focus_tree","layoutMode":"compact"}`                                                                                                                  |
+| `hoi4.gui_inspect`         | `{"windowName":"my_window"}`                                                                                                                                                                                            |
+| `hoi4.gui_render`          | `{"windowName":"my_window","scenario":{"id":"normal"}}`                                                                                                                                                                 |
+| `hoi4.gui_rewrite`         | `{"mode":"helpers","relativePath":"interface/my_window.gui","windowName":"my_window","scenario":{"id":"normal"},"helper":{…}}`                                                                                          |
+| `hoi4.map_inspect`         | `{"query":"Brandenburg","lookupOnly":true}` or `{"layer":"state","tile":{"x":2600,"y":500,"width":256,"height":256}}`                                                                                                   |
+| `hoi4.map_rewrite`         | `{"operations":[{"id":"s1","kind":"create_state","provinceIds":[120,121],"displayName":"New State"}]}`                                                                                                                  |
+| `hoi4.event_inspect`       | `{"mode":"trace","selector":"my_mod.1","direction":"downstream"}`                                                                                                                                                       |
+| `hoi4.event_render`        | `{"view":"overview","selector":"my_mod"}`                                                                                                                                                                               |
+| `hoi4.tech_inspect`        | `{"mode":"explain","technologyId":"my_tech"}`                                                                                                                                                                           |
+| `hoi4.tech_render`         | `{"view":"folder","folderId":"my_folder"}`                                                                                                                                                                              |
+| `hoi4.probability_inspect` | `{"candidatePool":["my_decision"],"scenarioSet":[{"actor":"GER","state":{"has_war":false}}]}`                                                                                                                           |
+| `hoi4.probability_analyze` | `{"analysis":"sweep","source":"common/decisions/my_decisions.txt","candidatePool":["my_decision"],"scenarioSet":[{"actor":"GER","state":{"variable.pressure":10}}],"sweep":{"paths":["variable.pressure"],"steps":10}}` |
+| `hoi4.impact_inspect`      | `{"symbols":[{"kind":"scripted_effect","id":"my_effect"}]}`                                                                                                                                                             |
+| `hoi4.decision_inspect`    | `{"mode":"inspect","id":"my_decision","scenarios":[{"id":"base","actor":"GER","state":{}}]}`                                                                                                                            |
+| `hoi4.mechanic_test`       | `{"test":{"id":"t","scenario":{…},"steps":[…],"assertions":[…]}}`, see [Mechanic tests](mechanics.md)                                                                                                                   |
+| `hoi4.package_check`       | `{"manifest":{"schemaVersion":"1.0","id":"my_package","definitions":[{"kind":"scripted_effect","id":"my_effect"}]}}`                                                                                                    |
+| `hoi4.scenario_test`       | `{"suitePath":"tests/my_suite.json","maxCases":20}`                                                                                                                                                                     |
+| `hoi4.job_inspect`         | `{"jobId":"job_<64 hex characters>"}` from a native task id                                                                                                                                                             |
+| `hoi4.job_cancel`          | `{"jobId":"job_<64 hex characters>"}`                                                                                                                                                                                   |
+
+## Result sizes
+
+An inline result never exceeds 32 KB of structured content.
+Typical answers are 1 to 5 KB: counts, the main findings, the strongest candidates and links.
+Focus, GUI and map results are larger, up to about 24 KB, because they list trees, scenes or matches.
+The text content of a successful call is a short JSON summary (status, code, workspace and artifact count), so a client that shows only text still sees how the call ended; an error or blocked result puts its blockers in the text.
+Pictures are never inlined: renders, galleries, full graphs and per-candidate traces are linked artifacts that you read in ranges, and every inline list says how many items it omitted.
+A reference read is limited to 80 lines and 8,000 bytes; a source lookup returns at most 3 definitions and 10 usages.
 
 ## Reading results
 
@@ -48,18 +157,18 @@ 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>`.
+Follow `continuationUri` until it is `null` to read a long result in pages.
 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.
+All 19 domain tools accept negotiated MCP tasks, so a client that supports tasks can retrieve a long operation after reconnecting.
+The 7 reference tools and the 2 job tools always answer in the foreground.
 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.
+On the stdio server (`hoi4-agent-tools`), setting `HOI4_AGENT_TOOLS_CHAOSX=1` exposes `chaosx.focus_country_assets` and `chaosx.visual_revision`.
+These workflow-specific tools are absent from the default list, and the HTTP server never exposes them.

package/docs/troubleshooting.md

@@ -0,0 +1,61 @@
+# Troubleshooting
+
+Start with the message: every failed call returns a tool error whose text names the code, what went wrong and what to do next.
+This page lists the codes you are most likely to meet, then the checks for problems that have no code.
+
+## Setup and connection
+
+| Symptom                                                     | Cause and fix                                                                                                                                                                                       |
+| ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| The client lists no `hoi4.*` tools                          | The server did not start. Run `hoi4-agent-tools-setup --diagnose`, which checks the Node.js version (22.19 or newer, or 24), the image library and the configured paths. Then restart the client.   |
+| `WORKSPACE_CONTEXT_NOT_FOUND`                               | The server does not know which mod you mean. Open the mod folder as the client's working directory, or configure it with `--mod-root` or a workspace in the [configuration file](configuration.md). |
+| `WORKSPACE_CONTEXT_AMBIGUOUS`                               | The working directory is inside more than one configured mod. Pass `workspaceId`, or open the one folder you mean.                                                                                  |
+| `WORKSPACE_NOT_REGISTERED`                                  | The `workspaceId` is not in the configuration. Use `"current"`, or a workspace id from the configuration file.                                                                                      |
+| Renders lack icons or fonts, native commands are unresolved | The game folder is not configured. Set `--game-root` (or `gameRoot`) to the Hearts of Iron IV folder; `hoi4-agent-tools-setup --discover` prints the folders it can find.                           |
+| `ERROR_LOG_NOT_FOUND`                                       | Launch the game once, or set `gameUserRoot` to the folder that holds `logs/`, `mod/` and `save games/` (with OneDrive that is often under `OneDrive\Documents`).                                    |
+| `AUTH_INVALID` over HTTP                                    | The bearer token is missing, expired or for another server. See the [HTTP guide](http.md).                                                                                                          |
+| Startup or a call times out in the client                   | A cold scan of a large mod takes minutes. Raise the client's startup and tool timeouts (the printed Codex entries use 120 and 600 seconds), or use [background jobs](jobs.md).                      |
+| Many idle `node` processes                                  | Some clients keep a server per subagent. Set `HOI4_AGENT_STDIO_IDLE_EXIT_MINUTES`; see [Server lifetime](setup.md#server-lifetime).                                                                 |
+
+## Arguments and results
+
+| Code or symptom                         | Cause and fix                                                                                                                                                                                            |
+| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `INVALID_ARGUMENTS`                     | The call does not match the tool's schema. The error names each failing field, what it expected and a working call; copy that example, or see [Example calls](tools.md#example-calls).                   |
+| `valid: null` from `script_validate`    | Nothing is wrong that the checker could prove, but some commands, argument blocks or scopes were not checked. Read `unresolvedCount` and the unresolved findings; `null` is not a pass.                  |
+| `MCP_RESPONSE_TRUNCATED`                | The inline result exceeded its 32 KB budget. The omitted detail is in the linked artifacts (see `artifacts` in the structured content); narrow the selector for a smaller answer.                        |
+| `SCAN_SOURCE_CHANGED`                   | A file changed while it was being read. Repeat the call; if it keeps happening, stop the tool or editor that is rewriting the file.                                                                      |
+| `SCAN_BYTE_LIMIT`, `SCAN_PATTERN_LIMIT` | The request reads more source than the configured limits allow. Ask for the specific tree, window or folder, or raise the limits in [Scan and storage limits](configuration.md#scan-and-storage-limits). |
+| `REFERENCE_REVISION_STALE`              | A documentation file changed after the search. Search again and read with the new `id` and `revision`.                                                                                                   |
+| `REFERENCE_RESPONSE_TOO_LARGE`          | The citation bundle is too large for one reply. Lower `limit` or search a specific source.                                                                                                               |
+| `ARTIFACT_NOT_FOUND`                    | The artifact left the server's bounded store. Run the tool again; archive images you need to keep.                                                                                                       |
+| `JOB_DEADLINE_EXCEEDED`                 | A long job ran past `jobDeadlineSeconds` and was stopped. Narrow it, or raise the limit in the configuration.                                                                                            |
+| `JOB_STORE_BUSY`                        | A crashed server process still holds the job store lock. Wait for the lease to expire (ten minutes) or stop the stale `node` process.                                                                    |
+| `JOB_NOT_FOUND`                         | The finished result expired. Start the operation again.                                                                                                                                                  |
+
+## Rewrites
+
+Rewrite tools (`focus_rewrite`, `gui_rewrite`, `map_rewrite`) validate the whole candidate and write nothing when it fails.
+
+| Code                                     | Cause and fix                                                                                                                                                                                |
+| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `TRANSACTION_STALE`                      | A source file changed after the review was made. Inspect again and repeat the rewrite on the current source.                                                                                 |
+| `TRANSACTION_RECOVERY_REQUIRED`          | An earlier rewrite was interrupted and its journal could not be recovered yet. Reads still work; the message names the reason. Restart the server, and repair the named file if it persists. |
+| `TRANSACTION_ROLLBACK_STALE`             | A file changed since the rewrite, so it cannot be rolled back safely. Restore the file from version control.                                                                                 |
+| `MAP_STATE_DISTRIBUTION_REQUIRED`        | A state operation was given an incomplete explicit policy. Omit `distribution` for the automatic land-share policy, or send every field (see [Maps](map.md)).                                |
+| `MAP_STATE_REGION_DISTRIBUTION_CONFLICT` | Moved or merged provinces lie in different strategic regions. Use `strategicRegion: "move-to-target-region"`, or move the provinces between regions first.                                   |
+| `MAP_EXTERNAL_REFERENCE_READ_ONLY`       | Base-game or dependency scripts name a changed state. Repeat with `remapReferences` or `readOnlySources` set to `override` to copy them into the mod with the numbers changed.               |
+| `MAP_DATED_STATE_HISTORY_CONFLICT`       | A dated block (`1939.1.1 = { ... }`) overrides the value you are changing. Edit that block, or change the later date's value deliberately.                                                   |
+| `MAP_SCRIPT_REFERENCE_MISSING` (error)   | A script names a state, province or region the map does not define. Remap it with `remap_map_references`, or correct the script.                                                             |
+| `MAP_REFERENCE_NEEDS_REVIEW` (info)      | A single-valued argument such as `capital = 64` had no single successor and was left as it was. Choose its new target by hand.                                                               |
+
+## Game and live testing
+
+This server reads source and never starts the game.
+To reproduce a problem in game, read what the game logged with `hoi4.error_log` (the last launch only, with the file and line where the message names one), then fix the file and ask `hoi4.script_validate` with `path` to check it before relaunching.
+For launching, loading a save and watching a campaign, pair it with the separate HOI4 Live Tools server (see [A running game](setup.md#a-running-game)).
+
+## Still stuck
+
+Run `hoi4-agent-tools-setup --diagnose`, then open an issue at <https://github.com/klimPaskov/hoi4-agent-tools/issues> with the tool name, the arguments (without private paths), the error code and message, and the output of `hoi4-agent-tools-setup --diagnose`, which includes the server and Node.js versions.
+For a security problem use the [Security Policy](../SECURITY.md) instead of a public issue.

package/examples/clients/codex-config.toml

@@ -1,5 +1,8 @@
+# Codex registration for a global install (npm install --global hoi4-agent-tools).
+# On Windows, set command = "hoi4-agent-tools.cmd".
+# hoi4-agent-tools-setup --print-client-config prints this entry with your paths filled in.
 [mcp_servers.hoi4_agent_tools]
-command = "npx"
-args = ["-y", "hoi4-agent-tools@latest"]
+command = "hoi4-agent-tools"
 startup_timeout_sec = 120
 tool_timeout_sec = 600
+env = { HOI4_AGENT_STDIO_IDLE_EXIT_MINUTES = "30" }

package/examples/clients/generic.json

@@ -1,8 +1,8 @@
 {
   "mcpServers": {
     "hoi4_agent_tools": {
-      "command": "npx",
-      "args": ["-y", "hoi4-agent-tools@latest"]
+      "command": "hoi4-agent-tools",
+      "args": []
     }
   }
 }

package/examples/config/config.json

@@ -0,0 +1,7 @@
+{
+  "version": 1,
+  "serverStateRoot": "/var/lib/hoi4-agent-tools-state",
+  "modRoots": ["/projects/hoi4-mods"],
+  "gameRoot": "/games/Hearts of Iron IV",
+  "workspaceStorageRoot": "/var/lib/hoi4-agent-tools"
+}