hoi4-agent-tools 3.4.1 → 3.5.0

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

@@ -4,7 +4,7 @@ import { workspaceIdSchema } from './common.js';
 function compact(schema, description) {
     return z.unknown().describe(description).pipe(schema);
 }
-const nestedSource = compact(probabilitySourceSchema, 'Source selector or proposed source.');
+const nestedSource = compact(probabilitySourceSchema, 'Source selector; snapshotPath binds frozen bytes to path with expectedSourceHash.');
 const nestedScenarios = compact(probabilityScenarioSetSchema, 'Explicit world-state scenarios.');
 const nestedManifest = compact(customWeightedPoolManifestSchema, 'Declared custom weighted pool and state transitions.');
 const nestedRenderFilter = compact(probabilityRenderFilterSchema, 'Optional scenario, candidate, metric, diagnostic, source, and page filter.');

package/dist/hoi4_agent_tools/schemas/probability.js

@@ -1,6 +1,7 @@
 import { z } from 'zod/v4';
-import { diagnosticSchema, sourceLocationSchema, workspaceIdSchema } from './common.js';
+import { diagnosticSchema, sourceLocationSchema, workspaceIdSchema, workspaceRelativePathSchema, } from './common.js';
 import { artifactLinkSchema } from './transaction.js';
+import { ConditionControlMapSchema } from '../core/condition-schema.js';
 export const probabilityAdapterIdSchema = z.enum([
     'event_mean_time_to_happen',
     'event_option_ai_chance',
@@ -145,6 +146,7 @@ export const probabilityScenarioSchema = z
     prevalence: z.number().min(0).max(1).optional(),
     actor: z.string().max(256).optional(),
     date: z.string().max(64).optional(),
+    controls: ConditionControlMapSchema.optional(),
     state: z.record(z.string().min(1).max(1024), scenarioValueSchema),
     flags: z.array(z.string().min(1).max(512)).max(100_000).optional(),
     eventTargets: z.record(z.string().max(512), z.string().max(512)).optional(),
@@ -257,10 +259,12 @@ export const probabilityDiagnosticThresholdsSchema = z
 })
     .strict();
 export const probabilitySamplingMethodSchema = z.enum(['latin_hypercube', 'pseudo_random']);
+const probabilitySourcePathSchema = workspaceRelativePathSchema.refine((value) => !/[:*?[\]{}!]/u.test(value), 'Source path must be an exact workspace-relative file path');
 export const probabilitySourceSchema = z
     .object({
     identifier: z.string().min(1).max(1024).optional(),
-    path: z.string().min(1).max(1024).optional(),
+    path: probabilitySourcePathSchema.optional(),
+    snapshotPath: probabilitySourcePathSchema.optional(),
     line: z.number().int().min(1).optional(),
     inlineClausewitz: z.string().max(16_777_216).optional(),
     virtualPatch: z.string().max(16_777_216).optional(),
@@ -270,6 +274,26 @@ export const probabilitySourceSchema = z
         .optional(),
 })
     .strict()
