hoi4-agent-tools 0.1.7 → 1.0.0

package/docs/agent-integration.md

@@ -1,136 +0,0 @@
-# Agent integration and autonomous tool selection
-
-HOI4 Agent Tools is a capability server for coding agents. Once an MCP-compatible host has a persistent server registration, the coding agent should decide when to invoke it from the task and repository context. The server does not need a special activation phrase and does not replace the agent's planning, research, or source-control workflow.
-
-## Persistent local availability
-
-Use a durable server configuration and a pinned package version. The MCP host launches the stdio process when needed, so no background daemon or manual server window is required.
-
-Suggested durable configuration locations:
-
-- Windows: `%APPDATA%\hoi4-agent-tools\config.json`
-- macOS: `~/.config/hoi4-agent-tools/config.json`
-- Linux: `~/.config/hoi4-agent-tools/config.json`
-
-Keep transaction state outside every game, mod, dependency, artifact, and cache root. Generated artifact/cache storage may also be placed outside the mod by using `storageRoots`, `artifactRoot`, and `cacheRoot`. See [configuration](configuration.md).
-
-Create and validate a configuration:
-
-```bash
-npm install --global hoi4-agent-tools@0.1.7
-hoi4-agent-tools-setup --init-config /absolute/path/config.json --workspace /absolute/path/mod --workspace-id my_mod --workspace-name "My Mod" --game /absolute/path/game
-hoi4-agent-tools-setup --diagnose --config /absolute/path/config.json
-hoi4-agent-tools-setup --print-client-config --config /absolute/path/config.json
-```
-
-The setup utility creates a read-only configuration unless `--enable-writes` and a separate `--server-state` root are supplied. `--print-client-config` prints both a pinned `npx` registration and an optional global-install registration. It does not edit an MCP host's settings.
-
-Generic host registration:
-
-```json
-{
-  "mcpServers": {
-    "hoi4_agent_tools": {
-      "command": "npx",
-      "args": ["-y", "hoi4-agent-tools@0.1.7"],
-      "env": {
-        "HOI4_AGENT_CONFIG": "/absolute/path/config.json"
-      }
-    }
-  }
-}
-```
-
-Codex registration:
-
-```toml
-[mcp_servers.hoi4_agent_tools]
-command = "npx"
-args = ["-y", "hoi4-agent-tools@0.1.7"]
-startup_timeout_sec = 120
-
-[mcp_servers.hoi4_agent_tools.env]
-HOI4_AGENT_CONFIG = "/absolute/path/config.json"
-```
-
-Use `npx.cmd` on Windows. Restart the coding-agent host after adding or changing the registration. Statically configured workspaces remain available across every server process; runtime `hoi4.project_register` registrations intentionally last only for the current process.
-
-## Autonomous selection rules
-
-A coding agent should select this server when a registered HOI4 workspace task involves any of these surfaces:
-
-- national focus trees or continuous focus palettes;
-- Clausewitz prerequisite, route-lock, mutual-exclusion, localisation, icon, AI, or linked-content validation;
-- scripted GUI, interface, GFX, sprites, fonts, animation states, deterministic previews, or visual comparisons;
-- states, provinces, province geometry, strategic regions, adjacency, supply nodes, or railways;
-- source-preserving dry runs, visual diffs, atomic multi-file apply, or rollback for those surfaces.
-
-Do not use the server for arbitrary shell commands, general repository edits, game automation, or in-game screenshots. It exposes typed HOI4 services, not a command runner.
-
-The normal first calls are:
-
-1. `hoi4.project_status` to discover the configured workspace ID and write status.
-2. `hoi4.project_scan` when a complete shared symbol/reference revision is useful.
-3. The relevant domain scan and lint tools.
-4. Deterministic layout/render/compare tools before a source plan.
-
-Large artifacts are returned as opaque `hoi4-agent://` resources. Read the linked resource instead of asking the tool to inline it. Artifact reads are range-bounded; use `?offset=N&length=1048576` until the complete advertised size has been retrieved.
-
-## Large focus-tree repair
-
-Use the Focus Tree Workbench for large or badly structured trees: broken or ambiguous prerequisites, duplicate coordinates, avoidable connector crossings, unstable route layout, missing references, weak convergence, or a tree whose visual structure no longer matches its route architecture.
-
-The safe repair sequence is:
-
-1. Call `hoi4.focus_scan`, `hoi4.focus_lint`, and `hoi4.focus_render` for the existing source. A very wide or deep national tree can pass `reviewScale` from `0.25` through `1.0`; retain that scale for transaction and final review artifacts.
-2. Read the complete imported plan resource and baseline HTML/SVG/PNG/JSON/source-map artifacts.
-3. Preserve prerequisites, exclusions, route locks, rewards, comments, raw passthrough, source locations, and provenance.
-4. Assign explicit `branchGroups`, `laneGroups`, `branchId`, and `laneId` metadata that reflect the intended route architecture.
-5. Keep only deliberate anchors fixed or pinned. Imported authored `x`/`y` values are intentionally treated as fixed; nodes do not become movable merely because `hoi4.focus_layout` was called.
-6. Change movable nodes to automatic positions, optionally retaining route intent with preferred coordinates:
-
-   ```json
-   {
-     "mode": "auto",
-     "pinned": false,
-     "preferredX": 8,
-     "preferredY": 12
-   }
-   ```
-
-7. Submit the complete plan to `hoi4.focus_plan_changes`. This performs the deterministic proposed layout, source-preserving compilation, lint, before/proposed render, bitmap comparison, and dry-run transaction. For a national tree whose default review canvas would exceed the bounded renderer, pass a uniform `reviewScale` from `0.25` through `1.0` (for example, `0.4` for a very large tree). It scales the complete visual rather than crowding node geometry, is applied identically to before and proposed artifacts, and does not change compiled focus coordinates. Optional `horizontalSpacing`, `verticalSpacing`, and `padding` controls remain available for intentional review-presentation changes.
-8. Follow every `hoi4.transaction_diff` cursor. Review the source map, changed fields, diagnostics, and visual artifacts.
-9. Apply only when the coding-agent host's write policy authorizes it, using the exact transaction ID and expected plan hash.
-10. Rescan, lint, and render the applied source. Use `hoi4.transaction_rollback` with the same hash if validation fails or the reviewed result is not acceptable.
-
-`hoi4.focus_layout` by itself is deliberately conservative. It preserves fixed, relative, pinned, and prior-stable nodes. Full-tree cleanup is an explicit plan decision because silently rearranging authored coordinates would be unsafe.
-
-## Creating a large focus tree
-
-The coding agent translates repository requirements and route descriptions into the public `FocusTreePlan` schema at `hoi4-agent://schema/focus-plan`. The MCP server validates and compiles that typed plan; it is not an unbounded natural-language generator.
-
-A serious large-tree plan should define:
-
-- a small number of intentional fixed anchors and automatic branch nodes;
-- lane and branch groups with stable order and horizontal bounds;
-- exact AND/OR prerequisite grouping;
-- reciprocal route exclusions where the UI should show them;
-- shared support lanes that stay available to compatible political routes;
-- convergence points, capstones, failure states, hidden/reveal metadata, and late-game payoffs;
-- localisation keys, icon sprites, AI weights/strategies, filters, and links to decisions, events, ideas, leaders, helpers, and formables;
-- raw passthrough for unsupported or not-yet-modelled Clausewitz content.
-
-For a new source beneath `common/national_focus`, call `hoi4.focus_plan_changes` with `createIfMissing: true`. Use `plan:<tree-id>` as creation `provenance.sourcePath` and 64 zeroes for both initial provenance hashes only when the target is missing. Existing targets normally use imported, hash-bound provenance; resolving intentional plan/source drift additionally requires explicit `authority: "plan"`. Creation refuses to append a different tree to an existing source file. The first write is still a dry-run transaction with transparent before evidence and complete proposed artifacts.
-
-## Write autonomy and safety boundary
-
-Agents may autonomously discover workspaces, scan, lint, lay out, render, compare, inspect artifacts, and prepare dry-run transactions. Source apply remains a distinct capability boundary:
-
-- global `writePolicy` must be `transactions`;
-- the canonical mod workspace must be allowlisted and `writeEnabled`;
-- the dry run must be complete and unexpired;
-- every source hash and principal/workspace binding is rechecked;
-- the separate apply call must carry the exact expected plan hash;
-- the coding-agent host's configured write/approval policy must authorize the apply.
-
-This division lets agents decide when the MCP is useful and do the analysis autonomously without turning discovery into implicit source mutation.

