hoi4-agent-tools 3.10.0 → 4.0.1

package/CHANGELOG.md

@@ -1,5 +1,136 @@
 # Changelog
 
+## Unreleased
+
+## 4.0.1 - 2026-10-12
+
+- Clean temporary test fixtures after each test, suite teardown and normal process exit. Reject fixture truncation above a 256 MiB aggregate disk budget before Windows allocates the file.
+- Recover stale reference-source and random-name event-evaluation scratch on startup after three hours, with local process leases, lock and canonical-path checks. Evict dead owners oldest first under a 256 MiB scratch cap; preserve live owners and dated benchmark evidence.
+- Document the leak's test-fixture origin. MCP reference lookup already reads configured sources directly and uses the shared persistent analysis cache; it does not copy a source tree per call or process.
+- Describe modding tasks in plain language across the README, guides, package metadata and MCP tool descriptions.
+
+### GUI render
+
+- Decode uncompressed 16-bit RGB DDS portraits, including the 5:5:5 format used by vanilla leaders; truncated pixel data remains unsupported.
+- Preserve declared font colours when a same-name bitmap atlas is loaded, including the dark super-event description font. Atlas metadata no longer outranks a named font declaration, and source links retain that declaration.
+- `hoi4.gui_render` and `hoi4.gui_inspect` model the engine-controlled branches of `countrypoliticsview` instead of drawing all of them: no faction, faction leader, faction member and balance of power are chosen from the scenario country (`tag`, `ideology`, `faction`, `balanceOfPower`, or its `history/countries` facts at the scenario date), and `pol_faction_icon` follows the ruling ideology instead of its static frame. Explicit scenario visibility, values and selected frames still win.
+- GUI text keys are matched without regard to case, so a window that spells `buttontext` in lower case (the vanilla trade window) shows its localised label instead of the key.
+- Element visibility honours `show` as well as `visible`, `hide` and `hidden`, and scenario `name.visible` values may be yes/no words or 1/0 as well as booleans.
+
+### Job workers
+
+- Uncaught worker failures log only a bounded diagnostic code; exception messages, stacks and thrown values are excluded to protect source text and credentials.
+- A worker that stops without a result is now reported by its real cause. The host keeps each worker's exit code, signal and last standard error and fails the job with `JOB_WORKER_EXIT` naming a V8 heap limit (with its size), a native out-of-memory, a native crash, an external termination, a stop by the server's own deadline, or an uncaught job error with its error code. Earlier releases discarded this and always suggested that memory ran out. Logs of workers that ended unexpectedly are kept, newest ten, in `job-workers/logs` under the server state root.
+- Workers start with a V8 heap ceiling of a quarter of physical memory, between 2,048 and 8,192 MiB, when `jobWorkerMaxHeapMiB` is not set. Node's own default tops out near 4.5 GB, which a large GUI render on a big mod can approach.
+- `hoi4.gui_render` rasterizes its derived variants, the comparison renders and the galleries one at a time instead of together, which lowers the peak native memory of a render.
+
+## 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.

package/README.md

@@ -1,160 +1,104 @@
 # 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.
+<!-- TODO-VIDEO-LINK: replace with the promo video URL -->
 
