hoi4-agent-tools 4.0.0 → 4.0.1

package/dist/hoi4_agent_tools/mcp/tools/gui.js

@@ -71,24 +71,24 @@ const artifactProducing = {
 export const guiTaskTools = [
     {
         name: 'hoi4.gui_inspect',
-        title: 'Inspect scripted GUI',
-        description: 'Inspect a scripted GUI window with its linked .gui, .gfx, scripted-GUI, localisation and font sources, and layout diagnostics. Example: {"windowName":"my_window"}. Returns element counts and fidelity inline; the full scene is a linked resource.',
+        title: 'Inspect a window',
+        description: 'Find the elements, assets and script behind a window, including layout problems, localisation and fonts. Example: {"windowName":"my_window"}. Returns element counts and fidelity inline; the full scene is a linked resource.',
         inputSchema: guiInspectRequestSchema,
         outputSchema: guiScanOutputSchema,
         annotations: artifactProducing,
     },
     {
         name: 'hoi4.gui_render',
-        title: 'Render scripted GUI artifacts',
-        description: 'Render a GUI window under a scenario at several states and resolutions, with click regions, hierarchy and a diagnostics report. Example: {"windowName":"my_window","scenario":{"id":"normal","flags":{"my_flag":true}}}. Returns a gallery of about 25 linked artifacts; undecided visibility stays marked unresolved.',
+        title: 'Preview a window',
+        description: 'Preview a window at different resolutions and states. Shows control regions, element hierarchy and layout problems; unknown visibility stays unresolved. Example: {"windowName":"my_window","scenario":{"id":"normal","flags":{"my_flag":true}}}. Images and reports are linked resources.',
         inputSchema: guiRenderRequestSchema,
         outputSchema: guiRenderOutputSchema,
         annotations: artifactProducing,
     },
     {
         name: 'hoi4.gui_rewrite',
-        title: 'Create or clean up scripted GUI',
-        description: 'Apply one validated GUI change as complete source, structured helpers or exact patches, plus extra text files (additionalFiles); binary art must already be in the mod. Example: {"mode":"helpers","relativePath":"interface/my_window.gui","windowName":"my_window","scenario":{"id":"normal"},"helper":{...}}. Writes atomically; returns changed files and a rollback-able transaction.',
+        title: 'Create or edit a window',
+        description: 'Create or edit a window using complete source, structured helpers or exact patches. Include related text files with additionalFiles; binary art must already be in the mod. Example: {"mode":"helpers","relativePath":"interface/my_window.gui","windowName":"my_window","scenario":{"id":"normal"},"helper":{...}}. Returns the changed files.',
         inputSchema: guiRewriteRequestSchema,
         outputSchema: guiPlanOutputSchema,
         annotations: {

package/dist/hoi4_agent_tools/mcp/tools/job.js

@@ -4,8 +4,8 @@ import { errorResult } from '../../core/operation-result.js';
 export const jobControlTools = [
     {
         name: 'hoi4.job_inspect',
-        title: 'Inspect persistent job',
-        description: 'Inspect a background operation by jobId (from a native task id): status while it runs, the original tool result once it completed. Example: {"jobId":"job_<64 hex characters>"}. Returns bounded status evidence.',
+        title: 'Check a background task',
+        description: 'Check progress on a background task or retrieve its completed result. Pass jobId from the task handle. Example: {"jobId":"job_<64 hex characters>"}. Returns task status or the completed result.',
         inputSchema: jobReferenceSchema,
         annotations: {
             readOnlyHint: true,
@@ -16,8 +16,8 @@ export const jobControlTools = [
     },
     {
         name: 'hoi4.job_cancel',
-        title: 'Cancel persistent job',
-        description: 'Durably request cancellation of a background operation by jobId. A completed result stays completed. Example: {"jobId":"job_<64 hex characters>"}.',
+        title: 'Stop a background task',
+        description: 'Stop a background task by jobId. A result that has already completed stays available. Example: {"jobId":"job_<64 hex characters>"}.',
         inputSchema: jobReferenceSchema,
         outputSchema: jobStatusOutputSchema,
         annotations: {

package/dist/hoi4_agent_tools/mcp/tools/map.js

@@ -127,16 +127,16 @@ const artifactProducing = {
 export const mapTaskTools = [
     {
         name: 'hoi4.map_inspect',
-        title: 'Inspect HOI4 map',
-        description: 'Validate the map with a searchable navigator, look up provinces, states, regions, names or coordinates (lookupOnly for speed), render a layer, tile or area, or check script references (references:true). Example: {"query":"Brandenburg","lookupOnly":true}. Returns counts and matches inline; PNG, HTML and the catalog are artifacts.',
+        title: 'Explore and preview the map',
+        description: 'Explore and preview the map. Find provinces, states and regions by name, ID or coordinates, inspect map problems and script references, or render a layer, tile or area. Use lookupOnly for a quick lookup and references:true for script references. Example: {"query":"Brandenburg","lookupOnly":true}. Returns counts and matches inline; PNG, HTML and the catalog are artifacts.',
         inputSchema: mapInspectRequestSchema,
         outputSchema: mapInspectOutputSchema,
         annotations: artifactProducing,
     },
     {
         name: 'hoi4.map_rewrite',
-        title: 'Create or clean up map content',
-        description: 'Create a world, or create, split, merge, move and renumber states and provinces, regenerate positions and supply, and remap script references. Example: {"operations":[{"id":"s1","kind":"create_state","provinceIds":[120,121],"displayName":"New State"}]}. All or nothing: a failed operation leaves no partial files. Returns changed IDs, semantic diff and a render.',
+        title: 'Build a world or edit the map',
+        description: 'Build a world, split or merge states, move or renumber provinces, and update script references. Regenerate building positions and supply networks. Example: {"operations":[{"id":"s1","kind":"create_state","provinceIds":[120,121],"displayName":"New State"}]}. Returns changed IDs, a summary of edits and a render.',
         inputSchema: mapRewriteRequestSchema,
         outputSchema: mapPlanOutputSchema,
         annotations: {

package/dist/hoi4_agent_tools/mcp/tools/probability.js

@@ -114,16 +114,16 @@ const readOnly = {
 export const probabilityTaskTools = [
     {
         name: 'hoi4.probability_inspect',
-        title: 'Inspect and evaluate AI weights and MTTH',
-        description: 'Find weighted logic (ai_will_do, ai_chance, MTTH, random_list, strategy factors) by path, ID or candidate IDs and evaluate it under declared scenarios, or none: weights, probabilities and the facts still missing. Example: {"candidatePool":["my_decision"],"scenarioSet":[{"actor":"GER","state":{"has_war":false}}]}. Ranks the strongest candidates inline.',
+        title: 'Explain AI choices and event timing',
+        description: 'Explain why the AI favours an option, decision, focus or technology. Find ai_will_do, ai_chance, MTTH, random_list or strategy factors by path, ID or candidate IDs and evaluate them under declared scenarios. Show weights, supported probabilities and missing facts. Example: {"candidatePool":["my_decision"],"scenarioSet":[{"actor":"GER","state":{"has_war":false}}]}. Ranks the strongest candidates inline.',
         inputSchema: probabilityInspectRequestSchema,
         outputSchema: inspectOutput,
         annotations: readOnly,
     },
     {
         name: 'hoi4.probability_analyze',
-        title: 'Compare, sweep, simulate, or sequence weighted logic',
-        description: 'Deeper weighted analysis: compare before and after source under the same scenarios, sweep input ranges for breakpoints and rank reversals, simulate uncertain inputs, run a declared pool over time, or render a retained analysis. Example: {"analysis":"sweep","source":"common/decisions/my_decisions.txt","candidatePool":["my_decision"],"scenarioSet":[{"actor":"GER","state":{"variable.pressure":10}}],"sweep":{"paths":["variable.pressure"],"steps":10}}.',
+        title: 'Compare AI choices and random outcomes',
+        description: 'Compare AI weights before and after an edit, find where a choice changes, or explore uncertain inputs and choices over time. Select compare, sweep, simulate, sequence or render with analysis. Example: {"analysis":"sweep","source":"common/decisions/my_decisions.txt","candidatePool":["my_decision"],"scenarioSet":[{"actor":"GER","state":{"variable.pressure":10}}],"sweep":{"paths":["variable.pressure"],"steps":10}}.',
         inputSchema: probabilityAnalyzeRequestSchema,
         outputSchema: analysisOutput,
         annotations: readOnly,

package/dist/hoi4_agent_tools/mcp/tools/reference.js

@@ -12,32 +12,32 @@ const readOnly = {
 export const referenceTools = [
     {
         name: 'hoi4.reference_search',
-        title: 'Search local HOI4 references',
-        description: 'Search the offline wiki and installed game documentation by words or script names; each hit gives its file, lines, revision and answering line. Example: {"query":"add_timed_idea"}. Returns 6 hits by default (up to 12); read one with hoi4.reference_read using its id and revision.',
+        title: 'Find a modding rule',
+        description: 'Find the right modding rule in the offline wiki and installed game docs using ordinary words or script names. Each hit includes its file, lines, revision and answering line. Example: {"query":"add_timed_idea"}. Returns 6 hits by default (up to 12); read one with hoi4.reference_read using its id and revision.',
         inputSchema: referenceSearchRequestSchema,
         outputSchema: strictOperationResultSchema(referenceSearchDataSchema),
         annotations: readOnly,
     },
     {
         name: 'hoi4.reference_read',
-        title: 'Read cited HOI4 reference section',
-        description: 'Read one cited documentation section: pass the id and revision of a reference_search or reference_context hit. Example: {"id":"<hit id>","revision":"<hit revision>"}. Returns at most 80 lines (40 by default) and 8,000 bytes, with a line to continue from.',
+        title: 'Read a modding rule',
+        description: 'Read a documentation section returned by reference_search or reference_context. Pass its id and revision. Example: {"id":"<hit id>","revision":"<hit revision>"}. Returns at most 80 lines (40 by default) and 8,000 bytes, with a line to continue from.',
         inputSchema: referenceReadRequestSchema,
         outputSchema: strictOperationResultSchema(referenceReadDataSchema),
         annotations: readOnly,
     },
     {
         name: 'hoi4.reference_context',
-        title: 'Get HOI4 task references',
-        description: 'Cited wiki and installed-documentation sections for one modding surface (event, decision, idea, focus, technology, gui, map, localisation, ai, general). Example: {"surface":"event","question":"fire an event after a delay"}. Returns up to 16 short sections; read more with hoi4.reference_read.',
+        title: 'Find docs for a modding task',
+        description: 'Find documentation for the content you are building: events, decisions, ideas, focuses, technology, GUI, maps, localisation or AI. Example: {"surface":"event","question":"fire an event after a delay"}. Returns up to 16 short sections; read more with hoi4.reference_read.',
         inputSchema: referenceContextRequestSchema,
         outputSchema: strictOperationResultSchema(referenceContextDataSchema),
         annotations: readOnly,
     },
     {
         name: 'hoi4.source_lookup',
-        title: 'Look up HOI4 source symbol',
-        description: 'Find where a script symbol is defined across game, DLC and mod, and where it is used; or pass path and line for the definition containing that line. Example: {"symbol":"my_scripted_effect"}. Returns up to 3 definitions with source text and 10 usages; keyPath and view=structure navigate nested blocks.',
+        title: 'Find definitions and usages',
+        description: 'Find where a script symbol is defined and used across the game, DLC and mod. Pass a symbol, or a file path and line. Example: {"symbol":"my_scripted_effect"}. Returns up to 3 definitions with source text and 10 usages; keyPath and view=structure navigate nested blocks.',
         inputSchema: sourceLookupRequestSchema,
         outputSchema: strictOperationResultSchema(sourceLookupDataSchema),
         annotations: readOnly,
@@ -45,7 +45,7 @@ export const referenceTools = [
     {
         name: 'hoi4.script_validate',
         title: 'Check HOI4 script commands and scopes',
-        description: 'Check an effect or trigger snippet, or a whole mod file, against the installed documentation: syntax, command kinds and scopes. Unknown helpers and native argument blocks stay marked unresolved, never valid. Example: {"source":"add_political_power = 10","kind":"effect","scope":"country"} or {"path":"events/a.txt"}. Returns up to 12 findings.',
+        description: 'Find broken syntax, commands and scopes in an effect, trigger or mod file using the installed docs. Unknown helpers and native argument blocks stay unresolved. Example: {"source":"add_political_power = 10","kind":"effect","scope":"country"} or {"path":"events/a.txt"}. Returns up to 12 findings.',
         inputSchema: scriptValidateRequestSchema,
         outputSchema: strictOperationResultSchema(scriptValidateDataSchema),
         annotations: readOnly,
@@ -53,15 +53,15 @@ export const referenceTools = [
     {
         name: 'hoi4.error_log',
         title: 'Read the game error log',
-        description: 'Group the game\'s logs/error.log from its last launch by category, with each entry\'s source file, line, layer and whether that file changed since; mod entries first. Example: {"scope":"mod","category":"effect"}. Returns at most 20 entries (limit 50) with fix hints and which entries are new since the previous launch.',
+        description: 'Find errors from the last game launch and group them by category, with source files, lines and fix hints. Show which files changed since the log and which errors appeared after a relaunch; mod entries come first. Example: {"scope":"mod","category":"effect"}. Returns at most 20 entries (limit 50) with fix hints and which entries are new since the previous launch.',
         inputSchema: errorLogRequestSchema,
         outputSchema: strictOperationResultSchema(errorLogDataSchema),
         annotations: readOnly,
     },
     {
         name: 'hoi4.mod_index',
-        title: 'Index mod definitions and free IDs',
-        description: 'overview: the mod descriptor, definition counts by kind, folders and event namespace ranges. next_id: the next free numbered ID for an event namespace or prefix across every layer. Example: {"mode":"next_id","kind":"event","namespace":"my_mod"}. Returns a compact summary; the first call indexes the mod, which takes seconds on a large one.',
+        title: 'Explore mod content and find free IDs',
+        description: 'Summarize the content in a mod or find a free event ID across the mod, game and dependencies. Use overview for descriptors, folders and definitions, or next_id with a namespace or prefix. Example: {"mode":"next_id","kind":"event","namespace":"my_mod"}. Returns a compact summary; the first call indexes the mod, which takes seconds on a large one.',
         inputSchema: modIndexRequestSchema,
         outputSchema: strictOperationResultSchema(modIndexDataSchema),
         annotations: readOnly,

package/dist/hoi4_agent_tools/mcp/tools/technology.js

@@ -93,15 +93,15 @@ export const technologyTaskTools = [
     {
         name: 'hoi4.tech_inspect',
         title: 'Inspect technology trees',
-        description: 'Scan, trace, explain, list unlocks and bonus coverage, lint, assess impact or compare (mode compare) technology and doctrine graphs. Example: {"mode":"explain","technologyId":"my_tech"}. Returns counts and the main findings inline; the full report is a linked resource.',
+        description: 'Explain technology and doctrine paths, unlocks, bonuses and dependencies. Find layout or reference problems and compare revisions with mode compare. Example: {"mode":"explain","technologyId":"my_tech"}. Returns counts and the main findings inline; the full report is a linked resource.',
         inputSchema: inspectInputSchema,
         outputSchema: analysisOutputSchema,
         annotations: readOnlyTechnologyTool,
     },
     {
         name: 'hoi4.tech_render',
-        title: 'Render technology trees',
-        description: 'Render a technology folder, dependencies, doctrine, bonuses, grants, unlocks or unresolved view as JSON, SVG and PNG with real item sizes and year guides. Example: {"view":"folder","folderId":"my_folder"}. Images are linked artifacts.',
+        title: 'Preview technology trees',
+        description: 'Preview technology folders and doctrines with their icons, item sizes and year guides. Show dependencies, bonuses, grants, unlocks or unresolved references as JSON, SVG and PNG. Example: {"view":"folder","folderId":"my_folder"}. Images are linked artifacts.',
         inputSchema: renderInputSchema,
         outputSchema: renderOutputSchema,
         annotations: readOnlyTechnologyTool,

package/dist/hoi4_agent_tools/runtime.js

@@ -1,11 +1,12 @@
 import { lstat, readdir, stat } from 'node:fs/promises';
 import path from 'node:path';
-import { homedir } from 'node:os';
+import { homedir, tmpdir } from 'node:os';
 import { loadConfiguration, serverConfigurationSchema, } from './core/configuration.js';
 import { CoreEngine } from './core/engine.js';
 import { ServiceError } from './core/result.js';
 import { WorkspaceResolver } from './core/workspace.js';
 import { CONFIG_VERSION } from './version.js';
+import { sweepTemporaryDirectories } from './core/temporary-directories.js';
 export function defaultConfigurationPath() {
     const configRoot = process.env.APPDATA ?? process.env.XDG_CONFIG_HOME ?? path.join(homedir(), '.config');
     return path.join(configRoot, 'hoi4-agent-tools', 'config.json');
@@ -236,6 +237,18 @@ export async function createEngine(configPath = configurationPath()) {
         configuration = await automaticConfiguration();
     }
     const resolver = await WorkspaceResolver.create(configuration);
+    await sweepTemporaryDirectories(tmpdir(), {
+        protectedRoots: [
+            ...resolver
+                .list()
+                .flatMap((workspace) => [
+                ...workspace.roots.map((root) => root.path),
+                workspace.artifactRoot,
+                workspace.cacheRoot,
+            ]),
+            ...(resolver.serverState() === undefined ? [] : [resolver.serverState().root]),
+        ],
+    }).catch(() => undefined);
     const engine = new CoreEngine(resolver);
     await engine.initialize();
     return engine;

package/dist/hoi4_agent_tools/schemas/map-requests.js

@@ -99,7 +99,7 @@ export const mapInspectRequestSchema = z
         .describe('Also check events, focuses, decisions, history and AI areas for states, provinces and regions the map lacks, and state tags without a country.'),
     layer: mapLayerSchema
         .optional()
-        .describe('Render this base layer instead of validating; combine with overlays, tile or area.'),
+        .describe('Render this base layer; combine with overlays, tile or area.'),
     overlays: z.array(mapOverlaySchema).max(12).optional(),
     scale: z.number().int().min(1).max(16).optional(),
     tile: mapTileSchema.optional().describe('Render one top-left bitmap area.'),

package/dist/hoi4_agent_tools/version.js

@@ -1,6 +1,6 @@
 import { LATEST_PROTOCOL_VERSION } from '@modelcontextprotocol/sdk/types.js';
 export const PACKAGE_NAME = 'hoi4-agent-tools';
-export const PACKAGE_VERSION = '4.0.0';
+export const PACKAGE_VERSION = '4.0.1';
 export const MCP_PROTOCOL_VERSION = LATEST_PROTOCOL_VERSION;
 export const CONFIG_VERSION = 1;
 export const TRANSACTION_VERSION = 1;

package/docs/analysis.md

@@ -1,7 +1,7 @@
 # Cross-system impact and decisions
 
-`hoi4.impact_inspect` and `hoi4.decision_inspect` analyze authorized HOI4 source without changing it or running the game.
-Both tools return a compact result and a linked JSON report containing source locations, hashes, unresolved cases, and the full analysis.
+Find out why a decision is hidden or unavailable, and see what a script change affects elsewhere in the mod.
+`hoi4.impact_inspect` and `hoi4.decision_inspect` return a summary and a linked JSON report with source locations, hashes and unresolved cases.
 They support ordinary calls and persistent MCP tasks through stdio and HTTP.
 
 ## Cross-system impact

package/docs/development.md

@@ -19,6 +19,8 @@ npm run inspector
 
 Keep changes focused and include tests for behavior changes. CI fixtures must be synthetic and project-owned; never commit installed-game or third-party-mod content. Public tool or schema changes require compatibility review and a versioned release.
 
+Vitest tracks temporary fixtures created with `mkdtemp` and removes them after each test or suite teardown, with process-exit cleanup as a fallback. Fixture writes and truncations reserve a 256 MiB aggregate disk budget. Test oversized inputs with a small injected limit or mocked metadata; do not allocate gigabyte fixtures. Startup recovery preserves live owners, locks and dated benchmark evidence; see [temporary fixture ownership](adr/0048-temporary-fixture-lifetimes.md).
+
 The event-chain acceptance fixture contains more than 300 project-owned event definitions and exercises routes, options, timing, state flow, scope changes, unresolved dynamic calls, rendering, and comparison.
 
 The technology acceptance fixture contains 1,040 project-owned technologies across 13 folders and exercises classic and current doctrines, prerequisites, exclusive branches, multiple placements, unlocks, bonuses, grants, assets, unresolved references, rendering, and comparison.

package/docs/events.md

@@ -1,8 +1,7 @@
 # Event chains
 
-The Event Chain Viewer analyzes event definitions and call sites across the active mod, configured dependencies, and vanilla sources. It is read-only: it does not rewrite event files or simulate the game.
-
-Use the three event tools directly from the target mod.
+Follow event chains, see the choices they offer and find broken calls.
+The event tools analyze the mod, its dependencies and vanilla sources. The agent uses the results with its file editor to create or fix events.
 
 ## Inspect
 

package/docs/examples.md

@@ -1,13 +1,10 @@
 # Examples
 
-Start with a task you would normally give your coding agent.
-The agent chooses the MCP tools and opens the resulting images or source references.
-The renders below use real mod and installed HOI4 files; use names from your own mod when trying the prompts.
+Describe what you want to make or fix and the agent chooses the tools.
+The previews below come from real mod and installed HOI4 files.
 
 ## Find a rule without reading a whole wiki
 
-> Find the installed documentation for `save_event_target_as`, read the relevant section, and show a vanilla usage. Keep the file and line references.
-
 The reference tools find the section, read a small excerpt, and retain its source revision so the agent can return to it later.
 In the [measured reference example](research/reference-benchmark.md), the search found the installed effect documentation first and a 12-line read supplied the command and supported scopes.
 No wiki download or game launch was needed.
@@ -16,54 +13,42 @@ Use [Local references](reference.md) to configure an offline wiki snapshot or na
 
 ## Review a large tree
 
-> Render the mod's largest branching focus tree. Check its branch connections, alternative prerequisites, missing references and crowded areas before suggesting edits.
-
 [![Branching focus tree preview](images/comparisons/utopia-mcp.png)](images/comparisons/utopia-mcp.png)
 
 Open the image at full size for the complete layout.
-This example contains 124 focuses in the recorded source version.
 The [focus guide](focus.md) covers inspecting, rendering and reorganizing trees.
 
 ## Preview technology layouts and artwork
 
-> Render the infantry technology folder using this mod and its installed game assets. Check card sizes, icons, prerequisite links and missing placements.
-
 [![Infantry technology folder](images/comparisons/infantry-mcp.png)](images/comparisons/infantry-mcp.png)
 
 The preview follows the loaded technology and GUI definitions, including wide equipment cards.
 The [technology comparisons](https://github.com/klimPaskov/hoi4-agent-tools/blob/main/docs/visual-comparisons.md#technology-folders) also show a mod folder with wide equipment cards rendered from a matching recorded source revision.
 See the [technology guide](technology.md) for grants, bonuses and doctrine paths.
 
-## Inspect an interface before editing it
-
-> Find the Video options window in the installed interface files. Render it with labelled control regions, then check its text, spacing and clipping.
+## Preview a window
 
 | Supplied in-game capture                                                  | MCP source preview                                                     |
 | ------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
 | ![Video options in game](images/comparisons/gui/options-video-ingame.png) | ![Video options preview](images/comparisons/gui/options-video-mcp.png) |
 
-For a mod window, ask for the same view at 100% and 125% UI scale and supply the state values needed by its controls.
+The agent can preview mod windows at different UI scales and work out which state values their controls need.
 Unknown state values must stay unresolved; a visible button alone does not establish that it is enabled in the game.
 The [interface gallery](https://github.com/klimPaskov/hoi4-agent-tools/blob/main/docs/gui-comparisons.md) includes a vanilla priority panel, a mod settings window, an event log, a status panel, and the decision and occupation views.
 
-## Locate map data and plan an edit
-
-> Find Brandenburg by name, show it on the map, and inspect its provinces, neighbours and railway connections. Show the affected files before changing anything.
+## Reshape a map
 
 [![Map rendered from installed source](images/comparisons/source/map-mcp.png)](images/comparisons/source/map-mcp.png)
 
-After reviewing the selection, you can ask for a specific change such as moving named provinces into a state or updating a railway path.
-The map tools check connected records and preserve dated state history when the operation can be represented safely.
+The agent finds the state, splits its provinces and updates connected map records and script references.
+It can also generate a whole new world.
 See [Maps](map.md) for supported edits.
 
 ## Trace an event or compare AI weights
 
-> Trace this event's options and follow-up events. Point out unresolved calls and link each route to its source.
-
 [![Mod event options](images/comparisons/source/event-chain-mcp.png)](images/comparisons/source/event-chain-mcp.png)
 
-> Compare this decision's `ai_will_do` score before and after my change in peace and war. List missing conditions separately from known results.
-
+The AI tools show why a route is favoured or ignored.
 Use [Events](events.md) for route graphs and [AI analysis](probability.md) for supported weights, chances and timing models.
 A decision score is not automatically a percentage chance of an AI click.
 

package/docs/focus.md

@@ -1,10 +1,11 @@
 # Focus trees
 
-Use `hoi4.focus_inspect`, `hoi4.focus_render`, and `hoi4.focus_rewrite` for national focus trees and continuous focus palettes.
+Build focus trees, arrange branches and preview the result.
+Use `hoi4.focus_inspect`, `hoi4.focus_render` and `hoi4.focus_rewrite` for national focus trees and continuous-focus palettes.
 
 ## Create a tree
 
-A complete plan should include:
+The agent assembles the tree from your request. For a direct API call, the `plan` argument should include:
 
 - tree ID and country assignment;
 - branch and lane groups;

package/docs/gui.md

@@ -1,11 +1,10 @@
 # Scripted GUIs
 
-Use `hoi4.gui_inspect`, `hoi4.gui_render`, and `hoi4.gui_rewrite` for `.gui`, `.gfx`, `common/scripted_guis`, localisation, sprites, fonts, and linked decision entry points.
+Build and edit windows, preview their states and find layout problems.
+Use `hoi4.gui_inspect`, `hoi4.gui_render` and `hoi4.gui_rewrite` for `.gui`, `.gfx`, `common/scripted_guis`, localisation, sprites, fonts and linked decisions.
 
 ## Start with a preview
 
-> Render this window at 100% and 125% UI scale. Show its control regions and list the state inputs needed to establish visibility and availability.
-
 The [interface examples](https://github.com/klimPaskov/hoi4-agent-tools/blob/main/docs/gui-comparisons.md) show real vanilla and mod windows.
 Cyan click regions have confirmed availability under the supplied scenario.
 Dashed amber regions are potential controls with unresolved visibility or enabling conditions; they do not count as confirmed branch coverage.
@@ -27,7 +26,7 @@ The preview does not establish native automatic positioning, frame composition,
 
 ## Create a GUI
 
-`hoi4.gui_rewrite` can work from supported source, targeted patches, or structured helpers. Source and helper rewrites may include one bounded text package: the main `.gui` plus additional interface `.gui`/`.gfx`, configured GFX `.gfx`, `common/scripted_guis/*.txt`, and localisation `.yml` files. The package is path-checked, parsed, linked, rendered, validated, and applied together in one rewrite. Existing text encodings are retained, while localisation is always written as UTF-8 with BOM.
+`hoi4.gui_rewrite` can work from supported source, targeted patches, or structured helpers. Source and helper rewrites may include one bounded text package: the main `.gui` plus additional interface `.gui`/`.gfx`, configured GFX `.gfx`, `common/scripted_guis/*.txt`, and localisation `.yml` files. The related files are written together. Existing text encodings are retained, while localisation is always written as UTF-8 with BOM.
 
 A package may contain at most 32 text files and 16 MiB of encoded source in total. Paths are compared portably, so aliases that differ only by letter case are rejected.
 
@@ -103,6 +102,10 @@ For native country-flag controls, bind `element_name.countryTag` and `element_na
 Only valid bounded tag tokens enter asset discovery; an invalid tag is reported, not converted into a different country's identifier or a filesystem path.
 An unrelated global country value does not turn every native icon into a flag.
 
+Some vanilla windows are not scripted: the game itself shows one branch of the window and picks an icon frame from the player's country. `countrypoliticsview` is modelled this way. Its `no_faction`, `original_in_faction` (faction leader), `in_faction` (faction member) and `power_balance_button` branches are shown only when they apply, and `pol_faction_icon` shows the frame of the ruling ideology (fascism, communism, democratic or neutrality) instead of its static `frame = 1`.
+The facts come from `scenario.country`: `tag`, `ideology`, `faction` (`none`, `member` or `leader`) and `balanceOfPower` (boolean). A fact the scenario does not set is read from `history/countries` at the scenario `date` (default 1936.1.1): `set_politics`, `create_faction`, `add_to_faction` in other countries' histories, and `set_power_balance`, with dated blocks later than the scenario date ignored and DLC-conditioned blocks treated as owned. With no country at all, the window shows a country in no faction without a balance of power and reports the approximation. Explicit `visibility`, `values` (`name.visible`, `name.frame`) and `selectedFrames` always win. Every decision is listed under `modelled` as `native_window_state`.
+Source visibility accepts `visible`, `show`, `hide` and `hidden`. Scenario visibility values may be booleans, `yes`/`no`, `true`/`false`, `visible`/`hidden`, or 1/0.
+
 `hoi4.gui_inspect` and `hoi4.gui_render` generate a seeded exploratory preview by default. The generator follows the complete `parent_scripted_gui` surface, discovers numeric and text tokens, fills meters within their declared ranges, and populates dynamic lists with coherent rows. Scripted-localisation text and sprite branches use the same structured condition evaluator as probability analysis, including compound conditions, inclusive comparisons, constants, declared scopes, and scripted triggers. An unknown earlier condition leaves the token unresolved instead of guessing a branch. The scenario's `conditionResults` records checked choices and missing inputs. Explicit values remain authoritative; generated inputs are not verified campaign state. Normal controls and animation frames remain stable unless variation is requested. Every explicit `relatedScenarios` entry is rendered beside the generated view.
 
 Declare scoped facts with `scopes`, for example `"scopes": { "FROM": { "id": "target", "actor": "FRA", "state": { "support": 10 } } }`. Existing flat values such as `FROM.support` remain usable. Seeded pane and active/idle selection is exploratory layout sampling, not proof that every visibility branch is reachable.

package/docs/helper-expansion.md

@@ -1,7 +1,7 @@
 # Bounded helper expansion
 
 `hoi4.event_inspect` and `hoi4.tech_inspect` accept `mode: "helper_expansion"`.
-This is a read-only stream of source-linked helper paths, not a source rewrite or runtime simulation.
+Follow helper calls back to their source and see where analysis could not resolve them.
 It avoids materializing the whole helper closure before returning its first page.
 
 Start either tool with:

package/docs/jobs.md

@@ -1,6 +1,7 @@
 # Persistent jobs and MCP tasks
 
-Long-running domain operations support optional MCP tasks while preserving the ordinary tool-call contract.
+Let a large preview or analysis run in the background, check its progress or stop it.
+Long-running operations support optional MCP tasks and ordinary tool calls.
 Clients that negotiate task support can request a task, disconnect, reconnect with the same authorized identity, inspect or cancel it, and retrieve the original tool result after completion.
 Clients that do not request a task receive the ordinary synchronous tool result.
 
@@ -62,7 +63,9 @@ A read-only job still running `jobCancelGraceSeconds` (1–600, default 10) afte
 A read-only job still running `jobDeadlineSeconds` (1–86,400, default 1,800) after it was dispatched is stopped and fails with `JOB_DEADLINE_EXCEEDED`; narrow its selector or limits, or raise the setting in the server configuration.
 Rewrite jobs are never stopped this way, because their transaction journal owns write recovery; they keep cooperative cancellation and reconciliation.
 Supervision belongs to the server process that dispatched the worker. A read-only worker whose dispatching server has exited enforces the same deadline itself and then exits; a rewrite worker keeps running until it finishes.
-`jobWorkerMaxHeapMiB` (256–65,536) sets a V8 heap ceiling for each worker; without it, workers use Node's default. A worker that runs out of memory ends a job with `JOB_WORKER_EXIT`; retry the call, which starts a fresh worker, or raise the ceiling.
+`jobWorkerMaxHeapMiB` (256–65,536) sets a V8 heap ceiling for each worker; without it, a worker gets a quarter of physical memory, between 2,048 and 8,192 MiB.
+A worker that stops without publishing a result ends the job with `JOB_WORKER_EXIT`, and the message gives the cause the server observed: a V8 heap limit (with its size), a native out-of-memory, a native crash, termination from outside the server, a stop by the server's own deadline, or an uncaught job error with its error code, together with the exit code or signal. Only a V8 heap limit or a native out-of-memory is a memory failure; raise `jobWorkerMaxHeapMiB` or narrow the request for those, and retry otherwise.
+The standard error of the newest ten workers that ended unexpectedly is kept in `job-workers/logs` under the server state root.
 At most `maxSharedTools` (1–128, default 4) workers and expensive calls run at once across every server process that shares a `serverStateRoot`; further work waits for capacity.
 
 Read-only jobs stage a source-revision-bound result checkpoint before terminal publication.

package/docs/map.md

@@ -1,10 +1,11 @@
 # Maps
 
-Use `hoi4.map_inspect` and `hoi4.map_rewrite` for provinces, states, strategic regions, adjacency, supply nodes, railways, positions, ownership, cores, claims, resources, buildings, and localisation.
+Generate a new world, split states and reshape provinces. Preview the map and update the scripts that refer to it.
+Use `hoi4.map_inspect` and `hoi4.map_rewrite` for provinces, states, regions, supply, railways, positions, ownership, resources, buildings and localisation.
 
 ## Inspect and navigate the complete map
 
-`hoi4.map_inspect` validates the map and returns a full-map PNG plus a searchable, clickable HTML navigator by default. The navigator supports pan, zoom, fit-to-map, search by numeric ID, localisation key, or localised name, and exact click lookup for province, state, and strategic-region IDs. Hovering reports both top-left bitmap coordinates and bottom-left HOI4 map coordinates.
+`hoi4.map_inspect` finds map problems and returns a full-map PNG plus a searchable, clickable HTML navigator by default. The navigator supports pan, zoom, fit-to-map, search by numeric ID, localisation key, or localised name, and exact click lookup for province, state, and strategic-region IDs. Hovering reports both top-left bitmap coordinates and bottom-left HOI4 map coordinates.
 
 The linked JSON catalog contains every active province definition, state, and strategic region with resolved names, alternate localisation values, source paths and lines, raster bounds and centers, memberships, neighbors, victory points, resources, buildings, ports, supply nodes, railways, normal and special adjacencies, building positions, unit positions, weather positions, and entity locators. Large catalog and render data remain in MCP resources instead of filling the agent prompt.
 
@@ -231,11 +232,11 @@ Width and height are multiples of 256 with at most 13,238,272 pixels. Land comes
 
 The operation writes `provinces.bmp`, `definition.csv`, `default.map`, `continent.txt`, `heightmap.bmp`, `terrain.bmp`, `rivers.bmp` (rivers run downhill to the coast), `trees.bmp`, `cities.bmp`, `world_normal.bmp`, the land and water colour maps, `adjacencies.csv`, strategic regions (`landProvincesPerRegion`, `seaProvincesPerRegion`) with weather by latitude, states (`provincesPerState`) with population, category, buildings, resources, victory points and ports, country tags, country files, history and three-band flags, a bookmark, localisation, and every position, supply node and railway. Countries grow from spread-out capitals in proportion to `share`; each state lies within one country and one strategic region.
 
-With `replaceBaseGame` (default `true`) it adds `replace_path` lines for `history/states`, `history/countries`, `history/units`, `map/strategicregions`, `map/supplyareas` and `common/bookmarks` to `descriptor.mod`, and its info diagnostic reminds you that the launcher's `.mod` file beside the mod folder needs the same lines. Base-game events, focuses and decisions still name base-game states; `map_inspect` with `references: true` lists them for replacement or remapping. The same seed always gives the same world, and the result is validated like any other rewrite; afterwards refine it with the other operations.
+With `replaceBaseGame` (default `true`) it adds `replace_path` lines for `history/states`, `history/countries`, `history/units`, `map/strategicregions`, `map/supplyareas` and `common/bookmarks` to `descriptor.mod`, and its info diagnostic reminds you that the launcher's `.mod` file beside the mod folder needs the same lines. Base-game events, focuses and decisions still name base-game states; `map_inspect` with `references: true` lists them for replacement or remapping. The same seed always gives the same world. Refine it with the other operations.
 
 ## Worked example: build a world, then reshape it
 
-1. Create the world. The result is validated like any other rewrite, and the same seed always gives the same world.
+1. Create the world. The same seed always gives the same world.
 
    ```json
    {

package/docs/mechanics.md

@@ -1,7 +1,7 @@
 # Mechanic tests, package checks, and scenario suites
 
-`hoi4.mechanic_test`, `hoi4.package_check`, and `hoi4.scenario_test` read authorized HOI4 source and return linked, revision-bound evidence.
-They do not launch the game or change source files.
+Test scripted effects, find missing pieces of a feature and run repeatable scenarios.
+`hoi4.mechanic_test`, `hoi4.package_check` and `hoi4.scenario_test` evaluate mod source and return reports tied to that source revision.
 Supply `expectedRevision` when continuing analysis against a reviewed scan.
 
 ## Test an effect

package/docs/probability.md

@@ -1,6 +1,7 @@
 # AI and MTTH scenario analysis
 
-The probability tools explain weighted HOI4 logic under explicit world-state scenarios. They inspect real mod source or proposed in-memory source, show which conditions and modifiers apply, calculate only probabilities supported by the selected HOI4 surface, and keep every unresolved input visible.
+Find out why the AI favours one choice and ignores another. Compare weights, conditions and timing to help your agent balance events, decisions, focuses and research.
+The tools evaluate existing or proposed source under declared game conditions and list any missing facts.
 
 Use them for event timing and option weights, decision and mission scores, focus selection, technology and doctrine selection, direct random chances, `random_list`, supported AI strategy factors, and declared custom weighted pools.
 
@@ -9,7 +10,9 @@ Use them for event timing and option weights, decision and mission scores, focus
 | `hoi4.probability_inspect` | Find weighted logic by file, identifier or candidate IDs and evaluate it: each candidate's weight and probability per scenario, the strongest first, and the facts still missing.                        |
 | `hoi4.probability_analyze` | Deeper analysis selected by `analysis`: `compare` a proposed or frozen source, `sweep` declared ranges, `simulate` uncertain inputs, `sequence` a declared pool over time, `render` a retained analysis. |
 
-Both tools are read-only. Proposed source is parsed in memory and never written. When an installed game root is configured, evaluation fails closed unless `launcher-settings.json` identifies the supported HOI4 build and checksum. Results otherwise state that they target the adapter version without claiming local-game verification.
+## Game version
+
+When `gameRoot` is configured, `launcher-settings.json` must identify the supported HOI4 build and checksum for evaluation to run. Without a game root, results identify the adapter version. Proposed source is evaluated in memory.
 
 ## One call for current weights
 

package/docs/reference.md

@@ -1,6 +1,7 @@
 # Local references and source lookup
 
-The reference tools read only local, authorized sources. They do not fetch the Paradox Wiki or start Hearts of Iron IV. The installed game's documentation has the highest authority for current syntax; the offline wiki supplies broader modding guidance. A result identifies its source, path, exact lines, and SHA-256 revision so an agent can inspect only the relevant section.
+Find the right modding rule and see how vanilla uses it. The tools search local game documentation, an offline wiki and your mod source.
+The installed game docs define current syntax; the wiki supplies broader guidance. Each result includes its file, lines and source revision.
 
 The server discovers these directories for a workspace:
 

package/docs/setup.md

@@ -44,11 +44,9 @@ After `--init` writes a configuration file, every folder under its mod roots is
 The [configuration reference](configuration.md#how-the-server-picks-your-mod) gives the exact rules, the default file location, every key and the environment variables.
 Indexes are kept in the server's state folder and generated images in workspace storage, both in your user data directory by default.
 
-## 3. Try a small task
+## 3. Start working
 
-> Find the focus trees in this mod and render one of them.
-
-> Find the installed documentation for `save_event_target_as` and read only the relevant section.
+Tell your agent what you want to build or fix in the mod.
 
 Continue with the [examples guide](examples.md).
 Without a configuration file, the folder must look like a mod: it needs `descriptor.mod` or standard HOI4 content folders.

package/docs/technology.md

@@ -1,8 +1,7 @@
 # Technology trees
 
-The Technology Tree Viewer reconstructs classic technologies, legacy doctrine technologies, and current doctrine definitions across the active mod, configured dependencies, and vanilla sources. It links prerequisites, folder placements, exclusive choices, categories, tags, unlocks, bonuses, grants, localisation, icons, and AI metadata without launching the game.
-
-Use the three technology tools directly from the target mod.
+Preview technology trees and doctrines. Follow research paths, unlocks and bonuses, and find missing links or misplaced items.
+The tools reconstruct classic technologies and legacy and current doctrines from the mod, its dependencies and vanilla sources.
 
 ## Inspect