hoi4-agent-tools 0.0.0-bootstrap.1 → 0.1.3

package/docs/map-workflow.md

@@ -0,0 +1,89 @@
+# Agent Nudger map workflow
+
+Agent Nudger is a headless declarative map transaction service for coding agents. HTML/PNG/JSON maps are inspection evidence, not a manual editor.
+
+## Indexed sources
+
+The shared scan connects province bitmap and definitions, states, strategic regions, terrain/continent values, adjacency CSV, supply nodes, railways, victory points, resources/buildings, ownership/control/cores/claims, coast/ports, placement files, localisation, and dependency overrides. It honors each workspace's configured `roots.map`, `roots.states`, and `roots.localisation` directories. Files named by the active `default.map` (including adjacency, supply-node, railway, province, definition, and position files) remain authoritative for active reads and additive writes. Allocation and collision evidence additionally resolves every scanned root's own `default.map`-selected definition filename. A partial root without its own selector inherits the active definition filename for evidence only. If any selector-owning root has a malformed, parser-limited, or otherwise diagnostic-bearing `default.map`, map scan and indexing stop with `MAP_DEFAULT_MAP_SELECTOR_BLOCKED`; the service never substitutes `definition.csv`, `provinces.bmp`, or an inherited selector for an untrustworthy file.
+
+## Geometry input
+
+Province geometry apply requires one exact representation:
+
+- selected existing province IDs;
+- polygon with integer raster-boundary coordinates and explicit `fillRule: "even-odd"`;
+- raster mask manifest with dimensions, origin, exact selected-pixel count, SHA-256, and canonical Base64 data;
+- explicit absolute pixel region (`kind: pixels`).
+
+Natural-language descriptions can guide a coding agent, but are not accepted as apply geometry.
+
+Polygon vertices describe raster cell boundaries, not pixel indices. For a raster of `width` by `height`, every vertex must use an integer `x` from `0` through `width` and an integer `y` from `0` through `height`; the right and bottom boundary values `width` and `height` are valid. A greater coordinate is rejected with `MAP_GEOMETRY_OUT_OF_BOUNDS` before bounding-box or raster-work allocation, and polygon geometry is never silently clipped. Rasterization samples each candidate pixel at its center, `(x + 0.5, y + 0.5)`, using the required even-odd fill rule. Every selected center must still belong to the declared source province.
+
+Raster-mask `data` is one byte per cell in row-major order. Every byte is exactly `0` or `1`; the SHA-256 is computed over those decoded bytes. The declared rectangle must fit the active raster, its byte length must equal `width * height`, and both the selected count and hash must match before every selected absolute pixel is checked against the source province. A mask may describe at most 20,000,000 cells, while any one split, mask, polygon, normal-adjacency transfer set, whole-province color update, or merge may select/recolor at most 1,000,000 pixels. Polygon admission also stops at 50,000,000 cell-point comparisons. Counts known from the manifest or indexed province geometry are checked before decoding, raster scanning, or selection-buffer allocation; an over-limit operation returns `MAP_SELECTED_PIXEL_BUDGET_BLOCKED` without proposing changes.
+
+Selected geometry is represented internally as deterministic row-major numeric offsets rather than coordinate strings or `{x, y, color}` object arrays. The fixed 1,000,000-pixel ceiling keeps the primary four-byte offset buffer below 4 MiB (4,000,000 bytes), and uniform recolors copy the BMP once and write directly through those offsets. Explicit-coordinate duplicates and normal-adjacency transfer duplicates are detected by numeric offset. Source BMP operations use exact colors without antialiasing, interpolation, resizing, alpha conversion, or palette quantization. Untouched bytes and pixels remain identical.
+
+## State payload policies
+
+Split/merge/move operations do not guess manpower, resources, buildings, victory points, ownership, control, cores, claims, supply, or railway behavior. Each applicable payload must select an explicit policy:
+
+- remain with original state;
+- move with a named province;
+- deterministic proportional distribution;
+- exact manifest values;
+- block until resolved.
+
+Proportional rounding is deterministic and checked for conservation. The transaction remains blocked while any required policy is unresolved.
+
+State move, split, and merge manifests also declare `ports`, `supplyNodes`, `railways`, and `positions` as `follow-province`. Those records are keyed by a selected province or its state association, so their source bytes remain unchanged except for the already modelled state-ID field on applicable position rows. The explicit literals make that behavior reviewable and prevent a partial distribution object from silently choosing it.
+
+New states require an explicit name localisation key and a strict `localisation` policy. `existing` requires exactly one safe active `l_english` entry. `upsert` updates only the quoted value of that exact entry, appends to an explicitly targeted existing file, or creates an explicitly targeted file in a configured localisation root. Created and edited files are UTF-8 with BOM. Comments, key versions, spacing, line endings, ordering, unknown lines, and unrelated entries are preserved. Missing policy/target/key, duplicate active keys, unsafe paths, target mismatch, non-BOM encoding, or malformed target source blocks the whole operation before it contributes changes.
+
+`StateRecord.capital` is inspection-only derived data: select the province with the highest exact victory-point value, then the lowest province ID on a tie. Current state source has no generic `capital = <province>` field. Agent Nudger never emits or patches that assignment. `update_state.changes.capital` is therefore an assertion, not a write: it is accepted only beside an exact `victoryPoints` payload whose derived result matches the assertion (including `null` for no victory points). State moves, splits, and merges derive the result from their explicit VP policy.
+
+## Province merge and removal
+
+`merge_provinces` and `remove_province` accept arbitrary compatible source IDs; removed IDs do not need to be the highest rows in `definition.csv`. Surviving definitions are compacted deterministically to contiguous IDs from zero in old-ID order. Removed source IDs map to the target's compacted ID, including when the target itself moves downward.
+
+The same total old-to-new map is applied atomically to state membership, victory points, province buildings, strategic regions, special-adjacency endpoints and through-provinces, supply nodes, railways, unit positions, and building-position sea references. Source pixels are repainted with the target color; other province colors and pixels remain unchanged. Reference collisions created by the merge are resolved by the declared sum/deduplicate policy. Definition row order, comments and extra fields, text-file comments, line endings, and source encoding are retained by targeted rewrites, and rollback restores every affected file byte-for-byte.
+
+Compaction requires an active definition table that is already contiguous from zero and unambiguous by ID and color. The merge also requires every source and target to share province type plus exact state and strategic-region membership; these are refusal cases rather than guessed redistribution.
+
+Province split/create manifests explicitly retain existing victory points, province buildings, ports, supply nodes, railways, special adjacencies, positions, and entity locators on the source province while the selected pixels and new ID join the declared state and strategic region. To move connected data to the new province, place the corresponding exact remove/add or update operations after the split in the same ordered transaction. Omitting any retention field blocks the split before geometry changes are proposed.
+
+## Province type migration
+
+`update_province_definition` can migrate among `land`, `sea`, and `lake`. A real type change requires the complete strict `distribution` object; missing, partial, unknown, or transition-incompatible policies block the operation before it contributes any file change.
+
+The policy explicitly covers:
+
+- exact state membership (`retain`, `remove` with the indexed state ID, or `assign` with a target state ID);
+- retention of state-level values in their current states and strategic-region membership;
+- victory points and non-port province buildings (`retain-if-valid` or `remove`);
+- naval-base buildings plus port placements/references (`retain-if-valid` or `remove`);
+- supply nodes (`retain-if-valid` or `remove`);
+- railways (`retain-if-valid` or remove every containing route; routes are never silently spliced);
+- building and unit positions (`retain-if-valid` or `remove`) and entity locators (`retain-at-coordinate`, because type migration does not alter geometry);
+- special adjacency endpoint/through references (`retain-if-valid` or `remove-referencing`).
+
+Land-to-water requires removal from the exact indexed state and cannot leave that state without land. Water-to-land requires an explicit existing target state in the same strategic region. Sea targets require `ocean` terrain and continent `0`; lake targets require `lakes` and continent `0`; land targets require a non-water terrain and nonzero continent. Coastal fields and neighboring coastal changes remain exact manifest inputs and are verified by final map validation. Dependency removals and the definition edit share one hash-bound transaction, so apply and rollback cover every affected state, definition, network, position, and adjacency file together.
+
+When a dependency should move rather than disappear, place the corresponding exact `update_state`, position, supply, railway, or adjacency operation after the type migration in the same ordered manifest. The migration policy removes or retains the old record explicitly; the later operation supplies the new target explicitly.
+
+## Normal and special adjacency
+
+Special adjacency rows remain declarative `add_adjacency` and `remove_adjacency` operations against the active `default.map` adjacency CSV. Normal topological adjacency is derived only from four-neighbor province bitmap geometry (including horizontal map wrap) and uses separate `add_normal_adjacency` and `remove_normal_adjacency` operations.
+
+Every normal-adjacency operation carries unique exact pixel transfers with a coordinate, the province currently owning that pixel, and the destination province. Both requested endpoints and all transfer provinces must exist, every source must match the active raster, and every transfer must involve at least one requested endpoint. Agent Nudger repaints only those 24-bit pixels, rebuilds topology, and blocks/rolls back the operation unless the requested pair is present after an add or absent after a remove. Related coastal-definition changes remain explicit ordered operations in the same transaction.
+
+## Allocation
+
+ID/color allocation scans current game, dependencies, and mod sources first, including the definition table selected by each root's own `default.map` even when its filename differs from the active table. It records per-file/root maxima, used ranges, active definition contiguity, collisions, reserved values, selected value/color, and source revision. Explicit values are checked against the same evidence. A lower-root ID/color collision is returned as a named dependency conflict on the manifest operation that requested it. The allocator never assumes the numerically next value is safe.
+
+## Artifacts and validation
+
+Map base layers cover province, state, strategic region, terrain, continent, owner, controller, cores, claims, and coast. Overlays cover coastlines, ports, victory points, resources, state buildings, province buildings, supply nodes, railways, special adjacencies, building positions, unit positions, and weather positions. Resource/building data is present in canonical JSON as exact sorted state/province maps as well as deterministic PNG markers; HTML embeds the same JSON and PNG with pan/zoom controls. Render loops honor cancellation signals.
+
+Every map preflight stores three content-addressed PNG/JSON/HTML triplets: baseline (`map-before.*`), proposed (`map-proposed.*`), and changed-pixel/semantic diff (`map-diff.*`). Their links and content hashes are included in the transaction plan hash. Semantic diff JSON includes definitions, state/region membership, full state values (manpower, category, resources, owner/controller, cores/claims, VPs, state/province buildings, and derived capital), ports, building/unit/weather positions, entity locators, supply, railways, exact special-adjacency records, and exact bitmap-derived normal-adjacency pairs.
+
+Validation detects duplicate IDs/colors, bitmap-definition mismatches, invalid references, unassigned/multi-state land, invalid derived capitals/VPs/ports/regions/adjacency/supply/rail/placements, removed references, coast inconsistencies, duplicate state IDs, missing localisation, ownership/control conflicts, lost payload, changes outside declared bounds, and dependency conflicts. Geometry review includes disconnected components, one-pixel corridors, and enclosed province holes. Hole detection uses one bounded digital-topology pass and reports `MAP_PROVINCE_HOLE_REVIEW` as a warning because intentional enclaves can be valid; provinces crossing the horizontally wrapping seam are excluded from planar hole classification. Baseline comparisons diagnose dimensions, file/DIB header, row orientation, pixel offset, bit depth, and palette changes separately. Sea and legitimate lake/island cases are not misclassified as missing state membership.

