hoi4-agent-tools 3.6.0 → 3.7.0

package/dist/hoi4_agent_tools/reference/source-lookup.js

@@ -1,21 +1,72 @@
 import { ServiceError } from '../core/result.js';
 import { decodeSource } from '../core/source/encoding.js';
-import { readBoundedLines } from './lines.js';
+import { readBoundedJsonLines } from './lines.js';
 import { scanImpactSemanticReferences } from '../core/impact-semantic.js';
+import { parseClausewitz } from '../core/source/parser.js';
+import { navigateSource } from './source-navigation.js';
+const semanticCache = new WeakMap();
 /** Exact source definitions and usage over the existing shared Clausewitz index. */
 export async function sourceLookup(engine, workspaceId, input, principal, signal) {
-    const snapshot = await engine.scan(workspaceId, {}, principal, signal);
+    const narrowPatterns = {
+        event: ['events/**/*.txt'],
+        scripted_effect: ['common/scripted_effects/**/*.txt'],
+        scripted_trigger: ['common/scripted_triggers/**/*.txt'],
+    };
+    const patterns = input.kind === 'event' && input.includeReferences
+        ? [
+            'events/**/*.txt',
+            'common/national_focus/**/*.txt',
+            'common/continuous_focus/**/*.txt',
+            'common/decisions/**/*.txt',
+            'common/ideas/**/*.txt',
+            'common/technologies/**/*.txt',
+            'common/scripted_effects/**/*.txt',
+            'common/scripted_triggers/**/*.txt',
+            'common/scripted_guis/**/*.txt',
+            'common/on_actions/**/*.txt',
+        ]
+        : input.includeReferences || input.kind === undefined
+            ? undefined
+            : narrowPatterns[input.kind];
+    const snapshot = await engine.scan(workspaceId, patterns === undefined ? {} : { patterns }, principal, signal);
     if (input.expectedRevision !== undefined && input.expectedRevision !== snapshot.revision) {
         throw new ServiceError('SOURCE_REVISION_STALE', 'Indexed source changed; look up the symbol again', { currentRevision: snapshot.revision });
     }
-    const definitions = snapshot.index.symbols
+    const navigating = input.keyPath !== undefined || input.view === 'structure';
+    const matchedDefinitions = snapshot.index.symbols
         .filter((entry) => entry.id === input.symbol && (input.kind === undefined || entry.kind === input.kind))
-        .sort((left, right) => Number(left.overridden) - Number(right.overridden) || right.loadOrder - left.loadOrder)
-        .slice(0, input.maxDefinitions)
+        .sort((left, right) => Number(left.overridden) - Number(right.overridden) || right.loadOrder - left.loadOrder);
+    if (navigating && new Set(matchedDefinitions.map(({ kind }) => kind)).size > 1)
+        throw new ServiceError('SOURCE_KIND_AMBIGUOUS', 'Nested navigation requires kind when the identifier has multiple symbol kinds');
+    const definitions = matchedDefinitions
+        .slice(0, navigating ? 1 : input.maxDefinitions)
         .map((entry, index) => {
         const source = snapshot.index.files.get(entry.path);
         const start = entry.location?.start.line;
         const end = entry.location?.end.line;
+        const navigation = navigating
+            ? (() => {
+                if (source === undefined ||
+                    entry.location === undefined ||
+                    /\.ya?ml$/iu.test(entry.path))
+                    throw new ServiceError('SOURCE_STRUCTURE_UNAVAILABLE', 'Nested navigation requires an indexed Clausewitz definition');
+                return navigateSource(parseClausewitz(source.bytes, source.displayPath), {
+                    start: entry.location.start.offset,
+                    end: entry.location.end.offset,
+                }, input.keyPath ?? [], {
+                    structure: input.view === 'structure',
+                    maxChildren: input.maxChildren,
+                    childOffset: input.childOffset,
+                    maxLines: input.maxLines,
+                    ...(index === 0 && input.fromLine !== undefined
+                        ? { fromLine: input.fromLine }
+                        : {}),
+                    ...(index === 0 && input.fromColumn !== undefined
+                        ? { fromColumn: input.fromColumn }
+                        : {}),
+                });
+            })()
+            : undefined;
         const fromLine = index === 0 ? (input.fromLine ?? start) : start;
         if (fromLine !== undefined &&
             start !== undefined &&
@@ -30,7 +81,7 @@ export async function sourceLookup(engine, workspaceId, input, principal, signal
                 .slice((start ?? fromLine) - 1, end);
         const selected = fromLine === undefined || lines.length === 0
             ? null
-            : readBoundedLines(lines, start ?? fromLine, fromLine, index === 0 ? (input.fromColumn ?? 1) : 1, input.maxLines, 2_000);
+            : readBoundedJsonLines(lines, start ?? fromLine, fromLine, index === 0 ? (input.fromColumn ?? 1) : 1, input.maxLines, 2_000, 4_096);
         return {
             kind: entry.kind,
             id: entry.id,
@@ -41,16 +92,19 @@ export async function sourceLookup(engine, workspaceId, input, principal, signal
             sourceShadowed: entry.sourceShadowed,
             startLine: start ?? null,
             endLine: end ?? null,
-            fromLine: fromLine ?? null,
-            toLine: selected?.endLine ?? null,
-            nextLine: selected?.nextLine ?? null,
-            nextColumn: selected?.nextColumn ?? null,
-            text: selected?.text ?? '',
+            fromLine: navigation?.fromLine ?? fromLine ?? null,
+            toLine: navigation?.endLine ?? selected?.endLine ?? null,
+            nextLine: navigation === undefined ? (selected?.nextLine ?? null) : navigation.nextLine,
+            nextColumn: navigation === undefined ? (selected?.nextColumn ?? null) : navigation.nextColumn,
+            text: navigation?.text ?? selected?.text ?? '',
+            ...(navigation === undefined ? {} : { navigation: navigation.navigation }),
         };
     });
-    const semantic = input.includeReferences
-        ? scanImpactSemanticReferences(snapshot, 200_000, { includeOnActions: true })
-        : undefined;
+    let semantic = input.includeReferences ? semanticCache.get(snapshot) : undefined;
+    if (input.includeReferences && semantic === undefined) {
+        semantic = scanImpactSemanticReferences(snapshot, 200_000, { includeOnActions: true });
+        semanticCache.set(snapshot, semantic);
+    }
     const referenceIdentities = new Set();
     const matchedReferences = input.includeReferences
         ? [...snapshot.index.references, ...(semantic?.references ?? [])]
@@ -70,11 +124,19 @@ export async function sourceLookup(engine, workspaceId, input, principal, signal
         path: entry.path,
         line: entry.location?.start.line ?? null,
     }));
-    return {
+    const result = {
+        sourceScope: input.kind === 'event'
+            ? input.includeReferences
+                ? 'event_consumers'
+                : 'event_definitions'
+            : patterns === undefined
+                ? 'workspace_index'
+                : 'helper_definitions',
         revision: snapshot.revision,
         complete: snapshot.complete,
         skippedSourceCount: snapshot.skippedSourceCount,
         definitionCount: snapshot.index.symbols.filter((entry) => entry.id === input.symbol && (input.kind === undefined || entry.kind === input.kind)).length,
+        definitionsTruncated: matchedDefinitions.length > definitions.length,
         definitions,
         references,
         referencesIncluded: input.includeReferences,
@@ -87,4 +149,18 @@ export async function sourceLookup(engine, workspaceId, input, principal, signal
             matchedReferences.length <= references.length,
         unresolvedReferenceCount: semantic?.unresolved.length ?? 0,
     };
+    while (Buffer.byteLength(JSON.stringify(result), 'utf8') > 24_000 &&
+        result.references.length > 0) {
+        result.references.pop();
+        result.referencesTruncated = true;
+        result.referencesComplete = false;
+    }
+    while (Buffer.byteLength(JSON.stringify(result), 'utf8') > 24_000 &&
+        result.definitions.length > 1) {
+        result.definitions.pop();
+        result.definitionsTruncated = true;
+    }
+    if (Buffer.byteLength(JSON.stringify(result), 'utf8') > 24_000)
+        throw new ServiceError('REFERENCE_RESPONSE_TOO_LARGE', 'Selected source metadata exceeds the bounded reply; use entry-index selectors for long nested keys');
+    return result;
 }

package/dist/hoi4_agent_tools/reference/source-navigation.js

@@ -0,0 +1,130 @@
+import { ServiceError } from '../core/result.js';
+import { locationFor } from '../core/source/lexer.js';
+import { readBoundedJsonLines } from './lines.js';
+function preview(text, limit) {
+    let end = Math.min(text.length, limit);
+    if (end > 0 &&
+        /[\uD800-\uDBFF]/u.test(text[end - 1]) &&
+        /[\uDC00-\uDFFF]/u.test(text[end] ?? ''))
+        end--;
+    return { text: text.slice(0, end), truncated: end < text.length };
+}
+function findEntry(block, range) {
+    for (const entry of block.entries) {
+        if (entry.start === range.start && entry.end === range.end)
+            return entry;
+        const value = entry.type === 'assignment' ? entry.value : entry;
+        if (value.type !== 'block' || value.start > range.start || value.end < range.end)
+            continue;
+        if (value.start === range.start && value.end === range.end)
+            return value;
+        const found = findEntry(value, range);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+/** Navigate actual parser nodes, preserving duplicate keys and exact source boundaries. */
+export function navigateSource(document, range, keyPath, options) {
+    if (document.diagnostics.some(({ severity }) => severity === 'error' || severity === 'blocker'))
+        throw new ServiceError('SOURCE_STRUCTURE_UNAVAILABLE', 'Cannot navigate a source document with parse errors');
+    const definition = findEntry(document.root, range);
+    if (definition === undefined)
+        throw new ServiceError('SOURCE_STRUCTURE_UNAVAILABLE', 'Indexed definition does not identify an exact parser node');
+    let selected = definition;
+    const resolvedPath = [];
+    for (const step of keyPath) {
+        const value = selected.type === 'assignment' ? selected.value : selected;
+        if (value.type !== 'block')
+            throw new ServiceError('SOURCE_PATH_NOT_BLOCK', 'Cannot navigate inside a scalar source value', { keyPath: resolvedPath });
+        if ('index' in step) {
+            const child = value.entries[step.index];
+            if (child === undefined)
+                throw new ServiceError('SOURCE_INDEX_UNKNOWN', 'No source child exists at the requested entry index', { index: step.index });
+            selected = child;
+            resolvedPath.push({ index: step.index });
+            continue;
+        }
+        const matches = value.entries.filter((entry) => entry.type === 'assignment' && entry.key.value === step.key);
+        if (step.occurrence === undefined && matches.length > 1)
+            throw new ServiceError('SOURCE_PATH_AMBIGUOUS', 'Repeated key requires an explicit zero-based occurrence', { key: step.key, occurrences: matches.length });
+        const occurrence = step.occurrence ?? 0;
+        const child = matches[occurrence];
+        if (child === undefined)
+            throw new ServiceError('SOURCE_PATH_UNKNOWN', 'No source child matches the requested key and occurrence', { key: step.key, occurrence });
+        selected = child;
+        resolvedPath.push(Buffer.byteLength(step.key, 'utf8') > 128
+            ? { index: value.entries.indexOf(child) }
+            : { key: step.key, occurrence });
+    }
+    const location = locationFor(document.path, document.lineIndex, selected.start, selected.end);
+    const fromLine = options.fromLine ?? location.start.line;
+    const fromColumn = options.fromColumn ?? (fromLine === location.start.line ? location.start.column : 1);
+    if (fromLine < location.start.line ||
+        fromLine > location.end.line ||
+        (fromLine === location.start.line && fromColumn < location.start.column) ||
+        (fromLine === location.end.line && fromColumn > location.end.column))
+        throw new ServiceError('SOURCE_POSITION_OUTSIDE_SELECTION', 'Requested position is outside the selected parser node');
+    const lines = document.text.split(/\r?\n/u).slice(location.start.line - 1, location.end.line);
+    lines[lines.length - 1] = lines.at(-1).slice(0, location.end.column - 1);
+    const read = options.structure
+        ? { text: '', endLine: location.end.line, nextLine: null, nextColumn: null }
+        : readBoundedJsonLines(lines, location.start.line, fromLine, fromColumn, options.maxLines, 2000, 4096);
+    const value = selected.type === 'assignment' ? selected.value : selected;
+    const entries = options.structure && value.type === 'block' ? value.entries : [];
+    const occurrences = new Map();
+    if (options.structure && options.childOffset > entries.length)
+        throw new ServiceError('SOURCE_CHILD_OFFSET_OUTSIDE_SELECTION', 'Child offset exceeds the selected block');
+    for (const entry of entries.slice(0, options.childOffset)) {
+        const key = entry.type === 'assignment' ? entry.key.value : null;
+        occurrences.set(key, (occurrences.get(key) ?? 0) + 1);
+    }
+    const candidates = entries
+        .slice(options.childOffset, options.childOffset + options.maxChildren)
+        .map((entry, index) => {
+        const key = entry.type === 'assignment' ? entry.key.value : null;
+        const occurrence = occurrences.get(key) ?? 0;
+        occurrences.set(key, occurrence + 1);
+        const childValue = entry.type === 'assignment' ? entry.value : entry;
+        const childLocation = locationFor(document.path, document.lineIndex, entry.start, entry.end);
+        const keyPreview = key === null ? null : preview(key, 1024);
+        const valuePreview = childValue.type === 'scalar' ? preview(childValue.value, 120) : null;
+        return {
+            key: keyPreview?.text ?? null,
+            index: options.childOffset + index,
+            keyTruncated: keyPreview?.truncated ?? false,
+            occurrence,
+            kind: childValue.type,
+            value: valuePreview?.text ?? null,
+            valueTruncated: valuePreview?.truncated ?? false,
+            startLine: childLocation.start.line,
+            endLine: childLocation.end.line,
+            childCount: childValue.type === 'block' ? childValue.entries.length : 0,
+        };
+    });
+    const children = [];
+    let childBytes = 2;
+    for (const child of candidates) {
+        const bytes = Buffer.byteLength(JSON.stringify(child), 'utf8') + 1;
+        if (childBytes + bytes > 6000)
+            break;
+        children.push(child);
+        childBytes += bytes;
+    }
+    return {
+        ...read,
+        fromLine,
+        navigation: {
+            keyPath: resolvedPath,
+            startLine: location.start.line,
+            startColumn: location.start.column,
+            endLine: location.end.line,
+            endColumn: location.end.column,
+            children,
+            omittedChildren: Math.max(0, entries.length - options.childOffset - children.length),
+            nextChildOffset: options.childOffset + children.length < entries.length
+                ? options.childOffset + children.length
+                : null,
+        },
+    };
+}

package/dist/hoi4_agent_tools/schemas/reference.js

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

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

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

package/dist/hoi4_agent_tools/version.js

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

package/docs/README.md

@@ -20,6 +20,7 @@ You can ask your coding agent for these tasks in ordinary language; you do not n
 ## See the results
 
 - [Examples](examples.md): practical prompts with real renders.
+- [Latest release](https://github.com/klimPaskov/hoi4-agent-tools/releases/latest): a short introduction to the published server.
 - [Focus and technology comparisons](visual-comparisons.md): supplied game captures beside source renders.
 - [Interface comparisons](gui-comparisons.md): vanilla and Chaos Redux windows.
 

package/docs/examples.md

@@ -14,16 +14,6 @@ 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.
@@ -41,7 +31,7 @@ The [focus guide](focus.md) covers inspecting, rendering and reorganizing trees.
 [![Infantry technology folder](images/comparisons/infantry-mcp.png)](images/comparisons/infantry-mcp.png)
 
 The preview follows the loaded technology and GUI definitions, including wide equipment cards.
-The [technology comparisons](visual-comparisons.md#technology-folders) also show chemical and biological folders and explain why different source versions can produce different layouts.
+The [technology comparisons](visual-comparisons.md#technology-folders) also show a chemical folder rendered from a matching recorded source revision.
 See the [technology guide](technology.md) for grants, bonuses and doctrine paths.
 
 ## Inspect an interface before editing it

package/docs/gui.md

@@ -14,22 +14,8 @@ 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:
+An explicit tooltip request uses a visible element's `pdx_tooltip` localisation key. Supply `tooltip.target` with its inspected instance ID or a unique element name, plus viewport `x`, `y`, `width` and `padding` values.
 
-```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.

package/docs/reference.md

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

package/docs/research/reference-benchmark.md

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