hoi4-agent-tools 3.6.0 → 3.8.0

package/dist/hoi4_agent_tools/schemas/reference.js

@@ -26,6 +26,7 @@ export const referenceReadRequestSchema = z
     workspaceId: workspaceIdSchema,
     id: z.string().regex(/^[a-f0-9]{64}$/u),
     revision: z.string().regex(/^[a-f0-9]{64}$/u),
+    source: referenceSourceSchema.optional(),
     startLine: z.number().int().min(1).optional(),
     startColumn: z.number().int().min(1).optional(),
     maxLines: z.number().int().min(1).max(80).default(40),
@@ -39,10 +40,25 @@ 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,
-    symbol: z.string().trim().min(1).max(256),
+    symbol: z.string().trim().min(1).max(256).optional(),
+    /** Locate mode: a scanned source path (`mod:events/a.txt`, `events/a.txt`, or absolute). */
+    path: z.string().trim().min(1).max(4096).optional(),
+    line: z.number().int().min(1).optional(),
+    column: z.number().int().min(1).optional(),
     kind: z
         .string()
         .regex(/^[a-z][a-z0-9_]{0,63}$/u)
@@ -51,6 +67,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
@@ -58,7 +78,39 @@ export const sourceLookupRequestSchema = z
         .regex(/^[a-f0-9]{64}$/u)
         .optional(),
 })
-    .strict();
+    .strict()
+    .superRefine((value, context) => {
+    const locating = value.path !== undefined || value.line !== undefined;
+    if (locating === (value.symbol !== undefined))
+        context.addIssue({
+            code: 'custom',
+            path: ['symbol'],
+            message: 'Provide either symbol, or path and line to locate a source position',
+        });
+    if (locating && (value.path === undefined || value.line === undefined))
+        context.addIssue({
+            code: 'custom',
+            path: ['line'],
+            message: 'Locating a source position requires both path and line',
+        });
+    if (!locating && value.column !== undefined)
+        context.addIssue({
+            code: 'custom',
+            path: ['column'],
+            message: 'column applies only with path and line',
+        });
+    if (locating &&
+        (value.keyPath !== undefined ||
+            value.view === 'structure' ||
+            value.fromLine !== undefined ||
+            value.fromColumn !== undefined ||
+            value.expectedRevision !== undefined))
+        context.addIssue({
+            code: 'custom',
+            path: ['path'],
+            message: 'Navigation options apply to a symbol lookup; locate first, then pass its keyPath',
+        });
+});
 const hash = z.string().regex(/^[a-f0-9]{64}$/u);
 const line = z.number().int().min(1);
 const count = z.number().int().min(0);
@@ -67,6 +119,7 @@ const coverage = z
     files: count,
     sections: count,
     unavailable: z.boolean(),
+    included: z.boolean(),
 })
     .strict();
 const coverageBySource = z
@@ -84,12 +137,16 @@ export const referenceSectionSchema = z
     endLine: line,
     excerpt: z.string().max(300),
     authority: z.string().max(80),
