hoi4-agent-tools 3.10.0 → 4.0.1

package/docs/focus.md

@@ -1,10 +1,11 @@
 # Focus trees
 
-Use `hoi4.focus_inspect`, `hoi4.focus_render`, `hoi4.focus_raster`, 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;
@@ -14,7 +15,108 @@ A complete plan should include:
 - focus positions, convergence points, and shared support branches;
 - titles, descriptions, icons, filters, and AI behavior.
 
-For a missing target, call `hoi4.focus_rewrite` with `createIfMissing: true`. Review the proposed and final artifacts returned by the rewrite, then inspect and render the result. Call `hoi4.focus_raster` when the review needs decoded source icons and a deterministic PNG. Do not call a tree complete with placeholder rewards, missing localisation, missing icons, or absent AI choices.
+The `plan` argument of `hoi4.focus_rewrite` follows [focus-plan.schema.json](../schemas/focus-plan.schema.json).
+The easiest starting point for an existing tree is the imported plan in the `plans` array of the JSON artifact returned by `hoi4.focus_inspect`.
+A minimal plan that creates a two-focus tree looks like this:
+
+```json
+{
+  "relativePath": "common/national_focus/my_focus_tree.txt",
+  "treeId": "my_focus_tree",
+  "createIfMissing": true,
+  "plan": {
+    "schemaVersion": 1,
+    "id": "my_focus_tree",
+    "countryAssignment": {
+      "raw": {
+        "text": "{ factor = 0 modifier = { add = 10 tag = AAA } }",
+        "referencedFocusIds": []
+      },
+      "countryTags": ["AAA"]
+    },
+    "default": false,
+    "branchGroups": [],
+    "laneGroups": [],
+    "entryFocusIds": ["my_root_focus"],
+    "focuses": [
+      {
+        "id": "my_root_focus",
+        "label": "Root focus",
+        "prerequisites": { "operator": "and", "groups": [] },
+        "mutuallyExclusive": [],
+        "routeLocks": [],
+        "position": { "mode": "fixed", "x": 0, "y": 0, "pinned": false },
+        "visibility": "normal",
+        "convergence": false,
+        "sharedSupport": false,
+        "icons": [{ "kind": "static", "sprite": "GFX_goal_generic_political_pressure" }],
+        "localisation": { "titleKey": "my_root_focus", "descriptionKey": "my_root_focus_desc" },
+        "ai": {
+          "raw": { "text": "{ factor = 1 }", "referencedFocusIds": [] },
+          "majorRoute": false,
+          "strategyIds": []
+        },
+        "filters": ["FOCUS_FILTER_POLITICAL"],
+        "links": [],
+        "cost": 10,
+        "completionReward": { "text": "{ add_political_power = 50 }", "referencedFocusIds": [] },
+        "rawPassthrough": []
+      },
+      {
+        "id": "my_second_focus",
+        "label": "Second focus",
+        "prerequisites": {
+          "operator": "and",
+          "groups": [{ "operator": "or", "focusIds": ["my_root_focus"], "rawPassthrough": [] }]
+        },
+        "mutuallyExclusive": [],
+        "routeLocks": [],
+        "position": {
+          "mode": "relative",
+          "x": 0,
+          "y": 1,
+          "relativeTo": "my_root_focus",
+          "pinned": false
+        },
+        "visibility": "normal",
+        "convergence": false,
+        "sharedSupport": false,
+        "icons": [{ "kind": "static", "sprite": "GFX_goal_generic_construct_civ_factory" }],
+        "localisation": { "titleKey": "my_second_focus", "descriptionKey": "my_second_focus_desc" },
+        "ai": {
+          "raw": { "text": "{ factor = 1 }", "referencedFocusIds": [] },
+          "majorRoute": false,
+          "strategyIds": []
+        },
+        "filters": ["FOCUS_FILTER_INDUSTRY"],
+        "links": [],
+        "cost": 10,
+        "completionReward": {
+          "text": "{ add_tech_bonus = { bonus = 0.5 uses = 1 category = industry } }",
+          "referencedFocusIds": []
+        },
+        "rawPassthrough": []
+      }
+    ],
+    "sharedFocusIds": [],
+    "continuousFocusPaletteIds": [],
+    "continuousFocusIds": [],
+    "rawPassthrough": [],
+    "provenance": {
+      "sourcePath": "plan:my_focus_tree",
+      "sourceHash": "0000000000000000000000000000000000000000000000000000000000000000",
+      "importedPlanHash": "0000000000000000000000000000000000000000000000000000000000000000"
+    }
+  }
+}
+```
+
+Raw blocks such as `countryAssignment.raw`, `ai.raw`, and `completionReward` hold the Clausewitz block text including its braces; the rewrite writes it after the matching key.
+Each `prerequisites.groups` entry is one `prerequisite` block whose `focusIds` are alternatives.
+`provenance` must be present: an imported plan carries the hashes of the source it came from, and a plan for a new tree may use 64-character hexadecimal placeholders as shown.
+When `treeId` is also supplied, it must equal `plan.id`.
+
+For a missing target, call `hoi4.focus_rewrite` with `createIfMissing: true`. Review the proposed and final artifacts returned by the rewrite, then inspect and render the result. `hoi4.focus_render` returns a deterministic PNG with decoded source icons. Do not call a tree complete with placeholder rewards, missing localisation, missing icons, or absent AI choices.
 
 ## Clean an existing tree
 
