hoi4-agent-tools 0.1.6 → 0.2.0

package/docs/completion-report.md

@@ -1,92 +1,122 @@
-# Completion report: 0.1.6 release candidate
+# Completion report: 0.1.7 public release
 
-- Candidate version: `0.1.6`
-- Report date: 2026-07-11
-- Status: fix-forward implementation in qualification; public delivery incomplete
+> 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 candidate 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 candidate has passed all 46 portable test files: 495 tests passed and one POSIX case was intentionally skipped on Windows. The latest 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.
-
-No end-to-end workflow-complete multi-surface public release is claimed in this report. The
-following evidence remains pending until the `0.1.6` fix-forward workflow finishes:
-
-| Surface        | Required completion evidence                                                                              | Status       |
-| -------------- | --------------------------------------------------------------------------------------------------------- | ------------ |
-| GitHub source  | Public canonical repository containing the tested commit and immutable `v0.1.6` tag                       | Pending      |
-| npm            | Public `hoi4-agent-tools@0.1.6` with exact tarball integrity and SLSA provenance                          | `0.1.5` only |
-| GitHub release | Immutable `v0.1.6` release containing the exact npm and container digest manifests                        | `0.1.5` only |
-| GHCR           | Public anonymous `0.1.6` digest with two runtime platforms and source-bound SBOM/provenance subjects      | `0.1.5` only |
-| MCP Registry   | Exact `io.github.klimPaskov/hoi4-agent-tools@0.1.6` metadata with official `active` and `isLatest` status | `0.1.5` only |
-| Public install | Clean registry installation, signature audit, MCP initialization, and tool discovery                      | Pending      |
-
-## First-release completion sequence
-
-1. Commit the tested candidate on `main` and push it to the canonical public repository.
-2. Run the manual GHCR bootstrap workflow, make the new package public in GitHub, and verify the bootstrap index without saved credentials.
-3. Create `npm-bootstrap-v0.0.0-bootstrap.1`, store a shortest-lived npm granular token only as `NPM_BOOTSTRAP_TOKEN`, and run the manual non-OIDC npm bootstrap workflow from that tag. The earlier immutable `.0` attempt stopped before publication; it is retained as audit evidence rather than rewritten.
-4. Revoke and delete `NPM_BOOTSTRAP_TOKEN`, then configure npm trusted publishing for `klimPaskov/hoi4-agent-tools`, `release.yml`, and the explicit `npm publish` allowed action.
-5. Preserve `v0.1.0` through `v0.1.4` as documented above, plus the immutable complete `v0.1.5` public objects whose final verifier stopped on schema-default serialization. Do not create `NPM_TOKEN`; the OIDC workflow rejects it.
-6. Qualify the synchronized `0.1.6` fix-forward commit with canonical default omission and unchanged strict Registry equality, then create `v0.1.6` only from an exact green commit.
-7. Allow the release workflow to publish and verify npm, digest-immutable GHCR, the immutable GitHub release, and MCP Registry in its enforced order.
-8. Update this report with the commit, workflow run, public URLs, npm and image digests, and Registry status. Only then is public delivery complete.
-
-Detailed commands and failure behavior are documented in [Release and MCP Registry publication](release.md).
+| Surface        | Verified public evidence                                                                                                                               | Status   |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- |
+| GitHub source  | Public repository, annotated tag object `d06a18d...`, peeled commit `97183886...`, and green exact-source CI                                           | Verified |
+| npm            | `hoi4-agent-tools@0.1.7`, Registry signature, npm publish attestation, and SLSA provenance v1                                                          | Verified |
+| GitHub Release | Immutable [Release v0.1.7](https://github.com/klimPaskov/hoi4-agent-tools/releases/tag/v0.1.7), ID `352694363`, with exactly four byte-verified assets | Verified |
+| GHCR           | Anonymous `ghcr.io/klimpaskov/hoi4-agent-tools:0.1.7` OCI index with exact amd64/arm64 runtimes and attached attestations                              | Verified |
+| MCP Registry   | Exact `io.github.klimPaskov/hoi4-agent-tools@0.1.7` record with official `active` and `isLatest: true` state                                           | Verified |
+| Public install | Clean install, signature/attestation audit, stdio discovery, and authenticated Streamable HTTP qualification                                           | Verified |
+
+### npm and provenance
+
+- Published at `2026-07-12T07:09:58.926Z`; `latest` resolves to `0.1.7`.
+- Tarball: `688,684` bytes at `https://registry.npmjs.org/hoi4-agent-tools/-/hoi4-agent-tools-0.1.7.tgz`.
+- SHA-1: `6c34d998f664b846de4a9b60a6dbadd39898a6cc`.
+- SHA-256: `e0c08ca4db2347dfadc767eea230d4c24071b6f54b1927c7e2a9aa2eec524b0e`.
+- SRI: `sha512-PmCgPyh/qA5dj6jgCpMKsKqFcQCVk0PdMa2PwATfcJ4EETbKgknJEKuaxHLb+UoPaFiDkHSQEJu2fF/UV8EGfQ==`.
+- The npm and GitHub Release tarballs are byte-identical. The npm publish attestation is recorded at Rekor log index `2148574615`; SLSA provenance v1 is recorded at index `2148573874` and binds `release.yml`, `refs/tags/v0.1.7`, release commit `9718388626a29dc4b584ae235bdbe325689e44b0`, and release run `29183455724`.
+
+### Immutable GitHub Release
+
+The GitHub Actions bot published Release ID `352694363` at `2026-07-12T07:15:14Z`. It is neither a draft nor a prerelease and reports `immutable: true`.
+
+| Asset                        |   Bytes | SHA-256                                                            |
+| ---------------------------- | ------: | ------------------------------------------------------------------ |
+| `container-image.json`       |     361 | `06695fa817a1ac9bc2fbb94840c817732875fec0988fe6caa23d46fec75983cb` |
+| `hoi4-agent-tools-0.1.7.tgz` | 688,684 | `e0c08ca4db2347dfadc767eea230d4c24071b6f54b1927c7e2a9aa2eec524b0e` |
+| `npm-pack.json`              |  50,050 | `9417225028ae5f516c5f727785eedf8764842d96e98a9674caab0c671dea3312` |
+| `release-identity.json`      |     431 | `49318a7d830e410520e61c6d7f9e67af2be8f072ecde50645f2d19cb962c5a79` |
+
+### GHCR image and attestations
+
+- OCI index: `sha256:b9651c3647d6f0efe563f82a7973ab4dcde7165546507a7fe6e4e429b0c31f0c`.
+- `linux/amd64`: `sha256:c4927b19b736ced1e528694e8f53bffd8f28066463ab806eacce1ee064715741`.
+- `linux/arm64`: `sha256:372c9ac76ced1cd7afb03e985cbb17855f9e44500257ca816c5f376ad233db7b`.
+- The index exposes exactly two runtime manifests and one attached attestation manifest per runtime. The checked-in release workflow verifies SPDX SBOM and SLSA statements, anonymous access, exact source identity, non-root execution, read-only container behavior, and both supported architectures.
+
+### MCP Registry and public installation
+
+The official Registry returned `io.github.klimPaskov/hoi4-agent-tools@0.1.7` with `status: active` and `isLatest: true`. `publishedAt`, `updatedAt`, and `statusChangedAt` are all `2026-07-12T07:15:29.426439Z`.
+
+A fresh independent public install fetched 132 packages. Its signature audit verified 131 installed-package signatures and 17 attestations with no invalid or missing records. Installed stdio and authenticated, Origin-validated Streamable HTTP initialization/discovery and protocol workflows passed.
+
+## Real large-focus transaction proof
+
+The published `0.1.7` stdio server was exercised against a 238-focus external mod workspace without copying that workspace into this repository or package.
+
+- Baseline import preserved all 238 focus IDs and symbolic costs and reported 15 avoidable connector crossings.
+- The structured plan used 14 branch groups, 12 ordered lanes, 16 fixed anchors, and 222 automatically placed nodes.
+- The proposed layout has 238 unique coordinates, zero parent-order violations, zero connector-crossing findings, and zero errors or blockers.
+- Source and semantic projections are byte-identical after normalising only focus `x`/`y` and `continuous_focus_position`; prerequisites, exclusions, rewards, triggers, comments, unknown fields, raw blocks, ordering, encoding, and symbolic costs are preserved.
+- The dry run emitted one complete transaction-diff page with 14 artifacts. A second fresh dry run reproduced every non-manifest artifact byte-for-byte.
+- A public-package apply passed all eight validation checks. Explicit rollback restored the exact baseline source hash and removed the newly created planning sidecar. A fresh transaction was then applied and retained.
+- Final scan/lint/render recovered all planning metadata and reproduced the reviewed 6317 by 1997 PNG exactly at `reviewScale: 0.4`.
+- Complete proposed and post-write diagnostic resources retained 116 content-specific repeated-reward warnings with zero hard findings. The fixed transaction diagnostic ceiling was not raised or bypassed.
+
+## Acceptance coverage
+
+| Acceptance source                                 | Completion evidence                                                                                                                                                                                 |
+| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `00_standalone_project_bootstrap.md`              | Independent public Git repository, Apache-2.0 licensing, project-owned instructions/docs/tests/workflows, installable npm package, immutable Release, and Registry metadata                         |
+| `01_shared_architecture.md`                       | One engine and shared workspace/source/index/diagnostic/configuration/transaction/artifact services across Focus, GUI, map, and MCP tests                                                           |
+| `02_focus_tree_workbench.md`                      | Source-preserving import/layout/lint/render/create/update workflows, complex route metadata, deterministic HTML/SVG/PNG/JSON, and source-linked diagnostics                                         |
+| `03_scripted_gui_studio.md`                       | Deterministic full/crop/annotation/state/resolution/click-region/hierarchy/comparison rendering, integrated source graphs, bitmap diffs, and mandatory fidelity reports                             |
+| `04_agent_nudger.md`                              | Declarative state/province/geometry/region/adjacency/supply/railway transactions, global ID/color scans, split-data blockers, map artifacts, and rollback tests                                     |
+| `05_validation_delivery_and_agent_integration.md` | 503 portable tests, enforced coverage, synthetic CI fixtures, installed-data qualification, official Inspector, package/install checks, and coding-agent workflows                                  |
+| `06_public_mcp_server.md`                         | Read-only-default stdio and secured Streamable HTTP, OAuth/origin/isolation/limit checks, typed handlers, resource-backed artifacts, package/Release/GHCR/Registry publication, and client examples |
+
+## Simplifications, omissions, and blockers
+
+No required feature was replaced by a mock tool, static placeholder diagram, manual editor, interactive dashboard, game automation, or unpublished package. No required acceptance item or release blocker remains.
+
+Engine-unknown syntax and renderer fields are preserved and explicitly reported through refusal diagnostics and fidelity reports. Supported boundaries remain listed in [Known limitations](limitations.md), not hidden behind fallback rewrites. The real external focus workflow deliberately preserved 116 gameplay-design warnings because it was a layout-only transaction; those warnings are reported above and are not suppressed by the server.
+
+Detailed release commands, ordering, recovery behavior, and the immutable earlier release-attempt history remain in [Release and MCP Registry publication](release.md).

package/docs/configuration.md

@@ -1,8 +1,20 @@
 # Configuration and workspaces
 
-Pass a config with `--config PATH` or `HOI4_AGENT_CONFIG`. Unknown fields are rejected.
+Pass a config with `--config PATH` or `HOI4_AGENT_CONFIG`. Without either override, the server uses
+`~/.config/hoi4-agent-tools/config.json` on every platform (for example,
+`C:\\Users\\name\\.config\\hoi4-agent-tools\\config.json` on Windows). A different durable absolute
+path is equally valid when the client registration sets `HOI4_AGENT_CONFIG`. Unknown fields are
+rejected.
 The read-only setup discovery command also checks `HOI4_GAME_ROOT` and the path-delimited `HOI4_MOD_ROOTS`; it reports candidates without registering or modifying them.
 
+Setup stays read-only unless a write flag is explicit. The recommended write configuration is generated with:
+
+```bash
+hoi4-agent-tools-setup --init-config /absolute/path/config.json --workspace /absolute/path/mod --autonomous-writes --server-state /separate/operator/state
+```
+
+That writes `"writePolicy": "autonomous"` and `"writeEnabled": true` for the supplied mod. Use `--reviewed-writes` only for the legacy separate review/apply tool sequence; `--enable-writes` remains a compatibility alias for reviewed mode. Autonomous and reviewed flags are mutually exclusive, and both require `--server-state`.
+
 The stdio executable accepts newline-delimited JSON-RPC frames up to a fixed 16,777,216-byte
 ceiling, excluding the line-feed delimiter. This transport safety limit is deliberately not a
 configuration field; malformed UTF-8 and oversized terminated or unterminated frames close the
@@ -12,7 +24,7 @@ separately configured `http.maxBodyBytes`.
 ```json
 {
   "version": 1,
-  "writePolicy": "read-only",
+  "writePolicy": "autonomous",
   "serverStateRoot": "/var/lib/hoi4-agent-tools-state",
   "transactionTtlSeconds": 3600,
   "transactionMaxJournalBytes": 536870912,
@@ -43,7 +55,7 @@ separately configured `http.maxBodyBytes`.
       "replacePaths": ["common/national_focus"],
       "artifactRoot": "/srv/hoi4/workspaces/example/.hoi4-agent/artifacts",
       "cacheRoot": "/srv/hoi4/workspaces/example/.hoi4-agent/cache",
-      "writeEnabled": false
+      "writeEnabled": true
     }
   ]
 }
@@ -56,8 +68,8 @@ All byte values are exact bytes. Defaults are applied when a field is omitted.
 | Field                        |                 Default | Validation and behavior                                                                                                                                                                           |
 | ---------------------------- | ----------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `version`                    |                required | Must equal the current configuration version, `1`.                                                                                                                                                |
-| `writePolicy`                |           `"read-only"` | `"read-only"` or `"transactions"`.                                                                                                                                                                |
-| `serverStateRoot`            |                 omitted | Required for `"transactions"`; absolute canonical operator state used for the private journal key and replay-protection heads.                                                                    |
+| `writePolicy`                |           `"read-only"` | `"read-only"`, recommended `"autonomous"`, or compatibility `"transactions"`.                                                                                                                     |
+| `serverStateRoot`            |                 omitted | Required for either write policy; absolute canonical operator state used for the private journal key and replay-protection heads.                                                                 |
 | `transactionTtlSeconds`      |                  `3600` | 60 through 86,400 seconds.                                                                                                                                                                        |
 | `transactionMaxJournalBytes` |             `536870912` | At least 1 MiB; aggregate transaction-journal retention ceiling and per-plan work ceiling.                                                                                                        |
 | `transactionMaxJournals`     |                   `128` | 1 through 10,000 journals per workspace cache.                                                                                                                                                    |
@@ -78,7 +90,7 @@ The configuration also rejects unsafe combined budgets: `scanMaxBytes` multiplie
 `maxConcurrentRequests` must be at most 16 MiB. HTTP concurrency has a fixed maximum of two so two
 simultaneous offline renders cannot exceed the supported process-safety model.
 
-`serverStateRoot` is mandatory whenever `writePolicy` is `"transactions"`. It must be absolute,
+`serverStateRoot` is mandatory whenever `writePolicy` is not `"read-only"`. It must be absolute,
 resolve to a canonical directory through components that contain no symbolic links or junctions,
 and it must not overlap any configured or runtime source, fixture, artifact, cache, registration,
 writable-registration, or storage root. The server stores the native canonical spelling, including
@@ -97,7 +109,7 @@ protocol when those primitives are unavailable.
 | Field             | Default                         | Validation and behavior                                                                                                                      |
 | ----------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
 | `id`              | required                        | Lowercase identifier matching `[a-z][a-z0-9_-]{0,63}`; unique in the configuration.                                                          |
-| `name`            | required                        | Human-readable name, 1 through 200 characters.                                                                                               |
+| `name`            | required                        | Display name, 1 through 200 characters.                                                                                                      |
 | `root`            | required                        | Primary source root. Its root kind is selected by `kind`.                                                                                    |
 | `kind`            | `"mod"`                         | `"mod"`, `"game"`, or `"dependency"`. Only a mod primary root can ever be writable.                                                          |
 | `gameRoot`        | omitted                         | Optional additional read-only base-game source; it must not overlap another source in the workspace.                                         |
@@ -108,7 +120,7 @@ protocol when those primitives are unavailable.
 | `artifactRoot`    | mod default; otherwise required | A mod defaults to `<root>/.hoi4-agent/artifacts`. A game/dependency primary workspace must name an operator-owned path under `storageRoots`. |
 | `cacheRoot`       | mod default; otherwise required | A mod defaults to `<root>/.hoi4-agent/cache`. A game/dependency primary workspace must name an operator-owned path under `storageRoots`.     |
 | `fixtureRoot`     | omitted                         | Optional read-only fixture source.                                                                                                           |
-| `writeEnabled`    | `false`                         | Effective only for `kind: "mod"` when global `writePolicy` is `"transactions"`.                                                              |
+| `writeEnabled`    | `false`                         | Effective only for `kind: "mod"` when global `writePolicy` is `"autonomous"` or `"transactions"`.                                            |
 
 `registrationRoots`, `writableRegistrationRoots`, and `storageRoots` grant different capabilities:
 
@@ -166,11 +178,19 @@ path samples, so a workspace with many `replace_path` entries cannot inflate a t
 
 ## Read and write policy
 
-`writePolicy` defaults to `read-only`. Source apply/rollback requires `transactions` globally and `writeEnabled: true` on that mod workspace. A dependency or game registration remains read-only even if misconfigured.
+`writePolicy` defaults to `read-only`. In this mode the server exposes analysis and evidence tools but no source-mutation path.
+
+`autonomous` is the recommended write policy. With `writeEnabled: true` on a mod workspace, it exposes `hoi4.focus_rewrite`, `hoi4.gui_rewrite`, and `hoi4.map_rewrite`. Each tool plans, validates, journals, applies, rebuilds the index, and post-validates inside one call. If application or post-validation fails, exact original bytes are restored automatically. The transaction status/diff/apply/rollback tools are not registered in autonomous mode.
+
+`transactions` is an optional compatibility policy for clients that still need a distinct reviewed plan and apply boundary. It exposes the `*_plan_changes`/`map_plan` tools plus `hoi4.transaction_status`, `hoi4.transaction_diff`, `hoi4.transaction_apply`, and `hoi4.transaction_rollback`. It uses the same journal, hash checks, post-validation, and automatic failure recovery as autonomous mode.
+
+Both write policies require `serverStateRoot` and `writeEnabled: true` on the target mod. A dependency or game registration remains read-only even if misconfigured. Changing the global policy changes the MCP tool surface; restart the server and reinitialize the MCP session after changing it.
+
+The autonomous rewrite tools advertise `destructiveHint: true`. MCP does not require per-call prompts from that annotation, and server configuration cannot override a client's host approval or filesystem policy. A client may still prompt for or refuse a rewrite.
 
 `registrationRoots` controls runtime `hoi4.project_register`. A requested root must canonicalize beneath one of these roots, and a runtime mod additionally requires `writableRegistrationRoots`. HTTP principals also need `allowRegistration`. Granting `allowRegistration` permits that principal to register unclaimed sources beneath the configured capability roots, so use narrow roots or static reviewed workspaces for multi-user deployments. Runtime registration does not edit a client configuration or persist raw paths. It atomically records a hash-only owner/workspace claim in the canonical artifact root; later registrations of that physical store must match it. Reassigning a claimed store is therefore an explicit operator operation: stop the server, review/archive the claim and existing evidence, and choose whether to preserve or separately migrate data. The server never deletes or silently rebinds it.
 
-Transaction mode does not accept pre-upgrade unauthenticated journal manifests. Preserve their
+Write modes do not accept pre-upgrade unauthenticated journal manifests. Preserve their
 cache directories for operator review, then explicitly archive or remove them together with the
 corresponding protected state decision; the server never guesses a migration or treats a public
 integrity hash as authorization.

package/docs/focus-workflow.md

@@ -15,6 +15,11 @@ Decision categories are additive database fragments: the category definition und
 The shared index retains those fragments without reporting a duplicate-definition collision while
 still honoring same-relative-file shadowing and load-order source ownership.
 
+National focus `cost` values support finite numbers and safe file-scoped constants such as
+`@focus_cost_standard`. Targeted layout updates preserve the exact existing cost lexeme, including
+numeric formatting and comments. A cost token outside the typed model is retained unchanged when
+the plan does not explicitly replace it; the compiler refuses to generate an arbitrary scalar.
+
 National focuses and continuous focuses use their actual HOI4 source models. National trees come from the workspace registration's configured `roots.focus` paths. Continuous focuses come from `common/continuous_focus/*.txt` as `continuous_focus_palette = { ... focus = { ... } }`; matching country palettes take precedence over the default palette, and the compiler never emits a `continuous` field inside a national `focus = { ... }` block.
 
 ## Agent workflow
@@ -23,9 +28,126 @@ National focuses and continuous focuses use their actual HOI4 source models. Nat
 2. `hoi4.focus_scan` imports active national trees, matching continuous-focus palettes, active localisation, sprite definitions, and only the exact texture paths referenced by those sprites.
 3. `hoi4.focus_lint` separates syntax, reference, layout, and design diagnostics. Omit `mode` for national-tree compatibility, or pass `mode: "continuous"` with an optional `paletteId` to lint a palette directly.
 4. `hoi4.focus_layout` calculates stable integer coordinates. Pinned positions and existing coordinates anchor incremental changes.
-5. `hoi4.focus_render` returns deterministic HTML, SVG, PNG, JSON, and generated-source-map resources. National mode also returns the graph layout and hash-bound planning sidecar; continuous mode accepts palette columns and renders the actual continuous-focus source model.
-6. `hoi4.focus_plan_changes` accepts either a national plan (the backward-compatible default) or `mode: "continuous"` with a continuous-palette plan. Both make source-preserving range edits where possible and produce before/proposed/bitmap-diff review artifacts before creating the dry-run transaction. National plans also maintain the adjacent planning sidecar. To create a first tree or palette in a new mod source file, the coding agent must set `createIfMissing: true`; without that explicit flag, missing sources and IDs refuse. Creation never appends a different target to an existing source file, because doing so could repurpose unrelated source or its adjacent planning sidecar. It uses a transparent source-linked before render, never copies a read-only game/dependency file into a shadowing mod path, and rolls back newly created source and sidecar files atomically.
-7. Review drift, diagnostics, source maps, diff artifacts, and plan hash before apply.
+5. `hoi4.focus_render` returns deterministic HTML, SVG, PNG, JSON, and generated-source-map resources. National mode also returns the graph layout and hash-bound planning sidecar; a uniform `reviewScale` from `0.25` through `1.0` keeps unusually wide or deep trees within bounded raster limits without changing logical geometry or source coordinates. Continuous mode accepts palette columns and renders the actual continuous-focus source model.
+6. In autonomous mode, `hoi4.focus_rewrite` accepts either a national plan (the default when `mode` is omitted) or `mode: "continuous"` with a continuous-palette plan. It makes source-preserving range edits where possible, produces before/proposed/bitmap-diff evidence, journals exact recovery bytes, applies, rebuilds the index, and post-validates in one call. National plans may set `horizontalSpacing`, `verticalSpacing`, `padding`, and a uniform `reviewScale` for both review renders; those pixel-space settings do not alter focus coordinates or compiled HOI4 source. National plans also maintain the adjacent planning sidecar. To create a first tree or palette in a new mod source file, set `createIfMissing: true`; without it, missing sources and IDs refuse. Creation never appends a different target to an existing source file, never copies a read-only game/dependency file into a shadowing mod path, and restores newly created source and sidecar files automatically if the rewrite fails.
+7. Check `execution`, drift, diagnostics, validation, changed files, source maps, and diff artifacts. `execution: "planned"` means validation blocked the proposal without changing source; `execution: "applied"` means post-write validation succeeded.
+
+With the optional `"transactions"` compatibility policy, use `hoi4.focus_plan_changes`, page through `hoi4.transaction_diff`, and call `hoi4.transaction_apply` with the exact plan hash instead. The same core validation and recovery engine is used.
+
+## Repairing an existing large tree
+
+Imported authored coordinates are fixed by design. A plain `hoi4.focus_layout` call therefore
+audits an existing layout without silently rearranging it. To opt a badly structured tree into a
+full cleanup, the coding agent must make the movement policy explicit:
+
+1. Scan, lint, and render the baseline, then read the complete imported plan resource. Use the same
+   national `reviewScale` for baseline, transaction, and final renders when the default canvas is too
+   large.
+2. Preserve every prerequisite group, exclusion, route lock, reward, raw passthrough entry, source
+   location, and provenance value.
+3. Model the intended route architecture with `branchGroups`, `laneGroups`, `branchId`, and
+   `laneId`. Give lanes stable order and, where appropriate, horizontal bounds.
+4. Keep only deliberate trunk or convergence anchors fixed/pinned. Change every movable focus to
+   `{ "mode": "auto", "pinned": false }`; `preferredX` and `preferredY` may retain the authored
+   route intent without making those coordinates mandatory.
+5. Submit the complete plan to `hoi4.focus_rewrite`. The call performs layout, compilation,
+   lint, source-preserving range edits, deterministic before/proposed rendering, bitmap diffing,
+   journaling, application, index rebuild, and post-write validation.
+   For an unusually wide or deep tree, set a uniform national `reviewScale` between `0.25` and
+   `1.0`; `0.4` is appropriate for a very large comparison. It scales nodes, text, connectors, and
+   the viewport together, avoiding artificial overlap. The same scale governs both sides of the
+   comparison and affects only artifact pixels, never source-grid coordinates. Explicit spacing and
+   padding remain available when the artifact's logical presentation itself needs adjustment.
+6. Inspect the returned validation and evidence links. Rescan, lint, and render when additional
+   final evidence is useful. A blocked proposal changes nothing; failure after replacement begins
+   restores every affected file automatically.
+
+This workflow is suitable for hundreds of focuses. The solver keeps parents above children,
+rejects visible overlap and duplicate coordinates, separates bounded lanes, validates relative
+chains, and minimizes avoidable connector crossings. It never changes gameplay relationships to
+make a picture look cleaner.
+
+## Authoring a large tree
+
+For a new tree, translate route requirements into the strict public schema at
+`hoi4-agent://schema/focus-plan`. A robust plan uses a centered entry/trunk, bounded political or
+strategic lanes, separately modelled shared-support lanes, exact AND/OR prerequisite groups,
+reciprocal route exclusions, explicit convergence and capstones, automatic positions, and complete
+localisation/icon/AI/link metadata. Unsupported Clausewitz blocks belong in `rawPassthrough` so they
+round-trip instead of being approximated.
+
+This minimal national plan is schema-valid. It intentionally omits an icon and reward; a production
+tree should add complete presentation and gameplay data before rewriting:
+
+```json
+{
+  "schemaVersion": 1,
+  "id": "example_tree",
+  "default": false,
+  "branchGroups": [
+    {
+      "id": "constitutional",
+      "label": "Constitutional route",
+      "family": "politics",
+      "focusIds": ["example_entry"],
+      "laneId": "centre",
+      "major": true,
+      "hidden": false,
+      "crisis": false,
+      "conditional": false,
+      "aiStrategyIds": []
+    }
+  ],
+  "laneGroups": [
+    { "id": "left", "label": "Left route", "order": 0, "minimumX": -12, "maximumX": -5 },
+    { "id": "centre", "label": "Constitutional trunk", "order": 1, "minimumX": -2, "maximumX": 2 },
+    { "id": "right", "label": "Right route", "order": 2, "minimumX": 5, "maximumX": 12 }
+  ],
+  "entryFocusIds": ["example_entry"],
+  "focuses": [
+    {
+      "id": "example_entry",
+      "label": "Example entry",
+      "branchId": "constitutional",
+      "laneId": "centre",
+      "prerequisites": { "operator": "and", "groups": [] },
+      "mutuallyExclusive": [],
+      "routeLocks": [],
+      "position": { "mode": "auto", "pinned": false, "preferredX": 0, "preferredY": 0 },
+      "visibility": "normal",
+      "convergence": false,
+      "sharedSupport": false,
+      "icons": [],
+      "localisation": {
+        "titleKey": "example_entry",
+        "descriptionKey": "example_entry_desc",
+        "workingLabel": "Example entry"
+      },
+      "ai": { "majorRoute": true, "strategyIds": [] },
+      "filters": ["FOCUS_FILTER_POLITICAL"],
+      "links": [],
+      "rawPassthrough": []
+    }
+  ],
+  "sharedFocusIds": [],
+  "continuousFocusPaletteIds": [],
+  "continuousFocusIds": [],
+  "rawPassthrough": [],
+  "provenance": {
+    "sourcePath": "plan:example_tree",
+    "sourceHash": "0000000000000000000000000000000000000000000000000000000000000000",
+    "importedPlanHash": "0000000000000000000000000000000000000000000000000000000000000000"
+  }
+}
+```
+
+Within each focus, one `prerequisites.groups` entry represents one Clausewitz `prerequisite` block
+whose listed focuses are OR alternatives. Multiple group entries are AND requirements. For a new
+target, use `sourcePath: "plan:<tree-id>"` and 64 zeroes for both initial hashes, then call
+`hoi4.focus_rewrite` with `createIfMissing: true`. Use that convention only for a missing
+target. Existing sources normally use imported, hash-bound provenance; resolving intentional
+plan/source drift additionally requires explicit `authority: "plan"`. The server refuses to append
+a different tree to an occupied source file and still requires complete pre-write and post-write validation.
 
 ## Prerequisite and route semantics
 
@@ -47,7 +169,7 @@ Raster discovery is deliberately exact: the shared workspace scan does not walk
 
 ## Layout contract
 
-Hard constraints keep parents above children, coordinates unique, visible nodes non-overlapping, pinned nodes fixed, route lanes separated, and relative-position chains valid. The solver records every move and unsatisfied constraint. It never changes a prerequisite, silently stacks nodes, or invents a route.
+Hard constraints keep parents above children, coordinates unique, visible nodes non-overlapping, automatic nodes inside configured lane bounds, pinned nodes fixed, and relative-position chains valid. Automatic preferred coordinates are clamped to their lane; a full lane raises `FOCUS_LAYOUT_LANE_CAPACITY_BLOCKED`. Fixed, relative, or prior-stable coordinates outside their declared lane are preserved as evidence but produce a blocking `FOCUS_LAYOUT_LANE_BOUNDS_VIOLATION`. The solver records every move and unsatisfied constraint. It never changes a prerequisite, silently stacks nodes, or invents a route.
 
 Mutual-exclusion relationships are also layout constraints: newly placed automatic endpoints must retain at least the configured `nodeSpacing` in horizontal focus-grid columns. Fixed, relative, pinned, and prior-layout coordinates are stability anchors. The solver does not move those anchors to improve mutual-exclusion spacing or connector routing; it emits `FOCUS_LAYOUT_MUTUAL_EXCLUSION_SPACING_UNSATISFIED` with the movable and preserved endpoints when authored constraints make the gap impossible.
 
@@ -59,10 +181,17 @@ Weak dangling branches, terminal payoff, missing AI, and repeated generic reward
 
 The plan records imported source and semantic hashes. If both saved plan and hand-edited script diverge, regeneration is blocked until the coding agent explicitly identifies the authoritative source. Raw fields remain attached to source ranges either way. An explicitly created target reports `target_missing` drift with `requiresAuthority: false`; that status means there is no prior target to reconcile, not that an existing source was overwritten.
 
-Every compiled or proposed focus block receives a source-map entry containing the focus ID, generated location, planning-node location when available, and imported source location when available. National render artifacts use `<tree>.focus.source-map.json`; continuous renders use `<palette>.continuous.source-map.json`. Dry-run transactions retain the corresponding proposed source map and all review artifacts after apply and rollback.
+Every compiled or proposed focus block receives a source-map entry containing the focus ID, generated location, planning-node location when available, and imported source location when available. National render artifacts use `<tree>.focus.source-map.json`; continuous renders use `<palette>.continuous.source-map.json`. Rewrite journals retain the corresponding proposed source map and all review artifacts after success or automatic restoration.
 
 ## Artifacts
 
 Each rendered node includes its ID, resolved title/working label, resolved icon frame or diagnostic, coordinates, prerequisite type, exclusions, branch family, planner visibility/convergence/terminal state, AI metadata, and source-linked diagnostics. HTML search and filters inspect evidence only; they cannot write source.
 
 National-tree renders store `<tree>.focus.html`, `.svg`, `.png`, `.json`, `.source-map.json`, and `.plan.json`. Continuous-palette renders use the same core artifact store and produce `<palette>.continuous.html`, `.svg`, `.png`, `.json`, and `.source-map.json`. The JSON embeds the same complete generated-source map that is also stored separately, and all formats carry content hashes plus source/render provenance.
+
+A national focus rewrite also stores `<tree>.focus.proposed-validation.json`. It contains every
+diagnostic and validation check from re-importing, laying out, and linting the compiled proposal.
+When that complete set is larger than the fixed transaction-manifest allowance, the manifest keeps
+a blocker-first bounded summary and an explicit resource diagnostic; it never drops findings from
+the validation decision. The rewrite boundary uses the same pattern for oversized post-write
+diagnostics.

package/docs/gui-workflow.md

@@ -63,11 +63,15 @@ BMFont text inputs stop at 2,097,152 bytes, 50,000 records, 32 fields per record
 
 ## Source-preserving plans
 
-Existing `.gui` files accept only hash-bound patches at parser-proven ranges. A patch may replace one known scalar assignment or scalar value, delete one known scalar assignment, or insert complete parsed entries immediately before a block close. Whole-file ranges, block rewrites, unknown-field rewrites, malformed insertions, stale text, and ambiguous ranges are refused. New files may be supplied in full only when no mod, dependency, or game source already owns the path. Every proposal is reparsed and rendered before it can become a transaction.
+Existing `.gui` files accept only hash-bound patches at parser-proven ranges. A patch may replace one known scalar assignment or scalar value, delete one known scalar assignment, or insert complete parsed entries immediately before a block close. Whole-file ranges, block rewrites, unknown-field rewrites, malformed insertions, stale text, and ambiguous ranges are refused. New files may be supplied in full only when no mod, dependency, or game source already owns the path. Every proposal is reparsed and rendered before it can be journaled or applied.
+
+With `writePolicy: "autonomous"`, call `hoi4.gui_rewrite` in `source`, `patches`, or `helpers` mode. The one call validates the proposal, persists exact recovery bytes, applies under the workspace lock, rebuilds the index, and post-validates. A successful result reports `execution: "applied"`; a blocked proposal reports `execution: "blocked"` and changes no source; a valid no-change request reports `execution: "unchanged"`. Any application or post-validation failure restores the original bytes automatically. No transaction diff/apply/rollback tools are exposed in autonomous mode.
+
+The optional `"transactions"` compatibility policy exposes `hoi4.gui_plan_changes` and the separate transaction review/apply tools instead. Both policies use the same source-preserving compiler, validation, journal, and recovery implementation.
 
 ## Declarative helper compilation
 
-`hoi4.gui_plan_changes` in `helpers` mode compiles a strict, build-time helper document into explicit `.gui` source and then plans the write through the normal transaction path. The generated mod has no runtime dependency on `hoi4-agent-tools` or its server.
+`hoi4.gui_rewrite` in `helpers` mode compiles a strict, build-time helper document into explicit `.gui` source and runs it through the normal autonomous rewrite path. In compatibility mode, use `hoi4.gui_plan_changes` with the same input. The generated mod has no runtime dependency on `hoi4-agent-tools` or its server.
 
 A document has one `root` and may declare reusable `templates`. A template instance uses `kind: "template"` plus `templateId`; its instance ID becomes the deterministic prefix for every expanded ID and name. For example, instance `left_status` of a template whose root is named `status_card` produces `left_status__status_card`. Instance fields may override the template root, but templates do not provide parameters, slots, or appended children. Missing references, duplicate template IDs, duplicate node IDs, reference cycles, duplicate compiled GUI names, and source or expanded budget overflow refuse compilation. Expanded identifiers stop at 1,024 UTF-8 bytes; conservative source-construction work stops at 16 MiB, and final source stops at the 8 MiB Clausewitz parser ceiling before a transaction is planned.
 
@@ -95,7 +99,7 @@ The structured helpers compile as follows:
 
 Structured leaf output is type-aware. `iconType` accepts sprite/frame fields, `instantTextBoxType` accepts text/font plus `maxWidth` and `maxHeight`, and `buttonType` accepts sprite/frame plus `buttonText` and `buttonFont`. Leaf elements never receive a fabricated `size` block and cannot contain child GUI elements. Hardcoded or legacy forms such as `checkboxType`, `guiButtonType`, and `textBoxType` are refused by the structured helper; use `raw` only when an exact engine precedent justifies them.
 
-Selecting a custom UI `state` requires a matching `stateVariants` entry. Its frame, sprite, text, font, and allowlisted scalar attributes replace the base values in the emitted source; no preview-state comment or inferred frame is written. The engine-managed `normal`, `hover`, `pressed`, and `disabled` states may be named on `buttonType` without a custom variant, but the compiler does not fabricate their frame mapping. Attribute keys must be both safe identifiers and documented scalar fields for the selected container, icon, text, or button type; structured fields, misspellings, and type-incompatible fields cannot be smuggled through `attributes`. `raw` remains the explicit escape hatch for complete advanced Clausewitz GUI source and is counted in transaction evidence.
+Selecting a custom UI `state` requires a matching `stateVariants` entry. Its frame, sprite, text, font, and allowlisted scalar attributes replace the base values in the emitted source; no preview-state comment or inferred frame is written. The engine-managed `normal`, `hover`, `pressed`, and `disabled` states may be named on `buttonType` without a custom variant, but the compiler does not fabricate their frame mapping. Attribute keys must be both safe identifiers and documented scalar fields for the selected container, icon, text, or button type; structured fields, misspellings, and type-incompatible fields cannot be smuggled through `attributes`. `raw` remains the explicit escape hatch for complete advanced Clausewitz GUI source and is counted in rewrite evidence.
 
 ## Validation
 

package/docs/limitations.md

@@ -6,6 +6,7 @@ These are precise safety boundaries, not silent fallbacks.
 - Workspace scans default to 20,000 enumerated files, 134,217,728 aggregate content bytes, and 67,108,864 bytes for one file. Operators may lower these values per request but cannot raise them above server policy. Exceeding any ceiling refuses the complete scan with `SCAN_FILE_LIMIT` or `SCAN_BYTE_LIMIT`; a partial index is not returned. The configuration additionally requires aggregate scan bytes multiplied by HTTP request concurrency to remain at or below 512 MiB.
 - Stdio uses strictly decoded UTF-8 newline-delimited JSON-RPC with a fixed 16,777,216-byte frame ceiling, excluding the line-feed delimiter. A malformed UTF-8 frame is refused without replacement decoding; an oversized frame is refused as soon as it crosses the ceiling, even without a newline or end-of-input. Either condition closes the local transport without emitting protocol output. Use workspace files and MCP resources instead of oversized inline payloads.
 - Clausewitz/localisation parsing is bounded to 8,388,608 source bytes and 250,000 lines per file; Clausewitz tokenization is bounded to 250,000 tokens, block nesting to 256 levels, and localisation parsing to 100,000 entries. Broad project and GUI inventories skip the entire active source when one of these bounds is crossed, return `complete: false` with a bounded skipped-source list, and do not walk or publish symbols from the partial parse. An unresolved reference is downgraded only when the skipped source's path family could define that reference kind. Targeted reads and writes still refuse the affected source with an explicit blocker; content beyond a limit is never treated as a complete parse.
+- The aggregate shared index is bounded to 500,000 symbol records and 500,000 reference records. Reaching either ceiling returns an explicitly incomplete inventory. A symbol-ceiling drop records the affected symbol kind so unresolved definitions are reported as partial only where dropped symbols could contain them; the reference ceiling reports incomplete outbound-reference coverage without implying that a missing definition might exist. The server never presents a capped inventory as complete.
 - Source diagnostics are capped at 100 per file. When additional findings exist, 99 findings are retained and the final slot becomes `SOURCE_DIAGNOSTICS_TRUNCATED`, a blocker rather than a silent truncation.
 - Renderer coverage is field-by-field. Parsed engine-only GUI properties are retained raw and reported as ignored or unsupported; source changes crossing an unknown field or parsed block are blocked rather than normalized away. Special `textSpriteType`, `corneredTileSpriteType`, GFX `progressbarType`, and `maskedShieldType` semantics, secondary textures, and effect files currently produce only a partial primary-texture appearance with explicit fidelity items and a warning.
 - Offline GUI output is not guaranteed pixel-identical to the game engine and is never called a screenshot. Modelled geometry and asset composition are deterministic for the recorded render profile.
@@ -14,6 +15,7 @@ These are precise safety boundaries, not silent fallbacks.
 - Declarative GUI helper documents admit at most 1,024 one-root templates and 64 state variants per node; both source and expanded trees remain subject to the 128-level and 10,000-node ceilings. Grid columns stop at 10,000, expanded identifiers at 1,024 UTF-8 bytes, conservative source-construction work at 16 MiB, and final generated source at 8 MiB. Templates have root overrides but no parameters, slots, or appended children. Scroll-list helpers emit deterministic grid and entry-container handoff names but do not create `dynamic_lists` scripted-GUI bindings or verify an external scrollbar definition's axis. Meter helpers choose one static icon frame from a validated range and do not provide runtime progress behavior. Advanced, hardcoded, legacy, or non-allowlisted scalar GUI fields require the counted raw escape hatch.
 - Focus design diagnostics such as weak branches, payoff quality, avoidable crossings, or generic rewards are deterministic heuristics and do not rewrite gameplay.
 - Plan/script drift requires an explicit authoritative-source choice.
+- Autonomous mode deliberately exposes only `hoi4.focus_rewrite`, `hoi4.gui_rewrite`, and `hoi4.map_rewrite`; it does not expose transaction diff, status, apply, or explicit rollback tools. Failed application and post-validation restore automatically. An intentional later reversal requires Git or another explicit domain rewrite. The tools advertise `destructiveHint: true`, but MCP does not mandate per-tool confirmation and the server cannot override its host's approval policy.
 - Map geometry requires an exact polygon with explicit `fillRule: "even-odd"`, a canonical hash-bound raster-mask manifest, or absolute pixel selection. Polygon vertices are integer raster-boundary coordinates: `0` through raster width/height are valid, greater coordinates are refused before work allocation, and polygons are never clipped. Inclusion is determined at pixel centers. Descriptive geography alone cannot apply.
 - Province hole detection is a deterministic four-connected digital-topology review. It warns on enclosed components but does not declare every enclave invalid; provinces touching the horizontally wrapping map seam are excluded from the planar hole calculation.
 - Map text tables are limited to 16,777,216 bytes and 500,000 records so the bounded parser admits the current vanilla unit-position table. Province rasters are limited to the documented 13,238,272-pixel engine area, exact raster masks to 20,000,000 cells, and polygon rasterization to 50,000,000 cell-point comparisons. Every exact selection/recolor operation is additionally limited to 1,000,000 pixels, including explicit pixels, selected mask cells, rasterized polygons, normal-adjacency transfers, whole-province color updates, and merges. Known counts are refused before dangerous decoding/scanning/materialization with `MAP_SELECTED_PIXEL_BUDGET_BLOCKED`. Selected pixels use four-byte numeric offsets, so the primary operation-owned offset buffer remains below 4 MiB (4,000,000 bytes); coordinate-string keys and per-pixel coordinate/color object arrays are not materialized. Map diagnostics are capped at 2,000; overflow retains 1,999 findings and replaces the last slot with a blocking `MAP_DIAGNOSTICS_TRUNCATED`. Undefined bitmap colors retain at most 256 individual samples and add a blocker when more distinct colors exist.
@@ -23,8 +25,8 @@ These are precise safety boundaries, not silent fallbacks.
 - State `capital` is derived from exact victory points for inspection; Agent Nudger does not write a generic state `capital` assignment.
 - Map ID allocation obeys scanned format/contiguity evidence from every root's own `default.map`-selected definition database; it refuses an allocation when the current source family cannot safely represent a gap or append. A present selector with any syntax or parser-limit diagnostic blocks the whole map model, including when it belongs to a lower game/dependency root, because falling back could hide an ID or color collision.
 - Province merge/removal supports arbitrary compatible source IDs and compacts every connected province reference; it refuses renumbering only when the active definition table is already gapped or ambiguous by ID/color, or when source and target type/state/region membership is incompatible.
-- Recoverable logical multi-file atomicity cannot prevent an unrelated process from briefly reading a replacement sequence. Success follows the server's post-write validation and final hash check, and persisted before-bytes support rollback. This is not a race-proof filesystem transaction: hostile concurrent symlink, junction, mount, directory, or file replacement by another operating-system principal is outside the application security boundary.
-- Artifact retention defaults to 536,870,912 bytes, 5,000 manifests, and 134,217,728 bytes per content object; each provenance manifest is separately capped at 1 MiB before parsing. Broad project, focus, GUI, and map manifests retain a bounded source-hash sample plus a digest commitment to the complete inventory, while exact structured artifact content retains the complete hashes. Opt-in oversized logical evidence is preserved as bounded binary chunks plus a one-read JSON index, not as a larger content object: every chunk/index manifest counts against the same quotas, an index above 1 MiB is refused, and one logical preparation batch has a fixed 536,870,912-byte in-memory ceiling (or the lower configured aggregate ceiling). The whole logical batch is admitted before copying or hashing; preflight and hashing yield to cancellation. Transaction journals default to 536,870,912 bytes and 128 entries, with a fixed 16 MiB ceiling per authenticated manifest; only expired authenticated planned/rolled-back journals, authenticated safe cache-without-head remnants, head-without-cache remnants, or old manifest-less directories are pruned, while other terminal/interrupted or unauthenticated states remain fail-closed and count against quota. See [artifacts](artifacts.md) and [transactions](transactions.md).
+- Recoverable logical multi-file atomicity cannot prevent an unrelated process from briefly reading a replacement sequence. Success follows the server's post-write validation and final hash check, and persisted before-bytes support automatic failure restoration (plus explicit rollback in reviewed compatibility mode). This is not a race-proof filesystem transaction: hostile concurrent symlink, junction, mount, directory, or file replacement by another operating-system principal is outside the application security boundary. Git supplies project history but is not required for the internal recovery guarantee.
+- Artifact retention defaults to 536,870,912 bytes, 5,000 manifests, and 134,217,728 bytes per content object; each provenance manifest is separately capped at 1 MiB before parsing. Broad project, focus, GUI, and map manifests retain a bounded source-hash sample plus a digest commitment to the complete inventory, while exact structured artifact content retains the complete hashes. Opt-in oversized logical evidence is preserved as bounded binary chunks plus a one-read JSON index, not as a larger content object: every chunk/index manifest counts against the same quotas, an index above 1 MiB is refused, and one logical preparation batch has a fixed 536,870,912-byte in-memory ceiling (or the lower configured aggregate ceiling). The whole logical batch is admitted before copying or hashing; preflight and hashing yield to cancellation. Internal rewrite/transaction journals default to 536,870,912 bytes and 128 entries, with a fixed 16 MiB ceiling per authenticated manifest; only expired authenticated planned/rolled-back journals, authenticated safe cache-without-head remnants, head-without-cache remnants, or old manifest-less directories are pruned, while other terminal/interrupted or unauthenticated states remain fail-closed and count against quota. See [artifacts](artifacts.md) and [autonomous rewrites and transactions](transactions.md).
 - Installed-game and external-workspace font files are read locally and are never published as raw MCP resources or redistributed by this package. Their glyph outlines or bounded BMFont atlas crops may appear inside an authorized generated review artifact. Portable fixtures and tool-owned artifact labels use the pinned Roboto package under OFL-1.1; unavailable workspace glyph data is visibly classified as an approximation rather than delegated to a host font.
 - Local external integration depends on environment-provided paths and is not a substitute for portable CI.
 - The server never launches, automates, controls, or captures Hearts of Iron IV. Offline previews are not game screenshots and do not prove in-engine rendering or gameplay behavior.