hoi4-agent-tools 0.2.0 → 1.0.0

package/docs/configuration.md

@@ -1,305 +0,0 @@
-# Configuration and workspaces
-
-Pass a config with `--config PATH` or `HOI4_AGENT_CONFIG`. Without either override, the server uses
-`~/.config/hoi4-agent-tools/config.json` on every platform (for example,
-`C:\\Users\\name\\.config\\hoi4-agent-tools\\config.json` on Windows). A different durable absolute
-path is equally valid when the client registration sets `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.
-
-Setup stays read-only unless a write flag is explicit. The recommended write configuration is generated with:
-
-```bash
-hoi4-agent-tools-setup --init-config /absolute/path/config.json --workspace /absolute/path/mod --autonomous-writes --server-state /separate/operator/state
-```
-
-That writes `"writePolicy": "autonomous"` and `"writeEnabled": true` for the supplied mod. Use `--reviewed-writes` only for the legacy separate review/apply tool sequence; `--enable-writes` remains a compatibility alias for reviewed mode. Autonomous and reviewed flags are mutually exclusive, and both require `--server-state`.
-
-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": "autonomous",
-  "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": true
-    }
-  ]
-}
-```
-
-## 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"`, recommended `"autonomous"`, or compatibility `"transactions"`.                                                                                                                     |
-| `serverStateRoot`            |                 omitted | Required for either write policy; 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 not `"read-only"`. 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                        | Display 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 `"autonomous"` or `"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`. In this mode the server exposes analysis and evidence tools but no source-mutation path.
-
-`autonomous` is the recommended write policy. With `writeEnabled: true` on a mod workspace, it exposes `hoi4.focus_rewrite`, `hoi4.gui_rewrite`, and `hoi4.map_rewrite`. Each tool plans, validates, journals, applies, rebuilds the index, and post-validates inside one call. If application or post-validation fails, exact original bytes are restored automatically. The transaction status/diff/apply/rollback tools are not registered in autonomous mode.
-
-`transactions` is an optional compatibility policy for clients that still need a distinct reviewed plan and apply boundary. It exposes the `*_plan_changes`/`map_plan` tools plus `hoi4.transaction_status`, `hoi4.transaction_diff`, `hoi4.transaction_apply`, and `hoi4.transaction_rollback`. It uses the same journal, hash checks, post-validation, and automatic failure recovery as autonomous mode.
-
-Both write policies require `serverStateRoot` and `writeEnabled: true` on the target mod. A dependency or game registration remains read-only even if misconfigured. Changing the global policy changes the MCP tool surface; restart the server and reinitialize the MCP session after changing it.
-
-The autonomous rewrite tools advertise `destructiveHint: true`. MCP does not require per-call prompts from that annotation, and server configuration cannot override a client's host approval or filesystem policy. A client may still prompt for or refuse a rewrite.
-
-`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.
-
-Write modes do 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

@@ -1,197 +0,0 @@
-# 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 focus `cost` values support finite numbers and safe file-scoped constants such as
-`@focus_cost_standard`. Targeted layout updates preserve the exact existing cost lexeme, including
-numeric formatting and comments. A cost token outside the typed model is retained unchanged when
-the plan does not explicitly replace it; the compiler refuses to generate an arbitrary scalar.
-
-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; a uniform `reviewScale` from `0.25` through `1.0` keeps unusually wide or deep trees within bounded raster limits without changing logical geometry or source coordinates. Continuous mode accepts palette columns and renders the actual continuous-focus source model.
-6. In autonomous mode, `hoi4.focus_rewrite` accepts either a national plan (the default when `mode` is omitted) or `mode: "continuous"` with a continuous-palette plan. It makes source-preserving range edits where possible, produces before/proposed/bitmap-diff evidence, journals exact recovery bytes, applies, rebuilds the index, and post-validates in one call. National plans may set `horizontalSpacing`, `verticalSpacing`, `padding`, and a uniform `reviewScale` for both review renders; those pixel-space settings do not alter focus coordinates or compiled HOI4 source. National plans also maintain the adjacent planning sidecar. To create a first tree or palette in a new mod source file, set `createIfMissing: true`; without it, missing sources and IDs refuse. Creation never appends a different target to an existing source file, never copies a read-only game/dependency file into a shadowing mod path, and restores newly created source and sidecar files automatically if the rewrite fails.
-7. Check `execution`, drift, diagnostics, validation, changed files, source maps, and diff artifacts. `execution: "planned"` means validation blocked the proposal without changing source; `execution: "applied"` means post-write validation succeeded.
-
-With the optional `"transactions"` compatibility policy, use `hoi4.focus_plan_changes`, page through `hoi4.transaction_diff`, and call `hoi4.transaction_apply` with the exact plan hash instead. The same core validation and recovery engine is used.
-
-## Repairing an existing large tree
-
-Imported authored coordinates are fixed by design. A plain `hoi4.focus_layout` call therefore
-audits an existing layout without silently rearranging it. To opt a badly structured tree into a
-full cleanup, the coding agent must make the movement policy explicit:
-
-1. Scan, lint, and render the baseline, then read the complete imported plan resource. Use the same
-   national `reviewScale` for baseline, transaction, and final renders when the default canvas is too
-   large.
-2. Preserve every prerequisite group, exclusion, route lock, reward, raw passthrough entry, source
-   location, and provenance value.
-3. Model the intended route architecture with `branchGroups`, `laneGroups`, `branchId`, and
-   `laneId`. Give lanes stable order and, where appropriate, horizontal bounds.
-4. Keep only deliberate trunk or convergence anchors fixed/pinned. Change every movable focus to
-   `{ "mode": "auto", "pinned": false }`; `preferredX` and `preferredY` may retain the authored
-   route intent without making those coordinates mandatory.
-5. Submit the complete plan to `hoi4.focus_rewrite`. The call performs layout, compilation,
-   lint, source-preserving range edits, deterministic before/proposed rendering, bitmap diffing,
-   journaling, application, index rebuild, and post-write validation.
-   For an unusually wide or deep tree, set a uniform national `reviewScale` between `0.25` and
-   `1.0`; `0.4` is appropriate for a very large comparison. It scales nodes, text, connectors, and
-   the viewport together, avoiding artificial overlap. The same scale governs both sides of the
-   comparison and affects only artifact pixels, never source-grid coordinates. Explicit spacing and
-   padding remain available when the artifact's logical presentation itself needs adjustment.
-6. Inspect the returned validation and evidence links. Rescan, lint, and render when additional
-   final evidence is useful. A blocked proposal changes nothing; failure after replacement begins
-   restores every affected file automatically.
-
-This workflow is suitable for hundreds of focuses. The solver keeps parents above children,
-rejects visible overlap and duplicate coordinates, separates bounded lanes, validates relative
-chains, and minimizes avoidable connector crossings. It never changes gameplay relationships to
-make a picture look cleaner.
-
-## Authoring a large tree
-
-For a new tree, translate route requirements into the strict public schema at
-`hoi4-agent://schema/focus-plan`. A robust plan uses a centered entry/trunk, bounded political or
-strategic lanes, separately modelled shared-support lanes, exact AND/OR prerequisite groups,
-reciprocal route exclusions, explicit convergence and capstones, automatic positions, and complete
-localisation/icon/AI/link metadata. Unsupported Clausewitz blocks belong in `rawPassthrough` so they
-round-trip instead of being approximated.
-
-This minimal national plan is schema-valid. It intentionally omits an icon and reward; a production
-tree should add complete presentation and gameplay data before rewriting:
-
-```json
-{
-  "schemaVersion": 1,
-  "id": "example_tree",
-  "default": false,
-  "branchGroups": [
-    {
-      "id": "constitutional",
-      "label": "Constitutional route",
-      "family": "politics",
-      "focusIds": ["example_entry"],
-      "laneId": "centre",
-      "major": true,
-      "hidden": false,
-      "crisis": false,
-      "conditional": false,
-      "aiStrategyIds": []
-    }
-  ],
-  "laneGroups": [
-    { "id": "left", "label": "Left route", "order": 0, "minimumX": -12, "maximumX": -5 },
-    { "id": "centre", "label": "Constitutional trunk", "order": 1, "minimumX": -2, "maximumX": 2 },
-    { "id": "right", "label": "Right route", "order": 2, "minimumX": 5, "maximumX": 12 }
-  ],
-  "entryFocusIds": ["example_entry"],
-  "focuses": [
-    {
-      "id": "example_entry",
-      "label": "Example entry",
-      "branchId": "constitutional",
-      "laneId": "centre",
-      "prerequisites": { "operator": "and", "groups": [] },
-      "mutuallyExclusive": [],
-      "routeLocks": [],
-      "position": { "mode": "auto", "pinned": false, "preferredX": 0, "preferredY": 0 },
-      "visibility": "normal",
-      "convergence": false,
-      "sharedSupport": false,
-      "icons": [],
-      "localisation": {
-        "titleKey": "example_entry",
-        "descriptionKey": "example_entry_desc",
-        "workingLabel": "Example entry"
-      },
-      "ai": { "majorRoute": true, "strategyIds": [] },
-      "filters": ["FOCUS_FILTER_POLITICAL"],
-      "links": [],
-      "rawPassthrough": []
-    }
-  ],
-  "sharedFocusIds": [],
-  "continuousFocusPaletteIds": [],
-  "continuousFocusIds": [],
-  "rawPassthrough": [],
-  "provenance": {
-    "sourcePath": "plan:example_tree",
-    "sourceHash": "0000000000000000000000000000000000000000000000000000000000000000",
-    "importedPlanHash": "0000000000000000000000000000000000000000000000000000000000000000"
-  }
-}
-```
-
-Within each focus, one `prerequisites.groups` entry represents one Clausewitz `prerequisite` block
-whose listed focuses are OR alternatives. Multiple group entries are AND requirements. For a new
-target, use `sourcePath: "plan:<tree-id>"` and 64 zeroes for both initial hashes, then call
-`hoi4.focus_rewrite` with `createIfMissing: true`. Use that convention only for a missing
-target. Existing sources normally use imported, hash-bound provenance; resolving intentional
-plan/source drift additionally requires explicit `authority: "plan"`. The server refuses to append
-a different tree to an occupied source file and still requires complete pre-write and post-write validation.
-
-## 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, automatic nodes inside configured lane bounds, pinned nodes fixed, and relative-position chains valid. Automatic preferred coordinates are clamped to their lane; a full lane raises `FOCUS_LAYOUT_LANE_CAPACITY_BLOCKED`. Fixed, relative, or prior-stable coordinates outside their declared lane are preserved as evidence but produce a blocking `FOCUS_LAYOUT_LANE_BOUNDS_VIOLATION`. 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`. Rewrite journals retain the corresponding proposed source map and all review artifacts after success or automatic restoration.
-
-## 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.
-
-A national focus rewrite also stores `<tree>.focus.proposed-validation.json`. It contains every
-diagnostic and validation check from re-importing, laying out, and linting the compiled proposal.
-When that complete set is larger than the fixed transaction-manifest allowance, the manifest keeps
-a blocker-first bounded summary and an explicit resource diagnostic; it never drops findings from
-the validation decision. The rewrite boundary uses the same pattern for oversized post-write
-diagnostics.