hoi4-agent-tools 3.4.0 → 3.5.0

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/operations.js

@@ -58,6 +58,34 @@ export function technologyValidation(graph) {
         ],
     };
 }
+export function technologyRenderValidation(graph, render) {
+    const omitted = render.omittedNodeCount;
+    const unresolvedSprites = render.unresolvedIconSprites.length;
+    const sourcePlacementPassed = render.view !== 'folder' || render.sourceAccurate;
+    const analysisBoundaryPassed = graph.complete || (graph.analysisMode === 'focused' && graph.skippedSourceCount === 0);
+    const renderPassed = sourcePlacementPassed && omitted === 0 && unresolvedSprites === 0;
+    return {
+        passed: renderPassed && analysisBoundaryPassed,
+        checks: [
+            {
+                id: 'technology-render',
+                passed: renderPassed,
+                message: renderPassed
+                    ? 'The requested technology view rendered with complete node and sprite coverage'
+                    : `${sourcePlacementPassed ? 0 : 1} source-placement failure(s), ${omitted} omitted node(s), and ${unresolvedSprites} unresolved sprite(s) affect the requested technology view`,
+            },
+            {
+                id: 'technology-analysis-boundary',
+                passed: analysisBoundaryPassed,
+                message: graph.complete
+                    ? 'The supporting technology analysis is complete'
+                    : analysisBoundaryPassed
+                        ? 'Whole-workspace helper projections were deferred; the requested render retains direct source evidence'
+                        : `${graph.skippedSourceCount} technology source(s) were skipped; linked evidence records the partial analysis boundary`,
+            },
+        ],
+    };
+}
 export async function inspectTechnologies(viewer, input) {
     const output = await viewer.analyze(input);
     const result = emptyServiceResult(input.workspaceId, {
@@ -93,7 +121,7 @@ export async function renderTechnologies(viewer, input) {
     result.code = output.graph.complete ? 'TECH_RENDERED' : 'TECH_RENDERED_PARTIAL';
     setInlineFilesScanned(result, output.graph.filesScanned);
     result.artifacts = output.artifacts.map(publicArtifactLink);
-    result.validation = technologyValidation(output.graph);
+    result.validation = technologyRenderValidation(output.graph, output.render);
     return result;
 }
 export async function compareTechnologies(viewer, input) {

package/dist/hoi4_agent_tools/technology/render.js

@@ -72,9 +72,10 @@ function technologyNode(graph, technologyId, placement) {
                 subTechnologies: technology.subTechnologies.map((id, index) => {
                     const definition = graph.technologies.find((candidate) => candidate.id === id);
                     const slot = itemLayout?.subTechnologySlots?.find((candidate) => candidate.index === index);
+                    const iconSprite = slot?.sprite ?? definition?.icon.sprite;
                     return {
                         id,
-                        ...(definition === undefined ? {} : { iconSprite: definition.icon.sprite }),
+                        ...(iconSprite === undefined ? {} : { iconSprite }),
                         placementStatus: slot === undefined ? 'missing_source_slot' : 'source_slot',
                         ...(slot === undefined ? {} : { slot }),
                     };
@@ -743,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;
@@ -766,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/technology/service.js

@@ -487,6 +487,7 @@ export class TechnologyTreeViewer {
             });
         const guiSprites = [
             ...preliminary.itemLayouts.flatMap(({ designTeamIcon }) => designTeamIcon === undefined ? [] : [designTeamIcon.sprite]),
+            ...preliminary.itemLayouts.flatMap(({ subTechnologySlots }) => (subTechnologySlots ?? []).flatMap(({ sprite }) => (sprite === undefined ? [] : [sprite]))),
             ...preliminary.itemLayouts.flatMap(({ backgroundSprite }) => backgroundSprite === undefined
                 ? []
                 : [

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.0';
+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/events.md

@@ -19,7 +19,7 @@ Use the three event tools directly from the target mod.
 
 Use narrow identifiers, direction, and depth limits when the task concerns one chain.
 Broad scans build the structural event graph without expanding every scripted helper into duplicate paths.
-Focused trace, path, and selector-based inventory requests may defer workspace-wide helper projections and lifecycle passes; their linked evidence records the partial boundary.
+Focused trace, path, and selector-based inventory requests may defer workspace-wide helper projections and lifecycle passes. When every event source was scanned and no blocking diagnostics remain, validation accepts the requested direct-source evidence while the linked artifacts continue to record that deferred boundary.
 Focused trace and path calls collapse only the selected bounded route.
 For a large helper closure, use [bounded helper expansion](helper-expansion.md) to receive resumable pages without first materializing every projection.
 

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.
@@ -51,6 +57,7 @@ The scene records the selected shader source, hash and entry point.
 Additional shader operations, including animated end-cap sampling, remain explicit unsupported findings rather than accepted pixel-parity evidence.
 
 Container scrollbars use referenced or inline `extendedScrollbarType` templates, including their backgrounds, inline track, thumb and end-button artwork.
+The template's slider and end-button roles are engine-owned compound controls, so scripted click-effect checks apply to authored source buttons and explicitly referenced role names rather than requiring effects for the native scrollbar internals.
 Each attachment has independent instance IDs and source provenance even when multiple containers reuse one template.
 The renderer measures direct content bounds and populated grid/list rows, retaining declared list bounds as a minimum, clamps scroll offsets, and applies `autohide_scrollbars`.
 A nested container contributes its declared bounds rather than the overflowing artwork of its descendants.

package/docs/jobs.md

@@ -57,6 +57,7 @@ Event and technology helper expansion also saves an authenticated intermediate f
 A replacement validates the saved paths, adjacency cursor, graph identity, and checkpoint bytes before continuing.
 Source changes before intermediate-frontier recovery cause a fresh analysis of the current revision; old and new graph evidence are never combined.
 An active host allows at most two replacement attempts after proven worker death, and never retries the same unchanged frontier twice.
+If another bounded host has already claimed an interrupted job, the initiating host follows that live replacement until it publishes a terminal outcome; it does not expose the replacement's intermediate `running` record as the synchronous result.
 Checkpoint recovery never overrides cancellation or live/unverifiable ownership, and never replays a rewrite.
 Event and technology scan artifacts retain revision-addressed graphs for later comparisons, and bounded responses state their requested depth, node, edge, render, helper-expansion, or candidate coverage.
 Their opt-in `helper_expansion` mode also returns [bounded continuation pages](helper-expansion.md) through both ordinary calls and persistent jobs.

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/mechanics.md

@@ -41,7 +41,8 @@ An `advance_days` step only expires modeled timed flags; it never runs on action
 
 The linked trace records applied, skipped, and unresolved source operations with before and after values.
 The `single_payment` assertion checks the named balance's final change and the number and size of its traced deductions, so a compensating grant cannot hide a second charge.
-Supported operations include documented variable arithmetic, flags, event targets, arrays, conditionals, finite declared scope iteration, scripted helpers, safe meta substitutions, and selected balance effects.
+Supported operations include documented persistent and unscoped temporary-variable arithmetic, exact `has_variable` presence checks, flags, event targets, arrays, conditionals, finite declared scope iteration, scripted helpers, safe meta substitutions, and selected balance effects.
+Active scripted-effect documents are parsed once per source file and their helper blocks share that bounded source model.
 Decision engine political-power costs are applied once before `complete_effect`; custom cost triggers check affordability and their payment remains in `complete_effect`.
 Unresolved eligibility, unsupported effects, dynamic names that cannot be resolved, missing finite scope catalogs, and bounded-work limits remain unresolved rather than guessed.
 An effect with an unknown write set conservatively makes state assertions unresolved.

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/docs/technology.md

@@ -56,10 +56,14 @@ It preserves separate conditional call sites and identifies source, cycle, and d
 
 `hoi4.tech_render` returns authoritative JSON with deterministic SVG and PNG resources; set `includeHtml` when a bundled static report is useful. Folder renders read the actual `techtree_<folder>_item` and `techtree_<folder>_small_item` geometry, choose the small item for technologies that do not unlock equipment or explicitly force it, and place the source GUI's year labels. Available views are `summary`, `folder`, `dependencies`, `technology`, `doctrine`, `exclusive`, `memberships`, `bonuses`, `grants`, `unlocks`, `metadata`, `assets`, and `unresolved`.
 
-Folder renders use folder assignments, gridbox geometry, technology coordinates, and item dimensions found in source. File-local `@` constants in technology coordinates are resolved before placement. A technology with multiple prerequisite roots can use its own declared gridbox. The item template supplies its unavailable, available, or researched skin, icon center, name position, and design-team icon position when the corresponding sprites resolve. `sub_technology_slot_<index>` geometry positions each declared subtechnology icon; a missing slot stays visible as unresolved placement metadata. The folder's tiled panel sprite fills the canvas, and source `*_techtree_bg` sprites render behind technology nodes at their declared GUI positions; when the GUI omits a sprite size, the decoded dimensions supply it. Year labels retain their source font, box dimensions, alignment, orientation, and colour declarations in the graph. Sprite declarations and texture files resolve through the active load order across the mod, configured dependencies, and the detected or configured game installation. The authoritative JSON and SVG expose `layoutSize`, rendered sprite coverage, and unresolved sprite names without embedding image data in JSON. `sourceAccurate` describes source pixel placement only; it is not a percentage of visual agreement with a game screenshot. The game may change the visibility of design-team icons and status corners at runtime. Dependency and other semantic views are labelled as generated analysis layouts.
+Folder renders use folder assignments, gridbox geometry, technology coordinates, and item dimensions found in source. File-local `@` constants in technology coordinates are resolved before placement. A technology with multiple prerequisite roots can use its own declared gridbox. The item template supplies its unavailable, available, or researched skin, icon center, name position, and design-team icon position when the corresponding sprites resolve. `sub_technology_slot_<index>` geometry and its source `picture` sprite position each declared subtechnology icon; the technology-id icon is a fallback when the slot does not declare art, and a missing slot stays visible as unresolved placement metadata. The folder's tiled panel sprite fills the canvas, and source `*_techtree_bg` sprites render behind technology nodes at their declared GUI positions; when the GUI omits a sprite size, the decoded dimensions supply it. Year labels retain their source font, box dimensions, alignment, orientation, and colour declarations in the graph. Sprite declarations and texture files resolve through the active load order across the mod, configured dependencies, and the detected or configured game installation. The authoritative JSON and SVG expose `layoutSize`, rendered sprite coverage, and unresolved sprite names without embedding image data in JSON. `sourceAccurate` describes source pixel placement only; it is not a percentage of visual agreement with a game screenshot. The game may change the visibility of design-team icons and status corners at runtime. Dependency and other semantic views are labelled as generated analysis layouts.
 
 A `small` 72-pixel item can still display its source `GFX_*_medium` artwork at full card size; the layout name does not select smaller icon art.
 
+Render validation is scoped to the requested view: folder source placement, omitted nodes, and unresolved sprites determine whether that render passes. Graph-wide semantic diagnostics remain available through technology inspection and do not falsely invalidate an otherwise complete source-backed folder render. Deferred whole-workspace helper projection remains an explicit analysis boundary and does not by itself invalidate a complete direct-source render.
+
+Subtechnology cards use the sprite declared by their source GUI slot before any technology-id fallback. Slot-declared textures are included in the bounded asset scan even when no ordinary technology icon references the same file.
+
 Example folder render:
 
 ```json

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.0",
+  "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",