+    .superRefine((value, context) => {
+    if (value.snapshotPath === undefined)
+        return;
+    if (value.path === undefined || value.expectedSourceHash === undefined)
+        context.addIssue({
+            code: 'custom',
+            message: 'snapshotPath requires the logical source path and expectedSourceHash of the frozen bytes',
+        });
+    if (value.inlineClausewitz !== undefined || value.virtualPatch !== undefined)
+        context.addIssue({
+            code: 'custom',
+            message: 'snapshotPath cannot be combined with inline source or a virtual patch',
+        });
+    if (value.path !== undefined && !workspaceRelativePathSchema.safeParse(value.path).success)
+        context.addIssue({
+            code: 'custom',
+            path: ['path'],
+            message: 'Snapshot logical source path must be workspace-relative',
+        });
+})
     .refine((value) => value.identifier !== undefined ||
     value.path !== undefined ||
     value.inlineClausewitz !== undefined ||

package/dist/hoi4_agent_tools/schemas/reference.js

@@ -0,0 +1,160 @@
+import { z } from 'zod/v4';
+import { workspaceIdSchema } from './common.js';
+export const referenceSourceSchema = z.enum(['game_doc', 'wiki', 'script_doc']);
+export const referenceSurfaceSchema = z.enum([
+    'general',
+    'event',
+    'decision',
+    'idea',
+    'focus',
+    'technology',
+    'gui',
+    'map',
+    'localisation',
+    'ai',
+]);
+export const referenceSearchRequestSchema = z
+    .object({
+    workspaceId: workspaceIdSchema,
+    query: z.string().trim().min(2).max(160),
+    sources: z.array(referenceSourceSchema).min(1).max(3).optional(),
+    limit: z.number().int().min(1).max(12).default(6),
+})
+    .strict();
+export const referenceReadRequestSchema = z
+    .object({
+    workspaceId: workspaceIdSchema,
+    id: z.string().regex(/^[a-f0-9]{64}$/u),
+    revision: z.string().regex(/^[a-f0-9]{64}$/u),
+    startLine: z.number().int().min(1).optional(),
+    startColumn: z.number().int().min(1).optional(),
+    maxLines: z.number().int().min(1).max(80).default(40),
+})
+    .strict();
+export const referenceContextRequestSchema = z
+    .object({
+    workspaceId: workspaceIdSchema,
+    surface: referenceSurfaceSchema,
+    question: z.string().trim().min(2).max(160).optional(),
+    limit: z.number().int().min(1).max(24).default(16),
+})
+    .strict();
+export const sourceLookupRequestSchema = z
+    .object({
+    workspaceId: workspaceIdSchema,
+    symbol: z.string().trim().min(1).max(256),
+    kind: z
+        .string()
+        .regex(/^[a-z][a-z0-9_]{0,63}$/u)
+        .optional(),
+    includeReferences: z.boolean().default(true),
+    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),
+    fromLine: z.number().int().min(1).optional(),
+    fromColumn: z.number().int().min(1).optional(),
+    expectedRevision: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .optional(),
+})
+    .strict();
+const hash = z.string().regex(/^[a-f0-9]{64}$/u);
+const line = z.number().int().min(1);
+const count = z.number().int().min(0);
+const coverage = z
+    .object({
+    files: count,
+    sections: count,
+    unavailable: z.boolean(),
+})
+    .strict();
+const coverageBySource = z
+    .object({ game_doc: coverage, wiki: coverage, script_doc: coverage })
+    .strict();
+export const referenceSectionSchema = z
+    .object({
+    id: hash,
+    revision: hash,
+    source: referenceSourceSchema,
+    title: z.string().max(512),
+    heading: z.string().max(512),
+    path: z.string().max(4096),
+    startLine: line,
+    endLine: line,
+    excerpt: z.string().max(300),
+    authority: z.string().max(80),
+})
+    .strict();
+export const referenceSearchDataSchema = z
+    .object({
+    results: z.array(referenceSectionSchema.extend({ score: z.number() })).max(12),
+    total: count,
+    coverage: coverageBySource,
+    skipped: count,
+})
+    .strict();
+export const referenceReadDataSchema = referenceSectionSchema
+    .extend({
+    sectionStartLine: line,
+    sectionEndLine: line,
+    startColumn: line,
+    text: z.string().max(8000),
+    nextLine: line.nullable(),
+    nextColumn: line.nullable(),
+})
+    .strict();
+export const referenceContextDataSchema = z
+    .object({
+    surface: referenceSurfaceSchema,
+    sections: z.array(referenceSectionSchema).max(24),
+    omitted: count,
+    missing: z.array(z.string().max(256)).max(32),
+    coverage: coverageBySource,
+    skipped: count,
+})
+    .strict();
+export const sourceLookupDataSchema = z
+    .object({
+    revision: hash,
+    complete: z.boolean(),
+    skippedSourceCount: count,
+    definitionCount: count,
+    referencesIncluded: z.boolean(),
+    referenceCount: count,
+    referencesTruncated: z.boolean(),
+    referencesComplete: z.boolean(),
+    unresolvedReferenceCount: count,
+    definitions: z
+        .array(z
+        .object({
+        kind: z.string().max(64),
+        id: z.string().max(1024),
+        path: z.string().max(4096),
+        rootKind: z.string().max(32),
+        loadOrder: count,
+        overridden: z.boolean(),
+        sourceShadowed: z.boolean(),
+        startLine: line.nullable(),
+        endLine: line.nullable(),
+        fromLine: line.nullable(),
+        toLine: line.nullable(),
+        nextLine: line.nullable(),
+        nextColumn: line.nullable(),
+        text: z.string().max(2000),
+    })
+        .strict())
+        .max(3),
+    references: z
+        .array(z
+        .object({
+        kind: z.string().max(64),
+        from: z.string().max(1024),
+        toKind: z.string().max(64),
+        path: z.string().max(4096),
+        line: line.nullable(),
+    })
+        .strict())
+        .max(20),
+})
+    .strict();

