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

package/docs/security.md

@@ -0,0 +1,139 @@
+# Security and threat model
+
+## Protected assets
+
+- external mod source and binary map data;
+- installed game and dependency references;
+- transaction approval intent and rollback blobs;
+- generated artifacts that may reveal source details;
+- HTTP credentials and principal/workspace grants.
+
+## Trust boundaries
+
+MCP input, file paths, manifest content, client annotations, session IDs, Origin/Host headers, and remote access tokens are untrusted. Tool annotations are descriptive hints. Prompts are guidance. Server-side policy is authoritative.
+
+## 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.
+- Transaction mode 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. A write requires global and workspace enablement, a validated dry run, a persisted transaction, exact plan hash, separate apply call, unexpired principal/workspace binding, unchanged source hashes, and a workspace lock. There is no command execution field. Stale apply and rollback operations fail closed.
+
+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 transaction 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. 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).

package/docs/self-hosting.md

@@ -0,0 +1,168 @@
+# Self-hosting Streamable HTTP
+
+The server exposes one stateful MCP endpoint at `/mcp` for POST and GET, plus DELETE session termination. It does not provide legacy SSE-only transport.
+
+## Loopback
+
+Set a random token of at least 32 characters in the environment named by config:
+
+```bash
+export HOI4_AGENT_HTTP_TOKEN='replace-with-a-random-secret'
+HOI4_AGENT_CONFIG=/srv/hoi4/config.json hoi4-agent-tools-http
+```
+
+Keep `host` as `127.0.0.1`. The client sends `Authorization: Bearer ...`. Present origins still need to match `allowedOrigins`.
+
+The HTTP process refuses to start if a configured token environment variable is missing, shorter
+than 32 characters, or has the same secret value as another configured token. Static tokens and
+OAuth are mutually exclusive deployment modes.
+
+## Public/team deployment
+
+Public mode—either a non-loopback listener or a non-loopback `publicUrl` in front of a loopback/private listener—refuses to start unless:
+
+- `publicUrl` is an HTTPS origin or exact `/mcp` endpoint and contains no credentials, path prefix, query, or fragment;
+- OAuth/OIDC JWT validation is configured;
+- the OAuth issuer, JWKS, and every authorization-server URL use HTTPS;
+- at least one origin is allowlisted;
+- principal/workspace grants are configured.
+
+```json
+{
+  "http": {
+    "host": "0.0.0.0",
+    "port": 3210,
+    "publicUrl": "https://mcp.example.test",
+    "allowedOrigins": ["https://agent.example.test"],
+    "trustedProxyAddresses": ["10.20.0.5"],
+    "tokens": [],
+    "principals": [
+      { "principal": "user-subject", "workspaceIds": ["example"], "allowRegistration": false }
+    ],
+    "oauth": {
+      "issuer": "https://issuer.example.test/",
+      "jwksUri": "https://issuer.example.test/.well-known/jwks.json",
+      "audience": "https://mcp.example.test/mcp",
+      "authorizationServers": ["https://issuer.example.test/"],
+      "requiredScopes": ["hoi4:read"],
+      "algorithms": ["RS256"]
+    }
+  }
+}
+```
+
+The server is an OAuth resource server, not an authorization server. Protected Resource Metadata is served at the standard well-known paths and its endpoint-specific URL is included in 401 and insufficient-scope 403 challenges. Baseline access uses the configured `requiredScopes`; transaction planning, registration, apply, and rollback additionally require `hoi4:write`. Each MCP session is bound to the exact bearer credential that initialized it, not only to mutable subject/client claims. A refreshed or step-up token must initialize a new MCP session; the previous session remains bound to its original credential and expires no later than that credential's `exp`. The server retains only a SHA-256 credential identifier, never the raw token. Static-token sessions keep the configured sliding inactivity lifetime. Terminate TLS at a trusted reverse proxy, preserve Authorization/Origin/Host headers, and do not make a session ID a bearer credential.
+
+### Reverse-proxy boundary
+
+`trustedProxyAddresses` is not a general proxy switch; it affects only the pre-auth rate-limit
+address and does not trust forwarded host or protocol metadata. Each entry is one exact IPv4 or
+IPv6 address as it appears for the direct socket peer; CIDR ranges and hostnames are rejected. An
+IPv4-mapped IPv6 peer is normalized to IPv4 for matching. When the peer is not an exact match, the
+application ignores `X-Forwarded-For` and rate-limits the socket address. When it is a match, the
+application requires a valid `X-Forwarded-For` value and uses its first comma-separated IP.
+
+The edge proxy must therefore:
+
+- be the only network path to the server port, enforced by a private bind/network and firewall;
+- terminate TLS for the HTTPS `publicUrl`;
+- remove any client-supplied forwarding chain and set the first `X-Forwarded-For` value to a
+  validated originating client IP;
+- preserve the bearer `Authorization` header, the original `Origin`, and a `Host` accepted by the
+  configured bind host or `publicUrl`;
+- enforce its own connection, header-size, body-size, header/request/idle timeout, and pre-auth
+  rate ceilings before forwarding.
+
+Do not configure a load-balancer subnet and expect range matching, and do not allow clients to
+bypass the named proxy. For multiple proxy hops, use an edge-controlled normalization point that
+delivers one trustworthy first address to the directly connected trusted peer.
+
+### Admission, sessions, and streams
+
+Before authentication, the application enforces Node connection/request timeouts and socket
+ceilings, then reserves one `maxConcurrentRequests` slot and applies a fixed-minute
+`requestsPerMinute` bucket to the resolved client address. Every POST must advertise exact,
+unparameterized positive-quality `application/json` and `text/event-stream` response ranges, use exact
+`application/json` request media with an absent or `utf-8` charset, and use identity content
+encoding. GET must advertise exact positive-quality `text/event-stream`. JSON is fatal-decoded as
+UTF-8 and parsed under the raw-wire `maxBodyBytes` ceiling before SDK dispatch. Suffix types,
+duplicate/malformed parameters, encoded entities, invalid UTF-8, and parameter-only media mentions
+are rejected.
+
+Before those checks, the server counts security-sensitive fields in the raw header list rather
+than trusting Node's first-value normalization. Duplicate Host, Authorization, Origin,
+Content-Type, Content-Encoding, forwarding identity, or MCP session/protocol fields are rejected.
+For an absolute-form request target, its allowlisted authority must exactly match Host; an allowed
+Host cannot conceal an untrusted request-target authority.
+After authentication, a separate fixed-minute bucket is applied to the principal. Host and any
+present Origin are checked before admission. These in-process controls complement, rather than
+replace, the edge limits above.
+
+`maxConcurrentRequests` cannot exceed two, and its product with `maxBodyBytes` cannot exceed
+16 MiB. The fixed concurrency ceiling also bounds simultaneous offline render allocations; raise
+edge capacity by running isolated server instances, not by removing the per-process safety bound.
+
+Session initialization is refused when either the global `maxSessions` or
+`maxSessionsPerPrincipal` count (including initializations in progress) is full. Resumable GET
+streams use `maxEventStreams` and `maxEventStreamsPerPrincipal`; an accepted long-lived stream
+releases the ordinary request-concurrency slot. Each session retains at most 1,000 replay events,
+`maxSessionEventBytes`, and the shared `maxEventStoreBytes`, for no longer than
+`sessionTtlSeconds`. Old per-session history is evicted first. A new event that cannot fit the
+shared budget is not retained for replay and does not evict another session's history.
+
+Principal grants isolate tool, resource, session, and transaction access within one deployment. Run separate least-privilege server instances or containers for mutually distrustful teams or operating-system trust domains; do not treat application-level grants as an OS sandbox.
+
+Runtime registration has two operator capabilities. `registrationRoots` permits read-only source
+selection. A caller-declared mod root additionally must be under the default-empty
+`writableRegistrationRoots` list, even when source apply is disabled, because mod registration
+creates generated storage. Never place a game or dependency directory under a writable
+registration root. Granting `allowRegistration` exposes every otherwise-unclaimed source beneath
+these capability roots to that principal; prefer static registrations or separate instances for
+mutually distrustful users.
+
+Runtime artifact storage must support same-volume hard links so the server can create persistent
+owner claims without replacement races. Transaction deployments additionally require an isolated,
+persistent `serverStateRoot` on a filesystem with hard-link and atomic-replacement support. Do not
+place it beneath any source, capability, artifact, cache, fixture, or `storageRoots` directory.
+
+## Container
+
+```bash
+docker build -t hoi4-agent-tools:0.1.3 .
+docker run --read-only --rm -p 127.0.0.1:3210:3210 \
+  -e HOI4_AGENT_CONFIG=/config/config.json \
+  -v /srv/hoi4/config:/config:ro \
+  -v /srv/hoi4/game:/srv/hoi4/game:ro \
+  -v /srv/hoi4/workspaces:/srv/hoi4/workspaces \
+  -v /var/lib/hoi4-agent-tools:/var/lib/hoi4-agent-tools \
+  -v /var/lib/hoi4-agent-tools-state:/var/lib/hoi4-agent-tools-state \
+  hoi4-agent-tools:0.1.3
+```
+
+Port publishing reaches the container through a non-loopback interface. The mounted configuration
+for this form must therefore use the public/team OAuth policy above: bind `0.0.0.0`, declare the
+canonical HTTPS `publicUrl`, allowlist the coding-agent origin, and validate OAuth access tokens.
+Terminate TLS at the configured reverse proxy. Mapping the host port only to `127.0.0.1` limits host
+exposure but does not turn the container-side listener into loopback, so it does not permit static
+bearer tokens.
+
+When writes are enabled, set `serverStateRoot` to `/var/lib/hoi4-agent-tools-state` in this example.
+Keep that mount persistent across restarts and protect it for the dedicated server account. It is a
+separate mount because a state root may not overlap `/var/lib/hoi4-agent-tools` when that path is a
+configured generated-storage capability.
+
+On Linux, a local-only static-token deployment may instead use `--network host` with the configured
+listener kept at `127.0.0.1`; do not combine that mode with `-p`. Host networking changes the
+container isolation boundary and is not portable to every Docker host, so review it explicitly
+before use.
+
+Do not mount a developer's home directory. A remote server sees only server-side mounts; the MCP client does not tunnel local files.
+
+If a configured workspace has `kind: "game"` or `kind: "dependency"`, mount a separate writable
+operator-owned generated-data directory, list its parent in `storageRoots`, and set both
+`artifactRoot` and `cacheRoot` beneath it. Never make the installed-game or dependency source
+mount writable merely to hold generated state. Mod workspaces may instead use their confined
+`<mod>/.hoi4-agent/artifacts` and `<mod>/.hoi4-agent/cache` defaults.
+
+The server does not launch or capture Hearts of Iron IV. A self-hosted deployment needs filesystem
+access only; it does not need a desktop session, Steam automation, or game-process permissions.