package/docs/performance.md

@@ -0,0 +1,117 @@
+# Performance benchmark
+
+Performance is recorded by an explicit developer command, not by a required CI timing assertion:
+
+```bash
+npm ci
+npm run benchmark
+```
+
+The command prints a structured JSON report to stdout and exits nonzero only for correctness failures such as a fixture below its required size, a changed deterministic output, or unsafe cache invalidation. It has no elapsed-time or memory pass threshold. Timing and memory naturally vary by host, runtime, system load, and native codec build.
+
+## Workload and methodology
+
+The benchmark reads only checked-in, project-owned synthetic fixtures:
+
+- `fixtures/focus`: 255 focuses in ten route families, scanned and indexed through `CoreEngine`, then laid out, linted, rendered, and stored through `FocusWorkbench`;
+- `fixtures/gui`: 158 source elements and 203 visible scene elements, rendered through `ScriptedGuiStudio` as fourteen state scenes, three resolution/UI-scale scenes, five primary variants, comparison evidence, and 24 stored artifacts;
+- `fixtures/map`: the complete 256×256 map fixture across game, dependency, and mod fixture roots, scanned and indexed through `AgentNudger`, then rendered in all ten current base layers (including continent) with all twelve current overlays enabled;
+- a temporary copy of the focus workspace for metadata/content-hash cache checks.
+
+The 255-focus fixture's 13,152×3,600 raster (47,347,200 pixels) is intentionally below the fixed 48-Mi-pixel per-artifact ceiling. The vanilla 5,632×2,048 map is also below the ceiling at scale 1, and its diff/before/proposed output trio charges 34,603,008 of the 64-Mi-pixel aggregate request budget. Larger scale or variant combinations are refused before allocation rather than included in benchmark timing.
+
+Each workload runs twice in one process. **Cold** means the first invocation using a fresh service and empty temporary artifact/cache roots. **Warm** means the immediate repeat in the same Node process. The script does not evict the operating system's file cache, so “cold” is an application-level cold run, not a physical-disk cold run. With `--expose-gc`, garbage collection is requested before each measured pass.
+
+Elapsed values use the monotonic Node performance clock. Memory is the process endpoint measurement from `process.memoryUsage()`, not a sampled peak. RSS includes native allocations from Sharp/libvips; because suites run sequentially, native allocator retention can affect later baselines and deltas. One cold and one warm pass keep the command bounded; rerun it several times externally when investigating variance.
+
+The GUI total deliberately includes an explicit source scan followed by `renderAndStore`, which performs its own scan as part of the public workflow. The map render phase operates on the fully scanned index and renders all base layers without artifact-store I/O. Output fingerprints must match between cold and warm passes.
+
+## Recorded result
+
+Recorded at `2026-07-10T22:22:50.905Z` with this exact command from the repository root:
+
+```bash
+npm run benchmark
+```
+
+Runtime and platform:
+
+- Windows (`win32`) release `10.0.26200`, x64;
+- AMD Ryzen 5 7500F 6-Core Processor; 12 logical processors;
+- 32,375.906 MiB total physical memory;
+- Node.js `v24.15.0`, V8 `13.6.233.17-node.48`;
+- Sharp `0.35.3`, libvips `8.18.3`.
+
+Times are milliseconds. Memory columns are endpoint delta MiB for the measured pass.
+
+| Workload                       | Pass |      Total |           Scan/index |                      Layout or render/store |   RSS Δ | Heap-used Δ |
+| ------------------------------ | ---- | ---------: | -------------------: | ------------------------------------------: | ------: | ----------: |
+| Focus (255 nodes)              | Cold | 15,082.652 |               36.402 | layout 62.085; lint/render/store 14,983.948 |  21.820 |      12.223 |
+| Focus (255 nodes)              | Warm | 16,721.268 |                8.274 | layout 59.933; lint/render/store 16,652.932 |  55.937 |       4.343 |
+| GUI (158 source / 203 visible) | Cold | 11,507.893 | 59.041 explicit scan |             gallery render/store 11,448.837 | 200.343 |      47.387 |
+| GUI (158 source / 203 visible) | Warm |  5,607.155 | 46.417 explicit scan |              gallery render/store 5,560.708 |  49.492 |      48.742 |
+| Map (65,536 pixels)            | Cold |    852.390 |               31.467 |        ten layers × twelve overlays 820.908 | -38.598 |      58.195 |
+| Map (65,536 pixels)            | Warm |    671.601 |               21.518 |        ten layers × twelve overlays 650.073 |  20.762 |      30.028 |
+
+Relevant output and input counts from the same run:
+
+| Workload | Counts                                                                                                                                                                                |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Focus    | 8 scanned files; 255 focuses; 10 route families; 6 artifacts                                                                                                                          |
+| GUI      | 7 scanned files; 158 source elements; 203 visible elements; 14 states; 3 resolutions; 5 primary variants; 24 artifacts; 14,455,435 output bytes                                       |
+| Map      | 21 scanned files / 198,897 bytes; 65,536 pixels; 5 definition rows; 4 provinces with geometry; 3 states; 2 strategic regions; 10 base layers; 12 overlays per layer; 14,339 PNG bytes |
+
+Cold and warm output fingerprints matched for all three workloads.
+
+## Cache invalidation behavior
+
+`WorkspaceScanner` reads file metadata and bytes on every scan and computes a SHA-256 content hash. `CoreEngine` derives its revision from each file's display path, load order, and content hash, then keys its in-memory scan/index cache by workspace ID and revision. Size and modification time are recorded as evidence but are not trusted as the semantic cache key.
+
+Scan admission normally serializes physical scans for a workspace. If a scanner ignores cancellation, one replacement scan may run after the original request is aborted so current callers are not held behind abandoned work. At most two physical scanners may exist for that workspace in this state; a third request waits. Generation fencing prevents a stale late completion from replacing the current cache entry.
+
+The benchmark changes only the copied fixture's modification time and confirms that the revision remains unchanged and the in-memory snapshot is reused. It then changes source bytes without changing file size or modification time and confirms that the content hash changes, the revision changes, and the cached snapshot is not reused. In the recorded run:
+
+- baseline scan: 21.353 ms;
+- metadata-only rescan/cache hit: 5.431 ms;
+- same-size, same-mtime content change/rescan: 20.300 ms.
+
+The deterministic unit test in `tests/unit/core-cache.test.ts` continuously checks this correctness property without asserting timing. Explicit transaction apply/rollback paths also invalidate the workspace cache; the content-derived revision remains the safety backstop for external edits.
+
+The Scripted GUI Studio and Agent Nudger benchmark paths currently rebuild their domain scans/indexes on each call. Their warm figures therefore reflect runtime/JIT and operating-system cache effects rather than a domain-level memoization claim. Stored artifacts are content-addressed, but artifact storage is not treated as a parsed-source cache.
+
+## Reproducing and comparing runs
+
+Run from a clean install on the host being measured:
+
+```bash
+npm ci
+npm run --silent benchmark > benchmark-result.json
+```
+
+No game installation, mod workspace, environment variable, network access, or proprietary input is used. The script creates all runtime storage below the operating system temporary directory and removes it on completion. Compare the JSON phase timings, memory samples, counts, and runtime/platform block; do not compare only the total time across unlike hosts.
+
+To check cache correctness without collecting performance data:
+
+```bash
+npm test -- tests/unit/core-cache.test.ts
+```
+
+## Opt-in installed-data qualification
+
+The opt-in local suite is a compatibility qualification, not a CI performance threshold. It reads configured installed-game and external-mod roots in place, writes only to an operating-system temporary directory, and neither launches the game nor copies proprietary inputs into the project.
+
+On the same Windows/Node host documented above, the final `2026-07-10` qualification completed all three required tests through the fail-closed `npm run test:local` harness:
+
+| Workflow                                                                                                    |   Elapsed |
+| ----------------------------------------------------------------------------------------------------------- | --------: |
+| Large vanilla focus import, stable layout, and two deterministic renders, plus an external-mod focus render |  83.551 s |
+| External GUI/GFX/font graph construction and two deterministic full/annotated renders                       |  56.019 s |
+| External map scan plus state/coastline/supply/railway render and content-addressed PNG/JSON/HTML storage    |  22.981 s |
+| Total test time                                                                                             | 162.578 s |
+
+The GUI qualification's canonical source-graph JSON was 302,497,021 bytes. The default
+134,217,728-byte per-object ceiling remained enabled: storage produced a byte-exact three-chunk
+resource bundle plus its canonical index, repeated the same render/storage call, and verified
+deterministic output without truncating the graph or increasing the ceiling.
+
+The reporter independently confirmed three completed tests and no unhandled worker error. Root paths and source-derived content are intentionally absent from the report. These timings vary with installed data, disk/cache state, processor, memory, and codec versions; only completion and deterministic/correct output are assertions.

package/docs/release.md

@@ -0,0 +1,200 @@
+# Release and MCP Registry publication
+
+Releases use strict stable Semantic Versioning and an immutable Git tag. Every public writer
+re-queries both the direct tag and its optional annotated-tag peel immediately before the write.
+The peeled commit must equal `GITHUB_SHA` and the commit recorded in the release artifact.
+
+## Prerequisites
+
+- a clean tested commit on `main`;
+- package, server, source, schema, documentation, lockfile, and changelog versions synchronized;
+- the public GitHub repository owned by the canonical `klimPaskov` account;
+- GitHub release immutability enabled in repository settings before the first stable release;
+- a public, pre-bootstrapped `ghcr.io/klimpaskov/hoi4-agent-tools` package;
+- the npm namespace bootstrap completed and the trusted publisher configured;
+- GitHub Actions OIDC available for ordinary npm and MCP Registry publication.
+
+The release workflow uses the npm 11.16.0 CLI bundled with the pinned Node 24.18.0 LTS distribution.
+No release job upgrades npm globally. The ordinary npm OIDC publisher does not check out source,
+run `npm ci`, execute dependency lifecycle scripts, or install any package. It downloads the one
+artifact made by `validate_pack`, checks its recorded commit and SHA-256/SHA-512 digests, rechecks
+the public npm state and peeled Git tag, resolves the validated basename to a contained absolute
+artifact path, and publishes that exact tarball with `--ignore-scripts` and provenance. The
+absolute path is required because npm can parse a slash-containing relative path as a GitHub
+repository shorthand. If either the legacy `NPM_TOKEN` or one-use `NPM_BOOTSTRAP_TOKEN` repository secret exists, the ordinary release fails
+before requesting or using trusted-publisher credentials.
+
+## One-time npm namespace bootstrap
+
+An unclaimed package cannot have a trusted publisher configured. The one-time manual
+`Bootstrap npm trusted publishing` workflow claims the namespace with the non-executable
+prerelease `0.0.0-bootstrap.1`; it never publishes a stable release. The `.1` suffix preserves
+the immutable audit trail of an earlier `.0` tag whose run stopped before npm accepted any
+publication.
+
+1. Create the immutable tag `npm-bootstrap-v0.0.0-bootstrap.1` on the reviewed `main` commit.
+2. Create a short-lived npm granular access token with read/write access to **All Packages** and
+   bypass-2FA enabled. This broad initial scope is an npm limitation for an unclaimed namespace.
+   Give it the shortest practical expiry and store it only as `NPM_BOOTSTRAP_TOKEN`.
+3. Dispatch `bootstrap-npm.yml` from that exact tag. The workflow has no `id-token` permission,
+   accepts only the hard-coded package/version/dist-tag, runs `npm audit signatures` before the
+   write, publishes a two-file non-executable tarball under the `bootstrap` dist-tag, and verifies
+   the public bytes and npm registry signature without the token.
+4. Revoke the granular token immediately and delete `NPM_BOOTSTRAP_TOKEN`.
+5. Configure npm trusted publishing for GitHub owner `klimPaskov`, repository
+   `hoi4-agent-tools`, and workflow `release.yml`; explicitly select the required allowed action `npm publish`.
+   npm requires an allowed action for configurations created after May 20, 2026.
+
+The ordinary release workflow never supports token fallback. Do not create an `NPM_TOKEN`
+secret, and delete `NPM_BOOTSTRAP_TOKEN` immediately after the namespace claim; either secret's
+presence deliberately blocks the OIDC publisher.
+
+On an entirely new npm package, the registry can additionally assign the sole bootstrap version
+to `latest` even when the publish command explicitly selects `bootstrap`. The first stable release
+accepts only the exact observed recovery state: versions contains only `0.0.0-bootstrap.1`, and
+the only dist-tags are `bootstrap` and `latest`, both naming that version. Any extra version, tag,
+different prerelease, missing bootstrap tag, or malformed state stops publication. Once the first
+stable package is published, the normal strict stable-version monotonic and exact-rerun rules apply.
+
+## 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.3` 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
+  tarball operand as GitHub repository shorthand;
+- `v0.1.2` published the exact npm package with trusted-publisher provenance, then stopped in the
+  independent verifier because the pinned npm subprocess had been configured with the official
+  Registry URL without its trailing slash while the strict verifier required the canonical
+  slash-terminated spelling. npm signatures and attestations themselves verified successfully;
+  GHCR, GitHub Release, and MCP Registry writers were skipped.
+
+`0.1.3` centralizes the exact canonical Registry URL used by the subprocess and verifier. The
+normal stable-version monotonic gate treats the public `0.1.2` 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
+
+GitHub's immutable-release settings endpoint requires repository `Administration:read`, which
+the short-lived repository `GITHUB_TOKEN` cannot request. Do not add a long-lived administration
+token to Actions for this check. Instead, the repository owner must run the authenticated check
+below immediately before pushing each stable release tag:
+
+```bash
+test "$(gh api \
+  --header 'X-GitHub-Api-Version: 2026-03-10' \
+  repos/klimPaskov/hoi4-agent-tools/immutable-releases \
+  --jq '.enabled')" = 'true'
+```
+
+This owner check is a release prerequisite and must pass before the first public writer starts.
+The workflow also requires the completed release to report `immutable: true` before MCP Registry
+publication and final verification. That post-publication gate detects a skipped prerequisite,
+but it cannot undo a mutable release; an administrator changing the setting between the owner
+check and release publication is an external GitHub settings race that the release API offers no
+conditional publish operation to close.
+
+## One-time GHCR visibility bootstrap
+
+GitHub creates the first personal-account container package as private. Run the pinned manual
+`Bootstrap GHCR` workflow from public `main`, then change package visibility to **Public** in the
+package settings. The bootstrap uses only the repository-scoped `GITHUB_TOKEN`, publishes only
+the `bootstrap` tag, and verifies the authenticated index contains exact `linux/amd64` and
+`linux/arm64` runtime manifests. GitHub exposes no supported API for changing a personal GHCR
+package's visibility, so the bootstrap cannot prove anonymous access until an administrator makes
+that newly created package public in the package settings.
+
+```bash
+gh workflow run bootstrap-ghcr.yml --repo klimPaskov/hoi4-agent-tools --ref main
+gh run watch --repo klimPaskov/hoi4-agent-tools
+```
+
+After changing visibility to **Public**, prove anonymous visibility and both runtime manifests with
+a Docker configuration that contains no credentials:
+
+```bash
+ANONYMOUS_DOCKER_CONFIG="$(mktemp -d)"
+MANIFEST="$(DOCKER_CONFIG="$ANONYMOUS_DOCKER_CONFIG" \
+  docker buildx imagetools inspect --raw \
+  ghcr.io/klimpaskov/hoi4-agent-tools:bootstrap)"
+RUNTIME_PLATFORMS="$(jq --raw-output \
+  '[.manifests[] | select(.platform.os == "linux") | "\(.platform.os)/\(.platform.architecture)"] | unique | sort | join(",")' \
+  <<<"$MANIFEST")"
+rm -rf "$ANONYMOUS_DOCKER_CONFIG"
+test "$RUNTIME_PLATFORMS" = 'linux/amd64,linux/arm64'
+```
+
+## Local release audit
+
+```bash
+npm ci --ignore-scripts
+npm audit --audit-level=high
+npm audit signatures --ignore-scripts
+npm run check
+npm run test:coverage
+npm run inspector
+REGISTRY_LIVE_VALIDATION=1 npm run registry:validate
+npm pack --dry-run --ignore-scripts --json
+```
+
+The workflow repeats `npm audit signatures` as a mandatory gate before any public writer can
+start. It verifies the package-manager inputs used by the build and later verifies the newly
+published package with `npm audit signatures --json --include-attestations`.
+
+## Enforced publication chain
+
+1. `validate_pack` verifies the remote peeled tag, `main` ancestry, canonical identity, npm
+   release order, repository/GHCR visibility, all checks, dependency signatures, and coverage. It
+   creates one tarball, `npm-pack.json`, and `release-identity.json` bound to the tarball digests
+   and source commit. This job has no OIDC permission.
+2. `publish_npm` is the minimal OIDC job. It rejects both npm bearer-token secrets, downloads and validates the
+   exact artifact, rechecks npm ordering and the remote peeled tag, resolves the tarball to a
+   contained absolute file path, then publishes only when the version is absent. It performs no
+   checkout or dependency installation.
+3. `verify_npm` has no OIDC permission. It downloads the public tarball byte-for-byte, runs the
+   official npm signature verifier, and passes the exact returned Sigstore bundle to npm's bundled
+   official Sigstore verifier with the expected Fulcio issuer and workflow certificate identity.
+   Verification requires one signed DSSE envelope, Rekor inclusion, the exact npm PURL and
+   SHA-512 subject, GitHub-hosted runner builder, release workflow/tag, and release commit. A
+   replayed bundle that differs from the current registry response is rejected.
+4. `publish_image` first checks the anonymous exact SemVer tag and GitHub release as one state
+   matrix. A completed identical rerun is accepted only when the tag digest equals the immutable
+   `container-image.json` release asset. If the tag exists but the later GitHub release does not,
+   the workflow reconstructs `container-image.json` from the exact anonymous digest and permits
+   recovery only after the normal anonymous verifier proves the index digest, two runtime
+   platforms, image source/revision/version labels, SBOM subjects, provenance subjects, source
+   tag, and source SHA against `GITHUB_SHA`. A release without its image tag, any mismatched
+   release asset, or any failed provenance check stops the chain. A first publication builds from
+   the action's default Git context, pushes by digest without a tag, rechecks the Git tag, then
+   creates the exact SemVer tag once. No mutable major/minor tag is published.
+5. `github_release` uses the authenticated, fully paginated List releases endpoint because
+   GitHub's by-tag endpoint exposes published releases but not drafts. It requires zero or one
+   exact tag match, cross-checks the published endpoint, and classifies the state as absent, a
+   mutable draft, or an already-complete immutable release. Drafts and publications must be owned
+   by the canonical GitHub Actions bot, use the exact tag-derived title and checked-in changelog
+   body, and expose no asset-label override. An existing draft may contain only a byte-for-byte
+   verified subset of the four expected uploaded assets from that same bot; unexpected,
+   duplicate, differently uploaded, non-uploaded, or differing assets stop the workflow without
+   deletion or replacement. The pinned release action stages missing assets with overwrite
+   disabled, canonicalizes the title and body, and leaves the release as a draft. Its numeric
+   release ID must match the unique authenticated listing. The workflow then requires the exact
+   npm tarball, both npm manifests, and `container-image.json`, repeats the unique-ID, metadata,
+   and byte checks, rechecks the peeled tag, and publishes that verified draft once.
+   Repository-level release immutability protects the assets and Git tag after publication. An
+   exact uploaded subset is resumable; a failed GitHub upload left in `starter` state or a draft
+   with noncanonical authorship or labels is a manual draft-cleanup blocker rather than permission
+   to overwrite or delete assets automatically. A completed rerun must match the one listed/public
+   release ID, canonical metadata, and all four immutable assets exactly.
+6. `publish_registry` validates a checksum-pinned official publisher, uses GitHub OIDC, rechecks
+   the peeled tag after login, and publishes the exact `server.json` only when absent.
+7. `verify_public` re-queries the peeled tag and verifies npm, immutable GitHub release assets,
+   anonymous GHCR digest/SBOM/provenance, and complete MCP Registry metadata. It also performs a
+   clean public install and registry-signature audit.
+
+The global non-cancelling `release` concurrency group serializes releases. npm, GitHub release,
+the exact container tag, and MCP Registry version are treated as immutable: existing matching
+objects may make a completed rerun idempotent, while absent records, moved tags, ambiguous state,
+or differing bytes/digests stop the chain. The Registry hosts metadata, not package bytes; local
+validation alone is never treated as publication evidence.

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