package/docs/architecture.md

@@ -1,60 +0,0 @@
-# Architecture
-
-All external behavior enters through MCP and calls typed domain services. Transport code validates protocol and authorization; it does not parse source, lay out graphs, render images, or write files.
-
-In this documentation, “read-only” scan, lint, layout, and render operations mean that registered HOI4 source bytes are never changed. MCP `readOnlyHint` follows the protocol's broader environmental-mutation meaning: an operation that creates content-addressed evidence under an allowlisted generated-artifact root advertises `readOnlyHint: false`, even though it cannot edit game or mod source.
-
-```text
-MCP tools/resources/prompts
-          │
-          ▼
-focus / gui / map services
-          │
-          ▼
-workspace resolver ─ source CST ─ symbol/reference index
-          │                 │
-          ├─ diagnostics ───┤
-          ├─ artifact store ┤
-          └─ transaction journal / diffs / rollback
-```
-
-## Workspace overlay
-
-A workspace combines a mod root, an optional installed-game reference root, ordered dependency roots, owner-scoped `replace_path` declarations, conventional subsystem roots, an artifact root, cache root, and optional fixture root. File traversal is stable. Same-relative-path files are shadowed by higher load order; each mod or dependency replacement declaration hides its subtree only in lower-precedence roots.
-
-Paths are canonicalized through existing ancestors. Public operations accept relative paths only and reject traversal, absolute/device/UNC paths, alternate data streams, Windows device names, and symlink or junction escapes. Game and dependency roots are immutable.
-
-## Source model
-
-The lexer retains original bytes and every token: whitespace, comments, strings, atoms, operators, braces, and invalid ranges. The CST retains duplicate keys and ordered blocks. Semantic readers build focus, GUI, or map views over CST ranges. Targeted replacements splice the original decoded text and encode with the original UTF-8 BOM, UTF-8, or Windows-1252 mode. No-change serialization returns original bytes.
-
-Malformed or unrepresentable content blocks rewriting. Unknown constructs remain raw source, not guessed fields.
-
-## Shared index
-
-`CoreEngine.scan` creates the authoritative `SymbolIndex` for an exact file snapshot. Focus consumes it directly; Scripted GUI receives that same index when building its connected source graph; Agent Nudger attaches it as `MapWorkspaceIndex.sharedIndex` and layers raster/network semantics over it. Proposed-file graphs rebuild through the shared index service rather than a domain parser authority.
-
-The index connects tree/focus IDs, sprites/textures, GUI elements, scripted GUI entries, localisation, state/province IDs and colors, strategic regions, adjacencies, supply nodes, railways, and cross-file references. Definitions retain load order, locations, collision state, and override evidence. Province definitions are resolved from each source root's own `default.map` selector, with lower partial roots inheriting the active selector name.
-
-Large binary rasters and translation catalogs are selected lazily rather than retained wholesale. Agent Nudger follows the active `default.map` province-bitmap selector. The shared index uses `l_english`, while GUI scenario operations add every explicitly requested language. This narrows scan breadth without changing source precedence or the lossless representation of any selected file.
-
-## Determinism
-
-Canonical JSON sorts keys with a locale-independent total UTF-16 code-unit order, traversal uses stable path ordering, layout tie-breaking is fixed, and artifact names are content hashes. Render profiles include source/asset/font hashes and all scenario geometry. Timestamps, host paths, locale collation, random IDs, and time zones are excluded from hashed artifacts.
-
-## Artifacts and transactions
-
-Generated evidence is content-addressed below `.hoi4-agent/artifacts`. Artifact manifests bind their
-immutable provenance address to a hash-only canonical workspace and configured/runtime owner
-identity. Runtime-generated stores also carry an atomic persistent owner claim, while statically
-configured workspaces retain one shared operator identity for their explicit grants.
-
-A transaction includes the complete affected-file set, before/after hashes and blobs, operation
-provenance, validation, source/binary/visual diffs, expiry, principal, workspace/root fingerprint,
-and plan hash. Its complete mutable journal is HMAC-authenticated by a random key beneath the
-isolated `serverStateRoot`; a protected latest-revision head prevents replay and bounds state to one
-head per admitted cache journal.
-
-Apply acquires one workspace write lock, rechecks preconditions, stages files on the same volume, journals deterministic replacements, rebuilds the affected index, and post-validates. Failure and startup recovery restore original blobs. This is recoverable logical atomicity; another process can briefly observe a replacement sequence.
-
-Detailed decisions are recorded in [ADRs](adr/README.md).

