hoi4-agent-tools 0.2.0 → 1.0.0

package/docs/release.md

@@ -1,222 +0,0 @@
-# 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 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.
-- `v0.1.3` published and independently verified npm, then published the exact two-platform GHCR
-  image with SPDX SBOM and SLSA v0.2 provenance for both runtime manifests. Its post-push verifier
-  incorrectly required BuildKit's `configSource.uri` to retain the Git tag even though the action
-  resolves the default Git context to the immutable commit. The provenance digest and URI were
-  commit-bound, and its environment separately carried the exact tag, repository, release workflow,
-  workflow SHA, event, and job. GitHub Release and MCP Registry writers were skipped.
-- `v0.1.4` published and independently verified npm and the exact two-platform GHCR image, then
-  staged an exact four-asset GitHub draft. The live Releases API represented an omitted optional
-  asset label as an empty string while the verifier accepted only `null`, so the draft remained
-  unpublished and MCP Registry publication was skipped. The tag, npm package, image, draft, and
-  draft assets remain unchanged as audit evidence.
-- `v0.1.5` published and independently verified npm, the exact two-platform GHCR image, an
-  immutable four-asset GitHub Release, and an active/latest MCP Registry record. The final
-  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.
-- `v0.1.6` completed the ordered workflow and independent verification across npm, GHCR, the
-  immutable GitHub Release, and the official MCP Registry.
-- `v0.1.7` completed the same ordered workflow with agent-first persistent setup guidance, large
-  focus-tree review scaling, symbolic focus-cost preservation, and complete resource-backed focus
-  validation. Its exact public evidence is retained in
-  [the 0.1.7 completion report](completion-report.md).
-
-`0.2.0` is the current strictly monotonic release candidate. The normal stable-version gate treats
-public `0.1.7` as immutable history; only a strictly newer version may be published. Rerunning or fixing a
-release never authorizes rewriting a tag, package version, image tag, release asset, or Registry
-version.
-
-## Required pre-tag immutability check
-
-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

@@ -1,52 +0,0 @@
-# MCP protocol, SDK, security, and Registry review
-
-Verified again on 2026-07-12 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 and do not require a client to show a confirmation prompt for each call.
-- Long work observes `AbortSignal` and sends monotonic progress only when the client supplies a progress token.
-- Large results are content-addressed resources. Binary reads are bounded/chunkable because resource links defer retrieval but are not a byte-stream transport.
-- Prompts describe domain workflows but grant no permission.
-
-### Write-policy conclusion
-
-MCP separates server-advertised tool metadata from client-host policy. A server can truthfully mark a source-changing tool with `readOnlyHint: false` and `destructiveHint: true`, but it cannot require, suppress, or bypass a host confirmation dialog. The host decides how to present or constrain the call; the server independently enforces its configured workspace, authentication, scope, validation, journaling, and recovery boundaries.
-
-For this server, `writePolicy: "autonomous"` therefore exposes one-call `hoi4.focus_rewrite`, `hoi4.gui_rewrite`, and `hoi4.map_rewrite` tools with destructive annotations. The tools internally plan, validate, journal, apply, and post-validate, restoring original bytes on failure. Transaction tools are not registered in that mode. `writePolicy: "transactions"` remains an optional compatibility surface for the older client-driven review/apply sequence, while `read-only` remains the default.
-
-## Remote security requirements applied
-
-- 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

@@ -1,68 +0,0 @@
-# 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.

package/docs/security.md

