hoi4-agent-tools 4.4.0 → 4.6.0

package/dist/hoi4_agent_tools/schemas/geography.js

@@ -79,6 +79,15 @@ export const geographySiteKindSchema = z.enum([
     'mine',
     'landmark',
 ]);
+/** The strategic resources of the game that a mine site can yield. */
+export const geographyResourceSchema = z.enum([
+    'steel',
+    'aluminium',
+    'tungsten',
+    'chromium',
+    'oil',
+    'rubber',
+]);
 export const geographyPlaceKindSchema = z.enum([
     'cape',
     'bay',
@@ -94,7 +103,7 @@ const seaSchema = z
     ...areaFields,
     depthClass: geographyDepthClassSchema.optional(),
     ice: unit.optional(),
-    kind: z.enum(['ocean', 'sea', 'gulf', 'fjord']).optional(),
+    kind: z.enum(['ocean', 'sea', 'gulf', 'bay', 'fjord']).optional(),
 })
     .strict();
 const landSchema = z
@@ -266,6 +275,8 @@ const siteSchema = z
     onWater: z.boolean().optional(),
     /** A lake the site belongs to, for a port on a lake shore. */
     lake: geographyFeatureIdSchema.optional(),
+    /** What a `mine` site yields in the world's economy (steel when it names none). */
+    resource: geographyResourceSchema.optional(),
 })
     .strict();
 const roadSchema = z

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(),
@@ -225,6 +278,32 @@ export const worldColormapSchema = z
 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.');
+/** Development model of a world built from a geography (ADR 0063). */
+export const worldDevelopmentSchema = z
+    .object({
+    model: z
+        .enum(['geography', 'legacy'])
+        .optional()
+        .describe('geography (default for a geography world) plans ports, population, state categories, infrastructure, factories, resources, victory points, names and railway costs from the model: fertility, rivers, the coast, passes, ranges and sites. legacy keeps the random economy.'),
+})
+    .strict();
+/** Automatic detection of narrow sea channels between landmasses (ADR 0062). */
+export const worldAutoStraitsSchema = z
+    .union([
+    z.boolean(),
+    z
+        .object({
+        maxGapPx: z
+            .number()
+            .int()
+            .min(4)
+            .max(96)
+            .optional()
+            .describe('Widest channel written as a crossing, in pixels; default 24 (about 170 km).'),
+    })
+        .strict(),
+])
+    .describe('Also write a sea crossing for every channel narrower than maxGapPx that one sea province fills between two landmasses and that the model does not declare as a strait. Needs a geography.');
 const partitionAreaPixels = z.number().int().min(20).max(50_000);
 export const worldPartitionTuningSchema = z
     .object({
@@ -581,6 +660,162 @@ const createProvinceOperation = z
 })
     .strict();
 const occurrenceSchema = z.number().int().min(0).optional();
