hoi4-agent-tools 3.10.0 → 4.0.0

package/docs/development.md

@@ -7,7 +7,7 @@ npm ci
 npm run check
 ```
 
-`npm run check` runs formatting, type checks, tests, fixture checks, schema generation checks, build checks, and package validation. Use narrower commands during iteration:
+`npm run check` runs formatting, lint, type checks, tests, fixture checks, schema generation checks, build checks, package validation, and MCP Registry metadata validation. Use narrower commands during iteration:
 
 ```bash
 npm run test
@@ -23,7 +23,7 @@ The event-chain acceptance fixture contains more than 300 project-owned event de
 
 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.
 
-`npx vitest run tests/integration/mcp-concurrent-workloads.test.ts` tests simultaneous production calls across all six domains over six HTTP sessions and four independent stdio processes, including artifact retrieval and queued cancellation. Execution limits and connection behavior are described in [HTTP](http.md) and the [concurrency decision](https://github.com/klimPaskov/hoi4-agent-tools/blob/main/docs/adr/0026-concurrent-request-execution.md).
+`npx vitest run tests/integration/mcp-concurrent-workloads.test.ts` tests simultaneous production calls across the tool domains over six HTTP sessions and four independent stdio processes, including artifact retrieval and queued cancellation. Execution limits and connection behavior are described in [HTTP](http.md) and the [concurrency decision](https://github.com/klimPaskov/hoi4-agent-tools/blob/main/docs/adr/0026-concurrent-request-execution.md).
 
 Persistent-job qualification covers authenticated record publication, request-key conflicts, read-result checkpoints, transaction-journal reconciliation, stopped-owner takeover, native task negotiation, ordinary-call parity, reconnect isolation, rewrite cancellation before source application, and fixed-entry worker execution. The public lifecycle contract is documented in [Persistent jobs and MCP tasks](jobs.md).
 
@@ -39,8 +39,30 @@ npm run test:local
 
 Add `HOI4_DEPENDENCY_ROOTS` as the platform path-delimited list when the external mod has dependencies. Local tests remain read-only.
 
+`tests/integration/mcp-stdio-smoke.test.ts` starts the real `src/bin/stdio.ts` entry point and calls every exposed tool once with the argument shape an agent sends, then once with a deliberately wrong field.
+Each success must be a non-error `ok` result whose inline structured content stays under 40 KB, and each wrong call must be a `INVALID_ARGUMENTS` tool error that names the field and shows a working example.
+The suite also builds a world with `create_world`, splits and merges a state with `create_state` and `merge_states`, repairs script references with `remap_map_references`, and load-checks the resulting `definition.csv`, state, strategic region, supply and railway files independently of the server's own validator.
+`tests/local/mcp-stdio-smoke.test.ts` repeats the read-only calls against the installed game (through an empty mod) and the external mod above; set `HOI4_SMOKE_REPORT` to a file path to receive the per-tool coverage table with timings.
+Set `HOI4_SMOKE_STDIO_ENTRY` to the absolute `dist/bin/stdio.js` path in a clean tarball installation to test the packaged server instead of the TypeScript source. Rewrites receive invalid inputs on the real mod; successful writes are exercised only on synthetic fixtures.
+`npm run benchmark:cold` times the slow first calls (`hoi4.mod_index`, an event lint and a decision inventory) of a real mod in a fresh server process and again in a second process on the same state folder; the maintainer checklist for tagging a release is `docs/RELEASING.md` in the repository.
+
 The installed-game qualification also parses every shipped bitmap-font descriptor, resolves every atlas page, shapes native and enlarged glyphs, verifies deterministic raster output, and checks HOI4 localisation colours across base fonts and language overrides.
 
+## Adding a known mistake
+
+`src/hoi4_agent_tools/reference/known-mistakes.json` is the reviewed list behind `known_mistakes` in `hoi4.script_validate`, the `knownMistakes` of `hoi4.reference_context`, and the `knownMistake` of `hoi4.error_log`.
+It is not written at run time: a mistake enters it through a commit.
+
+1. Find the mistake in the offline wiki, the game documentation, or a reproduced `error.log` message, and note the page, heading and item.
+   A rule without a source is not accepted.
+2. Add the rule: a unique snake_case `id`, `severity` (`error` when the definition cannot work, `warning` otherwise), the `surfaces` it belongs to, a `title`, the `mistake`, its `symptom`, the `fix`, the `sources`, and, when the game logs a fixed message, a `logPattern` regular expression.
+3. Add the detector with the same id in `known-mistakes.ts`, working on the parsed file, and the families it applies to.
+   `tests/unit/known-mistakes.test.ts` fails when a rule has no detector or a detector has no rule; add a case that flags the mistake and one that accepts the corrected script.
+4. When the rule is written from a recurring `error.log` pattern, run `hoi4.error_log` first: its `patterns` show the shapes, and the new `logPattern` makes later logs name the fix.
+
+When the game fixes the behaviour, or the rule turns out to be wrong, set `status` to `resolved` and add `resolution` with the date and the reason, and leave the entry in the file.
+A resolved rule is not applied and its detector is skipped; deleting it would lose why it was removed.
+
 See the package [Security Policy](../SECURITY.md) for private vulnerability reporting.
 
 ## Dependencies

package/docs/events.md

@@ -6,6 +6,8 @@ Use the three event tools directly from the target mod.
 
 ## Inspect
 
+A selector may also be a plain string: an event ID such as `my_mod.12`, a namespace such as `my_mod`, or a file path such as `events/my_events.txt`. An object without `kind` is read the same way from its `eventId`, `namespace`, `path` and `line` fields.
+
 `hoi4.event_inspect` provides eight focused modes:
 
 - `scan`: inventory event definitions, namespaces, call sites, and unresolved references.
@@ -40,6 +42,11 @@ Selectors use one of these forms:
 
 `impact` requires an `impactSubject` object with `kind` and `name`. Allowed impact kinds are `event`, `helper`, `flag`, `variable`, `array`, `event_target`, and `saved_scope`. Set `refresh: true` after source changes when a prior graph may be cached.
 
+`maxDepth` defaults to 8 (range 1 to 64), `maxNodes` defaults to 500 (range 1 to 5,000), and `maxEdges` defaults to 2,000 (range 1 to 20,000).
+`direction` defaults to `both`.
+`expandHelpers` defaults to `true` for `explain_path` and `false` for the other modes.
+`refresh` defaults to `true` for `scan` and `false` for the other modes.
+
 Example `hoi4.event_inspect` arguments:
 
 ```json
@@ -55,6 +62,19 @@ Example `hoi4.event_inspect` arguments:
 }
 ```
 
+Example `explain_path` arguments, which explain the route from one event to another:
+
+```json
+{
+  "mode": "explain_path",
+  "from": { "kind": "event", "eventId": "my_namespace.1" },
+  "to": { "kind": "event", "eventId": "my_namespace.5" },
+  "maxDepth": 8
+}
+```
+
+`from` and `to` accept any selector form and are both required in this mode.
+
 ## Render
 
 `hoi4.event_render` produces deterministic, source-linked views of a chain. The exact `view` values are `overview`, `neighborhood`, `options`, `entries`, `reachability`, `timing`, `state`, `targets`, `scope`, `terminals`, and `unresolved`. JSON is the authoritative graph; SVG and PNG provide visual review, with HTML available for bundled navigation when requested.
@@ -63,6 +83,9 @@ Large overview requests return a compact overview plus bounded branch JSON/SVG/P
 
 Dynamic and meta-generated targets that cannot be resolved statically remain explicit unresolved edges. The renderer never invents a destination.
 
+`maxDepth` defaults to 4 (range 1 to 64) and `maxNodes` defaults to 120 (range 1 to 240).
+`direction` defaults to `both`, and `expandHelpers`, `includeHtml`, and `refresh` default to `false`.
+
 Example `hoi4.event_render` arguments:
 
 ```json
@@ -80,16 +103,17 @@ Example `hoi4.event_render` arguments:
 
 ## Compare
 
-`hoi4.event_compare` compares whole workspace event graphs. `before` and `after` each accept exactly one graph reference: `{ "revision": "<sha256>" }` or `{ "artifactUri": "hoi4-agent://..." }`. If no reference or overlay is supplied, the tool compares the previous cached revision with a fresh scan of the current source and reports an error when no prior revision is available. Comparisons refresh current source by default so normal agent file edits are detected; set `refresh: false` only when intentionally comparing cached graphs.
+`hoi4.event_inspect` with `mode: compare` compares whole workspace event graphs. `before` and `after` each accept exactly one graph reference: `{ "revision": "<sha256>" }` or `{ "artifactUri": "hoi4-agent://..." }`. If no reference or overlay is supplied, the tool compares the previous cached revision with a fresh scan of the current source and reports an error when no prior revision is available. Comparisons refresh current source by default so normal agent file edits are detected; set `refresh: false` only when intentionally comparing cached graphs.
 
 Set `selector` to an event, namespace, file, source location, node, or manifest to view the downstream chain in both revisions. `maxChainNodes` bounds each traversal, defaults to 1,000, and reports `selectionTruncated` when the chain exceeds the boundary. The artifact retains the full comparison and graph hashes, and its `selection` reports selected, omitted, and unattributed changes explicitly. Diagnostics without a chain owner remain unattributed. The rendered view uses the selected changed nodes.
 
 Alternatively, compare the current graph with `proposedSources`, an in-memory list of `{ relativePath, source, expectedSourceHash? }` overlays. Set `source` to a string to add or replace source, or to `null` to delete an existing mod source. `after` and `proposedSources` are mutually exclusive. Proposed sources are analyzed without being written. The result reports added, removed, and changed definitions, edges, options, state operations, diagnostics, and route reachability.
 
-Example `hoi4.event_compare` arguments:
+Example `hoi4.event_inspect` comparison arguments:
 
 ```json
 {
+  "mode": "compare",
   "proposedSources": [
     {
       "relativePath": "events/example.txt",
@@ -114,6 +138,6 @@ A coding agent can combine the viewer with repository instructions, skills, and
 2. use `trace`, `explain_path`, `state_flow`, or `impact` for the current task;
 3. read linked JSON evidence only when the compact summary is insufficient;
 4. edit event source with the agent's normal file-editing workflow;
-5. call `hoi4.event_compare`, `lint`, and `hoi4.event_render` to review the result; comparison refreshes the edited source by default.
+5. call `hoi4.event_inspect` with `mode: compare` and `lint`, then `hoi4.event_render` to review the result; comparison refreshes the edited source by default.
 
 Static analysis cannot prove runtime conditions, random outcomes, delayed scheduling, or arbitrary meta-generated text. Those limits are reported in diagnostics and artifacts rather than hidden or guessed. The server never launches or captures Hearts of Iron IV.

package/docs/examples.md

@@ -2,7 +2,7 @@
 
 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 actual Chaos Redux and installed HOI4 files; use names from your own mod when trying the prompts.
+The renders below use real mod and installed HOI4 files; use names from your own mod when trying the prompts.
 
 ## Find a rule without reading a whole wiki
 
@@ -31,7 +31,7 @@ The [focus guide](focus.md) covers inspecting, rendering and reorganizing trees.
 [![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](visual-comparisons.md#technology-folders) also show a mod folder with wide equipment cards rendered from a matching recorded source revision.
+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
@@ -44,7 +44,7 @@ See the [technology guide](technology.md) for grants, bonuses and doctrine paths
 
 For a mod window, ask for the same view at 100% and 125% UI scale and supply the state values needed by its controls.
 Unknown state values must stay unresolved; a visible button alone does not establish that it is enabled in the game.
-The [interface gallery](gui-comparisons.md) includes Škoda Priority, Chaos Redux Settings, Event Log, Chaos Meter, decisions and occupation views.
+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
 
@@ -60,7 +60,7 @@ See [Maps](map.md) for supported edits.
 
 > Trace this event's options and follow-up events. Point out unresolved calls and link each route to its source.
 
-[![Chaos Redux event options](images/comparisons/source/event-chain-mcp.png)](images/comparisons/source/event-chain-mcp.png)
+[![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.
 
@@ -71,5 +71,5 @@ A decision score is not automatically a percentage chance of an AI click.
 
 The images are source previews, not recordings of the server running the game.
 Supplied game screenshots are identified separately and published with permission.
-The [comparison pages](visual-comparisons.md) and [interface gallery](gui-comparisons.md) keep source details, reproducible inputs and known differences alongside the images.
-The package does not include HOI4 or Chaos Redux source files or artwork.
+The [comparison pages](https://github.com/klimPaskov/hoi4-agent-tools/blob/main/docs/visual-comparisons.md) and [interface gallery](https://github.com/klimPaskov/hoi4-agent-tools/blob/main/docs/gui-comparisons.md) keep source details, reproducible inputs and known differences alongside the images.
+The package does not include HOI4 or mod source files or artwork.

package/docs/focus.md

@@ -1,6 +1,6 @@
 # Focus trees
 
-Use `hoi4.focus_inspect`, `hoi4.focus_render`, `hoi4.focus_raster`, and `hoi4.focus_rewrite` for national focus trees and continuous focus palettes.
+Use `hoi4.focus_inspect`, `hoi4.focus_render`, and `hoi4.focus_rewrite` for national focus trees and continuous focus palettes.
 
 ## Create a tree
 
@@ -14,7 +14,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 +129,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 +146,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 +173,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

@@ -6,7 +6,7 @@ Use `hoi4.gui_inspect`, `hoi4.gui_render`, and `hoi4.gui_rewrite` for `.gui`, `.
 
 > 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.
@@ -112,7 +112,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 +164,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 +189,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 +243,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

@@ -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.