@@ -0,0 +1,46 @@
+# MCP protocol, SDK, security, and Registry review
+
+Verified 2026-07-10 against official sources.
+
+## Selected production baseline
+
+- Final protocol: [`2025-11-25`](https://modelcontextprotocol.io/specification/2025-11-25).
+- Production TypeScript SDK: [`@modelcontextprotocol/sdk` 1.29.0](https://www.npmjs.com/package/%40modelcontextprotocol/sdk?activeTab=versions), using the [`v1.x` server guide](https://github.com/modelcontextprotocol/typescript-sdk/blob/v1.x/docs/server.md).
+- Inspector: [`@modelcontextprotocol/inspector` 0.22.0](https://www.npmjs.com/package/%40modelcontextprotocol/inspector).
+- Registry schema: [`2025-12-11/server.schema.json`](https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json).
+- Registry publisher pinned by release workflow: `v1.7.9`; the workflow verifies the published checksum manifest and archive before extraction.
+
+The breaking `2026-07-28` protocol and SDK v2 split packages were release candidates on the review date. They are not used for the production package. This decision must be revisited after the final release.
+
+## Transport and capability requirements applied
+
+- Stdio uses newline-delimited UTF-8 JSON-RPC, protocol-only stdout, and stderr logging.
+- Streamable HTTP uses one `/mcp` POST/GET endpoint plus DELETE for session termination. It is stateful to support progress, cancellation, server notifications, SSE resumption, and secure random sessions.
+- Sessions are bound to authenticated principals and expire; they are never authentication credentials.
+- Tools use strict schemas and explicit read-only/destructive/idempotent/open-world annotations. Hints do not replace enforcement.
+- Long work observes `AbortSignal` and sends monotonic progress only when the client supplies a progress token.
+- Large results are content-addressed resources. Binary reads are bounded/chunkable because resource links defer retrieval but are not a byte-stream transport.
+- Prompts describe safe workflows but grant no permission.
+
+## Remote security requirements applied
+
+- Loopback is the default bind address.
+- Present origins and Host are validated; request body, concurrency, rate, session, and expiry limits are enforced.
+- Every HTTP method authenticates. Static environment bearer tokens are loopback-only.
+- Non-loopback operation requires HTTPS and OAuth/OIDC resource-server JWT verification: issuer, JWKS, audience, algorithms, expiry, subject, and required scopes.
+- Protected Resource Metadata is exposed when OAuth is configured.
+- Principal-to-workspace grants are server-side; token passthrough, query-string tokens, cross-principal sessions, and cross-workspace transactions are rejected.
+
+Primary references: [transport specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports), [authorization](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization), [security guidance](https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices), [tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools), [resources](https://modelcontextprotocol.io/specification/2025-11-25/server/resources), [prompts](https://modelcontextprotocol.io/specification/2025-11-25/server/prompts), [progress](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/progress), and [cancellation](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/cancellation).
+
+## Registry requirements applied
+
+- `package.json.mcpName` exactly matches `server.json.name`.
+- The public npm package version, server version, and Registry version are exact and synchronized.
+- Registry versions are immutable; release metadata is validated before publishing.
+- npm is published first because the Registry stores discovery metadata rather than package bytes.
+- The release workflow uses GitHub OIDC for `mcp-publisher` and npm provenance.
+- npm trusted publishers created after May 20, 2026 require an explicit allowed action; this package selects `npm publish`, uses a GitHub-hosted runner with `id-token: write`, and does not restore a package-manager cache in release jobs.
+- The pinned official publisher's live `validate` operation accepts this release's `server.json` before publication.
+
+References: [Registry quickstart](https://modelcontextprotocol.io/registry/quickstart), [package types](https://modelcontextprotocol.io/registry/package-types), [versioning](https://modelcontextprotocol.io/registry/versioning), and [GitHub Actions publishing](https://modelcontextprotocol.io/registry/github-actions).

package/docs/research/source-ledger.md

@@ -0,0 +1,68 @@
+# HOI4 source research ledger
+
+Reviewed 2026-07-10. These sources informed format support and tests; no installed-game or third-party-mod content is included in this repository.
+
+## Offline wiki snapshot
+
+The supplied offline Hearts of Iron IV wiki snapshot was consulted for:
+
+- `Data structures - Hearts of Iron 4 Wiki.md`: ordered blocks, variables/tokens, event targets, and generic script structure.
+- `National focus modding - Hearts of Iron 4 Wiki.md`: tree assignment, prerequisite grouping, relative positions, exclusions, continuous focuses, icons, AI, filters, and localisation.
+- `Interface modding - Hearts of Iron 4 Wiki.md`: containers, element types, scrolling, positions, orientation, and fonts.
+- `Scripted GUI modding - Hearts of Iron 4 Wiki.md`: contexts, parents, visibility, effects/triggers, dynamic lists, properties, AI, templates, and scripted localisation.
+- `Graphical asset modding - Hearts of Iron 4 Wiki.md`: sprite, frame animation, progress, and bitmap-font declarations.
+- `Map modding - Hearts of Iron 4 Wiki.md`: BMP headers/palettes, coordinates, definitions, terrain, buildings, unit positions, adjacency, and supply.
+- `State modding - Hearts of Iron 4 Wiki.md`: state/history/province/building/resource/victory-point structure and strategic-region constraints.
+- `Localisation - Hearts of Iron 4 Wiki.md`: UTF-8 BOM, language headers, key grammar, versions, escaping, and scripted localisation.
+- `Triggers`, `Effects`, and `Scopes`: ordered raw trigger/effect preservation and source-reference indexing.
+
+The wiki remains useful background, but current official files and installed examples take precedence when they differ.
+
+## Installed official documentation
+
+Under `<HOI4_ROOT>/documentation`:
+
+- `script_concept_documentation.md`: collections, contextual/formatted localisation, math expressions, and script constants.
+- `triggers_documentation.md`: current trigger names/scopes, state/province/focus/railway references, and dynamic argument support.
+- `effects_documentation.md`: current effect names/scopes and state/province/focus references. Its
+  553 documented effect identifiers form the bundled Focus Workbench native-effect catalog;
+  headings only were retained, not proprietary documentation prose.
+- `loc_objects_documentation.md` and `loc_formatter_documentation.md`: current province/state objects and font/layout-relevant localisation behavior.
+- `dynamic_variables_documentation.md`, `modifiers_documentation.md`, collection input/operator documentation: tokens and raw constructs the CST must retain.
+
+Official documentation found outside that folder was also consulted, especially:
+
+- `common/scripted_guis/_documentation.md`: authoritative current contexts, parent attachment, dynamic lists, properties, dirty variables, effects/triggers, and AI fields.
+- `common/focus_inlay_windows/documentation.md`: current inlay fields, including scripted buttons and progress bars absent from older summaries.
+
+## Vanilla precedents
+
+Representative read-only examples:
+
+- `common/national_focus/generic.txt` and large country trees for repeated prerequisite blocks, OR groups, exclusions, relative positions, raw rewards, `continuous_focus_position`, route AI, uppercase `IF`/`ELSE_IF`/`ELSE`, weighted `random_list`, direct scripted-effect calls, scoped country/state/character blocks, decision/formable links, and cosmetic-tag effects.
+- `common/continuous_focus/generic.txt` for the current `continuous_focus_palette = { ... focus = { ... } }` model, palette selection/position, and continuous-focus availability, enablement, modifier, cost, and AI fields.
+- `interface/achievements.gui`, `interface/abilitylist.gui`, scripted-GUI interface files, and paired `.gfx` files for nested containers, lists, click regions, sprite states, and ordering.
+- `common/scripted_guis/*.txt` for decision-category contexts, button effect/trigger naming, AI, dynamic lists, and parent/window connections.
+- `interface/*.gfx`, `gfx/interface/**`, and `gfx/fonts/**` for horizontal frame strips, fractional animation rates, DDS/TGA/PNG textures, vector and bitmap font sources.
+- `map/default.map`, `map/provinces.bmp`, `map/definition.csv`, `map/adjacencies.csv`, `map/supply_nodes.txt`, `map/railways.txt`, `map/buildings.txt`, `map/unitstacks.txt`, and `map/weatherpositions.txt` for current map formats.
+- `history/states/*.txt` and `map/strategicregions/*.txt` for state/region membership and ordered history payloads.
+
+## Current format conclusions
+
+- The inspected installed build was HOI4 1.19.2 content dated 2026-06-12.
+- `provinces.bmp` is a 5632×2048, uncompressed, bottom-up 24-bit BMP with a 40-byte DIB header.
+- Other current map BMPs include indexed 8-bit DIB40 and DIB124 files; the codec must honor pixel offsets, row padding, palette size, orientation, and untouched bytes.
+- Map CSV/text examples use UTF-8 without BOM and LF; localisation examples use UTF-8 BOM. The source model detects and preserves each file rather than normalizing it.
+- Active placement data is in building/unit/weather files; `positions.txt` may exist but be empty. Model-local `.asset` locator blocks are a separate source family.
+- `weatherpositions.txt` uses `small` and `big` tokens in the inspected build.
+- Sprite textures include PNG, TGA, uncompressed DDS, DXT1/3/5, DX10 RGBA/BGRA, and RXGB variants. Frame counts divide a horizontal strip; animation rates may be fractional.
+- Bitmap fonts use `.fnt` metrics/kerning and texture atlases. Locale overrides and additional script font files must remain connected in the source graph.
+- Definition rows and state IDs are contiguous in the inspected build. Province ID allocation therefore records current contiguity and must not treat arbitrary gaps as universally safe.
+- Only land provinces are required to belong to a state; sea provinces and some lakes legitimately do not. Every nonzero province is expected in one strategic region.
+- State source does not expose a generic `capital` field. Map operations distinguish a country's capital-state reference from a state's chief victory-point/capital province and never guess between them.
+- Clausewitz quoted strings decode only escaped quote and backslash. Literal newlines are invalid. Token expressions such as `variable?100` are scalar atoms; only `?=` is an operator.
+- Focus completion rewards call scripted effects directly by identifier; there is no native
+  `scripted_effect = helper_id` wrapper. `set_cosmetic_tag` targets cosmetic identity and is not a
+  formable-decision reference. Formables are decision targets, and
+  `unlock_decision_category_tooltip` targets a top-level decision category.
+- File replacement, duplicate keys, and ordering are database-specific. Same relative indexed filename shadows lower load-order sources; directly indexed files in a `replace_path` directory are removed without treating every descendant asset as removed.