hoi4-agent-tools 0.2.0 → 1.0.0

package/docs/adr/README.md

@@ -1,14 +0,0 @@
-# Architecture decisions
-
-1. [Runtime and language](0001-runtime-and-language.md)
-2. [Lossless source model](0002-lossless-source-model.md)
-3. [Image and font codecs](0003-image-and-font-codecs.md)
-4. [Focus layout](0004-focus-layout.md)
-5. [Offline rendering](0005-offline-rendering.md)
-6. [MCP SDK and protocol](0006-mcp-sdk-and-protocol.md)
-7. [Storage and transactions](0007-storage-and-transactions.md)
-8. [Test strategy](0008-test-strategy.md)
-9. [Packaging and Registry](0009-packaging-and-registry.md)
-10. [Unsupported/refusal policy](0010-unsupported-and-refusal-policy.md)
-11. [HTTP security](0011-http-security.md)
-12. [Autonomous one-call rewrites](0012-autonomous-rewrites.md)

package/docs/agent-integration.md

@@ -1,146 +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 rewrite 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.2.0
-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 initialization command above creates a read-only configuration. To choose the recommended autonomous mode instead, replace that initialization command with:
-
-```bash
-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 --autonomous-writes --server-state /separate/operator/state
-```
-
-`--autonomous-writes` writes `"writePolicy": "autonomous"` and enables the named mod workspace. Use `--reviewed-writes --server-state /separate/operator/state` only when compatibility with the separate transaction review/apply sequence is required; `--enable-writes` remains a compatibility alias for reviewed mode. The flags are mutually exclusive. `--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.2.0"],
-      "env": {
-        "HOI4_AGENT_CONFIG": "/absolute/path/config.json"
-      }
-    }
-  }
-}
-```
-
-Codex registration:
-
-```toml
-[mcp_servers.hoi4_agent_tools]
-command = "npx"
-args = ["-y", "hoi4-agent-tools@0.2.0"]
-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 rewrites, visual diffs, and recoverable multi-file changes 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, effective `writePolicy`, 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 rewrite.
-
-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 autonomous 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 proposed and final evidence.
-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 once to `hoi4.focus_rewrite`. This performs deterministic proposed layout, source-preserving compilation, lint, before/proposed rendering, bitmap comparison, journal admission, application, index rebuild, and post-write validation. 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. Check `execution`, `changedFiles`, diagnostics, validation, source-map links, and visual evidence in the result. A blocked proposal has `execution: "planned"` and changes no source. A successful rewrite has `execution: "applied"`.
-9. Rescan, lint, and render when additional final evidence is useful. The rewrite call already rescans and post-validates; if any application or post-validation step fails, the journal restores every affected file automatically before failure is returned.
-
-`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_rewrite` 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 one-call rewrite retains transparent before evidence, complete proposed artifacts, and exact recovery bytes for the newly created source and sidecar.
-
-## Write autonomy and safety boundary
-
-Read-only remains the default. With global `writePolicy: "autonomous"` and `writeEnabled: true` on a canonical mod workspace, the server exposes only the one-call source tools:
-
-- `hoi4.focus_rewrite`;
-- `hoi4.gui_rewrite`;
-- `hoi4.map_rewrite`.
-
-Each rewrite internally creates a complete hash-bound plan, validates it, persists an authenticated journal and exact before-bytes, applies it under the workspace lock, rebuilds the shared index, and post-validates. Invalid proposals never apply. Stale source, wrong principal/workspace bindings, write-scope failure, application errors, final hash mismatch, and post-validation failures fail closed; failures after replacement begins trigger automatic restoration. Transaction status, diff, apply, and rollback tools are intentionally not registered in autonomous mode.
-
-MCP itself does not mandate a confirmation dialog for each mutating tool. The rewrite tools advertise `readOnlyHint: false` and `destructiveHint: true`, but those annotations are hints to the client. The server cannot override a coding-agent host policy that prompts for, blocks, or otherwise constrains the call. Operators grant server-side authority through configuration and, for HTTP, the `hoi4:write` scope; clients independently decide how that authority is presented to users.
-
-Git remains the project-history, collaboration, and intentional-revert layer. The authenticated journal is separate operational recovery: it prevents an interrupted or invalid multi-file rewrite from being reported as success or left partially applied.
-
-## Reviewed transaction compatibility
-
-Set `writePolicy: "transactions"` (or initialize with `--reviewed-writes`) only when a client or workflow still depends on the older review boundary. In that mode, the server exposes `hoi4.focus_plan_changes`, `hoi4.gui_plan_changes`, and `hoi4.map_plan`; callers page through `hoi4.transaction_diff`, then call `hoi4.transaction_apply` with the exact transaction ID and plan hash. `hoi4.transaction_status` and explicit `hoi4.transaction_rollback` are also available. The same planning, hash checks, journal, post-validation, and failure-recovery engine is used in both write modes.

package/docs/architecture.md

@@ -1,76 +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. The configured write policy selects the public MCP surface without changing the shared core implementation.
-
-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 write execution
-
-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.
-
-The server has three configured source policies. `read-only` authorizes no source mutation.
-`autonomous` registers `hoi4.focus_rewrite`, `hoi4.gui_rewrite`, and `hoi4.map_rewrite`, but not
-transaction status, diff, apply, or rollback tools. `transactions` is a compatibility surface that
-registers domain planning plus the separate transaction tools. MCP annotations remain truthful:
-the autonomous rewrite tools advertise `readOnlyHint: false` and `destructiveHint: true`. Those
-annotations do not mandate a client prompt, and the server cannot override its host's approval
-policy.
-
-Internally, both write policies call the same transaction core. A journal 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.
-
-In autonomous mode, the domain tool plans and validates, admits the journal, applies, rebuilds the
-index, and post-validates inside one call. Apply acquires one workspace write lock, rechecks
-preconditions, stages files on the same volume, and journals deterministic replacements. Failure
-and startup recovery restore original blobs automatically. This is recoverable logical atomicity;
-another process can briefly observe a replacement sequence, but the server never reports success
-for a partial result.
-
-Git provides durable project history and collaboration. The internal journal is deliberately
-independent of Git so failed multi-file writes recover even in an unversioned workspace.
-
-Detailed decisions are recorded in [ADRs](adr/README.md).

package/docs/artifacts.md

@@ -1,136 +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}
-```
-
-An applied autonomous rewrite returns a source-linked `*.execution-validation.json` resource with the complete pre-write and post-write checks, final target hashes, diagnostics, and any overflow-validation resource links. This public evidence omits the engine's internal transaction ID and plan hash.
-
-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 use a separate autonomous-rewrite or reviewed-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 rewrite-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,
-internal journal cleanup follows the separate rules in [autonomous rewrites and 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;
-- rewrite journals, 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,122 +0,0 @@
-# Completion report: 0.1.7 public release
-
-> Historical release record. Version 0.2.0 supersedes the agent-facing write workflow described here; see [ADR 0012](adr/0012-autonomous-rewrites.md) and the current workflow documentation.
-
-- Released version: `0.1.7`
-- Report date: 2026-07-12
-- Status: complete; public delivery, installation, and a real external-workspace transaction are verified
-- Release commit: `9718388626a29dc4b584ae235bdbe325689e44b0`
-- Annotated tag object: `d06a18d106a53007e12a202468cd85356ca91ef7`
-- Exact-source CI: [run 29183088020](https://github.com/klimPaskov/hoi4-agent-tools/actions/runs/29183088020)
-- Release workflow: [run 29183455724](https://github.com/klimPaskov/hoi4-agent-tools/actions/runs/29183455724)
-
-## Outcome
-
-The release provides one source-preserving engine for the Focus Tree Workbench, Scripted GUI Studio, Agent Nudger map workflow, MCP handlers, workspace resolution, Clausewitz parsing, symbol indexing, diagnostics, configuration, transactions, artifacts, diffs, and rollback data. It starts read-only, supports local stdio and secured Streamable HTTP, and is published as an installable package, a dual-platform container, an immutable GitHub Release, and an active/latest MCP Registry server.
-
-The coding agent selects the server from repository and task context once its MCP host has a persistent registration. No special activation phrase or background daemon is required. The public documentation covers pinned `npx`, optional global installation, durable configuration, Codex and generic client registration, self-hosted HTTP, safe transactions, and large focus-tree repair and creation.
-
-Version `0.1.7` additionally qualifies:
-
-- uniform `reviewScale` output for large national-tree baseline, transaction, and final artifacts without changing logical geometry or compiled coordinates;
-- exact import, schema, compilation, and targeted-update support for safe symbolic focus-cost constants;
-- complete proposed and post-write focus diagnostics as MCP resources while the bounded inline/manifest limits remain enforced;
-- sidecar-aware post-write focus validation without treating adjacent JSON planning metadata as Clausewitz focus source;
-- agent-first discovery and setup wording, with no human-request activation framing.
-
-No installed-game data, external-mod data, local configuration, runtime artifacts, test fixtures, source files, or tests are included in the npm payload.
-
-## Qualification evidence
-
-All 46 portable test files passed: 503 tests passed and one POSIX-only case was intentionally skipped on Windows. Enforced coverage is 88.58% statements, 78.34% branches, 91.38% functions, and 90.03% lines.
-
-The release gate and exact-source CI also verified:
-
-- deterministic project-owned focus, GUI, and map fixtures and generated schemas;
-- a 417-file package allowlist and clean installed entry points;
-- official MCP Inspector discovery against the production stdio server;
-- Node 22 and 24 on Windows and Linux plus the production container build;
-- zero dependency vulnerabilities, 448 dependency registry signatures, and 128 dependency attestations in the pinned release checkout;
-- live official MCP Registry schema/API validation;
-- strict tag, main ancestry, release ordering, immutable-release settings, and exact artifact identity;
-- stdio stdout isolation, authenticated/Origin-validated Streamable HTTP, limits, isolation, progress, cancellation, sessions, and resource reads;
-- source preservation, deterministic rendering, bitmap diffs, stale-plan rejection, atomic multi-file apply, post-write validation, exact rollback, symlink/path/cross-workspace security, and end-to-end coding-agent workflows.
-
-Independent final code and documentation reviews found no actionable defects. The code review covered symbolic cost preservation, uniform review scaling, complete diagnostic resources, capacity accounting, rollback behavior, sidecar filtering, and security boundaries.
-
-## Public delivery status
-
-| Surface        | Verified public evidence                                                                                                                               | Status   |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- |
-| GitHub source  | Public repository, annotated tag object `d06a18d...`, peeled commit `97183886...`, and green exact-source CI                                           | Verified |
-| npm            | `hoi4-agent-tools@0.1.7`, Registry signature, npm publish attestation, and SLSA provenance v1                                                          | Verified |
-| GitHub Release | Immutable [Release v0.1.7](https://github.com/klimPaskov/hoi4-agent-tools/releases/tag/v0.1.7), ID `352694363`, with exactly four byte-verified assets | Verified |
-| GHCR           | Anonymous `ghcr.io/klimpaskov/hoi4-agent-tools:0.1.7` OCI index with exact amd64/arm64 runtimes and attached attestations                              | Verified |
-| MCP Registry   | Exact `io.github.klimPaskov/hoi4-agent-tools@0.1.7` record with official `active` and `isLatest: true` state                                           | Verified |
-| Public install | Clean install, signature/attestation audit, stdio discovery, and authenticated Streamable HTTP qualification                                           | Verified |
-
-### npm and provenance
-
-- Published at `2026-07-12T07:09:58.926Z`; `latest` resolves to `0.1.7`.
-- Tarball: `688,684` bytes at `https://registry.npmjs.org/hoi4-agent-tools/-/hoi4-agent-tools-0.1.7.tgz`.
-- SHA-1: `6c34d998f664b846de4a9b60a6dbadd39898a6cc`.
-- SHA-256: `e0c08ca4db2347dfadc767eea230d4c24071b6f54b1927c7e2a9aa2eec524b0e`.
-- SRI: `sha512-PmCgPyh/qA5dj6jgCpMKsKqFcQCVk0PdMa2PwATfcJ4EETbKgknJEKuaxHLb+UoPaFiDkHSQEJu2fF/UV8EGfQ==`.
-- The npm and GitHub Release tarballs are byte-identical. The npm publish attestation is recorded at Rekor log index `2148574615`; SLSA provenance v1 is recorded at index `2148573874` and binds `release.yml`, `refs/tags/v0.1.7`, release commit `9718388626a29dc4b584ae235bdbe325689e44b0`, and release run `29183455724`.
-
-### Immutable GitHub Release
-
-The GitHub Actions bot published Release ID `352694363` at `2026-07-12T07:15:14Z`. It is neither a draft nor a prerelease and reports `immutable: true`.
-
-| Asset                        |   Bytes | SHA-256                                                            |
-| ---------------------------- | ------: | ------------------------------------------------------------------ |
-| `container-image.json`       |     361 | `06695fa817a1ac9bc2fbb94840c817732875fec0988fe6caa23d46fec75983cb` |
-| `hoi4-agent-tools-0.1.7.tgz` | 688,684 | `e0c08ca4db2347dfadc767eea230d4c24071b6f54b1927c7e2a9aa2eec524b0e` |
-| `npm-pack.json`              |  50,050 | `9417225028ae5f516c5f727785eedf8764842d96e98a9674caab0c671dea3312` |
-| `release-identity.json`      |     431 | `49318a7d830e410520e61c6d7f9e67af2be8f072ecde50645f2d19cb962c5a79` |
-
-### GHCR image and attestations
-
-- OCI index: `sha256:b9651c3647d6f0efe563f82a7973ab4dcde7165546507a7fe6e4e429b0c31f0c`.
-- `linux/amd64`: `sha256:c4927b19b736ced1e528694e8f53bffd8f28066463ab806eacce1ee064715741`.
-- `linux/arm64`: `sha256:372c9ac76ced1cd7afb03e985cbb17855f9e44500257ca816c5f376ad233db7b`.
-- The index exposes exactly two runtime manifests and one attached attestation manifest per runtime. The checked-in release workflow verifies SPDX SBOM and SLSA statements, anonymous access, exact source identity, non-root execution, read-only container behavior, and both supported architectures.
-
-### MCP Registry and public installation
-
-The official Registry returned `io.github.klimPaskov/hoi4-agent-tools@0.1.7` with `status: active` and `isLatest: true`. `publishedAt`, `updatedAt`, and `statusChangedAt` are all `2026-07-12T07:15:29.426439Z`.
-
-A fresh independent public install fetched 132 packages. Its signature audit verified 131 installed-package signatures and 17 attestations with no invalid or missing records. Installed stdio and authenticated, Origin-validated Streamable HTTP initialization/discovery and protocol workflows passed.
-
-## Real large-focus transaction proof
-
-The published `0.1.7` stdio server was exercised against a 238-focus external mod workspace without copying that workspace into this repository or package.
-
-- Baseline import preserved all 238 focus IDs and symbolic costs and reported 15 avoidable connector crossings.
-- The structured plan used 14 branch groups, 12 ordered lanes, 16 fixed anchors, and 222 automatically placed nodes.
-- The proposed layout has 238 unique coordinates, zero parent-order violations, zero connector-crossing findings, and zero errors or blockers.
-- Source and semantic projections are byte-identical after normalising only focus `x`/`y` and `continuous_focus_position`; prerequisites, exclusions, rewards, triggers, comments, unknown fields, raw blocks, ordering, encoding, and symbolic costs are preserved.
-- The dry run emitted one complete transaction-diff page with 14 artifacts. A second fresh dry run reproduced every non-manifest artifact byte-for-byte.
-- A public-package apply passed all eight validation checks. Explicit rollback restored the exact baseline source hash and removed the newly created planning sidecar. A fresh transaction was then applied and retained.
-- Final scan/lint/render recovered all planning metadata and reproduced the reviewed 6317 by 1997 PNG exactly at `reviewScale: 0.4`.
-- Complete proposed and post-write diagnostic resources retained 116 content-specific repeated-reward warnings with zero hard findings. The fixed transaction diagnostic ceiling was not raised or bypassed.
-
-## 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 across Focus, GUI, map, and MCP tests                                                           |
-| `02_focus_tree_workbench.md`                      | Source-preserving import/layout/lint/render/create/update workflows, complex route metadata, deterministic HTML/SVG/PNG/JSON, and source-linked diagnostics                                         |
-| `03_scripted_gui_studio.md`                       | Deterministic full/crop/annotation/state/resolution/click-region/hierarchy/comparison rendering, integrated source graphs, 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` | 503 portable tests, enforced coverage, synthetic CI fixtures, installed-data qualification, official Inspector, package/install checks, and 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 artifacts, package/Release/GHCR/Registry publication, and client 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. Supported boundaries remain listed in [Known limitations](limitations.md), not hidden behind fallback rewrites. The real external focus workflow deliberately preserved 116 gameplay-design warnings because it was a layout-only transaction; those warnings are reported above and are not suppressed by the server.
-
-Detailed release commands, ordering, recovery behavior, and the immutable earlier release-attempt history remain in [Release and MCP Registry publication](release.md).