package/docs/artifacts.md

@@ -1,133 +0,0 @@
-# Artifact resources
-
-Tools return compact summaries and links. Content is stored by SHA-256 under the workspace's configured artifact root and exposed through an authorization-checked URI:
-
-```text
-hoi4-agent://workspace/{workspaceId}/artifact/{sha256}/{provenanceHash}/{name}
-```
-
-Each version-2 manifest records name, MIME type, byte size, content hash, artifact kind,
-tool/schema version, SHA-256 source hashes, render profile, domain metadata, and hash-only bindings
-for the resolved workspace and its configured or runtime owner. Filesystem paths and raw principals
-are not exposed. Missing/create/delete states belong in provenance metadata, never sentinel values
-inside the source-hash map.
-
-Very broad domain inventories retain a deterministic path/hash sample capped at 256 entries and
-128 KiB in the manifest, plus a count and a SHA-256 commitment over every length-prefixed sorted
-path/hash pair. This policy applies uniformly to project, focus, GUI, and map evidence. Complete
-inventories remain in the structured artifact content: project diagnostics use their exact `files`
-inventory, while focus, GUI, and map JSON evidence records exact source hashes. Binary and HTML
-review artifacts carry the same bounded, digest-backed provenance and are paired with the exact
-structured evidence for their bundle. Bounding a manifest therefore does not drop source evidence.
-The inventory commitment uses the versioned `sha256-length-prefixed-path-digest-v1` algorithm
-recorded in metadata.
-
-The manifest is immutable for a given content hash, provenance hash, and artifact name. Repeating the same bytes, name, and provenance is idempotent. Identical content produced from a different source revision receives a distinct provenance hash and URI while reusing the same content-addressed bytes, so earlier evidence is never rewritten or ambiguously relabelled.
-
-Artifact names ending in `.manifest.json`, under an ASCII case-insensitive comparison, are reserved
-for store metadata and rejected. This rule is identical on case-sensitive and case-insensitive
-filesystems, so content can never be mistaken for an inventory manifest.
-
-The workspace and owner bindings participate in the provenance hash and are checked by list,
-describe, and resource reads. A store reused by another workspace ID, canonical root topology, or
-runtime principal cannot enumerate or read the older manifests. Statically configured workspaces
-derive one shared operator identity, so all explicitly granted principals retain their intended
-access. Legacy unbound manifests and malformed/conflicting manifests fail closed; the server does
-not delete or relabel them automatically.
-
-Resource reads are limited to 1 MiB per request and support `offset` and `length` query parameters for large artifacts. Integrity verification streams the complete artifact through a fixed-size hash buffer while retaining only the requested range, so chunking also bounds payload memory. Only a complete payload that round-trips as strict UTF-8 may return MCP `text`. Every partial range, invalid UTF-8 payload, image, and other binary returns an MCP base64 `blob`, preserving exact bytes even when a range splits a code point. Clients advance `offset` by the decoded byte count and continue until a chunk is shorter than the requested length; the same rule applies to provenance-manifest resources.
-
-Some complete logical evidence, notably an installed workspace's GUI source graph, can legitimately
-be larger than `artifactMaxSingleBytes`. Callers that opt into byte-exact logical storage receive a
-normal artifact when the payload fits. An oversized payload instead returns one small canonical
-JSON index named `*.chunks.json`. The index records `type = hoi4-agent.chunked-artifact`, the
-original name, MIME type, size, SHA-256 and description, followed by ordered chunk resource links
-with indexes, byte offsets, lengths and SHA-256 hashes. Chunks use
-`application/octet-stream`; concatenating their decoded bytes in index order must reproduce the
-recorded original size and SHA-256 exactly. The index itself is limited to 1 MiB so an MCP client
-can read it in one request.
-
-The chunks and index are one atomic artifact batch. Every physical object and provenance manifest
-counts against the same aggregate-byte and entry quotas, every chunk remains at or below the
-configured per-object ceiling, and any admission, write, cancellation or owning-commit failure
-removes all files newly created by the bundle. This representation is lossless storage, not graph
-truncation or a quota bypass. `hoi4.gui_scan` and GUI render source-graph evidence return only the
-logical index link; agents follow its resource links when they need the full graph.
-
-Logical chunk preparation has a separate fixed 536,870,912-byte in-memory batch ceiling, and a
-lower configured `artifactMaxBytes` always wins. Before any payload is copied or hashed, admission
-validates every logical write's name, provenance and byte length, checks safe aggregate arithmetic,
-and projects the complete physical entry count after chunking. Preflight yields after each 256
-logical writes so cancellation can stop a broad batch before preparation. Preparation is then
-sequential, verifies that each admitted byte length is unchanged, and yields during hashing every
-16 MiB. Chunks share the one owned logical buffer during preparation instead of duplicating it.
-Crossing the fixed preparation ceiling fails with `ARTIFACT_LOGICAL_BATCH_LIMIT` before allocation.
-
-Artifact listing is paged at no more than 100 links. The store walks the complete sorted manifest
-inventory to verify bindings and compute an exact SHA-256 inventory revision, but retains only the
-requested page in memory. Cursors name the last public URI and are accepted only when that exact URI
-still occurs under the same revision. Listing and content verification honor request cancellation
-between directories, manifests, and hash chunks.
-
-Manifest reads stat the file and enforce the fixed 1 MiB ceiling before signal-aware JSON loading.
-Artifact writes, existing-content verification, quota walks, and queue waits also honor
-cancellation. A cancelled batch completes non-cancellable cleanup of every partial file. Once the
-caller's commit callback begins, that callback owns its critical-phase completion rules.
-
-## Storage placement
-
-A mod workspace defaults to `<mod>/.hoi4-agent/artifacts`; any in-mod override must remain beneath
-that exact generated subtree. An operator may instead place it beneath a configured `storageRoots`
-parent. A primary `game` or `dependency` workspace must always use an explicit operator-owned
-artifact root beneath `storageRoots`, separate from its explicit cache root. Artifact and cache
-roots cannot overlap each other or a source root.
-
-Generated artifact writes never make the game, dependency, or fixture source writable. Source
-changes are a separate transaction surface and are confined to the mod root.
-
-## Retention quotas
-
-The default per-workspace limits are:
-
-- `artifactMaxBytes`: 536,870,912 bytes across content and manifests;
-- `artifactMaxEntries`: 5,000 provenance manifests;
-- `artifactMaxSingleBytes`: 134,217,728 bytes for one content object;
-- serialized provenance manifests have a separate fixed 1 MiB ceiling and bounded fields.
-- one logical chunk-preparation batch has a fixed 536,870,912-byte ceiling.
-
-Content deduplication means a reused content hash adds no duplicate content bytes, while a new
-provenance manifest still counts as an entry and consumes its serialized bytes. Within one server
-process, the store measures current usage under an in-process per-root write queue before adding
-immutable files. Multi-artifact operations preflight all logical writes and their projected
-normal/chunk/index entries as one batch before payload copying or hashing, then retain newly created
-content and manifests only if their owning operation commits. A failed transaction-journal
-admission removes the diff files created by that batch without deleting pre-existing shared
-content or provenance. If the complete content and manifest would exceed a count, aggregate-byte,
-or per-object ceiling, the store refuses the write with `ARTIFACT_STORAGE_LIMIT`,
-`ARTIFACT_LOGICAL_BATCH_LIMIT`, `ARTIFACT_SINGLE_LIMIT`, `ARTIFACT_CHUNK_INDEX_LIMIT`, or
-`ARTIFACT_MANIFEST_LIMIT`; it does not write a truncated artifact or evict older evidence. Listing
-also refuses when an externally modified store is already over its configured retention budget.
-
-Artifact retention has no automatic garbage collector. Operator deletion is explicit and should
-be coordinated with active requests; deleting an artifact invalidates its URI. In contrast,
-transaction-journal cleanup follows the separate rules in [transactions](transactions.md). Do not
-share one writable artifact root between uncoordinated server processes; an operating-system
-storage service or operator must provide that coordination.
-
-Typical artifacts:
-
-- shared diagnostics and capability reports;
-- focus HTML/SVG/PNG/JSON, generated-source maps, and hash-bound planning sidecars;
-- GUI renders, galleries, hierarchy/click maps, comparisons, and fidelity reports;
-- map layers, changed-pixel reports, and before/after previews;
-- transaction manifests, source diffs, binary diffs, and validation reports.
-
-Structured JSON evidence records source paths, hashes, frame numbers, dimensions, formats, and
-fidelity metadata, but strips embedded `data:` payloads and glyph bitmap bytes. Composite SVG and
-PNG review renders may contain processed, source-derived icon, sprite-frame, or font-glyph pixels
-needed to inspect the requested interface; they are principal-bound generated evidence, not raw
-asset-file resources. The server never registers an installed-game, dependency, or mod raster/font
-file itself as an artifact.
-
-Artifacts are evidence. External HOI4 source remains authoritative. Deleting the configured
-artifact root invalidates only generated evidence, not mod content.