+const stateChangesSchema = z
+    .object({
+    capital: provinceId
+        .nullable()
+        .optional()
+        .describe('Assertion for the capital derived from the exact victoryPoints payload; never writes a state capital field'),
+    manpower: z.number().min(0).optional(),
+    category: z.string().min(1).optional(),
+    resources: nonnegativeMap.optional(),
+    stateBuildings: nonnegativeMap.optional(),
+    owner: z.string().min(1).nullable().optional(),
+    controller: z.string().min(1).nullable().optional(),
+    cores: z.array(z.string().min(1)).max(10_000).optional(),
+    claims: z.array(z.string().min(1)).max(10_000).optional(),
+    victoryPoints: z
+        .array(z.object({ provinceId, value: z.number().min(0) }).strict())
+        .max(100_000)
+        .optional(),
+    provinceBuildings: z.record(z.string().regex(/^\d+$/u), nonnegativeMap).optional(),
+})
+    .strict();
+const tagSchema = z
+    .string()
+    .regex(/^[A-Z0-9]{3}$/u, 'A country tag is three capital letters or digits');
+const territoryRefSchema = z.union([
+    z.object({ state: stateId }).strict(),
+    z.object({ province: provinceId }).strict(),
+    z.object({ x: z.number().int().min(0), y: z.number().int().min(0) }).strict(),
+]);
+const territorySelectionSchema = z
+    .object({
+    stateIds: z.array(stateId).max(100_000).optional(),
+    provinceIds: z.array(provinceId).max(100_000).optional(),
+    regionIds: z.array(z.number().int().positive()).max(10_000).optional(),
+})
+    .strict();
+const borderQualityModeSchema = z
+    .enum(['off', 'report', 'enforce'])
+    .describe('off skips the measurement; report adds border naturalness to the result; enforce blocks the write when the borders miss the targets.');
+const borderTargetsSchema = z
+    .object({
+    minEnrichment: z.number().min(0).max(20).optional(),
+    maxStraightness: z.number().min(0).max(1).optional(),
+    minNaturalShare: z.number().min(0).max(1).optional(),
+})
+    .strict()
+    .describe('Override the targets (enrichment 1.6; straightness 0.12 for country borders and 0.25 for state borders).');
+const territoryCountrySchema = z
+    .object({
+    tag: tagSchema,
+    weight: z
+        .number()
+        .positive()
+        .max(1_000_000)
+        .optional()
+        .describe('Relative target size; default 1.'),
+    seeds: z
+        .array(territoryRefSchema)
+        .min(1)
+        .max(64)
+        .describe('{ state }, { province } or a pixel { x, y }. The first is the capital.'),
+    forced: territorySelectionSchema.optional(),
+    blocked: territorySelectionSchema.optional(),
+    regions: z
+        .array(z.number().int().positive())
+        .max(1_000)
+        .optional()
+        .describe('Strategic regions this country prefers to grow in.'),
+    overlord: tagSchema.optional().describe('Grow this country inside its overlord.'),
+    mergeInto: tagSchema
+        .optional()
+        .describe('Relabel the finished territory to another listed country (this tag stays a core).'),
+    cores: territorySelectionSchema.optional(),
+    claims: territorySelectionSchema.optional(),
+})
+    .strict();
+const territoryOperation = z
+    .object({
+    ...operationBase,
+    kind: z.literal('assign_territory'),
+    unit: z
+        .enum(['state', 'province'])
+        .default('state')
+        .describe('state assigns whole states. province assigns provinces and regroups the states a border cuts (conserving population, resources and buildings).'),
+    countries: z.array(territoryCountrySchema).min(1).max(512),
+    scope: z
+        .object({
+        stateIds: z.array(stateId).max(100_000).optional(),
+        regionIds: z.array(z.number().int().positive()).max(10_000).optional(),
+        owners: z.array(z.string().min(1).max(32)).max(1_000).optional(),
+    })
+        .strict()
+        .optional()
+        .describe('Only these states take part; the rest keep their owners.'),
+    unowned: territorySelectionSchema.optional(),
+    barriers: z
+        .enum(['natural', 'none'])
+        .default('natural')
+        .describe('none ignores rivers, ranges and shores (nearest seed).'),
+    rules: z
+        .object({
+        connectedMainland: z.boolean().default(true),
+        islandPolicy: z.enum(['one-owner', 'nearest', 'unowned']).default('one-owner'),
+    })
+        .strict()
+        .optional(),
+    smoothing: z
+        .object({
+        passes: z.number().int().min(0).max(20).default(4),
+        maxShareChange: z.number().min(0).max(1).default(0.15),
+    })
+        .strict()
+        .optional(),
+    shareTolerance: z.number().min(0.01).max(1).default(0.15),
+    seed: z.number().int().min(0).max(2_147_483_647).default(0),
+    ownership: z
+        .object({
+        controller: z.enum(['owner', 'keep']).default('owner'),
+        cores: z.enum(['keep', 'owner', 'add-owner']).default('keep'),
+        claims: z.enum(['keep', 'clear']).default('keep'),
+        unowned: z.enum(['clear', 'keep']).default('clear'),
+    })
+        .strict()
+        .optional(),
+    stateSize: z
+        .object({
+        min: z.number().int().min(1).max(1_000),
+        max: z.number().int().min(1).max(10_000).optional(),
+    })
+        .strict()
+        .optional()
+        .describe('Province unit: fragments below min provinces join a neighbour of the same owner.'),
+    remapReferences: z.enum(['refuse', 'override']).optional(),
+    borderQuality: borderQualityModeSchema.default('report'),
+    borderTargets: borderTargetsSchema.optional(),
+})
+    .strict();
+const repartitionOperation = z
+    .object({
+    ...operationBase,
+    kind: z.literal('repartition_states'),
+    countries: z.array(tagSchema).min(1).max(512).optional(),
+    stateIds: z.array(stateId).max(100_000).optional(),
+    provincesPerState: z
+        .object({
+        min: z.number().int().min(1).max(1_000).optional(),
+        target: z.number().int().min(1).max(1_000).optional(),
+        max: z.number().int().min(1).max(10_000).optional(),
+    })
+        .strict()
+        .optional(),
+    remapReferences: z.enum(['refuse', 'override']).optional(),
+    borderQuality: borderQualityModeSchema.default('report'),
+    borderTargets: borderTargetsSchema.optional(),
+})
+    .strict();
 export const mapOperationSchema = z.discriminatedUnion('kind', [
     z
         .object({
@@ -637,29 +872,22 @@ export const mapOperationSchema = z.discriminatedUnion('kind', [
         ...operationBase,
         kind: z.literal('update_state'),
         stateId,
-        changes: z
-            .object({
-            capital: provinceId
-                .nullable()
-                .optional()
-                .describe('Assertion for the capital derived from the exact victoryPoints payload; never writes a state capital field'),
-            manpower: z.number().min(0).optional(),
-            category: z.string().min(1).optional(),
-            resources: nonnegativeMap.optional(),
-            stateBuildings: nonnegativeMap.optional(),
-            owner: z.string().min(1).nullable().optional(),
-            controller: z.string().min(1).nullable().optional(),
-            cores: z.array(z.string().min(1)).max(10_000).optional(),
-            claims: z.array(z.string().min(1)).max(10_000).optional(),
-            victoryPoints: z
-                .array(z.object({ provinceId, value: z.number().min(0) }).strict())
-                .max(100_000)
-                .optional(),
-            provinceBuildings: z.record(z.string().regex(/^\d+$/u), nonnegativeMap).optional(),
-        })
-            .strict(),
+        changes: stateChangesSchema,
+    })
+        .strict(),
+    z
+        .object({
+        ...operationBase,
+        kind: z.literal('update_states'),
+        updates: z
+            .array(z.object({ stateId, changes: stateChangesSchema }).strict())
+            .min(1)
+            .max(5_000)
+            .describe('One entry per state, each with the changes update_state takes. The whole list is one validated rewrite; a state may appear once.'),
     })
         .strict(),
+    territoryOperation,
+    repartitionOperation,
     splitStateOperation('split_state'),
     createStateOperation,
     z
@@ -741,6 +969,10 @@ export const mapOperationSchema = z.discriminatedUnion('kind', [
         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.'),
+        synthesisCheck: z
+            .boolean()
+            .optional()
+            .describe('With preview:true and a geography: run only the relief and river synthesis and report every river that cannot reach its mouth, with the divide that stops it, without writing or planning the map. Refused without preview or without a geography.'),
         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.'),
@@ -760,19 +992,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()
@@ -793,9 +1030,15 @@ export const mapOperationSchema = z.discriminatedUnion('kind', [
         look: worldLookSchema.optional(),
         colormap: worldColormapSchema.optional(),
         partition: worldPartitionSchema.optional(),
+        development: worldDevelopmentSchema.optional(),
+        autoStraits: worldAutoStraitsSchema.optional(),
         partitionTuning: worldPartitionTuningSchema
             .optional()
             .describe('Size bands and strengths of the feature-aware partition; refused with partition legacy.'),
+        borderQuality: borderQualityModeSchema
+            .optional()
+            .describe('Measure how well the new world’s province, state, region and country borders follow rivers, slopes and shores. enforce blocks the write below the targets and needs the feature-aware partition; omitted measures nothing.'),
+        borderTargets: borderTargetsSchema.optional(),
         replaceBaseGame: z
             .boolean()
             .default(true)

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.6.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

@@ -113,7 +113,7 @@ A model is one object with `"version": 1` and any of these arrays. Unknown keys
 
 | Array       | Feature and main fields                                                                                                                                                                                                           |
 | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `seas`      | `polygons` (outer rings), optional `holes`, `depthClass` (`shelf`, `open`, `abyss`), `ice` 0 to 1, `kind` (`ocean`, `sea`, `gulf`, `fjord`)                                                                                       |
+| `seas`      | `polygons` (outer rings), optional `holes`, `depthClass` (`shelf`, `open`, `abyss`), `ice` 0 to 1, `kind` (`ocean`, `sea`, `gulf`, `bay`, `fjord`)                                                                                |
 | `lands`     | `polygons`, `holes`, `kind` (`continent`, `island`, `archipelago`, `peninsula`), `region`, default `biome` and `fertility`, `elevationBase`, `coastDetail`                                                                        |
 | `regions`   | `polygons` (optional), `terrain` target shares, `density` (`provincesPerState` as `[smallest, usual, largest]`, `provinceAreaPx`)                                                                                                 |
 | `ranges`    | `path` (points, each optionally with `halfWidth` and `peak`), `closed`, `halfWidth`, `peak`, `profile` (`ridge`, `massif`, `escarpment`, `wall`), `asymmetry`, `snowline`, `spurs`, `barrier` (`none`, `impassable`, `fort-line`) |
@@ -161,7 +161,7 @@ The synthesis checks its own output and reports: `MAP_RELIEF_SYNTHESIZED` (info:
 
 Measured on the project's synthetic large fantasy model at 5,120 x 2,560 (13.1 million pixels): land median 110, 99th percentile 222, maximum 244, mean height step 1.02 per half-resolution pixel (base game: 107, 213, 239 and 0.97), 6.0 million land pixels with 129,987 river pixels (2.16%, 88 connected rivers, no 2 x 2 block, one source each, 1.6% of river pixels on straight stretches), and about six seconds and 450 MB for the synthesis.
 
-Not synthesised yet: biomes, climate, fertility, tree and colour-map classes from the model, sea ice, strait and pass adjacencies, and the render layers for relief and rivers. With a reference picture the picture still gives the coast and the terrain classes; its elevation and river hints are replaced. A reference picture's rivers are not routed.
+Not synthesised yet: biomes, climate, fertility, tree and colour-map classes from the model, sea ice, and the render layers for relief and rivers. Straits, passes, walls, ports, development and names are described in [Crossings, ports, development and names from a model](#crossings-ports-development-and-names-from-a-model). With a reference picture the picture still gives the coast and the terrain classes; its elevation and river hints are replaced. A reference picture's rivers are not routed.
 
 ## Inspect and navigate the complete map
 
@@ -265,7 +265,8 @@ Every operation has a unique `id` (1 to 256 characters), an optional `summary`,
 The supported kinds are:
 
 - whole maps: `create_world`;
-- states: `create_state`, `split_state`, `merge_states`, `move_state_provinces`, `update_state`;
+- states: `create_state`, `split_state`, `merge_states`, `move_state_provinces`, `update_state`, `update_states`;
+- countries and whole maps: `assign_territory`, `repartition_states`;
 - provinces: `create_province`, `split_province`, `merge_provinces`, `remove_province`, `update_province_definition`;
 - strategic regions: `move_region_provinces`;
 - identifiers and script references: `renumber_map_entity`, `remap_map_references`;
@@ -358,6 +359,69 @@ Pass a full `distribution` with `stateValues: "retain-in-current-states"` to lea
 
 Nothing is lost or duplicated: for any split, merge or move, the sums of manpower, each resource and each slot building over all states are the same before and after.
 
+## Assign territory to countries
+
+`assign_territory` gives the land of a whole map to up to 512 countries in one call, so that their borders follow rivers, ranges and shores. `repartition_states` regroups the provinces of existing states along the same natural lines, and `update_states` edits up to 5,000 states in one validated rewrite. [ADR 0060](adr/0060-territory-assignment-service.md) records the design.
+
+```json
+{
+  "operations": [
+    {
+      "id": "politics",
+      "kind": "assign_territory",
+      "unit": "province",
+      "seed": 7,
+      "countries": [
+        { "tag": "AAA", "weight": 3, "seeds": [{ "state": 41 }, { "x": 1810, "y": 902 }] },
+        {
+          "tag": "BBB",
+          "weight": 2,
+          "seeds": [{ "province": 3318 }],
+          "blocked": { "regionIds": [12] }
+        },
+        {
+          "tag": "CCC",
+          "weight": 1,
+          "seeds": [{ "state": 108 }],
+          "overlord": "AAA",
+          "regions": [4]
+        }
+      ],
+      "stateSize": { "min": 3, "max": 12 },
+      "ownership": { "cores": "owner", "claims": "clear" },
+      "borderQuality": "report"
+    }
+  ]
+}
+```
+
+| Field of a country      | Meaning                                                                                                                                                |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `tag`, `weight`         | Three capital letters or digits, and the relative target size (default 1).                                                                             |
+| `seeds`                 | `{ state }`, `{ province }` or a pixel `{ x, y }` of the province map; the first is the capital. A seed in the sea is refused.                         |
+| `forced`, `blocked`     | `{ stateIds, provinceIds, regionIds }`: land the country always or never owns. `regionIds` are strategic regions.                                      |
+| `regions`               | Strategic regions the country prefers to grow in (a step into another country's preferred region costs more).                                          |
+| `overlord`, `mergeInto` | A subject is grown inside its overlord's territory. `mergeInto` relabels the finished territory to another listed country and keeps its tag as a core. |
+| `cores`, `claims`       | Extra states the country holds a core on or claims.                                                                                                    |
+
+Top-level fields: `unit` (`state`, the default, assigns whole states; `province` assigns provinces and regroups the states a border cuts), `scope` (`stateIds`, `regionIds`, `owners`: only these states take part), `unowned` (land nobody owns), `barriers` (`natural` or `none`, which grows on distance alone), `rules.connectedMainland` (default true) and `rules.islandPolicy` (`one-owner`, `nearest` or `unowned` for landmasses without a seed), `smoothing` (`passes` 0 to 20, `maxShareChange`), `shareTolerance` (default 0.15), `seed` (the same seed gives the same borders), `ownership` (`controller`: `owner` or `keep`; `cores`: `keep`, `owner` or `add-owner`; `claims`: `keep` or `clear`; `unowned`: `clear` or `keep`), `stateSize` (province unit: fragments below `min` provinces join a neighbour of the same owner and strategic region), `remapReferences` (`refuse` or `override`, as for `merge_states`), `borderQuality` and `borderTargets`.
+
+How it works: a multi-source shortest-path growth from the seeds over the province or state graph, where a step costs the distance between centres times `1 + 6 * barrier` (the barrier is the strength of the rivers, slopes, lake shores and terrain changes along the shared border, measured by the metric of [Border naturalness](#border-naturalness)); country multipliers are corrected until sizes are within the tolerance of their targets; a country cut apart on its capital's landmass is joined by a corridor; and a local search moves boundary atoms when that shortens the artificial border without disconnecting the donor or leaving the size tolerance. Targets follow the weights, corrected for what the land allows (a country alone on an island owns the island).
+
+The province unit writes the new borders exactly: each state is split by owner, small fragments are merged, and states are rewritten in one pass. Population, resources and slot buildings follow the land by pixel share in whole units (every total is conserved), levels keep their value, victory points and province buildings follow their provinces, cores and claims are the union of the states that contribute, and new states are named `STATE_<id>` in `hoi4_agent_map_l_english.yml` after the state they were cut from, with a number. A state may hold provinces of one strategic region only; dated history that would be lost or rewritten, and provinces without geometry, refuse the operation.
+
+`repartition_states` takes `countries` (owners), `stateIds`, `provincesPerState` (`min` 3, `target` 6 and `max` 10 by default) and `remapReferences`. States are clustered per owner and strategic region; a cluster equal to an existing state is left alone.
+
+`update_states` takes `updates: [{ stateId, changes }]` with the changes of `update_state`. The index is built once; a state may appear once, and an unknown state refuses the whole list.
+
+`borderQuality` is `report` by default: the result adds `MAP_BORDER_QUALITY_MEASURED` with the enrichment, natural share and straightness of the proposed country and state borders, and the artifact `map-territory-report.json` holds every number. `enforce` blocks the write when a layer misses the targets (enrichment 1.6; straightness 0.12 for countries and 0.25 for states; override with `borderTargets`) with `MAP_TERRITORY_BORDER_ARTIFICIAL`; `off` skips it. `data.territory` returns, per operation, the sizes against targets (worst eight countries), the border score, the same seeds grown on distance alone (`distanceOnly`), and the counts of states changed, created and removed. Previews work as for any rewrite and write nothing.
+
+Unowned land: states in `unowned`, and landmasses without a seed under `islandPolicy: "unowned"`, are not grown into. With `ownership.unowned: "clear"` (the default) their owner is removed, and their controller too when `controller` is `owner`; `"keep"` leaves them as they were. States outside `scope` are never edited. Provinces that belong to no state cannot be owned and are left out.
+
+Refusals name the cause and the state or province of the request: `MAP_TERRITORY_SEED_IN_WATER`, `_STATE_UNKNOWN`, `_PROVINCE_UNKNOWN`, `_REGION_UNKNOWN`, `_SCOPE_UNKNOWN`, `_POINT_OUTSIDE_MAP`, `_PROVINCE_WITHOUT_STATE`, `_SEED_MISSING` (a country with no seed), `_SEED_UNAVAILABLE` (a seed or forced land is unowned, outside the scope or outside its overlord), `_FORCED_CONFLICT` (two countries claim one state or province), `_FORCED_BLOCKED` (forced or a seed and blocked for the same country), `_FORCED_UNREACHABLE` (blocked or forced land cuts a seed off from its capital), `_TAG_INVALID`, `_TAG_DUPLICATE`, `_WEIGHT_INVALID`, `_TOO_MANY_COUNTRIES` (above 512), `_TOO_MANY_SEEDS` (above 64), `_OVERLORD_INVALID` (unknown, itself or a cycle), `_MERGE_INVALID`, `_OPTION_INVALID`, `_STATE_OVERLAP`, `_STATE_SIZE_INVALID`, `_STATE_SIZE_NEEDS_PROVINCE_UNIT`, `_NO_LAND`, `_MAP_MISSING`, `_NOTHING_TO_REPARTITION`, and `MAP_UPDATE_STATES_DUPLICATE` for a state listed twice in `update_states`. The schema refuses more than 512 countries, more than 64 seeds, an empty seed list, a tag that is not three capital letters or digits, a weight of zero or less, and more than 5,000 `update_states` entries before anything is planned. Warnings: `MAP_TERRITORY_SHARE_OFF` (a country is more than the tolerance from its target) and `MAP_TERRITORY_DISCONNECTED`; info: `MAP_TERRITORY_ASSIGNED`, `MAP_TERRITORY_REPARTITIONED` and `MAP_TERRITORY_NO_FEATURES` (no height, river or terrain bitmap, so borders fall back to distance), `MAP_TERRITORY_STATE_SIZE_UNMET` (a fragment below `stateSize.min` has no neighbour of the same owner and strategic region to join) and `MAP_TERRITORY_STATE_SKIPPED` (`repartition_states` leaves states that span several strategic regions or share provinces).
+
+Measured on project-owned synthetic fixtures (ADR 0060): country-border enrichment 3.1 to 3.6 against 1.2 to 2.5 for the same seeds grown on distance alone on a partitioned world with rivers and ridges; on a generated total-conversion map of 13.1 million pixels with about 300 countries and 1,500 states, 15 seconds by state and 26 seconds by province.
+
 ## Other map changes
 
 `hoi4.map_rewrite` also moves and merges states, moves provinces between strategic regions, merges or removes provinces, changes province definitions and types, adds or removes normal and special adjacency, and updates supply, railway, building, unit, weather, and entity-locator records. Send one ordered operation list when several connected changes belong together.
@@ -397,6 +461,28 @@ Keys that take exactly one value (`capital`, `state`, `to_state`, `start_state`,
 
 `merge_states`, `create_state` and `split_state` can do this themselves: add `"remapReferences": "refuse"` (or `"override"`, which copies the game files that need it into the mod) and the merged-away states are renamed to the survivor, or the source state's references are extended to the new part, in the same plan.
 
+### Crossings, ports, development and names from a model
+
+A world built from a geography also gets its gameplay facts from the model (ADR [0062](adr/0062-straits-passes-and-impassable-ranges.md) and [0063](adr/0063-geography-driven-ports-development-names-and-railways.md)). A world without a geography is unchanged.
+
+| Model feature                        | What the world gets                                                                                                                                                                                                                                                                        |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `strait`                             | A named `sea` row in `adjacencies.csv` (land to land through a sea province; sea to sea through land when the path crosses an isthmus) and a rule in `adjacency_rules.txt` whose access follows `rule`: `open`, `army-closed` or `navy-closed`. The closest shores give the crossing line. |
+| `range` with `barrier: "impassable"` | `impassable` rows for every pair of land provinces whose border crosses the range's path, except at its passes. The partition cuts along the wall, so provinces do not straddle it.                                                                                                        |
+| `pass`                               | A gap in the wall: the province pairs whose border passes through it carry no row. `fort` above 0 puts `bunker = level` on both provinces of the gate (the same for `fort-line` ranges, which write no rows).                                                                              |
+| `lake` with `gameplay: "inland-sea"` | Sea provinces, so ships and naval bases can use it; a canal row joins a sealed one to the nearest ocean unless a declared strait does. Other lakes stay `lake` provinces and cannot hold a port.                                                                                           |
+| `site`                               | Victory points and names for capital, city, port and fortress sites (importance 1 to 5 gives 3 to 20 points); a port site holds a port; a `mine` site gives its `resource` (steel by default); a `country` anchor chooses that country's capital.                                          |
+| fertility, rivers, coast, passes     | Population, state category, infrastructure, factories and the harbour score of each coastal province, with no random rolls.                                                                                                                                                                |
+| names                                | State, strategic region, victory-point and lake-province names from sites, lake shores, river valleys, ranges, regions, lands and seas by containment; shared names get a compass adjective.                                                                                               |
+
+Options of `create_world`: `development: { model }` (`geography`, the default for a geography world, or `legacy` for the random economy) and `autoStraits` (`true` or `{ maxGapPx }`, default 24 pixels, about 170 km) to also write a rule-less crossing for every narrow channel the model did not declare. Both need a geography (`MAP_DEVELOPMENT_REQUIRES_GEOGRAPHY`, `MAP_AUTO_STRAITS_REQUIRES_GEOGRAPHY`).
+
+Railways of a geography world follow a terrain-aware cost (ground, climb across the border, rivers, gates, model roads) and never cross a wall except at a gate; trunk lines of level 2 reach the cities of 8 or more victory points. The supply-node rule is unchanged.
+
+Diagnostics raised when a world is created (they need the model): `MAP_CROSSINGS_PLANNED`, `MAP_DEVELOPMENT_PLANNED` and `MAP_INLAND_SEA_CREATED` (info), `MAP_STRAIT_UNRESOLVED`, `MAP_STRAIT_DUPLICATE`, `MAP_STRAIT_NOT_NARROW`, `MAP_PASS_BLOCKED`, `MAP_RANGE_NOT_CLOSED`, `MAP_INLAND_SEA_SEALED`, `MAP_PORT_LAKE_UNSUPPORTED`, `MAP_PORT_SITE_NOT_COASTAL`, `MAP_SITE_UNPLACED` and `MAP_NAME_PLACEHOLDER` (warnings; the last counts the states, strategic regions and victory points still called "District N", "Region N" or "Settlement N"), and `MAP_IMPASSABLE_ROW_LIMIT` (refusal above 2,000 wall rows). Raised on any map by `hoi4.map_inspect`: `MAP_ADJACENCY_RULE_MISSING`, `_DUPLICATE` and `_INVALID` (errors), `MAP_ADJACENCY_RULE_UNUSED`, `MAP_IMPASSABLE_NOT_ADJACENT` and `MAP_UNIT_POSITION_MISSING` (information, or warnings when they are a pattern), `MAP_IMPASSABLE_NOT_LAND`, `MAP_ADJACENCY_ROW_LIMIT`, `MAP_STRAIT_NOT_NARROW` and `MAP_RAILWAY_CROSSES_IMPASSABLE` (warnings). The installed game raises nothing above information.
+
+Not done: whole provinces inside a massif are not made impassable states, the engine's handling of impassable rows by supply and the AI and of a naval base on an inland sea is not verified, and `positions.txt` stays empty as in the base game. Measured on the project's 5,120 x 2,560 synthetic model with about 6,000 provinces, the gameplay layer adds about 6 seconds to a 30 second `create_world` and the whole run peaks near 0.8 GiB.
+
 ## Positions and supply
 
 `regenerate_map_positions` places building, unit-stack and weather positions from province geometry. By default (`mode: missing`) it only adds what is absent: positions for each building model a state or province lacks (from `show_on_map` and the spawn points in `common/buildings`), a full unit-stack set for provinces without one, and a small and a big weather object for strategic regions without one. `mode: replace` rewrites the positions of the selected `stateIds`, `provinceIds` and `regionIds`. Interior points keep away from province borders, naval bases face the sea province they open onto, and floating harbours sit on the water and name their land province. `positions` limits it to `buildings`, `units` or `weather`; heights come from the heightmap.
@@ -429,8 +515,50 @@ 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.
 
+### Rivers, carved valleys and the river check
+
+A river the model draws is authoritative over the synthesised relief (ADR 0071). Where its course crosses a divide more than 22 height units above its bed (the cone of a volcano, a foothill, the tip of a range), the bed is cut through it as a gorge, and each crossing is reported as the warning `MAP_RIVER_CARVED_CROSSING` with the river, the climb and the divide (world pixel, height, and the nearest range or the volcano whose cone it crosses). Move the river or the feature in the model if the gorge is unwanted.
+
+Only a course that cannot exist is refused with `MAP_RIVER_UNREACHABLE_MOUTH`: a mouth on another landmass or not reachable over land, an unreachable source or via point, a lake without a free shore. The error lists every such river in `details.rivers` with its reason, or `blockedBy` another failed river.
+
+To check all of this without a write, call `hoi4.map_rewrite` with `preview: true` and `synthesisCheck: true` on the `create_world` operation: it runs the relief and river synthesis only, writes nothing and returns `MAP_SYNTHESIS_CHECK_READY` or `MAP_SYNTHESIS_CHECK_BLOCKED` with `data.synthesisCheck` (unreachable rivers and carved crossings). It does not run the partition, the countries or the climate stage (ADR 0070). A world that fails to generate returns only its own blockers, never the findings of the map it would replace.
+
 ### Feature-aware provinces, states and strategic regions
 
 By default provinces grow evenly from spread seeds and states and regions grow by breadth-first clusters, which ignore rivers, ridges and shores. Set `partition: "feature-aware"` (default `legacy`; a world given a `geography` defaults to it) to cut along natural lines instead (ADR 0058):
@@ -456,7 +584,7 @@ By default provinces grow evenly from spread seeds and states and regions grow b
 }
 ```
 
-All the engine rules hold as before: provinces are connected, no box exceeds an eighth of the map, no four provinces meet at a corner, provinces are at least 20 pixels where a same-kind neighbour exists, and at most 65,000 exist. A plan that needs more than 21,000 provinces is refused with `MAP_PARTITION_PROVINCE_COUNT_HIGH` and the fields to change; both partitions warn with that code above 14,000 provinces. Contradictory bands (`MAP_PARTITION_AREA_BANDS_CONTRADICTORY`), reversed ranges, a map too small for `minProvincePixels` (`MAP_PARTITION_MAP_TOO_SMALL`) and `partitionTuning` with `legacy` are refused before anything is written. Info notes report the provinces cut along rivers or straits (`MAP_PARTITION_SPLITS`) and coast pixels adjusted because a 2 x 2 block touched its own kind only at a corner (`MAP_PARTITION_MASK_SMOOTHED`). Check the result with `hoi4.map_inspect` and `quality: true` (border naturalness).
+All the engine rules hold as before: provinces are connected, no box exceeds an eighth of the map, no four provinces meet at a corner, provinces are at least 20 pixels where a same-kind neighbour exists, and at most 65,000 exist. A plan that needs more than 21,000 provinces is refused with `MAP_PARTITION_PROVINCE_COUNT_HIGH` and the fields to change; both partitions warn with that code above 14,000 provinces. Contradictory bands (`MAP_PARTITION_AREA_BANDS_CONTRADICTORY`), reversed ranges, a map too small for `minProvincePixels` (`MAP_PARTITION_MAP_TOO_SMALL`) and `partitionTuning` with `legacy` are refused before anything is written. Info notes report the provinces cut along rivers or straits (`MAP_PARTITION_SPLITS`) and coast pixels adjusted because a 2 x 2 block touched its own kind only at a corner (`MAP_PARTITION_MASK_SMOOTHED`). Check the result with `hoi4.map_inspect` and `quality: true` (border naturalness), or ask for it in the same call with `borderQuality`: `report` adds the measured province, state, region and country borders of the new world to the result, and `enforce` blocks the write below the targets (it needs the feature-aware partition and is refused with `legacy`, whose borders are at chance level). Countries of a feature-aware world without a reference picture are grown along natural lines by the territory service ([Assign territory to countries](#assign-territory-to-countries)).
 
 Code that needs the same cut calls `partitionWorld` (`src/hoi4_agent_tools/map/partition.ts`): it takes `PartitionFields` (distance to river, ridge strength, slope, terrain class, region id, fertility and a barrier mask; `partitionFieldsFromBitmaps` computes a basic version from `heightmap.bmp`, `terrain.bmp` and `rivers.bmp`, `partitionFieldsFromGeography` adds regions and walls) and returns the provinces, the barrier raster, the size distribution and a weighted province graph (`buildProvinceGraph`, `provinceEdgeCosts`) that the territory assignment service reuses.