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

package/docs/adr/0011-http-security.md

@@ -0,0 +1,16 @@
+# ADR 0011: Authenticated, origin-checked Streamable HTTP
+
+- Status: accepted
+- Date: 2026-07-10
+
+## Decision
+
+HTTP binds to `127.0.0.1` by default. Every request is authenticated. Loopback deployments may use long static bearer tokens loaded from environment variables. Non-loopback deployment requires an HTTPS public resource URL and JWT verification against configured OAuth/OIDC issuer, JWKS, audience, algorithms, expiry, and scopes. Protected-resource metadata is published and linked from Bearer challenges. Write-scoped tool calls are rejected at the transport with an MCP 2025-11-25 step-up challenge while the corresponding handlers independently enforce the same scope. Present origins are allowlisted, Host is validated, sessions use cryptographically secure IDs bound to principals, clients, and a monotonic scope set, and body/rate/concurrency/session limits are enforced.
+
+## Rationale
+
+MCP sessions are routing state, not authentication. OAuth resource-server validation and principal-to-workspace grants prevent token passthrough, confused-deputy behavior, and cross-user workspace access. Origin and Host checks address DNS rebinding and browser-origin attacks.
+
+## Consequences
+
+The server does not implement an authorization server. Operators configure a compatible issuer or keep HTTP on loopback. Stdio does not use MCP OAuth and inherits local process permissions plus the same workspace policy.

package/docs/adr/README.md

@@ -0,0 +1,13 @@
+# Architecture decisions
+
+1. [Runtime and language](0001-runtime-and-language.md)
+2. [Lossless source model](0002-lossless-source-model.md)
+3. [Image and font codecs](0003-image-and-font-codecs.md)
+4. [Focus layout](0004-focus-layout.md)
+5. [Offline rendering](0005-offline-rendering.md)
+6. [MCP SDK and protocol](0006-mcp-sdk-and-protocol.md)
+7. [Storage and transactions](0007-storage-and-transactions.md)
+8. [Test strategy](0008-test-strategy.md)
+9. [Packaging and Registry](0009-packaging-and-registry.md)
+10. [Unsupported/refusal policy](0010-unsupported-and-refusal-policy.md)
+11. [HTTP security](0011-http-security.md)

package/docs/architecture.md

@@ -0,0 +1,60 @@
+# Architecture
+
+All external behavior enters through MCP and calls typed domain services. Transport code validates protocol and authorization; it does not parse source, lay out graphs, render images, or write files.
+
+In this documentation, “read-only” scan, lint, layout, and render operations mean that registered HOI4 source bytes are never changed. MCP `readOnlyHint` follows the protocol's broader environmental-mutation meaning: an operation that creates content-addressed evidence under an allowlisted generated-artifact root advertises `readOnlyHint: false`, even though it cannot edit game or mod source.
+
+```text
+MCP tools/resources/prompts
+          │
+          ▼
+focus / gui / map services
+          │
+          ▼
+workspace resolver ─ source CST ─ symbol/reference index
+          │                 │
+          ├─ diagnostics ───┤
+          ├─ artifact store ┤
+          └─ transaction journal / diffs / rollback
+```
+
+## Workspace overlay
+
+A workspace combines a mod root, an optional installed-game reference root, ordered dependency roots, owner-scoped `replace_path` declarations, conventional subsystem roots, an artifact root, cache root, and optional fixture root. File traversal is stable. Same-relative-path files are shadowed by higher load order; each mod or dependency replacement declaration hides its subtree only in lower-precedence roots.
+
+Paths are canonicalized through existing ancestors. Public operations accept relative paths only and reject traversal, absolute/device/UNC paths, alternate data streams, Windows device names, and symlink or junction escapes. Game and dependency roots are immutable.
+
+## Source model
+
+The lexer retains original bytes and every token: whitespace, comments, strings, atoms, operators, braces, and invalid ranges. The CST retains duplicate keys and ordered blocks. Semantic readers build focus, GUI, or map views over CST ranges. Targeted replacements splice the original decoded text and encode with the original UTF-8 BOM, UTF-8, or Windows-1252 mode. No-change serialization returns original bytes.
+
+Malformed or unrepresentable content blocks rewriting. Unknown constructs remain raw source, not guessed fields.
+
+## Shared index
+
+`CoreEngine.scan` creates the authoritative `SymbolIndex` for an exact file snapshot. Focus consumes it directly; Scripted GUI receives that same index when building its connected source graph; Agent Nudger attaches it as `MapWorkspaceIndex.sharedIndex` and layers raster/network semantics over it. Proposed-file graphs rebuild through the shared index service rather than a domain parser authority.
+
+The index connects tree/focus IDs, sprites/textures, GUI elements, scripted GUI entries, localisation, state/province IDs and colors, strategic regions, adjacencies, supply nodes, railways, and cross-file references. Definitions retain load order, locations, collision state, and override evidence. Province definitions are resolved from each source root's own `default.map` selector, with lower partial roots inheriting the active selector name.
+
+Large binary rasters and translation catalogs are selected lazily rather than retained wholesale. Agent Nudger follows the active `default.map` province-bitmap selector. The shared index uses `l_english`, while GUI scenario operations add every explicitly requested language. This narrows scan breadth without changing source precedence or the lossless representation of any selected file.
+
+## Determinism
+
+Canonical JSON sorts keys with a locale-independent total UTF-16 code-unit order, traversal uses stable path ordering, layout tie-breaking is fixed, and artifact names are content hashes. Render profiles include source/asset/font hashes and all scenario geometry. Timestamps, host paths, locale collation, random IDs, and time zones are excluded from hashed artifacts.
+
+## Artifacts and transactions
+
+Generated evidence is content-addressed below `.hoi4-agent/artifacts`. Artifact manifests bind their
+immutable provenance address to a hash-only canonical workspace and configured/runtime owner
+identity. Runtime-generated stores also carry an atomic persistent owner claim, while statically
+configured workspaces retain one shared operator identity for their explicit grants.
+
+A transaction includes the complete affected-file set, before/after hashes and blobs, operation
+provenance, validation, source/binary/visual diffs, expiry, principal, workspace/root fingerprint,
+and plan hash. Its complete mutable journal is HMAC-authenticated by a random key beneath the
+isolated `serverStateRoot`; a protected latest-revision head prevents replay and bounds state to one
+head per admitted cache journal.
+
+Apply acquires one workspace write lock, rechecks preconditions, stages files on the same volume, journals deterministic replacements, rebuilds the affected index, and post-validates. Failure and startup recovery restore original blobs. This is recoverable logical atomicity; another process can briefly observe a replacement sequence.
+
+Detailed decisions are recorded in [ADRs](adr/README.md).

