hoi4-agent-tools 0.2.0 → 1.1.0

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

@@ -0,0 +1,54 @@
+import { z } from 'zod/v4';
+import { compareCodeUnits } from '../../core/canonical.js';
+import { emptyServiceResult } from '../../core/result.js';
+import { nonNegativeIntegerSchema } from '../server/output-schemas.js';
+import { errorResult, strictOperationResultSchema, toolResult } from '../server/result.js';
+const modsOutputSchema = strictOperationResultSchema(z
+    .object({
+    count: nonNegativeIntegerSchema,
+    mods: z
+        .array(z
+        .object({
+        id: z.string().min(1).max(64),
+        name: z.string().min(1).max(256),
+        writable: z.boolean(),
+    })
+        .strict())
+        .max(1_000),
+})
+    .strict());
+export function registerModsTool(server, engine, context) {
+    server.registerTool('hoi4.mods', {
+        title: 'List available HOI4 mods',
+        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: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, ({ workspaceId }) => {
+        try {
+            const mods = (workspaceId === undefined
+                ? engine.list(context.principal)
+                : [engine.status(workspaceId, context.principal)])
+                .filter(({ kind }) => kind === 'mod')
+                .sort((left, right) => compareCodeUnits(left.id, right.id));
+            const result = emptyServiceResult(workspaceId ?? '', {
+                count: mods.length,
+                mods: mods.map(({ id, name, writable }) => ({
+                    id,
+                    name,
+                    writable,
+                })),
+            });
+            result.code = 'MODS_LISTED';
+            return toolResult(result);
+        }
+        catch (error) {
+            return errorResult(error, workspaceId ?? '');
+        }
+    });
+}

package/dist/hoi4_agent_tools/mcp/transports/bounded-stdio.js

@@ -178,4 +178,3 @@ export class BoundedStdioServerTransport {
         });
     }
 }
-//# sourceMappingURL=bounded-stdio.js.map

package/dist/hoi4_agent_tools/mcp/transports/event-store.js

@@ -83,4 +83,3 @@ export class SharedEventStoreBudget {
         this.#bytes = Math.max(0, this.#bytes - bytes);
     }
 }
-//# sourceMappingURL=event-store.js.map

package/dist/hoi4_agent_tools/mcp/transports/http.js

@@ -10,17 +10,7 @@ import { MCP_PROTOCOL_VERSION } from '../../version.js';
 import { authenticate, bearerChallenge, HttpAuthError, protectedResourceMetadata, validateHttpDeployment, } from '../security/auth.js';
 import { BoundedEventStore, SharedEventStoreBudget } from './event-store.js';
 import { FinalProtocolTransport } from './protocol-gate.js';
-const WRITE_SCOPED_TOOLS = new Set([
-    'hoi4.project_register',
-    'hoi4.focus_plan_changes',
-    'hoi4.focus_rewrite',
-    'hoi4.gui_plan_changes',
-    'hoi4.gui_rewrite',
-    'hoi4.map_plan',
-    'hoi4.map_rewrite',
-    'hoi4.transaction_apply',
-    'hoi4.transaction_rollback',
-]);
+const WRITE_SCOPED_TOOLS = new Set(['hoi4.focus_rewrite', 'hoi4.gui_rewrite', 'hoi4.map_rewrite']);
 const MCP_ALLOWED_METHODS = 'GET, POST, DELETE';
 const SINGLETON_SECURITY_HEADERS = new Set([
     'authorization',
@@ -744,4 +734,3 @@ export async function startHttpServer(engine, configuration, serverFactory) {
         },
     };
 }
-//# sourceMappingURL=http.js.map

package/dist/hoi4_agent_tools/mcp/transports/protocol-gate.js

@@ -48,4 +48,3 @@ export class FinalProtocolTransport {
         this.inner.setProtocolVersion?.(version);
     }
 }
-//# sourceMappingURL=protocol-gate.js.map