@@ -28,6 +130,11 @@ For a layout-only cleanup of an existing national tree, call `hoi4.focus_rewrite
 }
 ```
 
+A plan-free call is accepted only in national mode with `layoutMode: "compact"`.
+It requires `treeId`, works on an existing focus source, and rejects `createIfMissing: true`.
+Every other national rewrite requires a `plan`.
+`compactFocusIds` (1 to 10,000 IDs), `pinnedFocusIds` (up to 10,000 IDs), and `symmetryGroups` (up to 64 groups) are accepted only with `layoutMode: "compact"`.
+
 Compact mode imports the tree, resets authored presentation coordinates and lane bounds, and performs a deterministic reflow in the same rewrite call. It keeps prerequisites, mutual exclusions, availability, bypasses, rewards, icons, localisation, AI behavior, and route/lane membership unchanged.
 
 The rewrite measures canvas bounds, same-row spacing, the same curved connector paths used by the renderer, connector lengths, connector-node intersections, branch balance, overall centering, and topology-aware fake-complexity patterns. Compact mode evaluates preservation, occupied-row repair, prerequisite-depth reflow, linear-chain repair, sibling balancing, and combined compression strategies, then chooses the cleanest valid result. Equivalent branches are aligned by dependency depth even when their authored rows differ, and connector shape is prioritized before raw canvas dimensions so a shorter canvas cannot win by introducing unnecessary horizontal detours. Sparse direct sibling fan-outs are packed around their parent at the minimum readable spacing, with each exclusive descendant branch moving as a unit and shared convergence focuses staying centered. Dense branches remain wider only when their contents need the room. It refuses invalid geometry such as overlapping or cramped focuses, bad parent order, rendered crossings, connectors through unrelated focuses, or an off-center canvas. Long connectors, fake detours, staircase or zigzag chains, and avoidable sibling imbalance are optimization priorities instead of independent rejection budgets.