-## Get started
+[![Watch the HOI4 Agent Tools demo](docs/images/agent-tools-demo-thumbnail.png)](https://www.youtube.com/@ChaosRedux)
 
-Install [Node.js](https://nodejs.org/) 22.19+ in the Node 22 line, or Node.js 24, then run:
+[![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)
+[![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/rAXesGcT2t)
+[![YouTube](https://img.shields.io/badge/YouTube-Chaos%20Redux-ff0000?logo=youtube&logoColor=white)](https://www.youtube.com/@ChaosRedux)
+[![Ko-fi](https://img.shields.io/badge/Ko--fi-Support%20the%20Project-ff5e5b?logo=kofi&logoColor=white)](https://ko-fi.com/klimpaskov)
+[![Download](https://img.shields.io/github/v/release/klimPaskov/hoi4-agent-tools?label=Release&logo=github&color=2ea44f)](https://github.com/klimPaskov/hoi4-agent-tools/releases/latest)
+[![Issues](https://img.shields.io/badge/Bugs%20%26%20Ideas-Issues-24292f?logo=github&logoColor=white)](https://github.com/klimPaskov/hoi4-agent-tools/issues)
 
-```bash
-npm install --global hoi4-agent-tools
-hoi4-agent-tools-setup --print-client-config
-```
+An [MCP](https://modelcontextprotocol.io/) server that helps coding agents build and edit Hearts of Iron IV mods.
+Make focus trees, events and decisions. Edit maps and generate a new world. Preview windows, trees and maps, find the right rule in the docs, fix broken script and balance AI choices.
+
+## What it does
+
+Your agent can build and edit focus trees, events, decisions and maps, and generate a new world.
+It previews focus trees, technology folders, windows and maps, finds the right rule in the game's documentation, fixes broken script and tunes AI choices.
+You describe what you want; the agent picks the right tools.
+
+## 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 tell it what you want to build or fix.
+
+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 connect the server for your mod.
+Part of the HOI4 modding toolkit with [Agentic HOI4 Modding](https://github.com/klimPaskov/Agentic-HOI4-Modding) (skills and instructions for your agent) and [HOI4 Live Tools](https://github.com/klimPaskov/HOI4-Live-Tools) (testing in the running game).
 
 ## 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)
+[![A large focus tree rendered from mod source](docs/images/comparisons/holy-realm-mcp.png)](docs/images/comparisons/holy-realm-mcp.png)
+
+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) |
+
+See more in the [examples gallery](docs/examples.md).
+
+## Tools
+
+The server gives your agent previews, documentation, script analysis and editing tools.
+The agent combines them with its file editor to build events and decisions, repair scripts and adjust AI weights.
+The [tool reference](docs/tools.md) lists exact names, arguments and results for integrations.
+
+## FAQ
+
+**Where do edits go?** Changes are written to your mod folder; use Git to review or undo them.
+
+**Does it run the game?** No. Previews come from mod source; test gameplay in HOI4 to see live clicks, AI choices and timing.
+
+## 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

@@ -23,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

@@ -53,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

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 = [];

package/dist/hoi4_agent_tools/core/canonical.js

@@ -16,10 +16,24 @@ export function canonicalize(value) {
         return value.map(canonicalize);
     if (typeof value === 'object') {
         const object = value;
-        return Object.fromEntries(Object.keys(object)
-            .sort(compareCodeUnits)
-            .filter((key) => object[key] !== undefined)
-            .map((key) => [key, canonicalize(object[key])]));
+        // Filling the copy directly avoids an entry array per member; a plain object lists integer
+        // keys first and the rest in insertion (here code unit) order, the same as before.
+        const copy = {};
+        for (const key of Object.keys(object).sort(compareCodeUnits)) {
+            const member = object[key];
+            if (member === undefined)
+                continue;
+            if (key === '__proto__')
+                Object.defineProperty(copy, key, {
+                    value: canonicalize(member),
+                    enumerable: true,
+                    writable: true,
+                    configurable: true,
+                });
+            else
+                copy[key] = canonicalize(member);
+        }
+        return copy;
     }
     throw new TypeError(`Canonical JSON cannot contain ${typeof value}`);
 }

package/dist/hoi4_agent_tools/core/condition-evaluator.js

@@ -176,6 +176,24 @@ function evaluateAssignmentCore(assignment, scenario, candidate, definitions, he
         const malformed = malformedBlock(assignment.value, candidate);
         if (malformed !== undefined)
             return malformed;
+        if (key === 'has_country_flag' || key === 'has_global_flag' || key === 'has_state_flag') {
+            // The block form tests a flag's stored value. A scenario declares that value as a number
+            // under `flag.<name>` (or `global_flag.<name>` for global flags).
+            const flag = firstScalar(assignment.value, 'flag')?.value;
+            const expected = firstScalar(assignment.value, 'value')?.value;
+            if (flag !== undefined) {
+                const names = key === 'has_global_flag' ? [`global_flag.${flag}`, `flag.${flag}`] : [`flag.${flag}`];
+                for (const name of names) {
+                    const declared = scopeStateValue(scenario, name, scopeContext);
+                    if (typeof declared === 'number' && expected !== undefined)
+                        return { state: declared === Number(expected) ? 'true' : 'false', unresolved: [] };
+                    if (typeof declared === 'boolean' && expected === undefined)
+                        return { state: declared ? 'true' : 'false', unresolved: [] };
+                }
+                if (expected !== undefined)
+                    return unresolved(assignment, candidate, `Scenario does not declare the value of flag ${flag}`, `flag.${flag}`);
+            }
+        }
         if (key === 'AND' ||
             key === 'hidden_trigger' ||
             key === 'custom_trigger_tooltip' ||