hoi4-agent-tools 3.9.0 → 4.0.0

package/CHANGELOG.md

@@ -1,5 +1,123 @@
 # Changelog
 
+## Unreleased
+
+## 4.0.0 - 2026-10-10
+
+### Known mistakes
+
+- Add a reviewed, source-cited list of documented script mistakes (`known-mistakes.json`, with a detector for each rule) in place of a mutable learned-rule database. `hoi4.script_validate` in file mode flags seven of them as `KNOWN_MISTAKE_<RULE>` with the symptom and the fix and reports `known_mistakes` in `checksPerformed`: an event without `add_namespace`, an event number that is not a whole number below 100,000, a timer on a triggered-only event, an automatic event that can fire every day, a news event that is not `major` or is `fire_only_once`, a date window shorter than the 20-day trigger check, and a scope prefix on a temporary variable.
+- `hoi4.reference_context` returns the `knownMistakes` of the requested surface, and `hoi4.error_log` adds `knownMistake` (rule id and fix) to a logged message that a rule explains. A rule that no longer applies is kept as `resolved` with the date and reason and is not applied.
+
+### Maps
+
+- `move_state_provinces` redistributes by default: without a `distribution`, or with `"proportional"`, the target receives the moved provinces' share of the source state's manpower, resources and slot buildings (in whole units; levels such as infrastructure keep the higher value). `stateValues: "retain-in-current-states"` keeps the old behaviour.
+- `merge_states`, `create_state` and `split_state` accept `remapReferences` (`refuse` or `override`) to rewrite the scripts that named the state in the same plan.
+- Script references now include `has_full_control_of_state`, `set_state_controller`, `to_state`, `border_state`, `capital` in any script, `set_province_controller`, `reset_province_name`, `goto_province`, `prioritize_location`, `to_province`, `region`, `area`, `prioritize = { ... }` lists and `province = { id = ... }` blocks. Arguments that take exactly one value are never copied or deleted by a remap; they change to the first successor, or stay and are reported as `MAP_REFERENCE_NEEDS_REVIEW`.
+- `MAP_COUNTRY_CAPITAL_NOT_OWNED` is checked only in `history/countries`.
+
+### Tools
+
+- Show at most 8 resource links beside a result (images first); every artifact stays in `structuredContent.artifacts`. A GUI render result was about 33 KB, a third of it links listed twice. Passed validation checks that only report a problem "not detected" are no longer listed.
+
+### Workers
+
+- A warm job worker whose heap still holds more than 40% of its limit after a job and a full collection exits instead of waiting for the next job. Against the real Chaos Redux mod, a GUI render followed by a decision inspection in one worker ran past the 4 GB heap limit and ended with `JOB_WORKER_EXIT`; the next job now starts in a fresh worker. The `JOB_WORKER_EXIT` message now names an out-of-memory exit and the `jobWorkerMaxHeapMiB` setting.
+
+### Documentation
+
+- Add a troubleshooting guide with the error codes and their fixes, the tool audit and the review of smerss/Clausewitz-MCP and cpntodd/HOI4-MCP under `docs/plans`, a worked example that builds and reshapes a world in the map guide, and a section on adding a known mistake to the development guide.
+
+### Breaking changes
+
+- 37 tools become 28, one inspect tool per domain:
+  - `hoi4.probability_inspect` finds weighted logic and evaluates it in the same call, with a fact-free scenario when none is given; `evaluate: false` returns only the inventory. `hoi4.probability_analyze` replaces `hoi4.probability_evaluate`'s siblings `_sweep`, `_simulate`, `_sequence`, `_compare` and `_render`, selected by `analysis`; `hoi4.probability_evaluate` itself is folded into `hoi4.probability_inspect`.
+  - `hoi4.event_compare` and `hoi4.tech_compare` become `mode: compare` of `hoi4.event_inspect` and `hoi4.tech_inspect`.
+  - `hoi4.focus_raster` is folded into `hoi4.focus_render`, which now produces the PNG with decoded icons by default; `png: false` keeps the vector-only output.
+  - `hoi4.map_render` is folded into `hoi4.map_inspect`: a `layer`, `overlays`, `scale`, `tile` or `area` renders that view.
+- Inline results list at most 12 scanned files, mod files first.
+
+- The HTTP server verifies the bearer token before it reads a request body, so an unauthenticated `POST /mcp` receives `401` without its body being parsed; body-dependent scopes such as `hoi4:write` for rewrites are checked again afterwards.
+- Behind a trusted proxy, rate limiting uses the rightmost `X-Forwarded-For` hop that is not a trusted proxy instead of the leftmost, client-supplied entry.
+- A rewrite journal that cannot be recovered no longer stops startup: the server starts, and rewrites of that workspace fail with `TRANSACTION_RECOVERY_REQUIRED` until recovery succeeds. A journal folder without a manifest is skipped.
+- Rolling back a transaction keeps a planned file that was never replaced and has no backup, instead of refusing the whole rollback; a replaced file that changed since still reports `TRANSACTION_STALE`.
+- `tools/list` omits the JSON Schema dialect and the safe-integer bounds that every integer field repeated; field types, ranges and descriptions are unchanged.
+
+### Agent ergonomics
+
+- Accept the argument shorthands agents most often send: an event selector as a plain string or without `kind`, a GUI scenario without `id`, a decision inspection without a scenario, a probability scenario set as a bare list or without ids and `state`, a probability `source` as a string, and `generatedScenarios.maxScenarios`. The full event selector is published in the tool schema. Also a namespace wildcard such as `chaosx.nr14.*`, a selector with `id` for its own field, a trace started from `from`, a GUI inspection without a scenario, a decision by `decisionId`, and a script file check that names the kind and scope its file fixes.
+- Answer invalid arguments with a tool error, code `INVALID_ARGUMENTS`, naming each failing field, what it expected and a working call, instead of a protocol error that clients reduced to "Invalid tool arguments". Error and blocked results carry their blockers in the text content, which is what clients show for an error.
+- Find decisions in files that open the same category block more than once; such decisions were reported as unresolved definitions. Decision inspections list each scenario's eligible, visible and available outcome inline, and a sample of any unresolved definitions.
+- A snippet check without a `kind` is read as the effect or trigger with fewer errors and unresolved commands, and a `limit`, `maxDepth`, `maxNodes` or `maxEdges` above its maximum is lowered to the maximum, instead of rejecting the call.
+- Return the answer inline: probability results rank the strongest candidates per scenario with weight, probability and MTTH, list the facts still missing, and list the largest changes of a comparison.
+- An event ID in a probability `candidatePool` stands for all its options and a `random_list` ID for its entries; a pool alone finds its defining file; a wrong adapter guess, such as a mission named as a decision, switches to the matching adapter.
+- Order inline diagnostics with the mod's own files first, summarise an omitted flood by code, and keep the first diagnostics of an oversized result instead of dropping them all.
+- Name the error kind and a path-free message for unexpected failures, and print the cause of a startup failure such as a configuration file's JSON error.
+- `hoi4.error_log` adds a fix hint per category, groups messages that differ only in names and numbers into `patterns`, and compares each new launch's log with the previous one: `sinceLastLaunch` counts new, persisting and fixed entries and every entry says whether it is new.
+- Every tool description now says what the tool is for, shows a working example call and gives the size of the answer, and every invalid-argument error shows an example for its tool (28 of 28; ten before). Tests send each published example to its tool's schema, and `docs/tools.md` lists the examples with the result sizes.
+
+### Speed
+
+- Keep a job worker warm for `jobWorkerIdleSeconds` (default 180) after a job, so its server's next job reuses the loaded indexes instead of scanning cold. An idle worker holds no execution slot and exits with its server; a failed job never leaves a worker for reuse.
+- Authenticate persistent cache entries over their metadata and payload hash instead of the whole payload, decode a cached parsed document when it is first read instead of for every file at load, and stop copying the payload of an entry that is already stored on every scan. The entry format version is 2, so older entries are rewritten once. Fill the canonical copy used for hashing and for index segments directly, about 40% faster on large segments with identical output.
+- Record where a cold index of a large mod spends its time, and why a background warm-up of the persistent cache does not help it, in ADR 0045. Add `npm run benchmark:cold`, which times `hoi4.mod_index`, an event lint and a decision inventory in a first and a second server process.
+
+### Maps
+
+- Add `create_world` to `hoi4.map_rewrite`: a complete new map from dimensions, a seed, land coverage or outlines and countries, with provinces, terrain, heights, rivers, trees, colour maps, continents, strategic regions with weather, states, country files, history, flags, a bookmark, localisation, positions, supply and `replace_path` entries.
+- Add `regenerate_map_positions` (building, unit-stack and weather positions from geometry), `rebuild_supply` (supply nodes in state capitals joined to each country's hub by railway, or only the states with a supply gap) and `remap_map_references` (rewrite script references to changed states, provinces or regions, copying a reference per successor, and override game files only on request).
+- Add `references: true` to `hoi4.map_inspect`: missing state, province and region references across events, focuses, decisions, helpers, history and AI areas, undeclared state tags, and countries whose capital they do not own.
+- Split states with dated history: dated ownership and effects apply to both parts, and dated victory points and buildings follow their provinces. Merges carry dated blocks without building levels.
+- Keep level buildings (infrastructure, air bases, anti-air, radar, or any building without `shares_slots`) at their level in both parts of a split and at the highest level in a merge, and divide slot buildings and resources in whole units.
+- A merge's distribution policy may be omitted. Generated positions take their height from the heightmap. Province 0's reserved null row no longer reports an unknown terrain or a missing continent.
+- Name transaction diff artifacts safely for files with spaces in their names.
+- Say why a restored rewrite failed: `JOB_REWRITE_RESTORED` now names the error and the first failing check or blocking diagnostic, such as `GUI_REFERENCE_UNRESOLVED`, instead of only that the source was restored.
+- Review a new world over sources that hold no map without a "before" picture, instead of failing with `MAP_RENDER_RASTER_MISSING`.
+- Notice a changed `descriptor.mod` at the next scan of a running server. A new world adds `replace_path` folders to the descriptor, and its post-write check used to see the base-game states it replaces and fail on duplicate state IDs until the server restarted. Jobs, transactions and caches keep the workspace identity they started under.
+- Stop undoing map rewrites that touch a state file. The post-write check scanned only the changed files, so every province a state lists counted as an unresolved reference unless the rewrite also changed `map/definition.csv`; a split, merge or manpower change on a real map was restored with `JOB_REWRITE_RESTORED`. The check now also reads `map/default.map` and the map CSV files.
+
+### Tools
+
+- Add `hoi4.error_log`: read the game's `logs/error.log` from its last launch, grouped by category, with each entry's source file, line and layer, whether that file changed since the log was written, and `scope`, `category` and text filters. Set `gameUserRoot` when the game's user folder is not found automatically.
+- Add `hoi4.mod_index`: summarize a mod's descriptor, definitions by kind, folders and event namespace ranges, or find the next free numbered ID for an event namespace or prefix across every source layer, with the first unused gap.
+- Name the tool and up to five failing fields with their reasons when the 2026-07-28 server rejects tool arguments.
+- Check every supported family of `hoi4.script_validate` file mode from one shared scan, skip localisation from shadowed files in player-text checks, and report only `§` colour codes in news text.
+- Report an overlapping pair whose visibility the GUI scenario does not decide only as `GUI_UNRESOLVED_VISIBILITY_OVERLAP`, without a generic overlap or click-region conflict.
+- Print `startup_timeout_sec = 120` and `tool_timeout_sec = 600` in the Codex registrations from `hoi4-agent-tools-setup --print-client-config`.
+
+### Fixes
+
+- Lex Clausewitz whitespace with a character-code test instead of a regular expression per character, which shortens the cold index of a large mod by roughly a quarter.
+- Update the MCP SDK packages (`@modelcontextprotocol/sdk` 1.32.1, `core`, `server` and `client` 2.3.1, `node` 2.1.1) and `sharp` 0.35.5 past their published high-severity advisories.
+- Keep each file's own diagnostics when an index is rebuilt incrementally after an edit; a rebuild could copy other files' errors and lose real ones.
+- Close a cancelled stdio request so the idle limit still applies, count a request open for twice the idle limit as abandoned, and finish open requests before exiting after the launching process exits.
+- Record an orphaned worker's own deadline as `JOB_DEADLINE_EXCEEDED` instead of leaving the job running.
+- Start one worker launcher per job across HTTP requests and polls, and spawn nothing when the job has finished or a live worker runs it.
+- Re-check a rewrite's journal under the workspace lock before applying it, re-hash the backup it moves aside, and take over a stale workspace lock only through an atomic rename that one process can win.
+- Refuse reads, not only writes, of server storage (`.hoi4-agent`, artifact and cache roots) through workspace paths.
+- Keep artifact listings from removing a folder that a concurrent write is filling.
+- Evict a chunked artifact by the age of its newest member, index first, and protect all its pieces when any of them is protected, so a large result's index never points at evicted pieces.
+- Treat a job store lock held for more than ten minutes as abandoned even when its process ID now belongs to another process, and wait at most two minutes for the lock before failing with `JOB_STORE_BUSY`, so a lock left by a crashed process cannot hang every job.
+- Sweep expired finished job results on first use, and keep the record of a refused task call for five minutes.
+- Bound retained scan snapshots by bytes, remove temporary files from failed heartbeat writes, and drop server records silent for two hours.
+- Release a foreground task's cancellation listener when the task finishes.
+
+### Documentation
+
+- Restructure the README around what the server does, a four-step quick start, a grouped tool table with what each area writes, and safety notes.
+- Add a configuration reference with every key, range, default location and environment variable.
+- Complete the GUI scenario and request field tables, and document the prompt, resources, task-capable tools and setup troubleshooting commands.
+- Add `docs/RELEASING.md`, the checklist for tagging a release, and describe the stdio smoke suites in the development guide: every tool called once with an agent-style argument shape and once with a wrong field, a generated world split, merged and repaired, and the same calls against the installed game and a real mod.
+
+## 3.10.0 - 2026-10-06
+
+- Rebuild a workspace index after an edit from the previous index, parsing and indexing only changed files, and keep the latest scan of each pattern set and each GUI graph scope instead of one per workspace. A repeated GUI preview of a large, actively edited mod took 64 s instead of 244 s.
+- Admit parsed documents to a full cache only on their second miss and only in place of entries never read, so scans larger than the cache no longer serialize and evict every document; build scripted-localisation definitions only for windows that show scripted localisation.
+- List every server process sharing a server state root, with its memory, last client activity and execution limits, in the `hoi4-agent://server/status` resource of local stdio connections.
+- Refuse an `hoi4.event_compare` or `hoi4.tech_compare` call without references before scanning when no earlier revision is cached, instead of after a full scan.
+- Report a `hoi4.tech_render` folder view without `folderId` as a readable argument error instead of a raw validation dump.
+- Ship `proxy-addr` 2.0.8, which fixes IP spoofing through IPv4-mapped IPv6 trust subnets (GHSA-jqcg-44mw-7w3h); the HTTP server sets no `trust proxy`, so earlier releases did not reach the affected code.
+
 ## 3.9.0 - 2026-10-06
 
 - Exit a stdio server whose launching process has exited, and add `stdioIdleExitMinutes` so clients that keep idle per-subagent connections no longer accumulate servers.

package/README.md

@@ -1,160 +1,128 @@
 # HOI4 Agent Tools
 
-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.
+[![npm](https://img.shields.io/npm/v/hoi4-agent-tools)](https://www.npmjs.com/package/hoi4-agent-tools)
+[![Node.js](https://img.shields.io/node/v/hoi4-agent-tools)](https://nodejs.org/)
+[![License](https://img.shields.io/npm/l/hoi4-agent-tools)](LICENSE)
 
-## Get started
+An [MCP](https://modelcontextprotocol.io/) server that lets a coding agent such as Claude Code, Codex or Cursor read, preview, analyse and safely edit a Hearts of Iron IV mod.
+Your agent gets cited answers from the game's own documentation, pictures of focus trees, technology folders, interfaces and maps, and checks that catch load errors before you launch the game.
 
-Install [Node.js](https://nodejs.org/) 22.19+ in the Node 22 line, or Node.js 24, then run:
+[![A large focus tree rendered from mod source](docs/images/comparisons/holy-realm-mcp.png)](docs/images/comparisons/holy-realm-mcp.png)
 
-```bash
-npm install --global hoi4-agent-tools
-hoi4-agent-tools-setup --print-client-config
-```
+## What it does
+
+| Area                   | Ask your agent, for example                                                                                |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------- |
+| Find the rule          | "Find the installed documentation for `save_event_target_as` and show a vanilla usage with file and line." |
+| Check before launch    | "Check `events/my_events.txt` for scope errors, then group the last `error.log` by category."              |
+| See the tree           | "Render this mod's largest focus tree and list focuses with missing icons."                                |
+| Preview the window     | "Preview this scripted GUI at 100% and 125% UI scale and check for clipped text."                          |
+| Read the map           | "Find Brandenburg, list its provinces and neighbours, and show the files a change would touch."            |
+| Reshape the map        | "Split Brandenburg in two and update every event and focus that names it."                                 |
+| Build a new world      | "Create a 2048x1024 world with six countries, then list what still needs hand-made content."               |
+| Follow the events      | "Trace this event's options and follow-up events and point out unresolved calls."                          |
+| Weigh the AI           | "Show the AI weights of event `my_mod.12`'s options, then compare them before and after my change."        |
+| Plan new content       | "Give me the next free event ID in my namespace and summarize what the mod defines."                       |
+| Edit with a safety net | "Add a new branch to this focus tree" — the edit is validated before anything is written.                  |
+
+The server never launches the game.
+Previews and tests are built from source files, so they show what the source says, not what a running campaign did.
+
+## Quick start
+
+1. Install [Node.js](https://nodejs.org/) 22 (22.19 or later) or 24, and keep Hearts of Iron IV installed for vanilla files, artwork and fonts.
+2. Install the server:
+
+   ```bash
+   npm install --global hoi4-agent-tools
+   ```
 
-Add the printed configuration to your MCP client and open your mod as its workspace.
-The install is about 280 MiB, because npm fetches the image library's binaries for every platform to keep each install identical.
-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.
+3. Print the client configuration:
 
-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.
+   ```bash
+   hoi4-agent-tools-setup --print-client-config
+   ```
+
+   Paste the `globalInstall` block into a JSON client such as Claude Code, Claude Desktop or Cursor, or the `codexTomlGlobal` block into Codex's `config.toml`.
+
+4. Open your mod folder as the agent's workspace and try: "Render this mod's largest focus tree."
+
+The [setup guide](docs/setup.md) covers several mods, explicit game paths, local wiki snapshots and troubleshooting with `--discover` and `--diagnose`.
+
+[Watch the Agent Tools demo](https://github.com/klimPaskov/Agentic-HOI4-Modding/releases/latest/download/hoi4_agent_tools_promo.mp4) or use [HOI4 Mod Setup](https://github.com/klimPaskov/HOI4-Mod-Setup/releases/latest) to install and register the verified server for your mod.
 
 ## Examples
 
-[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)
+Each pair shows a capture from the game next to the server's preview of the same source.
+
+| In game                                                                                                                                | Server preview                                                                                                                   |
+| -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| [![Focus tree in game](docs/images/comparisons/fury-ingame.png)](docs/images/comparisons/fury-ingame.png)                              | [![Focus tree preview](docs/images/comparisons/fury-mcp.png)](docs/images/comparisons/fury-mcp.png)                              |
+| [![Infantry technology folder in game](docs/images/comparisons/infantry-ingame.png)](docs/images/comparisons/infantry-ingame.png)      | [![Infantry technology folder preview](docs/images/comparisons/infantry-mcp.png)](docs/images/comparisons/infantry-mcp.png)      |
+| [![Video options in game](docs/images/comparisons/gui/options-video-ingame.png)](docs/images/comparisons/gui/options-video-ingame.png) | [![Video options preview](docs/images/comparisons/gui/options-video-mcp.png)](docs/images/comparisons/gui/options-video-mcp.png) |
+
+In focus previews, dotted lines mark alternative prerequisites: any one of them unlocks the focus.
+The focus screen in the game has its own framing, labels and icons, and the video options preview has no observed gamma value.
+More comparisons, with their source revisions and fidelity notes, are in the [focus and technology gallery](https://github.com/klimPaskov/hoi4-agent-tools/blob/main/docs/visual-comparisons.md), the [interface gallery](https://github.com/klimPaskov/hoi4-agent-tools/blob/main/docs/gui-comparisons.md) and the [examples guide](docs/examples.md), which also shows map and event renders.
+
+## Tools
+
+The default server has 28 tools.
+Agents pick them from ordinary language, so you rarely need their names.
+
+| Area                        | Tools                                                                                                                   | Writes                  |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------- |
+| References and source       | `reference_context`, `reference_search`, `reference_read`, `source_lookup`, `script_validate`, `error_log`, `mod_index` | —                       |
+| Focus trees                 | `focus_inspect`, `focus_render`, `focus_rewrite`                                                                        | review files; mod files |
+| Scripted GUIs               | `gui_inspect`, `gui_render`, `gui_rewrite`                                                                              | review files; mod files |
+| Maps                        | `map_inspect`, `map_rewrite`                                                                                            | review files; mod files |
+| Events                      | `event_inspect`, `event_render`                                                                                         | —                       |
+| Technology and doctrines    | `tech_inspect`, `tech_render`                                                                                           | —                       |
+| AI weights and timing       | `probability_inspect`, `probability_analyze`                                                                            | —                       |
+| Decisions, impact and tests | `impact_inspect`, `decision_inspect`, `mechanic_test`, `package_check`, `scenario_test`                                 | —                       |
+| Background jobs             | `job_inspect`, `job_cancel`                                                                                             | job state               |
+
+Every name starts with `hoi4.`.
+"Review files" are images and reports in the server's own storage; only the three `*_rewrite` tools change mod files.
+The [tool reference](docs/tools.md) gives each tool's purpose, prompts, resources and long-running behaviour.
+
+## Safety and limits
+
+- The server reads the mod, its dependencies, the installed game, local reference folders and the game's error log.
+- Inspection and rendering never change mod files.
+  The focus, GUI and map rewrite tools validate a proposed edit before writing it and write it as a journaled transaction, so an interrupted write is restored rather than left half-applied.
+- Large renders and reports are stored as linked files, and documentation is returned as cited sections rather than whole manuals.
+- The server does not launch or control the game.
+  Previews and source tests cannot prove live clicks, AI choices or engine timing; a source score alone does not establish an AI click probability.
+- Your repository instructions and review process still apply.
+
+## Configuration
+
+Started inside a mod folder, the server needs no configuration file.
+`hoi4-agent-tools-setup --init` writes one when you work on several mods or the game is not found automatically.
+For remote or shared use, `hoi4-agent-tools-http` serves the same tools over HTTP with tokens or OAuth.
+See the [configuration reference](docs/configuration.md) and the [HTTP guide](docs/http.md).
+
+## Documentation
+
+- [Setup](docs/setup.md) and [configuration](docs/configuration.md)
+- [Examples](docs/examples.md) and [tool reference](docs/tools.md)
+- Guides: [local references](docs/reference.md), [focus trees](docs/focus.md), [scripted GUIs](docs/gui.md), [maps](docs/map.md), [events](docs/events.md), [technology](docs/technology.md), [AI weights and timing](docs/probability.md), [decisions and impact](docs/analysis.md), [mechanic and package tests](docs/mechanics.md)
+- [Background jobs](docs/jobs.md) and [HTTP](docs/http.md)
+- [Development](docs/development.md), [changelog](CHANGELOG.md) and [security policy](SECURITY.md)
+- [Documentation index](docs/README.md)
+
+## Development
+
+```bash
+npm ci
+npm run check
+```
 
-### Focus trees and alternative prerequisites
+See the [contributing guide](https://github.com/klimPaskov/hoi4-agent-tools/blob/main/CONTRIBUTING.md) and the [development guide](docs/development.md).
 
-| Focus tree  | Supplied in-game capture                                                                                                    | MCP source preview                                                                                                    |
-| ----------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| 52 focuses  | [![Medium focus tree in game](docs/images/comparisons/fury-ingame.png)](docs/images/comparisons/fury-ingame.png)            | [![Medium focus tree preview](docs/images/comparisons/fury-mcp.png)](docs/images/comparisons/fury-mcp.png)            |
-| 111 focuses | [![Large focus tree in game](docs/images/comparisons/holy-realm-ingame.png)](docs/images/comparisons/holy-realm-ingame.png) | [![Large focus tree preview](docs/images/comparisons/holy-realm-mcp.png)](docs/images/comparisons/holy-realm-mcp.png) |
-| 124 focuses | [![Branching focus tree in game](docs/images/comparisons/utopia-ingame.png)](docs/images/comparisons/utopia-ingame.png)     | [![Branching focus tree preview](docs/images/comparisons/utopia-mcp.png)](docs/images/comparisons/utopia-mcp.png)     |
+## License
 
-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                                                                                                                           |
-| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| Vanilla infantry | [![Infantry folder 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)                          |
-| Mod wide cards   | [![Mod technology folder in game](docs/images/comparisons/chemical-recent-ingame.png)](docs/images/comparisons/chemical-recent-ingame.png) | [![Mod technology folder preview](docs/images/comparisons/chemical-historical-mcp.png)](docs/images/comparisons/chemical-historical-mcp.png) |
-
-The mod folder preview uses the source revision recorded with its screenshot and includes wide equipment cards.
-Armored-car artwork that installed DLC folders provide appears in the infantry preview.
-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.
-
-### Scripted interfaces
-
-> Preview an interface with its game assets and fonts. Check states, text clipping and clickable areas at 100% and 125% UI scale.
-
-| Interface              | Supplied in-game capture                                                                                                                  | MCP source preview                                                                                                                  |
-| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| Vanilla 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)          |
-| Vanilla priority panel | [![Priority panel in game](docs/images/comparisons/gui/skoda-priority-ingame.png)](docs/images/comparisons/gui/skoda-priority-ingame.png) | [![Priority panel preview](docs/images/comparisons/gui/skoda-priority-mcp.png)](docs/images/comparisons/gui/skoda-priority-mcp.png) |
-| Mod management window  | [![Management window in game](docs/images/comparisons/gui/tag-manager-ingame.png)](docs/images/comparisons/gui/tag-manager-ingame.png)    | [![Management window preview](docs/images/comparisons/gui/tag-manager-mcp.png)](docs/images/comparisons/gui/tag-manager-mcp.png)    |
-
-The management window capture comes from an older layout.
-The video options preview has no observed gamma value, and the priority panel's capture frames its background differently.
-
-| Mod event log                                                                                                        | Mod status panel                                                                                                                        | Mod status panel, second tab                                                                                                            |
-| -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| [![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) |
-
-| 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) |
-
-The event log, status panel, 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                                                                                                                      | Mod 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.
-
-| 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.                                |
-
-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.
+Apache-2.0; see [LICENSE](LICENSE) and the [third-party notices](docs/third-party-notices.md).
+Hearts of Iron IV artwork belongs to Paradox Interactive; this project is unaffiliated with Paradox Interactive.
+The in-game captures were supplied for these comparisons.

package/dist/bin/http.js

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 import { canonicalJson } from '../hoi4_agent_tools/core/canonical.js';
+import { ServerRegistry } from '../hoi4_agent_tools/core/server-registry.js';
 import { createMcpServer } from '../hoi4_agent_tools/mcp/server/create.js';
 import { startHttpServer } from '../hoi4_agent_tools/mcp/transports/http.js';
 import { createEngine } from '../hoi4_agent_tools/runtime.js';
 async function main() {
     const engine = await createEngine();
     const handle = await startHttpServer(engine, engine.resolver.config(), createMcpServer);
+    new ServerRegistry(engine.resolver, 'http').start();
     const shutdown = async () => {
         await handle.close();
         process.exit(0);
@@ -21,6 +23,16 @@ main().catch((error) => {
             ? String(error.code)
             : 'INTERNAL_ERROR',
         message: error instanceof Error ? error.message : String(error),
+        // Startup output goes to the operator's own log; the cause (such as the JSON parse
+        // position in a configuration file) is what makes the failure fixable.
+        ...(typeof error === 'object' &&
+            error !== null &&
+            'details' in error &&
+            typeof error.details === 'object' &&
+            error.details !== null &&
+            Object.keys(error.details).length > 0
+            ? { details: error.details }
+            : {}),
     })}\n`);
     process.exitCode = 1;
 });

package/dist/bin/setup.js

@@ -226,8 +226,9 @@ function printClientConfig(configPath) {
         ...(useDefaultConfiguration ? {} : { env: { HOI4_AGENT_CONFIG: absolute } }),
     };
     // Codex keeps a server per subagent connected after the subagent finishes, so its servers
-    // exit after half an hour without traffic instead of accumulating.
-    const codexEnv = `\nenv = { ${useDefaultConfiguration ? '' : `HOI4_AGENT_CONFIG = ${JSON.stringify(absolute)}, `}HOI4_AGENT_STDIO_IDLE_EXIT_MINUTES = "30" }`;
+    // exit after half an hour without traffic instead of accumulating. The first scan of a large
+    // mod and long renders need more than Codex's default startup and tool-call timeouts.
+    const codexEnv = `\nstartup_timeout_sec = 120\ntool_timeout_sec = 600\nenv = { ${useDefaultConfiguration ? '' : `HOI4_AGENT_CONFIG = ${JSON.stringify(absolute)}, `}HOI4_AGENT_STDIO_IDLE_EXIT_MINUTES = "30" }`;
     const npxToml = `[mcp_servers.hoi4_agent_tools]\ncommand = "${command}"\nargs = ["-y", "hoi4-agent-tools@${PACKAGE_VERSION}"]${codexEnv}`;
     const globalToml = `[mcp_servers.hoi4_agent_tools]\ncommand = "${installedCommand}"${codexEnv}`;
     process.stdout.write(`${JSON.stringify({

package/dist/bin/stdio.js

@@ -2,6 +2,7 @@
 import { canonicalJson } from '../hoi4_agent_tools/core/canonical.js';
 import { StdioFrameLimitError, StdioInvalidMessageError, StdioInvalidUtf8Error, } from '../hoi4_agent_tools/mcp/transports/bounded-stdio.js';
 import { serveNegotiatedStdio } from '../hoi4_agent_tools/mcp/transports/negotiated-stdio.js';
+import { ServerRegistry } from '../hoi4_agent_tools/core/server-registry.js';
 import { StdioLifetime } from '../hoi4_agent_tools/mcp/transports/stdio-lifetime.js';
 import { createEngine } from '../hoi4_agent_tools/runtime.js';
 /**
@@ -52,6 +53,16 @@ async function main() {
                 level: 'error',
                 event: 'transport_startup_failed',
                 message: error instanceof Error ? error.message : String(error),
+                // Startup output goes to the operator's own log; the cause (such as the JSON parse
+                // position in a configuration file) is what makes the failure fixable.
+                ...(typeof error === 'object' &&
+                    error !== null &&
+                    'details' in error &&
+                    typeof error.details === 'object' &&
+                    error.details !== null &&
+                    Object.keys(error.details).length > 0
+                    ? { details: error.details }
+                    : {}),
             })}\n`);
         },
         ...(chaosxTools === undefined
@@ -63,6 +74,7 @@ async function main() {
     });
     closeTransport = () => transport.close();
     lifetime.start();
+    new ServerRegistry(engine.resolver, 'stdio', () => lifetime.lastActivity()).start();
 }
 main().catch((error) => {
     process.stderr.write(`${canonicalJson({

package/dist/hoi4_agent_tools/core/artifacts.js

@@ -201,6 +201,14 @@ const artifactTemporaryPrefix = '.artifact-tmp-';
 const ownedArtifactContent = Symbol('ownedArtifactContent');
 const precomputedArtifactSha256 = Symbol('precomputedArtifactSha256');
 export const chunkedArtifactIndexMimeType = 'application/json';
+/** The chunked logical artifact a chunk or index manifest belongs to, and its role in it. */
+function chunkMembership(manifest) {
+    const chunked = manifest.provenance.metadata?.chunkedArtifact;
+    if (typeof chunked?.originalSha256 !== 'string' ||
+        (chunked.role !== 'chunk' && chunked.role !== 'index'))
+        return undefined;
+    return { group: chunked.originalSha256, role: chunked.role };
+}
 function isValidArtifactName(name) {
     return (safeNamePattern.test(name) &&
         isPortablePathSegment(name) &&
@@ -342,7 +350,12 @@ async function withArtifactQueue(root, action, signal) {
         });
     }
 }
-async function artifactUsage(root, signal) {
+/**
+ * Measure artifact storage. With `cleanup`, also remove aged temporary files and empty
+ * folders; only the serialized write path may do that, since a listing running beside a
+ * write could remove the folder a new artifact is about to be written into.
+ */
+async function artifactUsage(root, signal, cleanup = false) {
     let bytes = 0;
     let entries = 0;
     const canonicalRoot = await containedGeneratedPath(root);
@@ -388,7 +401,7 @@ async function artifactUsage(root, signal) {
                     const metadata = await lstat(temporary);
                     if (metadata.isSymbolicLink())
                         throw new ServiceError('ARTIFACT_STORAGE_UNSAFE', 'Artifact storage contains a symbolic link or junction');
-                    if (Date.now() - metadata.mtimeMs >= artifactDebrisMinimumAgeMs)
+                    if (cleanup && Date.now() - metadata.mtimeMs >= artifactDebrisMinimumAgeMs)
                         await unlink(temporary);
                 }
                 catch (error) {
@@ -420,7 +433,7 @@ async function artifactUsage(root, signal) {
                 }
             }
         }
-        if (directory !== canonicalRoot) {
+        if (cleanup && directory !== canonicalRoot) {
             try {
                 await rmdir(directory);
             }
@@ -883,8 +896,27 @@ export class ArtifactStore {
             }
         };
         await reclaimDebris(await containedGeneratedPath(workspace.artifactRoot));
+        // A chunked artifact's pieces are written before its index, so they are always older. Age
+        // a group by its newest member and evict its index first, so readers never follow an index
+        // to evicted pieces, and protect the whole group when any member is protected.
+        const groupAge = new Map();
+        const protectedGroups = new Set();
+        for (const entry of retained) {
+            const membership = chunkMembership(entry.manifest);
+            if (membership === undefined)
+                continue;
+            groupAge.set(membership.group, Math.max(groupAge.get(membership.group) ?? 0, entry.modifiedAt));
+            if (protectedManifests.has(entry.manifestPath) || protectedTargets.has(entry.targetPath))
+                protectedGroups.add(membership.group);
+        }
+        const evictionAge = (entry) => {
+            const membership = chunkMembership(entry.manifest);
+            return membership === undefined ? entry.modifiedAt : groupAge.get(membership.group);
+        };
+        const indexFirst = (entry) => chunkMembership(entry.manifest)?.role === 'chunk' ? 1 : 0;
         retained.sort((left, right) => Number(right.staleIdentity) - Number(left.staleIdentity) ||
-            left.modifiedAt - right.modifiedAt ||
+            evictionAge(left) - evictionAge(right) ||
+            indexFirst(left) - indexFirst(right) ||
             compareCodeUnits(left.manifestPath, right.manifestPath));
         const current = { ...usage };
         for (const candidate of retained) {
@@ -893,6 +925,9 @@ export class ArtifactStore {
                 break;
             if (protectedManifests.has(candidate.manifestPath))
                 continue;
+            const membership = chunkMembership(candidate.manifest);
+            if (membership !== undefined && protectedGroups.has(membership.group))
+                continue;
             try {
                 await unlink(candidate.manifestPath);
             }
@@ -1366,7 +1401,7 @@ export class ArtifactStore {
             if (!Number.isSafeInteger(additionalBytes)) {
                 throw new ServiceError('ARTIFACT_STORAGE_LIMIT', 'Artifact batch size is unsafe');
             }
-            const usage = await artifactUsage(workspace.artifactRoot, signal);
+            const usage = await artifactUsage(workspace.artifactRoot, signal, true);
             const additionalEntries = [...uniqueManifests.values()].filter((artifact) => !artifact.exists).length;
             await this.pruneForAdmission(workspace, usage, additionalBytes, additionalEntries, new Set(uniqueManifests.keys()), new Set(uniqueTargets.keys()), signal);
             const createdTargets = [];