package/dist/hoi4_agent_tools/runtime.js

@@ -4,6 +4,10 @@ import { loadConfiguration } from './core/configuration.js';
 import { CoreEngine } from './core/engine.js';
 import { ServiceError } from './core/result.js';
 import { WorkspaceResolver } from './core/workspace.js';
+export function defaultConfigurationPath() {
+    const configRoot = process.env.APPDATA ?? process.env.XDG_CONFIG_HOME ?? path.join(homedir(), '.config');
+    return path.join(configRoot, 'hoi4-agent-tools', 'config.json');
+}
 export function configurationPath(arguments_ = process.argv.slice(2)) {
     const index = arguments_.indexOf('--config');
     if (index >= 0) {
@@ -15,7 +19,7 @@ export function configurationPath(arguments_ = process.argv.slice(2)) {
     }
     if (process.env.HOI4_AGENT_CONFIG !== undefined)
         return path.resolve(process.env.HOI4_AGENT_CONFIG);
-    return path.join(homedir(), '.config', 'hoi4-agent-tools', 'config.json');
+    return defaultConfigurationPath();
 }
 export async function createEngine(configPath = configurationPath()) {
     const configuration = await loadConfiguration(configPath);
@@ -24,4 +28,3 @@ export async function createEngine(configPath = configurationPath()) {
     await engine.initialize();
     return engine;
 }
-//# sourceMappingURL=runtime.js.map

package/dist/hoi4_agent_tools/schemas/common.js

@@ -37,7 +37,7 @@ export const diagnosticSchema = z
         'design',
         'rendering',
         'security',
-        'transaction',
+        'validation',
         'map',
         'configuration',
     ]),
@@ -48,4 +48,3 @@ export const diagnosticSchema = z
     details: z.record(z.string().max(256), z.unknown()).optional(),
 })
     .strict();
-//# sourceMappingURL=common.js.map

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,7 +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();
-//# sourceMappingURL=focus.js.map

package/dist/hoi4_agent_tools/schemas/map.js

@@ -567,4 +567,3 @@ export const mapAllocationRequestSchema = z.discriminatedUnion('kind', [
     })
         .strict(),
 ]);
-//# sourceMappingURL=map.js.map

package/dist/hoi4_agent_tools/schemas/transaction.js

@@ -101,4 +101,3 @@ export const transactionManifestSchema = z
     failure: z.object({ code: identifierSchema, message: summarySchema }).strict().optional(),
 })
     .strict();
-//# sourceMappingURL=transaction.js.map

package/dist/hoi4_agent_tools/version.js

@@ -1,7 +1,6 @@
 import { LATEST_PROTOCOL_VERSION } from '@modelcontextprotocol/sdk/types.js';
 export const PACKAGE_NAME = 'hoi4-agent-tools';
-export const PACKAGE_VERSION = '0.2.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;
-//# sourceMappingURL=version.js.map

package/docs/README.md

@@ -1,23 +1,10 @@
 # Documentation
 
-- [Architecture and shared engine](architecture.md)
-- [Architecture decisions](adr/README.md)
-- [Configuration and workspace registration](configuration.md)
-- [Agent integration and autonomous tool selection](agent-integration.md)
-- [Security and threat model](security.md)
-- [Autonomous rewrites, transactions, and recovery](transactions.md)
-- [Focus Tree Workbench](focus-workflow.md)
-- [Scripted GUI Studio](gui-workflow.md)
-- [Agent Nudger map workflow](map-workflow.md)
-- [Artifact resources](artifacts.md)
-- [Self-hosted Streamable HTTP](self-hosting.md)
-- [Testing, fixtures, and local integration](testing.md)
-- [Performance benchmark](performance.md)
-- [Compatibility and versioning](compatibility.md)
-- [Known limitations](limitations.md)
-- [Third-party notices](third-party-notices.md)
-- [Troubleshooting](troubleshooting.md)
-- [0.1.7 completion report](completion-report.md)
-- [Release and MCP Registry publication](release.md)
-- [HOI4 research ledger](research/source-ledger.md)
-- [MCP research review](research/mcp-2026-07-10.md)
+- [Setup](setup.md): install the server, configure HOI4 paths, and connect an MCP client.
+- [Focus trees](focus.md): inspect, create, render, and clean national or continuous focus content.
+- [Scripted GUIs](gui.md): inspect linked UI source, render states, and create or repair GUIs.
+- [Maps](map.md): inspect and edit provinces, states, regions, adjacency, supply, and railways.
+- [HTTP](http.md): run the MCP server for shared or remote access.
+- [Development](development.md): build, test, and contribute.
+
+For vulnerability reporting, see the repository [Security Policy](../SECURITY.md).

