hoi4-agent-tools 4.0.5 → 4.2.0

package/dist/hoi4_agent_tools/mcp/tools/analysis.js

@@ -16,6 +16,7 @@ const impactOutputSchema = strictOperationResultSchema(z
     directConsumers: nonNegativeIntegerSchema,
     transitiveConsumers: nonNegativeIntegerSchema,
     affectedFiles: nonNegativeIntegerSchema,
+    affectedFilePaths: z.array(z.string().max(1024)).max(64).optional(),
     cycles: nonNegativeIntegerSchema,
     scenarioSuites: nonNegativeIntegerSchema,
     affectedCases: nonNegativeIntegerSchema,

package/dist/hoi4_agent_tools/mcp/tools/event.js

@@ -70,6 +70,70 @@ const renderHashSchema = z
     html: sha256Schema.optional(),
 })
     .strict();
+const countMapSchema = z.record(z.string().max(256), nonNegativeIntegerSchema);
+const inlineIdsSchema = z.array(z.string().max(256)).max(20);
+/** Bounded inline answer of an inspection; see docs/events.md. */
+const eventInspectSummarySchema = z
+    .object({
+    issues: nonNegativeIntegerSchema.optional(),
+    byClassification: countMapSchema.optional(),
+    byLayer: countMapSchema.optional(),
+    topCodes: countMapSchema.optional(),
+    findings: z
+        .array(z
+        .object({
+        code: z.string().max(256),
+        classification: z.enum([
+            'confirmed_error',
+            'probable_defect',
+            'design_warning',
+            'unresolved_analysis',
+        ]),
+        confidence: z.enum(['confirmed', 'high', 'medium', 'low', 'unresolved']),
+        message: z.string().max(300),
+        path: z.string().max(1024).optional(),
+        line: nonNegativeIntegerSchema.optional(),
+        subject: z.string().max(1024).optional(),
+    })
+        .strict())
+        .max(10)
+        .optional(),
+    trace: z
+        .object({
+        nodes: nonNegativeIntegerSchema,
+        edges: nonNegativeIntegerSchema,
+        events: nonNegativeIntegerSchema,
+        eventIds: inlineIdsSchema,
+        boundaryNodes: nonNegativeIntegerSchema,
+        truncated: z.boolean(),
+    })
+        .strict()
+        .optional(),
+    entryPoints: nonNegativeIntegerSchema.optional(),
+    entryKinds: countMapSchema.optional(),
+    automaticEvents: nonNegativeIntegerSchema.optional(),
+    callerlessTriggeredEvents: nonNegativeIntegerSchema.optional(),
+    callerlessTriggeredByLayer: countMapSchema.optional(),
+    callerlessTriggeredEventIds: inlineIdsSchema.optional(),
+    cycles: nonNegativeIntegerSchema.optional(),
+    found: z.boolean().optional(),
+    steps: nonNegativeIntegerSchema.optional(),
+    eventIds: inlineIdsSchema.optional(),
+    failureReason: z.string().max(64).optional(),
+    failureMessage: z.string().max(1024).optional(),
+    unresolvedAssumptions: nonNegativeIntegerSchema.optional(),
+    direct: nonNegativeIntegerSchema.optional(),
+    upstream: nonNegativeIntegerSchema.optional(),
+    downstream: nonNegativeIntegerSchema.optional(),
+    stateAccesses: nonNegativeIntegerSchema.optional(),
+    affectedRoots: nonNegativeIntegerSchema.optional(),
+    affectedTerminals: nonNegativeIntegerSchema.optional(),
+    wouldDisconnect: nonNegativeIntegerSchema.optional(),
+    wouldDisconnectTerminals: nonNegativeIntegerSchema.optional(),
+    unresolved: nonNegativeIntegerSchema.optional(),
+    sampleDownstream: z.array(z.string().max(1024)).max(20).optional(),
+})
+    .strict();
 const eventInspectDataSchema = z
     .object({
     mode: eventInspectModeSchema,
@@ -78,6 +142,7 @@ const eventInspectDataSchema = z
     graphHash: sha256Schema,
     counts: eventGraphCountsSchema,
     helperExpansion: helperExpansionSummarySchema.optional(),
+    summary: eventInspectSummarySchema.optional(),
     boundary: inspectBoundarySchema,
 })
     .strict();