package/docs/testing.md

@@ -0,0 +1,43 @@
+# Testing and fixtures
+
+```bash
+npm ci
+npm run test
+npm run test:coverage
+npm run fixtures:check
+npm run build
+npm run inspector
+npm run check
+```
+
+## Portable CI
+
+CI owns all inputs:
+
+- a 255-focus workspace with ten route families, exclusions, convergence, planner-sidecar hidden/crisis/shared-support metadata, relative/pinned/automatic positions, a real `continuous_focus_palette`, active localisation, a two-frame sprite texture, and resolved synthetic references;
+- a 170-element five-tab GUI with a dynamic list, target cards, meters, distinct frame animation, modal, all required states, licensed fixture font, and defect variants;
+- a nontrivial 24-bit BMP mini-world with islands, exact split masks/polygons, state/region/network/adjacency data, and invalid variants.
+
+Suites cover parser byte round trips, encodings, property cases, source locations, overlay/load order, custom focus roots, exact referenced-texture scanning, strict schemas, deterministic goldens, generated-source maps, planning-sidecar enrichment, image comparisons, font metrics, bitmap diffs, transaction fault/recovery, path security, cross-workspace isolation, stdio, Streamable HTTP, auth/origin/session limits, resource/prompt/tool discovery, package installation, Registry schema, and end-to-end agent workflows.
+
+## Local integration
+
+Set paths explicitly; tests are read-only:
+
+```bash
+HOI4_GAME_ROOT=/path/to/game \
+HOI4_EXTERNAL_MOD_ROOT=/path/to/mod \
+npm run test:local
+```
+
+Optionally set `HOI4_DEPENDENCY_ROOTS` to dependency roots separated by the operating system path delimiter (`;` on Windows, `:` on POSIX).
+
+Three local tests parse and deterministically render a large vanilla focus tree, build and render a current GUI/GFX/font source graph, and scan/render/store the current province map with state, coastline, supply-node, and railway data against one external mod. Generated caches and artifacts stay in a temporary directory that is removed after the suite; the external roots remain read-only, no files are copied into the repository, and the game is never launched.
+
+`npm run test:local` uses a project-owned validation runner around the standalone local Vitest configuration. It routes only `tests/local`, preserves ordinary Vitest failure codes, and independently requires the exact focus, GUI, and map qualification workflows to finish. The command fails when paths are absent and the tests skip, when a required workflow is not collected, when a worker terminates or runs out of memory, when Vitest reports any unhandled error, or when the reporter lifecycle is incomplete. A zero Vitest exit code alone is therefore not treated as success.
+
+## Performance
+
+Run the explicit, non-CI benchmark with `npm run benchmark`. It records cold/warm shared scans, the 255-node focus layout/render, the 150+ element GUI state gallery, and a full cross-root synthetic map scan plus all base-layer renders. Cache keys include content hashes; a deterministic unit test mutates content while preserving size and modification time to prove safe invalidation.
+
+Current measurements, methodology, and rerun instructions are in [performance.md](performance.md).