package/docs/development.md

@@ -0,0 +1,22 @@
+# Development
+
+Install dependencies and run the complete project check:
+
+```bash
+npm ci
+npm run check
+```
+
+`npm run check` runs formatting, type checks, tests, fixture checks, schema generation checks, build checks, and package validation. Use narrower commands during iteration:
+
+```bash
+npm run test
+npm run test:coverage
+npm run fixtures:check
+npm run build
+npm run inspector
+```
+
+Keep changes focused and include tests for behavior changes. CI fixtures must be synthetic and project-owned; never commit installed-game or third-party-mod content. Public tool or schema changes require compatibility review and a versioned release.
+
+See the package [Security Policy](../SECURITY.md) for private vulnerability reporting.

package/docs/focus.md

@@ -0,0 +1,50 @@
+# Focus trees
+
+Use `hoi4.focus_inspect`, `hoi4.focus_render`, and `hoi4.focus_rewrite` for national focus trees and continuous focus palettes. Start with `hoi4.mods` when the mod ID is not known.
+
+## Create a tree
+
+A complete plan should include:
+
+- tree ID and country assignment;
+- branch and lane groups;
+- exact prerequisites and mutual exclusions;
+- availability, visibility, bypass, and route locks;
+- rewards and links to decisions, events, ideas, characters, or scripted helpers;
+- focus positions, convergence points, and shared support branches;
+- titles, descriptions, icons, filters, and AI behavior.
+
+For a missing target, call `hoi4.focus_rewrite` with `createIfMissing: true`. Review the proposed and final artifacts returned by the rewrite, then inspect and render the result. Do not call a tree complete with placeholder rewards, missing localisation, missing icons, or absent AI choices.
+
+## Clean an existing tree
+
+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.
+
+## Layout metadata and unsupported script
+
+Branch names, lane assignments, working labels, and other planning-only data may be stored in a `.focus-plan.json` file beside the focus source. HOI4 does not load that file.
+
+If malformed or unsupported script makes a requested change ambiguous, the rewrite stops and explains the blocker instead of guessing.
+
+## 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. 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/gui.md

@@ -0,0 +1,37 @@
+# Scripted GUIs
+
+Use `hoi4.gui_inspect`, `hoi4.gui_render`, and `hoi4.gui_rewrite` for `.gui`, `.gfx`, `common/scripted_guis`, localisation, sprites, fonts, and linked decision entry points. Start with `hoi4.mods` when the mod ID is not known.
+
+## Create a GUI
+
+`hoi4.gui_rewrite` can work from supported source, targeted patches, or structured helpers. Source and helper rewrites may include one bounded text package: the main `.gui` plus additional interface `.gui`/`.gfx`, configured GFX `.gfx`, `common/scripted_guis/*.txt`, and localisation `.yml` files. The package is path-checked, parsed, linked, rendered, validated, and applied together in one rewrite. Existing text encodings are retained, while localisation is always written as UTF-8 with BOM.
+
+A package may contain at most 32 text files and 16 MiB of encoded source in total. Paths are compared portably, so aliases that differ only by letter case are rejected.
+
+Helpers cover common layouts such as anchors, rows, columns, stacks, grids, cards, tabs, scroll lists, meters, status panels, modals, and overlays. They compile to ordinary HOI4 GUI source; the finished mod has no runtime dependency on this server. Binary textures, fonts, and other art are referenced from `.gfx`/GUI source and must already exist in the workspace; the rewrite input does not upload binary art.
+
+Before writing:
+
+- define the root window, parent/context, element IDs, and dimensions;
+- register sprites, textures, fonts, and localisation used on screen;
+- provide button triggers, effects, scripted-GUI properties, dynamic-list wiring, and AI behavior where required;
+- render the important states and resolutions;
+- keep click regions aligned with visible controls.
+
+Rewrite once, then inspect and render the result.
+
+## Clean an existing GUI
+
+1. Inspect the root window and its linked GUI, GFX, scripted-GUI, and localisation source.
+2. Render the normal state and the states relevant to the task, such as hover, selected, disabled, warning, empty list, full list, minimum value, maximum value, or long text.
+3. Check common resolutions and UI scales when positioning or clipping can change.
+4. Fix the existing mod-owned file with targeted patches, a complete supported source replacement, or a structured helper replacement.
+5. Rewrite once, then inspect and render the result.
+
+Inspection checks missing assets and localisation, invalid sizes, overlap, clipping, overflow, conflicting click regions, invisible blockers, broken parents or contexts, list-row cuts, state conflicts, trigger/effect gaps, and resolution drift.
+
+## Offline preview limits
+
+The renderer does not run the game engine. Each render includes a fidelity report that separates fields it models from fields it approximates, ignores, cannot resolve, or does not support. Treat that report as part of the review.
+
+A rewrite stops if malformed or unsupported GUI script makes the requested change ambiguous. Runtime animation, masking, tiling, hardcoded controls, and dynamic values may require exact game precedents even when a useful offline preview is available.

package/docs/http.md

@@ -0,0 +1,53 @@
+# HTTP
+
+Local MCP clients should use the default stdio registration. Use `hoi4-agent-tools-http` only when the server must be reached by another process or machine.
+
+The HTTP server exposes the MCP endpoint at `/mcp`.
+
+JSON request bodies default to and are capped at 64 MiB. This leaves transport-envelope headroom for the bounded 16 MiB GUI text package and a maximum canonical map mask while the two-request concurrency ceiling keeps aggregate body bytes at or below 128 MiB.
+
+Resumable event history defaults to 2 MiB per session within the 16 MiB global store, enough to retain one framed 1 MiB artifact-resource chunk.
+
+## Loopback
+
+Keep the listener on `127.0.0.1`, configure a long random bearer token through an environment variable named by the HTTP config, and allow only the client origins you use. Do not place tokens in the config file or command line.
+
+Add an HTTP section to a config created by setup:
+
+```json
+{
+  "version": 1,
+  "serverStateRoot": "/var/lib/hoi4-agent-tools/state",
+  "modRoots": ["/projects/hoi4-mods"],
+  "workspaceStorageRoot": "/var/lib/hoi4-agent-tools/workspaces",
+  "http": {
+    "host": "127.0.0.1",
+    "port": 3210,
+    "allowedOrigins": ["https://agent.example"],
+    "tokens": [
+      {
+        "principal": "local-agent",
+        "tokenEnv": "HOI4_AGENT_HTTP_TOKEN",
+        "allowDiscoveredMods": true
+      }
+    ]
+  }
+}
+```
+
+Set `HOI4_AGENT_HTTP_TOKEN` to a random value of at least 32 characters, then run `hoi4-agent-tools-http --config PATH`. `allowDiscoveredMods` grants that principal only the mod IDs created by discovery beneath `modRoots`; it never grants unrelated explicit workspaces. For narrower remote access, define the permitted mods as explicit `workspaces`, list those IDs in `workspaceIds`, and omit `allowDiscoveredMods`.
+
+## Shared or remote access
+
+A non-loopback deployment needs:
+
+- HTTPS at a trusted reverse proxy;
+- OAuth/OIDC token validation;
+- an exact origin allowlist;
+- explicit user-to-mod grants;
+- narrow mounted mod and game paths;
+- request, connection, and session limits.
+
+Do not expose a developer home directory or a whole game library. The installed game and dependencies should be mounted read-only. Use separate server instances for teams that should not share operating-system access.
+
+The server never launches Hearts of Iron IV and does not need a desktop or Steam session. See the repository [Security Policy](../SECURITY.md) before exposing HTTP beyond loopback.

