hoi4-agent-tools 0.1.7 → 1.0.0

package/CHANGELOG.md

@@ -1,96 +1,14 @@
 # Changelog
 
-All notable changes are documented here. The project follows Semantic Versioning.
-
-## [0.1.7] - 2026-07-12
-
-### Added
-
-- Shipped an agent-integration guide as package documentation and an MCP resource, with persistent stdio registration, autonomous capability-selection rules, ranged artifact reads, and complete large focus-tree repair and creation workflows.
-- Added setup flags for stable workspace IDs and display names, plus both pinned `npx` and global-install client registration output.
-
-### Changed
-
-- Made MCP initialization instructions, prompts, metadata, and public documentation explicitly agent-first: coding agents proactively select HOI4 capabilities, while the separate hash-bound apply call remains governed by the coding-agent host's configured write policy.
-- Documented and advertised the fixed-to-automatic position transition required to opt an imported authored tree into full deterministic layout cleanup without silently moving source coordinates.
-
-### Fixed
-
-- Indexed only top-level event definitions instead of treating nested event calls as definitions, eliminating false event collisions and preventing valid mod symbols from being crowded out by game references.
-- Raised the bounded shared inventory to 500,000 symbols/references so a current game plus a feature-rich mod fits with safe headroom, and recorded the affected kind when a symbol ceiling drops a definition.
-- Reported unresolved focus sprites, localisation, and gameplay links as partial warnings only when an intentionally skipped source family could define that exact symbol kind; genuinely missing references remain missing diagnostics.
-- Made large-tree automatic layout reuse a coordinate occupancy index and incrementally cached connectors, bounded crossing optimization to a local 129-column window, and stopped evaluating a candidate as soon as it cannot beat the current crossing count. Complex 200+ focus plans now fit beneath the unchanged 500,000-operation safety ceiling instead of letting one unavoidable crossing exhaust the request.
-- Allowed national `focus_render` and `focus_plan_changes` calls to choose a bounded uniform viewport/raster scale; transaction plans also accept review-only spacing and padding. The server applies transaction settings to both before and proposed renders, so unusually wide or deep trees can retain meaningful baseline, diff, and final evidence without crowding node geometry, changing source-grid coordinates, or weakening artifact limits.
-- Modelled safe file-scoped focus-cost constants such as `cost = @focus_cost_standard` and preserved their exact source lexemes during layout-only updates. Unchanged numeric spellings and still-unmodelled cost tokens are also left byte-identical; deliberate supported cost edits remain targeted scalar replacements.
-- Kept large focus transactions below fixed manifest limits by storing complete proposed and post-write validation diagnostics as source-linked MCP resources. Transaction manifests retain blocker-first bounded summaries and explicit resource links while validation decisions still evaluate every diagnostic.
-
-## [0.1.6] - 2026-07-11
-
-### Fixed
-
-- Omitted the redundant explicit `isSecret: false` environment-variable value because the pinned official Registry schema defines the field's default as false and the Registry canonically omits that default from published metadata.
-- Kept strict byte-structural equality between checked-in `server.json` and the official Registry response instead of weakening verification with a broad normalizer.
-- Preserved the immutable complete `v0.1.5` npm, GHCR, GitHub Release, and MCP Registry publication whose final cross-surface verifier stopped only on the schema-default serialization difference, then advanced every synchronized release surface for the fix-forward release.
-
-## [0.1.5] - 2026-07-11
-
-### Fixed
-
-- Accepted the live GitHub Releases API's empty-string representation for an omitted optional asset label while continuing to reject every non-empty alternate label.
-- Added coverage for both canonical no-label representations and retained strict name, count, uploader, upload state, size, digest, API URL, and downloaded-byte verification for every release asset.
-- Preserved the immutable `v0.1.4` npm package and GHCR image plus its exact unpublished GitHub draft after the draft verifier stopped before Release publication or MCP Registry publication, then advanced every synchronized release surface for the fix-forward release.
-
-## [0.1.4] - 2026-07-11
-
-### Fixed
-
-- Verified BuildKit's commit-resolved Git context URI and digest while independently requiring the exact release tag, repository, release workflow ref, workflow SHA, push event, and `publish_image` job recorded in container provenance.
-- Added refusal coverage for altered container source URIs, digests, Dockerfile entry points, event/job identities, tag refs, repository identities, workflow refs, and workflow SHAs.
-- Preserved the immutable `v0.1.3` npm package and GHCR image whose post-push provenance verifier stopped before GitHub Release or MCP Registry publication, then advanced every synchronized release surface for the fix-forward release.
-
-## [0.1.3] - 2026-07-11
-
-### Fixed
-
-- Centralized the canonical slash-terminated npm Registry URL used by both the pinned npm audit subprocess and the strict provenance verifier, preventing equivalent configuration serialization from blocking verified publication.
-- Added refusal coverage for no-slash, insecure, credential-bearing, path-bearing, query-bearing, fragment-bearing, and lookalike npm Registry values.
-- Preserved the immutable `v0.1.2` tag and public npm package whose downstream verification stopped before GHCR, GitHub Release, or MCP Registry publication, then advanced every synchronized release surface for the fix-forward release.
-
-## [0.1.2] - 2026-07-11
-
-### Fixed
-
-- Canonicalized the downloaded release artifact to a contained absolute path before calling npm, preventing npm from interpreting a slash-containing relative tarball path as a GitHub repository shorthand.
-- Preserved the immutable failed `v0.1.1` tag as audit evidence and advanced every synchronized release surface for the first public stable publication.
-
-## [0.1.1] - 2026-07-11
-
-### Fixed
-
-- Allowed the first stable OIDC release only when npm reports the exact two-tag, one-version bootstrap state created by `0.0.0-bootstrap.1`; all additional, altered, stale, or ambiguous prerelease states still fail closed.
-- Preserved the immutable failed `v0.1.0` tag as audit evidence and advanced the synchronized package, server, Registry, schema, documentation, and client surfaces for the first public stable release.
-
-## [0.1.0] - 2026-07-11
-
-### Added
-
-- Lossless Clausewitz source model, cross-root symbol index, diagnostics, content-addressed artifacts, hash-bound transactions, crash recovery, and byte-exact rollback.
-- Focus Tree Workbench with planning models, stable layouts, route linting, source maps, continuous-focus palettes, and HTML/SVG/PNG/JSON review artifacts.
-- Scripted GUI Studio with connected GUI/GFX/script/localisation graphs, source-frame animation provenance, state and resolution galleries, comparisons, click and hierarchy reports, and per-render fidelity reports.
-- Bounded declarative GUI templates with deterministic expansion, type-aware HOI4 element compilation, explicit state variants, anchored layouts, grid-backed scroll-list handoffs, frame-based meters, and a counted raw escape hatch.
-- Agent Nudger declarative state, province geometry, strategic-region, adjacency, supply, railway, position, locator, ID, color, and map-rendering workflows.
-- Namespaced MCP tools, prompts, opaque resources, stdio and secured Streamable HTTP transports, setup diagnostics, package metadata, container publishing, and official MCP Registry release automation.
-
-### Fixed
-
-- Hardened generated artifact and transaction storage against descendant symlink/junction and Windows device-path escapes, restored interrupted runtime registrations before reuse, bounded artifact chunk and aggregate HTTP memory, sanitized internal MCP errors, corrected IPv6 loopback endpoints, rejected aliased transaction targets and opaque origins, separated writable runtime-mod roots from read-only source registration, and serialized monotonic releases.
-- Defined polygon edits with an explicit even-odd fill rule and integer raster-boundary coordinates, accepting the right/bottom edge while refusing overflow before raster work or allocation.
-- Made interrupted GitHub release publication recover through authenticated paginated draft discovery, unique release-ID binding, canonical bot-authored title/body/asset metadata, exact uploaded-asset verification, and immutable completed-rerun checks.
-
-### Security
-
-- Persisted atomic hash-only runtime registration claims and bound every artifact manifest/read/list/describe operation to the canonical workspace and owner identity.
-- Added an isolated operator `serverStateRoot`, random journal HMAC key, protected revision heads, exact-successor crash reconciliation, replay-safe bounded retention, strict journal schemas, and compact transaction structure limits.
-- Replaced non-hash create/delete provenance sentinels with explicit state metadata and added cancellation to artifact verification and rollback preflight.
-- Reserved the artifact-manifest filename namespace case-insensitively and made write-enabled setup require and diagnose an explicit isolated server-state root.
-- Kept read-only transaction inspection side-effect free, added cancellable bounded manifest reads and range caching, and refused post-validation or manifest-byte growth before it could create an unloadable journal.
+## 1.0.0 - 2026-07-12
+
+- Reduced the MCP surface to ten tools for discovering mods and creating, inspecting, rendering, and rewriting focus trees, scripted GUIs, and maps.
+- Added automatic writable discovery for every mod directly inside configured mod folders.
+- Replaced multi-step write workflows with one-call rewrites. Validation, atomic writes, stale-file checks, and failure recovery run inside the server.
+- Added large-tree workflow coverage, multi-file GUI creation, exact province-geometry export, and resumable artifact chunks.
+- Simplified setup to `hoi4-agent-tools-setup --init`, with automatic Windows, macOS, and Linux path detection and optional explicit path flags.
+- Consolidated the user documentation around setup and the three HOI4 work areas.
+- Removed runtime workspace registration, manual rollback, legacy write-policy inputs, and package-level library/schema exports.
+- Renamed the HTTP discovery grant to `allowDiscoveredMods`; it grants discovered mod IDs only.
+
+Earlier release history is available in the [Git tags](https://github.com/klimPaskov/hoi4-agent-tools/tags).

package/README.md

@@ -1,152 +1,66 @@
 # HOI4 Agent Tools
 
-HOI4 Agent Tools is a source-preserving Model Context Protocol server for coding agents working on Hearts of Iron IV mods. It combines a Focus Tree Workbench, Scripted GUI Studio, and headless map transaction system over one shared parser, workspace index, renderer, artifact store, and rollback engine.
+HOI4 Agent Tools is an MCP server that helps coding agents inspect, create, and clean up Hearts of Iron IV focus trees, scripted GUIs, and maps. It works directly with configured mod folders and produces offline renders for review. It does not launch or control the game.
 
-The agent workflow is:
+## What it does
 
-```text
-agentic HOI4 modding kit → coding agent selects the MCP capability → MCP tools → registered external mod workspace
-```
-
-The coding agent decides when the HOI4 capability is relevant; no special prompt is required once the server is registered with the agent host. The MCP server is the product interface. There is no focus editor, GUI editor, map editor, dashboard, or gameplay-tool CLI. The setup utility only creates server configuration, checks dependencies, and prints client configuration for review.
+- Focus trees: inspect structure and references, render layouts, create trees, and reorganize existing branches.
+- Scripted GUIs: trace GUI, GFX, scripted-GUI, and localisation links; render states; create or repair interface source.
+- Maps: inspect provinces, states, regions, adjacency, supply, and railways; render layers; create and repair exact map data.
 
-## Install
+## Setup
 
 Requires Node.js 22 or 24.
 
 ```bash
-npm install --global hoi4-agent-tools@0.1.7
-hoi4-agent-tools-setup --init-config /path/to/config.json --workspace /path/to/mod --workspace-id my_mod --workspace-name "My Mod" --game /path/to/game
-hoi4-agent-tools-setup --diagnose --config /path/to/config.json
-hoi4-agent-tools-setup --print-client-config --config /path/to/config.json
-```
-
-The generated configuration is read-only. Add `--enable-writes --server-state /separate/operator/state` only when transaction apply/rollback is intended. The state root is mandatory in transaction mode and must not overlap source, registration, artifact, cache, fixture, or generated-storage roots. The utility never edits an MCP client's settings.
-
-For one-shot stdio installation, clients can launch:
-
-```text
-npx -y hoi4-agent-tools@0.1.7
+npm install --global hoi4-agent-tools@1.0.0
+hoi4-agent-tools-setup --init
 ```
 
-with `HOI4_AGENT_CONFIG` set to the reviewed config path.
-
-For permanent local availability, keep the configuration at a durable absolute path, add the pinned stdio entry to the coding-agent host once, and restart that host. It will launch the server automatically on future tasks; a separate daemon is not required. A global npm installation is optional because the pinned `npx` entry is reproducible on every supported platform.
-
-## Minimal configuration
-
-```json
-{
-  "version": 1,
-  "writePolicy": "read-only",
-  "registrationRoots": ["/projects/hoi4-mods"],
-  "writableRegistrationRoots": [],
-  "workspaces": [
-    {
-      "id": "my_mod",
-      "name": "My Mod",
-      "root": "/projects/hoi4-mods/my-mod",
-      "gameRoot": "/games/Hearts of Iron IV",
-      "dependencyRoots": [],
-      "replacePaths": [],
-      "writeEnabled": false
-    }
-  ]
-}
-```
-
-All public paths are workspace-relative. Installed game and dependency roots are always read-only. Runtime mod registration additionally requires a separate, default-empty `writableRegistrationRoots` capability, so a read-only source root cannot be relabelled as a mod. Caches, render evidence, transaction manifests, and rollback blobs live under the workspace's ignored `.hoi4-agent/` directory; the private journal-authentication key and replay-protection heads live only under the separate operator `serverStateRoot`.
-
-See [configuration](docs/configuration.md) and [security](docs/security.md) before enabling writes.
-
-## Client configuration
-
-Generic JSON-based clients:
-
-```json
-{
-  "mcpServers": {
-    "hoi4_agent_tools": {
-      "command": "npx",
-      "args": ["-y", "hoi4-agent-tools@0.1.7"],
-      "env": { "HOI4_AGENT_CONFIG": "/absolute/path/to/config.json" }
-    }
-  }
-}
-```
+`--init` discovers the usual HOI4 game and mod locations and writes the default per-user configuration. No `HOI4_AGENT_CONFIG` environment variable is needed. For custom paths, multiple mod roots, or a custom config location, see [Setup](docs/setup.md).
 
-Codex `config.toml`:
+## Connect your agent
 
-```toml
-[mcp_servers.hoi4_agent_tools]
-command = "npx"
-args = ["-y", "hoi4-agent-tools@0.1.7"]
-env = { HOI4_AGENT_CONFIG = "/absolute/path/to/config.json" }
+```bash
+hoi4-agent-tools-setup --print-client-config
 ```
 
-On Windows, use `npx.cmd`. The complete persistent-registration and autonomous-selection guide is in [agent integration](docs/agent-integration.md). Additional repository examples are under [`examples/clients`](examples/clients).
-
-## Safe write protocol
-
-The server starts read-only. A source write requires all of the following:
-
-1. global transaction writes enabled with an isolated persistent `serverStateRoot`;
-2. a registered workspace whose canonical root is allowlisted and write-enabled;
-3. a completed in-memory dry run with all affected files and validation results;
-4. a persisted transaction ID and plan hash;
-5. authorization under the coding-agent host's configured write and approval policy;
-6. a separate `hoi4.transaction_apply` call carrying the exact expected plan hash.
-
-Apply rechecks the principal, workspace, canonical roots, expiry, and every source hash. Stale or cross-workspace plans are rejected. Multi-file changes use a durable journal and exact rollback blobs; post-write validation failure restores the original bytes. See [transactions](docs/transactions.md).
+Paste the printed Codex or generic global-install entry into your MCP client, then restart it. The utility prints the correct command for the current operating system.
 
-## Tool families
+## Tools
 
-- Projects: `hoi4.project_register`, `hoi4.project_scan`, `hoi4.project_status`
-- Focus: scan, import, lint, layout, render, plan changes, and export
-- GUI: scan, lint, deterministic render/state matrix, compare, and plan changes
-- Map: scan, inspect, allocate, plan, render, and validate
-- Transactions: `hoi4.transaction_diff`, `hoi4.transaction_apply`, `hoi4.transaction_rollback`, `hoi4.transaction_status`
-- Artifacts: `hoi4.artifact_list`, `hoi4.artifact_describe`, plus opaque MCP resources
+| Tool                 | Purpose                                                          |
+| -------------------- | ---------------------------------------------------------------- |
+| `hoi4.mods`          | List the writable mods available to the coding agent.            |
+| `hoi4.focus_inspect` | Read focus trees and report structural or reference problems.    |
+| `hoi4.focus_render`  | Render an existing focus tree or continuous palette.             |
+| `hoi4.focus_rewrite` | Create or update a focus tree.                                   |
+| `hoi4.gui_inspect`   | Read a scripted GUI and its linked assets and logic.             |
+| `hoi4.gui_render`    | Render GUI states and resolutions offline.                       |
+| `hoi4.gui_rewrite`   | Create or update a GUI source package.                           |
+| `hoi4.map_inspect`   | Read map, state, province, region, supply, and railway data.     |
+| `hoi4.map_render`    | Render map layers and overlays.                                  |
+| `hoi4.map_rewrite`   | Create or update map data from an ordered list of exact changes. |
 
-Large HTML, SVG, PNG, JSON, fidelity, hierarchy, map, and diff outputs are resources rather than oversized tool responses. MCP prompts guide safe focus, GUI, and map workflows but never bypass validation.
+Large outputs are linked `hoi4-agent://` resources. For resources over 1 MiB, follow the `continuationUri` returned in `_meta` until it is `null`; clients may also request byte ranges with `?offset=<bytes>&length=<bytes>`.
 
-## When coding agents should use this server
+## Create or clean content
 
-Agents should select HOI4 Agent Tools proactively when a registered workspace task touches national or continuous focus trees, scripted GUI/GFX/localisation, or map/state/province/rail/supply data.
+Ask your agent in normal task language. A typical workflow is inspect, render, rewrite, then inspect the result.
 
-Large focus trees are a flagship workflow. Use the workbench to import and preserve an existing tree, detect broken references and prerequisite semantics, find overlaps and avoidable connector crossings, assign coherent route lanes, produce deterministic review artifacts, and compile a hash-bound transaction. The same typed plan supports creating large new trees from an agent's structured interpretation of route requirements, including OR/AND prerequisites, mutually exclusive routes, shared support lanes, convergence, hidden branches, localisation, icons, AI metadata, and late-game payoffs.
+- Focus trees: "Create a complete national focus tree for this route specification," or "Clean up this tree's overlaps and route crossings without changing its prerequisites or rewards." See [Focus trees](docs/focus.md).
+- Scripted GUIs: "Create a scripted GUI for this mechanic," or "Render this window at common resolutions and fix clipping, missing assets, and click-region conflicts." See [Scripted GUIs](docs/gui.md).
+- Maps: "Create a state from these exact provinces," or "Inspect this state and split these provinces while keeping supply and railway references valid." See [Maps](docs/map.md).
 
-Start with `hoi4.project_status` or `hoi4.project_scan`, then use the relevant scan/lint/layout/render family. Existing authored coordinates are intentional stability anchors; a full repair must explicitly change movable imported nodes to automatic positions before `hoi4.focus_plan_changes`. Very large national-tree baseline, transaction, and final renders can use one uniform bounded review scale without changing compiled focus coordinates. See [Focus Tree Workbench](docs/focus-workflow.md).
+## HTTP
 
-## Offline rendering boundary
-
-Scripted GUI Studio parses and renders source files itself. It never launches, controls, automates, hooks, or captures screenshots from Hearts of Iron IV. Every GUI render is labelled as an offline representation and includes a fidelity report with modelled, approximated, ignored, missing, unsupported, and unresolved fields.
-
-## Streamable HTTP
-
-`hoi4-agent-tools-http` provides stateful Streamable HTTP on `127.0.0.1` by default. Every request requires authentication. Non-loopback deployment additionally requires HTTPS, OAuth/OIDC JWT verification, allowed origins, Host validation, principal-to-workspace grants, and limits. See [self-hosting](docs/self-hosting.md); legacy SSE-only transport is not provided.
-
-## Documentation
-
-- [Documentation index](docs/README.md)
-- [Agent integration and autonomous tool selection](docs/agent-integration.md)
-- [Architecture](docs/architecture.md)
-- [Focus workflow](docs/focus-workflow.md)
-- [GUI workflow and fidelity](docs/gui-workflow.md)
-- [Map workflow](docs/map-workflow.md)
-- [Testing and fixtures](docs/testing.md)
-- [Compatibility](docs/compatibility.md)
-- [Known limitations](docs/limitations.md)
-- [Release and Registry publication](docs/release.md)
+Rewrites validate and apply in one call. The installed game is never changed, and an interrupted multi-file rewrite is recovered automatically. Local MCP clients should use stdio; shared or remote deployments use the controls described in [HTTP](docs/http.md).
 
 ## Development
 
 ```bash
 npm ci
 npm run check
-npm run inspector
 ```
 
-Portable CI uses only project-owned synthetic fixtures. Opt-in local integration tests may read installed game and external mod sources but never copy or modify them.
-
-Apache-2.0 licensed. Hearts of Iron IV and Paradox Interactive are trademarks of their respective owners; this project is unaffiliated.
+See [Development](docs/development.md). Apache-2.0 licensed. Hearts of Iron IV and Paradox Interactive are trademarks of their respective owners; this project is unaffiliated.

package/SECURITY.md

@@ -2,16 +2,16 @@
 
 ## Supported versions
 
-Security fixes are provided for the latest minor release. A supported-version table is maintained in each release note.
+Security fixes are provided for the latest release.
 
 ## Reporting a vulnerability
 
 Do not open a public issue for a suspected vulnerability. Use GitHub private vulnerability reporting for this repository. Include the affected version, transport, configuration, reproduction steps, and expected impact. Reports are acknowledged within seven days; disclosure is coordinated after a fix is available.
 
-## Security model
+## Security boundary
 
-The server is read-only by default. Writes require an allowlisted canonical workspace, an explicitly enabled write policy, a dry-run transaction, a transaction ID, the expected plan hash, and a separate apply request. Remote operation additionally requires authentication, origin validation, request and concurrency limits, and principal-to-workspace authorization.
+HOI4 Agent Tools can read only configured mod, game, and dependency roots. Only configured mod roots can be changed; game and dependency data remain read-only. The server rejects paths outside those roots, unsafe links, stale edits, cross-mod access, and arbitrary command execution.
 
-The server never executes commands supplied by a caller. It rejects path traversal, symlink escapes, stale plans, cross-workspace transactions, and resource reads outside configured roots. Secrets and proprietary game assets are not exposed as resources.
+Offline renders may contain information derived from the configured workspace but do not expose raw installed-game assets as downloads. The server does not launch or control Hearts of Iron IV.
 
-See `docs/security.md` for deployment guidance and threat-model details.
+Local stdio is the recommended transport. Shared or remote HTTP deployments require authentication, exact origin checks, explicit mod access, HTTPS, and narrow filesystem mounts. See [HTTP setup](docs/http.md).

package/dist/bin/http.js

@@ -24,4 +24,3 @@ main().catch((error) => {
     })}\n`);
     process.exitCode = 1;
 });
-//# sourceMappingURL=http.js.map