package/dist/hoi4_agent_tools/technology/render.js

@@ -744,10 +744,15 @@ function svgFor(titleText, positioned, edges, sourceAccurate, iconDataUris, spri
                 ? undefined
                 : (iconDataUris[preferredSprite] ?? iconDataUris[node.itemBackgroundSprite]);
             const icon = node.iconSprite === undefined ? undefined : iconDataUris[node.iconSprite];
-            const iconSize = node.layoutSize === 'small' ? 62 : 70;
+            const nativeIconSize = node.layoutSize === 'large' && node.iconSprite !== undefined
+                ? spriteDimensions[node.iconSprite]
+                : undefined;
+            const fallbackIconSize = node.layoutSize === 'small' ? 62 : 70;
+            const iconWidth = nativeIconSize?.width ?? fallbackIconSize;
+            const iconHeight = nativeIconSize?.height ?? fallbackIconSize;
             const center = node.iconPosition ?? { x: node.width / 2, y: node.height / 2, centered: true };
-            const iconX = node.x + center.x - (center.centered ? iconSize / 2 : 0);
-            const iconY = node.y + center.y - (center.centered ? iconSize / 2 : 0);
+            const iconX = node.x + center.x - (center.centered ? iconWidth / 2 : 0);
+            const iconY = node.y + center.y - (center.centered ? iconHeight / 2 : 0);
             const name = node.namePosition ?? { x: 3, y: -3, maxWidth: node.width - 6 };
             const labelWidth = Math.min(name.maxWidth ?? node.width - 6, node.width - name.x - 3);
             let fittedLabel = node.label;
@@ -767,7 +772,7 @@ function svgFor(titleText, positioned, edges, sourceAccurate, iconDataUris, spri
                 : `<image data-item-background-sprite="${escapeXml(preferredSprite)}" href="${escapeXml(itemSkin)}" x="${node.x}" y="${node.y}" width="${node.width}" height="${node.height}" preserveAspectRatio="none"/>`;
             const iconSvg = icon === undefined
                 ? ''
-                : `<image href="${escapeXml(icon)}" x="${iconX}" y="${iconY}" width="${iconSize}" height="${iconSize}" preserveAspectRatio="xMidYMid meet"/>`;
+                : `<image data-tech-icon-sprite="${escapeXml(node.iconSprite)}" href="${escapeXml(icon)}" x="${iconX}" y="${iconY}" width="${iconWidth}" height="${iconHeight}" preserveAspectRatio="xMidYMid meet"/>`;
             const designTeamSprite = node.designTeamIcon?.sprite;
             const designTeamImage = designTeamSprite === undefined ? undefined : iconDataUris[designTeamSprite];
             const designTeamSize = designTeamSprite === undefined ? undefined : spriteDimensions[designTeamSprite];

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.4.1';
+export const PACKAGE_VERSION = '3.5.0';
 export const MCP_PROTOCOL_VERSION = LATEST_PROTOCOL_VERSION;
 export const CONFIG_VERSION = 1;
 export const TRANSACTION_VERSION = 1;

package/docs/README.md

@@ -1,10 +1,13 @@
 # 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.

package/docs/gui.md

@@ -33,6 +33,12 @@ Inspection checks missing assets and localisation, invalid sizes, overlap, clipp
 
 For source comparisons, pass `sourceBaseline: { "relativePath": "interface/example.gui", "source": "..." }` to `hoi4.gui_render`. The tool renders that mod-owned `.gui` text and the current source with the same requested scenario, and returns source-baseline and source-comparison PNGs plus a JSON report with source revisions and pixel deltas. `comparisonScenario` remains the separate comparison between two scenarios on the current source.
 
+GUI scenarios accept `date` in `YYYY.M.D` or `YYYY-MM-DD` form and `controls` as a map from state IDs to controller tags, for example `{"date":"1944.10.1","country":{"tag":"GER"},"controls":{"87":"GER","88":"GER"}}`. Date and controller facts reach the shared condition evaluator, including `controls_state` and `is_controlled_by` in declared state scopes. An absent state-controller fact remains unresolved. These fields are explicit scenario assumptions; they do not prove a live campaign's state or engine execution.
+
+A requested root window uses its source `show_position` when present. This is the settled visible endpoint, so native windows whose ordinary `position` is offscreen can be inspected as open panels. The static render does not claim to reproduce the engine's transition animation.
+
+Explicit native list rows resolve their entry template in the owning GUI file before considering a shared template, so reused names in unrelated vanilla windows do not select the wrong layout. One-column native grids with a one-pixel slot height stack entries by their rendered heights. Scenario `.text` overrides can name installed localisation keys even when those keys do not appear literally in the selected GUI source. For dimensions normally supplied by engine code, provide `values["element.width"]` or `values["element.height"]` in native UI pixels and record the source or declared-state basis for those values.
+
 The renderer resolves sprites and fonts through the complete mod, dependency, and installed-game load order. Mod windows therefore render ordinary vanilla sprites, tiled vanilla panels, progress bars, masked shields, button frames, country flags, and localisation icons such as `£command_power` without copying game assets into the mod. Case differences in GFX and font identifiers do not prevent a valid asset from resolving.
 
 Bitmap text uses the language-appropriate HOI4 font definition and its real glyph atlas. Header, serif, compact, typewriter, black, inverted, and other declared faces keep their own glyph shapes, native metrics, face colour, border colour, language override, and font-specific `textcolors` palette. The renderer reads BMFont channel roles, separates face and outline coverage, and recognizes both vanilla black-on-white masks and conventional white-on-transparent custom masks. HOI4 localisation colour runs such as `§Y` and `§R` therefore colour the glyph face while retaining its sharp antialiasing and declared border instead of flattening the glyph into a blurred monochrome mask or switching to the tool font. The default language uses the base font rather than an unrelated language override, and the renderer recognizes installed-game atlases whose filename omits a page suffix declared by the matching `.fnt` file.

package/docs/map.md

@@ -82,3 +82,11 @@ Set `collision` to `reject` to require an unused destination. Set `renameLocalis
 `hoi4.map_rewrite` also moves and merges states, moves provinces between strategic regions, merges or removes provinces, changes province definitions and types, adds or removes normal and special adjacency, and updates supply, railway, building, unit, weather, and entity-locator records. Send one ordered operation list when several connected changes belong together.
 
 Every rewrite returns changed-area, changed-ID, semantic, affected-file, diagnostic, and rendered comparison evidence. A failed operation does not leave a partial multi-file result.
+
+## Dated state history
+
+Map inspection reads active `common/bookmarks/*.txt` sources and uses the earliest valid bookmark date as the state-history basis. Supported owner, controller, core, claim, victory-point, and building commands in earlier dated blocks contribute to the inspected state and its rendered owner or controller layer. If no bookmark date is available, dated state fields retain their direct values and inspection reports `MAP_STATE_DATED_HISTORY_UNRESOLVED`.
+
+Map rewrites preserve dated source blocks byte-for-byte. An update to a field overridden by an applicable dated block returns `MAP_DATED_STATE_HISTORY_CONFLICT`. Province membership changes also block when a dated victory point or building entry would need remapping. Splitting or merging a source state with dated history returns `MAP_DATED_STATE_DISTRIBUTION_UNSUPPORTED`, because copying or deleting that history would change its later meaning. A direct edit with only later dated changes may proceed; those later commands remain and can supersede the direct value at later bookmarks. Edit the dated source deliberately when that later behavior is the intended change.
+
+`floating_harbor` placement rows differ from fixed `naval_base_spawn` ports. Their XYZ coordinates normally identify a sea placement, while the final numeric field names a land target. The map catalog does not count floating-harbor placements as starting naval-base locators. A missing or non-land target is an error. An off-sea position or an unusual state/coastal association is a review warning because those patterns also occur in installed vanilla map data; the warning retains the exact source line.

package/docs/probability.md

@@ -18,6 +18,9 @@ All seven tools are read-only. Proposed source is parsed in memory and never wri
 
 Pass a source without an adapter when the surface type is not yet known. Inspection returns every compatible adapter, candidate counts, and example candidate IDs; its discovery artifact includes every candidate ID and source location. If a requested adapter, identifier, or candidate pool does not match the source, inspection returns the same discovery result with an explanation and suggested adapter instead of `PROBABILITY_SURFACE_EMPTY`.
 
+Source request paths are exact workspace-relative files, such as `common/decisions/example.txt`.
+The `mod:`, `game:`, and `dependency-N:` labels in returned source citations identify origins; they are not part of a probability request's `source.path`.
+
 For a selected source, `hoi4.probability_inspect` includes missing source-condition fields in compact `requiredInputPaths`, adapter-wide completeness flags in `adapterRequiredInputPaths`, and the full candidate catalog, source provenance, and per-candidate requirements in its JSON resource. Unsupported source constructs remain unresolved evidence rather than being presented as scenario inputs. Evaluation reports eligible, excluded, and unresolved candidate counts inline; the resource preserves each candidate's exact eligibility and unresolved reasons for every scenario.
 
 Evaluation, sweep, simulation, and source comparison also accept an omitted adapter. When a source selector identifies one unambiguous weighted surface, the analyzer selects that source-backed adapter automatically. If a caller supplies a mismatched adapter or `custom_weighted_pool` for a source-backed request, the analyzer corrects it when the source has exactly one match. `customPoolManifest`, `beforeManifest`, and `afterManifest` use the custom-pool adapter automatically; `PROBABILITY_SURFACE_EMPTY` is reserved for sources with no weighted surface, while genuinely multi-adapter sources ask the caller to narrow by identifier or line.
@@ -94,6 +97,8 @@ Focus, technology, and doctrine probabilities require a complete candidate pool.
 
 Decision and mission adapters intentionally return scores and ranks without inventing normalized probabilities. Event-option and `random_list` adapters normalize only their complete local pools. Direct random remains an independent percentage. MTTH horizon chance uses the versioned game timing model and returns a bound when an inactive-to-active polling phase is unknown.
 
+`candidateOverrides` declares candidate eligibility for a scenario. It does not force weight-modifier conditions to be true or false; those conditions still use the scenario's actual declared variables, flags, scopes, and controller facts. An overridden eligibility claim is an explicit scenario assumption, not evidence that the engine makes that candidate available.
+
 Named acceptance bands and configurable diagnostic thresholds let a test suite state intended probability, timing, starvation, dominance, prevalence, and sensitivity limits. Evaluate, sweep, and simulation requests can name the metrics of interest; that set is retained in result metadata while the authoritative result keeps the eligibility and trace context required to explain them. Sweeps enumerate declared alternatives exactly, add trigger breakpoints and their adjacent values for continuous ranges, and report local elasticities, pairwise interactions, rank reversals, cliffs, and missed target bands. Sweep expansion is bounded and rejected before it can silently truncate the requested analysis.
 
 ## Results
@@ -119,6 +124,8 @@ Deterministic simulation uses constant-memory Latin hypercube sampling by defaul
 
 Pass `inlineClausewitz` or `virtualPatch` in a source selector to analyze text without writing it. `hoi4.probability_compare` evaluates the before and after source under the same scenarios and attributes each changed rank, score, probability, or uncertainty to its modifier trace.
 
+For a frozen file stored outside its gameplay folder, set the source selector's `path` to its logical gameplay path, `snapshotPath` to the preserved workspace-relative file, and `expectedSourceHash` to the SHA-256 of that file's exact bytes. For example, a decision copy in `docs/evidence/decisions-before.txt` can be analyzed as `common/decisions/policy.txt`. The server verifies the frozen bytes and retains their physical source provenance while using the logical path for domain recognition. It never replaces the current file. Both paths must identify exact files inside authorized roots; traversal and wildcard selectors are rejected. Shared helpers and constants still come from the current configured workspace, so one frozen file is not a complete historical workspace snapshot.
+
 ## Declared sequences
 
 Sequence analysis accepts a `customPoolManifest`. The manifest is the complete model boundary: candidates, selection mode, cadence, state, recovery, caps, cooldowns, removals, resets, timer changes, and terminal states. Small finite systems use exact state distributions, bounded systems expose omitted beam mass, and large systems use deterministic seeded Monte Carlo. Results include per-candidate and per-category next-choice probability, expected selections, ever-selected probability, starvation, and expected first-selection day. The analyzer never executes event effects or infers wider campaign state.

package/docs/reference.md

@@ -0,0 +1,32 @@
+# Local references and source lookup
+
+The reference tools read only local, authorized sources. They do not fetch the Paradox Wiki or start Hearts of Iron IV. The installed game's documentation has the highest authority for current syntax; the offline wiki supplies broader modding guidance. A result identifies its source, path, exact lines, and SHA-256 revision so an agent can inspect only the relevant section.
+
+The server discovers these directories for a workspace:
+
+| Source                         | Default location                                                            | Optional workspace registration                        |
+| ------------------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------ |
+| Installed game documentation   | `gameRoot/documentation/**/*.md` and `gameRoot/common/**/*documentation.md` | Configure `gameRoot`.                                  |
+| Offline wiki                   | `modRoot/paradox_wiki/**/*.md`                                              | Set absolute `wikiRoot`.                               |
+| Generated script documentation | `modRoot/script_docs/**/*.md` and `**/*.log`                                | Set absolute `scriptDocsRoot` to a user-supplied dump. |
+
+Only Markdown headings and recognizable standalone names in generated `.log` files form sections. A dump that yields one section should be treated as insufficiently parsed; inspect its source format before relying on it. Source bytes are hashed on each request, while unchanged section indexes are reused. Missing roots are reported as unavailable. The public package contains none of these local source files.
+
+## Tools
+
+- `hoi4.reference_context`: request a surface such as `event`, `focus`, `technology`, `gui`, or `map`. It returns only the relevant offline wiki and installed documentation citations for that surface. Supply `question` to put the five best matching sections first. `missing` names a selected source absent from the configured roots. 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.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.
+
+Example:
+
+```json
+{ "workspaceId": "current", "surface": "event", "question": "save_event_target_as" }
+```
+
+Call `hoi4.reference_context` with that input, then search `save_event_target_as` and pass the result's `id` and `revision` to `hoi4.reference_read`. Use `hoi4.source_lookup` for an exact event, effect, or other indexed symbol. Run `hoi4.event_inspect` and the relevant render/compare/scenario tools for the event itself; references do not validate a mod implementation.
+
+The local index admits at most 512 files per source kind, 2 MB per file, 32 MB in total, and 20,000 sections. Search and read responses are bounded by the MCP result budget. `skipped` and per-source coverage expose incomplete ingestion instead of implying that an omitted source was checked. Registered external reference roots are operator configuration and remain private to the authorized workspace.
+
+See [the measured Chaos Redux reference retrieval](research/reference-benchmark.md) for actual source coverage and response sizes.

package/docs/research/reference-benchmark.md

@@ -0,0 +1,28 @@
+# Chaos Redux reference retrieval
+
+Measured on 2026-09-26 against the local Chaos Redux `paradox_wiki/` snapshot and the installed Hearts of Iron IV documentation. The fixture script requested context bundles for six work surfaces, then searched and read the installed `save_event_target_as` effect documentation. These are local-source measurements, not a claim about response accuracy for every future task.
+
+| Surface    | Citations | Missing required sources | Context JSON bytes | Elapsed milliseconds |
+| ---------- | --------: | -----------------------: | -----------------: | -------------------: |
+| Event      |        10 |                        0 |              5,536 |                  218 |
+| Decision   |         7 |                        0 |              3,988 |                  115 |
+| Focus      |         8 |                        0 |              4,537 |                  128 |
+| Technology |         6 |                        0 |              3,525 |                  137 |
+| GUI        |         6 |                        0 |              3,678 |                  109 |
+| Map        |         7 |                        0 |              4,224 |                  113 |
+
+The eleven full core wiki files alone total 1,167,186 bytes in this snapshot. The task-specific context responses above used 3,525–5,536 bytes, approximately 99.5–99.7% fewer bytes than loading those eleven whole pages. This measures retrieved bytes, not tokenizer-specific tokens or complete knowledge of every page. Follow-up section reads add context as needed. Each bundle selected the relevant wiki topics and installed documentation for its work surface; no selected source was missing in these six runs.
+
+The `save_event_target_as` search returned the installed `effects_documentation.md` section at line 6,496 first. A 12-line read returned the command name and supported scopes from that file. The exact source revision and path were returned with the citation. The server did not invoke the game or access the wiki website.
+
+## Natural-language discovery
+
+Nine queries were chosen before ranking changes to cover focus OR prerequisites, technology icon sizing, event-target scope documentation, mission timeouts, scripted GUI click effects, dated state history, localisation BOM, AI focus weights, and event option weights. Each query has a manually checked answer-bearing file and section in the local sources. The original exact-phrase ranking found the expected page in the top five for 2 of 9 queries. Term-aware ranking found the expected page and section in the top five for all 9. Five answer-bearing sections ranked first; all nine ranked fourth or better. This is a small task-specific retrieval set, not a general precision guarantee.
+
+The nine ranked result sets occupied 2,776–4,216 JSON bytes each. The dedicated run took 126–234 milliseconds per query, including source hash checks; earlier concurrent runs took up to about three seconds. `scripts/evaluate-reference.ts` reruns the page, section, context coverage, response-size, and latency checks against a supplied mod and game root. It exits with a failure when an expected answer-bearing section or required context source is missing.
+
+Revision-bound section IDs stayed stable across unrelated retrieval calls in the fixture test, and a fresh reference-service instance reopened the same cited text without the previous cache. A changed source invalidated the old revision. This supports returning to an exact citation without keeping full pages in conversation context. It does not measure a model's memory or guarantee that every future question can be answered from one retrieved section.
+
+The retrieval benchmark used the local service directly. A separate real-workspace stdio run identified the built server as 3.5.0 and completed documentation context in 306 ms, a cited section read in 162 ms, and a first exact source lookup in 58,851 ms. That lookup builds the broader game/mod symbol inventory; it should not be confused with the much narrower documentation lookup. MCP transport fixtures cover both protocol adapters, workspace authorization, read-scope denial, and source usage discovery. Individual task adequacy and actual engine behavior remain separate checks.
+
+The four additional public tool definitions add approximately 6.5 KB to the one-time MCP tool discovery response. The complete list is about 72 KB in the discovery fixture and is tested against a 72 KiB ceiling. The context reduction above applies to reference retrieval after discovery.

package/docs/setup.md

@@ -1,5 +1,9 @@
 # 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).
+
 HOI4 Agent Tools requires Node.js 22.19 or later in the Node 22 line, or Node.js 24.
 
 ## Install
@@ -33,6 +37,8 @@ hoi4-agent-tools-setup --init --mod-root /projects/hoi4-mods --mod-root /worksho
 
 The corresponding config fields are `modRoots`, `gameRoot`, and `workspaceStorageRoot`.
 
+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).
+
 Linked directory entries are not followed. If a mod folder is a symlink or junction, configure the real parent directory as another `--mod-root`.
 
 ## MCP client registration

package/examples/clients/codex-config.toml

@@ -1,3 +1,5 @@
 [mcp_servers.hoi4_agent_tools]
 command = "npx"
 args = ["-y", "hoi4-agent-tools@latest"]
+startup_timeout_sec = 120
+tool_timeout_sec = 600

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hoi4-agent-tools",
   "mcpName": "io.github.klimPaskov/hoi4-agent-tools",
-  "version": "3.4.1",
+  "version": "3.5.0",
   "description": "Analyze HOI4 events, decisions, impact, tech, AI, and MTTH; build focus trees, GUIs, and maps.",
   "type": "module",
   "license": "Apache-2.0",
@@ -49,11 +49,12 @@
     "docs/focus.md",
     "docs/gui.md",
     "docs/map.md",
+    "docs/reference.md",
+    "docs/research/reference-benchmark.md",
     "docs/http.md",
     "docs/development.md",
     "docs/jobs.md",
     "docs/helper-expansion.md",
-    "docs/images/readme/",
     "examples/clients/",
     "examples/probability/",
     "schemas/",
@@ -83,6 +84,7 @@
     "test:coverage": "vitest run --coverage",
     "benchmark": "node --expose-gc --import tsx scripts/benchmark.ts",
     "docs:examples": "tsx scripts/generate-readme-examples.ts",
+    "docs:comparison-examples": "tsx scripts/generate-real-visual-comparisons.ts",
     "fixtures:generate": "npm run fixtures:generate:focus && npm run fixtures:generate:gui && npm run fixtures:generate:map && npm run fixtures:generate:event && npm run fixtures:generate:technology && npm run fixtures:generate:probability",
     "fixtures:generate:focus": "tsx scripts/generate-fixtures.ts",
     "fixtures:generate:gui": "tsx scripts/generate-gui-fixture.ts",