package/docs/map.md

@@ -0,0 +1,39 @@
+# Maps
+
+Use `hoi4.map_inspect`, `hoi4.map_render`, and `hoi4.map_rewrite` for provinces, states, strategic regions, adjacency, supply nodes, railways, positions, ownership, cores, claims, resources, buildings, and localisation. Start with `hoi4.mods` when the mod ID is not known.
+
+## Create or reshape map content
+
+Map changes may add, split, merge, remove, or redefine provinces and states; update strategic regions; edit normal or special adjacency; and update supply, railway, building, unit, or weather positions.
+
+Geometry must be exact. Use existing province IDs, integer polygon boundaries with the required fill rule, a validated raster mask, or explicit pixels. Natural-language geography can guide an agent, but it is not rewrite geometry.
+
+Pass up to 32 `provinceIds` to `hoi4.map_inspect` to receive a linked exact-geometry JSON artifact. It records the active map dimensions, unknown IDs, and each known province as maximal `[y, startX, endXExclusive]` runs sorted in top-left raster order. Derive a bounded pixel subset or mask from those runs before calling `hoi4.map_rewrite`; row runs are inspection evidence, not a rewrite geometry kind.
+
+For state or province moves, splits, merges, removals, or type changes, explicitly state what happens to applicable data:
+
+- state membership and strategic region membership;
+- manpower, resources, buildings, and victory points;
+- owner, controller, cores, and claims;
+- ports, supply nodes, and railways;
+- building, unit, weather, and entity positions;
+- normal and special adjacency;
+- state localisation.
+
+Build one ordered list of exact operations, call `hoi4.map_rewrite`, and review its before, proposed, and changed-area evidence. Then inspect and render the result.
+
+## Inspect and clean a map
+
+1. Inspect the affected map area and read reference diagnostics.
+2. Render a baseline with the relevant province, state, region, terrain, coastline, supply, railway, ownership, or building overlays.
+3. Build one ordered list of exact repair operations.
+4. Supply every required geometry and data-movement choice.
+5. Rewrite, then inspect and render the result.
+
+Common cleanup work includes duplicate IDs or colors, bitmap/definition mismatches, invalid state or region membership, broken adjacency, missing localisation, disconnected province geometry, invalid ports or victory points, and stale supply or railway references.
+
+The map tools do not infer a corridor, choose a replacement province, redistribute state data, reconnect a railway, or move a port without an explicit instruction. ID and color allocation checks the configured game, dependencies, and mod before choosing a value.
+
+## Review boundary
+
+Map renders are offline evidence. Final inspection checks that references remain valid and changes stay within the declared geometry. Unsupported or ambiguous changes stop with a blocker instead of applying a partial substitute.

package/docs/setup.md

