hoi4-agent-tools 4.4.0 → 4.5.0

package/dist/hoi4_agent_tools/schemas/map.js

@@ -24,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(),
@@ -760,19 +813,24 @@ 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()

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.4.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/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.

package/docs/map.md

@@ -429,6 +429,40 @@ Width and height are multiples of 256 with at most 13,238,272 pixels. Land comes
 
 The operation writes `provinces.bmp`, `definition.csv`, `default.map`, `continent.txt`, `heightmap.bmp`, `terrain.bmp`, `rivers.bmp` (rivers run downhill to the coast), `trees.bmp`, `cities.bmp`, `world_normal.bmp`, the land and water colour maps, `adjacencies.csv`, strategic regions (`landProvincesPerRegion`, `seaProvincesPerRegion`) with weather by latitude, states (`provincesPerState`) with population, category, buildings, resources, victory points and ports, country tags, country files, history and three-band flags, a bookmark, localisation, and every position, supply node and railway. Countries grow from spread-out capitals in proportion to `share`; each state lies within one country and one strategic region.
 
+Each write records its generated files in `.hoi4-agent-world.json`. A later `create_world` deletes the recorded files it no longer writes (retires them) in the same transaction and refuses with `MANAGED_OUTPUT_EDITED` when a recorded file was edited since. `MAP_WORLD_OUTPUTS_RECONCILED` and `data.outputs` give the counts of written, retired and released files with up to 200 paths each; `map-world-outputs.json` lists them all.
+
+### Countries the mod already owns
+
+A mod that writes its own country tags, country files, histories, orders of battle, flags and names gives `countries` as an object instead of an array (ADR 0069):
+
+```json
+"countries": {
+  "source": "workspace",
+  "realms": [
+    { "tag": "AUR", "capital": { "x": 812, "y": 340 }, "weight": 2 },
+    {
+      "tag": "BOR",
+      "capital": { "x": 1210, "y": 300 },
+      "seeds": [{ "x": 1300, "y": 420 }],
+      "claim": [[{ "x": 1180, "y": 250 }, { "x": 1290, "y": 250 }, { "x": 1290, "y": 380 }]],
+      "exclude": [[{ "x": 1000, "y": 500 }, { "x": 1100, "y": 500 }, { "x": 1100, "y": 600 }]]
+    }
+  ],
+  "unowned": [[{ "x": 600, "y": 700 }, { "x": 680, "y": 700 }, { "x": 680, "y": 760 }]],
+  "islands": "nearest"
+}
+```
+
+Points and polygon vertices are world pixels with the origin at the top left. A capital or seed names the land province under it; a land province with more than half its pixels inside a claim belongs to that country, inside an exclusion never does, and inside `unowned` belongs to nobody. Countries grow from their capitals, seeds and claims by `weight` (default 1). Land that growth does not reach goes, on a landmass a country already holds, to the nearest country that may own it; a landmass no country starts on follows `islands`: `nearest` (each province to the nearest capital), `one-owner` (the whole landmass to the country nearest its centre) or `unowned`. At most 512 countries.
+
+Every tag must be declared by an active `common/country_tags` file other than the world's own (`MAP_WORLD_REALM_TAG_UNKNOWN`) and not only as a dynamic tag (`MAP_WORLD_REALM_TAG_DYNAMIC`). A point outside the world (`MAP_WORLD_REALM_POINT_OUTSIDE`) or in water (`MAP_WORLD_REALM_POINT_WATER`), a point in unowned land, in the country's own exclusion or on another country's point (`MAP_WORLD_REALM_POINT_CONFLICT`), and claims that overlap each other or unowned land (`MAP_WORLD_REALM_CLAIM_OVERLAP`) are refused with the tag and position. A reference picture's political colours are not used with this form.
+
+The world then writes no country tag file, country file, `colors.txt`, country history, order of battle, flag, country name or bookmark. Unowned land forms states with no `owner`, `controller` or `add_core_of` (`MAP_WORLD_STATE_UNOWNED`, and `MAP_STATE_OWNER_MISSING` for each); whether the game build accepts unowned land is the mod's to verify. `MAP_WORLD_REALMS_PLACED`, `data.realms` and `map-world-realms.json` give each country's capital state and province, states, provinces and land share against its target. The country histories stay the mod's: a `capital` in a state the country does not own is the existing warning `MAP_COUNTRY_CAPITAL_NOT_OWNED`.
+
+A recorded country file of an earlier generated world that the mod has since edited is released: left in place, dropped from `.hoi4-agent-world.json` and listed as released (`MAP_WORLD_OUTPUT_RELEASED`). Unedited ones are retired. Other edited recorded files still refuse. To keep a file the mod changed, leave its recorded hash as the world wrote it.
+
+Every `create_world` reports the country tags declared after the write (`MAP_WORLD_TAG_COUNT`: static, written by the world, dynamic, total) and warns above 439 (`MAP_WORLD_TAG_COUNT_HIGH`), the count at which one measured game build overflowed its flag sheet; this is an observation, not a documented limit, and never blocks.
+
 With `replaceBaseGame` (default `true`) it adds `replace_path` lines for `history/states`, `history/countries`, `history/units`, `map/strategicregions`, `map/supplyareas` and `common/bookmarks` to `descriptor.mod`, and its info diagnostic reminds you that the launcher's `.mod` file beside the mod folder needs the same lines. Base-game events, focuses and decisions still name base-game states; `map_inspect` with `references: true` lists them for replacement or remapping. The same seed always gives the same world. Refine it with the other operations.
 
 ### Feature-aware provinces, states and strategic regions

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "hoi4-agent-tools",
-  "version": "4.4.0",
+  "version": "4.5.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "hoi4-agent-tools",
-      "version": "4.4.0",
+      "version": "4.5.0",
       "license": "Apache-2.0",
       "dependencies": {
         "@fontsource-variable/roboto": "5.3.0",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hoi4-agent-tools",
   "mcpName": "io.github.klimPaskov/hoi4-agent-tools",
-  "version": "4.4.0",
+  "version": "4.5.0",
   "description": "Build HOI4 mods: focus trees, events, decisions, worlds, GUI previews, docs and AI balance.",
   "type": "module",
   "license": "Apache-2.0",

package/schemas/configuration.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.4.0/schemas/configuration.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.5.0/schemas/configuration.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/continuous-focus-palette.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.4.0/schemas/continuous-focus-palette.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.5.0/schemas/continuous-focus-palette.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/custom-weighted-pool.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.4.0/schemas/custom-weighted-pool.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.5.0/schemas/custom-weighted-pool.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/decision-inspect-input.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.4.0/schemas/decision-inspect-input.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.5.0/schemas/decision-inspect-input.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/error-log-input.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.4.0/schemas/error-log-input.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.5.0/schemas/error-log-input.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/event-feature-manifest.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.4.0/schemas/event-feature-manifest.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.5.0/schemas/event-feature-manifest.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/focus-plan.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.4.0/schemas/focus-plan.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.5.0/schemas/focus-plan.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/focus-planning-sidecar.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.4.0/schemas/focus-planning-sidecar.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.5.0/schemas/focus-planning-sidecar.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/geography-model.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.4.0/schemas/geography-model.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.5.0/schemas/geography-model.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/gui-animation-source.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.4.0/schemas/gui-animation-source.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.5.0/schemas/gui-animation-source.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/gui-helper.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.4.0/schemas/gui-helper.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.5.0/schemas/gui-helper.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/gui-scenario.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.4.0/schemas/gui-scenario.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.5.0/schemas/gui-scenario.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/helper-expansion-request.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.4.0/schemas/helper-expansion-request.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.5.0/schemas/helper-expansion-request.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/helper-expansion-summary.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.4.0/schemas/helper-expansion-summary.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.5.0/schemas/helper-expansion-summary.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

package/schemas/impact-inspect-input.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.4.0/schemas/impact-inspect-input.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.5.0/schemas/impact-inspect-input.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {