hoi4-agent-tools 0.1.6 → 0.2.0

package/docs/map-workflow.md

@@ -1,6 +1,6 @@
 # Agent Nudger map workflow
 
-Agent Nudger is a headless declarative map transaction service for coding agents. HTML/PNG/JSON maps are inspection evidence, not a manual editor.
+Agent Nudger is a headless declarative map rewrite service for coding agents. HTML/PNG/JSON maps are inspection evidence, not a manual editor.
 
 ## Indexed sources
 
@@ -8,14 +8,14 @@ The shared scan connects province bitmap and definitions, states, strategic regi
 
 ## Geometry input
 
-Province geometry apply requires one exact representation:
+Province geometry rewrite requires one exact representation:
 
 - selected existing province IDs;
 - polygon with integer raster-boundary coordinates and explicit `fillRule: "even-odd"`;
 - raster mask manifest with dimensions, origin, exact selected-pixel count, SHA-256, and canonical Base64 data;
 - explicit absolute pixel region (`kind: pixels`).
 
-Natural-language descriptions can guide a coding agent, but are not accepted as apply geometry.
+Natural-language descriptions can guide a coding agent, but are not accepted as rewrite geometry.
 
 Polygon vertices describe raster cell boundaries, not pixel indices. For a raster of `width` by `height`, every vertex must use an integer `x` from `0` through `width` and an integer `y` from `0` through `height`; the right and bottom boundary values `width` and `height` are valid. A greater coordinate is rejected with `MAP_GEOMETRY_OUT_OF_BOUNDS` before bounding-box or raster-work allocation, and polygon geometry is never silently clipped. Rasterization samples each candidate pixel at its center, `(x + 0.5, y + 0.5)`, using the required even-odd fill rule. Every selected center must still belong to the declared source province.
 
@@ -33,7 +33,7 @@ Split/merge/move operations do not guess manpower, resources, buildings, victory
 - exact manifest values;
 - block until resolved.
 
-Proportional rounding is deterministic and checked for conservation. The transaction remains blocked while any required policy is unresolved.
+Proportional rounding is deterministic and checked for conservation. The rewrite remains blocked while any required policy is unresolved.
 
 State move, split, and merge manifests also declare `ports`, `supplyNodes`, `railways`, and `positions` as `follow-province`. Those records are keyed by a selected province or its state association, so their source bytes remain unchanged except for the already modelled state-ID field on applicable position rows. The explicit literals make that behavior reviewable and prevent a partial distribution object from silently choosing it.
 
@@ -45,11 +45,11 @@ New states require an explicit name localisation key and a strict `localisation`
 
 `merge_provinces` and `remove_province` accept arbitrary compatible source IDs; removed IDs do not need to be the highest rows in `definition.csv`. Surviving definitions are compacted deterministically to contiguous IDs from zero in old-ID order. Removed source IDs map to the target's compacted ID, including when the target itself moves downward.
 
-The same total old-to-new map is applied atomically to state membership, victory points, province buildings, strategic regions, special-adjacency endpoints and through-provinces, supply nodes, railways, unit positions, and building-position sea references. Source pixels are repainted with the target color; other province colors and pixels remain unchanged. Reference collisions created by the merge are resolved by the declared sum/deduplicate policy. Definition row order, comments and extra fields, text-file comments, line endings, and source encoding are retained by targeted rewrites, and rollback restores every affected file byte-for-byte.
+The same total old-to-new map is applied as one recoverable operation to state membership, victory points, province buildings, strategic regions, special-adjacency endpoints and through-provinces, supply nodes, railways, unit positions, and building-position sea references. Source pixels are repainted with the target color; other province colors and pixels remain unchanged. Reference collisions created by the merge are resolved by the declared sum/deduplicate policy. Definition row order, comments and extra fields, text-file comments, line endings, and source encoding are retained by targeted rewrites. A failed application or post-validation restores every affected file byte-for-byte.
 
 Compaction requires an active definition table that is already contiguous from zero and unambiguous by ID and color. The merge also requires every source and target to share province type plus exact state and strategic-region membership; these are refusal cases rather than guessed redistribution.
 
-Province split/create manifests explicitly retain existing victory points, province buildings, ports, supply nodes, railways, special adjacencies, positions, and entity locators on the source province while the selected pixels and new ID join the declared state and strategic region. To move connected data to the new province, place the corresponding exact remove/add or update operations after the split in the same ordered transaction. Omitting any retention field blocks the split before geometry changes are proposed.
+Province split/create manifests explicitly retain existing victory points, province buildings, ports, supply nodes, railways, special adjacencies, positions, and entity locators on the source province while the selected pixels and new ID join the declared state and strategic region. To move connected data to the new province, place the corresponding exact remove/add or update operations after the split in the same ordered rewrite. Omitting any retention field blocks the split before geometry changes are proposed.
 
 ## Province type migration
 
@@ -66,7 +66,7 @@ The policy explicitly covers:
 - building and unit positions (`retain-if-valid` or `remove`) and entity locators (`retain-at-coordinate`, because type migration does not alter geometry);
 - special adjacency endpoint/through references (`retain-if-valid` or `remove-referencing`).
 
-Land-to-water requires removal from the exact indexed state and cannot leave that state without land. Water-to-land requires an explicit existing target state in the same strategic region. Sea targets require `ocean` terrain and continent `0`; lake targets require `lakes` and continent `0`; land targets require a non-water terrain and nonzero continent. Coastal fields and neighboring coastal changes remain exact manifest inputs and are verified by final map validation. Dependency removals and the definition edit share one hash-bound transaction, so apply and rollback cover every affected state, definition, network, position, and adjacency file together.
+Land-to-water requires removal from the exact indexed state and cannot leave that state without land. Water-to-land requires an explicit existing target state in the same strategic region. Sea targets require `ocean` terrain and continent `0`; lake targets require `lakes` and continent `0`; land targets require a non-water terrain and nonzero continent. Coastal fields and neighboring coastal changes remain exact manifest inputs and are verified by final map validation. Dependency removals and the definition edit share one hash-bound journal, so success or automatic failure restoration covers every affected state, definition, network, position, and adjacency file together.
 
 When a dependency should move rather than disappear, place the corresponding exact `update_state`, position, supply, railway, or adjacency operation after the type migration in the same ordered manifest. The migration policy removes or retains the old record explicitly; the later operation supplies the new target explicitly.
 
@@ -74,16 +74,22 @@ When a dependency should move rather than disappear, place the corresponding exa
 
 Special adjacency rows remain declarative `add_adjacency` and `remove_adjacency` operations against the active `default.map` adjacency CSV. Normal topological adjacency is derived only from four-neighbor province bitmap geometry (including horizontal map wrap) and uses separate `add_normal_adjacency` and `remove_normal_adjacency` operations.
 
-Every normal-adjacency operation carries unique exact pixel transfers with a coordinate, the province currently owning that pixel, and the destination province. Both requested endpoints and all transfer provinces must exist, every source must match the active raster, and every transfer must involve at least one requested endpoint. Agent Nudger repaints only those 24-bit pixels, rebuilds topology, and blocks/rolls back the operation unless the requested pair is present after an add or absent after a remove. Related coastal-definition changes remain explicit ordered operations in the same transaction.
+Every normal-adjacency operation carries unique exact pixel transfers with a coordinate, the province currently owning that pixel, and the destination province. Both requested endpoints and all transfer provinces must exist, every source must match the active raster, and every transfer must involve at least one requested endpoint. Agent Nudger repaints only those 24-bit pixels, rebuilds topology, and restores the operation unless the requested pair is present after an add or absent after a remove. Related coastal-definition changes remain explicit ordered operations in the same rewrite.
 
 ## Allocation
 
 ID/color allocation scans current game, dependencies, and mod sources first, including the definition table selected by each root's own `default.map` even when its filename differs from the active table. It records per-file/root maxima, used ranges, active definition contiguity, collisions, reserved values, selected value/color, and source revision. Explicit values are checked against the same evidence. A lower-root ID/color collision is returned as a named dependency conflict on the manifest operation that requested it. The allocator never assumes the numerically next value is safe.
 
+## Autonomous rewrite
+
+With `writePolicy: "autonomous"`, submit the complete ordered operation manifest once to `hoi4.map_rewrite`. The tool scans dependencies, resolves exact geometry and policies, renders baseline/proposed/diff evidence, validates, journals exact before-bytes, applies all affected text and binary files under the workspace lock, rescans, and post-validates. `execution: "applied"` means the final hashes and validation passed. A blocked proposal reports `execution: "blocked"` and changes nothing; a valid no-change request reports `execution: "unchanged"`; a failure after replacement begins restores every affected file automatically.
+
+No transaction tools are registered in autonomous mode. The optional `"transactions"` compatibility policy exposes `hoi4.map_plan` followed by the separate diff/apply/status/rollback tools, using the same internal journal and recovery engine.
+
 ## Artifacts and validation
 
 Map base layers cover province, state, strategic region, terrain, continent, owner, controller, cores, claims, and coast. Overlays cover coastlines, ports, victory points, resources, state buildings, province buildings, supply nodes, railways, special adjacencies, building positions, unit positions, and weather positions. Resource/building data is present in canonical JSON as exact sorted state/province maps as well as deterministic PNG markers; HTML embeds the same JSON and PNG with pan/zoom controls. Render loops honor cancellation signals.
 
-Every map preflight stores three content-addressed PNG/JSON/HTML triplets: baseline (`map-before.*`), proposed (`map-proposed.*`), and changed-pixel/semantic diff (`map-diff.*`). Their links and content hashes are included in the transaction plan hash. Semantic diff JSON includes definitions, state/region membership, full state values (manpower, category, resources, owner/controller, cores/claims, VPs, state/province buildings, and derived capital), ports, building/unit/weather positions, entity locators, supply, railways, exact special-adjacency records, and exact bitmap-derived normal-adjacency pairs.
+Every map preflight stores three content-addressed PNG/JSON/HTML triplets: baseline (`map-before.*`), proposed (`map-proposed.*`), and changed-pixel/semantic diff (`map-diff.*`). Their links and content hashes are included in the internal plan hash. Semantic diff JSON includes definitions, state/region membership, full state values (manpower, category, resources, owner/controller, cores/claims, VPs, state/province buildings, and derived capital), ports, building/unit/weather positions, entity locators, supply, railways, exact special-adjacency records, and exact bitmap-derived normal-adjacency pairs.
 
 Validation detects duplicate IDs/colors, bitmap-definition mismatches, invalid references, unassigned/multi-state land, invalid derived capitals/VPs/ports/regions/adjacency/supply/rail/placements, removed references, coast inconsistencies, duplicate state IDs, missing localisation, ownership/control conflicts, lost payload, changes outside declared bounds, and dependency conflicts. Geometry review includes disconnected components, one-pixel corridors, and enclosed province holes. Hole detection uses one bounded digital-topology pass and reports `MAP_PROVINCE_HOLE_REVIEW` as a warning because intentional enclaves can be valid; provinces crossing the horizontally wrapping seam are excluded from planar hole classification. Baseline comparisons diagnose dimensions, file/DIB header, row orientation, pixel offset, bit depth, and palette changes separately. Sea and legitimate lake/island cases are not misclassified as missing state membership.

package/docs/performance.md

@@ -75,7 +75,7 @@ The benchmark changes only the copied fixture's modification time and confirms t
 - metadata-only rescan/cache hit: 5.431 ms;
 - same-size, same-mtime content change/rescan: 20.300 ms.
 
-The deterministic unit test in `tests/unit/core-cache.test.ts` continuously checks this correctness property without asserting timing. Explicit transaction apply/rollback paths also invalidate the workspace cache; the content-derived revision remains the safety backstop for external edits.
+The deterministic unit test in `tests/unit/core-cache.test.ts` continuously checks this correctness property without asserting timing. Autonomous rewrites and reviewed transaction apply/rollback paths all invalidate the workspace cache; the content-derived revision remains the safety backstop for external edits.
 
 The Scripted GUI Studio and Agent Nudger benchmark paths currently rebuild their domain scans/indexes on each call. Their warm figures therefore reflect runtime/JIT and operating-system cache effects rather than a domain-level memoization claim. Stored artifacts are content-addressed, but artifact storage is not treated as a parsed-source cache.
 

package/docs/release.md

@@ -59,7 +59,7 @@ stable package is published, the normal strict stable-version monotonic and exac
 ## Immutable fix-forward history
 
 Stable tags and public package versions are never moved, deleted, or overwritten after a failed
-release attempt. The retained history before `0.1.6` is:
+release attempt. The retained history is:
 
 - `v0.1.0` stopped during prepublication validation, before any public writer ran;
 - `v0.1.1` stopped before npm accepted bytes because npm interpreted a slash-containing relative
@@ -85,12 +85,17 @@ release attempt. The retained history before `0.1.6` is:
   cross-surface verifier rejected the Registry's omission of explicit `isSecret: false`, although
   the pinned official schema defines false as that field's default and every public object passed
   its preceding publication gate. All public objects remain unchanged as audit evidence.
-
-`0.1.6` omits the redundant false default from checked-in Registry metadata so the strict verifier
-can continue comparing the complete published server record without normalization. The normal
-stable-version monotonic gate treats the public `0.1.5` package as immutable history and permits
-only a strictly newer version. Rerunning or fixing a release never authorizes rewriting a tag,
-package version, image tag, release asset, or Registry version.
+- `v0.1.6` completed the ordered workflow and independent verification across npm, GHCR, the
+  immutable GitHub Release, and the official MCP Registry.
+- `v0.1.7` completed the same ordered workflow with agent-first persistent setup guidance, large
+  focus-tree review scaling, symbolic focus-cost preservation, and complete resource-backed focus
+  validation. Its exact public evidence is retained in
+  [the 0.1.7 completion report](completion-report.md).
+
+`0.2.0` is the current strictly monotonic release candidate. The normal stable-version gate treats
+public `0.1.7` as immutable history; only a strictly newer version may be published. Rerunning or fixing a
+release never authorizes rewriting a tag, package version, image tag, release asset, or Registry
+version.
 
 ## Required pre-tag immutability check
 

package/docs/research/mcp-2026-07-10.md

@@ -1,6 +1,6 @@
 # MCP protocol, SDK, security, and Registry review
 
-Verified 2026-07-10 against official sources.
+Verified again on 2026-07-12 against official sources.
 
 ## Selected production baseline
 
@@ -17,10 +17,16 @@ The breaking `2026-07-28` protocol and SDK v2 split packages were release candid
 - Stdio uses newline-delimited UTF-8 JSON-RPC, protocol-only stdout, and stderr logging.
 - Streamable HTTP uses one `/mcp` POST/GET endpoint plus DELETE for session termination. It is stateful to support progress, cancellation, server notifications, SSE resumption, and secure random sessions.
 - Sessions are bound to authenticated principals and expire; they are never authentication credentials.
-- Tools use strict schemas and explicit read-only/destructive/idempotent/open-world annotations. Hints do not replace enforcement.
+- Tools use strict schemas and explicit read-only/destructive/idempotent/open-world annotations. Hints do not replace enforcement and do not require a client to show a confirmation prompt for each call.
 - Long work observes `AbortSignal` and sends monotonic progress only when the client supplies a progress token.
 - Large results are content-addressed resources. Binary reads are bounded/chunkable because resource links defer retrieval but are not a byte-stream transport.
-- Prompts describe safe workflows but grant no permission.
+- Prompts describe domain workflows but grant no permission.
+
+### Write-policy conclusion
+
+MCP separates server-advertised tool metadata from client-host policy. A server can truthfully mark a source-changing tool with `readOnlyHint: false` and `destructiveHint: true`, but it cannot require, suppress, or bypass a host confirmation dialog. The host decides how to present or constrain the call; the server independently enforces its configured workspace, authentication, scope, validation, journaling, and recovery boundaries.
+
+For this server, `writePolicy: "autonomous"` therefore exposes one-call `hoi4.focus_rewrite`, `hoi4.gui_rewrite`, and `hoi4.map_rewrite` tools with destructive annotations. The tools internally plan, validate, journal, apply, and post-validate, restoring original bytes on failure. Transaction tools are not registered in that mode. `writePolicy: "transactions"` remains an optional compatibility surface for the older client-driven review/apply sequence, while `read-only` remains the default.
 
 ## Remote security requirements applied
 

package/docs/security.md

@@ -4,13 +4,13 @@
 
 - external mod source and binary map data;
 - installed game and dependency references;
-- transaction approval intent and rollback blobs;
+- configured write authority, authenticated journals, and exact recovery blobs;
 - generated artifacts that may reveal source details;
 - HTTP credentials and principal/workspace grants.
 
 ## Trust boundaries
 
-MCP input, file paths, manifest content, client annotations, session IDs, Origin/Host headers, and remote access tokens are untrusted. Tool annotations are descriptive hints. Prompts are guidance. Server-side policy is authoritative.
+MCP input, file paths, manifest content, client annotations, session IDs, Origin/Host headers, and remote access tokens are untrusted. Tool annotations are descriptive hints. Prompts are guidance. MCP does not require a confirmation prompt for every destructive tool call. Server-side configuration is authoritative for server access, while the MCP host independently controls its own approval and filesystem policy; neither can override the other.
 
 ## Filesystem controls
 
@@ -19,7 +19,7 @@ MCP input, file paths, manifest content, client annotations, session IDs, Origin
 - Traversal, absolute paths, UNC/device paths, NULs, alternate data streams, ambiguous trailing characters, and device names are rejected.
 - Existing symlinks and junctions are resolved; an escape outside the root is rejected.
 - Artifact shards, transaction journals, blobs, and lock descendants are re-canonicalized before access. A symlink or junction observed in artifact/journal enumeration is rejected.
-- Transaction mode requires an absolute `serverStateRoot` whose existing components are non-linked
+- Each write-enabled policy requires an absolute `serverStateRoot` whose existing components are non-linked
   and whose canonical target does not overlap any source, registration capability,
   generated-storage root, or runtime-nominated root. Harmless native path-spelling aliases are
   normalized only after the link check. Its random journal key and protected revision heads are
@@ -40,7 +40,13 @@ concurrent mutation.
 
 ## Write controls
 
-Read-only is the default. A write requires global and workspace enablement, a validated dry run, a persisted transaction, exact plan hash, separate apply call, unexpired principal/workspace binding, unchanged source hashes, and a workspace lock. There is no command execution field. Stale apply and rollback operations fail closed.
+Read-only is the default. The recommended `"autonomous"` policy exposes only `hoi4.focus_rewrite`, `hoi4.gui_rewrite`, and `hoi4.map_rewrite` for source mutation. Each call computes the complete affected-file set, validates proposed bytes, persists an authenticated journal and exact before-bytes, rechecks the unexpired principal/workspace binding and source hashes under a workspace lock, applies, rebuilds the index, and post-validates. Invalid proposals do not apply; an application, final-hash, or post-validation failure restores original bytes automatically.
+
+The optional `"transactions"` compatibility policy exposes the older plan/diff/apply/status/rollback tool sequence. It uses the same core journal and failure-recovery path. Autonomous mode intentionally does not register the transaction tools, so it has no client-callable bypass around the one-call rewrite contract.
+
+The autonomous rewrite tools advertise `destructiveHint: true` because a successful call changes mod source. That hint is truthful risk metadata, not a server request to suppress or force a dialog. A client host may prompt for or block the call; the server cannot override it. There is no command-execution field in either mode, and stale or cross-workspace writes fail closed.
+
+Git remains the project-history and intentional-revert layer. It is not required for operational recovery: the journal and exact before-bytes prevent a failed multi-file rewrite from remaining partially applied.
 
 Runtime registration definitions and raw paths are not persisted. The canonical artifact root does
 retain an atomically created ownership claim containing only domain-separated SHA-256 workspace and
@@ -63,7 +69,7 @@ valid manifest. A cache-first crash may reconcile only an authenticated exact ne
 missing head, revision gap, altered expiry/state/failure/rollback field, or recomputed public hash
 fails closed. No HMAC key is derived from public workspace data.
 
-Read-only transaction operations never repair protected state. Cache-first successor promotion is
+Read-only journal/resource operations never repair protected state. Cache-first successor promotion is
 confined to startup recovery and authorized write paths. Artifact manifests are capped at 1 MiB and
 transaction manifests at 16 MiB before parsing; transaction resource ranges use a bounded verified
 byte cache instead of repeatedly rebuilding the authenticated object.
@@ -129,7 +135,7 @@ root ACL for the dedicated server account; the server still rejects a linked/non
 inherits that operator ACL. A hostile operating-system principal that can read the key or replace
 state-root entries remains outside the documented filesystem trust boundary.
 
-Raw installed-game or dependency sprite, font, and bitmap files are never registered as downloadable resources. Structured JSON evidence strips embedded raster and glyph payloads, retaining only source-linked hashes, paths, frame and dimension metadata. Composite SVG/PNG reviews may contain processed frames or glyphs required to inspect the requested render, but remain generated, authorization-checked workspace evidence rather than raw asset-file resources. Transaction evidence may contain authorized mod-source before/proposed text and diffs; every artifact remains bound to the workspace principal.
+Raw installed-game or dependency sprite, font, and bitmap files are never registered as downloadable resources. Structured JSON evidence strips embedded raster and glyph payloads, retaining only source-linked hashes, paths, frame and dimension metadata. Composite SVG/PNG reviews may contain processed frames or glyphs required to inspect the requested render, but remain generated, authorization-checked workspace evidence rather than raw asset-file resources. Rewrite and reviewed-transaction evidence may contain authorized mod-source before/proposed text and diffs; every artifact remains bound to the workspace principal.
 
 The runtime sends no telemetry or analytics. Its only outbound network request is OAuth JWT-key retrieval from the administrator-configured JWKS endpoint; stdio and static-token loopback deployments require no runtime network access.
 

package/docs/self-hosting.md

@@ -51,7 +51,9 @@ Public mode—either a non-loopback listener or a non-loopback `publicUrl` in fr
 }
 ```
 
-The server is an OAuth resource server, not an authorization server. Protected Resource Metadata is served at the standard well-known paths and its endpoint-specific URL is included in 401 and insufficient-scope 403 challenges. Baseline access uses the configured `requiredScopes`; transaction planning, registration, apply, and rollback additionally require `hoi4:write`. Each MCP session is bound to the exact bearer credential that initialized it, not only to mutable subject/client claims. A refreshed or step-up token must initialize a new MCP session; the previous session remains bound to its original credential and expires no later than that credential's `exp`. The server retains only a SHA-256 credential identifier, never the raw token. Static-token sessions keep the configured sliding inactivity lifetime. Terminate TLS at a trusted reverse proxy, preserve Authorization/Origin/Host headers, and do not make a session ID a bearer credential.
+The server is an OAuth resource server, not an authorization server. Protected Resource Metadata is served at the standard well-known paths and its endpoint-specific URL is included in 401 and insufficient-scope 403 challenges. Baseline access uses the configured `requiredScopes`; runtime registration and every source-mutation tool additionally require `hoi4:write`. In autonomous mode that means `hoi4.focus_rewrite`, `hoi4.gui_rewrite`, and `hoi4.map_rewrite`; in compatibility mode it includes planning, apply, and rollback. Each MCP session is bound to the exact bearer credential that initialized it, not only to mutable subject/client claims. A refreshed or step-up token must initialize a new MCP session; the previous session remains bound to its original credential and expires no later than that credential's `exp`. The server retains only a SHA-256 credential identifier, never the raw token. Static-token sessions keep the configured sliding inactivity lifetime. Terminate TLS at a trusted reverse proxy, preserve Authorization/Origin/Host headers, and do not make a session ID a bearer credential.
+
+`hoi4:write` authorizes the server-side capability; it does not dictate the MCP host's user-interaction policy. Autonomous rewrite tools advertise `destructiveHint: true`, but MCP does not require a prompt for every such call. The server cannot override a host that prompts for or blocks it.
 
 ### Reverse-proxy boundary
 
@@ -110,7 +112,7 @@ releases the ordinary request-concurrency slot. Each session retains at most 1,0
 `sessionTtlSeconds`. Old per-session history is evicted first. A new event that cannot fit the
 shared budget is not retained for replay and does not evict another session's history.
 
-Principal grants isolate tool, resource, session, and transaction access within one deployment. Run separate least-privilege server instances or containers for mutually distrustful teams or operating-system trust domains; do not treat application-level grants as an OS sandbox.
+Principal grants isolate tool, resource, session, and journal access within one deployment. Run separate least-privilege server instances or containers for mutually distrustful teams or operating-system trust domains; do not treat application-level grants as an OS sandbox.
 
 Runtime registration has two operator capabilities. `registrationRoots` permits read-only source
 selection. A caller-declared mod root additionally must be under the default-empty
@@ -121,14 +123,14 @@ these capability roots to that principal; prefer static registrations or separat
 mutually distrustful users.
 
 Runtime artifact storage must support same-volume hard links so the server can create persistent
-owner claims without replacement races. Transaction deployments additionally require an isolated,
+owner claims without replacement races. Every write-enabled deployment additionally requires an isolated,
 persistent `serverStateRoot` on a filesystem with hard-link and atomic-replacement support. Do not
 place it beneath any source, capability, artifact, cache, fixture, or `storageRoots` directory.
 
 ## Container
 
 ```bash