package/docs/compatibility.md

@@ -1,33 +0,0 @@
-# Compatibility and versioning
-
-## Runtime and platforms
-
-| Component | Supported                                                                                                                                         |
-| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Node.js   | 22.x and 24.x                                                                                                                                     |
-| Windows   | Windows 10/11 x64                                                                                                                                 |
-| Linux     | Current x64/arm64 distributions supported by Node and Sharp                                                                                       |
-| macOS     | Source package supported; CI coverage may lag Windows/Linux                                                                                       |
-| MCP       | Final `2025-11-25` only; initialization requests for other revisions receive `2025-11-25` so clients without that revision can disconnect cleanly |
-| HOI4      | Current file formats are capability-scanned; no fixed game installation path                                                                      |
-
-The `2026-07-28` protocol was a release candidate at 0.1.0 development time. Adopting its breaking stateless core and SDK v2 requires a compatibility release after it is final and supported by clients.
-
-The pinned SDK also recognizes `2025-06-18`, `2025-03-26`, `2024-11-05`, and `2024-10-07`, but this server does not claim them: its public contracts use the final revision's structured output and resource-link behavior. Both stdio and Streamable HTTP gate negotiation to `2025-11-25`. After initialization, every Streamable HTTP POST, GET, or DELETE must carry `MCP-Protocol-Version: 2025-11-25`; a missing or different value receives a JSON-RPC error with HTTP status 400.
-
-## Public schemas
-
-Tool names and input/output schemas are public API. Additive compatible changes use a minor release. Removing/renaming a tool or changing accepted/returned meaning requires a major release or a documented deprecation period. Schema version, package version, server implementation version, changelog, container tag, and Registry metadata stay synchronized.
-
-Focus consumers can use `focus-plan.schema.json`, `focus-planning-sidecar.schema.json`, and `continuous-focus-palette.schema.json`. The planning sidecar is hash-bound enrichment data; it is not Clausewitz source and is never loaded by HOI4.
-
-Focus reward import ships a reviewed native-effect identifier catalog derived from the official
-HOI4 1.19.2 `effects_documentation.md`. This lets the importer distinguish engine effects from
-direct `scripted_effect_id = yes/{ ... }` calls without requiring an installed game at runtime.
-Compatibility reviews must refresh the catalog when official effect identifiers change; unknown
-effect-position scalars remain source-linked helper references so stale or misspelled calls lint
-as missing instead of disappearing.
-
-## Configuration migration
-
-Config has an integer `version`. Unknown versions or fields fail with deterministic diagnostics. A future migration utility must print a reviewable proposed config and never edit a client or workspace silently.

