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

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`.

package/docs/focus-workflow.md

@@ -0,0 +1,68 @@
+# Focus Tree Workbench
+
+The workbench imports existing focus source into a structured plan without normalizing away unsupported fields. It models tree/country assignment, branches and lanes, explicit prerequisite groups, exclusions, route locks, bypass/availability, fixed/relative/pinned/automatic positions, planner-only hidden/crisis/conditional routes, convergence, shared support, icons, localisation, AI/filter metadata, linked content, and raw passthrough.
+
+Linked reward content is taken from the actual effect grammar. Native effects are distinguished by
+the bundled catalog of all 553 identifiers documented for the supported HOI4 1.19.2 build. Direct scripted-effect calls, including calls nested in
+`IF`/`ELSE`, iterator scopes, and weighted `random_list` entries, link to the shared scripted-effect
+index. Native control/trigger blocks and country, state, character, event-target, or variable scopes
+are traversed without becoming helper links. Decision-category tooltips link to indexed top-level
+categories; decision targets recognized as formables link to the formable symbol; cosmetic tags do
+not masquerade as formables. Missing links retain the exact reward source location.
+
+Decision categories are additive database fragments: the category definition under
+`common/decisions/categories` and one or more decision-member blocks may legitimately share an ID.
+The shared index retains those fragments without reporting a duplicate-definition collision while
+still honoring same-relative-file shadowing and load-order source ownership.
+
+National focuses and continuous focuses use their actual HOI4 source models. National trees come from the workspace registration's configured `roots.focus` paths. Continuous focuses come from `common/continuous_focus/*.txt` as `continuous_focus_palette = { ... focus = { ... } }`; matching country palettes take precedence over the default palette, and the compiler never emits a `continuous` field inside a national `focus = { ... }` block.
+
+## Agent workflow
+
+1. `hoi4.project_scan` builds the common workspace/index revision.
+2. `hoi4.focus_scan` imports active national trees, matching continuous-focus palettes, active localisation, sprite definitions, and only the exact texture paths referenced by those sprites.
+3. `hoi4.focus_lint` separates syntax, reference, layout, and design diagnostics. Omit `mode` for national-tree compatibility, or pass `mode: "continuous"` with an optional `paletteId` to lint a palette directly.
+4. `hoi4.focus_layout` calculates stable integer coordinates. Pinned positions and existing coordinates anchor incremental changes.
+5. `hoi4.focus_render` returns deterministic HTML, SVG, PNG, JSON, and generated-source-map resources. National mode also returns the graph layout and hash-bound planning sidecar; continuous mode accepts palette columns and renders the actual continuous-focus source model.
+6. `hoi4.focus_plan_changes` accepts either a national plan (the backward-compatible default) or `mode: "continuous"` with a continuous-palette plan. Both make source-preserving range edits where possible and produce before/proposed/bitmap-diff review artifacts before creating the dry-run transaction. National plans also maintain the adjacent planning sidecar. To create a first tree or palette in a new mod source file, the coding agent must set `createIfMissing: true`; without that explicit flag, missing sources and IDs refuse. Creation never appends a different target to an existing source file, because doing so could repurpose unrelated source or its adjacent planning sidecar. It uses a transparent source-linked before render, never copies a read-only game/dependency file into a shadowing mod path, and rolls back newly created source and sidecar files atomically.
+7. Review drift, diagnostics, source maps, diff artifacts, and plan hash before apply.
+
+## Prerequisite and route semantics
+
+One `prerequisite` block containing several `focus` entries is an OR group. Several prerequisite blocks are ANDed. The importer preserves that grouping exactly. It never flattens prerequisites into a graph that changes meaning.
+
+Structured route locks compile only to valid trigger fields: selection conditions use `available`, while branch visibility uses `allow_branch`. `all`, `any`, exclusion, and impossible locks compile to direct conditions, `OR`, `NOT`, and `always = no` respectively. Hidden/crisis labels are design metadata, not Clausewitz keys; re-import enrichment restores them from the sidecar without emitting invalid `hidden =` or `crisis =` markers.
+
+## Planning sidecar
+
+Branch/lane assignment, shared-support status, working labels, planner visibility/reveal intent, terminal/payoff classification, and major-route AI notes are design metadata rather than HOI4 fields. A source file such as `common/national_focus/example.txt` therefore has an adjacent `example.focus-plan.json` sidecar.
+
+The sidecar records the exact generated source SHA-256. Enrichment is explicit and succeeds only for the matching tree and source hash; stale or mismatched sidecars produce diagnostics and do not silently override source truth. Source-only imports remain valid when no sidecar exists.
+
+## Localisation and sprite resolution
+
+Scan and render select active localisation and sprite symbols through the shared load-order index. Rendered titles use the active language value, and icons use frame zero from the active sprite's real `texturefile` and `noOfFrames` definition. Sprite strips are cropped to the resolved frame rather than displayed as a whole image.
+
+Raster discovery is deliberately exact: the shared workspace scan does not walk every `gfx/**/*.dds` or `gfx/**/*.png` file. After resolving referenced sprites, the asset catalog scans only their normalized texture paths. Missing localisation, sprite, texture, or unsupported-frame diagnostics retain the originating focus/icon source location.
+
+## Layout contract
+
+Hard constraints keep parents above children, coordinates unique, visible nodes non-overlapping, pinned nodes fixed, route lanes separated, and relative-position chains valid. The solver records every move and unsatisfied constraint. It never changes a prerequisite, silently stacks nodes, or invents a route.
+
+Mutual-exclusion relationships are also layout constraints: newly placed automatic endpoints must retain at least the configured `nodeSpacing` in horizontal focus-grid columns. Fixed, relative, pinned, and prior-layout coordinates are stability anchors. The solver does not move those anchors to improve mutual-exclusion spacing or connector routing; it emits `FOCUS_LAYOUT_MUTUAL_EXCLUSION_SPACING_UNSATISFIED` with the movable and preserved endpoints when authored constraints make the gap impossible.
+
+For each new automatic node, the solver evaluates integer candidates in deterministic distance and direction order, rejects visible overlap and mutual-exclusion violations, and chooses the nearest candidate with the fewest connector crossings. A crossing-only move is recorded as `moved_to_reduce_crossings` with its before/after count. Remaining crossings produce `FOCUS_LAYOUT_CONNECTOR_CROSSING_UNSATISFIED` with the preserved endpoints and reason. Supplying a previous layout makes its existing automatic nodes stable anchors, so a small addition cannot reshuffle an accepted tree.
+
+Weak dangling branches, terminal payoff, missing AI, and repeated generic rewards remain deterministic design warnings. Layout heuristics never become automatic gameplay edits.
+
+## Drift and source maps
+
+The plan records imported source and semantic hashes. If both saved plan and hand-edited script diverge, regeneration is blocked until the coding agent explicitly identifies the authoritative source. Raw fields remain attached to source ranges either way. An explicitly created target reports `target_missing` drift with `requiresAuthority: false`; that status means there is no prior target to reconcile, not that an existing source was overwritten.
+
+Every compiled or proposed focus block receives a source-map entry containing the focus ID, generated location, planning-node location when available, and imported source location when available. National render artifacts use `<tree>.focus.source-map.json`; continuous renders use `<palette>.continuous.source-map.json`. Dry-run transactions retain the corresponding proposed source map and all review artifacts after apply and rollback.
+
+## Artifacts
+
+Each rendered node includes its ID, resolved title/working label, resolved icon frame or diagnostic, coordinates, prerequisite type, exclusions, branch family, planner visibility/convergence/terminal state, AI metadata, and source-linked diagnostics. HTML search and filters inspect evidence only; they cannot write source.
+
+National-tree renders store `<tree>.focus.html`, `.svg`, `.png`, `.json`, `.source-map.json`, and `.plan.json`. Continuous-palette renders use the same core artifact store and produce `<palette>.continuous.html`, `.svg`, `.png`, `.json`, and `.source-map.json`. The JSON embeds the same complete generated-source map that is also stored separately, and all formats carry content hashes plus source/render provenance.

package/docs/gui-workflow.md

@@ -0,0 +1,121 @@
+# Scripted GUI Studio
+
+Scripted GUI Studio builds an offline source graph across `.gui`, `.gfx`, `common/scripted_guis`, localisation/scripted localisation, sprites/textures, frame animation, fonts, decision entry points, parents/contexts, button effects, triggers, properties, dynamic lists, and AI behavior.
+
+It does not launch, automate, hook, or capture the game. Output is always labelled an offline representation.
+
+## Preview scenarios
+
+A scenario selects resolution, UI scale, root window, rendered state, global animation sample time, optional time-since-visible, explicit frame overrides, and mock country/state/variables/flags/lists/localisation/scripted-GUI values. `play_on_show = yes` samples `visibleTimeSeconds` (or the global clock when it is omitted); other animations sample `animationTimeSeconds`. Non-looping sprites clamp to the final frame, and looping sprites honor `pause_on_loop`. The exact scenario and source revision are stored with every artifact so another coding agent can reproduce it.
+
+Required state coverage includes normal, hover, selected, locked, disabled, warning, active, completed, empty/full list, minimum/maximum values, long text, and missing localisation.
+
+## Renderer
+
+The renderer resolves nested parent offsets, positions, sizes, scale, clipping, z-order, sprite dimensions/frame strips, text alignment/wrapping, font metrics/kerning, button/icon states, list rows, visibility, and selected animation frames. Scanned TTF/OTF text is rendered from fontkit outline paths and uses the scanned ascent as its baseline. Scanned BMFont text defaults to the font's native `info size` when the GUI element has no `fontSize`, uses `common lineHeight` and `base`, and composes bounded crops of declared atlas pages with parsed offsets, advances, and kerning. Artifact-owned labels and unavailable workspace glyph data use paths from the pinned redistributable project font, so SVG-to-PNG output never depends on fonts installed on the host. It produces:
+
+- full and cropped PNG/SVG renders;
+- annotated bounds/ID render;
+- click-region overlay;
+- hierarchy and source-location reports;
+- state gallery;
+- resolution/UI-scale gallery;
+- before/after comparison;
+- JSON layout and fidelity reports.
+
+Generated PNGs are real compositions from parsed synthetic or workspace assets, not placeholder diagrams.
+
+Standalone comparison artifacts are bound to the exact source graph used for both renders. Their JSON evidence records both complete preview scenarios, both source revisions, both full fidelity reports, and the deterministic bitmap-diff statistics; PNG and JSON manifests repeat bounded fidelity summaries for both scenarios.
+
+Studio discovery is two phase. `gui_scan` indexes configured `roots.interface`, `roots.gfx`, `roots.scriptedGui`, and `roots.localisation` definitions plus the fixed decision, scripted-localisation, font-definition, and animation-manifest paths. It does not eagerly read every texture in an installed game. Lint and render calls then resolve only the selected window's transitive sprites, static fallbacks, fonts, BMFont pages, and animation source frames by safe exact path or unique basename.
+
+The complete source graph is never truncated to fit artifact storage. If its canonical JSON exceeds
+the configured per-object ceiling, `gui_scan` and render storage return a `*.chunks.json` logical
+artifact index. Its ordered content-addressed resource links reconstruct the exact original JSON
+bytes and hash. The index, chunks, and their provenance manifests are admitted and rolled back as
+one bounded artifact batch; all physical objects still consume the configured byte and entry
+budgets. See [Artifact resources](artifacts.md) for the index format and reconstruction rule.
+
+If an active definition source exceeds a fixed parser byte, line, token, entry, or nesting limit, broad GUI discovery skips that whole source before content sniffing or graph traversal. `gui_scan` returns `GUI_SCANNED_PARTIAL`, `complete: false`, the total skipped-source count, and a bounded source sample in both structured output and the graph artifact. Missing references become partial-inventory warnings only when the skipped source family could define that exact target kind; an unrelated capped source does not weaken validation. A lint/render target that cannot be found because a GUI definition source was skipped, and a patch aimed directly at a capped source, refuse with `GUI_TARGET_SOURCE_SKIPPED_LIMIT`.
+
+Localisation is selected with the same bounded approach. Discovery indexes `l_english`; lint, render, state, resolution, and comparison calls derive the complete language set from their preview scenarios and scan those exact language directories. A French scenario therefore resolves `l_french` source without retaining every unrelated installed translation.
+
+## Fidelity report
+
+Every render groups fields into:
+
+- `modelled`: represented from source values;
+- `approximated`: deterministic but not asserted engine-identical;
+- `ignored`: known nonvisual or intentionally excluded fields;
+- `missing`: referenced asset/font/localisation is unavailable;
+- `unsupported`: parsed construct has no renderer implementation;
+- `unresolved`: dynamic value is absent from the scenario.
+
+The report includes scenario, source revision, resolution, UI scale, state, font/asset hashes, and renderer version. `font_glyph_rendering` is modelled only when the rendered line comes from scanned TTF/OTF outlines or BMFont atlas glyphs with a declared baseline; a project-font or missing-baseline substitution is approximated and missing code points are separately reported. Every parsed element attribute is classified: attributes actually consulted by the scene model are `modelled`, while fields such as tooltips, sounds, shortcuts, engine-only window animation, and `fixedsize` are explicitly `ignored` until their behavior is represented. A missing or unsupported field is never given an invented appearance.
+
+The primary frame of `textSpriteType`, `corneredTileSpriteType`, GFX `progressbarType`, and `maskedShieldType` can be shown for source review, but their engine text generation, tiling, progress composition, and masking semantics are not implemented. `textureFile2` and `effectFile` are retained in the source graph but are not composited or executed. Each affected element therefore receives explicit unsupported fields, an approximated `sprite_frame`, and a `GUI_SPRITE_RENDER_PARTIAL` warning; it is never labelled as a fully modelled appearance.
+
+## Bounded resource admission
+
+Studio discovery, graph construction, validation, and rendering use fixed process-safety ceilings. A render admits no more than 512 distinct raster/native-image operations, including selected GUI assets, galleries, focus icons, render plans, and bitmap comparisons. Rendered text is limited to 16,384 characters per element, 262,144 aggregate characters per scene, and 32,768 layout operations while preserving BMFont kerning across wrapping decisions.
+
+BMFont text inputs stop at 2,097,152 bytes, 50,000 records, 32 fields per record, 256 pages, 32,768 characters, and 32,768 kerning pairs; binary font inputs stop at 8,388,608 bytes. Missing-glyph evidence retains 64 samples. Source-graph admission fails before retaining more than 50,000 GUI elements, 500,000 total nodes, or 1,000,000 edges; expanded scenes stop at 10,000 elements. Validation stops at 2,000 diagnostics, 2,000,000 pair comparisons, or 2,000,000 ancestor hops. Exceeding a bound returns an explicit blocker instead of a partial render, unbounded validation pass, or invented approximation.
+
+## Source-preserving plans
+
+Existing `.gui` files accept only hash-bound patches at parser-proven ranges. A patch may replace one known scalar assignment or scalar value, delete one known scalar assignment, or insert complete parsed entries immediately before a block close. Whole-file ranges, block rewrites, unknown-field rewrites, malformed insertions, stale text, and ambiguous ranges are refused. New files may be supplied in full only when no mod, dependency, or game source already owns the path. Every proposal is reparsed and rendered before it can become a transaction.
+
+## Declarative helper compilation
+
+`hoi4.gui_plan_changes` in `helpers` mode compiles a strict, build-time helper document into explicit `.gui` source and then plans the write through the normal transaction path. The generated mod has no runtime dependency on `hoi4-agent-tools` or its server.
+
+A document has one `root` and may declare reusable `templates`. A template instance uses `kind: "template"` plus `templateId`; its instance ID becomes the deterministic prefix for every expanded ID and name. For example, instance `left_status` of a template whose root is named `status_card` produces `left_status__status_card`. Instance fields may override the template root, but templates do not provide parameters, slots, or appended children. Missing references, duplicate template IDs, duplicate node IDs, reference cycles, duplicate compiled GUI names, and source or expanded budget overflow refuse compilation. Expanded identifiers stop at 1,024 UTF-8 bytes; conservative source-construction work stops at 16 MiB, and final source stops at the 8 MiB Clausewitz parser ceiling before a transaction is planned.
+
+The structured helpers compile as follows:
+
+| Helper         | Explicit source behavior                                                                                                                                                                                       |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `anchor`       | A child-bearing `containerWindowType`; `orientation` selects the reference point in the parent or screen, while `origo` selects the corresponding point on the container itself. Both default to `upper_left`. |
+| `row`          | Children flow horizontally with margins and `gap`.                                                                                                                                                             |
+| `column`       | Children flow vertically with margins and `gap`.                                                                                                                                                               |
+| `stack`        | Children overlap at their explicit offsets inside the padded container.                                                                                                                                        |
+| `grid`         | Children occupy fixed columns; each following row begins after the tallest item in the preceding row.                                                                                                          |
+| `card`         | A stacked container with an optional named sprite background.                                                                                                                                                  |
+| `tabs`         | Tab controls flow horizontally; button appearance is supplied by explicit `buttonType` children and state selection.                                                                                           |
+| `scroll-list`  | A clipped, background-backed scrolling container with a nested `gridBoxType` and one independent, top-level entry container.                                                                                   |
+| `target-row`   | Target controls flow horizontally as a distinct composition surface.                                                                                                                                           |
+| `meter`        | A container with an icon whose selected frame is derived deterministically from `minValue`, `maxValue`, `value`, and `frames`.                                                                                 |
+| `status-panel` | Status items flow vertically.                                                                                                                                                                                  |
+| `modal`        | A centered `windowType` with centered `origo`, stacked children, and an optional named sprite background.                                                                                                      |
+| `overlay`      | Children overlap and the container defaults to `clipping = no`.                                                                                                                                                |
+
+`scroll-list` requires positive dimensions, a background sprite, an axis-compatible scrollbar definition, and exactly one structured entry-container child. A helper named `orders` emits `orders__grid`, `orders__entry`, and `orders__background`. `flow: "vertical"` emits a vertical scrollbar and one horizontal slot; `flow: "horizontal"` emits a horizontal scrollbar and one vertical slot. The compiler cannot inspect the referenced scrollbar definition in this standalone build-time document, so the caller must supply a definition whose `horizontal` setting matches the selected flow. The matching `common/scripted_guis` `dynamic_lists` wiring must reference the generated grid and entry names separately; helper compilation does not invent an array, scope, or scripted-GUI binding.
+
+`meter` is a static, reviewable frame selection, not an engine progress widget or runtime variable binding. `progressbarType` belongs to GFX sprite definitions and is never emitted as a `.gui` element. The declared range is validated, then `value` selects a frame from the declared multi-frame icon sprite. Runtime changes still require explicit scripted-GUI properties or raw source authored for that mechanic.
+
+Structured leaf output is type-aware. `iconType` accepts sprite/frame fields, `instantTextBoxType` accepts text/font plus `maxWidth` and `maxHeight`, and `buttonType` accepts sprite/frame plus `buttonText` and `buttonFont`. Leaf elements never receive a fabricated `size` block and cannot contain child GUI elements. Hardcoded or legacy forms such as `checkboxType`, `guiButtonType`, and `textBoxType` are refused by the structured helper; use `raw` only when an exact engine precedent justifies them.
+
+Selecting a custom UI `state` requires a matching `stateVariants` entry. Its frame, sprite, text, font, and allowlisted scalar attributes replace the base values in the emitted source; no preview-state comment or inferred frame is written. The engine-managed `normal`, `hover`, `pressed`, and `disabled` states may be named on `buttonType` without a custom variant, but the compiler does not fabricate their frame mapping. Attribute keys must be both safe identifiers and documented scalar fields for the selected container, icon, text, or button type; structured fields, misspellings, and type-incompatible fields cannot be smuggled through `attributes`. `raw` remains the explicit escape hatch for complete advanced Clausewitz GUI source and is counted in transaction evidence.
+
+## Validation
+
+The studio checks visible overlap, clipping, overflow, spacing, invalid size, child/clip escape, visual/click mismatch, invisible blockers, conflicting click regions, missing assets/fonts/localisation, frame/sheet/fallback errors, parent/context errors, z-order risks, cut scroll rows, resolution drift, conflicting tab states, button trigger/effect gaps, cost disagreements, AI equivalence, and renderer fidelity blockers.
+
+Actual font metrics drive text checks; OCR is not used. GUI costs are derived from standard `£icon amount` tokens in the button's referenced localisation and compared with direct negative scripted-GUI resource effects such as `add_political_power = -12`. Diagnostics link the localisation, GUI element, and scripted effect source locations. Scenario `guiCosts`/`scriptCosts` remain optional preview assertions but are not the source-validation path.
+
+## Animation source manifests
+
+A project-owned animation may provide one manifest at `hoi4_agent/animation_sources/<animation>/manifest.json`, validated by `schemas/gui-animation-source.schema.json`. The manifest identifies the `frameAnimatedSpriteType`, final sheet path and hash, cell dimensions, independently authored source-frame paths/hashes/anchors, animation settings, and a source-derived static fallback.
+
+For a selected window, the public Studio path verifies:
+
+- manifest and sprite frame counts and animation settings;
+- source, sheet, and fallback SHA-256 hashes;
+- supported and identical source-frame dimensions;
+- distinct source bytes and distinct decoded artwork;
+- stable in-frame anchors;
+- exact decoded pixels from each source frame against its sheet cell;
+- sheet dimensions and declared sprite size;
+- static-fallback sprite/path/hash/dimensions and exact equality to its declared source frame.
+
+Without a manifest, the composed sheet remains renderable but validation emits `GUI_ANIMATION_SOURCE_PROVENANCE_UNAVAILABLE`; it is not accepted as proof of independent frames. Rendering checks cancellation between bounded element chunks and variants without changing deterministic output.

package/docs/limitations.md

@@ -0,0 +1,30 @@
+# Known limitations and refusal cases
+
+These are precise safety boundaries, not silent fallbacks.
+
+- Arbitrary dynamic trigger/effect evaluation is outside an offline renderer. Preview scenarios must supply dynamic values; unresolved values appear in fidelity reports.
+- Workspace scans default to 20,000 enumerated files, 134,217,728 aggregate content bytes, and 67,108,864 bytes for one file. Operators may lower these values per request but cannot raise them above server policy. Exceeding any ceiling refuses the complete scan with `SCAN_FILE_LIMIT` or `SCAN_BYTE_LIMIT`; a partial index is not returned. The configuration additionally requires aggregate scan bytes multiplied by HTTP request concurrency to remain at or below 512 MiB.
+- Stdio uses strictly decoded UTF-8 newline-delimited JSON-RPC with a fixed 16,777,216-byte frame ceiling, excluding the line-feed delimiter. A malformed UTF-8 frame is refused without replacement decoding; an oversized frame is refused as soon as it crosses the ceiling, even without a newline or end-of-input. Either condition closes the local transport without emitting protocol output. Use workspace files and MCP resources instead of oversized inline payloads.
+- Clausewitz/localisation parsing is bounded to 8,388,608 source bytes and 250,000 lines per file; Clausewitz tokenization is bounded to 250,000 tokens, block nesting to 256 levels, and localisation parsing to 100,000 entries. Broad project and GUI inventories skip the entire active source when one of these bounds is crossed, return `complete: false` with a bounded skipped-source list, and do not walk or publish symbols from the partial parse. An unresolved reference is downgraded only when the skipped source's path family could define that reference kind. Targeted reads and writes still refuse the affected source with an explicit blocker; content beyond a limit is never treated as a complete parse.
+- Source diagnostics are capped at 100 per file. When additional findings exist, 99 findings are retained and the final slot becomes `SOURCE_DIAGNOSTICS_TRUNCATED`, a blocker rather than a silent truncation.
+- Renderer coverage is field-by-field. Parsed engine-only GUI properties are retained raw and reported as ignored or unsupported; source changes crossing an unknown field or parsed block are blocked rather than normalized away. Special `textSpriteType`, `corneredTileSpriteType`, GFX `progressbarType`, and `maskedShieldType` semantics, secondary textures, and effect files currently produce only a partial primary-texture appearance with explicit fidelity items and a warning.
+- Offline GUI output is not guaranteed pixel-identical to the game engine and is never called a screenshot. Modelled geometry and asset composition are deterministic for the recorded render profile.
+- Offline image work uses fixed process-safety ceilings: 16,384 pixels per axis, 50,331,648 pixels per generated artifact, 16,777,216 pixels per decoded texture, 33,554,432 bytes per encoded image input, and 67,108,864 charged pixel units across one request. Oversized source assets, derived canvases, scale factors, comparison planes, or variant matrices are refused with `RENDER_*_BLOCKED`; these ceilings are not configurable and are checked before pixel allocation where dimensions are known. Workspace SVG raster inputs are rejected before decoding because nested SVG resources are not governed by the outer pixel limit; use PNG source frames/assets instead. Deterministic SVG remains a generated review-artifact format.
+- Declarative GUI helpers stop at 128 levels and 10,000 nodes. GUI scenarios admit at most 256 list keys, 10,000 aggregate rows, 100,000 aggregate keys, and 1,000,000 string characters; expanded scenes stop at 128 levels, 10,000 elements, or 100,000 construction-work units. One render may perform at most 512 distinct raster/native-image operations. Rendered text is limited to 16,384 characters per element, 262,144 aggregate characters per scene, and 32,768 text-layout operations. BMFont text sources are limited to 2,097,152 bytes, 50,000 records, 32 fields per record, 256 pages, 32,768 characters, and 32,768 kerning pairs; binary font inputs stop at 8,388,608 bytes, and missing-glyph evidence retains at most 64 samples. Focus and GUI graph validation uses fixed node, edge, depth, and work ceilings: the GUI source graph stops at 50,000 GUI elements, 500,000 total nodes, or 1,000,000 edges; validation stops at 2,000,000 pair comparisons or ancestor hops; focus layout stops at 500,000 work units; and focus lint stops at 2,000,000 transitive/route-analysis units. Focus lint/layout, GUI source-graph, and GUI validation diagnostics retain at most 2,000 entries, including an explicit truncation blocker when findings overflow.
+- Declarative GUI helper documents admit at most 1,024 one-root templates and 64 state variants per node; both source and expanded trees remain subject to the 128-level and 10,000-node ceilings. Grid columns stop at 10,000, expanded identifiers at 1,024 UTF-8 bytes, conservative source-construction work at 16 MiB, and final generated source at 8 MiB. Templates have root overrides but no parameters, slots, or appended children. Scroll-list helpers emit deterministic grid and entry-container handoff names but do not create `dynamic_lists` scripted-GUI bindings or verify an external scrollbar definition's axis. Meter helpers choose one static icon frame from a validated range and do not provide runtime progress behavior. Advanced, hardcoded, legacy, or non-allowlisted scalar GUI fields require the counted raw escape hatch.
+- Focus design diagnostics such as weak branches, payoff quality, avoidable crossings, or generic rewards are deterministic heuristics and do not rewrite gameplay.
+- Plan/script drift requires an explicit authoritative-source choice.
+- Map geometry requires an exact polygon with explicit `fillRule: "even-odd"`, a canonical hash-bound raster-mask manifest, or absolute pixel selection. Polygon vertices are integer raster-boundary coordinates: `0` through raster width/height are valid, greater coordinates are refused before work allocation, and polygons are never clipped. Inclusion is determined at pixel centers. Descriptive geography alone cannot apply.
+- Province hole detection is a deterministic four-connected digital-topology review. It warns on enclosed components but does not declare every enclave invalid; provinces touching the horizontally wrapping map seam are excluded from the planar hole calculation.
+- Map text tables are limited to 16,777,216 bytes and 500,000 records so the bounded parser admits the current vanilla unit-position table. Province rasters are limited to the documented 13,238,272-pixel engine area, exact raster masks to 20,000,000 cells, and polygon rasterization to 50,000,000 cell-point comparisons. Every exact selection/recolor operation is additionally limited to 1,000,000 pixels, including explicit pixels, selected mask cells, rasterized polygons, normal-adjacency transfers, whole-province color updates, and merges. Known counts are refused before dangerous decoding/scanning/materialization with `MAP_SELECTED_PIXEL_BUDGET_BLOCKED`. Selected pixels use four-byte numeric offsets, so the primary operation-owned offset buffer remains below 4 MiB (4,000,000 bytes); coordinate-string keys and per-pixel coordinate/color object arrays are not materialized. Map diagnostics are capped at 2,000; overflow retains 1,999 findings and replaces the last slot with a blocking `MAP_DIAGNOSTICS_TRUNCATED`. Undefined bitmap colors retain at most 256 individual samples and add a blocker when more distinct colors exist.
+- State/province redistribution and new-state English localisation policy must be explicit. State move/split/merge policies name port, supply-node, railway, and position behavior; province splits name retention for every connected reference family. Missing or ambiguous policy blocks the plan; localisation writes require a safe BOM source or an explicit in-root creation target.
+- Bitmap-derived normal adjacency changes require exact source-to-target pixel transfers whose requested topological result can be verified. The service does not infer a corridor or boundary; special adjacency CSV rows remain a separate operation family.
+- Province land/sea/lake migration only supports the documented complete dependency policy. Agent Nudger will not infer a state, reconnect a railway after removing a province, move a port, or repair incompatible positions/adjacencies.
+- State `capital` is derived from exact victory points for inspection; Agent Nudger does not write a generic state `capital` assignment.
+- Map ID allocation obeys scanned format/contiguity evidence from every root's own `default.map`-selected definition database; it refuses an allocation when the current source family cannot safely represent a gap or append. A present selector with any syntax or parser-limit diagnostic blocks the whole map model, including when it belongs to a lower game/dependency root, because falling back could hide an ID or color collision.
+- Province merge/removal supports arbitrary compatible source IDs and compacts every connected province reference; it refuses renumbering only when the active definition table is already gapped or ambiguous by ID/color, or when source and target type/state/region membership is incompatible.
+- Recoverable logical multi-file atomicity cannot prevent an unrelated process from briefly reading a replacement sequence. Success follows the server's post-write validation and final hash check, and persisted before-bytes support rollback. This is not a race-proof filesystem transaction: hostile concurrent symlink, junction, mount, directory, or file replacement by another operating-system principal is outside the application security boundary.
+- Artifact retention defaults to 536,870,912 bytes, 5,000 manifests, and 134,217,728 bytes per content object; each provenance manifest is separately capped at 1 MiB before parsing. Broad project, focus, GUI, and map manifests retain a bounded source-hash sample plus a digest commitment to the complete inventory, while exact structured artifact content retains the complete hashes. Opt-in oversized logical evidence is preserved as bounded binary chunks plus a one-read JSON index, not as a larger content object: every chunk/index manifest counts against the same quotas, an index above 1 MiB is refused, and one logical preparation batch has a fixed 536,870,912-byte in-memory ceiling (or the lower configured aggregate ceiling). The whole logical batch is admitted before copying or hashing; preflight and hashing yield to cancellation. Transaction journals default to 536,870,912 bytes and 128 entries, with a fixed 16 MiB ceiling per authenticated manifest; only expired authenticated planned/rolled-back journals, authenticated safe cache-without-head remnants, head-without-cache remnants, or old manifest-less directories are pruned, while other terminal/interrupted or unauthenticated states remain fail-closed and count against quota. See [artifacts](artifacts.md) and [transactions](transactions.md).
+- Installed-game and external-workspace font files are read locally and are never published as raw MCP resources or redistributed by this package. Their glyph outlines or bounded BMFont atlas crops may appear inside an authorized generated review artifact. Portable fixtures and tool-owned artifact labels use the pinned Roboto package under OFL-1.1; unavailable workspace glyph data is visibly classified as an approximation rather than delegated to a host font.
+- Local external integration depends on environment-provided paths and is not a substitute for portable CI.
+- The server never launches, automates, controls, or captures Hearts of Iron IV. Offline previews are not game screenshots and do not prove in-engine rendering or gameplay behavior.