-docker build -t hoi4-agent-tools:0.1.6 .
+docker build -t hoi4-agent-tools:0.2.0 .
 docker run --read-only --rm -p 127.0.0.1:3210:3210 \
   -e HOI4_AGENT_CONFIG=/config/config.json \
   -v /srv/hoi4/config:/config:ro \
@@ -136,7 +138,7 @@ docker run --read-only --rm -p 127.0.0.1:3210:3210 \
   -v /srv/hoi4/workspaces:/srv/hoi4/workspaces \
   -v /var/lib/hoi4-agent-tools:/var/lib/hoi4-agent-tools \
   -v /var/lib/hoi4-agent-tools-state:/var/lib/hoi4-agent-tools-state \
-  hoi4-agent-tools:0.1.6
+  hoi4-agent-tools:0.2.0
 ```
 
 Port publishing reaches the container through a non-loopback interface. The mounted configuration
@@ -146,7 +148,7 @@ Terminate TLS at the configured reverse proxy. Mapping the host port only to `12
 exposure but does not turn the container-side listener into loopback, so it does not permit static
 bearer tokens.
 
-When writes are enabled, set `serverStateRoot` to `/var/lib/hoi4-agent-tools-state` in this example.
+When writes are enabled in either autonomous or reviewed mode, set `serverStateRoot` to `/var/lib/hoi4-agent-tools-state` in this example.
 Keep that mount persistent across restarts and protect it for the dedicated server account. It is a
 separate mount because a state root may not overlap `/var/lib/hoi4-agent-tools` when that path is a
 configured generated-storage capability.

package/docs/transactions.md

@@ -1,38 +1,55 @@
-# Transactions, diffs, and rollback
+# Autonomous rewrites, transactions, and recovery
 
-## Plan
+The recommended `"autonomous"` write policy exposes three source-mutation tools:
 
-A domain `plan_changes`/`map_plan` call calculates every affected source and binary file before writing. Proposed bytes are validated in memory. The plan persists content-addressed before/after blobs and produces source, binary, pixel, and rendered comparison artifacts where applicable.
+- `hoi4.focus_rewrite`;
+- `hoi4.gui_rewrite`;
+- `hoi4.map_rewrite`.
 
-Every proposed source target is resolved with write access restricted to the workspace's canonical
-mod root. Transaction calls cannot write the game, a dependency, a fixture, artifact storage,
-cache storage, or the reserved `.hoi4-agent` subtree as mod source.
+One rewrite call calculates every affected source and binary file, validates the proposed bytes in memory, persists an authenticated journal with exact recovery data, applies under the workspace lock, rebuilds the shared index, and post-validates the result. The caller does not receive or invoke separate transaction apply or rollback tools. Those tools are not registered in autonomous mode.
 
-The transaction API requires both validation phases: planning must return at least one explicit in-memory check, and apply must return at least one explicit post-write check. Missing or empty callbacks fail with `TRANSACTION_DRY_RUN_VALIDATION_REQUIRED` or `TRANSACTION_POST_VALIDATION_REQUIRED`; callers cannot opt out through the typed core API. Diff artifacts are committed as one batch with the journal only after the planning validator returns structurally valid results. A rejected validator or journal admission leaves artifact inventory unchanged. A completed dry run whose explicit checks fail remains reviewable as a blocked plan and cannot be applied.
+`"transactions"` remains available as an optional compatibility policy. It exposes the older `hoi4.focus_plan_changes`, `hoi4.gui_plan_changes`, and `hoi4.map_plan` tools, followed by `hoi4.transaction_diff`, `hoi4.transaction_apply`, `hoi4.transaction_status`, and `hoi4.transaction_rollback`. Both modes use the same core transaction engine and safety properties; only the public MCP workflow differs.
+
+## Autonomous rewrite pipeline
+
+Every autonomous rewrite follows this sequence inside one MCP call:
+
+1. resolve targets with write access confined to the canonical mod root;
+2. calculate the complete affected-file set and exact proposed bytes;
+3. run domain-specific in-memory validation and create source, binary, pixel, or rendered evidence as applicable;
+4. persist the plan, before/after blobs, authentication tag, and protected revision head;
+5. recheck principal, workspace, canonical roots, expiry, and every before-hash under the workspace lock;
+6. stage and replace files in deterministic order;
+7. rebuild the shared index, run domain post-write validation, and verify every final hash;
+8. return `execution: "applied"`, changed-file samples, validation, and evidence links only after success.
+
+A proposal whose pre-write checks fail returns blocked with `execution: "blocked"` and changes no source bytes. A request whose desired bytes already match every target returns `execution: "unchanged"` as a successful no-op. Any error after replacement begins starts exact restoration before failure is returned. Startup recovery also completes restoration for an interrupted journal before another write is accepted. Autonomous mode therefore removes the client-driven review/apply handshake without weakening validation or recoverability.
+
+The rewrite tools truthfully advertise `readOnlyHint: false` and `destructiveHint: true`. MCP does not mandate a confirmation prompt for each tool call. A coding-agent host can still prompt for or block the call under its own policy, and the server cannot override that host decision.
+
+Git remains the recommended source-history, collaboration, and intentional-revert system. Internal recovery serves a different purpose: exact before-bytes and the durable journal prevent a failed multi-file rewrite from leaving partial corruption, including outside a Git checkout.
+
+Successful autonomous journals are internal recovery data, not user history. They are reclaimed automatically when journal retention reaches its configured count or byte limit; authenticated source-linked evidence remains in the artifact store. Reviewed compatibility mode retains applied journals so its explicit rollback operation remains available.
+
+## Planning and evidence
+
+Proposed bytes are validated in memory before any source replacement. Every target is restricted to the workspace's canonical mod root; rewrites cannot write the game, a dependency, a fixture, artifact storage, cache storage, or the reserved `.hoi4-agent` subtree as mod source.
+
+The transaction core requires both validation phases: planning must return at least one explicit in-memory check, and apply must return at least one explicit post-write check. Missing or empty callbacks fail with `TRANSACTION_DRY_RUN_VALIDATION_REQUIRED` or `TRANSACTION_POST_VALIDATION_REQUIRED`; domain adapters cannot opt out. Diff artifacts are committed as one batch with the journal only after the planning validator returns structurally valid results. A rejected validator or journal admission leaves artifact inventory unchanged. A completed plan whose explicit checks fail remains evidence for the blocked rewrite and cannot be applied.
 
 Text diffs use an exact deterministic algorithm with a fixed memory bound and cancellation checks. If an exact diff would exceed the bound, planning stops with `DIFF_COMPLEXITY_LIMIT`; the server does not substitute a truncated, approximate, or misleading diff.
 