package/docs/artifacts.md

@@ -0,0 +1,133 @@
+# Artifact resources
+
+Tools return compact summaries and links. Content is stored by SHA-256 under the workspace's configured artifact root and exposed through an authorization-checked URI:
+
+```text
+hoi4-agent://workspace/{workspaceId}/artifact/{sha256}/{provenanceHash}/{name}
+```
+
+Each version-2 manifest records name, MIME type, byte size, content hash, artifact kind,
+tool/schema version, SHA-256 source hashes, render profile, domain metadata, and hash-only bindings
+for the resolved workspace and its configured or runtime owner. Filesystem paths and raw principals
+are not exposed. Missing/create/delete states belong in provenance metadata, never sentinel values
+inside the source-hash map.
+
+Very broad domain inventories retain a deterministic path/hash sample capped at 256 entries and
+128 KiB in the manifest, plus a count and a SHA-256 commitment over every length-prefixed sorted
+path/hash pair. This policy applies uniformly to project, focus, GUI, and map evidence. Complete
+inventories remain in the structured artifact content: project diagnostics use their exact `files`
+inventory, while focus, GUI, and map JSON evidence records exact source hashes. Binary and HTML
+review artifacts carry the same bounded, digest-backed provenance and are paired with the exact
+structured evidence for their bundle. Bounding a manifest therefore does not drop source evidence.
+The inventory commitment uses the versioned `sha256-length-prefixed-path-digest-v1` algorithm
+recorded in metadata.
+
+The manifest is immutable for a given content hash, provenance hash, and artifact name. Repeating the same bytes, name, and provenance is idempotent. Identical content produced from a different source revision receives a distinct provenance hash and URI while reusing the same content-addressed bytes, so earlier evidence is never rewritten or ambiguously relabelled.
+
+Artifact names ending in `.manifest.json`, under an ASCII case-insensitive comparison, are reserved
+for store metadata and rejected. This rule is identical on case-sensitive and case-insensitive
+filesystems, so content can never be mistaken for an inventory manifest.
+
+The workspace and owner bindings participate in the provenance hash and are checked by list,
+describe, and resource reads. A store reused by another workspace ID, canonical root topology, or
+runtime principal cannot enumerate or read the older manifests. Statically configured workspaces
+derive one shared operator identity, so all explicitly granted principals retain their intended
+access. Legacy unbound manifests and malformed/conflicting manifests fail closed; the server does
+not delete or relabel them automatically.
+
+Resource reads are limited to 1 MiB per request and support `offset` and `length` query parameters for large artifacts. Integrity verification streams the complete artifact through a fixed-size hash buffer while retaining only the requested range, so chunking also bounds payload memory. Only a complete payload that round-trips as strict UTF-8 may return MCP `text`. Every partial range, invalid UTF-8 payload, image, and other binary returns an MCP base64 `blob`, preserving exact bytes even when a range splits a code point. Clients advance `offset` by the decoded byte count and continue until a chunk is shorter than the requested length; the same rule applies to provenance-manifest resources.
+
+Some complete logical evidence, notably an installed workspace's GUI source graph, can legitimately
+be larger than `artifactMaxSingleBytes`. Callers that opt into byte-exact logical storage receive a
+normal artifact when the payload fits. An oversized payload instead returns one small canonical
+JSON index named `*.chunks.json`. The index records `type = hoi4-agent.chunked-artifact`, the
+original name, MIME type, size, SHA-256 and description, followed by ordered chunk resource links
+with indexes, byte offsets, lengths and SHA-256 hashes. Chunks use
+`application/octet-stream`; concatenating their decoded bytes in index order must reproduce the
+recorded original size and SHA-256 exactly. The index itself is limited to 1 MiB so an MCP client
+can read it in one request.
+
+The chunks and index are one atomic artifact batch. Every physical object and provenance manifest
+counts against the same aggregate-byte and entry quotas, every chunk remains at or below the
+configured per-object ceiling, and any admission, write, cancellation or owning-commit failure
+removes all files newly created by the bundle. This representation is lossless storage, not graph
+truncation or a quota bypass. `hoi4.gui_scan` and GUI render source-graph evidence return only the
+logical index link; agents follow its resource links when they need the full graph.
+
+Logical chunk preparation has a separate fixed 536,870,912-byte in-memory batch ceiling, and a
+lower configured `artifactMaxBytes` always wins. Before any payload is copied or hashed, admission
+validates every logical write's name, provenance and byte length, checks safe aggregate arithmetic,
+and projects the complete physical entry count after chunking. Preflight yields after each 256
+logical writes so cancellation can stop a broad batch before preparation. Preparation is then
+sequential, verifies that each admitted byte length is unchanged, and yields during hashing every
+16 MiB. Chunks share the one owned logical buffer during preparation instead of duplicating it.
+Crossing the fixed preparation ceiling fails with `ARTIFACT_LOGICAL_BATCH_LIMIT` before allocation.
+
+Artifact listing is paged at no more than 100 links. The store walks the complete sorted manifest
+inventory to verify bindings and compute an exact SHA-256 inventory revision, but retains only the
+requested page in memory. Cursors name the last public URI and are accepted only when that exact URI
+still occurs under the same revision. Listing and content verification honor request cancellation
+between directories, manifests, and hash chunks.
+
+Manifest reads stat the file and enforce the fixed 1 MiB ceiling before signal-aware JSON loading.
+Artifact writes, existing-content verification, quota walks, and queue waits also honor
+cancellation. A cancelled batch completes non-cancellable cleanup of every partial file. Once the
+caller's commit callback begins, that callback owns its critical-phase completion rules.
+
+## Storage placement
+
+A mod workspace defaults to `<mod>/.hoi4-agent/artifacts`; any in-mod override must remain beneath
+that exact generated subtree. An operator may instead place it beneath a configured `storageRoots`
+parent. A primary `game` or `dependency` workspace must always use an explicit operator-owned
+artifact root beneath `storageRoots`, separate from its explicit cache root. Artifact and cache
+roots cannot overlap each other or a source root.
+
+Generated artifact writes never make the game, dependency, or fixture source writable. Source
+changes are a separate transaction surface and are confined to the mod root.
+
+## Retention quotas
+
+The default per-workspace limits are:
+
+- `artifactMaxBytes`: 536,870,912 bytes across content and manifests;
+- `artifactMaxEntries`: 5,000 provenance manifests;
+- `artifactMaxSingleBytes`: 134,217,728 bytes for one content object;
+- serialized provenance manifests have a separate fixed 1 MiB ceiling and bounded fields.
+- one logical chunk-preparation batch has a fixed 536,870,912-byte ceiling.
+
+Content deduplication means a reused content hash adds no duplicate content bytes, while a new
+provenance manifest still counts as an entry and consumes its serialized bytes. Within one server
+process, the store measures current usage under an in-process per-root write queue before adding
+immutable files. Multi-artifact operations preflight all logical writes and their projected
+normal/chunk/index entries as one batch before payload copying or hashing, then retain newly created
+content and manifests only if their owning operation commits. A failed transaction-journal
+admission removes the diff files created by that batch without deleting pre-existing shared
+content or provenance. If the complete content and manifest would exceed a count, aggregate-byte,
+or per-object ceiling, the store refuses the write with `ARTIFACT_STORAGE_LIMIT`,
+`ARTIFACT_LOGICAL_BATCH_LIMIT`, `ARTIFACT_SINGLE_LIMIT`, `ARTIFACT_CHUNK_INDEX_LIMIT`, or
+`ARTIFACT_MANIFEST_LIMIT`; it does not write a truncated artifact or evict older evidence. Listing
+also refuses when an externally modified store is already over its configured retention budget.
+
+Artifact retention has no automatic garbage collector. Operator deletion is explicit and should
+be coordinated with active requests; deleting an artifact invalidates its URI. In contrast,
+transaction-journal cleanup follows the separate rules in [transactions](transactions.md). Do not
+share one writable artifact root between uncoordinated server processes; an operating-system
+storage service or operator must provide that coordination.
+
+Typical artifacts:
+
+- shared diagnostics and capability reports;
+- focus HTML/SVG/PNG/JSON, generated-source maps, and hash-bound planning sidecars;
+- GUI renders, galleries, hierarchy/click maps, comparisons, and fidelity reports;
+- map layers, changed-pixel reports, and before/after previews;
+- transaction manifests, source diffs, binary diffs, and validation reports.
+
+Structured JSON evidence records source paths, hashes, frame numbers, dimensions, formats, and
+fidelity metadata, but strips embedded `data:` payloads and glyph bitmap bytes. Composite SVG and
+PNG review renders may contain processed, source-derived icon, sprite-frame, or font-glyph pixels
+needed to inspect the requested interface; they are principal-bound generated evidence, not raw
+asset-file resources. The server never registers an installed-game, dependency, or mod raster/font
+file itself as an artifact.
+
+Artifacts are evidence. External HOI4 source remains authoritative. Deleting the configured
+artifact root invalidates only generated evidence, not mod content.

package/docs/compatibility.md

@@ -0,0 +1,33 @@
+# Compatibility and versioning
+
+## Runtime and platforms
+
+| Component | Supported                                                                                                                                         |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Node.js   | 22.x and 24.x                                                                                                                                     |
+| Windows   | Windows 10/11 x64                                                                                                                                 |
+| Linux     | Current x64/arm64 distributions supported by Node and Sharp                                                                                       |
+| macOS     | Source package supported; CI coverage may lag Windows/Linux                                                                                       |
+| MCP       | Final `2025-11-25` only; initialization requests for other revisions receive `2025-11-25` so clients without that revision can disconnect cleanly |
+| HOI4      | Current file formats are capability-scanned; no fixed game installation path                                                                      |
+
+The `2026-07-28` protocol was a release candidate at 0.1.0 development time. Adopting its breaking stateless core and SDK v2 requires a compatibility release after it is final and supported by clients.
+
+The pinned SDK also recognizes `2025-06-18`, `2025-03-26`, `2024-11-05`, and `2024-10-07`, but this server does not claim them: its public contracts use the final revision's structured output and resource-link behavior. Both stdio and Streamable HTTP gate negotiation to `2025-11-25`. After initialization, every Streamable HTTP POST, GET, or DELETE must carry `MCP-Protocol-Version: 2025-11-25`; a missing or different value receives a JSON-RPC error with HTTP status 400.
+
+## Public schemas
+
+Tool names and input/output schemas are public API. Additive compatible changes use a minor release. Removing/renaming a tool or changing accepted/returned meaning requires a major release or a documented deprecation period. Schema version, package version, server implementation version, changelog, container tag, and Registry metadata stay synchronized.
+
+Focus consumers can use `focus-plan.schema.json`, `focus-planning-sidecar.schema.json`, and `continuous-focus-palette.schema.json`. The planning sidecar is hash-bound enrichment data; it is not Clausewitz source and is never loaded by HOI4.
+
+Focus reward import ships a reviewed native-effect identifier catalog derived from the official
+HOI4 1.19.2 `effects_documentation.md`. This lets the importer distinguish engine effects from
+direct `scripted_effect_id = yes/{ ... }` calls without requiring an installed game at runtime.
+Compatibility reviews must refresh the catalog when official effect identifiers change; unknown
+effect-position scalars remain source-linked helper references so stale or misspelled calls lint
+as missing instead of disappearing.
+
+## Configuration migration
+
+Config has an integer `version`. Unknown versions or fields fail with deterministic diagnostics. A future migration utility must print a reviewable proposed config and never edit a client or workspace silently.

package/docs/completion-report.md

@@ -0,0 +1,60 @@
+# Completion report: 0.1.2 release candidate
+
+- Candidate version: `0.1.2`
+- Report date: 2026-07-11
+- Status: implementation and local release qualification complete; public delivery pending
+
+## Implemented scope
+
+The release candidate provides the shared source-preserving core, Focus Tree Workbench, Scripted GUI Studio, Agent Nudger map workflow, read-only-by-default transaction controls, stdio and authenticated Streamable HTTP transports, package entry points, schemas, synthetic portable fixtures, and public deployment documentation described by this repository.
+
+The npm payload is explicitly limited to compiled entry points, documentation, schemas, `server.json`, and the project license, security policy, README, and changelog. Installed-game data, third-party mod data, fixtures, tests, source files, local configuration, and workspace artifacts are excluded.
+
+## Qualification evidence
+
+The candidate has passed all 46 portable test files: 494 tests passed and one POSIX case was intentionally skipped on Windows. The latest enforced coverage is 88.44% statements, 78.25% branches, 91.28% functions, and 89.90% lines.
+
+Release-specific qualification also covers:
+
+- installation of the actual `npm pack` tarball into an isolated consumer, including an empty-cache install that proves `--prefer-offline` can fetch missing dependencies;
+- execution of the installed stdio, HTTP, and setup entry points;
+- package-content allowlisting, workspace-path leak checks, synchronized package and Registry metadata, and generated-schema checks;
+- npm dependency audit, registry signatures, and attestations;
+- live validation against the official MCP Registry API and pinned schema;
+- official MCP Inspector discovery against the production stdio entry point;
+- a production Docker build and protocol-only container stdio initialization/discovery; the release workflow records the final non-self-referential image digest in `container-image.json` rather than embedding an obsolete candidate digest into documentation copied inside that image;
+- immutable GitHub Action references, workflow and shell linting, strict release ordering, and byte-for-byte npm/GitHub release verification;
+- pinned Dockerfile-frontend and Node base-image digests, a multi-platform base supporting `linux/amd64` and `linux/arm64`, and a warning-free Docker build check;
+- read-only production-container checks proving OAuth metadata discovery, unauthenticated `401`, invalid-Origin `403`, protocol-only stdio initialization/discovery of all 26 tools, and a real read-only `hoi4.project_status` call from the non-root Node 22.23.1 runtime;
+- reusable bounded GUI helper templates, source-valid typed helper output, explicit state variants, deterministic scrolling and static meter handoffs, and refusal tests for unsafe or ambiguous helper compilation;
+- explicit even-odd province polygons with raster-boundary bounds checking before rasterization, pixel-center sampling, and refusal rather than clipping;
+- interrupted GitHub release recovery through a uniquely selected, byte-verified draft without asset overwrite or deletion, followed by exact immutable-release verification;
+- three installed-data qualifications covering a large vanilla/external focus workflow, a real GUI/GFX/font graph with deterministic full/annotated renders, and full province-map scan/render/storage without launching the game; the 302,497,021-byte canonical GUI graph was stored exactly as three bounded resources plus its one-read index while the default 128 MiB per-object ceiling remained enabled;
+- deterministic cold/warm benchmark output for the 255-focus, 203-visible-element GUI, and all-layer map workloads, including same-size/same-mtime content-hash invalidation.
+
+Known refusal cases and intentional boundaries remain documented in [Known limitations](limitations.md). They are explicit product constraints, not fallback implementations.
+
+## Public delivery status
+
+No public endpoint is claimed as complete in this report. The following evidence remains pending until the first release workflow finishes:
+
+| Surface        | Required completion evidence                                                                              | Status  |
+| -------------- | --------------------------------------------------------------------------------------------------------- | ------- |
+| GitHub source  | Public canonical repository containing the tested commit and immutable `v0.1.2` tag                       | Pending |
+| npm            | Public `hoi4-agent-tools@0.1.2` with exact tarball integrity and SLSA provenance                          | Pending |
+| GitHub release | Immutable `v0.1.2` release containing the exact npm and container digest manifests                        | Pending |
+| GHCR           | Public anonymous `0.1.2` digest with two runtime platforms and source-bound SBOM/provenance subjects      | Pending |
+| MCP Registry   | Exact `io.github.klimPaskov/hoi4-agent-tools@0.1.2` metadata with official `active` and `isLatest` status | Pending |
+| Public install | Clean registry installation, signature audit, MCP initialization, and tool discovery                      | Pending |
+
+## First-release completion sequence
+
+1. Commit the tested candidate on `main` and push it to the canonical public repository.
+2. Run the manual GHCR bootstrap workflow, make the new package public in GitHub, and verify the bootstrap index without saved credentials.
+3. Create `npm-bootstrap-v0.0.0-bootstrap.1`, store a shortest-lived npm granular token only as `NPM_BOOTSTRAP_TOKEN`, and run the manual non-OIDC npm bootstrap workflow from that tag. The earlier immutable `.0` attempt stopped before publication; it is retained as audit evidence rather than rewritten.
+4. Revoke and delete `NPM_BOOTSTRAP_TOKEN`, then configure npm trusted publishing for `klimPaskov/hoi4-agent-tools`, `release.yml`, and the explicit `npm publish` allowed action.
+5. Preserve the immutable `v0.1.0` tag whose run stopped in prepublication validation and `v0.1.1` whose OIDC job stopped before npm accepted bytes because npm parsed a relative tarball path as a Git shorthand. Qualify the synchronized `0.1.2` fix-forward commit and create `v0.1.2`. Do not create `NPM_TOKEN`; the OIDC workflow rejects it.
+6. Allow the release workflow to publish and verify npm, digest-immutable GHCR, the immutable GitHub release, and MCP Registry in its enforced order.
+7. Update this report with the commit, workflow run, public URLs, npm and image digests, and Registry status. Only then is public delivery complete.
+
+Detailed commands and failure behavior are documented in [Release and MCP Registry publication](release.md).