package/docs/third-party-notices.md

@@ -0,0 +1,11 @@
+# Third-party notices
+
+## Roboto
+
+HOI4 Agent Tools depends on `@fontsource-variable/roboto` version 5.2.10 for deterministic, host-independent artifact labels and the project-owned synthetic BMFont fixture.
+
+Copyright 2011 The Roboto Project Authors (<https://github.com/googlefonts/roboto-classic>). Roboto-Italic[wdth,wght].ttf: Copyright 2011 The Roboto Project Authors (<https://github.com/googlefonts/roboto-classic>).
+
+Roboto is licensed under the SIL Open Font License, Version 1.1 (`OFL-1.1`). The complete license text is distributed as `LICENSE` in the installed `@fontsource-variable/roboto` package. The font package is pinned in `package.json` and `package-lock.json`; generated SVG/PNG documents may contain derived glyph outlines or pixels as permitted by the OFL.
+
+The application source remains licensed under Apache-2.0 as stated in the repository [LICENSE](../LICENSE). Third-party components retain their respective licenses.

package/docs/transactions.md

@@ -0,0 +1,162 @@
+# Transactions, diffs, and rollback
+
+## Plan
+
+A domain `plan_changes`/`map_plan` call calculates every affected source and binary file before writing. Proposed bytes are validated in memory. The plan persists content-addressed before/after blobs and produces source, binary, pixel, and rendered comparison artifacts where applicable.
+
+Every proposed source target is resolved with write access restricted to the workspace's canonical
+mod root. Transaction calls cannot write the game, a dependency, a fixture, artifact storage,
+cache storage, or the reserved `.hoi4-agent` subtree as mod source.
+
+The transaction API requires both validation phases: planning must return at least one explicit in-memory check, and apply must return at least one explicit post-write check. Missing or empty callbacks fail with `TRANSACTION_DRY_RUN_VALIDATION_REQUIRED` or `TRANSACTION_POST_VALIDATION_REQUIRED`; callers cannot opt out through the typed core API. Diff artifacts are committed as one batch with the journal only after the planning validator returns structurally valid results. A rejected validator or journal admission leaves artifact inventory unchanged. A completed dry run whose explicit checks fail remains reviewable as a blocked plan and cannot be applied.
+
+Text diffs use an exact deterministic algorithm with a fixed memory bound and cancellation checks. If an exact diff would exceed the bound, planning stops with `DIFF_COMPLEXITY_LIMIT`; the server does not substitute a truncated, approximate, or misleading diff.
+
+The returned transaction ID is not approval. Review:
+
+- operations and unresolved choices;
+- affected file list;
+- source and visual diff resources;
+- diagnostic locations and validation gates;
+- expiry and plan hash.
+
+Plan and mutation tool results keep only a bounded path sample plus the authenticated transaction
+manifest resource. Review artifacts remain listed in that manifest rather than being duplicated as
+hundreds of inline resource links. `hoi4.transaction_diff` returns at most 20 files, operation
+summaries, and artifact links per page; follow every `nextCursor` until it is absent. Cursors are
+bound to the immutable plan hash and fail if reused for a different transaction. Inline validation
+contains at most five checks with an explicit truncation diagnostic; the manifest is the complete
+validation record.
+
+Focus plans include both the edited Clausewitz source and its adjacent `.focus-plan.json` design sidecar in one transaction. The manifest also retains the proposed generated-source map and sidecar artifacts through apply and rollback so each generated focus range remains traceable to its planning/source node.
+
+## Apply
+
+Call `hoi4.transaction_apply` separately with `workspaceId`, `transactionId`, and the exact 64-character `expectedPlanHash`. The server rejects a different principal/workspace, changed roots, failed dry run, expiry, reused state, or any changed before-hash.
+
+The persisted immutable plan payload is recomputed against `planHash` whenever a manifest is
+loaded. A recomputable integrity hash remains useful for deterministic diagnostics, but is never an
+authorization boundary. Every exact-version manifest also carries an HMAC-SHA-256 tag over the
+complete canonical payload except that tag itself, including expiry, state, applied files, failure,
+rollback status, operations, plan, diagnostics, and validation. The random 256-bit key is created
+atomically beneath the non-overlapping operator `serverStateRoot`; it is never derived from public
+workspace data or exposed through MCP.
+
+The same protected state stores one authenticated latest-revision head per admitted journal. An
+older valid manifest is rejected as replay. Manifest replacement is cache-first and caller state is
+updated only after persistence: a crash between cache replacement and protected-head commit may
+reconcile only an HMAC-valid exact `+1` successor. Missing heads, gaps, conflicting same revisions,
+and forged successors fail closed. Successor creation is durable before older revision-head files
+are removed, so an old-head cleanup failure does not break loading.
+
+Ordinary status, diff, and resource reads are pure: they accept only an exact protected head and
+never promote state. An authenticated cache-first exact successor reports
+`TRANSACTION_HEAD_RECONCILIATION_REQUIRED` until startup recovery or an authorized write path
+performs the narrowly allowed reconciliation.
+
+Unauthenticated journals from an older deployment are deliberately not auto-migrated. They remain
+fail-closed for operator review because no server-held secret can prove their origin. Archive or
+remove them explicitly before reclaiming their quota; do not manufacture an authentication tag.
+
+During apply the server:
+
+1. takes the exclusive workspace lock;
+2. rechecks every precondition;
+3. writes and flushes same-volume staged files;
+4. journals backups and replacements in deterministic order;
+5. rebuilds the shared index;
+6. runs post-write validation;
+7. removes temporary backups only after success.
+
+The workspace lock serializes cooperating server processes that use the same cache. Before each
+replacement, the current source hash is checked again; after post-write validation, every result
+hash is checked. These checks detect stale ordinary edits, but they are not a race-proof
+filesystem sandbox against a hostile operating-system principal.
+
+## Failure and recovery
+
+Any error starts rollback in reverse file order. Existing backups or persisted blobs restore exact original bytes, including BMP headers and padding. Restores stage and flush bytes before atomically renaming over the current target; they never unlink an existing target before a blob replacement. A durable `rolling_back` journal can also resume the legacy interrupted state where that target is already missing, but only after verifying its persisted before-blob. Startup scans unfinished journals and completes rollback before accepting a new write.
+
+Runtime registration definitions are not persisted, but their hash-only ownership claims are.
+Their unfinished journals are recovered only after the same principal re-registers an exactly
+matching canonical workspace and the persistent claim is verified, before status or write access
+is returned to the caller.
+
+Lock owners record the host, process, server instance, and process start time. A dead owner on the same host is cleared during startup recovery; an ownerless acquisition lock is cleared only after a 30-second grace period. A live local owner and every different- or unknown-host owner remain authoritative. Automatic cross-host crash recovery is intentionally unsupported: deployments sharing a workspace/cache filesystem across hosts must provide single-writer orchestration and operator-confirmed recovery rather than relying on local PID evidence.
+
+Multi-file atomicity is logical and recoverable, not an operating-system transaction. External
+processes can briefly observe replacement steps. Under an operator-controlled filesystem, success
+is returned only after post-write validation and final result-hash verification. A principal able
+to concurrently replace directories, links, mounts, or files outside the transaction lock already
+has direct filesystem authority and is outside the application security boundary; the server does
+not claim race-proof atomicity against that actor.
+
+## Journal retention and quotas
+
+Transaction journals live under `<cacheRoot>/transactions`. The configurable defaults are 128
+journals and 536,870,912 bytes per workspace cache. A plan must also fit its own rollback blobs,
+serialized manifest, and replacement-work estimate beneath the byte ceiling. The plan is refused
+with `TRANSACTION_JOURNAL_LIMIT` before a usable journal is committed if either the count, stored
+bytes, or single-plan work budget would be exceeded. No smaller or truncated rollback journal is
+substituted.
+
+One manifest is bounded to 1,000 changed files, 1,000 operations, 10,000 read dependencies, 100
+validation checks, 100 diagnostics, 512 artifacts, and 1,000 applied-file entries. Inputs over a
+count limit or the existing serialized journal/work-byte budget are rejected, never truncated.
+Post-write validation is preflighted against the combined check and diagnostic counts before the
+manifest is mutated. A 100+1 overflow triggers exact rollback while preserving a schema-bounded
+authenticated terminal journal.
+
+Before committing a new plan, the server performs narrowly scoped retention cleanup:
+
+- expired `planned` and `rolled_back` journals are removed by deleting their protected head first
+  and cache journal second. A crash or later reintroduction of the cache copy then fails for a
+  missing head rather than replaying;
+- an incomplete transaction directory with no manifest is removed only after it is older than
+  `transactionTtlSeconds`;
+- `applied`, `failed`, `applying`, and `rolling_back` journals are not quota-evicted. Interrupted
+  states are handled by recovery instead;
+- malformed, integrity-failing, or otherwise unreadable journals are retained and continue to
+  count against quota rather than being guessed safe to delete.
+
+Only the latest protected revision is retained per live journal. Cache-without-head planned or
+rolled-back remnants from an interrupted admission/prune are authenticated and removed safely;
+active or unauthenticated remnants remain fail-closed. Head-without-cache remnants are removed
+while reconciling a workspace. Protected state therefore remains bounded by admitted cache
+journals rather than growing with revision or expiry churn.
+
+After that cleanup, the server deterministically accepts the complete plan or refuses it. It does
+not evict a valid applied/failed journal to make room. Operators who intentionally remove terminal
+journals also remove their status, audit evidence, persisted blobs, and any later explicit rollback
+ability.
+
+Diff artifact creation and journal admission share a failure boundary. If the journal count or byte
+check rejects a plan, the artifact store removes only content and provenance files created for that
+attempt; artifact inventory is unchanged and any identical artifact retained by another operation
+remains addressable.
+
+## Explicit rollback
+
+`hoi4.transaction_rollback` is available after successful apply. It first verifies that every current file still has the transaction's after-hash. An external edit makes rollback stale, protecting later work from being overwritten.
+
+Rollback accepts cancellation through its path/hash verification preflight. Once byte restoration
+starts, restore plus authenticated journal advancement is deliberately non-cancellable so a client
+disconnect cannot strand a partial rollback.
+
+Status/manifest reads and runtime recovery enumeration accept cancellation around filesystem
+reads, JSON/schema validation, and protected-head verification. Once recovery begins restoring
+source bytes, it follows the same non-cancellable critical-phase rule.
+
+Transaction manifests are readable as:
+
+```text
+hoi4-agent://workspace/{workspaceId}/transaction/{transactionId}
+```
+
+Manifest resources use the same 1 MiB `offset`/`length` byte ranges as artifacts. A complete
+strict-UTF-8 manifest may be returned as MCP `text`; every partial range is a base64 `blob`.
+Advance `offset` by the decoded byte count and continue until a chunk is shorter than the requested
+length. Transaction manifests have a separate fixed 16 MiB serialized ceiling, independent of the
+larger rollback-blob journal budget.
+Canonical resource bytes are cached by stable file identity and protected revision, with at most
+eight entries and 16 MiB total, so later ranges do not repeatedly rebuild a large manifest object.

package/docs/troubleshooting.md

@@ -0,0 +1,46 @@
+# Troubleshooting
+
+## Configuration not found
+
+Set `HOI4_AGENT_CONFIG` to an absolute path or add `--config PATH` to the server command. Run `hoi4-agent-tools-setup --diagnose --config PATH`.
+
+## Workspace/path rejected
+
+Use a registered workspace-relative path. Confirm the canonical root is beneath `registrationRoots`; runtime mods also require the separate `writableRegistrationRoots` capability. Check for junctions/symlinks, parent segments, device names, trailing dots/spaces, or alternate data streams. Game and dependencies are intentionally read-only.
+
+## Apply reports stale
+
+The source changed after planning. Do not reuse the transaction. Scan and produce a new dry run so review evidence matches current files.
+
+## Transaction state rejected
+
+Transaction mode requires an absolute, persistent `serverStateRoot` that does not overlap any
+source or generated-storage capability. Run setup with `--enable-writes --server-state ROOT`, then
+run `--diagnose`. Preserve the same private state root across restarts. A missing key, malformed or
+replayed head, unauthenticated legacy manifest, or cache/head revision conflict fails closed; review
+and archive the affected journal/state evidence instead of regenerating a public hash or tag.
+
+## Runtime registration conflicts after restart
+
+The artifact root already has a hash-only runtime owner claim. Register the exact canonical
+workspace as the same principal, or stop the server and perform an explicit operator-reviewed data
+reassignment. Do not delete the claim alone or expect a renamed workspace ID, path alias, or second
+principal to inherit the existing evidence.
+
+## Render has missing/unsupported fields
+
+Read the fidelity resource. Register the correct game/dependency root and supply a scenario value or asset. Unsupported fields stay raw; do not treat an approximation as engine evidence.
+
+## HTTP refuses to start
+
+Authentication is mandatory. Static token secrets must be at least 32 characters and are loopback-only. Public binding requires HTTPS `publicUrl`, OAuth settings, allowed origins, and principal grants.
+
+## HTTP returns 401/403/404
+
+- 401: missing/invalid/expired token or wrong issuer/audience.
+- 403: origin, scope, principal/workspace, or cross-principal session rejected.
+- 404 with session ID: session is unknown or expired; initialize a new MCP session.
+
+## Inspector
+
+Build first, then run `npm run inspector`. The Inspector proxy is a local debugging surface; do not expose it unauthenticated.