+    /** The cited line that best matches the query; start a bounded read here. */
+    matchLine: line.optional(),
 })
     .strict();
 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 +166,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,15 +175,62 @@ export const referenceContextDataSchema = z
     .strict();
 export const sourceLookupDataSchema = z
     .object({
+    sourceScope: z.enum([
+        'workspace_index',
+        'event_definitions',
+        'event_consumers',
+        'helper_definitions',
+        'source_location',
+    ]),
     revision: hash,
     complete: z.boolean(),
     skippedSourceCount: count,
     definitionCount: count,
+    definitionsTruncated: z.boolean(),
     referencesIncluded: z.boolean(),
     referenceCount: count,
     referencesTruncated: z.boolean(),
     referencesComplete: z.boolean(),
     unresolvedReferenceCount: count,
+    /** Indexed identifiers within three edits of a symbol that has no definition. */
+    suggestions: z.array(z.string().max(1024)).max(5).optional(),
+    location: z
+        .object({
+        path: z.string().max(4096),
+        rootKind: z.string().max(32),
+        loadOrder: count,
+        shadowed: z.boolean(),
+        line,
+        column: line,
+        text: z.string().max(300),
+        owners: z
+            .array(z
+            .object({
+            kind: z.string().max(64),
+            id: z.string().max(1024),
+            startLine: line,
+            endLine: line,
+            overridden: z.boolean(),
+        })
+            .strict())
+            .max(8),
+        chain: z
+            .array(z
+            .object({
+            key: z.string().max(128).nullable(),
+            occurrence: count,
+            index: count,
+            startLine: line,
+            endLine: line,
+        })
+            .strict())
+            .max(24),
+        chainTruncated: z.boolean(),
+        keyPath: sourceKeyPathSchema.nullable(),
+        structureAvailable: z.boolean(),
+    })
+        .strict()
+        .optional(),
     definitions: z
         .array(z
         .object({
@@ -143,6 +248,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/schemas/transaction.js

@@ -34,7 +34,7 @@ const transactionOperationSchema = z
     .strict();
 const transactionReadDependencySchema = z
     .object({
-    rootKind: z.enum(['mod', 'game', 'dependency', 'artifact', 'cache', 'fixture']),
+    rootKind: z.enum(['mod', 'game', 'dlc', 'dependency', 'artifact', 'cache', 'fixture']),
     loadOrder: z.number().int().min(0),
     relativePath: workspaceRelativePathSchema,
     sha256: sha256Schema,

package/dist/hoi4_agent_tools/technology/service.js

@@ -117,7 +117,7 @@ async function scanTechnologySources(engine, workspaceId, workspace, principal,
     const scans = await Promise.all([
         engine.scan(workspaceId, { patterns, rootKinds: ['mod', 'dependency', 'fixture'] }, principal, signal),
         ...(workspace.roots.some(({ kind }) => kind === 'game')
-            ? [engine.scan(workspaceId, { patterns, rootKinds: ['game'] }, principal, signal)]
+            ? [engine.scan(workspaceId, { patterns, rootKinds: ['game', 'dlc'] }, principal, signal)]
             : []),
     ]);
     const files = scans.flatMap(({ files }) => files.map((file) => ({ ...file })));

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.8.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/development.md

@@ -42,3 +42,9 @@ Add `HOI4_DEPENDENCY_ROOTS` as the platform path-delimited list when the externa
 The installed-game qualification also parses every shipped bitmap-font descriptor, resolves every atlas page, shapes native and enlarged glyphs, verifies deterministic raster output, and checks HOI4 localisation colours across base fonts and language overrides.
 
 See the package [Security Policy](../SECURITY.md) for private vulnerability reporting.
+
+## Dependencies
+
+`npm-shrinkwrap.json` is published and fixes the complete production dependency tree for every consumer, who no longer receive newer transitive releases on their own.
+Run `npm audit --omit=dev` and `npm audit signatures` before each release, and publish a new version with a refreshed shrinkwrap when a production advisory is fixed upstream.
+Keep `overrides` inside every dependent's declared range; consumers do not apply this package's overrides, and `tests/package/metadata.test.ts` checks each production dependency edge in the shrinkwrap against its range.

package/docs/examples.md

@@ -14,21 +14,11 @@ 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.
+> Render the mod's largest branching 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)
+[![Branching focus tree preview](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.
@@ -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 mod folder with wide equipment cards 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/map.md

@@ -18,6 +18,16 @@ Pass `tile: { x, y, width, height }` to `hoi4.map_render` for a reusable bounded
 
 Pass `area: { provinceIds, stateIds, regionIds, padding }` to render the exact bounding area of those map entities with optional pixel padding. The result reports the resolved tile coordinates. An unknown ID or an area larger than 2,048 pixels in either direction is explicit, so a narrower selection can be requested.
 
+## Catalog consistency
+
+Validation reads the active `common/terrain/*.txt` categories and `map/continent.txt` (or the continent file `default.map` names) along with the map files.
+A province whose terrain no category defines reports `MAP_TERRAIN_UNKNOWN`, and a land province with a continent number beyond the continents listed reports `MAP_CONTINENT_UNKNOWN`; continent IDs follow their order in the file.
+Seas and lakes must use a category with `is_water = yes` (`MAP_SEA_TERRAIN_INVALID`, `MAP_LAKE_TERRAIN_INVALID`), land provinces must not (`MAP_LAND_TERRAIN_WATER`), and a strategic region's `naval_terrain` must name a category with `naval_terrain = yes` (`MAP_REGION_NAVAL_TERRAIN_INVALID`).
+When no terrain category file is available, seas and lakes are checked against the base game's `ocean` and `lakes` names instead, and unknown terrain is not reported.
+
+The engine stops reading `adjacencies.csv` at its first `-1` row.
+Rows after it are not read and report `MAP_ADJACENCY_AFTER_TERMINATOR`; a file without that row reports `MAP_ADJACENCY_TERMINATOR_MISSING` as a warning, because the offline wiki describes it as required although at least one published mod omits it.
+
 ## Create states
 
 The compact `create_state` form needs selected provinces and a display name:

package/docs/reference.md

@@ -10,14 +10,57 @@ The server discovers these directories for a workspace:
 | 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.
+Markdown headings and recognizable standalone names in generated `.log` files form sections. A Markdown table row whose first cell is an identifier, such as a wiki effect, trigger, modifier, define, or on action, is also its own one-line section, so a citation can name the exact entry inside a long table. 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 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 with plain words or exact script tokens. Ranking weighs headings above body text and rare words above common ones, and it matches identifiers both whole and by their words, so "check if a state is controlled by a country" can find `is_controlled_by`. A query that names an identifier only matches sections containing it, an exact heading ranks first, and installed documentation precedes the wiki when they rank equally. Each result's `matchLine` is the cited line that best matches the query; pass it as `startLine` to `hoi4.reference_read` to land on the answer inside a long section. When several sources document the same name, the first copy keeps its place and later copies follow other distinct answers. 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.
+- When `hoi4.source_lookup` finds no definition, `suggestions` lists up to five indexed identifiers within three edits of the requested symbol, nearest first, which catches typos and near-miss names.
+- `hoi4.source_lookup` with `path` and `line` instead of `symbol` locates a source position, such as a diagnostic or a changed line in a diff. `path` may be a result path such as `mod:events/example.txt`, a path relative to a source root, or an absolute path inside one. The result names the file's layer and whether a later layer shadows it, the indexed definitions that contain the line, innermost first, and the chain of enclosing assignments with zero-based occurrences for repeated keys. Its `keyPath` starts inside the innermost definition: pass that definition's `id` as `symbol`, its `kind`, and the `keyPath` to read or list that exact block. Without `column`, the first non-blank character of the line is used. A file with parse errors returns its definitions but no structural chain. Only the requested file's folder is scanned, in every layer.
+- `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:
 
@@ -29,4 +72,4 @@ Call `hoi4.reference_context` with that input, then search `save_event_target_as
 
 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.
+See [the measured Chaos Redux reference retrieval](research/reference-benchmark.md) for actual source coverage, held-out discovery results, and response sizes. Plain-word questions still miss when the documentation uses different vocabulary, for example "national spirit" for `ideas`; search the script name directly when it is known.

package/docs/research/reference-benchmark.md

@@ -27,6 +27,45 @@ The retrieval benchmark used the local service directly. A separate real-workspa
 
 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.
 
+## Held-out discovery questions
+
+Measured on 2026-10-04 against the same local Chaos Redux wiki snapshot and installed documentation.
+The nine questions above were assembled alongside the previous ranking, so they cannot show whether a ranking change generalizes.
+Two further sets in `scripts/reference-discovery-cases.ts` phrase tasks the way an agent asks them, mostly without the script name.
+Every expected answer was checked by hand in the local files, and a case may list several acceptable sections.
+A result answers a question when its cited section contains an expected answer line; it lands when its cited line is within eight lines of that answer.
+
+The discovery set has 32 plain-word questions, five exact identifiers, and two unrelated negative queries.
+The validation set has 24 plain-word questions written before any ranking adjustment and was never used to tune it.
+
+| Set and ranking                | Answer first | Within three | Within five | Lands within three | Mean reciprocal rank |
+| ------------------------------ | -----------: | -----------: | ----------: | -----------------: | -------------------: |
+| Discovery, previous ranking    |         7/37 |        19/37 |       22/37 |              18/37 |                0.342 |
+| Discovery, field-weighted BM25 |        19/37 |        28/37 |       29/37 |              26/37 |                0.628 |
+| Validation, previous ranking   |         4/24 |         7/24 |       12/24 |               7/24 |                0.272 |
+| Validation, field-weighted     |        11/24 |        16/24 |       20/24 |              16/24 |                0.588 |
+
+The previous ranking placed four of the five exact identifiers first and did not return the `on_startup` wiki entry at all; the current one places each first, with installed documentation ahead of the wiki.
+Both returned no results for the two negative queries.
+On the original nine questions, all nine stay within five results, three rank first rather than five, and one moves from fourth to fifth.
+
+In three repeated runs, the first query after a source change took 370–386 ms to index about twelve thousand sections, compared with 147–159 ms with the previous ranking.
+Later queries took a median of 37 ms, compared with 49–63 ms, and the median ranked reply was about 3.7 KB in both.
+
+Twelve plain-word questions across both sets still miss the top five.
+Most use vocabulary the documentation does not: "national spirit" where script says `ideas`, "give a state" for `transfer_state`, "repeat effects" for `for_loop_effect`, and "build a factory" for `add_building_construction`.
+Search the script name when it is known; the ranking does not add synonyms for individual questions.
+These are 61 task questions over one documentation snapshot, not a general precision guarantee.
+
+Run both sets with:
+
+```bash
+npx tsx scripts/evaluate-reference-discovery.ts MOD_ROOT GAME_ROOT
+npx tsx scripts/evaluate-reference-discovery.ts MOD_ROOT GAME_ROOT --validation
+```
+
+The script exits with a failure when a case has no expected answer in the supplied sources.
+
 ## Compact context budgets
 
 A 2026-09-27 check of the installed 3.5.0 server found that eight GUI results could contain only wiki sections even though the installed GUI documentation was available. The 3.5.1 source qualifies limits of one, two, and eight citations across the same six work surfaces. All eighteen cases retained installed documentation; limits of two or more also retained wiki citations. Required sources excluded by the limit appeared in `omittedSources`, separately from files absent under `missing`. The nine search queries still found all expected answer-bearing sections.
@@ -40,3 +79,44 @@ For the GUI question “Where are scripted GUI click effects and triggers define
 | 8              | Installed documentation and wiki |                        0 |      5,926 |          339 |
 
 The default six-surface context bundles used 3,545–5,556 bytes including omission metadata. A smaller response is not sufficient evidence when `omittedSources` is nonempty: increase the limit or search and read those sources directly. The evaluation script fails when a compact budget drops a required source kind or silently omits its required-source pointers.
+
+## Source navigation and scan measurements
+
+On 2026-10-03, `scripts/evaluate-source-tools.ts --game-only` selected the installed `political.1` definition, listed its options, read exactly `add_political_power = -100` from its first option, and checked that command against installed documentation.
+The country-scope check succeeded and the state-scope check reported the documented mismatch.
+The evaluation retained source and documentation revisions and compared repeated reference results for equality.
+
+| Operation                      | Initial cache-enabled run | Scoped-cache run | Reply bytes |
+| ------------------------------ | ------------------------: | ---------------: | ----------: |
+| Cold event structure           |                 55,550 ms |        24,723 ms |       2,258 |
+| Repeated nested read           |                 20,936 ms |         3,565 ms |         862 |
+| Installed command check        |                  1,471 ms |        10,804 ms |       1,152 |
+| Event-consumer lookup          |   Timed out at 180,002 ms |       145,532 ms |       1,363 |
+| Repeated event-consumer lookup | Not completed in that run |        16,233 ms |       1,363 |
+
+A separate run with persistent caching disabled completed the broader lookup in 102,437 ms and its repeated lookup in 122,023 ms.
+This helped identify filesystem and cache costs; it is not a causal comparison under identical machine load.
+The candidate bounds optional cache writes, skips resident hydration, overlaps source verification, and scopes event queries to the analyser's supported owner sources.
+Its persistent cache recorded 32 writes across two bounded batches, with no invalid entries or evictions.
+The process recorded 616–625 MiB resident memory during the consumer lookups; these are sampled values, not peak-memory guarantees.
+
+Other work was running on the host, and latency varied materially.
+The command-document check was slower in the scoped-cache run, so these measurements must not be presented as an improvement for every operation or as a latency guarantee.
+The selected source index was complete, while reference completeness remained false because 2,379 dynamic references were unresolved.
+Static retrieval does not resolve those engine-dependent dispatches or establish runtime behavior.
+
+These source timings preceded the subsequent batched reference reader and glob-library replacement.
+A separate 2026-10-03 reference evaluation found all nine expected pages and answer-bearing sections and passed all eighteen compact-context cases, with no missing required sources or budget failures.
+Its six context replies used 3,616–5,627 JSON bytes.
+The candidate's complete MCP discovery list contains 35 tools and is tested against a 75 KiB ceiling.
+
+## Worker startup
+
+Five isolated readiness handshakes on 2026-10-03 averaged 2,163 ms with eager imports and 1,408 ms with authenticated domain loading.
+The individual samples were 2,056/2,570/2,349/1,857/1,985 ms and 3,213/930/995/960/942 ms respectively.
+The first changed-worker sample includes a cold TypeScript loader cache.
+These samples measure the readiness handshake without running a job, and do not establish complete request latency or throughput.
+Concurrent HTTP qualification keeps its original four-minute total request ceiling.
+Two earlier 64-request runs exceeded that ceiling for 23 and five requests respectively.
+The isolated run after domain loading passed all 64 requests in a 124.49-second test, including fixture setup and cleanup.
+Shared-host load varied between runs, so these are qualification receipts rather than a controlled throughput comparison.

package/docs/setup.md

@@ -9,6 +9,9 @@ Keep an installed copy of Hearts of Iron IV available for vanilla references, ar
 npm install --global hoi4-agent-tools
 ```
 
+The package publishes an `npm-shrinkwrap.json`, so every registry or `npx` install receives the same reviewed dependency versions.
+npm installs the image library's prebuilt binaries for every supported platform from it, about 280 MiB in total; the server loads only the one for your system.
+
 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.
 
@@ -53,6 +56,18 @@ 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.
 
+### How sources are layered
+
+Sources load in the engine's order: the base game, then each installed folder under `dlc/` and `integrated_dlc/` in order of its internal DLC ID, then dependencies, then the mod.
+A later layer replaces a file with the same path from an earlier one, so a DLC's version of an interface file is the active one and the base game's copy is reported as shadowed.
+Results name a DLC layer by its folder, for example `dlc023_man_the_guns:interface/mtg_leaders.gfx`.
+Only folders that contain a `dlcNNN.dlc` descriptor and resolve inside the game root are layers; archives inside a DLC folder are not unpacked.
+An installed DLC folder is not proof that the DLC is enabled in a particular playset; check `has_dlc` where content depends on it.
+Set `"includeGameDlc": false` on a configured workspace to analyze the base game alone.
+
+`replace_path` entries in a mod's or dependency's `descriptor.mod` unload earlier-loaded files under that folder, as the engine does, and join any `replacePaths` configured for the workspace.
+Entries that are not plain relative folders, such as `../outside` or wildcard paths, are ignored.
+
 ## Add local reference material
 
 Place an offline wiki snapshot in `paradox_wiki/` inside the mod.