hoi4-agent-tools 1.0.0 → 1.1.0

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

@@ -8,6 +8,7 @@ import { GuiHelperDocumentSchema, GuiPreviewScenarioSchema, GUI_TEXT_PACKAGE_MAX
 import { workspaceIdSchema, workspaceRelativePathSchema } from '../../schemas/common.js';
 import { PACKAGE_VERSION } from '../../version.js';
 import { requireServerScope } from '../server/base-tools.js';
+import { compactValidatedInputSchema } from '../server/context-schemas.js';
 import { autonomousFailureContext, autonomousResultArtifacts, executePlannedTransaction, } from '../server/transaction-execution.js';
 import { indexSkippedSourceSchema, nonNegativeIntegerSchema, sha256Schema, } from '../server/output-schemas.js';
 import { progressReporter } from '../server/progress.js';
@@ -88,19 +89,21 @@ const previewStateSchema = z.enum([
     'long-text',
     'missing-localisation',
 ]);
+const compactGuiScenarioSchema = compactValidatedInputSchema(GuiPreviewScenarioSchema, `Complete GUI preview scenario: https://github.com/klimPaskov/hoi4-agent-tools/blob/v${PACKAGE_VERSION}/docs/gui.md`);
+const compactGuiHelperSchema = compactValidatedInputSchema(GuiHelperDocumentSchema, `Complete GUI helper document: https://github.com/klimPaskov/hoi4-agent-tools/blob/v${PACKAGE_VERSION}/docs/gui.md`);
 const guiBaseInput = z
     .object({
     workspaceId: workspaceIdSchema,
     windowName: z.string().min(1).max(256),
-    scenario: GuiPreviewScenarioSchema,
+    scenario: compactGuiScenarioSchema,
 })
     .strict();
 const guiInspectInput = z
     .object({
     workspaceId: workspaceIdSchema,
     windowName: z.string().min(1).max(256).optional(),
-    scenario: GuiPreviewScenarioSchema.optional(),
-    relatedScenarios: z.array(GuiPreviewScenarioSchema).max(32).optional(),
+    scenario: compactGuiScenarioSchema.optional(),
+    relatedScenarios: z.array(compactGuiScenarioSchema).max(32).optional(),
 })
     .strict()
     .superRefine((value, context) => {
@@ -142,7 +145,7 @@ export function registerGuiTools(server, engine, context) {
     const studio = new ScriptedGuiStudio(engine);
     server.registerTool('hoi4.gui_inspect', {
         title: 'Inspect scripted GUI',
-        description: 'Inspect GUI, GFX, scripted logic, localisation, sprites, fonts, interactions, and animation sources for creation and cleanup. Provide a window scenario to include visual, state, click, AI, and cost diagnostics.',
+        description: 'Inspect GUI, GFX, script, localisation, and animation sources. Window/scenario selectors add offline visual and interaction diagnostics.',
         inputSchema: guiInspectInput,
         outputSchema: guiScanOutputSchema,
         annotations: artifactProducing,
@@ -315,7 +318,7 @@ export function registerGuiTools(server, engine, context) {
         .extend({
         states: z.array(previewStateSchema).max(14).optional(),
         resolutions: z.array(resolutionSchema).min(1).max(16).optional(),
-        comparisonScenario: GuiPreviewScenarioSchema.optional(),
+        comparisonScenario: compactGuiScenarioSchema.optional(),
     })
         .strict()
         .superRefine(({ scenario, states, resolutions }, context) => {
@@ -351,23 +354,23 @@ export function registerGuiTools(server, engine, context) {
     });
     server.registerTool('hoi4.gui_render', {
         title: 'Render scripted GUI artifacts',
-        description: 'Render deterministic full, cropped, annotated, click, hierarchy, state, resolution, comparison, and fidelity artifacts for GUI creation and cleanup review.',
+        description: 'Render deterministic offline review artifacts for one GUI window and scenario.',
         inputSchema: renderInput,
         outputSchema: guiRenderOutputSchema,
         annotations: artifactProducing,
     }, (input, extra) => render(input, extra, 'GUI_RENDERED'));
     server.registerTool('hoi4.gui_rewrite', {
         title: 'Create or clean up scripted GUI',
-        description: 'Create or replace a bounded scripted-GUI text package, or clean up one mod-owned .gui with exact patches. Source/helper mode accepts a main .gui plus additional .gui, .gfx, common/scripted_guis .txt, and localisation .yml source; binary art is referenced by those files, not uploaded. The complete package is validated, rendered, and applied in one call.',
+        description: 'Apply one validated source, helper, or exact-patch GUI package. Text dependencies use additionalFiles; binary art stays workspace-referenced.',
         inputSchema: z
             .object({
             mode: z.enum(['source', 'helpers', 'patches']),
             workspaceId: workspaceIdSchema,
             relativePath: workspaceRelativePathSchema,
             windowName: z.string().min(1).max(256),
-            scenario: GuiPreviewScenarioSchema,
+            scenario: compactGuiScenarioSchema,
             source: z.string().max(SOURCE_MAX_BYTES).optional(),
-            helper: GuiHelperDocumentSchema.optional(),
+            helper: compactGuiHelperSchema.optional(),
             additionalFiles: z
                 .array(z
                 .object({

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

@@ -7,6 +7,7 @@ import { workspaceIdSchema } from '../../schemas/common.js';
 import { mapAllocationRequestSchema, mapOperationSchema } from '../../schemas/map.js';
 import { PACKAGE_VERSION } from '../../version.js';
 import { requireServerScope } from '../server/base-tools.js';
+import { compactValidatedInputSchema } from '../server/context-schemas.js';
 import { autonomousFailureContext, autonomousResultArtifacts, executePlannedTransaction, } from '../server/transaction-execution.js';
 import { allocationEvidenceSchema, bitmapRenderHashesSchema, nonNegativeIntegerSchema, operationBlockerDataSchema, sha256Schema, } from '../server/output-schemas.js';
 import { progressReporter } from '../server/progress.js';
@@ -235,6 +236,7 @@ const mapOverlaySchema = z.enum([
     'unit-positions',
     'weather-positions',
 ]);
+const compactMapOperationSchema = compactValidatedInputSchema(mapOperationSchema, `Complete map operation: https://github.com/klimPaskov/hoi4-agent-tools/blob/v${PACKAGE_VERSION}/docs/map.md`);
 function validationSummary(validation) {
     return { passed: validation.passed, checks: validation.checks };
 }
@@ -346,7 +348,7 @@ export function registerMapTools(server, engine, context) {
     const nudger = new AgentNudger(engine);
     server.registerTool('hoi4.map_inspect', {
         title: 'Inspect HOI4 map',
-        description: 'Inspect map geometry and records for creation and cleanup, validate the complete map, return selected province/state/region details, preview requested free IDs and province colors, and export exact canonical province row runs when provinceIds are supplied.',
+        description: 'Validate the map and write linked inspection evidence. ID selectors return bounded records; provinceIds also export exact row-run geometry.',
         inputSchema: z
             .object({
             workspaceId: workspaceIdSchema,
@@ -499,7 +501,7 @@ export function registerMapTools(server, engine, context) {
     });
     server.registerTool('hoi4.map_render', {
         title: 'Render map inspection artifacts',
-        description: 'Render deterministic PNG, JSON, and pan-and-zoom HTML artifacts for map creation and cleanup review, with one semantic layer and bounded overlays.',
+        description: 'Render deterministic offline map artifacts for one layer and bounded overlays.',
         inputSchema: z
             .object({
             workspaceId: workspaceIdSchema,
@@ -540,11 +542,11 @@ export function registerMapTools(server, engine, context) {
     });
     server.registerTool('hoi4.map_rewrite', {
         title: 'Create or clean up map content',
-        description: 'Create or clean up states, provinces, regions, adjacencies, networks, positions, locators, and localisation with exact declarative operations, apply them in one call, and return pixel and semantic review artifacts.',
+        description: 'Apply validated declarative map operations in one call and return linked pixel and semantic evidence.',
         inputSchema: z
             .object({
             workspaceId: workspaceIdSchema,
-            operations: z.array(mapOperationSchema).min(1).max(100),
+            operations: z.array(compactMapOperationSchema).min(1).max(100),
             diffScale: z.number().int().min(1).max(16).optional(),
         })
             .strict(),

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

@@ -20,7 +20,7 @@ const modsOutputSchema = strictOperationResultSchema(z
 export function registerModsTool(server, engine, context) {
     server.registerTool('hoi4.mods', {
         title: 'List available HOI4 mods',
-        description: 'List the configured HOI4 mods available for focus-tree, GUI, and map inspection, rendering, creation, and cleanup.',
+        description: 'List configured HOI4 mod workspaces, optionally selecting one by ID.',
         inputSchema: z.object({ workspaceId: z.string().min(1).max(64).optional() }).strict(),
         outputSchema: modsOutputSchema,
         annotations: {

package/dist/hoi4_agent_tools/schemas/focus.js

@@ -32,6 +32,14 @@ const prerequisitesSchema = z
         .max(10_000),
 })
     .strict();
+const automaticPositionSchema = z
+    .object({
+    mode: z.literal('auto'),
+    pinned: z.literal(false),
+    preferredX: z.number().int().min(-100_000).max(100_000).optional(),
+    preferredY: z.number().int().min(-100_000).max(100_000).optional(),
+})
+    .strict();
 const positionSchema = z.discriminatedUnion('mode', [
     z
         .object({
@@ -50,14 +58,7 @@ const positionSchema = z.discriminatedUnion('mode', [
         pinned: z.boolean(),
     })
         .strict(),
-    z
-        .object({
-        mode: z.literal('auto'),
-        pinned: z.literal(false),
-        preferredX: z.number().int().min(-100_000).max(100_000).optional(),
-        preferredY: z.number().int().min(-100_000).max(100_000).optional(),
-    })
-        .strict(),
+    automaticPositionSchema,
 ]);
 const routeLockSchema = z
     .object({
@@ -305,6 +306,7 @@ export const focusPlanningSidecarSchema = z
         aiStrategyIds: z.array(z.string()),
         payoff: z.string().optional(),
         terminalKind: focusNodeSchema.shape.terminalKind,
+        autoPosition: automaticPositionSchema.optional(),
     })
         .strict()),
 })
@@ -317,12 +319,65 @@ export const focusLayoutDecisionSchema = z
         'relative',
         'placed',
         'moved_for_collision',
+        'moved_for_spacing',
         'moved_for_mutual_exclusion',
+        'moved_for_parent_order',
+        'moved_for_lane_bounds',
         'moved_to_reduce_crossings',
     ]),
     message: z.string(),
 })
     .strict();
+export const focusLayoutMetricsSchema = z
+    .object({
+    bounds: z
+        .object({
+        minimumX: z.number().int(),
+        maximumX: z.number().int(),
+        minimumY: z.number().int(),
+        maximumY: z.number().int(),
+        columnSpan: z.number().int().nonnegative(),
+        rowSpan: z.number().int().nonnegative(),
+        columnCount: z.number().int().nonnegative(),
+        rowCount: z.number().int().nonnegative(),
+    })
+        .strict(),
+    connectors: z
+        .object({
+        count: z.number().int().nonnegative(),
+        crossingCount: z.number().int().nonnegative(),
+        nodeIntersectionCount: z.number().int().nonnegative(),
+        longConnectorCount: z.number().int().nonnegative(),
+        totalHorizontalSpan: z.number().int().nonnegative(),
+        maximumHorizontalSpan: z.number().int().nonnegative(),
+        totalVerticalSpan: z.number().int().nonnegative(),
+        maximumVerticalSpan: z.number().int().nonnegative(),
+        totalManhattanSpan: z.number().int().nonnegative(),
+        maximumManhattanSpan: z.number().int().nonnegative(),
+    })
+        .strict(),
+    symmetry: z
+        .object({
+        siblingCohortCount: z.number().int().nonnegative(),
+        asymmetricSiblingCohortCount: z.number().int().nonnegative(),
+        totalSiblingDeviation: z.number().int().nonnegative(),
+        maximumSiblingDeviation: z.number().int().nonnegative(),
+        offAnchorSiblingCohortCount: z.number().int().nonnegative(),
+        totalSiblingAnchorDeviation: z.number().int().nonnegative(),
+        maximumSiblingAnchorDeviation: z.number().int().nonnegative(),
+        boundingCenterOffsetTwice: z.number().int().nonnegative(),
+    })
+        .strict(),
+    spacing: z
+        .object({
+        requiredSameRowSpacing: z.number().int().positive(),
+        sameRowPairCount: z.number().int().nonnegative(),
+        tooCloseSameRowPairCount: z.number().int().nonnegative(),
+        minimumSameRowSpacing: z.number().int().nonnegative(),
+    })
+        .strict(),
+})
+    .strict();
 export const focusLayoutSchema = z
     .object({
     treeId: z.string(),
@@ -338,6 +393,7 @@ export const focusLayoutSchema = z
         .strict()),
     decisions: z.array(focusLayoutDecisionSchema),
     diagnostics: z.array(z.unknown()),
+    metrics: focusLayoutMetricsSchema.optional(),
     layoutHash: z.string().regex(/^[a-f0-9]{64}$/u),
 })
     .strict();

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

package/docs/focus.md

@@ -18,12 +18,22 @@ For a missing target, call `hoi4.focus_rewrite` with `createIfMissing: true`. Re
 
 ## Clean an existing tree
 
-1. Inspect the tree and read its diagnostics.
-2. Render the current layout before changing coordinates.
-3. Keep prerequisites, mutual exclusions, availability, bypasses, rewards, icons, localisation, and AI behavior unless the task explicitly changes them.
-4. Group branches and lanes by their gameplay role. Existing coordinates remain fixed until movable focuses are marked for automatic placement; keep only deliberate anchors fixed.
-5. Submit the complete plan to `hoi4.focus_rewrite` and review its proposed layout for overlaps, connector crossings, branch spacing, and route readability.
-6. Inspect and render the result.
+For a layout-only cleanup of an existing national tree, call `hoi4.focus_rewrite` without a plan:
+
+```json
+{
+  "workspaceId": "my-mod",
+  "relativePath": "common/national_focus/my_tree.txt",
+  "treeId": "my_tree",
+  "layoutMode": "compact"
+}
+```
+
+Compact mode imports the tree, resets authored presentation coordinates and lane bounds, and performs a deterministic reflow in the same rewrite call. It keeps prerequisites, mutual exclusions, availability, bypasses, rewards, icons, localisation, AI behavior, and route/lane membership unchanged.
+
+The rewrite measures canvas bounds, same-row spacing, the same curved connector paths used by the renderer, connector lengths, connector-node intersections, branch balance, and overall centering. A bounded refinement pass moves automatic gateways and blockers only when the measured connector result improves. The rewrite refuses changes with close focuses, rendered crossings, excessive branch imbalance, an off-center canvas, or connector and size metrics outside absolute and source-relative limits.
+
+Use the default `layoutMode: "authored"` with a complete plan when deliberately designing coordinates or changing gameplay. Set `layoutMode: "compact"` with a complete plan when creating a large automatically arranged tree. Inspect and render calls remain useful before or after either rewrite mode, but a separate plan is not required for compact cleanup.
 
 A cleanup should not change gameplay relationships to improve the picture. One `prerequisite` block containing several focus IDs is an OR group; several prerequisite blocks are AND requirements.
 
@@ -35,6 +45,6 @@ If malformed or unsupported script makes a requested change ambiguous, the rewri
 
 ## What inspection checks
 
-Inspection and rendering can report missing references, invalid prerequisite structure, duplicate or overlapping positions, route conflicts, missing localisation or sprites, weak terminal branches, repeated rewards, and missing AI metadata. Renders are offline review artifacts, not game screenshots.
+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. Renders are offline review artifacts, not game screenshots.
 
 National trees with 200 or more focuses render review PNGs at half scale by default so large agent workflows stay responsive. Pass an explicit `reviewScale` from `0.25` through `1` when a different raster size is needed; HTML, SVG, JSON, layout, and diagnostics remain complete.

package/docs/setup.md

@@ -5,7 +5,7 @@ HOI4 Agent Tools requires Node.js 22 or 24.
 ## Install and initialize
 
 ```bash
-npm install --global hoi4-agent-tools@1.0.0
+npm install --global hoi4-agent-tools@1.1.0
 hoi4-agent-tools-setup --init
 ```
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hoi4-agent-tools",
   "mcpName": "io.github.klimPaskov/hoi4-agent-tools",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "MCP tools for coding agents to create and clean HOI4 focus trees, scripted GUIs, and maps",
   "type": "module",
   "license": "Apache-2.0",
@@ -84,7 +84,7 @@
     "fast-glob": "3.3.3",
     "fontkit": "2.0.4",
     "iconv-lite": "0.7.3",
-    "jose": "6.1.3",
+    "jose": "6.2.3",
     "sharp": "0.35.3",
     "zod": "4.4.3"
   },
@@ -98,7 +98,7 @@
     "@vitest/coverage-v8": "4.1.10",
     "ajv": "8.20.0",
     "ajv-formats": "3.0.1",
-    "eslint": "10.6.0",
+    "eslint": "10.7.0",
     "fast-check": "4.9.0",
     "pixelmatch": "7.2.0",
     "prettier": "3.9.5",

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.klimPaskov/hoi4-agent-tools",
   "title": "HOI4 Agent Tools",
   "description": "Create and clean HOI4 focus trees, scripted GUIs, and maps with coding agents.",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "repository": {
     "url": "https://github.com/klimPaskov/hoi4-agent-tools",
     "source": "github"
@@ -13,7 +13,7 @@
     {
       "registryType": "npm",
       "identifier": "hoi4-agent-tools",
-      "version": "1.0.0",
+      "version": "1.1.0",
       "transport": {
         "type": "stdio"
       }