@@ -1,145 +0,0 @@
-# Security and threat model
-
-## Protected assets
-
-- external mod source and binary map data;
-- installed game and dependency references;
-- configured write authority, authenticated journals, and exact recovery blobs;
-- generated artifacts that may reveal source details;
-- HTTP credentials and principal/workspace grants.
-
-## Trust boundaries
-
-MCP input, file paths, manifest content, client annotations, session IDs, Origin/Host headers, and remote access tokens are untrusted. Tool annotations are descriptive hints. Prompts are guidance. MCP does not require a confirmation prompt for every destructive tool call. Server-side configuration is authoritative for server access, while the MCP host independently controls its own approval and filesystem policy; neither can override the other.
-
-## Filesystem controls
-
-- Only registered roots are visible.
-- Public paths are relative and canonicalized.
-- Traversal, absolute paths, UNC/device paths, NULs, alternate data streams, ambiguous trailing characters, and device names are rejected.
-- Existing symlinks and junctions are resolved; an escape outside the root is rejected.
-- Artifact shards, transaction journals, blobs, and lock descendants are re-canonicalized before access. A symlink or junction observed in artifact/journal enumeration is rejected.
-- Each write-enabled policy requires an absolute `serverStateRoot` whose existing components are non-linked
-  and whose canonical target does not overlap any source, registration capability,
-  generated-storage root, or runtime-nominated root. Harmless native path-spelling aliases are
-  normalized only after the link check. Its random journal key and protected revision heads are
-  never returned through MCP.
-- Writes target the canonical mod root only. Game, dependency, fixture, and unrelated user files are never writable.
-- Runtime mod registration requires a separate, default-empty `writableRegistrationRoots`
-  capability. A caller cannot relabel a game/dependency path from the read-only
-  `registrationRoots` allowlist as a mod.
-- Artifact URIs are opaque and authorization-checked; filesystem paths are not placed in MCP responses.
-
-These are application checks, not a kernel-enforced filesystem sandbox. The operator must prevent
-hostile operating-system principals from concurrently replacing directories, symlinks, junctions,
-mounts, or files inside registered and generated roots between validation and I/O. Such an actor
-already has direct filesystem authority and is outside the application security boundary. The
-server detects normal stale-source changes and observed link escapes, but does not claim
-race-proof `openat`-style containment or operating-system transaction atomicity against hostile
-concurrent mutation.
-
-## Write controls
-
-Read-only is the default. The recommended `"autonomous"` policy exposes only `hoi4.focus_rewrite`, `hoi4.gui_rewrite`, and `hoi4.map_rewrite` for source mutation. Each call computes the complete affected-file set, validates proposed bytes, persists an authenticated journal and exact before-bytes, rechecks the unexpired principal/workspace binding and source hashes under a workspace lock, applies, rebuilds the index, and post-validates. Invalid proposals do not apply; an application, final-hash, or post-validation failure restores original bytes automatically.
-
-The optional `"transactions"` compatibility policy exposes the older plan/diff/apply/status/rollback tool sequence. It uses the same core journal and failure-recovery path. Autonomous mode intentionally does not register the transaction tools, so it has no client-callable bypass around the one-call rewrite contract.
-
-The autonomous rewrite tools advertise `destructiveHint: true` because a successful call changes mod source. That hint is truthful risk metadata, not a server request to suppress or force a dialog. A client host may prompt for or block the call; the server cannot override it. There is no command-execution field in either mode, and stale or cross-workspace writes fail closed.
-
-Git remains the project-history and intentional-revert layer. It is not required for operational recovery: the journal and exact before-bytes prevent a failed multi-file rewrite from remaining partially applied.
-
-Runtime registration definitions and raw paths are not persisted. The canonical artifact root does
-retain an atomically created ownership claim containing only domain-separated SHA-256 workspace and
-owner bindings. Re-registration restores that binding only for the same canonical workspace and
-runtime principal; malformed, linked, raced, aliased, cross-principal, and cross-workspace claims
-fail closed. A failed journal recovery removes only the in-memory registration, never its persistent
-claim or existing generated data. Statically configured workspaces do not use runtime claims and
-remain shared according to their operator-reviewed principal grants.
-
-Every artifact provenance manifest includes the resolved workspace identity and its configured or
-runtime owner identity in the immutable provenance hash. List, describe, and resource-read paths
-verify both values before returning metadata or bytes. Reusing a physical artifact store through a
-different workspace or owner therefore cannot expose prior evidence; unbound legacy or malformed
-manifests are rejected rather than migrated or deleted implicitly.
-
-Transaction manifests are authenticated with HMAC-SHA-256 over the complete canonical manifest,
-excluding only the authentication tag. The 256-bit random key lives beneath `serverStateRoot`, not
-in a workspace or public configuration value. Protected revision heads prevent replay of an older
-valid manifest. A cache-first crash may reconcile only an authenticated exact next revision; a
-missing head, revision gap, altered expiry/state/failure/rollback field, or recomputed public hash
-fails closed. No HMAC key is derived from public workspace data.
-
-Read-only journal/resource operations never repair protected state. Cache-first successor promotion is
-confined to startup recovery and authorized write paths. Artifact manifests are capped at 1 MiB and
-transaction manifests at 16 MiB before parsing; transaction resource ranges use a bounded verified
-byte cache instead of repeatedly rebuilding the authenticated object.
-
-## HTTP controls
-
-- Every POST, GET, and DELETE request to `/mcp` is authenticated; only standards-required OAuth discovery metadata is public.
-- Present Origin and Host are checked before MCP dispatch. Security-sensitive singleton fields are counted from the raw HTTP header list before Node normalization, so duplicate Host, Authorization, Origin, content metadata, forwarding identity, or MCP session/protocol fields fail closed. Absolute-form request targets must use an allowlisted authority identical to Host.
-- Session IDs are secure random routing identifiers bound to the authenticated principal, an explicit OAuth client when present, the exact bearer credential's SHA-256 identifier, and the non-downgraded scope set; they are not credentials. A token without `client_id` or `azp` is credential-bound rather than being aliased to the subject.
-- Missing, expired, cross-principal, or unknown sessions fail.
-- Connection count, requests per socket, header/request/keep-alive time, JSON body size, admitted concurrency, request rate, session count, event streams, event history, and session lifetime are bounded.
-- Admitted request concurrency is fixed at no more than two; configured body bytes multiplied by
-  concurrency cannot exceed 16 MiB.
-- Static bearer tokens are loopback-only. A non-loopback listener or a non-loopback canonical `publicUrl` (including a loopback listener behind a public reverse proxy) requires HTTPS and OAuth/OIDC JWT signature, issuer, audience, algorithm, expiry, subject, and scope verification.
-- Tokens are accepted only in the Authorization header and are never logged, forwarded, copied into a session, or exposed to MCP handlers. Only a one-way SHA-256 credential identifier is retained for session binding.
-- Protected Resource Metadata is published for OAuth deployments and linked from OAuth `WWW-Authenticate` challenges.
-- Initial 401 challenges identify the baseline scope. A write-scoped tool call made with a read token receives an HTTP 403 `insufficient_scope` challenge naming the baseline plus `hoi4:write`, before JSON-RPC dispatch.
-- Streamable HTTP reserves concurrency before JSON parsing or token verification and applies a socket-address rate bucket before authentication, followed by an independent per-principal bucket after authentication. Host and any present Origin are rejected even earlier. Every `/mcp` POST must advertise unparameterized, positively weighted `application/json` and `text/event-stream` response media types, use the exact `application/json` request media type with an absent or `utf-8` charset, and use no content coding other than identity. GET requires an unparameterized, positively weighted `text/event-stream` range. Bodies are fatal-decoded as UTF-8 and parsed under the raw-wire `maxBodyBytes` ceiling; suffix types, malformed or ambiguous media parameters, encoded entities, replacement-decoded UTF-8, and parameter-only media-type mentions are rejected before SDK dispatch.
-- `trustedProxyAddresses` contains exact IP addresses only and affects only derivation of the pre-auth rate-limit key; it does not enable general forwarded-header trust. `X-Forwarded-For` is ignored unless the direct socket peer exactly matches a configured address (IPv4-mapped IPv6 is normalized). For a trusted peer, a missing or invalid header is rejected and only the first comma-separated address is used.
-- A reverse proxy must be the only network path to a proxied server, terminate TLS, overwrite client-supplied forwarding headers with a validated client IP, preserve Authorization/Origin/Host, and enforce edge connection, header, body, timeout, and rate limits. CIDR ranges, hostnames, and an unverified proxy chain are not inferred by the application.
-- Every session request is reauthenticated and must present the exact credential that initialized the session; another token cannot take over merely because its subject or client claims match. OAuth refresh and scope step-up therefore initialize a new MCP session. Scope authority within a session remains monotonic, and handler-level write-scope checks remain in place as defense in depth.
-
-Session admission counts both active sessions and initializations in progress, globally and per
-principal. Static-token sessions use the configured sliding inactivity lifetime. OAuth session
-expiry is the earlier of that lifetime and the access token's `exp`; an expired token cannot create
-a session. Expiration timers remove sessions at that bound, with access checks, pre-admission
-pruning, and periodic cleanup as fail-closed backstops.
-Resumable GET streams have separate global/per-principal ceilings; once accepted, a long-lived
-stream releases the ordinary short-request concurrency reservation and remains charged to the
-stream ceilings.
-
-Replay history is also bounded: at most 1,000 events per session, the configured per-session byte
-budget, the configured process-wide event-store byte budget, and the session TTL. Per-session
-overflow evicts the oldest history first. If one event cannot fit the per-session or shared byte
-budget, it is not retained for replay; the store does not evict another session's history to make
-room. Closing or expiring a session releases its shared budget.
-
-## Stdio controls
-
-Stdio accepts newline-delimited JSON-RPC frames of at most 16,777,216 bytes, excluding the line-feed
-delimiter. The ceiling is fixed and matches the largest configurable Streamable HTTP JSON body.
-Input is retained in a geometrically grown bounded byte buffer, keeping cumulative copy work
-linear without per-chunk metadata growth. Completed frames use fatal UTF-8 decoding; malformed byte
-sequences are never replaced with U+FFFD or dispatched as JSON-RPC. A malformed UTF-8 frame or a
-frame that crosses the ceiling is refused immediately (for size, including when no newline or
-end-of-input has arrived): the server writes a structured `STDIO_INVALID_UTF8` or
-`STDIO_FRAME_TOO_LARGE` event to stderr, closes that transport, and exits unsuccessfully. The
-rejected payload is never echoed. Protocol responses remain exclusively on stdout; transport and
-startup diagnostics remain exclusively on stderr.
-
-Well-formed UTF-8 frames that fail JSON or JSON-RPC schema validation are not dispatched. Their
-stderr diagnostic has the fixed `STDIO_INVALID_MESSAGE` code and a generic message; it never
-interpolates caller-controlled frame content. A later valid frame may continue on the local
-connection.
-
-## Source and artifact privacy
-
-Stdio inherits the local process user's access but still applies the configured roots. A remote deployment can access only paths mounted and registered on the server; it cannot reach a client computer. Do not mount a home directory or an entire game library when one read-only game root and selected workspaces suffice.
-
-On POSIX, the server enforces mode `0700` on the state root and `0600` on the journal key. Node does
-not provide a portable Windows DACL authoring API, so Windows operators must provision the state
-root ACL for the dedicated server account; the server still rejects a linked/non-regular key and
-inherits that operator ACL. A hostile operating-system principal that can read the key or replace
-state-root entries remains outside the documented filesystem trust boundary.
-
-Raw installed-game or dependency sprite, font, and bitmap files are never registered as downloadable resources. Structured JSON evidence strips embedded raster and glyph payloads, retaining only source-linked hashes, paths, frame and dimension metadata. Composite SVG/PNG reviews may contain processed frames or glyphs required to inspect the requested render, but remain generated, authorization-checked workspace evidence rather than raw asset-file resources. Rewrite and reviewed-transaction evidence may contain authorized mod-source before/proposed text and diffs; every artifact remains bound to the workspace principal.
-
-The runtime sends no telemetry or analytics. Its only outbound network request is OAuth JWT-key retrieval from the administrator-configured JWKS endpoint; stdio and static-token loopback deployments require no runtime network access.
-
-The product never launches, automates, controls, or captures Hearts of Iron IV. Every preview is
-an offline tool-generated render, not a game screenshot or evidence of in-engine behavior.
-
-Vulnerabilities should be reported through GitHub private vulnerability reporting as described in the root [security policy](../SECURITY.md).