hoi4-agent-tools 4.3.0 → 4.5.0

package/dist/hoi4_agent_tools/schemas/map.js

@@ -2,6 +2,8 @@ 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';
+import { geographyModelSchema, geographyPathSchema } from './geography.js';
+import { referenceSheetsDocumentSchema, referenceSheetsPathSchema } from './reference-sheets.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;
@@ -22,6 +24,59 @@ const rgbSchema = z
 })
     .strict();
 const pointSchema = z.object({ x: z.number().int().min(0), y: z.number().int().min(0) }).strict();
+const countryTagSchema = z.string().regex(/^[A-Z][A-Z0-9]{2}$/u);
+const realmPolygonSchema = z.array(pointSchema).min(3).max(10_000);
+const realmPolygonsSchema = z.array(realmPolygonSchema).min(1).max(64);
+export const workspaceRealmSchema = z
+    .object({
+    tag: countryTagSchema,
+    capital: pointSchema.describe('World pixel, top-left origin, on land; the capital province.'),
+    seeds: z
+        .array(pointSchema)
+        .max(256)
+        .optional()
+        .describe('Further world pixels whose provinces the country must own.'),
+    claim: realmPolygonsSchema
+        .optional()
+        .describe('Polygons in world pixels; land provinces more than half inside belong to the country.'),
+    exclude: realmPolygonsSchema
+        .optional()
+        .describe('Polygons in world pixels; land provinces more than half inside never belong to it.'),
+    weight: z
+        .number()
+        .min(0.05)
+        .max(100)
+        .optional()
+        .describe('Relative share of the land claims leave free; default 1.'),
+})
+    .strict();
+export const workspaceCountriesSchema = z
+    .object({
+    source: z.literal('workspace'),
+    realms: z.array(workspaceRealmSchema).min(1).max(512),
+    unowned: z
+        .array(realmPolygonSchema)
+        .max(256)
+        .optional()
+        .describe('Polygons in world pixels whose land provinces no country owns.'),
+    islands: z
+        .enum(['nearest', 'one-owner', 'unowned'])
+        .default('nearest')
+        .describe('Landmasses no country reaches: every province to the nearest capital, the whole landmass to one country, or unowned.'),
+})
+    .strict()
+    .superRefine((value, context) => {
+    const seen = new Set();
+    for (const [index, realm] of value.realms.entries()) {
+        if (seen.has(realm.tag))
+            context.addIssue({
+                code: 'custom',
+                path: ['realms', index, 'tag'],
+                message: `Country ${realm.tag} is listed twice`,
+            });
+        seen.add(realm.tag);
+    }
+});
 const operationBase = {
     id: identifier,
     summary: z.string().max(1000).optional(),
@@ -75,6 +130,28 @@ export const worldReferenceSchema = z
         .max(64)
         .optional(),
     coastDetail: z.number().min(0).max(1).optional(),
+    paletteMatch: z
+        .enum(['nearest', 'exact'])
+        .optional()
+        .describe('nearest (default) snaps every pixel to the closest palette colour. exact requires every pixel to equal a palette colour, trusts the classes as painted (no text masking, cleanup, smoothing or political inference) and fails with MAP_REFERENCE_PALETTE_UNKNOWN_COLOR naming any other colour, its count and source pixels.'),
+    sheets: referenceSheetsDocumentSchema
+        .optional()
+        .describe('Registration of a picture made of drawn sheets onto the world frame (inline; use sheetsPath for a file). Each sheet maps its part of the picture with anchor, target and scale (or affine); the registered picture is read at the resolution the sheets need and every layer derives from it. Implies fit frame; width and height are required. Annotations, masks, labels and cities then use world coordinates.'),
+    agreement: z
+        .object({
+        minLandIou: z.number().min(0).max(1).optional(),
+        warnLandIou: z.number().min(0).max(1).optional(),
+    })
+        .strict()
+        .optional()
+        .describe('With a geography model: land intersection over union between the model and this reference below minLandIou (default 0.85) blocks the write with MAP_IMPORT_SOURCES_DISAGREE; below warnLandIou (default 0.95) it is a warning. The measured value is always in map-import-report.json.'),
+    sheetsPath: referenceSheetsPathSchema
+        .optional()
+        .describe('Workspace-relative .json file holding the sheet registration (reference-sheets version 1).'),
+    fit: z
+        .enum(['contain', 'frame'])
+        .optional()
+        .describe('contain (default) centres the picture with sea padding at a working size of at most 3,072 pixels per side. frame maps the picture (or its crop) onto exactly width x height, which must be given and have the same shape within 1%, and reads it at the frame resolution.'),
     labels: z
         .array(z
         .object({
@@ -102,7 +179,156 @@ export const worldReferenceSchema = z
         .optional(),
 })
     .strict()
+    .refine((value) => value.paletteMatch !== 'exact' || (value.palette?.length ?? 0) > 0, {
+    path: ['palette'],
+    message: 'paletteMatch "exact" needs a palette that lists every colour of the picture',
+})
+    .refine((value) => value.sheets === undefined || value.sheetsPath === undefined, {
+    path: ['sheetsPath'],
+    message: 'Give the sheets inline (sheets) or by file (sheetsPath), not both',
+})
+    .refine((value) => (value.sheets === undefined && value.sheetsPath === undefined) || value.fit !== 'contain', { path: ['fit'], message: 'Registered sheets always fill the frame; omit fit or use "frame"' })
     .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.');
+/** World edge and seam policy (ADR 0061). Omit `edge` to keep land and sea as drawn. */
+export const worldEdgeSchema = z
+    .object({
+    mode: z
+        .enum(['sea-band', 'rim', 'none'])
+        .optional()
+        .describe('sea-band (default when edge is given) clears land from the east and west edges and the poles to open sea; rim ends land at the seam in an impassable snow range with impassable adjacencies across the seam; none keeps the picture and warns about land cut by the wrapping seam.'),
+    bandPx: z
+        .number()
+        .int()
+        .min(8)
+        .max(2_048)
+        .optional()
+        .describe('East and west sea band in pixels; default max(192, 4% of the width), at most a quarter of the width.'),
+    polarPx: z
+        .number()
+        .int()
+        .min(0)
+        .max(1_024)
+        .optional()
+        .describe('North and south sea band in pixels; default 64, at most a quarter of the height.'),
+    rimPx: z
+        .number()
+        .int()
+        .min(16)
+        .max(2_048)
+        .optional()
+        .describe('Rim range width in pixels for mode rim; default 160, at most a quarter of the width.'),
+})
+    .strict();
+/** Relief synthesis from a geography model (ADR 0056). */
+export const worldReliefSchema = z
+    .object({
+    scale: z
+        .enum(['vanilla', 'low', 'dramatic'])
+        .optional()
+        .describe('Height of everything above the lowland: vanilla (the default) follows the base game, low is 25% lower, dramatic 15% higher.'),
+    detail: z
+        .number()
+        .min(0)
+        .max(1)
+        .optional()
+        .describe('Full-resolution roughness of the terrain, 0 to 1; default 0.5.'),
+})
+    .strict();
+/** River network target for a geography world: a share of the land pixels. */
+export const worldRiverDensitySchema = z
+    .object({
+    density: z
+        .number()
+        .min(0)
+        .max(0.04)
+        .describe('Share of land pixels the unnamed river network covers, 0 to 0.04; the named rivers come on top. Default 0.02 (the base game has 0.023).'),
+})
+    .strict();
+export const worldLookSchema = z
+    .enum(['vanilla-temperate', 'fertile', 'arid', 'custom'])
+    .describe('Colour palette set for the calibrated land colour map: the base game, a greener fertile palette, a drier arid palette, or custom with colormap.palette. Setting it selects the calibrated colour map.');
+const colourClassNames = [
+    'plains',
+    'farmland',
+    'forest',
+    'hills',
+    'desert',
+    'mountain',
+    'marsh',
+    'jungle',
+    'snow',
+    'urban',
+    'lakes',
+    'ocean',
+];
+export const worldColormapSchema = z
+    .object({
+    profile: z
+        .enum(['calibrated', 'legacy'])
+        .optional()
+        .describe('calibrated writes a dark, varied colour map calibrated to the base game; legacy keeps the original flat tints. Defaults to calibrated when look is set, otherwise legacy.'),
+    palette: z
+        .object(Object.fromEntries(colourClassNames.map((name) => [name, rgbSchema.optional()])))
+        .strict()
+        .optional()
+        .describe('Class colours for look custom: the intended colour map value of each class.'),
+})
+    .strict();
+/** Feature-aware provinces, states and strategic regions (ADR 0058). */
+export const worldPartitionSchema = z
+    .enum(['legacy', 'feature-aware'])
+    .describe('legacy (default) keeps the warped Voronoi provinces and breadth-first clusters, so a seed gives the same world as before; feature-aware cuts provinces along rivers, ridges, steep slopes and shores, sizes them by terrain, fertility and coast, and clusters states and regions along natural lines. A world given a geography defaults to feature-aware.');
+const partitionAreaPixels = z.number().int().min(20).max(50_000);
+export const worldPartitionTuningSchema = z
+    .object({
+    landArea: z
+        .object({
+        fertile: partitionAreaPixels.optional(),
+        hills: partitionAreaPixels.optional(),
+        mountain: partitionAreaPixels.optional(),
+        waste: partitionAreaPixels.optional(),
+    })
+        .strict()
+        .optional()
+        .describe('Typical land province area in pixels by ground. Defaults follow landProvincePixels (0.35, 1, 2.2 and 3.4 times, scaled so the mean stays landProvincePixels). fertile must not exceed hills, nor hills mountain.'),
+    seaArea: z
+        .object({
+        coastal: z.number().int().min(20).max(200_000).optional(),
+        open: z.number().int().min(20).max(200_000).optional(),
+    })
+        .strict()
+        .optional()
+        .describe('Sea province area in pixels near a coast and on the open sea. Defaults follow seaProvincePixels (0.5 and 2.4 times, scaled so the mean stays seaProvincePixels).'),
+    provincesPerState: z
+        .tuple([z.number().int().min(1).max(64), z.number().int().min(1).max(64)])
+        .optional()
+        .describe('[smallest, largest] land provinces per state; the preferred size is the geometric mean.'),
+    regionSize: z
+        .tuple([z.number().int().min(1).max(400), z.number().int().min(1).max(400)])
+        .optional()
+        .describe('[smallest, largest] land provinces per strategic region.'),
+    barrierStrength: z
+        .number()
+        .min(0)
+        .max(60)
+        .optional()
+        .describe('How strongly borders are pulled onto natural lines, 0 to 60; default 20.'),
+    minProvincePixels: z
+        .number()
+        .int()
+        .min(20)
+        .max(2_000)
+        .optional()
+        .describe('No province is planned smaller than this; default 40. The engine floor is 8.'),
+    narrowStraitPx: z
+        .number()
+        .int()
+        .min(4)
+        .max(64)
+        .optional()
+        .describe('A sea channel at most this wide gets two sea provinces across it; default 24.'),
+})
+    .strict();
 const moveStateDistributionSchema = z
     .object({
     stateValues: z.enum(['retain-in-current-states', 'proportional-by-land-pixels']),
@@ -565,6 +791,12 @@ export const mapOperationSchema = z.discriminatedUnion('kind', [
             .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(),
+        geography: geographyModelSchema
+            .optional()
+            .describe('Geography model version 1, inline: seas, lands, ranges, passes, volcanoes, plateaus, rivers, lakes, biomes, straits, sites and climate in normalized 0..1 world coordinates. Use geographyPath for models over a few hundred vertices. With preview:true it returns a model overlay and map-geography-report.json. Without preview the world is built from it: relief (ranges with passes, volcanoes, plateaus), rivers and lakes are synthesised; biomes, climate and fertility are not yet, and a model that declares them is blocked with MAP_GEOGRAPHY_SYNTHESIS_UNAVAILABLE.'),
+        geographyPath: geographyPathSchema
+            .optional()
+            .describe('Workspace-relative .json file holding a geography model (at most 4 MiB). Alternative to the inline geography field; give one of them.'),
         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),
@@ -581,31 +813,64 @@ export const mapOperationSchema = z.discriminatedUnion('kind', [
         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: 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)
-            .optional(),
+            .union([
+            z
+                .array(z
+                .object({
+                tag: countryTagSchema,
+                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),
+            workspaceCountriesSchema,
+        ])
+            .optional()
+            .describe('Countries the world generates and writes (an array), or { source: "workspace", realms } for countries the workspace already declares: the world then places them from their capital, seeds, claims and exclusions and writes no country, flag, unit, country history, country name or bookmark file.'),
         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).optional(),
+        rivers: z
+            .union([z.number().int().min(0).max(500), worldRiverDensitySchema])
+            .optional()
+            .describe('Without a geography: the number of generated rivers. With a geography: an integer limits the number of unnamed river systems, an object { density } sets the share of land the network covers; the rivers the model names are always routed.'),
+        relief: worldReliefSchema
+            .optional()
+            .describe('Relief of a world built from a geography model: height scale and detail. Needs geography.'),
+        edge: worldEdgeSchema.optional(),
+        ambientFrame: z
+            .boolean()
+            .optional()
+            .describe("Write the base map's north and south frame borders and logo frame into ambient_object.txt, placed for the world size. Off by default."),
+        look: worldLookSchema.optional(),
+        colormap: worldColormapSchema.optional(),
+        partition: worldPartitionSchema.optional(),
+        partitionTuning: worldPartitionTuningSchema
+            .optional()
+            .describe('Size bands and strengths of the feature-aware partition; refused with partition legacy.'),
         replaceBaseGame: z
             .boolean()
             .default(true)
             .describe('Add replace_path for the base game states, countries, units, strategic regions, supply areas and bookmarks to descriptor.mod.'),
     })
-        .strict(),
+        .strict()
+        .refine((operation) => operation.geography === undefined || operation.geographyPath === undefined, {
+        path: ['geographyPath'],
+        message: 'Give the geography inline (geography) or by file (geographyPath), not both',
+    })
+        .refine((operation) => (operation.reference?.fit !== 'frame' &&
+        operation.reference?.sheets === undefined &&
+        operation.reference?.sheetsPath === undefined) ||
+        (operation.width !== undefined && operation.height !== undefined), {
+        path: ['reference', 'fit'],
+        message: 'reference.fit "frame" and registered sheets need explicit width and height',
+    }),
     z
         .object({
         ...operationBase,

package/dist/hoi4_agent_tools/schemas/reference-sheets.js

@@ -0,0 +1,92 @@
+import { z } from 'zod/v4';
+import { workspaceRelativePathSchema } from './common.js';
+/** Bounds of a sheet document (ADR 0067). */
+export const REFERENCE_SHEETS_SOURCE_MAX_BYTES = 1_048_576;
+export const REFERENCE_SHEETS_MAX = 64;
+export const REFERENCE_SHEET_CLIP_MAX_VERTICES = 512;
+const unit = z.number().min(0).max(1);
+const finite = z.number().refine(Number.isFinite, 'Must be a finite number');
+const pointSchema = z.tuple([unit, unit]);
+/**
+ * One drawn sheet: the part of the picture it occupies (`box`, optionally cut by `clip`), and the
+ * map from picture to world, `world = target + scale * (picture - anchor)` per axis, or a general
+ * affine `[a, b, c, d, e, f]` with `x' = a x + b y + c`, `y' = d x + e y + f`. Picture coordinates
+ * are normalised to the picture, world coordinates to the output frame; a negative scale mirrors.
+ */
+export const referenceSheetSchema = z
+    .object({
+    id: z
+        .string()
+        .regex(/^[A-Za-z][A-Za-z0-9_-]{0,63}$/u)
+        .describe('Unique sheet id, named in diagnostics and artifacts.'),
+    box: z
+        .tuple([unit, unit, unit, unit])
+        .refine(([left, top, right, bottom]) => right > left && bottom > top, {
+        message: 'box is [left, top, right, bottom] with right > left and bottom > top',
+    })
+        .describe('[left, top, right, bottom] of the sheet in normalised picture coordinates.'),
+    clip: z
+        .array(pointSchema)
+        .min(3)
+        .max(REFERENCE_SHEET_CLIP_MAX_VERTICES)
+        .optional()
+        .describe('Polygon in picture coordinates that cuts the sheet out of its box, so a neighbouring sheet inside the box is not pulled in.'),
+    anchor: z.tuple([unit, unit]).optional().describe('Picture point that maps to target.'),
+    target: z.tuple([finite, finite]).optional().describe('World point of the anchor.'),
+    scale: z
+        .tuple([finite, finite])
+        .refine(([x, y]) => x !== 0 && y !== 0, 'scale must not be zero')
+        .optional()
+        .describe('World units per picture unit along x and y; a negative value mirrors.'),
+    affine: z
+        .tuple([finite, finite, finite, finite, finite, finite])
+        .optional()
+        .describe('General map [a, b, c, d, e, f] from picture to world, instead of anchor, target and scale.'),
+    order: z
+        .number()
+        .int()
+        .min(0)
+        .max(1_000)
+        .default(0)
+        .describe('Where targets overlap the higher order wins; equal orders that overlap are an error.'),
+})
+    .strict()
+    .refine((sheet) => (sheet.affine === undefined) ===
+    (sheet.anchor !== undefined && sheet.target !== undefined && sheet.scale !== undefined) &&
+    (sheet.affine !== undefined || sheet.anchor !== undefined), { message: 'Give either anchor, target and scale, or affine' });
+export const referenceSheetsDocumentSchema = z
+    .object({
+    version: z.literal(1),
+    source: z
+        .object({
+        width: z.number().int().positive(),
+        height: z.number().int().positive(),
+        sha256: z
+            .string()
+            .regex(/^[a-f0-9]{64}$/u)
+            .optional(),
+    })
+        .strict()
+        .optional()
+        .describe('The picture these registrations were made for; a picture of another size or hash is refused.'),
+    fill: z
+        .enum(['sea', 'error'])
+        .default('sea')
+        .describe('What world pixels outside every sheet become: open sea, or an error.'),
+    sheets: z.array(referenceSheetSchema).min(1).max(REFERENCE_SHEETS_MAX),
+})
+    .strict()
+    .superRefine((document, context) => {
+    const seen = new Set();
+    for (const [index, sheet] of document.sheets.entries()) {
+        if (seen.has(sheet.id))
+            context.addIssue({
+                code: 'custom',
+                path: ['sheets', index, 'id'],
+                message: `Duplicate sheet id ${sheet.id}`,
+            });
+        seen.add(sheet.id);
+    }
+})
+    .describe('Registration of a drawn picture made of sheets onto the world frame (ADR 0067). Coordinates are normalised: picture coordinates to the picture, world coordinates to width x height.');
+export const referenceSheetsPathSchema = workspaceRelativePathSchema.refine((value) => !value.includes(':') && /\.json$/iu.test(value), 'Sheets must be a workspace-relative .json 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 = '4.3.0';
+export const PACKAGE_VERSION = '4.5.0';
 export const MCP_PROTOCOL_VERSION = LATEST_PROTOCOL_VERSION;
 export const CONFIG_VERSION = 1;
 export const TRANSACTION_VERSION = 2;

package/docs/configuration.md

@@ -66,16 +66,18 @@ Every tool takes a `workspaceId` argument, which defaults to `"current"`.
 For `"current"`, the server asks the MCP client for its workspace roots when the client supports them:
 
 - It selects the one mod workspace that contains a client root or lies inside one.
-- No match fails with `WORKSPACE_CONTEXT_NOT_FOUND`, and more than one match fails with `WORKSPACE_CONTEXT_AMBIGUOUS`.
+- More than one match fails with `WORKSPACE_CONTEXT_AMBIGUOUS`.
+- With no match, for example a session started in another repository, it selects the `defaultWorkspace` when it is set, or the only mod workspace when there is one.
+- Otherwise the call fails with `WORKSPACE_CONTEXT_NOT_FOUND`, and the error lists up to 32 workspace IDs and names (`workspaceIds`, `workspaceNames`, `workspaceCount`) with the three fixes.
 
 When the client does not supply roots, the server uses its own working directory:
 
 - It selects the one mod workspace that contains the working directory.
-- If the working directory is in no mod and exactly one mod workspace exists, it selects that mod.
-- If the working directory is in no mod and several mod workspaces exist, the call fails with `WORKSPACE_CONTEXT_REQUIRED`, and the error lists the available workspace IDs.
+- If the working directory is in no mod, it selects the `defaultWorkspace` when it is set, or the only mod workspace when there is one.
+- Otherwise the call fails with `WORKSPACE_CONTEXT_REQUIRED`, and the error lists the available workspace IDs and names.
 - With no mod workspace at all, the call fails with `WORKSPACE_CONTEXT_NOT_FOUND`.
 
-When a tool reads a named source file with `"current"` and the selected mod lacks that file, the server uses the one other mod that has it, and fails with `WORKSPACE_SOURCE_AMBIGUOUS` if several do.
+When a tool reads a named source file with `"current"` (the `relativePath` of the focus tools, the `path` of `hoi4.script_validate`) and the selected mod lacks that file, or no mod could be selected, the server uses the one mod that has it, and fails with `WORKSPACE_SOURCE_AMBIGUOUS` if several do.
 
 To choose a mod explicitly, pass its workspace ID.
 A configured workspace keeps the `id` you gave it.
@@ -87,16 +89,17 @@ Over HTTP, a principal sees only the workspaces granted to it, and any other ID
 
 ## Paths
 
-| Key                    | Type             | Range       | Default | Purpose                                                                                                                                                                                                                                                                                                                           |
-| ---------------------- | ---------------- | ----------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `version`              | number           | `1`         | none    | Configuration format version; required.                                                                                                                                                                                                                                                                                           |
-| `serverStateRoot`      | absolute path    |             | unset   | Private folder for indexes, jobs and server records. Required whenever `modRoots` or a `mod` workspace is configured.                                                                                                                                                                                                             |
-| `modRoots`             | array of paths   | up to 16    | `[]`    | Parent folders whose direct subfolders each become a writable mod workspace. Hidden and linked subfolders are skipped, and a subfolder already registered under `workspaces` keeps that registration.                                                                                                                             |
-| `gameRoot`             | path             |             | unset   | The installed game, used by every `mod` workspace that sets no `gameRoot` of its own.                                                                                                                                                                                                                                             |
-| `gameUserRoot`         | path             |             | unset   | The game's user-data folder holding `logs/error.log`, read by `hoi4.error_log`. When unset, the server tries the folder containing a mod's parent `mod/` folder, then `Documents/Paradox Interactive/Hearts of Iron IV` (also under `%OneDrive%` on Windows), or `~/.local/share/Paradox Interactive/Hearts of Iron IV` on Linux. |
-| `workspaceStorageRoot` | path             |             | unset   | Base folder for generated files: each workspace stores `artifacts/` and `cache/` in `<workspaceStorageRoot>/<workspace ID>/`. When unset, mods use `.hoi4-agent/` inside the mod.                                                                                                                                                 |
-| `storageRoots`         | array of paths   | up to 16    | `[]`    | Additional folders in which an explicit `artifactRoot` or `cacheRoot` may be placed.                                                                                                                                                                                                                                              |
-| `workspaces`           | array of objects | up to 1,000 | `[]`    | Explicit workspace registrations, described in the next section.                                                                                                                                                                                                                                                                  |
+| Key                    | Type             | Range        | Default | Purpose                                                                                                                                                                                                                                                                                                                           |
+| ---------------------- | ---------------- | ------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `version`              | number           | `1`          | none    | Configuration format version; required.                                                                                                                                                                                                                                                                                           |
+| `serverStateRoot`      | absolute path    |              | unset   | Private folder for indexes, jobs and server records. Required whenever `modRoots` or a `mod` workspace is configured.                                                                                                                                                                                                             |
+| `modRoots`             | array of paths   | up to 16     | `[]`    | Parent folders whose direct subfolders each become a writable mod workspace. Hidden and linked subfolders are skipped, and a subfolder already registered under `workspaces` keeps that registration.                                                                                                                             |
+| `gameRoot`             | path             |              | unset   | The installed game, used by every `mod` workspace that sets no `gameRoot` of its own.                                                                                                                                                                                                                                             |
+| `gameUserRoot`         | path             |              | unset   | The game's user-data folder holding `logs/error.log`, read by `hoi4.error_log`. When unset, the server tries the folder containing a mod's parent `mod/` folder, then `Documents/Paradox Interactive/Hearts of Iron IV` (also under `%OneDrive%` on Windows), or `~/.local/share/Paradox Interactive/Hearts of Iron IV` on Linux. |
+| `workspaceStorageRoot` | path             |              | unset   | Base folder for generated files: each workspace stores `artifacts/` and `cache/` in `<workspaceStorageRoot>/<workspace ID>/`. When unset, mods use `.hoi4-agent/` inside the mod.                                                                                                                                                 |
+| `storageRoots`         | array of paths   | up to 16     | `[]`    | Additional folders in which an explicit `artifactRoot` or `cacheRoot` may be placed.                                                                                                                                                                                                                                              |
+| `workspaces`           | array of objects | up to 1,000  | `[]`    | Explicit workspace registrations, described in the next section.                                                                                                                                                                                                                                                                  |
+| `defaultWorkspace`     | string           | workspace ID | unset   | The mod workspace, by ID or short form, used for `"current"` when neither the client roots nor the working directory identify one. It must name a registered mod workspace, and over HTTP it applies only to principals granted that workspace.                                                                                   |
 
 ## Workspaces
 

package/docs/focus.md

@@ -168,6 +168,12 @@ Branch names, lane assignments, working labels, and other planning-only data may
 
 If malformed or unsupported script makes a requested change ambiguous, the rewrite stops and explains the blocker instead of guessing.
 
+### Stale source and source encoding
+
+A rewrite starts from a plan returned by `hoi4.focus_inspect`. If the source file changed in meaning after that inspection, `hoi4.focus_rewrite` refuses with `FOCUS_SOURCE_CHANGED_SINCE_PLAN` and writes nothing, because applying the plan would overwrite the other change with the plan's older values. Call `hoi4.focus_inspect` again, reapply the intended edit to the new plan, and retry. There is no override. A change that only touches comments or formatting does not trigger the refusal, and neither does a source that already equals the plan.
+
+Source files are read as UTF-8 (with or without a byte order mark) and, when they are not valid UTF-8, as Windows-1252. Windows-1252 leaves the bytes 0x81, 0x8D, 0x8F, 0x90 and 0x9D undefined, so a file containing any of them cannot be edited without changing those bytes. Inspection still works and reports the warning `SOURCE_ENCODING_NOT_ROUND_TRIPPABLE`; every rewrite of that file is refused with the same code. Convert the file to UTF-8, or replace those bytes, and retry.
+
 ## What inspection checks
 
 Inspection and rendering can report missing references, invalid prerequisite structure, duplicate or overlapping positions, insufficient spacing, long or crossing connectors, branch asymmetry, route conflicts, missing localisation or sprites, weak terminal branches, repeated rewards, and missing AI metadata. National-tree inspection also returns the exact `continuous_focus_position` coordinates and linked palette IDs in its compact result, so an agent can identify and move the continuous-focus area without opening the full artifact. Renders are offline review artifacts, not game screenshots.