hoi4-agent-tools 0.1.7 → 0.2.0

package/docs/adr/0012-autonomous-rewrites.md

@@ -0,0 +1,55 @@
+# ADR 0012: Autonomous one-call rewrites over internal durable journals
+
+- Status: accepted
+- Date: 2026-07-12
+
+## Context
+
+The original public write protocol exposed planning as a dry-run transaction and required a coding agent to carry a transaction ID and plan hash through separate diff, apply, status, and rollback calls. Those checks protected source integrity, but the caller choreography conflicted with the product's agent-first model: an operator had already selected the allowed roots and principals, yet an authorized agent still had to perform a second transaction-approval protocol before completing one supported edit.
+
+The integrity properties supplied by the shared transaction engine remain necessary. A multi-file HOI4 rewrite must still validate the complete proposal, reject stale input, journal exact original bytes, prevent cross-workspace access, recover from interrupted replacement, validate the written result, and restore the original state on failure.
+
+## Decision
+
+The server remains read-only by default. An operator may explicitly opt a canonical mod workspace into effective `writePolicy: "autonomous"`. That policy authorizes the supported domain rewrite tools for the already allowlisted workspace; it does not make game, dependency, fixture, artifact, cache, state, or unrelated roots writable.
+
+The primary mutating MCP surface is one call per domain:
+
+- `focus_rewrite`
+- `gui_rewrite`
+- `map_rewrite`
+
+Each rewrite call performs one server-owned sequence:
+
+1. authenticate and authorize the principal, workspace grant, and transport write scope;
+2. resolve every target beneath the canonical writable mod root;
+3. calculate the complete affected-file set and proposed bytes;
+4. run mandatory in-memory validation and produce relevant source and visual evidence;
+5. acquire the workspace lock and recheck roots, ownership, and all source hashes;
+6. persist an authenticated internal journal containing exact before bytes and intended replacements;
+7. stage and replace the affected files with recoverable logical atomicity;
+8. rebuild the affected index and run mandatory post-write validation;
+9. restore exact original bytes automatically if a write or required validation check fails; and
+10. return the completed rewrite outcome, diagnostics, changed files, and evidence resources.
+
+A blocker detected before mutation returns without changing source. A caller does not receive or resubmit a transaction ID or expected plan hash, page through a transaction diff as an authorization step, make a separate apply call, or invoke rollback. Internal plan hashes, manifests, protected revision heads, before blobs, and recovery states remain server implementation details and audit evidence where safe to expose in sanitized form; they are not bearer capabilities or caller approval tokens.
+
+An explicitly enabled `writePolicy: "transactions"` mode may remain as a compatibility surface for existing clients. It is not the primary documentation, prompt, example, discovery, or acceptance path, and autonomous acceptance cannot depend on its manual tools.
+
+Remote deployment retains the HTTP decision in ADR 0011: every request is authenticated, present Origin and Host values are checked, non-loopback access requires the configured HTTPS OAuth/OIDC policy, write calls require write scope, sessions are credential-bound routing state, and principal-to-workspace grants remain authoritative. Runtime registration cannot elevate itself to autonomous write authority; that authority must come from operator-controlled configuration or an equally explicit operator capability for the canonical root.
+
+ADR 0007 remains authoritative for per-workspace storage, authenticated journals, locking, exact-byte recovery, and crash reconciliation. This decision supersedes only the interpretation that ADR 0007's transaction ID and plan hash must form the primary caller workflow.
+
+## Rationale
+
+The operator's explicit workspace policy is the durable authorization decision. Repeating that decision through a server-specific multi-call confirmation protocol adds agent steps without expanding the filesystem or principal boundary. Keeping the complete safety sequence inside the mutating call gives an authorized coding agent a reliable one-call capability while retaining the protections that matter at the write boundary.
+
+Read-only scan, lint, layout, render, compare, and validation tools remain available for analysis and evidence. They are useful inputs to agent reasoning, but an autonomous rewrite does not depend on a mandatory preview transaction. A coding-agent host may still apply its own generic tool-use policy; the server protocol does not require a host-specific confirmation interface.
+
+## Consequences
+
+Public schemas, tool descriptions, prompts, examples, and acceptance tests use the domain rewrite tools and must not require transaction IDs, expected plan hashes, manual diff/apply sequences, or explicit rollback. Successful rewrites return review and validation evidence after the server has completed its protected sequence.
+
+Recovery is automatic for failed or interrupted rewrites. Intentional reversal of a successful accepted change is a new source edit through version control or another authorized rewrite, not a caller-invoked journal rollback capability.
+
+The server still provides recoverable logical atomicity rather than an operating-system transaction. Another process may briefly observe replacement steps, while stale-source checks and final validation prevent the server from reporting success for an unverified mixed state. Shared-filesystem deployments still require single-writer coordination as specified by ADR 0007.