@@ -40,6 +147,21 @@ Pass `symmetryGroups` with a `centerFocusId` and one or more `{ "leftFocusId": "
 
 A cleanup should not change gameplay relationships to improve the picture. One `prerequisite` block containing several focus IDs is an OR group; several prerequisite blocks are AND requirements.
 
+## Continuous focus palettes
+
+Set `mode: "continuous"` on `hoi4.focus_inspect`, `hoi4.focus_render`, or `hoi4.focus_rewrite` to work with a `continuous_focus_palette` instead of a national tree; the default mode is `national`.
+
+- `hoi4.focus_inspect` and `hoi4.focus_render` select one palette with `paletteId`.
+  Without it, inspection includes every palette in the selected source, and rendering requires the source to contain exactly one palette.
+  The inspection JSON artifact lists the imported palette plans in `continuousFocusPalettes`.
+- `treeId` is rejected in continuous mode.
+  Inspection also rejects `previous`, `laneSpacing`, `nodeSpacing`, and `scenario`, and rendering rejects `horizontalSpacing`, `verticalSpacing`, `reviewScale`, and `cropFocusIds`.
+- Rendering accepts `columns` (1 to 12) only in continuous mode, and continuous `padding` must be at least 24 pixels.
+- `hoi4.focus_rewrite` requires a `plan` that matches [continuous-focus-palette.schema.json](../schemas/continuous-focus-palette.schema.json); the palette is identified by `plan.id`, and the rewrite has no `paletteId` field.
+  `layoutMode` must stay `authored`, and `horizontalSpacing`, `verticalSpacing`, `padding`, and `reviewScale` are rejected.
+- A palette needs a mod-owned source.
+  Creating a palette with `createIfMissing: true` requires a new source file, so an unrelated existing file is never repurposed.
+
 ## Layout metadata and unsupported script
 
 Branch names, lane assignments, working labels, and other planning-only data may be stored in a `.focus-plan.json` file beside the focus source. HOI4 does not load that file.
@@ -52,10 +174,10 @@ Inspection and rendering can report missing references, invalid prerequisite str
 
 For a named tree, pass `scenario: { "completedFocusIds": ["my_route_root"] }` to `hoi4.focus_inspect`. The linked inspection artifact records each focus's prerequisite groups, route locks, exclusive choices, and unresolved runtime fields against that completed set. The inline tree summary counts completed, blocked, unresolved, and structural candidate focuses, plus contradictory completed choices. A structural candidate still requires runtime trigger evaluation before an agent can call it playable.
 
-Pass up to 16 `cropFocusIds` to `hoi4.focus_raster` for source-linked problem crops around specific focuses. Each crop uses the same rendered pixels as the full tree; a JSON manifest records the focus ID, crop bounds, image hash, and diagnostics. An unknown focus ID is reported explicitly.
+Pass up to 16 `cropFocusIds` to `hoi4.focus_render` for source-linked problem crops around specific focuses. Each crop uses the same rendered pixels as the full tree; a JSON manifest records the focus ID, crop bounds, image hash, and diagnostics. An unknown focus ID is reported explicitly.
 
 The layout JSON reports horizontal, vertical, and Manhattan grid spans for every prerequisite connector in `layout.connectorMeasurements`.
 
-`hoi4.focus_render` is the normal structural view and writes complete HTML, SVG, JSON, and source-map artifacts without decoding every icon or creating a PNG. `hoi4.focus_raster` adds decoded icons and the high-fidelity PNG. National trees with 200 or more focuses raster at half scale by default; pass `reviewScale` from `0.25` through `1` when a different PNG size is needed.
+`hoi4.focus_render` writes complete HTML, SVG, JSON and source-map artifacts and a high-fidelity PNG with decoded icons. Pass `png: false` for the faster structural view without decoding icons. National trees with 200 or more focuses raster at half scale by default; pass `reviewScale` from `0.25` through `1` when a different PNG size is needed.
 
 The public workflow is regression-tested with 1,024-focus creation, compact rewrites, deterministic repeat runs, inspection, vector rendering, and raster rendering. A separate 1,024-icon test decodes a distinct texture for every focus. Large source diffs use the same deterministic review-artifact path instead of blocking at the quadratic matrix size.

package/docs/gui.md

@@ -1,12 +1,11 @@
 # 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](gui-comparisons.md) show real vanilla and Chaos Redux windows.
+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.
 The scene retains the reason so the agent can supply the missing facts instead of guessing.
@@ -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.
@@ -112,7 +115,7 @@ Generation is reproducible. Set `generatedScenarios.seed` to any stable string f
 ```json
 {
   "generatedScenarios": {
-    "seed": "chaos-meter-review",
+    "seed": "status-panel-review",
     "count": 3,
     "numericMinimum": 0,
     "numericMaximum": 100,
@@ -164,7 +167,10 @@ Broad inspection indexes localisation actually referenced by GUI source and retu
 
 GUI rewrites keep complete validation evidence in a linked JSON resource and retain the highest-priority findings in the transaction result. Large surrounding interface inventories therefore do not turn a small scalar patch into a transaction structure-limit error.
 
-Large inspections, renders, and rewrites send periodic MCP progress heartbeats while a service stage is still running. Clients that request progress can reset their idle request timer from these notifications; there is no 180-second GUI operation limit in the server, and cancellation still follows the request signal.
+Large inspections, renders, and rewrites send periodic MCP progress heartbeats while a service stage is still running.
+Clients that request progress can reset their idle request timer from these notifications, and cancellation follows the request signal.
+A read-only `hoi4.gui_inspect` or `hoi4.gui_render` job still running after the configurable `jobDeadlineSeconds` (default 1,800) is stopped with `JOB_DEADLINE_EXCEEDED`; a `hoi4.gui_rewrite` job is not stopped by that deadline.
+See [persistent jobs and MCP tasks](jobs.md#cancellation-and-recovery).
 
 ## Source-backed button shading
 
@@ -186,20 +192,48 @@ The renderer does not run the game engine. Each render includes a fidelity repor
 
 ### Scenario fields
 
-Every `scenario` needs an `id`, a short label such as `"usa_1936"`. The other fields describe the game state the window is drawn under:
-
-| Field                                        | Meaning                                                                                                                                                                                        |
-| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `date`                                       | Game date, `"1936.1.1"`.                                                                                                                                                                       |
-| `controls`                                   | State controllers, `{"64": "GER"}`.                                                                                                                                                            |
-| `flags`                                      | Flags on the viewing country, `{"show_settings_page": true}`.                                                                                                                                  |
-| `closedFlags`                                | `true` treats every flag not listed in `flags` as unset, as on a country that never received it. Without it, an undeclared flag is unknown and every condition that reads it stays unresolved. |
-| `variables`                                  | Variables on the viewing country, `{"settings_page": 1}`.                                                                                                                                      |
-| `values`                                     | Exact runtime values for localisation tokens and scripted GUI properties, keyed as they appear in source.                                                                                      |
-| `visibility`                                 | Forced visibility by element or scripted GUI name, `{"settings_page_events": false}`; it overrides evaluated triggers.                                                                         |
-| `scopes`                                     | Named scope bindings such as `FROM` with their own state.                                                                                                                                      |
-| `resolution`, `uiScale`, `state`, `language` | Screen size, in-game UI scale, preview element state, and localisation language.                                                                                                               |
-| `background`                                 | `"transparent"` renders without the preview backdrop, so pixels the window does not cover are fully transparent in every PNG.                                                                  |
+Every `scenario` needs an `id`, a short label such as `"usa_1936"`.
+The other fields describe the game state the window is drawn under and how the preview is produced.
+Unknown fields are rejected.
+The complete schema is [gui-scenario.schema.json](../schemas/gui-scenario.schema.json); `relatedScenarios` entries and `comparisonScenario` use the same shape.
+
+| Field                  | Type                                          | Default and limits                                                                                                                                                                                                           | Meaning                                                                                                                                                                                                            |
+| ---------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `id`                   | string                                        | Required; 1–128 characters matching `^[A-Za-z0-9][A-Za-z0-9._-]*$`.                                                                                                                                                          | Scenario label used in artifact names and reports.                                                                                                                                                                 |
+| `description`          | string                                        | Optional; at most 500 characters.                                                                                                                                                                                            | Free-text note about the scenario.                                                                                                                                                                                 |
+| `date`                 | string                                        | Optional; a valid calendar date as `YYYY.M.D` or `YYYY-MM-DD`, at most 16 characters.                                                                                                                                        | Game date, `"1936.1.1"`, for date conditions.                                                                                                                                                                      |
+| `country`              | map of name → string, number, or boolean      | Optional.                                                                                                                                                                                                                    | Viewing-country values for `[ROOT.GetName]`-style text; `tag`, `countryTag`, or `GetTag` names the actor country for conditions and for country flags, and `ideology` selects the flag variant.                    |
+| `controls`             | map of state ID → country tag                 | Optional; state IDs are positive integers without leading zeros, tags are three `A-Z` or `0-9` characters, at most 2,048 entries.                                                                                            | State controllers, `{"64": "GER"}`, for `controls_state` and `is_controlled_by`.                                                                                                                                   |
+| `flags`                | map of flag name → boolean                    | `{}`.                                                                                                                                                                                                                        | Flags on the viewing country, `{"show_settings_page": true}`.                                                                                                                                                      |
+| `closedFlags`          | boolean                                       | Optional; absent means `false`.                                                                                                                                                                                              | `true` treats every flag not listed in `flags` as unset, as on a country that never received it. Without it, an undeclared flag is unknown and every condition that reads it stays unresolved.                     |
+| `variables`            | map of name → number                          | `{}`.                                                                                                                                                                                                                        | Variables on the viewing country, `{"settings_page": 1}`.                                                                                                                                                          |
+| `values`               | map of key → string, number, or boolean       | `{}`; strings at most 16,384 characters.                                                                                                                                                                                     | Exact runtime values for localisation tokens, scripted-GUI properties, and element keys such as `element.visible`, `element.enabled`, `element.frame`, `element.x`, `container.scrollY`, or `element.width`.       |
+| `stateValues`          | map of key → string, number, or boolean       | Optional.                                                                                                                                                                                                                    | Additional condition state for the viewing country; `variables` and `values` override the same key.                                                                                                                |
+| `conditionResults`     | array of condition records                    | Optional; at most 10,000 records of `{ token, sourcePath, state, localisationKey?, unresolved }`, where `state` is `true`, `false`, or `unresolved`.                                                                         | Written by the scenario generator to record checked scripted-localisation choices and missing inputs. It is accepted on input so a returned scenario can be sent back unchanged; it does not decide any condition. |
+| `visibility`           | map of element or scripted-GUI name → boolean | `{}`.                                                                                                                                                                                                                        | Forced visibility, `{"settings_page_events": false}`; it overrides evaluated triggers.                                                                                                                             |
+| `scopes`               | map of scope name → scope binding             | Optional; names at most 256 characters.                                                                                                                                                                                      | Named scope bindings such as `FROM`. A binding has `id` (1–256 characters) and optional `type`, `actor`, `state`, `flags` (an array of names), `eventTargets`, and `weight`.                                       |
+| `lists`                | map of list name → array of row objects       | `{}`; at most 256 list names and 10,000 rows across all lists.                                                                                                                                                               | Dynamic and native list rows. Each row is a map of scalars, such as `id`, `label`, `countryScope`, `entryContainer`, `countryTag`, `ideology`, and row-scoped element values.                                      |
+| `localisation`         | map of key → text                             | `{}`.                                                                                                                                                                                                                        | Per-scenario localisation overrides; a key here replaces the installed text for that key.                                                                                                                          |
+| `scriptedGui`          | map of key → string, number, or boolean       | `{}`.                                                                                                                                                                                                                        | Scripted-GUI property and token values, including exact `[!element_action]`-style tooltip tokens; `values` takes precedence for the same key.                                                                      |
+| `elementStates`        | map of element name → preview state           | `{}`; states as listed for `state`.                                                                                                                                                                                          | Per-element preview state that overrides `state` for that element.                                                                                                                                                 |
+| `selectedFrames`       | map of element or sprite name → integer       | `{}`; integers of at least 0.                                                                                                                                                                                                | Zero-based frame index for a frame sprite, clamped to the last frame. It takes precedence over `.frame` values, which are one-based as in HOI4 source.                                                             |
+| `scrollOffsets`        | map of container name → number                | `{}`; numbers of at least 0.                                                                                                                                                                                                 | Vertical scroll offset shorthand in native UI pixels, including names with row-instance suffixes.                                                                                                                  |
+| `guiCosts`             | map of key → number                           | `{}`.                                                                                                                                                                                                                        | Cost shown by the GUI for a key.                                                                                                                                                                                   |
+| `scriptCosts`          | map of key → number                           | `{}`.                                                                                                                                                                                                                        | Cost charged by script for the same key; a different `guiCosts` value for that key reports `GUI_COST_MISMATCH`.                                                                                                    |
+| `expectations`         | object                                        | `{ "visible": [], "hidden": [], "containedBy": {}, "centeredOn": {} }`; each list holds at most 10,000 selectors.                                                                                                            | Layout assertions: `visible` and `hidden` list selectors, `containedBy` maps a selector to its intended background or panel, and `centeredOn` maps a label to the control it should be centred on.                 |
+| `tooltip`              | object                                        | Optional; `target` (1–256 characters), `x`, `y`, `width`, and `padding` are all required. `x`, `y`, and `padding` are at least 0, `width` is greater than 0 and at most 16,384, and `padding * 2` must be less than `width`. | Immediate tooltip preview for one element, as described in [Preview immediate tooltip text](#preview-immediate-tooltip-text).                                                                                      |
+| `resolution`           | `{ width, height }`                           | `{ "width": 1920, "height": 1080 }`; integers, width 320–16,384 and height 200–16,384, within the render pixel budget.                                                                                                       | Screen size in pixels.                                                                                                                                                                                             |
+| `uiScale`              | number                                        | `1`; 0.25–4.                                                                                                                                                                                                                 | In-game UI scale. It changes layout geometry and is not an output-image zoom.                                                                                                                                      |
+| `state`                | string                                        | `"normal"`; one of `normal`, `hover`, `selected`, `locked`, `disabled`, `warning`, `active`, `completed`, `empty-list`, `full-list`, `minimum-value`, `maximum-value`, `long-text`, `missing-localisation`.                  | Preview state applied to every element without an `elementStates` entry.                                                                                                                                           |
+| `language`             | string                                        | `"l_english"`; matches `^l_[a-z_]+$`.                                                                                                                                                                                        | Localisation language, which also selects language-specific fonts.                                                                                                                                                 |
+| `background`           | string                                        | Optional; `scene` or `transparent`. Absent means `scene`.                                                                                                                                                                    | `"transparent"` renders without the preview backdrop, so pixels the window does not cover are fully transparent in every PNG.                                                                                      |
+| `animationTimeSeconds` | number                                        | `0`; 0–86,400.                                                                                                                                                                                                               | Elapsed time for frame animation and button-state shading; `0` represents entry into the state.                                                                                                                    |
+| `visibleTimeSeconds`   | number                                        | Optional; 0–86,400.                                                                                                                                                                                                          | Elapsed time since the window became visible, used by frame animations that play on show; absent means `animationTimeSeconds`.                                                                                     |
+
+A whole scenario may hold at most 100,000 object keys and 1,000,000 string characters in total.
+
+GUI `flags` is a `{ "name": true }` map.
+Decision scenarios (`hoi4.decision_inspect`) and probability scenarios take `flags` as an array of flag names, such as `["relief_open"]`, and so do scope bindings in every tool, including GUI `scopes`.
 
 A scripted GUI `visible` or `<element>_visible` trigger that the scenario decides hides or shows its element exactly.
 For compositing, each visible element is its own `<g>` group in the full SVG, with an `id` that matches the element in `layout.json`, which also records every element's box.
@@ -212,3 +246,53 @@ Scripted localisation (`defined_text`) used by the window resolves to its first
 The generated primary view replaces discovered numeric and text runtime tokens with plausible values. Set `generatedScenarios.preservePlaceholder` to `true`, or disable generation, when the same run should also show unresolved numeric values such as `[?variable|format]` as `[X]` and unresolved text-returning scripted or scoped localisation such as `[GetStatusText]`, `[FROM.GetName]`, and `[?leader_scope.GetName]` as `[dynamic_loc]`. Put `variable` or `GetStatusText` in the supplied scenario's `values` object when an exact value matters; explicit values always take precedence over generated ones and can drive the related meter or state-dependent controls. Supported HOI4 `§` localisation colour controls use the active font's palette and `§!` restores the face colour.
 
 A rewrite stops if malformed or unsupported GUI script makes the requested change ambiguous. Frame-sheet animation, nine-slice tiling, progress composition, masking, and the primary and secondary textures referenced by vanilla GFX definitions render offline. Font selection follows mod/game load order and preview language, accepts Paradox hex and numeric color declarations, and uses the supplied HOI4 bitmap or outline font assets without requiring host font installation. Shader operations outside the supported colour subset, hardcoded controls, and dynamic values that are not supplied by a scenario remain fidelity-report entries; an unexecuted shader never hides its resolved base texture.
+
+### Generated scenarios
+
+`generatedScenarios` configures the seeded exploratory scenarios that `hoi4.gui_inspect` and `hoi4.gui_render` build from the supplied scenario.
+It requires a window `scenario`, and unknown fields are rejected.
+
+| Field                 | Default and limits                                                                                  | Meaning                                                                                                                                                                     |
+| --------------------- | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `enabled`             | `true`                                                                                              | `false` renders only the supplied scenario and its related scenarios.                                                                                                       |
+| `count`               | `1`; 1–16.                                                                                          | Number of generated scenarios.                                                                                                                                              |
+| `seed`                | `"auto"`; 1–256 characters.                                                                         | `"auto"` derives the seed from the window name, scenario `id`, and source-graph hash, so unchanged source reproduces the same output; any other string is used as the seed. |
+| `idPrefix`            | `"generated"`; 1–64 characters matching `^[A-Za-z0-9][A-Za-z0-9._-]*$`.                             | Generated scenario IDs are `<scenario id>-<idPrefix>-<n>`.                                                                                                                  |
+| `preservePlaceholder` | `false`                                                                                             | `true` also renders the supplied scenario, with unresolved tokens shown as `[X]` and `[dynamic_loc]`.                                                                       |
+| `numericMinimum`      | `0`; −1,000,000,000 to 1,000,000,000.                                                               | Lower bound for generated numbers.                                                                                                                                          |
+| `numericMaximum`      | `100`; −1,000,000,000 to 1,000,000,000, and at least `numericMinimum`.                              | Upper bound for generated numbers.                                                                                                                                          |
+| `integerValues`       | `true`                                                                                              | `false` allows decimal values.                                                                                                                                              |
+| `listRowsMinimum`     | `1`; 0–100.                                                                                         | Fewest generated rows per list.                                                                                                                                             |
+| `listRowsMaximum`     | `5`; 0–100, and at least `listRowsMinimum`.                                                         | Most generated rows per list.                                                                                                                                               |
+| `trueProbability`     | `0.7`; 0–1.                                                                                         | Probability that a generated Boolean is `true`.                                                                                                                             |
+| `visibility`          | `"varied"`; `show-all` or `varied`.                                                                 | `show-all` shows every scripted GUI that has a visibility trigger; `varied` samples which of them are shown. Explicit `visibility` entries are kept in both modes.          |
+| `elementStates`       | `"normal"`; `normal` or `varied`.                                                                   | `varied` samples per-element preview states; `normal` keeps controls in their normal state.                                                                                 |
+| `textSamples`         | `["Operational", "Ready", "Stable", "Available", "In Progress"]`; 1–64 strings of 1–128 characters. | Strings used for generated text values.                                                                                                                                     |
+
+### Request fields
+
+Every request accepts `workspaceId`, which defaults to `"current"`.
+`windowName` is 1–256 characters, and `scenario` follows the scenario fields above.
+
+| Field                | Tools                    | Limits                                                                                                         | Meaning                                                                                                                                                                         |
+| -------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `windowName`         | inspect, render, rewrite | Required for render and rewrite; inspect requires it exactly when `scenario` is present.                       | Root window to inspect, render, or validate. An inspect call without `windowName` and `scenario` inspects the workspace GUI graph.                                              |
+| `scenario`           | inspect, render, rewrite | Required for render and rewrite.                                                                               | Primary scenario.                                                                                                                                                               |
+| `relatedScenarios`   | inspect, render          | At most 32; requires `scenario`.                                                                               | Additional explicit scenarios rendered beside the primary and generated views.                                                                                                  |
+| `generatedScenarios` | inspect, render          | Requires `scenario`.                                                                                           | Generator options from the table above.                                                                                                                                         |
+| `states`             | render                   | At most 14 values of the `state` enumeration; defaults to all 14.                                              | Preview states in the state gallery.                                                                                                                                            |
+| `resolutions`        | render                   | 1–16 entries of `{ width, height, uiScale? }`, with the same size limits as `resolution` and `uiScale` 0.25–4. | Resolution gallery. The default is 1280×720, 1920×1080, and 2560×1440 at UI scale 1, plus 1920×1080 at UI scale 1.25. An entry without `uiScale` uses the scenario's `uiScale`. |
+| `comparisonScenario` | render                   | Same shape as `scenario`.                                                                                      | Second scenario compared against the primary scenario on the current source.                                                                                                    |
+| `sourceBaseline`     | render                   | `{ relativePath, source }`; `source` at most 32 MiB.                                                           | Previous mod-owned `.gui` text rendered with the same scenario for a source comparison.                                                                                         |
+| `mode`               | rewrite                  | Required; `source`, `helpers`, or `patches`.                                                                   | Rewrite input form.                                                                                                                                                             |
+| `relativePath`       | rewrite                  | Required workspace-relative path.                                                                              | Main `.gui` file to write.                                                                                                                                                      |
+| `source`             | rewrite                  | Required in `source` mode and rejected in the other modes; at most 32 MiB.                                     | Complete replacement `.gui` source.                                                                                                                                             |
+| `helper`             | rewrite                  | Required in `helpers` mode and rejected in the other modes.                                                    | Structured helper document; see [gui-helper.schema.json](../schemas/gui-helper.schema.json).                                                                                    |
+| `additionalFiles`    | rewrite                  | At most 31 entries of `{ relativePath, source }`, each `source` at most 32 MiB; rejected in `patches` mode.    | Other files in the same text package, as described in [Create a GUI](#create-a-gui).                                                                                            |
+| `expectedSourceHash` | rewrite                  | Required in `patches` mode and rejected otherwise; 64 lowercase hexadecimal characters.                        | SHA-256 of the current file bytes; a different current file fails with `GUI_SOURCE_STALE`.                                                                                      |
+| `patches`            | rewrite                  | Required in `patches` mode and rejected otherwise; 1–1,000 entries.                                            | Targeted replacements of `{ start, end, expectedText, text, description }`.                                                                                                     |
+| `requestKey`         | rewrite                  | 1–256 characters.                                                                                              | Caller-stable key for native background rewrites and their retries; see [rewrite request keys](jobs.md#rewrite-request-keys).                                                   |
+
+Each patch replaces the source text between offsets `start` and `end`, which are integers of at least 0.
+The current text in that range must equal `expectedText`; otherwise the rewrite stops with `GUI_PATCH_PRECONDITION_FAILED`.
+`expectedText` and `text` are at most 5,000,000 characters each, and `description` is 1–1,000 characters.

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:
@@ -33,13 +33,13 @@ To analyze edited source or use a different depth, start a new request without t
 
 `helperExpansion` has these optional fields:
 
-| Field             | Contract                                                                                                                                                                 |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `rootIds`         | Up to 2,000 exact structural helper-call root IDs; omitted means all recognized non-helper callers. Obtain IDs from a page's `rootId` or the linked ordinary scan graph. |
-| `maxDepth`        | 1–256 helper calls, default 64.                                                                                                                                          |
-| `maxRecords`      | 1–5,000 records per page, default 250.                                                                                                                                   |
-| `maxWork`         | 1–100,000 traversal transitions per page, default 5,000.                                                                                                                 |
-| `continuationUri` | Opaque sibling resource returned in the prior tool result. Do not edit or construct it.                                                                                  |
+| Field             | Contract                                                                                                                                                                                                             |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rootIds`         | 1 to 2,000 exact structural helper-call root IDs; an empty array is rejected, and omitting the field selects all recognized non-helper callers. Obtain IDs from a page's `rootId` or the linked ordinary scan graph. |
+| `maxDepth`        | 1–256 helper calls, default 64.                                                                                                                                                                                      |
+| `maxRecords`      | 1–5,000 records per page, default 250.                                                                                                                                                                               |
+| `maxWork`         | 1–100,000 traversal transitions per page, default 5,000.                                                                                                                                                             |
+| `continuationUri` | Opaque sibling resource returned in the prior tool result. Do not edit or construct it.                                                                                                                              |
 
 Other inspection filters such as top-level `maxDepth`, `selector`, and `technologyId` are rejected in this mode rather than silently ignored.
 The shared dependency inventory is limited to one million edges; source, parser, and artifact byte limits also remain enforced.
@@ -69,7 +69,7 @@ This is not permanent storage of every historical page.
 
 ## Compatibility and boundaries
 
-This opt-in mode and optional result summary are additive in 3.1.0.
+The `helper_expansion` mode and its `data.helperExpansion` result summary are opt-in; other inspection modes neither accept `helperExpansion` nor return the summary.
 Existing inspection modes retain their own ordering, representative-path policy, and materialization limits.
 A depth- or projection-truncated materialized graph reports incomplete coverage.
 The paged edge-path stream must not be mistaken for the deduplicated projections in those graphs.

package/docs/http.md

@@ -41,7 +41,7 @@ Add an HTTP section to a config created by setup:
 }
 ```
 
-Set `HOI4_AGENT_HTTP_TOKEN` to a random value of at least 32 characters, then run `hoi4-agent-tools-http --config PATH`. `allowDiscoveredMods` grants that principal only the mod IDs created by discovery beneath `modRoots`; it never grants unrelated explicit workspaces. For narrower remote access, define the permitted mods as explicit `workspaces`, list those IDs in `workspaceIds`, and omit `allowDiscoveredMods`.
+Set `HOI4_AGENT_HTTP_TOKEN` to a random value of at least 32 characters, then run `hoi4-agent-tools-http --config PATH`. `allowDiscoveredMods` grants that principal only the mod IDs created by discovery beneath `modRoots`; it never grants unrelated explicit workspaces. A static token always grants both `hoi4:read` and `hoi4:write`, so its holder can run the rewrite tools that change mod source. For narrower remote access, define the permitted mods as explicit `workspaces`, list those IDs in `workspaceIds`, and omit `allowDiscoveredMods`.
 
 ## Shared or remote access
 
@@ -54,6 +54,8 @@ A non-loopback deployment needs:
 - narrow mounted mod and game paths;
 - request, connection, and session limits.
 
+The `http.oauth` block (`issuer`, `jwksUri`, `audience`, `requiredScopes`, `algorithms`) validates tokens; an OAuth principal receives only the scopes in its token, and `requiredScopes` defaults to `["hoi4:read"]`, so grant `hoi4:write` only to principals that may edit mods. `publicUrl`, `trustedProxyAddresses`, the timeouts, and the connection, session, event-stream and rate limits are listed in the [configuration reference](configuration.md#http).
+
 Do not expose a developer home directory or a whole game library. The installed game and dependencies should be mounted read-only. Use separate server instances for teams that should not share operating-system access.
 
 The server never launches Hearts of Iron IV and does not need a desktop or Steam session. See the repository [Security Policy](../SECURITY.md) before exposing HTTP beyond loopback.

package/docs/jobs.md

@@ -1,10 +1,11 @@
 # 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 continue to receive the same synchronous tool result as before.
+Clients that do not request a task receive the ordinary synchronous tool result.
 
-Version 3.1.0 routes 2025-era clients through the existing stateful adapter and 2026-07-28 clients through the [modern operation/task adapter](adr/0031-modern-mcp-task-adapter.md) on both stdio and HTTP.
+The server routes 2025-era clients through the stateful adapter and 2026-07-28 clients through the [modern operation/task adapter](https://github.com/klimPaskov/hoi4-agent-tools/blob/main/docs/adr/0031-modern-mcp-task-adapter.md) on both stdio and HTTP.
 Modern requests independently negotiate the Tasks extension, use authenticated flat handles, and receive terminal results in `tasks/get`.
 
 Clients can request ordinary-call progress with a progress token.
@@ -14,15 +15,21 @@ A modern native task handoff ends that request's heartbeat without declaring the
 
 ## Supported tools
 
-Optional tasks are available for every read-only event, impact, decision, technology, probability, map, GUI, and focus operation, and for the three rewrite tools:
+Optional tasks are available for all 19 domain tools; the 7 reference tools and the 2 job tools always answer in the foreground.
 
-- `hoi4.event_inspect`, `hoi4.event_render`, and `hoi4.event_compare`
-- `hoi4.impact_inspect` and `hoi4.decision_inspect`
-- `hoi4.tech_inspect`, `hoi4.tech_render`, and `hoi4.tech_compare`
-- `hoi4.probability_inspect`, `hoi4.probability_evaluate`, `hoi4.probability_sweep`, `hoi4.probability_simulate`, `hoi4.probability_sequence`, `hoi4.probability_compare`, and `hoi4.probability_render`
-- `hoi4.map_inspect`, `hoi4.map_render`, and `hoi4.map_rewrite`
+- `hoi4.event_inspect` and `hoi4.event_render`
+- `hoi4.impact_inspect`, `hoi4.decision_inspect`, `hoi4.mechanic_test`, `hoi4.package_check`, and `hoi4.scenario_test`
+- `hoi4.tech_inspect` and `hoi4.tech_render`
+- `hoi4.probability_inspect` and `hoi4.probability_analyze`
+- `hoi4.map_inspect` and `hoi4.map_rewrite`
 - `hoi4.gui_inspect`, `hoi4.gui_render`, and `hoi4.gui_rewrite`
-- `hoi4.focus_inspect`, `hoi4.focus_render`, `hoi4.focus_raster`, and `hoi4.focus_rewrite`
+- `hoi4.focus_inspect`, `hoi4.focus_render`, and `hoi4.focus_rewrite`
+
+## Warm workers
+
+Domain tools run in a separate worker process. After a job the worker stays warm for `jobWorkerIdleSeconds` (default 180) and runs its server's next job with the indexes it already loaded, so a second GUI render or decision inspection of a large mod skips the cold scan. An idle worker holds no execution slot, exits when its idle time ends or its server closes, and a worker whose job failed, or whose heap still holds more than 40% of its limit after a job and a full collection, is never reused (the next job starts a fresh worker, so several heavy jobs in a row cannot exhaust one worker's heap). Set `jobWorkerIdleSeconds: 0` to start a fresh worker for every job.
+
+## Results
 
 Task results are exact tool results, including linked artifacts, partial-analysis markers, validation evidence, and tool-level errors.
 A completed tool-level error is therefore a completed task whose result has `isError: true`; an execution or storage failure is a failed task.
@@ -52,12 +59,14 @@ Cancelling an ordinary synchronous call prevents admission when possible and oth
 Closing the originating connection does not cancel an accepted native task.
 
 A worker busy in long synchronous analysis cannot observe its own cancellation, so the server that started it also supervises read-only jobs.
-A read-only job still running `jobCancelGraceSeconds` (default 10) after cancellation is stopped and settles as cancelled.
-A read-only job still running `jobDeadlineSeconds` (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.
+A read-only job still running `jobCancelGraceSeconds` (1–600, default 10) after cancellation is stopped and settles as cancelled.
+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` sets a V8 heap ceiling for each worker; without it, workers use Node's default.
-At most `maxSharedTools` (default 4) workers and expensive calls run at once across every server process that shares a `serverStateRoot`; further work waits for capacity.
+`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.
 If a worker or server stops after that checkpoint, a later authorized process publishes the retained result without rerunning the operation.