@@ -93,6 +158,7 @@ const eventRenderOutputSchema = strictOperationResultSchema(z
         selectedNodes: nonNegativeIntegerSchema,
         omittedNodes: nonNegativeIntegerSchema,
         branchRenders: nonNegativeIntegerSchema,
+        omittedBranchRenders: nonNegativeIntegerSchema,
     }),
     boundary: z
         .object({

package/dist/hoi4_agent_tools/mcp/tools/map.js

@@ -105,7 +105,7 @@ const mapRenderDataSchema = z
 const mapInspectOutputSchema = strictOperationResultSchema(z.union([mapWorkspaceInspectDataSchema, mapRenderDataSchema]));
 const mapPlanOutputSchema = strictOperationResultSchema(z
     .object({
-    execution: z.enum(['applied', 'blocked', 'unchanged']),
+    execution: z.enum(['applied', 'blocked', 'unchanged', 'preview']),
     allocations: z.array(allocationEvidenceSchema).max(100),
     operationBlockers: z.array(operationBlockerDataSchema).max(100),
     expectedChangedBounds: changedBoundsSchema.nullable(),
@@ -116,6 +116,19 @@ const mapPlanOutputSchema = strictOperationResultSchema(z
     semanticDiffTruncated: z.boolean(),
     fileCount: nonNegativeIntegerSchema,
     artifactCount: nonNegativeIntegerSchema,
+    preview: z
+        .object({
+        offlineRepresentation: z.literal(true),
+        width: nonNegativeIntegerSchema,
+        height: nonNegativeIntegerSchema,
+        provinces: nonNegativeIntegerSchema,
+        states: nonNegativeIntegerSchema,
+        regions: nonNegativeIntegerSchema,
+        countries: nonNegativeIntegerSchema,
+        warningCount: nonNegativeIntegerSchema,
+    })
+        .strict()
+        .optional(),
 })
     .strict());
 const artifactProducing = {
@@ -136,7 +149,7 @@ export const mapTaskTools = [
     {
         name: 'hoi4.map_rewrite',
         title: 'Build a world or edit the map',
-        description: 'Build a world, split or merge states, move or renumber provinces, and update script references. Regenerate building positions and supply networks. Example: {"operations":[{"id":"s1","kind":"create_state","provinceIds":[120,121],"displayName":"New State"}]}. Returns changed IDs, a summary of edits and a render.',
+        description: 'Build a world from a local reference image or edit provinces, states, regions and supply. Example: {"preview":true,"operations":[{"kind":"create_world","reference":{"imagePath":"references/world.png"}}]}. Preview first to check coastlines, terrain and provisional countries; omit preview to write the generated map and starting scenario. Reviewed masks and labels refine ambiguous artwork. Returns counts, diagnostics and linked PNGs. Offline validation does not prove game playability.',
         inputSchema: mapRewriteRequestSchema,
         outputSchema: mapPlanOutputSchema,
         annotations: {

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

@@ -1,7 +1,7 @@
 import { ServiceError } from '../core/result.js';
 import { decodeSource } from '../core/source/encoding.js';
 import { readBoundedJsonLines } from './lines.js';
-import { scanImpactSemanticReferences } from '../core/impact-semantic.js';
+import { IMPACT_SEMANTIC_MAX_REFERENCES, scanImpactSemanticReferences, } from '../core/impact-semantic.js';
 import { parseClausewitz } from '../core/source/parser.js';
 import { navigateSource } from './source-navigation.js';
 import { locatePatterns, locateSource } from './source-locate.js';
@@ -126,7 +126,9 @@ export async function sourceLookup(engine, workspaceId, input, principal, signal
     });
     let semantic = input.includeReferences ? semanticCache.get(snapshot) : undefined;
     if (input.includeReferences && semantic === undefined) {
-        semantic = scanImpactSemanticReferences(snapshot, 200_000, { includeOnActions: true });
+        semantic = scanImpactSemanticReferences(snapshot, IMPACT_SEMANTIC_MAX_REFERENCES, {
+            includeOnActions: true,
+        });
         semanticCache.set(snapshot, semantic);
     }
     const referenceIdentities = new Set();

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

@@ -143,6 +143,10 @@ export const mapRewriteRequestSchema = z
     .object({
     workspaceId: workspaceIdSchema,
     operations: z.array(compactMapOperationSchema).min(1).max(100),
+    preview: z
+        .boolean()
+        .default(false)
+        .describe('Return generated reference, terrain and political previews and counts without changing mod files.'),
     diffScale: z.number().int().min(1).max(16).optional(),
     requestKey: backgroundRequestKeySchema.optional(),
 })

package/dist/hoi4_agent_tools/schemas/map.js

@@ -1,7 +1,15 @@
 import { z } from 'zod/v4';
 import { renderDimensionViolation, RENDER_MAX_DIMENSION } from '../core/render-budget.js';
 import { MAP_MASK_CELL_LIMIT, MAP_SELECTED_PIXEL_LIMIT } from '../map/limits.js';
+import { workspaceRelativePathSchema } from './common.js';
 const identifier = z.string().min(1).max(256);
+// eslint-disable-next-line no-control-regex -- portable JSON Schema pattern rejects grammar-breaking controls.
+const worldNamePattern = /^[^\u0000-\u001f\u007f]+$/u;
+const worldName = z
+    .string()
+    .min(1)
+    .max(64)
+    .regex(worldNamePattern, 'World names must not contain control characters');
 const stateId = z.number().int().positive();
 const provinceId = z.number().int().min(0);
 const provinceTypeSchema = z.enum(['land', 'sea', 'lake']);
@@ -18,6 +26,83 @@ const operationBase = {
     id: identifier,
     summary: z.string().max(1000).optional(),
 };
+const referencePointSchema = z
+    .object({ x: z.number().min(0).max(1), y: z.number().min(0).max(1) })
+    .strict();
+const referenceKindSchema = z.enum([
+    'sea',
+    'land',
+    'plains',
+    'forest',
+    'desert',
+    'mountain',
+    'snow',
+    'lake',
+    'volcano',
+    'hills',
+    'marsh',
+    'jungle',
+]);
+const referencePolygonSchema = z.array(referencePointSchema).min(3).max(1_000);
+const referenceImagePathSchema = workspaceRelativePathSchema.refine((value) => !value.includes(':') && /\.(?:png|jpe?g|webp)$/iu.test(value), 'Reference must be a workspace-relative PNG, JPEG or WebP file');
+/** Optional controls refine automatic interpretation; a single imagePath is sufficient. */
+export const worldReferenceSchema = z
+    .object({
+    imagePath: referenceImagePathSchema,
+    politicalImagePath: referenceImagePathSchema.optional(),
+    terrainImagePath: referenceImagePathSchema.optional(),
+    heightImagePath: referenceImagePathSchema.optional(),
+    mode: z
+        .enum(['auto', 'illustrated', 'satellite', 'sketch', 'political', 'grayscale'])
+        .optional(),
+    crop: z
+        .object({
+        x: z.number().int().min(0),
+        y: z.number().int().min(0),
+        width: z.number().int().positive().max(65_536),
+        height: z.number().int().positive().max(65_536),
+    })
+        .strict()
+        .optional(),
+    ignoreMasks: z.array(referencePolygonSchema).max(64).optional(),
+    annotations: z
+        .array(z.object({ kind: referenceKindSchema, polygon: referencePolygonSchema }).strict())
+        .max(128)
+        .optional(),
+    riverAnnotations: z.array(z.array(referencePointSchema).min(2).max(1_000)).max(128).optional(),
+    palette: z
+        .array(z.object({ kind: referenceKindSchema, color: rgbSchema }).strict())
+        .max(64)
+        .optional(),
+    coastDetail: z.number().min(0).max(1).optional(),
+    labels: z
+        .array(z
+        .object({
+        name: worldName,
+        x: z.number().min(0).max(1),
+        y: z.number().min(0).max(1),
+        kind: z.enum(['state', 'country', 'city', 'sea', 'region', 'mountain', 'geography']),
+    })
+        .strict())
+        .max(2_048)
+        .optional(),
+    cities: z
+        .array(z
+        .object({
+        name: worldName,
+        x: z.number().min(0).max(1),
+        y: z.number().min(0).max(1),
+        countryTag: z
+            .string()
+            .regex(/^[A-Z][A-Z0-9]{2}$/u)
+            .optional(),
+    })
+        .strict())
+        .max(200)
+        .optional(),
+})
+    .strict()
+    .describe('Generate from one local reference image. Optional controls use normalized 0..1 source coordinates; crop uses source pixels. Labels and political semantics may need refinement.');
 const moveStateDistributionSchema = z
     .object({
     stateValues: z.enum(['retain-in-current-states', 'proportional-by-land-pixels']),
@@ -473,8 +558,15 @@ export const mapOperationSchema = z.discriminatedUnion('kind', [
         .object({
         ...operationBase,
         kind: z.literal('create_world'),
-        width: z.number().int().min(256).max(8_192).multipleOf(256).default(1_024),
-        height: z.number().int().min(256).max(4_096).multipleOf(256).default(512),
+        worldName: worldName.optional(),
+        startingScenario: z
+            .boolean()
+            .optional()
+            .describe('Include basic starting units and stockpiles and replace old-world startup/AI geography. Defaults on for reference-image worlds.'),
+        id: identifier.default('world'),
+        reference: worldReferenceSchema.optional(),
+        width: z.number().int().min(256).max(8_192).multipleOf(256).optional(),
+        height: z.number().int().min(256).max(4_096).multipleOf(256).optional(),
         seed: z.number().int().min(0).max(2_147_483_647).default(1),
         landCoverage: z.number().min(0.05).max(0.9).default(0.35),
         continents: z.number().int().min(1).max(12).default(3),
@@ -485,28 +577,29 @@ export const mapOperationSchema = z.discriminatedUnion('kind', [
             .describe('Land outlines in top-left pixel coordinates; omit for generated continents.'),
         landProvincePixels: z.number().int().min(60).max(50_000).default(400),
         seaProvincePixels: z.number().int().min(200).max(200_000).default(2_500),
-        provincesPerState: z.number().int().min(1).max(64).default(5),
-        landProvincesPerRegion: z.number().int().min(2).max(400).default(25),
-        seaProvincesPerRegion: z.number().int().min(1).max(200).default(10),
+        provincesPerState: z.number().int().min(1).max(64).optional(),
+        landProvincesPerRegion: z.number().int().min(2).max(400).optional(),
+        seaProvincesPerRegion: z.number().int().min(1).max(200).optional(),
         countries: z
             .array(z
             .object({
             tag: z.string().regex(/^[A-Z][A-Z0-9]{2}$/u),
-            name: z.string().min(1).max(64),
-            adjective: z.string().min(1).max(64).optional(),
+            name: worldName,
+            adjective: worldName.optional(),
             color: rgbSchema.optional(),
             share: z.number().min(0.05).max(100).optional(),
             ideology: z.enum(['democratic', 'communism', 'fascism', 'neutrality']).optional(),
         })
             .strict())
             .min(1)
-            .max(200),
-        continentNames: z.array(z.string().min(1).max(64)).max(12).optional(),
+            .max(200)
+            .optional(),
+        continentNames: z.array(worldName).max(12).optional(),
         startDate: z
             .string()
             .regex(/^\d{3,4}\.\d{1,2}\.\d{1,2}$/u)
             .default('1936.1.1'),
-        rivers: z.number().int().min(0).max(500).default(8),
+        rivers: z.number().int().min(0).max(500).optional(),
         replaceBaseGame: z
             .boolean()
             .default(true)

package/dist/hoi4_agent_tools/schemas/transaction.js

@@ -1,8 +1,15 @@
 import { z } from 'zod/v4';
-import { TRANSACTION_MAX_APPLIED_FILES, TRANSACTION_MAX_ARTIFACTS, TRANSACTION_MAX_DIAGNOSTICS, TRANSACTION_MAX_FILES, TRANSACTION_MAX_OPERATIONS, TRANSACTION_MAX_READ_DEPENDENCIES, TRANSACTION_MAX_VALIDATION_CHECKS, } from '../core/transaction-limits.js';
+import { TRANSACTION_MAX_APPLIED_FILES, TRANSACTION_MAX_ARTIFACTS, TRANSACTION_MAX_DIAGNOSTICS, TRANSACTION_MAX_FILES, TRANSACTION_MAX_OPERATIONS, TRANSACTION_MAX_PENDING_FILES, TRANSACTION_MAX_READ_DEPENDENCIES, TRANSACTION_MAX_VALIDATION_CHECKS, } from '../core/transaction-limits.js';
 import { TRANSACTION_VERSION } from '../version.js';
 import { diagnosticSchema, workspaceIdSchema, workspaceRelativePathSchema } from './common.js';
 const sha256Schema = z.string().regex(/^[a-f0-9]{64}$/u);
+const compatibleTransactionVersion = z.union([z.literal(1), z.literal(TRANSACTION_VERSION)]);
+const fileIdentitySchema = z
+    .object({
+    device: z.string().regex(/^(0|[1-9][0-9]{0,39})$/u),
+    inode: z.string().regex(/^(0|[1-9][0-9]{0,39})$/u),
+})
+    .strict();
 const identifierSchema = z.string().min(1).max(256);
 const summarySchema = z.string().max(4096);
 const mediaTypeSchema = z.string().min(1).max(255);
@@ -55,7 +62,7 @@ const transactionFileSchema = z
     .strict();
 const transactionPlanPayloadSchema = z
     .object({
-    version: z.literal(TRANSACTION_VERSION),
+    version: compatibleTransactionVersion,
     workspaceId: workspaceIdSchema,
     principal: z.string().max(1024).nullable(),
     rootFingerprint: sha256Schema,
@@ -72,7 +79,7 @@ const transactionPlanPayloadSchema = z
     .strict();
 export const transactionManifestSchema = z
     .object({
-    version: z.literal(TRANSACTION_VERSION),
+    version: compatibleTransactionVersion,
     revision: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER),
     transactionId: z.string().regex(/^txn_[0-9a-f-]{36}$/u),
     workspaceId: workspaceIdSchema,
@@ -98,6 +105,16 @@ export const transactionManifestSchema = z
     artifacts: z.array(artifactLinkSchema).max(TRANSACTION_MAX_ARTIFACTS),
     executionArtifacts: z.array(artifactLinkSchema).max(TRANSACTION_MAX_ARTIFACTS).optional(),
     appliedFiles: z.array(workspaceRelativePathSchema).max(TRANSACTION_MAX_APPLIED_FILES),
+    pendingFiles: z
+        .array(z
+        .object({
+        relativePath: workspaceRelativePathSchema,
+        beforeIdentity: fileIdentitySchema.nullable(),
+        stagedIdentity: fileIdentitySchema.nullable(),
+    })
+        .strict())
+        .max(TRANSACTION_MAX_PENDING_FILES)
+        .optional(),
     rollbackStatus: z.enum(['available', 'applied', 'failed']),
     failure: z.object({ code: identifierSchema, message: summarySchema }).strict().optional(),
 })

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 = '4.0.5';
+export const PACKAGE_VERSION = '4.2.0';
 export const MCP_PROTOCOL_VERSION = LATEST_PROTOCOL_VERSION;
 export const CONFIG_VERSION = 1;
-export const TRANSACTION_VERSION = 1;
+export const TRANSACTION_VERSION = 2;

package/docs/analysis.md

@@ -58,6 +58,8 @@ Malformed, missing, or oversized suite files produce explicit partial coverage.
 The graph includes active and overridden definitions, direct and transitive consumers, source locations, state-key reads and writes, and coverage limits.
 It connects source-backed event, focus, decision, idea, technology, scripted-helper, localisation, GUI, sprite, and texture references where a typed static edge can be established.
 Unresolved dynamic names, missing definitions, skipped sources, cycles, and traversal limits remain explicit in the report.
+A dynamic reference counts against completeness only when it names a symbol kind the traversal reaches, so `activate_decision = event_target:choice` affects the impact of a decision but not of an idea that no decision consumes.
+`data.affectedFilePaths` lists up to 64 affected files; the result's `changedFiles` stays empty because the analysis never writes.
 An affected file is a source dependency lead, not a claim that the game executed that path.
 
 ## Decisions and missions
@@ -99,6 +101,8 @@ The inventory lists active decisions, category fragments, overridden source defi
 Category and decision `allowed`, `visible`, and `available` results remain separate; mission visibility is reported as ignored where documented.
 Target selection covers explicit lists and arrays plus supported state ownership, control, and continent filters.
 When a target, flag, variable, or helper input is unknown, the corresponding gate remains unresolved.
+This includes `has_variable` and `has_event_target`: an undeclared variable or event target is unknown, not absent, unless the scenario sets `closedFlags: true`.
+AI weights use probability adapters verified for one game version. On another installed version the report keeps the gate, cost and lifecycle evidence, marks the AI part unresolved and returns a `PROBABILITY_GAME_VERSION_UNSUPPORTED` warning.
 
 Costs distinguish automatic engine political-power payment from a custom affordability trigger and its separate `complete_effect` payment.
 The report identifies direct deductions, possible double payment, missing direct payment, conditional or helper-dependent paths, repeatability, cooldowns, removal, activation, cancellation, and mission timeout paths.

package/docs/events.md

@@ -26,6 +26,18 @@ For a large helper closure, use [bounded helper expansion](helper-expansion.md)
 
 The compact response summarizes the result. Small scan resources contain the complete graph; large scan resources contain exact totals, grouped inventories, representative diagnostics, and the revision needed for focused follow-up queries. Large focused scans keep direct event and on-action evidence, call sites, state accesses, and source locations while leaving helper expansion and workspace-wide lifecycle analysis explicit as deferred boundaries. This keeps an agent's prompt and artifact storage bounded without allowing a broad scan to exhaust the MCP process.
 
+`data.summary` answers the request inline before the linked report is opened. `scan`, `lint` and `state_flow` return the number of findings in the selection, counts by classification, the ten most frequent codes and the ten most severe findings with their path, line and subject. `trace` adds the traced node, edge and event counts with up to twenty event IDs. `roots` returns entry-point counts by kind, automatic and callerless triggered events, and cycle counts. `data.counts` still describes the whole analyzed graph, including vanilla events.
+
+`explain_path` adds whether a route was found, its step count, event IDs and failure reason; `impact` adds direct, upstream, downstream, affected-root and disconnection counts.
+
+Workspace-wide modes expand scripted helpers up to a fixed work ceiling. On a very large mod the expansion stops there with an `EVENT_HELPER_PROJECTION_LIMIT` finding that names the completed and total roots; calls from the remaining roots stay structural, and a namespace, event or file selector or `helper_expansion` mode covers them. An unselected overview render returns the overview and as many branch renders as the request's raster budget allows, reporting the rest in `omittedBranchRenders`.
+
+A `scan` retains the complete graph as a snapshot artifact only up to 128 MiB of canonical JSON. A larger graph, such as a mod with thousands of events and hundreds of thousands of state accesses, returns the scan report with the info diagnostic `EVENT_GRAPH_SNAPSHOT_OMITTED`; comparisons then use the revisions this server holds in memory.
+
+An assignment such as `custom_effect = yes` is reported as a missing helper only where it can execute: in effect blocks of events, decisions, focuses and on-actions, inside scope and loop effects, and in conventionally named effect blocks (`on_*`, `*_effect`, `*_effects`) of other definition files. Arguments of native effects such as `add_building_construction = { instant_build = yes }`, condition blocks such as `visible`, `available`, `allowed`, `ai_will_do`, `NOT` or `any_*`, and data fields of ideas, raids, special projects and scripted GUIs are not calls.
+
+A read is linked to a writer of the same name when the writer is a temporary variable, a write inside a scripted helper (whose scope is decided by its caller), a scope-prefixed name such as `GER.value`, or the array behind `entries^num`. `event_target:name` reads targets saved by `save_event_target_as` and `save_global_event_target_as`; `global_event_target:name` reads only global targets. A finding is kept per owner and subject, so different flags or targets read in one event remain separate findings.
+
 Selectors use one of these forms:
 
 ```json

package/docs/map.md

@@ -3,6 +3,51 @@
 Generate a new world, split states and reshape provinces. Preview the map and update the scripts that refer to it.
 Use `hoi4.map_inspect` and `hoi4.map_rewrite` for provinces, states, regions, supply, railways, positions, ownership, resources, buildings and localisation.
 
+## Generate a world from one image
+
+Put a PNG, JPEG or WebP reference in your mod workspace, then call `hoi4.map_rewrite`:
+
+```json
+{
+  "operations": [{ "kind": "create_world", "reference": { "imagePath": "references/sketch.png" } }]
+}
+```
+
+For a first run, copy the project-owned [synthetic hand sketch](images/reference-maps/sketch.png) to `references/sketch.png` in your mod. The [synthetic flat political map](images/reference-maps/political.png) is another ready-made input; copy it to `references/political.png` and change `imagePath` accordingly. The examples are intentionally small and contain no third-party artwork.
+
+The server generates the complete map and supporting country/state files in one validated atomic rewrite. No country list, manual masks, coordinates or separate apply call is required. `workspaceId` defaults to the current mod, and the operation ID defaults to `world`. The default reference world is 5632 by 2048 pixels; the artwork retains its aspect ratio within sea padding. Set `width` and `height` to choose other multiples of 256 within the map pixel budget. Reference defaults group 12 provinces per state, 60 land provinces or 30 sea provinces per strategic region, and request 80 rivers; explicit values override these defaults.
+
+Add `"preview": true` at the top level to return offline reference, terrain and political PNGs, a comparison and counts without changing mod files. Repeat the request without `preview` to apply it. Preview uses the same extraction, generation and validation as application, and never launches the game.
+
+Use a cleaned, unlabelled raster for production generation. Handwriting, sheet joins and map frames can become false islands or relief. Keep the original unchanged, remove these marks in a separate reference, compare its coastlines with the original, then inspect the terrain preview before writing. Supply reviewed names through `reference.labels` and `reference.cities`; an explicit label list, including an empty list, prevents OCR from adding unreviewed names. The server does not automatically redraw artwork or promise lossless interpretation of every map.
+
+Reference worlds enable `startingScenario` by default; procedural worlds keep it off unless requested. The starter includes a bookmark, country histories, provisional councils, recruitable infantry templates, two equipped divisions per country, stockpiles, an infantry production line, supply and building positions. `worldName` sets the bookmark title. Demographics, industry and ownership remain provisional. Existing world events, decisions, startup hooks and country-specific AI strategy folders are replaced; shared game systems remain dependencies and can report unused-definition warnings. Generated names use the localisation replacement folder, and explicit country color declarations match the flags. Inherited country tags receive inactive histories. The adjacent launcher `.mod` file must mirror the generated `descriptor.mod` replacement paths. The server cannot enable a launcher playset or test a campaign.
+
+Regeneration records generated paths and hashes in `.hoi4-agent-world.json`. It removes obsolete recorded outputs through the same atomic rewrite and refuses to overwrite recorded files edited since generation. Preserve that inventory. Unrelated authored files are not deleted; validation can block a rebuild if they conflict with the generated world. Large world diffs remain linked evidence so counts and preview images fit within the MCP response budget.
+
+Automatic interpretation recognizes visual land/water and terrain cues, derives relief and drainage, and uses flat political colors when available. Offline English OCR supplies candidate names and city locations; recognized text bounds are masked before terrain classification so ocean labels do not become islands. Masks near a coastline can soften its detail and produce a review warning. Decorative text, handwriting, unknown languages and visually ambiguous borders may be missed or misclassified; diagnostics identify uncertain interpretation and deterministic defaults. Population, resources, buildings and country ownership inferred from artwork are generated assumptions, not historical facts or a balance assessment.
+
+Optional `reference` controls refine the same call:
+
+| Field                                                       | Meaning                                                                                                                                                  |
+| ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `politicalImagePath`, `terrainImagePath`, `heightImagePath` | Additional aligned workspace images for political regions, terrain cues or grayscale height.                                                             |
+| `mode`                                                      | `auto`, `illustrated`, `satellite`, `sketch`, `political` or `grayscale`.                                                                                |
+| `crop`                                                      | `{x,y,width,height}` in original source pixels.                                                                                                          |
+| `ignoreMasks`                                               | Polygons that exclude legends, frames or decorative areas.                                                                                               |
+| `annotations`                                               | `{kind,polygon}` semantic polygons: sea, land, plains, lake, forest, desert, mountain, snow, volcano, hills, marsh or jungle.                            |
+| `riverAnnotations`                                          | Paths for known rivers.                                                                                                                                  |
+| `palette`                                                   | `{kind,color:{r,g,b}}` color cues for the same semantic kinds.                                                                                           |
+| `coastDetail`                                               | Detail preservation from 0 to 1.                                                                                                                         |
+| `cities`                                                    | `{name,x,y,countryTag?}` reviewed city and optional capital anchors. `countryTag` must name a generated country.                                         |
+| `labels`                                                    | `{name,x,y,kind}` reviewed names for `state`, `country`, `city`, `sea`, `region`, `mountain` or `geography`; useful for handwritten or ambiguous labels. |
+
+Reviewed geography labels preserve names for lakes, rivers, forests and other features in localisation and generated-world provenance. They do not invent a native HOI4 map entity or turn a geographic label into a city or victory point.
+
+All annotation positions and polygons use normalized 0 to 1 coordinates relative to the original, uncropped reference, with the origin at its top left. Crop uses source pixels instead. Explicit `countries` on the operation supplies reviewed country tags, names, colors and relative shares. If borders or names cannot be inferred reliably, the server generates named defaults and reports the assumptions. Manual controls are optional and never change the original image.
+
+Only relative paths inside the authorized mod workspace are accepted. URLs, absolute paths, traversal, generated storage and symlink escapes are refused. The source is bounded to 1 GiB and 300 million decoded pixels; analysis uses a reduced working PNG up to 3072 pixels per side. The verified source handle is streamed into an exclusive private temporary snapshot, and the same copied bytes are hashed and decoded; the snapshot is removed on completion, failure or cancellation. The original SHA-256 is checked again before writing, using a streaming read, so replacing the source after preparation blocks application. CI image fixtures are synthetic and project-owned. Attributed comparison images may be published separately with permission and remain outside the npm package.
+
 ## Inspect and navigate the complete map
 
 `hoi4.map_inspect` finds map problems and returns a full-map PNG plus a searchable, clickable HTML navigator by default. The navigator supports pan, zoom, fit-to-map, search by numeric ID, localisation key, or localised name, and exact click lookup for province, state, and strategic-region IDs. Hovering reports both top-left bitmap coordinates and bottom-left HOI4 map coordinates.

package/docs/third-party-notices.md

@@ -8,4 +8,10 @@ Copyright 2011 The Roboto Project Authors (<https://github.com/googlefonts/robot
 
 Roboto is licensed under the SIL Open Font License, Version 1.1 (`OFL-1.1`). The complete license text is distributed as `LICENSE` in the installed `@fontsource-variable/roboto` package. The font package is pinned in `package.json` and the published `npm-shrinkwrap.json`; generated SVG/PNG documents may contain derived glyph outlines or pixels as permitted by the OFL.
 
+## Offline reference-image OCR
+
+`tesseract.js` version 7.0.0 and its `tesseract.js-core` dependency provide the local WebAssembly OCR engine under Apache-2.0. English trained data is installed through `@tesseract.js-data/eng` version 1.0.0. That package declares MIT licensing for its packaging; its upstream [tessdata repository](https://github.com/naptha/tessdata) distributes Tesseract language data under [Apache-2.0](https://github.com/naptha/tessdata/blob/gh-pages/LICENSE). The project uses the unmodified `4.0.0_best_int/eng.traineddata.gz` model from the dependency. No reference artwork or language model is copied into project fixtures or source assets.
+
+These dependencies are pinned by `package.json` and `npm-shrinkwrap.json`. OCR uses the installed worker, engine and language bytes without runtime network downloads or external OCR executables. The engine and language data retain their upstream licenses.
+
 The application source remains licensed under Apache-2.0 as stated in the repository [LICENSE](../LICENSE). Third-party components retain their respective licenses.