package/docs/configuration.md

@@ -0,0 +1,285 @@
+# Configuration and workspaces
+
+Pass a config with `--config PATH` or `HOI4_AGENT_CONFIG`. Unknown fields are rejected.
+The read-only setup discovery command also checks `HOI4_GAME_ROOT` and the path-delimited `HOI4_MOD_ROOTS`; it reports candidates without registering or modifying them.
+
+The stdio executable accepts newline-delimited JSON-RPC frames up to a fixed 16,777,216-byte
+ceiling, excluding the line-feed delimiter. This transport safety limit is deliberately not a
+configuration field; malformed UTF-8 and oversized terminated or unterminated frames close the
+stdio connection with a stderr diagnostic and no protocol output. Streamable HTTP uses the
+separately configured `http.maxBodyBytes`.
+
+```json
+{
+  "version": 1,
+  "writePolicy": "read-only",
+  "serverStateRoot": "/var/lib/hoi4-agent-tools-state",
+  "transactionTtlSeconds": 3600,
+  "transactionMaxJournalBytes": 536870912,
+  "transactionMaxJournals": 128,
+  "scanMaxFiles": 20000,
+  "scanMaxBytes": 134217728,
+  "scanMaxFileBytes": 67108864,
+  "artifactMaxBytes": 536870912,
+  "artifactMaxEntries": 5000,
+  "artifactMaxSingleBytes": 134217728,
+  "registrationRoots": ["/srv/hoi4/workspaces", "/srv/hoi4/game", "/srv/hoi4/dependencies"],
+  "writableRegistrationRoots": ["/srv/hoi4/workspaces"],
+  "storageRoots": ["/var/lib/hoi4-agent-tools"],
+  "workspaces": [
+    {
+      "id": "example",
+      "name": "Example Mod",
+      "kind": "mod",
+      "root": "/srv/hoi4/workspaces/example",
+      "gameRoot": "/srv/hoi4/game",
+      "dependencyRoots": [],
+      "dependencies": [
+        {
+          "root": "/srv/hoi4/dependencies/base",
+          "replacePaths": ["common/ideas"]
+        }
+      ],
+      "replacePaths": ["common/national_focus"],
+      "artifactRoot": "/srv/hoi4/workspaces/example/.hoi4-agent/artifacts",
+      "cacheRoot": "/srv/hoi4/workspaces/example/.hoi4-agent/cache",
+      "writeEnabled": false
+    }
+  ]
+}
+```
+
+## Server fields
+
+All byte values are exact bytes. Defaults are applied when a field is omitted.
+
+| Field                        |                 Default | Validation and behavior                                                                                                                                                                           |
+| ---------------------------- | ----------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `version`                    |                required | Must equal the current configuration version, `1`.                                                                                                                                                |
+| `writePolicy`                |           `"read-only"` | `"read-only"` or `"transactions"`.                                                                                                                                                                |
+| `serverStateRoot`            |                 omitted | Required for `"transactions"`; absolute canonical operator state used for the private journal key and replay-protection heads.                                                                    |
+| `transactionTtlSeconds`      |                  `3600` | 60 through 86,400 seconds.                                                                                                                                                                        |
+| `transactionMaxJournalBytes` |             `536870912` | At least 1 MiB; aggregate transaction-journal retention ceiling and per-plan work ceiling.                                                                                                        |
+| `transactionMaxJournals`     |                   `128` | 1 through 10,000 journals per workspace cache.                                                                                                                                                    |
+| `scanMaxFiles`               |                 `20000` | 1 through 1,000,000 enumerated files per scan.                                                                                                                                                    |
+| `scanMaxBytes`               |             `134217728` | At least 1 MiB of file content per scan.                                                                                                                                                          |
+| `scanMaxFileBytes`           |              `67108864` | At least 64 KiB and no greater than `scanMaxBytes`.                                                                                                                                               |
+| `artifactMaxBytes`           |             `536870912` | At least 1 MiB across one workspace artifact store; a lower value also bounds logical chunk preparation, which has an independent fixed 536,870,912-byte ceiling.                                 |
+| `artifactMaxEntries`         |                  `5000` | 1 through 100,000 provenance manifests.                                                                                                                                                           |
+| `artifactMaxSingleBytes`     |             `134217728` | At least 1 MiB and no greater than `artifactMaxBytes`; applies to content. Provenance manifests have a separate fixed 1 MiB ceiling.                                                              |
+| `registrationRoots`          |                    `[]` | Up to 16 operator-approved source parents for runtime `hoi4.project_register`; this alone never grants writable-mod registration.                                                                 |
+| `writableRegistrationRoots`  |                    `[]` | Up to 16 narrow descendants of `registrationRoots` that may be runtime `kind: "mod"` roots. Empty fails closed.                                                                                   |
+| `storageRoots`               |                    `[]` | Up to 16 operator-approved parents for artifact and cache directories; not a source-registration allowlist.                                                                                       |
+| `workspaces`                 |                    `[]` | Up to 1,000 statically reviewed workspace registrations; configured plus runtime registrations may never exceed 1,000.                                                                            |
+| `http`                       | loopback defaults below | Streamable HTTP policy. An omitted/default HTTP block has no credentials, so the HTTP executable refuses to start until authentication is configured. Stdio does not require HTTP authentication. |
+
+The configuration also rejects unsafe combined budgets: `scanMaxBytes` multiplied by
+`http.maxConcurrentRequests` must be at most 512 MiB, while `maxBodyBytes` multiplied by
+`maxConcurrentRequests` must be at most 16 MiB. HTTP concurrency has a fixed maximum of two so two
+simultaneous offline renders cannot exceed the supported process-safety model.
+
+`serverStateRoot` is mandatory whenever `writePolicy` is `"transactions"`. It must be absolute,
+resolve to a canonical directory through components that contain no symbolic links or junctions,
+and it must not overlap any configured or runtime source, fixture, artifact, cache, registration,
+writable-registration, or storage root. The server stores the native canonical spelling, including
+expanding harmless Windows 8.3 names, only after checking every existing component for links.
+The server creates one random 32-byte journal HMAC key there with mode `0600`; the surrounding
+POSIX directory must exclude group/other access. Windows operators must grant only the dedicated
+server account access through the directory DACL. Keep the same state root when restarting or
+temporarily changing to read-only mode so existing journals remain verifiable and recoverable. Do
+not copy a state root between unrelated deployments or expose it through a workspace mount.
+The state filesystem and every runtime artifact filesystem must support same-volume hard links and
+atomic rename/replacement. The server does not substitute a weaker ownership-claim or key-creation
+protocol when those primitives are unavailable.
+
+## Workspace fields
+
+| Field             | Default                         | Validation and behavior                                                                                                                      |
+| ----------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`              | required                        | Lowercase identifier matching `[a-z][a-z0-9_-]{0,63}`; unique in the configuration.                                                          |
+| `name`            | required                        | Human-readable name, 1 through 200 characters.                                                                                               |
+| `root`            | required                        | Primary source root. Its root kind is selected by `kind`.                                                                                    |
+| `kind`            | `"mod"`                         | `"mod"`, `"game"`, or `"dependency"`. Only a mod primary root can ever be writable.                                                          |
+| `gameRoot`        | omitted                         | Optional additional read-only base-game source; it must not overlap another source in the workspace.                                         |
+| `dependencyRoots` | `[]`                            | Up to 16 ordered read-only dependency roots without replacement metadata.                                                                    |
+| `dependencies`    | `[]`                            | Up to 16 ordered objects with required `root` and up to 1,000 `replacePaths`; mutually exclusive with non-empty `dependencyRoots`.           |
+| `replacePaths`    | `[]`                            | Up to 1,000 safe relative paths owned by the primary source root.                                                                            |
+| `roots`           | conventional roots below        | Relative source-family search paths. Unknown root-family names are rejected.                                                                 |
+| `artifactRoot`    | mod default; otherwise required | A mod defaults to `<root>/.hoi4-agent/artifacts`. A game/dependency primary workspace must name an operator-owned path under `storageRoots`. |
+| `cacheRoot`       | mod default; otherwise required | A mod defaults to `<root>/.hoi4-agent/cache`. A game/dependency primary workspace must name an operator-owned path under `storageRoots`.     |
+| `fixtureRoot`     | omitted                         | Optional read-only fixture source.                                                                                                           |
+| `writeEnabled`    | `false`                         | Effective only for `kind: "mod"` when global `writePolicy` is `"transactions"`.                                                              |
+
+`registrationRoots`, `writableRegistrationRoots`, and `storageRoots` grant different capabilities:
+
+- `registrationRoots` is consulted for runtime registration. The requested primary root and every
+  requested game, dependency, and fixture source must pass both lexical and canonical containment
+  beneath one of these roots. Statically configured `workspaces` come from the operator-reviewed
+  config file and are not required to be beneath `registrationRoots`.
+- `writableRegistrationRoots` is a separate, default-empty capability. Every entry must remain
+  lexically and canonically beneath `registrationRoots`. A runtime primary root declared as
+  `kind: "mod"` must remain beneath one of these narrow roots even when `writeEnabled` is false,
+  because mod registration creates generated artifact/cache storage. A game or dependency root
+  listed only in `registrationRoots` cannot be relabelled as a writable mod by a caller.
+- `storageRoots` permits generated files only. It never makes a directory eligible as a source.
+  Explicit artifact/cache paths outside a writable mod must canonicalize beneath one of these
+  roots.
+- A mod may use its defaults or another descendant of the corresponding
+  `<mod>/.hoi4-agent/artifacts` or `<mod>/.hoi4-agent/cache` subtree. It may also use an explicit
+  path under `storageRoots`. Artifact and cache roots must be distinct, non-overlapping, and must
+  not overlap source roots.
+- A `game` or `dependency` primary workspace is read-only and cannot place generated files in its
+  source tree. Both generated roots are therefore required and must be explicit operator-owned
+  descendants of `storageRoots`.
+
+Read-only source roots may be shared only where the workspace-isolation checks permit it; a
+workspace's internal primary/game/dependency/fixture roots must themselves be distinct and
+non-overlapping. Writable mod roots and generated roots are protected from overlap with other
+workspace-owned roots. The server creates approved artifact/cache directories when needed;
+approval comes from containment, not from the directory merely existing.
+
+For example, a read-only primary game workspace needs separate generated storage:
+
+```json
+{
+  "storageRoots": ["/var/lib/hoi4-agent-tools"],
+  "workspaces": [
+    {
+      "id": "game-reference",
+      "name": "Installed Game Reference",
+      "kind": "game",
+      "root": "/srv/hoi4/game",
+      "artifactRoot": "/var/lib/hoi4-agent-tools/game-reference/artifacts",
+      "cacheRoot": "/var/lib/hoi4-agent-tools/game-reference/cache"
+    }
+  ]
+}
+```
+
+The same explicit-storage requirement applies when the primary `kind` is `"dependency"`.
+
+`dependencyRoots` remains the concise form when dependencies declare no replacement ownership. Use `dependencies` instead when a dependency owns `replace_path` declarations; entries are ordered from lowest to highest precedence, and each replacement hides that subtree only in lower roots. The active mod's `replacePaths` remains the highest-precedence owner. The two dependency forms are mutually exclusive.
+
+`hoi4.project_status` returns one authorized workspace per page when no `workspaceId` is supplied;
+follow `nextCursor` until absent. Replacement ownership is summarized with exact counts and bounded
+path samples, so a workspace with many `replace_path` entries cannot inflate a tool response.
+
+## Read and write policy
+
+`writePolicy` defaults to `read-only`. Source apply/rollback requires `transactions` globally and `writeEnabled: true` on that mod workspace. A dependency or game registration remains read-only even if misconfigured.
+
+`registrationRoots` controls runtime `hoi4.project_register`. A requested root must canonicalize beneath one of these roots, and a runtime mod additionally requires `writableRegistrationRoots`. HTTP principals also need `allowRegistration`. Granting `allowRegistration` permits that principal to register unclaimed sources beneath the configured capability roots, so use narrow roots or static reviewed workspaces for multi-user deployments. Runtime registration does not edit a client configuration or persist raw paths. It atomically records a hash-only owner/workspace claim in the canonical artifact root; later registrations of that physical store must match it. Reassigning a claimed store is therefore an explicit operator operation: stop the server, review/archive the claim and existing evidence, and choose whether to preserve or separately migrate data. The server never deletes or silently rebinds it.
+
+Transaction mode does not accept pre-upgrade unauthenticated journal manifests. Preserve their
+cache directories for operator review, then explicitly archive or remove them together with the
+corresponding protected state decision; the server never guesses a migration or treats a public
+integrity hash as authorization.
+
+## Conventional roots
+
+Each workspace can override relative root lists:
+
+- localisation: `localisation`, `localisation_synced`
+- interface: `interface`
+- GFX: `gfx`
+- map: `map`
+- focuses: `common/national_focus`
+- scripted GUI: `common/scripted_guis`
+- states: `history/states`
+
+The exact default `roots` object is:
+
+```json
+{
+  "localisation": ["localisation", "localisation_synced"],
+  "interface": ["interface"],
+  "gfx": ["gfx"],
+  "map": ["map"],
+  "focus": ["common/national_focus"],
+  "scriptedGui": ["common/scripted_guis"],
+  "states": ["history/states"]
+}
+```
+
+Adapters can change these paths, not the safety model or source semantics.
+
+## HTTP configuration
+
+Loopback static token example:
+
+```json
+{
+  "http": {
+    "host": "127.0.0.1",
+    "port": 3210,
+    "allowedOrigins": ["https://agent.example.test"],
+    "trustedProxyAddresses": [],
+    "tokens": [
+      {
+        "principal": "developer",
+        "tokenEnv": "HOI4_AGENT_HTTP_TOKEN",
+        "workspaceIds": ["example"],
+        "allowRegistration": false
+      }
+    ],
+    "principals": [],
+    "maxBodyBytes": 1048576,
+    "headersTimeoutMs": 10000,
+    "requestTimeoutMs": 30000,
+    "keepAliveTimeoutMs": 5000,
+    "maxConnections": 64,
+    "maxRequestsPerSocket": 100,
+    "maxConcurrentRequests": 2,
+    "maxSessions": 128,
+    "maxSessionsPerPrincipal": 32,
+    "maxEventStreams": 32,
+    "maxEventStreamsPerPrincipal": 4,
+    "maxSessionEventBytes": 1048576,
+    "maxEventStoreBytes": 16777216,
+    "requestsPerMinute": 120,
+    "sessionTtlSeconds": 3600
+  }
+}
+```
+
+Secrets are read from named environment variables and are not stored in config. A missing static
+secret, a value shorter than 32 characters, or duplicate secret values make HTTP startup fail. See
+[self-hosting](self-hosting.md) for OAuth configuration.
+
+Every HTTP field is listed below. URLs are validated absolute URLs.
+
+| Field                         | Default       | Validation and behavior                                                                                                                                                                                                                                                     |
+| ----------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `host`                        | `"127.0.0.1"` | Listen address. Static tokens are permitted only on `127.0.0.1`, `localhost`, or `::1`.                                                                                                                                                                                     |
+| `port`                        | `3210`        | 0 through 65,535; `0` requests an ephemeral port.                                                                                                                                                                                                                           |
+| `publicUrl`                   | omitted       | Canonical HTTP(S) origin or exact `/mcp` endpoint. Required for OAuth. A non-loopback listener or URL requires HTTPS public OAuth policy, including when a public reverse proxy reaches a loopback listener. Credentials, path prefixes, query, and fragment are forbidden. |
+| `allowedOrigins`              | `[]`          | Exact HTTP(S) origins (`scheme://host[:port]`) without credentials, paths, queries, or fragments; opaque origins such as `null` are rejected. A present `Origin` header must match. Non-loopback deployments require at least one.                                          |
+| `trustedProxyAddresses`       | `[]`          | Exact IPv4/IPv6 socket-peer addresses allowed to supply `X-Forwarded-For` for the pre-auth rate key only; no CIDR, hostname, other forwarded-header trust, or implicit trust.                                                                                               |
+| `tokens`                      | `[]`          | Static-token grants. Mutually exclusive with `oauth`.                                                                                                                                                                                                                       |
+| `principals`                  | `[]`          | OAuth subject allowlist and workspace grants. OAuth startup requires at least one entry.                                                                                                                                                                                    |
+| `oauth`                       | omitted       | OAuth/OIDC JWT verification settings.                                                                                                                                                                                                                                       |
+| `maxBodyBytes`                | `1048576`     | 1,024 through 16,777,216 JSON bytes.                                                                                                                                                                                                                                        |
+| `headersTimeoutMs`            | `10000`       | 1,000 through 120,000; cannot exceed `requestTimeoutMs`.                                                                                                                                                                                                                    |
+| `requestTimeoutMs`            | `30000`       | 1,000 through 300,000 to receive the complete request.                                                                                                                                                                                                                      |
+| `keepAliveTimeoutMs`          | `5000`        | 1,000 through 120,000 and strictly less than `headersTimeoutMs`.                                                                                                                                                                                                            |
+| `maxConnections`              | `64`          | 1 through 100,000 accepted server connections.                                                                                                                                                                                                                              |
+| `maxRequestsPerSocket`        | `100`         | 1 through 100,000 requests before a socket is retired.                                                                                                                                                                                                                      |
+| `maxConcurrentRequests`       | `2`           | 1 through 2 admitted requests, enforced before JSON parsing and authentication. This fixed ceiling bounds concurrent offline render work.                                                                                                                                   |
+| `maxSessions`                 | `128`         | 1 through 10,000 active plus pending MCP sessions globally.                                                                                                                                                                                                                 |
+| `maxSessionsPerPrincipal`     | `32`          | 1 through 10,000 active plus pending sessions per principal, also capped by `maxSessions`.                                                                                                                                                                                  |
+| `maxEventStreams`             | `32`          | 1 through 10,000 simultaneous resumable GET streams globally.                                                                                                                                                                                                               |
+| `maxEventStreamsPerPrincipal` | `4`           | 1 through 10,000 simultaneous streams per principal.                                                                                                                                                                                                                        |
+| `maxSessionEventBytes`        | `1048576`     | 64 KiB through 64 MiB of replay history per session; cannot exceed `maxEventStoreBytes`.                                                                                                                                                                                    |
+| `maxEventStoreBytes`          | `16777216`    | 64 KiB through 256 MiB of replay history shared across sessions.                                                                                                                                                                                                            |
+| `requestsPerMinute`           | `120`         | 1 through 100,000 in each fixed minute, independently before auth per client address and after auth per principal.                                                                                                                                                          |
+| `sessionTtlSeconds`           | `3600`        | 60 through 86,400; renewed by an authorized request.                                                                                                                                                                                                                        |
+
+Each `tokens` entry requires `principal`, `tokenEnv`, and at least one configured `workspaceId`;
+`allowRegistration` defaults to `false`. Token principals and environment-variable names must be
+unique. Each `principals` entry requires `principal`; `workspaceIds` defaults to `[]` and
+`allowRegistration` to `false`. OAuth principals must be unique, and static-token/OAuth principal
+namespaces must be disjoint. Every granted workspace ID must exist in the static configuration.
+
+The `oauth` object requires `issuer`, `jwksUri`, `audience`, and at least one
+`authorizationServers` URL. `requiredScopes` defaults to `["hoi4:read"]`. `algorithms` defaults to
+`["RS256"]` and accepts only `RS256`, `RS384`, `RS512`, `ES256`, `ES384`, `ES512`, or `EdDSA`.