hoi4-agent-tools 0.2.0 → 1.0.0

package/docs/self-hosting.md

@@ -1,170 +0,0 @@
-# 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`; runtime registration and every source-mutation tool additionally require `hoi4:write`. In autonomous mode that means `hoi4.focus_rewrite`, `hoi4.gui_rewrite`, and `hoi4.map_rewrite`; in compatibility mode it includes planning, apply, and rollback. 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.
-
-`hoi4:write` authorizes the server-side capability; it does not dictate the MCP host's user-interaction policy. Autonomous rewrite tools advertise `destructiveHint: true`, but MCP does not require a prompt for every such call. The server cannot override a host that prompts for or blocks it.
-
-### 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 journal 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. Every write-enabled deployment additionally requires 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.2.0 .
-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.2.0
-```
-
-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 in either autonomous or reviewed mode, 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

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

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

@@ -1,180 +0,0 @@
-# Autonomous rewrites, transactions, and recovery
-
-The recommended `"autonomous"` write policy exposes three source-mutation tools:
-
-- `hoi4.focus_rewrite`;
-- `hoi4.gui_rewrite`;
-- `hoi4.map_rewrite`.
-
-One rewrite call calculates every affected source and binary file, validates the proposed bytes in memory, persists an authenticated journal with exact recovery data, applies under the workspace lock, rebuilds the shared index, and post-validates the result. The caller does not receive or invoke separate transaction apply or rollback tools. Those tools are not registered in autonomous mode.
-
-`"transactions"` remains available as an optional compatibility policy. It exposes the older `hoi4.focus_plan_changes`, `hoi4.gui_plan_changes`, and `hoi4.map_plan` tools, followed by `hoi4.transaction_diff`, `hoi4.transaction_apply`, `hoi4.transaction_status`, and `hoi4.transaction_rollback`. Both modes use the same core transaction engine and safety properties; only the public MCP workflow differs.
-
-## Autonomous rewrite pipeline
-
-Every autonomous rewrite follows this sequence inside one MCP call:
-
-1. resolve targets with write access confined to the canonical mod root;
-2. calculate the complete affected-file set and exact proposed bytes;
-3. run domain-specific in-memory validation and create source, binary, pixel, or rendered evidence as applicable;
-4. persist the plan, before/after blobs, authentication tag, and protected revision head;
-5. recheck principal, workspace, canonical roots, expiry, and every before-hash under the workspace lock;
-6. stage and replace files in deterministic order;
-7. rebuild the shared index, run domain post-write validation, and verify every final hash;
-8. return `execution: "applied"`, changed-file samples, validation, and evidence links only after success.
-
-A proposal whose pre-write checks fail returns blocked with `execution: "blocked"` and changes no source bytes. A request whose desired bytes already match every target returns `execution: "unchanged"` as a successful no-op. Any error after replacement begins starts exact restoration before failure is returned. Startup recovery also completes restoration for an interrupted journal before another write is accepted. Autonomous mode therefore removes the client-driven review/apply handshake without weakening validation or recoverability.
-
-The rewrite tools truthfully advertise `readOnlyHint: false` and `destructiveHint: true`. MCP does not mandate a confirmation prompt for each tool call. A coding-agent host can still prompt for or block the call under its own policy, and the server cannot override that host decision.
-
-Git remains the recommended source-history, collaboration, and intentional-revert system. Internal recovery serves a different purpose: exact before-bytes and the durable journal prevent a failed multi-file rewrite from leaving partial corruption, including outside a Git checkout.
-
-Successful autonomous journals are internal recovery data, not user history. They are reclaimed automatically when journal retention reaches its configured count or byte limit; authenticated source-linked evidence remains in the artifact store. Reviewed compatibility mode retains applied journals so its explicit rollback operation remains available.
-
-## Planning and evidence
-
-Proposed bytes are validated in memory before any source replacement. Every target is restricted to the workspace's canonical mod root; rewrites cannot write the game, a dependency, a fixture, artifact storage, cache storage, or the reserved `.hoi4-agent` subtree as mod source.
-
-The transaction core 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`; domain adapters cannot opt out. 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 plan whose explicit checks fail remains evidence for the blocked rewrite 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.
-
-Autonomous rewrite results keep bounded path samples and return the generated evidence resources directly; internal transaction identifiers and plan hashes are not caller inputs or success-result fields. Every applied autonomous rewrite links a sanitized execution-validation JSON resource containing the complete pre-write and post-write checks, source-linked diagnostics, final target hashes, and any overflow diagnostic resources without exposing the internal transaction ID or plan hash. Inline validation remains capped at five checks for wire efficiency. Reviewed compatibility mode additionally exposes the authenticated transaction-manifest resource.
-
-In reviewed compatibility mode, `hoi4.transaction_diff` returns at most 20 files, operation summaries, and artifact links per page. Follow every `nextCursor` until absent before applying. Cursors are bound to the immutable plan hash and fail if reused for a different transaction. A transaction ID is a journal identifier, not approval.
-
-Focus rewrites include both the edited Clausewitz source and its adjacent `.focus-plan.json` design sidecar in one recoverable operation. The manifest retains the proposed generated-source map and sidecar artifacts after success or restoration so each generated focus range remains traceable to its planning/source node.
-
-Complete focus proposal validation is a linked JSON resource. If proposed or post-write diagnostics exceed the fixed manifest allowance, validation still evaluates the complete set, stores it as a source-linked MCP resource, and retains a blocker-first bounded manifest summary. The plan phase reserves diagnostic capacity for the independent post-write phase, so a warning-heavy large tree does not weaken limits or prevent a valid rewrite.
-
-## Apply pipeline and protected state
-
-Autonomous tools pass their internal transaction ID and exact 64-character plan hash directly to the core apply path. In compatibility mode, the caller supplies the same values to `hoi4.transaction_apply`. The server rejects a different principal/workspace, changed roots, failed pre-write validation, 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 manifest-resource reads, and status/diff reads when compatibility mode exposes them, 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 in compatibility mode
-
-`hoi4.transaction_rollback` is available only in reviewed `"transactions"` mode 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.
-
-Autonomous mode does not expose an explicit rollback tool. Failed application and post-validation restore automatically; an intentional later reversal belongs in Git or a new explicit domain rewrite.
-
-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

@@ -1,54 +0,0 @@
-# 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.
-
-## Rewrite reports stale
-
-The source changed after planning or before the workspace lock completed its recheck. Scan again and submit a new rewrite so evidence matches current files. In reviewed compatibility mode, do not reuse the stale transaction.
-
-## Rewrite or transaction tools are missing
-
-Check `writePolicy` in `hoi4.project_status`. `"read-only"` authorizes no source mutation, even if compatibility-named planning or transaction tools are listed by the client. `"autonomous"` exposes `hoi4.focus_rewrite`, `hoi4.gui_rewrite`, and `hoi4.map_rewrite` and intentionally hides all transaction tools. `"transactions"` enables the older plan/diff/apply/status/rollback surface instead. Restart the server and initialize a new MCP session after changing configuration.
-
-## Transaction state rejected
-
-Each write-enabled policy requires an absolute, persistent `serverStateRoot` that does not overlap any
-source or generated-storage capability. Run setup with `--autonomous-writes --server-state ROOT` for autonomous rewrites, or `--reviewed-writes --server-state ROOT` for compatibility mode, 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.
-
-## The MCP host still asks for approval
-
-The autonomous rewrite tools advertise `destructiveHint: true`. MCP does not require or forbid a prompt; the coding-agent host controls its own approval and filesystem policy, and the server cannot override it. Change the host policy only if that matches your local security requirements.
-
-## 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.