package/docs/adr/README.md

@@ -11,3 +11,4 @@
 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

@@ -12,18 +12,24 @@ Suggested durable configuration locations:
 - 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).
+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.1.7
+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 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.
+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:
 
@@ -32,7 +38,7 @@ Generic host registration:
   "mcpServers": {
     "hoi4_agent_tools": {
       "command": "npx",
-      "args": ["-y", "hoi4-agent-tools@0.1.7"],
+      "args": ["-y", "hoi4-agent-tools@0.2.0"],
       "env": {
         "HOI4_AGENT_CONFIG": "/absolute/path/config.json"
       }
@@ -46,7 +52,7 @@ Codex registration:
 ```toml
 [mcp_servers.hoi4_agent_tools]
 command = "npx"
-args = ["-y", "hoi4-agent-tools@0.1.7"]
+args = ["-y", "hoi4-agent-tools@0.2.0"]
 startup_timeout_sec = 120
 
 [mcp_servers.hoi4_agent_tools.env]
@@ -63,16 +69,16 @@ A coding agent should select this server when a registered HOI4 workspace task i
 - 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.
+- 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 and write status.
+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 plan.
+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.
 
@@ -80,9 +86,9 @@ Large artifacts are returned as opaque `hoi4-agent://` resources. Read the linke
 
 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:
+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 transaction and final review artifacts.
+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.
@@ -98,10 +104,9 @@ The safe repair sequence is:
    }
    ```
 
-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.
+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.
 
@@ -120,17 +125,22 @@ A serious large-tree plan should define:
 - 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.
+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
 
-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:
+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.
 
-- 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.
+## Reviewed transaction compatibility
 
-This division lets agents decide when the MCP is useful and do the analysis autonomously without turning discovery into implicit source mutation.
+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,6 +1,6 @@
 # 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.
+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.
 
@@ -42,19 +42,35 @@ Large binary rasters and translation catalogs are selected lazily rather than re
 
 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
+## 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.
 
-A transaction includes the complete affected-file set, before/after hashes and blobs, operation
+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.
 
-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.
+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

@@ -6,6 +6,8 @@ Tools return compact summaries and links. Content is stored by SHA-256 under the
 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
@@ -83,7 +85,8 @@ artifact root beneath `storageRoots`, separate from its explicit cache root. Art
 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.
+changes use a separate autonomous-rewrite or reviewed-transaction surface and are confined to the
+mod root.
 
 ## Retention quotas
 
@@ -100,8 +103,8 @@ provenance manifest still counts as an entry and consumes its serialized bytes.
 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 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
@@ -110,7 +113,7 @@ also refuses when an externally modified store is already over its configured re
 
 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
+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.
 
@@ -120,7 +123,7 @@ Typical artifacts:
 - 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.
+- 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

package/docs/completion-report.md

@@ -1,162 +1,122 @@
-# Completion report: 0.1.6 public release
+# Completion report: 0.1.7 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)
+> 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.
 
-## Implemented scope
+- 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)
 
-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.
+## Outcome
 
-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.
+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
 
-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.
+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.
 
-Release-specific qualification also covers:
+The release gate and exact-source CI also verified:
 
-- 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.
+- 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.
 
-Known refusal cases and intentional boundaries remain documented in [Known limitations](limitations.md). They are explicit product constraints, not fallback implementations.
+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
 
-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 |
+| 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-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`.
+- 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 `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:
+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 | `0830611b33f26cb24baf05a8e997512db962ad4297966aa3b7db0bd1a37da179` |
-| `hoi4-agent-tools-0.1.6.tgz` | 669,550 | `b3925c8600fbb8eda44b7aaf36edb7d7bd056b84766e2b0cd6b4fa8fdbc385ce` |
-| `npm-pack.json`              |  49,941 | `a359bc1e0e64d119606a9c6bfb3f1a77725089e7cd5ada82c7efef839594543f` |
-| `release-identity.json`      |     431 | `d289937579f1e6e272264b09b4d9286a62e2c05c01a921d56dbc3d678fb5f576` |
+| `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: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.
+- 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 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`.
+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.
 
-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.
+- 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 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 |
+| 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; the supported boundaries are listed in
-[Known limitations](limitations.md), not hidden behind fallback rewrites.
+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.
 
-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.
+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 commands and failure behavior are documented in [Release and MCP Registry publication](release.md).
+Detailed release commands, ordering, recovery behavior, and the immutable earlier release-attempt history remain in [Release and MCP Registry publication](release.md).