-The returned transaction ID is not approval. Review:
+Autonomous rewrite results keep bounded path samples and return the generated evidence resources directly; internal transaction identifiers and plan hashes are not caller inputs or success-result fields. Every applied autonomous rewrite links a sanitized execution-validation JSON resource containing the complete pre-write and post-write checks, source-linked diagnostics, final target hashes, and any overflow diagnostic resources without exposing the internal transaction ID or plan hash. Inline validation remains capped at five checks for wire efficiency. Reviewed compatibility mode additionally exposes the authenticated transaction-manifest resource.
 
-- operations and unresolved choices;
-- affected file list;
-- source and visual diff resources;
-- diagnostic locations and validation gates;
-- expiry and plan hash.
+In reviewed compatibility mode, `hoi4.transaction_diff` returns at most 20 files, operation summaries, and artifact links per page. Follow every `nextCursor` until absent before applying. Cursors are bound to the immutable plan hash and fail if reused for a different transaction. A transaction ID is a journal identifier, not approval.
 
-Plan and mutation tool results keep only a bounded path sample plus the authenticated transaction
-manifest resource. Review artifacts remain listed in that manifest rather than being duplicated as
-hundreds of inline resource links. `hoi4.transaction_diff` returns at most 20 files, operation
-summaries, and artifact links per page; follow every `nextCursor` until it is absent. Cursors are
-bound to the immutable plan hash and fail if reused for a different transaction. Inline validation
-contains at most five checks with an explicit truncation diagnostic; the manifest is the complete
-validation record.
+Focus rewrites include both the edited Clausewitz source and its adjacent `.focus-plan.json` design sidecar in one recoverable operation. The manifest retains the proposed generated-source map and sidecar artifacts after success or restoration so each generated focus range remains traceable to its planning/source node.
 
-Focus plans include both the edited Clausewitz source and its adjacent `.focus-plan.json` design sidecar in one transaction. The manifest also retains the proposed generated-source map and sidecar artifacts through apply and rollback so each generated focus range remains traceable to its planning/source node.
+Complete focus proposal validation is a linked JSON resource. If proposed or post-write diagnostics exceed the fixed manifest allowance, validation still evaluates the complete set, stores it as a source-linked MCP resource, and retains a blocker-first bounded manifest summary. The plan phase reserves diagnostic capacity for the independent post-write phase, so a warning-heavy large tree does not weaken limits or prevent a valid rewrite.
 
-## Apply
+## Apply pipeline and protected state
 
-Call `hoi4.transaction_apply` separately with `workspaceId`, `transactionId`, and the exact 64-character `expectedPlanHash`. The server rejects a different principal/workspace, changed roots, failed dry run, expiry, reused state, or any changed before-hash.
+Autonomous tools pass their internal transaction ID and exact 64-character plan hash directly to the core apply path. In compatibility mode, the caller supplies the same values to `hoi4.transaction_apply`. The server rejects a different principal/workspace, changed roots, failed pre-write validation, expiry, reused state, or any changed before-hash.
 
 The persisted immutable plan payload is recomputed against `planHash` whenever a manifest is
 loaded. A recomputable integrity hash remains useful for deterministic diagnostics, but is never an
@@ -49,8 +66,7 @@ reconcile only an HMAC-valid exact `+1` successor. Missing heads, gaps, conflict
 and forged successors fail closed. Successor creation is durable before older revision-head files
 are removed, so an old-head cleanup failure does not break loading.
 