@@ -0,0 +1,39 @@
+# Setup
+
+HOI4 Agent Tools requires Node.js 22 or 24.
+
+## Install and initialize
+
+```bash
+npm install --global hoi4-agent-tools@1.1.0
+hoi4-agent-tools-setup --init
+```
+
+The setup command discovers standard HOI4 game and mod locations, creates a separate storage folder for generated workspace data, and writes the default per-user config. Each configured mod root is a parent folder whose immediate child directories are individual mods. Every discovered mod is writable through the three rewrite tools; no per-mod write switch or approval step is required. The installed game remains reference-only.
+
+After connecting the MCP server, call `hoi4.mods` to confirm which mods are available.
+
+## Override discovered paths
+
+Use explicit paths when discovery is incomplete or when you want to expose more than one mod root:
+
+```bash
+hoi4-agent-tools-setup --init --mod-root /projects/hoi4-mods --mod-root /workshop/hoi4-mods --game-root "/games/Hearts of Iron IV" --workspace-storage-root /var/lib/hoi4-agent-tools
+```
+
+- `--mod-root PATH` adds a parent folder containing mods. Repeat it for additional locations.
+- `--game-root PATH` selects the installed game folder used as a read-only reference.
+- `--workspace-storage-root PATH` selects where indexes, renders, and other generated workspace files are stored.
+- `--config PATH` writes or reads a config at a custom path instead of the default per-user location.
+
+The corresponding config fields are `modRoots`, `gameRoot`, and `workspaceStorageRoot`.
+
+Linked directory entries are not followed. If a mod folder is a symlink or junction, configure the real parent directory as another `--mod-root`.
+
+## MCP client registration
+
+```bash
+hoi4-agent-tools-setup --print-client-config
+```
+
+Use the printed `globalInstall` or `codexTomlGlobal` entry. It is platform-correct and uses the default config without an environment variable. For a custom config, add `--config PATH` when printing the registration.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "hoi4-agent-tools",
   "mcpName": "io.github.klimPaskov/hoi4-agent-tools",
-  "version": "0.2.0",
-  "description": "Source-preserving HOI4 workbench with workspace-authorized autonomous rewrites for coding agents",
+  "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",
   "author": "HOI4 Agent Tools contributors",
@@ -29,27 +29,26 @@
   },
   "files": [
     "dist/",
-    "docs/",
-    "schemas/",
+    "docs/README.md",
+    "docs/setup.md",
+    "docs/focus.md",
+    "docs/gui.md",
+    "docs/map.md",
+    "docs/http.md",
+    "docs/development.md",
     "server.json",
     "README.md",
     "CHANGELOG.md",
     "LICENSE",
     "SECURITY.md"
   ],
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./schemas/*": "./schemas/*"
-  },
   "bin": {
     "hoi4-agent-tools": "./dist/bin/stdio.js",
     "hoi4-agent-tools-http": "./dist/bin/http.js",
     "hoi4-agent-tools-setup": "./dist/bin/setup.js"
   },
   "scripts": {
+    "prebuild": "node --eval \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint": "eslint .",
@@ -85,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"
   },
@@ -99,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

@@ -2,8 +2,8 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.klimPaskov/hoi4-agent-tools",
   "title": "HOI4 Agent Tools",
-  "description": "Agent-first HOI4 focus, scripted GUI, and map tools with workspace-authorized autonomous rewrites.",
-  "version": "0.2.0",
+  "description": "Create and clean HOI4 focus trees, scripted GUIs, and maps with coding agents.",
+  "version": "1.1.0",
   "repository": {
     "url": "https://github.com/klimPaskov/hoi4-agent-tools",
     "source": "github"
@@ -13,16 +13,7 @@
     {
       "registryType": "npm",
       "identifier": "hoi4-agent-tools",
-      "version": "0.2.0",
-      "environmentVariables": [
-        {
-          "name": "HOI4_AGENT_CONFIG",
-          "description": "Absolute path to a persistent allowlisted HOI4 Agent Tools server configuration file.",
-          "format": "filepath",
-          "isRequired": true,
-          "placeholder": "/absolute/path/to/config.json"
-        }
-      ],
+      "version": "1.1.0",
       "transport": {
         "type": "stdio"
       }

package/dist/bin/http.d.ts

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-export {};
-//# sourceMappingURL=http.d.ts.map

package/dist/bin/http.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/bin/http.ts"],"names":[],"mappings":""}