package/docs/completion-report.md

@@ -1,162 +0,0 @@
-# Completion report: 0.1.6 public release
-
-- Released version: `0.1.6`
-- Report date: 2026-07-11
-- Status: complete; public delivery and installation independently verified
-- Release commit: `a7eeb31532c067fa2fe4e297f1710615b49a1273`
-- Annotated tag object: `4933d5bc28cc7941304d8573fcc1fea65ad74328`
-- Exact-source CI: [run 29161368937](https://github.com/klimPaskov/hoi4-agent-tools/actions/runs/29161368937)
-- Release workflow: [run 29161750887](https://github.com/klimPaskov/hoi4-agent-tools/actions/runs/29161750887)
-
-## Implemented scope
-
-The release provides the shared source-preserving core, Focus Tree Workbench, Scripted GUI Studio, Agent Nudger map workflow, read-only-by-default transaction controls, stdio and authenticated Streamable HTTP transports, package entry points, schemas, synthetic portable fixtures, and public deployment documentation described by this repository.
-
-The npm payload is explicitly limited to compiled entry points, documentation, schemas, `server.json`, and the project license, security policy, README, and changelog. Installed-game data, third-party mod data, fixtures, tests, source files, local configuration, and workspace artifacts are excluded.
-
-## Qualification evidence
-
-The release passed all 46 portable test files: 495 tests passed and one POSIX case was intentionally skipped on Windows. Enforced coverage is 88.44% statements, 78.25% branches, 91.28% functions, and 89.90% lines.
-
-Release-specific qualification also covers:
-
-- installation of the actual `npm pack` tarball into an isolated consumer, including an empty-cache install that proves `--prefer-offline` can fetch missing dependencies;
-- execution of the installed stdio, HTTP, and setup entry points;
-- package-content allowlisting, workspace-path leak checks, synchronized package and Registry metadata, and generated-schema checks;
-- npm dependency audit, registry signatures, and attestations;
-- live validation against the official MCP Registry API and pinned schema;
-- official MCP Inspector discovery against the production stdio entry point;
-- a production Docker build and protocol-only container stdio initialization/discovery; the release workflow records the final non-self-referential image digest in `container-image.json` rather than embedding an obsolete candidate digest into documentation copied inside that image;
-- immutable GitHub Action references, workflow and shell linting, strict release ordering, and byte-for-byte npm/GitHub release verification;
-- pinned Dockerfile-frontend and Node base-image digests, a multi-platform base supporting `linux/amd64` and `linux/arm64`, and a warning-free Docker build check;
-- read-only production-container checks proving OAuth metadata discovery, unauthenticated `401`, invalid-Origin `403`, protocol-only stdio initialization/discovery of all 26 tools, and a real read-only `hoi4.project_status` call from the non-root Node 22.23.1 runtime;
-- reusable bounded GUI helper templates, source-valid typed helper output, explicit state variants, deterministic scrolling and static meter handoffs, and refusal tests for unsafe or ambiguous helper compilation;
-- explicit even-odd province polygons with raster-boundary bounds checking before rasterization, pixel-center sampling, and refusal rather than clipping;
-- interrupted GitHub release recovery through a uniquely selected, byte-verified draft without asset overwrite or deletion, followed by exact immutable-release verification;
-- three installed-data qualifications covering a large vanilla/external focus workflow, a real GUI/GFX/font graph with deterministic full/annotated renders, and full province-map scan/render/storage without launching the game; the 302,497,021-byte canonical GUI graph was stored exactly as three bounded resources plus its one-read index while the default 128 MiB per-object ceiling remained enabled;
-- deterministic cold/warm benchmark output for the 255-focus, 203-visible-element GUI, and all-layer map workloads, including same-size/same-mtime content-hash invalidation.
-
-Known refusal cases and intentional boundaries remain documented in [Known limitations](limitations.md). They are explicit product constraints, not fallback implementations.
-
-## Public delivery status
-
-The immutable `v0.1.2` release attempt published npm with trusted-publisher provenance and then
-stopped in independent verification because the pinned npm subprocess reported the configured
-official Registry URL without a trailing slash while the strict verifier required the canonical
-slash-terminated spelling. npm's signature audit itself verified 448 registry signatures and 128
-attestations. The workflow correctly skipped GHCR, GitHub Release, MCP Registry, and final public
-verification. The public npm `0.1.2` bytes and tag are retained as immutable audit evidence.
-
-The immutable `v0.1.3` release attempt published and independently verified npm, then published
-the exact two-platform GHCR image with SPDX SBOM and SLSA v0.2 provenance attached to each runtime
-manifest. BuildKit correctly resolved its Git context URI to the immutable commit while recording
-the exact release tag and workflow identity in the provenance environment; the verifier had
-incorrectly required the URI itself to retain the tag. GitHub Release, MCP Registry, and final
-public verification were skipped. The npm `0.1.3` bytes, GHCR `0.1.3` digest, and tag are retained
-as immutable audit evidence.
-
-The immutable `v0.1.4` release attempt published and independently verified npm and the exact
-two-platform GHCR image, then staged a four-asset GitHub draft with the expected names, sizes,
-SHA-256 digests, upload states, and GitHub Actions bot ownership. The live Releases API represented
-the omitted optional asset label as an empty string while the verifier accepted only `null`, so the
-draft remained unpublished. MCP Registry and final public verification were skipped. The npm
-`0.1.4` bytes, GHCR `0.1.4` digest, tag, draft, and draft assets are retained as immutable or
-unchanged audit evidence.
-
-The immutable `v0.1.5` release attempt published and independently verified npm, the exact
-two-platform GHCR image with attestations, an immutable four-asset GitHub Release, and an
-active/latest official MCP Registry record. Its final cross-surface verifier stopped because the
-Registry canonically omitted explicit `isSecret: false`; the pinned official schema defines false
-as that field's default. Every public object had already passed its dedicated publication gate and
-remains unchanged as audit evidence.
-
-The `v0.1.6` workflow completed every validation, writer, and final verification job. Independent
-post-release audits then downloaded the public bytes again without changing release state.
-
-| Surface        | Verified public evidence                                                                                                                                                           | Status   |
-| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
-| GitHub source  | Public repository, annotated tag object `4933d5bc...`, and peeled commit `a7eeb315...`                                                                                             | Verified |
-| npm            | `hoi4-agent-tools@0.1.6`, exact tarball bytes, Registry signature, npm publish attestation, and SLSA provenance v1                                                                 | Verified |
-| GitHub release | Immutable [Release v0.1.6](https://github.com/klimPaskov/hoi4-agent-tools/releases/tag/v0.1.6), ID `352573210`, with exactly four byte-verified assets                             | Verified |
-| GHCR           | Anonymous `ghcr.io/klimpaskov/hoi4-agent-tools:0.1.6` index with exact amd64/arm64 runtimes and per-runtime SPDX/SLSA attestations                                                 | Verified |
-| MCP Registry   | Exact `io.github.klimPaskov/hoi4-agent-tools@0.1.6` record, strict-equal to `server.json`, with official `active` and `isLatest: true` state                                       | Verified |
-| Public install | Clean npm install, signature/attestation audit, setup diagnostics, stdio initialization/discovery, and authenticated Streamable HTTP session/resource/progress/cancellation checks | Verified |
-
-### npm and provenance
-
-- Published at `2026-07-11T17:41:29.169Z`; `latest` resolves to `0.1.6`.
-- Tarball: `669,550` bytes at `https://registry.npmjs.org/hoi4-agent-tools/-/hoi4-agent-tools-0.1.6.tgz`.
-- SHA-1: `0b240508a9dab4bc31a84ba1733ded3eb6983390`.
-- SHA-256: `b3925c8600fbb8eda44b7aaf36edb7d7bd056b84766e2b0cd6b4fa8fdbc385ce`.
-- SRI: `sha512-OaWY67zCEuwNj4AQZHlGBg59BoAQlgBoJ7soV5cOD2DiVClcjdz+8z0gBB02I1UXkoxFQgCcWw8YMVkBl0iLhg==`.
-- The npm and GitHub Release tarballs are byte-identical. Pinned npm `11.16.0` verified the
-  Registry signature, npm publish attestation, and SLSA provenance v1 with Rekor log index
-  `2145861311`. The provenance binds `release.yml`, `refs/tags/v0.1.6`, release commit
-  `a7eeb31532c067fa2fe4e297f1710615b49a1273`, and workflow run `29161750887`.
-
-### Immutable GitHub Release
-
-The GitHub Actions bot published Release ID `352573210` at `2026-07-11T17:46:42Z`; it is neither a
-draft nor a prerelease and reports `immutable: true`. Its body exactly matches tagged
-`CHANGELOG.md`. All assets have canonical empty labels, uploaded state, the canonical bot uploader,
-and API digest/size values matching independently downloaded bytes:
-
-| Asset                        |   Bytes | SHA-256                                                            |
-| ---------------------------- | ------: | ------------------------------------------------------------------ |
-| `container-image.json`       |     361 | `0830611b33f26cb24baf05a8e997512db962ad4297966aa3b7db0bd1a37da179` |
-| `hoi4-agent-tools-0.1.6.tgz` | 669,550 | `b3925c8600fbb8eda44b7aaf36edb7d7bd056b84766e2b0cd6b4fa8fdbc385ce` |
-| `npm-pack.json`              |  49,941 | `a359bc1e0e64d119606a9c6bfb3f1a77725089e7cd5ada82c7efef839594543f` |
-| `release-identity.json`      |     431 | `d289937579f1e6e272264b09b4d9286a62e2c05c01a921d56dbc3d678fb5f576` |
-
-### GHCR image and attestations
-
-- OCI index: `sha256:9593b77b50938a76341d293dd4ef97bb42224661a6a25dc28a1378e0109e0e5b`.
-- `linux/amd64`: `sha256:bda20a48cff5d5597467e22bb53b142bcb698420b637fe5cdc1f05107e7bce0f`.
-- `linux/arm64`: `sha256:52ed0aa7bf35de90f49364a94bb41fbd0136895a155af624fc26b4275631d735`.
-- The index has exactly two runtime and two attached attestation manifests, without orphans. Each
-  runtime has one SPDX 2.3 and one SLSA v0.2 statement whose sole SHA-256 subject is that runtime
-  digest. Provenance binds `Dockerfile`, `publish_image`, `refs/tags/v0.1.6`, the release workflow,
-  and the exact commit.
-- A fresh pull with an empty Docker configuration succeeded anonymously. A non-root, read-only,
-  network-disabled stdio smoke negotiated MCP `2025-11-25`, reported version `0.1.6`, and listed 26
-  tools. The default HTTP entry point also returned an authenticated Streamable HTTP initialization.
-
-### MCP Registry and public installation
-
-The exact official Registry endpoint returned a server object strict-equal to checked-in
-`server.json`, plus `status: active` and `isLatest: true`. `publishedAt`, `updatedAt`, and
-`statusChangedAt` are all `2026-07-11T17:46:54.873191Z`.
-
-A clean public installation fetched 132 packages only from `https://registry.npmjs.org`; its
-lockfile had no `file:`, `workspace:`, `link:`, repository-path, or other local resolution. The
-signature audit verified 131 installed package signatures and 17 attestations with no invalid or
-missing records. The installed setup entry point passed help, read-only config initialization,
-diagnostics, rendering probe, and client-config output. Installed stdio and authenticated,
-Origin-validated Streamable HTTP passed initialization, discovery, resources, prompts, progress,
-cancellation, and session deletion.
-
-## Acceptance coverage
-
-| Acceptance source                                 | Completion evidence                                                                                                                                                                                |
-| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `00_standalone_project_bootstrap.md`              | Independent public Git repository, Apache-2.0 licensing, project-owned instructions/docs/tests/workflows, installable npm package, immutable Release, and Registry metadata                        |
-| `01_shared_architecture.md`                       | One engine and shared workspace/source/index/diagnostic/configuration/transaction/artifact services exercised across Focus, GUI, map, and MCP acceptance tests                                     |
-| `02_focus_tree_workbench.md`                      | Synthetic and installed-data import/layout/lint/render workflows with deterministic HTML/SVG/PNG/JSON artifacts and source-linked diagnostics                                                      |
-| `03_scripted_gui_studio.md`                       | Deterministic full/crop/annotation/state/resolution/click-region/hierarchy/comparison rendering, source graph integration, bitmap diffs, and mandatory fidelity reports                            |
-| `04_agent_nudger.md`                              | Declarative state/province/geometry/region/adjacency/supply/railway transactions, global ID/color scans, split-data blockers, map artifacts, and rollback tests                                    |
-| `05_validation_delivery_and_agent_integration.md` | 495 portable tests, enforced coverage, synthetic CI fixtures, installed-data qualification, official MCP Inspector discovery, package/install tests, and end-to-end coding-agent workflows         |
-| `06_public_mcp_server.md`                         | Read-only-default stdio and secured Streamable HTTP, OAuth/origin/isolation/limit checks, typed handlers, resource-backed large artifacts, package/Release/GHCR/Registry publication, and examples |
-
-## Simplifications, omissions, and blockers
-
-No required feature was replaced by a mock tool, static placeholder diagram, manual editor,
-interactive dashboard, game automation, or unpublished package. No required acceptance item or
-release blocker remains. Engine-unknown syntax and renderer fields are preserved and explicitly
-reported through refusal diagnostics and fidelity reports; the supported boundaries are listed in
-[Known limitations](limitations.md), not hidden behind fallback rewrites.
-
-The immutable earlier release attempts and the exact unpublished `v0.1.4` draft remain unchanged as
-audit evidence. One independent post-release Registry read timed out and succeeded on retry; it did
-not affect the green release workflow or repeated successful verification.
-
-Detailed commands and failure behavior are documented in [Release and MCP Registry publication](release.md).