-Ordinary status, diff, and resource reads are pure: they accept only an exact protected head and
-never promote state. An authenticated cache-first exact successor reports
+Ordinary manifest-resource reads, and status/diff reads when compatibility mode exposes them, are pure: they accept only an exact protected head and never promote state. An authenticated cache-first exact successor reports
 `TRANSACTION_HEAD_RECONCILIATION_REQUIRED` until startup recovery or an authorized write path
 performs the narrowly allowed reconciliation.
 
@@ -135,9 +151,11 @@ check rejects a plan, the artifact store removes only content and provenance fil
 attempt; artifact inventory is unchanged and any identical artifact retained by another operation
 remains addressable.
 
-## Explicit rollback
+## Explicit rollback in compatibility mode
+
+`hoi4.transaction_rollback` is available only in reviewed `"transactions"` mode after successful apply. It first verifies that every current file still has the transaction's after-hash. An external edit makes rollback stale, protecting later work from being overwritten.
 
-`hoi4.transaction_rollback` is available after successful apply. It first verifies that every current file still has the transaction's after-hash. An external edit makes rollback stale, protecting later work from being overwritten.
+Autonomous mode does not expose an explicit rollback tool. Failed application and post-validation restore automatically; an intentional later reversal belongs in Git or a new explicit domain rewrite.
 
 Rollback accepts cancellation through its path/hash verification preflight. Once byte restoration
 starts, restore plus authenticated journal advancement is deliberately non-cancellable so a client

package/docs/troubleshooting.md

@@ -8,18 +8,26 @@ Set `HOI4_AGENT_CONFIG` to an absolute path or add `--config PATH` to the server
 
 Use a registered workspace-relative path. Confirm the canonical root is beneath `registrationRoots`; runtime mods also require the separate `writableRegistrationRoots` capability. Check for junctions/symlinks, parent segments, device names, trailing dots/spaces, or alternate data streams. Game and dependencies are intentionally read-only.
 
-## Apply reports stale
+## Rewrite reports stale
 
-The source changed after planning. Do not reuse the transaction. Scan and produce a new dry run so review evidence matches current files.
+The source changed after planning or before the workspace lock completed its recheck. Scan again and submit a new rewrite so evidence matches current files. In reviewed compatibility mode, do not reuse the stale transaction.
+
+## Rewrite or transaction tools are missing
+
+Check `writePolicy` in `hoi4.project_status`. `"read-only"` authorizes no source mutation, even if compatibility-named planning or transaction tools are listed by the client. `"autonomous"` exposes `hoi4.focus_rewrite`, `hoi4.gui_rewrite`, and `hoi4.map_rewrite` and intentionally hides all transaction tools. `"transactions"` enables the older plan/diff/apply/status/rollback surface instead. Restart the server and initialize a new MCP session after changing configuration.
 
 ## Transaction state rejected
 
-Transaction mode requires an absolute, persistent `serverStateRoot` that does not overlap any
-source or generated-storage capability. Run setup with `--enable-writes --server-state ROOT`, then
+Each write-enabled policy requires an absolute, persistent `serverStateRoot` that does not overlap any
+source or generated-storage capability. Run setup with `--autonomous-writes --server-state ROOT` for autonomous rewrites, or `--reviewed-writes --server-state ROOT` for compatibility mode, then
 run `--diagnose`. Preserve the same private state root across restarts. A missing key, malformed or
 replayed head, unauthenticated legacy manifest, or cache/head revision conflict fails closed; review
 and archive the affected journal/state evidence instead of regenerating a public hash or tag.
 
+## The MCP host still asks for approval
+
+The autonomous rewrite tools advertise `destructiveHint: true`. MCP does not require or forbid a prompt; the coding-agent host controls its own approval and filesystem policy, and the server cannot override it. Change the host policy only if that matches your local security requirements.
+
 ## Runtime registration conflicts after restart
 
 The artifact root already has a hash-only runtime owner claim. Register the exact canonical

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "hoi4-agent-tools",
   "mcpName": "io.github.klimPaskov/hoi4-agent-tools",
-  "version": "0.1.6",
-  "description": "Source-preserving HOI4 workbench exposed as a safe Model Context Protocol server for coding agents",
+  "version": "0.2.0",
+  "description": "Source-preserving HOI4 workbench with workspace-authorized autonomous rewrites for coding agents",
   "type": "module",
   "license": "Apache-2.0",
   "author": "HOI4 Agent Tools contributors",
@@ -18,7 +18,11 @@
     "hearts-of-iron-iv",
     "hoi4",
     "modding",
-    "coding-agents"
+    "coding-agents",
+    "clausewitz",
+    "focus-trees",
+    "scripted-gui",
+    "hoi4-map"
   ],
   "engines": {
     "node": "^22.0.0 || ^24.0.0"

package/schemas/configuration.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v0.1.6/schemas/configuration.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v0.2.0/schemas/configuration.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {
@@ -69,7 +69,8 @@
       "type": "string",
       "enum": [
         "read-only",
-        "transactions"
+        "transactions",
+        "autonomous"
       ]
     },
     "__schema2": {

package/schemas/continuous-focus-palette.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v0.1.6/schemas/continuous-focus-palette.schema.json",
+  "$id": "https://github.com/klimPaskov/hoi4-agent-tools/blob/v0.2.0/schemas/continuous-focus-palette.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {