hoi4-agent-tools 3.5.1 → 3.7.0

package/dist/hoi4_agent_tools/schemas/reference.js

@@ -26,6 +26,7 @@ export const referenceReadRequestSchema = z
     workspaceId: workspaceIdSchema,
     id: z.string().regex(/^[a-f0-9]{64}$/u),
     revision: z.string().regex(/^[a-f0-9]{64}$/u),
+    source: referenceSourceSchema.optional(),
     startLine: z.number().int().min(1).optional(),
     startColumn: z.number().int().min(1).optional(),
     maxLines: z.number().int().min(1).max(80).default(40),
@@ -39,6 +40,17 @@ export const referenceContextRequestSchema = z
     limit: z.number().int().min(1).max(24).default(16),
 })
     .strict();
+export const sourceKeyPathSchema = z
+    .array(z.union([
+    z
+        .object({
+        key: z.string().min(1).max(1024),
+        occurrence: z.number().int().min(0).max(100_000).optional(),
+    })
+        .strict(),
+    z.object({ index: z.number().int().min(0).max(100_000) }).strict(),
+]))
+    .max(24);
 export const sourceLookupRequestSchema = z
     .object({
     workspaceId: workspaceIdSchema,
@@ -51,6 +63,10 @@ export const sourceLookupRequestSchema = z
     maxDefinitions: z.number().int().min(1).max(3).default(3),
     maxReferences: z.number().int().min(0).max(20).default(10),
     maxLines: z.number().int().min(1).max(80).default(30),
+    keyPath: sourceKeyPathSchema.optional(),
+    view: z.enum(['source', 'structure']).default('source'),
+    maxChildren: z.number().int().min(1).max(40).default(20),
+    childOffset: z.number().int().min(0).max(100_000).default(0),
     fromLine: z.number().int().min(1).optional(),
     fromColumn: z.number().int().min(1).optional(),
     expectedRevision: z
@@ -67,6 +83,7 @@ const coverage = z
     files: count,
     sections: count,
     unavailable: z.boolean(),
+    included: z.boolean(),
 })
     .strict();
 const coverageBySource = z
@@ -90,6 +107,8 @@ export const referenceSearchDataSchema = z
     .object({
     results: z.array(referenceSectionSchema.extend({ score: z.number() })).max(12),
     total: count,
+    omitted: count,
+    limitedByBytes: z.boolean(),
     coverage: coverageBySource,
     skipped: count,
 })
@@ -109,6 +128,7 @@ export const referenceContextDataSchema = z
     surface: referenceSurfaceSchema,
     sections: z.array(referenceSectionSchema).max(24),
     omitted: count,
+    limitedByBytes: z.boolean(),
     omittedSources: z.array(z.string().max(256)).max(32),
     missing: z.array(z.string().max(256)).max(32),
     coverage: coverageBySource,
@@ -117,10 +137,17 @@ export const referenceContextDataSchema = z
     .strict();
 export const sourceLookupDataSchema = z
     .object({
+    sourceScope: z.enum([
+        'workspace_index',
+        'event_definitions',
+        'event_consumers',
+        'helper_definitions',
+    ]),
     revision: hash,
     complete: z.boolean(),
     skippedSourceCount: count,
     definitionCount: count,
+    definitionsTruncated: z.boolean(),
     referencesIncluded: z.boolean(),
     referenceCount: count,
     referencesTruncated: z.boolean(),
@@ -143,6 +170,34 @@ export const sourceLookupDataSchema = z
         nextLine: line.nullable(),
         nextColumn: line.nullable(),
         text: z.string().max(2000),
+        navigation: z
+            .object({
+            keyPath: sourceKeyPathSchema,
+            startLine: line,
+            startColumn: line,
+            endLine: line,
+            endColumn: line,
+            children: z
+                .array(z
+                .object({
+                key: z.string().max(1024).nullable(),
+                index: count,
+                keyTruncated: z.boolean(),
+                occurrence: count,
+                kind: z.enum(['scalar', 'block']),
+                value: z.string().max(120).nullable(),
+                valueTruncated: z.boolean(),
+                startLine: line,
+                endLine: line,
+                childCount: count,
+            })
+                .strict())
+                .max(40),
+            omittedChildren: count,
+            nextChildOffset: count.nullable(),
+        })
+            .strict()
+            .optional(),
     })
         .strict())
         .max(3),

package/dist/hoi4_agent_tools/schemas/script-validation.js

@@ -0,0 +1,69 @@
+import { z } from 'zod/v4';
+import { workspaceIdSchema } from './common.js';
+import { referenceSectionSchema } from './reference.js';
+const scope = z.enum([
+    'country',
+    'state',
+    'character',
+    'combatant',
+    'ace',
+    'strategic_region',
+    'operation',
+    'industrial_org',
+    'purchase_contract',
+    'raid_instance',
+    'special_project',
+    'faction',
+]);
+export const scriptValidateRequestSchema = z
+    .object({
+    workspaceId: workspaceIdSchema,
+    source: z.string().min(1).max(64_000),
+    kind: z.enum(['effect', 'trigger']),
+    scope,
+    documentation: z.enum(['game_doc', 'script_doc']).default('game_doc'),
+    bindings: z
+        .array(z.object({ name: z.string().min(1).max(256), scope }).strict())
+        .max(16)
+        .default([]),
+    limit: z.number().int().min(1).max(32).default(12),
+})
+    .strict();
+export const scriptValidateDataSchema = z
+    .object({
+    valid: z.boolean().nullable(),
+    checksPerformed: z.array(z.enum(['syntax', 'command_kind', 'declared_scope'])),
+    parametersChecked: z.literal(false),
+    documentation: z
+        .object({
+        source: z.enum(['game_doc', 'script_doc']),
+        revision: z.string().regex(/^[a-f0-9]{64}$/u),
+        effectCount: z.number().int().min(0),
+        triggerCount: z.number().int().min(0),
+        skippedSources: z.number().int().min(0),
+    })
+        .strict(),
+    findings: z
+        .array(z
+        .object({
+        code: z.string().max(80),
+        status: z.enum(['supported', 'error', 'unresolved']),
+        command: z.string().max(256),
+        kind: z.enum(['effect', 'trigger']),
+        scope: z.string().max(64),
+        line: z.number().int().min(1),
+        column: z.number().int().min(1),
+        message: z.string().max(500),
+        suggestions: z.array(z.string().max(256)).max(3),
+        reference: referenceSectionSchema.optional(),
+    })
+        .strict())
+        .max(32),
+    totalFindings: z.number().int().min(0),
+    omittedFindings: z.number().int().min(0),
+    checkedCommands: z.number().int().min(0),
+    unresolvedCount: z.number().int().min(0),
+    truncated: z.boolean(),
+    argumentBlocksUnchecked: z.number().int().min(0),
+})
+    .strict();

package/dist/hoi4_agent_tools/version.js

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

package/docs/README.md

@@ -1,20 +1,36 @@
 # Documentation
 
-- [Setup](setup.md): install the server, configure HOI4 paths, and connect an MCP client.
-- [Local references](reference.md): retrieve cited offline wiki and installed documentation sections and exact source definitions.
-- [Event chains](events.md): inspect, trace, lint, render, and compare event chains.
-- [Cross-system impact and decisions](analysis.md): trace source consumers and evaluate decision or mission scenarios.
-- [Mechanic tests and scenario suites](mechanics.md): interpret declared effect steps, check package links, and run resumable cases.
-- [Technology trees](technology.md): inspect, trace, lint, render, and compare technologies and doctrines.
-- [Visual examples and comparison limits](visual-comparisons.md): real game captures beside MCP renders, with measured findings and limits.
-- [Interface examples and comparison limits](https://github.com/klimPaskov/hoi4-agent-tools/blob/main/docs/gui-comparisons.md): native-size vanilla and Chaos Redux windows, populated templates, scenarios, and provenance.
-- [Bounded helper expansion](helper-expansion.md): resume source-linked event and technology helper paths with exact coverage boundaries.
-- [Persistent jobs](jobs.md): run, inspect, cancel, and recover long operations.
-- [AI and MTTH analysis](probability.md): evaluate weighted logic, timing, uncertainty, sequences, and patches.
-- [Focus trees](focus.md): inspect, create, render, and clean national or continuous focus content.
-- [Scripted GUIs](gui.md): inspect linked UI source, render states, and create or repair GUIs.
-- [Maps](map.md): inspect and edit provinces, states, regions, adjacency, supply, and railways.
-- [HTTP](http.md): run the MCP server for shared or remote access.
-- [Development](development.md): build, test, and contribute.
-
-For vulnerability reporting, see the repository [Security Policy](../SECURITY.md).
+Start with [Setup](setup.md), then try the [Examples](examples.md).
+You can ask your coding agent for these tasks in ordinary language; you do not need to memorize tool names.
+
+## Choose a task
+
+| I want to…                                           | Read                                      |
+| ---------------------------------------------------- | ----------------------------------------- |
+| Find a modding rule or a vanilla example             | [Local references](reference.md)          |
+| Work on a focus tree                                 | [Focus trees](focus.md)                   |
+| Understand an event chain                            | [Events](events.md)                       |
+| Trace dependencies or inspect decisions and missions | [Decisions and dependencies](analysis.md) |
+| Preview a technology or doctrine tree                | [Technology trees](technology.md)         |
+| Build or review an interface                         | [Scripted GUIs](gui.md)                   |
+| Inspect or edit the map                              | [Maps](map.md)                            |
+| Compare weights, chances or timing                   | [AI and probability](probability.md)      |
+| Test a mechanic or check a content package           | [Mechanic tests](mechanics.md)            |
+
+## See the results
+
+- [Examples](examples.md): practical prompts with real renders.
+- [Latest release](https://github.com/klimPaskov/hoi4-agent-tools/releases/latest): a short introduction to the published server.
+- [Focus and technology comparisons](visual-comparisons.md): supplied game captures beside source renders.
+- [Interface comparisons](gui-comparisons.md): vanilla and Chaos Redux windows.
+
+## Detailed reference
+
+- [Tool reference](tools.md): tool names and what each one does.
+- [Background jobs](jobs.md): inspect, cancel or retrieve long operations.
+- [Large event and technology queries](helper-expansion.md): follow bounded results without losing coverage.
+- [Remote hosting](http.md): share the server over HTTP.
+- [Development](development.md): build, test and contribute.
+- [Architecture decisions](adr/README.md): implementation rationale for contributors.
+
+For vulnerability reporting, use the [security policy](../SECURITY.md).

package/docs/examples.md

@@ -0,0 +1,75 @@
+# Examples
+
+Start with a task you would normally give your coding agent.
+The agent chooses the MCP tools and opens the resulting images or source references.
+The renders below use actual Chaos Redux and installed HOI4 files; use names from your own mod when trying the prompts.
+
+## Find a rule without reading a whole wiki
+
+> Find the installed documentation for `save_event_target_as`, read the relevant section, and show a vanilla usage. Keep the file and line references.
+
+The reference tools find the section, read a small excerpt, and retain its source revision so the agent can return to it later.
+In the [measured reference example](research/reference-benchmark.md), the search found the installed effect documentation first and a 12-line read supplied the command and supported scopes.
+No wiki download or game launch was needed.
+
+Use [Local references](reference.md) to configure an offline wiki snapshot or narrow a search.
+
+## Review a large tree
+
+> Render the Utopia Manifesto focus tree. Check its branch connections, alternative prerequisites, missing references and crowded areas before suggesting edits.
+
+[![Utopia Manifesto focus tree](images/comparisons/utopia-mcp.png)](images/comparisons/utopia-mcp.png)
+
+Open the image at full size for the complete layout.
+This example contains 124 focuses in the recorded source version.
+The [focus guide](focus.md) covers inspecting, rendering and reorganizing trees.
+
+## Preview technology layouts and artwork
+
+> Render the infantry technology folder using this mod and its installed game assets. Check card sizes, icons, prerequisite links and missing placements.
+
+[![Infantry technology folder](images/comparisons/infantry-mcp.png)](images/comparisons/infantry-mcp.png)
+
+The preview follows the loaded technology and GUI definitions, including wide equipment cards.
+The [technology comparisons](visual-comparisons.md#technology-folders) also show a chemical folder rendered from a matching recorded source revision.
+See the [technology guide](technology.md) for grants, bonuses and doctrine paths.
+
+## Inspect an interface before editing it
+
+> Find the Video options window in the installed interface files. Render it with labelled control regions, then check its text, spacing and clipping.
+
+| Supplied in-game capture                                                  | MCP source preview                                                     |
+| ------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| ![Video options in game](images/comparisons/gui/options-video-ingame.png) | ![Video options preview](images/comparisons/gui/options-video-mcp.png) |
+
+For a mod window, ask for the same view at 100% and 125% UI scale and supply the state values needed by its controls.
+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.
+
+## Locate map data and plan an edit
+
+> Find Brandenburg by name, show it on the map, and inspect its provinces, neighbours and railway connections. Show the affected files before changing anything.
+
+[![Map rendered from installed source](images/comparisons/source/map-mcp.png)](images/comparisons/source/map-mcp.png)
+
+After reviewing the selection, you can ask for a specific change such as moving named provinces into a state or updating a railway path.
+The map tools check connected records and preserve dated state history when the operation can be represented safely.
+See [Maps](map.md) for supported edits.
+
+## Trace an event or compare AI weights
+
+> Trace this event's options and follow-up events. Point out unresolved calls and link each route to its source.
+
+[![Chaos Redux 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.
+
+Use [Events](events.md) for route graphs and [AI analysis](probability.md) for supported weights, chances and timing models.
+A decision score is not automatically a percentage chance of an AI click.
+
+## About these examples
+
+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.

package/docs/gui.md

@@ -2,6 +2,29 @@
 
 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.
 
+## 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.
+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.
+These are source-model results, not proof of native click execution.
+
+## Preview immediate tooltip text
+
+An explicit tooltip request uses a visible element's `pdx_tooltip` localisation key. Supply `tooltip.target` with its inspected instance ID or a unique element name, plus viewport `x`, `y`, `width` and `padding` values.
+
+Position, width and padding are declared viewport pixels; height follows the measured text.
+The preview uses the loaded `ToolTip` sprite and `cg_16b` font.
+Missing or ambiguous targets, hidden or unresolved visibility, missing text/assets, and bounds errors produce diagnostics without a guessed popup.
+A visibly disabled control can still have tooltip text.
+
+Engine-generated `[!element_action]` and `[!element_action_enabled]` descriptions are not invented.
+If their exact text is known, supply the exact bracketed token as a string key in `scenario.values` or `scenario.scriptedGui`; otherwise the tooltip remains unresolved.
+The preview does not establish native automatic positioning, frame composition, delayed timing or `click_to_front` behavior.
+
 ## 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.

package/docs/reference.md

@@ -15,9 +15,50 @@ Only Markdown headings and recognizable standalone names in generated `.log` fil
 ## Tools
 
 - `hoi4.reference_context`: request a surface such as `event`, `focus`, `technology`, `gui`, or `map`. It reserves citations for available installed documentation and offline wiki sources before adding further question matches. Supply `question` to select the best matching section within each required source. At a limit of two or more, both source kinds are represented when available; a one-result limit prioritizes installed documentation. `omittedSources` names required sources excluded by the result limit, while `missing` names sources absent from the configured roots. Increase the limit or search an omitted source directly before treating the bundle as sufficient. Citations are pointers and excerpts; read the pertinent sections before changing code.
-- `hoi4.reference_search`: search page names, headings, exact script tokens, and matching body lines. The default limit is six results and the maximum is twelve. Filter `sources` to `game_doc`, `wiki`, or `script_doc` when appropriate.
-- `hoi4.reference_read`: provide a search/context result's `id` and `revision`. Read up to 80 lines and 8,000 UTF-8 bytes. Continue with the returned `nextLine`, `nextColumn` as `startColumn`, and the same revision. Long source lines continue without losing characters. A changed source returns `REFERENCE_REVISION_STALE`.
+- `hoi4.reference_search`: search page names, headings, exact script tokens, and matching body lines. The default limit is six results and the maximum is twelve. Filter `sources` to `game_doc`, `wiki`, or `script_doc` when appropriate. Only selected authorities are scanned; `coverage.included = false` means that an authority was excluded from this query, not that it is missing.
+- `hoi4.reference_read`: provide a search/context result's `id` and `revision`. Optionally pass its `source` for a focused authority read; resident citations provide this hint automatically. Read up to 80 lines and 8,000 UTF-8 bytes, with JSON escaping also bounded. Continue with the returned `nextLine`, `nextColumn` as `startColumn`, and the same revision. Long source lines continue without losing characters. A changed source returns `REFERENCE_REVISION_STALE`.
 - `hoi4.source_lookup`: find exact definitions and indexed usages in the installed game and configured mod source. The response includes load order, override status, up to three source blocks bounded to 2,000 bytes each, a scan revision, and explicit reference counts and truncation. Follow `nextLine` and `nextColumn` as `fromLine` and `fromColumn`, with `expectedRevision`, to read more of the active definition.
+- `hoi4.script_validate`: check a bounded effect or trigger body against installed native-command documentation. Supply the body in `source`, its `kind`, and its current `scope`. Results cover syntax, command kind, and declared scope, with exact documentation citations. They do not validate command parameters or prove game execution.
+
+## Navigate a definition
+
+Use `view: "structure"` to list the immediate children of the active definition, then pass `keyPath` to select a nested block or scalar assignment.
+Keyed path steps have a `key` and an optional zero-based `occurrence`; repeated keys require an explicit occurrence.
+Use an `{ "index": 1 }` step to select an unkeyed array entry or a child with an unusually long key.
+For example, `[{"key":"option","occurrence":1},{"key":"hidden_effect"}]` selects the second option's hidden effects.
+Navigation reads exact parser boundaries, including when several assignments share a line.
+If an identifier has multiple symbol kinds, supply `kind` before navigating it.
+Override counts remain visible, while navigation selects the active definition.
+
+Structure replies have at most 40 children.
+They also have a byte ceiling, with `keyTruncated` and `valueTruncated` identifying shortened previews.
+Continue with `navigation.nextChildOffset` as `childOffset`, retaining the same `keyPath`, query settings, and `expectedRevision`.
+Source replies continue with `nextLine` and `nextColumn` as before.
+Use `includeReferences: false` with an exact `event`, `scripted_effect`, or `scripted_trigger` kind when only the definition is needed; this limits scanning to that source family.
+Enable references when looking for consumers across the workspace.
+Event-consumer queries scan the source families supported by event reference analysis rather than unrelated presentation files.
+`sourceScope` labels the scanned surface, and `definitionsTruncated` and reference omission fields identify bounded output.
+Revisions describe the selected scan, so keep the scan settings unchanged during continuation.
+
+## Check native commands
+
+`hoi4.script_validate` accepts a standalone effect or trigger body rather than an entire event or focus definition.
+It recognizes documented control wrappers, conditional limits, country/state iterators, fixed country/state scopes, and the `ROOT`, `THIS`, and `PREV` traversal context.
+Use `bindings` to declare external scope names such as `event_target:recipient` when their type is known.
+Those bindings are supplied facts, not observed game state.
+
+The default documentation authority is `game_doc`.
+Use `documentation: "script_doc"` explicitly for a configured generated dump; the checker does not silently mix authorities or substitute wiki text for native signatures.
+It reads supported scopes from `effects_documentation.md`, `triggers_documentation.md`, and corresponding `effect_docs.log`/`trigger_docs.log` files.
+
+`valid: false` identifies a syntax, kind, or scope error.
+`valid: null` identifies missing or conflicting documentation, an unresolved command/helper, an unchecked native argument block, or exhausted coverage.
+`valid: true` applies only to `checksPerformed`; `parametersChecked` remains false.
+Inspect the cited parameter syntax and use the relevant domain tools for broader validation.
+Replies prioritize problems, bound `findings`, and report `omittedFindings`; execution is bounded to 256 visited entries and 64,000 UTF-8 source bytes.
+Search and context replies also report `limitedByBytes` when metadata exceeds their reply budget.
+Read omitted required sources with targeted calls rather than repeatedly requesting the same oversized bundle.
+Reference text supports UTF-8, Windows-1252, and explicitly BOM-marked UTF-16; native engine source encoding rules remain separate.
 
 Example:
 

package/docs/research/reference-benchmark.md

@@ -40,3 +40,44 @@ For the GUI question “Where are scripted GUI click effects and triggers define
 | 8              | Installed documentation and wiki |                        0 |      5,926 |          339 |
 
 The default six-surface context bundles used 3,545–5,556 bytes including omission metadata. A smaller response is not sufficient evidence when `omittedSources` is nonempty: increase the limit or search and read those sources directly. The evaluation script fails when a compact budget drops a required source kind or silently omits its required-source pointers.
+
+## Source navigation and scan measurements
+
+On 2026-10-03, `scripts/evaluate-source-tools.ts --game-only` selected the installed `political.1` definition, listed its options, read exactly `add_political_power = -100` from its first option, and checked that command against installed documentation.
+The country-scope check succeeded and the state-scope check reported the documented mismatch.
+The evaluation retained source and documentation revisions and compared repeated reference results for equality.
+
+| Operation                      | Initial cache-enabled run | Scoped-cache run | Reply bytes |
+| ------------------------------ | ------------------------: | ---------------: | ----------: |
+| Cold event structure           |                 55,550 ms |        24,723 ms |       2,258 |
+| Repeated nested read           |                 20,936 ms |         3,565 ms |         862 |
+| Installed command check        |                  1,471 ms |        10,804 ms |       1,152 |
+| Event-consumer lookup          |   Timed out at 180,002 ms |       145,532 ms |       1,363 |
+| Repeated event-consumer lookup | Not completed in that run |        16,233 ms |       1,363 |
+
+A separate run with persistent caching disabled completed the broader lookup in 102,437 ms and its repeated lookup in 122,023 ms.
+This helped identify filesystem and cache costs; it is not a causal comparison under identical machine load.
+The candidate bounds optional cache writes, skips resident hydration, overlaps source verification, and scopes event queries to the analyser's supported owner sources.
+Its persistent cache recorded 32 writes across two bounded batches, with no invalid entries or evictions.
+The process recorded 616–625 MiB resident memory during the consumer lookups; these are sampled values, not peak-memory guarantees.
+
+Other work was running on the host, and latency varied materially.
+The command-document check was slower in the scoped-cache run, so these measurements must not be presented as an improvement for every operation or as a latency guarantee.
+The selected source index was complete, while reference completeness remained false because 2,379 dynamic references were unresolved.
+Static retrieval does not resolve those engine-dependent dispatches or establish runtime behavior.
+
+These source timings preceded the subsequent batched reference reader and glob-library replacement.
+A separate 2026-10-03 reference evaluation found all nine expected pages and answer-bearing sections and passed all eighteen compact-context cases, with no missing required sources or budget failures.
+Its six context replies used 3,616–5,627 JSON bytes.
+The candidate's complete MCP discovery list contains 35 tools and is tested against a 75 KiB ceiling.
+
+## Worker startup
+
+Five isolated readiness handshakes on 2026-10-03 averaged 2,163 ms with eager imports and 1,408 ms with authenticated domain loading.
+The individual samples were 2,056/2,570/2,349/1,857/1,985 ms and 3,213/930/995/960/942 ms respectively.
+The first changed-worker sample includes a cold TypeScript loader cache.
+These samples measure the readiness handshake without running a job, and do not establish complete request latency or throughput.
+Concurrent HTTP qualification keeps its original four-minute total request ceiling.
+Two earlier 64-request runs exceeded that ceiling for 23 and five requests respectively.
+The isolated run after domain loading passed all 64 requests in a 124.49-second test, including fixture setup and cleanup.
+Shared-host load varied between runs, so these are qualification receipts rather than a controlled throughput comparison.

package/docs/setup.md

@@ -1,50 +1,74 @@
 # Setup
 
-For Codex, the supplied registration allows 120 seconds for startup and 600 seconds per tool call.
-Large source scans and GUI renders can take several minutes; keep selectors and scenario matrices bounded and use negotiated task support when available.
-`tool_timeout_sec` is the per-server tool deadline described in the [official configuration reference](https://developers.openai.com/ja-JP/docs/config-file/config-reference).
+You need a coding agent that supports MCP and Node.js 22.19+ in the Node 22 line, or Node.js 24.
+Keep an installed copy of Hearts of Iron IV available for vanilla references, artwork and fonts.
 
-HOI4 Agent Tools requires Node.js 22.19 or later in the Node 22 line, or Node.js 24.
-
-## Install
+## 1. Install
 
 ```bash
 npm install --global hoi4-agent-tools
 ```
 
-Set the MCP process working directory to the mod being edited. The server creates its local workspace in memory, keeps generated artifacts in the per-user data directory, and starts without a config file. The installed game is detected when available for vanilla references; it is not required for source inspection or offline rendering.
+Source inspection can work without an installed game.
+Previews need the assets and fonts referenced by the mod; missing files are reported in the result.
+
+## 2. Connect your agent
+
+```bash
+hoi4-agent-tools-setup --print-client-config
+```
+
+Copy the printed `globalInstall` configuration into your MCP client, or use `codexTomlGlobal` for a TOML-based Codex configuration.
+The printed command is correct for your platform.
+
+Open the mod as your agent's workspace.
+If your client does not supply workspace roots, set the MCP process working directory to that mod folder.
+The server can then select the active mod without a separate configuration file.
+It keeps indexes and generated images in your user data directory.
 
-When the MCP server starts with its working directory inside a mod, every focus, GUI, map, event, and technology call uses that mod automatically. Configured multi-mod or remote deployments can use explicit workspace selection.
+## 3. Try a small task
 
-Local startup accepts normal descriptor-based mods and sparse descriptor-less mods that contain standard HOI4 content folders. Empty roots need a `descriptor.mod` or an explicit configuration so the server does not guess an unrelated directory.
+> Find the focus trees in this mod and render one of them.
 
-## Optional persistent configuration
+> Find the installed documentation for `save_event_target_as` and read only the relevant section.
 
-Use `--init` only when you need several mod roots, a fixed game path, or a shared/remote process:
+Continue with the [examples guide](examples.md).
+A mod normally has `descriptor.mod` or standard HOI4 content folders; an empty folder needs a descriptor or explicit configuration.
 
-### Configure explicit paths
+## Choose game and mod paths
 
-Use explicit paths when discovery is incomplete or when you want to expose more than one mod root:
+Use explicit paths if automatic discovery cannot find the game, or if you want to configure several mods:
 
 ```bash
-hoi4-agent-tools-setup --init --mod-root /projects/hoi4-mods --mod-root /workshop/hoi4-mods --game-root "/games/Hearts of Iron IV" --workspace-storage-root /var/lib/hoi4-agent-tools
+hoi4-agent-tools-setup --init --mod-root "/projects/hoi4-mods" --game-root "/games/Hearts of Iron IV"
+hoi4-agent-tools-setup --print-client-config
 ```
 
-- `--mod-root PATH` adds a parent folder containing mods. Repeat it for additional locations.
-- `--game-root PATH` selects the installed game folder used for vanilla references.
-- `--workspace-storage-root PATH` selects where indexes, renders, and other generated workspace files are stored.
-- `--config PATH` writes or reads a config at a custom path instead of the default per-user location.
+`--mod-root` is a parent folder containing mod directories, not the game installation.
+It can be repeated for several locations.
+`--game-root` points to the installed game.
+Use quoted Windows paths on Windows, for example `"C:/Program Files (x86)/Steam/steamapps/common/Hearts of Iron IV"`.
 
-The corresponding config fields are `modRoots`, `gameRoot`, and `workspaceStorageRoot`.
+For a custom configuration location, add `--config PATH` to both setup commands.
+`--workspace-storage-root PATH` chooses where generated indexes and images are saved.
+Linked mod directories are not followed; configure their real parent directory instead.
 
-For a configured workspace, `wikiRoot` can select an absolute path to an offline Paradox Wiki snapshot and `scriptDocsRoot` can select an absolute path to a user-supplied generated documentation dump. Without these fields, the reference tools look for `paradox_wiki/` and `script_docs/` inside the mod. See [Local references](reference.md).
+## Add local reference material
 
-Linked directory entries are not followed. If a mod folder is a symlink or junction, configure the real parent directory as another `--mod-root`.
+Place an offline wiki snapshot in `paradox_wiki/` inside the mod.
+An optional generated documentation dump can go in `script_docs/`.
+For a configured workspace, `wikiRoot` and `scriptDocsRoot` can point to other absolute directories.
+The server reads these local files; it does not download the wiki.
+See [Local references](reference.md) for source selection and missing-source reports.
 
-## MCP client registration
+## Common problems
 
-```bash
-hoi4-agent-tools-setup --print-client-config
-```
+| Problem                             | Check                                                                                                                       |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| The agent cannot find a mod         | Open the mod workspace, set the server working directory, or configure its real parent with `--mod-root`.                   |
+| A render lacks icons or fonts       | Confirm `--game-root` and the mod's asset paths. Read the missing-file findings.                                            |
+| A control's state is unresolved     | Supply the scenario's required country, state, controller or variable inputs; do not assume a visible control is available. |
+| A large query takes several minutes | Start with the specific tree, window or source area you need. Use [background jobs](jobs.md) when supported by your client. |
 
-Use the printed `globalInstall` or `codexTomlGlobal` entry. It is platform-correct and uses the default config without an environment variable. For a custom config, add `--config PATH` when printing the registration.
+The supplied Codex registration allows 120 seconds for startup and 600 seconds per tool call.
+For remote or shared deployments, use the [HTTP guide](http.md).

package/docs/tools.md

@@ -0,0 +1,65 @@
+# Tool reference
+
+Most users can ask their agent in ordinary language; the [examples guide](examples.md) is the best starting point.
+This page lists exact tool names for agents and integrations.
+Use the connected server's live schema for the fields accepted by each call.
+
+| Tool                        | Purpose                                                                                      |
+| --------------------------- | -------------------------------------------------------------------------------------------- |
+| `hoi4.focus_inspect`        | Read focus trees, continuous-focus placement, and structural or reference problems.          |
+| `hoi4.focus_render`         | Produce fast HTML, SVG, JSON, and source-linked layout artifacts.                            |
+| `hoi4.focus_raster`         | Produce a PNG preview with decoded source icons.                                             |
+| `hoi4.focus_rewrite`        | Create or update a focus tree.                                                               |
+| `hoi4.gui_inspect`          | Read a scripted GUI and its linked assets and logic.                                         |
+| `hoi4.gui_render`           | Render generated and explicit GUI scenarios, states, resolutions, and layout diagnostics.    |
+| `hoi4.gui_rewrite`          | Create or update a GUI source package.                                                       |
+| `hoi4.map_inspect`          | Search, click, navigate, and inspect the complete rendered map and its linked data.          |
+| `hoi4.map_render`           | Render full-map layers, overlays, names, IDs, coordinates, and source-linked catalogs.       |
+| `hoi4.map_rewrite`          | Create or update states, provinces, IDs, networks, positions, and connected map data.        |
+| `hoi4.reference_context`    | Get compact, cited wiki and installed documentation pointers for a modding surface.          |
+| `hoi4.reference_search`     | Search bounded local documentation sections.                                                 |
+| `hoi4.reference_read`       | Read one revision-bound section, with line continuation.                                     |
+| `hoi4.source_lookup`        | Find exact definitions, overrides, usages, and narrow source blocks.                         |
+| `hoi4.script_validate`      | Check snippet syntax, native command kinds, and declared scopes against local documentation. |
+| `hoi4.event_inspect`        | Scan, trace, explain, lint, or assess event chains and their state flow.                     |
+| `hoi4.event_render`         | Render source-linked event routes, options, timing, state, scope, and unresolved edges.      |
+| `hoi4.event_compare`        | Compare event-chain topology and diagnostics between revisions.                              |
+| `hoi4.impact_inspect`       | Trace symbol and changed-file consumers across source systems and compare proposals.         |
+| `hoi4.decision_inspect`     | Inventory and evaluate decisions or missions under declared scenarios and source changes.    |
+| `hoi4.mechanic_test`        | Execute bounded source effects on a copied declared scenario and check assertions.           |
+| `hoi4.package_check`        | Check declarative package definitions, calls, registrations, assets, and case links.         |
+| `hoi4.scenario_test`        | Run named source and domain cases in resumable, revision-bound batches.                      |
+| `hoi4.job_inspect`          | Inspect durable background work or retrieve its completed tool result.                       |
+| `hoi4.job_cancel`           | Durably request cancellation of authorized background work.                                  |
+| `hoi4.tech_inspect`         | Scan, trace, explain, lint, and assess technology and doctrine systems.                      |
+| `hoi4.tech_render`          | Render source layouts with real item sizes and year guides, plus dependencies and assets.    |
+| `hoi4.tech_compare`         | Compare technology graphs, placements, references, diagnostics, and source overlays.         |
+| `hoi4.probability_inspect`  | Locate weighted logic and discover compatible adapters, candidates, and required inputs.     |
+| `hoi4.probability_evaluate` | Evaluate supported weights, probability and timing models, and missing inputs.               |
+| `hoi4.probability_sweep`    | Find sensitivity, breakpoints, cliffs, and rank reversals across declared ranges.            |
+| `hoi4.probability_simulate` | Run deterministic sampled analysis with confidence and convergence data.                     |
+| `hoi4.probability_sequence` | Analyze declared recovery, caps, cooldowns, resets, timers, and terminal states.             |
+| `hoi4.probability_compare`  | Attribute AI-weight and MTTH changes between real or proposed source.                        |
+| `hoi4.probability_render`   | Render cached rankings, matrices, timing, sensitivity, sequence, and comparisons.            |
+
+## Reading results
+
+Inspect findings and missing inputs along with the image or result.
+A rendered control does not by itself prove native availability, and a source simulation is not a game-engine receipt.
+For reference searches, retain the cited file, lines and revision so you can reopen the same section.
+
+Large results are returned as linked `hoi4-agent://` resources.
+Follow `continuationUri` until it is `null`; clients can also request byte ranges with `?offset=<bytes>&length=<bytes>`.
+Archive images you need to keep rather than relying on temporary server storage.
+
+## Longer operations
+
+Clients that negotiate MCP tasks can retrieve a long operation after reconnecting.
+Other clients receive the ordinary synchronous result.
+Use `hoi4.job_inspect` to inspect an authorized job or retrieve its result, and `hoi4.job_cancel` to request cancellation.
+See [Background jobs](jobs.md) for request keys, cancellation and recovery.
+
+## Optional ChaosX tools
+
+Setting `HOI4_AGENT_TOOLS_CHAOSX=1` on the server process exposes `chaosx.focus_country_assets` and `chaosx.visual_revision`.
+These workflow-specific tools are absent from the default public list.