hoi4-agent-tools 0.1.6 → 0.1.7

package/docs/agent-integration.md

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

package/docs/completion-report.md

@@ -1,18 +1,22 @@
-# Completion report: 0.1.6 release candidate
+# Completion report: 0.1.6 public release
 
-- Candidate version: `0.1.6`
+- Released version: `0.1.6`
 - Report date: 2026-07-11
-- Status: fix-forward implementation in qualification; public delivery incomplete
+- Status: complete; public delivery and installation independently verified
+- Release commit: `a7eeb31532c067fa2fe4e297f1710615b49a1273`
+- Annotated tag object: `4933d5bc28cc7941304d8573fcc1fea65ad74328`
+- Exact-source CI: [run 29161368937](https://github.com/klimPaskov/hoi4-agent-tools/actions/runs/29161368937)
+- Release workflow: [run 29161750887](https://github.com/klimPaskov/hoi4-agent-tools/actions/runs/29161750887)
 
 ## Implemented scope
 
-The release 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.
+The release provides the shared source-preserving core, Focus Tree Workbench, Scripted GUI Studio, Agent Nudger map workflow, read-only-by-default transaction controls, stdio and authenticated Streamable HTTP transports, package entry points, schemas, synthetic portable fixtures, and public deployment documentation described by this repository.
 
 The npm payload is explicitly limited to compiled entry points, documentation, schemas, `server.json`, and the project license, security policy, README, and changelog. Installed-game data, third-party mod data, fixtures, tests, source files, local configuration, and workspace artifacts are excluded.
 
 ## Qualification evidence
 
-The 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.
+The release passed all 46 portable test files: 495 tests passed and one POSIX case was intentionally skipped on Windows. Enforced coverage is 88.44% statements, 78.25% branches, 91.28% functions, and 89.90% lines.
 
 Release-specific qualification also covers:
 
@@ -66,27 +70,93 @@ Registry canonically omitted explicit `isSecret: false`; the pinned official sch
 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.
+The `v0.1.6` workflow completed every validation, writer, and final verification job. Independent
+post-release audits then downloaded the public bytes again without changing release state.
+
+| Surface        | Verified public evidence                                                                                                                                                           | Status   |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
+| GitHub source  | Public repository, annotated tag object `4933d5bc...`, and peeled commit `a7eeb315...`                                                                                             | Verified |
+| npm            | `hoi4-agent-tools@0.1.6`, exact tarball bytes, Registry signature, npm publish attestation, and SLSA provenance v1                                                                 | Verified |
+| GitHub release | Immutable [Release v0.1.6](https://github.com/klimPaskov/hoi4-agent-tools/releases/tag/v0.1.6), ID `352573210`, with exactly four byte-verified assets                             | Verified |
+| GHCR           | Anonymous `ghcr.io/klimpaskov/hoi4-agent-tools:0.1.6` index with exact amd64/arm64 runtimes and per-runtime SPDX/SLSA attestations                                                 | Verified |
+| MCP Registry   | Exact `io.github.klimPaskov/hoi4-agent-tools@0.1.6` record, strict-equal to `server.json`, with official `active` and `isLatest: true` state                                       | Verified |
+| Public install | Clean npm install, signature/attestation audit, setup diagnostics, stdio initialization/discovery, and authenticated Streamable HTTP session/resource/progress/cancellation checks | Verified |
+
+### npm and provenance
+
+- Published at `2026-07-11T17:41:29.169Z`; `latest` resolves to `0.1.6`.
+- Tarball: `669,550` bytes at `https://registry.npmjs.org/hoi4-agent-tools/-/hoi4-agent-tools-0.1.6.tgz`.
+- SHA-1: `0b240508a9dab4bc31a84ba1733ded3eb6983390`.
+- SHA-256: `b3925c8600fbb8eda44b7aaf36edb7d7bd056b84766e2b0cd6b4fa8fdbc385ce`.
+- SRI: `sha512-OaWY67zCEuwNj4AQZHlGBg59BoAQlgBoJ7soV5cOD2DiVClcjdz+8z0gBB02I1UXkoxFQgCcWw8YMVkBl0iLhg==`.
+- The npm and GitHub Release tarballs are byte-identical. Pinned npm `11.16.0` verified the
+  Registry signature, npm publish attestation, and SLSA provenance v1 with Rekor log index
+  `2145861311`. The provenance binds `release.yml`, `refs/tags/v0.1.6`, release commit
+  `a7eeb31532c067fa2fe4e297f1710615b49a1273`, and workflow run `29161750887`.
+
+### Immutable GitHub Release
+
+The GitHub Actions bot published Release ID `352573210` at `2026-07-11T17:46:42Z`; it is neither a
+draft nor a prerelease and reports `immutable: true`. Its body exactly matches tagged
+`CHANGELOG.md`. All assets have canonical empty labels, uploaded state, the canonical bot uploader,
+and API digest/size values matching independently downloaded bytes:
+
+| Asset                        |   Bytes | SHA-256                                                            |
+| ---------------------------- | ------: | ------------------------------------------------------------------ |
+| `container-image.json`       |     361 | `0830611b33f26cb24baf05a8e997512db962ad4297966aa3b7db0bd1a37da179` |
+| `hoi4-agent-tools-0.1.6.tgz` | 669,550 | `b3925c8600fbb8eda44b7aaf36edb7d7bd056b84766e2b0cd6b4fa8fdbc385ce` |
+| `npm-pack.json`              |  49,941 | `a359bc1e0e64d119606a9c6bfb3f1a77725089e7cd5ada82c7efef839594543f` |
+| `release-identity.json`      |     431 | `d289937579f1e6e272264b09b4d9286a62e2c05c01a921d56dbc3d678fb5f576` |
+
+### GHCR image and attestations
+
+- OCI index: `sha256:9593b77b50938a76341d293dd4ef97bb42224661a6a25dc28a1378e0109e0e5b`.
+- `linux/amd64`: `sha256:bda20a48cff5d5597467e22bb53b142bcb698420b637fe5cdc1f05107e7bce0f`.
+- `linux/arm64`: `sha256:52ed0aa7bf35de90f49364a94bb41fbd0136895a155af624fc26b4275631d735`.
+- The index has exactly two runtime and two attached attestation manifests, without orphans. Each
+  runtime has one SPDX 2.3 and one SLSA v0.2 statement whose sole SHA-256 subject is that runtime
+  digest. Provenance binds `Dockerfile`, `publish_image`, `refs/tags/v0.1.6`, the release workflow,
+  and the exact commit.
+- A fresh pull with an empty Docker configuration succeeded anonymously. A non-root, read-only,
+  network-disabled stdio smoke negotiated MCP `2025-11-25`, reported version `0.1.6`, and listed 26
+  tools. The default HTTP entry point also returned an authenticated Streamable HTTP initialization.
+
+### MCP Registry and public installation
+
+The exact official Registry endpoint returned a server object strict-equal to checked-in
+`server.json`, plus `status: active` and `isLatest: true`. `publishedAt`, `updatedAt`, and
+`statusChangedAt` are all `2026-07-11T17:46:54.873191Z`.
+
+A clean public installation fetched 132 packages only from `https://registry.npmjs.org`; its
+lockfile had no `file:`, `workspace:`, `link:`, repository-path, or other local resolution. The
+signature audit verified 131 installed package signatures and 17 attestations with no invalid or
+missing records. The installed setup entry point passed help, read-only config initialization,
+diagnostics, rendering probe, and client-config output. Installed stdio and authenticated,
+Origin-validated Streamable HTTP passed initialization, discovery, resources, prompts, progress,
+cancellation, and session deletion.
+
+## Acceptance coverage
+
+| Acceptance source                                 | Completion evidence                                                                                                                                                                                |
+| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `00_standalone_project_bootstrap.md`              | Independent public Git repository, Apache-2.0 licensing, project-owned instructions/docs/tests/workflows, installable npm package, immutable Release, and Registry metadata                        |
+| `01_shared_architecture.md`                       | One engine and shared workspace/source/index/diagnostic/configuration/transaction/artifact services exercised across Focus, GUI, map, and MCP acceptance tests                                     |
+| `02_focus_tree_workbench.md`                      | Synthetic and installed-data import/layout/lint/render workflows with deterministic HTML/SVG/PNG/JSON artifacts and source-linked diagnostics                                                      |
+| `03_scripted_gui_studio.md`                       | Deterministic full/crop/annotation/state/resolution/click-region/hierarchy/comparison rendering, source graph integration, bitmap diffs, and mandatory fidelity reports                            |
+| `04_agent_nudger.md`                              | Declarative state/province/geometry/region/adjacency/supply/railway transactions, global ID/color scans, split-data blockers, map artifacts, and rollback tests                                    |
+| `05_validation_delivery_and_agent_integration.md` | 495 portable tests, enforced coverage, synthetic CI fixtures, installed-data qualification, official MCP Inspector discovery, package/install tests, and end-to-end coding-agent workflows         |
+| `06_public_mcp_server.md`                         | Read-only-default stdio and secured Streamable HTTP, OAuth/origin/isolation/limit checks, typed handlers, resource-backed large artifacts, package/Release/GHCR/Registry publication, and examples |
+
+## Simplifications, omissions, and blockers
+
+No required feature was replaced by a mock tool, static placeholder diagram, manual editor,
+interactive dashboard, game automation, or unpublished package. No required acceptance item or
+release blocker remains. Engine-unknown syntax and renderer fields are preserved and explicitly
+reported through refusal diagnostics and fidelity reports; the supported boundaries are listed in
+[Known limitations](limitations.md), not hidden behind fallback rewrites.
+
+The immutable earlier release attempts and the exact unpublished `v0.1.4` draft remain unchanged as
+audit evidence. One independent post-release Registry read timed out and succeeded on retry; it did
+not affect the green release workflow or repeated successful verification.
 
 Detailed commands and failure behavior are documented in [Release and MCP Registry publication](release.md).

package/docs/configuration.md

@@ -1,6 +1,10 @@
 # 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.
 
 The stdio executable accepts newline-delimited JSON-RPC frames up to a fixed 16,777,216-byte
@@ -97,7 +101,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.                                         |

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,10 +28,125 @@ 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.
+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. `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 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, 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.
 
+## 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_plan_changes`. The dry run performs layout, compilation,
+   lint, source-preserving range edits, deterministic before/proposed rendering, and bitmap diffing.
+   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. Read every `hoi4.transaction_diff` page and all linked review resources. Apply the exact
+   hash-bound transaction only under the coding-agent host's configured write policy.
+7. Rescan, lint, and render the applied tree. A rejected result can be restored exactly with
+   `hoi4.transaction_rollback` and the same transaction ID and plan hash.
+
+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 apply:
+
+```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_plan_changes` 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 the normal dry-run/apply boundary.
+
 ## Prerequisite and route semantics
 
 One `prerequisite` block containing several `focus` entries is an OR group. Several prerequisite blocks are ANDed. The importer preserves that grouping exactly. It never flattens prerequisites into a graph that changes meaning.
@@ -47,7 +167,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.
 
@@ -66,3 +186,10 @@ Every compiled or proposed focus block receives a source-map entry containing th
 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 transaction 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 generic apply boundary uses the same pattern for oversized post-write
+diagnostics.

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.

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 before the `0.1.7` candidate 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,15 @@ 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. Its exact public evidence is retained in
+  [the 0.1.6 completion report](completion-report.md).
+
+`0.1.7` is the next strictly monotonic candidate. It adds agent-first discovery/setup guidance and
+corrects shared event indexing and partial-inventory focus diagnostics. The normal stable-version
+gate treats the public `0.1.6` 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.
 
 ## Required pre-tag immutability check
 

package/docs/self-hosting.md

@@ -128,7 +128,7 @@ place it beneath any source, capability, artifact, cache, fixture, or `storageRo
 ## Container
 
 ```bash
-docker build -t hoi4-agent-tools:0.1.6 .
+docker build -t hoi4-agent-tools:0.1.7 .
 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 +136,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.1.7
 ```
 
 Port publishing reaches the container through a non-loopback interface. The mounted configuration

package/docs/transactions.md

@@ -30,6 +30,12 @@ validation record.
 
 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 make a valid reviewed transaction impossible to apply.
+
 ## Apply
 
 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.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hoi4-agent-tools",
   "mcpName": "io.github.klimPaskov/hoi4-agent-tools",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Source-preserving HOI4 workbench exposed as a safe Model Context Protocol server for coding agents",
   "type": "module",
   "license": "Apache-2.0",
@@ -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.1.7/schemas/configuration.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {

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.1.7/schemas/continuous-focus-palette.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {