hoi4-agent-tools 3.5.1 → 3.6.0

package/dist/hoi4_agent_tools/gui/renderer.js

@@ -39,7 +39,10 @@ function bitmapDefinitionId(key, layer = 'face') {
 function sceneGlyphDefinitions(scene) {
     const outlines = new Map();
     const bitmaps = new Map();
-    for (const element of scene.elements) {
+    for (const element of [
+        ...scene.elements,
+        ...(scene.tooltipPreview === undefined ? [] : [scene.tooltipPreview.textElement]),
+    ]) {
         for (const line of element.text?.glyphLines ?? []) {
             for (const glyph of line.glyphs) {
                 if (glyph.kind === 'outline')
@@ -400,6 +403,8 @@ function renderOverlay(element, variant, toolText) {
     if (rect.width <= 0 || rect.height <= 0)
         return '';
     if (variant === 'click-regions') {
+        if (element.enablement === 'unresolved')
+            return `<g><rect ${rectAttributes(rect)} fill="#ffb84d" fill-opacity="0.12" stroke="#ffb84d" stroke-width="2" stroke-dasharray="5 3"/><title>${escapeXml(`Potential click region: ${element.enablementReason ?? element.visibilityStatusReason ?? element.name}`)}</title>${toolText.render(`${element.name} (?)`, { x: rect.x + 3, y: rect.y + 13, fontSize: 11, fill: '#ffb84d' })}</g>`;
         if (!element.clickable)
             return '';
         return `<g><rect ${rectAttributes(rect)} fill="#00d4ff" fill-opacity="0.2" stroke="#00d4ff" stroke-width="2"/>${toolText.render(element.name, { x: rect.x + 3, y: rect.y + 13, fontSize: 11, fill: '#00d4ff' })}</g>`;
@@ -418,6 +423,13 @@ function renderOverlay(element, variant, toolText) {
     }
     return '';
 }
+function renderTooltipPreview(scene, toolText) {
+    const tooltip = scene.tooltipPreview;
+    if (tooltip === undefined)
+        return '';
+    return (renderBaseElement(tooltip.element, undefined, toolText) +
+        renderBaseElement(tooltip.textElement, undefined, toolText));
+}
 function viewFor(scene, variant) {
     if (variant !== 'cropped' || scene.bounds.width <= 0 || scene.bounds.height <= 0) {
         return {
@@ -453,7 +465,7 @@ export function sceneToSvg(scene, variant) {
         : [`<clipPath id="clip-${index}"><rect ${rectAttributes(element.clipRect)}/></clipPath>`]);
     const body = scene.elements
         .map((element, index) => renderBaseElement(element, element.clipRect === undefined ? undefined : `clip-${index}`, toolText))
-        .join('');
+        .join('') + renderTooltipPreview(scene, toolText);
     const overlays = scene.elements
         .map((element) => renderOverlay(element, variant, toolText))
         .join('');
@@ -479,7 +491,7 @@ async function sceneToSvgCooperative(scene, variant, signal) {
     const clipDefinitions = await cooperativeParts(scene.elements, (element, index) => element.clipRect === undefined
         ? ''
         : `<clipPath id="clip-${index}"><rect ${rectAttributes(element.clipRect)}/></clipPath>`, signal);
-    const body = await cooperativeParts(scene.elements, (element, index) => renderBaseElement(element, element.clipRect === undefined ? undefined : `clip-${index}`, toolText), signal);
+    const body = (await cooperativeParts(scene.elements, (element, index) => renderBaseElement(element, element.clipRect === undefined ? undefined : `clip-${index}`, toolText), signal)) + renderTooltipPreview(scene, toolText);
     const overlays = await cooperativeParts(scene.elements, (element) => renderOverlay(element, variant, toolText), signal);
     const fidelity = escapeXml(canonicalJson(scene.fidelity));
     return `<svg xmlns="http://www.w3.org/2000/svg" width="${view.width}" height="${view.height}" viewBox="${finite(view.viewBox.x)} ${finite(view.viewBox.y)} ${finite(view.viewBox.width)} ${finite(view.viewBox.height)}"><metadata data-renderer="hoi4-agent-tools" data-mode="offline">${fidelity}</metadata><defs>${clipDefinitions}${sceneGlyphDefinitions(scene)}${toolText.definitions()}</defs><rect ${rectAttributes(view.viewBox)} fill="#17202a"/>${body}${overlays}</svg>`;
@@ -526,6 +538,27 @@ export function hierarchyToSvg(scene) {
 function sceneLayoutEvidence(scene) {
     return {
         ...scene,
+        ...(scene.tooltipPreview === undefined
+            ? {}
+            : {
+                tooltipPreview: {
+                    targetId: scene.tooltipPreview.targetId,
+                    localisationKey: scene.tooltipPreview.localisationKey,
+                    placement: scene.tooltipPreview.placement,
+                    element: {
+                        id: scene.tooltipPreview.element.id,
+                        rect: scene.tooltipPreview.element.rect,
+                        sprite: scene.tooltipPreview.element.sprite?.spriteName,
+                    },
+                    textElement: {
+                        id: scene.tooltipPreview.textElement.id,
+                        rect: scene.tooltipPreview.textElement.rect,
+                        text: scene.tooltipPreview.textElement.text?.text,
+                        lines: scene.tooltipPreview.textElement.text?.lines,
+                        fontName: scene.tooltipPreview.textElement.text?.fontName,
+                    },
+                },
+            }),
         elements: scene.elements.map((element) => ({
             ...element,
             ...(element.sprite === undefined

package/dist/hoi4_agent_tools/gui/scenario.js

@@ -103,6 +103,24 @@ const GuiPreviewScenarioBodySchema = z
         .min(1)
         .max(128)
         .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/u),
+    tooltip: z
+        .object({
+        target: elementNameSchema,
+        x: z.number().nonnegative(),
+        y: z.number().nonnegative(),
+        width: z.number().positive().max(RENDER_MAX_DIMENSION),
+        padding: z
+            .number()
+            .nonnegative()
+            .max(RENDER_MAX_DIMENSION / 2)
+            .describe('Caller-declared inset on each side, in viewport pixels; no native padding is inferred.'),
+    })
+        .strict()
+        .refine(({ padding, width }) => padding * 2 < width, {
+        path: ['padding'],
+        message: 'Tooltip padding must leave a positive text width.',
+    })
+        .optional(),
     description: z.string().max(500).optional(),
     date: GuiScenarioDateSchema.optional(),
     controls: ConditionControlMapSchema.optional(),

package/dist/hoi4_agent_tools/gui/studio.js

@@ -343,14 +343,20 @@ function localisationIconSpriteCandidates(token) {
     const normalized = token.startsWith('GFX_') ? token : `GFX_${token}`;
     return [...new Set([normalized, `${normalized}_texticon`, `${normalized}_text_icon`])];
 }
-export function referencedAssetPatternsForWindow(graph, windowName, additionalSpriteNames = [], languages = ['l_english'], additionalTemplateNames = []) {
+export function referencedAssetPatternsForWindow(graph, windowName, additionalSpriteNames = [], languages = ['l_english'], additionalTemplateNames = [], includeImmediateTooltip = false) {
     const spriteNames = new Set(additionalSpriteNames);
     const fontNames = new Set();
     const textValues = new Set();
+    if (includeImmediateTooltip) {
+        spriteNames.add('ToolTip');
+        fontNames.add('cg_16b');
+    }
     for (const element of selectedElements(graph, windowName, additionalTemplateNames)) {
         collectNamedAttributes(element.attributes, new Set(['spriteType', 'quadTextureSprite']), spriteNames);
         collectNamedAttributes(element.attributes, new Set(['font', 'buttonFont']), fontNames);
         collectNamedAttributes(element.attributes, new Set(['text', 'buttonText', 'context_aware_text']), textValues);
+        if (includeImmediateTooltip)
+            collectNamedAttributes(element.attributes, new Set(['pdx_tooltip']), textValues);
     }
     for (const localisation of graph.localisation) {
         if (textValues.has(localisation.key))
@@ -619,7 +625,7 @@ function assertUniqueScenarioIds(scenarios) {
         seen.add(scenario.id);
     }
 }
-function scenarioMatrixEvidence(graph, scenes) {
+export function scenarioMatrixEvidence(graph, scenes) {
     const primary = scenes[0];
     if (primary === undefined)
         return { offline: true, scenarios: [], changes: [] };
@@ -664,16 +670,23 @@ function scenarioMatrixEvidence(graph, scenes) {
         if (matches.length === 0)
             return [];
         const shown = matches
-            .filter(({ elements }) => elements.some(({ visible }) => visible))
+            .filter(({ elements }) => elements.every(({ visibilityStatus }) => visibilityStatus !== 'unresolved') &&
+            elements.some(({ visibilityStatus }) => visibilityStatus === 'shown'))
             .map(({ scene }) => scene.scenario.id);
         const hidden = matches
-            .filter(({ elements }) => elements.every(({ visible }) => !visible))
+            .filter(({ elements }) => elements.every(({ visibilityStatus }) => visibilityStatus === 'hidden'))
+            .map(({ scene }) => scene.scenario.id);
+        const unresolvedVisibility = matches
+            .filter(({ elements }) => elements.some(({ visibilityStatus }) => visibilityStatus === 'unresolved'))
             .map(({ scene }) => scene.scenario.id);
         const enabled = matches
-            .filter(({ elements }) => elements.some(({ clickable }) => clickable))
+            .filter(({ elements }) => elements.some(({ enablement }) => enablement === 'enabled'))
             .map(({ scene }) => scene.scenario.id);
         const disabled = matches
-            .filter(({ elements }) => elements.every(({ clickable }) => !clickable))
+            .filter(({ elements }) => elements.every(({ enablement }) => enablement === 'disabled'))
+            .map(({ scene }) => scene.scenario.id);
+        const unresolved = matches
+            .filter(({ elements }) => elements.some(({ enablement }) => enablement === 'unresolved'))
             .map(({ scene }) => scene.scenario.id);
         return [
             {
@@ -682,10 +695,24 @@ function scenarioMatrixEvidence(graph, scenes) {
                     ...new Set(matches.flatMap(({ elements }) => elements.map(({ sourcePath }) => sourcePath))),
                 ].sort(compareCodeUnits),
                 ...(visibilityNames.has(name)
-                    ? { visibility: { shown, hidden, covered: shown.length > 0 && hidden.length > 0 } }
+                    ? {
+                        visibility: {
+                            shown,
+                            hidden,
+                            unresolved: unresolvedVisibility,
+                            covered: shown.length > 0 && hidden.length > 0,
+                        },
+                    }
                     : {}),
                 ...(enabledNames.has(name)
-                    ? { enabled: { enabled, disabled, covered: enabled.length > 0 && disabled.length > 0 } }
+                    ? {
+                        enabled: {
+                            enabled,
+                            disabled,
+                            unresolved,
+                            covered: enabled.length > 0 && disabled.length > 0,
+                        },
+                    }
                     : {}),
             },
         ];
@@ -736,13 +763,34 @@ function scenarioMatrixEvidence(graph, scenes) {
             })),
             visibleElements: scene.elements
                 .filter(({ visible }) => visible)
-                .map(({ id, name }) => ({ id, name })),
+                .map(({ id, name, visibilityStatus }) => ({ id, name, visibilityStatus })),
             hiddenElements: scene.elements
                 .filter(({ visible }) => !visible)
-                .map(({ id, name, visibilityReason }) => ({ id, name, reason: visibilityReason })),
+                .map(({ id, name, visibilityReason, visibilityStatus }) => ({
+                id,
+                name,
+                reason: visibilityReason,
+                visibilityStatus,
+            })),
+            unresolvedVisibility: scene.elements
+                .filter(({ visibilityStatus }) => visibilityStatus === 'unresolved')
+                .map(({ id, name, visible, visibilityStatusReason }) => ({
+                id,
+                name,
+                previewVisible: visible,
+                reason: visibilityStatusReason,
+            })),
             disabledElements: scene.elements
-                .filter(({ disabledReason }) => disabledReason !== undefined)
+                .filter(({ disabledReason, enablement }) => disabledReason !== undefined && enablement === 'disabled')
                 .map(({ id, name, disabledReason }) => ({ id, name, reason: disabledReason })),
+            unresolvedClickRegions: scene.elements
+                .filter(({ visible, enablement }) => visible && enablement === 'unresolved')
+                .map(({ id, name, rect, enablementReason }) => ({
+                id,
+                name,
+                rect,
+                reason: enablementReason,
+            })),
         })),
         changes: scenes.slice(1).map((scene) => {
             const currentByKey = new Map(scene.elements.map((element) => [elementKey(element), element]));
@@ -758,13 +806,13 @@ function scenarioMatrixEvidence(graph, scenes) {
             for (const key of keys) {
                 const before = primaryByKey.get(key);
                 const after = currentByKey.get(key);
-                if (before?.visible !== true && after?.visible === true)
+                if (before?.visibilityStatus === 'hidden' && after?.visibilityStatus === 'shown')
                     shown.push(after.name);
-                if (before?.visible === true && after?.visible !== true)
+                if (before?.visibilityStatus === 'shown' && after?.visibilityStatus === 'hidden')
                     hidden.push(before.name);
-                if (before?.clickable === true && after?.clickable === false)
+                if (before?.enablement === 'enabled' && after?.enablement === 'disabled')
                     disabled.push(after.name);
-                if (before?.clickable === false && after?.clickable === true)
+                if (before?.enablement === 'disabled' && after?.enablement === 'enabled')
                     enabled.push(after.name);
                 if (before === undefined || after === undefined)
                     continue;
@@ -924,7 +972,7 @@ export class ScriptedGuiStudio {
         const files = mergeScannedFiles(snapshot.files, localisationFiles);
         return this.graphForFiles(files, `workspace:${workspaceId}`);
     }
-    async scanWindow(workspaceId, windowName, principal, signal, languages = ['l_english'], additionalSpriteNames = [], additionalTemplateNames = [], additionalAssetPatterns = [], additionalLocalisationKeys = []) {
+    async scanWindow(workspaceId, windowName, principal, signal, languages = ['l_english'], additionalSpriteNames = [], additionalTemplateNames = [], additionalAssetPatterns = [], additionalLocalisationKeys = [], includeImmediateTooltip = false) {
         const workspace = this.resolver.get(workspaceId, principal);
         const layoutPatterns = guiLayoutPatterns(workspace);
         const overlayLayouts = await this.engine.scan(workspaceId, {
@@ -955,7 +1003,7 @@ export class ScriptedGuiStudio {
         const definitions = this.graphForFiles(definitionFiles, `definitions:${workspaceId}`, additionalLocalisationKeys);
         assertTargetWindowAvailable(definitions.graph, windowName);
         const referencedPatterns = [
-            ...referencedAssetPatternsForWindow(definitions.graph, windowName, additionalSpriteNames, languages, additionalTemplateNames),
+            ...referencedAssetPatternsForWindow(definitions.graph, windowName, additionalSpriteNames, languages, additionalTemplateNames, includeImmediateTooltip),
             ...additionalAssetPatterns,
         ];
         const exactReferenced = referencedPatterns.length === 0
@@ -1000,7 +1048,7 @@ export class ScriptedGuiStudio {
         const generatedOptions = input.generatedScenarios === undefined
             ? undefined
             : parseGeneratedScenarioOptions(input.generatedScenarios);
-        const scanned = await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [placeholderScenario.language, ...explicitRelatedScenarios.map(({ language }) => language)], scenarioSpriteNames([placeholderScenario, ...explicitRelatedScenarios], generatedOptions?.textSamples), scenarioTemplateNames([placeholderScenario, ...explicitRelatedScenarios]), scenarioCountryFlagPatterns([placeholderScenario, ...explicitRelatedScenarios]), scenarioLocalisationKeys([placeholderScenario, ...explicitRelatedScenarios]));
+        const scanned = await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [placeholderScenario.language, ...explicitRelatedScenarios.map(({ language }) => language)], scenarioSpriteNames([placeholderScenario, ...explicitRelatedScenarios], generatedOptions?.textSamples), scenarioTemplateNames([placeholderScenario, ...explicitRelatedScenarios]), scenarioCountryFlagPatterns([placeholderScenario, ...explicitRelatedScenarios]), scenarioLocalisationKeys([placeholderScenario, ...explicitRelatedScenarios]), [placeholderScenario, ...explicitRelatedScenarios].some(({ tooltip }) => tooltip !== undefined));
         const generatedScenarios = generatedOptions === undefined
             ? []
             : generateGuiPreviewScenarios(scanned.graph, input.windowName, placeholderScenario, generatedOptions, ClausewitzEvaluationDefinitions.build(scanned));
@@ -1030,7 +1078,7 @@ export class ScriptedGuiStudio {
         const budget = new RenderBudget();
         const beforeScenario = parsePreviewScenario(input.before);
         const afterScenario = parsePreviewScenario(input.after);
-        const scanned = await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [beforeScenario.language, afterScenario.language], scenarioSpriteNames([beforeScenario, afterScenario]), scenarioTemplateNames([beforeScenario, afterScenario]), scenarioCountryFlagPatterns([beforeScenario, afterScenario]), scenarioLocalisationKeys([beforeScenario, afterScenario]));
+        const scanned = await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [beforeScenario.language, afterScenario.language], scenarioSpriteNames([beforeScenario, afterScenario]), scenarioTemplateNames([beforeScenario, afterScenario]), scenarioCountryFlagPatterns([beforeScenario, afterScenario]), scenarioLocalisationKeys([beforeScenario, afterScenario]), [beforeScenario, afterScenario].some(({ tooltip }) => tooltip !== undefined));
         const beforeCatalog = new GuiAssetCatalog(scanned.graph, scanned.files, budget, beforeScenario.language);
         const afterCatalog = new GuiAssetCatalog(scanned.graph, scanned.files, budget, afterScenario.language);
         const before = await buildGuiScene(scanned.graph, scanned.files, input.windowName, beforeScenario, beforeCatalog);
@@ -1091,7 +1139,11 @@ export class ScriptedGuiStudio {
             placeholderScenario,
             ...(requestedBaselineScenario === undefined ? [] : [requestedBaselineScenario]),
             ...explicitRelatedScenarios,
-        ]));
+        ]), [
+            placeholderScenario,
+            ...(requestedBaselineScenario === undefined ? [] : [requestedBaselineScenario]),
+            ...explicitRelatedScenarios,
+        ].some(({ tooltip }) => tooltip !== undefined));
         const generatedScenarios = generatedOptions === undefined
             ? []
             : generateGuiPreviewScenarios(scanned.graph, input.windowName, placeholderScenario, generatedOptions, ClausewitzEvaluationDefinitions.build(scanned));
@@ -1438,7 +1490,7 @@ export class ScriptedGuiStudio {
         const previewScenario = input.scenario === undefined ? undefined : parsePreviewScenario(input.scenario);
         const initiallyScanned = input.windowName === undefined
             ? await this.scan(input.workspaceId, input.principal, input.signal)
-            : await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [previewScenario.language], scenarioSpriteNames([previewScenario]), scenarioTemplateNames([previewScenario]), scenarioCountryFlagPatterns([previewScenario]), scenarioLocalisationKeys([previewScenario]));
+            : await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [previewScenario.language], scenarioSpriteNames([previewScenario]), scenarioTemplateNames([previewScenario]), scenarioCountryFlagPatterns([previewScenario]), scenarioLocalisationKeys([previewScenario]), previewScenario.tooltip !== undefined);
         const exactTargets = await this.scanner.scan(workspace, {
             patterns: prepared.map(({ relativePath }) => relativePath),
             ...(input.signal === undefined ? {} : { signal: input.signal }),

package/dist/hoi4_agent_tools/mcp/server/instructions.js

@@ -1,2 +1,2 @@
 /** Shared agent-facing guidance for both MCP protocol generations. */
-export const SERVER_INSTRUCTIONS = 'Use hoi4.reference_context for local wiki and installed documentation citations, hoi4.reference_search and hoi4.reference_read for exact sections, and hoi4.source_lookup for indexed source examples. Use focus tools for focus trees, GUI tools for interfaces, and map tools for map data. Start unfamiliar event chains with hoi4.event_inspect. Event tools are read-only. Start cross-system source review with hoi4.impact_inspect and decision or mission scenarios with hoi4.decision_inspect. Test declared mechanic steps with hoi4.mechanic_test, package connections with hoi4.package_check, and named suites with hoi4.scenario_test. These analysis tools are read-only. Start technology and doctrine work with hoi4.tech_inspect. Technology tools are read-only. Start weighted AI, MTTH, random, and declared-pool analysis with hoi4.probability_inspect. Probability tools are read-only. Concurrent calls queue automatically and emit periodic progress when the client requests it. Long operations support negotiated MCP tasks; native background rewrites require a stable requestKey. Large evidence is linked as resources.';
+export const SERVER_INSTRUCTIONS = 'Start with the matching inspect tool; use hoi4.probability_inspect for weights and timing. Find local documentation with hoi4.reference_context, hoi4.reference_search and hoi4.reference_read, and source definitions with hoi4.source_lookup. Inspection and rendering are read-only; rewrite tools edit mod source. Results describe offline source and scenario models, not observed game behavior. Unresolved states are not confirmed coverage. Read linked artifacts when summaries omit detail. Long operations support negotiated MCP tasks and hoi4.job_inspect/hoi4.job_cancel; background rewrites need a stable requestKey.';

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.6.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,35 @@
 # 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.
+- [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,85 @@
+# 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.
+
+## Check alternative focus prerequisites
+
+> Find Fury's focus tree. Render the branch leading to “The Last Neighbor Has Fallen” and show whether both preceding focuses are required or either one is enough.
+
+![Fury branch with dotted alternative prerequisites](images/comparisons/fury-or-mcp.png)
+
+Dotted connectors mark alternatives within one prerequisite group; solid connectors mark separate required prerequisites.
+The agent can link each finding to the source block before you change the route.
+The [in-game comparison](visual-comparisons.md#focus-trees) shows the same branch and explains the presentation differences.
+
+## 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 chemical and biological folders and explain why different source versions can produce different layouts.
+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,43 @@
 
 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:
+
+```json
+{
+  "id": "close-tooltip",
+  "tooltip": {
+    "target": "close_button",
+    "x": 980,
+    "y": 100,
+    "width": 160,
+    "padding": 16
+  }
+}
+```
+
+The target can be an instance ID from inspection or a unique element name.
+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/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).